feat(docs-hygiene): add audit-derivability skill

README.md

@@ -101,7 +101,7 @@ user opts in with `/plugin enable`; an existing install is never flipped by cata
 
 - [`bug-report`](plugins/bug-report) — Produces a structured five-field bug report — title, steps to reproduce, expected vs actual, severity with justification, and suggested fix location — from an informal defect description. Read-only by default: it emits the report and never edits code, opens a PR, or files an issue on its own.
 - [`debugging`](plugins/debugging) — Debug observed failures via a disciplined six-phase loop: build a fast deterministic reproduction signal, reproduce, rank falsifiable hypotheses, instrument, fix with a regression test, then clean up and post-mortem.
-- [`docs-hygiene`](plugins/docs-hygiene) — Documentation-hygiene toolkit of five skills: compress (flavor-trim markdown with a semantic-diff safety net), audit-noise (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), audit-encapsulation (detect citations into skill-private surfaces), and rename-references (sweep stale references after renames).
+- [`docs-hygiene`](plugins/docs-hygiene) — Documentation-hygiene toolkit of six skills: compress (flavor-trim markdown with a semantic-diff safety net), audit-noise (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), audit-encapsulation (detect citations into skill-private surfaces), rename-references (sweep stale references after renames), and audit-derivability (classify whether a whole document earns its existence — could a fresh agent re-derive it from the code?).
 - [`code-tidying`](plugins/code-tidying) — Code tidying and comment hygiene: /code-tidying:tidy proactively hunts a rotated, glob-scoped lane for Beck-style tidyings under a research-backed scope budget and ships one tight PR; /code-tidying:batch-simplify sweeps recently changed files through grouped, dependency-ordered simplification waves with a never-drop deferred-items contract; /code-tidying:audit-comment-residue is a read-only classifier that flags history, plan, conversational, and ticket/PR residue in code comments for author-applied deletion. Project-specific tidy lanes are scaffolded into a tracked .claude/tidy-lanes/ config folder by a re-runnable setup skill.
 - [`repo-hygiene`](plugins/repo-hygiene) — Repo hygiene action-router: /repo-hygiene:clean sweeps reclaimable caches, build artifacts, and stale git metadata, and can realign the working tree to a fresh-pull state — dry-run-first, with destructive tiers gated behind explicit confirmation and a session-scoped destructive-command guard. Ecosystem targets are detected at runtime; secrets, runtime dependencies, and skill data are preserved by default.
 - [`repo-fleet-hygiene`](plugins/repo-fleet-hygiene) — Read-only Git/GitHub fleet audit for merged local branches, orphaned or mismatched worktree registrations, and repository transfers or renames. Findings are confidence-tiered and hand off exact targets to existing per-repository cleanup tools; this plugin never deletes branches or worktrees.

plugins/docs-hygiene/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "docs-hygiene",
-  "version": "0.7.1",
-  "description": "Documentation-hygiene toolkit of five skills: compress (flavor-trim markdown with a semantic-diff safety net), audit-noise (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), audit-encapsulation (detect citations into skill-private surfaces), and rename-references (sweep stale references after renames).",
+  "version": "0.8.0",
+  "description": "Documentation-hygiene toolkit of six skills: compress (flavor-trim markdown with a semantic-diff safety net), audit-noise (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), audit-encapsulation (detect citations into skill-private surfaces), rename-references (sweep stale references after renames), and audit-derivability (classify whether a whole document earns its existence — could a fresh agent re-derive it from the code?).",
   "author": {
     "name": "Melodic Software",
     "email": "info@melodicsoftware.com"
@@ -14,6 +14,7 @@
     "maintenance",
     "hygiene",
     "deduplication",
+    "derivability",
     "refactoring"
   ]
 }

plugins/docs-hygiene/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog — docs-hygiene plugin
 
+## [0.8.0] — 2026-07-20
+
+### Added
+
+- `/docs-hygiene:audit-derivability` — a read-only, document-level worth
+  classifier. It asks whether a whole documentation file earns its existence:
+  could a fresh agent re-derive the document's conclusions by natively exploring
+  the code, config, metadata, and structure? Verdicts weigh four factors
+  together (derivability, re-derivation cost, drift risk, fact ownership) and
+  never derivability alone — `delete`, `convert-to-pointer`,
+  `keep-as-derivation-cache` (which demotes when it carries no drift-control
+  condition), or `keep-owns-facts` (rationale, decisions, constraints, and
+  external facts are non-derivable). Audience-aware (agent-facing surfaces get
+  the full axe; human-facing docs clear a higher bar), and load-bearing or
+  contested deletions are confirmed by a fresh-context, non-fork spot-test that
+  has not seen the document. Distinct axis from the siblings, which trim
+  *inside* a document worth keeping.
+
 ## [0.7.1] — 2026-07-20
 
 ### Changed

plugins/docs-hygiene/README.md

@@ -1,11 +1,12 @@
 # docs-hygiene
 
-A Claude Code plugin bundling five documentation-hygiene skills — one cohesive
+A Claude Code plugin bundling six documentation-hygiene skills — one cohesive
 capability: keeping a repository's tracked markdown lean, deduplicated, and
 free of decayed references. Each skill is invocable on its own; together they
-cover the flavor, noise, duplication, boundary, and rename axes of doc upkeep.
+cover the flavor, noise, duplication, boundary, rename, and worth axes of doc
+upkeep.
 
-## The five skills
+## The six skills
 
 | Skill | What it does |
 |---|---|
@@ -14,6 +15,7 @@ cover the flavor, noise, duplication, boundary, and rename axes of doc upkeep.
 | `/docs-hygiene:extract-ssot` | Deduplicates content repeated across 3+ files into a single named source of truth and migrates call sites to cite it by heading — with refuse-fast verification gates (Rule of Three, Tier-0 evidence) so weak clusters are rejected instead of extracted. |
 | `/docs-hygiene:audit-encapsulation` | Detects external citations reaching into skill-private surfaces inside `.claude/skills/<name>/` (private subdirectories, heading anchors, schema files) and routes each violation to a remediation path. Ships its own public-surface contract reference. |
 | `/docs-hygiene:rename-references` | Sweeps stale references after renames — the forms plain token grep misses: slash-command tokens, relative paths from moved files, frontmatter chains and globs — via a 12-form pattern library with audit, half-rename detection, and apply modes. |
+| `/docs-hygiene:audit-derivability` | Read-only, document-level worth classifier: could a fresh agent re-derive this whole document from the code, config, and structure? Weighs derivability, re-derivation cost, drift risk, and fact ownership into a verdict (delete, convert-to-pointer, keep-as-derivation-cache, keep-owns-facts), splits it by audience, and confirms load-bearing deletions with a fresh-context spot-test. Where the other five trim *inside* a doc, this decides whether the doc should exist. |
 
 ## Requirements
 
@@ -23,7 +25,7 @@ cover the flavor, noise, duplication, boundary, and rename axes of doc upkeep.
   post-edit lint pass is the mandatory ship gate. It must be on `PATH` or
   installed in the consuming repo (`node_modules/.bin/markdownlint-cli2`);
   when absent, `compress` stops at the entry point with that remediation
-  instead of shipping unverified output. The other four skills do not use it.
+  instead of shipping unverified output. The other five skills do not use it.
 - **`caveman` plugin** (optional) — a compression backend for `compress`;
   absent, an in-session fallback applies and every verification gate still
   runs.