open/config-audit
1
0
Fork 0
Code Issues Releases 1 Activity
config-audit/docs/cc-2.1.x-fase4-items-2-3-plan.md
Kjell Tore Guttormsen 7bb254780a feat(skill-listing): add SKL scanner for the skill-listing token budget 
Fase 4 Items 2+3 (CC 2.1.114→181 gap-review). New orchestrated scanner
`skill-listing-scanner.mjs` (prefix SKL) flags every active skill whose
description exceeds the verified 1,536-char listing cap (CC 2.1.105, changelog
L1502). Past the cap, Claude Code silently truncates the description the model
reads to route skill invocation — dropping the trigger phrases at the tail.
HOME-scoped over all user + plugin skills via enumerateSkills (COL is the model).

- CA-SKL-001 (medium): description > 1,536 chars. Remediation folds in Item
  2(b) — recommends disableBundledSkills + skillOverrides + trimming
  (designvalg A: no standalone GAP-check, which would fire for nearly everyone).
- Designvalg B: v1 ships the verified cap ONLY. The aggregate 2%-of-context
  listing budget is deferred — it needs a context-window assumption that would
  turn a verified fact into a guess (would carry a CALIBRATION_NOTE if added).
- Choice C: recognize the skillOverrides settings key (CC 2.1.129) in
  KNOWN_KEYS. Left OUT of TYPE_CHECKS — the value is a per-skill object
  (off/user-invocable-only/name-only), not a string; a 'string' check (as the
  plan sketched) would create a NEW false positive. Verify-first deviation.

Registration: scan-orchestrator (13th scanner), humanizer (SKL → 'Wasted
tokens' + static/_default translations), scoring SCANNER_AREA_MAP (→ Token
Efficiency; no 11th area), README badge 12→13, CLAUDE.md (finding-id +
test-count), docs/scanner-internals.md, gap-matrix + plan status notes.

Snapshots reseeded hermetically (SEED_SNAPSHOT/UPDATE_SNAPSHOT): SKL entry with
0 findings in empty HOME, scanners_ok 11→12, claudeMdEstimatedTokens bump from
the CLAUDE.md edits flowing through the cascade. Contamination grep clean.

Suite 868/868 (856 baseline + 11 SKL + 1 skillOverrides). RED→GREEN logged
per cycle.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ter3E2JSi1Khgmuf2kady8
2026-06-18 17:36:28 +02:00

99 lines
9.1 KiB
Markdown
Raw Blame History

# Plan — Fase 4 Items 2 + 3 (skill-listing token-styring)
**Skrevet:** 2026-06-18 · **Scope:** kun `config-audit/` · **Status:** ✅ **LEVERT 2026-06-18.** Designvalg bekreftet: A=fold inn i SKL, B=v1 KUN 1 536-cap (aggregat utsatt), C=`skillOverrides` i KNOWN_KEYS (IKKE TYPE_CHECKS — verdien er objekt; avvik fra §C-skissen, verify-først). Syklus 1+3+4 ferdig; Syklus 2 (aggregat CA-SKL-002) gjenstår som valgfri stretch. Suite 868/868. Detaljer i `STATE.md`.
**Forrige:** Fase 4 Item 1 (4.7→modell-nøytral) levert som `8376dab`. Baseline **856/856 grønn**.
## Mål
Lukke matrise-radene 167 + 169 (skill-listing token-styring): gjøre config-audit i stand til å anbefale/varsle om skill-listing-budsjett før CC selv trunkerer det. Item 2(a) (false-positive) er **allerede gjort** (Batch 1).
---
## Verifiserte fakta (changelog-cache, CC 2.1.181 — re-verifisert 2026-06-18 FØR skriving)
| Fakta | Versjon | Changelog-linje |
|---|---|---|
| `disableBundledSkills` + `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` — skjuler bundled skills/workflows/built-in slash commands fra modellen | **2.1.169** | L176 |
| Skill-listing-truncation-varsel viser nå *antall* berørte beskrivelser | **2.1.178** | L64 |
| Truncation-varsel flyttet fra startup til `/doctor` | 2.1.144 | L666 |
| `skillOverrides`: `off` / `user-invocable-only` / `name-only` (kollapser beskrivelse) | 2.1.129 | L995 |
| Per-beskrivelse listing-cap hevet 250 → **1 536 tegn** + startup-varsel ved truncation | 2.1.105 | L1502 |
| Skill-tegnbudsjett skalerer med kontekstvindu = **2 % av kontekst** | 2.1.32 | L2860 |
**Matrise-korreksjon (verify-først):** rad 170s hypotetiske settings-nøkler `skillListingBudgetFraction` / `maxSkillDescriptionChars` **finnes ikke** som nøkler. Budsjettet (2 % kontekst) og cap-en (1 536 tegn) er interne CC-mekanismer. Ekte config-levere er `skillOverrides` (2.1.129) + `disableBundledSkills` (2.1.169).
---
## Item 2 — `disableBundledSkills` som token-lever (matrise-rad 166 + 167)
### 2(a) — false-positive-fiks → ✅ ALLEREDE GJORT (Batch 1)
`disableBundledSkills` ligger allerede i `KNOWN_KEYS` (`scanners/settings-validator.mjs:25`) + `TYPE_CHECKS` boolean (:53), og dekkes av testen `NEW_KEYS` (`tests/scanners/settings-validator.test.mjs:133,176-180`). **Ingen kode.** Matrise-rad 166 markert DONE.
### 2(b) — anbefaling (matrise-rad 167)
**Designfunn:** GAP-checks (`scanners/feature-gap-scanner.mjs:91` `GAP_CHECKS`) er binære `{id,tier,title,recommendation,check}` der finding fyres når `check()` = false. En ren binær «`disableBundledSkills` ikke satt»-check ville fyre for nær alle brukere → **støy + dårlig råd** (lever-en fjerner ALLE bundled skills; bare verdt det ved faktisk listing-press).
**Anbefalt (DESIGNVALG A — confirm):** IKKE en frittstående GAP-check. Folde `disableBundledSkills`-anbefalingen inn som en **remediation-lever i Item 3s SKL-scanner** (fyres bare ved kvantitativt budsjett-press). Substansen i Item 2(b) leveres dermed via Item 3. Matrise-rad 167 omklassifiseres «folded into SKL (Item 3)».
**Alternativ:** frittstående tier-4 GAP-check gated på antall aktive skills (krever skill-enumerering → samme kobling som Item 3; mer kode, mer støyrisiko).
---
## Item 3 — SKL-scanner: skill-listing-budsjett (matrise-rad 169)
**Ny scanner** `scanners/skill-listing-scanner.mjs`, prefiks **`SKL`** (ledig; bekreftet mot alle eksisterende prefikser). Finding-IDs `CA-SKL-NNN`.
### Hva den gjør
1. **Primær (høy konfidens):** flagg hver aktiv skill-beskrivelse > **1 536 tegn** — verifisert hard cap → CC trunkerer den. Severity medium. Dette er rock-solid (ikke estimat).
2. **Aggregat (estimat, lavere konfidens):** sum av skill-beskrivelse-tegn på tvers av ALLE aktive skills (user + plugin + bundled). Varsle når summen nærmer seg/overskrider budsjett. Budsjett = 2 % av kontekst → **krever kontekstvindu-antakelse** (se DESIGNVALG B). Merk med `CALIBRATION_NOTE`-mønster (jf. TOK) og ±-usikkerhet — IKKE lat som vi vet brukerens kontekstvindu.
3. **Remediation (alle funn):** trim beskrivelse < 1 536; `skillOverrides: name-only` (kollaps); `disableBundledSkills: true` (fjern bundled). ← her bor Item 2(b).
### Gjenbruk (ikke gjenoppfinn)
- **Aktiv-skill-enumerering:** `enumerateSkills(pluginList)` i `scanners/lib/active-config-reader.mjs:465` → `{name, source:'user'|'plugin', pluginName, path, bytes, estimatedTokens}`. Dekker user + plugin skills (bredere enn project-local).
- **Beskrivelse-uttrekk:** `parseFrontmatter(content)?.frontmatter?.description` (`scanners/lib/yaml-parser.mjs`), nøyaktig som TOK pattern F (`token-hotspots.mjs:381-411`). Les fil via `readTextFile` (`lib/file-discovery.mjs`).
- **`estimateTokens()`** (`active-config-reader.mjs:35`) — markdown = bytes/4. Brukes hvis budsjett uttrykkes i tokens.
### Avgrensning mot eksisterende TOK pattern F
TOK pattern F flagger project-local `skill-md` med beskrivelse > **500 tegn** (strukturell «bloat»-heuristikk, `SKILL_DESCRIPTION_THRESHOLD`, `token-hotspots.mjs:53`). SKL er en **annen linse**: ALLE aktive skills (ikke bare project-local) + den **verifiserte 1 536-cap-en** (hard truncation) + aggregat-budsjett. Dokumentér de to linsene eksplisitt i begge scanner-headere så det ikke leses som duplikat.
---
## ⚠️ Åpne designvalg — BEKREFT med operatør FØR kode (per syklus)
- **A — Item 2(b)-plassering:** anbefalt = folde inn i SKL-remediation (ikke frittstående GAP-check). [Alternativ: tier-4 GAP-check.]
- **B — kontekstvindu-antakelse for aggregat-budsjettet:** anbefalt = konservativ default **200k tokens** (2 % ⇒ budsjett), eksplisitt merket estimat m/ `CALIBRATION_NOTE`. Eventuelt: dropp aggregat-sjekken i v1 og lever KUN den verifiserte 1 536-cap-en (høyest konfidens, null gjetting) — minst risiko. [Anbefaler å starte med per-beskrivelse-cap; aggregat som stretch.]
- **C (valgfri relatert quick-win):** `skillOverrides` mangler i `KNOWN_KEYS` → egen unknown-key false-positive (matrise-rad 170, L/S). Hvis SKL anbefaler `skillOverrides`, bør nøkkelen samtidig legges i `KNOWN_KEYS` + `TYPE_CHECKS` (`'string'`) for konsistens. Egen mini-syklus.
---
## Utførelsesrekkefølge (hver = ratifisert failing-test-først, Iron Law)
**Syklus 1 — Item 3 SKL-scanner (per-beskrivelse 1 536-cap):**
1. Failing test: `tests/scanners/skill-listing-scanner.test.mjs` + fixture med en skill-beskrivelse > 1 536 tegn → forvent `CA-SKL-001`. (RED: scanner finnes ikke.)
2. Skriv `scanners/skill-listing-scanner.mjs` (gjenbruk enumerateSkills + parseFrontmatter).
3. Registrer: import + `SCANNERS`-entry i `scanners/scan-orchestrator.mjs:19-65`; humanizer-entry i `lib/humanizer-data.mjs` (`SKL.static` + `_default`) + `SCANNER_TO_CATEGORY` i `lib/humanizer.mjs:30-43` (kategori `'Wasted tokens'`).
4. README-badge `scanners-12` → `13` (validert av `self-audit.mjs countScannerShape()`); CLAUDE.md scanner-tabell + `docs/scanner-internals.md`.
5. Snapshot-reseed (HERMETISK): `SEED_SNAPSHOT=1` (v5.0.0/) + `UPDATE_SNAPSHOT=1` (default-output/) — scan-orchestrator + posture endres hvis fixturen `marketplace-medium` trigges. Verifiser `git diff tests/snapshots/` + kontaminerings-grep.
**Syklus 2 — Item 3 aggregat-budsjett (HVIS designvalg B = inkluder):** failing test for sum-over-budsjett → `CA-SKL-002`; CALIBRATION_NOTE; kontekstvindu-konstant.
**Syklus 3 — Item 2(b) remediation:** verifiser at SKL-funn lister `disableBundledSkills` + `skillOverrides` + trim som levere (test på recommendation-tekst).
**(Valgfri) Syklus 4 — designvalg C:** `skillOverrides` i `KNOWN_KEYS`+`TYPE_CHECKS` + utvid `NEW_KEYS`-testen.
---
## Verifisering (testbare kriterier)
- `node --test 'tests/**/*.test.mjs'` grønn (baseline **856** + nye SKL-tester).
- Failing-test-først bevist per syklus (RED → GREEN logget).
- Fixture med beskrivelse > 1 536 tegn → nøyaktig `CA-SKL`-funn; fixture med korte beskrivelser → 0 SKL-funn.
- `node scanners/self-audit.mjs --check-readme` ren (badge 13 matcher).
- `git diff tests/snapshots/` reseedet bevisst, kontaminerings-grep ren (sadhguru/vegnorm/pluginCount).
- Ingen ny `Opus 4.x`-æra-stempling i ny scanner (gjenbruk modell-nøytral framing fra Item 1).
## Scope-gjerde
Kun `config-audit/`. Item 2(a) ferdig. Items 2(b)/3 = ny kode → ratifisert design (A+B) + failing-test-først per syklus. IKKE auto-eskalér; bekreft A/B FØR første scanner-linje.
## Risiko
- **Aggregat-budsjett er et estimat** (ukjent kontekstvindu) — håndteres med CALIBRATION_NOTE + å lede med den verifiserte 1 536-cap-en. Ved tvil: lever KUN per-beskrivelse-cap i v1.
- **Snapshot-drift:** ny orkestrert scanner endrer scan-orchestrator/posture-snapshots → MÅ reseedes hermetisk (`hermeticEnv()`), ALDRI rå `node scanners/...`.
- **Matrise er agent-generert** (2 kjente versjonsfeil) — fakta over er re-verifisert mot changelog; re-verifiser nye påstander før skriving.
## Pekere
- Kartlegging (denne sesjonen): scanner-registrering, GAP-mekanisme, enumerateSkills, snapshot-mønster — alt ankret i koden over.
- Gap-matrise: `docs/cc-2.1.x-gap-matrix.md` rad 166 (✅ DONE), 167 (Item 2b), 169 (Item 3), 170 (skillOverrides quick-win).
- Mønster-katalog: `knowledge/prompt-cache-patterns.md` (rad 167/169 retargetet hit).
Reference in a new issue View git blame Copy permalink