docs(config-audit): v5.0.0 brief + implementation plan

Planning artifacts for v5.0.0 (token-economy round):

- v5-brief.md: scope brief with 22 items (F1-F7 + M1-M8 + N1-N7), revised
  with Avklaringer-section after critical review (N7 dropped, M3+N6 merged,
  N5 promoted to v5.0.0, SC-6/SC-10 reformulated)
- v5-plan.md: 31-step implementation plan in 5 sessions
  (alpha.1 → alpha.2 → beta.1 → rc.1 → release). B+ score (84/100) after
  plan-critic + scope-guardian review addressed all blockers/majors/gaps.
- v5-implementation-log.md: per-session status record (skeleton)

Sessions track via state files (REMEMBER.md, TODO.md gitignored;
implementation-log.md committed; NEXT-SESSION-PROMPT.local.md gitignored).

No code changes in this commit — planning only.

plugins/config-audit/docs/v5-brief.md

@@ -0,0 +1,186 @@
+# 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).

plugins/config-audit/docs/v5-implementation-log.md

@@ -0,0 +1,71 @@
+# config-audit v5.0.0 — Implementation Log
+
+Per-session record of what was done, what was deferred, and what failed.
+Written at the end of each session. State for the next session lives in
+`NEXT-SESSION-PROMPT.local.md` (gitignored).
+
+---
+
+## Planning session (2026-05-01)
+
+**Outcome:** Plan ready for execution.
+
+**Completed:**
+- Read `v5-brief.md` (drafted 2026-04-19)
+- Brief reviewer ran — 5 findings requiring user input
+- User decisions captured:
+  - N7 (cache-hit-digest) dropped from v5.0.0 — moved to post-release
+  - N5 (live tokenizer) moved into v5.0.0 with warn-and-fallback
+  - M3 merged into N6 (single collision scanner)
+  - M1 manifest-fallback approach approved (cache → package.json → "tool count unknown" finding)
+  - SC-6 split to 6a/6b
+  - SC-10 replaced with per-feature coverage requirement
+  - N1 backward-compat for `CA-TOK-*` glob suppression flagged in CHANGELOG
+- Brief revised with "Avklaringer fra konsultasjon 2026-05-01" section (authoritative)
+- Exploration: 7 parallel agents (architecture, task-finder, dependency-tracer, risk-assessor, test-strategist, git-historian, convention-scanner)
+- Plan written: `docs/v5-plan.md` — 31 steps in 5 sessions
+- Adversarial review: plan-critic verdict REPLAN (Grade C, 5 blockers + 8 majors); scope-guardian MIXED (4 gaps)
+- Plan revised to address all 5 blockers + 8 majors + 4 scope-gaps; new score B+ (84/100)
+
+**Open assumptions** (carry into execution):
+1. Anthropic `count_tokens` endpoint accepts plain-text payload, returns `{input_tokens: number}` (Step 26)
+2. MCP servers expose tool count via `tools/list` or `package.json` `tools` field (Steps 14, 18)
+3. `readActiveConfig` performant enough for TOK at scale (Step 6)
+4. Cross-plugin namespace model — to be verified by Step 22a research spike before Step 22b
+5. `baseline-all-a` fixture is genuinely info-only after F3 — Step 3 audit verifies
+
+**Next session:** Session 1 — alpha.1 (F1-F5 + reference cleanup). See `NEXT-SESSION-PROMPT.local.md`.
+
+---
+
+## Session 1 — alpha.1 (TBD)
+
+*Start when ready. Replace this stub with actual log at session end.*
+
+**Steps planned:** 1-9 (incl. 8b)
+
+**Branch strategy:** direct-to-main (Forgejo, pre-authorized).
+
+---
+
+## Session 2 — alpha.2 (TBD)
+
+*Steps 10-17.*
+
+---
+
+## Session 3 — beta.1 (TBD)
+
+*Steps 18, 19, 20, 21, 22a, 22b, 23.*
+
+---
+
+## Session 4 — rc.1 (TBD)
+
+*Steps 24-27.*
+
+---
+
+## Session 5 — release (TBD)
+
+*Steps 28-30, including SC-6b release gate.*