@tea-agent/loop-agent 0.13.0-beta.0 → 0.13.0

package/docs/architecture/worker-and-feature.md

@@ -1,85 +1,85 @@
-# Worker 与 Feature 架构
-
-本页说明 `agent-worker` 如何通过冻结的已发布 `loop-agent` 子进程执行 DAG（不 in-process import runtime kernel），以及其上的产品线 read model：TaskSpec、Task Pool、Feature 与 Observe。边界契约权威是 `runtime-boundaries.md` §Worker adapter。
-
-## 核心事实：子进程，非 in-process
-
-`agent-worker` 真正执行 DAG 时通过 Node `child_process.spawn` 启动**已发布**的 `loop-agent`，**不** in-process import runtime kernel：
-
-| 事实 | 源码入口 |
-| --- | --- |
-| 客户端 | `src/worker/loop-agent/loop-agent-client.ts` `LoopAgentClient` |
-| 执行入口 | `LoopAgentClient.run(args, options)` |
-| spawn 实现 | `spawnCommand(...)` → `spawn(input.command, input.args, { cwd, env, shell: false, stdio: ["ignore", "pipe", "pipe"] })` |
-| 治理禁止 | `scripts/check-architecture-boundaries.sh` 禁止 `src/worker/**` → `src/{cli,commands,application}/**`，transitional allowlist 为空 |
-
-`shell: false` + 绝对 launch spec（见下）意味着 Worker 不走 PATH 重新解析，也不在当前进程内加载 CLI command 实现。
-
-## controller identity（冻结的已发布 controller）
-
-每次写入型 Feature/batch/Task/final verification 在任何目标仓库或 Task Pool 状态写入前，`LoopAgentClient` 解析并冻结 schemaVersion 1 identity（`ControllerIdentityV1`，定义在 `src/shared/package-metadata.ts`）：
-
-| 字段 | 含义 |
-| --- | --- |
-| `schemaVersion` | 固定 `1` |
-| `packageName` | 必须为 `@tea-agent/loop-agent` |
-| `binName` / `requested` / `entry` / `realEntry` | 入口解析链（realEntry 经 `realpathSync`） |
-| `launch.command` / `launch.argsPrefix` | 直接可执行的绝对 launch spec |
-| `binarySha256` | `actualEntry` 二进制 hash |
-| `packageVersion` | `package.json` version |
-| `packageFingerprint` | 覆盖 `package.json`、`bin/**`、`dist/**`、`skills/**` 的 portable fingerprint（`computePackageFingerprint`） |
-
-关键方法：
-
-- `resolveIdentity()`（`loop-agent-client.ts`）：首次解析并冻结 identity；`this._identityResolved = true`。
-- `assertControllerIdentityUnchangedBeforeSpawn(identity)`（`loop-agent-client.ts`）：**每次 spawn 前**重验，漂移即 throw（`run` 与 `runCommand` 路径都调）。
-- `getIdentity()` / `observeReportedVersion(reportedVersion)`：读取/校验子进程回报的版本须与 `packageVersion` 一致。
-
-CLI 层（`src/worker/cli.ts`）在写入型命令传 `resolveIdentity: true` 构造 `LoopAgentClient`，并支持 `--expected-controller-version` / `--expected-controller-fingerprint` fail-fast（见 `src/worker/preflight.ts`）。
-
-controller identity 与 DAG skill snapshot 是两个不同冻结层（前者跨 Worker/Task Pool/Feature 生命周期，后者单个 DAG run），见 `runtime-boundaries.md` §版本化自举边界。
-
-## 独立 CLI
-
-`agent-worker` 是独立 CLI（`bin/agent-worker.js` → `src/worker/cli.ts`），有自己的命令面（`task`、`batch`、`feature`、`report`、`observe` 等）。它**不是**第二套 executor 或 DAG kernel；它编排产品线 Task 并把执行委托给 `loop-agent` 子进程。
-
-## 产品线 read model
-
-### TaskSpec
-
-- schema/validate：`src/worker/task-spec/{schema,validate}.ts`。
-- 校验验收条件、依赖、验证命令；`agent-worker task validate-feature` 等用之。
-
-### Task Pool
-
-- 唯一 runtime root：`src/worker/pool/run-store.ts`
-  `TASK_POOL_RELATIVE_ROOT = ".harness/task-pool"`（ADR 0002）。
-- 此前的顶层 Task Pool 位置不读取、不迁移、不合并、不重映射。
-- **Feature-scoped identity（ADR 0004）**：canonical Task 身份为复合键 `TaskPoolTaskRef = { featureId, taskId }`。`taskId` 仅 Feature 内唯一；同仓库多 Feature 可安全共用同名 Task ID。
-- **State schema v2**：新 state 必须 `schemaVersion: 2` 且显式携带 `featureId` / `taskId`；canonical 路径为 `.harness/task-pool/states/<featureId>/<taskId>.json`。
-- **Consumers**：runner Ready Queue、retry、Follow-up、Feature review、Delivery / Closeout、morning report / metrics 均按 Feature 作用域读写，不得把裸 `taskId` 当作仓库全局唯一键。
-- **Operator**：`pool doctor` 只读 inventory；`pool migrate-state` 默认 dry-run，apply 需 `--owner` + `--reason`；legacy v1 写入路径 fail-closed。
-- batch / retry / morning report 等都基于此根。
-
-### Feature（M2 交付闭环）
-
-- review/run/approve-followup/delivery/closeout/verify-final：`src/worker/feature/{review,run}.ts` 及相关。
-- Follow-up：`src/worker/` 下 draft-followup + approve-followup 事务，覆盖全部失败分类（可执行/Spec/Risk/Human/EnvFailure）。
-- Delivery / Closeout：clean Delivery HEAD 上生成 canonical QA/最终验证证据、Delivery Package、Acceptance Coverage、PR 草稿；Closeout 默认预览，显式 `--apply --owner` 才原子写回。
-- 权威证据：`CHANGELOG.md [0.10.0]`、`docs/reports/2026-07-12-m2-completion-audit.md`。
-
-### Observe（只读 read model）
-
-- 模块：`src/worker/observe/`、`src/worker/observability/{read-model,event-store}.ts`。
-- 全局快照：`buildGlobalSnapshot({ repoRoot })`（`src/worker/observability/read-model.ts`），是 **derived** 视图，消费 `.harness/` 与 Task Pool 事实，**不**改变执行成败。
-- Observe 是本地只读暖白控制台；snapshot 投影失败返回安全错误摘要而非全零健康状态（见 `CHANGELOG.md [0.9.0]`）。
-
-## 版本化自举的 deterministic canary
-
-源码仓库的 deterministic candidate canary（`scripts/self-host-canary.mjs`，`npm run self-host:canary -- --deterministic`）是只读/确定性接棒证据：候选 tarball 安装到隔离 slot，两个 bin 从包内绝对入口启动，PATH 中放置 controller fallback trap，只执行 Feature dry-run 与 static/shell DAG。它必须证明 `piExecutorObserved=false` / `modelExecutorObserved=false` / `featureExecutedTasks=[]`，因此**不是** live Pi takeover。该脚本**不**属于发布 package surface（`package.json` `files` 不含它）。
-
-## 不变式
-
-- Worker 不得 in-process import `src/cli/**`、`src/commands/**` 或 `src/application/**`（governance 机器校验）。
-- Worker 不实现 executor、scheduler、prompt 或 write guard。
-- `agent-worker` skill（`skills/agent-worker/`）不加入 `DEFAULT_SKILLS_BY_ROLE`；DAG leaf node 不得递归启动 `agent-worker`（`runtime-boundaries.md` §Skill layer）。
+# Worker 与 Feature 架构
+
+本页说明 `agent-worker` 如何通过冻结的已发布 `loop-agent` 子进程执行 DAG（不 in-process import runtime kernel），以及其上的产品线 read model：TaskSpec、Task Pool、Feature 与 Observe。边界契约权威是 `runtime-boundaries.md` §Worker adapter。
+
+## 核心事实：子进程，非 in-process
+
+`agent-worker` 真正执行 DAG 时通过 Node `child_process.spawn` 启动**已发布**的 `loop-agent`，**不** in-process import runtime kernel：
+
+| 事实 | 源码入口 |
+| --- | --- |
+| 客户端 | `src/worker/loop-agent/loop-agent-client.ts` `LoopAgentClient` |
+| 执行入口 | `LoopAgentClient.run(args, options)` |
+| spawn 实现 | `spawnCommand(...)` → `spawn(input.command, input.args, { cwd, env, shell: false, stdio: ["ignore", "pipe", "pipe"] })` |
+| 治理禁止 | `scripts/check-architecture-boundaries.sh` 禁止 `src/worker/**` → `src/{cli,commands,application}/**`，transitional allowlist 为空 |
+
+`shell: false` + 绝对 launch spec（见下）意味着 Worker 不走 PATH 重新解析，也不在当前进程内加载 CLI command 实现。
+
+## controller identity（冻结的已发布 controller）
+
+每次写入型 Feature/batch/Task/final verification 在任何目标仓库或 Task Pool 状态写入前，`LoopAgentClient` 解析并冻结 schemaVersion 1 identity（`ControllerIdentityV1`，定义在 `src/shared/package-metadata.ts`）：
+
+| 字段 | 含义 |
+| --- | --- |
+| `schemaVersion` | 固定 `1` |
+| `packageName` | 必须为 `@tea-agent/loop-agent` |
+| `binName` / `requested` / `entry` / `realEntry` | 入口解析链（realEntry 经 `realpathSync`） |
+| `launch.command` / `launch.argsPrefix` | 直接可执行的绝对 launch spec |
+| `binarySha256` | `actualEntry` 二进制 hash |
+| `packageVersion` | `package.json` version |
+| `packageFingerprint` | 覆盖 `package.json`、`bin/**`、`dist/**`、`.agents/skills/**` 的 portable fingerprint（`computePackageFingerprint`） |
+
+关键方法：
+
+- `resolveIdentity()`（`loop-agent-client.ts`）：首次解析并冻结 identity；`this._identityResolved = true`。
+- `assertControllerIdentityUnchangedBeforeSpawn(identity)`（`loop-agent-client.ts`）：**每次 spawn 前**重验，漂移即 throw（`run` 与 `runCommand` 路径都调）。
+- `getIdentity()` / `observeReportedVersion(reportedVersion)`：读取/校验子进程回报的版本须与 `packageVersion` 一致。
+
+CLI 层（`src/worker/cli.ts`）在写入型命令传 `resolveIdentity: true` 构造 `LoopAgentClient`，并支持 `--expected-controller-version` / `--expected-controller-fingerprint` fail-fast（见 `src/worker/preflight.ts`）。
+
+controller identity 与 DAG skill snapshot 是两个不同冻结层（前者跨 Worker/Task Pool/Feature 生命周期，后者单个 DAG run），见 `runtime-boundaries.md` §版本化自举边界。
+
+## 独立 CLI
+
+`agent-worker` 是独立 CLI（`bin/agent-worker.js` → `src/worker/cli.ts`），有自己的命令面（`task`、`batch`、`feature`、`report`、`observe` 等）。它**不是**第二套 executor 或 DAG kernel；它编排产品线 Task 并把执行委托给 `loop-agent` 子进程。
+
+## 产品线 read model
+
+### TaskSpec
+
+- schema/validate：`src/worker/task-spec/{schema,validate}.ts`。
+- 校验验收条件、依赖、验证命令；`agent-worker task validate-feature` 等用之。
+
+### Task Pool
+
+- 唯一 runtime root：`src/worker/pool/run-store.ts`
+  `TASK_POOL_RELATIVE_ROOT = ".harness/task-pool"`（ADR 0002）。
+- 此前的顶层 Task Pool 位置不读取、不迁移、不合并、不重映射。
+- **Feature-scoped identity（ADR 0004）**：canonical Task 身份为复合键 `TaskPoolTaskRef = { featureId, taskId }`。`taskId` 仅 Feature 内唯一；同仓库多 Feature 可安全共用同名 Task ID。
+- **State schema v2**：新 state 必须 `schemaVersion: 2` 且显式携带 `featureId` / `taskId`；canonical 路径为 `.harness/task-pool/states/<featureId>/<taskId>.json`。
+- **Consumers**：runner Ready Queue、retry、Follow-up、Feature review、Delivery / Closeout、morning report / metrics 均按 Feature 作用域读写，不得把裸 `taskId` 当作仓库全局唯一键。
+- **Operator**：`pool doctor` 只读 inventory；`pool migrate-state` 默认 dry-run，apply 需 `--owner` + `--reason`；legacy v1 写入路径 fail-closed。
+- batch / retry / morning report 等都基于此根。
+
+### Feature（M2 交付闭环）
+
+- review/run/approve-followup/delivery/closeout/verify-final：`src/worker/feature/{review,run}.ts` 及相关。
+- Follow-up：`src/worker/` 下 draft-followup + approve-followup 事务，覆盖全部失败分类（可执行/Spec/Risk/Human/EnvFailure）。
+- Delivery / Closeout：clean Delivery HEAD 上生成 canonical QA/最终验证证据、Delivery Package、Acceptance Coverage、PR 草稿；Closeout 默认预览，显式 `--apply --owner` 才原子写回。
+- 权威证据：`CHANGELOG.md [0.10.0]`、`ai_workspace/loop-agent/reports/2026-07-12-m2-completion-audit.md`。
+
+### Observe（只读 read model）
+
+- 模块：`src/worker/observe/`、`src/worker/observability/{read-model,event-store}.ts`。
+- 全局快照：`buildGlobalSnapshot({ repoRoot })`（`src/worker/observability/read-model.ts`），是 **derived** 视图，消费 `.harness/` 与 Task Pool 事实，**不**改变执行成败。
+- Observe 是本地只读暖白控制台；snapshot 投影失败返回安全错误摘要而非全零健康状态（见 `CHANGELOG.md [0.9.0]`）。
+
+## 版本化自举的 deterministic canary
+
+源码仓库的 deterministic candidate canary（`scripts/self-host-canary.mjs`，`npm run self-host:canary -- --deterministic`）是只读/确定性接棒证据：候选 tarball 安装到隔离 slot，两个 bin 从包内绝对入口启动，PATH 中放置 controller fallback trap，只执行 Feature dry-run 与 static/shell DAG。它必须证明 `piExecutorObserved=false` / `modelExecutorObserved=false` / `featureExecutedTasks=[]`，因此**不是** live Pi takeover。该脚本**不**属于发布 package surface（`package.json` `files` 不含它）。
+
+## 不变式
+
+- Worker 不得 in-process import `src/cli/**`、`src/commands/**` 或 `src/application/**`（governance 机器校验）。
+- Worker 不实现 executor、scheduler、prompt 或 write guard。
+- `agent-worker` skill（`.agents/skills/agent-worker/`）不加入 `DEFAULT_SKILLS_BY_ROLE`；DAG leaf node 不得递归启动 `agent-worker`（`runtime-boundaries.md` §Skill layer）。

package/docs/cursor-prompt-sidecar.md

@@ -1,36 +1,36 @@
-# cursor-prompt Sidecar
-
-`cursor-prompt` 是显式、手工触发的 one-shot sidecar。它不是受治理 Agent runtime，也不参与 DAG、Loop 自动写入、Delegate `--auto-run` 或 task writer 选择。
-
-## 产品定位
-
-| 路径 | 角色 |
-|---|---|
-| Pi DAG (`implement-pi` / `repair-pi`) | 唯一受治理 Agent writer |
-| shell / static | 确定性验证与静态输出 |
-| `cursor-prompt` | 人工 one-shot 干预；成功不等于任务完成 |
-
-## 用法
-
-```bash
-loop-agent cursor-prompt --cwd . "bounded task prompt"
-loop-agent cursor-prompt --file <path>
-loop-agent cursor-prompt --stdin
-loop-agent cursor-prompt --model <id>
-loop-agent cursor-prompt --timeout <ms>
-loop-agent cursor-prompt --stream
-loop-agent cursor-prompt --list-models
-```
-
-调用时才加载 `@cursor/sdk`。缺少 SDK 或 `CURSOR_API_KEY` 时，只有这条命令失败；普通 Agent DAG / doctor / init 不要求 Cursor。
-
-## 约束
-
-- 不读取 `harness.json` task config / DAG facts 作为授权来源。
-- 不复制 DAG `writeSet`、repair、resume 或 Loop auto-execute 能力。
-- 返回后由主会话检查 diff，并显式运行 shell verification。
-- one-shot evidence 写入 `.harness/runs/{active,completed,failed}`。
-
-## 迁移说明
-
-旧 `executor: "cursor"` DAG、`executors.cursor`、`loopAutoWritePolicy` 与 `cursor-fix` 已硬切删除。需要写入时请重新生成 Pi-only DAG，或仅在人工干预场景使用本 sidecar。
+# cursor-prompt Sidecar
+
+`cursor-prompt` 是显式、手工触发的 one-shot sidecar。它不是受治理 Agent runtime，也不参与 DAG、Loop 自动写入、Delegate `--auto-run` 或 task writer 选择。
+
+## 产品定位
+
+| 路径 | 角色 |
+|---|---|
+| Pi DAG (`implement-pi` / `repair-pi`) | 唯一受治理 Agent writer |
+| shell / static | 确定性验证与静态输出 |
+| `cursor-prompt` | 人工 one-shot 干预；成功不等于任务完成 |
+
+## 用法
+
+```bash
+loop-agent cursor-prompt --cwd . "bounded task prompt"
+loop-agent cursor-prompt --file <path>
+loop-agent cursor-prompt --stdin
+loop-agent cursor-prompt --model <id>
+loop-agent cursor-prompt --timeout <ms>
+loop-agent cursor-prompt --stream
+loop-agent cursor-prompt --list-models
+```
+
+调用时才加载 `@cursor/sdk`。缺少 SDK 或 `CURSOR_API_KEY` 时，只有这条命令失败；普通 Agent DAG / doctor / init 不要求 Cursor。
+
+## 约束
+
+- 不读取 `harness.json` task config / DAG facts 作为授权来源。
+- 不复制 DAG `writeSet`、repair、resume 或 Loop auto-execute 能力。
+- 返回后由主会话检查 diff，并显式运行 shell verification。
+- one-shot evidence 写入 `.harness/runs/{active,completed,failed}`。
+
+## 迁移说明
+
+旧 `executor: "cursor"` DAG、`executors.cursor`、`loopAutoWritePolicy` 与 `cursor-fix` 已硬切删除。需要写入时请重新生成 Pi-only DAG，或仅在人工干预场景使用本 sidecar。

package/docs/decisions/README.md

@@ -1,18 +1,18 @@
-# 决策
-
-本目录存放架构决策记录（ADR）。模板见 `docs/templates/adr.md`。
-
-## 索引
-
-| ADR | 状态 | 摘要 |
-| --- | --- | --- |
-| [`0001-pi-only-agent-runtime.md`](0001-pi-only-agent-runtime.md) | accepted | 受治理 Agent 仅 Pi；`cursor-prompt` 为显式 sidecar |
-| [`0002-task-pool-runtime-root.md`](0002-task-pool-runtime-root.md) | accepted | Task Pool 唯一根 `.harness/task-pool/`，旧 `.task-pool/` 不兼容 |
-| [`0003-docs-dual-tree-converge.md`](0003-docs-dual-tree-converge.md) | accepted | `website/docs/` 用法 vs `docs/` 治理；docs-converge 检查表 |
-| [`0004-task-pool-feature-scoped-task-identity.md`](0004-task-pool-feature-scoped-task-identity.md) | accepted | Task Pool 复合身份 `{featureId,taskId}`、state v2、legacy fail-closed、Observe composite route |
-
-**读者注意（M4）**：ADR 0004 **决策边界**仍有效；正文中「M2+ 未改 consumers/Observe」段落是 M0/M1 当时的切片叙述，现已过时。实现进度以 `docs/progress/2026-07-15-task-pool-v2-feature-scoped-task-identity.md`、最终报告 `docs/reports/2026-07-15-task-pool-v2-feature-scoped-task-identity.md` 与 `CHANGELOG.md [Unreleased]` 为准。本任务 **不修改** ADR 0004 正文（不在 closeout allowedPaths）。
-
-新增跨版本架构取舍时：用模板新增 `NNNN-title.md`，并更新本表。不要把 ADR 正文复制进 `website/docs/`。
-
-实施细节与证据仍以对应 `docs/exec-plans/completed/` 与 `CHANGELOG.md` 为准；ADR 只固化决策边界。
+# 决策
+
+本目录存放架构决策记录（ADR）。模板见 `docs/templates/adr.md`。
+
+## 索引
+
+| ADR | 状态 | 摘要 |
+| --- | --- | --- |
+| [`0001-pi-only-agent-runtime.md`](0001-pi-only-agent-runtime.md) | accepted | 受治理 Agent 仅 Pi；`cursor-prompt` 为显式 sidecar |
+| [`0002-task-pool-runtime-root.md`](0002-task-pool-runtime-root.md) | accepted | Task Pool 唯一根 `.harness/task-pool/`，旧 `.task-pool/` 不兼容 |
+| [`0003-docs-dual-tree-converge.md`](0003-docs-dual-tree-converge.md) | accepted | `website/docs/` 用法 vs `docs/` 治理；docs-converge 检查表 |
+| [`0004-task-pool-feature-scoped-task-identity.md`](0004-task-pool-feature-scoped-task-identity.md) | accepted | Task Pool 复合身份 `{featureId,taskId}`、state v2、legacy fail-closed、Observe composite route |
+
+**读者注意（M4）**：ADR 0004 **决策边界**仍有效；正文中「M2+ 未改 consumers/Observe」段落是 M0/M1 当时的切片叙述，现已过时。实现进度以 `docs/progress/2026-07-15-task-pool-v2-feature-scoped-task-identity.md`、最终报告 `docs/reports/2026-07-15-task-pool-v2-feature-scoped-task-identity.md` 与 `CHANGELOG.md [Unreleased]` 为准。本任务 **不修改** ADR 0004 正文（不在 closeout allowedPaths）。
+
+新增跨版本架构取舍时：用模板新增 `NNNN-title.md`，并更新本表。不要把 ADR 正文复制进 `website/docs/`。
+
+实施细节与证据仍以对应 `docs/exec-plans/completed/` 与 `CHANGELOG.md` 为准；ADR 只固化决策边界。

package/docs/design/README.md

@@ -1,167 +1,167 @@
-# 设计笔记
-
-`docs/design/` 存放将 `loop-agent` 作为更大产品线 agent 平台内仓库本地 runtime 的规划笔记。这些是设计输入，不是 `src/` 已具备该能力的证明——**除非**页首明确写了实现校准条，且有 `src/` / CHANGELOG / completed plan 旁证。
-
-**维护日：2026-07-16** — 索引与归档建议按当前代码（`@tea-agent/loop-agent@0.12.0` + 主干 Unreleased）再采样。
-
-| 文档 | 用途 |
-|---|---|
-| `taskspec-to-loop-agent-mapping.md` | 将产品线 TaskSpec 适配为 `loop-agent` task 的契约 |
-| `taskspec-to-loop-agent-mapping.yaml` | 同上契约的结构化对照表 |
-| `state-and-failure-taxonomy.md` | 文档、Task Pool、DAG、Loop 共用的 canonical status 与 failure taxonomy |
-| `frontend-implementation-workflow.md` | 前端 DAG 实现 / 评审 / 验证工作流与证据约定 |
-| `frontend-mock-data-workflow.md` | 前端任务先读取规范、识别项目 Mock 服务、生成 Mock 合同并做专项验证的已实现设计 |
-| `dag-source-binding-and-recovery.md` | 新生成 DAG 的权威任务源绑定、前端需求编号覆盖门禁与中断后完整重生成规则 |
-| `full-chain-test-knowledge-base.md` | 全流程测试知识库分层、目录、对象模型、与 backend-test-dag / Feature QA 的读写映射 |
-| `full-chain-testing-system-redesign.md` | **综合重设计**：知识库权威层 + I/T/V/K 四类 DAG + knowledge-sync v2 硬化与迁移 |
-| `testing-knowledge-base-impl-spec.md` | **知识库实现细节 v1（先冻结）**：目录、schema、ID、读写矩阵、校验规则、MVP 清单 |
-| `knowledge-graph-and-query-spec.md` | **业务知识图谱 + 查询协议 v1**：实体/边、knowledge-links、kb-query 分层、索引 materialize |
-| `knowledge-graph-ai-bootstrap.md` | **AI 构建图谱 + 初始化 B0–B6**：staging 提案、人审晋升、bootstrap DAG、增量更新 |
-| `verification-subdag-plugin.md` | 独立测试全流程 Verification DAG 与三种实现 DAG 的 compose 设计（若分支存在） |
-## 归档策略（何时迁入 `archive/`）
-
-满足以下**多数**条件时可归档：
-
-1. 对应能力已在 `src/` 落地，且有 `docs/exec-plans/completed/*` 或 dated report / CHANGELOG 版本说明；
-2. 文档主体是**阶段性计划 / 月度 WBS / 已关闭路线图**，不再驱动实现决策；
-3. 继续放在 design 根目录会让新人误判为「未做完」或「下一件必做」。
-
-**不要归档**（仍放根目录）：
-
-- 仍被代码/CLI/映射表**持续引用**的契约（taxonomy、taskspec mapping、frontend workflow 等）；
-- 仍有 **active exec-plan** 或大段 **planned/deferred** 的设计真源（如 Eval Lab）；
-- 长期路线与方法论笔记（六个月规划、腾讯实践、研发模式）——可加校准条，不必塞进 archive；
-- 纯视觉 token 参考（`DESIGN-*.md`）。
-
----
-
-## 契约与实现映射（优先读 · 仍活）
-
-| 文档 | 用途 | 归档建议 |
-|---|---|---|
-| `taskspec-to-loop-agent-mapping.md` / `.yaml` | TaskSpec → loop-agent task 契约 | **保留**（随 schema 更新） |
-| `state-and-failure-taxonomy.md` | 状态 / failure taxonomy | **保留** |
-| `frontend-implementation-workflow.md` | 前端 DAG 实现/评审/验证约定 | **保留**（活工作流） |
-| `full-chain-test-knowledge-base.md` | 测试知识库分层与对象模型 | **保留**（K 族权威设计） |
-| `full-chain-testing-system-redesign.md` | I/T/V/K 综合重设计 | **保留**（后续 T/V 与 hardening 仍可能引用；MVP 已部分 ship） |
-| `testing-knowledge-base-impl-spec.md` | 知识库实现细节 v1 | **保留**（规格冻结；DAG 细节另文） |
-| `knowledge-graph-and-query-spec.md` | 图谱 + 查询协议 v1 | **保留**（Phase A 已实现，规格仍真源） |
-| `knowledge-graph-ai-bootstrap.md` | AI bootstrap B0–B6 / staging | **保留**（bootstrap MVP 已实现，增量/产品化仍引用） |
-
-**执行 Contract（knowledge 已完成归档）：** `docs/exec-plans/completed/2026-07-14-knowledge-sync-and-graph.md`
-
----
-
-## 实验 / 评测（设计输入 · 进行中）
-
-| 文档 | 用途 | 归档建议 |
-|---|---|---|
-| `recursive-self-improvement-eval-lab.md` | Harness Eval Lab 设计真源 | **保留 active**：M1 + M2 W2.1–W2.3 已实现；W2.4 / M3+ 未做。执行计划：`docs/exec-plans/active/2026-07-16-recursive-self-improvement-eval-lab.md` |
-
-> 设计 README 旧句「W2.3 仍未实现」已过时：W2.3 run association **已合入**（见 active plan 进度与 `CHANGELOG.md [Unreleased]`）。
-
----
-
-## 路线与产品线笔记（非实现证明 · 保留 + 校准条）
-
-| 文档 | 用途 | 归档建议 |
-|---|---|---|
-| `dynamic-workflow-dag-engine-roadmap.md` | Dynamic Workflow 阶段规划 | **保留**：页首有落地校准；高风险 shard/merge 等仍是 roadmap |
-| `六个月规划.md` | 长期路线 | **保留**：页首 **2026-07-16** 已补 0.12.0 / Task Pool v2 / Ready Planner / Eval 指针；第 3–6 月仍有效前瞻 |
-| `产品线共享知识库.md` | 产品线文档仓库上游事实源 | **保留**（docs-sync 等仍多为未来） |
-| `研发模式.md` | 10 日 Feature 团队工作流 | **保留**（方法论） |
-| `腾讯实践对当前项目的指引.md` | 外部实践映射 | **保留**（背景；源文在 website practices） |
-
----
-
-## 视觉参考（保留）
-
-| 文档 | 用途 | 归档建议 |
-|---|---|---|
-| `DESIGN-cursor.md` | Observe 暖白 / Cursor 风格 token | **保留**（视觉参考） |
-| `DESIGN-lovable.md` | Lovable 暖色视觉参考 | **保留** |
-
----
-
-## 本次已迁入 `archive/`（2026-07-16）
-
-| 文档 | 原因 |
-|---|---|
-| `archive/2026-07-14-loop-agent-self-update-notifier.md` | 自更新提醒 **已实现**（0.11.0 + report/completed plan）；设计不再是「尚未实现」 |
-| `archive/2026-07-16-priority-ready-planner-contract.md` | Ready Planner **已实现并 closeout**；原 M0 RED「未实现」状态条会误导 |
-
----
-
-## 已归档（历史）
-
-| 文档 | 用途 |
-|---|---|
-| `archive/2026-07-07-agent-worker-plan.md` | Worker 落地计划（已实现于 `src/worker/`） |
-| `archive/2026-07-07-taskspec-plan.md` | TaskSpec v0.1 设计（已实现） |
-| `archive/2026-07-10-下一阶段任务-功能开发完成.md` | 样本/失败硬化完成记录 |
-| `archive/2026-07-10-observe-ui.md` | Observe UI v0（OBS-001～010） |
-| `archive/2026-07-10-observe-ui-optimization.md` | 中文 DAG-first / 过程时间线 |
-| `archive/2026-07-10-observe-ui-goal.md` | OBS 进度看板（全部 done） |
-| `archive/2026-07-14-observe-ui-roadmap.md` | Observe R1–R5 路线图（已完成） |
-| `archive/2026-07-11-第一月规划.md` / `第一月wbs.md` | 首月闭环历史 |
-| `archive/2026-07-12-第二月规划.md` | 第二月 Feature 闭环历史 |
-| `archive/2026-07-14-loop-agent-self-update-notifier.md` | CLI 自更新提醒设计（已实现） |
-| `archive/2026-07-16-priority-ready-planner-contract.md` | Ready Planner M0 合同（已实现） |
-
----
-
-## 根目录文件 — 归档建议一览（2026-07-16）
-
-| 文件 | 建议 | 说明 |
-|---|---|---|
-| `README.md` | 保留 | 本索引 |
-| `taskspec-to-loop-agent-mapping.*` | 保留 | 活契约 |
-| `state-and-failure-taxonomy.md` | 保留 | 活契约 |
-| `frontend-implementation-workflow.md` | 保留 | 活工作流 |
-| `full-chain-test-knowledge-base.md` | 保留 | K 族设计真源 |
-| `full-chain-testing-system-redesign.md` | 保留（可选日后拆「已落地摘要」） | 综合草案；部分已 ship |
-| `testing-knowledge-base-impl-spec.md` | 保留 | 规格冻结 |
-| `knowledge-graph-and-query-spec.md` | 保留 | 协议真源 |
-| `knowledge-graph-ai-bootstrap.md` | 保留 | bootstrap 设计真源 |
-| `recursive-self-improvement-eval-lab.md` | **保留 active** | Eval Lab 真源 |
-| `dynamic-workflow-dag-engine-roadmap.md` | 保留 | roadmap + 校准 |
-| `六个月规划.md` | 保留 | 路线；校准条已含 0.12 / Unreleased |
-| `产品线共享知识库.md` | 保留 | 上游知识库愿景 |
-| `研发模式.md` | 保留 | 方法论 |
-| `腾讯实践对当前项目的指引.md` | 保留 | 实践映射 |
-| `DESIGN-cursor.md` / `DESIGN-lovable.md` | 保留 | 视觉 |
-| ~~`2026-07-14-loop-agent-self-update-notifier.md`~~ | **已归档** | 见上 |
-| ~~`2026-07-16-priority-ready-planner-contract.md`~~ | **已归档** | 见上 |
-
-### 暂不建议归档（但可标注「部分落地」）
-
-- **knowledge 四件套 + full-chain\***：exec-plan 已 complete，但设计文仍是目录/schema/增量协议的权威；归档会切断引用习惯。若未来拆出「实现状态」短页，可把**纯进度段落**迁 archive，规格正文仍留根。
-- **六个月规划 / Dynamic Workflow roadmap**：含未来月与未完成 primitive；只做页首校准，整篇归档会丢前瞻。
-
----
-
-## 命名约定（2026-07-09 起）
-
-| 名称 | 含义 | 状态 |
-|---|---|---|
-| `loop-agent` | 仓库本地 runtime / 治理控制器 CLI | 已发布 |
-| `agent-worker` | 产品线 TaskSpec 批处理适配层 CLI | 已发布 |
-| `agent-platform` | 早期规划设想名；**不是**当前 CLI | 仅未来 monorepo/上层服务语境 |
-
-```text
-产品线 docs / TaskSpec / TaskGraph
-  → agent-worker（本地批处理适配）
-    → loop-agent（runtime kernel）
-      → Pi（受治理 Agent） / shell / static
-      → cursor-prompt（显式手工 one-shot sidecar，非受治理 writer）
-```
-
-## 维护规则
-
-1. 保持 TaskSpec 字段、status、failure category、命令示例与契约文档一致。  
-2. 未来平台组件标为目标架构，除非已存在于 `src/` 或 `scripts/`。  
-3. 命令示例只用 `agent-worker` / `loop-agent`。  
-4. `config-types` / profile routing 变更时更新 mapping 文档。  
-5. failure / Task Pool state 变更时更新 taxonomy。  
-6. **过期月规划 / 已关闭实现合同**迁入 `archive/`，并更新本 README。  
-7. 运行 `bash scripts/check-repo.sh`（或至少 check-doc-index / check-doc-links）。  
+# 设计笔记
+
+`docs/design/` 存放将 `loop-agent` 作为更大产品线 agent 平台内仓库本地 runtime 的规划笔记。这些是设计输入，不是 `src/` 已具备该能力的证明——**除非**页首明确写了实现校准条，且有 `src/` / CHANGELOG / completed plan 旁证。
+
+**维护日：2026-07-16** — 索引与归档建议按当前代码（`@tea-agent/loop-agent@0.12.0` + 主干 Unreleased）再采样。
+
+| 文档 | 用途 |
+|---|---|
+| `taskspec-to-loop-agent-mapping.md` | 将产品线 TaskSpec 适配为 `loop-agent` task 的契约 |
+| `taskspec-to-loop-agent-mapping.yaml` | 同上契约的结构化对照表 |
+| `state-and-failure-taxonomy.md` | 文档、Task Pool、DAG、Loop 共用的 canonical status 与 failure taxonomy |
+| `frontend-implementation-workflow.md` | 前端 DAG 实现 / 评审 / 验证工作流与证据约定 |
+| `frontend-mock-data-workflow.md` | 前端任务先读取规范、识别项目 Mock 服务、生成 Mock 合同并做专项验证的已实现设计 |
+| `dag-source-binding-and-recovery.md` | 新生成 DAG 的权威任务源绑定、前端需求编号覆盖门禁与中断后完整重生成规则 |
+| `full-chain-test-knowledge-base.md` | 全流程测试知识库分层、目录、对象模型、与 backend-test-dag / Feature QA 的读写映射 |
+| `full-chain-testing-system-redesign.md` | **综合重设计**：知识库权威层 + I/T/V/K 四类 DAG + knowledge-sync v2 硬化与迁移 |
+| `testing-knowledge-base-impl-spec.md` | **知识库实现细节 v1（先冻结）**：目录、schema、ID、读写矩阵、校验规则、MVP 清单 |
+| `knowledge-graph-and-query-spec.md` | **业务知识图谱 + 查询协议 v1**：实体/边、knowledge-links、kb-query 分层、索引 materialize |
+| `knowledge-graph-ai-bootstrap.md` | **AI 构建图谱 + 初始化 B0–B6**：staging 提案、人审晋升、bootstrap DAG、增量更新 |
+| `verification-subdag-plugin.md` | 独立测试全流程 Verification DAG 与三种实现 DAG 的 compose 设计（若分支存在） |
+## 归档策略（何时迁入 `archive/`）
+
+满足以下**多数**条件时可归档：
+
+1. 对应能力已在 `src/` 落地，且有 `docs/exec-plans/completed/*` 或 dated report / CHANGELOG 版本说明；
+2. 文档主体是**阶段性计划 / 月度 WBS / 已关闭路线图**，不再驱动实现决策；
+3. 继续放在 design 根目录会让新人误判为「未做完」或「下一件必做」。
+
+**不要归档**（仍放根目录）：
+
+- 仍被代码/CLI/映射表**持续引用**的契约（taxonomy、taskspec mapping、frontend workflow 等）；
+- 仍有 **active exec-plan** 或大段 **planned/deferred** 的设计真源（如 Eval Lab）；
+- 长期路线与方法论笔记（六个月规划、腾讯实践、研发模式）——可加校准条，不必塞进 archive；
+- 纯视觉 token 参考（`DESIGN-*.md`）。
+
+---
+
+## 契约与实现映射（优先读 · 仍活）
+
+| 文档 | 用途 | 归档建议 |
+|---|---|---|
+| `taskspec-to-loop-agent-mapping.md` / `.yaml` | TaskSpec → loop-agent task 契约 | **保留**（随 schema 更新） |
+| `state-and-failure-taxonomy.md` | 状态 / failure taxonomy | **保留** |
+| `frontend-implementation-workflow.md` | 前端 DAG 实现/评审/验证约定 | **保留**（活工作流） |
+| `full-chain-test-knowledge-base.md` | 测试知识库分层与对象模型 | **保留**（K 族权威设计） |
+| `full-chain-testing-system-redesign.md` | I/T/V/K 综合重设计 | **保留**（后续 T/V 与 hardening 仍可能引用；MVP 已部分 ship） |
+| `testing-knowledge-base-impl-spec.md` | 知识库实现细节 v1 | **保留**（规格冻结；DAG 细节另文） |
+| `knowledge-graph-and-query-spec.md` | 图谱 + 查询协议 v1 | **保留**（Phase A 已实现，规格仍真源） |
+| `knowledge-graph-ai-bootstrap.md` | AI bootstrap B0–B6 / staging | **保留**（bootstrap MVP 已实现，增量/产品化仍引用） |
+
+**执行 Contract（knowledge 已完成归档）：** `docs/exec-plans/completed/2026-07-14-knowledge-sync-and-graph.md`
+
+---
+
+## 实验 / 评测（设计输入 · 进行中）
+
+| 文档 | 用途 | 归档建议 |
+|---|---|---|
+| `recursive-self-improvement-eval-lab.md` | Harness Eval Lab 设计真源 | **保留 active**：M1 + M2 W2.1–W2.3 已实现；W2.4 / M3+ 未做。执行计划：`docs/exec-plans/active/2026-07-16-recursive-self-improvement-eval-lab.md` |
+
+> 设计 README 旧句「W2.3 仍未实现」已过时：W2.3 run association **已合入**（见 active plan 进度与 `CHANGELOG.md [Unreleased]`）。
+
+---
+
+## 路线与产品线笔记（非实现证明 · 保留 + 校准条）
+
+| 文档 | 用途 | 归档建议 |
+|---|---|---|
+| `dynamic-workflow-dag-engine-roadmap.md` | Dynamic Workflow 阶段规划 | **保留**：页首有落地校准；高风险 shard/merge 等仍是 roadmap |
+| `六个月规划.md` | 长期路线 | **保留**：页首 **2026-07-16** 已补 0.12.0 / Task Pool v2 / Ready Planner / Eval 指针；第 3–6 月仍有效前瞻 |
+| `产品线共享知识库.md` | 产品线文档仓库上游事实源 | **保留**（docs-sync 等仍多为未来） |
+| `研发模式.md` | 10 日 Feature 团队工作流 | **保留**（方法论） |
+| `腾讯实践对当前项目的指引.md` | 外部实践映射 | **保留**（背景；源文在 website practices） |
+
+---
+
+## 视觉参考（保留）
+
+| 文档 | 用途 | 归档建议 |
+|---|---|---|
+| `DESIGN-cursor.md` | Observe 暖白 / Cursor 风格 token | **保留**（视觉参考） |
+| `DESIGN-lovable.md` | Lovable 暖色视觉参考 | **保留** |
+
+---
+
+## 本次已迁入 `archive/`（2026-07-16）
+
+| 文档 | 原因 |
+|---|---|
+| `archive/2026-07-14-loop-agent-self-update-notifier.md` | 自更新提醒 **已实现**（0.11.0 + report/completed plan）；设计不再是「尚未实现」 |
+| `archive/2026-07-16-priority-ready-planner-contract.md` | Ready Planner **已实现并 closeout**；原 M0 RED「未实现」状态条会误导 |
+
+---
+
+## 已归档（历史）
+
+| 文档 | 用途 |
+|---|---|
+| `archive/2026-07-07-agent-worker-plan.md` | Worker 落地计划（已实现于 `src/worker/`） |
+| `archive/2026-07-07-taskspec-plan.md` | TaskSpec v0.1 设计（已实现） |
+| `archive/2026-07-10-下一阶段任务-功能开发完成.md` | 样本/失败硬化完成记录 |
+| `archive/2026-07-10-observe-ui.md` | Observe UI v0（OBS-001～010） |
+| `archive/2026-07-10-observe-ui-optimization.md` | 中文 DAG-first / 过程时间线 |
+| `archive/2026-07-10-observe-ui-goal.md` | OBS 进度看板（全部 done） |
+| `archive/2026-07-14-observe-ui-roadmap.md` | Observe R1–R5 路线图（已完成） |
+| `archive/2026-07-11-第一月规划.md` / `第一月wbs.md` | 首月闭环历史 |
+| `archive/2026-07-12-第二月规划.md` | 第二月 Feature 闭环历史 |
+| `archive/2026-07-14-loop-agent-self-update-notifier.md` | CLI 自更新提醒设计（已实现） |
+| `archive/2026-07-16-priority-ready-planner-contract.md` | Ready Planner M0 合同（已实现） |
+
+---
+
+## 根目录文件 — 归档建议一览（2026-07-16）
+
+| 文件 | 建议 | 说明 |
+|---|---|---|
+| `README.md` | 保留 | 本索引 |
+| `taskspec-to-loop-agent-mapping.*` | 保留 | 活契约 |
+| `state-and-failure-taxonomy.md` | 保留 | 活契约 |
+| `frontend-implementation-workflow.md` | 保留 | 活工作流 |
+| `full-chain-test-knowledge-base.md` | 保留 | K 族设计真源 |
+| `full-chain-testing-system-redesign.md` | 保留（可选日后拆「已落地摘要」） | 综合草案；部分已 ship |
+| `testing-knowledge-base-impl-spec.md` | 保留 | 规格冻结 |
+| `knowledge-graph-and-query-spec.md` | 保留 | 协议真源 |
+| `knowledge-graph-ai-bootstrap.md` | 保留 | bootstrap 设计真源 |
+| `recursive-self-improvement-eval-lab.md` | **保留 active** | Eval Lab 真源 |
+| `dynamic-workflow-dag-engine-roadmap.md` | 保留 | roadmap + 校准 |
+| `六个月规划.md` | 保留 | 路线；校准条已含 0.12 / Unreleased |
+| `产品线共享知识库.md` | 保留 | 上游知识库愿景 |
+| `研发模式.md` | 保留 | 方法论 |
+| `腾讯实践对当前项目的指引.md` | 保留 | 实践映射 |
+| `DESIGN-cursor.md` / `DESIGN-lovable.md` | 保留 | 视觉 |
+| ~~`2026-07-14-loop-agent-self-update-notifier.md`~~ | **已归档** | 见上 |
+| ~~`2026-07-16-priority-ready-planner-contract.md`~~ | **已归档** | 见上 |
+
+### 暂不建议归档（但可标注「部分落地」）
+
+- **knowledge 四件套 + full-chain\***：exec-plan 已 complete，但设计文仍是目录/schema/增量协议的权威；归档会切断引用习惯。若未来拆出「实现状态」短页，可把**纯进度段落**迁 archive，规格正文仍留根。
+- **六个月规划 / Dynamic Workflow roadmap**：含未来月与未完成 primitive；只做页首校准，整篇归档会丢前瞻。
+
+---
+
+## 命名约定（2026-07-09 起）
+
+| 名称 | 含义 | 状态 |
+|---|---|---|
+| `loop-agent` | 仓库本地 runtime / 治理控制器 CLI | 已发布 |
+| `agent-worker` | 产品线 TaskSpec 批处理适配层 CLI | 已发布 |
+| `agent-platform` | 早期规划设想名；**不是**当前 CLI | 仅未来 monorepo/上层服务语境 |
+
+```text
+产品线 docs / TaskSpec / TaskGraph
+  → agent-worker（本地批处理适配）
+    → loop-agent（runtime kernel）
+      → Pi（受治理 Agent） / shell / static
+      → cursor-prompt（显式手工 one-shot sidecar，非受治理 writer）
+```
+
+## 维护规则
+
+1. 保持 TaskSpec 字段、status、failure category、命令示例与契约文档一致。
+2. 未来平台组件标为目标架构，除非已存在于 `src/` 或 `scripts/`。
+3. 命令示例只用 `agent-worker` / `loop-agent`。
+4. `config-types` / profile routing 变更时更新 mapping 文档。
+5. failure / Task Pool state 变更时更新 taxonomy。
+6. **过期月规划 / 已关闭实现合同**迁入 `archive/`，并更新本 README。
+7. 运行 `bash scripts/check-repo.sh`（或至少 check-doc-index / check-doc-links）。