fix(tokens): refresh stale "Opus 4.7" framing to model-neutral + Opus 4.8 anchor

Fase 4 token-opt, Item 1 of gap-review NEXT STEP #2. The prompt-cache pattern corpus + TOK scanner were frozen at an "Opus 4.7" framing after CC shipped Opus 4.8 (default, 2.1.154) and Fable 5 (2.1.170). Model-era facts re-verified against the official changelog cache before editing.

The patterns are properties of prompt-caching, not of any model, so mechanic text is now model-neutral with a single "current default: Opus 4.8" anchor — preventing a re-freeze at the next model bump.

- rename knowledge/opus-4.7-patterns.md -> prompt-cache-patterns.md (git mv, history preserved); 6 reference sites updated
- TOK scanner: line-318 finding text (human-facing) made model-neutral; header + cache-prefix-scanner + CLI comments refreshed
- configuration-best-practices.md body + footnote 4.7 -> 4.8
- human-facing docs: commands/{tokens,help,manifest}.md, project CLAUDE.md, README, docs/scanner-internals.md
- gap-matrix row marked DONE; future Items 2/3 retargeted to new filename

Failing-test-first (Iron Law): +2 knowledge staleness guards (era-anchor + no-refreeze) +1 scanner assertion (no stale model anchor in finding text). Suite 853 -> 856 green; zero snapshot drift; self-audit A(97) PASS. CHANGELOG / v5 plan / ratified gap-plan keep historical opus-4.7-patterns refs (correct record of past state).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ter3E2JSi1Khgmuf2kady8

knowledge/prompt-cache-patterns.md

@@ -0,0 +1,58 @@
+# Prompt-Cache Configuration Patterns
+
+> Token-efficiency patterns for current Claude Code (defaults to Opus 4.8; Fable 5 is the top-capability model). Detection IDs map to TOK scanner findings.
+> Sources: research/01-opus-47-features-token-efficiency.md (Topic 1), research/04-prompt-caching-patterns.md (Topic 4). Patterns verified 2026-04-19; model-era anchor refreshed 2026-06-18.
+
+Current Claude Code defaults to Opus 4.8 (Fable 5 is the top-capability model).
+On these models the cost ceiling per turn is high and both the context window
+and prompt-cache window are large, so cache reuse and tool-schema discipline
+are the dominant levers for keeping a session affordable. These patterns are
+properties of prompt-caching itself, not of any single model — they are
+structural and detectable statically by reading config files without running a
+session. Cache hit-rate measurement requires runtime telemetry and is
+explicitly out of scope.
+
+| # | Pattern | Detection (ID) | Severity | Fix |
+|---|---------|----------------|----------|-----|
+| 1 | Cache-breaking volatile top-of-file content in CLAUDE.md (timestamps, session ids, rolling activity logs above stable content) | CA-TOK-001 | medium | Move volatile sections to the bottom of CLAUDE.md, or extract to an `@import`-ed file that lives outside the prompt-cache prefix. Keep the first 30 lines stable across turns. |
+| 2 | Redundant tool/permission declarations in settings.json (e.g., both `"Read"` and `"Read(**)"`, duplicate Bash matchers, overlapping glob patterns) | CA-TOK-002 | low | Deduplicate the `permissions.allow` and `permissions.deny` arrays. Prefer the most specific entry that still grants the intended access. Each duplicate entry inflates the tool-schema payload sent on every turn. |
+| 3 | Deep `@import` chain in CLAUDE.md (more than 2 hops, e.g., A → B → C → D) | CA-TOK-003 | medium | Flatten the chain to ≤ 2 hops. Each `@import` boundary fragments the prompt-cache prefix; deeply chained imports defeat caching for the deepest content even when it never changes. |
+
+> The v4 sonnet-era signature pattern was removed in v5 F5 — too noisy and not
+> actionable. Hotspots ranking and per-pattern findings cover the same ground
+> with concrete, file-anchored signal.
+
+## Detection notes
+
+- **Pattern 1 (cache-breaking)** is detected by inspecting the first ~30 lines
+  of CLAUDE.md for tokens that look volatile: literal `{timestamp}`, `{uuid}`,
+  `{date}`, `{session}` placeholders, or runs of ISO-timestamp-prefixed lines.
+  The scanner does not attempt to verify cache-hit rate; it flags the *shape*
+  of content that empirically defeats prompt-cache reuse.
+- **Pattern 2 (redundant tools)** is detected by flattening the
+  `permissions.allow` and `permissions.deny` arrays and looking for entries
+  that are strict subsets of broader entries (e.g., `Bash(npm test)` when
+  `Bash(*)` is also present), or exact duplicates.
+- **Pattern 3 (deep imports)** uses the existing IMP scanner's chain depth as
+  the input — anything > 2 hops triggers TOK-003 as well as the IMP finding.
+
+## Threshold calibration
+
+All thresholds in this catalogue are **structural** — derived from the
+existing `estimateTokens(bytes, kind)` heuristic in
+`scanners/lib/active-config-reader.mjs:29-39`. They are intentionally
+conservative until Topic 3 (token-cost model) research is complete. When
+Topic 3 lands, severities for patterns 1–3 will be re-tuned.
+
+The `estimateTokens` heuristic uses ~4 bytes per token for markdown content,
+which is conservative but unverified against an authoritative tokenizer.
+All token counts surfaced by the TOK scanner carry an implicit ±20%
+uncertainty band.
+
+## Severity Scale
+
+| Severity | Meaning |
+|----------|---------|
+| medium | Materially inflates token cost per turn (cache miss, schema bloat) |
+| low | Detectable inefficiency that compounds across long sessions |
+| info | Informational signal — no action required, may indicate room for optimisation |