coding-agent-harness 1.0.4 → 1.0.5

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

@@ -78,24 +78,6 @@ Scanner 会根据必需文件、章节、证据和这个严格提交块派生 `m
 
 [如果没有重要发现，明确写：本轮已检查上述证据，未发现阻塞目标的重要发现。]
 
-## 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 |

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

@@ -1,6 +1,7 @@
 # [任务名称]
 
 Task Contract: harness-task/v1
+Task Package Index: required
 
 ## 目标
 
@@ -12,24 +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 | 常规功能、修复或文档改动 | `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`。
-
-没有真实触发条件时，不创建可选目录；已创建则必须有 index 和明确用途。
+选择理由：[为什么本任务适合这个预算]
 
 ## 上下文包（Context Packet）
 
@@ -37,54 +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:`：外部资料。
-
-## 执行与可视化文件
-
-不要手工复制本模板来创建任务目录。必须使用 `harness new-task`，让所选预算自动
-创建正确文件集，并让 `harness check` 能按同一契约校验。
-
-`execution_strategy.md` 和 `visual_map.md` 是本任务的同级合同文件，不嵌入 `task_plan.md`。这样 dashboard 和 checker 可以稳定读取。
-
-| 预算 | 必需文件 |
-| --- | --- |
-| 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；新任务必须使用独立文件。
-
-## 产物索引（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]

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/execution-workflow-standard.md

@@ -28,7 +28,31 @@
 6. 遇到共享文件冲突，由 coordinator 或人工决定串行顺序。
 7. 遇到目标失效、权限阻塞、高风险决策或 stop condition 不适用，立即暂停并记录。
 8. 主动提交已验证的、有意义的中间成果；commit message 应说明变更类型和范围。除非用户明确要求暂不提交、检查失败、dirty 归属不清，或安全边界阻止干净提交，否则不要把已完成切片长期留在未提交状态；延期提交必须写明 no-commit reason、owner 和下一步。
-9. 机械化 Harness 写入优先使用 CLI lifecycle 命令。CLI-owned 写入会加锁、限制 allowlist 并自动提交，也会拒绝 dirty Git 状态；agent-owned 手工编辑仍需要明确任务提交或延期提交理由。
+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 字段。
 
 ## 完成任务后
 
@@ -39,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`，再由维护命令写 promoted lesson 详情文档。没有可复用候选时记录 `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` 清理或记录保留原因。
 
 ## 提交规范