@guanlin4924/devflow-pi 0.1.19 → 0.1.20

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.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 {
@@ -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",
@@ -515,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);
 }
 
@@ -967,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,
@@ -1520,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(),
@@ -1542,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(","));
       }
@@ -1588,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",

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/acceptance_test_runner.py

@@ -0,0 +1,394 @@
+#!/usr/bin/env python3
+"""Execute only adapters bound to a frozen TC suite; never derive scope from delivery prose."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode, urljoin
+from urllib.request import Request, urlopen
+
+from test_command_policy import validate_test_command
+
+
+FEATURE_RE = re.compile(r"^[^/\\\x00-\x1f\x7f]+$")
+AUTOMATION_MODES = {"automated", "manual", "blocked"}
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def digest(value: str | bytes) -> str:
+    if isinstance(value, str):
+        value = value.encode("utf-8")
+    return hashlib.sha256(value).hexdigest()
+
+
+def read_json(path: Path, errors: list[str], label: str) -> dict[str, Any] | None:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        errors.append(f"missing {label}: {path.as_posix()}")
+        return None
+    except json.JSONDecodeError as error:
+        errors.append(f"invalid {label}: {error.msg}")
+        return None
+    if not isinstance(value, dict):
+        errors.append(f"invalid {label}: root must be an object")
+        return None
+    return value
+
+
+def write_json(path: Path, value: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.tmp")
+    temporary.write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    temporary.replace(path)
+
+
+def valid_argv(value: Any) -> bool:
+    return isinstance(value, list) and bool(value) and all(isinstance(token, str) and token and "\x00" not in token for token in value)
+
+
+ENV_NAME_RE = re.compile(r"^[A-Z_][A-Z0-9_]*$")
+
+
+def valid_http_adapter(value: Any) -> bool:
+    if not isinstance(value, dict) or value.get("kind") != "http" or not isinstance(value.get("base_url_env"), str) or not ENV_NAME_RE.fullmatch(value["base_url_env"]):
+        return False
+    headers_env = value.get("headers_env", {})
+    if not isinstance(headers_env, dict) or not all(isinstance(header, str) and header and isinstance(env, str) and ENV_NAME_RE.fullmatch(env) for header, env in headers_env.items()):
+        return False
+    setup = value.get("setup")
+    return setup is None or (isinstance(setup, dict) and valid_argv(setup.get("argv")))
+
+
+def pointer_value(document: Any, pointer: str) -> Any:
+    if pointer == "":
+        return document
+    if not isinstance(pointer, str) or not pointer.startswith("/"):
+        raise ValueError("error_code_pointer must be an RFC 6901 JSON pointer")
+    current = document
+    for token in pointer[1:].split("/"):
+        token = token.replace("~1", "/").replace("~0", "~")
+        if isinstance(current, dict) and token in current:
+            current = current[token]
+        elif isinstance(current, list) and token.isdigit() and int(token) < len(current):
+            current = current[int(token)]
+        else:
+            raise KeyError(pointer)
+    return current
+
+
+def http_execution_error(source: dict[str, Any]) -> str | None:
+    execution = source.get("execution")
+    if not isinstance(execution, dict) or execution.get("protocol") != "http":
+        return "frozen TC has no HTTP execution definition"
+    request = execution.get("request")
+    expect = execution.get("expect")
+    if not isinstance(request, dict) or not isinstance(expect, dict):
+        return "frozen TC HTTP execution requires request and expect"
+    if not isinstance(request.get("method"), str) or not re.fullmatch(r"[A-Z]+", request["method"]):
+        return "frozen TC HTTP request method is invalid"
+    if not isinstance(request.get("path"), str) or not request["path"].startswith("/"):
+        return "frozen TC HTTP request path is invalid"
+    if not isinstance(expect.get("http_status"), int) or not 100 <= expect["http_status"] <= 599:
+        return "frozen TC HTTP expectation http_status is invalid"
+    for key in ("path_params", "query", "headers", "body"):
+        if key in request and not isinstance(request[key], dict):
+            return f"frozen TC HTTP request {key} must be an object"
+    if "error_code" in expect and (not isinstance(expect["error_code"], str) or not expect["error_code"].strip()):
+        return "frozen TC HTTP expectation error_code is invalid"
+    if "error_code_pointer" in expect and (not isinstance(expect["error_code_pointer"], str) or not expect["error_code_pointer"].startswith("/")):
+        return "frozen TC HTTP expectation error_code_pointer is invalid"
+    return None
+
+
+def frozen_cases(suite: dict[str, Any], errors: list[str]) -> dict[str, dict[str, Any]]:
+    cases: dict[str, dict[str, Any]] = {}
+    for node in suite.get("nodes", []):
+        if not isinstance(node, dict) or node.get("kind") != "test_case":
+            continue
+        tc_id = node.get("id")
+        data = node.get("data")
+        if not isinstance(tc_id, str) or not isinstance(data, dict):
+            errors.append("invalid test_case node in TC suite")
+            continue
+        if node.get("status") != "confirmed" or node.get("stale") is True:
+            errors.append(f"TC is not frozen and fresh: {tc_id}")
+        cases[tc_id] = data
+    if not cases:
+        errors.append("TC suite contains no test_case nodes")
+    return cases
+
+
+def paths(root: Path, feature: str) -> tuple[Path, Path, Path]:
+    return (
+        root / ".planning" / "requirements" / feature / "tests.json",
+        root / ".planning" / "features" / feature / "acceptance-test-bindings.json",
+        root / ".planning" / "test-runs" / feature / "acceptance-results.json",
+    )
+
+
+def file_fingerprint(path: Path) -> str | None:
+    return digest(path.read_bytes()) if path.is_file() else None
+
+
+def run_http_case(source: dict[str, Any], adapter: dict[str, Any]) -> tuple[bool, int, str]:
+    execution = source["execution"]
+    request_spec = execution["request"]
+    expect = execution["expect"]
+    base_url = os.environ.get(adapter["base_url_env"])
+    if not base_url:
+        return False, 127, f"required test base URL environment variable is unset: {adapter['base_url_env']}"
+    setup_output = ""
+    setup = adapter.get("setup")
+    if isinstance(setup, dict):
+        try:
+            completed = subprocess.run(setup["argv"], text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=180, check=False)
+            setup_output = f"setup exit={completed.returncode}: {completed.stdout}\n{completed.stderr}"
+            if completed.returncode != 0:
+                return False, completed.returncode, setup_output
+        except subprocess.TimeoutExpired as error:
+            return False, 124, f"setup command timed out: {error}"
+        except OSError as error:
+            return False, 127, f"setup command could not start: {error}"
+    path = request_spec["path"]
+    for key, value in request_spec.get("path_params", {}).items():
+        path = path.replace("{" + str(key) + "}", str(value)).replace(":" + str(key), str(value))
+    query = request_spec.get("query", {})
+    url = urljoin(base_url.rstrip("/") + "/", path.lstrip("/"))
+    if query:
+        url += ("&" if "?" in url else "?") + urlencode(query, doseq=True)
+    headers = {str(key): str(value) for key, value in request_spec.get("headers", {}).items()}
+    for header, env_name in adapter.get("headers_env", {}).items():
+        value = os.environ.get(env_name)
+        if not value:
+            return False, 127, f"required test header environment variable is unset: {env_name}"
+        headers[header] = value
+    body = request_spec.get("body")
+    payload: bytes | None = None
+    if body is not None:
+        payload = json.dumps(body, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+        headers.setdefault("Content-Type", "application/json")
+    request = Request(url, data=payload, headers=headers, method=request_spec["method"])
+    try:
+        with urlopen(request, timeout=20) as response:
+            http_status = response.status
+            output = response.read().decode("utf-8", errors="replace")
+    except HTTPError as error:
+        http_status = error.code
+        output = error.read().decode("utf-8", errors="replace")
+    except (URLError, OSError) as error:
+        return False, 127, f"{setup_output}\nHTTP adapter could not complete request: {error}"
+    expected_status = expect["http_status"]
+    if http_status != expected_status:
+        return False, 1, f"{setup_output}\nexpected HTTP {expected_status}, got {http_status}; body={output[:1000]}"
+    if "error_code" in expect:
+        try:
+            body_json = json.loads(output)
+            actual_code = pointer_value(body_json, expect.get("error_code_pointer", "/error/code"))
+        except (json.JSONDecodeError, KeyError, ValueError) as error:
+            return False, 1, f"{setup_output}\ncould not read expected error code from response: {error}; body={output[:1000]}"
+        if actual_code != expect["error_code"]:
+            return False, 1, f"{setup_output}\nexpected error code {expect['error_code']}, got {actual_code!r}; body={output[:1000]}"
+    return True, 0, f"{setup_output}\nHTTP {http_status} matched expectation"
+
+
+def validate(root: Path, feature: str) -> tuple[dict[str, Any], dict[str, Any] | None, dict[str, Any] | None]:
+    errors: list[str] = []
+    suite_path, binding_path, _ = paths(root, feature)
+    suite = read_json(suite_path, errors, "TC suite")
+    bindings = read_json(binding_path, errors, "acceptance-test bindings")
+    if suite is None or bindings is None:
+        return {"ok": False, "feature": feature, "errors": errors}, suite, bindings
+    cases = frozen_cases(suite, errors)
+    if bindings.get("schema_version") != 1:
+        errors.append("acceptance-test bindings schema_version must be 1")
+    if bindings.get("origin") != "devflow_acceptance_test_execution":
+        errors.append("acceptance-test bindings origin must be devflow_acceptance_test_execution")
+    if bindings.get("feature") != feature:
+        errors.append("acceptance-test bindings feature does not match requested feature")
+    pin = bindings.get("test_suite")
+    meta = suite.get("view_meta") if isinstance(suite.get("view_meta"), dict) else {}
+    if not isinstance(pin, dict):
+        errors.append("test_suite pin is required")
+    else:
+        if pin.get("graph_revision") != suite.get("graph_revision"):
+            errors.append("test_suite.graph_revision does not match current TC suite")
+        if pin.get("fingerprint") != meta.get("fingerprint"):
+            errors.append("test_suite.fingerprint does not match current TC suite")
+
+    entries = bindings.get("cases")
+    if not isinstance(entries, list) or not entries:
+        errors.append("cases must be a non-empty array")
+        entries = []
+    seen: set[str] = set()
+    for index, entry in enumerate(entries):
+        label = f"cases[{index}]"
+        if not isinstance(entry, dict):
+            errors.append(f"{label} must be an object")
+            continue
+        tc_id = entry.get("tc_id")
+        if not isinstance(tc_id, str) or not tc_id:
+            errors.append(f"{label}.tc_id is required")
+            continue
+        if tc_id in seen:
+            errors.append(f"duplicate acceptance-test binding: {tc_id}")
+        seen.add(tc_id)
+        source = cases.get(tc_id)
+        if source is None:
+            errors.append(f"unknown TC reference: {tc_id}")
+            continue
+        mode = entry.get("mode")
+        if mode not in AUTOMATION_MODES:
+            errors.append(f"{label}.mode is invalid")
+            continue
+        if mode != source.get("automation_mode"):
+            errors.append(f"{label}.mode must match frozen TC automation_mode")
+        if mode == "automated":
+            adapter = entry.get("adapter")
+            if not isinstance(adapter, dict):
+                errors.append(f"{label}.adapter is required")
+            elif adapter.get("kind") == "command":
+                if not valid_argv(adapter.get("argv")):
+                    errors.append(f"{label}.adapter command requires non-empty argv")
+                    continue
+                command_error = validate_test_command(root, adapter["argv"])
+                if command_error:
+                    errors.append(f"{label}.adapter: {command_error}")
+            elif adapter.get("kind") == "http":
+                if not valid_http_adapter(adapter):
+                    errors.append(f"{label}.adapter HTTP requires base_url_env, valid optional headers_env, and optional setup.argv")
+                else:
+                    execution_error = http_execution_error(source)
+                    if execution_error:
+                        errors.append(f"{label}.adapter: {execution_error}")
+                    if isinstance(adapter.get("setup"), dict):
+                        setup_error = validate_test_command(root, adapter["setup"]["argv"])
+                        if setup_error:
+                            errors.append(f"{label}.adapter.setup: {setup_error}")
+            else:
+                errors.append(f"{label}.adapter kind must be command or http")
+        elif mode == "manual":
+            if not isinstance(entry.get("owner"), str) or not entry["owner"].strip() or not isinstance(entry.get("reason"), str) or not entry["reason"].strip():
+                errors.append(f"{label}.manual requires owner and reason")
+        elif mode == "blocked":
+            if not isinstance(entry.get("blocked_by"), str) or not entry["blocked_by"].strip() or not isinstance(entry.get("owner"), str) or not entry["owner"].strip():
+                errors.append(f"{label}.blocked requires blocked_by and owner")
+    for tc_id in sorted(set(cases) - seen):
+        errors.append(f"unbound frozen TC: {tc_id}")
+    return {"ok": not errors, "feature": feature, "tc_ids": sorted(cases), "errors": errors}, suite, bindings
+
+
+def run(root: Path, feature: str, write: bool) -> dict[str, Any]:
+    validation, suite, bindings = validate(root, feature)
+    if not validation["ok"]:
+        return validation
+    assert suite is not None and bindings is not None
+    cases = frozen_cases(suite, [])
+    _, _, result_path = paths(root, feature)
+    previous = read_json(result_path, [], "previous acceptance-test results")
+    task_bindings_path = root / ".planning" / "features" / feature / "test-bindings.json"
+    execution_bindings_path = root / ".planning" / "features" / feature / "acceptance-test-bindings.json"
+    results: list[dict[str, Any]] = []
+    for entry in bindings["cases"]:
+        tc_id = entry["tc_id"]
+        mode = entry["mode"]
+        if mode == "automated":
+            started_at = utc_now()
+            adapter = entry["adapter"]
+            if adapter["kind"] == "command":
+                argv = adapter["argv"]
+                try:
+                    completed = subprocess.run(argv, cwd=root, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=180, check=False)
+                    exit_code = completed.returncode
+                    output = f"{completed.stdout}\n{completed.stderr}"
+                except subprocess.TimeoutExpired as error:
+                    exit_code = 124
+                    output = f"command timed out: {error}"
+                except OSError as error:
+                    exit_code = 127
+                    output = f"command could not start: {error}"
+                result = {"tc_id": tc_id, "status": "passed" if exit_code == 0 else "failed", "mode": mode, "adapter_kind": "command", "argv": argv,
+                          "command_hash": digest(json.dumps(argv, ensure_ascii=False, separators=(",", ":"))), "started_at": started_at,
+                          "finished_at": utc_now(), "exit_code": exit_code, "output_sha256": digest(output)}
+            else:
+                passed, exit_code, output = run_http_case(cases[tc_id], adapter)
+                result = {"tc_id": tc_id, "status": "passed" if passed else "failed", "mode": mode, "adapter_kind": "http",
+                          "adapter_fingerprint": digest(json.dumps(adapter, ensure_ascii=False, separators=(",", ":"))), "started_at": started_at,
+                          "finished_at": utc_now(), "exit_code": exit_code, "output_sha256": digest(output)}
+            results.append(result)
+        elif mode == "manual":
+            results.append({"tc_id": tc_id, "status": "blocked", "mode": mode, "owner": entry["owner"], "reason": entry["reason"],
+                            "blocked_by": "manual execution has no Core-observed result"})
+        else:
+            results.append({"tc_id": tc_id, "status": "blocked", "mode": mode, "owner": entry["owner"], "blocked_by": entry["blocked_by"]})
+    all_passed = all(item["status"] == "passed" for item in results)
+    history = previous.get("history", []) if isinstance(previous, dict) and isinstance(previous.get("history"), list) else []
+    if isinstance(previous, dict) and isinstance(previous.get("results"), list):
+        history = [*history, {"executed_at": previous.get("executed_at"), "passed": previous.get("passed"), "test_suite": previous.get("test_suite"),
+                              "implementation_task_bindings": previous.get("implementation_task_bindings"), "execution_binding_fingerprint": previous.get("execution_binding_fingerprint"),
+                              "results": previous["results"]}]
+    payload = {"schema_version": 1, "origin": "core_acceptance_test_runner", "feature": feature, "executed_at": utc_now(),
+               "test_suite": bindings["test_suite"], "implementation_task_bindings": {"path": str(task_bindings_path.relative_to(root)), "fingerprint": file_fingerprint(task_bindings_path)},
+               "execution_binding_fingerprint": file_fingerprint(execution_bindings_path), "results": results, "passed": all_passed, "history": history[-20:]}
+    if write:
+        write_json(result_path, payload)
+    return {"ok": all_passed, "feature": feature, "path": str(result_path.relative_to(root)), "results": results,
+            "errors": [] if all_passed else ["one or more frozen TC cases failed or are blocked"]}
+
+
+def validate_results(root: Path, feature: str) -> dict[str, Any]:
+    validation, suite, _ = validate(root, feature)
+    errors = list(validation["errors"])
+    _, _, result_path = paths(root, feature)
+    results = read_json(result_path, errors, "acceptance-test results")
+    if suite is None or results is None:
+        return {"ok": False, "feature": feature, "errors": errors}
+    if results.get("origin") != "core_acceptance_test_runner" or results.get("feature") != feature:
+        errors.append("acceptance-test results identity is invalid")
+    meta = suite.get("view_meta") if isinstance(suite.get("view_meta"), dict) else {}
+    if results.get("test_suite") != {"graph_revision": suite.get("graph_revision"), "fingerprint": meta.get("fingerprint")}:
+        errors.append("acceptance-test results are pinned to a stale TC suite")
+    expected = set(validation.get("tc_ids", []))
+    result_entries = results.get("results") if isinstance(results.get("results"), list) else []
+    actual = {item.get("tc_id") for item in result_entries if isinstance(item, dict) and isinstance(item.get("tc_id"), str)}
+    if actual != expected:
+        errors.append("acceptance-test results do not cover exactly the frozen TC suite")
+    failed = sorted(item.get("tc_id", "<unknown>") for item in result_entries if not isinstance(item, dict) or item.get("status") != "passed")
+    if failed:
+        errors.append(f"frozen TC cases not passed: {', '.join(failed)}")
+    return {"ok": not errors, "feature": feature, "errors": errors, "result_path": str(result_path.relative_to(root))}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("action", choices=("validate", "run", "validate-results"))
+    parser.add_argument("--feature", required=True)
+    parser.add_argument("--write", action="store_true")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+    root = Path.cwd().resolve()
+    if not FEATURE_RE.fullmatch(args.feature):
+        result = {"ok": False, "errors": ["invalid feature"]}
+    elif args.action == "validate":
+        result, _, _ = validate(root, args.feature)
+    elif args.action == "run":
+        result = run(root, args.feature, args.write) if args.write else {"ok": False, "errors": ["--write is required for run"]}
+    else:
+        result = validate_results(root, args.feature)
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())