From 8376dab83f593a8c55ec272983f0938fec060056 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Thu, 18 Jun 2026 15:27:36 +0200 Subject: [PATCH] fix(tokens): refresh stale "Opus 4.7" framing to model-neutral + Opus 4.8 anchor MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) Claude-Session: https://claude.ai/code/session_01Ter3E2JSi1Khgmuf2kady8 --- CLAUDE.md | 2 +- README.md | 12 +++++------ commands/help.md | 2 +- commands/manifest.md | 2 +- commands/tokens.md | 8 ++++---- docs/cc-2.1.x-gap-matrix.md | 6 +++--- docs/scanner-internals.md | 8 ++++---- knowledge/cache-telemetry-recipe.md | 2 +- knowledge/configuration-best-practices.md | 4 ++-- ...7-patterns.md => prompt-cache-patterns.md} | 20 ++++++++++--------- scanners/cache-prefix-scanner.mjs | 2 +- scanners/token-hotspots-cli.mjs | 2 +- scanners/token-hotspots.mjs | 8 ++++---- tests/knowledge/knowledge-staleness.test.mjs | 18 +++++++++++++++++ tests/scanners/token-hotspots.test.mjs | 6 ++++++ 15 files changed, 64 insertions(+), 38 deletions(-) rename knowledge/{opus-4.7-patterns.md => prompt-cache-patterns.md} (78%) diff --git a/CLAUDE.md b/CLAUDE.md index 392c292..920efbc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -17,7 +17,7 @@ Analyzes and optimizes Claude Code configuration across three pillars: |---------|-------------| | `/config-audit` | Full audit with auto-scope detection (no setup needed) | | `/config-audit posture` | Quick health scorecard (A-F grades, 10 quality areas incl. Token Efficiency, Plugin Hygiene) | -| `/config-audit tokens` | Opus-4.7-aware token hotspots (6 patterns: cache-breaking, redundant perms, deep imports, oversized cascade, bloated SKILL.md desc, MCP tool-schema budget) — optional `--accurate-tokens` API calibration, `--with-telemetry-recipe` cache-hit recipe pointer | +| `/config-audit tokens` | prompt-cache-aware token hotspots (6 patterns: cache-breaking, redundant perms, deep imports, oversized cascade, bloated SKILL.md desc, MCP tool-schema budget) — optional `--accurate-tokens` API calibration, `--with-telemetry-recipe` cache-hit recipe pointer | | `/config-audit manifest` | Ranked table of every system-prompt token source (CLAUDE.md, plugins, skills, MCP, hooks) sorted by estimated tokens | | `/config-audit feature-gap` | Context-aware feature recommendations grouped by impact | | `/config-audit fix` | Auto-fix deterministic issues with backup + verification | diff --git a/README.md b/README.md index 8d0c200..2b74256 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ ![Tests](https://img.shields.io/badge/tests-792+-brightgreen) ![License](https://img.shields.io/badge/license-MIT-lightgrey) -A Claude Code plugin that checks configuration health, suggests context-aware improvements, and auto-fixes issues — `CLAUDE.md`, `settings.json`, hooks, rules, MCP servers, `@imports`, and plugins. 12 deterministic scanners across 10 quality areas, context-aware feature recommendations, auto-fix with backup/rollback, an Opus-4.7-aware Token Hotspots scanner with optional API-calibrated `--accurate-tokens` mode, plus cache-prefix stability, dead-tool, and cross-plugin collision detection. Zero external dependencies. +A Claude Code plugin that checks configuration health, suggests context-aware improvements, and auto-fixes issues — `CLAUDE.md`, `settings.json`, hooks, rules, MCP servers, `@imports`, and plugins. 12 deterministic scanners across 10 quality areas, context-aware feature recommendations, auto-fix with backup/rollback, a prompt-cache-aware Token Hotspots scanner with optional API-calibrated `--accurate-tokens` mode, plus cache-prefix stability, dead-tool, and cross-plugin collision detection. Zero external dependencies. --- @@ -104,7 +104,7 @@ Claude Code reads instructions from at least 7 different file types across multi This plugin provides three layers of configuration intelligence: -- **Health** — 12 deterministic scanners verify correctness across every configuration file, catching broken imports, deprecated settings, conflicting rules, format errors, permission contradictions, Opus-4.7-era token waste, cache-prefix instability, dead tool grants, and cross-plugin skill collisions +- **Health** — 12 deterministic scanners verify correctness across every configuration file, catching broken imports, deprecated settings, conflicting rules, format errors, permission contradictions, prompt-cache token waste, cache-prefix instability, dead tool grants, and cross-plugin skill collisions - **Opportunities** — context-aware recommendations for Claude Code features that could benefit your specific project, backed by Anthropic's official guidance - **Action** — auto-fix with mandatory backups, syntax validation, rollback support, and a human-in-the-loop workflow for anything non-trivial @@ -303,7 +303,7 @@ Your team configuration changes over time. Track it: |---------|-------------| | `/config-audit` | Full audit with auto-scope detection (no setup needed) | | `/config-audit posture` | Quick health scorecard: A-F grades across 10 quality areas (incl. Token Efficiency, Plugin Hygiene) | -| `/config-audit tokens` | Opus-4.7-aware token hotspots — ranked by estimated waste; 6 patterns + optional `--accurate-tokens` API calibration | +| `/config-audit tokens` | prompt-cache-aware token hotspots — ranked by estimated waste; 6 patterns + optional `--accurate-tokens` API calibration | | `/config-audit manifest` | Ranked table of every system-prompt token source (CLAUDE.md, plugins, skills, MCP, hooks) sorted by estimated tokens | | `/config-audit feature-gap` | Context-aware feature recommendations grouped by impact | | `/config-audit fix` | Auto-fix deterministic issues with backup + verification | @@ -333,7 +333,7 @@ By default, `/config-audit` auto-detects scope from your git context. Override w ## Deterministic Scanners -12 Node.js scanners that perform structural analysis an LLM cannot reliably do: schema validation, circular reference detection, import resolution, conflict detection across scopes, Opus-4.7-aware token-cost analysis, cache-prefix stability, dead-tool detection, and cross-plugin skill collisions. Plus a standalone plugin-health scanner. Zero external dependencies. +12 Node.js scanners that perform structural analysis an LLM cannot reliably do: schema validation, circular reference detection, import resolution, conflict detection across scopes, prompt-cache-aware token-cost analysis, cache-prefix stability, dead-tool detection, and cross-plugin skill collisions. Plus a standalone plugin-health scanner. Zero external dependencies. **Why deterministic?** LLMs are powerful at understanding intent and context. But they cannot reliably validate JSON schemas, detect circular `@import` chains, or catch that your global `settings.json` contradicts your project-level one. These scanners fill that gap — fast, repeatable, and zero false positives on structural issues. @@ -523,12 +523,12 @@ Reference documents that inform the feature-gap agent and context-aware recommen | File | Content | |------|---------| | `claude-code-capabilities.md` | Feature register: 18 config surfaces, Anthropic guidance, relevance table | -| `configuration-best-practices.md` | Per-layer best practices (Opus 4.7 cache-stability guidance) | +| `configuration-best-practices.md` | Per-layer best practices (cache-stability guidance) | | `anti-patterns.md` | Common mistakes mapped to scanner IDs | | `hook-events-reference.md` | All 26 hook events with details | | `feature-evolution.md` | Feature timeline for staleness detection | | `gap-closure-templates.md` | Config-specific templates for closing gaps | -| `opus-4.7-patterns.md` | Token-cost dynamics for Opus 4.7 era — patterns powering the TOK scanner | +| `prompt-cache-patterns.md` | Token-cost dynamics (prompt-cache patterns) — patterns powering the TOK scanner | | `cache-telemetry-recipe.md` | `jq` recipe for verifying prompt-cache hit rate from session transcripts | --- diff --git a/commands/help.md b/commands/help.md index 70b807f..22bf6dd 100644 --- a/commands/help.md +++ b/commands/help.md @@ -32,7 +32,7 @@ if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi |---------|-------------| | `/config-audit` | Full audit with auto-scope detection | | `/config-audit posture` | Quick scorecard with A-F grades per area (10 areas) | -| `/config-audit tokens` | Opus-4.7 token hotspots; optional `--accurate-tokens` API calibration | +| `/config-audit tokens` | prompt-cache token hotspots; optional `--accurate-tokens` API calibration | | `/config-audit manifest` | Ranked table of every system-prompt token source | | `/config-audit feature-gap` | Deep analysis of features you're not using | | `/config-audit fix` | Auto-fix deterministic issues; a copy of every changed file is saved first so you can roll back with one command | diff --git a/commands/manifest.md b/commands/manifest.md index 4b77cda..f2e8bee 100644 --- a/commands/manifest.md +++ b/commands/manifest.md @@ -70,7 +70,7 @@ If `sources.length > 20`, follow the table with: _"Showing top 20 of {N} sources ```markdown **Next steps:** -- `/config-audit tokens` — Opus-4.7 token-hotspot patterns (cache-breaking, redundant perms, deep imports, MCP budget) +- `/config-audit tokens` — prompt-cache token-hotspot patterns (cache-breaking, redundant perms, deep imports, MCP budget) - `/config-audit whats-active` — same data grouped by category, with disable suggestions - `/config-audit feature-gap` — what *could* improve here, grouped by impact ``` diff --git a/commands/tokens.md b/commands/tokens.md index e7c10a1..1840a69 100644 --- a/commands/tokens.md +++ b/commands/tokens.md @@ -1,6 +1,6 @@ --- name: config-audit:tokens -description: Show ranked token hotspots and Opus 4.7 pattern findings — what's costing the most per turn and how to reduce it +description: Show ranked token hotspots and prompt-cache pattern findings — what's costing the most per turn and how to reduce it argument-hint: "[path] [--global]" allowed-tools: Read, Bash model: sonnet @@ -8,7 +8,7 @@ model: sonnet # Config-Audit: Token Hotspots -Show the configuration sources that contribute the most tokens per turn, ranked by estimated tokens, with Opus 4.7-specific recommendations for reducing prompt-cache misses, schema bloat, and deep import chains. +Show the configuration sources that contribute the most tokens per turn, ranked by estimated tokens, with prompt-cache-aware recommendations for reducing cache misses, schema bloat, and deep import chains. Complementary to `/config-audit whats-active`: - **`whats-active`** = inventory view (what loads). @@ -63,7 +63,7 @@ Use the Read tool on `$TMPFILE`. Extract: - `total_estimated_tokens` — top-line number - `hotspots[]` — top 10 ranked sources -- `findings[]` — Opus 4.7 pattern findings (CA-TOK-001..003); each finding in default mode carries humanizer fields (`userImpactCategory`, `userActionLanguage`, `relevanceContext`) alongside the v5.0.0 fields +- `findings[]` — prompt-cache pattern findings (CA-TOK-001..003); each finding in default mode carries humanizer fields (`userImpactCategory`, `userActionLanguage`, `relevanceContext`) alongside the v5.0.0 fields - `counts` — severity breakdown Render as markdown. Group findings by `userImpactCategory` (e.g., "Wasted tokens" vs "Configuration mistake") rather than re-deriving severity prose; lead each line with `userActionLanguage` ("Fix this now", "Fix soon", "Optional cleanup", etc.) so the urgency phrasing stays consistent with the rest of the toolchain. The humanizer already replaced jargon-heavy `title`/`description`/`recommendation` strings with plain-language equivalents — render them verbatim. @@ -111,7 +111,7 @@ rm -f "$TMPFILE" - **`/config-audit whats-active`** — full inventory of what loads (plugins, skills, MCP, hooks) - **`/config-audit posture`** — overall health scorecard (Token Efficiency is the 8th area) - **`/config-audit fix`** — auto-fix deterministic issues (where applicable) -- See `knowledge/opus-4.7-patterns.md` for the full pattern catalogue (CA-TOK-001 … 003) +- See `knowledge/prompt-cache-patterns.md` for the full pattern catalogue (CA-TOK-001 … 003) - **Verify cache hit rate after a fix:** rerun with `--with-telemetry-recipe` to surface the path to `knowledge/cache-telemetry-recipe.md` — a copy-paste `jq` recipe that reads cache hit rate from your session transcripts. Opt-in. The TOK scanner is structural; this recipe is the runtime escape hatch. ``` diff --git a/docs/cc-2.1.x-gap-matrix.md b/docs/cc-2.1.x-gap-matrix.md index 77c9d25..95f34e1 100644 --- a/docs/cc-2.1.x-gap-matrix.md +++ b/docs/cc-2.1.x-gap-matrix.md @@ -164,9 +164,9 @@ Mest actionable nye funn: | surface | cc change | versions | verdict | action | target file | priority | effort | |---|---|---|---|---|---|---|---| | token management | `disableBundledSkills` flagges «unknown» + er uutnyttet token-lever | 2.1.169 | now-wrong | fix-false-positive | scanners/settings-validator.mjs | H | S | -| token management | `disableBundledSkills` kan ANBEFALES (skjuler bundled-skill-desc fra system-prompt) | 2.1.169 | missing | new-feature-gap-check | knowledge/opus-4.7-patterns.md | M | S | -| token management | `opus-4.7-patterns.md` rammet rundt 4.7; lean system prompt-default (2.1.154) senker baseline | 2.1.154, 2.1.170 | now-wrong | update-knowledge | knowledge/opus-4.7-patterns.md | H | M | -| token management | CC truncerer skill-listing ved budsjett-overflow; config-audit kan varsle før | 2.1.178 | partial | new-scanner | knowledge/opus-4.7-patterns.md | M | M | +| token management | `disableBundledSkills` kan ANBEFALES (skjuler bundled-skill-desc fra system-prompt) | 2.1.169 | missing | new-feature-gap-check | knowledge/prompt-cache-patterns.md | M | S | +| token management | `prompt-cache-patterns.md` (rendøpt fra `opus-4.7-patterns.md`); modell-nøytral mekanisme-tekst + ett Opus 4.8-anker | 2.1.154, 2.1.170 | ✅ DONE 2026-06-18 | update-knowledge | knowledge/prompt-cache-patterns.md | H | M | +| token management | CC truncerer skill-listing ved budsjett-overflow; config-audit kan varsle før | 2.1.178 | partial | new-scanner | knowledge/prompt-cache-patterns.md | M | M | | token management | `skillListingBudgetFraction`/`maxSkillDescriptionChars` (UVERIFISERT, under gulv) | ~2.1.105 | missing | update-knowledge | knowledge/claude-code-capabilities.md | L | S | | slash commands | **`/config key=value`** — in-session-anvendelse av settings-anbefalinger (kan refereres i fix/feature-gap-tekst) | 2.1.181 | missing | update-knowledge | knowledge/claude-code-capabilities.md | M | S | | slash commands | `/simplify` → `/code-review` (stale bundled-skill-liste) | 2.1.147 | now-wrong | update-knowledge | knowledge/claude-code-capabilities.md | M | S | diff --git a/docs/scanner-internals.md b/docs/scanner-internals.md index 5db38ec..d1fe7a9 100644 --- a/docs/scanner-internals.md +++ b/docs/scanner-internals.md @@ -18,7 +18,7 @@ Scanner CLI: `node scanners/scan-orchestrator.mjs [--global] [--full-mach | `import-resolver.mjs` | IMP | Broken @imports, circular refs, deep chains, tilde paths | | `conflict-detector.mjs` | CNF | Settings conflicts, permission contradictions, hook duplicates | | `feature-gap-scanner.mjs` | GAP | 25 feature checks across 4 tiers — shown as opportunities, not grades | -| `token-hotspots.mjs` | TOK | Cache-breaking volatile content, redundant tool permissions, deep import chains, oversized cascade, bloated SKILL.md descriptions, MCP tool-schema budget (Opus 4.7 patterns) | +| `token-hotspots.mjs` | TOK | Cache-breaking volatile content, redundant tool permissions, deep import chains, oversized cascade, bloated SKILL.md descriptions, MCP tool-schema budget (prompt-cache patterns) | | `cache-prefix-scanner.mjs` | CPS | Volatile content in lines 31–150 of CLAUDE.md cascade (beyond Pattern A's top-30 window) | | `disabled-in-schema-scanner.mjs` | DIS | Tools listed in BOTH `permissions.deny` AND `permissions.allow` — deny wins, allow entries are dead config | | `collision-scanner.mjs` | COL | Cross-plugin skill name collisions (low); user-vs-plugin overlaps (medium); `details.namespaces` payload | @@ -52,7 +52,7 @@ Scanner CLI: `node scanners/scan-orchestrator.mjs [--global] [--full-mach | `fix-cli.mjs` | CLI: `node fix-cli.mjs [--apply] [--json] [--global]` | | `drift-cli.mjs` | CLI: `node drift-cli.mjs [--save] [--baseline name] [--json]` | | `whats-active.mjs` | CLI: `node whats-active.mjs [--json] [--verbose] [--suggest-disables]` — read-only active-config inventory | -| `token-hotspots-cli.mjs` | CLI: `node token-hotspots-cli.mjs [--json] [--global] [--output-file path] [--accurate-tokens] [--with-telemetry-recipe]` — Opus-4.7 token hotspots ranking with optional API calibration | +| `token-hotspots-cli.mjs` | CLI: `node token-hotspots-cli.mjs [--json] [--global] [--output-file path] [--accurate-tokens] [--with-telemetry-recipe]` — prompt-cache token hotspots ranking with optional API calibration | | `manifest.mjs` | CLI: `node manifest.mjs [--json]` — ranked system-prompt token-source table (v5 N2) | ## Standalone Scanner @@ -67,10 +67,10 @@ Scanner CLI: `node scanners/scan-orchestrator.mjs [--global] [--full-mach | File | Content | |------|---------| | `claude-code-capabilities.md` | Feature register: 18 config surfaces, Anthropic guidance, relevance table | -| `configuration-best-practices.md` | Per-layer best practices (v5: Opus 4.7 cache-stability guidance replaces Sonnet-era 200-line rule) | +| `configuration-best-practices.md` | Per-layer best practices (v5: cache-stability guidance replaces Sonnet-era 200-line rule) | | `anti-patterns.md` | Common mistakes mapped to scanner IDs | | `hook-events-reference.md` | All 26 hook events with details | | `feature-evolution.md` | Feature timeline for staleness detection | | `gap-closure-templates.md` | Config-specific templates for closing gaps | -| `opus-4.7-patterns.md` | Token-cost dynamics for Opus 4.7 era — patterns powering the TOK scanner | +| `prompt-cache-patterns.md` | Token-cost dynamics (prompt-cache patterns) — patterns powering the TOK scanner | | `cache-telemetry-recipe.md` | Manual `jq` recipe for verifying prompt-cache hit rate from session transcripts (v5 M7) | diff --git a/knowledge/cache-telemetry-recipe.md b/knowledge/cache-telemetry-recipe.md index a9d767f..9739bfd 100644 --- a/knowledge/cache-telemetry-recipe.md +++ b/knowledge/cache-telemetry-recipe.md @@ -109,6 +109,6 @@ when structural signal alone isn't enough. ## See also -- `knowledge/opus-4.7-patterns.md` — structural patterns the TOK scanner detects (CA-TOK-001..005) +- `knowledge/prompt-cache-patterns.md` — structural patterns the TOK scanner detects (CA-TOK-001..005) - `knowledge/configuration-best-practices.md` — CLAUDE.md cache-stability guidance - `/config-audit tokens --with-telemetry-recipe` — surfaces a pointer to this file in JSON output diff --git a/knowledge/configuration-best-practices.md b/knowledge/configuration-best-practices.md index 7d631c1..c2a7659 100644 --- a/knowledge/configuration-best-practices.md +++ b/knowledge/configuration-best-practices.md @@ -6,7 +6,7 @@ ## CLAUDE.md -1. **Optimise for prompt-cache stability.** Place stable content in the first 30 lines (cache-friendly prefix); volatile content (timestamps, dynamic counts, rolling activity logs) goes below that threshold or moves to an `@import`-ed file outside the cache prefix. On Opus 4.7 the dominant cost lever is cache reuse, not file length.[^200lines] +1. **Optimise for prompt-cache stability.** Place stable content in the first 30 lines (cache-friendly prefix); volatile content (timestamps, dynamic counts, rolling activity logs) goes below that threshold or moves to an `@import`-ed file outside the cache prefix. On Opus 4.8 the dominant cost lever is cache reuse, not file length.[^200lines] 2. **Use `@import` for specs/docs.** `@path/to/spec.md` inlines the file at session start. Max 5 hops, but keep chains ≤ 2 hops — every `@import` boundary fragments the prompt-cache prefix. Keeps the main file scannable. 3. **Use HTML comments for maintainer notes.** `` is stripped before context injection — zero token cost. 4. **Put personal dev notes in `CLAUDE.local.md`**, not `CLAUDE.md`. Add `CLAUDE.local.md` to `.gitignore`. Team members' sandbox URLs should never appear in git. @@ -94,4 +94,4 @@ --- -[^200lines]: The "keep CLAUDE.md under 200 lines" threshold was a Sonnet-era adherence heuristic — Sonnet's attention quality dropped on longer files, so trimming raw line count was the optimisation lever. Opus 4.7 uses prompt-cache structure as the dominant cost driver: the first 30 lines must stay byte-stable across turns to keep the cache hit, and `@import` boundaries fragment the cached prefix. A 400-line CLAUDE.md with stable structure outperforms a 150-line file whose top contains a daily-rolling activity log. See `knowledge/opus-4.7-patterns.md` for detection IDs (CA-TOK-001..003). +[^200lines]: The "keep CLAUDE.md under 200 lines" threshold was a Sonnet-era adherence heuristic — Sonnet's attention quality dropped on longer files, so trimming raw line count was the optimisation lever. Opus 4.8 uses prompt-cache structure as the dominant cost driver: the first 30 lines must stay byte-stable across turns to keep the cache hit, and `@import` boundaries fragment the cached prefix. A 400-line CLAUDE.md with stable structure outperforms a 150-line file whose top contains a daily-rolling activity log. See `knowledge/prompt-cache-patterns.md` for detection IDs (CA-TOK-001..003). diff --git a/knowledge/opus-4.7-patterns.md b/knowledge/prompt-cache-patterns.md similarity index 78% rename from knowledge/opus-4.7-patterns.md rename to knowledge/prompt-cache-patterns.md index caf09c6..5e4d3c4 100644 --- a/knowledge/opus-4.7-patterns.md +++ b/knowledge/prompt-cache-patterns.md @@ -1,14 +1,16 @@ -# Opus 4.7 Configuration Patterns +# Prompt-Cache Configuration Patterns -> Token-efficiency patterns for Claude Opus 4.7. 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). Last verified 2026-04-19. +> 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. -Opus 4.7 raises the cost ceiling per turn while expanding the context window -and prompt-cache window. Net effect: cache reuse and tool-schema discipline -become the dominant levers for keeping a session affordable. The patterns -below are structural — they can be detected statically by reading config files -without running a session. Cache hit-rate measurement requires runtime -telemetry and is explicitly out of scope. +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 | |---|---------|----------------|----------|-----| diff --git a/scanners/cache-prefix-scanner.mjs b/scanners/cache-prefix-scanner.mjs index 256fb5b..ff42208 100644 --- a/scanners/cache-prefix-scanner.mjs +++ b/scanners/cache-prefix-scanner.mjs @@ -5,7 +5,7 @@ * cached prefix (≤ CACHED_PREFIX_LINES). Distinguishes from TOK Pattern A, * which only inspects the top 30 lines: CPS catches a `!git log` at line 60 * or a `${TIMESTAMP}` at line 100. Volatile content anywhere in the cached - * prefix breaks Opus 4.7 prompt-cache reuse from that line forward. + * prefix breaks prompt-cache reuse from that line forward. * * Volatile patterns extend the TOK set with shell-exec `!` prefix and * `${VAR}` substitutions — both common cache-busters in real CLAUDE.md files. diff --git a/scanners/token-hotspots-cli.mjs b/scanners/token-hotspots-cli.mjs index 9848243..ff0c542 100755 --- a/scanners/token-hotspots-cli.mjs +++ b/scanners/token-hotspots-cli.mjs @@ -1,7 +1,7 @@ #!/usr/bin/env node /** - * token-hotspots CLI — emit ranked token hotspots and Opus 4.7 pattern findings + * token-hotspots CLI — emit ranked token hotspots and prompt-cache pattern findings * for a target repo path. * * Usage: diff --git a/scanners/token-hotspots.mjs b/scanners/token-hotspots.mjs index 1b0d247..12bfbe7 100644 --- a/scanners/token-hotspots.mjs +++ b/scanners/token-hotspots.mjs @@ -1,7 +1,7 @@ /** - * TOK Scanner — Token Hotspots / Opus 4.7 patterns + * TOK Scanner — Token Hotspots / prompt-cache patterns * - * Detects three structural Opus 4.7-era token-efficiency patterns + * Detects three structural prompt-cache token-efficiency patterns * (severities recalibrated for tokens/turn impact in v5 F7): * CA-TOK-001 cache-breaking volatile top in CLAUDE.md (high) * CA-TOK-002 redundant tool/permission declarations (medium) @@ -15,7 +15,7 @@ * a `hotspots` array (≤10 entries, possibly fewer for tiny projects) on the * scanner result. * - * Pattern catalogue: knowledge/opus-4.7-patterns.md + * Pattern catalogue: knowledge/prompt-cache-patterns.md * Token heuristic: estimateTokens() in scanners/lib/active-config-reader.mjs * * Zero external dependencies. @@ -315,7 +315,7 @@ export async function scan(targetPath, discovery) { description: `The first ${VOLATILE_TOP_LINES} lines of ${f.relPath || f.absPath} contain volatile ` + 'tokens (timestamps, session ids, or activity logs). Volatile content above stable ' + - 'content defeats Opus 4.7 prompt-cache reuse on every turn.', + 'content defeats prompt-cache reuse on every turn.', file: f.absPath, evidence: CALIBRATION_NOTE, recommendation: diff --git a/tests/knowledge/knowledge-staleness.test.mjs b/tests/knowledge/knowledge-staleness.test.mjs index 20a5cb5..2928df7 100644 --- a/tests/knowledge/knowledge-staleness.test.mjs +++ b/tests/knowledge/knowledge-staleness.test.mjs @@ -92,3 +92,21 @@ test('configuration-best-practices.md recommends real MCP approval, not a `trust assert.doesNotMatch(md, /Set trust levels explicitly/, 'the invented "set trust levels" advice must be gone'); }); + +// Token-efficiency corpus era-anchor (Fase 4 token-opt). The prompt-cache pattern +// catalogue was frozen at an "Opus 4.7" framing after CC shipped Opus 4.8 (default, +// 2.1.154) and Fable 5 (2.1.170). The mechanics are properties of prompt-caching, +// not of a model, so the corpus anchors the current default (Opus 4.8) once and +// keeps the pattern text model-neutral — preventing a re-freeze at the next bump. +test('prompt-cache pattern catalogue is anchored to Opus 4.8, not frozen at Opus 4.7', () => { + const md = read('prompt-cache-patterns.md'); + assert.match(md, /Opus 4\.8/, 'must name the current default model (Opus 4.8), not a stale 4.7 anchor'); + assert.doesNotMatch(md, /Opus 4\.7/, 'all stale Opus-4.7 era-stamping must be gone from the pattern catalogue'); +}); + +test('configuration-best-practices.md CLAUDE.md cost framing names Opus 4.8, not stale 4.7', () => { + const md = read('configuration-best-practices.md'); + assert.match(md, /Opus 4\.8/, 'the cache-vs-length cost-lever framing must name the current default model'); + assert.doesNotMatch(md, /On Opus 4\.7|Opus 4\.7 uses prompt-cache/, + 'the present-tense Opus-4.7 cost framing (body + footnote) must be refreshed to 4.8'); +}); diff --git a/tests/scanners/token-hotspots.test.mjs b/tests/scanners/token-hotspots.test.mjs index 04d2cc1..f0888dc 100644 --- a/tests/scanners/token-hotspots.test.mjs +++ b/tests/scanners/token-hotspots.test.mjs @@ -61,6 +61,12 @@ describe('TOK scanner — opus-47/cache-breaking', () => { const f = result.findings.find(x => x.id === 'CA-TOK-001'); assert.equal(f.severity, 'high', `expected high after F7, got ${f.severity}`); }); + + it('CA-TOK-001 description carries no stale Opus-4.7 anchor (mechanic is model-agnostic)', () => { + const f = result.findings.find(x => x.id === 'CA-TOK-001'); + assert.doesNotMatch(f.description, /Opus 4\.7/, + 'prompt-cache mechanics are a feature property, not model-specific; do not era-stamp a stale model'); + }); }); describe('TOK scanner — opus-47/redundant-tools', () => {