Skip to content

disk-hygiene: doc corrections — Windows mislabeled 'full', false CLAUDE_PLUGIN_DATA premise repeated, PowerShell-lane gaps #386

Description

@kyle-sexton

Summary

Several disk-hygiene docs are inaccurate about platform capability and the guard's env mechanism.
Grouping the doc corrections so the set stays internally consistent (some should land together with
the #376 fix).

D1 — setup mislabels Windows execution posture as "full"

  • skills/setup/SKILL.md:39-42 frames Windows as execution-capable ("Windows (full, lstat
    reparse + Win32, never UAC)") and separates macOS as "audit/report only by design."
  • But hygiene.py:1013-1016 (execution_blockers) returns execution-platform-unsupported for
    every non-Linux OS, and SKILL.md:151 confirms only Linux executes.

A Windows user is told they have "full" capability when apply always returns
execution-platform-unsupported. Windows should be described as audit-only for execution, like macOS.

D2 — multiple docs restate the false "hook process receives CLAUDE_PLUGIN_DATA" premise

Beyond the already-known CHANGELOG 0.3.0 line, the same incorrect claim appears at:

  • SKILL.md:59-61 ("The guard validates --data-root against the value its own hook process
    received … even when the shell environment lacks CLAUDE_PLUGIN_DATA")
  • safety-model.md:55-59

These are false for skill-frontmatter hooks (the #376 mechanism) and should be corrected together
with the CHANGELOG and the code fix so the security narrative is consistent.

D4 — PowerShell-lane docs omit two real gaps

safety-model.md:63-66 and SKILL.md:222-225 describe the PowerShell lane as gating "known
deletion spellings" without noting that (a) the kill switch does not close it (see the kill-switch
issue) and (b) move/overwrite spellings are not covered (see the mutation-spelling issue).

Severity

MEDIUM (correctness of the platform + security narrative). D2 should ship with the #376 fix.

Work-class: C2 (mechanical) — attended triage 2026-07-23, operator-ratified. 🤖

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.priority: mediumReal value, no hard deadline; normal backlog flow.

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions