coding-agent-harness 1.0.0

package/templates-zh-CN/reference/walkthrough-standard.md

@@ -0,0 +1,83 @@
+# 收口记录标准
+
+## 职责
+
+收口记录是每个 wave、feature、release 或非平凡任务完成后的交接文档，写给下一轮 agent、reviewer 和维护者看。它不复述每一行代码，而是说明本轮做了什么、为什么这样做、如何验证、还有什么 residual。
+
+默认位置：
+
+```text
+docs/10-WALKTHROUGH/YYYY-MM-DD-<feature-name>.md
+```
+
+Closeout SSoT 固定位置：
+
+```text
+docs/10-WALKTHROUGH/Closeout-SSoT.md
+```
+
+## 何时必须写
+
+- 每个 feature、wave、release 或非平凡任务完成后。
+- merge 后需要给后续 agent 留交接。
+- 产生 review、regression、CI/CD、Lessons 或 Harness Ledger 回写。
+- 用户要求阶段收口或交付总结。
+
+没有 walkthrough 的非平凡任务视为未完整收口；如受控跳过，必须登记原因。
+
+## 必须包含
+
+1. **概要**：一句话说清楚本轮交付。
+2. **改动范围**：模块、文件、配置、文档和外部系统影响。
+3. **关键决策**：为什么选择当前方案，放弃了什么方案。
+4. **验证结果**：测试、回归、CI/CD、smoke、browser inspection、evidence depth。
+5. **审查结果**：引用 `review.md`，列出 material findings、no-finding 结论和 `accepted-risk`。
+6. **残余风险**：没有残余也要写“无”；有残余则写 owner 和后续路径。
+7. **Lessons 反思**：判断是否有可沉淀的 workflow、reference、checker 或工程规则。
+8. **关联信息**：task plan、SSoT、Regression SSoT、Harness Ledger ID、commit、PR、release。
+
+## 写作原则
+
+- 重点写决策、证据和残余，不写流水账。
+- 用路径和命令引用证据，不依赖聊天记录。
+- 表格适合列验证、关联和 residual；段落适合解释判断。
+- 关键决策要足够明确，避免后续 agent 推翻已验证选择。
+- 如果本轮存在 skipped check，必须说明原因、影响和 owner。
+
+## 收口单一事实源规则
+
+以下 Harness Ledger row 必须有 Closeout SSoT row：
+
+- `closed`
+- `closed-with-residual`
+- `closed-local-only`
+
+Closeout SSoT 中：
+
+- walkthrough 列写实际路径，或写受控跳过原因。
+- Lessons 检查列写 `checked-created: L-YYYY-MM-DD-NNN` 或 `checked-none: <reason>`。
+- 允许的跳过原因只有：`docs-only`、`no-runtime`、`superseded`、`historical-backfill`、`owner-deferred`。
+
+## 经验沉淀反思规则
+
+写 walkthrough 时必须加入“Lessons 反思”小节，并回答：
+
+1. 本轮有没有发现 reference、workflow、checker 不够用或有误？
+2. 有没有反复出现、跨页面、跨模块或跨阶段的共性问题？
+3. 有没有下次 agent 也可能重复踩的坑？
+
+任一答案为“有”时：
+
+- 先在 `docs/01-GOVERNANCE/lessons/` 写 lesson 详情文档。
+- 再在 Lessons SSoT 追加一行。
+- Lessons SSoT 的详情文档列必须指向该详情文档。
+
+三个答案都为“没有”时，Closeout SSoT 和 Harness Ledger 仍要记录：
+
+```text
+checked-none: <reason>
+```
+
+## 收口要求
+
+walkthrough 写完后，必须更新 Closeout SSoT 和 Harness Ledger。涉及回归、CI/CD、repo governance、reference 或 template 的，还要同步对应标准或 SSoT。

package/templates-zh-CN/reference/worktree-standard.md

@@ -0,0 +1,116 @@
+# 工作树标准
+
+## 职责
+
+本标准定义 git worktree 的使用规则，确保多 agent、长程任务和隔离开发不会污染主工作区。worktree 是执行隔离和交接边界，不是临时目录。
+
+## 必须使用独立工作树的场景
+
+- 跨多个模块的实现、重构或迁移。
+- 会持续多轮迭代的任务。
+- regression、smoke、checker、harness 语义改动。
+- 当前主工作区已有未提交改动，且本轮任务不是继续这些改动。
+- 使用可写 subagent worker。
+- 多个任务需要并行推进。
+
+## 可以不开的场景
+
+- 纯只读分析。
+- 明确的小文档修正。
+- 用户明确要求直接在当前工作区修改。
+- 当前任务就是接着本工作区已存在的同一批改动继续收尾。
+
+不开 worktree 时，必须在 task plan 或 progress 中写明原因。
+
+## 命名规则
+
+worktree 目录推荐：
+
+```text
+.worktrees/<type>/<name>
+```
+
+分支名推荐：
+
+```text
+<type>/<name>
+```
+
+常用类型：
+
+- `feat/`：新功能。
+- `fix/`：缺陷修复。
+- `refactor/`：重构。
+- `test/`：测试相关。
+- `docs/`：文档相关。
+- `codex/`：agent 任务分支。
+
+示例：
+
+```text
+.worktrees/feat/user-auth-oauth2 -> feat/user-auth-oauth2
+.worktrees/fix/timeline-render-delay -> fix/timeline-render-delay
+```
+
+## 记录规则
+
+开始实现前，在 `task_plan.md` 或 `progress.md` 记录：
+
+- worktree 路径。
+- 分支名。
+- owner。
+- 允许修改范围。
+- 与主工作区或其他 worktree 的冲突风险。
+- 未开 worktree 的原因。
+
+## 多代理并行规则
+
+1. 每个 agent 只操作自己的 worktree。
+2. 会改代码、测试、产品文档或 harness 文档的 subagent 必须升级为 worker，并使用独立 worktree / branch。
+3. reviewer subagent 默认只读；如要修改，必须重新分配 worker 合同。
+4. 共享文件修改需要 coordinator 串行协调。
+5. merge 顺序由 coordinator、maintainer 或 release owner 决定。
+6. 复杂冲突必须记录并上报，不允许静默覆盖。
+
+## 可写执行者交接
+
+Coordinator 启动 worker 前必须给出：
+
+- worktree 路径。
+- 分支名。
+- 任务目录。
+- write scope。
+- 允许触碰的共享文件。
+- required checks。
+- handoff 格式。
+
+Worker 收口前必须：
+
+- 只在自己的 worktree 内修改。
+- 提交自己的改动。
+- handoff 写明 worktree path、branch、commit SHA、checks、residual。
+
+Coordinator 必须：
+
+- 只通过 commit / branch 集成 worker 结果。
+- 不让多个 worker 在 coordinator 当前 checkout 留下混合未提交改动。
+- 集成后运行最终 regression / smoke / required checks。
+- 将偏离 worktree 规则的原因写入 progress、walkthrough 或 Harness Ledger。
+
+## 清理规则
+
+- merge 完成后删除对应 worktree。
+- 已 merge 的分支按项目规则删除。
+- 长期保留 worktree 必须在 progress 或 Delivery SSoT 中写原因。
+- 不允许堆积无 owner、无任务、无状态的 worktree。
+
+## 并发上限
+
+项目必须在 `repo-governance-standard.md` 的 worktree 并发部分定义：
+
+- 最大活跃 worktree 数。
+- merge ordering rule。
+- cleanup owner。
+- shared file lock 或串行规则。
+
+未定义并发上限时，不应启动多 agent 并行开发。

package/templates-zh-CN/regression/Cadence-Ledger.md

@@ -0,0 +1,48 @@
+# 回归节奏总账 - [项目名称]
+
+> 本文件定义“什么改动触发哪些回归 gate”。Regression SSoT 记录 gate 本身；本文件记录触发规则和批次执行历史。
+
+## 使用约定
+
+- 新增、删除或调整 Regression Gate 时，同步更新本文件。
+- 改动范围命中多条规则时，按并集触发，不做最小化猜测。
+- 如果因为时间、环境或权限跳过触发项，必须写入批次日志和残余路由。
+
+## 触发规则
+
+| 改动范围 | 必跑 Gate | 可选 / 条件 Gate | 触发说明 | 负责人 |
+| --- | --- | --- | --- | --- |
+| [范围1，如 API 路由层] | RG-001, RG-003 | RG-010（仅涉及鉴权时） | [为什么需要这些 gate] | [负责人] |
+| [范围2，如前端关键流程] | RG-005 | RG-006（移动端布局变化时） | [说明] | [负责人] |
+| [范围3，如数据库 schema] | RG-001, RG-002, RG-004 | `none` | [说明] | [负责人] |
+| 任何 merge 到主干 | 全量共享批次 | [项目自定义] | 主干合并前或合并后固定批次 | [负责人] |
+
+## 共享回归批次日志
+
+| 批次 ID | 日期 | 范围 | 触发条件 | 执行 Gate | 结果 | 证据 | 残余路由 | 下一检查点 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| SRB-001 | YYYY-MM-DD | 全量 | 初始化基线 | RG-001, RG-002 | pass | [命令、报告或链接] | `none` | SRB-002 after [条件] |
+
+## 归档索引
+
+> 批次日志超过 50 行或完成阶段收口时，移入 `docs/05-TEST-QA/_archive/Cadence-Ledger-archive-YYYY-QN.md`。
+
+| 归档文件 | 覆盖批次 | 移入日期 | 说明 |
+| --- | --- | --- | --- |
+| `docs/05-TEST-QA/_archive/Cadence-Ledger-archive-YYYY-QN.md` | SRB-... 至 SRB-... | YYYY-MM-DD | [说明] |
+
+## 结果状态
+
+- `pass`：触发 gate 全部通过。
+- `pass-with-residual`：通过主判断，但有已路由残余。
+- `fail`：至少一个必跑 gate 失败。
+- `partial`：只执行了部分触发 gate，必须说明缺口。
+- `skipped-with-reason`：未执行，必须写明原因、负责人和补跑条件。
+- `inconclusive`：执行了但证据不足，不能作为通过依据。
+
+## 路由规则
+
+1. `fail`、`partial`、`skipped-with-reason`、`inconclusive` 都必须路由到 Regression SSoT、任务计划或 Harness Ledger。
+2. 全量共享批次的定义变化必须经过负责人确认，并记录在 Harness Ledger。
+3. 发布前采用最近一次相关批次作为依据；过期证据不能直接复用。
+4. 批次日志只记录执行事实，具体失败分析写入 Regression SSoT 或 review。

package/templates-zh-CN/ssot/Delivery-SSoT.md

@@ -0,0 +1,60 @@
+# 交付 SSoT - [项目名称]
+
+> 面向多人、多 agent、多仓或多模块交付的协调单一事实源。它回答“谁负责哪块、写哪里、依赖谁、按什么顺序集成”。
+
+## 交付模型
+
+| 字段 | 当前值 |
+| --- | --- |
+| 交付模型 | [solo-orchestrator / team-feature-lead / split-repo-contract / program-multi-repo / kanban-continuous / 其他] |
+| 计划负责人 | [负责人] |
+| 集成负责人 | [负责人] |
+| 仓库拓扑 | [单仓 / 多仓 / 上下游仓 / 前后端分离] |
+| 当前窗口 | [sprint、stage、release、日期范围] |
+| 共享文件策略 | [coordinator-only / shared-lock-owner / contract-first / 其他] |
+
+## 活跃交付块
+
+| 工作块 ID | 功能 / 工作块 | 负责人 | Agent 范围 | 仓库 / 目录 | 依赖 | 共享文件 / 合同 | 集成顺序 | 验收 Gate | 状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| DB-001 | [工作块名称] | [负责人] | [允许编辑范围] | `[repo 或 path]` | [DB-...] / `none` | [共享文件、接口合同或锁负责人] | 1 | [测试、review、Regression Gate] | planned |
+
+## 跨仓 / 跨模块合同
+
+| 合同 ID | 生产方 | 消费方 | 事实源 | 兼容规则 | 验证方式 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- |
+| DC-001 | [repo/module] | [repo/module] | [OpenAPI、类型、schema、文档路径] | [向后兼容、版本策略、迁移规则] | [命令、测试、人工验收] | draft |
+
+## 集成队列
+
+| 顺序 | 工作块 ID | PR / Branch / Worktree | 合并前必需项 | 集成负责人 | 状态 |
+| --- | --- | --- | --- | --- | --- |
+| 1 | DB-001 | `[branch 或 PR]` | [review、测试、合同验证] | [负责人] | waiting |
+
+## 归档索引
+
+> 已完成交付块在 release 或阶段收口后移入 `docs/09-PLANNING/_archive/Delivery-SSoT-archive-YYYY-QN.md`，活跃表只保留当前仍会影响集成决策的内容。
+
+| 归档文件 | 覆盖范围 | 移入日期 | 说明 |
+| --- | --- | --- | --- |
+| `docs/09-PLANNING/_archive/Delivery-SSoT-archive-YYYY-QN.md` | DB-... 至 DB-... | YYYY-MM-DD | [说明] |
+
+## 状态说明
+
+- `planned`：已纳入交付计划，尚未分配或启动。
+- `assigned`：已分配负责人和写入范围。
+- `in-progress`：正在实现或验证。
+- `blocked`：依赖、合同、权限、环境或审查阻塞。
+- `ready-for-integration`：工作块完成，等待集成负责人合并。
+- `integrating`：正在合并、解决冲突或跑集成验证。
+- `integrated`：已集成，等待 release / closeout。
+- `closed`：已完成交付收口。
+- `superseded`：被其他工作块或合同取代。
+
+## 路由规则
+
+1. 工作块范围必须互不重叠；共享文件必须指定唯一负责人或走合同优先。
+2. 依赖未满足时不得标记 `ready-for-integration`。
+3. 跨仓接口变化必须有合同条目，不能只靠聊天说明。
+4. 集成队列是合并顺序来源；临时改顺序必须更新本文件。
+5. 完成后的证据和残余同步回 Harness Ledger 与 Closeout SSoT。

package/templates-zh-CN/ssot/Feature-SSoT.md

@@ -0,0 +1,49 @@
+# 功能 SSoT - [项目名称]
+
+> 功能、wave、用户可见改动和实现残余的单一事实源。开始非平凡功能前先读本文件，收口后必须回写。
+
+## 使用约定
+
+- 只记录当前仍需要决策、执行、验证或追踪的功能项。
+- 每个条目必须能指向任务计划、分支或 worktree、验证证据和残余负责人。
+- 不在这里记录逐行 diff；实现细节写在任务计划、review、walkthrough 或 PR 中。
+
+## 活跃功能
+
+| 功能 ID | 功能 / Wave | 负责人 | 状态 | 任务计划 | 分支 / Worktree | 验收依据 | 残余路由 | 更新时间 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| F-001 | [功能名称] | [负责人] | planned | `docs/09-PLANNING/TASKS/[task]/task_plan.md` | `[branch 或 worktree]` | [验收标准、Regression Gate 或证据路径] | `none` / [负责人 + 后续动作] | YYYY-MM-DD |
+
+## 已完成索引
+
+> 完成项只保留最近一批，便于冷启动。超过 20 行、release 收束或模块并行切换时，移入 `docs/09-PLANNING/_archive/Feature-SSoT-archive-YYYY-QN.md`。
+
+| 功能 ID | 功能 / Wave | 完成日期 | 收口记录 | 关联 Harness ID |
+| --- | --- | --- | --- | --- |
+| F-001 | [功能名称] | YYYY-MM-DD | `docs/10-WALKTHROUGH/[file].md` | HL-YYYY-MM-DD-001 |
+
+## 归档索引
+
+| 归档文件 | 覆盖范围 | 移入日期 | 说明 |
+| --- | --- | --- | --- |
+| `docs/09-PLANNING/_archive/Feature-SSoT-archive-YYYY-QN.md` | F-... 至 F-... | YYYY-MM-DD | [说明] |
+
+## 状态说明
+
+- `planned`：已确认进入计划，但尚未开始实现。
+- `in-progress`：正在实现或验证。
+- `blocked`：被依赖、决策、权限、环境或失败回归阻塞；残余路由必须写清。
+- `ready-for-review`：实现完成，等待审查或验证。
+- `ready-for-release`：审查和回归完成，等待合并、发布或上线。
+- `completed`：已完成并收口，保留索引用于追溯。
+- `paused`：暂缓推进，保留负责人和恢复条件。
+- `cancelled`：明确取消，说明原因和替代方案。
+- `superseded`：被其他功能项取代，必须指向新功能 ID。
+
+## 路由规则
+
+1. 新功能进入实现前，必须有任务计划或明确的轻量豁免原因。
+2. 状态进入 `completed` 前，必须有验证证据、残余路由和 closeout 记录。
+3. 回归失败或覆盖面变化写入 Regression SSoT，不只写在本表备注里。
+4. 可复用流程经验写入 Lessons SSoT，不在本表长篇展开。
+5. 多人并行时，只由功能负责人或协调者更新状态字段。

package/templates-zh-CN/ssot/Lessons-SSoT.md

@@ -0,0 +1,49 @@
+# 经验沉淀 SSoT - [项目名称]
+
+> 可复用经验、流程修正和 reference 改动建议的单一事实源。这里管理 lesson 生命周期，详情必须写在独立文档中。
+
+## 使用约定
+
+- 写新 lesson 前，先完整阅读本表，确认是否已有相同或冲突建议。
+- 表行不能单独存在；每条活跃 lesson 都必须有 `docs/01-GOVERNANCE/lessons/` 下的详情文档。
+- lesson 只记录可复用的机制性改进，不记录一次性 bug、个人偏好或聊天摘要。
+- 人批准前，pending lesson 不能被当成正式流程规则使用。
+
+## 活跃 Lessons
+
+| Lesson ID | 日期 | 来源 | 类型 | 目标 | 摘要 | 详情文档 | 状态 | 冲突 / 关联 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| L-YYYY-MM-DD-001 | YYYY-MM-DD | `docs/10-WALKTHROUGH/[file].md` | ref-change | `docs/11-REFERENCE/[target].md` | [一句话摘要] | `docs/01-GOVERNANCE/lessons/L-YYYY-MM-DD-001-[slug].md` | pending | `none` / L-... |
+
+## 已归档 Lessons
+
+> 状态为 `merged`、`rejected`、`superseded` 的条目在阶段收口后移入 `docs/01-GOVERNANCE/_archive/Lessons-SSoT-archive-YYYY-QN.md`，本节保留索引。
+
+| Lesson ID | 日期 | 处理结果 | 处理日期 | 归档文件 |
+| --- | --- | --- | --- | --- |
+| L-YYYY-MM-DD-001 | YYYY-MM-DD | merged / rejected / superseded | YYYY-MM-DD | `docs/01-GOVERNANCE/_archive/Lessons-SSoT-archive-YYYY-QN.md` |
+
+## 状态说明
+
+- `pending`：Agent 提出建议，等待人审查。
+- `approved`：已批准，等待合入正式 reference、template 或 checker。
+- `merged`：已合入正式文件，并有 commit 或变更证据。
+- `rejected`：明确不采纳，保留原因。
+- `superseded`：被后续 lesson 取代，必须指向新 Lesson ID。
+- `needs-rework`：方向可能成立，但详情文档需要补充或重写。
+
+## 类型说明
+
+- `ref-change`：修改现有 reference、标准或规则文档。
+- `new-doc`：新增 reference、模板、检查器说明或治理文档。
+- `arch-change`：架构、模块边界、仓库结构或系统职责变化。
+- `process-change`：任务流程、审查流程、回归节奏或 closeout 规则变化。
+
+## 路由规则
+
+1. 先写详情文档，再追加本表行；不要先占表行。
+2. `详情文档` 字段必须是路径，不能写摘要。
+3. `ref-change` 的详情文档必须包含基于当前正式文件的完整副本或明确 diff。
+4. 多个 pending lesson 指向同一目标时，必须在“冲突 / 关联”中互相标记。
+5. `merged` 后必须更新目标正式文件，并在详情文档或本表记录证据。
+6. closeout 中的 Lessons 检查必须能追溯到本表行，或写明 `checked-none` 原因。

package/templates-zh-CN/ssot/Module-Registry.md

@@ -0,0 +1,48 @@
+# 模块注册表 - [项目名称]
+
+> 并行模块开发的冷启动入口。它记录模块负责人、分支、写入范围、当前步骤和协调者同步状态。
+
+## 使用约定
+
+- 模块 worker 开始前先读本表，确认自己的写入范围和共享文件限制。
+- worker 只更新自己模块内的计划、进度和交接文件；本注册表通常由协调者或明确的共享锁负责人更新。
+- 写入范围必须互不重叠；有交集时先解决负责人和集成顺序，再启动开发。
+
+## 活跃模块
+
+| 模块 Key | 模块名称 | ID 前缀 | 分支 / Worktree | 当前步骤 | 状态 | 写入范围 | 负责人 | Coordinator 备注 | 更新时间 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| example | 示例模块 | EXM | `codex/example` | EXM-01 | planned | `src/features/example/` | [负责人] | [需要同步的总表项或共享风险] | YYYY-MM-DD |
+
+## 共享范围 / 锁
+
+| 范围 | 当前负责人 | 允许动作 | 释放条件 | 状态 |
+| --- | --- | --- | --- | --- |
+| `[共享文件或目录]` | [负责人] | [只读 / 可编辑 / coordinator-only] | [测试、合并或交接条件] | [open / released / blocked] |
+
+## 归档索引
+
+> 完成、取消或合并进其他模块的条目移入 `MODULES/_archive/Module-Registry-archive-YYYY-QN.md`。
+
+| 归档文件 | 覆盖模块 | 移入日期 | 说明 |
+| --- | --- | --- | --- |
+| `MODULES/_archive/Module-Registry-archive-YYYY-QN.md` | [模块 Key 范围] | YYYY-MM-DD | [说明] |
+
+## 状态说明
+
+- `planned`：模块已规划，尚未启动。
+- `in-progress`：有活跃 worker 正在开发。
+- `blocked`：依赖、共享范围、测试或 review 阻塞。
+- `ready-for-sync`：模块工作完成，等待协调者同步总表或集成。
+- `integrating`：正在合并、解决冲突或跑集成验证。
+- `completed`：模块完成并已收口，可归档。
+- `paused`：暂停推进，保留恢复条件。
+- `cancelled`：取消模块，必须说明替代路径。
+
+## 路由规则
+
+1. 共享基础设施修改走 `_shared` 任务或共享锁，不归入普通模块范围。
+2. 模块状态变化要有对应的 module plan、progress、review 或 evidence 证据。
+3. `ready-for-sync` 不能直接等同完成；协调者同步后才能标记 `completed`。
+4. 写入范围变化必须先更新本表，再让 worker 修改文件。
+5. 模块完成后，收口证据回写 Harness Ledger、Closeout SSoT 和必要的 Feature / Regression SSoT。

package/templates-zh-CN/ssot/Regression-SSoT.md

@@ -0,0 +1,51 @@
+# 回归 SSoT - [项目名称]
+
+> 回归覆盖面、固定 gate、证据深度和未关闭风险的单一事实源。新增 gate、改变触发规则或调整证据深度时必须更新。
+
+## 活跃回归 Gate
+
+| Gate ID | 覆盖面 | 主入口 | 触发场景 | 证据深度 | 上次验证 | 当前结果 | 负责人 | 残余路由 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| RG-001 | [覆盖面名称] | `[命令、脚本、URL 或手工步骤]` | [哪些改动必须触发] | L2-local-smoke | YYYY-MM-DD | pass | [负责人] | `none` / [R-...] |
+
+## 未关闭回归残余
+
+| 残余 ID | Gate ID | 问题 | 严重级别 | 负责人 | 创建日期 | 路由 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+
+不要保留示例残余。只有真实未关闭回归风险才新增行。
+
+## 证据深度说明
+
+| 等级 | 名称 | 说明 |
+| --- | --- | --- |
+| L1-tests | 自动化测试或静态检查通过，但没有运行时验证。 |
+| L2-local-smoke | 本地环境完成关键路径冒烟。 |
+| L3-live | 真实或准真实环境完成端到端验证。 |
+| L4-browser-human-proxy | 浏览器或 UI 自动化覆盖接近真人操作的关键流程。 |
+| L5-hard-gate | 结构化判定、可重复运行，并以非零退出或明确 verdict 阻断发布。 |
+
+## 归档索引
+
+> 废弃 gate、已关闭残余和历史批次移入 `docs/05-TEST-QA/_archive/Regression-SSoT-archive-YYYY-QN.md`。活跃表只保留仍会影响当前开发和发布判断的内容。
+
+| 归档文件 | 覆盖范围 | 移入日期 | 说明 |
+| --- | --- | --- | --- |
+| `docs/05-TEST-QA/_archive/Regression-SSoT-archive-YYYY-QN.md` | RG-... / R-... | YYYY-MM-DD | [说明] |
+
+## 结果状态
+
+- `pass`：本次验证通过，无未路由问题。
+- `pass-with-residual`：主路径通过，但存在已路由或已接受残余。
+- `fail`：验证失败，阻塞相关合并、发布或收口。
+- `inconclusive`：证据不足，不能作为通过依据。
+- `paused`：gate 暂停执行，必须写清原因和恢复条件。
+- `retired`：gate 已废弃，必须归档并说明替代覆盖面。
+
+## 路由规则
+
+1. Cadence Ledger 决定“什么时候触发哪些 gate”；本文件记录 gate 本身和当前事实。
+2. 任何 `fail` 或 `inconclusive` 都必须写入未关闭回归残余，除非立即修复并有新证据。
+3. 发布阻塞级问题必须同步到 Harness Ledger 和对应任务计划。
+4. 接受风险必须有负责人、原因、期限或复查条件。
+5. 提升或降低证据深度时，必须记录原因和最近一次验证证据。

package/templates-zh-CN/verifier/verifier-output.md

@@ -0,0 +1,38 @@
+# 验证器输出（Verifier）
+
+## 验证器元信息（Verifier Metadata）
+
+- template_id: harness-verifier/v1
+- verifier: [agent / tool / human]
+- target: [task / PR / release]
+- verdict: pass / fail / inconclusive
+- date: YYYY-MM-DD
+- confidence_basis: `self-check | verifier-backed | adversarial-reviewed | human-approved`
+
+## 检查范围
+
+[说明本次 verifier 检查了什么、没有检查什么、哪些证据被视为有效依据。]
+
+## 已检查的不变量
+
+| 不变量 | 证据 | 结果 |
+| --- | --- | --- |
+| 没有未关闭的发布阻塞级 P0 / P1 / material-P2 | review、命令、fixture、PR 或运行时验证 | pass / fail / inconclusive |
+
+## 发现记录
+
+| ID | Severity | Finding | Evidence Checked | Required Action | Open | Disposition | Blocks Release | Follow-up |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+允许的 `处理方式`：`open`、`mitigated`、`closed`、`deferred`、`accepted-risk`、`not-reproducible`、`out-of-scope`。
+不要保留示例 finding。若无发现，只保留表头，并在 `Final Confidence Basis` 中说明无发现依据。
+
+## 残余路由
+
+| 残余 | 负责人 | 到期 / 复查条件 | 是否接受风险 | 路由位置 |
+| --- | --- | --- | --- | --- |
+| [风险或未验证项] | [负责人] | [日期或条件] | yes / no | [任务、SSoT、issue、PR 或 Harness ID] |
+
+## 最终信心依据（Final Confidence Basis）
+
+[用中文说明为什么当前 verdict 成立。必须引用实际证据；如果 verdict 是 `inconclusive`，写清缺少什么证据以及下一步由谁补齐。]

package/templates-zh-CN/walkthrough/Closeout-SSoT.md

@@ -0,0 +1,42 @@
+# 收口 SSoT - [项目名称]
+
+> 任务收口证据的单一事实源。每个已关闭的 Harness Ledger 行都必须在这里有对应记录。
+
+## 活跃收口
+
+| Harness ID | 日期 | 任务 | 任务计划 | 审查报告 | 收口记录 | 证据 | 残余路由 | Lessons 检查 | 收口状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| HL-YYYY-MM-DD-001 | YYYY-MM-DD | [任务名称] | `docs/09-PLANNING/TASKS/[task]/task_plan.md` | `review.md` / `n/a: [原因]` | `docs/10-WALKTHROUGH/[file].md` / 允许的跳过原因 | [测试、命令、review、运行时证据] | `none` / [负责人 + 路由] | `checked-created: L-YYYY-MM-DD-001` / `checked-none: [原因]` | [open / closed / blocked] |
+
+## 允许的 walkthrough 跳过原因
+
+- `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`
+
+## 状态说明
+
+- `open`：收口材料仍在整理。
+- `closed`：证据、残余和 Lessons 检查已完成。
+- `closed-with-residual`：收口完成，但仍有已路由残余。
+- `blocked`：缺少必要证据或负责人决策，暂不能收口。
+- `superseded`：被后续 closeout 行取代。
+
+## 归档索引
+
+> 活跃收口表超过 50 行，或 release / wave 完成后，将已关闭条目移入 `docs/10-WALKTHROUGH/_archive/Closeout-SSoT-archive-YYYY-QN.md`。
+
+| 归档文件 | 覆盖 Harness ID | 移入日期 | 说明 |
+| --- | --- | --- | --- |
+| `docs/10-WALKTHROUGH/_archive/Closeout-SSoT-archive-YYYY-QN.md` | HL-... 至 HL-... | YYYY-MM-DD | [说明] |
+
+## 路由规则
+
+1. 每个 `closed`、`closed-with-residual` 或 `closed-local-only` 的 Harness Ledger 行都必须在本文件有一行。
+2. 实现类任务应写 walkthrough；跳过原因只用于受限场景，不用于省略收口。
+3. `证据` 必须列出实际检查、冒烟、review、运行时验证或发布证据。
+4. `残余路由` 必须写 `none`，或指向负责人、任务、Regression SSoT、Harness Ledger、issue 或接受风险记录。
+5. `Lessons 检查` 只能写 `checked-created: L-YYYY-MM-DD-NNN` 或 `checked-none: [原因]`。
+6. `checked-created` 必须同时存在 Lessons SSoT 行和 lesson 详情文档。

package/templates-zh-CN/walkthrough/walkthrough-template.md

@@ -0,0 +1,62 @@
+# [Wave / 功能名称] 收口记录
+
+## 概要
+
+[用一两句话说明本轮交付完成了什么、影响哪些用户或系统能力。]
+
+## 改动范围
+
+- 代码范围：[包、模块、目录或 PR]
+- 文档范围：[任务计划、SSoT、reference、walkthrough、lesson 等]
+- 运行时范围：[服务、页面、接口、脚本、配置；不适用则写 `n/a`]
+- 明确未覆盖：[本轮刻意没有处理的范围]
+
+## 关键决策
+
+| 决策 | 选择 | 原因 | 证据 / 链接 |
+| --- | --- | --- | --- |
+| [决策点] | [采用的方案] | [为什么这样做] | [任务计划、review、issue、commit 等] |
+
+## 验证结果
+
+| 验证项 | 命令 / 步骤 | 结果 | 证据 |
+| --- | --- | --- | --- |
+| [测试或检查名称] | `[命令或步骤]` | pass / fail / inconclusive / skipped-with-reason | [输出摘要、报告路径或截图路径] |
+
+- 回归依据：[Regression SSoT Gate、Cadence Ledger 批次或 `n/a: [原因]`]
+- 证据深度：[L1-tests / L2-local-smoke / L3-live / L4-browser-human-proxy / L5-hard-gate]
+- 未能验证的内容：[无则写 `none`；否则写原因和补验负责人]
+
+## 审查结果
+
+- 审查报告：[review.md、PR review、人工确认或 `n/a: [原因]`]
+- 关键审查发现：[无 / 已修复 / 已接受残余；列出 ID]
+- 未关闭审查项：[无则写 `none`；否则写负责人和路由]
+
+## 残余
+
+| 残余 | 严重级别 | 负责人 | 路由 | 期限 / 复查条件 |
+| --- | --- | --- | --- | --- |
+| `none` | n/a | n/a | n/a | n/a |
+
+## 经验沉淀反思（Lessons）
+
+| 检查问题 | 结论 |
+| --- | --- |
+| 本轮是否暴露 reference、workflow、模板或 checker 的缺口？ | [有 / 无，写一句理由] |
+| 是否出现跨模块、跨阶段、跨 agent 的重复问题？ | [有 / 无，写一句理由] |
+| 下次 agent 是否可能在同类任务中重复踩坑？ | [有 / 无，写一句理由] |
+| Lessons 结果 | `checked-created: L-YYYY-MM-DD-NNN` / `checked-none: [一句话原因]` |
+| Lessons 详情文档 | `docs/01-GOVERNANCE/lessons/[file].md` / `none` |
+
+## 关联索引
+
+- 任务计划：`docs/09-PLANNING/TASKS/[task]/task_plan.md`
+- 进度记录：`docs/09-PLANNING/TASKS/[task]/progress.md`
+- 审查报告：`docs/09-PLANNING/TASKS/[task]/review.md` / `n/a`
+- 功能 SSoT：[F-...]
+- Delivery SSoT：[DB-...] / `n/a`
+- 回归 Gate：[RG-...] / `n/a`
+- Harness Ledger：[HL-...]
+- Closeout SSoT：[对应行]
+- Commit / PR：[hash、branch 或 PR 链接]