Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
045c36c
feat(repo-hygiene): single pruned walk + dry-run manifest + apply sum…
kyle-sexton Jul 22, 2026
8c845e5
test(repo-hygiene): pin manifest line format and --include-caches fol…
kyle-sexton Jul 22, 2026
d8e8c98
feat(repo-hygiene): drop the dotnet clean driver from clean-build
kyle-sexton Jul 22, 2026
9a534d2
style(repo-hygiene): drop issue-refs and TODO marker from code comments
kyle-sexton Jul 22, 2026
9311037
fix(repo-hygiene): harden manifest consumption and de-quadratic the d…
kyle-sexton Jul 22, 2026
76d3617
fix(repo-hygiene): validate manifest entries against tier and target …
kyle-sexton Jul 22, 2026
137efb6
fix(repo-hygiene): type-check manifest targets and guard manifest ove…
kyle-sexton Jul 22, 2026
1967662
fix(repo-hygiene): reject a valueless --manifest instead of looping f…
kyle-sexton Jul 22, 2026
05f716a
fix(repo-hygiene): reject manifest entries inside pruned trees
kyle-sexton Jul 22, 2026
694eb56
fix(repo-hygiene): fail closed on truncated and newline-less manifest…
kyle-sexton Jul 22, 2026
8f0a905
fix(repo-hygiene): fail on uncreatable manifest and reject symlinked …
kyle-sexton Jul 22, 2026
770ca04
fix(repo-hygiene): apply-loop fd isolation, honest bytes, dry-run/app…
kyle-sexton Jul 22, 2026
4d8b060
style(repo-hygiene): drop issue-ref from manifest-encoding comment
kyle-sexton Jul 22, 2026
9b14290
style(repo-hygiene): fix spell-check hits in comments
kyle-sexton Jul 22, 2026
c84086d
fix(repo-hygiene): reject manifest paths through a symlinked ancestor
kyle-sexton Jul 22, 2026
bd20952
fix(repo-hygiene): unify symlinked-path rejection message
kyle-sexton Jul 22, 2026
a331f34
feat(repo-hygiene): stash audit, worktree/no-upstream branch classes,…
kyle-sexton Jul 22, 2026
d8942b4
Merge origin/main into feat/repo-hygiene-stash-preflight-resolver
kyle-sexton Jul 22, 2026
be73009
chore: restore source-control plugin to origin/main
kyle-sexton Jul 22, 2026
564f36c
Merge remote-tracking branch 'origin/main' into feat/repo-hygiene-sta…
kyle-sexton Jul 22, 2026
03c63e1
test(repo-hygiene): pin audit test repos to main branch
kyle-sexton Jul 22, 2026
4b7c976
fix(repo-hygiene): review-driven hardening for stash/branch audits + CI
kyle-sexton Jul 22, 2026
08be94a
Merge origin/main (Batch C #1064) into feat/repo-hygiene-stash-prefli…
kyle-sexton Jul 22, 2026
97b8b44
fix(repo-hygiene): fail-closed gone branches + fleet-indicator note r…
kyle-sexton Jul 22, 2026
d4d8cf0
Merge remote-tracking branch 'origin/main' into feat/repo-hygiene-sta…
kyle-sexton Jul 22, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion plugins/repo-hygiene/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "repo-hygiene",
"version": "0.6.0",
"version": "0.7.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",
Expand Down
49 changes: 49 additions & 0 deletions plugins/repo-hygiene/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,55 @@
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.7.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/<default>` 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). Each stash also carries its
stable commit id (`Commit:`) — the safe handle when dropping several, since the
`stash@{n}` selector renumbers after every drop — and a confirmed `git stash
drop`/`clear` is now covered by the session destructive guard (blocked until the
`CLEAN_GUARD_ACK=1` acknowledgement). 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 <upstream>` or, for a
never-pushed branch, `no upstream, M commits not on origin/<default>` — 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. A
branch whose upstream is `gone` but that still carries commits not on
origin/<default> is held in REVIEW too, rather than offered as a LIKELY-SAFE
deletion candidate that would lose those commits. (#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.6.0]

### Added
Expand Down
19 changes: 14 additions & 5 deletions plugins/repo-hygiene/skills/clean/SKILL.md
Original file line number Diff line number Diff line change
@@ -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, and fleet batch forms of the selective tiers (caches-batch / build-batch / git-batch / all-batch over many repos behind one gate). 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, clean caches across all repos, clear build artifacts across all my repos, prune git across the fleet, 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, and fleet batch forms of the selective tiers (caches-batch / build-batch / git-batch / all-batch over many repos behind one gate). 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, clean caches across all repos, clear build artifacts across all my repos, prune git across the fleet, 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|caches-batch|build-batch|git-batch|all-batch|aliases…] (bare → menu or auto-detect)"
argument-hint: "[scan|caches|build|git|stash|tree|tree-batch|all|caches-batch|build-batch|git-batch|all-batch|aliases…] (bare → menu or auto-detect)"
allowed-tools:
- Bash(bash ${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/*)
hooks:
Expand Down Expand Up @@ -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: <text>` 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).
Expand All @@ -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 | — |
Expand All @@ -72,7 +75,7 @@ Protected-path enforcement gates `scan`, `caches`, `build`, `git`, AND `tree` (`

`tree` requires explicit confirmation and is never auto-invoked. Any file tracked by git is reset via `git reset --hard`, not selective deletion — and any tracked file deleted by reparse-point traversal (junction/symlink into a tracked dir) is auto-restored.

**Session-scoped destructive guard (frontmatter hook).** While this skill is active, a PreToolUse hook (`scripts/destructive-guard.sh`) blocks destructive Bash commands (`rm -rf`, `git clean -f*`, `git reset --hard`, `git checkout --`, recursive `Remove-Item`). After the dry-run → user-confirmation gate passes, re-issue the confirmed command with the acknowledgement prefix `CLEAN_GUARD_ACK=1 <command>` — never add the prefix without the user's explicit confirmation in this session. Kill switch: the `clean_destructive_guard_enabled` userConfig option set to `false` (`/plugin configure repo-hygiene`).
**Session-scoped destructive guard (frontmatter hook).** While this skill is active, a PreToolUse hook (`scripts/destructive-guard.sh`) blocks destructive Bash commands (`rm -rf`, `git clean -f*`, `git reset --hard`, `git checkout --`, `git stash drop`/`clear`, recursive `Remove-Item`). After the dry-run → user-confirmation gate passes, re-issue the confirmed command with the acknowledgement prefix `CLEAN_GUARD_ACK=1 <command>` — never add the prefix without the user's explicit confirmation in this session. Kill switch: the `clean_destructive_guard_enabled` userConfig option set to `false` (`/plugin configure repo-hygiene`).

## Cleanup configuration

Expand Down Expand Up @@ -120,7 +123,13 @@ 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/<default>` 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.
Comment thread
kyle-sexton marked this conversation as resolved.
Resolved

**Dropping stashes safely.** A confirmed drop is destructive and gated by the session guard — after the user confirms, re-issue as `CLEAN_GUARD_ACK=1 git stash drop <ref>`. The `Stash:` selector (`stash@{n}`) is **volatile**: the list renumbers after every drop, so dropping more than one by selector top-down retargets the wrong entry. Drop by the stable `Commit:` id (resolve it to its current selector immediately before each drop), or drop the highest-numbered selector first so lower indices stay valid.

### 5. All

Expand Down
9 changes: 6 additions & 3 deletions plugins/repo-hygiene/skills/clean/context/action-router.md
Original file line number Diff line number Diff line change
Expand Up @@ -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** |
Expand All @@ -23,14 +24,15 @@ SKILL.md carries the action table headline; this file carries alias resolution,
bash ${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/resolve-clean-action.sh <tokens...>
```

Emits `Action: <canonical|menu>`. Single-token aliases:
Emits `Action: <canonical|menu>`, plus an optional `Note: <text>` 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 |
| --- | --- |
| `scan`, `inventory`, `space`, `audit`, `report`, `show` | `scan` |
| `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` |
Expand Down Expand Up @@ -59,7 +61,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 <path>`), 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) |
| `caches-batch` / `build-batch` / `git-batch` / `all-batch` | `clean-batch.sh --tier <…> --dry-run` (writes a batch plan; emits `BatchPlan:` + aggregate `Summary: repos=N planned=P bytes=K`) | **Mandatory** single batch-wide `AskUserQuestion` before `--apply` (surface per-repo `Outcome`/`Reason`, `Summary` reclaimable `bytes`, `UnmatchedSkip:`); apply the **same** plan (`CLEAN_GUARD_ACK=1 … --apply --batch-plan <path>`, which errors without the plan) — one gate for the whole batch, never per repo; never autonomous. Detail: [clean-batch.md](clean-batch.md) |
Expand Down
Loading