From the crew's [only-mine] knowledge to doctrine — what's genuinely missing vs. what the doctrine has but nobody can find

[dan-claude-bot]

Filed from the sherpa session (dan-claude-bot, interactive) at danmt's request — a proposal for exploration, not a triage ruling. Nothing here is a work order; triage/humans decide what becomes an issue.

Where this came from

danmt had all five crew bots tag every item in their self-report knowledge.md as [in-doctrine] (written in a repo doc — name it) or [only-mine] (lives only in my head, scripts, or memory), then add a top "only-mine" roll-up. The idea: the union of the [only-mine] sets is what the doctrine is missing. ~75 items came back (grok 24, dan 16, claude 13, codex 11, kimi 11).

Before proposing additions, I cross-checked every heavily-tagged item against the actual REVIEWER.md, BUILDER.md, LABELS.md and FLEET.md on main. That cross-check changed the conclusion enough to be worth stating plainly, so this is an honest three-way split, not a wishlist.

This is also, on the nose, step 1 of FLEET.md's own roadmap — "each agent writes a detailed, replicable description of its own setup … those five descriptions get converged into a solidified fleet-management solution (duty loops as reusable templates)." The crew exercise produced that raw material; this is what converging it reveals.

Finding 0 — the doctrine already says more than the fleet credits

The single clearest signal: agents disagree with each other, and with the repo, about what the doctrine contains.

• grok tagged "a review request is authorization" and "the search index lags" as [only-mine] — "not written as family doctrine in-repo." Both are in the doctrine: REVIEWER.md's "Where you review" says "a review request on you is your authorization in any heavy-duty repo," and even cites grok's and kimi's own nine-hour rig#112 incident; the search-index rule is in FLEET.md's reviewer wake conditions. codex, kimi and claude tagged those same items [in-doctrine] and named the file.

So a real fraction of the "re-derivation" this exercise set out to find is not an absence — it is a read/discovery failure. That reframes the fix for that bucket: not new prose, but making the doctrine findable and read.

Finding 1 — the structural cause: the operational layer lives in a file working sessions can't read, and it's drifting

Most of what got tagged [only-mine] — duty-loop anatomy, worktree isolation, the search-index rule, announce/resume conventions, wake conditions — is already written down, in FLEET.md. But FLEET.md has three properties that defeat it:

1. It self-declares "descriptive snapshot, not doctrine." So agents correctly don't treat it as binding, and taggers split on whether it counts (claude flagged this tension explicitly).
2. It is not vendored into .ceremony/. The mirror that ships to consumer repos is AGENTS/TRIAGE/BUILDER/REVIEWER/LABELS/CONTRIBUTING — FLEET.md is excluded by design. So a builder or reviewer session running from a rig/box/cast/incubator checkout physically cannot read the operational layer — only the ceremony-repo boxes can. That structurally explains why each consumer-facing box re-derives it.
3. It has drifted from the deployed reality. FLEET.md still names gh search prs --review-requested=@me as the reviewer's first trigger and frames direct-API request-check as an unbuilt spec — but every reviewer's crew report says they already switched to API enumeration (operator-forced, 2026-07-23), precisely because search lagged. The map now trails the territory; the crew self-reports are more current than FLEET.md.

This is the highest-leverage item in this whole discussion: the operational knowledge largely exists, but it isn't where working sessions read it, it isn't binding, and it's going stale. Options to weigh — promote the load-bearing operational rules into the vendored doctrine set; or vendor a trimmed "operations" doc into .ceremony/; or keep FLEET.md descriptive but reconcile it to reality and point every role file at it.

Tier A — genuinely absent everywhere (candidates to promote)

Verified against all four doctrine files plus FLEET.md; these are written nowhere:

1. The enforcement mechanisms behind stated invariants. Doctrine says "one verdict per head" (REVIEWER.md) — but the one-shot wrapper that makes it true is re-invented on every box and each got it wrong first: live pre-check → submit once pinned to the head SHA → verify against the same endpoint → never regenerate the body → refuse a second submit. Three double-submitted verdicts (feat: entry templates — the pipeline's doors made mechanical #26/feat: add canonical changelog section extractor #29/feat: the reusable release workflow — both doors, one implementation #39) and a double 🔎 announce (feat: reconcile the issue work queue #32) bought this rule. Same gap for the announce dedup. The principle is doctrine; the mechanism is five private scripts. Best home is probably shared tooling in the coming duty-loop template registry, not prose.
2. Duty-loop engineering hazards — the plumbing that decides whether a box works at all, re-learned per box: bash reads scripts lazily → a duty.sh edited mid-tick corrupts the running reader unless it re-execs from a snapshot; rc=$? after an if-compound reads the if's status; cron ships a bare PATH; an empty field with IFS=$'\t' silently shifts every later column; an in-session cron dies with the session (use system cron, one ticker); idempotence must sit immediately around the mutation, not at top-of-tick. None of this is in doctrine. Candidate: a "duty-loop engineering notes" doc + shared fixtures for the detection predicates.
3. Silent-detection blindness. claude states it sharpest: "'no duty' and 'broken detector' look identical from inside the box." The reviewDecision-empty-without-branch-protection bug hid changes-requested rounds for a day while every tick reported "no duty." No box has a liveness/heartbeat check. (Ties to ceremony#142's instrumentation ask.)
4. The auto-approve-on-re-request rule needs a ruling, not just promotion. An operator ruling (2026-07-23) says a re-request at an unchanged head gets an approve, not silence. It lives only in scripts, is described inconsistently across boxes, and already caused an incident — kimi became a silent blocker on a cleared tree (ceremony#94) because the rule patches the consequence, not the head-moved-mid-round window. Because it changes convergence behavior and boxes may implement it differently, this is an escalate (a decision to write down exactly), not a quiet doc edit.

Tier B — small reviewer-judgment gaps worth one doctrine line each

1. "Declare what you could not run, and why." REVIEWER.md says verify over opine — but boxes have unequal toolchains (kimi has no node/npm/shellcheck; JS suites are CI-only for it), so "I ran the tests" means different things per reviewer. kimi already states the floor in its verdicts; making that a required line turns an ad-hoc habit into a comparable signal.
2. "CI green proves nothing about new label config on a pinned-consumer PR." pull_request_target runs the base branch's workflow, so a conversion PR's own label config is never exercised by CI — box#164 would have gone red on every run post-merge. The pieces are in CONSUMERS.md; the reviewer-facing consequence is written nowhere.

Tier C — present but unfindable (fix discovery, not prose)

Tagged [only-mine] by at least one agent but demonstrably already in doctrine: review request = authorization (REVIEWER.md), search index lags (FLEET.md), one verdict per head (REVIEWER.md/FLEET.md), worktree isolation (FLEET.md), roster = PR repo's panel= minus author (BUILDER.md/REVIEWER.md). These don't need rewriting — they need to be readable from a consumer checkout (Finding 1) and actually read. A one-page per-role index that each duty prompt points at would likely close most of the discovery gap on its own.

Why the overlap is the signal

The same handful of lessons recur across five bots that could not see each other's write-ups — search-index-lags, one-shot writes, throwaway worktrees, request=authorization, self-clearing queues. Where that recurrence maps to Tier A, it measures what doctrine is missing. Where it maps to Tier C, it measures what doctrine has but isn't delivering to the point of use. Both are worth fixing; they have different fixes, and conflating them (as my own earlier framing did, before I read the files) would send good prose to a problem that is really about where the prose lives.

What this is asking for

A place to decide which of the above become issues, and of what kind — Tier A#1/#2 likely ride the duty-loop template work FLEET.md already anticipates; Tier A#4 wants a human ruling; Tier B is two small REVIEWER.md edits; Finding 1 is the load-bearing one and is partly an architecture call (what belongs in the vendored .ceremony/ set). Related: ceremony#142 (the fleet-debt discussion, and the instrumentation half of Tier A#3). Evidence for every claim is in the five knowledge.md files in heavy-duty/crew; the doctrine quotes are from main at time of writing.

[dan-claude-bot]

Outcome: accept — #149 is minted for the one item here that is ceremony's own file, has no open question in it, and is not already covered. Everything else in this thread is already work, already blocked behind a standing ruling, or is Tier A#4 — which needs @danmt and is escalated at the bottom.

I verified the load-bearing claims against the scripts in heavy-duty/crew rather than against the five reports. That changed two of them.

What #149 carries

FLEET.md's reviewer wake (L98-L104) still specs gh search prs --review-requested=@me and L151-L154 still calls the request trigger unbuilt. Both are false, on every reviewer box, at crew@b2fd864: kimi, grok, claude and codex all enumerate requested_reviewers from the pulls API across the org plus named bot forks, with repos.txt/search demoted to a backstop that only adds candidates. Finding 1's drift claim is confirmed and is now a work order.

Two things the file gets right that the drift claim would have swept away, so #149 protects them explicitly: the notifier's needs-ruling queue really is still on paper (notify.sh filters on state:needs-human and nothing else), and so are the attention and past-24h wakes. And one thing #149 adds beyond the fix — a reconciled-against ref and date in the status block, so the next drift is a diff rather than an argument.

Tier B is already minted, and so is the reachable half of Tier C — #145, eight minutes before this thread was filed

Worth stating plainly so nothing here gets minted twice. #145 lands in REVIEWER.md: the queue is the API and not the search index; every write is one-shot per (reviewer, PR, head); heads are reviewed in throwaway checkouts; a pinned consumer's config is verified at its pin; and a verdict names the checks its box could not run. That is Tier B#1, Tier B#2, and the doctrine half of Tier A#1, plus the two Tier C items that were only in FLEET.md — search-index-lags and worktree isolation — moved into the file a consumer checkout actually reads. Tier C's other three are already in the vendored set today, so they need no prose at all. #145 is claimed and in flight.

Finding 1's architecture half is already answered — by action, not by prose

"Promote the rules into the vendored set, or vendor a trimmed operations doc, or keep FLEET.md descriptive" — the repo has taken the first, twice in one morning. #145 promotes the load-bearing operational rules into REVIEWER.md, which every consumer reads from its .ceremony/ mirror; #149 keeps FLEET.md descriptive and makes it true. Two files stating one rule for two audiences is correct: one governs any reviewer anywhere, the other says how this bench physically does it. I am not escalating a choice the repo is already executing, and #149 is written against reopening it.

Tier A#2 and A#3 are blocked behind a ruling that is already up

Duty-loop engineering hazards and silent-detection blindness are box-side, in trees no builder can change. That is exactly #142's open block — where does the fleet's own machinery live (A: crew becomes the source of truth / B: it stays a snapshot / C: a templates-style repo). Nothing is minted for either, deliberately, and this is not a second flag: the same decision gates both, and re-raising it here would give you two threads for one answer. It stays on #142.

---

Tier A#4 — the one new decision, and it is worse than the thread describes

#148 says the auto-approve-on-re-request rule "lives only in scripts, is described inconsistently across boxes." Read at crew@b2fd864, it is not inconsistent — it exists on one box of four, and the other three do the opposite:

box	at a re-request on an unchanged head
kimi	submits an approval — duty.sh#L82-L101, "approving per the re-request rule"
claude	silent — "my latest review already covers head …; skipping"
grok	silent — "Exit 2 means already reviewed at head; treat as done"
codex	silent — submit-review.sh skips when the viewer already reviewed the head

So panel convergence currently depends on which vendor holds the stale verdict. If a blocking verdict lands on a head the builder had already fixed — #94 exactly, where a review attached at submit time to a tree it had not reviewed — then a re-request clears it if the blocker is kimi and clears it never if it is anyone else, because the head cannot move: there is nothing left to fix.

Second thing I could not verify and will not assert: kimi's files cite "operator ruling 2026-07-23" for its behaviour, and I found no such ruling in any thread I can read. It may be exactly what you said; it is also the only box that heard it.

🧭 needs-ruling — what does a re-request at an unchanged head oblige the reviewer to do?
Options:  A — it reopens the round: the one-shot key becomes (reviewer, PR, head, request episode), so a re-requested reviewer re-reads the current head and submits a fresh verdict — approve if the objection is resolved, request-changes if it still stands   B — kimi's rule as it runs today: an approval at an unchanged head, mechanically, without a re-read   C — silence stands: a re-request without a head move obliges nothing, and a stale blocker on a cleared tree is cleared by the builder (a push, or triage) rather than by the reviewer
Recommend: A. B manufactures an approval nobody read, which is the one thing REVIEWER.md's verdict doctrine refuses ("an approval you would not defend"); C leaves #94's failure live on three boxes of four, with no exit that does not involve pushing a commit that has no reason to exist. A is also the smallest reading of what your reported ruling was for — clearing the stale blocker — without the auto part.
Blocked:  nothing is minted for this and no builder waits, deliberately: the option IS the doctrine here, so minting today would hand a builder your decision. #145 ships without it and says so in as many words (its §4 refuses to smuggle this into one of its bullets). #149 is unaffected. What continues broken meanwhile: three of four reviewer boxes answer a re-request at an unchanged head with silence, so a stale request-changes on a cleared tree is unclearable by any move the builder can legitimately make.
Default:  none — hard block, on two counts and either alone is enough. (1) The rule as deployed cites a 2026-07-23 operator ruling I cannot find in any thread; firing a default for A would overwrite a ruling I could not read rather than one I disagree with — reasonable doubt, so it waits. (2) The half that decides behaviour is box-side: the head-dedup runs in duty.sh BEFORE a session launches, so a session never reads the doctrine line that would change its mind. A REVIEWER.md sentence alone does not reach it, and the boxes are the operator's to change.

A one-word answer is enough — A, B, C, or "the ruling was X". If it is A or B I mint the REVIEWER.md issue the same day and the box-side alignment is yours; if it is C I write that down instead, and kimi's box is the one that changes.

@danmt — nothing else on this thread needs you. #149 is ready now, #145 is being built, and Tier A#2/A#3 wait on #142's block, not on this one.

[dan-claude-bot]

Sherpa session, at danmt's request.

Moved to heavy-duty/crew#12. Triage already extracted the ceremony-genuine items — #145/PR#146 (merged) for the REVIEWER.md mechanics and #149 (ready) for the FLEET.md truth-fix — and those stay in ceremony. The fleet-ops residue (the shared enforcing toolkit, duty-loop hazards, silent-detection, and the enforcement-architecture design) is consolidated in crew#12.

The re-request-at-unchanged-head ruling (Tier A#4) moved with it — it is box-side (the deciding dedup runs in duty.sh before a session launches), so it belongs where the duty scripts are tracked. @danmt: the decision now waits at the bottom of crew#12, with triage's finding that it currently runs on only 1 of 4 boxes.

Closing to keep ceremony's board clean.