gupp-propulsion

# GUPP Propulsion The Gas Town Universal Propulsion Principle: **If there is work on your hook, YOU MUST RUN IT.** GUPP is the interrupt controller of the Gastown chipset. In a real processor, the interrupt controller converts external events (keyboard press, network packet, timer tick) into CPU interrupts that force immediate handling. GUPP does the same for AI coding agents: it converts the polled model (agent checks periodically, waits for user input) into an interrupt-driven model (work appears on hook, agent executes immediately). ## Why GUPP Exists RLHF-trained LLM assistants have a strong bias toward *waiting for the user* — asking clarifying questions, seeking confirmation, pausing for feedback. This is appropriate in interactive chat but catastrophic for autonomous multi-agent orchestration, where every moment of idle waiting stalls the pipeline. Gastown discovered this empirically: agents spawned with a work item would introduce themselves, summarize the task, and *wait*, asking "Shall I proceed?" when the answer was already on their hook. GUPP overrides this trained passivity with an explicit, non-negotiable execution mandate: if you have hooked work, you do not wait, do not ask for confirmation, do not pause for feedback. You begin immediately. This is physics, not politeness. ## Activation Triggers This skill activates when: - An agent has work assigned to its hook and is not yet executing - Stall detection identifies an agent with hooked work that has gone idle - A new agent is spawned and needs GUPP enforcement injected into its context - Runtime-specific GUPP strategy selection is needed - Heartbeat supervision needs to be configured for active agents - An agent has been nudged but remains stalled ## Enforcement at a Glance GUPP enforcement adapts to each runtime via the Runtime HAL. The HAL exposes `getGUPPStrategy()` which returns one of: - `hook_injection` — Claude Code (SessionStart hook, highest fidelity) - `startup_fallback` — Codex (tmux `gt prime`, medium fidelity) - `polling` — Gemini / Cursor / unknown (prompt preamble + state polling) A Deacon heartbeat loop runs inside the witness-observer at the configured `nudge_interval`, detecting agents that received hooks but stalled. After `restart_threshold`, the watchdog requests a session restart. Per-runtime strategy tables, configurable thresholds, the full heartbeat protocol, and the Claude Code HAL note are in [`references/runtime-strategies.md`](references/runtime-strategies.md). ## Safety Boundaries **These safety rules MUST remain in effect at all times — they are not advisory.** ### GUPP Is Advisory in GSD GUPP enforcement is ADVISORY within GSD's structured workflow. The GSD orchestrator's phase gates, verification steps, and checkpoint protocols take precedence over GUPP urgency. If a GSD checkpoint requires human verification, GUPP does not override it. If a phase gate blocks progress pending approval, GUPP does not force execution past the gate. The hierarchy is: ``` GSD orchestrator (highest authority) -> Phase gates and checkpoints -> GUPP propulsion (execution enforcement) -> Agent autonomy (lowest -- must obey all above) ``` GUPP operates between the orchestrator's structural gates. Within a phase, within an approved plan, within a committed task — GUPP demands immediate execution. But it never overrides the orchestrator's decision about *what* to execute or *when* a phase is complete. ### Restart Limits The watchdog restart mechanism has strict limits to prevent infinite restart loops: | Limit | Value | |-------|-------| | Max restart threshold | 1800s (30 min, hard cap) | | Max restarts per bead | 3 | | Restart cooldown | 60s minimum between consecutive restarts | After 3 restarts for the same work item, escalation to human is mandatory. ### Human Escalation After 3 restarts for the same bead without resolution, GUPP stops attempting automated recovery and escalates to a human operator via durable mail to the mayor. The mayor surfaces this through whatever channel the human is monitoring. GUPP does not attempt a fourth restart. ### No Data Destruction GUPP enforcement never destroys work in progress. Restarts preserve the agent's branch and commits. Nudges are non-destructive signals. Escalations are informational. At no point does GUPP delete files, reset branches, or discard uncommitted changes. ## Integration with Other Gastown Skills Reads runtime capabilities from `runtime-hal` (`getGUPPStrategy()`, thresholds, restart support). Targets `polecat-worker` (the primary enforcement target). Runs inside `witness-observer` (Deacon heartbeat). Sends nudges via `nudge-sync` and escalations via `mail-async`. Reads agent activity timestamps from `beads-state` and hook status from `hook-persistence`. `mayor-coordinator` receives escalations. `sling-dispatch` sets hooks that activate GUPP enforcement. ## References Implementation detail moved to: - [`references/runtime-strategies.md`](references/runtime-strategies.md) — per-runtime enforcement tables (Claude Code, Codex, Gemini, Cursor), threshold reference, Deacon heartbeat pattern. - [`references/boundaries.md`](references/boundaries.md) — full Safety Boundaries detail (advisory-in-GSD hierarchy, restart limits, escalation, no-data-destruction). - [`references/metrics-and-learning.md`](references/metrics-and-learning.md) — observable metrics (response time, nudge effectiveness, strategy success, stall frequency) and the learning feedback loop. - [`references/gastown-origin.md`](references/gastown-origin.md) — the GUPP principle from Gastown, how it fights model training bias. - [`heartbeat.md`](heartbeat.md) — Deacon heartbeat supervision pattern and integration points.