coding-agent-harness 1.0.0

package/references/lessons-governance.md

@@ -0,0 +1,157 @@
+# 经验沉淀治理（Lessons Governance）
+
+## 核心思路
+
+Agent 在 Walkthrough 收口时自动识别可沉淀的经验，先将详细内容落到
+`docs/01-GOVERNANCE/lessons/` 目录，再写入 Lessons SSoT。人审批后决定是否合入正式 reference。
+
+**硬规则：Lessons SSoT 表行不能单独存在。** 每一条 pending lesson 必须有一篇
+`docs/01-GOVERNANCE/lessons/L-YYYY-MM-DD-NNN-<slug>.md` 详情文档，表里的
+`Detail Doc` 列必须指向这篇文档。如果只是填表而没有详情文档，这次 closeout
+不算完成。
+
+这是 harness 的第三条 SSoT 轨道：
+
+| SSoT | 管什么 | 位置 |
+|------|--------|------|
+| Feature SSoT | 实施排期 | `docs/09-PLANNING/` |
+| Regression SSoT | 回归控制 | `docs/05-TEST-QA/` |
+| **Lessons SSoT** | **经验沉淀** | **`docs/01-GOVERNANCE/`** |
+
+Lessons SSoT 管“规范是否应该演进”。本轮任务是否做过 Lessons 检查、是否创建了
+Lessons 条目，由 `docs/Harness-Ledger.md` 记录，避免把 SOP 合规状态塞进
+Lessons SSoT。
+
+## 目录结构
+
+```
+docs/01-GOVERNANCE/
+├── Lessons-SSoT.md              ← 沉淀建议表（SSoT）
+├── lessons/                     ← 具体沉淀内容存放
+│   ├── L-2026-05-07-001-xxx.md  ← 单条沉淀建议的详细内容
+│   └── ...
+└── _archive/                    ← 已处理的历史条目归档
+    └── Lessons-SSoT-archive-YYYY-QN.md
+```
+
+## 触发时机
+
+在 Walkthrough 收口流程中，写完 Walkthrough 并更新 Feature/Regression SSoT 之后，Agent 执行经验沉淀检查：
+
+1. 这次开发中有没有发现现有 reference 不够用或有误的地方？
+2. 有没有值得固化为规范的新模式/新做法？
+3. 有没有踩坑经验值得记录，避免下次重复？
+4. 有没有架构层面的洞察，值得更新架构文档？
+
+如果任何一条答案是"有"，必须执行“双写”：
+
+1. 选择 `templates/lessons/` 下的对应模板，先创建详情文档。
+2. 详情文档必须写清背景、现状问题、建议改动、影响范围和冲突声明。
+3. 再在 Lessons SSoT 追加表行，`Detail Doc` 指向这篇详情文档。
+4. 在 Closeout SSoT / Harness Ledger 中记录 `checked-created`，并引用 lesson ID。
+
+如果四个问题的答案全是"没有"，也不能静默跳过。必须在 Closeout SSoT 和
+Harness Ledger 中记录 `checked-none: <一句话原因>`。
+
+## Closeout 判定
+
+收口时只允许以下两种合格状态：
+
+- `checked-created: L-YYYY-MM-DD-NNN`：发现可沉淀经验，已创建详情文档并更新 Lessons SSoT。
+- `checked-none: <reason>`：已完整检查，确认本轮没有可复用的规范/流程/架构改进。
+
+以下状态不合格：
+
+- 只写 Lessons SSoT 表行，没有详情文档。
+- 只写详情文档，没有 Lessons SSoT 表行。
+- 在 walkthrough 或 progress 中说“无 lessons”，但 Closeout SSoT / Harness Ledger 没有记录。
+- 用 `n/a` 代替检查结果，除非任务是纯只读分析且没有 closed ledger row。
+
+## 沉淀类型
+
+| Type | 说明 |
+|------|------|
+| `ref-change` | 修改现有 reference 文档 |
+| `new-doc` | 新增文档/规范 |
+| `arch-change` | 架构层面的改动建议 |
+| `process-change` | 流程/工作方式的改动建议 |
+
+## 冲突处理规则
+
+### 规则 1：写之前必须读 SSoT
+
+Agent 在产出任何沉淀建议之前，**必须完整读一遍 Lessons SSoT**，了解：
+- 当前有哪些 pending 条目
+- 是否有人已经对同一个 target 提出了改动
+- 当前各条目的状态
+
+### 规则 2：副本始终基于正式版本
+
+无论 SSoT 上有多少个 pending 的改动指向同一个 target，新的副本**始终基于当前正式 reference 的最新版本**，不基于任何未合入的 pending 副本。
+
+**原因**：人可能选择不采纳之前的 pending 改动。如果基于别人未合入的副本去改，一旦那个被 reject，改动就建立在错误基础上。
+
+### 规则 3：以解决冲突的方式编写
+
+如果发现有 pending 条目指向同一 target，Agent 必须：
+1. 读取那个 pending 条目的内容（了解对方想改什么）
+2. 在自己的副本中，以"解决冲突"的方式编写——即：假设对方的改动最终也会被采纳，自己的改动应该与之兼容
+3. 在"冲突声明"中明确说明：我看到了 L-XXX 的改动，我的副本已考虑兼容
+4. 但**不是在对方副本之上修改**，而是独立基于正式版本编写
+
+### 规则 4：人做最终聚合
+
+当多个 pending 条目指向同一 target 时，人在审批时可以：
+- 逐个 approve，按顺序合入
+- 一次性看所有 pending 改动，做聚合后合入
+- reject 部分，approve 部分
+- 要求 Agent 基于审批结果重新生成一个合并版本
+
+### 规则 5：SSoT 表标记冲突
+
+当新条目与已有 pending 条目指向同一 target 时，两个条目的 Conflict 列都要标记对方的 ID。人一眼就能看到"这两个要一起审"。
+
+## 状态流转
+
+```
+🟡 pending → 🟢 approved → ✅ merged
+                         ↘ (人决定不合入) → ❌ rejected
+          → 🔀 superseded (被后续条目取代)
+```
+
+## 归档机制
+
+### 触发条件
+- Active Lessons 表超过 **20 条**时，将所有 `✅ merged` 和 `❌ rejected` 的条目移入归档
+- 人也可以手动触发归档
+
+### 归档格式
+```
+docs/01-GOVERNANCE/_archive/Lessons-SSoT-archive-YYYY-QN.md
+```
+
+### 归档后
+- Active 表只保留 `🟡 pending` / `🟢 approved` / `🔀 superseded` 的条目
+- 归档文件保留完整历史，可追溯
+
+## 人的审批工作流
+
+1. 打开 `Lessons-SSoT.md`，看 Active 表里有没有 🟡 pending 的条目
+2. 看 Summary 列，大部分情况一句话就能判断
+3. 需要细看就点进 Detail Doc 路径，看完整副本和改动理由
+4. 有冲突的条目一起审（看 Conflict 列）
+5. 批准后改状态为 🟢 approved
+6. Agent 下次看到 approved 状态就执行合入，完成后改为 ✅ merged
+
+## 合入执行
+
+当 Agent 发现 Lessons SSoT 中有 `🟢 approved` 状态的条目时：
+- `ref-change`：用 lessons/ 中的副本替换正式 reference
+- `new-doc`：将 lessons/ 中的内容移动到建议路径
+- `arch-change`：按建议更新架构文档
+- `process-change`：按建议更新流程文档
+
+合入完成后，状态改为 `✅ merged`。
+
+合入任务收口时，还必须在 `docs/Harness-Ledger.md` 的当前任务 row 中记录
+`Lessons=updated` 或 `Lessons=checked-created`。

package/references/long-running-task-standard.md

@@ -0,0 +1,209 @@
+# Long-Running Task Standard
+
+## 核心思路
+
+长程任务不是“让 agent 多跑一会儿”，而是把任务先设计成可连续执行、可审查、可停止的合同。
+
+当任务需要持续数小时、多轮 hardening、多 agent 分工或子代理 review 时，必须先把合同写清楚，再开放连续执行权限。
+
+## 适用场景
+
+以下任务应使用本标准：
+
+- 预计持续多轮迭代的复杂修复、重构、交付收口
+- 需要连续推进 2 小时以上的任务
+- 需要多轮测试、浏览器巡检、真实环境 smoke 或人工代理操作的任务
+- 需要 reviewer agent、subagent、外部审查者交叉检查的任务
+- 用户希望“不要每轮问我，直到满足停止条件再汇报”的任务
+
+以下任务通常不需要：
+
+- 单文件小修
+- 一次性命令执行
+- 纯只读分析
+- 没有客观验收口径的轻量 brainstorming
+
+## 四个前提
+
+长程任务能稳定推进，需要四件事同时成立：
+
+1. **开放执行权限**：agent 不需要每一轮都回来请求继续。
+2. **封闭验收口径**：什么算完成、什么不算完成，事先定义。
+3. **持续证据循环**：每一轮都能产生新的可验证证据。
+4. **明确停止条件**：agent 知道什么时候继续，什么时候停。
+
+缺任何一项，任务容易过早停下、跑偏、无限扩大 scope，或者在主观细节里打转。
+
+## 任务合同
+
+长程任务开始前，必须在 task plan 或独立 contract 文件中写清以下字段。
+
+### Goal
+
+只回答一个问题：本轮任务到底要收掉什么主问题？
+
+要求：
+
+- 只能有一个主目标
+- 不能混入多个并列主目标
+- 不能写成“整体优化一下”
+
+### Scope
+
+必须明确：
+
+- 允许修改哪些目录、模块、接口、文档或流程
+- 哪些能力面明确 out of scope
+- 哪些共享文件需要避免并行冲突
+
+### Primary Caller / Entry Surface
+
+必须判断这轮能力主要面向谁：
+
+- 本机 agent / CLI
+- 人类用户 / UI
+- 服务调用 / API
+- 自动化系统 / scheduler
+- 外部集成 / adapter
+
+判断调用者不是为了提前做所有入口，而是避免把主入口设计错。
+
+### Execution Permission
+
+写清 agent 是否可以连续推进：
+
+- 是否可以不用每轮确认
+- 是否允许自动进入下一轮 review/fix/test
+- 是否允许启动子代理或 reviewer
+- 哪些动作仍需人工批准
+
+### Review Loop
+
+定义每一轮的闭环，并写清 review report 的落点。常见组合：
+
+- implement -> test -> self-review -> fix
+- implement -> browser/manual smoke -> reviewer agent -> fix
+- split work -> independent reviewer -> integration pass -> regression
+
+如果使用子代理，必须写清：
+
+- reviewer 只审查还是可改代码
+- reviewer 负责哪些文件或问题域
+- 主 agent 如何吸收反馈
+- reviewer 是否必须写 `review.md`
+- reviewer 是否必须执行 Confidence Challenge：“你对这个方案、实现和策略有 100% 的信心吗？”
+- 几轮 review 后才允许停止
+
+如果子代理可改代码、测试、产品文档或 harness 文档，它必须按 worker 合同执行：
+
+- coordinator 先分配独立 worktree / branch、任务目录和 write scope
+- worker 只在自己的 worktree 内实现、验证并提交
+- handoff 必须包含 worktree path、branch、commit SHA、checks、residual risks
+- coordinator 负责 merge / conflict resolution / final gates
+
+只读 reviewer 和可写 worker 不能混用同一个口径。若原本是 reviewer，后来需要改代码，
+必须先升级为 worker 并补齐 worktree 合同。
+
+如果 review loop 使用 reviewer agent、subagent 或外部审查者，必须在任务目录写
+`review.md`，并按 `docs/11-REFERENCE/adversarial-review-standard.md` 记录 material findings、
+no-finding statement、evidence checked 和 residual risk。
+
+### Evidence Depth
+
+写清任务需要哪些证据。常见证据：
+
+- lint / typecheck / build
+- unit / integration / e2e tests
+- local smoke
+- browser or UI inspection
+- live environment smoke
+- logs / screenshots / traces
+- reviewer findings and no-finding confirmation
+- `review.md` 中的 material finding 状态与 residual routing
+- walkthrough / release notes / PR checks
+
+证据必须能被后来的人复查，不能只写“看起来可以”。
+
+### Stop Condition
+
+停止条件必须是可判断的完成门。
+
+推荐组合：
+
+- 关键路径通过
+- 目标 regression gate 通过
+- console / request / page / runtime errors 清零或有明确残项
+- reviewer 没有 material finding
+- `review.md` 已完成，且无 open P0/P1 finding
+- 自审没有明显不满意项
+- residual items 已记录，且不阻塞本轮目标
+
+### Deliverables
+
+明确最终交付物：
+
+- 代码改动
+- 测试或 regression gate
+- docs / task plan / progress / findings 回写
+- review report（如适用）
+- worker branch / commit SHA / integration evidence（如使用 worker subagent）
+- walkthrough
+- Harness Ledger
+- PR / commit / release note
+- residual risk summary
+
+## 标准执行形态
+
+推荐顺序：
+
+1. 讨论并收敛任务合同
+2. 建 planning 目录和 worktree
+3. 做一轮可验证增量
+4. 运行约定证据
+5. 自审或 reviewer 审查
+6. 根据发现继续修
+7. 重跑证据
+8. 直到 stop condition 达成
+9. 写 walkthrough、Harness Ledger 和 residual risk
+
+核心原则：
+
+> 开放执行，封闭验收；多轮证据，不靠感觉。
+
+## 暂停条件
+
+即使用户授权连续执行，出现以下情况也必须停下来汇报：
+
+- 主目标或 scope 变得不清楚
+- 需要高风险产品、架构、安全或数据决策
+- 当前任务与已有未提交改动直接冲突
+- stop condition 已经不适用
+- 外部环境、权限、配额、依赖阻塞，无法继续产生有效证据
+- reviewer 发现的问题会改变任务目标
+
+长程任务不是永远不问，而是在合同清楚时少问，在合同失效时及时停。
+
+## 反模式
+
+以下口径不适合作为长程任务合同：
+
+- “你先看看，能改多少改多少”
+- “整体优化一下”
+- “差不多就行”
+- “有问题再说”
+- “不用测了，先做”
+- “我也不知道什么时候算完成，你自己把握”
+
+这些写法共同缺少 Goal、Scope、Evidence 或 Stop Condition。
+
+## 项目落地规则
+
+一个项目安装 harness 后，应做到：
+
+- `AGENTS.md` 的 Task-Type Reading Matrix 指向 `docs/11-REFERENCE/long-running-task-standard.md`
+- `docs/09-PLANNING/TASKS/_task-template/` 包含 long-running task contract 模板
+- `docs/09-PLANNING/TASKS/_task-template/` 包含 `review.md` 模板
+- `docs/11-REFERENCE/adversarial-review-standard.md` 定义 reviewer 报告规范
+- `execution-workflow-standard.md` 在开始任务前要求判断是否属于长程任务
+- regression / testing 标准能提供可复查证据，而不是只依赖主观判断
+- `docs/Harness-Ledger.md` 记录长程任务是否完成必要的上下文回写

package/references/module-parallel-standard.md

@@ -0,0 +1,292 @@
+# 模块并行开发标准
+
+## 核心思路
+
+当项目有多个可独立演进的功能域时，用模块（Module）替代全局 Phase 作为工作单元。每个模块有自己的步骤序列、worktree、会话，互不干扰。Phase 降级为"发布事件"——从各模块已完成步骤中挑选打包。
+
+## 何时启用
+
+同时满足以下条件时启用模块并行：
+
+- Operating Model 为 `solo-orchestrator` 或 `team-feature-lead`
+- 项目有 2+ 个功能域可独立演进
+- 各功能域的源文件几乎不重叠
+- 开发者计划多会话 / 多 worktree 并行推进
+
+不满足时继续使用 Feature SSoT + 线性 Phase 模型。
+
+## 核心概念
+
+| 概念 | 定义 | 生命周期 |
+|------|------|----------|
+| 模块（Module） | 长期存在的功能域 | 从注册到归档 |
+| 步骤（Step） | 模块内一个可合并工作单元（≈ 一个 PR） | planned → in-progress → done |
+| 发布（Release） | 从各模块已完成步骤中挑选打包的事件 | git tag |
+
+## 模块注册表（Module Registry）
+
+安装位置：`docs/09-PLANNING/Module-Registry.md`
+
+使用模板：`templates/ssot/Module-Registry.md`
+
+职责：
+- 记录所有活跃模块的 key、PREFIX、scope、当前步骤、分支、状态
+- 是新会话冷启动时的第一个读取文件（在 AGENTS.md 之后）
+- 声明每个模块的 write scope，用于冲突检测
+
+### Status 定义
+
+- `planned` — 步骤已规划，尚未开始
+- `in-progress` — 有活跃会话在开发
+- `paused` — 暂停，无活跃会话
+- `completed` — 所有步骤完成，待归档
+
+## 模块计划（Module Plan）
+
+安装位置：`docs/09-PLANNING/MODULES/<key>/module_plan.md`
+
+使用模板：`templates/planning/module_plan.md`
+
+职责：
+- 记录该模块的步骤序列、当前进度、完成标准
+- 每个步骤对应一个 task_plan（在模块的 TASKS/ 子目录下）
+
+## 模块会话启动 Prompt（Module Session Prompt）
+
+安装位置由项目选择，推荐二选一：
+
+- 单文件 Prompt Pack：`docs/09-PLANNING/MODULES/Session-Prompt-Pack.md`
+- 每模块 Prompt：`docs/09-PLANNING/MODULES/<key>/session_prompt.md`
+
+使用模板：`templates/planning/module_session_prompt.md`
+
+职责：
+
+- 给用户提供可直接粘贴到新会话的模块启动文本
+- 明确模块目标、读取顺序、branch/worktree、write scope、共享/禁止修改范围、验证命令、收口动作和 stop conditions
+- 让多个模块会话能独立冷启动，而不是依赖上一轮聊天上下文
+
+硬规则：
+
+- 每个 Active Module 必须能在 Prompt Pack 或自己的 `session_prompt.md` 中找到对应启动 prompt。
+- Prompt 必须写清楚 allowed scope 和 forbidden/shared scope。
+- Prompt 必须写清楚至少一个项目级 check 和该模块的 targeted checks。
+- Prompt 必须包含 start gate：校验 registry 当前步骤、branch/worktree、dirty state、共享锁和过期 prompt。
+- Prompt 必须要求开始改代码前创建或更新模块 task_plan，并记录 scope、acceptance、verification、worktree 和 shared coordination。
+- Prompt 必须包含 closeout：review.md 或 skipped-with-reason、walkthrough Lessons Reflection、Closeout SSoT、Lessons Check、Regression SSoT / Harness Ledger 条件更新。
+- Prompt 中不得要求 agent 修改其他模块代码；需要跨模块文件时，必须先进入 `_shared` task 或指定单一 owner。
+
+## 模块目录结构
+
+```
+docs/09-PLANNING/MODULES/<key>/
+├── module_plan.md          ← 模块总览和步骤序列
+├── session_prompt.md       ← 可选：该模块专用启动 prompt
+└── TASKS/                  ← 该模块的所有 task
+    ├── <PREFIX>-NN-<name>/
+    │   ├── task_plan.md
+    │   ├── progress.md
+    │   ├── findings.md
+    │   └── review.md (如需要)
+    └── ...
+
+docs/10-WALKTHROUGH/
+├── <module-key>/
+│   ├── <PREFIX>-NN-walkthrough.md
+│   └── ...
+└── _shared/               ← 跨模块基础设施 task 的 walkthrough
+
+docs/09-PLANNING/MODULES/_shared/TASKS/
+└── YYYY-MM-DD-<name>/     ← 跨模块/基础设施 task
+    └── ...
+```
+
+## 步骤 ID 规则
+
+- 格式：`<PREFIX>-NN`（如 `RDR-01`、`GRF-02`、`MOT-01`）
+- PREFIX 在注册表中唯一分配，不可重复
+- 步骤 ID 只在模块内有序，跨模块无顺序关系
+- NN 从 01 开始递增，不跳号
+
+## 会话冷启动协议
+
+新会话的读取顺序：
+
+1. `AGENTS.md` — 获取项目总览和模块并行指引
+2. `docs/09-PLANNING/Module-Registry.md` — 了解全局模块状态
+3. `docs/09-PLANNING/MODULES/Session-Prompt-Pack.md` 或目标模块的 `session_prompt.md` — 获取会话启动合同
+4. 目标模块的 `docs/09-PLANNING/MODULES/<key>/module_plan.md` — 了解模块进度
+5. 当前步骤的 `task_plan.md` — 了解具体任务
+
+会话开始时，用户告知目标模块（如"做 Reader"），agent 据此定位。
+
+会话结束时必须更新：
+- module_plan.md 的步骤状态和"当前状态"段落
+- 模块 TASKS 下的 progress / findings / review / walkthrough 相关引用
+- 模块 TASKS 下的 Coordinator Handoff，列出需要 coordinator 同步到总表的 registry / ledger / closeout 项
+
+模块 worker 默认不得写全局总表：
+
+- `docs/09-PLANNING/Module-Registry.md`
+- `docs/Harness-Ledger.md`
+- `docs/10-WALKTHROUGH/Closeout-SSoT.md`
+- `docs/05-TEST-QA/Regression-SSoT.md`
+- `docs/05-TEST-QA/Cadence-Ledger.md`
+
+这些文件只有 coordinator pass 或显式 shared lock owner 能写。模块 worker 需要总表同步时，只在模块任务的
+`progress.md` / `task_plan.md` 中写 `Coordinator Handoff`，状态使用
+`pending-coordinator-pass`。这样模块分支不会互相抢同一张总表。
+
+### AGENTS.md 必须包含的段落
+
+```markdown
+## 模块并行开发
+
+本项目启用了模块并行开发。开始任何模块工作前：
+
+1. 读 docs/09-PLANNING/Module-Registry.md 了解全局状态
+2. 读 docs/09-PLANNING/MODULES/Session-Prompt-Pack.md 或目标模块的 session_prompt.md
+3. 读目标模块的 docs/09-PLANNING/MODULES/<key>/module_plan.md
+4. 在模块对应的 worktree 上工作
+5. 不跨模块修改文件（不修改 write scope 之外的代码）
+6. 如果作为 worker subagent 改代码/测试/文档，必须在 coordinator 分配的独立 worktree / branch 中工作，提交自己的 commit，并 handoff commit SHA / checks / residual risks
+7. 会话结束时更新 module_plan.md 和模块任务的 Coordinator Handoff；Module Registry / Harness Ledger 是 coordinator-owned shared state，只能在 coordinator pass 或显式 shared lock 中更新
+```
+
+如果主 agent 作为 coordinator 启动多个模块 worker，禁止让它们共享 coordinator 当前 checkout。
+每个 worker 必须有自己的模块 worktree 或任务 worktree；coordinator 只集成 worker commits。
+
+## 发布打包
+
+对 solo-orchestrator：
+
+- 发布 = git tag + merge 到 main 的一批模块步骤
+- 在 git tag message 中列出包含的步骤 ID
+- 示例：`git tag -a v0.3.0 -m "Release 3: RDR-01, RDR-02, GRF-01, MOT-01"`
+- 如需更正式的发布管理，可选创建 `docs/09-PLANNING/releases/` 目录
+
+## 共享文件冲突规则
+
+### Write Scope 声明
+
+每个模块必须在 Module Registry 中声明 write scope（可修改的目录/文件范围）。
+
+### 硬规则
+
+如果两个模块的 write scope 有交集，必须在开发前解决。解决方式三选一：
+
+1. **串行**：有交集的步骤不同时开发，一个完成后另一个再开始
+2. **指定 owner**：将共享文件的修改权归属一个模块，另一个模块不碰
+3. **提取**：将共享文件提取为独立的 `_shared` 模块或基础设施 task
+
+### 共享基础设施
+
+shell、data layer、design system 等共享基础设施的修改：
+- 不属于任何模块
+- 走独立的"基础设施 task"（见下文）
+- 修改期间，其他模块暂停对该区域的修改
+
+最小协调产物：
+
+- `_shared` task：`docs/09-PLANNING/MODULES/_shared/TASKS/<id>/task_plan.md`
+- 或模块 task_plan 中的 `Shared Coordination` 段落，必须写明 owner、touched files、allowed change、reviewer、merge order。
+
+Module Registry 本身也是 shared lock。活跃模块会话默认更新自己的 module_plan 和 TASKS；Registry 的 Current Step / Status 只在持锁或 coordinator pass 中更新，避免多个会话同时改同一个表。
+
+Checker 必须反向扫描模块任务目录：
+
+- 模块任务必须被本模块 `module_plan.md` 索引。
+- 普通模块 worker 分支上，如果全局总表尚未同步，必须在任务文件里留下 `Coordinator Handoff: pending-coordinator-pass`。
+- coordinator 集成 pass 必须清掉 pending handoff，并同步 `Module-Registry.md`、`Harness-Ledger.md`、必要的 Closeout / Regression 表。
+- 最终集成门禁可启用严格模式，要求活跃模块任务已经完成全局总表同步。
+
+严格模式命令：
+
+```bash
+HARNESS_REQUIRE_GLOBAL_MODULE_SYNC=1 node scripts/check-harness.mjs <repo-path>
+```
+
+这条规则的目的不是让每个 worker 都改总表，而是让总表同步变成单一 owner 的串行步骤。
+
+## 跨模块重构
+
+当需要修改多个模块共享的代码（如改 shared type、重命名 utility）时：
+
+1. 不走模块 worktree
+2. 在主干上开普通 task worktree（命名：`refactor/<name>`）
+3. 完成后 merge 回主干
+4. 各模块 worktree rebase 到最新主干
+5. 可选：在 Module Registry 标注 `infra-task-pending: true`，提醒各模块会话 rebase
+
+基础设施 task 的文件放在 `docs/09-PLANNING/MODULES/_shared/TASKS/` 下。
+
+## 模块级 Worktree
+
+每个模块对应一个长期 worktree：
+
+- 命名：`codex/<module-key>`（如 `codex/reader`、`codex/graph`）
+- 生命周期：模块活跃期间持续存在，不在每个步骤后删除
+- 步骤在模块 worktree 内顺序执行，每个步骤完成后提交并推送
+
+### Merge 策略
+
+项目级决定，二选一：
+
+- **频繁合并**：每个步骤完成后 merge 回 main。divergence 小，冲突少。适合 solo-orchestrator（main 上有半成品不影响他人）。
+- **批量合并**：所有步骤完成后一次性 merge。main 始终是完整功能。适合有 CI/CD 发布流水线绑定 main 的项目。
+
+### 定期 Rebase
+
+无论哪种策略，模块 worktree 应定期 rebase 到最新 main：
+- 建议频率：每周一次，或每次基础设施 task 完成后
+- 目的：避免 divergence 过大导致 merge 困难
+
+## 与 Feature SSoT 的分工
+
+启用模块并行后：
+
+- **Module Registry + module_plan.md** 追踪模块内步骤进度
+- **Feature SSoT** 只追踪：
+  - 不属于任何模块的独立功能
+  - 发布级汇总（哪个 release 包含了哪些模块步骤）
+
+**禁止**：同一个工作项同时出现在 module_plan 和 Feature SSoT 中。
+
+切换时必须收缩 Feature SSoT：
+
+- Feature SSoT Active 表只保留非模块、未完成、仍需操作的 feature。
+- Phase 历史和 completed 明细移到 `docs/09-PLANNING/_archive/<feature-ssot-name>-phase-<range>.md`。
+- Feature SSoT 主文件保留 freeze notice、当前 active 指针、completed summary、archive index。
+- 不允许把历史大表留在 Feature SSoT 主文件底部作为"文件内归档"；这会让 Active SSoT 继续膨胀。
+
+## 归档与过期检测
+
+### 归档
+
+- 模块所有步骤完成后，状态改为 `completed`
+- 将模块目录移入 `docs/09-PLANNING/MODULES/_archive/<key>/`
+- 对应的 walkthrough 保留在 `docs/10-WALKTHROUGH/<key>/`（不归档）
+
+### 过期检测
+
+- 如果模块 Updated 字段超过 30 天未更新：checker 发出 warning
+- 超过 60 天未更新：建议标记为 `paused`
+- `paused` 模块可随时恢复为 `in-progress`
+
+## 从线性 Phase 迁移
+
+对已有线性 Phase 历史的项目：
+
+1. 冻结 Feature SSoT 当前状态，标注"后续工作按模块推进"
+2. 将 Feature SSoT 的历史 completed 明细移入 `docs/09-PLANNING/_archive/`，主文件只保留 active 指针、summary 和 archive index
+3. 将历史 `docs/09-PLANNING/TASKS/` 移入 `docs/09-PLANNING/_archive/`
+4. 将历史 walkthrough 移入 `docs/10-WALKTHROUGH/_archive/`
+5. 从最后一个 Phase 的未完成项中识别模块
+6. 创建 Module Registry 和各模块的 module_plan.md
+7. 创建 Module Session Prompt Pack 或每模块 `session_prompt.md`
+8. 定义切换日期，此后不再创建新 Phase
+
+不做的事：
+- 不回溯重写历史 Ledger 条目
+- 不删除现有 Feature SSoT
+- 不强制已完成的 Phase 工作重新归类