open/config-audit
1
0
Fork 0
Code Issues Pull requests Releases Activity
config-audit/CLAUDE.md
Kjell Tore Guttormsen e9921d3c9d feat(optimize): add --subtract, the subtraction axis, behind a deterministic floor 
Every command so far asked an addition question — what to add, what to move,
what it costs. Nothing asked what is no longer earning its always-loaded rent.
This adds that axis as a fourth lensCheck on the existing hybrid motor rather
than a new scanner or a 22nd command: the measured payoff (~18% of one file)
justifies a mode, not machinery.

It is the only lens that proposes REMOVING config, so it carries a guarantee
the others don't need: a load-bearing block is never a candidate. Precision is
asymmetric — a missed dead line costs a few tokens per turn, a deleted one
costs a wrong remote or a broken script — so the floor is decided in code
(lib/floor-exclusion.mjs) before the opus judge sees anything, never in prose.

Granularity is the leaf block, with two structural exceptions: a paragraph
ending in ':' merges with the list it introduces, and an ordered list is a
contract whose steps inherit floor from any sibling. Unordered lists
deliberately do not inherit — a load-bearing bullet and a disposable one
routinely share a list, and container-reasoning is the error the hand-built
ground truth exists to catch.

Verified against that ground truth (built before any classifier existed), with
the comparison machine-checked rather than read by eye: zero load-bearing
blocks proposed, 11/18 deletable groups surfaced, ~756 tok ~ 18% of a ~4300
token file — inside the pre-registered band. The first run found five floor
violations the synthesized fixture missed; each got a structural rule and a
fixture shape so it cannot regress.

Three real bugs the dogfood run exposed, all now covered:
- JS \b is ASCII-only, so /\bunngå\b/ never matches — every Norwegian keyword
  ending in æ/ø/å was silently dead.
- A bare word/word is not a path; "pros/cons" vetoed the largest deletable
  block until PATH_RE was tightened to rooted paths and globs.
- "Mid-sentence" must key on a preceding lowercase letter; the loose version
  read **bold labels:** and quoted openers as entities, costing 4 of 11 groups.

BP-SUB-001 is grounded entirely in the Anthropic steering blog already cited by
BP-MECH-001..004 and asserts nothing from the talk that motivated the feature —
no "80%", no ablation figure.

Suite 1365 -> 1382/0. Frozen v5.0.0 snapshots untouched; plain optimize output
byte-identical on identical input (--subtract adds keys only when passed).
knowledge-refresh-cli's reference date moved to 2026-08-01: its premise that
every seed entry was verified 2026-06-20 expired when BP-SUB-001 got a genuine
verification date, and backdating the entry to fit the test would have been a
lie about when its source was checked.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RW2haJXbxZpKivKHseSXNh
2026-07-31 16:24:51 +02:00

6.9 KiB
Raw Blame History

Config-Audit Plugin

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

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

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

Command Description
/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. --subtract adds the subtraction axis (what no longer earns its always-loaded rent, BP-SUB-001) — opt-in, proposes only
/config-audit fix Auto-fix deterministic issues with backup + verification
/config-audit rollback Restore configuration from backup
/config-audit plan Create action plan from findings
/config-audit implement Execute plan with backups + auto-verify
/config-audit help Show all commands

Additional

Command Description
/config-audit drift Compare current config against saved baseline
/config-audit plugin-health Audit plugin structure, frontmatter, cross-plugin coherence
/config-audit whats-active Read-only inventory of 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)
/config-audit status Show current session state
/config-audit cleanup Clean up old sessions

Agents

Agent Role Model Color Tools
scanner-agent Find config files sonnet cyan Read, Glob, Grep, Write
analyzer-agent Generate report sonnet blue Read, Glob, Grep, Write
planner-agent Create action plan opus yellow Read, Glob, Write
implementer-agent Execute changes sonnet magenta Read, Write, Edit, Bash, Glob
verifier-agent Verify results sonnet purple Read, Glob, Grep
feature-gap-agent 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 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)

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

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 — 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. 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).

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

Subtraction floor (invariant). optimize --subtract is the only lens that proposes removing config, so scanners/lib/floor-exclusion.mjs runs as a deterministic pre-step before the judge — a load-bearing block is never a candidate, and that guarantee must not be moved into the agent prompt. Two rules follow from it: (1) staleness is not a deletion signal — an outdated version pin inside a floor block is a drift/CA-CML dead-reference concern; (2) tier 2 ≠ tier 3 — a compensatory block that keeps earning its place returns, and reporting it as dead weight is wrong even when the label matches. Norwegian keywords need the Unicode boundaries in subtraction-prefilter.mjs; JS \b is ASCII-only, so /\bunngå\b/ silently never matches.

Testing

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

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)
  • Plugin CLAUDE.md files in node_modules should be excluded via scope