release: v5.2.0 — CC 2.1.114→181 compat + skill-listing budget (SKL)
New orchestrated scanner SKL (CA-SKL-001 1,536-char listing cap, CA-SKL-002 listing-budget sum) → 13 orchestrated scanners. Five validators refreshed for the CC 2.1.114→181 settings/hook surface (xhigh effort, MessageDisplay + post-session events). False positives eliminated in MCP and permissions scanners. Hermetic HOME isolation across all CLI-spawning tests. Version sync: plugin.json 5.1.0→5.2.0, README badges (version + tests-875+), 5 stale "12→13 scanners" prose fixes, What's New + version-history rewrite, CHANGELOG [5.2.0] entry. 875/875 tests; self-audit configGrade A, pluginGrade A, readmeCheck.passed:true. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ter3E2JSi1Khgmuf2kady8
This commit is contained in:
parent
5b28e84966
commit
157690993f
4 changed files with 230 additions and 57 deletions
73
README.md
73
README.md
|
|
@ -6,22 +6,22 @@
|
|||
|
||||
*AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
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, a prompt-cache-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.
|
||||
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. 13 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, and cross-plugin collision detection. Zero external dependencies.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [What's New in v5.1.0](#whats-new-in-v510)
|
||||
- [What's New in v5.2.0](#whats-new-in-v520)
|
||||
- [What Is This?](#what-is-this)
|
||||
- [The Configuration Problem](#the-configuration-problem)
|
||||
- [Quick Start](#quick-start)
|
||||
|
|
@ -45,56 +45,16 @@ A Claude Code plugin that checks configuration health, suggests context-aware im
|
|||
|
||||
---
|
||||
|
||||
## What's New in v5.1.0
|
||||
## What's New in v5.2.0
|
||||
|
||||
**Plain-language UX humanizer** — every command's default output now leads with prose. Findings are grouped by what they mean for the user (Configuration mistake, Conflict, Wasted tokens, Missed opportunity, Dead config) and led with an urgency phrase (Fix this now, Fix soon, Fix when convenient, Optional cleanup, FYI). Technical IDs (`CA-CML-001`, `CA-TOK-005`, …) still appear, but at end-of-line where they belong as references rather than headlines.
|
||||
|
||||
### Before / after
|
||||
|
||||
```
|
||||
v5.0.0 default
|
||||
- [low] CA-CNF-001: Hook duplicate event registration
|
||||
|
||||
v5.1.0 default
|
||||
- [low] The same automation is set up more than once
|
||||
|
||||
v5.1.0 with --json (machine-readable, byte-stable)
|
||||
{ "id": "CA-CNF-001", "title": "...", "userImpactCategory": "Conflict",
|
||||
"userActionLanguage": "Optional cleanup", "relevanceContext": "affects-everyone" }
|
||||
```
|
||||
|
||||
### Plain-language vocabulary
|
||||
|
||||
The toolchain uses these terms when describing findings:
|
||||
|
||||
| User-facing label | What it means |
|
||||
|-------------------|---------------|
|
||||
| Fix this now | Something is broken or risky and should be addressed immediately |
|
||||
| Fix soon | High-priority issue worth scheduling this week |
|
||||
| Fix when convenient | Real issue but not urgent |
|
||||
| Optional cleanup | Tidy-up that improves polish but isn't required |
|
||||
| FYI | Informational; no action expected |
|
||||
| Configuration mistake | A configuration file has an error or omission |
|
||||
| Conflict | Two configuration sources disagree |
|
||||
| Wasted tokens | Configuration is loading content that costs tokens without payback |
|
||||
| Missed opportunity | A Claude Code feature you aren't using that could help your project |
|
||||
| Dead config | Configuration that has no effect (e.g., a permission that's also denied) |
|
||||
|
||||
### Backwards compatibility — the `--raw` flag
|
||||
|
||||
Every CLI accepts `--raw` for byte-stable v5.0.0 verbatim output (technical IDs, raw severity, no prose translation). `--json` is unchanged from v5.0.0 — already byte-stable for programmatic consumption. Use `--raw` only if you've built tooling against v5.0.0 stderr scrapes; for new automation, prefer `--json`.
|
||||
|
||||
```bash
|
||||
node scanners/posture.mjs . # v5.1.0 plain-language default
|
||||
node scanners/posture.mjs . --raw # v5.0.0 verbatim (byte-stable)
|
||||
node scanners/posture.mjs . --json # unchanged JSON envelope
|
||||
```
|
||||
|
||||
### What's not changed
|
||||
|
||||
- All scanner internals (12 scanners + standalone PLH) emit the same finding IDs and structural data — humanization happens at output-formatting time only
|
||||
- `--json` envelope shape is byte-stable with v5.0.0 (humanizer fields are additive on findings only in default mode; the `--json` path bypasses humanization entirely)
|
||||
- 635 tests grew to 792 (+157 covering humanizer module, scenario read-tests, forbidden-words lint, JSON / `--raw` backwards-compat, default-output snapshots, and command-template / agent-prompt shape)
|
||||
**Claude Code 2.1.114→181 compatibility + skill-listing budget.** A new orchestrated
|
||||
scanner, **SKL**, checks the model's skill-listing token budget: `CA-SKL-001` flags any
|
||||
active skill description over the 1,536-char listing cap (silently truncated by CC 2.1.105),
|
||||
and `CA-SKL-002` flags when the summed descriptions exceed the listing budget (~2% of context).
|
||||
Five validators were refreshed for the settings and hook surface that shipped across
|
||||
CC 2.1.114–181 (new settings keys, `xhigh` effort, `MessageDisplay` + post-session hook
|
||||
events), and an adversarial gap-review eliminated a batch of false positives in the MCP and
|
||||
permissions scanners. → **13 orchestrated deterministic scanners** (+ standalone plugin-health).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -104,7 +64,7 @@ Claude Code reads instructions from at least 7 different file types across multi
|
|||
|
||||
This plugin provides three layers of configuration intelligence:
|
||||
|
||||
- **Health** — 12 deterministic scanners verify correctness across every configuration file, catching broken imports, deprecated settings, conflicting rules, format errors, permission contradictions, prompt-cache token waste, cache-prefix instability, dead tool grants, and cross-plugin skill collisions
|
||||
- **Health** — 13 deterministic scanners verify correctness across every configuration file, catching broken imports, deprecated settings, conflicting rules, format errors, permission contradictions, prompt-cache 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
|
||||
|
||||
|
|
@ -333,7 +293,7 @@ By default, `/config-audit` auto-detects scope from your git context. Override w
|
|||
|
||||
## Deterministic Scanners
|
||||
|
||||
12 Node.js scanners that perform structural analysis an LLM cannot reliably do: schema validation, circular reference detection, import resolution, conflict detection across scopes, prompt-cache-aware token-cost analysis, cache-prefix stability, dead-tool detection, and cross-plugin skill collisions. Plus a standalone plugin-health scanner. Zero external dependencies.
|
||||
13 Node.js scanners that perform structural analysis an LLM cannot reliably do: schema validation, circular reference detection, import resolution, conflict detection across scopes, prompt-cache-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.
|
||||
|
||||
|
|
@ -474,7 +434,7 @@ node scanners/posture.mjs examples/optimal-setup/
|
|||
|
||||
### Self-Audit: Scanning the Scanner
|
||||
|
||||
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.
|
||||
The plugin runs all 13 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
|
||||
|
|
@ -598,6 +558,7 @@ This plugin is cautious by design — configuration files are important, and a b
|
|||
|
||||
| Version | Date | Highlights |
|
||||
|---------|------|-----------|
|
||||
| **5.2.0** | 2026-06-18 | CC 2.1.114→181 compatibility + skill-listing budget. New orchestrated scanner **SKL** (`CA-SKL-001` 1,536-char listing cap, `CA-SKL-002` listing-budget sum) → 13 orchestrated scanners. Five validators refreshed for CC 2.1.114–181 settings/hook surface (`xhigh` effort, `MessageDisplay` + post-session events, 28 hook events). False positives eliminated in MCP (auto-injected/POSIX env vars, invented `trust` field) and permissions (param-aware DIS/CNF). Hermetic HOME isolation across all CLI-spawning tests. 875 tests |
|
||||
| **5.1.0** | 2026-05-01 | Plain-language UX humanizer. Default output of all 18 commands now leads with prose; findings grouped by user-impact category (Configuration mistake, Conflict, Wasted tokens, Missed opportunity, Dead config) and led by urgency phrase (Fix this now → FYI). New `--raw` flag preserves v5.0.0 verbatim output for tooling that scrapes stderr; `--json` is unchanged and byte-stable. New scanner-lib modules: `humanizer.mjs`, `humanizer-data.mjs` with TRANSLATIONS for 13 scanner prefixes. Self-audit terminal output also humanized. 792 tests (+157 humanizer-tester) |
|
||||
| **5.0.0** | 2026-05-01 | Reality-based token-optimization. 3 new scanners (CPS cache-prefix, DIS dead tools, COL plugin collisions) → 12 deterministic scanners. New `/config-audit manifest` and `--accurate-tokens` API calibration. Severity-weighted scoring (`scoringVersion: 'v5'`). MCP token estimates 15 → 500+. Plugin Hygiene as 10th quality area. Knowledge: cache-stability replaces 200-line rule, cache-telemetry recipe. **Breaking:** F2 token magnitude jump, F3 severity weighting, F5 Pattern D removed, N1 `CA-TOK-*` glob now matches CA-TOK-005. 635 tests |
|
||||
| **4.0.0** | 2026-04-19 | Opus 4.7 era: new TOK scanner (cache-breaking volatile content, redundant tool permissions, deep import chains, sonnet-era setups), `/config-audit tokens` command, Token Efficiency 8th quality area, scanner-agent + verifier-agent migrated haiku → sonnet. 543 tests |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue