johno/gastown
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Steve Yegge
2025-12-28 11:13:00 -08:00
parent 1366a032de
commit c564bfd736
3 changed files with 681 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
.beads/formulas/mol-polecat-lease.formula.toml
View File

@@ -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"
[[steps]]
title = "Verify polecat boots successfully"
description = """
Actively working. Monitor for stuck.
Polecat has been spawned. Verify it initializes and starts working.
The polecat is processing its assigned issue ({{issue}}).
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:
**Check if alive:**
```bash
gt session kill {{polecat}}
gt worktree prune {{polecat}}
tmux capture-pane -t gt-{{rig}}-{{polecat}} -p | tail -20
```
Update beads state and close the lease."""
id = "done"
Look for:
- 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

382
.beads/formulas/mol-polecat-work.formula.toml
View File

@@ -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 |
|----------|----------|-------------|
| issue | Yes | The source issue ID being worked on |"""
| Variable | Source | Description |
|----------|--------|-------------|
| 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 = """
Implement the solution for {{issue}}. 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."""
id = "implement"
id = "branch-setup"
title = "Set up working branch"
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:
- Bugs and edge cases
- Style issues
- Missing error handling
- Security concerns
Do the actual implementation work.
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 = """
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."""
id = "request-shutdown"
id = "run-tests"
title = "Run tests and verify coverage"
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

161
templates/polecat-CLAUDE.md Normal file
View File

@@ -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