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

package/CHANGELOG.md

@@ -2,14 +2,62 @@
 
 这里记录每个版本对使用者有影响的变化。命令名和配置字段保持原样，其余内容尽量用日常语言说明。
 
-## [Unreleased]
+## [Unreleased]
+
+## [0.13.0] - Unreleased
+
+### 新增
 
-## [0.12.0] - 2026-07-16
+- 前端 DAG 新增设计修订闭环：首轮 design review 输出 `request-revision` 时通过只读 `frontend-plan-revision-pi` 修订计划后经 `frontend-final-design-review-pi` 和 `frontend-final-design-gate-shell` 最终门禁，不再直接终止。只有最终 `VERDICT: pass` 才授权写入。
+- Observe 节点检查器新增「规范证据」页签，展示 skill 注入状态、已读取规范文件（基于 session event 中成功完成的 read 工具调用）、检索操作（grep/find/ls）以及知识库查询；证据不足时提供明确提示。
+- 规范证据接口强制要求通过 `toolCallId` 配对 `tool_execution_start` 与 `tool_execution_end` 事件；仅有 start 而无匹配成功 end、end 报错（`isError: true`）或缺失 complete 事件的 read 一律不计入已读取。
+
+### 变更
+
+- 前端 design gate shell 失败路由改为 `ContractMismatch` / `frontend-plan-revision-and-rerun`，不再路由为 `ProductBug` / `dev-fix`。
+- 前端实现、design review 和 review skill 要求显式执行并记录规范检索与读取，以便后续新 run 在 Observe 中生成可观察证据。
+
+### 破坏性变更
+
+- Task Pool 任务身份升级为 feature-scoped 复合键 `{ featureId, taskId }`（`TaskPoolTaskRef`，ADR 0004）。新 state 使用 `schemaVersion: 2`，canonical 路径为 `.harness/task-pool/states/<featureId>/<taskId>.json`；裸 `taskId` 不再是仓库全局唯一键。
+- `agent-worker task retry` 的 canonical 调用必须携带 `--feature-id`。跨 Feature 同名 Task 时省略 `--feature-id` 会 fail-closed，不会静默猜 Feature。
+- 扁平 legacy `states/<taskId>.json` 在写入 / Ready 路径 fail-closed，不会被静默解释为某个 Feature 的状态。
+
+### 迁移提示
+
+1. 运行 `agent-worker pool doctor --repo <repo> --json` 盘点 v2 / legacy inventory。
+2. 需要迁移时先 `agent-worker pool migrate-state --repo <repo>`（dry-run），确认映射后再 `--apply --owner <owner> --reason <reason>`。
+3. 更新脚本与文档中的 retry 示例为 `task retry <task-id> --feature-id <feature-id> ...`。
+4. Observe / 书签改用 `#/feature/:featureId/task/:taskId`；legacy `#/task/:taskId` 仅在 taskId 全库唯一时兼容。
+5. `runs.jsonl` / `events.jsonl` 不会被 migrate 重写；历史 `workerRunId` 仍可追溯。
+
+### 新增
+
+- `agent-worker pool doctor`：只读 Task Pool inventory 与迁移证据（exit 0 也可带 findings）。
+- `agent-worker pool migrate-state`：legacy → v2 显式迁移；默认 dry-run，apply 需 owner/reason，失败全回滚并保留审计 artifact。
+- `agent-worker batch plan-ready`：零写入预览 TaskSpec priority 驱动的 selected、deferred 与 blocked 计划。
+
+### 变更
+
+- Runner Ready Queue、Feature review/run、Follow-up、Delivery / Closeout、morning report / metrics 与 Observe read-model 均按 Feature 作用域消费 state，同名 Task 跨 Feature 不串线。
+- Observe canonical API：`GET /api/features/:featureId/tasks/:taskId[/runs]`；legacy bare task route 在歧义时返回 409 + `candidates`。
+- Feature dry-run / review / next-action、morning report、GlobalSnapshot、Observe 消费同一 Ready Planner projection；前端与投影层不得独立重选或重排 ready tasks。
+
+### 修复
+
+- Windows 下发布/测试更稳：路径断言对齐 `realpathSync`（避免短路径与长路径比较失败）、Git Bash 解析与生产 `shell-executor` 一致（支持 `LOOP_AGENT_BASH` / `GIT_BASH` 与多候选路径），并放宽 self-host canary、Ring 1 materialize 与 Git-backed Delivery 集成测试在重负载下的超时上限。
+- 前端实现 skill 会完整注入增长后的必需节点契约，不再因单引用预算仍停留在旧上限而截断设计修订闭环规则。
+
+## [0.12.0] - 2026-07-16
 
 ### 新增
 
 - 只读 Pi DAG 节点支持 opt-in 安全重试：仅 planner/scout/reviewer/verifier/closeout 角色且无写入能力的 Pi 节点可声明 `retryPolicy`，在同一 run 内重试模型连接中断（`network`）、provider 限流（`rate-limit`）、临时不可用（`unavailable`）或请求 timeout。生成模板默认总尝试 3 次，手工配置最多 5 次，并使用有上限的指数退避。每次 attempt 保留独立证据，节点耗时、Token 与事件数按尝试聚合；后一次成功不会覆盖前一次失败证据。`quota`、`auth`、`invalid-output`、`write-guard` 与未知失败不重试；supervisor、implementer、writer、dynamic、shell、static、docs-only、decision-gate 节点声明策略会在校验阶段失败。未声明策略的历史 DAG 不新增 attempt artifact，行为保持不变。
 - 新增 `taskKind: "backend-test"` 专用 DAG：从需求分析开始，生成并评审后端功能用例，再生成和执行 pytest 自动化，最后产出测试复盘报告；新 DAG 沿用当前 Pi-only runtime、版本化 runtime contract 与既有执行恢复机制。
+- 测试知识回写专用 DAG：`taskKind: "knowledge-sync"`。生成 collect→draft→validate→apply→pointer；**必须绑定 `featureId`**（`task.json.featureId` 或 hardConstraints / 需求中的 `F-…`），writeSet 收窄到 `features/<featureId>/…`。
+- 业务知识图谱开荒 DAG：`taskKind: "knowledge-graph-bootstrap"`（preflight→inventory→propose→validate→review→gate→promote→materialize）；AI 只写 `knowledge/bootstrap/staging/**`。
+- 图谱辅助脚本与 CLI：`loop-agent knowledge query|graph-init|graph-materialize|graph-promote|graph-incremental-prepare`（薄封装 `scripts/kb-*`）；`knowledge curate` 仍只负责 repair guidance 提案。
+- B1 骨架、Phase A 查询（by_id / by_feature / search）、merge-new-only 晋升、增量 scope 准备与 materialize 索引；设计文档见 `docs/design/knowledge-*.md` 与 active plan `docs/exec-plans/active/2026-07-14-knowledge-sync-and-graph.md`。
 
 ### 修复
 

package/README.md

@@ -27,7 +27,7 @@ loop-agent --help
 如果你拒绝版本 A，当前系统用户下不会再提醒 A；之后发布版本 B 时会继续提醒。确认更新时，CLI 会先证明当前安装来自同一 npm global root，然后安装刚确认的精确版本，例如：
 
 ```bash
-npm install -g @tea-agent/loop-agent@0.12.0
+npm install -g @tea-agent/loop-agent@0.13.0
 ```
 
 需要完全关闭自动检查时设置：
@@ -97,6 +97,25 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
 
 当前 `dag run-task` 也支持按 `task.json.taskKind` 选择专用模板；`frontend-implementation` 会生成前端契约、design gate、静态验证、行为验证和 review gate 节点链，`backend-test` 会生成从需求分析、功能用例、pytest 自动化到测试复盘的专用节点链。
 
+测试结论写回与业务知识图谱（结构化 Git，非 RAG）：
+
+```bash
+# 最终验证后：同步结论/用例/缺陷到 features/<F>/testing/**（须 featureId）
+# task.json: { "taskKind": "knowledge-sync", "featureId": "F-2026-004" }
+loop-agent dag run-task <task-id> --strict-models
+
+# 图谱开荒 / 增量（AI 只写 staging，晋升默认不覆盖已有正式文件）
+# task.json: { "taskKind": "knowledge-graph-bootstrap" }
+loop-agent knowledge graph-init --product-name my-app
+loop-agent knowledge graph-incremental-prepare --feature F-2026-004 --service order
+loop-agent dag run-task <task-id> --strict-models
+loop-agent knowledge graph-promote
+loop-agent knowledge graph-materialize
+loop-agent knowledge query --mode by_feature --feature F-2026-004 --json
+```
+
+`knowledge curate` 仍只用于 repair/learned guidance 提案，与图谱查询不是同一能力。细节见 `docs/feature-workflow.md` 与 `docs/design/knowledge-graph-ai-bootstrap.md`。
+
 `<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。
 
 非微小工作需要 exec-plan 时，使用确定性生命周期命令维护计划与索引；`new-task` 不会自动创建计划：
@@ -158,7 +177,16 @@ Morning report 和 Observe snapshot/UI 复用同一 Feature reducer，优先展
 
 nightly wrapper 按 feature 互斥，保留批次/超时退出码，并输出 morning report、Observe snapshot 和 controller 版本 artifacts。
 
-自 0.8.0 起，`.harness/task-pool/` 是唯一受支持的 Task Pool runtime root，其中包含根级 `runs.jsonl`、`events.jsonl`、`states/`、`artifacts/`、`failure-handoffs/`、`observability/` 和 `reports/`。这是 hard cutover：旧路径不读取、不迁移、不合并、不重映射；升级意味着本地 Worker Task Pool 历史重置。
+自 0.8.0 起，`.harness/task-pool/` 是唯一受支持的 Task Pool runtime root，其中包含根级 `runs.jsonl`、`events.jsonl`、`states/`、`artifacts/`、`failure-handoffs/`、`observability/` 和 `reports/`。这是 hard cutover：此前的顶层 Task Pool 位置不读取、不迁移、不合并、不重映射。
+
+Task Pool **state identity** 进一步固定为 feature-scoped 复合键 `{ featureId, taskId }`（ADR 0004）：
+
+- canonical state 路径：`.harness/task-pool/states/<featureId>/<taskId>.json`（schema v2，文件内容必须携带 `featureId` / `taskId`）
+- 同仓库多 Feature 可安全使用相同 Task ID（例如 `F-A/QA-EXEC-001` 与 `F-B/QA-EXEC-001` 互不覆盖）
+- retry 必须显式指定 Feature：`agent-worker task retry <task-id> --feature-id <feature-id> --repo <repo> --reason <reason>`
+- 诊断与迁移：`agent-worker pool doctor --repo <repo> --json`（只读）；`agent-worker pool migrate-state --repo <repo>` 默认 dry-run，apply 需 `--owner` + `--reason`
+- 扁平 legacy `states/<taskId>.json` 不得静默解释；存在时新写入 fail-closed，必须经 doctor / migrate 处理
+- Observe 只读：canonical `#/feature/:featureId/task/:taskId` 与 `GET /api/features/:featureId/tasks/:taskId`；legacy bare task route 仅在唯一命中时兼容，歧义返回 409 + candidates
 
 ## 核心概念
 

package/dist/application/dag/generate-task-dag.js

@@ -205,6 +205,8 @@ export async function generateTaskDagUseCase(input) {
     const taskConfig = await loadTaskConfig(repoRoot, parsed.taskId);
     const isFrontendImplementationTask = taskConfig.taskKind === "frontend-implementation";
     const isBackendTestTask = taskConfig.taskKind === "backend-test";
+    const isKnowledgeSyncTask = taskConfig.taskKind === "knowledge-sync";
+    const isKnowledgeGraphBootstrapTask = taskConfig.taskKind === "knowledge-graph-bootstrap";
     const candidateResult = await initHybridDagFromTask(repoRoot, parsed.taskId, {
         outputPath: parsed.outputPath,
         template: "standard-dag",
@@ -245,6 +247,34 @@ export async function generateTaskDagUseCase(input) {
             profileRouting.selectedByProfile = parsed.profile;
         }
     }
+    if (isKnowledgeSyncTask) {
+        profileRouting.selectedTemplate = "knowledge-sync-dag";
+        profileRouting.source = "taskKind";
+        profileRouting.routingReasons = [
+            'taskKind "knowledge-sync" selects the dedicated knowledge-sync DAG template',
+        ];
+        if (parsed.profile === "auto") {
+            profileRouting.selectedByProfile =
+                resolveAutoRoutingProfile(profileRouting.candidateProfile);
+        }
+        else if (parsed.profileExplicit) {
+            profileRouting.selectedByProfile = parsed.profile;
+        }
+    }
+    if (isKnowledgeGraphBootstrapTask) {
+        profileRouting.selectedTemplate = "knowledge-graph-bootstrap-dag";
+        profileRouting.source = "taskKind";
+        profileRouting.routingReasons = [
+            'taskKind "knowledge-graph-bootstrap" selects the dedicated knowledge-graph bootstrap DAG template',
+        ];
+        if (parsed.profile === "auto") {
+            profileRouting.selectedByProfile =
+                resolveAutoRoutingProfile(profileRouting.candidateProfile);
+        }
+        else if (parsed.profileExplicit) {
+            profileRouting.selectedByProfile = parsed.profile;
+        }
+    }
     const initResult = profileRouting.selectedTemplate === "standard-dag"
         ? candidateResult
         : await initHybridDagFromTask(repoRoot, parsed.taskId, {

package/dist/cli/command-definitions.js

@@ -84,7 +84,14 @@ const HANDOFF_USAGE = "handoff <check|coverage> [taskId]";
 const REFERENCE_SUBCOMMANDS = ["index"];
 const STUDY_SUBCOMMANDS = ["init"];
 const WORKTREE_SUBCOMMANDS = ["create", "list", "remove"];
-const KNOWLEDGE_SUBCOMMANDS = ["curate"];
+const KNOWLEDGE_SUBCOMMANDS = [
+    "curate",
+    "query",
+    "graph-init",
+    "graph-materialize",
+    "graph-promote",
+    "graph-incremental-prepare",
+];
 const DAG_SUBCOMMANDS = [
     "init-hybrid",
     "run-task",
@@ -435,8 +442,8 @@ export const COMMAND_DEFINITIONS = [
         name: "knowledge",
         adapter: "required",
         tier: "operator",
-        intent: "Curate completed convergence patterns into human-gated learned guidance proposals.",
-        usage: "knowledge curate [--json|--markdown] [--output <path>]",
+        intent: "Curate repair guidance proposals, query the structured knowledge graph, and run graph bootstrap helpers (init/materialize/promote/incremental).",
+        usage: "knowledge <curate|query|graph-init|graph-materialize|graph-promote|graph-incremental-prepare> ...",
         subcommands: [...KNOWLEDGE_SUBCOMMANDS],
         handler: async ({ repoRoot, subcommand, rest }) => {
             await runKnowledge(repoRoot, [subcommand, ...rest].filter((arg) => Boolean(arg)));

package/dist/commands/knowledge.js

@@ -1,41 +1,104 @@
 import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
 import { curateKnowledgePatterns } from "../workflows/dag/knowledge-curator.js";
+export const KNOWLEDGE_CLI_SUBCOMMANDS = [
+    "curate",
+    "query",
+    "graph-init",
+    "graph-materialize",
+    "graph-promote",
+    "graph-incremental-prepare",
+];
+const USAGE = "usage: knowledge <curate|query|graph-init|graph-materialize|graph-promote|graph-incremental-prepare> ...";
+function packageRoot() {
+    // dist/commands/knowledge.js or src/commands/knowledge.ts → package/repo root
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+}
+function resolveScript(repoRoot, fileName) {
+    const candidates = [
+        path.join(repoRoot, "scripts", fileName),
+        path.join(packageRoot(), "scripts", fileName),
+    ];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    throw new Error(`knowledge script not found: ${fileName} (looked under repo scripts/ and package scripts/)`);
+}
+function runProcess(command, args, cwd) {
+    const result = spawnSync(command, args, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["inherit", "pipe", "pipe"],
+    });
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0 && result.status !== null) {
+        process.exitCode = result.status;
+    }
+}
+function runNodeScript(repoRoot, scriptFile, forwardArgs) {
+    const scriptPath = resolveScript(repoRoot, scriptFile);
+    runProcess(process.execPath, [scriptPath, ...forwardArgs], repoRoot);
+}
+function runBashScript(repoRoot, scriptFile, forwardArgs) {
+    const scriptPath = resolveScript(repoRoot, scriptFile);
+    runProcess("bash", [scriptPath, ...forwardArgs], repoRoot);
+}
+function ensureRootFlag(repoRoot, rest) {
+    if (rest.includes("--root"))
+        return rest;
+    return ["--root", repoRoot, ...rest];
+}
 export function parseKnowledgeArgs(args) {
     const [command, ...rest] = args;
-    if (command !== "curate") {
-        throw new Error("usage: knowledge curate [--json|--markdown] [--output <path>]");
+    if (!command ||
+        !KNOWLEDGE_CLI_SUBCOMMANDS.includes(command)) {
+        throw new Error(USAGE);
     }
-    let outputPath;
-    let json = false;
-    let markdown = false;
-    for (let i = 0; i < rest.length; i += 1) {
-        const arg = rest[i];
-        if (arg === "--json") {
-            json = true;
-            continue;
-        }
-        if (arg === "--markdown") {
-            markdown = true;
-            continue;
+    if (command === "curate") {
+        let outputPath;
+        let json = false;
+        let markdown = false;
+        for (let i = 0; i < rest.length; i += 1) {
+            const arg = rest[i];
+            if (arg === "--json") {
+                json = true;
+                continue;
+            }
+            if (arg === "--markdown") {
+                markdown = true;
+                continue;
+            }
+            if (arg === "--output") {
+                outputPath = rest[++i];
+                if (!outputPath) {
+                    throw new Error("knowledge curate --output requires a path");
+                }
+                continue;
+            }
+            if (arg.startsWith("--output=")) {
+                outputPath = arg.slice("--output=".length);
+                continue;
+            }
+            throw new Error(`unknown knowledge curate argument: ${arg}`);
         }
-        if (arg === "--output") {
-            outputPath = rest[++i];
-            if (!outputPath)
-                throw new Error("knowledge curate --output requires a path");
-            continue;
-        }
-        if (arg.startsWith("--output=")) {
-            outputPath = arg.slice("--output=".length);
-            continue;
-        }
-        throw new Error(`unknown knowledge curate argument: ${arg}`);
+        if (!json && !markdown)
+            json = true;
+        return { command: "curate", outputPath, json, markdown };
     }
-    if (!json && !markdown)
-        json = true;
-    return { command, outputPath, json, markdown };
+    return {
+        command: command,
+        forward: rest,
+    };
 }
-export async function runKnowledge(repoRoot, args) {
-    const parsed = parseKnowledgeArgs(args);
+async function runCurate(repoRoot, parsed) {
     const result = await curateKnowledgePatterns({
         repoRoot,
         outputPath: parsed.outputPath,
@@ -50,7 +113,9 @@ export async function runKnowledge(repoRoot, args) {
         console.log(JSON.stringify({
             ok: result.ok,
             patternsPath: path.relative(repoRoot, result.patternsPath),
-            outputPath: result.outputPath ? path.relative(repoRoot, result.outputPath) : undefined,
+            outputPath: result.outputPath
+                ? path.relative(repoRoot, result.outputPath)
+                : undefined,
             patternCount: result.patternCount,
             safetyFindings: result.safetyFindings,
             message: result.message,
@@ -62,3 +127,36 @@ export async function runKnowledge(repoRoot, args) {
         process.stdout.write(result.proposalMarkdown);
     }
 }
+/**
+ * knowledge CLI:
+ * - curate: repair/learned guidance proposals (existing)
+ * - query / graph-*: thin wrappers over scripts/kb-*.{mjs,sh} for graph KB ops
+ */
+export async function runKnowledge(repoRoot, args) {
+    const parsed = parseKnowledgeArgs(args);
+    if (parsed.command === "curate") {
+        await runCurate(repoRoot, parsed);
+        return;
+    }
+    const forward = ensureRootFlag(repoRoot, parsed.forward);
+    switch (parsed.command) {
+        case "query":
+            runNodeScript(repoRoot, "kb-query.mjs", forward);
+            return;
+        case "graph-init":
+            // B1 skeleton is a bash script (no LLM)
+            runBashScript(repoRoot, "kb-bootstrap-init-skeleton.sh", forward);
+            return;
+        case "graph-materialize":
+            runNodeScript(repoRoot, "kb-graph-materialize.mjs", forward);
+            return;
+        case "graph-promote":
+            runNodeScript(repoRoot, "kb-graph-promote.mjs", forward);
+            return;
+        case "graph-incremental-prepare":
+            runNodeScript(repoRoot, "kb-graph-incremental-prepare.mjs", forward);
+            return;
+        default:
+            throw new Error(USAGE);
+    }
+}

package/dist/governance/manifest-types.js

@@ -43,6 +43,9 @@ export const workflowPolicyDagTemplateSchema = z.enum([
     "review-gated-dag",
     "supervised-implementation",
     "frontend-implementation",
+    "backend-test-dag",
+    "knowledge-sync-dag",
+    "knowledge-graph-bootstrap-dag",
 ]);
 export const workflowPolicyOutputLanguageSchema = z.enum(["zh-CN", "en"]);
 export const workflowPolicySchema = z

package/dist/task/config-types.js

@@ -12,6 +12,8 @@ export const taskKindSchema = z.enum([
     "feature-study",
     "frontend-implementation",
     "backend-test",
+    "knowledge-sync",
+    "knowledge-graph-bootstrap",
 ]);
 export const referenceRepoConfigSchema = z.object({
     name: z.string().min(1),
@@ -62,8 +64,10 @@ const taskConfigObjectSchema = z.object({
     taskId: z.string(),
     title: z.string(),
     sourceFiles: z.array(z.string()),
-    /** standard: 本仓库需求实现；feature-study: 参考外部代码特性并在目标仓库落地；frontend-implementation: 使用前端实现 DAG 模板 */
+    /** standard: 本仓库需求实现；feature-study: 参考外部代码特性并在目标仓库落地；frontend-implementation: 前端实现 DAG；backend-test: 后端测试 DAG；knowledge-sync: 最终验证后回写测试知识库 DAG；knowledge-graph-bootstrap: AI 辅助业务知识图谱初始化 */
     taskKind: taskKindSchema.optional().default("standard"),
+    /** Feature 目录 id（如 F-2026-004）。knowledge-sync 必填（也可从 hardConstraints/需求正文/taskId 解析）；用于收窄 writeSet */
+    featureId: z.string().min(1).optional(),
     referenceRepos: z.array(referenceRepoConfigSchema).optional().default([]),
     referenceDocs: z.array(referenceDocConfigSchema).optional().default([]),
     referenceMaxFilesPerRepo: z.number().int().positive().optional(),

package/dist/worker/cli.js

@@ -14,10 +14,15 @@ import { createCompositeProgressReporter } from "./observability/progress-compos
 import { createRoutedWorkerEventStore } from "./observability/event-store.js";
 import { buildGlobalSnapshot } from "./observability/read-model.js";
 import { createObserveServer } from "./observe/server.js";
-import { getTaskPoolRoot, prepareTaskPoolRetry } from "./pool/run-store.js";
+import { diagnoseTaskPoolStates, formatDoctorHuman, loadOperatorMapping } from "./pool/doctor.js";
+import { migrateTaskPoolStates } from "./pool/migrate-state.js";
+import { getTaskPoolRoot, prepareTaskPoolRetry, readFeatureTaskPoolStates } from "./pool/run-store.js";
+import { TaskPoolStateError } from "./pool/types.js";
 import { taskSpecSchema } from "./task-spec/schema.js";
 import { validateTaskSpec } from "./task-spec/validate.js";
 import { validateFeatureTaskGraph } from "./task-graph/validate.js";
+import { taskGraphSpecSchema } from "./task-graph/task-graph-schema.js";
+import { planReadyTasks } from "./task-graph/ready-planner.js";
 import { renderFeatureReview, reviewFeature } from "./feature/review.js";
 import { renderFeatureRun, runFeature } from "./feature/run.js";
 import { draftFollowUpDecision } from "./follow-up/factory.js";
@@ -40,6 +45,58 @@ export function buildAgentWorkerProgram() {
     const report = program.command("report").description("Task Pool reporting utilities");
     const observe = program.command("observe").description("Observe UI server and snapshot utilities");
     const feature = program.command("feature").description("Feature-level review and delivery workflow");
+    const pool = program.command("pool").description("Task Pool state doctor and migration utilities");
+    pool
+        .command("doctor")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--json", "Emit stable JSON instead of the human summary")
+        .option("--mapping <file>", "Optional operator mapping JSON (taskId -> featureId)")
+        .description("Inventory legacy and v2 Task Pool states (read-only)")
+        .action(async (options) => {
+        const repoRoot = path.resolve(options.repo);
+        const mapping = await loadOperatorMapping(options.mapping);
+        const report = await diagnoseTaskPoolStates(repoRoot, { mapping });
+        process.stdout.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : formatDoctorHuman(report));
+    });
+    pool
+        .command("migrate-state")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--dry-run", "Plan migration without writes (default when --apply is omitted)")
+        .option("--apply", "Apply migration (requires --owner and --reason)")
+        .option("--owner <owner>", "Migration owner for apply")
+        .option("--reason <reason>", "Why migration is being applied")
+        .option("--mapping <file>", "Optional operator mapping JSON (taskId -> featureId)")
+        .option("--json", "Emit stable JSON")
+        .description("Migrate legacy flat Task Pool states to feature-scoped v2 (default dry-run)")
+        .action(async (options) => {
+        try {
+            const result = await migrateTaskPoolStates({
+                repoRoot: path.resolve(options.repo),
+                apply: options.apply === true,
+                ...(options.owner ? { owner: options.owner } : {}),
+                ...(options.reason ? { reason: options.reason } : {}),
+                ...(options.mapping ? { mappingPath: options.mapping } : {}),
+            });
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            if (result.status === "failed")
+                process.exitCode = 1;
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            const code = error instanceof TaskPoolStateError ? error.code : "task-pool-migrate-failed";
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify({
+                    schemaVersion: 1,
+                    status: "failed",
+                    error: { code, message: detail },
+                }, null, 2)}\n`);
+            }
+            else {
+                process.stderr.write(`${detail}\n`);
+            }
+            process.exitCode = 1;
+        }
+    });
     feature
         .command("review")
         .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
@@ -206,12 +263,14 @@ export function buildAgentWorkerProgram() {
         .command("retry")
         .argument("<task-id>", "Failed Task Pool task to requeue")
         .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--feature-id <feature-id>", "Canonical Feature id for the Task Pool state (required when identity is ambiguous)")
         .option("--reason <reason>", "Why the failure is safe to retry")
         .description("Explicitly requeue a failed task; the next run-ready uses a new workerRunId")
         .action(async (taskId, options) => {
         const result = await prepareTaskPoolRetry({
             repoRoot: path.resolve(options.repo),
             taskId,
+            ...(options.featureId ? { featureId: options.featureId } : {}),
             ...(options.reason ? { reason: options.reason } : {}),
         });
         process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
@@ -268,6 +327,42 @@ export function buildAgentWorkerProgram() {
             handleFollowUpCliError(error, options.json ?? false, "approve-followup");
         }
     });
+    batch
+        .command("plan-ready")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing tasks/task-graph.yaml")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--limit <count>", "Maximum ready tasks to select")
+        .option("--json", "Emit stable JSON (default human summary)")
+        .description("Preview the read-only priority-aware ready plan without writing state or artifacts")
+        .action(async (options) => {
+        // Strict zero-write preview: load graph + specs + feature-scoped states only.
+        const featureDir = path.resolve(options.featureDir);
+        const repoRoot = path.resolve(options.repo);
+        const graph = taskGraphSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "tasks", "task-graph.yaml"), "utf-8")));
+        const taskSpecs = new Map();
+        for (const node of graph.nodes) {
+            const taskFile = node.task ?? `${node.id}.yaml`;
+            taskSpecs.set(node.id, taskSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "tasks", taskFile), "utf-8"))));
+        }
+        const selectionLimit = options.limit
+            ? Number.parseInt(options.limit, 10)
+            : graph.nodes.length;
+        if (!Number.isInteger(selectionLimit) || selectionLimit < 1) {
+            process.stderr.write("selectionLimit must be a positive integer\n");
+            process.exitCode = 1;
+            return;
+        }
+        const plan = planReadyTasks({
+            featureId: graph.feature_id,
+            graph,
+            taskSpecs,
+            states: await readFeatureTaskPoolStates(repoRoot, graph.feature_id),
+            selectionLimit,
+        });
+        process.stdout.write(options.json
+            ? `${JSON.stringify(plan, null, 2)}\n`
+            : `Selected: ${plan.selected.map((task) => task.taskId).join(", ") || "none"}\nDeferred: ${plan.deferred.map((task) => task.taskId).join(", ") || "none"}\nBlocked: ${plan.blocked.length}\n`);
+    });
     batch
         .command("run-ready")
         .requiredOption("--feature-dir <dir>", "Feature directory containing tasks/task-graph.yaml")

package/dist/worker/delivery/package.js

@@ -6,7 +6,7 @@ import { promisify } from "node:util";
 import YAML from "yaml";
 import { z } from "zod";
 import { controllerIdentitiesMatch, LOOP_AGENT_PACKAGE_NAME, } from "../loop-agent/loop-agent-client.js";
-import { getRunsJsonlPath, getTaskPoolRoot, readAllTaskPoolStates, readJsonlFile } from "../pool/run-store.js";
+import { getRunsJsonlPath, getTaskPoolRoot, readFeatureTaskPoolStates, readJsonlFile } from "../pool/run-store.js";
 import { acceptanceSpecSchema } from "../task-graph/acceptance-schema.js";
 import { taskGraphSpecSchema } from "../task-graph/task-graph-schema.js";
 import { validateFeatureTaskGraph } from "../task-graph/validate.js";
@@ -104,7 +104,7 @@ export async function prepareFeatureDelivery(input) {
     }
     const acceptance = acceptanceSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "acceptance.yaml"), "utf-8")));
     const graph = taskGraphSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "tasks", "task-graph.yaml"), "utf-8")));
-    const states = await readAllTaskPoolStates(repoRoot);
+    const states = await readFeatureTaskPoolStates(repoRoot, featureId);
     const runs = await readJsonlFile(getRunsJsonlPath(repoRoot));
     const taskSpecs = new Map();
     for (const node of graph.nodes)
@@ -208,7 +208,7 @@ export async function validateDeliveryPackage(input) {
         blockers.push(`Git worktree is not clean for Closeout: ${closeoutStatus}`);
     const graph = taskGraphSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "tasks", "task-graph.yaml"), "utf-8")));
     const acceptance = acceptanceSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "acceptance.yaml"), "utf-8")));
-    const states = await readAllTaskPoolStates(repoRoot);
+    const states = await readFeatureTaskPoolStates(repoRoot, featureId);
     const specs = new Map();
     for (const node of graph.nodes)
         specs.set(node.id, taskSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "tasks", node.task), "utf-8"))));

package/dist/worker/feature/decision-loader.js

@@ -46,16 +46,47 @@ async function auditTaskPoolFacts(repoRoot) {
     }
     const stateDir = path.join(getTaskPoolRoot(repoRoot), "states");
     try {
-        for (const entry of await readdir(stateDir))
-            if (entry.endsWith(".json"))
+        for (const entry of await readdir(stateDir, { withFileTypes: true })) {
+            if (entry.isFile() && entry.name.endsWith(".json")) {
                 try {
-                    const parsed = taskPoolStateFactSchema.safeParse(JSON.parse(await readFile(path.join(stateDir, entry), "utf-8")));
-                    if (!parsed.success || parsed.data.taskId !== entry.slice(0, -5))
-                        warnings.push(`Task Pool state is semantically invalid: ${entry}`);
+                    const parsed = taskPoolStateFactSchema.safeParse(JSON.parse(await readFile(path.join(stateDir, entry.name), "utf-8")));
+                    if (!parsed.success || parsed.data.taskId !== entry.name.slice(0, -5)) {
+                        warnings.push(`Task Pool state is semantically invalid: ${entry.name}`);
+                    }
+                    else {
+                        warnings.push(`legacy Task Pool state requires migration: ${entry.name}`);
+                    }
                 }
                 catch {
-                    warnings.push(`Task Pool state is corrupt: ${entry}`);
+                    warnings.push(`Task Pool state is corrupt: ${entry.name}`);
                 }
+                continue;
+            }
+            if (!entry.isDirectory())
+                continue;
+            const featureId = entry.name;
+            try {
+                for (const stateName of await readdir(path.join(stateDir, featureId))) {
+                    if (!stateName.endsWith(".json"))
+                        continue;
+                    const relative = `${featureId}/${stateName}`;
+                    try {
+                        const parsed = taskPoolStateFactSchema.safeParse(JSON.parse(await readFile(path.join(stateDir, featureId, stateName), "utf-8")));
+                        const expectedTaskId = stateName.slice(0, -5);
+                        if (!parsed.success || parsed.data.taskId !== expectedTaskId || parsed.data.featureId !== featureId) {
+                            warnings.push(`Task Pool state is semantically invalid: ${relative}`);
+                        }
+                    }
+                    catch {
+                        warnings.push(`Task Pool state is corrupt: ${relative}`);
+                    }
+                }
+            }
+            catch (error) {
+                if (!isNotFound(error))
+                    warnings.push(`Task Pool states for ${featureId} are unreadable: ${message(error)}`);
+            }
+        }
     }
     catch (error) {
         if (!isNotFound(error))

package/dist/worker/feature/next-action.js

@@ -35,7 +35,7 @@ export function projectNextAction(input, status) {
             return {
                 kind: "retry_task",
                 label: `重试环境失败任务 ${failed.taskId}`,
-                command: `agent-worker task retry ${quote(failed.taskId)} --repo ${quote(input.repoRoot)}`,
+                command: `agent-worker task retry ${quote(failed.taskId)} --feature-id ${quote(input.featureId)} --repo ${quote(input.repoRoot)}`,
             };
         }
         return {
@@ -51,9 +51,17 @@ export function projectNextAction(input, status) {
         };
     }
     if (status === "ready") {
+        const selected = input.planning?.selected[0];
+        const deferredCount = input.planning?.deferred.length ?? 0;
+        const blockedCount = input.planning?.blocked.length ?? 0;
+        const reasonSuffix = selected && (deferredCount > 0 || blockedCount > 0)
+            ? `；deferred ${deferredCount} / blocked ${blockedCount}`
+            : "";
         return {
             kind: "run_feature",
-            label: "执行当前 Ready tasks",
+            label: selected
+                ? `执行最高优先级 Ready task ${selected.taskId} (${selected.priority})${reasonSuffix}`
+                : "执行当前 Ready tasks",
             command: `agent-worker batch run-ready ${featureArgs}`,
         };
     }