coding-agent-harness 1.0.5 → 1.0.7

package/CONTRIBUTING.md

@@ -40,7 +40,7 @@ docs row. For larger PRs or when you are unsure, run the full root suite.
 | --- | --- |
 | Docs only | `git diff --check` |
 | CLI/runtime | `npm test`, `npm run check`, `git diff --check` |
-| Templates or examples | `npm test`, `node scripts/harness.mjs check --profile target-project examples/minimal-project`, `git diff --check` |
+| Templates or examples | `npm test`, `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` |
@@ -52,7 +52,7 @@ npm install
 npm test
 npm run smoke:dashboard
 npm run check
-node scripts/harness.mjs check --profile target-project examples/minimal-project
+node dist/harness.mjs check --profile target-project examples/minimal-project
 npm run pack:dry-run
 git diff --check
 ```

package/README.md

@@ -84,9 +84,18 @@ context in every prompt, put it in a preset and create each task with
 
 Harness ships bundled presets, `harness init` seeds them into the target project,
 and teams can add project-local presets under `.coding-agent-harness/presets/`.
+This dotdir is a preset overlay exception: operational task state lives under
+`coding-agent-harness/`, while preset packages keep their existing overlay root
+so user and project preset precedence remains stable across upgrades.
 The `preset-creator` Skill is for authoring these preset packages; the Harness
 CLI is what checks, installs, lists, and applies them.
 
+Default task and module templates come from the installed npm package at command
+runtime. Target projects should not treat `planning/**/_task-template` or
+`planning/**/_module-template` directories as active state; v2 structure
+migration removes those generated legacy template directories when it finds
+them.
+
 ### Safe Migration For Existing Projects
 
 Legacy project migration starts with a scan, a migration plan, a recommended migration mode, and user confirmation. Only then should the agent write files. Final status is proven with a dashboard and checks.
@@ -160,9 +169,47 @@ The npm install seeds bundled presets into `~/.coding-agent-harness/presets/`.
 `harness init` also seeds those presets into the target project at
 `.coding-agent-harness/presets/`, so agents can discover stable task methods
 with `harness preset list --json`.
+The `.coding-agent-harness/presets/` location is intentionally retained for
+preset overlays; it is not a legacy task-state directory.
 
 Agents must not silently run a global install. They may run `npm install -g coding-agent-harness` only after the user explicitly approves changing the global npm environment. Without that approval, keep using `npx --yes coding-agent-harness ...`.
 
+### Harness State Location
+
+By default, `harness init` and `harness migrate-structure --apply` write active
+Harness state under `coding-agent-harness/` in the target project:
+
+```text
+coding-agent-harness/harness.yaml
+coding-agent-harness/planning/tasks/
+coding-agent-harness/governance/
+```
+
+Checks and dashboards are not tied to that exact folder name. A project can keep
+Harness state in a custom project-relative directory by placing `harness.yaml`
+there and declaring the same path in `structure.harnessRoot`. For example:
+
+```yaml
+version: 2
+locale: zh-CN
+capabilities:
+  - core
+  - dashboard
+structure:
+  harnessRoot: .project-control/harness-state
+  planningRoot: .project-control/harness-state/planning
+  tasksRoot: .project-control/harness-state/planning/tasks
+  governanceRoot: .project-control/harness-state/governance
+  generatedRoot: .project-control/harness-state/governance/generated
+```
+
+After that, these are equivalent when the manifest is unique under the project:
+
+```bash
+npx --yes coding-agent-harness status --json /path/to/project
+npx --yes coding-agent-harness status --json /path/to/project/.project-control/harness-state
+```
+
 ### Commands For Humans
 
 Initialize a Chinese Harness:
@@ -222,7 +269,7 @@ Use Chinese templates by default. If the project is clearly an English team or E
 
 First diagnose the project structure, then give me an initialization plan.
 If this is a microservice, multi-repo, split frontend/backend, or externally integrated project, proactively ask me whether I have external architecture docs, API docs, diagrams, meeting notes, links, source paths, or exported packets.
-If the external material is large, create an external-source-packs index and digests first, then project stable conclusions into 03-ARCHITECTURE / 04-DEVELOPMENT / 06-INTEGRATIONS.
+If the external material is large, create an external-source-packs index and digests first, then project stable conclusions into coding-agent-harness/context/{architecture,development,integrations}.
 After confirmation, execute Diagnose → Decide → Scaffold → Configure → Verify → Deliver.
 When initializing, run:
 npx --yes coding-agent-harness init --locale zh-CN --capabilities core,dashboard .
@@ -263,7 +310,7 @@ This project already has an older Harness. Do not edit files yet.
 
 First run a detailed scan and give me a migration plan:
 1. Check git status, Harness status, task count, brief coverage, visual_map coverage, warnings/actions/residuals, strict status, and dashboard usability.
-2. If this is a microservice, multi-repo, split frontend/backend, or externally integrated project, proactively ask me for external source material; when the material is large, create an external-source-packs index and digests before projecting facts into 03/04/06.
+2. If this is a microservice, multi-repo, split frontend/backend, or externally integrated project, proactively ask me for external source material; when the material is large, create an external-source-packs index and digests before projecting facts into context/{architecture,development,integrations}.
 3. Recommend the migration mode from project evidence:
    - baseline-preserve: safe adoption first; only add necessary structure and visibility.
    - status-aware-rewrite: rewrite current or reopened tasks from SSoT, Ledger, progress, review, and git evidence.
@@ -274,6 +321,19 @@ First run a detailed scan and give me a migration plan:
 During the scan phase, run at least:
 npx --yes coding-agent-harness status --json .
 npx --yes coding-agent-harness migrate-plan --json --limit 1000 .
+npx --yes coding-agent-harness migrate-structure --plan --json .
+
+After I confirm the migration mode, first migrate the directory structure to the
+v2 manifest layout, then run the migration rail and verify it:
+npx --yes coding-agent-harness migrate-structure --apply --json .
+npx --yes coding-agent-harness check --profile target-project .
+npx --yes coding-agent-harness migrate-run --locale zh-CN --session-dir /tmp/cah-migration-project --out-dir /tmp/cah-migration-project/dashboard .
+npx --yes coding-agent-harness migrate-verify /tmp/cah-migration-project/session.json
+
+Then create the controlled migration task with the bundled preset:
+npx --yes coding-agent-harness new-task --budget complex --preset legacy-migration --from-session /tmp/cah-migration-project/session.json .
+
+Do not skip the `legacy-migration` preset task. It records the migration session, evidence bundle, preset audit, and follow-up work queue in the project Harness. It does not automatically rewrite historical task bodies.
 
 When the migration is complete, report the dynamic workbench URL or static dashboard HTML, session.json, normal/strict checks, migrate-plan summary, and whether full-cutover verification passes. If human review confirmation is required, expose that action in the local web workbench; static dashboards are read-only evidence snapshots.
 ```
@@ -291,7 +351,7 @@ Start from the latest main branch and create a new feature branch. Read README.m
 
 Keep the change scoped. Use only public repository files and do not rely on maintainer-local state, hidden workflows, credentials, generated dashboards, temporary files, or ignored local-only files.
 
-Run the checks that match the change. For docs-only changes, run git diff --check. For root package changes, run npm install, npm test, npm run smoke:dashboard, npm run check, node scripts/harness.mjs check --profile target-project examples/minimal-project, npm run pack:dry-run, and git diff --check as relevant. If the change touches harness-gui, also run cd harness-gui && npm ci && npm run typecheck && npm test && npm run build.
+Run the checks that match the change. For docs-only changes, run git diff --check. For root package changes, run npm install, npm test, npm run smoke:dashboard, npm run check, node dist/harness.mjs check --profile target-project examples/minimal-project, npm run pack:dry-run, and git diff --check as relevant. If the change touches harness-gui, also run cd harness-gui && npm ci && npm run typecheck && npm test && npm run build.
 
 When done, summarize what changed, list verification results, call out any skipped checks with reasons, and prepare the PR using the repository template.
 ```

package/README.zh-CN.md

@@ -83,6 +83,9 @@ Harness 自带内置 Preset，`harness init` 会把它们 seed 到目标项目
 `.coding-agent-harness/presets/` 下维护项目级 Preset。`preset-creator` Skill 用来制作
 这些 Preset 包；真正检查、安装、列出和应用 Preset 的是 Harness CLI。
 
+默认任务模板和模块模板来自当前安装的 npm 包，在命令运行时读取。目标项目不应该把
+`planning/**/_task-template` 或 `planning/**/_module-template` 当作活跃状态；v2 结构迁移发现这些旧生成模板目录时会直接清理。
+
 ### 旧项目也能迁移
 
 旧项目迁移不是直接套模板。标准流程是：先扫描项目，生成迁移计划，推荐迁移模式，向用户提问确认，再执行迁移，最后用 Dashboard 和检查结果证明迁移状态。
@@ -158,6 +161,40 @@ npm 安装会把内置 Preset seed 到 `~/.coding-agent-harness/presets/`。
 
 Agent 不应静默执行全局安装。只有用户明确同意修改全局 npm 环境后，Agent 才能运行 `npm install -g coding-agent-harness`；否则继续使用 `npx --yes coding-agent-harness ...`。
 
+### Harness 状态目录
+
+默认情况下，`harness init` 和 `harness migrate-structure --apply` 会把活跃
+Harness 状态写到目标项目里的 `coding-agent-harness/`：
+
+```text
+coding-agent-harness/harness.yaml
+coding-agent-harness/planning/tasks/
+coding-agent-harness/governance/
+```
+
+检查和 Dashboard 不绑定这个固定目录名。项目可以把 Harness 状态放在自定义的项目相对目录里，只要在那个目录放 `harness.yaml`，并在 `structure.harnessRoot` 里声明同一个路径。例如：
+
+```yaml
+version: 2
+locale: zh-CN
+capabilities:
+  - core
+  - dashboard
+structure:
+  harnessRoot: .project-control/harness-state
+  planningRoot: .project-control/harness-state/planning
+  tasksRoot: .project-control/harness-state/planning/tasks
+  governanceRoot: .project-control/harness-state/governance
+  generatedRoot: .project-control/harness-state/governance/generated
+```
+
+只要项目里只有一个这样的 manifest，下面两种写法等价：
+
+```bash
+npx --yes coding-agent-harness status --json /path/to/project
+npx --yes coding-agent-harness status --json /path/to/project/.project-control/harness-state
+```
+
 ### 人看的常用命令
 
 初始化一个中文 Harness：
@@ -213,7 +250,7 @@ npx --yes coding-agent-harness <command>
 
 请先诊断项目结构，再给出初始化计划。
 如果项目是微服务、多仓、前后端分仓，或依赖外部系统，请主动询问我是否有外部架构文档、接口文档、流程图、会议纪要、链接或导出包。
-外部资料很多时，请先建立 external-source-packs 索引和摘要，再把稳定结论投影到 03-ARCHITECTURE / 04-DEVELOPMENT / 06-INTEGRATIONS。
+外部资料很多时，请先建立 external-source-packs 索引和摘要，再把稳定结论投影到 coding-agent-harness/context/{architecture,development,integrations}。
 确认后，按照 Diagnose → Decide → Scaffold → Configure → Verify → Deliver 六阶段执行。
 执行初始化时使用：
 npx --yes coding-agent-harness init --locale zh-CN --capabilities core,dashboard .
@@ -254,7 +291,7 @@ npx --yes coding-agent-harness <command>
 
 请先执行详尽扫描，并给我一个迁移计划：
 1. 检查当前 git 状态、Harness 状态、任务数量、brief 覆盖、visual_map 覆盖、warning/action/residual、strict 状态和 dashboard 可用性。
-2. 如果项目是微服务、多仓、前后端分仓，或依赖外部系统，主动询问我是否有外部资料；资料很多时先建立 external-source-packs 索引和摘要，再投影到 03/04/06。
+2. 如果项目是微服务、多仓、前后端分仓，或依赖外部系统，主动询问我是否有外部资料；资料很多时先建立 external-source-packs 索引和摘要，再投影到 context/{architecture,development,integrations}。
 3. 根据项目证据主动推荐迁移模式：
    - baseline-preserve：先安全接入，只补必要结构和可见性。
    - status-aware-rewrite：按 SSoT、Ledger、progress、review、git 证据重写当前或重新打开的任务。
@@ -265,6 +302,18 @@ npx --yes coding-agent-harness <command>
 扫描阶段至少运行：
 npx --yes coding-agent-harness status --json .
 npx --yes coding-agent-harness migrate-plan --json --limit 1000 .
+npx --yes coding-agent-harness migrate-structure --plan --json .
+
+等我确认迁移模式后，先把目录结构迁到 v2 manifest 布局，再执行迁移轨道并验证：
+npx --yes coding-agent-harness migrate-structure --apply --json .
+npx --yes coding-agent-harness check --profile target-project .
+npx --yes coding-agent-harness migrate-run --locale zh-CN --session-dir /tmp/cah-migration-project --out-dir /tmp/cah-migration-project/dashboard .
+npx --yes coding-agent-harness migrate-verify /tmp/cah-migration-project/session.json
+
+然后用内置 preset 创建受控迁移任务：
+npx --yes coding-agent-harness new-task --budget complex --preset legacy-migration --from-session /tmp/cah-migration-project/session.json .
+
+不要跳过 `legacy-migration` preset 任务。它会把 migration session、证据包、preset audit 和后续 work queue 记录进项目 Harness；它不会自动重写历史任务正文。
 
 最终迁移完成时，必须给出动态 workbench 入口或静态 dashboard HTML、session.json、normal/strict check、migrate-plan summary，以及 full-cutover 验证是否通过。需要人工确认审查时，必须通过本地网页 workbench 暴露确认操作；静态 dashboard 只作为只读证据快照。
 ```
@@ -282,7 +331,7 @@ npx --yes coding-agent-harness migrate-plan --json --limit 1000 .
 
 改动要保持聚焦。只使用公开仓库文件；不要依赖维护者本地状态、隐藏工作流、凭据、生成的 Dashboard、临时文件或被 ignore 的本地专用文件。
 
-根据改动范围运行检查。仅文档改动至少运行 git diff --check。根包相关改动按需运行 npm install、npm test、npm run smoke:dashboard、npm run check、node scripts/harness.mjs check --profile target-project examples/minimal-project、npm run pack:dry-run 和 git diff --check。如果改到 harness-gui，还要运行 cd harness-gui && npm ci && npm run typecheck && npm test && npm run build。
+根据改动范围运行检查。仅文档改动至少运行 git diff --check。根包相关改动按需运行 npm install、npm test、npm run smoke:dashboard、npm run check、node dist/harness.mjs check --profile target-project examples/minimal-project、npm run pack:dry-run 和 git diff --check。如果改到 harness-gui，还要运行 cd harness-gui && npm ci && npm run typecheck && npm test && npm run build。
 
 完成后，请总结改了什么，列出验证结果，说明任何未运行检查及原因，并按仓库 PR 模板准备 PR。
 ```

package/SKILL.md

@@ -3,9 +3,9 @@ name: coding-agent-harness
 description: >
   Coding Agent Harness 工程方法论。为使用 Coding Agent（Codex、Claude Code、Gemini CLI 等）
   做长程项目开发的团队，在用户的项目上构建一套完整的 harness 工程体系。
-  包括：项目诊断、AGENTS.md + CLAUDE.md 入口文件生成、docs/ 目录搭建、Planning Loop、SSoT 治理、
+  包括：项目诊断、AGENTS.md + CLAUDE.md 入口文件生成、coding-agent-harness/ 目录搭建、Planning Loop、SSoT 治理、
   Delivery Operating Model、Repository Governance、CI/CD、Long-Running Task Protocol、Adversarial Review Report、Review Routing、Worktree 并行开发、
-  Regression SSoT 与 Evidence Depth 分级回归、Walkthrough / Closeout SSoT 收口、Cadence Ledger、任务本地 lesson 候选与 promoted lesson 详情文档、
+  Regression SSoT 与 Evidence Depth 分级回归、Walkthrough / Closeout Index 收口、Cadence Ledger、任务本地 lesson 候选与 promoted lesson 详情文档、
   Harness Ledger 全局上下文回写总账。
   当用户要求设置 coding agent 的开发流程、建立回归测试体系、设计 AGENTS.md / CLAUDE.md、
   规划长程 agent 任务的执行框架、子代理审查循环、对抗性 review 报告、搭建 harness、或者提到 harness engineering 时，使用此技能。
@@ -24,7 +24,7 @@ description: >
 - **单元测试只是底线，不是保障。** 真正的保障需要多层证据（Evidence Depth）。
 - **先识别交付组织，再设计 harness。** 一人多 agent、多人团队、前后端分仓、program 多仓、敏捷/瀑布，对应的 SSoT 和冲突治理不同。
 - **Repo 护栏是地基。** CI/CD、PR policy、branch protection、required checks、worktree concurrency 必须项目级定制，不能停留在模板。
-- **外部资料先摄取，再投影。** 微服务或多仓项目的外部文档不能直接塞进执行文档；先建 source pack、digest、验证，再投影到 `03/04/06`。
+- **外部资料先摄取，再投影。** 微服务或多仓项目的外部文档不能直接塞进执行文档；先建 source pack、digest、验证，再投影到 `context/{architecture,development,integrations}`。
 - **长程任务先设计合同，再开放执行。** 连续跑数小时的前提是 Goal、Scope、Review Loop、Evidence、Stop Condition 都清楚。
 - **审查必须落盘。** 对抗性 review 是独立交付物，不应只留在对话、progress 或 walkthrough 里；reviewer 必须用 Confidence Challenge 反复挑战方案，直到没有 open material finding。
 - **Worker handoff 必须 commit-backed。** 可写 subagent 不是 reviewer；它必须在独立 worktree / branch 内实现、验证并提交，再由 coordinator 集成。
@@ -39,7 +39,7 @@ description: >
 coding-agent-harness"，不要重新 bootstrap 覆盖整个项目。先执行增量更新流程：
 
 1. 读取本 Skill 的最新版 `SKILL.md`、相关 `references/`、`templates/`。
-2. 扫描目标项目现有 `AGENTS.md`、`CLAUDE.md`、`docs/` 和 SSoT / Ledger 文件。
+2. 扫描目标项目现有 `AGENTS.md`、`CLAUDE.md`、`coding-agent-harness/` 和 SSoT / Ledger 文件。
 3. 输出 delta plan：哪些 harness 骨架、reference、template、SSoT、Ledger 项缺失或过期。
 4. 只补齐新增标准和缺失结构；不得用模板覆盖已有业务事实、历史 walkthrough、
    task progress、generated ledger、Regression SSoT 或 lesson detail docs。
@@ -48,8 +48,8 @@ coding-agent-harness"，不要重新 bootstrap 覆盖整个项目。先执行增
 7. 收口时写 walkthrough，必须包含 Lessons Reflection；新任务先写并审查
    `lesson_candidates.md`。如人工标记值得沉淀，默认先用 dry-run 或后续
    lesson sedimentation 任务完成分类、冲突检查和建议 diff；只有人工明确批准后，
-   维护命令才写 `docs/01-GOVERNANCE/lessons/` 详情文档；最后在
-   `docs/Harness-Ledger.md` 与 `docs/10-WALKTHROUGH/Closeout-SSoT.md` 记录本次 harness update 的 delta 和 Lessons Check。
+   维护命令才写 `coding-agent-harness/governance/lessons/` 详情文档；最后在
+   `coding-agent-harness/governance/generated/Harness-Ledger.md` 与 `coding-agent-harness/governance/generated/Closeout-Index.md` 记录本次 harness update 的 delta 和 Lessons Check。
 
 一句话：harness update 是 delta merge，不是重新搭一遍。
 
@@ -64,7 +64,7 @@ CLI 示例默认使用目标项目可调用的 `harness` 命令。执行前先
 `command -v harness`；如果没有，不要静默全局安装，按安装指南询问用户是否
 允许 `npm install -g coding-agent-harness`。未获明确同意时，用
 `npx --yes coding-agent-harness <command>` 执行同一条命令。只有维护本源码
-checkout 时，才把 `harness` 替换为 `node scripts/harness.mjs`。
+checkout 时，才把 `harness` 替换为 `node dist/harness.mjs`。
 
 ### Agent 安装合同
 
@@ -78,7 +78,7 @@ checkout 时，才把 `harness` 替换为 `node scripts/harness.mjs`。
   明确配置中推断 locale，并显式传 `--locale`。如果无法判断，先暂停询问。
 - 中文用户或中文项目默认选择 `zh-CN`；英文团队、英文代码库或用户明确要求英文时选择
   `en-US`。
-- scaffold 后必须检查 `.harness-capabilities.json` 的 `locale`，并确认 dashboard、
+- scaffold 后必须检查 `coding-agent-harness/harness.yaml` 的 `locale`，并确认 dashboard、
   task template、review template 来自同一套模板树。
 - `templates/` 和 `templates-zh-CN/` 是两套完整模板树。不要在目标项目里混拷两套模板；
   只允许保留 schema 字段、文件名、状态枚举、命令和跨工具协议 token 的英文。
@@ -105,9 +105,10 @@ SDK、API gateway、message queue、webhook、contract、schema、mock，必须
    split-repo-contract、program-multi-repo、waterfall-stage-gate 或
    kanban-continuous。
 3. Capability Packs：core 必装；按需选择 module-parallel、subagent-worker、
-   adversarial-review、long-running-task、dashboard、safe-adoption。
+   adversarial-review、long-running-task、dashboard。旧项目先用
+   `migrate-structure --plan/--apply` 迁到 v2，不再通过兼容 capability 长期运行。
 4. External Source Intake：如果外部资料超过 5 份、跨多个主题或会持续增长，
-   决定是否创建 `docs/04-DEVELOPMENT/external-source-packs/<source-key>/`。
+   决定是否创建 `coding-agent-harness/context/development/external-source-packs/<source-key>/`。
 
 Capability 选择规则必须按表执行，不得凭感觉多装：
 
@@ -115,7 +116,6 @@ Capability 选择规则必须按表执行，不得凭感觉多装：
 | --- | --- |
 | `core` | 永远安装。它是任务计划、回归、walkthrough、Lessons 和 Harness Ledger 的最小内核。 |
 | `dashboard` | 用户或 agent 需要本地只读状态页时安装。它不写目标项目文件。 |
-| `safe-adoption` | 只在已有旧 harness 项目接入 v1.0、且需要保留历史文档时安装。新项目默认不装。 |
 | `adversarial-review` | 发布、架构、安全、数据、策略风险需要独立 review artifact 时安装。 |
 | `long-running-task` | 用户允许 agent 多轮连续执行、不能每步都询问时安装。 |
 | `module-parallel` | 项目有 2 个以上可独立演进模块，且需要模块 owner / registry / 同步规则时安装。 |
@@ -127,7 +127,7 @@ Capability 选择规则必须按表执行，不得凭感觉多装：
 
 运行或模拟 `harness init --locale zh-CN|en-US --capabilities ...`。面向 agent 的安装
 必须显式传 `--locale`；只有人直接在终端运行且未传 `--locale` 时，CLI 才交互询问。CLI 只创建
-目录、模板、空表、索引和 `.harness-capabilities.json`，不得把项目级 reference
+目录、模板、空表、索引和 `coding-agent-harness/harness.yaml`，不得把项目级 reference
 伪装成已经定制完成的标准。
 
 CLI 会在 JSON 输出中返回 `report`。Agent 必须读取这份 report，并把其中的
@@ -144,8 +144,8 @@ worktree/subagent handoff 规则。已有项目事实只能 merge/append/residua
 如果用户提供了外部资料，Configure 阶段必须按
 `external-source-intake-standard.md` 执行：Inventory、Classify、Sanitize、Digest、
 Project、Verify、Residual。`external-source-packs/` 只保存资料索引、摘要和投影状态；
-稳定事实必须回写到 `03-ARCHITECTURE`、`04-DEVELOPMENT/external-context` 或
-`06-INTEGRATIONS`。
+稳定事实必须回写到 `coding-agent-harness/context/architecture`、`coding-agent-harness/context/development/external-context` 或
+`coding-agent-harness/context/integrations`。
 
 ### Phase 4b: Task Lifecycle / 任务生命周期
 
@@ -171,7 +171,7 @@ harness task-list --json /path/to/project
 - 状态推进只写 `progress.md`，不得重写历史 `task_plan.md`。
 - `simple` 任务可以直接 `in_progress -> done`；`standard` / `complex` 必须 `in_progress -> review -> done`，不能跳过 `task-review`。
 - `task-review` 只表示 Agent Review Submission：agent/coordinator 认为材料包已准备好并提交待审。它不是人工确认。
-- `review-confirm` 是唯一的 Human Review Confirmation 门禁。它只确认人工 review evidence / findings，不代表 closeout；closeout 仍走 walkthrough / Closeout SSoT。
+- `review-confirm` 是唯一的 Human Review Confirmation 门禁。它只确认人工 review evidence / findings，不代表 closeout；closeout 仍走 walkthrough / Closeout Index。
 - Review queue 只收录已提交 review packet、材料齐全、无 blocker、等待人工确认的任务。
 - 缺文件、缺章节、缺证据、缺 lesson decision 或未执行 `task-review` 的任务进入 Missing Materials 队列，不进入 Review queue。
 - open blocking finding、状态矛盾、审计失败或需要 human waiver 的任务进入 Blocked 队列，不进入 Review queue。
@@ -193,8 +193,8 @@ harness status --json /path/to/project
 
 | 回归路径 | 必须证明 |
 | --- | --- |
-| 新项目初始化 | 空项目 `init --locale zh-CN|en-US --capabilities core,...` 后，模板语言一致、registry 正确、`status --json` 不误报 `safe-adoption`。 |
-| 老项目迁移 | 已有旧 harness 文档的项目 `add-capability safe-adoption --locale ...` 后，旧 `AGENTS.md`、`CLAUDE.md`、`Harness-Ledger` 和历史 task 不被覆盖；缺失 v1.0 模板被补齐；普通检查只给 `adoption-needed` warning；`--strict` 仍可阻塞历史合同缺口。 |
+| 新项目初始化 | 空项目 `init --locale zh-CN|en-US --capabilities core,...` 后，模板语言一致、v2 manifest 正确、`status --json` 通过。 |
+| 老项目迁移 | 已有旧 harness 文档的项目先 `migrate-structure --plan`，再 `migrate-structure --apply`；旧 `coding-agent-harness/` 和 legacy registry 从 active root 移走或归档；迁移后 `status/check/dashboard` 只读 v2 路径。 |
 
 检查失败时不能声称 harness complete；必须修复或记录 owner/action/status 明确的
 residual。
@@ -237,33 +237,33 @@ harness bootstrap 完成后，项目中至少应存在以下文件：
 
 - [ ] `AGENTS.md`，默认 80-160 行，宪章 + 阅读矩阵，不承载安装教程
 - [ ] `CLAUDE.md`，Claude Code 兼容 shim，指向 `AGENTS.md`（不复制完整规范）
-- [ ] `docs/11-REFERENCE/` 下至少 3 个标准文件
-- [ ] `docs/09-PLANNING/TASKS/_task-template/` 包含 task plan / findings / progress / review 模板
-- [ ] `docs/11-REFERENCE/delivery-operating-model-standard.md`
-- [ ] `docs/11-REFERENCE/repo-governance-standard.md`
-- [ ] `docs/11-REFERENCE/ci-cd-standard.md`
-- [ ] `docs/11-REFERENCE/long-running-task-standard.md`
-- [ ] `docs/11-REFERENCE/adversarial-review-standard.md`
-- [ ] `docs/11-REFERENCE/review-routing-standard.md`
-- [ ] `docs/09-PLANNING/TASKS/_task-template/long-running-task-contract.md`
-- [ ] `docs/09-PLANNING/TASKS/_task-template/review.md`
-- [ ] `docs/05-TEST-QA/Regression-SSoT.md`
-- [ ] `docs/05-TEST-QA/Cadence-Ledger.md`
-- [ ] `docs/10-WALKTHROUGH/_walkthrough-template.md`
-- [ ] `docs/10-WALKTHROUGH/Closeout-SSoT.md`
-- [ ] `docs/01-GOVERNANCE/lessons/`（空目录 + .gitkeep）
-- [ ] `docs/01-GOVERNANCE/_archive/`（空目录 + .gitkeep）
-- [ ] `docs/Harness-Ledger.md`
-- [ ] `docs/11-REFERENCE/external-source-intake-standard.md`
-- [ ] `docs/11-REFERENCE/harness-ledger-standard.md`
+- [ ] `coding-agent-harness/governance/standards/` 下至少 3 个标准文件
+- [ ] `coding-agent-harness/planning/tasks/_task-template/` 包含 task plan / findings / progress / review 模板
+- [ ] `coding-agent-harness/governance/standards/delivery-operating-model-standard.md`
+- [ ] `coding-agent-harness/governance/standards/repo-governance-standard.md`
+- [ ] `coding-agent-harness/governance/standards/ci-cd-standard.md`
+- [ ] `coding-agent-harness/governance/standards/long-running-task-standard.md`
+- [ ] `coding-agent-harness/governance/standards/adversarial-review-standard.md`
+- [ ] `coding-agent-harness/governance/standards/review-routing-standard.md`
+- [ ] `coding-agent-harness/planning/tasks/_task-template/long-running-task-contract.md`
+- [ ] `coding-agent-harness/planning/tasks/_task-template/review.md`
+- [ ] `coding-agent-harness/governance/regression/Regression-SSoT.md`
+- [ ] `coding-agent-harness/governance/regression/Cadence-Ledger.md`
+- [ ] `coding-agent-harness/governance/standards/walkthrough-template.md`
+- [ ] `coding-agent-harness/governance/generated/Closeout-Index.md`
+- [ ] `coding-agent-harness/governance/lessons/`（空目录 + .gitkeep）
+- [ ] `coding-agent-harness/governance/_archive/`（空目录 + .gitkeep）
+- [ ] `coding-agent-harness/governance/generated/Harness-Ledger.md`
+- [ ] `coding-agent-harness/governance/standards/external-source-intake-standard.md`
+- [ ] `coding-agent-harness/governance/standards/harness-ledger-standard.md`
 - [ ] `.github/pull_request_template.md` 或 platform-specific PR template / residual
 - [ ] CI workflow 或 `ci-cd-standard.md` 中的 blocked-with-owner residual
 - [ ] Branch protection plan 和 required checks 状态
 - [ ] Worktree concurrency policy
-- [ ] Delivery operating model 已选择；多人/多仓模式下有 `docs/09-PLANNING/Delivery-SSoT.md`
-- [ ] 如启用模块并行：`docs/09-PLANNING/Module-Registry.md`
-- [ ] 如启用模块并行：`docs/09-PLANNING/MODULES/Session-Prompt-Pack.md` 或每模块 `session_prompt.md`
-- [ ] 如启用模块并行：每个 active module 有 `docs/09-PLANNING/MODULES/<key>/module_plan.md`
+- [ ] Delivery operating model 已选择；多人/多仓模式下有 `coding-agent-harness/planning/Delivery-SSoT.md`
+- [ ] 如启用模块并行：`coding-agent-harness/planning/modules/Module-Registry.md`
+- [ ] 如启用模块并行：`coding-agent-harness/planning/modules/Session-Prompt-Pack.md` 或每模块 `session_prompt.md`
+- [ ] 如启用模块并行：每个 active module 有 `coding-agent-harness/planning/modules/<key>/module_plan.md`
 - [ ] 如启用模块并行：模块 task template / shared lock / dependency readiness 规则已落地
 - [ ] Harness checker 已通过，或 residual 写明 owner/action/status
 - [ ] Bootstrap Summary 已输出给用户
@@ -286,7 +286,7 @@ harness 搭建完成后，每个 feature 从想法到代码的标准流程：
 10. **Review Routing** — planned task 收口前自动触发 subagent / reviewer 审查，或记录 skip reason；Review queue 只等待 Human Review Confirmation，缺材料和 blocker 分别进入 Missing Materials / Blocked 队列
 11. **Merge + 自动回归** — Cadence Ledger 触发对应回归面；coordinator 只集成 worker commit，不混合多个 worker 的未提交改动
 12. **Walkthrough 收口** — 写收口记录并引用 review report
-13. **Closeout SSoT 回写** — 每个 closed 任务必须记录 walkthrough 路径或受控 skip reason
+13. **Closeout Index 回写** — 每个 closed 任务必须记录 walkthrough 路径或受控 skip reason
 14. **Lessons Reflection** — 写 walkthrough 时主动反思共性/反复问题；新任务用 `lesson_candidates.md` 承载人工判定，`queued-promotion` 进入 Lessons 队列；默认先 dry-run 或创建沉淀任务，不直接写共享 Lessons 表；`checked-created` 必须有 promoted lesson 详情文档，旧任务兼容的 `checked-none` 必须写明原因
 15. **Generated Ledger 刷新** — 由 lifecycle CLI 或 `harness governance rebuild` 生成任务生命周期总索引
 16. **Worktree 清理** — 删除已 merge 的 worktree
@@ -316,7 +316,7 @@ harness 搭建完成后，每个 feature 从想法到代码的标准流程：
 | Harness Ledger | `references/harness-ledger.md` | 理解 generated task lifecycle ledger 与非任务治理表边界时 |
 | Regression | `references/regression-system.md` | 设计或更新回归面、evidence depth 和 gate 时 |
 | Cadence Ledger | `references/cadence-ledger.md` | 根据改动类型触发回归批次时 |
-| Walkthrough | `references/walkthrough-closeout.md` | 收口、Closeout SSoT 和交付说明时 |
+| Walkthrough | `references/walkthrough-closeout.md` | 收口、Closeout Index 和交付说明时 |
 | Worktree | `references/worktree-parallel.md` | 并行开发、worker handoff 或隔离分支时 |
 
 ## Template 索引
@@ -339,7 +339,7 @@ harness 搭建完成后，每个 feature 从想法到代码的标准流程：
 | Long-Running Task Contract | `templates/planning/long-running-task-contract.md` | 长程任务授权、review loop 和停止条件 |
 | Module Session Prompt | `templates/planning/module_session_prompt.md` | 模块并行开发会话冷启动 |
 | Walkthrough | `templates/walkthrough/walkthrough-template.md` | 任务收口记录 |
-| Closeout SSoT | `templates/walkthrough/Closeout-SSoT.md` | closed task 索引和收口证据 |
+| Closeout Index | `templates/walkthrough/walkthrough-template.md` | closed task 索引和收口证据 |
 | Testing Standard | `templates/reference/testing-standard.md` | 测试、冒烟和回归规范 |
 | Execution Workflow | `templates/reference/execution-workflow-standard.md` | 执行、提交、PR 和证据记录 |
 | Delivery Operating Model Standard | `templates/reference/delivery-operating-model-standard.md` | 交付组织模型选择 |

package/dist/build-dist.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const typescriptVersion = "5.9.3";
+export function buildRuntimeDist({ projectRoot = repoRoot, configPath = path.join(projectRoot, "tsconfig.dist.json"), outDir = path.join(projectRoot, "dist"), } = {}) {
+    const absoluteProjectRoot = path.resolve(projectRoot);
+    const absoluteConfig = path.resolve(configPath);
+    const absoluteOutDir = path.resolve(outDir);
+    const defaultDist = path.join(absoluteProjectRoot, "dist");
+    const buildOutDir = absoluteOutDir === defaultDist
+        ? fs.mkdtempSync(path.join(os.tmpdir(), "coding-agent-harness-dist-build-"))
+        : absoluteOutDir;
+    if (!fs.existsSync(absoluteConfig)) {
+        return {
+            ok: false,
+            error: `dist build config not found: ${absoluteConfig}`,
+        };
+    }
+    if (isDangerousOutDir({ projectRoot: absoluteProjectRoot, outDir: absoluteOutDir })) {
+        return {
+            ok: false,
+            error: `refusing to clean unsafe dist output directory: ${absoluteOutDir}`,
+        };
+    }
+    fs.rmSync(buildOutDir, { recursive: true, force: true });
+    const emit = spawnSync("npm", ["exec", "--yes", "--package", `typescript@${typescriptVersion}`, "--", "tsc", "-p", absoluteConfig, "--outDir", buildOutDir, "--noCheck"], {
+        cwd: absoluteProjectRoot,
+        encoding: "utf8",
+    });
+    if (emit.status !== 0) {
+        return {
+            ok: false,
+            error: `TypeScript dist build failed\nSTDOUT:\n${emit.stdout}\nSTDERR:\n${emit.stderr}`,
+            status: emit.status,
+        };
+    }
+    if (buildOutDir !== absoluteOutDir) {
+        syncDirectory(buildOutDir, absoluteOutDir);
+        fs.rmSync(buildOutDir, { recursive: true, force: true });
+    }
+    const files = collectFiles(absoluteOutDir).filter((file) => file.endsWith(".mjs")).sort();
+    const relativeFiles = files.map((file) => toPosix(path.relative(absoluteOutDir, file)));
+    const requiredFiles = [
+        "harness.mjs",
+        "postinstall.mjs",
+        "lib/harness-core.mjs",
+        "commands/task-command.mjs",
+    ];
+    const missingFiles = requiredFiles.filter((file) => !relativeFiles.includes(file));
+    if (missingFiles.length > 0) {
+        return {
+            ok: false,
+            error: `dist build missing required runtime files: ${missingFiles.join(", ")}`,
+            outDir: absoluteOutDir,
+            files: relativeFiles,
+        };
+    }
+    return {
+        ok: true,
+        outDir: absoluteOutDir,
+        files: relativeFiles,
+    };
+}
+function isDangerousOutDir({ projectRoot, outDir }) {
+    const parsed = path.parse(outDir);
+    if (outDir === parsed.root)
+        return true;
+    if (outDir === projectRoot)
+        return true;
+    const defaultDist = path.join(projectRoot, "dist");
+    if (outDir === defaultDist || outDir.startsWith(`${defaultDist}${path.sep}`))
+        return false;
+    const relativeToProject = path.relative(projectRoot, outDir);
+    if (relativeToProject && !relativeToProject.startsWith("..") && !path.isAbsolute(relativeToProject))
+        return true;
+    const tempRoot = fs.realpathSync.native(os.tmpdir());
+    const outputParent = fs.existsSync(path.dirname(outDir)) ? fs.realpathSync.native(path.dirname(outDir)) : path.resolve(path.dirname(outDir));
+    if (outputParent === tempRoot || outputParent.startsWith(`${tempRoot}${path.sep}`))
+        return false;
+    return true;
+}
+function collectFiles(directory) {
+    const files = [];
+    if (fs.existsSync(directory))
+        walk(directory, files);
+    return files;
+}
+function walk(current, files) {
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink())
+        return;
+    if (stat.isDirectory()) {
+        for (const entry of fs.readdirSync(current))
+            walk(path.join(current, entry), files);
+        return;
+    }
+    if (stat.isFile())
+        files.push(current);
+}
+function syncDirectory(sourceDir, targetDir) {
+    fs.mkdirSync(targetDir, { recursive: true });
+    const sourceEntries = new Set(fs.readdirSync(sourceDir));
+    for (const entry of sourceEntries) {
+        const source = path.join(sourceDir, entry);
+        const target = path.join(targetDir, entry);
+        const stat = fs.lstatSync(source);
+        if (stat.isDirectory()) {
+            syncDirectory(source, target);
+        }
+        else if (stat.isFile()) {
+            const tempTarget = `${target}.tmp-${process.pid}`;
+            fs.copyFileSync(source, tempTarget);
+            fs.renameSync(tempTarget, target);
+        }
+    }
+    for (const entry of fs.readdirSync(targetDir)) {
+        if (sourceEntries.has(entry))
+            continue;
+        if (entry.includes(".tmp-"))
+            continue;
+        fs.rmSync(path.join(targetDir, entry), { recursive: true, force: true });
+    }
+}
+function toPosix(value) {
+    return value.split(path.sep).join("/");
+}
+function parseArgs(argv) {
+    const options = {
+        projectRoot: repoRoot,
+        configPath: path.join(repoRoot, "tsconfig.dist.json"),
+        outDir: path.join(repoRoot, "dist"),
+        json: false,
+        quiet: false,
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--json") {
+            options.json = true;
+        }
+        else if (arg === "--quiet") {
+            options.quiet = true;
+        }
+        else if (arg === "--out-dir") {
+            options.outDir = path.resolve(options.projectRoot, requireValue(argv, index, arg));
+            index += 1;
+        }
+        else if (arg === "--config") {
+            options.configPath = path.resolve(options.projectRoot, requireValue(argv, index, arg));
+            index += 1;
+        }
+        else {
+            throw new Error(`Unknown build-dist option: ${arg}`);
+        }
+    }
+    return options;
+}
+function requireValue(argv, index, option) {
+    const value = argv[index + 1];
+    if (!value)
+        throw new Error(`${option} requires a value`);
+    return value;
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    let options;
+    try {
+        options = parseArgs(process.argv.slice(2));
+    }
+    catch (error) {
+        console.error(error.message);
+        process.exit(1);
+    }
+    const result = buildRuntimeDist(options);
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else if (result.ok && !options.quiet) {
+        console.log(`Runtime dist build completed: ${path.relative(repoRoot, result.outDir) || "."} (${result.files.length} files)`);
+    }
+    else if (!result.ok) {
+        console.error(result.error);
+    }
+    if (!result.ok)
+        process.exit(result.status || 1);
+}