wheels-dev
diff --git a/‎.ai/wheels/wheels-bot.md‎
Lines changed: 11 additions & 7 deletions b/‎.ai/wheels/wheels-bot.md‎
Lines changed: 11 additions & 7 deletions
diff --git a/‎.claude/commands/_shared-rails.md‎
Lines changed: 1 addition & 2 deletions b/‎.claude/commands/_shared-rails.md‎
Lines changed: 1 addition & 2 deletions
diff --git a/‎.claude/commands/address-review.md‎
Lines changed: 65 additions & 55 deletions b/‎.claude/commands/address-review.md‎
Lines changed: 65 additions & 55 deletions
diff --git a/‎.claude/commands/advise-on-deadlock.md‎
Lines changed: 15 additions & 11 deletions b/‎.claude/commands/advise-on-deadlock.md‎
Lines changed: 15 additions & 11 deletions
diff --git a/‎.claude/commands/propose-fix.md‎
Lines changed: 1 addition & 1 deletion b/‎.claude/commands/propose-fix.md‎
Lines changed: 1 addition & 1 deletion
@@ -1,24 +1,28 @@
 # Wheels Bot
 
-`wheels-bot[bot]` is a custom GitHub App that runs Claude-powered automation on issues and PRs in `wheels-dev/wheels`. Five stages, all opt-out via the `[skip-claude]` label or repo variable `WHEELS_BOT_ENABLED=false`. Slash-command prompts live in `.claude/commands/`; workflows in `.github/workflows/bot-*.yml`. Full user-facing docs: [`docs/contributing/wheels-bot.md`](../../docs/contributing/wheels-bot.md).
+`wheels-bot[bot]` is a custom GitHub App that runs Claude-powered automation on issues and PRs in `wheels-dev/wheels`. All stages are opt-out via the `[skip-claude]` label or repo variable `WHEELS_BOT_ENABLED=false`. Slash-command prompts live in `.claude/commands/`; workflows in `.github/workflows/bot-*.yml`. Full user-facing docs: [`docs/contributing/wheels-bot.md`](../../docs/contributing/wheels-bot.md).
 
 ## Stages
 
 | Stage | Trigger | Model | Output |
 |---|---|---|---|
 | Triage | issue opened/reopened | Opus | Comment classifying as `bug` / `framework-design` / `other` (+ confidence on `bug` path). Reads code with the allowlisted tools to resolve uncertainty before rating. |
 | Research | bot triage emits `framework-design` marker | Opus | Comment comparing Rails / Laravel / Django / Phoenix / Spring Boot / +1 and recommending a Wheels-idiomatic path (+ confidence). |
-| Propose Fix | bot triage emits `triage-confidence:high\|medium` OR research emits `research-confidence:high\|medium` (or `workflow_dispatch`) | Opus | TDD-mandatory draft PR on branch `fix/bot-<issue>-<slug>`. Spec-then-implementation, both required by `bot-tdd-gate.yml`. |
-| Reviewer A | PR opened / synchronized / ready_for_review | Sonnet | Single PR review with line comments, verdict, and `wheels-bot:review-a:<pr>:<sha>` marker. |
-| Reviewer B | Reviewer A submits a review | Sonnet | PR comment critiquing A for sycophancy, false positives, and missed issues. Loop cap = 3 rounds. |
+| Propose Fix | bot triage emits `triage-confidence:high\|medium` OR research emits `research-confidence:high\|medium` (or `workflow_dispatch`). A pre-gate skips the run when a `peter/issue-<N>-*` branch or an open non-bot PR already targets the issue (campaign guard). | Opus | TDD-mandatory draft PR on branch `fix/bot-<issue>-<slug>`. Spec-then-implementation, both required by `bot-tdd-gate.yml`. |
+| Reviewer | PR opened / synchronized / ready_for_review (`bot-review.yml`; fork PRs via maintainer-labeled `bot-review-fork.yml`) | Fable | Single PR review with line comments, verdict, and `wheels-bot:review-a:<pr>:<sha>` marker (legacy marker name retained). The prompt includes a self-adversarial pass — refute each finding against the actual code before posting — replacing the retired Reviewer B critique loop. |
+| Address Review | **opt-in**: maintainer applies the `bot-address-review` label or dispatches `bot-address-review.yml` | Opus | Applies the most recent wheels-bot review's findings on the current head SHA, pushes to the PR branch, comments with `wheels-bot:address-review:<pr>:<sha>:<round>`. |
+
+**Model policy:** judging gate = fable, coding stages = opus, janitorial = sonnet (auto-close, write-docs, update-docs stay on Sonnet).
+
+**Retired (2026-06-11):** the Reviewer A / Reviewer B convergence loop (`bot-review-b.yml`, `/review-the-review`, `/respond-to-critique`) and the `converged-*` auto-fire chain into address-review. The loop was expensive and flaky, B's marginal catch rate no longer justified a second model pass, and the auto-fire push chain landed a broken spec on a PR (#3005). `bot-advisor.yml` (the loop's deadlock-breaker) is retained but inert — its trigger marker is no longer produced.
 
 ## Marker conventions (HTML comments, used for idempotency)
 
 - `<!-- wheels-bot:triage:<issue> -->` + `<!-- wheels-bot:triage-class:<bug|framework-design|other> -->` (+ optional `<!-- wheels-bot:triage-confidence:high|medium -->` — either fires propose-fix; low omitted)
 - `<!-- wheels-bot:research:<issue> -->` (+ optional `<!-- wheels-bot:research-confidence:high|medium -->` — either fires propose-fix; low omitted)
 - `<!-- wheels-bot:fix:<issue> -->` / `<!-- wheels-bot:fix-held:<issue> -->`
-- `<!-- wheels-bot:review-a:<pr>:<sha> -->`
-- `<!-- wheels-bot:review-b:<pr>:<sha>:<round> -->`
+- `<!-- wheels-bot:review-a:<pr>:<sha> -->` — the Reviewer's review marker (legacy name kept for continuity across the single-reviewer consolidation)
+- `<!-- wheels-bot:address-review:<pr>:<sha>:<round> -->` / `<!-- wheels-bot:address-held:<pr>:<sha> -->`
 - `<!-- wheels-bot:auto-close:<issue> -->`
 
 ## Allow-listed scopes per stage
@@ -31,7 +35,7 @@ Flip the repo variable `WHEELS_BOT_ENABLED` to `false` to halt every bot workflo
 
 ## Auto-fire safety net
 
-The bot is permitted to chain stages (triage → research → propose-fix), and handoff fires on `*-confidence:high` OR `*-confidence:medium`. Low stays manual. Sensitive areas (security, middleware, migrations, deploy, DI, cross-engine) are caught by the propose-fix prompt's own step-4 safety net, which posts a `fix-held` marker instead of opening a PR. Reviewer A and B then critique whatever propose-fix produces, escalating to the Senior Advisor on deadlock. All bot PRs land as `--draft` and require a human approving review on `develop`.
+The bot is permitted to chain stages (triage → research → propose-fix), and handoff fires on `*-confidence:high` OR `*-confidence:medium`. Low stays manual. Sensitive areas (security, middleware, migrations, deploy, DI, cross-engine) are caught by the propose-fix prompt's own step-4 safety net, which posts a `fix-held` marker instead of opening a PR. The Reviewer then reviews whatever propose-fix produces. Address-review never auto-fires — a human opts the PR in via the `bot-address-review` label. All bot PRs land as `--draft` and require a human approving review on `develop`.
 
 ## PR-prep automation (release unblocking)
 
 
@@ -78,8 +78,7 @@ existing comments for the marker that matches your stage and key. If found,
 ## Output format
 
 - Start every comment / review with a clear H2 header naming the stage:
-  `## Wheels Bot — Triage`, `## Wheels Bot — Reviewer A`,
-  `## Wheels Bot — Reviewer B (round N)`,
+  `## Wheels Bot — Triage`, `## Wheels Bot — Reviewer`,
   `## Wheels Bot — Cross-Framework Research`.
 - End with the appropriate marker on its own line.
 - No emoji unless the team's existing style uses them (CFML repo norms — minimal).
 
@@ -1,10 +1,11 @@
 # /address-review
 
-Implementer for the convergence loop. After Reviewer A and Reviewer B
-have aligned on a "changes needed" verdict for a PR, read the consensus
-and apply the changes. Push commits to the PR's existing branch — new
-commits trigger a fresh Reviewer A on the new SHA, restarting the
-convergence loop until reviewers converge on `approve`.
+Implementer for reviewer findings. This is an **opt-in** stage: a human
+either applied the `bot-address-review` label to the PR or dispatched the
+workflow manually. Read the most recent wheels-bot review on the PR's
+current head SHA, apply the actionable findings, and push commits to the
+PR's existing branch. The new commit triggers a fresh Reviewer run on the
+new SHA; the human decides whether to opt in again.
 
 This is a *coding* stage like propose-fix — Opus, broad allowlist with
 the test runner. Mirrors propose-fix's safety patterns.
@@ -24,13 +25,14 @@ Read `.claude/commands/_shared-rails.md` first. Highlights:
 
 ## Args
 
-- `<pr-number>` — the PR with converged-changes markers to address
+- `<pr-number>` — the PR whose reviewer findings to address
 - `<head-sha>` — the PR head SHA at the start of this run, captured once by
   the workflow and passed here. Use it verbatim as the marker SHA — it is the
   `<sha>` / `<sha-before>` every marker below writes (the head *before* your
-  own commit). Don't compute the SHA yourself — re-deriving it mid-session is
-  the #2848 race. This governs only the marker SHA; you still use `gh pr view`
-  normally to read comments, the consensus, and the head ref name.
+  own commit), AND the SHA whose wheels-bot review you consume. Don't compute
+  the SHA yourself — re-deriving it mid-session is the #2848 race. This
+  governs only the marker SHA; you still use `gh pr view` normally to read
+  reviews, comments, and the head ref name.
 
 ## Steps
 
@@ -47,40 +49,45 @@ Read `.claude/commands/_shared-rails.md` first. Highlights:
      ```
      ## Wheels Bot — Address Review (max iterations reached)
 
-     Five address-review rounds have run on this PR without the
-     reviewers converging on `approve`. Handing back to humans —
-     either the PR's scope is larger than the bot can resolve, or
-     the reviewers are deadlocked on a design call.
+     Five address-review rounds have run on this PR. Handing back to
+     humans — the PR's scope is larger than the bot can resolve
+     iteratively. Remove and re-apply the `bot-address-review` label
+     only after a human has reshaped the PR.
 
      <!-- wheels-bot:address-review:<pr>:<head-sha>:terminal -->
      ```
 
      and exit.
    - Otherwise: round number = (count of address-review comments) + 1.
 
-2. **Read the consensus.**
-   - Reviewer A's initial review (`wheels-bot:review-a:<pr>:<sha>:`)
-   - All Reviewer A response reviews (`wheels-bot:review-a-response:`)
-   - All Reviewer B comments
-     (`wheels-bot:review-b:<pr>:<sha>:<round>`) — chronological order
-   - The latest B comment carrying
-     `wheels-bot:converged-changes:<pr>:<sha>` is the trigger; its
-     body summarizes the alignment.
-
-   The **consensus changes** = the union of:
-   - A's findings B did **not** mark as false positives
-   - B's missed-issues findings A did **not** successfully refute in
-     a response
-   - Findings both A and B explicitly agreed on in any round
+2. **Read the reviewer's findings.** Fetch the PR's reviews via
+   `gh pr view <pr-number> --json reviews`. Find the **most recent**
+   `wheels-bot[bot]` review whose `.commit.oid` equals `<head-sha>` (note:
+   `gh pr view` exposes `commit.oid` — `commit_id` is the REST shape from
+   `gh api`, and matching on it silently finds nothing) and whose state is
+   `CHANGES_REQUESTED`, or `COMMENTED` with concrete findings in the body.
+   That review's findings are your work list.
+
+   - If no wheels-bot review exists on `<head-sha>`, exit silently with a
+     brief log line — there is nothing to address at this SHA (the label
+     was applied before the Reviewer ran, or only a stale-SHA review
+     exists; a fresh Reviewer run will produce one).
+   - If the review on `<head-sha>` is `APPROVED`, exit silently — there
+     are no changes to make.
+
+   The **actionable findings** = the review's findings that:
+   - cite a concrete file/line (or are otherwise precisely actionable), and
+   - assert a correctness, convention, cross-engine, test, docs-metadata,
+     commit, or security problem (the sections of the review body).
 
    Skip (do not act on):
-   - A's findings B successfully refuted as false positives
-   - Findings A and B disagreed on across rounds (the
-     converged-changes verdict means there's enough alignment on the
-     above to act; isolated disputes are left for the next loop)
+   - purely stylistic preferences with no cited convention,
+   - findings you cannot verify against the actual code after reading the
+     cited lines (note them as skipped in your comment instead),
+   - findings explicitly framed as optional/nit by the reviewer.
 
 3. **Auto-downgrade safety net.** Before writing anything, if any
-   consensus finding would touch:
+   actionable finding would touch:
    - `vendor/wheels/security/**`, auth flows, password / token code
    - `vendor/wheels/middleware/**` auth-related middleware
    - Migration files under
@@ -93,10 +100,9 @@ Read `.claude/commands/_shared-rails.md` first. Highlights:
    ```
    ## Wheels Bot — Address Review held for human review
 
-   The consensus findings touch a sensitive area (`<area>`) and the
+   The reviewer's findings touch a sensitive area (`<area>`) and the
    bot's safety net requires a human in the loop before any code
-   change. The PR's reviewer-feedback exchange is preserved above
-   for context.
+   change. The review is preserved above for context.
 
    <!-- wheels-bot:address-held:<pr>:<head-sha> -->
    ```
@@ -105,26 +111,31 @@ Read `.claude/commands/_shared-rails.md` first. Highlights:
 
 4. **Branch-aware scope check.** Read the PR's head ref via
    `gh pr view <pr-number> --json headRefName -q '.headRefName'`:
-   - `fix/bot-*` → may modify code, tests, changelog fragments
-     (`changelog.d/<slug>.<type>.md` — never `CHANGELOG.md` directly)
-   - `docs/bot-*` → doc paths only. If a consensus finding requires
-     touching code, post `address-held` and exit (the PR's scope is
-     wrong for that finding).
-
-5. **Apply the consensus changes.** For each consensus finding:
+   - `docs/bot-*` (or any `docs/*` branch) → doc paths only. If a finding
+     requires touching code, post `address-held` and exit (the PR's scope
+     is wrong for that finding).
+   - any other branch (`fix/bot-*`, human branches — the label is
+     maintainer-applied, so human PRs may opt in too) → may modify code,
+     tests, changelog fragments (`changelog.d/<slug>.<type>.md` — never
+     `CHANGELOG.md` directly).
+
+5. **Apply the findings.** For each actionable finding:
    - Read the cited file
    - Make the smallest change that addresses the finding
-   - For `fix/bot-*` PRs: after the changes, re-run any affected spec
-     via `bash tools/test-local.sh <layer>` to confirm nothing
-     regressed. Capture the output.
+   - When a finding asserts a behavioral bug with no covering spec, extend
+     or add a spec alongside the fix (TDD discipline: see the failing
+     assertion before the fix where practical)
+   - After the changes, re-run any affected spec via
+     `bash tools/test-local.sh <layer>` to confirm nothing regressed.
+     Capture the output. (Doc-only changes skip the test run.)
 
 6. **Stage and commit.** Single conventional commit on the existing
    branch. Don't open a new branch — push back to the same branch
    the PR is on.
 
-   - Type: `fix` (for `fix/bot-*` PRs) or `docs` (for `docs/bot-*` PRs)
+   - Type: `fix` (code changes) or `docs` (doc-only changes)
    - Subject (≤ 100 chars):
-     `address Reviewer A/B consensus findings (round <N>)`
+     `address reviewer findings (round <N>)`
    - Body: bullet list of what was addressed, with file references.
 
    ```bash
@@ -142,25 +153,24 @@ Read `.claude/commands/_shared-rails.md` first. Highlights:
    ```
    ## Wheels Bot — Address Review (round <N>)
 
-   Applied consensus findings from Reviewer A and Reviewer B's
-   convergence (round <round-of-convergence-loop>):
+   Applied the Reviewer's findings from its review of <head-sha>:
 
    <bulleted list — what was addressed, file:line references>
 
-   <if any findings were intentionally skipped because they weren't in
-   the consensus, list them with "skipped: <reason>">
+   <if any findings were intentionally skipped — unverifiable, stylistic,
+   or explicitly optional — list them with "skipped: <reason>">
 
-   The new commit will trigger a fresh Reviewer A run on the updated
-   SHA. Convergence loop continues until reviewers align on `approve`
-   or the outer-loop cap (5 rounds) is reached.
+   The new commit will trigger a fresh Reviewer run on the updated
+   SHA. This stage is opt-in: re-apply the `bot-address-review` label
+   (or dispatch the workflow) to address that review too.
 
    <!-- wheels-bot:address-review:<pr>:<head-sha>:<N> -->
    ```
 
 8. **Self-check before posting.**
    - [ ] Branch-aware scope check passed — no files modified outside
      allowed paths
-   - [ ] For `fix/bot-*`: tests re-run, output cited in the comment
+   - [ ] For code changes: tests re-run, output cited in the comment
    - [ ] Commit message is conventional, subject ≤ 100 chars
    - [ ] PR comment includes the marker built from the `<head-sha>`
      argument (the head SHA at the start of this run, before your
 
@@ -1,19 +1,22 @@
 # /advise-on-deadlock
 
-Senior advisor for the wheels-bot review chain. Fires only when
-Reviewer A and Reviewer B fail to converge on a recommendation after
-the inner loop's 10-round cap (B emits a `:terminal` marker). Read
+> **LEGACY.** The Reviewer A / Reviewer B convergence loop this command
+> arbitrated was retired per maintainer decision 2026-06-11 (single-pass
+> Reviewer; see `bot-review.yml` and `/review-pr`). No pipeline stage emits
+> the `:terminal` trigger marker anymore, and the `converged-*` markers this
+> command produces no longer auto-fire `bot-address-review.yml` (that stage
+> is opt-in via the `bot-address-review` label). This command is retained
+> only for manual reruns against historical PRs that already carry a
+> terminal marker; step 2's deadlock check makes it exit silently
+> everywhere else.
+
+Senior advisor for the retired wheels-bot review loop. Fired only when
+Reviewer A and Reviewer B failed to converge on a recommendation after
+the inner loop's 10-round cap (B emitted a `:terminal` marker). Read
 the full exchange, identify the specific disputed points, and issue a
 tie-breaking verdict using deeper reasoning than the analytical
 reviewers brought.
 
-This is the only stage in the pipeline that runs **Opus on a
-non-coding task**. The reasoning depth is justified because the
-advisor's verdict overrides the analytical reviewers' deadlock and
-drops back into the existing convergence flow — the advisor either
-ends the loop (`converged-approve`) or triggers `bot-address-review.yml`
-(`converged-changes`).
-
 ## Rails
 
 Read `.claude/commands/_shared-rails.md` first. Highlights:
@@ -155,7 +158,8 @@ Read `.claude/commands/_shared-rails.md` first. Highlights:
    - `<!-- wheels-bot:converged-approve:<pr>:<head-sha> -->` if verdict is
      `approve`
    - `<!-- wheels-bot:converged-changes:<pr>:<head-sha> -->` if verdict is
-     `changes` (triggers `bot-address-review.yml`)
+     `changes` (no longer auto-fires anything — a human opts the PR into
+     `bot-address-review.yml` via the `bot-address-review` label)
 
 10. **Self-check before posting.**
     - [ ] Each ruling cites a concrete file:line, doc path, or both —
 
@@ -199,7 +199,7 @@ is enforced by code, so don't skip steps.
     Spec: `<path/to/spec.cfc>` — failing → passing
     Implementation: `<path(s)>`
 
-    A human review is required before merge. Reviewer A and Reviewer B
+    A human review is required before merge. The Reviewer
     will weigh in shortly. Doc updates (MDX guides, `.ai/wheels/`,
     `CLAUDE.md`) are handled separately by `bot-update-docs.yml`.