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

description = """
Full polecat work lifecycle from assignment through completion.

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 (Self-Cleaning Model)

You are a self-cleaning worker. You:
1. Receive work via your hook (pinned molecule + issue)
2. Work through molecule steps using `bd ready` / `bd close <step>`
3. Complete and self-clean via `gt done` (submit + nuke yourself)
4. You are GONE - Refinery merges from MQ

**Self-cleaning:** When you run `gt done`, you push your work, submit to MQ,
nuke your sandbox, and exit. There is no idle state. Done means gone.

**Important:** This formula defines the template. Your molecule already has step
beads created from it. Use `bd ready` to find them - do NOT read this file directly.

**You do NOT:**
- Push directly to main (Refinery merges from MQ)
- Close your own issue (Refinery closes after merge)
- Wait for merge (you're gone after `gt done`)
- Handle rebase conflicts (Refinery spawns fresh polecats for that)

## 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 = 4

[[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 hook               # 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 = "preflight-tests"
title = "Verify tests pass on main"
needs = ["branch-setup"]
description = """
Check if the codebase is healthy BEFORE starting your work.

**The Scotty Principle:** Don't walk past a broken warp core. But also don't
let someone else's mess consume your entire mission.

**1. Check tests on main:**
```bash
git stash                   # Save your branch state
git checkout origin/main
go test ./...               # Or appropriate test command
```

**2. If tests PASS:**
```bash
git checkout -              # Back to your branch
git stash pop               # Restore state
```
Continue to implement step.

**3. If tests FAIL on main:**

Make a judgment call:

| Situation | Action |
|-----------|--------|
| Quick fix (<15 min) | Fix it, commit to main, then continue |
| Medium fix (15-60 min) | Fix if it blocks your work, else file bead |
| Big fix (>1 hour) | File bead, notify Witness, proceed with your work |

**Quick fix path:**
```bash
# Fix the issue
git add <files>
git commit -m "fix: <description> (pre-existing failure)"
git push origin main
git checkout -
git stash pop
git rebase origin/main      # Get your fix
```

**File and proceed path:**
```bash
bd create --title "Pre-existing test failure: <description>" \
  --type bug --priority 1

gt mail send <rig>/witness -s "NOTICE: Main has failing tests" \
  -m "Found pre-existing test failures on main.
Filed: <bead-id>
Proceeding with my assigned work ({{issue}})."

git checkout -
git stash pop
```

**Context consideration:**
If fixing pre-existing failures consumed significant context:
```bash
gt handoff -s "Fixed pre-existing failures, ready for assigned work" \
  -m "Issue: {{issue}}
Fixed: <what you fixed>
Ready to start: implement step"
```
Fresh session continues from implement.

**Exit criteria:** Tests pass on main (or issue filed), ready to implement."""

[[steps]]
id = "implement"
title = "Implement the solution"
needs = ["preflight-tests"]
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 = "prepare-for-review"
title = "Prepare work for review"
needs = ["cleanup-workspace"]
description = """
Verify work is complete and ready for merge queue.

**Note:** Do NOT close the issue. The Refinery will close it after successful merge.
This enables conflict-resolution retries without reopening closed issues.

**1. Verify the issue shows your work:**
```bash
bd show {{issue}}
# Status should still be 'in_progress' (you're working on it)
```

**2. Add completion notes:**
```bash
bd update {{issue}} --notes "Implemented: <brief summary of what was done>"
```

**3. Sync beads:**
```bash
bd sync
```

**Exit criteria:** Issue updated with completion notes, beads synced."""

[[steps]]
id = "submit-and-exit"
title = "Submit work and self-clean"
needs = ["prepare-for-review"]
description = """
Submit your work and clean up. You cease to exist after this step.

**Self-Cleaning Model:**
Once you run `gt done`, you're gone. The command:
1. Pushes your branch to origin
2. Creates an MR bead in the merge queue
3. Nukes your sandbox (worktree removal)
4. Exits your session immediately

**Run gt done:**
```bash
gt done
```

You should see output like:
```
✓ Work submitted to merge queue
  MR ID: gt-xxxxx
  Source: polecat/<name>
  Target: main
  Issue: {{issue}}
✓ Sandbox nuked
✓ Session exiting
```

**What happens next (not your concern):**
- Refinery processes your MR from the queue
- Refinery rebases and merges to main
- Refinery closes the issue
- If conflicts: Refinery spawns a FRESH polecat to re-implement

You are NOT involved in any of that. You're gone. Done means gone.

**Exit criteria:** Work submitted, sandbox nuked, session exited."""

[vars]
[vars.issue]
description = "The issue ID assigned to this polecat"
required = true