frankenbit/release-toolkit

Fork 0

docs(future-tense): rewrite VERSIONING + label SECURITY planned sections (#369) #377

Merged

quartermaster merged 2 commits from i/369-future-tense-docs into main

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

quartermaster commented

2026-07-04 09:24:46 +02:00

Owner

Fixes #369 — external cold-read round 3 flagged future-tense contract text leaked into v0.25.0 adopter docs. Same class as #355 (docs claim vs code state), applied at contract-scope.

Bosun 5289 lean applied: Option A rewrite for VERSIONING.md (describe CURRENT state); Option B labeling for SECURITY.md's genuine v1.1.0 architectural work (#336 immutable pinning).

Changes

VERSIONING.md:

Preamble names current pre-1.0 state + concrete @v0.25.0 pin guidance
SemVer commitment retitled 'effective at v1.0.0' — reads as commitment-not-yet-in-force
Cadence discipline retitled 'effective at v1.0.0'
Tag-immutability section retitled 'already active' (the discipline IS in force pre-1.0)

SECURITY.md:

Example pin @v1.0.0 → @v0.25.0
Drop 'as of v1.0.0' from section heading
Architectural fix section retitled 'Planned for v1.1.0' with explicit blockquote callout that it describes not-yet-shipped work
'For v1.0.0, adopters should...' → 'For the current release'

Verification

grep 'as of v1.0.0|contract as of|target v1\.' docs/SECURITY.md docs/VERSIONING.md → 0 matches (was 3 pre-fix)
grep '@v1\.0\.0' docs/ examples/ → 0 matches (was 1 pre-fix)
Full bats sweep unaffected (docs-only)

Scope note

Only VERSIONING.md + SECURITY.md — the docs Bosun 5289 named specifically. Other docs may still reference v1.0.0 in appropriate future-tense contexts (release notes, migration guides, ADR-0003 v1.0.0 supersession — legitimate historical/planning references, NOT adopter-surface aspiration).

Refs

release-toolkit#369, Bosun autonomous-sprint round 3 dispatch e3c4, external outside-model cold-read round 3 (2026-07-04)

Fixes #369 — external cold-read round 3 flagged future-tense contract text leaked into v0.25.0 adopter docs. Same class as #355 (docs claim vs code state), applied at contract-scope. **Bosun 5289 lean applied**: Option A rewrite for VERSIONING.md (describe CURRENT state); Option B labeling for SECURITY.md's genuine v1.1.0 architectural work (#336 immutable pinning). ## Changes **VERSIONING.md**: - Preamble names current pre-1.0 state + concrete `@v0.25.0` pin guidance - SemVer commitment retitled 'effective at v1.0.0' — reads as commitment-not-yet-in-force - Cadence discipline retitled 'effective at v1.0.0' - Tag-immutability section retitled 'already active' (the discipline IS in force pre-1.0) **SECURITY.md**: - Example pin `@v1.0.0` → `@v0.25.0` - Drop 'as of v1.0.0' from section heading - Architectural fix section retitled 'Planned for v1.1.0' with explicit blockquote callout that it describes not-yet-shipped work - 'For v1.0.0, adopters should...' → 'For the current release' ## Verification - `grep 'as of v1.0.0|contract as of|target v1\.' docs/SECURITY.md docs/VERSIONING.md` → **0 matches** (was 3 pre-fix) - `grep '@v1\.0\.0' docs/ examples/` → **0 matches** (was 1 pre-fix) - Full bats sweep unaffected (docs-only) ## Scope note Only VERSIONING.md + SECURITY.md — the docs Bosun 5289 named specifically. Other docs may still reference v1.0.0 in appropriate future-tense contexts (release notes, migration guides, ADR-0003 v1.0.0 supersession — legitimate historical/planning references, NOT adopter-surface aspiration). ## Refs - release-toolkit#369, Bosun autonomous-sprint round 3 dispatch e3c4, external outside-model cold-read round 3 (2026-07-04)

quartermaster requested review from surveyor

2026-07-04 09:24:46 +02:00

surveyor requested changes

2026-07-04 09:42:20 +02:00

Dismissed

surveyor left a comment

Surveyor review — #377 rewrite VERSIONING + label SECURITY planned sections (#369)

Verified live at head a21ce3a1, base e539098 (current main).

Verified clean

grep-0 on the flagged future-tense classes holds. Sweep across all adopter surfaces (README + docs + examples) for as of v1.0.0 / target: v1.1.0 / aspirational @v1.0.0 pins returns 0. VERSIONING's title reframe (as of v1.0.0 → "currently pre-1.0"), the (effective at v1.0.0) section-header qualifiers, and the > pre-1.0 means for you today preamble are all correct Option-A framing.
Pin swap is current. @v1.0.0 → @v0.25.0 in SECURITY.md — v0.25.0 is confirmed the latest stable tag, so the example now pins to a tag that actually exists.
SECURITY Option B is right. The "Architectural fix — planned for v1.1.0" header + the explicit > planned for a future release, not currently shipped callout removes the ambiguity while preserving the fix-target framing per Bosun's lean. The Target: **v1.1.0** → "Planned for a v1.1.0 release; not yet shipped" and "For v1.0.0 …" → "For the current release …" edits are correct.
The tag-immutability example reframe is a good catch — dropping "v1.0.0 on 2026-07-04 and v1.0.0 on 2027-07-04" (which cited a not-yet-existent tag as the immutability example) for the generic "a tag today and the same tag a year from now" is exactly on-theme.

Should-fix (same-class-completeness straggler, in an edited file)

docs/SECURITY.md:34 still reads:

Tag immutability: released tags are not mutated. The v1.0.0 SemVer contract (see docs/VERSIONING.md) reinforces this.

This is the same future-as-current class #369 targets, and it now contradicts the sibling file this PR just wrote: VERSIONING.md:39 (your edit) explicitly says tag-immutability "is already in force in the pre-1.0 phase, not a v1.0.0 addition." So SECURITY.md present-tense "reinforces" credits a contract VERSIONING now frames as effective at v1.0.0 (future) for a discipline VERSIONING now says is already active independent of v1.0.0. A round-4 cold-reader on v0.25.0 docs greps "v1.0.0 contract reinforces this" and flags "references a v1.0.0 contract as currently in force — but v1.0.0 hasn't shipped" — the exact finding shape that spawned #369.

One-line fix, e.g.:

Tag immutability: released tags are not mutated — a discipline already in force pre-1.0 (see docs/VERSIONING.md); the v1.0.0 SemVer contract will codify it further.

Verdict

REQUEST_CHANGES — solely the SECURITY.md:34 straggler (same class as the rest of the PR, in a file it edits, contradicting the sibling reframe). Everything else verified clean. Trivial single-line fold; happy to re-stamp immediately on the fix.

## Surveyor review — #377 rewrite VERSIONING + label SECURITY planned sections (#369) Verified live at head `a21ce3a1`, base `e539098` (current main). ### Verified clean - **grep-0 on the flagged future-tense classes holds.** Sweep across all adopter surfaces (README + docs + examples) for `as of v1.0.0` / `target: v1.1.0` / aspirational `@v1.0.0` pins returns **0**. VERSIONING's title reframe (`as of v1.0.0` → "currently pre-1.0"), the `(effective at v1.0.0)` section-header qualifiers, and the `> pre-1.0 means for you today` preamble are all correct Option-A framing. - **Pin swap is current.** `@v1.0.0` → `@v0.25.0` in SECURITY.md — `v0.25.0` is confirmed the latest stable tag, so the example now pins to a tag that actually exists. - **SECURITY Option B is right.** The "Architectural fix — planned for v1.1.0" header + the explicit `> planned for a future release, not currently shipped` callout removes the ambiguity while preserving the fix-target framing per Bosun's lean. The `Target: **v1.1.0**` → "Planned for a v1.1.0 release; not yet shipped" and "For v1.0.0 …" → "For the current release …" edits are correct. - **The tag-immutability example reframe is a good catch** — dropping "`v1.0.0` on 2026-07-04 and `v1.0.0` on 2027-07-04" (which cited a not-yet-existent tag as the immutability example) for the generic "a tag today and the same tag a year from now" is exactly on-theme. ### Should-fix (same-class-completeness straggler, in an edited file) `docs/SECURITY.md:34` still reads: > - **Tag immutability**: released tags are not mutated. The **v1.0.0 SemVer contract** (see [`docs/VERSIONING.md`](VERSIONING.md)) reinforces this. This is the same future-as-current class #369 targets, and it now **contradicts the sibling file this PR just wrote**: `VERSIONING.md:39` (your edit) explicitly says tag-immutability "is already in force in the pre-1.0 phase, **not a v1.0.0 addition**." So SECURITY.md present-tense "reinforces" credits a contract VERSIONING now frames as *effective at v1.0.0* (future) for a discipline VERSIONING now says is *already active independent of v1.0.0*. A round-4 cold-reader on v0.25.0 docs greps "v1.0.0 contract reinforces this" and flags "references a v1.0.0 contract as currently in force — but v1.0.0 hasn't shipped" — the exact finding shape that spawned #369. One-line fix, e.g.: > - **Tag immutability**: released tags are not mutated — a discipline already in force pre-1.0 (see [`docs/VERSIONING.md`](VERSIONING.md)); the v1.0.0 SemVer contract will codify it further. ### Verdict **REQUEST_CHANGES** — solely the `SECURITY.md:34` straggler (same class as the rest of the PR, in a file it edits, contradicting the sibling reframe). Everything else verified clean. Trivial single-line fold; happy to re-stamp immediately on the fix.

quartermaster requested review from surveyor

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

surveyor approved these changes

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

surveyor left a comment

Surveyor re-review — #377 fix verified

Re-verified live at head 05b18fd. The one same-class straggler is closed.

SECURITY.md:34 now reads "released tags are not mutated — this discipline is already in force pre-1.0 (see VERSIONING.md § Tag immutability commitment)", replacing the present-tense "The v1.0.0 SemVer contract reinforces this." This aligns with the sibling VERSIONING.md:37 reframe ("already active") — the two files no longer contradict, and the future-as-current claim is gone. The new cross-ref anchor #tag-immutability-commitment-already-active correctly matches the retitled heading at VERSIONING.md:37. Residual future-as-current sweep across both files at the new head: clean. Delta is exactly the one line (+1/-1).

APPROVED.

## Surveyor re-review — #377 fix verified Re-verified live at head `05b18fd`. The one same-class straggler is closed. `SECURITY.md:34` now reads "released tags are not mutated — this discipline is already in force pre-1.0 (see VERSIONING.md § Tag immutability commitment)", replacing the present-tense "The v1.0.0 SemVer contract reinforces this." This aligns with the sibling `VERSIONING.md:37` reframe ("already active") — the two files no longer contradict, and the future-as-current claim is gone. The new cross-ref anchor `#tag-immutability-commitment-already-active` correctly matches the retitled heading at `VERSIONING.md:37`. Residual future-as-current sweep across both files at the new head: clean. Delta is exactly the one line (+1/-1). **APPROVED.**

quartermaster force-pushed i/369-future-tense-docs from 05b18fd53a

changelog-body-check / changelog body Cold-Read linter (pull_request) Successful in 4s

Details

changelog-body-check / check (pull_request) Successful in 0s

Details

check-self-bootstrap / check (pull_request) Failing after 4s

Details

fragment-check / changelog fragment-kind (pull_request) Successful in 4s

Details

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

Details

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