docs: define cross-repo discovery guards

This commit is contained in:
codex-bot-andresmgsl 2026-07-23 11:21:52 +00:00
parent 66f1c08e1a
commit 5e283ec09e
4 changed files with 52 additions and 10 deletions

View file

@ -26,8 +26,14 @@ triage bug, and the move is to say so on the issue, not to guess.
## Building ## Building
- Branch per issue; open the PR **as a draft early**, `Closes #N` in the - 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 body. `Closes #N` does not cross repos: when the PR is in a different repo
phase is yours. from its authorizing issue, use `Part of <owner>/<repo>#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 - **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 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 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 panel roster and any repo-specific flow notes live in that repo's own
CONTRIBUTING; everything below is the shared flow.) CONTRIBUTING; everything below is the shared flow.)
1. Mark ready-for-review; request **the whole panel** (the roster is in the 1. Mark ready-for-review; request **the whole panel**. The panel is the roster
repo's CONTRIBUTING). 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 2. **Wait for every verdict, then answer the round whole** — one reply
covering every point, then push the fixes, then re-request exactly the covering every point, then push the fixes, then re-request exactly the
reviewers who did not approve. Prefer verification over argument: when a reviewers who did not approve. Prefer verification over argument: when a

View file

@ -7,6 +7,7 @@ so entries say what changed, cite the issue, and stop.
## Unreleased ## Unreleased
- `needs-ruling` — the cross-cutting flag for a pending human decision, excluded from `state:needs-human` and from the staleness sweep (#51). - `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 <repo>#N` replaces the `Closes #N` that cannot cross repos (#57).
## 0.1.0 — 2026-07-22 ## 0.1.0 — 2026-07-22

View file

@ -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`, fully approved (write the closing summary, flip to `state:needs-human`,
request the human), my PR `CONFLICTING` (rebase; never act on `UNKNOWN` request the human), my PR `CONFLICTING` (rebase; never act on `UNKNOWN`
post-merge flap). post-merge flap).
- **Reviewers:** an open PR by someone else whose head I have not yet - **Reviewers**, in priority order: first, a review requested on me in any
reviewed — one verdict per head, deduplicated against my own latest review's repo (`gh search prs --review-requested=@me --state=open`); second, the
SHA, not against the search index (it lags). 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 ### Resilience

View file

@ -23,9 +23,10 @@ The machine reads only your **verdict**; humans read your reasons.
In order of authority: In order of authority:
1. **The issue's acceptance criteria** — the PR's `Closes #N` names your 1. **The issue's acceptance criteria** — the PR's `Closes #N`, or its
spec. Check every criterion; a PR that ships less than the issue says is cross-repo `Part of <owner>/<repo>#N`, names your spec. Check every
a request-changes even if the code is beautiful. 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 2. **The repo's load-bearing constraints** — the rules bought with
incidents (in ceremony itself: issue #1's constraint list; in a governed incidents (in ceremony itself: issue #1's constraint list; in a governed
repo: its own CONTRIBUTING plus ceremony's README). A change that 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 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". 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 ## What you do not do
- **Re-litigate the spec.** The issue's decisions were made in triage and, - **Re-litigate the spec.** The issue's decisions were made in triage and,