fix(skill): prune orphaned semantic cache entries

[zrh805]

Summary

• prune semantic cache entries after every skill-driven graph build
• hash the full live document, paper, and image corpus so incremental runs retain unchanged entries
• use the same corpus-root hash anchor as the CLI extraction path and keep cleanup best-effort

Verification

• uv run --frozen pytest tests/test_skillgen.py
• uv run --frozen pytest tests/test_cache.py -k semantic_prune
• uv run --frozen python -m tools.skillgen --check
• uv run --frozen python -m tools.skillgen --audit-coverage
• uv run --frozen python -m tools.skillgen --schema-singleton
• uv run --frozen python -m tools.skillgen --monolith-roundtrip
• uv run --frozen python -m tools.skillgen --always-on-roundtrip
• uv run --frozen ruff check tools/skillgen/gen.py tests/test_skillgen.py

Fixes #2307

[graphify-labs]

Looks safe to merge — no coupling regressions and no blocking issues, checked against the code graph (not a self-assessment).

Graphify reviewed this change.

Looks safe to merge — no coupling regressions and no blocking issues, checked against the code graph (not a self-assessment).

---

Graphify review — findings

This PR adds a semantic cache pruning step to the update/watch flow across all the per-agent skill-*.md templates (agents, aider, amp, claw, codex, copilot, devin, droid, kilo, kiro, opencode, etc.). The inserted snippet, placed after save_manifest, hashes the full live semantic corpus and calls prune_semantic_cache to remove orphaned entries, printing a count when any are pruned. Because these skill files are generated, the change also touches the skillgen tooling (fragments, generator constants/helpers, rationale) and the corresponding expected-output fixtures and tests so the generated artifacts stay in sync. The surface area is broad but repetitive—the same block is duplicated across every agent variant, with wording differing slightly between the two comment styles.

No blocking issues surfaced. 3 lower-confidence candidates did not survive cross-model review.

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 1144 functions depend on the 1144 functions this change touches.

Health — grade A; 5 existing hotspot(s) in the area this change touches (pre-existing, not introduced here):

• audit_coverage() — 8 callers, 6 callees (high)
• render() — 12 callers, 4 callees (high)
• main() — 2 callers, 11 callees (medium)
• monolith_roundtrip() — 3 callers, 5 callees (medium)
• test_audit_catches_a_dropped_non_allowlisted_heading() — 0 callers, 6 callees (medium)

Verification — 1144 functions in the blast radius were not formally verified this run (proofs are advisory here).

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

• verification_scope: 1144 function(s) in the blast radius were not formally verified this run

[graphify-labs]

Looks safe to merge — no coupling regressions and no blocking issues, checked against the code graph (not a self-assessment).

Graphify reviewed this change.

Looks safe to merge — no coupling regressions and no blocking issues, checked against the code graph (not a self-assessment).

---

Graphify review — findings

This PR adds a semantic cache pruning step to the post-update/save-manifest section of the graphify skill definition files (skill-agents, skill-aider, skill-amp, skill-codex, skill-copilot, and many other agent variants). The new block hashes the full live semantic corpus via file_hash and calls prune_semantic_cache to remove orphaned entries, printing a count when any are pruned. Corresponding changes appear in the skillgen tooling, expected fixtures, and test files to reflect this added block across the generated skill outputs.

No blocking issues surfaced. 5 lower-confidence candidates did not survive cross-model review.

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 1144 functions depend on the 1144 functions this change touches.

Health — grade A; 5 existing hotspot(s) in the area this change touches (pre-existing, not introduced here):

• audit_coverage() — 8 callers, 6 callees (high)
• render() — 12 callers, 4 callees (high)
• main() — 2 callers, 11 callees (medium)
• monolith_roundtrip() — 3 callers, 5 callees (medium)
• test_audit_catches_a_dropped_non_allowlisted_heading() — 0 callers, 6 callees (medium)

Verification — 1144 functions in the blast radius were not formally verified this run (proofs are advisory here).

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

• verification_scope: 1144 function(s) in the blast radius were not formally verified this run