Specs are meant to be self-contained — readable without the working documents around them — so a spec should never link to or name-reference docs/plan/ or docs/research/. scripts/spec-check.py validates a good deal of spec hygiene (well-formedness, sibling links, status lines, absolute core-spec URLs) but does not check this at all.
A downstream repository that consumes this script recently found six such violations by hand, in three specs: a relative link into docs/plan/, a malformed plan link, and four references to research notes and issues. All had been present for some time with the check passing green.
Suggested fix. Add a rule that flags, in any spec:
- relative links into
../plan/ or ../research/
PNN / RNN tokens (the plan and research number forms)- prose forms like
research 004 / research note R04
with an exemption for 000-*.md, which documents the naming schemes themselves and would otherwise always fail.
A caveat worth building in from the start. A pure regex will under-report, and it is worth being honest about that in the output rather than implying completeness. The same manual pass turned up four shapes no single-line pattern catches:
Originates from research doc 004. — the word doc splits research from the numberUser chose Option A. — a bare label pointing into another document, with no number at allThe issue text marked captions as "stretch". — an issue reference with no number- a
spec 009 reference that had been line-wrapped, so the two tokens sat on different lines
The line-wrap case is mechanically fixable by matching across a normalized whitespace join. The other three are not, so the check should probably describe itself as catching the resolvable-reference forms rather than as proving self-containment.
No urgency — this is a hygiene gate, not a correctness one.
Specs are meant to be self-contained — readable without the working documents around them — so a spec should never link to or name-reference
docs/plan/ordocs/research/.scripts/spec-check.pyvalidates a good deal of spec hygiene (well-formedness, sibling links, status lines, absolute core-spec URLs) but does not check this at all.A downstream repository that consumes this script recently found six such violations by hand, in three specs: a relative link into
docs/plan/, a malformed plan link, and four references to research notes and issues. All had been present for some time with the check passing green.Suggested fix. Add a rule that flags, in any spec:
../plan/or../research/PNN/RNNtokens (the plan and research number forms)research 004/research note R04with an exemption for
000-*.md, which documents the naming schemes themselves and would otherwise always fail.A caveat worth building in from the start. A pure regex will under-report, and it is worth being honest about that in the output rather than implying completeness. The same manual pass turned up four shapes no single-line pattern catches:
Originates from research doc 004.— the worddocsplitsresearchfrom the numberUser chose Option A.— a bare label pointing into another document, with no number at allThe issue text marked captions as "stretch".— an issue reference with no numberspec 009reference that had been line-wrapped, so the two tokens sat on different linesThe line-wrap case is mechanically fixable by matching across a normalized whitespace join. The other three are not, so the check should probably describe itself as catching the resolvable-reference forms rather than as proving self-containment.
No urgency — this is a hygiene gate, not a correctness one.