0f88c793f8
Documents the Claude-driven execution model: - Molecules are playbooks, not auto-executing code - Mail-based coordination between agents - Nudge escalation matrix for stuck polecats - State persistence in handoff bead See gt-poxd for handoff bead implementation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
148 lines
5.7 KiB
Markdown
148 lines
5.7 KiB
Markdown
# Witness Patrol: Theory of Operation
|
|
|
|
## Overview
|
|
|
|
The Witness is the per-rig worker monitor. It watches polecats, nudges them toward
|
|
completion, verifies clean state before cleanup, and escalates stuck workers.
|
|
|
|
**Key principle: Claude-driven execution.** The mol-witness-patrol molecule is a
|
|
playbook that Claude reads and executes. There is no Go "runtime" that auto-executes
|
|
steps. Claude provides the intelligence; gt/bd commands provide the primitives.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ THE AGENT (Claude) │
|
|
│ │
|
|
│ Reads molecule steps → Executes commands → Closes atoms │
|
|
│ Uses TodoWrite for complex atoms (optional) │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ PRIMITIVES (gt, bd CLI) │
|
|
│ │
|
|
│ gt mail, gt nudge, gt session, bd close, bd show, etc. │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ COORDINATION (Mail) │
|
|
│ │
|
|
│ Polecats → POLECAT_DONE → Witness inbox │
|
|
│ Witness → "You're stuck" → Polecat (via gt nudge) │
|
|
│ Witness → Escalation → Mayor inbox │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## The Patrol Cycle
|
|
|
|
Each patrol cycle follows the mol-witness-patrol molecule:
|
|
|
|
### 1. inbox-check
|
|
Check mail for lifecycle events:
|
|
- **POLECAT_DONE**: Polecat finished work, ready for cleanup
|
|
- **Help requests**: Polecat asking for assistance
|
|
- **Escalations**: Issues requiring attention
|
|
|
|
```bash
|
|
gt mail inbox
|
|
gt mail read <id>
|
|
```
|
|
|
|
### 2. survey-workers
|
|
For each polecat in the rig:
|
|
|
|
```bash
|
|
gt polecat list <rig>
|
|
```
|
|
|
|
For each polecat:
|
|
1. **Capture**: `tmux capture-pane -t gt-<rig>-<name> -p | tail -50`
|
|
2. **Assess**: Claude reads output, determines state (working/idle/error/done)
|
|
3. **Load history**: Read nudge count from handoff bead
|
|
4. **Decide**: Apply escalation matrix (see below)
|
|
5. **Execute**: Take action (none, nudge, escalate, cleanup)
|
|
|
|
### 3. save-state
|
|
Persist state to handoff bead for next cycle:
|
|
- Nudge counts per polecat
|
|
- Last nudge timestamps
|
|
- Pending actions
|
|
|
|
### 4. burn-or-loop
|
|
- If context low: sleep briefly, loop back to inbox-check
|
|
- If context high: exit (daemon respawns fresh Witness)
|
|
|
|
## Nudge Escalation Matrix
|
|
|
|
The Witness applies escalating pressure to idle polecats:
|
|
|
|
| Idle Time | Nudge Count | Action |
|
|
|-----------|-------------|--------|
|
|
| <10min | any | none |
|
|
| 10-15min | 0 | Gentle: "How's progress?" |
|
|
| 15-20min | 1 | Direct: "Please wrap up. What's blocking?" |
|
|
| 20+min | 2 | Final: "Will escalate in 5min if no response." |
|
|
| any | 3 | Escalate to Mayor |
|
|
|
|
**Key insight**: Only Claude can assess whether a polecat is truly stuck.
|
|
Looking at tmux output requires understanding context:
|
|
- "I'm stuck on this error" → needs help
|
|
- "Running tests..." → actively working
|
|
- Sitting at prompt with no activity → maybe stuck
|
|
|
|
## State Persistence
|
|
|
|
The Witness handoff bead tracks:
|
|
|
|
```yaml
|
|
# In handoff bead description
|
|
nudges:
|
|
toast:
|
|
count: 2
|
|
last: "2025-12-24T10:30:00Z"
|
|
ace:
|
|
count: 0
|
|
last: null
|
|
pending_cleanup:
|
|
- nux # received POLECAT_DONE, queued for verification
|
|
```
|
|
|
|
This survives across patrol cycles and context burns.
|
|
|
|
## Polecat Cleanup Flow
|
|
|
|
When a polecat signals completion:
|
|
|
|
1. Polecat runs `gt done` or sends POLECAT_DONE mail
|
|
2. Witness receives mail in inbox-check
|
|
3. Witness runs pre-kill verification:
|
|
```bash
|
|
cd polecats/<name>
|
|
git status # Must be clean
|
|
git log origin/main.. # Check for unpushed
|
|
bd show <issue> # Verify closed
|
|
```
|
|
4. If clean: kill session, remove worktree, delete branch
|
|
5. If dirty: send nudge asking polecat to fix state
|
|
|
|
## What We DON'T Need
|
|
|
|
- **Go patrol runtime**: Claude executes the playbook
|
|
- **Polling for WaitsFor**: Mail tells us when things are ready
|
|
- **Automated health checks**: Claude reads tmux, assesses
|
|
- **Go nudge logic**: Claude applies the matrix
|
|
|
|
## What We DO Need
|
|
|
|
- **mol-witness-patrol**: The playbook (exists)
|
|
- **Handoff bead**: State persistence (gt-poxd)
|
|
- **CLI primitives**: gt mail, gt nudge, gt session (exist)
|
|
- **Molecule tracking**: bd close for step completion (exists)
|
|
|
|
## Related Issues
|
|
|
|
- gt-poxd: Create handoff beads for Witness and Refinery roles
|
|
- gt-y481: Patrol parity - Witness and Refinery match Deacon sophistication
|
|
- gt-tnow: Implement Christmas Ornament pattern for mol-witness-patrol
|