fix(agent): surface pending capsule review details (#38)

* fix(agent): surface pending capsule review details

* fix(skill): require explicit capsule review choice

* fix(skill): keep capsule review handoff concise

* test: replace brittle guidance text assertions

Author: sunjiajunsunjiajun

docs/superpowers/plans/2026-07-19-pending-capsule-review-summary.md

@@ -0,0 +1,67 @@
+# Pending Capsule Review Summary Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ensure agents list every pending capsule candidate in the user's language whenever a final response still requires review.
+
+**Architecture:** Add matching behavioral contracts to the generated global AGENTS guidance and the packaged `rgit-capture` skill. Keep translation in the presentation layer and preserve proposal ids, capsule names, code symbols, configuration keys, file paths, and stored records.
+
+**Tech Stack:** Python string rendering, Markdown skill instructions, pytest, isolated Codex behavior validation.
+
+**Spec:** `docs/superpowers/specs/2026-07-19-pending-capsule-review-summary-design.md`
+
+## Global Constraints
+
+- No new CLI command, dependency, or storage schema.
+- List every candidate as stored name plus one-line intent; include key knobs only when they affect the choice.
+- A candidate count alone is not an acceptable final review summary.
+- Translate explanatory prose and intent into the user's current language, but preserve stable identifiers and stored data.
+
+---
+
+### Task 1: Define the host-agent behavior check
+
+- [ ] Create an isolated Git repository with a real `.rgit/` store and one
+      open proposal containing multiple English-language candidates.
+- [ ] Load the branch versions of the global guidance and `rgit-capture`
+      skill, then ask an isolated Codex session to finish in another language
+      without approving, dismissing, or rewriting the proposal.
+- [ ] Verify the final response includes every candidate and key choice-relevant
+      knob, preserves stable identifiers, requests the user's decision, and
+      leaves the stored proposal unchanged.
+
+---
+
+### Task 2: Add the matching instruction contracts
+
+**Files:**
+- Modify: `src/rgit/agent_guidance.py`
+- Modify: `src/rgit/_plugin/skills/rgit-capture/SKILL.md`
+
+**Interfaces:**
+- Consumes: pending proposal data already available from `rgit pending --json`.
+- Produces: agent instructions only; no runtime API changes.
+
+- [ ] **Step 1: Update global final-feedback guidance**
+
+Replace the current state-only sentence with a compact rule that lists pending
+proposal details, follows the user's current language, preserves identifiers,
+and forbids count-only summaries.
+
+- [ ] **Step 2: Add the capture-skill final-response fallback**
+
+After the normal review instructions, require the same presentation whenever a
+proposal remains open at the end of a response.
+
+- [ ] **Step 3: Run the existing focused tests**
+
+Run: `python -m pytest tests/test_agent_guidance.py tests/test_installer.py tests/test_guidance_coupling.py -q`
+
+Expected: existing guidance coupling and packaging tests pass without
+hard-coding the new prose in test assertions.
+
+- [ ] **Step 4: Run the full suite**
+
+Run: `python -m pytest -q`
+
+Expected: all tests pass with no new warnings or failures.

docs/superpowers/specs/2026-07-19-pending-capsule-review-summary-design.md

@@ -0,0 +1,68 @@
+# Pending Capsule Review Summary
+
+**Date:** 2026-07-19
+**Status:** approved
+
+## Problem
+
+When a run ends with open research-git proposals, an agent can report only the
+number of capsule candidates awaiting review. The user cannot make the required
+human decision because the final response omits the candidates' concrete
+contents.
+
+The capture skill already asks the agent to show each candidate during the
+normal review step, but the global guidance has no equivalent requirement for
+the final response. There is also no fallback in the skill for a turn that ends
+before the review decision is complete.
+
+## Design
+
+Use the same compact review contract in both instruction layers:
+
+- The global AGENTS guidance requires final feedback to report open proposals.
+  For every open proposal, list its stable proposal id and every candidate's
+  stored name plus a one-line explanation of its intent. Include key knobs only
+  when they affect the user's choice. A count alone is not sufficient.
+- The `rgit-capture` skill keeps its normal interactive review flow and adds a
+  final-response fallback. If any proposal remains open when the agent is about
+  to finish, the agent presents the same candidate list and asks which names to
+  keep.
+- User-facing explanations follow the language the user is currently using,
+  regardless of the language stored in the capsule. Proposal ids, capsule names,
+  code symbols, configuration keys, and file paths remain unchanged.
+- Translation is presentation-only. It never changes candidates stored under
+  `.rgit`.
+
+## Output Shape
+
+```text
+Pending capsule review
+
+Proposal prop_abc:
+- reranking-retrieval: Add a reranking stage before final retrieval.
+- cache-fallback: Fall back to uncached retrieval when cache lookup fails.
+  Key knob: fallback_timeout
+
+Tell me which capsule names to keep. Nothing is approved until you decide.
+```
+
+For a Chinese-speaking user, the intent and surrounding prose are presented in
+Chinese while `prop_abc`, `reranking-retrieval`, `cache-fallback`, and
+`fallback_timeout` remain unchanged.
+
+## Testing
+
+- Run an isolated host-agent behavior check against a real pending proposal
+  with multiple candidates and a user language different from the stored
+  intents.
+- Verify the final response lists every candidate, translates presentation
+  text, preserves stable identifiers, requests a review decision, and leaves
+  the stored proposal unchanged.
+- Keep guidance coupling and installer packaging tests passing.
+
+## Out of Scope
+
+- New CLI commands or output formats.
+- Changes to proposal or capsule storage schemas.
+- Translating or rewriting stored capsule records.
+- Truncating candidate lists. The final response lists every candidate.

src/rgit/_plugin/skills/rgit-capture/SKILL.md

@@ -66,6 +66,10 @@ Lost the ids from step 2? Bare `rgit review` re-lists every open proposal with i
 
 4. Echo the `approved -> <feature_id>` lines back to the user, then continue to step 6.
 
+If any proposal remains open when you are about to finish a response, include a `Pending capsule review` section before finishing. List each proposal id and every candidate's stored name and one-line intent; include key knobs only when they affect the choice. Never replace this list with only a candidate count. Present the explanations and intents in the language the user is currently using, even when the stored capsule uses another language. Do not translate proposal ids, capsule names, code symbols, configuration keys, or file paths. Translation is presentation-only; never rewrite the stored candidates.
+
+Keep the handoff compact. Do not add a separate Git, capsule, or graph status list unless the user explicitly asked for those details. After the candidate list, end with exactly one short paragraph in the user's language that combines the unresolved status and decision request: ask which capsule names to keep, whether to keep all, or whether to discard all; state in the first person that you will execute the review for the user and that kept candidates will be approved and stored as capsules. Do not repeat candidate names as reply examples, render a separate decision menu, or say only that review "can" be executed. Do not approve, discard, or otherwise make a review decision before the user confirms.
+
 ### 6. Infer graph edges (deterministic baseline + agent-judged relationships)
 
 After approval, wire the new capsules into the graph:

src/rgit/agent_guidance.py

@@ -88,7 +88,14 @@ def render_global_block(mode: str = "default") -> str:
         "scan` stages a plan (plain `rgit init` offers it), then the "
         "`rgit-digest` skill drains the queue batch by batch.\n"
         "- In final feedback, mention any capsules created, approved, applied, "
-        "or skipped, plus important graph relations.\n"
+        "or skipped, plus important graph relations. If open proposals awaiting "
+        "review remain, list each proposal id and every candidate's stored name "
+        "and one-line intent; include key knobs only when they affect the choice. "
+        "A candidate count alone is not enough. Present explanations in the "
+        "language the user is currently using, regardless of the stored capsule "
+        "language. Keep proposal ids, capsule names, code symbols, configuration "
+        "keys, and file paths unchanged; translation is presentation-only and "
+        "must not modify the stored capsule.\n"
     )
     provisional = f"{START}\n{body}{END}\n"
     h = canonical_hash(provisional)