ci: add convergence loop with address-review + senior-advisor stages (#2540)

Closes the gap between analytical reviewers (A and B) and actual code
change. Before this PR, A's review and B's critique produced
analytical context for the human to act on — but the human had to
translate that context into code edits manually. The loop was open.

Three architectural additions close it:

## 1. Reviewer A↔B convergence loop

Reviewer A and Reviewer B now back-and-forth until they align on a
recommendation:

- bot-review-a.yml gains a second trigger (issue_comment) and a new
  /respond-to-critique prompt for response mode. The response is a
  review (state=COMMENT), which triggers B's next round.
- review-the-review.md (B's prompt) gains the convergence verdict
  per round:
  - converged-approve — aligned on no changes needed
  - converged-changes — aligned on changes needed (triggers Stage 8)
  - (no marker) — not aligned, A responds in next round
- Inner loop cap: 10 rounds per SHA (was 3 for B). Bun-published
  demos show A↔B going to 100 rounds; 10 is conservative and
  respects "alignment is the goal."

## 2. Stage 8: Address Review (Opus, code-modifying)

New workflow bot-address-review.yml + new prompt /address-review.

Fires on wheels-bot:converged-changes:<pr>:<sha> markers. Reads the
consensus, applies changes to the PR's existing branch, pushes new
commits. The new SHA triggers fresh Reviewer A → loop restarts.

Coding stage: Opus model, broad allowlist with test runner, mirrors
propose-fix's setup. Branch-aware scope: fix/bot-* allows code+tests,
docs/bot-* allows doc paths only.

Outer-loop cap: 5 implementations per PR. Combined with B's 10-round
inner cap, max bot effort is bounded at 5 × 10 = 50 review rounds
before human intervention.

## 3. Stage 9: Senior Advisor (Opus, deadlock resolver)

New workflow bot-advisor.yml + new prompt /advise-on-deadlock.

Fires on B's :terminal marker (cap reached without convergence).
Reads the full A↔B exchange, the disputed code, and canonical
references; rules on each disputed point with concrete evidence;
issues a tie-breaking verdict (approve or changes) that drops back
into the existing convergence flow.

This is the only stage running Opus on a non-coding task. Cost is
justified because the advisor's verdict overrides the deadlock — it
must be right.

Without the advisor, deadlocked PRs would just sit waiting for human
intervention. With it, even disagreement-prone reviews resolve
automatically. The advisor sits as a sibling to address-review:
both fire from B's output but on different markers (converged-
changes vs :terminal).

## What still doesn't change

- WHEELS_BOT_ENABLED=false kill switch — still the active-incident
  safety net
- Required approving review on develop's ruleset — still the merge
  gate
- All bot PRs remain --draft; humans mark ready when ready
- Author-identity checks on every auto-fire if: block — still
  load-bearing

## Model selection

- Reviewer A (initial + respond): Sonnet (analytical)
- Reviewer B (critique + arbitrate): Sonnet (analytical)
- Address Review: Opus (modifies code)
- Senior Advisor: Opus (adjudicates code-related disputes)

Per the user's call: all coding-adjacent stages use Opus.

## Why convergence-then-implement (not implement-on-every-critique)

The earlier sketch fired address-review on every Reviewer B comment,
applying findings A flagged but B might dispute. Wasted work at best,
regressive at worst. This design waits for genuine alignment (or the
advisor's tie-breaking verdict) before any code change.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bpamiri

.claude/commands/address-review.md

@@ -0,0 +1,159 @@
+# /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`.
+
+This is a *coding* stage like propose-fix — Opus, broad allowlist with
+the test runner. Mirrors propose-fix's safety patterns.
+
+## Rails
+
+Read `.claude/commands/_shared-rails.md` first. Highlights:
+
+- Use `gh` for GitHub state, full `git` for **the PR's existing branch
+  only** (the workflow has checked you out on it).
+- Run tests via `bash tools/test-local.sh` for `fix/bot-*` PRs after
+  changes.
+- For `docs/bot-*` PRs, restrict edits to doc paths only —
+  `web/sites/guides/`, `.ai/wheels/`, `CLAUDE.md`, `CHANGELOG.md`.
+- Output is **commits to the PR branch** plus **one comment on the
+  PR** summarizing what you addressed.
+
+## Args
+
+- `<pr-number>` — the PR with converged-changes markers to address
+
+## Steps
+
+1. **Idempotency + outer-loop cap.** Read PR comments via
+   `gh pr view <pr-number> --json comments,headRefOid,headRefName`.
+   - If any comment contains
+     `wheels-bot:address-review:<pr>:<sha>:` for the current head
+     SHA, exit silently — already addressed at this SHA.
+   - Count comments matching `wheels-bot:address-review:<pr>:` for
+     ANY SHA on this PR. If count ≥ 5, post:
+
+     ```
+     ## 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.
+
+     <!-- wheels-bot:address-review:<pr>:<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
+
+   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)
+
+3. **Auto-downgrade safety net.** Before writing anything, if any
+   consensus finding would touch:
+   - `vendor/wheels/security/**`, auth flows, password / token code
+   - `vendor/wheels/middleware/**` auth-related middleware
+   - Migration files under
+     `vendor/wheels/migrator/**` or `app/migrator/migrations/**`
+   - `cli/lucli/services/deploy/**` or anything under `wheels deploy`
+   - `vendor/wheels/di/**` or DI container internals
+
+   **Stop**. Post:
+
+   ```
+   ## Wheels Bot — Address Review held for human review
+
+   The consensus 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.
+
+   <!-- wheels-bot:address-held:<pr>:<sha> -->
+   ```
+
+   and exit.
+
+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
+   - `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:
+   - 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.
+
+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)
+   - Subject (≤ 100 chars):
+     `address Reviewer A/B consensus findings (round <N>)`
+   - Body: bullet list of what was addressed, with file references.
+
+   ```bash
+   git add <files>
+   git commit -m "<message>"
+   ```
+
+   The workflow's "Push branch" step pushes after this prompt
+   completes.
+
+7. **Post the address-review comment** on the PR:
+
+   ```
+   ## Wheels Bot — Address Review (round <N>)
+
+   Applied consensus findings from Reviewer A and Reviewer B's
+   convergence (round <round-of-convergence-loop>):
+
+   <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>">
+
+   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.
+
+   <!-- wheels-bot:address-review:<pr>:<sha-before>:<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
+   - [ ] Commit message is conventional, subject ≤ 100 chars
+   - [ ] PR comment includes the marker with the correct
+     `<sha-before>` (the head SHA at the start of this run, not after
+     your commit)
+   - [ ] Outer-loop count is correctly reflected in the round number
+
+   If any check fails, do not post; investigate and exit non-zero.

.claude/commands/advise-on-deadlock.md

@@ -0,0 +1,161 @@
+# /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
+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:
+
+- Use `gh` for GitHub state and **read-only** `git`. No file writes,
+  no edits, no commits.
+- Output is **one PR comment** with the verdict + a convergence
+  marker. No PR reviews, no code modifications.
+- One-shot stage — fires once per terminal marker per SHA and exits.
+  No iteration.
+
+## Args
+
+- `<pr-number>` — the PR with deadlocked A↔B exchange
+
+## Steps
+
+1. **Idempotency check.** Read PR comments via
+   `gh pr view <pr-number> --json comments,headRefOid`. If any
+   comment contains `wheels-bot:advisor:<pr>:<sha>` for the current
+   head SHA, exit silently — already advised at this SHA.
+
+2. **Confirm the deadlock.** Look for a comment containing
+   `wheels-bot:review-b:<pr>:<sha>:terminal` for the current head
+   SHA. That's the trigger marker. If no terminal marker is present
+   for the current SHA, exit silently (this command shouldn't have
+   fired).
+
+3. **Read the full exchange.**
+   - The PR diff via `gh pr diff <pr-number>`.
+   - The PR title/body via `gh pr view <pr-number>` for original
+     context (and the `Fixes #<issue>` link, if any — the original
+     issue's framing matters).
+   - All `wheels-bot[bot]` PR reviews on the current SHA: A's initial
+     review and any response reviews
+     (`wheels-bot:review-a-response:`).
+   - All `wheels-bot[bot]` PR comments on the current SHA matching
+     `wheels-bot:review-b:<pr>:<sha>:` — the full B critique chain in
+     chronological order.
+
+4. **Identify the deadlock.** Make a precise list of the SPECIFIC
+   points where A and B disagreed and never resolved across rounds:
+   - Findings A flagged but B persistently called false positives
+     (and A defended).
+   - Issues B raised but A persistently refuted (and B re-raised).
+   - Verdict disagreements (A says `approve`, B says
+     `request-changes`, or vice versa).
+
+   For each disputed point, capture: A's position, B's position, and
+   why neither yielded.
+
+5. **Read the disputed code.** For each disputed point, `Read` the
+   actual file at the cited line. Don't rely solely on quoted
+   snippets in the exchange — the source of truth is the code on the
+   PR's branch (you're checked out on its head SHA).
+
+6. **Consult canonical references.** Before each ruling:
+   - `.ai/wheels/<layer>/` for the layer in dispute (model, view,
+     controller, etc.).
+   - `CLAUDE.md` § "Critical Anti-Patterns" + § "Wheels Conventions"
+     + § "Commit Message Conventions" — these are authoritative.
+   - `.ai/wheels/cross-engine-compatibility.md` if the dispute
+     touches Lucee/Adobe/BoxLang behavior.
+   - Existing precedent: `Grep`/`Glob` for similar code elsewhere in
+     the repo to see how this convention is handled when it's not
+     contested.
+
+7. **Rule on each disputed point.** For each, decide:
+   - **A was right** (cite the evidence)
+   - **B was right** (cite the evidence)
+   - **Both partially right** (synthesize the actually-correct
+     position)
+   - **Neither was right** (the dispute itself was misframed; here's
+     the real concern)
+
+   Cite a concrete reference for each ruling — file:line, doc path,
+   or both.
+
+8. **Synthesize the verdict.** Roll up the per-point rulings into one
+   final recommendation:
+
+   - **`approve`** — disputed points were minor, or A and B were
+     debating preferences rather than correctness. PR is fine to
+     merge as-is. Use this when the per-point rulings are dominated
+     by "both partially right" or "neither was right" outcomes.
+   - **`changes`** — at least one disputed point clearly required a
+     change (you ruled on a real correctness issue, anti-pattern, or
+     security concern). Specify which findings address-review should
+     act on (the ones you ruled in favor of the side requesting the
+     change) and which to drop.
+
+9. **Post the advisor comment** on the PR. Use
+   `gh pr comment <pr-number> --body "<...>"`:
+
+   ```
+   ## Wheels Bot — Senior Advisor (deadlock resolution)
+
+   Reviewer A and Reviewer B reached the 10-round inner-loop cap
+   without converging. After re-reading the full exchange and the
+   disputed code, here are the rulings on each contested point:
+
+   ### Disputed points
+
+   1. **<short title>** — A claimed `<A's position>`; B claimed
+      `<B's position>`. **Ruling:** `<A right | B right | both
+      partially | neither>`. **Evidence:** `<file:line | doc path |
+      both>`. `<one-sentence reasoning>`.
+   2. ...
+
+   ### Verdict: `<approve | changes>`
+
+   <one paragraph: synthesizing the rulings into the recommendation>
+
+   <if verdict is `changes`, list the specific findings address-review
+   should act on:>
+
+   ### Findings for address-review to apply
+   - **<finding>** at `<file:line>` — `<concrete action>`
+   - ...
+
+   <if verdict is `approve`, note that the disputed findings should be
+   dropped and the PR is fine to merge as-is.>
+
+   <!-- wheels-bot:advisor:<pr>:<sha> -->
+   <CONVERGENCE_MARKER>
+   ```
+
+   Where `<CONVERGENCE_MARKER>` is:
+   - `<!-- wheels-bot:converged-approve:<pr>:<sha> -->` if verdict is
+     `approve`
+   - `<!-- wheels-bot:converged-changes:<pr>:<sha> -->` if verdict is
+     `changes` (triggers `bot-address-review.yml`)
+
+10. **Self-check before posting.**
+    - [ ] Each ruling cites a concrete file:line, doc path, or both —
+      no vague handwaves.
+    - [ ] Read the actual disputed code (not just exchange quotes).
+    - [ ] Consulted `CLAUDE.md` and `.ai/wheels/` where applicable.
+    - [ ] Verdict is one of `approve` or `changes` — not "kinda
+      mostly", not equivocal.
+    - [ ] Convergence marker is consistent with the verdict.
+    - [ ] Advisor marker present.
+
+    If any check fails, fix before posting. The advisor's verdict is
+    authoritative within the convergence loop — get it right.