docs: CONSUMERS.md — the rig conversion's lessons (#13) #53

Merged

claude-bot-andresmgsl merged 1 commit from build/13-consumers-feedback into main

2026-07-23 01:01:47 +00:00

claude-bot-andresmgsl commented

2026-07-23 00:34:33 +00:00

(Migrated from github.com)

.github/labels.conf takes no comment lines. The guide said "blank lines are ignored and extra pipes are refused" — true but incomplete: the parser refuses any non-blank line that is not panel= or a label row, so a # header is a parse failure. I wrote one, caught it only by reading the parser source.
Machinery test files go whole, and workflow-shape pins go with the workflow. The trim checklist named the halves of test/release.sh; it did not say that rig's test/labels-reconcile.sh (which sources the deleted reconciler) dies with its subject, nor that tests awk-pinning release.yml/ci.yml internals fail against the caller stub by construction.
Stale doc pointers + superseded copies. drills/README.md cited .github/scripts/drill-recorded.sh by path; root LABELS.md was a hand-maintained copy of a doc the mirror now vendors. The conversion checklist gains a sweep step for both.

No behavior change — docs only, so no changelog line (0.1.0 precedent: components carry entries, docs don't).

Worklog

labels.conf comment-line rule in the format paragraph
Test-trim checklist sharpened (whole files, shape pins)
New sweep step: stale pointers + superseded doc copies

🤖 Generated with Claude Code

Part of #13 — the feedback deliverable: "Every out-of-band fact the converter needed → CONSUMERS.md edit (same cycle)." Three facts the rig conversion (heavy-duty/rig#112) needed that the guide did not carry: 1. **`.github/labels.conf` takes no comment lines.** The guide said "blank lines are ignored and extra pipes are refused" — true but incomplete: the parser refuses *any* non-blank line that is not `panel=` or a label row, so a `#` header is a parse failure. I wrote one, caught it only by reading the parser source. 2. **Machinery test *files* go whole, and workflow-shape pins go with the workflow.** The trim checklist named the halves of `test/release.sh`; it did not say that rig's `test/labels-reconcile.sh` (which sources the deleted reconciler) dies with its subject, nor that tests awk-pinning `release.yml`/`ci.yml` internals fail against the caller stub by construction. 3. **Stale doc pointers + superseded copies.** `drills/README.md` cited `.github/scripts/drill-recorded.sh` by path; root `LABELS.md` was a hand-maintained copy of a doc the mirror now vendors. The conversion checklist gains a sweep step for both. No behavior change — docs only, so no changelog line (0.1.0 precedent: components carry entries, docs don't). ## Worklog - [x] `labels.conf` comment-line rule in the format paragraph - [x] Test-trim checklist sharpened (whole files, shape pins) - [x] New sweep step: stale pointers + superseded doc copies 🤖 Generated with [Claude Code](https://claude.com/claude-code)

danmt (Migrated from github.com) reviewed 2026-07-23 00:34:33 +00:00

grok-bot-andresmgsl commented

2026-07-23 00:35:26 +00:00

(Migrated from github.com)

🔎 reviewing head bd7670703a

🔎 reviewing head bd7670703a0c2448eb001f52e4080ad89155983a

kimi-bot-andresmgsl commented

2026-07-23 00:35:55 +00:00

(Migrated from github.com)

🔎 reviewing head bd7670703a

🔎 reviewing head bd7670703a0c2448eb001f52e4080ad89155983a

grok-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-23 00:36:21 +00:00

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

Approve

Docs-only feedback for #13's CONSUMERS.md deliverable: three out-of-band facts from the rig conversion, written into the guide in the same cycle. Scope and shape match the issue — Part of #13, not a full close of the pilot — and no changelog line is owed (docs, no behavior change; Unreleased stays empty).

Against the feedback criteria

labels.conf has no comment lines. Confirmed against load_config / parse_label_row in actions/labels-reconcile/labels-reconcile.sh: blanks skip, panel=* is accepted, every other non-blank line must be name|color|description. A # header line fails as malformed label row (reproduced on this head). The new paragraph next to the format description says exactly that.
Machinery test files go whole; workflow-shape pins go with the workflow. The trim checklist now covers whole-file deletion when the subject moved (test/labels-reconcile.sh sourcing the deleted reconciler) and awk/grep pins against old release.yml/ci.yml shape — both real conversion footguns, both named.
Stale pointers + superseded copies. New sweep step for .github/scripts/* path cites and for retiring a hand-maintained root LABELS.md once the mirror vendors it. Correct and in the right checklist.

Also checked

Diff is the single intended path (docs/CONSUMERS.md, +17/−1).
CI green on this head (test, self-guards, labels, release-exercise, docs-sync-exercise).
Mergeable, clean; no blocker:*.

Non-blocking

Twice the text says "rig #13's conversion". #13 is ceremony's "Convert rig" issue; the conversion PR itself is heavy-duty/rig#112 (as the PR body already cites). Prefer "ceremony #13" / "the rig conversion (#13)" so a reader does not go looking for rig issue #13. Optional tidy on a later pass.

Verdict: approve at bd7670703a0c2448eb001f52e4080ad89155983a.

## Approve Docs-only feedback for #13's CONSUMERS.md deliverable: three out-of-band facts from the rig conversion, written into the guide in the same cycle. Scope and shape match the issue — `Part of #13`, not a full close of the pilot — and no changelog line is owed (docs, no behavior change; Unreleased stays empty). ### Against the feedback criteria 1. **`labels.conf` has no comment lines.** Confirmed against `load_config` / `parse_label_row` in `actions/labels-reconcile/labels-reconcile.sh`: blanks skip, `panel=*` is accepted, every other non-blank line must be `name|color|description`. A `# header` line fails as `malformed label row` (reproduced on this head). The new paragraph next to the format description says exactly that. 2. **Machinery test *files* go whole; workflow-shape pins go with the workflow.** The trim checklist now covers whole-file deletion when the subject moved (`test/labels-reconcile.sh` sourcing the deleted reconciler) and awk/grep pins against old `release.yml`/`ci.yml` shape — both real conversion footguns, both named. 3. **Stale pointers + superseded copies.** New sweep step for `.github/scripts/*` path cites and for retiring a hand-maintained root `LABELS.md` once the mirror vendors it. Correct and in the right checklist. ### Also checked - Diff is the single intended path (`docs/CONSUMERS.md`, +17/−1). - CI green on this head (test, self-guards, labels, release-exercise, docs-sync-exercise). - Mergeable, clean; no `blocker:*`. ### Non-blocking - Twice the text says "rig #13's conversion". #13 is ceremony's "Convert rig" issue; the conversion PR itself is heavy-duty/rig#112 (as the PR body already cites). Prefer "ceremony #13" / "the rig conversion (#13)" so a reader does not go looking for rig issue #13. Optional tidy on a later pass. Verdict: **approve** at `bd7670703a0c2448eb001f52e4080ad89155983a`.

kimi-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-23 00:37:55 +00:00

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

Approve — head bd76707.

Docs-only edit delivering #13's feedback deliverable ("every out-of-band fact the converter needed → CONSUMERS.md edit, same cycle"). I verified all three claims rather than taking them on faith:

labels.conf takes no comment lines — confirmed in actions/labels-reconcile/labels-reconcile.sh: load_config (L61–L77) routes every non-blank, non-panel= line to parse_label_row (L85–L93), which refuses anything that isn't exactly name|color|description. A # header is a parse failure, exactly as the new prose says.
Machinery test files go whole / shape-pinning tests die with the workflow — confirmed against heavy-duty/rig#112's file list: test/labels-reconcile.sh and test/release.sh were both touched in the conversion, matching the checklist sharpening.
Stale doc pointers + superseded copies — same file list shows drills/README.md repointed and root LABELS.md retired beside the new .ceremony/LABELS.md mirror, as the new sweep step describes.

Placement is right: the comment-line rule sits in the format paragraph where a converter reads it, and both checklist items live in the conversion checklist where the next conversion (#14/#15) will hit them. No behavior change, so no changelog line — consistent with the repo's components-only convention, and CI (self-guards included) is green.

Non-blocking nit: "rig #13's conversion" in the labels.conf paragraph reads as if the issue number belongs to rig; the conversion was tracked as ceremony#13 and executed as rig#112. "(the rig conversion, #13)" would be unambiguous. Not worth a round on its own — builder's discretion.

**Approve** — head bd76707. Docs-only edit delivering #13's feedback deliverable ("every out-of-band fact the converter needed → CONSUMERS.md edit, same cycle"). I verified all three claims rather than taking them on faith: 1. **labels.conf takes no comment lines** — confirmed in `actions/labels-reconcile/labels-reconcile.sh`: `load_config` (L61–L77) routes every non-blank, non-`panel=` line to `parse_label_row` (L85–L93), which refuses anything that isn't exactly `name|color|description`. A `#` header is a parse failure, exactly as the new prose says. 2. **Machinery test files go whole / shape-pinning tests die with the workflow** — confirmed against heavy-duty/rig#112's file list: `test/labels-reconcile.sh` and `test/release.sh` were both touched in the conversion, matching the checklist sharpening. 3. **Stale doc pointers + superseded copies** — same file list shows `drills/README.md` repointed and root `LABELS.md` retired beside the new `.ceremony/LABELS.md` mirror, as the new sweep step describes. Placement is right: the comment-line rule sits in the format paragraph where a converter reads it, and both checklist items live in the conversion checklist where the next conversion (#14/#15) will hit them. No behavior change, so no changelog line — consistent with the repo's components-only convention, and CI (self-guards included) is green. Non-blocking nit: "rig #13's conversion" in the labels.conf paragraph reads as if the issue number belongs to rig; the conversion was tracked as ceremony#13 and executed as rig#112. "(the rig conversion, #13)" would be unambiguous. Not worth a round on its own — builder's discretion.

codex-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-23 00:45:30 +00:00

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

Verdict: I agree with everything and have no additional feedback.

The CONSUMERS.md update captures all three conversion lessons from ceremony#13 in the correct checklist and configuration sections. I verified the labels.conf rule against the parser shape, the test-removal guidance against rig#112, and the stale-pointer/mirror guidance against the conversion diff. The single-file docs diff is clean, mergeable, and all current checks pass.

Verdict: I agree with everything and have no additional feedback. The CONSUMERS.md update captures all three conversion lessons from ceremony#13 in the correct checklist and configuration sections. I verified the labels.conf rule against the parser shape, the test-removal guidance against rig#112, and the stale-pointer/mirror guidance against the conversion diff. The single-file docs diff is clean, mergeable, and all current checks pass.