docs(disk-hygiene): split Windows audit/execution lanes, scope the guard wording, fix stale no-userConfig claim

[kyle-sexton]

Summary

Fixes findings 2 + 4 (plus one stale claim found while reproducing) from handoff-inbox item 20260722-004536-disk-hygiene-setup-audit — all declarative wording/accuracy fixes:

• Windows lanes split (F2, MED): setup check's platform posture reported "Windows (full, lstat reparse + Win32, never UAC)" while clean's preview returns execution-platform-unsupported on Windows. The posture line and the README Windows bullet now separate the lanes: full audit; engine execution unsupported; manual, per-path Recycle-Bin handoff after explicit approval. macOS gains the matching manual-Trash note.
• Guard scope stated (F4, LOW): destructive_guard.py's PreToolUse hook is registered in the clean skill's frontmatter and fires only within that skill's context. One clause in setup check step 1 and the README requirements bullet now says setup's own probes and direct hygiene.py invocation rely on the engine's built-in containment, not the hook.
• Stale security-review claim: the plugin-acceptance review's Configuration bullet said "no userConfig" — false since 0.3.0 introduced disk_hygiene_enabled. It now describes the actual surface (one non-sensitive boolean, only able to narrow the destructive surface); review conclusion unchanged.
• Version 0.6.1 → 0.6.2 + CHANGELOG.

Testing

Docs-only (SKILL.md prose + README + manifest/CHANGELOG). check-changed-skills.sh PASS, check-changelog-parity.sh --check-bump PASS.

Related

• Closes docs(disk-hygiene): split Windows audit/execution lanes, scope the guard wording, fix stale no-userConfig claim #1009
• Handoff-inbox item: 20260722-004536-disk-hygiene-setup-audit (F2 MED, F4 LOW, + stale README claim)

🤖 Generated with Claude Code

[claude]

Claude finished @kyle-sexton's task in 2m 58s —— View job

---

PR Review — docs(disk-hygiene): split Windows audit/execution lanes, scope the guard wording, fix stale no-userConfig claim

Tasks

• Load tools and start review
• Read changed files and PR diff
• Verify accuracy of documentation claims
• Check CHANGELOG and version bump
• Cross-check prose consistency across files
• Final review summary

---

Summary

This is a docs-only patch (SKILL.md prose, README, CHANGELOG, version bump). The three substantive claims all check out against the source of truth:

1. Windows lane split — The guard-scope claim is confirmed: destructive_guard.py is registered as a hooks.PreToolUse hook only in clean/SKILL.md's frontmatter (line 7–13), not globally. preview returning execution-platform-unsupported on Windows is stated consistently in clean/SKILL.md §206 and the safety-model reference.

2. Guard scope wording — The parenthetical added in setup/SKILL.md step 1 and the README requirements bullet are accurate: the hook's scope is the clean skill context, and setup's probes plus any direct hygiene.py invocation outside that context fall back on the engine's own containment.

3. userConfig stale claim — plugin.json (line 20–27) confirms disk_hygiene_enabled exists as a non-sensitive boolean defaulting to true. The new prose matches exactly.

Version bump: 0.6.1 → 0.6.2 is the correct semver increment for a docs/accuracy fix. CHANGELOG follows Keep a Changelog format, consistent with prior entries.

---

🟡 Nit — README macOS bullet doesn't gain the Trash-handoff note that Windows now has

After this PR, README.md's Windows platform bullet explicitly names the Recycle-Bin manual handoff (line 58–61):

Windows has the full audit lane … but engine execution is unsupported: preview returns execution-platform-unsupported, and removal is a manual, per-path Recycle-Bin handoff after explicit approval.

The macOS bullet (line 63–65) stays unchanged and still reads:

macOS supports audit/report only because this implementation has no authoritative bind-mount and descriptor-anchoring proof for its execution lane.

setup/SKILL.md step 3 does gain the macOS Trash note (manual Trash handoff — INFO, not a defect), and clean/SKILL.md §217 covers it in detail, so it's not undocumented. But a README reader comparing the two platform bullets sees explicit handoff guidance for Windows and none for macOS, which is a mild asymmetry.

The CHANGELOG entry says "macOS gains the matching manual Trash note" — true for SKILL.md, but the README macOS bullet is unchanged, so the sentence could mislead changelog readers.

Fix this →

---

Verdict

No blocking or important issues. All accuracy fixes are verified correct. The one Nit above is a symmetry gap rather than a factual error — it can be addressed here or deferred to a follow-up. The security review update accurately reflects the actual userConfig surface. Ready to merge as-is.

[claude]

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

---

Security Review

• Gather context and understand the request
• Fetch PR diff to identify changed files
• Read changed files in detail
• Analyze for security vulnerabilities
• Post findings

---

Scope: 4 changed files — plugin.json (version bump), CHANGELOG.md (release notes), README.md (docs), skills/setup/SKILL.md (docs). All changes are declarative/prose; no executable code was modified.

Finding: No security issues.

I reviewed all four files against the following attack surfaces and found nothing actionable:

1. Guard bypass disclosure (README.md:52–55, SKILL.md:31–34)

The PR now explicitly states that destructive_guard.py's PreToolUse hook is skill-scoped and does not cover direct hygiene.py invocations outside the clean skill. This is an honest disclosure of an existing architectural fact — it was already derivable from reading the plugin code. The text correctly names the fallback: the engine's built-in containment and preview gate still applies. No new attack surface is created; the documentation is now accurate instead of misleadingly implying always-on guard coverage.

2. userConfig surface disclosure (README.md:138–144)

The security review bullet previously falsely claimed "no userConfig". The fix accurately names disk_hygiene_enabled as a non-sensitive boolean that defaults to true and can only narrow (never widen) the destructive surface. This is confirmed against plugin.json: the userConfig definition matches the description and carries no credentials or secrets. Correcting a false "no userConfig" claim to the accurate description is a security posture improvement.

3. Windows platform posture (README.md:58–61, SKILL.md:45–51)

Purely clarifies that Windows has a full audit lane but an unsupported execution lane requiring a manual Recycle-Bin handoff. No code path changes; this closes a potential misunderstanding that the engine deletes files on Windows.

4. plugin.json version bump

Semver bump from 0.6.1 → 0.6.2. No schema, permission, or config changes beyond what was already present.

Conclusion: All changes improve the accuracy of security documentation without introducing new attack surfaces, new permissions, code execution paths, secrets, or network egress. Security review result unchanged: accept.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fc883c8039

ℹ️ 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".

[claude]

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

---

PR Review — docs(disk-hygiene): split Windows audit/execution lanes, scope the guard wording, fix stale no-userConfig claim

Tasks

• Load tools and start review
• Read changed files and PR diff
• Review the new commit (8b2cc55) addressing the Codex finding
• Check if previous nit (macOS README bullet) was addressed
• Final review summary

---

Commit 8b2cc55 — Codex P2 finding: Addressed correctly

The Codex finding was that "setting it false is audit-only mode" implied a global execution kill switch when disk_hygiene_enabled=false, which is inaccurate for direct hygiene.py invocations outside the clean skill context.

The fix at README.md:139–143 correctly scopes the claim:

setting it false puts /disk-hygiene:clean in audit-only mode (enforced by the skill-scoped guard, which denies every deletion lane there; a direct hygiene.py invocation outside that skill does not read the toggle and answers only to the engine's own preview/approval-token gate)

This is accurate — confirmed against destructive_guard.py's registration scope in clean/SKILL.md's frontmatter. The wording now draws the same boundary the README requirements bullet drew earlier in the same commit.

---

🟡 Nit (unchanged from prior review) — macOS README bullet still missing Trash handoff

The CHANGELOG 0.6.2 entry says:

macOS gains the matching manual Trash note.

This is true for setup/SKILL.md step 3 (updated in fc883c8 to say "manual Trash handoff — INFO, not a defect"), but README.md:64–65 still reads:

macOS supports audit/report only because this implementation has no authoritative bind-mount and descriptor-anchoring proof for its execution lane.

The Windows bullet immediately above it now explicitly calls out the Recycle-Bin manual handoff. A README reader comparing the two platform bullets will see explicit handoff guidance for Windows but nothing for macOS. The CHANGELOG claim is technically inaccurate for the README specifically.

Fix this →

---

Verdict

The Codex P2 finding was correctly addressed — the Configuration bullet now accurately scopes disk_hygiene_enabled=false to /disk-hygiene:clean and states the direct-invocation fallback explicitly. All other accuracy fixes from fc883c8 remain sound. The macOS README nit is a minor prose asymmetry and a small CHANGELOG inaccuracy, not a correctness or security issue. Ready to merge as-is, or address the nit here.

[claude]

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

---

Security Review

• Load tools
• Fetch PR diff
• Read changed files and verify claims against source
• Analyze for security issues
• Post findings

---

Scope: 4 changed files — plugin.json (version bump), CHANGELOG.md (release notes), README.md (prose), skills/setup/SKILL.md (prose). All changes are declarative; no executable code was touched.

Findings: None

I hunted across the following attack surfaces and found nothing actionable.

Guard-scope disclosure accuracy

The README and SKILL.md now explicitly state that destructive_guard.py's PreToolUse hook fires only within the clean skill's context, and that direct hygiene.py invocations bypass the toggle. I verified this is correct:

• The hook is registered only in clean/SKILL.md lines 7–13 as a hooks.PreToolUse entry.
• hygiene.py contains zero references to disk_hygiene_enabled — the toggle is passed only to the guard, never read by the engine directly. The documentation is accurate.

The disclosure documents an existing architectural fact, not a new bypass. Documenting it accurately is a security posture improvement; it removes a false impression that the toggle acts as a global kill switch.

userConfig surface description

plugin.json lines 20–27 confirms disk_hygiene_enabled is a non-sensitive boolean defaulting to true. The new Configuration bullet matches the definition exactly: one boolean, can only narrow (never widen) the destructive surface, no credentials.

Injection surfaces / secrets / Actions patterns / supply-chain

No run: blocks, no ${{ github.* }} interpolation, no dependency pins changed, no permissions block touched, no credentials or secrets introduced, no MCP servers added, no network egress paths added. Nothing to report.

Conclusion: No security issues. All changes improve the accuracy of existing security documentation without introducing new attack surfaces, permissions, code execution paths, or secrets.

[kyle-sexton]

🔒 merge-drive lane claiming this PR for on-branch fix work this cycle (amendment-round: 16, worker tier). Will fix clear branch-owned CI/bot findings, defer non-DEFER-FORBIDDEN items with reply+resolve, push, then re-check the merge gate.