aidd-lint rule: dead-reference-pointer

jared commented

2026-07-23 11:31:02 +00:00

Owner

Problem

Preventive rule -- no live offense today. The aidd-lint fix pattern is "relocate detail to a references/*.md and point to it" (see step-bulk), which makes pointers load-bearing: a broken pointer silently deletes the relocated instructions from the agent's reachable context. Exemplar of the pattern done right, plugins/os-sdlc/skills/mine-lints/SKILL.md (current):

2. **Triage.** Split each finding into mechanical vs. reviewer residue, per
   `references/reconcile-gate.md`.

Detection

Inputs: a markdown file and its directory on disk.
Algorithm:
1. Collect candidate paths: markdown links and inline-code spans matching /[\w.\/-]+\.md/, resolved relative to the file's directory (also try repo root for plugins/... absolute-style paths).
2. Skip URLs and paths containing </> placeholders.
3. For each resolved path, stat the file; missing -> offense.
Failure message (verbatim contract): "<file>:<line>: points at <path>, which does not exist. Create it or fix the path."
Not autocorrectable.

Correction

-2. **Triage.** Split each finding per `references/triage-criteria.md`.
+2. **Triage.** Split each finding per `references/reconcile-gate.md`.

Pass/fail examples

Must fail: a step referencing references/does-not-exist.md when no such file is on disk.
Must pass: the current mine-lints SKILL.md (both references/reconcile-gate.md and references/implement-cop.md exist); a link to https://example.com/x.md; a templated references/<name>.md placeholder.

Provenance

mine-lints simplification 2026-07-23; consequence of adopting relocate-don't-delete as the standard fix. Part of the aidd-lint system (see mapping ticket).

Implementation plan

Same markdown-lint infra; TDD; fixtures include a temp directory with and without the target file.

## Problem Preventive rule -- no live offense today. The aidd-lint fix pattern is "relocate detail to a references/*.md and point to it" (see step-bulk), which makes pointers load-bearing: a broken pointer silently deletes the relocated instructions from the agent's reachable context. Exemplar of the pattern done right, `plugins/os-sdlc/skills/mine-lints/SKILL.md` (current): ``` 2. **Triage.** Split each finding into mechanical vs. reviewer residue, per `references/reconcile-gate.md`. ``` ## Detection - **Inputs:** a markdown file and its directory on disk. - **Algorithm:** 1. Collect candidate paths: markdown links and inline-code spans matching `/[\w.\/-]+\.md/`, resolved relative to the file's directory (also try repo root for `plugins/...` absolute-style paths). 2. Skip URLs and paths containing `<`/`>` placeholders. 3. For each resolved path, stat the file; missing -> offense. - **Failure message (verbatim contract):** `"<file>:<line>: points at <path>, which does not exist. Create it or fix the path."` - Not autocorrectable. ## Correction ```diff -2. **Triage.** Split each finding per `references/triage-criteria.md`. +2. **Triage.** Split each finding per `references/reconcile-gate.md`. ``` ## Pass/fail examples - **Must fail:** a step referencing `references/does-not-exist.md` when no such file is on disk. - **Must pass:** the current mine-lints SKILL.md (both `references/reconcile-gate.md` and `references/implement-cop.md` exist); a link to `https://example.com/x.md`; a templated `references/<name>.md` placeholder. ## Provenance mine-lints simplification 2026-07-23; consequence of adopting relocate-don't-delete as the standard fix. Part of the aidd-lint system (see mapping ticket). ## Implementation plan Same markdown-lint infra; TDD; fixtures include a temp directory with and without the target file.

jared referenced this issue

2026-07-23 11:31:45 +00:00

aidd-lint: system map (umbrella) #109

jared referenced this issue

2026-07-23 12:09:09 +00:00

aidd-lint: system map (umbrella) #109

jared added the

review

label

2026-07-23 12:44:02 +00:00

jared commented

2026-07-23 12:44:02 +00:00

Author

Owner

Implemented on branch aidd-lint/tier-1 (plugins/os-aidd-lint, cop: dead_reference_pointer.rb). 55-test suite green; report-only corpus scan run. Awaiting human review — open items noted on #109.

jared commented

2026-07-23 12:44:22 +00:00

Author

Owner

Implemented on branch aidd-lint/tier-1 (plugins/os-aidd-lint, cop: dead_reference_pointer.rb). 55-test suite green; report-only corpus scan run. Awaiting human review — open items noted on #109.

jared referenced this issue

2026-07-23 12:44:29 +00:00

aidd-lint: system map (umbrella) #109

jared referenced this issue

2026-07-23 15:40:50 +00:00

aidd-lint: system map (umbrella) #109

jared added the

labels

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

jared commented

2026-08-01 16:43:53 +00:00

Author

Owner

This was generated by AI during triage.

Implemented on main: lib/aidd_lint/cops/dead_reference_pointer.rb, registered in registry.rb (DeadReferencePointer), tests at tests/cops/dead_reference_pointer_test.rb (24 runs, 50 assertions, 0 failures). Closing.

> *This was generated by AI during triage.* Implemented on main: `lib/aidd_lint/cops/dead_reference_pointer.rb`, registered in `registry.rb` (DeadReferencePointer), tests at `tests/cops/dead_reference_pointer_test.rb` (24 runs, 50 assertions, 0 failures). Closing.

jared closed this issue

2026-08-01 16:43:54 +00:00

Rows
Columns

aidd-lint rule: dead-reference-pointer #102

Problem

Detection

Correction

Pass/fail examples

Provenance

Implementation plan