Warp Drive

Autonomous development loop for Claude Code. Picks up approved work from GitHub Issues, breaks it into chunks, codes, tests, commits, and reports — with minimal human intervention.

TL;DR

# Inside Claude Code
/warp-drive 42       # work on issue #42
/warp-drive          # auto-discover next approved issue
/stop-warp-drive     # graceful stop
 
# From any terminal
warp status          # check on the loop
warp stop            # abort from outside

Where It Fits
Installation
First-Time Setup
Running Warp Drive
The warp CLI
How It Works
Stopping and Resuming
Remote Mode (RDB)
Error Handling
Configuration
What Gets Created
Troubleshooting
Internals Reference

Where It Fits

Vision & Strategy (docs/vision.md)    /vision — why, who, where
└── Capability (GitHub Issue, cap)     /capability — feature spec
    └── Requirement (GitHub Issue, req) /requirement — acceptance criteria
        └── Warp-drive chunks          automatic — individual commits

Warp Drive operates at the bottom of the product hierarchy. It picks up requirements (not capabilities or vision) and turns acceptance criteria into commits. Each requirement is a GitHub Issue with checkboxes; warp-drive works through them one commit at a time.

Installation

Prerequisites

These must be installed on your machine:

Dependency	Check	Install
Node.js	`node --version`	nodejs.org
jq	`jq --version`	`brew install jq`
GitHub CLI	`gh --version`	`brew install gh`
Git	`git --version`	`brew install git`

BoB Framework

Warp Drive is part of BoB (Big ol’ Brain), the global Claude Code tooling framework at ~/.claude/. If you have BoB installed, warp-drive is already available. The key files:

~/.claude/
├── bin/warp                              # CLI (this is new)
├── commands/warp-drive.md                # /warp-drive slash command
├── commands/dev-up.md                    # /dev-up slash command
├── skills/stop-warp-drive/SKILL.md       # /stop-warp-drive skill
├── scripts/warp-drive/state-machine.js   # State machine engine
├── scripts/dev-lifecycle/                # Dev environment IaC scripts
│   ├── dev-up.sh                         # Full lifecycle orchestrator
│   ├── health-check.sh                   # Lightweight health probe
│   ├── provision-users.sh                # Test user provisioning
│   └── check-seed-coverage.sh            # Seed data coverage gate
├── hooks/warp-drive-gate.sh              # Blocks commits outside committing phase
├── hooks/warp-drive-inject.sh            # Resumes state on session start
├── hooks/warp-drive-edit-tracker.sh      # Doom loop detection
├── hooks/warp-drive-pre-exit.sh          # Self-verification before phase advance
├── hooks/warp-drive-stop.sh              # Blocks exit when report is pending
├── templates/dev.json                    # Dev manifest template
├── templates/seed/                       # Seed data templates
└── docs/warp-drive-guide.md              # This file

Add warp to your PATH

Add this to your ~/.zshrc (or ~/.bashrc):

# BoB CLI tools
export PATH="$HOME/.claude/bin:$PATH"

Then reload: source ~/.zshrc

Verify: warp help

Hook Registration

All 5 hooks are registered in ~/.claude/settings.json automatically. If you’re setting up from scratch, the hooks need entries in:

Hook Type	File	Purpose
SessionStart	`warp-drive-inject.sh`	Resume from last phase
PreToolUse (Bash)	`warp-drive-gate.sh`	Block commits outside committing phase
PreToolUse (Bash)	`warp-drive-pre-exit.sh`	Self-verification before phase advance
PostToolUse (Edit\|Write)	`warp-drive-edit-tracker.sh`	Track edits, detect doom loops
PostToolUse (Edit\|Write)	`warp-drive-docs-detector.sh`	Auto-detect doc edits → advance state
PostToolUse (Bash)	`warp-drive-commit-detector.sh`	Auto-detect git commit → advance state
Stop	`warp-drive-stop.sh`	Block exit when report is pending

If hooks aren’t registered, warp-drive still works — you just lose the safety rails (commits could happen at the wrong time, doom loops won’t be caught, auto-detection won’t fire, etc.).

First-Time Setup

1. Initialize your project with BoB tooling

cdi -y /path/to/your/project

This creates the .claude/ directory structure in your project. If you skip this, /automation will run it for you.

2. Set automation level

Inside Claude Code, in your project directory:

/automation level 2

This writes permission rules to .claude/settings.local.json. Warp-drive requires Level 2 or 3.

Level	Who It’s For	Merge Strategy
Level 2 (Trusted Dev)	Active development, you review PRs	Creates PR for review
Level 3 (Autonomous)	Trusted mode, minimal intervention	Direct merge to master

3. Create work items

Create a requirement as a GitHub Issue:

/requirement

This creates an issue with acceptance criteria checkboxes, labeled req. When ready for warp-drive, add the approved label:

gh issue edit 42 --add-label approved

4. Create a feature branch (Level 2 only)

/start-work

Level 3 auto-creates branches. Level 2 requires you to start one first.

5. Launch

/warp-drive 42       # work on issue #42
/warp-drive          # auto-discover next approved issue

Running Warp Drive

Starting a session

From inside Claude Code, in your project directory:

/warp-drive              # finds next issue with labels: req + approved
/warp-drive 42           # works on issue #42 specifically

Warp-drive checks prerequisites (automation level, branch, test command), then enters the loop.

What you’ll see

Once running, warp-drive works through phases automatically. At Level 2/3, it only interrupts you for project decisions — architecture questions, ambiguous requirements, new dependencies, or scope expansion. Everything else is autonomous.

Each chunk produces:

Code changes implementing 1-3 acceptance criteria
A test run
A conventional commit (feat(scope): description)
A chunk report filed as a GitHub Issue

When it finishes

After all chunks are done, warp-drive:

Runs a final test
Merges (L2: creates PR / L3: direct merge to master)
Asks “Continue to next task?”
If yes → discovers next approved issue
If no → files a session summary and exits

The warp CLI

The warp command is a terminal tool for observing and controlling warp-drive from outside Claude Code. Think of it as docker ps for the autonomous loop.

Commands

warp status          # What phase is it in? What issue? How many commits?
warp log             # Full phase transition history
warp config          # Show workflow settings for this project
warp stop            # Graceful abort (moves to aborted phase)
warp stop --hard     # Emergency reset (deletes state file)
warp help            # Help text

warp status

Shows the live state of the loop:

WARP DRIVE ACTIVE
  Project:  bodmail
  Phase:    coding
  Issue:    42
  Branch:   feature/issue-42-email-parser
  Level:    2
  Chunk:    2 / 5

  Commits:  1    Chunks: 1    Tests: 3    Reports: 1

  Started:  2026-02-18T14:30:00Z
  PID:      12345

If the Claude session has ended but the state file remains, it shows (stale).

warp stop

From outside Claude Code, warp stop transitions the state machine to the aborted phase. The next time Claude Code starts in that project, it picks up the abort and runs cleanup (WIP commit, abort report).

warp stop --hard deletes the state file immediately. No cleanup, no report. Use this when the state file is corrupted or you just want a clean slate.

warp log

Shows every phase transition with timestamps:

Phase History (bodmail)

  #  Phase                     Event               Time
  ── ──────────────────────── ─────────────────── ─────────────────────
   0  prerequisites             init                2026-02-18T14:30:00Z
   1  discovering               prerequisites_ok    2026-02-18T14:30:05Z
   2  planning                  work_selected       2026-02-18T14:30:12Z
   ...

warp config

Shows the current workflow tuning for the project — automation level, RDB status, and all _workflow settings with their defaults.

How It Works

The State Machine

Warp-drive is a phase-based state machine backed by a persistent JSON file at .claude/.warp-drive-state.json in your project. Hooks enforce phase ordering — commits are blocked outside the committing phase, session exit is blocked without a report.

Phase Flow

prerequisites → discovering → planning → chunking
    ↓
  coding → updating_docs → testing → committing → reporting
    ↑                                                  ↓
    └──────────── next chunk ←──── chunk_complete ─────┘
                                        ↓ (all done)
                          requirement_complete → merging
                                                   ↓
                                          awaiting_continue
                                           ↙          ↘
                                   discovering    session_ending
                                  (next task)      (done)

  ─── Circuit-breaker checkpoint ──────────────────────────────
  any phase ──(phase_timeout |               ┌─ budget_continue → coding
              retry_exceeded |               │
              coding_cycles_exceeded |       │  (resume work)
              total_chunks_exceeded |        │
              session_timeout)──→ budget_exceeded ─┤
                                                   │
                                                   └─ budget_abort → aborted
                                                      (give up & clean up)
  ─────────────────────────────────────────────────────────────

The state machine routes any phase into budget_exceeded when an enforced budget trips (see Configuration for the trigger reasons). From budget_exceeded, a budget_continue event resumes coding; budget_abort moves to aborted. The aborted phase has its own cleanup events: abort_resolved (cleanup OK → completed), abort_cleanup_failed (cleanup failed → completed anyway), and restart (back to idle).

Phase Details

Phase	What Happens	Advances When
prerequisites	Checks automation level (2+), branch (not main), test command	All checks pass
discovering	Runs `gh issue list --label approved` to find work	Issue selected
planning	Reads issue, drafts approach if complex (>3 ACs or architecture decisions)	Plan ready
chunking	Splits work into commit-sized pieces (max 3 ACs each)	Chunks defined
coding	Implements the current chunk’s acceptance criteria	Code complete
updating_docs	Checks off completed ACs in the GitHub Issue	Hook auto-detects
testing	Runs project test suite; retries up to 3 alternatives on failure	Tests pass
committing	Creates conventional commit; hook auto-detects	Commit created
doc_drift_check (opt-in)	Runs `/doc-sync` (mechanical fixes) and `/doc-audit --fail-on-drift` after the commit. Active when `_workflow.doc_drift_gate=true`.	`drift_clean` → reporting / `drift_blocked` → coding
reporting	Files chunk report as GitHub Issue	Report filed
chunk_complete	Checks if more chunks remain	Next chunk or done
requirement_complete	Final test, close issue via PR	Merge ready
merging	L2: push + PR / L3: rebase + push master	Merged
awaiting_continue	Asks: “Continue to next task?”	User responds
session_ending	Files session summary, notifies, cleans up state	Done

Automation Levels in Practice

Behavior	Level 2	Level 3
Branch creation	You create via `/start-work`	Auto-creates `feature/issue-NN-title`
Merge strategy	Creates PR for review	Direct merge to master
Decisions	Asks for architecture, scope, ambiguity	Same
Continue prompt	”Continue to next task?”	Same
File operations	Auto-approved	Auto-approved
Destructive git	Blocked (force push, reset —hard)	Blocked (force push, reset —hard)

Self-Verification

Before advancing past key phases (code_complete, tests_passed, requirement_done), a hook injects a verification prompt forcing Claude to re-read the original acceptance criteria and confirm each one is genuinely satisfied — not just that code exists.

Doom Loop Detection

A PostToolUse hook tracks how many times each file is edited during a phase. If any file exceeds the threshold (default: 5 edits), a warning is injected. This catches infinite edit cycles where Claude keeps tweaking the same file without making progress.

Stopping and Resuming

Stopping

From inside Claude Code:

/stop-warp-drive              # Graceful: WIP commit, abort report, cleanup
/stop-warp-drive reset        # Hard: delete state file immediately

From any terminal:

warp stop                     # Graceful abort
warp stop --hard              # Hard reset

Graceful stop does:

Transitions to aborted phase
Creates a WIP commit for uncommitted changes
Files an abort report as a GitHub Issue
Cleans up the state file

Hard reset does:

Deletes the state file
That’s it — uncommitted work stays in the working tree

Resuming

Warp-drive auto-resumes. When you start a new Claude Code session in a project that has a .warp-drive-state.json, the SessionStart hook injects the current phase context and Claude picks up where it left off.

If the state is stale (the original Claude process has ended), the session still resumes — it just notes the staleness.

The Stop Hook

When you try to exit Claude Code (/exit, Ctrl+D, etc.) during an active warp-drive session:

Report pending? Exit is blocked. File the chunk report first.
Other active phase? Exit is allowed with an advisory: “Consider running session end protocol before stopping.”

Remote Mode (RDB)

For autonomous sessions where you’re away from the terminal.

Setup

/rdb on

This enables the Remote Decision Bridge. All decisions go to Telegram instead of the terminal, and every phase transition sends a notification.

What you get on Telegram

Phase transition notifications: [warp-drive] coding -- chunk 2/5 for #42
Decision prompts when Claude needs input
Completion notice: [warp-drive] session ending -- 4 commits, 3 chunks

Decision Timeout

If warp-drive needs your input (terminal or Telegram) and you don’t respond within 10 minutes:

It files a GitHub Issue labeled todo, assigned to you, describing the decision needed
Skips the blocked item and continues to the next chunk
If nothing else to do, transitions to session ending

You’ll find the TODO in your issue list when you’re back.

Going AFK

Tell Claude you’re stepping away — it treats that as /rdb on:

“I’m going to grab lunch, keep going”

Dev Environment Integration

When a project has a dev.json at its root, warp-drive automatically manages the dev environment throughout the coding loop.

What happens

Phase	Action	Script
prerequisites	Full dev-up: start server, run migrations, seed data, provision users	`dev-up.sh "$(pwd)" --verbose`
coding	Seed coverage check (advisory — warns if schema changed without seed data)	`check-seed-coverage.sh "$(pwd)"`
chunk_complete	Fast health check before next chunk	`dev-up.sh "$(pwd)" --check`
chunk_complete (recovery)	Full dev-up if health check fails	`dev-up.sh "$(pwd)" --verbose`

Dev health as a blocker

If the dev server goes down during coding and can’t be recovered after 2 attempts, warp-drive treats it as a blockable event and escalates per the Error Escalation protocol.

Setting up dev.json

# Copy template and customize
cp ~/.claude/templates/dev.json ./dev.json
vi dev.json

The template has sensible defaults for SvelteKit + Cloudflare Workers projects. Customize the server.command, server.port, server.health, seed, and auth sections for your stack.

Seed data in the loop

Warp-drive encourages additive seed data: when a chunk adds new database entities or lifecycle states, the check-seed-coverage.sh gate advises adding seed data in the same commit. This ensures dev is always testable with realistic data across all entity states.

Skipping dev lifecycle

Projects without dev.json skip all dev lifecycle steps — the integration is fully opt-in. Set _workflow.dev_health_check: false to disable even when dev.json exists.

See dev-lifecycle.md for the full IaC dev lifecycle reference.

Configuration

All settings live in .claude/settings.local.json under _workflow. Edit directly or view with warp config.

Setting	Default	Purpose
`max_acs_per_commit`	3	Max acceptance criteria per chunk
`test_before_commit`	true	Run tests before each commit
`auto_merge`	true	L3: auto-merge to master
`max_phase_minutes`	30	Timeout per phase before budget warning
`max_coding_cycles`	3	Max code/test retries per chunk
`max_retries_per_chunk`	5	Max total retries before escalation
`max_edits_per_file`	5	Doom loop detection threshold
`pre_exit_verification`	true	Self-check before phase advance
`decision_timeout_minutes`	10	Minutes before filing TODO issue
`heartbeat_on_commit`	true	RDB notify on each commit
`reconcile_per_chunk`	true	Auto-correct progress counters
`dev_health_check`	true	Run dev-up health check between chunks
`dev_seed_check`	true	Run seed coverage advisory during coding
`max_total_chunks`	20	Circuit breaker: max chunks per session (hard limit)
`max_session_minutes`	480	Circuit breaker: max session duration in minutes (hard limit)
`phase_timeout_enforcement`	`warn`	How `max_phase_minutes` breaches are handled: `warn` (advisory only), `block` (reject the offending transition until elapsed time recovers), or `abort` (route through `budget_exceeded` and auto-abort)
`doc_drift_gate`	`false`	When `true`, the slash command fires `commit_with_doc_gate` after each commit, routing through the `doc_drift_check` phase before reporting. Mechanical drift is auto-fixed via `/doc-sync`; high-severity audit findings route the loop back to `coding`. See Doc Drift Gate.

phase_timeout_enforcement is the only budget threshold whose enforcement mode is configurable — retry_exceeded, coding_cycles_exceeded, total_chunks_exceeded, and session_timeout are always enforced (they always route through budget_exceeded). Set phase_timeout_enforcement to warn (the default) for ordinary use and to block or abort only when you actively want phase-level timeouts to halt the loop.

For the full budget system, circuit breaker behavior, token capture pipeline, cost estimation, and reporting tools, see Token Monitoring & Budget System.

Verification Gates

You can configure custom shell commands that must pass before phase transitions:

{
  "_workflow": {
    "verification_gates": {
      "code_complete": ["make lint"],
      "tests_passed": ["make type-check"]
    }
  }
}

If a gate command fails, the transition is blocked and Claude must fix the issue before advancing.

Doc Drift Gate

When _workflow.doc_drift_gate=true, the loop routes through a new doc_drift_check phase between committing and reporting:

committing → (commit_with_doc_gate) → doc_drift_check
                                         ↙               ↘
                              drift_clean              drift_blocked
                                  ↓                         ↓
                              reporting                  coding
                            (proceed normally)     (fix high-severity drift)

Inside the gate:

~/.claude/scripts/doc-keeper/sync.js --root . --apply runs and applies every fix_kind: mechanical finding (component counts, label naming, etc.).
~/.claude/scripts/doc-keeper/audit.js --root . --fail-on-drift re-audits.
If audit exits zero (no high-severity drift), the loop emits drift_clean and proceeds to reporting. Any sync edits are staged into a follow-up commit (or amended into the chunk commit, depending on policy).
If audit exits non-zero, the loop emits drift_blocked and returns to coding so Claude can address the high-severity findings before retrying the chunk.

The gate is opt-in (doc_drift_gate=false by default) for backward compatibility. When it’s off, the standard committed → reporting transition still runs.

The advisory hook hooks/doc-drift-warning.sh runs after every successful git commit — even when the gate is disabled — and warns when a commit touches tooling source paths (skills/, commands/, agents/, hooks/, bin/, scripts/, Makefile) without touching any *.md. That hook is non-blocking; the gate above is.

Reasoning Budget

Control Claude’s reasoning effort per phase (the “reasoning sandwich” pattern — high reasoning for planning/verification, standard for implementation):

{
  "_workflow": {
    "reasoning_budget": {
      "planning": "high",
      "coding": "standard",
      "testing": "high"
    }
  }
}

See Token Monitoring & Budget System for the full per-phase default table and how reasoning levels are applied.

What Gets Created

Artifact	Where	Labels
Commits	Feature branch (conventional commit format)	—
Chunk reports	GitHub Issues	`warp-drive`
Session summary	GitHub Issue	`session-summary`, `warp-drive`
Lessons learned	GitHub Issues	`lesson`, `warp-drive`
Decisions made	GitHub Issues	`decision`, `warp-drive`
Deferred bugs	GitHub Issues	`bug-deferred`, `warp-drive`
TODO (timeouts)	GitHub Issues	`todo`, `warp-drive`
Abort reports	GitHub Issues	`warp-drive`, `session-summary`
PR (Level 2)	GitHub PR via `gh pr create`	—

GitHub labels are created automatically on first run (warp-drive, lesson, decision, risk, bug-deferred, session-summary).

Recovery

If a session is lost (crash, worktree deletion, etc.), use the disaster recovery CLI:

# Check current state
~/.claude/scripts/lib/cdr.sh status
 
# Re-initialize tooling (clone from remote, re-run cdi)
~/.claude/scripts/lib/cdr.sh recover /path/to/project
 
# Emergency state reset (deletes warp-drive state file)
~/.claude/scripts/lib/cdr.sh reset /path/to/project

Commit hash recovery

Warp-drive records commit hashes in the state file (commit_hashes[]). If the state file survives but the worktree is lost, cherry-pick commits from the remote:

git fetch origin
git cherry-pick <hash1> <hash2> ...

Preflight check

Run the preflight checker to verify all dependencies are installed:

~/.claude/scripts/lib/preflight-check.sh

This checks: jq, node, git, gh auth, hook file existence, and core scripts.

Troubleshooting

”Automation level must be 2 or 3”

Run /automation level 2 inside Claude Code first. This sets up permissions in .claude/settings.local.json.

”Must not be on main/master”

Run /start-work to create a feature branch (Level 2), or let Level 3 auto-create one.

Warp-drive won’t start — “Active session exists”

A previous session didn’t clean up. Check if it’s stale:

warp status

If stale, reset it:

warp stop --hard

Commit blocked — “only allowed during committing phase”

The gate hook is working correctly. Claude tried to commit outside the committing phase. This usually means a phase was skipped. Check the state:

warp log

Can’t exit Claude Code — “report is missing”

The stop hook blocks exit when a commit was made but no chunk report was filed. Tell Claude to file the report, or if you need to force exit, kill the terminal.

Doom loop warning

Claude keeps editing the same file. The edit tracker caught it. This usually means the approach isn’t working. Claude should try an alternative strategy or escalate.

State file is corrupted

warp stop --hard

This deletes the state file. Your code changes are still in the working tree. Start a new session when ready.

warp command not found

Add ~/.claude/bin to your PATH:

echo 'export PATH="$HOME/.claude/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Internals Reference

For contributors and power users.

State File

Location: <project>/.claude/.warp-drive-state.json

This is what state-machine.js init produces (with a few rows populated after the first transitions). Keep this in sync with the state object literal at the bottom of init() in scripts/warp-drive/state-machine.js.

{
  "version": 1,
  "session": {
    "started_at": "2026-05-08T15:56:59.401Z",
    "started_at_epoch": 1778255819402,
    "pid": 51506,
    "level": 3,
    "github_user": "paulirv"
  },
  "phase": "coding",
  "requirement": "42",
  "branch": "feature/issue-42-title",
  "chunk": { "index": 1, "total": 5, "acs": [["AC-01","AC-02"],["AC-03"]] },
  "checklist": {
    "docs_updated": false,
    "tests_passed": false,
    "committed": false,
    "report_filed": false
  },
  "budgets": {
    "phase_started_at": "2026-05-08T15:57:53.487Z",
    "retry_count": 0,
    "coding_cycles": 0
  },
  "aborted": false,
  "edit_counts": { "src/file.ts": 3 },
  "doom_loop_events": [],
  "gates": {
    "code_complete": { "semantic": "diff_relevance_check" },
    "docs_updated":  { "semantic": "ac_count_check" }
  },
  "completed_chunks": [],
  "history": [
    { "phase": "prerequisites", "at": "..." },
    { "phase": "discovering", "at": "...", "from": "prerequisites", "event": "prerequisites_ok" }
  ],
  "metrics": {
    "commits": 0,
    "reports_filed": 0,
    "tests_run": 0,
    "chunks_completed": 0,
    "session_duration_minutes": 0
  },
  "token_usage": {
    "session_total": null,
    "chunk_snapshots": [],
    "current_chunk_started_at": null
  },
  "main_branch": "master",
  "session_branch": null,
  "merge_target": "master",
  "merge_strategy": "ff-only"
}

Fields appear roughly in this order in the file. Notes on the less-obvious ones:

session.started_at_epoch and session.github_user are populated at init; the latter comes from gh api user -q .login (empty string if gh is unauthenticated, which silently disables @mention notifications).
aborted: false flips to true when the engine routes through the aborted phase. Cleanup messaging keys off this flag.
gates is seeded with the two semantic gates (diff_relevance_check, ac_count_check) plus any verification_gates from _workflow config. The targets arrays from config land alongside semantic on the matching event keys.
metrics.session_duration_minutes is updated when the engine writes the state — useful when reporting from warp status.
main_branch / session_branch / merge_target / merge_strategy are populated from ~/.claude/scripts/branch-detect.sh at init and consulted during merging.
After budget_exceeded, budgets gains exceeded_reasons, exceeded_at, and exceeded_from_phase to record the trip.

State Machine CLI

node ~/.claude/scripts/warp-drive/state-machine.js <action> <project-root> [args]

Action	Purpose
`init`	Create new session: `init <root> --level 2 --issue 42 --pid $PPID`
`status`	Show current state (exit 2 if no session)
`transition`	Move phases: `transition <root> <event> [--data '{"key":"val"}']`
`inject`	Get phase context for SessionStart hook
`gate`	Check if an operation is allowed: `gate <root> git_commit`
`verify`	Run verification gates: `verify <root> code_complete`
`abort`	Shorthand for `transition <root> abort`
`reset`	Delete state file immediately

Transition Table

Every phase lists its valid events and where they lead. This matches the TRANSITIONS object in scripts/warp-drive/state-machine.js.

Phase	Event	Next Phase
idle	start	prerequisites
idle	abort	aborted
prerequisites	prerequisites_ok	discovering
prerequisites	abort	aborted
discovering	work_selected	planning
discovering	no_work	session_ending
discovering	abort	aborted
planning	plan_ready	chunking
planning	abort	aborted
chunking	chunks_defined	coding
chunking	abort	aborted
coding	code_complete	updating_docs
coding	abort	aborted
updating_docs	docs_updated	testing
updating_docs	abort	aborted
testing	tests_passed	committing
testing	tests_failed	coding
testing	abort	aborted
committing	committed	reporting
committing	commit_with_doc_gate	doc_drift_check
committing	abort	aborted
doc_drift_check	drift_clean	reporting
doc_drift_check	drift_blocked	coding
doc_drift_check	abort	aborted
reporting	report_filed	chunk_complete
reporting	abort	aborted
chunk_complete	next_chunk	coding
chunk_complete	requirement_done	requirement_complete
chunk_complete	abort	aborted
requirement_complete	merge_ready	merging
requirement_complete	abort	aborted
merging	merged	awaiting_continue
merging	merge_failed	merging
merging	push_failed	merging
merging	abort	aborted
awaiting_continue	continue_yes	discovering
awaiting_continue	continue_no	session_ending
awaiting_continue	abort	aborted
session_ending	session_ended	completed
session_ending	abort	aborted
budget_exceeded	budget_continue	coding
budget_exceeded	budget_abort	aborted
budget_exceeded	abort	aborted
aborted	abort_resolved	completed
aborted	abort_cleanup_failed	completed
aborted	restart	idle

Budget-trigger reasons. When an enforced budget trips, the engine routes the current phase into budget_exceeded and records the reason on state.budgets.exceeded_reasons. The reasons are:

Reason	Source	Default Threshold	Config Key
`phase_timeout`	Phase elapsed too long	30 min	`max_phase_minutes` (+ `phase_timeout_enforcement`)
`retry_exceeded`	Per-chunk retry counter exceeded	5 retries	`max_retries_per_chunk`
`coding_cycles_exceeded`	Code/test cycles for this chunk exceeded	3 cycles	`max_coding_cycles`
`total_chunks_exceeded`	Chunks completed in this session exceeded hard limit	20 chunks	`max_total_chunks`
`session_timeout`	Total session duration exceeded hard limit	480 min	`max_session_minutes`

phase_timeout is only enforced (rather than a soft warning) when phase_timeout_enforcement is block or abort — see Configuration. The other four are always enforced.

🪴 Quartz 4.0

Explorer

warp-drive-guide