@guanlin4924/devflow-pi 0.1.93 → 0.1.95

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

@@ -59,7 +59,7 @@ OptionParser.new do |opts|
 end.parse!
 
 root = Dir.pwd
-state_path, = DevflowControlIO.resolve_control_path(root, options[:state] || ".planning/STATE.md", :state)
+state_path, = DevflowControlIO.resolve_control_path(root, options[:state] || ".devflow/planning/STATE.md", :state)
 
 def front_matter(markdown)
   match = markdown.match(/\A---\n(.*?)\n---\n/m)
@@ -71,7 +71,7 @@ def load_yaml_file(path)
 end
 
 def workflow_path_for(root, state)
-  state["workflow_config"] || File.join(".planning", "workflows", "#{state.fetch("current_flow")}.yaml")
+  state["workflow_config"] || File.join(".devflow/planning", "workflows", "#{state.fetch("current_flow")}.yaml")
 end
 
 def load_workflow(root, state)
@@ -384,7 +384,7 @@ def checkpoint_label(workflow, checkpoint_id)
 end
 
 def next_intent_path(root, workflow)
-  workflow.dig("resume_rules", "continue_keyword", "next_intent_path") || ".planning/.next-intent"
+  workflow.dig("resume_rules", "continue_keyword", "next_intent_path") || ".devflow/planning/.next-intent"
 end
 
 def write_next_intent(root, workflow)
@@ -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" }
 
@@ -635,16 +668,16 @@ end
 
 def business_cross_model_check(root, feature)
   script = File.join(__dir__, "business_cross_model_check.py")
-  business = ".planning/business-model/#{feature}/canonical.json"
-  wireframe = ".planning/features/#{feature}/canonical.json"
+  business = ".devflow/planning/business-model/#{feature}/canonical.json"
+  wireframe = ".devflow/planning/features/#{feature}/canonical.json"
   unless File.file?(File.join(root, business))
     return { "valid" => false, "errors" => [{ "code" => "BUSINESS_CANONICAL_MISSING", "path" => business }] }
   end
   command = ["python3", script, "--business-canonical", business]
   command += ["--wireframe", wireframe] if File.file?(File.join(root, wireframe))
-  claims = ".planning/features/#{feature}/business-claims.yaml"
+  claims = ".devflow/planning/features/#{feature}/business-claims.yaml"
   command += ["--claims", claims] if File.file?(File.join(root, claims))
-  traceability = ".planning/requirements/#{feature}/traceability.json"
+  traceability = ".devflow/planning/requirements/#{feature}/traceability.json"
   command += ["--traceability", traceability] if File.file?(File.join(root, traceability))
   stdout, stderr, status = Open3.capture3(*command, "--json", chdir: root)
   payload = JSON.parse(stdout)
@@ -675,7 +708,7 @@ rescue JSON::ParserError => error
 end
 
 def test_suite_freeze_attestation_path(root, feature)
-  DevflowControlIO.resolve_control_path(root, ".planning/features/#{feature}/test-suite-freeze.json", :artifact)
+  DevflowControlIO.resolve_control_path(root, ".devflow/planning/features/#{feature}/test-suite-freeze.json", :artifact)
 end
 
 def frozen_test_suite_pin(freeze_result)
@@ -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)
@@ -1218,7 +1269,7 @@ result =
         prospective_owner = if changed
                               {
                                 "phase" => state["current_phase"], "feature" => state["current_feature"],
-                                "flow" => state["current_flow"], "state_path" => ".planning/STATE.md",
+                                "flow" => state["current_flow"], "state_path" => ".devflow/planning/STATE.md",
                                 "scope" => "global", "status" => "active"
                               }
                             end

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

@@ -72,8 +72,8 @@ def write_text(path: Path, value: str) -> None:
 
 
 def paths(root: Path, feature: str) -> tuple[Path, Path, Path, Path]:
-    requirements = root / ".planning" / "requirements" / feature
-    feature_dir = root / ".planning" / "features" / feature
+    requirements = root / ".devflow/planning" / "requirements" / feature
+    feature_dir = root / ".devflow/planning" / "features" / feature
     return (
         requirements / "governance.json",
         requirements / "api-test-matrix.json",

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())