From 685b770cb95ec347172d56a1b935245155e7167f Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Sat, 20 Jun 2026 22:02:01 +0200 Subject: [PATCH] =?UTF-8?q?docs(state):=20v5.7=20Fase=201=20designet=20?= =?UTF-8?q?=E2=80=94=20visjons-diskusjon?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Visjons-diskusjon gjennomført (F1-tuning: korrekt? → optimal?). Visjonen dekomponert i 4 byggeklosser, sekvensert i 2 faser. Fase 1 (optimerings-linse + levende kunnskapsbase) designet og operatør-låst; Fase 2 (maskinvid kampanje + varig backlog) utsatt til eget GO. Låste beslutninger: strukturert register (linsen leser; markdown som speil); ny familie CA-OPT med hybrid motor (determ. pre-filter → opus-analyzer), presisjons-gated. GO-ready plan i docs/v5.7-optimization-lens-plan.md; STATE oppdatert. Ingen produksjonskode (bevisst diskusjons-sesjon). Co-Authored-By: Claude Opus 4.8 (1M context) --- STATE.md | 45 +++++----- docs/v5.7-optimization-lens-plan.md | 126 ++++++++++++++++++++++++++++ 2 files changed, 149 insertions(+), 22 deletions(-) create mode 100644 docs/v5.7-optimization-lens-plan.md diff --git a/STATE.md b/STATE.md index d69e114..36dabdb 100644 --- a/STATE.md +++ b/STATE.md @@ -2,36 +2,37 @@ _Current state-of-play for DENNE pluginen. Auto-injisert ved sesjonsstart. Overskrives (ikke append) ved sesjonsslutt. Historikk → git (STATE.md er tracked). Stier relative til plugin-mappa._ -## Aktiv kontekst (v5.6.0 RELEASED — NESTE SESJON: visjons-diskusjon, ikke kode) -**v5.6.0 released** (`7548a62`, tag `v5.6.0`, catalog-ref `dbbd1ff` i `../catalog`). Hele v5.6 (Foundation+B+C) shipped. Suite **1023**, scanner **14** (`CA-OST`), self-audit **A/A**, readmeCheck passed. +## Aktiv kontekst (v5.6.0 RELEASED — visjon DISKUTERT, v5.7 Fase 1 DESIGNET & GO-ready) +**v5.6.0 released** (`7548a62`, tag `v5.6.0`, catalog-ref `dbbd1ff`). Suite **1023**, scanner **14** (`CA-OST`), self-audit **A/A**. -**→ NESTE SESJON: operatøren vil DISKUTERE produktretning (visjonen under), ikke starte koding.** Ikke hopp til implementering. Start med å lese «Visjon», bekreft forståelse, og diskuter retning/neste steg. (v5.7 D er parkert kandidat, ikke prioritet.) +**Visjons-diskusjonen er gjennomført (2026-06-20).** Vi leste Anthropic-bloggen «Steering Claude Code» + kartla pluginens nåværende kunnskaps-/persistens-arkitektur. Resultat: en konkret, GO-ready plan → **`docs/v5.7-optimization-lens-plan.md`** (les den FØR implementering). -## Visjon (operatørens tanker — 2026-06-20, diskuteres neste sesjon) -Nordstjerne: en plugin som **tuner Claude Code-oppsettet om til en «F1-motor»** — for **ett repo lokalt**, **ett repo helt til rot**, eller **hele maskinen** (config-audit støtter alt disse scope-ene i dag: current/repo/home/full). Skiftet er fra «er konfigen *korrekt*?» (dagens health) mot «er konfigen *optimal / best-practice-tunet*?». Drivere: -- **Uoversiktlig overflate:** CC har enormt mange innstillinger + config-filer spredt over hele disken — umulig for et menneske å følge med manuelt. -- **Beste praksis finnes, men er spredt:** «tricks of the trade» fra Anthropic + eksperter på BÅDE hvordan CC bør settes opp OG hvordan *innholdet* i config-filene bør være (operatørens globale CLAUDE.md har f.eks. Karpathy-inspirerte kodeprinsipper). Hundrevis av videoer/artikler. Nøkkel-ref: Anthropic-blogg «Steering Claude Code: skills, hooks, rules, subagents and more» — `https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more` (IKKE lest ennå — les neste sesjon). Hele v5.5+ steering-model-temaet (`docs/v5.5-steering-model-plan.md`) er et første skritt i denne retningen. -- **Konflikt-aksen:** innstillinger på ulike nivå (user/project/local/plugin/enterprise) kan kollidere — config-audit har CNF/DIS/COL i dag, men dette kan utvides. -- **Synergi `/repo-init`:** operatøren har en `/repo-init`-skill som bl.a. setter opp repo-CLAUDE.md, men er usikker på kvaliteten → evaluer den / koble den mot denne pluginen. -- Full visjon lagret som auto-memory `config-audit-vision` (overlever STATE-overskriving). +## v5.7 Fase 1 — låste beslutninger (2026-06-20) +Visjonen («F1-tuning»: korrekt? → optimal?) dekomponert i 4 byggeklosser. **Fase 1 = blokk 1+2; Fase 2 = blokk 3+4 (utsatt, eget GO).** Operatør-låst: +- **Rekkefølge:** Fase 1 (linse + kunnskapsbase) FØRST, så Fase 2 (kampanje + backlog). +- **Kunnskaps-format:** strukturert register (YAML/JSON) linsen leser; markdown som lesbart speil. +- **Linse-motor:** ny finding-familie (`CA-OPT` foreslått) + hybrid motor (determ. pre-filter → opus-analyzer), presisjons-gated. = v5.7 D «mechanism-fit» løftet til familie, drevet av registeret. -## Gjort denne økten (2026-06-20, lør — pushet) -1. **v5.6 C (`e3b044a`):** ny OST-scanner (`CA-OST-001/002/003`, count 13→14). 001=user/project style uten `keep-coding-instructions:true` (V10); 002=plugin-style `force-for-plugin:true` overstyrer `outputStyle` (V11, keyer `source==='plugin'`); 003=settings `outputStyle`→ukjent = dead config. Byte-stab: bevart frozen v5.0.0 + strippet OST ved compare (`strip-added-scanner.mjs`), KUN SC-5 regenerert. -2. **v5.6.0 release-cut (`7548a62`+tag+catalog):** plugin.json/README-badge/version-history/CHANGELOG + annotert tag + catalog ref-bump. +## Foreslått chunking (ett GO'd-sesjon hver — neste sesjon = Chunk 1) +1. **Chunk 1 — Register-fundament:** strukturert register-format + schema-validering + migrer `knowledge/` + v5.5 V-rader inn + tester (byte-stabil, ingen output-endring). +2. **Chunk 2 — Linsen (`CA-OPT`):** pre-filter + opus-analyzer-agent + humanizer/scoring-wiring + fixtures + byte-stab strip (additiv familie). +3. **Chunk 3 — `knowledge-refresh`:** semi-auto poller (`--dry-run`, stale/candidate, human-godkjente skriv) — den «levende» delen. +Avhengighet: 1 → 2 (linse leser register) → 3 (holder register friskt). ## Åpne tråder / neste steg (prioritert) -1. **Visjons-diskusjon (NESTE SESJON):** les «Visjon» + `config-audit-vision`-memory + Anthropic-bloggen, og diskuter hvordan «F1-tuning» konkret kan realiseres (best-practice-kunnskapsbase, scope-tuning, /repo-init-synergi). Diskusjon FØR kode. -2. **v5.7 D (mechanism-fit) — parkert kandidat, KREVER GO:** heuristisk CLAUDE.md-lint (lifecycle→hook, path-spesifikk→rule). Precision-gated. Passer inn under visjonen, men ikke prioritert isolert. -3. **llm-security KRITISK** (annet repo) + 3 aktive plugins + STATE-sveip — uendret. Egne GO. +1. **v5.7 Fase 1 Chunk 1 — KREVER GO:** start register-fundamentet. Les `docs/v5.7-optimization-lens-plan.md` først. +2. **Fase 2 (kampanje + backlog) — utsatt, eget GO** etter at linsen er validert på ett repo. +3. **Åpne design-detaljer** (i planen): endelig ID-prefix (`CA-OPT`?), YAML vs JSON, refresh-kilder/kadens, `/repo-init`-synergi (linsen som kvalitetsmåler). +4. **llm-security KRITISK** (annet repo) + 3 aktive plugins + STATE-sveip — uendret. Egne GO. ## Gotchas (UFRAVIKELIG) -- **Release-cut (config-audit) = 3 filer + annotert tag + catalog.** `release:`-commit: plugin.json + README (version-badge + ÉN version-history-rad) + CHANGELOG-seksjon. Så `git tag -a vX -m "..."`. Så `../catalog/.claude-plugin/marketplace.json` ref-bump (eget repo/remote `ktg-plugin-marketplace.git`). README «What's New» er IKKE del av cuttet (lagger bevisst på v5.4.0). -- **Scanner-tillegg = strip, IKKE re-seed (POST-B2).** Bevar frozen v5.0.0 via `strip-added-scanner.mjs`; re-seed KUN SC-5. To strip-helpere: `strip-hotspot-load-pattern` (B2-felt) + `strip-added-scanner` (C-scanner). Frozen-komparatorer: json/raw-backcompat + cli/posture/scan-orch-humanizer. -- tests-badge = EKSAKT `ℹ tests N` (`countTestCases`); `readmeCheck.passed:true`. **1023**, scanner **14**. Versjon i plugin.json + README-badge + CHANGELOG + catalog-ref. -- **docs-gate krever ≥3 ikke-ws-linjer i README OG CLAUDE.md for `feat:`** (ikke `release:`). Path-guard tillater Edit på eksisterende `.claude-plugin/plugin.json`. Push-vindu: hverdag 20–23, helg fritt. +- **Scanner-/familie-tillegg = strip, IKKE re-seed (POST-B2).** Bevar frozen v5.0.0 via strip-helpere (`strip-hotspot-load-pattern` + `strip-added-scanner`); re-seed KUN SC-5. `CA-OPT` følger CA-OST-presedensen (bumper `scanners_ok` → strip). +- **Release-cut = 3 filer + annotert tag + catalog.** plugin.json + README (badge + 1 version-history-rad) + CHANGELOG; så `git tag -a`; så `../catalog` ref-bump. tests-badge = `ℹ tests N` (`countTestCases`), `readmeCheck.passed:true`. Nå: **1023**, scanner **14**. +- **Persistens (verifisert):** sesjoner i `~/.claude/config-audit/sessions/` ligger UTENFOR plugin-mappa → overlever reinstall/oppgradering. Fase 2 legger til versjons-felt + migrering. +- Push-vindu: hverdag 20–23, helg fritt. **I dag = lørdag → push tillatt.** docs-gate: `feat:` krever ≥3 ikke-ws-linjer i README+CLAUDE.md (ikke `release:`). ## Scope-gjerde -Hele v5.6 + v5.6.0 release komplett og pushet. Ingen åpen kode-oppgave. **Neste sesjon = diskusjon, ikke implementering.** Alt nytt arbeid (visjon-realisering, v5.7 D, andre repos) = egne GO. +Diskusjons-sesjonen er ferdig: visjon dekomponert, Fase 1 designet & låst, plan skrevet til `docs/`. **Ingen kode skrevet denne økten (bevisst).** Alt implementeringsarbeid (Chunk 1+) = eget GO. Denne økten: STATE + plan-doc + visjons-memory oppdatert. ## Kontinuitet -Tre lag: STATE.md (tracked) + auto-memory (`config-audit-vision` for visjonen) + CLAUDE.md. Oppdater DENNE som siste handling. +Tre lag: STATE.md (tracked) + auto-memory (`config-audit-vision` — nå med låste beslutninger) + CLAUDE.md. Plan-detalj → `docs/v5.7-optimization-lens-plan.md`. Oppdater DENNE som siste handling. diff --git a/docs/v5.7-optimization-lens-plan.md b/docs/v5.7-optimization-lens-plan.md new file mode 100644 index 0000000..8318d85 --- /dev/null +++ b/docs/v5.7-optimization-lens-plan.md @@ -0,0 +1,126 @@ +# v5.7 — Optimization Lens + Living Knowledge Base (Plan) + +> Outcome of the 2026-06-20 vision discussion. This is the **first concrete realization** +> of the operator's "F1-tuning" north star (see auto-memory `config-audit-vision`). The +> shift is from *"is the config **correct**?"* (today's health scanners) to *"is the config +> **optimal / best-practice-tuned**?"*. +> +> **Status: GO-ready design. Implementation is a SEPARATE GO, chunk by chunk.** The +> discussion session deliberately stopped before code (per STATE.md). This doc mirrors the +> verification-protocol format of `docs/v5.5-steering-model-plan.md`. + +## The four building blocks (full vision) + +The vision decomposes into four blocks. v5.7 builds **Fase 1** (blocks 1+2 lite). Blocks +3+4 are **Fase 2** (deferred, own GO). + +| # | Block | Phase | One-liner | +|---|-------|-------|-----------| +| 1 | **Optimization lens** | **Fase 1** | New finding family: "you USE mechanism X, but Y fits this content better" (mechanism-fit). | +| 2 | **Living knowledge base** | **Fase 1** | Structured, provenance-stamped register the lens reads + semi-auto refresh. | +| 3 | Machine-wide campaign | Fase 2 | A durable ledger above sessions: audit N repos over many sessions, resumable, machine-wide roll-up. | +| 4 | Durable backlog + execution | Fase 2 | One cross-repo prioritized backlog (critical/high/med/low) the user picks from; per-repo plans exported to each repo's `docs/`. | + +**Why Fase 1 first (operator-confirmed):** the value of a machine-wide campaign (Fase 2) +depends on the lens being good. Building the campaign shell on today's correctness-only +scanners would underdeliver the vision. So: establish + validate the lens on ONE repo, +then scale. + +## Decisions locked (2026-06-20) + +- **Sequence:** Fase 1 (lens + knowledge) first, then Fase 2 (campaign + backlog). _(operator)_ +- **Knowledge format:** **structured register** (YAML/JSON) the lens reads directly; + markdown kept as a human-readable mirror. _(operator, over markdown-only)_ +- **Lens engine:** **new finding family** with a **hybrid motor** — deterministic + pre-filter → opus analyzer that judges mechanism-fit and cites the register rule; + precision-gated. _(operator, over extend-feature-gap / pure-deterministic-scanner)_ + +## Fase 1 — two deliverables + +### Leveranse A — Living knowledge register + +Today `knowledge/*.md` (8 files) is prose with a `Source: … verified DATE` header, and the +v5.5 V-rows are an ad-hoc table. The foundation exists; what's missing is a +**machine-consumable** form with provenance per claim. + +- **Format:** one register (e.g. `knowledge/best-practices.yaml`), one entry = one + best-practice rule, with fields: + `id / claim / mechanism / recommendation / source-url / verified-date / confidence + {confirmed|inferred|unverified} / lens-check (which detector consumes it)`. +- **Markdown stays** as the readable mirror; the v5.5 V-rows are **migrated into** the + register (formalizing the existing claim→source→CONFIRMED protocol). +- **"Living" =** `/config-audit knowledge-refresh` (semi-auto, **human-approved writes**): + polls CC changelog + Anthropic docs/blog, flags `stale` (older than N days / source + changed) and `candidate` (new practice found), presents for approval. Mirrors the + `architect` plugin's kb-update poll. **No unverified claim is ever auto-written** + (Verifiseringsplikt). + +### Leveranse B — Optimization lens (new family, e.g. `CA-OPT`) + +A new finding layer that reads CLAUDE.md / rules / skills / hooks and checks each against +the register's mechanism-fit rules. Content is already source-anchored from the Anthropic +"Steering Claude Code" blog (read 2026-06-20): + +| Signal in config | Best-practice rule | Source | +|---|---|---| +| Lifecycle phrasing ("after every commit, do X") in CLAUDE.md | → hook (deterministic) | blog | +| Path-specific instruction, unscoped | → path-scoped rule (`paths:`) | blog | +| 30-line procedure in CLAUDE.md | → skill | blog | +| "Never do X" as an instruction | → permission/hook (an instruction is the wrong tool for absolute prohibitions) | blog | +| Custom output-style missing `keep-coding-instructions` | (already covered by CA-OST-001) | blog/docs | + +This is **v5.7 D "mechanism-fit" promoted to a real family**, driven by the register +instead of hardcoded rules. + +- **Hybrid motor:** cheap deterministic pre-filter (line counts, lifecycle keywords, + path-specificity) → opus analyzer agent (sibling of `feature-gap-agent`) that judges fit + and cites the register rule. **Precision-gated** (emit only on high confidence). +- **Overlap with `feature-gap`:** feature-gap = "you DON'T use feature X"; optimization + lens = "you USE mechanism X, but Y fits THIS content better." Decision: **separate + family** to keep those two intents clean. +- Findings fold into existing posture/report/plan flow → **Fase 2 campaign inherits them + for free**. + +## Proposed chunking (one GO'd session each; per `chunk-work-before-compaction`) + +1. **Chunk 1 — Register foundation.** Structured register format + schema validation + + migrate existing `knowledge/` + v5.5 V-rows into it + tests. (No output change → byte-stable.) +2. **Chunk 2 — The lens (`CA-OPT`).** Deterministic pre-filter + opus analyzer agent + + humanizer/scoring wiring + fixtures + byte-stability strip. (New family → additive.) +3. **Chunk 3 — `knowledge-refresh`.** Semi-auto poller: `--dry-run`, stale/candidate + flagging, human-approved writes. (The "living" part.) + +Dependency order: Chunk 1 → Chunk 2 (lens reads register) → Chunk 3 (keeps register fresh). + +## Verification (per plan-quality rule) + +- **Register:** schema validates; every entry has source + verified-date; + `knowledge-refresh --dry-run` lists stale/candidate **without writing**. +- **Lens:** a fixture repo with KNOWN mechanism-fit problems (procedure-in-CLAUDE.md, + unscoped path-rule) → lens flags **exactly** those; **zero false positives** on a clean + fixture. Precision target stated explicitly (lens is precision-gated). +- **Byte-stability:** new `CA-OPT` family is additive → follow the **post-B2 "preserve + frozen + strip"** regime (do NOT re-seed); regen only SC-5 default-output. New scanner + family also bumps `scanners_ok` on the deterministic fixture → mirror the `strip-added-scanner` + precedent from CA-OST (v5.6 C). + +## Fase 2 — deferred (own GO, after Fase 1 validated) + +- **Block 3 — Machine-wide campaign:** a durable campaign ledger above sessions (repo + list + per-repo status pending/audited/planned/implemented + machine-wide roll-up by + severity), resumable across sessions. Start **thin** (ledger + roll-up), not full + orchestration. +- **Block 4 — Durable backlog + execution:** make persistence explicit + versioned/ + migratable; one cross-repo prioritized backlog the user picks from; per-repo plans + optionally exported to each repo's own `docs/` ("planer følger arbeidsstedet"); reuse + existing backup/rollback for execution. +- **Persistence note:** sessions already live in `~/.claude/config-audit/sessions/` + (OUTSIDE the plugin dir → survive uninstall/reinstall/upgrade — verified). Fase 2 adds + an explicit version field + migration so upgrades don't break the ledger. + +## Synergy / open threads + +- **`/repo-init` synergy:** once the lens exists, it becomes the quality meter for what + `/repo-init` produces — evaluate repo-init output with the same lens. +- **Open:** final ID prefix for the family (`CA-OPT` proposed); register file format + (YAML vs JSON); `knowledge-refresh` poll cadence + which sources beyond changelog/blog.