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

description = """
Full polecat work lifecycle from assignment through merge-ready handoff.

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 | 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 = 2

[[steps]]
id = "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]]
id = "branch-setup"
title = "Set up working branch"
needs = ["load-context"]
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 = """
Do the actual implementation work.

**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"]
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]]
id = "run-tests"
title = "Run tests and verify coverage"
needs = ["self-review"]
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 issue ID assigned to this polecat"
required = true