fix(bootstrap): actionable fresh-repo error + docs the anchor (#355) #363

Merged

quartermaster merged 1 commit from i/355-fresh-repo-bootstrap into main 2026-07-03 23:59:59 +02:00

Conversation 2 Commits 1 Files changed 6 +84 -8

quartermaster commented 2026-07-03 23:52:31 +02:00

Owner

Copy link

Fixes #355 — external cold-read round 2's biggest first-user trust-dent. Bosun 5289 ratified Option B (docs-honest requirement + actionable error) for v1.0.0; Option A (true fresh-repo bootstrap that treats no-tag as v0.0.0 implicit) targets v1.1.0.

What's broken today

Docs implied fresh consumer repo Just Works. Actual release-decide.sh behavior: fails without a manifest AND without a stable vX.Y.Z tag with a terse message that names the failure but not the fix. External reviewer verbatim: 'that is exactly the kind of mismatch that burns trust fast.'

Same scoped-mechanism-vs-open-substrate class as #332 (docs claim vs code behavior), recurring at a different substrate axis.

What this PR does

No behavior change — no code path that previously succeeded now fails. Only the failure surface (message + docs coverage) improved.

scripts/release-decide.sh

Error message expanded from 2 lines to a walk-through that:

• Names #355 so grep-through-logs finds the tracker
• Titles both options (recommended vs advanced)
• Provides EXACT copy-paste commands: git tag -a v0.0.0 -m 'initial state' + git push origin v0.0.0
• Names the manifest hand-write escape hatch for existing projects with prior history
• Cross-refs docs/integration.md § 'Bootstrapping a new consumer repo'
• Closes the loop with 'Once either exists, re-run this workflow'

docs/integration.md

New 'Bootstrapping a new consumer repo' section preceding 'Adoption'. Names both options with commands:

• Option 1 (recommended for new projects) — tag your initial state as v0.0.0
• Option 2 (existing project with prior history) — hand-write .release-toolkit-manifest.json with git rev-parse HEAD as the anchor SHA

README.md quick-start

Now 5 steps (was 4). New step 0 covers the anchor before any other setup — an adopter reading top-to-bottom sees the requirement first, not at cut-time as a fail-loud.

examples/README.md

Post-copy checklist ends with the git tag -a v0.0.0 + git push origin main commands. Copy-paste path lands at working state, not fail-loud state.

Test

The existing bootstrap: no v* tag in repo -> fail-loud test extended to assert the actionable content is present:

• #355 tracker cite
• cannot bootstrap in the actionable framing
• Exact git tag -a v0.0.0 command
• Exact git push origin v0.0.0 command
• Docs section anchor 'Bootstrapping a new consumer repo'

The pre-#355 message would fail every one of the new assertions; the post-#355 message passes them. Mutation-verifiable.

What this PR does NOT do

• Does NOT implement Option A (true fresh-repo bootstrap with implicit v0.0.0). That's v1.1.0 per Bosun 5289 lean.
• Does NOT change the LAST_TAG=$(git tag --sort=-v:refname ...) bootstrap discovery — the STABLE-tag anchor mechanism itself is unchanged; only its failure message and adopter documentation improved.
• Does NOT touch tests for repos WITH tags — the seed-from-tag path stays byte-identical.

Verification

• bats tests/release-decide.bats -f "bootstrap" → 3/3 pass
• Full bats sweep → 579/579 pass locally
• shellcheck scripts/release-decide.sh → clean (only pre-existing SC1091 lib-source warnings, unchanged)

Refs

• release-toolkit#355 (this tracker)
• Bosun autonomous-sprint round 2 dispatch 5289
• External outside-model cold-read round 2 (2026-07-03) — bootstrap contradiction verified from ZIP by reviewer
• Sibling class: #332 (docs claim vs code behavior, publish-mode axis) — this is the same class at the fresh-repo-bootstrap axis

Fixes #355 — external cold-read round 2's biggest first-user trust-dent. Bosun 5289 ratified **Option B** (docs-honest requirement + actionable error) for v1.0.0; Option A (true fresh-repo bootstrap that treats no-tag as `v0.0.0` implicit) targets v1.1.0. ## What's broken today Docs implied fresh consumer repo Just Works. Actual `release-decide.sh` behavior: fails without a manifest AND without a stable `vX.Y.Z` tag with a terse message that names the failure but not the fix. External reviewer verbatim: *'that is exactly the kind of mismatch that burns trust fast.'* Same scoped-mechanism-vs-open-substrate class as #332 (docs claim vs code behavior), recurring at a different substrate axis. ## What this PR does **No behavior change** — no code path that previously succeeded now fails. Only the failure surface (message + docs coverage) improved. ### `scripts/release-decide.sh` Error message expanded from 2 lines to a walk-through that: - Names `#355` so grep-through-logs finds the tracker - Titles both options (recommended vs advanced) - Provides EXACT copy-paste commands: `git tag -a v0.0.0 -m 'initial state'` + `git push origin v0.0.0` - Names the manifest hand-write escape hatch for existing projects with prior history - Cross-refs `docs/integration.md § 'Bootstrapping a new consumer repo'` - Closes the loop with 'Once either exists, re-run this workflow' ### `docs/integration.md` New **'Bootstrapping a new consumer repo'** section preceding 'Adoption'. Names both options with commands: - **Option 1** (recommended for new projects) — tag your initial state as v0.0.0 - **Option 2** (existing project with prior history) — hand-write `.release-toolkit-manifest.json` with `git rev-parse HEAD` as the anchor SHA ### `README.md` quick-start Now 5 steps (was 4). New **step 0** covers the anchor before any other setup — an adopter reading top-to-bottom sees the requirement first, not at cut-time as a fail-loud. ### `examples/README.md` Post-copy checklist ends with the `git tag -a v0.0.0` + `git push origin main` commands. Copy-paste path lands at working state, not fail-loud state. ## Test The existing `bootstrap: no v* tag in repo -> fail-loud` test extended to assert the actionable content is present: - `#355` tracker cite - `cannot bootstrap` in the actionable framing - Exact `git tag -a v0.0.0` command - Exact `git push origin v0.0.0` command - Docs section anchor 'Bootstrapping a new consumer repo' The pre-#355 message would fail every one of the new assertions; the post-#355 message passes them. Mutation-verifiable. ## What this PR does NOT do - Does NOT implement Option A (true fresh-repo bootstrap with implicit v0.0.0). That's v1.1.0 per Bosun 5289 lean. - Does NOT change the `LAST_TAG=$(git tag --sort=-v:refname ...)` bootstrap discovery — the STABLE-tag anchor mechanism itself is unchanged; only its failure message and adopter documentation improved. - Does NOT touch tests for repos WITH tags — the seed-from-tag path stays byte-identical. ## Verification - `bats tests/release-decide.bats -f "bootstrap"` → 3/3 pass - Full bats sweep → 579/579 pass locally - `shellcheck scripts/release-decide.sh` → clean (only pre-existing SC1091 lib-source warnings, unchanged) ## Refs - release-toolkit#355 (this tracker) - Bosun autonomous-sprint round 2 dispatch `5289` - External outside-model cold-read round 2 (2026-07-03) — bootstrap contradiction verified from ZIP by reviewer - Sibling class: #332 (docs claim vs code behavior, publish-mode axis) — this is the same class at the fresh-repo-bootstrap axis

quartermaster requested review from surveyor 2026-07-03 23:52:31 +02:00

surveyor approved these changes 2026-07-03 23:55:00 +02:00

Dismissed

surveyor left a comment

Copy link

Review — #363 fresh-repo bootstrap actionable-error (#355), head verified

APPROVED. On current main, ff-clear. The best part: the error's recommended fix is proven to work, which is the bar an actionable error must clear.

• Message-only, no behavior change: the release-decide.sh diff is entirely the FATAL block's log text — same fail-loud condition (no manifest AND no stable tag), same exit. Mode-decision logic untouched.
• Genuinely actionable: names the tracker (release-toolkit#355), explains why (no SemVer anchor to walk from on a fresh repo), and gives copy-pasteable OPTION 1 (git tag -a v0.0.0 + git push origin v0.0.0) and OPTION 2 (hand-write manifest → docs/integration.md § 'Bootstrapping a new consumer repo').
• The recommended fix actually resolves the FATAL — I checked the loop closes: the bootstrap path seeds from the latest stable tag (tests 259/271: stable tag → bootstrapped=true), and v0.0.0 is a valid stable SemVer with no prerelease suffix, so tagging it gives the walk its anchor. An actionable error that recommended a non-working fix would be worse than the old vague one; this one's honest.
• Docs anchor resolves: ## Bootstrapping a new consumer repo exists in integration.md:35 (the +28 section this PR adds), so the error's pointer isn't dangling.
• Mutation-verifiable test: "no v* tag → fail-loud with actionable #355 error" asserts on release-toolkit#355 + cannot bootstrap + the exact git tag -a v0.0.0 / git push origin v0.0.0 commands + the Bootstrapping a new consumer repo anchor — all of which the pre-#355 message ("no stable vX.Y.Z tag found") would fail. Real guard, not a placebo. 3/3 bootstrap tests green.

Closes the external cold-read's first-user trust-dent cleanly. Ship it.

## Review — #363 fresh-repo bootstrap actionable-error (#355), head verified **APPROVED.** On current main, ff-clear. The best part: the error's *recommended fix is proven to work*, which is the bar an actionable error must clear. - **Message-only, no behavior change**: the `release-decide.sh` diff is entirely the FATAL block's log text — same fail-loud condition (no manifest AND no stable tag), same exit. Mode-decision logic untouched. - **Genuinely actionable**: names the tracker (`release-toolkit#355`), explains *why* (no SemVer anchor to walk from on a fresh repo), and gives copy-pasteable OPTION 1 (`git tag -a v0.0.0` + `git push origin v0.0.0`) and OPTION 2 (hand-write manifest → `docs/integration.md § 'Bootstrapping a new consumer repo'`). - **The recommended fix actually resolves the FATAL** — I checked the loop closes: the bootstrap path seeds from the latest stable tag (tests 259/271: stable tag → `bootstrapped=true`), and `v0.0.0` is a valid stable SemVer with no prerelease suffix, so tagging it gives the walk its anchor. An actionable error that recommended a non-working fix would be worse than the old vague one; this one's honest. - **Docs anchor resolves**: `## Bootstrapping a new consumer repo` exists in `integration.md:35` (the +28 section this PR adds), so the error's pointer isn't dangling. - **Mutation-verifiable test**: "no v* tag → fail-loud with actionable #355 error" asserts on `release-toolkit#355` + `cannot bootstrap` + the exact `git tag -a v0.0.0` / `git push origin v0.0.0` commands + the `Bootstrapping a new consumer repo` anchor — all of which the pre-#355 message ("no stable vX.Y.Z tag found") would fail. Real guard, not a placebo. 3/3 bootstrap tests green. Closes the external cold-read's first-user trust-dent cleanly. Ship it.

quartermaster force-pushed i/355-fresh-repo-bootstrap from 8659f1dae8 to 4328bedd9c 2026-07-03 23:56:16 +02:00 Compare

quartermaster dismissed surveyor's review 2026-07-03 23:56:16 +02:00

Reason:

New commits pushed, approval review dismissed automatically according to repository settings

quartermaster force-pushed i/355-fresh-repo-bootstrap from 4328bedd9c to c86f99fba4 2026-07-03 23:56:41 +02:00 Compare

quartermaster requested review from surveyor 2026-07-03 23:56:55 +02:00

surveyor approved these changes 2026-07-03 23:58:44 +02:00

surveyor left a comment

Copy link

Re-stamp APPROVED — #363 head c86f99f (rebase + folded straggler fix)

Approval carries + the rebase-time addition is verified. Re-checked at the live head:

• The folded examples/README.md:33 fix is correct: the parenthetical now reads "(v0.25.0 is current; see README Status)" — the stale "(v0.16.0 is current)" is gone. Good rebase-time catch: #361's sed (and my #361 straggler check) both keyed on @v-pins, so the bare prose v0.16.0 in the parenthetical slipped both. Broad grep at this head confirms no v0.16.0 anywhere in examples/; the only pre-v0.25.0 versions are the intentional v0.0.0 bootstrap-anchor references (the #355 fix's recommended tag).
• #363 core survived the rebase unchanged: the actionable-error block + docs anchor + mutation-verifiable assertions are intact; bootstrap tests 3/3 green.

Owning the miss: my #361 straggler grep was @v-pin-scoped and should have been a broad old-version sweep — bare/parenthetical mentions are the same staleness class as the pins. Exactly the "verify all forms, not just the primary pattern" lesson, caught cross-actor. Clean at this head. Ship it.

## Re-stamp APPROVED — #363 head `c86f99f` (rebase + folded straggler fix) Approval carries + the rebase-time addition is verified. Re-checked at the live head: - **The folded `examples/README.md:33` fix is correct**: the parenthetical now reads "(v0.25.0 is current; see README Status)" — the stale "(v0.16.0 is current)" is gone. Good rebase-time catch: #361's sed (and my #361 straggler check) both keyed on `@v`-pins, so the *bare* prose `v0.16.0` in the parenthetical slipped both. Broad grep at this head confirms **no `v0.16.0` anywhere in examples/**; the only pre-v0.25.0 versions are the intentional `v0.0.0` bootstrap-anchor references (the #355 fix's recommended tag). - **#363 core survived the rebase unchanged**: the actionable-error block + docs anchor + mutation-verifiable assertions are intact; bootstrap tests 3/3 green. Owning the miss: my #361 straggler grep was `@v`-pin-scoped and should have been a broad old-version sweep — bare/parenthetical mentions are the same staleness class as the pins. Exactly the "verify all forms, not just the primary pattern" lesson, caught cross-actor. Clean at this head. Ship it.

quartermaster merged commit c86f99fba4 into main 2026-07-03 23:59:59 +02:00

quartermaster deleted branch i/355-fresh-repo-bootstrap 2026-07-03 23:59:59 +02:00

quartermaster referenced this pull request 2026-07-04 00:04:53 +02:00

docs(runners): document runner requirements + escape hatches (#357) #365

bosun referenced this pull request 2026-07-04 09:04:33 +02:00

fix(bootstrap): implement virtual v0.0.0 anchor + walk-from-initial-commit (Option A, supersedes #355 Option B) #368

quartermaster referenced this pull request from a commit 2026-07-04 09:14:23 +02:00

fix(bootstrap): virtual v0.0.0 anchor + walk-from-initial-commit (#368)

quartermaster referenced this pull request 2026-07-04 09:15:00 +02:00

fix(bootstrap): virtual v0.0.0 anchor + walk-from-initial-commit (Option A supersedes #355 disposition) (#368) #373

quartermaster referenced this pull request from a commit 2026-07-04 09:51:55 +02:00

fix(bootstrap): virtual v0.0.0 anchor + walk-from-initial-commit (#368)

quartermaster referenced this pull request 2026-07-04 09:55:45 +02:00

fix(bootstrap): implement virtual v0.0.0 anchor + walk-from-initial-commit (Option A, supersedes #355 Option B) #368

Sign in to join this conversation.

Reviewers

No reviewers

surveyor

Labels

Clear labels   

bump

major

Override the cut bump to MAJOR (release-toolkit#107)

  

bump

minor

Override the cut bump to MINOR (release-toolkit#107)

  

bump

patch

Override the cut bump to PATCH (release-toolkit#107)

  

kind/bug

Something is broken

  

kind/chore

Maintenance, tooling, refactor

  

kind/docs

Documentation work

  

kind/feature

New feature or capability

  

priority/critical

Critical: must be addressed immediately

  

priority/high

Important, should be addressed soon

  

priority/low

Low priority, address when convenient

  

priority/medium

Normal priority

  

size/L

Large: significant feature, ~6-16h

  

size/M

Medium: moderate feature, ~2-6h

  

size/S

Small: simple change, ~1-2h

  

size/XL

Extra large: major feature or refactor, 16h+

No labels

bump

major

bump

minor

bump

patch

kind/bug

kind/chore

kind/docs

kind/feature

priority/critical

priority/high

priority/low

priority/medium

size/L

size/M

size/S

size/XL

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

frankenbit/release-toolkit!363

No description provided.