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.