From fae2dc29d6d1738b6cd9659481ebb234821b9321 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 30 Sep 2026 00:35:01 -0400 Subject: [PATCH 1/4] docs(disk-hygiene): fix run-directory, fan-out brief and --project-dir wording Refs #5520 Co-Authored-By: Claude Opus 5.5 --- .../disk-hygiene/.claude-plugin/plugin.json | 2 +- plugins/disk-hygiene/CHANGELOG.md | 11 +++++ plugins/disk-hygiene/skills/clean/SKILL.md | 5 ++- .../clean/reference/fan-out-worker-brief.md | 41 ++++++++++++------- 4 files changed, 41 insertions(+), 18 deletions(-) diff --git a/plugins/disk-hygiene/.claude-plugin/plugin.json b/plugins/disk-hygiene/.claude-plugin/plugin.json index 066b53f004..c9ffa07e60 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.29.0", + "version": "0.29.1", "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 5e1fa6c271..98be42bc54 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.29.1] - 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.29.0] - 2026-09-29 ### Added diff --git a/plugins/disk-hygiene/skills/clean/SKILL.md b/plugins/disk-hygiene/skills/clean/SKILL.md index 2ef2d309ad..e2658df5ad 100644 --- a/plugins/disk-hygiene/skills/clean/SKILL.md +++ b/plugins/disk-hygiene/skills/clean/SKILL.md @@ -160,8 +160,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 b5ffd25362..b382eb3458 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) and never receives the +guard-values note, which a hook emits only when a person types the command. Before spawning, +replace ``, `` (the path `${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/` plus the +engine filename), `` (the `data_root` value), ``, and, when it applies, +`` with the literal absolute values you already hold from the guard-values note or the +kill-switch probe in `SKILL.md`. + ## 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`, `rm`, `del`, moves, or any command that mutates the target. Do not wrap the engine in compound shells (`;`, `&&`, `|`). @@ -28,9 +39,9 @@ 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 ""]... ``` From ce630c2446f5994fb4dfdb1d9736af2664be93ed Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 30 Sep 2026 01:49:02 -0400 Subject: [PATCH 2/4] docs(disk-hygiene): point the brief's guard-values note at its verified record Co-Authored-By: Claude Opus 5.5 --- .../skills/clean/reference/fan-out-worker-brief.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 b382eb3458..f74db14577 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 @@ -6,9 +6,9 @@ evidence only. ## Parent: fill the placeholders before spawning -A worker cannot expand `${...}` tokens (the guard rejects shell expansion) and never receives the -guard-values note, which a hook emits only when a person types the command. Before spawning, -replace ``, `` (the path `${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/` plus the +A worker cannot expand `${...}` tokens (the guard rejects shell expansion) and sees only its spawn +prompt, not the guard-values note in your context (how the note arrives: +[safety-model.md](safety-model.md), "Handing the values over up front"). Before spawning, replace ``, `` (the path `${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/` plus the engine filename), `` (the `data_root` value), ``, and, when it applies, `` with the literal absolute values you already hold from the guard-values note or the kill-switch probe in `SKILL.md`. From 3305b397443569634c239456beceb94de876f19e Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 30 Sep 2026 10:43:36 -0400 Subject: [PATCH 3/4] docs(disk-hygiene): drop the unverified worker-context claim from the brief Co-Authored-By: Claude Opus 5.5 --- .../skills/clean/reference/fan-out-worker-brief.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) 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 f74db14577..123fa1fc74 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 @@ -6,12 +6,11 @@ evidence only. ## Parent: fill the placeholders before spawning -A worker cannot expand `${...}` tokens (the guard rejects shell expansion) and sees only its spawn -prompt, not the guard-values note in your context (how the note arrives: -[safety-model.md](safety-model.md), "Handing the values over up front"). Before spawning, replace ``, `` (the path `${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/` plus the -engine filename), `` (the `data_root` value), ``, and, when it applies, -`` with the literal absolute values you already hold from the guard-values note or the -kill-switch probe in `SKILL.md`. +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 ``, `` (the +path `${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/` plus the engine filename), `` (the +`data_root` value), ``, and, when it applies, `` with the literal absolute +values you already hold from the guard-values note or the kill-switch probe in `SKILL.md`. ## Bash contract (instructions to you; the belt may not enforce them in a subagent) From 1516eebfd4ecf095a054ae090017d452a2ed5764 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 30 Sep 2026 11:32:25 -0400 Subject: [PATCH 4/4] fix(disk-hygiene): resolve changelog conflict and renumber to 0.32.1 Co-Authored-By: Claude Opus 5.5 --- plugins/disk-hygiene/.claude-plugin/plugin.json | 2 +- plugins/disk-hygiene/CHANGELOG.md | 7 ++----- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/plugins/disk-hygiene/.claude-plugin/plugin.json b/plugins/disk-hygiene/.claude-plugin/plugin.json index 92b5bd0c5c..2829d60352 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.32.0", + "version": "0.32.1", "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 cfd2ddc4cb..6fe9831d58 100644 --- a/plugins/disk-hygiene/CHANGELOG.md +++ b/plugins/disk-hygiene/CHANGELOG.md @@ -3,8 +3,7 @@ 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. -<<<<<<< HEAD -## [0.31.1] - 2026-09-30 +## [0.32.1] - 2026-09-30 ### Fixed @@ -14,8 +13,7 @@ All notable changes to the `disk-hygiene` plugin are documented here. Format fol 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. -||||||| 023026f4c -======= + ## [0.32.0] - 2026-09-30 ### Added @@ -41,7 +39,6 @@ All notable changes to the `disk-hygiene` plugin are documented here. Format fol ([#5517](https://github.com/melodic-software/claude-code-plugins/issues/5517)). The error now lists the top five top-level children by entry count so far, marks the one still being walked as a lower bound, and points at `--sizes-only` and then `--root-children --root-child ` or `--max-depth`. ->>>>>>> origin/main ## [0.31.0] - 2026-09-30