coding-agent-harness 1.0.7 → 1.1.0

package/docs-release/architecture/system-explainer/en-US/06-preset-and-migration.md

@@ -221,7 +221,7 @@ must be satisfied to pass.
 flowchart TD
   Core["core\n(required, foundation for all other capabilities)"]
 
-  Core --> ModParallel["module-parallel\nModule registry + parallel work"]
+  Core --> ModParallel["module-parallel\nYAML module registry + parallel work"]
   Core --> AdvReview["adversarial-review\nAdversarial review reports\n(alias: review-contract)"]
   Core --> LongRunning["long-running-task\nLong-running task contracts"]
   Core --> Dashboard["dashboard\nLocal HTML Dashboard"]
@@ -233,7 +233,7 @@ flowchart TD
 | Capability | When to enable |
 | --- | --- |
 | `core` | Always — this is the required foundation |
-| `module-parallel` | When the project has 2+ independent modules needing parallel ownership |
+| `module-parallel` | When the project has 2+ independent modules and needs `harness.yaml modules.items` to maintain owner, scope, dependencies, and sync rules |
 | `subagent-worker` | When code-change subagents need to work in isolated worktrees and commit handoffs |
 | `adversarial-review` | When release, architecture, security, data, or policy risks require independent review artifacts |
 | `long-running-task` | When Agents may run across multiple loops without per-step user confirmation |

package/docs-release/architecture/system-explainer/en-US/README.md

@@ -19,7 +19,7 @@ For example:
 - Why is state stored in Markdown files instead of a database?
 - Why are there three check profiles instead of one?
 - What's the difference between `governance-sync` and `governance rebuild`, and why are they separate?
-- Why must `review-confirm` be a manual operation — why can't it be automated?
+- Why must human confirmation go through the local Workbench instead of a regular CLI command?
 
 The answers to these questions are scattered across design decisions, historical evolution,
 and operating standards. These docs bring them together so you can understand the system's

package/docs-release/guides/agent-installation.en-US.md

@@ -8,7 +8,7 @@ This guide is written for coding agents that install or upgrade Harness inside a
 
 The main operator for this CLI is usually an agent inside the target project, not the end user. The agent should not ask the user to study command flags, template folders, or capability choices. Those decisions must happen during Diagnose / Decide and be explained in the delivery summary.
 
-Commands in this guide are written with an installed `harness` command. The 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. Run that global install 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 the same command with `node dist/harness.mjs`.
+Commands in this guide are written with an installed `harness` command. The 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. Run that global install 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 the same command with `node dist/harness.mjs` after `npm install` or `npm run build:runtime` has generated `dist/`.
 
 `harness init` does not add this npm package to the target project's dependencies. It only writes Harness docs, templates, and the registry. Delivery summaries must not imply that the target project now has an npm dependency installed. The first `npx` run downloads the package into npm cache; it is not a project dependency or a global command install. When CLI access is needed, keep using `npx --yes coding-agent-harness ...`, a user-approved global `harness`, or `node dist/harness.mjs` from the source checkout.
 
@@ -205,10 +205,8 @@ harness task-log <task-id-from-new-task-output> \
   --evidence "command:TARGET:npm-test:passed" \
   /path/to/project
 
-harness review-confirm <task-id-from-new-task-output> \
-  --reviewer "Human Reviewer" \
-  --confirm <task-id-from-new-task-output> \
-  /path/to/project
+# Human confirmation is only available from the local Dashboard workbench:
+harness dev /path/to/project
 
 harness task-complete <task-id-from-new-task-output> \
   --message "Verification loop completed" \
@@ -225,7 +223,7 @@ Rules:
 - Existing task directories are not overwritten. Renaming or continuing old tasks is a coordinator decision.
 - `task-start`, `task-block`, and `task-complete` only update lifecycle status and logs in `progress.md`.
 - `task-log` only appends execution records. Evidence uses `type:PATH:summary`, for example `command:TARGET:npm-test:passed`.
-- `review-confirm` writes human review confirmation audit fields to the task `INDEX.md` through gated commits. It must reject open P0/P1/P2 findings marked `Open: yes` or `Blocks Release: yes`.
+- Dashboard workbench writes human review confirmation audit fields to the task `INDEX.md` through gated commits. It must reject open P0/P1/P2 findings marked `Open: yes` or `Blocks Release: yes`. The regular CLI does not expose a human confirmation command.
 - CLI-owned lifecycle and lesson commands auto-commit allowlisted writes in a clean Git root. Dirty state appears in `status` / dashboard warnings and blocks those mechanical commits. Agent-owned manual edits still need proactive commits; deferred commits must record the no-commit reason, owner, and next step.
 - `status --json` keeps old `task.state` for compatibility and adds `lifecycleState`, `reviewStatus`, `closeoutStatus`, and `stateConflicts`. `done` means implementation finished; it does not mean `closed`.
 - For human operation, start the local HTML workbench with `harness dev /path/to/project`. It binds to `127.0.0.1`, chooses a port automatically, opens the browser, and refreshes when docs change. In headless or CI contexts, use `harness dev --no-open /path/to/project`.

package/docs-release/guides/agent-installation.md

@@ -15,7 +15,8 @@ English mirror: `docs-release/guides/agent-installation.en-US.md`
 如果目标环境没有 `harness` 命令，不得静默全局安装；先询问用户是否允许运行
 `npm install -g coding-agent-harness`。只有用户明确同意后才能修改全局 npm 环境。
 用户不同意或未回复时，用 `npx --yes coding-agent-harness <command>` 运行同一条 CLI。
-维护者在本源码仓调试时，可以把同一命令替换为 `node dist/harness.mjs`。
+维护者在本源码仓调试时，可以在 `npm install` 或 `npm run build:runtime`
+生成 `dist/` 后，把同一命令替换为 `node dist/harness.mjs`。
 
 `harness init` 不会把 npm 包写进目标项目依赖；它只写 Harness 文档、模板和 registry。
 因此 agent 交付时不能暗示目标项目已经安装了 npm dependency。`npx` 第一次运行会把包
@@ -91,7 +92,7 @@ Capability 要保守选择：
 | `dashboard` | 否 | 用户或 agent 需要本地状态页、静态证据快照，或本机动态 workbench。 |
 | `adversarial-review` | 否 | 发布、架构、安全、数据或策略风险需要独立 review artifact。 |
 | `long-running-task` | 否 | Agent 需要连续多轮执行，不能每步都询问用户。 |
-| `module-parallel` | 否 | 两个以上独立模块需要 owner、registry 和同步规则。 |
+| `module-parallel` | 否 | 两个以上独立模块需要 YAML 注册、owner、scope、依赖和同步规则。 |
 | `subagent-worker` | 否 | 会改代码的 subagent 需要独立 worktree 和 commit-backed handoff；依赖 `module-parallel`。 |
 
 `init` 的 JSON 输出会包含 `report`。交付 summary 必须包含：
@@ -195,7 +196,7 @@ harness new-task \
 - 已有项目事实只能 merge、append 或记录 residual；不能用泛化模板替换。
 - 历史合同缺口在普通模式下进入 `adoption-needed` warning。
 - `--strict` 必须仍然能因为旧 checker 失败或历史合同缺口而失败。
-- 旧全局表和模块索引先归档，再用 `harness governance rebuild --archive --apply` 重新生成；这些表是 Agent 索引，人看状态优先用 Dashboard。
+- 旧全局表和模块索引先归档，再用 `harness governance rebuild --archive --apply` 重新生成；这些表是 Agent 索引，人看状态优先用 Dashboard。模块注册表以根 `harness.yaml` 的 `modules.items` 为准，`Module-Registry.md` 是生成视图。
 - `migrate-verify` 必须通过，才能报告迁移输出可用；dashboard 路径必须是 HTML。
 - 必须基于验证通过的 `session.json` 创建 `legacy-migration` preset 任务。它记录 migration session、证据包、preset audit 和后续 work queue；不会自动重写历史任务正文。
 - 详细迁移策略见 `docs-release/guides/migration-playbook.md` 或英文镜像
@@ -224,10 +225,8 @@ harness task-log <new-task 输出的 task-id> \
   --evidence "command:TARGET:npm-test:passed" \
   /path/to/project
 
-harness review-confirm <new-task 输出的 task-id> \
-  --reviewer "Human Reviewer" \
-  --confirm <new-task 输出的 task-id> \
-  /path/to/project
+# 人工确认只能在本地 Dashboard workbench 中点击完成：
+harness dev /path/to/project
 
 harness task-complete <new-task 输出的 task-id> \
   --message "验证闭环完成" \
@@ -246,11 +245,15 @@ harness task-complete <new-task 输出的 task-id> \
   `execution_strategy.md`、`findings.md`、`lesson_candidates.md` 和 `review.md`。
 - `new-task --budget complex` 创建 standard 文件，并额外创建
   `references/INDEX.md` 和 `artifacts/INDEX.md`。
+- `module register` 只创建模块根 `brief.md`、`module_plan.md`，并把模块登记到
+  `harness.yaml modules.items`；`module scaffold` 只修复这两个模块根文档。
+- `new-task --module <key>` 在 `planning/modules/<key>/tasks/<task-id>/` 下创建任务，
+  任务目录内才包含 `execution_strategy.md`、`visual_map.md` 等执行合同。
 - 已存在的任务目录不会被覆盖；需要改名或继续旧任务时，由 coordinator 决定。
 - `task-start`、`task-block`、`task-complete` 只更新 `progress.md` 的生命周期状态和日志。
 - `task-log` 只追加执行记录；证据使用 `type:PATH:summary`，例如
   `command:TARGET:npm-test:passed`。
-- `review-confirm` 会通过受控提交把人工确认审计字段写入任务 `INDEX.md`；如果存在 `Open: yes` 或 `Blocks Release: yes` 的开放 P0/P1/P2 finding，必须拒绝确认。
+- Dashboard workbench 会通过受控提交把人工确认审计字段写入任务 `INDEX.md`；如果存在 `Open: yes` 或 `Blocks Release: yes` 的开放 P0/P1/P2 finding，必须拒绝确认。普通 CLI 不暴露人工确认命令。
 - CLI-owned lifecycle 和 lesson 命令会在干净 Git root 中自动提交 allowlisted 写入；dirty 状态会出现在 `status` / dashboard 的警告里，并阻塞这些机械化提交。Agent 手工改动仍要主动提交，不能提交时记录 no-commit reason、owner 和下一步。
 - `status --json` 保留旧 `task.state` 用于兼容，并新增 `lifecycleState`、`reviewStatus`、`closeoutStatus` 和 `stateConflicts`。`done` 只表示实现完成，不等于 `closed`。
 - 人工操作入口使用本地 HTML workbench：`harness dev /path/to/project`。它会启动只绑定 `127.0.0.1` 的动态页面、自动选择端口、打开浏览器并随 docs 变更刷新。无 GUI 或 CI 场景使用 `harness dev --no-open /path/to/project`。

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 沉淀