docs(config-audit): straggler sweep for v5.0.0 — sync all badge counts
Reconcile README/CLAUDE.md/commands/agents to filesystem truth ahead of v5.0.0 release. Self-audit --check-readme now passes (counts: scanners 12, commands 18, tests 635, knowledge 8, agents 6, hooks 4). Self-audit (scanners/self-audit.mjs): - Exclude plugin-health-scanner.mjs from countScannerShape (it is a "standalone" scanner per README/CLAUDE.md taxonomy; orchestrated scanners stay at 12) - countTestCases: spawn `node --test` and parse the `tests N` line so the badge reflects test cases (635), not test files (36). countTestFiles kept as fallback when subprocess fails. README.md: - Badges: scanners 9→12, commands 17→18, tests 543→635 - Body counts updated: 8 quality scanners → 12 deterministic scanners; 8 quality areas → 10 (incl. Plugin Hygiene from N6); 9 Node.js scanners → 12 - Scanner table extended with CPS / DIS / COL rows; TOK row reflects the v5 Pattern E/F/N1 expansion (sonnet-era removed) - CLI table adds manifest, whats-active, --accurate-tokens, --with-telemetry-recipe - Knowledge table adds opus-4.7-patterns.md and cache-telemetry-recipe.md - Scanner Lib table notes WEIGHTS export, severity-weighted scoring, tokenizer-api - Action Engines table adds manifest.mjs, whats-active.mjs, token-hotspots-cli.mjs - Test count text 486→635, file count 27→36 (12 lib + 23 scanner + 1 hook) - Tokens command: 4-pattern phrasing → 6 patterns + --accurate-tokens - Adds /config-audit manifest and /config-audit whats-active to command tables CLAUDE.md: - Posture row: 8 → 10 quality areas - Tokens row: 4 patterns (incl. sonnet-era) → 6 patterns + --accurate-tokens - Adds /config-audit manifest entry - Scanner table: TOK description rewritten; CPS, DIS, COL rows added - Scanner Lib table: tokenizer-api.mjs added; v5 annotations on severity, output, scoring, active-config-reader - Action Engines table: manifest.mjs added; token-hotspots-cli.mjs flags expanded - Knowledge table: cache-telemetry-recipe.md added; configuration-best-practices notes Opus-4.7 cache-stability rewrite - Finding ID examples extended with CA-TOK-005, CA-CPS-001, CA-DIS-001, CA-COL-001 - Test count text 543→635, file count 31→36 commands/help.md: tokens/manifest added to Core commands/posture.md: 8 → 10 quality areas commands/config-audit.md: argument-hint adds tokens/manifest; router adds tokens and manifest; "Running 8 configuration scanners" → 12 agents/feature-gap-agent.md: 8 → 10 quality areas No production code paths changed beyond self-audit's badge-counting heuristic. All 635 tests still green. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen
parent
17af3d55f6
commit
5bf500e1a8
7 changed files with 95 additions and 35 deletions
|
|
@ -8,14 +8,14 @@
|
|||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
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. 8 quality scanners for correctness, context-aware feature recommendations, auto-fix with backup/rollback, plus an Opus-4.7-aware Token Hotspots scanner. Zero external dependencies.
|
||||
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. 12 deterministic scanners across 10 quality areas, context-aware feature recommendations, auto-fix with backup/rollback, an Opus-4.7-aware Token Hotspots scanner with optional API-calibrated `--accurate-tokens` mode, plus cache-prefix stability, dead-tool, and cross-plugin collision detection. Zero external dependencies.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -50,7 +50,7 @@ Claude Code reads instructions from at least 7 different file types across multi
|
|||
|
||||
This plugin provides three layers of configuration intelligence:
|
||||
|
||||
- **Health** — 8 deterministic scanners verify correctness across every configuration file, catching broken imports, deprecated settings, conflicting rules, format errors, permission contradictions, and Opus-4.7-era token waste
|
||||
- **Health** — 12 deterministic scanners verify correctness across every configuration file, catching broken imports, deprecated settings, conflicting rules, format errors, permission contradictions, Opus-4.7-era token waste, cache-prefix instability, dead tool grants, and cross-plugin skill collisions
|
||||
- **Opportunities** — context-aware recommendations for Claude Code features that could benefit your specific project, backed by Anthropic's official guidance
|
||||
- **Action** — auto-fix with mandatory backups, syntax validation, rollback support, and a human-in-the-loop workflow for anything non-trivial
|
||||
|
||||
|
|
@ -248,8 +248,9 @@ Your team configuration changes over time. Track it:
|
|||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/config-audit` | Full audit with auto-scope detection (no setup needed) |
|
||||
| `/config-audit posture` | Quick health scorecard: A-F grades across 8 quality areas (incl. Token Efficiency) |
|
||||
| `/config-audit tokens` | Opus-4.7-aware token hotspots — ranked by estimated waste, with 4-pattern findings |
|
||||
| `/config-audit posture` | Quick health scorecard: A-F grades across 10 quality areas (incl. Token Efficiency, Plugin Hygiene) |
|
||||
| `/config-audit tokens` | Opus-4.7-aware token hotspots — ranked by estimated waste; 6 patterns + optional `--accurate-tokens` API calibration |
|
||||
| `/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 a previous backup |
|
||||
|
|
@ -263,6 +264,7 @@ Your team configuration changes over time. Track it:
|
|||
|---------|-------------|
|
||||
| `/config-audit drift` | Compare current config against a 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` | Set preferences for action plan _(optional)_ |
|
||||
|
|
@ -277,7 +279,7 @@ By default, `/config-audit` auto-detects scope from your git context. Override w
|
|||
|
||||
## Deterministic Scanners
|
||||
|
||||
9 Node.js scanners that perform structural analysis an LLM cannot reliably do: schema validation, circular reference detection, import resolution, conflict detection across scopes, and Opus-4.7-aware token-cost analysis. Zero external dependencies.
|
||||
12 Node.js scanners that perform structural analysis an LLM cannot reliably do: schema validation, circular reference detection, import resolution, conflict detection across scopes, Opus-4.7-aware token-cost analysis, cache-prefix stability, dead-tool detection, and cross-plugin skill collisions. Plus a standalone plugin-health scanner. Zero external dependencies.
|
||||
|
||||
**Why deterministic?** LLMs are powerful at understanding intent and context. But they cannot reliably validate JSON schemas, detect circular `@import` chains, or catch that your global `settings.json` contradicts your project-level one. These scanners fill that gap — fast, repeatable, and zero false positives on structural issues.
|
||||
|
||||
|
|
@ -291,7 +293,10 @@ By default, `/config-audit` auto-detects scope from your git context. Override w
|
|||
| `import-resolver.mjs` | IMP | Broken @imports, circular references, deep chains, tilde path issues |
|
||||
| `conflict-detector.mjs` | CNF | Settings contradictions across scopes, permission conflicts, hook duplicates |
|
||||
| `feature-gap-scanner.mjs` | GAP | 25 feature checks — shown as opportunities, not grades |
|
||||
| `token-hotspots.mjs` | TOK | Cache-breaking volatile content, redundant tool permissions, deep import chains, sonnet-era setups |
|
||||
| `token-hotspots.mjs` | TOK | Cache-breaking volatile content, redundant tool permissions, deep import chains, oversized cascades, bloated skill descriptions, MCP tool-schema budget |
|
||||
| `cache-prefix-scanner.mjs` | CPS | Volatile content in lines 31–150 of the CLAUDE.md cascade — beyond the cache-prefix window but still re-loaded every turn |
|
||||
| `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; user-vs-plugin overlaps |
|
||||
|
||||
### CLI Tools
|
||||
|
||||
|
|
@ -302,8 +307,10 @@ All tools work standalone — no Claude Code session needed:
|
|||
| **Posture** | `node scanners/posture.mjs <path> [--json] [--global] [--full-machine] [--output-file path]` |
|
||||
| **Fix** | `node scanners/fix-cli.mjs <path> [--apply] [--json] [--global]` |
|
||||
| **Drift** | `node scanners/drift-cli.mjs <path> [--save] [--baseline name] [--json]` |
|
||||
| **Tokens** | `node scanners/token-hotspots-cli.mjs <path> [--json] [--global] [--output-file path]` |
|
||||
| **Self-audit** | `node scanners/self-audit.mjs [--json] [--fix]` |
|
||||
| **Tokens** | `node scanners/token-hotspots-cli.mjs <path> [--json] [--global] [--output-file path] [--accurate-tokens] [--with-telemetry-recipe]` |
|
||||
| **Manifest** | `node scanners/manifest.mjs <path> [--json]` — ranked system-prompt source table |
|
||||
| **What's active** | `node scanners/whats-active.mjs <path> [--json] [--verbose] [--suggest-disables]` |
|
||||
| **Self-audit** | `node scanners/self-audit.mjs [--json] [--fix] [--check-readme]` |
|
||||
| **Full scan** | `node scanners/scan-orchestrator.mjs <path> [--global] [--full-machine] [--no-suppress]` |
|
||||
|
||||
---
|
||||
|
|
@ -413,7 +420,7 @@ node scanners/posture.mjs examples/optimal-setup/
|
|||
|
||||
### Self-Audit: Scanning the Scanner
|
||||
|
||||
The plugin runs all 9 scanners on itself via `self-audit.mjs`. Current result: **Grade A, score 98, 0 real findings.** Test fixtures and example files are automatically excluded from scoring — a security plugin that ships deliberately broken examples shouldn't fail its own audit.
|
||||
The plugin runs all 12 scanners + the standalone plugin-health scanner on itself via `self-audit.mjs`. Test fixtures and example files are automatically excluded from scoring — a configuration plugin that ships deliberately broken examples shouldn't fail its own audit. Use `--check-readme` to verify badge counts are in sync with the filesystem.
|
||||
|
||||
```bash
|
||||
node scanners/self-audit.mjs
|
||||
|
|
@ -427,17 +434,19 @@ Shared modules used by all scanners — useful if you're reading the source or e
|
|||
|
||||
| Module | Purpose |
|
||||
|--------|---------|
|
||||
| `severity.mjs` | Severity constants, risk scoring, verdict logic |
|
||||
| `output.mjs` | Finding objects (`CA-XXX-NNN` format), scanner results, envelope |
|
||||
| `severity.mjs` | Severity constants, risk scoring, verdict logic, `WEIGHTS` export (v5 F3) |
|
||||
| `output.mjs` | Finding objects (`CA-XXX-NNN` format), scanner results, envelope, `details` field |
|
||||
| `file-discovery.mjs` | Config file discovery: single-path, multi-path, full-machine |
|
||||
| `yaml-parser.mjs` | Frontmatter parsing, JSON parsing, @import/section extraction |
|
||||
| `string-utils.mjs` | Line counting, truncation, similarity, key extraction |
|
||||
| `scoring.mjs` | Area scoring, health scorecard |
|
||||
| `scoring.mjs` | Area scoring (v5 severity-weighted), health scorecard, `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 of plugins/skills/MCP/hooks/CLAUDE.md cascade with token estimates |
|
||||
| `tokenizer-api.mjs` | Anthropic `count_tokens` wrapper for `--accurate-tokens` (v5 N5); 5s timeout, 429 backoff, key masking |
|
||||
|
||||
### Action Engines
|
||||
|
||||
|
|
@ -447,6 +456,9 @@ Shared modules used by all scanners — useful if you're reading the source or e
|
|||
| `rollback-engine.mjs` | `listBackups()`, `restoreBackup()`, `deleteBackup()` |
|
||||
| `fix-cli.mjs` | CLI entry point for auto-fix |
|
||||
| `drift-cli.mjs` | CLI entry point for drift detection |
|
||||
| `manifest.mjs` | CLI: ranked system-prompt source table (v5 N2) |
|
||||
| `whats-active.mjs` | CLI: read-only active-config inventory (v3.1.0+) |
|
||||
| `token-hotspots-cli.mjs` | CLI: token hotspots ranking with optional `--accurate-tokens` |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -457,11 +469,13 @@ Reference documents that inform the feature-gap agent and context-aware recommen
|
|||
| File | Content |
|
||||
|------|---------|
|
||||
| `claude-code-capabilities.md` | Feature register: 18 config surfaces, Anthropic guidance, relevance table |
|
||||
| `configuration-best-practices.md` | Per-layer best practices |
|
||||
| `configuration-best-practices.md` | Per-layer best practices (Opus 4.7 cache-stability guidance) |
|
||||
| `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` | `jq` recipe for verifying prompt-cache hit rate from session transcripts |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -471,7 +485,7 @@ Reference documents that inform the feature-gap agent and context-aware recommen
|
|||
node --test 'tests/**/*.test.mjs'
|
||||
```
|
||||
|
||||
486 tests across 27 test files (10 lib + 16 scanner + 1 hook). Test fixtures in `tests/fixtures/`. Requires Node.js 18+ (`node:test`).
|
||||
635 tests across 36 test files (12 lib + 23 scanner + 1 hook). Test fixtures in `tests/fixtures/`. Requires Node.js 18+ (`node:test`).
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue