coding-agent-harness 1.0.4 → 1.0.5

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,26 @@ 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/`.
+The `preset-creator` Skill is for authoring these preset packages; the Harness
+CLI is what checks, installs, lists, and applies 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.
@@ -157,6 +177,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
@@ -281,6 +305,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 +314,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,22 @@ 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。
+
 ### 旧项目也能迁移
 
 旧项目迁移不是直接套模板。标准流程是：先扫描项目，生成迁移计划，推荐迁移模式，向用户提问确认，再执行迁移，最后用 Dashboard 和检查结果证明迁移状态。
@@ -280,6 +296,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 +305,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

@@ -152,20 +152,21 @@ Project、Verify、Residual。`external-source-packs/` 只保存资料索引、
 初始化或迁移完成后，活跃任务必须通过 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`。

package/docs-release/architecture/overview.md

@@ -225,7 +225,7 @@ confirmation. Tasks with missing packets, incomplete evidence, lesson-routing
 work, blocking findings, or historical closeout debt are routed to separate
 lifecycle queues: Missing Materials, Blocked, Lessons, Confirmed / Finalized,
 and Soft-deleted / Superseded. Agent-authored submissions can request review,
-but only a strict `Human Review Confirmation` block marks the task as
+but only committed Task Audit Metadata in `INDEX.md` marks the task as
 `confirmed`.
 
 ## Migration Rails

package/docs-release/architecture/overview.zh-CN.md

@@ -202,7 +202,7 @@ flowchart TB
 
 standard 和 complex 任务必须具备进度、证据、lesson 决议、人工确认和收口链接，才会被视为真正关闭。
 
-Review 队列只展示已经提交审查材料包、并且可以等待人工确认的任务。缺少审查提交、证据不完整、仍有 Lesson 路由、存在阻塞发现，或历史收口债务的任务，会进入独立的生命周期队列：Missing Materials、Blocked、Lessons、Confirmed / Finalized、Soft-deleted / Superseded。Agent 写入的提交只能请求审查；只有严格的 `Human Review Confirmation` 块存在时，任务才是 `confirmed`。
+Review 队列只展示已经提交审查材料包、并且可以等待人工确认的任务。缺少审查提交、证据不完整、仍有 Lesson 路由、存在阻塞发现，或历史收口债务的任务，会进入独立的生命周期队列：Missing Materials、Blocked、Lessons、Confirmed / Finalized、Soft-deleted / Superseded。Agent 写入的提交只能请求审查；只有 `INDEX.md` 中已提交的 Task Audit Metadata 才能把任务标记为 `confirmed`。
 
 ## 迁移轨道
 

package/docs-release/architecture/system-explainer/01-system-overview.md

@@ -0,0 +1,217 @@
+# 01 — 系统全景
+
+## 这是什么，解决什么问题
+
+在 AI 编程工具（Codex、Claude Code、Gemini CLI）普及之前，
+"任务管理"对开发者来说意味着 Jira ticket 或 GitHub issue——
+这些工具是为人类设计的，Agent 读不懂，也无法从中派生出可验证的状态。
+
+**Coding Agent Harness** 解决的核心问题是：
+
+> 当 Agent 在你的代码仓库里工作时，如何确保它的工作有迹可查、有门可守、有人可审？
+
+它不是 Agent 本身，也不是给人用的任务管理工具。
+它是一个**仓库原生的 Agent 操作层**（repository-native operating layer）——
+给 Agent 提供可执行的结构化上下文，让 Agent 能从文件中恢复执行，
+而不依赖之前的聊天记忆。
+
+核心设计理念只有一句话：
+
+> **把重要状态保存在 Agent 能读的 Markdown 文件里，然后用 CLI 从这些文件派生出
+> 状态、检查、迁移计划和 Dashboard 视图。**
+
+---
+
+## 为什么叫 "Harness"
+
+"Harness"在工程语境中是"约束装置"的意思——用来约束、引导、测量一个系统的行为，
+而不是替代它。就像测试框架中的 "test harness" 不是测试本身，
+而是让测试可以被组织、执行和验证的基础设施。
+
+Coding Agent Harness 不是 Agent 的替代品，而是 Agent 的约束装置：
+- 任务有生命周期（创建 → 执行 → 审查 → 收口）
+- 审查有门禁（Agent 不能自己给自己打通关）
+- 状态有记录（每次变更都写入 Markdown，可 git blame）
+- 人类有检查入口（本地 Dashboard + Workbench 审查确认）
+
+---
+
+## 和 Jira / Linear / GitHub Issues 的本质区别
+
+| | Jira / Linear / GitHub Issues | Coding Agent Harness |
+| --- | --- | --- |
+| 设计给谁 | 人类协作 | Agent 执行 + 人类审查 |
+| 状态存在哪 | 外部 SaaS 数据库 | 仓库内的 Markdown 文件 |
+| Agent 能读吗 | 需要 API 集成 | 直接读文件 |
+| 能 git diff 吗 | 不能 | 可以 |
+| 能离线工作吗 | 不能 | 可以 |
+| 能从文件恢复执行吗 | 不能 | 可以 |
+
+---
+
+## Level 0 — 四个大块
+
+先看最高层。整个系统由四个大块组成：
+
+```mermaid
+flowchart LR
+  A["📦 Package\n发布的 npm 包\n（CLI + 模板 + 标准 + Preset）"]
+  B["📁 Target Repo\n用户的项目仓库\n（文档树 + 状态文件）"]
+  C["⚙️ Runtime\n运行时引擎\n（扫描 + 检查 + 生成）"]
+  D["👤 Human\n人类检查入口\n（Dashboard + 审查确认）"]
+
+  A -->|"scaffold + validate"| B
+  B -->|"读取"| C
+  C -->|"生成"| D
+  D -->|"review-confirm"| B
+```
+
+- **Package**：你 `npm install` 的那个东西，包含 CLI、模板、标准文档、Preset 包
+- **Target Repo**：你的项目，harness 在里面创建 `docs/` 文档树来记录任务状态
+- **Runtime**：CLI 运行时，扫描文档树、验证合规、生成 Dashboard
+- **Human**：浏览器里看 Dashboard，在 Workbench 里做审查确认
+
+注意这个循环的方向：**Package 写入 Target Repo，Runtime 读取 Target Repo，
+Human 通过 review-confirm 再写回 Target Repo**。
+整个系统是一个以 Markdown 文件为中心的读写循环，没有任何隐藏状态。
+
+---
+
+## Level 1 — 每个大块里有什么
+
+### Package 里有什么
+
+```mermaid
+flowchart TD
+  PKG["📦 Package\ncoding-agent-harness@npm"]
+
+  PKG --> CLI["harness CLI\nscripts/harness.mjs\n唯一命令入口"]
+  PKG --> Lib["核心库\nscripts/lib/\n~30 个模块，6 个功能层"]
+  PKG --> Templates["任务模板\ntemplates/\n任务骨架文件（task_plan / visual_map 等）"]
+  PKG --> References["操作标准\nreferences/\n可复制到目标仓库的规范文档"]
+  PKG --> Presets["Preset 包\npresets/\n可复用任务方法（legacy-migration / module 等）"]
+```
+
+Package 是**只读的**——它提供工具和模板，但不存储任何状态。
+状态全部在 Target Repo 里。
+
+### Target Repo 里有什么
+
+```mermaid
+flowchart TD
+  REPO["📁 Target Repo\n你的项目仓库"]
+
+  REPO --> Entry["AGENTS.md\nAgent 入口和路由\n（告诉 Agent 去哪里找上下文）"]
+  REPO --> Caps[".harness-capabilities.json\n启用了哪些能力模块"]
+  REPO --> Docs["docs/\n文档树（harness 的工作区）"]
+
+  Docs --> Planning["09-PLANNING/\n任务目录 + 模块目录"]
+  Docs --> Ledger["Harness-Ledger.md\n全局账本（所有任务汇总）"]
+  Docs --> Walkthrough["10-WALKTHROUGH/\n收口证据和 Closeout SSoT"]
+  Docs --> Reference["11-REFERENCE/\n本地操作标准（从 Package 复制过来）"]
+  Docs --> Governance["01-GOVERNANCE/\nLesson 沉淀库"]
+```
+
+每个任务对应 `docs/09-PLANNING/TASKS/<task-id>/` 下的一个目录，
+里面有 `task_plan.md`、`progress.md`、`visual_map.md`、`review.md` 等文件。
+
+### Runtime 做什么
+
+```mermaid
+flowchart TD
+  RT["⚙️ Runtime\nharness CLI 运行时"]
+
+  RT --> Scan["扫描\n读取所有任务文件\n解析状态 / 阶段 / 审查 / Lesson"]
+  RT --> Check["检查\n9 个验证器验证合规性\n输出 failures / warnings"]
+  RT --> Generate["生成\n输出 Dashboard HTML + JSON 索引\n输出治理索引表"]
+  RT --> Migrate["迁移\n分析旧项目差距\n生成迁移动作队列"]
+  RT --> Lifecycle["生命周期\n执行状态转换命令\n写入 Governance Sync"]
+```
+
+Runtime 是**无状态的**——每次运行都从 Markdown 文件重新读取，
+不缓存任何中间状态（除了 `harness dev` 的文件监听）。
+
+---
+
+## Level 2 — 核心概念词汇表
+
+| 概念 | 一句话解释 | 在哪里 |
+| --- | --- | --- |
+| **Task** | 一个有生命周期的工作单元 | `docs/09-PLANNING/TASKS/<id>/` |
+| **Budget** | 任务复杂度：`simple` / `standard` / `complex`，决定门禁严格程度 | `task_plan.md` |
+| **Phase** | Visual Map 中的执行阶段，有状态和完成度 | `visual_map.md` |
+| **Capability** | 可选功能模块，如 `dashboard`、`adversarial-review` | `.harness-capabilities.json` |
+| **Review Gate** | 阻止任务完成的审查门禁，必须人工确认才能通过 | `INDEX.md` + `review.md` |
+| **Governance Sync** | 任务状态变更时自动更新全局账本的原子操作 | `Harness-Ledger.md` |
+| **Preset** | 可复用的任务方法包，如 `legacy-migration`、`module` | `presets/<id>/` |
+| **Lesson** | 从任务中沉淀的可复用经验 | `docs/01-GOVERNANCE/lessons/` |
+| **Tombstone** | 软删除 / 合并 / 被取代的任务标记 | `task_plan.md` 中的特殊块 |
+| **lifecycleState** | 从任务状态 + 审查状态综合派生的队列分类 | 运行时派生，不存文件 |
+
+---
+
+## Level 2 — 设计决策
+
+### 为什么用 Markdown 而不是数据库
+
+这是最常被问到的问题。
+
+**选择 Markdown 的原因**：
+
+1. **Agent 可读**：所有主流 AI 编程工具都能读写 Markdown，不需要特殊 API
+2. **Git 原生**：状态变更可以 diff、可以 blame、可以回滚，审计链天然存在
+3. **人类可读**：不需要工具就能直接查看状态，降低工具依赖
+4. **离线工作**：不依赖外部服务，断网也能用
+5. **可移植**：换 Agent 工具不需要迁移数据
+6. **单一事实源**：避免 Markdown、JSON、SQLite 三份事实互相漂移
+
+**代价**：
+
+- 解析 Markdown 比查数据库慢（但对于任务管理规模，这不是瓶颈）
+- 格式约束需要靠检查器维护，而不是数据库 schema 强制
+- 并发写入需要文件锁（`governance-sync` 的锁机制）
+
+**被考虑但否决的方案**：
+- **SQLite**：Git diff 不友好，引入二进制文件，且当前规模（几百任务）不需要
+- **JSON**：适合机器解析但不适合 Agent 理解叙述性上下文
+- **YAML/TOML**：不适合承载 brief、执行策略这类长文本内容
+
+### 为什么是 npm 包而不是 SaaS
+
+Agent 需要在本地文件系统上读写状态。SaaS 会引入网络依赖、认证、延迟，
+破坏 Agent 的自主执行能力。npm 包让任何能运行 Node.js 的环境都能直接使用，
+无需账号或网络。`package.json` 的 `dependencies` 为空——零运行时依赖。
+
+### 为什么 review-confirm 必须是人工操作
+
+`review-confirm` 是整个系统里**唯一不能被 Agent 自动执行**的操作。
+
+原因：
+
+> Agent 不能给自己的工作打通关。
+
+这个边界不是一开始就有的。最初 Dashboard workbench 的 review action 没有 Agent/Human 区分。
+后来通过竞品分析（Taskr competitive intake）识别出"Agent 自动确认 review"是 P0 风险，
+才引入了 Git 提交门禁：`review-confirm` 会把带有 Git `user.name` / `user.email` 的
+人工确认审计字段写入任务 `INDEX.md`，并做两次 Git 原子提交——第一次提交确认字段，
+第二次提交包含第一个 commit SHA 的最终审计记录。这个 Git commit 是**可审计的人类签名**，
+证明有真实的人类看过这个任务。
+
+### 为什么派生状态不存储在文件里
+
+`lifecycleState`、`taskQueues`、`reviewQueueState` 这些派生状态每次运行时重新计算，
+不写回 Markdown 文件。原因有三：
+
+1. **避免事实漂移**：如果派生状态也写回文件，就有了两份事实源，任何一份过期都会造成误报
+2. **防止绕过门禁**：如果 Agent 能直接修改派生字段，就能绕过 review-confirm 的门禁
+3. **治理规则即代码**：scanner 的推导规则本身就是治理规则的机器可读表达，每次运行重新计算等于每次都重新执行一遍治理检查
+
+---
+
+## 下一步
+
+- 想理解代码怎么组织的 → [02-module-dependency.md](02-module-dependency.md)
+- 想理解一个任务从头到尾怎么走 → [03-task-lifecycle.md](03-task-lifecycle.md)
+- 想理解检查器在验什么 → [04-check-and-governance.md](04-check-and-governance.md)
+- 想理解 Dashboard 数据从哪来 → [05-data-flow.md](05-data-flow.md)
+- 想理解 Preset 和迁移怎么工作 → [06-preset-and-migration.md](06-preset-and-migration.md)

package/docs-release/architecture/system-explainer/02-module-dependency.md

@@ -0,0 +1,257 @@
+# 02 — 代码模块依赖关系
+
+## Level 0 — 入口在哪
+
+所有命令都从一个文件进来：
+
+```mermaid
+flowchart LR
+  User["用户 / Agent\n$ harness <command> [target]"] -->|"解析参数 + 分发"| Entry["scripts/harness.mjs\n唯一 CLI 入口"]
+```
+
+`harness.mjs` 做两件事：解析命令行参数，然后分发给对应的 command 模块或直接调用核心库。
+它本身不包含任何业务逻辑。
+
+---
+
+## Level 1 — 命令如何分发
+
+```mermaid
+flowchart TD
+  Entry["scripts/harness.mjs"]
+
+  Entry -->|"dashboard\ndev"| DashCmd["scripts/dashboard-command.mjs\nDashboard 生成 + 动态服务"]
+  Entry -->|"migrate-plan\nmigrate-run\nmigrate-verify"| MigCmd["scripts/migration-command.mjs\n迁移三阶段命令"]
+  Entry -->|"new-task / task-start\ntask-phase / task-review\ntask-complete / review-confirm\ntask-tombstone"| TaskCmd["scripts/task-command.mjs\n任务生命周期命令"]
+  Entry -->|"preset catalog\npreset install\npreset uninstall"| PresetCmd["scripts/preset-command.mjs\nPreset 管理命令"]
+  Entry -->|"check / status / init\ngovernance / lesson-promote\n..."| Core["lib/harness-core.mjs\n（直接调用）"]
+```
+
+四个 command 模块各自负责一个领域，其余命令直接调用 `harness-core.mjs`。
+
+**为什么这样分**：command 模块处理的是有复杂交互逻辑的命令（多步骤、需要读写多个文件、
+有用户提示），而简单的查询类命令（`check`、`status`）直接调用核心库更简洁。
+
+---
+
+## Level 2 — harness-core.mjs 是什么
+
+`harness-core.mjs` 是一个 **facade（门面）**，它自己不写任何业务逻辑，
+只是把 `lib/` 下所有模块的导出重新 re-export 出来。
+
+这样设计的好处：外部代码只需要 `import from "./lib/harness-core.mjs"` 就能拿到所有功能，
+不需要知道具体在哪个子模块里。
+
+```mermaid
+flowchart TD
+  Core["harness-core.mjs\n（纯 re-export facade）"]
+
+  Core --> G1["① 核心工具层\ncore-shared + markdown-utils"]
+  Core --> G2["② 任务扫描层\ntask-scanner + review-model + lesson-candidates"]
+  Core --> G3["③ 检查与治理层\ncheck-profiles + governance-sync + governance-index"]
+  Core --> G4["④ Dashboard 层\ndashboard-data + dashboard-writer + workbench"]
+  Core --> G5["⑤ 任务生命周期层\ntask-lifecycle + review-gates + review-confirm"]
+  Core --> G6["⑥ 迁移与 Preset 层\nmigration-planner + preset-registry + tombstone"]
+```
+
+下面逐层展开。
+
+---
+
+## Level 3 — 六个功能层详解
+
+### ① 核心工具层
+
+这两个模块是所有其他模块的基础，几乎每个模块都会 import 它们：
+
+```mermaid
+flowchart LR
+  CoreShared["core-shared.mjs\n路径解析 / 常量枚举\n文件读写 / locale 处理\n模板渲染"]
+  MarkdownUtils["markdown-utils.mjs\nMarkdown 表格提取\n行更新 / 列查找\n依赖列表拆分"]
+```
+
+`core-shared` 定义了所有允许的枚举值，是整个系统的"类型系统"：
+
+| 枚举 | 允许值 |
+| --- | --- |
+| `allowedTaskStates` | `not_started / planned / in_progress / review / blocked / done` |
+| `allowedTaskBudgets` | `simple / standard / complex` |
+| `allowedPhaseStates` | `planned / in_progress / review / blocked / done / skipped` |
+| `allowedCapabilities` | `core / module-parallel / subagent-worker / adversarial-review / ...` |
+
+`markdown-utils` 提供了对 Markdown 表格的结构化操作——这是整个系统能从 Markdown 文件
+派生状态的技术基础。
+
+---
+
+### ② 任务扫描层
+
+负责读取 `docs/09-PLANNING/TASKS/` 下的所有文件，解析出结构化数据：
+
+```mermaid
+flowchart TD
+  TaskScanner["task-scanner.mjs\n扫描所有任务目录\n解析状态 / 预算 / 阶段 / 元数据"]
+
+  TaskScanner --> ReviewModel["task-review-model.mjs\n审查确认解析\n生命周期队列派生\ntombstone 解析"]
+  TaskScanner --> LessonCandidates["task-lesson-candidates.mjs\nLesson candidate 状态解析\n决策完成判定"]
+
+  ReviewModel --> CoreShared
+  ReviewModel --> MarkdownUtils
+  TaskScanner --> CoreShared
+  TaskScanner --> MarkdownUtils
+```
+
+`task-review-model` 里有几个关键的**派生函数**——它们不读文件，
+只根据已解析的数据计算出新的状态：
+
+| 函数 | 输入 | 输出 |
+| --- | --- | --- |
+| `deriveLifecycleState()` | taskState + reviewStatus + tombstone | `lifecycleState`（队列分类） |
+| `deriveTaskQueues()` | lifecycleState + materials + lessons | `taskQueues[]`（属于哪些队列） |
+| `deriveReviewQueueState()` | findings + confirmation | `reviewQueueState` |
+| `parseTaskTombstone()` | task_plan.md 内容 | 软删除 / 合并 / 被取代状态 |
+
+这些派生函数是**纯函数**，相同输入永远得到相同输出，便于测试和调试。
+
+---
+
+### ③ 检查与治理层
+
+负责验证合规性，以及维护全局索引的原子写入：
+
+```mermaid
+flowchart TD
+  CheckProfiles["check-profiles.mjs\nbuildStatus() 编排 9 个验证器\n返回 failures + warnings + tasks"]
+
+  CheckProfiles --> V1["validateCapabilities\n能力注册表一致性"]
+  CheckProfiles --> V2["validateReviewSchema\nreview.md 结构"]
+  CheckProfiles --> V3["validateVisualMaps\nvisual_map 合规"]
+  CheckProfiles --> V4["validatePlanContracts\n任务合约标记"]
+  CheckProfiles --> V5["validateTaskPresetContracts\nPreset 合约"]
+  CheckProfiles --> V6["validateContextDocs\n上下文文档完整性"]
+  CheckProfiles --> V7["validateGovernanceTableBoundaries\n表格边界"]
+  CheckProfiles --> V8["validateSubagentAuthorization\nsubagent 授权"]
+  CheckProfiles --> V9["validateTaskCompletionConsistency\n完成一致性"]
+
+  CheckProfiles --> GitSummary["git-status-summary.mjs\nGit 状态摘要（dirty files 等）"]
+
+  GovSync["governance-sync.mjs\n原子锁 + 行级更新 + Git commit\n（任务状态变更时自动调用）"]
+  GovIndex["governance-index-generator.mjs\n重建全局索引表\n（手动触发）"]
+  GovIndex --> GovSync
+```
+
+**重要区分**：`governance-sync` 和 `check-profiles` 没有依赖关系。
+- `check-profiles`：只读，验证状态，不写文件
+- `governance-sync`：只写，更新账本，不做验证
+
+---
+
+### ④ Dashboard 层
+
+负责把扫描结果转换成 HTML Dashboard：
+
+```mermaid
+flowchart TD
+  DashData["dashboard-data.mjs\nbuildDashboardBundle()\n收集 status + documents + tables + graph + adoption"]
+
+  DashData --> CheckProfiles["check-profiles.mjs\n（调用 buildStatus）"]
+  DashData --> DashWriter["dashboard-writer.mjs\n写入 HTML + JSON 文件\n（静态快照模式）"]
+  DashData --> StatusRenderer["status-dashboard-renderer.mjs\n渲染状态摘要文本"]
+
+  DashWorkbench["dashboard-workbench.mjs\nDev 动态服务\nHTTP server + 文件监听 + 自动刷新\n（harness dev 命令）"]
+```
+
+`DashWorkbench` 和 `DashData` / `DashWriter` 是**独立的**：
+- `DashData` + `DashWriter`：生成静态快照（只读）
+- `DashWorkbench`：启动本地 HTTP 服务，支持 Workbench 写操作
+
+---
+
+### ⑤ 任务生命周期层
+
+负责执行所有任务状态转换命令：
+
+```mermaid
+flowchart TD
+  TaskLifecycle["task-lifecycle.mjs\n生命周期命令实现\nnew-task / task-start / task-phase\ntask-review / task-complete"]
+
+  TaskLifecycle --> ReviewGates["task-lifecycle/review-gates.mjs\n门禁验证逻辑\n（进入 review 前的检查）"]
+  TaskLifecycle --> ReviewConfirm["task-lifecycle/review-confirm.mjs\n人工确认执行\n（review-confirm 命令）"]
+  TaskLifecycle --> TextUtils["task-lifecycle/text-utils.mjs\n文本追加工具\n（向 Markdown 文件追加内容）"]
+  TaskLifecycle --> GovSync["governance-sync.mjs\n状态变更时同步账本"]
+  TaskLifecycle --> MigPreset["task-migration-preset.mjs\n迁移 preset 上下文注入"]
+
+  ReviewConfirm --> GitGate["review-confirm-git-gate.mjs\nGit 原子提交门禁\n（写入人工确认块 + commit）"]
+```
+
+`review-confirm` 是整个生命周期层里最特殊的命令——它是唯一需要 Git 原子提交的操作，
+也是唯一不能被 Agent 自动执行的操作（见 [01-system-overview.md](01-system-overview.md) 的设计决策）。
+
+---
+
+### ⑥ 迁移与 Preset 层
+
+```mermaid
+flowchart TD
+  PresetReg["preset-registry.mjs\n读取 presets/ YAML\n验证包完整性\n分层发现（project / user / bundled）"]
+  PresetEngine["preset-engine.mjs\n执行 preset entrypoints\n（template / script / check 类型）"]
+  PresetAudit["preset-audit-contracts.mjs\n验证 preset 合约完整性"]
+  PresetResource["preset-resource-contracts.mjs\n验证 preset 资源声明"]
+
+  MigPlanner["migration-planner.mjs\n分析目标仓库差距\n生成迁移动作队列"]
+  MigSupport["migration-support.mjs\nsession 管理 / locale 探测\nGit 状态检查 / full-cutover 验证"]
+  Tombstone["task-tombstone-commands.mjs\n软删除 / 合并 / 重开命令"]
+
+  LessonSed["task-lesson-sedimentation.mjs\nLesson 沉淀任务创建"]
+  LessonMaint["lesson-maintenance.mjs\nLesson 库维护"]
+  TaskIndex["task-index.mjs\n任务索引生成"]
+
+  MigPlanner --> MigSupport
+  PresetEngine --> PresetReg
+```
+
+---
+
+## 一张完整的依赖总图（参考用）
+
+如果你已经理解了上面的分层，这张图可以作为查阅索引：
+
+```mermaid
+flowchart TD
+  Entry["harness.mjs"] --> DashCmd & MigCmd & TaskCmd & PresetCmd & Core["harness-core.mjs"]
+
+  Core --> CoreShared & MarkdownUtils
+  Core --> TaskScanner --> ReviewModel & LessonCandidates
+  Core --> CheckProfiles --> GitSummary
+  Core --> GovSync
+  Core --> GovIndex --> GovSync
+  Core --> DashData --> DashWriter & StatusRenderer
+  Core --> DashWorkbench
+  Core --> TaskLifecycle --> ReviewGates & ReviewConfirm & TextUtils & GovSync & MigPreset
+  ReviewConfirm --> GitGate
+  Core --> PresetReg
+  Core --> PresetEngine --> PresetReg
+  Core --> MigPlanner --> MigSupport
+  Core --> Tombstone
+  Core --> LessonSed
+  Core --> LessonMaint
+  Core --> TaskIndex
+```
+
+---
+
+## Level 2 — 模块命名规律
+
+理解命名规律可以帮你快速定位代码：
+
+| 前缀 / 后缀 | 含义 | 例子 |
+| --- | --- | --- |
+| `task-` | 与任务相关 | `task-scanner`, `task-lifecycle`, `task-review-model` |
+| `dashboard-` | 与 Dashboard 相关 | `dashboard-data`, `dashboard-writer`, `dashboard-workbench` |
+| `governance-` | 与治理 / 账本相关 | `governance-sync`, `governance-index-generator` |
+| `migration-` | 与迁移相关 | `migration-planner`, `migration-support` |
+| `preset-` | 与 Preset 相关 | `preset-registry`, `preset-engine`, `preset-audit-contracts` |
+| `check-` | 验证器 | `check-profiles`, `check-module-parallel` |
+| `-command.mjs` | CLI 命令模块 | `task-command`, `dashboard-command` |
+| `-utils.mjs` | 工具函数 | `markdown-utils`, `text-utils` |
+| `-gates.mjs` | 门禁逻辑 | `review-gates`, `review-confirm-git-gate` |