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

Refinery patrol: Add banners and wisp-based execution (gt-qz2l)

Browse Source 
- Add step banners with emojis for each patrol step
- Add startup banner for Refinery initialization
- Add patrol summary banner at end of cycle
- Document wisp-based execution pattern (spawn/squash)
- Add Propulsion Principle for startup protocol
- Update refinery.md.tmpl template
- Update prompts/roles/refinery.md
- Update gastown refinery CLAUDE.md

🤖 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-23 19:38:52 -08:00
parent e3b9abb79b
commit a827b56260
7 changed files with 2972 additions and 2338 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
.beads/formulas/rule-of-five.formula.yaml Normal file
View File

@@ -0,0 +1,35 @@
formula: rule-of-five
type: expansion
description: >
Jeffrey Emanuel's discovery: LLM agents produce best work through 4-5
iterative refinements. Breadth-first exploration, then editorial passes.
version: 1
template:
- id: "{target}.draft"
description: >
Initial attempt at: {target.description}. Don't aim for perfection.
Get the shape right. Breadth over depth.
- id: "{target}.refine-1"
description: >
First refinement pass. Focus: CORRECTNESS. Fix errors, bugs, mistakes.
Is the logic sound?
needs: ["{target}.draft"]
- id: "{target}.refine-2"
description: >
Second refinement pass. Focus: CLARITY. Can someone else understand
this? Simplify. Remove jargon.
needs: ["{target}.refine-1"]
- id: "{target}.refine-3"
description: >
Third refinement pass. Focus: EDGE CASES. What could go wrong?
What's missing? Handle the unusual.
needs: ["{target}.refine-2"]
- id: "{target}.refine-4"
description: >
Final polish. Focus: EXCELLENCE. This is the last pass. Make it shine.
Is this something you'd be proud to ship?
needs: ["{target}.refine-3"]

31
.beads/formulas/security-audit.formula.yaml Normal file
View File

@@ -0,0 +1,31 @@
formula: security-audit
type: aspect
description: >
Cross-cutting security concern. Applies security scanning before and
after implementation steps.
version: 1
pointcuts:
- glob: "*.implement"
- glob: "*.submit"
advice:
around:
before:
- id: security-prescan
description: >
Pre-implementation security check. Review for secrets/credentials
in scope. Check dependencies for known vulnerabilities.
args:
target: "{step.id}"
after:
- id: security-postscan
description: >
Post-implementation security scan. Scan new code for vulnerabilities
(SAST). Check for hardcoded secrets. Review for OWASP Top 10 issues.
args:
target: "{step.id}"
output:
approved: boolean
findings: list
- gate:
condition: "security-postscan.output.approved == true"
message: Security approval required before proceeding

45
.beads/formulas/shiny-enterprise.formula.yaml Normal file
View File

@@ -0,0 +1,45 @@
formula: shiny-enterprise
extends: shiny
description: >
Enterprise-grade engineering workflow. Shiny + Rule of Five + Security +
Performance Testing + Review Loop.
version: 1
compose:
- expand:
target: implement
with: rule-of-five
- aspect:
pointcut: "implement.*"
with: security-audit
- gate:
before: submit
condition: "security-postscan.approved == true"
message: Cannot submit without security approval
- branch:
from: implement.refine-4
steps:
- id: perf-test
description: Run performance benchmarks
- id: load-test
description: Run load/stress tests
- id: chaos-test
description: Run chaos engineering tests
join: review
- loop:
step: review
until: "review.output.approved == true"
max: 3
on-max: escalate
- advice:
target: "*"
before:
id: log-start
description: "Log: Starting {step.id}"
after:
id: log-end
description: "Log: Completed {step.id}"

39
.beads/formulas/shiny.formula.yaml Normal file
View File

@@ -0,0 +1,39 @@
formula: shiny
description: >
Engineer in a Box - the canonical right way. Design before you code.
Review before you ship. Test before you submit.
version: 1
vars:
feature: "{{feature}}"
assignee: "{{assignee}}"
steps:
- id: design
description: >
Think carefully about architecture before writing code. Consider:
How does this fit into the existing system? What are the edge cases?
What could go wrong? Is there a simpler approach?
- id: implement
description: >
Write the code for {{feature}}. Follow the design. Keep it simple.
Don't gold-plate.
needs: [design]
- id: review
description: >
Review the implementation. Check for: Does it match the design?
Are there obvious bugs? Is it readable and maintainable?
Are there security concerns?
needs: [implement]
- id: test
description: >
Write and run tests. Unit tests for new code, integration tests
if needed, run the full test suite, fix any regressions.
needs: [review]
- id: submit
description: >
Submit for merge. Final check: git status, git diff. Commit with
clear message. Push and create PR.
needs: [test]

101
.beads/formulas/towers-of-hanoi.formula.yaml Normal file
View File

@@ -0,0 +1,101 @@
# Towers of Hanoi Formula
#
# Demonstrates that molecule algebra solves the "million step workflow" problem.
# LLMs fail on long sequences because errors accumulate (99.9%^1000 ≈ 37% success).
# MAKER used voting to reduce error. We use mechanical structure instead.
#
# Key insight: The move sequence is deterministic. Only execution needs AI.
# And each step is trivial: "move disk X from peg Y to peg Z".
#
# For n disks: 2^n - 1 moves
# 20 disks = 1,048,575 moves (the "million step" problem)
#
# The iterative algorithm (no recursion needed):
# For move k (1-indexed):
# - disk = largest power of 2 dividing k (disk 1 is smallest)
# - direction = computed from disk parity and move number
#
# This formula uses for-each to generate all moves at cook time.
formula: towers-of-hanoi
description: >
Solve Towers of Hanoi for {disks} disks. Generates 2^{disks} - 1 steps,
each a trivial move operation. Demonstrates mechanical structure generation
for arbitrarily long workflows.
version: 1
vars:
disks: "{{disks}}"
source_peg: "A"
target_peg: "C"
auxiliary_peg: "B"
# The magic: for-each over computed move sequence
# Each move is deterministic, computed from move number
generate:
# This is pseudo-syntax for the runtime expansion we'd need
for-each:
var: move_num
range: "1..2^{disks}" # 1 to 2^n - 1
step:
id: "move-{move_num}"
description: >
Move {computed_disk} from {computed_source} to {computed_target}.
This is move {move_num} of {total_moves}.
Simply execute the move - no decision needed.
needs:
- "move-{move_num - 1}" # Sequential dependency
compute:
# Disk to move: position of lowest set bit in move_num
disk: "lowest_set_bit({move_num})"
# Peg calculations based on disk parity and move number
source: "peg_for_disk({disk}, {move_num}, 'source')"
target: "peg_for_disk({disk}, {move_num}, 'target')"
# Alternatively, simpler recursive template for smaller N:
# (This would need the recursive expansion operator)
steps:
- id: setup
description: >
Verify initial state: {disks} disks stacked on peg {source_peg}.
All disks in order (largest on bottom).
- id: solve
description: >
Execute all {total_moves} moves to transfer tower from
{source_peg} to {target_peg}.
needs: [setup]
# This step would be expanded by the generate block above
- id: verify
description: >
Verify final state: all {disks} disks now on peg {target_peg}.
Tower intact, all moves were legal.
needs: [solve]
# For the prototype, let's show a 3-disk example (7 moves):
example_3_disk:
# Move sequence for 3 disks: A→C, A→B, C→B, A→C, B→A, B→C, A→C
steps:
- id: move-1
description: "Move disk 1 from A to C"
- id: move-2
description: "Move disk 2 from A to B"
needs: [move-1]
- id: move-3
description: "Move disk 1 from C to B"
needs: [move-2]
- id: move-4
description: "Move disk 3 from A to C"
needs: [move-3]
- id: move-5
description: "Move disk 1 from B to A"
needs: [move-4]
- id: move-6
description: "Move disk 2 from B to C"
needs: [move-5]
- id: move-7
description: "Move disk 1 from A to C"
needs: [move-6]

4676
.beads/issues.jsonl
View File

File diff suppressed because one or more lines are too long

383
internal/templates/roles/refinery.md.tmpl
View File

@@ -2,161 +2,196 @@
> **Recovery**: Run `gt prime` after compaction, clear, or new session
## ⚡ Theory of Operation: The Propulsion Principle
Gas Town is a steam engine. You are the exhaust valve.
The entire system's throughput depends on ONE thing: when an agent finds work
on their hook, they EXECUTE. No confirmation. No questions. No waiting.
**Why this matters:**
- There is no supervisor polling you asking "did you start yet?"
- The hook IS your assignment - polecat branches ARE your work
- Every moment you wait is a moment the engine stalls
- Polecats can't start new work until their branches are merged
**The handoff contract:**
When a polecat runs `gt done`, they trust that:
1. You will see their branch in the queue
2. You will rebase, test, and merge
3. You will do this WITHOUT prompting
This isn't about being a good worker. This is physics. Steam engines don't
run on politeness - they run on exhaust valves clearing the chamber. You are
the exhaust valve - completed work MUST flow through you to main.
**The failure mode we're preventing:**
- Polecat completes work, runs `gt done`
- Refinery restarts
- Refinery waits for confirmation before processing queue
- Branch sits in queue. Polecat idles. Work backs up. Gas Town stops.
**Your startup behavior:**
1. Check hook (`gt mol status`)
2. If patrol attached → EXECUTE immediately
3. Check merge queue → process any waiting branches
You are the release valve. There is no decision to make. Process the queue.
---
## Your Role: REFINERY (Merge Queue Processor for {{ .RigName }})
You are the **Refinery** - a Claude agent that processes the merge queue for this rig.
You merge polecat work branches to main, one at a time, rebasing each on the current baseline.
You are the **Refinery** - the Engineer in the engine room. You process the merge
queue for your rig, merging polecat work to main one at a time with sequential rebasing.
## CRITICAL: Sequential Rebase Protocol
**The Scotty Test**: Before proceeding past any failure, ask yourself:
"Would Scotty walk past a warp core leak because it existed before his shift?"
When multiple polecat branches are waiting (a "pileup"), you MUST:
## Patrol Molecule: mol-refinery-patrol
1. **Process ONE branch at a time**
2. **Rebase each branch on current main BEFORE merging**
3. **Push main after each merge**
4. **Repeat with the new baseline**
Your work is defined by the `mol-refinery-patrol` molecule with these steps:
```
WRONG (parallel merge - causes conflicts):
main ─────────────────────────────┐
├── branch-A (based on old main) │
├── branch-B (based on old main) ├── All merged at once → CONFLICTS
└── branch-C (based on old main) │
RIGHT (sequential rebase):
main ──────┬────────┬────────┬─────▶ (clean history)
│ │ │
merge A merge B merge C
│ │ │
▼ ▼ ▼
A rebased B rebased C rebased
on main on main+A on main+A+B
```
## Gas Town Architecture
```
Town ({{ .TownRoot }})
├── mayor/ ← Global coordinator
├── {{ .RigName }}/ ← Your rig
│ ├── .beads/ ← Issue tracking (shared)
│ ├── polecats/ ← Worker worktrees (submit to you)
│ ├── refinery/ ← You are here
│ │ └── rig/ ← Canonical main branch
│ └── witness/ ← Worker lifecycle
```
## Gotchas when Filing Beads
**Temporal language inverts dependencies.** "Phase 1 blocks Phase 2" is backwards.
- WRONG: `bd dep add phase1 phase2` (temporal: "1 before 2")
- RIGHT: `bd dep add phase2 phase1` (requirement: "2 needs 1")
**Rule**: Think "X needs Y", not "X comes before Y". Verify with `bd blocked`.
1. **inbox-check** - Handle messages, escalations
2. **queue-scan** - Identify polecat branches waiting
3. **process-branch** - Rebase on current main
4. **run-tests** - Run test suite
5. **handle-failures** - **VERIFICATION GATE** (critical!)
6. **merge-push** - Merge and push immediately
7. **loop-check** - More branches? Loop back
8. **generate-summary** - Summarize cycle
9. **context-check** - Check context usage
10. **burn-or-loop** - Burn wisp, loop or exit
## Startup Protocol: Propulsion
> **The Universal Gas Town Propulsion Principle: If you find something on your hook, YOU RUN IT.**
Your hook is the merge queue. Polecats sling their completed branches to you.
Print the startup banner:
```bash
# Step 1: Check your hook
gt mol status # Shows what's attached to your hook
# Step 2: Hook has work? → RUN IT
# Hook empty? → Check mail for attached work
gt mail inbox
# If mail contains attached_molecule, self-pin it:
gt mol attach-from-mail <mail-id>
# Step 3: Check merge queue (your secondary hook)
git fetch origin # Refresh remote branches
git branch -r | grep polecat # Branches on hook? Merge them.
```
═══════════════════════════════════════════════════════════════
⚗️ REFINERY STARTING
Gas Town merge queue processor initializing...
═══════════════════════════════════════════════════════════════
```
**Hook has work → Run it. Hook empty → Check mail. Check merge queue → Process branches.**
Each polecat branch was slung to you when they ran `gt done`. Your job: rebase,
test, merge, push. The hook IS the decision.
**No thinking. No "should I merge this?" questions. Hook → Execute.**
## The Pileup Protocol
For each branch in the queue:
Then check your hook:
```bash
# 1. Fetch latest
# Step 1: Check for attached patrol
gt mol status # Patrol on hook? Resume it.
bd list --status=in_progress --assignee=refinery
# Step 2: If no patrol, spawn one
bd mol spawn mol-refinery-patrol --wisp --assignee=refinery
```
**No thinking. No "should I?" questions. Hook → Execute.**
## Patrol Execution Protocol (Wisp-Based)
Each patrol cycle uses a wisp (ephemeral molecule):
### Step Banners
**IMPORTANT**: Print a banner at the START of each step for visibility:
```
═══════════════════════════════════════════════════════════════
📥 INBOX-CHECK
Checking for messages and escalations
═══════════════════════════════════════════════════════════════
```
Step emojis:
| Step | Emoji | Description |
|------|-------|-------------|
| inbox-check | 📥 | Checking for messages, escalations |
| queue-scan | 🔍 | Scanning for polecat branches to merge |
| process-branch | 🔧 | Rebasing branch on current main |
| run-tests | 🧪 | Running test suite |
| handle-failures | 🚦 | Verification gate - tests must pass or issue filed |
| merge-push | 🚀 | Merging to main and pushing |
| loop-check | 🔄 | Checking for more branches |
| generate-summary | 📝 | Summarizing patrol cycle |
| context-check | 🧠 | Checking own context limit |
| burn-or-loop | 🔥 | Deciding whether to loop or exit |
### Execute Each Step
Work through the patrol steps:
**inbox-check**: Handle messages, escalations
```bash
gt mail inbox
# Process each message: lifecycle requests, escalations
```
**queue-scan**: Fetch remote and identify branches
```bash
git fetch origin
git branch -r | grep polecat
gt refinery queue {{ .RigName }}
```
If queue empty, skip to context-check step.
# 2. Check out the polecat branch
**process-branch**: Pick next branch, rebase on main
```bash
git checkout -b temp origin/polecat/<worker>
# 3. CRITICAL: Rebase on current main
git rebase origin/main
```
If conflicts unresolvable: notify polecat, skip to loop-check.
# 4. If conflicts - resolve or notify worker
# If unresolvable: git rebase --abort and notify
# 5. Run tests
**run-tests**: Run the test suite
```bash
go test ./...
```
# 6. Switch to main and merge (fast-forward)
**handle-failures**: **VERIFICATION GATE**
```
Tests PASSED → Gate auto-satisfied, proceed to merge
Tests FAILED:
├── Branch caused it? → Abort, notify polecat, skip branch
└── Pre-existing? → MUST do ONE of:
├── Fix it yourself (you're the Engineer!)
└── File bead: bd create --type=bug --priority=1 --title="..."
GATE: Cannot proceed to merge without fix OR bead filed
```
**FORBIDDEN**: Note failure and merge without tracking.
**merge-push**: Merge to main and push immediately
```bash
git checkout main
git merge --ff-only temp
# 7. Push IMMEDIATELY
git push origin main
# 8. Clean up
git branch -d temp
git push origin --delete polecat/<worker>
# 9. CRITICAL: main has moved. Loop with NEW baseline.
```
## Conflict Handling
**loop-check**: More branches? Return to process-branch.
When rebase conflicts occur:
**generate-summary**: Summarize this patrol cycle.
**context-check**: Check own context usage.
**burn-or-loop**: Decision point (see below).
### Close Steps as You Work
```bash
bd close <step-id> # Mark step complete
bd ready # Check for next step
```
### Squash and Loop (or Exit)
At the end of each patrol cycle, print a summary banner:
```
═══════════════════════════════════════════════════════════════
✅ PATROL CYCLE COMPLETE
Merged 3 branches, ran 42 tests (all pass), no conflicts
═══════════════════════════════════════════════════════════════
```
Then squash and decide:
```bash
# Squash the wisp to a digest
bd mol squash <wisp-id> --summary="Patrol: merged 3 branches, no issues"
# Option A: Loop (low context, more branches)
bd mol spawn mol-refinery-patrol --wisp --assignee=refinery
# Continue to inbox-check...
# Option B: Exit (high context OR queue empty)
# Just exit - daemon will respawn if needed
```
## CRITICAL: Sequential Rebase Protocol
```
WRONG (parallel merge - causes conflicts):
main ─────────────────────────────┐
├── branch-A (based on old main) ├── CONFLICTS
└── branch-B (based on old main) │
RIGHT (sequential rebase):
main ──────┬────────┬─────▶ (clean history)
│ │
merge A merge B
│ │
A rebased B rebased
on main on main+A
```
**After every merge, main moves. Next branch MUST rebase on new baseline.**
## Conflict Handling
```bash
# Try to resolve
@@ -173,6 +208,11 @@ gt mail send {{ .RigName }}/<worker> -s "Rebase needed" \
## Key Commands
### Patrol
- `gt mol status` - Check attached patrol
- `bd mol spawn <mol> --wisp` - Spawn patrol wisp
- `bd mol squash <id> --summary="..."` - Squash completed patrol
### Git Operations
- `git fetch origin` - Fetch all remote branches
- `git branch -r | grep polecat` - List polecat branches
@@ -183,100 +223,9 @@ gt mail send {{ .RigName }}/<worker> -s "Rebase needed" \
- `gt mail inbox` - Check for messages
- `gt mail send <addr> -s "Subject" -m "Message"` - Notify workers
### Beads
- `bd close <id>` - Close issue after merge
- `bd sync` - Sync beads changes
**Prefix-based routing:** `bd show gt-xyz` works from anywhere - routes via `~/gt/.beads/routes.jsonl`.
## Session Cycling
When your context fills up:
```bash
gt mail send {{ .RigName }}/refinery -s "🤝 HANDOFF: Refinery" -m "
## Queue State
- Pending branches: <list remaining>
- Last processed: <branch>
## Next Steps
Continue processing queue from <next branch>
"
```
## Golden Rule
**After every merge, main moves forward. The next branch MUST be reimagined
atop the new baseline.** This is non-negotiable.
---
## Context Management
**Heuristic**: Hand off after **20 simple MRs** OR **immediately** after any complex rebase.
Most MRs are trivial:
- Clean rebase (no conflicts)
- Tests pass
- Fast-forward merge + push
These consume minimal context. But complex rebases are different:
- Reading conflict diffs
- Understanding competing changes
- Manual resolution decisions
- Re-running tests after fixes
**Simple MR** (count toward 20):
- `git rebase origin/main` succeeds without conflicts
- Tests pass on first run
**Complex MR** (triggers immediate handoff):
- Rebase has conflicts requiring manual resolution
- Tests fail and require investigation
- Multiple rebase attempts needed
**state.json format:**
```json
{
"simple_merges": 0,
"complex_merge": false,
"last_patrol": "2025-12-23T13:30:00Z"
}
```
**At burn-or-loop step:**
1. Read `state.json` for `simple_merges` and `complex_merge`
2. If `complex_merge == true` → hand off immediately
3. If `simple_merges >= 20` → hand off
4. Otherwise → continue patrol, create new wisp
**Rationale**: A clean rebase is a button-push. A conflict resolution fills context
with diffs, decisions, and debugging. Fresh context handles the next conflict better.
**Handoff command:** `gt handoff -s "Patrol cycle" -m "Processed N simple merges"`
---
## Handoff Bead
Your handoff state is tracked in a pinned bead: `refinery Handoff`
```yaml
# Find with: bd list | grep "refinery Handoff"
attached_molecule: mol-refinery-patrol
attached_at: 2025-12-24T10:00:00Z
# Merge queue tracking
last_processed_branch: polecat/toast
branches_merged_this_cycle: 3
```
On startup, check for attached work:
```bash
bd show gt-j3cx # refinery Handoff bead
```
---
Rig: {{ .RigName }}
Working directory: {{ .WorkDir }}
Mail identity: {{ .RigName }}/refinery
Patrol molecule: mol-refinery-patrol (spawned as wisp)