coding-agent-harness 1.0.2 → 1.0.5

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

@@ -0,0 +1,224 @@
+# 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 review evidence.
+- `INDEX.md` stores Task Audit Metadata, including task creation and human review confirmation audit fields.
+- `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 confirmation gate and writes its audit fields to `INDEX.md`. `task-complete` / closeout is not a substitute for review confirmation.
+
+## Phase Kind Map
+
+`visual_map.md` is the machine-readable phase timeline. New phase tables may include `Kind`, `Exit Command`, and `Actor` columns:
+
+| Kind | Purpose | Counts Toward Implementation Completion | Typical Exit |
+| --- | --- | --- | --- |
+| `init` | Scope, context, budget, and execution strategy. | no | `harness task-start <task-id>` |
+| `execution` | Implementation, documentation, and verification slices. | yes | `harness task-phase <task-id> <phase-id> --state done --completion 100 --evidence present` |
+| `gate` | Agent review submission, human confirmation, lesson routing, walkthrough, and closeout. | no | `harness task-review`, `harness review-confirm`, or `harness task-complete` |
+
+Older phase tables without `Kind` remain valid and are treated as `execution`.
+The Dashboard implementation score uses non-skipped `execution` phases only.
+Gate phases explain the next lifecycle action and owner; they do not make a finished implementation look incomplete.
+Agents may run `Exit Command` values with `Actor: agent`. `Actor: human` gates, especially `review-confirm`, require explicit human action.
+
+## Derived State
+
+```mermaid
+flowchart TB
+  Progress["progress.md<br/>task.state + evidence"]
+  Index["INDEX.md<br/>Task Audit Metadata"]
+  Review["review.md<br/>Agent Review Submission + findings + evidence"]
+  Lessons["lesson_candidates.md<br/>decision + sedimentation route"]
+  Closeout["Closeout-SSoT.md<br/>closeout row + walkthrough"]
+  Tombstone["tombstone / supersede metadata"]
+  Scanner["scanner"]
+
+  Progress --> Scanner
+  Index --> 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` | `INDEX.md` Task Audit Metadata + `review.md` findings/submission | 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 `INDEX.md` does not show human confirmation | `review-submitted` | Truly waiting for human review. |
+| `INDEX.md` shows human confirmation, but closeout / ledger / lessons are not fully closed | `confirmed-finalization-pending` | Accountability moved to the reviewer, but governance closeout remains. |
+| `INDEX.md` shows human confirmation, 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` | `INDEX.md` Task Audit Metadata has `Human Review Status: confirmed` and committed audit fields. |
+
+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 the confirmation audit fields in `INDEX.md`.
+
+## 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 confirmation fields to INDEX.md
+    Lifecycle->>Lifecycle: commit allowlisted INDEX.md
+    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 task `INDEX.md` contains committed confirmation audit fields. 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 `INDEX.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,231 @@
+# 任务状态机与生命周期队列
+
+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 和审查证据。
+- `INDEX.md` 记录任务审计元数据，包括任务创建和人工确认审计字段。
+- `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` 才表示人工确认门禁，并把审计字段写入 `INDEX.md`。`task-complete` / closeout 也不是 review confirmation 的替代品。
+
+## 阶段类型地图
+
+`visual_map.md` 是机器可读的阶段时间线。新的阶段表可以包含 `Kind`、`Exit Command` 和 `Actor` 三列：
+
+| Kind | 作用 | 是否计入实现完成度 | 典型出口 |
+| --- | --- | --- | --- |
+| `init` | 范围、上下文、预算和执行策略。 | 否 | `harness task-start <task-id>` |
+| `execution` | 实现、文档和验证切片。 | 是 | `harness task-phase <task-id> <phase-id> --state done --completion 100 --evidence present` |
+| `gate` | Agent 提交审查、人工确认、lesson routing、walkthrough 和 closeout。 | 否 | `harness task-review`、`harness review-confirm` 或 `harness task-complete` |
+
+旧阶段表没有 `Kind` 也继续有效，默认按 `execution` 处理。
+Dashboard 实现完成度只计算非 skipped 的 `execution` 阶段。
+Gate 阶段用于解释下一步生命周期动作和责任人，不会让已完成的实现看起来未完成。
+Agent 只能执行 `Actor: agent` 的 `Exit Command`。`Actor: human` 的 gate，尤其是 `review-confirm`，必须由人工明确执行。
+
+## 派生状态
+
+```mermaid
+flowchart TB
+  Progress["progress.md<br/>task.state + evidence"]
+  Index["INDEX.md<br/>Task Audit Metadata"]
+  Review["review.md<br/>Agent Review Submission + findings + evidence"]
+  Lessons["lesson_candidates.md<br/>decision + sedimentation route"]
+  Closeout["Closeout-SSoT.md<br/>closeout row + walkthrough"]
+  Tombstone["tombstone / supersede metadata"]
+  Scanner["scanner"]
+
+  Progress --> Scanner
+  Index --> 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` | `INDEX.md` Task Audit Metadata + `review.md` findings/submission | 区分缺审查、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`，材料齐全，且 `INDEX.md` 尚未显示人工确认 | `review-submitted` | 真正等待人审。 |
+| `INDEX.md` 已显示人工确认，但 closeout / ledger / lessons 仍未全部收口 | `confirmed-finalization-pending` | 责任已转移给确认人，但治理收口仍待完成。 |
+| `INDEX.md` 已显示人工确认，且 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` | `INDEX.md` Task Audit Metadata 包含 `Human Review Status: confirmed` 和已提交审计字段。 |
+
+Agent 自查、subagent 审查和 coordinator 审查都只能让任务接近 `submitted`。只有 `review-confirm` 或 Workbench 的明确人工确认动作会把确认审计字段写入 `INDEX.md`。
+
+## 生命周期队列
+
+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 confirmation fields to INDEX.md
+    Lifecycle->>Lifecycle: commit allowlisted INDEX.md
+    Lifecycle->>Docs: record confirmation commit SHA + committed audit status
+    API->>Scanner: regenerate dashboard snapshot
+    API-->>UI: confirmed task
+  end
+```
+
+严格规则：Agent 可以准备 review evidence，也可以提交审查；但任务只有在任务 `INDEX.md` 包含已提交的确认审计字段后，才算人工确认。确认动作必须通过 gated auto-commit：Git 状态不干净、提交身份缺失、hook/preflight 失败，或待写文件超出当前任务 `INDEX.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/en-US.md

@@ -2,7 +2,7 @@
 
 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-en.png)
+![Dashboard overview](../assets/dashboard-overview.png)
 
 ## How It Works
 

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

@@ -2,7 +2,7 @@
 
 Coding Agent Harness 把 Coding Agent 的计划、进度、审查、迁移记录和 Dashboard 快照留在仓库里，而不是散在聊天记录里。
 
-![Dashboard overview](../assets/dashboard-overview-en.png)
+![Dashboard overview](../assets/dashboard-overview.png)
 
 ## 怎么用
 

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

@@ -0,0 +1,60 @@
+# Demo task - Task Package Index
+
+Task Contract: harness-task/v1
+
+## Task Identity
+
+| Field | Value |
+| --- | --- |
+| Task ID | `demo-task` |
+| Budget | `standard` |
+| Preset | `none` |
+| Module | `n/a` |
+| Long-running | `no` |
+| Created | 2026-05-25 |
+
+## Task Audit Metadata
+
+| Field | Value |
+| --- | --- |
+| Created By | historical-backfill |
+| Created At | 2026-05-25 |
+| Command Shape | n/a |
+| Budget | standard |
+| Template Source | examples/minimal-project historical fixture |
+| Task Creator | n/a |
+| Task Creator Source | legacy-unavailable |
+| Human Review Status | not-confirmed |
+| Confirmation ID | n/a |
+| Confirmed At | n/a |
+| Reviewer | n/a |
+| Reviewer Email | n/a |
+| Confirm Text | n/a |
+| Evidence Checked | n/a |
+| Review Commit SHA | n/a |
+| Audit Source | migrated-legacy-scaffold |
+| Audit Status | migrated |
+| Exception Reason | Existing demo task predates scaffold provenance enforcement. |
+| Message | n/a |
+| Migration Status | migrated |
+| Migrated From | brief.md#Scaffold Provenance |
+| Legacy Extra Fields | {} |
+| Migration Notes | example fixture backfilled to INDEX audit metadata |
+
+## Core Contract Files
+
+| File | Purpose |
+| --- | --- |
+| `brief.md` | Human-readable task summary and context entry. |
+| `task_plan.md` | Current task goal, scope, selected budget, acceptance, and operating decisions. |
+| `visual_map.md` | Phase map, evidence status, next lifecycle commands, and supporting diagrams. |
+| `progress.md` | Execution log, verification evidence, decisions, and handoff notes. |
+
+## Standard Task Files
+
+| File | Purpose |
+| --- | --- |
+| `execution_strategy.md` | Execution mode, ownership, conflict control, and evidence strategy. |
+| `findings.md` | Findings, research notes, accepted risks, and unresolved questions. |
+| `lesson_candidates.md` | Task-local lesson candidate decisions before closeout. |
+| `review.md` | Agent review submission, adversarial review, findings, evidence, and routing. |

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coding-agent-harness",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "description": "Document governance kernel for long-running coding agents.",
   "type": "module",
   "keywords": [
@@ -31,17 +31,23 @@
     "status": "node scripts/harness.mjs status --json .",
     "dashboard": "node scripts/harness.mjs dashboard --out tmp/harness-dashboard.html examples/minimal-project",
     "dashboard:folder": "node scripts/harness.mjs dashboard --out-dir tmp/harness-dashboard examples/minimal-project",
-    "smoke:dashboard": "node scripts/smoke-dashboard.mjs",
-    "test": "node scripts/test-harness.mjs"
+    "pack:dry-run": "npm pack --dry-run --json",
+    "postinstall": "node scripts/postinstall.mjs",
+    "smoke:dashboard": "node tests/smoke-dashboard.mjs",
+    "test": "node tests/run-all.mjs"
   },
   "files": [
     "README.md",
     "README.en-US.md",
     "README.zh-CN.md",
+    "CONTRIBUTING.md",
     "CHANGELOG.md",
     "SKILL.md",
     "LICENSE",
+    "LICENSE-EXCEPTION.md",
     "references/",
+    "skills/",
+    "presets/",
     "templates/",
     "templates-zh-CN/",
     "scripts/",
@@ -51,5 +57,5 @@
   "engines": {
     "node": ">=18"
   },
-  "license": "MIT"
+  "license": "AGPL-3.0-or-later"
 }

package/presets/legacy-migration/checks/preset-check.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+console.log(JSON.stringify({ status: "pass", preset: "legacy-migration", scope: "manifest" }, null, 2));