a7831ba11d
Implements structured escalation channel for Gas Town: - gt escalate command with CRITICAL/HIGH/MEDIUM severity levels - Mayor startup check for pending escalations - Escalation beads with tag for audit trail - Mail routing to overseer with priority mapping - Documentation in docs/escalation.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
150 lines
4.8 KiB
Markdown
150 lines
4.8 KiB
Markdown
# 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`:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```go
|
|
// 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
|
|
|
|
```bash
|
|
# 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.
|