chore(evals): author skill evals for docs-hygiene (5 skills)

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.1.0",
+  "version": "0.2.0",
   "description": "Documentation-hygiene toolkit of five skills: compress (flavor-trim markdown with a semantic-diff safety net), declutter (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), encapsulation-audit (detect citations into skill-private surfaces), and rename-references (sweep stale references after renames).",
   "author": {
     "name": "Melodic Software",

plugins/docs-hygiene/skills/compress/evals/evals.json

@@ -0,0 +1,78 @@
+{
+  "skill_name": "compress",
+  "evals": [
+    {
+      "id": 1,
+      "name": "default-compress-preserves-content",
+      "prompt": "Compress this doc: read evals/fixtures/verbose-onboarding-snippet.md relative to the skill directory and tighten it. Drop the flavor but keep everything load-bearing.",
+      "expected_output": "Runs the default action: snapshot, mechanical compression backend (caveman or in-session Edit), a separate semantic-diff pass, revert of any semantic loss, then markdownlint. Filler ('basically', 'really', 'just', 'honestly', 'perhaps') is cut; the zero-warnings directive, the `MAX_UPLOAD_MB=25` value, and the 25 MB rejection threshold are preserved verbatim.",
+      "files": ["evals/fixtures/verbose-onboarding-snippet.md"],
+      "expectations": [
+        "Output removes filler/hedging words (e.g. 'basically', 'really', 'just', 'honestly', 'perhaps')",
+        "The literal `MAX_UPLOAD_MB=25` and the 25 MB rejection threshold are preserved, not dropped or altered",
+        "The 'warnings are treated as errors / block the merge' directive is preserved as content, not cut as flavor",
+        "The run includes a semantic-diff verification step and a markdownlint check, not just a raw edit"
+      ]
+    },
+    {
+      "id": 2,
+      "name": "audit-is-read-only",
+      "prompt": "/compress audit docs/",
+      "expected_output": "Runs the audit action only: a read-only dry-run that classifies each target SKIP / COMPRESS / UNCERTAIN with an expected-yield estimate. No file is edited and no semantic-diff subagent is dispatched.",
+      "files": [],
+      "expectations": [
+        "The run classifies targets as SKIP / COMPRESS / UNCERTAIN rather than editing them",
+        "No file is modified (audit is read-only)",
+        "No semantic-diff subagent is dispatched (dispatch is default-action only, not audit)"
+      ]
+    },
+    {
+      "id": 3,
+      "name": "semantic-diff-is-separate-not-self-audit",
+      "prompt": "Compress the prose in docs/architecture/overview.md. It's long and wordy.",
+      "expected_output": "After producing the condensed edits, a SEPARATE fresh-context semantic-diff pass compares original vs condensed and reverts every SEMANTIC LOSS and AMBIGUITY finding. The model that produced the edits does not grade its own output, and the verifier does not re-add words to 'preserve clarity'.",
+      "files": [],
+      "expectations": [
+        "The semantic-diff verification is described as a separate fresh-context pass, not a self-review by the editing model",
+        "SEMANTIC LOSS and AMBIGUITY findings are reverted, not merely noted",
+        "The verifier is not used to re-expand or re-add removed words"
+      ]
+    },
+    {
+      "id": 4,
+      "name": "sub-3-percent-reverts-without-force",
+      "prompt": "Compress CLAUDE.md — it's already pretty tight but see if there's anything to cut.",
+      "expected_output": "An already-disciplined always-loaded instruction file yields under 3% with zero semantic loss, so the default `<3% AND 0 semantic-loss -> REVERT` rule trips and the change is reverted. The run notes that `--force` would be required to keep a sub-3% diff.",
+      "files": [],
+      "expectations": [
+        "A sub-3%, zero-semantic-loss result is reverted rather than shipped under the default rule",
+        "Output states that `--force` is the way to keep an intentional sub-3% diff",
+        "Output does not silently ship a below-threshold change as if it were a normal compression"
+      ]
+    },
+    {
+      "id": 5,
+      "name": "refuse-code-file-target",
+      "prompt": "Compress apps/billing/src/fees.ts — trim the verbose comments and dead code.",
+      "expected_output": "Declines: the methodology is markdown-specific and code / code-comment compression is out of scope. It does not run the compression pipeline on the TypeScript file and points to code-focused tooling instead.",
+      "files": [],
+      "expectations": [
+        "Output declines to compress the code file, citing markdown-only scope",
+        "Output does NOT run the flavor-vs-content compression pipeline on the `.ts` source",
+        "Output does not treat code-comment trimming as in scope"
+      ]
+    },
+    {
+      "id": 6,
+      "name": "ssot-relocation-not-flavor",
+      "prompt": "Compress docs/guide.md. One paragraph restates the full label taxonomy that already lives in .claude/rules/labels.md — collapse it down to a citation while you're compressing.",
+      "expected_output": "Recognizes that collapsing a passage which recaps a cited single source of truth is content RELOCATION, not flavor removal — the semantic-diff net would see the words gone from THIS file and revert them as semantic loss, blind to the SSOT. It treats the relocation as a manual editorial pass (verifying the SSOT actually holds the detail first), or routes multi-file duplication to /extract-ssot, rather than silently deleting the paragraph as flavor.",
+      "files": [],
+      "expectations": [
+        "Output distinguishes content relocation (recap of a cited SSOT) from flavor removal",
+        "Output does NOT silently delete the recap paragraph as if it were flavor that the semantic-diff pass would allow",
+        "Output routes the dedup to a manual editorial pass or to /extract-ssot rather than handling it as ordinary compression"
+      ]
+    }
+  ]
+}

plugins/docs-hygiene/skills/compress/evals/fixtures/verbose-onboarding-snippet.md

@@ -0,0 +1,12 @@
+# Onboarding: local build
+
+Basically, before you really get started, you should just make sure that you have
+the required toolchain installed. Honestly, this is perhaps the single most common
+thing that trips new contributors up, so it is really worth double-checking.
+
+Run the build. The build MUST complete with zero warnings — warnings are treated as
+errors and will block the merge. If you happen to see any warnings at all, you will
+want to fix the root cause rather than suppressing them.
+
+Set `MAX_UPLOAD_MB=25` before starting the dev server; uploads above 25 MB are
+rejected by the gateway.

plugins/docs-hygiene/skills/declutter/evals/evals.json

@@ -0,0 +1,74 @@
+{
+  "skill_name": "declutter",
+  "evals": [
+    {
+      "id": 1,
+      "name": "classify-noise-shapes-with-tiers",
+      "prompt": "Declutter this file: read evals/fixtures/noisy-rule-snippet.md relative to the skill directory and audit it for noise.",
+      "expected_output": "Emits a per-file tier table classifying the noise: the dated 'Empirically observed 2026-03-14' line as a citation, the `.work/net-hardening-slice/PLAN.md` reference as a ghost-ref (Tier 2), the 'Path-scoped to ... loads on Read' clause as scope-meta, and the hardcoded 'following three skills' roster as an enum-list. Each finding carries treatment guidance. No edits are applied.",
+      "files": ["evals/fixtures/noisy-rule-snippet.md"],
+      "expectations": [
+        "Output classifies findings by the skill's shape vocabulary (citation, ghost-ref, preamble, enum-list, scope-meta)",
+        "The `.work/net-hardening-slice/PLAN.md` reference is flagged as a ghost-ref",
+        "The hardcoded 'following three skills' list is flagged as an enum-list with a runtime-derivation / category-citation treatment",
+        "The output is a classification report with tiers and treatments; no file is edited"
+      ]
+    },
+    {
+      "id": 2,
+      "name": "read-only-even-when-asked-to-fix",
+      "prompt": "Declutter .claude/rules/foo.md and just go ahead and strip the noise you find — remove it for me.",
+      "expected_output": "Stays read-only despite the request to edit: surfaces the findings with treatment guidance and does NOT apply Edit/Write. It explains the author applies each treatment, or points to the sibling edit-capable skills for the actual removal.",
+      "files": [],
+      "expectations": [
+        "Output does NOT edit or write the file despite the explicit request to strip noise",
+        "Output surfaces findings with treatment guidance for the author to apply",
+        "The read-only contract is honored or explicitly stated"
+      ]
+    },
+    {
+      "id": 3,
+      "name": "slot-variable-not-flagged-as-ghost-ref",
+      "prompt": "Declutter a rule file whose body contains the schema placeholder path `.work/<slug>/PLAN.md` used to describe the working-notes convention (not a literal directory name). Classify it.",
+      "expected_output": "Recognizes `<slug>` as a slot-variable / schema placeholder and does NOT flag it as a ghost-ref. Only concrete literal paths into ephemeral directories are ghost-refs.",
+      "files": [],
+      "expectations": [
+        "The `<slug>` placeholder path is NOT flagged as a ghost-ref",
+        "Output states that slot-variable / schema-placeholder tokens are exempt from the ghost-ref shape"
+      ]
+    },
+    {
+      "id": 4,
+      "name": "exempt-sections-never-flagged",
+      "prompt": "Declutter a rule file that ends with a `## Cross-references` section listing sibling rules and a `## Sources` footer with dated citations. Audit the whole file.",
+      "expected_output": "Treats `## Cross-references` and `## Sources` / `## History` footers as exempt sections and does NOT flag their contents (including the dated citations that live in the Sources footer, which is exactly where the citation treatment relocates them).",
+      "files": [],
+      "expectations": [
+        "Content under `## Cross-references` is not flagged as noise",
+        "Dated citations inside a `## Sources` / `## History` footer are not flagged (the footer is the citation shape's relocation target, not noise)"
+      ]
+    },
+    {
+      "id": 5,
+      "name": "flavor-is-compress-not-declutter",
+      "prompt": "Declutter docs/wordy.md — it's full of filler like 'basically', 'really', and 'just', plus a lot of hedging. Flag all of that.",
+      "expected_output": "Does NOT classify filler / hedging / articles as any of the five declutter noise shapes — that FLAVOR is the sibling /compress's territory. It reports no noise-shape findings for the filler and routes flavor removal to /compress.",
+      "files": [],
+      "expectations": [
+        "Filler / hedging words are NOT classified under any of declutter's five noise shapes",
+        "Output routes flavor removal to /compress rather than handling it as declutter noise"
+      ]
+    },
+    {
+      "id": 6,
+      "name": "preamble-diataxis-classification",
+      "prompt": "Declutter a data-registry reference file (a table of label slugs) that opens with a multi-paragraph 'Why this file exists' section explaining the history and motivation. How do you treat the preamble?",
+      "expected_output": "Applies the Diataxis classifier: on a Reference-quadrant file (a data table / registry) the 'Why this file exists' preamble is Tier 2 with a STRIP treatment, replacing it with a one-sentence orientation — as opposed to KEEP on an Explanation-quadrant file (rule body, ADR, convention rationale).",
+      "files": [],
+      "expectations": [
+        "Output flags the preamble on the Reference-quadrant file with a STRIP / replace-with-one-sentence treatment",
+        "Output distinguishes the Reference-quadrant STRIP from the Explanation-quadrant KEEP case"
+      ]
+    }
+  ]
+}

plugins/docs-hygiene/skills/declutter/evals/fixtures/noisy-rule-snippet.md

@@ -0,0 +1,22 @@
+# Retry policy
+
+## Why this file exists
+
+This file exists to document the retry policy. It was created because we kept
+re-litigating retry behavior in review, so we wrote it down here to settle it.
+
+Path-scoped to `src/net/**`; loads on Read of any file under that tree.
+
+## Policy
+
+Empirically observed 2026-03-14: three retries with exponential backoff clears the
+transient socket resets we saw in the incident. Cap total wait at 30s.
+
+For per-slice overrides, see `.work/net-hardening-slice/PLAN.md` for the worked
+example the author drafted.
+
+The following three skills consume this rule: `/net-audit`, `/net-lint`, `/net-verify`.
+
+## Cross-references
+
+- `src/net/backoff.md` — backoff curve derivation

plugins/docs-hygiene/skills/encapsulation-audit/evals/evals.json

@@ -0,0 +1,75 @@
+{
+  "skill_name": "encapsulation-audit",
+  "evals": [
+    {
+      "id": 1,
+      "name": "detect-routes-and-tables-violations",
+      "prompt": "Audit encapsulation across the repo — who is reaching into skill internals?",
+      "expected_output": "Runs the detect action: executes the detection grep, classifies each raw hit legal-vs-illegal via the filter taxonomy, and emits a violations table (File / Line / Cite / Suggested path A|B) plus a summary count. One action per response.",
+      "files": [],
+      "expectations": [
+        "Output runs the detect action and produces a violations table with a suggested remediation path (A or B) per hit",
+        "Raw hits are classified through the filter taxonomy rather than every grep hit being reported as illegal",
+        "Output is scoped to detect only, not fix or file-issues in the same response"
+      ]
+    },
+    {
+      "id": 2,
+      "name": "single-violation-still-flagged",
+      "prompt": "The detector found exactly one external citation reaching into a skill's private subdirectory. It's only one place — is that worth flagging?",
+      "expected_output": "Flags the single violation. Encapsulation violations are single-instance matters — the Rule of Three does NOT gate them, and 'it's only one place' is the single-violation-tolerance anti-pattern the skill guards against. Each cite is a binary contract break.",
+      "files": [],
+      "expectations": [
+        "Output flags the single violation rather than dismissing it as below a threshold",
+        "Output states that the Rule of Three does not gate encapsulation (single-instance matter)",
+        "Output does not treat 'only one place' as a reason to tolerate the violation"
+      ]
+    },
+    {
+      "id": 3,
+      "name": "filter-taxonomy-legal-hits",
+      "prompt": "The detect grep returned two hits: (a) `.claude/skills/compress/SKILL.md` citing `.claude/skills/compress/context/flavor-vs-content-matrix.md`, and (b) a path under `~/.claude/plugins/cache/docs-hygiene/...`. Classify them.",
+      "expected_output": "Classifies both as legal, not violations: (a) is self-citation (intra-skill progressive disclosure) and (b) is plugin-cache (upstream territory / foreign contract). Neither survives the filter taxonomy as illegal.",
+      "files": [],
+      "expectations": [
+        "The self-citation (skill citing its own private path) is classified legal, not a violation",
+        "The `~/.claude/plugins/cache/...` hit is classified legal (plugin-cache filter)",
+        "Neither hit is reported as an illegal violation"
+      ]
+    },
+    {
+      "id": 4,
+      "name": "path-b-missing-action-files-and-stops",
+      "prompt": "A rule file reaches into a skill's private body because it wants the skill's behavior, but the skill has no public action that covers the use case. Remediate it.",
+      "expected_output": "Chooses Path B (route via /skill invocation) but, finding the needed public action does NOT exist, surfaces the gap as a side note, files a tracking work item for the missing action, and leaves a `# TODO(encapsulation-audit): missing /<skill> <action>` marker — it does NOT silently inline a workaround that hides the violation from future audits.",
+      "files": [],
+      "expectations": [
+        "Output identifies this as a Path B (wants behavior) case, not Path A (wants data)",
+        "On the missing action it files a tracking work item and leaves a TODO(encapsulation-audit) marker rather than fixing it silently",
+        "Output does NOT inline a workaround that would hide the violation from later audits"
+      ]
+    },
+    {
+      "id": 5,
+      "name": "scripts-entry-surface-is-legal",
+      "prompt": "A CI workflow path-cites `.claude/skills/extract-ssot/scripts/detect.sh` directly. Is that an encapsulation violation?",
+      "expected_output": "No — a skill's `scripts/` is its declared entry surface, so harness / CI / hooks may path-cite entry scripts directly. The inbound audit treats `<X>/scripts/...` cites as legal (like data files and a bare SKILL.md path) and does not flag it.",
+      "files": [],
+      "expectations": [
+        "Output classifies the `scripts/` entry-script cite as legal, not a violation",
+        "Output cites the scripts/ entry-surface carve-out as the reason"
+      ]
+    },
+    {
+      "id": 6,
+      "name": "duplication-routes-to-extract-ssot",
+      "prompt": "I found the same paragraph of content duplicated across three skill bodies. Can encapsulation-audit consolidate it?",
+      "expected_output": "Routes away: content duplication / Rule-of-Three clusters are the sibling /extract-ssot's concern, not encapsulation-audit's. This skill detects citations into private surfaces, not repeated content.",
+      "files": [],
+      "expectations": [
+        "Output routes content-duplication consolidation to /extract-ssot",
+        "Output does NOT treat cross-file duplication as an encapsulation violation"
+      ]
+    }
+  ]
+}