heavy-duty/ceremony

Fork 2

docs: teach reviewers the queue mechanics #146

Merged

codex-bot-andresmgsl merged 1 commit from build/145-review-mechanics-doctrine into main

2026-07-24 13:32:57 +00:00

codex-bot-andresmgsl commented

2026-07-24 13:12:42 +00:00

(Migrated from github.com)

Closes #145

Summary

make environment blind spots explicit in verdict evidence
require pinned-consumer verification at the configured ref
document API queue discovery, one-shot writes, and throwaway review worktrees

A doctrine edit on ceremony main cannot red a consumer: actions/docs-sync/docs-sync.sh resolves and compares doctrine from the consumer’s own pinned ceremony ref, never from ceremony main.

Worklog

Add the verdict blind-spot rule and pin-verification rule with incident evidence
Add the exactly-three-bullet queue mechanics section with incident evidence
Add the exact changelog fragment
Run the full suite and scope/line-count/read-back checks
Mark ready and request the full review panel

Acceptance criteria

## How you work the queue is between ## Where you review and ## What you do not do, with exactly three bullets
Each of the five rules names the incident that bought it through a resolvable reference
The one-shot rule states the immediate check, insufficient session-start check, stop-after-verification, and announce/verdict coverage
The queue rule makes search add-only and states that requested_reviewers self-clears
The verdict rule names both unrun checks and substitute evidence
Only REVIEWER.md and changelog.d/145.md change
REVIEWER.md remains under 140 lines (134)
bash test/run.sh is green

Verification

git diff --check
Queue section contains exactly three top-level bullets
git diff --name-only origin/main returns exactly the two allowed paths
bash test/run.sh — 17 test files passed, 0 failed

Closes #145 ## Summary - make environment blind spots explicit in verdict evidence - require pinned-consumer verification at the configured ref - document API queue discovery, one-shot writes, and throwaway review worktrees A doctrine edit on ceremony `main` cannot red a consumer: `actions/docs-sync/docs-sync.sh` resolves and compares doctrine from the consumer’s own pinned ceremony ref, never from ceremony `main`. ## Worklog - [x] Add the verdict blind-spot rule and pin-verification rule with incident evidence - [x] Add the exactly-three-bullet queue mechanics section with incident evidence - [x] Add the exact changelog fragment - [x] Run the full suite and scope/line-count/read-back checks - [x] Mark ready and request the full review panel ## Acceptance criteria - [x] `## How you work the queue` is between `## Where you review` and `## What you do not do`, with exactly three bullets - [x] Each of the five rules names the incident that bought it through a resolvable reference - [x] The one-shot rule states the immediate check, insufficient session-start check, stop-after-verification, and announce/verdict coverage - [x] The queue rule makes search add-only and states that `requested_reviewers` self-clears - [x] The verdict rule names both unrun checks and substitute evidence - [x] Only `REVIEWER.md` and `changelog.d/145.md` change - [x] `REVIEWER.md` remains under 140 lines (134) - [x] `bash test/run.sh` is green ## Verification - [x] `git diff --check` - [x] Queue section contains exactly three top-level bullets - [x] `git diff --name-only origin/main` returns exactly the two allowed paths - [x] `bash test/run.sh` — 17 test files passed, 0 failed

danmt (Migrated from github.com) reviewed 2026-07-24 13:12:42 +00:00

grok-bot-andresmgsl commented

2026-07-24 13:15:53 +00:00

(Migrated from github.com)

🔎 reviewing head 1233e9b1b6

🔎 reviewing head 1233e9b1b6cc0249906220140519bdc679007658

grok-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-24 13:17:52 +00:00

grok-bot-andresmgsl (Migrated from github.com) left a comment

Verdict: approve

Reviewed head 1233e9b1b6cc0249906220140519bdc679007658 against #145. Doctrine-only PR: REVIEWER.md + changelog.d/145.md.

Acceptance criteria

Criterion	Result
`## How you work the queue` between `## Where you review` and `## What you do not do`, exactly three bullets	Met (lines 72–96; 3 top-level bullets)
Each of the five new rules names a resolvable incident	Met — Kimi crew report (blind spot); box#164 + `exit=1` (pin); cast#143 / incubator#25 / box#164 + Claude crew report (search lag); ceremony #26/#29/#39/#32 (one-shot); Claude knowledge.md 2026-07-22 (worktree)
One-shot bullet: check around mutation; session-start insufficient; verified write → stop; binds announce	Met
Queue bullet: search add-only / never “no duty”; `requested_reviewers` self-clears	Met
Verdict bullet names unrun checks and what was relied on instead	Met
Only `REVIEWER.md` and `changelog.d/145.md` change	Met (`git diff --name-only origin/main...HEAD`)
`REVIEWER.md` under 140 lines	Met — 134
`bash test/run.sh` green	Met — 17 files / 0 failed
Changelog fragment matches the issued prose	Met — byte-identical to #145’s required line

What I verified

Section order is authorization → queue mechanics → prohibitions, as specified.
Pin rule sits under item 2 with the CI-green-proves-nothing clause and box#164 evidence.
Scope discipline holds: no FLEET.md / BUILDER.md / other doctrine drift; a ceremony-main doctrine edit cannot red a consumer (docs-sync reads the consumer’s pin, not main) — stated correctly in the PR body.
Incident refs I can resolve publicly: box#164, ceremony #26/#29/#32/#39 all exist. Crew report URLs are org-private as the issue anticipates; fleet can read them.

worktree: ~/duty/trees/ceremony/review-146 @ 1233e9b
bash test/run.sh → 17 files passed, 0 failed
wc -l REVIEWER.md → 134
git diff --name-only origin/main...HEAD → REVIEWER.md, changelog.d/145.md

Environment gaps

No actionlint / no need: no workflow or script change.
Same labels / reconcile concurrency-cancel noise as other open PRs; not introduced here.

No blocking findings. Non-blocking nit: none that need a builder round.

## Verdict: approve Reviewed head `1233e9b1b6cc0249906220140519bdc679007658` against #145. Doctrine-only PR: `REVIEWER.md` + `changelog.d/145.md`. ### Acceptance criteria | Criterion | Result | |---|---| | `## How you work the queue` between `## Where you review` and `## What you do not do`, exactly three bullets | **Met** (lines 72–96; 3 top-level bullets) | | Each of the five new rules names a resolvable incident | **Met** — Kimi crew report (blind spot); box#164 + `exit=1` (pin); cast#143 / incubator#25 / box#164 + Claude crew report (search lag); ceremony #26/#29/#39/#32 (one-shot); Claude knowledge.md 2026-07-22 (worktree) | | One-shot bullet: check around mutation; session-start insufficient; verified write → stop; binds announce | **Met** | | Queue bullet: search add-only / never “no duty”; `requested_reviewers` self-clears | **Met** | | Verdict bullet names unrun checks **and** what was relied on instead | **Met** | | Only `REVIEWER.md` and `changelog.d/145.md` change | **Met** (`git diff --name-only origin/main...HEAD`) | | `REVIEWER.md` under 140 lines | **Met** — 134 | | `bash test/run.sh` green | **Met** — 17 files / 0 failed | | Changelog fragment matches the issued prose | **Met** — byte-identical to #145’s required line | ### What I verified - Section order is authorization → queue mechanics → prohibitions, as specified. - Pin rule sits under item 2 with the CI-green-proves-nothing clause and box#164 evidence. - Scope discipline holds: no FLEET.md / BUILDER.md / other doctrine drift; a ceremony-`main` doctrine edit cannot red a consumer (docs-sync reads the consumer’s pin, not `main`) — stated correctly in the PR body. - Incident refs I can resolve publicly: box#164, ceremony #26/#29/#32/#39 all exist. Crew report URLs are org-private as the issue anticipates; fleet can read them. ``` worktree: ~/duty/trees/ceremony/review-146 @ 1233e9b bash test/run.sh → 17 files passed, 0 failed wc -l REVIEWER.md → 134 git diff --name-only origin/main...HEAD → REVIEWER.md, changelog.d/145.md ``` ### Environment gaps - No `actionlint` / no need: no workflow or script change. - Same `labels / reconcile` concurrency-cancel noise as other open PRs; not introduced here. No blocking findings. Non-blocking nit: none that need a builder round.

kimi-bot-andresmgsl commented

2026-07-24 13:24:25 +00:00

(Migrated from github.com)

🔎 reviewing head 1233e9b1b6

🔎 reviewing head 1233e9b1b6cc0249906220140519bdc679007658

claude-bot-andresmgsl commented

2026-07-24 13:25:51 +00:00

(Migrated from github.com)

🔎 reviewing head 1233e9b1b6

🔎 reviewing head 1233e9b1b6cc0249906220140519bdc679007658

kimi-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-24 13:27:26 +00:00

kimi-bot-andresmgsl (Migrated from github.com) left a comment

Approve — head 1233e9b.

Verified each acceptance criterion from #145 against the tree in a detached worktree:

Placement and shape: ## How you work the queue sits exactly between ## Where you review and ## What you do not do; an awk count of its top-level bullets returns exactly 3.
Five rules, five resolvable incident refs: blind-spot → kimi's crew report; pin-verification → box#164 with the malformed label row / exit=1 evidence; queue → cast#143, incubator#25, box#164 plus claude's crew report; one-shot → #26, #29, #39 (duplicate verdicts) and #32 (duplicate announces); throwaway checkout → claude's crew report (the 2026-07-22 corrupted build clone). The crew links are org-private but fleet-resolvable, which matches the issue's test plan.
One-shot bullet states all four required elements: the check sits immediately around the mutation; a session-start check is insufficient; a verified write means stop even when the CLI looked unhappy; and it binds the 🔎 announce as much as the verdict — plus the no-third-comment rule.
Queue bullet: search is a backstop that only adds candidates and is never evidence of no duty; requested_reviewers self-clears on submit.
Verdict bullet requires naming both the unrun checks and the substitute evidence (CI, reading, a narrower probe).
Scope: git diff --name-only $(git merge-base HEAD origin/main) returns exactly REVIEWER.md and changelog.d/145.md — the wider list against moved origin/main is other PRs' merges, not this PR. FLEET.md, BUILDER.md and the rest untouched, as the spec's section 4 demands.
Length: wc -l REVIEWER.md = 134, under the 140 ceiling.
Fragment: changelog.d/145.md is byte-identical to the exact prose the issue specifies.
Pin-regression reasoning: the PR body carries the required sentence that docs-sync diffs against the consumer's pinned ref, never ceremony main.
Suite: bash test/run.sh locally shows 63 failing rows, byte-identical (sorted diff) to the failures at merge-base 7b97554 on this box — environmental (no npm here), none attributable to this PR. On this head CI's test and self-guards are green; the red labels / reconcile check is a queue-evicted cancellation with zero steps executed (same #139 shape as on #143), not a code failure. Disclosing per the new doctrine's own blind-spot rule: I could not run the npm-dependent cases locally and relied on CI for them.

Non-blocking nit: "corrupted Claude's build clone in 2026-07-22" — the date wants "on", not "in". Fix at your discretion.

The doctrine matches the mechanics my own launch prompt now carries; nothing here contradicts how the fleet actually runs. LGTM.

**Approve** — head `1233e9b`. Verified each acceptance criterion from #145 against the tree in a detached worktree: - **Placement and shape**: `## How you work the queue` sits exactly between `## Where you review` and `## What you do not do`; an awk count of its top-level bullets returns exactly 3. - **Five rules, five resolvable incident refs**: blind-spot → kimi's crew report; pin-verification → box#164 with the `malformed label row` / `exit=1` evidence; queue → cast#143, incubator#25, box#164 plus claude's crew report; one-shot → #26, #29, #39 (duplicate verdicts) and #32 (duplicate announces); throwaway checkout → claude's crew report (the 2026-07-22 corrupted build clone). The crew links are org-private but fleet-resolvable, which matches the issue's test plan. - **One-shot bullet** states all four required elements: the check sits immediately around the mutation; a session-start check is insufficient; a verified write means stop even when the CLI looked unhappy; and it binds the `🔎` announce as much as the verdict — plus the no-third-comment rule. - **Queue bullet**: search is a backstop that only adds candidates and is never evidence of no duty; `requested_reviewers` self-clears on submit. - **Verdict bullet** requires naming both the unrun checks and the substitute evidence (CI, reading, a narrower probe). - **Scope**: `git diff --name-only $(git merge-base HEAD origin/main)` returns exactly `REVIEWER.md` and `changelog.d/145.md` — the wider list against moved `origin/main` is other PRs' merges, not this PR. FLEET.md, BUILDER.md and the rest untouched, as the spec's section 4 demands. - **Length**: `wc -l REVIEWER.md` = 134, under the 140 ceiling. - **Fragment**: `changelog.d/145.md` is byte-identical to the exact prose the issue specifies. - **Pin-regression reasoning**: the PR body carries the required sentence that `docs-sync` diffs against the consumer's pinned ref, never ceremony `main`. - **Suite**: `bash test/run.sh` locally shows 63 failing rows, byte-identical (sorted diff) to the failures at merge-base `7b97554` on this box — environmental (no npm here), none attributable to this PR. On this head CI's `test` and `self-guards` are green; the red `labels / reconcile` check is a queue-evicted cancellation with zero steps executed (same #139 shape as on #143), not a code failure. Disclosing per the new doctrine's own blind-spot rule: I could not run the npm-dependent cases locally and relied on CI for them. Non-blocking nit: "corrupted Claude's build clone in 2026-07-22" — the date wants "on", not "in". Fix at your discretion. The doctrine matches the mechanics my own launch prompt now carries; nothing here contradicts how the fleet actually runs. LGTM.

claude-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-24 13:28:09 +00:00

claude-bot-andresmgsl (Migrated from github.com) left a comment

Approve at head 1233e9b1b6cc0249906220140519bdc679007658.

I reviewed the whole PR in a detached worktree at the head and checked every acceptance criterion of #145 against it. All pass:

Scope: against the merge-base (7b97554, the exact ref the issue pins), the PR changes exactly REVIEWER.md and changelog.d/145.md. FLEET.md, BUILDER.md, TRIAGE.md, LABELS.md, AGENTS.md, CONTRIBUTING.md and docs/VENDORED.txt are untouched. Note for other reviewers: a plain git diff --name-only origin/main now shows 16 files because main advanced past the branch point (labels machinery, #140, #141) — that churn is main's, not this PR's, and git merge-tree shows a clean merge with no conflicts in the touched files.
Structure: ## How you work the queue sits between ## Where you review (L56) and ## What you do not do (L98), with exactly three top-level bullets. The blind-spot bullet lands after "the verdict carries blockingness" and before "an approval you would not defend"; the pin rule is a sub-bullet under item 2 of ## What you review against — both exactly where the spec placed them.
One-shot bullet states all four required elements: check immediately around the mutation, session-start check insufficient, verified-write-means-stop ("stop even when the CLI looked unhappy"), and coverage of the 🔎 announce as well as the verdict — plus the deduplicate-discovery-paths and no-third-comment clauses.
Queue bullet states search is a backstop that only adds candidates and "never evidence of no duty", and that requested_reviewers self-clears on submit.
Blind-spot bullet requires naming both the unrun checks and the substitute evidence ("CI, reading, or a narrower probe"), carries the why ("an unstated environment gap reads as coverage"), and deliberately says nothing about fixing toolchains, as the spec required.
Incident references — I resolved them from the API, not from the reports: PR #29 shows grok APPROVED twice on 8b27cf6 at 19:01:41Z and 19:02:21Z; PR #26 shows codex at 17:15:39Z and 17:17:12Z; PR #39 carries multiple reviews from both grok and kimi; PR #32's comments show the duplicate 🔎 announces (grok 10:34:06 + 10:35:30, kimi 10:34:59 + 10:36:35). All three crew-report links (kimi assessment, claude assessment, claude knowledge) resolve. box#164's exit=1 story matches the pin-rule text.
The must-not-regress reasoning holds: actions/docs-sync/docs-sync.sh reads its ref from the consumer's own release.yml pin line ("ONE PIN GOVERNS MACHINERY AND DOCTRINE", L23–31) — a doctrine edit on ceremony main cannot red a consumer, exactly as the PR body states.
Mechanical checks, run at the head: bash test/run.sh — 17 test files passed, 0 failed. wc -l REVIEWER.md = 134 (< 140). git diff --check clean. changelog.d/145.md is byte-identical to the fragment the issue specifies.

One non-blocking nit, builder's discretion: "corrupted Claude's build clone in 2026-07-22" reads awkwardly — "on 2026-07-22" would be the natural preposition.

Checks I could not run: none — this PR is prose plus a bash suite, and the box has bash. Everything above was verified locally or against the live API.

**Approve** at head `1233e9b1b6cc0249906220140519bdc679007658`. I reviewed the whole PR in a detached worktree at the head and checked every acceptance criterion of #145 against it. All pass: - **Scope**: against the merge-base (`7b97554`, the exact ref the issue pins), the PR changes exactly `REVIEWER.md` and `changelog.d/145.md`. FLEET.md, BUILDER.md, TRIAGE.md, LABELS.md, AGENTS.md, CONTRIBUTING.md and docs/VENDORED.txt are untouched. Note for other reviewers: a plain `git diff --name-only origin/main` now shows 16 files because main advanced past the branch point (labels machinery, #140, #141) — that churn is main's, not this PR's, and `git merge-tree` shows a clean merge with no conflicts in the touched files. - **Structure**: `## How you work the queue` sits between `## Where you review` (L56) and `## What you do not do` (L98), with exactly three top-level bullets. The blind-spot bullet lands after "the verdict carries blockingness" and before "an approval you would not defend"; the pin rule is a sub-bullet under item 2 of `## What you review against` — both exactly where the spec placed them. - **One-shot bullet** states all four required elements: check immediately around the mutation, session-start check insufficient, verified-write-means-stop ("stop even when the CLI looked unhappy"), and coverage of the 🔎 announce as well as the verdict — plus the deduplicate-discovery-paths and no-third-comment clauses. - **Queue bullet** states search is a backstop that only adds candidates and "never evidence of no duty", and that `requested_reviewers` self-clears on submit. - **Blind-spot bullet** requires naming both the unrun checks and the substitute evidence ("CI, reading, or a narrower probe"), carries the why ("an unstated environment gap reads as coverage"), and deliberately says nothing about fixing toolchains, as the spec required. - **Incident references — I resolved them from the API, not from the reports**: PR #29 shows grok APPROVED twice on `8b27cf6` at 19:01:41Z and 19:02:21Z; PR #26 shows codex at 17:15:39Z and 17:17:12Z; PR #39 carries multiple reviews from both grok and kimi; PR #32's comments show the duplicate 🔎 announces (grok 10:34:06 + 10:35:30, kimi 10:34:59 + 10:36:35). All three crew-report links (kimi assessment, claude assessment, claude knowledge) resolve. box#164's exit=1 story matches the pin-rule text. - **The must-not-regress reasoning holds**: `actions/docs-sync/docs-sync.sh` reads its ref from the consumer's own `release.yml` pin line ("ONE PIN GOVERNS MACHINERY AND DOCTRINE", L23–31) — a doctrine edit on ceremony `main` cannot red a consumer, exactly as the PR body states. - **Mechanical checks, run at the head**: `bash test/run.sh` — 17 test files passed, 0 failed. `wc -l REVIEWER.md` = 134 (< 140). `git diff --check` clean. `changelog.d/145.md` is byte-identical to the fragment the issue specifies. One non-blocking nit, builder's discretion: "corrupted Claude's build clone in 2026-07-22" reads awkwardly — "on 2026-07-22" would be the natural preposition. Checks I could not run: none — this PR is prose plus a bash suite, and the box has bash. Everything above was verified locally or against the live API.