Repo Hygiene

---
name: repo-hygiene
description: Periodic repository cleanup sweep (Tierward repo variant) - finds orphaned/merged git branches, orphaned worktrees and unregistered worktree directories, stale `.claude/session/*.md` files, stale `.claude/initiatives/*.md` files, and (target:full / target:reviews) orphaned documentation and stale `docs/reviews/` snapshots (archive-only moves, never deletion). Reports every finding with evidence, then executes only the branches/worktrees/session-files the user explicitly confirms via a single AskUserQuestion batch. Never deletes docs/*.md itself - those are always report-only, evidence-based, human-decided. Distinct from the Phase 8 cleanup gate (which tears down one specific block at closure) - this is the periodic sweep that catches what block-by-block cleanup misses.
user-invocable: true
model: sonnet
argument-hint: "[target:full]"
allowed-tools: >
  Bash(bash .claude/skills/repo-hygiene/references/scan-branches-worktrees.sh), Bash(git branch:*),
  Bash(git worktree:*), Bash(git status:*), Bash(git log:*), Bash(git fetch:*),
  Bash(git rev-parse:*), Bash(git show:*), Bash(gh pr list:*), Bash(gh pr view:*),
  Bash(ls:*), Bash(wc:*), Bash(date:*), Bash(stat:*), Bash(find:*), Bash(rm .claude/session/*.md),
  Bash(rm .claude/initiatives/*.md), Bash(mkdir -p docs/reviews/archive), Bash(mv .claude/initiatives/*),
  Bash(mv docs/reviews/*),
  Bash(rm -rf .claude/worktrees/*),
  Read, Grep, Glob
---

**Tierward repo variant** - diverges deliberately from the scaffolded payload copy (`packages/cli/templates/tier-{m,l}/...`): adds the unregistered-worktree-dir scan, Step 2b (initiatives staleness), and the `docs/reviews/` staleness pass. Do not sync this file back over the payload copies.

Runs in the **main conversation, deliberately without `context: fork`**. `AskUserQuestion` is unavailable to subagents/forked skill contexts, and this skill's confirm-then-execute design requires it mid-run. Do not add `context: fork` to this file.

Goal: search thoroughly, report every candidate with concrete evidence, execute only what the user explicitly confirms. Never guess-execute. Never touch `docs/*.md` regardless of confirmation.

## Step 0 - Parse scope

`$ARGUMENTS`: default = quick scan (Steps 1, 2, 2b). `target:full` adds Step 3 (doc orphans + reviews staleness) - the slow, judgment-heavy pass. `target:reviews` runs ONLY the Step 3 reviews-staleness pass (skips the tracked-doc orphan sweep). State which mode is active before starting.

**Always exclude `.claude/worktrees/**` from every Grep/Glob in Steps 2 and 3.** Worktrees are full repo checkouts - without this exclusion every file inside every active worktree gets reported as a duplicate "root-level" finding.

## Step 1 - Branch & worktree scan (mechanical, always runs)

Run the companion script:
```bash
bash .claude/skills/repo-hygiene/references/scan-branches-worktrees.sh
```

It is read-only and prints three sections:
- `SAFE_BRANCH_DELETE` - bare branch names with no attached worktree, merged into every protected branch that exists on origin (see `PROTECTED_BRANCHES` at the top of the script), no open PR.
- `SAFE_WORKTREE_REMOVE` - `<branch>|<path>` pairs, merged into all protected branches, clean working tree, no open PR. Lines prefixed `KEEP|` are explicitly excluded with a reason (uncommitted changes / not yet merged / open PR / gh check failed) - do not re-litigate these, the script already checked.
- `PRUNABLE_WORKTREE` - paths registered in `git worktree list` whose actual directory no longer exists.
- `ORPHAN_WORKTREE_DIR` - directories on disk under `.claude/worktrees/` that are NOT registered in `git worktree list` (leftovers of a failed/manual removal + prune), with a content summary (`files:N|newest:date`). Git cannot report dirtiness for an unregistered dir, so these NEVER join the low-risk batch: each one gets its own separate confirmation in Step 5, after the content summary is shown, and is removed with `rm -rf` only on that explicit per-item confirm.

The classification is deliberately conservative (merged into ALL protected branches + clean + no open PR; a failed `gh` check reads as unknown, never as "no PR"). Trust it - do not loosen or tighten the criteria ad hoc.

**Safety nets when executing in Step 6**: always `git branch -d` (never `-D` - `-d` refuses on unmerged content, which is your backstop against a misclassification). Always `git worktree remove` without `--force` (refuses if dirty). If either refuses, STOP and report to the user - do not retry with the forced variant.

## Step 2 - Session-file staleness check (judgment, always runs)

For every `.claude/session/*.md` (block-*.md and fix-*.md):

1. Read the file. Note its mtime (`stat`), its front matter, and any `Status:` line.
2. Front matter `block_closed: true` or `fix_closed: true` means the block was closed and the file was kept on purpose at the cleanup gate - classify as **WEAK CANDIDATE** ("archived by choice - delete only if no longer needed").
3. `gh pr list --state merged --search "<slug derived from filename>" --limit 5` - does a merged PR confirm that block is closed?
4. Check `git branch -a` and `git worktree list` for a branch/worktree matching the file's block/branch name.
5. Classify - evidence-based, never by mtime alone in either direction (a fresh in-progress block and a long-blocked-but-still-relevant investigation must both resolve to KEEP absent closure evidence):
   - **STRONG CANDIDATE**: a merged PR confirms closure AND no matching branch/worktree exists anymore.
   - **WEAK CANDIDATE**: closed-and-kept front matter (point 2), OR no merged PR references it AND the file's own status reads as finished/abandoned AND it is several days old. Report with lower confidence, explicit evidence.
   - **KEEP**: recent activity, an in-progress/blocked-pending-external-action status, or a still-existing matching branch/worktree. When in doubt, KEEP.

## Step 2b - Initiatives staleness check (Tierward repo only, judgment, always runs)

For every `.claude/initiatives/*.md` (gitignored, local - deletable like session files, with one hard exception):

- **`roadmap-status.md` is KEEP, always, non-negotiable.** It is the single source of truth for roadmap state. Never list it as a candidate, regardless of any evidence.
- For each other file: read the header/status, note mtime and size, then cross-check closure evidence - does `roadmap-status.md` mark the corresponding item(s) Done/Closed/Deferred-with-criteria? Do merged PRs confirm the plan was executed? Does a superseding doc exist?
- Classify STRONG / WEAK / KEEP with the same evidence discipline as Step 2 (never mtime alone; deferred-with-criteria plans are KEEP - they are the criteria's home).
- For large closed memos (>50KB), offer **archive** (`mkdir -p docs/reviews/archive && mv` the file there) as the default proposal instead of deletion - they carry decision history worth keeping out of the working set but not destroying.

## Step 3 - Documentation orphan sweep + reviews staleness (`target:full`; reviews pass alone via `target:reviews`)

Tracked-doc orphan findings are judgment-based, **evidence-only, NEVER executable**. The `docs/reviews/` staleness pass below is the one exception with an action - and that action is archive-only, never deletion.

Scan `docs/**/*.md`, excluding the pipeline-fed canonical set (`requirements.md`, `implementation-checklist.md`, `refactoring-backlog.md`, `sitemap.md`, `db-map.md`, `pipeline-standards.md`, `claudemd-standards.md`, `model-effort-policy.md`, `adr/`, `specs/`, `metrics/`). For each remaining file, check inbound references - Grep across every other tracked doc, every `SKILL.md`, `CLAUDE.md`, and the `.claude/rules/*.md` files. A file with zero inbound references AND content suggesting a closed/superseded snapshot is reported as **evidence-only**.

Additionally (Tierward repo, also runs under `target:reviews`): scan `docs/reviews/` (gitignored, local audit history), excluding `docs/reviews/archive/` (the destination). For each dated snapshot dir/file:

1. **Mechanical KEEP first (non-negotiable)**: Grep for inbound references across `roadmap-status.md`, every tracked doc, every `SKILL.md`, `CLAUDE.md`, and `.claude/rules/*.md`. Any hit → KEEP, regardless of age or absorption evidence (e.g. the roadmap "Source files for open items" table cites review synthesis files - those must stay where the pointer says).
2. For the rest, classify by staleness - ALL THREE required, never one alone: (a) findings absorbed into `docs/refactoring-backlog.md` or roadmap-status, (b) superseded by a more recent review of the same surface, (c) older than 30 days.
3. **Action semantics - archive-only**: candidates are proposed as `mv docs/reviews/<item> docs/reviews/archive/` in the Step 5 batch. **Deletion of anything under `docs/reviews/` stays forbidden** - this history exists nowhere else (gitignored, no git recovery); a move within the same tree is reversible by hand, a delete is not.

**Hard rule**: documentation is git-tracked content - a wrong call here is real, hard-to-reverse loss, a different risk class than a git branch or a local session file. Never include a doc-orphan finding in the Step 5 confirmation batch, never suggest a deletion command for it, regardless of how confident the evidence looks. State this limitation explicitly in the report so it doesn't read as an oversight.

## Step 4 - Report

Present findings grouped by category, each with its evidence. For branches/worktrees/session files: include the exact command that would run. For doc orphans: evidence only, explicitly labeled "not included in execution - human judgment required."

## Step 5 - Confirm (AskUserQuestion)

One batched question (or a small set): list the exact items proposed for deletion, grouped, with an option to execute all / execute a subset / cancel. Initiatives candidates state their proposed action per item (archive vs delete). `ORPHAN_WORKTREE_DIR` items are NEVER part of the batch: each gets its own dedicated confirmation, with the content summary restated. Reviews-staleness candidates enter the batch as MOVES only (`mv` into `docs/reviews/archive/`), clearly labeled as such. Do not include tracked-doc orphan findings in this gate - they were never candidates for execution.

## Step 6 - Execute confirmed items only

- Branches: `git branch -d <name>`
- Worktrees: `git worktree remove <path>`
- Prunable worktree registrations: `git worktree prune`
- Session files: `rm .claude/session/<file>.md` - only for items the user explicitly confirmed, one at a time, never a bulk `rm .claude/session/*.md`.
- Initiatives: `rm .claude/initiatives/<file>.md` (delete) or `mkdir -p docs/reviews/archive && mv .claude/initiatives/<file>.md docs/reviews/archive/` (archive) - one at a time, per the action confirmed for that item. Never touch `roadmap-status.md`.
- Orphan worktree dirs: `rm -rf .claude/worktrees/<dir>` - only after that item's own dedicated confirmation.
- Reviews snapshots: `mv docs/reviews/<item> docs/reviews/archive/` - one at a time, archive-only; never `rm` anything under `docs/reviews/`.

If any command refuses (unmerged branch, dirty worktree), stop and report - do not force.

## Step 7 - Summary

One line per category: found / confirmed / executed / left for later (docs). If nothing was found in a category, say so plainly rather than omitting the section - a clean report is a valid, useful outcome.