feat: add skip-stale-REQUEST_CHANGES reviewer menu prompt (#482)

Add a second reviewer workflow prompt to the root MCP operator menu:
"Skip already-reviewed stale REQUEST_CHANGES PR and hand off to author".

show_reviewer_prompts becomes a small 2-option submenu (mirroring the
existing show_author_prompts idiom): option 1 keeps the standard PR
review prompt; option 2 is the new prompt. It instructs the reviewer to
determine whether the current head already carries a non-stale
REQUEST_CHANGES verdict and, if so, to submit no new terminal review
mutation, run only handoff diagnostics, and return an author-ready fix
prompt with the full 8-field handoff.

Stacked on PR #479 (feat/issue-478-mcp-menu-shell); the menu is not yet
on master. Diff limited to the new prompt: mcp-menu.sh, docs/mcp-menu.md,
and a discoverability test in tests/test_mcp_menu_script.py.

Closes #482.

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

docs/mcp-menu.md

@@ -41,7 +41,7 @@ The script must be executable (`chmod +x mcp-menu.sh`). It uses bash with
 |--------|-------------|
 | Project status / root checkout health | Shows cwd, branch, `git status --short --branch`, HEAD SHA, `prgs/master` SHA, and warnings when the root checkout is dirty or off `master`. |
 | Author workflow prompts | Ready-to-copy prompts for issue work, conflict-fix sessions, and root checkout recovery. |
-| Reviewer workflow prompts | PR review prompt (review-only; no merge). |
+| Reviewer workflow prompts | Standard PR review prompt, and a skip-already-reviewed-stale-`REQUEST_CHANGES` prompt that hands off to the author without a duplicate terminal mutation (review-only; no merge). |
 | Merger workflow prompts | PR merge prompt (merge gates and explicit approval). |
 | Reconciler workflow prompts | Already-landed / closed PR reconciliation prompt. |
 | Onboarding new project | Checklist prompt for adding a repository to the MCP workflow. |

mcp-menu.sh

@@ -115,7 +115,15 @@ Workflow:
 }
 
 show_reviewer_prompts() {
-  print_prompt_block "Reviewer — PR review" \
+  while true; do
+    printf '\n--- Reviewer workflow prompts ---\n'
+    printf '  1) Standard PR review\n'
+    printf '  2) Skip already-reviewed stale REQUEST_CHANGES PR and hand off to author\n'
+    printf '  0) Back\n'
+    read -r -p 'Choice: ' choice
+    case "$choice" in
+      1)
+        print_prompt_block "Reviewer — PR review" \
 "You are the REVIEWER session for <org>/<repo>.
 
 Goal: review PR #<P> only — do not merge unless explicitly switched to merger mode.
@@ -126,6 +134,35 @@ Workflow:
 3. gitea_view_pr, validate scope, run required checks in the correct worktree.
 4. gitea_review_pr with approve, request-changes, or comment as warranted.
 5. Final report: PR head SHA, verdict, validation evidence, mutation ledger. No merge in reviewer-only runs."
+        ;;
+      2)
+        print_prompt_block "Reviewer — skip already-reviewed stale REQUEST_CHANGES PR and hand off to author" \
+"You are the REVIEWER session for <org>/<repo>.
+
+Goal: review PR #<P> only far enough to determine whether the current head already has a non-stale REQUEST_CHANGES verdict. If it does, do NOT submit another terminal review mutation — produce an author handoff and stop.
+
+Workflow:
+1. gitea_view_pr; pin the current head SHA.
+2. Load prior reviews; find the latest REQUEST_CHANGES and the head SHA it was bound to.
+3. If that REQUEST_CHANGES is still bound to the current head (non-stale), do not submit another terminal review mutation. Confirm the binding and summarize the blockers.
+4. Run only the diagnostics needed to produce a useful author handoff — no full re-review.
+5. Duplicate/supersession check: confirm no newer canonical PR or superseding head changes the decision.
+6. Stop — no new review mutation.
+
+Return:
+- selected PR and issue
+- current head SHA
+- prior REQUEST_CHANGES proof (review id + bound head SHA)
+- duplicate/supersession analysis
+- validation summary
+- why no new review mutation was submitted
+- corrected mutation ledger, including local worktree create/remove if used
+- author-ready fix prompt"
+        ;;
+      0) return ;;
+      *) printf 'Invalid choice.\n' ;;
+    esac
+  done
 }
 
 show_merger_prompts() {

tests/test_mcp_menu_script.py

@@ -105,6 +105,19 @@ class TestMcpMenuScript(unittest.TestCase):
         self.assertIn("./mcp-menu.sh", docs_text)
         self.assertIn("placeholder", docs_text.lower())
 
+    def test_reviewer_skip_stale_request_changes_prompt_discoverable(self):
+        # #482: the skip-already-reviewed-stale-REQUEST_CHANGES reviewer prompt
+        # must be reachable from the reviewer menu and documented.
+        label = "Skip already-reviewed stale REQUEST_CHANGES PR and hand off to author"
+        reviewer_fn = self._extract_function("show_reviewer_prompts")
+        self.assertIn(label, reviewer_fn, "new reviewer prompt label must appear in the reviewer menu")
+        # The prompt must instruct: no duplicate terminal review mutation for a
+        # non-stale REQUEST_CHANGES head, and must carry the author handoff.
+        self.assertIn("do NOT submit another terminal review mutation", reviewer_fn)
+        self.assertIn("author-ready fix prompt", reviewer_fn)
+        docs_text = DOCS.read_text(encoding="utf-8")
+        self.assertIn("REQUEST_CHANGES", docs_text)
+
     def _extract_function(self, name: str) -> str:
         marker = f"{name}() {{"
         start = self.content.index(marker)