From 7b76ffee4cc107adc1906cb02efe93f8618afb50 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Fri, 19 Dec 2025 22:01:17 -0800 Subject: [PATCH] Add mol-polecat-work built-in molecule MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .beads/issues.jsonl | 2 + internal/beads/builtin_molecules.go | 92 ++++++++++++++++++++++++ internal/beads/builtin_molecules_test.go | 62 +++++++++++++++- 3 files changed, 154 insertions(+), 2 deletions(-) diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index fd1b6007..b4f97bf2 100644 --- a/.beads/issues.jsonl +++ b/.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"}]} diff --git a/internal/beads/builtin_molecules.go b/internal/beads/builtin_molecules.go index 492cd466..187366da 100644 --- a/internal/beads/builtin_molecules.go +++ b/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. diff --git a/internal/beads/builtin_molecules_test.go b/internal/beads/builtin_molecules_test.go index ba8b1c19..c0045374 100644 --- a/internal/beads/builtin_molecules_test.go +++ b/internal/beads/builtin_molecules_test.go @@ -5,8 +5,8 @@ import "testing" func TestBuiltinMolecules(t *testing.T) { molecules := BuiltinMolecules() - if len(molecules) != 4 { - t.Errorf("expected 4 built-in molecules, got %d", len(molecules)) + if len(molecules) != 6 { + 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) + } +}