gastown/docs/design/escalation.md

Gas Town Escalation Protocol

Reference for escalation paths in Gas Town

Overview

Gas Town agents can escalate issues when automated resolution isn't possible. This document covers:

• Severity levels and routing
• Escalation categories for structured communication
• Tiered escalation (Deacon -> Mayor -> Overseer)
• Decision patterns for async resolution
• Integration with gates and patrol lifecycles

Severity Levels

Level	Priority	Description	Examples
CRITICAL	P0 (urgent)	System-threatening, immediate attention	Data corruption, security breach, system down
HIGH	P1 (high)	Important blocker, needs human soon	Unresolvable merge conflict, critical bug, ambiguous spec
MEDIUM	P2 (normal)	Standard escalation, human at convenience	Design decision needed, unclear requirements

Escalation Categories

Categories provide structured routing based on the nature of the escalation:

Category	Description	Default Route
decision	Multiple valid paths, need choice	Deacon -> Mayor
help	Need guidance or expertise	Deacon -> Mayor
blocked	Waiting on unresolvable dependency	Mayor
failed	Unexpected error, can't proceed	Deacon
emergency	Security or data integrity issue	Overseer (direct)
gate_timeout	Gate didn't resolve in time	Deacon
lifecycle	Worker stuck or needs recycle	Witness

Escalation Command

Basic Usage (unchanged)

# Basic escalation (default: MEDIUM severity)
gt escalate "Database migration failed"

# Critical escalation - immediate attention
gt escalate -s CRITICAL "Data corruption detected in user table"

# High priority escalation
gt escalate -s HIGH "Merge conflict cannot be resolved automatically"

# With additional details
gt escalate -s MEDIUM "Need clarification on API design" -m "Details..."

Category-Based Escalation

# Decision needed - routes to Deacon first
gt escalate --type decision "Which auth approach?"

# Help request
gt escalate --type help "Need architecture guidance"

# Blocked on dependency
gt escalate --type blocked "Waiting on bd-xyz"

# Failure that can't be recovered
gt escalate --type failed "Tests failing unexpectedly"

# Emergency - direct to Overseer
gt escalate --type emergency "Security vulnerability found"

Tiered Routing

# Explicit routing to specific tier
gt escalate --to deacon "Infra issue"
gt escalate --to mayor "Cross-rig coordination needed"
gt escalate --to overseer "Human judgment required"

# Forward from one tier to next
gt escalate --forward --to mayor "Deacon couldn't resolve"

Structured Decisions

For decisions requiring explicit choices:

gt escalate --type decision \
  --question "Which authentication approach?" \
  --options "JWT tokens,Session cookies,OAuth2" \
  --context "Admin panel needs login" \
  --issue bd-xyz

This updates the issue with a structured decision format (see below).

What Happens on Escalation

1. Bead created/updated: Escalation bead (tagged escalation) created or updated
2. Mail sent: Routed to appropriate tier (Deacon, Mayor, or Overseer)
3. Activity logged: Event logged to activity feed
4. Issue updated: For decision type, issue gets structured format

Tiered Escalation Flow

Worker encounters issue
    |
    v
gt escalate --type <category> [--to <tier>]
    |
    v
[Deacon receives] (default for most categories)
    |
    +-- Can resolve? --> Updates issue, re-slings work
    |
    +-- Cannot resolve? --> gt escalate --forward --to mayor
                                |
                                v
                           [Mayor receives]
                                |
                                +-- Can resolve? --> Updates issue, re-slings
                                |
                                +-- Cannot resolve? --> gt escalate --forward --to overseer
                                                            |
                                                            v
                                                       [Overseer resolves]

Each tier can resolve OR forward. The escalation chain is tracked via comments.

Decision Pattern

When --type decision is used, the issue is updated with structured format:

## Decision Needed

**Question:** Which authentication approach?

| Option | Description |
|--------|-------------|
| A | JWT tokens |
| B | Session cookies |
| C | OAuth2 |

**Context:** Admin panel needs login

**Escalated by:** beads/polecats/obsidian
**Escalated at:** 2026-01-01T15:00:00Z

**To resolve:**
1. Comment with chosen option (e.g., "Decision: A")
2. Reassign to work queue or original worker

The issue becomes the async communication channel. Resolution updates the issue and can trigger re-slinging to the original worker.

Integration Points

Gate Timeouts

When timer gates expire (see bd-7zka.2), Witness escalates:

if gate.Expired() {
    exec.Command("gt", "escalate",
        "--type", "gate_timeout",
        "--severity", "HIGH",
        "--issue", gate.BlockedIssueID,
        fmt.Sprintf("Gate %s timed out after %s", gate.ID, gate.Timeout)).Run()
}

Witness Patrol

Witness formalizes stuck-polecat detection as escalation:

exec.Command("gt", "escalate",
    "--type", "lifecycle",
    "--to", "mayor",
    "--issue", polecat.CurrentIssue,
    fmt.Sprintf("Polecat %s stuck: no progress for %d minutes", polecat.ID, minutes)).Run()

Refinery

On merge failures that can't be auto-resolved:

exec.Command("gt", "escalate",
    "--type", "failed",
    "--issue", mr.IssueID,
    "Merge failed: "+reason).Run()

Polecat Exit with Escalation

When a polecat needs a decision to continue:

# 1. Update issue with decision structure
bd update $ISSUE --notes "$(cat <<EOF
## Decision Needed

**Question:** Which approach for caching?

| Option | Description |
|--------|-------------|
| A | Redis (external dependency) |
| B | In-memory (simpler, no persistence) |
| C | SQLite (local persistence) |

**Context:** API response times are slow, need caching layer.
EOF
)"

# 2. Escalate
gt escalate --type decision --issue $ISSUE "Caching approach needs decision"

# 3. Exit cleanly
gt done --status ESCALATED

Mayor Startup Check

On gt prime, Mayor checks for pending escalations:

## PENDING ESCALATIONS

There are 3 escalation(s) awaiting attention:

  CRITICAL: 1
  HIGH: 1
  MEDIUM: 1

  [CRITICAL] Data corruption detected (gt-abc)
  [HIGH] Merge conflict in auth module (gt-def)
  [MEDIUM] API design clarification needed (gt-ghi)

**Action required:** Review escalations with `bd list --tag=escalation`
Close resolved ones with `bd close <id> --reason "resolution"`

When to Escalate

Agents SHOULD escalate when:

• System errors: Database corruption, disk full, network failures
• Security issues: Unauthorized access attempts, credential exposure
• Unresolvable conflicts: Merge conflicts that can't be auto-resolved
• Ambiguous requirements: Spec is unclear, multiple valid interpretations
• Design decisions: Architectural choices that need human judgment
• Stuck loops: Agent is stuck and can't make progress
• Gate timeouts: Async conditions didn't resolve in expected time

Agents should NOT escalate for:

• Normal workflow: Regular work that can proceed without human input
• Recoverable errors: Transient failures that will auto-retry
• Information queries: Questions that can be answered from context

Viewing Escalations

# List all open escalations
bd list --status=open --tag=escalation

# Filter by category
bd list --tag=escalation --tag=decision

# View specific escalation
bd show <escalation-id>

# Close resolved escalation
bd close <id> --reason "Resolved by fixing X"

Implementation Phases

Phase 1: Extend gt escalate

• Add --type flag for categories
• Add --to flag for routing (deacon, mayor, overseer)
• Add --forward flag for tier forwarding
• Backward compatible with existing usage

Phase 2: Decision Pattern

• Add --question, --options, --context flags
• Auto-update issue with decision structure
• Parse decision from issue comments on resolution

Phase 3: Gate Integration

• Add gate_timeout escalation type
• Witness checks timer gates, escalates on timeout
• Refinery checks GH gates, escalates on timeout/failure

Phase 4: Patrol Integration

• Formalize Witness stuck-polecat as escalation
• Formalize Refinery merge-failure as escalation
• Unified escalation handling in Mayor

References

• bd-7zka.2: Gate evaluation (uses escalation for timeouts)
• bd-0sgd: Design issue for this extended escalation system