Skip to content

fix(spec): phantom "ADR-0006 D4" citations wedge the merge queue — check:adr-anchors red on main itself since the ADR-0006 decision-letter section landed #12922

Description

@os-elon

Queue-wedging, repo-wide. Every merge-queue group since ~08:29Z fails the same step — Lint & Repo Gates step 61 「ADR anchors + number uniqueness」 — regardless of what the PR touches (observed on the queue groups of #12897, #12901, #12905; #12897 was kicked twice). The gate is a whole-tree invariant and main itself is red:

✗ check-adr-anchors --self-test — live-decision-letters-are-green-today:
ADR-0006 D4 is cited by 1 file(s), but ADR-0006 declares no D4 —
it decides: D1, D1.1, D1.2, D1.3, D2, D3
packages/spec/src/data/object.zod.ts

Mechanism (two individually-green PRs, colliding union)

  • The namespace tombstone in packages/spec/src/data/object.zod.ts:1467 has cited "ADR-0006 D4" since long before today (blame: the tombstone landed with that spelling). No version of ADR-0006 (docs/adr/0006-project-environment-split{,.v2,.v4}.md) has ever declared a D4, and none mentions the object-namespace retirement at all — the citation was phantom from birth. git log -S 'D4' -- 'docs/adr/0006*' is empty.
  • It never fired because ADR-0006 declared no decision letters at all, so the letter check had nothing to bind to.
  • PR docs(adr): record the ADR-0006 API-surface boundary — three surfaces keep project deliberately #12736 (merged ac35e2a2, 07:49Z — the maintainer-ruled ADR-0006 API-surface boundary record) added the ADR's first letter headings (D1–D3 + D1.x). ADR-0006 thereby entered the declared-letters regime and the old D4 citation went dangling. Both PRs were green alone; the union broke main.

Fix (per the gate's own remedy order)

Remedy (a) is unavailable — no letter decides this. Remedy (b): the decision (object namespace retired; module prefix embedded literally in name) is real and enforced (validateNamespacePrefix(), packages/spec/src/kernel/namespace-prefix.ts; parse-path rejection closed by the silent-strip fix the tombstone already cites), but per ADR-0028's own Supersedes note "there is no standalone ADR for that rule today" — ADR-0028 records the literal-prefix contract as current state (its D1–D6 are a Deferred target model, not the shipped decision).

De-letter the citations in the three live source sites — do NOT add a D4 to ADR-0006 (that ADR is the project/environment split; recording an unrelated naming decision there would be a false record, and docs/adr/** is a governed surface besides):

  1. packages/spec/src/data/object.zod.ts:1467 — drop ADR-0006 D4; keep the tombstone's full upgrade prescription; point the record at the enforced literal-prefix contract (ADR-0028's recorded current state / spec/kernel/namespace-prefix.ts).
  2. packages/spec/src/data/object.test.ts:1573 — same in the test name.
  3. packages/spec/src/system/translation.zod.ts:362 — same in the translation tombstone (not flagged by the gate's current scan scope, but the identical phantom; fix it so a scope widening cannot re-wedge the queue).

⛔ Not the fix: loosening check-adr-anchors (the gate's own text forbids it), or touching CHANGELOG.md history (generated record, and the gate's scan reported source only).

Scope: message/comment text only — no schema shape, no runtime behaviour. Clause-②: no.
Verification the PR must show: pnpm check:adr-anchors red on merge-base main (reproducing the exact failure above), green with the fix; the standard dispatch gate union for the touched paths.

Urgency: until this lands the merge queue rejects every PR. The fix PR's own queue group contains the fix, so it passes and un-wedges the queue by landing.

Found while driving #12897 (kicked twice by this exact failure; its maintainer approval remains pinned to its unmoved head 04c7536 — re-arm auto-merge after this lands).

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions