docs(plan): v5.13 plan — model routing, effort awareness, dead references

Video-derived audit ('The Model Isn't the Moat') cross-checked against
primary sources. Verified: orchestrator+cheap-worker pattern and 5-level
per-agent effort tuning (official docs); rejected: the 'Fable low ≈ Opus
high' chart claim (contradicted by Anthropic's own pages). Five chunks:
register entries BP-MODEL-001/002, fix-engine xhigh hygiene, CA-CML dead
prose references, feature-gap model/effort opportunity, planner-agent
adversarial gate. Sequenced AFTER DEL B pipeline dogfood + batch release.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CTontYwY5JGS4nL2AuiASy

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "config-audit",
   "description": "Multi-agent workflow for analyzing, reporting, and optimizing Claude Code configuration across your entire machine",
-  "version": "5.12.2",
+  "version": "5.12.5",
   "author": {
     "name": "Kjell Tore Guttormsen"
   },

CHANGELOG.md

@@ -5,6 +5,123 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.12.5] - 2026-06-26
+
+### Summary
+"Dogfood denoise" — a samle-release of the Fase-3 scanner false-positive batch: `M-BUG-2/6/7/8/10`,
+all dogfooding finds from running config-audit on the maintainer's real `~/.claude`. The shared theme
+is **non-user / non-live config wrongly counted as the user's authored cascade**: installed plugins'
+bundled config, frozen backup copies, doc examples, and forward-compatible settings keys all produced
+findings the user could neither act on nor was responsible for. No new scanner, command, agent, or hook
+(counts stay scanners **16**, agents **7**, commands **21**, hooks **4**); all five fixes are byte-stable
+— the frozen v5.0.0 + SC-5 + default-output snapshots are untouched and **no fixture was re-seeded**
+(verified per bug: each affected fixture's findings are genuinely unchanged because the snapshot fixtures
+contain none of the triggering paths/tokens). **1344** tests (+37).
+
+### Fixed
+- **`conflict-detector` segregates plugin-bundled config (`M-BUG-2`).** CNF compared every discovered
+  `settings.json`/`hooks.json` pairwise regardless of origin, so it treated installed plugins' bundled
+  configs — each plugin's own settings/hooks plus its shipped fixtures and examples under
+  `~/.claude/plugins/` — as the user's cascade. A "conflict" between two plugins' bundled test fixtures
+  is not user-resolvable, yet these dominated the count (dogfood **339** findings: 315 high-sev
+  allow/deny, 18 duplicate-hook, 6 settings-key — Conflicts grade F on ~100% plugin noise). Fix: a new
+  `isPluginBundled` predicate excludes any file whose absolute path is under `.claude/plugins/` from
+  conflict analysis. Kept **CNF-local, not a discovery-level skip** on purpose — an active plugin's
+  contributed `hooks.json`/`.mcp.json` legitimately lives in `plugins/cache` and other scanners need it;
+  only conflict analysis must ignore plugin-bundled files. Same class as `M-BUG-8`. Dogfood **339→0**
+  (the ~3 genuine user-scope local settings have no actually-conflicting keys). +3 tests (plugin-bundled
+  exclusion, discovery-side sanity, over-exclusion guard).
+- **`file-discovery` skips `backups/` (`M-BUG-8`).** A directory named `backups` holds backup COPIES, not
+  live config, so walking it during an audit produces stale findings. config-audit's own session backups
+  (`~/.claude/config-audit/backups/<ts>/files/.../CLAUDE.md`) were the canonical case: a `~/.claude`-scope
+  audit walked 36 frozen copies as if live, polluting CPS and HKV/RUL. Fix: add `backups` to `SKIP_DIRS`
+  (broad, name-based — consistent with `vendor`/`dist`/`.cache`). Dogfood files-under-`/backups/`
+  **36→0**, 717 live config files retained. +3 tests.
+- **token estimator discounts block-level HTML comments (`M-BUG-6`).** CLAUDE.md token estimates counted
+  block-level `<!-- -->` comments toward always-loaded tokens, but CC strips them before injection
+  (preserved only inside code fences, per `code.claude.com/docs/en/memory`). Fix: new
+  `stripInjectedHtmlComments` + `effectiveMemoryBytes` in `active-config-reader`; the CML cascade and
+  `token-hotspots` now size CLAUDE.md from effective (stripped) bytes while raw byte figures stay honest.
+  Block-level only — inline comments retained (conservative, verified scope). Dogfood `~/.claude` CLAUDE.md
+  ~3386→3301 tok (~85 tok). +13 tests.
+- **`cache-prefix-stability` ignores code + CC-stable path vars (`M-BUG-7`).** CPS flagged
+  `${CLAUDE_PLUGIN_ROOT}`/`${CLAUDE_PROJECT_DIR}` (CC-provided stable paths) and `{date}`/timestamp tokens
+  shown in documentation as cache-busters. Fix: skip fenced code blocks, strip inline-code spans, and
+  whitelist CC-stable vars before pattern-matching. Suppress-only — frozen v5.0.0 snapshots untouched
+  (CPS yields `findings:[]` there). Dogfood **5→2** (3 doc false-positives suppressed; 2 remaining are
+  own volatile test fixtures). +6 tests.
+- **`settings-validator` typo-gates unknown keys (`M-BUG-10`).** The CC settings schema is passthrough
+  (verified against the 2.1.193 binary): it forwards unrecognized keys unchanged rather than rejecting
+  them, so an arbitrary unknown key is forward-compatible, not an error — the finding's "silently ignored"
+  claim was factually wrong. The only real risk is a TYPO of a real key (the intended setting then
+  silently has no effect). Fix: flag an unknown key only when it closely matches a known key (new
+  `levenshtein` helper; edit distance ≤2, both keys ≥4 chars); severity medium→low; honest passthrough
+  framing in scanner + humanizer. Also refreshed `KNOWN_KEYS` with 6 binary-verified keys
+  (`agentPushNotifEnabled`, `remoteControlAtStartup`, `skipAutoPermissionPrompt`,
+  `skipDangerousModePermissionPrompt`, `skipWorkflowUsageWarning`, `tui`). Dogfood
+  `~/.claude/settings.json` **6→0** (all 6 were false unknown-key findings; 0 typo flags introduced across
+  167 walked files). +12 tests.
+
+## [5.12.4] - 2026-06-26
+
+### Summary
+"Rooted rules" — fixes `M-BUG-9` (dogfooding find) in `scanners/rules-validator.mjs`. The RUL
+"Rule path pattern matches no files" check resolved a rule's `paths:`/`globs:` glob against the
+outer **scan root** instead of the rule's **own project root** (the directory containing its
+`.claude/`), and `collectProjectFiles` carried a `depth>4` cutoff that never reached deep matching
+files. As a result, a live rule in a **nested repo** — e.g. a marketplace checkout under
+`~/.claude/plugins/marketplaces/<mkt>/.claude/rules/` — was wrongly flagged "never activates" (high
+severity), a false F-grade for any user with rules in a nested repo. Same scope-conflation family as
+`M-BUG-1/2` (the scanner treats a nested repo's config as scoped to the outer scan root). The fix is a
+no-op for the common single-repo scan (`projectRoot === targetPath`), so the frozen v5.0.0 +
+default-output snapshots stay byte-stable; no count change (scanners **16**, agents **7**, commands
+**21**). **1307** tests (+2).
+
+### Fixed
+- **`rules-validator` glob base (`M-BUG-9`).** The dead-rule check now resolves each rule against its
+  own project root:
+  - `deriveProjectRoot(ruleAbsPath)` returns the parent of the rule's `.claude` segment.
+  - Project files are collected and globbed **per project root** (cached), relative to that root, so a
+    nested repo's rule matches against its own tree where its files live. This also sidesteps the old
+    `depth>4` cutoff, because the walk now starts at the nearby project root.
+  - User-global rules (`projectRoot === $HOME`, i.e. `~/.claude/rules/`) skip the no-match check: they
+    scope against whatever project is active at runtime, not a fixed tree, so "matches 0 files here" is
+    not a dead-rule signal (and this avoids a `$HOME`-wide file walk).
+  - TDD: 2 failing tests (nested-repo false-positive + HOME guard) → fix → full suite 1307/0, frozen
+    v5.0.0 + default-output snapshots untouched (RUL findings appear in none). Real-machine verify: the
+    two `ktg-privat` false positives clear and a previously-hidden genuine dead rule (a false negative)
+    surfaces in the bundled `optimal-setup` example; zero new false positives.
+
+## [5.12.3] - 2026-06-26
+
+### Summary
+"Phantom agents" — fixes `M-BUG-3/4/5` (dogfooding finds) in `scanners/lib/active-config-reader.mjs`
+so that `enumerateAgents` counts only the agents Claude Code actually **registers**. Per the official
+subagents documentation, an agent file must carry valid `name`+`description` frontmatter, and CC
+scans the agents directory **recursively** while silently skipping frontmatter-less files. The reader
+violated all three rules: it counted every `.md` regardless of frontmatter (`M-BUG-5`), never recursed
+into agent subdirectories (`M-BUG-3`), and double-counted entries when the project directory equals the
+user directory — the case when the scope root is `$HOME` (`M-BUG-4`, the root cause, which also affected
+rules and output-styles). Real-machine verify: the user-agent count dropped **13→0** (all 12 user
+agents plus `REMEMBER.md` are frontmatter-less, so CC registers none of them) and the HOME `project`
+duplicate dropped **13→0**; the corrected always-loaded baseline is ≈ **53**, not 66. Agent enumeration
+is machine-dependent and therefore absent from the frozen snapshots, so the v5.0.0 + SC-5 +
+default-output snapshots stay byte-stable; no count change (scanners **16**, agents **7**, commands
+**21**). **1305** tests (+4).
+
+### Fixed
+- **`active-config-reader` agent enumeration (`M-BUG-3/4/5`).** Three surgical fixes:
+  - `listMarkdownFiles` gains an opt-in `recursive` flag so agent enumeration descends into
+    subdirectories the way Claude Code does (`M-BUG-3`).
+  - `configDirs` now de-duplicates the project and user paths when they resolve to the same directory
+    (the case when the scope root is `$HOME`), the root cause that also double-counted rules and
+    output-styles (`M-BUG-4`).
+  - `enumerateAgents` requires a valid `name`+`description` frontmatter block before counting a file,
+    matching CC's actual registration rule — frontmatter-less files are silently skipped (`M-BUG-5`).
+  - Added a `hasText` frontmatter helper. TDD: 4 failing tests (one per bug) → fix → full suite
+    1305/0, frozen v5.0.0 + SC-5 + default-output snapshots untouched (agent enumeration is
+    machine-dependent and never seeded into a snapshot).
+
 ## [5.12.2] - 2026-06-24
 
 ### Summary

CLAUDE.md

@@ -1,13 +1,8 @@
 # Config-Audit Plugin
 
-Claude Code Configuration Intelligence — know if your configuration is correct, find what could improve it, fix it automatically.
+Claude Code Configuration Intelligence — know if your config is correct, find what could improve it, fix it automatically. Three pillars: **Health** (deterministic scanners), **Opportunities** (context-aware recommendations), **Action** (auto-fix with backup/rollback).
 
-## 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
+Per-command flags, patterns, and feature lists live in `README.md` and `/config-audit help`. This file carries what's invariant for working on the plugin.
 
 ## Commands
 
@@ -15,15 +10,15 @@ Analyzes and optimizes Claude Code configuration across three pillars:
 
 | 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 (8 patterns: cache-breaking, redundant perms, deep imports, oversized cascade, bloated SKILL.md desc, MCP tool-schema budget, MCP tool-schema deferral, stale plugin-cache disk-cleanup), each ranked hotspot tagged with its load pattern (always / on-demand / external) — **cache-aware** (stale `~/.claude/plugins/cache` versions excluded by default; only each plugin's active version counts; `--no-exclude-cache` for the full walk), 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` | Full audit with auto-scope detection |
+| `/config-audit posture` | A-F health scorecard (10 quality areas) |
+| `/config-audit tokens` | Prompt-cache-aware token hotspots, each tagged with its load pattern; cache-aware |
+| `/config-audit manifest` | Ranked table of every token source + always-loaded subtotal |
+| `/config-audit feature-gap` | Context-aware feature recommendations grouped by impact |
+| `/config-audit optimize` | Mechanism-fit lens (procedure→skill, lifecycle→hook, path→rule, never→permission). 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 plan` | Create action plan from findings |
 | `/config-audit implement` | Execute plan with backups + auto-verify |
 | `/config-audit help` | Show all commands |
 
@@ -33,9 +28,9 @@ Analyzes and optimizes Claude Code configuration across three pillars:
 |---------|-------------|
 | `/config-audit drift` | Compare current config against saved baseline |
 | `/config-audit plugin-health` | Audit plugin structure, frontmatter, cross-plugin coherence |
-| `/config-audit whats-active` | Read-only inventory of plugins, skills, MCP, hooks, CLAUDE.md active for a repo (with token estimates) |
-| `/config-audit knowledge-refresh` | Keep the best-practices register fresh — deterministic stale check (sources older than ~90d) + web candidate poll (CC changelog + Anthropic blog); **human-approved writes only** (Verifiseringsplikt). The "living" half of the knowledge base. Web/judgment-driven, **not byte-stable** |
-| `/config-audit campaign` | Machine-wide audit campaign — durable ledger ABOVE sessions: per-repo lifecycle (pending→audited→planned→implemented) + machine-wide roll-up by severity + **machine-wide always-loaded token bill** (`refresh-tokens` live cross-repo sweep — shared global layer counted once + per-repo deltas) + cross-repo prioritized backlog + plan **export** (drop a planned repo's plan into its own `docs/`), resumable across sessions. Read-only report (campaign-cli) + **human-approved** writes via deterministic write/export CLIs. THIN: tracks+routes state, reuses existing implement/rollback for execution. Judgment-driven, **not byte-stable** |
+| `/config-audit whats-active` | Read-only inventory of active plugins/skills/MCP/hooks/CLAUDE.md (with token estimates) |
+| `/config-audit knowledge-refresh` | Refresh the best-practices register (stale check + web poll). Human-approved writes; **not byte-stable** |
+| `/config-audit campaign` | Machine-wide audit ledger + token bill across repos. Human-approved writes; **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) |
@@ -51,68 +46,43 @@ Analyzes and optimizes Claude Code configuration across three pillars:
 | 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 |
+| feature-gap-agent | Feature recommendations | opus | green | Read, Glob, Grep, Write |
+| optimization-lens-agent | Mechanism-fit precision gate | 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 |
+| PreToolUse | `auto-backup-config.mjs` | Backup config files before Edit/Write |
+| PostToolUse | `post-edit-verify.mjs` | Verify after Edit/Write, block on new critical/high |
+| SessionStart | `session-start.mjs` | Check for active (unfinished) sessions |
+| Stop | `stop-session-reminder.mjs` | Remind about current session phase |
 
 ## Reference docs (read on demand)
 
-- **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`
+- `docs/scanner-internals.md` — scanner inventory, lib modules, action engines, knowledge base, per-scanner/per-block implementation notes (design rationale, primary-source verification, byte-stability lessons)
+- `docs/humanizer.md` — plain-language output (v5.1.0), humanizer vocabularies, output modes
 
-## Plain-Language Output (v5.1.0) — summary
+## Plain-Language Output (v5.1.0)
 
-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`.
+Default output of all commands routes through `humanizeEnvelope` (`lib/humanizer.mjs`), decorating each finding with `userImpactCategory`, `userActionLanguage`, and `relevanceContext`. `--raw` and `--json` bypass the humanizer for byte-stable v5.0.0 output. Full detail: `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`.
+Create `.config-audit-ignore` at project root — one exact ID or glob per line (`CA-SET-003`, `CA-GAP-*`). Suppressed findings are tracked in the 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).
+Workflow: `/config-audit → discover + analyze (auto) → plan → implement → verify`. Auto-detects scope from git context; override with `full|repo|home|current`; `--delta` for incremental. Session state lives under `~/.claude/config-audit/sessions/{id}/` (scope.yaml, discovery.json, state.yaml, findings/, analysis-report.md, action-plan.md, backups/, implementation-log.md).
 
-### 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`, `CA-AGT-001`
+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-SKL-001`, `CA-OST-001`, `CA-OPT-001`, `CA-AGT-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)
+Enforced conventions live in `.claude/rules/` (auto-loaded as project instructions):
+- `ux-rules.md` — output/narration/formatting for all commands (never dump raw JSON, narrate before each step, space-separated command suggestions)
 - `command-development.md` — required command frontmatter + `plugin:action` naming
+- `agent-development.md` — agent frontmatter + "when to use" conventions
 - `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.
@@ -123,12 +93,10 @@ Coding style: scanners are zero-dependency Node ESM; new findings use the `CA-{S
 node --test 'tests/**/*.test.mjs'
 ```
 
-1279 tests across 72 test files (23 lib + 39 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`.
-
-Per-scanner and per-build-block implementation notes (design rationale, primary-source verification, byte-stability lessons) live in `docs/scanner-internals.md` → **Implementation notes**.
+Test fixtures in `tests/fixtures/`. 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
 
 - Session directories accumulate — use `/config-audit cleanup` to manage
-- Scanners run on Node.js >= 18 (uses node:test, node:fs/promises)
+- Scanners run on Node.js ≥ 18 (uses node:test, node:fs/promises)
 - Plugin CLAUDE.md files in node_modules should be excluded via scope

README.md

@@ -6,13 +6,13 @@
 
 *AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*
 
-![Version](https://img.shields.io/badge/version-5.12.2-blue)
+![Version](https://img.shields.io/badge/version-5.12.5-blue)
 ![Platform](https://img.shields.io/badge/platform-Claude_Code_Plugin-purple)
 ![Scanners](https://img.shields.io/badge/scanners-16-cyan)
 ![Commands](https://img.shields.io/badge/commands-21-green)
 ![Agents](https://img.shields.io/badge/agents-7-orange)
 ![Hooks](https://img.shields.io/badge/hooks-4-red)
-![Tests](https://img.shields.io/badge/tests-1301-brightgreen)
+![Tests](https://img.shields.io/badge/tests-1344-brightgreen)
 ![License](https://img.shields.io/badge/license-MIT-lightgrey)
 
 A Claude Code plugin that checks configuration health, suggests context-aware improvements, and auto-fixes issues — `CLAUDE.md`, `settings.json`, hooks, rules, MCP servers, `@imports`, and plugins. 16 deterministic scanners across 10 quality areas, context-aware feature recommendations, auto-fix with backup/rollback, a prompt-cache-aware Token Hotspots scanner with optional API-calibrated `--accurate-tokens` mode, plus cache-prefix stability, dead-tool, cross-plugin collision, output-style, and always-loaded agent-listing-budget detection. Zero external dependencies.
@@ -662,6 +662,9 @@ This plugin is cautious by design — configuration files are important, and a b
 
 | Version | Date | Highlights |
 |---------|------|-----------|
+| **5.12.5** | 2026-06-26 | "Dogfood denoise" — a samle-release of the Fase-3 scanner false-positive batch (`M-BUG-2/6/7/8/10`, all dogfooding finds on the maintainer's real machine). Five scanners stop counting non-user / non-live config as the user's: **CNF** (`M-BUG-2`) excludes files under `.claude/plugins/` from conflict analysis (`isPluginBundled`) — installed plugins' bundled settings/hooks/fixtures are not a user-resolvable cascade (dogfood **339→0**, Conflicts was an F on pure plugin noise). **file-discovery** (`M-BUG-8`) adds `backups` to `SKIP_DIRS` — a `backups/` tree holds frozen copies, never live config (dogfood files-under-`/backups/` **36→0**, 717 live retained). **token estimator** (`M-BUG-6`) strips block-level `<!-- -->` HTML comments from CLAUDE.md sizing — CC strips them before injection, so they were never always-loaded tokens (dogfood ~3386→3301, ~85 tok). **CPS** (`M-BUG-7`) skips fenced/inline code and whitelists CC-stable path vars (`${CLAUDE_PLUGIN_ROOT}`/`${CLAUDE_PROJECT_DIR}`) before cache-buster matching (dogfood **5→2**). **SET** (`M-BUG-10`) typo-gates the unknown-settings-key finding — the CC schema is passthrough (verified against the 2.1.193 binary), so an unknown key is forward-compatible, not an error; it now flags only a near-miss of a known key (levenshtein ≤2), severity medium→low, +6 binary-verified `KNOWN_KEYS` (dogfood **6→0**). No count change (scanners **16**, agents **7**, commands **21**, hooks **4**); all five are byte-stable — frozen v5.0.0 + SC-5 + default-output snapshots untouched, no re-seed (each fixture's findings are genuinely unchanged). **1344** tests (+37). |
+| **5.12.4** | 2026-06-26 | "Rooted rules" — fixes `M-BUG-9` (dogfooding find) in `scanners/rules-validator.mjs`: the RUL "Rule path pattern matches no files" check now resolves a rule's `paths:`/`globs:` pattern against the rule's **own project root** (the dir containing its `.claude/`), not the outer scan root. Previously `countGlobMatches` globbed against the scan target and `collectProjectFiles`' `depth>4` cutoff never reached deep matching files, so a live rule in a **nested repo** (e.g. a marketplace checkout under `~/.claude`) was wrongly flagged "never activates" (high) — a false F-grade for anyone with rules in a nested repo. The fix derives each rule's project root, collects+globs per root (cached), and skips the check for user-global rules (`root === $HOME`), which scope against the active project at runtime. Same scope-conflation family as `M-BUG-1/2`. No count change (scanners **16**, agents **7**, commands **21**); the fix is a no-op when `projectRoot === targetPath` (the common single-repo scan), so frozen v5.0.0 + default-output snapshots stay byte-stable. **1307** tests (+2 TDD: nested-repo false-positive + HOME guard). |
+| **5.12.3** | 2026-06-26 | "Phantom agents" — fixes `M-BUG-3/4/5` (dogfooding finds) in `scanners/lib/active-config-reader.mjs`: `enumerateAgents` now counts only the agents Claude Code actually **registers**. Per the official subagents doc, an agent needs valid `name`+`description` frontmatter, and CC scans recursively and silently skips frontmatter-less files. The reader previously (`M-BUG-5`) counted every `.md` regardless of frontmatter, (`M-BUG-3`) never recursed into agent subdirs, and (`M-BUG-4`) double-counted when the project dir equals the user dir (scanning `$HOME` — root cause, also affecting rules/output-styles). Real-machine verify: user-agent count **13→0** (all 12 user agents + `REMEMBER.md` are frontmatter-less → CC registers none), HOME `project`-dup **13→0**; corrected always-loaded baseline ≈ **53** (was 66). Agent enumeration is machine-dependent and absent from the frozen snapshots, so the v5.0.0 + SC-5 + default-output snapshots stay byte-stable; no count change (scanners **16**, agents **7**, commands **21**). **1305** tests. |
 | **5.12.2** | 2026-06-24 | "Honest census" — fixes `M-BUG-1` (dogfooding find): `enumeratePlugins` walked `~/.claude/plugins/marketplaces/<mkt>/plugins/` and ignored both enable-state and the polyrepo cache layout, so it **over-counted phantom agents** from disabled plugins while **missing the entire enabled polyrepo set** (whose plugins live under `cache/`). It now gates on `installed_plugins.json` + `enabledPlugins` and enumerates each plugin from its active `installPath`, with the marketplaces walk as fallback. Fixes `manifest`/`whats-active`/AGT/`token-hotspots` for any user with disabled plugins or a polyrepo marketplace. No count change (scanners **16**, agents **7**, commands **21**); `--json`/`--raw` byte-stable, frozen v5.0.0 + SC-5 + default-output snapshots untouched. Real-machine verify: agent listing 114→104, ghosts gone. **1301** tests. |
 | **5.12.1** | 2026-06-24 | "Footgun guard" — Pattern H (stale plugin-cache versions, `token-hotspots`) recommended deleting stale version dirs with **no warning** that a currently-running session may still hold one of those versions for its whole lifetime. "Stale" is judged against `installed_plugins.json` (what NEW sessions load), so the recommendation could reproduce the exact failure that breaks a live session: deleting the dir pulls the files out from under the running session, which then must `/exit` + restart. The `plugin-cache-hygiene` recommendation now carries the live-session caveat. **Recommendation string only** — no new finding ID or scanner (count stays **16**, agents **7**, commands **21**), no token figures changed, so `--json`/`--raw` stay byte-stable and the frozen v5.0.0 + SC-5 + default-output snapshots are untouched. **1297** tests. |
 | **5.12.0** | 2026-06-23 | "Auto-calibration" — completes the deferred B8 half (**B8b**): `--context-window auto` now **probes the configured model** instead of always falling back to advisory. New pure `modelToContextWindow()` maps known 1M-tier model IDs (Fable 5, Opus 4.8/4.7/4.6, Sonnet 4.6 — verified June 2026 — plus the explicit `[1m]` tier tag, dated/provider-prefixed IDs, and the `opus`/`sonnet`/`fable` aliases) to the 1M window; new IO helper `lib/active-model.mjs` `resolveActiveModel()` reads the model the way Claude Code resolves it (shell `ANTHROPIC_MODEL` override, then the settings cascade local > project > user). When `auto` resolves a recognized model the budget calibrates to its window (`auto-probed`, not advisory); when no model is pinned or it is unrecognized it keeps the conservative anchor and stays advisory (`auto-unresolved`) — the honest fallback. No new finding ID or scanner (count stays **16**, agents **7**, commands **21**); the default and explicit `--context-window` paths are unchanged, so `--json`/`--raw` stay byte-stable and the frozen v5.0.0 + SC-5 snapshots are untouched. **1296** tests. |

docs/scanner-internals.md

@@ -254,6 +254,39 @@ model-switch is a *runtime* behaviour, not static config a scanner can reliably
 automation. "No overstated behavioral finding ships" — so even the permitted opusplan *info*-advisory was
 left out; the verified @import extension is the whole of B6.
 
+### GAP scanner — authored-config scoping + direct cascade read (M-BUG-13)
+
+The 25 presence checks ask "does the user's effective config have feature X?" and GAP **always**
+runs `includeGlobal: true`. Two failure modes made the answer wrong on a real machine, both surfaced
+by dogfooding `feature-gap`/`posture --global`:
+
+1. **Demo/vendored config masks real gaps.** This plugin's own `examples/optimal-setup/` is a complete
+   config (sets `outputStyle`/`statusLine`/`worktree`/`model`/`keybindings.json`/`.lsp.json`), and its
+   copies vendored under `~/.claude/plugins/cache/.../config-audit/<ver>/examples/` are pulled into the
+   includeGlobal discovery. Because `anySettingsHas`/`files.some(...)` accept ANY discovered file, that
+   one demo file drove every tier-3 check to "present" → **GAP=0 on any target** (false negative).
+   Fix: `isAuthoredConfig` filters `ctx.files`/`parsedSettings` to the user's authored cascade —
+   excludes `~/.claude/plugins/` (absPath marker, mirrors CNF's M-BUG-2 exclusion) and any file whose
+   path **relative to the scan target** sits under `examples/` or `tests/fixtures/`. relPath (not
+   absPath) is deliberate: a fixture scanned AS the target keeps its own files, so the frozen v5.0.0
+   snapshots (scanned from `tests/fixtures/marketplace-medium`, which has no such nested trees) are
+   byte-stable.
+
+2. **The real `~/.claude/settings.json` is invisible to the settings-key checks.** Discovery misses it
+   (its relPath carries no `.claude` segment when the walk root IS `~/.claude` — the gotcha) AND, when
+   vendored plugins flood the walk, the `maxFiles=2000` cap drops it. After (1) removed the demo
+   maskers, `statusLine`/`autoMode`/`permissions` (which the user HAS) would flip to false **positives**.
+   Fix: `readSettingsCascade` reads the four canonical cascade paths (user `settings.json`/`.local`,
+   project `settings.json`/`.local`) directly and merges them INTO `parsedSettings` — immune to the
+   cap and the gotcha. Merge (not replace) keeps non-canonical project settings and leaves the snapshot
+   (hermetic empty HOME → cascade adds nothing new) byte-stable.
+
+Net: an empty target now surfaces ~18 humanized opportunities (was masked to ~0); config-audit's own
+repo still shows 0 in output via its intentional `.config-audit-ignore` `CA-GAP-*` self-suppression
+(a plugin repo legitimately lacks user-project features) — suppression is an envelope-layer concern,
+orthogonal to this scanner fix. Scoped GAP-local; the includeGlobal discovery gotcha itself is left
+to other consumers (see auto-memory `discovery-includeglobal-user-settings-gotcha`).
+
 ### CML scanner — context-window-scaled char budget
 
 Beyond the line-count checks (200/500 lines, both MEDIUM), the CML scanner mirrors

docs/v5.13-model-routing-effort-deadref-plan.md

@@ -0,0 +1,157 @@
+# v5.13 Plan — Model Routing, Effort Awareness, Dead References
+
+Derived from an external video analysis ("The Model Isn't the Moat", 2026-07) cross-checked
+against primary sources and against what config-audit already encodes. Every claim acted on
+here was verified against Anthropic's own docs; video-only claims are explicitly rejected below.
+
+## Source verification (done 2026-07-14)
+
+| Claim from video | Verdict | Source |
+|---|---|---|
+| Orchestrator + cheaper worker models is a supported, recommended pattern | VERIFIED | code.claude.com/docs/en/sub-agents ("Control costs by routing tasks to faster, cheaper models like Haiku"), code.claude.com/docs/en/workflows |
+| Reasoning effort is tunable per settings / session / launch / **per-agent frontmatter** / SDK; levels `low, medium, high, xhigh, max` | VERIFIED | code.claude.com/docs/en/model-config#adjust-effort-level, sub-agents doc |
+| Leaked Fable 5 system prompt principles ("partial recognition ≠ current knowledge"; "a prompt implying a file is present doesn't mean one is"; answer-first-then-one-question; tool-call scaling 1 / 3–5 / 5–10) | VERIFIED near-verbatim, **provenance unconfirmed** (third-party leak repo, not Anthropic-confirmed) | github.com/asgeirtj/system_prompts_leaks `Anthropic/claude-fable-5.md` |
+| "Fable 5 on low ≈ Opus 4.8 on high, slightly higher cost/quality" score-vs-cost chart | **CONTRADICTED** — no such chart/statement on Anthropic's pages; GPT-5.5 appears only in a testimonial | anthropic.com/news/claude-fable-5-mythos-5 |
+
+## Already covered — no action
+
+| Video idea | Existing coverage |
+|---|---|
+| "Process is the moat" (config/harness > raw model) | The plugin's entire thesis |
+| Extract repeated procedure into a skill | BP-MECH-003 + CA-OPT-001 (`optimization-lens-scanner.mjs:121`) |
+| CLAUDE.md size/ownership discipline | BP-SIZE-001 + CA-CML line/size checks (`claude-md-linter.mjs:109/:120/:140`) |
+| Check that referenced imports exist | CA-IMP broken `@import` (`lib/import-resolver.mjs:88`) — but **only** `@import`, see Chunk 3 |
+| Plugin's own agents are model-routed | Agents table already pins sonnet for mechanical, opus for judgment |
+
+## Gaps → chunks
+
+Verified gap summary (register-mapper sweep, 2026-07-14): no scanner audits per-agent
+`model:`/`effort:` frontmatter; effort has validity-check only (`settings-validator.mjs:195`),
+no recommendation; no dead-reference check for prose file mentions in CLAUDE.md; no
+adversarial/failure-mode requirement in planner-agent; `fix-engine.mjs:26` effort list
+omits `xhigh` (settings-validator has all five).
+
+### Chunk 1 — Register entries: model routing + effort (dogfoods `knowledge-refresh`)
+
+Add to `knowledge/best-practices.json` via the knowledge-refresh flow (human-approved write):
+
+- **BP-MODEL-001** (`category: model-fit`): subagents doing mechanical/read-only work can pin a
+  cheaper model via `model:` frontmatter; orchestrator keeps the strong model. Source:
+  code.claude.com/docs/en/sub-agents → `confidence: confirmed`.
+- **BP-MODEL-002** (`category: model-fit`): reasoning effort is tunable at five levels in five
+  places (settings `effortLevel`, `/effort`, `--effort`, per-agent `effort` frontmatter, SDK);
+  default `high`; higher effort is not universally better for simple tasks. Source:
+  code.claude.com/docs/en/model-config → `confidence: confirmed`.
+
+Schema per `scanners/lib/best-practices-register.mjs:42-102` (id/claim/confidence/source.url/
+source.verified required). This chunk doubles as the DEL B dogfood of `/config-audit
+knowledge-refresh` (each chunk is also a plugin test).
+
+### Chunk 2 — fix-engine effort hygiene (tiny, TDD)
+
+`fix-engine.mjs:26` `VALID_EFFORT_LEVELS = ['low','medium','high','max']` — missing `xhigh`.
+Consequence: nearest-match "fix" for a typo like `xhig` corrects to `high`, not `xhigh`.
+Red test first: `findNearestEffortLevel('xhig') === 'xhigh'`. Align list with
+`settings-validator.mjs:75`.
+
+### Chunk 3 — CA-CML dead prose references (new deterministic check)
+
+The strongest video-derived principle ("a prompt implying a file is present doesn't mean one
+is") applied to CLAUDE.md quality: flag file paths mentioned in CLAUDE.md **prose** that do not
+exist on disk. Today only `@import` targets are existence-checked; stale pointers like
+`docs/foo.md` or `scripts/bar.sh` rot silently and burn always-loaded tokens on misdirection.
+
+Conservative v1 to control false positives:
+- Only backtick-quoted tokens that look like relative file paths (contain `/` or a known
+  extension), resolved against the CLAUDE.md's own directory.
+- Skip URLs, globs (`*`), placeholders (`{...}`, `<...>`, `$VAR`, `${...}`), absolute and
+  `~/` paths (machine-specific), and paths under `.gitignore`d dirs if cheap to determine.
+- Severity: low. New CA-CML-NNN (verify next free NNN at implementation — IDs are dynamic).
+
+Byte-stability: follow [[adding-scanner-byte-stability]] steps for a new finding type in an
+EXISTING scanner — frozen `tests/snapshots/v5.0.0/` must stay untouched; default-output
+snapshots regenerate (`UPDATE_SNAPSHOT=1`) only if a fixture actually carries the new type;
+humanizer step 7 (M-16/M-17 lessons): `TRANSLATIONS`-static entry for the new RAW title
+(CML category mapping already exists).
+
+### Chunk 4 — feature-gap + inventory: model/effort awareness
+
+- New T3 opportunity check in `feature-gap-scanner.mjs`: authored agents
+  (`isAuthoredConfig`, M-BUG-13 lesson) where **no** agent sets `model:` or `effort:` →
+  "all agents inherit the session model/effort — mechanical agents can be routed cheaper /
+  effort-calibrated" citing BP-MODEL-001/002. Fires only when authored agents exist
+  (M-BUG-15 lesson: no enhancement-check on empty collections). Opportunity framing, never
+  failure — deliberate max-model setups are a valid choice; finding is suppressable
+  (`.config-audit-ignore`).
+- `whats-active` / `manifest`: surface `model`/`effort` per agent in the inventory tables.
+- Humanizer wiring step 7 for the new GAP finding; verify via direct `scan()` output, not the
+  self-suppressed default output ([[agent-commands-need-scanner-scoping]]).
+- feat commit → docs-gate: README + CLAUDE.md diffs required.
+
+### Chunk 5 — planner-agent adversarial gate (do AFTER DEL B pipeline dogfood)
+
+Add a required "Failure modes" section to `agents/planner-agent.md`'s action-plan contract:
+before an action plan is emitted, list what could go wrong per change + rollback trigger.
+Mirrors the video's scoping-vs-devil's-advocate distinction; currently absent (zero
+adversarial requirements in agents/). **Sequencing constraint:** DEL B step 3.2 judges
+planner-agent against a fasit — change the agent only after that dogfood pass, or the
+fasit target moves mid-evaluation.
+
+## Explicitly rejected (do not revisit without new evidence)
+
+1. **"Fable low ≈ Opus high" cost/score framing** — contradicted by Anthropic's own pages.
+   Never encode in register, copy, or recommendations.
+2. **Tool-call-count effort scaling (1 / 3–5 / 5–10) as a register entry** — source is an
+   unconfirmed third-party leak → would be `confidence: inferred`, never surfaced. Not worth
+   carrying.
+3. **Cost/intelligence/"taste" model-routing table generator** — subjective scores don't fit
+   the deterministic, provenance-gated design. BP-MODEL-001 covers the actionable core.
+4. **"Fable mode" skill** — a user-level skill, not configuration auditing. Out of plugin scope.
+5. **CLAUDE.md prose contradiction detection** — real gap (CA-CNF only covers
+   settings/permissions/hooks) but not video-driven; keep this plan surgical.
+
+## Known tension (named, not resolved here)
+
+The operator's own global policy is Opus/max-effort for ALL subagents, never Haiku — the
+opposite of Chunk 4's recommendation. Both are legitimate: the docs-backed routing advice
+optimizes cost at equal quality for the general user; the operator deliberately buys maximum
+quality. Chunk 4's copy must respect that (opportunity framing + suppressability), and on this
+machine the finding will simply be suppressed or ignored. The plugin serves general users;
+the operator's setup is not the target of the check.
+
+## Verification
+
+Global, after every chunk:
+- `node --test 'tests/**/*.test.mjs'` → green (baseline 1359/0; count grows with new tests)
+- `git status --porcelain tests/snapshots/v5.0.0/` → empty (frozen untouched)
+- TDD: red test exists and fails BEFORE each production change
+
+Per chunk:
+- **C1:** `node --test tests/lib/best-practices-register.test.mjs` green;
+  `node scanners/knowledge-refresh-cli.mjs` classifies BP-MODEL-001/002 as fresh
+- **C2:** `findNearestEffortLevel('xhig')` → `xhigh` (red first); `grep xhigh scanners/fix-engine.mjs` non-empty
+- **C3:** fixture CLAUDE.md referencing `docs/missing.md` → finding fires; existing file /
+  URL / glob / placeholder / `~/` path → silent; humanized output has non-contradictory copy
+- **C4:** authored-agent fixture without model/effort → opportunity fires; with either set →
+  silent; zero authored agents → silent; `userImpactCategory` ≠ `Other` end-to-end via direct scan()
+- **C5:** dogfood plan run produces a Failure-modes section; DEL B 3.2 fasit judged BEFORE the change
+
+## Key assumptions (test before/at implementation)
+
+1. **Per-agent `effort` frontmatter is official** — verified 2026-07-14 against
+   code.claude.com/docs/en/sub-agents + /model-config; re-fetch both pages at implementation
+   (docs move).
+2. **New finding type in existing scanner leaves frozen snapshots untouched** — M-17 precedent
+   says yes when no v5.0.0 fixture carries the type; verify by running the suite and inspecting
+   which snapshots differ before committing.
+3. **Next free CA-CML/CA-GAP finding numbers** — IDs are built dynamically; grep tests +
+   snapshots for the highest used NNN before assigning.
+
+## Sequencing vs DEL B (one plan, no relitigation)
+
+This plan does NOT preempt the active DEL B sequence. Recommended order:
+1. DEL B step 3 pipeline dogfood (`analyze → plan → implement → rollback`) — unchanged, next.
+2. Batch patch release M-11→M-17 — unchanged.
+3. v5.13 chunks 1→5 (chunk 1 doubles as the `knowledge-refresh` dogfood already queued in
+   DEL B "Resten"; chunk 5 explicitly waits for step 3.2). Release as minor v5.13.0 via
+   `release-plugin.mjs` when all chunks land.

scanners/cache-prefix-scanner.mjs

@@ -30,7 +30,28 @@ const SCANNER = 'CPS';
 // hits per turn, not to chase every inline date in a long backlog file.
 const CACHED_PREFIX_LINES = 150;
 
-// Volatile-pattern set (extends token-hotspots.mjs Pattern A).
+// CC-provided substitution variables that resolve to a stable per-install or
+// per-project path (e.g. "${CLAUDE_PLUGIN_ROOT}/hooks/x.mjs"). CC expands them
+// to the same value every turn, so they never break the prompt cache — unlike a
+// runtime ${TIMESTAMP}. Excluded from the ${VAR} volatile flag (M-BUG-7).
+const STABLE_CC_VARS = new Set(['CLAUDE_PLUGIN_ROOT', 'CLAUDE_PROJECT_DIR']);
+
+// Matches every ${VAR} occurrence on a line so a line carrying only stable CC
+// vars is not mistaken for a runtime cache-buster.
+const VAR_RX = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
+
+/** True when a line contains at least one non-CC-stable ${VAR} substitution. */
+function hasVolatileVar(line) {
+  VAR_RX.lastIndex = 0;
+  let m;
+  while ((m = VAR_RX.exec(line)) !== null) {
+    if (!STABLE_CC_VARS.has(m[1])) return true;
+  }
+  return false;
+}
+
+// Volatile-pattern set (extends token-hotspots.mjs Pattern A). The ${VAR} entry
+// is `varAware` — flagged via hasVolatileVar() so CC-stable vars are excluded.
 const VOLATILE_PATTERNS = [
   { rx: /\{timestamp\}/i, label: '{timestamp} placeholder' },
   { rx: /\{uuid\}/i, label: '{uuid} placeholder' },
@@ -41,7 +62,7 @@ const VOLATILE_PATTERNS = [
   { rx: /^\s*\[\d{4}-\d{2}-\d{2}/, label: 'dated log line [YYYY-MM-DD ...]' },
   // v5 N3 extensions:
   { rx: /^\s*!/, label: 'shell-exec line (! prefix)' },
-  { rx: /\$\{[A-Z_][A-Z0-9_]*\}/, label: '${VAR} substitution' },
+  { rx: /\$\{[A-Z_][A-Z0-9_]*\}/, label: '${VAR} substitution', varAware: true },
 ];
 
 /**
@@ -68,16 +89,33 @@ function findVolatileLines(content) {
   const out = [];
   if (!content) return out;
   const lines = content.split('\n').slice(0, CACHED_PREFIX_LINES);
+  let inFence = false;
   for (let i = 0; i < lines.length; i++) {
-    for (const { rx, label } of VOLATILE_PATTERNS) {
-      if (rx.test(lines[i])) {
-        out.push({
-          line: i + 1,
-          label,
-          snippet: lines[i].length > 120 ? lines[i].slice(0, 117) + '...' : lines[i],
-        });
-        break;
-      }
+    const line = lines[i];
+    // Fenced code blocks (``` or ~~~) hold illustrative, byte-stable literal
+    // text — a ${VAR} or timestamp shown inside one is documentation, not a
+    // runtime cache-buster — so the fence delimiters and their content are
+    // skipped (M-BUG-7).
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    // Strip `inline code` spans before pattern-testing: a {date} or ${VAR}
+    // shown inside backticks is literal documentation text, byte-stable, not a
+    // runtime cache-buster (M-BUG-7). The original line is still reported as the
+    // snippet so context is preserved.
+    const probe = line.replace(/`[^`]*`/g, '');
+    for (const { rx, label, varAware } of VOLATILE_PATTERNS) {
+      // The ${VAR} pattern flags only non-CC-stable substitutions; every other
+      // pattern keeps its plain line test.
+      if (varAware ? !hasVolatileVar(probe) : !rx.test(probe)) continue;
+      out.push({
+        line: i + 1,
+        label,
+        snippet: line.length > 120 ? line.slice(0, 117) + '...' : line,
+      });
+      break;
     }
   }
   return out;

scanners/conflict-detector.mjs

@@ -5,6 +5,7 @@
  * Finding IDs: CA-CNF-NNN
  */
 
+import { sep } from 'node:path';
 import { readTextFile } from './lib/file-discovery.mjs';
 import { finding, scannerResult } from './lib/output.mjs';
 import { SEVERITY } from './lib/severity.mjs';
@@ -17,6 +18,22 @@ const SCANNER = 'CNF';
 // Keys checked separately or not meaningful to compare
 const SKIP_KEYS = new Set(['$schema', 'hooks', 'permissions']);
 
+// Files under `.claude/plugins/` are shipped by installed plugins — the plugin's
+// own settings.json/hooks.json plus bundled test fixtures and examples. They are
+// not the user's authored cascade and a "conflict" between them is not something
+// the user can resolve, so they must be excluded from cross-scope conflict
+// analysis. (Other scanners still need active plugin config, so this exclusion is
+// CNF-local, not a discovery-level skip. M-BUG-2.)
+const PLUGIN_TREE_MARKER = `.claude${sep}plugins${sep}`;
+
+/**
+ * @param {import('./lib/file-discovery.mjs').ConfigFile} file
+ * @returns {boolean} true if the file is shipped by an installed plugin
+ */
+function isPluginBundled(file) {
+  return file.absPath.includes(PLUGIN_TREE_MARKER);
+}
+
 /**
  * Flatten an object's top-level keys into a simple key→value map.
  * Only first level — we compare top-level settings, not nested.
@@ -63,10 +80,10 @@ export async function scan(targetPath, discovery) {
   const start = Date.now();
   const findings = [];
 
-  // Collect settings files
-  const settingsFiles = discovery.files.filter(f => f.type === 'settings-json');
-  // Collect hooks files
-  const hooksFiles = discovery.files.filter(f => f.type === 'hooks-json');
+  // Collect settings files (excluding plugin-bundled — see PLUGIN_TREE_MARKER)
+  const settingsFiles = discovery.files.filter(f => f.type === 'settings-json' && !isPluginBundled(f));
+  // Collect hooks files (excluding plugin-bundled)
+  const hooksFiles = discovery.files.filter(f => f.type === 'hooks-json' && !isPluginBundled(f));
 
   const totalFiles = settingsFiles.length + hooksFiles.length;
 

scanners/feature-gap-scanner.mjs

@@ -7,7 +7,7 @@
  * Finding IDs: CA-GAP-NNN
  */
 
-import { resolve } from 'node:path';
+import { resolve, join, sep } from 'node:path';
 import { readTextFile, discoverConfigFiles } from './lib/file-discovery.mjs';
 import { finding, scannerResult } from './lib/output.mjs';
 import { SEVERITY } from './lib/severity.mjs';
@@ -46,6 +46,68 @@ function isTargetLocal(ctx, f) {
   return f.absPath.startsWith(ctx.targetPath);
 }
 
+// Files that are test/demo/vendored config — NOT part of the user's authored
+// cascade — must not satisfy "is feature X present?" checks, or they mask real
+// gaps. The canonical case: this plugin's own examples/optimal-setup sets
+// outputStyle/statusLine/worktree/model/keybindings/.lsp.json, and (because GAP
+// always runs includeGlobal) its copies vendored under ~/.claude/plugins/cache
+// drive every tier-3 presence check to "present" — hiding the user's real gaps
+// on ANY target. Two classes to exclude:
+//   - plugin-bundled: anything under ~/.claude/plugins/ (absPath marker, mirrors
+//     the CNF conflict-detector exclusion from M-BUG-2).
+//   - nested demo/test data: a file whose path RELATIVE TO THE SCAN TARGET sits
+//     under an examples/ or tests/fixtures/ subtree. relPath (not absPath) is
+//     deliberate: a fixture scanned AS the target keeps its own files, so the
+//     frozen v5.0.0 byte-snapshots (scanned from tests/fixtures/marketplace-medium)
+//     are untouched. (M-BUG-13)
+const PLUGIN_TREE_MARKER = `.claude${sep}plugins${sep}`;
+
+/**
+ * @param {import('./lib/file-discovery.mjs').ConfigFile} file
+ * @returns {boolean} true if the file is part of the user's authored config
+ */
+function isAuthoredConfig(file) {
+  if (file.absPath.includes(PLUGIN_TREE_MARKER)) return false;
+  const segs = (file.relPath || '').split(sep);
+  if (segs.includes('examples')) return false;
+  const ti = segs.indexOf('tests');
+  if (ti !== -1 && segs[ti + 1] === 'fixtures') return false;
+  return true;
+}
+
+/**
+ * Read the user→project→local settings cascade directly from the filesystem.
+ * The settings-key gap checks ask "does the USER's resolved config set X?" — a
+ * question the includeGlobal discovery answers unreliably on a real machine: the
+ * top-level ~/.claude/settings.json is missed (its relPath carries no `.claude`
+ * segment when the walk root IS ~/.claude) and, when many vendored plugins flood
+ * the walk, dropped by the discovery file cap. Reading the canonical cascade
+ * paths directly is immune to both. Merged INTO (not replacing) the discovery
+ * settings so any non-canonical project settings still count and the frozen
+ * snapshots stay byte-stable. (M-BUG-13)
+ * @param {string} targetPath
+ * @returns {Promise<Array<{ key: string, parsed: object }>>}
+ */
+async function readSettingsCascade(targetPath) {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  const paths = [];
+  if (home) {
+    paths.push(['user', join(home, '.claude', 'settings.json')]);
+    paths.push(['user-local', join(home, '.claude', 'settings.local.json')]);
+  }
+  paths.push(['project', join(targetPath, '.claude', 'settings.json')]);
+  paths.push(['local', join(targetPath, '.claude', 'settings.local.json')]);
+
+  const out = [];
+  for (const [scope, p] of paths) {
+    const content = await readTextFile(p);
+    if (!content) continue;
+    const parsed = parseJson(content);
+    if (parsed && typeof parsed === 'object') out.push({ key: `cascade:${scope}:${p}`, parsed });
+  }
+  return out;
+}
+
 const TIER_SEVERITY = {
   t1: SEVERITY.medium,
   t2: SEVERITY.low,
@@ -479,18 +541,30 @@ export async function scan(targetPath, sharedDiscovery) {
     ? sharedDiscovery
     : await discoverConfigFiles(resolve(targetPath), { includeGlobal: true });
 
-  // Parse all settings files upfront
+  // Presence checks ("does the user have feature X?") must see only the user's
+  // authored cascade — not bundled/vendored/demo config, which masks real gaps
+  // (M-BUG-13, see isAuthoredConfig).
+  const authoredFiles = discovery.files.filter(isAuthoredConfig);
+
+  // Parse all settings files upfront (authored discovery files) ...
   const parsedSettings = new Map();
-  for (const file of discovery.files.filter(f => f.type === 'settings-json')) {
+  for (const file of authoredFiles.filter(f => f.type === 'settings-json')) {
     const content = await readTextFile(file.absPath);
     if (content) {
       const parsed = parseJson(content);
       parsedSettings.set(`${file.scope}:${file.relPath}`, parsed);
     }
   }
+  // ... plus the real user→project→local cascade read directly, so settings-key
+  // checks see the true resolved config regardless of the discovery cap/gotcha
+  // (M-BUG-13). Merged, not replacing — keeps non-canonical project settings and
+  // the frozen byte-snapshots unchanged.
+  for (const { key, parsed } of await readSettingsCascade(resolve(targetPath))) {
+    parsedSettings.set(key, parsed);
+  }
 
   const ctx = {
-    files: discovery.files,
+    files: authoredFiles,
     targetPath: resolve(targetPath),
     parsedSettings,
     fileContents: new Map(),

scanners/lib/active-config-reader.mjs

@@ -53,6 +53,76 @@ export function estimateTokens(bytes, kind = 'markdown', opts = {}) {
   return Math.ceil(bytes / 4);
 }
 
+/**
+ * Strip block-level HTML comments (`<!-- ... -->`) that lie OUTSIDE fenced code
+ * blocks. Claude Code strips these before injecting a CLAUDE.md / memory file
+ * into context (code.claude.com/docs/en/memory: "block-level HTML comments are
+ * stripped before the content is injected"), preserving them only inside fenced
+ * code blocks (``` / ~~~). A byte-accurate token estimate must therefore discount
+ * them. (M-BUG-6)
+ *
+ * Conservative scope — only *block-level* comments are removed (a comment that
+ * occupies its own line(s)); inline comments sharing a line with other text are
+ * retained, since the verified CC behavior covers block-level stripping only.
+ *
+ * @param {string} content
+ * @returns {string} content with out-of-fence block comments removed
+ */
+export function stripInjectedHtmlComments(content) {
+  if (typeof content !== 'string' || content === '') return '';
+  const lines = content.split('\n');
+  const out = [];
+  let inFence = false;
+  let inComment = false;
+  for (const line of lines) {
+    if (inComment) {
+      // Inside a multi-line block comment: drop lines until the closing `-->`,
+      // keeping any real content that trails the close on the same line.
+      const end = line.indexOf('-->');
+      if (end !== -1) {
+        inComment = false;
+        const rest = line.slice(end + 3);
+        if (rest.trim() !== '') out.push(rest);
+      }
+      continue;
+    }
+    // Fence delimiters (``` / ~~~) toggle a preserve-verbatim region.
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      out.push(line);
+      continue;
+    }
+    if (inFence) {
+      out.push(line);
+      continue;
+    }
+    // Whole line is a single self-contained block comment → CC strips it.
+    if (/^\s*<!--[\s\S]*?-->\s*$/.test(line)) continue;
+    // Block comment opening with nothing but whitespace before it and no close
+    // on this line → runs onto following lines.
+    const openIdx = line.indexOf('<!--');
+    if (openIdx !== -1 && line.indexOf('-->', openIdx) === -1 && line.slice(0, openIdx).trim() === '') {
+      inComment = true;
+      continue;
+    }
+    out.push(line);
+  }
+  return out.join('\n');
+}
+
+/**
+ * Effective injected byte length of a CLAUDE.md / memory source: raw UTF-8 bytes
+ * minus the block-level HTML comments CC strips before injection. Used wherever a
+ * CLAUDE.md token estimate must reflect what actually enters context. (M-BUG-6)
+ *
+ * @param {string} content
+ * @returns {number}
+ */
+export function effectiveMemoryBytes(content) {
+  if (typeof content !== 'string') return 0;
+  return Buffer.byteLength(stripInjectedHtmlComments(content), 'utf8');
+}
+
 // ─────────────────────────────────────────────────────────────────────────
 // Load-pattern model (v5.6 Foundation)
 // ─────────────────────────────────────────────────────────────────────────
@@ -202,7 +272,11 @@ export async function walkClaudeMdCascade(repoPath) {
 
   const totalBytes = files.reduce((sum, f) => sum + f.bytes, 0);
   const totalLines = files.reduce((sum, f) => sum + f.lines, 0);
-  const estimatedTokens = estimateTokens(totalBytes, 'markdown');
+  // Token estimate is computed from the *effective* (injected) byte count — CC
+  // strips block-level HTML comments before injection — while totalBytes stays
+  // the honest on-disk figure. (M-BUG-6)
+  const effectiveBytes = files.reduce((sum, f) => sum + (f.effectiveBytes ?? f.bytes), 0);
+  const estimatedTokens = estimateTokens(effectiveBytes, 'markdown');
 
   return { files, totalBytes, totalLines, estimatedTokens };
 }
@@ -217,6 +291,7 @@ async function tryAddClaudeMd(absPath, scope, parent, files, seen) {
       path: absPath,
       scope,
       bytes: s.size,
+      effectiveBytes: effectiveMemoryBytes(content),
       lines: lineCount(content),
       parent,
     };
@@ -572,14 +647,20 @@ async function countPluginItems(pluginRoot) {
   return counts;
 }
 
-async function listMarkdownFiles(dir) {
+async function listMarkdownFiles(dir, recursive = false) {
   const out = [];
   let entries;
   try { entries = await readdir(dir, { withFileTypes: true }); } catch { return out; }
   for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      // Opt-in recursion (M-BUG-3): CC scans agents dirs recursively, so agents
+      // organized into subfolders must be enumerated too. Other callers stay flat.
+      if (recursive) out.push(...await listMarkdownFiles(full, true));
+      continue;
+    }
     if (!e.isFile()) continue;
     if (!e.name.endsWith('.md')) continue;
-    const full = join(dir, e.name);
     try {
       const s = await stat(full);
       out.push({ path: full, size: s.size });
@@ -662,6 +743,11 @@ export async function enumerateSkills(pluginList = []) {
 // Rules, agents, output styles (v5.6 Foundation enumeration)
 // ─────────────────────────────────────────────────────────────────────────
 
+/** True when `v` is a non-empty, non-whitespace string (a usable frontmatter field). */
+function hasText(v) {
+  return typeof v === 'string' && v.trim().length > 0;
+}
+
 /**
  * Build the project/user/plugin directory list for a per-kind enumerator.
  * Project + user dirs live under `.claude/<dir>`; plugins under each of the
@@ -669,8 +755,16 @@ export async function enumerateSkills(pluginList = []) {
  */
 function configDirs(repoPath, pluginList, subdir, pluginSubdirs = [subdir]) {
   const home = process.env.HOME || process.env.USERPROFILE || '';
-  const dirs = [{ dir: join(repoPath, '.claude', subdir), source: 'project', pluginName: null }];
-  if (home) dirs.push({ dir: join(home, '.claude', subdir), source: 'user', pluginName: null });
+  const projectDir = join(repoPath, '.claude', subdir);
+  const userDir = home ? join(home, '.claude', subdir) : null;
+  const dirs = [];
+  // M-BUG-4: when repoPath === $HOME (the `manifest --global` self-scan), the
+  // project dir resolves to the same path as the user dir. Count it once, as
+  // user scope, instead of enumerating the same directory twice.
+  if (!(userDir && userDir === projectDir)) {
+    dirs.push({ dir: projectDir, source: 'project', pluginName: null });
+  }
+  if (userDir) dirs.push({ dir: userDir, source: 'user', pluginName: null });
   for (const p of pluginList) {
     for (const sub of pluginSubdirs) {
       dirs.push({ dir: join(p.path, sub), source: 'plugin', pluginName: p.name });
@@ -730,8 +824,17 @@ export async function enumerateAgents(repoPath, pluginList = []) {
   const lp = deriveLoadPattern('agent');
   const dirs = configDirs(repoPath, pluginList, 'agents');
   for (const { dir, source, pluginName } of dirs) {
-    const files = await listMarkdownFiles(dir);
+    const files = await listMarkdownFiles(dir, true); // M-BUG-3: CC scans agents dirs recursively
     for (const f of files) {
+      // M-BUG-5: CC registers a subagent only when its frontmatter declares both
+      // `name` and `description` (docs: identity comes only from `name`; both are
+      // required). Frontmatter-less / incomplete files are registration no-ops
+      // that cost zero always-loaded tokens — don't count them as agents.
+      let frontmatter;
+      try {
+        ({ frontmatter } = parseFrontmatter(await readFile(f.path, 'utf-8')));
+      } catch { continue; }
+      if (!hasText(frontmatter && frontmatter.name) || !hasText(frontmatter && frontmatter.description)) continue;
       out.push({
         name: basename(f.path).replace(/\.md$/, ''),
         source,

scanners/lib/file-discovery.mjs

@@ -11,6 +11,11 @@ const SKIP_DIRS = new Set([
   'node_modules', '.git', 'dist', 'build', 'coverage', '__pycache__',
   '.next', '.nuxt', '.output', '.cache', '.turbo', '.parcel-cache',
   'vendor', 'venv', '.venv', '.tox',
+  // A `backups` dir holds backup COPIES, not live config — auditing it as if
+  // live produces stale findings. config-audit's own session backups
+  // (~/.claude/config-audit/backups/<ts>/files/.../CLAUDE.md) are the canonical
+  // case (M-BUG-8), but the rule is general: backups are never live config.
+  'backups',
 ]);
 
 // Path marker for the plugin install cache (~/.claude/plugins/cache).

scanners/lib/humanizer-data.mjs

@@ -96,10 +96,10 @@ export const TRANSLATIONS = {
   // ─────────────────────────────────────────────────────────────
   SET: {
     static: {
-      'Unknown settings key': {
-        title: 'A settings key isn\'t recognized',
-        description: 'A key in your settings file isn\'t one Claude Code understands. It will be ignored.',
-        recommendation: 'Check the key name for typos, or remove the key if it\'s no longer in use.',
+      'Possible typo in settings key': {
+        title: 'A settings key looks like a typo',
+        description: 'A key in your settings file isn\'t recognized, but it\'s very close to a real one — likely a typo. Claude Code forwards unrecognized keys unchanged rather than rejecting them, so a misspelled key silently has no effect.',
+        recommendation: 'Check the suggested key name. Fix the spelling, or keep the key if it\'s intentional (e.g. a newer key this audit doesn\'t know yet).',
       },
       'Deprecated settings key': {
         title: 'A settings key is no longer supported',
@@ -435,12 +435,12 @@ export const TRANSLATIONS = {
         recommendation: 'Consider moving team-wide settings to project scope and keeping personal ones at user or local scope.',
       },
       'CLAUDE.md not modular': {
-        title: 'Your instructions file is one big block',
-        description: 'Splitting long instructions into smaller linked files makes them easier to maintain and easier on the loading time.',
+        title: 'Your instructions all live in one file',
+        description: 'Splitting your instructions into smaller linked files with `@import` or `.claude/rules/` keeps each part focused and easier to maintain.',
         recommendation: 'Break out long sections into separate files and link them with `@import`.',
       },
       'No path-scoped rules': {
-        title: 'Your rules all load on every conversation',
+        title: 'You haven\'t set up path-scoped rules yet',
         description: 'Path-scoped rules only load when you\'re working with files that match — keeps each conversation focused.',
         recommendation: 'Add scoping to your rules so they only load for the files they apply to.',
       },
@@ -490,7 +490,7 @@ export const TRANSLATIONS = {
         recommendation: 'Add fields like `model`, `tools`, or `description` to your skill files where useful.',
       },
       'No subagent isolation': {
-        title: 'Your subagents share Claude\'s main work folder',
+        title: 'You haven\'t set up subagent isolation yet',
         description: 'Isolated subagents run in their own copy of the repo so they can\'t accidentally disturb your main work.',
         recommendation: 'Add `isolation: worktree` to subagents that do destructive or experimental work.',
       },
@@ -817,6 +817,11 @@ export const TRANSLATIONS = {
         description: 'Claude Code keeps every active skill\'s description in one shared listing it reads to choose which skill to use, and that listing has a limited size. Added up, your skills\' descriptions run past that size on a smaller setup, so Claude Code may drop some of them — and stop seeing those skills. This is an estimate; a larger setup has more room.',
         recommendation: 'Free up room: turn off bundled skills you do not use, collapse the heaviest ones so only their names show, or shorten the longest descriptions. The details show the measured total and the room available.',
       },
+      'Skill body is large (loads on demand when the skill runs)': {
+        title: 'A skill\'s body is large (it loads only when that skill runs)',
+        description: 'This skill\'s instructions run longer than the rough guidance for a skill body. The body is not part of the always-loaded listing Claude reads every turn — it loads only when you invoke the skill, so it costs nothing until then. Once it loads, though, it stays in context for the rest of that session.',
+        recommendation: 'Move reference material into supporting files the skill opens only when needed, so the body stays lean. For a heavy skill you can also run its body in a separate context with `context: fork` in the skill\'s settings.',
+      },
     },
     patterns: [],
     _default: {

scanners/lib/humanizer.mjs

@@ -38,6 +38,7 @@ const SCANNER_TO_CATEGORY = {
   TOK: 'Wasted tokens',
   CPS: 'Wasted tokens',
   SKL: 'Wasted tokens',
+  AGT: 'Wasted tokens',
   DIS: 'Dead config',
   GAP: 'Missed opportunity',
   PLH: 'Configuration mistake',

scanners/lib/string-utils.mjs

@@ -43,6 +43,41 @@ export function isSimilar(a, b, threshold = 0.8) {
   return similarity >= threshold;
 }
 
+/**
+ * Levenshtein edit distance between two strings (insertions, deletions,
+ * substitutions; a transposition counts as 2). Used for typo detection on
+ * settings keys. Zero external dependencies, O(a*b) with two rolling rows.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export function levenshtein(a, b) {
+  if (a === b) return 0;
+  const al = a.length;
+  const bl = b.length;
+  if (al === 0) return bl;
+  if (bl === 0) return al;
+  let prev = new Array(bl + 1);
+  let curr = new Array(bl + 1);
+  for (let j = 0; j <= bl; j++) prev[j] = j;
+  for (let i = 1; i <= al; i++) {
+    curr[0] = i;
+    const ac = a.charCodeAt(i - 1);
+    for (let j = 1; j <= bl; j++) {
+      const cost = ac === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(
+        prev[j] + 1,        // deletion
+        curr[j - 1] + 1,    // insertion
+        prev[j - 1] + cost, // substitution
+      );
+    }
+    const tmp = prev;
+    prev = curr;
+    curr = tmp;
+  }
+  return prev[bl];
+}
+
 /**
  * Extract all key-like patterns from a settings.json or similar config.
  * @param {object} obj

scanners/optimize-lens-cli.mjs

@@ -24,7 +24,7 @@
  * Exit codes: 0=ok, 3=unrecoverable error. Zero external dependencies.
  */
 
-import { resolve } from 'node:path';
+import { resolve, sep } from 'node:path';
 import { writeFile, readFile, stat } from 'node:fs/promises';
 import { discoverConfigFiles } from './lib/file-discovery.mjs';
 import { resetCounter } from './lib/output.mjs';
@@ -33,6 +33,15 @@ import { loadRegister, getEntry } from './lib/best-practices-register.mjs';
 import { prefilterClaudeMd, LENS_DETECTORS } from './lib/lens-prefilter.mjs';
 import { scan as optScan } from './optimization-lens-scanner.mjs';
 
+// Files under `.claude/plugins/` are shipped by an installed plugin — vendored
+// CLAUDE.md plus its bundled tests/fixtures and examples. They are not the user's
+// authored config, so a mechanism-fit suggestion against them is not actionable
+// (the user can't edit a file the plugin overwrites on update). Excluded from the
+// lens regardless of active/stale version. (M-BUG-11; mirrors the M-BUG-2 rule
+// that keeps plugin-bundled config out of the conflict detector.)
+const PLUGIN_TREE_MARKER = `.claude${sep}plugins${sep}`;
+const isPluginBundled = (file) => (file.absPath || '').includes(PLUGIN_TREE_MARKER);
+
 /** Confirmed register entry for `id`, or null. */
 function confirmedEntry(register, id) {
   const e = getEntry(register, id);
@@ -72,7 +81,13 @@ async function main() {
   }
 
   resetCounter();
-  const discovery = await discoverConfigFiles(absPath, { includeGlobal });
+  const rawDiscovery = await discoverConfigFiles(absPath, { includeGlobal });
+  // Scope the lens to the user's authored config: drop plugin-bundled files for
+  // BOTH halves of the motor (the OPT scanner reads discovery.files directly).
+  const discovery = {
+    ...rawDiscovery,
+    files: (rawDiscovery.files || []).filter((f) => !isPluginBundled(f)),
+  };
 
   // ── Deterministic half: the OPT scanner (CA-OPT-001) ──
   const opt = await optScan(absPath, discovery);
@@ -94,7 +109,11 @@ async function main() {
       const entry = register ? confirmedEntry(register, cand.registerId) : null;
       if (!entry) continue; // never surface an unverifiable recommendation
       candidates.push({
-        file: file.relPath || file.absPath,
+        // Absolute path: unique + readable. relPath collides across scopes
+        // (a repo-root `CLAUDE.md` and the user-global `~/.claude/CLAUDE.md`
+        // both relPath to `CLAUDE.md`), which would send the agent's Read() to
+        // the wrong file. (M-BUG-11)
+        file: file.absPath,
         line: bodyStartLine - 1 + cand.line,
         lensCheck: cand.lensCheck,
         mechanism: cand.mechanism,

scanners/posture.mjs

@@ -10,6 +10,7 @@
 import { resolve } from 'node:path';
 import { writeFile } from 'node:fs/promises';
 import { runAllScanners } from './scan-orchestrator.mjs';
+import { humanizeEnvelope } from './lib/humanizer.mjs';
 import {
   calculateUtilization,
   determineMaturityLevel,
@@ -114,7 +115,14 @@ async function main() {
   }
 
   if (outputFile) {
-    const json = JSON.stringify(result, null, 2);
+    // Consumers (feature-gap.md, posture.md) read scannerEnvelope.scanners[].findings
+    // and group on humanizer fields. posture's result nests the envelope under
+    // `scannerEnvelope`, so humanize THAT (not `result`, which has no top-level
+    // `scanners` array — humanizeEnvelope would no-op). --json/--raw stay raw.
+    const fileEnv = (jsonMode || rawMode)
+      ? result
+      : { ...result, scannerEnvelope: humanizeEnvelope(result.scannerEnvelope) };
+    const json = JSON.stringify(fileEnv, null, 2);
     await writeFile(outputFile, json, 'utf-8');
     process.stderr.write(`\nResults written to ${outputFile}\n`);
   }

scanners/rules-validator.mjs

@@ -10,7 +10,7 @@ import { SEVERITY } from './lib/severity.mjs';
 import { parseFrontmatter } from './lib/yaml-parser.mjs';
 import { lineCount, truncate } from './lib/string-utils.mjs';
 import { readdir, stat } from 'node:fs/promises';
-import { join, resolve, relative } from 'node:path';
+import { join, resolve, relative, sep } from 'node:path';
 
 const SCANNER = 'RUL';
 
@@ -30,8 +30,16 @@ export async function scan(targetPath, discovery) {
     return scannerResult(SCANNER, 'skipped', [], 0, Date.now() - start);
   }
 
-  // Collect all real files in the project for glob matching
-  const projectFiles = await collectProjectFiles(targetPath);
+  // Rule path patterns scope relative to the rule's OWN project root (the dir
+  // containing its .claude/), not the outer scan root. Resolve + cache per root.
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  const projectFilesByRoot = new Map();
+  async function projectFilesFor(root) {
+    if (!projectFilesByRoot.has(root)) {
+      projectFilesByRoot.set(root, await collectProjectFiles(root));
+    }
+    return projectFilesByRoot.get(root);
+  }
 
   for (const file of ruleFiles) {
     const content = await readTextFile(file.absPath);
@@ -74,22 +82,32 @@ export async function scan(targetPath, discovery) {
       if (paths) {
         const patterns = Array.isArray(paths) ? paths : [paths];
 
-        for (const pattern of patterns) {
-          if (typeof pattern !== 'string') continue;
+        // A rule scopes relative to its own project root (parent of its .claude/),
+        // not the scan root. User-global rules (root === HOME) match against the
+        // active project at runtime, so "matches no files here" is not meaningful.
+        const projectRoot = deriveProjectRoot(file.absPath) || targetPath;
+        const isUserGlobal = home && projectRoot === home;
 
-          // Check if pattern matches any real files
-          const matchCount = countGlobMatches(pattern, projectFiles, targetPath);
-          if (matchCount === 0) {
-            findings.push(finding({
-              scanner: SCANNER,
-              severity: SEVERITY.high,
-              title: 'Rule path pattern matches no files',
-              description: `${file.relPath}: pattern "${pattern}" matches 0 files. This rule will never activate.`,
-              file: file.absPath,
-              evidence: `paths: "${pattern}"`,
-              recommendation: 'Check the glob pattern. Common issues: wrong directory name, missing **, incorrect extension.',
-              autoFixable: false,
-            }));
+        if (!isUserGlobal) {
+          const projectFiles = await projectFilesFor(projectRoot);
+
+          for (const pattern of patterns) {
+            if (typeof pattern !== 'string') continue;
+
+            // Check if pattern matches any real files (relative to the rule's root)
+            const matchCount = countGlobMatches(pattern, projectFiles, projectRoot);
+            if (matchCount === 0) {
+              findings.push(finding({
+                scanner: SCANNER,
+                severity: SEVERITY.high,
+                title: 'Rule path pattern matches no files',
+                description: `${file.relPath}: pattern "${pattern}" matches 0 files. This rule will never activate.`,
+                file: file.absPath,
+                evidence: `paths: "${pattern}"`,
+                recommendation: 'Check the glob pattern. Common issues: wrong directory name, missing **, incorrect extension.',
+                autoFixable: false,
+              }));
+            }
           }
         }
       }
@@ -195,6 +213,18 @@ async function collectProjectFiles(targetPath, depth = 0) {
  * @param {string} basePath
  * @returns {number}
  */
+/**
+ * Resolve the project root a rule scopes against: the directory containing the
+ * `.claude/` dir the rule lives under. `/a/b/.claude/rules/x.md` → `/a/b`.
+ * Returns null if the path has no `.claude` segment.
+ */
+function deriveProjectRoot(ruleAbsPath) {
+  const parts = ruleAbsPath.split(sep);
+  const idx = parts.lastIndexOf('.claude');
+  if (idx <= 0) return null;
+  return parts.slice(0, idx).join(sep);
+}
+
 function countGlobMatches(pattern, files, basePath) {
   try {
     const regex = globToRegex(pattern);

scanners/settings-validator.mjs

@@ -8,11 +8,11 @@ import { readTextFile } from './lib/file-discovery.mjs';
 import { finding, scannerResult } from './lib/output.mjs';
 import { SEVERITY } from './lib/severity.mjs';
 import { parseJson } from './lib/yaml-parser.mjs';
-import { extractKeys } from './lib/string-utils.mjs';
+import { extractKeys, levenshtein } from './lib/string-utils.mjs';
 
 const SCANNER = 'SET';
 
-/** Known top-level settings.json keys (as of CC 2.1.181 / June 2026) */
+/** Known top-level settings.json keys (as of CC 2.1.193 / June 2026) */
 const KNOWN_KEYS = new Set([
   'additionalDirectories',
   'agent', 'allowAllClaudeAiMcps', 'allowedChannelPlugins', 'allowedHttpHookUrls',
@@ -37,6 +37,9 @@ const KNOWN_KEYS = new Set([
   'spinnerTipsOverride', 'spinnerVerbs', 'statusLine', 'strictKnownMarketplaces',
   'useAutoModeDuringPlan', 'voiceEnabled', 'wheelScrollAccelerationEnabled',
   'worktree', '$schema',
+  // CC 2.1.193 binary-verified (M-BUG-10): present as quoted string literals in the binary
+  'agentPushNotifEnabled', 'remoteControlAtStartup', 'skipAutoPermissionPrompt',
+  'skipDangerousModePermissionPrompt', 'skipWorkflowUsageWarning', 'tui',
 ]);
 
 /** Deprecated keys with migration info */
@@ -75,6 +78,16 @@ const VALID_EFFORT_LEVELS = new Set(['low', 'medium', 'high', 'xhigh', 'max']);
  * a project root to walks/discovery, inflating per-turn cost and confusing scope. */
 const ADDITIONAL_DIRS_THRESHOLD = 2;
 
+/** M-BUG-10: the CC settings schema is passthrough — it forwards unrecognized
+ * keys unchanged rather than rejecting them, so an arbitrary unknown key is
+ * valid/forward-compatible, not an error. The only real risk is a TYPO of a
+ * real key (the intended setting silently does nothing), so an unknown key is
+ * flagged ONLY when it closely matches a known key: edit distance within
+ * TYPO_MAX_DISTANCE and both keys at least TYPO_MIN_LEN chars (short keys are
+ * too noisy for reliable edit-distance matching). */
+const TYPO_MAX_DISTANCE = 2;
+const TYPO_MIN_LEN = 4;
+
 /** The only valid sub-keys of `autoMode`, each a prose-rule string array
  * (the literal "$defaults" is a valid entry). Verified against
  * code.claude.com/docs/en/auto-mode-config. */
@@ -115,17 +128,32 @@ export async function scan(targetPath, discovery) {
       continue;
     }
 
-    // Check for unknown keys
+    // Check for unknown keys — typo gate (M-BUG-10). The CC settings schema is
+    // passthrough, so an unrecognized key is NOT an error; only a typo of a real
+    // key is (the intended setting silently does nothing). Flag a key only when
+    // it closely matches a known key; an unknown key far from every known key is
+    // treated as valid/forward-compatible and emitted nothing.
     for (const key of Object.keys(parsed)) {
-      if (!KNOWN_KEYS.has(key)) {
+      if (KNOWN_KEYS.has(key)) continue;
+      let nearest = null;
+      let best = Infinity;
+      for (const known of KNOWN_KEYS) {
+        if (Math.min(key.length, known.length) < TYPO_MIN_LEN) continue;
+        const d = levenshtein(key, known);
+        if (d <= TYPO_MAX_DISTANCE && d < best) {
+          best = d;
+          nearest = known;
+        }
+      }
+      if (nearest) {
         findings.push(finding({
           scanner: SCANNER,
-          severity: SEVERITY.medium,
-          title: 'Unknown settings key',
-          description: `${file.relPath}: "${key}" is not a recognized settings.json key. It will be silently ignored.`,
+          severity: SEVERITY.low,
+          title: 'Possible typo in settings key',
+          description: `${file.relPath}: "${key}" is not a recognized settings.json key, but it closely matches "${nearest}". Claude Code forwards unrecognized keys unchanged (it does not reject them), so if "${key}" is a typo of "${nearest}" the intended setting silently has no effect.`,
           file: file.absPath,
           evidence: key,
-          recommendation: 'Check spelling. See https://json.schemastore.org/claude-code-settings.json for valid keys.',
+          recommendation: `Did you mean "${nearest}"? Fix the spelling, or keep "${key}" if it is intentional (e.g. a newer settings key this audit does not recognize yet).`,
           autoFixable: false,
         }));
       }

scanners/token-hotspots.mjs

@@ -22,12 +22,12 @@
  */
 
 import { resolve, dirname, isAbsolute } from 'node:path';
-import { stat } from 'node:fs/promises';
+import { stat, readFile } from 'node:fs/promises';
 import { readTextFile } from './lib/file-discovery.mjs';
 import { finding, scannerResult } from './lib/output.mjs';
 import { SEVERITY } from './lib/severity.mjs';
 import { findImports, parseJson, parseFrontmatter } from './lib/yaml-parser.mjs';
-import { estimateTokens, readActiveConfig, deriveLoadPattern } from './lib/active-config-reader.mjs';
+import { estimateTokens, effectiveMemoryBytes, readActiveConfig, deriveLoadPattern } from './lib/active-config-reader.mjs';
 import {
   assessMcpDeferralForRepo,
   severityForForcedSchemas,
@@ -261,6 +261,26 @@ function detectRedundantPermissions(settings) {
   return issues;
 }
 
+/**
+ * Byte count to feed the token estimator for a discovered file. CLAUDE.md /
+ * memory files are sized from their *effective* (injected) content — CC strips
+ * block-level HTML comments before injection — so a raw byte read over-counts
+ * them. Every other source uses the raw on-disk size. (M-BUG-6)
+ *
+ * @param {{type:string, absPath?:string, size:number}} f
+ * @returns {Promise<number>}
+ */
+async function tokenBytesFor(f) {
+  if (f.type === 'claude-md' && f.absPath) {
+    try {
+      return effectiveMemoryBytes(await readFile(f.absPath, 'utf-8'));
+    } catch {
+      return f.size;
+    }
+  }
+  return f.size;
+}
+
 /**
  * Build the ranked hotspots array.
  *
@@ -272,7 +292,7 @@ async function buildHotspots(discovery, targetPath, activeConfig) {
   const ranked = [];
   for (const f of discovery.files) {
     const kind = tokenKind(f.type);
-    const tokens = estimateTokens(f.size, kind);
+    const tokens = estimateTokens(await tokenBytesFor(f), kind);
     if (tokens <= 0) continue;
     ranked.push({
       absPath: f.absPath,
@@ -651,7 +671,7 @@ export async function scan(targetPath, discovery) {
   // ── Total estimated tokens (sum of every discovered source + activeConfig MCP) ──
   let totalTokens = 0;
   for (const f of discovery.files) {
-    totalTokens += estimateTokens(f.size, tokenKind(f.type));
+    totalTokens += estimateTokens(await tokenBytesFor(f), tokenKind(f.type));
   }
   if (activeConfig && Array.isArray(activeConfig.mcpServers)) {
     for (const m of activeConfig.mcpServers) {

tests/fixtures/cps-fenced/inside-fence/CLAUDE.md

@@ -0,0 +1,46 @@
+# Fenced Documentation Project
+
+Stable preamble. All volatility below is illustrative, inside a code fence.
+Body line 4.
+Body line 5.
+Body line 6.
+Body line 7.
+Body line 8.
+Body line 9.
+Body line 10.
+Body line 11.
+Body line 12.
+Body line 13.
+Body line 14.
+Body line 15.
+Body line 16.
+Body line 17.
+Body line 18.
+Body line 19.
+Body line 20.
+Body line 21.
+Body line 22.
+Body line 23.
+Body line 24.
+Body line 25.
+Body line 26.
+Body line 27.
+Body line 28.
+Body line 29.
+Body line 30.
+Body line 31.
+Body line 32.
+Body line 33.
+Body line 34.
+```bash
+export STAMP=${TIMESTAMP}
+!deploy.sh --at 2026-06-26T10:00:00
+echo {date} > /tmp/log
+[2026-06-26 12:00] starting
+```
+Body line 41.
+Body line 42.
+Body line 43.
+Body line 44.
+Body line 45.
+Body line 46.

tests/fixtures/cps-fenced/mixed/CLAUDE.md

@@ -0,0 +1,55 @@
+# Fenced Plus Prose Project
+
+Stable preamble. A fence below, plus one genuine volatile prose line.
+Body line 4.
+Body line 5.
+Body line 6.
+Body line 7.
+Body line 8.
+Body line 9.
+Body line 10.
+Body line 11.
+Body line 12.
+Body line 13.
+Body line 14.
+Body line 15.
+Body line 16.
+Body line 17.
+Body line 18.
+Body line 19.
+Body line 20.
+Body line 21.
+Body line 22.
+Body line 23.
+Body line 24.
+Body line 25.
+Body line 26.
+Body line 27.
+Body line 28.
+Body line 29.
+Body line 30.
+Body line 31.
+Body line 32.
+Body line 33.
+Body line 34.
+```bash
+export STAMP=${TIMESTAMP}  # documented, not live
+```
+Body line 38.
+Body line 39.
+Body line 40.
+Body line 41.
+Body line 42.
+Body line 43.
+Body line 44.
+Body line 45.
+Body line 46.
+Body line 47.
+Body line 48.
+Body line 49.
+!git log -1  # genuine shell-exec in live prose at line 50
+Body line 51.
+Body line 52.
+Body line 53.
+Body line 54.
+Body line 55.

tests/fixtures/cps-inline-code/mixed/CLAUDE.md

@@ -0,0 +1,55 @@
+# Inline Code Mixed Project
+
+Stable preamble. Backticked template plus a live var in prose.
+Body line 4.
+Body line 5.
+Body line 6.
+Body line 7.
+Body line 8.
+Body line 9.
+Body line 10.
+Body line 11.
+Body line 12.
+Body line 13.
+Body line 14.
+Body line 15.
+Body line 16.
+Body line 17.
+Body line 18.
+Body line 19.
+Body line 20.
+Body line 21.
+Body line 22.
+Body line 23.
+Body line 24.
+Body line 25.
+Body line 26.
+Body line 27.
+Body line 28.
+Body line 29.
+Body line 30.
+Body line 31.
+Body line 32.
+Body line 33.
+Body line 34.
+Body line 35.
+Body line 36.
+Body line 37.
+Body line 38.
+Body line 39.
+Output template is `run-{date}.md` (documented).
+Body line 41.
+Body line 42.
+Body line 43.
+Body line 44.
+Body line 45.
+Body line 46.
+Body line 47.
+Body line 48.
+Body line 49.
+Deployed at ${RELEASE_STAMP} on every push.
+Body line 51.
+Body line 52.
+Body line 53.
+Body line 54.
+Body line 55.

tests/fixtures/cps-inline-code/pure/CLAUDE.md

@@ -0,0 +1,46 @@
+# Inline Code Doc Project
+
+Stable preamble. A filename template is documented in backticks below.
+Body line 4.
+Body line 5.
+Body line 6.
+Body line 7.
+Body line 8.
+Body line 9.
+Body line 10.
+Body line 11.
+Body line 12.
+Body line 13.
+Body line 14.
+Body line 15.
+Body line 16.
+Body line 17.
+Body line 18.
+Body line 19.
+Body line 20.
+Body line 21.
+Body line 22.
+Body line 23.
+Body line 24.
+Body line 25.
+Body line 26.
+Body line 27.
+Body line 28.
+Body line 29.
+Body line 30.
+Body line 31.
+Body line 32.
+Body line 33.
+Body line 34.
+Body line 35.
+Body line 36.
+Body line 37.
+Body line 38.
+Body line 39.
+| `--brief <path>` | writes to `.claude/plans/run-{date}-{slug}.md` |
+Body line 41.
+Body line 42.
+Body line 43.
+Body line 44.
+Body line 45.
+Body line 46.

tests/fixtures/cps-stable-vars/non-whitelisted/CLAUDE.md

@@ -0,0 +1,46 @@
+# Non-Whitelisted Var Project
+
+Stable preamble with a genuine runtime substitution below.
+Body line 4.
+Body line 5.
+Body line 6.
+Body line 7.
+Body line 8.
+Body line 9.
+Body line 10.
+Body line 11.
+Body line 12.
+Body line 13.
+Body line 14.
+Body line 15.
+Body line 16.
+Body line 17.
+Body line 18.
+Body line 19.
+Body line 20.
+Body line 21.
+Body line 22.
+Body line 23.
+Body line 24.
+Body line 25.
+Body line 26.
+Body line 27.
+Body line 28.
+Body line 29.
+Body line 30.
+Body line 31.
+Body line 32.
+Body line 33.
+Body line 34.
+Body line 35.
+Body line 36.
+Body line 37.
+Body line 38.
+Body line 39.
+Deployed build tag: ${DEPLOY_TIMESTAMP} (changes every release).
+Body line 41.
+Body line 42.
+Body line 43.
+Body line 44.
+Body line 45.
+Body line 46.

tests/fixtures/cps-stable-vars/whitelisted/CLAUDE.md

@@ -0,0 +1,46 @@
+# Stable CC Vars Project
+
+Stable preamble — only CC-provided path vars appear below.
+Body line 4.
+Body line 5.
+Body line 6.
+Body line 7.
+Body line 8.
+Body line 9.
+Body line 10.
+Body line 11.
+Body line 12.
+Body line 13.
+Body line 14.
+Body line 15.
+Body line 16.
+Body line 17.
+Body line 18.
+Body line 19.
+Body line 20.
+Body line 21.
+Body line 22.
+Body line 23.
+Body line 24.
+Body line 25.
+Body line 26.
+Body line 27.
+Body line 28.
+Body line 29.
+Body line 30.
+Body line 31.
+Body line 32.
+Body line 33.
+Body line 34.
+Body line 35.
+Body line 36.
+Body line 37.
+Body line 38.
+Body line 39.
+Hooks resolve under ${CLAUDE_PLUGIN_ROOT}/hooks and project root is ${CLAUDE_PROJECT_DIR}.
+Body line 41.
+Body line 42.
+Body line 43.
+Body line 44.
+Body line 45.
+Body line 46.

tests/lib/active-config-reader.test.mjs

@@ -5,6 +5,8 @@ import { mkdir, writeFile, rm, readFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import {
   estimateTokens,
+  stripInjectedHtmlComments,
+  effectiveMemoryBytes,
   detectGitRoot,
   walkClaudeMdCascade,
   readClaudeJsonProjectSlice,
@@ -196,6 +198,85 @@ describe('estimateTokens', () => {
   });
 });
 
+// ─────────────────────────────────────────────────────────────────────────
+// stripInjectedHtmlComments / effectiveMemoryBytes (M-BUG-6)
+// Claude Code strips block-level HTML comments from a CLAUDE.md/memory file
+// before injecting it into context (code.claude.com/docs/en/memory), preserving
+// them only inside fenced code blocks. A byte-accurate token estimate must
+// discount them. Inline comments (text on the same line) are conservatively
+// retained — only block-level stripping is verified behavior.
+// ─────────────────────────────────────────────────────────────────────────
+
+describe('stripInjectedHtmlComments (M-BUG-6)', () => {
+  it('strips a single-line block-level comment outside code fences', () => {
+    const src = '# Title\n\n<!-- maintainer note: regenerate weekly -->\n\nBody text.\n';
+    const out = stripInjectedHtmlComments(src);
+    assert.ok(!out.includes('maintainer note'), 'comment text should be removed');
+    assert.ok(out.includes('# Title') && out.includes('Body text.'), 'surrounding content preserved');
+  });
+
+  it('strips a multi-line block comment outside fences', () => {
+    const src = 'A\n<!--\nline one\nline two\n-->\nB\n';
+    const out = stripInjectedHtmlComments(src);
+    assert.ok(!out.includes('line one') && !out.includes('line two'), 'all comment lines removed');
+    assert.ok(out.includes('A') && out.includes('B'), 'surrounding content preserved');
+  });
+
+  it('preserves an HTML comment inside a ``` fenced code block', () => {
+    const src = '# Title\n\n```html\n<!-- kept: this is example code -->\n```\n';
+    const out = stripInjectedHtmlComments(src);
+    assert.ok(out.includes('kept: this is example code'), 'fenced comment must be preserved (CC keeps it)');
+  });
+
+  it('preserves an HTML comment inside a ~~~ fenced code block', () => {
+    const src = '~~~\n<!-- kept tilde -->\n~~~\n';
+    const out = stripInjectedHtmlComments(src);
+    assert.ok(out.includes('kept tilde'), 'tilde-fenced comment must be preserved');
+  });
+
+  it('keeps inline comments (only block-level stripping is verified)', () => {
+    // Text on the same line as the comment → conservatively retained; the
+    // verified CC behavior covers block-level comments only (Verifiseringsplikt).
+    const src = 'Visible <!-- hidden --> tail\n';
+    assert.equal(stripInjectedHtmlComments(src), src);
+  });
+
+  it('returns content unchanged when there are no comments', () => {
+    const src = '# Plain\n\nNo comments here.\n';
+    assert.equal(stripInjectedHtmlComments(src), src);
+  });
+
+  it('handles empty and non-string input', () => {
+    assert.equal(stripInjectedHtmlComments(''), '');
+    assert.equal(stripInjectedHtmlComments(undefined), '');
+    assert.equal(stripInjectedHtmlComments(null), '');
+  });
+});
+
+describe('effectiveMemoryBytes (M-BUG-6)', () => {
+  it('discounts out-of-fence block comments from the byte count', () => {
+    const src = '# Title\n\n<!-- a fairly long maintainer note that costs real bytes -->\n\nBody.\n';
+    const raw = Buffer.byteLength(src, 'utf8');
+    const eff = effectiveMemoryBytes(src);
+    assert.ok(eff < raw, `effective (${eff}) should be below raw (${raw})`);
+  });
+
+  it('counts comments inside fences (CC keeps them)', () => {
+    const src = '```\n<!-- kept -->\n```\n';
+    assert.equal(effectiveMemoryBytes(src), Buffer.byteLength(src, 'utf8'));
+  });
+
+  it('equals raw bytes when no comments are present', () => {
+    const src = '# Plain markdown\n\nbody\n';
+    assert.equal(effectiveMemoryBytes(src), Buffer.byteLength(src, 'utf8'));
+  });
+
+  it('returns 0 for non-string input', () => {
+    assert.equal(effectiveMemoryBytes(undefined), 0);
+    assert.equal(effectiveMemoryBytes(null), 0);
+  });
+});
+
 // ─────────────────────────────────────────────────────────────────────────
 // detectGitRoot
 // ─────────────────────────────────────────────────────────────────────────
@@ -291,6 +372,23 @@ describe('walkClaudeMdCascade', () => {
     assert.equal(result.estimatedTokens, Math.ceil(result.totalBytes / 4));
   });
 
+  it('discounts block-level HTML comments from estimatedTokens (M-BUG-6)', async () => {
+    // CC strips block-level HTML comments before injection, so a CLAUDE.md
+    // padded with a maintainer-note comment must estimate FEWER tokens than its
+    // raw byte size would imply — totalBytes stays the honest on-disk figure.
+    const comment = `<!-- ${'maintainer note '.repeat(40)} -->`;
+    await writeFile(
+      join(fixture.root, 'CLAUDE.md'),
+      `# Project Instructions\n\n${comment}\n\nBuild with care.\n`,
+    );
+    const result = await walkClaudeMdCascade(fixture.root);
+    assert.ok(
+      result.estimatedTokens < Math.ceil(result.totalBytes / 4),
+      `expected discounted tokens (${result.estimatedTokens}) below raw heuristic ` +
+        `(${Math.ceil(result.totalBytes / 4)})`,
+    );
+  });
+
   it('handles missing user CLAUDE.md gracefully', async () => {
     // Remove user CLAUDE.md
     await rm(join(fixture.fakeHome, '.claude', 'CLAUDE.md'));
@@ -952,6 +1050,70 @@ describe('enumerateAgents (v5.6)', () => {
     await mkdir(root, { recursive: true });
     assert.deepEqual(await enumerateAgents(root, []), []);
   });
+
+  // M-BUG-5: CC registers a subagent only when its frontmatter declares both
+  // `name` and `description` (docs: identity comes only from `name`; both are
+  // required). Frontmatter-less / incomplete files are registration no-ops that
+  // cost zero always-loaded tokens — they must NOT be counted as agents.
+  it('M-BUG-5: skips files with no frontmatter at all', async () => {
+    const dir = join(root, '.claude', 'agents');
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'reviewer.md'), '---\nname: reviewer\ndescription: reviews code\n---\nbody\n');
+    await writeFile(join(dir, 'not-an-agent.md'), '# Not An Agent\n\nJust a markdown doc, no frontmatter.\n');
+    const agents = await enumerateAgents(root, []);
+    assert.deepEqual(agents.map(a => a.name).sort(), ['reviewer']);
+  });
+
+  it('M-BUG-5: skips files missing name or description', async () => {
+    const dir = join(root, '.claude', 'agents');
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'reviewer.md'), '---\nname: reviewer\ndescription: reviews code\n---\nbody\n');
+    await writeFile(join(dir, 'name-only.md'), '---\nname: name-only\n---\nbody\n');
+    await writeFile(join(dir, 'desc-only.md'), '---\ndescription: has no name\n---\nbody\n');
+    await writeFile(join(dir, 'empty-name.md'), '---\nname:\ndescription: blank name\n---\nbody\n');
+    const agents = await enumerateAgents(root, []);
+    assert.deepEqual(agents.map(a => a.name).sort(), ['reviewer']);
+  });
+
+  // M-BUG-3: CC scans agents dirs recursively, so a valid agent in a subfolder
+  // (e.g. agents/review/security.md) is registered and must be counted.
+  it('M-BUG-3: recurses into agent subdirectories', async () => {
+    const sub = join(root, '.claude', 'agents', 'review');
+    await mkdir(sub, { recursive: true });
+    await writeFile(join(sub, 'security.md'), '---\nname: security\ndescription: security review\n---\nbody\n');
+    const agents = await enumerateAgents(root, []);
+    const a = agents.find(x => x.name === 'security');
+    assert.ok(a, 'agent in subdir should be counted');
+    assert.equal(a.source, 'project');
+  });
+});
+
+// M-BUG-4: when repoPath === $HOME (the `manifest --global` self-scan), the
+// project agents dir resolves to the SAME path as the user agents dir. The
+// shared configDirs helper must count it once (as user scope), not twice.
+describe('enumerateAgents — HOME self-scan dedup (M-BUG-4)', () => {
+  let home, originalHome;
+  beforeEach(async () => {
+    home = uniqueDir('agents-home-selfscan');
+    await mkdir(join(home, '.claude', 'agents'), { recursive: true });
+    originalHome = process.env.HOME;
+    process.env.HOME = home;
+  });
+  afterEach(async () => {
+    process.env.HOME = originalHome;
+    await rm(home, { recursive: true, force: true });
+  });
+
+  it('does not double-count user agents when repoPath === HOME', async () => {
+    await writeFile(
+      join(home, '.claude', 'agents', 'solo.md'),
+      '---\nname: solo\ndescription: only one of me\n---\nbody\n',
+    );
+    const agents = await enumerateAgents(home, []);
+    const solos = agents.filter(a => a.name === 'solo');
+    assert.equal(solos.length, 1, 'agent at HOME must be counted once, not twice');
+    assert.equal(solos[0].source, 'user', 'HOME self-scan agents are user scope');
+  });
 });
 
 describe('enumerateOutputStyles (v5.6)', () => {

tests/lib/file-discovery.test.mjs

@@ -1,6 +1,6 @@
 import { describe, it, before, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { join } from 'node:path';
+import { join, sep } from 'node:path';
 import { mkdir, writeFile, rm, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import {
@@ -509,3 +509,49 @@ describe('discoverConfigFiles — cache-aware filtering', () => {
     assert.ok(!keys.has(STALE1) && !keys.has(STALE2), 'stale dropped via Multi');
   });
 });
+
+// ───────────────────────────────────────────────────────────────
+// Group 8: backups/ skip (M-BUG-8) — a directory named `backups`
+// holds backup COPIES, not live config. config-audit's own session
+// backups (~/.claude/config-audit/backups/<ts>/files/plugins/*/CLAUDE.md)
+// were walked as if live, producing stale findings on a ~/.claude audit.
+// ───────────────────────────────────────────────────────────────
+
+describe('discoverConfigFiles — skips backups/ (M-BUG-8)', () => {
+  let dir;
+
+  before(async () => {
+    dir = tempDir('backups');
+    // A live CLAUDE.md at the root (must still be discovered).
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'CLAUDE.md'), '# Live config');
+    // config-audit's own backup tree — frozen copies, NOT live config.
+    const backupClaude = join(dir, 'config-audit', 'backups', '20260518_103233', 'files', 'plugins', 'voyage');
+    await mkdir(backupClaude, { recursive: true });
+    await writeFile(join(backupClaude, 'CLAUDE.md'), '# Frozen backup copy');
+    const backupSettings = join(dir, 'config-audit', 'backups', '20260518_103233', 'files', '.claude');
+    await mkdir(backupSettings, { recursive: true });
+    await writeFile(join(backupSettings, 'settings.json'), '{}');
+  });
+
+  after(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('discovers the live CLAUDE.md', async () => {
+    const { files } = await discoverConfigFiles(dir);
+    const live = files.find(f => f.relPath === 'CLAUDE.md');
+    assert.ok(live, 'live CLAUDE.md at root should be discovered');
+  });
+
+  it('does NOT discover config files under a backups/ directory', async () => {
+    const { files } = await discoverConfigFiles(dir);
+    const inBackups = files.filter(f => f.absPath.includes(`backups${sep}`));
+    assert.equal(inBackups.length, 0, 'no files under backups/ should be discovered');
+  });
+
+  it('counts backups/ as a skipped directory', async () => {
+    const { skipped } = await discoverConfigFiles(dir);
+    assert.ok(skipped >= 1, 'backups/ should be counted as skipped');
+  });
+});

tests/lib/humanizer-data.test.mjs

@@ -162,6 +162,63 @@ test('CML, SET, HKV, RUL, MCP, IMP, GAP, TOK, PLH have non-empty static maps', (
   }
 });
 
+test('GAP "CLAUDE.md not modular" copy is size-neutral (M-BUG-14)', () => {
+  // The t2_2 check is a pure presence check (no length gate), so a small
+  // non-modular CLAUDE.md must not be told it is "big"/"long" or that it
+  // costs "loading time". Title + description must stay size/cost-neutral
+  // and keep only the honest structural "split into linked files" framing.
+  const t = TRANSLATIONS.GAP.static['CLAUDE.md not modular'];
+  assert.ok(t, 'GAP static map missing "CLAUDE.md not modular"');
+  const title = t.title.toLowerCase();
+  const desc = t.description.toLowerCase();
+  assert.ok(!/\bbig\b/.test(title), `title overclaims size: "${t.title}"`);
+  assert.ok(!/\blong\b/.test(title), `title overclaims size: "${t.title}"`);
+  assert.ok(!/\bbig\b/.test(desc), `description overclaims size: "${t.description}"`);
+  assert.ok(!/\blong\b/.test(desc), `description overclaims size: "${t.description}"`);
+  assert.ok(!/loading time/.test(desc), `description overclaims load cost: "${t.description}"`);
+  assert.ok(/split/.test(desc), `description should keep structural split framing: "${t.description}"`);
+});
+
+test('GAP enhancement-gap titles do not presuppose the feature exists (M-BUG-15)', () => {
+  // t2_3 ("No path-scoped rules") and t3_6 ("No subagent isolation") iterate a
+  // collection and return false for an EMPTY one — so they fire even when the
+  // user has zero rules / zero subagents. The humanized title must therefore
+  // not assert the feature exists, or it contradicts the sibling presence gap
+  // ("No custom subagents" → "You haven't set up any specialized helper agents
+  // yet"). Mirror the house "You haven't set up X yet" framing — honest for
+  // both the zero-state and the has-but-unconfigured state.
+  const rules = TRANSLATIONS.GAP.static['No path-scoped rules'];
+  const iso = TRANSLATIONS.GAP.static['No subagent isolation'];
+  assert.ok(rules, 'GAP static map missing "No path-scoped rules"');
+  assert.ok(iso, 'GAP static map missing "No subagent isolation"');
+  // Title must not presuppose existing rules / subagents.
+  assert.ok(!/your rules all load/i.test(rules.title),
+    `t2_3 title presupposes existing rules: "${rules.title}"`);
+  assert.ok(!/your subagents/i.test(iso.title),
+    `t3_6 title presupposes existing subagents: "${iso.title}"`);
+  // Title must still name the feature it points at.
+  assert.ok(/path-scoped rules/i.test(rules.title),
+    `t2_3 title should still name path-scoped rules: "${rules.title}"`);
+  assert.ok(/isolation/i.test(iso.title),
+    `t3_6 title should still name subagent isolation: "${iso.title}"`);
+});
+
+test('SKL oversized-body copy is on-demand, not listing-budget (M-BUG-16)', () => {
+  // The skill-listing check emits a third finding for an oversized skill BODY,
+  // which loads ON DEMAND only when the skill runs — not the always-loaded
+  // listing. Before the fix this title had no static entry and fell through to
+  // the SKL _default ("using more of the listing budget"), contradicting the
+  // finding's own evidence ("NOT every turn like the always-loaded listing").
+  const t = TRANSLATIONS.SKL.static['Skill body is large (loads on demand when the skill runs)'];
+  assert.ok(t, 'SKL static map missing "Skill body is large (loads on demand when the skill runs)"');
+  assert.ok(!/listing budget/i.test(t.title), `body title must not claim listing budget: "${t.title}"`);
+  assert.ok(!/listing budget/i.test(t.description), `body description must not claim listing budget: "${t.description}"`);
+  // Must convey the on-demand body cost.
+  assert.ok(/body/i.test(t.title), `body title should name the body: "${t.title}"`);
+  assert.ok(/loads only|on demand|when (it|that|the) skill runs|when you invoke/i.test(t.title + ' ' + t.description),
+    `copy should convey the on-demand load: "${t.title}" / "${t.description}"`);
+});
+
 test('CNF, COL, PLH have at least one pattern entry (template-literal titles)', () => {
   // These scanners use template-literal titles for some findings.
   for (const prefix of ['CNF', 'COL', 'PLH']) {

tests/lib/humanizer.test.mjs

@@ -116,6 +116,27 @@ test('humanizeFinding falls back to _default when title unknown', () => {
   assert.ok(/instructions file/i.test(out.title), `expected CML _default title, got: ${out.title}`);
 });
 
+test('humanizeFinding maps SKL oversized-body finding to an on-demand title, not the listing-budget _default', () => {
+  // RAW title emitted by skill-listing-scanner for body > threshold (v5.11 B7).
+  // It is an ON-DEMAND body cost, NOT the always-loaded listing budget — the
+  // scanner is careful to distinguish them, so the humanized title must not
+  // regress into "listing budget" language via the SKL _default (M-BUG-16).
+  const input = makeFinding({
+    scanner: 'SKL',
+    severity: 'low',
+    title: 'Skill body is large (loads on demand when the skill runs)',
+    description: 'Skill "repo-init" (user) has a body of about 6223 tokens (712 lines), over the ~5000-token guidance for a skill body.',
+    evidence: 'body_tokens~6223; threshold=5000 tok; skill="repo-init"; source=user - this is the skill BODY which loads ON DEMAND only when the skill is invoked - NOT every turn like the always-loaded listing.',
+  });
+  const out = humanizeFinding(input);
+  assert.doesNotMatch(out.title, /listing budget/i,
+    `body finding must not be framed as a listing-budget cost, got: ${out.title}`);
+  assert.notEqual(out.title, 'A skill is using more of the listing budget than it should',
+    'body finding must have its own mapping, not the SKL _default');
+  assert.match(out.title, /body|on demand|when (it|the skill) runs/i,
+    `humanized title must convey the on-demand body cost, got: ${out.title}`);
+});
+
 test('humanizeFinding passes through original strings when scanner prefix unknown', () => {
   const input = makeFinding({ scanner: 'XXX', title: 'whatever' });
   const out = humanizeFinding(input);
@@ -184,10 +205,13 @@ test('humanizeFinding sets category Conflict for CNF/COL', () => {
   }
 });
 
-test('humanizeFinding sets category Wasted tokens for TOK/CPS/SKL', () => {
-  for (const s of ['TOK', 'CPS', 'SKL']) {
+test('humanizeFinding sets category Wasted tokens for TOK/CPS/SKL/AGT', () => {
+  // AGT (agent-listing budget) is an always-loaded per-turn token cost — the
+  // agent name+description is re-sent every turn in the listing — so it belongs
+  // in "Wasted tokens" alongside TOK/CPS/SKL, not the 'Other' fallback (M-BUG-17).
+  for (const s of ['TOK', 'CPS', 'SKL', 'AGT']) {
     const out = humanizeFinding(makeFinding({ scanner: s }));
-    assert.equal(out.userImpactCategory, 'Wasted tokens');
+    assert.equal(out.userImpactCategory, 'Wasted tokens', `${s} should map to Wasted tokens`);
   }
 });
 

tests/lib/string-utils.test.mjs

@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { lineCount, truncate, isSimilar, extractKeys, normalizePath } from '../../scanners/lib/string-utils.mjs';
+import { lineCount, truncate, isSimilar, extractKeys, normalizePath, levenshtein } from '../../scanners/lib/string-utils.mjs';
 
 describe('lineCount', () => {
   it('counts lines correctly', () => {
@@ -90,6 +90,42 @@ describe('extractKeys', () => {
   });
 });
 
+describe('levenshtein', () => {
+  it('returns 0 for identical strings', () => {
+    assert.strictEqual(levenshtein('permissions', 'permissions'), 0);
+  });
+
+  it('counts a single substitution as 1', () => {
+    assert.strictEqual(levenshtein('model', 'modet'), 1);
+  });
+
+  it('counts a single deletion as 1 (permisions → permissions)', () => {
+    assert.strictEqual(levenshtein('permisions', 'permissions'), 1);
+  });
+
+  it('counts a single insertion as 1', () => {
+    assert.strictEqual(levenshtein('hooks', 'hooks2'), 1);
+  });
+
+  it('counts a transposition as 2 (standard Levenshtein)', () => {
+    assert.strictEqual(levenshtein('import', 'improt'), 2);
+  });
+
+  it('returns the other length when one string is empty', () => {
+    assert.strictEqual(levenshtein('', 'abc'), 3);
+    assert.strictEqual(levenshtein('abc', ''), 3);
+    assert.strictEqual(levenshtein('', ''), 0);
+  });
+
+  it('is symmetric', () => {
+    assert.strictEqual(levenshtein('effortLevel', 'efortLevel'), levenshtein('efortLevel', 'effortLevel'));
+  });
+
+  it('gives a large distance for unrelated keys', () => {
+    assert.ok(levenshtein('unknownKey123', 'permissions') > 2);
+  });
+});
+
 describe('normalizePath', () => {
   it('expands ~ to HOME', () => {
     const home = process.env.HOME;

tests/scanners/cache-prefix.test.mjs

@@ -86,6 +86,66 @@ describe('CPS scanner — volatile content in @imported files (v5.10 B6)', () =>
   });
 });
 
+describe('CPS scanner — CC-stable vars are not cache-busters (M-BUG-7)', () => {
+  it('does NOT flag ${CLAUDE_PLUGIN_ROOT} / ${CLAUDE_PROJECT_DIR} in prose', async () => {
+    // These are CC-provided path substitutions that resolve to a stable value
+    // every turn — referencing them in CLAUDE.md prose is not a cache-buster.
+    const result = await runScanner('cps-stable-vars/whitelisted');
+    const f = result.findings.find(x => /volatile content inside cached prefix/i.test(x.title || ''));
+    assert.equal(f, undefined,
+      `CC-stable path vars must not trip CPS; got: ${f?.evidence}`);
+  });
+
+  it('STILL flags a genuine non-CC ${VAR} substitution (whitelist is selective)', async () => {
+    const result = await runScanner('cps-stable-vars/non-whitelisted');
+    const f = result.findings.find(x => /volatile content inside cached prefix/i.test(x.title || ''));
+    assert.ok(f, `expected a finding for a genuine runtime var; got none`);
+    assert.match(String(f.evidence || ''), /line 40/);
+    assert.match(String(f.evidence || ''), /\$\{VAR\} substitution/i);
+  });
+});
+
+describe('CPS scanner — volatility inside fenced code blocks is documentation (M-BUG-7)', () => {
+  it('does NOT flag volatile-looking lines inside a ```fence```', async () => {
+    // Content inside a fenced code block is illustrative, byte-stable literal
+    // text — not runtime volatility — so it must not break the cached prefix.
+    const result = await runScanner('cps-fenced/inside-fence');
+    const f = result.findings.find(x => /volatile content inside cached prefix/i.test(x.title || ''));
+    assert.equal(f, undefined,
+      `fenced code content must not trip CPS; got: ${f?.evidence}`);
+  });
+
+  it('STILL flags genuine volatility in live prose outside the fence', async () => {
+    const result = await runScanner('cps-fenced/mixed');
+    const f = result.findings.find(x => /volatile content inside cached prefix/i.test(x.title || ''));
+    assert.ok(f, `expected a finding for the out-of-fence volatile line; got none`);
+    assert.match(String(f.evidence || ''), /line 50/);
+    assert.match(String(f.evidence || ''), /shell-exec/i);
+    assert.doesNotMatch(String(f.evidence || ''), /line 3[567]/,
+      'fenced lines 35–37 must not appear in the evidence');
+  });
+});
+
+describe('CPS scanner — volatility inside inline code is documentation (M-BUG-7)', () => {
+  it('does NOT flag a {date} placeholder shown inside `inline code`', async () => {
+    // A filename template like `.claude/plans/run-{date}.md` in backticks is
+    // literal documentation text — byte-stable, not a runtime substitution.
+    const result = await runScanner('cps-inline-code/pure');
+    const f = result.findings.find(x => /volatile content inside cached prefix/i.test(x.title || ''));
+    assert.equal(f, undefined,
+      `inline-code documentation must not trip CPS; got: ${f?.evidence}`);
+  });
+
+  it('STILL flags a live ${VAR} that sits outside backticks', async () => {
+    const result = await runScanner('cps-inline-code/mixed');
+    const f = result.findings.find(x => /volatile content inside cached prefix/i.test(x.title || ''));
+    assert.ok(f, `expected a finding for the out-of-backtick volatile line; got none`);
+    assert.match(String(f.evidence || ''), /line 50/);
+    assert.doesNotMatch(String(f.evidence || ''), /line 40/,
+      'the backticked {date} on line 40 must not appear in the evidence');
+  });
+});
+
 describe('CPS scanner — orchestrator wiring', () => {
   it('CPS appears in scan-orchestrator scanner list', async () => {
     const orch = await import('../../scanners/scan-orchestrator.mjs');

tests/scanners/conflict-detector.test.mjs

@@ -1,6 +1,6 @@
 import { describe, it, beforeEach, before, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { resolve, join } from 'node:path';
+import { resolve, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { mkdir, writeFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
@@ -208,3 +208,98 @@ describe('CNF scanner — cache exclusion drops duplicate-hook count (B3)', () =
       `cache exclusion must drop CNF count: include=${includeCount} exclude=${excludeCount}`);
   });
 });
+
+// M-BUG-2: CNF must segregate plugin-bundled configs from the user's authored
+// cascade. Installed plugins ship their OWN settings.json / hooks.json — plus
+// bundled test fixtures and examples — under ~/.claude/plugins/. None of these
+// are user-authored config the user can edit, and a "conflict" between two
+// plugins' bundled files is not something the user can resolve. Yet CNF compared
+// every settings-json/hooks-json pairwise regardless of origin, inflating the
+// Conflicts grade to F with hundreds of bogus findings (339 on this machine,
+// ~315 of them high-severity permission "conflicts" between plugin test
+// fixtures). CNF must exclude any file whose path is under `.claude/plugins/`.
+// The exclusion belongs in CNF, NOT discovery: an active plugin's contributed
+// hooks.json/.mcp.json legitimately lives in plugins/cache and other scanners
+// need it — only conflict analysis must ignore it.
+describe('CNF scanner — excludes plugin-bundled configs (M-BUG-2)', () => {
+  let dir, result, discovery;
+
+  before(async () => {
+    dir = join(tmpdir(), `config-audit-cnf-mbug2-${Date.now()}`);
+    // Live, user-authored cascade (project-scope settings).
+    const liveClaude = join(dir, '.claude');
+    await mkdir(liveClaude, { recursive: true });
+    await writeFile(join(liveClaude, 'settings.json'), JSON.stringify({
+      model: 'opus',
+      permissions: { deny: ['Bash(curl:*)'] },
+      hooks: { PreToolUse: [{ matcher: 'Edit' }] },
+    }));
+    // An installed plugin ships its OWN settings.json + hooks.json (active version).
+    const p1 = join(liveClaude, 'plugins', 'cache', 'mkt', 'p1', '1.0.0');
+    await mkdir(join(p1, '.claude'), { recursive: true });
+    await writeFile(join(p1, '.claude', 'settings.json'), JSON.stringify({
+      model: 'sonnet',
+      permissions: { allow: ['Bash(curl:*)'] },
+      hooks: { PreToolUse: [{ matcher: 'Edit' }] },
+    }));
+    await mkdir(join(p1, 'hooks'), { recursive: true });
+    await writeFile(join(p1, 'hooks', 'hooks.json'), JSON.stringify({
+      hooks: { PreToolUse: [{ matcher: 'Edit' }] },
+    }));
+    // Another plugin ships a TEST FIXTURE settings.json — pure noise, never live.
+    const p2fix = join(liveClaude, 'plugins', 'cache', 'mkt', 'p2', '2.0.0',
+      'tests', 'fixtures', 'proj', '.claude');
+    await mkdir(p2fix, { recursive: true });
+    await writeFile(join(p2fix, 'settings.json'), JSON.stringify({
+      model: 'haiku',
+      permissions: { allow: ['Bash(rm:*)'] },
+    }));
+
+    resetCounter();
+    discovery = await discoverConfigFiles(dir);
+    result = await scan(dir, discovery);
+  });
+
+  after(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('discovery surfaces the plugin-bundled settings (exclusion must be CNF-side, not discovery-side)', () => {
+    const pluginSettings = discovery.files.filter(
+      f => f.type === 'settings-json' && f.absPath.includes(`.claude${sep}plugins${sep}`));
+    assert.ok(pluginSettings.length >= 2,
+      `expected ≥2 plugin-bundled settings discovered; got ${pluginSettings.length}`);
+  });
+
+  it('does not flag any conflict sourced from plugin-bundled configs', () => {
+    assert.equal(result.findings.length, 0,
+      `expected 0 CNF findings (only noise is plugin-bundled); got ${result.findings.length}: ${result.findings.map(f => f.title).join(', ')}`);
+  });
+});
+
+// Guard against over-exclusion: the fix must NOT silence genuine conflicts
+// between the user's own authored files (user/project/local), which are not
+// under `.claude/plugins/`.
+describe('CNF scanner — genuine live conflict still flagged (M-BUG-2 guard)', () => {
+  let dir, result;
+
+  before(async () => {
+    dir = join(tmpdir(), `config-audit-cnf-mbug2-guard-${Date.now()}`);
+    const claude = join(dir, '.claude');
+    await mkdir(claude, { recursive: true });
+    await writeFile(join(claude, 'settings.json'), JSON.stringify({ model: 'opus' }));
+    await writeFile(join(claude, 'settings.local.json'), JSON.stringify({ model: 'haiku' }));
+    resetCounter();
+    const discovery = await discoverConfigFiles(dir);
+    result = await scan(dir, discovery);
+  });
+
+  after(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('still flags the genuine cross-scope key conflict between user-authored files', () => {
+    assert.ok(result.findings.some(f => f.title.includes('model')),
+      `expected a genuine "model" conflict; got: ${result.findings.map(f => f.title).join(', ') || '(none)'}`);
+  });
+});

tests/scanners/feature-gap-scanner.test.mjs

@@ -1,6 +1,6 @@
 import { describe, it, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { resolve, join } from 'node:path';
+import { resolve, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
@@ -411,3 +411,98 @@ describe('GAP scanner — filter-before lever wiring (chatty hook fixture)', ()
     assert.equal(lever, undefined, `expected no filter-before lever; got id=${lever?.id}`);
   });
 });
+
+describe('GAP scanner — test/demo data must not mask real gaps (M-BUG-13)', () => {
+  // Build a throwaway project (+ optional hermetic HOME settings) and run GAP
+  // exactly as posture --global does: includeGlobal discovery + scan().
+  async function runGap({ projectFiles = {}, homeSettings = null } = {}) {
+    const project = await mkdtemp(join(tmpdir(), 'config-audit-gap-mask-proj-'));
+    const home = await mkdtemp(join(tmpdir(), 'config-audit-gap-mask-home-'));
+    for (const [rel, content] of Object.entries(projectFiles)) {
+      const abs = join(project, rel);
+      await mkdir(dirname(abs), { recursive: true });
+      await writeFile(abs, content);
+    }
+    if (homeSettings) {
+      await mkdir(join(home, '.claude'), { recursive: true });
+      await writeFile(join(home, '.claude', 'settings.json'), JSON.stringify(homeSettings));
+    }
+    const original = process.env.HOME;
+    process.env.HOME = home;
+    try {
+      resetCounter();
+      const discovery = await discoverConfigFiles(project, { includeGlobal: true });
+      const result = await scan(project, discovery);
+      return result;
+    } finally {
+      process.env.HOME = original;
+      await rm(project, { recursive: true, force: true });
+      await rm(home, { recursive: true, force: true });
+    }
+  }
+
+  const hasGap = (result, titleRe) =>
+    result.findings.some(f => f.scanner === 'GAP' && titleRe.test(f.title || ''));
+
+  it('a nested examples/ settings.json does NOT satisfy the outputStyle check (settings-key)', async () => {
+    const result = await runGap({
+      projectFiles: {
+        '.claude/CLAUDE.md': '# proj',
+        'examples/optimal-setup/.claude/settings.json': JSON.stringify({ outputStyle: 'Explanatory' }),
+      },
+    });
+    assert.ok(
+      hasGap(result, /output style/i),
+      `example settings.json must not mask the outputStyle gap; got: ${result.findings.map(f => f.title).join(' | ')}`,
+    );
+  });
+
+  it('a nested examples/ keybindings.json does NOT satisfy the keybindings check (file-type)', async () => {
+    const result = await runGap({
+      projectFiles: {
+        '.claude/CLAUDE.md': '# proj',
+        'examples/optimal-setup/.claude/keybindings.json': JSON.stringify({}),
+      },
+    });
+    assert.ok(
+      hasGap(result, /keybinding/i),
+      `example keybindings.json must not mask the keybindings gap; got: ${result.findings.map(f => f.title).join(' | ')}`,
+    );
+  });
+
+  it('a nested tests/fixtures/ settings.json does NOT satisfy the model check', async () => {
+    const result = await runGap({
+      projectFiles: {
+        '.claude/CLAUDE.md': '# proj',
+        'tests/fixtures/demo/.claude/settings.json': JSON.stringify({ model: 'opus' }),
+      },
+    });
+    assert.ok(
+      hasGap(result, /model config/i),
+      `fixture settings.json must not mask the model gap; got: ${result.findings.map(f => f.title).join(' | ')}`,
+    );
+  });
+
+  it("the project's OWN real .claude/settings.json IS counted (not over-excluded)", async () => {
+    const result = await runGap({
+      projectFiles: {
+        '.claude/CLAUDE.md': '# proj',
+        '.claude/settings.json': JSON.stringify({ outputStyle: 'Explanatory' }),
+      },
+    });
+    assert.ok(
+      !hasGap(result, /output style/i),
+      `real project settings.json must satisfy outputStyle; got: ${result.findings.map(f => f.title).join(' | ')}`,
+    );
+  });
+
+  it('the real ~/.claude/settings.json IS seen for settings-key checks (gotcha fix end-to-end)', async () => {
+    const result = await runGap({
+      homeSettings: { statusLine: { type: 'command', command: 'x' } },
+    });
+    assert.ok(
+      !hasGap(result, /status line/i),
+      `~/.claude/settings.json statusLine must be discovered; got: ${result.findings.map(f => f.title).join(' | ')}`,
+    );
+  });
+});

tests/scanners/optimize-lens-cli.test.mjs

@@ -0,0 +1,102 @@
+/**
+ * optimize-lens-cli tests — payload scoping + candidate identity (M-BUG-11).
+ *
+ * The lens CLI feeds the precision-gate agent. Two correctness invariants it must
+ * hold, both established elsewhere in the codebase but originally missing here:
+ *
+ *   1. SCOPING — plugin-bundled CLAUDE.md (anything under `.claude/plugins/`:
+ *      vendored plugin config + its bundled tests/fixtures + examples, active or
+ *      stale) is NOT the user's authored config. The user can't act on a
+ *      mechanism-fit suggestion against a file a plugin ships. So the lens must
+ *      drop them — the M-BUG-2 `isPluginBundled` rule, applied to the lens.
+ *
+ *   2. IDENTITY — a candidate's `file` must uniquely name a readable file. The
+ *      user-global `~/.claude/CLAUDE.md` and a repo-root `CLAUDE.md` both have
+ *      relPath `CLAUDE.md`; labelling candidates by relPath collides them, and
+ *      the agent's `Read(file)` then resolves the wrong one. Candidates carry an
+ *      absolute path.
+ *
+ * Hermetic: a temp target with a real CLAUDE.md and a nested plugin-bundled one.
+ * `.claude/plugins/` is not in SKIP_DIRS, so the normal walk discovers it —
+ * no ~/.claude / --global needed.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { join, isAbsolute } from 'node:path';
+import { mkdtemp, mkdir, writeFile, rm, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+const execFileP = promisify(execFile);
+const CLI = fileURLToPath(new URL('../../scanners/optimize-lens-cli.mjs', import.meta.url));
+
+/** Build a temp target, run the lens CLI on it, return the parsed payload. */
+async function runLens(files) {
+  const root = await mkdtemp(join(tmpdir(), 'ca-lens-cli-'));
+  try {
+    for (const [rel, content] of Object.entries(files)) {
+      const abs = join(root, rel);
+      await mkdir(join(abs, '..'), { recursive: true });
+      await writeFile(abs, content, 'utf-8');
+    }
+    const out = join(root, 'payload.json');
+    await execFileP('node', [CLI, root, '--output-file', out]);
+    return JSON.parse(await readFile(out, 'utf-8'));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+const REAL = '# Project\n\nNever commit secrets to the repo.\n';
+const PLUGIN = '# Vendored plugin\n\nNever delete the plugin cache directory.\n';
+
+describe('optimize-lens-cli — scoping (M-BUG-11)', () => {
+  it('excludes plugin-bundled CLAUDE.md from candidates', async () => {
+    const payload = await runLens({
+      'CLAUDE.md': REAL,
+      '.claude/plugins/cache/mkt/plug/1.0.0/CLAUDE.md': PLUGIN,
+    });
+    const bundled = payload.candidates.filter(
+      (c) => c.file.includes(`.claude/plugins/`) || c.file.includes(`/plugins/`),
+    );
+    assert.deepEqual(
+      bundled.map((c) => c.file),
+      [],
+      'no candidate should come from a file under .claude/plugins/',
+    );
+  });
+
+  it('still surfaces the user’s real CLAUDE.md', async () => {
+    const payload = await runLens({
+      'CLAUDE.md': REAL,
+      '.claude/plugins/cache/mkt/plug/1.0.0/CLAUDE.md': PLUGIN,
+    });
+    const real = payload.candidates.filter((c) => c.file.endsWith(`${join('', 'CLAUDE.md')}`));
+    assert.ok(real.length >= 1, 'the real CLAUDE.md never-instruction should survive scoping');
+  });
+
+  it('excludes plugin-bundled CLAUDE.md from deterministic findings too', async () => {
+    const procedure =
+      '# Plugin release\n\n' +
+      Array.from({ length: 7 }, (_, i) => `${i + 1}. Do release step ${i + 1} and verify.`).join('\n') +
+      '\n';
+    const payload = await runLens({
+      'CLAUDE.md': REAL,
+      '.claude/plugins/cache/mkt/plug/1.0.0/CLAUDE.md': procedure,
+    });
+    const bundled = (payload.deterministic || []).filter((f) => String(f.file).includes('plugins/'));
+    assert.deepEqual(bundled, [], 'deterministic CA-OPT-001 must not fire on vendored plugin CLAUDE.md');
+  });
+});
+
+describe('optimize-lens-cli — candidate identity (M-BUG-11)', () => {
+  it('labels every candidate with an absolute, unique path', async () => {
+    const payload = await runLens({ 'CLAUDE.md': REAL });
+    assert.ok(payload.candidates.length >= 1, 'expected at least one candidate');
+    for (const c of payload.candidates) {
+      assert.ok(isAbsolute(c.file), `candidate file must be absolute, got: ${c.file}`);
+    }
+  });
+});

tests/scanners/posture-humanizer.test.mjs

@@ -1,6 +1,7 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { resolve, dirname } from 'node:path';
+import { resolve, dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
@@ -141,4 +142,44 @@ describe('posture humanizer wiring (Step 6)', () => {
         'humanized stderr must differ from v5.0.0 verbatim stderr');
     });
   });
+
+  // M-BUG-12: feature-gap.md/posture.md read findings from posture.mjs --output-file
+  // and group on humanizer fields (userActionLanguage etc.). Default-mode output-file
+  // must therefore humanize findings inside the nested scannerEnvelope; --raw stays raw.
+  describe('default mode --output-file (M-BUG-12: humanized findings)', () => {
+    it('writes humanized GAP findings (userActionLanguage defined) to the output file', async () => {
+      const tmp = join(tmpdir(), `ca-posture-outfile-${process.pid}.json`);
+      try {
+        await runPosture(['--output-file', tmp]);
+        const env = JSON.parse(await readFile(tmp, 'utf-8'));
+        const gap = env.scannerEnvelope.scanners.find(s => s.scanner === 'GAP');
+        assert.ok(gap, 'GAP scanner must be present in the output file');
+        assert.ok(gap.findings.length > 0, 'fixture must yield at least one GAP finding');
+        for (const f of gap.findings) {
+          assert.notEqual(f.userActionLanguage, undefined,
+            `${f.id}: default-mode output-file findings must carry userActionLanguage`);
+          assert.notEqual(f.userImpactCategory, undefined,
+            `${f.id}: default-mode output-file findings must carry userImpactCategory`);
+        }
+      } finally {
+        await unlink(tmp).catch(() => {});
+      }
+    });
+
+    it('--raw --output-file keeps v5.0.0 raw finding shape (no humanizer fields)', async () => {
+      const tmp = join(tmpdir(), `ca-posture-outfile-raw-${process.pid}.json`);
+      try {
+        await runPosture(['--raw', '--output-file', tmp]);
+        const env = JSON.parse(await readFile(tmp, 'utf-8'));
+        for (const s of env.scannerEnvelope.scanners) {
+          for (const f of s.findings) {
+            assert.equal(f.userActionLanguage, undefined,
+              `${f.id}: --raw output-file must not carry userActionLanguage`);
+          }
+        }
+      } finally {
+        await unlink(tmp).catch(() => {});
+      }
+    });
+  });
 });

tests/scanners/rules-validator.test.mjs

@@ -200,3 +200,94 @@ describe('RUL — block-sequence-scoped rule is correctly scoped (parser regress
     assert.equal(f.severity, 'low');
   });
 });
+
+describe('RUL — nested-repo rule glob resolves to its own project root (M-BUG-9)', () => {
+  // A rule living in a NESTED repo's .claude/rules/ scopes its paths: pattern
+  // relative to that nested repo's root — NOT relative to the outer scan root.
+  // Before the fix, countGlobMatches globbed against the scan root and
+  // collectProjectFiles' depth>4 cutoff never reached the deep matching files,
+  // so a live rule was wrongly flagged "matches no files / never activates".
+  // (Real-machine surface: ~/.claude/plugins/marketplaces/ktg-privat/.claude/rules/.)
+  let tmpRoot;
+  let result;
+
+  async function writeNestedRepo(scanRoot) {
+    // Nested repo sits 3 dirs below the scan root → its matching files land
+    // past the old depth>4 cutoff when walked from the scan root.
+    const nested = join(scanRoot, 'level1', 'level2', 'nested-repo');
+    await mkdir(join(nested, '.claude', 'rules'), { recursive: true });
+    await mkdir(join(nested, 'plugins', 'app'), { recursive: true });
+    await mkdir(join(nested, 'plugins', 'app', 'hooks'), { recursive: true });
+    // Files that the rule patterns match — relative to the NESTED repo root.
+    await writeFile(join(nested, 'plugins', 'app', 'CLAUDE.md'), '# App\n', 'utf8');
+    await writeFile(join(nested, 'plugins', 'app', 'hooks', 'hooks.json'), '{}\n', 'utf8');
+    // Two rules mirroring the real ktg-privat ones.
+    await writeFile(
+      join(nested, '.claude', 'rules', 'plugin-convention.md'),
+      '---\npaths: "plugins/*/CLAUDE.md"\n---\n\n# Convention\nbody\n',
+      'utf8',
+    );
+    await writeFile(
+      join(nested, '.claude', 'rules', 'hook-format.md'),
+      '---\npaths: "**/hooks/hooks.json"\n---\n\n# Hook format\nbody\n',
+      'utf8',
+    );
+  }
+
+  beforeEach(async () => {
+    resetCounter();
+    tmpRoot = await mkdtemp(join(tmpdir(), 'ca-rul-nested-'));
+    await writeNestedRepo(tmpRoot);
+    const discovery = await discoverConfigFiles(tmpRoot);
+    result = await scan(tmpRoot, discovery);
+  });
+
+  afterEach(async () => {
+    if (tmpRoot) await rm(tmpRoot, { recursive: true, force: true });
+  });
+
+  it('does NOT flag the nested rules as "matches no files"', () => {
+    const dead = result.findings.filter(f => f.title.includes('matches no files'));
+    assert.equal(
+      dead.length,
+      0,
+      `nested-repo rules matched real files but were flagged dead: ${dead.map(f => f.evidence).join(' | ')}`,
+    );
+  });
+});
+
+describe('RUL — user-global rule is not flagged "matches no files" (M-BUG-9 guard)', () => {
+  // A user-global ~/.claude/rules/ rule scopes against whatever project is
+  // active at runtime, not a fixed tree — so "matches 0 files here" is not a
+  // meaningful dead-rule signal and must not be flagged (and must not trigger a
+  // HOME-wide file walk).
+  let tmpHome;
+  let savedHome;
+  let result;
+
+  beforeEach(async () => {
+    resetCounter();
+    tmpHome = await mkdtemp(join(tmpdir(), 'ca-rul-home-'));
+    savedHome = process.env.HOME;
+    process.env.HOME = tmpHome;
+    await mkdir(join(tmpHome, '.claude', 'rules'), { recursive: true });
+    await writeFile(
+      join(tmpHome, '.claude', 'rules', 'global.md'),
+      '---\npaths: "src/**/*.rs"\n---\n\n# Global rust rule\nbody\n',
+      'utf8',
+    );
+    // Scan from HOME so the rule is discovered AND its derived project root === HOME.
+    const discovery = await discoverConfigFiles(tmpHome);
+    result = await scan(tmpHome, discovery);
+  });
+
+  afterEach(async () => {
+    process.env.HOME = savedHome;
+    if (tmpHome) await rm(tmpHome, { recursive: true, force: true });
+  });
+
+  it('does NOT flag a user-global rule as "matches no files"', () => {
+    const dead = result.findings.filter(f => f.title.includes('matches no files'));
+    assert.equal(dead.length, 0, `user-global rule wrongly flagged dead: ${dead.map(f => f.evidence).join(' | ')}`);
+  });
+});

tests/scanners/settings-validator.test.mjs

@@ -47,10 +47,12 @@ describe('SET scanner — broken project', () => {
     result = await scan(resolve(FIXTURES, 'broken-project'), discovery);
   });
 
-  it('detects unknown settings key', () => {
-    // CA-SET-001 in broken-project, evidence='unknownKey123'.
+  it('does NOT flag an arbitrary unknown key (CC schema is passthrough)', () => {
+    // M-BUG-10: "unknownKey123" is not close to any known key, so it is a
+    // valid forward-compatible / passthrough key — NOT a typo. Claude Code
+    // forwards unrecognized keys unchanged, so flagging it is a false positive.
     const found = result.findings.some(f => f.scanner === 'SET' && /unknownKey123/.test(f.evidence || ''));
-    assert.ok(found, 'Should detect unknownKey123');
+    assert.ok(!found, 'unknownKey123 is far from every known key → must not be flagged');
   });
 
   it('detects deprecated key (includeCoAuthoredBy)', () => {
@@ -192,6 +194,63 @@ describe('SET scanner — CC 2.1.114→181 valid keys (Batch 1 false-positive fi
   });
 });
 
+describe('SET scanner — unknown-key typo gate (M-BUG-10)', () => {
+  // The CC settings schema is passthrough: it forwards unrecognized keys
+  // unchanged rather than rejecting them, so an arbitrary unknown key is
+  // valid/forward-compatible and must NOT be flagged. The only real risk is a
+  // TYPO of a real key (the intended setting silently has no effect), so the
+  // scanner flags ONLY unknown keys that closely match a known key.
+  // Path-guard blocks committing settings.json fixtures → materialize a temp one.
+  let tmpRoot;
+  let result;
+  const TYPO_TITLE = 'Possible typo in settings key';
+
+  beforeEach(async () => {
+    resetCounter();
+    tmpRoot = await mkdtemp(join(tmpdir(), 'ca-set-typo-'));
+    await mkdir(join(tmpRoot, '.claude'), { recursive: true });
+    const settings = {
+      $schema: 'https://json.schemastore.org/claude-code-settings.json',
+      permisions: { deny: ['Read(./.env)'] },   // TYPO of "permissions" (edit distance 1)
+      someNewKey2027: true,                      // forward-compat / passthrough — far from every known key
+      permissions: { deny: ['Read(./.env)'], allow: ['Bash(npm run *)'] },
+    };
+    await writeFile(
+      join(tmpRoot, '.claude', 'settings.json'),
+      JSON.stringify(settings, null, 2) + '\n',
+      'utf8',
+    );
+    const discovery = await discoverConfigFiles(tmpRoot);
+    result = await scan(tmpRoot, discovery);
+  });
+
+  afterEach(async () => {
+    if (tmpRoot) await rm(tmpRoot, { recursive: true, force: true });
+  });
+
+  it('flags a likely typo ("permisions") and suggests the nearest known key', () => {
+    const typo = result.findings.find(f => f.scanner === 'SET' && f.evidence === 'permisions');
+    assert.ok(typo, `expected a typo finding for "permisions"; got: ${result.findings.map(f => `${f.title}:${f.evidence || ''}`).join(' | ')}`);
+    assert.equal(typo.title, TYPO_TITLE);
+    assert.match(typo.recommendation, /permissions/, 'recommendation suggests the nearest known key');
+  });
+
+  it('marks the typo finding as low severity (passthrough → not a hard error)', () => {
+    const typo = result.findings.find(f => f.scanner === 'SET' && f.evidence === 'permisions');
+    assert.equal(typo.severity, 'low');
+  });
+
+  it('does NOT flag a forward-compatible key far from any known key', () => {
+    const fwd = result.findings.find(f => f.scanner === 'SET' && f.evidence === 'someNewKey2027');
+    assert.equal(fwd, undefined, 'someNewKey2027 is far from every known key → passthrough, not flagged');
+  });
+
+  it('emits exactly one typo finding for this file', () => {
+    const typos = result.findings.filter(f => f.scanner === 'SET' && f.title === TYPO_TITLE);
+    assert.equal(typos.length, 1, `expected exactly one typo finding; got: ${typos.map(f => f.evidence).join(', ')}`);
+  });
+});
+
 describe('SET scanner — empty project', () => {
   let result;
   beforeEach(async () => {

tests/scanners/token-hotspots.test.mjs

@@ -1,7 +1,9 @@
 import { describe, it, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { resolve } from 'node:path';
+import { resolve, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 import { resetCounter } from '../../scanners/lib/output.mjs';
 import { scan } from '../../scanners/token-hotspots.mjs';
 import { discoverConfigFiles } from '../../scanners/lib/file-discovery.mjs';
@@ -405,3 +407,36 @@ describe('TOK scanner — H stale plugin-cache versions (v5.9 B3)', () => {
     assert.ok(!result.findings.some(x => /stale plugin-cache/i.test(x.title || '')));
   });
 });
+
+describe('TOK scanner — CLAUDE.md HTML-comment token discount (M-BUG-6)', () => {
+  it('estimates a comment-padded CLAUDE.md below its raw byte heuristic', async () => {
+    const dir = join(
+      tmpdir(),
+      `config-audit-tok-mbug6-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    );
+    await mkdir(dir, { recursive: true });
+    try {
+      // Big block-level comment CC strips before injection — the hotspot's
+      // estimated_tokens must reflect the stripped size, not the raw on-disk byte
+      // count. (Hotspot output exposes `path` + `estimated_tokens`, not `size`.)
+      const comment = `<!-- ${'maintainer note '.repeat(80)} -->`;
+      const content = `# Root\n\n${comment}\n\nReal instruction body.\n`;
+      const rawBytes = Buffer.byteLength(content, 'utf8');
+      await writeFile(join(dir, 'CLAUDE.md'), content);
+      resetCounter();
+      const discovery = await discoverConfigFiles(dir);
+      const result = await withHermeticHome(() => scan(dir, discovery));
+      const hs = result.hotspots.find(
+        h => typeof h.path === 'string' && h.path.endsWith('CLAUDE.md'),
+      );
+      assert.ok(hs, 'expected a CLAUDE.md hotspot for the fixture');
+      assert.ok(
+        hs.estimated_tokens < Math.ceil(rawBytes / 4),
+        `expected discounted tokens (${hs.estimated_tokens}) below raw heuristic ` +
+          `(${Math.ceil(rawBytes / 4)}) for ${rawBytes} raw bytes`,
+      );
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

tests/snapshots/default-output/scan-orchestrator.json

@@ -165,7 +165,7 @@
             "id": "CA-GAP-003",
             "scanner": "GAP",
             "severity": "low",
-            "title": "Your rules all load on every conversation",
+            "title": "You haven't set up path-scoped rules yet",
             "description": "Path-scoped rules only load when you're working with files that match — keeps each conversation focused.",
             "file": null,
             "line": null,
@@ -309,7 +309,7 @@
             "id": "CA-GAP-012",
             "scanner": "GAP",
             "severity": "info",
-            "title": "Your subagents share Claude's main work folder",
+            "title": "You haven't set up subagent isolation yet",
             "description": "Isolated subagents run in their own copy of the repo so they can't accidentally disturb your main work.",
             "file": null,
             "line": null,