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

package/dist/workflows/dag/types.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { assertDagPromptSourceRule } from "./prompt-source.js";
+import { dagRetryPolicySchema } from "./retry-policy.js";
 export const dagComplexitySchema = z.enum(["HIGH", "MED", "LOW"]);
 export const dagNodeExecutorSchema = z.enum([
     "pi",
@@ -33,6 +34,32 @@ export const dagRepairArtifactGateSchema = z.object({
     fromNodeId: z
         .string()
         .regex(/^[a-z][a-z0-9-]*$/, "fromNodeId must be kebab-case"),
+    /**
+     * Explicit reference to the governed Pi repair writer this gate feeds.
+     * New generated supervised DAGs must set this. Legacy DAGs without it are
+     * only accepted when a unique safe downstream Pi writer can be derived.
+     */
+    repairNodeId: z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/, "repairNodeId must be kebab-case")
+        .optional(),
+});
+export const DAG_RUNTIME_CONTRACT_SCHEMA_VERSION = 1;
+export const DAG_AGENT_RUNTIME_PI_ONLY = "pi-only";
+export const DAG_REPAIR_WRITER_PROTOCOL_EXPLICIT_NODE_V1 = "explicit-node-v1";
+export const dagRuntimeContractSchema = z.object({
+    schemaVersion: z.literal(DAG_RUNTIME_CONTRACT_SCHEMA_VERSION),
+    agentRuntime: z.literal(DAG_AGENT_RUNTIME_PI_ONLY),
+    repairWriterProtocol: z.literal(DAG_REPAIR_WRITER_PROTOCOL_EXPLICIT_NODE_V1),
+    /**
+     * Optional minimum controller version for diagnosis / fail-below. Capability
+     * fields above are primary; semver is only used for guidance when the
+     * controller is otherwise compatible.
+     */
+    minimumControllerVersion: z
+        .string()
+        .regex(/^\d+\.\d+\.\d+([-+].+)?$/, "minimumControllerVersion must be semver")
+        .optional(),
 });
 export const dagVerdictGateSchema = z.object({
     fromNodeId: z
@@ -44,7 +71,7 @@ export const dagVerdictGateSchema = z.object({
 });
 export const ENV_VAR_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 export const dagVersionSchema = z
-    .union([z.literal(1), z.literal(2)])
+    .union([z.literal(1), z.literal(2), z.literal(3)])
     .default(1);
 export const dagRoleSchema = z.enum([
     "planner",
@@ -190,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({
@@ -217,6 +245,7 @@ export const dagTaskSchema = z.object({
     allowedPaths: z.array(z.string()).optional().default([]),
     forbiddenPaths: z.array(z.string()).optional().default([]),
     decisionGate: dagDecisionGateSchema.optional(),
+    retryPolicy: dagRetryPolicySchema.optional(),
     dynamicExpansion: dagDynamicExpansionSchema.optional(),
     dynamicReduction: dagDynamicReductionSchema.optional(),
     dynamicCondition: dagDynamicConditionSchema.optional(),
@@ -240,6 +269,7 @@ export const dagSpecSchema = z
     .object({
     version: dagVersionSchema,
     title: z.string().min(1),
+    runtimeContract: dagRuntimeContractSchema.optional(),
     outputLanguage: dagOutputLanguageSchema.optional(),
     objective: z.string().optional(),
     successCriteria: z.array(z.string()).optional(),
@@ -252,6 +282,20 @@ export const dagSpecSchema = z
     tasks: z.array(dagTaskSchema).min(1),
 })
     .superRefine((spec, ctx) => {
+    if (spec.runtimeContract && spec.version !== 3) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "runtimeContract requires DagSpec version 3",
+            path: ["version"],
+        });
+    }
+    if (spec.version === 3 && !spec.runtimeContract) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "DagSpec version 3 requires runtimeContract",
+            path: ["runtimeContract"],
+        });
+    }
     // Catch raw cursor keys that Zod .strict() on nested objects already rejects when parsed
     // via parseDagSpec; this refine covers typed object construction paths.
     const models = spec.executorModels;

package/dist/workflows/dag/validate.js

@@ -1,7 +1,9 @@
 import { DEFAULT_DAG_EXECUTOR_MODELS, ENV_VAR_NAME_PATTERN, } from "./types.js";
 import { resolveShellCommands } from "../../executors/shell-executor.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
+import { resolveRepairTaskForGate } from "./repair-artifact.js";
 import { topoSortToRanks } from "./topo.js";
+import { isSafeReadOnlyPiRetryCandidate } from "./retry-policy.js";
 const GOVERNANCE_WARNING_TYPES = new Set([
     "read-only-missing-artifacts-forbidden",
     "read-only-prompt-mentions-artifact-writes",
@@ -176,14 +178,65 @@ function validateRepairArtifactGateConfig(task, spec, issues) {
         });
     }
     const upstream = spec.tasks.find((candidate) => candidate.id === repairArtifactGate.fromNodeId);
-    if (!upstream)
-        return;
-    if (upstream.executor === "shell") {
+    if (upstream && upstream.executor === "shell") {
         issues.push({
             type: "invalid-repair-artifact-gate-config",
             message: `task ${task.id} shell.repairArtifactGate.fromNodeId "${repairArtifactGate.fromNodeId}" must reference a non-shell upstream artifact node`,
         });
     }
+    const resolution = resolveRepairTaskForGate({
+        tasks: spec.tasks,
+        gateTask: task,
+    });
+    if (!resolution.ok) {
+        issues.push({
+            type: "invalid-repair-artifact-gate-config",
+            message: `task ${task.id} ${resolution.reason}`,
+        });
+        return;
+    }
+    const hardVerifyCandidates = spec.tasks.filter((candidate) => candidate.depends_on.includes(resolution.repairTask.id) &&
+        candidate.executor === "shell" &&
+        candidate.role === "verifier" &&
+        candidate.shell?.verifyEvidence?.phase === "final" &&
+        candidate.shell.verifyEvidence.quota === "full" &&
+        candidate.shell.verifyEvidence.finalFullRequired === true);
+    if (hardVerifyCandidates.length !== 1) {
+        issues.push({
+            type: "invalid-repair-artifact-gate-config",
+            message: hardVerifyCandidates.length === 0
+                ? `task ${task.id} repair node "${resolution.repairTask.id}" must have one direct downstream final/full hard verification shell node with finalFullRequired=true`
+                : `task ${task.id} repair node "${resolution.repairTask.id}" has multiple hard verification shell nodes (${hardVerifyCandidates.map((candidate) => candidate.id).join(", ")})`,
+        });
+        return;
+    }
+    const hardVerify = hardVerifyCandidates[0];
+    const descendantIds = new Set();
+    const queue = [hardVerify.id];
+    while (queue.length > 0) {
+        const parentId = queue.shift();
+        for (const candidate of spec.tasks) {
+            if (candidate.depends_on.includes(parentId) &&
+                !descendantIds.has(candidate.id)) {
+                descendantIds.add(candidate.id);
+                queue.push(candidate.id);
+            }
+        }
+    }
+    const reviewCandidates = spec.tasks.filter((candidate) => descendantIds.has(candidate.id) &&
+        candidate.executor === "pi" &&
+        candidate.role === "reviewer" &&
+        !candidate.decisionGate?.enabled &&
+        candidate.writePolicy === "read-only" &&
+        (candidate.outputContract?.includes("VERDICT:") ?? false));
+    if (reviewCandidates.length !== 1) {
+        issues.push({
+            type: "invalid-repair-artifact-gate-config",
+            message: reviewCandidates.length === 0
+                ? `task ${task.id} hard verification node "${hardVerify.id}" must reach one read-only Pi reviewer with a VERDICT output contract`
+                : `task ${task.id} hard verification node "${hardVerify.id}" has multiple Pi reviewer nodes (${reviewCandidates.map((candidate) => candidate.id).join(", ")})`,
+        });
+    }
 }
 function validateShellVerdictGateGovernance(task, commands, issues) {
     if (task.executor !== "shell") {
@@ -229,7 +282,7 @@ function writeSetEntriesOverlap(a, b) {
         pathMatchesPattern(probeB, a)));
 }
 function shouldValidateWritePolicy(spec, task) {
-    return (spec.version === 2 ||
+    return (spec.version >= 2 ||
         task.writePolicy !== undefined ||
         task.writeSet !== undefined);
 }
@@ -414,6 +467,16 @@ function validateStaticTaskConfig(task, issues) {
         });
     }
 }
+function validateRetryPolicyTaskConfig(task, issues) {
+    if (task.retryPolicy === undefined)
+        return;
+    if (!isSafeReadOnlyPiRetryCandidate(task)) {
+        issues.push({
+            type: "invalid-retry-policy",
+            message: `task ${task.id} declares retryPolicy but is not a safe read-only non-dynamic Pi node; retry is only allowed for read-only/none Pi planner/scout/reviewer/verifier/closeout nodes without write, supervisor, or dynamic capabilities`,
+        });
+    }
+}
 function validateDecisionGateTaskConfig(task, issues) {
     if (!task.decisionGate?.enabled) {
         return;
@@ -512,6 +575,7 @@ export function validateDagSpec(spec) {
         validateShellTaskConfig(task, spec, issues);
         validateStaticTaskConfig(task, issues);
         validateDecisionGateTaskConfig(task, issues);
+        validateRetryPolicyTaskConfig(task, issues);
     }
     validateSameRankWriteSetConflicts(spec, ranks, issues);
     validateSameRankAgentAttributionRisks(spec, ranks, issues);

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/agent-dag-runner.md

@@ -17,7 +17,32 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
 - `static`：确定性生成的 artifacts 或 notes
 - `shell`：验证与文件系统检查
 - `pi`：规划、review、诊断；节点设 `toolProfile: "write"` 时有界写入
-- `cursor`：显式启用时的可选有界写后端
+
+## Retry (read-only Pi nodes)
+
+planner/scout/reviewer/verifier/closeout 角色的只读 Pi 节点可声明 opt-in `retryPolicy`，用于在同一 run 内有界重试模型连接中断、provider 限流、临时不可用或请求 timeout。生成器会为这些安全节点自动声明默认策略：总尝试次数 3（手工配置上限 5），指数退避，单次等待上限 30s。
+
+- 仅以下原始失败分类默认可重试：`timeout`、`network`、`rate-limit`、`unavailable`。
+- `quota`、`auth`、`invalid-output`、`write-guard`、`decision-envelope` 与未知失败不重试。`quota` 不是 rate limit，不会被自动重试。
+- 资格由确定性 helper 判断：仅 `writePolicy=read-only|none`（或 Pi 默认只读）的 planner/scout/reviewer/verifier/closeout 可用。supervisor、implementer、writer（`toolProfile=write` 或 `writePolicy=exclusive`）、docs-only、dynamic、shell、static 与 decision-gate 节点一律不重试，DAG validation 会拒绝其策略。
+- 每次 attempt 写入独立不可变证据（`<node-id>/attempt-<n>.json`，run-relative path），最终 node record 的 `attempts` 字段引用完整 attempt 历史；后一次成功不会覆盖前一次失败证据。
+- 重试期间复用同一 run、controller identity、skill snapshot、prompt、model 与上游输入。节点终态的 `durationMs`、`tokensUsed`、`parsedEvents` 聚合全部 attempts；退避等待会刷新 `lastActivityAt`，避免被误判为 node-quiet。当前退避会占用该节点所在的并发槽。
+
+示例：
+
+```json
+{
+  "retryPolicy": {
+    "maxAttempts": 3,
+    "backoff": "exponential",
+    "initialDelayMs": 2000,
+    "maxDelayMs": 30000,
+    "retryCategories": ["timeout", "network", "rate-limit", "unavailable"]
+  }
+}
+```
+
+未声明 `retryPolicy` 的历史 DAG 行为不变（单次执行、无 `attempts` 字段，也不新增 attempt artifact）。
 
 ## Skills
 

package/docs/architecture/dag-execution.md

@@ -34,6 +34,12 @@ src/commands/dag-validate.ts  runDagValidate
   → src/application/dag/validate-dag.ts  validateDagUseCase
 ```
 
+### runtime contract preflight 与 repair writer 解析
+
+- `src/workflows/dag/runtime-contract.ts` `assertRuntimeContractCompatible` 依据 controller capabilities（`DAG_CONTROLLER_CAPABILITIES`：`agentRuntime="pi-only"`、`repairWriterProtocol="explicit-node-v1"`）校验 DagSpec v3 必需的 `runtimeContract`。v3 让旧 controller 在解析阶段拒绝；新 controller 的 `validateDagUseCase`、`runDagUseCase`、`runDag` 与 resume 还会校验 capability 和可选最低版本，不兼容在任何节点执行前 fail-fast。legacy v1/v2 DagSpec 可读但没有 v3 握手。
+- `src/workflows/dag/repair-artifact.ts` `resolveRepairTaskForGate` 解析 `shell.repairArtifactGate`：优先显式 `repairNodeId`，否则推导唯一的下游受治理 Pi writer（`repairWriterContractIssues` 校验 executor/toolProfile/writePolicy/path 契约）。`validate.ts` 与 `node-execution.ts` 复用同一 resolver，runtime 不再按节点名硬编码。
+- `src/workflows/dag/controller-identity.ts` 在 run 创建前要求 controller identity 可解析，再由 `captureControllerIdentity` 冻结到 `<runDir>/controller-identity.json`；`verifyControllerIdentityForResume` 在 resume 前重新校验并对漂移、篡改或 legacy-unpinned run fail closed。
+
 ## rank 调度
 
 拓扑排序与按 rank 执行的符号归属（校准版，勿笼统归到 `runner.ts`）：

package/docs/architecture/evolution.md

@@ -1,8 +1,8 @@
 # 架构演进：当前 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.10.0 + 主干 Unreleased）
+## 当前已实现（0.11.0）
 
 | 域 | 现状 | 权威入口 |
 | --- | --- | --- |
@@ -11,8 +11,10 @@
 | 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 | 本地只读暖白控制台（derived） | `website/docs/guides/observe-ui.md` |
+| 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 |
 
@@ -24,7 +26,7 @@
 
 ## 未来规划（第 3–6 月，**未实现**）
 
-以下能力来自 `docs/design/六个月规划.md` 与 `docs/design/dynamic-workflow-dag-engine-roadmap.md`（两文件均带 2026-07-14 校准条，未交付 phase 为**设计输入**，不是已实现证明）。它们**当前不存在于代码或 CLI**：
+以下能力来自 `docs/design/六个月规划.md` 与 `docs/design/dynamic-workflow-dag-engine-roadmap.md`（六个月规划页首 2026-07-15 / 0.11.0 校准；未交付 phase 为**设计输入**，不是已实现证明）。它们**当前不存在于代码或 CLI**：
 
 | 未来方向 | 状态 | 规划来源 |
 | --- | --- | --- |

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

@@ -10,17 +10,30 @@
 | 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 |
 
 ### 区分要点
 
-- **Task vs DAG run**：Task 是用户意图的源（`source/`、需求、执行约束、artifacts）；DAG run 是一次执行实例，`<runId>/` 下落 spec、state、节点 artifacts、skill snapshot、decision envelope、convergence。
+- **Task vs DAG run**：Task 是用户意图的源（`source/`、需求、执行约束、artifacts）；DAG run 是一次执行实例，`<runId>/` 下落 spec、state、节点 artifacts、skill snapshot、controller identity（`controller-identity.json`，冻结执行 controller 的 package version/binary 哈希/portable fingerprint，state 记录相对 ref 与内容哈希，resume 时重新校验、漂移 fail closed）、decision envelope、convergence。
 - **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,16 +10,24 @@
 | `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/` |
 
 ## 路线与产品线笔记（非实现证明）
 
 | 文档 | 用途 |
 |---|---|
 | `dynamic-workflow-dag-engine-roadmap.md` | Dynamic Workflow 适配分析与阶段规划；**页首有实现状态 / Pi-only 校准条**（已落地 vs 设计输入）；正文 Cursor 叙述视为历史 |
-| `六个月规划.md` | 长期路线；**第 1–2 月已收敛为 archive/reports 指针**，当前有效前瞻从第 3 月起 |
-| `产品线共享知识库.md` | 产品线文档仓库作为上游事实源 |
+| `六个月规划.md` | 长期路线；**页首 2026-07-15 / 0.11.0 校准**；第 1–2 月为 archive/reports 指针，当前有效前瞻从第 3 月起 |
+| `产品线共享知识库.md` | 产品线文档仓库作为上游事实源；**页首 2026-07-15 / 0.11.0 校准**（模板+Feature dogfood 已落地 vs docs-sync 未来） |
 | `研发模式.md` | 10 个工作日 Feature 团队工作流 |
-| `腾讯实践对当前项目的指引.md` | 腾讯 Harness Engineering 实践对本仓库的映射笔记 |
+| `腾讯实践对当前项目的指引.md` | 腾讯 Harness Engineering 实践对本仓库的映射笔记；源文见 `website/docs/practices/tencent-harness-engineering/index.md` |
 
 ## 视觉参考
 
@@ -39,6 +47,7 @@
 | `archive/2026-07-10-observe-ui.md` | 已归档：Observe UI v0 设计（OBS-001～010；0.9.0 暖白重设计在其上演进） |
 | `archive/2026-07-10-observe-ui-optimization.md` | 已归档：Observe UI 中文化与过程时间线（UI-1～UI-9 已实现） |
 | `archive/2026-07-10-observe-ui-goal.md` | 已归档：OBS-001～010 逐任务进度看板（全部 done） |
+| `archive/2026-07-14-observe-ui-roadmap.md` | 已归档：Observe R1–R5 运营控制台路线图（资源池/Batch-Run/Feature 关联/事件时间线/前端模块化；证据见 completed plans + reports） |
 | `archive/2026-07-11-第一月规划.md` | 已归档：首月落地计划（0.8.0 + Round 1/2/3 闭环） |
 | `archive/2026-07-11-第一月wbs.md` | 已归档：首月 WBS 与分工（历史记录） |
 | `archive/2026-07-12-第二月规划.md` | 已归档：第二月本地 Feature 交付闭环（M2-01～08；见 `docs/reports/2026-07-12-m2-completion-audit.md`） |

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

@@ -6,6 +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-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` 及更早计划。
+- 已归档：`../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

@@ -4,6 +4,13 @@
 
 npm 包携带本 README 作为目录契约。具体 completed plan 属于目标仓库历史，不从 loop-agent 源码历史复制。
 
+- [`2026-07-15-repair-artifact-gate-runtime-contract.md`](2026-07-15-repair-artifact-gate-runtime-contract.md) — 显式 `repairNodeId` + 严格 repair writer 契约、DagSpec `runtimeContract` capability preflight，以及 run-owned controller identity（resume 漂移 fail-closed）
+- [`2026-07-14-backend-test-dag-template.md`](2026-07-14-backend-test-dag-template.md) — 通过 `taskKind: "backend-test"` 生成需求分析、功能用例、pytest 自动化、执行与复盘的 Pi-only 专用 DAG
+- [`2026-07-14-observe-ui-r5.md`](2026-07-14-observe-ui-r5.md) — Observe 原生 ES module 拆分、四态 helper、Pool hash 筛选与入口 re-export
+- [`2026-07-14-observe-ui-r4.md`](2026-07-14-observe-ui-r4.md) — Observe Batch/Pool 有界事件时间线、cursor/limit、JSONL 容量与投影 fault-first
+- [`2026-07-14-observe-ui-r2.md`](2026-07-14-observe-ui-r2.md) — Observe Batch / Worker Run 证据化详情、三层只读结构与安全 artifact preview
+- [`2026-07-14-observe-ui-r3.md`](2026-07-14-observe-ui-r3.md) — Observe Feature 决策详情、copy-only 建议命令与 canonical 对象关系导航
+- [`2026-07-14-observe-ui-r1.md`](2026-07-14-observe-ui-r1.md) — Observe 资源池总览、Task 下钻、精确对象关联与有界 run history
 - [`2026-07-14-init-canonical-layout.md`](2026-07-14-init-canonical-layout.md) — 目标项目治理资料统一到 `ai_workspace/loop-agent/` 与 `.agents/skills/`，并为旧布局提供保守安全迁移
 - [`2026-07-14-self-update-notifier-implementation.md`](2026-07-14-self-update-notifier-implementation.md) — 实现 loop-agent CLI 自更新提醒，覆盖拒绝版本、精确安装、npm global 来源证明和验证收口
 - [`2026-07-12-observe-warm-console-redesign.md`](2026-07-12-observe-warm-console-redesign.md) — 以暖白、细边界和高密度信息架构重构 Observe Dashboard；多轮细节调整后按用户确认收口归档。
@@ -60,3 +67,8 @@ npm 包携带本 README 作为目录契约。具体 completed plan 属于目标
 - [`2026-07-10-observe-ui-review-remediation.md`](2026-07-10-observe-ui-review-remediation.md) — 修复 Observe UI 事件链路、历史 run 投影、artifact 安全边界与失败状态展示
 
 - [`2026-07-13-exec-plan-lifecycle.md`](2026-07-13-exec-plan-lifecycle.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,106 @@ 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：
+
+```text
+analyze-inputs-pi
+  -> generate-backend-functional-cases-pi
+  -> review-backend-cases-pi
+  -> review-backend-cases-gate-shell
+  -> generate-backend-pytest-pi
+  -> execute-backend-pytest-shell
+  -> test-retrospect-pi
+```
+
+这条链覆盖后端功能测试从需求分析到复盘评级的全链路流程：
+
+1. **analyze-inputs-pi**：读取需求.md 和开发详设等参考文档，产出端到端测试分析契约（范围、风险、策略要点）
+2. **generate-backend-functional-cases-pi**：根据契约生成结构化后端功能测试用例（Markdown），用例 ID 带 `BE-` 前缀（如 `BE-ORDER-001`），写入 `testcase/md/`
+3. **review-backend-cases-pi**：评审后端功能测试用例，输出审查报告 + `VERDICT: pass` / `VERDICT: request-revision`
+4. **review-backend-cases-gate-shell**：只有评审首条 verdict 为 `VERDICT: pass` 时才允许继续生成 pytest
+5. **generate-backend-pytest-pi**：将后端功能用例转化为 pytest 自动化代码，仅写入 `testcase/**/test_*.py`
+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。
 
 `verify-shell` 使用 adapter 根据 task verify preset/quota 解析出的最终验证命令，并把新鲜 exit code/stdout/stderr 交给后续只读 verifier。review-gated 模板继续插入：
@@ -131,6 +233,10 @@ verify-shell -> verify-pi -> review-pi -> review-gate-shell -> closeout-pi
 
 supervised 模板在实现路径上增加 write-set audit、soft/hard shell 验证、process supervision、有界 repair、decision gates 与可选 convergence retry。
 
+### 只读 Pi 节点安全重试
+
+所有生成模板都会为安全的只读 Pi 节点（planner/scout/reviewer/verifier/closeout，且 `writePolicy=read-only|none`、非 writer、非 dynamic、非 decision-gate）自动声明默认 `retryPolicy`（总尝试 3 次，手工配置最多 5 次，指数退避，单次等待上限 30s）。supervisor 与 implementer 明确不在资格范围。仅重试 `timeout`、`network`、`rate-limit`、`unavailable`；`quota`、`auth`、`invalid-output`、`write-guard` 与未知失败不重试。每次 attempt 保留独立证据，详见 [docs/agent-dag-runner.md](./agent-dag-runner.md#retry-read-only-pi-nodes)。
+
 ### 可选 repo-local SDD skill 增强
 
 `dag run-task` 会在目标项目的 `.agents/skills/` 中探测三个可选 skill：

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