refactor: harden reviewer handoff command surface (#562)

* refactor: harden reviewer handoff command surface

* fix: align reviewer handoff hardening

* fix: close reviewer feedback handoff gaps

* fix: finalize reviewer feedback handoff ordering

* fix: close reviewer command authority gaps

Author: PLeVasseur

REVIEWING.md

@@ -86,7 +86,6 @@ permission to persist reviewer-bot state.
 
 Who can run it:
 - The currently assigned reviewer
-- A maintainer with triage+ permission
 
 What it does (for the current PR only):
 - If the latest review by the assigned reviewer is `APPROVED`, it marks the review complete.

scripts/reviewer_bot_core/comment_command_policy.py

@@ -11,6 +11,7 @@
 class OrdinaryCommandId(StrEnum):
     PASS = "pass"
     AWAY = "away"
+    FEEDBACK = "feedback"
     DONE = "done"
     LABEL = "label"
     SYNC_MEMBERS = "sync-members"
@@ -103,6 +104,26 @@ def decide_comment_command(bot, request, classified, *, actor_class: str, comman
             success=False,
             react=True,
         )
+    if command == OrdinaryCommandId.FEEDBACK.value:
+        if args:
+            return InlineResponseDecision(
+                response=f"❌ `/feedback` does not accept arguments. Usage: `{bot.BOT_MENTION} /feedback`",
+                success=False,
+                react=True,
+            )
+        return ExecuteOrdinaryCommandDecision(
+            command_id=OrdinaryCommandId.FEEDBACK,
+            issue_number=issue_number,
+            actor=comment_author,
+            raw_args=(),
+            needs_assignment_request=False,
+        )
+    if command == "_malformed_feedback_args":
+        return InlineResponseDecision(
+            response=f"❌ `/feedback` does not accept arguments. Usage: `{bot.BOT_MENTION} /feedback`",
+            success=False,
+            react=True,
+        )
     if command == OrdinaryCommandId.DONE.value:
         return ExecuteOrdinaryCommandDecision(
             command_id=OrdinaryCommandId.DONE,

scripts/reviewer_bot_core/review_state_machine.py

@@ -97,6 +97,18 @@ def _compare_records(left: dict | None, right: dict | None) -> int:
     return 0
 
 
+def _clear_handoff_after_newer_contributor_event(review_data: dict, timestamp: str) -> bool:
+    handoff = review_data.get("current_cycle_reviewer_handoff")
+    if not isinstance(handoff, dict):
+        return False
+    contributor_time = parse_github_timestamp(timestamp)
+    handoff_time = parse_github_timestamp(handoff.get("timestamp"))
+    if contributor_time is None or handoff_time is None or contributor_time <= handoff_time:
+        return False
+    review_data["current_cycle_reviewer_handoff"] = None
+    return True
+
+
 def semantic_key_seen(review_data: dict, channel_name: str, semantic_key: str) -> bool:
     channel = _ensure_channel_map(review_data, channel_name)
     return semantic_key in channel["seen_keys"]
@@ -135,6 +147,8 @@ def accept_channel_event(
     current = channel.get("accepted")
     if _compare_records(candidate, current) >= 0:
         channel["accepted"] = candidate
+    if channel_name in {"contributor_comment", "contributor_revision"}:
+        _clear_handoff_after_newer_contributor_event(review_data, timestamp)
     return True
 
 
@@ -161,9 +175,17 @@ def _reset_cycle_state(review_data: dict) -> None:
         review_data[channel] = {"accepted": None, "seen_keys": []}
     review_data["current_cycle_completion"] = {}
     review_data["current_cycle_write_approval"] = {}
+    review_data["current_cycle_reviewer_handoff"] = None
     review_data["overdue_anchor"] = None
 
 
+def clear_current_cycle_reviewer_handoff(review_data: dict) -> bool:
+    if review_data.get("current_cycle_reviewer_handoff") is None:
+        return False
+    review_data["current_cycle_reviewer_handoff"] = None
+    return True
+
+
 def set_current_reviewer(
     state: dict,
     issue_number: int,
@@ -204,6 +226,7 @@ def clear_current_reviewer(state: dict, issue_number: int) -> bool:
     if review_data.get("assignment_method") is not None:
         review_data["assignment_method"] = None
         changed = True
+    changed = clear_current_cycle_reviewer_handoff(review_data) or changed
     clear_transition_timers(review_data)
     return changed
 

scripts/reviewer_bot_core/review_state_types.py

@@ -45,6 +45,17 @@ class ReviewChannelState:
     seen_keys: list[str] = field(default_factory=list)
 
 
+@dataclass
+class CurrentCycleReviewerHandoff:
+    """Maps to the exact persisted `/feedback` reviewer handoff shape."""
+
+    source_event_key: str
+    timestamp: str
+    actor: str
+    command_name: str
+    reviewed_head_sha: str | None = None
+
+
 @dataclass
 class ReviewEntryState:
     """Maps to the persisted review entry fields used by the future C1 cutover.
@@ -79,3 +90,4 @@ class ReviewEntryState:
     review_dismissal: ReviewChannelState = field(default_factory=ReviewChannelState)
     current_cycle_completion: dict[str, Any] = field(default_factory=dict)
     current_cycle_write_approval: dict[str, Any] = field(default_factory=dict)
+    current_cycle_reviewer_handoff: CurrentCycleReviewerHandoff | None = None