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

docs: add plugin and escalation system designs

Browse Source 
Plugin System (gt-n08ix):
- Deacon-dispatched periodic automation
- Dog execution model (non-blocking)
- Wisps for state tracking (no state.json)
- Gate types: cooldown, cron, condition, event
- First plugin: rebuild-gt for stale binary detection

Escalation System (gt-i9r20):
- Unified gt escalate command with severity routing
- Config-driven: settings/escalation.json
- Escalation beads for tracking
- Stale escalation re-escalation
- Actions: bead, mail, email, sms

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
gastown/crew/george
2026-01-11 21:24:58 -08:00
committed by Steve Yegge
parent a106796a0e
commit f5832188a6
2 changed files with 1061 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

576
docs/design/escalation-system.md Normal file
View File

@@ -0,0 +1,576 @@
# Escalation System Design
> Detailed design for the Gas Town unified escalation system.
> Written 2026-01-11, crew/george session.
> Parent epic: gt-i9r20
## Problem Statement
Current escalation is ad-hoc "mail Mayor". Issues:
- Mayor gets backlogged easily (especially during swarms)
- No severity differentiation
- No alternative channels (email, SMS, Slack)
- No tracking of stale/unacknowledged escalations
- No visibility into escalation history
## Design Goals
1. **Unified API**: Single `gt escalate` command for all escalation needs
2. **Severity-based routing**: Different severities go to different channels
3. **Config-driven**: Town config controls routing, no code changes needed
4. **Audit trail**: All escalations tracked as beads
5. **Stale detection**: Unacknowledged escalations re-escalate automatically
6. **Extensible**: Easy to add new notification channels
---
## Architecture
### Components
```
┌─────────────────────────────────────────────────────────────┐
│ gt escalate command │
│ --severity --subject --body --source │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Escalation Manager │
│ 1. Read config (settings/escalation.json) │
│ 2. Create escalation bead │
│ 3. Execute route actions for severity │
└─────────────────────┬───────────────────────────────────────┘
│
┌───────────┼───────────┬───────────┐
▼ ▼ ▼ ▼
┌───────┐ ┌─────────┐ ┌───────┐ ┌───────┐
│ Bead │ │ Mail │ │ Email │ │ SMS │
│Create │ │ Action │ │Action │ │Action │
└───────┘ └─────────┘ └───────┘ └───────┘
```
### Data Flow
1. Agent calls `gt escalate --severity=high --subject="..." --body="..."`
2. Command loads escalation config from `settings/escalation.json`
3. Creates escalation bead with severity, subject, body, source labels
4. Looks up route for severity level
5. Executes each action in the route (bead already created, then mail, email, etc.)
6. Returns escalation bead ID
### Stale Escalation Flow
1. Deacon patrol (or plugin) runs `gt escalate stale`
2. Queries for escalation beads older than threshold without `acknowledged:true`
3. For each stale escalation:
- Bump severity (low→medium, medium→high, high→critical)
- Re-execute route for new severity
- Add `reescalated:true` label and timestamp
---
## Configuration
### File Location
`~/gt/settings/escalation.json`
This follows the existing pattern where `~/gt/settings/` contains town-level behavioral config.
### Schema
```go
// EscalationConfig represents escalation routing configuration.
type EscalationConfig struct {
Type string `json:"type"` // "escalation"
Version int `json:"version"` // schema version
// Routes maps severity levels to action lists.
// Actions are executed in order.
Routes map[string][]string `json:"routes"`
// Contacts contains contact information for actions.
Contacts EscalationContacts `json:"contacts"`
// StaleThreshold is how long before an unacknowledged escalation
// is considered stale and gets re-escalated. Default: "4h"
StaleThreshold string `json:"stale_threshold,omitempty"`
// MaxReescalations limits how many times an escalation can be
// re-escalated. Default: 2 (low→medium→high, then stops)
MaxReescalations int `json:"max_reescalations,omitempty"`
}
// EscalationContacts contains contact information.
type EscalationContacts struct {
HumanEmail string `json:"human_email,omitempty"`
HumanSMS string `json:"human_sms,omitempty"`
SlackWebhook string `json:"slack_webhook,omitempty"`
}
const CurrentEscalationVersion = 1
```
### Default Configuration
```json
{
"type": "escalation",
"version": 1,
"routes": {
"low": ["bead"],
"medium": ["bead", "mail:mayor"],
"high": ["bead", "mail:mayor", "email:human"],
"critical": ["bead", "mail:mayor", "email:human", "sms:human"]
},
"contacts": {
"human_email": "",
"human_sms": ""
},
"stale_threshold": "4h",
"max_reescalations": 2
}
```
### Action Types
| Action | Format | Behavior |
|--------|--------|----------|
| `bead` | `bead` | Create escalation bead (always first, implicit) |
| `mail:<target>` | `mail:mayor` | Send gt mail to target |
| `email:human` | `email:human` | Send email to `contacts.human_email` |
| `sms:human` | `sms:human` | Send SMS to `contacts.human_sms` |
| `slack` | `slack` | Post to `contacts.slack_webhook` |
| `log` | `log` | Write to escalation log file |
### Severity Levels
| Level | Use Case | Default Route |
|-------|----------|---------------|
| `low` | Informational, non-urgent | bead only |
| `medium` | Needs attention soon | bead + mail mayor |
| `high` | Urgent, needs human | bead + mail + email |
| `critical` | Emergency, immediate | bead + mail + email + SMS |
---
## Escalation Beads
### Bead Format
```yaml
id: gt-esc-abc123
type: escalation
status: open
title: "Plugin FAILED: rebuild-gt"
labels:
- severity:high
- source:plugin:rebuild-gt
- acknowledged:false
- reescalated:false
- reescalation_count:0
description: |
Build failed: make returned exit code 2
## Context
- Source: plugin:rebuild-gt
- Original severity: medium
- Escalated at: 2026-01-11T19:00:00Z
created_at: 2026-01-11T15:00:00Z
```
### Label Schema
| Label | Values | Purpose |
|-------|--------|---------|
| `severity:<level>` | low, medium, high, critical | Current severity |
| `source:<type>:<name>` | plugin:rebuild-gt, patrol:deacon | What triggered it |
| `acknowledged:<bool>` | true, false | Has human acknowledged |
| `reescalated:<bool>` | true, false | Has been re-escalated |
| `reescalation_count:<n>` | 0, 1, 2, ... | Times re-escalated |
| `original_severity:<level>` | low, medium, high | Initial severity |
---
## Commands
### gt escalate
Create a new escalation.
```bash
gt escalate \
--severity=<low|medium|high|critical> \
--subject="Short description" \
--body="Detailed explanation" \
[--source="plugin:rebuild-gt"]
```
**Flags:**
- `--severity` (required): Escalation severity level
- `--subject` (required): Short description (becomes bead title)
- `--body` (required): Detailed explanation (becomes bead description)
- `--source`: Source identifier for tracking (e.g., "plugin:rebuild-gt")
- `--dry-run`: Show what would happen without executing
- `--json`: Output escalation bead ID as JSON
**Exit codes:**
- 0: Success
- 1: Config error or invalid flags
- 2: Action failed (e.g., email send failed)
**Example:**
```bash
gt escalate \
--severity=high \
--subject="Plugin FAILED: rebuild-gt" \
--body="Build failed: make returned exit code 2. Working directory: ~/gt/gastown/crew/george" \
--source="plugin:rebuild-gt"
# Output:
# ✓ Created escalation gt-esc-abc123 (severity: high)
# → Created bead
# → Mailed mayor/
# → Emailed steve@example.com
```
### gt escalate ack
Acknowledge an escalation.
```bash
gt escalate ack <bead-id> [--note="Investigating"]
```
**Behavior:**
- Sets `acknowledged:true` label
- Optionally adds note to bead
- Prevents re-escalation
**Example:**
```bash
gt escalate ack gt-esc-abc123 --note="Looking into it"
# ✓ Acknowledged gt-esc-abc123
```
### gt escalate list
List escalations.
```bash
gt escalate list [--severity=...] [--stale] [--unacked] [--all]
```
**Flags:**
- `--severity`: Filter by severity level
- `--stale`: Show only stale (past threshold, unacked)
- `--unacked`: Show only unacknowledged
- `--all`: Include acknowledged/closed
- `--json`: Output as JSON
**Example:**
```bash
gt escalate list --unacked
# 📢 Unacknowledged Escalations (2)
#
# ● gt-esc-abc123 [HIGH] Plugin FAILED: rebuild-gt
# Source: plugin:rebuild-gt · Age: 2h · Stale in: 2h
# ● gt-esc-def456 [MEDIUM] Witness unresponsive
# Source: patrol:deacon · Age: 30m · Stale in: 3h30m
```
### gt escalate stale
Check for and re-escalate stale escalations.
```bash
gt escalate stale [--dry-run]
```
**Behavior:**
- Queries unacked escalations older than `stale_threshold`
- For each, bumps severity and re-executes route
- Respects `max_reescalations` limit
**Example:**
```bash
gt escalate stale
# 🔄 Re-escalating stale escalations...
#
# gt-esc-abc123: medium → high (age: 5h, reescalation: 1/2)
# → Emailed steve@example.com
#
# ✓ Re-escalated 1 escalation
```
### gt escalate close
Close an escalation (resolved).
```bash
gt escalate close <bead-id> [--reason="Fixed in commit abc123"]
```
**Behavior:**
- Sets status to closed
- Adds resolution note
- Records who closed it
---
## Implementation Details
### File: internal/cmd/escalate.go
```go
package cmd
// escalateCmd is the parent command for escalation management.
var escalateCmd = &cobra.Command{
Use: "escalate",
Short: "Manage escalations",
Long: `Create, acknowledge, and manage escalations with severity-based routing.`,
}
// escalateCreateCmd creates a new escalation.
var escalateCreateCmd = &cobra.Command{
Use: "escalate --severity=<level> --subject=<text> --body=<text>",
Short: "Create a new escalation",
// ... implementation
}
// escalateAckCmd acknowledges an escalation.
var escalateAckCmd = &cobra.Command{
Use: "ack <bead-id>",
Short: "Acknowledge an escalation",
// ... implementation
}
// escalateListCmd lists escalations.
var escalateListCmd = &cobra.Command{
Use: "list",
Short: "List escalations",
// ... implementation
}
// escalateStaleCmd checks for stale escalations.
var escalateStaleCmd = &cobra.Command{
Use: "stale",
Short: "Re-escalate stale escalations",
// ... implementation
}
// escalateCloseCmd closes an escalation.
var escalateCloseCmd = &cobra.Command{
Use: "close <bead-id>",
Short: "Close an escalation",
// ... implementation
}
```
### File: internal/escalation/manager.go
```go
package escalation
// Manager handles escalation creation and routing.
type Manager struct {
config *config.EscalationConfig
beads *beads.Client
mailer *mail.Client
}
// Escalate creates a new escalation and executes the route.
func (m *Manager) Escalate(ctx context.Context, opts EscalateOptions) (*Escalation, error) {
// 1. Validate options
// 2. Create escalation bead
// 3. Look up route for severity
// 4. Execute each action
// 5. Return escalation with results
}
// Acknowledge marks an escalation as acknowledged.
func (m *Manager) Acknowledge(ctx context.Context, beadID string, note string) error {
// 1. Load escalation bead
// 2. Set acknowledged:true label
// 3. Add note if provided
}
// ReescalateStale finds and re-escalates stale escalations.
func (m *Manager) ReescalateStale(ctx context.Context) ([]Reescalation, error) {
// 1. Query unacked escalations older than threshold
// 2. For each, bump severity
// 3. Execute new route
// 4. Update labels
}
```
### File: internal/escalation/actions.go
```go
package escalation
// Action is an escalation route action.
type Action interface {
Execute(ctx context.Context, esc *Escalation) error
String() string
}
// BeadAction creates the escalation bead.
type BeadAction struct{}
// MailAction sends gt mail.
type MailAction struct {
Target string // e.g., "mayor"
}
// EmailAction sends email.
type EmailAction struct {
Recipient string // from config.contacts
}
// SMSAction sends SMS.
type SMSAction struct {
Recipient string // from config.contacts
}
// ParseAction parses an action string into an Action.
func ParseAction(s string) (Action, error) {
// "bead" -> BeadAction{}
// "mail:mayor" -> MailAction{Target: "mayor"}
// "email:human" -> EmailAction{Recipient: "human"}
// etc.
}
```
### Email/SMS Implementation
For v1, use simple exec of external commands:
```go
// EmailAction sends email using the 'mail' command or similar.
func (a *EmailAction) Execute(ctx context.Context, esc *Escalation) error {
// Option 1: Use system mail command
// Option 2: Use sendgrid/ses API (future)
// Option 3: Use configured webhook
// For now, just log a placeholder
// Real implementation can be added based on user's infrastructure
}
```
The email/SMS actions can start as stubs that log warnings, with real implementations added based on the user's infrastructure (SendGrid, Twilio, etc.).
---
## Integration Points
### Plugin System
Plugins use escalation for failure notification:
```markdown
# In plugin.md execution section:
On failure:
```bash
gt escalate \
--severity=medium \
--subject="Plugin FAILED: rebuild-gt" \
--body="$ERROR" \
--source="plugin:rebuild-gt"
```
```
### Deacon Patrol
Deacon uses escalation for health issues:
```bash
# In health-scan step:
if [ $unresponsive_cycles -ge 5 ]; then
gt escalate \
--severity=high \
--subject="Witness unresponsive: gastown" \
--body="Witness has been unresponsive for $unresponsive_cycles cycles" \
--source="patrol:deacon:health-scan"
fi
```
### Stale Escalation Check
Can be either:
1. A Deacon patrol step
2. A plugin (dogfood!)
3. Part of `gt escalate` itself (run periodically)
Recommendation: Start as patrol step, migrate to plugin later.
---
## Testing Plan
### Unit Tests
- Config loading and validation
- Action parsing
- Severity level ordering
- Re-escalation logic
### Integration Tests
- Create escalation → bead exists
- Acknowledge → label updated
- Stale detection → re-escalation triggers
- Route execution → all actions called
### Manual Testing
1. `gt escalate --severity=low --subject="Test" --body="Testing"`
2. `gt escalate list --unacked`
3. `gt escalate ack <id>`
4. Wait for stale threshold, run `gt escalate stale`
---
## Dependencies
### Internal Dependencies (task order)
```
gt-i9r20.2 (Config Schema)
│
▼
gt-i9r20.1 (gt escalate command)
│
├──▶ gt-i9r20.4 (gt escalate ack)
│
└──▶ gt-i9r20.3 (Stale patrol)
```
### External Dependencies
- `bd create` for creating escalation beads
- `bd list` for querying escalations
- `bd label` for updating labels
- `gt mail send` for mail action
---
## Open Questions (Resolved)
1. **Where to store config?** → `settings/escalation.json` (follows existing pattern)
2. **How to implement email/SMS?** → Start with stubs, add real impl based on infrastructure
3. **Stale check: patrol step or plugin?** → Start as patrol step, can migrate to plugin
4. **Escalation bead type?** → `type: escalation` (new bead type)
---
## Future Enhancements
1. **Slack integration**: Post to Slack channels
2. **PagerDuty integration**: Create incidents
3. **Escalation dashboard**: Web UI for escalation management
4. **Scheduled escalations**: "Remind me in 2h if not resolved"
5. **Escalation templates**: Pre-defined escalation types

485
docs/design/plugin-system.md Normal file
View File

@@ -0,0 +1,485 @@
# Plugin System Design
> Design document for the Gas Town plugin system.
> Written 2026-01-11, crew/george session.
## Problem Statement
Gas Town needs extensible, project-specific automation that runs during Deacon patrol cycles. The immediate use case is rebuilding stale binaries (gt, bd, wv), but the pattern generalizes to any periodic maintenance task.
Current state:
- Plugin infrastructure exists conceptually (patrol step mentions it)
- `~/gt/plugins/` directory exists with README
- No actual plugins in production use
- No formalized execution model
## Design Principles Applied
### Discover, Don't Track
> Reality is truth. State is derived.
Plugin state (last run, run count, results) lives on the ledger as wisps, not in shadow state files. Gate evaluation queries the ledger directly.
### ZFC: Zero Framework Cognition
> Agent decides. Go transports.
The Deacon (agent) evaluates gates and decides whether to dispatch. Go code provides transport (`gt dog dispatch`) but doesn't make decisions.
### MEOW Stack Integration
| Layer | Plugin Analog |
|-------|---------------|
| **M**olecule | `plugin.md` - work template with TOML frontmatter |
| **E**phemeral | Plugin-run wisps - high-volume, digestible |
| **O**bservable | Plugin runs appear in `bd activity` feed |
| **W**orkflow | Gate → Dispatch → Execute → Record → Digest |
---
## Architecture
### Plugin Locations
```
~/gt/
├── plugins/ # Town-level plugins (universal)
│ └── README.md
├── gastown/
│ └── plugins/ # Rig-level plugins
│ └── rebuild-gt/
│ └── plugin.md
├── beads/
│ └── plugins/
│ └── rebuild-bd/
│ └── plugin.md
└── wyvern/
└── plugins/
└── rebuild-wv/
└── plugin.md
```
**Town-level** (`~/gt/plugins/`): Universal plugins that apply everywhere.
**Rig-level** (`<rig>/plugins/`): Project-specific plugins.
The Deacon scans both locations during patrol.
### Execution Model: Dog Dispatch
**Key insight**: Plugin execution should not block Deacon patrol.
Dogs are reusable workers designed for infrastructure tasks. Plugin execution is dispatched to dogs:
```
Deacon Patrol Dog Worker
───────────────── ─────────────────
1. Scan plugins
2. Evaluate gates
3. For open gates:
└─ gt dog dispatch plugin ──→ 4. Execute plugin
(non-blocking) 5. Create result wisp
6. Send DOG_DONE
4. Continue patrol
...
5. Process DOG_DONE ←── (next cycle)
```
Benefits:
- Deacon stays responsive
- Multiple plugins can run concurrently (different dogs)
- Plugin failures don't stall patrol
- Consistent with Dogs' purpose (infrastructure work)
### State Tracking: Wisps on the Ledger
Each plugin run creates a wisp:
```bash
bd wisp create \
--label type:plugin-run \
--label plugin:rebuild-gt \
--label rig:gastown \
--label result:success \
--body "Rebuilt gt: abc123 → def456 (5 commits)"
```
**Gate evaluation** queries wisps instead of state files:
```bash
# Cooldown check: any runs in last hour?
bd list --type=wisp --label=plugin:rebuild-gt --since=1h --limit=1
```
**Derived state** (no state.json needed):
| Query | Command |
|-------|---------|
| Last run time | `bd list --label=plugin:X --limit=1 --json` |
| Run count | `bd list --label=plugin:X --json \| jq length` |
| Last result | Parse `result:` label from latest wisp |
| Failure rate | Count `result:failure` vs total |
### Digest Pattern
Like cost digests, plugin wisps accumulate and get squashed daily:
```bash
gt plugin digest --yesterday
```
Creates: `Plugin Digest 2026-01-10` bead with summary
Deletes: Individual plugin-run wisps from that day
This keeps the ledger clean while preserving audit history.
---
## Plugin Format Specification
### File Structure
```
rebuild-gt/
└── plugin.md # Definition with TOML frontmatter
```
### plugin.md Format
```markdown
+++
name = "rebuild-gt"
description = "Rebuild stale gt binary from source"
version = 1
[gate]
type = "cooldown"
duration = "1h"
[tracking]
labels = ["plugin:rebuild-gt", "rig:gastown", "category:maintenance"]
digest = true
[execution]
timeout = "5m"
notify_on_failure = true
+++
# Rebuild gt Binary
Instructions for the dog worker to execute...
```
### TOML Frontmatter Schema
```toml
# Required
name = "string" # Unique plugin identifier
description = "string" # Human-readable description
version = 1 # Schema version (for future evolution)
[gate]
type = "cooldown|cron|condition|event|manual"
# Type-specific fields:
duration = "1h" # For cooldown
schedule = "0 9 * * *" # For cron
check = "gt stale -q" # For condition (exit 0 = run)
on = "startup" # For event
[tracking]
labels = ["label:value", ...] # Labels for execution wisps
digest = true|false # Include in daily digest
[execution]
timeout = "5m" # Max execution time
notify_on_failure = true # Escalate on failure
severity = "low" # Escalation severity if failed
```
### Gate Types
| Type | Config | Behavior |
|------|--------|----------|
| `cooldown` | `duration = "1h"` | Query wisps, run if none in window |
| `cron` | `schedule = "0 9 * * *"` | Run on cron schedule |
| `condition` | `check = "cmd"` | Run check command, run if exit 0 |
| `event` | `on = "startup"` | Run on Deacon startup |
| `manual` | (no gate section) | Never auto-run, dispatch explicitly |
### Instructions Section
The markdown body after the frontmatter contains agent-executable instructions. The dog worker reads and executes these steps.
Standard sections:
- **Detection**: Check if action is needed
- **Action**: The actual work
- **Record Result**: Create the execution wisp
- **Notification**: On success/failure
---
## Escalation System
### Problem
Current escalation is ad-hoc "mail Mayor". Issues:
- Mayor gets backlogged easily
- No severity differentiation
- No alternative channels (email, SMS, etc.)
- No tracking of stale escalations
### Solution: Unified Escalation API
New command:
```bash
gt escalate \
--severity=<low|medium|high|critical> \
--subject="Plugin FAILED: rebuild-gt" \
--body="Build failed: make returned exit code 2" \
--source="plugin:rebuild-gt"
```
### Escalation Routing
The command reads town config (`~/gt/config.json` or similar) for routing rules:
```json
{
"escalation": {
"routes": {
"low": ["bead"],
"medium": ["bead", "mail:mayor"],
"high": ["bead", "mail:mayor", "email:human"],
"critical": ["bead", "mail:mayor", "email:human", "sms:human"]
},
"contacts": {
"human_email": "steve@example.com",
"human_sms": "+1234567890"
},
"stale_threshold": "4h"
}
}
```
### Escalation Actions
| Action | Behavior |
|--------|----------|
| `bead` | Create escalation bead with severity label |
| `mail:mayor` | Send mail to mayor/ |
| `email:human` | Send email via configured service |
| `sms:human` | Send SMS via configured service |
### Escalation Beads
Every escalation creates a bead:
```yaml
type: escalation
status: open
labels:
- severity:high
- source:plugin:rebuild-gt
- acknowledged:false
```
### Stale Escalation Patrol
A patrol step (or plugin!) checks for unacknowledged escalations:
```bash
bd list --type=escalation --label=acknowledged:false --older-than=4h
```
Stale escalations get re-escalated at higher severity.
### Acknowledging Escalations
```bash
gt escalate ack <bead-id>
# Sets label acknowledged:true
```
---
## New Commands Required
### gt stale
Expose binary staleness check:
```bash
gt stale # Human-readable output
gt stale --json # Machine-readable
gt stale --quiet # Exit code only (0=stale, 1=fresh)
```
### gt dog dispatch
Formalized plugin dispatch to dogs:
```bash
gt dog dispatch --plugin <name> [--rig <rig>]
```
This:
1. Finds the plugin definition
2. Slinga a standardized work unit to an idle dog
3. Returns immediately (non-blocking)
### gt escalate
Unified escalation API:
```bash
gt escalate \
--severity=<level> \
--subject="..." \
--body="..." \
[--source="..."]
gt escalate ack <bead-id>
gt escalate list [--severity=...] [--stale]
```
### gt plugin
Plugin management:
```bash
gt plugin list # List all plugins
gt plugin show <name> # Show plugin details
gt plugin run <name> [--force] # Manual trigger
gt plugin digest [--yesterday] # Squash wisps to digest
gt plugin history <name> # Show execution history
```
---
## Implementation Plan
### Phase 1: Foundation
1. **`gt stale` command** - Expose CheckStaleBinary() via CLI
2. **Plugin format spec** - Finalize TOML schema
3. **Plugin scanning** - Deacon scans town + rig plugin dirs
### Phase 2: Execution
4. **`gt dog dispatch --plugin`** - Formalized dog dispatch
5. **Plugin execution in dogs** - Dog reads plugin.md, executes
6. **Wisp creation** - Record results on ledger
### Phase 3: Gates & State
7. **Gate evaluation** - Cooldown via wisp query
8. **Other gate types** - Cron, condition, event
9. **Plugin digest** - Daily squash of plugin wisps
### Phase 4: Escalation
10. **`gt escalate` command** - Unified escalation API
11. **Escalation routing** - Config-driven multi-channel
12. **Stale escalation patrol** - Check unacknowledged
### Phase 5: First Plugin
13. **`rebuild-gt` plugin** - The actual gastown plugin
14. **Documentation** - So Beads/Wyvern can create theirs
---
## Example: rebuild-gt Plugin
```markdown
+++
name = "rebuild-gt"
description = "Rebuild stale gt binary from gastown source"
version = 1
[gate]
type = "cooldown"
duration = "1h"
[tracking]
labels = ["plugin:rebuild-gt", "rig:gastown", "category:maintenance"]
digest = true
[execution]
timeout = "5m"
notify_on_failure = true
severity = "medium"
+++
# Rebuild gt Binary
Checks if the gt binary is stale (built from older commit than HEAD) and rebuilds.
## Gate Check
The Deacon evaluates this before dispatch. If gate closed, skip.
## Detection
Check binary staleness:
```bash
gt stale --json
```
If `"stale": false`, record success wisp and exit early.
## Action
Rebuild from source:
```bash
cd ~/gt/gastown/crew/george && make build && make install
```
## Record Result
On success:
```bash
bd wisp create \
--label type:plugin-run \
--label plugin:rebuild-gt \
--label rig:gastown \
--label result:success \
--body "Rebuilt gt: $OLD → $NEW ($N commits)"
```
On failure:
```bash
bd wisp create \
--label type:plugin-run \
--label plugin:rebuild-gt \
--label rig:gastown \
--label result:failure \
--body "Build failed: $ERROR"
gt escalate --severity=medium \
--subject="Plugin FAILED: rebuild-gt" \
--body="$ERROR" \
--source="plugin:rebuild-gt"
```
```
---
## Open Questions
1. **Plugin discovery in multiple clones**: If gastown has crew/george, crew/max, crew/joe - which clone's plugins/ dir is canonical? Probably: scan all, dedupe by name, prefer rig-root if exists.
2. **Dog assignment**: Should specific plugins prefer specific dogs? Or any idle dog?
3. **Plugin dependencies**: Can plugins depend on other plugins? Probably not in v1.
4. **Plugin disable/enable**: How to temporarily disable a plugin without deleting it? Label on a plugin bead? `enabled = false` in frontmatter?
---
## References
- PRIMING.md - Core design principles
- mol-deacon-patrol.formula.toml - Patrol step plugin-run
- ~/gt/plugins/README.md - Current plugin stub