coding-agent-harness 1.0.0

package/references/ssot-governance.md

@@ -0,0 +1,111 @@
+# SSoT 治理
+
+## 核心思路
+
+SSoT（Single Source of Truth，单一事实源）是长程项目的命脉。没有 SSoT，agent 和人都会在多个版本的"真相"之间迷失。
+
+## 四张 SSoT + 一张 Ledger
+
+长程项目需要四张 SSoT 保存当前事实，再用一张全局 Harness Ledger 记录每轮任务是否按 SOP 维护这些事实。
+
+### Delivery SSoT（交付排期表）
+
+管理多人、多 agent、多仓或传统流程下的 feature block 分配、依赖和集成顺序。
+
+- 文件：`docs/09-PLANNING/Delivery-SSoT.md`
+- 职责：谁负责哪个 feature block、agent 能看哪些上下文、依赖和 merge 顺序是什么
+- 规则：多人、多仓、split-repo、program、waterfall 或 kanban 团队流程必须维护
+
+### Feature SSoT（实施排期表）
+
+管理 feature / wave / implementation 的进度和 residual。
+
+- 文件：`docs/09-PLANNING/Feature-SSoT.md`（按你的项目命名）
+- 职责：哪些 feature 在做、做到哪了、还剩什么
+- 规则：开始任何非平凡任务前先读，完成后必须回写
+- 归档：Active 表只保留未完成或仍需操作的 feature；completed / superseded 历史行超过 20 条、release 收束、或启用模块并行切换时，必须移入 `docs/09-PLANNING/_archive/` 的 Feature SSoT 归档文件
+
+### Regression SSoT（回归控制塔）
+
+管理所有 regression surface 的状态、证据深度和残项。
+
+- 文件：`docs/05-TEST-QA/Regression-SSoT.md`
+- 职责：哪些回归面存在、每条的标准入口、当前证据深度、residual
+- 规则：新增固定 gate 或 evidence depth 变化时必须更新
+
+### Lessons SSoT（经验沉淀）
+
+管理 Agent 在开发过程中发现的经验、改进建议和规范演进。
+
+- 文件：`docs/01-GOVERNANCE/Lessons-SSoT.md`
+- 职责：哪些经验值得沉淀、当前审批状态、冲突关系
+- 规则：Walkthrough 收口后检查是否有沉淀建议；写之前必须完整读 SSoT
+- 详细治理规范：`references/lessons-governance.md`
+
+### Harness Ledger（全局上下文回写总账）
+
+管理每个非平凡任务对 harness 文档骨架的回写情况。
+
+- 文件：`docs/Harness-Ledger.md`
+- 职责：本轮任务是否回写 task plan、Feature SSoT、Regression SSoT、walkthrough、Lessons SSoT 和 reference/template
+- 规则：任务收口时最后更新；只记录任务级 compliance，不记录逐行 diff
+- 详细规范：`references/harness-ledger.md`
+
+### 分工规则
+
+- Feature SSoT 不替代 Regression SSoT
+- Delivery SSoT 不替代 Feature SSoT；它管交付组织和集成顺序，不管功能细节
+- Regression SSoT 也不替代 Feature SSoT
+- Lessons SSoT 不替代前两者，它管的是规范本身的演进
+- Harness Ledger 不替代任何 SSoT，它只记录本轮任务是否维护了对应事实
+- 四张 SSoT 和 Harness Ledger 必须各司其职，不能彼此吞并
+
+### Module Registry 与 Feature SSoT 的分工
+
+当项目启用模块并行开发（见 `references/module-parallel-standard.md`）时：
+
+- **Module Registry + module_plan.md** 追踪模块内步骤进度（替代 Feature SSoT 对模块工作的追踪）
+- **Feature SSoT** 只追踪：
+  - 不属于任何模块的独立功能
+  - 发布级汇总（哪个 release 包含了哪些模块步骤）
+
+**禁止**：同一个工作项同时出现在 module_plan 和 Feature SSoT 中。这会造成真相分裂。
+
+模块并行切换后，Feature SSoT 的 Active 表必须变小：
+
+- Active 表只保留不属于任何模块、且仍未完成的独立功能。
+- Phase 历史、completed feature 明细、旧 task 路径明细移入 `docs/09-PLANNING/_archive/`。
+- Feature SSoT 主文件只保留冻结边界、当前 active 指针、completed summary 和 archive index。
+- 不允许把几百行历史明细继续堆在 Feature SSoT 底部作为“文件内归档”。
+
+未启用模块并行的项目继续使用 Feature SSoT 追踪所有功能进度。
+
+## SSoT 归档规则
+
+每张 SSoT 都必须区分 Active 与 Archive。Active 保存当前事实；Archive 保存可追溯历史。
+
+| SSoT | Active 保留 | 归档触发 | 归档位置 |
+|------|-------------|----------|----------|
+| Feature SSoT | 未完成 / 仍需操作的 feature | completed/superseded 超过 20 条、release 收束、模块并行切换 | `docs/09-PLANNING/_archive/` |
+| Delivery SSoT | 当前交付 block、集成顺序和阻塞项 | wave 结束或 completed/superseded blocks 超过 20 条 | `docs/09-PLANNING/_archive/` |
+| Module Registry | 活跃 / 暂停不久的模块 | 模块 completed 或 paused 超过 60 天 | `docs/09-PLANNING/MODULES/_archive/<key>/` |
+| Regression SSoT | active gates | gate 废弃或长期不再运行 | `docs/05-TEST-QA/_archive/` |
+| Lessons SSoT | pending / approved / superseded 条目 | merged/rejected 超过 20 条 | `docs/01-GOVERNANCE/_archive/` |
+| Harness Ledger | 最近 50 条 active/closed 任务记录 | closed/superseded 超过 50 条 | `docs/01-GOVERNANCE/_archive/` |
+
+归档不改变 ID，不删除证据文件；Active 文件必须留下 archive index 或指向归档文件。
+
+## SSoT 与 Planning 的双向绑定
+
+- 每个 task plan 必须指向 SSoT 中的对应条目
+- SSoT 中的每个条目必须指向对应的 task plan
+- 完成任务后，SSoT 和 task plan 都必须更新
+- 非平凡任务完成后，Harness Ledger 必须记录本轮上下文回写结果
+
+## 常见反模式
+
+- 只更新 task plan 不回写 SSoT → SSoT 过时，下一轮 agent 拿到错误信息
+- 只更新 SSoT 不更新 task plan → 任务目录变成死文档
+- 建多个平行的进度总览 → 真相分裂，没人知道哪个是对的
+- 把业务事实复制进 Harness Ledger → 四张 SSoT 被架空
+- 把 Harness Ledger 写成逐行 diff 流水账 → 表会快速失控，没人再读

package/references/walkthrough-closeout.md

@@ -0,0 +1,135 @@
+# Walkthrough 收口
+
+## 核心思路
+
+每个 wave / feature 完成后,必须写一篇 walkthrough。这是给下一轮 agent 看的交接文档,不是给人看的周报。
+
+## Walkthrough 模板
+
+```markdown
+# [Wave/Feature 名称] Walkthrough
+
+## 概要
+[一句话说清楚这个 wave 做了什么]
+
+## 改动范围
+- [改了哪些包/模块]
+- [新增了哪些文件]
+- [删除了哪些文件]
+
+## 关键决策
+- [决策1:为什么选了方案A而不是方案B]
+- [决策2:...]
+
+## 验证结果
+- [跑了哪些测试]
+- [回归结果]
+- [Evidence Depth 到了哪一层]
+- [Review Report: review.md 路径、material finding 状态、no-finding 结论]
+
+## Residual
+- [遗留问题1]
+- [遗留问题2]
+
+## Lessons Reflection
+- 本轮有没有发现 reference / workflow / checker 不够用或有误：[有/无，写一句理由]
+- 有没有反复出现、跨页面/跨模块/跨阶段的共性问题：[有/无，写一句理由]
+- 有没有下次 agent 也可能重复踩的坑：[有/无，写一句理由]
+- Lessons 结果：[checked-created: L-YYYY-MM-DD-NNN / checked-none: 一句话原因]
+- Lessons Detail Doc：[如 checked-created，填 `docs/01-GOVERNANCE/lessons/...md`；否则写"无"]
+
+## 相关文件
+- Task Plan: [路径]
+- SSoT 条目: [引用]
+- Regression Gate: [引用]
+- Harness Ledger: [HL-...]
+```
+
+## 存放位置
+
+```
+docs/10-WALKTHROUGH/<YYYY-MM-DD-wave名称>.md
+```
+
+Closeout SSoT:
+
+```text
+docs/10-WALKTHROUGH/Closeout-SSoT.md
+```
+
+## 规则
+
+1. **每个 wave 必须有 walkthrough** — 没有 walkthrough 的 wave 视为未完成
+2. **Walkthrough 必须包含 residual** — 即使没有遗留问题，也要显式写“无 residual”
+3. **Walkthrough 必须引用验证结果** — 跑了什么、结果是什么
+4. **如有 review.md，Walkthrough 必须引用审查结论** — material findings、no-finding statement、accepted residual 必须可追溯
+5. **Walkthrough 必须包含 Lessons Reflection** — 写 walkthrough 时就要反思共性问题、反复问题、下一轮 agent 可能重复踩的坑
+6. **Walkthrough 不是代码注释** — 不需要逐行解释代码，重点是决策、验证和可复用教训
+7. **Walkthrough 完成后必须执行经验沉淀检查** — 见下方“经验沉淀检查”章节
+8. **收口后必须更新 Harness Ledger** — 记录本轮上下文回写是否完成
+9. **收口后必须更新 Closeout SSoT** — 每个 `closed` / `closed-with-residual` / `closed-local-only` 的 Harness Ledger row 必须有 Closeout SSoT row
+
+## Closeout SSoT 规则
+
+`Closeout-SSoT.md` 是 walkthrough 是否写入的硬门槛，不是目录索引。
+
+每个 closed 任务必须满足一项：
+
+1. `Walkthrough` 列写入 `docs/10-WALKTHROUGH/<file>.md`
+2. `Walkthrough` 列写入受控 skip reason
+
+允许的 skip reason 只有：
+
+- `walkthrough skipped-with-reason: docs-only`
+- `walkthrough skipped-with-reason: no-runtime`
+- `walkthrough skipped-with-reason: superseded`
+- `walkthrough skipped-with-reason: historical-backfill`
+- `walkthrough skipped-with-reason: owner-deferred`
+
+如果任务是 implementation wave，默认必须写 walkthrough；skip reason 只用于 docs-only、历史补录、被后续收口取代、或需要 owner 另行决定的场景。
+
+## 经验沉淀检查
+
+写完 Walkthrough 并更新 Feature/Regression SSoT 之后，Agent 必须执行以下自检：
+
+1. 这次开发中有没有发现现有 reference 不够用或有误的地方？
+2. 有没有值得固化为规范的新模式/新做法？
+3. 有没有踩坑经验值得记录，避免下次重复？
+4. 有没有架构层面的洞察，值得更新架构文档？
+
+这一步不是普通勾选。写 walkthrough 时，Agent 必须主动从“这次做了什么”切换到
+“下次怎样避免重复问题”的复盘视角，尤其检查：
+
+- 同一类问题是否跨多个文件、页面、阶段或 review round 反复出现？
+- 本轮是否暴露了 prompt、模板、checker 或 reference 没有强制到位的地方？
+- 有没有某个动作虽然已有规范，但 agent 没有主动执行？
+
+如果任何一条答案是“有”：
+
+1. 完整读一遍 `docs/01-GOVERNANCE/Lessons-SSoT.md`
+2. 按 `references/lessons-governance.md` 中的规则处理冲突
+3. 在 `docs/01-GOVERNANCE/lessons/` 下写入详细建议（使用 `templates/lessons/` 下的对应模板）
+4. 更新 Lessons SSoT 表，`Detail Doc` 必须指向刚写的详情文档
+5. 在 Closeout SSoT 和 Harness Ledger 中记录 `checked-created: L-YYYY-MM-DD-NNN`
+
+如果所有答案都是“没有”，不能静默跳过；在 Closeout SSoT 和 Harness Ledger 中记录
+`checked-none: <一句话原因>`。
+
+## Harness Ledger 回写
+
+写完 Walkthrough、更新 Feature/Regression SSoT，并完成 Lessons 检查后，Agent 必须更新
+`docs/Harness-Ledger.md` 和 `docs/10-WALKTHROUGH/Closeout-SSoT.md`：
+
+1. 为本轮任务追加或更新对应 `HL-*` 条目
+2. 记录 Task Plan、Feature SSoT、Regression SSoT、Review Report、Walkthrough、Lessons Check 的结果
+3. 列出本轮触碰的 harness 文档
+4. 如有未完成项，使用 `missing` 或 `skipped-with-reason` 并写明 residual
+
+没有 Harness Ledger 条目或 Closeout SSoT 条目的 wave，不视为完整 closed。
+
+## 为什么 Walkthrough 有效
+
+- 下一轮 agent 开始工作前,读最近几篇 walkthrough 就能快速了解项目当前状态
+- Residual 列表是下一轮任务的输入源之一
+- 关键决策记录避免后续 agent 推翻已经验证过的架构选择
+- 可追溯性:413 篇 walkthrough = 413 次可查的交接记录

package/references/worktree-parallel.md

@@ -0,0 +1,184 @@
+# Worktree 并行开发
+
+## 核心思路
+
+所有非平凡代码任务，默认先开独立的 git worktree，再开始写代码。这样多个 agent 可以在各自的分支上独立工作，互不干扰。
+
+但 worktree 只是 `solo-orchestrator` 或单仓并行的一种实现。若项目是多人团队、
+前后端分仓、program 多仓或瀑布 stage-gate，必须先读
+`docs/11-REFERENCE/delivery-operating-model-standard.md`，再决定使用 worktree、
+feature branch、contract branch、release branch 或跨仓 paired PR。
+
+## 什么时候必须开 worktree
+
+- 跨多个子项目或多文件的实现/重构
+- 会持续多轮迭代的任务
+- regression / smoke / harness 语义改动
+- 当前主工作区已经有未提交改动，且本轮任务不是在这些改动上继续
+
+## 什么时候可以不开
+
+- 纯只读分析
+- 纯文档小修
+- 用户明确要求直接在当前工作区修改
+- 当前任务就是接着本工作区已存在的同一批改动继续收尾
+
+## 为什么并行开发不会乱
+
+1. **分支隔离** — 每个 worktree 有自己的分支，代码改动互不影响
+2. **Planning 隔离** — 每个 worktree 对应的 agent 只看自己的 task_plan，不会被别的任务上下文污染
+3. **Merge 时自动回归** — Cadence Ledger 定义了改什么就跑什么回归面
+4. **Worktree 清理** — merge 完成后必须删除，不允许长期堆积
+
+## Worktree 命名规范
+
+格式：`<前缀>-<任务名称>`
+
+前缀规则：
+- `feat/` — 新功能
+- `fix/` — Bug 修复
+- `refactor/` — 重构
+- `test/` — 测试相关
+- `docs/` — 文档相关
+
+示例：
+- `feat/user-auth-oauth2`
+- `fix/timeline-render-delay`
+- `refactor/external-adapter-decouple`
+
+## 分支命名规范
+
+分支名与 worktree 名保持一致，使用同样的前缀和任务名。
+
+## 操作流程
+
+### 创建 Worktree
+
+```bash
+# 1. 确保主干是干净的
+git status  # 应该是 clean
+
+# 2. 创建 worktree
+git worktree add .worktrees/<worktree-name> -b <branch-name>
+
+# 3. 进入 worktree
+cd .worktrees/<worktree-name>
+
+# 4. 安装依赖（如需要）
+npm install  # 或 pnpm install / yarn install
+```
+
+### Merge 回主干
+
+```bash
+# 1. 在 worktree 中确保所有改动已提交
+git status  # 应该是 clean
+
+# 2. 回到主工作区
+cd /path/to/main/repo
+
+# 3. Merge
+git merge <branch-name>
+
+# 4. 解决冲突（如有）
+# ...
+
+# 5. 跑回归测试（按 Cadence Ledger 规则）
+```
+
+### 清理 Worktree
+
+```bash
+# 1. 删除 worktree
+git worktree remove .worktrees/<worktree-name>
+
+# 2. 删除分支（如已 merge）
+git branch -d <branch-name>
+
+# 3. 确认清理完成
+git worktree list  # 不应该再看到该 worktree
+```
+
+## 多 Agent 并行分工协议
+
+当多个 agent 同时在不同 worktree 上工作时：
+
+1. **任务分配必须明确** — 每个 agent 只负责自己的 worktree，不跨 worktree 操作
+2. **共享文件的修改需要协调** — 如果两个 agent 都需要改同一个文件，必须串行执行
+3. **Merge 顺序由人决定** — agent 不应自行决定 merge 顺序
+4. **冲突解决需要人工确认** — agent 可以尝试自动解决简单冲突，但复杂冲突必须报告给人
+
+## Subagent Worker Handoff / Coordinator Integration
+
+当主 agent 作为 coordinator 调用 subagent 时，必须先区分角色：
+
+- **reviewer**：只读审查，输出 `review.md` / findings / report，不改业务代码。
+- **worker**：会改代码、测试、产品文档或 harness 文档，必须使用独立 worktree / branch。
+
+Worker handoff 的最低字段：
+
+- worktree path
+- branch
+- task directory
+- write scope
+- commit SHA
+- checks run and result
+- residual risks / shared-file conflicts
+
+Coordinator 集成规则：
+
+1. coordinator 先分配 worker 的 worktree、branch、任务目录和 write scope。
+2. worker 只在自己的 worktree 内编辑并提交；不得把改动直接写进 coordinator 当前 checkout。
+3. coordinator 通过 worker commit / branch 集成结果，解决冲突并运行最终 gates。
+4. 若工具限制、用户要求或紧急情况导致未使用独立 worktree，必须在 progress、walkthrough
+   或 Harness Ledger 记录 deviation reason、风险和补偿验证。
+
+## 并发上限
+
+项目必须在 `docs/11-REFERENCE/repo-governance-standard.md` 的 Worktree Concurrency
+中定义 max active worktrees、merge ordering rule 和 cleanup owner。
+
+未定义并发上限时，不应启动多 agent 并行开发。
+
+## 保留旧 Worktree 的唯一合理理由
+
+- 当前还有运行中的服务依赖该路径
+- 仍在做未完成的验证或回滚比对
+- 用户明确要求保留
+
+若选择暂时保留，必须在 progress.md 里写明保留原因。
+
+## 模块级 Worktree
+
+当项目启用模块并行开发（见 `references/module-parallel-standard.md`）时，每个模块对应一个长期 worktree。这与上文的"任务级 worktree"（每个 task 一个，merge 后删除）共存不冲突。
+
+### 命名
+
+`codex/<module-key>`（如 `codex/reader`、`codex/graph`）
+
+### 生命周期
+
+- 模块注册时创建，模块完成时删除
+- 步骤在模块 worktree 内顺序执行，每个步骤完成后提交并推送
+- 不在每个步骤后删除 worktree
+
+### Merge 策略（项目级决定）
+
+- **频繁合并**：每个步骤完成后 merge 回 main。divergence 小，冲突少。推荐 solo-orchestrator 使用。
+- **批量合并**：所有步骤完成后一次性 merge。main 始终是完整功能。适合有 CI/CD 发布流水线绑定 main 的项目。
+
+### 定期 Rebase
+
+无论哪种策略，模块 worktree 应定期 rebase 到最新 main：
+
+- 频率：每周一次，或每次基础设施 task 完成后
+- 目的：避免 divergence 过大导致 merge 困难
+
+### 与任务级 Worktree 的区别
+
+| 维度 | 任务级 Worktree | 模块级 Worktree |
+|------|----------------|----------------|
+| 命名 | `feat/<task-name>` | `codex/<module-key>` |
+| 生命周期 | 一个 task，merge 后删除 | 模块活跃期间持续存在 |
+| 适用场景 | 独立短期任务 | 长期演进的功能域 |
+| 清理时机 | task 完成后立即清理 | 模块所有步骤完成后清理 |