coding-agent-harness 1.0.1 → 1.0.4

package/templates-zh-CN/development/external-context/service-template.md

@@ -0,0 +1,33 @@
+# 外部服务开发上下文：<service-key> / External Development Context: <service-key>
+
+Context Doc Type: external-development-context
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Index Links
+
+| Service Profile | Source Pack | Integration Contracts | Last Verified | Confidence |
+| --- | --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/services/<service-key>.md` | `docs/04-DEVELOPMENT/external-source-packs/<source-key>/README.md` 或 N/A | `docs/06-INTEGRATIONS/<contract>.md` | unknown | low |
+
+## Development Use
+
+[说明 Agent 修改本仓时需要知道的外部服务事实。只写可验证事实、mock 方式和调试入口。]
+
+## Do Not Assume
+
+- [未查看外部仓库或未问负责人前不能成立的假设。]
+
+## Mocks / Stubs
+
+| Scenario | Stub / Mock | Command or Path | Source Evidence |
+| --- | --- | --- | --- |
+
+## Cross-Repo Debug Notes
+
+[当问题涉及这个外部服务时，按什么顺序定位、用哪些命令或日志确认。]
+
+## Placement Rule
+
+本文件只写本仓开发、测试、调试这个外部服务时需要的上下文。服务职责放 `03-ARCHITECTURE`，接口字段和 schema 放 `06-INTEGRATIONS`。

package/templates-zh-CN/development/external-source-packs/README.md

@@ -0,0 +1,24 @@
+# 外部资料包索引 / External Source Packs
+
+Context Doc Type: external-source-pack-registry
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Purpose
+
+这个目录只承载外部资料的摄取、索引和摘要。稳定事实必须投影到 `03-ARCHITECTURE`、`04-DEVELOPMENT/external-context` 或 `06-INTEGRATIONS` 后才算进入 Harness 执行上下文。
+
+先读 `docs/11-REFERENCE/external-source-intake-standard.md`，再新增资料包。
+
+## Source Packs
+
+| Source Key | External Project / Service | Raw Storage Mode | Source Count | Digest Status | Projected To 03/04/06 | Owner | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+## Placement Rule
+
+- 资料量小于 5 份时，优先在 `03/04/06` 的 `Source Evidence` 中引用，不必建资料包。
+- 资料很多、跨多个主题或会持续增长时，创建 `<source-key>/README.md` 和 `digests/`。
+- `raw/` 只能放允许入仓、无密钥、无隐私、无客户数据的原始材料。
+- 不能入仓的资料只记录外部路径、owner、访问条件和 digest。

package/templates-zh-CN/development/external-source-packs/digest-template.md

@@ -0,0 +1,28 @@
+# 外部资料摘要：<source-id> / External Source Digest: <source-id>
+
+Context Doc Type: external-source-digest
+Source Pack: <source-key>
+Original Location: <path-or-url-or-owner>
+Digest Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Source Summary
+
+[用 5-10 行说明原始资料是什么、覆盖范围、可信度和更新时间。]
+
+## Extracted Facts
+
+| Fact ID | Fact | Category | Project To | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- |
+| F-001 | [可验证事实] | architecture / development / integration / security / operations / product / unknown | `docs/...` 或 hold | <source-id> | unknown | low |
+
+## Questions / Unsafe Assumptions
+
+| ID | Question Or Assumption | Why It Matters | Owner | Status |
+| --- | --- | --- | --- | --- |
+
+## Projection Status
+
+| Target Doc | Action | Status | Evidence |
+| --- | --- | --- | --- |

package/templates-zh-CN/development/local-setup.md

@@ -0,0 +1,16 @@
+# 本地启动 / Local Setup
+
+Context Doc Type: local-setup
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Commands
+
+| Task | Command | Expected Result | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- |
+
+## Environment
+
+| Variable | Required | Purpose | Source Evidence |
+| --- | --- | --- | --- |

package/templates-zh-CN/development/stubs-and-mocks.md

@@ -0,0 +1,11 @@
+# Stub 与 Mock / Stubs and Mocks
+
+Context Doc Type: stubs-and-mocks
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Available Stubs
+
+| External Service | Scenario | Stub Path | How To Run | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- |

package/templates-zh-CN/integrations/README.md

@@ -0,0 +1,42 @@
+# 接口契约 / Integrations
+
+Context Doc Type: integration-index
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Purpose
+
+这个文件夹只放具体接口契约：API、event、webhook、SDK、第三方集成、auth、payload、error 和 contract tests。
+
+Keep the English field names and section headings because CLI checks rely on them.
+
+## Boundary
+
+- 服务拓扑和职责归属放 `docs/03-ARCHITECTURE/`。
+- 开发 mock 和调试说明放 `docs/04-DEVELOPMENT/`。
+- endpoint、payload、error、auth、event、webhook、SDK 契约放这里。
+
+## Structure Contract
+
+| 文件 / 路径 | 必须维护的事实 | 写入规则 |
+| --- | --- | --- |
+| `<service-key>-api.md` | API endpoint、auth、payload、error、contract test | 从 `api-contract.md` 创建 |
+| `<event-name>-event.md` | event producer/consumer、schema、delivery、retry | 从 `event-contract.md` 创建 |
+| `<webhook-name>-webhook.md` | webhook source、target、signature、payload、retry | 从 `webhook-contract.md` 创建 |
+| `third-party/<vendor-key>.md` | 第三方平台、账号/权限边界、SDK 使用、限制 | 从 `third-party/vendor-template.md` 创建 |
+
+## Contract Rule
+
+每个接口契约必须是独立文件，并链接回对应服务：
+
+- 服务职责和上下游关系：`docs/03-ARCHITECTURE/service-catalog.md` 或 `services/<service-key>.md`
+- 本地 mock / stub / debug：`docs/04-DEVELOPMENT/external-context/<service-key>.md`
+- 具体 payload、auth、error、contract test：本文件夹
+
+不要在一个“接口说明”大文档里混写多个服务。多个微服务就维护多个契约文件；README 里的 Contract Index 负责让人和 Agent 快速定位。
+
+## Contract Index
+
+| Contract | Type | Producer | Consumer | Service Profile | Development Context | Contract Tests | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |

package/templates-zh-CN/integrations/api-contract.md

@@ -0,0 +1,42 @@
+# API 契约：<service-or-api> / API Contract: <service-or-api>
+
+Context Doc Type: api-contract
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Contract Type
+
+API
+
+## Index Links
+
+| Service Profile | Development Context | Contract Index | Last Verified | Confidence |
+| --- | --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/services/<service-key>.md` | `docs/04-DEVELOPMENT/external-context/<service-key>.md` | `docs/06-INTEGRATIONS/README.md` | unknown | low |
+
+## Auth
+
+[认证和授权要求。不要写入真实密钥。]
+
+## Endpoints
+
+| Method | Path | Purpose | Request Payload | Response Payload | Errors | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+## Payload
+
+[请求/响应 schema，或指向 schema 的路径。]
+
+## Errors
+
+[错误码、重试规则、用户可见行为。]
+
+## Contract Tests
+
+| Test | Command / Path | Expected Result |
+| --- | --- | --- |
+
+## Placement Rule
+
+本文件只写一个 API 契约。服务职责放 `03-ARCHITECTURE`，本地 mock/stub/debug 放 `04-DEVELOPMENT`。

package/templates-zh-CN/integrations/event-contract.md

@@ -0,0 +1,46 @@
+# 事件契约：<event-name> / Event Contract: <event-name>
+
+Context Doc Type: event-contract
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Contract Type
+
+Event
+
+## Index Links
+
+| Service Profile | Development Context | Contract Index | Last Verified | Confidence |
+| --- | --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/services/<service-key>.md` | `docs/04-DEVELOPMENT/external-context/<service-key>.md` | `docs/06-INTEGRATIONS/README.md` | unknown | low |
+
+## Topic / Channel
+
+[Queue、topic、stream 或 bus。]
+
+## Auth
+
+[生产者/消费者权限、签名或访问控制。没有也要写 N/A 和证据。]
+
+## Payload
+
+[事件 schema 或 schema 路径。]
+
+## Producers and Consumers
+
+| Role | Service | Responsibility | Source Evidence |
+| --- | --- | --- | --- |
+
+## Errors
+
+[Dead-letter、retry、兼容性策略。]
+
+## Contract Tests
+
+| Test | Command / Path | Expected Result |
+| --- | --- | --- |
+
+## Placement Rule
+
+本文件只写一个 event 契约。服务职责放 `03-ARCHITECTURE`，本地 mock/stub/debug 放 `04-DEVELOPMENT`。

package/templates-zh-CN/integrations/third-party/vendor-template.md

@@ -0,0 +1,42 @@
+# 第三方集成：<vendor> / Third-Party Integration: <vendor>
+
+Context Doc Type: third-party-integration
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Contract Type
+
+Third-party service
+
+## Index Links
+
+| Service Profile | Development Context | Contract Index | Last Verified | Confidence |
+| --- | --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/services/<vendor-key>.md` | `docs/04-DEVELOPMENT/external-context/<vendor-key>.md` | `docs/06-INTEGRATIONS/README.md` | unknown | low |
+
+## Auth
+
+[凭证与权限模型。不要写入真实密钥。]
+
+## API / SDK Surface
+
+| Surface | Purpose | Contract Link | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- |
+
+## Payload
+
+[重要请求/响应体，或相关 schema 路径。]
+
+## Errors
+
+[供应商错误、额度限制、重试和降级策略。]
+
+## Contract Tests
+
+| Test | Command / Path | Expected Result |
+| --- | --- | --- |
+
+## Placement Rule
+
+本文件只写一个第三方集成。账号/权限/SDK/限制放这里；业务职责和系统拓扑放 `03-ARCHITECTURE`。

package/templates-zh-CN/integrations/webhook-contract.md

@@ -0,0 +1,41 @@
+# Webhook 契约：<webhook-name> / Webhook Contract: <webhook-name>
+
+Context Doc Type: webhook-contract
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Contract Type
+
+Webhook
+
+## Index Links
+
+| Service Profile | Development Context | Contract Index | Last Verified | Confidence |
+| --- | --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/services/<service-key>.md` | `docs/04-DEVELOPMENT/external-context/<service-key>.md` | `docs/06-INTEGRATIONS/README.md` | unknown | low |
+
+## Auth
+
+[签名、token、IP allowlist 或其他认证方式。不要写入真实密钥。]
+
+## Payload
+
+[Webhook body schema 或 schema 路径。]
+
+## Source Evidence
+
+[代码、供应商文档、负责人说明或发现命令。]
+
+## Errors
+
+[重试、超时、幂等行为。]
+
+## Contract Tests
+
+| Test | Command / Path | Expected Result |
+| --- | --- | --- |
+
+## Placement Rule
+
+本文件只写一个 webhook 契约。服务职责放 `03-ARCHITECTURE`，本地 mock/stub/debug 放 `04-DEVELOPMENT`。

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

@@ -1,50 +1,27 @@
-# 项目 Harness 总账 - [项目名称]
+# 项目总账
 
-> 本文件记录非平凡任务是否完成了必要的 harness 上下文回写。它不是变更日志，也不替代 Feature SSoT、Regression SSoT、Lessons SSoT 或 walkthrough。
+## 用途
 
-## 使用约定
+本文件是自动生成的任务生命周期总索引。人类查看当前状态应优先使用 Dashboard；Agent 快速检索应使用 `task-list`、`task-index` 或这张 generated ledger。
 
-- 开始任务时，为需要跨文件、跨模块、跨会话或影响发布质量的工作创建一行。
-- 收口任务时，更新任务计划、审查、回归、walkthrough、Lessons 检查和残余路由。
-- 不把聊天记录当证据；证据必须指向文件、命令输出、测试报告、PR、commit 或运行时验证记录。
-- 其他 worker 同时工作时，只更新自己负责的行；共享行由协调者或明确负责人更新。
+本文件不是手写工作日志。不要手工编辑生命周期行。需要改变事实时，更新任务本地文件（`task_plan.md`、`progress.md`、`review.md`、`lesson_candidates.md`、closeout / walkthrough 证据），然后运行 `harness governance rebuild --archive --apply`。
 
-## 活跃任务
+Repo Governance / CI-CD 变化仍通过对应 reference 和任务证据路由。Regression gate、交付顺序、回归节奏、closeout 合同和模块所有权继续保留在各自治理文件中，除非未来提供等价的 scanner-supported fact。
 
-| 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 取代，必须指向新行。
+| ID | Scope | Module | Task | State | Queues | Plan | Review | Lessons Check | Closeout | Residual | Updated |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| HL-YYYY-MM-DD-001 | task | none | 短任务标题 | planned | none | docs/09-PLANNING/TASKS/.../task_plan.md | pending | pending | pending | none | YYYY-MM-DD |
 
-## 字段取值
+## 字段规则
 
-- `任务计划`：填任务计划路径；轻量任务可写 `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`；否则写负责人、目标文件或任务、预期处理时间。
+- `Scope`：根 planning 任务为 `task`，模块内任务为 `module`。
+- `Module`：模块 key；非模块任务写 `none`。
+- `Queues`：scanner 派生的生命周期队列；用 `harness task-list --queue` 查询。
+- `Review`、`Lessons Check`、`Closeout`、`Residual`：scanner 派生摘要和路由；详细证据留在任务本地文件。
+- `Updated`：生成日期，不是人工编辑时间。
 
-## 路由规则
+## 旧表
 
-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。
+`Feature-SSoT.md` 和 `Private-Feature-SSoT.md` 是旧任务生命周期投影。当前 Harness 版本在 `harness governance rebuild --archive --apply` 时归档它们，不再重新生成。

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

@@ -0,0 +1,32 @@
+# {{TASK_TITLE}}
+
+## Brief
+
+## Task ID
+
+`{{TASK_ID}}`
+
+## 创建日期
+
+{{DATE}}
+
+## 目标结果
+
+说明这个任务完成后，用户或项目能直接看到的结果。
+
+## 边界
+
+- 范围内：本任务允许修改的文件、行为、文档或验证内容。
+- 范围外：不能顺手塞进来的工作。
+- 停止条件：遇到不确定性、风险或缺少权限时，必须回到 coordinator 或用户确认。
+
+## 执行合同
+
+- Owner：coordinator
+- 生命周期状态：未开始
+- 必需文件：`task_plan.md`、`execution_strategy.md`、`visual_map.md`、`progress.md`、`findings.md`、`review.md`
+- 完成条件：验证证据必须记录到 `progress.md`
+
+## 第一步
+
+开始实现前，把这里替换成第一个具体动作。

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

@@ -1,5 +1,35 @@
 # 执行策略
 
+## Subagent Authorization
+
+任务开始时先读这一段，并向用户说明当前授权状态。这里是授权记录，不是执行沙箱。
+
+| Role | Status | Permission | Authorized By | Authorized At | Scope | Worktree / Branch | Reuse |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| reviewer subagent | allowed by default | read-only | harness task policy | task creation | current task review | n/a | allowed within this task |
+| worker subagent | not authorized | write only after user approval | pending | pending | pending | pending | allowed only within approved task/scope |
+
+## Subagent Delegation Decision
+
+任务开始时，coordinator 必须根据用户目标主动做这个判断，即使用户完全没有提到 subagent。
+不要假设用户知道 subagent 或 worker 是什么。如果分工有帮助，用白话说明收益，并向用户申请一次授权。
+可以直接对用户说 subagent 或 worker subagent；关键规则是 agent 不能等用户主动提出 subagent。
+如果任务已经明显拆成互不重叠的独立切片，implementation 前就应判断为 `ask-user`。如果还不知道精确文件路径，先确认路径，然后立刻申请独立执行助手授权。
+
+| Question | Decision | Reason | Next Action |
+| --- | --- | --- | --- |
+| Should a reviewer subagent be used? | yes / no | [为什么需要或不需要 reviewer] | 如果 yes，直接调用只读 reviewer，不需要额外申请。 |
+| Would a worker subagent materially help? | no / ask-user / already-authorized | [并行切片、独立实现、专项调查，或说明为什么不需要] | 如果 ask-user，直接问：“这个任务适合拆给 worker subagent 并行处理。是否授权我派一个 worker subagent，只修改 [scope]，只在 [worktree/branch] 内执行，我负责协调和最终审查？” |
+
+## User Authorization Decision
+
+如果上方 worker 决策是 `ask-user`，implementation 必须暂停，直到这里记录用户答案。
+已解决状态只能是 `authorized`、`denied` 或 `not-needed`。选择 `ask-user` 后不得继续保持 `pending`。
+
+| Gate | State | Decided By | Decided At | Scope | Worktree / Branch | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| worker subagent | pending | pending | pending | pending | pending | 只有直接问过用户后才能填写。 |
+
 ## 决策表
 
 | 决策 | 选择 | 说明 |

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

@@ -0,0 +1,70 @@
+# {{TASK_TITLE}} - 教训候选
+
+本文件是任务本地 lesson candidate queue。人工审查需要决定候选是留在任务内、拒绝、进入 dry-run promotion、创建 promoted lesson 详情文档，还是创建单独的沉淀任务。
+
+## Candidate Status
+
+| Field | Value |
+| --- | --- |
+| Schema version | lesson-candidate-v1 |
+| Task-level status | pending-review |
+| Review gate | candidate-file-present |
+| Review decision | pending-human-review |
+| Promotion state | not-promoted |
+| Closeout token | pending |
+| Source task | {{TASK_ID}} |
+| Owner | coordinator |
+| Last updated | {{DATE}} |
+
+## Schema
+
+允许的任务级状态：
+
+- `missing`：候选文件不存在。
+- `pending-review`：候选文件存在，但人工判定还没完成。
+- `no-candidate-accepted`：人工接受本任务没有可复用候选的理由。
+- `needs-promotion`：至少一个候选已排队等待治理沉淀。
+- `promoted`：所有接受的候选都已写入已确认的治理目标。
+- `rejected`：所有候选都已带理由拒绝或归档。
+
+允许的行级状态：
+
+- `ready-for-review`：agent 认为这个候选可能有复用价值。
+- `needs-promotion`：人工标记这个候选值得通过 dry-run promotion 或后续沉淀任务保留。
+- `promoted`：维护 CLI 或已批准的后续任务已把候选写入确认的治理目标。
+- `rejected`：人工带理由拒绝这个候选。
+
+聚合规则：
+
+- 任意 `ready-for-review` 行会让任务级状态保持 `pending-review`。
+- 任意 `needs-promotion` 行会让任务级状态变成 `needs-promotion`，除非仍有 `ready-for-review` 行。
+- 全部行都是 `promoted` 时，任务级状态为 `promoted`。
+- 全部行都是 `rejected` 时，任务级状态为 `rejected`。
+- 没有候选的任务必须使用 `no-candidate-accepted`，并填写 `No-Candidate Reason`。
+
+## Candidates
+
+| ID | Row Status | Title | Scope | Module Key | Detail Artifact | Boundary Reason | Why It Might Matter | Review Decision | Promotion Target | Conflict Check | Required Standard Update | Follow-up Task |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+## No-Candidate Reason
+
+尚未判定。只有人工审查接受本任务没有可复用候选时，才填写这里。
+
+## Promotion Notes
+
+- 如果人工审查认为候选值得沉淀，把对应行标记为 `needs-promotion`，并记录目标治理位置。
+- 候选标记为 `needs-promotion` 时，必须趁源任务上下文还新鲜写出完整 task-local detail artifact，并在 `Detail Artifact` 中链接。
+- `Scope` 使用 `task`、`module` 或 `global`；module 级候选必须填写 `Module Key`。
+- 如果人工审查拒绝候选，把对应行标记为 `rejected`，并在 review decision 中保留理由。
+- `needs-promotion` 不阻止任务 closeout，但必须继续出现在维护队列和收口记录里。
+- 默认 promotion 行为是先 dry-run 或创建后续沉淀任务。不要写共享 Lessons 表；被接受的候选应成为 promoted lesson 详情文档。
+- 沉淀任务必须先分类 scope、检查既有 lessons 和 standards 冲突、提出目标改动，并在 apply 前报告验证证据。
+
+## Queue Routing
+
+| Queue | When this task enters it | Exit condition |
+| --- | --- | --- |
+| Lessons | 任意候选是 `ready-for-review` 或 `needs-promotion`。 | 人工拒绝、保留在任务内、创建沉淀任务或批准 promotion。 |
+| Missing Materials | 文件缺失、状态非法，或缺少必需的 no-candidate reason。 | Agent 修复候选文件。 |
+| Confirmed / Finalized | 已人工确认，但候选仍有延后的治理事项。 | 记录后续任务或 dry-run 决策。 |

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

@@ -113,6 +113,6 @@
 - [ ] `progress.md` / `findings.md` 更新
 - [ ] Harness Ledger 更新
 - [ ] 收口记录
-- [ ] Lessons 反思与检查（`checked-created` 或 `checked-none`）
+- [ ] Lessons 反思与检查：`lesson_candidates.md` 已进入 `no-candidate-accepted` / `needs-promotion` / `promoted` / `rejected`
 - [ ] PR / commit / 发布说明
 - [ ] 残余风险摘要

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

@@ -0,0 +1,25 @@
+# {{TASK_TITLE}} 模块
+
+## Brief
+
+## 模块 Key
+
+`{{TASK_ID}}`
+
+## 创建日期
+
+{{DATE}}
+
+## 模块职责
+
+说明这个模块负责什么，以及为什么需要独立管理。
+
+## 边界
+
+- 负责：本模块拥有的目录、服务或文档区域。
+- 共享面：需要 coordinator 同步的文件。
+- 不负责：相邻模块或未声明的全局文件。
+
+## 当前工作
+
+列出当前模块任务，或指向 `module_plan.md`。

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

@@ -17,12 +17,12 @@
 
 ## 执行与可视化文件
 
-模块级 `execution_strategy.md` 和 `visual_roadmap.md` 应放在本模块目录，与 `module_plan.md` 同级，不嵌入本文件。
+模块级 `execution_strategy.md` 和 `visual_map.md` 应放在本模块目录，与 `module_plan.md` 同级，不嵌入本文件。
 
 | 合同文件 | 是否必需 | 用途 |
 | --- | --- | --- |
 | `execution_strategy.md` | yes | 模块执行模式、写入边界、subagent 使用、全局同步 owner、验证深度 |
-| `visual_roadmap.md` | yes | 模块阶段图、状态、完成度、证据状态、阻塞风险 |
+| `visual_map.md` | yes | 模块图表集合、阶段图、状态、完成度、证据状态、阻塞风险 |
 
 旧模块目录可以保留历史嵌入式段落作为 fallback；新模块目录必须使用独立文件。
 

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

@@ -28,8 +28,8 @@
 - 编辑前检查 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 前补齐或更新。
+- 代码编辑前，确认模块任务目录含有 `execution_strategy.md` 与 `visual_map.md`。如缺失，先补齐再实现。
+- 如果 docs/09-PLANNING/MODULES/<module-key>/ 缺少模块级 `execution_strategy.md` 或 `visual_map.md`，在派发 worker 前补齐或更新。
 
 分支与工作树：
 - Worktree path: <worktree-path>.
@@ -55,8 +55,9 @@
 - 除非 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。
+- 汇报状态时区分 `task.state`、`lifecycleState`、`reviewStatus` 和 `closeoutStatus`；`done` 只表示实现步骤完成，不等于 `closed`。
 - 更新 docs/09-PLANNING/MODULES/<module-key>/module_plan.md。
-- 写 review.md，或记录 review skipped-with-reason。
+- 写 review.md，或记录 review skipped-with-reason。需要人工确认审查完成时，必须通过本地 dashboard workbench，或由 coordinator 执行 `harness review-confirm`；存在开放 P0/P1/P2 finding 时不得确认。
 - 步骤完成时写 walkthrough，并包含 Lessons 反思。
 - Coordinator pass 在任务关闭时更新 Closeout SSoT 和 Lessons 检查。
 - Coordinator pass 在行为、测试、架构或流程改变时更新 Regression SSoT 和 Harness Ledger。