coding-agent-harness 1.0.2 → 1.0.5

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/INDEX.md

@@ -0,0 +1,87 @@
+# {{TASK_TITLE}} - 任务包索引
+
+Task Contract: harness-task/v1
+
+## 任务身份
+
+| Field | Value |
+| --- | --- |
+| Task ID | `{{TASK_ID}}` |
+| Budget | `{{TASK_BUDGET}}` |
+| Preset | `{{TASK_PRESET}}` |
+| Module | `{{TASK_MODULE}}` |
+| Long-running | `{{TASK_LONG_RUNNING}}` |
+| Created | {{DATE}} |
+
+## 任务审计元数据
+
+| Field | Value |
+| --- | --- |
+| Created By | {{TASK_AUDIT_CREATED_BY}} |
+| Created At | {{TASK_AUDIT_CREATED_AT}} |
+| Command Shape | {{TASK_AUDIT_COMMAND_SHAPE}} |
+| Budget | {{TASK_AUDIT_BUDGET}} |
+| Template Source | {{TASK_AUDIT_TEMPLATE_SOURCE}} |
+| Task Creator | {{TASK_AUDIT_TASK_CREATOR}} |
+| Task Creator Source | {{TASK_AUDIT_TASK_CREATOR_SOURCE}} |
+| Human Review Status | {{TASK_AUDIT_HUMAN_REVIEW_STATUS}} |
+| Confirmation ID | {{TASK_AUDIT_CONFIRMATION_ID}} |
+| Confirmed At | {{TASK_AUDIT_CONFIRMED_AT}} |
+| Reviewer | {{TASK_AUDIT_REVIEWER}} |
+| Reviewer Email | {{TASK_AUDIT_REVIEWER_EMAIL}} |
+| Confirm Text | {{TASK_AUDIT_CONFIRM_TEXT}} |
+| Evidence Checked | {{TASK_AUDIT_EVIDENCE_CHECKED}} |
+| Review Commit SHA | {{TASK_AUDIT_REVIEW_COMMIT_SHA}} |
+| Audit Source | {{TASK_AUDIT_AUDIT_SOURCE}} |
+| Audit Status | {{TASK_AUDIT_AUDIT_STATUS}} |
+| Exception Reason | {{TASK_AUDIT_EXCEPTION_REASON}} |
+| Message | {{TASK_AUDIT_MESSAGE}} |
+| Migration Status | {{TASK_AUDIT_MIGRATION_STATUS}} |
+| Migrated From | {{TASK_AUDIT_MIGRATED_FROM}} |
+| Legacy Extra Fields | {{TASK_AUDIT_LEGACY_EXTRA_FIELDS}} |
+| Migration Notes | {{TASK_AUDIT_MIGRATION_NOTES}} |
+
+## 核心合同文件
+
+| 文件 | 用途 |
+| --- | --- |
+| `brief.md` | 面向人和下一轮 agent 的任务摘要与上下文入口。 |
+| `task_plan.md` | 当前任务目标、范围、所选预算、验收标准和执行决策。 |
+| `visual_map.md` | 阶段图、证据状态、下一步生命周期命令和支持性图表。 |
+| `progress.md` | 执行日志、验证证据、决策和交接记录。 |
+
+## 标准任务文件
+
+standard 和 complex 任务包含以下文件。
+
+| 文件 | 用途 |
+| --- | --- |
+| `execution_strategy.md` | 执行模式、owner、冲突控制和证据策略。 |
+| `findings.md` | 发现、研究记录、已接受风险和未解决问题。 |
+| `lesson_candidates.md` | closeout 前的任务本地 lesson candidate 决策。 |
+| `review.md` | Agent Review Submission、对抗审查、findings、evidence 和 routing。 |
+
+## 可选索引
+
+| 索引 | 用途 |
+| --- | --- |
+| `references/INDEX.md` | 参考资料和 preset 提供的 required reads。 |
+| `artifacts/INDEX.md` | 生成产物、证据包、截图、报告和命令输出。 |
+
+## Preset 摘要
+
+本节由系统渲染。Preset 不能新增自定义根级文件，也不能任意追加根 `INDEX.md` 内容。
+
+| Field | Value |
+| --- | --- |
+| Preset | `{{TASK_PRESET}}` |
+| Preset Version | `{{TASK_PRESET_VERSION}}` |
+| Evidence Bundle | `{{TASK_EVIDENCE_BUNDLE}}` |
+| Resource Indexes | `references/INDEX.md`; `artifacts/INDEX.md` |
+
+## 更新规则
+
+- 状态和决策写入 `progress.md`。
+- 任务专属目标和验收标准写入 `task_plan.md`。
+- 大段命令输出、截图、报告和生成文件放入 `artifacts/INDEX.md`。
+- 源材料、外部链接和 preset required reads 放入 `references/INDEX.md`。

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

@@ -24,7 +24,7 @@
 
 - Owner：coordinator
 - 生命周期状态：未开始
-- 必需文件：`task_plan.md`、`execution_strategy.md`、`visual_map.md`、`progress.md`、`findings.md`、`review.md`
+- 必需文件：`INDEX.md`、`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

@@ -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/module_session_prompt.md

@@ -56,6 +56,7 @@
 - 如果需要全局表更新，在 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`。
+- 把当前任务 `visual_map.md` 阶段表作为生命周期地图。切片结束时检查当前 gate phase；只有 `Actor` 为 `agent` 的 `Exit Command` 才由 Agent 执行。
 - 更新 docs/09-PLANNING/MODULES/<module-key>/module_plan.md。
 - 写 review.md，或记录 review skipped-with-reason。需要人工确认审查完成时，必须通过本地 dashboard workbench，或由 coordinator 执行 `harness review-confirm`；存在开放 P0/P1/P2 finding 时不得确认。
 - 步骤完成时写 walkthrough，并包含 Lessons 反思。

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% 信心？
@@ -55,13 +84,24 @@
 | --- | --- | --- | --- |
 | [风险] | [负责人] | 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

@@ -1,6 +1,7 @@
 # [任务名称]
 
 Task Contract: harness-task/v1
+Task Package Index: required
 
 ## 目标
 
@@ -12,23 +13,11 @@ 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 个切片 | 完整任务文件，并只启用实际需要的可选索引 |
+## 预算选择
 
 选择预算：{{TASK_BUDGET}}
 
-可选子目录按触发条件创建，不作为默认脚手架：
-
-- `references/INDEX.md`：任务本地资料、外部链接、reviewer 输入包、跨仓上下文。
-- `artifacts/INDEX.md`：命令输出、截图、fixture、生成报告、审查记录等证据。
-- `slices/<slice-id>/`：多切片任务。每个切片使用 `brief.md`、`evidence.md`、`review.md`。
-
-没有真实触发条件时，不创建可选目录；已创建则必须有 index 和明确用途。
+选择理由：[为什么本任务适合这个预算]
 
 ## 上下文包（Context Packet）
 
@@ -36,34 +25,6 @@ Task Contract: harness-task/v1
 | --- | --- | --- | --- | --- |
 | C-001 | public-doc / private-plan / external / code | PUBLIC:path 或 PRIVATE:path 或 TARGET:path 或 EXTERNAL:path 或 URL:https://example.com | [说明这份上下文如何影响任务] | coordinator / reviewer / worker |
 
-路径前缀约定：
-
-- `PUBLIC:`：公开源仓库中的文件。
-- `PRIVATE:`：私有 harness 仓库中的文件。
-- `TARGET:`：已安装目标项目中的文件。
-- `EXTERNAL:` 或 `URL:`：外部资料。
-
-## 执行与可视化文件
-
-`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 结论 |
-
-旧任务可以保留历史嵌入式段落作为 fallback；新任务必须使用独立文件。
-
-## 产物索引（Artifact Index）
-
-简单任务可在这里登记关键证据。产物较多时，创建 `artifacts/INDEX.md` 并在此引用 ID。
-
-| Artifact ID | 类型 | 路径 | 摘要 |
-| --- | --- | --- | --- |
-| A-001 | command / diff / fixture / screenshot / review / report | PUBLIC:path 或 PRIVATE:path 或 TARGET:path 或 EXTERNAL:path 或 URL:https://example.com | [这份证据证明了什么] |
-
 ## 步骤
 
 1. [步骤 1]
@@ -101,10 +62,9 @@ Task Contract: harness-task/v1
 
 ## 关联
 
-- 功能 SSoT 条目：[引用]
 - 相关 Regression Gate：[引用]
 - 审查报告：[路径 / 不适用]
-- Harness Ledger 条目：[完成时填写 / HL-...]
+- Generated Ledger：由 lifecycle CLI / `harness governance rebuild` 重建
 - 前置任务：[引用；如无写“无”]
 
 ## 模块关联（启用模块并行时填写）

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

@@ -14,22 +14,29 @@ Visual Map Contract: v1.0
 
 ```mermaid
 flowchart LR
-  PH01["PH-01 计划确认"] --> PH02["PH-02 实现"]
-  PH02 --> PH03["PH-03 验证"]
-  PH03 --> PH04["PH-04 审查与收口"]
+  INIT01["INIT-01 范围与上下文\nkind=init"] --> EXEC01["EXEC-01 实现切片\nkind=execution"]
+  EXEC01 --> GATE01["GATE-01 Agent 提交审查\nkind=gate"]
+  GATE01 --> GATE02["GATE-02 人工审查确认\nkind=gate"]
 ```
 
 ## 阶段表（Phase Table，表头供 checker 解析）
 
-| Phase ID | Depends On | State | Completion | Output | Required Evidence | Evidence Status | Blocking Risk | Owner / Handoff |
-| --- | --- | --- | ---: | --- | --- | --- | --- | --- |
-| PH-01 | none | planned | 0 | [计划输出] | [必需证据] | missing | none | coordinator |
+| Phase ID | Kind | Depends On | State | Completion | Output | Required Evidence | Exit Command | Actor | Evidence Status | Blocking Risk | Owner / Handoff |
+| --- | --- | --- | --- | ---: | --- | --- | --- | --- | --- | --- | --- |
+| INIT-01 | init | none | planned | 0 | 任务计划和执行策略已确认 | `task_plan.md`; `execution_strategy.md` | `harness task-start {{TASK_ID}}` | agent | missing | none | coordinator |
+| EXEC-01 | execution | INIT-01 | planned | 0 | 有边界的实现、文档切片和验证证据 | diff、commands、worker handoff 或 artifact path | `harness task-phase {{TASK_ID}} EXEC-01 --state done --completion 100 --evidence present` | agent | missing | [risk] | [owner] |
+| GATE-01 | gate | EXEC-01 | planned | 0 | Agent Review Submission | `review.md`、progress update、lesson routing | `harness task-review {{TASK_ID}} --message "<summary>"` | agent | missing | [risk] | coordinator |
+| GATE-02 | gate | GATE-01 | planned | 0 | Human Review Confirmation | review packet 和人工确认 | `harness review-confirm {{TASK_ID}} --confirm {{TASK_ID}}` | human | missing | Agent 不能代办人工确认 | human |
 
 允许的 `State`：`planned`, `in_progress`, `review`, `blocked`, `done`, `skipped`。
 
 允许的 `Evidence Status`：`missing`, `partial`, `present`, `waived`。
 
-`Completion` 使用 `0..100` 的整数；`done` 应为 `100`，`planned` 应为 `0`，`skipped` 不计入 dashboard 总完成度。dashboard 以阶段表计算进度，不从正文推断。
+允许的 `Kind`：`init`, `execution`, `gate`。
+
+允许的 `Actor`：`agent`, `human`, `coordinator`。
+
+`Completion` 使用 `0..100` 的整数；`done` 应为 `100`，`planned` 应为 `0`，`skipped` 不计入 dashboard 总完成度。dashboard 的实现完成度只由非 skipped 的 `execution` 阶段计算；`init` 和 `gate` 阶段表达生命周期门禁、下一步命令和责任人，不拉低实现完成度。
 
 ## 支持性图表（Supporting Maps）
 

package/templates-zh-CN/planning/visual_map.simple.md

@@ -0,0 +1,48 @@
+# Visual Map / 可视化图谱
+
+Visual Map Contract: v1.0
+
+本文件是任务图表集合，不只是阶段路线图。只有对人或 agent 理解任务有实际帮助的图才放进来。
+
+## 图表索引（Map Index）
+
+| ID | Type | Purpose | Required For Understanding | Source Evidence | Promotion Candidate |
+| --- | --- | --- | --- | --- | --- |
+| MAP-01 | phase | 展示执行阶段和依赖关系 | yes | `task_plan.md` | no |
+
+## 阶段关系图（Phase Graph）
+
+```mermaid
+flowchart LR
+  INIT01["INIT-01 范围与上下文\nkind=init"] --> EXEC01["EXEC-01 实现切片\nkind=execution"]
+  EXEC01 --> GATE01["GATE-01 直接完成\nkind=gate"]
+```
+
+## 阶段表（Phase Table，表头供 checker 解析）
+
+| Phase ID | Kind | Depends On | State | Completion | Output | Required Evidence | Exit Command | Actor | Evidence Status | Blocking Risk | Owner / Handoff |
+| --- | --- | --- | --- | ---: | --- | --- | --- | --- | --- | --- | --- |
+| INIT-01 | init | none | planned | 0 | 任务边界已清楚到可以执行 | `task_plan.md` | `harness task-start {{TASK_ID}}` | agent | missing | none | coordinator |
+| EXEC-01 | execution | INIT-01 | planned | 0 | 简单实现或文档变更已完成 | diff、command 或 artifact path | `harness task-phase {{TASK_ID}} EXEC-01 --state done --completion 100 --evidence present` | agent | missing | [risk] | [owner] |
+| GATE-01 | gate | EXEC-01 | planned | 0 | 直接完成任务 | progress update 和最终证据说明 | `harness task-complete {{TASK_ID}} --message "<summary>"` | agent | missing | [risk] | coordinator |
+
+允许的 `State`：`planned`, `in_progress`, `review`, `blocked`, `done`, `skipped`。
+
+允许的 `Evidence Status`：`missing`, `partial`, `present`, `waived`。
+
+允许的 `Kind`：`init`, `execution`, `gate`。
+
+允许的 `Actor`：`agent`, `human`, `coordinator`。
+
+`Completion` 使用 `0..100` 的整数；`done` 应为 `100`，`planned` 应为 `0`，`skipped` 不计入 dashboard 总完成度。dashboard 的实现完成度只由非 skipped 的 `execution` 阶段计算；`init` 和 `gate` 阶段表达生命周期门禁、下一步命令和责任人，不拉低实现完成度。
+
+## 支持性图表（Supporting Maps）
+
+按需添加，不要求每类都存在：
+
+- architecture：模块、组件、服务结构。
+- sequence：前端、后端、服务、数据库、agent 时序。
+- data-flow：数据流转和所有权。
+- state：状态机或生命周期。
+- topology：repo、服务、worker、worktree 拓扑。
+- decision：方案分叉和决策树。

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,32 @@
 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 并自动提交。`new-task` 可以保留无关 dirty 文件，并只提交本次命令自己的 write scope；但 write scope 重叠 dirty 或无关 staged 文件仍会阻塞命令。其他 lifecycle 命令仍可能要求 clean tree。agent-owned 手工编辑仍需要明确任务提交或延期提交理由。
+10. 把 `visual_map.md` 当作生命周期阶段地图。`init` 阶段准备工作，`execution` 阶段定义实现完成度，`gate` 阶段定义审查、人工确认、lesson routing 和 closeout。只有当前操作者匹配阶段 `Actor` 时，才执行该阶段 `Exit Command`；Agent 不得执行 `human` gate。
+11. 新任务目录必须在 `INDEX.md` 保留机器可读任务审计元数据。正常路径是 `Created By: harness new-task`；手工创建只能作为 `manual-exception`，并写清具体原因；历史迁移使用 `historical-backfill`。
+
+## 任务包结构
+
+使用 `harness new-task` 创建任务目录，不要手工复制任务文件。CLI 会按所选预算创建文件集，并在 `INDEX.md` 记录任务审计元数据，供 `harness check` 校验。
+
+| 预算 | 必需文件 |
+| --- | --- |
+| simple | `INDEX.md`、`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` |
+
+`INDEX.md` 是任务包导航页，也是审计元数据 SSoT。它只指向合同文件和可选索引，不替代这些文件。
+
+可选目录只在触发时创建：
+
+- `references/INDEX.md`：任务本地资料、外部链接、reviewer 输入包、preset 提供的 required reads。
+- `artifacts/INDEX.md`：命令输出、截图、fixture、生成报告、审查记录和其他证据。
+- `lessons/LC-*.md`：进入 `needs-promotion` 的 lesson candidate 的任务本地详情文件。
+- `slices/<slice-id>/`：明确启用多切片任务包时使用。
+
+Preset 包不能新增或替换根级 base scaffold 文档。Preset 只能追加固定基础文档的受控 section，或把隔离资源写入 `references/**` 和 `artifacts/**`。resource rows 只能登记在 `references/INDEX.md` 和 `artifacts/INDEX.md`；根 `INDEX.md` 最多显示系统渲染的 preset summary 字段。
 
 ## 完成任务后
 
@@ -38,11 +63,12 @@
 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>`。
-9. 最后更新 Harness Ledger，因为它记录本轮上下文维护的最终状态。
-10. 完成 commit / PR / release note，并确认本任务工作区没有未解释的遗留改动。
-11. 如使用 worker，coordinator 集成 worker commit 后运行最终 gates，并记录 integration evidence。
-12. 如使用 worktree，按 `worktree-standard.md` 清理或记录保留原因。
+8. 确认当前 `visual_map.md` lifecycle gate 已执行，或已记录 blocker。
+9. 执行 Lessons 检查：新任务默认先写 `lesson_candidates.md` 并交给人工审查；人工标记后可记录 `queued-promotion`，再由维护命令写 promoted lesson 详情文档。没有可复用候选时记录 `no-candidate-accepted`；旧任务兼容可记录 `checked-none: <reason>`。
+10. 最后更新 Harness Ledger，因为它记录本轮上下文维护的最终状态。
+11. 完成 commit / PR / release note，并确认本任务工作区没有未解释的遗留改动。
+12. 如使用 worker，coordinator 集成 worker commit 后运行最终 gates，并记录 integration evidence。
+13. 如使用 worktree，按 `worktree-standard.md` 清理或记录保留原因。
 
 ## 提交规范
 
@@ -75,7 +101,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。