coding-agent-harness 1.0.2 → 1.0.4

package/templates/reference/pull-request-standard.md

@@ -0,0 +1,80 @@
+# Pull Request Standard
+
+## Purpose
+
+Every non-trivial PR must be reviewable without reading the full agent
+conversation. The PR body is a handoff packet for maintainers: what changed,
+why it changed, how it was verified, which version is affected, and what risks
+remain.
+
+## Required Shape
+
+The PR body must include:
+
+1. Summary
+2. What Changed
+3. Version Impact
+4. Verification
+5. Review Evidence
+6. Residual Risk
+7. References
+
+Use a bilingual PR body when the repository has Chinese and English users or
+the task discussion is Chinese. English comes first for public GitHub readers,
+then the localized section follows after the English section.
+
+## Content Rules
+
+- State the target version explicitly. If `package.json` changes from `1.0.3`
+  to `1.0.4`, say so in Version Impact.
+- List changed surfaces by user-visible area or module, not by dumping every
+  file path.
+- Verification must name the real commands, browser checks, CI runs, or
+  evidence artifacts. If a check was not run, say why.
+- Review Evidence must mention self-review, subagent review, human review, or
+  code-quality review status. Release-blocking findings must be closed or
+  routed before merge.
+- Residual Risk must distinguish accepted risk, deferred follow-up, and
+  unrelated local/private debt.
+- References must link relevant task docs, SSoT rows, review files, commits,
+  issues, or PRs.
+
+## Template
+
+```markdown
+## Summary
+
+[One or two sentences explaining the intent and outcome.]
+
+## What Changed
+
+- [User-facing or module-level change.]
+- [Governance, CLI, dashboard, docs, or template change.]
+
+## Version Impact
+
+- Package version: `[old]` -> `[new]`
+- Release notes: [CHANGELOG entry or reason no release note is needed]
+
+## Verification
+
+- `[command]`: pass
+- `[browser/runtime/CI evidence]`: pass
+- Not run: [reason]
+
+## Review Evidence
+
+- Self-review: [summary]
+- Additional review: [reviewer/subagent/human result]
+- Blocking findings: [none / closed / routed]
+
+## Residual Risk
+
+- [none / accepted / deferred / unrelated debt]
+
+## References
+
+- Task: [path or issue]
+- Review: [path or PR review]
+- Evidence: [path, commit, screenshot, workflow, or dashboard]
+```

package/templates/reference/repo-governance-standard.md

@@ -10,10 +10,11 @@ Define repository-level rules for branches, commits, pull requests, ownership, g
 2. Use task-scoped branches and worktrees for non-trivial changes, especially when multiple workers are active.
 3. Keep commits focused on the requested scope and avoid mixing unrelated cleanup with feature work.
 4. Generated files, caches, build output, local runtime state, and secrets must be ignored or stored in the approved location.
-5. Commit verified, meaningful slices proactively. Deferred commits require an explicit reason and owner.
-6. Pull requests must describe intent, changed surfaces, checks run, checks not run, review status, and residual risk.
-7. Required checks and material review findings block merge unless an approved exception is recorded.
-8. Merge or release ownership must be explicit when several branches or workers contribute to the same outcome.
+5. Commit verified, meaningful slices proactively. Deferred commits require an explicit no-commit reason, owner, and next step.
+6. Do not mix unrelated dirty changes into a task commit. CLI-owned Harness writes should use the local Harness commands so their locked, allowlisted auto-commit can protect shared governance files.
+7. Pull requests must follow `docs/11-REFERENCE/pull-request-standard.md` and describe intent, changed surfaces, version impact, checks run, checks not run, review status, references, and residual risk.
+8. Required checks and material review findings block merge unless an approved exception is recorded.
+9. Merge or release ownership must be explicit when several branches or workers contribute to the same outcome.
 
 ## Required Checklist
 
@@ -21,8 +22,8 @@ Define repository-level rules for branches, commits, pull requests, ownership, g
 - Allowed and forbidden paths are respected.
 - Dirty worktree state was checked before edits.
 - Generated and private files are not accidentally staged.
-- Verified slices have commit SHAs, or deferred commit rationale is recorded.
-- PR summary includes evidence and residuals.
+- Verified slices have commit SHAs, or deferred commit rationale records the no-commit reason, owner, and next step.
+- PR summary follows `pull-request-standard.md` and includes evidence, version impact, references, and residuals.
 - Review findings are resolved or explicitly accepted.
 - Merge strategy and rollback or revert path are understood.
 

package/templates/reference/review-routing-standard.md

@@ -13,6 +13,12 @@ Define when work needs review, which reviewer identity is appropriate, and how r
 5. Reviewers must list `Evidence Checked`; unverified claims are questions, not conclusions.
 6. The implementation owner is responsible for reconciling conflicting reviewer feedback.
 7. Closeout must include the final review disposition and `Final Confidence Basis`.
+8. At task start, read the current task `execution_strategy.md` Subagent Authorization and Subagent Delegation Decision sections, then report the state and delegation choice; users do not need to know or ask for subagents.
+9. Reviewer subagents are allowed by default for read-only review within the current task.
+10. If a worker subagent would materially help and is not authorized, proactively ask the user once in plain language for task/scope/worktree authorization; it is fine to say "worker subagent", but do not wait for the user to know or suggest subagents.
+11. If independent slices are obvious but exact file paths are not, identify the file paths first and then immediately ask for independent-execution-helper authorization before implementation.
+12. Worker subagents require one user authorization recorded in `execution_strategy.md`; reuse is limited to the same task, scope, and worktree/branch.
+13. A `Would a worker subagent materially help?` decision of `ask-user` is a blocking gate until `User Authorization Decision` records `authorized`, `denied`, or `not-needed`.
 
 ## Required Checklist
 

package/templates/reference/walkthrough-standard.md

@@ -10,7 +10,7 @@ Define the closeout walkthrough that converts implementation work into durable p
 2. A walkthrough must explain what changed, why it changed, how it was verified, what review found, and what residual risk remains.
 3. Do not paste large raw logs. Link to evidence files, commands, PRs, screenshots, or CI runs.
 4. Material findings and their resolution must be visible.
-5. Lessons that change future behavior must first be routed through `lesson_candidates.md`; accepted candidates are then routed to the appropriate SSoT, reference standard, or Harness Ledger.
+5. Lessons that change future behavior must first be routed through `lesson_candidates.md`; candidates marked `needs-promotion` must link a task-local `lessons/LC-*.md` detail artifact before a follow-up task or promotion tries to preserve them.
 6. Walkthroughs must be written from the final integrated state, not from a single worker's partial view.
 7. If work is incomplete, the walkthrough must identify the next safe action and stop reason.
 
@@ -22,6 +22,7 @@ Define the closeout walkthrough that converts implementation work into durable p
 - Residual risk section.
 - Lesson or follow-up section.
 - Lesson candidate decision: `checked-candidate:<LC-ID>`, `queued-promotion:<LC-ID>`, `checked-created:<L-ID>`, or legacy `checked-none:<reason>`.
+- Source lesson detail link for any queued or promoted candidate.
 - Links to updated SSoT, Regression SSoT, or Harness Ledger entries when applicable.
 
 ## Closeout Expectations

package/templates/verifier/verifier-output.md

@@ -16,7 +16,7 @@
 | Tests and regression | yes / no | commands, CI runs, logs, screenshots |
 | SSoT and ledger updates | yes / no | Feature, Delivery, Regression, Closeout, or Harness Ledger links |
 | Review disposition | yes / no | review path, finding IDs, or no-finding statement |
-| Lessons and references | yes / no | Lessons SSoT, detail doc, or checked-none reason |
+| Lessons and references | yes / no | lesson_candidates.md, detail doc, or checked-none reason |
 
 ## Explicit Exclusions
 

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

@@ -18,7 +18,7 @@
 3. 非平凡任务先在 `docs/09-PLANNING/TASKS/` 下建立任务目录。
 4. 声称完成前必须记录证据。
 5. 保护无关工作区改动，不回滚任务范围外文件。
-6. 已验证的、有意义的工作切片要主动提交，除非用户明确说不要提交。
+6. 已验证的、有意义的工作切片要主动提交。除非用户明确暂停提交、检查失败、dirty 归属不清，或安全边界导致无法形成干净提交，否则不要把已完成工作只留在未提交文件里；不能提交时，必须在 progress、handoff 或 closeout 中写明 no-commit reason、owner 和下一步。不要把无关 dirty 改动混入本任务提交。
 
 ## 任务阅读矩阵
 
@@ -31,7 +31,7 @@
 | 本地开发、mock、stub、跨仓调试 | `docs/04-DEVELOPMENT/README.md`、`docs/04-DEVELOPMENT/codebase-map.md` |
 | API、event、webhook、SDK、第三方契约 | `docs/06-INTEGRATIONS/README.md` 和相关契约文件 |
 | 测试、冒烟、回归 | `docs/11-REFERENCE/testing-standard.md`、`docs/05-TEST-QA/Regression-SSoT.md` |
-| 开发执行、提交、PR、发布 | `docs/11-REFERENCE/execution-workflow-standard.md`、`docs/11-REFERENCE/repo-governance-standard.md`、`docs/11-REFERENCE/ci-cd-standard.md` |
+| 开发执行、提交、PR、发布 | `docs/11-REFERENCE/execution-workflow-standard.md`、`docs/11-REFERENCE/repo-governance-standard.md`、`docs/11-REFERENCE/pull-request-standard.md`、`docs/11-REFERENCE/ci-cd-standard.md` |
 | 创建或推进任务 | `docs/09-PLANNING/TASKS/` 下的当前任务目录；如果本项目已配置 Harness CLI，优先用 CLI |
 | Brief、Execution Strategy、Visual Map | 当前任务的 `brief.md`、`execution_strategy.md`、`visual_map.md` |
 | 长程任务 | `docs/11-REFERENCE/long-running-task-standard.md` |
@@ -41,39 +41,43 @@
 | 文档治理或 Harness 更新 | `docs/11-REFERENCE/docs-library-standard.md`、`.harness-capabilities.json` |
 | 外部资料摄取 | `docs/11-REFERENCE/external-source-intake-standard.md` |
 | Regression SSoT 维护 | `docs/11-REFERENCE/regression-ssot-governance.md` |
-| 收口、walkthrough、Lessons | `docs/11-REFERENCE/walkthrough-standard.md`、`docs/10-WALKTHROUGH/Closeout-SSoT.md`、`docs/01-GOVERNANCE/Lessons-SSoT.md` |
+| 收口、walkthrough、Lessons | `docs/11-REFERENCE/walkthrough-standard.md`、`docs/10-WALKTHROUGH/Closeout-SSoT.md`、当前任务 `lesson_candidates.md`、`docs/01-GOVERNANCE/lessons/` |
 | Worktree、并行开发隔离 | `docs/11-REFERENCE/worktree-standard.md` |
 
 ## 标准执行流程
 
 1. 先确认请求、范围和受影响文件。
 2. 非平凡任务先创建或更新任务计划，再改代码。
-3. 只读取任务阅读矩阵要求的 reference 文档。
-4. 保留已有项目事实；新增上下文使用 merge / append，不覆盖历史。
-5. 需要隔离或并行时，使用独立 worktree 或分支。
-6. 只在确认范围内实现。
-7. 运行相关检查，并把证据写入任务记录。
-8. 按需触发 review，关闭阻塞发现。
-9. 写入或更新 walkthrough 与 closeout 记录。
-10. 只更新本任务实际触达的 SSoT / ledger。
+3. 根据用户目标主动判断是否需要分工；用户不需要知道或主动要求 subagent。
+4. 只读取任务阅读矩阵要求的 reference 文档。
+5. 保留已有项目事实；新增上下文使用 merge / append，不覆盖历史。
+6. 需要隔离或并行时，使用独立 worktree 或分支。
+7. 只在确认范围内实现。
+8. 运行相关检查，并把证据写入任务记录。
+9. 按需触发 review，关闭阻塞发现。
+10. 写入或更新 walkthrough 与 closeout 记录。
+11. 只更新本任务实际触达的 SSoT / ledger；任务生命周期总账优先由 Harness CLI 生成，不手写任务行。
 
 ## 协作规则
 
-- reviewer 默认只读，除非明确分配写入范围。
-- worker 只能编辑分配给自己的分支、worktree 和文件范围。
+- 任务开始时，先读取当前任务 `execution_strategy.md` 的 Subagent Authorization 和 Subagent Delegation Decision，并说明是否应该使用 reviewer 或 worker subagent；即使用户只说目标，也要主动判断。
+- reviewer subagent 默认允许，只能做当前任务的只读审查。
+- 如果 worker subagent 对任务有明显帮助但尚未授权，用白话主动向用户申请一次 task/scope/worktree 授权；可以直接说 worker subagent，但不要等用户知道或主动提醒你用 subagent。
+- 如果独立切片已经明显但精确文件路径还不清楚，先确认文件路径，然后在 implementation 前立刻申请独立执行助手授权。
+- worker subagent 需要用户授权一次，并记录到 `execution_strategy.md`；之后只可在同一任务、同一范围、同一 worktree/branch 内复用。
 - 共享 ledger、registry 和 SSoT 默认由 coordinator 维护，除非明确登记锁。
 - worker 交接必须包含分支或 worktree、改动文件、检查、证据和残余风险。
 
 ## 单一事实源
 
-- Feature SSoT：`docs/09-PLANNING/Feature-SSoT.md`
+- Harness Ledger：`docs/Harness-Ledger.md`（任务生命周期总账，由 CLI 生成）
 - Delivery SSoT：`docs/09-PLANNING/Delivery-SSoT.md`
 - Module Registry：`docs/09-PLANNING/Module-Registry.md`
 - Regression SSoT：`docs/05-TEST-QA/Regression-SSoT.md`
 - Cadence Ledger：`docs/05-TEST-QA/Cadence-Ledger.md`
-- Lessons SSoT：`docs/01-GOVERNANCE/Lessons-SSoT.md`
+- Lesson Candidates：当前任务 `lesson_candidates.md`
+- Lesson Detail Docs：`docs/01-GOVERNANCE/lessons/`
 - Closeout SSoT：`docs/10-WALKTHROUGH/Closeout-SSoT.md`
-- Harness Ledger：`docs/Harness-Ledger.md`
 
 ## 本地命令
 

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/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

@@ -1,6 +1,6 @@
 # {{TASK_TITLE}} - 教训候选
 
-本文件是任务本地 lesson candidate queue。它不是 Lessons SSoT；只有人工审查确认值得沉淀后，才进入治理 promotion。
+本文件是任务本地 lesson candidate queue。人工审查需要决定候选是留在任务内、拒绝、进入 dry-run promotion、创建 promoted lesson 详情文档，还是创建单独的沉淀任务。
 
 ## Candidate Status
 
@@ -24,14 +24,14 @@
 - `pending-review`：候选文件存在，但人工判定还没完成。
 - `no-candidate-accepted`：人工接受本任务没有可复用候选的理由。
 - `needs-promotion`：至少一个候选已排队等待治理沉淀。
-- `promoted`：所有接受的候选都已写入 Lessons SSoT。
+- `promoted`：所有接受的候选都已写入已确认的治理目标。
 - `rejected`：所有候选都已带理由拒绝或归档。
 
 允许的行级状态：
 
 - `ready-for-review`：agent 认为这个候选可能有复用价值。
-- `needs-promotion`：人工标记这个候选值得沉淀。
-- `promoted`：维护 CLI 已把候选写入 Lessons SSoT。
+- `needs-promotion`：人工标记这个候选值得通过 dry-run promotion 或后续沉淀任务保留。
+- `promoted`：维护 CLI 或已批准的后续任务已把候选写入确认的治理目标。
 - `rejected`：人工带理由拒绝这个候选。
 
 聚合规则：
@@ -44,8 +44,8 @@
 
 ## Candidates
 
-| ID | Row Status | Title | Why It Might Matter | Review Decision | Promotion Target |
-| --- | --- | --- | --- | --- | --- |
+| 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
 
@@ -54,5 +54,17 @@
 ## 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/review.md

@@ -13,6 +13,35 @@
 - 范围外：[明确不审查的内容；如无写“无”]
 - 来源材料：[task plan、diff、commit、PR、测试输出、运行证据]
 
+## Agent Review Submission（Agent 提交审查）
+
+本节由 agent 或 coordinator 在审查材料包准备好时填写。它只表示“提交待审”，不表示人工批准。
+
+| Field | Value |
+| --- | --- |
+| Submission ID | [由 task-review 生成] |
+| Submitted At | [timestamp] |
+| Submitted By | [agent 或 coordinator 身份] |
+| Task Key | {{TASK_ID}} |
+| Materials Checklist Hash | [由 task-review 生成；只作信息记录，不作为手工门禁] |
+| Evidence Summary | [测试、diff、运行和审查材料证据] |
+| Open Findings Count | [数字] |
+| Scanner Version | [生成时的 scanner 版本] |
+
+### Material Checklist（材料清单）
+
+| Material | Required? | Status | Evidence |
+| --- | --- | --- | --- |
+| Brief | yes / no | present / missing / incomplete | [路径或原因] |
+| Task plan | yes / no | present / missing / incomplete | [路径或原因] |
+| Progress and evidence | yes / no | present / missing / incomplete | [路径或原因] |
+| Visual map | yes / no | present / missing / incomplete | [路径或原因] |
+| Lesson candidate decision | yes / no | present / missing / incomplete | [路径或原因] |
+| Walkthrough or closeout link | yes / no | present / missing / incomplete | [路径或原因] |
+
+Scanner 会根据必需文件、章节、证据和这个严格提交块派生 `materialsReady`。如果材料未齐，任务应进入缺材料队列，而不是人工审查确认队列。
+如果存在开放的 P0/P1/P2 阻塞发现，任务应进入阻塞队列，而不是人工审查确认队列。
+
 ## 信心挑战（Confidence Challenge）
 
 直接回答：你是否对当前计划、实现和策略有 100% 信心？
@@ -49,19 +78,48 @@
 
 [如果没有重要发现，明确写：本轮已检查上述证据，未发现阻塞目标的重要发现。]
 
+## Human Review Confirmation（人工审查确认）
+
+本节只能由人工 reviewer，或代表明确人工确认的命令 / workbench 动作填写。Agent 提交审查、自查、subagent 审查都不能满足这个门禁。
+
+| Field | Value |
+| --- | --- |
+| Confirmation ID | [由 review-confirm 生成] |
+| Confirmed At | [timestamp] |
+| Reviewer | [人工 reviewer 姓名] |
+| Reviewer Email | [邮箱，如可用] |
+| Task Key | {{TASK_ID}} |
+| Confirm Text | [必须匹配任务 ID 或命令要求的确认短语] |
+| Evidence Checked | [review packet / tests / diff 摘要] |
+| Commit SHA | [由 review-confirm 生成的确认提交 SHA] |
+| Audit Status | committed / blocked |
+
+任务仍属于缺材料、阻塞或 Lessons 路由时，不要填写本节。`review-confirm` 与 Dashboard Workbench 必须在 Git dirty、提交身份缺失、hook 失败，或写入超出当前任务 `review.md` / `progress.md` 白名单时拒绝确认。
+
 ## 残余风险
 
 | Risk | Owner | Accepted? | Follow-up |
 | --- | --- | --- | --- |
 | [风险] | [负责人] | yes / no | [后续路径或“无”] |
 
+## Lifecycle Queue Routing（生命周期队列路由）
+
+| Queue | Applies? | Reason | Exit condition |
+| --- | --- | --- | --- |
+| Review | yes / no | 已提交审查材料包，且可等待人工确认。 | 人工确认或退回。 |
+| Missing Materials | yes / no | 必需文件、章节、证据或 review submission 缺失 / 不完整。 | Agent 补齐材料并重新提交审查。 |
+| Blocked | yes / no | 存在 open blocking finding、非法状态转换、审计失败或需要人工 waiver。 | blocker 被修复、关闭或明确豁免。 |
+| Lessons | yes / no | Lesson candidate 需要拒绝、留在任务内、dry-run promotion 或创建沉淀任务。 | 人工决定候选路由；除非明确批准，promotion 仍是单独维护任务。 |
+| Confirmed / Finalized | yes / no | 已有人工确认；可能仍待结项或治理收口。 | Closeout、ledger 和 lesson routing 都完成。 |
+| Soft-deleted / Superseded | yes / no | 任务有 tombstone、superseded-by、archive、duplicate 或 abandoned 状态。 | reopen 或作为只读审计历史保留。 |
+
 ## 后续路由（Follow-Up Routing）
 
 - 任务计划：[是否需要更新，路径或“无”]
 - Progress：[对应 `progress.md` 条目]
 - 发现记录：[是否需要写入 `findings.md`]
 - Regression SSoT：[新增 / 调整 / 无]
-- Lessons SSoT：[checked-created: L-YYYY-MM-DD-NNN / checked-none: 一句话原因]
+- Lessons：[checked-created: L-YYYY-MM-DD-NNN / checked-candidate: LC-YYYYMMDD-NNN / queued-promotion: LC-YYYYMMDD-NNN / checked-none: 一句话原因]
 - 收口记录：[收口时引用路径]
 
 ## 最终信心依据（Final Confidence Basis）

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

@@ -17,13 +17,14 @@ Task Contract: harness-task/v1
 | 预算 | 适用场景 | 必需结构 |
 | --- | --- | --- |
 | simple | 单 owner、无 subagent、证据深度为 L0/L1、不需要正式 review gate | `brief.md`、`task_plan.md`、`visual_map.md`、`progress.md` |
-| standard | 常规功能、修复或文档改动 | 完整任务文件：计划、策略、图谱、进度、发现和按需审查 |
-| complex | 需要 L2/L3 证据、subagent/reviewer、外部参考、生成产物，或超过 5 个切片 | 完整任务文件，并只启用实际需要的可选索引 |
+| standard | 常规功能、修复或文档改动 | `brief.md`、`task_plan.md`、`execution_strategy.md`、`visual_map.md`、`findings.md`、`lesson_candidates.md`、`progress.md`、`review.md` |
+| complex | 需要 L2/L3 证据、subagent/reviewer、外部参考、生成产物，或超过 5 个切片 | standard 文件，并额外创建 `references/INDEX.md` 与 `artifacts/INDEX.md` |
 
 选择预算：{{TASK_BUDGET}}
 
 可选子目录按触发条件创建，不作为默认脚手架：
 
+- `lessons/LC-*.md`：进入 `needs-promotion` 的 lesson candidate 的任务本地详情文件。
 - `references/INDEX.md`：任务本地资料、外部链接、reviewer 输入包、跨仓上下文。
 - `artifacts/INDEX.md`：命令输出、截图、fixture、生成报告、审查记录等证据。
 - `slices/<slice-id>/`：多切片任务。每个切片使用 `brief.md`、`evidence.md`、`review.md`。
@@ -45,14 +46,34 @@ Task Contract: harness-task/v1
 
 ## 执行与可视化文件
 
+不要手工复制本模板来创建任务目录。必须使用 `harness new-task`，让所选预算自动
+创建正确文件集，并让 `harness check` 能按同一契约校验。
+
 `execution_strategy.md` 和 `visual_map.md` 是本任务的同级合同文件，不嵌入 `task_plan.md`。这样 dashboard 和 checker 可以稳定读取。
 
-| 合同文件 | 是否必需 | 用途 |
-| --- | --- | --- |
-| `execution_strategy.md` | yes | 执行模式、subagent 使用、冲突控制、证据深度、交接规则 |
-| `visual_map.md` | yes | 图表集合：阶段图、可选架构/时序/数据流/状态图、完成度、证据状态、阻塞风险 |
-| `lesson_candidates.md` | standard/complex 必需 | 任务本地教训候选队列。人工审查确认前必须接受无候选、拒绝候选，或排队 promotion |
-| `review.md` | 按需 | 对抗性审查、release review、外部 reviewer 结论 |
+| 预算 | 必需文件 |
+| --- | --- |
+| simple | `brief.md`、`task_plan.md`、`visual_map.md`、`progress.md` |
+| standard | simple 文件，加 `execution_strategy.md`、`findings.md`、`lesson_candidates.md`、`review.md` |
+| complex | standard 文件，加 `references/INDEX.md`、`artifacts/INDEX.md` |
+| long-running 附加项 | 选择 `--long-running` 时额外创建 `long-running-task-contract.md` |
+
+文件职责：
+
+| 合同文件 | 用途 |
+| --- | --- |
+| `brief.md` | 面向人和下一轮 agent 的任务摘要与上下文包 |
+| `task_plan.md` | 目标、范围、预算、验收与执行决策 |
+| `execution_strategy.md` | 执行模式、subagent 使用、冲突控制、证据深度、交接规则 |
+| `visual_map.md` | 图表集合：阶段图、可选架构/时序/数据流/状态图、完成度、证据状态、阻塞风险 |
+| `progress.md` | 执行日志、决策和交接 |
+| `findings.md` | 发现、研究记录和未解决风险 |
+| `lesson_candidates.md` | 任务本地教训候选队列。人工审查确认前必须接受无候选、拒绝候选，或排队 promotion |
+| `lessons/LC-*.md` | 可选的任务本地 lesson 详情文件，趁源任务上下文还新鲜写出，并由 `Detail Artifact` 链接 |
+| `review.md` | Agent Review Submission、对抗性审查、release review、外部 reviewer 结论 |
+| `references/INDEX.md` | complex 任务的资料包和参考索引 |
+| `artifacts/INDEX.md` | complex 任务的生成证据和产物索引 |
+| `long-running-task-contract.md` | 连续执行权限、循环规则和停止条件 |
 
 旧任务可以保留历史嵌入式段落作为 fallback；新任务必须使用独立文件。
 
@@ -101,10 +122,9 @@ Task Contract: harness-task/v1
 
 ## 关联
 
-- 功能 SSoT 条目：[引用]
 - 相关 Regression Gate：[引用]
 - 审查报告：[路径 / 不适用]
-- Harness Ledger 条目：[完成时填写 / HL-...]
+- Generated Ledger：由 lifecycle CLI / `harness governance rebuild` 重建
 - 前置任务：[引用；如无写“无”]
 
 ## 模块关联（启用模块并行时填写）

package/templates-zh-CN/reference/adversarial-review-standard.md

@@ -64,7 +64,7 @@ docs/09-PLANNING/TASKS/<YYYY-MM-DD-任务名>/review.md
 - `not-reproducible`
 - `out-of-scope`
 
-`accepted-risk` 必须写明为什么不阻塞本轮目标，并路由到 task、SSoT、Regression SSoT、Lessons SSoT 或后续 PR。
+`accepted-risk` 必须写明为什么不阻塞本轮目标，并路由到 task、SSoT、Regression SSoT、lesson candidates/detail docs 或后续 PR。
 
 ## 无发现结论
 

package/templates-zh-CN/reference/docs-library-standard.md

@@ -9,7 +9,7 @@
 | 位置 | 职责 |
 | --- | --- |
 | `docs/Harness-Ledger.md` | 全局上下文维护总账，记录非平凡任务是否完成计划、审查、回归、Lessons 和收口回写。 |
-| `docs/01-GOVERNANCE/` | Lessons SSoT、经验详情、治理记录、归档。 |
+| `docs/01-GOVERNANCE/` | promoted lesson 详情、治理记录、归档。 |
 | `docs/03-ARCHITECTURE/` | ADR、架构设计、接口决策、关键技术方案。 |
 | `docs/04-DEVELOPMENT/` | 本地开发、代码地图、外部服务开发上下文、mock/stub、跨仓调试。 |
 | `docs/05-TEST-QA/` | Regression SSoT、Cadence Ledger、测试策略和回归证据索引。 |

package/templates-zh-CN/reference/execution-workflow-standard.md

@@ -27,7 +27,8 @@
 5. 可写 worker 必须在自己的 worktree 内实现、验证、提交，并 handoff branch、commit SHA、checks、residual。
 6. 遇到共享文件冲突，由 coordinator 或人工决定串行顺序。
 7. 遇到目标失效、权限阻塞、高风险决策或 stop condition 不适用，立即暂停并记录。
-8. 主动提交已验证的、有意义的中间成果；commit message 应说明变更类型和范围。除非用户明确要求暂不提交，或检查失败 / diff 归属不清，否则不要把已完成切片长期留在未提交状态。
+8. 主动提交已验证的、有意义的中间成果；commit message 应说明变更类型和范围。除非用户明确要求暂不提交、检查失败、dirty 归属不清，或安全边界阻止干净提交，否则不要把已完成切片长期留在未提交状态；延期提交必须写明 no-commit reason、owner 和下一步。
+9. 机械化 Harness 写入优先使用 CLI lifecycle 命令。CLI-owned 写入会加锁、限制 allowlist 并自动提交，也会拒绝 dirty Git 状态；agent-owned 手工编辑仍需要明确任务提交或延期提交理由。
 
 ## 完成任务后
 
@@ -38,7 +39,7 @@
 5. 确认 `review.md` 没有 open P0/P1 finding；material P2 已修复或写为 `accepted-risk` 并路由。
 6. planned task 必须完成 closeout review，或写明 `skipped-with-reason`。
 7. 写 walkthrough，引用 task plan、review、证据、residual、Regression SSoT 和 commit。
-8. 执行 Lessons 检查：新任务默认先写 `lesson_candidates.md` 并交给人工审查；人工标记后可记录 `queued-promotion`，再由维护命令写 lesson 详情并更新 Lessons SSoT。没有可复用候选时记录 `no-candidate-accepted`；旧任务兼容可记录 `checked-none: <reason>`。
+8. 执行 Lessons 检查：新任务默认先写 `lesson_candidates.md` 并交给人工审查；人工标记后可记录 `queued-promotion`，再由维护命令写 promoted lesson 详情文档。没有可复用候选时记录 `no-candidate-accepted`；旧任务兼容可记录 `checked-none: <reason>`。
 9. 最后更新 Harness Ledger，因为它记录本轮上下文维护的最终状态。
 10. 完成 commit / PR / release note，并确认本任务工作区没有未解释的遗留改动。
 11. 如使用 worker，coordinator 集成 worker commit 后运行最终 gates，并记录 integration evidence。
@@ -75,7 +76,7 @@ PR 描述必须包含：
 
 - 每个已验证的、有意义的切片默认都要提交。
 - 提交前只 stage 本任务范围内文件，不能顺手带入无关 dirty 文件、私有文件或生成产物。
-- 如果用户明确说不要提交、检查失败、或 diff 归属还没厘清，必须把未提交原因写入 `progress.md` 或交接说明。
+- 如果用户明确说不要提交、检查失败、或 dirty 归属还没厘清，必须把 no-commit reason、owner 和下一步写入 `progress.md` 或交接说明。
 - closeout 时必须列出相关 commit SHA；如果没有 commit，必须说明为什么这是安全的例外。
 
 ## 禁止事项

package/templates-zh-CN/reference/harness-ledger-standard.md

@@ -8,7 +8,7 @@ Harness Ledger 是 `docs/` 骨架的全局上下文维护总账，固定位置
 docs/Harness-Ledger.md
 ```
 
-它记录每个非平凡任务是否完成了 task plan、progress、review、功能 SSoT、Delivery SSoT、Regression SSoT、Lessons SSoT、walkthrough、Closeout SSoT、reference/template 和 CI/CD 治理回写。它不复制业务事实，只记录上下文维护是否合规。
+它记录每个非平凡任务是否完成了 task plan、progress、review、功能 SSoT、Delivery SSoT、Regression SSoT、lesson candidates/detail docs、walkthrough、Closeout SSoT、reference/template 和 CI/CD 治理回写。它不复制业务事实，只记录上下文维护是否合规。
 
 ## 必须更新的场景
 
@@ -17,7 +17,7 @@ docs/Harness-Ledger.md
 - 新增或修改 AGENTS.md、CLAUDE.md、reference、template、checker 或 dashboard。
 - coordinator pass 汇总模块任务、worker handoff、review、closeout 或 regression 结果。
 - 创建或更新 required review。
-- 修改功能 SSoT、Delivery SSoT、Regression SSoT、Lessons SSoT、Closeout SSoT 任一文件。
+- 修改功能 SSoT、Delivery SSoT、Regression SSoT、lesson detail docs、Closeout SSoT 任一文件。
 - 创建 walkthrough 或接受受控跳过。
 - Lessons approved 后合入正式 reference。