From 947a06846efea4740f272f3dde27880be021d1bb Mon Sep 17 00:00:00 2001
From: QiuSW <105186638@qq.com>
Date: Sun, 16 Aug 2026 19:51:20 +0800
Subject: [PATCH] docs: add DevHarness upgrade baseline guidance (#16)

---
 dev_scripts/check_harness.py         |  4 +++
 docs/00-project-profile.md           | 17 ++++++++++--
 docs/08-existing-project-adoption.md | 39 ++++++++++++++++++++++++++--
 tests/test_harness_docs.py           | 12 +++++++++
 4 files changed, 68 insertions(+), 4 deletions(-)

diff --git a/dev_scripts/check_harness.py b/dev_scripts/check_harness.py
index 6b237a7..c7e0793 100644
--- a/dev_scripts/check_harness.py
+++ b/dev_scripts/check_harness.py
@@ -42,6 +42,7 @@ CORE_DOCUMENT_REQUIREMENTS = {
     ),
     "docs/00-project-profile.md": (
         "## 基本信息",
+        "## DevHarness 来源与基线",
         "## 子项目与交付单元",
         "## 技术栈与运行环境",
         "## 阅读入口",
@@ -105,6 +106,9 @@ CORE_DOCUMENT_REQUIREMENTS = {
         "### 可以考虑拆仓",
         "### 保持单仓库时的最小规则",
         "## 增量接入顺序",
+        "## 后续升级",
+        "### 升级步骤",
+        "### 可复制升级指令",
         "## 冲突处理和停止条件",
         "## 可复制 Agent 指令",
         "### 只分析",
diff --git a/docs/00-project-profile.md b/docs/00-project-profile.md
index 10db76b..dd946d9 100644
--- a/docs/00-project-profile.md
+++ b/docs/00-project-profile.md
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Project-Profile
 wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Project-Profile.-
-wiki_revision: 62d1251f807f7d1b60017790c35d46186ffb9617
-synchronized_at: 2026-08-16T11:18:50Z
+wiki_revision: 16456d6ed083197759d553b1033e3e5c8a6b8932
+synchronized_at: 2026-08-16T11:49:52Z
 <!-- gitea-wiki-mirror:end -->
 
 # 项目档案
@@ -23,6 +23,19 @@ synchronized_at: 2026-08-16T11:18:50Z
 | 主要维护者 | `ila` |
 | 文档适用范围 | 默认分支当前版本；具体镜像 revision 见每个本地文件头 |
 
+## DevHarness 来源与基线
+
+每个采用 DevHarness 的业务项目都必须填写本节。它记录的是所采用的 DevHarness 上游版本，不是业务项目自己的提交。不得使用“最新版本”“当前 main”等动态描述代替完整提交哈希。
+
+| 项目 | 内容 |
+|---|---|
+| DevHarness 来源仓库 | `http://ilaer.eicp.net:8418/opc/dev_harness` |
+| 当前基线提交 | 本仓库是 DevHarness 上游源模板，不适用；复制到业务项目后必须替换为实际采用的完整提交哈希 |
+| 最后接入或升级日期 | 2026-08-16 |
+| 项目适配说明 | 本仓库维护源模板；业务项目填写保留、改写或未采用的 Harness 规则与工具 |
+
+首次接入和后续升级都必须在目标项目工单中记录旧基线、新基线和差异分类。升级验收通过后，目标项目应把“当前基线提交”和日期更新为已采用的上游提交；未完成或已回退的升级不得更新基线。
+
 ## 子项目与交付单元
 
 “子项目”是仓库中具有明确职责和规则边界的应用或模块；“交付单元”是能够独立构建、测试、版本化或发布的程序、服务、库或文档包。一个子项目可以对应一个交付单元，也可以包含多个交付单元。
diff --git a/docs/08-existing-project-adoption.md b/docs/08-existing-project-adoption.md
index e362311..1e6e4f1 100644
--- a/docs/08-existing-project-adoption.md
+++ b/docs/08-existing-project-adoption.md
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Existing-Project-Adoption-Guide
 wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Existing-Project-Adoption-Guide.-
-wiki_revision: 5c187a1d1cc215c632fcc26b2a4c6df735af5d92
-synchronized_at: 2026-08-10T11:03:05Z
+wiki_revision: 2ef3d7cd26874f652e9bfab2a5c2f6c8273ab7ac
+synchronized_at: 2026-08-16T11:50:18Z
 <!-- gitea-wiki-mirror:end -->
 
 # 已有项目接入 DevHarness 指南
@@ -133,6 +133,41 @@ Agent 在提出方案前只读检查：
 
 提交只包含当前接入工单相关文件。记录测试、未验证部分、Wiki revision 和提交哈希，创建任务归档并保持工单“待验收”，等待用户明确验收后再关闭。
 
+## 后续升级
+
+已接入的项目必须以 Project-Profile 中记录的 DevHarness 来源和当前基线为起点升级，不得重新复制整个模板，也不得用“最新版本”代替可复现的目标提交。
+
+### 升级步骤
+
+1. 读取目标项目的 Project-Profile，确认 DevHarness 来源仓库、当前基线完整提交、最后升级日期和项目适配说明；字段缺失时先补齐可验证事实，无法确认则停止。
+2. 选择一个明确、已审阅的 DevHarness 目标提交，记录旧基线和新基线。先比较两个上游提交之间的变化，再判断这些变化如何作用于目标项目。
+3. 只读比较与 Harness 有关的 `AGENTS.md`、`CLAUDE.md`、工单模板、`dev_scripts/`、Harness 测试和核心 Wiki 结构，把差异分为“直接采用、按项目改写、冲突待确认、不采用”。不得把 DevHarness 的项目事实、工单或任务归档带入目标项目。
+4. 在目标项目建立单元任务工单，写明升级范围、差异分类、项目专用规则、风险、回退、验证和文档影响。会改变产品行为的内容必须拆成独立任务。
+5. 按工单最小合并，保留目标项目更具体的业务、安全、权限和目录规则，以及 Git 历史和无关工作区修改。无法判断哪一方规则有效时停止并等待负责人确认。
+6. 长期文档先更新目标项目 Wiki，读取确认后再同步目标项目的核心 `docs/` 镜像；不得用 DevHarness 的本地镜像覆盖目标项目文档。
+7. 执行目标项目规定的必要检查和受影响测试，提交并回写证据。工单保持“待验收”。
+8. 用户验收通过后，确认目标项目 Project-Profile 已记录新 DevHarness 基线完整提交和升级日期，再关闭工单。升级失败或回退时保留旧基线。
+
+### 升级停止条件
+
+除本页已有的冲突停止条件外，来源仓库与记录不一致、旧基线不存在、目标提交未明确、差异跨越过大而无法可靠分类，或升级需要覆盖项目专用安全规则时，都必须停止并请求确认。可以把升级拆成多个单元任务，但每个任务都要声明最终采用的同一目标基线。
+
+### 可复制升级指令
+
+```text
+请把当前项目从 Project-Profile 记录的 DevHarness 基线升级到
+<DevHarness 目标完整提交哈希>。
+
+先只读比较来源仓库中“旧基线..目标基线”的 Harness 变化和当前项目
+适配，列出直接采用、按项目改写、冲突待确认和不采用的内容，以及
+风险、回退、验证和文档影响。不要覆盖项目专用规则、业务文档、Git
+历史或无关改动，不复制 DevHarness 工单和任务归档。方案确认后在
+当前项目建单并实施；长期文档先改当前项目 Wiki，再同步本地镜像。
+工单保持待验收，验收通过后确认 Project-Profile 已记录新基线。
+```
+
+路径和目标完整提交哈希必须替换为真实值；目标提交未明确时只分析，不实施。
+
 ## 冲突处理和停止条件
 
 出现以下情况时停止实施并请求负责人确认：
diff --git a/tests/test_harness_docs.py b/tests/test_harness_docs.py
index 79c3864..1eeae90 100644
--- a/tests/test_harness_docs.py
+++ b/tests/test_harness_docs.py
@@ -58,6 +58,18 @@ class CoreDocumentTests(unittest.TestCase):
         self.assertIn(path, CORE_DOCUMENT_REQUIREMENTS)
         self.assertIn("## 可复制 Agent 指令", CORE_DOCUMENT_REQUIREMENTS[path])
 
+    def test_existing_project_adoption_requires_upgrade_process(self) -> None:
+        required = CORE_DOCUMENT_REQUIREMENTS[
+            "docs/08-existing-project-adoption.md"
+        ]
+        self.assertIn("## 后续升级", required)
+        self.assertIn("### 升级步骤", required)
+        self.assertIn("### 可复制升级指令", required)
+
+    def test_project_profile_requires_dev_harness_baseline(self) -> None:
+        required = CORE_DOCUMENT_REQUIREMENTS["docs/00-project-profile.md"]
+        self.assertIn("## DevHarness 来源与基线", required)
+
     def test_new_project_setup_requires_baseline_selection(self) -> None:
         required = CORE_DOCUMENT_REQUIREMENTS[
             "docs/07-new-project-documentation-setup.md"