From 597e1efd8287dfbab7bc3d74a9710beab6605766 Mon Sep 17 00:00:00 2001 From: kyle-sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sun, 23 Aug 2026 18:50:30 +0000 Subject: [PATCH] fix(docs-hygiene): correct audit-noise's stated negation limitation (0.21.2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 0.21.1's "the line must close its own sentence" gate silently changed what happens to a soft-wrapped prohibition, and the "known limitation" bullet in SKILL.md was left describing 0.21.0. Two claims in it are false against the shipped detector: - It says `Do not use markdown;` / `compose prose instead.` across two lines is reported. Measured: it is not. `;` never terminates a sentence, so the line reaches no verdict at all. - It says the error direction is "a false positive, never a silent withhold". That is inverted. A hard-wrapped prohibition with no positive alternative anywhere in its sentence is now missed entirely. The second claim is load-bearing, not cosmetic: a silent withhold is the one failure mode the detector-findings admission test asks this rule set to avoid, and in a hard-wrapped repo it takes every prohibition long enough to wrap. The bullet now names it as the shape's one departure from fail-safe-toward-emitting rather than reassuring a reader that coverage is safe, and points at #3195, which carries the revised acceptance criteria. Documentation only — no detector, emitter or test behavior changes. Refs #3195, #3202. --- .../docs-hygiene/.claude-plugin/plugin.json | 2 +- plugins/docs-hygiene/CHANGELOG.md | 21 +++++++++++++++++++ .../docs-hygiene/skills/audit-noise/SKILL.md | 17 +++++++++------ 3 files changed, 33 insertions(+), 7 deletions(-) diff --git a/plugins/docs-hygiene/.claude-plugin/plugin.json b/plugins/docs-hygiene/.claude-plugin/plugin.json index bf81d29205..d21ec237b9 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.21.1", + "version": "0.21.2", "description": "Documentation-hygiene toolkit: 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), audit-derivability (classify whether a whole document earns its existence — could a fresh agent re-derive it from the code?), audit-progressive-disclosure (grade instruction files against a load-tier model for split opportunities and hub/spoke disclosure defects), write-for-agents (authoring-time doctrine that fires while agent-consumed markdown is being written), and write-for-humans (the same moment for the other reader — end-user READMEs, RFCs, release notes and guides — resolving the consuming project's own style guide first).", "author": { "name": "Melodic Software", diff --git a/plugins/docs-hygiene/CHANGELOG.md b/plugins/docs-hygiene/CHANGELOG.md index 23e6af27bd..1326800bd7 100644 --- a/plugins/docs-hygiene/CHANGELOG.md +++ b/plugins/docs-hygiene/CHANGELOG.md @@ -1,5 +1,26 @@ # Changelog — docs-hygiene plugin +## [0.21.2] + +### Fixed + +- **`audit-noise`'s stated `negation` limitation described behavior the skill no longer has, in the + wrong direction (#3195).** 0.21.1's "the line must close its own sentence" gate silently changed + what happens to a soft-wrapped prohibition, and the "known limitation" bullet in `SKILL.md` was + left describing 0.21.0. It claimed `Do not use markdown;` / `compose prose instead.` across two + lines **is reported**; measured on the shipped detector it is not — `;` never terminates a + sentence, so the line reaches no verdict. It also claimed the error direction "is a false + positive, never a silent withhold". That is now inverted: a hard-wrapped prohibition with no + positive alternative anywhere in its sentence is missed entirely. + + The correction matters beyond wording. A silent withhold is the one failure mode the + detector-findings admission test asks this rule set to avoid, and in a hard-wrapped repo it takes + every prohibition long enough to wrap — so the bullet now names it as the shape's one departure + from fail-safe-toward-emitting rather than reassuring a reader that coverage is safe. The + deferral pointer is unchanged; #3195 carries the revised acceptance criteria. + + Documentation only — no detector, emitter or test behavior changes. + ## [0.21.1] ### Fixed diff --git a/plugins/docs-hygiene/skills/audit-noise/SKILL.md b/plugins/docs-hygiene/skills/audit-noise/SKILL.md index ece8d9a1e7..5da6f3eac8 100644 --- a/plugins/docs-hygiene/skills/audit-noise/SKILL.md +++ b/plugins/docs-hygiene/skills/audit-noise/SKILL.md @@ -136,12 +136,17 @@ Shared clean-tree / no-scope shape: [`../../context/clean-tree-fallback.md`](../ pairing rule is per sentence, so a continuation line cannot be shown to lack a positive sitting on the next line; the same test excludes a table row. The cost is stated rather than hidden: a subject-led instruction ("The agent must not emit a bare summary") is not selected. -- **`negation` is scoped to one physical line (known limitation).** `detect.sh` classifies line by - line, so a sentence markdown soft-wraps is judged in pieces: `Do not use markdown;` on one line - with `compose prose instead.` on the next is reported even though the positive is paired in the - same sentence. The error direction is a false positive, never a silent withhold, so it costs - reviewer attention rather than coverage. Accumulating sentence state across soft line breaks is - deferred, not assumed away. +- **`negation` is scoped to one physical line, and WITHHOLDS on a soft-wrapped sentence (known + limitation).** `detect.sh` classifies line by line, and the scope gate requires a line to close + its own sentence, so a prohibition that markdown soft-wraps reaches no verdict at all: `Do not + use markdown` on one line with `in the summary body.` on the next is not reported, even though + no positive is paired anywhere in that sentence. Unlike every other gap here the error direction + is a **silent withhold, not a false positive** — it costs coverage rather than reviewer + attention, and in a hard-wrapped repo it takes every prohibition long enough to wrap. This is the + one place the shape does not satisfy the fail-safe-toward-emitting property that the + detector-findings admission test asks for, and it is stated rather than assumed away. + Accumulating sentence state across soft line breaks is deferred to + [#3195](https://github.com/melodic-software/claude-code-plugins/issues/3195). - **Opt-out markers respected.** A well-formed HTML comment line `` (covers the next paragraph, through the next blank line or heading) and `` (exactly the next physical line — a blank line consumes it, so place the marker directly above the content line) skip the wrapped content. A prose mention of the marker name is not a live marker. - **Convention-path exemptions apply per matched path, never per line.** An angle-bracket slot variable (`.work//…`, `docs/topics//…`) is a schema placeholder, not a literal path; the reserved concern-scoped roots (`.work/handoffs/`, `.work/reviews/`, `.work/running-retros/`, `.work/overengineering/` — roster SSOT: topic-docs Memory, concern-scoped tier) are citable only bare or with a placeholder child — a concrete child under them flags. A convention token on a line never exempts a concrete ghost ref sharing that line; the tracked concern file (`.claude/topic-docs.yaml`) matches no ghost-ref pattern and needs no exemption. Exception: the retired `.claude/notes/` location flags even in placeholder form. - **Output deterministic.** Filenames sort lexically; per-file tier rows sort by line number; no timestamps in output.