frankenbit/release-toolkit

Fork 0

docs(future-tense): remove 'as of v1.0.0' + 'target v1.1.0' language from SECURITY.md + VERSIONING.md (currently v0.25.0) #369

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

Finding

External cold-read round 3 flagged:

docs/SECURITY.md:15: 'as of v1.0.0'
docs/SECURITY.md:45: target 'v1.1.0'
docs/VERSIONING.md:3: 'stability contract as of v1.0.0'

But README says (correctly): 'latest is v0.25.0, pre-1.0.'

Reviewer: 'That looks like future contract text leaked into current adopter docs. For a tool that wants token access and release authority, this kind of mismatch matters.'

Blocking rationale

Adopters read v0.25.0 docs as CURRENT state. Future-tense language reads as either:
(a) confusion about what's shipped, OR
(b) unstated deferral that adopters cannot verify

Both erode trust. Same class as #355 (docs claim future, code current) applied at contract-scope.

Fix path

Options per doc section:

Option A (recommended): rewrite to describe CURRENT state. Example: 'The stability contract commits to backward compat for v1.x releases.' → 'This project is pre-1.0. When v1.0.0 ships, it will commit to backward compat for v1.x.'
Option B: explicitly label as 'planned for v1.0.0' with tracker link (#338 stability contract memorialization). Requires clear visual signaling.

Option A gives adopters honest current-state; Option B preserves the aspirational-contract text with clear labeling.

Lean: A for VERSIONING.md, B for SECURITY.md sections that describe genuine planned v1.1.0 architectural work (immutable pinning #336).

Verification AC

Every 'as of v1.0.0' or 'target v1.1.0' phrase reviewed + reclassified
No adopter reading v0.25.0 docs would confuse future contract with current guarantee
External cold-read round 4 finds no future-tense-in-current-surface 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.

## Finding External cold-read round 3 flagged: - `docs/SECURITY.md:15`: 'as of v1.0.0' - `docs/SECURITY.md:45`: target 'v1.1.0' - `docs/VERSIONING.md:3`: 'stability contract as of v1.0.0' But README says (correctly): 'latest is v0.25.0, pre-1.0.' Reviewer: 'That looks like future contract text leaked into current adopter docs. For a tool that wants token access and release authority, this kind of mismatch matters.' ## Blocking rationale Adopters read v0.25.0 docs as CURRENT state. Future-tense language reads as either: (a) confusion about what's shipped, OR (b) unstated deferral that adopters cannot verify Both erode trust. Same class as #355 (docs claim future, code current) applied at contract-scope. ## Fix path Options per doc section: - **Option A** (recommended): rewrite to describe CURRENT state. Example: 'The stability contract commits to backward compat for v1.x releases.' → 'This project is pre-1.0. When v1.0.0 ships, it will commit to backward compat for v1.x.' - **Option B**: explicitly label as 'planned for v1.0.0' with tracker link (#338 stability contract memorialization). Requires clear visual signaling. Option A gives adopters honest current-state; Option B preserves the aspirational-contract text with clear labeling. Lean: A for VERSIONING.md, B for SECURITY.md sections that describe genuine planned v1.1.0 architectural work (immutable pinning #336). ## Verification AC - Every 'as of v1.0.0' or 'target v1.1.0' phrase reviewed + reclassified - No adopter reading v0.25.0 docs would confuse future contract with current guarantee - External cold-read round 4 finds no future-tense-in-current-surface 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/high

size/S

kind/docs

labels

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

quartermaster referenced this issue

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

fix(security): keep FORGEJO_TOKEN out of curl argv (#371) #375

quartermaster referenced this issue from a commit

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

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

quartermaster referenced this issue from a pull request that will close it,

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

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

quartermaster referenced this issue from a commit

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

docs(security): tag-immutability is already-in-force pre-1.0, not v1.0.0 addition (#369)

quartermaster referenced this issue from a commit

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

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

quartermaster referenced this issue from a commit

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

docs(security): tag-immutability is already-in-force pre-1.0, not v1.0.0 addition (#369)

quartermaster closed this issue

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

quartermaster commented

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

Owner

Delta merged via PR #377 at bc9ce54. Future-tense contract language retired from adopter surface: VERSIONING.md rewritten to describe current pre-1.0 state (Option A); SECURITY.md architectural fix section explicitly labeled 'Planned for v1.1.0' with not-yet-shipped callout (Option B). Includes Surveyor dee2's SECURITY.md:34 tag-immutability reframe (was 'The v1.0.0 SemVer contract reinforces this', now 'this discipline is already in force pre-1.0').

Delta merged via [PR #377](https://git.frankenbit.de/frankenbit/release-toolkit/pulls/377) at bc9ce54. Future-tense contract language retired from adopter surface: VERSIONING.md rewritten to describe current pre-1.0 state (Option A); SECURITY.md architectural fix section explicitly labeled 'Planned for v1.1.0' with not-yet-shipped callout (Option B). Includes Surveyor dee2's SECURITY.md:34 tag-immutability reframe (was 'The v1.0.0 SemVer contract reinforces this', now 'this discipline is already in force pre-1.0').