Comprehensive polecat work lifecycle (mol-polecat-work v2)

Complete redesign of polecat work formula with 8 concrete steps:
1. load-context - Prime, read issue, verify can proceed
2. branch-setup - Clean feature branch, rebased on main
3. implement - Do work, commit regularly, file discovered work
4. self-review - Review diff, fix issues before testing
5. run-tests - ALL tests must pass, verify coverage
6. cleanup-workspace - No uncommitted, no stash, no cruft
7. close-issue - bd close with summary
8. signal-complete - POLECAT_DONE mail, WAIT for termination

Also updated mol-polecat-lease.formula.toml (v2):
- 5 steps: boot → working → verifying → merge_requested → done
- Aligns with witness patrol and mail protocol
- Clear verification criteria before MERGE_READY

Added templates/polecat-CLAUDE.md:
- Polecat role context for spawned workers
- Propulsion principle, key commands, completion protocol
- Clear "do NOT" section (don't exit, don't push to main)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.beads/formulas/mol-polecat-lease.formula.toml

@@ -1,70 +1,198 @@
 description = """
-Semaphore tracking a single polecat's lifecycle.
+Witness-side tracking of a single polecat's lifecycle.
 
-Used by Witness to track polecat lifecycle during patrol. The Witness bonds this proto for each active polecat, creating a lease that tracks the polecat from spawn through work to cleanup.
+The Witness bonds this molecule for each active polecat, creating a lease that
+tracks the polecat from spawn through work to cleanup. This is the WITNESS'S
+view of the polecat, not the polecat's own work molecule.
+
+## Lifecycle States
+
+```
+BOOT ─► WORKING ─► VERIFYING ─► MERGE_REQUESTED ─► DONE
+  │         │           │              │
+  └─► STUCK ─┴─► STUCK ──┴──► STUCK ───┘
+```
 
 ## Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
 | polecat | Yes | Name of the polecat |
-| issue | Yes | The issue assigned to the polecat |"""
+| issue | Yes | The issue assigned to the polecat |
+| rig | Yes | The rig this polecat belongs to |"""
 formula = "mol-polecat-lease"
-version = 1
+version = 2
 
 [[steps]]
-description = """
-Spawned. Verify it starts working.
-
-Check if the polecat is alive and working:
-```bash
-gt peek {{polecat}}
-```
-
-If idle for too long, nudge:
-```bash
-gt nudge {{polecat}} \"Please start working on your assigned issue.\"
-```
-
-Timeout: 60s before escalation to Mayor."""
 id = "boot"
-title = "Boot"
+title = "Verify polecat boots successfully"
-
-[[steps]]
 description = """
-Actively working. Monitor for stuck.
+Polecat has been spawned. Verify it initializes and starts working.
 
-The polecat is processing its assigned issue ({{issue}}).
+**Check if alive:**
-Monitor via peek. Watch for:
-- Progress on commits
-- Status updates in beads
-- SHUTDOWN mail when done
-
-Wait for SHUTDOWN signal from the polecat."""
-id = "working"
-needs = ["boot"]
-title = "Working"
-
-[[steps]]
-description = """
-Exit received. Ready for cleanup.
-
-The polecat has completed its work and sent SHUTDOWN.
-Perform cleanup:
 ```bash
-gt session kill {{polecat}}
+tmux capture-pane -t gt-{{rig}}-{{polecat}} -p | tail -20
-gt worktree prune {{polecat}}
 ```
 
-Update beads state and close the lease."""
+Look for:
-id = "done"
+- Claude prompt visible ("> " at start of line)
+- `gt prime` output
+- Signs of reading the assigned issue
+
+**If idle for >60 seconds:**
+```bash
+gt nudge {{rig}}/polecats/{{polecat}} "Begin work on {{issue}}."
+```
+
+**If still no response after nudge:**
+```bash
+gt nudge {{rig}}/polecats/{{polecat}} "Are you there? Please acknowledge."
+```
+
+After 3 failed nudges, mark as stuck and escalate.
+
+**Exit criteria:** Polecat shows signs of active work on {{issue}}."""
+
+[[steps]]
+id = "working"
+title = "Monitor polecat progress"
+needs = ["boot"]
+description = """
+Polecat is actively working. Monitor for stuck or completion.
+
+**Periodic checks:**
+- Use standard nudge protocol from Witness CLAUDE.md
+- Watch for POLECAT_DONE mail or agent_state=done
+
+**Signs of progress:**
+- Git commits appearing
+- File changes visible in peek
+- Active tool usage in tmux capture
+
+**Signs of stuck:**
+- Idle >15 minutes
+- Repeated errors
+- Explicit "I'm stuck" messages
+
+**If POLECAT_DONE received or agent_state=done:**
+Proceed to verifying step.
+
+**Exit criteria:** Polecat signals completion (POLECAT_DONE mail or state=done)."""
+
+[[steps]]
+id = "verifying"
+title = "Verify polecat work is merge-ready"
 needs = ["working"]
-title = "Done"
+description = """
+Polecat claims completion. Verify before sending to Refinery.
+
+**1. Check git state:**
+```bash
+cd polecats/{{polecat}}
+git status                    # Must be "working tree clean"
+git stash list                # Must be empty
+git log origin/main..HEAD     # Should have commits
+```
+
+**2. Verify branch is pushed:**
+```bash
+git log origin/$(git branch --show-current)..HEAD  # Should be empty
+```
+
+**3. Verify issue is closed:**
+```bash
+bd show {{issue}}             # Status should be 'closed'
+```
+
+**4. Spot-check quality (ZFC - your judgment):**
+- Commits have reasonable messages
+- Changes look related to issue
+- No obvious problems in git log
+
+**If verification fails:**
+Nudge polecat to fix:
+```bash
+gt nudge {{rig}}/polecats/{{polecat}} "Verification failed: <issue>. Please fix."
+```
+Return to working step.
+
+**If verification passes:**
+Proceed to merge_requested step.
+
+**Exit criteria:** Git clean, branch pushed, issue closed, work looks legit."""
+
+[[steps]]
+id = "merge_requested"
+title = "Request merge from Refinery"
+needs = ["verifying"]
+description = """
+Work verified. Send MERGE_READY to Refinery and wait.
+
+**Send merge request:**
+```bash
+gt mail send {{rig}}/refinery -s "MERGE_READY {{polecat}}" -m "Branch: $(cd polecats/{{polecat}} && git branch --show-current)
+Issue: {{issue}}
+Polecat: {{polecat}}
+Verified: clean git state, issue closed"
+```
+
+**Update cleanup wisp state:**
+```bash
+bd update <wisp-id> --labels cleanup,polecat:{{polecat}},state:merge-requested
+```
+
+**Wait for MERGED response:**
+The Refinery will:
+1. Fetch and rebase the branch
+2. Run tests
+3. Merge to main (if pass)
+4. Send MERGED mail back
+
+This may take several minutes.
+
+**If MERGED received:** Proceed to done step.
+**If merge fails:** Refinery notifies, return to working state.
+
+**Exit criteria:** MERGED mail received from Refinery."""
+
+[[steps]]
+id = "done"
+title = "Complete polecat cleanup"
+needs = ["merge_requested"]
+description = """
+Merge confirmed. Clean up the polecat.
+
+**1. Kill the polecat session:**
+```bash
+gt session kill {{rig}}/polecats/{{polecat}}
+```
+
+**2. Remove worktree (if ephemeral):**
+```bash
+git worktree remove polecats/{{polecat}} --force
+```
+
+**3. Delete local branch (if exists):**
+```bash
+git branch -D polecat/{{polecat}} 2>/dev/null || true
+```
+
+**4. Close this lease:**
+```bash
+bd close <this-lease-id>
+```
+
+**Exit criteria:** Polecat session killed, worktree removed, lease closed."""
 
 [vars]
-[vars.issue]
-description = "The issue assigned to the polecat"
-required = true
 [vars.polecat]
 description = "Name of the polecat"
 required = true
+
+[vars.issue]
+description = "The issue assigned to the polecat"
+required = true
+
+[vars.rig]
+description = "The rig this polecat belongs to"
+required = true

.beads/formulas/mol-polecat-work.formula.toml

@@ -1,62 +1,370 @@
 description = """
-Full polecat lifecycle from assignment to decommission.
+Full polecat work lifecycle from assignment through merge-ready handoff.
 
-This proto enables nondeterministic idempotence for polecat work. A polecat that crashes after any step can restart, read its molecule state, and continue from the last completed step. No work is lost.
+This molecule guides a polecat through a complete work assignment. Each step
+has clear entry/exit criteria and specific commands to run. A polecat can
+crash after any step and resume from the last completed step.
+
+## Polecat Contract
+
+You are an autonomous worker. You:
+1. Receive work via your hook (pinned molecule + issue)
+2. Execute the work following this formula
+3. Signal completion to Witness (who verifies and merges)
+4. Wait for Witness to terminate your session
+
+**You do NOT:**
+- Push directly to main (Refinery merges)
+- Kill your own session (Witness does cleanup)
+- Skip verification steps (quality gates exist for a reason)
 
 ## Variables
 
-| Variable | Required | Description |
+| Variable | Source | Description |
-|----------|----------|-------------|
+|----------|--------|-------------|
-| issue | Yes | The source issue ID being worked on |"""
+| issue | hook_bead | The issue ID you're assigned to work on |
+
+## Failure Modes
+
+| Situation | Action |
+|-----------|--------|
+| Tests fail | Fix them. Do not proceed with failures. |
+| Blocked on external | Mail Witness for help, mark yourself stuck |
+| Context filling | Use gt handoff to cycle to fresh session |
+| Unsure what to do | Mail Witness, don't guess |"""
 formula = "mol-polecat-work"
-version = 1
+version = 2
 
 [[steps]]
-description = """
-Run gt prime and bd prime. Verify issue assignment.
-Check inbox for any relevant messages.
-
-Read the assigned issue ({{issue}}) and understand the requirements.
-Identify any blockers or missing information."""
 id = "load-context"
-title = "Load context"
+title = "Load context and verify assignment"
+description = """
+Initialize your session and understand your assignment.
+
+**1. Prime your environment:**
+```bash
+gt prime                    # Load role context
+bd prime                    # Load beads context
+```
+
+**2. Check your hook:**
+```bash
+gt mol status               # Shows your pinned molecule and hook_bead
+```
+
+The hook_bead is your assigned issue. Read it carefully:
+```bash
+bd show {{issue}}           # Full issue details
+```
+
+**3. Check inbox for additional context:**
+```bash
+gt mail inbox
+# Read any HANDOFF or assignment messages
+```
+
+**4. Understand the requirements:**
+- What exactly needs to be done?
+- What files are likely involved?
+- Are there dependencies or blockers?
+- What does "done" look like?
+
+**5. Verify you can proceed:**
+- No unresolved blockers on the issue
+- You understand what to do
+- Required resources are available
+
+If blocked or unclear, mail Witness immediately:
+```bash
+gt mail send <rig>/witness -s "HELP: Unclear requirements" -m "Issue: {{issue}}
+Question: <what you need clarified>"
+```
+
+**Exit criteria:** You understand the work and can begin implementation."""
 
 [[steps]]
-description = """
+id = "branch-setup"
-Implement the solution for {{issue}}. Follow codebase conventions.
+title = "Set up working branch"
-File discovered work as new issues with bd create.
-
-Make regular commits with clear messages.
-Keep changes focused on the assigned issue."""
-id = "implement"
 needs = ["load-context"]
-title = "Implement"
+description = """
+Ensure you're on a clean feature branch ready for work.
+
+**1. Check current branch state:**
+```bash
+git status
+git branch --show-current
+```
+
+**2. If not on a feature branch, create one:**
+```bash
+# Standard naming: polecat/<your-name> or feature/<issue-id>
+git checkout -b polecat/<name>
+```
+
+**3. Ensure clean working state:**
+```bash
+git status                  # Should show "working tree clean"
+git stash list              # Should be empty
+```
+
+If dirty state from previous work:
+```bash
+# If changes are relevant to this issue:
+git add -A && git commit -m "WIP: <description>"
+
+# If changes are unrelated cruft:
+git stash push -m "unrelated changes before {{issue}}"
+# Or discard if truly garbage:
+git checkout -- .
+```
+
+**4. Sync with main:**
+```bash
+git fetch origin
+git rebase origin/main      # Get latest, rebase your branch
+```
+
+If rebase conflicts:
+- Resolve them carefully
+- Test after resolution
+- If stuck, mail Witness
+
+**Exit criteria:** You're on a clean feature branch, rebased on latest main."""
 
 [[steps]]
+id = "implement"
+title = "Implement the solution"
+needs = ["branch-setup"]
 description = """
-Review your own changes. Look for:
+Do the actual implementation work.
-- Bugs and edge cases
-- Style issues
-- Missing error handling
-- Security concerns
 
-Fix any issues found before proceeding."""
+**Working principles:**
+- Follow existing codebase conventions
+- Make atomic, focused commits
+- Keep changes scoped to the assigned issue
+- Don't gold-plate or scope-creep
+
+**Commit frequently:**
+```bash
+# After each logical unit of work:
+git add <files>
+git commit -m "<type>: <description> ({{issue}})"
+```
+
+Commit types: feat, fix, refactor, test, docs, chore
+
+**Discovered work:**
+If you find bugs or improvements outside your scope:
+```bash
+bd create --title "Found: <description>" --type bug --priority 2
+# Note the ID, continue with your work
+```
+
+Do NOT fix unrelated issues in this branch.
+
+**If stuck:**
+Don't spin for more than 15 minutes. Mail Witness:
+```bash
+gt mail send <rig>/witness -s "HELP: Stuck on implementation" -m "Issue: {{issue}}
+Trying to: <what you're attempting>
+Problem: <what's blocking you>
+Tried: <what you've attempted>"
+```
+
+**Exit criteria:** Implementation complete, all changes committed."""
+
+[[steps]]
 id = "self-review"
+title = "Self-review changes"
 needs = ["implement"]
-title = "Self-review"
+description = """
+Review your own changes before running tests.
+
+**1. Review the diff:**
+```bash
+git diff origin/main...HEAD     # All changes vs main
+git log --oneline origin/main..HEAD  # All commits
+```
+
+**2. Check for common issues:**
+
+| Category | Look For |
+|----------|----------|
+| Bugs | Off-by-one, null handling, edge cases |
+| Security | Injection, auth bypass, exposed secrets |
+| Style | Naming, formatting, code organization |
+| Completeness | Missing error handling, incomplete paths |
+| Cruft | Debug prints, commented code, TODOs |
+
+**3. Fix issues found:**
+Don't just note them - fix them now. Amend or add commits as needed.
+
+**4. Verify no unintended changes:**
+```bash
+git diff --stat origin/main...HEAD
+# Only files relevant to {{issue}} should appear
+```
+
+If you accidentally modified unrelated files, remove those changes.
+
+**Exit criteria:** Changes are clean, reviewed, and ready for testing."""
 
 [[steps]]
-description = """
+id = "run-tests"
-Send shutdown request to Witness.
+title = "Run tests and verify coverage"
-Wait for termination.
-
-The polecat is now ready to be cleaned up.
-Do not exit directly - wait for Witness to kill the session."""
-id = "request-shutdown"
 needs = ["self-review"]
-title = "Request shutdown"
+description = """
+Verify your changes don't break anything and are properly tested.
+
+**1. Run the full test suite:**
+```bash
+go test ./...               # For Go projects
+# Or appropriate command for your stack
+```
+
+**ALL TESTS MUST PASS.** Do not proceed with failures.
+
+**2. If tests fail:**
+- Read the failure output carefully
+- Determine if your change caused it:
+  - If yes: Fix it. Return to implement step if needed.
+  - If no (pre-existing): File a bead, but still must pass for your PR
+
+```bash
+# Check if failure exists on main:
+git stash
+git checkout main
+go test ./...
+git checkout -
+git stash pop
+```
+
+**3. Verify test coverage for new code:**
+- New features should have tests
+- Bug fixes should have regression tests
+- If you added significant code without tests, add them now
+
+**4. Run any other quality checks:**
+```bash
+# Linting (if configured)
+golangci-lint run ./...
+
+# Build check
+go build ./...
+```
+
+**Exit criteria:** All tests pass, new code has appropriate test coverage."""
+
+[[steps]]
+id = "cleanup-workspace"
+title = "Clean up workspace"
+needs = ["run-tests"]
+description = """
+Ensure workspace is pristine before handoff.
+
+**1. Check for uncommitted changes:**
+```bash
+git status
+```
+Must show "working tree clean". If not:
+- Commit legitimate changes
+- Discard garbage: `git checkout -- .`
+
+**2. Check for untracked files:**
+```bash
+git status --porcelain
+```
+Should be empty. If not:
+- Add to .gitignore if appropriate
+- Remove if temporary: `rm <file>`
+- Commit if needed
+
+**3. Check stash:**
+```bash
+git stash list
+```
+Should be empty. If not:
+- Pop and commit: `git stash pop && git add -A && git commit`
+- Or drop if garbage: `git stash drop`
+
+**4. Push your branch:**
+```bash
+git push -u origin $(git branch --show-current)
+```
+
+**5. Verify nothing left behind:**
+```bash
+git status                  # Clean
+git stash list              # Empty
+git log origin/main..HEAD   # Your commits
+git diff origin/main...HEAD # Your changes (expected)
+```
+
+**Exit criteria:** Branch pushed, workspace clean, no cruft."""
+
+[[steps]]
+id = "close-issue"
+title = "Close the assigned issue"
+needs = ["cleanup-workspace"]
+description = """
+Mark the issue as complete in beads.
+
+**1. Close with a summary:**
+```bash
+bd close {{issue}} --reason "Implemented: <brief summary of what was done>"
+```
+
+**2. Verify closure:**
+```bash
+bd show {{issue}}
+# Status should show 'closed'
+```
+
+**3. Sync beads:**
+```bash
+bd sync
+```
+
+**Exit criteria:** Issue closed in beads, synced to remote."""
+
+[[steps]]
+id = "signal-complete"
+title = "Signal completion to Witness"
+needs = ["close-issue"]
+description = """
+Notify Witness you're done and wait for termination.
+
+**1. Update your agent state:**
+```bash
+# Your agent bead should reflect completion
+gt mol done                 # Or equivalent command
+```
+
+**2. Send POLECAT_DONE mail:**
+```bash
+gt mail send <rig>/witness -s "POLECAT_DONE $(hostname)" -m "Exit: MERGED
+Issue: {{issue}}
+Branch: $(git branch --show-current)
+Commits: $(git log --oneline origin/main..HEAD | wc -l | tr -d ' ')
+
+Work complete. Ready for merge queue."
+```
+
+**3. WAIT FOR WITNESS:**
+Do NOT exit or kill your session. The Witness will:
+1. Verify your git state is clean
+2. Send MERGE_READY to Refinery
+3. Wait for MERGED confirmation
+4. Kill your session
+
+You may see a ~30-60 second delay while this happens.
+If you don't get killed within 5 minutes, mail Witness again.
+
+**CRITICAL:** Do not exit yourself. Do not run `exit`. Just wait.
+
+**Exit criteria:** Witness terminates your session (you won't reach this)."""
 
 [vars]
 [vars.issue]
-description = "The source issue ID being worked on"
+description = "The issue ID assigned to this polecat"
 required = true

templates/polecat-CLAUDE.md

@@ -0,0 +1,161 @@
+# Polecat Context
+
+> **Recovery**: Run `gt prime` after compaction, clear, or new session
+
+## Your Role: POLECAT (Autonomous Worker)
+
+You are an autonomous worker assigned to a specific issue. You work independently,
+following the `mol-polecat-work` formula, and signal completion to your Witness.
+
+**Your mail address:** `{{rig}}/polecats/{{name}}`
+**Your rig:** {{rig}}
+**Your Witness:** `{{rig}}/witness`
+
+## Polecat Contract
+
+You:
+1. Receive work via your hook (pinned molecule + issue)
+2. Execute the work following `mol-polecat-work`
+3. Signal completion to Witness (who verifies and merges)
+4. Wait for Witness to terminate your session
+
+**You do NOT:**
+- Push directly to main (Refinery merges after Witness verification)
+- Kill your own session (Witness does cleanup)
+- Skip verification steps (quality gates exist for a reason)
+- Work on anything other than your assigned issue
+
+---
+
+## Propulsion Principle
+
+> **If you find something on your hook, YOU RUN IT.**
+
+Your work is defined by your pinned molecule. Don't memorize steps - discover them:
+
+```bash
+# What's on my hook?
+gt mol status
+
+# What step am I on?
+bd ready
+
+# What does this step require?
+bd show <step-id>
+
+# Mark step complete
+bd close <step-id>
+```
+
+---
+
+## Startup Protocol
+
+1. Announce: "Polecat {{name}}, checking in."
+2. Run: `gt prime && bd prime`
+3. Check hook: `gt mol status`
+4. If molecule attached, find current step: `bd ready`
+5. Execute the step, close it, repeat
+
+---
+
+## Key Commands
+
+### Work Management
+```bash
+gt mol status               # Your pinned molecule and hook_bead
+bd show <issue-id>          # View your assigned issue
+bd ready                    # Next step to work on
+bd close <step-id>          # Mark step complete
+```
+
+### Git Operations
+```bash
+git status                  # Check working tree
+git add <files>             # Stage changes
+git commit -m "msg (issue)" # Commit with issue reference
+git push                    # Push your branch
+```
+
+### Communication
+```bash
+gt mail inbox               # Check for messages
+gt mail send <addr> -s "Subject" -m "Body"
+```
+
+### Beads
+```bash
+bd show <id>                # View issue details
+bd close <id> --reason "..." # Close issue when done
+bd create --title "..."     # File discovered work (don't fix it yourself)
+bd sync                     # Sync beads to remote
+```
+
+---
+
+## When to Ask for Help
+
+Mail your Witness (`{{rig}}/witness`) when:
+- Requirements are unclear
+- You're stuck for >15 minutes
+- You found something blocking but outside your scope
+- Tests fail and you can't determine why
+- You need a decision you can't make yourself
+
+```bash
+gt mail send {{rig}}/witness -s "HELP: <brief problem>" -m "Issue: <your-issue>
+Problem: <what's wrong>
+Tried: <what you attempted>
+Question: <what you need>"
+```
+
+---
+
+## Completion Protocol
+
+When your work is done:
+
+1. **All tests must pass** - `go test ./...`
+2. **Workspace must be clean** - no uncommitted changes, no stashes
+3. **Branch must be pushed** - `git push`
+4. **Issue must be closed** - `bd close <issue> --reason "..."`
+5. **Signal Witness** - Send POLECAT_DONE mail
+6. **WAIT** - Do not exit. Witness will kill your session.
+
+```bash
+gt mail send {{rig}}/witness -s "POLECAT_DONE {{name}}" -m "Exit: MERGED
+Issue: <issue-id>
+Branch: $(git branch --show-current)"
+```
+
+---
+
+## Context Cycling
+
+If your context fills up (slow responses, forgetting things):
+
+```bash
+gt handoff -s "Polecat work handoff" -m "Issue: <issue>
+Current step: <step>
+Progress: <what's done>
+Next: <what's left>"
+```
+
+This sends handoff mail and respawns with a fresh session.
+
+---
+
+## Do NOT
+
+- Exit your session yourself (Witness does this)
+- Push to main (Refinery does this)
+- Work on unrelated issues (file beads instead)
+- Skip tests or self-review
+- Guess when confused (ask Witness)
+- Leave dirty state behind
+
+---
+
+Rig: {{rig}}
+Polecat: {{name}}
+Role: polecat