coding-agent-harness 1.0.4 → 1.0.5

package/docs-release/architecture/system-explainer/05-data-flow.md

@@ -0,0 +1,276 @@
+# 05 — 数据流：从 Markdown 到 Dashboard
+
+## Level 0 — 数据的起点和终点
+
+```mermaid
+flowchart LR
+  A["📄 Markdown 文件\n（docs/ 下的源文件）"]
+  B["⚙️ Scanner\n（解析 + 验证）"]
+  C["📊 Dashboard\n（HTML + JSON）"]
+
+  A -->|"读取"| B -->|"生成"| C
+```
+
+所有数据都来自 Markdown 文件，没有数据库，没有外部服务。
+每次运行都从文件系统重新读取，不缓存任何中间状态。
+
+---
+
+## Level 1 — 哪些文件是数据源
+
+```mermaid
+flowchart TD
+  Sources["数据源文件"]
+
+  Sources --> TP["task_plan.md\n预算 / 标题 / 元数据 / Preset 信息\nTask Contract 标记"]
+  Sources --> PR["progress.md\n当前状态 / 操作日志"]
+  Sources --> VM["visual_map.md\n阶段列表 / 完成度 / 证据状态"]
+  Sources --> RV["review.md\nfindings 表格 / 人工确认块"]
+  Sources --> BR["brief.md\n任务摘要"]
+  Sources --> LC["lesson_candidates.md\nLesson 候选 / 决策状态"]
+  Sources --> HL["Harness-Ledger.md\n全局账本（所有任务汇总行）"]
+  Sources --> ES["execution_strategy.md\nsubagent 授权状态"]
+```
+
+---
+
+## Level 2 — Scanner 如何处理这些文件
+
+Scanner 层（`task-scanner.mjs` + `task-review-model.mjs`）把原始 Markdown 解析成结构化对象。
+
+### collectTasks() 的发现流程
+
+```mermaid
+flowchart TD
+  CT["collectTasks()"]
+
+  CT --> Discover["listTaskPlanPaths()\n扫描两个根目录：\n09-PLANNING/TASKS/\n09-PLANNING/MODULES/\n过滤模板和归档目录"]
+
+  Discover --> ReadFiles["对每个任务目录读取 9 个文件\ntask_plan / brief / progress\nreview / visual_map\nexecution_strategy\nlesson_candidates / findings / context"]
+
+  ReadFiles --> Parse["解析各文件"]
+
+  Parse --> P1["parseTaskBudget()\n从 task_plan.md 提取 budget"]
+  Parse --> P2["parseTaskState()\n从 progress.md 提取 state"]
+  Parse --> P3["parsePhases()\n从 visual_map.md 提取阶段列表"]
+  Parse --> P4["parseAgentReviewSubmission()\n从 review.md 提取 Agent 提交状态"]
+  Parse --> P5["parseReviewConfirmation()\n从 review.md 提取人工确认块"]
+  Parse --> P6["parseLessonCandidateStatus()\n从 lesson_candidates.md 提取决策状态"]
+  Parse --> P7["parseTaskTombstone()\n从 task_plan.md 提取软删除状态"]
+
+  P1 & P2 & P3 & P4 & P5 & P6 & P7 --> Derive["派生计算（纯函数）"]
+
+  Derive --> LS["deriveLifecycleState()\n综合推导 lifecycleState"]
+  Derive --> QS["deriveTaskQueues()\n决定任务属于哪些队列"]
+  Derive --> RQS["deriveReviewQueueState()\n推导 reviewQueueState"]
+```
+
+### parseTaskState() 的格式
+
+从 `progress.md` 的 `## Current Status` 或 `## Status` 标题后的第一行提取状态：
+
+```markdown
+## Current Status
+
+in_progress
+```
+
+支持中文别名（`进行中` → `in_progress`）。如果格式不符合预期，会降级到遗留表格解析模式。
+
+### parsePhases() 的表格格式
+
+从 `visual_map.md` 中查找 `Phase ID` 列标题的表格，提取 9 个字段：
+
+```markdown
+| Phase ID | Depends On | State | Completion | Output | Required Evidence | Evidence Status | Blocking Risk | Owner / Handoff |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| P1 | — | done | 100 | ... | E-001 | present | low | coordinator |
+```
+
+依赖字段支持逗号、分号、`&` 分隔的多值。
+
+---
+
+## Level 2 — buildStatus() 把 Scanner 结果组装成什么
+
+```mermaid
+flowchart TD
+  BS["buildStatus()"]
+
+  BS --> Tasks["tasks[]\n每个任务的完整结构化数据\n（见下方字段列表）"]
+  BS --> Failures["failures[]\n硬失败列表"]
+  BS --> Warnings["warnings[]\n软警告列表"]
+  BS --> Caps["capabilities[]\n能力注册表状态"]
+  BS --> Git["git\nGit 状态摘要（dirty files 等）"]
+  BS --> Summary["summary\nbriefCoverage / visualMapCoverage\nfullCutoverEligible 等汇总指标"]
+```
+
+**task 对象的完整字段**：
+
+| 字段 | 含义 |
+| --- | --- |
+| `path` | 相对路径 |
+| `title` | 任务标题 |
+| `state` | 任务状态（`in_progress / done / ...`） |
+| `stateSource` | 状态来源（`valid / invalid`） |
+| `budget` | 预算等级（`simple / standard / complex`） |
+| `lifecycleState` | 派生的生命周期状态 |
+| `reviewQueueState` | 审查队列状态 |
+| `taskQueues[]` | 所属队列列表 |
+| `phases[]` | 阶段列表（含 id / state / completion / evidenceStatus） |
+| `closeoutStatus` | 收口状态 |
+| `tombstone` | 软删除信息 |
+| `briefSource` | brief 来源（`standalone / missing / ...`） |
+| `visualMapSource` | visual map 来源（`canonical / legacy / missing`） |
+| `taskPreset` | 使用的 Preset ID |
+| `presetVersion` | Preset 版本 |
+| `handoffs` | 交接信息数组 |
+| `lessonCandidateDecisionComplete` | Lesson 决策是否完成 |
+
+---
+
+## Level 3 — buildDashboardBundle() 在 status 基础上再加什么
+
+`buildDashboardBundle()` 调用 `buildStatus()` 后，再额外收集四类数据：
+
+```mermaid
+flowchart TD
+  Bundle["buildDashboardBundle()"]
+
+  Bundle --> Status["status\n（来自 buildStatus）"]
+  Bundle --> Documents["documents[]\n所有 Markdown 文档的内容\n每个文档：id / path / title / type / content"]
+  Bundle --> Tables["tables[]\n从文档中提取的 Markdown 表格\n每个表格：列定义 + 行数据"]
+  Bundle --> Graph["graph\n任务依赖关系图\nnodes（任务/阶段/模块/步骤）\nedges（依赖/包含/交接关系）"]
+  Bundle --> Adoption["adoption\n迁移采纳状态分析\n（warnings 分类汇总，含优先级和修复建议）"]
+```
+
+### documents 收集范围
+
+`collectMarkdownDocuments()` 收集哪些文件：
+
+```mermaid
+flowchart TD
+  Collect["collectMarkdownDocuments()"]
+
+  Collect --> Fixed["固定路径（存在时收集）\nHarness-Ledger.md\n09-PLANNING/Module-Registry.md\n05-TEST-QA/Regression-SSoT.md\n10-WALKTHROUGH/Closeout-SSoT.md"]
+
+  Collect --> Walkthrough["10-WALKTHROUGH/ 下所有 .md\n（排除 _archive/ 和 _ 开头文件）"]
+
+  Collect --> TaskDocs["每个任务目录下：\nbrief / task_plan / execution_strategy\nvisual_map / lesson_candidates\nprogress / review / findings\nreferences/INDEX.md / artifacts/INDEX.md"]
+
+  Collect --> ModuleDocs["09-PLANNING/MODULES/ 下：\n每个模块的 module_plan.md\n每个模块的 brief.md"]
+
+  Collect --> Lessons["01-GOVERNANCE/lessons/ 下所有 .md"]
+```
+
+收集后统一过滤掉 `_archive/`、`_task-template/`、`_optional-structures/` 路径。
+
+### graph 数据结构
+
+图包含两类元素：
+
+- **nodes**：任务节点、阶段节点、模块节点、步骤节点
+- **edges**：依赖关系（阶段 → 阶段）、包含关系（任务 → 阶段）、交接关系（步骤 → 步骤）
+
+如果依赖的源节点不存在，会创建一个 `external-dependency` 类型的虚拟节点。
+
+---
+
+## Level 2 — 两种 Dashboard 生成模式
+
+```mermaid
+flowchart LR
+  subgraph "静态模式（只读快照）"
+    SC["harness dashboard\n--out-dir ./out"]
+    SC --> SH["index.html\n（内联所有资源）"]
+    SC --> SJ["dashboard-data.json\n（供外部工具读取）"]
+    SC --> SF["status.json / tables.json\ndocuments.json / graph.json\nadoption.json"]
+  end
+
+  subgraph "动态模式（Workbench）"
+    DC["harness dev"]
+    DC --> HTTP["本地 HTTP 服务\nlocalhost:PORT"]
+    DC --> Watch["文件监听\n轮询模式，每 1 秒检查一次\n变化后延迟 250ms 重新生成"]
+    HTTP --> Browser["浏览器实时查看\n支持 review-confirm 等写操作"]
+  end
+```
+
+**关键边界**：静态 Dashboard 是只读的，不能触发任何写操作。
+只有 `harness dev`（Workbench 模式）才能执行 `review-confirm`、`task-start` 等写操作。
+
+### Dashboard HTML 生成方式
+
+Dashboard HTML 通过字符串拼接生成（非模板引擎）。
+`app.js` 通过 manifest 或直接读取获得——如果存在 manifest，
+按顺序读取并拼接多个源文件（`app-src/` 目录下的模块化源码）。
+
+payload 中的 `<` 被转义为 `<` 防止 HTML 注入。
+
+### 文件监听实现
+
+`dashboard-workbench.mjs` 的文件监听采用**轮询模式**（`startPollingWatch()`）：
+- 每 1000ms 检查一次目录树的最新修改时间（mtime）
+- 检测到变化时，延迟 250ms 后触发重新生成（防抖）
+- 监听范围：整个 `target.docsRoot`，排除 `.git`、`node_modules`、`tmp`
+
+---
+
+## Level 3 — markdown-utils.mjs 的核心能力
+
+整个系统能从 Markdown 文件派生状态，技术基础是 `markdown-utils.mjs` 提供的表格解析能力：
+
+| 函数 | 用途 |
+| --- | --- |
+| `markdownTableRows()` | 提取所有表格行 |
+| `parseAllMarkdownTables()` | 解析文档中所有表格，返回结构化对象数组 |
+| `splitMarkdownRow()` | 分割行单元格（处理转义管道符和代码块） |
+| `tableAfterHeading()` | 定位特定标题后的表格 |
+| `getCell()` | 按列名获取单元格（支持多个别名） |
+| `splitList()` | 分割逗号/分号/加号分隔的列表 |
+| `splitDependencies()` | 分割依赖，过滤 `none/n/a` 等占位符 |
+
+**代码块内的管道符**：`splitMarkdownRow()` 会跟踪代码块状态，
+代码块内的 `|` 不会被当作列分隔符，保留原始内容。
+
+---
+
+## Level 2 — 设计决策
+
+### 为什么 Dashboard 是纯 HTML + vanilla JS，不用 React/Vite
+
+harness 通过 `npx` 分发，引入 React/Vite 意味着用户每次运行都要拉取大量构建依赖，
+破坏零依赖的可移植性。静态 HTML 可以直接从 `file://` 打开，
+也可以作为 CI 证据快照分享，不需要任何运行时。
+
+app-src 里的 vanilla JS 组件（`DashboardShell`、`SidebarNav`、`TableView` 等）
+通过 manifest 按顺序拼接，每个文件 < 600 行，git diff 可读，不需要 webpack/esbuild。
+
+### 为什么静态 Dashboard 是只读的
+
+静态 Dashboard 的定位是"可分享的证据快照"——它可以被 CI 生成、离线打开、
+发给外部审查者。这些场景下写操作没有安全边界（没有 CSRF/Origin/Host 校验）。
+写操作只能在 Workbench 模式下执行，因为 Workbench server 绑定 `127.0.0.1`
+并有完整的安全校验链。
+
+### 为什么 `harness dev` 和 `harness dashboard` 是两个命令
+
+`harness dashboard` 生成静态只读快照（适合 CI、迁移报告、离线证据）。
+`harness dev` 启动本地动态 Workbench server，支持文件 watch、自动刷新、
+review-confirm 写操作。两者的边界是：**静态快照可以分享，动态 Workbench 只能本地用**。
+
+### 为什么文件监听用轮询而不是 fs.watch
+
+`fs.watch` 在 macOS 上对深层目录树有已知的漏报问题，
+而 harness 的 docs 目录结构是多层嵌套的 Markdown 文件树。
+轮询方案实现简单、行为可预期、不引入 chokidar 等第三方依赖（与零依赖原则一致）。
+1 秒轮询 + 250ms debounce 对人类编辑场景足够。
+
+### 为什么不引入 SQLite 或 JSON 数据库
+
+引入 JSON/SQLite 若没有清楚的 authority 边界，会形成 Markdown、JSON、SQLite 三份事实互相漂移。
+Git review 对 Markdown/JSON 友好，对 SQLite diff 不友好。
+当前规模是"几百任务"，generated JSON + indexed in-memory filtering 足够。
+
+决策是：Markdown 是唯一事实源，generated JSON index 是可再生缓存，
+SQLite 只在任务数量和查询复杂度超过 JSON 能承载时才考虑引入，
+且只能作为可再生查询缓存，不能手写、不能作为权威事实源。

package/docs-release/architecture/system-explainer/06-preset-and-migration.md

@@ -0,0 +1,303 @@
+# 06 — Preset 系统与迁移引擎
+
+## Level 0 — 两个独立子系统
+
+本文档覆盖两个相关但独立的子系统：
+
+```mermaid
+flowchart LR
+  A["Preset 系统\n可复用的任务方法包\n（new-task 时注入）"]
+  B["迁移引擎\n旧项目接入 harness\n（migrate-* 命令）"]
+
+  A -->|"legacy-migration preset\n是迁移引擎的专用 Preset"| B
+```
+
+它们的关系：迁移引擎有一个专用 Preset（`legacy-migration`），但 Preset 系统本身是通用的，
+任何类型的任务都可以有自己的 Preset。
+
+---
+
+## Part 1 — Preset 系统
+
+### Level 1 — Preset 是什么
+
+Preset 是一个**可复用的任务方法包**，打包了特定类型任务所需的：
+- 模板追加内容（在标准模板基础上追加 preset 专属内容）
+- 执行脚本（plan / scaffold 阶段运行）
+- 检查脚本（验证 preset 合规）
+- 资源声明（参考文件、工件、必需阅读）
+
+```mermaid
+flowchart TD
+  Preset["Preset 包\npresets/<id>/"]
+
+  Preset --> Manifest["preset.yaml\n包清单（必须）"]
+  Preset --> Templates["templates/\n模板追加文件"]
+  Preset --> Scripts["scripts/\nplan / scaffold 脚本"]
+  Preset --> Checks["checks/\n检查脚本"]
+  Preset --> Workbench["workbench/\nDashboard 面板定义（可选）"]
+```
+
+### Level 1 — 分层发现：三个搜索层
+
+Preset 按 **project → user → builtin** 的顺序搜索，同名 Preset 采用**首匹配优先**策略：
+
+```mermaid
+flowchart LR
+  P["project 层\n<target>/.coding-agent-harness/presets/\n（优先级最高）"]
+  U["user 层\n~/.coding-agent-harness/presets/\n（次优先）"]
+  B["builtin 层\npackage/presets/\n（最低优先级）"]
+
+  P -->|"未找到时继续"| U -->|"未找到时继续"| B
+```
+
+这个设计允许：
+- **项目级覆盖**：在项目里放一个同名 Preset，覆盖 builtin 版本
+- **用户级覆盖**：在 home 目录放 Preset，对所有项目生效
+- **builtin 兜底**：package 自带的 Preset 作为默认实现
+
+`harness preset install --project <preset-id>` 把 Preset 安装到项目层；
+`harness preset uninstall --project <preset-id>` 从项目层移除（不影响 user 和 builtin 层）。
+
+### Level 2 — preset.yaml 的结构
+
+```mermaid
+flowchart TD
+  YAML["preset.yaml"]
+
+  YAML --> Meta["基本信息\nid / version / purpose\ncompatibleBudgets / localeSupport"]
+  YAML --> Task["task 配置\nkind / requiresFromSession\nprojectLevelOnly"]
+  YAML --> EP["entrypoints\n（见下）"]
+  YAML --> WS["writeScopes\n限定写入路径（安全边界）"]
+  YAML --> Resources["resources\nreferences / artifacts / context.requiredReads"]
+  YAML --> Audit["audit\nmanifestRequired: true\nevidenceFiles[]"]
+```
+
+### Level 3 — Entrypoint 类型系统
+
+每个 entrypoint 有两个维度：**name**（触发时机）和 **type**（执行方式）：
+
+```mermaid
+flowchart LR
+  subgraph "Name（触发时机）"
+    N1["newTask\nharness new-task --preset X 时"]
+    N2["plan\n迁移计划阶段"]
+    N3["scaffold\n批量补全阶段"]
+    N4["check\n验证阶段"]
+  end
+
+  subgraph "Type（执行方式）"
+    T1["template\n追加模板内容到任务文件"]
+    T2["script\n运行 Node.js 脚本"]
+    T3["check\n运行检查脚本"]
+  end
+```
+
+三种执行方式的区别：
+- **template**：渲染模板文件，将结果追加到任务文件（`task_plan.md`、`execution_strategy.md` 等）
+- **script**：执行 Node.js 脚本，脚本可读写文件系统，返回结果作为 audit 证据
+- **check**：执行检查脚本，验证 preset 应用的完整性，失败时阻止任务创建
+
+每个 entrypoint 还声明 `writes`（允许写入的路径 glob）和 `reads`（允许读取的路径 glob）。
+
+### Level 3 — writeScopes 安全边界
+
+`writeScopes` 是一个路径白名单，限制 Preset 只能写入声明的目录。
+`assertPresetWriteScope()` 在每次文件写入时检查相对路径是否匹配任何 scope。
+
+```
+writeScopes:
+  tasks:
+    path: docs/09-PLANNING/TASKS/**
+    access: write
+```
+
+支持 `path/**` 通配符表示目录及其所有子目录。
+相对路径必须规范化（无 `../`、无绝对路径），防止目录遍历攻击。
+
+### Level 2 — Preset 的生命周期
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant CLI as harness CLI
+  participant Registry as preset-registry.mjs
+  participant Engine as preset-engine.mjs
+  participant TaskDir as 任务目录
+
+  User->>CLI: harness new-task my-task --preset legacy-migration --from-session session.json
+  CLI->>Registry: listPresetPackages()\n（分层发现，首匹配优先）
+  Registry-->>CLI: preset 对象（含 manifest + 路径）
+  CLI->>TaskDir: 创建标准任务骨架（brief / task_plan / visual_map 等）
+  CLI->>Engine: executeEntrypoint("newTask", preset, taskDir)
+  Engine->>TaskDir: 追加 preset 模板内容到任务文件
+  CLI->>TaskDir: 写入 preset metadata 到 task_plan.md
+  CLI->>TaskDir: 生成证据包（preset-manifest.json / preset-audit.json）
+  CLI-->>User: 任务创建完成
+```
+
+### Level 1 — 当前可用 Preset
+
+| Preset ID | 用途 | 兼容 Budget | 特殊要求 |
+| --- | --- | --- | --- |
+| `legacy-migration` | 旧 harness 项目迁移到 v1.0 | complex | 需要 `--from-session session.json` |
+| `lesson-sedimentation` | Lesson 沉淀任务 | standard, complex | 无 |
+| `module` | 模块并行工作任务 | standard, complex | 需要 `--module <module-id>` |
+| `standard-task` | 标准任务方法 | standard, complex | 无 |
+
+---
+
+## Part 2 — 迁移引擎
+
+### Level 1 — 迁移的三个阶段
+
+```mermaid
+flowchart LR
+  A["① migrate-plan\n分析差距\n生成动作队列"] --> B["② migrate-run\n执行迁移动作\n写入 session 记录"] --> C["③ migrate-verify\n验证迁移结果\n对比 baseline"]
+```
+
+### Level 2 — migrate-plan 做什么
+
+`buildMigrationPlan()` 识别 6 类差距：
+
+```mermaid
+flowchart TD
+  Plan["harness migrate-plan"]
+
+  Plan --> Scan["扫描目标仓库\nbuildStatus（非严格模式）"]
+  Scan --> Detect["检测已有能力\nreadCapabilityRegistry()"]
+  Detect --> Gaps["识别差距（6 类）"]
+
+  Gaps --> TaskActions["taskActions\n缺失 execution_strategy.md\n缺失 visual_map.md 的活跃任务"]
+  Gaps --> ReviewActions["reviewActions\n缺失审查字段\n（Reviewer Identity 等）"]
+  Gaps --> LegacyActions["legacyActions\n缺失必需的参考文件"]
+  Gaps --> LegacyResiduals["legacyResiduals\n历史任务的合同差距\n（不应自动迁移）"]
+  Gaps --> WeakBriefs["weakBriefTasks\nbrief.md 质量不达标"]
+  Gaps --> UnknownClass["unknownClassificationTasks\n任务分类不明确"]
+```
+
+**动作队列格式**：每个 taskAction 包含 `taskId`、`path`、`files[]`、`commands[]`、`action` 描述。
+`commands[]` 是可以直接执行的 harness CLI 命令列表。
+
+### Level 2 — migrate-verify 的两种模式
+
+```mermaid
+flowchart TD
+  Verify["harness migrate-verify session.json"]
+
+  Verify --> Normal["普通模式\n重新运行检查\n报告 failures / warnings"]
+
+  Verify --> FullCutover["--full-cutover 模式\n最严格验证（8 个条件）"]
+
+  FullCutover --> C1{"session.result == complete?"}
+  C1 -->|"否"| F1["FAIL"]
+  C1 -->|"是"| C2{"无 strictDeferred?"}
+  C2 -->|"否"| F2["FAIL"]
+  C2 -->|"是"| C3{"所有计数器 == 0?\n（warnings / taskActions\nreviewSchemaGaps / legacyResiduals 等）"}
+  C3 -->|"否"| F3["FAIL（列出非零计数器）"]
+  C3 -->|"是"| C4{"fullCutoverEligible == true?"}
+  C4 -->|"否"| F4["FAIL"]
+  C4 -->|"是"| P1["PASS（完全切换就绪）"]
+```
+
+`--full-cutover` 是迁移完成的最终验收标准：8 个条件全部满足才算通过。
+
+---
+
+## Part 3 — Capability 注册表
+
+### Level 1 — 能力依赖图
+
+```mermaid
+flowchart TD
+  Core["core\n（必选，所有其他能力的基础）"]
+
+  Core --> ModParallel["module-parallel\n模块注册表 + 并行工作"]
+  Core --> AdvReview["adversarial-review\n对抗审查报告\n（别名：review-contract）"]
+  Core --> LongRunning["long-running-task\n长时间运行任务合约"]
+  Core --> Dashboard["dashboard\n本地 HTML Dashboard"]
+  Core --> SafeAdoption["safe-adoption\n旧项目平滑接入"]
+
+  ModParallel --> SubagentWorker["subagent-worker\ncommit-backed worker 交接协议"]
+```
+
+### Level 2 — 每个能力的 selectWhen
+
+| 能力 | 何时启用 |
+| --- | --- |
+| `core` | 始终，这是必选基础 |
+| `module-parallel` | 项目有 2 个以上独立模块需要并行所有权时 |
+| `subagent-worker` | 代码变更 subagent 需要在独立 worktree 工作并 commit 交接时 |
+| `adversarial-review` | 发布、架构、安全、数据或策略风险需要独立审查产物时 |
+| `long-running-task` | Agent 可能跨多个 loop 运行而无需每步用户确认时 |
+| `dashboard` | 需要本地只读状态可视化时 |
+| `safe-adoption` | 将 v1.0 接入已有 harness 项目而不重写历史时 |
+
+### Level 2 — Preset 资源声明（resources）
+
+Preset 可以声明三类资源，这些资源会在任务创建时自动生成，并由检查器验证：
+
+| 资源类型 | 含义 | 验证方式 |
+| --- | --- | --- |
+| `resources.references` | Preset 提供的参考文件 | 文件存在 + `references/INDEX.md` 中有索引 + `task_plan.md` 中有必需阅读声明 |
+| `resources.artifacts` | Preset 生成的工件 | 文件存在 + `artifacts/INDEX.md` 中有索引 |
+| `context.requiredReads` | 必需阅读的参考文件 ID | 在两个索引中都有记录 |
+
+这是一个**三层验证链**：文件存在 → 索引表中有记录 → task_plan.md 中有必需阅读声明。
+任何一层缺失都会产生 failure。
+
+---
+
+## Part 4 — 设计决策
+
+### 为什么 Preset 不是一开始就有的
+
+Preset 系统是从"旧项目迁移太复杂"这个需求演进出来的。最初只有 `new-task --budget complex`，
+没有任何 preset 概念。当用户提出旧项目迁移需求时，最初的方案是发明一个新的 "Ultra" 任务等级。
+
+研究后发现问题不是 Complex 不够用，而是"没有 preset 时每个 Agent 都要自己想迁移流程该怎么拆"。
+三个独立 subagent 的对抗审查都指向同一结论——preset 是正确抽象，Ultra 是过度设计。
+
+否决 Ultra 的理由：
+1. Ultra 会引入第二套任务系统，破坏 simple/standard/complex 的一致性
+2. 问题的根因不是 Complex 承载不了，而是没有预填骨架
+3. Preset 是通用抽象，不只服务迁移——任何类型的任务都可以有自己的 Preset
+
+### 为什么 Preset manifest 用 YAML
+
+选择 YAML 是因为可读性——preset manifest 需要人工编写和审查，YAML 比 JSON 少引号和括号。
+选择自写轻量解析器（`parseSimpleYaml()`）而不是引入 `js-yaml` 是为了保持零依赖。
+JS 格式被排除是因为 preset 需要跨工具可审计，不能是可执行代码。
+
+### 为什么分层发现（project/user/builtin）
+
+分层发现比 preset 系统本身晚了两天引入。最初只从 package 的 `presets/` 固定路径读取。
+分层设计解决的核心问题是：
+- 不同项目可以有自己的私有 preset（project 层）
+- 用户可以安装跨项目共享的 preset（user 层）
+- Package bundled preset 作为兜底，不需要安装就能用（builtin 层）
+
+优先级顺序（project > user > builtin）确保项目级定制能覆盖全局默认。
+
+### 为什么迁移分三个阶段而不是一步到位
+
+核心考量是"不能自动迁移"——preset 只搭骨架，不自动改历史文档，
+不自动 stage 或 commit。真正写入目标仓库前，仍然要先让用户确认写入范围和迁移深度。
+
+- `migrate-plan`：只读分析，无副作用
+- `migrate-run`：有写入的执行，需要用户确认
+- `migrate-verify`：事后验证，确认迁移结果
+
+三步分离让用户在每个有副作用的节点都有确认机会。
+
+### 为什么 full-cutover 验证这么严格
+
+`full-cutover` 是不可逆的声明——一旦宣称完成迁移，后续 Agent 就不会再把这个项目当成迁移目标处理。
+更宽松的方案（只检查 strict pass）被否决，因为真实项目验证（471 个任务）证明了
+即使 strict pass，仍然可能有 weak brief 或 legacy-only visual map 残留。
+
+### writeScopes 安全边界
+
+writeScopes 和 preset 系统同时引入，不是后来补的安全加固。
+Preset 是第三方可安装的包，如果不限制写入范围，恶意或错误的 preset 可以覆盖任意文件。
+运行时强制检查路径，拒绝 `../` 开头的路径和绝对路径（path traversal 防护）。

package/docs-release/architecture/system-explainer/README.md

@@ -0,0 +1,67 @@
+# Coding Agent Harness — 架构解释文档
+
+这组文档帮助你理解 `coding-agent-harness` 的系统架构。
+无论你是想贡献代码、集成到自己的项目、还是只是想搞清楚"这东西到底怎么工作的"，
+这里都是最好的起点。
+
+每篇文档采用**自顶向下、逐层展开**的方式：先给你一张大图建立整体感，
+再一个模块一个模块地深入。你可以在任意层级停下来——不需要读完所有细节。
+
+---
+
+## 为什么要有这套文档
+
+`coding-agent-harness` 的代码库本身并不复杂，但它的**设计意图**不容易从代码里直接读出来。
+
+比如：
+- 为什么状态存在 Markdown 文件里，而不是数据库？
+- 为什么有三种 check profile，而不是一种？
+- `governance-sync` 和 `governance rebuild` 有什么区别，为什么要分开？
+- `review-confirm` 为什么必须是人工操作，不能自动化？
+
+这些问题的答案散落在设计决策、历史演进和操作规范里。
+这套文档把它们集中起来，让你不需要翻 git log 就能理解系统的"为什么"。
+
+---
+
+## 阅读顺序
+
+按顺序读效果最好，每篇 15-25 分钟：
+
+| 文件 | 主题 | 你会理解什么 |
+| --- | --- | --- |
+| [01-system-overview.md](01-system-overview.md) | 系统全景 | 这个东西是什么，解决什么问题，四个大块分别做什么 |
+| [02-module-dependency.md](02-module-dependency.md) | 代码模块 | CLI 怎么分发，lib/ 里 30+ 个模块怎么分层，依赖关系 |
+| [03-task-lifecycle.md](03-task-lifecycle.md) | 任务生命周期 | 一个任务从创建到收口的完整流转、门禁和队列系统 |
+| [04-check-and-governance.md](04-check-and-governance.md) | 检查体系 | 三种 profile，9 个验证器各验什么，治理索引如何重建 |
+| [05-data-flow.md](05-data-flow.md) | 数据流 | Markdown 文件如何变成 Dashboard，两种生成模式的边界 |
+| [06-preset-and-migration.md](06-preset-and-migration.md) | Preset 与迁移 | Preset 包结构和 entrypoint 类型系统，旧项目迁移三阶段 |
+
+---
+
+## 文档约定
+
+每个文件用 `Level 0 / 1 / 2 / 3` 标注层级深度：
+
+- **Level 0**：最高层，3-5 个大块，建立整体感（必读）
+- **Level 1**：展开大块，看清子模块（推荐读）
+- **Level 2**：深入子模块，理解内部逻辑（按需读）
+- **Level 3**：最细节，函数级别的流程（查阅用）
+
+可以只读到 Level 1 就停，有需要再往下看。
+
+---
+
+## 快速定位
+
+如果你有具体问题，直接跳到对应文件：
+
+| 我想知道… | 去哪里 |
+| --- | --- |
+| 这个系统解决什么问题 | [01 — 系统全景](01-system-overview.md) |
+| `harness check` 在验什么 | [04 — 检查体系](04-check-and-governance.md) |
+| 任务的 `review` 状态是什么意思 | [03 — 任务生命周期](03-task-lifecycle.md) |
+| Dashboard 数据从哪来 | [05 — 数据流](05-data-flow.md) |
+| Preset 怎么写 | [06 — Preset 与迁移](06-preset-and-migration.md) |
+| 代码里某个模块是干什么的 | [02 — 代码模块](02-module-dependency.md) |
+| 旧项目怎么迁移进来 | [06 — Preset 与迁移](06-preset-and-migration.md) |