claude-memory: patch audit criteria for navigation pointers — C5 carve-out, C7 stale-highway note, C3 nested CLAUDE.md + @-mention rows, design-smell remediation

[kyle-sexton]

Context

Implementation deliverable of course lane 9 (#2911; decisions locked 2026-08-17, rounds 1–2 user-confirmed). The lane validated claude-memory:audit against the course's navigation-pointer lesson and decided four criteria patches; this issue executes them — do not relitigate the locked decisions. Decision rows: docs/upstream/aihero-steering-lanes.md (lane 9). Criteria live in plugins/claude-memory/skills/audit/reference/criteria.md (a plugin file — patched here, never in-lane).

Harness-claim backing (verified 2026-08-17 against Claude Code v2.1.233; verdict table in docs/upstream/aihero-steering-lanes.md, lane 9): nested CLAUDE.md files below cwd load on demand when Claude reads files in those directories; ancestors load in full at launch; nested files are not auto re-injected after /compact (root is). Label: single-pool (docs-only) with a cure-when-convenient note — cite the docs, phrase accordingly.

Proposed work

• C5 carve-out: distinguish curated navigation pointers to non-obvious, load-bearing docs (KEEP branch) from file-by-file codebase inventories Claude can rebuild itself (still FLAG). If official docs state no navigation posture, mark the carve-out as a repo extension per the provenance rule (update must not overwrite extensions).
• C7 note: one line naming stale pointers as the standing cost of navigation sections ("a stale highway is worse than no highway") — C7 already FAILs on referenced paths that do not exist; the note ties that check to the navigation-section posture.
• C3 placement-table row: "subdirectory-specific conventions → nested CLAUDE.md", with the verified loading semantics above.
• C3 import-row distinction: conversational @-mention is one-turn steering — cheaper than a permanent pointer for one-off needs; @path imports in CLAUDE.md load at launch (already priced by the audit).
• Remediation guidance (design-smell caveat): a pointer that exists because changes must be mirrored across distant folders can mask low cohesion — remediation should consider restructuring ("things that change together live together") before adding a pointer.
• Version bump + CHANGELOG entry for claude-memory.

Acceptance criteria

• C5 carve-out present with KEEP/FLAG branches and (if applicable) extension-provenance marking
• C7 stale-highway note present
• C3 gains the nested-CLAUDE.md destination row with docs-accurate loading semantics
• C3 import row carries the @-mention one-turn-scope distinction
• Remediation guidance carries the restructure-before-pointer consideration
• Version bump + CHANGELOG entry land for claude-memory

References

• docs/upstream/aihero-steering-lanes.md — lane 9 decision rows + harness-claims verdict table
• plugins/claude-memory/skills/audit/reference/criteria.md
• Issue claude-memory: aihero course lane 9: steering-surface validations (navigation pointers, harness claims, auto-memory, /init-then-prune eval) #2911 (lane 9 specification); docs-hygiene: implement write-for-agents — authoring-time skill for agent-consumed markdown #2962 (authoring skill pointed at the design-smell caveat via coordination comment)

Metadata

Field	Value
Category	unspecified
Area	claude-memory
Ecosystem	unspecified

[kyle-sexton]

Coordination from #3003 (write-for-agents build): review caught that its pointer to this issue's future navigation-pointer remediation guidance targeted nothing (the guidance doesn't exist until this lands). The restructure-before-pointer caveat is therefore stated INLINE in docs-hygiene:write-for-agents § "Write pointers that cover their branches" for now. When this criteria patch lands, consider converting that inline sentence to a pointer at the real home so the doctrine keeps one owner.

---

Generated by Claude Code