@tea-agent/loop-agent 0.12.0 → 0.13.0-alpha.0

package/dist/workflows/dag/types.js

@@ -217,6 +217,7 @@ export const dagConvergenceSpecSchema = z
     stopOnVerdictPass: z.boolean().optional().default(true),
     stopOnHardVerifyPass: z.boolean().optional().default(true),
     pauseOnRegression: z.boolean().optional().default(true),
+    chainNodeIds: z.array(z.string()).optional(),
 })
     .optional();
 export const dagTaskSchema = z.object({

package/docs/README.md

@@ -55,7 +55,7 @@
 - `exec-plans/completed/README.md` — 已完成的执行计划（全量）
 - `progress/README.md` — 进度交接日志（全量）
 - `reports/README.md` — 验证与审计报告（全量）；活能力摘要见 `reports/current-capability-summary.md`
-- `decisions/README.md` — 架构决策（ADR 0001–0003）
+- `decisions/README.md` — 架构决策（ADR 0001–0004；0004 = Task Pool feature-scoped identity）
 - `skills/README.md` — repo-local skill registry and vetting notes
 - `templates/` — 可复用的规划、报告与 DAG 模板
 

package/docs/agent-dag-recovery-playbook.md

@@ -17,6 +17,15 @@ recommended_follow_up
 
 Product-line taxonomy 定义见 `docs/design/state-and-failure-taxonomy.md`。
 
+### 前端设计门禁专用恢复路径
+
+前端 DAG 的 design gate shell 失败（`frontend-first-design-gate-shell`、`frontend-final-design-gate-shell`、`frontend-design-gate-shell`）**不路由为 `ProductBug` / `dev-fix`**。此类失败固定路由为：
+
+- `productLineFailureCategory`: `ContractMismatch`
+- `recommendedFollowUp`: `frontend-plan-revision-and-rerun`
+
+恢复动作由 `planDagRecovery` 根据实际的 `normalizedFailureCategory` 和 run status 决定（通常为 `rerun-after-fix` 或 `manual-review`），但 product-line 维度的分类确保 Task Pool 和 morning report 不会将其混入普通 bug backlog。
+
 **非目标（本 playbook 不覆盖、runner 不实现）：**
 
 - 自动 retry / resume 节点执行

package/docs/architecture/evolution.md

@@ -1,6 +1,6 @@
 # 架构演进：当前 vs 未来
 
-本页区分 loop-agent **当前已实现**的架构能力与**未来规划**。当前事实以代码、发布 CLI、已完成计划为准；未来能力一律标「规划 / 未实现 / 前瞻」。权威源：`CHANGELOG.md`、`docs/reports/current-capability-summary.md`、ADR 0001–0003、`docs/exec-plans/completed/`。
+本页区分 loop-agent **当前已实现**的架构能力与**未来规划**。当前事实以代码、发布 CLI、已完成计划为准；未来能力一律标「规划 / 未实现 / 前瞻」。权威源：`CHANGELOG.md`、`docs/reports/current-capability-summary.md`、ADR 0001–0004、`docs/exec-plans/completed/` 与 active identity plan 的 progress。
 
 ## 当前已实现（0.11.0）
 
@@ -11,8 +11,9 @@
 | Dynamic Workflow | `WorkflowSpec` → validate → compile → 同一 `run-dag`；agent-like 节点仅 `pi\|static` | `src/workflows/dynamic/{spec,validate,compile}.ts`、`website/docs/guides/dynamic-workflow.md` |
 | 版本化自举 | controller identity + run-owned skill snapshot + deterministic canary | `docs/reports/2026-07-13-versioned-self-hosting-bootstrap.md` |
 | Feature 交付（M2） | review/run/approve-followup/delivery/closeout/verify-final | `docs/reports/2026-07-12-m2-completion-audit.md` |
-| Task Pool | 唯一根 `.harness/task-pool/` | ADR 0002 |
-| Observe | 本地只读暖白运营控制台 R1–R5（derived） | `website/docs/guides/observe-ui.md`、`CHANGELOG.md [0.11.0]` |
+| Task Pool | 唯一根 `.harness/task-pool/`；**feature-scoped** state v2（`TaskPoolTaskRef`） | ADR 0002、ADR 0004 |
+| 本地多 Feature 运营 | 同仓库多 Feature 可共用 Task ID；Ready / retry / Delivery / Observe 按 Feature 隔离 | ADR 0004、`docs/progress/2026-07-15-task-pool-v2-feature-scoped-task-identity.md` |
+| Observe | 本地只读暖白运营控制台 R1–R5（derived）；canonical Task route 为 feature-scoped | `website/docs/guides/observe-ui.md`、`CHANGELOG.md [0.11.0]`、ADR 0004 |
 | DagSpec / repair | v3 + `runtimeContract`；显式 `repairNodeId` | `CHANGELOG.md [0.11.0]`、`dag-execution.md` |
 | 文档双树 | `website/docs/` 用法 vs `docs/` 治理；docs-converge | ADR 0003 |
 | 文档治理 | `docs/architecture/` 主题文档（本目录）+ package 可达 | 本目录 README |

package/docs/architecture/facts-and-state.md

@@ -10,7 +10,7 @@
 | DAG run | `.harness/dag-runs/{active,paused,completed}/<runId>/` | `src/workflows/dag/lifecycle.ts` `DAG_RUNS_DIR` | canonical，active/paused 可写；completed 受 guard |
 | one-shot run | `.harness/runs/{active,completed,failed}/<slug>/` | `src/infrastructure/harness/one-shot-run-store.ts`（逻辑封装见 `src/records/one-shot-runs.ts`） | canonical；active 可写，completed/failed 为终态事实 |
 | Loop | `.harness/tasks/<taskId>/loop/` | `src/workflows/loop/**` | canonical，**不是独立根**，是 task 之上的多轮状态机 |
-| Task Pool | `.harness/task-pool/`（唯一根） | `src/worker/pool/run-store.ts` `TASK_POOL_RELATIVE_ROOT`（ADR 0002） | canonical，可写（Worker 专用，可选） |
+| Task Pool | `.harness/task-pool/`（唯一根；state v2 见下） | `src/worker/pool/run-store.ts` `TASK_POOL_RELATIVE_ROOT`（ADR 0002 / 0004） | canonical，可写（Worker 专用，可选） |
 | Observe snapshot | Worker 内存/HTTP 派生视图 | `src/worker/observability/read-model.ts` `buildGlobalSnapshot` | **derived**，advisory |
 
 ### 区分要点
@@ -19,8 +19,21 @@
 - **DAG run vs one-shot run**：DAG run 在 `.harness/dag-runs/`，有三态 lifecycle；one-shot run（当前主要由 `cursor-prompt` 及显式 one-shot evidence 路径产生）在 `.harness/runs/`，三态为 `active|completed|failed`。`pi-prompt` 当前不创建该目录下的 run evidence。两者是不同根、不同 schema。
 - **Loop 不是顶层根**：Loop 状态在 `.harness/tasks/<taskId>/loop/`，是 task 之上的多轮状态机（round、signal、context、failureStreak、closeout）。
 - **Task Pool 是 Worker 专用可选根**：只有使用 `agent-worker` 产品线时才存在；唯一根 `.harness/task-pool/`。
+- **Task Pool state identity（ADR 0004）**：canonical 键为 `{ featureId, taskId }`（`TaskPoolTaskRef`），不是裸 `taskId`。
 - **Observe snapshot 不是事实源**：`buildGlobalSnapshot` 投影失败返回安全错误摘要而非全零健康，不改变执行成败。
 
+### Task Pool state 布局与迁移
+
+| 路径 / 对象 | 性质 | 说明 |
+| --- | --- | --- |
+| `.harness/task-pool/states/<featureId>/<taskId>.json` | canonical 可写 | schema v2；路径解码 identity 必须与文件内容一致 |
+| `.harness/task-pool/states/<taskId>.json`（扁平 v1） | legacy | 不得静默猜 Feature；存在时 v2 写入 fail-closed |
+| `.harness/task-pool/runs.jsonl` / `events.jsonl` | canonical append-only | migration 不改写 JSONL；`workerRunId` 仍是执行历史键 |
+| `agent-worker pool doctor` | 只读诊断 | inventory + mapping 证据；exit 0 可有 findings |
+| `agent-worker pool migrate-state` | 显式迁移 | 默认 dry-run；`--apply --owner --reason` 才写入；失败全回滚 |
+
+`readFeatureTaskPoolStates` / `listTaskPoolStates` 是 v2 列表入口；deprecated `readAllTaskPoolStates` 仅扫描 legacy 扁平 state，不合并 v2。
+
 ## canonical（可写）
 
 - `.harness/tasks/<taskId>/` — `getTaskDir`。

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

@@ -54,8 +54,12 @@ controller identity 与 DAG skill snapshot 是两个不同冻结层（前者跨
 
 - 唯一 runtime root：`src/worker/pool/run-store.ts`
   `TASK_POOL_RELATIVE_ROOT = ".harness/task-pool"`（ADR 0002）。
-- 旧顶层路径不读取、不迁移、不合并、不重映射。
-- batch/retry/morning report 等都基于此根。
+- 此前的顶层 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 交付闭环）
 

package/docs/decisions/README.md

@@ -9,6 +9,9 @@
 | [`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/`。
 

package/docs/design/README.md

@@ -10,6 +10,14 @@
 | `taskspec-to-loop-agent-mapping.yaml` | 同上契约的结构化对照表 |
 | `state-and-failure-taxonomy.md` | 文档、Task Pool、DAG、Loop 共用的 canonical status 与 failure taxonomy |
 | `frontend-implementation-workflow.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 设计（若分支存在） |
+
+**执行 Contract（进行中）：** `docs/exec-plans/active/2026-07-14-knowledge-sync-and-graph.md` · PRD/issues：`.scratch/knowledge-sync-and-graph/` |
 
 ## 路线与产品线笔记（非实现证明）
 

package/docs/exec-plans/active/README.md

@@ -6,4 +6,6 @@
 
 当前 active execution plan：
 
+- [`2026-07-14-knowledge-sync-and-graph.md`](2026-07-14-knowledge-sync-and-graph.md) — 知识库同步 DAG（测试结论/用例/缺陷写回）+ 业务知识图谱开荒与持续更新；Contract：`.scratch/knowledge-sync-and-graph/PRD.md`
+
 - 已归档：`../completed/2026-07-15-repair-artifact-gate-runtime-contract.md`、`../completed/2026-07-14-observe-ui-r5.md`、`../completed/2026-07-14-observe-ui-r4.md`、`../completed/2026-07-14-observe-ui-r3.md`、`../completed/2026-07-14-observe-ui-r2.md`、`../completed/2026-07-14-observe-ui-r1.md`、`../completed/2026-07-14-init-canonical-layout.md`、`../completed/2026-07-12-observe-warm-console-redesign.md`、`../completed/2026-07-14-website-docs-ia-and-converge.md`、`../completed/2026-07-13-versioned-self-hosting-bootstrap.md`、`../completed/2026-07-12-pi-only-agent-runtime.md`、第二月 M2-01～M2-08、`../completed/2026-07-11-observe-dashboard-page-system.md`、`../completed/2026-07-11-observe-dashboard-detail-refinement.md`、`../completed/2026-07-11-observe-terminal-dag-kpi.md`、`../completed/2026-07-11-observe-polling-efficiency.md`、`../completed/2026-07-11-command-performance-guardrails.md` 及更早计划。

package/docs/exec-plans/completed/README.md

@@ -68,6 +68,7 @@ npm 包携带本 README 作为目录契约。具体 completed plan 属于目标
 
 - [`2026-07-13-exec-plan-lifecycle.md`](2026-07-13-exec-plan-lifecycle.md)
 
-- [`2026-07-15-readonly-node-retry.md`](2026-07-15-readonly-node-retry.md)
-
+- [`2026-07-15-task-pool-priority-aware-ready-planner.md`](2026-07-15-task-pool-priority-aware-ready-planner.md)
+- [`2026-07-15-task-pool-v2-feature-scoped-task-identity.md`](2026-07-15-task-pool-v2-feature-scoped-task-identity.md)
 - [`2026-07-15-init-update-surface-coverage.md`](2026-07-15-init-update-surface-coverage.md)
+- [`2026-07-15-readonly-node-retry.md`](2026-07-15-readonly-node-retry.md)

package/docs/feature-workflow.md

@@ -111,7 +111,10 @@ frontend-contract-pi
   -> frontend-scout-pi
   -> frontend-plan-pi
   -> frontend-design-gate-pi
-  -> frontend-design-gate-shell
+  -> frontend-first-design-gate-shell
+  -> frontend-plan-revision-pi
+  -> frontend-final-design-review-pi
+  -> frontend-final-design-gate-shell
   -> frontend-implement-pi
   -> frontend-static-verify-shell
   -> frontend-behavior-verify-shell
@@ -120,7 +123,9 @@ frontend-contract-pi
   -> frontend-closeout-pi
 ```
 
-这条链在实现前加入 design gate，并将前端静态验证与行为验证分开建模；当前 MVP 不包含独立 a11y、视觉回归或浏览器自动化 executor。
+这条链在实现前加入两阶段 design gate：首轮 design review 同时接受 `VERDICT: pass` 和 `VERDICT: request-revision`，request-revision 时由只读 `frontend-plan-revision-pi` 消费原计划与 design findings 完成修订，再经 `frontend-final-design-review-pi` 和 `frontend-final-design-gate-shell` 最终门禁；只有最终 `VERDICT: pass` 才授权写入。design gate 失败路由为 `ContractMismatch` / `frontend-plan-revision-and-rerun`，不路由为 `ProductBug` / `dev-fix`。
+
+这条链还将前端静态验证与行为验证分开建模；当前 MVP 不包含独立 a11y、视觉回归或浏览器自动化 executor。
 
 后端测试任务可通过 `task.json.taskKind = "backend-test"` 选择专用模板；它不新增 governance profile：
 
@@ -144,6 +149,79 @@ analyze-inputs-pi
 6. **execute-backend-pytest-shell**：执行 `pytest testcase/` 并生成 HTML 报告
 7. **test-retrospect-pi**：读取上游审查报告和测试报告，生成复盘报告 + 成熟度评级（A/B/C/D）
 
+最终验证后的知识库回写可通过 `task.json.taskKind = "knowledge-sync"` 选择专用模板（与 `backend-test` 一样走 taskKind 路由，不占用 governance `--profile`）。
+
+**必须绑定 `featureId`**（fail-closed）。解析顺序：`task.json.featureId` → `hardConstraints` 中 `featureId=F-…` → 需求正文中的 `F-YYYY-NNN` → 若 `taskId` 本身是 `F-*`。生成器会把 writeSet 收窄到 `features/<featureId>/…`，validate 只检查该 Feature 下的 draft。
+
+```json
+{
+  "taskKind": "knowledge-sync",
+  "featureId": "F-2026-004"
+}
+```
+
+```text
+knowledge-sync-collect-pi
+  -> knowledge-sync-draft-pi
+  -> knowledge-sync-validate-shell
+  -> knowledge-sync-apply-pi
+  -> knowledge-sync-pointer-pi
+```
+
+这条链在 shell 最终验证证据之后，把稳定事实写入 Feature 测试知识库（L1），而不是把 `.harness` 大日志搬进 docs：
+
+1. **knowledge-sync-collect-pi**：只读汇总 final verification / AC / 用例 / 缺陷 / 需求 delta 候选
+2. **knowledge-sync-draft-pi**：写入 `features/<featureId>/testing/sync/pending/knowledge-sync-draft.json`
+3. **knowledge-sync-validate-shell**：校验该路径 draft 的 schema、`featureId` 一致、operations 目标路径、finalVerification 门禁
+4. **knowledge-sync-apply-pi**：仅在 `features/<featureId>/testing/**`（及该 Feature 的 `requirement-delta.md`、`docs/test-reports/**`）受控回写
+5. **knowledge-sync-pointer-pi**：写 `features/<featureId>/testing/runs/latest.md` 与 `sync/applied/KS-*.json`
+
+设计说明见 `docs/design/full-chain-test-knowledge-base.md` §11；JSON 示例见 `docs/templates/knowledge-sync-dag.json`。
+
+业务知识图谱**初始化**可通过 `task.json.taskKind = "knowledge-graph-bootstrap"` 选择专用模板。跑前先落 B1 骨架：
+
+```bash
+bash scripts/kb-bootstrap-init-skeleton.sh --root .
+# 编辑 knowledge/bootstrap/scope.yaml 后再 run-task
+```
+
+（需有 `knowledge/bootstrap/scope.yaml` 与 `status.yaml`；脚本幂等，默认不覆盖已有 scope/status，可用 `--force`。）
+
+图谱索引与 Phase A 查询（脚本，非 RAG）：
+
+```bash
+bash scripts/kb-graph-materialize.sh --root .
+bash scripts/kb-query.sh --mode by_feature --feature F-2026-004 --json
+bash scripts/kb-query.sh --mode by_id --id SVC-order --json
+bash scripts/kb-query.sh --mode search --text "预占" --json
+```
+
+**增量更新（非全量开荒）**：缩小 scope 后复用同一 `knowledge-graph-bootstrap` DAG（propose 仅针对 seeds/includes；promote 仍默认不覆盖已有正式文件）：
+
+```bash
+bash scripts/kb-graph-incremental-prepare.sh --root . \
+  --feature F-2026-004 --service order [--reset-staging]
+# 审阅 knowledge/bootstrap/scope.yaml（update_mode: incremental）
+# task.json.taskKind = "knowledge-graph-bootstrap"
+loop-agent dag run-task <id>
+bash scripts/kb-graph-materialize.sh --root .
+```
+
+测试知识日常写回仍用 `knowledge-sync`（`featureId` 必填），与图谱增量入口分离。
+
+```text
+kg-bootstrap-preflight-shell
+  -> kg-bootstrap-inventory-shell
+  -> kg-bootstrap-propose-pi
+  -> kg-bootstrap-validate-shell
+  -> kg-bootstrap-review-pi
+  -> kg-bootstrap-review-gate-shell
+  -> kg-bootstrap-promote-shell
+  -> kg-bootstrap-materialize-shell
+```
+
+AI 只写 `knowledge/bootstrap/staging/**`；禁止 self-`asserted`；review-gate 通过后 promote 仅合并新文件；materialize 写 `knowledge/graph/` 索引。设计见 `docs/design/knowledge-graph-ai-bootstrap.md`，示意 JSON 见 `docs/templates/knowledge-graph-bootstrap-dag.json`。
+
 前端测试模板（`frontend-test-dag`）后续沿用对称命名即可接入。
 前端 shell 验证优先使用任务源 `需求.md` / `执行约束.md` 中声明的前端验证命令，例如 `npm run typecheck`、`npm run build`、`npm test`；解析不到时再使用 adapter 验证命令和模板 fallback。
 

package/docs/loop-agent-harness.md

@@ -10,6 +10,7 @@ loop-agent 提供结构化 agent 工作的本地 harness。
 - `.harness/cache/` — 本地 runtime 缓存
 - `.harness/live/` — 瞬态 live-session 文件
 - `.harness/task-pool/` — `agent-worker` 的 Task Pool state、batch artifacts、failure handoffs 与 Observe events；它是 `.harness/` 内的独立 Worker runtime root，默认不提交
+- `.harness/task-pool/states/<featureId>/<taskId>.json` — Task Pool schema v2 的 canonical state（ADR 0004）；复合身份 `TaskPoolTaskRef = { featureId, taskId }`。扁平 `states/<taskId>.json` 为 legacy，不得静默解释
 - `.harness/dag-runs/<lifecycle>/<run-id>/.runtime/skill-snapshot.json` — 该 run 实际使用的 resolved skill profile snapshot；由 state 中相对 ref 与原始 bytes SHA-256 锚定，随 lifecycle 目录整体迁移
 
 ## Skill 指令
@@ -71,7 +72,7 @@ DAG agent 节点的输出语言由 `harness.json.workflowPolicy.dag.outputLangua
 - `loop init`、`loop run`、`loop status`、`loop closeout`
 - `pi-prompt`、`cursor-prompt`
 - `handoff check`、`spine audit`、`knowledge curate`
-- `agent-worker feature review|run|verify-final|delivery|closeout|approve-followup`、`agent-worker task validate|explain-profile|retry|draft-followup`、`agent-worker batch run-ready`、`agent-worker report morning|metrics`、`agent-worker observe serve|snapshot`
+- `agent-worker feature review|run|verify-final|delivery|closeout|approve-followup`、`agent-worker task validate|explain-profile|retry|draft-followup`、`agent-worker batch run-ready`、`agent-worker pool doctor|migrate-state`、`agent-worker report morning|metrics`、`agent-worker observe serve|snapshot`
 
 `dag run-task` 在生成 DAG 草稿前会运行与 `plan check` 同源的 exec-plan 索引校验；active plan 与 `docs/exec-plans/active/README.md` 索引不一致时立即失败，避免运行昂贵节点后才在末端 shell verify 发现。`plan create` 优先复用目标项目模板并回退到发布包内置 `docs/templates/exec-plan.md`，`plan create`/`plan complete` 的多文件写入均有回滚保护；`new-task` 不自动绑定 exec-plan。
 
@@ -112,14 +113,24 @@ canary 会记录 tarball SHA-256、slot containment、两个 bin identity、由
 
 ## Worker Retry
 
-失败 Task Pool task 必须显式 retry，不能删除 `.harness/task-pool/runs.jsonl` 或复用失败的 `workerRunId`：
+失败 Task Pool task 必须显式 retry，不能删除 `.harness/task-pool/runs.jsonl` 或复用失败的 `workerRunId`。canonical 命令必须携带 Feature：
 
 ```bash
-agent-worker task retry <task-id> --repo <target-repo> --reason "provider configuration corrected"
+agent-worker task retry <task-id> --feature-id <feature-id> --repo <target-repo> --reason "provider configuration corrected"
 agent-worker batch run-ready --feature-dir <feature-dir> --repo <target-repo>
 ```
 
-`task retry` 只接受 `Failed` state，保留旧 run 和 failure handoff，并写入 `retryOfWorkerRunId`。下一次 `run-ready` 生成新的 `workerRunId`；`Blocked`、`Done` 或无 state 的 task 必须先由 operator 处理根因，不能盲目重试。
+`task retry` 只接受指定 Feature 下的 `Failed` state，保留旧 run 和 failure handoff，并写入 `retryOfWorkerRunId`。跨 Feature 同名 Task 时省略 `--feature-id` 必须 fail-closed。下一次 `run-ready` 生成新的 `workerRunId`；`Blocked`、`Done` 或无 state 的 task 必须先由 operator 处理根因，不能盲目重试。
+
+## Task Pool Doctor 与 State 迁移
+
+```bash
+agent-worker pool doctor --repo <target-repo> --json
+agent-worker pool migrate-state --repo <target-repo>            # dry-run 默认
+agent-worker pool migrate-state --repo <target-repo> --apply --owner <owner> --reason <reason>
+```
+
+`pool doctor` 只读扫描 v2 / legacy inventory 与映射证据，exit 0 也可带 findings。`pool migrate-state` 默认零写入；apply 需要 `--owner` 与 `--reason`，保留 bytes/hash 审计 artifact，失败全回滚，且不改写 `runs.jsonl` / `events.jsonl`。
 
 ## 验证 Preset
 

package/docs/progress/README.md

@@ -6,6 +6,8 @@
 
 ## 近期要点（导读）
 
+- [`2026-07-16-ready-planner.md`](2026-07-16-ready-planner.md) — Priority-aware Ready Planner：M1 core + RP-02 Feature/report/Observe 同源投影（已验证）
+- [`2026-07-15-task-pool-v2-feature-scoped-task-identity.md`](2026-07-15-task-pool-v2-feature-scoped-task-identity.md) — Task Pool v2 复合身份：M1 store + M2 consumers + M3 Observe + M4 文档收口（已归档 completed）
 - [`2026-07-15-init-update-surface-coverage.md`](2026-07-15-init-update-surface-coverage.md) — 修复初始化 surface 升级漏检（自动发现 copied 文件、blockedTargetPaths fail-safe、drift gate）实施交接（已验证）
 - [`2026-07-15-readonly-node-retry.md`](2026-07-15-readonly-node-retry.md) — 只读 Pi DAG 节点安全重试（默认策略、attempt 证据、validation 门禁）实施交接（已验证）
 - [`2026-07-15-repair-artifact-gate-runtime-contract-implementation.md`](2026-07-15-repair-artifact-gate-runtime-contract-implementation.md) — 显式 repairNodeId、runtime contract preflight 与 run-owned controller identity 实施交接（已验证）
@@ -27,6 +29,8 @@
 
 ## 全量列表（新→旧）
 
+- [`2026-07-16-ready-planner.md`](2026-07-16-ready-planner.md)
+- [`2026-07-15-task-pool-v2-feature-scoped-task-identity.md`](2026-07-15-task-pool-v2-feature-scoped-task-identity.md)
 - [`2026-07-15-init-update-surface-coverage.md`](2026-07-15-init-update-surface-coverage.md)
 - [`2026-07-15-readonly-node-retry.md`](2026-07-15-readonly-node-retry.md)
 - [`2026-07-15-repair-artifact-gate-runtime-contract-implementation.md`](2026-07-15-repair-artifact-gate-runtime-contract-implementation.md)

package/docs/reports/README.md

@@ -13,6 +13,9 @@
 ## 近期要点（导读，非权威全集）
 
 - [`current-capability-summary.md`](current-capability-summary.md) — **活**能力摘要（新进展写这里 / CHANGELOG / 新 report）
+- [`2026-07-16-task-pool-priority-aware-ready-planner.md`](2026-07-16-task-pool-priority-aware-ready-planner.md) — Priority-aware Ready Planner 关闭报告
+- [`2026-07-15-task-pool-v2-feature-scoped-task-identity.md`](2026-07-15-task-pool-v2-feature-scoped-task-identity.md) — Task Pool v2 复合身份 M0–M4 最终报告
+- [`2026-07-15-task-pool-v2-init-evolution-review.md`](2026-07-15-task-pool-v2-init-evolution-review.md) — Task Pool v2 文档变更的 init surface 非影响审查
 - [`2026-07-15-init-update-surface-coverage-init-evolution-review.md`](2026-07-15-init-update-surface-coverage-init-evolution-review.md) — 初始化 surface 升级漏检修复的 init surface 审查（init update required）
 - [`2026-07-15-readonly-node-retry-init-evolution-review.md`](2026-07-15-readonly-node-retry-init-evolution-review.md) — 只读 Pi DAG 节点安全重试的 init surface 审查（surface check only，无需 init evolution）
 - [`2026-07-15-backend-test-dag-init-evolution-review.md`](2026-07-15-backend-test-dag-init-evolution-review.md) — 后端测试专用 DAG 的 package/init surface 审查
@@ -28,6 +31,9 @@
 
 ## 全量列表（新→旧）
 
+- [`2026-07-16-task-pool-priority-aware-ready-planner.md`](2026-07-16-task-pool-priority-aware-ready-planner.md)
+- [`2026-07-15-task-pool-v2-feature-scoped-task-identity.md`](2026-07-15-task-pool-v2-feature-scoped-task-identity.md)
+- [`2026-07-15-task-pool-v2-init-evolution-review.md`](2026-07-15-task-pool-v2-init-evolution-review.md)
 - [`2026-07-15-init-update-surface-coverage-init-evolution-review.md`](2026-07-15-init-update-surface-coverage-init-evolution-review.md)
 - [`2026-07-15-readonly-node-retry-init-evolution-review.md`](2026-07-15-readonly-node-retry-init-evolution-review.md)
 - [`2026-07-15-backend-test-dag-init-evolution-review.md`](2026-07-15-backend-test-dag-init-evolution-review.md)

package/docs/templates/backend-test-dag.json

@@ -37,6 +37,18 @@
     "Actual file operation paths must be macOS/Windows compatible; use / only for stable repo refs, JSON/Markdown evidence refs, and glob conventions.",
     "Same-rank exclusive writeSet entries must be disjoint."
   ],
+  "convergence": {
+    "enabled": true,
+    "maxPasses": 3,
+    "stopOnVerdictPass": true,
+    "stopOnHardVerifyPass": true,
+    "pauseOnRegression": true,
+    "chainNodeIds": [
+      "generate-backend-functional-cases-pi",
+      "review-backend-cases-pi",
+      "review-backend-cases-gate-shell"
+    ]
+  },
   "defaults": {
     "executor": "pi",
     "contextProfile": "slim",

package/docs/templates/knowledge-graph-bootstrap-dag.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "./agent-dag.schema.json",
+  "version": 2,
+  "title": "Knowledge-graph bootstrap DAG template",
+  "objective": "AI-assisted business knowledge graph initialization: inventory repo signals, propose entities/edges under staging only, validate, review-gate, promote without overwrite, materialize query indexes.",
+  "successCriteria": [
+    "preflight requires knowledge/bootstrap/scope.yaml and status.yaml",
+    "inventory writes knowledge/bootstrap/inventory.json",
+    "propose-pi writes only knowledge/bootstrap/staging/** with evidence and non-asserted confidence",
+    "validate-shell fails on empty staging, missing edges.proposed/coverage-notes, or self-asserted confidence",
+    "review-gate blocks promote unless VERDICT: pass",
+    "promote merges new formal files only (no overwrite)",
+    "materialize writes knowledge/graph/entities-index.yaml and edges.yaml"
+  ],
+  "globalConstraints": [
+    "AI must never set confidence: asserted.",
+    "Do not modify src/** or Feature testing verdict/cases via bootstrap.",
+    "Promote must not overwrite existing formal knowledge files.",
+    "Complete B0/B1 skeleton before running this DAG."
+  ],
+  "defaults": {
+    "executor": "shell",
+    "contextProfile": "slim",
+    "writePolicy": "read-only"
+  },
+  "tasks": [
+    {
+      "id": "kg-bootstrap-preflight-shell",
+      "depends_on": [],
+      "role": "verifier",
+      "executor": "shell",
+      "complexity": "LOW",
+      "writePolicy": "read-only",
+      "subtask_prompt": "Require bootstrap skeleton."
+    },
+    {
+      "id": "kg-bootstrap-inventory-shell",
+      "depends_on": ["kg-bootstrap-preflight-shell"],
+      "role": "verifier",
+      "executor": "shell",
+      "complexity": "LOW",
+      "writePolicy": "exclusive",
+      "writeSet": ["knowledge/bootstrap/inventory.json"],
+      "subtask_prompt": "B2 inventory."
+    },
+    {
+      "id": "kg-bootstrap-propose-pi",
+      "depends_on": ["kg-bootstrap-inventory-shell"],
+      "role": "implementer",
+      "executor": "pi",
+      "toolProfile": "write",
+      "complexity": "HIGH",
+      "writePolicy": "exclusive",
+      "writeSet": [
+        "knowledge/bootstrap/staging/**",
+        "knowledge/bootstrap/runs/**"
+      ],
+      "subtask_prompt": "B3 AI proposals in staging only; never asserted."
+    },
+    {
+      "id": "kg-bootstrap-validate-shell",
+      "depends_on": ["kg-bootstrap-propose-pi"],
+      "role": "verifier",
+      "executor": "shell",
+      "complexity": "LOW",
+      "writePolicy": "read-only",
+      "subtask_prompt": "B4 validate staging."
+    },
+    {
+      "id": "kg-bootstrap-review-pi",
+      "depends_on": ["kg-bootstrap-validate-shell"],
+      "role": "reviewer",
+      "executor": "pi",
+      "complexity": "HIGH",
+      "writePolicy": "read-only",
+      "outputContract": "First line VERDICT: pass or VERDICT: request-revision.",
+      "subtask_prompt": "Review staging quality."
+    },
+    {
+      "id": "kg-bootstrap-review-gate-shell",
+      "depends_on": ["kg-bootstrap-review-pi"],
+      "role": "verifier",
+      "executor": "shell",
+      "complexity": "LOW",
+      "writePolicy": "read-only",
+      "subtask_prompt": "Gate on VERDICT: pass."
+    },
+    {
+      "id": "kg-bootstrap-promote-shell",
+      "depends_on": ["kg-bootstrap-review-gate-shell"],
+      "role": "verifier",
+      "executor": "shell",
+      "complexity": "LOW",
+      "writePolicy": "exclusive",
+      "writeSet": [
+        "knowledge/domains/**",
+        "knowledge/services/**",
+        "knowledge/modules/**",
+        "knowledge/graph/edges.manual.yaml",
+        "features/**/knowledge-links.yaml"
+      ],
+      "subtask_prompt": "B5 promote new files only."
+    },
+    {
+      "id": "kg-bootstrap-materialize-shell",
+      "depends_on": ["kg-bootstrap-promote-shell"],
+      "role": "closeout",
+      "executor": "shell",
+      "complexity": "LOW",
+      "writePolicy": "exclusive",
+      "writeSet": [
+        "knowledge/graph/entities-index.yaml",
+        "knowledge/graph/edges.yaml"
+      ],
+      "subtask_prompt": "B6 materialize indexes."
+    }
+  ]
+}