From 6cfca82885e2aee649d21b9a449baf70641de884 Mon Sep 17 00:00:00 2001
From: Kjell Tore Guttormsen <ktg@humanize.no>
Date: Fri, 1 May 2026 09:45:56 +0200
Subject: [PATCH] fix(config-audit): expose hotspot.path for --accurate-tokens
 calibration + SC-6b PASS
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The v5.0.0-rc.1 N5 implementation looked up hotspot.path in
calibrateAgainstApi() but token-hotspots.mjs only emitted hotspot.source —
calibration silently produced 0 actual_tokens because every iteration hit
the `if (!hotspot?.path) continue` guard.

Fix: file-backed hotspots now expose `path: h.absPath` in the JSON output.
MCP-server hotspots intentionally leave path unset — their tokens are
runtime tool-schema (formula-based: 500 + toolCount × 200), not file
content readable by count_tokens.

SC-6b release-gate verified against tests/fixtures/marketplace-large:
- Actual (count_tokens, claude-opus-4-7): 589 tokens for CLAUDE.md
- Estimated (4-bytes/token byte heuristic): 594 tokens
- Delta: -5 tokens / -0.85% — well within ±5% gate. PASS.

CHANGELOG: documented the fix + SC-6b result inline under [5.0.0].

All 635 tests still green. No estimateTokens tuning required for v5.0.0.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 plugins/config-audit/CHANGELOG.md                |  8 +++++++-
 plugins/config-audit/scanners/token-hotspots.mjs | 12 ++++++++++--
 2 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/plugins/config-audit/CHANGELOG.md b/plugins/config-audit/CHANGELOG.md
index 8973fd0..c330125 100644
--- a/plugins/config-audit/CHANGELOG.md
+++ b/plugins/config-audit/CHANGELOG.md
@@ -78,7 +78,13 @@ Consolidated from `5.0.0-alpha.1` (F1-F5 token-economy round), `5.0.0-alpha.2` (
 - **`mock.method` against ESM module exports does not work** (Node 18+ ESM read-only export bindings). v5 tests use `globalThis.fetch` mocking for `--accurate-tokens` instead — equivalent coverage at the actual external-dependency boundary.
 - **Plugin-vs-built-in collision detection is intentionally not implemented.** Step 22a research spike (`docs/v5-namespace-research.md`, gitignored) could not verify Claude Code's resolution behavior when a plugin command shares a name with a built-in. Treated as info-only; v5.0.1 candidate.
 - **README/CLAUDE.md badge reconciliation** done in Step 28 (this release). `self-audit --check-readme` PASSES against the filesystem. Test count counter switched from file-count to test-case count via subprocess `node --test` parse.
-- **SC-6b release-gate** (±5% tokenizer accuracy against real `count_tokens` API): documented separately in `docs/v5-implementation-log.md` Session 5. Either verified at release time with a live API key, or recorded as deferred — see implementation log for the actual outcome.
+- **`hotspot.path` exposed on file-backed hotspots** (Step 30 fix). The rc.1 `--accurate-tokens` implementation looked up `hotspot.path` but the scanner only emitted `source`. File-backed hotspots now carry `path` (absolute path); MCP-server hotspots leave it unset (they are virtual entries representing runtime tool-schema cost, not file content).
+
+### SC-6b release-gate result (verified 2026-05-01)
+- **PASS — 0.85% under-estimation against real `count_tokens` API.**
+- Fixture: `tests/fixtures/marketplace-large/`. Top-3 hotspots = 1 file-backed (`CLAUDE.md`) + 2 MCP virtuals. MCP entries skipped per design (no readable content; their tokens are formula-based at 500 + toolCount × 200).
+- `CLAUDE.md` actual: 589 tokens (Anthropic `count_tokens`, `claude-opus-4-7`). Estimated: 594 tokens (byte heuristic at 4 bytes/token via `estimateTokens`). Delta: **−5 tokens, −0.85%** — well within the ±5% gate.
+- No tuning of `estimateTokens` heuristic required for v5.0.0.
 
 ## [5.0.0-rc.1] - 2026-05-01
 
diff --git a/plugins/config-audit/scanners/token-hotspots.mjs b/plugins/config-audit/scanners/token-hotspots.mjs
index f5617e2..1b0d247 100644
--- a/plugins/config-audit/scanners/token-hotspots.mjs
+++ b/plugins/config-audit/scanners/token-hotspots.mjs
@@ -245,12 +245,20 @@ async function buildHotspots(discovery, targetPath, activeConfig) {
   const out = [];
   for (let i = 0; i < top.length; i++) {
     const h = top[i];
-    out.push({
+    const entry = {
       source: h.relPath || h.absPath,
       estimated_tokens: h.estimated_tokens,
       rank: i + 1,
       recommendations: hotspotRecommendations(h),
-    });
+    };
+    // Expose the on-disk path for file-backed hotspots so the
+    // --accurate-tokens calibration in token-hotspots-cli can read content.
+    // MCP-server hotspots are virtual (runtime tool-schema, not file content)
+    // so their path stays unset and calibration skips them.
+    if (h.type !== 'mcp-server' && h.absPath) {
+      entry.path = h.absPath;
+    }
+    out.push(entry);
   }
 
   return out;