config-audit/CLAUDE.md

# Config-Audit Plugin

Claude Code Configuration Intelligence — know if your configuration is correct, find what could improve it, fix it automatically.

## What this plugin does

Analyzes and optimizes Claude Code configuration across three pillars:
- **Health** — Deterministic scanners verify correctness, consistency, and completeness
- **Opportunities** — Context-aware recommendations for features that could benefit your project
- **Action** — Auto-fix with backup/rollback

## Commands

### Core (just run `/config-audit` to get started)

| Command | Description |
|---------|-------------|
| `/config-audit` | Full audit with auto-scope detection (no setup needed) |
| `/config-audit posture` | Quick health scorecard (A-F grades, 10 quality areas incl. Token Efficiency, Plugin Hygiene) |
| `/config-audit tokens` | prompt-cache-aware token hotspots (6 patterns: cache-breaking, redundant perms, deep imports, oversized cascade, bloated SKILL.md desc, MCP tool-schema budget), each ranked hotspot tagged with its load pattern (always / on-demand / external) — optional `--accurate-tokens` API calibration, `--with-telemetry-recipe` cache-hit recipe pointer |
| `/config-audit manifest` | Ranked table of every token source (CLAUDE.md, rules, agents, skills, output styles, MCP, hooks) sorted by estimated tokens, each tagged with its load pattern (always-loaded / on-demand / external) + an always-loaded subtotal ("tokens that enter context every turn") |
| `/config-audit feature-gap` | Context-aware feature recommendations grouped by impact (incl. a conditional `disableBundledSkills` lever when the active skill listing is over budget — remediation companion to SKL `CA-SKL-002`) |
| `/config-audit optimize` | Optimization lens (mechanism-fit) — config that works but fits a better mechanism: procedure→skill (CA-OPT-001, deterministic), lifecycle→hook / unscoped path→rule / "never"→permission (prose-judgment via opus `optimization-lens-agent`). Hybrid motor; every finding cites a best-practices-register rule. Agent-driven, **not byte-stable** |
| `/config-audit fix` | Auto-fix deterministic issues with backup + verification |
| `/config-audit rollback` | Restore configuration from backup |
| `/config-audit plan` | Create action plan from audit findings |
| `/config-audit implement` | Execute plan with backups + auto-verify |
| `/config-audit help` | Show all commands |

### Additional

| Command | Description |
|---------|-------------|
| `/config-audit drift` | Compare current config against saved baseline |
| `/config-audit plugin-health` | Audit plugin structure, frontmatter, cross-plugin coherence |
| `/config-audit whats-active` | Read-only inventory of plugins, skills, MCP, hooks, CLAUDE.md active for a repo (with token estimates) |
| `/config-audit knowledge-refresh` | Keep the best-practices register fresh — deterministic stale check (sources older than ~90d) + web candidate poll (CC changelog + Anthropic blog); **human-approved writes only** (Verifiseringsplikt). The "living" half of the knowledge base. Web/judgment-driven, **not byte-stable** |
| `/config-audit campaign` | Machine-wide audit campaign — durable ledger ABOVE sessions: per-repo lifecycle (pending→audited→planned→implemented) + machine-wide roll-up by severity, resumable across sessions. Read-only report (campaign-cli) + **human-approved** writes via a deterministic write-CLI (init/add/set-status). THIN: tracks state, doesn't run audits/fixes. Judgment-driven, **not byte-stable** |
| `/config-audit discover` | Run discovery phase only |
| `/config-audit analyze` | Run analysis phase only |
| `/config-audit interview` | Gather user preferences (opt-in) |
| `/config-audit status` | Show current session state |
| `/config-audit cleanup` | Clean up old sessions |

## Agents

| Agent | Role | Model | Color | Tools |
|-------|------|-------|-------|-------|
| scanner-agent | Find config files | sonnet | cyan | Read, Glob, Grep, Write |
| analyzer-agent | Generate report | sonnet | blue | Read, Glob, Grep, Write |
| planner-agent | Create action plan | opus | yellow | Read, Glob, Write |
| implementer-agent | Execute changes | sonnet | magenta | Read, Write, Edit, Bash, Glob |
| verifier-agent | Verify results | sonnet | purple | Read, Glob, Grep |
| feature-gap-agent | Context-aware feature recommendations | opus | green | Read, Glob, Grep, Write |
| optimization-lens-agent | Mechanism-fit precision gate (prose-judgment lens cases) | opus | orange | Read, Glob, Grep, Write |

## Hooks

| Event | Script | Purpose |
|-------|--------|---------|
| PreToolUse | `auto-backup-config.mjs` | Auto-backup config files before Edit/Write |
| PostToolUse | `post-edit-verify.mjs` | Verify config files after Edit/Write, block on new critical/high |
| SessionStart | `session-start.mjs` | Checks for active (unfinished) sessions |
| Stop | `stop-session-reminder.mjs` | Reminds about current session phase |

## Reference docs (read on demand)

- **Scanner inventory, lib modules, action engines, knowledge base:** `docs/scanner-internals.md`
- **Plain-language output (v5.1.0), humanizer vocabularies, output modes:** `docs/humanizer.md`

## Plain-Language Output (v5.1.0) — summary

Default output of all 18 commands routes through `humanizeEnvelope` from `lib/humanizer.mjs`. Findings get three decorated fields:

- `userImpactCategory` — Configuration mistake / Conflict / Wasted tokens / Dead config / Missed opportunity
- `userActionLanguage` — Fix this now / Fix soon / Fix when convenient / Optional cleanup / FYI (derived from severity)
- `relevanceContext` — `affects-everyone` (default) / `affects-this-machine-only` (`*.local.*` files) / `test-fixture-no-impact`

`--raw` bypasses the humanizer for byte-stable v5.0.0 output. `--json` is also byte-stable. Full detail and Wave 5 lessons: `docs/humanizer.md`.

## Suppressions

Create `.config-audit-ignore` at project root to suppress known findings:
```
CA-SET-003          # Exact ID
CA-GAP-*            # Glob pattern (all GAP findings)
```
Suppressed findings tracked in envelope's `suppressed_findings` for audit trail. Disable with `--no-suppress`.

## Architecture

### Workflow
```
/config-audit  →  discover + analyze (auto)  →  plan  →  implement  →  verify
```
Default: auto-detects scope from git context. Override with `/config-audit full|repo|home|current`. Delta mode: `--delta` (incremental).

### Session Directory
```
~/.claude/config-audit/sessions/{session-id}/
├── scope.yaml, discovery.json, state.yaml
├── findings/, analysis-report.md, action-plan.md
├── backups/, implementation-log.md
└── interview.md (if interview run)
```

### Finding ID Format
`CA-{SCANNER}-{NNN}` — e.g. `CA-CML-001`, `CA-SET-003`, `CA-HKV-002`, `CA-RUL-005`, `CA-TOK-005`, `CA-CPS-001`, `CA-DIS-001`, `CA-COL-001`, `CA-SKL-001`, `CA-OST-001`, `CA-OPT-001`

## Testing

```bash
node --test 'tests/**/*.test.mjs'
```

1138 tests across 65 test files (21 lib + 34 scanner + 1 hook + 1 agent + 3 commands + 1 knowledge + 4 top-level). Test fixtures in `tests/fixtures/`. Top-level humanizer tests: `json-backcompat.test.mjs`, `raw-backcompat.test.mjs`, `scenario-read-test.test.mjs`, `snapshot-default-output.test.mjs`.

### active-config-reader — load-pattern model + rule/agent/output-style enumeration (v5.6 Foundation)

`scanners/lib/active-config-reader.mjs` now enumerates the three source kinds it previously
missed — **rules** (`enumerateRules`), **agents** (`enumerateAgents`), and **output styles**
(`enumerateOutputStyles`) — alongside the existing CLAUDE.md/plugins/skills/hooks/MCP enumerators.
Each new item, plus a pure `deriveLoadPattern(kind, {scoped})` helper, carries a
`loadPattern ∈ {always, on-demand, external}`, `survivesCompaction ∈ {yes, no, n/a}`, and
`derivationConfidence ∈ {confirmed, inferred}` derived from the published Claude Code loading
model (the V-rows in `docs/v5.5-steering-model-plan.md`). `readActiveConfig` exposes `rules`/
`agents`/`outputStyles` arrays + `totals` counts/subtotals (folded into `grandTotal`). This is
**internal plumbing** for v5.6 B (manifest/tokens rendering) — no command output changes yet, so
`--json`/`--raw`/SC-5 stay byte-stable. Output-style discovery is done directly (mirroring
`enumerateSkills`), **not** via a new `file-discovery` type, to keep the discovery surface stable.

The frontmatter parser (`scanners/lib/yaml-parser.mjs`) now also reads **YAML block sequences**
(`paths:\n  - a\n  - b`), not just inline `paths: "a, b"`. This resolves a pre-existing RUL
false-positive (a block-sequence-scoped rule was misread as unscoped). An empty-valued key with
no following `- ` items still resolves to `null` (backwards-compatible); only a real `- ` item
list becomes an array.

### manifest — load-pattern accounting (v5.6 B)

`buildManifest` (`scanners/manifest.mjs`) now consumes the Foundation enumeration. Two changes:

1. **Component-level sources (plugin roll-up dropped).** The coarse `kind:'plugin'` aggregate is
   gone. A plugin contributes via its skills/rules/agents/output-styles/hooks/MCP — each already
   enumerated **once** by `readActiveConfig` — so the old roll-up double-counted them (the plugin
   aggregate's `estimatedTokens` already summed its components). Source kinds are now
   `claude-md`/`skill`/`rule`/`agent`/`output-style`/`mcp-server`/`hook`.
2. **Load-pattern triple on every record + a `summary`.** Each source carries
   `loadPattern`/`survivesCompaction`/`derivationConfidence`. Rules/agents/output-styles
   **propagate** the foundation-derived values (rules vary by `scoped`); CLAUDE.md maps `scope`→
   kind via `CLAUDE_MD_SCOPE_KIND` (all cascade files walk **up**, so all are always-loaded);
   skills are tagged **on-demand** via `deriveLoadPattern('skill-body')` — the measured tokens are
   the skill **body** (paid on invoke), not the tiny always-loaded name+desc listing (tracked by
   `skill-listing-budget`/posture), so tagging the body always would inflate the headline. The new
   `summary` buckets sources into `always`/`onDemand`/`external`/`unknown` `{tokens,count}`; the
   **always-loaded subtotal** ("≈X tokens enter context every turn before you type") is the headline.

**Byte-stability.** manifest is an **environment-aware CLI** → SC-6/SC-7 verify it by
**mode-equivalence** (`--json == --raw`), not byte-equal against a frozen snapshot, and it is not in
SC-5 default-output. Adding fields in place therefore keeps all snapshots green with **no regen**
(verified). `total` changes (de-duped, component-level) — that is the intended correctness fix.

### token-hotspots — load-pattern column (v5.6 B2)

TOK now annotates every ranked hotspot with the same load-pattern triple (`hotspotLoadPattern`
maps each discovery `type`→a `deriveLoadPattern` kind; rules reuse `activeConfig.rules` for precise
`scoped` handling; `claude-md` maps by scope). Two new `deriveLoadPattern` kinds back this:
**`command`** (on-demand — body loads on `/invoke`) and **`harness-config`** (external — settings/
keybindings/`.mcp.json`/hooks.json/plugin.json configure the CLI, **not** the model context, so they
cost no per-turn context tokens). Note the honest split: the `.mcp.json` **file** is `external`,
while the MCP **server**'s tool schemas are a separate `always` hotspot.

**Byte-stability — the opposite of manifest.** token-hotspots **is** a byte-equal SC-6/SC-7 CLI,
**and** its hotspots ride inside the scan-orchestrator + posture payloads, so the change broke
**six** frozen-v5.0.0 comparisons across five test files (json/raw-backcompat + the three Step 5/6/7
humanizer tests). Resolved by **preserving the frozen v5.0.0 baselines**: a shared
`tests/helpers/strip-hotspot-load-pattern.mjs` strips the additive triple before each byte-equal
compare (proves the original schema is byte-identical), and the **SC-5 default-output** snapshots
(scan-orchestrator + token-hotspots) were **regenerated** (`UPDATE_SNAPSHOT=1`) since their job is to
track current output — diff reviewed as additive-only. **Lesson for any future hotspot/scanner-output
field:** grep every frozen-v5.0.0 comparator (it is 5 files, not 2) before assuming the blast radius.

### CML scanner — context-window-scaled char budget

Beyond the line-count checks (200/500 lines, both MEDIUM), the CML scanner mirrors
Claude Code's own startup warning — *"Large CLAUDE.md will impact performance
(X chars > 40.0k)"* — as a `char`-based finding:

- **Char budget** — flags a CLAUDE.md over **~40.0k chars** (CC's startup-warning
  figure at a 200k-context model). CC 2.1.169 scales that threshold with the model's
  context window, so the finding anchors on the conservative 200k window (we cannot
  observe the user's window; the anchor fires earliest) and discloses the relaxed
  ~200,000-char figure at 1M context. Severity MEDIUM (token cost, not an adherence
  cliff). New `CA-CML` finding.

It keys on chars, not lines, so it is complementary to the line checks: a file can be
long by lines yet under budget (short lines), or short by lines yet over it (long lines).
The 200k/1M window constants live in the shared `scanners/lib/context-window.mjs`
(single source of truth, also re-exported by `skill-listing-budget.mjs`). The 40.0k
figure and context-window scaling are verified against the CC changelog (2.1.169) and
the live startup-warning text.

### DIS scanner — permission-rule hygiene

Beyond deny/allow overlap, the DIS scanner now also flags:

- **Ineffective allow wildcards** — unanchored tool-name globs in `permissions.allow`
  (`*`, `B*`, `mcp__*`) that Claude Code silently skips (auto-approve nothing). Valid
  only as a glob-free `mcp__<server>__*`. New `CA-DIS` finding, severity low.
- **`Tool(*)` deny-all glob** — treated as equivalent to a bare deny (`Bash(*)` ≡ `Bash`),
  so a bare allow killed by it is correctly reported as dead config.
- **Forbidden-param rules** — `Tool(param:value)` whose key is the tool's own canonicalizing
  field (`command` for Bash/PowerShell, `file_path` for Read/Edit/Write, `path` for
  Grep/Glob, `notebook_path` for NotebookEdit, `url` for WebFetch). CC ignores these and
  emits a startup warning. Severity follows intent: **deny/ask = false security (medium)** —
  the block never applies; **allow = dead config (low)** — `param:value` matching is
  deny/ask-only. Valid forms (`Bash(npm:*)`, `WebFetch(domain:host)`, `Agent(model:opus)`)
  are never flagged. Predicate `forbiddenParamRule` in `permission-rules.mjs`.

These predicates live in `scanners/lib/permission-rules.mjs` (shared with the CNF
conflict-detector). Behavior verified against `code.claude.com/docs/en/permissions`.

### PLH scanner — plugin namespace collision

The standalone PLH scanner (cross-plugin checks in `scan()`) flags **plugin namespace
collisions**: two or more discovered plugins that declare the **same `name`** in
`plugin.json`. The search-first finding that shaped this check: Claude Code namespaces
every plugin component by the declared `name` — `/name:command`, `name:skill`, agent
`name` (verified against `code.claude.com/docs/en/plugins`, and observable in any session's
namespaced skill listing). A plugin component therefore can **never** shadow a user- or
project-level one; the only shadow that loses components is a same-`name` collision, where
the namespaces collapse into one and CC must pick a winner. Resolution between two installed
same-name plugins is **undocumented**, so the loser's commands/skills/agents go silently
unreachable — hence severity **MEDIUM** (dead config), `category: 'plugin-hygiene'`, with a
COL-shaped `details.namespaces` payload (`{ source: 'plugin:<dir>', name, path }`).

Two design notes: (1) the check keys on the declared `name` field, **not** `basename(dir)` —
the folder name is irrelevant to the namespace; `scanSinglePlugin` now returns `declaredName`
for this. (2) Name-less plugins are excluded from the collision map (they are flagged by the
missing-field check and must never group on an `undefined` key).

The sibling cross-plugin **command-name** check was corrected to match the same model. Because
commands are namespaced (`/name:command`), a command name shared by two **differently-named**
plugins is ambiguity — not a hard conflict — so it now mirrors COL's plugin-vs-plugin skill
finding: severity **LOW**, `category: 'plugin-hygiene'`, COL-shaped `details.namespaces`, and a
group-first shape (one finding per command name listing every namespace, not pairwise). It keys
on the declared namespace and fires only when a name spans **2+ distinct** namespaces; when two
plugins share the same declared name, the namespace-collision finding above is the right (more
severe) signal, so the command check stays silent there to avoid a redundant `"dup, dup"` report.
The earlier HIGH `Cross-plugin command name conflict` finding (basename-keyed, "only one wins")
is gone, along with its now-inaccurate humanizer entry.

### PLH scanner — plugin-folder shadowing (`CA-PLH-015`)

Per-plugin check (in `scanSinglePlugin`, right after the required-field loop): a `plugin.json`
component-path key that **replaces** its default folder while that folder still exists on disk →
the folder is silently ignored (dead config). Severity **MEDIUM**, `category: 'plugin-hygiene'`,
`details: { field, ignoredDir, customPaths }`. Mirrors Claude Code's own warning in `/doctor`,
`claude plugin list`, and the `/plugin` detail view (v2.1.140+).

The field set is **primary-source-pinned** to the *replaces* category only —
`SHADOWING_PATH_FIELDS` = `commands`/`agents`/`outputStyles` (defaults `commands/`, `agents/`,
`output-styles/`). Deliberately excluded: **`skills`** (per
`code.claude.com/docs/.../path-behavior-rules` it *adds to* the default `skills/` scan — both
load, never a shadow), and **`hooks`/`mcpServers`/`lspServers`** (own merge rules, not a
folder-shadow). Experimental `themes`/`monitors` are omitted because the docs warn their manifest
schema may change between releases. The check also honors the doc's explicit-address exception: a
custom path that resolves *into* the default folder (`"commands": ["./commands/x.md"]`) is not
flagged, because Claude Code keeps scanning the folder in that case (`addressesDefaultDir`
predicate). The v5.4.0 plan originally listed `commands/agents/skills/hooks`; that set was
corrected here against the live docs (Verifiseringsplikt).

### PLH scanner — skills:-array validation (`CA-PLH-016`)

Per-plugin check (in `scanSinglePlugin`, after the shadow check): when `plugin.json` has a
`skills` field (string or array), each entry must resolve to an **existing directory inside the
plugin root**. The value is normalized `Array.isArray(v) ? v : [v]`, so a single string is one
entry — and a non-string top-level value (e.g. `42`) is naturally caught as a single non-string
entry (no separate top-level check needed). One finding per bad entry, severity **MEDIUM**,
`category: 'plugin-hygiene'`, `details: { field: 'skills', entry, problem }` where `problem` is
one of `non-string` / `escapes-root` / `not-found` / `not-a-directory`. Mirrors
`claude plugin validate` (~2.1.145).

Escape detection uses `skillsEntryEscapesRoot` (resolve + `startsWith(pluginDir + sep)`
containment — robust against a literal `..foo` dir name), backed by the docs' path-traversal rule
(*"Installed plugins cannot reference files outside their directory … such as `../shared-utils`"*).
`statOrNull` distinguishes missing from file-vs-dir. **Verifiseringsplikt note:** the v5.4.0 plan
claimed CC "suggests the parent directory when an entry points at a file"; that exact error text is
**not** in the primary docs, so it was dropped — the finding asserts only the four
primary-source-verified conditions. `skills` is deliberately *not* in `SHADOWING_PATH_FIELDS`
(it adds to the default scan, never shadows).

### SET scanner — autoMode validation (`CA-SET`)

Per-file check in `settings-validator.mjs` (`autoMode` was in `KNOWN_KEYS` but had no nested
validation). Two sub-checks, both primary-source-verified against
`code.claude.com/docs/en/auto-mode-config`:

1. **Structure** (severity **MEDIUM**): `autoMode`, if present, must be an object whose only keys
   are `environment`/`allow`/`soft_deny`/`hard_deny` (`AUTO_MODE_SUBKEYS`), each a **string
   array** (the literal `"$defaults"` is a valid entry, so it passes the string check for free).
   `problem` ∈ `not-an-object` / `unknown-subkey` / `not-string-array` in `details`.
2. **Dead-config** (severity **LOW**): Claude Code does **not** read `autoMode` from *shared*
   project settings — verbatim: *"The classifier does not read `autoMode` from shared project
   settings in `.claude/settings.json`, so a checked-in repo cannot inject its own allow rules."*
   The check keys on **`file.scope === 'project'`** (file-discovery's `classifyScope` returns
   `'project'` for a committed `.claude/settings.json`; `'local'`/`'user'`/`'managed'` are read and
   not flagged). `problem: 'shared-project-scope'`. This is why the plan's "test per-file scope
   first" gate passed — `ConfigFile` already carries `scope`.

The two sub-checks are independent (a malformed autoMode in shared scope yields both). SET is in the
orchestrator, so SC-5 was re-checked after this change — byte-equal (the snapshot fixture has no
`autoMode`, so the block never fires there).

### OST scanner — output-style validation (`CA-OST`, v5.6 C, count 13→14)

New orchestrated scanner `output-style-scanner.mjs` — the first new scanner family since SKL
(v5.2.0). It reads the active config (`readActiveConfig`) and each output-style file's frontmatter
(via `parseFrontmatter`, keys hyphen→underscore-normalized, so it reads `keep_coding_instructions` /
`force_for_plugin`). Three findings, every claim pinned to a CONFIRMED row of
`docs/v5.5-steering-model-plan.md` (V9/V10/V11/V12), re-verified against
`code.claude.com/docs/en/output-styles` + `.../plugins-reference`:

- **`CA-OST-001`** (medium) — a **user/project** custom style not setting `keep-coding-instructions:
  true`. The flag defaults to **false**, so the style silently **removes** Claude Code's built-in
  software-engineering instructions when active (V10). Scoped to user/project (the styles the user
  authors); a plugin author's choice is out of scope.
- **`CA-OST-002`** (low) — a **plugin** style with `force-for-plugin: true`, which auto-applies and
  **overrides** the user's selected `outputStyle` (V11). **Verifiseringsplikt correction:** the v5.5+
  plan's CA-OST-002 bullet said "in a project/user style," but `force-for-plugin` is
  **plugin-styles-only** per the docs (its own cited V11 + `output-styles.md`), so the check keys on
  `source === 'plugin'` — a user/project style with the flag is simply ignored, not an override.
- **`CA-OST-003`** (medium) — a settings `outputStyle` value resolving to **no** built-in
  (`Default`/`Explanatory`/`Learning`/`Proactive`, matched case-insensitively) and **no** discovered
  custom style → dead config (CC falls back to default; the configured behavior never applies).

**Byte-stability — a scanner addition, NOT a field addition.** Adding the 14th scanner grows
`envelope.scanners` by one entry and bumps `aggregate.scanners_ok` 12→13 on the deterministic
fixture **regardless of findings** — a field-strip helper cannot paper this over. The SKL precedent
(`7bb2547`) re-seeded the frozen v5.0.0 snapshots, but that predates B2's strip-preservation regime;
re-seeding now would **bake in** B2's hotspot triple + `claudeMdEstimatedTokens` drift (verified by
inspecting the seed diff). So, consistent with the B2 lesson ("preserve frozen via strip-helper;
regen ONLY SC-5"), C **preserves** the frozen v5.0.0 snapshots and **strips the OST entry at compare
time**: shared `tests/helpers/strip-added-scanner.mjs` (`stripAddedScanners` removes OST entries +
decrements `scanners_ok`; `stripAddedScannerStderr` drops the `[OST]` progress line) is wired into
json/raw-backcompat + the Step 5/6 humanizer wiring tests (cli-humanizer did **not** break — its
v5.0.0 compares don't grow a scanners array). Only **SC-5 default-output** (scan-orchestrator +
posture) is regenerated (additive OST entry only — diff reviewed). OST is fixture-gated: the
`marketplace-medium` fixture and the hermetic HOME have no output styles, so it emits nothing there.

Wiring: orchestrator import + `SCANNERS` entry; `humanizer.mjs` `SCANNER_TO_CATEGORY`
(`OST: 'Configuration mistake'`); `humanizer-data.mjs` OST family (title-coupled to the three exact
finding titles); `scoring.mjs` `SCANNER_AREA_MAP` (`OST: 'Settings'` — keeps the 10 quality areas,
byte-stable on zero-finding projects). Count badges: self-audit scanner count 13→14; humanizer-data
TRANSLATIONS families 14→15 (PLH is a translation family but not orchestrated).

### best-practices register — machine-readable knowledge layer (v5.7 Fase 1 Chunk 1)

`knowledge/best-practices.json`: provenance-stamped, schema-validated register (entry =
`id`/`claim`/`confidence`/`source` + optional `mechanism`/`lensCheck`/…). First runtime-consumed
file in `knowledge/` (the `*.md` stay human-only); source of truth for the v5.7 optimization lens
(`CA-OPT`); seeded from the v5.5 V-rows + the Anthropic "Steering Claude Code" blog. Only
**confirmed** entries are user-facing (Verifiseringsplikt). Loaded/validated by
`scanners/lib/best-practices-register.mjs` (`loadRegister`/`validateRegister`/`getEntry`; zero-dep
JSON, **not** YAML — `yaml-parser.mjs` can't do arrays-of-objects). Byte-stable until a scanner
consumes it (Chunk 2). Full design: `docs/v5.7-optimization-lens-plan.md`.

### OPT scanner — optimization lens / mechanism-fit (`CA-OPT`, v5.7 Fase 1 Chunk 2a, count 14→15)

First detector of the «optimal?» axis (vs «correct?»). `optimization-lens-scanner.mjs` reads the
best-practices register and flags config that works but fits a better mechanism. **`CA-OPT-001`**
(low, *Missed opportunity*): a CLAUDE.md procedure (≥6 consecutive numbered steps) that belongs in a
skill — recommendation/provenance from register `BP-MECH-003`. Conservative (negative corpus = null
false-positive); prose-judgment cases (lifecycle→hook, unscoped path→rule, «never»→permission) are
handled by the Chunk 2b opus analyzer (below). Wiring mirrors OST: orchestrator entry, humanizer
`OPT:'Missed opportunity'` + family, scoring `OPT:'CLAUDE.md'` (existing area → no new posture row →
byte-stable), strip-helper `OPT`, SC-5 regenerated (additive).

### Optimization lens Chunk 2b — opus analyzer (prose-judgment half, `/config-audit optimize`)

The hybrid motor's recall + precision halves for the three cases the deterministic OPT scanner skips.
**Pre-filter** (`scanners/lib/lens-prefilter.mjs`, pure + tested): cheap, recall-oriented line scan
of CLAUDE.md body for lifecycle phrasing (`BP-MECH-001`→hook), unscoped path-specific instructions
(`BP-MECH-002`→rule), and absolute «never» prohibitions (`BP-MECH-004`→permission); skips fenced
code, gates the path class on an instruction verb. Detector names = the register `lensCheck` fields.
**CLI** (`optimize-lens-cli.mjs`, `-cli` → not a scanner): runs discovery + OPT scanner + pre-filter,
attaches the **confirmed** register entry to each candidate (unverifiable → dropped, Verifiseringsplikt),
emits `{deterministic, candidates, register, counts}`. **Agent** (`optimization-lens-agent`, opus,
orange — the 7th agent, **precision gate**): reads the real CLAUDE.md, drops low-confidence candidates,
keeps only genuine opportunities, cites register id + source. **Command** `/config-audit optimize`
orchestrates pre-filter→agent→report. **Agent-driven → deliberately NOT byte-stable** (own command,
outside the snapshot suite); the pre-filter lib *is* unit-tested (13 tests). No new orchestrated
scanner → scanner count stays 15; agents 6→7, commands 18→19, suite 1055→1068.

**Test-isolation fix (this session):** `token-hotspots.test.mjs` `runScanner` now wraps `scan()` in
the shared `withHermeticHome` helper — the suite is green on BOTH a real and a clean `HOME` (the OPT
section's old «run with clean HOME» caveat is resolved). Snapshot/byte tests were already hermetic.

### knowledge-refresh — the "living" half of the register (v5.7 Fase 1 Chunk 3, commands 19→20)

Keeps `knowledge/best-practices.json` current so the optimization lens never reads stale rules.
Same hybrid split as Chunk 2b — a deterministic, byte-stable, unit-tested core + a web/judgment shell:

- **Deterministic core** (`scanners/lib/knowledge-refresh.mjs`, pure, 15 tests): `assessFreshness(register,
  {referenceDate, staleAfterDays})` classifies each entry `fresh`/`stale` by the age of its
  `source.verified` stamp. `referenceDate` is **injected** (not read from the clock) so the function is
  fully deterministic; default threshold `STALE_AFTER_DAYS_DEFAULT = 90` (quarterly re-verify cadence).
  An unparseable/missing `verified` → stale with `ageDays: null` (defensive; the schema-validated bundle
  never hits this, but the command's hand-built candidates might). «Source changed» detection is a **web
  responsibility** (command layer), **not** in this core.
- **CLI** (`scanners/knowledge-refresh-cli.mjs`, `-cli` → **NOT** an orchestrated scanner → scanner count
  stays 15, suite byte-stable; 8 tests): read-only — it NEVER writes the register and NEVER hits the
  network. `--reference-date` (defaults to today; the **only** place the clock is read) makes it
  deterministically testable against the bundled register. `--stale-after N`, `--dry-run` (implicit + only
  mode, echoed as `requestedDryRun`). Exit **0** = all fresh, **1** = some stale (advisory), **3** = error.
- **Command** (`commands/knowledge-refresh.md`, opus): orchestrates CLI stale-report → re-verify each stale
  entry by re-reading its `source.url` (WebFetch) → poll CC changelog + Anthropic blog for new/changed
  practices (WebSearch) → present everything → **apply ONLY human-approved writes**, then re-run the
  register schema test before declaring done. **No unverified claim is ever auto-written** (Verifiseringsplikt).
  Web/judgment-driven → **deliberately NOT byte-stable** (own command, outside the snapshot suite), exactly
  like `/config-audit optimize`. **No new agent** (web poll runs in the command's own context), **no new
  orchestrated scanner**. suite 1068→1091.

### campaign-ledger — durable machine-wide campaign core (v5.7 Fase 2, Block 3a THIN)

`scanners/lib/campaign-ledger.mjs`: the durable ledger that sits ABOVE individual sessions for a
machine-wide audit campaign — repo list + per-repo lifecycle (`STATUSES` = pending→audited→planned
→implemented) + a machine-wide `rollUp` (counts by status + severity aggregated across repos). It
persists to a single JSON file **outside** the plugin dir (`~/.claude/config-audit/campaign-ledger
.json`, next to `sessions/`) so it survives uninstall/reinstall/upgrade. Same hybrid split as
knowledge-refresh: PURE transforms (`createLedger`/`addRepo`/`setRepoStatus`/`rollUp`) with `now`
**injected** (YYYY-MM-DD, never the clock) + soft `validateLedger` (returns `{valid,errors}`, never
throws) + a thin IO shell (`defaultLedgerPath`/`loadLedger`→null-on-ENOENT/`saveLedger`). Transforms
throw on programmer error (invalid status, unknown path); `schemaVersion` stamped from the start so a
Block 4 migration is cheap. **THIN**: ledger + roll-up + persistence only — NO execution, CLI, or
command surface (Blocks 3b/3c/4). **Internal plumbing, byte-stable until consumed**: no `export async
function scan` + lives in `lib/` → scanner count stays 15, no orchestrator wiring, SC-5 unchanged.
28 tests, suite 1091→1119.

### campaign-cli — read-only ledger reporter (v5.7 Fase 2, Block 3b)

`scanners/campaign-cli.mjs` (`-cli` → NOT an orchestrated scanner → scanner count stays 15, suite
byte-stable; 8 tests): the DETERMINISTIC, READ-ONLY half of the campaign motor, mirroring
`knowledge-refresh-cli`. It `loadLedger`s the durable ledger, `validateLedger`s it, and emits
`{status, initialized, ledgerPath, schemaVersion, createdDate, updatedDate, repos, rollUp}` as JSON.
It NEVER writes — a missing ledger is reported gracefully (`initialized:false`, all-zero roll-up),
**never created**; init + every status transition belong to the Block 3c command layer (human-approved
writes, Verifiseringsplikt). `--ledger-file` overrides the default path (deterministic testing);
`--output-file` mirrors the sibling. Exit codes: **0** = initialized & valid, **1** = not initialized
yet (advisory), **3** = error (parse/corrupt/invalid). suite 1119→1127.

### campaign-write-cli + `/config-audit campaign` — the WRITE half (v5.7 Fase 2, Block 3c, commands 20→21)

The human-approved mutation half of the campaign motor, completing the THIN campaign surface
(ledger + roll-up + status). Two pieces:

- **`scanners/campaign-write-cli.mjs`** (`-cli` → NOT an orchestrated scanner → scanner count stays
  15, suite byte-stable; 11 tests): the sibling of `campaign-cli` that *mutates*. Subcommands
  `init` / `add <path>...` / `set-status <path> <status>`, each a thin wrapper over the
  invariant-enforcing lib transforms (`createLedger`/`addRepo`/`setRepoStatus`) + `saveLedger` — so
  path-normalization/dedup, idempotent add, the status-lifecycle guard, and the `updatedDate` bump
  are **never re-implemented by hand**. `init` refuses to clobber an existing (or corrupt) ledger
  (**exit 1** advisory, file untouched); `add` **auto-inits** when no ledger exists and reports
  `added` vs `skipped`; `set-status` accepts `--findings '<json>'` + `--session <id>`. Determinism
  mirrors the lib + `knowledge-refresh-cli`: `--reference-date` is the **only** place the clock is
  read (defaults to today), passed to the transforms as the injected `now`. Exit: **0** = write
  performed, **1** = advisory no-op (init-clobber), **3** = error (unknown subcommand, bad args,
  invalid status, untracked repo, no/corrupt ledger).
- **`commands/campaign.md`** (opus, `allowed-tools: Read/Write/Edit/Bash/Glob` — **no Web**,
  judgment-free): a thin orchestrator. It always **reports** first (read-only `campaign-cli`), then
  for `init`/`add`/`set-status` it proposes the change and, **only on explicit human approval**,
  invokes one write-CLI subcommand (Verifiseringsplikt — it never hand-edits the ledger JSON).
  `add --discover <root>` finds git repos under a root and lets the user pick. When marking a repo
  `audited` it attaches findings-by-severity from the repo's session (or user-provided counts) —
  **never invented**.

**Not a new scanner, not byte-stable.** Both CLIs carry the `-cli` suffix (out of the
scan-orchestrator → scanner count stays **15**, snapshot suite untouched); the command's
orchestration is judgment-driven and deliberately outside the snapshot suite, exactly like
`/config-audit optimize` + `knowledge-refresh`. **No new agent** (web/judgment-free, runs in the
command's own context). suite 1127→1138.

## Gotchas

- Session directories accumulate — use `/config-audit cleanup` to manage
- Scanners run on Node.js >= 18 (uses node:test, node:fs/promises)
- Plugin CLAUDE.md files in node_modules should be excluded via scope