coding-agent-harness 1.0.2 → 1.0.4

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

@@ -29,6 +29,19 @@ English mirror: `docs-release/guides/agent-installation.en-US.md`
 `npx --yes coding-agent-harness status` / `migrate-plan` 完成扫描；等用户确认允许写入后
 再安装 Skill 或运行初始化/迁移写入命令。
 
+本仓库还发布嵌套的 `preset-creator` Skill，给需要制作可复用 Harness Preset 的 Agent
+使用。因为本仓库同时有根目录 `SKILL.md` 和嵌套 Skill，查看或安装它时要加
+`--full-depth`：
+
+```bash
+npx skills add FairladyZ625/coding-agent-harness --list --full-depth
+npx skills add FairladyZ625/coding-agent-harness --skill preset-creator --full-depth
+```
+
+`coding-agent-harness` 用于在目标项目中运行 Harness；`preset-creator` 只在 Agent
+需要为一类可重复任务设计 Preset 时使用，例如这些任务共享 Reference、Artifact、Evidence
+或 Complex Task 骨架叠加规则。
+
 使用 v1.0 六阶段流程：
 
 1. Diagnose：扫描项目结构、语言、现有文档、CI、协作方式、外部依赖和风险面。
@@ -124,6 +137,16 @@ harness install-user --agent codex --global
 harness doctor-user --agent codex
 ```
 
+`npm install -g coding-agent-harness`、`harness install-user` 和 `harness init`
+都会 seed 内置 Preset：
+
+- 用户级 Preset：`~/.coding-agent-harness/presets/<preset-id>/`
+- 项目级 Preset：`<target>/.coding-agent-harness/presets/<preset-id>/`
+
+Agent 初始化或接手任务前必须运行 `harness preset list --json [target]`，
+确认可用 Preset 后再选择 `--preset`。如需修复缺失的内置 Preset，运行
+`harness preset seed` 或 `harness preset seed --project <target>`。
+
 支持的 agent target：
 
 | Agent | 用户级目录 |
@@ -140,7 +163,7 @@ harness doctor-user --agent codex
 - 默认交互确认；非交互场景必须传 `--yes` 或先用 `--dry-run`。
 - 默认不覆盖已有文件，只补缺失文件。
 - 需要强制更新时显式传 `--force`。
-- `doctor-user` 会检查 `SKILL.md`、模板、references、CLI scripts 和本指南是否存在。
+- `doctor-user` 会检查 `SKILL.md`、模板、references、内置 Preset、CLI scripts、本指南，以及用户级 Preset seed 是否存在。
 
 ## 旧 Harness 迁移
 
@@ -156,11 +179,6 @@ 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
 ```
 
 规则：
@@ -172,8 +190,8 @@ harness new-task \
 - 已有项目事实只能 merge、append 或记录 residual；不能用泛化模板替换。
 - 历史合同缺口在普通模式下进入 `adoption-needed` warning。
 - `--strict` 必须仍然能因为旧 checker 失败或历史合同缺口而失败。
+- 旧全局表和模块索引先归档，再用 `harness governance rebuild --archive --apply` 重新生成；这些表是 Agent 索引，人看状态优先用 Dashboard。
 - `migrate-verify` 必须通过，才能报告迁移输出可用；dashboard 路径必须是 HTML。
-- `new-task --preset legacy-migration --from-session` 只创建 Complex Task 骨架和证据包；不会继续迁移、改写历史、stage 或 commit。
 - 详细迁移策略见 `docs-release/guides/migration-playbook.md` 或英文镜像
   `docs-release/guides/migration-playbook.en-US.md`。如果用户要求证明旧项目已经完整迁移，
   还必须读取 `docs-release/guides/full-legacy-migration-subagent-strategy.md` 或中文镜像
@@ -212,13 +230,20 @@ harness task-complete phase-2-lifecycle \
 
 规则：
 
-- `new-task` 创建 `brief.md`、`task_plan.md`、`execution_strategy.md`、
-  `visual_map.md`、`findings.md`、`progress.md` 和 `review.md`。
+- 不要手工复制任务模板，也不要创建不完整任务目录。`harness check` 会按
+  `new-task` 创建的预算文件集校验。
+- `new-task --budget simple` 创建 `brief.md`、`task_plan.md`、`visual_map.md`
+  和 `progress.md`。
+- `new-task` 默认 `standard`，创建 simple 文件，并额外创建
+  `execution_strategy.md`、`findings.md`、`lesson_candidates.md` 和 `review.md`。
+- `new-task --budget complex` 创建 standard 文件，并额外创建
+  `references/INDEX.md` 和 `artifacts/INDEX.md`。
 - 已存在的任务目录不会被覆盖；需要改名或继续旧任务时，由 coordinator 决定。
 - `task-start`、`task-block`、`task-complete` 只更新 `progress.md` 的生命周期状态和日志。
 - `task-log` 只追加执行记录；证据使用 `type:PATH:summary`，例如
   `command:TARGET:npm-test:passed`。
 - `review-confirm` 会向 `review.md` 追加人工审查确认，并向 `progress.md` 追加日志；如果存在 `Open: yes` 或 `Blocks Release: yes` 的开放 P0/P1/P2 finding，必须拒绝确认。
+- CLI-owned lifecycle 和 lesson 命令会在干净 Git root 中自动提交 allowlisted 写入；dirty 状态会出现在 `status` / dashboard 的警告里，并阻塞这些机械化提交。Agent 手工改动仍要主动提交，不能提交时记录 no-commit reason、owner 和下一步。
 - `status --json` 保留旧 `task.state` 用于兼容，并新增 `lifecycleState`、`reviewStatus`、`closeoutStatus` 和 `stateConflicts`。`done` 只表示实现完成，不等于 `closed`。
 - 人工操作入口使用本地 HTML workbench：`harness dev /path/to/project`。它会启动只绑定 `127.0.0.1` 的动态页面、自动选择端口、打开浏览器并随 docs 变更刷新。无 GUI 或 CI 场景使用 `harness dev --no-open /path/to/project`。
 - 底层兼容入口仍是 `harness dashboard --workbench --out-dir /tmp/harness-workbench /path/to/project`。静态 dashboard 文件仍然只读，不能承载人工确认动作。

package/docs-release/guides/contributing.md

@@ -0,0 +1,100 @@
+# Contributor Guide
+
+This guide is for external contributors working on the public Coding Agent Harness repository.
+
+## Working Model
+
+Coding Agent Harness is more than documentation. The public repository includes:
+
+- CLI implementation under `scripts/`
+- tests under `tests/`
+- installable templates under `templates/` and `templates-zh-CN/`
+- bundled presets under `presets/`
+- public documentation under `docs-release/`
+- examples under `examples/`
+- an optional GUI submodule under `harness-gui/`
+
+Keep pull requests focused on one change family when possible. Documentation, CLI behavior, target-project templates, presets, and GUI work have different verification paths.
+
+## Local Setup
+
+Use Node.js 18 or newer. CI runs Node.js 20.
+
+```bash
+npm install
+```
+
+If your change touches the GUI submodule:
+
+```bash
+cd harness-gui
+npm ci
+```
+
+## Required Checks
+
+Run the checks that match your change. For larger PRs or when you are unsure, run
+the full root suite.
+
+| Change type | Minimum local checks |
+| --- | --- |
+| Docs only | `git diff --check` |
+| CLI/runtime | `npm test`, `npm run check`, `git diff --check` |
+| Templates or examples | `npm test`, `node scripts/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` |
+
+Full root suite:
+
+```bash
+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
+```
+
+GUI submodule setup and checks:
+
+```bash
+cd harness-gui
+npm ci
+npm run typecheck
+npm test
+npm run build
+```
+
+If a check cannot be run locally, say why in the PR.
+
+## PR Requirements
+
+Use the repository PR template and fill in:
+
+- summary
+- what changed
+- version impact
+- verification evidence
+- review evidence
+- residual risk
+- related issue, task, or design reference when available
+
+For docs-only or CI-only changes, "no version change" is usually correct. Runtime, template, preset, or package-surface changes may need a version decision from a maintainer.
+
+## GUI Submodule Changes
+
+`harness-gui/` is a Git submodule. GUI changes should be committed in the GUI repository first, then the parent repository should update the submodule pointer. A parent PR that updates the pointer should link to the GUI PR and include the GUI verification output.
+
+## CI
+
+GitHub Actions runs the same broad gates contributors should run locally:
+
+- root package tests
+- source/package boundary check
+- minimal target project check
+- dashboard generation and smoke test
+- npm package dry run
+- GUI submodule typecheck, tests, and build
+
+Repository owners manage branch protection and required checks in GitHub. Contributors only need to keep their PRs focused, documented, and verified.

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

@@ -0,0 +1,99 @@
+# 贡献者指南
+
+这份指南面向参与公开 `coding-agent-harness` 仓库的外部贡献者。
+
+## 工作模型
+
+Coding Agent Harness 不只是文档仓库。公开仓库包含：
+
+- `scripts/` 下的 CLI 实现
+- `tests/` 下的测试
+- `templates/` 与 `templates-zh-CN/` 下的可安装模板
+- `presets/` 下的内置 preset
+- `docs-release/` 下的公开文档
+- `examples/` 下的示例项目
+- `harness-gui/` 下的可选 GUI 子模块
+
+PR 尽量聚焦在一类改动上。文档、CLI 行为、目标项目模板、preset 和 GUI 有不同的验证路径。
+
+## 本地准备
+
+使用 Node.js 18 或更高版本。CI 当前使用 Node.js 20。
+
+```bash
+npm install
+```
+
+如果改动涉及 GUI 子模块：
+
+```bash
+cd harness-gui
+npm ci
+```
+
+## 必要检查
+
+根据改动范围运行相关检查。较大的 PR 或不确定范围时，运行完整根仓检查。
+
+| 改动类型 | 最小本地检查 |
+| --- | --- |
+| 仅文档 | `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` |
+| 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` |
+
+完整根仓检查：
+
+```bash
+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
+```
+
+GUI 子模块安装和检查：
+
+```bash
+cd harness-gui
+npm ci
+npm run typecheck
+npm test
+npm run build
+```
+
+如果某个检查无法在本地运行，请在 PR 中说明原因。
+
+## PR 要求
+
+使用仓库 PR 模板，并填写：
+
+- 摘要
+- 改动内容
+- 版本影响
+- 验证证据
+- 审查证据
+- 残余风险
+- 如有相关 issue、任务或设计材料，附上链接
+
+文档或 CI-only 改动通常可以写“不改版本”。运行时、模板、preset 或 package surface 改动可能需要维护者决定版本策略。
+
+## GUI 子模块改动
+
+`harness-gui/` 是 Git submodule。GUI 改动应先提交到 GUI 仓库，再由父仓更新 submodule pointer。更新 pointer 的父仓 PR 应链接 GUI PR，并附上 GUI 验证结果。
+
+## CI
+
+GitHub Actions 会运行贡献者本地也应覆盖的主要 gate：
+
+- 根包测试
+- source/package boundary 检查
+- minimal target project 检查
+- dashboard 生成与 smoke test
+- npm package dry run
+- GUI 子模块 typecheck、测试和 build
+
+GitHub branch protection 和 required checks 由仓库 owner 在 GitHub 上管理。贡献者只需要让 PR 聚焦、说明清楚并附上验证证据。

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

@@ -27,7 +27,7 @@ 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/` | Agents and project owners | Feature SSoT, task plans, current state | Generic marketing material |
+| 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 |
 
@@ -62,7 +62,8 @@ Agent-facing docs answer:
 Typical files:
 
 - `AGENTS.md`
-- `docs/09-PLANNING/Feature-SSoT.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`

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

@@ -27,7 +27,7 @@ Agent 读的文档定义事实、路径、门禁和下一步动作。
 | `references/` | Agent 和维护者 | 可复用标准，例如 testing、workflow、review、worktree | 某个项目的当前排期 |
 | `templates/` | CLI 和 Agent | 初始化目标项目时生成的文件 | 已经执行过的任务证据 |
 | 目标项目 `AGENTS.md` | Agent | 入口、路由、硬规则、读文件矩阵 | 大段背景叙事 |
-| 目标项目 `docs/09-PLANNING/` | Agent 和项目负责人 | Feature SSoT、任务计划、当前状态 | 通用营销材料 |
+| 目标项目 `docs/09-PLANNING/` 与 `docs/Harness-Ledger.md` | Agent 和项目负责人 | 任务计划、生成的任务生命周期索引、当前状态 | 通用营销材料 |
 | 目标项目 `docs/05-TEST-QA/` | Agent、QA、人审 | Regression SSoT、Cadence Ledger、质量门禁 | 需求讨论草稿 |
 | 目标项目 `docs/10-WALKTHROUGH/` | 人审、接手 Agent | 收口证据、残留项、人工确认 | 未验证的计划 |
 
@@ -62,7 +62,8 @@ Agent 读文档要回答：
 典型文件：
 
 - `AGENTS.md`
-- `docs/09-PLANNING/Feature-SSoT.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`

package/docs-release/guides/full-legacy-migration-subagent-strategy.md

@@ -120,7 +120,7 @@ Use small, bounded worker roles. These roles can run sequentially or in parallel
 | --- | --- | --- |
 | Task Contract Worker | `docs/09-PLANNING/TASKS/**/brief.md`, `execution_strategy.md`, `visual_map.md`, optional same-task `progress.md` log | Remove task contract failures; in a confirmed rewrite mode, rewrite weak old surfaces. |
 | Review/Capability Worker | `.harness-capabilities.json`, current strict review files | Declare real capabilities and normalize release-blocking review schema. |
-| Legacy Governance Worker | `AGENTS.md`, PR template or residual, `docs/11-REFERENCE/**`, Ledger, Closeout SSoT, Lessons SSoT, walkthrough template | Clear legacy checker failures. |
+| Legacy Governance Worker | `AGENTS.md`, PR template or residual, `docs/11-REFERENCE/**`, Ledger, Closeout SSoT, lesson candidates/detail docs, walkthrough template | Clear legacy checker failures. |
 | Brief Coverage Workers | disjoint task-date or module ranges, missing or explicitly weak `brief.md` files | Reach dashboard brief coverage 100 percent and remove empty templates. |
 | Quality Repair Worker | only files named by reviewer | Remove weak brief patterns and stale dashboard assumptions. |
 
@@ -235,7 +235,7 @@ Fix or route:
 - PR template exists or an explicit blocked-with-owner residual exists.
 - `Harness-Ledger.md` includes repo governance / CI-CD and Lessons Check columns.
 - `Closeout-SSoT.md` includes walkthrough, Lessons Check, and closeout status.
-- `Lessons-SSoT.md` includes ID, status, and detail doc columns.
+- Promoted lessons live in `docs/01-GOVERNANCE/lessons/*.md`; task-local candidates stay in `lesson_candidates.md`.
 - `_walkthrough-template.md` includes Lessons Reflection.
 
 Do not overwrite business facts. Merge missing columns or append a migration section when possible.

package/docs-release/guides/full-legacy-migration-subagent-strategy.zh-CN.md

@@ -120,7 +120,7 @@ harness migrate-verify /tmp/cah-migration-baseline/session.json
 | --- | --- | --- |
 | Task Contract Worker | `docs/09-PLANNING/TASKS/**/brief.md`、`execution_strategy.md`、`visual_map.md`、同任务 `progress.md` 可选追加 | 清掉 task contract failures；在已确认 rewrite 模式下重写薄弱旧表面。 |
 | Review/Capability Worker | `.harness-capabilities.json`、当前 strict review 文件 | 声明真实能力并规范 release-blocking review schema。 |
-| Legacy Governance Worker | `AGENTS.md`、PR template 或 residual、`docs/11-REFERENCE/**`、Ledger、Closeout SSoT、Lessons SSoT、walkthrough template | 清掉 legacy checker failures。 |
+| Legacy Governance Worker | `AGENTS.md`、PR template 或 residual、`docs/11-REFERENCE/**`、Ledger、Closeout SSoT、lesson candidates/detail docs、walkthrough template | 清掉 legacy checker failures。 |
 | Brief Coverage Workers | 按 task 日期段或模块拆分，写缺失或被点名薄弱的 `brief.md` | 达到 dashboard brief coverage 100%，并移除空模板。 |
 | Quality Repair Worker | 只写 reviewer 点名的文件 | 移除弱 brief、自动解析痕迹和 stale dashboard assumptions。 |
 
@@ -235,7 +235,7 @@ Task/review cleanup 后，strict cutover 仍可能因为旧 checker 要求 gover
 - PR template 存在，或有 explicit blocked-with-owner residual。
 - `Harness-Ledger.md` 包含 repo governance / CI-CD 和 Lessons Check 列。
 - `Closeout-SSoT.md` 包含 walkthrough、Lessons Check 和 closeout status。
-- `Lessons-SSoT.md` 包含 ID、status 和 detail doc 列。
+- Promoted lessons 位于 `docs/01-GOVERNANCE/lessons/*.md`；任务本地候选保留在 `lesson_candidates.md`。
 - `_walkthrough-template.md` 包含 Lessons Reflection。
 
 不要覆盖业务事实。尽量 merge 缺失列，或追加 migration section。

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

@@ -122,17 +122,6 @@ The command writes:
 - `status-strict.json`
 - `dashboard/index.html`
 
-After `migrate-verify` passes, create the migration task as a Complex Task preset:
-
-```bash
-harness new-task \
-  --budget complex \
-  --preset legacy-migration \
-  --from-session /tmp/cah-migration-project/session.json
-```
-
-This command only scaffolds the task and copies/references evidence. It does not run migration, rewrite history, stage files, or commit.
-
 Classify the output:
 
 | Output | Meaning | Action |

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

@@ -123,17 +123,6 @@ harness migrate-run \
 - `status-strict.json`
 - `dashboard/index.html`
 
-`migrate-verify` 通过后，把本次迁移变成 Complex Task preset：
-
-```bash
-harness new-task \
-  --budget complex \
-  --preset legacy-migration \
-  --from-session /tmp/cah-migration-project/session.json
-```
-
-这条命令只创建任务骨架并复制/引用证据，不会继续运行迁移、改写历史、stage 或 commit。
-
 输出分类：
 
 | Output | 含义 | 动作 |

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

@@ -94,17 +94,6 @@ harness migrate-verify /tmp/cah-migration-project/session.json
 
 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.
 
-4. Create the Complex Task preset from the session:
-
-```bash
-harness new-task \
-  --budget complex \
-  --preset legacy-migration \
-  --from-session /tmp/cah-migration-project/session.json
-```
-
-This only creates the task scaffold and `evidence/<timestamp>/` bundle. It does not run more migration, rewrite historical tasks, stage files, or commit. The generated task records `Task Kind`, `Task Preset`, `Preset Version`, `Migration Target Level`, `Migration Achieved Level`, and `Evidence Bundle`; later agents should continue migration inside that Complex Task instead of inventing a second workflow.
-
 `migrate-verify` passing does not mean the full migration is complete. Full migration also requires:
 
 - `migrate-plan` is `declared-capability`.
@@ -115,7 +104,7 @@ This only creates the task scaffold and `evidence/<timestamp>/` bundle. It does
 - The task index opens and shows all tasks.
 - At least one adversarial subagent review round passes.
 
-5. Continue cleanup from the plan:
+4. Continue cleanup from the plan:
 
 - `MP-01`: confirm compatibility layer and locale; verify historical docs were not overwritten.
 - `MP-02`: choose capabilities; only declare capabilities that project facts support.
@@ -124,14 +113,14 @@ This only creates the task scaffold and `evidence/<timestamp>/` bundle. It does
 - `MP-05`: upgrade current release/architecture/security/data reviews; do not rewrite every historical review.
 - `MP-06`: only use strict as a gate after normal warnings have owner/action/status.
 
-6. Normal migration verification:
+5. Normal migration verification:
 
 ```bash
 harness check --profile target-project /path/to/project
 harness dashboard --out-dir /tmp/harness-dashboard /path/to/project
 ```
 
-7. Strict cutover verification:
+6. Strict cutover verification:
 
 ```bash
 harness check --profile target-project --strict /path/to/project
@@ -171,6 +160,16 @@ In baseline mode, only `current-active` tasks or tasks still referenced by SSoT
 
 In status-aware rewrite mode, an existing `brief.md`, `execution_strategy.md`, or `visual_map.md` is not automatically preserved. If evidence shows it is an old template, parser residue, wrong language, or too weak for a human to judge current state, rewrite it. Historical tasks may become readable index cards or residuals, but that decision must be evidence-backed.
 
+Global table and module index migration is not manual refilling. Current Harness versions generate task lifecycle summaries into `Harness-Ledger.md` only; legacy `Feature-SSoT.md` and `Private-Feature-SSoT.md` files are archived during cutover and are not regenerated. Module `module_plan.md` Steps tables and module `visual_map.md` topology tables are still generated from module task files. Humans should inspect current state through the Dashboard; agents can use `task-list` / `task-index` queries for fast lookup. Before cutting over an older project, archive the legacy lifecycle tables and rebuild current indexes from task files:
+
+```bash
+harness governance rebuild --dry-run --archive /path/to/project
+harness governance rebuild --archive --apply /path/to/project
+harness task-list --json --search "keyword" /path/to/project
+```
+
+The archive directory preserves old lifecycle table snapshots. After the Dashboard, `task-list` / `task-index`, and generated Ledger all reflect current tasks, the project owner may decide whether to delete the old archive. Migration agents should not delete historical table evidence directly. Delivery, Regression, Cadence, Closeout, and Module Registry governance tables are not deleted by this step unless a later version provides equivalent scanner and generator support.
+
 In full semantic rewrite mode, every task needs a standalone `brief.md`, but the brief must not be an empty template. A historical task brief is a readable index card: task goal, first human read, evidence sources, status judgment, and residuals. `visual_map.md` is a diagram collection, not a roadmap template; include phase flow, sequence, architecture, data-flow, state, topology, or decision maps only when they improve understanding. Do not generate empty diagrams to satisfy a checker.
 
 If the legacy project is a microservice, multi-repo, split frontend/backend, or externally integrated project, the migration plan must also ask the user whether external source material exists. Do not migrate dozens of external-team documents directly into `03/04/06`. First use `external-source-intake-standard.md` to create `docs/04-DEVELOPMENT/external-source-packs/<source-key>/`, complete the source index and digests, then project stable facts into service profiles, external contexts, and integration contracts.
@@ -282,7 +281,7 @@ Full migration should not let one agent edit everything from start to finish. Us
 | --- | --- | --- |
 | Task Contract Worker | `docs/09-PLANNING/TASKS/**/brief.md`, `execution_strategy.md`, `visual_map.md`, same-task `progress.md` append | Clear task contract gaps; in a confirmed rewrite mode, rewrite weak old surfaces. |
 | Review/Capability Worker | `.harness-capabilities.json`, current strict review files | Declare real capabilities and repair release-blocking review schema. |
-| Legacy Governance Worker | `AGENTS.md`, PR template, `docs/11-REFERENCE/**`, Ledger, Closeout SSoT, Lessons SSoT, walkthrough template | Clear legacy checker aggregate failures. |
+| Legacy Governance Worker | `AGENTS.md`, PR template, `docs/11-REFERENCE/**`, Ledger, Closeout SSoT, lesson candidates/detail docs, walkthrough template | Clear legacy checker aggregate failures. |
 | Brief Coverage Workers | date or module slices, missing or explicitly weak `brief.md` files | Bring dashboard brief coverage to 100 percent and remove empty templates. |
 | Quality Repair Worker | only files named by reviewers | Remove parser residue, empty templates, language mismatch, and weak evidence. |
 

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

@@ -98,17 +98,6 @@ harness migrate-verify /tmp/cah-migration-project/session.json
 
 如果后续继续清理 warning 或补活跃任务合同，第一次 session 只能作为 baseline。最终交付前要重新运行 `migrate-run` 生成新 session/dashboard，或者明确列出 baseline session 与最终检查证据的差异。
 
-4. 用 session 创建 Complex Task preset：
-
-```bash
-harness new-task \
-  --budget complex \
-  --preset legacy-migration \
-  --from-session /tmp/cah-migration-project/session.json
-```
-
-这一步只创建任务骨架和 `evidence/<timestamp>/` 证据包，不会继续运行迁移、改写历史任务、stage 或 commit。生成的任务会写入 `Task Kind`、`Task Preset`、`Preset Version`、`Migration Target Level`、`Migration Achieved Level` 和 `Evidence Bundle`，后续 agent 应在这个 Complex Task 里推进迁移，而不是另起一套流程。
-
 `migrate-verify` 通过不等于 full migration complete。完整迁移还必须满足：
 
 - `migrate-plan` 是 `declared-capability`。
@@ -119,7 +108,7 @@ harness new-task \
 - 任务索引页面能打开并显示全量任务。
 - 至少一轮 subagent 对抗审查 PASS。
 
-5. 按计划继续人工/agent 清理：
+4. 按计划继续人工/agent 清理：
 
 - `MP-01`：确认兼容层和 locale，保证历史文档没有被覆盖。
 - `MP-02`：选择 capability，只声明项目事实已经支持的能力。
@@ -128,14 +117,14 @@ harness new-task \
 - `MP-05`：升级当前 release/architecture/security/data review，不重写所有历史 review。
 - `MP-06`：普通检查 warning 都有 owner/action/status 后，再使用 strict 作为门禁。
 
-6. 普通迁移验证：
+5. 普通迁移验证：
 
 ```bash
 harness check --profile target-project /path/to/project
 harness dashboard --out-dir /tmp/harness-dashboard /path/to/project
 ```
 
-7. 严格切换验证：
+6. 严格切换验证：
 
 ```bash
 harness check --profile target-project --strict /path/to/project
@@ -175,6 +164,16 @@ Baseline 模式下，只有 `current-active` 或 “仍被 SSoT 引用为当前
 
 Status-aware rewrite 模式下，已有 `brief.md`、`execution_strategy.md`、`visual_map.md` 不是自动保留；如果证据显示它们只是旧模板、解析残留、语言错误或不能让人判断当前状态，就重写。历史任务可以只写可读索引卡或 residual，但这个判断必须有证据。
 
+全局表和模块索引迁移不是人工重填。新版本只把任务生命周期汇总生成到 `Harness-Ledger.md`；旧的 `Feature-SSoT.md` 和 `Private-Feature-SSoT.md` 是 legacy 生命周期投影，切换时应先归档，不再重建。模块 `module_plan.md` 的 Steps 表和模块 `visual_map.md` 的拓扑表仍由模块任务文件生成。人看当前状态应优先看 Dashboard，Agent 需要快速定位时用 `task-list` / `task-index` 查询。旧项目切换前，先把旧生命周期表归档，再用生成器从任务文件重建当前索引：
+
+```bash
+harness governance rebuild --dry-run --archive /path/to/project
+harness governance rebuild --archive --apply /path/to/project
+harness task-list --json --search "keyword" /path/to/project
+```
+
+归档目录会保留旧生命周期表快照。确认 Dashboard、`task-list` / `task-index` 查询和新生成 Ledger 都能反映当前任务后，再由项目 owner 决定是否删除旧归档；迁移 agent 不应直接删除历史表证据。Delivery、Regression、Cadence、Closeout、Module Registry 等非任务生命周期治理表不是本步骤的删除对象，除非后续版本提供等价 scanner 和生成器。
+
 Full semantic rewrite 模式下，所有任务都需要 standalone `brief.md`，但不能写空模板。历史任务的 brief 应该是“可读索引卡”：说明任务目标、第一眼应该看什么、证据来自哪里、状态判断和 residual。`visual_map.md` 是图表集合，不是路线图模板；只画能提高理解速度的 phase flow、sequence、architecture、data-flow、state、topology 或 decision map，不能为了过检查生成空图。
 
 如果旧项目属于微服务、多仓、前后端分仓或依赖外部系统，迁移计划还必须询问用户是否有外部资料。不要把外部团队给的几十份文档直接迁入 `03/04/06`。先按 `external-source-intake-standard.md` 建立 `docs/04-DEVELOPMENT/external-source-packs/<source-key>/`，完成 source index 和 digest，再把稳定事实投影到 service profile、external context 和 integration contract。
@@ -286,7 +285,7 @@ Full cutover 的 dashboard smoke 必须验证：
 | --- | --- | --- |
 | Task Contract Worker | `docs/09-PLANNING/TASKS/**/brief.md`、`execution_strategy.md`、`visual_map.md`、同任务 `progress.md` 追加 | 清掉 task contract 缺口；在已确认 rewrite 模式下重写薄弱旧表面。 |
 | Review/Capability Worker | `.harness-capabilities.json`、当前 strict review 文件 | 声明真实 capability，修 release-blocking review schema。 |
-| Legacy Governance Worker | `AGENTS.md`、PR template、`docs/11-REFERENCE/**`、Ledger、Closeout SSoT、Lessons SSoT、walkthrough template | 清掉 legacy checker 聚合错误。 |
+| Legacy Governance Worker | `AGENTS.md`、PR template、`docs/11-REFERENCE/**`、Ledger、Closeout SSoT、lesson candidates/detail docs、walkthrough template | 清掉 legacy checker 聚合错误。 |
 | Brief Coverage Workers | 按日期段或模块划分，写缺失或被点名薄弱的 `brief.md` | 把 dashboard brief coverage 变成 100%，并移除空模板。 |
 | Quality Repair Worker | 只写 reviewer 点名的问题文件 | 修掉自动解析痕迹、空模板、语言不一致和证据薄弱。 |
 

package/docs-release/guides/parent-control-repository-pattern.en-US.md

@@ -16,7 +16,7 @@ Multi-repo projects often run into these failures:
 
 - Frontend, backend, SDK, and services each have their own plans, and no one can tell where the global release is blocked.
 - An agent starts inside a child repository, reads only local `AGENTS.md`, and misses cross-repo architecture constraints.
-- Each repository maintains its own Feature SSoT, and the states conflict.
+- Each repository maintains its own handwritten task lifecycle table, and the states conflict.
 - Review evidence, test evidence, and walkthroughs are scattered across repositories, making it hard to prove that a cross-repo task is complete.
 
 The parent-control pattern solves a control-plane problem. It does not force code back into a monorepo. It moves the harness source of truth into one place.
@@ -62,7 +62,8 @@ It should contain:
 - `docs/03-ARCHITECTURE/repository-topology.md`: repository topology, owners, boundaries, dependency direction.
 - `docs/04-DEVELOPMENT/local-development.md`: cross-repo local startup, integration workflow, dependency setup.
 - `docs/06-INTEGRATIONS/`: cross-service APIs, events, SDKs, databases, permissions, and external contracts.
-- `docs/09-PLANNING/Feature-SSoT.md`: global feature and release state.
+- `docs/Harness-Ledger.md`: generated global task lifecycle index from task files.
+- `docs/09-PLANNING/Delivery-SSoT.md`: cross-repo feature blocks, dependencies, and release orchestration.
 - `docs/09-PLANNING/TASKS/`: cross-repo task contracts.
 - `docs/05-TEST-QA/Regression-SSoT.md`: cross-repo regression gates.
 - `docs/05-TEST-QA/Cadence-Ledger.md`: which changes trigger which checks.
@@ -94,7 +95,7 @@ They should contain:
 - Repository-local reviews or pull requests.
 - Repository-local test evidence.
 
-Child repositories should not independently maintain the global Feature SSoT, and they should not decide whether a cross-repo release is complete.
+Child repositories should not independently maintain global task lifecycle tables, and they should not decide whether a cross-repo release is complete.
 
 A child repository `AGENTS.md` can be short:
 
@@ -228,7 +229,7 @@ The agent does not need to read all docs in 100 repositories at startup. It read
 
 Avoid:
 
-- Each child repository maintaining its own global Feature SSoT.
+- Each child repository maintaining its own global task lifecycle table.
 - A parent repository with only a README and no task, regression, or closeout surface.
 - Child `AGENTS.md` files copying large sections from the parent, causing drift.
 - Starting cross-repo tasks from a child repository and backfilling parent records at the end.
@@ -241,7 +242,8 @@ To adopt the parent-control model, start with:
 
 - Parent `AGENTS.md` states that this is the control repository.
 - `docs/03-ARCHITECTURE/repository-topology.md` lists all child repositories.
-- `docs/09-PLANNING/Feature-SSoT.md` is the global feature source of truth.
+- `docs/Harness-Ledger.md` is generated from task files as the global task lifecycle index.
+- `docs/09-PLANNING/Delivery-SSoT.md` is maintained only when cross-repo release or block orchestration is needed.
 - `docs/05-TEST-QA/Regression-SSoT.md` defines local, contract, integration, and release gates.
 - Each child repository has only a short local `AGENTS.md`.
 - New cross-repo tasks are created only in the parent repository.

package/docs-release/guides/parent-control-repository-pattern.md

@@ -16,7 +16,7 @@ English mirror: `docs-release/guides/parent-control-repository-pattern.en-US.md`
 
 - 前端、后端、SDK、微服务各有自己的计划，没人知道全局 release 到底卡在哪里。
 - Agent 从某个子仓库启动，只看到局部 `AGENTS.md`，忽略了跨仓架构约束。
-- 每个仓库各自维护 Feature SSoT，状态互相冲突。
+- 每个仓库各自维护手写任务生命周期表，状态互相冲突。
 - Review 证据、测试证据、walkthrough 分散在不同仓库，最后无法证明一个跨仓任务真正完成。
 
 主控仓库模式解决的是控制面问题。它不是要求把代码放回单仓，而是把 Harness 的事实源收回一个地方。
@@ -62,7 +62,8 @@ product-control-repo/
 - `docs/03-ARCHITECTURE/repository-topology.md`：仓库拓扑、owner、边界、依赖方向。
 - `docs/04-DEVELOPMENT/local-development.md`：跨仓本地启动、联调、依赖安装。
 - `docs/06-INTEGRATIONS/`：跨服务 API、事件、SDK、数据库、权限、外部系统契约。
-- `docs/09-PLANNING/Feature-SSoT.md`：全局 feature 和 release 状态。
+- `docs/Harness-Ledger.md`：由任务文件生成的全局任务生命周期索引。
+- `docs/09-PLANNING/Delivery-SSoT.md`：跨仓 feature block、依赖和 release 编排。
 - `docs/09-PLANNING/TASKS/`：跨仓任务合同。
 - `docs/05-TEST-QA/Regression-SSoT.md`：跨仓 regression gates。
 - `docs/05-TEST-QA/Cadence-Ledger.md`：哪些变更触发哪些检查。
@@ -94,7 +95,7 @@ node tools/check-harness.mjs
 - 本仓库局部 review 或 PR。
 - 本仓库局部测试证据。
 
-子仓库不应该单独维护全局 Feature SSoT，也不应该自己决定跨仓 release 是否完成。
+子仓库不应该单独维护全局任务生命周期表，也不应该自己决定跨仓 release 是否完成。
 
 一个子仓库 `AGENTS.md` 可以很短：
 
@@ -228,7 +229,7 @@ Agent 不需要在启动时读 100 个仓库的所有文档。它先读父任务
 
 避免这些做法：
 
-- 每个子仓库各自维护全局 Feature SSoT。
+- 每个子仓库各自维护全局任务生命周期表。
 - 父仓库只有 README，没有任务、回归和 closeout。
 - 子仓库 `AGENTS.md` 复制父仓库大段内容，导致漂移。
 - 跨仓任务从子仓库启动，最后再补父仓库记录。
@@ -241,7 +242,8 @@ Agent 不需要在启动时读 100 个仓库的所有文档。它先读父任务
 
 - 父仓库 `AGENTS.md` 写清楚它是 control repo。
 - `docs/03-ARCHITECTURE/repository-topology.md` 列出所有子仓库。
-- `docs/09-PLANNING/Feature-SSoT.md` 成为全局 feature source of truth。
+- `docs/Harness-Ledger.md` 由任务文件生成全局任务生命周期索引。
+- `docs/09-PLANNING/Delivery-SSoT.md` 只在需要跨仓 release / block 编排时维护。
 - `docs/05-TEST-QA/Regression-SSoT.md` 定义局部、契约、集成、发布 gate。
 - 每个子仓库只有短的局部 `AGENTS.md`。
 - 新跨仓任务只在父仓库创建。