coding-agent-harness 1.0.8 → 1.1.0

package/docs-release/guides/contributing.md

@@ -24,6 +24,10 @@ Use Node.js 24 or newer. CI should run on the minimum supported LTS line.
 npm install
 ```
 
+The source repository ignores `dist/`. `npm install`, Git/source `prepare`,
+`prepack`, and the root npm scripts regenerate it when needed. The npm package
+still publishes `dist/` and excludes `scripts/` and `tests/`.
+
 If your change touches the GUI submodule:
 
 ```bash
@@ -39,8 +43,8 @@ the full root suite.
 | Change type | Minimum local checks |
 | --- | --- |
 | Docs only | `git diff --check` |
-| CLI/runtime | `npm test`, `npm run check`, `git diff --check` |
-| Templates or examples | `npm test`, `node dist/harness.mjs check --profile target-project examples/minimal-project`, `git diff --check` |
+| CLI/runtime | `npm run typecheck`, `npm run typecheck:guards`, `npm test`, `npm run check`, `git diff --check` |
+| Templates or examples | `npm test`, `npm run build:runtime`, `node dist/harness.mjs check --profile target-project examples/minimal-project`, `git diff --check` |
 | Dashboard | `npm test`, `npm run smoke:dashboard`, `git diff --check` |
 | Package surface | `npm test`, `npm run pack:dry-run`, `git diff --check` |
 | GUI submodule | `cd harness-gui && npm ci && npm run typecheck && npm test && npm run build` |
@@ -48,6 +52,9 @@ the full root suite.
 Full root suite:
 
 ```bash
+npm run build:runtime
+npm run typecheck
+npm run typecheck:guards
 npm test
 npm run smoke:dashboard
 npm run check
@@ -97,4 +104,4 @@ GitHub Actions runs the same broad gates contributors should run locally:
 - npm package dry run
 - GUI submodule typecheck, tests, and build
 
-Repository owners manage branch protection and required checks in GitHub. Contributors only need to keep their PRs focused, documented, and verified.
+Repository owners manage branch protection and required checks in GitHub. The root CI includes the enforced TypeScript integrity gate: `npm run typecheck` plus `npm run typecheck:guards`, including the no-`@ts-nocheck` regression check. Contributors only need to keep their PRs focused, documented, and verified.

package/docs-release/guides/contributing.zh-CN.md

@@ -24,6 +24,10 @@ PR 尽量聚焦在一类改动上。文档、CLI 行为、目标项目模板、p
 npm install
 ```
 
+源码仓忽略 `dist/`。`npm install`、Git/source `prepare`、`prepack` 和根仓
+npm scripts 会按需重新生成它。npm 包仍然发布 `dist/`，并排除 `scripts/` 和
+`tests/`。
+
 如果改动涉及 GUI 子模块：
 
 ```bash
@@ -38,8 +42,8 @@ npm ci
 | 改动类型 | 最小本地检查 |
 | --- | --- |
 | 仅文档 | `git diff --check` |
-| CLI / runtime | `npm test`, `npm run check`, `git diff --check` |
-| 模板或示例 | `npm test`, `node dist/harness.mjs check --profile target-project examples/minimal-project`, `git diff --check` |
+| CLI / runtime | `npm run typecheck`, `npm run typecheck:guards`, `npm test`, `npm run check`, `git diff --check` |
+| 模板或示例 | `npm test`, `npm run build:runtime`, `node dist/harness.mjs check --profile target-project examples/minimal-project`, `git diff --check` |
 | Dashboard | `npm test`, `npm run smoke:dashboard`, `git diff --check` |
 | Package surface | `npm test`, `npm run pack:dry-run`, `git diff --check` |
 | GUI 子模块 | `cd harness-gui && npm ci && npm run typecheck && npm test && npm run build` |
@@ -47,6 +51,9 @@ npm ci
 完整根仓检查：
 
 ```bash
+npm run build:runtime
+npm run typecheck
+npm run typecheck:guards
 npm test
 npm run smoke:dashboard
 npm run check
@@ -96,4 +103,4 @@ GitHub Actions 会运行贡献者本地也应覆盖的主要 gate：
 - npm package dry run
 - GUI 子模块 typecheck、测试和 build
 
-GitHub branch protection 和 required checks 由仓库 owner 在 GitHub 上管理。贡献者只需要让 PR 聚焦、说明清楚并附上验证证据。
+GitHub branch protection 和 required checks 由仓库 owner 在 GitHub 上管理。根仓 CI 已包含 enforced TypeScript integrity gate：`npm run typecheck` 和 `npm run typecheck:guards`，其中包括 no-`@ts-nocheck` 防回归检查。贡献者只需要让 PR 聚焦、说明清楚并附上验证证据。

package/docs-release/guides/legacy-migration-agent-prompt.md

@@ -83,7 +83,7 @@ If the user provides external source material, first use `docs/11-REFERENCE/exte
 
 ## Step 1: Baseline
 
-First check whether the target environment has the `harness` command. If it does not, do not silently install globally. Ask the user whether `npm install -g coding-agent-harness` is allowed. Run that global install only after explicit approval. If the user does not approve or does not respond, use `npx --yes coding-agent-harness <command>` for Harness CLI calls. If you are debugging from the source checkout, replace `harness` with `node dist/harness.mjs`.
+First check whether the target environment has the `harness` command. If it does not, do not silently install globally. Ask the user whether `npm install -g coding-agent-harness` is allowed. Run that global install only after explicit approval. If the user does not approve or does not respond, use `npx --yes coding-agent-harness <command>` for Harness CLI calls. If you are debugging from the source checkout, run `npm install` or `npm run build:runtime` first, then replace `harness` with `node dist/harness.mjs`.
 
 After user confirmation, run or reuse:
 

package/docs-release/guides/legacy-migration-agent-prompt.zh-CN.md

@@ -83,7 +83,7 @@ Agent 应推荐下面三种模式之一，而不是让用户自己先懂这些
 
 ## Step 1: Baseline
 
-先检查目标环境是否有 `harness` 命令。如果没有，不要静默全局安装。先询问用户是否允许运行 `npm install -g coding-agent-harness`。只有用户明确同意后才执行全局安装。用户不同意或未回复时，Harness CLI 都用 `npx --yes coding-agent-harness <command>` 临时执行。如果你在源码仓调试，把 `harness` 替换为 `node dist/harness.mjs`。
+先检查目标环境是否有 `harness` 命令。如果没有，不要静默全局安装。先询问用户是否允许运行 `npm install -g coding-agent-harness`。只有用户明确同意后才执行全局安装。用户不同意或未回复时，Harness CLI 都用 `npx --yes coding-agent-harness <command>` 临时执行。如果你在源码仓调试，先运行 `npm install` 或 `npm run build:runtime` 生成 `dist/`，再把 `harness` 替换为 `node dist/harness.mjs`。
 
 用户确认迁移模式后再运行或复用：
 

package/docs-release/guides/migration-playbook.en-US.md

@@ -11,7 +11,7 @@ If another agent will execute the migration, first give it:
 - `docs-release/guides/full-legacy-migration-subagent-strategy.md`
 - `docs-release/guides/full-legacy-migration-subagent-strategy.zh-CN.md`
 
-This guide assumes the installed `harness` command. The executing agent must first check `command -v harness`. If the target environment does not have `harness`, do not silently install globally. Ask the user whether `npm install -g coding-agent-harness` is allowed. Install globally only after explicit approval. If the user does not approve or does not respond, run the same CLI with `npx --yes coding-agent-harness <command>`. Maintainers debugging from the source checkout can replace it with `node dist/harness.mjs`.
+This guide assumes the installed `harness` command. The executing agent must first check `command -v harness`. If the target environment does not have `harness`, do not silently install globally. Ask the user whether `npm install -g coding-agent-harness` is allowed. Install globally only after explicit approval. If the user does not approve or does not respond, run the same CLI with `npx --yes coding-agent-harness <command>`. Maintainers debugging from the source checkout can replace it with `node dist/harness.mjs` after `npm install` or `npm run build:runtime` has generated `dist/`.
 
 ## Target Path And v2 Structure
 
@@ -105,7 +105,9 @@ migration destination is `coding-agent-harness/`, and the old `docs/` root is
 archived under `coding-agent-harness/governance/archive/legacy-docs/`. Legacy
 `planning/**/_task-template` and `planning/**/_module-template` directories are
 generated copies of npm-package templates, so migration removes them from the
-target project when present:
+target project when present. New module templates live in bundled
+`templates/modules/**`; target projects keep only real module documents and YAML
+registration data:
 
 ```bash
 harness migrate-structure --plan --json /path/to/project
@@ -222,7 +224,7 @@ In baseline mode, only `current-active` tasks or tasks still referenced by SSoT
 
 In status-aware rewrite mode, an existing `brief.md`, `execution_strategy.md`, or `visual_map.md` is not automatically preserved. If evidence shows it is an old template, parser residue, wrong language, or too weak for a human to judge current state, rewrite it. Historical tasks may become readable index cards or residuals, but that decision must be evidence-backed.
 
-Global table and module index migration is not manual refilling. Current Harness versions generate task lifecycle summaries into `Harness-Ledger.md` only; legacy `Feature-SSoT.md` and `Private-Feature-SSoT.md` files are archived during cutover and are not regenerated. Module `module_plan.md` Steps tables and module `visual_map.md` topology tables are still generated from module task files. Humans should inspect current state through the Dashboard; agents can use `task-list` / `task-index` queries for fast lookup. Before cutting over an older project, archive the legacy lifecycle tables and rebuild current indexes from task files:
+Global table and module index migration is not manual refilling. Current Harness versions generate task lifecycle summaries into `Harness-Ledger.md` only; legacy `Feature-SSoT.md` and `Private-Feature-SSoT.md` files are archived during cutover and are not regenerated. Module registration data lives in root `harness.yaml` `modules.items`; `Module-Registry.md` is a generated view. Module roots own only `brief.md` and `module_plan.md` by default; `execution_strategy.md`, `visual_map.md`, `review.md`, and `walkthrough.md` belong under concrete task directories. Humans should inspect current state through the Dashboard; agents can use `task-list` / `task-index` queries for fast lookup. Before cutting over an older project, archive the legacy lifecycle tables and rebuild current indexes from task files:
 
 ```bash
 harness governance rebuild --dry-run --archive /path/to/project
@@ -251,7 +253,8 @@ Do not turn many historical tasks into modules automatically. Adopt `module-para
 - the project has two or more independently evolving product or engineering domains;
 - every module has an owner, write scope, dependency model, and integration rule;
 - shared files are owned by the coordinator and worker changes flow through handoff;
-- `Module-Registry.md` and each `module_plan.md` can be maintained after migration.
+- root `harness.yaml` `modules.items` can remain the maintained registry, with `Module-Registry.md` only as its generated reading view;
+- each module root needs only real `brief.md` and `module_plan.md`; do not batch-create module-level task contract files just to enable modules.
 
 If the project merely has many historical tasks without stable module boundaries, keep `safe-adoption`, use `migrate-plan` as the action list, and add module capability later.
 
@@ -372,11 +375,11 @@ Treat any FAIL as valid until disproven with evidence. After fixing, regenerate
 
 Module classification has three levels and must not skip levels:
 
-1. `explicit module`: tasks already live under `docs/09-PLANNING/MODULES/<module>/`, or a maintained `Module-Registry.md` exists.
+1. `explicit module`: tasks already live under v2 `planning/modules/<module>/tasks/`, or root `harness.yaml` `modules.items` registers the module.
 2. `inferred module`: dashboard temporary grouping from task path/title/ID keywords, for browsing and triage only. It does not mean the project adopted `module-parallel`.
 3. `legacy-unclassified`: historical tasks that cannot be classified reliably. Preserve history and do not batch-rewrite them.
 
-Before creating `Module-Registry.md`, produce a classification summary:
+Before registering modules, produce a classification summary:
 
 - candidate module name;
 - why this is a product/engineering domain rather than a folder or date range;

package/docs-release/guides/migration-playbook.md

@@ -15,7 +15,8 @@ English mirror: `docs-release/guides/migration-playbook.en-US.md`
 如果目标环境没有 `harness`，不得静默全局安装；先询问用户是否允许运行
 `npm install -g coding-agent-harness`。用户明确同意后才能安装。用户不同意或未回复时，
 用 `npx --yes coding-agent-harness <command>` 运行同一条 CLI。维护者在本源码仓调试时，
-可以把同一命令替换为 `node dist/harness.mjs`。
+可以在 `npm install` 或 `npm run build:runtime` 生成 `dist/` 后，把同一命令替换为
+`node dist/harness.mjs`。
 
 ## 目标路径和 v2 结构
 
@@ -105,7 +106,8 @@ Agent 必须记录具体判断证据，例如 `AGENTS.md`、`CLAUDE.md`、`READM
 `--apply`。默认迁移目标是 `coding-agent-harness/`，并会把旧 `docs/` 归档到
 `coding-agent-harness/governance/archive/legacy-docs/`。旧版本遗留的
 `planning/**/_task-template` 和 `planning/**/_module-template` 是 npm 包内模板的生成副本，
-迁移时会从目标项目中移除：
+迁移时会从目标项目中移除。新模块模板来自 npm 包内的 `templates/modules/**`；
+目标项目只保留真实模块文档和 YAML 注册数据：
 
 ```bash
 harness migrate-structure --plan --json /path/to/project
@@ -222,7 +224,7 @@ Baseline 模式下，只有 `current-active` 或 “仍被 SSoT 引用为当前
 
 Status-aware rewrite 模式下，已有 `brief.md`、`execution_strategy.md`、`visual_map.md` 不是自动保留；如果证据显示它们只是旧模板、解析残留、语言错误或不能让人判断当前状态，就重写。历史任务可以只写可读索引卡或 residual，但这个判断必须有证据。
 
-全局表和模块索引迁移不是人工重填。新版本只把任务生命周期汇总生成到 `Harness-Ledger.md`；旧的 `Feature-SSoT.md` 和 `Private-Feature-SSoT.md` 是 legacy 生命周期投影，切换时应先归档，不再重建。模块 `module_plan.md` 的 Steps 表和模块 `visual_map.md` 的拓扑表仍由模块任务文件生成。人看当前状态应优先看 Dashboard，Agent 需要快速定位时用 `task-list` / `task-index` 查询。旧项目切换前，先把旧生命周期表归档，再用生成器从任务文件重建当前索引：
+全局表和模块索引迁移不是人工重填。新版本只把任务生命周期汇总生成到 `Harness-Ledger.md`；旧的 `Feature-SSoT.md` 和 `Private-Feature-SSoT.md` 是 legacy 生命周期投影，切换时应先归档，不再重建。模块注册数据写在根 `harness.yaml` 的 `modules.items`，`Module-Registry.md` 是生成视图。模块根目录默认只维护 `brief.md` 和 `module_plan.md`；`execution_strategy.md`、`visual_map.md`、`review.md`、`walkthrough.md` 属于具体任务目录。人看当前状态应优先看 Dashboard，Agent 需要快速定位时用 `task-list` / `task-index` 查询。旧项目切换前，先把旧生命周期表归档，再用生成器从任务文件重建当前索引：
 
 ```bash
 harness governance rebuild --dry-run --archive /path/to/project
@@ -251,7 +253,8 @@ Full semantic rewrite 模式下，所有任务都需要 standalone `brief.md`，
 - 项目存在两个以上可独立演进的产品或工程域。
 - 每个模块有 owner、write scope、依赖关系和集成规则。
 - 共享文件由 coordinator 维护，worker 通过 handoff 请求更新。
-- `Module-Registry.md` 和每个 `module_plan.md` 能被持续维护。
+- 根 `harness.yaml` 的 `modules.items` 能作为注册表持续维护，生成的 `Module-Registry.md` 只作为视图阅读。
+- 每个模块根目录只需要真实的 `brief.md` 和 `module_plan.md`；不要为了启用模块而批量创建模块级任务合同文件。
 
 如果只是历史 task 很多，但没有稳定模块边界，先保持 `safe-adoption`，用 `migrate-plan` 输出 action list，等模块边界明确后再加 capability。
 
@@ -372,11 +375,11 @@ Capability registry 必须由一个 worker 顺序写，不能多个 worker 并
 
 模块分类有三个层级，不能跳级：
 
-1. `explicit module`：任务已经在 `docs/09-PLANNING/MODULES/<module>/` 下，或已有明确 `Module-Registry.md` 维护。
+1. `explicit module`：任务已经在 v2 `planning/modules/<module>/tasks/` 下，或根 `harness.yaml` 的 `modules.items` 已注册该模块。
 2. `inferred module`：dashboard 根据任务路径、标题、ID 关键字临时分组，仅用于浏览和分诊，不代表项目已经采用 `module-parallel`。
 3. `legacy-unclassified`：无法稳定归类的历史任务，保持历史状态，不要批量改写。
 
-创建 `Module-Registry.md` 前，必须先输出分类摘要：
+注册模块前，必须先输出分类摘要：
 
 - 候选模块名。
 - 为什么这是产品/工程域，而不是文件夹或时间段。

package/docs-release/guides/preset-development.md

@@ -27,6 +27,24 @@ and `harness install-user` seed them into the user preset root, while
 `harness init` seeds them into the project preset root. Re-run
 `harness preset seed` for the user root or `harness preset seed --project <target>`
 for the project root when a preset root is missing or incomplete.
+Use `harness preset audit --json` or `harness preset audit --project --json <target>`
+to compare installed preset manifest hashes with bundled presets before deciding
+whether to re-seed with `--force`.
+
+## Task Provenance Drift
+
+Preset audit hashes on a task are creation-time provenance. After a task is
+created, the task directory is an independent document record, so later changes
+to the currently discovered preset do not invalidate historical tasks by
+default. Target checks report manifest, version, and resource drift as
+`preset-drift-warning` messages so maintainers can see that a task came from an
+older preset shape without treating that history as a release-blocking failure.
+
+Current preset execution remains stricter. `harness preset check`,
+`harness preset install`, `harness new-task --preset`, and
+`harness preset action` still validate the current preset package and require an
+explicit current-preset opt-in for sensitive reruns when a task's stored audit
+no longer matches the preset being executed.
 
 ## Dashboard Management
 
@@ -78,7 +96,7 @@ task:
 entrypoints:
   newTask:
     type: template
-    writes: [coding-agent-harness/planning/tasks/**]
+    writes: [{{paths.tasksRoot}}/**]
     audit: true
     templates:
       taskPlanAppend: templates/task_plan.append.md
@@ -106,10 +124,47 @@ audit:
   evidenceFiles: [preset-audit.json, preset-manifest.json, write-scope.json]
 writeScopes:
   taskDocs:
-    path: coding-agent-harness/planning/tasks/**
+    path: {{paths.tasksRoot}}/**
     access: write
 ```
 
+## Task Actions
+
+Use `actions` when a preset needs task-level commands after task creation, such
+as closing a workflow stage or generating a preset-owned artifact. Actions run
+through the namespaced CLI entrypoint:
+
+```bash
+harness preset action custom-review close-stage --task custom-review-task --stage PLAN /path/to/project
+```
+
+Action scripts are trusted local Node.js code, not a sandbox. Non-bundled
+script actions require explicit trust when installed:
+
+```bash
+harness preset install ./custom-review --project --allow-scripts /path/to/project
+```
+
+```yaml
+actions:
+  close-stage:
+    type: script
+    command: scripts/close-stage.mjs
+    taskRequired: true
+    inputs:
+      stage:
+        type: text
+        flag: --stage
+        required: true
+    reads: [{{task.paths.taskPlan}}, {{task.paths.artifacts}}/**]
+    writes: [{{task.paths.artifacts}}/stages/**, {{task.paths.progress}}]
+    audit: true
+```
+
+Action commands must be package-local `.mjs` files. Inputs are schema-only
+(`text`, `flag`, or `json-file`), and writes should use `{{task.paths.*}}`
+tokens so the action stays scoped to the current task.
+
 ## Reference Bundles
 
 Use `resources.references` when a family of tasks shares the same outside context, such as another microservice, API contract, migration packet, reviewer input, or local verification runbook. Harness copies or renders these files into each created task directory, appends `references/INDEX.md` rows, and can add a required-read section to `task_plan.md`.
@@ -160,6 +215,12 @@ resources:
 
 Templates use `{{valueName}}` placeholders from `templateValues`. `templateValues` and `metadata` support literal `value`, `default`, and dot-path `from` references such as `inputs.subject` or `task.title`; they do not evaluate arbitrary expressions.
 
+Runtime paths must use the structure-aware `{{paths.*}}` context instead of
+hard-coded `coding-agent-harness/...` strings. Supported path fields include
+`harnessRoot`, `planningRoot`, `tasksRoot`, `modulesRoot`, `externalRoot`,
+`governanceRoot`, `generatedRoot`, `regressionRoot`, `ledgerPath`, and
+`closeoutIndexPath`. Harness resolves them from the target `harness.yaml`.
+
 `metadata` entries render first-class task plan lines such as `Review Subject: API contracts`.
 
 ```md
@@ -212,6 +273,9 @@ harness preset install ./my-preset --project /path/to/project
 harness preset install legacy-migration --force
 harness preset seed
 harness preset seed --project /path/to/project
+harness preset audit --json
+harness templates audit --json /path/to/project
+harness templates refresh --apply --json /path/to/project
 harness preset list --json /path/to/project
 harness preset inspect custom-review --json /path/to/project
 harness new-task --title "Custom review task" --preset custom-review --subject "API contracts" /path/to/project
@@ -233,6 +297,8 @@ For every preset, prove both the manifest and downstream task behavior:
 
 - Presets cannot write outside declared `writeScopes`.
 - Presets do not run arbitrary JavaScript during `new-task`.
+- Preset actions may run trusted `.mjs` scripts, but only through
+  `harness preset action <preset> <action>` and task-local materialization.
 - Reference bundles are task-local snapshots. If the shared upstream context changes later, create a new preset version or a follow-up task rather than silently mutating historical tasks.
 - Script and check entrypoints may exist in bundled packages, but the task creation path is YAML + templates + built-in processors.
 - Use a new built-in processor only when multiple presets need the same capability and the behavior can be tested centrally.

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

@@ -28,12 +28,12 @@ stateDiagram-v2
   review_submitted --> missing_materials: returned for materials
   missing_materials --> in_progress: repair materials
   review_submitted --> blocked: blocking finding
-  review_submitted --> human_confirmed: review-confirm
+  review_submitted --> human_confirmed: Dashboard workbench confirmation
   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.
+`task-review` means the agent submitted a review packet. It does not mean human approval. Dashboard workbench human confirmation 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
 
@@ -43,12 +43,12 @@ stateDiagram-v2
 | --- | --- | --- | --- |
 | `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` |
+| `gate` | Agent review submission, human confirmation, lesson routing, walkthrough, and closeout. | no | `harness task-review`, Dashboard workbench human confirmation, 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.
+Agents may run `Exit Command` values with `Actor: agent`. `Actor: human` gates, especially Dashboard workbench human confirmation, require explicit human action.
 
 ## Derived State
 
@@ -91,7 +91,7 @@ flowchart TB
 
 | Condition | `lifecycleState` | Meaning |
 | --- | --- | --- |
-| Tombstone, superseded-by, archive, or abandoned marker exists | `soft-deleted-superseded` | Hidden by default, but preserved for audit and replacement tracing. |
+| Tombstone, superseded-by, or archive marker exists | `soft-deleted-superseded` | Hidden by default, but preserved for audit, reason, and replacement tracing; abandoned, duplicate, and requirement-change semantics live in `Reason`. |
 | 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. |
@@ -111,7 +111,7 @@ flowchart TB
 | `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`.
+Agent self-review, subagent review, and coordinator review can only move a task toward `submitted`. Only an explicit Dashboard Workbench human confirmation writes the confirmation audit fields in `INDEX.md`.
 
 ## Lifecycle Queues
 
@@ -143,7 +143,7 @@ flowchart TD
 | 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. |
+| Soft-deleted / Superseded | Task was soft-deleted, replaced, merged, or archived; abandoned / duplicate / requirement-change semantics are tombstone reasons. | 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.
 
@@ -195,7 +195,7 @@ sequenceDiagram
 
 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.
+CLI-owned mechanical writes, Workbench human confirmation, and agent-owned manual slices have different boundaries. `new-task`, `task-*`, `task-phase`, `module-step`, `lesson-sediment`, and `lesson-promote --apply` acquire a lock, restrict writes to an allowlist, and auto-commit in a clean Git root; human confirmation runs only through the local Workbench. 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
 

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

@@ -28,12 +28,12 @@ stateDiagram-v2
   review_submitted --> missing_materials: returned for materials
   missing_materials --> in_progress: repair materials
   review_submitted --> blocked: blocking finding
-  review_submitted --> human_confirmed: review-confirm
+  review_submitted --> human_confirmed: Dashboard workbench confirmation
   human_confirmed --> finalized: task-complete + closeout
   finalized --> [*]
 ```
 
-`task-review` 表示 Agent 提交审查材料包，不表示人工批准。`review-confirm` 才表示人工确认门禁，并把审计字段写入 `INDEX.md`。`task-complete` / closeout 也不是 review confirmation 的替代品。
+`task-review` 表示 Agent 提交审查材料包，不表示人工批准。Dashboard workbench 人工确认才表示人工确认门禁，并把审计字段写入 `INDEX.md`。`task-complete` / closeout 也不是 review confirmation 的替代品。
 
 ## 阶段类型地图
 
@@ -43,12 +43,12 @@ stateDiagram-v2
 | --- | --- | --- | --- |
 | `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` |
+| `gate` | Agent 提交审查、人工确认、lesson routing、walkthrough 和 closeout。 | 否 | `harness task-review`、Dashboard workbench 人工确认，或 `harness task-complete` |
 
 旧阶段表没有 `Kind` 也继续有效，默认按 `execution` 处理。
 Dashboard 实现完成度只计算非 skipped 的 `execution` 阶段。
 Gate 阶段用于解释下一步生命周期动作和责任人，不会让已完成的实现看起来未完成。
-Agent 只能执行 `Actor: agent` 的 `Exit Command`。`Actor: human` 的 gate，尤其是 `review-confirm`，必须由人工明确执行。
+Agent 只能执行 `Actor: agent` 的 `Exit Command`。`Actor: human` 的 gate，尤其是 Dashboard workbench 人工确认，必须由人工明确执行。
 
 ## 派生状态
 
@@ -91,7 +91,7 @@ flowchart TB
 
 | 条件 | `lifecycleState` | 含义 |
 | --- | --- | --- |
-| 有 tombstone、superseded-by、archive 或 abandoned 标记 | `soft-deleted-superseded` | 默认隐藏，但保留审计和替代链。 |
+| 有 tombstone、superseded-by 或 archive 标记 | `soft-deleted-superseded` | 默认隐藏，但保留审计、原因和替代链；废弃、重复、需求变更写入 `Reason`。 |
 | 有 open P0-P2 finding、非法状态转换、审计失败或人审门禁失败 | `blocked` | 不能进入人工确认，必须先修 blocker 或记录 waiver。 |
 | 标准/复杂任务缺必需文件、章节、证据、lesson decision 或 review submission | `missing-materials` | 需要 Agent 补材料，不属于人审队列。 |
 | 已执行 `task-review`，材料齐全，且 `INDEX.md` 尚未显示人工确认 | `review-submitted` | 真正等待人审。 |
@@ -111,7 +111,7 @@ flowchart TB
 | `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`。
+Agent 自查、subagent 审查和 coordinator 审查都只能让任务接近 `submitted`。只有 Workbench 的明确人工确认动作会把确认审计字段写入 `INDEX.md`。
 
 ## 生命周期队列
 
@@ -202,7 +202,7 @@ sequenceDiagram
 
 严格规则：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 混入任务提交。
+CLI-owned 机械写入、Workbench 人工确认和 agent-owned 手工切片是三条边界。`new-task`、`task-*`、`task-phase`、`module-step`、`lesson-sediment` 和 `lesson-promote --apply` 会在干净 Git root 中加锁、限制写入范围并自动提交；人工确认只通过本地 Workbench 执行。Agent 手工编辑代码、模板或任务文档时仍要在验证后主动提交；无法提交时必须记录 no-commit reason、owner 和下一步，不能把 unrelated dirty changes 混入任务提交。
 
 ## Lesson 沉淀
 

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

@@ -1,25 +1,26 @@
 # 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.
+TypeScript runtime migration. The package executes generated `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.
+- `scripts/**/*.mts` builds to generated `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.
+- `dist/**/*.mjs` is the package runtime surface for npm bin and installed
+  execution. Source checkout npm scripts refresh it before running.
 - `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.
+The source repository ignores `dist/`, but the npm package publishes generated
+`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
 
@@ -42,12 +43,15 @@ dashboard exceptions below.
 ## Runtime Contract
 
 The package is an ESM package and its current public runtime contract points at
-the committed dist build output:
+generated dist build output:
 
 - `package.json` maps the `harness` executable to `dist/harness.mjs`.
-- npm postinstall runs `dist/postinstall.mjs`.
+- npm postinstall runs the source-safe `postinstall.mjs` bootstrap, which
+  delegates to `dist/postinstall.mjs` after generating `dist/` in a source
+  checkout.
 - npm helper scripts such as `check`, `status`, and dashboard generation run
-  through `dist/harness.mjs`.
+  through `run-dist.mjs`, which refreshes `dist/` in a source checkout and then
+  runs the relevant dist entrypoint.
 - Runtime modules import sibling `.mjs` files inside `dist/`, so installed
   package execution does not depend on TypeScript loaders.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coding-agent-harness",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "description": "Document governance kernel for long-running coding agents.",
   "type": "module",
   "keywords": [
@@ -26,21 +26,23 @@
     "harness": "dist/harness.mjs"
   },
   "scripts": {
-    "check": "node dist/harness.mjs check --profile source-package .",
-    "check:private": "node dist/harness.mjs check --profile private-harness .harness-private",
+    "check": "node run-dist.mjs harness.mjs check --profile source-package .",
+    "check:private": "node run-dist.mjs harness.mjs check --profile private-harness .harness-private",
     "build:runtime": "node scripts/build-dist.mts",
     "prepack": "node scripts/build-dist.mts --quiet",
+    "prepublishOnly": "node run-dist.mjs check-dist-observation.mjs --skip-install-smoke",
+    "prepare": "node postinstall.mjs --build-only",
     "typecheck": "npm exec --yes --package typescript@5.9.3 -- tsc -p tsconfig.json",
-    "typecheck:guards": "node dist/check-type-boundaries.mjs && node dist/check-no-ts-nocheck.mjs",
-    "check:nocheck": "node dist/check-no-ts-nocheck.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",
+    "typecheck:guards": "node run-dist.mjs check-type-boundaries.mjs && node run-dist.mjs check-no-ts-nocheck.mjs",
+    "check:nocheck": "node run-dist.mjs check-no-ts-nocheck.mjs",
+    "status": "node run-dist.mjs harness.mjs status --json .",
+    "dashboard": "node run-dist.mjs harness.mjs dashboard --out tmp/harness-dashboard.html examples/minimal-project",
+    "dashboard:folder": "node run-dist.mjs harness.mjs dashboard --out-dir tmp/harness-dashboard examples/minimal-project",
     "pack:dry-run": "npm pack --dry-run --json",
-    "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"
+    "postinstall": "node postinstall.mjs",
+    "observe:dist": "node run-dist.mjs check-dist-observation.mjs --skip-pack --skip-install-smoke",
+    "smoke:dashboard": "node run-dist.mjs run-built-tests.mjs --test tests/smoke-dashboard.mjs",
+    "test": "node run-dist.mjs run-built-tests.mjs"
   },
   "files": [
     "README.md",
@@ -49,6 +51,8 @@
     "CONTRIBUTING.md",
     "CHANGELOG.md",
     "SKILL.md",
+    "postinstall.mjs",
+    "run-dist.mjs",
     "tsconfig.json",
     "tsconfig.dist.json",
     "tsconfig.runtime.json",

package/postinstall.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+const buildScript = path.join(root, "scripts/build-dist.mts");
+const distPostinstall = path.join(root, "dist/postinstall.mjs");
+const buildOnly = process.argv.includes("--build-only");
+const skipPostinstall = process.env.CODING_AGENT_HARNESS_SKIP_POSTINSTALL === "1";
+
+function runBuild() {
+  if (!fs.existsSync(buildScript)) return false;
+  const result = spawnSync(process.execPath, [buildScript, "--quiet"], {
+    cwd: root,
+    stdio: "inherit",
+  });
+  if (result.status !== 0) process.exit(result.status ?? 1);
+  return true;
+}
+
+if (!fs.existsSync(distPostinstall)) {
+  runBuild();
+}
+
+if (buildOnly || skipPostinstall) {
+  process.exit(0);
+}
+
+if (!fs.existsSync(distPostinstall)) {
+  console.error("coding-agent-harness postinstall failed: missing dist/postinstall.mjs");
+  console.error("Run npm run build:runtime from a source checkout, or reinstall a complete package.");
+  process.exit(1);
+}
+
+await import(pathToFileURL(distPostinstall).href);