paths: a stale path that is only a link LABEL is a display name, not a claim - #11
Merged
Conversation
…a claim
see [`docs/STATE-MD-LIFECYCLE.md`](reference/state-md.md) for the field reference
The label went stale. The target resolves. Nobody following that link lands
anywhere wrong, so reporting it argues with a document that is doing its job.
This is not a new rule, it completes one. REF_DEFINITION already skips the
reference form `[label]: target` on exactly this reasoning. Judging the inline form
while skipping the reference form was an inconsistency rather than a position, and
the inline form is the common one: 137,937 of them across the 134 cloned
repositories against a few dozen reference definitions.
MEASURED BEFORE IT WAS BUILT, and the measurement is why it is narrow:
137,937 inline links, 7,426 with a path-shaped label
5,529 where the label is not in the tree and the target resolves
4,838 of those resolve to a URL, and almost all are org/repo slugs used as a
label (shadcn/ui, encode/broadcaster) which were never repository paths
687 resolve to a file on disk, the real class
4 of the 217 corpus findings sit in it, and none was ever filed
A URL target earns no skip, and that is the whole safety of it. This cannot fetch,
and when a repository deletes a file the blob URL pointing at it dies too, so
trusting a URL would turn a real broken reference into silence.
ONLY WHEN THE LABEL DOES NOT RESOLVE, and that condition was added after watching
it over-fire. Skipping every label whose target works turned 85 gsd-core claims
into skips to remove 3 findings; the other 82 were labels naming real files that
the tool was checking correctly. A skip that swallows a passing check buys nothing
and costs coverage. Tightened, gsd-core goes 34 broken/1085 checked to 31/1082 -
three findings, three claims, no collateral. The count shrinking is what showed
this, which is why the skip is printed rather than dropped.
Outside witness, which no other skip family here has: triaging open-gsd/gsd-core#3620
a maintainer listed his own out-of-scope items and named this shape unprompted,
"the link whose label carries a pre-Diataxis name but whose target resolves". The
exclusion had already been made by hand in that filing and he verified it
independently.
173 tests.
inline_link_labels annotates document and root as Path and paths.py never imported it. from __future__ import annotations makes annotations lazy strings, so it parsed, ran, and passed all 173 tests while being wrong - the exact family the lint guard exists for, and ruff found it in milliseconds. Caught by running the guard, and I had already pushed the branch by then. Read the lint output before committing, not after.
'Lint and types' runs ruff format --check and it failed on both new files. The project's line-length is 110 and I had hand-wrapped shorter, so the formatter wanted them joined. Nothing about behaviour. Third time tonight a check existed and I ran it after pushing rather than before: ruff caught an undefined Path the same way. The rule is the charter's own - the tools are not the safeguard, running them is - and it applies to CI's tools too.
melbinjp
added a commit
that referenced
this pull request
Aug 18, 2026
Releases the inline link-label skip from #11. A stale path that is only the label of a link whose target resolves is a display name, not a claim, and gsd-core is where the shape was found - its maintainer named it in his own out-of-scope list while triaging #3620. Running v0.1.3 on that repo reports three findings he has already judged non-issues, which is the wrong thing to hand him.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The label went stale, the target resolves, and nobody following that link lands anywhere wrong.
This completes an existing rule rather than adding one.
REF_DEFINITIONalready skips[label]: targeton exactly this reasoning. Judging the inline form while skipping the reference form was an inconsistency, and the inline form is the common one: 137,937 across the 134 cloned repositories against a few dozen reference definitions.Measured before it was built, and the measurement is why it is narrow:
The URL bucket is almost all org/repo slugs used as labels (
shadcn/ui,encode/broadcaster) which were never repository paths. A URL target earns no skip: docproof cannot fetch, and a deleted file makes a dead blob URL, so trusting one would turn a real broken reference into silence.Only when the label does not resolve, added after watching it over-fire: skipping every label whose target works turned 85 gsd-core claims into skips to remove 3 findings. The other 82 named real files being checked correctly. Tightened: gsd-core goes 34 broken / 1085 checked to 31 / 1082. Three findings, three claims, no collateral.
A gsd-core maintainer named this shape unprompted in his own out-of-scope list while triaging #3620; the exclusion had already been made by hand in that filing.