@guanlin4924/devflow-pi 0.1.94 → 0.1.95

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/advance_state.rb

@@ -558,6 +558,13 @@ HARD_FAILURE_REASONS = %w[
   cross_track_consistency_failed
   business_cross_model_check_failed
   gate_boundary_rejected
+  acceptance_results_not_passed
+  execution_surface_mismatch
+  approval_invalid
+  human_result_unapproved
+  dsl_not_approved
+  environment_profile_not_approved
+  runtime_integrity_error
 ].freeze
 $devflow_advisories = []
 
@@ -588,6 +595,32 @@ rescue JSON::ParserError => error
   { "ok" => false, "reason" => "test_task_binding_#{stage}_check_failed", "errors" => ["checker returned invalid JSON: #{error.message}"] }
 end
 
+# Acceptance results are a hard gate even in the default soft mode: Core itself
+# re-validates the frozen-suite results instead of trusting a checker summary.
+ACCEPTANCE_RESULT_GATED_STEPS = %w[run-acceptance-tests release-closeout].freeze
+
+def acceptance_results_check(root, feature)
+  script = File.join(__dir__, "acceptance_test_runner.py")
+  stdout, stderr, status = Open3.capture3("python3", script, "validate-results", "--feature", feature, "--json", chdir: root)
+  payload = JSON.parse(stdout)
+  return payload if status.success? && payload.is_a?(Hash) && payload["ok"] == true
+
+  { "ok" => false, "errors" => payload.is_a?(Hash) && payload["errors"].is_a?(Array) ? payload["errors"] : [stderr.strip.empty? ? "acceptance results checker returned invalid output" : stderr.strip] }
+rescue JSON::ParserError => error
+  { "ok" => false, "errors" => ["acceptance results checker returned invalid JSON: #{error.message}"] }
+end
+
+def execution_surface_check(root, feature)
+  script = File.join(__dir__, "execution_surface.py")
+  stdout, stderr, status = Open3.capture3("python3", script, "check-suite", "--feature", feature, "--json", chdir: root)
+  payload = JSON.parse(stdout)
+  return payload if status.success? && payload.is_a?(Hash) && payload["ok"] == true
+
+  { "ok" => false, "errors" => payload.is_a?(Hash) && payload["errors"].is_a?(Array) ? payload["errors"] : [stderr.strip.empty? ? "execution surface checker returned invalid output" : stderr.strip] }
+rescue JSON::ParserError => error
+  { "ok" => false, "errors" => ["execution surface checker returned invalid JSON: #{error.message}"] }
+end
+
 def api_test_matrix_check(root, feature, graph)
   return { "ok" => true, "skipped" => "no_api_nodes" } unless Array(graph["nodes"]).any? { |node| node.is_a?(Hash) && node["kind"] == "api" }
 
@@ -976,6 +1009,18 @@ result =
         )
       end
 
+      acceptance_gate_step = if options[:complete_step]
+                               options[:complete_step].to_s
+                             elsif options[:confirm_checkpoint] && state["status"] == "waiting_checkpoint"
+                               state["current_step"].to_s
+                             end
+      if result.nil? && ACCEPTANCE_RESULT_GATED_STEPS.include?(acceptance_gate_step) && step_by_id.key?(acceptance_gate_step)
+        acceptance_check = acceptance_results_check(root, state.fetch("current_feature"))
+        unless acceptance_check["ok"]
+          result = fail_result("acceptance_results_not_passed", "step" => acceptance_gate_step, "acceptance_results" => acceptance_check)
+        end
+      end
+
       if result.nil? && options[:complete_step]
         step_id = options[:complete_step]
         step = step_by_id[step_id]
@@ -1106,9 +1151,15 @@ result =
               end
             else
               matrix_check = api_test_matrix_check(root, feature, graph)
+              # A new freeze requires every TC to declare a consistent
+              # execution_surface; this is a hard failure even in soft mode.
+              surface_check = matrix_check["ok"] ? execution_surface_check(root, feature) : nil
               unless matrix_check["ok"]
                 result = fail_result("api_test_matrix_incomplete", "api_test_matrix" => matrix_check)
               else
+                result = fail_result("execution_surface_mismatch", "execution_surface" => surface_check) unless surface_check["ok"]
+              end
+              if matrix_check["ok"] && surface_check["ok"]
                 candidate_check = test_task_binding_check(root, feature, "candidate")
                 unless candidate_check["ok"]
                   result = fail_result("acceptance_test_suite_candidate_binding_failed", "test_suite" => candidate_check)

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

@@ -0,0 +1,433 @@
+#!/usr/bin/env python3
+"""Compute the current pins for a Core human-approval subject.
+
+This module is the single pin implementation shared by the runtime extension
+(propose + confirm CAS) and the Python approval reader.  It only reads project
+files; it never writes control.db.  There is intentionally no confirm entry
+point here: confirmation exists only in the runtime UI callback.
+
+Pins per kind (change list §1.8):
+
+- execution_plan      {suite_graph_revision, suite_fingerprint, tc_sha256, dsl_sha256}
+- environment_profile {profile_sha256}
+- mode_override       {suite_fingerprint, tc_sha256, binding_entry_sha256, from, to}
+- human_result        {suite_fingerprint, tc_sha256, evidence: [{path, sha256}]}
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+KINDS = ("execution_plan", "environment_profile", "mode_override", "human_result")
+FEATURE_RE = re.compile(r"^[^/\\\x00-\x1f\x7f]+$")
+TC_ID_RE = re.compile(r"^TC-[A-Za-z0-9_-]+$")
+PROFILE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$")
+MAX_EVIDENCE_FILE_BYTES = 25 * 1024 * 1024
+MAX_DSL_FILE_BYTES = 2 * 1024 * 1024
+MAX_EVIDENCE_FILES = 50
+SUMMARY_LIMIT = 300
+
+
+class PinError(Exception):
+    pass
+
+
+def _import_tc_hash():
+    try:
+        import tc_hash  # type: ignore
+    except ImportError as error:  # pragma: no cover - depends on concurrent Core work
+        raise PinError(f"tc_hash module is unavailable: {error}") from error
+    return tc_hash
+
+
+def jcs_sha256(value: Any) -> str:
+    """sha256(JCS(value)) using the single Core JCS implementation."""
+    tc_hash = _import_tc_hash()
+    return hashlib.sha256(tc_hash.canonicalize(value)).hexdigest()
+
+
+def tc_sha256(data: dict[str, Any]) -> str:
+    return str(_import_tc_hash().tc_sha256(data))
+
+
+def _read_json(path: Path, label: str) -> Any:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as error:
+        raise PinError(f"missing {label}: {path.as_posix()}") from error
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise PinError(f"invalid {label}: {error}") from error
+
+
+def workflow_state(root: Path) -> dict[str, Any]:
+    """Read revision and current_feature from STATE.md front matter."""
+    path = root / ".devflow/planning/STATE.md"
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as error:
+        raise PinError(f"workflow state is unavailable: {path.as_posix()}") from error
+    match = re.match(r"\A---\s*\n(.*?)\n---\s*(?:\n|\Z)", text, re.S)
+    if not match:
+        raise PinError("workflow state has no front matter")
+    fields: dict[str, str] = {}
+    for line in match.group(1).splitlines():
+        found = re.match(r"^([A-Za-z_][A-Za-z0-9_]*):\s*(.*?)\s*$", line)
+        if found:
+            fields[found.group(1)] = found.group(2)
+    raw_revision = fields.get("revision", "0").strip("'\"") or "0"
+    if not re.fullmatch(r"\d+", raw_revision):
+        raise PinError(f"workflow state revision is not an integer: {raw_revision}")
+    feature = fields.get("current_feature", "").strip()
+    if len(feature) >= 2 and feature[0] == feature[-1] and feature[0] in "'\"":
+        feature = feature[1:-1]
+    return {"revision": int(raw_revision), "current_feature": feature}
+
+
+def load_suite(root: Path, feature: str) -> dict[str, Any]:
+    suite = _read_json(root / ".devflow/planning/requirements" / feature / "tests.json", "TC suite")
+    if not isinstance(suite, dict):
+        raise PinError("TC suite root must be an object")
+    return suite
+
+
+def suite_pins(suite: dict[str, Any]) -> dict[str, Any]:
+    meta = suite.get("view_meta") if isinstance(suite.get("view_meta"), dict) else {}
+    fingerprint = meta.get("fingerprint")
+    if not isinstance(fingerprint, str) or not fingerprint:
+        raise PinError("TC suite view_meta.fingerprint is missing")
+    revision = suite.get("graph_revision")
+    if revision is None or isinstance(revision, bool):
+        raise PinError("TC suite graph_revision is missing")
+    return {"suite_fingerprint": fingerprint, "suite_graph_revision": revision}
+
+
+def frozen_case(suite: dict[str, Any], tc_id: str) -> dict[str, Any]:
+    for node in suite.get("nodes", []):
+        if isinstance(node, dict) and node.get("kind") == "test_case" and node.get("id") == tc_id:
+            if node.get("status") != "confirmed" or node.get("stale") is True:
+                raise PinError(f"TC is not frozen and fresh: {tc_id}")
+            data = node.get("data")
+            if not isinstance(data, dict):
+                raise PinError(f"TC has no data object: {tc_id}")
+            return data
+    raise PinError(f"TC is not in the frozen suite: {tc_id}")
+
+
+def binding_entry(root: Path, feature: str, tc_id: str, required: bool) -> dict[str, Any] | None:
+    path = root / ".devflow/planning/features" / feature / "acceptance-test-bindings.json"
+    if not path.is_file():
+        if required:
+            raise PinError(f"missing acceptance-test bindings: {path.relative_to(root).as_posix()}")
+        return None
+    bindings = _read_json(path, "acceptance-test bindings")
+    cases = bindings.get("cases") if isinstance(bindings, dict) else None
+    if not isinstance(cases, list):
+        raise PinError("acceptance-test bindings cases must be an array")
+    matches = [entry for entry in cases if isinstance(entry, dict) and entry.get("tc_id") == tc_id]
+    if len(matches) > 1:
+        raise PinError(f"duplicate binding entries for {tc_id}")
+    if not matches:
+        if required:
+            raise PinError(f"no binding entry for {tc_id}")
+        return None
+    return matches[0]
+
+
+def _contained_file(root: Path, raw: Any, base: Path, label: str, max_bytes: int) -> tuple[Path, str]:
+    if not isinstance(raw, str) or not raw.strip() or "\x00" in raw:
+        raise PinError(f"{label} must be a non-empty project-relative path")
+    candidate = Path(raw)
+    if candidate.is_absolute() or ".." in candidate.parts:
+        raise PinError(f"{label} escapes the project root: {raw}")
+    root_real = root.resolve()
+    resolved = (root_real / candidate).resolve()
+    try:
+        relative = resolved.relative_to(root_real)
+        resolved.relative_to(base.resolve())
+    except ValueError as error:
+        raise PinError(f"{label} is outside {base.relative_to(root).as_posix() if base != root else 'the project root'}: {raw}") from error
+    if not resolved.is_file():
+        raise PinError(f"{label} is missing: {raw}")
+    if resolved.stat().st_size > max_bytes:
+        raise PinError(f"{label} exceeds {max_bytes} bytes: {raw}")
+    return resolved, relative.as_posix()
+
+
+def _truncate(value: Any, limit: int = SUMMARY_LIMIT) -> str:
+    text = value if isinstance(value, str) else json.dumps(value, ensure_ascii=False, sort_keys=True)
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+def _target_text(target: Any) -> str:
+    if not isinstance(target, dict):
+        return ""
+    for key in ("testid", "role", "label", "placeholder", "text", "css"):
+        if key in target:
+            text = f"{key}={target[key]}"
+            if key == "role" and target.get("name") is not None:
+                text += f"[name={target['name']}]"
+            return text
+    return _truncate(target, 120)
+
+
+def assertion_summary(step: dict[str, Any]) -> str:
+    """Human-readable summary of one DSL step for the approval UI."""
+    action = str(step.get("action", "?"))
+    identifier = str(step.get("id", "?"))
+    if step.get("driver") == "api" or "request" in step or "method" in step:
+        request = step.get("request") if isinstance(step.get("request"), dict) else step
+        method = str(request.get("method", "")).upper()
+        url = request.get("url") or request.get("path") or ""
+        assertions = step.get("assertions", step.get("expect"))
+        return f"{identifier}: API {method} {url} 断言 {_truncate(assertions, 200)}".strip()
+    target = _target_text(step.get("target"))
+    parts = [f"{identifier}: {action}"]
+    if target:
+        parts.append(target)
+    if "expected" in step:
+        match = step.get("match", "exact")
+        parts.append(f"{match} = {_truncate(step.get('expected'), 200)}")
+    elif "url" in step and action == "assert_url":
+        parts.append(f"url {_truncate(step.get('url'), 200)}")
+    return " ".join(parts)
+
+
+def dsl_steps(dsl: dict[str, Any]) -> list[dict[str, Any]]:
+    steps = [step for step in dsl.get("steps", []) if isinstance(step, dict)]
+    data = dsl.get("data") if isinstance(dsl.get("data"), dict) else {}
+    setup = [step for step in data.get("setup", []) if isinstance(step, dict)] if isinstance(data.get("setup"), list) else []
+    return setup + steps
+
+
+def coverage_display(tc_data: dict[str, Any], dsl: dict[str, Any]) -> dict[str, Any]:
+    oracle_steps = []
+    covered_pre: set[int] = set()
+    covered_steps: set[int] = set()
+    for step in dsl_steps(dsl):
+        covers = step.get("covers") if isinstance(step.get("covers"), dict) else {}
+        if covers.get("oracle") is True:
+            oracle_steps.append(assertion_summary(step))
+        for key, target in (("preconditions", covered_pre), ("steps", covered_steps)):
+            values = covers.get(key)
+            if isinstance(values, list):
+                target.update(item for item in values if isinstance(item, int) and not isinstance(item, bool))
+    preconditions = tc_data.get("preconditions") if isinstance(tc_data.get("preconditions"), list) else []
+    steps = tc_data.get("steps") if isinstance(tc_data.get("steps"), list) else []
+    return {
+        "oracle_assertions": oracle_steps,
+        "uncovered_preconditions": [index for index in range(1, len(preconditions) + 1) if index not in covered_pre],
+        "uncovered_steps": [index for index in range(1, len(steps) + 1) if index not in covered_steps],
+    }
+
+
+def structural_validation(tc_data: dict[str, Any], dsl: dict[str, Any]) -> tuple[str, list[str]]:
+    """Run the Core DSL validators when they are installed (K05/K06)."""
+    errors: list[str] = []
+    try:
+        import dsl_v1  # type: ignore
+        import dsl_coverage  # type: ignore
+    except ImportError:
+        return "unavailable", []
+    errors.extend(str(item) for item in dsl_v1.validate(dsl) or [])
+    if not errors:
+        errors.extend(str(item) for item in dsl_coverage.check(tc_data, dsl) or [])
+    return ("failed" if errors else "passed"), errors
+
+
+def tc_display(tc_id: str, data: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "tc_id": tc_id,
+        "target": data.get("target"),
+        "oracle": data.get("oracle"),
+        "preconditions": data.get("preconditions") if isinstance(data.get("preconditions"), list) else [],
+        "steps": data.get("steps") if isinstance(data.get("steps"), list) else [],
+        "automation_mode": data.get("automation_mode"),
+    }
+
+
+def _require_tc(subject_key: str) -> None:
+    if not TC_ID_RE.fullmatch(subject_key):
+        raise PinError(f"subject_key must be a TC id: {subject_key}")
+
+
+def compute_execution_plan(root: Path, feature: str, tc_id: str, payload: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+    _require_tc(tc_id)
+    suite = load_suite(root, feature)
+    pins_suite = suite_pins(suite)
+    data = frozen_case(suite, tc_id)
+    if data.get("automation_mode") != "automated":
+        raise PinError(f"execution_plan applies only to automated TCs: {tc_id} is {data.get('automation_mode')}")
+    base = root / ".devflow/planning/generated-cases" / feature
+    raw = payload.get("dsl_file") or f".devflow/planning/generated-cases/{feature}/{tc_id}.json"
+    path, relative = _contained_file(root, raw, base, "dsl_file", MAX_DSL_FILE_BYTES)
+    content = path.read_bytes()
+    try:
+        dsl = json.loads(content.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise PinError(f"DSL is not valid JSON: {error}") from error
+    if not isinstance(dsl, dict):
+        raise PinError("DSL root must be an object")
+    current_tc = tc_sha256(data)
+    if dsl.get("tc_id") != tc_id:
+        raise PinError(f"DSL tc_id {dsl.get('tc_id')!r} does not match {tc_id}")
+    if dsl.get("tc_sha256") != current_tc:
+        raise PinError("DSL tc_sha256 does not match the current frozen TC")
+    validation, validation_errors = structural_validation(data, dsl)
+    if validation_errors:
+        raise PinError("DSL structural validation failed: " + "; ".join(validation_errors[:20]))
+    pins = {
+        "suite_graph_revision": pins_suite["suite_graph_revision"],
+        "suite_fingerprint": pins_suite["suite_fingerprint"],
+        "tc_sha256": current_tc,
+        "dsl_sha256": hashlib.sha256(content).hexdigest(),
+    }
+    display = {**tc_display(tc_id, data), "dsl_file": relative, "structural_validation": validation, **coverage_display(data, dsl)}
+    return pins, display
+
+
+def compute_environment_profile(root: Path, feature: str, name: str, payload: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+    if not PROFILE_RE.fullmatch(name):
+        raise PinError(f"invalid environment profile name: {name}")
+    try:
+        import environment_profile  # type: ignore
+    except ImportError as error:  # pragma: no cover - depends on concurrent Core work
+        raise PinError(f"environment_profile module is unavailable: {error}") from error
+    profile, sha256, errors = environment_profile.load(root, name)
+    if errors:
+        raise PinError("environment profile is invalid: " + "; ".join(str(item) for item in errors))
+    if not isinstance(profile, dict) or not isinstance(sha256, str) or not sha256:
+        raise PinError("environment profile loader returned no profile hash")
+    secret_env = profile.get("secret_env") if isinstance(profile.get("secret_env"), dict) else {}
+    display = {
+        "profile": name,
+        "path": f".devflow/planning/test-environments/{name}.json",
+        "base_url": profile.get("base_url"),
+        "navigation_origins": profile.get("navigation_origins", []),
+        "api_origins": profile.get("api_origins", []),
+        "subresources": profile.get("subresources"),
+        # Names only: the profile maps aliases to environment variable names, never values.
+        "secret_env": {str(key): str(value) for key, value in secret_env.items()},
+        "trace": profile.get("trace"),
+    }
+    return {"profile_sha256": sha256}, display
+
+
+def compute_mode_override(root: Path, feature: str, tc_id: str, payload: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+    _require_tc(tc_id)
+    suite = load_suite(root, feature)
+    pins_suite = suite_pins(suite)
+    data = frozen_case(suite, tc_id)
+    entry = binding_entry(root, feature, tc_id, required=True)
+    assert entry is not None
+    source = data.get("automation_mode")
+    target = entry.get("mode")
+    if source != "automated" or target != "manual":
+        raise PinError(f"mode_override only approves automated -> manual; got {source} -> {target}")
+    pins = {
+        "suite_fingerprint": pins_suite["suite_fingerprint"],
+        "tc_sha256": tc_sha256(data),
+        "binding_entry_sha256": jcs_sha256(entry),
+        "from": source,
+        "to": target,
+    }
+    display = {**tc_display(tc_id, data), "from": source, "to": target, "binding_entry": entry}
+    return pins, display
+
+
+def compute_human_result(root: Path, feature: str, tc_id: str, payload: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+    _require_tc(tc_id)
+    suite = load_suite(root, feature)
+    pins_suite = suite_pins(suite)
+    data = frozen_case(suite, tc_id)
+    entry = binding_entry(root, feature, tc_id, required=False)
+    mode = entry.get("mode") if entry is not None else data.get("automation_mode")
+    if mode != "manual":
+        raise PinError(f"human_result applies only to manual TCs: {tc_id} is {mode}")
+    raw_files = payload.get("evidence_files", [])
+    if not isinstance(raw_files, list):
+        raise PinError("evidence_files must be an array of project-relative paths")
+    if len(raw_files) > MAX_EVIDENCE_FILES:
+        raise PinError(f"at most {MAX_EVIDENCE_FILES} evidence files are allowed")
+    evidence: dict[str, dict[str, Any]] = {}
+    for raw in raw_files:
+        path, relative = _contained_file(root, raw, root, "evidence file", MAX_EVIDENCE_FILE_BYTES)
+        if relative.startswith(".devflow/planning/test-runs/") and relative.endswith("human-acceptance-results.json"):
+            raise PinError("the human acceptance draft cannot be its own evidence")
+        content = path.read_bytes()
+        evidence[relative] = {"path": relative, "sha256": hashlib.sha256(content).hexdigest(), "bytes": len(content)}
+    ordered = [evidence[key] for key in sorted(evidence)]
+    pins = {
+        "suite_fingerprint": pins_suite["suite_fingerprint"],
+        "tc_sha256": tc_sha256(data),
+        "evidence": [{"path": item["path"], "sha256": item["sha256"]} for item in ordered],
+    }
+    display = {**tc_display(tc_id, data), "evidence": ordered}
+    return pins, display
+
+
+COMPUTERS = {
+    "execution_plan": compute_execution_plan,
+    "environment_profile": compute_environment_profile,
+    "mode_override": compute_mode_override,
+    "human_result": compute_human_result,
+}
+
+
+def compute(root: Path, feature: str, kind: str, subject_key: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Return {ok, kind, feature, subject_key, state_revision, pins, display, errors}."""
+    result: dict[str, Any] = {"ok": False, "kind": kind, "feature": feature, "subject_key": subject_key, "errors": []}
+    try:
+        if kind not in COMPUTERS:
+            raise PinError(f"unknown approval kind: {kind}")
+        if not isinstance(feature, str) or not FEATURE_RE.fullmatch(feature):
+            raise PinError("feature must be a plain feature name")
+        if payload is not None and not isinstance(payload, dict):
+            raise PinError("payload must be an object")
+        state = workflow_state(root)
+        if state["current_feature"] != feature:
+            raise PinError(f"feature is not active: requested={feature}, current={state['current_feature'] or 'none'}")
+        pins, display = COMPUTERS[kind](root, feature, subject_key, payload or {})
+    except PinError as error:
+        result["errors"].append(str(error))
+        return result
+    result.update({"ok": True, "state_revision": state["revision"], "pins": pins, "display": display})
+    return result
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    sub = parser.add_subparsers(dest="command", required=True)
+    compute_parser = sub.add_parser("compute", help="compute current pins for one approval subject (read-only)")
+    compute_parser.add_argument("--root", default=".")
+    compute_parser.add_argument("--feature", required=True)
+    compute_parser.add_argument("--kind", required=True, choices=KINDS)
+    compute_parser.add_argument("--subject", required=True)
+    compute_parser.add_argument("--payload-json", default="{}")
+    compute_parser.add_argument("--json", action="store_true")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    try:
+        payload = json.loads(args.payload_json)
+    except json.JSONDecodeError as error:
+        print(json.dumps({"ok": False, "errors": [f"invalid --payload-json: {error.msg}"]}, ensure_ascii=False))
+        return 1
+    result = compute(Path(args.root).resolve(), args.feature, args.kind, args.subject, payload)
+    print(json.dumps(result, ensure_ascii=False, sort_keys=True))
+    return 0 if result["ok"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Read-only access to Core approval records in control.db (变更清单 §1.8).
+
+Approvals are written only by the Runtime extension's UI confirmation path.
+This module never writes: it opens control.db with mode=ro and re-derives
+validity by recomputing the current pins with approval_pins.compute (the single
+pin implementation shared with the proposal/confirm side) and comparing them
+with the stored pins_json.  The
+file-compatibility authority has no approval channel, so every lookup there
+fails with approval_requires_database_authority.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from tc_hash import canonicalize
+
+
+APPROVAL_KINDS = frozenset({"execution_plan", "environment_profile", "mode_override", "human_result"})
+REQUIRES_DATABASE = "approval_requires_database_authority"
+
+
+def _project_id(root: Path) -> str | None:
+    try:
+        value = json.loads((root / ".devflow" / "project.json").read_text(encoding="utf-8"))["projectId"]
+        return value if isinstance(value, str) and value else None
+    except (OSError, KeyError, TypeError, ValueError):
+        return None
+
+
+def devflow_home() -> Path:
+    """DEVFLOW_HOME rule shared with the TS writer (src/paths.ts normalizeDevflowHome) and hook_common.
+
+    Unset, empty or whitespace-only means unset -> ~/.devflow-pi. Otherwise only a leading '~' or '~/'
+    is expanded (never '~user'), then the path is made absolute with os.path.abspath (existence is not required).
+    """
+    value = os.environ.get("DEVFLOW_HOME")
+    value = "~/.devflow-pi" if value is None or not value.strip() else value.strip()
+    if value == "~" or value.startswith("~/"):
+        value = str(Path.home()) + value[1:]
+    return Path(os.path.abspath(value))
+
+
+def _connect(root: Path) -> tuple[sqlite3.Connection | None, str | None]:
+    project_id = _project_id(root)
+    if project_id is None:
+        return None, None
+    database = devflow_home() / "projects" / project_id / "control.db"
+    if not database.is_file():
+        return None, project_id
+    # Path.as_uri() percent-quotes '?', '#', '%' etc., so they cannot be read as URI syntax.
+    connection = sqlite3.connect(f"{database.as_uri()}?mode=ro", uri=True)
+    connection.row_factory = sqlite3.Row
+    return connection, project_id
+
+
+def _same(left: Any, right: Any) -> bool:
+    try:
+        return canonicalize(left) == canonicalize(right)
+    except ValueError:
+        return False
+
+
+def latest_approval(root: Path, feature: str, kind: str, subject_key: str) -> dict[str, Any]:
+    """The newest non-superseded approval for (feature, kind, subject_key), without validity checks."""
+    if kind not in APPROVAL_KINDS:
+        return {"ok": False, "reason": "approval_invalid", "message": f"unknown approval kind: {kind}"}
+    try:
+        connection, project_id = _connect(root)
+        if connection is None:
+            return {"ok": False, "reason": REQUIRES_DATABASE, "message": "approvals require the database control-plane authority"}
+        try:
+            authority = connection.execute("SELECT authority FROM authority_state WHERE project_id=?", (project_id,)).fetchone()
+            if not authority or authority["authority"] != "database":
+                return {"ok": False, "reason": REQUIRES_DATABASE, "message": "approvals require the database control-plane authority"}
+            row = connection.execute(
+                """SELECT a.id, a.proposal_id, a.pins_json, a.decision_json, a.approved_via, a.approved_at, p.status AS proposal_status, p.payload_json,
+                          p.kind AS proposal_kind, p.subject_key AS proposal_subject, p.feature AS proposal_feature, p.project_id AS proposal_project
+                   FROM approvals a JOIN approval_proposals p ON p.id=a.proposal_id
+                   WHERE a.project_id=? AND a.feature=? AND a.kind=? AND a.subject_key=? AND a.superseded_at IS NULL
+                   ORDER BY a.approved_at DESC, a.rowid DESC LIMIT 1""",
+                (project_id, feature, kind, subject_key),
+            ).fetchone()
+        finally:
+            connection.close()
+    except sqlite3.Error as error:
+        return {"ok": False, "reason": "approval_invalid", "message": f"approval store is unreadable: {error}"}
+    if row is None:
+        return {"ok": False, "reason": "approval_missing", "message": f"no {kind} approval for {subject_key}"}
+    if (row["approved_via"] != "runtime_ui_confirm" or row["proposal_status"] != "consumed" or row["proposal_kind"] != kind
+            or row["proposal_subject"] != subject_key or row["proposal_feature"] != feature or row["proposal_project"] != project_id):
+        return {"ok": False, "reason": "approval_invalid", "message": "approval record is not bound to a consumed UI-confirmed proposal"}
+    try:
+        pins = json.loads(row["pins_json"])
+        decision = json.loads(row["decision_json"])
+        payload = json.loads(row["payload_json"] or "{}")
+    except (TypeError, json.JSONDecodeError):
+        return {"ok": False, "reason": "approval_invalid", "message": "approval record JSON is malformed"}
+    if not isinstance(pins, dict) or not isinstance(decision, dict) or not isinstance(payload, dict):
+        return {"ok": False, "reason": "approval_invalid", "message": "approval pins, decision and payload must be objects"}
+    request = payload.get("request", {})
+    return {"ok": True, "reason": None, "approval": {"id": row["id"], "proposal_id": row["proposal_id"], "kind": kind, "subject_key": subject_key,
+                                                      "pins": pins, "decision": decision, "request": request if isinstance(request, dict) else {},
+                                                      "approved_at": row["approved_at"]}}
+
+
+def valid_approval(root: Path, feature: str, kind: str, subject_key: str, current_pins: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Return {"ok", "reason", "message", "approval"}.
+
+    Valid only when the newest non-superseded approval's pins equal the pins
+    approval_pins.compute derives now from the proposal request; any key given
+    in ``current_pins`` (e.g. the hash of the DSL the binding actually names)
+    must additionally equal the stored pin.
+    """
+    found = latest_approval(root, feature, kind, subject_key)
+    if not found["ok"]:
+        return {**found, "approval": None}
+    approval = found["approval"]
+    try:
+        from approval_pins import compute
+    except ImportError as error:
+        return {"ok": False, "reason": "approval_invalid", "message": f"approval_pins is unavailable: {error}", "approval": None}
+    computed = compute(root, feature, kind, subject_key, approval["request"])
+    if not computed.get("ok"):
+        return {"ok": False, "reason": "approval_stale", "message": "current pins cannot be computed: " + "; ".join(map(str, computed.get("errors", []))), "approval": None}
+    expected = dict(computed["pins"])
+    for key, value in (current_pins or {}).items():
+        if not _same(expected.get(key), value):
+            return {"ok": False, "reason": "approval_stale", "message": f"approval does not cover the current {key}", "approval": None}
+    if not _same(approval["pins"], expected):
+        changed = sorted(key for key in set(approval["pins"]) | set(expected) if not _same(approval["pins"].get(key), expected.get(key)))
+        return {"ok": False, "reason": "approval_stale", "message": f"approval pins no longer match: {', '.join(changed)}", "approval": None}
+    return {"ok": True, "reason": None, "message": None, "approval": approval}