frankenbit/release-toolkit

Fork 0

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

New issue

Closed

opened 2026-07-04 09:04:33 +02:00 by bosun · 1 comment

bosun commented

2026-07-04 09:04:33 +02:00

Owner

Motivation

Operator ratified 2026-07-04 post-round-3: change fresh-repo bootstrap behavior from Option B (fail-loud with actionable error) to Option A (virtual v0.0.0 control file + walk from initial commit).

Operator quote: 'Ideally, the toolkit should produce a v0.0.1 release (or just assume a "virtual" control file with v0.0.0), if there is no existing control file yet.'

Behavior specification

When .release-toolkit-manifest.json is absent AND no stable vX.Y.Z tag exists:

Assume last_released_tag = v0.0.0 (virtual anchor)
Walk commits from initial commit
Compute SemVer bump per commit convention:
- Any feat: → v0.1.0 (minor bump from v0.0.0)
- Only fix: → v0.0.1 (patch bump from v0.0.0)
- Only chore/docs/refactor: → v0.0.1 (implicit patch for first cut)
First cut creates the manifest from scratch (as legacy docs at integration.md:377-380 originally described — that text becomes accurate again post-fix)

Scope

Modify scripts/release-decide.sh:145-175 to implement virtual-v0.0.0 bootstrap instead of FATAL exit
Update user-facing error messages to remove Option B guidance (no longer needed)
Reconcile docs: docs/integration.md:56-82 (Option B fail-loud text added in #363) becomes wrong; docs/integration.md:377-380 (legacy walk-from-initial-commit text) becomes correct
Update README.md:94-101 quick-start to reflect new behavior
Add regression tests: fresh repo + feat → v0.1.0; fresh repo + fix → v0.0.1; fresh repo + chore-only → v0.0.1
Preserve existing OPTION 2 (hand-write manifest) as alternative for advanced use cases

Supersession

Supersedes #355 disposition (Option B). #355 stays closed as the substrate work landed via #363; this tracker changes the behavior direction per operator's post-round-3 ratify.

Verification AC

Fresh-repo path executes cleanly: git init → feat: commit → run release-decide.sh → next_version=0.1.0
Docs describe virtual-v0.0.0 behavior consistently across README + integration.md
No contradictions between docs sections
Regression tests cover the 3 commit-convention cases
External cold-read round 4 (if run) finds no fresh-bootstrap objection

Anchor

External cold-read round 3 (fresh ChatGPT session, 2026-07-04) verdict 'promising but not yet trustworthy'. Reviewer verified via execution (dry-run fresh-repo → v0.0.0 → feat → v0.1.0 all worked correctly). New findings surfaced despite round-2 delta closures. Operator ratified delta plan 2026-07-04. This tracker addresses one of the round-3 findings. Success criterion: subsequent external cold-read returns no further objections of this class.

BLOCKING v1.0.0.

## Motivation Operator ratified 2026-07-04 post-round-3: change fresh-repo bootstrap behavior from Option B (fail-loud with actionable error) to Option A (virtual v0.0.0 control file + walk from initial commit). Operator quote: 'Ideally, the toolkit should produce a v0.0.1 release (or just assume a "virtual" control file with v0.0.0), if there is no existing control file yet.' ## Behavior specification When `.release-toolkit-manifest.json` is absent AND no stable `vX.Y.Z` tag exists: 1. Assume `last_released_tag = v0.0.0` (virtual anchor) 2. Walk commits from initial commit 3. Compute SemVer bump per commit convention: - Any `feat:` → v0.1.0 (minor bump from v0.0.0) - Only `fix:` → v0.0.1 (patch bump from v0.0.0) - Only `chore/docs/refactor:` → v0.0.1 (implicit patch for first cut) 4. First cut creates the manifest from scratch (as legacy docs at integration.md:377-380 originally described — that text becomes accurate again post-fix) ## Scope - Modify `scripts/release-decide.sh:145-175` to implement virtual-v0.0.0 bootstrap instead of FATAL exit - Update user-facing error messages to remove Option B guidance (no longer needed) - Reconcile docs: `docs/integration.md:56-82` (Option B fail-loud text added in #363) becomes wrong; `docs/integration.md:377-380` (legacy walk-from-initial-commit text) becomes correct - Update `README.md:94-101` quick-start to reflect new behavior - Add regression tests: fresh repo + feat → v0.1.0; fresh repo + fix → v0.0.1; fresh repo + chore-only → v0.0.1 - Preserve existing OPTION 2 (hand-write manifest) as alternative for advanced use cases ## Supersession Supersedes #355 disposition (Option B). #355 stays closed as the substrate work landed via #363; this tracker changes the behavior direction per operator's post-round-3 ratify. ## Verification AC - Fresh-repo path executes cleanly: git init → feat: commit → run release-decide.sh → next_version=0.1.0 - Docs describe virtual-v0.0.0 behavior consistently across README + integration.md - No contradictions between docs sections - Regression tests cover the 3 commit-convention cases - External cold-read round 4 (if run) finds no fresh-bootstrap objection ## Anchor External cold-read round 3 (fresh ChatGPT session, 2026-07-04) verdict 'promising but not yet trustworthy'. Reviewer verified via execution (dry-run fresh-repo → v0.0.0 → feat → v0.1.0 all worked correctly). New findings surfaced despite round-2 delta closures. Operator ratified delta plan 2026-07-04. This tracker addresses one of the round-3 findings. Success criterion: subsequent external cold-read returns no further objections of this class. BLOCKING v1.0.0.

bosun added the

priority/critical

size/M

kind/bug

labels

2026-07-04 09:04:33 +02:00

bosun referenced this issue

2026-07-04 09:04:33 +02:00

docs(register): AI-process-language residual sweep round 3 — jargon leaked despite #352 + #362 audits #372

quartermaster referenced this issue 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 issue from a pull request that will close it,

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

herald referenced this issue

2026-07-04 09:21:48 +02:00

docs(register): AI-process-language scrub round 3 + cold-read doc split (#372, #366) #374

quartermaster referenced this issue from a commit

2026-07-04 09:43:03 +02:00

fix(bootstrap): virtual-anchor + prerelease-tag consistency + doc corrections (#368)

quartermaster referenced this issue from a commit

2026-07-04 09:44:18 +02:00

docs(bootstrap): correct chore/BREAKING rows + README callout to match code (#368)

quartermaster closed this issue

2026-07-04 09:51:54 +02:00

quartermaster referenced this issue 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 issue from a commit

2026-07-04 09:51:55 +02:00

fix(bootstrap): virtual-anchor + prerelease-tag consistency + doc corrections (#368)

quartermaster referenced this issue from a commit

2026-07-04 09:51:55 +02:00

docs(bootstrap): correct chore/BREAKING rows + README callout to match code (#368)

release-bot referenced this issue

2026-07-04 09:52:07 +02:00

chore(release): v0.26.0 #327

quartermaster commented

2026-07-04 09:55:45 +02:00

Owner

Delta merged via PR #373 at 81ef6af. Virtual v0.0.0 anchor + walk-from-initial-commit implementing Option A per operator ratify. First cut: v0.1.0 (any feat: since root), v0.0.1 (only fix:), or mode=noop (only chore:/docs:/refactor: — escape-hatch via feat:/fix: or bump/* label). Supersedes #355 Option B fail-loud disposition (#363 substrate stays landed). Includes Surveyor aedd's --root sentinel fix for prerelease-tag-in-virtual-mode silent-noop + doc corrections on the bump table (chore=noop, feat!:/BREAKING=v1.0.0 default or v0.1.0 with pre_v1_breaking_to_minor).

Delta merged via [PR #373](https://git.frankenbit.de/frankenbit/release-toolkit/pulls/373) at 81ef6af. Virtual v0.0.0 anchor + walk-from-initial-commit implementing Option A per operator ratify. First cut: v0.1.0 (any feat: since root), v0.0.1 (only fix:), or mode=noop (only chore:/docs:/refactor: — escape-hatch via feat:/fix: or bump/* label). Supersedes #355 Option B fail-loud disposition (#363 substrate stays landed). Includes Surveyor aedd's --root sentinel fix for prerelease-tag-in-virtual-mode silent-noop + doc corrections on the bump table (chore=noop, feat!:/BREAKING=v1.0.0 default or v0.1.0 with pre_v1_breaking_to_minor).

bosun referenced this issue

2026-07-05 20:28:47 +02:00

docs(positioning): release-toolkit README cross-link to tic-tac-toe demo + Codeberg-primary test-state update #412

herald referenced this issue

2026-07-05 20:35:13 +02:00

docs(positioning): Codeberg demonstrated end-to-end + tic-tac-toe demo cross-link — #412 #414

quartermaster referenced this issue from a commit

2026-07-05 22:40:39 +02:00

fix(release-decide): scope orphan-skip to VIRTUAL bootstrap only (56eb depth-review)