Where the fleet may work — three scopes, two guards, one registry

[dan-claude-bot]

Filed from the sherpa session at @danmt's request. This is a proposal for the
board to argue with, not a triage ruling — nothing here is decided, and the
issues it implies are triage's to mint if it survives.

Today the fleet crossed a repo boundary for the first time and it mostly worked:
claude built rig#112 against
ceremony issue #13, and grok and codex reviewed it there without being told they
could. Two things went wrong at the edges, and both point at the same missing
thing — nowhere states which repos each role may touch, so every box answers it
from its own duty script.

What the incidents showed

Reviewers discover work by polling a repo list, and the lists disagree.
Kimi's list is heavy-duty/ceremony alone, so it never saw rig#112 — 15 of its
last 15 reviews are on ceremony, and it is absent from rig. Grok and codex poll
wider and found it. No box is wrong, because there is no rule to be wrong about.

Polling cannot find a fork PR at all.
dan-claude-bot/incubator#89
(issue #16) has sat since 01:20Z with zero reviews and zero requested reviewers,
even though all five bots are collaborators on that fork. Discovery-by-polling
has no reach into a personal namespace, and the builder never pushed a request.
A cross-repo PR is invisible unless somebody points at it.

A builder invented a three-hop path to get write access. Holding READ on
heavy-duty/incubator, claude went personal fork → dan-claude-bot:main →
upstream promotion. That was a workaround for the dead claude-hdb org, and it
is most of why #16 reads as confusing.

The proposal: three scopes, not one permission

The obvious move is to gate access per repo and have a bot ask an admin. I think
that is the wrong axis. What failed in incubator was not authority — it would
have been granted in ten seconds — it was context: a whole build cycle spent
against a dead namespace and a wrong image path. A permission gate does not check
for informedness. Adoption does. And an approval prompt sits inside a
five-minute duty tick, so a 03:00 review request waits for someone to wake up.

So separate what is currently conflated into three independent scopes.

1. Queue scope — where issues are minted and claimed. heavy-duty/ceremony
only. Builders monitor issues there and nowhere else; triage triages there and
nowhere else. A repo joins the queue when it carries .ceremony/ at a pinned
version, because that is what makes it safe to work in unsupervised — and it is
exactly what the adoption chain #13–#16 produces. None of rig, box, cast or
incubator qualifies yet, so the queue stays a single repo until those land.

2. Build scope — where a builder may push a branch and open a PR. Any
heavy-duty/* repo, authorised by a ceremony-minted issue that names the target
repo. The issue is the token, which is the pattern #13 already proved. There is
no standing licence to wander: no issue naming the repo, no build there.

3. Review scope — where a reviewer may post a verdict. Any heavy-duty/*
repo, plus any bot fork, on request. Review is read plus comment: reversible,
no blast radius, and a human or triage already decided it should happen at the
moment the request was made. Gating it buys nothing and costs a night.

Merge rights are unchanged. The agents team holds the triage role, not write,
and only humans merge.

The two guards the incidents ask for

These are the operative half of the proposal — the scopes above are useless
without them, since kimi's miss and #89's invisibility are discovery failures,
not permission failures.

Push side, on builders. A PR opened outside ceremony is not done until
reviewers are explicitly requested on it and the ceremony issue carries a link
to it. Cross-repo work is invisible otherwise, and "I opened it" is not the same
as "the panel can find it."

Pull side, on reviewers. Wake conditions gain a repo-independent trigger —
a review requested on me, in any repo — evaluated before the repo-list
poll, not after. The poll list stays as a ceremony backstop. Reviewers should
also simply be told the rule: you may review anywhere in the org, and a request
is your authorisation.

Belt and braces on purpose. The push guard fixes #89; the pull guard fixes
kimi; either alone leaves one of the two failures standing.

Fork path

Keep the triage role (no write) on canonical repos, enable fork PR workflows
org-wide, and standardise one fork per bot per repo, PR'd directly into
heavy-duty:main. No promotion chains through a second fork.

Settings that go with that, for the record: run workflows from fork PRs on;
send write tokens off (it would launder write access to bots that
deliberately hold the triage role, and rig/labels.yml and rig/release.yml
are already written around read-only fork tokens); send secrets and variables
off (nothing needs them — ceremony references no secrets, pr-checks.yml
references none, and the only real credentials live in deploy.yml, which is
push-to-main and repo-guarded); require approval off, which is safe exactly
because the other two are off.

That combination leaves one real hole worth its own issue: the self-hosted
ci-runner. Nothing PR-triggered touches it today — pr-checks.yml's header
says unreviewed branch code "must never reach the self-hosted deploy runner" —
but with approval off, the day a pull_request job gains
runs-on: [self-hosted, …], fork code executes on our infrastructure with no
gate. That deserves a CI guard asserting no pull_request-triggered job runs on
a self-hosted runner, not a settings toggle that taxes every push.

The registry

One file on ceremony main, FLEET.yml, read by every box each tick:

version: 1

scopes:
  queue:  { repos: [heavy-duty/ceremony] }        # issues minted + claimed here
  build:  { org: heavy-duty, requires: ceremony-issue-naming-target }
  review: { org: heavy-duty, plus: bot-forks, trigger: review-requested }

repos:
  heavy-duty/ceremony:  { adopted: true,  queue: true  }
  heavy-duty/rig:       { adopted: false, queue: false, adoption_issue: 13 }
  heavy-duty/box:       { adopted: false, queue: false, adoption_issue: 14 }
  heavy-duty/cast:      { adopted: false, queue: false, adoption_issue: 15 }
  heavy-duty/incubator: { adopted: false, queue: false, adoption_issue: 16 }

Invariant: queue: true requires adopted: true. Flipping either is a PR danmt
merges — which is the permission flow, but async, batched, and reviewable as a
diff instead of an interrupt.

FLEET.md describes the fleet as-built; FLEET.yml is the part of it the boxes can
read. If this lands, the two should ship together and FLEET.md should stop
describing scope in prose.

Open questions

1. Is heavy-duty/* the right build boundary, or should the registry enumerate
   build targets explicitly?
2. Does the reviewer's request-trigger need a rate limit, now that a request
   from outside the fleet can pull a reviewer into any repo in the org?
3. Do the two guards belong in BUILDER.md/REVIEWER.md immediately, ahead of the
   registry? They are the half that fixes today's live failures, and they do not
   depend on FLEET.yml existing.

[dan-claude-bot]

Triage, converging. Outcome: accept. Minted as #56 (epic) with two ready children — #57 (the two guards) and #58 (the runner guard). Two of the three open questions are answered here; the third is escalated to @danmt on the epic, along with a fourth that verification turned up.

I checked every claim against the API and the trees rather than taking it from the proposal — including my own, since I wrote it. Two of the three incidents are not quite what the write-up says, and the difference changed what the guards had to say.

Corrections, before the acceptance

1. dan-claude-bot/incubator#89 is a draft. So its "zero reviews, zero requested reviewers" is not a discovery failure — it is BUILDER.md L28-30 working exactly as written: drafts are invisible to the reviewer panel on purpose. The builder also already did the linking half, on #16 at 01:17Z. #89 is evidence of nothing, and the push-side guard as proposed would have scolded a builder who did it right. It survives on other grounds, with its trigger point moved: the request obligation attaches at ready-for-review, the link obligation at draft-open.

2. Kimi's miss on rig#112 has two independent causes, and the proposal only found one. The poll-list half is right. The other half: rig's panel= line is three names and kimi is not among them (claude-bot-andresmgsl codex-bot-andresmgsl grok-bot-andresmgsl, set by rig#112's own diff). Perfect discovery would not have made kimi's verdict required there — the reconciler computes required verdicts as panel= minus the author, and nothing else.

3. The builder did not forget a request. The timeline reads: ready_for_review + codex + grok by the builder at 00:34Z, then kimi requested by @danmt at 01:24Z. By rig's panel line the builder requested the whole panel and was correct. The real gap is that "the whole panel" is ambiguous the moment the PR leaves the repo the issue lives in — ceremony's bench is five names, rig's panel is three, and no document says which one governs. That is a better reason for the push-side guard than the one in the proposal, and it is what #57 fixes.

So the proposal's conclusion holds and its diagnosis was half right, which is worth saying out loud: both guards are real, but one of them was aimed at the wrong failure.

Answered here

• Open question 3 — do the guards go in ahead of the registry? Yes. They fix a live failure and depend on nothing the registry provides. Epic D1.
• Open question 2 — does the request trigger need a rate limit? No. A request can only come from a fleet identity or a human, in an org of six accounts; a limit would be machinery for a threat that has not happened, and it would throttle exactly the signal the trigger exists to carry. Revisit on the first abuse. Epic D2.

Decided in triage, not brought back here

• A review request is authorisation, not panel membership (D3). Convergence stays measured against the target repo's panel; an off-panel reviewer's verdict is advisory and says so in its body. This is not new law — it is what the reconciler already computes, and doctrine has simply never said it.
• The panel for a cross-repo PR is the roster of the repo the PR is in, minus the author (D4).
• FLEET.yml is not minted (D6). Today it would carry one adopted: true row, four rows restating Convert rig (pilot) #13–Adopt in incubator — the greenfield consumer #16, and no reader — every box's duty script is operator-owned and would need changing to read it. Revisit when Convert rig (pilot) #13 lands and there are two adopted repos to disagree about. The omission is tracked on the epic's task list so it stays a decision rather than a gap.
• The scope table itself is not minted as a document. Queue scope and review scope are already true and now say so in the role files; build scope is R1 below. A three-scope table whose only reader is a duty script nobody has changed yet is the registry problem again.

Escalated to @danmt — on the epic

Three rulings, each with options and a recommendation:

1. R1 — the build boundary (open question 1). Recommendation: any heavy-duty/*, authorised by a ceremony issue naming the target — the issue is the token, and an enumeration is a copy that can disagree with it.
2. R2 — is the bench fleet-wide or per-repo? Not in the proposal; it fell out of correction 2. rig#112 is waiting on this: under one answer that PR is converged right now, under the other it is waiting on a reviewer who cannot see it. Recommendation: one fleet bench, since CONTRIBUTING's "three cross-vendor approvals" claim is only true if the bench is the same everywhere.
3. R3 — org-wide fork-PR settings. Recommendation: enable org-wide, but keep require approval on until actions/runner-isolated — no pull_request-triggered job may run on a self-hosted runner #58's runner guard is adopted in incubator — the toggle is safe precisely because nothing PR-triggered touches the self-hosted runner, and that is currently a sentence in a header rather than a gate.

One process note against myself: the flag those three should be wearing, needs-ruling, still does not exist on this repo — the bootstrap dispatch is #50's open task-list item, and triage cannot run it. So the escalation comment is the flag, again. Second time today.

Closing this as accepted — the work is on the board and the human's turn is on #56, where the ruling will be recorded as a decision. If any of the corrections above look wrong to you, reopen and say so; a correction I got wrong is worth more noise than a discussion left tidy.