From 045c36cd18e4bbaf64706f8fc61e4b602cf2b278 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 12:25:04 -0400 Subject: [PATCH 01/21] feat(repo-hygiene): single pruned walk + dry-run manifest + apply summary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rework the clean skill's build/caches enumeration and apply flow as one change. #993 — the selective caches/build tiers ran ~10 unpruned full-tree `find` walks per repo; the `! -path` exclusions filtered output but did not `-prune`, so every walk re-descended `.git/`, `node_modules/`, and `.venv/`. A single pruned walk per tier (`clean_enumerate`) now prunes those three trees once and `-print`s all dir-name and file-glob matches, then classifies on the result list. Measured on a large .NET + node repo (Windows/NTFS): one pruned walk incl. `du` sizing ~17s vs a 10-walk unpruned dry-run that exceeded 10 min (killed). #995 — the dry-run now writes a session-scoped manifest (`\t\t` per eligible target), prints `Manifest: ` and `Summary: planned=N bytes=K` so the gate can state reclaimable space, and `--apply --manifest ` consumes it with a re-stat + re-classify staleness guard instead of re-walking. Resume = re-run the same command (already-gone entries are idempotent). `--apply` without a manifest builds one then applies it, preserving the standalone CLI contract; `--include-caches` folds the caches tier into the one build manifest (no subprocess). #1002 — each `--apply` ends with `Summary: removed=N failed=M bytes=K` and exits non-zero when failed>0, so a fleet sweep no longer needs per-log grepping. Cross-tier nested-target dedup drops any eligible path under an eligible ancestor so byte totals never double-count. scan.sh keeps the old walk pattern for now, tracked as TODO(#1011). Closes #993 Closes #995 Closes #1002 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- .../repo-hygiene/.claude-plugin/plugin.json | 2 +- plugins/repo-hygiene/CHANGELOG.md | 31 +++ plugins/repo-hygiene/skills/clean/SKILL.md | 8 +- .../skills/clean/context/action-router.md | 2 +- .../skills/clean/scripts/clean-build.sh | 103 ++++---- .../skills/clean/scripts/clean-build.test.sh | 37 +++ .../skills/clean/scripts/clean-caches.sh | 94 ++++--- .../skills/clean/scripts/clean-caches.test.sh | 55 ++++ .../skills/clean/scripts/lib/clean-common.sh | 238 ++++++++++++++++++ 9 files changed, 463 insertions(+), 107 deletions(-) diff --git a/plugins/repo-hygiene/.claude-plugin/plugin.json b/plugins/repo-hygiene/.claude-plugin/plugin.json index b2e2dd20566..5d95568b6bd 100644 --- a/plugins/repo-hygiene/.claude-plugin/plugin.json +++ b/plugins/repo-hygiene/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "repo-hygiene", - "version": "0.4.6", + "version": "0.5.0", "description": "Repo hygiene action-router: /repo-hygiene:clean sweeps reclaimable caches, build artifacts, and stale git metadata, and can realign the working tree to a fresh-pull state — dry-run-first, with destructive tiers gated behind explicit confirmation and a session-scoped destructive-command guard. Ecosystem targets are detected at runtime; secrets, runtime dependencies, and skill data are preserved by default.", "author": { "name": "Melodic Software", diff --git a/plugins/repo-hygiene/CHANGELOG.md b/plugins/repo-hygiene/CHANGELOG.md index 9b295e187ab..260f6e9e488 100644 --- a/plugins/repo-hygiene/CHANGELOG.md +++ b/plugins/repo-hygiene/CHANGELOG.md @@ -3,6 +3,37 @@ All notable changes to the `repo-hygiene` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.5.0] + +### Fixed + +- **Selective `caches`/`build` tiers now run a single pruned walk per tier instead + of ~10 unpruned full-tree `find` walks.** The old `! -path` exclusions filtered + output but did not `-prune`, so every per-pattern walk still descended `.git/`, + `node_modules/`, and `.venv/`. Enumeration now prunes those three trees once and + `-print`s all directory-name and file-glob matches in one walk, then applies + per-path protection on the result list. Measured on a large .NET + node repo + (Windows/NTFS): one pruned walk incl. `du` sizing ~17s vs a 10-walk unpruned + dry-run that exceeded 10 min (killed). (#993) + +### Added + +- **Dry-run writes a manifest and states reclaimable space; `--apply` consumes it + instead of re-walking.** The dry-run emits a session-scoped manifest + (`\t\t` per eligible target), prints its path + (`Manifest: `), and a `Summary: planned=N bytes=K` total so the + confirmation gate can state reclaimable bytes. `--apply --manifest ` + removes the manifest's entries with a re-stat + re-classify staleness guard (no + second walk); a killed apply resumes by re-running the same command + (already-gone entries are idempotent no-ops). `--apply` without a manifest + builds one then applies it, preserving the standalone CLI contract. With + `--include-caches` the caches tier folds into the same manifest — one walk per + tier, no subprocess. (#995) +- **Apply ends with a machine-parseable summary and fails closed.** Each `--apply` + run prints `Summary: removed=N failed=M bytes=K` (bytes actually reclaimed) and + exits non-zero when any removal fails, so a fleet sweep no longer requires + grepping every per-repo log to confirm success. (#1002) + ## [0.4.6] ### Fixed diff --git a/plugins/repo-hygiene/skills/clean/SKILL.md b/plugins/repo-hygiene/skills/clean/SKILL.md index 1ea64683658..de41efc0018 100644 --- a/plugins/repo-hygiene/skills/clean/SKILL.md +++ b/plugins/repo-hygiene/skills/clean/SKILL.md @@ -96,13 +96,17 @@ REPO_ROOT=$(git rev-parse --show-toplevel) `bash ${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/preflight.sh` — see [context/preflight.md](context/preflight.md). Interactive: `AskUserQuestion` before `--apply` when non-empty. Autonomous: abort. +#### Dry-run → confirm → apply manifest flow (caches / build) + +Both selective mutating tiers pay the filesystem walk **once**. `--dry-run` writes a session-scoped manifest and prints two machine-parseable lines: `Manifest: ` and `Summary: planned=N bytes=K` (bytes reclaimable — surface this in the confirmation gate). After the user confirms, apply the **same** manifest with `CLEAN_GUARD_ACK=1 … --apply --manifest ` — apply re-stats each entry (staleness guard) and removes it without re-walking, then prints `Summary: removed=N failed=M bytes=K` and exits non-zero if `failed>0`. A killed apply **resumes** by re-running the identical `--apply --manifest ` (already-removed entries are idempotent no-ops). Capture `` from the dry-run's `Manifest:` line and thread it through unchanged; the manifest is ephemeral (mktemp default), so pass `--manifest ` on the dry-run too if you need a stable location. + ### 2. Caches -`bash ${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/clean-caches.sh` — default `--dry-run`; `--apply` only after confirmation. +`bash ${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/clean-caches.sh` — default `--dry-run`; apply per the manifest flow above (`--apply --manifest `) only after confirmation. ### 3. Build (includes caches) -`bash ${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/clean-build.sh --include-caches` — default `--dry-run`; `--apply` after confirmation. +`bash ${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/clean-build.sh --include-caches` — default `--dry-run`; apply per the manifest flow above only after confirmation. `--include-caches` folds the caches tier into the one build manifest. ### 4. Git diff --git a/plugins/repo-hygiene/skills/clean/context/action-router.md b/plugins/repo-hygiene/skills/clean/context/action-router.md index 4841d908768..996a702eee9 100644 --- a/plugins/repo-hygiene/skills/clean/context/action-router.md +++ b/plugins/repo-hygiene/skills/clean/context/action-router.md @@ -53,7 +53,7 @@ Default when still unsure after one question: **`scan`** (safest). | Action | Pre-mutation step | User gate | | --- | --- | --- | | `scan` | Run `scan.sh` | None | -| `caches`, `build`, `all` | `preflight.sh` + tier scripts `--dry-run` | `AskUserQuestion` when preflight non-empty OR before `--apply` | +| `caches`, `build`, `all` | `preflight.sh` + tier scripts `--dry-run` (writes a manifest; emits `Manifest:` + `Summary: planned=N bytes=K`) | `AskUserQuestion` when preflight non-empty OR before `--apply` — surface the `bytes` reclaimable total; apply the same manifest (`--apply --manifest `), which emits `Summary: removed=N failed=M bytes=K` and exits non-zero on failure | | `git` | `git-prune.sh --dry-run`, `git-branch-audit.sh` | Before `--apply` prune; before any branch deletion | | `tree` | `git-tree-reset.sh --dry-run` (always) | **Mandatory** `AskUserQuestion` before `--apply` (surface `PreserveDeps`/`PreserveSecrets`/`AheadCount`); a non-zero `AheadCount` or exit 4 needs explicit unpushed-loss confirmation before `--allow-unpushed`; `--include-secrets` is UNRECOVERABLE — confirm separately; never autonomous | | `tree-batch` | `git-tree-reset-batch.sh --dry-run` (always) | **Mandatory** single batch-wide `AskUserQuestion` before `--apply` (surface the per-repo `Outcome`/`Reason`, `Summary`, and `UnmatchedSkip:`); one gate for the whole batch, never per repo; `--include-dirty` re-enables the data-loss vector — confirm separately naming the dirty repos, like `--include-secrets`; never autonomous. Detail: [git-tree-reset-batch.md](git-tree-reset-batch.md) | diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh index 2cdf4de7900..aa22e9866c3 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh @@ -2,7 +2,11 @@ # shellcheck disable=SC2154 # Remove build artifacts for the clean build tier (includes caches when --include-caches). # -# Default: --dry-run. --apply mutates. Optional dotnet clean driver when dotnet available. +# Default: --dry-run (writes a manifest of planned removals + reclaimable bytes). +# --apply consumes the manifest (re-stat staleness guard) and mutates disk. +# Optional dotnet clean driver when dotnet available. With --include-caches the +# caches tier shares this one manifest — a single pruned walk per tier, no +# subprocess. Enumeration/manifest/apply engine lives in lib/clean-common.sh. set -uo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" @@ -11,17 +15,27 @@ source "$SCRIPT_DIR/lib/clean-common.sh" DRY_RUN=1 INCLUDE_CACHES=0 +MANIFEST_ARG="" usage() { cat <<'EOF' clean-build.sh — remove build artifacts for the clean build tier. Usage: - clean-build.sh [--dry-run] [--apply] [--include-caches] [--help] + clean-build.sh [--dry-run] [--apply] [--include-caches] [--manifest PATH] [--help] -Default: --dry-run. --include-caches runs clean-caches.sh first. +Default: --dry-run — writes a manifest and prints its path + reclaimable total, +never mutates. --include-caches folds the caches tier into the same manifest. -Exit: 0 success; 1 not a git repo; 2 usage error. +Manifest flow (single walk paid once): + --dry-run writes a manifest, prints `Manifest: ` and + `Summary: planned=N bytes=K`. + --apply --manifest P consumes manifest P (re-stat guard, no re-walk); resume + = re-run the same command (already-gone entries skipped). + --apply without --manifest builds the manifest then applies it. + --manifest P on --dry-run writes to P instead of a mktemp path. + +Exit: 0 success; 1 not a git repo OR an apply had rm failures; 2 usage error. EOF } @@ -39,6 +53,10 @@ while [[ $# -gt 0 ]]; do INCLUDE_CACHES=1 shift ;; + --manifest) + MANIFEST_ARG="${2:-}" + shift 2 + ;; -h | --help) usage exit 0 @@ -58,16 +76,11 @@ fi cd "$REPO_ROOT" || exit 1 -CACHE_FLAG=--dry-run -[[ "$DRY_RUN" -eq 0 ]] && CACHE_FLAG=--apply - -if [[ "$INCLUDE_CACHES" -eq 1 ]]; then - bash "$SCRIPT_DIR/clean-caches.sh" "$CACHE_FLAG" -fi - # .NET clean driver — solution/project detected at runtime, never hardcoded. # Prefer a *.slnx, then *.sln, at the repo root; skip cleanly when none exists # or dotnet is unavailable (universal bin/obj globs below still remove output). +# Independent of the path manifest (it is an action, not a path): announced on +# dry-run, run on any --apply. DOTNET_SOLUTION="" if command -v dotnet >/dev/null 2>&1; then for cand in "$REPO_ROOT"/*.slnx "$REPO_ROOT"/*.sln; do @@ -88,47 +101,35 @@ if [[ -n "$DOTNET_SOLUTION" ]]; then fi fi -plan_remove() { - local abs="$1" - [[ -e "$abs" ]] || return 0 - if clean_path_is_protected "$REPO_ROOT" "$abs"; then - printf 'Skip (protected): %s\n' "${abs#"$REPO_ROOT"/}" - return 0 - fi - if clean_path_in_submodule "$REPO_ROOT" "$abs"; then - printf 'Skip (submodule): %s\n' "${abs#"$REPO_ROOT"/}" - return 0 - fi - if [[ -d "$abs" ]] && clean_dir_has_protected_descendant "$REPO_ROOT" "$abs"; then - printf 'Skip (protected descendant): %s\n' "${abs#"$REPO_ROOT"/}" - return 0 - fi - if [[ "$DRY_RUN" -eq 1 ]]; then - printf 'Planned remove: %s\n' "${abs#"$REPO_ROOT"/}" - else - rm -rf "$abs" - printf 'Removed: %s\n' "${abs#"$REPO_ROOT"/}" - fi -} +# --apply with a prebuilt manifest: skip enumeration entirely, just consume it. +if [[ "$DRY_RUN" -eq 0 && -n "$MANIFEST_ARG" ]]; then + clean_apply_manifest "$REPO_ROOT" "$MANIFEST_ARG" + printf 'Summary: removed=%s failed=%s bytes=%s\n' \ + "$CLEAN_REMOVED_COUNT" "$CLEAN_FAILED_COUNT" "$CLEAN_REMOVED_BYTES" + [[ "$CLEAN_FAILED_COUNT" -eq 0 ]] || exit 1 + exit 0 +fi -for name in "${CLEAN_BUILD_DIR_NAMES[@]}"; do - while IFS= read -r abs; do - [[ -z "$abs" ]] && continue - plan_remove "$abs" - done < <(find "$REPO_ROOT" -type d -name "$name" \ - ! -path "$CLEAN_FIND_EXCLUDE_GIT" \ - ! -path "$CLEAN_FIND_EXCLUDE_VENV" \ - ! -path "$CLEAN_FIND_EXCLUDE_NODE_MODULES" 2>/dev/null) -done +MANIFEST="$(clean_manifest_path "$MANIFEST_ARG")" -for glob in "${CLEAN_BUILD_FILE_GLOBS[@]}"; do - while IFS= read -r abs; do - [[ -z "$abs" ]] && continue - plan_remove "$abs" - done < <(find "$REPO_ROOT" -type f -name "$glob" \ - ! -path "$CLEAN_FIND_EXCLUDE_GIT" \ - ! -path "$CLEAN_FIND_EXCLUDE_VENV" \ - ! -path "$CLEAN_FIND_EXCLUDE_NODE_MODULES" 2>/dev/null) -done +if [[ "$INCLUDE_CACHES" -eq 1 ]]; then + mapfile -t CACHE_CANDS < <(clean_caches_candidates "$REPO_ROOT") + clean_add_candidates caches "${CACHE_CANDS[@]}" +fi + +mapfile -t BUILD_CANDS < <(clean_build_candidates "$REPO_ROOT") +clean_add_candidates build "${BUILD_CANDS[@]}" + +clean_plan "$REPO_ROOT" "$MANIFEST" "$DRY_RUN" + +if [[ "$DRY_RUN" -eq 1 ]]; then + printf 'Manifest: %s\n' "$MANIFEST" + printf 'Summary: planned=%s bytes=%s\n' "$CLEAN_PLANNED_COUNT" "$CLEAN_PLANNED_BYTES" + exit 0 +fi +clean_apply_manifest "$REPO_ROOT" "$MANIFEST" +printf 'Summary: removed=%s failed=%s bytes=%s\n' \ + "$CLEAN_REMOVED_COUNT" "$CLEAN_FAILED_COUNT" "$CLEAN_REMOVED_BYTES" +[[ "$CLEAN_FAILED_COUNT" -eq 0 ]] || exit 1 exit 0 diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-build.test.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-build.test.sh index f910f6ec59c..6bc8e67210d 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-build.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-build.test.sh @@ -48,6 +48,43 @@ out="$(run_build --apply)" assert_contains "submodule build dir skipped" "$out" "Skip (submodule):" assert_file_exists "submodule tracked file preserved" "$TEST_TMPDIR/repo/deps/sub/build/app.js" +# --- manifest / nested-dedup / apply-from-manifest / resume (#993, #995, #1002) --- +# Fresh repo so progressive mutation above does not bleed into these cases. +git init "$TEST_TMPDIR/b2" >/dev/null 2>&1 +git -C "$TEST_TMPDIR/b2" config user.email "t@example.com" +git -C "$TEST_TMPDIR/b2" config user.name "Test" +# bin/ with a nested obj/ — both are build dir names; the walk returns both but +# the ancestor (bin/) must collapse the descendant so the byte total is not +# double-counted and apply does not chase an already-removed path. +mkdir -p "$TEST_TMPDIR/b2/bin/obj" +echo a >"$TEST_TMPDIR/b2/bin/x.dll" +echo b >"$TEST_TMPDIR/b2/bin/obj/y.dll" +MANI="$TEST_TMPDIR/b2.manifest" + +run_b2() { + bash -c "cd '$TEST_TMPDIR/b2' && bash '$BUILD' $*" +} + +out="$(run_b2 --dry-run --manifest "$MANI")" +assert_contains "dry-run prints manifest path" "$out" "Manifest: $MANI" +assert_contains "nested dir deduped to one plan" "$out" "Summary: planned=1 bytes=" +mani_body="$(cat "$MANI")" +assert_contains "manifest carries bin" "$mani_body" "build" +assert_not_contains "nested obj not a separate entry" "$mani_body" "bin/obj" +assert_file_exists "dry-run does not mutate" "$TEST_TMPDIR/b2/bin/obj/y.dll" + +out="$(run_b2 --apply --manifest "$MANI")" +rc=$? +assert_contains "apply-from-manifest removes bin" "$out" "Removed: bin" +assert_contains "apply summary shape" "$out" "Summary: removed=1 failed=0 bytes=" +assert_exit "apply exit 0" 0 "$rc" +assert_file_absent "bin gone after apply" "$TEST_TMPDIR/b2/bin/x.dll" + +out="$(run_b2 --apply --manifest "$MANI")" +rc=$? +assert_contains "resume removes nothing" "$out" "Summary: removed=0 failed=0 bytes=0" +assert_exit "resume exit 0" 0 "$rc" + if [[ $FAILED -ne 0 ]]; then echo "FAILED: $FAILED test(s)" exit 1 diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh index 586ee7b1254..19ed240e3b7 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh @@ -2,8 +2,10 @@ # shellcheck disable=SC2154 # Remove tool/linter caches for the clean caches tier. # -# Default: --dry-run (print planned removals). --apply mutates disk. -# Respects protected paths and git-tracked files. +# Default: --dry-run (writes a manifest of planned removals + reclaimable bytes). +# --apply consumes the manifest (re-stat staleness guard) and mutates disk. +# Respects protected paths and git-tracked files. Enumeration/manifest/apply +# engine is shared with clean-build.sh in lib/clean-common.sh. set -uo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" @@ -11,17 +13,27 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" source "$SCRIPT_DIR/lib/clean-common.sh" DRY_RUN=1 +MANIFEST_ARG="" usage() { cat <<'EOF' clean-caches.sh — remove tool/linter caches for the clean caches tier. Usage: - clean-caches.sh [--dry-run] [--apply] [--help] + clean-caches.sh [--dry-run] [--apply] [--manifest PATH] [--help] -Default: --dry-run. --apply performs rm -rf on eligible targets. +Default: --dry-run — writes a manifest and prints its path + reclaimable total, +never mutates. --apply performs rm -rf on eligible targets. -Exit: 0 success; 1 not a git repo; 2 usage error. +Manifest flow (single walk paid once): + --dry-run writes a manifest, prints `Manifest: ` and + `Summary: planned=N bytes=K`. + --apply --manifest P consumes manifest P (re-stat guard, no re-walk); resume + = re-run the same command (already-gone entries skipped). + --apply without --manifest builds the manifest then applies it. + --manifest P on --dry-run writes to P instead of a mktemp path. + +Exit: 0 success; 1 not a git repo OR an apply had rm failures; 2 usage error. EOF } @@ -35,6 +47,10 @@ while [[ $# -gt 0 ]]; do DRY_RUN=0 shift ;; + --manifest) + MANIFEST_ARG="${2:-}" + shift 2 + ;; -h | --help) usage exit 0 @@ -54,55 +70,29 @@ fi cd "$REPO_ROOT" || exit 1 -plan_remove() { - local abs="$1" - [[ -e "$abs" ]] || return 0 - if clean_path_is_protected "$REPO_ROOT" "$abs"; then - printf 'Skip (protected): %s\n' "${abs#"$REPO_ROOT"/}" - return 0 - fi - if clean_path_in_submodule "$REPO_ROOT" "$abs"; then - printf 'Skip (submodule): %s\n' "${abs#"$REPO_ROOT"/}" - return 0 - fi - if [[ -d "$abs" ]] && clean_dir_has_protected_descendant "$REPO_ROOT" "$abs"; then - printf 'Skip (protected descendant): %s\n' "${abs#"$REPO_ROOT"/}" - return 0 - fi - if [[ "$DRY_RUN" -eq 1 ]]; then - printf 'Planned remove: %s\n' "${abs#"$REPO_ROOT"/}" - else - rm -rf "$abs" - printf 'Removed: %s\n' "${abs#"$REPO_ROOT"/}" - fi -} - -for rel in "${CLEAN_CACHE_EXPLICIT[@]}"; do - plan_remove "$REPO_ROOT/$rel" -done +# --apply with a prebuilt manifest: skip enumeration entirely, just consume it. +if [[ "$DRY_RUN" -eq 0 && -n "$MANIFEST_ARG" ]]; then + clean_apply_manifest "$REPO_ROOT" "$MANIFEST_ARG" + printf 'Summary: removed=%s failed=%s bytes=%s\n' \ + "$CLEAN_REMOVED_COUNT" "$CLEAN_FAILED_COUNT" "$CLEAN_REMOVED_BYTES" + [[ "$CLEAN_FAILED_COUNT" -eq 0 ]] || exit 1 + exit 0 +fi -for rel in "${CLEAN_CACHE_EXPLICIT_FILES[@]}"; do - plan_remove "$REPO_ROOT/$rel" -done +MANIFEST="$(clean_manifest_path "$MANIFEST_ARG")" -for name in "${CLEAN_CACHE_FIND_DIR_NAMES[@]}"; do - while IFS= read -r abs; do - [[ -z "$abs" ]] && continue - plan_remove "$abs" - done < <(find "$REPO_ROOT" -type d -name "$name" \ - ! -path "$CLEAN_FIND_EXCLUDE_GIT" \ - ! -path "$CLEAN_FIND_EXCLUDE_VENV" \ - ! -path "$CLEAN_FIND_EXCLUDE_NODE_MODULES" 2>/dev/null) -done +mapfile -t CACHE_CANDS < <(clean_caches_candidates "$REPO_ROOT") +clean_add_candidates caches "${CACHE_CANDS[@]}" +clean_plan "$REPO_ROOT" "$MANIFEST" "$DRY_RUN" -for glob in "${CLEAN_CACHE_FIND_FILE_GLOBS[@]}"; do - while IFS= read -r abs; do - [[ -z "$abs" ]] && continue - plan_remove "$abs" - done < <(find "$REPO_ROOT" -type f -name "$glob" \ - ! -path "$CLEAN_FIND_EXCLUDE_GIT" \ - ! -path "$CLEAN_FIND_EXCLUDE_VENV" \ - ! -path "$CLEAN_FIND_EXCLUDE_NODE_MODULES" 2>/dev/null) -done +if [[ "$DRY_RUN" -eq 1 ]]; then + printf 'Manifest: %s\n' "$MANIFEST" + printf 'Summary: planned=%s bytes=%s\n' "$CLEAN_PLANNED_COUNT" "$CLEAN_PLANNED_BYTES" + exit 0 +fi +clean_apply_manifest "$REPO_ROOT" "$MANIFEST" +printf 'Summary: removed=%s failed=%s bytes=%s\n' \ + "$CLEAN_REMOVED_COUNT" "$CLEAN_FAILED_COUNT" "$CLEAN_REMOVED_BYTES" +[[ "$CLEAN_FAILED_COUNT" -eq 0 ]] || exit 1 exit 0 diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh index 9ff36a5b63c..20df57360e7 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh @@ -35,6 +35,61 @@ assert_file_absent "cache deleted after apply" "$TEST_TMPDIR/repo/.pytest_cache/ out="$(run_clean --dry-run)" assert_not_contains "node_modules skipped" "$out" "node_modules" +# --- manifest / summary / apply-from-manifest / resume (issues #995, #1002) --- +# Fresh repo so progressive mutation above does not bleed into these cases. +git init "$TEST_TMPDIR/r2" >/dev/null 2>&1 +git -C "$TEST_TMPDIR/r2" config user.email "t@example.com" +git -C "$TEST_TMPDIR/r2" config user.name "Test" +mkdir -p "$TEST_TMPDIR/r2/.pytest_cache" +echo x >"$TEST_TMPDIR/r2/.pytest_cache/x" +MANI="$TEST_TMPDIR/r2.manifest" + +run_r2() { + bash -c "cd '$TEST_TMPDIR/r2' && bash '$CLEAN' $*" +} + +out="$(run_r2 --dry-run --manifest "$MANI")" +assert_contains "dry-run prints manifest path" "$out" "Manifest: $MANI" +assert_contains "dry-run planned summary" "$out" "Summary: planned=1 bytes=" +assert_file_exists "manifest written" "$MANI" +mani_body="$(cat "$MANI")" +assert_contains "manifest tags class+path" "$mani_body" "caches" +assert_contains "manifest carries the cache path" "$mani_body" ".pytest_cache" +assert_file_exists "dry-run does not mutate" "$TEST_TMPDIR/r2/.pytest_cache/x" + +out="$(run_r2 --apply --manifest "$MANI")" +rc=$? +assert_contains "apply-from-manifest removes" "$out" "Removed: .pytest_cache" +assert_contains "apply summary shape" "$out" "Summary: removed=1 failed=0 bytes=" +assert_exit "apply exit 0" 0 "$rc" +assert_file_absent "cache gone after apply" "$TEST_TMPDIR/r2/.pytest_cache/x" + +# Resume: re-applying the spent manifest is idempotent — nothing removed, no +# failures, clean exit (a killed apply just re-runs the same command). +out="$(run_r2 --apply --manifest "$MANI")" +rc=$? +assert_contains "resume removes nothing" "$out" "Summary: removed=0 failed=0 bytes=0" +assert_exit "resume exit 0" 0 "$rc" + +# rm-failure accounting: a manifest entry rm cannot remove must count failed and +# force a non-zero exit. Deterministic only where the FS enforces a write-denied +# parent (real POSIX / Linux CI); Cygwin/MSYS ignores it, so probe and skip. +mkdir -p "$TEST_TMPDIR/r2/.mypy_cache/inner" +echo y >"$TEST_TMPDIR/r2/.mypy_cache/inner/y" +chmod a-w "$TEST_TMPDIR/r2/.mypy_cache" 2>/dev/null || true +if rm -rf "$TEST_TMPDIR/r2/.mypy_cache/inner" 2>/dev/null; then + chmod u+w "$TEST_TMPDIR/r2/.mypy_cache" 2>/dev/null || true + rm -rf "$TEST_TMPDIR/r2/.mypy_cache" 2>/dev/null || true + skip_case "rm-failure accounting — FS does not enforce write-denied parent here" +else + printf 'caches\t4096\t.mypy_cache/inner\n' >"$TEST_TMPDIR/r2.fail.manifest" + out="$(run_r2 --apply --manifest "$TEST_TMPDIR/r2.fail.manifest")" + rc=$? + assert_contains "failure counted" "$out" "Summary: removed=0 failed=1 bytes=0" + assert_exit "apply exits non-zero on failure" 1 "$rc" + chmod u+w "$TEST_TMPDIR/r2/.mypy_cache" 2>/dev/null || true +fi + if [[ $FAILED -ne 0 ]]; then echo "FAILED: $FAILED test(s)" exit 1 diff --git a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh index 123682df436..2737f42a7af 100644 --- a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh @@ -222,3 +222,241 @@ clean_branch_matches_protected_pattern() { return 1 } + +# --- enumeration + manifest engine (issues #993 / #995 / #1002) -------------- +# +# The selective build/caches tiers formerly ran one unpruned full-tree `find` +# per pattern (~10 walks/repo); the `! -path` exclusions filtered output but did +# not `-prune`, so every walk still descended `.git/`, `node_modules/`, `.venv/`. +# The engine below replaces that with ONE pruned walk per tier that never +# descends those three trees, then classifies, sizes, and manifests the result. +# Measured on a large .NET + node repo (Windows/NTFS): one pruned walk incl. `du` +# sizing ~17s vs a 10-walk unpruned dry-run that exceeded 10 min (killed). +# +# scan.sh still uses the old per-pattern unpruned walks — TODO(#1011) migrate it +# onto clean_enumerate (kept out of #993's named scope). + +# Single pruned walk. Prunes .git / node_modules / .venv (never descended), +# then `-print`s directory-name and file-glob matches. Tier-agnostic: +# clean_enumerate ROOT dirname… -- fileglob… +# `du -sk` (POSIX) handles sizing downstream; GNU-only `find -printf` is avoided +# for BSD/macOS portability. +clean_enumerate() { + local root="$1" + shift + local -a dir_names=() file_globs=() + local bucket=dirs tok + for tok in "$@"; do + if [[ "$tok" == "--" ]]; then + bucket=globs + continue + fi + if [[ "$bucket" == dirs ]]; then dir_names+=("$tok"); else file_globs+=("$tok"); fi + done + + local -a args=("$root" '(' -name .git -o -name node_modules -o -name .venv ')' -prune -o '(') + local -a match=() + local i + if ((${#dir_names[@]})); then + match+=(-type d '(') + for i in "${!dir_names[@]}"; do + ((i)) && match+=(-o) + match+=(-name "${dir_names[$i]}") + done + match+=(')') + fi + if ((${#file_globs[@]})); then + ((${#dir_names[@]})) && match+=(-o) + match+=(-type f '(') + for i in "${!file_globs[@]}"; do + ((i)) && match+=(-o) + match+=(-name "${file_globs[$i]}") + done + match+=(')') + fi + args+=("${match[@]}" ')' -print) + find "${args[@]}" 2>/dev/null +} + +# Candidate absolute paths for the caches / build tiers (explicit repo-root +# paths + one pruned walk). SSOT for both the standalone scripts and the +# build-tier's --include-caches path, so the two never drift. +clean_caches_candidates() { + local root="$1" rel + for rel in "${CLEAN_CACHE_EXPLICIT[@]}"; do printf '%s\n' "$root/$rel"; done + for rel in "${CLEAN_CACHE_EXPLICIT_FILES[@]}"; do printf '%s\n' "$root/$rel"; done + clean_enumerate "$root" "${CLEAN_CACHE_FIND_DIR_NAMES[@]}" -- "${CLEAN_CACHE_FIND_FILE_GLOBS[@]}" +} + +clean_build_candidates() { + local root="$1" + clean_enumerate "$root" "${CLEAN_BUILD_DIR_NAMES[@]}" -- "${CLEAN_BUILD_FILE_GLOBS[@]}" +} + +# Return 0 when an existing absolute path is eligible for removal; otherwise +# print the reason as a `Skip (…)` line on stdout and return 1. This same gate +# runs at both dry-run (building the manifest) and --apply (the staleness guard: +# a path that became protected between the two is not removed). Assumes the path +# exists — callers handle absence (a walk match always exists; an already-removed +# manifest entry is idempotent-success, handled in clean_apply_manifest). +clean_target_eligible() { + local root="$1" abs="$2" rel="${2#"$1"/}" + if clean_path_is_protected "$root" "$abs"; then + printf 'Skip (protected): %s\n' "$rel" + return 1 + fi + if clean_path_in_submodule "$root" "$abs"; then + printf 'Skip (submodule): %s\n' "$rel" + return 1 + fi + if [[ -d "$abs" ]] && clean_dir_has_protected_descendant "$root" "$abs"; then + printf 'Skip (protected descendant): %s\n' "$rel" + return 1 + fi + return 0 +} + +# Class-tagged candidate accumulators, consumed by clean_plan. Reset per run. +CLEAN_CAND_ABS=() +CLEAN_CAND_CLASS=() + +# Dry-run / summary accumulators (bytes are raw bytes — same unit scan.sh reports +# as `Total reclaimable`). +CLEAN_PLANNED_COUNT=0 +CLEAN_PLANNED_BYTES=0 +CLEAN_REMOVED_COUNT=0 +CLEAN_FAILED_COUNT=0 +CLEAN_REMOVED_BYTES=0 + +# clean_add_candidates CLASS abs… — tag each candidate path with its manifest +# class (caches|build) for the shared dedup + sizing pass. +clean_add_candidates() { + local class="$1" p + shift + for p in "$@"; do + [[ -n "$p" ]] || continue + CLEAN_CAND_ABS+=("$p") + CLEAN_CAND_CLASS+=("$class") + done +} + +clean_human_size() { + local b="$1" + if ((b >= 1073741824)); then + awk -v b="$b" 'BEGIN { printf "%.1f GB", b / 1073741824 }' + elif ((b >= 1048576)); then + awk -v b="$b" 'BEGIN { printf "%.1f MB", b / 1048576 }' + elif ((b >= 1024)); then + awk -v b="$b" 'BEGIN { printf "%.1f KB", b / 1024 }' + else + printf '%s B' "$b" + fi +} + +# Classify every accumulated candidate, drop any eligible path nested under an +# eligible ancestor (`du` of the ancestor already counts it and `rm -rf` already +# removes it — otherwise the byte total double-counts and apply hits a spent +# path), size the survivors with a SINGLE batched `du` (one subprocess for the +# whole set — process creation is slow on Windows/MSYS), append +# `\t\t` manifest lines, and — when announce=1 (dry-run) +# — print `Planned remove:` lines. Accumulates CLEAN_PLANNED_COUNT / _BYTES. +# clean_plan ROOT MANIFEST ANNOUNCE +clean_plan() { + local root="$1" manifest="$2" announce="$3" + local -a elig_abs=() elig_class=() + local i abs class skip + # Classify first (a dir skipped for a protected descendant must not shadow a + # clean nested target below it), dedup second. + for i in "${!CLEAN_CAND_ABS[@]}"; do + abs="${CLEAN_CAND_ABS[$i]}" + class="${CLEAN_CAND_CLASS[$i]}" + [[ -e "$abs" ]] || continue + if skip="$(clean_target_eligible "$root" "$abs")"; then + elig_abs+=("$abs") + elig_class+=("$class") + else + [[ -n "$skip" ]] && printf '%s\n' "$skip" + fi + done + + local -a surv_abs=() surv_class=() + local a b nested j + for i in "${!elig_abs[@]}"; do + a="${elig_abs[$i]}" + nested=0 + for j in "${!elig_abs[@]}"; do + [[ "$i" == "$j" ]] && continue + b="${elig_abs[$j]}" + # Anchor on '/' so `build` never swallows a sibling `buildstuff`. + if [[ "$a" == "$b"/* ]]; then + nested=1 + break + fi + done + ((nested)) && continue + surv_abs+=("$a") + surv_class+=("${elig_class[$i]}") + done + ((${#surv_abs[@]})) || return 0 + + local -A size_of=() + local kb path + while IFS=$'\t' read -r kb path; do + [[ -n "$path" ]] || continue + size_of["$path"]=$((kb * 1024)) + done < <(du -sk "${surv_abs[@]}" 2>/dev/null) + + local bytes rel + for i in "${!surv_abs[@]}"; do + abs="${surv_abs[$i]}" + rel="${abs#"$root"/}" + bytes="${size_of[$abs]:-0}" + printf '%s\t%s\t%s\n' "${surv_class[$i]}" "$bytes" "$rel" >>"$manifest" + ((announce)) && printf 'Planned remove: %s (%s)\n' "$rel" "$(clean_human_size "$bytes")" + CLEAN_PLANNED_COUNT=$((CLEAN_PLANNED_COUNT + 1)) + CLEAN_PLANNED_BYTES=$((CLEAN_PLANNED_BYTES + bytes)) + done +} + +# Consume a manifest: re-stat + re-run the protection gate per entry (the +# staleness guard), `rm -rf` survivors, and accumulate outcomes. An entry whose +# path is already gone is idempotent success (resume) — counted neither removed +# nor failed. A path that became protected since the dry-run is skipped (its +# `Skip` line re-emitted), not removed. CLEAN_FAILED_COUNT counts only genuine +# `rm` failures (locked / Unremovable). +# clean_apply_manifest ROOT MANIFEST +clean_apply_manifest() { + local root="$1" manifest="$2" + local class bytes rel abs skip + while IFS=$'\t' read -r class bytes rel; do + [[ -n "$rel" ]] || continue + abs="$root/$rel" + [[ -e "$abs" ]] || continue + if ! skip="$(clean_target_eligible "$root" "$abs")"; then + [[ -n "$skip" ]] && printf '%s\n' "$skip" + continue + fi + if rm -rf "$abs" 2>/dev/null; then + printf 'Removed: %s\n' "$rel" + CLEAN_REMOVED_COUNT=$((CLEAN_REMOVED_COUNT + 1)) + CLEAN_REMOVED_BYTES=$((CLEAN_REMOVED_BYTES + bytes)) + else + printf 'Unremovable: %s\n' "$rel" >&2 + CLEAN_FAILED_COUNT=$((CLEAN_FAILED_COUNT + 1)) + fi + done <"$manifest" +} + +# clean_manifest_path [--manifest VALUE] → resolve/create the session manifest. +# Honors an explicit path (agent passes dry-run's path back at --apply); else +# mktemp a session-scoped file. Truncates so a reused path starts clean. +clean_manifest_path() { + local explicit="$1" path + if [[ -n "$explicit" ]]; then + path="$explicit" + else + path="$(mktemp 2>/dev/null)" || path="${TMPDIR:-/tmp}/clean-manifest.$$" + fi + : >"$path" + printf '%s' "$path" +} From 8c845e5e1ddd599f3de9ae8a6f0136d0635dc3ac Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 12:34:07 -0400 Subject: [PATCH 02/21] test(repo-hygiene): pin manifest line format and --include-caches folding The manifest is a consumed contract (#994 parses it), so assert the exact classbytesrelpath shape per tier rather than substrings, and cover --include-caches folding both a build and a caches entry into one manifest. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- .../skills/clean/scripts/clean-build.test.sh | 24 +++++++++++++++---- .../skills/clean/scripts/clean-caches.test.sh | 9 +++++-- 2 files changed, 27 insertions(+), 6 deletions(-) diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-build.test.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-build.test.sh index 6bc8e67210d..3275c1e338c 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-build.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-build.test.sh @@ -59,26 +59,42 @@ git -C "$TEST_TMPDIR/b2" config user.name "Test" mkdir -p "$TEST_TMPDIR/b2/bin/obj" echo a >"$TEST_TMPDIR/b2/bin/x.dll" echo b >"$TEST_TMPDIR/b2/bin/obj/y.dll" +# A caches-tier target too, to prove --include-caches folds both classes into +# the one build manifest (no clean-caches.sh subprocess). +mkdir -p "$TEST_TMPDIR/b2/.pytest_cache" +echo c >"$TEST_TMPDIR/b2/.pytest_cache/c" MANI="$TEST_TMPDIR/b2.manifest" run_b2() { bash -c "cd '$TEST_TMPDIR/b2' && bash '$BUILD' $*" } -out="$(run_b2 --dry-run --manifest "$MANI")" +out="$(run_b2 --dry-run --include-caches --manifest "$MANI")" assert_contains "dry-run prints manifest path" "$out" "Manifest: $MANI" -assert_contains "nested dir deduped to one plan" "$out" "Summary: planned=1 bytes=" +# bin/ (nested obj/ deduped) + .pytest_cache = 2 planned. +assert_contains "nested dir deduped, caches folded in" "$out" "Summary: planned=2 bytes=" mani_body="$(cat "$MANI")" -assert_contains "manifest carries bin" "$mani_body" "build" +# Structural pin (consumed contract, #994): exact classbytespath per tier. +if grep -qE "^build"$'\t'"[0-9]+"$'\t'"bin$" "$MANI"; then + pass "build line is classbytespath" +else + fail "build manifest line format" "buildbin" "$mani_body" +fi +if grep -qE "^caches"$'\t'"[0-9]+"$'\t'"\.pytest_cache$" "$MANI"; then + pass "caches line folded into build manifest" +else + fail "folded caches manifest line" "caches.pytest_cache" "$mani_body" +fi assert_not_contains "nested obj not a separate entry" "$mani_body" "bin/obj" assert_file_exists "dry-run does not mutate" "$TEST_TMPDIR/b2/bin/obj/y.dll" out="$(run_b2 --apply --manifest "$MANI")" rc=$? assert_contains "apply-from-manifest removes bin" "$out" "Removed: bin" -assert_contains "apply summary shape" "$out" "Summary: removed=1 failed=0 bytes=" +assert_contains "apply summary shape" "$out" "Summary: removed=2 failed=0 bytes=" assert_exit "apply exit 0" 0 "$rc" assert_file_absent "bin gone after apply" "$TEST_TMPDIR/b2/bin/x.dll" +assert_file_absent "folded cache gone after apply" "$TEST_TMPDIR/b2/.pytest_cache/c" out="$(run_b2 --apply --manifest "$MANI")" rc=$? diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh index 20df57360e7..fd599db2b2d 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh @@ -53,8 +53,13 @@ assert_contains "dry-run prints manifest path" "$out" "Manifest: $MANI" assert_contains "dry-run planned summary" "$out" "Summary: planned=1 bytes=" assert_file_exists "manifest written" "$MANI" mani_body="$(cat "$MANI")" -assert_contains "manifest tags class+path" "$mani_body" "caches" -assert_contains "manifest carries the cache path" "$mani_body" ".pytest_cache" +# Structural pin: the manifest is a consumed contract (#994 parses it), so +# assert the exact \t\t shape, not just substrings. +if grep -qE "^caches"$'\t'"[0-9]+"$'\t'"\.pytest_cache$" "$MANI"; then + pass "manifest line is classbytespath" +else + fail "manifest line format" "caches.pytest_cache" "$mani_body" +fi assert_file_exists "dry-run does not mutate" "$TEST_TMPDIR/r2/.pytest_cache/x" out="$(run_r2 --apply --manifest "$MANI")" From d8e8c98d6de5864824c4acfb118723d51feff9fc Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 12:45:02 -0400 Subject: [PATCH 03/21] feat(repo-hygiene): drop the dotnet clean driver from clean-build MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `clean-build.sh --apply` ran `dotnet clean ` before removing bin/obj wholesale, but the universal artifact removal already deletes everything the driver would — running it first was pure overhead: a full MSBuild evaluation (minutes on a large solution) that also re-created obj/ evaluation artifacts. One walk + rm is strictly faster and equally complete. Removes the driver and its `Planned: dotnet clean …` (dry-run) / `DRIVER_FAILED:` (apply) output markers, and the now-stale driver references in the config/ecosystem/README docs. Closes #999 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- plugins/repo-hygiene/CHANGELOG.md | 10 ++++++ plugins/repo-hygiene/README.md | 2 +- .../skills/clean/context/action-router.md | 2 +- .../skills/clean/reference/cleanup-config.md | 4 +-- .../skills/clean/reference/ecosystems.md | 4 +-- .../skills/clean/scripts/clean-build.sh | 35 +++++-------------- .../skills/clean/scripts/lib/cleanup-paths.sh | 6 ++-- 7 files changed, 26 insertions(+), 37 deletions(-) diff --git a/plugins/repo-hygiene/CHANGELOG.md b/plugins/repo-hygiene/CHANGELOG.md index 260f6e9e488..b3838e65226 100644 --- a/plugins/repo-hygiene/CHANGELOG.md +++ b/plugins/repo-hygiene/CHANGELOG.md @@ -34,6 +34,16 @@ All notable changes to the `repo-hygiene` plugin are documented here. Format fol exits non-zero when any removal fails, so a fleet sweep no longer requires grepping every per-repo log to confirm success. (#1002) +### Removed + +- **The `dotnet clean` build-system driver.** `clean-build.sh` no longer runs + `dotnet clean ` before removing `bin/`/`obj/`. The universal artifact + removal already deletes everything the driver would, so running it first was + pure overhead — a full MSBuild evaluation (minutes on a large solution) that + also re-created `obj/` evaluation artifacts. One walk + `rm` is strictly faster + and equally complete. Removes the `Planned: dotnet clean …` (dry-run) and + `DRIVER_FAILED:` (apply) output markers. (#999) + ## [0.4.6] ### Fixed diff --git a/plugins/repo-hygiene/README.md b/plugins/repo-hygiene/README.md index c904d52e813..3c3a8ab0bea 100644 --- a/plugins/repo-hygiene/README.md +++ b/plugins/repo-hygiene/README.md @@ -17,7 +17,7 @@ the conversation, or presents a menu and falls back to the safe `scan`. |--------|--------------|------| | `scan` | Read-only inventory of reclaimable caches, build output, and stale git refs | Safe | | `caches` | Remove tool / linter caches (`.pytest_cache`, `.ruff_cache`, `__pycache__`, `.turbo`, `.vs`, …) | Low | -| `build` | Remove build artifacts (`bin`/`obj`/`build`/`dist`/`out`/`target`/`TestResults`, `*.binlog`), includes caches; runs a runtime-detected `dotnet clean` when a `*.slnx`/`*.sln` and `dotnet` are present | Low | +| `build` | Remove build artifacts (`bin`/`obj`/`build`/`dist`/`out`/`target`/`TestResults`, `*.binlog`), includes caches | Low | | `git` | Prune stale worktree/remote metadata and gc; audit branches (merged / PR-merged / stale) and delete only on per-branch opt-in | Low | | `tree` | Reset the working tree like a fresh pull — `git reset --hard` + `git clean -fdx` | **Destructive** | | `tree-batch` | Run `tree` across many repos (`ghq list`, a glob, or an explicit list) behind one confirmation gate, with a separator-agnostic skip list and a dirty-by-default guard | **Destructive** | diff --git a/plugins/repo-hygiene/skills/clean/context/action-router.md b/plugins/repo-hygiene/skills/clean/context/action-router.md index 996a702eee9..fe7a2e12e78 100644 --- a/plugins/repo-hygiene/skills/clean/context/action-router.md +++ b/plugins/repo-hygiene/skills/clean/context/action-router.md @@ -8,7 +8,7 @@ SKILL.md carries the action table headline; this file carries alias resolution, | --- | --- | --- | --- | --- | | `scan` | "Show what's reclaimable" | Read-only inventory | Safe | N/A (no mutation) | | `caches` | "Clear tool and linter caches" | `.pytest_cache/`, `.ruff_cache/`, `__pycache__/`, … | Low | **Never** | -| `build` | "Clear build output and logs" | `bin/`, `obj/`, `dist/`, dotnet clean driver, … | Low | **Never** | +| `build` | "Clear build output and logs" | `bin/`, `obj/`, `dist/`, `*.binlog`, … | Low | **Never** | | `git` | "Prune stale git metadata" | `worktree prune`, `remote prune`, `gc`, branch audit | Low | Prune/gc only after user OK; branch delete always opt-in | | `tree` | "Reset working tree like a fresh pull" | `fetch` + `reset --hard` upstream + `clean -fdx` (default-preserve secrets/deps/skill-data; `--include-deps` / `--include-secrets` to widen) | **Destructive** | **Never** | | `tree-batch` | "Reset all my repos like a fresh pull" | `tree` across a repo set behind one gate; separator-agnostic skip list; dirty/unpushed skipped unless `--include-dirty` | **Destructive** | **Never** | diff --git a/plugins/repo-hygiene/skills/clean/reference/cleanup-config.md b/plugins/repo-hygiene/skills/clean/reference/cleanup-config.md index 614a0fe0e75..8eec1743106 100644 --- a/plugins/repo-hygiene/skills/clean/reference/cleanup-config.md +++ b/plugins/repo-hygiene/skills/clean/reference/cleanup-config.md @@ -25,9 +25,7 @@ Universal artifact directory globs: - `**/bin/`, `**/obj/`, `**/build/`, `**/dist/`, `**/out/`, `**/target/`, `**/TestResults/`, `**/*.binlog` -Build-system clean driver (run before the glob removal in Workflow §3): - -- .NET: `clean-build.sh` detects a `*.slnx` or `*.sln` at the repo root at runtime and runs `dotnet clean -v q`. If `dotnet` is unavailable or no solution is present, the driver is skipped; the universal globs still remove `bin/`/`obj/` directly. +No build-system clean driver (e.g. `dotnet clean`): the universal artifact globs above already remove every output such a driver would delete, so running one first is pure overhead — a full MSBuild evaluation (minutes on a large solution) that also re-creates `obj/` evaluation artifacts. One walk + rm is strictly faster and equally complete. App-specific runtime output (application logs written outside the universal artifact dirs) is **not** swept generically — no portable path exists. A consumer whose app writes logs to a non-artifact directory reclaims them through the `tree` tier (they are untracked/ignored) or their own gitignore + tooling. diff --git a/plugins/repo-hygiene/skills/clean/reference/ecosystems.md b/plugins/repo-hygiene/skills/clean/reference/ecosystems.md index e3d319d6e94..26dcd974440 100644 --- a/plugins/repo-hygiene/skills/clean/reference/ecosystems.md +++ b/plugins/repo-hygiene/skills/clean/reference/ecosystems.md @@ -8,13 +8,13 @@ Per-ecosystem teaching tables for the clean skill. Each entry includes command s | Target | Tier | Command | Safety | Regen cost | |--------|------|---------|--------|-----------| -| bin/, obj/ | build | `dotnet clean -v q` then `find . -type d \( -name bin -o -name obj \) -not -path '*/.git/*' -not -path '*/.venv/*' -not -path '*/node_modules/*' -exec rm -rf {} +` | Safe | `dotnet build` (~15s) | +| bin/, obj/ | build | `find . \( -name .git -o -name node_modules -o -name .venv \) -prune -o -type d \( -name bin -o -name obj \) -print` then `rm -rf` each eligible path | Safe | `dotnet build` (~15s) | | TestResults/ | build | `find . -type d -name TestResults -exec rm -rf {} +` | Safe | `dotnet test` | | *.binlog | build | `find . -name '*.binlog' -delete` | Safe | Intentional capture only | | App log dirs | build | Not swept generically (no portable path) — reclaim via the `tree` action | Safe | App sink creates on next run | | `*.csproj.user` / `*.suo` | NEVER | — | Protected | VS / IDE debug profile preference | -The `.NET` solution/project is detected at runtime (`*.slnx` then `*.sln` at repo root); the driver is skipped when `dotnet` or a solution is absent. +No build-system clean driver runs (e.g. `dotnet clean`): the single pruned walk + `rm -rf` already removes every `bin/`/`obj/` output such a driver would, so invoking one first is pure overhead (#999). ## Python diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh index aa22e9866c3..97b65813a0c 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh @@ -4,9 +4,9 @@ # # Default: --dry-run (writes a manifest of planned removals + reclaimable bytes). # --apply consumes the manifest (re-stat staleness guard) and mutates disk. -# Optional dotnet clean driver when dotnet available. With --include-caches the -# caches tier shares this one manifest — a single pruned walk per tier, no -# subprocess. Enumeration/manifest/apply engine lives in lib/clean-common.sh. +# With --include-caches the caches tier shares this one manifest — a single +# pruned walk per tier, no subprocess. Enumeration/manifest/apply engine lives +# in lib/clean-common.sh. set -uo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" @@ -76,30 +76,11 @@ fi cd "$REPO_ROOT" || exit 1 -# .NET clean driver — solution/project detected at runtime, never hardcoded. -# Prefer a *.slnx, then *.sln, at the repo root; skip cleanly when none exists -# or dotnet is unavailable (universal bin/obj globs below still remove output). -# Independent of the path manifest (it is an action, not a path): announced on -# dry-run, run on any --apply. -DOTNET_SOLUTION="" -if command -v dotnet >/dev/null 2>&1; then - for cand in "$REPO_ROOT"/*.slnx "$REPO_ROOT"/*.sln; do - if [[ -f "$cand" ]]; then - DOTNET_SOLUTION="$cand" - break - fi - done -fi -if [[ -n "$DOTNET_SOLUTION" ]]; then - DOTNET_DRIVER="dotnet clean \"$DOTNET_SOLUTION\" -v q" - if [[ "$DRY_RUN" -eq 1 ]]; then - printf 'Planned: %s\n' "$DOTNET_DRIVER" - else - if ! dotnet clean "$DOTNET_SOLUTION" -v q 2>/dev/null; then - printf 'DRIVER_FAILED: %s\n' "$DOTNET_DRIVER" >&2 - fi - fi -fi +# No build-system clean driver (e.g. `dotnet clean`): the universal bin/obj/… +# removal below already deletes everything such a driver would, and running one +# first is pure overhead (full MSBuild evaluation, minutes on a large solution) +# that also re-creates obj/ evaluation artifacts. One walk + rm is strictly +# faster and equally complete (#999). # --apply with a prebuilt manifest: skip enumeration entirely, just consume it. if [[ "$DRY_RUN" -eq 0 && -n "$MANIFEST_ARG" ]]; then diff --git a/plugins/repo-hygiene/skills/clean/scripts/lib/cleanup-paths.sh b/plugins/repo-hygiene/skills/clean/scripts/lib/cleanup-paths.sh index da42bc6cc49..ffeea048772 100644 --- a/plugins/repo-hygiene/skills/clean/scripts/lib/cleanup-paths.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/lib/cleanup-paths.sh @@ -47,9 +47,9 @@ CLEAN_BUILD_FILE_GLOBS=( '*.binlog' ) -# build — .NET clean driver. The solution/project file is detected at runtime by -# clean-build.sh (any *.slnx / *.sln at the repo root), never hardcoded — the -# universal bin/obj globs above remove output directly when dotnet is absent. +# build — no build-system clean driver: the universal bin/obj globs above remove +# every output a driver like `dotnet clean` would, so running one first is pure +# overhead (#999). # git — safe prune mutations GIT_PRUNE_OPS=( From 9a534d2cb5c6027e6748d19eef8baaec1b3ff04c Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 12:54:00 -0400 Subject: [PATCH 04/21] style(repo-hygiene): drop issue-refs and TODO marker from code comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The repo's comment-hygiene gate forbids tracker/issue references and TODO markers in code comments; version control, the CHANGELOG, and the tracker own that history. Strips the `(#NNN)` refs and the scan.sh `TODO(#…)` note from the clean scripts and their comments — no behavior change. The scan.sh migration deferral remains tracked by its own issue and this PR. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- plugins/repo-hygiene/skills/clean/reference/ecosystems.md | 2 +- plugins/repo-hygiene/skills/clean/scripts/clean-build.sh | 2 +- .../repo-hygiene/skills/clean/scripts/clean-build.test.sh | 4 ++-- .../repo-hygiene/skills/clean/scripts/clean-caches.test.sh | 6 +++--- .../repo-hygiene/skills/clean/scripts/lib/clean-common.sh | 5 +---- .../repo-hygiene/skills/clean/scripts/lib/cleanup-paths.sh | 2 +- 6 files changed, 9 insertions(+), 12 deletions(-) diff --git a/plugins/repo-hygiene/skills/clean/reference/ecosystems.md b/plugins/repo-hygiene/skills/clean/reference/ecosystems.md index 26dcd974440..9863e1ea896 100644 --- a/plugins/repo-hygiene/skills/clean/reference/ecosystems.md +++ b/plugins/repo-hygiene/skills/clean/reference/ecosystems.md @@ -14,7 +14,7 @@ Per-ecosystem teaching tables for the clean skill. Each entry includes command s | App log dirs | build | Not swept generically (no portable path) — reclaim via the `tree` action | Safe | App sink creates on next run | | `*.csproj.user` / `*.suo` | NEVER | — | Protected | VS / IDE debug profile preference | -No build-system clean driver runs (e.g. `dotnet clean`): the single pruned walk + `rm -rf` already removes every `bin/`/`obj/` output such a driver would, so invoking one first is pure overhead (#999). +No build-system clean driver runs (e.g. `dotnet clean`): the single pruned walk + `rm -rf` already removes every `bin/`/`obj/` output such a driver would, so invoking one first is pure overhead. ## Python diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh index 97b65813a0c..8f34b23aec5 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh @@ -80,7 +80,7 @@ cd "$REPO_ROOT" || exit 1 # removal below already deletes everything such a driver would, and running one # first is pure overhead (full MSBuild evaluation, minutes on a large solution) # that also re-creates obj/ evaluation artifacts. One walk + rm is strictly -# faster and equally complete (#999). +# faster and equally complete. # --apply with a prebuilt manifest: skip enumeration entirely, just consume it. if [[ "$DRY_RUN" -eq 0 && -n "$MANIFEST_ARG" ]]; then diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-build.test.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-build.test.sh index 3275c1e338c..e80bb20ee6c 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-build.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-build.test.sh @@ -48,7 +48,7 @@ out="$(run_build --apply)" assert_contains "submodule build dir skipped" "$out" "Skip (submodule):" assert_file_exists "submodule tracked file preserved" "$TEST_TMPDIR/repo/deps/sub/build/app.js" -# --- manifest / nested-dedup / apply-from-manifest / resume (#993, #995, #1002) --- +# --- manifest / nested-dedup / apply-from-manifest / resume --- # Fresh repo so progressive mutation above does not bleed into these cases. git init "$TEST_TMPDIR/b2" >/dev/null 2>&1 git -C "$TEST_TMPDIR/b2" config user.email "t@example.com" @@ -74,7 +74,7 @@ assert_contains "dry-run prints manifest path" "$out" "Manifest: $MANI" # bin/ (nested obj/ deduped) + .pytest_cache = 2 planned. assert_contains "nested dir deduped, caches folded in" "$out" "Summary: planned=2 bytes=" mani_body="$(cat "$MANI")" -# Structural pin (consumed contract, #994): exact classbytespath per tier. +# Structural pin (the manifest is a consumed contract): exact classbytespath per tier. if grep -qE "^build"$'\t'"[0-9]+"$'\t'"bin$" "$MANI"; then pass "build line is classbytespath" else diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh index fd599db2b2d..fff9199dc02 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh @@ -35,7 +35,7 @@ assert_file_absent "cache deleted after apply" "$TEST_TMPDIR/repo/.pytest_cache/ out="$(run_clean --dry-run)" assert_not_contains "node_modules skipped" "$out" "node_modules" -# --- manifest / summary / apply-from-manifest / resume (issues #995, #1002) --- +# --- manifest / summary / apply-from-manifest / resume --- # Fresh repo so progressive mutation above does not bleed into these cases. git init "$TEST_TMPDIR/r2" >/dev/null 2>&1 git -C "$TEST_TMPDIR/r2" config user.email "t@example.com" @@ -53,8 +53,8 @@ assert_contains "dry-run prints manifest path" "$out" "Manifest: $MANI" assert_contains "dry-run planned summary" "$out" "Summary: planned=1 bytes=" assert_file_exists "manifest written" "$MANI" mani_body="$(cat "$MANI")" -# Structural pin: the manifest is a consumed contract (#994 parses it), so -# assert the exact \t\t shape, not just substrings. +# Structural pin: the manifest is a consumed contract downstream tooling parses, +# so assert the exact \t\t shape, not just substrings. if grep -qE "^caches"$'\t'"[0-9]+"$'\t'"\.pytest_cache$" "$MANI"; then pass "manifest line is classbytespath" else diff --git a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh index 2737f42a7af..f0d3c1155ea 100644 --- a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh @@ -223,7 +223,7 @@ clean_branch_matches_protected_pattern() { return 1 } -# --- enumeration + manifest engine (issues #993 / #995 / #1002) -------------- +# --- enumeration + manifest engine ------------------------------------------- # # The selective build/caches tiers formerly ran one unpruned full-tree `find` # per pattern (~10 walks/repo); the `! -path` exclusions filtered output but did @@ -232,9 +232,6 @@ clean_branch_matches_protected_pattern() { # descends those three trees, then classifies, sizes, and manifests the result. # Measured on a large .NET + node repo (Windows/NTFS): one pruned walk incl. `du` # sizing ~17s vs a 10-walk unpruned dry-run that exceeded 10 min (killed). -# -# scan.sh still uses the old per-pattern unpruned walks — TODO(#1011) migrate it -# onto clean_enumerate (kept out of #993's named scope). # Single pruned walk. Prunes .git / node_modules / .venv (never descended), # then `-print`s directory-name and file-glob matches. Tier-agnostic: diff --git a/plugins/repo-hygiene/skills/clean/scripts/lib/cleanup-paths.sh b/plugins/repo-hygiene/skills/clean/scripts/lib/cleanup-paths.sh index ffeea048772..8f8addb4f9c 100644 --- a/plugins/repo-hygiene/skills/clean/scripts/lib/cleanup-paths.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/lib/cleanup-paths.sh @@ -49,7 +49,7 @@ CLEAN_BUILD_FILE_GLOBS=( # build — no build-system clean driver: the universal bin/obj globs above remove # every output a driver like `dotnet clean` would, so running one first is pure -# overhead (#999). +# overhead. # git — safe prune mutations GIT_PRUNE_OPS=( From 931103755934da30dfc14096830f02010bd18813 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 13:08:32 -0400 Subject: [PATCH 05/21] fix(repo-hygiene): harden manifest consumption and de-quadratic the dedup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `--apply --manifest ` surface is documented and caller-supplied, so `clean_apply_manifest` now treats the manifest as untrusted input: - Containment: an entry whose repo-relative path is absolute or traverses a parent (`..`, either separator) is rejected before any stat/rm and counted as a failure — an entry like `../outside` can no longer make `rm -rf` escape the repository. - Byte field as data: the size field is validated as an unsigned decimal before it reaches Bash arithmetic (which evaluates array subscripts recursively), so a crafted value cannot execute embedded command substitution. - Fail closed: `--apply --manifest ` now exits non-zero with a clear message instead of printing `removed=0 failed=0` and exiting 0, which would let automation treat a mistyped path as a successful sweep. Also replaces the O(n^2) nested-target dedup with an O(n log n) sort pass: each path is sorted under a trailing-'/' key so an ancestor sorts immediately before all its descendants (and never swallows a sibling like `buildstuff`), then a single scan drops anything under the last kept ancestor — the dry-run no longer spends minutes deduplicating a monorepo's thousands of candidates before it can show the confirmation plan. Regression tests cover containment rejection, arithmetic-injection refusal via a sentinel, and the missing-manifest fail-closed exit. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- .../skills/clean/scripts/clean-build.sh | 4 ++ .../skills/clean/scripts/clean-caches.sh | 4 ++ .../skills/clean/scripts/clean-caches.test.sh | 39 +++++++++++ .../skills/clean/scripts/lib/clean-common.sh | 67 +++++++++++++------ 4 files changed, 95 insertions(+), 19 deletions(-) diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh index 8f34b23aec5..a3d196bc008 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh @@ -84,6 +84,10 @@ cd "$REPO_ROOT" || exit 1 # --apply with a prebuilt manifest: skip enumeration entirely, just consume it. if [[ "$DRY_RUN" -eq 0 && -n "$MANIFEST_ARG" ]]; then + if [[ ! -r "$MANIFEST_ARG" ]]; then + echo "clean-build.sh: manifest not readable: $MANIFEST_ARG" >&2 + exit 1 + fi clean_apply_manifest "$REPO_ROOT" "$MANIFEST_ARG" printf 'Summary: removed=%s failed=%s bytes=%s\n' \ "$CLEAN_REMOVED_COUNT" "$CLEAN_FAILED_COUNT" "$CLEAN_REMOVED_BYTES" diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh index 19ed240e3b7..f245b8cc50e 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh @@ -72,6 +72,10 @@ cd "$REPO_ROOT" || exit 1 # --apply with a prebuilt manifest: skip enumeration entirely, just consume it. if [[ "$DRY_RUN" -eq 0 && -n "$MANIFEST_ARG" ]]; then + if [[ ! -r "$MANIFEST_ARG" ]]; then + echo "clean-caches.sh: manifest not readable: $MANIFEST_ARG" >&2 + exit 1 + fi clean_apply_manifest "$REPO_ROOT" "$MANIFEST_ARG" printf 'Summary: removed=%s failed=%s bytes=%s\n' \ "$CLEAN_REMOVED_COUNT" "$CLEAN_FAILED_COUNT" "$CLEAN_REMOVED_BYTES" diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh index fff9199dc02..6a8253d6f07 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh @@ -76,6 +76,45 @@ rc=$? assert_contains "resume removes nothing" "$out" "Summary: removed=0 failed=0 bytes=0" assert_exit "resume exit 0" 0 "$rc" +# The manifest is an untrusted --apply surface (a caller supplies it, or a +# concurrent process alters it). Three hardening guards: + +# 1. Containment — an entry escaping the repo (`..`) is rejected, never removed, +# and counts as a failure (fail closed). The external victim survives. +mkdir -p "$TEST_TMPDIR/outside_victim" +echo v >"$TEST_TMPDIR/outside_victim/keep" +printf 'caches\t1\t../outside_victim\n' >"$TEST_TMPDIR/r2.escape.manifest" +out="$(run_r2 --apply --manifest "$TEST_TMPDIR/r2.escape.manifest" 2>&1)" +rc=$? +assert_contains "escaping entry rejected" "$out" "Rejected (outside repo): ../outside_victim" +assert_contains "rejection counts as failure" "$out" "Summary: removed=0 failed=1 bytes=0" +assert_exit "escape apply exits non-zero" 1 "$rc" +assert_file_exists "external victim preserved" "$TEST_TMPDIR/outside_victim/keep" + +# 2. Byte field as data — a non-numeric byte field must NOT reach Bash arithmetic +# (which evaluates array subscripts recursively). The payload would `touch` a +# sentinel if evaluated; the guard coerces it to 0, so the path still removes +# and the sentinel never appears. +mkdir -p "$TEST_TMPDIR/r2/.ruff_cache" +echo r >"$TEST_TMPDIR/r2/.ruff_cache/r" +SENTINEL="$TEST_TMPDIR/injected" +# The `$(...)` MUST stay literal in the manifest — expanding it here would defeat +# the test. shellcheck disable=SC2016 (intentional single quotes). +# shellcheck disable=SC2016 +printf 'caches\tx[$(touch %s)]\t.ruff_cache\n' "$SENTINEL" >"$TEST_TMPDIR/r2.inject.manifest" +out="$(run_r2 --apply --manifest "$TEST_TMPDIR/r2.inject.manifest")" +rc=$? +assert_file_absent "arithmetic injection did not execute" "$SENTINEL" +assert_contains "malformed-byte entry still removes" "$out" "Removed: .ruff_cache" +assert_exit "inject apply exit 0" 0 "$rc" + +# 3. Fail closed on an unreadable/missing manifest — silently doing nothing and +# exiting 0 would let automation treat a mistyped path as a successful sweep. +out="$(run_r2 --apply --manifest "$TEST_TMPDIR/does-not-exist.manifest" 2>&1)" +rc=$? +assert_contains "missing manifest reported" "$out" "manifest not readable" +assert_exit "missing manifest exits non-zero" 1 "$rc" + # rm-failure accounting: a manifest entry rm cannot remove must count failed and # force a non-zero exit. Deterministic only where the FS enforces a write-denied # parent (real POSIX / Linux CI); Cygwin/MSYS ignores it, so probe and skip. diff --git a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh index f0d3c1155ea..feb53b62940 100644 --- a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh @@ -376,24 +376,28 @@ clean_plan() { fi done + # Drop any eligible path nested under an eligible ancestor (`du` of the ancestor + # already counts it and `rm -rf` already removes it — otherwise the byte total + # double-counts and apply hits a spent path). O(n log n), not O(n²): sort each + # path with a trailing '/' key so an ancestor sorts immediately before ALL its + # descendants and they stay contiguous (the '/' also stops `build` swallowing a + # sibling `buildstuff` — `buildstuff/` does not start with `build/`), then skip + # anything under the last kept ancestor in a single pass. local -a surv_abs=() surv_class=() - local a b nested j - for i in "${!elig_abs[@]}"; do - a="${elig_abs[$i]}" - nested=0 - for j in "${!elig_abs[@]}"; do - [[ "$i" == "$j" ]] && continue - b="${elig_abs[$j]}" - # Anchor on '/' so `build` never swallows a sibling `buildstuff`. - if [[ "$a" == "$b"/* ]]; then - nested=1 - break - fi - done - ((nested)) && continue - surv_abs+=("$a") - surv_class+=("${elig_class[$i]}") - done + local last_key="" key + while IFS=$'\t' read -r key abs class; do + [[ -n "$abs" ]] || continue + if [[ -n "$last_key" && "$key" == "$last_key"* ]]; then + continue + fi + surv_abs+=("$abs") + surv_class+=("$class") + last_key="$key" + done < <( + for i in "${!elig_abs[@]}"; do + printf '%s/\t%s\t%s\n' "${elig_abs[$i]}" "${elig_abs[$i]}" "${elig_class[$i]}" + done | LC_ALL=C sort + ) ((${#surv_abs[@]})) || return 0 local -A size_of=() @@ -415,18 +419,43 @@ clean_plan() { done } +# Return 0 when a manifest-supplied repo-relative path is safe to act on — below +# REPO_ROOT, never absolute, never traversing a parent (`..`, either separator). +# The manifest is a documented `--apply --manifest` surface a caller may supply +# or a concurrent process may alter, so an entry like `../outside` must never let +# `rm` escape the repository. +clean_manifest_rel_safe() { + local norm="${1//\\//}" + [[ -n "$norm" ]] || return 1 + [[ "$norm" == /* ]] && return 1 + case "/$norm/" in + */../*) return 1 ;; + *) return 0 ;; + esac +} + # Consume a manifest: re-stat + re-run the protection gate per entry (the # staleness guard), `rm -rf` survivors, and accumulate outcomes. An entry whose # path is already gone is idempotent success (resume) — counted neither removed # nor failed. A path that became protected since the dry-run is skipped (its -# `Skip` line re-emitted), not removed. CLEAN_FAILED_COUNT counts only genuine -# `rm` failures (locked / Unremovable). +# `Skip` line re-emitted), not removed. CLEAN_FAILED_COUNT counts genuine `rm` +# failures (locked / Unremovable) and rejected entries (a manifest a caller +# supplied or a concurrent process altered may carry a path that escapes the repo +# — fail closed on it). The manifest is untrusted input: paths are containment- +# checked and the byte field is validated as an unsigned decimal before it ever +# reaches Bash arithmetic (which evaluates array subscripts recursively). # clean_apply_manifest ROOT MANIFEST clean_apply_manifest() { local root="$1" manifest="$2" local class bytes rel abs skip while IFS=$'\t' read -r class bytes rel; do [[ -n "$rel" ]] || continue + if ! clean_manifest_rel_safe "$rel"; then + printf 'Rejected (outside repo): %s\n' "$rel" >&2 + CLEAN_FAILED_COUNT=$((CLEAN_FAILED_COUNT + 1)) + continue + fi + [[ "$bytes" =~ ^[0-9]+$ ]] || bytes=0 abs="$root/$rel" [[ -e "$abs" ]] || continue if ! skip="$(clean_target_eligible "$root" "$abs")"; then From 76d361725c2b37d7abcc0468ff44bf926d5dfb2e Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 13:19:57 -0400 Subject: [PATCH 06/21] fix(repo-hygiene): validate manifest entries against tier and target rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The manifest containment guard stopped `..`/absolute escapes but still trusted that any in-repo path a manifest listed was a real cleanup target. A caller- supplied or concurrently-altered entry such as `caches\t1\tnotes` therefore passed the protection gate (an ordinary untracked dir is unprotected) and was removed while the run reported success. `clean_apply_manifest` now takes the tier's allowed classes and, per entry, rejects (fail closed, counted as a failure) any entry whose class the tier does not produce, and any path that is not a legitimate target for its class per the same candidate rules enumeration uses to find targets (explicit repo-root paths, a recognized dir-name leaf, or a file-glob leaf). clean-caches accepts only `caches`; clean-build accepts `build` and the caches it folds in. Regression tests cover a non-target untracked dir (`notes/`) and a wrong-tier entry — both rejected, preserved, non-zero exit. The rm-failure case now targets a valid explicit cache so it exercises the genuine Unremovable branch rather than target rejection. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- .../skills/clean/scripts/clean-build.sh | 4 +- .../skills/clean/scripts/clean-caches.sh | 4 +- .../skills/clean/scripts/clean-caches.test.sh | 30 ++++++++- .../skills/clean/scripts/lib/clean-common.sh | 61 ++++++++++++++++--- 4 files changed, 85 insertions(+), 14 deletions(-) diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh index a3d196bc008..b2f43f246d7 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh @@ -88,7 +88,7 @@ if [[ "$DRY_RUN" -eq 0 && -n "$MANIFEST_ARG" ]]; then echo "clean-build.sh: manifest not readable: $MANIFEST_ARG" >&2 exit 1 fi - clean_apply_manifest "$REPO_ROOT" "$MANIFEST_ARG" + clean_apply_manifest "$REPO_ROOT" "$MANIFEST_ARG" "build caches" printf 'Summary: removed=%s failed=%s bytes=%s\n' \ "$CLEAN_REMOVED_COUNT" "$CLEAN_FAILED_COUNT" "$CLEAN_REMOVED_BYTES" [[ "$CLEAN_FAILED_COUNT" -eq 0 ]] || exit 1 @@ -113,7 +113,7 @@ if [[ "$DRY_RUN" -eq 1 ]]; then exit 0 fi -clean_apply_manifest "$REPO_ROOT" "$MANIFEST" +clean_apply_manifest "$REPO_ROOT" "$MANIFEST" "build caches" printf 'Summary: removed=%s failed=%s bytes=%s\n' \ "$CLEAN_REMOVED_COUNT" "$CLEAN_FAILED_COUNT" "$CLEAN_REMOVED_BYTES" [[ "$CLEAN_FAILED_COUNT" -eq 0 ]] || exit 1 diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh index f245b8cc50e..89e259f5012 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh @@ -76,7 +76,7 @@ if [[ "$DRY_RUN" -eq 0 && -n "$MANIFEST_ARG" ]]; then echo "clean-caches.sh: manifest not readable: $MANIFEST_ARG" >&2 exit 1 fi - clean_apply_manifest "$REPO_ROOT" "$MANIFEST_ARG" + clean_apply_manifest "$REPO_ROOT" "$MANIFEST_ARG" "caches" printf 'Summary: removed=%s failed=%s bytes=%s\n' \ "$CLEAN_REMOVED_COUNT" "$CLEAN_FAILED_COUNT" "$CLEAN_REMOVED_BYTES" [[ "$CLEAN_FAILED_COUNT" -eq 0 ]] || exit 1 @@ -95,7 +95,7 @@ if [[ "$DRY_RUN" -eq 1 ]]; then exit 0 fi -clean_apply_manifest "$REPO_ROOT" "$MANIFEST" +clean_apply_manifest "$REPO_ROOT" "$MANIFEST" "caches" printf 'Summary: removed=%s failed=%s bytes=%s\n' \ "$CLEAN_REMOVED_COUNT" "$CLEAN_FAILED_COUNT" "$CLEAN_REMOVED_BYTES" [[ "$CLEAN_FAILED_COUNT" -eq 0 ]] || exit 1 diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh index 6a8253d6f07..eb483db5e7f 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh @@ -108,7 +108,29 @@ assert_file_absent "arithmetic injection did not execute" "$SENTINEL" assert_contains "malformed-byte entry still removes" "$out" "Removed: .ruff_cache" assert_exit "inject apply exit 0" 0 "$rc" -# 3. Fail closed on an unreadable/missing manifest — silently doing nothing and +# 3. Target validation — an entry naming an ordinary untracked dir that is not a +# cache target (here `notes/`) is rejected by the tier's candidate rules, never +# removed, and counts as a failure. Without this, a tampered manifest could +# delete any unprotected untracked path. +mkdir -p "$TEST_TMPDIR/r2/notes" +echo n >"$TEST_TMPDIR/r2/notes/keep" +printf 'caches\t1\tnotes\n' >"$TEST_TMPDIR/r2.bogus.manifest" +out="$(run_r2 --apply --manifest "$TEST_TMPDIR/r2.bogus.manifest" 2>&1)" +rc=$? +assert_contains "non-target entry rejected" "$out" "Rejected (not a caches target): notes" +assert_exit "non-target apply exits non-zero" 1 "$rc" +assert_file_exists "unrelated untracked dir preserved" "$TEST_TMPDIR/r2/notes/keep" + +# Wrong-tier entry (a build-class line handed to the caches tier) is rejected too. +printf 'build\t1\tbin\n' >"$TEST_TMPDIR/r2.wrongtier.manifest" +mkdir -p "$TEST_TMPDIR/r2/bin" +echo b >"$TEST_TMPDIR/r2/bin/x" +out="$(run_r2 --apply --manifest "$TEST_TMPDIR/r2.wrongtier.manifest" 2>&1)" +rc=$? +assert_contains "wrong-tier entry rejected" "$out" "Rejected (wrong tier): bin" +assert_file_exists "wrong-tier target preserved" "$TEST_TMPDIR/r2/bin/x" + +# 4. Fail closed on an unreadable/missing manifest — silently doing nothing and # exiting 0 would let automation treat a mistyped path as a successful sweep. out="$(run_r2 --apply --manifest "$TEST_TMPDIR/does-not-exist.manifest" 2>&1)" rc=$? @@ -126,8 +148,10 @@ if rm -rf "$TEST_TMPDIR/r2/.mypy_cache/inner" 2>/dev/null; then rm -rf "$TEST_TMPDIR/r2/.mypy_cache" 2>/dev/null || true skip_case "rm-failure accounting — FS does not enforce write-denied parent here" else - printf 'caches\t4096\t.mypy_cache/inner\n' >"$TEST_TMPDIR/r2.fail.manifest" - out="$(run_r2 --apply --manifest "$TEST_TMPDIR/r2.fail.manifest")" + # `.mypy_cache` is a valid explicit cache target; rm cannot empty it while the + # dir stays write-denied, so this exercises the genuine Unremovable branch. + printf 'caches\t4096\t.mypy_cache\n' >"$TEST_TMPDIR/r2.fail.manifest" + out="$(run_r2 --apply --manifest "$TEST_TMPDIR/r2.fail.manifest" 2>&1)" rc=$? assert_contains "failure counted" "$out" "Summary: removed=0 failed=1 bytes=0" assert_exit "apply exits non-zero on failure" 1 "$rc" diff --git a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh index feb53b62940..194636d1c68 100644 --- a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh @@ -434,27 +434,74 @@ clean_manifest_rel_safe() { esac } +# Return 0 when REL is a legitimate removal target for CLASS — matching the SAME +# candidate rules enumeration uses to FIND targets (explicit repo-root paths, a +# recursive dir-name leaf, or a file-glob leaf). The manifest is untrusted, so +# --apply re-derives target-hood from the rules rather than trusting a listed +# path was ever a real target: a tampered entry like `caches\t1\tnotes` names an +# ordinary untracked dir that is not a cache and must never be removed. +clean_manifest_target_valid() { + local class="$1" rel="${2//\\//}" base="${2##*/}" e pat + case "$class" in + caches) + for e in "${CLEAN_CACHE_EXPLICIT[@]}" "${CLEAN_CACHE_EXPLICIT_FILES[@]}"; do + [[ "$rel" == "$e" ]] && return 0 + done + for e in "${CLEAN_CACHE_FIND_DIR_NAMES[@]}"; do + [[ "$base" == "$e" ]] && return 0 + done + for pat in "${CLEAN_CACHE_FIND_FILE_GLOBS[@]}"; do + # shellcheck disable=SC2053 + [[ "$base" == $pat ]] && return 0 + done + ;; + build) + for e in "${CLEAN_BUILD_DIR_NAMES[@]}"; do + [[ "$base" == "$e" ]] && return 0 + done + for pat in "${CLEAN_BUILD_FILE_GLOBS[@]}"; do + # shellcheck disable=SC2053 + [[ "$base" == $pat ]] && return 0 + done + ;; + *) ;; + esac + return 1 +} + # Consume a manifest: re-stat + re-run the protection gate per entry (the # staleness guard), `rm -rf` survivors, and accumulate outcomes. An entry whose # path is already gone is idempotent success (resume) — counted neither removed # nor failed. A path that became protected since the dry-run is skipped (its # `Skip` line re-emitted), not removed. CLEAN_FAILED_COUNT counts genuine `rm` -# failures (locked / Unremovable) and rejected entries (a manifest a caller -# supplied or a concurrent process altered may carry a path that escapes the repo -# — fail closed on it). The manifest is untrusted input: paths are containment- -# checked and the byte field is validated as an unsigned decimal before it ever -# reaches Bash arithmetic (which evaluates array subscripts recursively). -# clean_apply_manifest ROOT MANIFEST +# failures (locked / Unremovable) and rejected entries — fail closed. The +# manifest is untrusted input (a caller supplies it, or a concurrent process may +# alter it): every entry is validated before its path is acted on — the class +# must be one this tier produces (ALLOWED, space-separated), the path must be +# repo-contained (no `..`/absolute) AND a real target for its class (not an +# arbitrary untracked dir), and the byte field must be an unsigned decimal before +# it reaches Bash arithmetic (which evaluates array subscripts recursively). +# clean_apply_manifest ROOT MANIFEST ALLOWED_CLASSES clean_apply_manifest() { - local root="$1" manifest="$2" + local root="$1" manifest="$2" allowed="${3:-}" local class bytes rel abs skip while IFS=$'\t' read -r class bytes rel; do [[ -n "$rel" ]] || continue + if [[ -n "$allowed" && " $allowed " != *" $class "* ]]; then + printf 'Rejected (wrong tier): %s\n' "$rel" >&2 + CLEAN_FAILED_COUNT=$((CLEAN_FAILED_COUNT + 1)) + continue + fi if ! clean_manifest_rel_safe "$rel"; then printf 'Rejected (outside repo): %s\n' "$rel" >&2 CLEAN_FAILED_COUNT=$((CLEAN_FAILED_COUNT + 1)) continue fi + if ! clean_manifest_target_valid "$class" "$rel"; then + printf 'Rejected (not a %s target): %s\n' "$class" "$rel" >&2 + CLEAN_FAILED_COUNT=$((CLEAN_FAILED_COUNT + 1)) + continue + fi [[ "$bytes" =~ ^[0-9]+$ ]] || bytes=0 abs="$root/$rel" [[ -e "$abs" ]] || continue From 137efb648a6eeecbcb81860fab05afc3df81847b Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 13:30:03 -0400 Subject: [PATCH 07/21] fix(repo-hygiene): type-check manifest targets and guard manifest overwrite MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two more hardenings of the untrusted --manifest surface: - Target type: manifest target validation now also checks the filesystem type each candidate rule emits (dir names / explicit dirs are found -type d, globs / explicit files -type f). A regular file merely named `bin` (or `__pycache__`) can no longer be removed by a crafted `build\t1\timportant/bin` — the dry-run could never have planned it. The existence check now precedes validation so a resumed, already-removed entry stays an idempotent no-op rather than a rejection. - Manifest overwrite: `--manifest ` is a caller-supplied input, so the dry-run build refuses to truncate an existing NON-manifest file (e.g. a mistyped `~/.config/app/settings`) and exits non-zero instead of silently erasing it; an absent path or an existing manifest-format file is still (re)written. Regression tests cover a file-as-dir-name target rejection and the refuse-to-overwrite guard (including that a real manifest is still rewritable). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- .../skills/clean/scripts/clean-build.sh | 2 +- .../skills/clean/scripts/clean-caches.sh | 2 +- .../skills/clean/scripts/clean-caches.test.sh | 27 +++++++- .../skills/clean/scripts/lib/clean-common.sh | 65 ++++++++++++++----- 4 files changed, 77 insertions(+), 19 deletions(-) diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh index b2f43f246d7..58d030ed5f5 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh @@ -95,7 +95,7 @@ if [[ "$DRY_RUN" -eq 0 && -n "$MANIFEST_ARG" ]]; then exit 0 fi -MANIFEST="$(clean_manifest_path "$MANIFEST_ARG")" +MANIFEST="$(clean_manifest_path "$MANIFEST_ARG")" || exit 1 if [[ "$INCLUDE_CACHES" -eq 1 ]]; then mapfile -t CACHE_CANDS < <(clean_caches_candidates "$REPO_ROOT") diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh index 89e259f5012..79b345aa980 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh @@ -83,7 +83,7 @@ if [[ "$DRY_RUN" -eq 0 && -n "$MANIFEST_ARG" ]]; then exit 0 fi -MANIFEST="$(clean_manifest_path "$MANIFEST_ARG")" +MANIFEST="$(clean_manifest_path "$MANIFEST_ARG")" || exit 1 mapfile -t CACHE_CANDS < <(clean_caches_candidates "$REPO_ROOT") clean_add_candidates caches "${CACHE_CANDS[@]}" diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh index eb483db5e7f..d4d909a089f 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh @@ -130,13 +130,38 @@ rc=$? assert_contains "wrong-tier entry rejected" "$out" "Rejected (wrong tier): bin" assert_file_exists "wrong-tier target preserved" "$TEST_TMPDIR/r2/bin/x" -# 4. Fail closed on an unreadable/missing manifest — silently doing nothing and +# 4. Type validation — a regular file whose basename matches a dir-name target +# (enumeration only emits those under -type d) is rejected, never removed. +mkdir -p "$TEST_TMPDIR/r2/src" +echo f >"$TEST_TMPDIR/r2/src/__pycache__" # a FILE named like a cache dir +printf 'caches\t1\tsrc/__pycache__\n' >"$TEST_TMPDIR/r2.type.manifest" +out="$(run_r2 --apply --manifest "$TEST_TMPDIR/r2.type.manifest" 2>&1)" +rc=$? +assert_contains "file-as-dir target rejected" "$out" "Rejected (not a caches target): src/__pycache__" +assert_exit "type-mismatch apply exits non-zero" 1 "$rc" +assert_file_exists "misnamed file preserved" "$TEST_TMPDIR/r2/src/__pycache__" + +# 5. Fail closed on an unreadable/missing manifest — silently doing nothing and # exiting 0 would let automation treat a mistyped path as a successful sweep. out="$(run_r2 --apply --manifest "$TEST_TMPDIR/does-not-exist.manifest" 2>&1)" rc=$? assert_contains "missing manifest reported" "$out" "manifest not readable" assert_exit "missing manifest exits non-zero" 1 "$rc" +# 6. Dry-run must not truncate an arbitrary --manifest destination: an existing +# non-manifest file (a mistyped path) is refused, not erased. +printf 'important user config\n' >"$TEST_TMPDIR/precious.conf" +out="$(run_r2 --dry-run --manifest "$TEST_TMPDIR/precious.conf" 2>&1)" +rc=$? +assert_contains "non-manifest overwrite refused" "$out" "refusing to overwrite non-manifest file" +assert_exit "refuse-overwrite exits non-zero" 1 "$rc" +preserved="$(cat "$TEST_TMPDIR/precious.conf")" +assert_contains "precious file left intact" "$preserved" "important user config" +# Re-writing an existing MANIFEST-format file is still allowed (dry-run reuse). +out="$(run_r2 --dry-run --manifest "$MANI" 2>&1)" +rc=$? +assert_exit "rewriting a real manifest still works" 0 "$rc" + # rm-failure accounting: a manifest entry rm cannot remove must count failed and # force a non-zero exit. Deterministic only where the FS enforces a write-denied # parent (real POSIX / Linux CI); Cygwin/MSYS ignores it, so probe and skip. diff --git a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh index 194636d1c68..63e61a3dd80 100644 --- a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh @@ -434,34 +434,42 @@ clean_manifest_rel_safe() { esac } -# Return 0 when REL is a legitimate removal target for CLASS — matching the SAME -# candidate rules enumeration uses to FIND targets (explicit repo-root paths, a -# recursive dir-name leaf, or a file-glob leaf). The manifest is untrusted, so +# Return 0 when the existing path ABS is a legitimate removal target for CLASS — +# matching the SAME candidate rules enumeration uses to FIND targets, INCLUDING +# the filesystem type it emits each under (dir names / explicit dirs are found +# `-type d`, globs / explicit files `-type f`). The manifest is untrusted, so # --apply re-derives target-hood from the rules rather than trusting a listed -# path was ever a real target: a tampered entry like `caches\t1\tnotes` names an -# ordinary untracked dir that is not a cache and must never be removed. +# path was ever a real target: a tampered `caches\t1\tnotes` (an ordinary +# untracked dir) or `build\t1\timportant/bin` (a regular file merely named `bin`) +# is one the dry-run could never have planned and must never be removed. Assumes +# ABS exists (callers `-e`-check first so a resumed, already-gone entry stays an +# idempotent no-op rather than a rejection). +# clean_manifest_target_valid CLASS REL ABS clean_manifest_target_valid() { - local class="$1" rel="${2//\\//}" base="${2##*/}" e pat + local class="$1" rel="${2//\\//}" abs="$3" base="${2##*/}" e pat case "$class" in caches) - for e in "${CLEAN_CACHE_EXPLICIT[@]}" "${CLEAN_CACHE_EXPLICIT_FILES[@]}"; do - [[ "$rel" == "$e" ]] && return 0 + for e in "${CLEAN_CACHE_EXPLICIT[@]}"; do + [[ "$rel" == "$e" ]] && { [[ -d "$abs" ]] && return 0 || return 1; } + done + for e in "${CLEAN_CACHE_EXPLICIT_FILES[@]}"; do + [[ "$rel" == "$e" ]] && { [[ -f "$abs" ]] && return 0 || return 1; } done for e in "${CLEAN_CACHE_FIND_DIR_NAMES[@]}"; do - [[ "$base" == "$e" ]] && return 0 + [[ "$base" == "$e" ]] && { [[ -d "$abs" ]] && return 0 || return 1; } done for pat in "${CLEAN_CACHE_FIND_FILE_GLOBS[@]}"; do # shellcheck disable=SC2053 - [[ "$base" == $pat ]] && return 0 + [[ "$base" == $pat ]] && { [[ -f "$abs" ]] && return 0 || return 1; } done ;; build) for e in "${CLEAN_BUILD_DIR_NAMES[@]}"; do - [[ "$base" == "$e" ]] && return 0 + [[ "$base" == "$e" ]] && { [[ -d "$abs" ]] && return 0 || return 1; } done for pat in "${CLEAN_BUILD_FILE_GLOBS[@]}"; do # shellcheck disable=SC2053 - [[ "$base" == $pat ]] && return 0 + [[ "$base" == $pat ]] && { [[ -f "$abs" ]] && return 0 || return 1; } done ;; *) ;; @@ -497,14 +505,17 @@ clean_apply_manifest() { CLEAN_FAILED_COUNT=$((CLEAN_FAILED_COUNT + 1)) continue fi - if ! clean_manifest_target_valid "$class" "$rel"; then + abs="$root/$rel" + # Idempotent resume: an entry a prior apply already removed is neither a + # failure nor a re-removal — skip before target/type validation (which needs + # the path to exist). + [[ -e "$abs" ]] || continue + if ! clean_manifest_target_valid "$class" "$rel" "$abs"; then printf 'Rejected (not a %s target): %s\n' "$class" "$rel" >&2 CLEAN_FAILED_COUNT=$((CLEAN_FAILED_COUNT + 1)) continue fi [[ "$bytes" =~ ^[0-9]+$ ]] || bytes=0 - abs="$root/$rel" - [[ -e "$abs" ]] || continue if ! skip="$(clean_target_eligible "$root" "$abs")"; then [[ -n "$skip" ]] && printf '%s\n' "$skip" continue @@ -520,13 +531,35 @@ clean_apply_manifest() { done <"$manifest" } +# Return 0 when PATH is safe to (re)write as a manifest: absent, or an existing +# regular file that is empty or already in manifest format. `--manifest` is a +# documented caller-supplied path, so an explicit value that names an existing +# non-manifest file (e.g. a mistyped `~/.config/app/settings`) must not be +# truncated — the dry-run build would silently erase it. +clean_manifest_writable_target() { + local path="$1" line + [[ -e "$path" ]] || return 0 + [[ -f "$path" ]] || return 1 + [[ -s "$path" ]] || return 0 + while IFS= read -r line || [[ -n "$line" ]]; do + [[ -z "$line" ]] && continue + [[ "$line" =~ ^(caches|build)$'\t'[0-9]+$'\t' ]] || return 1 + done <"$path" + return 0 +} + # clean_manifest_path [--manifest VALUE] → resolve/create the session manifest. # Honors an explicit path (agent passes dry-run's path back at --apply); else -# mktemp a session-scoped file. Truncates so a reused path starts clean. +# mktemp a session-scoped file. Truncates so a reused path starts clean, but +# refuses (returns 1, prints nothing) to overwrite an existing non-manifest file. clean_manifest_path() { local explicit="$1" path if [[ -n "$explicit" ]]; then path="$explicit" + if ! clean_manifest_writable_target "$path"; then + printf 'clean: refusing to overwrite non-manifest file: %s\n' "$path" >&2 + return 1 + fi else path="$(mktemp 2>/dev/null)" || path="${TMPDIR:-/tmp}/clean-manifest.$$" fi From 1967662c9f2a252dd13eca084b5e4d6f8b66e928 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 13:37:43 -0400 Subject: [PATCH 08/21] fix(repo-hygiene): reject a valueless --manifest instead of looping forever A trailing `--manifest` (e.g. `clean-caches.sh --apply --manifest`) hung: `$2` is empty so `shift 2` fails on the single remaining arg, and without `set -e` `$#` is unchanged, so the case loop reprocesses `--manifest` forever. Both entry scripts now require a value to follow `--manifest` and exit with the documented usage error (2) otherwise. Regression test guards with a `timeout` so a regression fails loudly instead of spinning. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- plugins/repo-hygiene/skills/clean/scripts/clean-build.sh | 6 +++++- plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh | 6 +++++- .../skills/clean/scripts/clean-caches.test.sh | 8 ++++++++ 3 files changed, 18 insertions(+), 2 deletions(-) diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh index 58d030ed5f5..83c55c75799 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-build.sh @@ -54,7 +54,11 @@ while [[ $# -gt 0 ]]; do shift ;; --manifest) - MANIFEST_ARG="${2:-}" + if [[ $# -lt 2 ]]; then + echo "clean-build.sh: --manifest requires a value" >&2 + exit 2 + fi + MANIFEST_ARG="$2" shift 2 ;; -h | --help) diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh index 79b345aa980..2371c44ddc3 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.sh @@ -48,7 +48,11 @@ while [[ $# -gt 0 ]]; do shift ;; --manifest) - MANIFEST_ARG="${2:-}" + if [[ $# -lt 2 ]]; then + echo "clean-caches.sh: --manifest requires a value" >&2 + exit 2 + fi + MANIFEST_ARG="$2" shift 2 ;; -h | --help) diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh index d4d909a089f..50045008685 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh @@ -162,6 +162,14 @@ out="$(run_r2 --dry-run --manifest "$MANI" 2>&1)" rc=$? assert_exit "rewriting a real manifest still works" 0 "$rc" +# 7. A trailing `--manifest` with no value is a usage error, not an infinite loop +# (without set -e, `shift 2` on a single remaining arg is a silent no-op). The +# timeout fails the case loudly if the guard ever regresses into a hang. +out="$(timeout 10 bash -c "cd '$TEST_TMPDIR/r2' && bash '$CLEAN' --apply --manifest" 2>&1)" +rc=$? +assert_exit "trailing --manifest is a usage error" 2 "$rc" +assert_contains "trailing --manifest reported" "$out" "--manifest requires a value" + # rm-failure accounting: a manifest entry rm cannot remove must count failed and # force a non-zero exit. Deterministic only where the FS enforces a write-denied # parent (real POSIX / Linux CI); Cygwin/MSYS ignores it, so probe and skip. From 05f716a2f57e563e71e2cab99d4054e31b6b6152 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 13:46:02 -0400 Subject: [PATCH 09/21] fix(repo-hygiene): reject manifest entries inside pruned trees MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Enumeration prunes .git/node_modules/.venv and never emits a target inside them, but the apply path did not re-exclude them: a manifest entry such as `caches\t1\t.git/objects/__pycache__` passed every guard (its basename is a valid target name and .git is not in the protected-substring set) and was removed — removing files under .git can corrupt the repository. Lift the prune set into a single CLEAN_PRUNE_DIRS SSOT that the single-walk enumeration builds its `-prune` alternation from AND the apply path rejects against, so the prune set is enforced uniformly on both sides. Any manifest entry with a pruned segment is now rejected (fail closed). Regression test covers a `.git/...` entry. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- .../skills/clean/scripts/clean-caches.test.sh | 12 ++++++ .../skills/clean/scripts/lib/clean-common.sh | 38 +++++++++++++++++-- .../skills/clean/scripts/lib/cleanup-paths.sh | 7 ++++ 3 files changed, 53 insertions(+), 4 deletions(-) diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh index 50045008685..485b89e19e7 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh @@ -130,6 +130,18 @@ rc=$? assert_contains "wrong-tier entry rejected" "$out" "Rejected (wrong tier): bin" assert_file_exists "wrong-tier target preserved" "$TEST_TMPDIR/r2/bin/x" +# 3b. Pruned-tree entry — enumeration never descends .git/node_modules/.venv, so +# a manifest entry inside one (removing it could corrupt the repo) is rejected +# even though its basename is a valid target name. +mkdir -p "$TEST_TMPDIR/r2/.git/objects/__pycache__" +echo g >"$TEST_TMPDIR/r2/.git/objects/__pycache__/g" +printf 'caches\t1\t.git/objects/__pycache__\n' >"$TEST_TMPDIR/r2.pruned.manifest" +out="$(run_r2 --apply --manifest "$TEST_TMPDIR/r2.pruned.manifest" 2>&1)" +rc=$? +assert_contains "pruned-tree entry rejected" "$out" "Rejected (pruned tree): .git/objects/__pycache__" +assert_exit "pruned-tree apply exits non-zero" 1 "$rc" +assert_file_exists "pruned-tree path preserved" "$TEST_TMPDIR/r2/.git/objects/__pycache__/g" + # 4. Type validation — a regular file whose basename matches a dir-name target # (enumeration only emits those under -type d) is rejected, never removed. mkdir -p "$TEST_TMPDIR/r2/src" diff --git a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh index 63e61a3dd80..79f4c9b665d 100644 --- a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh @@ -251,7 +251,14 @@ clean_enumerate() { if [[ "$bucket" == dirs ]]; then dir_names+=("$tok"); else file_globs+=("$tok"); fi done - local -a args=("$root" '(' -name .git -o -name node_modules -o -name .venv ')' -prune -o '(') + local -a prune=('(') + local d + for d in "${CLEAN_PRUNE_DIRS[@]}"; do + ((${#prune[@]} > 1)) && prune+=(-o) + prune+=(-name "$d") + done + prune+=(')') + local -a args=("$root" "${prune[@]}" -prune -o '(') local -a match=() local i if ((${#dir_names[@]})); then @@ -434,6 +441,22 @@ clean_manifest_rel_safe() { esac } +# Return 0 when a repo-relative path lies within a pruned tree (a +# CLEAN_PRUNE_DIRS segment). Enumeration never descends these, so a manifest +# entry inside one — e.g. `.git/...`, whose removal could corrupt the repo — is +# one the dry-run could never have emitted. Rejected on --apply, keeping the +# prune set uniform on the enumerate and apply sides. +clean_path_has_pruned_segment() { + local rel="${1//\\//}" seg + for seg in "${CLEAN_PRUNE_DIRS[@]}"; do + case "/$rel/" in + *"/$seg/"*) return 0 ;; + *) ;; + esac + done + return 1 +} + # Return 0 when the existing path ABS is a legitimate removal target for CLASS — # matching the SAME candidate rules enumeration uses to FIND targets, INCLUDING # the filesystem type it emits each under (dir names / explicit dirs are found @@ -486,9 +509,11 @@ clean_manifest_target_valid() { # manifest is untrusted input (a caller supplies it, or a concurrent process may # alter it): every entry is validated before its path is acted on — the class # must be one this tier produces (ALLOWED, space-separated), the path must be -# repo-contained (no `..`/absolute) AND a real target for its class (not an -# arbitrary untracked dir), and the byte field must be an unsigned decimal before -# it reaches Bash arithmetic (which evaluates array subscripts recursively). +# repo-contained (no `..`/absolute), outside every pruned tree (enumeration never +# descends CLEAN_PRUNE_DIRS, so a `.git/...` entry is never one it emitted) AND a +# real target of the right type for its class (not an arbitrary untracked path), +# and the byte field must be an unsigned decimal before it reaches Bash +# arithmetic (which evaluates array subscripts recursively). # clean_apply_manifest ROOT MANIFEST ALLOWED_CLASSES clean_apply_manifest() { local root="$1" manifest="$2" allowed="${3:-}" @@ -505,6 +530,11 @@ clean_apply_manifest() { CLEAN_FAILED_COUNT=$((CLEAN_FAILED_COUNT + 1)) continue fi + if clean_path_has_pruned_segment "$rel"; then + printf 'Rejected (pruned tree): %s\n' "$rel" >&2 + CLEAN_FAILED_COUNT=$((CLEAN_FAILED_COUNT + 1)) + continue + fi abs="$root/$rel" # Idempotent resume: an entry a prior apply already removed is neither a # failure nor a re-removal — skip before target/type validation (which needs diff --git a/plugins/repo-hygiene/skills/clean/scripts/lib/cleanup-paths.sh b/plugins/repo-hygiene/skills/clean/scripts/lib/cleanup-paths.sh index 8f8addb4f9c..d6fd3abcbe5 100644 --- a/plugins/repo-hygiene/skills/clean/scripts/lib/cleanup-paths.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/lib/cleanup-paths.sh @@ -3,6 +3,13 @@ # SSOT: reference/cleanup-config.md — drift detected by cleanup-paths.test.sh # shellcheck disable=SC2034 +# Heavy trees that hold no cleanup targets we own — never descended by the +# single-walk enumeration (`-prune`) and, symmetrically, never accepted from a +# manifest at `--apply`, so both sides share one prune set. SSOT: the scan tier +# still uses the per-glob CLEAN_FIND_EXCLUDE_* below (its migration to this walk +# is deferred). +CLEAN_PRUNE_DIRS=(.git node_modules .venv) + # Universal find exclusions (cleanup-config.md intro) CLEAN_FIND_EXCLUDE_GIT='*/.git/*' CLEAN_FIND_EXCLUDE_VENV='*/.venv/*' From 694eb56594f3a6188857267778fd7944abd1ae54 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 14:01:47 -0400 Subject: [PATCH 10/21] fix(repo-hygiene): fail closed on truncated and newline-less manifest records MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two manifest-parsing gaps that let a bad manifest report success: - A valid final record with no trailing newline (common in caller-written files) was dropped: `read` returns nonzero at EOF so the loop body never ran, and `--apply` reported `removed=0 failed=0` while leaving the target in place. The loop now processes a nonempty final record via `|| [[ -n … ]]`. - A nonblank but truncated record missing the path field (e.g. `caches1`, or a partial write by a concurrent process) was silently skipped. It is now a malformed-record failure (fail closed); only genuinely blank lines are ignored. Regression tests cover both. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- .../skills/clean/scripts/clean-caches.test.sh | 24 ++++++++++++++++--- .../skills/clean/scripts/lib/clean-common.sh | 15 ++++++++++-- 2 files changed, 34 insertions(+), 5 deletions(-) diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh index 485b89e19e7..5fef84478f3 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh @@ -153,14 +153,32 @@ assert_contains "file-as-dir target rejected" "$out" "Rejected (not a caches tar assert_exit "type-mismatch apply exits non-zero" 1 "$rc" assert_file_exists "misnamed file preserved" "$TEST_TMPDIR/r2/src/__pycache__" -# 5. Fail closed on an unreadable/missing manifest — silently doing nothing and +# 5. A valid final record without a trailing newline (common in caller-written +# files) must still be processed, not silently dropped. +mkdir -p "$TEST_TMPDIR/r2/.pytest_cache" +echo x >"$TEST_TMPDIR/r2/.pytest_cache/x" +printf 'caches\t1\t.pytest_cache' >"$TEST_TMPDIR/r2.nonl.manifest" # no trailing newline +out="$(run_r2 --apply --manifest "$TEST_TMPDIR/r2.nonl.manifest")" +rc=$? +assert_contains "newline-less final record processed" "$out" "Removed: .pytest_cache" +assert_exit "newline-less apply exit 0" 0 "$rc" + +# 6. A nonblank but truncated record (missing the path field) is malformed and +# fails closed; a genuinely blank line is still ignored. +printf 'caches\t1\n\n' >"$TEST_TMPDIR/r2.malformed.manifest" +out="$(run_r2 --apply --manifest "$TEST_TMPDIR/r2.malformed.manifest" 2>&1)" +rc=$? +assert_contains "malformed record rejected" "$out" "Rejected (malformed record)" +assert_exit "malformed record exits non-zero" 1 "$rc" + +# 7. Fail closed on an unreadable/missing manifest — silently doing nothing and # exiting 0 would let automation treat a mistyped path as a successful sweep. out="$(run_r2 --apply --manifest "$TEST_TMPDIR/does-not-exist.manifest" 2>&1)" rc=$? assert_contains "missing manifest reported" "$out" "manifest not readable" assert_exit "missing manifest exits non-zero" 1 "$rc" -# 6. Dry-run must not truncate an arbitrary --manifest destination: an existing +# 8. Dry-run must not truncate an arbitrary --manifest destination: an existing # non-manifest file (a mistyped path) is refused, not erased. printf 'important user config\n' >"$TEST_TMPDIR/precious.conf" out="$(run_r2 --dry-run --manifest "$TEST_TMPDIR/precious.conf" 2>&1)" @@ -174,7 +192,7 @@ out="$(run_r2 --dry-run --manifest "$MANI" 2>&1)" rc=$? assert_exit "rewriting a real manifest still works" 0 "$rc" -# 7. A trailing `--manifest` with no value is a usage error, not an infinite loop +# 9. A trailing `--manifest` with no value is a usage error, not an infinite loop # (without set -e, `shift 2` on a single remaining arg is a silent no-op). The # timeout fails the case loudly if the guard ever regresses into a hang. out="$(timeout 10 bash -c "cd '$TEST_TMPDIR/r2' && bash '$CLEAN' --apply --manifest" 2>&1)" diff --git a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh index 79f4c9b665d..65765626970 100644 --- a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh @@ -518,8 +518,19 @@ clean_manifest_target_valid() { clean_apply_manifest() { local root="$1" manifest="$2" allowed="${3:-}" local class bytes rel abs skip - while IFS=$'\t' read -r class bytes rel; do - [[ -n "$rel" ]] || continue + # `|| [[ -n … ]]` processes a final record with no trailing newline (common in + # caller-written files) instead of dropping it — dropping it would report a + # cleanup as done while leaving it undone. + while IFS=$'\t' read -r class bytes rel || [[ -n "$class$bytes$rel" ]]; do + if [[ -z "$rel" ]]; then + # A deliberately blank line is ignored; a nonblank but truncated record + # (missing the path field, e.g. a partial write by a concurrent process) is + # malformed — fail closed so automation cannot read it as a successful no-op. + [[ -z "$class$bytes" ]] && continue + printf 'Rejected (malformed record): %s\n' "$class $bytes" >&2 + CLEAN_FAILED_COUNT=$((CLEAN_FAILED_COUNT + 1)) + continue + fi if [[ -n "$allowed" && " $allowed " != *" $class "* ]]; then printf 'Rejected (wrong tier): %s\n' "$rel" >&2 CLEAN_FAILED_COUNT=$((CLEAN_FAILED_COUNT + 1)) From 8f0a905fb91c69b5696e1573203596ea45d9876d Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 14:25:06 -0400 Subject: [PATCH 11/21] fix(repo-hygiene): fail on uncreatable manifest and reject symlinked targets Two more manifest-surface hardenings, both keeping apply to exactly what the dry-run could have emitted: - Manifest creation: clean_manifest_path only truncated its target and never checked the result, so `--dry-run --manifest ` printed a `Manifest:`/`Summary: planned=` plan for a file that was never written, handing apply a bogus path. It now fails (non-zero, prints nothing on stdout) when the file cannot be created. - Symlinked targets: the enumerator matches with `find -type d`/`-type f`, which never follow a symlink or Windows junction, but Bash `[[ -d ]]`/`[[ -f ]]` do. Target validation now requires a plain dir/file (not a symlink/reparse point), so a manifest naming a link (or a path swapped for one after the dry-run) is rejected instead of having its link removed. Regression tests cover the uncreatable-manifest failure and the symlinked-target rejection (the latter skips where the FS cannot create a symlink). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- .../skills/clean/scripts/clean-caches.test.sh | 26 +++++++++++++ .../skills/clean/scripts/lib/clean-common.sh | 37 ++++++++++++++----- 2 files changed, 54 insertions(+), 9 deletions(-) diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh index 5fef84478f3..922059ecf05 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh @@ -200,6 +200,32 @@ rc=$? assert_exit "trailing --manifest is a usage error" 2 "$rc" assert_contains "trailing --manifest reported" "$out" "--manifest requires a value" +# 10. A --manifest path that cannot be created (nonexistent parent) must fail +# before planning, not print a Manifest:/Summary: line for a file never +# written (which would hand apply a bogus path). +out="$(run_r2 --dry-run --manifest "$TEST_TMPDIR/nonexistent-dir/sub/m" 2>&1)" +rc=$? +assert_contains "uncreatable manifest reported" "$out" "cannot create manifest" +assert_exit "uncreatable manifest exits non-zero" 1 "$rc" +assert_not_contains "no bogus plan emitted" "$out" "Summary: planned=" + +# 11. A symlink/reparse point whose basename is a valid target is rejected — the +# enumerator uses `find -type d`/`-type f` and never emits a link, but Bash +# `[[ -d ]]` follows one. Skips where the FS cannot create a symlink. +mkdir -p "$TEST_TMPDIR/r2/realcache" +echo c >"$TEST_TMPDIR/r2/realcache/c" +ln -s "$TEST_TMPDIR/r2/realcache" "$TEST_TMPDIR/r2/.turbo" 2>/dev/null || true +if [[ -L "$TEST_TMPDIR/r2/.turbo" ]]; then + printf 'caches\t1\t.turbo\n' >"$TEST_TMPDIR/r2.symlink.manifest" + out="$(run_r2 --apply --manifest "$TEST_TMPDIR/r2.symlink.manifest" 2>&1)" + rc=$? + assert_contains "symlinked dir target rejected" "$out" "Rejected (not a caches target): .turbo" + assert_exit "symlink apply exits non-zero" 1 "$rc" + assert_file_exists "symlink target contents preserved" "$TEST_TMPDIR/r2/realcache/c" +else + skip_case "symlink dir target — symlinks not creatable here" +fi + # rm-failure accounting: a manifest entry rm cannot remove must count failed and # force a non-zero exit. Deterministic only where the FS enforces a write-denied # parent (real POSIX / Linux CI); Cygwin/MSYS ignores it, so probe and skip. diff --git a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh index 65765626970..789397b38e0 100644 --- a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh @@ -467,32 +467,41 @@ clean_path_has_pruned_segment() { # is one the dry-run could never have planned and must never be removed. Assumes # ABS exists (callers `-e`-check first so a resumed, already-gone entry stays an # idempotent no-op rather than a rejection). +# A plain directory / regular file that is NOT a symlink or reparse point. The +# enumerator matches targets with `find -type d`/`-type f`, which never follow a +# symlink or Windows junction; Bash `[[ -d ]]`/`[[ -f ]]` DO follow them, so a +# manifest entry naming a link (or a path swapped for one after the dry-run) +# would otherwise be accepted and its link removed — never a path the dry-run +# could have emitted. +clean_is_plain_dir() { [[ -d "$1" ]] && ! clean_path_is_reparse_point "$1"; } +clean_is_plain_file() { [[ -f "$1" ]] && ! clean_path_is_reparse_point "$1"; } + # clean_manifest_target_valid CLASS REL ABS clean_manifest_target_valid() { local class="$1" rel="${2//\\//}" abs="$3" base="${2##*/}" e pat case "$class" in caches) for e in "${CLEAN_CACHE_EXPLICIT[@]}"; do - [[ "$rel" == "$e" ]] && { [[ -d "$abs" ]] && return 0 || return 1; } + [[ "$rel" == "$e" ]] && { clean_is_plain_dir "$abs" && return 0 || return 1; } done for e in "${CLEAN_CACHE_EXPLICIT_FILES[@]}"; do - [[ "$rel" == "$e" ]] && { [[ -f "$abs" ]] && return 0 || return 1; } + [[ "$rel" == "$e" ]] && { clean_is_plain_file "$abs" && return 0 || return 1; } done for e in "${CLEAN_CACHE_FIND_DIR_NAMES[@]}"; do - [[ "$base" == "$e" ]] && { [[ -d "$abs" ]] && return 0 || return 1; } + [[ "$base" == "$e" ]] && { clean_is_plain_dir "$abs" && return 0 || return 1; } done for pat in "${CLEAN_CACHE_FIND_FILE_GLOBS[@]}"; do # shellcheck disable=SC2053 - [[ "$base" == $pat ]] && { [[ -f "$abs" ]] && return 0 || return 1; } + [[ "$base" == $pat ]] && { clean_is_plain_file "$abs" && return 0 || return 1; } done ;; build) for e in "${CLEAN_BUILD_DIR_NAMES[@]}"; do - [[ "$base" == "$e" ]] && { [[ -d "$abs" ]] && return 0 || return 1; } + [[ "$base" == "$e" ]] && { clean_is_plain_dir "$abs" && return 0 || return 1; } done for pat in "${CLEAN_BUILD_FILE_GLOBS[@]}"; do # shellcheck disable=SC2053 - [[ "$base" == $pat ]] && { [[ -f "$abs" ]] && return 0 || return 1; } + [[ "$base" == $pat ]] && { clean_is_plain_file "$abs" && return 0 || return 1; } done ;; *) ;; @@ -591,8 +600,12 @@ clean_manifest_writable_target() { # clean_manifest_path [--manifest VALUE] → resolve/create the session manifest. # Honors an explicit path (agent passes dry-run's path back at --apply); else -# mktemp a session-scoped file. Truncates so a reused path starts clean, but -# refuses (returns 1, prints nothing) to overwrite an existing non-manifest file. +# mktemp a session-scoped file. Truncates so a reused path starts clean; returns +# 1 (printing nothing on stdout) if it would overwrite an existing non-manifest +# file OR if the file cannot actually be created/truncated (an unwritable or +# nonexistent-parent path) — otherwise the dry-run would print a `Manifest:` line +# and plan removals against a file that was never written, handing the apply step +# a bogus path. clean_manifest_path() { local explicit="$1" path if [[ -n "$explicit" ]]; then @@ -604,6 +617,12 @@ clean_manifest_path() { else path="$(mktemp 2>/dev/null)" || path="${TMPDIR:-/tmp}/clean-manifest.$$" fi - : >"$path" + # Subshell so the redirect's own failure message is captured by 2>/dev/null + # (a bare `: >"$path" 2>/dev/null` still prints it — the target redirect is set + # up before stderr is redirected). + if ! (: >"$path") 2>/dev/null; then + printf 'clean: cannot create manifest: %s\n' "$path" >&2 + return 1 + fi printf '%s' "$path" } From 770ca049db3bf7e806f9ebdfecdabdc4db33e76a Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 15:16:48 -0400 Subject: [PATCH 12/21] fix(repo-hygiene): apply-loop fd isolation, honest bytes, dry-run/apply parity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Keeps the dry-run plan and the apply outcome faithful to each other and to the filesystem: - Apply loop fd isolation (root-cause bug): a per-entry validator shells out to `fsutil` (the reparse-point check), which drains stdin. Read on fd 0, it swallowed the rest of the manifest — every entry after the first was silently skipped, so `clean-build --apply --include-caches` removed the first target and reported success while leaving the rest. The loop now reads the manifest on a dedicated fd (3), and the reparse check gives fsutil its own ` Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- .../skills/clean/scripts/clean-caches.test.sh | 38 +++++++++++++ .../skills/clean/scripts/lib/clean-common.sh | 54 +++++++++++++++---- 2 files changed, 81 insertions(+), 11 deletions(-) diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh index 922059ecf05..46901d58b72 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh @@ -247,6 +247,44 @@ else chmod u+w "$TEST_TMPDIR/r2/.mypy_cache" 2>/dev/null || true fi +# --- dry-run/apply consistency + honest byte accounting (fresh repo) --- +git init "$TEST_TMPDIR/r3" >/dev/null 2>&1 +git -C "$TEST_TMPDIR/r3" config user.email "t@example.com" +git -C "$TEST_TMPDIR/r3" config user.name "Test" +run_r3() { bash -c "cd '$TEST_TMPDIR/r3' && bash '$CLEAN' $*"; } + +# 12. A file (or symlink) whose name matches an explicit cache dir must NOT be +# planned: the dry-run only emits what --apply will accept, so a file named +# `.pytest_cache` is filtered at planning, keeping the plan applyable. +echo f >"$TEST_TMPDIR/r3/.pytest_cache" # a FILE named like a cache DIR +out="$(run_r3 --dry-run --manifest "$TEST_TMPDIR/r3.m")" +assert_contains "file-named explicit cache not planned" "$out" "Summary: planned=0" +assert_file_exists "file-named explicit cache untouched by dry-run" "$TEST_TMPDIR/r3/.pytest_cache" +rm -f "$TEST_TMPDIR/r3/.pytest_cache" + +# 13. Reclaimed bytes come from the filesystem at apply, not the manifest's byte +# field — a caller-supplied inflated value must not reach the summary. +mkdir -p "$TEST_TMPDIR/r3/.ruff_cache" +head -c 4000 /dev/urandom >"$TEST_TMPDIR/r3/.ruff_cache/blob" 2>/dev/null || echo x >"$TEST_TMPDIR/r3/.ruff_cache/blob" +printf 'caches\t999999999\t.ruff_cache\n' >"$TEST_TMPDIR/r3.inflated.manifest" +out="$(run_r3 --apply --manifest "$TEST_TMPDIR/r3.inflated.manifest")" +rc=$? +assert_contains "target removed" "$out" "Removed: .ruff_cache" +assert_not_contains "inflated manifest byte field not trusted" "$out" "bytes=999999999" +assert_exit "recompute apply exit 0" 0 "$rc" + +# 14. A path containing a tab/newline cannot be encoded in the tab-delimited +# manifest, so it is skipped with a warning rather than mis-mapped. Skips +# where the FS cannot create such a name (NTFS rejects some characters). +if mkdir -p "$TEST_TMPDIR/r3/od$(printf '\t')d/__pycache__" 2>/dev/null; then + echo p >"$TEST_TMPDIR/r3/od$(printf '\t')d/__pycache__/p" + out="$(run_r3 --dry-run --manifest "$TEST_TMPDIR/r3.tab.manifest" 2>&1)" + assert_contains "unencodable path skipped" "$out" "Skip (unencodable path):" + assert_not_contains "unencodable path not manifested" "$(cat "$TEST_TMPDIR/r3.tab.manifest")" "__pycache__" +else + skip_case "unencodable path — FS rejects tab in a filename here" +fi + if [[ $FAILED -ne 0 ]]; then echo "FAILED: $FAILED test(s)" exit 1 diff --git a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh index 789397b38e0..4d6889efd1f 100644 --- a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh @@ -199,7 +199,9 @@ clean_path_is_reparse_point() { local path="$1" [[ -L "$path" ]] && return 0 if command -v fsutil >/dev/null 2>&1 && command -v cygpath >/dev/null 2>&1; then - fsutil reparsepoint query "$(cygpath -w "$path")" >/dev/null 2>&1 && return 0 + # `/dev/null 2>&1 && return 0 fi return 1 } @@ -287,8 +289,13 @@ clean_enumerate() { # build-tier's --include-caches path, so the two never drift. clean_caches_candidates() { local root="$1" rel - for rel in "${CLEAN_CACHE_EXPLICIT[@]}"; do printf '%s\n' "$root/$rel"; done - for rel in "${CLEAN_CACHE_EXPLICIT_FILES[@]}"; do printf '%s\n' "$root/$rel"; done + # Explicit repo-root paths bypass `find`'s `-type` filter, so apply the same + # type check here (explicit dirs must be plain dirs, explicit files plain + # files) — otherwise a file or symlink named e.g. `.pytest_cache` would be + # planned at dry-run but rejected at --apply, making the advertised plan + # unapplyable. + for rel in "${CLEAN_CACHE_EXPLICIT[@]}"; do clean_is_plain_dir "$root/$rel" && printf '%s\n' "$root/$rel"; done + for rel in "${CLEAN_CACHE_EXPLICIT_FILES[@]}"; do clean_is_plain_file "$root/$rel" && printf '%s\n' "$root/$rel"; done clean_enumerate "$root" "${CLEAN_CACHE_FIND_DIR_NAMES[@]}" -- "${CLEAN_CACHE_FIND_FILE_GLOBS[@]}" } @@ -375,6 +382,18 @@ clean_plan() { abs="${CLEAN_CAND_ABS[$i]}" class="${CLEAN_CAND_CLASS[$i]}" [[ -e "$abs" ]] || continue + # The manifest is tab-delimited and newline-terminated; a path containing + # either cannot be encoded unambiguously and would corrupt both the dedup + # parse below and the record #994 consumes. Pathological for build/cache + # artifacts — skip with a visible warning rather than emit a record that maps + # to the wrong path at --apply. + case "$abs" in + *$'\t'* | *$'\n'*) + printf 'Skip (unencodable path): %s\n' "${abs#"$root"/}" >&2 + continue + ;; + *) ;; + esac if skip="$(clean_target_eligible "$root" "$abs")"; then elig_abs+=("$abs") elig_class+=("$class") @@ -389,7 +408,9 @@ clean_plan() { # path with a trailing '/' key so an ancestor sorts immediately before ALL its # descendants and they stay contiguous (the '/' also stops `build` swallowing a # sibling `buildstuff` — `buildstuff/` does not start with `build/`), then skip - # anything under the last kept ancestor in a single pass. + # anything under the last kept ancestor in a single pass. Inputs never carry a + # trailing slash (find never emits one; explicit paths are root-joined), so the + # single appended '/' is unambiguous. local -a surv_abs=() surv_class=() local last_key="" key while IFS=$'\t' read -r key abs class; do @@ -520,17 +541,22 @@ clean_manifest_target_valid() { # must be one this tier produces (ALLOWED, space-separated), the path must be # repo-contained (no `..`/absolute), outside every pruned tree (enumeration never # descends CLEAN_PRUNE_DIRS, so a `.git/...` entry is never one it emitted) AND a -# real target of the right type for its class (not an arbitrary untracked path), -# and the byte field must be an unsigned decimal before it reaches Bash -# arithmetic (which evaluates array subscripts recursively). +# real target of the right type for its class (not an arbitrary untracked path). +# The reclaimed-bytes total is re-measured from the filesystem at removal time, +# so the manifest's byte field never reaches summary arithmetic — a caller value +# cannot inject (array subscripts evaluate recursively) or overflow it. # clean_apply_manifest ROOT MANIFEST ALLOWED_CLASSES clean_apply_manifest() { local root="$1" manifest="$2" allowed="${3:-}" local class bytes rel abs skip + # Read the manifest on a dedicated fd (3), not stdin: a per-entry validator can + # shell out to a tool that drains stdin (e.g. `fsutil` in the reparse-point + # check), which on fd 0 would swallow the rest of the manifest and silently + # skip every entry after the first. # `|| [[ -n … ]]` processes a final record with no trailing newline (common in # caller-written files) instead of dropping it — dropping it would report a # cleanup as done while leaving it undone. - while IFS=$'\t' read -r class bytes rel || [[ -n "$class$bytes$rel" ]]; do + while IFS=$'\t' read -r class bytes rel <&3 || [[ -n "$class$bytes$rel" ]]; do if [[ -z "$rel" ]]; then # A deliberately blank line is ignored; a nonblank but truncated record # (missing the path field, e.g. a partial write by a concurrent process) is @@ -565,20 +591,26 @@ clean_apply_manifest() { CLEAN_FAILED_COUNT=$((CLEAN_FAILED_COUNT + 1)) continue fi - [[ "$bytes" =~ ^[0-9]+$ ]] || bytes=0 if ! skip="$(clean_target_eligible "$root" "$abs")"; then [[ -n "$skip" ]] && printf '%s\n' "$skip" continue fi + # Reclaimed bytes are re-measured from the filesystem now, not read from the + # manifest's dry-run byte field: the target may have grown/shrunk since the + # plan, and this also keeps a caller-supplied field out of the summary + # arithmetic entirely (no overflow/wrap, no evaluation of untrusted input). + local kb + kb="$(du -sk "$abs" 2>/dev/null | awk '{print $1}')" + [[ "$kb" =~ ^[0-9]+$ ]] || kb=0 if rm -rf "$abs" 2>/dev/null; then printf 'Removed: %s\n' "$rel" CLEAN_REMOVED_COUNT=$((CLEAN_REMOVED_COUNT + 1)) - CLEAN_REMOVED_BYTES=$((CLEAN_REMOVED_BYTES + bytes)) + CLEAN_REMOVED_BYTES=$((CLEAN_REMOVED_BYTES + kb * 1024)) else printf 'Unremovable: %s\n' "$rel" >&2 CLEAN_FAILED_COUNT=$((CLEAN_FAILED_COUNT + 1)) fi - done <"$manifest" + done 3<"$manifest" } # Return 0 when PATH is safe to (re)write as a manifest: absent, or an existing From 4d8b060be25eeaed095afe435cf9646faf79dffc Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 15:17:46 -0400 Subject: [PATCH 13/21] style(repo-hygiene): drop issue-ref from manifest-encoding comment Comment-hygiene forbids tracker references in code comments; reword to name the downstream consumer generically. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- .../repo-hygiene/skills/clean/scripts/lib/clean-common.sh | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh index 4d6889efd1f..08ac179a792 100644 --- a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh @@ -384,9 +384,9 @@ clean_plan() { [[ -e "$abs" ]] || continue # The manifest is tab-delimited and newline-terminated; a path containing # either cannot be encoded unambiguously and would corrupt both the dedup - # parse below and the record #994 consumes. Pathological for build/cache - # artifacts — skip with a visible warning rather than emit a record that maps - # to the wrong path at --apply. + # parse below and the record a downstream consumer parses. Pathological for + # build/cache artifacts — skip with a visible warning rather than emit a + # record that maps to the wrong path at --apply. case "$abs" in *$'\t'* | *$'\n'*) printf 'Skip (unencodable path): %s\n' "${abs#"$root"/}" >&2 From 9b14290de1984827da0a1206372dd6ac000eaa82 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 15:29:09 -0400 Subject: [PATCH 14/21] style(repo-hygiene): fix spell-check hits in comments `typos` flagged `applyable` and `mis-mapped` in the new comments; reword to plain phrasing ("the plan can still be applied", "not mapped to a wrong path"). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- .../repo-hygiene/skills/clean/scripts/clean-caches.test.sh | 4 ++-- plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh index 46901d58b72..76088c02ecc 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh @@ -255,7 +255,7 @@ run_r3() { bash -c "cd '$TEST_TMPDIR/r3' && bash '$CLEAN' $*"; } # 12. A file (or symlink) whose name matches an explicit cache dir must NOT be # planned: the dry-run only emits what --apply will accept, so a file named -# `.pytest_cache` is filtered at planning, keeping the plan applyable. +# `.pytest_cache` is filtered at planning, so the plan can still be applied. echo f >"$TEST_TMPDIR/r3/.pytest_cache" # a FILE named like a cache DIR out="$(run_r3 --dry-run --manifest "$TEST_TMPDIR/r3.m")" assert_contains "file-named explicit cache not planned" "$out" "Summary: planned=0" @@ -274,7 +274,7 @@ assert_not_contains "inflated manifest byte field not trusted" "$out" "bytes=999 assert_exit "recompute apply exit 0" 0 "$rc" # 14. A path containing a tab/newline cannot be encoded in the tab-delimited -# manifest, so it is skipped with a warning rather than mis-mapped. Skips +# manifest, so it is skipped with a warning, not mapped to a wrong path. Skips # where the FS cannot create such a name (NTFS rejects some characters). if mkdir -p "$TEST_TMPDIR/r3/od$(printf '\t')d/__pycache__" 2>/dev/null; then echo p >"$TEST_TMPDIR/r3/od$(printf '\t')d/__pycache__/p" diff --git a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh index 08ac179a792..379b6ac2761 100644 --- a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh @@ -292,8 +292,8 @@ clean_caches_candidates() { # Explicit repo-root paths bypass `find`'s `-type` filter, so apply the same # type check here (explicit dirs must be plain dirs, explicit files plain # files) — otherwise a file or symlink named e.g. `.pytest_cache` would be - # planned at dry-run but rejected at --apply, making the advertised plan - # unapplyable. + # planned at dry-run but rejected at --apply, so the advertised plan could not + # be applied. for rel in "${CLEAN_CACHE_EXPLICIT[@]}"; do clean_is_plain_dir "$root/$rel" && printf '%s\n' "$root/$rel"; done for rel in "${CLEAN_CACHE_EXPLICIT_FILES[@]}"; do clean_is_plain_file "$root/$rel" && printf '%s\n' "$root/$rel"; done clean_enumerate "$root" "${CLEAN_CACHE_FIND_DIR_NAMES[@]}" -- "${CLEAN_CACHE_FIND_FILE_GLOBS[@]}" From c84086d3a959b16126d360ed9f8263d492298243 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 15:39:29 -0400 Subject: [PATCH 15/21] fix(repo-hygiene): reject manifest paths through a symlinked ancestor MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `..`/absolute containment guard and the final-component reparse check did not cover a symlinked ANCESTOR: a manifest naming `link/__pycache__`, where `link` points outside the repo, passed every check and `rm -rf` followed the ancestor symlink to delete the external directory while reporting success. Enumeration uses `find -type d`, which never descends a symlinked dir, so such a path is never one the dry-run emitted. Apply now walks every component of `root/rel` and rejects the entry (fail closed) if any ancestor or the target is a symlink/reparse point — junction-aware via the existing fsutil check, so it also catches Windows reparse-point ancestors that `realpath`/`-L` miss. Regression test covers a symlinked ancestor pointing outside the repo (skips where the FS cannot create a symlink). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- .../skills/clean/scripts/clean-caches.test.sh | 17 ++++++++++ .../skills/clean/scripts/lib/clean-common.sh | 32 +++++++++++++++++-- 2 files changed, 46 insertions(+), 3 deletions(-) diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh index 76088c02ecc..15aeff22ae6 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh @@ -247,6 +247,23 @@ else chmod u+w "$TEST_TMPDIR/r2/.mypy_cache" 2>/dev/null || true fi +# A symlinked ANCESTOR must not let rm follow a manifest path out of the repo: +# `link/__pycache__` where `link` points outside is rejected, the outside dir +# preserved. Enumeration never descends a symlinked dir, so this is never planned. +mkdir -p "$TEST_TMPDIR/escape_victim/__pycache__" +echo s >"$TEST_TMPDIR/escape_victim/__pycache__/s" +ln -s "$TEST_TMPDIR/escape_victim" "$TEST_TMPDIR/r2/link" 2>/dev/null || true +if [[ -L "$TEST_TMPDIR/r2/link" ]]; then + printf 'caches\t1\tlink/__pycache__\n' >"$TEST_TMPDIR/r2.ancestor.manifest" + out="$(run_r2 --apply --manifest "$TEST_TMPDIR/r2.ancestor.manifest" 2>&1)" + rc=$? + assert_contains "symlinked ancestor rejected" "$out" "Rejected (symlinked ancestor): link/__pycache__" + assert_exit "symlinked ancestor exits non-zero" 1 "$rc" + assert_file_exists "outside dir preserved through symlinked ancestor" "$TEST_TMPDIR/escape_victim/__pycache__/s" +else + skip_case "symlinked ancestor — symlinks not creatable here" +fi + # --- dry-run/apply consistency + honest byte accounting (fresh repo) --- git init "$TEST_TMPDIR/r3" >/dev/null 2>&1 git -C "$TEST_TMPDIR/r3" config user.email "t@example.com" diff --git a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh index 379b6ac2761..e8af25d7e11 100644 --- a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh @@ -462,6 +462,26 @@ clean_manifest_rel_safe() { esac } +# Return 0 when any component of ROOT/REL (an ancestor directory OR the target) +# is a symlink or reparse point. `..`-rejection stops textual escapes, but a +# manifest naming `link/__pycache__` where `link` points outside the repo would +# otherwise let `rm -rf` follow the ancestor out of the tree. Enumeration uses +# `find -type d`, which never descends a symlinked dir, so such a path is never +# one the dry-run emitted — reject it. Junction-aware (fsutil), so it also +# catches Windows reparse-point ancestors that `realpath`/`-L` miss. +clean_path_has_reparse_ancestor() { + local root="$1" seg + local cur="$root" + local -a parts + IFS=/ read -r -a parts <<<"${2//\\//}" + for seg in "${parts[@]}"; do + [[ -z "$seg" ]] && continue + cur="$cur/$seg" + clean_path_is_reparse_point "$cur" && return 0 + done + return 1 +} + # Return 0 when a repo-relative path lies within a pruned tree (a # CLEAN_PRUNE_DIRS segment). Enumeration never descends these, so a manifest # entry inside one — e.g. `.git/...`, whose removal could corrupt the repo — is @@ -539,9 +559,10 @@ clean_manifest_target_valid() { # manifest is untrusted input (a caller supplies it, or a concurrent process may # alter it): every entry is validated before its path is acted on — the class # must be one this tier produces (ALLOWED, space-separated), the path must be -# repo-contained (no `..`/absolute), outside every pruned tree (enumeration never -# descends CLEAN_PRUNE_DIRS, so a `.git/...` entry is never one it emitted) AND a -# real target of the right type for its class (not an arbitrary untracked path). +# repo-contained (no `..`/absolute, no symlinked ancestor that `rm -rf` could +# follow out of the repo), outside every pruned tree (enumeration never descends +# CLEAN_PRUNE_DIRS, so a `.git/...` entry is never one it emitted) AND a real +# target of the right type for its class (not an arbitrary untracked path). # The reclaimed-bytes total is re-measured from the filesystem at removal time, # so the manifest's byte field never reaches summary arithmetic — a caller value # cannot inject (array subscripts evaluate recursively) or overflow it. @@ -586,6 +607,11 @@ clean_apply_manifest() { # failure nor a re-removal — skip before target/type validation (which needs # the path to exist). [[ -e "$abs" ]] || continue + if clean_path_has_reparse_ancestor "$root" "$rel"; then + printf 'Rejected (symlinked ancestor): %s\n' "$rel" >&2 + CLEAN_FAILED_COUNT=$((CLEAN_FAILED_COUNT + 1)) + continue + fi if ! clean_manifest_target_valid "$class" "$rel" "$abs"; then printf 'Rejected (not a %s target): %s\n' "$class" "$rel" >&2 CLEAN_FAILED_COUNT=$((CLEAN_FAILED_COUNT + 1)) From bd20952ba3ca0b888a7fe013f71d8462e0290951 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 15:48:54 -0400 Subject: [PATCH 16/21] fix(repo-hygiene): unify symlinked-path rejection message MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The new symlinked-ancestor walk also catches a symlinked final target (it walks every component including the leaf), which fires before the type check — so a symlinked `.turbo` is now rejected as a symlinked path, not "not a caches target". Rename the marker to `Rejected (symlinked path)` (accurate for both a symlinked ancestor and a symlinked target) and align the two symlink regression tests, which now run on Linux CI. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- .../repo-hygiene/skills/clean/scripts/clean-caches.test.sh | 4 ++-- plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh index 15aeff22ae6..e09da02a65a 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/clean-caches.test.sh @@ -219,7 +219,7 @@ if [[ -L "$TEST_TMPDIR/r2/.turbo" ]]; then printf 'caches\t1\t.turbo\n' >"$TEST_TMPDIR/r2.symlink.manifest" out="$(run_r2 --apply --manifest "$TEST_TMPDIR/r2.symlink.manifest" 2>&1)" rc=$? - assert_contains "symlinked dir target rejected" "$out" "Rejected (not a caches target): .turbo" + assert_contains "symlinked dir target rejected" "$out" "Rejected (symlinked path): .turbo" assert_exit "symlink apply exits non-zero" 1 "$rc" assert_file_exists "symlink target contents preserved" "$TEST_TMPDIR/r2/realcache/c" else @@ -257,7 +257,7 @@ if [[ -L "$TEST_TMPDIR/r2/link" ]]; then printf 'caches\t1\tlink/__pycache__\n' >"$TEST_TMPDIR/r2.ancestor.manifest" out="$(run_r2 --apply --manifest "$TEST_TMPDIR/r2.ancestor.manifest" 2>&1)" rc=$? - assert_contains "symlinked ancestor rejected" "$out" "Rejected (symlinked ancestor): link/__pycache__" + assert_contains "symlinked ancestor rejected" "$out" "Rejected (symlinked path): link/__pycache__" assert_exit "symlinked ancestor exits non-zero" 1 "$rc" assert_file_exists "outside dir preserved through symlinked ancestor" "$TEST_TMPDIR/escape_victim/__pycache__/s" else diff --git a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh index e8af25d7e11..df653dffcc5 100644 --- a/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/lib/clean-common.sh @@ -608,7 +608,7 @@ clean_apply_manifest() { # the path to exist). [[ -e "$abs" ]] || continue if clean_path_has_reparse_ancestor "$root" "$rel"; then - printf 'Rejected (symlinked ancestor): %s\n' "$rel" >&2 + printf 'Rejected (symlinked path): %s\n' "$rel" >&2 CLEAN_FAILED_COUNT=$((CLEAN_FAILED_COUNT + 1)) continue fi From a331f34f08573cb0de7ecdef3fe3787d9d5e0e99 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 15:22:13 -0400 Subject: [PATCH 17/21] feat(repo-hygiene): stash audit, worktree/no-upstream branch classes, single-walk scan, resolver notes Add a stash audit action and script (age, source branch, diffstat, PR/merge signal, per-stash keep/drop advisory; never auto-drops; deduped across linked worktrees by --git-common-dir). Give branches checked out in a linked worktree their own WORKTREE bucket routed to the worktree tool, and surface never-pushed branches' unpushed commits (no-upstream count vs origin/) as their own class plus an Unpushed line. Migrate scan.sh's per-pattern unpruned find walks onto the shared clean_enumerate engine so the read-only inventory and the mutating tiers share one prune set. Teach the resolver to echo trailing free text after an action token as an advisory Note. Closes #996 Closes #997 Closes #998 Closes #1000 Closes #1011 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- .../repo-hygiene/.claude-plugin/plugin.json | 2 +- plugins/repo-hygiene/CHANGELOG.md | 43 +++++++ plugins/repo-hygiene/skills/clean/SKILL.md | 15 ++- .../skills/clean/context/action-router.md | 9 +- .../clean/context/git-branch-cleanup.md | 41 +++--- .../skills/clean/scripts/git-branch-audit.sh | 49 +++++++- .../clean/scripts/git-branch-audit.test.sh | 62 ++++++++++ .../skills/clean/scripts/git-stash-audit.sh | 117 ++++++++++++++++++ .../clean/scripts/git-stash-audit.test.sh | 76 ++++++++++++ .../skills/clean/scripts/lib/cleanup-paths.sh | 10 +- .../clean/scripts/resolve-clean-action.sh | 72 ++++++++--- .../scripts/resolve-clean-action.test.sh | 32 +++++ .../repo-hygiene/skills/clean/scripts/scan.sh | 70 +++-------- .../skills/clean/scripts/scan.test.sh | 11 ++ 14 files changed, 499 insertions(+), 110 deletions(-) create mode 100644 plugins/repo-hygiene/skills/clean/scripts/git-stash-audit.sh create mode 100644 plugins/repo-hygiene/skills/clean/scripts/git-stash-audit.test.sh diff --git a/plugins/repo-hygiene/.claude-plugin/plugin.json b/plugins/repo-hygiene/.claude-plugin/plugin.json index 5d95568b6bd..a45c61c0ed8 100644 --- a/plugins/repo-hygiene/.claude-plugin/plugin.json +++ b/plugins/repo-hygiene/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "repo-hygiene", - "version": "0.5.0", + "version": "0.6.0", "description": "Repo hygiene action-router: /repo-hygiene:clean sweeps reclaimable caches, build artifacts, and stale git metadata, and can realign the working tree to a fresh-pull state — dry-run-first, with destructive tiers gated behind explicit confirmation and a session-scoped destructive-command guard. Ecosystem targets are detected at runtime; secrets, runtime dependencies, and skill data are preserved by default.", "author": { "name": "Melodic Software", diff --git a/plugins/repo-hygiene/CHANGELOG.md b/plugins/repo-hygiene/CHANGELOG.md index b3838e65226..7dd456babba 100644 --- a/plugins/repo-hygiene/CHANGELOG.md +++ b/plugins/repo-hygiene/CHANGELOG.md @@ -3,6 +3,49 @@ All notable changes to the `repo-hygiene` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.6.0] + +### Added + +- **`stash` action — stash audit and triage across every tier that previously + ignored stashes.** `git-stash-audit.sh` reports each stash's age, source + branch, diffstat, and a PR/merge signal, with a per-stash keep/drop advisory — + and **never drops a stash**; the agent confirms keep-or-drop per entry. A + `possibly superseded` / `likely superseded` advisory (source branch merged into + `origin/` or via a merged PR) is a hint to raise first, never an + autonomous drop. Deduped across linked worktrees by the `--git-common-dir` + `StashStore:` key (worktrees share one stash ref). Runs standalone (`stash`) + and as part of the `git` tier. (#996) +- **Branch audit now surfaces unpushed commits per branch, including no-upstream + branches.** A new `Unpushed:` line reports `N ahead of ` or, for a + never-pushed branch, `no upstream, M commits not on origin/` — the + latter is invisible to `@{upstream}`-based ahead reporting, so unmerged local + work no longer goes unseen. Such branches form their own REVIEW class ranked + above generic stale/orphaned, so the unpushed-commit count is the headline. + (#998) +- **The resolver echoes trailing free text as a `Note:` line.** When a leading + action token is followed by a question or a live-session constraint (e.g. + `all mind the 6 live sessions`), the remainder is emitted as advisory context + the agent must address, instead of being silently dropped during action + resolution. (#1000) + +### Changed + +- **Branches checked out in a linked worktree are their own `WORKTREE` bucket, no + longer folded into `PROTECTED`.** Such a branch is a real cleanup candidate but + `git branch -d` on it fails or, forced, breaks the worktree — so it is + subtracted from the deletion set and routed to the worktree-management tool + ("clean up the worktree first") rather than mislabeled untouchable. The + protected-name checks now rank above the worktree check so a `release/*` or + default branch checked out in a worktree stays PROTECTED. `Summary:` gains a + `worktree=` count. (#997) +- **`scan.sh` enumerates through the shared single pruned-walk engine.** The + read-only inventory dropped its per-pattern unpruned `find` walks (which still + descended `.git/`, `node_modules/`, `.venv/` despite `! -path` filters) for + `clean_caches_candidates` / `clean_build_candidates`, so the scan and the + mutating caches/build tiers now share one enumeration way and one prune set. + (#1011) + ## [0.5.0] ### Fixed diff --git a/plugins/repo-hygiene/skills/clean/SKILL.md b/plugins/repo-hygiene/skills/clean/SKILL.md index de41efc0018..3345d340e86 100644 --- a/plugins/repo-hygiene/skills/clean/SKILL.md +++ b/plugins/repo-hygiene/skills/clean/SKILL.md @@ -1,8 +1,8 @@ --- name: clean -description: "Repo hygiene action-router: scan (inventory), caches, build, git (prune/branch audit), tree (destructive fresh-pull reset), tree-batch (multi-repo tree reset with skip-list + dirty guard), all. Bare invocation detects intent from conversation or shows a menu. Dry-run-first; destructive actions require explicit confirmation. Use when: clean, disk space, remove caches, build artifacts, fresh pull, fresh clone state, reset to origin, reset all my repos, stale branches, repo hygiene. Skip: removing git worktree directories (a worktree-management tool handles those)." +description: "Repo hygiene action-router: scan (inventory), caches, build, git (prune/branch audit), stash (stash audit/triage), tree (destructive fresh-pull reset), tree-batch (multi-repo tree reset with skip-list + dirty guard), all. Bare invocation detects intent from conversation or shows a menu. Dry-run-first; destructive actions require explicit confirmation. Use when: clean, disk space, remove caches, build artifacts, fresh pull, fresh clone state, reset to origin, reset all my repos, stale branches, stashes, repo hygiene. Skip: removing git worktree directories (a worktree-management tool handles those)." user-invocable: true -argument-hint: "[scan|caches|build|git|tree|tree-batch|all|aliases…] (bare → menu or auto-detect)" +argument-hint: "[scan|caches|build|git|stash|tree|tree-batch|all|aliases…] (bare → menu or auto-detect)" allowed-tools: - Bash(bash ${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/*) hooks: @@ -38,6 +38,8 @@ Bare invocation never mutates silently: resolve intent → dry-run → user conf bash ${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/resolve-clean-action.sh $ARGUMENTS ``` +When a leading action token is followed by free text, the resolver also emits a `Note: ` line. That note is **advisory context you must address** — a question to answer (e.g. "does this include stashes?") or a live-session constraint to honor (e.g. "6-7 live sessions, mind WIP") — not part of action selection. Surface it and act on it alongside the resolved action; never silently drop it. + ### Bare invocation (empty args) 1. Infer from conversation (fresh pull → `tree`, disk space → `scan`, … — see action-router). @@ -51,7 +53,8 @@ bash ${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/resolve-clean-action.sh $ARGUMEN | `scan` | Show what's reclaimable | Safe | No | — | | `caches` | Clear tool and linter caches | Low | Yes | — | | `build` | Clear build output and logs | Low | Yes (includes caches) | — | -| `git` | Prune stale git metadata; audit branches | Low | No | Yes | +| `git` | Prune stale git metadata; audit branches + stashes | Low | No | Yes | +| `stash` | Audit and triage stashes (age, source, diffstat) | Safe | No | — | | `tree` | Reset working tree like a fresh pull | **Destructive** | No (always dry-run first) | **Never** | | `tree-batch` | Reset many repos like a fresh pull (skip-list + dirty guard) | **Destructive** | No (always dry-run first) | **Never** | | `all` | Sweep caches + build + git hygiene | Medium | Yes | — | @@ -118,7 +121,11 @@ Both selective mutating tiers pay the filesystem walk **once**. `--dry-run` writ #### 4.2 Branch audit -`bash ${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/git-branch-audit.sh` — deletion via `AskUserQuestion` per [context/git-branch-cleanup.md](context/git-branch-cleanup.md). +`bash ${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/git-branch-audit.sh` — deletion via `AskUserQuestion` per [context/git-branch-cleanup.md](context/git-branch-cleanup.md). Branches in the `WORKTREE` tier are checked out in a linked worktree: never offer them for `git branch -d` — route the user to the worktree-management tool to clean up the worktree first. Branches carrying `no upstream, M commits not on origin/` are never-pushed local work — surface the count and confirm before any deletion. + +#### 4.3 Stash audit + +`bash ${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/git-stash-audit.sh` — read-only per-stash facts (age, source branch, diffstat, PR/merge signal, advisory). **Never drops a stash.** Present the list and, for each stash, ask the user keep-or-drop via `AskUserQuestion`; a `possibly superseded` / `likely superseded` advisory is a hint to raise first, never an autonomous drop. Dedup a fleet sweep by the `StashStore:` key (linked worktrees share one stash ref). When the resolved action is `stash`, run only this step. ### 5. All diff --git a/plugins/repo-hygiene/skills/clean/context/action-router.md b/plugins/repo-hygiene/skills/clean/context/action-router.md index fe7a2e12e78..37f8e791c52 100644 --- a/plugins/repo-hygiene/skills/clean/context/action-router.md +++ b/plugins/repo-hygiene/skills/clean/context/action-router.md @@ -9,7 +9,8 @@ SKILL.md carries the action table headline; this file carries alias resolution, | `scan` | "Show what's reclaimable" | Read-only inventory | Safe | N/A (no mutation) | | `caches` | "Clear tool and linter caches" | `.pytest_cache/`, `.ruff_cache/`, `__pycache__/`, … | Low | **Never** | | `build` | "Clear build output and logs" | `bin/`, `obj/`, `dist/`, `*.binlog`, … | Low | **Never** | -| `git` | "Prune stale git metadata" | `worktree prune`, `remote prune`, `gc`, branch audit | Low | Prune/gc only after user OK; branch delete always opt-in | +| `git` | "Prune stale git metadata" | `worktree prune`, `remote prune`, `gc`, branch audit, stash audit | Low | Prune/gc only after user OK; branch delete always opt-in | +| `stash` | "Audit and triage my stashes" | Read-only per-stash facts (age, source branch, diffstat, PR/merge signal) | Safe | **Never** drops — keep/drop confirmed per stash | | `tree` | "Reset working tree like a fresh pull" | `fetch` + `reset --hard` upstream + `clean -fdx` (default-preserve secrets/deps/skill-data; `--include-deps` / `--include-secrets` to widen) | **Destructive** | **Never** | | `tree-batch` | "Reset all my repos like a fresh pull" | `tree` across a repo set behind one gate; separator-agnostic skip list; dirty/unpushed skipped unless `--include-dirty` | **Destructive** | **Never** | | `all` | "Sweep caches, build artifacts, and git hygiene" | `build` + `git` (not `tree`) | Medium | **Never** | @@ -22,7 +23,7 @@ SKILL.md carries the action table headline; this file carries alias resolution, bash ${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/resolve-clean-action.sh ``` -Emits `Action: `. Single-token aliases: +Emits `Action: `, plus an optional `Note: ` line when a leading action token is trailed by free text (a question or a live-session constraint) — advisory context the agent must address, never part of resolution. Single-token aliases: | Tokens → | Action | | --- | --- | @@ -30,6 +31,7 @@ Emits `Action: `. Single-token aliases: | `cache`, `caches`, `linter-caches`, `linter` | `caches` | | `build`, `artifacts`, `artifact`, `bin`, `obj`, `output` | `build` | | `git`, `branches`, `branch`, `prune`, `gc` | `git` | +| `stash`, `stashes`, `stash-audit` | `stash` | | `tree`, `fresh`, `fresh-pull`, `fresh-pull-state`, `pristine`, `reset-tree`, `working-tree` | `tree` | | `tree-batch`, `batch`, `fleet`, `multi-repo`, `reset-all` | `tree-batch` | | `all`, `sweep`, `everything` | `all` | @@ -54,7 +56,8 @@ Default when still unsure after one question: **`scan`** (safest). | --- | --- | --- | | `scan` | Run `scan.sh` | None | | `caches`, `build`, `all` | `preflight.sh` + tier scripts `--dry-run` (writes a manifest; emits `Manifest:` + `Summary: planned=N bytes=K`) | `AskUserQuestion` when preflight non-empty OR before `--apply` — surface the `bytes` reclaimable total; apply the same manifest (`--apply --manifest `), which emits `Summary: removed=N failed=M bytes=K` and exits non-zero on failure | -| `git` | `git-prune.sh --dry-run`, `git-branch-audit.sh` | Before `--apply` prune; before any branch deletion | +| `git` | `git-prune.sh --dry-run`, `git-branch-audit.sh`, `git-stash-audit.sh` | Before `--apply` prune; before any branch deletion; per-stash keep/drop | +| `stash` | `git-stash-audit.sh` (read-only) | Per-stash keep/drop — **never** auto-dropped, even a `superseded` advisory | | `tree` | `git-tree-reset.sh --dry-run` (always) | **Mandatory** `AskUserQuestion` before `--apply` (surface `PreserveDeps`/`PreserveSecrets`/`AheadCount`); a non-zero `AheadCount` or exit 4 needs explicit unpushed-loss confirmation before `--allow-unpushed`; `--include-secrets` is UNRECOVERABLE — confirm separately; never autonomous | | `tree-batch` | `git-tree-reset-batch.sh --dry-run` (always) | **Mandatory** single batch-wide `AskUserQuestion` before `--apply` (surface the per-repo `Outcome`/`Reason`, `Summary`, and `UnmatchedSkip:`); one gate for the whole batch, never per repo; `--include-dirty` re-enables the data-loss vector — confirm separately naming the dirty repos, like `--include-secrets`; never autonomous. Detail: [git-tree-reset-batch.md](git-tree-reset-batch.md) | diff --git a/plugins/repo-hygiene/skills/clean/context/git-branch-cleanup.md b/plugins/repo-hygiene/skills/clean/context/git-branch-cleanup.md index 606f9fc9289..90d0f58d2c2 100644 --- a/plugins/repo-hygiene/skills/clean/context/git-branch-cleanup.md +++ b/plugins/repo-hygiene/skills/clean/context/git-branch-cleanup.md @@ -10,7 +10,9 @@ Run the branch-audit script — do not reimplement collection inline: bash ${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/git-branch-audit.sh ``` -**Output contract** (per branch): `Branch:`, `Tier:`, `Age days:`, `PR:`, `Reason:`; trailing `Summary: protected=… safe=… likely-safe=… review=…`. +**Output contract** (per branch): `Branch:`, `Tier:`, `Age days:`, `PR:`, `Unpushed:`, `Reason:`; trailing `Summary: protected=… worktree=… safe=… likely-safe=… review=…`. + +**`Unpushed:` line** — commits at risk of loss. With an upstream: `N ahead of `. With no upstream: `no upstream, M commits not on origin/` (or `no upstream (no origin/ to compare)` when the default branch is unfetched). Never-pushed local work is invisible to `@{upstream}`-based ahead reporting, so this line is the only signal that a no-upstream branch carries unmerged commits — surface it before offering any deletion. **Default branch resolution** (inside script): `origin/HEAD` symbolic ref → `gh repo view --json defaultBranchRef` → `main`. @@ -24,19 +26,24 @@ The script applies rules in priority order (first match wins). Agent interprets |----------|-----------|------|--------| | 1 | Branch = current | PROTECTED | current branch | | 2 | Branch = default | PROTECTED | default branch | -| 3 | Branch in worktree list | PROTECTED | worktree-attached | -| 4 | Branch glob-matches protected pattern (see list below) | PROTECTED | protected pattern | +| 3 | Branch glob-matches protected pattern (see list below) | PROTECTED | protected pattern | +| 4 | Branch checked out in a linked worktree | WORKTREE | checked out in worktree — clean up the worktree first | | 5 | `PR` = MERGED and local tip matches PR headRefOid | SAFE | PR merged | | 5b | `PR` = MERGED and local tip differs from headRefOid | REVIEW | PR merged but branch has commits since merge | | 6 | Branch in git `--merged` ancestry | SAFE | merged (non-squash) | | 7 | `PR` = CLOSED | REVIEW | PR closed without merge | | 8 | Upstream gone (`: gone]` in `branch -vv`) | LIKELY-SAFE | upstream deleted | -| 9 | Age > 90 days | REVIEW | stale | -| 10 | No PR, no tracking, not merged | REVIEW | orphaned | +| 9 | No upstream, M commits not on origin/default | REVIEW | no upstream, M commits not on origin/ | +| 10 | Age > 90 days | REVIEW | stale | +| 11 | No PR, no tracking, not merged | REVIEW | orphaned | Stale threshold: 90 days (`CLEAN_STALE_BRANCH_DAYS` in `cleanup-paths.sh`). Branch can match multiple REVIEW reasons — list all in report. -**Protected branch patterns (priority 4):** exact names and globs that MUST NEVER be offered for deletion — `main`, `master`, `develop`, `release/*`, `hotfix/*`. Matched via bash `case` in `clean_branch_matches_protected_pattern`. Extend with repo-specific long-lived branches if needed (e.g. `staging`, `production`, `deploy/*`). +**WORKTREE tier (priority 4)** — a branch checked out in a linked worktree is a real cleanup candidate (it may be merged or gone), but `git branch -d` on it fails or, forced, breaks the worktree. It is therefore its own bucket, distinct from PROTECTED: never offer it for deletion here — route the user to the worktree-management tool to remove the worktree first (after which a later audit reclassifies the branch on its merge/PR state). Priority 4 sits below the protected checks so a `release/*` or default branch that also happens to be checked out stays PROTECTED. + +**No-upstream class (priority 9)** — a never-pushed branch with commits not on `origin/` is unmerged local work; it ranks above the generic stale/orphaned REVIEW reasons so the unpushed-commit count is the headline. Stays REVIEW (never a deletion candidate) — confirm the commit loss explicitly before any deletion. + +**Protected branch patterns (priority 3):** exact names and globs that MUST NEVER be offered for deletion — `main`, `master`, `develop`, `release/*`, `hotfix/*`. Matched via bash `case` in `clean_branch_matches_protected_pattern`. Extend with repo-specific long-lived branches if needed (e.g. `staging`, `production`, `deploy/*`). **Squash-merge handling:** `git branch --merged` (priority 6) misses squash-merged branches because squash creates a new combined commit. `gh pr list` (priority 5) correctly detects these via PR state. When `gh` is unavailable, squash-merged branches land in REVIEW tier — safe-conservative handling. @@ -47,16 +54,18 @@ Map script output to a table: ```markdown ## Branch Audit -| Branch | Tier | Age | PR | Reason | -|--------|------|-----|----|--------| -| main | PROTECTED | 0d | — | default branch | -| worktree-worktree-2 | PROTECTED | 0d | — | current branch, worktree-attached | -| feat/old-thing | SAFE | 45d | #123 MERGED | PR merged | -| refactor/x | LIKELY-SAFE | 12d | — | upstream gone | -| experiment | REVIEW | 120d | — | stale (120d), orphaned | - -**Summary:** N protected, M safe, P likely-safe, Q review -**Deletion candidates (M+P):** +| Branch | Tier | Age | PR | Unpushed | Reason | +|--------|------|-----|----|----------|--------| +| main | PROTECTED | 0d | — | 0 ahead of origin/main | default branch | +| feat/parked | WORKTREE | 3d | — | 0 ahead of origin/feat/parked | checked out in worktree — clean up the worktree first | +| feat/old-thing | SAFE | 45d | #123 MERGED | 0 ahead of origin/feat/old-thing | PR merged | +| refactor/x | LIKELY-SAFE | 12d | — | no upstream (no origin/main to compare) | upstream gone | +| draft/local | REVIEW | 4d | — | no upstream, 5 commits not on origin/main | no upstream, 5 commits not on origin/main | +| experiment | REVIEW | 120d | — | 0 ahead of origin/experiment | stale (120d), orphaned | + +**Summary:** N protected, W worktree, M safe, P likely-safe, Q review +**Deletion candidates (M+P):** +**Worktree cleanup first:** ``` ## 4.7 Interactive deletion diff --git a/plugins/repo-hygiene/skills/clean/scripts/git-branch-audit.sh b/plugins/repo-hygiene/skills/clean/scripts/git-branch-audit.sh index bc6fdb7dd73..0ec7fe43ee8 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/git-branch-audit.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/git-branch-audit.sh @@ -2,7 +2,7 @@ # shellcheck disable=SC2154 # Branch audit facts for the clean git branch cleanup. No deletion. # -# Output: Branch, Tier, Age days, PR, Reason; Summary line. +# Output: Branch, Tier, Age days, PR, Unpushed, Reason; Summary line. # Exit: 0. # Omit -e/-o pipefail: script always exits 0; sub-commands are best-effort (gh may be absent). set -u @@ -62,11 +62,32 @@ WORKTREE_BRANCHES="$(git -C "$REPO_ROOT" worktree list --porcelain 2>/dev/null | GONE_BRANCHES="$(git -C "$REPO_ROOT" branch -vv 2>/dev/null | grep ': gone]' | awk '{print $1}' | tr -d '\r')" MERGED_BRANCHES="$(git -C "$REPO_ROOT" branch --merged "origin/${DEFAULT_BRANCH}" 2>/dev/null | sed 's/^[ *]*//' | grep -v "^${DEFAULT_BRANCH}$" | tr -d '\r' || true)" -prot=0 safe=0 likely=0 review=0 +prot=0 wt=0 safe=0 likely=0 review=0 NOW=$(date +%s) classify_branch() { local branch="$1" age_days="$2" tier reason pr_line="none" local_tip + local upstream no_upstream=0 ahead_default="" unpushed_line ahead_up + + # No-upstream branches are invisible to `@{upstream}`-based ahead/behind + # reporting (it yields nothing), so never-pushed local work goes unseen. Detect + # the missing upstream and, when origin/ exists, count the branch's + # commits absent from it — surfaced below as its own class and Unpushed line. + # `rev-parse --abbrev-ref` echoes its input to stdout on failure (no upstream + # configured, or a configured upstream whose tracking ref is unfetched), so gate + # on its exit status rather than on empty output — otherwise that echo reads as a + # real upstream. + if upstream="$(git -C "$REPO_ROOT" rev-parse --abbrev-ref "${branch}@{upstream}" 2>/dev/null)"; then + upstream="${upstream%$'\r'}" + else + upstream="" + fi + if [[ -z "$upstream" ]]; then + no_upstream=1 + if git -C "$REPO_ROOT" rev-parse --verify --quiet "refs/remotes/origin/${DEFAULT_BRANCH}" >/dev/null 2>&1; then + ahead_default="$(git -C "$REPO_ROOT" rev-list --count "origin/${DEFAULT_BRANCH}..refs/heads/${branch}" 2>/dev/null | tr -d '\r')" + fi + fi if [[ "$branch" == "$CURRENT_BRANCH" ]]; then tier="PROTECTED" @@ -74,12 +95,12 @@ classify_branch() { elif [[ "$branch" == "$DEFAULT_BRANCH" ]]; then tier="PROTECTED" reason="default branch" - elif grep -qxF "$branch" <<<"$WORKTREE_BRANCHES"; then - tier="PROTECTED" - reason="worktree-attached" elif clean_branch_matches_protected_pattern "$branch"; then tier="PROTECTED" reason="protected pattern" + elif grep -qxF "$branch" <<<"$WORKTREE_BRANCHES"; then + tier="WORKTREE" + reason="checked out in worktree — clean up the worktree first" elif [[ -n "${PR_STATE[$branch]:-}" && "${PR_STATE[$branch]}" == "MERGED" ]]; then local_tip="$(git -C "$REPO_ROOT" rev-parse "refs/heads/$branch" 2>/dev/null | tr -d '\r')" if [[ -n "${PR_REFOID[$branch]:-}" && -n "$local_tip" && "$local_tip" != "${PR_REFOID[$branch]}" ]]; then @@ -101,6 +122,9 @@ classify_branch() { elif grep -qxF "$branch" <<<"$GONE_BRANCHES"; then tier="LIKELY-SAFE" reason="upstream gone" + elif [[ "$no_upstream" == 1 && -n "$ahead_default" && "$ahead_default" -gt 0 ]]; then + tier="REVIEW" + reason="no upstream, ${ahead_default} commits not on origin/${DEFAULT_BRANCH}" elif [[ "$age_days" -gt "$CLEAN_STALE_BRANCH_DAYS" ]]; then tier="REVIEW" reason="stale (${age_days}d)" @@ -111,6 +135,7 @@ classify_branch() { case "$tier" in PROTECTED) prot=$((prot + 1)) ;; + WORKTREE) wt=$((wt + 1)) ;; SAFE) safe=$((safe + 1)) ;; LIKELY-SAFE) likely=$((likely + 1)) ;; *) review=$((review + 1)) ;; @@ -120,10 +145,22 @@ classify_branch() { pr_line="#${PR_NUM[$branch]} ${PR_STATE[$branch]}" fi + if [[ "$no_upstream" == 1 ]]; then + if [[ -n "$ahead_default" ]]; then + unpushed_line="no upstream, ${ahead_default} commits not on origin/${DEFAULT_BRANCH}" + else + unpushed_line="no upstream (no origin/${DEFAULT_BRANCH} to compare)" + fi + else + ahead_up="$(git -C "$REPO_ROOT" rev-list --count "${branch}@{upstream}..refs/heads/${branch}" 2>/dev/null | tr -d '\r')" + unpushed_line="${ahead_up:-0} ahead of ${upstream}" + fi + printf 'Branch: %s\n' "$branch" printf 'Tier: %s\n' "$tier" printf 'Age days: %s\n' "$age_days" printf 'PR: %s\n' "$pr_line" + printf 'Unpushed: %s\n' "$unpushed_line" printf 'Reason: %s\n' "$reason" } @@ -135,5 +172,5 @@ while IFS= read -r line; do classify_branch "$branch" "$age_days" done < <(git -C "$REPO_ROOT" for-each-ref refs/heads/ --format='%(refname:short) %(committerdate:unix)' 2>/dev/null | tr -d '\r') -printf 'Summary: protected=%s safe=%s likely-safe=%s review=%s\n' "$prot" "$safe" "$likely" "$review" +printf 'Summary: protected=%s worktree=%s safe=%s likely-safe=%s review=%s\n' "$prot" "$wt" "$safe" "$likely" "$review" exit 0 diff --git a/plugins/repo-hygiene/skills/clean/scripts/git-branch-audit.test.sh b/plugins/repo-hygiene/skills/clean/scripts/git-branch-audit.test.sh index 15933dc5172..2296a796a98 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/git-branch-audit.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/git-branch-audit.test.sh @@ -52,6 +52,68 @@ FAKEGH assert_contains "closed pr reason" "$closed_out" "PR closed without merge" fi +# A no-op gh stub keeps the worktree / no-upstream cases below deterministic and +# offline (the real gh would hit the network for its PR map). +STUB_BIN="$TEST_TMPDIR/stub-bin" +mkdir -p "$STUB_BIN" +printf '#!/usr/bin/env bash\nexit 1\n' >"$STUB_BIN/gh" +chmod +x "$STUB_BIN/gh" + +# Worktree exclusion: a branch checked out in a linked worktree is its own +# WORKTREE bucket — never a deletion candidate lumped under PROTECTED, and never +# offered for `git branch -d` (which would break the worktree). +WT_REPO="$TEST_TMPDIR/wt-repo" +git init -q "$WT_REPO" +git -C "$WT_REPO" config user.email "t@example.com" +git -C "$WT_REPO" config user.name "Test" +echo x >"$WT_REPO/x" +git -C "$WT_REPO" add x +git -C "$WT_REPO" commit -qm init +git -C "$WT_REPO" branch feat/parked +git -C "$WT_REPO" worktree add -q "$TEST_TMPDIR/wt-linked" feat/parked +wt_out="$(PATH="$STUB_BIN:$PATH" bash -c "cd '$WT_REPO' && bash '$AUDIT'")" +assert_contains "worktree branch own tier" "$wt_out" "Tier: WORKTREE" +assert_contains "worktree branch reason" "$wt_out" "clean up the worktree first" +assert_contains "summary counts worktree bucket" "$wt_out" "worktree=1" + +# No-upstream classification: a never-pushed branch with commits not on +# origin/ is surfaced as its own class and Unpushed line, not left +# invisible behind @{upstream}-only ahead reporting. +NU_REPO="$TEST_TMPDIR/nu-repo" +git init -q --bare "$TEST_TMPDIR/nu-origin.git" +git init -q "$NU_REPO" +git -C "$NU_REPO" config user.email "t@example.com" +git -C "$NU_REPO" config user.name "Test" +echo a >"$NU_REPO/a" +git -C "$NU_REPO" add a +git -C "$NU_REPO" commit -qm init +git -C "$NU_REPO" remote add origin "$TEST_TMPDIR/nu-origin.git" +git -C "$NU_REPO" push -q origin HEAD:main +git -C "$NU_REPO" symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main +git -C "$NU_REPO" checkout -q -b feat/never-pushed +echo b >"$NU_REPO/b" +git -C "$NU_REPO" add b +git -C "$NU_REPO" commit -qm b +git -C "$NU_REPO" checkout -q main +nu_out="$(PATH="$STUB_BIN:$PATH" bash -c "cd '$NU_REPO' && bash '$AUDIT'")" +assert_contains "no-upstream unpushed line" "$nu_out" "no upstream, 1 commits not on origin/main" +assert_contains "no-upstream own review class" "$nu_out" "Reason: no upstream, 1 commits not on origin/main" + +# A configured upstream whose tracking ref is unfetched still counts as no-upstream: +# `rev-parse --abbrev-ref` echoes the literal input on failure, which must not be +# mistaken for a real upstream (it would print `@{upstream}` as the ahead +# base). Configure tracking, then delete the remote-tracking ref to simulate it. +git -C "$NU_REPO" checkout -q -b feat/tracked-unfetched +echo c >"$NU_REPO/c" +git -C "$NU_REPO" add c +git -C "$NU_REPO" commit -qm c +git -C "$NU_REPO" config branch.feat/tracked-unfetched.remote origin +git -C "$NU_REPO" config branch.feat/tracked-unfetched.merge refs/heads/feat/tracked-unfetched +git -C "$NU_REPO" checkout -q main +uf_out="$(PATH="$STUB_BIN:$PATH" bash -c "cd '$NU_REPO' && bash '$AUDIT'")" +assert_not_contains "unfetched upstream not echoed literally" "$uf_out" "@{upstream}" +assert_contains "unfetched upstream falls to no-upstream count" "$uf_out" "no upstream, 1 commits not on origin/main" + if [[ $FAILED -ne 0 ]]; then echo "FAILED: $FAILED test(s)" exit 1 diff --git a/plugins/repo-hygiene/skills/clean/scripts/git-stash-audit.sh b/plugins/repo-hygiene/skills/clean/scripts/git-stash-audit.sh new file mode 100644 index 00000000000..dd4606c863e --- /dev/null +++ b/plugins/repo-hygiene/skills/clean/scripts/git-stash-audit.sh @@ -0,0 +1,117 @@ +#!/usr/bin/env bash +# shellcheck disable=SC2154 +# Stash audit facts for the clean git tier. No stash is ever dropped. +# +# Output contract (stable labels): +# StashStore: (dedup key across worktrees) +# per stash — Stash, Age days, Source branch, Diffstat, PR, Advisory +# Stash count: +# Summary: stashes= likely-superseded= (never auto-dropped) +# Exit: 0. +# Omit -e/-o pipefail: always exits 0; sub-commands are best-effort (gh may be absent). +set -u + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +# shellcheck source=lib/clean-common.sh source=lib/cleanup-paths.sh +source "$SCRIPT_DIR/lib/clean-common.sh" + +usage() { + cat <<'EOF' +git-stash-audit.sh — emit stash audit facts for the clean git tier. + +Usage: + git-stash-audit.sh + git-stash-audit.sh --help + +Never drops a stash (read-only). Exit: 0. +EOF +} + +case "${1:-}" in +-h | --help) + usage + exit 0 + ;; +*) ;; +esac + +REPO_ROOT="$(clean_repo_root)" +if [[ -z "$REPO_ROOT" ]]; then + echo "Error: not a git repository" + exit 0 +fi + +# Linked worktrees share one stash ref (stored against the common git dir), so a +# fleet sweep visiting several worktrees of the same repo must dedup on this key +# rather than counting each worktree's identical stash list. +COMMON_DIR="$(git -C "$REPO_ROOT" rev-parse --path-format=absolute --git-common-dir 2>/dev/null | tr -d '\r')" +[[ -z "$COMMON_DIR" ]] && COMMON_DIR="$(git -C "$REPO_ROOT" rev-parse --git-common-dir 2>/dev/null | tr -d '\r')" +printf 'StashStore: %s\n' "${COMMON_DIR:-unknown}" + +DEFAULT_BRANCH="$(git -C "$REPO_ROOT" symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|^refs/remotes/origin/||' | tr -d '\r')" +if [[ -z "$DEFAULT_BRANCH" ]] && command -v gh >/dev/null 2>&1; then + DEFAULT_BRANCH="$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null | tr -d '\r')" +fi +DEFAULT_BRANCH="${DEFAULT_BRANCH:-main}" + +# PR map (best-effort): source-branch → state, so a stash whose source branch was +# merged can be flagged likely-superseded. Same batched gh call as the branch audit. +declare -A PR_STATE=() +declare -A PR_NUM=() +if command -v gh >/dev/null 2>&1; then + while IFS=$'\t' read -r head state num; do + [[ -z "$head" ]] && continue + PR_STATE["$head"]="$state" + PR_NUM["$head"]="$num" + done < <(gh pr list --state all --json headRefName,state,number --limit 200 2>/dev/null | + jq -r '.[] | [.headRefName, .state, .number] | @tsv' 2>/dev/null | tr -d '\r') +fi + +NOW=$(date +%s) +count=0 superseded=0 + +while IFS=$'\t' read -r sel ts subject; do + [[ -z "$sel" ]] && continue + count=$((count + 1)) + age_days=$(((NOW - ts) / 86400)) + # Source branch from the stash subject ("WIP on X: …" / "On X: …"). + src="$(printf '%s' "$subject" | sed -n 's/^\(WIP on\|On\) \([^:]*\):.*/\2/p')" + src="${src:-unknown}" + # Prefer the untracked-inclusive stat (a `stash -u` pre-rebase backup is often + # all untracked, invisible to the default stat); fall back to the tracked-only + # stat on git too old for --include-untracked, then to a plain marker. + diffstat="$(git -C "$REPO_ROOT" stash show --include-untracked --stat "$sel" 2>/dev/null | tail -1 | sed 's/^[[:space:]]*//')" + [[ -z "$diffstat" ]] && diffstat="$(git -C "$REPO_ROOT" stash show --stat "$sel" 2>/dev/null | tail -1 | sed 's/^[[:space:]]*//')" + [[ -z "$diffstat" ]] && diffstat="(no tracked changes)" + + pr_line="none" + advisory="review — confirm with the user before dropping (never auto-dropped)" + if [[ "$src" != "unknown" && -n "${PR_STATE[$src]:-}" ]]; then + pr_line="#${PR_NUM[$src]} ${PR_STATE[$src]}" + if [[ "${PR_STATE[$src]}" == "MERGED" ]]; then + advisory="likely superseded — source branch PR merged; still confirm before dropping" + superseded=$((superseded + 1)) + fi + elif [[ "$src" != "unknown" && "$src" != "$DEFAULT_BRANCH" ]] && + git -C "$REPO_ROOT" rev-parse --verify --quiet "refs/remotes/origin/${DEFAULT_BRANCH}" >/dev/null 2>&1 && + git -C "$REPO_ROOT" show-ref --verify --quiet "refs/heads/${src}" && + [[ -z "$(git -C "$REPO_ROOT" rev-list "origin/${DEFAULT_BRANCH}..refs/heads/${src}" 2>/dev/null | head -1)" ]]; then + # No PR record but the source branch is fully merged into origin/: + # its committed work is on the default branch, so the stash is more likely a + # superseded pre-merge backup. The stash's own diff may still be unique — hence + # advisory only, never auto-drop. + advisory="possibly superseded — source branch merged into origin/${DEFAULT_BRANCH}; confirm before dropping" + superseded=$((superseded + 1)) + fi + + printf 'Stash: %s\n' "$sel" + printf 'Age days: %s\n' "$age_days" + printf 'Source branch: %s\n' "$src" + printf 'Diffstat: %s\n' "$diffstat" + printf 'PR: %s\n' "$pr_line" + printf 'Advisory: %s\n' "$advisory" +done < <(git -C "$REPO_ROOT" stash list --format='%gd%x09%ct%x09%gs' 2>/dev/null | tr -d '\r') + +printf 'Stash count: %s\n' "$count" +printf 'Summary: stashes=%s likely-superseded=%s (never auto-dropped)\n' "$count" "$superseded" +exit 0 diff --git a/plugins/repo-hygiene/skills/clean/scripts/git-stash-audit.test.sh b/plugins/repo-hygiene/skills/clean/scripts/git-stash-audit.test.sh new file mode 100644 index 00000000000..ba8b4a2d6c9 --- /dev/null +++ b/plugins/repo-hygiene/skills/clean/scripts/git-stash-audit.test.sh @@ -0,0 +1,76 @@ +#!/usr/bin/env bash +# Tests for git-stash-audit.sh +set -uo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +# shellcheck source=lib/test-helpers.sh +source "$SCRIPT_DIR/lib/test-helpers.sh" + +AUDIT="$SCRIPT_DIR/git-stash-audit.sh" +TEST_TMPDIR="$(mktemp -d)" +trap 'rm -rf "$TEST_TMPDIR"' EXIT +FAILED=0 + +rc=0 +bash "$AUDIT" --help >/dev/null 2>&1 || rc=$? +assert_exit "--help exits 0" 0 "$rc" + +# A no-op gh stub keeps the audit deterministic and offline. +STUB_BIN="$TEST_TMPDIR/stub-bin" +mkdir -p "$STUB_BIN" +printf '#!/usr/bin/env bash\nexit 1\n' >"$STUB_BIN/gh" +chmod +x "$STUB_BIN/gh" + +# Empty repo: no stashes → count 0, never an error, exit 0. +git init -q "$TEST_TMPDIR/empty" +git -C "$TEST_TMPDIR/empty" config user.email "t@example.com" +git -C "$TEST_TMPDIR/empty" config user.name "Test" +echo x >"$TEST_TMPDIR/empty/x" +git -C "$TEST_TMPDIR/empty" add x +git -C "$TEST_TMPDIR/empty" commit -qm init +empty_out="$(PATH="$STUB_BIN:$PATH" bash -c "cd '$TEST_TMPDIR/empty' && bash '$AUDIT'")" +assert_contains "emits stash store key" "$empty_out" "StashStore:" +assert_contains "zero stash count" "$empty_out" "Stash count: 0" +assert_contains "summary line" "$empty_out" "Summary: stashes=0" + +# Populated repo: a stash on the default branch is live WIP (never superseded), +# a stash whose source branch merged into origin/ is flagged possibly +# superseded — but only ever as advisory, never dropped. +REPO="$TEST_TMPDIR/repo" +git init -q --bare "$TEST_TMPDIR/origin.git" +git init -q "$REPO" +git -C "$REPO" config user.email "t@example.com" +git -C "$REPO" config user.name "Test" +echo a >"$REPO/a" +git -C "$REPO" add a +git -C "$REPO" commit -qm init +git -C "$REPO" remote add origin "$TEST_TMPDIR/origin.git" +git -C "$REPO" push -q origin HEAD:main +git -C "$REPO" symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main +echo change >"$REPO/a" +git -C "$REPO" stash push -q -m "live wip on main" +git -C "$REPO" checkout -q -b feat/done +echo b >"$REPO/b" +git -C "$REPO" add b +git -C "$REPO" commit -qm b +git -C "$REPO" checkout -q main +git -C "$REPO" merge -q feat/done +git -C "$REPO" push -q origin main +git -C "$REPO" checkout -q feat/done +echo edit >>"$REPO/b" +git -C "$REPO" stash push -q -m "pre-merge backup" +git -C "$REPO" checkout -q main +out="$(PATH="$STUB_BIN:$PATH" bash -c "cd '$REPO' && bash '$AUDIT'")" +assert_contains "counts both stashes" "$out" "Stash count: 2" +assert_contains "emits diffstat" "$out" "Diffstat:" +assert_contains "attributes source branch" "$out" "Source branch: feat/done" +assert_contains "merged source flagged superseded" "$out" "possibly superseded" +# A stash on the default branch is live WIP, never flagged superseded. +assert_contains "main stash stays review" "$out" "review — confirm with the user" +assert_contains "never auto-dropped disclaimer" "$out" "never auto-dropped" + +if [[ $FAILED -ne 0 ]]; then + echo "FAILED: $FAILED test(s)" + exit 1 +fi +echo "OK: git-stash-audit.sh tests passed" diff --git a/plugins/repo-hygiene/skills/clean/scripts/lib/cleanup-paths.sh b/plugins/repo-hygiene/skills/clean/scripts/lib/cleanup-paths.sh index d6fd3abcbe5..7e149a6885a 100644 --- a/plugins/repo-hygiene/skills/clean/scripts/lib/cleanup-paths.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/lib/cleanup-paths.sh @@ -5,15 +5,13 @@ # Heavy trees that hold no cleanup targets we own — never descended by the # single-walk enumeration (`-prune`) and, symmetrically, never accepted from a -# manifest at `--apply`, so both sides share one prune set. SSOT: the scan tier -# still uses the per-glob CLEAN_FIND_EXCLUDE_* below (its migration to this walk -# is deferred). +# manifest at `--apply`, so both sides share one prune set. The caches/build/scan +# tiers all enumerate through this engine; only preflight's narrow recent-build +# probe still runs a standalone find (CLEAN_FIND_EXCLUDE_GIT below). CLEAN_PRUNE_DIRS=(.git node_modules .venv) -# Universal find exclusions (cleanup-config.md intro) +# Standalone-find exclusion for preflight's recent-build probe (cleanup-config.md intro). CLEAN_FIND_EXCLUDE_GIT='*/.git/*' -CLEAN_FIND_EXCLUDE_VENV='*/.venv/*' -CLEAN_FIND_EXCLUDE_NODE_MODULES='*/node_modules/*' # caches — explicit repo-root paths (trailing slash = directory; no slash on files). # Generic across ecosystems; regenerated on the next tool run. diff --git a/plugins/repo-hygiene/skills/clean/scripts/resolve-clean-action.sh b/plugins/repo-hygiene/skills/clean/scripts/resolve-clean-action.sh index 1220f0e7ffa..48d7145b6a3 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/resolve-clean-action.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/resolve-clean-action.sh @@ -1,7 +1,9 @@ #!/usr/bin/env bash # Map clean-skill user tokens to canonical action names (Tier-0 fact emission). # -# Output: Action: +# Output: Action: +# plus an optional `Note: ` when a leading action token is +# followed by advisory context (a question or a live-session constraint). # Exit: 0 always. set -u @@ -47,6 +49,9 @@ resolve_one() { git | branches | branch | prune | gc) printf 'git' ;; + stash | stashes | stash-audit) + printf 'stash' + ;; tree | fresh | fresh-pull | fresh-pull-state | pristine | reset-tree | working-tree) printf 'tree' ;; @@ -75,26 +80,52 @@ is_fleet_phrase() { } canonical="" -for token in "$@"; do - lower="$(printf '%s' "$token" | tr '[:upper:]' '[:lower:]')" - hit="$(resolve_one "$lower")" - # A bare "all" token is the single-repo `all` tier, but inside a fleet phrase it - # names the multi-repo tree-batch. Let the phrase win over the token so "reset - # all my repos" routes to tree-batch instead of the single-repo sweep. A genuine - # conflict with another explicit token (e.g. "scan all repos") still falls to the - # menu via the mismatch check below. - if [[ "$hit" == "all" ]] && is_fleet_phrase "$joined"; then - hit=tree-batch - fi - if [[ -n "$hit" ]]; then - if [[ -z "$canonical" ]]; then - canonical="$hit" - elif [[ "$canonical" != "$hit" ]]; then - printf 'Action: menu\n' - exit 0 +note="" + +# "Action token + advisory note" shape: a leading action token followed by free +# text (a question or a live-session constraint), where that trailing text is NOT +# itself a second action token and the whole input is not a fleet phrase. The note +# must not be re-interpreted as an action — so trailing text that merely mentions +# an action word (e.g. "…include stashes?") does not read as a conflict. A genuine +# second action token (e.g. "scan tree", "scan all repos") is left to the +# full-token resolution below, which reports the ambiguity as `menu`. +first_lower="$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')" +first_action="$(resolve_one "$first_lower")" +second_action="" +if [[ $# -ge 2 ]]; then + second_lower="$(printf '%s' "$2" | tr '[:upper:]' '[:lower:]')" + second_action="$(resolve_one "$second_lower")" +fi +if [[ -n "$first_action" && $# -ge 2 && -z "$second_action" ]] && ! is_fleet_phrase "$joined"; then + canonical="$first_action" + shift + note="$*" + note="${note#"${note%%[![:space:]]*}"}" + note="${note%"${note##*[![:space:]]}"}" +fi + +if [[ -z "$canonical" ]]; then + for token in "$@"; do + lower="$(printf '%s' "$token" | tr '[:upper:]' '[:lower:]')" + hit="$(resolve_one "$lower")" + # A bare "all" token is the single-repo `all` tier, but inside a fleet phrase it + # names the multi-repo tree-batch. Let the phrase win over the token so "reset + # all my repos" routes to tree-batch instead of the single-repo sweep. A genuine + # conflict with another explicit token (e.g. "scan all repos") still falls to the + # menu via the mismatch check below. + if [[ "$hit" == "all" ]] && is_fleet_phrase "$joined"; then + hit=tree-batch fi - fi -done + if [[ -n "$hit" ]]; then + if [[ -z "$canonical" ]]; then + canonical="$hit" + elif [[ "$canonical" != "$hit" ]]; then + printf 'Action: menu\n' + exit 0 + fi + fi + done +fi if [[ -z "$canonical" ]]; then if is_fleet_phrase "$joined"; then @@ -122,5 +153,6 @@ if [[ -z "$canonical" ]]; then printf 'Action: menu\n' else printf 'Action: %s\n' "$canonical" + [[ -n "$note" ]] && printf 'Note: %s\n' "$note" fi exit 0 diff --git a/plugins/repo-hygiene/skills/clean/scripts/resolve-clean-action.test.sh b/plugins/repo-hygiene/skills/clean/scripts/resolve-clean-action.test.sh index 5cdc805c366..d4ee8ff0e4b 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/resolve-clean-action.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/resolve-clean-action.test.sh @@ -17,6 +17,24 @@ assert_action() { assert_contains "$label" "$out" "Action: $want" } +# assert_note LABEL WANT ARG... — args passed verbatim (each a distinct token) so +# a multi-word note stays one logical note. +assert_note() { + local label="$1" want="$2" + shift 2 + local out + out="$(bash "$RESOLVE" "$@")" + assert_contains "$label" "$out" "Note: $want" +} + +assert_no_note() { + local label="$1" + shift + local out + out="$(bash "$RESOLVE" "$@")" + assert_not_contains "$label" "$out" "Note:" +} + assert_action "empty -> menu" "" "menu" assert_action "scan" "scan" "scan" assert_action "inventory alias" "inventory" "scan" @@ -24,6 +42,9 @@ assert_action "fresh alias" "fresh" "tree" assert_action "fresh-pull alias" "fresh-pull" "tree" assert_action "build alias" "artifacts" "build" assert_action "git alias" "branches" "git" +assert_action "stash token" "stash" "stash" +assert_action "stashes alias" "stashes" "stash" +assert_action "stash-audit alias" "stash-audit" "stash" assert_action "tree-batch token" "tree-batch" "tree-batch" assert_action "batch alias" "batch" "tree-batch" assert_action "fleet alias" "fleet" "tree-batch" @@ -40,6 +61,17 @@ assert_action "everything alias -> single-repo all" "everything" "all" # A genuine conflict (explicit non-all token + fleet phrase) still routes to menu. assert_action "scan + fleet phrase -> menu" "scan all repos" "menu" +# Multi-arg intent: a leading action token still resolves, and the trailing free +# text (a question, live-session constraints) surfaces as an advisory Note. +assert_action "action token before note still resolves" "all mind the live sessions" "all" +assert_note "trailing text becomes note" "mind the live sessions" all mind the live sessions +assert_note "question after action becomes note" "does this include stashes" scan does this include stashes +# A single quoted multi-line note stays one note verbatim. +assert_note "multiline note preserved" $'6-7 live sessions\nmind WIP' all $'6-7 live sessions\nmind WIP' +# No spurious note when the action stands alone or the whole input is one phrase. +assert_no_note "bare action emits no note" all +assert_no_note "fleet phrase emits no note" reset all my repos + if [[ $FAILED -ne 0 ]]; then echo "FAILED: $FAILED test(s)" exit 1 diff --git a/plugins/repo-hygiene/skills/clean/scripts/scan.sh b/plugins/repo-hygiene/skills/clean/scripts/scan.sh index f497dfded0e..88552e3e61f 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/scan.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/scan.sh @@ -48,17 +48,18 @@ format_size() { } emit_path_line() { - local category="$1" tier="$2" rel="$3" abs - abs="$REPO_ROOT/$rel" + local category="$1" tier="$2" abs="$3" rel kb [[ -e "$abs" ]] || return 0 if clean_path_is_protected "$REPO_ROOT" "$abs"; then return 0 fi + rel="${abs#"$REPO_ROOT"/}" printf 'Category: %s\n' "$category" printf 'Path: %s\n' "$rel" printf 'Size: %s\n' "$(format_size "$abs")" printf 'Tier: %s\n' "$tier" - TOTAL_BYTES=$((TOTAL_BYTES + $(du -sk "$abs" 2>/dev/null | awk '{print $1}') * 1024)) + kb="$(du -sk "$abs" 2>/dev/null | awk '{print $1}')" + TOTAL_BYTES=$((TOTAL_BYTES + ${kb:-0} * 1024)) } REPO_ROOT="$(clean_repo_root)" @@ -71,57 +72,18 @@ fi cd "$REPO_ROOT" || exit 0 -for rel in "${CLEAN_CACHE_EXPLICIT[@]}"; do - emit_path_line "Caches" "caches" "$rel" -done - -for rel in "${CLEAN_CACHE_EXPLICIT_FILES[@]}"; do - emit_path_line "Caches" "caches" "$rel" -done - -for name in "${CLEAN_CACHE_FIND_DIR_NAMES[@]}"; do - while IFS= read -r abs; do - [[ -z "$abs" ]] && continue - rel="${abs#"$REPO_ROOT"/}" - emit_path_line "Caches" "caches" "$rel" - done < <(find "$REPO_ROOT" -type d -name "$name" \ - ! -path "$CLEAN_FIND_EXCLUDE_GIT" \ - ! -path "$CLEAN_FIND_EXCLUDE_VENV" \ - ! -path "$CLEAN_FIND_EXCLUDE_NODE_MODULES" 2>/dev/null) -done - -for glob in "${CLEAN_CACHE_FIND_FILE_GLOBS[@]}"; do - while IFS= read -r abs; do - [[ -z "$abs" ]] && continue - rel="${abs#"$REPO_ROOT"/}" - emit_path_line "Caches" "caches" "$rel" - done < <(find "$REPO_ROOT" -type f -name "$glob" \ - ! -path "$CLEAN_FIND_EXCLUDE_GIT" \ - ! -path "$CLEAN_FIND_EXCLUDE_VENV" \ - ! -path "$CLEAN_FIND_EXCLUDE_NODE_MODULES" 2>/dev/null | head -50) -done - -for name in "${CLEAN_BUILD_DIR_NAMES[@]}"; do - while IFS= read -r abs; do - [[ -z "$abs" ]] && continue - rel="${abs#"$REPO_ROOT"/}" - emit_path_line "Build artifacts" "build" "$rel" - done < <(find "$REPO_ROOT" -type d -name "$name" \ - ! -path "$CLEAN_FIND_EXCLUDE_GIT" \ - ! -path "$CLEAN_FIND_EXCLUDE_VENV" \ - ! -path "$CLEAN_FIND_EXCLUDE_NODE_MODULES" 2>/dev/null | head -100) -done - -for glob in "${CLEAN_BUILD_FILE_GLOBS[@]}"; do - while IFS= read -r abs; do - [[ -z "$abs" ]] && continue - rel="${abs#"$REPO_ROOT"/}" - emit_path_line "Build artifacts" "build" "$rel" - done < <(find "$REPO_ROOT" -type f -name "$glob" \ - ! -path "$CLEAN_FIND_EXCLUDE_GIT" \ - ! -path "$CLEAN_FIND_EXCLUDE_VENV" \ - ! -path "$CLEAN_FIND_EXCLUDE_NODE_MODULES" 2>/dev/null | head -50) -done +# Enumeration shares the single pruned-walk engine with the mutating caches/build +# tiers (clean-common.sh) so the read-only inventory and the tiers that act on it +# report the same targets from one walk that never descends .git/node_modules/.venv. +while IFS= read -r abs; do + [[ -z "$abs" ]] && continue + emit_path_line "Caches" "caches" "$abs" +done < <(clean_caches_candidates "$REPO_ROOT") + +while IFS= read -r abs; do + [[ -z "$abs" ]] && continue + emit_path_line "Build artifacts" "build" "$abs" +done < <(clean_build_candidates "$REPO_ROOT") WT_COUNT="$(git worktree list 2>/dev/null | wc -l | tr -d ' ')" echo "Git worktrees: ${WT_COUNT:-0}" diff --git a/plugins/repo-hygiene/skills/clean/scripts/scan.test.sh b/plugins/repo-hygiene/skills/clean/scripts/scan.test.sh index b2be7c287bc..b058156f371 100755 --- a/plugins/repo-hygiene/skills/clean/scripts/scan.test.sh +++ b/plugins/repo-hygiene/skills/clean/scripts/scan.test.sh @@ -37,6 +37,17 @@ assert_contains "finds untracked cache" "$out" ".ruff_cache" assert_contains "emits category" "$out" "Category:" assert_contains "emits total" "$out" "Total reclaimable:" +# Single pruned-walk engine: a build dir NESTED inside a pruned tree +# (node_modules) is never descended into, while a top-level build dir still +# enumerates. This proves the walk prunes rather than merely filters output. +mkdir -p "$TEST_TMPDIR/repo/node_modules/pkg/bin" +echo z >"$TEST_TMPDIR/repo/node_modules/pkg/bin/z" +mkdir -p "$TEST_TMPDIR/repo/src/bin" +echo z >"$TEST_TMPDIR/repo/src/bin/z" +out="$(GIT_DIR="$TEST_TMPDIR/repo/.git" GIT_WORK_TREE="$TEST_TMPDIR/repo" bash -c "cd '$TEST_TMPDIR/repo' && bash '$SCAN'")" +assert_contains "top-level build dir inventoried" "$out" "src/bin" +assert_not_contains "build dir under pruned node_modules skipped" "$out" "node_modules/pkg/bin" + if [[ $FAILED -ne 0 ]]; then echo "FAILED: $FAILED test(s)" exit 1 From be73009cf174d5d2ef66c6beca298528a6ffe3e9 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 17:09:33 -0400 Subject: [PATCH 18/21] chore: restore source-control plugin to origin/main The merge inadvertently carried this branch's older base snapshot of the source-control plugin (0.18.0), reverting main's 0.19.0. Reset those files to origin/main so the PR diff is exactly the Batch-D repo-hygiene changes. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016D1oCPX8LaUKnLUi3TXmih --- .../source-control/.claude-plugin/plugin.json | 2 +- plugins/source-control/CHANGELOG.md | 33 +++++++++ .../skills/pull-request/evals/evals.json | 14 ++++ .../skills/pull-request/reference/create.md | 73 ++++++++++++++----- plugins/source-control/skills/setup/SKILL.md | 47 ++++++++++-- .../skills/setup/evals/evals.json | 39 ++++++++++ 6 files changed, 184 insertions(+), 24 deletions(-) diff --git a/plugins/source-control/.claude-plugin/plugin.json b/plugins/source-control/.claude-plugin/plugin.json index 944b52556b9..90690cf45f5 100644 --- a/plugins/source-control/.claude-plugin/plugin.json +++ b/plugins/source-control/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "source-control", - "version": "0.18.0", + "version": "0.19.0", "description": "Git and GitHub delivery workflow: /commit (Conventional Commits + Co-Authored-By trailer via safe heredoc mechanics), /pull-request (prep, create, CI monitoring, review-comment triage, merge, CI-log fetch), /babysit-prs (self-pacing fleet loop — safe by default; opt-in worker/autopilot tiers add gate-checked merge and thread resolution behind a deterministic Python engine), /worktree (create, status, cleanup, audit for parallel-session isolation), /setup (check the effective commit-subject / PR-title convention merged across its config layers and the babysit-prs config, or apply — interview the repo and write the convention config to a chosen layer), and /resolve-conflicts (intent-first merge/rebase conflict resolution with a semantic-conflict sweep — never --abort). The commit-subject / PR-title convention is configurable via a source-control.md config written by a re-runnable setup skill, layered across a ~/.claude user-global file, the tracked team file, and a gitignored .claude/source-control.local.md personal overlay merged per key; Conventional Commits is the default when no convention is declared.", "author": { "name": "Melodic Software", diff --git a/plugins/source-control/CHANGELOG.md b/plugins/source-control/CHANGELOG.md index cdb34b8fa19..3348633c30c 100644 --- a/plugins/source-control/CHANGELOG.md +++ b/plugins/source-control/CHANGELOG.md @@ -3,6 +3,39 @@ All notable changes to the `source-control` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.19.0] + +### Added + +- **`/source-control:setup` now covers `pr_body_required_sections` (#1032, completing #975's + adoption path).** `check` reports the key's effective value across all three layers — a + `pr_body_required_sections` row on the effective-configuration table, resolving to the plugin's + portable default (`Summary`, `Test plan`) with `won by: plugin default` when no layer sets it, + rather than a blank row. `apply`'s interview offers setting it and the written-config template + gains the matching `## pr_body_required_sections` section, at parity with every other per-key + surface (`subject_pattern`, `pr_title_pattern`, `trailer_policy`, `pr_body_attribution`). The + interview deliberately recommends only the plugin's own portable default and never proposes a + `Related`/linked-issue section or any other organization-specific list — asking what the repo's + actual convention requires, never inventing one, per the plugin's Two-lane convention posture. The + interview also states, per-key-fallthrough-aware, when resetting to the portable default over a + lower layer that already sets the key requires writing the explicit default list rather than + omitting the section — an omission only inherits, it never overrides (review-caught during #1032). + +### Fixed + +- **`## Related` pre-create gate no longer drops visible text sharing a line with an inline HTML + comment (#975/#1029 follow-up, review-caught during #1032).** The comment-aware heading scan + previously treated an entire line as comment text once it saw `` before the section's non-empty check — a false-fail, + since GitHub still renders the visible text outside the comment. The scan now strips only the + comment SPAN (single- or multi-line), preserving visible text before, between, and after spans on + the same line; a genuinely comment-only line, or a fully-hidden middle line of a multi-line span, + still contributes nothing. Defensive pass over the fence/comment interaction: a fence's content is + never comment-parsed (comment-marker-shaped text inside a fence stays literal) and a comment's + content is never fence-parsed (fence-marker-shaped text inside a comment stays literal), and a + heading line carrying a trailing inline comment is still correctly read as a real exit boundary. + New eval 18 covers the regression. + ## [0.18.0] ### Added diff --git a/plugins/source-control/skills/pull-request/evals/evals.json b/plugins/source-control/skills/pull-request/evals/evals.json index 4e20d20863f..033b1d3c527 100644 --- a/plugins/source-control/skills/pull-request/evals/evals.json +++ b/plugins/source-control/skills/pull-request/evals/evals.json @@ -213,6 +213,20 @@ "Comment text is never counted as non-empty content, even inside a genuinely matched section — unlike a fenced code block, which is rendered and does count", "The behavior matches what GitHub itself renders (nothing) and what a comment-stripping PR-body validator would see (nothing)" ] + }, + { + "id": 18, + "name": "pr-body-required-sections-gate-preserves-visible-text-around-inline-comments", + "prompt": "/pull-request create. pr_body_required_sections requires Test plan. The drafted `## Test plan` section's only content line is `Ran smoke tests ` — real visible text sharing a line with a trailing HTML comment.", + "expected_output": "The §2.4.2.2 gate passes for `## Test plan` — 'Ran smoke tests ' is real content GitHub renders, so the section is not empty. The scan strips only the comment SPAN (``), not the whole line, so visible text before, between, or after a comment span on the same line (including a multi-line span whose opening or closing line also carries visible text) is preserved and counted; only a genuinely comment-only line (eval 17) or a fully-hidden middle line of a multi-line span contributes nothing. A fence still takes priority over a comment inside it (fence content is literal, never comment-parsed) and vice versa (comment content is literal, never fence-parsed), and a heading line carrying a trailing inline comment is still correctly read as a real exit boundary rather than misrouted into comment handling.", + "files": [], + "expectations": [ + "Visible text sharing a line with an inline HTML comment is preserved and counted as real content — the gate does not block on a section whose only issue is a trailing/leading inline comment", + "Only the comment span itself is removed, not the whole line — text before the span, after the span, or between two spans on the same line is all kept", + "A multi-line comment span's opening line keeps its pre-comment visible text and its closing line keeps its post-comment visible text; only a fully-hidden middle line contributes nothing", + "A fenced code block's content is preserved even if it contains comment-marker-shaped text (`, single- or multi-line) — # a Summary that documents a template containing a literal "## Related" inside a # code sample, or a body carrying a commented-out draft section, must never - # satisfy the Related requirement GitHub itself renders as absent. A single - # action block (not separate pattern-action rules) keeps exactly one branch - # firing per line — awk otherwise runs every matching rule for a line, which - # would double-toggle state on a line matching more than one pattern. + # satisfy the Related requirement GitHub itself renders as absent. # # Fences and comments are NOT symmetric once inside the found section: a fence - # delimiter encountered there is real, RENDERED content and stays in the - # captured body (a section whose own genuine content includes a code block is - # still captured correctly) — but a comment is never rendered at all, in or out - # of a found section, so comment text is never printed into SECTION_BODY. A - # required section whose entire body is an unfilled `` template - # placeholder must read as empty, the same as GitHub's own render and this - # repo's PR-body validator (which strips comments before checking) would. + # delimiter there is real, RENDERED content and stays in the captured body (a + # section whose own genuine content includes a code block is still captured + # correctly) — but a comment is never rendered at all, so comment text is + # never counted as content, even inside a found section. An *inline* comment + # is stripped as a SPAN, not a whole line, though: "Ran smoke tests " keeps "Ran smoke tests " (GitHub still renders the text + # outside the comment) rather than dropping the entire line the way a + # comment-only line correctly does. A fence or comment already open when a + # line starts consumes that line's meaning entirely before any NEW fence or + # comment on the same line is considered — GFM parses both literally with no + # nested markup, so a "" span from `line`, keeping visible text + # before/after/between spans on the same line; updates the global + # in_comment state when a span does not close on this line (a multi-line + # comment). A comment-only line returns "". + out = "" + while (1) { + if (in_comment) { + idx = index(line, "-->") + if (idx == 0) { return out } + line = substr(line, idx + 3) + in_comment = 0 + } else { + idx = index(line, "/) in_comment = 0 - next - } if (in_comment) { - if ($0 ~ /-->/) in_comment = 0 + visible = strip_comment_span($0) + if (found && visible != "") print visible next } + + # Heading and exit-boundary checks run on the RAW line, never a + # comment-stripped one: a real ATX heading (or the next one, ending this + # section) must start the line itself, so a "##"-shaped fragment freed by + # stripping a same-line comment could never be a real heading GitHub would + # render as one. Checking the raw line here also means a heading carrying + # a trailing inline comment ("## Related ") is still + # correctly read as a real exit boundary, not misrouted into the + # comment-open branch below. if (!found && $0 == h) { found = 1; next } if (found && $0 ~ /^## /) { exit } + + if (fence_char != "") { in_fence = 1; open_char = fence_char; if (found) print; next } + if ($0 ~ /