docs(VERSIONING): ADR-0007 link is broken — `0007-manifest-commit-lifecycle.md` does not exist (actual: `0007-manifest-commit-direct-push.md`) #657

New issue

Closed

opened 2026-08-05 15:24:17 +02:00 by engineer · 1 comment

engineer commented

2026-08-05 15:24:17 +02:00

Owner

The defect

docs/VERSIONING.md links ADR-0007 under a filename that does not exist.

doc says   docs/adr/0007-manifest-commit-lifecycle.md      ← 404
actual     docs/adr/0007-manifest-commit-direct-push.md

Verified — all three ADR links checked, with a control

adr/0003-multi-stage-operator-gate.md          ✅ resolves
adr/0004-push-trigger-manifest-rolling-pr.md   ✅ resolves
adr/0007-manifest-commit-lifecycle.md          🔴 BROKEN

CONTROL: docs/VERSIONING.md itself resolves via the same check
         ⇒ the existence test discriminates; the failure is real, not a broken probe

Independently reproduced by two chambers.

⚠️ Why this one matters more than a typical dead link

It sits in the paragraph defining the path α / path γ contract — inside the "v1.x releases preserve backward compatibility on … documented behavior contracts" bullet.

That is the passage an adopter reads to learn what pinning @v1.x actually guarantees. The ADR it points at is the authority for the contract's semantics.

A stability contract whose supporting ADR 404s is the shape where a reader concludes the guarantee is aspirational.

The link is load-bearing for the document's credibility, not merely for navigation.

Fix

One-line path correction: lifecycle → direct-push.

Worth a sweep of the other docs/** files for the same stale filename while in there — this ADR was presumably renamed at some point and VERSIONING.md may not be the only referrer.

Context

Found while verifying whether #338's SemVer discipline was already memorialized (it is — docs/VERSIONING.md carries all four of its bullets, marked effective at v1.0.0, so #338 is an at-cut checkpoint rather than a pending decision).

⚠️ Filed as a tracker tonight deliberately, with the fix PR left for a fresh session. A tracker needs no reviewer; a doc PR at hour nine would need one at hour nine. Filing now so the finding does not depend on anyone's recall tomorrow.

Refs frankenbit/release-toolkit#338.

## The defect `docs/VERSIONING.md` links ADR-0007 under a filename that does not exist. ``` doc says docs/adr/0007-manifest-commit-lifecycle.md ← 404 actual docs/adr/0007-manifest-commit-direct-push.md ``` ## Verified — all three ADR links checked, with a control ``` adr/0003-multi-stage-operator-gate.md ✅ resolves adr/0004-push-trigger-manifest-rolling-pr.md ✅ resolves adr/0007-manifest-commit-lifecycle.md 🔴 BROKEN CONTROL: docs/VERSIONING.md itself resolves via the same check ⇒ the existence test discriminates; the failure is real, not a broken probe ``` Independently reproduced by two chambers. ## ⚠️ Why this one matters more than a typical dead link It sits in the paragraph defining the **`path α` / `path γ` contract** — inside the *"v1.x releases preserve backward compatibility on … documented behavior contracts"* bullet. That is the passage an adopter reads to learn **what pinning `@v1.x` actually guarantees**. The ADR it points at is the authority for the contract's semantics. > **A stability contract whose supporting ADR 404s is the shape where a reader concludes the guarantee is aspirational.** The link is load-bearing for the document's credibility, not merely for navigation. ## Fix One-line path correction: `lifecycle` → `direct-push`. Worth a sweep of the other `docs/**` files for the same stale filename while in there — this ADR was presumably renamed at some point and `VERSIONING.md` may not be the only referrer. ## Context Found while verifying whether `#338`'s SemVer discipline was already memorialized (it is — `docs/VERSIONING.md` carries all four of its bullets, marked *effective at v1.0.0*, so `#338` is an at-cut checkpoint rather than a pending decision). ⚠️ **Filed as a tracker tonight deliberately, with the fix PR left for a fresh session.** A tracker needs no reviewer; a doc PR at hour nine would need one at hour nine. Filing now so the finding does not depend on anyone's recall tomorrow. Refs frankenbit/release-toolkit#338.

engineer added the

kind/docs

label

2026-08-05 15:24:17 +02:00

engineer added the

priority/low

size/S

labels

2026-08-06 16:39:57 +02:00

engineer commented

2026-08-06 16:45:08 +02:00

Author

Owner

Staleness pass — LIVE, all three verdicts

SYMPTOM   doc links `0007-manifest-commit-lifecycle.md` · actual `0007-manifest-commit-direct-push.md`
CONTROL   0003 → RESOLVES · 0004 → RESOLVES · 0007 → 404   ⇒ the 404 is real, not a broken check
CAUSE     accurate — file has existed as `-direct-push` since dc9b9f1 (#340 ADR scrub)
REMEDY    accurate and complete — VERSIONING.md is the ONLY referrer (1 hit repo-wide)

Fix the link. Nothing else touches it.

## Staleness pass — **LIVE**, all three verdicts ``` SYMPTOM doc links `0007-manifest-commit-lifecycle.md` · actual `0007-manifest-commit-direct-push.md` CONTROL 0003 → RESOLVES · 0004 → RESOLVES · 0007 → 404 ⇒ the 404 is real, not a broken check CAUSE accurate — file has existed as `-direct-push` since dc9b9f1 (#340 ADR scrub) REMEDY accurate and complete — VERSIONING.md is the ONLY referrer (1 hit repo-wide) ``` Fix the link. Nothing else touches it.