@guanlin4924/devflow-pi 0.1.94 → 0.1.96

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

@@ -3,18 +3,28 @@
 from __future__ import annotations
 
 import argparse
+import contextlib
+import fcntl
 import hashlib
 import json
 import os
 import re
+import shutil
 import subprocess
-from datetime import datetime, timezone
+from datetime import date, datetime, timedelta, 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
 
+import playwright_adapter
+from approval_store import REQUIRES_DATABASE, valid_approval
+from dsl_coverage import check as dsl_coverage_check
+from dsl_v1 import validate as validate_dsl
+from environment_profile import load as load_environment_profile
+from execution_surface import ADAPTERS_BY_SURFACE, consistency_errors, derive as derive_surface, http_execution_error
+from tc_hash import tc_sha256
 from test_command_policy import validate_test_command
 
 
@@ -22,6 +32,13 @@ FEATURE_RE = re.compile(r"^[^/\\\x00-\x1f\x7f]+$")
 AUTOMATION_MODES = {"automated", "manual", "blocked"}
 EVIDENCE_STRATEGIES = {"replay", "causal", "observation"}
 MAX_EVIDENCE_FILE_BYTES = 25 * 1024 * 1024
+# 方案 §11: automation_mode may only be downgraded by a binding, never upgraded.
+ALLOWED_BINDING_MODES = {"automated": ("automated", "manual", "blocked"), "manual": ("manual", "blocked"), "blocked": ("blocked",)}
+RESULT_ORIGINS = {"command": "project_test_command", "http": "core_http_adapter", playwright_adapter.ADAPTER_KIND: playwright_adapter.RESULT_ORIGIN}
+DEFAULT_RUN_RETENTION_DAYS = 30
+DEFAULT_UNREFERENCED_RUN_TTL_DAYS = 7
+MAX_REPORT_ERRORS = 50
+MAX_REPORT_ERROR_CHARS = 500
 
 
 def utc_now() -> str:
@@ -56,6 +73,49 @@ def write_json(path: Path, value: dict[str, Any]) -> None:
     temporary.replace(path)
 
 
+def human_results_path(root: Path, feature: str) -> Path:
+    """Agent-maintained draft/evidence list only; never a result source (方案 §11)."""
+    return root / ".devflow/planning" / "test-runs" / feature / "human-acceptance-results.json"
+
+
+def manual_case_ids(root: Path, feature: str, suite: dict[str, Any], bindings: dict[str, Any] | None) -> list[str]:
+    """Manual TCs are determined by the binding mode; before bindings exist, by the frozen mode."""
+    cases = frozen_cases(suite, [])
+    if bindings is None:
+        _, binding_path, _ = paths(root, feature)
+        bindings = read_json(binding_path, [], "acceptance-test bindings") if binding_path.is_file() else None
+    if isinstance(bindings, dict) and isinstance(bindings.get("cases"), list):
+        return sorted({entry["tc_id"] for entry in bindings["cases"] if isinstance(entry, dict) and entry.get("mode") == "manual" and entry.get("tc_id") in cases})
+    return sorted(tc_id for tc_id, data in cases.items() if data.get("automation_mode") == "manual")
+
+
+def validate_human_results(root: Path, feature: str, suite: dict[str, Any], bindings: dict[str, Any] | None = None) -> tuple[dict[str, Any], dict[str, dict[str, Any]]]:
+    """Manual results come only from valid Core human_result approvals (UI-confirmed, pins re-derived)."""
+    errors: list[str] = []
+    manual = manual_case_ids(root, feature, suite, bindings)
+    by_id: dict[str, dict[str, Any]] = {}
+    for tc_id in manual:
+        found = valid_approval(root, feature, "human_result", tc_id)
+        if not found["ok"]:
+            code = REQUIRES_DATABASE if found["reason"] == REQUIRES_DATABASE else "human_result_unapproved"
+            errors.append(f"{code}: manual TC {tc_id} has no valid human_result approval ({found['message']})")
+            continue
+        approval = found["approval"]
+        decision = approval["decision"]
+        status = decision.get("status")
+        actual = decision.get("actual_result")
+        evidence = approval["pins"].get("evidence") if isinstance(approval["pins"].get("evidence"), list) else []
+        if status not in {"passed", "failed", "blocked"} or not isinstance(actual, str) or not actual.strip():
+            errors.append(f"approval_invalid: human_result approval for {tc_id} must record status and actual_result")
+            continue
+        if status == "passed" and not evidence:
+            errors.append(f"approval_invalid: passed human_result for {tc_id} requires at least one pinned evidence file")
+            continue
+        by_id[tc_id] = {"status": status, "actual_result": actual, "approval_id": approval["id"], "approved_at": approval["approved_at"],
+                        "evidence_artifacts": [{"path": item.get("path"), "sha256": item.get("sha256")} for item in evidence if isinstance(item, dict)]}
+    return {"ok": not errors, "feature": feature, "tc_ids": manual, "errors": errors}, by_id
+
+
 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)
 
@@ -90,30 +150,6 @@ def pointer_value(document: Any, pointer: str) -> Any:
     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", []):
@@ -144,27 +180,33 @@ def file_fingerprint(path: Path) -> str | None:
     return digest(path.read_bytes()) if path.is_file() else None
 
 
-def evidence_artifacts(root: Path, value: Any) -> tuple[list[dict[str, Any]], list[str]]:
-    """Hash causal evidence from bounded project-relative files only."""
+def evidence_declaration_errors(root: Path, value: Any) -> list[str]:
+    """Before a run only the declaration and path boundary are checked; files may be produced by the run."""
     if not isinstance(value, list) or not value:
-        return [], ["causal verification requires non-empty evidence_files"]
+        return ["causal verification requires non-empty evidence_files"]
     root_real = root.resolve()
-    artifacts: list[dict[str, Any]] = []
     errors: list[str] = []
     for raw in value:
         if not isinstance(raw, str) or not raw.strip() or "\x00" in raw:
             errors.append("evidence_files entries must be non-empty relative paths")
             continue
         candidate = Path(raw)
-        if candidate.is_absolute() or ".." in candidate.parts:
-            errors.append(f"evidence file escapes project root: {raw}")
-            continue
-        resolved = (root_real / candidate).resolve()
-        try:
-            relative = resolved.relative_to(root_real)
-        except ValueError:
+        if candidate.is_absolute() or ".." in candidate.parts or not (root_real / candidate).resolve().is_relative_to(root_real):
             errors.append(f"evidence file escapes project root: {raw}")
-            continue
+    return errors
+
+
+def evidence_artifacts(root: Path, value: Any) -> tuple[list[dict[str, Any]], list[str]]:
+    """After a run: hash causal evidence from bounded project-relative files only."""
+    declaration_errors = evidence_declaration_errors(root, value)
+    if declaration_errors:
+        return [], declaration_errors
+    root_real = root.resolve()
+    artifacts: list[dict[str, Any]] = []
+    errors: list[str] = []
+    for raw in value:
+        resolved = (root_real / Path(raw)).resolve()
+        relative = resolved.relative_to(root_real)
         if not resolved.is_file():
             errors.append(f"causal evidence file is missing: {raw}")
             continue
@@ -237,6 +279,37 @@ def run_http_case(source: dict[str, Any], adapter: dict[str, Any]) -> tuple[bool
     return True, 0, f"{setup_output}\nHTTP {http_status} matched expectation"
 
 
+def playwright_binding_errors(root: Path, feature: str, tc_id: str, source: dict[str, Any], adapter: dict[str, Any]) -> list[str]:
+    """Binding shape, DSL schema/semantics, TC identity, structural coverage and profile validity."""
+    errors = playwright_adapter.adapter_errors(root, feature, adapter)
+    if errors:
+        return errors
+    path, _ = playwright_adapter.dsl_path(root, feature, adapter["dsl_file"])
+    assert path is not None
+    _raw, dsl, dsl_error = playwright_adapter.read_dsl(path)
+    if dsl_error:
+        return [dsl_error]
+    dsl_errors = validate_dsl(dsl)
+    if dsl_errors:
+        return [f"DSL is invalid: {error}" for error in dsl_errors]
+    if dsl["tc_id"] != tc_id:
+        errors.append(f"DSL tc_id {dsl['tc_id']} does not match binding {tc_id}")
+    if dsl["tc_sha256"] != tc_sha256(source):
+        errors.append("DSL tc_sha256 does not match the current frozen TC (JCS SHA-256)")
+    errors.extend(f"DSL coverage: {error}" for error in dsl_coverage_check(source, dsl))
+    _profile, _sha, profile_errors = load_environment_profile(root, adapter["environment_profile"])
+    errors.extend(f"environment profile: {error}" for error in profile_errors)
+    return errors
+
+
+def mode_override_errors(root: Path, feature: str, tc_id: str) -> list[str]:
+    found = valid_approval(root, feature, "mode_override", tc_id)
+    if found["ok"]:
+        return []
+    code = REQUIRES_DATABASE if found["reason"] == REQUIRES_DATABASE else "approval_invalid"
+    return [f"{code}: automated -> manual downgrade of {tc_id} requires a valid UI-confirmed mode_override approval ({found['message']})"]
+
+
 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)
@@ -282,6 +355,8 @@ def validate(root: Path, feature: str) -> tuple[dict[str, Any], dict[str, Any] |
         if source is None:
             errors.append(f"unknown TC reference: {tc_id}")
             continue
+        surface, _legacy = derive_surface(source)
+        errors.extend(f"execution_surface_mismatch: {label} ({tc_id}) {error}" for error in consistency_errors(source))
         strategy = source.get("evidence_strategy")
         if strategy is not None and strategy not in EVIDENCE_STRATEGIES:
             errors.append(f"{label}.source evidence_strategy is invalid")
@@ -291,20 +366,30 @@ def validate(root: Path, feature: str) -> tuple[dict[str, Any], dict[str, Any] |
         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")
+        frozen_mode = source.get("automation_mode")
+        if mode not in ALLOWED_BINDING_MODES.get(frozen_mode, ()):
+            errors.append(f"{label}.mode {mode} is not allowed for frozen automation_mode {frozen_mode} (bindings may only downgrade)")
+            continue
         if mode == "automated":
             adapter = entry.get("adapter")
             if not isinstance(adapter, dict):
                 errors.append(f"{label}.adapter is required")
-            elif adapter.get("kind") == "command":
+                continue
+            kind = adapter.get("kind")
+            if kind not in RESULT_ORIGINS:
+                errors.append(f"{label}.adapter kind must be command, http, or devflow_playwright")
+                continue
+            if surface is not None and kind not in ADAPTERS_BY_SURFACE[surface]:
+                errors.append(f"execution_surface_mismatch: {label} ({tc_id}) execution_surface={surface} cannot be bound to adapter kind {kind}")
+                continue
+            if 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":
+            elif 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:
@@ -316,27 +401,74 @@ def validate(root: Path, feature: str) -> tuple[dict[str, Any], dict[str, Any] |
                         if setup_error:
                             errors.append(f"{label}.adapter.setup: {setup_error}")
             else:
-                errors.append(f"{label}.adapter kind must be command or http")
+                errors.extend(f"{label}.adapter: {error}" for error in playwright_binding_errors(root, feature, tc_id, source, adapter))
             if strategy == "causal":
-                _artifacts, artifact_errors = evidence_artifacts(root, entry.get("evidence_files"))
-                errors.extend(f"{label}.{error}" for error in artifact_errors)
+                errors.extend(f"{label}.{error}" for error in evidence_declaration_errors(root, entry.get("evidence_files")))
         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")
+            if frozen_mode == "automated":
+                errors.extend(f"{error} [{label}]" for error in mode_override_errors(root, feature, tc_id))
         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")
+            if frozen_mode != "blocked" and (not isinstance(entry.get("reason"), str) or not entry["reason"].strip()):
+                errors.append(f"{label}.blocked downgrade requires reason")
     for tc_id in sorted(set(cases) - seen):
         errors.append(f"unbound frozen TC: {tc_id}")
+    human_validation, _ = validate_human_results(root, feature, suite, bindings)
+    errors.extend(human_validation["errors"])
     return {"ok": not errors, "feature": feature, "tc_ids": sorted(cases), "errors": errors}, suite, bindings
 
 
+def run_command_case(root: Path, argv: list[str]) -> tuple[int, str]:
+    try:
+        completed = subprocess.run(argv, cwd=root, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=180, check=False)
+        return completed.returncode, f"{completed.stdout}\n{completed.stderr}"
+    except subprocess.TimeoutExpired as error:
+        return 124, f"command timed out: {error}"
+    except OSError as error:
+        return 127, f"command could not start: {error}"
+
+
+@contextlib.contextmanager
+def acceptance_run_lock(root: Path, feature: str):
+    """Hold the feature write lock for the complete run, including result writes."""
+    lock_path = root / ".devflow/planning/test-runs" / feature / ".run.lock"
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    handle = lock_path.open("a+")
+    try:
+        try:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            yield False
+            return
+        yield True
+    finally:
+        try:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+        finally:
+            handle.close()
+
+
 def run(root: Path, feature: str, write: bool) -> dict[str, Any]:
+    if write:
+        with acceptance_run_lock(root, feature) as acquired:
+            if not acquired:
+                return {"ok": False, "feature": feature, "reason": "acceptance_run_in_progress", "errors": []}
+            return _run_locked(root, feature, write)
+    return _run_locked(root, feature, write)
+
+
+def _run_locked(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, [])
+    human_validation, human_results = validate_human_results(root, feature, suite, bindings)
+    if not human_validation["ok"]:
+        return human_validation
     _, _, result_path = paths(root, feature)
     previous = read_json(result_path, [], "previous acceptance-test results")
     task_bindings_path = root / ".devflow/planning" / "features" / feature / "test-bindings.json"
@@ -345,43 +477,54 @@ def run(root: Path, feature: str, write: bool) -> dict[str, Any]:
     for entry in bindings["cases"]:
         tc_id = entry["tc_id"]
         mode = entry["mode"]
-        strategy = cases[tc_id].get("evidence_strategy")
+        source = cases[tc_id]
+        strategy = source.get("evidence_strategy")
+        surface, legacy = derive_surface(source)
+        common = {"tc_id": tc_id, "mode": mode, "execution_surface": surface, "legacy_unclassified": legacy, "tc_sha256": tc_sha256(source)}
+        frozen_mode = source.get("automation_mode")
+        if mode != frozen_mode:
+            common["downgrade"] = {"from": frozen_mode, "to": mode}
         if mode == "automated":
             started_at = utc_now()
             adapter = entry["adapter"]
-            if adapter["kind"] == "command":
+            kind = adapter["kind"]
+            if 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,
+                exit_code, output = run_command_case(root, argv)
+                result = {**common, "status": "passed" if exit_code == 0 else "failed", "adapter_kind": "command", "origin": RESULT_ORIGINS[kind], "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",
+            elif kind == "http":
+                passed, exit_code, output = run_http_case(source, adapter)
+                result = {**common, "status": "passed" if passed else "failed", "adapter_kind": "http", "origin": RESULT_ORIGINS[kind],
                           "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)}
+            else:
+                outcome = playwright_adapter.execute(root, feature, tc_id, source, suite, adapter)
+                result = {**common, "adapter_kind": kind, "origin": RESULT_ORIGINS[kind], "started_at": started_at, **outcome}
+                result.setdefault("finished_at", utc_now())
+                result.setdefault("dsl_approval", "none")
             if strategy == "causal":
                 artifacts, artifact_errors = evidence_artifacts(root, entry.get("evidence_files"))
                 if artifact_errors:
-                    result["status"] = "failed"
+                    if result["status"] == "passed":
+                        result["status"] = "failed"
                     result["evidence_error"] = "; ".join(artifact_errors)
                 else:
                     result["evidence_artifacts"] = artifacts
             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"})
+            human = human_results[tc_id]
+            if "downgrade" in common:
+                override = valid_approval(root, feature, "mode_override", tc_id)
+                common["downgrade"]["approval_id"] = override["approval"]["id"] if override["ok"] else None
+            results.append({**common, "status": human["status"], "origin": "human_result_approval", "approval_id": human["approval_id"],
+                            "approved_at": human["approved_at"], "actual_result": human["actual_result"], "evidence_artifacts": human["evidence_artifacts"]})
         else:
-            results.append({"tc_id": tc_id, "status": "blocked", "mode": mode, "owner": entry["owner"], "blocked_by": entry["blocked_by"]})
+            blocked_result = {**common, "status": "blocked", "owner": entry["owner"], "blocked_by": entry["blocked_by"]}
+            if isinstance(entry.get("reason"), str):
+                blocked_result["reason"] = entry["reason"]
+            results.append(blocked_result)
     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):
@@ -390,7 +533,9 @@ def run(root: Path, feature: str, write: bool) -> dict[str, Any]:
                               "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:]}
+               "execution_binding_fingerprint": file_fingerprint(execution_bindings_path),
+               "human_acceptance_fingerprint": file_fingerprint(human_results_path(root, feature)),
+               "results": results, "passed": all_passed, "history": history[-20:]}
     if write:
         write_json(result_path, payload)
         meta_path = result_path.with_name("acceptance-results.meta.json")
@@ -403,6 +548,9 @@ def run(root: Path, feature: str, write: bool) -> dict[str, Any]:
             "acceptance_tc_passed": passed,
             "acceptance_tc_failed": failed,
             "acceptance_tc_blocked": blocked,
+            "acceptance_tc_legacy_unclassified": sum(1 for item in results if item.get("legacy_unclassified")),
+            "acceptance_tc_downgraded": sum(1 for item in results if item.get("downgrade")),
+            "acceptance_tc_dsl_unapproved": sum(1 for item in results if item.get("dsl_approval") == "none"),
             "acceptance_suite_graph_revision": payload["test_suite"].get("graph_revision"),
             "acceptance_results_fingerprint": file_fingerprint(result_path),
             "built_by": "core_acceptance_test_runner",
@@ -412,13 +560,190 @@ def run(root: Path, feature: str, write: bool) -> dict[str, Any]:
             "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)
+def _report_error(value: Any) -> dict[str, Any]:
+    text = str(value)
+    # Reports are safe summaries: do not expose project or run locations from gate diagnostics.
+    text = re.sub(r"(?:[A-Za-z]:)?[^\s,;()]+(?:/|\\)[^\s,;()]+", "<path>", text)
+    text = re.sub(r"(?:^|\s)(?:/|~/?|\.\.?/)[^\s,;()]+", " <path>", text)
+    truncated = len(text) > MAX_REPORT_ERROR_CHARS
+    return {"message": text[:MAX_REPORT_ERROR_CHARS], "truncated": True} if truncated else {"message": text, "truncated": False}
+
+
+def _result_summary(entry: dict[str, Any]) -> dict[str, Any]:
+    approval = entry.get("dsl_approval")
+    if isinstance(approval, dict):
+        approval = "approved" if approval.get("status") == "approved" else "none"
+    elif approval not in {"approved", "none"}:
+        approval = None
+    return {key: entry.get(key) for key in (
+        "tc_id", "status", "mode", "adapter_kind", "execution_surface", "error_code"
+    )} | {"dsl_approval": approval, "legacy_unclassified": bool(entry.get("legacy_unclassified")),
+        "downgrade": entry.get("downgrade")}
+
+
+def report(root: Path, feature: str) -> dict[str, Any]:
+    _, _, result_path = paths(root, feature)
+    if not result_path.is_file():
+        return {"ok": False, "feature": feature, "reason": "acceptance_results_missing"}
+    try:
+        payload = json.loads(result_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {"ok": False, "feature": feature, "reason": "acceptance_results_missing"}
+    if not isinstance(payload, dict) or not isinstance(payload.get("results"), list):
+        return {"ok": False, "feature": feature, "reason": "acceptance_results_missing"}
+    entries = [entry for entry in payload["results"] if isinstance(entry, dict)]
+    statuses = {status: sum(1 for entry in entries if entry.get("status") == status)
+                for status in ("passed", "failed", "blocked")}
+    counts = {"passed": statuses["passed"], "failed": statuses["failed"], "blocked": statuses["blocked"],
+              "legacy_unclassified": sum(bool(entry.get("legacy_unclassified")) for entry in entries),
+              "downgraded": sum(bool(entry.get("downgrade")) for entry in entries)}
+    gate = validate_results(root, feature)
+    raw_errors = gate.get("errors", []) if isinstance(gate, dict) else []
+    return {"ok": True, "feature": feature,
+            "gate": {"ok": bool(gate.get("ok")), "reason": gate.get("reason"),
+                     "errors": [_report_error(error) for error in raw_errors[:MAX_REPORT_ERRORS]]},
+            "executed_at": payload.get("executed_at"), "test_suite": payload.get("test_suite"),
+            "counts": counts, "results": [_result_summary(entry) for entry in entries]}
+
+
+def run_evidence_expired(root: Path, feature: str, today: date | None = None) -> bool:
+    """True only once release-closeout completed and the post-closeout retention window has elapsed.
+
+    Decision: a missing .devflow/runs/<feature>/<execution_id> directory is an error while the feature is
+    open or within DEFAULT_RUN_RETENTION_DAYS after closeout (gc_runs never removes referenced runs
+    earlier, so a missing directory then means deletion/tampering).  After that window gc-runs may have
+    removed it legitimately, so only the file-level evidence checks are skipped; every other recorded
+    field is still re-verified against current state.
+    """
+    closed = closeout_completed_on(root, feature)
+    return closed is not None and (today or datetime.now(timezone.utc).date()) >= closed + timedelta(days=DEFAULT_RUN_RETENTION_DAYS)
+
+
+def _recorded_str(entry: dict[str, Any], key: str) -> str | None:
+    value = entry.get(key)
+    return value if isinstance(value, str) and value else None
+
+
+def playwright_entry_errors(root: Path, feature: str, tc_id: str, source: dict[str, Any], suite: dict[str, Any], adapter: dict[str, Any],
+                            entry: dict[str, Any], run_dir_expired: bool) -> list[str]:
+    """A devflow_playwright result must still be backed by the CURRENT execution_plan and environment_profile approvals."""
+    errors: list[str] = []
+    if entry.get("origin") != playwright_adapter.RESULT_ORIGIN:
+        errors.append(f"origin must be {playwright_adapter.RESULT_ORIGIN}")
+    runtime = entry.get("runtime")
+    if not isinstance(runtime, dict) or not all(isinstance(runtime.get(key), str) and runtime[key] for key in ("version", "manifest_sha256")):
+        errors.append("runtime info (version, manifest_sha256) is missing")
+    for key in ("execution_id", "run_dir"):
+        if _recorded_str(entry, key) is None:
+            errors.append(f"{key} is missing")
+    if not (isinstance(entry.get("result_sha256"), str) and playwright_adapter.SHA256_RE.fullmatch(entry["result_sha256"])):
+        errors.append("result_sha256 is missing or malformed")
+    approval = entry.get("dsl_approval")
+    if approval == "none" or not isinstance(approval, dict) or approval.get("status") != "approved" or not _recorded_str(approval, "approval_id"):
+        errors.append(f"dsl_approval is {approval!r}, not an approved execution_plan approval")
+    if playwright_adapter.adapter_errors(root, feature, adapter):
+        return errors  # the binding itself is invalid; validate() already reported why
+    trust = playwright_adapter.resolve_trust(root, feature, tc_id, source, suite, adapter)
+    current = trust["base"]
+    if trust["failure"] is not None:
+        failure = trust["failure"]
+        return errors + [f"{failure.get('error_code')}: {failure.get('error')}"]
+    if entry.get("dsl_sha256") != current["dsl_sha256"]:
+        errors.append("recorded dsl_sha256 differs from the current DSL file (DSL edited after the run)")
+    if isinstance(approval, dict) and approval.get("approval_id") != current["dsl_approval"]["approval_id"]:
+        errors.append(f"recorded execution_plan approval {approval.get('approval_id')!r} is not the currently valid approval {current['dsl_approval']['approval_id']!r} (superseded or re-approved after the run)")
+    recorded_profile = entry.get("environment_profile")
+    current_profile = current["environment_profile"]
+    if not isinstance(recorded_profile, dict):
+        errors.append("environment_profile approval record is missing")
+    else:
+        if recorded_profile.get("name") != current_profile["name"] or recorded_profile.get("sha256") != current_profile["sha256"]:
+            errors.append("recorded environment profile hash differs from the current profile file (profile edited after the run)")
+        if recorded_profile.get("approval_id") != current_profile["approval_id"]:
+            errors.append(f"recorded environment_profile approval {recorded_profile.get('approval_id')!r} is not the currently valid approval {current_profile['approval_id']!r}")
+    errors.extend(playwright_adapter.recorded_run_errors(root, feature, tc_id, entry, run_dir_expired))
+    return errors
+
+
+def manual_entry_errors(root: Path, feature: str, tc_id: str, source: dict[str, Any], entry: dict[str, Any], human: dict[str, Any] | None) -> list[str]:
+    errors: list[str] = []
+    if entry.get("origin") != "human_result_approval":
+        errors.append("origin must be human_result_approval")
+    if human is None:
+        return errors + ["no currently valid human_result approval backs this manual result"]
+    for key in ("status", "actual_result", "approval_id", "evidence_artifacts"):
+        if entry.get(key) != human[key]:
+            errors.append(f"recorded {key} does not match the current human_result approval (superseded or evidence changed)")
+    downgrade = entry.get("downgrade")
+    if source.get("automation_mode") == "automated":
+        override = valid_approval(root, feature, "mode_override", tc_id)
+        if not isinstance(downgrade, dict) or (downgrade.get("from"), downgrade.get("to")) != ("automated", "manual"):
+            errors.append("automated -> manual downgrade is not recorded")
+        elif not override["ok"] or downgrade.get("approval_id") != override["approval"]["id"]:
+            errors.append("automated -> manual downgrade has no currently valid mode_override approval matching the recorded approval_id")
+    return errors
+
+
+def result_entry_errors(root: Path, feature: str, tc_id: str, source: dict[str, Any], suite: dict[str, Any], binding: dict[str, Any],
+                        entry: dict[str, Any], human: dict[str, Any] | None, run_dir_expired: bool) -> list[str]:
+    """Re-verify one recorded result against the CURRENT binding, frozen TC, approvals and evidence files."""
+    errors: list[str] = []
+    surface, _legacy = derive_surface(source)
+    mode = binding.get("mode")
+    if entry.get("mode") != mode:
+        errors.append(f"recorded mode {entry.get('mode')!r} does not match the current binding mode {mode!r}")
+    if entry.get("execution_surface") != surface:
+        errors.append(f"recorded execution_surface {entry.get('execution_surface')!r} does not match the frozen TC surface {surface!r}")
+    frozen_mode = source.get("automation_mode")
+    recorded_downgrade = entry.get("downgrade")
+    if mode != frozen_mode and (not isinstance(recorded_downgrade, dict) or (recorded_downgrade.get("from"), recorded_downgrade.get("to")) != (frozen_mode, mode)):
+        errors.append(f"downgrade {frozen_mode} -> {mode} is not recorded")
+    if mode == frozen_mode and recorded_downgrade is not None:
+        errors.append("a downgrade is recorded but the current binding does not downgrade this TC")
+    passed = entry.get("status") == "passed"
+    if passed and entry.get("tc_sha256") != tc_sha256(source):
+        errors.append("recorded tc_sha256 differs from the current frozen TC")
+    if mode == "manual":
+        return errors + manual_entry_errors(root, feature, tc_id, source, entry, human)
+    if mode != "automated":
+        return errors  # blocked entries never pass
+    adapter = binding.get("adapter") if isinstance(binding.get("adapter"), dict) else {}
+    kind = adapter.get("kind")
+    if entry.get("adapter_kind") != kind:
+        errors.append(f"recorded adapter_kind {entry.get('adapter_kind')!r} does not match the current binding adapter {kind!r}")
+        return errors
+    if surface is not None and kind not in ADAPTERS_BY_SURFACE[surface]:
+        errors.append(f"execution_surface_mismatch: execution_surface={surface} cannot be bound to adapter kind {kind}")
+    if kind in RESULT_ORIGINS and entry.get("origin") != RESULT_ORIGINS[kind]:
+        errors.append(f"origin {entry.get('origin')!r} does not match adapter kind {kind} (expected {RESULT_ORIGINS[kind]})")
+    if kind == "command":
+        if entry.get("argv") != adapter.get("argv") or (valid_argv(adapter.get("argv")) and entry.get("command_hash") != digest(json.dumps(adapter["argv"], ensure_ascii=False, separators=(",", ":")))):
+            errors.append("recorded command argv/command_hash differs from the current binding")
+    elif kind == "http":
+        if entry.get("adapter_fingerprint") != digest(json.dumps(adapter, ensure_ascii=False, separators=(",", ":"))):
+            errors.append("recorded HTTP adapter fingerprint differs from the current binding")
+    elif kind == playwright_adapter.ADAPTER_KIND and passed:
+        errors.extend(playwright_entry_errors(root, feature, tc_id, source, suite, adapter, entry, run_dir_expired))
+    if passed and source.get("evidence_strategy") == "causal":
+        recorded = entry.get("evidence_artifacts")
+        current, current_errors = evidence_artifacts(root, binding.get("evidence_files"))
+        if not isinstance(recorded, list) or not recorded:
+            errors.append("causal evidence_artifacts are not recorded")
+        elif current_errors:
+            errors.extend(current_errors)
+        elif [{"path": item.get("path"), "sha256": item.get("sha256")} for item in recorded if isinstance(item, dict)] != [{"path": item["path"], "sha256": item["sha256"]} for item in current]:
+            errors.append("causal evidence files differ from the recorded hashes (evidence changed)")
+    return errors
+
+
+def validate_results(root: Path, feature: str, today: date | None = None) -> dict[str, Any]:
+    """Hard-gate check: every recorded result must still hold against the CURRENT frozen TCs, bindings, approvals and evidence."""
+    validation, suite, bindings = 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}
+        return {"ok": False, "feature": feature, "reason": "acceptance_results_not_passed", "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 {}
@@ -432,14 +757,97 @@ def validate_results(root: Path, feature: str) -> dict[str, Any]:
     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))}
+    if suite is not None and isinstance(bindings, dict):
+        cases = frozen_cases(suite, [])
+        binding_by_id = {item["tc_id"]: item for item in bindings.get("cases", []) if isinstance(item, dict) and isinstance(item.get("tc_id"), str)}
+        _human_validation, human_results = validate_human_results(root, feature, suite, bindings)
+        expired = run_evidence_expired(root, feature, today)
+        seen: set[str] = set()
+        for entry in result_entries:
+            tc_id = entry.get("tc_id") if isinstance(entry, dict) else None
+            if not isinstance(tc_id, str) or tc_id not in cases or tc_id not in binding_by_id:
+                continue  # coverage mismatch is already reported above
+            if tc_id in seen:
+                errors.append(f"{tc_id}: duplicate result entry")
+                continue
+            seen.add(tc_id)
+            errors.extend(f"{tc_id}: {error}" for error in result_entry_errors(root, feature, tc_id, cases[tc_id], suite, binding_by_id[tc_id], entry, human_results.get(tc_id), expired))
+    result = {"ok": not errors, "feature": feature, "errors": errors, "result_path": str(result_path.relative_to(root))}
+    if errors:
+        result["reason"] = "acceptance_results_not_passed"
+    return result
+
+
+def closeout_completed_on(root: Path, feature: str) -> date | None:
+    """Date release-closeout completed for this feature according to STATE.md, if it did."""
+    try:
+        text = (root / ".devflow/planning" / "STATE.md").read_text(encoding="utf-8")
+    except OSError:
+        return None
+    match = re.match(r"\A---\s*\n(.*?)\n---", text, re.S)
+    if not match:
+        return None
+    front = match.group(1)
+    field = lambda name: (re.search(rf"^{name}:\s*['\"]?([^'\"\n]*)['\"]?\s*$", front, re.M) or [None, None])[1]
+    completed = re.search(r"^completed_steps:\s*\n((?:\s*-\s*.*\n?)*)", front, re.M)
+    steps = {line.strip()[1:].strip().strip("'\"") for line in completed.group(1).splitlines()} if completed else set()
+    if field("current_feature") != feature or "release-closeout" not in steps:
+        return None
+    try:
+        return date.fromisoformat(str(field("state_updated_at")))
+    except ValueError:
+        return None
+
+
+def referenced_execution_ids(result_path: Path) -> set[str]:
+    payload = read_json(result_path, [], "acceptance-test results") if result_path.is_file() else None
+    if not isinstance(payload, dict):
+        return set()
+    batches = [payload.get("results")] + [item.get("results") for item in payload.get("history", []) if isinstance(item, dict)]
+    return {entry["execution_id"] for batch in batches if isinstance(batch, list) for entry in batch
+            if isinstance(entry, dict) and isinstance(entry.get("execution_id"), str)}
+
+
+def gc_runs(root: Path, feature: str, write: bool, retention_days: int = DEFAULT_RUN_RETENTION_DAYS,
+            unreferenced_ttl_days: int = DEFAULT_UNREFERENCED_RUN_TTL_DAYS, today: date | None = None) -> dict[str, Any]:
+    """方案 §9.1: keep referenced runs until release-closeout + retention; expire unreferenced runs after a short TTL."""
+    today = today or datetime.now(timezone.utc).date()
+    directory = playwright_adapter.runs_dir(root, feature)
+    _, _, result_path = paths(root, feature)
+    referenced = referenced_execution_ids(result_path)
+    closed = closeout_completed_on(root, feature)
+    kept: list[dict[str, str]] = []
+    removed: list[str] = []
+    if directory.is_dir() and not directory.is_symlink():
+        for entry in sorted(directory.iterdir()):
+            name = entry.name
+            if entry.is_symlink() or not entry.is_dir() or not playwright_adapter.EXECUTION_ID_RE.fullmatch(name):
+                kept.append({"execution_id": name, "reason": "not a Core run directory"})
+                continue
+            started = datetime.strptime(name[:16], "%Y%m%dT%H%M%SZ").date()
+            if name in referenced:
+                if closed is None:
+                    kept.append({"execution_id": name, "reason": "referenced by acceptance-results.json before release-closeout"})
+                    continue
+                if today < closed + timedelta(days=retention_days):
+                    kept.append({"execution_id": name, "reason": f"referenced; retained {retention_days} days after release-closeout"})
+                    continue
+            elif today < started + timedelta(days=unreferenced_ttl_days):
+                kept.append({"execution_id": name, "reason": f"unreferenced run younger than {unreferenced_ttl_days} days"})
+                continue
+            removed.append(name)
+            if write:
+                shutil.rmtree(entry)
+    return {"ok": True, "feature": feature, "written": write, "removed": removed, "kept": kept}
 
 
 def main() -> int:
     parser = argparse.ArgumentParser()
-    parser.add_argument("action", choices=("validate", "run", "validate-results"))
+    parser.add_argument("action", choices=("validate", "validate-human", "run", "validate-results", "report", "gc-runs"))
     parser.add_argument("--feature", required=True)
     parser.add_argument("--write", action="store_true")
+    parser.add_argument("--retention-days", type=int, default=DEFAULT_RUN_RETENTION_DAYS)
+    parser.add_argument("--unreferenced-ttl-days", type=int, default=DEFAULT_UNREFERENCED_RUN_TTL_DAYS)
     parser.add_argument("--json", action="store_true")
     args = parser.parse_args()
     root = Path.cwd().resolve()
@@ -447,12 +855,21 @@ def main() -> int:
         result = {"ok": False, "errors": ["invalid feature"]}
     elif args.action == "validate":
         result, _, _ = validate(root, args.feature)
+    elif args.action == "validate-human":
+        suite_path, _, _ = paths(root, args.feature)
+        errors: list[str] = []
+        suite = read_json(suite_path, errors, "TC suite")
+        result = {"ok": False, "feature": args.feature, "errors": errors} if suite is None else validate_human_results(root, args.feature, suite)[0]
     elif args.action == "run":
         result = run(root, args.feature, args.write) if args.write else {"ok": False, "errors": ["--write is required for run"]}
+    elif args.action == "gc-runs":
+        result = gc_runs(root, args.feature, args.write, max(args.retention_days, 0), max(args.unreferenced_ttl_days, 0))
+    elif args.action == "report":
+        result = report(root, args.feature)
     else:
         result = validate_results(root, args.feature)
     print(json.dumps(result, ensure_ascii=False, indent=2))
-    return 0
+    return 0 if result.get("ok") is True else 1
 
 
 if __name__ == "__main__":