Macroscope owns automatic PR review: record the decision and the verified fleet state

CLAUDE.md

@@ -24,6 +24,11 @@ The public home of Driver's Bonsai→GitHub pipeline workflows. Two products liv
   `dependabot.yml` (hand-installed — merged into a repo's existing file, never copied over it).
   Kit install conventions: `templates/github/README.md`.
 
+PR review is Macroscope's, org-wide (Maria, 2026-09-12): Claude reviews a PR only when a person `@claude`s it
+(optionally naming `/code-review`). The implementer's own `/code-review` pass before it opens a PR is
+implementing, not PR review — keep it. Never add an automatic Claude review of an opened PR —
+`docs/macroscope-integration-scope.md`.
+
 Two more files in `.github/workflows/` are this repo's own CI, not products: `lint.yml` and
 `dependabot-auto-merge.yml`. **`.github/workflows/lint.yml` and `templates/github/lint.yml` are
 different files** with the same name and the same job id `actionlint` (the required-check context).

README.md

@@ -507,16 +507,17 @@ run only if those `package.json` scripts exist, `themeCheck`/`dev` run only if c
 
 ## Reviewer handoff
 
-Retired with the review rails at v1.12.0 — no workflow reassigns a Bonsai task, or requests a reviewer
-*on review completion*, any more; that's a PM's job until the Macroscope→Bonsai integration lands.
-Since v1.13.0 `claude.yml` does request the GitHub reviewer named on the issue body's `Reviewer:` line
-when it opens the PR, so a ticketed PR still pings someone the moment it exists.
+Retired with the review rails at v1.12.0 — nothing here reassigns a Bonsai task or requests a reviewer
+*on review completion* any more; the status moves are a PM's job until the Macroscope→Bonsai
+integration lands. Since v1.13.0 `claude.yml` requests the GitHub reviewer named on the issue body's
+`Reviewer:` line when it opens the PR, and since 2026-09-11 the dispatcher (driver-agents) assigns the
+reviewer in Bonsai when the PR reaches Internal Review.
 The bridge server that carried `/tasks/reviewer-handoff` is retired too; what replaces it for that
 build — the Bonsai public API, and the reviewer read off the issue body instead of the Reviewer
 field — is in [`docs/macroscope-integration-scope.md`](docs/macroscope-integration-scope.md).
 `dependabot-report` still requests a human reviewer on Dependabot PRs (default `mcarter-astronautdev`,
 per-repo override via the `PR_REVIEWER_HANDLE` Actions **variable**). The live reviewer map is
-`driver-bonsai-mcp/config/reviewers.json`, read by the dispatcher to write the issue's
+`driver-agents/config/reviewers.json`, read by the dispatcher to write the issue's
 `**Reviewer:**` line; this repo no longer carries a copy.
 
 ## First-run / required-check

docs/HANDOFF.md

@@ -1,4 +1,4 @@
-# Handoff — 2026-09-10
+# Handoff — 2026-09-12
 
 State of play for the next session. Conventions, how-tos and release history live in
 [`README.md`](../README.md); the agent-facing subset is [`CLAUDE.md`](../CLAUDE.md).
@@ -17,8 +17,18 @@ major tag is the maintainers' only compatibility promise, and reconciling a majo
 is one wave, so the refs stay where they are. The Dependabot proof from the 2026-08-22 handoff
 closed that morning (vite-plugin-shopify-clean #95, opened unaided, merged, waved).
 
-Nothing is in flight in this repo. The fleet's `claude.yml` now fails an issue run that leaves no PR
-and keeps the full transcript in the job log — and **no real ticket has run on it yet**. That run is
+2026-09-12: **Macroscope owns automatic PR review, org-wide** (Maria). Claude is the pipeline and the
+on-demand second opinion, never an automatic reviewer of an opened PR; the implementer's own
+pre-review before it opens a PR is implementing and stays. #57 records the decision
+([`macroscope-integration-scope.md`](macroscope-integration-scope.md)) and changes no workflow: a fleet
+scan the same day found no Claude review on any `pull_request` event, so the kit already complied.
+`dependabot-report` is the one Claude-driven automatic verdict on a PR left, and Macroscope reviews
+Dependabot PRs too since 2026-09-10 — whether it stays is Maria's call. The to-do list was
+reconciled against the 2026-09-11 state-of-play survey; the one new gated item is the Check Run
+agents file set for `fleet-wave.sh`.
+
+Otherwise nothing is in flight. The fleet's `claude.yml` fails an issue run that leaves no PR and
+keeps the full transcript in the job log — and **no real ticket has run on it yet**. That run is
 the acceptance test (step 7 of the 2026-09-10 state-of-play), and reading its transcript is how the
 Avara #195 diagnosis gets confirmed.
 
@@ -34,6 +44,12 @@ Avara #195 diagnosis gets confirmed.
   — the dated note in [`reusable-conversion-scope.md`](reusable-conversion-scope.md).
 - **Identity unification** — still **DEFERRED**;
   [`identity-unification-scope.md`](identity-unification-scope.md).
+- **`dependabot-report`'s future.** It runs Claude automatically on every Dependabot PR (verdict over
+  the inert artifact, never the diff). Macroscope reviews Dependabot PRs too since 2026-09-10, so it is
+  the one place two bots still review automatically. Keep, or retire like the review rails.
+- **Marcella-NYC-Main review coverage.** Macroscope cannot reach a repo outside the org, so that
+  active client work gets no bot review. Install Macroscope there, transfer the repo, or accept it
+  (state-of-play survey, 2026-09-11).
 
 ## Watch-items
 
@@ -73,8 +89,9 @@ The 2026-09-10 state-of-play sets the order; the workflows-side pieces are:
 - [`fleet-operations.md`](fleet-operations.md) — wave mechanics, the fleet counts, what the pin audit
   cannot see, branch protection.
 - [`claude-yml-wave-plan.md`](claude-yml-wave-plan.md) — the next implementer wave and its gates.
-- [`macroscope-integration-scope.md`](macroscope-integration-scope.md) — the Macroscope → Bonsai
-  build, and what replaced the retired bridge server. Observed 2026-09-10: it re-reviews every push,
+- [`macroscope-integration-scope.md`](macroscope-integration-scope.md) — the 2026-09-12 decision that
+  Macroscope owns automatic review, the Macroscope → Bonsai build, and what replaced the retired
+  bridge server. Observed 2026-09-10: it re-reviews every push,
   resolves its own threads once a push addresses them, and its verdict reads `Approved at <sha>`
   once nothing is left; a fleet-changing kit release gets "not approved" on risk with zero findings.
 - `driver-agents` — the dispatcher (since 2026-09-10), the box-retirement spec, and

docs/claude-yml-wave-plan.md

@@ -19,8 +19,9 @@ implementation plan was deleted in #40 once executed. Two items deliberately div
 - **The ticketed-review prompt arm** was to be stripped; it is kept on purpose as the Macroscope
   revise-loop re-entry point (`macroscope-integration-scope.md`). Do not strip it.
 
-`v1.14.0` and `v1.15.0` were further `claude.yml` waves (README has each). Nothing below is
-un-started Plan B work; it is the ride-along list for the wave after `v1.15.0`.
+`v1.14.0`, `v1.15.0` and `v1.16.0` were further `claude.yml` waves (README has each; `v1.16.0`
+carried none of the table below). Nothing below is un-started Plan B work; it is the ride-along list
+for the next `claude.yml` wave.
 
 ## Ride-alongs for the next wave, with their gates
 

docs/macroscope-integration-scope.md

@@ -5,6 +5,19 @@ rails are retired so it gets a clean trial. Executed at `v1.12.0`. The driver: t
 maintenance burden (distributing workflow files, troubleshooting reviews that silently don't run,
 manual re-runs) vs. a vendor product that already does the loop.
 
+Decision (Maria, 2026-09-12): **Macroscope owns automatic PR review for the whole org, alone.** Claude
+is the agentic pipeline (issue → PR, `@claude` revisions) and the on-demand second opinion (a person
+`@claude`s the PR, optionally naming `/code-review`) — never an automatic reviewer of an opened PR.
+What the implementer does to its own branch before it opens the PR (the in-run `/code-review high`
+pass and the `Pre-review:` body line, v1.13.0) is implementing, not PR review, and **stays**. Verified
+the same day, so nothing in the kit had to change: no fleet workflow runs Claude on a `pull_request`
+event (45 repo/branch pairs scanned), the Claude GitHub App reviews nothing on its own (Anthropic's
+managed Code Review is a Team/Enterprise toggle in claude.ai admin settings, not a Max-plan feature),
+and the only Claude-driven automatic verdict on a PR is `dependabot-report` — `workflow_run` after a
+Dependabot validate, reasoning over the inert artifact, never the diff. Macroscope reviews Dependabot
+PRs too since 2026-09-10, so whether that rail stays is an open question for Maria. The split is also
+a usage split: Claude's Max-plan usage stays on the pipeline, Macroscope bills its own reviews.
+
 ## What v1.12.0 retired
 
 - **`pr-first-review.yml` + `ticketed-review.yml` caller stubs** — deleted from `templates/github/`
@@ -23,10 +36,11 @@ manual re-runs) vs. a vendor product that already does the loop.
 
 - Auto-flips still live, polled by the dispatcher now: issue opened → **In Progress**; non-draft PR
   dev-linked to the issue → **Internal Review**.
-- Everything after Internal Review is **manual** (PM): Revisions Requested, Ready for QA, and the
-  move of a Bonsai task off **Agents** to a human reviewer. Since v1.13.0 the PR itself does ping a
-  human — `claude.yml` requests the reviewer named on the issue body when it opens the PR — but
-  nothing moves the Bonsai task, so that is where a ticket stalls.
+- The status moves after Internal Review are **manual** (PM): Revisions Requested and Ready for QA.
+  Since 2026-09-11 the dispatcher assigns the reviewer in Bonsai at Internal Review (driver-agents
+  #12) and, once a person sets Revisions Requested, forwards the revisions to the PR as an `@claude`
+  comment. `claude.yml` still requests the GitHub reviewer named on the issue body when it opens the
+  PR (v1.13.0).
 - `claude.yml` still carries the ticketed-loop machinery (round-marker prompt branch, actor gate,
   re-request step) — v1.13.0 rewrote the issue prompt around it and left it intact. It looks dead;
   it is not — it's the re-entry point below. **Do not strip it in a claude.yml wave.**
@@ -81,9 +95,9 @@ Building blocks that already exist — reuse, don't rebuild:
   `driver-digital-agents` (id `261291955`) posts a comment carrying `<!-- ticketed-review-round -->`
   + `@claude`. The receiver posts that comment via `AGENTS_GH_PAT` and the whole revise loop comes
   back — Macroscope-driven instead of ticketed-review-driven.
-- **Human handoff:** reassigning the Bonsai task is a public-API write now and the reviewer handle
-  comes from the issue body (2026-08-21 note below); the GitHub-side reviewer request already ships
-  in `claude.yml` (v1.13.0) — one `gh pr edit --add-reviewer` with the same PAT.
+- **Human handoff:** done by the dispatcher since 2026-09-11 — it assigns the Bonsai reviewer at
+  Internal Review from `driver-agents/config/reviewers.json`; the GitHub-side reviewer request still
+  ships in `claude.yml` (v1.13.0) — one `gh pr edit --add-reviewer` with the same PAT.
 - **Status flips:** a public-API write too (note below); the bridge endpoint the retired sync rail
   used is gone.
 
@@ -93,6 +107,7 @@ the Agents API key, and triggers the dispatcher via workflow_dispatch { task_uui
 driver-bonsai-mcp. The Reviewer custom field is not readable through the public API; the reviewer
 comes from the issue body's **Reviewer:** line instead.
 
-Open questions for the build: Macroscope's webhook auth/payload shape; where the receiver
-terminates; whether the remaining two status legs (issue → In Progress, PR → Internal Review) fold
-into the receiver eventually or stay with the dispatcher's polling.
+Open questions for the build: Macroscope's webhook auth/payload shape — moot if the Check Run agents
+pilot (`docs/HANDOFF.md`, next steps) gives the receiver GitHub's own `check_run` event as its
+contract; where the receiver terminates; whether the remaining two status legs (issue → In Progress,
+PR → Internal Review) fold into the receiver eventually or stay with the dispatcher's polling.

templates/github/README.md

@@ -25,9 +25,13 @@ trailing `# vX.Y.Z` comment on the `uses:` line is the only place the version is
 | `dependabot-report.yml` | Reasons over that artifact → verdict comment + human reviewer request. |
 | `dependabot-keep-current.yml` | Rebases out-of-date Dependabot PRs on strict (require-up-to-date) repos; inert elsewhere. |
 
-**PR review is Macroscope's job, not the kit's** (decided 2026-08-08). The old review rails —
-`pr-first-review.yml` and `ticketed-review.yml` — were retired at v1.12.0: stubs deleted here and
-fleet-wide, reusables preserved caller-less in the central repo. See
+**PR review is Macroscope's job, not the kit's** (decided 2026-08-08, reaffirmed 2026-09-12). The old
+review rails — `pr-first-review.yml` and `ticketed-review.yml` — were retired at v1.12.0: stubs deleted
+here and fleet-wide, reusables preserved caller-less in the central repo. Claude reviews a PR only when
+a person `@claude`s it (optionally naming `/code-review`); the implementer's own `/code-review` pass
+before it opens a PR is part of implementing, not PR review, and stays. Macroscope is installed
+org-wide, so a repo outside DriverDigital gets no automatic review at all (open decision,
+`../../docs/HANDOFF.md`). See
 [`../../docs/macroscope-integration-scope.md`](../../docs/macroscope-integration-scope.md).
 
 Two rules that fail **silently** if broken: