fix(issue-fix): require PR-description recall before review notification (#2344)

* fix(issue-fix): gate reviewer notification on PR evidence

* refactor(issue-fix): narrow review gate to recall evidence

Author: huangruiteng

examples/issue-fix-pr-description-builder-smoke.py

@@ -85,6 +85,7 @@
     assert counter.read_text() == "1", "enabled build must call provider once"
     assert applied["description"].startswith("## 动机"), applied
     preference = applied["semantic_preference"]
+    assert preference["recall_executed"] is True, preference
     assert preference["application_status"] == "applied", preference
     assert preference["receipt"]["outcome"] == "applied", preference
     assert preference["corpus_inventory"][0]["corpus_id"] == (
@@ -185,6 +186,7 @@
     )
     assert counter.read_text() == "1", "disabled build must not call provider"
     assert disabled_result["description"] == BASE, disabled_result
+    assert disabled_result["semantic_preference"]["recall_executed"] is True
     assert disabled_result["semantic_preference"]["recall_status"] == "disabled"
 
     def unexpected_recall(*_args, **_kwargs):
@@ -196,6 +198,7 @@ def unexpected_recall(*_args, **_kwargs):
         recall_fn=unexpected_recall,
     )
     assert unconfigured["description"] == BASE, unconfigured
+    assert unconfigured["semantic_preference"]["recall_executed"] is False
 
     failing = temp / "failing.json"
     failing.write_text(
@@ -225,6 +228,7 @@ def unexpected_recall(*_args, **_kwargs):
         ),
     )
     assert unavailable["description"].endswith("Fixes #22\n"), unavailable
+    assert unavailable["semantic_preference"]["recall_executed"] is True
     assert unavailable["fail_open_preserved_base"] is True, unavailable
 
     unattributed = build_issue_fix_pr_description(

examples/issue-fix-reviewer-request-smoke.py

@@ -1969,6 +1969,61 @@ def drain_metadata_loader(
         assert drain_calls[-1]["number"] == 103
         assert len(drain_calls) == 3
 
+        write(path / ".loopx/config/semantic-preference.json", "{}")
+        gated_combined = FakeCombinedRunner(FakeGitHubRunner(before=metadata()))
+        missing_publication_evidence = build_issue_fix_reviewer_request_packet(
+            repo_path=path,
+            url="https://github.com/owner/repo/pull/42",
+            base_ref="main",
+            notification_sinks_input=sinks_input,
+            execute=True,
+            runner=gated_combined,
+        )
+        assert missing_publication_evidence["ok"] is False
+        assert missing_publication_evidence["blocker"] == (
+            "pr_description_recall_evidence_required"
+        )
+        assert missing_publication_evidence["selected_reviewers"] == []
+        assert missing_publication_evidence["external_writes_performed"] is False
+        assert missing_publication_evidence["pr_description_publication_gate"][
+            "required_evidence_inputs"
+        ] == ["pr_description_build_json"]
+        assert missing_publication_evidence["secondary_notification_status"] == (
+            "skipped_reviewer_unavailable"
+        )
+        assert gated_combined.github.edits == 0
+        assert gated_combined.github.comments == 0
+        assert gated_combined.lark_calls == []
+        assert_public_safe(missing_publication_evidence)
+
+        publication_build = {
+            "schema_version": "issue_fix_pr_description_build_v0",
+            "semantic_preference": {
+                "surface": "issue_fix.pr_description",
+                "recall_executed": True,
+                "recall_status": "completed",
+            },
+        }
+        verified_runner = FakeGitHubRunner(
+            before=metadata(),
+            after=metadata(requested=["service-owner"]),
+        )
+        verified_publication = build_issue_fix_reviewer_request_packet(
+            repo_path=path,
+            url="https://github.com/owner/repo/pull/42",
+            base_ref="main",
+            pr_description_build=publication_build,
+            execute=True,
+            runner=verified_runner,
+        )
+        assert verified_publication["ok"] is True, verified_publication
+        assert verified_publication["pr_description_publication_gate"]["status"] == (
+            "verified"
+        )
+        assert verified_publication["review_request_verified"] is True
+        assert verified_runner.edits == 1
+        assert_public_safe(verified_publication)
+
         subprocess.run(
             [
                 sys.executable,

loopx/capabilities/issue_fix/pr_description.py

@@ -9,6 +9,7 @@
 
 
 BUILD_SCHEMA = "issue_fix_pr_description_build_v0"
+PUBLICATION_GATE_SCHEMA = "issue_fix_pr_description_publication_gate_v0"
 SURFACE = "issue_fix.pr_description"
 ISSUE_REFERENCE_BLOCK_SCHEMA = "issue_fix_pr_issue_reference_block_v0"
 
@@ -34,14 +35,54 @@
     "resolves": "Resolves",
     "resolved": "Resolves",
 }
-
 PreferenceApplier = Callable[
     [str, Sequence[Mapping[str, Any]]],
     Mapping[str, Any],
 ]
 Recall = Callable[..., dict[str, Any]]
 
 
+def validate_issue_fix_pr_description_publication(
+    *,
+    project: str | Path,
+    build_packet: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Require only proof that the PR-description recall path executed."""
+
+    recall_required = (
+        Path(project).expanduser().resolve()
+        / ".loopx/config/semantic-preference.json"
+    ).exists()
+    preference = (
+        build_packet.get("semantic_preference")
+        if isinstance(build_packet, Mapping)
+        and build_packet.get("schema_version") == BUILD_SCHEMA
+        else None
+    )
+    preference = preference if isinstance(preference, Mapping) else {}
+    recall_executed = preference.get("recall_executed") is True
+    ok = not recall_required or recall_executed
+
+    return {
+        "ok": ok,
+        "schema_version": PUBLICATION_GATE_SCHEMA,
+        "status": (
+            "verified"
+            if recall_executed
+            else "not_required"
+            if ok
+            else "blocked"
+        ),
+        "blocker": None if ok else "pr_description_recall_evidence_required",
+        "recall_required": recall_required,
+        "recall_executed": recall_executed,
+        "recall_status": str(preference.get("recall_status") or "") or None,
+        "required_evidence_inputs": (
+            ["pr_description_build_json"] if recall_required else []
+        ),
+    }
+
+
 def _normalise_issue_references(
     values: Sequence[str] | None, *, field: str
 ) -> list[str]:
@@ -162,6 +203,7 @@ def _result(
     description: str,
     recall_status: str,
     application_status: str,
+    recall_executed: bool = False,
     recalled_item_count: int = 0,
     applied_preference_count: int = 0,
     receipt: Mapping[str, Any] | None = None,
@@ -182,6 +224,7 @@ def _result(
         "description_changed": description_changed or issue_reference_changed,
         "semantic_preference": {
             "surface": SURFACE,
+            "recall_executed": recall_executed,
             "recall_status": recall_status,
             "application_status": application_status,
             "recalled_item_count": recalled_item_count,
@@ -294,6 +337,7 @@ def build_issue_fix_pr_description(
             description=base_description,
             recall_status=recall_status,
             application_status=recall_status,
+            recall_executed=True,
             fail_open_preserved_base=recall_status == "provider_unavailable",
             issue_reference_policy=issue_reference_policy,
             corpus_inventory=corpus_inventory,
@@ -304,6 +348,7 @@ def build_issue_fix_pr_description(
             description=base_description,
             recall_status=recall_status,
             application_status="available_not_applied",
+            recall_executed=True,
             recalled_item_count=len(items),
             issue_reference_policy=issue_reference_policy,
             corpus_inventory=corpus_inventory,
@@ -337,6 +382,7 @@ def build_issue_fix_pr_description(
             description=base_description,
             recall_status=recall_status,
             application_status="application_failed",
+            recall_executed=True,
             recalled_item_count=len(items),
             receipt=application_receipt(
                 surface=SURFACE,
@@ -355,6 +401,7 @@ def build_issue_fix_pr_description(
         description=description,
         recall_status=recall_status,
         application_status=outcome,
+        recall_executed=True,
         recalled_item_count=len(items),
         applied_preference_count=len(set(applied_refs)),
         receipt=application_receipt(

loopx/capabilities/issue_fix/reviewer_cli.py

@@ -215,6 +215,13 @@ def register_issue_fix_reviewer_commands(
             "verifies GitHub state instead."
         ),
     )
+    reviewer_request_parser.add_argument(
+        "--pr-description-build-json",
+        help=(
+            "Compact issue_fix_pr_description_build_v0 JSON proving the PR "
+            "description recall path executed before notification writes."
+        ),
+    )
     reviewer_request_parser.add_argument(
         "--notification-sinks-json",
         help=(
@@ -801,6 +808,11 @@ def semantic_history_matcher(
         reviewer_artifact_reward_memory=reviewer_artifact_reward_memory,
         reviewer_notification_reward_memory=reviewer_notification_reward_memory,
         reviewer_artifact_required=reviewer_artifact_required,
+        pr_description_build=(
+            load_json_object(args.pr_description_build_json)
+            if getattr(args, "pr_description_build_json", None)
+            else None
+        ),
         provider_payload=(
             load_json_object(args.metadata_json) if args.metadata_json else None
         ),

loopx/capabilities/issue_fix/reviewer_request.py

@@ -9,6 +9,7 @@
 
 from ...control_plane.runtime.public_safety import public_safe_compact_text
 from .metadata_preview import normalise_github_issue_reference
+from .pr_description import validate_issue_fix_pr_description_publication
 from .reviewer_notification import (
     NotificationSinkAdapter,
     build_issue_fix_reviewer_notification_sinks_result,
@@ -525,6 +526,7 @@ def build_issue_fix_reviewer_request_packet(
     reviewer_artifact_reward_memory: Mapping[str, Any] | None = None,
     reviewer_notification_reward_memory: Mapping[str, Any] | None = None,
     reviewer_artifact_required: bool = False,
+    pr_description_build: Mapping[str, Any] | None = None,
     provider_payload: Mapping[str, Any] | None = None,
     execute: bool = False,
     generated_at: str | None = "2026-07-10T00:00:00Z",
@@ -562,6 +564,10 @@ def build_issue_fix_reviewer_request_packet(
         )
         external_reads = True
         metadata = fetched or {}
+    publication_gate = validate_issue_fix_pr_description_publication(
+        project=repo_path,
+        build_packet=pr_description_build,
+    )
     identities = _metadata_identities(metadata, repo=repo, number=number)
     excluded = list(exclude_reviewers)
     if identities["author_handle"]:
@@ -604,7 +610,11 @@ def build_issue_fix_reviewer_request_packet(
     ][:remaining_slots]
     author_exclusion_verified = bool(identities["author_handle"])
     pr_state_verified = identities["state"] in {"OPEN", "CLOSED", "MERGED"}
-    if not author_exclusion_verified or not pr_state_verified:
+    if (
+        not author_exclusion_verified
+        or not pr_state_verified
+        or publication_gate["ok"] is not True
+    ):
         selected = []
 
     existing_notified_reviewers = list(
@@ -633,7 +643,7 @@ def build_issue_fix_reviewer_request_packet(
     )
 
     packet: dict[str, Any] = {
-        "ok": metadata_error is None,
+        "ok": metadata_error is None and publication_gate["ok"] is True,
         "schema_version": ISSUE_FIX_REVIEWER_REQUEST_SCHEMA_VERSION,
         "mode": "issue-fix-reviewer-request",
         "generated_at": generated_at,
@@ -681,6 +691,7 @@ def build_issue_fix_reviewer_request_packet(
             execute and identities["semantic_comment_notified_reviewers"]
         ),
         "reviewer_comment_url": existing_comment_url,
+        "pr_description_publication_gate": publication_gate,
         "private_repo_state_read": True,
         "local_paths_captured": False,
         "raw_provider_payload_captured": False,
@@ -710,6 +721,17 @@ def build_issue_fix_reviewer_request_packet(
             ),
             material_change=True,
         )
+    elif publication_gate["ok"] is not True:
+        packet["blocker"] = publication_gate["blocker"]
+        packet["transition"] = _transition(
+            decision="blocker",
+            action_kind="issue_fix_pr_description_recall_evidence",
+            reason=(
+                "Run the PR-description recall path and pass its compact build "
+                "packet before requesting review or sending a notification."
+            ),
+            material_change=False,
+        )
     elif not author_exclusion_verified:
         packet["ok"] = False
         packet["blocker"] = "github_pr_author_unavailable"