diff --git a/CLAUDE.md b/CLAUDE.md index 1d9166f..bdb48ad 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -65,7 +65,7 @@ Analyzes and optimizes Claude Code configuration across three pillars: ## Reference docs (read on demand) -- **Scanner inventory, lib modules, action engines, knowledge base:** `docs/scanner-internals.md` +- **Scanner inventory, lib modules, action engines, knowledge base, per-scanner/per-block implementation notes:** `docs/scanner-internals.md` - **Plain-language output (v5.1.0), humanizer vocabularies, output modes:** `docs/humanizer.md` ## Plain-Language Output (v5.1.0) — summary @@ -107,6 +107,16 @@ Default: auto-detects scope from git context. Override with `/config-audit full| ### 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` +## Conventions + +Enforced project conventions live in `.claude/rules/` (auto-loaded as project instructions): + +- `ux-rules.md` — output/narration/formatting rules for all commands (never dump raw JSON, narrate before each step, space-separated command suggestions) +- `command-development.md` — required command frontmatter + `plugin:action` naming +- `state-management.md` — update `state.yaml` after every workflow phase + +Coding style: scanners are zero-dependency Node ESM; new findings use the `CA-{SCANNER}-{NNN}` ID format; byte-stable CLIs are verified against frozen `tests/snapshots/v5.0.0/` baselines. + ## Testing ```bash @@ -115,423 +125,7 @@ node --test 'tests/**/*.test.mjs' 1168 tests across 67 test files (22 lib + 35 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____*`. 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:', 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 ...` / `set-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 ''` + `--session `. 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 ` 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. - -### campaign backlog — cross-repo prioritized pick-list (v5.7 Fase 2, Block 4b) - -The first half of Block 4 ("one cross-repo prioritized backlog the user picks from"). A pure -lib transform + a read-only CLI-payload field — **no schema change, no new scanner, byte-stable**. - -- **`buildBacklog(ledger)`** (`scanners/lib/campaign-ledger.mjs`, pure, mirrors `rollUp`): the - single machine-wide prioritized work list. The actionable unit is a **repo** (the ledger tracks - per-repo severity *counts*, not individual findings — it tracks state, it does not re-run - audits), so each item is one repo: `{path, name, status, sessionId, findingsBySeverity - (normalized), totalFindings, weightedScore, rank}`. **Inclusion:** `status !== 'implemented'` - AND `totalFindings > 0` (implemented = done; pending / zero-finding repos have nothing known to - fix — they still surface in `rollUp.byStatus`). **Order:** DESC by `weightedScore` (exported - `SEVERITY_WEIGHTS = {critical:1000, high:100, medium:10, low:1}`), tie-broken lexicographically - by critical→high→medium→low count, then ascending `name` — fully deterministic, and the - tie-break keeps "criticals always win" even on a weighted-score collision (1 critical vs 10 high). - `rank` is 1-based after the sort. -- **`campaign-cli`** now emits `backlog: buildBacklog(ledger)` in both branches (uninitialized → - `[]`). Purely additive + read-only → fits the Block 3b read-only contract; the existing CLI - tests use targeted asserts (not full `deepEqual`), so the new field doesn't break them. -- **`commands/campaign.md`** renders the backlog as a "Prioritized backlog" pick-list and points - the user at the top item (still a pick-list, NOT an executor — execution is the later 4c block). - -**Byte-stability.** `-cli`/lib/command only → scanner count stays **15**, snapshot/backcompat -suite untouched. suite 1138→1150 (lib +9, campaign-cli +3). **Deferred to 4c:** per-repo plan -export to each repo's `docs/` + reuse of backup/rollback for execution. **Deferred until the first -breaking schema change:** `migrateLedger` (4a) — backlog needs no schema bump, so building -migration now would be speculative (`schemaVersion` is already stamped for when it's needed). - -### campaign plan-export + execution-by-reuse (v5.7 Fase 2, Block 4c — the rest of Block 4) - -The second half of Block 4. **Asymmetric:** plan export is the new testable code; execution is -*pure reuse* (no new machinery), per the plan's "reuse existing backup/rollback". - -- **Plan export** (`scanners/lib/campaign-export.mjs`, pure, 8 tests): `planExportPath(repoPath, - sessionId)` → `/docs/config-audit-plan-.md` (keyed on the timestamp-unique - sessionId, not the date, so same-day re-audits don't collide); `buildPlanExportDocument({...,now})` - → provenance header (repo/session/how-to-execute-and-undo) + the verbatim session plan. `now` - injected → deterministic. **CLI** `scanners/campaign-export-cli.mjs` (`-cli`, read-only by - default, 10 tests): `--repo ` resolves the repo's linked session, reads its - `action-plan.md`, assembles the doc, emits `{exportable, problems, targetPath, document, ...}`. - Two gates → exit 1 advisory: `no-session-linked` (repo has no `sessionId`), `no-action-plan` - (linked session has no plan yet). Writes the file **only** under opt-in `--write` — the CLI does - the byte-faithful copy so a 200-line plan is never re-typed/mutated by the LLM. `--sessions-dir` - override for hermetic tests; exit 0/1/3 mirror the sibling CLIs. -- **Execution = reuse.** No campaign-side execution code. The exported `docs/` file is the repo's - durable record; `/config-audit implement` still reads the canonical plan from the session - (backup + apply + verify), `/config-audit rollback` undoes, then `set-status implemented` - records it. The command (`commands/campaign.md`, new `export ` mode) previews → asks → on - approval invokes `--write` → routes the user to that existing machinery. -- **Byte-stable.** lib + `-cli` + command-doc only → scanner count stays **15**, agents **7**, - commands **21** (export is a *mode*, not a new command), snapshot/backcompat suite untouched. - suite 1150→1168 (lib +8, export-cli +10). **Block 4a (`migrateLedger`) still deferred** to the - first breaking schema change (export needs no schema bump). +Per-scanner and per-build-block implementation notes (design rationale, primary-source verification, byte-stability lessons) live in `docs/scanner-internals.md` → **Implementation notes**. ## Gotchas diff --git a/docs/scanner-internals.md b/docs/scanner-internals.md index 5183a9f..0a91879 100644 --- a/docs/scanner-internals.md +++ b/docs/scanner-internals.md @@ -77,3 +77,425 @@ Scanner CLI: `node scanners/scan-orchestrator.mjs [--global] [--full-mach | `gap-closure-templates.md` | Config-specific templates for closing gaps | | `prompt-cache-patterns.md` | Token-cost dynamics (prompt-cache patterns) — patterns powering the TOK scanner | | `cache-telemetry-recipe.md` | Manual `jq` recipe for verifying prompt-cache hit rate from session transcripts (v5 M7) | + +## Implementation notes (per scanner / build block) + +Detailed design rationale, primary-source verification, and byte-stability lessons for each scanner family and v5.6/v5.7 build block. Moved out of `CLAUDE.md` (kept lean per the "invariants only" rule); each note records why a change is correct and which frozen baselines it touched. Read on demand when working on the named scanner/block. + +### 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____*`. 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:', 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 ...` / `set-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 ''` + `--session `. 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 ` 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. + +### campaign backlog — cross-repo prioritized pick-list (v5.7 Fase 2, Block 4b) + +The first half of Block 4 ("one cross-repo prioritized backlog the user picks from"). A pure +lib transform + a read-only CLI-payload field — **no schema change, no new scanner, byte-stable**. + +- **`buildBacklog(ledger)`** (`scanners/lib/campaign-ledger.mjs`, pure, mirrors `rollUp`): the + single machine-wide prioritized work list. The actionable unit is a **repo** (the ledger tracks + per-repo severity *counts*, not individual findings — it tracks state, it does not re-run + audits), so each item is one repo: `{path, name, status, sessionId, findingsBySeverity + (normalized), totalFindings, weightedScore, rank}`. **Inclusion:** `status !== 'implemented'` + AND `totalFindings > 0` (implemented = done; pending / zero-finding repos have nothing known to + fix — they still surface in `rollUp.byStatus`). **Order:** DESC by `weightedScore` (exported + `SEVERITY_WEIGHTS = {critical:1000, high:100, medium:10, low:1}`), tie-broken lexicographically + by critical→high→medium→low count, then ascending `name` — fully deterministic, and the + tie-break keeps "criticals always win" even on a weighted-score collision (1 critical vs 10 high). + `rank` is 1-based after the sort. +- **`campaign-cli`** now emits `backlog: buildBacklog(ledger)` in both branches (uninitialized → + `[]`). Purely additive + read-only → fits the Block 3b read-only contract; the existing CLI + tests use targeted asserts (not full `deepEqual`), so the new field doesn't break them. +- **`commands/campaign.md`** renders the backlog as a "Prioritized backlog" pick-list and points + the user at the top item (still a pick-list, NOT an executor — execution is the later 4c block). + +**Byte-stability.** `-cli`/lib/command only → scanner count stays **15**, snapshot/backcompat +suite untouched. suite 1138→1150 (lib +9, campaign-cli +3). **Deferred to 4c:** per-repo plan +export to each repo's `docs/` + reuse of backup/rollback for execution. **Deferred until the first +breaking schema change:** `migrateLedger` (4a) — backlog needs no schema bump, so building +migration now would be speculative (`schemaVersion` is already stamped for when it's needed). + +### campaign plan-export + execution-by-reuse (v5.7 Fase 2, Block 4c — the rest of Block 4) + +The second half of Block 4. **Asymmetric:** plan export is the new testable code; execution is +*pure reuse* (no new machinery), per the plan's "reuse existing backup/rollback". + +- **Plan export** (`scanners/lib/campaign-export.mjs`, pure, 8 tests): `planExportPath(repoPath, + sessionId)` → `/docs/config-audit-plan-.md` (keyed on the timestamp-unique + sessionId, not the date, so same-day re-audits don't collide); `buildPlanExportDocument({...,now})` + → provenance header (repo/session/how-to-execute-and-undo) + the verbatim session plan. `now` + injected → deterministic. **CLI** `scanners/campaign-export-cli.mjs` (`-cli`, read-only by + default, 10 tests): `--repo ` resolves the repo's linked session, reads its + `action-plan.md`, assembles the doc, emits `{exportable, problems, targetPath, document, ...}`. + Two gates → exit 1 advisory: `no-session-linked` (repo has no `sessionId`), `no-action-plan` + (linked session has no plan yet). Writes the file **only** under opt-in `--write` — the CLI does + the byte-faithful copy so a 200-line plan is never re-typed/mutated by the LLM. `--sessions-dir` + override for hermetic tests; exit 0/1/3 mirror the sibling CLIs. +- **Execution = reuse.** No campaign-side execution code. The exported `docs/` file is the repo's + durable record; `/config-audit implement` still reads the canonical plan from the session + (backup + apply + verify), `/config-audit rollback` undoes, then `set-status implemented` + records it. The command (`commands/campaign.md`, new `export ` mode) previews → asks → on + approval invokes `--write` → routes the user to that existing machinery. +- **Byte-stable.** lib + `-cli` + command-doc only → scanner count stays **15**, agents **7**, + commands **21** (export is a *mode*, not a new command), snapshot/backcompat suite untouched. + suite 1150→1168 (lib +8, export-cli +10). **Block 4a (`migrateLedger`) still deferred** to the + first breaking schema change (export needs no schema bump).