heavy-duty/ceremony

Fork 2

docs: a post-merge acceptance criterion rides Refs #N — triage closes on the evidence #152

Merged

claude-bot-andresmgsl merged 1 commit from build/151-refs-not-closes into main

2026-07-24 14:27:43 +00:00

claude-bot-andresmgsl commented

2026-07-24 13:48:55 +00:00

(Migrated from github.com)

Closes #151

Merging #143 auto-closed #137 with its post-merge criterion unmet: the PR carried Closes #137 as doctrine required, the criterion (a live proof of a pull_request_target trigger, which resolves from the base branch) could only be checked after the merge, and the contract was silent — the same keyword-vs-close-authority disagreement the cross-repo carve-out already resolved, one case over. Triage reopened #137 by hand and minted this issue. (This PR's own criteria are all pre-merge-checkable, so Closes #151 is the correct default here — the exception doesn't apply to the PR that writes it down.)

What this PR does — prose only, four docs and one fragment, per D5 no script/workflow/test/label changes:

D1, BUILDER.md — the second exception sits beside the cross-repo one in the Building bullet, in its shape and voice: when the issue body marks a criterion post-merge, the same-repo PR uses Refs #N, triage closes by hand on the evidence, the builder never judges which issues qualify, and Closes #N stays the default. The #143/#137 incident is named as the why.
D2, TRIAGE.md — the issue contract's acceptance-criteria bullet now requires a post-merge criterion to carry its own mechanism: named post-merge, triage owns the close, Refs #N names the reference. #137's amended body is cited as the worked example.
D3, REVIEWER.md — Refs #N joins Closes #N and Part of <owner>/<repo>#N in the first authority, with the not-a-defect sentence: request-changes on the "missing" keyword enforces the bug the shape fixes.
D4, CONTRIBUTING.md — step 1 gets one pointer clause ("its exceptions … live in BUILDER.md") and no restatement; one rule, one home, three pointers.

Test evidence

bash test/run.sh — 18 files, all green (unchanged behaviour; proves nothing under test/, actions/, lib/ or .github/workflows/ was dragged in — the diff is exactly the four docs plus changelog.d/151.md).
bash .github/scripts/shellcheck-all.sh — clean.
Read-order check (CONTRIBUTING → BUILDER → the issue → REVIEWER): CONTRIBUTING points, BUILDER states, TRIAGE obligates the author, REVIEWER de-fangs the false positive — no two files restate the rule.
#137's amended criterion re-read against the new TRIAGE.md text: it names itself post-merge, names triage as closer, and asks for Refs #137 — a compliant example now, not a special case.

Acceptance criteria

BUILDER.md states that a same-repo PR uses Refs #N when the issue's body says a criterion is post-merge, and that triage closes those issues by hand.
TRIAGE.md requires a post-merge criterion to name itself as post-merge, name triage as the closer, and name the Refs #N reference.
REVIEWER.md lists Refs #N alongside Closes #N and Part of <owner>/<repo>#N, and says a reference-only PR is not a defect in this case.
CONTRIBUTING.md points at BUILDER.md for the exceptions and does not duplicate the rule; Closes #N is still the default in all four files.
No script, workflow or test is changed — the diff is four docs and one fragment.
The full local suite and shellcheck are green.

Worklog

Read the spec and the four target regions at main (identical to the pinned 6a16a30 in all four spots)
D1: BUILDER.md second exception
D2: TRIAGE.md criterion-owns-its-mechanism
D3: REVIEWER.md authority list + not-a-defect
D4: CONTRIBUTING.md pointer clause
changelog.d/151.md
Suite + shellcheck green; diff scope verified
CI green on the draft
Mark ready-for-review, request the panel (codex, grok, kimi)

Closes #151 Merging #143 auto-closed #137 with its post-merge criterion unmet: the PR carried `Closes #137` as doctrine required, the criterion (a live proof of a `pull_request_target` trigger, which resolves from the base branch) could only be checked after the merge, and the contract was silent — the same keyword-vs-close-authority disagreement the cross-repo carve-out already resolved, one case over. Triage reopened #137 by hand and minted this issue. (This PR's own criteria are all pre-merge-checkable, so `Closes #151` is the correct default here — the exception doesn't apply to the PR that writes it down.) **What this PR does** — prose only, four docs and one fragment, per D5 no script/workflow/test/label changes: - **D1, `BUILDER.md`** — the second exception sits beside the cross-repo one in the Building bullet, in its shape and voice: when the issue body marks a criterion post-merge, the same-repo PR uses `Refs #N`, triage closes by hand on the evidence, the builder never judges which issues qualify, and `Closes #N` stays the default. The #143/#137 incident is named as the why. - **D2, `TRIAGE.md`** — the issue contract's acceptance-criteria bullet now requires a post-merge criterion to carry its own mechanism: named post-merge, triage owns the close, `Refs #N` names the reference. #137's amended body is cited as the worked example. - **D3, `REVIEWER.md`** — `Refs #N` joins `Closes #N` and `Part of <owner>/<repo>#N` in the first authority, with the not-a-defect sentence: request-changes on the "missing" keyword enforces the bug the shape fixes. - **D4, `CONTRIBUTING.md`** — step 1 gets one pointer clause ("its exceptions … live in BUILDER.md") and no restatement; one rule, one home, three pointers. **Test evidence** - `bash test/run.sh` — 18 files, all green (unchanged behaviour; proves nothing under `test/`, `actions/`, `lib/` or `.github/workflows/` was dragged in — the diff is exactly the four docs plus `changelog.d/151.md`). - `bash .github/scripts/shellcheck-all.sh` — clean. - Read-order check (CONTRIBUTING → BUILDER → the issue → REVIEWER): CONTRIBUTING points, BUILDER states, TRIAGE obligates the author, REVIEWER de-fangs the false positive — no two files restate the rule. - #137's amended criterion re-read against the new TRIAGE.md text: it names itself post-merge, names triage as closer, and asks for `Refs #137` — a compliant example now, not a special case. ## Acceptance criteria - [x] `BUILDER.md` states that a same-repo PR uses `Refs #N` when the issue's body says a criterion is post-merge, and that triage closes those issues by hand. - [x] `TRIAGE.md` requires a post-merge criterion to name itself as post-merge, name triage as the closer, and name the `Refs #N` reference. - [x] `REVIEWER.md` lists `Refs #N` alongside `Closes #N` and `Part of <owner>/<repo>#N`, and says a reference-only PR is not a defect in this case. - [x] `CONTRIBUTING.md` points at BUILDER.md for the exceptions and does not duplicate the rule; `Closes #N` is still the default in all four files. - [x] No script, workflow or test is changed — the diff is four docs and one fragment. - [x] The full local suite and shellcheck are green. ## Worklog - [x] Read the spec and the four target regions at main (identical to the pinned `6a16a30` in all four spots) - [x] D1: BUILDER.md second exception - [x] D2: TRIAGE.md criterion-owns-its-mechanism - [x] D3: REVIEWER.md authority list + not-a-defect - [x] D4: CONTRIBUTING.md pointer clause - [x] `changelog.d/151.md` - [x] Suite + shellcheck green; diff scope verified - [x] CI green on the draft - [x] Mark ready-for-review, request the panel (codex, grok, kimi)

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

claude-bot-andresmgsl commented

2026-07-24 13:54:08 +00:00

(Migrated from github.com)

⟲ resuming from b3b9830700

⟲ resuming from b3b983070055749d0d8ba71e63a76e1b78139804

grok-bot-andresmgsl commented

2026-07-24 13:55:48 +00:00

(Migrated from github.com)

🔎 reviewing head b3b9830700

🔎 reviewing head b3b983070055749d0d8ba71e63a76e1b78139804

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

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

Verdict: approve

Reviewed head b3b983070055749d0d8ba71e63a76e1b78139804 against #151 (D1–D5 and the six acceptance criteria). On-panel (author is claude-bot-andresmgsl).

Acceptance criteria

Criterion	Result
BUILDER.md: same-repo `Refs #N` when the issue body marks a criterion post-merge; triage closes by hand	met — sits beside the cross-repo carve-out, same shape/voice; builder does not judge; `Closes #N` remains the default; #143/#137/#151 named as the why
TRIAGE.md: post-merge criterion must name itself post-merge, triage as closer, and `Refs #N`	met — three obligations live in the criterion itself; #137 amended body cited as the worked example
REVIEWER.md: `Refs #N` listed with `Closes #N` / `Part of …`; reference-only is not a defect	met — authority list extended; not-a-defect sentence blocks the false-positive request-changes
CONTRIBUTING.md: pointer only, no restatement; `Closes #N` still the default in all four files	met — one clause naming both exceptions and linking BUILDER.md
Diff is four docs + one fragment (D5)	met — `BUILDER.md`, `TRIAGE.md`, `REVIEWER.md`, `CONTRIBUTING.md`, `changelog.d/151.md` only
Full suite + shellcheck green	met — ran in detached worktree at this head: `bash test/run.sh` → 18 files, all green; `bash .github/scripts/shellcheck-all.sh` clean. CI `test` / `self-guards` also green

Read-order / #137 check

CONTRIBUTING points → BUILDER states the rule once → TRIAGE obligates the issue author → REVIEWER de-fangs the keyword false positive. One home, three pointers. #137's post-merge criterion already names itself post-merge, names triage as closer, and asks for Refs #137 — it is a compliant example under the new TRIAGE text, not a special case.

This PR correctly uses Closes #151 (all criteria pre-merge checkable); the exception it writes down does not apply to itself.

No blocking findings. Non-blocking: none worth tracking.

Approve.

## Verdict: approve Reviewed head `b3b983070055749d0d8ba71e63a76e1b78139804` against #151 (D1–D5 and the six acceptance criteria). On-panel (author is `claude-bot-andresmgsl`). ### Acceptance criteria | Criterion | Result | |---|---| | BUILDER.md: same-repo `Refs #N` when the issue body marks a criterion post-merge; triage closes by hand | **met** — sits beside the cross-repo carve-out, same shape/voice; builder does not judge; `Closes #N` remains the default; #143/#137/#151 named as the why | | TRIAGE.md: post-merge criterion must name itself post-merge, triage as closer, and `Refs #N` | **met** — three obligations live in the criterion itself; #137 amended body cited as the worked example | | REVIEWER.md: `Refs #N` listed with `Closes #N` / `Part of …`; reference-only is not a defect | **met** — authority list extended; not-a-defect sentence blocks the false-positive request-changes | | CONTRIBUTING.md: pointer only, no restatement; `Closes #N` still the default in all four files | **met** — one clause naming both exceptions and linking BUILDER.md | | Diff is four docs + one fragment (D5) | **met** — `BUILDER.md`, `TRIAGE.md`, `REVIEWER.md`, `CONTRIBUTING.md`, `changelog.d/151.md` only | | Full suite + shellcheck green | **met** — ran in detached worktree at this head: `bash test/run.sh` → 18 files, all green; `bash .github/scripts/shellcheck-all.sh` clean. CI `test` / `self-guards` also green | ### Read-order / #137 check CONTRIBUTING points → BUILDER states the rule once → TRIAGE obligates the issue author → REVIEWER de-fangs the keyword false positive. One home, three pointers. #137's post-merge criterion already names itself post-merge, names triage as closer, and asks for `Refs #137` — it is a compliant example under the new TRIAGE text, not a special case. This PR correctly uses `Closes #151` (all criteria pre-merge checkable); the exception it writes down does not apply to itself. No blocking findings. Non-blocking: none worth tracking. Approve.

codex-bot-andresmgsl commented

2026-07-24 14:00:47 +00:00

(Migrated from github.com)

🔎 reviewing head b3b9830700

🔎 reviewing head b3b983070055749d0d8ba71e63a76e1b78139804

codex-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-24 14:02:00 +00:00

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

All acceptance criteria are met at b3b983070055749d0d8ba71e63a76e1b78139804.

The four doctrine changes preserve Closes #N as the default while defining the issue-directed Refs #N exception consistently: BUILDER owns the rule, TRIAGE requires the criterion to carry its mechanism, REVIEWER recognizes the reference as authoritative, and CONTRIBUTING only points to BUILDER. The changed-path set is exactly those four documents plus changelog.d/151.md; no machinery or tests changed. I also checked the amended #137 criterion and it satisfies the new TRIAGE contract.

Verified locally:

bash test/run.sh — 18 test files passed, 0 failed (the existing yq-dependent cases were skipped because yq is unavailable)
bash .github/scripts/shellcheck-all.sh — clean across 39 tracked scripts
git diff --check e8675548ce34a4b38007ab5d6fd035aac382af73...HEAD — clean

Current CI reports the test, self-guards, action exercise, docs-sync exercise, fixture-chain, both step replays, and label reconciliation checks successful.

All acceptance criteria are met at `b3b983070055749d0d8ba71e63a76e1b78139804`. The four doctrine changes preserve `Closes #N` as the default while defining the issue-directed `Refs #N` exception consistently: BUILDER owns the rule, TRIAGE requires the criterion to carry its mechanism, REVIEWER recognizes the reference as authoritative, and CONTRIBUTING only points to BUILDER. The changed-path set is exactly those four documents plus `changelog.d/151.md`; no machinery or tests changed. I also checked the amended #137 criterion and it satisfies the new TRIAGE contract. Verified locally: - `bash test/run.sh` — 18 test files passed, 0 failed (the existing `yq`-dependent cases were skipped because `yq` is unavailable) - `bash .github/scripts/shellcheck-all.sh` — clean across 39 tracked scripts - `git diff --check e8675548ce34a4b38007ab5d6fd035aac382af73...HEAD` — clean Current CI reports the test, self-guards, action exercise, docs-sync exercise, fixture-chain, both step replays, and label reconciliation checks successful.

kimi-bot-andresmgsl commented

2026-07-24 14:08:09 +00:00

(Migrated from github.com)

🔎 reviewing head b3b9830700

🔎 reviewing head b3b983070055749d0d8ba71e63a76e1b78139804

kimi-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-24 14:11:50 +00:00

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

Approve — head b3b983070055749d0d8ba71e63a76e1b78139804.

Reviewed against #151's acceptance criteria, all met:

BUILDER.md — the second exception sits beside the cross-repo one in the Building bullet: issue-body-marked post-merge criterion → Refs #N, triage closes by hand on the evidence, builder never judges which issues qualify, Closes #N remains the default, #143/#137 named as the why. ✓
TRIAGE.md — the issue contract now requires a post-merge criterion to name itself post-merge, name triage as the closer, and name the Refs #N reference; #137's amended body cited as the worked example. ✓ I re-read #137's amended criterion against this text — it names all three ("Post-merge, not on this PR", "Triage keeps #137 open past the merge and closes on this evidence", "Refs #137, not Closes #137"), so it is now a compliant example, not a special case. ✓
REVIEWER.md — Refs #N joins Closes #N and Part of <owner>/<repo>#N in the first authority, with the not-a-defect sentence and the incident citation. ✓
CONTRIBUTING.md — step 1 gets one pointer clause ("its exceptions … live in BUILDER.md"), no restatement; Closes #N stays the default in all four files. ✓ One rule, one home, three pointers — reading the four files in builder order (CONTRIBUTING → BUILDER → issue → REVIEWER) shows no duplicated statement that can drift.
D5 scope — the diff is exactly four docs plus changelog.d/151.md; nothing under test/, actions/, lib/, or .github/ was touched. ✓
Fragment changelog.d/151.md exists; the ### Changed heading matches the convention already used by 135.md/137.md. ✓

Environment gaps, named per doctrine: this box has no node, shellcheck, yq, or npm. shellcheck-all.sh therefore could not run at all (shellcheck: command not found), and bash test/run.sh reports 7 failing files (package-json version cases, ruling/offsite sweeps) in both a detached worktree of this head and a detached worktree of origin/main (9e960f8) — the sorted FAIL/SKIP lists are byte-identical between base and head, so every failure is pre-existing/environmental and none is attributable to this PR. For a prose-only diff confined to the five files above, the base-vs-head failure-parity comparison plus direct reading of the diff is the coverage I relied on; CI is the authority on the shellcheck criterion.

Approve — head `b3b983070055749d0d8ba71e63a76e1b78139804`. Reviewed against #151's acceptance criteria, all met: - **BUILDER.md** — the second exception sits beside the cross-repo one in the Building bullet: issue-body-marked post-merge criterion → `Refs #N`, triage closes by hand on the evidence, builder never judges which issues qualify, `Closes #N` remains the default, #143/#137 named as the why. ✓ - **TRIAGE.md** — the issue contract now requires a post-merge criterion to name itself post-merge, name triage as the closer, and name the `Refs #N` reference; #137's amended body cited as the worked example. ✓ I re-read #137's amended criterion against this text — it names all three ("Post-merge, not on this PR", "Triage keeps #137 open past the merge and closes on this evidence", "`Refs #137`, not `Closes #137`"), so it is now a compliant example, not a special case. ✓ - **REVIEWER.md** — `Refs #N` joins `Closes #N` and `Part of <owner>/<repo>#N` in the first authority, with the not-a-defect sentence and the incident citation. ✓ - **CONTRIBUTING.md** — step 1 gets one pointer clause ("its exceptions … live in BUILDER.md"), no restatement; `Closes #N` stays the default in all four files. ✓ One rule, one home, three pointers — reading the four files in builder order (CONTRIBUTING → BUILDER → issue → REVIEWER) shows no duplicated statement that can drift. - **D5 scope** — the diff is exactly four docs plus `changelog.d/151.md`; nothing under `test/`, `actions/`, `lib/`, or `.github/` was touched. ✓ - Fragment `changelog.d/151.md` exists; the `### Changed` heading matches the convention already used by `135.md`/`137.md`. ✓ **Environment gaps, named per doctrine:** this box has no `node`, `shellcheck`, `yq`, or `npm`. `shellcheck-all.sh` therefore could not run at all (`shellcheck: command not found`), and `bash test/run.sh` reports 7 failing files (package-json version cases, ruling/offsite sweeps) in both a detached worktree of this head and a detached worktree of `origin/main` (`9e960f8`) — the sorted FAIL/SKIP lists are byte-identical between base and head, so every failure is pre-existing/environmental and none is attributable to this PR. For a prose-only diff confined to the five files above, the base-vs-head failure-parity comparison plus direct reading of the diff is the coverage I relied on; CI is the authority on the shellcheck criterion.

claude-bot-andresmgsl commented

2026-07-24 14:16:30 +00:00

(Migrated from github.com)

📦 Round summary — one round, unanimous, no fixes owed.

The panel was requested at 13:54:58Z on head b3b9830 — the only head this PR has ever had — and all three verdicts approve it: grok 13:56Z, codex 14:02Z, kimi 14:11Z, with no blocking or non-blocking points raised, so nothing changed post-review.

What was verified: docs-only diff (BUILDER.md, TRIAGE.md, REVIEWER.md, CONTRIBUTING.md + changelog.d/151.md), the four edits land #151's D1–D4 exactly (the Refs #N exception for post-merge criteria, triage's closer obligation, the reviewer's check, the flow note), local suite and CI green, no blocker:*. The reconciler validated state:needs-human at 14:12Z and the review request to @danmt is live — the merge is yours.

📦 Round summary — one round, unanimous, no fixes owed. The panel was requested at `13:54:58Z` on head `b3b9830` — the only head this PR has ever had — and all three verdicts approve it: grok `13:56Z`, codex `14:02Z`, kimi `14:11Z`, with no blocking or non-blocking points raised, so nothing changed post-review. What was verified: docs-only diff (BUILDER.md, TRIAGE.md, REVIEWER.md, CONTRIBUTING.md + `changelog.d/151.md`), the four edits land #151's D1–D4 exactly (the `Refs #N` exception for post-merge criteria, triage's closer obligation, the reviewer's check, the flow note), local suite and CI green, no `blocker:*`. The reconciler validated `state:needs-human` at `14:12Z` and the review request to @danmt is live — the merge is yours.