From 5e283ec09ee7ac2282785e6ef06d75d440af30a1 Mon Sep 17 00:00:00 2001 From: codex-bot-andresmgsl <304681515+codex-bot-andresmgsl@users.noreply.github.com> Date: Thu, 23 Jul 2026 11:21:52 +0000 Subject: [PATCH] docs: define cross-repo discovery guards --- BUILDER.md | 23 +++++++++++++++++++---- CHANGELOG.md | 1 + FLEET.md | 15 ++++++++++++--- REVIEWER.md | 23 ++++++++++++++++++++--- 4 files changed, 52 insertions(+), 10 deletions(-) diff --git a/BUILDER.md b/BUILDER.md index 6667fb2..185afe7 100644 --- a/BUILDER.md +++ b/BUILDER.md @@ -26,8 +26,14 @@ triage bug, and the move is to say so on the issue, not to guess. ## Building - Branch per issue; open the PR **as a draft early**, `Closes #N` in the - body. Drafts are invisible to the reviewer panel on purpose — the draft - phase is yours. + body. `Closes #N` does not cross repos: when the PR is in a different repo + from its authorizing issue, use `Part of /#N` instead, and + comment on that issue with the draft PR link as soon as the draft opens. + Triage closes the authorizing issue by hand when its acceptance criteria + are met; the cross-repo merge never closes it. This codifies the linkage + builders already used on rig#112 and ceremony #13/#16 rather than adding a + new review obligation. Drafts are invisible to the reviewer panel on + purpose — the draft phase is yours. - **The issue's acceptance criteria are your definition of done.** Reproduce them as a checklist in the PR body and check them honestly as you go. If one turns out to be wrong or unreachable, say so on the issue and get it @@ -49,8 +55,17 @@ triage bug, and the move is to say so on the issue, not to guess. panel roster and any repo-specific flow notes live in that repo's own CONTRIBUTING; everything below is the shared flow.) -1. Mark ready-for-review; request **the whole panel** (the roster is in the - repo's CONTRIBUTING). +1. Mark ready-for-review; request **the whole panel**. The panel is the roster + of the repo the **PR** is in, minus you — never the roster of the repo the + issue is in. The PR repo's `.github/labels.conf` `panel=` line is the + machine's answer; its CONTRIBUTING roster is the human-readable answer, + and `panel=` governs if they disagree because that is what the state + machine reads. If the PR repo names no roster, ask triage on the + authorizing issue before marking ready-for-review; do not guess. You may + request an off-panel reviewer, but say that their verdict is advisory and + does not become required. On rig#112 this distinction mattered: requesting + codex and grok was correct for rig's panel even though ceremony's bench was + larger, and the doctrine had not said which roster governed. 2. **Wait for every verdict, then answer the round whole** — one reply covering every point, then push the fixes, then re-request exactly the reviewers who did not approve. Prefer verification over argument: when a diff --git a/CHANGELOG.md b/CHANGELOG.md index 34eed9d..2cf773f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ so entries say what changed, cite the issue, and stop. ## Unreleased - `needs-ruling` — the cross-cutting flag for a pending human decision, excluded from `state:needs-human` and from the staleness sweep (#51). +- Cross-repo doctrine: the panel is the PR's repo's roster, a review request is authorization but not panel membership, and `Part of #N` replaces the `Closes #N` that cannot cross repos (#57). ## 0.1.0 — 2026-07-22 diff --git a/FLEET.md b/FLEET.md index 184e2e0..1a37f22 100644 --- a/FLEET.md +++ b/FLEET.md @@ -54,9 +54,18 @@ Every box runs the same skeleton, adapted to its CLI: fully approved (write the closing summary, flip to `state:needs-human`, request the human), my PR `CONFLICTING` (rebase; never act on `UNKNOWN` — post-merge flap). -- **Reviewers:** an open PR by someone else whose head I have not yet - reviewed — one verdict per head, deduplicated against my own latest review's - SHA, not against the search index (it lags). +- **Reviewers**, in priority order: first, a review requested on me in any + repo (`gh search prs --review-requested=@me --state=open`); second, the + repo-list poll for an open PR by someone else whose head I have not yet + reviewed. Both triggers keep the existing one-verdict-per-head rule, + deduplicated against my own latest review's SHA rather than the search index + (it lags). The request trigger runs first because it reaches repos the list + does not name. + +`~/duty/repos.txt` and the duty scripts live inside each box and are the +operator's to change. This descriptive edit is the spec for those box-side +updates; until an operator makes them, the request trigger exists on paper +only. ### Resilience diff --git a/REVIEWER.md b/REVIEWER.md index 3a28e0b..f92006d 100644 --- a/REVIEWER.md +++ b/REVIEWER.md @@ -23,9 +23,10 @@ The machine reads only your **verdict**; humans read your reasons. In order of authority: -1. **The issue's acceptance criteria** — the PR's `Closes #N` names your - spec. Check every criterion; a PR that ships less than the issue says is - a request-changes even if the code is beautiful. +1. **The issue's acceptance criteria** — the PR's `Closes #N`, or its + cross-repo `Part of /#N`, names your spec. Check every + criterion; a PR that ships less than the issue says is a request-changes + even if the code is beautiful. 2. **The repo's load-bearing constraints** — the rules bought with incidents (in ceremony itself: issue #1's constraint list; in a governed repo: its own CONTRIBUTING plus ceremony's README). A change that @@ -40,6 +41,22 @@ In order of authority: test settles what a comment thread can't. A review that says "I ran X and saw Y" outranks one that says "this looks like it might". +## Where you review + +- **A review request on you is your authorization** in any `heavy-duty` repo + and on any fleet member's fork. You need no separate permission and do not + wait for the repo to appear on a list: review is reversible + read-plus-comment work, and the requester already decided it should happen. +- **A request is authorization, not panel membership.** Convergence is + measured against the target repo's `panel=` roster minus the author. If you + are requested off-panel, post the verdict anyway and say in its body that + it is advisory; neither your silence nor your request-changes is a gate the + reconciler enforces. The nine-hour wait for kimi's off-panel verdict on + rig#112 showed why authorization and membership must not be conflated. +- **Being requested is a wake condition of its own.** It is how work in a + repo you have never heard of reaches you; a repo list finds only work in + repos somebody thought to list. + ## What you do not do - **Re-litigate the spec.** The issue's decisions were made in triage and,