diff --git a/plugins/docs-hygiene/.claude-plugin/plugin.json b/plugins/docs-hygiene/.claude-plugin/plugin.json index 9a26334bb..1fec29347 100644 --- a/plugins/docs-hygiene/.claude-plugin/plugin.json +++ b/plugins/docs-hygiene/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "docs-hygiene", - "version": "0.8.0", + "version": "0.8.1", "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", diff --git a/plugins/docs-hygiene/CHANGELOG.md b/plugins/docs-hygiene/CHANGELOG.md index cf924dcf5..a134818dd 100644 --- a/plugins/docs-hygiene/CHANGELOG.md +++ b/plugins/docs-hygiene/CHANGELOG.md @@ -1,5 +1,23 @@ # Changelog — docs-hygiene plugin +## [0.8.1] — 2026-07-21 + +### Added + +- **`audit-noise` gates its five in-page NOISE shapes behind a whole-page + existence pre-check** (#505). Before line-level classification, the skill + now asks whether a reader with repository search could derive the page's + content from the code itself; a FAIL is a deletion candidate (recommend + relocate-then-delete, never auto-delete) and skips the in-page tier table. + Decisions, domain language, thin navigation, and policy/wiring pages always + pass admission. Reuses `/docs-hygiene:audit-derivability`'s rubric by + reference for contested calls (optional namespaced skill invocation, + degrading to the admission question standalone when unavailable). Ships as + a portable-baseline default; a consuming repo's own declared + documentation-existence convention overrides it via + `/re-anchor:follow-our-standards`'s resolution ladder. Read-only, matching + the skill's existing contract. + ## [0.8.0] — 2026-07-20 ### Added diff --git a/plugins/docs-hygiene/skills/audit-noise/SKILL.md b/plugins/docs-hygiene/skills/audit-noise/SKILL.md index 64a8915b5..14d57ef2c 100644 --- a/plugins/docs-hygiene/skills/audit-noise/SKILL.md +++ b/plugins/docs-hygiene/skills/audit-noise/SKILL.md @@ -17,6 +17,29 @@ Noise findings (sample): !`bash "${CLAUDE_SKILL_DIR}/scripts/detect.sh" 2>/dev/n Tracked markdown — rules, skill bodies, instruction files (`CLAUDE.md`, `AGENTS.md`), `docs/`, READMEs — accumulates five NOISE shapes distinct from FLAVOR (owned by the sibling `/compress`). Each shape carries a maintenance tax plus a reader-facing tax that compounds across the corpus. This skill is a read-only classifier: it surfaces candidates with treatment guidance; the author hand-applies every edit. +## Existence pre-check (before in-page noise) + +Before classifying in-page noise, ask the whole-page admission question first: +**could a reader with repository search derive this page's content from the +code itself?** A page failing admission is a deletion candidate — its finding +recommends relocate-then-delete (salvage anything admissible first), never a +line-level noise treatment, and never auto-delete (this skill stays +read-only). + +Four categories always pass admission regardless of derivability: decisions, +domain language, thin navigation, and policy/wiring. For the four-factor +scoring behind a contested call, reuse `/docs-hygiene:audit-derivability`'s +rubric by reference — namespaced skill invocation, optional: invoke it when +available; otherwise apply the admission question above standalone. + +**Org override.** This pre-check is a portable-baseline default. When the +consuming repository declares its own documentation-existence convention, +resolve and defer to it via `/re-anchor:follow-our-standards`'s resolution +ladder (repo-declared source → repo's own conventions → this portable +baseline) instead of the default above. + +Only a page that passes admission proceeds to the five in-page NOISE shapes below. + ## Noise shapes and treatments | Shape | What it looks like | Default tier | Treatment | @@ -58,7 +81,14 @@ Single action v1; `relocate` and `generalize` actions are deferred until real de ## Output schema -Per target file: +Per target file, the existence pre-check verdict precedes the in-page findings: + +```text +: admission PASS +: admission FAIL — deletion candidate (relocate-then-delete recommended) +``` + +A FAIL skips the in-page tier table below; a PASS proceeds to it: ```text : N finding(s) — T1=, T2=, T3= diff --git a/plugins/review/.claude-plugin/plugin.json b/plugins/review/.claude-plugin/plugin.json index d97d12a78..1543c421d 100644 --- a/plugins/review/.claude-plugin/plugin.json +++ b/plugins/review/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "review", - "version": "0.14.8", + "version": "0.14.9", "description": "Code-review toolkit: six read-only reviewer agents (code, security, architecture, doc drift, build/test/lint, CI-log audit) plus two orchestration skills — a single-lens quality gate and a multi-surface review fan-out with severity-ranked, deduplicated findings.", "author": { "name": "Melodic Software", diff --git a/plugins/review/CHANGELOG.md b/plugins/review/CHANGELOG.md index bc132f3bb..442c46d69 100644 --- a/plugins/review/CHANGELOG.md +++ b/plugins/review/CHANGELOG.md @@ -3,6 +3,25 @@ All notable changes to the `review` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.14.9] + +### Added + +- **`doc-drift-detector` gates classification behind an existence pre-check** + (#505). Before judging a page's accuracy, the agent now asks the admission + question first — could a reader with repository search derive this content + from the code itself? — and routes an admission failure to a new + **Deletion-candidate** category (recommend relocate-then-delete, never + auto-delete) instead of forcing it into Stale/Missing/Aspirational. + Decisions, domain language, thin navigation, and policy/wiring pages always + pass admission. The four-factor scoring behind a contested call reuses + `/docs-hygiene:audit-derivability`'s rubric by reference (optional + namespaced skill invocation, degrading to the admission question standalone + when that plugin is unavailable). Ships as a portable-baseline default; + a consuming repo's own declared documentation-existence convention overrides + it via `/re-anchor:follow-our-standards`'s resolution ladder. Report-only, + matching the agent's existing read-only contract. + ## [0.14.8] ### Changed diff --git a/plugins/review/agents/doc-drift-detector.md b/plugins/review/agents/doc-drift-detector.md index 4bf53c726..9d609fd42 100644 --- a/plugins/review/agents/doc-drift-detector.md +++ b/plugins/review/agents/doc-drift-detector.md @@ -39,12 +39,47 @@ Cross-reference the project's instruction surfaces (`CLAUDE.md`, project rules, - External URLs — spot-check for 404s, not exhaustively - Version numbers hardcoded in docs vs actual versions in config +## Existence pre-check (before accuracy) + +Before evaluating a page's accuracy, ask the admission question first: **could +a reader with repository search derive this content from the code itself?** A +page that fails admission is drift by construction — its finding is a +deletion-candidate recommendation, not an accuracy fix, and the page never +enters the Stale/Missing/Aspirational classification below. + +Four categories always pass admission, regardless of how derivable the +surrounding page reads: + +- **Decisions** — a chosen option erases the record of alternatives rejected +- **Domain language** — ubiquitous-language definitions the code enforces but + does not narrate +- **Thin navigation** — index/wayfinding pages whose value is curation, not + restated content +- **Policy and wiring** — cross-cutting rules and integration seams no single + file states + +For the four-factor scoring behind a contested admission call, reuse +`/docs-hygiene:audit-derivability`'s rubric by reference — namespaced skill +invocation, optional: invoke it when the `docs-hygiene` plugin is available; +otherwise apply the admission question above standalone, which stands on its +own for a pass/fail call. + +An admission failure recommends **relocate-then-delete** (salvage anything +admissible first) — this agent is report-only and never deletes. + +**Org override.** This pre-check is a portable-baseline default. When the +consuming repository declares its own documentation-existence convention, +resolve and defer to it via `/re-anchor:follow-our-standards`'s resolution +ladder (repo-declared source → repo's own conventions → this portable +baseline) instead of the default above. + ## Workflow 1. Pick a documentation area to audit (or audit all when invoked without scope) -2. Read the documentation file -3. Cross-reference each factual claim against the actual code/config -4. Report discrepancies with specific `file:line` references +2. For each candidate page, run the existence pre-check above before anything else +3. Read the documentation file +4. Cross-reference each factual claim against the actual code/config +5. Report discrepancies with specific `file:line` references ## Output format @@ -54,11 +89,12 @@ Cross-reference the project's instruction surfaces (`CLAUDE.md`, project rules, Categorize findings: -1. **Stale** — documentation contradicts current code (fix immediately) -2. **Missing** — code exists that documentation doesn't cover (add docs) -3. **Aspirational** — documentation describes planned features as if implemented (clarify status) +1. **Deletion-candidate** — failed the existence pre-check (recommend relocate-then-delete, never auto-delete) +2. **Stale** — documentation contradicts current code (fix immediately) +3. **Missing** — code exists that documentation doesn't cover (add docs) +4. **Aspirational** — documentation describes planned features as if implemented (clarify status) -Severity baseline when the caller needs tiers: `${CLAUDE_PLUGIN_ROOT}/context/severity.md` — Stale maps to IMPORTANT; Missing and Aspirational map to SUGGESTION. +Severity baseline when the caller needs tiers: `${CLAUDE_PLUGIN_ROOT}/context/severity.md` — Deletion-candidate and Stale map to IMPORTANT; Missing and Aspirational map to SUGGESTION. You are a subagent and cannot ask the user questions. Flag ambiguities explicitly in your report instead.