dead-reference-pointer flags placeholder path templates as dead references

jared commented

2026-07-25 21:49:30 +00:00

Owner

Surfaced 2026-07-25 while verifying the new /os-aidd-lint:check skill path (ADR-0064).

The Tier-1 cop dead-reference-pointer treats any backtick/markdown path as a literal file. Docs that legitimately describe a path template containing a placeholder therefore always fail it.

Four current false positives, all pointing at tmp/aidd-tier2/NN.prompt.md where NN is a zero-padded index placeholder, not a filename:

plugins/os-aidd-lint/agents/charter-judge.md:11
plugins/os-aidd-lint/skills/check/SKILL.md:17
plugins/os-aidd-lint/skills/check/SKILL.md:28
plugins/os-aidd-lint/skills/check/SKILL.md:52

These were deliberately left unfixed — rewording docs to dodge the cop would make the wire contract less clear, which is the wrong tradeoff.

This is not specific to os-aidd-lint: any skill documenting a generated-path convention (os-sdlc's tmp/lint-batch/group-NN.txt, os-doc-hygiene's scratch paths) hits the same thing.

Possible directions, none decided: recognise a placeholder convention in path segments; allow an inline opt-out marker; or scope the cop to paths that resolve to a real directory. Needs a decision before implementation — the cop shares PathReferenceScanner with Tier 2's AuthoritySourceResolver (ADR-0060), so widening the matcher has blast radius beyond this cop.

Surfaced 2026-07-25 while verifying the new /os-aidd-lint:check skill path (ADR-0064). The Tier-1 cop `dead-reference-pointer` treats any backtick/markdown path as a literal file. Docs that legitimately describe a *path template* containing a placeholder therefore always fail it. Four current false positives, all pointing at `tmp/aidd-tier2/NN.prompt.md` where `NN` is a zero-padded index placeholder, not a filename: - plugins/os-aidd-lint/agents/charter-judge.md:11 - plugins/os-aidd-lint/skills/check/SKILL.md:17 - plugins/os-aidd-lint/skills/check/SKILL.md:28 - plugins/os-aidd-lint/skills/check/SKILL.md:52 These were deliberately left unfixed — rewording docs to dodge the cop would make the wire contract less clear, which is the wrong tradeoff. This is not specific to os-aidd-lint: any skill documenting a generated-path convention (os-sdlc's `tmp/lint-batch/group-NN.txt`, os-doc-hygiene's scratch paths) hits the same thing. Possible directions, none decided: recognise a placeholder convention in path segments; allow an inline opt-out marker; or scope the cop to paths that resolve to a real directory. Needs a decision before implementation — the cop shares `PathReferenceScanner` with Tier 2's `AuthoritySourceResolver` (ADR-0060), so widening the matcher has blast radius beyond this cop.

jared added the

P3

label

2026-07-25 21:49:30 +00:00

jared commented

2026-07-26 21:35:10 +00:00

Author

Owner

Probable root cause identified, 2026-07-26.

bin/aidd-lint's repo-root detection appears to break when given a RELATIVE path — its dirname walk never escapes the current working directory, so reference paths resolve against the wrong root and produce spurious dead-reference-pointer offenses. Discovered while building the mine-blindspots skill (commit f7c52e1); the skill's ## Setup section now carries a mandatory "pass absolute paths" note at line 12 so a discovery run does not feed these false positives into its own candidate-miss diff.

This may or may not be the same root cause as the originally reported tmp/aidd-tier2/NN.prompt.md placeholder false positive — the placeholder case involves a path that genuinely does not exist (NN is a stand-in), which is a separate matter from root resolution. Both should be checked before closing.

Probable root cause identified, 2026-07-26. `bin/aidd-lint`'s repo-root detection appears to break when given a RELATIVE path — its dirname walk never escapes the current working directory, so reference paths resolve against the wrong root and produce spurious `dead-reference-pointer` offenses. Discovered while building the `mine-blindspots` skill (commit f7c52e1); the skill's `## Setup` section now carries a mandatory "pass absolute paths" note at line 12 so a discovery run does not feed these false positives into its own candidate-miss diff. This may or may not be the same root cause as the originally reported `tmp/aidd-tier2/NN.prompt.md` placeholder false positive — the placeholder case involves a path that genuinely does not exist (NN is a stand-in), which is a separate matter from root resolution. Both should be checked before closing.

jared referenced this issue

2026-07-26 21:54:03 +00:00

os-aidd-lint: dead-reference-pointer path-resolution false positives (consolidated: outside-repo, placeholder, relative-CLI, runtime-artifact) #150

jared commented

2026-07-26 21:54:30 +00:00

Author

Owner

Third false-positive class identified, 2026-07-26.

A separate class from both the placeholder case and the relative-path root-resolution case has been filed as its own issue (#150). It covers references to real files at documented runtime locations outside the repo — specifically os-vault/skills/write/SKILL.md:39 pointing at vault-conventions.md "at the vault root", which exists at ~/Documents/SecondBrain/.

All three classes should be triaged together before any of them is closed, since a single fix to reference resolution may or may not address all three.

## Third false-positive class identified, 2026-07-26. A separate class from both the placeholder case and the relative-path root-resolution case has been filed as its own issue (#150). It covers references to real files at documented runtime locations outside the repo — specifically `os-vault/skills/write/SKILL.md:39` pointing at `vault-conventions.md` "at the vault root", which exists at ~/Documents/SecondBrain/. All three classes should be triaged together before any of them is closed, since a single fix to reference resolution may or may not address all three.

jared referenced this issue

2026-07-27 16:24:43 +00:00

[mine-blindspots hyperthrive corpus] DeadReferencePointer skips leading-slash repo-relative paths (false negative) #162

jared added the

labels

2026-08-01 16:39:00 +00:00

jared referenced this issue

2026-08-01 16:47:16 +00:00

os-aidd-lint: dead-reference-pointer path-resolution false positives (consolidated: outside-repo, placeholder, relative-CLI, runtime-artifact) #150

jared commented

2026-08-01 16:47:24 +00:00

Author

Owner

This was generated by AI during triage.

Consolidated into #150 per its explicit joint-triage request. Verified live: the placeholder-segment gap still reproduces generally (PLACEHOLDER_TOKEN only covers YYYY/MM/DD, not NN-style tokens) even though the four originally-cited lines no longer literal-match after doc rewording — carried into #150 as class 2. The relative-path CLI root-detection bug mentioned in comments is now confirmed reproducing (4 vs 1 hits on the same file, subdir-relative vs absolute) — carried into #150 as class 3. Both remain undecided/needing a maintainer call where noted. Closing as duplicate.

> *This was generated by AI during triage.* Consolidated into #150 per its explicit joint-triage request. Verified live: the placeholder-segment gap still reproduces generally (PLACEHOLDER_TOKEN only covers YYYY/MM/DD, not NN-style tokens) even though the four originally-cited lines no longer literal-match after doc rewording — carried into #150 as class 2. The relative-path CLI root-detection bug mentioned in comments is now confirmed reproducing (4 vs 1 hits on the same file, subdir-relative vs absolute) — carried into #150 as class 3. Both remain undecided/needing a maintainer call where noted. Closing as duplicate.

jared closed this issue

2026-08-01 16:47:25 +00:00

Rows
Columns

dead-reference-pointer flags placeholder path templates as dead references #129

Third false-positive class identified, 2026-07-26.