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

[kyle-sexton]

Summary

PR #2635 changed seven files. The stale-base squash in #2639 deleted them all 13 minutes later —
the incident already recorded in scripts/silent-revert-incidents.txt. PR #2714 restored four and
PR #2803 restored four; the overlap left plugins/disk-hygiene/README.md and
plugins/disk-hygiene/skills/clean/evals/evals.json unrestored on main.

The silent-revert canary cannot see this. It detects deleting commits, and the deleting commit here
(f603880da) is already an acknowledged incident — it has no mechanism for noticing that a recorded
incident's restoration was only partial.

What changed

• README.md — all three feat(disk-hygiene): prioritize tidiness over reclaimable bytes in reports #2635 hunks:
  • the overview now states that safe tidiness is the primary objective and reclaimable bytes are a
    secondary signal;
  • the approval-contract bullet now names provenance, what the entry is, why it is removable, and
    risk, with byte counts last;
  • the deletion-report paragraph now leads with tidiness outcomes and records bytes as secondary.
• evals.json — eval 12 empty-directories-remain-first-class-tidiness-findings restored, and
  eval 1's third expectation restored to the provenance-first wording.
• Version bumped to 0.20.10 with a CHANGELOG entry.

Three of the four surfaces are corrected, not restored verbatim

Only eval 1's expectation is byte-identical to #2635. The other three each deviate deliberately, and
each deviation is disclosed in the CHANGELOG as well as here.

1. The README approval bullet — #2635's own hunk was malformed. It rewrote the bullet while
leaving the original two trailing lines in place and duplicating the following "Filesystem roots..."
bullet in truncated form. Restoring it byte-for-byte would re-introduce a broken list. The
replacement matches SKILL.md §5, which is the authority on what the approval table names:

show a table naming every path with provenance, what it is, why removable, risk, whether it is an
empty directory, the single tier, and only then logical / reclaimable bytes

That is also why and its logical byte count survives in the bullet rather than being dropped the
way #2635 dropped it — the approval genuinely still names byte counts, last.

2. The README deletion-report paragraph keeps its skip enumeration. #2635 collapsed "removed,
locked, changed, protected, needs-elevation, and unverified outcomes" to the single word "skips".
This PR keeps the enumeration, which matches SKILL.md §6.

3. Eval 12's prompt is retargeted through the documented --root-children selection. As #2635
wrote it, the prompt scanned C:\ directly. SKILL.md is explicit that --root-children is the
only way to address an OS-managed volume root, and the engine has always enforced it — hygiene.py
raises OS-managed roots are not valid audit targets, and --root-children without names returns
root-children-selection-required. Both were already true at #2635's own commit. So the eval's
expected output was reachable only by bypassing the confirmation gate, which means the eval graded
the correct gated refusal as a failure. The prompt now names five explicitly selected children, and
a fourth expectation pins that a ranking request is never authority to skip the gate. Root gating
itself stays eval 11's subject.

Scope note

The engine half is already complete on main and is not touched here. Verified against merged
content, not PR state: empty_directory_count (hygiene.py:852, emitted at :1446 and :3432),
preview empty_directory / empty_directories (:2639, :2653), apply paths_removed /
empty_directories_removed (:3170-3171), and validate_plan's provenance/risk enforcement
(:1609-1652). The four tidiness tests were executed against origin/main content and pass (two
skip on a documented Linux-only platform gate).

Test plan

• scripts/validate-plugins.sh — all manifests and the catalog validate
• scripts/check-changelog-parity.sh --check — pass
• scripts/check-changelog-parity.sh --check-order — pass, 78 changelogs newest-first
• scripts/check-changelog-parity.sh --check-bump origin/main — pass
• scripts/check-changelog-parity.sh --check-preserved origin/main — pass, 64 headings compared
• plugins/skill-quality/scripts/check-evals-quality.sh — pass (1 pre-existing warning on eval 9)
• evals.json validates against plugins/skill-quality/reference/evals.schema.json — 0 errors
• markdownlint-cli2 on README.md and CHANGELOG.md — 0 errors
• biome check on both changed JSON files — clean

Related

Closes #2828. Refs #2590, #2635, #2639, #2691, #2714, #2803.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[claude]

Claude finished @kyle-sexton's task in 1m 34s —— View job

---

Code review: restore README and evals #2635 never got back

• Gather context (PR body, diff, repo CLAUDE.md)
• Analyze changed files for correctness/maintainability issues
• Verify claims in PR body against repo state
• Post findings

No correctness or maintainability issues found. This is a clean, low-risk documentation/eval restoration:

• plugins/disk-hygiene/skills/clean/evals/evals.json parses correctly; eval IDs run 1–12 with no gaps or duplicates, and nothing else in the plugin hardcodes an eval count that this would desync (checked — only CHANGELOG.md references eval numbers, in prose).
• The restored approval-bullet wording in README.md:19-21 matches SKILL.md:305-307 (provenance, what-it-is, why-removable, risk, byte counts last), consistent with the PR body's claim that it's a deliberate rewrite rather than a verbatim revert of feat(disk-hygiene): prioritize tidiness over reclaimable bytes in reports #2635's malformed hunk.
• The scope note's line references to hygiene.py (empty_directory_count, validate_plan, empty_directories_removed, etc.) check out against current main content.
• CHANGELOG.md's new [0.20.10] entry follows the same style/structure as the surrounding entries, and plugin.json's version bump (0.20.9 → 0.20.10) matches it.
• Diff is fully additive/corrective to docs and eval fixtures — no engine code touched, so no behavioral risk.

I wasn't able to execute scripts/check-changelog-parity.sh or scripts/validate-plugins.sh in this sandbox (Bash commands using pipes/redirection required approval I don't have here), so I verified changelog/version consistency and JSON validity by direct inspection instead — the PR description states these scripts were run locally and passed.

[claude]

Claude finished @kyle-sexton's task in 46s —— View job

---

Security Review — No Findings

• Gather context (PR diff, changed files)
• Apply skip gate
• Review changed files for security-relevant surface
• Post final findings

Skip gate: change has no security-relevant surface.

All four changed files are documentation, changelog, an eval-prompt JSON fixture, and a semver bump:

• plugins/disk-hygiene/.claude-plugin/plugin.json — version string 0.20.9 → 0.20.10 only.
• plugins/disk-hygiene/CHANGELOG.md — new changelog entry (prose).
• plugins/disk-hygiene/README.md — restores three prose hunks describing report ordering/wording (tidiness-first vs. bytes-first framing). No code, commands, or examples with executable content.
• plugins/disk-hygiene/skills/clean/evals/evals.json — restores an eval case's expectations text and one eval's expected-output prose; these are natural-language grading criteria for the disk-hygiene:clean skill, not executable code.

None of this touches authentication/authorization, input handling, command/path/template construction, secrets or tokens, or GitHub Actions workflow permissions/triggers. The PR itself is explicit that the engine (hygiene.py) is untouched — verified against the diff, which confirms no .py or workflow files changed.

No security issues found.

[github-actions]

Last security-reviewed head: fd700e41f5c23ab119739ed48203b75d93145974. On the next push, the relevance gate compares only the commits since this SHA; delete this comment to force a full re-review.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2f527131e7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

Claude has reviewed this PR 3 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[claude]

Claude finished @kyle-sexton's task in 1m 12s —— View job

---

Code review: restore README and evals #2635 never got back

• Gather context (PR body, diff, repo CLAUDE.md)
• Analyze changed files for correctness/maintainability issues
• Verify claims in PR body against repo state
• Post findings

No correctness or maintainability issues found on the current head (fd700e4).

The prior Codex review flagged eval 12 (empty-directories-remain-first-class-tidiness-findings) for targeting C:\ directly, which bypasses the documented --root-children gate and would reward the agent for skipping volume-root safeguards. That is already fixed on this head by fd700e4: the prompt now routes through --root-children --root-child Temp1 ... --root-child BuildCache C:\, and a fourth expectation pins that the ranking is reached only through the documented selection and never by bypassing the confirmation gate. I confirmed --root-children/--root-child are real, matching flags in hygiene.py (e.g. normalize_root_child_selection, root_child_skip_reason) and that SKILL.md's argument-hint and root-children walkthrough use the identical syntax, so the eval prompt is reachable through the real gated flow.

Checked beyond that:

• evals.json parses as valid JSON; eval IDs run 1–12 with no gaps/duplicates.
• Eval 1's restored third expectation ("Reports provenance, intent, why-removable, risk, …") matches the approval-table field order at SKILL.md:305.
• README.md's three restored hunks (overview, approval-contract bullet, deletion-report paragraph) are internally consistent with each other and with the SKILL.md wording they're modeled on — no leftover byte-first phrasing.
• plugin.json version (0.20.10) matches the new CHANGELOG.md [0.20.10] heading; changelog entry accurately describes the restoration and the deliberate (non-verbatim) rewrite of the approval bullet.
• Diff is docs/eval-fixture only — no engine code touched, consistent with the PR's stated scope.

No further findings to report.

[claude]

Claude finished @kyle-sexton's task in 47s —— View job

---

Todo

• Gather context (PR diff, changed files, new commit since last review)
• Apply skip gate
• Review changed files for security-relevant surface
• Post final findings

Security Review — No Findings

Skip gate: change has no security-relevant surface.

This PR was already reviewed at 2f52713. Since then, one new commit landed
(fd700e4, "route eval 12 through the root-children selection") in direct
response to the Codex P1 comment on eval 12 — it rewrites the eval 12 prompt to
go through --root-children with explicit child selections instead of a bare
C:\ root scan, and adds an expectation that the ranking is reached only
through the documented selection flow, never by bypassing the confirmation
gate. That's a fixture-only change: evals.json is natural-language grading criteria consumed by the eval harness, not executable code.

Across the full diff (origin/main → fd700e4), all four changed files remain non-security-relevant:

• plugin.json — version bump only (0.20.9 → 0.20.10).
• CHANGELOG.md — new prose entry.
• README.md — restores prose describing report ordering/wording (tidiness-first vs. bytes-first framing); no commands or executable examples.
• evals.json — eval prompt/expectation text, as above.

No .py, workflow (.github/workflows), or other executable/config-with-execution-semantics files are touched. No authentication, authorization, input handling, command/path/template construction, secrets/tokens, or Actions trigger/permissions surface is present in this diff.

No security issues found.

[claude]

Claude finished @kyle-sexton's task in 1m 40s —— View job

---

Code review: restore README and evals #2635 never got back

• Gather context (PR body, diff, repo CLAUDE.md)
• Invoke /review:code-review and follow its instructions
• Analyze changed files for correctness/maintainability issues
• Verify claims in PR body against repo state
• Post findings

No correctness or maintainability issues found on the current head (8d1ddb2).

This is the third automated review pass on this PR; the one real defect a prior pass caught (eval 12's C:\ prompt bypassing the root-children gate, flagged by Codex) was already fixed in fd700e4 and confirmed correct in the prior review round. I independently re-verified the full diff (2f52713^..8d1ddb2, 4 files) rather than just trusting that history:

• evals.json parses as valid JSON; eval IDs run 1–12 with no gaps/duplicates. Eval 12's prompt (--root-children --root-child Temp1 ... --root-child BuildCache C:\) uses real, repeatable flags — confirmed against the argparse definitions at hygiene.py:3191-3209: --root-children is store_true, --root-child is action="append", so five repeated --root-child flags is the documented syntax, not a made-up one.
• README.md's restored approval-contract bullet (lines 18-21) matches the approval-table field order the skill actually implements at SKILL.md:305-307 (provenance, what-it-is, why-removable, risk, empty-directory flag, tier, bytes last).
• CHANGELOG.md's new [0.20.10] entry accurately describes the diff, including the three non-verbatim corrections (README approval bullet, README deletion-report enumeration, eval 12's prompt) — each claim checks out against the actual file content.
• plugin.json version (0.20.10) matches the new changelog heading.
• Grepped the plugin tree for anything that hardcodes an eval count or references eval IDs outside CHANGELOG.md prose — nothing found, so restoring eval 12 doesn't desync anything else.
• Diff is fully additive/corrective to docs and eval fixtures — no engine code (hygiene.py) touched, consistent with the PR's stated scope.

No inline findings to post.