clean

Disk hygiene

Audit first; mutate only after a fresh deterministic preview and explicit approval of one tier. A filename pattern is a discovery hint, never proof that an entry is junk. Safe tidiness is the primary objective; reclaimed bytes are secondary. Read the safety model before the optional execution lane.

Arguments and boundaries

Parse $ARGUMENTS as the complete user-facing surface: optional --execute, optional --policy <file>, optional --max-depth <N>, optional --confirmed-large-scan, optional --root-children with zero or more --root-child <name>, and one target directory. Remaining engine flags (--output, --project-dir, --data-root on scan; --snapshot, --plan, --report, --confirm-tier, --approval-token, --paths, and --vcs-evidence on the other subcommands) are supplied by this skill's command templates, not typed by the user. --execute means "deletion may be offered" on every platform, the gated engine lane where the platform supports it, the manual handoff elsewhere; it is not approval. (Deliberate semantic unification, not a restatement: the flag previously read as engine-lane-only, which left the manual lane's gate ambiguous, consumer sessions read it both ways.) --max-depth <N> bounds a scan to depth N (preferred for large targets); --confirmed-large-scan opts into an unbounded full walk after the human clears the confirmation gate's scan-scope row. --root-children is the only way to address an OS-managed volume root (for example C:\ or /): it never walks that root recursively. Without --root-child names the engine returns root-children-selection-required listing admitted immediate directories (OS-owned, hidden, system, reparse, mount, protected-shell-folder, and non-directory entries are withheld). With one or more explicit --root-child <name> flags, after the human clears the confirmation gate's root-children row, it audits only those admitted children into one snapshot. A general "clean everything" is not selection. With no target, ask once. Reject an OS-managed root (unless --root-children), a non-root mount target, a protected shell-folder root or descendant, a missing directory, a symlink, or a Windows reparse point. A whole-volume root that is not OS-managed (a Windows Dev Drive) is no longer rejected outright, it is a valid target, but as a known-large root it is gated like a home target (see step 1): the scan returns large-target-confirmation-required unless bounded with --max-depth or confirmed with --confirmed-large-scan. --root-children is invalid on a non-OS volume root or a non-volume target; scan those without the flag.