feat(codebase-audit): add repo-wide drift-audit plugin

.claude-plugin/marketplace.json

@@ -210,6 +210,12 @@
       "source": "./plugins/implementation",
       "category": "development",
       "tags": ["implementation", "build", "lint", "testing", "tdd", "e2e", "verification", "skill"]
+    },
+    {
+      "name": "codebase-audit",
+      "source": "./plugins/codebase-audit",
+      "category": "quality",
+      "tags": ["audit", "drift", "documentation", "configuration", "architecture", "verification", "claims", "skill"]
     }
   ]
 }

README.md

@@ -54,6 +54,7 @@ Browse and manage with `/plugin`. To refresh after updates: `/plugin marketplace
 | [`planning`](plugins/planning) | Skills | Pre-implementation planning pipeline of six skills: `/planning:brainstorm` (cheapest→most-ambitious candidate divergence), `/planning:prd` (three-tier product requirements), `/planning:interview` (depth-first Q&A locking a task contract into a PLAN.md Brief), `/planning:design` (collaborative type/contract/topology exploration with a binary handoff gate), `/planning:devils-advocate` (evidence-backed adversarial stress-testing), and `/planning:architect` (structured implementation plans with blast radius, parallelism analysis, and a user approval gate). |
 | [`review-toolkit`](plugins/review-toolkit) | Agents + Skills | Code-review toolkit: six read-only reviewer agents (code quality, security, architecture, doc drift, build/test/lint, CI-log audit) plus two orchestration skills — `/review-toolkit:quality-gate` (single-lens checkpoint with eight modes) and `/review-toolkit:code-review-fanout` (multi-surface fan-out normalized into one severity-ranked findings report, with a findings-driven fix pass). |
 | [`implementation`](plugins/implementation) | Skills | Implementation-stage toolkit of ten skills: `implement` / `implement-dispatch` (inline vs orchestrated plan execution with TDD cadence, divergence detection, and phase-boundary handoffs), `build` / `lint` (polyglot ecosystem-detecting verification with consumer-convention overrides), `test-write` / `test-plan` / `test-diagnose` / `test-e2e` (authoring, coverage-gap analysis, failure diagnosis, live E2E evidence), and `verify-changes` / `verify-improvement` (outcome verification and baseline-vs-after improvement measurement). |
+| [`codebase-audit`](plugins/codebase-audit) | Skills | Repo-wide drift audit that verifies a codebase's factual claims against reality: `/codebase-audit:codebase-audit` runs an eight-phase per-file subagent fan-out over configurable documentation/configuration/code-quality/architecture dimensions, independently validates each finding, and fixes or reports in a severity-rated table; `/codebase-audit:setup` interviews and writes the tracked `.claude/codebase-audit.md` audit-target config. |
 
 Install one: `/plugin install <plugin-name>@melodic-software`.
 

plugins/codebase-audit/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "codebase-audit",
+  "version": "0.1.0",
+  "description": "Repo-wide drift audit between docs, config, code, and architecture: verifies every factual claim against reality via parallel subagent fan-out, severity-rates findings, and fixes or presents for review. Audit dimensions are configurable through a tracked .claude/codebase-audit.md config file written by the setup skill.",
+  "author": {
+    "name": "Melodic Software",
+    "email": "info@melodicsoftware.com"
+  },
+  "license": "MIT",
+  "keywords": ["audit", "drift", "documentation", "configuration", "architecture", "verification", "claims", "skill"]
+}

plugins/codebase-audit/README.md

@@ -0,0 +1,85 @@
+# codebase-audit
+
+A Claude Code plugin for repo-wide drift auditing: it verifies that a codebase's **factual claims** —
+in docs, config, code, and architecture notes — still match reality. Every claim is checked against
+ground truth via a parallel per-file subagent fan-out, findings are severity-rated, and the audit
+either fixes them or presents them for review.
+
+Distinct from diff/PR review (which judges a change) and from Claude Code configuration audits (which
+check `settings.json` / hooks / permissions): this plugin verifies whether the repo's own written
+claims about itself are true.
+
+| Skill | What it does |
+|---|---|
+| `/codebase-audit:codebase-audit` | Runs the audit — prime conventions, fan out claim-extraction per file, independently validate, severity-rate, then fix or report. |
+| `/codebase-audit:setup` | Configures the audit for this repo — interviews the user, infers targets from the layout, and writes the tracked `.claude/codebase-audit.md` config. |
+
+## The audit
+
+Eight phases (0–7): prime the repo's conventions, discover via per-file fan-out, independently
+validate each finding (a separate agent re-verifies — never self-review), categorize and present in a
+severity-rated table with a verified-non-issues proof-of-thoroughness list, then — unless
+`--review-only` — fix in priority order, verify against the repo's own gates, self-review, and
+retrospect.
+
+```shell
+/codebase-audit:codebase-audit                      # audit every configured dimension (scope-gated)
+/codebase-audit:codebase-audit docs/ --docs-only    # one dimension, scoped to a subtree
+/codebase-audit:codebase-audit README.md --review-only   # scoped, present findings, no fixes
+```
+
+Dimension filters (`--docs-only`, `--code-only`, `--config-only`, `--arch-only`) are mutually
+exclusive. A scope path narrows the file set. An unscoped whole-repo run is gated — the skill
+requires a scope, a filter, or explicit confirmation before fanning out, because a full fan-out spans
+every doc/config/source file.
+
+## Configurable audit dimensions
+
+What the audit reads and how it verifies claims is **not baked in** — it comes from the consuming
+repo's tracked config, resolved additively across three layers:
+
+1. `~/.claude/codebase-audit.md` — user-global base (optional)
+2. `.claude/codebase-audit.md` — team config (tracked)
+3. `.claude/codebase-audit.local.md` — personal overlay (gitignored)
+
+Each dimension declares `primary-sources` (globs where claims live), `verification-sources` (globs
+where claims are checked against ground truth), and `example-claims` (concrete `{ claim, verify-via }`
+rows that teach the extraction pass what drift looks like in THIS repo). The four bundled dimensions
+are `documentation`, `configuration`, `code-quality`, and `architecture`; the config may tune their
+globs, remove a dimension, or add custom ones.
+
+When no config is present, the audit infers targets from the repo layout, uses them, and offers to
+persist the inference via `/codebase-audit:setup` — so the next run is deterministic. It never
+hardcodes a repo's layout.
+
+```shell
+/codebase-audit:setup   # interview + write .claude/codebase-audit.md (re-runnable)
+```
+
+Add `.claude/*.local.*` to your `.gitignore` so personal overlays stay out of version control while
+team config stays tracked.
+
+## Consumer conventions
+
+Phase 0 reads the consuming repo's own `CLAUDE.md` / `AGENTS.md` / `.claude/rules/` to learn what
+"correct" looks like — a claim contradicting those conventions is a finding; one following them is a
+verified non-issue. Nothing project-specific is baked into the plugin.
+
+## Install
+
+```shell
+/plugin marketplace add melodic-software/claude-code-plugins
+/plugin install codebase-audit@melodic-software
+```
+
+## Configuration
+
+No `userConfig` — audit targets flow through the tracked `.claude/codebase-audit.md` config seam
+above (written by `/codebase-audit:setup`). No hooks, no MCP servers, no bundled scripts, no network
+calls of its own (Phase 2 may use whatever documentation-research tools your setup provides). State:
+the audit reads and writes only the consumer's own files under the scope you give it.
+
+## License
+
+MIT (SPDX-License-Identifier: MIT). See the LICENSE file at the root of the
+melodic-software/claude-code-plugins repository.