Add mol-polecat-work built-in molecule

Defines the standard polecat work lifecycle molecule with 8 steps:
- load-context: Load context and verify assignment
- implement: Do the work, file discovered issues
- self-review: Review changes for bugs and issues
- verify-tests: Run tests, add new ones as needed
- rebase-main: Rebase against main
- submit-merge: Submit to merge queue
- update-handoff: Update handoff state
- request-shutdown: Request witness termination

This molecule enables nondeterministic idempotence for polecat work.
Crash recovery is automatic - restart reads molecule state and continues
from the last completed step.

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

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

.beads/issues.jsonl

@@ -7,6 +7,7 @@
 {"id":"gt-0pc","title":"Document Overseer role (human operator)","description":"Document the Overseer role in Gas Town architecture.\n\n## The Overseer\n\nThe **Overseer** is the human operator of Gas Town. Not an agent - a person.\n\n## Responsibilities\n\n| Area | Overseer Does | Mayor/Agents Do |\n|------|---------------|-----------------|\n| Strategy | Define project goals | Execute toward goals |\n| Priorities | Set priority order | Work in priority order |\n| Escalations | Final decision on stuck work | Escalate to Overseer |\n| Resources | Provision machines | Use allocated resources |\n| Quality | Review \u0026 approve swarm output | Produce output |\n| Operations | Run gt commands, monitor dashboards | Do the work |\n\n## Key Interactions\n\n### Overseer → Mayor\n- Start/stop Mayor sessions\n- Direct Mayor via conversation\n- Review Mayor recommendations\n- Approve cross-rig decisions\n\n### Mayor → Overseer (Escalations)\n- Stuck workers after retries\n- Resource decisions (add machines, polecats)\n- Ambiguous requirements\n- Architecture decisions\n\n## Operating Cadence\n\nTypical Overseer workflow:\n1. Morning: Check status, review overnight work\n2. During day: Monitor, respond to escalations, adjust priorities\n3. End of day: Review progress, plan next batch\n\n## Commands for Overseers\n\n```bash\ngt status              # Quick health check\ngt doctor              # Detailed diagnostics  \ngt doctor --fix        # Auto-repair issues\ngt inbox               # Messages from agents\ngt stop --all          # Emergency halt\n```\n\n## Documentation Updates\n\nAdd to docs/architecture.md:\n- Overseer section under Agent Roles\n- Clarify Mayor reports to Overseer\n- Add Overseer to workflow diagrams","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-15T23:18:03.177633-08:00","updated_at":"2025-12-15T23:22:51.477786-08:00","closed_at":"2025-12-15T23:22:51.477786-08:00"}
 {"id":"gt-0pl","title":"Polecat CLAUDE.md: configure auto-approve for bd and gt commands","description":"Polecats get stuck waiting for bash command approval when running\nbd and gt commands. Need to configure Claude Code to auto-approve these.\n\nOptions:\n1. Add allowedTools to polecat CLAUDE.md\n2. Configure .claude/settings.json in polecat directory\n3. Use --dangerously-skip-permissions flag (not recommended)\n\nShould auto-approve:\n- bd (beads commands)\n- gt (gastown commands)\n- go build/test\n- git status/add/commit/push\n\nShould still require approval:\n- rm -rf\n- Arbitrary commands outside project\n\nRelated to polecat prompting (gt-e1y, gt-sd6).","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-17T14:10:27.611612-08:00","updated_at":"2025-12-17T14:22:00.715979-08:00","closed_at":"2025-12-17T14:22:00.715979-08:00"}
 {"id":"gt-0qki","title":"Refinery-Witness communication protocol","description":"Define mail protocol between Refinery and Witness:\n\nFROM Witness → Refinery:\n- 'Polecat ready': polecat X completed work, ready for merge\n- 'Rework complete': polecat Y finished requested rework\n\nFROM Refinery → Witness:\n- 'Merge success': polecat X merged, can be cleaned up\n- 'Merge failed': polecat X needs rework on \u003creason\u003e\n- 'Rework request': please have a polecat rebase X on current main\n\nImplement as structured mail with parseable format.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-19T18:09:27.451344-08:00","updated_at":"2025-12-19T18:09:27.451344-08:00","dependencies":[{"issue_id":"gt-0qki","depends_on_id":"gt-ktal","type":"blocks","created_at":"2025-12-19T18:09:39.58445-08:00","created_by":"daemon"}]}
+{"id":"gt-14hd","title":"Work on ga-xxp: Define mol-polecat-work standard molecule...","description":"Work on ga-xxp: Define mol-polecat-work standard molecule. See bd show ga-xxp for full details.","status":"in_progress","priority":2,"issue_type":"task","assignee":"gastown/polecat-01","created_at":"2025-12-19T21:49:14.070072-08:00","updated_at":"2025-12-19T21:49:14.140363-08:00"}
 {"id":"gt-17r","title":"Doctor check: Zombie session cleanup","description":"Detect and clean up zombie tmux sessions via gt doctor.\n\n## Problem\n\nZombie sessions occur when:\n- Agent crashes without cleanup\n- gt kill fails mid-operation\n- System restart leaves orphan sessions\n- Session naming collision\n\n## Checks\n\n### ZombieSessionCheck\n- List all tmux sessions matching gt-* pattern\n- Cross-reference with known polecats\n- Flag sessions with no corresponding polecat state\n- Flag sessions for removed polecats\n- Check session age vs polecat creation time\n\n### Detection Criteria\n- Session exists but polecat directory doesn't\n- Session name doesn't match any registered polecat\n- Polecat state=idle but session running\n- Multiple sessions for same polecat\n\n## Output\n\n```\n[WARN] Zombie tmux sessions detected:\n  - gt-wyvern-OldPolecat (polecat removed)\n  - gt-beads-Unknown (no matching polecat)\n  - gt-wyvern-Toast (duplicate session)\n\n  Run 'gt doctor --fix' to clean up\n```\n\n## Auto-Fix (--fix flag)\n\n- Kill orphan tmux sessions\n- Update polecat state to match reality\n- Log all cleanup actions\n\n## Safety\n\n- Never kill sessions where polecat state=working\n- Prompt before killing if --fix used without --force\n- Create audit log of killed sessions","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T23:18:01.446702-08:00","updated_at":"2025-12-15T23:18:39.517644-08:00","dependencies":[{"issue_id":"gt-17r","depends_on_id":"gt-f9x.4","type":"blocks","created_at":"2025-12-15T23:19:05.66301-08:00","created_by":"daemon"},{"issue_id":"gt-17r","depends_on_id":"gt-7ik","type":"blocks","created_at":"2025-12-17T15:44:41.945064-08:00","created_by":"daemon"}]}
 {"id":"gt-17zr","title":"gt refinery start: doesn't actually start a session","description":"## Problem\n\n`gt refinery start gastown` reports success but doesn't start a tmux session.\n\n## Evidence\n\n```\n$ gt refinery start gastown\nStarting refinery for gastown...\n✓ Refinery started for gastown\n\n$ tmux list-sessions | grep refinery\n(nothing)\n\n$ gt refinery status gastown\nState: ○ stopped\n```\n\n## Expected\n\nShould start a tmux session (e.g., gt-gastown-refinery) with Claude processing the merge queue.\n\n## Related\n\n- gt-kcee: Witness commands also need implementation\n- The refinery 'start' may just be updating state.json without spawning a session","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-18T21:58:57.188389-08:00","updated_at":"2025-12-19T01:33:49.858934-08:00","closed_at":"2025-12-19T01:33:49.858934-08:00"}
 {"id":"gt-1cuq","title":"Merge: gt-svi.1","description":"type: merge-request\nbranch: polecat/Max\ntarget: main\nsource_issue: gt-svi.1\nrig: gastown","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-18T20:15:31.738938-08:00","updated_at":"2025-12-18T20:15:49.759778-08:00","closed_at":"2025-12-18T20:15:49.759778-08:00"}
@@ -181,6 +182,7 @@
 {"id":"gt-ebl","title":"CLI: names commands for polecat naming pool","description":"Polecat naming pool for auto-generated names.\n\n## Commands\n\n### gt names generate\n```\ngt names generate [--count N]\n```\nGenerate N names from pool.\n\n### gt names add\n```\ngt names add \u003cname\u003e...\n```\nAdd custom names to pool.\n\n### gt names list\n```\ngt names list\n```\nShow available and used names.\n\n### gt names reset\n```\ngt names reset [--keep-used]\n```\nReset pool to defaults.\n\n## Config File\n\u003crig\u003e/town/naming.json:\n```json\n{\n  \"enabled\": true,\n  \"auto_refill\": true,\n  \"refill_threshold\": 5,\n  \"pool\": {\n    \"available\": [\"Toast\", \"Nux\", \"Capable\", ...],\n    \"used\": [\"Alice\", \"Bob\"]\n  }\n}\n```\n\n## Default Pool\nMad Max themed: Toast, Nux, Capable, Furiosa, Immortan, etc.\n\n## Integration\ngt polecat add calls naming pool if no name given:\n```go\nif name == \"\" {\n    name, err = naming.Generate(rigPath)\n}\n```\n\n## New Package\ninternal/naming/\n├── pool.go     # Pool management\n└── defaults.go # Default name lists\n\n## Acceptance Criteria\n- [ ] Auto-generate names on polecat add\n- [ ] Track used vs available\n- [ ] Auto-refill when low\n- [ ] Custom names addable","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-16T14:48:33.592129-08:00","updated_at":"2025-12-16T16:07:13.882465-08:00"}
 {"id":"gt-egu","title":"gt refinery attach: Attach to refinery session","description":"Add 'gt refinery attach [rig]' command to attach to refinery tmux session.\n\nMirrors 'gt mayor attach' pattern. If rig not specified, use current rig context.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-17T21:47:19.164342-08:00","updated_at":"2025-12-17T22:28:45.661097-08:00","closed_at":"2025-12-17T22:28:45.661097-08:00","dependencies":[{"issue_id":"gt-egu","depends_on_id":"gt-hw6","type":"blocks","created_at":"2025-12-17T22:22:47.578871-08:00","created_by":"daemon"}]}
 {"id":"gt-eqys","title":"gt spawn: pasted work assignment needs manual Enter to start","description":"## Problem\n\nAfter `gt spawn` pastes the work assignment into Claude, the session waits for Enter.\n\n## Current Behavior\n\n1. `gt spawn gastown/Rictus --issue gt-xxx`\n2. Session starts, work is pasted\n3. Claude shows 'Pasted text #1 +53 lines' but doesn't start\n4. Must manually send Enter or attach and press Enter\n\n## Expected\n\nThe spawn should send Enter after pasting to kick off the work.\n\n## Related\n\nSame debounce issue as tmux notifications (gt-vnp9).","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-18T21:54:14.111101-08:00","updated_at":"2025-12-19T12:01:32.74364-08:00","closed_at":"2025-12-19T12:01:32.74364-08:00"}
+{"id":"gt-er0u","title":"Work on ga-yp3: Polecat inbox system for reliable work as...","description":"Work on ga-yp3: Polecat inbox system for reliable work assignment. This is P1 priority. See bd show ga-yp3 for full design spec.","status":"in_progress","priority":2,"issue_type":"task","assignee":"gastown/polecat-02","created_at":"2025-12-19T21:57:34.473056-08:00","updated_at":"2025-12-19T21:57:34.540384-08:00"}
 {"id":"gt-eu9","title":"Witness session cycling and handoff","description":"Add session cycling and handoff protocol to Witness CLAUDE.md template.\n\n## Session Cycling Protocol\n\n```markdown\n## Session Cycling\n\nYour context will fill over long swarms. Proactively cycle when:\n- Running for many hours\n- Losing track of which workers you've checked\n- Responses getting slower\n- About to start complex operation\n\n### Handoff Protocol\n\n1. **Capture current state**:\n```bash\ntown list .           # Worker states\ntown all beads        # Pending verifications  \ntown inbox            # Unprocessed messages\n```\n\n2. **Compose handoff note**:\n```\n[HANDOFF_TYPE]: witness_cycle\n[TIMESTAMP]: \u003cnow\u003e\n[RIG]: \u003crig\u003e\n\n## Active Workers\n\u003clist workers and status\u003e\n\n## Pending Verifications\n\u003cworkers signaled done but not verified\u003e\n\n## Recent Actions\n\u003clast 3-5 actions\u003e\n\n## Warnings/Notes\n\u003canything next session should know\u003e\n\n## Next Steps\n\u003cwhat should happen next\u003e\n```\n\n3. **Send handoff**:\n```bash\ntown mail send \u003crig\u003e/witness -s \"Session Handoff\" -m \"\u003cnote\u003e\"\n```\n\n4. **Exit cleanly**: End session, daemon spawns fresh one.\n\n### On Fresh Session Start\n\n1. Check for handoff: `town inbox | grep \"Session Handoff\"`\n2. If found, read it and resume from handoff state\n3. If not found, do full status check\n```\n\n## Implementation\n\nAdd to WITNESS_CLAUDE.md template.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:48:55.484911-08:00","updated_at":"2025-12-15T20:47:30.768506-08:00","dependencies":[{"issue_id":"gt-eu9","depends_on_id":"gt-82y","type":"blocks","created_at":"2025-12-15T19:49:05.846443-08:00","created_by":"daemon"}]}
 {"id":"gt-f8v","title":"Witness pre-kill verification protocol","description":"Add pre-kill verification protocol to Witness CLAUDE.md template.\n\n## Protocol for Witness Prompting\n\n```markdown\n## Pre-Kill Verification Protocol\n\nBefore killing any worker session, verify workspace is clean.\n\n### Verification Steps\n\nWhen a worker signals done:\n\n1. **Capture worker state**:\n```bash\ntown capture \u003cpolecat\u003e \"git status \u0026\u0026 git stash list \u0026\u0026 bd sync --status\"\n```\n\n2. **Assess the output** (use your judgment):\n- Is working tree clean?\n- Is stash list empty?\n- Is beads synced?\n\n3. **Decision**:\n- **CLEAN**: Proceed to kill session\n- **DIRTY**: Send nudge with specific issues\n\n### Nudge Templates\n\n**Uncommitted Changes**:\n```\ntown inject \u003cpolecat\u003e \"WITNESS CHECK: Uncommitted changes found. Please commit or discard: \u003cfiles\u003e. Signal done when clean.\"\n```\n\n**Beads Not Synced**:\n```\ntown inject \u003cpolecat\u003e \"WITNESS CHECK: Beads not synced. Run 'bd sync' then commit. Signal done when complete.\"\n```\n\n### Kill Sequence\n\nOnly after verification passes:\n```bash\ntown kill \u003cpolecat\u003e\ntown sleep \u003cpolecat\u003e\n```\n\n### Escalation\n\nIf worker fails verification 3+ times:\n```bash\ntown mail send mayor/ -s \"Escalation: \u003cpolecat\u003e stuck\" -m \"Cannot complete cleanup after 3 attempts. Issues: \u003clist\u003e.\"\n```\n```\n\n## Implementation\n\nAdd to WITNESS_CLAUDE.md template.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:48:54.065679-08:00","updated_at":"2025-12-15T20:47:30.415244-08:00","dependencies":[{"issue_id":"gt-f8v","depends_on_id":"gt-82y","type":"blocks","created_at":"2025-12-15T19:49:05.763378-08:00","created_by":"daemon"}]}
 {"id":"gt-f9x","title":"Town \u0026 Rig Management: install, doctor, federation","description":"Reify the Gas Town installation as a first-class concept.\n\n## Goals\n- Installable: gt install [path] creates complete installation\n- Diagnosable: gt doctor checks and fixes issues\n- Federable: Clone town to VMs with central control\n\n## Architecture Reference\n\nSee docs/architecture.md for full design, especially:\n- Directory structure (Town Level / Rig Level sections)\n- Configuration (town.json, rigs.json schemas)\n- Key design decisions (visible config dir, decentralized agents)","status":"open","priority":1,"issue_type":"epic","created_at":"2025-12-15T16:36:37.344283-08:00","updated_at":"2025-12-15T21:15:13.120038-08:00","dependencies":[{"issue_id":"gt-f9x","depends_on_id":"gt-u1j.1","type":"blocks","created_at":"2025-12-15T16:37:32.3363-08:00","created_by":"daemon"}]}

internal/beads/builtin_molecules.go

@@ -16,6 +16,7 @@ func BuiltinMolecules() []BuiltinMolecule {
 		ResearchMolecule(),
 		InstallGoBinaryMolecule(),
 		BootstrapGasTownMolecule(),
+		PolecatWorkMolecule(),
 	}
 }
 
@@ -299,6 +300,97 @@ Needs: sync-beads, install-paths`,
 	}
 }
 
+// PolecatWorkMolecule returns the polecat-work molecule definition.
+// This is the full polecat lifecycle from assignment to decommission.
+// It's an operational molecule that enables crash recovery and context survival.
+func PolecatWorkMolecule() BuiltinMolecule {
+	return BuiltinMolecule{
+		ID:    "mol-polecat-work",
+		Title: "Polecat Work",
+		Description: `Full polecat lifecycle from assignment to decommission.
+
+This molecule 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.
+
+## Step: load-context
+Run gt prime and bd prime. Verify issue assignment.
+Check inbox for any relevant messages.
+
+Read the assigned issue and understand the requirements.
+Identify any blockers or missing information.
+
+## Step: implement
+Implement the solution. Follow codebase conventions.
+File discovered work as new issues with bd create.
+
+Make regular commits with clear messages.
+Keep changes focused on the assigned issue.
+Needs: load-context
+
+## Step: self-review
+Review your own changes. Look for:
+- Bugs and edge cases
+- Style issues
+- Missing error handling
+- Security concerns
+
+Fix any issues found before proceeding.
+Needs: implement
+
+## Step: verify-tests
+Run existing tests. Add new tests for new functionality.
+Ensure adequate coverage.
+
+` + "```" + `bash
+go test ./...
+` + "```" + `
+
+Fix any test failures before proceeding.
+Needs: implement
+
+## Step: rebase-main
+Rebase against main to incorporate any changes.
+Resolve conflicts if needed.
+
+` + "```" + `bash
+git fetch origin main
+git rebase origin/main
+` + "```" + `
+
+If there are conflicts, resolve them carefully and
+continue the rebase.
+Needs: self-review, verify-tests
+
+## Step: submit-merge
+Submit to merge queue. Create PR if needed.
+Verify CI passes.
+
+` + "```" + `bash
+gt done  # Signal work ready for merge queue
+` + "```" + `
+
+If there are CI failures, fix them before proceeding.
+Needs: rebase-main
+
+## Step: update-handoff
+Update handoff bead with final state.
+File any remaining work as issues.
+
+Document any important context for the next session
+or for anyone reviewing the work.
+Needs: submit-merge
+
+## Step: request-shutdown
+Send shutdown request to Witness.
+Wait for termination.
+
+The polecat is now ready to be cleaned up.
+Do not exit directly - wait for Witness to kill the session.
+Needs: update-handoff`,
+	}
+}
+
 // SeedBuiltinMolecules creates all built-in molecules in the beads database.
 // It skips molecules that already exist (by title match).
 // Returns the number of molecules created.

internal/beads/builtin_molecules_test.go

@@ -5,8 +5,8 @@ import "testing"
 func TestBuiltinMolecules(t *testing.T) {
 	molecules := BuiltinMolecules()
 
-	if len(molecules) != 4 {
+	if len(molecules) != 6 {
-		t.Errorf("expected 4 built-in molecules, got %d", len(molecules))
+		t.Errorf("expected 6 built-in molecules, got %d", len(molecules))
 	}
 
 	// Verify each molecule can be parsed and validated
@@ -172,3 +172,61 @@ func TestInstallGoBinaryMolecule(t *testing.T) {
 		t.Errorf("install should have no deps, got %v", steps[0].Needs)
 	}
 }
+
+func TestPolecatWorkMolecule(t *testing.T) {
+	mol := PolecatWorkMolecule()
+
+	if mol.ID != "mol-polecat-work" {
+		t.Errorf("expected ID 'mol-polecat-work', got %q", mol.ID)
+	}
+
+	if mol.Title != "Polecat Work" {
+		t.Errorf("expected Title 'Polecat Work', got %q", mol.Title)
+	}
+
+	steps, err := ParseMoleculeSteps(mol.Description)
+	if err != nil {
+		t.Fatalf("failed to parse: %v", err)
+	}
+
+	// Should have 8 steps: load-context, implement, self-review, verify-tests,
+	// rebase-main, submit-merge, update-handoff, request-shutdown
+	if len(steps) != 8 {
+		t.Errorf("expected 8 steps, got %d", len(steps))
+	}
+
+	expectedRefs := []string{
+		"load-context", "implement", "self-review", "verify-tests",
+		"rebase-main", "submit-merge", "update-handoff", "request-shutdown",
+	}
+	for i, expected := range expectedRefs {
+		if i >= len(steps) {
+			t.Errorf("missing step %d: expected %q", i, expected)
+			continue
+		}
+		if steps[i].Ref != expected {
+			t.Errorf("step %d: expected ref %q, got %q", i, expected, steps[i].Ref)
+		}
+	}
+
+	// Verify key dependencies
+	// load-context has no deps
+	if len(steps[0].Needs) != 0 {
+		t.Errorf("load-context should have no deps, got %v", steps[0].Needs)
+	}
+
+	// implement needs load-context
+	if len(steps[1].Needs) != 1 || steps[1].Needs[0] != "load-context" {
+		t.Errorf("implement should need load-context, got %v", steps[1].Needs)
+	}
+
+	// rebase-main needs self-review and verify-tests
+	if len(steps[4].Needs) != 2 {
+		t.Errorf("rebase-main should need 2 deps, got %v", steps[4].Needs)
+	}
+
+	// request-shutdown needs update-handoff
+	if len(steps[7].Needs) != 1 || steps[7].Needs[0] != "update-handoff" {
+		t.Errorf("request-shutdown should need update-handoff, got %v", steps[7].Needs)
+	}
+}