coding-agent-harness 1.0.0

package/templates-zh-CN/ledger/Harness-Ledger.md

@@ -0,0 +1,50 @@
+# 项目 Harness 总账 - [项目名称]
+
+> 本文件记录非平凡任务是否完成了必要的 harness 上下文回写。它不是变更日志，也不替代 Feature SSoT、Regression SSoT、Lessons SSoT 或 walkthrough。
+
+## 使用约定
+
+- 开始任务时，为需要跨文件、跨模块、跨会话或影响发布质量的工作创建一行。
+- 收口任务时，更新任务计划、审查、回归、walkthrough、Lessons 检查和残余路由。
+- 不把聊天记录当证据；证据必须指向文件、命令输出、测试报告、PR、commit 或运行时验证记录。
+- 其他 worker 同时工作时，只更新自己负责的行；共享行由协调者或明确负责人更新。
+
+## 活跃任务
+
+| Harness ID | 日期 | 任务 | 负责人 | 任务计划 | 审查 | 回归 | Walkthrough / Closeout | Lessons 检查 | 证据 | 残余路由 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| HL-YYYY-MM-DD-001 | YYYY-MM-DD | [任务名称] | [负责人] | `docs/09-PLANNING/TASKS/[task]/task_plan.md` | `review.md` / `n/a` | `Regression-SSoT: RG-...` / `n/a` | `docs/10-WALKTHROUGH/[file].md` / 允许的跳过原因 | `checked-created: L-YYYY-MM-DD-001` / `checked-none: [原因]` | [测试、命令、PR、commit 或运行时证据] | `none` / [负责人 + 路径] | [open / closed / blocked] |
+
+## 归档索引
+
+> 活跃表超过 50 行，或一次 release / wave 完成后，将 `closed`、`closed-with-residual`、`closed-local-only`、`superseded` 条目移入季度归档：`docs/01-GOVERNANCE/_archive/Harness-Ledger-archive-YYYY-QN.md`。
+
+| 归档文件 | 覆盖范围 | 移入日期 | 说明 |
+| --- | --- | --- | --- |
+| `docs/01-GOVERNANCE/_archive/Harness-Ledger-archive-YYYY-QN.md` | HL-... 至 HL-... | YYYY-MM-DD | [说明] |
+
+## 状态说明
+
+- `open`：任务仍在进行，当前行可以继续更新。
+- `blocked`：任务或上下文回写被阻塞，必须在“残余路由”写清负责人、下一步和证据。
+- `closed`：任务完成，所需上下文和证据已回写，无未路由残余。
+- `closed-with-residual`：任务完成，但仍有已接受或已路由的残余。
+- `closed-local-only`：本地工作完成但尚未合并、发布或上线；必须写清后续负责人。
+- `superseded`：本行被后续 Harness ID 取代，必须指向新行。
+
+## 字段取值
+
+- `任务计划`：填任务计划路径；轻量任务可写 `n/a: [原因]`。
+- `审查`：填审查文件、PR review、人工确认，或 `n/a: [原因]`。
+- `回归`：填触发的 Regression Gate、Cadence Ledger 批次，或 `n/a: [原因]`。
+- `Walkthrough / Closeout`：已关闭任务必须对应 `Closeout-SSoT.md` 行；实现类任务应写 walkthrough。
+- `Lessons 检查`：只能写 `checked-created: L-YYYY-MM-DD-NNN` 或 `checked-none: [一句话原因]`。
+- `残余路由`：无残余写 `none`；否则写负责人、目标文件或任务、预期处理时间。
+
+## 路由规则
+
+1. 功能进度写入 Feature SSoT，不在本表展开。
+2. 回归覆盖面、证据深度和失败项写入 Regression SSoT / Cadence Ledger。
+3. 复用性流程经验写入 Lessons SSoT，并创建 lesson 详情文档。
+4. 收口证据写入 `docs/10-WALKTHROUGH/Closeout-SSoT.md`。
+5. 任意 `closed`、`closed-with-residual`、`closed-local-only` 行都必须能从本表追溯到任务计划、证据和 closeout。

package/templates-zh-CN/lessons/lesson-arch-process-change.md

@@ -0,0 +1,47 @@
+# L-[ID]: [一句话标题]
+
+## 元信息
+
+- **ID**: L-[YYYY-MM-DD-NNN]
+- **日期**: YYYY-MM-DD
+- **来源**: `docs/10-WALKTHROUGH/[walkthrough文件名].md`
+- **类型**: arch-change / process-change
+- **目标**: [受影响的模块、流程、reference、template 或 checker]
+- **提出者**: [agent session / model / human]
+
+## 背景
+
+[说明为什么提出这个架构或流程改动。写清实际任务中遇到的问题、触发场景和影响范围，不写泛泛的原则。]
+
+## 共性问题
+
+[说明这个问题是否跨多轮、多个模块、多个 agent 或多个阶段反复出现。若不是重复问题，说明为什么仍值得沉淀为流程或架构规则。]
+
+## 现状分析
+
+[描述当前架构或流程如何工作，问题出在哪里。可以从职责边界、文件归属、review 顺序、checker 缺口、模板缺字段、并行冲突等角度分析。]
+
+## 建议方案
+
+[具体写出建议怎么改。包括新职责、新顺序、新 gate、新负责人、新文档位置或新检查方式。避免只写“加强规范”。]
+
+## 影响范围
+
+| 范围 | 影响 | 需要更新的文件 / 流程 | 负责人 |
+| --- | --- | --- | --- |
+| [模块、目录或流程] | [影响说明] | [路径或流程名] | [负责人] |
+
+## 采纳后的触发点
+
+[说明下次 agent 在什么动作点会被提醒或拦截，例如任务计划阶段、review 后、closeout 前、checker 运行时、协调者合并前。]
+
+## 验证方式
+
+[说明采纳后如何确认它真的生效：检查器、模板字段、review 清单、回归 gate、人工审查或一次试运行。]
+
+## 冲突声明
+
+- 当前是否有其他 pending 条目涉及相同范围：是 / 否
+- 如果有，涉及条目：L-[XXX]
+- 本建议是否已考虑兼容：是 / 否
+- 需要人工决策的问题：[无 / 列出]

package/templates-zh-CN/lessons/lesson-new-doc.md

@@ -0,0 +1,49 @@
+# L-[ID]: [一句话标题]
+
+## 元信息
+
+- **ID**: L-[YYYY-MM-DD-NNN]
+- **日期**: YYYY-MM-DD
+- **来源**: `docs/10-WALKTHROUGH/[walkthrough文件名].md`
+- **类型**: new-doc
+- **建议路径**: `docs/11-REFERENCE/[建议文件名].md`
+- **提出者**: [agent session / model / human]
+
+## 背景
+
+[说明为什么需要新增文档。写清在哪个任务或 walkthrough 中发现缺失，以及缺失导致了什么执行风险。]
+
+## 共性问题
+
+[说明这个缺失是否跨多轮、多个模块、多个 agent 或多个阶段反复出现。若不是重复问题，说明为什么仍值得新增正式文档。]
+
+## 现有文档为什么不够
+
+[说明为什么现有 reference、template、checker 或 SSoT 无法承载这条规则。若可以合入现有文档，应改用 `ref-change` 类型。]
+
+## 建议路径
+
+`docs/11-REFERENCE/[建议文件名].md`
+
+## 建议文档内容
+
+```markdown
+# [新文档标题]
+
+[完整的新文档内容。内容应能直接合入，不要只写提纲。]
+```
+
+## 采纳后的触发点
+
+[说明下次 agent 在什么动作点会读取或使用这份文档，例如任务计划阶段、模块拆分前、review 后、closeout 前、checker 运行时。]
+
+## 验证方式
+
+[说明新增文档如何被发现和执行：AGENTS.md 索引、checker、模板引用、review 清单或一次试运行。]
+
+## 冲突声明
+
+- 当前是否有其他 pending 条目涉及相同范围：是 / 否
+- 如果有，涉及条目：L-[XXX]
+- 本建议是否已考虑兼容：是 / 否
+- 如果不新增文档，替代方案是什么：[无 / 说明]

package/templates-zh-CN/lessons/lesson-ref-change.md

@@ -0,0 +1,59 @@
+# L-[ID]: [一句话标题]
+
+## 元信息
+
+- **ID**: L-[YYYY-MM-DD-NNN]
+- **日期**: YYYY-MM-DD
+- **来源**: `docs/10-WALKTHROUGH/[walkthrough文件名].md`
+- **类型**: ref-change
+- **目标**: `docs/11-REFERENCE/[目标文件].md`
+- **提出者**: [agent session / model / human]
+
+## 背景
+
+[说明为什么提出这个 reference 改动。写清在哪个 walkthrough 中发现问题、具体场景是什么、现有规则为什么没有让 agent 做对。]
+
+## 共性问题
+
+[说明这个问题是否跨多轮、多个文件、多个 agent 或多个阶段反复出现。若不是重复问题，说明为什么仍值得沉淀到正式 reference。]
+
+## 现行规范缺口
+
+[引用当前 reference 的相关段落或规则，说明缺口属于措辞不清、顺序错误、模板缺字段、checker 没拦住、负责人不明确，还是路由规则缺失。]
+
+## 建议改动
+
+[具体写出要改什么。可以使用 diff、前后对比或要点列表，但必须足够具体，能直接落到目标文件。]
+
+## 改动理由
+
+[说明为什么这个改动比现状更好。引用实际任务证据、review 发现、失败案例或重复返工情况。]
+
+## 采纳后的触发点
+
+[说明下次 agent 在什么动作点会被提醒或拦截，例如读 AGENTS.md 后、写任务计划时、review 后、closeout 前、checker 运行时。]
+
+## 验证方式
+
+[说明合入后如何确认它生效：模板字段、checker、review 清单、一次试运行或人工确认。]
+
+## 冲突声明
+
+- 当前是否有其他 pending 条目指向同一目标：是 / 否
+- 如果有，涉及条目：L-[XXX]
+- 本文档是否已考虑冲突：是 / 否
+- 基于版本：当前正式 reference（`docs/11-REFERENCE/[目标文件].md`）@ YYYY-MM-DD
+
+## 完整副本
+
+> 以下是修改后的完整 reference 副本。副本必须基于当前正式版本独立编写，不基于其他 pending 副本。若存在冲突，必须在“冲突声明”中说明。
+
+---
+<!-- 完整副本开始 -->
+<!-- 基于: docs/11-REFERENCE/[目标文件].md @ YYYY-MM-DD -->
+<!-- 本副本独立于其他 pending 改动 -->
+
+[完整的修改后文档内容]
+
+<!-- 完整副本结束 -->
+---

package/templates-zh-CN/planning/execution_strategy.md

@@ -0,0 +1,37 @@
+# 执行策略
+
+## 决策表
+
+| 决策 | 选择 | 说明 |
+| --- | --- | --- |
+| 主执行者 | coordinator | coordinator 负责编排顺序、冲突判断和最终收口。 |
+| Subagent 模式 | none / reviewer-only / worker-worktree | 选择能满足任务的最小协作模式。 |
+| 审查模型 | self-check / predefined verifier / adversarial review | 说明为什么该审查层级足够。 |
+| Worktree 策略 | same checkout / dedicated worktree | 会改代码的 subagent 必须使用独立 worktree，并提交 handoff commit。 |
+| 冲突控制 | coordinator owns shared files | subagent 不得直接编辑 coordinator 管理的全局表或共享文件，除非获得明确锁。 |
+| 证据深度 | L0 / L1 / L2 / L3 | 按变更风险匹配证据深度。 |
+
+## 子代理 / Worker 合同
+
+如使用 subagent 或 worker，在这里写清楚输入包、写入范围、handoff 格式和最终集成 owner。
+
+| 角色 | 输入包 | 写入范围 | 交接要求 | 负责人 |
+| --- | --- | --- | --- | --- |
+| reviewer / worker / n/a | C-001 | read-only / path list / n/a | report / commit SHA / n/a | coordinator |
+
+## 证据计划
+
+| 证据层级 | 计划命令或检查 | 记录位置 | 完成条件 |
+| --- | --- | --- | --- |
+| L0 | [静态检查 / 小范围自检] | `progress.md` | [通过标准] |
+| L1 | [单元测试 / targeted check] | `progress.md` 或 `artifacts/INDEX.md` | [通过标准] |
+| L2 | [集成 / 浏览器 / 真实数据冒烟] | `artifacts/INDEX.md` | [通过标准] |
+| L3 | [发布前 / 生产等价验证 / 外部审查] | `review.md` 与 walkthrough | [通过标准] |
+
+## 暂停 / 升级条件
+
+- 所需工作超出已批准写入范围。
+- 共享表需要更新，但没有 coordinator lock。
+- 实际风险高于原计划，证据深度需要升级。
+- reviewer 发现会改变范围或方案的 P0/P1/P2 问题。
+- 环境无法提供关键证据，继续执行会变成猜测。

package/templates-zh-CN/planning/findings.md

@@ -0,0 +1,24 @@
+# [任务名称] - 发现记录
+
+本文件记录任务执行中形成的判断、事实和技术决策。它不是审查报告；阻塞性问题请写入 `review.md`。
+
+## 研究发现
+
+### [发现主题 1]
+
+- 背景：[为什么需要调查这个问题]
+- 发现：[查到了什么事实，证据来自哪里]
+- 影响：[这会如何改变计划、范围、实现或验证]
+- 后续：[需要继续跟进的动作；如无写“无”]
+
+## 技术决策
+
+| 决策 | 选择 | 原因 | 替代方案 | 状态 |
+| --- | --- | --- | --- | --- |
+| [决策 1] | [选了什么] | [为什么这样选] | [未采用的方案] | proposed / accepted / superseded |
+
+## 待确认问题
+
+| 问题 | 当前判断 | Owner | 截止点 |
+| --- | --- | --- | --- |
+| [问题] | [当前可用判断] | [负责人] | [什么时候必须确认] |

package/templates-zh-CN/planning/long-running-task-contract.md

@@ -0,0 +1,118 @@
+# [任务名称] - 长程任务合同
+
+## 目标
+
+[一句话说明本轮要完整收掉的主问题。只保留一个主目标。]
+
+## 范围
+
+### 范围内
+
+- [允许修改的目录、模块、能力面]
+
+### 范围外
+
+- [本轮明确不做的事项]
+
+### 共享文件 / 冲突风险
+
+- [可能与其他任务冲突的共享文件；如无写“无”]
+
+## 主调用入口（Primary Caller / Entry）
+
+- 主调用方（Primary caller）：[CLI / 本地 agent / UI / API / automation / integration / 其他]
+- 本任务必须支持的入口：[列出]
+- 明确不要求的入口：[列出]
+
+## 执行授权（Execution Permission）
+
+- 是否允许连续执行（Continuous execution）：[allowed / not allowed]
+- 是否允许每轮后不再询问直接继续：[yes / no]
+- 是否允许启动审查 agent / 子代理：[yes / no]
+- 是否需要审查报告：[yes / no；如 yes，必须写 `review.md`]
+- 仍需人工批准的动作：
+  - [高风险操作，例如 destructive migration / production deploy / secret change]
+
+## 必需循环
+
+每一轮至少包含：
+
+1. 实现、编辑或配置。
+2. 本地运行。
+3. 测试、冒烟或检查。
+4. 执行 Confidence Challenge。
+5. 如合同要求审查者或子代理，更新 `review.md`。
+6. 修复 findings。
+7. 重新收集证据。
+8. 重跑 Confidence Challenge，直到没有 open 重要发现。
+9. 更新 `progress.md`。
+
+最低循环次数或无重要发现要求：
+
+- [例如：至少 2 轮；或自审 + 审查者均无重要发现]
+
+## 审查者 / 子代理合同（Reviewer / Subagent）
+
+- 审查者角色（Reviewer role）：[只读审查 / 改代码 worker / 测试验证者]
+- 审查范围（Reviewer scope）：[文件 / 模块 / 问题域]
+- 如果是 code-change worker：
+  - Worktree path：[路径 / 不适用]
+  - Branch：[分支 / 不适用]
+  - 任务目录：[路径 / 不适用]
+  - 交接前提交（Commit before handoff）：[yes / no / 不适用]
+  - 交接必须包含：[worktree path / branch / commit SHA / checks / residual risks]
+- Reviewer 必须报告：
+  - [缺陷]
+  - [回归]
+  - [缺失测试]
+  - [未验证假设]
+  - [`review.md` 中的重要发现或无重要发现声明]
+- Reviewer 不得：
+  - [越权改动 / 重写不相关模块 / 擅自扩大 scope]
+
+## 证据
+
+完成前必需证据：
+
+- [ ] [lint / typecheck / build command]
+- [ ] [unit / integration / e2e test command]
+- [ ] [本地冒烟命令]
+- [ ] [浏览器 / UI / 人工检查]
+- [ ] [线上环境冒烟]
+- [ ] [审查者无重要发现]
+- [ ] [如要求审查，`review.md` 已完成]
+- [ ] [walkthrough / PR / 发布说明]
+
+## 完成条件（Stop Condition）
+
+任务只有在以下条件满足后才可停止并声明完成：
+
+- [ ] [关键路径通过]
+- [ ] [必需测试或回归门禁通过]
+- [ ] [runtime / console / request 错误已清除，或已记录为非阻塞残余]
+- [ ] [如要求审查者，审查者无 open 重要发现]
+- [ ] [如要求审查，`review.md` 无 open P0/P1 发现]
+- [ ] [残余风险已记录，且不阻塞本轮目标]
+
+## 暂停条件（Pause Conditions）
+
+遇到以下情况必须暂停并汇报：
+
+- [ ] 目标或范围已经失效。
+- [ ] 需要高风险的产品、架构、安全或数据决策。
+- [ ] 未知的无关改动与本任务冲突。
+- [ ] 环境阻断了所有有用证据的收集。
+- [ ] 审查者发现改变了任务方向。
+
+## 交付物（Deliverables）
+
+- [ ] 代码 / 配置改动
+- [ ] 测试 / 回归证据
+- [ ] 文档更新
+- [ ] 如要求审查，`review.md` 报告
+- [ ] `progress.md` / `findings.md` 更新
+- [ ] Harness Ledger 更新
+- [ ] 收口记录
+- [ ] Lessons 反思与检查（`checked-created` 或 `checked-none`）
+- [ ] PR / commit / 发布说明
+- [ ] 残余风险摘要

package/templates-zh-CN/planning/module_plan.md

@@ -0,0 +1,43 @@
+# [模块名] Module Plan
+
+## 基本信息
+
+- Key：[module key]
+- PREFIX：[step ID prefix]
+- Branch：[长期分支名，例如 `codex/reader`]
+- 写入范围：[该模块可修改的目录或文件范围]
+- Shared surfaces：[与其他模块共享、需要协调的文件或能力面；无则写“无”]
+
+## 步骤序列
+
+| 步骤 ID | 名称 | 状态 | 任务计划 | 依赖 |
+| --- | --- | --- | --- | --- |
+| XXX-01 | [步骤名] | planned | — | — |
+| XXX-02 | [步骤名] | planned | — | XXX-01 |
+
+## 执行与可视化文件
+
+模块级 `execution_strategy.md` 和 `visual_roadmap.md` 应放在本模块目录，与 `module_plan.md` 同级，不嵌入本文件。
+
+| 合同文件 | 是否必需 | 用途 |
+| --- | --- | --- |
+| `execution_strategy.md` | yes | 模块执行模式、写入边界、subagent 使用、全局同步 owner、验证深度 |
+| `visual_roadmap.md` | yes | 模块阶段图、状态、完成度、证据状态、阻塞风险 |
+
+旧模块目录可以保留历史嵌入式段落作为 fallback；新模块目录必须使用独立文件。
+
+## 状态定义
+
+- `planned`：尚未开始
+- `in-progress`：正在开发
+- `done`：已完成并合并
+- `blocked`：被依赖或外部条件阻塞
+- `superseded`：已被其他步骤替代
+
+## 当前状态
+
+[用 1-3 句话描述当前进度，供新会话快速接手。每次会话结束时更新。]
+
+## 完成标准
+
+[写清模块整体完成条件。所有步骤 `done` 不等于模块完成，可能仍需集成测试、性能验证、文档收口或 coordinator 同步。]

package/templates-zh-CN/planning/module_session_prompt.md

@@ -0,0 +1,70 @@
+# 模块会话提示词（Module Session Prompt）
+
+用于为模块并行项目启动一个长程模块会话。交给新 agent 前，coordinator 必须先用真实项目事实替换占位符。
+
+```text
+你正在 <repo-path> 中处理 <module-key> 模块。
+
+子代理 worker 不变量：
+- 如果这个提示词被交给会改代码的 worker 子代理，coordinator 必须先分配独立 worktree 和分支。
+- Worker 只能在 <worktree-path> 内编辑，必须提交自己的改动，并交接 worktree path、branch、commit SHA、checks、residual risks。
+- Reviewer 子代理默认只读；除非明确升级为 worker，并遵守同一套 worktree 合同。
+- Coordinator 负责集成 worker commit 并运行最终门禁；不要在一个 checkout 中混合多个 worker 的未提交改动。
+
+目标：
+- 执行 docs/09-PLANNING/Module-Registry.md 与 docs/09-PLANNING/MODULES/<module-key>/module_plan.md 中为 <module-key> 标记的当前步骤。
+- 除非触发 stop condition，否则持续推进到该步骤已实现、已验证、已记录，并可进入审查。
+
+冷启动：
+1. 阅读 AGENTS.md。
+2. 阅读 docs/09-PLANNING/Module-Registry.md。
+3. 阅读 docs/09-PLANNING/MODULES/Session-Prompt-Pack.md 或 docs/09-PLANNING/MODULES/<module-key>/session_prompt.md。
+4. 阅读 docs/09-PLANNING/MODULES/<module-key>/module_plan.md。
+5. 按项目任务阅读矩阵读取本任务涉及文件对应的标准文档。
+
+启动门禁：
+- 确认 registry 中 <module-key> 的 branch、current step、status、write scope 与本 prompt 一致。
+- 确认当前 checkout/worktree path 是 <worktree-path>，当前分支是 <branch-name>。
+- 编辑前检查 dirty state，不要 revert 无关改动。
+- 如果另一个活跃会话拥有该模块或必需共享文件，停止并记录冲突。
+- 代码编辑前，基于项目 planning 模板创建或更新 docs/09-PLANNING/MODULES/<module-key>/TASKS/<current-step>-<short-name>/task_plan.md，写清范围、验收、验证、分支/worktree 和共享协调。
+- 代码编辑前，确认模块任务目录含有 `execution_strategy.md` 与 `visual_roadmap.md`。如缺失，先补齐再实现。
+- 如果 docs/09-PLANNING/MODULES/<module-key>/ 缺少模块级 `execution_strategy.md` 或 `visual_roadmap.md`，在派发 worker 前补齐或更新。
+
+分支与工作树：
+- Worktree path: <worktree-path>.
+- Branch: <branch-name>.
+- Base branch: <base-branch>.
+- Remote: <remote-name>.
+- 只在 <module-key> 的模块 worktree 中工作。若 worktree 不存在，按项目 worktree 标准创建。
+
+写入范围：
+- 允许：<module-write-scope>.
+- 未明确协调前禁止：<shared-or-forbidden-scope>.
+- 共享协调产物：docs/09-PLANNING/MODULES/_shared/TASKS/<id>/task_plan.md，或模块任务计划中的“共享协调”段，必须写明 owner、涉及文件、允许改动、reviewer 和 merge 顺序。
+- 如果实现需要触碰允许范围之外的文件，停止并记录所需协调，不要直接编辑。
+
+验证：
+- Project harness check: <project-harness-check-command>.
+- 运行模块 targeted checks: <targeted-checks>.
+- 改动代码或 UI 行为时，运行 lint/build/smoke checks。
+- 将精确命令和结果记录到模块任务 progress 或 walkthrough。
+
+收口：
+- 更新模块计划和模块任务进度。
+- 除非 coordinator 明确分配共享锁，worker session 不得更新 docs/09-PLANNING/Module-Registry.md、docs/Harness-Ledger.md、Closeout SSoT、Regression SSoT 或 Cadence Ledger。
+- 如果需要全局表更新，在 task_plan.md 或 progress.md 写 Coordinator 交接，并标记 `Global sync status: pending-coordinator-pass`。
+- 只有 coordinator pass 或明确的 shared-lock owner 可以更新 docs/09-PLANNING/Module-Registry.md。
+- 更新 docs/09-PLANNING/MODULES/<module-key>/module_plan.md。
+- 写 review.md，或记录 review skipped-with-reason。
+- 步骤完成时写 walkthrough，并包含 Lessons 反思。
+- Coordinator pass 在任务关闭时更新 Closeout SSoT 和 Lessons 检查。
+- Coordinator pass 在行为、测试、架构或流程改变时更新 Regression SSoT 和 Harness Ledger。
+- 验证未通过前不得声明完成；无法解决的残余必须记录 owner 和原因。
+
+暂停条件：
+- 必需工作超出模块写入范围，且尚未选择 owner。
+- 用户数据或私密数据需要被提交。
+- 回归检查失败，且根因在本模块之外。
+- 任务需要 module plan 中没有写明的产品范围变更。
+```

package/templates-zh-CN/planning/optional/artifacts/INDEX.md

@@ -0,0 +1,13 @@
+# 任务产物索引
+
+仅在任务产生较多证据或大体量产物时使用，例如命令输出、截图、fixture、生成报告、review transcript、导出的数据文件等。核心任务文件只引用这里的 ID，不粘贴长输出。
+
+| ID | 类型 | 路径 | 摘要 | Produced By |
+| --- | --- | --- | --- | --- |
+| ART-001 | command / diff / fixture / screenshot / review / report | PUBLIC:path 或 PRIVATE:path 或 TARGET:path 或 EXTERNAL:path 或 URL:https://example.com | [该产物证明了什么] | coordinator |
+
+## 使用规则
+
+- 路径必须可复查；临时终端输出应先保存为稳定文件再登记。
+- 产物如果包含敏感信息，先脱敏或改为记录复查方式，不要提交原始敏感内容。
+- 与 `review.md`、`progress.md`、walkthrough 互相引用时，使用 `ART-xxx` ID。

package/templates-zh-CN/planning/optional/references/INDEX.md

@@ -0,0 +1,13 @@
+# 任务参考资料索引
+
+仅在任务需要外部资料、跨仓上下文、reviewer 输入包或生成参考材料时使用。不要把无关背景资料堆进来。
+
+| ID | 类型 | 路径 | 摘要 | Used By |
+| --- | --- | --- | --- | --- |
+| REF-001 | public-doc / private-plan / external / code | PUBLIC:path 或 PRIVATE:path 或 TARGET:path 或 EXTERNAL:path 或 URL:https://example.com | [这份资料为什么影响本任务] | coordinator |
+
+## 使用规则
+
+- 每条参考资料都要说明用途，否则不要登记。
+- 外部链接需要写清访问日期或版本线索，避免后续复查时语境漂移。
+- reviewer 或 worker 只应读取与其 scope 相关的条目。

package/templates-zh-CN/planning/optional/slices/_slice-template/brief.md

@@ -0,0 +1,35 @@
+# 切片简报
+
+## 切片 ID
+
+SL-001
+
+## 所属阶段（Parent Phase）
+
+| 父阶段 ID | 依赖 | 状态 | 负责人 / 交接 |
+| --- | --- | --- | --- |
+| PH-01 | none | planned | coordinator |
+
+## 目标
+
+[说明该切片完成后交付什么可验证结果。]
+
+## 范围
+
+- 允许写入：[目录、文件或能力面]
+- 明确排除：[不属于本切片的内容]
+- 共享协调：[涉及共享文件时写 owner、锁和 merge 顺序；如无写“无”]
+
+## 输入（Inputs）
+
+- [引用 `references/INDEX.md`、`artifacts/INDEX.md`、任务计划或上游切片 ID]
+
+## 必需证据
+
+- [ ] [该切片关闭前必须提供的命令、diff、截图、review 或报告]
+
+## 关闭条件
+
+- [ ] 范围内工作完成。
+- [ ] 必需证据已登记到 `evidence.md`。
+- [ ] 如需审查，`review.md` 无 open blocking finding。

package/templates-zh-CN/planning/optional/slices/_slice-template/evidence.md

@@ -0,0 +1,12 @@
+# 切片证据
+
+| 证据 ID | 类型 | 路径 | 摘要 | 状态 |
+| --- | --- | --- | --- | --- |
+| E-001 | command / diff / fixture / screenshot / review / report | PUBLIC:path 或 PRIVATE:path 或 TARGET:path 或 EXTERNAL:path 或 URL:https://example.com | [这份证据证明了什么] | missing |
+
+## 状态说明
+
+- `missing`：证据尚未收集。
+- `partial`：已有部分证据，但不足以关闭切片。
+- `present`：证据完整，可复查。
+- `waived`：证据被明确豁免，并有原因。

package/templates-zh-CN/planning/optional/slices/_slice-template/review.md

@@ -0,0 +1,37 @@
+# 切片审查
+
+本文件只记录当前切片的审查结论。任务级发布判断仍以任务目录根部的 `review.md` 为准。
+
+## 审查者身份（Reviewer Identity）
+
+| Reviewer | Type | Scope |
+| --- | --- | --- |
+| [name] | self / subagent / external / human | [切片范围] |
+
+## 信心挑战（Confidence Challenge）
+
+直接回答：你是否对这个切片有 100% 信心？
+
+- Verdict：yes / no
+- 如果不是 100%，列出剩余漏洞和修复建议。
+
+## 重要发现（Material Findings）
+
+| ID | Severity | Finding | Evidence Checked | Required Action | Open | Disposition | Blocks Release | Follow-up |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+不要保留示例 finding。若没有重要发现，只保留表头，并补全 Final Confidence Basis。
+
+## 已检查证据（Evidence Checked）
+
+| Evidence ID | Type | Path | Summary |
+| --- | --- | --- | --- |
+| SE-001 | command / file / runtime | [路径或命令] | [检查了什么，结论是什么] |
+
+## 残余风险
+
+- [切片级残余风险；如无写“无”]
+
+## 最终信心依据（Final Confidence Basis）
+
+[说明为什么这个切片可以合并，或写清剩余限制和负责人。]

package/templates-zh-CN/planning/progress.md

@@ -0,0 +1,29 @@
+# [任务名称] - 进度
+
+## 状态：未开始
+
+## 进度记录
+
+证据使用 `type:path:summary` 格式。
+
+允许的 `type`：`command`, `diff`, `fixture`, `screenshot`, `review`, `report`。
+
+证据较长或数量较多时，不要粘贴全文；放入 `artifacts/INDEX.md` 并在这里引用 ID。
+
+### [YYYY-MM-DD HH:MM] - [阶段名称]
+
+- 做了什么：[具体操作]
+- 验证结果：[运行了什么检查，结果如何]
+- 下一步：[下一步动作]
+- 证据：[type:path:summary]
+
+## 残余
+
+- [遗留问题；如无写“无”]
+
+## 协调者交接（Coordinator，启用模块并行时填写）
+
+- Global sync status：pending-coordinator-pass / synced / n/a
+- Registry update needed：[module key, step, status, branch, updated / 不适用]
+- Harness Ledger update needed：[task plan path, review path, closeout status / 不适用]
+- 负责人：coordinator / 不适用