Context
Surfaced while reviewing PR #12581 and PR #12584 (the named-section-ref lint, which I approved). Three skill audits/ files reference the sibling references/ directory using a skill-root-relative path (references/<file>.md §N) instead of the file-relative ../references/<file>.md §N. Harmless today (prose refs on unchanged lines), but latent: once #12584 merges, lint-skill-manifest will flag these as broken section-ref target the moment any of their lines is edited (per #12557 changed-line ownership). PR #12581 originally attempted this exact path-fix but it was dropped pre-merge (bundled with an out-of-scope §-ref restyle this review flagged); this ticket lands the legitimate path-fix cleanly on its own.
The Problem
audits/ files live one level below the skill root, but their section-refs are written as if from the root:
.agents/skills/ideation-sandbox/audits/consensus-mandate.md → `references/ideation-sandbox-workflow.md §6.2` (×9 refs)
.agents/skills/ideation-sandbox/audits/tier-2-revalidation.md → `references/ideation-sandbox-workflow.md §6.5` (×2 refs)
.agents/skills/pull-request/audits/consensus-gate-mirror.md → `references/pull-request-workflow.md §6.1.1` (×2 refs)
From audits/, references/... resolves to the non-existent audits/references/...; the correct relative target is ../references/... (the references/ dir is a sibling of audits/).
The Architectural Reality
lint-skill-manifest.mjs (checkSkillReferenceIntegrity, ~`:640) resolves section-ref targets **file-relative** via resolveSkillMarkdownTarget. V-B-A: each target file exists under the skill's references/dir (e.g..agents/skills/ideation-sandbox/references/ideation-sandbox-workflow.md), and the cited numeric anchors (§6.2, §6.5, §6.1.1, etc.) are live headings — so ../references/` resolves cleanly and the refs become lint-valid. This is purely a relative-path correction; no anchor or prose-content change.
The Fix
In the three files above, rewrite the broken references/<file>.md §N section-refs to ../references/<file>.md §N (~13 occurrences total). Re-verify with node ai/scripts/lint/lint-skill-manifest.mjs --base origin/dev (changed lines clean) + a seam grep confirming no audits/-resident references/...§ remains.
Decision Record impact
none (relative-path correctness; aligned-with the #12557/#12584 reference-integrity lint substrate).
Acceptance Criteria
Out of Scope
- Bare-basename refs the lint resolves by basename (not the broken-relative-path class).
- Non-
audits/ skill files (root-resident references/... paths are correct).
- The lint full-scan mode (the periodic-full-scan
[TOOLING_GAP] flagged on #12584 — its own follow-up).
Related
PR #12584 (the lint that will enforce this; my review surfaced the gap), #12557 (changed-line ownership), PR #12581 (dropped the original path-fix), #11319 / #11320 (the byte-budget sub-rule extractions that introduced these audit files).
Live latest-open sweep: checked latest 20 open issues 2026-06-05; no equivalent found.
Origin Session ID: 0f6d0fa0-327f-42ec-b970-e32f388699b4
Retrieval Hint: query_raw_memories("broken references section-ref path skill audits ../references lint-skill-manifest")
Context
Surfaced while reviewing PR #12581 and PR #12584 (the named-section-ref lint, which I approved). Three skill
audits/files reference the siblingreferences/directory using a skill-root-relative path (references/<file>.md §N) instead of the file-relative../references/<file>.md §N. Harmless today (prose refs on unchanged lines), but latent: once #12584 merges,lint-skill-manifestwill flag these asbroken section-ref targetthe moment any of their lines is edited (per #12557 changed-line ownership). PR #12581 originally attempted this exact path-fix but it was dropped pre-merge (bundled with an out-of-scope §-ref restyle this review flagged); this ticket lands the legitimate path-fix cleanly on its own.The Problem
audits/files live one level below the skill root, but their section-refs are written as if from the root:From
audits/,references/...resolves to the non-existentaudits/references/...; the correct relative target is../references/...(thereferences/dir is a sibling ofaudits/).The Architectural Reality
lint-skill-manifest.mjs(checkSkillReferenceIntegrity, ~`:640) resolves section-ref targets **file-relative** viaresolveSkillMarkdownTarget. V-B-A: each target file exists under the skill'sreferences/dir (e.g..agents/skills/ideation-sandbox/references/ideation-sandbox-workflow.md), and the cited numeric anchors (§6.2,§6.5,§6.1.1, etc.) are live headings — so../references/` resolves cleanly and the refs become lint-valid. This is purely a relative-path correction; no anchor or prose-content change.The Fix
In the three files above, rewrite the broken
references/<file>.md §Nsection-refs to../references/<file>.md §N(~13 occurrences total). Re-verify withnode ai/scripts/lint/lint-skill-manifest.mjs --base origin/dev(changed lines clean) + a seam grep confirming noaudits/-residentreferences/...§remains.Decision Record impact
none(relative-path correctness; aligned-with the #12557/#12584 reference-integrity lint substrate).Acceptance Criteria
references/<file>.md §Nsection-refs in the threeaudits/files use../references/<file>.md §N.dangling section ref/broken section-ref target).lint-skill-manifestreports zero new errors on the changed lines.audits/- orgraduated-records/-residentreferences/…§path remains.Out of Scope
audits/skill files (root-residentreferences/...paths are correct).[TOOLING_GAP]flagged on #12584 — its own follow-up).Related
PR #12584 (the lint that will enforce this; my review surfaced the gap), #12557 (changed-line ownership), PR #12581 (dropped the original path-fix), #11319 / #11320 (the byte-budget sub-rule extractions that introduced these audit files).
Live latest-open sweep: checked latest 20 open issues 2026-06-05; no equivalent found.
Origin Session ID: 0f6d0fa0-327f-42ec-b970-e32f388699b4
Retrieval Hint:
query_raw_memories("broken references section-ref path skill audits ../references lint-skill-manifest")