feat(ce-review): add per-finding judgment loop to Interactive mode

[tmchow]

Summary

Before this PR, ce:review's Interactive mode asked one bucket-level policy question covering every remaining gated_auto and manual finding. Users either approved the whole bucket, deferred the whole bucket, or scrolled a pipe-delimited table with no way to engage per-item. In practice it degraded into rubber-stamping or wholesale deferral — the gated_auto / manual routing tiers in the schema existed but were never exercised per-finding.

After this PR, a four-option routing question dispatches to focused interactions sized to the user's intent: a per-finding walk-through with plain-English framing for engaged review, an LFG path with a compact plan preview for trust-and-ship moments, a batch-file-tickets path for teams that triage in Linear / Jira / GitHub Issues, and a report-only exit. Defer actions route to the project's tracker via reasoning-based detection — never to the deprecated internal .context/ todo store. The redesign ships together with supporting changes: deterministic recommended-action tie-breaking so LFG is auditable, a shared-template framing-guidance upgrade so walk-through content comes from persona output directly, and a presentation split that keeps the question stem compact while the finding explanation renders with full markdown hierarchy.

Fixes #562

What's different

flowchart TD
    A[safe_auto fixes applied] --> B{Any gated/manual<br/>findings remain?}
    B -->|No| Z[Completion summary -> Step 5]
    B -->|Yes| C[Four-option<br/>routing question]

    C -->|A Review| W[Per-finding<br/>walk-through]
    C -->|B LFG| P1[Bulk preview]
    C -->|C File tickets| P2[Bulk preview]
    C -->|D Report only| E[Exit]

    W -->|Apply/Defer/Skip| W
    W -->|LFG the rest| P3[Bulk preview<br/>scoped to remaining]

    P1 -->|Proceed| X[Apply -> Step 3 fixer<br/>Defer -> tracker<br/>Skip/Acknowledge no-op]
    P2 -->|Proceed| Y[All findings -> tracker]
    P3 -->|Proceed| X

    X --> S{Any fixes<br/>landed?}
    Y --> E
    S -->|Yes| F[Step 5 final-next-steps]
    S -->|No| E

Loading

Routing

The current Review and approve specific gated fixes / Leave as residual work / Report only question is gone. In its place:

• (A) Review each finding one by one — accept the recommendation or choose another action
• (B) LFG. Apply the agent's best-judgment action per finding
• (C) File a [TRACKER] ticket per finding without applying fixes
• (D) Report only — take no further action

Distinguishing words (Review / LFG / File / Report) front-load so labels survive truncation in harnesses that hide option descriptions. The stem is third-person agent voice per plugins/compound-engineering/AGENTS.md:127. When tracker detection is low-confidence or the sink is unavailable, the tracker name falls back to generic wording or option C is omitted entirely with a one-line explanation.

Per-finding walk-through

Each finding renders in two surfaces: a terminal markdown block carries the explanation (heading, What's wrong, Proposed fix, Why it works); a compact two-line question stem carries the decision. The stem opens with Finding N of M — {severity} {short handle}. and frames the single recommended action as a yes/no question (Apply the format-validation guard?, Skip the fix since the fixture is being deleted?). The stem never enumerates alternatives — the option list carries those.

The four per-finding options are Apply / Defer / Skip / LFG the rest. Advisory-only findings substitute Acknowledge — mark as reviewed. N=1 suppresses LFG the rest. No-sink platforms omit Defer. The post-tie-break recommendation from Stage 5 step 7b is marked (recommended) on whichever option carries it — any of the four can be recommended, and option order is fixed so the marker alone carries the signal (no reordering to hoist the recommendation to position 1).

Proposed fix renders as intent-language prose, not quoted code. Examples: Throw on non-2xx response before parsing JSON., Replace `==` with `===` on line 42., Extract the request-building logic into a helper and call it from both sites. A code-span budget of 2 inline backtick spans per sentence caps complexity — each span a single identifier or operator, never a full statement or nested template literal. Raw code blocks are reserved for short (≤5 line) genuinely additive new code where no before-state exists. Diff blocks are banned — diffs are PR-review tooling that don't fit a decision surface.

Between findings, a one-line confirmation of the action taken (→ Applied. Fix staged at src/utils/api-client.ts:36-37., → Deferred. Ticket filed: <url>.) gives the user continuous feedback. Walk-through state is in-memory only; Apply decisions accumulate and dispatch once at end-of-loop through the existing one-fixer-consistent-tree mechanic.

Bulk preview

Before any bulk action (routing option B, option C, or walk-through LFG the rest) executes, a compact plan preview shows findings grouped by intended action — Applying (N):, Filing [TRACKER] tickets (N):, Skipping (N):, Acknowledging (N): — with one line of compressed framing per finding. Exactly two responses: Proceed or Cancel. Cancel from the walk-through's LFG the rest returns the user to the current finding, not to the routing question.

Recommended-action tie-breaking

Stage 5 gains a new sub-step 7b. When contributing reviewers imply different per-finding actions for the same merged finding, synthesis picks the most conservative using Skip > Defer > Apply > Acknowledge. Identical review artifacts now produce the same recommendation deterministically — LFG runs are reproducible and the walk-through's recommendation is stable across re-runs.

Framing quality in reviewer output

Sampling 15+ recent review artifacts surfaced two failure modes: adversarial-reviewer and api-contract-reviewer emitting why_it_matters: null (schema violation), and correctness-reviewer / maintainability-reviewer leading with code-structure-first prose (orders_controller.rb:42 has a missing authorization check) instead of observable behavior. The shared subagent template now includes a framing-guidance block — one file change applied universally to every persona via the existing dispatch path. Observable-behavior-first, why-the-fix-works grounding, 2-4 sentence budget, required-field reminder, and a positive/negative example pair. No synthesis-time rewrite pass, no per-persona file edits.

Tracker detection and defer

Detection is reasoning-based: the agent reads CLAUDE.md / AGENTS.md and whatever other documentation is obvious, then forms a { tracker_name, confidence, sink_available } tuple. Availability probes (gh auth status, MCP-tracker reachability) run at most once per session, only when the routing question is about to be asked. The fallback chain prefers durable external trackers: named tracker → GitHub Issues via gh → harness task primitive (TaskCreate / update_plan) with an explicit once-per-session durability confirmation. The internal .context/compound-engineering/todos/ system is never part of this fallback chain.

Platform question-tool loading (Claude Code)

In Claude Code, AskUserQuestion is a deferred tool — its schema is not available at session start. A new ### Interactive mode rules section at the top of SKILL.md directs the agent to load it via ToolSearch with query select:AskUserQuestion once at the start of the Interactive flow, not lazily at each invocation site. The numbered-list text fallback applies only when ToolSearch explicitly returns no match or the tool call errors — never as a path the agent takes because it skipped the load. On Codex (request_user_input) and Gemini (ask_user) this step is not required; the tools are loaded by default.

Step 5 conditioning

The existing push / PR / exit final-next-steps flow now runs only when at least one fix landed in the working tree. Skipped for routing options C and D, for LFG runs where every recommendation was Defer/Skip/Acknowledge, and for walk-throughs that completed with zero Apply decisions. Asking a user "push fixes?" after they deliberately picked Report only was incoherent.

Cohort color alignment

agent-native-reviewer frontmatter color moves from cyan (one-off) to blue, matching the structured-findings JSON reviewer cohort it shares a role with. Blue for structured JSON reviewers; red for adversarial-reviewer; yellow for the distinct-lens set (previous-comments-reviewer, cli-agent-readiness-reviewer).

Scope boundaries

• No new ce:fix skill. The redesign lives inside ce:review.
• No changes to the findings schema, merge/dedup routing beyond R15, or autofix-mode residual-todo creation.
• No inline freeform fix authoring. The walk-through is a decision loop; "approve the intent but write a variant" is explicitly unsupported in v1 — users Skip and hand-edit.
• Other modes (Autofix, Report-only, Headless) unchanged. Contract test asserts this continues to hold.
• Internal .context/compound-engineering/todos/ phase-out is acknowledged as the long-term direction but out of scope for this PR.

Design decisions worth calling out

• Shared subagent-template upgrade over persona upgrades or synthesis rewrite. Sampling evidence shaped this choice. Per-persona edits would inflate scope to 5+ files; a synthesis-time rewrite pass would add recurring per-review model cost and paper over the adversarial/api-contract schema violation rather than fix it. One file edit at the source fixes both gaps for every reviewer.
• Split per-finding surface: terminal block for explanation, compact stem for decision. Packing the full attack scenario + proposed fix + reasoning into the AskUserQuestion stem produced a wall of text that couldn't render markdown. Splitting lets each surface do its job: terminal block uses markdown hierarchy; stem uses plain-text yes/no framing on a single recommendation.
• Intent-over-syntax for Proposed fix. Showing code (raw or diffed) forces syntax-parsing during a decision loop. The walk-through's job is trust-the-action, not review-the-code; the fixer subagent owns syntax. Prose intent description with a 2-span code budget avoids nested-backtick rendering bugs observed in live testing, where the terminal's markdown renderer ate delimiters and ran adjacent words together.
• (recommended) marker mandatory over optional. Previous wording said "may label (recommended)" and let the agent communicate the recommendation through option ordering instead. Stabilizing the order and making the marker required decouples recommendation signal from position — users don't have to re-orient when Skip is recommended instead of Apply.
• Apply actions batch at end of walk-through, not per-finding. Preserves the existing "one fixer, consistent tree" guarantee. The fixer receives the full Apply set at once and can handle inter-fix dependencies (two Applies touching overlapping regions) in one pass. Trade-off: fix failures surface at the end of the walk-through rather than per-decision.
• Walk-through state is in-memory only. No per-decision disk writes. An interrupted walk-through discards in-flight state; Defer actions that already executed remain in the tracker (external side effects). Avoids the complexity of state-file schema, external-edit staleness detection, and .context/ lifecycle management for a feature (inspectable partial state) with no consumer.
• Hoisted pre-load directive over inline reminders for AskUserQuestion. Inline "load via ToolSearch" instructions at each invocation point proved unreliable in long-skill attention-decay conditions — the agent would emit the question as narrative text instead of firing the tool. A single directive in a new Interactive mode rules section (symmetric with the existing autofix / report-only / headless rules), plus a local checklist bullet before the routing question, and a gated fallback requiring confirmed ToolSearch failure, reliably fires the tool.
• Walk-through, bulk preview, and tracker defer live in references/ files. SKILL.md was already 744 lines; inlining would add ~200 lines paid on every invocation. Per plugins/compound-engineering/AGENTS.md:109-114 rationale discipline.
• Contract test uses structural assertions, not exact prose. Landmark tokens (file paths, required distinguishing words, mode-branch isolation) so wording improvements in future PRs do not break the test — regression guard, not authoring ossification.

Testing

• bun test tests/review-skill-contract.test.ts — 10/10 pass. The documents policy-driven routing and residual handoff test was rewritten to cover the new structure: four-option distinguishing words (regex), third-person stem assertion, reference-file existence, subagent-template framing-guidance presence, Stage 5 tie-breaking order, internal-todos-forbidden assertion in tracker-defer.md, Step 5 fixes-applied gating, walk-through option labels, bulk-preview Proceed / Cancel contract. Structural assertions only; exact prose is not locked.
• bun test full suite — 752 pass, 1 fail. The failing test is resolve-base.sh > prefers the PR base remote from gh metadata over origin, which fails on main too (pre-existing, environment-dependent, unrelated to this work).
• bun run release:validate — in sync.
• Live validation on a controlled diff (src/utils/api-client.ts seeded with 7 deliberate issues across severity and autofix-class tiers) surfaced the split-surface, intent-over-syntax, mandatory-recommended-marker, and hoisted-pre-load refinements that shipped as presentation-layer follow-ups. Scenario A (walk-through with mixed Apply/Defer/Skip decisions) now fires the question tool correctly and renders each finding's explanation in readable markdown.

Review

• Brainstorm: docs/brainstorms/2026-04-17-ce-review-interactive-judgment-requirements.md — 28 requirements, refined via document-review (6 personas, 38 findings addressed).
• Plan: docs/plans/2026-04-17-002-feat-ce-review-interactive-judgment-plan.md — 8 units with requirements trace, refined via document-review (6 personas, 54 findings addressed), status now completed.
• Post-implementation self-review completed via ce:review mode:autofix equivalent. Zero P0–P2 findings. One safe_auto contract-test assertion-coverage fix applied mid-review. Run artifact at .context/compound-engineering/ce-review/20260417-215343-cde5b0e8/.
• End-to-end pipeline learnings captured at docs/solutions/developer-experience/ce-pipeline-end-to-end-learnings-2026-04-17.md (300 lines) — the full brainstorm → plan → work → review → PR flow on this PR itself, including the research-subagent pipeline separation pattern that came out of it.

Post-deploy monitoring and validation

No additional operational monitoring required. This is a plugin skill change — no runtime infrastructure, no user data, no external API contracts. Users who invoke Interactive mode after this lands will see the new four-option routing question on their next review with gated_auto or manual findings. If UX feedback surfaces issues (wrong tracker inferred, unclear option wording, walk-through friction), iterate via prose edits in follow-up PRs.

---

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e5947b8a8a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 244bc3fd86

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 81de392dc2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 57efb95538

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f620e1372e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bb1c268ca6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 45a5424b7f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[tmchow]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d06d022527

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".