chore(coderabbit): stop incremental reviews to cut add-on spend

.agents/skills/backlog-sweep/SKILL.md

@@ -86,8 +86,10 @@ record that looks stale from outside is routinely a live holder inside a long
 browser suite.
 
 **State the usage reality before starting.** One shipped PR costs roughly 3% of
-the weekly usage window, and every push to it triggers another round of bot
-reviews whose findings then cost replies and often another push. Two issues is
+the weekly usage window, and every push to it triggers another round of Codex
+and Claude reviews whose findings then cost replies and often another push.
+CodeRabbit is no longer part of that per-push cost: it reviews the opening push
+and the closeout head only (ADR 0066). Two issues is
 the default because the cost is dominated by review rounds, not by the first
 implementation. **Refuse a batch size above 4.** Say that plainly and stop
 rather than clamping silently — an operator who asked for 6 needs to know they
@@ -543,7 +545,7 @@ changed.` Review the lifecycle and install scripts in the diff first, then
   `pnpm issue:review --pr <pr> --issue <n>`.
 - **The babysit:** sweep every feedback surface — top-level comments, review
   bodies, inline threads, annotations, failing logs. **Batch fixes into single
-  pushes**, because every push costs another bot review round. Reply before
+  pushes**, because every push costs another Codex and Claude review round. Reply before
   resolving, in the two canonical forms: `Fixed in <commit> — <what changed>`
   and `Won't fix: <technical reason why>`. Drive to READY on both projections,
   `pr:feedback-state` clean first, then `pr:ready-state`.

.claude/skills/backlog-sweep/SKILL.md

@@ -86,8 +86,10 @@ record that looks stale from outside is routinely a live holder inside a long
 browser suite.
 
 **State the usage reality before starting.** One shipped PR costs roughly 3% of
-the weekly usage window, and every push to it triggers another round of bot
-reviews whose findings then cost replies and often another push. Two issues is
+the weekly usage window, and every push to it triggers another round of Codex
+and Claude reviews whose findings then cost replies and often another push.
+CodeRabbit is no longer part of that per-push cost: it reviews the opening push
+and the closeout head only (ADR 0066). Two issues is
 the default because the cost is dominated by review rounds, not by the first
 implementation. **Refuse a batch size above 4.** Say that plainly and stop
 rather than clamping silently — an operator who asked for 6 needs to know they
@@ -543,7 +545,7 @@ changed.` Review the lifecycle and install scripts in the diff first, then
   `pnpm issue:review --pr <pr> --issue <n>`.
 - **The babysit:** sweep every feedback surface — top-level comments, review
   bodies, inline threads, annotations, failing logs. **Batch fixes into single
-  pushes**, because every push costs another bot review round. Reply before
+  pushes**, because every push costs another Codex and Claude review round. Reply before
   resolving, in the two canonical forms: `Fixed in <commit> — <what changed>`
   and `Won't fix: <technical reason why>`. Drive to READY on both projections,
   `pr:feedback-state` clean first, then `pr:ready-state`.

.coderabbit.yaml

@@ -69,8 +69,8 @@ reviews:
         Report an ordering or lifecycle finding when the trace shows a documented lifecycle invariant violation, such as a bypassed prerequisite, duplicate execution, deadlock, incorrect ownership, or missed settlement, or when focused coverage no longer reaches the changed path.
 
   # Generated, vendored, and machine-written trees. Reviewing them spends
-  # reviewed-file capacity (the Pro+ fair-usage ladder is finite; no usage-based
-  # add-on is enabled) on diffs no human authored.
+  # billable reviewed files (the usage-based add-on is enabled, so over-limit
+  # reviews bill 25¢ per reviewed file) on diffs no human authored.
   path_filters:
     - "!pnpm-lock.yaml"
     - "!**/pnpm-lock.yaml"
@@ -102,10 +102,18 @@ reviews:
     # Empty means the default branch flow only.
     base_branches: []
     drafts: false
-    auto_incremental_review: true
-    # Keep the vendor default of 5. A threshold of 2 paused 16 of the first 29
-    # PRs after rollout, including six PRs with only 2-4 total commits. Five
-    # avoids treating one normal fix round as an active-development burst while
-    # still bounding long agent commit sequences. `@coderabbitai review`
-    # requests one exact-head closeout review after a pause.
+    # Off since 2026-09-02 (ADR 0066). The usage-based add-on is enabled
+    # (Automatic mode, $500/month cap) and the cap was reached on 2026-09-02
+    # with 16 days left in the cycle. The 30-day team view read that day: 672
+    # review events, 365 billed, 3.9 review events per PR, ~5.5 billed files
+    # per billed push. CodeRabbit bills per push delta, so every agent fix
+    # round re-bills the same files. With this off, CodeRabbit reviews a PR
+    # once when it opens, and the head-bound `@coderabbitai review` request in
+    # `docs/notes/pr-ready-state.md` buys the final head one more review.
+    # Intermediate pushes lose CodeRabbit only: Codex and Claude still review
+    # them. No required gate changes, because CodeRabbit's check was already
+    # advisory; ADR 0066 records the residual this does cost.
+    auto_incremental_review: false
+    # The vendor default of 5, kept. It now only matters if incremental
+    # reviews are re-enabled; the org-level global override pins it too.
     auto_pause_after_reviewed_commits: 5

docs/adr/0066-coderabbit-replaces-bugbot-third-reviewer.md

@@ -14,7 +14,8 @@ garden_lane: adrs-architecture
 # ADR 0066 — CodeRabbit replaces Cursor BugBot as the third PR review bot
 
 **Status:** Accepted (Aug 2026) — BugBot disabled on 2026-08-31; the live
-compatibility paths retired on 2026-09-02.
+compatibility paths retired on 2026-09-02; amended 2026-09-02 (usage add-on
+enabled, incremental reviews off).
 **Scope:** ci/process
 
 ## Context
@@ -114,6 +115,10 @@ BugBot after reviewing these results.
 | Graphite Agent      | Flat $20–40/month, unlimited reviews          | $20–40                                                   |
 | Drop to two bots    | —                                             | $0, minus third-bot coverage                             |
 
+The CodeRabbit row records the 2026-08-18 estimate. The add-on was later
+enabled and its real cost overran that row — see the 2026-09-02 amendment
+below.
+
 CodeRabbit's public-repo terms were verified against the vendor's docs and
 the installed org's billing page on 2026-08-18. The Open Source tier gives
 public repos **Pro+ features free**, with no application step and no license
@@ -148,9 +153,10 @@ Replace BugBot with CodeRabbit as the third advisory reviewer.
    deferred: the operator decided on 2026-08-18 to feel the rate-limit
    friction first, at flat seat cost, and enable the add-on only if that
    friction proves annoying. Until then, over-limit reviews wait instead of
-   billing. The $0 OSS tier (Pro+ features, ~1/hour, manual-trigger-only
-   under 10 stars, no add-on) remains the documented fallback if spend must
-   return to zero.
+   billing. **Superseded 2026-09-02** — the add-on was enabled in Automatic
+   mode with a $500/month cap; see the amendment below. The $0 OSS tier (Pro+
+   features, ~1/hour, manual-trigger-only under 10 stars, no add-on) remains
+   the documented fallback if spend must return to zero.
 2. **Commit `.coderabbit.yaml`** (done 2026-08-19 in PR #1927): use the `chill`
    profile, `path_filters` that exclude lockfiles and generated trees, and
    `auto_pause_after_reviewed_commits: 5`. The initial value of 2 paused normal
@@ -159,6 +165,10 @@ Replace BugBot with CodeRabbit as the third advisory reviewer.
    normal fix round as active development. The ship and babysit closeout
    requests one manual review for an exact head when the automatic review is
    stale or missing after the optional check becomes terminal.
+   **Amended 2026-09-02** — `auto_incremental_review: false` means no
+   automatic review follows a push, so the closeout request no longer waits
+   for one; the pause threshold now only matters if incremental reviews
+   return.
 3. **Run both reviewers for two weeks** (complete 2026-08-31). Compare their
    findings on the same PRs. Use the result to confirm or reverse the decision.
 4. **Disable BugBot** (complete 2026-08-31) and **retire the compatibility
@@ -176,6 +186,103 @@ Replace BugBot with CodeRabbit as the third advisory reviewer.
    assess future review changes. Do not erase historical evidence when the
    live compatibility path retires.
 
+## Amendment 2026-09-02 — usage add-on enabled, incremental reviews off
+
+This corrects the "add-on deferred" record above. Decision step 1, the cost
+table, and the first Consequences bullet describe the state as of 2026-08-18
+and stay in place as history.
+
+- **The add-on was enabled, not deferred.** It runs in Automatic mode with a
+  $500/month cap. The enabling date was not recorded; the billing page showed
+  it active on 2026-09-02.
+- **The vendor renamed the plan tiers.** Checked 2026-09-02,
+  docs.coderabbit.ai/management/plans calls the tier this org holds **Team**
+  (formerly Pro+): $48/developer/month annual, $60 month-to-month, 8 PR
+  reviews/hour, 300 files per review. Pro is now Essentials. The rate-limit
+  notice on PR #2236 reported `Plan: Team` for that reason — the same seat
+  under a new name, not a downgrade. Sections above this amendment keep the
+  Pro+ name they were written with.
+- **The cap was reached on 2026-09-02**, sixteen days before the cycle resets
+  on 2026-09-18. Past the cap only the free refill runs — 1 review/hour for
+  the sole PR author, who sits permanently in the 90+ reviews/7-days tier —
+  and every other push is blocked.
+- **30-day Review usage, team view, read 2026-09-02:** 672 review events, 365
+  continued with credits (billed), 48 blocked, 3.9 review events per PR, ~5.5
+  billed files per continued review. CodeRabbit meters pushes, not commits or
+  files: each push past the hourly refill bills every file in that push's
+  delta at 25¢, so agent fix rounds re-bill the same files several times per
+  PR.
+- **Decision:** set `reviews.auto_review.auto_incremental_review: false` in
+  `.coderabbit.yaml`. CodeRabbit then reviews a PR once when it opens and once
+  more at closeout, when the ready-state flow posts the head-bound
+  `@coderabbitai review` request that
+  [`../notes/pr-ready-state.md`](../notes/pr-ready-state.md) already defines.
+  Intermediate pushes get no automatic CodeRabbit review; Codex and Claude
+  still review them. No required gate changes, because CodeRabbit's own check
+  was already advisory — but read the accepted residual below for what this
+  does cost. Expected: review events per PR fall from ~3.9 to ~2, each changed
+  file bills at most twice per PR, and spend lands at an estimated
+  $200–$250/month at current volume.
+- **The repository file governs this key.** The organization-level Global
+  overrides applied on 2026-09-02 pin `reviews.profile`,
+  `request_changes_workflow`, `auto_review.enabled`, `auto_review.drafts`, and
+  `auto_review.auto_pause_after_reviewed_commits`. They do not set
+  `auto_incremental_review`, so `.coderabbit.yaml` decides it and
+  `scripts/coderabbit-config.test.mjs` is its only guard. **Follow-up, now
+  indicated rather than conditional:** the operator adds
+  `auto_incremental_review: false` to the Global overrides. PR #2236 measured
+  the repository file on its own and it did not hold — see the next bullet.
+- **Measured on PR #2236, 2026-09-02: the repository file alone did not
+  suppress the attempt.** The second push (head `242f47afb`, `15:50:24Z`) drew
+  a fresh CodeRabbit run 75 seconds later — new Run ID
+  `5e05ac36-1445-4fa7-b78e-6e0e0f820745` against the opening review's
+  `3fdfc30d-2f46-4fc3-86de-2539b29fbcb6` — reporting all ten changed files and
+  a `CodeRabbit` check of "Review rate limited". The run read this branch's own
+  config (`Path: .coderabbit.yaml`, `Review profile: CHILL`), so
+  `auto_incremental_review: false` was in force and the trigger still fired. No
+  bill followed, because the spending cap blocked the review before it ran.
+  One confound stays open: the opening review never completed either, and
+  CodeRabbit may retry an unfinished review when the head moves regardless of
+  this key. Both runs covered the full base-to-head diff rather than an
+  incremental delta, and the second reused the same sticky comment, which fits
+  either explanation. A clean measurement needs a PR whose opening review
+  completed, so it waits for the 2026-09-18 cap reset.
+- **The closeout request is the vendor-documented path here, checked
+  2026-09-02.** docs.coderabbit.ai/configuration/auto-review states that
+  `auto_incremental_review: false` reviews "only when a PR is first opened.
+  Subsequent pushes will be ignored until you trigger the review manually", and
+  names `@coderabbitai review` as that manual trigger.
+  docs.coderabbit.ai/reference/review-commands lists "when automatic reviews
+  are disabled" as a use case for the same command, describes it as triggering
+  "an incremental review of new changes only", and notes it spends one review
+  from the allowance. The "applicable only when automatic reviews are paused"
+  line in PR #2236's refusal came attached to a rate-limited command, so it is
+  not evidence against the documented path. Two things stay open for the
+  2026-09-18 re-measure: the runs that fired on pushes two and three, which the
+  documentation says should have been ignored, and whether the closeout command
+  completes once the allowance permits it.
+- **Rejected here:** raising the cap keeps the per-push meter and buys more
+  duplicate reviews; tightening `path_filters` saves little because the billed
+  unit is an already-small push delta. The $0 OSS tier stays the fallback if
+  spend must return to zero.
+- **Accepted residual:** the closeout request is now the final head's only
+  chance at a CodeRabbit review, and readiness never waits for it.
+  `summarizeCodeRabbitReviewGate` returns `required: false`, `ready` is
+  `required.ready` in `scripts/pr/pr-ready-state-core.mjs`, and
+  `pr-ready-state.test.mjs` pins "never awaits a pending CodeRabbit check for
+  readiness" — so a head can reach all-clear with its CodeRabbit signal still
+  `requested`. That was already true before this change; incremental review
+  only made it unlikely to bite, because the final head usually already
+  carried an automatic review. The partial cover stays as
+  [`../notes/pr-ready-state.md`](../notes/pr-ready-state.md) states it: if the
+  requested review lands while the PR is still under watch, rerun
+  `pr:feedback-state` and handle its findings before all-clear. Making the
+  CodeRabbit signal blocking is a separate decision this ADR does not take.
+- **Revisit trigger:** closeout-only coverage missing defects that incremental
+  reviews would have caught, heads merging with the closeout review still only
+  `requested`, or spend still tracking toward the cap after the 2026-09-18
+  reset.
+
 ## Alternatives considered
 
 - **Greptile** — strongest precision on the current Martian snapshot, 0% false
@@ -218,6 +325,8 @@ Replace BugBot with CodeRabbit as the third advisory reviewer.
   ~$180/month in heavy months, with path filters shrinking the file counts.
   BugBot's per-run meter, which scaled with agent iteration, is gone from the
   default path either way, and the $0 OSS fallback caps downside.
+  **Superseded 2026-09-02**: the add-on was on, and add-on spend reached its
+  $500/month cap rather than staying under ~$180. See the amendment below.
 - The stack's third seat changes character from precision-quiet to
   high-recall. CodeRabbit's known weakness is verbosity; the quiet/chill
   profiles, path filters, and pause-after-reviewed-commits are the levers, and
@@ -231,7 +340,10 @@ Replace BugBot with CodeRabbit as the third advisory reviewer.
   the add-on. Keep `auto_pause_after_reviewed_commits` at 5 and request one
   head-bound `@coderabbitai review` at closeout when the automatic review is
   stale or missing. This spends the ladder on review rounds that matter while
-  preventing duplicate requests for the same head.
+  preventing duplicate requests for the same head. **Amended 2026-09-02**:
+  agent fix bursts now do neither — incremental auto-review is off, so they
+  get no CodeRabbit review at all and the closeout request is the second and
+  last one per PR.
   `@coderabbitai rate limit` reports remaining capacity without consuming
   a review.
 - The 2026-08-31 open-PR sweep found one current-head Cursor finding, on PR
@@ -317,6 +429,10 @@ Replace BugBot with CodeRabbit as the third advisory reviewer.
   add-on availability (paid plans only). The installed org's billing page
   confirmed the default Pro+ trial and the 2026-08-18 paid upgrade. All
   checked 2026-08-18.
+- Usage add-on state and spend: the installed org's CodeRabbit Subscription
+  and Usage pages, read 2026-09-02 — add-on Automatic with a $500/month cap,
+  cap reached that day, cycle reset 2026-09-18, and the 30-day Review usage
+  figures (672 / 365 / 48 / 3.9 / ~5.5) in the amendment above.
 - Post-rollout pause sample, queried from GitHub on 2026-08-21: 16 of the 29
   PRs created after `.coderabbit.yaml` merged carried CodeRabbit's generated
   pause marker. Six of those PRs had only 2-4 total commits. Two of the 29 PRs

docs/notes/github-tooling-surfaces.md

@@ -273,9 +273,19 @@ polled. Do not foreground-poll and never sleep-poll.
      after paging. If MCP cannot prove complete pagination, the current file
      count, or an unchanged head, fail closed and treat the skip as no current
      review signal. Generic no-file, incremental no-change, rate-limit, and
-     free-tier replies never count. After the optional CodeRabbit check becomes
-     terminal, refresh once. If the signal is missing or stale and no trusted
-     top-level comment contains both `@coderabbitai review` and
+     free-tier replies never count. Before deciding whether to wait, read
+     `reviews.auto_review.auto_incremental_review` from the PR head's
+     `.coderabbit.yaml` — CodeRabbit reads that file from the source branch, so
+     a branch predating the 2026-09-02 change still has it `true`. When it is
+     `true`, wait for the automatic attempt to become terminal as before; when
+     it is `false`, a push onto an already-open PR starts no automatic review —
+     only the opening push does — so refresh once the head is stable instead of
+     waiting. One exception to that second branch: if this PR's opening review
+     never completed, coming back as a rate-limit or cap notice rather than a
+     review, CodeRabbit may still run and possibly retry it, so wait the
+     bounded time as in the `true` branch before posting (PR #2236 observed
+     three runs across three pushes with `false` in force). If the signal is missing or stale and no
+     trusted top-level comment contains both `@coderabbitai review` and
      `<!-- coderabbit-final-head-review:<full-head-sha> -->`, use
      `add_issue_comment` to post `@coderabbitai review`, a blank line, and that
      exact marker. A marker comment is trusted only when its author association
@@ -285,7 +295,12 @@ polled. Do not foreground-poll and never sleep-poll.
      require the request comment to be at or after it, and recheck the current
      full head immediately before the write. The marker detects completed
      requests and provides best-effort duplicate suppression; the issue-comment
-     API has no atomic claim.
+     API has no atomic claim. After posting, wait for that closeout attempt to
+     become terminal before the final feedback sweep, bounded by the babysit
+     deadline, and handle any findings it posts. That wait is procedural: the
+     readiness contract still never blocks on the CodeRabbit signal, and a
+     review that never starts or is still pending at the deadline is optional
+     lag.
 4. **A fork head stops the run on this surface too.** The repo gate that refuses
    fork heads (`.claude/babysit-pr.sh`) cannot run here, so establish
    `isCrossRepository` from the PR payload before the first repo command and