diff --git a/plugins/disk-hygiene/.claude-plugin/plugin.json b/plugins/disk-hygiene/.claude-plugin/plugin.json index d1daacc70a..76290b7e0d 100644 --- a/plugins/disk-hygiene/.claude-plugin/plugin.json +++ b/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.34.2", + "version": "0.34.3", "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", diff --git a/plugins/disk-hygiene/CHANGELOG.md b/plugins/disk-hygiene/CHANGELOG.md index 3d612037bd..0dc9dd9814 100644 --- a/plugins/disk-hygiene/CHANGELOG.md +++ b/plugins/disk-hygiene/CHANGELOG.md @@ -3,6 +3,17 @@ 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.34.3] - 2026-09-30 + +### Fixed + +- **`/disk-hygiene:clean` docs match the engine** + ([#5520](https://github.com/melodic-software/claude-code-plugins/issues/5520)). Section 1 says the + engine creates the run directory instead of telling the agent to create it. The fan-out worker + brief tells the parent to fill ``, ``, ``, `` and the + optional `` with literal absolute values, since a worker cannot expand `${...}` + tokens, and states that `--project-dir` is optional. + ## [0.34.2] - 2026-09-30 ### Fixed diff --git a/plugins/disk-hygiene/skills/clean/SKILL.md b/plugins/disk-hygiene/skills/clean/SKILL.md index 6684e1f3ec..6d48d4adba 100644 --- a/plugins/disk-hygiene/skills/clean/SKILL.md +++ b/plugins/disk-hygiene/skills/clean/SKILL.md @@ -165,8 +165,9 @@ and has no entry cap. Detail: ## 1. Create a read-only snapshot -Create a unique run directory under `${CLAUDE_PLUGIN_DATA}/runs/`; snapshots, plans, and reports must -stay there, never in the target or `${CLAUDE_PLUGIN_ROOT}`. Run: +Choose a unique run-directory path under `${CLAUDE_PLUGIN_DATA}/runs/`; the engine creates it (it +creates the parent of `--output`). Snapshots, plans, and reports must stay there, never in the target +or `${CLAUDE_PLUGIN_ROOT}`. Run: ```text "" "${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/hygiene.py" scan \ diff --git a/plugins/disk-hygiene/skills/clean/reference/fan-out-worker-brief.md b/plugins/disk-hygiene/skills/clean/reference/fan-out-worker-brief.md index f9c83d05fd..3ded6418e4 100644 --- a/plugins/disk-hygiene/skills/clean/reference/fan-out-worker-brief.md +++ b/plugins/disk-hygiene/skills/clean/reference/fan-out-worker-brief.md @@ -4,21 +4,32 @@ Evidence-only subtree worker for `/disk-hygiene:clean` home or large-target audi owns classification, the single report, approvals, preview, and execution. You return scan evidence only. +## Parent: fill the placeholders before spawning + +A worker cannot expand `${...}` tokens (the guard rejects shell expansion), so every value it needs +must be a literal in its spawn prompt. Before spawning, replace `` and `` +with the literal values from the guard-values note (the probe in `SKILL.md` only when the note is absent). Fill +`` with `${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/` plus the engine filename, `` +with the run directory you chose, and, when it applies, `` with `${CLAUDE_PROJECT_DIR}`, +each as a literal absolute path. + ## Bash contract (instructions to you; the belt may not enforce them in a subagent) The session's skill-frontmatter belt is not reliably active inside a subagent, so nothing here is -enforced for you by that belt. The plugin-level engine gate still checks any call that names -`hygiene.py`. Follow the contract yourself. +enforced for you by that belt. The plugin-level engine gate still checks any call that names the +engine. Follow the contract yourself. + +Make every engine call a **single** invocation of the engine with no shell chaining, redirection, +or extra commands in the same tool call. Required flags on every scan: -Make every engine call a **single** invocation of `hygiene.py` with no shell chaining, -redirection, or extra commands in the same tool call. Required flags on every scan: +- `--data-root ""` (the plugin data directory the engine gate authorizes) +- `--output "/snapshot.json"` under `/runs/…`, never inside the target -- `--data-root "${CLAUDE_PLUGIN_DATA}"` (the plugin data directory the engine gate authorizes) -- `--project-dir "${CLAUDE_PROJECT_DIR}"` when the consumer project has standing policy files -- `--output "/snapshot.json"` under `${CLAUDE_PLUGIN_DATA}/runs/…`, never inside the target +`--project-dir` is optional: pass it (as a literal absolute path filled by the parent) only when the +session's project has standing policy that should apply to the target, and omit it otherwise, for +example in a home-directory session; the engine then skips the project policy layer. -Use the hook Python launcher from the skill (`` in `SKILL.md`), not a bare `python3` -on PATH. +Use the hook Python launcher the parent filled in for ``, not a bare `python3` on PATH. Do not run `apply`, `preview`, `handoff-verify`, `catalog`, `rm`, `del`, moves, or any command that mutates the target. Do not wrap the engine in compound shells (`;`, `&&`, `|`). @@ -28,9 +39,9 @@ mutates the target. Do not wrap the engine in compound shells (`;`, `&&`, `|`). **Exact subtree sizing (no per-entry inventory, no entry cap):** ```text -"" "${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/hygiene.py" scan \ +"" "" scan \ --target "" --output "/sizes.json" \ - --project-dir "${CLAUDE_PROJECT_DIR}" --data-root "${CLAUDE_PLUGIN_DATA}" \ + --data-root "" [--project-dir ""] \ --sizes-only ``` @@ -41,9 +52,9 @@ floors. **Bounded inventory (hints + handoff paths):** ```text -"" "${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/hygiene.py" scan \ +"" "" scan \ --target "" --output "/snapshot.json" \ - --project-dir "${CLAUDE_PROJECT_DIR}" --data-root "${CLAUDE_PLUGIN_DATA}" \ + --data-root "" [--project-dir ""] \ [--max-depth ] [--confirmed-large-scan] ``` @@ -52,9 +63,9 @@ Depth-cut rollups carry `walked: false` and `unwalked_reasons`; do not treat the **Home fan-out after depth-1 (selected top-level children only):** ```text -"" "${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/hygiene.py" scan \ +"" "" scan \ --target "" --output "/snapshot.json" \ - --project-dir "${CLAUDE_PROJECT_DIR}" --data-root "${CLAUDE_PLUGIN_DATA}" \ + --data-root "" [--project-dir ""] \ --root-children --root-child "" [--root-child ""]... ``` diff --git a/scripts/spoke-plugin-root-baseline.txt b/scripts/spoke-plugin-root-baseline.txt index 0656aebbb3..dad9b1b2dc 100644 --- a/scripts/spoke-plugin-root-baseline.txt +++ b/scripts/spoke-plugin-root-baseline.txt @@ -54,7 +54,7 @@ plugins/context-guard/skills/setup/reference/legacy-statusline-detect.md 2 plugins/context-guard/skills/setup/reference/statusline-edit.md 3 plugins/context-guard/skills/setup/reference/unwrap-before-compose.md 1 plugins/context7/skills/lookup/context/update.md 3 -plugins/disk-hygiene/skills/clean/reference/fan-out-worker-brief.md 3 +plugins/disk-hygiene/skills/clean/reference/fan-out-worker-brief.md 1 plugins/disk-hygiene/skills/clean/reference/safety-model.md 7 plugins/disk-hygiene/skills/clean/reference/unsupported-platform-handoff.md 2 plugins/dometrain/skills/sync/context/update.md 2