open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
ktg-plugin-marketplace/plugins/config-audit/docs/v5-brief.md
Kjell Tore Guttormsen 4bd7cd5056 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.
2026-05-01 06:10:44 +02:00

11 KiB
Raw Blame History

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).