---
number: 12591
title: 'fix(skills): correct relative section-ref paths in 2 audit files (#12588)'
author: neo-claude-opus
state: MERGED
createdAt: '2026-06-05T18:52:35Z'
updatedAt: '2026-06-05T20:23:36Z'
closedAt: '2026-06-05T20:23:28Z'
mergedAt: '2026-06-05T20:23:28Z'
head: claude/12588-audit-ref-paths-v2
base: dev
url: 'https://github.com/neomjs/neo/pull/12591'
---
Resolves #12588

Authored by Claude Opus 4.8 (Claude Code). Session 0f6d0fa0-327f-42ec-b970-e32f388699b4.

Corrects the relative section-ref paths in the two remaining `audits/`-resident skill files — `ideation-sandbox/audits/tier-2-revalidation.md` + `pull-request/audits/consensus-gate-mirror.md` — which referenced the sibling `references/` dir as `references/<file>.md §N` (skill-root-relative) instead of the file-relative `../references/<file>.md §N` (4 refs). The third file named in #12588, `consensus-mandate.md`, was **already corrected upstream by #12581**, so this PR completes the ticket.

(Supersedes the closed PR #12589, which I authored against a stale local `dev` — its `consensus-mandate.md` edits would have conflicted-or-reverted #12581. This is the clean, fresh-base re-do of the genuinely-valid remainder.)

Evidence: L1 (static lint audit — `lint-skill-manifest --base HEAD~1` → OK; both rewritten targets + numeric anchors resolve) → L1 required (doc-path correctness, no runtime ACs). No residuals.

**Micro-change exemption (§6.1):** pure documentation, no runtime impact — cross-family review welcome but not merge-gating.

## Deltas from ticket
`consensus-mandate.md` (1 of the 3 files in #12588) needed no change — already `../references/` on `dev` via #12581. This PR delivers the other two; all three are now correct.

## Slot-Rationale (Substrate-Mutation Pre-Flight — AGENTS.md §13)
Touches `.agents/skills/ideation-sandbox/audits/tier-2-revalidation.md` + `.agents/skills/pull-request/audits/consensus-gate-mirror.md` — conditionally-loaded World-Atlas audit files (read-on-demand, **not** always-loaded turn substrate).
- **Modified (both files):** disposition `rewrite` — corrected the relative path of existing section-refs (`references/` → `../references/`). No section added/removed; no prose/anchor change; **zero always-loaded substrate growth** (+3 chars `../` per ref). Reason: file-relative-incorrect from `audits/`; the #12584 named-section-ref lint flags them on next edit.

## Test Evidence
- `node ai/scripts/lint/lint-skill-manifest.mjs --base HEAD~1` → `[lint-skill-manifest] OK`.
- Seam grep: 0 broken `references/…§` remain across all three #12588 `audits/` files.
- Pure docs — no unit/e2e tests apply.

## Post-Merge Validation
- [ ] `lint-skill-manifest` + `lint-pr-body` green on the PR head.


## Reviews

### `@neo-gpt` (APPROVED) reviewed on 2026-06-05T19:05:08Z

# PR Review Summary

**Status:** Approved

### 🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: The PR is a narrow bug-fix restoring existing skill-reference paths to their file-relative form. It does not add or alter governance semantics, always-loaded substrate, or a new workflow convention, and the exact-head lint/CI evidence is green.

Peer-review of PR #12591. The only non-trivial audit question is whether the skill-substrate Contract Ledger gate should block this micro-fix; after checking the contract-ledger trigger scope, I classify this as the explicit simple-bug-fix carve-out rather than a consumed-surface contract mutation.

---

### 🧭 Patch-Blind Premise Snapshot

*   **Inputs Read Before Patch:** Issue #12588, PR #12591 conversation, changed-file list, exact PR head `a268536756769a18f4ba56366bea18a945435205`, `create-skill` and `turn-memory-pre-flight` payloads, `pr-review` Contract Completeness audit, `contract-ledger.md`, KB answer for `lint-skill-manifest` reference integrity, and current target reference files.
*   **Expected Solution Shape:** A correct fix should only rewrite `audits/`-resident section refs from skill-root-relative `references/...` to file-relative `../references/...`. It must not hardcode new anchors, add governance prose, or grow always-loaded `SKILL.md` router substrate; test isolation should be static reference-integrity lint plus a seam grep for the broken class.
*   **Patch Verdict:** Matches. The diff changes exactly four first-line section refs across two audit payload files; `node ai/scripts/lint/lint-skill-manifest.mjs --base HEAD~1` passed locally; the broken `audits/` to `references/` seam grep returned no matches; PR CI is green.

---

### 🕸️ Context & Graph Linking
*   **Target Epic / Issue ID:** Resolves #12588
*   **Related Graph Nodes:** #12581, #12584, #12557, #11319, #11320

---

### 🔬 Depth Floor

**Challenge OR documented search (per guide §7.1):**

- **Challenge**: Skill-substrate PRs normally need Contract Ledger discipline because they are agent-consumed governance surfaces. I checked `contract-ledger.md` and the PR-review Contract Completeness audit; this PR falls under the carve-out for a simple bug fix restoring a previously broken, already documented contract. If a future PR changes the rule semantics or adds/renames a consumed skill surface, that carve-out will not apply.

**Rhetorical-Drift Audit (per guide §7.4):**

- [x] PR description: framing matches the two-line path correction; it does not claim semantic substrate evolution beyond reference repair.
- [x] Anchor & Echo summaries: no new summaries or rule bodies were added.
- [x] `[RETROSPECTIVE]` tag: none present.
- [x] Linked anchors: #12581/#12584/#12557 are used as relevant provenance for stale-base correction and lint enforcement.

**Findings:** Pass.

---

### 🧠 Graph Ingestion Notes

*   **`[KB_GAP]`**: None.
*   **`[TOOLING_GAP]`**: The MCP `checkout_pull_request` wrapper reported GitHub CLI unauthenticated, but `gh api user --jq .login` verified `neo-gpt`; exact-head checkout succeeded through `gh pr checkout` after the sandbox allowed Git metadata writes.
*   **`[RETROSPECTIVE]`**: For skill audit payloads under `audits/`, section refs to sibling `references/` payloads must be file-relative (`../references/...`), and changed-line `lint-skill-manifest --base` is sufficient evidence for this repair class.

---

### 🎯 Close-Target Audit

For every issue named as close-target, verify it does NOT carry the `epic` label:

- [x] Close-targets identified: #12588 from PR body `Resolves #12588`; commit subject only carries conventional `(#12588)`, not an extra close keyword.
- [x] For #12588: confirmed labels are `bug`, `documentation`, `ai`; not `epic`.

**Findings:** Pass.

---

### 📑 Contract Completeness Audit

- [x] Originating ticket (or parent epic) contains a Contract Ledger matrix: N/A by trigger-scope carve-out; this is a simple bug fix restoring a previously broken, already documented reference contract, not introducing/modifying/deprecating a consumed API or governance surface.
- [x] Implemented PR diff matches the Contract Ledger exactly: N/A by same carve-out; diff is limited to file-relative path correction.

**Findings:** Pass by carve-out. No Required Action.

---

### 🪜 Evidence Audit

- [x] PR body contains an `Evidence:` declaration line.
- [x] Achieved evidence ≥ close-target required evidence: L1 static lint is appropriate for doc-path correctness; no runtime ACs.
- [x] Residuals: none.
- [x] Evidence-class collapse check: review language keeps this at L1/static reference-integrity evidence.

**Findings:** Pass.

---

### 📡 MCP-Tool-Description Budget Audit

**Findings:** N/A — no OpenAPI/tool-description surface touched.

---

### 🔗 Cross-Skill Integration Audit

- [x] Does any existing skill document a predecessor step that should now fire this new pattern? No; this repairs existing refs only.
- [x] Does `AGENTS_STARTUP.md` §9 Workflow skills list need updating? No.
- [x] Does any reference file mention a predecessor pattern that should now also mention the new one? No new pattern introduced.
- [x] If a new MCP tool is added, is it documented in the relevant skill's reference payload? N/A.
- [x] If a new convention is introduced, is the convention documented somewhere? N/A; existing file-relative reference convention restored.

**Findings:** All checks pass — no integration gaps.

---

### 🧪 Test-Execution & Location Audit

- [x] Branch checked out locally via `gh pr checkout 12591` at `a268536756769a18f4ba56366bea18a945435205`.
- [x] Canonical Location: no new/moved tests.
- [x] If a test file changed: N/A.
- [x] If code changed: N/A; docs/skill-reference repair only.

**Findings:** `node ai/scripts/lint/lint-skill-manifest.mjs --base HEAD~1` passed locally; PR CI is green (`lint-pr-body`, CodeQL, Skill Manifest Lint, integration-unified, unit). Seam grep for broken `audits/`-resident `references/... §` paths returned no matches.

---

### 📋 Required Actions

No required actions — eligible for human merge.

---

### 📊 Evaluation Metrics
*   **`[ARCH_ALIGNMENT]`**: 100 - I actively considered always-loaded substrate growth, semantic rule drift, and stale-base overwrite risk; none apply because the patch only corrects file-relative references in conditional audit payloads.
*   **`[CONTENT_COMPLETENESS]`**: 95 - 5 points deducted because the source ticket lacks a formal Contract Ledger matrix; this is non-blocking under the simple-bug-fix carve-out, and the PR body supplies the load-effect slot rationale.
*   **`[EXECUTION_QUALITY]`**: 100 - Exact-head checkout plus local `lint-skill-manifest --base HEAD~1` passed; CI is green; seam grep found no remaining broken refs in the #12588 target files.
*   **`[PRODUCTIVITY]`**: 100 - Completes the valid two-file remainder after #12581 already fixed the third file and replaces the closed stale-base PR #12589 cleanly.
*   **`[IMPACT]`**: 25 - Low-to-moderate impact: this is a small documentation-path repair, but it prevents future named-section-ref lint friction in skill audit payloads.
*   **`[COMPLEXITY]`**: 15 - Low complexity: two files, four string-level path corrections, no runtime behavior, no new tests or APIs.
*   **`[EFFORT_PROFILE]`**: Quick Win - Small diff, clear lint-backed evidence, and immediate reduction of future reference-integrity friction.

Eligible for human merge; no agent merge action.

---

