repository-hygiene-sweep

What this skill does

# repository-hygiene-sweep — clean a repository without destroying useful work

Maintain a git repository: prune merged branches, compact storage, hunt large/dangling objects, and (only with explicit consent) rewrite history to remove accidental large files or secrets. The discipline is conservation — every step is reversible-first, and anything ambiguous is skipped, not guessed.

## ⚠️ Critical Constraints

- **Never run a destructive command without explicit, scoped confirmation.** Branch deletion, history rewrite, `reflog expire`, and `gc --prune=now` are the destructive set. Name exactly what will be destroyed and wait for a yes. **Why:** these are the operations that lose real work, and the user often does not realize what a branch or reflog entry was protecting.
- **Skip when in doubt — never guess.** If you cannot prove a branch is fully merged, a file is truly junk, or a repo is not shared, do nothing and report the ambiguity. **Why:** the cost of a wrong delete (lost work) vastly exceeds the cost of leaving a stale branch around.
- **Read-only first; mutate only after.** Run the diagnosis pass (counts, sizes, candidate lists) and present it before changing anything. **Why:** the user must see what they are approving.
  - WRONG: `git branch --merged | grep -v '\*' | xargs git branch -d`  (auto-deletes on a single guess)
  - CORRECT: list `git branch --merged main`, show it, get confirmation, then delete named branches one set at a time.
- **Never delete a branch that is not merged with `-D`.** Use `-d` (refuses to delete unmerged). **Why:** `-D` force-deletes branches that contain unique commits — the classic way to silently lose work.
  - WRONG: `git branch -D feature/x`
  - CORRECT: `git branch -d feature/x` and, if it refuses, investigate why instead of forcing.
- **Never rewrite published/shared history casually.** History rewrite (filter-repo, BFG) is acceptable only on a repo the owner confirms is unshared or whose collaborators have agreed to re-clone. **Why:** rewriting shared history breaks every other clone and can resurrect "deleted" data on the next push.
- **Always confirm a clean, backed-up state before any history rewrite.** Require a committed/clean working tree and a fresh mirror clone (`git clone --mirror`) as the backup. **Why:** history rewrite is the one operation with no in-repo undo once reflogs are expired.
- **A leaked secret is not "removed" by rewriting history alone.** Always advise rotating/revoking the secret too. **Why:** the secret may already be cloned, cached, or on a fork — rotation is the only real remediation.

## Why This Exists

Repositories accumulate cruft: dozens of merged feature branches, a `.git` directory bloated by an accidentally-committed binary, loose objects, and `.gitignore` files that let junk slip in. Cleaning them is routine but genuinely dangerous — the same commands that reclaim space (`gc --prune`, `branch -D`, history rewrite) are the ones that permanently destroy work. Agents are biased toward "looks done" and toward force-flags that make errors disappear; that bias is exactly wrong here. This skill exists to make the safe path the default path: diagnose, propose, confirm, act reversibly, and skip anything uncertain.

## Quick Start

```bash
# 1. Confirm where you are and that nothing is uncommitted (diagnosis is safe, read-only).
git rev-parse --is-inside-work-tree && git status --short

# 2. Run the full read-only diagnosis bundle.
bash {baseDir}/scripts/diagnose.sh        # branches, sizes, large blobs, dangling objects

# 3. Review the report, confirm specific actions, then mutate one category at a time.
```

`{baseDir}/scripts/diagnose.sh` is **Execute** — run it to gather the report. It changes nothing.

## Workflow

### Phase 1 — Diagnose (read-only, always first)
Establish ground truth before touching anything.

```bash
git status --short                                  # uncommitted work? (if yes, STOP — back up first)
git fetch --all --prune --dry-run                   # what would prune; preview only
git branch -vv --merged                             # branches fully merged into HEAD
git branch -vv --no-merged                          # branches with unique commits (DO NOT auto-delete)
git for-each-ref --sort=committerdate refs/heads --format='%(committerdate:short) %(refname:short)'
du -sh .git                                          # current repo storage footprint
git count-objects -vH                               # loose vs packed, size, dangling count
```

**Checkpoint:** if the working tree is dirty, or this is a shared repo and the user has not confirmed it, stop and report. Do not proceed to any mutation.

### Phase 2 — Prune branches (reversible)
Branch deletion is recoverable via reflog for a while, but treat it as consequential.

```bash
# Identify the integration branch explicitly (main/master/develop) — do not assume.
git branch --merged main | grep -vE '^\*| main$| master$| develop$'   # safe-to-delete candidates
```

- Present the candidate list. Delete only confirmed names, using `-d` (never `-D`).
- For remote-tracking cleanup of branches already deleted upstream: `git fetch --prune` (safe; only removes stale remote refs, not your local branches).
- Record each deleted branch's tip SHA in the report so it can be restored: `git branch <name> <sha>`.

**Checkpoint:** verify each deletion succeeded with `-d` (no force). If git refused, the branch had unique commits — leave it and flag it.

### Phase 3 — Compact storage (reversible vs destructive split)
```bash
git gc                          # safe: repacks, keeps reflog-reachable + recent loose objects
git repack -Ad                  # safe: consolidate packs
# DESTRUCTIVE — only after explicit confirmation:
# git reflog expire --expire=now --all && git gc --prune=now   # drops unreachable objects permanently
```

Run the safe `gc` by default. Only offer the prune-now path when the user explicitly wants to reclaim space from already-removed history AND understands it makes recovery impossible.

### Phase 4 — Find large / dangling objects (read-only)
See [references/large-objects.md](references/large-objects.md) for the blob-size ranking and dangling-object triage recipes.

**Checkpoint:** finding a large blob does not mean removing it. Confirm it is genuinely unwanted (not a needed asset) before considering Phase 5.

### Phase 5 — Remove large files / secrets from history (DESTRUCTIVE — gated)
This rewrites history. Do not enter this phase without: clean tree, confirmed unshared-or-agreed repo, and a `git clone --mirror` backup. Procedure, tool choice (git-filter-repo vs BFG), and the force-push/re-clone protocol are in [references/history-rewrite.md](references/history-rewrite.md).

### Phase 6 — .gitignore hygiene (low-risk)
```bash
git status --ignored --short                        # what is currently ignored
git ls-files --others --exclude-standard            # untracked, not ignored — should any be ignored?
git check-ignore -v <path>                           # explain why a path is/ignored
```

- Propose additions for build artifacts, dependency dirs, env/secret files, OS cruft. Do not blanket-ignore source.
- If a file is ALREADY tracked, adding it to `.gitignore` does nothing — note that it needs `git rm --cached` (a tracked-content change, confirm separately).

## Output Specification

Produce a report named `repo-cleanup-report.md` (or inline if small) with:
1. **Findings** — repo size, branch counts (merged/unmerged/stale), large blobs (size + path), dangling object count, .gitignore gaps.
2. **Actions taken** — each mutation, the exact command, and the result.
3. **Skipped (and why)** — every ambiguous item deliberately left alone.
4. **Recovery** — reversible commands (deleted branch SHAs, mirror-backup location).

## Quality Rubric

- No destructive command (`branch -D`, `gc --prune=now`, history rewrite, `reflog expire`) ran without a logged, explicit confirmation for that specific tar