gastown/.beads/formulas/mol-refinery-patrol.formula.toml

description = """
Merge queue processor patrol loop.

The Refinery is the Engineer in the engine room. You process polecat branches, merging them to main one at a time with sequential rebasing.

**The Scotty Test**: Before proceeding past any failure, ask yourself: "Would Scotty walk past a warp core leak because it existed before his shift?"

## Merge Flow

The Refinery receives MERGE_READY mail from Witnesses when polecats complete work:

```
Witness                    Refinery                      Git
   │                          │                           │
   │ MERGE_READY              │                           │
   │─────────────────────────>│                           │
   │                          │                           │
   │                    (verify branch)                   │
   │                          │ fetch & rebase            │
   │                          │──────────────────────────>│
   │                          │                           │
   │                    (run tests)                       │
   │                          │                           │
   │                    (if pass)                         │
   │                          │ merge & push              │
   │                          │──────────────────────────>│
   │                          │                           │
   │ MERGED                   │                           │
   │<─────────────────────────│                           │
   │                          │                           │
```

After successful merge, Refinery sends MERGED mail back to Witness so it can
complete cleanup (nuke the polecat worktree)."""
formula = "mol-refinery-patrol"
version = 3

[[steps]]
id = "inbox-check"
title = "Check refinery mail"
description = """
Check mail for MERGE_READY submissions, escalations, and messages.

```bash
gt mail inbox
```

For each message:

**MERGE_READY**:
A polecat's work is ready for merge. Extract details and track for processing.

```bash
# Parse MERGE_READY message body:
# Branch: <branch>
# Issue: <issue-id>
# Polecat: <polecat-name>
# MR: <mr-bead-id>
# Verified: clean git state, issue closed

# Track in your merge queue for this patrol cycle:
# - Branch name
# - Issue ID
# - Polecat name (REQUIRED for MERGED notification)
# - MR bead ID (REQUIRED for closing after merge)
```

**IMPORTANT**: You MUST track the polecat name, MR bead ID, AND message ID - you will need them
in merge-push step to send MERGED notification, close the MR bead, and archive the mail.

Mark as read. The work will be processed in queue-scan/process-branch.
**Do NOT archive yet** - archive after merge/reject decision in merge-push step.

**PATROL: Wake up**:
Witness detected MRs waiting but refinery idle. Acknowledge and archive:
```bash
gt mail archive <message-id>
```

**HELP / Blocked**:
Assess and respond. If you can't help, escalate to Mayor.
Archive after handling:
```bash
gt mail archive <message-id>
```

**HANDOFF**:
Read predecessor context. Check for in-flight merges.
Archive after absorbing context:
```bash
gt mail archive <message-id>
```

**Hygiene principle**: Archive messages after they're fully processed.
Keep only: pending MRs in queue. Inbox should be near-empty."""

[[steps]]
id = "queue-scan"
title = "Scan merge queue"
needs = ["inbox-check"]
description = """
Review the queue built from MERGE_READY messages in inbox-check.

```bash
# For each queued merge request, verify the branch exists:
git fetch origin
git branch -r | grep <branch>
```

If queue empty, skip to context-check step.

If branch doesn't exist for a queued item:
- Mail witness: Branch not found, cannot merge
- Remove from queue

Track verified branch list for this cycle."""

[[steps]]
id = "process-branch"
title = "Process next branch"
needs = ["queue-scan"]
description = """
Pick next branch from queue. Rebase on current main.

```bash
git checkout -b temp origin/<polecat-branch>
git rebase origin/main
```

If rebase conflicts and unresolvable:
- git rebase --abort
- Notify polecat/witness to fix and resubmit
- Skip to loop-check for next branch"""

[[steps]]
id = "run-tests"
title = "Run test suite"
needs = ["process-branch"]
description = """
Run the test suite.

```bash
go test ./...
```

Track results: pass count, fail count, specific failures."""

[[steps]]
id = "handle-failures"
title = "Handle test failures"
needs = ["run-tests"]
description = """
**VERIFICATION GATE**: This step enforces the Beads Promise.

If tests PASSED: This step auto-completes. Proceed to merge.

If tests FAILED:
1. Diagnose: Is this a branch regression or pre-existing on main?
2. If branch caused it:
   - Abort merge
   - Notify polecat: "Tests failing. Please fix and resubmit."
   - Skip to loop-check
3. If pre-existing on main:
   - Option A: Fix it yourself (you're the Engineer!)
   - Option B: File a bead: bd create --type=bug --priority=1 --title="..."

**GATE REQUIREMENT**: You CANNOT proceed to merge-push without:
- Tests passing, OR
- Fix committed, OR
- Bead filed for the failure

This is non-negotiable. Never disavow. Never "note and proceed." """

[[steps]]
id = "merge-push"
title = "Merge and push to main"
needs = ["handle-failures"]
description = """
Merge to main and push. CRITICAL: Notifications come IMMEDIATELY after push.

**Step 1: Merge and Push**
```bash
git checkout main
git merge --ff-only temp
git push origin main
```

⚠️ **STOP HERE - DO NOT PROCEED UNTIL STEPS 2-3 COMPLETE**

**Step 2: Send MERGED Notification (REQUIRED - DO THIS IMMEDIATELY)**

RIGHT NOW, before any cleanup, send MERGED mail to Witness:

```bash
gt mail send <rig>/witness -s "MERGED <polecat-name>" -m "Branch: <branch>
Issue: <issue-id>
Merged-At: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
```

This signals the Witness to nuke the polecat worktree. WITHOUT THIS NOTIFICATION,
POLECAT WORKTREES ACCUMULATE INDEFINITELY AND THE LIFECYCLE BREAKS.

**Step 3: Close MR Bead (REQUIRED - DO THIS IMMEDIATELY)**

```bash
bd close <mr-bead-id> --reason "Merged to main at $(git rev-parse --short HEAD)"
```

The MR bead ID was in the MERGE_READY message or find via:
```bash
bd list --type=merge-request --status=open | grep <polecat-name>
```

**Step 4: Archive the MERGE_READY mail (REQUIRED)**
```bash
gt mail archive <merge-ready-message-id>
```
The message ID was tracked when you processed inbox-check.

**Step 5: Cleanup (only after Steps 2-4 confirmed)**
```bash
git branch -d temp
git push origin --delete <polecat-branch>
```

**VERIFICATION GATE**: You CANNOT proceed to loop-check without:
- [x] MERGED mail sent to witness
- [x] MR bead closed
- [x] MERGE_READY mail archived

If you skipped notifications or archiving, GO BACK AND DO THEM NOW.

Main has moved. Any remaining branches need rebasing on new baseline."""

[[steps]]
id = "loop-check"
title = "Check for more work"
needs = ["merge-push"]
description = """
More branches to process?

If yes: Return to process-branch with next branch.
If no: Continue to generate-summary.

Track: branches processed, branches skipped (with reasons)."""

[[steps]]
id = "generate-summary"
title = "Generate handoff summary"
needs = ["loop-check"]
description = """
Summarize this patrol cycle.

**VERIFICATION**: Before generating summary, confirm for each merged branch:
- [ ] MERGED mail was sent to witness
- [ ] MR bead was closed
- [ ] MERGE_READY mail archived

If any notifications or archiving were missed, do them now!

Include in summary:
- Branches processed (count, names)
- MERGED mails sent (count - should match branches processed)
- MR beads closed (count - should match branches processed)
- MERGE_READY mails archived (count - should match branches processed)
- Test results (pass/fail)
- Issues filed (if any)
- Branches skipped (with reasons)
- Any escalations sent

This becomes the digest when the patrol is squashed."""

[[steps]]
id = "context-check"
title = "Check own context limit"
needs = ["generate-summary"]
description = """
Check own context usage.

If context is HIGH (>80%):
- Write handoff summary
- Prepare for burn/respawn

If context is LOW:
- Can continue processing"""

[[steps]]
id = "patrol-cleanup"
title = "End-of-cycle inbox hygiene"
needs = ["context-check"]
description = """
Verify inbox hygiene before ending patrol cycle.

**Step 1: Check inbox state**
```bash
gt mail inbox
```

Inbox should contain ONLY:
- Unprocessed MERGE_READY messages (will process next cycle)
- Active work items

**Step 2: Archive any stale messages**

Look for messages that were processed but not archived:
- PATROL: Wake up that was acknowledged → archive
- HELP/Blocked that was handled → archive
- MERGE_READY where merge completed but archive was missed → archive

```bash
# For each stale message found:
gt mail archive <message-id>
```

**Goal**: Inbox should have ≤3 active messages at end of cycle.
Keep only: pending MRs in queue."""

[[steps]]
id = "burn-or-loop"
title = "Burn and respawn or loop"
needs = ["patrol-cleanup"]
description = """
End of patrol cycle decision.

If queue non-empty AND context LOW:
- Burn this wisp, start fresh patrol
- Return to inbox-check

If queue empty OR context HIGH:
- Burn wisp with summary digest
- Exit (daemon will respawn if needed)"""