fc8808d6e4
- Plugin README: add "What's New in v5.1.0" section with humanizer overview, before/after example, plain-language vocabulary table, --raw flag docs. Bump version badge 5.0.0 → 5.1.0. Add Version History row. - Plugin CLAUDE.md: add humanizer.mjs + humanizer-data.mjs to Scanner Lib table. Add "Plain-Language Output (v5.1.0)" section documenting output modes, vocabularies, and Wave 5 lessons. Bump test count 635 → 792 across 52 test files. - Marketplace root README: bump config-audit entry 5.0.0 → 5.1.0, update one-line description to mention plain-language UX, add bullet for the v5.1.0 humanizer, bump test count 635+ → 792+. Test-normalizer hardening (consequence of growing CLAUDE.md): walkClaudeMdCascade walks upward from the marketplace-medium fixture into this plugin's own CLAUDE.md, so any docs edit ripples into `scanners[*].activeConfig.claudeMdEstimatedTokens`. The v5.0.0 byte-stability contract is about scanner internals being unchanged, not ancestor input content being frozen. Normalizers in json-backcompat, raw-backcompat, posture-humanizer, scan-orchestrator-humanizer, and snapshot-default-output now strip claudeMdEstimatedTokens to <ANCESTOR_DERIVED>. The default-output snapshot for scan-orchestrator was re-seeded via UPDATE_SNAPSHOT=1 (intent: Wave 6 docs additions; humanizer prose unchanged). Verify: - grep -E "5\.1\.0|v5\.1\.0" README.md CLAUDE.md ../../README.md | wc -l = 12 - node --test 'tests/**/*.test.mjs' = 792/792 pass - self-audit configGrade A (97), pluginGrade A (100), readmeCheck.passed true
227 lines
13 KiB
Markdown
227 lines
13 KiB
Markdown
# Config-Audit Plugin
|
||
|
||
Claude Code Configuration Intelligence — know if your configuration is correct, find what could improve it, fix it automatically.
|
||
|
||
## What this plugin does
|
||
|
||
Analyzes and optimizes Claude Code configuration across three pillars:
|
||
- **Health** — Deterministic scanners verify correctness, consistency, and completeness
|
||
- **Opportunities** — Context-aware recommendations for features that could benefit your project
|
||
- **Action** — Auto-fix with backup/rollback
|
||
|
||
## Commands
|
||
|
||
### Core (just run `/config-audit` to get started)
|
||
|
||
| Command | Description |
|
||
|---------|-------------|
|
||
| `/config-audit` | Full audit with auto-scope detection (no setup needed) |
|
||
| `/config-audit posture` | Quick health scorecard (A-F grades, 10 quality areas incl. Token Efficiency, Plugin Hygiene) |
|
||
| `/config-audit tokens` | Opus-4.7-aware token hotspots (6 patterns: cache-breaking, redundant perms, deep imports, oversized cascade, bloated SKILL.md desc, MCP tool-schema budget) — optional `--accurate-tokens` API calibration, `--with-telemetry-recipe` cache-hit recipe pointer |
|
||
| `/config-audit manifest` | Ranked table of every system-prompt token source (CLAUDE.md, plugins, skills, MCP, hooks) sorted by estimated tokens |
|
||
| `/config-audit feature-gap` | Context-aware feature recommendations grouped by impact |
|
||
| `/config-audit fix` | Auto-fix deterministic issues with backup + verification |
|
||
| `/config-audit rollback` | Restore configuration from backup |
|
||
| `/config-audit plan` | Create action plan from audit findings |
|
||
| `/config-audit implement` | Execute plan with backups + auto-verify |
|
||
| `/config-audit help` | Show all commands |
|
||
|
||
### Additional
|
||
|
||
| Command | Description |
|
||
|---------|-------------|
|
||
| `/config-audit drift` | Compare current config against saved baseline |
|
||
| `/config-audit plugin-health` | Audit plugin structure, frontmatter, cross-plugin coherence |
|
||
| `/config-audit whats-active` | Read-only inventory of plugins, skills, MCP, hooks, CLAUDE.md active for a repo (with token estimates) |
|
||
| `/config-audit discover` | Run discovery phase only |
|
||
| `/config-audit analyze` | Run analysis phase only |
|
||
| `/config-audit interview` | Gather user preferences (opt-in) |
|
||
| `/config-audit status` | Show current session state |
|
||
| `/config-audit cleanup` | Clean up old sessions |
|
||
|
||
## Agents
|
||
|
||
| Agent | Role | Model | Color | Tools |
|
||
|-------|------|-------|-------|-------|
|
||
| scanner-agent | Find config files | sonnet | cyan | Read, Glob, Grep, Write |
|
||
| analyzer-agent | Generate report | sonnet | blue | Read, Glob, Grep, Write |
|
||
| planner-agent | Create action plan | opus | yellow | Read, Glob, Write |
|
||
| implementer-agent | Execute changes | sonnet | magenta | Read, Write, Edit, Bash, Glob |
|
||
| verifier-agent | Verify results | sonnet | purple | Read, Glob, Grep |
|
||
| feature-gap-agent | Context-aware feature recommendations | opus | green | Read, Glob, Grep, Write |
|
||
|
||
## Deterministic Scanners
|
||
|
||
Node.js scanners (zero external dependencies), run via `node scanners/scan-orchestrator.mjs <path>`.
|
||
Posture CLI: `node scanners/posture.mjs <path> [--json] [--global] [--full-machine] [--output-file path]`.
|
||
Scanner CLI: `node scanners/scan-orchestrator.mjs <path> [--global] [--full-machine] [--no-suppress]`.
|
||
|
||
| Scanner | Prefix | Detects |
|
||
|---------|--------|---------|
|
||
| `claude-md-linter.mjs` | CML | Structure, length, sections, @imports, duplicates, TODOs |
|
||
| `settings-validator.mjs` | SET | Schema, unknown/deprecated keys, type mismatches, permissions |
|
||
| `hook-validator.mjs` | HKV | Format, script existence, event validity, timeouts |
|
||
| `rules-validator.mjs` | RUL | Glob matching, orphan rules, deprecated fields, unscoped rules |
|
||
| `mcp-config-validator.mjs` | MCP | Server types, trust levels, env vars, unknown fields |
|
||
| `import-resolver.mjs` | IMP | Broken @imports, circular refs, deep chains, tilde paths |
|
||
| `conflict-detector.mjs` | CNF | Settings conflicts, permission contradictions, hook duplicates |
|
||
| `feature-gap-scanner.mjs` | GAP | 25 feature checks across 4 tiers — shown as opportunities, not grades |
|
||
| `token-hotspots.mjs` | TOK | Cache-breaking volatile content, redundant tool permissions, deep import chains, oversized cascade, bloated SKILL.md descriptions, MCP tool-schema budget (Opus 4.7 patterns) |
|
||
| `cache-prefix-scanner.mjs` | CPS | Volatile content in lines 31–150 of CLAUDE.md cascade (beyond Pattern A's top-30 window) |
|
||
| `disabled-in-schema-scanner.mjs` | DIS | Tools listed in BOTH `permissions.deny` AND `permissions.allow` — deny wins, allow entries are dead config |
|
||
| `collision-scanner.mjs` | COL | Cross-plugin skill name collisions (low); user-vs-plugin overlaps (medium); `details.namespaces` payload |
|
||
|
||
### Scanner Lib (`scanners/lib/`)
|
||
|
||
| Module | Purpose |
|
||
|--------|---------|
|
||
| `severity.mjs` | Severity constants, risk scoring, verdict logic, `WEIGHTS` named export (v5 F3) |
|
||
| `output.mjs` | Finding objects (CA-XXX-NNN format), scanner results, envelope, optional `details` payload (v5 N6) |
|
||
| `file-discovery.mjs` | Config file discovery: single-path, multi-path (`discoverConfigFilesMulti`), full-machine (`discoverFullMachinePaths`) |
|
||
| `yaml-parser.mjs` | Frontmatter parsing, JSON parsing, @import/section extraction |
|
||
| `string-utils.mjs` | Line counting, truncation, similarity, key extraction |
|
||
| `scoring.mjs` | Severity-weighted `scoreByArea` (v5 F3), health scorecard, dedup-by-area (v5 N3), `scoringVersion: 'v5'` |
|
||
| `backup.mjs` | Backup creation, manifest parsing, checksum verification |
|
||
| `diff-engine.mjs` | Drift diffing: diffEnvelopes(), formatDiffReport() |
|
||
| `baseline.mjs` | Baseline save/load/list/delete for drift detection |
|
||
| `report-generator.mjs` | Unified markdown reports: posture, drift, plugin health |
|
||
| `suppression.mjs` | .config-audit-ignore parsing, finding suppression, audit trail |
|
||
| `active-config-reader.mjs` | Read-only inventory: readActiveConfig(), detectGitRoot(), walkClaudeMdCascade(), readClaudeJsonProjectSlice() (longest-prefix match), enumeratePlugins(), enumerateSkills(), readActiveHooks(), readActiveMcpServers() (with cache → package.json tool-count fallback), estimateTokens() (v5: `'mcp'` kind = 500 + toolCount × 200) |
|
||
| `tokenizer-api.mjs` | Anthropic `count_tokens` wrapper for `--accurate-tokens` (v5 N5); 5s AbortController timeout, exponential 429 backoff, key masking |
|
||
| `humanizer.mjs` | Plain-language output translator (v5.1.0): `humanizeFinding`, `humanizeFindings`, `humanizeEnvelope`, `computeRelevanceContext`. Pure functions; never mutate inputs. Adds `userImpactCategory`, `userActionLanguage`, `relevanceContext` fields and replaces title/description/recommendation when a translation exists. Bypassed by `--raw` and `--json` paths. |
|
||
| `humanizer-data.mjs` | TRANSLATIONS table for 13 scanner prefixes (CML/SET/HKV/RUL/MCP/IMP/CNF/COL/TOK/CPS/DIS/GAP/PLH). Three-step lookup: exact title → regex pattern → `_default` → fall through to original |
|
||
|
||
### Action Engines (`scanners/`)
|
||
|
||
| Module | Purpose |
|
||
|--------|---------|
|
||
| `fix-engine.mjs` | planFixes(), applyFixes(), verifyFixes() — 9 fix types |
|
||
| `rollback-engine.mjs` | listBackups(), restoreBackup(), deleteBackup() |
|
||
| `fix-cli.mjs` | CLI: `node fix-cli.mjs <path> [--apply] [--json] [--global]` |
|
||
| `drift-cli.mjs` | CLI: `node drift-cli.mjs <path> [--save] [--baseline name] [--json]` |
|
||
| `whats-active.mjs` | CLI: `node whats-active.mjs <path> [--json] [--verbose] [--suggest-disables]` — read-only active-config inventory |
|
||
| `token-hotspots-cli.mjs` | CLI: `node token-hotspots-cli.mjs <path> [--json] [--global] [--output-file path] [--accurate-tokens] [--with-telemetry-recipe]` — Opus-4.7 token hotspots ranking with optional API calibration |
|
||
| `manifest.mjs` | CLI: `node manifest.mjs <path> [--json]` — ranked system-prompt token-source table (v5 N2) |
|
||
|
||
### Standalone Scanner
|
||
|
||
| Module | Prefix | Purpose |
|
||
|--------|--------|---------|
|
||
| `plugin-health-scanner.mjs` | PLH | Plugin structure, frontmatter, cross-plugin conflicts (runs independently) |
|
||
| `self-audit.mjs` | — | Runs all scanners + plugin health on this plugin itself |
|
||
|
||
## Knowledge Base (`knowledge/`)
|
||
|
||
| File | Content |
|
||
|------|---------|
|
||
| `claude-code-capabilities.md` | Feature register: 18 config surfaces, Anthropic guidance, relevance table |
|
||
| `configuration-best-practices.md` | Per-layer best practices (v5: Opus 4.7 cache-stability guidance replaces Sonnet-era 200-line rule) |
|
||
| `anti-patterns.md` | Common mistakes mapped to scanner IDs |
|
||
| `hook-events-reference.md` | All 26 hook events with details |
|
||
| `feature-evolution.md` | Feature timeline for staleness detection |
|
||
| `gap-closure-templates.md` | Config-specific templates for closing gaps |
|
||
| `opus-4.7-patterns.md` | Token-cost dynamics for Opus 4.7 era — patterns powering the TOK scanner |
|
||
| `cache-telemetry-recipe.md` | Manual `jq` recipe for verifying prompt-cache hit rate from session transcripts (v5 M7) |
|
||
|
||
## 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 |
|
||
|
||
## Plain-Language Output (v5.1.0)
|
||
|
||
Default output of all 18 commands routes through `humanizeEnvelope` from `lib/humanizer.mjs`. Findings are decorated with three additive fields and may have title/description/recommendation replaced when a translation exists.
|
||
|
||
### Output modes
|
||
|
||
| Flag | Behavior |
|
||
|------|----------|
|
||
| (default, no flag) | Plain-language: humanizer applied, findings group by user-impact, titles lead with prose. Self-audit terminal render also humanized. |
|
||
| `--raw` | Byte-stable v5.0.0 verbatim — humanizer bypassed, technical IDs and severity-only labels. For tooling that scrapes stderr from v5.0.0. |
|
||
| `--json` | Unchanged from v5.0.0 — humanizer bypassed, byte-stable JSON envelope. Always preferred for programmatic consumption over `--raw`. |
|
||
| `--output-file <path>` | Writes raw v5.0.0-shape JSON (humanizer bypassed). Posture-specific. |
|
||
|
||
`--raw` is threaded through every CLI: `posture.mjs`, `scan-orchestrator.mjs`, `token-hotspots-cli.mjs`, `manifest.mjs`, `whats-active.mjs`, `fix-cli.mjs`, `drift-cli.mjs`, `self-audit.mjs`.
|
||
|
||
### Vocabularies
|
||
|
||
User-impact category (added to each finding as `userImpactCategory`, derived from scanner prefix):
|
||
|
||
| Label | Scanners |
|
||
|-------|----------|
|
||
| Configuration mistake | CML, SET, HKV, RUL, MCP, IMP, PLH |
|
||
| Conflict | CNF, COL |
|
||
| Wasted tokens | TOK, CPS |
|
||
| Dead config | DIS |
|
||
| Missed opportunity | GAP |
|
||
|
||
Action language (added to each finding as `userActionLanguage`, derived from severity):
|
||
|
||
| Severity | Phrase |
|
||
|----------|--------|
|
||
| critical | Fix this now |
|
||
| high | Fix soon |
|
||
| medium | Fix when convenient |
|
||
| low | Optional cleanup |
|
||
| info | FYI |
|
||
|
||
Relevance context (added to each finding as `relevanceContext`, computed from finding's file path):
|
||
|
||
| Value | When |
|
||
|-------|------|
|
||
| `test-fixture-no-impact` | Path contains `/tests/fixtures/` or `/test/fixtures/` |
|
||
| `affects-this-machine-only` | Basename matches `*.local.*` (e.g., `settings.local.json`) |
|
||
| `affects-everyone` | Default — assumed shared/committed config |
|
||
|
||
### Wave 5 lessons
|
||
|
||
- Posture's stderr scorecard is rendered prose-side and is not part of the JSON envelope; `humanized.areas[].titleHumanized` referenced by command templates lives only in the prose render.
|
||
- Posture's `--output-file` writes raw v5.0.0-shape JSON because `posture.mjs` does not call `humanizeEnvelope`. If session-files should later be humanized, posture needs its own humanize pass — out of v5.1.0 scope.
|
||
- The default-output snapshot at `tests/snapshots/default-output/posture.json` is frozen — change requires `UPDATE_SNAPSHOT=1` plus intent confirmation.
|
||
|
||
## Suppressions
|
||
|
||
Create `.config-audit-ignore` at project root to suppress known findings:
|
||
```
|
||
CA-SET-003 # Exact ID
|
||
CA-GAP-* # Glob pattern (all GAP findings)
|
||
```
|
||
Suppressed findings tracked in envelope's `suppressed_findings` for audit trail. Disable with `--no-suppress`.
|
||
|
||
## Architecture
|
||
|
||
### Workflow
|
||
```
|
||
/config-audit → discover + analyze (auto) → plan → implement → verify
|
||
```
|
||
Default: auto-detects scope from git context. Override with `/config-audit full|repo|home|current`. Delta mode: `--delta` (incremental).
|
||
|
||
### Session Directory
|
||
```
|
||
~/.claude/config-audit/sessions/{session-id}/
|
||
├── scope.yaml, discovery.json, state.yaml
|
||
├── findings/, analysis-report.md, action-plan.md
|
||
├── backups/, implementation-log.md
|
||
└── interview.md (if interview run)
|
||
```
|
||
|
||
### Finding ID Format
|
||
`CA-{SCANNER}-{NNN}` — e.g. `CA-CML-001`, `CA-SET-003`, `CA-HKV-002`, `CA-RUL-005`, `CA-TOK-005`, `CA-CPS-001`, `CA-DIS-001`, `CA-COL-001`
|
||
|
||
## Testing
|
||
|
||
```bash
|
||
node --test 'tests/**/*.test.mjs'
|
||
```
|
||
|
||
792 tests across 52 test files (15 lib + 28 scanner + 1 hook + 1 agent + 3 commands + 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`.
|
||
|
||
## 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
|