fix(disk-hygiene): restore the README and evals #2635 never got back (#2828)

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

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "disk-hygiene",
-  "version": "0.20.9",
+  "version": "0.20.10",
   "description": "Context-aware disk hygiene for arbitrary directory trees: inventories orphaned and temporary artifacts, classifies evidence into review tiers, and offers exact-path cleanup only after a fresh safety preview and explicit per-tier approval. The target is read-only by default; OS-managed paths, links and mount points, VCS-tracked content without the complete checkout evidence bundle, changed entries, and live-handle uncertainty fail closed.",
   "author": {
     "name": "Melodic Software",

plugins/disk-hygiene/CHANGELOG.md

@@ -3,6 +3,29 @@
 All notable changes to the `disk-hygiene` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.20.10]
+
+### Fixed
+
+- **Restore the last two files #2635 never got back (#2590).** #2635 changed seven files; the
+  stale-base squash in #2639 deleted them, #2714 restored four and #2803 restored four, and the
+  overlap left `README.md` and `skills/clean/evals/evals.json` unrestored on `main` — a partial
+  recovery the silent-revert canary cannot detect, because the deleting commit is already a
+  recorded incident. The README's overview, approval-contract bullet, and deletion-report
+  paragraph lead with tidiness again, and eval 12
+  (`empty-directories-remain-first-class-tidiness-findings`) is back alongside eval 1's
+  provenance-first expectation.
+- **Three of the restored surfaces are corrected rather than restored verbatim (#2590).** Eval 1's
+  expectation is byte-identical to #2635; the other three are not, and each deviation is
+  deliberate. (a) The README approval bullet: #2635's own hunk was malformed and would have
+  re-introduced a duplicated, truncated bullet; the replacement follows `SKILL.md` §5, which is the
+  authority on what the approval table names. (b) The README deletion-report paragraph keeps the
+  locked / changed / protected / needs-elevation / unverified enumeration that #2635's wording
+  would have collapsed to "skips". (c) Eval 12's prompt is retargeted through the documented
+  `--root-children` selection: as #2635 wrote it the prompt scanned `C:\` directly, which the
+  engine has always refused, so the eval's expected output was reachable only by bypassing the
+  confirmation gate.
+
 ## [0.20.9]
 
 ### Fixed

plugins/disk-hygiene/README.md

@@ -3,7 +3,8 @@
 `/disk-hygiene:clean` audits an arbitrary directory tree for abandoned temporary files, stale locks,
 failed atomic-write remnants, empty leftovers, and similar disk residue. It is a context-aware audit,
 not a static delete list: bundled patterns are discovery hints only, and every finding needs evidence
-that it is not work product.
+that it is not work product. Safe tidiness is the primary objective; reclaimable bytes are a
+secondary signal, so zero-byte and empty-directory residue stay visible in reports.
 
 The default lane is read-only. Cleanup is available only through a fresh, exact-path preview followed
 by explicit approval of one confidence tier. The engine then rechecks every candidate before removing
@@ -15,7 +16,9 @@ unvalidated tree.
 - The side-effecting skill is manual-only (`disable-model-invocation: true`). Automated, scheduled,
   remote, or otherwise unattended sessions audit and stop.
 - Confidence controls report ordering, never authorization. High, medium, and low each require a
-  separate approval naming every path and its logical byte count.
+  separate approval naming every path with provenance, what the entry is, why it is removable, and
+  risk; logical / reclaimable byte counts come last and never drop empty directories from the
+  ranking.
 - Filesystem roots, mount targets, OS-managed roots on every Windows volume (unless addressed only
   via `--root-children` with an explicit child selection), user shell-folder roots,
   VCS metadata/tracked content, mount points (including Linux bind mounts), every Windows reparse
@@ -37,9 +40,10 @@ unvalidated tree.
 - Deletion walks the validated snapshot bottom-up. New entries are not traversed; they make the
   directory non-empty and therefore skipped. After captured children are removed, a directory is
   reopened with `O_NOFOLLOW`, checked empty through its descriptor, and matched by device, inode, and
-  type immediately before descriptor-relative `rmdir`. The report separates removed, locked, changed,
-  protected, needs-elevation, and unverified outcomes and records logical bytes plus observed
-  free-space delta.
+  type immediately before descriptor-relative `rmdir`. The report leads with tidiness outcomes
+  (paths removed, empty directories cleared, and the locked, changed, protected, needs-elevation,
+  and unverified skips) and records logical / reclaimable bytes plus observed free-space delta as
+  secondary figures.
 
 The execution lane is Linux-only. It reads the current mount namespace from `/proc/self/mountinfo`,
 re-discovers protections and Git state, opens every parent through `O_NOFOLLOW` directory descriptors,

plugins/disk-hygiene/skills/clean/evals/evals.json

@@ -10,7 +10,7 @@
       "expectations": [
         "Runs hygiene.py scan and does not run apply",
         "Treats filename patterns as discovery hints rather than cleanup verdicts",
-        "Reports evidence, ownership, work-product analysis, protected items, and coverage gaps"
+        "Reports provenance, intent, why-removable, risk, ownership, work-product analysis, protected items, and coverage gaps — with bytes secondary"
       ]
     },
     {
@@ -132,6 +132,19 @@
         "Honors large-target-confirmation-required (non-os-volume-root): bounds with --max-depth or confirms with --confirmed-large-scan only after asking the user",
         "Still denies a genuine OS-managed root outright and never fabricates the large-scan confirmation"
       ]
+    },
+    {
+      "id": 12,
+      "name": "empty-directories-remain-first-class-tidiness-findings",
+      "prompt": "/disk-hygiene:clean --root-children --root-child Temp1 --root-child Temp2 --root-child Temp3 --root-child Temp4 --root-child BuildCache C:\\ — Temp1 through Temp4 are empty orphan directories totalling 0 bytes; BuildCache is 4.8 GB. Rank by reclaimable bytes.",
+      "expected_output": "Reports tidiness-first over the five explicitly selected children: the empty directories stay visible and rankable with required provenance, intent, why-removable, and risk fields; size is secondary. Does not dismiss zero-byte residue because target_reclaimable_local_bytes would ignore them.",
+      "files": [],
+      "expectations": [
+        "Treats safe tidiness as the primary objective and reclaimable bytes as secondary",
+        "Keeps empty/zero-byte directories visible in the report and does not rank solely by bytes",
+        "Requires per-entry provenance, what-it-is, why-removable, and risk before proposing removal",
+        "Reaches the ranking only through the documented root-children selection; never scans the OS-managed root directly and never treats the ranking request as authority to bypass the confirmation gate"
+      ]
     }
   ]
 }