fix(bootstrap): fresh-repo path fails — docs say works without manifest, code fails without stable vX.Y.Z tag OR manifest #355

New issue

Closed

opened 2026-07-03 23:42:48 +02:00 by bosun · 0 comments

bosun commented

2026-07-03 23:42:48 +02:00

Owner

Empirical failure (external cold-read verified from ZIP)

Docs say fresh consumer repo without .release-toolkit-manifest.json is treated as having no prior release and walks from the initial commit.

Actual behavior of scripts/release-decide.sh: FAILS if there is no manifest AND no existing stable vX.Y.Z tag. Tests also encode the "fail without stable tag" behavior.

External reviewer verified: "no manifest and no tag produces a fatal error requiring a manual stable tag or hand-bootstrapped manifest."

Blocking rationale

External review verbatim: "That is exactly the kind of mismatch that burns trust fast" — named as the biggest stopper. First-user experience broken. This is the SAME CLASS as ChatGPT round-1 #332 (docs claim vs code behavior). We thought we closed this class. It recurred at a different substrate axis (bootstrap-path vs publish-mode default). Same scoped-mechanism-vs-open-substrate class recursion.

Fix path (either A or B, not both)

Option A (adopter-friendly, harder): implement true fresh-repo bootstrap. release-decide.sh treats no-manifest + no-tag as "start at v0.0.0, walk from initial commit." Add regression test for the fresh-repo path.

Option B (docs-honest, easier): require initial v0.0.0 or v0.0.1 tag OR hand-written manifest. Update README + examples/README.md + integration.md + quick-start to name this requirement clearly and provide the exact command to create the initial tag. Make error message in release-decide.sh actionable when the requirement isn't met.

My lean: Option B for v1.0.0 (docs-honest, ship soon), Option A can be v1.1.0 feature.

Verification AC

Fresh repo (no manifest, no tag) either: (a) succeeds with a walk-from-initial-commit release-decide, OR (b) fails with a clear actionable error message naming the requirement + fix
README + examples show the correct bootstrap path matching implementation
External cold-read round 3 finds no bootstrap contradiction

Anchor

External outside-model cold-read round 2 (fresh ChatGPT session, 2026-07-03 late) returned new findings after Pilot Cold-Read delta had cleared. External verdict: 'promising but not yet trustworthy.' Operator ratified delta plan 2026-07-03 23:35. This tracker addresses one of the round-2 findings. Success criterion: subsequent external cold-read returns no further objections of this class.

## Empirical failure (external cold-read verified from ZIP) Docs say fresh consumer repo without `.release-toolkit-manifest.json` is treated as having no prior release and walks from the initial commit. Actual behavior of `scripts/release-decide.sh`: FAILS if there is no manifest AND no existing stable `vX.Y.Z` tag. Tests also encode the "fail without stable tag" behavior. External reviewer verified: "no manifest and no tag produces a fatal error requiring a manual stable tag or hand-bootstrapped manifest." ## Blocking rationale External review verbatim: "That is exactly the kind of mismatch that burns trust fast" — named as the biggest stopper. First-user experience broken. This is the SAME CLASS as ChatGPT round-1 #332 (docs claim vs code behavior). We thought we closed this class. It recurred at a different substrate axis (bootstrap-path vs publish-mode default). Same scoped-mechanism-vs-open-substrate class recursion. ## Fix path (either A or B, not both) **Option A** (adopter-friendly, harder): implement true fresh-repo bootstrap. release-decide.sh treats no-manifest + no-tag as "start at v0.0.0, walk from initial commit." Add regression test for the fresh-repo path. **Option B** (docs-honest, easier): require initial `v0.0.0` or `v0.0.1` tag OR hand-written manifest. Update README + examples/README.md + integration.md + quick-start to name this requirement clearly and provide the exact command to create the initial tag. Make error message in release-decide.sh actionable when the requirement isn't met. My lean: Option B for v1.0.0 (docs-honest, ship soon), Option A can be v1.1.0 feature. ## Verification AC - Fresh repo (no manifest, no tag) either: (a) succeeds with a walk-from-initial-commit release-decide, OR (b) fails with a clear actionable error message naming the requirement + fix - README + examples show the correct bootstrap path matching implementation - External cold-read round 3 finds no bootstrap contradiction ## Anchor External outside-model cold-read round 2 (fresh ChatGPT session, 2026-07-03 late) returned new findings after Pilot Cold-Read delta had cleared. External verdict: 'promising but not yet trustworthy.' Operator ratified delta plan 2026-07-03 23:35. This tracker addresses one of the round-2 findings. Success criterion: subsequent external cold-read returns no further objections of this class.

bosun added the

priority/critical

size/M

kind/bug

labels

2026-07-03 23:42:48 +02:00