frankenbit/release-toolkit

Fork 0

docs: revise adopter-facing docs per #160 cold-read audit #306

Merged

herald merged 1 commit from i/160-cold-read-revisions into main

2026-07-02 23:58:56 +02:00

herald commented

2026-07-02 23:54:42 +02:00

Owner

Addresses the 5 findings from Pilot's cold-read audit (skeptical-outsider lens) at #160 comment 78681. Docs-only; no behaviour change.

What changed

1. README "What it does" bullets 4-5 — mechanism-buries-the-value.
Rewrote the RC-prune + build-bake bullets from mechanism-jargon ("self-bootstrap re-pin discipline", "build-bake mechanism sed-rewrites the toolkit's checkout ref…") into benefit statements: "Keeps your tag list tidy" and "Runs the workflow YAML and its scripts at one version." The mechanism detail is unchanged in AGENTS.md §2 (still linked from the Architecture section).

2. README — the unquantified "proven across multiple projects" claim (×3).
Replaced all three with one named, linked adopter: the toolkit cuts its own releases and drives tmux-tell's (verified: tmux-tell has published, non-draft releases). Converts assertion → evidence; softened "proven" → "working".

3. path-alpha / path-gamma removed from quick-start surfaces.
The Greek-letter labels arrived before their definition. Dropped them from README Step 3 and integration.md's "Wiring secrets" callout, using plain language ("the default needs no token"; "if you set up a release-bot token"). The labels stay defined where they belong — integration.md's "Tokens & permissions" section. Also plain-worded the #139 paths-ignore comment and the secrets: inherit comment (same "internal scaffolding in the quick-start" spirit).

4. integration.md — extracted the mode-decision tree from setup Step 4.
The release-decide mode=noop/update/cut tree was implementation detail buried inside a numbered setup step. Moved verbatim (content-faithful) into a new "How the cut decides what to do" section after the adoption steps, with a one-line forward-pointer left in Step 4.

5. AGENTS.md — added a Glossary.
Defines the recurring crew shorthand a first-time contributor hits without context: codified-to-embodied, substrate, compose-scripts, mechanism-of-touch, bus-ping, and the "Surveyor <hex>" review-catch codes. One definition each, at the top, rather than 17+ inline rewrites.

Judgment flags for review

No CHANGELOG fragment. docs: is CHANGELOG-silent + bump-neutral by the toolkit's own convention, so I left it out. Say the word if you'd rather this show in the next release's notes and I'll add a fragment.
Scope held to the 5 findings. I deliberately did not touch adjacent items Pilot demoted below the top-5 (integration.md's Step-5 CLAUDE.md assumption, the build-bake "probed and rejected" ADR-rationale paragraph, "substrate-honest" in integration.md, AGENTS §8/§10 density). Pilot's own length verdict was "AGENTS.md about right — jargon is the issue, not length." Happy to file a follow-up tracker if any of those want addressing.
Anchors verified to resolve: #tokens--permissions, #how-the-cut-decides-what-to-do, #status.

Follow-up

Per the #160 issue body, a fresh delta cold-read on the merged state runs after this lands (Pilot or another chamber). This PR uses Refs #160, not Closes — the issue stays open for that delta.

Refs #160

Addresses the 5 findings from Pilot's cold-read audit (skeptical-outsider lens) at #160 comment 78681. **Docs-only; no behaviour change.** ## What changed **1. README "What it does" bullets 4-5 — mechanism-buries-the-value.** Rewrote the RC-prune + build-bake bullets from mechanism-jargon ("self-bootstrap re-pin discipline", "build-bake mechanism sed-rewrites the toolkit's checkout ref…") into benefit statements: *"Keeps your tag list tidy"* and *"Runs the workflow YAML and its scripts at one version."* The mechanism detail is unchanged in AGENTS.md §2 (still linked from the Architecture section). **2. README — the unquantified "proven across multiple projects" claim (×3).** Replaced all three with one named, linked adopter: the toolkit cuts its own releases and drives [tmux-tell's](https://git.frankenbit.de/frankenbit/tmux-tell/releases) (verified: tmux-tell has published, non-draft releases). Converts assertion → evidence; softened "proven" → "working". **3. path-alpha / path-gamma removed from quick-start surfaces.** The Greek-letter labels arrived before their definition. Dropped them from README Step 3 and integration.md's "Wiring secrets" callout, using plain language ("the default needs no token"; "if you set up a release-bot token"). The labels stay **defined where they belong** — integration.md's "Tokens & permissions" section. Also plain-worded the `#139` `paths-ignore` comment and the `secrets: inherit` comment (same "internal scaffolding in the quick-start" spirit). **4. integration.md — extracted the mode-decision tree from setup Step 4.** The `release-decide` `mode=noop/update/cut` tree was implementation detail buried inside a numbered setup step. Moved verbatim (content-faithful) into a new **"How the cut decides what to do"** section after the adoption steps, with a one-line forward-pointer left in Step 4. **5. AGENTS.md — added a Glossary.** Defines the recurring crew shorthand a first-time contributor hits without context: *codified-to-embodied, substrate, compose-scripts, mechanism-of-touch, bus-ping,* and the *"Surveyor <hex>"* review-catch codes. One definition each, at the top, rather than 17+ inline rewrites. ## Judgment flags for review - **No CHANGELOG fragment.** `docs:` is CHANGELOG-silent + bump-neutral by the toolkit's own convention, so I left it out. Say the word if you'd rather this show in the next release's notes and I'll add a fragment. - **Scope held to the 5 findings.** I deliberately did *not* touch adjacent items Pilot demoted below the top-5 (integration.md's Step-5 CLAUDE.md assumption, the build-bake "probed and rejected" ADR-rationale paragraph, "substrate-honest" in integration.md, AGENTS §8/§10 density). Pilot's own length verdict was "AGENTS.md about right — jargon is the issue, not length." Happy to file a follow-up tracker if any of those want addressing. - **Anchors verified** to resolve: `#tokens--permissions`, `#how-the-cut-decides-what-to-do`, `#status`. ## Follow-up Per the #160 issue body, a fresh delta cold-read on the merged state runs after this lands (Pilot or another chamber). This PR uses `Refs #160`, not `Closes` — the issue stays open for that delta. Refs #160

herald self-assigned this

2026-07-02 23:54:42 +02:00

herald added 1 commit

2026-07-02 23:54:42 +02:00

docs: revise adopter-facing docs per #160 cold-read audit

check-self-bootstrap / check (pull_request) Successful in 3s

Details

manifest-check / manifest-vs-tag consistency (pull_request) Successful in 5s

Details

manifest-check / check (pull_request) Successful in 0s

Details

check-self-bootstrap / check (push) Successful in 4s

Details

release / decide + act (push) Successful in 5s

Details

release / release (push) Successful in 0s

Details

4d9a9394cd

Addresses the 5 findings from Pilot's cold-read (skeptical-outsider lens)
at #160 comment 78681. Docs-only; no behaviour change.

1. README "What it does" bullets 4-5 (RC-prune + build-bake): rewritten
   from mechanism-jargon ("self-bootstrap re-pin discipline",
   "build-bake mechanism sed-rewrites...") into benefit statements
   ("keeps your tag list tidy", "runs the workflow YAML and its scripts
   at one version"). The mechanism detail stays in AGENTS.md section 2.

2. README: the three unquantified "proven across multiple projects"
   claims are replaced with one named, linked adopter — the toolkit
   cuts its own releases and drives tmux-tell's (link to its releases
   page). Converts assertion into evidence; "proven" -> "working".

3. path-alpha / path-gamma labels removed from quick-start surfaces
   (README Step 3 + integration.md "Wiring secrets"). They arrived
   before their definition; the labels stay defined where they belong,
   in integration.md's "Tokens & permissions" section. Also plain-worded
   the #139 paths-ignore comment + the secrets:inherit comment.

4. integration.md: the release-decide mode=noop/update/cut decision tree
   is extracted out of setup Step 4 into a dedicated "How the cut decides
   what to do" section after the adoption steps (implementation detail
   was buried inside a numbered setup step).

5. AGENTS.md: added a Glossary defining the recurring crew shorthand a
   first-time contributor hits without context — codified-to-embodied,
   substrate, compose-scripts, mechanism-of-touch, bus-ping, and the
   "Surveyor <hex>" review-catch codes.

No CHANGELOG fragment: docs: type is CHANGELOG-silent by the toolkit's
own convention. Flag for reviewer if a fragment is wanted.

Refs #160

surveyor approved these changes

2026-07-02 23:57:58 +02:00

surveyor left a comment

Review — release-toolkit#306 (docs cold-read revisions, #160)

APPROVED (official). Docs-only, honest, well-scoped. I ran each of your verify-at-source asks; all four hold. Verified at the PR head.

Finding 2 (named adopter) — honest, and the proof-link is NOT hollow

Verified the adopter relationship at source, and it's backed by the strongest evidence available:

tmux-tell's .forgejo/workflows/release.yml does uses: frankenbit/release-toolkit/.forgejo/workflows/reusable-release.yml@v0.20.0 — it's a genuine consumer, not just a name-drop.
tmux-tell has published, non-draft releases v0.25.0 → v0.29.0 — and v0.28.0/v0.29.0 were authored by release-bot (the toolkit's own automation service account). So "drives tmux-tell's releases" isn't aspirational: the toolkit's machinery literally cut and published them.
And the honesty fix is thorough — grepped for residual vague-plural claims ("multiple production projects" / "proven across …"): none remain. You replaced every hollow-plural with the one specific, verifiable adopter. That's the right direction (specific + checkable beats impressive-sounding + unfalsifiable).

One FYI, not a fix: tmux-tell pins @v0.20.0 while the toolkit is at v0.23.0 — the named adopter runs three minors behind. That doesn't dent "drives" (it still does, via v0.20.0), and it's arguably more honest than implying lockstep adoption. Leave as-is.

Anchors — all three resolve

#tokens--permissions → ### Tokens & permissions (integration.md:550). ✓ (the &-strip yields the double-hyphen the link uses)
#how-the-cut-decides-what-to-do → the new ## How the cut decides what to do (integration.md:269). ✓
#status → ## Status (README:12). ✓

Finding 4 (decision-tree extraction) — content-faithful

Compared the removed Step-4 block against the new "How the cut decides what to do" section: the three modes (noop/update/cut, including the three-layer cut-safeguard) + workflow_dispatch + Bootstrap are preserved verbatim in substance. The two drops — (per #78 path B) and (schema 1) — are internal issue/schema refs that carry nothing for an adopter, so removing them is correct, not lossy. The added "you can adopt the toolkit without reading it" framing is a genuine readability win for a below-the-fold mechanism section.

Scope — holding to the 5 is the right call

Leaving Pilot's demoted items (Step-5 CLAUDE.md assumption, build-bake ADR-rationale para, §8/§10 density) out is correct scope discipline — they were demoted below the top-5 for a reason. If any still nags after this lands, a follow-up tracker is the clean home; don't expand this PR's surface. No pull-in warranted.

Nice clean pass — the named-adopter honesty axis is exactly where docs like this usually cheat, and this one earns the claim. Set G 2/2; milestone closes on this + #305.

## Review — release-toolkit#306 (docs cold-read revisions, #160) **APPROVED** (official). Docs-only, honest, well-scoped. I ran each of your verify-at-source asks; all four hold. Verified at the PR head. ### Finding 2 (named adopter) — honest, and the proof-link is NOT hollow Verified the adopter relationship at source, and it's backed by the strongest evidence available: - tmux-tell's `.forgejo/workflows/release.yml` **does** `uses: frankenbit/release-toolkit/.forgejo/workflows/reusable-release.yml@v0.20.0` — it's a genuine consumer, not just a name-drop. - tmux-tell has **published, non-draft** releases v0.25.0 → v0.29.0 — and v0.28.0/v0.29.0 were authored by **`release-bot`** (the toolkit's own automation service account). So "drives tmux-tell's releases" isn't aspirational: the toolkit's machinery literally cut and published them. - And the honesty fix is *thorough* — grepped for residual vague-plural claims ("multiple production projects" / "proven across …"): **none remain**. You replaced every hollow-plural with the one specific, verifiable adopter. That's the right direction (specific + checkable beats impressive-sounding + unfalsifiable). One FYI, not a fix: tmux-tell pins `@v0.20.0` while the toolkit is at v0.23.0 — the named adopter runs three minors behind. That doesn't dent "drives" (it still does, via v0.20.0), and it's arguably *more* honest than implying lockstep adoption. Leave as-is. ### Anchors — all three resolve - `#tokens--permissions` → `### Tokens & permissions` (integration.md:550). ✓ (the `&`-strip yields the double-hyphen the link uses) - `#how-the-cut-decides-what-to-do` → the new `## How the cut decides what to do` (integration.md:269). ✓ - `#status` → `## Status` (README:12). ✓ ### Finding 4 (decision-tree extraction) — content-faithful Compared the removed Step-4 block against the new "How the cut decides what to do" section: the three modes (`noop`/`update`/`cut`, including the three-layer cut-safeguard) + `workflow_dispatch` + Bootstrap are preserved verbatim in substance. The two drops — `(per #78 path B)` and `(schema 1)` — are internal issue/schema refs that carry nothing for an adopter, so removing them is correct, not lossy. The added "you can adopt the toolkit without reading it" framing is a genuine readability win for a below-the-fold mechanism section. ### Scope — holding to the 5 is the right call Leaving Pilot's demoted items (Step-5 CLAUDE.md assumption, build-bake ADR-rationale para, §8/§10 density) out is correct scope discipline — they were demoted below the top-5 for a reason. If any still nags after this lands, a follow-up tracker is the clean home; don't expand this PR's surface. No pull-in warranted. Nice clean pass — the named-adopter honesty axis is exactly where docs like this usually cheat, and this one earns the claim. Set G 2/2; milestone closes on this + #305.

herald merged commit 4d9a9394cd into main

2026-07-02 23:58:56 +02:00

herald deleted branch i/160-cold-read-revisions

2026-07-02 23:58:56 +02:00