feat: verify canonical workflow citation and version in review reports (Closes #296)

The canonical PR review/merge workflow already lives in
skills/llm-project-workflow/workflows/review-merge-pr.md and is exposed
through mcp_list_project_skills / mcp_get_skill_guide (#333-#335), and
its final-report schema already demands a workflow version. What was
missing is enforcement: add compute_workflow_hash (short sha256
version hash of workflow text) and assess_review_workflow_source to
review_proofs. Review reports must cite the canonical workflow file
and carry a populated Workflow version field; when the current
canonical hash is supplied, a mismatched citation fails as a stale
workflow copy, directing the agent to reload via mcp_get_skill_guide.
Fails closed. Tests cover hash determinism and content sensitivity,
matching-hash pass, missing citation, missing version field, stale
hash, version none, and offline validation without a canonical hash.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

review_proofs.py

@@ -14,6 +14,7 @@ is usable from prompts, harness assertions, and tests. The MCP-level gates
 here weakens or replaces them.
 """
 
+import hashlib
 import re
 
 import issue_duplicate_gate
@@ -3097,6 +3098,67 @@ def assess_issue_filing_duplicate_summary(
     }
 
 
+# ── Canonical review-workflow citation and version proof (Issue #296) ────────
+#
+# The canonical PR review/merge workflow lives in
+# skills/llm-project-workflow/workflows/review-merge-pr.md and is exposed
+# via mcp_get_skill_guide. Review reports must prove they loaded it and
+# cite the version hash used, so stale or shortened prompt copies are
+# rejected.
+
+REVIEW_WORKFLOW_MARKERS = (
+    "workflows/review-merge-pr.md",
+    "review-merge-pr.md",
+)
+
+
+def compute_workflow_hash(workflow_text):
+    """Return the short (12-hex) sha256 version hash of a workflow text."""
+    digest = hashlib.sha256((workflow_text or "").encode("utf-8"))
+    return digest.hexdigest()[:12]
+
+
+def assess_review_workflow_source(report_text, *, canonical_hash=None):
+    """#296: review reports must cite the canonical workflow and version.
+
+    The report must reference the canonical workflow file and carry a
+    populated ``Workflow version`` (or ``Workflow hash``) field. When
+    *canonical_hash* — ``compute_workflow_hash`` of the current
+    workflows/review-merge-pr.md content — is supplied, the cited hash
+    must match it, rejecting stale copies.
+
+    Returns {'complete', 'downgraded', 'reasons'}; fails closed.
+    """
+    lower = (report_text or "").lower()
+    reasons = []
+
+    if not any(marker in lower for marker in REVIEW_WORKFLOW_MARKERS):
+        reasons.append(
+            "review report missing canonical workflow source citation "
+            "(workflows/review-merge-pr.md)"
+        )
+
+    fields = _report_labeled_fields(report_text)
+    version = fields.get("workflow version") or fields.get("workflow hash")
+    if not version or version.strip().lower().startswith(("none", "unknown")):
+        reasons.append(
+            "review report missing populated 'Workflow version' field "
+            "(version/hash of the canonical workflow used)"
+        )
+    elif canonical_hash and canonical_hash.lower() not in version.lower():
+        reasons.append(
+            f"review report cites stale workflow version '{version}'; "
+            f"current canonical hash is '{canonical_hash}' — reload the "
+            "workflow via mcp_get_skill_guide"
+        )
+
+    return {
+        "complete": not reasons,
+        "downgraded": bool(reasons),
+        "reasons": reasons,
+    }
+
+
 def assess_create_issue_workflow_source(report_text: str) -> dict:
     """#337: create-issue reports must cite the canonical workflow file."""
     lower = (report_text or "").lower()