@guanlin4924/devflow-pi 0.1.19 → 0.1.21

package/README.md

@@ -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.19",
+  "version": "0.1.21",
   "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 {
@@ -335,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",
@@ -353,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",
@@ -371,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",
@@ -408,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",
@@ -496,12 +512,21 @@ function assertRuntimeProjectBoundary(cwd: string): void {
       if (!canonical.startsWith(`${resolvedCwd}${path.sep}`)) {
         throw new Error(`Devflow control path escapes project boundary: ${canonical}`);
       }
+      if (lstatSync(target).isDirectory()) assertNoSymlinkDescendantsSync(target);
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
     }
   }
 }
 
+function assertNoSymlinkDescendantsSync(target: string): void {
+  for (const entry of readdirSync(target, { withFileTypes: true })) {
+    const child = path.join(target, entry.name);
+    if (entry.isSymbolicLink()) throw new Error(`Refusing symlinked Devflow control path: ${child}`);
+    if (entry.isDirectory()) assertNoSymlinkDescendantsSync(child);
+  }
+}
+
 function safeControlPath(cwd: string, raw: string | undefined, kind: "state" | "workflow"): string | undefined {
   if (raw === undefined) return undefined;
   if (path.isAbsolute(raw)) throw new Error(`${kind} path must be project-relative`);
@@ -515,7 +540,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);
 }
 
@@ -967,6 +992,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,
@@ -1520,7 +1554,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(),
@@ -1542,6 +1576,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(","));
       }
@@ -1588,6 +1630,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",
@@ -2131,7 +2280,7 @@ export default function devflowCore(pi: ExtensionAPI) {
   pi.registerTool({
     name: "devflow_skill_script",
     label: "Devflow Skill Script",
-    description: "Run an allowlisted deterministic script bundled with a Devflow skill without relying on a .skills filesystem path.",
+    description: "Run an allowlisted deterministic script bundled with a Devflow skill. project-context-validate is a final initialization gate: call it only after all manifest outputs and current-run markers are written.",
     parameters: z.object({
       script: z.enum([
         "project-context-validate",