coding-agent-harness 1.0.1 → 1.0.4

package/docs-release/guides/task-state-machine.en-US.md

@@ -0,0 +1,207 @@
+# Task State Machine And Lifecycle Queues
+
+Chinese mirror: `docs-release/guides/task-state-machine.md`
+
+Coding Agent Harness does not model task state as a single field. The Dashboard derives the visible lifecycle from multiple files:
+
+- `progress.md` stores raw `task.state` and execution evidence.
+- `review.md` stores Agent Review Submission, material findings, and Human Review Confirmation.
+- `lesson_candidates.md` records lesson candidate decisions and sedimentation routing.
+- `10-WALKTHROUGH/Closeout-SSoT.md` records closeout status and links walkthrough evidence.
+- Tombstone / supersede metadata records whether a task was soft-deleted, merged, archived, or replaced.
+- The scanner derives `lifecycleState`, `reviewStatus`, `closeoutStatus`, `taskQueues[]`, `queueReasons[]`, and `repairPrompt` from those files.
+
+The older `reviewQueueState` model was enough for a single review page. After PF-024, the public model is a set of lifecycle queues: Review, Missing Materials, Blocked, Lessons, Confirmed / Finalized, and Soft-deleted / Superseded.
+
+## Raw Task Command Flow
+
+```mermaid
+stateDiagram-v2
+  [*] --> not_started: new-task
+  not_started --> in_progress: task-start
+  planned --> in_progress: task-start
+  in_progress --> in_progress: task-log / task-phase
+  in_progress --> blocked: task-block
+  blocked --> in_progress: blocker fixed
+  in_progress --> review_submitted: task-review
+  review_submitted --> missing_materials: returned for materials
+  missing_materials --> in_progress: repair materials
+  review_submitted --> blocked: blocking finding
+  review_submitted --> human_confirmed: review-confirm
+  human_confirmed --> finalized: task-complete + closeout
+  finalized --> [*]
+```
+
+`task-review` means the agent submitted a review packet. It does not mean human approval. `review-confirm` is the Human Review Confirmation gate. `task-complete` / closeout is not a substitute for review confirmation.
+
+## Derived State
+
+```mermaid
+flowchart TB
+  Progress["progress.md<br/>task.state + evidence"]
+  Review["review.md<br/>Agent Review Submission + findings + Human Review Confirmation"]
+  Lessons["lesson_candidates.md<br/>decision + sedimentation route"]
+  Closeout["Closeout-SSoT.md<br/>closeout row + walkthrough"]
+  Tombstone["tombstone / supersede metadata"]
+  Scanner["scanner"]
+
+  Progress --> Scanner
+  Review --> Scanner
+  Lessons --> Scanner
+  Closeout --> Scanner
+  Tombstone --> Scanner
+
+  Scanner --> Lifecycle["lifecycleState"]
+  Scanner --> ReviewStatus["reviewStatus"]
+  Scanner --> CloseoutStatus["closeoutStatus"]
+  Scanner --> Queues["taskQueues[]"]
+  Scanner --> Reasons["queueReasons[]"]
+  Scanner --> Prompt["repairPrompt"]
+```
+
+| Field | Source | Purpose |
+| --- | --- | --- |
+| `task.state` | `progress.md` | Raw execution stage. |
+| `reviewStatus` | `review.md` + findings + Human Review Confirmation | Separates missing review, agent-submitted review, blockers, and human confirmation. |
+| `closeoutStatus` | `Closeout-SSoT.md` | Separates missing, pending, and closed closeout. |
+| `lifecycleState` | scanner-derived | Main Dashboard lifecycle meaning. |
+| `taskQueues[]` | scanner-derived | Which lifecycle queues include the task. A task can be visible in more than one governance queue. |
+| `queueReasons[]` | scanner-derived | Why the task entered a queue, including source file, field, and repair action. |
+| `repairPrompt` | scanner-derived | A copyable, scoped repair prompt for a Coding Agent. |
+
+## Lifecycle Matrix
+
+| Condition | `lifecycleState` | Meaning |
+| --- | --- | --- |
+| Tombstone, superseded-by, archive, or abandoned marker exists | `soft-deleted-superseded` | Hidden by default, but preserved for audit and replacement tracing. |
+| Open P0-P2 finding, invalid transition, audit failure, or failed human-review gate | `blocked` | Cannot enter human confirmation until the blocker is fixed or waived. |
+| Standard / complex task is missing required files, sections, evidence, lesson decision, or review submission | `missing-materials` | Needs agent repair; not part of the human review queue. |
+| `task-review` was submitted, materials are ready, and Human Review Confirmation is missing | `review-submitted` | Truly waiting for human review. |
+| Human Review Confirmation exists, but closeout / ledger / lessons are not fully closed | `confirmed-finalization-pending` | Accountability moved to the reviewer, but governance closeout remains. |
+| Human Review Confirmation exists, and closeout / ledger / lesson routing are complete | `finalized` | Truly complete and traceable. |
+| `task.state = blocked` without a review blocker | `active-blocked` | Execution is blocked. |
+| `task.state = in_progress` | `active` | Work is active. |
+| `task.state = planned/not_started` | `ready` | Work has not started; not in human review by default. |
+
+## Review Status
+
+| `reviewStatus` | Meaning |
+| --- | --- |
+| `missing` | No usable review document or Agent Review Submission exists. |
+| `required` | Review document exists, but the packet is not ready for human review. |
+| `submitted` | An agent submitted a review packet. This is not human confirmation. |
+| `blocked-open-findings` | There is an open P0-P2 finding or a finding that blocks release / confirmation. |
+| `confirmed` | `Human Review Confirmation` exists. |
+
+Agent self-review, subagent review, and coordinator review can only move a task toward `submitted`. Only `review-confirm` or an explicit Dashboard Workbench human confirmation writes `Human Review Confirmation`.
+
+## Lifecycle Queues
+
+The Dashboard lifecycle workbench is a set of queues, not one mixed review list.
+
+```mermaid
+flowchart TD
+  Task["task facts"]
+  Task --> Deleted{"tombstone / superseded / archived?"}
+  Deleted -->|yes| QDeleted["Soft-deleted / Superseded"]
+  Deleted -->|no| Blocker{"blocking finding or invalid transition?"}
+  Blocker -->|yes| QBlocked["Blocked"]
+  Blocker -->|no| Missing{"required materials missing?"}
+  Missing -->|yes| QMissing["Missing Materials"]
+  Missing -->|no| Submitted{"Agent Review Submission exists?"}
+  Submitted -->|yes + not human confirmed| QReview["Review"]
+  Submitted -->|no| Out["not in human review queue"]
+  Submitted -->|yes + human confirmed| Confirmed{"finalization complete?"}
+  Confirmed -->|no| QConfirmed["Confirmed / Finalized"]
+  Confirmed -->|yes| QFinal["Confirmed / Finalized"]
+  Task --> Lessons{"lesson candidate needs decision or sedimentation?"}
+  Lessons -->|yes| QLessons["Lessons"]
+```
+
+| Queue | Entry condition | Primary owner | Exit condition |
+| --- | --- | --- | --- |
+| Review | Review packet submitted, materials ready, and no human confirmation yet. | human | Human confirms or returns it. |
+| Missing Materials | Missing file, section, evidence, lesson decision, review submission, or incomplete phase. | agent | Agent repairs materials and resubmits review. |
+| Blocked | Blocking finding, state conflict, Git audit failure, completion gate failure, or human waiver required. | agent + human | Fixed, closed, or explicitly waived. |
+| Lessons | Lesson candidate needs decision, task-local retention, rejection, dry-run promotion, or a sedimentation task. | human + agent | Decision is complete, or a traceable sedimentation task exists. |
+| Confirmed / Finalized | Human-confirmed, or finalized and ready for read-only tracing. | coordinator | Closeout, ledger, and lesson routing are complete; then read-only. |
+| Soft-deleted / Superseded | Task was soft-deleted, replaced, merged, archived, or abandoned. | coordinator | Read-only tracing; reopen only when needed. |
+
+The Review queue only waits for human confirmation. Missing materials, blockers, lesson sedimentation, confirmed-but-not-finalized work, and historical superseded tasks must not masquerade as Review queue items.
+
+## Global Table Boundary
+
+Global governance tables only keep index, state, route, and audit summary. They help the Dashboard find the source of truth, but they do not carry module-local facts, long evidence, execution logs, or temporary repair prompts.
+
+| Layer | Should record | Should not record |
+| --- | --- | --- |
+| Global tables: Harness Ledger, Closeout SSoT, Regression SSoT, Cadence Ledger, Delivery SSoT | Current state, owner, task/module/detail links, regression gate, delivery sequence, closeout or audit summary | Module-internal steps, undecided lesson candidates, full command output, long evidence paragraphs, review transcripts, temporary repair prompts |
+| Module layer: Module Registry, `module_plan.md` | Module boundary, module steps, handoff, current blockers, and local evidence indexes | Final promoted lesson body or cross-module release audit ledger |
+| Task layer: `brief.md`, `task_plan.md`, `progress.md`, `review.md`, `lesson_candidates.md`, `lessons/LC-*.md`, `artifacts/INDEX.md` | Execution detail, evidence, agent review, candidate lessons, task-local lesson detail, repair prompts, and raw artifact routing | Cross-task ledgers or promoted lesson detail bodies |
+
+The checker enforces this boundary for new global table rows. Overloaded rows that already existed before 2026-05-24 are surfaced in Dashboard migration advice as `legacy-report-only`; they are not automatically deleted or bulk-rewritten. New rows that continue placing task/module-local detail in global tables are reported as `governance-table-entropy` failures. Lesson candidates stay in `lesson_candidates.md`; candidates that enter `needs-promotion` must link a task-local `lessons/LC-*.md` detail artifact, and accepted reusable lessons live in `docs/01-GOVERNANCE/lessons/*.md`. The fix is to keep the global summary row and move detail into module/task/detail documents linked from that row.
+
+## Human Confirmation Loop
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant Agent as Agent / coordinator
+  participant Human as Human reviewer
+  participant UI as Dashboard Workbench
+  participant API as workbench API
+  participant Lifecycle as task lifecycle writer
+  participant Docs as markdown files
+  participant Scanner as scanner
+
+  Agent->>Docs: write Agent Review Submission + evidence
+  Agent->>UI: submit task-review
+  Human->>UI: open Review queue item
+  UI->>API: POST /api/tasks/review-complete
+  API->>Scanner: read current task facts
+  Scanner-->>API: taskQueues, queueReasons, reviewStatus
+  alt not in Review queue
+    API-->>UI: reject with target queue
+  else missing material or blocker
+    API-->>UI: reject with repairPrompt
+  else accepted
+    API->>Lifecycle: confirmTaskReview()
+    Lifecycle->>Lifecycle: verify clean Git state, identity, hooks, allowlist
+    Lifecycle->>Docs: write Human Review Confirmation
+    Lifecycle->>Docs: append review-confirm log
+    Lifecycle->>Lifecycle: commit allowlisted review/progress files
+    Lifecycle->>Docs: record confirmation commit SHA + committed audit status
+    API->>Scanner: regenerate dashboard snapshot
+    API-->>UI: confirmed task
+  end
+```
+
+Strict rule: an agent can prepare review evidence and submit the task for review, but the task is not human-confirmed until the Human Review Confirmation block exists. Confirmation must use gated auto-commit: the CLI and Workbench reject dirty Git state, missing commit identity, hook/preflight failure, or writes outside the current task `review.md` / `progress.md` allowlist, and return recovery guidance.
+
+CLI-owned mechanical writes and agent-owned manual slices have different boundaries. `new-task`, `task-*`, `task-phase`, `module-step`, `review-confirm`, `lesson-sediment`, and `lesson-promote --apply` acquire a lock, restrict writes to an allowlist, and auto-commit in a clean Git root. When an agent manually edits code, templates, or task docs, it still needs to proactively commit after verification; if it cannot commit, it must record the no-commit reason, owner, and next step, and must not mix unrelated dirty changes into the task commit.
+
+## Lesson Sedimentation
+
+Lesson promotion does not write a shared Lessons table. The Dashboard or CLI should prefer a dry-run or follow-up sedimentation task so the assignee first:
+
+- Classifies scope and boundary reason.
+- Reads the task-local detail artifact referenced by the candidate row instead of reconstructing the lesson from the brief row.
+- Checks conflicts against existing lesson candidates, lesson detail docs, reference standards, templates, and checkers.
+- Proposes a target diff or no-action reason.
+- Writes the promoted lesson detail doc or standard update only after human approval.
+
+`needs-promotion` should not block human review confirmation by itself, but it must enter the Lessons queue and remain traceable in closeout / ledger records.
+
+## Soft Delete And Supersede
+
+The document library does not hard-delete task directories by default.
+
+| State | Meaning | Requirement |
+| --- | --- | --- |
+| `active` | Normal task. | Dashboard shows it by default. |
+| `soft-deleted` | Task was abandoned but the directory stays. | Write a tombstone with operator, timestamp, reason, and reopen eligibility. |
+| `superseded` | Task was replaced or merged into a newer task. | Old task records `Superseded By`; new task records `Supersedes`. |
+| `archived` | Task moved to archive. | Reference checks must pass first, and a redirect stub or generated index entry must remain. |
+| `hard-deleted` | Physically deleted. | Forbidden by default; allowed only for mistaken tasks with no references, ledger, progress, or review evidence. |
+
+The Soft-deleted / Superseded queue is read-only tracing. It tells users why a task is not active and which task replaced it.

package/docs-release/guides/task-state-machine.md

@@ -0,0 +1,214 @@
+# 任务状态机与生命周期队列
+
+English mirror: `docs-release/guides/task-state-machine.en-US.md`
+
+Coding Agent Harness 的任务状态不是一个单字段。Dashboard 里看到的生命周期由多个文件共同推导：
+
+- `progress.md` 记录原始 `task.state` 和执行证据。
+- `review.md` 记录 Agent Review Submission、material findings 和 Human Review Confirmation。
+- `lesson_candidates.md` 记录 lesson candidate 的人工判定和后续沉淀路由。
+- `10-WALKTHROUGH/Closeout-SSoT.md` 记录任务是否完成收口，并链接 walkthrough。
+- Tombstone / supersede 信息记录任务是否被软删除、合并、归档或替代。
+- Scanner 从这些文件推导 `lifecycleState`、`reviewStatus`、`closeoutStatus`、`taskQueues[]`、`queueReasons[]` 和 `repairPrompt`。
+
+旧版 `reviewQueueState` 只适合表示单一审查页面。PF-024 后，公开模型改为多个生命周期队列：Review、Missing Materials、Blocked、Lessons、Confirmed / Finalized、Soft-deleted / Superseded。
+
+## 原始任务命令流
+
+```mermaid
+stateDiagram-v2
+  [*] --> not_started: new-task
+  not_started --> in_progress: task-start
+  planned --> in_progress: task-start
+  in_progress --> in_progress: task-log / task-phase
+  in_progress --> blocked: task-block
+  blocked --> in_progress: blocker fixed
+  in_progress --> review_submitted: task-review
+  review_submitted --> missing_materials: returned for materials
+  missing_materials --> in_progress: repair materials
+  review_submitted --> blocked: blocking finding
+  review_submitted --> human_confirmed: review-confirm
+  human_confirmed --> finalized: task-complete + closeout
+  finalized --> [*]
+```
+
+`task-review` 表示 Agent 提交审查材料包，不表示人工批准。`review-confirm` 才表示 Human Review Confirmation。`task-complete` / closeout 也不是 review confirmation 的替代品。
+
+## 派生状态
+
+```mermaid
+flowchart TB
+  Progress["progress.md<br/>task.state + evidence"]
+  Review["review.md<br/>Agent Review Submission + findings + Human Review Confirmation"]
+  Lessons["lesson_candidates.md<br/>decision + sedimentation route"]
+  Closeout["Closeout-SSoT.md<br/>closeout row + walkthrough"]
+  Tombstone["tombstone / supersede metadata"]
+  Scanner["scanner"]
+
+  Progress --> Scanner
+  Review --> Scanner
+  Lessons --> Scanner
+  Closeout --> Scanner
+  Tombstone --> Scanner
+
+  Scanner --> Lifecycle["lifecycleState"]
+  Scanner --> ReviewStatus["reviewStatus"]
+  Scanner --> CloseoutStatus["closeoutStatus"]
+  Scanner --> Queues["taskQueues[]"]
+  Scanner --> Reasons["queueReasons[]"]
+  Scanner --> Prompt["repairPrompt"]
+```
+
+| 字段 | 来源 | 作用 |
+| --- | --- | --- |
+| `task.state` | `progress.md` | 原始执行阶段。 |
+| `reviewStatus` | `review.md` + findings + Human Review Confirmation | 区分缺审查、Agent 已提交审查、阻塞、人工确认。 |
+| `closeoutStatus` | `Closeout-SSoT.md` | 区分收口缺失、待处理、已关闭。 |
+| `lifecycleState` | scanner 派生 | Dashboard 的主生命周期语义。 |
+| `taskQueues[]` | scanner 派生 | 任务属于哪些生命周期队列。一个任务可同时在多个治理队列中可见。 |
+| `queueReasons[]` | scanner 派生 | 为什么进入队列，以及对应源文件、字段和修复动作。 |
+| `repairPrompt` | scanner 派生 | 可复制给 Coding Agent 的受限修复提示。 |
+
+## 生命周期矩阵
+
+| 条件 | `lifecycleState` | 含义 |
+| --- | --- | --- |
+| 有 tombstone、superseded-by、archive 或 abandoned 标记 | `soft-deleted-superseded` | 默认隐藏，但保留审计和替代链。 |
+| 有 open P0-P2 finding、非法状态转换、审计失败或人审门禁失败 | `blocked` | 不能进入人工确认，必须先修 blocker 或记录 waiver。 |
+| 标准/复杂任务缺必需文件、章节、证据、lesson decision 或 review submission | `missing-materials` | 需要 Agent 补材料，不属于人审队列。 |
+| 已执行 `task-review`，材料齐全，且未 Human Review Confirmation | `review-submitted` | 真正等待人审。 |
+| 已 Human Review Confirmation，但 closeout / ledger / lessons 仍未全部收口 | `confirmed-finalization-pending` | 责任已转移给确认人，但治理收口仍待完成。 |
+| 已 Human Review Confirmation，且 closeout / ledger / lesson routing 完成 | `finalized` | 真正完成，可只读追溯。 |
+| `task.state = blocked` 但没有 review blocker | `active-blocked` | 执行阻塞。 |
+| `task.state = in_progress` | `active` | 执行中。 |
+| `task.state = planned/not_started` | `ready` | 准备中，默认不进入人审队列。 |
+
+## 审查状态
+
+| `reviewStatus` | 含义 |
+| --- | --- |
+| `missing` | 没有可用 review 文档或缺 Agent Review Submission。 |
+| `required` | 有 review 文档，但还没有足够材料可提交人审。 |
+| `submitted` | Agent 已提交审查材料包；这不是人工确认。 |
+| `blocked-open-findings` | 有 open P0-P2 finding，或 finding 阻塞发布 / 确认。 |
+| `confirmed` | 已写入 `Human Review Confirmation`。 |
+
+Agent 自查、subagent 审查和 coordinator 审查都只能让任务接近 `submitted`。只有 `review-confirm` 或 Workbench 的明确人工确认动作会写入 `Human Review Confirmation`。
+
+## 生命周期队列
+
+Dashboard 的 lifecycle workbench 是多个队列，不是一个混合 review 列表。
+
+```mermaid
+flowchart TD
+  Task["task facts"]
+  Task --> Deleted{"tombstone / superseded / archived?"}
+  Deleted -->|yes| QDeleted["Soft-deleted / Superseded"]
+  Deleted -->|no| Blocker{"blocking finding or invalid transition?"}
+  Blocker -->|yes| QBlocked["Blocked"]
+  Blocker -->|no| Missing{"required materials missing?"}
+  Missing -->|yes| QMissing["Missing Materials"]
+  Missing -->|no| Submitted{"Agent Review Submission exists?"}
+  Submitted -->|yes + not human confirmed| QReview["Review"]
+  Submitted -->|no| Out["not in human review queue"]
+  Submitted -->|yes + human confirmed| Confirmed{"finalization complete?"}
+  Confirmed -->|no| QConfirmed["Confirmed / Finalized"]
+  Confirmed -->|yes| QFinal["Confirmed / Finalized"]
+  Task --> Lessons{"lesson candidate needs decision or sedimentation?"}
+  Lessons -->|yes| QLessons["Lessons"]
+```
+
+| 队列 | 进入条件 | 主要责任方 | 退出条件 |
+| --- | --- | --- | --- |
+| Review | 已提交 review packet，材料齐，且未人工确认。 | human | 人工确认或退回。 |
+| Missing Materials | 缺文件、缺章节、缺证据、缺 lesson decision、缺 review submission 或 phase 未完成。 | agent | 补齐材料并重新提交 review。 |
+| Blocked | 有 blocking finding、状态矛盾、Git 审计失败、完成门禁失败或需要 human waiver。 | agent + human | 修复、关闭、或人工豁免。 |
+| Lessons | lesson candidate 需要判定、保留、拒绝、dry-run promotion 或创建沉淀任务。 | human + agent | 决策完成，或创建可追踪沉淀任务。 |
+| Confirmed / Finalized | 已人工确认，或已结项需要只读追溯。 | coordinator | closeout、ledger、lesson routing 全部完成；之后只读。 |
+| Soft-deleted / Superseded | 任务被软删除、替代、合并、归档或废弃。 | coordinator | 只读追溯；必要时 reopen。 |
+
+Review 队列只等人确认。缺材料、阻塞、lesson 沉淀、已确认待结项、历史替代任务都不应伪装成 Review 队列项。
+
+## 全局表边界
+
+全局治理表只保留索引、状态、路由和审计摘要。它们帮助 Dashboard 找到事实位置，
+但不承载模块局部事实、长证据、执行流水或临时修复提示。
+
+| 层级 | 应该记录什么 | 不应该记录什么 |
+| --- | --- | --- |
+| 全局表：Harness Ledger、Closeout SSoT、Regression SSoT、Cadence Ledger、Delivery SSoT | 当前状态、负责人、任务/模块/详情文档链接、回归 gate、交付顺序、收口或审计摘要 | 模块内步骤、未判定 lesson candidate、完整命令输出、长证据段落、review transcript、临时 repair prompt |
+| 模块层：Module Registry、`module_plan.md` | 模块边界、模块内步骤、handoff、当前阻塞和局部证据索引 | 已 promotion 的全局 lesson 正文、跨模块发布审计总账 |
+| 任务层：`brief.md`、`task_plan.md`、`progress.md`、`review.md`、`lesson_candidates.md`、`lessons/LC-*.md`、`artifacts/INDEX.md` | 执行细节、证据、agent review、候选 lesson、task-local lesson 详情、修复提示和 raw artifact 路由 | 跨任务总账或 promoted lesson 详情正文 |
+
+Checker 对新增全局表行执行该边界。2026-05-24 之前已经存在的过载行默认作为
+`legacy-report-only` 出现在 Dashboard 迁移建议里，不会被自动删除或批量改写。
+新增行如果把 task/module 局部细节继续塞进全局表，会作为 `governance-table-entropy`
+失败项报告。Lesson candidate 留在 `lesson_candidates.md`；进入 `needs-promotion`
+的候选必须链接任务本地 `lessons/LC-*.md` 详情文件，已接受的经验再写入
+`docs/01-GOVERNANCE/lessons/*.md` promoted 详情文档。修复方式是保留必要全局摘要行，
+把细节移动到 module/task/detail 文档并在全局表中链接过去。
+
+## 人工确认闭环
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant Agent as Agent / coordinator
+  participant Human as Human reviewer
+  participant UI as Dashboard Workbench
+  participant API as workbench API
+  participant Lifecycle as task lifecycle writer
+  participant Docs as markdown files
+  participant Scanner as scanner
+
+  Agent->>Docs: write Agent Review Submission + evidence
+  Agent->>UI: submit task-review
+  Human->>UI: open Review queue item
+  UI->>API: POST /api/tasks/review-complete
+  API->>Scanner: read current task facts
+  Scanner-->>API: taskQueues, queueReasons, reviewStatus
+  alt not in Review queue
+    API-->>UI: reject with target queue
+  else missing material or blocker
+    API-->>UI: reject with repairPrompt
+  else accepted
+    API->>Lifecycle: confirmTaskReview()
+    Lifecycle->>Lifecycle: verify Git clean, identity, hooks, allowlist
+    Lifecycle->>Docs: write Human Review Confirmation
+    Lifecycle->>Docs: append review-confirm log
+    Lifecycle->>Lifecycle: commit allowlisted review/progress files
+    Lifecycle->>Docs: record confirmation commit SHA + committed audit status
+    API->>Scanner: regenerate dashboard snapshot
+    API-->>UI: confirmed task
+  end
+```
+
+严格规则：Agent 可以准备 review evidence，也可以提交审查；但任务只有在 Human Review Confirmation block 存在后，才算人工确认。确认动作必须通过 gated auto-commit：Git 状态不干净、提交身份缺失、hook/preflight 失败，或待写文件超出当前任务 `review.md` / `progress.md` 白名单时，CLI 和 Workbench 都会拒绝并返回恢复建议。
+
+CLI-owned 机械写入和 agent-owned 手工切片是两条边界。`new-task`、`task-*`、`task-phase`、`module-step`、`review-confirm`、`lesson-sediment` 和 `lesson-promote --apply` 会在干净 Git root 中加锁、限制写入范围并自动提交。Agent 手工编辑代码、模板或任务文档时仍要在验证后主动提交；无法提交时必须记录 no-commit reason、owner 和下一步，不能把 unrelated dirty changes 混入任务提交。
+
+## Lesson 沉淀
+
+Lesson promotion 默认不写共享 Lessons 表。Dashboard 或 CLI 应优先创建 dry-run 或后续沉淀任务，让执行者先完成：
+
+- 分类 scope 和边界原因。
+- 读取候选行的 `Detail Artifact` 指向的任务本地详情文件，不从表格 brief 复写正文。
+- 检查既有 lesson candidate、lesson detail doc、reference standard、template、checker 是否冲突。
+- 给出目标 diff 或 no-action 理由。
+- 由人工批准后再写 promoted lesson 详情文档或标准文档。
+
+`needs-promotion` 不应阻塞人审确认本身，但必须进入 Lessons 队列，并在 closeout / ledger 中可追踪。
+
+## 软删除与替代
+
+文档库默认不 hard delete 任务目录。
+
+| 状态 | 含义 | 要求 |
+| --- | --- | --- |
+| `active` | 正常任务。 | Dashboard 默认显示。 |
+| `soft-deleted` | 任务被废弃但保留目录。 | 写 tombstone，记录操作者、时间、原因和 reopen eligibility。 |
+| `superseded` | 任务被新任务替代或合并。 | 旧任务记录 `Superseded By`，新任务记录 `Supersedes`。 |
+| `archived` | 任务移入归档。 | 必须先通过引用检查，并留下 redirect stub 或 generated index entry。 |
+| `hard-deleted` | 物理删除。 | 默认禁止；只允许误创建且无引用、无 ledger、无 progress、无 review 证据的任务。 |
+
+Soft-deleted / Superseded 队列用于只读追溯，帮助用户看清“为什么这个任务不在活跃队列里”以及替代任务是谁。

package/docs-release/intl/README.md

@@ -0,0 +1,15 @@
+# International Introductions
+
+Coding Agent Harness uses English as the canonical public language and maintains full executable templates in English and Simplified Chinese.
+
+These lightweight introductions help international readers understand the project quickly. For implementation details, use the English docs first.
+
+| Language | Intro | Support Level |
+| --- | --- | --- |
+| English | [`en-US.md`](en-US.md) | Full docs and templates |
+| Simplified Chinese | [`zh-CN.md`](zh-CN.md) | Full docs and templates |
+| Japanese | [`ja-JP.md`](ja-JP.md) | Intro only |
+| Korean | [`ko-KR.md`](ko-KR.md) | Intro only |
+| French | [`fr-FR.md`](fr-FR.md) | Intro only |
+| Spanish | [`es-ES.md`](es-ES.md) | Intro only |
+| German | [`de-DE.md`](de-DE.md) | Intro only |

package/docs-release/intl/de-DE.md

@@ -0,0 +1,18 @@
+# Coding Agent Harness
+
+Coding Agent Harness legt die Arbeit von Coding Agents im Repository ab, nicht nur im Chatverlauf. Plaene, Fortschritt, Reviews, Migrationsnotizen und Dashboard-Zustaende bleiben beim Code.
+
+Die vollstaendige UI und die ausfuehrbaren Templates werden derzeit in English und Simplified Chinese gepflegt.
+
+## So funktioniert es
+
+1. Installieren Sie den Skill oder starten Sie die CLI mit `npx`.
+2. Der Agent analysiert das Repository und schlaegt einen Initialisierungs- oder Migrationsplan vor.
+3. Das lokale Dashboard zeigt Aufgaben, Warnungen, Nachweise und Review-Status.
+4. Vor der Uebergabe laufen die harness checks.
+
+## Sprachunterstuetzung
+
+Ausfuehrbare Templates und vollstaendige Dokumentation werden derzeit in English und Simplified Chinese gepflegt. Diese Seite ist eine kurze Einfuehrung.
+
+Start here: [`../../README.md`](../../README.md).

package/docs-release/intl/en-US.md

@@ -0,0 +1,18 @@
+# Coding Agent Harness
+
+Coding Agent Harness keeps coding-agent work inside the repository instead of leaving it buried in chat history. Plans, progress, reviews, migration notes, and dashboard snapshots stay with the code.
+
+![Dashboard overview](../assets/dashboard-overview.png)
+
+## How It Works
+
+1. Install the Skill or run the CLI with `npx`.
+2. Let the agent diagnose the repository and propose an initialization or migration plan.
+3. Review tasks, warnings, evidence, and handoff state in the local Dashboard.
+4. Run harness checks before delivery.
+
+## Language Support
+
+English and Simplified Chinese have full README, guide, and executable template support. Other languages currently provide short introductions and route users to the English documentation.
+
+Start with the canonical README: [`../../README.md`](../../README.md).

package/docs-release/intl/es-ES.md

@@ -0,0 +1,18 @@
+# Coding Agent Harness
+
+Coding Agent Harness deja el trabajo de los agentes de programacion dentro del repositorio, no solo en el historial del chat. Planes, progreso, revisiones, notas de migracion y estados del Dashboard quedan junto al codigo.
+
+La interfaz completa y las plantillas ejecutables se mantienen actualmente en English y Simplified Chinese.
+
+## Como funciona
+
+1. Instala el Skill o ejecuta la CLI con `npx`.
+2. El agente diagnostica el repositorio y propone un plan de inicializacion o migracion.
+3. El Dashboard local muestra tareas, advertencias, evidencia y estado de revision.
+4. Ejecuta las verificaciones de harness antes de entregar.
+
+## Idiomas
+
+Las plantillas ejecutables y la documentacion completa se mantienen en English y Simplified Chinese. Esta pagina es una introduccion breve.
+
+Start here: [`../../README.md`](../../README.md).

package/docs-release/intl/fr-FR.md

@@ -0,0 +1,18 @@
+# Coding Agent Harness
+
+Coding Agent Harness garde le travail des agents de code dans le depot, pas seulement dans l'historique de discussion. Plans, progression, revues, notes de migration et etats du Dashboard restent avec le code.
+
+L'interface complete et les modeles executables sont actuellement maintenus en English et Simplified Chinese.
+
+## Fonctionnement
+
+1. Installez le Skill ou lancez le CLI avec `npx`.
+2. L'agent analyse le depot et propose un plan d'initialisation ou de migration.
+3. Le Dashboard local affiche les taches, alertes, preuves et etats de revue.
+4. Les verifications harness confirment l'etat avant livraison.
+
+## Langues
+
+Les modeles executables et la documentation complete sont maintenus en English et Simplified Chinese. Cette page est une introduction courte.
+
+Start here: [`../../README.md`](../../README.md).

package/docs-release/intl/ja-JP.md

@@ -0,0 +1,18 @@
+# Coding Agent Harness
+
+Coding Agent Harness は、コーディングエージェントの作業をチャット履歴ではなくリポジトリに残すための仕組みです。計画、進捗、レビュー、移行メモ、Dashboard の状態がコードと一緒に残ります。
+
+UI と実行可能なテンプレートは、現在 English と Simplified Chinese を中心に保守されています。
+
+## 使い方
+
+1. Skill をインストールするか、`npx` で CLI を実行します。
+2. エージェントがリポジトリを診断し、初期化または移行計画を提示します。
+3. ローカル Dashboard でタスク、警告、証拠、レビュー状態を確認します。
+4. 受け渡し前に harness check を実行します。
+
+## 言語サポート
+
+実行可能なテンプレートと詳細ドキュメントは、現在 English と Simplified Chinese を中心に保守されています。このページは概要紹介です。
+
+Start here: [`../../README.md`](../../README.md).

package/docs-release/intl/ko-KR.md

@@ -0,0 +1,18 @@
+# Coding Agent Harness
+
+Coding Agent Harness는 코딩 에이전트의 작업을 채팅 기록이 아니라 저장소 안에 남기기 위한 도구입니다. 계획, 진행 상황, 리뷰, 마이그레이션 메모, Dashboard 상태가 코드와 함께 남습니다.
+
+전체 UI와 실행 가능한 템플릿은 현재 English와 Simplified Chinese를 중심으로 유지됩니다.
+
+## 사용 방식
+
+1. Skill을 설치하거나 `npx`로 CLI를 실행합니다.
+2. 에이전트가 저장소를 진단하고 초기화 또는 마이그레이션 계획을 제안합니다.
+3. 로컬 Dashboard에서 작업, 경고, 증거, 리뷰 상태를 확인합니다.
+4. 전달 전에 harness check를 실행합니다.
+
+## 언어 지원
+
+실행 가능한 템플릿과 자세한 문서는 현재 English와 Simplified Chinese를 중심으로 유지됩니다. 이 페이지는 간단한 소개입니다.
+
+Start here: [`../../README.md`](../../README.md).

package/docs-release/intl/zh-CN.md

@@ -0,0 +1,18 @@
+# Coding Agent Harness
+
+Coding Agent Harness 把 Coding Agent 的计划、进度、审查、迁移记录和 Dashboard 快照留在仓库里，而不是散在聊天记录里。
+
+![Dashboard overview](../assets/dashboard-overview.png)
+
+## 怎么用
+
+1. 安装 Skill，或用 `npx` 运行 CLI。
+2. 让 Agent 先诊断仓库，再给出初始化或迁移计划。
+3. 在本地 Dashboard 里查看任务、风险、证据和审查状态。
+4. 交付前运行 harness 检查。
+
+## 语言支持
+
+英文和简体中文提供完整 README、指南和可执行模板。其他语言目前是简介和入口页，具体实施请优先阅读英文文档。
+
+中文 README：[`../../README.zh-CN.md`](../../README.zh-CN.md)。

package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/brief.md

@@ -0,0 +1,13 @@
+# Demo task
+
+## Brief
+
+Minimal example task used by the dashboard smoke tests.
+
+## Task ID
+
+`demo-task`
+
+## Outcome
+
+Show a readable task summary in the static dashboard without requiring an editor.

package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/findings.md

@@ -0,0 +1,7 @@
+# Demo Task Findings
+
+## Findings
+
+| ID | Severity | Finding | Status | Owner |
+| --- | --- | --- | --- | --- |
+| F-001 | P3 | Minimal project fixture has no open implementation findings. | closed | coordinator |

package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/lesson_candidates.md

@@ -0,0 +1,24 @@
+# Demo Task - Lesson Candidates
+
+## Candidate Status
+
+| Field | Value |
+| --- | --- |
+| Schema version | lesson-candidate-v1 |
+| Task-level status | no-candidate-accepted |
+| Review gate | candidate-file-present |
+| Review decision | accepted-no-candidate |
+| Promotion state | not-promoted |
+| Closeout token | checked-candidate:LC-20260101-000 |
+| Source task | demo-task |
+| Owner | coordinator |
+| Last updated | 2026-01-01 |
+
+## Candidates
+
+| ID | Row Status | Title | Why It Might Matter | Review Decision | Promotion Target |
+| --- | --- | --- | --- | --- | --- |
+
+## No-Candidate Reason
+
+The example task exists only to demonstrate dashboard parsing and does not produce a reusable governance lesson.

package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/progress.md

@@ -8,4 +8,4 @@ in-progress
 
 | Date | Update | Evidence |
 | --- | --- | --- |
-| 2026-05-18 | Created example roadmap | report:TARGET:docs/09-PLANNING/TASKS/demo-task/visual_roadmap.md:example phase table |
+| 2026-05-18 | Created example visual map | report:TARGET:docs/09-PLANNING/TASKS/demo-task/visual_map.md:example phase table |

package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/task_plan.md

@@ -1,8 +1,10 @@
 # Demo Task
 
+Task Contract: harness-task/v1
+
 ## Goal
 
-Show the v1.0 visual roadmap contract.
+Show the v1.0 visual map contract.
 
 ## Scope
 
@@ -11,4 +13,4 @@ Public example only.
 ## Execution & Visualization Files
 
 - `execution_strategy.md`
-- `visual_roadmap.md`
+- `visual_map.md`