coding-agent-harness 1.0.5 → 1.0.7

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

@@ -8,9 +8,9 @@ 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 scripts/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`.
 
-`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 scripts/harness.mjs` from the source checkout.
+`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.
 
 `npx skills add FairladyZ625/coding-agent-harness --skill coding-agent-harness`
 is not a zero-write operation. It copies the Skill into `.agents/skills/coding-agent-harness/`
@@ -41,7 +41,7 @@ Use the v1.0 six-phase flow:
 5. Verify: run CLI checks and native project evidence.
 6. Deliver: report residuals, owners, and next actions.
 
-If Diagnose finds a microservice, multi-repo, split frontend/backend, or platform subsystem, or the code references external services, SDKs, API gateways, message queues, webhooks, contracts, schemas, or mocks, the agent must ask the user whether external source material exists. Small source sets can be linked from `Source Evidence`; large source sets use `docs/11-REFERENCE/external-source-intake-standard.md` and `docs/04-DEVELOPMENT/external-source-packs/<source-key>/`, then project stable conclusions into `03/04/06`.
+If Diagnose finds a microservice, multi-repo, split frontend/backend, or platform subsystem, or the code references external services, SDKs, API gateways, message queues, webhooks, contracts, schemas, or mocks, the agent must ask the user whether external source material exists. Small source sets can be linked from `Source Evidence`; large source sets use `coding-agent-harness/governance/standards/external-source-intake-standard.md` and `coding-agent-harness/context/development/external-source-packs/<source-key>/`, then project stable conclusions into `context/{architecture,development,integrations}`.
 
 ## Locale Rules
 
@@ -77,7 +77,6 @@ Choose capabilities conservatively:
 | --- | --- | --- |
 | `core` | Yes | Always install. This is the document kernel. |
 | `dashboard` | No | A user or agent needs a local status page, static evidence snapshot, or localhost dynamic workbench. |
-| `safe-adoption` | No | A legacy Harness project adopts v1.0 while preserving history. |
 | `adversarial-review` | No | Release, architecture, security, data, or policy risk needs independent review artifacts. |
 | `long-running-task` | No | An agent needs to execute across many turns without asking the user at every step. |
 | `module-parallel` | No | Two or more independent modules need owners, a registry, and synchronization rules. |
@@ -98,7 +97,7 @@ The JSON output from `init` includes a `report`. The delivery summary must inclu
 
 ## External Source Intake
 
-When a project depends on external microservices, repositories, or external-team documents, agents should not drop those materials directly into `03-ARCHITECTURE`, `04-DEVELOPMENT`, or `06-INTEGRATIONS`. Use this order:
+When a project depends on external microservices, repositories, or external-team documents, agents should not drop those materials directly into `context/architecture`, `context/development`, or `context/integrations`. Use this order:
 
 ```text
 Inventory -> Classify -> Sanitize -> Digest -> Project -> Verify -> Residual
@@ -108,9 +107,9 @@ Rules:
 
 - Ask the user for external architecture docs, API docs, diagrams, meeting notes, links, source paths, or exported packets.
 - Confirm whether the material may be copied into the repository; non-committable material is represented by path, URL, owner, access condition, and digest only.
-- If there are more than 5 external documents, multiple topics, or continuing growth, create `docs/04-DEVELOPMENT/external-source-packs/<source-key>/`.
+- If there are more than 5 external documents, multiple topics, or continuing growth, create `coding-agent-harness/context/development/external-source-packs/<source-key>/`.
 - `external-source-packs/` stores source indexes, digests, and projection status only.
-- Stable facts must be written back to `03-ARCHITECTURE/services/<service-key>.md`, `04-DEVELOPMENT/external-context/<service-key>.md`, or `06-INTEGRATIONS/<contract>.md`.
+- Stable facts must be written back to `coding-agent-harness/context/architecture/services/<service-key>.md`, `coding-agent-harness/context/development/external-context/<service-key>.md`, or `coding-agent-harness/context/integrations/<contract>.md`.
 - Unconfirmed or conflicting material stays in the source pack or `Do Not Assume`.
 
 ## User-Level Registration
@@ -164,11 +163,17 @@ harness migrate-run \
 
 harness migrate-verify \
   /tmp/cah-migration-project/session.json
+
+harness new-task \
+  --budget complex \
+  --preset legacy-migration \
+  --from-session /tmp/cah-migration-project/session.json \
+  /path/to/old-project
 ```
 
 Rules:
 
-- Do not overwrite existing `AGENTS.md`, `CLAUDE.md`, `docs/Harness-Ledger.md`, SSoTs, walkthroughs, task progress, or historical task plans.
+- Do not overwrite existing `AGENTS.md`, `CLAUDE.md`, `coding-agent-harness/governance/generated/Harness-Ledger.md`, SSoTs, walkthroughs, task progress, or historical task plans.
 - When the old project mixes Chinese and English, explicitly pass `--locale zh-CN` or `--locale en-US`.
 - Only add the missing v1.0 templates and capability registry.
 - Existing project facts may be merged, appended, or recorded as residuals. They must not be replaced with generic templates.
@@ -176,6 +181,7 @@ Rules:
 - `--strict` must still fail on legacy checker failures or unresolved historical contract gaps.
 - Archive old global tables and module indexes first, then regenerate them with `harness governance rebuild --archive --apply`; those tables are agent indexes, while humans should use the Dashboard for status.
 - `migrate-verify` must pass before the migration output is reported as usable, and the dashboard path must be HTML.
+- The `legacy-migration` preset task must be created from the verified `session.json`. It records the migration session, evidence bundle, preset audit, and follow-up work queue; it does not automatically rewrite historical task bodies.
 - For detailed migration strategy, read `docs-release/guides/migration-playbook.md` or `docs-release/guides/migration-playbook.en-US.md`. If the user requires proof that the old project is fully migrated, also read `docs-release/guides/full-legacy-migration-subagent-strategy.md` or `docs-release/guides/full-legacy-migration-subagent-strategy.zh-CN.md`.
 
 The agent must read `session.json` and `migrate-plan.json`, then migrate active tasks, current reviews, and truly adopted capabilities step by step. Subagent review must prove dashboard brief coverage, strict check, and final session all pass.

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

@@ -15,13 +15,13 @@ 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 scripts/harness.mjs`。
+维护者在本源码仓调试时，可以把同一命令替换为 `node dist/harness.mjs`。
 
 `harness init` 不会把 npm 包写进目标项目依赖；它只写 Harness 文档、模板和 registry。
 因此 agent 交付时不能暗示目标项目已经安装了 npm dependency。`npx` 第一次运行会把包
 下载到 npm 缓存；这不是项目依赖，也不是全局命令安装。需要 CLI 时继续用
 `npx --yes coding-agent-harness ...`、用户批准后的全局 `harness`，或源码仓的
-`node scripts/harness.mjs`。
+`node dist/harness.mjs`。
 
 `npx skills add FairladyZ625/coding-agent-harness --skill coding-agent-harness`
 不是零写入操作。它会把 Skill 拷贝到目标项目的 `.agents/skills/coding-agent-harness/`
@@ -51,7 +51,7 @@ npx skills add FairladyZ625/coding-agent-harness --skill preset-creator --full-d
 5. Verify：运行 CLI 检查和项目原生证据。
 6. Deliver：输出 residual、owner 和下一步。
 
-如果 Diagnose 阶段发现项目属于微服务、多仓、前后端分仓、平台子系统，或代码里有外部服务、SDK、API gateway、message queue、webhook、contract、schema、mock，Agent 必须询问用户是否有外部资料。资料少时作为 `Source Evidence` 链接；资料多时按 `docs/11-REFERENCE/external-source-intake-standard.md` 建立 `docs/04-DEVELOPMENT/external-source-packs/<source-key>/`，再把稳定结论投影到 `03/04/06`。
+如果 Diagnose 阶段发现项目属于微服务、多仓、前后端分仓、平台子系统，或代码里有外部服务、SDK、API gateway、message queue、webhook、contract、schema、mock，Agent 必须询问用户是否有外部资料。资料少时作为 `Source Evidence` 链接；资料多时按 `coding-agent-harness/governance/standards/external-source-intake-standard.md` 建立 `coding-agent-harness/context/development/external-source-packs/<source-key>/`，再把稳定结论投影到 `context/{architecture,development,integrations}`。
 
 ## 语言规则
 
@@ -89,7 +89,6 @@ Capability 要保守选择：
 | --- | --- | --- |
 | `core` | 是 | 永远安装。这是 document kernel。 |
 | `dashboard` | 否 | 用户或 agent 需要本地状态页、静态证据快照，或本机动态 workbench。 |
-| `safe-adoption` | 否 | 旧 harness 项目接入 v1.0，需要保留历史文档。 |
 | `adversarial-review` | 否 | 发布、架构、安全、数据或策略风险需要独立 review artifact。 |
 | `long-running-task` | 否 | Agent 需要连续多轮执行，不能每步都询问用户。 |
 | `module-parallel` | 否 | 两个以上独立模块需要 owner、registry 和同步规则。 |
@@ -112,7 +111,7 @@ Capability 要保守选择：
 
 ## 外部资料摄取
 
-当项目依赖外部微服务、外部仓库或外部团队文档时，Agent 不应该把外部资料直接塞进 `03-ARCHITECTURE`、`04-DEVELOPMENT` 或 `06-INTEGRATIONS`。正确顺序是：
+当项目依赖外部微服务、外部仓库或外部团队文档时，Agent 不应该把外部资料直接塞进 `context/architecture`、`context/development` 或 `context/integrations`。正确顺序是：
 
 ```text
 Inventory -> Classify -> Sanitize -> Digest -> Project -> Verify -> Residual
@@ -122,9 +121,9 @@ Inventory -> Classify -> Sanitize -> Digest -> Project -> Verify -> Residual
 
 - 询问用户是否有外部架构文档、接口文档、流程图、会议纪要、链接或导出包。
 - 确认资料是否能复制进仓；不能入仓的只保留路径、URL、owner、访问条件和 digest。
-- 外部资料超过 5 份、跨多个主题或会持续增长时，创建 `docs/04-DEVELOPMENT/external-source-packs/<source-key>/`。
+- 外部资料超过 5 份、跨多个主题或会持续增长时，创建 `coding-agent-harness/context/development/external-source-packs/<source-key>/`。
 - `external-source-packs/` 只保存资料索引、digest 和投影状态。
-- 稳定事实必须回写到 `03-ARCHITECTURE/services/<service-key>.md`、`04-DEVELOPMENT/external-context/<service-key>.md` 或 `06-INTEGRATIONS/<contract>.md`。
+- 稳定事实必须回写到 `coding-agent-harness/context/architecture/services/<service-key>.md`、`coding-agent-harness/context/development/external-context/<service-key>.md` 或 `coding-agent-harness/context/integrations/<contract>.md`。
 - 未确认或冲突的内容只能留在 source pack 或 `Do Not Assume`。
 
 ## 用户级注册
@@ -179,11 +178,17 @@ harness migrate-run \
 
 harness migrate-verify \
   /tmp/cah-migration-project/session.json
+
+harness new-task \
+  --budget complex \
+  --preset legacy-migration \
+  --from-session /tmp/cah-migration-project/session.json \
+  /path/to/old-project
 ```
 
 规则：
 
-- 不覆盖已有 `AGENTS.md`、`CLAUDE.md`、`docs/Harness-Ledger.md`、SSoT、
+- 不覆盖已有 `AGENTS.md`、`CLAUDE.md`、`coding-agent-harness/governance/generated/Harness-Ledger.md`、SSoT、
   walkthrough、task progress 和历史 task plan。
 - 旧项目中英文混杂时，必须显式传 `--locale zh-CN` 或 `--locale en-US`。
 - 只补齐缺失的 v1.0 模板和 capability registry。
@@ -192,6 +197,7 @@ harness migrate-verify \
 - `--strict` 必须仍然能因为旧 checker 失败或历史合同缺口而失败。
 - 旧全局表和模块索引先归档，再用 `harness governance rebuild --archive --apply` 重新生成；这些表是 Agent 索引，人看状态优先用 Dashboard。
 - `migrate-verify` 必须通过，才能报告迁移输出可用；dashboard 路径必须是 HTML。
+- 必须基于验证通过的 `session.json` 创建 `legacy-migration` preset 任务。它记录 migration session、证据包、preset audit 和后续 work queue；不会自动重写历史任务正文。
 - 详细迁移策略见 `docs-release/guides/migration-playbook.md` 或英文镜像
   `docs-release/guides/migration-playbook.en-US.md`。如果用户要求证明旧项目已经完整迁移，
   还必须读取 `docs-release/guides/full-legacy-migration-subagent-strategy.md` 或中文镜像

package/docs-release/guides/contributing.md

@@ -18,7 +18,7 @@ Keep pull requests focused on one change family when possible. Documentation, CL
 
 ## Local Setup
 
-Use Node.js 18 or newer. CI runs Node.js 20.
+Use Node.js 24 or newer. CI should run on the minimum supported LTS line.
 
 ```bash
 npm install
@@ -40,7 +40,7 @@ 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` |
@@ -51,7 +51,7 @@ Full root suite:
 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/docs-release/guides/contributing.zh-CN.md

@@ -18,7 +18,7 @@ PR 尽量聚焦在一类改动上。文档、CLI 行为、目标项目模板、p
 
 ## 本地准备
 
-使用 Node.js 18 或更高版本。CI 当前使用 Node.js 20。
+使用 Node.js 24 或更高版本。CI 应覆盖最低支持的 LTS 版本。
 
 ```bash
 npm install
@@ -39,7 +39,7 @@ npm ci
 | --- | --- |
 | 仅文档 | `git diff --check` |
 | CLI / runtime | `npm test`, `npm run check`, `git diff --check` |
-| 模板或示例 | `npm test`, `node scripts/harness.mjs check --profile target-project examples/minimal-project`, `git diff --check` |
+| 模板或示例 | `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 子模块 | `cd harness-gui && npm ci && npm run typecheck && npm test && npm run build` |
@@ -50,7 +50,7 @@ npm ci
 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/docs-release/guides/document-audience-and-surfaces.en-US.md

@@ -27,9 +27,9 @@ Release docs explain public methodology and product capability. They do not carr
 | `references/` | Agents and maintainers | Reusable standards such as testing, workflow, review, worktree rules | A project's current schedule |
 | `templates/` | CLI and agents | Files generated into target projects | Evidence from completed work |
 | Target `AGENTS.md` | Agents | Entrypoint, routing, hard rules, reading matrix | Long background essays |
-| Target `docs/09-PLANNING/` and `docs/Harness-Ledger.md` | Agents and project owners | Task plans, generated task lifecycle index, current state | Generic marketing material |
-| Target `docs/05-TEST-QA/` | Agents, QA, human reviewers | Regression SSoT, Cadence Ledger, quality gates | Requirement brainstorm drafts |
-| Target `docs/10-WALKTHROUGH/` | Reviewers and handoff agents | Closeout evidence, residuals, human confirmation | Unverified plans |
+| Target `coding-agent-harness/planning/` and `coding-agent-harness/governance/generated/Harness-Ledger.md` | Agents and project owners | Task plans, generated task lifecycle index, current state | Generic marketing material |
+| Target `coding-agent-harness/governance/regression/` | Agents, QA, human reviewers | Regression SSoT, Cadence Ledger, quality gates | Requirement brainstorm drafts |
+| Target `coding-agent-harness/planning/tasks/<task>/` | Reviewers and handoff agents | Closeout evidence, residuals, human confirmation | Unverified plans |
 
 ## Human-Facing Docs
 
@@ -62,13 +62,13 @@ Agent-facing docs answer:
 Typical files:
 
 - `AGENTS.md`
-- `docs/Harness-Ledger.md`
-- `docs/09-PLANNING/TASKS/<task>/task_plan.md`
-- `docs/09-PLANNING/TASKS/<task>/task_plan.md`
-- `docs/09-PLANNING/TASKS/<task>/progress.md`
-- `docs/05-TEST-QA/Regression-SSoT.md`
-- `docs/10-WALKTHROUGH/<date>-<task>.md`
-- `docs/11-REFERENCE/*.md`
+- `coding-agent-harness/governance/generated/Harness-Ledger.md`
+- `coding-agent-harness/planning/tasks/<task>/task_plan.md`
+- `coding-agent-harness/planning/tasks/<task>/task_plan.md`
+- `coding-agent-harness/planning/tasks/<task>/progress.md`
+- `coding-agent-harness/governance/regression/Regression-SSoT.md`
+- `coding-agent-harness/planning/tasks/<task>/walkthrough.md`
+- `coding-agent-harness/governance/standards/*.md`
 
 Agent-facing docs should be concrete, path-oriented, and checkable. Do not turn them into essays, and do not make agents infer execution contracts from narrative prose.
 

package/docs-release/guides/document-audience-and-surfaces.md

@@ -27,9 +27,9 @@ Agent 读的文档定义事实、路径、门禁和下一步动作。
 | `references/` | Agent 和维护者 | 可复用标准，例如 testing、workflow、review、worktree | 某个项目的当前排期 |
 | `templates/` | CLI 和 Agent | 初始化目标项目时生成的文件 | 已经执行过的任务证据 |
 | 目标项目 `AGENTS.md` | Agent | 入口、路由、硬规则、读文件矩阵 | 大段背景叙事 |
-| 目标项目 `docs/09-PLANNING/` 与 `docs/Harness-Ledger.md` | Agent 和项目负责人 | 任务计划、生成的任务生命周期索引、当前状态 | 通用营销材料 |
-| 目标项目 `docs/05-TEST-QA/` | Agent、QA、人审 | Regression SSoT、Cadence Ledger、质量门禁 | 需求讨论草稿 |
-| 目标项目 `docs/10-WALKTHROUGH/` | 人审、接手 Agent | 收口证据、残留项、人工确认 | 未验证的计划 |
+| 目标项目 `coding-agent-harness/planning/` 与 `coding-agent-harness/governance/generated/Harness-Ledger.md` | Agent 和项目负责人 | 任务计划、生成的任务生命周期索引、当前状态 | 通用营销材料 |
+| 目标项目 `coding-agent-harness/governance/regression/` | Agent、QA、人审 | Regression SSoT、Cadence Ledger、质量门禁 | 需求讨论草稿 |
+| 目标项目 `coding-agent-harness/planning/tasks/<task>/` | 人审、接手 Agent | 收口证据、残留项、人工确认 | 未验证的计划 |
 
 ## 人读文档
 
@@ -62,13 +62,13 @@ Agent 读文档要回答：
 典型文件：
 
 - `AGENTS.md`
-- `docs/Harness-Ledger.md`
-- `docs/09-PLANNING/TASKS/<task>/task_plan.md`
-- `docs/09-PLANNING/TASKS/<task>/task_plan.md`
-- `docs/09-PLANNING/TASKS/<task>/progress.md`
-- `docs/05-TEST-QA/Regression-SSoT.md`
-- `docs/10-WALKTHROUGH/<date>-<task>.md`
-- `docs/11-REFERENCE/*.md`
+- `coding-agent-harness/governance/generated/Harness-Ledger.md`
+- `coding-agent-harness/planning/tasks/<task>/task_plan.md`
+- `coding-agent-harness/planning/tasks/<task>/task_plan.md`
+- `coding-agent-harness/planning/tasks/<task>/progress.md`
+- `coding-agent-harness/governance/regression/Regression-SSoT.md`
+- `coding-agent-harness/planning/tasks/<task>/walkthrough.md`
+- `coding-agent-harness/governance/standards/*.md`
 
 Agent 文档应该具体、短路径、可检查。不要把它写成文章，也不要让 Agent 从长篇叙事里猜执行合同。
 

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

@@ -44,6 +44,7 @@ Scan first. Do not write files:
 git -C /path/to/project status --short --branch
 harness status --json /path/to/project > /tmp/harness-status.json
 harness migrate-plan --json --limit 1000 /path/to/project > /tmp/harness-migrate-plan.json
+harness migrate-structure --plan --json /path/to/project > /tmp/harness-migrate-structure-plan.json
 ```
 
 Then return a short migration plan and ask for confirmation. The plan must include:
@@ -51,6 +52,7 @@ Then return a short migration plan and ask for confirmation. The plan must inclu
 - task count, brief coverage, and canonical `visual_map.md` coverage;
 - `migrate-plan.summary` warnings, taskActions, reviewSchemaGaps, legacyReferenceGaps, legacyResiduals, and fullCutoverEligible;
 - dirty / untracked file explanation;
+- v2 structure plan, including whether the active Harness root is the default `coding-agent-harness/` or a custom `structure.harnessRoot`;
 - whether the project is a microservice, multi-repo, split frontend/backend, or externally integrated project, and whether the user has been asked for external source material;
 - recommended migration mode and rationale;
 - estimated write scope, token / time cost, and whether subagents are needed;
@@ -81,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 scripts/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, replace `harness` with `node dist/harness.mjs`.
 
 After user confirmation, run or reuse:
 
@@ -101,7 +103,14 @@ Before writing files:
   - `--locale zh-CN` for Chinese users, Chinese project operating context, or Chinese-facing docs.
   - `--locale en-US` for English teams or English-facing docs.
 - Record concrete locale evidence from entry files or product-facing docs, such as `AGENTS.md`, `CLAUDE.md`, `README.md`, `docs/Harness-Ledger.md`, and active task docs. Stop and ask for a locale decision if those signals conflict.
-- Run the migration rail:
+- Run the v2 directory-structure migration, then the migration rail:
+
+```bash
+harness migrate-structure --apply --json /path/to/project
+harness check --profile target-project /path/to/project
+```
+
+Then create the migration session:
 
 ```bash
 harness migrate-run \
@@ -122,6 +131,20 @@ The command writes:
 - `status-strict.json`
 - `dashboard/index.html`
 
+After `migrate-run`, verify the session and create the controlled migration task:
+
+```bash
+harness migrate-verify /tmp/cah-migration-project/session.json
+
+harness new-task \
+  --budget complex \
+  --preset legacy-migration \
+  --from-session /tmp/cah-migration-project/session.json \
+  /path/to/project
+```
+
+Do not skip the `legacy-migration` preset task. It creates a Complex Task that records the session, evidence bundle, preset manifest audit, write scope, and migration follow-up queue. It does not automatically rewrite historical task bodies. If `harness new-task --preset legacy-migration` fails, stop and report that the migration task was not created instead of continuing from a verbal summary.
+
 Classify the output:
 
 | Output | Meaning | Action |

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

@@ -44,6 +44,7 @@ English source: `docs-release/guides/legacy-migration-agent-prompt.md`
 git -C /path/to/project status --short --branch
 harness status --json /path/to/project > /tmp/harness-status.json
 harness migrate-plan --json --limit 1000 /path/to/project > /tmp/harness-migrate-plan.json
+harness migrate-structure --plan --json /path/to/project > /tmp/harness-migrate-structure-plan.json
 ```
 
 然后给用户一个简短迁移计划，并主动提问。计划必须包含：
@@ -51,6 +52,7 @@ harness migrate-plan --json --limit 1000 /path/to/project > /tmp/harness-migrate
 - 任务总数、brief 覆盖、canonical `visual_map.md` 覆盖。
 - `migrate-plan.summary` 中的 warnings、taskActions、reviewSchemaGaps、legacyReferenceGaps、legacyResiduals、fullCutoverEligible。
 - dirty / untracked 文件解释。
+- v2 目录结构计划，包括活跃 Harness 根目录是默认的 `coding-agent-harness/`，还是自定义的 `structure.harnessRoot`。
 - 是否属于微服务、多仓、前后端分仓或外部集成项目；如果是，是否已询问用户外部资料。
 - 推荐迁移模式和原因。
 - 预计改动范围、token / 时间成本、是否需要 subagent。
@@ -81,7 +83,7 @@ Agent 应推荐下面三种模式之一，而不是让用户自己先懂这些
 
 ## Step 1: Baseline
 
-先检查目标环境是否有 `harness` 命令。如果没有，不要静默全局安装。先询问用户是否允许运行 `npm install -g coding-agent-harness`。只有用户明确同意后才执行全局安装。用户不同意或未回复时，Harness CLI 都用 `npx --yes coding-agent-harness <command>` 临时执行。如果你在源码仓调试，把 `harness` 替换为 `node scripts/harness.mjs`。
+先检查目标环境是否有 `harness` 命令。如果没有，不要静默全局安装。先询问用户是否允许运行 `npm install -g coding-agent-harness`。只有用户明确同意后才执行全局安装。用户不同意或未回复时，Harness CLI 都用 `npx --yes coding-agent-harness <command>` 临时执行。如果你在源码仓调试，把 `harness` 替换为 `node dist/harness.mjs`。
 
 用户确认迁移模式后再运行或复用：
 
@@ -102,7 +104,14 @@ harness migrate-plan --json --limit 50 /path/to/project > /tmp/harness-migrate-p
   - 英文团队或英文对外文档使用 `--locale en-US`。
 - 从入口文件或产品文档记录具体语言证据，例如 `AGENTS.md`、`CLAUDE.md`、`README.md`、`docs/Harness-Ledger.md` 和活跃任务文档。信号冲突时停止并让用户决定语言。
 
-运行迁移轨道：
+先运行 v2 目录结构迁移，再运行迁移轨道：
+
+```bash
+harness migrate-structure --apply --json /path/to/project
+harness check --profile target-project /path/to/project
+```
+
+然后创建 migration session：
 
 ```bash
 harness migrate-run \
@@ -123,6 +132,20 @@ harness migrate-run \
 - `status-strict.json`
 - `dashboard/index.html`
 
+`migrate-run` 之后，先验证 session，再创建受控迁移任务：
+
+```bash
+harness migrate-verify /tmp/cah-migration-project/session.json
+
+harness new-task \
+  --budget complex \
+  --preset legacy-migration \
+  --from-session /tmp/cah-migration-project/session.json \
+  /path/to/project
+```
+
+不要跳过 `legacy-migration` preset 任务。它会创建一个 Complex Task，把 session、证据包、preset manifest audit、write scope 和 migration follow-up queue 记录下来；它不会自动重写历史任务正文。如果 `harness new-task --preset legacy-migration` 失败，停止并报告迁移任务没有创建，不要只靠口头总结继续。
+
 输出分类：
 
 | Output | 含义 | 动作 |

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

@@ -11,7 +11,40 @@ 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 scripts/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`.
+
+## Target Path And v2 Structure
+
+The default active v2 directory is `coding-agent-harness/` inside the target
+project, with `coding-agent-harness/harness.yaml` as the entry file. Checks do
+not require that exact folder name. If a project keeps Harness state in a custom
+project-relative directory, such as `.project-control/harness-state/`, declare it
+in that directory's `harness.yaml`:
+
+```yaml
+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
+```
+
+Then commands can run from the project root:
+
+```bash
+harness status --json /path/to/project
+harness check --profile target-project /path/to/project
+```
+
+They can also point directly at the Harness root:
+
+```bash
+harness status --json /path/to/project/.project-control/harness-state
+```
+
+If a project contains multiple `harness.yaml` files, the agent must not guess.
+Pass the intended Harness root explicitly.
 
 ## Migration Principles
 
@@ -31,6 +64,7 @@ After receiving the migration prompt, the target-project agent starts with read-
 git -C /path/to/project status --short --branch
 harness status --json /path/to/project
 harness migrate-plan --json --limit 1000 /path/to/project
+harness migrate-structure --plan --json /path/to/project
 ```
 
 Then the agent must give the user a migration plan and actively recommend a migration depth:
@@ -65,6 +99,22 @@ If this run does not yet have a user-confirmed migration depth, stop here and do
 
 2. Run the migration rail:
 
+First migrate the old `docs/` layout into the v2 manifest layout. `--plan` is a
+read-only preview; run `--apply` only after user confirmation. The default
+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:
+
+```bash
+harness migrate-structure --plan --json /path/to/project
+harness migrate-structure --apply --json /path/to/project
+harness check --profile target-project /path/to/project
+```
+
+After the directory migration passes, run the session migration rail:
+
 ```bash
 harness migrate-run \
   --locale zh-CN \
@@ -92,6 +142,18 @@ harness migrate-verify /tmp/cah-migration-project/session.json
 
 `migrate-verify` checks the capability registry, locale, dashboard HTML path, normal check, strict deferred metadata, and git index. Only after it passes may the agent say the migration output is usable.
 
+4. Create the migration task from the verified session:
+
+```bash
+harness new-task \
+  --budget complex \
+  --preset legacy-migration \
+  --from-session /tmp/cah-migration-project/session.json \
+  /path/to/project
+```
+
+The `legacy-migration` preset task is the auditable handoff point for later work. It records the session, evidence bundle, preset audit, write scope, and migration follow-up queue. It does not automatically rewrite historical task bodies.
+
 If later cleanup repairs warnings or active task contracts, the first session is only the baseline. Before final delivery, rerun `migrate-run` for a fresh session/dashboard or explicitly label the differences between baseline session and final evidence.
 
 `migrate-verify` passing does not mean the full migration is complete. Full migration also requires:

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

@@ -15,7 +15,38 @@ 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 scripts/harness.mjs`。
+可以把同一命令替换为 `node dist/harness.mjs`。
+
+## 目标路径和 v2 结构
+
+v2 的默认活跃目录是目标项目里的 `coding-agent-harness/`，入口文件是
+`coding-agent-harness/harness.yaml`。但检查目标不要求这个目录一定在仓库根目录下使用固定名称。
+如果项目已经把 Harness 状态放在自定义目录，例如
+`.project-control/harness-state/`，需要在该目录的 `harness.yaml` 中声明：
+
+```yaml
+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
+```
+
+之后可以从项目根运行：
+
+```bash
+harness status --json /path/to/project
+harness check --profile target-project /path/to/project
+```
+
+也可以直接指向 Harness 根目录：
+
+```bash
+harness status --json /path/to/project/.project-control/harness-state
+```
+
+如果一个项目下存在多个 `harness.yaml`，不要让 agent 猜；必须把目标 Harness 根目录作为命令参数传入。
 
 ## 迁移原则
 
@@ -35,6 +66,7 @@ English mirror: `docs-release/guides/migration-playbook.en-US.md`
 git -C /path/to/project status --short --branch
 harness status --json /path/to/project
 harness migrate-plan --json --limit 1000 /path/to/project
+harness migrate-structure --plan --json /path/to/project
 ```
 
 然后 agent 必须给用户一份迁移计划，并主动推荐迁移深度：
@@ -69,6 +101,20 @@ Agent 必须记录具体判断证据，例如 `AGENTS.md`、`CLAUDE.md`、`READM
 
 2. 运行迁移轨道：
 
+先把旧 `docs/` 布局迁到 v2 manifest 布局。`--plan` 是只读预览；用户确认后才运行
+`--apply`。默认迁移目标是 `coding-agent-harness/`，并会把旧 `docs/` 归档到
+`coding-agent-harness/governance/archive/legacy-docs/`。旧版本遗留的
+`planning/**/_task-template` 和 `planning/**/_module-template` 是 npm 包内模板的生成副本，
+迁移时会从目标项目中移除：
+
+```bash
+harness migrate-structure --plan --json /path/to/project
+harness migrate-structure --apply --json /path/to/project
+harness check --profile target-project /path/to/project
+```
+
+目录迁移通过后，再运行 session 迁移轨道：
+
 ```bash
 harness migrate-run \
   --locale zh-CN \
@@ -96,6 +142,18 @@ harness migrate-verify /tmp/cah-migration-project/session.json
 
 `migrate-verify` 会检查 capability registry、locale、dashboard HTML 路径、普通检查、strict deferred 元数据和 git index。它通过以后，才可以说迁移输出“可用”。
 
+4. 基于验证通过的 session 创建迁移任务：
+
+```bash
+harness new-task \
+  --budget complex \
+  --preset legacy-migration \
+  --from-session /tmp/cah-migration-project/session.json \
+  /path/to/project
+```
+
+`legacy-migration` preset 任务是后续迁移工作的可审计交接点。它会记录 session、证据包、preset audit、write scope 和 migration follow-up queue；不会自动重写历史任务正文。
+
 如果后续继续清理 warning 或补活跃任务合同，第一次 session 只能作为 baseline。最终交付前要重新运行 `migrate-run` 生成新 session/dashboard，或者明确列出 baseline session 与最终检查证据的差异。
 
 `migrate-verify` 通过不等于 full migration complete。完整迁移还必须满足：