coding-agent-harness 1.0.4 → 1.0.6

package/LICENSE-EXCEPTION.md

@@ -0,0 +1,37 @@
+# Additional Permission for Generated Harness Materials
+
+Copyright (c) 2026 ZeyuLi (FairladyZ)
+
+Coding Agent Harness is licensed under the GNU Affero General Public License
+version 3 or any later version (`AGPL-3.0-or-later`). This file grants an
+additional permission under section 7 of the AGPL.
+
+## Generated Harness Materials
+
+For the purposes of this permission, "Generated Harness Materials" means files
+created, copied, rendered, scaffolded, or installed into a target project by
+Coding Agent Harness from bundled or user-provided templates, presets, skills,
+reference packs, examples, or documentation skeletons. This includes generated
+or installed project governance files such as `AGENTS.md`, `CLAUDE.md`, task
+plans, review files, ledgers, walkthroughs, generated dashboard data, and other
+target-project harness documents.
+
+## Permission
+
+You may use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+Generated Harness Materials under the license terms of the target project or
+under any other terms chosen by that target project's copyright holder.
+
+The AGPL does not apply to a target project, to that target project's source
+code, or to Generated Harness Materials solely because Coding Agent Harness was
+used to create, copy, render, scaffold, install, or update those materials.
+
+## Limits
+
+This additional permission does not apply to Coding Agent Harness itself,
+including its CLI/runtime source code, dashboard implementation, package source,
+or the bundled templates, presets, skills, reference packs, examples, and
+documentation as distributed in this repository or package.
+
+This permission does not grant trademark rights or remove any third-party
+license obligations that may apply independently.

package/README.md

@@ -67,6 +67,35 @@ Harness covers the continuity layer of real development: task lifecycle, Brief,
 
 It gives each agent step context, evidence, and a finish condition.
 
+### Reusable Presets For Task Families
+
+A preset is a versioned, declarative task method package. It does not install a
+new agent and it does not replace the Harness. It tells `harness new-task` how
+to create a task for a repeatable work type: what task kind to set, which inputs
+to ask for, which shared references or artifacts to copy into the task, which
+files the agent must read first, and what audit/evidence files should prove the
+task was created correctly.
+
+Use presets when a group of tasks share the same setup. For example, several
+interface tasks may all depend on the same upstream microservice contract,
+fixture packet, runbook, and verification checklist. Instead of repeating that
+context in every prompt, put it in a preset and create each task with
+`harness new-task --preset <preset-id> ...`.
+
+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.
@@ -140,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:
@@ -157,6 +224,10 @@ Start the local dynamic Workbench:
 npx --yes coding-agent-harness dev .
 ```
 
+The Workbench includes a Presets view for checking, installing, seeding, and
+uninstalling project or user presets. Static dashboards show the same preset
+catalog as read-only evidence.
+
 Generate a static Dashboard that can be opened offline:
 
 ```bash
@@ -198,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 .
@@ -239,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.
@@ -250,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.
 ```
@@ -267,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.
 ```
@@ -281,6 +365,8 @@ When done, summarize what changed, list verification results, call out any skipp
 - Legacy migration playbook: [`docs-release/guides/migration-playbook.en-US.md`](docs-release/guides/migration-playbook.en-US.md)
 - Full legacy migration strategy: [`docs-release/guides/full-legacy-migration-subagent-strategy.md`](docs-release/guides/full-legacy-migration-subagent-strategy.md)
 - Architecture overview: [`docs-release/architecture/overview.md`](docs-release/architecture/overview.md)
+- Deep architecture explainer (zh-CN): [`docs-release/architecture/system-explainer/`](docs-release/architecture/system-explainer/) — system design, module dependencies, task lifecycle, check system, data flow, and preset/migration engine with design rationale
+- Deep architecture explainer (en-US): [`docs-release/architecture/system-explainer/en-US/`](docs-release/architecture/system-explainer/en-US/)
 
 ## Star History
 
@@ -288,4 +374,10 @@ When done, summarize what changed, list verification results, call out any skipp
 
 ## License
 
-MIT
+AGPL-3.0-or-later with an additional permission for Generated Harness
+Materials.
+
+See [`LICENSE`](LICENSE) and [`LICENSE-EXCEPTION.md`](LICENSE-EXCEPTION.md).
+The additional permission keeps files generated or installed into a target
+project from becoming AGPL-covered solely because Coding Agent Harness created
+or updated them.

package/README.zh-CN.md

@@ -67,6 +67,25 @@ Harness 覆盖长程开发里的持续性问题：任务生命周期、Brief、E
 
 它让 Agent 每一步都有上下文、证据和收口标准。
 
+### 面向任务族的可复用 Preset
+
+Preset 是一个可版本化、声明式的任务方法包。它不是安装一个新 Agent，也不是替代
+Harness；它告诉 `harness new-task` 如何为某一类可重复工作创建任务：应该设置什么
+Task Kind、需要询问哪些输入、要把哪些共享 Reference 或 Artifact 复制进任务、Agent
+必须先读哪些文件，以及要生成哪些 audit / evidence 文件来证明任务创建正确。
+
+当一组任务共享同一套启动上下文时，就适合用 Preset。比如多个接口任务都依赖同一个
+上游微服务 contract、fixture packet、runbook 和验证清单，就不应该每次都把这些内容塞进
+prompt；应该把它们放进 Preset，然后用
+`harness new-task --preset <preset-id> ...` 创建每个任务。
+
+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 和检查结果证明迁移状态。
@@ -142,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：
@@ -197,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 .
@@ -238,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 证据重写当前或重新打开的任务。
@@ -249,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 只作为只读证据快照。
 ```
@@ -266,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。
 ```
@@ -280,6 +345,8 @@ npx --yes coding-agent-harness migrate-plan --json --limit 1000 .
 - 旧项目迁移指南：[`docs-release/guides/migration-playbook.md`](docs-release/guides/migration-playbook.md)
 - 完整旧项目迁移策略：[`docs-release/guides/full-legacy-migration-subagent-strategy.zh-CN.md`](docs-release/guides/full-legacy-migration-subagent-strategy.zh-CN.md)
 - 架构说明：[`docs-release/architecture/overview.md`](docs-release/architecture/overview.md)
+- 深度架构解析（中文）：[`docs-release/architecture/system-explainer/`](docs-release/architecture/system-explainer/) — 系统设计、模块依赖、任务生命周期、检查体系、数据流、Preset 与迁移引擎，含设计决策背景
+- Deep architecture explainer (en-US): [`docs-release/architecture/system-explainer/en-US/`](docs-release/architecture/system-explainer/en-US/)
 
 ## Star History
 
@@ -287,4 +354,8 @@ npx --yes coding-agent-harness migrate-plan --json --limit 1000 .
 
 ## License
 
-MIT
+AGPL-3.0-or-later，并附带 Generated Harness Materials 额外许可。
+
+详见 [`LICENSE`](LICENSE) 和 [`LICENSE-EXCEPTION.md`](LICENSE-EXCEPTION.md)。
+该额外许可确保 Harness 生成或安装到目标项目里的文件，不会仅仅因为由
+Coding Agent Harness 创建或更新，就自动变成 AGPL 覆盖范围。

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,33 +144,34 @@ 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 / 任务生命周期
 
 初始化或迁移完成后，活跃任务必须通过 CLI 创建和推进，避免 agent 手工复制模板造成漂移：
 
 ```bash
-harness new-task <task-id> --title "<title>" --locale zh-CN|en-US /path/to/project
-harness task-start <task-id> --message "<what started>" /path/to/project
-harness task-log <task-id> --message "<what changed>" --evidence "command:TARGET:path:summary" /path/to/project
-harness task-block <task-id> --message "<blocker>" /path/to/project
-harness task-review <task-id> --message "<ready for review>" /path/to/project
-harness review-confirm <task-id> --message "<human confirmation>" /path/to/project
-harness task-complete <task-id> --message "<closeout>" /path/to/project
-harness lesson-promote <task-id> <candidate-id> --dry-run /path/to/project
+harness new-task --title "<title>" --locale zh-CN|en-US /path/to/project
+harness task-start <task-id-from-new-task-output> --message "<what started>" /path/to/project
+harness task-log <task-id-from-new-task-output> --message "<what changed>" --evidence "command:TARGET:path:summary" /path/to/project
+harness task-block <task-id-from-new-task-output> --message "<blocker>" /path/to/project
+harness task-review <task-id-from-new-task-output> --message "<ready for review>" /path/to/project
+harness review-confirm <task-id-from-new-task-output> --confirm <task-id-from-new-task-output> --message "<human confirmation>" /path/to/project
+harness task-complete <task-id-from-new-task-output> --message "<closeout>" /path/to/project
+harness lesson-promote <task-id-from-new-task-output> <candidate-id> --dry-run /path/to/project
 harness task-list --json /path/to/project
 ```
 
 - `new-task --budget simple` 创建轻量任务目录：`brief.md`、`task_plan.md`、`visual_map.md`、`progress.md`。
 - `new-task` 默认 `standard`，创建完整任务目录，包括 `brief.md`、计划、策略、路线图、进度、发现和审查文件。
 - `new-task --budget complex` 在完整任务文件之外创建 optional references/artifacts 索引。
+- `new-task --title "<title>"` 默认生成 `YYYY-MM-DD-<title-slug>-<8hex>` 任务 ID，降低多人和多 agent 同仓创建任务时的重名概率；只有 coordinator 需要固定兼容 ID 时才传显式 `<task-id>`。
 - 已存在任务不会被覆盖；旧项目迁移时先 `task-list --json`，再决定复用旧任务还是开新任务。
 - 状态推进只写 `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。
@@ -192,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。
@@ -236,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 已输出给用户
@@ -285,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
@@ -315,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 索引
@@ -338,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` | 交付组织模型选择 |