ai-branch-cleanup

name	ai-branch-cleanup
description	Cleans branches safely: switches to the default branch, prunes merged and squash-merged branches, syncs to remote, sweeps stale specs, rotates `.ai-engineering/runtime/` per retention policy. Trigger for 'tidy up', 'tidy branches', 'sync to main', 'delete old branches', 'start fresh', 'rotate runtime'. Auto-invoked by /ai-pr after merge. Not for committing changes; use /ai-commit instead. Not for code-level dead-code removal; use /ai-simplify instead.
effort	cheap
argument-hint	--branches|--sync|--specs|--runtime|--consolidate-spec <slug>|--all
tags	["git","branch","cleanup","hygiene","status","delivery"]
requires	{"bins":["git"]}

Branch Cleanup

Full repository hygiene: safely migrate to the default branch, delete merged and squash-merged branches, sweep stale specs, rotate runtime artifacts, and produce a per-branch status report. No destructive operations without confirmation.

Quick start

/ai-branch-cleanup              # full: instinct consolidation + sync + branch cleanup + spec sweep + runtime rotate + report
/ai-branch-cleanup --sync       # sync to default branch only
/ai-branch-cleanup --branches   # branch cleanup only (no migration)
/ai-branch-cleanup --specs      # spec lifecycle sweep + _history.md rotation (DRAFT >14d → ABANDONED; SHIPPED → row appended)
/ai-branch-cleanup --runtime    # rotate .ai-engineering/runtime/ per retention policy
/ai-branch-cleanup --consolidate-spec <slug>   # manual spec consolidation via _shared/consolidate-spec.md
/ai-branch-cleanup --all        # explicit full cleanup

Process

Default (no flags) ≡ --all: runs Phase 0a → 0 → 1 → 3 → 4 → 5 → 2. Single-purpose flags run only their phase.

Phase 0a — Instinct consolidation (default / --all, fail-open)

• Consolidate session learnings BEFORE switching branches: if .ai-engineering/observations/observations.yml exists, run /ai-session-watch --review to fold this session's observations (especially the LLM-only corrections family) into the corpus — closing the no-commit/no-PR gap where a tidy-up ends a session that never ran --review. Skip silently when the file is absent (fail-open) or when a single-purpose flag (--branches/--sync/--specs/--runtime/--consolidate-spec) ran without --all. Mirrors /ai-pr Step 2 and /ai-commit Step 2.

Phase 0 — Safe migration (--sync or --all)

1. Detect default branch — git symbolic-ref refs/remotes/origin/HEAD (main or master).
2. Record current branch for the report.
3. Auto-stash if dirty — git stash push -m "cleanup-auto-stash-$(date +%s)".
4. Switch to default — git checkout <default>.
5. Pull latest — git pull --ff-only origin <default>. If ff-only fails: WARN and STOP.
6. Restore stash — git stash pop. On conflict: WARN, leave stash, continue cleanup.

Phase 1 — Branch analysis (--branches or --all)

7. Fetch and prune — git fetch --prune origin.
8. Enumerate all local branches (excluding main, master).
9. Classify each branch:

Category	Criteria	Action
Merged	In git branch --merged <default>	Delete (git branch -d)
Squash-merged	Not in --merged but git diff <default>..<branch> is empty	Delete (git branch -D)
Gone (safe)	Tracking ref [gone] AND no content diff	Delete (git branch -D)
Gone (has dev)	Tracking ref [gone] BUT has content diff	KEEP
Active	Has remote tracking, not merged	KEEP
Local only	No remote, has commits ahead	KEEP

10. Delete eligible — merged with -d, squash-merged and gone-safe with -D.

Phase 3 — Spec sweep (--specs or --all)

Reap stale spec drafts so the lifecycle ledger does not accumulate abandonware. Run python .ai-engineering/scripts/spec_lifecycle.py sweep: DRAFTs older than 14 days move to ABANDONED; counts are returned as JSON and emitted as a framework_operation audit event. Fail-open: a missing script or locked sidecar logs and continues — branch cleanup is the load-bearing hot path.

Phase 4 — Runtime rotation (--runtime or --all)

Rotate .ai-engineering/runtime/ so transient observability data does not bloat the working tree. Run python .ai-engineering/scripts/runtime_rotate.py:

Subtree	Retention	Action
runtime/tool-outputs/*.txt	7 days	unlink
runtime/autopilot/sub-*	30 days	rmtree
runtime/tool-history.ndjson	10000 lines / 5 MB	tail-truncate

Hot-path budget <100 ms; stdlib only; idempotent; fail-open on missing dirs; emits a runtime-rotate framework_event per run.

Phase 5 — Spec consolidation (--specs or --all)

ai-eng cleanup specs runs both verbs in order: reconcile_merged then consolidate_shipped. The composite phase ORDER is unchanged (the D-161-04 fix is gh-aware classification, NOT resequencing).

1. Reconcile (python .ai-engineering/scripts/spec_lifecycle.py reconcile_merged, the D-153-03 backstop): for any non-terminal sidecar (DRAFT/APPROVED/IN_PROGRESS), classify merge state primarily via gh PR state (gh pr list --head <branch> --state merged) — this SURVIVES the Phase-1 branch prune; the local-ref check (git branch --merged + squash-merge emptiness) is the FALLBACK when gh is absent. On a merged classification, resolve the PR via gh and call mark_shipped — catching specs merged via the GitHub UI that /ai-pr never marked, including those whose local branch Phase 1 already deleted.
2. Consolidate (python .ai-engineering/scripts/spec_lifecycle.py consolidate_shipped): append the canonical 7-col _history.md row for any SHIPPED record (including ones reconcile just marked) and emit the framework_operation audit event.

Verification-only step — actual lifecycle writes live in spec_lifecycle.py; this skill calls the entry point. Idempotent: already-SHIPPED records are a no-op. Fail-open: missing script or locked sidecar logs and continues. See .claude/skills/_shared/consolidate-spec.md for the shared handler; the --consolidate-spec <slug> flag exposes the explicit post-merge action via spec_lifecycle.py mark_shipped.

Phase 2 — Status report

11. Build per-branch table:

## Repository Cleanup Report

**Default branch**: `main` (up to date)
**Previous branch**: `feat/old-feature`
**Working tree**: clean | stash restored | stash pending

| Branch | Action | Reason | Remote | Ahead/Behind |
|--------|--------|--------|--------|--------------|
| `feat/done` | DELETED | Merged | -- | -- |
| `feat/squashed` | DELETED | Squash-merged | -- | -- |
| `feat/active` | KEPT | Unmerged (5 commits) | origin/feat/active | +5/-2 |

Phase 6 — Spec consolidation (--consolidate-spec <slug>)

Read .claude/skills/_shared/consolidate-spec.md and execute the shared handler: resolve the spec record, append/upsert the _history.md row via spec_lifecycle.py mark_shipped, clear .ai-engineering/specs/spec.md and plan.md to placeholders. Fail-open on missing script.

Examples

User: "tidy up before I start a new task"

/ai-branch-cleanup

Switches to main, ff-pulls, prunes merged + squash-merged branches, sweeps stale spec drafts, rotates runtime, prints the per-branch report.

Integration

Called by: /ai-pr (auto after merge), /ai-start (session bootstrap). Calls: /ai-session-watch --review (Phase 0a, fail-open instinct consolidation), git, python .ai-engineering/scripts/spec_lifecycle.py sweep, python .ai-engineering/scripts/runtime_rotate.py. See also: /ai-brainstorm (run before new spec), /ai-simplify (code-level cleanup).

References

• .ai-engineering/manifest.yml — protected branch rules.
• .claude/skills/ai-brainstorm/SKILL.md — spec creation composes cleanup. $ARGUMENTS