CI failed on the guard added in 0c3729b, which passed locally. Both were
right: docs/TODO.md sent readers to
`.superpowers/sdd/2026-09-02-versioned-allocation-rules/`, a tool-managed
ledger whose own .gitignore is `*`. It existed on the machine that wrote
the reference and has never been in the repository, so the guard saw a
real file locally and nothing at all in a fresh checkout.
Two fixes, because there were two faults:
- TODO.md now points at the four commit messages that actually record why
those surfaces work as they do — de128e3, 1cb91d3, e3023d0, f94e458 —
and says plainly that the fuller ledger was never committed. Three of
the four brief defects it described are in those messages.
- The guard now checks a path is git-TRACKED, not merely present. That is
the invariant it was always meant to enforce: a path only the author
can follow is exactly the reference a reader cannot. It degrades to a
filesystem check when git cannot answer, and `.superpowers/` joins
docs/superpowers/specs/ as a declared exception — both are named in the
docs precisely because they are not in the repository.
A fresh clone is now the standard the check measures against, so it means
the same thing on a laptop and in CI.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Moving the docs rewrote about thirty cross-references in one go. A
reference left pointing at nothing fails no build, fails no test, and
does not look wrong in review — it is found by the next person who
follows it. That is the same silence eventCapture.test.ts and
cssTokens.test.ts exist for.
Checks markdown links and backticked paths in AGENTS.md, CLAUDE.md,
GEMINI.md, README.md and docs/*.md. A path counts as resolved from either
the file naming it or the repository root, since both conventions are in
use and both are unambiguous to a reader.
Scoped to the docs a reader NAVIGATES. docs/specs/ and docs/plans/ are
excluded on purpose: they are dated records of a moment, and the plan
that names src/App.tsx is describing scaffolding it went on to delete.
Holding history to today's tree would force rewriting the past or
deleting the guard.
One declared exception, with its reason in the source: AGENTS.md §4 names
docs/superpowers/specs/ precisely because it must NOT exist — it is the
tooling default that has to be overridden, or the next spec silently
recreates the old tree.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
