ktg-plugin-marketplace/plugins/config-audit/CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[4.0.0] - 2026-04-19

Summary

Opus 4.7 era upgrade. New TOK scanner detects token-efficiency anti-patterns (cache-breaking volatile content, redundant tool permissions, deep import chains, sonnet-era minimal setups). Token Efficiency joins the quality scorecard as the 8th area. Scanner-agent and verifier-agent migrate from haiku → sonnet per global no-haiku policy.

Added

• token-hotspots.mjs scanner (CA-TOK-001..004) — 4 patterns aligned with Opus 4.7 token-cost dynamics:
  • CA-TOK-001 cache-breaking volatile content (timestamps/UUIDs in top 30 lines of CLAUDE.md)
  • CA-TOK-002 redundant tool permissions (duplicate or subset overlaps)
  • CA-TOK-003 deep @import chains (>2 hops on the load path)
  • CA-TOK-004 sonnet-era minimal setup (no skills/MCP/hooks/managed/plugins)
• /config-audit tokens [path] [--global] — ranked hotspot table + per-pattern findings.
• scanners/token-hotspots-cli.mjs — standalone CLI emitting total_estimated_tokens, hotspots, and per-finding output.
• Token Efficiency as the 8th quality area in the posture scorecard (now 9 scanners total: CML/SET/HKV/RUL/MCP/IMP/CNF/GAP/TOK).
• id field on every area in the scorecard payload (token_efficiency, instruction_clarity, etc.) for stable downstream lookup.
• 13 new TOK scanner tests + 3 CLI tests + posture grade-stability test for token_efficiency.
• Knowledge refresh: knowledge/opus-4.7-patterns.md, plus 2026-04 deltas (v2.1.83–v2.1.111) added to feature-evolution.md, claude-code-capabilities.md, and hook-events-reference.md from research/03-claude-code-changes-config-surfaces.md.

Changed

• BREAKING (additive surface): Quality areas count 7 → 8. Posture JSON consumers that hard-coded 7 areas must update.
• BREAKING (model migration): scanner-agent and verifier-agent migrated haiku → sonnet. Latency and cost trade-offs accepted; deterministic scanner CLIs preferred over agent invocations.
• Scanner count: 8 → 9 (TOK added).
• Command count: 16 → 17 (/config-audit tokens added).
• Version bump: 3.1.0 → 4.0.0.

[3.1.0] - 2026-04-14

Summary

New read-only command /config-audit whats-active — shows exactly what Claude Code loads for a given repo, with token estimates.

Added

• /config-audit whats-active [path] — inventory of active plugins, skills, MCP servers, hooks, and CLAUDE.md cascade for a repo, with source attribution (user/project/plugin) and rough token estimates. Read-only, <2s.
• scanners/lib/active-config-reader.mjs — pure async helper: readActiveConfig(), detectGitRoot(), walkClaudeMdCascade(), readClaudeJsonProjectSlice() (longest-prefix matching), enumeratePlugins(), enumerateSkills(), readActiveHooks(), readActiveMcpServers(), estimateTokens().
• scanners/whats-active.mjs — thin CLI shim supporting --json, --output-file, --verbose, --suggest-disables.
• Optional --suggest-disables flag surfaces deterministic disable candidates (disabled MCP servers, zero-item plugins, unreferenced plugins, orphan skills) and invites an LLM judgment pass in the command.
• 36 new tests in tests/lib/active-config-reader.test.mjs, plus a rich-repo tmpdir fixture helper.

Changed

• Version bump: 3.0.1 → 3.1.0 (minor, additive feature, no breaking changes).
• Command count: 15 → 16.

[3.0.1] - 2026-04-04

Summary

Cross-platform fix — scanners, hooks, and lib now work correctly on Windows.

Fixed

• file-discovery.mjs: depth calculation, agent/command/plugin path matching now use path.sep
• scan-orchestrator.mjs: fixture-path filtering now uses path.sep
• post-edit-verify.mjs: rules-dir regex handles both / and \ separators
• auto-backup-config.mjs: rules-dir detection now uses path.sep
• import-resolver.mjs: circular import display uses basename(), /tmp fallback replaced with os.tmpdir()
• string-utils.mjs: normalizePath trailing separator regex handles both / and \

Added

• 4 cross-platform path tests (total 486 tests)

[3.0.0] - 2026-04-04

Summary

Health redesign — configuration health is now quality-only. Feature utilization removed from grades entirely.

Changed

• Health = quality only. 7 deterministic scanners (CML, SET, HKV, RUL, MCP, IMP, CNF) determine your grade. Feature Coverage is no longer a graded area.
• Feature recommendations are opt-in. Unused features shown as "opportunities" via /config-audit feature-gap, grouped by impact (high/medium/explore), backed by Anthropic docs. No more "Feature Coverage: F" for correct minimal setups.
• Posture output redesigned. Shows Health: {grade} ({score}/100) with 7 quality areas. Removed utilization %, maturity level, segment label.
• Feature-gap is interactive. Users select recommendations to implement directly — no manual file editing required. Backup created automatically.
• avgScore bug fixed. Grade letter and displayed score now computed from the same population (quality areas only).

Added

• generateHealthScorecard() in scoring.mjs — quality-only scorecard
• opportunitySummary() in feature-gap-scanner.mjs — groups findings by impact tier
• opportunityCount field in posture JSON output
• "Official Configuration Guidance" section in knowledge base (Anthropic docs, proven impacts)
• 21 new tests (total 482 across 27 test files)

Removed

• S2-PROMPT.md and V2-ANNOUNCEMENT.md — v2 development artifacts
• Utilization %, maturity level, segment label from posture terminal output and reports
• Feature Coverage row from area breakdown tables
• "Top Actions" sourced from GAP findings (replaced by opportunities pointer)

Backward Compatibility

• JSON output preserves all legacy fields (utilization, maturity, segment) for programmatic consumers
• Drift baselines unaffected — GAP findings still present in envelopes
• All existing exports maintained (calculateUtilization, determineMaturityLevel, etc.)

[2.2.0] - 2026-04-04

Summary

UX quality fix — fixture filtering, session path migration, output polish.

Added

• Automatic test-fixture filtering in scan-orchestrator: findings from tests/, examples/, __tests__/ excluded from grades, stored in env.fixture_findings
• --include-fixtures CLI flag for scan-orchestrator and posture to override filtering
• scan-orchestrator.test.mjs — 20 new tests for fixture filtering and isFixturePath
• Legacy session path detection in cleanup command

Changed

• Session storage moved from ~/.config-audit/ to ~/.claude/config-audit/ (pathguard compatible)
• Self-audit grade: F → A (98) after fixture filtering
• Combined scanner + posture into single Bash call in default audit command
• Removed "F grade is misleading" disclaimer — grades are now accurate
• All CLI banners and envelope metadata updated to v2.2.0
• 461 tests (up from 441), 27 test files (up from 26)

Removed

• Manual fixture counting instruction in config-audit.md (orchestrator handles it)
• Redundant isFixtureOrExample filter in self-audit.mjs (promoted to orchestrator)

[2.1.0] - 2026-04-03

Summary

UX redesign — auto-scope detection, zero questions, simplified command surface.

Changed

• /config-audit now runs full audit automatically (auto-detects scope from git context)
• Removed mode selection prompts — scope override via /config-audit full|repo|home|current
• Simplified from 17 to 15 commands (removed quick, report, watch; added help)
• All CLI banners and envelope metadata updated to v2.1.0

Added

• /config-audit help command with categorized command reference
• Auto-scope detection from git context (repo vs home vs full-machine)

Removed

• /config-audit:quick (merged into default /config-audit)
• /config-audit:report (merged into analyze output)
• /config-audit:watch (use /config-audit drift instead)

[2.0.0] - 2026-04-03 (v2.0 Complete)

Summary

Complete rewrite from LLM-only prototype to deterministic scanner-backed configuration intelligence. 7 development sessions (S1-S7), ~15,000 lines of code, 408+ tests.

Highlights

• 8 deterministic scanners (CML, SET, HKV, RUL, MCP, IMP, CNF, GAP) + PLH standalone
• Feature gap analysis with 25 dimensions across 4 tiers
• Auto-fix engine with 9 fix types + backup/rollback
• Drift detection with baseline comparison
• Suppression engine (.config-audit-ignore)
• Self-audit CLI
• 17 commands, 6 agents, 4 hooks
• 408+ tests (zero external dependencies)

Added (S7)

• Example projects: examples/minimal-setup/ and examples/optimal-setup/
• Demo script: examples/run-demo.sh
• .config-audit-ignore for self-audit suppressions
• V2-ANNOUNCEMENT.md
• DEPRECATED.md for capability-auditor skill

Fixed (S7)

• hooks.json: SessionStart and Stop timeout 5ms → 5000ms
• self-audit.mjs: Suppression now enabled (was hardcoded to suppress: false)

Changed (S7)

• README.md: Complete rewrite for public release
• CLAUDE.md: Added Suppressions section
• .gitignore: Added node_modules/ and S*-PROMPT.md

[1.6.0] - 2026-04-03 (v2.0 S6: Unified Reports + Self-Audit + Suppressions)

Added

• Report generator scanners/lib/report-generator.mjs — unified markdown reports: generatePostureReport(), generateDriftReport(), generatePluginHealthReport(), generateFullReport()
• Suppression engine scanners/lib/suppression.mjs — .config-audit-ignore file support with exact IDs and glob patterns (CA-SET-*), audit trail via suppressed_findings in envelope
• Self-audit CLI scanners/self-audit.mjs — runs all scanners + plugin health on this plugin: node self-audit.mjs [--json] [--fix], exit codes 0/1/2
• PostToolUse hook post-edit-verify.mjs — verifies config files after Edit/Write, blocks if new critical/high findings introduced
• New command: /config-audit:report — generate unified report (posture + optional drift/plugin-health)
• Test fixture .config-audit-ignore in fixable-project
• 54 new tests (total 408 across 25 test files)

Changed

• scan-orchestrator.mjs: suppression integration — applies .config-audit-ignore after all scanners run, --no-suppress flag to disable
• hooks.json: added PostToolUse event with post-edit-verify

[1.5.0] - 2026-04-03 (v2.0 S5: Drift + Watch + Plugin Health)

Added

• Diff engine scanners/lib/diff-engine.mjs — diffEnvelopes() comparing baseline vs current, formatDiffReport() for terminal output
• Baseline manager scanners/lib/baseline.mjs — save/load/list/delete named baselines in ~/.claude/config-audit/baselines/
• Drift CLI scanners/drift-cli.mjs — standalone: node drift-cli.mjs <path> [--save] [--baseline name] [--json] [--list]
• Plugin health scanner scanners/plugin-health-scanner.mjs (PLH) — validates plugin structure, frontmatter, cross-plugin conflicts (runs independently, not in scan-orchestrator)
• 3 new commands:
  • /config-audit:drift — compare current config against saved baseline
  • /config-audit:watch — on-demand drift check with baseline monitoring
  • /config-audit:plugin-health — audit plugin structure and cross-plugin coherence
• Test fixtures test-plugin/ (valid) and broken-plugin/ (invalid) for plugin health tests
• 48 new tests (total 354 across 21 test files)

[1.4.0] - 2026-04-03 (v2.0 S4: Fix + Rollback Action Pillar)

Added

• Fix engine scanners/fix-engine.mjs — deterministic auto-fix for 9 fix types:
  • json-key-add (missing $schema), json-key-remove (deprecated keys), json-key-type-fix (type mismatches, invalid effortLevel), json-restructure (hooks array→object, matcher object→string), frontmatter-rename (globs→paths), file-rename (non-.md→.md)
• Rollback engine scanners/rollback-engine.mjs — listBackups(), restoreBackup(), deleteBackup() with checksum verification
• Fix CLI scanners/fix-cli.mjs — standalone: node fix-cli.mjs <path> [--apply] [--json] [--global], dry-run by default
• Backup lib scanners/lib/backup.mjs — shared backup module with checksums and manifests
• 2 new commands:
  • /config-audit:fix — scan, plan, backup, apply, verify in one flow
  • /config-audit:rollback — list or restore from backups
• PreToolUse hook auto-backup-config.mjs — auto-backup config files before Edit/Write
• Test fixture fixable-project/ — fixture with all 9 fixable issue types
• 38 new tests (total 306 across 17 test files)

Changed

• file-discovery.mjs: walkRulesDir now discovers all files (not just .md) for non-.md validation
• backup-before-change.mjs: refactored to use shared lib/backup.mjs (no logic duplication)
• hooks.json: added PreToolUse event with auto-backup

[1.3.0] - 2026-04-03 (v2.0 S3: Posture + Feature Gap Commands)

Added

• Scoring module scanners/lib/scoring.mjs — utilization, maturity (5 levels), segments, area scoring, scorecard generation
• Posture CLI scanners/posture.mjs — standalone Node.js tool: node posture.mjs <path> [--json] [--global]
• 2 new commands:
  • /config-audit:posture — quick scorecard with A-F grades, utilization%, maturity level
  • /config-audit:feature-gap — deep gap analysis with prioritized next-best-actions
• feature-gap-agent — Opus agent for deep analysis, report generation (max 200 lines)
• Knowledge file gap-closure-templates.md — 11 templates with effort/gain estimates
• HTML report template templates/feature-gap-report.html — visual report with progress bars, grade badges
• 64 new tests (total 268 across 14 test files)

Changed

• Tier weighting: T1 gaps count 3x, T2 count 2x, T3/T4 count 1x in utilization score
• Maturity is threshold-based: highest level where ALL requirements are met

[1.2.0] - 2026-04-03 (v2.0 S2: Advanced Scanners + Knowledge Base)

Added

• 4 advanced scanners (zero external deps):
  • 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 gaps across 4 tiers (Foundation/Depth/Advanced/Enterprise)
• Knowledge base — 5 reference documents: capabilities, best practices, anti-patterns, hook events, feature evolution
• New test fixtures — .mcp.json files, @import chains, conflict-project/ fixture
• 75 new tests (total 204 across 12 test files)

Changed

• Scan orchestrator runs 8 scanners (was 4)
• Analyzer agent cross-references scanner findings with knowledge base

[1.1.0] - 2026-04-03 (v2.0 S1: Scanner Foundation)

Added

• Deterministic scanner infrastructure — 4 Node.js scanners (zero external deps):
  • claude-md-linter.mjs (CML) — CLAUDE.md structure, length, sections, @imports, duplicates
  • settings-validator.mjs (SET) — settings.json schema, unknown/deprecated keys, type checks
  • hook-validator.mjs (HKV) — hooks.json format, script existence, event validity, timeouts
  • rules-validator.mjs (RUL) — .claude/rules/ glob matching, orphan detection, deprecated fields
• Scanner lib — 5 shared modules: severity, output, file-discovery, yaml-parser, string-utils
• Scan orchestrator — scan-orchestrator.mjs runs all scanners, outputs JSON envelope
• Test infrastructure — 129 tests across 8 test files using node:test (zero deps)
• Test fixtures — 4 fixture projects (healthy, broken, empty, minimal)
• Finding ID format: CA-{SCANNER}-{NNN} (e.g. CA-CML-001)

Fixed

• Agent model mismatches: scanner→haiku, analyzer→sonnet, planner→opus, implementer→sonnet, verifier→haiku

Changed

• CLAUDE.md rewritten in English for public release readiness

[1.0.0] - 2026-02-11

Added

• Cross-platform support (macOS, Linux, Windows)

Fixed

• stop-session-reminder.mjs: Use path.basename/path.dirname instead of hardcoded / split
• backup-before-change.mjs: Handle both / and \ path separators in safe filename generation

Removed

• "Windows: hooks are 100% bash" from known gaps (was incorrect — all hooks are Node.js)

[0.7.0] - 2026-02-07

Note

Version reset from 1.2.0 to reflect actual maturity. Previous version was inflated — this plugin has never been externally tested.

What exists today

• 6 specialized agents (scanner, analyzer, interviewer, planner, implementer, verifier)
• Full machine-wide Claude Code configuration discovery
• Scope selection (current project, repo, home, full machine)
• Inheritance hierarchy mapping and conflict detection
• Mandatory backups before any changes
• Rollback support
• Syntax validation for all configuration files
• Quick audit-only mode
• Full optimization workflow with HITL checkpoints

Known gaps

• Testing: no automated tests
• Onboarding: never verified that a new user can install and use from scratch
• External verification: nobody else has ever used this