config-audit/docs/v5.7-optimization-lens-plan.md

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.