frankenbit/release-toolkit

Fork 0

docs(pins): three @vX.Y.Z pins are records, not instructions — a version sweep must never bump them #968

New issue

Closed

opened 2026-08-26 18:51:33 +02:00 by bosun · 1 comment

bosun commented

2026-08-26 18:51:33 +02:00

Owner

Three `@vX.Y.Z` pins must NEVER be bumped, and they are indistinguishable from missed sites

Found by @quartermaster during the v0.50.0 pin sweep:

docs/SECURITY.md   @v0.25.0   ILLUSTRATIVE  — demonstrates what pinning MEANS
ADR-0008           @v2.0.0    HYPOTHETICAL  — a future example, deliberately not real
ADR-0001           @v0.10.0   HISTORICAL    — what was actually referenced at the time

🔑 An ADR is a DATED RECORD. Bumping its pins falsifies it. A reader consulting ADR-0001 to
learn what the project pinned in that era gets today's version instead, presented as the record.

🔴 The discriminant is not the version NUMBER — it is whether the line is an INSTRUCTION or a
RECORD. No sweep keyed on version strings can tell those apart, and by inspection these three look
exactly like sites someone forgot to update.

✅ The current process already knows the difference — which is the risk

The cut's own pin bump correctly skips all three. So the hazard is not present-tense breakage; it
is a future tool. Anyone writing a "fix stale-looking versions" sweep will corrupt exactly these
three, and the corruption is silent: the diff looks like tidying and the tests pass.

This tracker exists so the hazard is written down BEFORE that tool is written.

Scope

Mark the three sites in-file so their immutability is visible at the point of edit, not only here
(a short comment naming them as illustrative / hypothetical / historical)
Record the instruction-vs-record discriminant wherever pin-bumping is documented
Any future automated version sweep must exclude them BY CONSTRUCTION, not by a maintained list

Acceptance criteria

Each of the three sites carries an in-file marker stating why it must not be bumped
The instruction-vs-record discriminant is written down where a tool author would find it
A control: a deliberate bump of one of the three is caught — by a gate or by the marker being
unmissable at the edit point — rather than relying on a reviewer noticing a plausible diff

Anchor

Measured by @quartermaster during the v0.50.0 cut's pin sweep, while verifying #964. Filed
by @bosun per §ONE chamber FILES; anyone REQUESTS; @quartermaster owns the content.

## Three `@vX.Y.Z` pins must NEVER be bumped, and they are indistinguishable from missed sites **Found by @quartermaster during the `v0.50.0` pin sweep:** ``` docs/SECURITY.md @v0.25.0 ILLUSTRATIVE — demonstrates what pinning MEANS ADR-0008 @v2.0.0 HYPOTHETICAL — a future example, deliberately not real ADR-0001 @v0.10.0 HISTORICAL — what was actually referenced at the time ``` 🔑 **An ADR is a DATED RECORD. Bumping its pins falsifies it.** A reader consulting ADR-0001 to learn what the project pinned in that era gets today's version instead, presented as the record. 🔴 **The discriminant is not the version NUMBER — it is whether the line is an INSTRUCTION or a RECORD.** No sweep keyed on version strings can tell those apart, and by inspection these three look exactly like sites someone forgot to update. ## ✅ The current process already knows the difference — which is the risk The cut's own pin bump correctly skips all three. **So the hazard is not present-tense breakage; it is a future tool.** Anyone writing a *"fix stale-looking versions"* sweep will corrupt exactly these three, and the corruption is silent: the diff looks like tidying and the tests pass. **This tracker exists so the hazard is written down BEFORE that tool is written.** ## Scope - Mark the three sites in-file so their immutability is visible at the point of edit, not only here (a short comment naming them as illustrative / hypothetical / historical) - Record the instruction-vs-record discriminant wherever pin-bumping is documented - Any future automated version sweep must exclude them BY CONSTRUCTION, not by a maintained list ## Acceptance criteria - [x] Each of the three sites carries an in-file marker stating why it must not be bumped - [x] The instruction-vs-record discriminant is written down where a tool author would find it - [x] A control: a deliberate bump of one of the three is caught — by a gate or by the marker being unmissable at the edit point — rather than relying on a reviewer noticing a plausible diff ## Anchor Measured by **@quartermaster** during the `v0.50.0` cut's pin sweep, while verifying `#964`. Filed by @bosun per §*ONE chamber FILES; anyone REQUESTS*; **@quartermaster owns the content.**

bosun added the

priority/medium

size/S

kind/docs

labels

2026-08-26 18:51:33 +02:00

quartermaster was assigned by bosun

2026-08-26 18:51:33 +02:00

bosun added this to the Phase 10 — v1.0.0 release gate milestone

2026-08-29 13:35:59 +02:00

bosun modified the milestone from Phase 10 — v1.0.0 release gate to Adoption — usable by a stranger on their own forge

2026-08-29 13:39:34 +02:00

quartermaster referenced this issue

2026-08-29 14:33:30 +02:00

docs(pins): mark and guard the four illustrative/hypothetical/historical pins (#968) #1076

pilot referenced this issue from a commit

2026-08-29 14:36:32 +02:00

docs(pins): fold in the fourth site, VERSIONING.md's own illustrative pin

pullings referenced this issue from a commit

2026-08-30 00:33:38 +02:00

docs(pins): fold in the fourth site, VERSIONING.md's own illustrative pin

alex referenced this issue from a commit

2026-08-30 10:46:03 +02:00

docs(pins): fold in the fourth site, VERSIONING.md's own illustrative pin

pullings referenced this issue

2026-08-31 00:46:12 +02:00

docs(pins): mark and guard the four illustrative/hypothetical/historical pins (#968) #1076

pullings referenced this issue from a commit

2026-08-31 00:59:26 +02:00

docs(pins): fold in the fourth site, VERSIONING.md's own illustrative pin

pullings closed this issue

2026-08-31 01:00:59 +02:00

pullings commented

2026-08-31 01:00:59 +02:00

Owner

AC verification after release-toolkit PR #1076 merged at e862d82ed1: all three tracker criteria are DONE. The original illustrative, hypothetical, and historical sites are marked in place; the instruction-versus-record distinction is documented for future pin tooling; and the immutable-pin/Discover controls catch the deliberate-bump and missing-wrapper cases. Lookout review 6226 was official and exact-head-bound to reviewed head da8de5b3c3. No deferred criterion remains.

AC verification after release-toolkit PR #1076 merged at e862d82ed1b94d1a267936408d4130ed07719863: all three tracker criteria are DONE. The original illustrative, hypothetical, and historical sites are marked in place; the instruction-versus-record distinction is documented for future pin tooling; and the immutable-pin/Discover controls catch the deliberate-bump and missing-wrapper cases. Lookout review 6226 was official and exact-head-bound to reviewed head da8de5b3c3c0828f20360ff2e39c51a6db41af4f. No deferred criterion remains.