@guanlin4924/devflow-pi 0.1.85 → 0.1.88

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

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""Read-only Core review preflight. Never runs an AI review or changes project files."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import subprocess
+import sys
+
+
+def sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def within(root: Path, relative: str) -> Path:
+    if not isinstance(relative, str) or not relative or Path(relative).is_absolute() or "\x00" in relative:
+        raise ValueError("invalid relative path")
+    path = (root / relative).resolve()
+    if not path.is_relative_to(root):
+        raise ValueError("path escapes project")
+    return path
+
+
+def load_workflow(path: Path) -> dict:
+    command = ["ruby", "-ryaml", "-rjson", "-e",
+               "puts JSON.generate(YAML.safe_load(File.read(ARGV.fetch(0)), permitted_classes: [], aliases: false))",
+               str(path)]
+    result = subprocess.run(command, text=True, capture_output=True, timeout=15, check=False)
+    if result.returncode:
+        raise ValueError(f"workflow cannot be read: {result.stderr.strip()}")
+    return json.loads(result.stdout)
+
+
+def load_state(path: Path) -> dict:
+    command = ["ruby", "-ryaml", "-rjson", "-e",
+               "front = File.read(ARGV.fetch(0)).match(/\\A---\\n(.*?)\\n---/m); "
+               "abort 'STATE front matter missing' unless front; "
+               "puts JSON.generate(YAML.safe_load(front[1], permitted_classes: [], aliases: false))",
+               str(path)]
+    result = subprocess.run(command, text=True, capture_output=True, timeout=15, check=False)
+    if result.returncode:
+        raise ValueError(f"STATE cannot be read: {result.stderr.strip()}")
+    return json.loads(result.stdout)
+
+
+def preflight(root: Path, feature: str, step: str, contract_path: str,
+              obligations: list[dict], review_agent: str | None = None,
+              review_contract_path: str | None = None, stage: str = "completion") -> dict:
+    root = root.resolve()
+    evidence, issues = [], []
+    if stage not in {"entry", "completion"}:
+        return {"status": "human_confirmation", "scope": "snapshot_preflight_only_not_gate_approval",
+                "evidence": [], "issues": [{"code": "INVALID_STAGE"}]}
+    try:
+        frozen_path = within(root, contract_path)
+        frozen = json.loads(frozen_path.read_text(encoding="utf-8"))
+        command = ["ruby", str(Path(__file__).with_name("execution_contract.rb")),
+                   "inspect", "--feature", feature, "--step", step, "--json"]
+        run = subprocess.run(command, cwd=root, text=True, capture_output=True, timeout=15, check=False)
+        current_result = json.loads(run.stdout)
+        if run.returncode or not current_result.get("ok"):
+            return {"status": "human_confirmation", "evidence": evidence,
+                    "issues": [{"code": "CURRENT_TRUTH_UNAVAILABLE", "detail": current_result.get("message", run.stderr)}]}
+        current = current_result["contract"]
+        evidence.extend([
+            {"kind": "state_graph", "state_revision": current["state_revision"],
+             "graph_revision": current["graph_revision"]},
+            {"kind": "contract", "path": contract_path, "sha256": sha256(frozen_path),
+             "contract_id": frozen.get("contract_id")},
+        ])
+        if frozen != current:
+            return {"status": "human_confirmation", "evidence": evidence,
+                    "issues": [{"code": "STALE_EXECUTION_CONTRACT",
+                                "detail": "frozen contract differs from current Core snapshot; recreate and retry"}]}
+        if frozen.get("feature") != feature or frozen.get("step") != step:
+            issues.append({"code": "CONTRACT_TARGET_MISMATCH", "detail": "contract feature/step mismatch"})
+        workflow_path = within(root, current["workflow_path"])
+        if sha256(workflow_path) != current["workflow_fingerprint"]:
+            return {"status": "human_confirmation", "evidence": evidence,
+                    "issues": [{"code": "STALE_WORKFLOW_SNAPSHOT"}]}
+        workflow = load_workflow(workflow_path)
+        state = load_state(within(root, ".planning/STATE.md"))
+        if state.get("revision") != current["state_revision"] or state.get("current_feature") != feature or state.get("current_step") != step:
+            return {"status": "human_confirmation", "evidence": evidence,
+                    "issues": [{"code": "STALE_STATE_SNAPSHOT"}]}
+        step_definition = next((item for item in workflow.get("steps", [])
+                                if isinstance(item, dict) and item.get("id") == step), None)
+        if step_definition is None:
+            raise ValueError("current workflow step unavailable")
+        render = lambda value: value.replace("{feature}", feature).replace("{phase}", str(state["current_phase"]))
+        derived = []
+        for raw in step_definition.get("inputs", []):
+            if isinstance(raw, str):
+                relative, required = raw, True
+            elif isinstance(raw, dict) and isinstance(raw.get("path"), str):
+                relative = raw["path"]
+                required = (raw.get("required", True) and raw.get("required_at_entry", True)) if stage == "entry" else raw.get("required_at_completion", raw.get("required", True))
+            else:
+                issues.append({"code": "INVALID_WORKFLOW_INPUT", "detail": "unrecognized input obligation"})
+                continue
+            if required and relative != ".planning/execution-contract.md":
+                derived.append({"path": render(relative), "producer": "existing"})
+        for item in step_definition.get("outputs", []):
+            if isinstance(item, dict) and item.get("required") is True and isinstance(item.get("path"), str):
+                derived.append({"path": render(item["path"]), "producer": "step"})
+        meta = step_definition.get("meta_output")
+        if isinstance(meta, dict) and isinstance(meta.get("path"), str):
+            derived.append({"path": render(meta["path"]), "producer": "step"})
+        evidence.append({"kind": "workflow", "path": current["workflow_path"],
+                         "sha256": current["workflow_fingerprint"],
+                         "required_obligation_count": len(derived),
+                         "checker_ids": current.get("checker_ids", [])})
+        if step == "code-review":
+            graph_relative = f".planning/requirements/{feature}/governance.json"
+            graph_path = within(root, graph_relative)
+            if not graph_path.is_file():
+                issues.append({"code": "CONFIRMED_EXPECTATIONS_UNAVAILABLE", "path": graph_relative})
+            else:
+                graph = json.loads(graph_path.read_text(encoding="utf-8"))
+                stale = {entry.get("node_id") for entry in graph.get("stale", []) if isinstance(entry, dict)}
+                relevant = [node for node in graph.get("nodes", [])
+                            if isinstance(node, dict) and node.get("kind") in {"requirement", "rule", "boundary", "acceptance"}]
+                unconfirmed = [node.get("id", "unknown") for node in relevant
+                               if node.get("status") != "confirmed" or node.get("id") in stale
+                               or not isinstance(node.get("confirmation"), dict)
+                               or node["confirmation"].get("origin") != "core"
+                               or not node["confirmation"].get("evidence")]
+                if graph.get("feature") != feature or graph.get("revision") != current["graph_revision"] or not relevant:
+                    issues.append({"code": "CONFIRMED_EXPECTATIONS_UNAVAILABLE", "path": graph_relative})
+                elif unconfirmed:
+                    issues.append({"code": "UNCONFIRMED_EXPECTATIONS", "path": graph_relative,
+                                   "node_ids": unconfirmed,
+                                   "detail": "Core review scope is not available; confirm or scope these nodes before task dispatch"})
+                else:
+                    evidence.append({"kind": "confirmed_expectations", "path": graph_relative,
+                                     "sha256": sha256(graph_path), "graph_revision": graph["revision"],
+                                     "node_ids": [node["id"] for node in relevant]})
+        if not derived and not current.get("checker_ids"):
+            issues.append({"code": "NO_REVIEW_OBLIGATIONS", "detail": "Core workflow defines no review obligations"})
+        supplied = {item.get("path"): item for item in obligations if isinstance(item, dict)}
+        for item in derived:
+            supplement = supplied.get(item["path"], {})
+            if supplement.get("producer") not in (None, item["producer"]):
+                issues.append({"code": "OBLIGATION_PRODUCER_MISMATCH", "path": item["path"]})
+            item.update({key: value for key, value in supplement.items() if key == "sha256"})
+        obligations = derived + [item for item in obligations if not isinstance(item, dict) or item.get("path") not in {d["path"] for d in derived}]
+        allowed = set(current.get("allowed_paths", []))
+        for index, obligation in enumerate(obligations):
+            if not isinstance(obligation, dict) or not isinstance(obligation.get("path"), str):
+                issues.append({"code": "INVALID_OBLIGATION", "index": index})
+                continue
+            relative = obligation["path"]
+            try:
+                path = within(root, relative)
+            except ValueError as error:
+                issues.append({"code": "INVALID_OBLIGATION_PATH", "index": index, "detail": str(error)})
+                continue
+            producer = obligation.get("producer")
+            if producer == "existing":
+                if not path.is_file():
+                    issues.append({"code": "MISSING_INPUT_FACT", "index": index, "path": relative})
+                elif obligation.get("sha256") is not None and obligation.get("sha256") != sha256(path):
+                    issues.append({"code": "STALE_INPUT_FACT", "index": index, "path": relative})
+                else:
+                    evidence.append({"kind": "input", "path": relative, "sha256": sha256(path)})
+            elif producer == "step":
+                if relative not in allowed:
+                    issues.append({"code": "UNREACHABLE_OBLIGATION", "index": index, "path": relative,
+                                   "detail": "step contract does not allow producing this path"})
+                else:
+                    evidence.append({"kind": "producer", "path": relative, "step": step,
+                                     "contract_id": current["contract_id"]})
+                    if path.is_file():
+                        evidence.append({"kind": "output_snapshot", "path": relative, "sha256": sha256(path)})
+                    elif stage == "completion":
+                        issues.append({"code": "MISSING_REVIEW_OUTPUT", "index": index, "path": relative})
+            else:
+                issues.append({"code": "UNKNOWN_PRODUCER", "index": index, "path": relative})
+        if step == "code-review" and review_agent not in (None, "devflow-code-reviewer"):
+            issues.append({"code": "REVIEW_AGENT_MISMATCH", "agent": review_agent,
+                           "detail": "code-review requires the independent devflow-code-reviewer"})
+        if step == "code-review":
+            review_agent = "devflow-code-reviewer"
+        if review_agent:
+            reviewer_contract = current
+            if review_contract_path:
+                review_path = within(root, review_contract_path)
+                reviewer_contract = json.loads(review_path.read_text(encoding="utf-8"))
+                evidence.append({"kind": "review_contract", "path": review_contract_path,
+                                 "sha256": sha256(review_path)})
+                if reviewer_contract.get("feature") != feature or reviewer_contract.get("graph_revision") != current.get("graph_revision"):
+                    issues.append({"code": "STALE_REVIEW_CONTRACT"})
+                # A separate step cannot be inspected while STATE points at the execution
+                # step. A supplied JSON file alone is not Core authority.
+                issues.append({"code": "REVIEW_CONTRACT_UNVERIFIED",
+                               "detail": "separate review contract needs a Core-verified step transition"})
+            if review_agent not in reviewer_contract.get("allowed_agents", []) or reviewer_contract.get("tool_budget", 0) < 1:
+                issues.append({"code": "REVIEW_AGENT_UNREACHABLE", "agent": review_agent,
+                               "detail": "review agent is not allowed or task budget is insufficient"})
+    except (OSError, ValueError, KeyError, TypeError, subprocess.TimeoutExpired) as error:
+        return {"status": "human_confirmation", "evidence": evidence,
+                "issues": [{"code": "PREFLIGHT_INPUT_UNAVAILABLE", "detail": str(error)}]}
+    conflict_codes = {"CONTRACT_TARGET_MISMATCH", "UNREACHABLE_OBLIGATION", "REVIEW_AGENT_MISMATCH",
+                      "REVIEW_AGENT_UNREACHABLE", "STALE_REVIEW_CONTRACT"}
+    status = ("core_contract_conflict" if any(issue["code"] in conflict_codes for issue in issues)
+              else "human_confirmation" if issues else "ready")
+    return {"status": status, "scope": "snapshot_preflight_only_not_gate_approval",
+            "evidence": evidence, "issues": issues}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, default=Path.cwd())
+    parser.add_argument("--feature", required=True)
+    parser.add_argument("--step", required=True)
+    parser.add_argument("--contract", required=True, help="project-relative frozen contract JSON")
+    parser.add_argument("--obligations", required=True, help="JSON array: {path, producer: existing|step, sha256?}")
+    parser.add_argument("--review-agent")
+    parser.add_argument("--review-contract", help="separate project-relative reviewer contract JSON")
+    parser.add_argument("--stage", choices=["entry", "completion"], default="completion")
+    args = parser.parse_args()
+    try:
+        obligations = json.loads(args.obligations)
+        if not isinstance(obligations, list):
+            raise ValueError("obligations must be an array")
+        result = preflight(args.root.resolve(), args.feature, args.step, args.contract,
+                           obligations, args.review_agent, args.review_contract, args.stage)
+    except ValueError as error:
+        result = {"status": "human_confirmation", "evidence": [],
+                  "issues": [{"code": "INVALID_INPUT", "detail": str(error)}]}
+    print(json.dumps(result, ensure_ascii=False, sort_keys=True))
+    return 0 if result["status"] == "ready" else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -7,6 +7,7 @@ pretend that a source excerpt alone proves runtime behaviour.
 from __future__ import annotations
 
 import hashlib
+import hmac
 import json
 import os
 from pathlib import Path
@@ -36,6 +37,29 @@ def canonical(value: Any) -> str:
     return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
 
 
+def verified_review_binding(request: dict) -> tuple[bool, str]:
+    """A completed reviewer task, not the caller, owns the submitted report."""
+    binding = request.get("core_review_binding")
+    secret = os.environ.get("DEVFLOW_REVIEW_BINDING_KEY", "")
+    if not isinstance(binding, dict) or not secret:
+        return False, "missing Core-bound independent reviewer task"
+    fields = ("agent", "feature", "contract_id", "task_call_id", "report_sha256", "signature")
+    if any(not isinstance(binding.get(field), str) or not binding[field] for field in fields):
+        return False, "incomplete Core reviewer task binding"
+    target = request.get("target")
+    if binding["agent"] != "devflow-code-reviewer" or not isinstance(target, dict) or binding["feature"] != target.get("feature"):
+        return False, "reviewer identity or feature does not match the report"
+    unsigned_report = {key: value for key, value in request.items() if key != "core_review_binding"}
+    report_hash = digest(canonical(unsigned_report).encode())
+    if not hmac.compare_digest(report_hash, binding["report_sha256"]):
+        return False, "review report differs from the completed reviewer task"
+    unsigned_binding = {key: binding[key] for key in fields if key != "signature"}
+    expected = hmac.new(secret.encode(), canonical(unsigned_binding).encode(), hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, binding["signature"]):
+        return False, "invalid Core reviewer task signature"
+    return True, ""
+
+
 def safe_file(root: Path, relative: str) -> Path:
     if not isinstance(relative, str) or not relative or Path(relative).is_absolute() or "\x00" in relative:
         raise ValueError("path must be a nonempty project-relative path")
@@ -136,6 +160,10 @@ def db_open(root: Path) -> sqlite3.Connection:
         id INTEGER PRIMARY KEY, chain_id TEXT, status TEXT NOT NULL, detail_json TEXT NOT NULL,
         created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
       );
+      CREATE TABLE IF NOT EXISTS reviewer_tasks (
+        task_call_id TEXT PRIMARY KEY, chain_id TEXT NOT NULL, round INTEGER NOT NULL,
+        report_sha256 TEXT NOT NULL
+      );
     """)
     return db
 
@@ -221,6 +249,35 @@ def verify_core_result(root: Path, feature: str, evidence: Any, expected_status:
         return False, f"unreadable Core acceptance result: {exc}"
 
 
+def verify_core_impact(root: Path, feature: str, evidence: dict, impact: str, trigger: str) -> tuple[bool, str]:
+    """A failed TC alone does not establish the reviewer's causal/impact label."""
+    try:
+        suite = read_json(safe_file(root, f".planning/requirements/{feature}/tests.json"))
+        node = next((n for n in suite.get("nodes", []) if isinstance(n, dict) and n.get("id") == evidence.get("tc_id")), None)
+        data = node.get("data", {}) if node else {}
+        if data.get("review_impact") == impact and data.get("review_trigger") == trigger:
+            return True, ""
+        return False, "Core frozen TC does not confirm the claimed failure trigger and business impact"
+    except (OSError, ValueError, TypeError, json.JSONDecodeError) as exc:
+        return False, f"Core frozen impact cannot be verified: {exc}"
+
+
+def declared_change_paths(root: Path, feature: str) -> tuple[set[str], str, str]:
+    relative = f".planning/features/{feature}/变更清单.md"
+    source = safe_file(root, relative)
+    declarations = re.findall(r"^\s*-\s*\*\*文件\*\*\s*[：:]\s*(.+)$", source.read_text(encoding="utf-8"), re.MULTILINE)
+    paths = set()
+    for declaration in declarations:
+        matches = re.findall(r"`([^`]+)`", declaration)
+        if len(matches) != 1 or declaration.strip() != f"`{matches[0]}`":
+            raise ValueError("ambiguous change-list file declaration")
+        safe_file(root, matches[0])
+        paths.add(matches[0])
+    if not paths:
+        raise ValueError("change list has no unambiguous source file declarations")
+    return paths, relative, digest(source.read_bytes())
+
+
 def verify_coverage(root: Path, feature: str, required: list[str], coverage_evidence: Any) -> tuple[set[str], list[str]]:
     if not isinstance(coverage_evidence, dict):
         return set(), ["Each review surface and scenario needs a distinct Core TC binding"]
@@ -241,7 +298,10 @@ def verify_coverage(root: Path, feature: str, required: list[str], coverage_evid
         suite = read_json(safe_file(root, f".planning/requirements/{feature}/tests.json"))
         node = next((n for n in suite.get("nodes", []) if isinstance(n, dict) and n.get("id") == ref["tc_id"]), None)
         types = {"scenario:normal": {"api", "page"}, "scenario:unauthorized": {"permission"}, "scenario:failure_rollback": {"resilience", "boundary"}, "scenario:compatibility": {"migration"}}
-        if not node or node.get("kind") != "test_case" or node.get("status") != "confirmed" or node.get("data", {}).get("test_type") not in types.get(tag, set()):
+        data = node.get("data", {}) if node else {}
+        explicit = tag in data.get("review_coverage_tags", []) if isinstance(data.get("review_coverage_tags"), list) else False
+        typed = data.get("test_type") in types.get(tag, set())
+        if not node or node.get("kind") != "test_case" or node.get("status") != "confirmed" or not (explicit or typed):
             issues.append(f"{tag}: frozen TC type cannot prove this coverage obligation; request human confirmation")
             continue
         covered.add(tag)
@@ -256,10 +316,139 @@ def suite_has_failures(root: Path, feature: str) -> bool:
         return True
 
 
+def gate_status(root: Path, feature: str, contract_id: str | None = None) -> dict:
+    """Read only the Core ledger; prose reports never confer approval."""
+    root = root.resolve(strict=True)
+    if not contract_id:
+        return {"status": "human_confirmation", "reason": "Current Core review contract identity is required"}
+    try:
+        contract = read_json(safe_file(root, f".planning/contracts/{feature}/{contract_id}.json"))
+        if contract.get("origin") != "core_execution_contract" or contract.get("step") != "code-review" or contract.get("feature") != feature or contract.get("contract_id") != contract_id:
+            return {"status": "core_contract_conflict", "reason": "Review contract identity is not a frozen Core code-review contract"}
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        from review_preflight import load_state
+        state = load_state(safe_file(root, ".planning/STATE.md"))
+        graph = read_json(safe_file(root, f".planning/requirements/{feature}/governance.json"))
+        workflow = safe_file(root, contract["workflow_path"])
+        if (state.get("current_feature") != feature or state.get("current_step") != "code-review"
+            or state.get("revision") != contract.get("state_revision")
+            or graph.get("revision") != contract.get("graph_revision")
+            or digest(workflow.read_bytes()) != contract.get("workflow_fingerprint")):
+            return {"status": "stale_evidence", "reason": "Review contract differs from current Core state, graph, or workflow"}
+    except (OSError, ValueError, KeyError, TypeError, ImportError, json.JSONDecodeError) as exc:
+        return {"status": "human_confirmation", "reason": f"Current Core review contract cannot be verified: {exc}"}
+    database = root / ".planning" / "review-runs" / "review-runs.sqlite"
+    if not database.is_file() or database.is_symlink():
+        return {"status": "human_confirmation", "reason": "No Core review round exists"}
+    db = sqlite3.connect(f"file:{database}?mode=ro", uri=True)
+    try:
+        rows = db.execute("SELECT result_json FROM rounds ORDER BY created_at DESC, rowid DESC").fetchall()
+    finally:
+        db.close()
+    for (raw,) in rows:
+        result = json.loads(raw)
+        task = result.get("reviewer_task", {})
+        if task.get("feature") != feature:
+            continue
+        if task.get("contract_id") != contract_id:
+            continue
+        report_path = next((item for item in contract.get("allowed_paths", []) if isinstance(item, str) and item.endswith("/REVIEW.md")), None)
+        if not report_path:
+            return {"status": "core_contract_conflict", "reason": "Core contract has no REVIEW.md output"}
+        try:
+            if safe_file(root, report_path).read_text(encoding="utf-8") != review_markdown(result):
+                return {"status": "core_contract_conflict", "reason": "REVIEW.md differs from Core review round"}
+        except (OSError, ValueError):
+            return {"status": "core_contract_conflict", "reason": "Core-derived REVIEW.md is missing"}
+        if task.get("agent") != "devflow-code-reviewer":
+            return {"status": "core_contract_conflict", "reason": "Review round lacks independent reviewer"}
+        fixed = result.get("fixed_versions", {})
+        index_generation = fixed.get("code_index_generation")
+        if index_generation is not None:
+            try:
+                snapshot = read_json(safe_file(root, ".planning/code-index/SNAPSHOT.json"))
+                if snapshot.get("generation") != index_generation:
+                    return {"status": "stale_evidence", "reason": "Code-index generation changed after review", "chain_id": result.get("chain_id")}
+            except (OSError, ValueError, json.JSONDecodeError):
+                return {"status": "stale_evidence", "reason": "Code-index snapshot unavailable after review", "chain_id": result.get("chain_id")}
+        for relative, expected in fixed.get("source", {}).items():
+            try:
+                if digest(safe_file(root, relative).read_bytes()) != expected:
+                    return {"status": "stale_evidence", "reason": f"Source changed after review: {relative}", "chain_id": result.get("chain_id")}
+            except (OSError, ValueError):
+                return {"status": "stale_evidence", "reason": f"Source unavailable after review: {relative}", "chain_id": result.get("chain_id")}
+        for authority in fixed.get("authority", []):
+            try:
+                if digest(safe_file(root, authority["authority_path"]).read_bytes()) != authority["authority_sha256"]:
+                    return {"status": "stale_evidence", "reason": "Authority changed after review", "chain_id": result.get("chain_id")}
+            except (OSError, ValueError, KeyError):
+                return {"status": "stale_evidence", "reason": "Authority unavailable after review", "chain_id": result.get("chain_id")}
+        for relative, expected in fixed.get("core_results", {}).items():
+            try:
+                if digest(safe_file(root, relative).read_bytes()) != expected:
+                    return {"status": "stale_evidence", "reason": f"Core test evidence changed after review: {relative}", "chain_id": result.get("chain_id")}
+            except (OSError, ValueError):
+                return {"status": "stale_evidence", "reason": f"Core test evidence unavailable: {relative}", "chain_id": result.get("chain_id")}
+        plan = fixed.get("change_plan", {})
+        try:
+            if not plan or digest(safe_file(root, plan["path"]).read_bytes()) != plan["sha256"]:
+                return {"status": "stale_evidence", "reason": "Core change-list scope changed after review", "chain_id": result.get("chain_id")}
+        except (OSError, ValueError, KeyError, TypeError):
+            return {"status": "stale_evidence", "reason": "Core change-list scope unavailable", "chain_id": result.get("chain_id")}
+        status = result.get("status")
+        verdict = "pass" if status == "clean" and result.get("automatic_release_allowed") else ("terminate_task" if status == "terminated_p0" else "repair")
+        return {"status": verdict, "chain_id": result.get("chain_id"), "round": result.get("round"), "evidence_chain": {"reviewer_task": task, "fixed_versions": fixed, "coverage": result.get("coverage")}, "open_findings": [f for f in result.get("findings", []) if f.get("state") != "resolved"], "next_action": "advance" if verdict == "pass" else ("stop_current_task" if verdict == "terminate_task" else "repair_and_re_review")}
+    return {"status": "human_confirmation", "reason": "No Core review round exists for this feature and contract"}
+
+
+def review_markdown(result: dict) -> str:
+    lines = ["# Code Review", "", "> Core-derived view; the review ledger is authoritative.", "", f"- Chain: `{result['chain_id']}`", f"- Round: {result['round']}", f"- Decision: `{result['status']}`", f"- Reviewer task: `{result['reviewer_task']['task_call_id']}`", "", "## Open findings", ""]
+    for finding in result.get("findings", []):
+        if finding.get("state") != "resolved":
+            source = finding.get("source", {})
+            lines.append(f"- `{finding['finding_id']}` {finding['severity']}: {source.get('path')}:{source.get('line')} — {finding.get('actual', '')}")
+    if lines[-1] == "":
+        lines.append("- None")
+    lines.extend(["", "## Next action", "", "Advance to the next workflow step." if result.get("status") == "clean" else "Repair findings and request a new independent review.", ""])
+    return "\n".join(lines)
+
+
+def render_review(root: Path, feature: str, contract_id: str) -> dict:
+    root = root.resolve(strict=True)
+    contract = read_json(safe_file(root, f".planning/contracts/{feature}/{contract_id}.json"))
+    path = next((item for item in contract.get("allowed_paths", []) if isinstance(item, str) and item.endswith("/REVIEW.md")), None)
+    if not path:
+        return {"status": "core_contract_conflict", "reason": "Core contract has no REVIEW.md output"}
+    database = root / ".planning/review-runs/review-runs.sqlite"
+    if not database.is_file():
+        return {"status": "human_confirmation", "reason": "No Core review round exists"}
+    db = sqlite3.connect(f"file:{database}?mode=ro", uri=True)
+    try:
+        rows = db.execute("SELECT result_json FROM rounds ORDER BY created_at DESC, rowid DESC").fetchall()
+    finally:
+        db.close()
+    for (raw,) in rows:
+        result = json.loads(raw)
+        task = result.get("reviewer_task", {})
+        if task.get("feature") == feature and task.get("contract_id") == contract_id:
+            destination = root / path
+            if destination.is_symlink() or not destination.resolve().is_relative_to(root):
+                return {"status": "core_contract_conflict", "reason": "Unsafe review output path"}
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            temporary = destination.with_name(destination.name + ".core-tmp")
+            if temporary.exists() or temporary.is_symlink():
+                return {"status": "core_contract_conflict", "reason": "Review output temporary path is occupied"}
+            temporary.write_text(review_markdown(result), encoding="utf-8")
+            os.replace(temporary, destination)
+            return {"status": "rendered", "path": path, "chain_id": result["chain_id"], "round": result["round"]}
+    return {"status": "human_confirmation", "reason": "No Core review round exists for this contract"}
+
+
 def run(root: Path, request: dict) -> dict:
     root = root.resolve(strict=True)
     if not isinstance(request, dict):
         raise ValueError("request must be an object")
+    bound, binding_issue = verified_review_binding(request)
     if "round" in request or "findings" in request or "severity" in request:
         raise ValueError("Core assigns rounds and findings; caller-supplied authority fields are forbidden")
     target = request.get("target")
@@ -275,6 +464,9 @@ def run(root: Path, request: dict) -> dict:
         raise ValueError("review_plan.questions must be nonempty")
     if not all(isinstance(q, str) and q.strip() for q in plan["questions"]):
         raise ValueError("review questions must be strings")
+    review_questions = request.get("review_questions", [])
+    if not isinstance(review_questions, list) or not all(isinstance(q, str) and q.strip() for q in review_questions):
+        raise ValueError("review_questions must be a list of nonempty strings")
     surfaces, scenarios = plan.get("surfaces"), plan.get("required_scenarios")
     if not isinstance(surfaces, list) or not set(surfaces) <= SURFACES or not isinstance(scenarios, list) or not set(scenarios) <= SCENARIOS:
         raise ValueError("review plan uses an unsupported surface or scenario")
@@ -284,6 +476,14 @@ def run(root: Path, request: dict) -> dict:
     if not isinstance(expectations, list):
         raise ValueError("expectations must be a list")
     accepted, questions = validate_authority(root, target["feature"], expectations)
+    try:
+        declared_paths, change_plan_path, change_plan_hash = declared_change_paths(root, target["feature"])
+        missing_paths = declared_paths - set(paths)
+        if missing_paths:
+            questions.append("Review target omits change-list files: " + ", ".join(sorted(missing_paths)))
+    except (OSError, ValueError, UnicodeError) as exc:
+        declared_paths, change_plan_path, change_plan_hash = set(), None, None
+        questions.append(f"Core change-list review scope cannot be verified: {exc}")
     chain_id = request.get("chain_id")
     if chain_id is not None and (not isinstance(chain_id, str) or not chain_id.startswith("rev_")):
         raise ValueError("invalid chain_id")
@@ -311,11 +511,14 @@ def run(root: Path, request: dict) -> dict:
                 raise ValueError("three completed review rounds exhausted")
         else:
             round_no = 1
-        if questions:
-            result = response("awaiting_human_confirmation", chain_id, round_no, questions=questions)
+        if questions or review_questions:
+            result = response("awaiting_human_confirmation", chain_id, round_no, questions=[*questions, *review_questions])
             db.execute("INSERT INTO events(chain_id,status,detail_json) VALUES(?,?,?)", (chain_id, result["status"], canonical(result)))
             db.commit()
             return result
+        binding = request.get("core_review_binding") if bound else None
+        if bound and db.execute("SELECT 1 FROM reviewer_tasks WHERE task_call_id=?", (binding["task_call_id"],)).fetchone():
+            raise ValueError("reviewer task was already consumed by another review round")
         if not chain_id:
             # A new ID cannot erase an unresolved P0 for the same target and authority.
             for old_id, raw in db.execute("SELECT c.chain_id,r.result_json FROM chains c JOIN rounds r ON r.chain_id=c.chain_id AND r.round=(SELECT MAX(round) FROM rounds WHERE chain_id=c.chain_id) WHERE c.target_key=? AND c.authority_key=?", (target_key, authority_key)):
@@ -370,6 +573,10 @@ def run(root: Path, request: dict) -> dict:
                 valid, reason = verify_core_result(root, target["feature"], item.get("runtime_evidence"), "failed", authority_node_id)
                 if not valid:
                     evidence_issues.append(f"{evidence['path']}:{evidence['line']}: {reason}")
+                else:
+                    causal, reason = verify_core_impact(root, target["feature"], item["runtime_evidence"], item["impact"], item.get("trigger"))
+                    if not causal:
+                        evidence_issues.append(f"{evidence['path']}:{evidence['line']}: {reason}; human confirmation required")
             fingerprint = digest(canonical([item["expectation_id"], evidence["path"], evidence["line"], item["impact"], item.get("trigger")]).encode())[:20]
             findings.append({"finding_id": "F-" + fingerprint, "expectation_id": item["expectation_id"], "severity": IMPACTS[item["impact"]], "severity_source": "reviewer_claim", "impact": item["impact"], "source": evidence, "actual": item.get("actual"), "trigger": item.get("trigger"), "reproduction": item.get("reproduction"), "improvement": item.get("improvement"), "confidence": "source_and_core_tc_verified_causality_unverified" if item.get("runtime_evidence") else "source_verified_inference", "epistemic_status": "reviewer_interpretation", "verified_boundaries": ["approved_core_graph_expectation", "source_line_and_hash", "core_tc_identity_and_status"] if item.get("runtime_evidence") else ["approved_core_graph_expectation", "source_line_and_hash"]})
         gaps = sorted(set(required) - covered)
@@ -390,13 +597,12 @@ def run(root: Path, request: dict) -> dict:
                     evidence_issues.append(f"{old_id}: source unchanged; cannot resolve by removing a report observation")
                 else:
                     regression = request.get("regression_evidence", {}).get(old_id)
-                    try:
-                        if not isinstance(regression, dict) or digest(safe_file(root, regression.get("path")).read_bytes()) != regression.get("sha256"):
-                            evidence_issues.append(f"{old_id}: missing verified regression evidence")
-                        else:
-                            findings.append({**old, "state": "resolved"})
-                    except (OSError, ValueError, TypeError):
-                        evidence_issues.append(f"{old_id}: missing verified regression evidence")
+                    authority_node_id = next((e["node_id"] for e in accepted if e["id"] == old.get("expectation_id")), None)
+                    valid, reason = verify_core_result(root, target["feature"], regression, "passed", authority_node_id)
+                    if not valid:
+                        evidence_issues.append(f"{old_id}: missing Core passed regression TC: {reason}")
+                    else:
+                        findings.append({**old, "state": "resolved"})
         for rel, start_hash in versions.items():
             if digest(safe_file(root, rel).read_bytes()) != start_hash:
                 result = response("stale_evidence", chain_id, round_no, questions=[f"Source changed during review: {rel}"])
@@ -424,33 +630,24 @@ def run(root: Path, request: dict) -> dict:
             return result
         open_findings = [f for f in findings if f["state"] != "resolved"]
         summary = {p: sum(f["severity"] == p for f in open_findings) for p in ("P0", "P1", "P2", "P3")}
-        if open_findings:
-            # Source and TC hashes establish identity, not that the reviewer's
-            # causal story or impact category is true. Until Core has a
-            # verifiable independent-review attestation, these are proposals,
-            # not completed rounds that can terminate a task after three tries.
-            result = response(
-                "awaiting_human_confirmation", chain_id, round_no,
-                questions=["Independent reviewer identity and business causality/impact require confirmation"],
-                proposed_findings=open_findings,
-                proposed_risk_summary=summary,
-                proposed_improvement_plan=[{"finding_id": f["finding_id"], "severity": f["severity"], "action": f["improvement"]} for f in open_findings],
-                coverage={"covered": sorted(covered), "gaps": gaps},
-            )
+        if not bound:
+            result = response("awaiting_human_confirmation", chain_id, round_no, questions=[binding_issue], proposed_findings=open_findings, proposed_risk_summary=summary, coverage={"covered": sorted(covered), "gaps": gaps})
             db.execute("INSERT INTO events(chain_id,status,detail_json) VALUES(?,?,?)", (chain_id, result["status"], canonical(result)))
             db.commit()
             return result
-        if not summary["P0"] and not summary["P1"]:
+        if not open_findings:
             reasons = [*evidence_issues]
             if suite_has_failures(root, target["feature"]):
                 reasons.append("The same Core acceptance run contains failed or blocked TCs; clean cannot be inferred from selected passed cases")
-            reasons.append("No Core-verifiable independent reviewer identity or causal semantic attestation is available; clean needs human confirmation")
-            result = response("awaiting_human_confirmation", chain_id, round_no, questions=reasons, coverage={"covered": sorted(covered), "gaps": gaps})
-            db.execute("INSERT INTO events(chain_id,status,detail_json) VALUES(?,?,?)", (chain_id, result["status"], canonical(result)))
-            db.commit()
-            return result
-        status = "terminated_p0" if round_no == 3 and summary["P0"] else ("findings" if summary["P0"] or summary["P1"] else "clean")
-        result = response(status, chain_id, round_no, fixed_versions={"source": versions, "authority": accepted, "code_index_generation": index_discovery.get("generation")}, index_discovery=index_discovery, coverage={"covered": sorted(covered), "gaps": gaps, "index_gap": index_discovery.get("reason") if index_discovery["status"] != "located" else None}, findings=findings, risk_summary=summary, improvement_plan=[{"finding_id": f["finding_id"], "severity": f["severity"], "action": f["improvement"]} for f in sorted(open_findings, key=lambda x: x["severity"])], all_p0_resolved=summary["P0"] == 0, severity_source="reviewer_claim", semantic_causality_verified=False, automatic_release_allowed=False, termination_scope="review_chain_only" if status == "terminated_p0" else None, history=[{"round": r, "status": json.loads(raw)["status"]} for r, raw in db.execute("SELECT round,result_json FROM rounds WHERE chain_id=? ORDER BY round", (chain_id,))])
+            if reasons:
+                result = response("awaiting_human_confirmation", chain_id, round_no, questions=reasons, coverage={"covered": sorted(covered), "gaps": gaps})
+                db.execute("INSERT INTO events(chain_id,status,detail_json) VALUES(?,?,?)", (chain_id, result["status"], canonical(result)))
+                db.commit()
+                return result
+        status = "terminated_p0" if round_no == 3 and summary["P0"] else ("findings" if open_findings else "clean")
+        core_results = {rel: digest(safe_file(root, rel).read_bytes()) for rel in (f".planning/requirements/{target['feature']}/tests.json", f".planning/test-runs/{target['feature']}/acceptance-results.json")}
+        result = response(status, chain_id, round_no, fixed_versions={"source": versions, "authority": accepted, "core_results": core_results, "change_plan": {"path": change_plan_path, "sha256": change_plan_hash, "declared_paths": sorted(declared_paths)}, "code_index_generation": index_discovery.get("generation")}, index_discovery=index_discovery, coverage={"covered": sorted(covered), "gaps": gaps, "index_gap": index_discovery.get("reason") if index_discovery["status"] != "located" else None}, findings=findings, risk_summary=summary, improvement_plan=[{"finding_id": f["finding_id"], "severity": f["severity"], "action": f["improvement"]} for f in sorted(open_findings, key=lambda x: x["severity"])], all_p0_resolved=summary["P0"] == 0, severity_source="independent_reviewer_core_evidence_bound", semantic_causality_verified=True, automatic_release_allowed=status == "clean", termination_scope="current_task_only" if status == "terminated_p0" else None, reviewer_task={key: binding[key] for key in ("agent", "feature", "contract_id", "task_call_id", "report_sha256")}, history=[{"round": r, "status": json.loads(raw)["status"]} for r, raw in db.execute("SELECT round,result_json FROM rounds WHERE chain_id=? ORDER BY round", (chain_id,))])
+        db.execute("INSERT INTO reviewer_tasks(task_call_id,chain_id,round,report_sha256) VALUES(?,?,?,?)", (binding["task_call_id"], chain_id, round_no, binding["report_sha256"]))
         db.execute("INSERT INTO rounds(chain_id,round,result_json) VALUES(?,?,?)", (chain_id, round_no, canonical(result)))
         if status == "terminated_p0":
             db.execute("UPDATE chains SET terminal=? WHERE chain_id=?", (status, chain_id))
@@ -466,7 +663,12 @@ def run(root: Path, request: dict) -> dict:
 if __name__ == "__main__":
     try:
         project = Path(sys.argv[1] if len(sys.argv) > 1 else os.getcwd())
-        print(canonical(run(project, json.load(sys.stdin))))
+        if len(sys.argv) > 3 and sys.argv[2] == "--gate":
+            print(canonical(gate_status(project.resolve(strict=True), sys.argv[3], sys.argv[4] if len(sys.argv) > 4 else None)))
+        elif len(sys.argv) > 4 and sys.argv[2] == "--render":
+            print(canonical(render_review(project, sys.argv[3], sys.argv[4])))
+        else:
+            print(canonical(run(project, json.load(sys.stdin))))
     except (ValueError, OSError, json.JSONDecodeError, sqlite3.Error, StaleEvidence) as error:
         print(canonical({"status": "error", "error": str(error)}))
         sys.exit(2)