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 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

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

1091 tests across 62 test files (20 lib + 32 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.

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