@guanlin4924/devflow-pi 0.1.18 → 0.1.20

package/README.md

@@ -34,7 +34,7 @@ devflow-pi
 /usage-stats
 ```
 
-`/devflow project-init` 会在边界确认时提供两种模式：`plan`（默认，只读规划）和 `apply`（写入初始化）。选择 `apply` 并确认后，只会创建 Devflow 的 `.planning/` 与 `.context/` 初始化产物，不会修改业务源码、依赖或项目配置。
+`/devflow project-init` 会先读取当前项目已有的 `.planning/PROJECT.md` 与 `.planning/navigation/INDEX.md`：仅回填仍存在于项目根目录内的已登记前后端路径，删除或越界的历史路径会被忽略。随后可选择复用已有边界、复用边界并重建索引，或手动覆盖。初始化模式使用选择器提供“只读规划（默认）”和“写入初始化”；选择后者并确认，只会创建 Devflow 的 `.planning/` 与 `.context/` 初始化产物，不会修改业务源码、依赖或项目配置。
 
 用量统计默认只读取当前项目的隔离会话：`/usage-stats`。需要明确查看历史 OMP 会话时，使用 `/usage-stats omp`，或加筛选条件：`/usage-stats omp --from 2026-08-01 --to 2026-08-10`。历史统计保留真实会话路径，不再把不同项目的长会话文件合并成 `main`；统计只使用 assistant message 的原始 usage，不虚构工具调用成本分摊。
 
@@ -119,6 +119,25 @@ bash .skills/install.sh --apply --force-config
 
 `/devflow start` 会先进入安全的需求梳理：可澄清并只读检查，不写入项目。用户随后直接补充需求，原文会被带入入口分诊并启动当前步骤。每个步骤结束后，系统展示产物和证据；用户明确回复“批准执行”才会推进并运行下一步，回复修改意见或“拒绝执行”则保持原步骤。普通需求描述绝不会自动确认 checkpoint。`/devflow explain-state` 发现控制面和制品 registry 漂移时会给出只读恢复计划；用户审查后可用 `/devflow recover` 确认仅修复可由文件系统证明的 registry 字段，它绝不推进步骤或自动通过 checkpoint。恢复已有流程使用 `/devflow resume`，它同样只恢复状态而不自动执行。
 
+### 需求验收测试与 TDD 证据链
+
+新建功能在 `integration-verify` 后会先生成独立的 `TC-*` 验收测试设计，再生成变更清单：
+
+```text
+已确认需求/契约/架构事实 → TC-* 候选 → 变更清单（任务 ↔ 候选 TC 绑定）
+                                                        ↓
+                    CP-3：校验候选绑定 → 冻结 TC → 写入 Core attestation
+                                                        ↓
+                    RED / GREEN / REGRESSION 证据 → 按冻结 TC 执行 API / 页面 / 专项测试 → UAT → CP-4
+```
+
+- `TC-*` 的步骤和 oracle 在代码出现前冻结；CP-3 在同一次确认中先校验候选绑定，再冻结 TC 并固定绑定哈希。需求或契约变化会使它 stale，不能继续以旧测试集宣称通过。
+- `tdd_required` 任务必须先由 Core 记录准备快照，再记录 RED（命中预期失败）、同一目标的 GREEN 和回归；缺失或环境失败不算完成。
+- API、跨数据域、边界、迁移、工作负载与架构风险会派生相应的 `api`、`permission`、`boundary`、`migration`、`performance`、`resilience` TC 义务。
+- 代码完成后，`workflow-run-acceptance-tests` 只能运行绑定到冻结 TC、且已在初始化 `.planning/toolchain.md` 发现的测试运行器命令。任何失败、未执行、人工待执行或环境阻塞用例都会阻止 CP-4。
+
+正常使用不需要记忆底层命令：在 Devflow 工作流中按步骤继续即可。需要排查时，可用 `devflow_acceptance_tests` 查看冻结套件，或由工作流调用 `devflow_tdd_evidence` 与 `devflow_run_acceptance_tests` 生成 Core-owned 证据；不要手写“已测试”来替代结果文件。
+
 ## Marketplace 能力包
 
 仓库也可作为 OMP marketplace 使用，但 Marketplace 安装只用于发现和安装 Skills、Agents、命令等能力内容，不代表完整 Devflow Runtime 已启用。OMP 不会从 Marketplace 安装加载 `package.json` 中的 `omp.extensions`，因此下面的命令不能替代 `bash .skills/install.sh --apply`：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "type": "module",
   "description": "Devflow 专项研发 Pi，基于固定版本 OMP Runtime 组装研发状态机、代码智能、设计、实现与质量门禁。",
   "license": "UNLICENSED",
@@ -11,8 +11,8 @@
     "dev": "bun run src/cli.ts",
     "doctor": "bun run src/cli.ts doctor",
     "test:devflow-pi": "bun test tests/devflow-pi",
-    "test": "bun test tests/devflow-pi && python -m pytest",
-    "check": "bun test tests/devflow-pi && python -m pytest"
+    "test": "bun test tests/devflow-pi && python3 -m unittest discover -s tests -p 'test_*.py'",
+    "check": "bun test tests/devflow-pi && python3 -m unittest discover -s tests -p 'test_*.py'"
   },
   "engines": {
     "bun": ">=1.3.14"

package/plugins/devflow-core/extensions/devflow-core.ts

@@ -52,6 +52,7 @@ const READ_ONLY_TOOLS = new Set([
   "devflow_doctor",
   "devflow_code_index",
   "devflow_context_cursor",
+  "devflow_acceptance_tests",
   "devflow_usage_stats",
   "usage_stats",
 ]);
@@ -68,7 +69,10 @@ const STATE_MUTATION_TOOLS = new Set([
   "devflow_bootstrap",
   "devflow_transition",
   "devflow_artifact",
+  "devflow_api_test_matrix",
   "devflow_evidence",
+  "devflow_tdd_evidence",
+  "devflow_run_acceptance_tests",
 ]);
 
 export function initialControlState(): SessionControlState {
@@ -98,11 +102,116 @@ export function planningState(intent: "project-init" | "requirement-draft"): Ses
   };
 }
 
-function parseProjectInitializationMode(value: string): ProjectInitializationMode | null {
-  const normalized = value.trim().toLowerCase();
-  if (["", "plan", "readonly", "read-only", "只读", "规划"].includes(normalized)) return "plan";
-  if (["apply", "write", "写入", "执行"].includes(normalized)) return "apply";
-  return null;
+export type ExistingProjectInitialization = {
+  projectName?: string;
+  frontendPaths: string[];
+  backendPaths: string[];
+  codeIndexStatus?: string;
+  sourcePath: string;
+};
+
+type DocumentedProjectLocations = {
+  frontendPaths: string[];
+  backendPaths: string[];
+};
+
+function markdownTableCells(line: string): string[] | null {
+  if (!line.trim().startsWith("|")) return null;
+  const cells = line.trim().split("|").slice(1, -1).map(cell => cell.trim());
+  return cells.length > 0 ? cells : null;
+}
+
+function documentedProjectPath(raw: string, cwd: string): string | null {
+  const cleaned = raw
+    .replaceAll("`", "")
+    .replaceAll("~", "")
+    .replaceAll("*", "")
+    .replace(/\s*[（(].*$/, "")
+    .trim();
+  if (!cleaned) return null;
+  const absolute = path.resolve(cwd, cleaned);
+  const relative = path.relative(cwd, absolute).replaceAll("\\", "/");
+  if (!relative || relative === ".." || relative.startsWith("../") || path.isAbsolute(relative)) return null;
+  if (!existsSync(absolute)) return null;
+  return relative;
+}
+
+function documentedLocations(markdown: string, cwd: string): DocumentedProjectLocations {
+  const frontendPaths: string[] = [];
+  const backendPaths: string[] = [];
+  const lines = markdown.split(/\r?\n/);
+  for (let index = 0; index < lines.length - 2; index += 1) {
+    const header = markdownTableCells(lines[index]);
+    const divider = markdownTableCells(lines[index + 1]);
+    if (!header || !divider || !divider.every(cell => /^:?-{3,}:?$/.test(cell))) continue;
+    const pathColumn = header.findIndex(cell => /^(?:path|路径)$/i.test(cell));
+    const typeColumn = header.findIndex(cell => /^(?:type|类型)$/i.test(cell));
+    if (pathColumn < 0 || typeColumn < 0) continue;
+    for (let rowIndex = index + 2; rowIndex < lines.length; rowIndex += 1) {
+      const row = markdownTableCells(lines[rowIndex]);
+      if (!row || row.length !== header.length) break;
+      const projectPath = documentedProjectPath(row[pathColumn], cwd);
+      if (!projectPath) continue;
+      const type = row[typeColumn];
+      if (/(?:前端|frontend|\bh5\b|小程序|uniapp)/i.test(type)) frontendPaths.push(projectPath);
+      if (/(?:后端|backend|服务|\bapi\b)/i.test(type)) backendPaths.push(projectPath);
+    }
+  }
+  return {
+    frontendPaths: [...new Set(frontendPaths)],
+    backendPaths: [...new Set(backendPaths)],
+  };
+}
+
+function documentedProjectName(markdown: string): string | undefined {
+  const match = markdown.match(/^\s*-\s*\*\*Name\*\*:\s*(.+?)\s*$/mi);
+  return match?.[1]?.trim() || undefined;
+}
+
+function documentedCodeIndexStatus(markdown: string): string | undefined {
+  const comment = markdown.match(/code_index_status:\s*([^;\-\n]+)/i);
+  if (comment?.[1]?.trim()) return comment[1].trim();
+  const field = markdown.match(/^\s*-\s*\*\*Code Index Status\*\*:\s*([^\n]+)/mi);
+  return field?.[1]?.trim() || undefined;
+}
+
+/**
+ * Reuses only existing, project-local initialization records.  Markdown is
+ * evidence, not authority by itself: every documented path must still exist
+ * beneath the current project root before it can be offered back to the user.
+ */
+export function discoverExistingProjectInitialization(cwd: string): ExistingProjectInitialization | null {
+  const sources = [".planning/PROJECT.md", ".planning/navigation/INDEX.md"];
+  const records: Array<ExistingProjectInitialization> = [];
+  for (const sourcePath of sources) {
+    const absolute = path.join(cwd, sourcePath);
+    if (!existsSync(absolute)) continue;
+    const markdown = readFileSync(absolute, "utf8");
+    const locations = documentedLocations(markdown, cwd);
+    if (locations.frontendPaths.length === 0 && locations.backendPaths.length === 0) continue;
+    records.push({
+      projectName: documentedProjectName(markdown),
+      frontendPaths: locations.frontendPaths,
+      backendPaths: locations.backendPaths,
+      codeIndexStatus: documentedCodeIndexStatus(markdown),
+      sourcePath,
+    });
+  }
+  const preferred = records[0];
+  if (!preferred) return null;
+  const fallback = records.find(record => record !== preferred);
+  const useFallbackFrontend = preferred.frontendPaths.length === 0 && Boolean(fallback?.frontendPaths.length);
+  const useFallbackBackend = preferred.backendPaths.length === 0 && Boolean(fallback?.backendPaths.length);
+  return {
+    projectName: preferred.projectName ?? fallback?.projectName,
+    frontendPaths: preferred.frontendPaths.length > 0 ? preferred.frontendPaths : (fallback?.frontendPaths ?? []),
+    backendPaths: preferred.backendPaths.length > 0 ? preferred.backendPaths : (fallback?.backendPaths ?? []),
+    codeIndexStatus: preferred.codeIndexStatus ?? fallback?.codeIndexStatus,
+    sourcePath: [
+      preferred.sourcePath,
+      ...((useFallbackFrontend || useFallbackBackend) && fallback ? [fallback.sourcePath] : []),
+    ].join(", "),
+  };
 }
 
 export function executingState(label = "当前工作流步骤执行"): SessionControlState {
@@ -230,6 +339,10 @@ const REQUIRED_EXTENSION_TOOLS = [
   "devflow_artifact",
   "devflow_machine_evidence",
   "devflow_requirement_graph",
+  "devflow_acceptance_tests",
+  "devflow_api_test_matrix",
+  "devflow_tdd_evidence",
+  "devflow_run_acceptance_tests",
   "devflow_evidence",
   "devflow_contract",
   "devflow_recovery",
@@ -248,6 +361,7 @@ const REQUIRED_SKILLS = [
   "workflow-api-call-guide",
   "workflow-api-contract",
   "workflow-api-supplement",
+  "workflow-acceptance-test-design",
   "workflow-audit-milestone",
   "workflow-backend-tech-spec",
   "workflow-bug-fix",
@@ -266,6 +380,7 @@ const REQUIRED_SKILLS = [
   "workflow-orchestrator",
   "workflow-pipeline",
   "workflow-project-context",
+  "workflow-run-acceptance-tests",
   "workflow-requirement-baseline",
   "workflow-requirement-triage",
   "workflow-ui-spec",
@@ -303,6 +418,12 @@ const REQUIRED_SCRIPTS = [
   "workflow-orchestrator/scripts/advance_state.rb",
   "workflow-orchestrator/scripts/sync_artifacts.rb",
   "workflow-orchestrator/scripts/requirement_graph.rb",
+  "workflow-orchestrator/scripts/acceptance_test_suite.rb",
+  "workflow-orchestrator/scripts/api_test_matrix.py",
+  "workflow-orchestrator/scripts/test_task_binding_check.py",
+  "workflow-orchestrator/scripts/test_command_policy.py",
+  "workflow-orchestrator/scripts/tdd_evidence.py",
+  "workflow-orchestrator/scripts/acceptance_test_runner.py",
   "workflow-orchestrator/scripts/machine_evidence.rb",
   "workflow-orchestrator/scripts/execution_contract.rb",
   "workflow-code-index/scripts/code_index.py",
@@ -410,7 +531,7 @@ function safeControlPath(cwd: string, raw: string | undefined, kind: "state" | "
 }
 
 function isCanonicalRequirementGraphPath(filePath: string): boolean {
-  return /^\.planning\/requirements\/[^/\\\x00-\x1F\x7F]+\/(?:governance|evidence|definitions|behavior-graph|requirement-graph|slices|acceptance|traceability|graph\.meta)\.json$/u.test(filePath)
+  return /^\.planning\/requirements\/[^/\\\x00-\x1F\x7F]+\/(?:governance|evidence|definitions|behavior-graph|requirement-graph|slices|acceptance|tests|traceability|graph\.meta)\.json$/u.test(filePath)
     || /^\.planning\/requirements\/[^/\\\x00-\x1F\x7F]+\/(?:context\/[^/\\]+\.json|control-events\.jsonl)$/u.test(filePath);
 }
 
@@ -740,32 +861,106 @@ export default function devflowCore(pi: ExtensionAPI) {
   }
 
   async function collectProjectInitialization(ctx: {
+    cwd: string;
     ui: {
+      select(title: string, options: Array<{ label: string; description?: string }>): Promise<string | undefined>;
       input(title: string, placeholder?: string): Promise<string | undefined>;
       confirm(title: string, message: string): Promise<boolean>;
       notify(message: string, type?: "info" | "warning" | "error"): void;
     };
   }): Promise<ProjectInitializationRequest | null> {
-    const projectName = await ctx.ui.input("Devflow 项目初始化", "项目名称（留空则使用当前目录）");
-    const frontendPath = await ctx.ui.input("前端边界", "前端目录；没有请填写 none");
-    if (frontendPath === undefined) return null;
-    const backendPath = await ctx.ui.input("后端边界", "后端目录；没有请填写 none");
-    if (backendPath === undefined) return null;
-    const buildIndex = await ctx.ui.input("代码索引", "建立索引？输入 yes 或 no");
-    if (buildIndex === undefined) return null;
-    const initializationMode = await ctx.ui.input("初始化方式", "输入 plan（只读规划，默认）或 apply（写入初始化）");
-    if (initializationMode === undefined) return null;
-    const mode = parseProjectInitializationMode(initializationMode);
-    if (!mode) {
-      ctx.ui.notify("初始化方式只能是 plan（只读规划）或 apply（写入初始化）；未写入任何文件。", "error");
-      return null;
+    const existing = discoverExistingProjectInitialization(ctx.cwd);
+    const reuseExisting = "使用已记录的项目结构（推荐）";
+    const rebuildExisting = "使用已记录的项目结构，并重新扫描代码";
+    const manualEntry = "我需要手动指定项目目录";
+
+    let projectName: string | undefined;
+    let frontendPath: string | undefined;
+    let backendPath: string | undefined;
+    let buildIndex: string | undefined;
+    let boundarySource: string | undefined;
+
+    if (existing) {
+      const frontend = existing.frontendPaths.length > 0 ? existing.frontendPaths.join(", ") : "未记录（unknown）";
+      const backend = existing.backendPaths.length > 0 ? existing.backendPaths.join(", ") : "未记录（unknown）";
+      const selected = await ctx.ui.select("检测到已有项目记录：这次初始化怎么处理？", [
+        {
+          label: reuseExisting,
+          description: `直接复用下面已核验、仍存在的目录，不重新扫描代码。\n前端：${frontend}\n后端：${backend}\n记录来源：${existing.sourcePath}${existing.codeIndexStatus ? `；索引状态：${existing.codeIndexStatus}` : ""}`,
+        },
+        {
+          label: rebuildExisting,
+          description: `沿用已登记目录，但重新扫描代码并更新索引。\n前端：${frontend}\n后端：${backend}`,
+        },
+        {
+          label: manualEntry,
+          description: "不采用上面的记录。我会依次询问项目名、前端目录和后端目录；目录均相对当前项目根目录。",
+        },
+      ]);
+      if (!selected) return null;
+      if (selected === reuseExisting || selected === rebuildExisting) {
+        projectName = existing.projectName;
+        frontendPath = existing.frontendPaths.join(", ") || "unknown";
+        backendPath = existing.backendPaths.join(", ") || "unknown";
+        buildIndex = selected === reuseExisting
+          ? `复用已有索引${existing.codeIndexStatus ? `（${existing.codeIndexStatus}）` : ""}`
+          : "yes";
+        boundarySource = `${existing.sourcePath}（已校验目录仍存在）`;
+      }
     }
+
+    if (!frontendPath || !backendPath || !buildIndex) {
+      projectName = await ctx.ui.input(
+        "项目显示名称（可留空）",
+        "用于 Devflow 文档标题；留空时使用当前目录名。例如：商城运营平台",
+      );
+      if (projectName === undefined) return null;
+      frontendPath = await ctx.ui.input(
+        "前端代码目录（相对当前项目根目录）",
+        "可填写多个目录，用英文逗号分隔。例：apps/admin, apps/h5；不确定请填 unknown",
+      );
+      if (frontendPath === undefined) return null;
+      backendPath = await ctx.ui.input(
+        "后端代码目录（相对当前项目根目录）",
+        "例：services/api 或 server；项目没有后端请填 none；不确定请填 unknown",
+      );
+      if (backendPath === undefined) return null;
+      const fullIndex = "建立完整代码索引（推荐）";
+      const skipIndex = "暂不建立代码索引";
+      const selectedIndex = await ctx.ui.select("是否扫描代码并建立索引？", [
+        {
+          label: fullIndex,
+          description: "扫描已确认的代码目录，建立调用关系和符号索引；后续需求与架构评估可直接复用。",
+        },
+        {
+          label: skipIndex,
+          description: "只建立项目说明与规则入口；后续需要源码级分析时再补建索引。",
+        },
+      ]);
+      if (!selectedIndex) return null;
+      buildIndex = selectedIndex === fullIndex ? "yes" : "no";
+    }
+    const planMode = "只读规划（不写任何项目文件）";
+    const applyMode = "写入初始化";
+    const selectedMode = await ctx.ui.select("确认这次初始化是否写入项目文件？", [
+      {
+        label: planMode,
+        description: "只读取项目和已有初始化记录，输出规划与待确认项；不写入任何项目文件。",
+      },
+      {
+        label: applyMode,
+        description: "确认范围后创建或更新 Devflow 初始化产物；不修改业务源码、依赖或项目配置。",
+      },
+    ]);
+    if (!selectedMode) return null;
+    const mode: ProjectInitializationMode = selectedMode === applyMode ? "apply" : "plan";
     const modeSummary = mode === "apply" ? "写入初始化" : "只读规划";
     const summary = [
       `项目名：${projectName?.trim() || "当前目录"}`,
       `前端：${frontendPath.trim() || "未提供"}`,
       `后端：${backendPath.trim() || "未提供"}`,
       `建立代码索引：${buildIndex.trim() || "未提供"}`,
+      ...(boundarySource ? [`边界来源：${boundarySource}`] : []),
       `初始化方式：${modeSummary}`,
     ].join("\n");
     const consequence = mode === "apply"
@@ -788,6 +983,15 @@ export default function devflowCore(pi: ExtensionAPI) {
     });
   }
 
+  async function runPython(cwd: string, relativeScript: string, args: string[]) {
+    assertRuntimeProjectBoundary(cwd);
+    const kitRoot = resolveKitRoot(cwd);
+    return runProcess(["python3", path.join(kitRoot, relativeScript), ...args], cwd, {
+      DEVFLOW_KIT_ROOT: kitRoot,
+      OMP_PROJECT_DIR: cwd,
+    });
+  }
+
   async function runHook(
     cwd: string,
     scriptName: string,
@@ -1341,7 +1545,7 @@ export default function devflowCore(pi: ExtensionAPI) {
       read: z.boolean().optional(),
       delta: z.object({
         op: z.enum(["add", "link", "update"]),
-        kind: z.enum(["source", "code", "term", "object", "behavior", "requirement", "rule", "boundary", "slice", "risk", "decision", "acceptance", "api", "workload_shape", "workload_constraint"]).optional(),
+        kind: z.enum(["source", "code", "term", "object", "behavior", "requirement", "rule", "boundary", "slice", "risk", "decision", "acceptance", "api", "workload_shape", "workload_constraint", "test_case"]).optional(),
         id: z.string().min(1).optional(),
         data: z.record(z.string(), z.unknown()).optional(),
         from: z.string().min(1).optional(),
@@ -1363,6 +1567,14 @@ export default function devflowCore(pi: ExtensionAPI) {
         if (params.expectedRevision === undefined || !params.delta) {
           return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "propose requires expectedRevision and delta" });
         }
+        if (params.delta.kind === "test_case" && activeContract?.step !== "acceptance-test-design") {
+          return renderResult({
+            ok: false,
+            exitCode: 1,
+            stdout: "",
+            stderr: "TC candidates are accepted only during the active acceptance-test-design contract.",
+          });
+        }
         args.push("--write", "--expected-revision", String(params.expectedRevision), "--delta-json", JSON.stringify(params.delta));
         if (activeContract?.allowedGraphDelta?.length) args.push("--allowed-kinds", activeContract.allowedGraphDelta.join(","));
       }
@@ -1409,6 +1621,113 @@ export default function devflowCore(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerTool({
+    name: "devflow_acceptance_tests",
+    label: "Devflow Acceptance Tests",
+    description: "Inspect the Core-owned frozen TC acceptance suite. CP-3, not an agent, freezes the suite.",
+    parameters: z.object({
+      feature: z.string().min(1),
+    }),
+    approval: "read",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      return renderResult(
+        await runRuby(ctx.cwd, "workflow-orchestrator/scripts/acceptance_test_suite.rb", ["inspect", "--feature", params.feature, "--json"]),
+        { feature: params.feature },
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_api_test_matrix",
+    label: "Devflow API Test Matrix",
+    description: "Compile complete API field-boundary, pairwise and error-code TC candidates; import them only during acceptance-test design.",
+    parameters: z.object({
+      action: z.enum(["compile", "import", "validate"]),
+      feature: z.string().min(1),
+    }),
+    approval: args => args.action === "validate" ? "read" : "write",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      if (params.action !== "validate" && activeContract?.step !== "acceptance-test-design") {
+        return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: "API test matrix compilation/import is allowed only during the active acceptance-test-design contract." });
+      }
+      if (params.action === "validate") {
+        const process = await runPython(ctx.cwd, "workflow-orchestrator/scripts/api_test_matrix.py", ["validate", "--feature", params.feature, "--json"]);
+        const payload = parseJsonResult(process);
+        const failed = payload && typeof payload === "object" && (payload as { ok?: unknown }).ok === false;
+        return renderResult(failed ? { ...process, ok: false, exitCode: process.exitCode || 1 } : process, { action: params.action, feature: params.feature });
+      }
+      const compiled = await runPython(ctx.cwd, "workflow-orchestrator/scripts/api_test_matrix.py", ["compile", "--feature", params.feature, "--write", "--json"]);
+      const compiledPayload = parseJsonResult(compiled);
+      if (!compiled.ok || !compiledPayload || typeof compiledPayload !== "object" || (compiledPayload as { ok?: unknown }).ok !== true) {
+        return renderResult({ ...compiled, ok: false, exitCode: compiled.exitCode || 1 }, { action: params.action, feature: params.feature });
+      }
+      if (params.action === "compile") return renderResult(compiled, { action: params.action, feature: params.feature });
+
+      const inspected = parseJsonResult(await runRuby(ctx.cwd, "workflow-orchestrator/scripts/requirement_graph.rb", ["inspect", "--feature", params.feature, "--json"]));
+      const revision = inspected && typeof inspected === "object" && typeof (inspected as { graph?: { revision?: unknown } }).graph?.revision === "number"
+        ? (inspected as { graph: { revision: number } }).graph.revision
+        : undefined;
+      if (revision === undefined) return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: "Could not read the current requirement-graph revision before importing API TC candidates." });
+      const imported = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/requirement_graph.rb", ["import-test-cases", "--feature", params.feature, "--write", "--expected-revision", String(revision), "--json"]);
+      const importedPayload = parseJsonResult(imported);
+      const failed = importedPayload && typeof importedPayload === "object" && (importedPayload as { ok?: unknown }).ok === false;
+      return renderResult(failed ? { ...imported, ok: false, exitCode: imported.exitCode || 1 } : imported, { action: params.action, feature: params.feature });
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_tdd_evidence",
+    label: "Devflow TDD Evidence",
+    description: "Core-owned preparation and RED/GREEN/REGRESSION evidence for a frozen tdd_required task binding.",
+    parameters: z.object({
+      action: z.enum(["prepare", "record", "inspect"]),
+      feature: z.string().min(1),
+      taskId: z.string().min(1),
+      stage: z.enum(["red", "green", "regression"]).optional(),
+    }),
+    approval: args => args.action === "inspect" ? "read" : "write",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      if (params.action === "record" && !params.stage) {
+        return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "record requires stage" });
+      }
+      const args = [params.action, "--feature", params.feature, "--task-id", params.taskId, "--json"];
+      if (params.action !== "inspect") args.push("--write");
+      if (params.stage) args.push("--stage", params.stage);
+      const process = await runPython(ctx.cwd, "workflow-orchestrator/scripts/tdd_evidence.py", args);
+      const payload = parseJsonResult(process);
+      const failed = payload && typeof payload === "object" && (payload as { ok?: unknown }).ok === false;
+      return renderResult(failed ? { ...process, ok: false, exitCode: process.exitCode || 1 } : process, {
+        action: params.action,
+        feature: params.feature,
+        taskId: params.taskId,
+        stage: params.stage,
+      });
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_run_acceptance_tests",
+    label: "Devflow Run Acceptance Tests",
+    description: "Validate or execute only command or portable HTTP adapters bound to the frozen TC acceptance suite.",
+    parameters: z.object({
+      action: z.enum(["validate", "run", "validate_results"]),
+      feature: z.string().min(1),
+    }),
+    approval: args => args.action === "run" ? "write" : "read",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const scriptAction = params.action === "validate_results" ? "validate-results" : params.action;
+      const args = [scriptAction, "--feature", params.feature, "--json"];
+      if (params.action === "run") args.push("--write");
+      const process = await runPython(ctx.cwd, "workflow-orchestrator/scripts/acceptance_test_runner.py", args);
+      const payload = parseJsonResult(process);
+      const failed = payload && typeof payload === "object" && (payload as { ok?: unknown }).ok === false;
+      return renderResult(failed ? { ...process, ok: false, exitCode: process.exitCode || 1 } : process, {
+        action: params.action,
+        feature: params.feature,
+      });
+    },
+  });
+
   pi.registerTool({
     name: "devflow_runtime_context",
     label: "Devflow Runtime Context",