coding-agent-harness 1.0.4 → 1.0.6

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

@@ -5,9 +5,10 @@ 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.
+- `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.
+- `coding-agent-harness/governance/generated/Closeout-Index.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.
 
@@ -32,20 +33,37 @@ stateDiagram-v2
   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.
+`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"]
-  Review["review.md<br/>Agent Review Submission + findings + Human Review Confirmation"]
+  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"]
+  Closeout["Closeout-Index.md<br/>closeout row + walkthrough"]
   Tombstone["tombstone / supersede metadata"]
   Scanner["scanner"]
 
   Progress --> Scanner
+  Index --> Scanner
   Review --> Scanner
   Lessons --> Scanner
   Closeout --> Scanner
@@ -62,8 +80,8 @@ flowchart TB
 | 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. |
+| `reviewStatus` | `INDEX.md` Task Audit Metadata + `review.md` findings/submission | Separates missing review, agent-submitted review, blockers, and human confirmation. |
+| `closeoutStatus` | `Closeout-Index.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. |
@@ -76,9 +94,9 @@ flowchart TB
 | 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-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. |
@@ -91,9 +109,9 @@ flowchart TB
 | `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. |
+| `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 `Human Review Confirmation`.
+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
 
@@ -135,11 +153,11 @@ Global governance tables only keep index, state, route, and audit summary. They
 
 | 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 |
+| Global tables: Harness Ledger, Closeout Index, 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.
+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 `coding-agent-harness/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
 
@@ -167,16 +185,15 @@ sequenceDiagram
   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: 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 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.
+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.
 

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

@@ -5,9 +5,10 @@ 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。
+- `review.md` 记录 Agent Review Submission、material findings 和审查证据。
+- `INDEX.md` 记录任务审计元数据，包括任务创建和人工确认审计字段。
 - `lesson_candidates.md` 记录 lesson candidate 的人工判定和后续沉淀路由。
-- `10-WALKTHROUGH/Closeout-SSoT.md` 记录任务是否完成收口，并链接 walkthrough。
+- `coding-agent-harness/governance/generated/Closeout-Index.md` 记录任务是否完成收口，并链接 walkthrough。
 - Tombstone / supersede 信息记录任务是否被软删除、合并、归档或替代。
 - Scanner 从这些文件推导 `lifecycleState`、`reviewStatus`、`closeoutStatus`、`taskQueues[]`、`queueReasons[]` 和 `repairPrompt`。
 
@@ -32,20 +33,37 @@ stateDiagram-v2
   finalized --> [*]
 ```
 
-`task-review` 表示 Agent 提交审查材料包，不表示人工批准。`review-confirm` 才表示 Human Review Confirmation。`task-complete` / closeout 也不是 review confirmation 的替代品。
+`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"]
-  Review["review.md<br/>Agent Review Submission + findings + Human Review Confirmation"]
+  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"]
+  Closeout["Closeout-Index.md<br/>closeout row + walkthrough"]
   Tombstone["tombstone / supersede metadata"]
   Scanner["scanner"]
 
   Progress --> Scanner
+  Index --> Scanner
   Review --> Scanner
   Lessons --> Scanner
   Closeout --> Scanner
@@ -62,8 +80,8 @@ flowchart TB
 | 字段 | 来源 | 作用 |
 | --- | --- | --- |
 | `task.state` | `progress.md` | 原始执行阶段。 |
-| `reviewStatus` | `review.md` + findings + Human Review Confirmation | 区分缺审查、Agent 已提交审查、阻塞、人工确认。 |
-| `closeoutStatus` | `Closeout-SSoT.md` | 区分收口缺失、待处理、已关闭。 |
+| `reviewStatus` | `INDEX.md` Task Audit Metadata + `review.md` findings/submission | 区分缺审查、Agent 已提交审查、阻塞、人工确认。 |
+| `closeoutStatus` | `Closeout-Index.md` | 区分收口缺失、待处理、已关闭。 |
 | `lifecycleState` | scanner 派生 | Dashboard 的主生命周期语义。 |
 | `taskQueues[]` | scanner 派生 | 任务属于哪些生命周期队列。一个任务可同时在多个治理队列中可见。 |
 | `queueReasons[]` | scanner 派生 | 为什么进入队列，以及对应源文件、字段和修复动作。 |
@@ -76,9 +94,9 @@ flowchart TB
 | 有 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-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` | 准备中，默认不进入人审队列。 |
@@ -91,9 +109,9 @@ flowchart TB
 | `required` | 有 review 文档，但还没有足够材料可提交人审。 |
 | `submitted` | Agent 已提交审查材料包；这不是人工确认。 |
 | `blocked-open-findings` | 有 open P0-P2 finding，或 finding 阻塞发布 / 确认。 |
-| `confirmed` | 已写入 `Human Review Confirmation`。 |
+| `confirmed` | `INDEX.md` Task Audit Metadata 包含 `Human Review Status: confirmed` 和已提交审计字段。 |
 
-Agent 自查、subagent 审查和 coordinator 审查都只能让任务接近 `submitted`。只有 `review-confirm` 或 Workbench 的明确人工确认动作会写入 `Human Review Confirmation`。
+Agent 自查、subagent 审查和 coordinator 审查都只能让任务接近 `submitted`。只有 `review-confirm` 或 Workbench 的明确人工确认动作会把确认审计字段写入 `INDEX.md`。
 
 ## 生命周期队列
 
@@ -136,7 +154,7 @@ Review 队列只等人确认。缺材料、阻塞、lesson 沉淀、已确认待
 
 | 层级 | 应该记录什么 | 不应该记录什么 |
 | --- | --- | --- |
-| 全局表：Harness Ledger、Closeout SSoT、Regression SSoT、Cadence Ledger、Delivery SSoT | 当前状态、负责人、任务/模块/详情文档链接、回归 gate、交付顺序、收口或审计摘要 | 模块内步骤、未判定 lesson candidate、完整命令输出、长证据段落、review transcript、临时 repair prompt |
+| 全局表：Harness Ledger、Closeout Index、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 详情正文 |
 
@@ -145,7 +163,7 @@ Checker 对新增全局表行执行该边界。2026-05-24 之前已经存在的
 新增行如果把 task/module 局部细节继续塞进全局表，会作为 `governance-table-entropy`
 失败项报告。Lesson candidate 留在 `lesson_candidates.md`；进入 `needs-promotion`
 的候选必须链接任务本地 `lessons/LC-*.md` 详情文件，已接受的经验再写入
-`docs/01-GOVERNANCE/lessons/*.md` promoted 详情文档。修复方式是保留必要全局摘要行，
+`coding-agent-harness/governance/lessons/*.md` promoted 详情文档。修复方式是保留必要全局摘要行，
 把细节移动到 module/task/detail 文档并在全局表中链接过去。
 
 ## 人工确认闭环
@@ -174,16 +192,15 @@ sequenceDiagram
   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: 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，也可以提交审查；但任务只有在 Human Review Confirmation block 存在后，才算人工确认。确认动作必须通过 gated auto-commit：Git 状态不干净、提交身份缺失、hook/preflight 失败，或待写文件超出当前任务 `review.md` / `progress.md` 白名单时，CLI 和 Workbench 都会拒绝并返回恢复建议。
+严格规则：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 混入任务提交。
 

package/docs-release/guides/typescript-runtime-migration-closeout.md

@@ -0,0 +1,96 @@
+# TypeScript Runtime Migration Closeout
+
+This closeout records the public package rule after the progressive JavaScript to
+TypeScript runtime migration. The package now executes committed
+`dist/**/*.mjs` artifacts, while `scripts/**/*.mts` and `tests/**/*.mts` are the
+source ownership surfaces. Historical checked-in `scripts/**/*.mjs` and
+`tests/**/*.mjs` shims have been removed after the dist observation gates passed.
+
+## Current State
+
+All Node runtime and test sources under `scripts/` and `tests/` are now
+TypeScript-first:
+
+- `scripts/**/*.mts` builds to committed `dist/**/*.mjs` artifacts.
+- `tests/**/*.mts` runs through the built test runner.
+- `dist/**/*.mjs` is the package runtime surface for npm bin, npm scripts, and
+  postinstall.
+- `scripts/**/*.mjs` and `tests/**/*.mjs` have a final inventory of zero.
+
+The npm package publishes `dist/` and no longer publishes `scripts/` or `tests/`.
+This keeps installed execution independent from TypeScript source files and from
+the deleted historical shims.
+
+## Final Closeout Evidence
+
+The TS-first runtime closeout is based on the PR-28 deletion gate plus the PR-29
+final inventory:
+
+- final `scripts/` and `tests/` JavaScript shim inventory is zero;
+- packed package file inventory includes `dist/` and excludes `scripts/` and
+  `tests/`;
+- Node 24 tarball smoke proved installed `harness` commands execute from
+  `dist/` with a temporary `HOME` and PATH isolated to the temp consumer
+  `node_modules/.bin`;
+- source-package and target-project checks pass through `dist/harness.mjs`;
+- snapshot matrix reported no blocking drift after shim deletion.
+
+That means remaining package-included JavaScript is not unfinished CLI/test
+runtime migration work. The remaining files are the documented preset and
+dashboard exceptions below.
+
+## Runtime Contract
+
+The package is an ESM package and its current public runtime contract points at
+the committed dist build output:
+
+- `package.json` maps the `harness` executable to `dist/harness.mjs`.
+- npm postinstall runs `dist/postinstall.mjs`.
+- npm helper scripts such as `check`, `status`, and dashboard generation run
+  through `dist/harness.mjs`.
+- Runtime modules import sibling `.mjs` files inside `dist/`, so installed
+  package execution does not depend on TypeScript loaders.
+
+The PR-27 observation gate proved the package was dist-primary before deletion.
+The PR-28 deletion gate keeps that proof executable by requiring final inventory
+counts of zero for `scripts/**/*.mjs` and `tests/**/*.mjs`, package dry-run with
+no `scripts/**` or `tests/**`, snapshot matrix, and Node 24 tarball smoke.
+
+## Documented Exceptions
+
+The following package-included JavaScript files are not part of the Node runtime
+source-twin cleanup target.
+
+| Path | Reason To Keep |
+| --- | --- |
+| `presets/legacy-migration/checks/preset-check.mjs` | Preset executable hook. It belongs to the preset extension surface, not core runtime migration. |
+| `presets/legacy-migration/scripts/plan-work-queue.mjs` | Preset helper script loaded as packaged preset material. |
+| `presets/legacy-migration/scripts/scaffold-task-contracts.mjs` | Preset helper script loaded as packaged preset material. |
+| `templates/dashboard/assets/app-src/*.js` | Browser dashboard source assets. They are shipped as template assets, not Node runtime modules. |
+| `templates/dashboard/assets/app.js` | Built browser dashboard bundle. Keep until a separate dashboard asset pipeline replaces it. |
+| `templates/dashboard/assets/i18n.js` | Browser dashboard localization asset. |
+| `templates/dashboard/assets/markdown-reader.js` | Browser dashboard helper asset. |
+| `templates/dashboard/assets/mermaid-renderer.js` | Browser dashboard helper asset. |
+
+These files should not be deleted by a runtime `.mjs` cleanup PR. If they are
+migrated later, use a dedicated preset or dashboard asset migration plan with its
+own package and browser checks.
+
+## Future Cleanup Gate
+
+Any future PR that removes or migrates the remaining preset/dashboard JavaScript
+exceptions must prove all of the following for its own surface:
+
+- package `bin` and `postinstall` still work from a packed tarball;
+- installed package execution works with a temp `HOME` and PATH isolated to the
+  temp consumer `node_modules/.bin`;
+- `npm pack --dry-run --json` includes the intended runtime files and excludes
+  private, temporary, and test-only material;
+- snapshot matrix has no blocking drift;
+- real target smoke passes;
+- the PR is independently revertible without reverting the earlier dist runtime
+  cutover or the PR-28 historical shim deletion.
+
+`dist/**/*.mjs` remains the supported package execution surface. Preset `.mjs`
+hooks and dashboard browser `.js` assets remain documented exceptions, not
+unfinished CLI runtime migration work.

package/examples/minimal-project/AGENTS.md

@@ -1,4 +1,4 @@
 # Minimal Harness Example
 
-Use `docs/11-REFERENCE/` for project rules and `docs/09-PLANNING/TASKS/` for
-task execution records.
+Use `coding-agent-harness/governance/standards/` for project rules and
+`coding-agent-harness/planning/tasks/` for task execution records.

package/examples/minimal-project/coding-agent-harness/harness.yaml

@@ -0,0 +1,14 @@
+version: 2
+locale: en-US
+capabilities:
+  - core
+  - dashboard
+structure:
+  harnessRoot: coding-agent-harness
+  planningRoot: coding-agent-harness/planning
+  tasksRoot: coding-agent-harness/planning/tasks
+  modulesRoot: coding-agent-harness/planning/modules
+  externalRoot: coding-agent-harness/planning/external
+  governanceRoot: coding-agent-harness/governance
+  generatedRoot: coding-agent-harness/governance/generated
+  regressionRoot: coding-agent-harness/governance/regression

package/examples/minimal-project/coding-agent-harness/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/coding-agent-harness/planning/tasks/demo-task/progress.md

@@ -0,0 +1,11 @@
+# Demo Task - Progress
+
+## Status
+
+in-progress
+
+## Updates
+
+| Date | Update | Evidence |
+| --- | --- | --- |
+| 2026-05-18 | Created example visual map | report:TARGET:coding-agent-harness/planning/tasks/demo-task/visual_map.md:example phase table |

package/examples/minimal-project/{docs/09-PLANNING/TASKS → coding-agent-harness/planning/tasks}/demo-task/review.md

@@ -14,7 +14,7 @@ No material finding for this example.
 
 | Evidence ID | Type | Path | Summary |
 | --- | --- | --- | --- |
-| E-001 | review | TARGET:docs/09-PLANNING/TASKS/demo-task/task_plan.md | Visual roadmap table exists |
+| E-001 | review | TARGET:coding-agent-harness/planning/tasks/demo-task/task_plan.md | Visual map table exists |
 
 ## Findings
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coding-agent-harness",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Document governance kernel for long-running coding agents.",
   "type": "module",
   "keywords": [
@@ -23,18 +23,23 @@
     "url": "https://github.com/FairladyZ625/coding-agent-harness/issues"
   },
   "bin": {
-    "harness": "scripts/harness.mjs"
+    "harness": "dist/harness.mjs"
   },
   "scripts": {
-    "check": "node scripts/harness.mjs check --profile source-package .",
-    "check:private": "node scripts/harness.mjs check --profile private-harness .harness-private",
-    "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",
+    "check": "node dist/harness.mjs check --profile source-package .",
+    "check:private": "node dist/harness.mjs check --profile private-harness .harness-private",
+    "build:runtime": "node scripts/build-dist.mts",
+    "prepack": "node scripts/build-dist.mts --quiet",
+    "typecheck": "npm exec --yes --package typescript@5.9.3 -- tsc -p tsconfig.json",
+    "typecheck:guards": "node dist/check-type-boundaries.mjs",
+    "status": "node dist/harness.mjs status --json .",
+    "dashboard": "node dist/harness.mjs dashboard --out tmp/harness-dashboard.html examples/minimal-project",
+    "dashboard:folder": "node dist/harness.mjs dashboard --out-dir tmp/harness-dashboard examples/minimal-project",
     "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"
+    "postinstall": "node dist/postinstall.mjs",
+    "observe:dist": "node dist/check-dist-observation.mjs --skip-pack --skip-install-smoke",
+    "smoke:dashboard": "node dist/run-built-tests.mjs --test tests/smoke-dashboard.mjs",
+    "test": "node dist/run-built-tests.mjs"
   },
   "files": [
     "README.md",
@@ -43,18 +48,22 @@
     "CONTRIBUTING.md",
     "CHANGELOG.md",
     "SKILL.md",
+    "tsconfig.json",
+    "tsconfig.dist.json",
+    "tsconfig.runtime.json",
     "LICENSE",
+    "LICENSE-EXCEPTION.md",
     "references/",
     "skills/",
     "presets/",
     "templates/",
     "templates-zh-CN/",
-    "scripts/",
+    "dist/",
     "docs-release/",
     "examples/"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=24"
   },
-  "license": "MIT"
+  "license": "AGPL-3.0-or-later"
 }

package/presets/legacy-migration/preset.yaml

@@ -43,7 +43,7 @@ templateValues:
 entrypoints:
   newTask:
     type: template
-    writes: [docs/09-PLANNING/TASKS/**]
+    writes: [coding-agent-harness/planning/tasks/**]
     reads: [session.json]
     audit: true
     templates:
@@ -55,19 +55,19 @@ entrypoints:
   plan:
     type: script
     command: scripts/plan-work-queue.mjs
-    writes: [docs/09-PLANNING/TASKS/**]
+    writes: [coding-agent-harness/planning/tasks/**]
     reads: [docs/**, .git/**]
     audit: true
   scaffold:
     type: script
     command: scripts/scaffold-task-contracts.mjs
-    writes: [docs/09-PLANNING/TASKS/**]
+    writes: [coding-agent-harness/planning/tasks/**]
     reads: [docs/**]
     audit: true
   check:
     type: check
     command: checks/preset-check.mjs
-    writes: [docs/09-PLANNING/TASKS/**]
+    writes: [coding-agent-harness/planning/tasks/**]
     reads: [docs/**]
     audit: true
 workbench:
@@ -130,5 +130,5 @@ audit:
   evidenceFiles: [preset-manifest.json, preset-audit.json, write-scope.json]
 writeScopes:
   taskArtifacts:
-    path: docs/09-PLANNING/TASKS/**
+    path: coding-agent-harness/planning/tasks/**
     access: write

package/presets/legacy-migration/templates/execution_strategy.append.md

@@ -15,4 +15,4 @@ Declare lanes before dispatching workers.
 
 | Lane ID | Allowed globs | Forbidden globs | Shared file owner | Worktree / branch | Handoff path | Merge order | Verification command |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| coordinator | docs/09-PLANNING/TASKS/** | AGENTS.md, CLAUDE.md, docs/Harness-Ledger.md until closeout | coordinator | current | progress.md | 1 | harness check --profile target-project . |
+| coordinator | coding-agent-harness/planning/tasks/** | AGENTS.md, CLAUDE.md, coding-agent-harness/governance/generated/Harness-Ledger.md until closeout | coordinator | current | progress.md | 1 | harness check --profile target-project . |

package/presets/lesson-sedimentation/preset.yaml

@@ -9,14 +9,14 @@ task:
 entrypoints:
   newTask:
     type: template
-    writes: [docs/09-PLANNING/TASKS/**]
-    reads: [docs/09-PLANNING/TASKS/**/lesson_candidates.md]
+    writes: [coding-agent-harness/planning/tasks/**]
+    reads: [coding-agent-harness/planning/tasks/**/lesson_candidates.md]
     audit: true
     templates:
       prompt: templates/prompt.md
 writeScopes:
   taskDocs:
-    path: docs/09-PLANNING/TASKS/**
+    path: coding-agent-harness/planning/tasks/**
     access: write
 audit:
   manifestRequired: true

package/presets/module/preset.yaml

@@ -8,7 +8,7 @@ task:
 entrypoints:
   newTask:
     type: template
-    writes: [docs/09-PLANNING/**]
+    writes: [coding-agent-harness/planning/**]
     audit: true
     templates:
       taskPlanAppend: templates/task_plan.append.md
@@ -21,5 +21,5 @@ audit:
   evidenceFiles: [preset-audit.json]
 writeScopes:
   planningDocs:
-    path: docs/09-PLANNING/**
+    path: coding-agent-harness/planning/**
     access: write

package/presets/module/templates/execution_strategy.append.md

@@ -3,6 +3,6 @@
 | Field | Value |
 | --- | --- |
 | Module Key | {{moduleKey}} |
-| Module Plan | docs/09-PLANNING/MODULES/{{moduleKey}}/module_plan.md |
+| Module Plan | coding-agent-harness/planning/modules/{{moduleKey}}/module_plan.md |
 
 Keep shared module decisions in the module plan or module context files. Keep task-specific evidence in this task directory.

package/presets/module/templates/task_plan.append.md

@@ -12,6 +12,6 @@ Read these module-level entry points before changing shared module behavior. Con
 
 | Reference | Path | Why / When |
 | --- | --- | --- |
-| Module brief | docs/09-PLANNING/MODULES/{{moduleKey}}/brief.md | Start here for the module purpose and current scope. |
-| Module plan | docs/09-PLANNING/MODULES/{{moduleKey}}/module_plan.md | Use this for module steps, active task links, and handoff state. |
-| Module visual map | docs/09-PLANNING/MODULES/{{moduleKey}}/visual_map.md | Inspect when the change affects module sequencing or dependencies. |
+| Module brief | coding-agent-harness/planning/modules/{{moduleKey}}/brief.md | Start here for the module purpose and current scope. |
+| Module plan | coding-agent-harness/planning/modules/{{moduleKey}}/module_plan.md | Use this for module steps, active task links, and handoff state. |
+| Module visual map | coding-agent-harness/planning/modules/{{moduleKey}}/visual_map.md | Inspect when the change affects module sequencing or dependencies. |