feat: add controller issue-acceptance gate (Closes #500)

Add issue_acceptance_gate validation for Controller Issue Acceptance
comments, final-report rules blocking merge-only issue completion claims,
documentation/templates, and regression tests.

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

final_report_validator.py

@@ -11,6 +11,7 @@ import inspect
 import re
 from typing import Any, Callable
 
+import issue_acceptance_gate
 import issue_lock_provenance
 from review_proofs import (
     HANDOFF_HEADING,
@@ -1007,6 +1008,22 @@ def _rule_shared_manual_lock_pr_override(report_text: str) -> list[dict[str, str
     )
 
 
+def _rule_shared_issue_acceptance_gate(report_text: str) -> list[dict[str, str]]:
+    result = issue_acceptance_gate.validate_final_report_issue_acceptance(report_text)
+    if not result.get("applicable") or result.get("valid"):
+        return []
+    return _findings_from_reasons(
+        "shared.issue_acceptance_gate",
+        result.get("reasons") or [],
+        field="Controller acceptance",
+        severity="block",
+        safe_next_action=(
+            "add Controller Issue Acceptance proof or state that controller "
+            "acceptance is pending; do not claim issue complete from PR merge alone"
+        ),
+    )
+
+
 def _rule_shared_author_reviewer_same_run(report_text: str) -> list[dict[str, str]]:
     result = issue_lock_provenance.assess_author_reviewer_same_run_report(report_text)
     if result.get("proven"):
@@ -1095,6 +1112,7 @@ _RULES_BY_TASK: dict[str, list[Callable[..., list[dict[str, str]]]]] = {
         _rule_shared_controller_handoff,
         _rule_shared_email_disclosure,
         *_SHARED_ISSUE_LOCK_RULES,
+        _rule_shared_issue_acceptance_gate,
         _rule_reviewer_vague_mutations_none,
         _rule_conflict_fix_push_proof,
     ],