gastown/docs/escalation.md

Gas Town Escalation Protocol

Reference for human escalation path in Gas Town

Overview

Gas Town agents can escalate issues to the human overseer when automated resolution isn't possible. This provides a structured channel for:

• System-threatening errors (data corruption, security issues)
• Unresolvable conflicts (merge conflicts, ambiguous requirements)
• Design decisions requiring human judgment
• Edge cases in molecular algebra that can't proceed without guidance

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 Command

Any agent can escalate directly using gt escalate:

# 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 "The spec mentions both REST and GraphQL..."

What happens on escalation

1. Bead created: An escalation bead (tagged escalation) is created for audit trail
2. Mail sent: Mail is sent to the overseer (human operator) with appropriate priority
3. Activity logged: Event logged to the activity feed for visibility

Escalation Flow

Any Agent                     Overseer (Human)
    |                              |
    | gt escalate -s HIGH "msg"    |
    |----------------------------->|
    |                              |
    | [ESCALATION] msg (P1 mail)   |
    |----------------------------->|
    |                              |
    |     Reviews & resolves       |
    |                              |
    |   bd close <esc-id>          |
    |<-----------------------------|

Mayor Startup Check

On gt prime, the Mayor automatically checks for pending escalations:

## PENDING ESCALATIONS

There are 3 escalation(s) awaiting human 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

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

Molecular Algebra Edge Cases

All edge cases in molecular algebra should escalate rather than fail silently:

// Example: Molecule step has conflicting dependencies
if hasConflictingDeps {
    // Don't fail silently - escalate
    exec.Command("gt", "escalate", "-s", "HIGH",
        "Molecule step has conflicting dependencies: "+stepID).Run()
}

This ensures:

1. Issues are visible to humans
2. Audit trail exists for debugging
3. System doesn't silently break

Viewing Escalations

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

# View specific escalation
bd show <escalation-id>

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

Integration with Existing Flow

The escalation system integrates with the existing polecat exit flow:

Exit Type	When to Use	Escalation?
COMPLETED	Work done successfully	No
ESCALATED	Hit blocker, needs human	Yes (automatic via gt done --exit ESCALATED)
DEFERRED	Work paused, will resume	No

When a polecat uses gt done --exit ESCALATED:

1. Witness receives the notification
2. Witness can forward to Mayor with ESCALATION: subject
3. Mayor callback handler forwards to overseer

The new gt escalate command provides a more direct path that any agent can use, with structured severity levels and audit trail.