polecat-lifecycle

# polecat-lifecycle - Polecat Worker Lifecycle

Manage the full lifecycle of polecat worker agents in Gas Town.

> **For Witness and Mayor roles.** Polecats don't manage their own lifecycle.

## Overview

Polecats are worker agents that operate in isolated git worktrees. They spawn,
work, and get cleaned up when done.

| User Says | Claude Does |
|-----------|-------------|
| "spawn a polecat for this" | `gt sling <bead> <rig>` (auto-spawns) |
| "nuke that polecat" | `gt polecat nuke <rig>/<name> --force` |
| "clean up stale branches" | `gt polecat gc <rig>` |
| "is this polecat stuck?" | `gt polecat status <rig>/<name>` |
| "list polecats" | `gt polecat list <rig>` |

---

## Quick Reference

```bash
# Spawn (via sling - auto-creates polecat)
gt sling <bead> <rig>                # Auto-spawn + dispatch

# Manual add (rarely needed)
gt polecat add <rig> <name>          # Create polecat worktree

# Status
gt polecat list <rig>                # List all polecats
gt polecat status <rig>/<name>       # Detailed status

# Cleanup
gt polecat nuke <rig>/<name>         # Destroy (with safety checks)
gt polecat nuke <rig>/<name> --force # Destroy (bypass safety)
gt polecat gc <rig>                  # Clean orphaned branches

# Diagnostics
gt polecat stale <rig>               # Find stale polecats
gt polecat git-state <rig>/<name>    # Pre-nuke verification
gt polecat check-recovery <rig>/<name>  # Recovery needed?
```

---

## Lifecycle Stages

```
┌─────────┐    gt sling     ┌─────────┐    work done    ┌─────────┐
│ (none)  │ ─────────────→  │ working │ ─────────────→  │  done   │
└─────────┘                 └─────────┘                 └─────────┘
     ↑                           │                          │
     │                           │ stuck/error              │
     │                           ↓                          │
     │                      ┌─────────┐                     │
     │                      │  stuck  │                     │
     │