ktg-plugin-marketplace/plugins/config-audit/docs/v5-brief.md

# config-audit v5.0.0 — Brief

**Status:** Final input til implementation planning (avklart 2026-05-01)
**Opprettet:** 2026-04-19
**Utgangspunkt:** Kritisk review av v4.0.0 (Opus 4.7-perspektiv)
**Eier:** Kjell Tore Guttormsen

---

## Avklaringer fra konsultasjon 2026-05-01

Disse avklaringene OVERSTYRER tilsvarende felter i seksjonene under. Brief-reviewer
fant 9 inkonsistenser/uklarheter; brukerens beslutninger er kodifisert her.

### Scope-justeringer

- **N7 droppes fra v5.0.0.** Flyttes til "post-v5.0.0 stretch" (krever transcript-parsing
  som motsier non-goals; data-tilgang må løses separat). SC-12 utgår.
- **M3 og N6 slås sammen til N6.** M3 fjernes fra should-fix-listen. N6 flyttes
  fra `rc.1` til `beta.1`. Nytt finding-prefix: `CA-COL-001`.
- **N5 flyttes inn i v5.0.0** (fra v5.1.0) — beholdes som opt-in via `--accurate-tokens`.
  Hvis `ANTHROPIC_API_KEY` mangler: warn + graceful fallback til zero-deps-heuristikk.
  Bruker Anthropic `POST /v1/messages/count_tokens`-endepunktet.

### Korrigerte fil/linje-referanser

- **F7:** Severity-assignments er på 4 linjer (270, 299, 321, 338) i `token-hotspots.mjs`,
  ikke linje 298. Alle fire patterns må rekalibreres mot tokens/tur.
- **F3:** Krever `import { riskScore } from './severity.mjs'` i `scoring.mjs`
  (WEIGHTS bor i severity.mjs, ikke scoring.mjs).
- **F2:** Hovedbug er caller-side: `whats-active.mjs` og lignende sender `kind='item'`
  for MCP-servere. Fix krever både ny `'mcp'`-kind i `estimateTokens` OG endrede caller-kall.

### Reviderte success criteria

- **SC-4:** Avhenger av `--check-readme`-flagg som F6 bygger. Sjekkbar først etter `alpha.2`.
- **SC-6 splittes i to:**
  - **SC-6a:** `node scanners/manifest.mjs <path>` returnerer rangert kilde-tokens-liste
    med korrekt struktur (uavhengig av tokenizer-presisjon).
  - **SC-6b:** Med `--accurate-tokens`: byte-estimat innen ±5% av Anthropic count_tokens-API.
- **SC-10 erstattes:** I stedet for "≥600 tester totalt", krev: alle 543 v4.0.0-tester
  fortsatt grønne + ≥1 fixture-backet test per ny scanner-funksjon (N1-N4, N6) og per
  strukturell endring (F1, F2, F3, M1-M6).
- **SC-11 (ny):** `node scanners/token-hotspots-cli.mjs <path> --accurate-tokens` exit 0
  + output har `calibration.actual_tokens`-felt når API-key finnes; `calibration.skipped: "no-api-key"`
  når ikke.

### Mindre justeringer

- **M1 (MCP tool-count):** Når `tools/list` ikke kan kjøres, fall back til:
  npm-pakke → les `package.json` `tools`-felt; cached `tools/list`-respons; ellers flag
  "tool count unknown" som finding (ikke skip).
- **N1 backward-compat:** Eksisterende `CA-TOK-*`-globs i `.config-audit-ignore` vil
  suppressere det nye `CA-TOK-005`. Flagg eksplisitt i CHANGELOG som "kjent breaking
  change for glob-suppressions".

### Revidert release-plan (autoritativ)

- **v5.0.0-alpha.1** — F1-F5 (TOK-rensing + estimateTokens-fix + scoring-severity-fix).
- **v5.0.0-alpha.2** — M1, M2, M4-M6 (M3 fjernet) + F6, F7.
- **v5.0.0-beta.1** — N1, N2, N3, N4, N6 (collision-scanner flyttet hit fra rc.1).
- **v5.0.0-rc.1** — M7, M8 + N5 (tokenizer-kalibrering).
- **v5.0.0** — Full suite grønn, README oppdatert, CHANGELOG, versjonssync, self-audit grade A.
- **v5.1.0+ (post-release)** — N7 (cache-hit-digest) når data-tilgang er løst.

---

## 1. Hvorfor v5.0.0

v4.0.0 markedsfører seg som "Opus 4.7-aware token optimization" (TOK-scanner, `/config-audit tokens`, Token Efficiency som 8. kvalitetsområde). Kritisk review viser at markedsføringen ikke holder:

- TOK-scanneren importerer `readActiveConfig` og bruker den eksplisitt ikke (`void readActiveConfig` i `scanners/token-hotspots.mjs:31`) — scanneren ser aldri på plugins, skills, MCP-servere eller CLAUDE.md-kaskade som aggregert token-kost.
- 4 TOK-mønstre dekker 29% av 14 identifiserte Opus 4.7-kostdrivere. De største sinkene (MCP tool-schema-eksplosjon, skill-description-bloat, CLAUDE.md-kaskade-sum) har null dekning.
- `estimateTokens` (`scanners/lib/active-config-reader.mjs:29-39`) flater MCP-servere og hooks til 15 tokens hver. En bruker med 5 MCP-servere får rapportert 75 tokens der virkeligheten er 10-20k.
- Area-score ignorerer severity helt (`scanners/lib/scoring.mjs:184`): 1 kritisk og 1 info gir identisk areascore.
- Pattern D (`detectSonnetEra`) motsier pluginens egen v3.0-policy om at minimalt korrekt oppsett = Grade A.

Resten av pluginen (8 strukturelle scannere, backup/rollback, suppression, plugin-health) fungerer og skal ikke rives ned. v5.0.0 er en token-economy-runde, ikke en totalombygging.

---

## 2. Mål for v5.0.0

**Primært:** Gjøre pluginens token-optimalisering reality-based. Etter v5.0.0 skal en bruker som kjører `/config-audit tokens` få konkret, kalibrert innsikt i hva som faktisk koster tokens i deres oppsett — MCP, skills, CLAUDE.md-kaskade, hooks inkludert.

**Sekundært:**
- Severity reflekterer estimert tokens/tur, ikke "hvor trivielt mønsteret er å detektere".
- Area-score tar hensyn til severity.
- README/CLAUDE.md-tall samsvarer med faktisk kode.
- Knowledge-basen reflekterer Opus 4.7-prioriteringer (cache-reuse og schema-disiplin), ikke Sonnet-æra-"tokens er billige".

**Ikke-mål:**
- Runtime-telemetri som kjernefunksjon (bare som opt-in recipe; krever transcript-parsing).
- Full tiktoken-bundling (opt-in `--accurate-tokens` via API er akseptabelt; default skal være zero-deps-heuristikk).
- Kryssrepo-benchmarking eller cloud-telemetri.
- Endringer i secret/credential-scanning-scope (fortsatt delegert til llm-security).

---

## 3. Scope

### Must-fix (7 kritiske)

| ID | Fil/linje | Hva |
|----|-----------|-----|
| F1 | `scanners/token-hotspots.mjs:31` | TOK må faktisk bruke `readActiveConfig` — ikke bare importere den |
| F2 | `scanners/lib/active-config-reader.mjs:29-39` | `estimateTokens` må type-differensiere MCP/hooks, ikke flat 15 tokens |
| F3 | `scanners/lib/scoring.mjs:184` | Area-score må vekte findings etter severity (gjenbruk `riskScore`-WEIGHTS) |
| F4 | `scanners/token-hotspots.mjs:202-229` | Fjern død `take`-logikk + fabrikerte hotspot-padding-entries |
| F5 | `scanners/token-hotspots.mjs:166-178` | Fjern pattern D (`detectSonnetEra`) eller flytt bak `--suggest-features` |
| F6 | `README.md:15,86,111,280,459-474` + `CLAUDE.md` | Legg til self-audit som verifiserer README-tall mot kode |
| F7 | `scanners/token-hotspots.mjs:298` | Severity må følge tokens/tur, ikke detektor-kompleksitet |

### Should-fix (8 mangler)

| ID | Hva |
|----|-----|
| M1 | MCP tool-count per server (parse manifest/`tools/list`, flagg > 15 tools) |
| M2 | Skill-description-lengde (frontmatter, ikke body) — flagg > 500 tegn |
| M3 | Plugin-skill/command-kollisjoner på tvers av aktive plugins |
| M4 | CLAUDE.md-kaskadens totalsum eksponert til TOK — flagg > 10k tokens |
| M5 | Hook-stdout/`additionalContext`-størrelse — flagg hooks som skriver > 50 linjer |
| M6 | `additionalDirectories` inn i `KNOWN_KEYS` + flagg > 2 entries |
| M7 | Cache-telemetri-recipe i knowledge/ + `/config-audit tokens --with-telemetry-recipe` |
| M8 | Knowledge-base-rensing: flytt Sonnet-æra-råd (adherence-basert 200-linjer-grense, kosmetiske tier-3-gaps) mot Opus 4.7-prioriteringer |

### Nye features (prioritert)

| # | Feature | Begrunnelse |
|---|---------|-------------|
| N1 | **MCP Tool-Schema Budget Scanner** — ny finding `CA-TOK-005` | Største token-sink; 10-20k/tur-potensial |
| N2 | **System-Prompt Manifest** — `/config-audit manifest`-kommando | Gjør alle andre TOK-findings forståelige |
| N3 | **Cache-Prefix Stability Analyzer** | Klassifiser segmenter som stable/volatile, ikke bare topp-30-linjer |
| N4 | **Disabled-Tools-Still-In-Schema Detector** | Vanlig mønster: denied tools lastes i schema likevel |
| N5 | **Live Tokenizer Calibration** (`--accurate-tokens`, opt-in) | Senker ±20%-usikkerheten til ±5% for brukere som godtar API-kall |
| N6 | **Cross-Plugin Skill/Command Collision Scanner** | Korrekthet ved heavy plugin use (relevant for KTG med 8 plugins) |
| N7 | **Cache-Hit-Rate Session Digest** — `/config-audit cache-digest` | Eneste sannhetskilde for om token-optimalisering faktisk virker |

---

## 4. Success criteria (testbare)

Etter v5.0.0 skal følgende kunne verifiseres:

1. **TOK bruker `readActiveConfig`.** `grep -n "readActiveConfig(" scanners/token-hotspots.mjs` må vise minst ett faktisk kall, ikke bare `void`.
2. **`estimateTokens` differensierer.** Unit test: MCP-server med 10 tools returnerer > 2000 estimerte tokens, ikke 15.
3. **Area-score reagerer på severity.** Unit test: 1 critical gir lavere score enn 5 lows, holder alt annet likt.
4. **README-tall matcher kode.** `node scanners/self-audit.mjs --check-readme` exit-code 0 — sjekker testfil-count, scanner-count, command-count, agent-count, hook-count, knowledge-count mot README-badges.
5. **MCP tool-count flagges.** Fixture med `.mcp.json` pluss `tools/list`-mock med 20 tools: TOK-scanner produserer `CA-TOK-005` finding.
6. **System-prompt-manifest fungerer.** `node scanners/manifest.mjs <path>` returnerer en rangert liste med kilde + tokens DESC, totalt innenfor ±20% av faktisk summert byte-estimat.
7. **Cache-prefix-analyse.** CLAUDE.md med volatile midt-seksjon genererer finding, ikke bare hvis volatilitet er i topp-30.
8. **Kollisjons-scanner.** Fixture med to plugins som begge eksponerer skill `review`: collision-finding produseres.
9. **Knowledge-basen oppdatert.** Grep etter "Keep under 200 lines" (Sonnet-æra-formulering) i `knowledge/configuration-best-practices.md` returnerer 0 — erstattet av cache-stabilitets-rettet guidance.
10. **Suite-helse.** `node --test 'tests/**/*.test.mjs'` ≥ 600 tester grønne (fra 543 i v4.0.0). Ny scanner-funksjonalitet har fixture-dekning.

---

## 5. Risikoer og avhengigheter

- **Tokenizer-kalibrering** — ingen zero-deps-tokenizer gir 100% nøyaktighet. Godta ±20% default; markér opt-in `--accurate-tokens` som eksperimentell.
- **MCP `tools/list`-tilgang** — krever kjørende MCP-server. Fallback: parse serverens manifest hvis det finnes, ellers bruk cache/estimat.
- **Schema-drift på `.claude.json`-format** — Anthropic kan endre formatet. `readClaudeJsonProjectSlice` har allerede longest-prefix-matching; nye felter må detekteres robust.
- **Breaking changes** — v5.0.0 er major bump. TOK-finding-IDer består (`CA-TOK-001..004`), nye legges til fra `CA-TOK-005`. Suppression-filer fra v4.x skal fortsatt fungere.
- **Self-audit-failure etter bump** — README-sjekken (F6) kan feile ved første push. Godta midlertidig rød self-audit under v5-arbeid; krav om grønn før release-tag.

---

## 6. Release-plan (high-level)

- **v5.0.0-alpha.1** — F1-F5 (TOK-scanner-rensing + estimateTokens-fix + scoring-severity-fix).
- **v5.0.0-alpha.2** — M1-M6 (manglende strukturelle sjekker) + F6-F7 (README-sync + severity-rekalibrering).
- **v5.0.0-beta.1** — N1-N4 (MCP budget, manifest, cache-prefix, disabled-in-schema).
- **v5.0.0-rc.1** — M7-M8 (knowledge-basens opus-4.7-rensing) + N6 (collision-scanner).
- **v5.0.0** — Full suite grønn, README oppdatert, CHANGELOG, versjonssync, selv-audit grade A.
- **v5.1.0** (post-release) — N5 (tokenizer) + N7 (cache-hit-digest) som opt-in features.

---

## 7. Referanser

- **Kritisk review (full):** inline i sesjonen 2026-04-19 (KTG-konsultasjon, Opus 4.7-perspektiv).
- **TOK-scanner:** `scanners/token-hotspots.mjs`
- **Token-heuristikk:** `scanners/lib/active-config-reader.mjs` + `knowledge/opus-4.7-patterns.md`
- **Area-scoring:** `scanners/lib/scoring.mjs`
- **Aktiv v4.0.0:** `README.md`, `CLAUDE.md`
- **Opus 4.7-dekningskartlegging:** reviewets "Mangler"-seksjon (14 punkter, 10 udekkede).