@thierrynakoa/fire-flow 12.2.2 → 13.0.1

package/references/issue-to-pr-pipeline.md

@@ -1,150 +1,149 @@
-# Issue-to-PR Automation Pipeline
-
-> **Research basis (v10.0):** GitHub Copilot Workspace, Devin, Jules (Google) — automated
-> issue analysis → branch creation → implementation → PR creation. Industry standard for
-> AI coding agents in 2025-2026. Eliminates manual branch/PR ceremony overhead.
-
----
-
-## Overview
-
-When given a GitHub issue URL or issue description, automatically execute the full
-development lifecycle from analysis through PR creation. This pipeline connects
-Dominion Flow's planning → execution → verification → handoff workflow to GitHub's
-issue/PR system.
-
-**Core principle:** The agent should handle the ceremony (branching, committing, PR creation)
-so the developer focuses on the design decisions.
-
----
-
-## Pipeline Steps
-
-### Step 1: Issue Analysis
-
-```
-INPUT: GitHub issue URL or issue description
-
-IF github_url provided:
-  # Use gh CLI to fetch issue details
-  gh issue view {number} --json title,body,labels,assignees,milestone
-
-EXTRACT:
-  - Title: one-line summary
-  - Requirements: bullet points from issue body
-  - Labels: map to task type (bug→fix, enhancement→feat, etc.)
-  - Acceptance criteria: from issue body or derive from requirements
-  - Scope estimate: SIMPLE | MODERATE | COMPLEX (from difficulty router)
-```
-
-### Step 2: Branch Creation
-
-```
-# Create feature branch from current base
-branch_name = "{type}/{issue-number}-{slugified-title}"
-  Examples:
-    fix/42-login-timeout
-    feat/123-dark-mode
-    refactor/87-auth-middleware
-
-git checkout -b {branch_name}
-```
-
-### Step 3: Planning (Delegate to /fire-2-plan)
-
-```
-# Auto-generate plan from issue requirements
-/fire-2-plan {issue_number} --from-issue
-
-# Plan should reference:
-- Issue URL as source
-- Acceptance criteria as must-haves
-- Labels as task type hints
-```
-
-### Step 4: Execution (Delegate to /fire-3-execute)
-
-```
-# Execute the plan
-/fire-3-execute {phase} --auto-continue
-
-# On completion, all commits are on the feature branch
-```
-
-### Step 5: PR Creation
-
-```
-# Push branch
-git push -u origin {branch_name}
-
-# Create PR with structured body
-gh pr create \
-  --title "{type}: {issue title}" \
-  --body "$(cat <<'EOF'
-## Summary
-{1-3 bullet points from plan accomplishments}
-
-## Changes
-{files created/modified list from handoff}
-
-## Test Plan
-{verification results from fire-4-verify}
-
-## Issue
-Closes #{issue_number}
-
----
-Generated by Dominion Flow v10.0
-EOF
-)"
-
-# Link PR to issue
-gh issue comment {issue_number} --body "PR created: #{pr_number}"
-```
-
----
-
-## Integration with Dominion Flow Commands
-
-| Command | Role in Pipeline |
-|---------|-----------------|
-| `/fire-2-plan` | Generates BLUEPRINT from issue requirements |
-| `/fire-3-execute` | Implements the plan on feature branch |
-| `/fire-4-verify` | Validates implementation meets acceptance criteria |
-| `/fire-5-handoff` | Creates handoff with PR link and issue reference |
-
----
-
-## Usage
-
-```bash
-# Full pipeline from issue URL
-/fire-issue-to-pr https://github.com/owner/repo/issues/42
-
-# From issue number (assumes current repo)
-/fire-issue-to-pr 42
-
-# Scan-only (analyze issue, create plan, don't implement)
-/fire-issue-to-pr 42 --plan-only
-```
-
----
-
-## Safety Checks
-
-1. **Before branching:** Verify clean working directory (`git status`)
-2. **Before pushing:** Run full verification (`/fire-4-verify`)
-3. **Before PR:** Check branch is ahead of base (`git log base..HEAD`)
-4. **PR body:** Always include "Closes #N" for automatic issue closing
-5. **Labels:** Copy relevant labels from issue to PR
-
----
-
-## References
-
-- **Copilot Workspace:** GitHub's issue-to-PR pipeline (2025)
-- **Devin:** Cognition's autonomous issue resolution (2025-2026)
-- **Jules:** Google's issue-to-PR agent (2026)
-- **Related:** `commands/fire-2-plan.md` — plan generation
-- **Related:** `commands/fire-3-execute.md` — plan execution
-- **Related:** `commands/fire-4-verify.md` — verification
+# Issue-to-PR Automation Pipeline
+
+> issue analysis → branch creation → implementation → PR creation. Industry standard for
+> AI coding agents in 2025-2026. Eliminates manual branch/PR ceremony overhead.
+
+---
+
+## Overview
+
+When given a GitHub issue URL or issue description, automatically execute the full
+development lifecycle from analysis through PR creation. This pipeline connects
+Dominion Flow's planning → execution → verification → handoff workflow to GitHub's
+issue/PR system.
+
+**Core principle:** The agent should handle the ceremony (branching, committing, PR creation)
+so the developer focuses on the design decisions.
+
+---
+
+## Pipeline Steps
+
+### Step 1: Issue Analysis
+
+```
+INPUT: GitHub issue URL or issue description
+
+IF github_url provided:
+  # Use gh CLI to fetch issue details
+  gh issue view {number} --json title,body,labels,assignees,milestone
+
+EXTRACT:
+  - Title: one-line summary
+  - Requirements: bullet points from issue body
+  - Labels: map to task type (bug→fix, enhancement→feat, etc.)
+  - Acceptance criteria: from issue body or derive from requirements
+  - Scope estimate: SIMPLE | MODERATE | COMPLEX (from difficulty router)
+```
+
+### Step 2: Branch Creation
+
+```
+# Create feature branch from current base
+branch_name = "{type}/{issue-number}-{slugified-title}"
+  Examples:
+    fix/42-login-timeout
+    feat/123-dark-mode
+    refactor/87-auth-middleware
+
+git checkout -b {branch_name}
+```
+
+### Step 3: Planning (Delegate to /fire-2-plan)
+
+```
+# Auto-generate plan from issue requirements
+/fire-2-plan {issue_number} --from-issue
+
+# Plan should reference:
+- Issue URL as source
+- Acceptance criteria as must-haves
+- Labels as task type hints
+```
+
+### Step 4: Execution (Delegate to /fire-3-execute)
+
+```
+# Execute the plan
+/fire-3-execute {phase} --auto-continue
+
+# On completion, all commits are on the feature branch
+```
+
+### Step 5: PR Creation
+
+```
+# Push branch
+git push -u origin {branch_name}
+
+# Create PR with structured body
+gh pr create \
+  --title "{type}: {issue title}" \
+  --body "$(cat <<'EOF'
+## Summary
+{1-3 bullet points from plan accomplishments}
+
+## Changes
+{files created/modified list from handoff}
+
+## Test Plan
+{verification results from fire-4-verify}
+
+## Issue
+Closes #{issue_number}
+
+---
+Generated by Dominion Flow v10.0
+EOF
+)"
+
+# Link PR to issue
+gh issue comment {issue_number} --body "PR created: #{pr_number}"
+```
+
+---
+
+## Integration with Dominion Flow Commands
+
+| Command | Role in Pipeline |
+|---------|-----------------|
+| `/fire-2-plan` | Generates BLUEPRINT from issue requirements |
+| `/fire-3-execute` | Implements the plan on feature branch |
+| `/fire-4-verify` | Validates implementation meets acceptance criteria |
+| `/fire-5-handoff` | Creates handoff with PR link and issue reference |
+
+---
+
+## Usage
+
+```bash
+# Full pipeline from issue URL
+/fire-issue-to-pr https://github.com/owner/repo/issues/42
+
+# From issue number (assumes current repo)
+/fire-issue-to-pr 42
+
+# Scan-only (analyze issue, create plan, don't implement)
+/fire-issue-to-pr 42 --plan-only
+```
+
+---
+
+## Safety Checks
+
+1. **Before branching:** Verify clean working directory (`git status`)
+2. **Before pushing:** Run full verification (`/fire-4-verify`)
+3. **Before PR:** Check branch is ahead of base (`git log base..HEAD`)
+4. **PR body:** Always include "Closes #N" for automatic issue closing
+5. **Labels:** Copy relevant labels from issue to PR
+
+---
+
+## References
+
+- **Copilot Workspace:** GitHub's issue-to-PR pipeline (2025)
+- **Devin:** Cognition's autonomous issue resolution (2025-2026)
+- **Jules:** Google's issue-to-PR agent (2026)
+- **Related:** `commands/fire-2-plan.md` — plan generation
+- **Related:** `commands/fire-3-execute.md` — plan execution
+- **Related:** `commands/fire-4-verify.md` — verification

package/references/metrics-and-trends.md

@@ -56,11 +56,10 @@ metrics:
 
 ### Per-Iteration Turn Rewards (v6.0 — AgentPRM)
 
-> **Research basis:** AgentPRM (Feb 2025) — Process reward models score each turn,
 > enabling fine-grained learning signals beyond binary success/fail.
 
 ```yaml
-## Turn-Level Metrics (collected in fire-flow.local.md per loop session)
+## Turn-Level Metrics (collected in dominion-flow.local.md per loop session)
 iteration_rewards:
   - iteration: 1
     reward: 4.2

package/references/research-improvements.md

@@ -1,110 +1,6 @@
-# Research-Backed Improvements Reference
+# Research Improvements
 
-> Dominion Flow v3.2 — Research sources, gap analysis findings, and implementation mapping
->
-> Every v3.2 enhancement cites a tag from this document (e.g., `GAP-1`, `RECITATION-1`).
-> Use this file to trace any inline comment back to its research basis.
+Research citations have been removed from the public release.
 
----
-
-## Research Sources (2024–2026)
-
-### Academic Papers
-
-| ID | Paper | Key Finding | Applied In |
-|----|-------|-------------|------------|
-| PLAN-DEBUG-1 | MapCoder (ACL 2024) — "Multi-Agent Code Generation through Planning" | Achieved 93.9% pass@1 by feeding the Debugging Agent the original plan alongside buggy code. Plan-derived debugging significantly outperforms debugging without plan context because the agent can compare "what was intended" vs "what happened." | `/fire-debug` Step 4: `<plan_context>` block |
-| RECITATION-1 | Manus AI — Context Engineering (2025) | Without task recitation, agents drift off-topic after ~50 tool calls. Rewriting a compressed todo at the end of context keeps the current plan in the model's recent attention span, preventing the "lost-in-the-middle" problem (transformer attention bias toward recent tokens). | `/fire-loop` Step 7 rule 6, iteration context injection |
-| OBSERVE-1 | Mastra — Observational Memory (2025) | Two-agent (Observer/Reflector) compression achieves 5-40x compression with 10x cost reduction over RAG. Observer extracts key facts; Reflector synthesizes patterns. | Future: Tier 2 enhancement |
-| JUDGE-1 | Mason (2026) — "Judge Agent Separation" | Dedicated Judge agent that only evaluates (never generates) prevents self-evaluation bias. Separating generation from evaluation improves quality scoring accuracy. | Future: Tier 3 enhancement |
-| SWE-1 | SWE-Bench Pro (2025) | Single agent + retries outperforms multi-agent swarms for most routine tasks. Multi-agent overhead only justified for genuinely parallel work. | Informs execution mode intelligence (SWARM threshold) |
-| METR-1 | METR Study (2025) — "AI Impact on Developer Productivity" | AI can slow experienced devs 19% on familiar code. AI excels at exploration and unfamiliar codebases, not well-known code. | Informs when to apply AI vs manual work |
-| RLCR-1 | MIT RLCR (2025) — "Confidence-Based Escalation" | Route low-confidence items to human review instead of auto-deciding. Confidence thresholds improve decision quality across automated workflows. | Future: Tier 2 enhancement |
-
-### Community Patterns
-
-| ID | Source | Pattern | Applied In |
-|----|--------|---------|------------|
-| CNCF-1 | CNCF Four Pillars (2025) | Golden Paths, Guardrails, Safety Nets, Manual Review — taxonomy for organizing validation checklists by enforcement level. | Future: restructure 70-point checklist |
-| BOLT-1 | Bolt.new — .powerignore (2025) | File-level exclusion patterns prevent context pollution from generated files, node_modules, etc. | v3.0: `.powerignore` in context engineering |
-| RALPH-1 | Ralph Wiggum Loops — Circuit Breaker Fork | Stall/spin/degradation detection with automatic recovery. Prevents infinite loops and wasted iterations. | v3.0: Circuit Breaker system |
-| REPLIT-1 | Replit Agent — Decision-Time Guidance (2025) | Micro-inject relevant skills at the moment of decision rather than front-loading all knowledge. Reduces context bloat while maintaining quality. | v3.0: DTG system |
-
----
-
-## Gap Analysis Findings
-
-> Internal analysis of Dominion Flow v3.1 identified these gaps.
-> Each gap has a severity, the v3.2 fix applied, and the file modified.
-
-### GAP Series (Structural Gaps)
-
-| ID | Gap Description | Severity | v3.2 Fix | File Modified |
-|----|----------------|----------|----------|---------------|
-| GAP-1 | No explicit decision log — architectural decisions scattered across handoffs and CONSCIENCE.md with no central tracking | HIGH | Created `DECISION_LOG.md` template with DEC-XXX format, cross-phase impact tracking, and integration points | `templates/DECISION_LOG.md` (new) |
-| GAP-2 | Assumptions accumulate across phases without systematic tracking — Phase 6 can contradict Phase 1 assumptions | HIGH | Enhanced `ASSUMPTIONS.md` with cross-phase contradiction detection, phase-gate validation protocol | `templates/ASSUMPTIONS.md` |
-| GAP-3 | No cross-phase contradiction detection for decisions | MEDIUM | Decision Log includes "Affected Phases" and cross-phase validation protocol | `templates/DECISION_LOG.md` |
-| GAP-4 | Deferred items multiply without compound impact tracking | MEDIUM | Added deferred-item impact analysis template (DEFERRED-XXX format) to Assumptions | `templates/ASSUMPTIONS.md` |
-| GAP-5 | Handoff completeness not validated — broken context chains if any session skips proper handoff | HIGH | Added 17-point automated validation checklist as Step 5 in handoff command | `commands/fire-5-handoff.md` |
-| GAP-6 | Task recitation missing — agents drift after many iterations in fire-loop | HIGH | Added recitation pattern to iteration context injection with compressed todo rewrite | `commands/fire-loop.md` |
-| GAP-7 | Debug loops lack plan context — debugger can't compare intended vs actual behavior | MEDIUM | Added `<plan_context>` block to debugger spawn and continuation prompts | `commands/fire-debug.md` |
-| GAP-8 | CONSCIENCE.md doesn't reference Decision Log | LOW | Added Decision Log reference and Assumptions Health section to state template | `templates/state.md` |
-| GAP-9 | Handoff success criteria don't include Decision Log or Assumptions sync | LOW | Added 3 new items to handoff success criteria | `commands/fire-5-handoff.md` |
-| GAP-10 | No executable handoff validation — relies on manual review | HIGH | 17-point checklist with structural, content, and cross-reference checks | `commands/fire-5-handoff.md` |
-
-### BLIND-SPOT Series (Discovered During Analysis)
-
-| ID | Blind Spot | Impact | v3.2 Fix |
-|----|-----------|--------|----------|
-| BLIND-SPOT-A | Decisions made in one phase can silently conflict with decisions from earlier phases | Cross-phase bugs, wasted work | Decision Log cross-phase validation protocol |
-| BLIND-SPOT-B | Unvalidated assumptions from early phases relied upon in later phases without re-check | Architecture built on unverified foundations | Phase-gate validation: mandatory assumption audit at phase start |
-| BLIND-SPOT-C | Context drift in long fire-loop runs leads to repeated mistakes and circular attempts | Wasted iterations, degraded solutions | Task recitation pattern forces model to re-read compressed state |
-| BLIND-SPOT-D | Handoff chain breaks permanently if one session skips proper handoff | Complete context loss, restart required | Automated completeness validation prevents saving incomplete handoffs |
-
----
-
-## Implementation Mapping
-
-### Tier 1 — Implemented in v3.2.0
-
-| Enhancement | Research Basis | Files Changed |
-|-------------|---------------|---------------|
-| Decision Log template | GAP-1, GAP-3, BLIND-SPOT-A | `templates/DECISION_LOG.md` (new) |
-| Assumptions Registry enhancement | GAP-2, GAP-4, BLIND-SPOT-B | `templates/ASSUMPTIONS.md` |
-| CONSCIENCE.md Decision/Assumptions references | GAP-8 | `templates/state.md` |
-| Handoff Completeness Validator | GAP-5, GAP-9, GAP-10, BLIND-SPOT-D | `commands/fire-5-handoff.md` |
-| Task Recitation Pattern | RECITATION-1, GAP-6, BLIND-SPOT-C | `commands/fire-loop.md` |
-| Plan-Aware Debugging | PLAN-DEBUG-1, GAP-7 | `commands/fire-debug.md` |
-| Plugin version bump + this doc | — | `plugin.json`, `references/research-improvements.md` |
-
-### Tier 2 — Planned for v3.3.0
-
-| Enhancement | Research Basis | Target |
-|-------------|---------------|--------|
-| Observational Memory (Observer/Reflector agents) | OBSERVE-1 | Handoff compression, cross-session learning |
-| Confidence-Based Escalation | RLCR-1 | Route uncertain decisions to user during execution |
-| CNCF Four Pillars restructure | CNCF-1 | Reorganize 70-point checklist by enforcement level |
-| METR-aware task routing | METR-1 | Route AI to exploration tasks, manual for familiar code |
-
-### Tier 3 — Planned for v3.4.0
-
-| Enhancement | Research Basis | Target |
-|-------------|---------------|--------|
-| Judge Agent separation | JUDGE-1 | Dedicated evaluation agent for verification |
-| SWE-Bench calibrated execution modes | SWE-1 | Better SWARM vs SEQUENTIAL thresholds |
-| Skills Library auto-pruning | Community patterns | Remove unused skills, version popular ones |
-
----
-
-## Version History
-
-| Version | Date | Key Additions |
-|---------|------|---------------|
-| v3.0.0 | 2026-02-09 | Dominion Flow consolidation, Circuit Breaker, Error Classification, Context Engineering, DTG |
-| v3.1.0 | 2026-02-10 | Playwright E2E testing (Step 8), 70-point validation, visual regression |
-| v3.2.0 | 2026-02-10 | Research-backed: Task Recitation, Plan-Aware Debug, Decision Log, Assumptions enhancement, Handoff Validator, Code Comments Standard |
-
----
-
-*Created: 2026-02-10*
-*Source: 4-agent parallel research sweep (15 papers + 15 community patterns + 10 testing findings + 10 internal gaps)*
+See the methodology skill for how research-backed upgrades work:
+`skills-library/_general/methodology/RESEARCH_BACKED_WORKFLOW_UPGRADE.md`

package/references/sdlc-mapping.md

@@ -0,0 +1,73 @@
+# SDLC Flowchart → Dominion Flow Mapping
+
+Source: Greg Balajewicz's generic SDLC flowchart (3-page swimlane diagram)
+
+---
+
+## SDLC Structure
+
+```
+Page 1: DEV PROCESS (Devs lane)
+  Feature branch → unit test → merge develop into feature → integration test
+  → "All works?" gate → discuss with team → wait for develop readiness
+  → PR merge → deploy to DEV → go to QA
+
+Page 2: QA/RELEASE PROCESS (QA + DevOps lanes)
+  Refresh QA from prod → cut release branch → smoke test → full QA testing
+  → "Bugs found?" loop (fix → retest → re-assess scope → continue)
+  → QA sign-off → refresh staging from prod → test staging
+  → "Bugs found on staging?" → go BACK to QA (never fix on staging)
+  → release to prod → sanity check
+
+Page 3: POST-PROD (Devs lane)
+  Check error logs → check perf logs → done
+```
+
+---
+
+## Key SDLC Patterns and Dominion Flow Equivalents
+
+| SDLC Pattern | Dominion Flow Equivalent | Status |
+|-------------|------------------------|--------|
+| Feature branch + unit test | `/fire-3-execute` (breath execution) | Strong |
+| "All works?" gate | Must-haves verification | Strong |
+| Merge to develop via PR | Atomic commits per task | Strong |
+| QA testing + bug loop | `/fire-4-verify` (70-point) | Improved v11.3 |
+| "Assess scope of retest" | Scope-adaptive checklist (v11.3) | Added v11.3 |
+| "No fixes on staging" | Verifier isolation (fresh instance) | Strong |
+| "Bugs found?" → fix → retest | Recovery research loop | Improved v11.3 |
+| Post-prod: error/perf logs | Not yet implemented | Future |
+| Branch readiness gate | Phase dependency gates | Strong |
+| Sanity check on prod | Post-deploy verification | Future |
+
+---
+
+## Critical SDLC Insight: The "Bugs Found?" Diamond
+
+The most important shape on the SDLC chart is the "Bugs found?" diamond. It appears at:
+- DEV: "All works?" → No → loop back to fix
+- QA: "Bugs found?" → Yes → fix → retest (scoped, not full regression)
+- Staging: "Bugs found?" → Yes → go BACK to QA (never fix on staging)
+
+**The diamond is a roundabout, not a stop sign.**
+
+In Dominion Flow v11.3, this maps to:
+- Circuit breaker trip → spawn fire-researcher → get alternatives → re-plan → retry
+- Verification FAIL → recovery research → re-plan with different approach → re-execute
+- Low confidence → research first → then proceed with givens
+
+---
+
+## SDLC Rules Applied to Dominion Flow
+
+1. **"No fixes on staging"** = Verifier runs in isolation. If it finds bugs, it sends you BACK to execute (via re-plan), never patches in place.
+
+2. **"Assess scope of retest"** = 70-point checklist is scope-adaptive. Backend change? Skip E2E/mobile/bundle checks. Config change? Minimal verification.
+
+3. **"Bugs found? → fix → retest loop"** = Circuit breaker trips route to fire-researcher, not just escalation. The loop continues until resolved or max attempts exhausted.
+
+4. **"Post-prod monitoring"** = Future: add error log + perf check step after deployment.
+
+---
+
+*Reference for Dominion Flow architecture decisions. Source: github.com/GregBalajewicz/SDLC-flow-chart*

package/references/state-machine.md

@@ -0,0 +1,151 @@
+# Phase Transition State Machine
+
+> Formal state diagram governing Dominion Flow phase lifecycle. Every phase must follow these transitions — no skipping, no shortcuts.
+---
+
+## State Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> INITIALIZED: /fire-1a-new
+
+    INITIALIZED --> PLANNING: /fire-2-plan {phase}
+    PLANNING --> PLAN_APPROVED: User approves blueprint
+    PLANNING --> INITIALIZED: User rejects plan
+
+    PLAN_APPROVED --> EXECUTING: /fire-3-execute {phase}
+    PLAN_APPROVED --> PLANNING: Plan revision needed
+
+    EXECUTING --> EXECUTION_PAUSED: Context limit / circuit breaker
+    EXECUTING --> EXECUTION_BLOCKED: Unresolvable blocker
+    EXECUTING --> VERIFYING: All breaths complete
+
+    EXECUTION_PAUSED --> EXECUTING: /fire-6-resume
+    EXECUTION_PAUSED --> HANDOFF: /fire-5-handoff
+
+    EXECUTION_BLOCKED --> PLANNING: Re-plan required
+    EXECUTION_BLOCKED --> DEBUGGING: /fire-debug
+
+    DEBUGGING --> EXECUTING: Fix applied, resume
+    DEBUGGING --> PLANNING: Architectural issue found
+
+    VERIFYING --> VERIFICATION_FAILED: Score < 70%
+    VERIFYING --> COMPLETE: Score ≥ 70% + all must-haves pass
+
+    VERIFICATION_FAILED --> EXECUTING: Fix failed checks
+    VERIFICATION_FAILED --> PLANNING: Fundamental design issue
+
+    COMPLETE --> HANDOFF: /fire-5-handoff
+    COMPLETE --> [*]: Project finished
+
+    HANDOFF --> INITIALIZED: /fire-6-resume (new session)
+```
+
+---
+
+## States
+
+| State | Description | Entry Command | Valid Exits |
+|-------|-------------|---------------|-------------|
+| **INITIALIZED** | Project created, no planning done | `/fire-1a-new` | PLANNING |
+| **PLANNING** | Blueprint being created for a phase | `/fire-2-plan` | PLAN_APPROVED, INITIALIZED |
+| **PLAN_APPROVED** | Blueprint approved, ready to execute | User approval | EXECUTING, PLANNING |
+| **EXECUTING** | Code being written in breaths | `/fire-3-execute` | VERIFYING, EXECUTION_PAUSED, EXECUTION_BLOCKED |
+| **EXECUTION_PAUSED** | Stopped mid-execution (context limit, break) | Circuit breaker / manual | EXECUTING, HANDOFF |
+| **EXECUTION_BLOCKED** | Unresolvable issue during execution | Error escalation | PLANNING, DEBUGGING |
+| **DEBUGGING** | Active investigation of a blocker | `/fire-debug` | EXECUTING, PLANNING |
+| **VERIFYING** | Running 70-point WARRIOR checklist | `/fire-4-verify` | COMPLETE, VERIFICATION_FAILED |
+| **VERIFICATION_FAILED** | Verification score below threshold | Score < 70% | EXECUTING, PLANNING |
+| **COMPLETE** | Phase verified and approved | Score ≥ 70% | HANDOFF, next phase |
+| **HANDOFF** | Session state saved for continuity | `/fire-5-handoff` | INITIALIZED (new session) |
+
+---
+
+## Transition Guards
+
+Guards are conditions that MUST be true before a transition is allowed.
+
+### PLANNING → PLAN_APPROVED
+- [ ] BLUEPRINT.md exists with all required sections
+- [ ] At least one breath defined with tasks
+- [ ] Skills-to-apply section populated (or explicitly marked "none needed")
+- [ ] User has reviewed and approved the blueprint
+
+### PLAN_APPROVED → EXECUTING
+- [ ] Blueprint has not been modified since approval
+- [ ] No unresolved blockers from previous phases
+- [ ] Required dependencies available (APIs, databases, etc.)
+
+### EXECUTING → VERIFYING
+- [ ] All breaths in the phase have been attempted
+- [ ] No breath is in BLOCKED state without resolution
+- [ ] Build passes (if applicable)
+- [ ] At least one test exists for non-trivial code
+
+### VERIFYING → COMPLETE
+- [ ] Overall verification score ≥ 70%
+- [ ] ALL must-have checks pass (truths, artifacts, key links)
+- [ ] No critical security findings
+- [ ] FaR confidence calibration completed (fact-elicit + reflect)
+
+### EXECUTION_BLOCKED → PLANNING
+- [ ] Blocker documented in debug log
+- [ ] Root cause identified (or explicitly marked "unknown — needs investigation")
+- [ ] Impact assessment: which blueprint tasks are affected
+
+---
+
+## Rollback Paths
+
+When a phase fails verification or hits an unresolvable blocker, these are the safe rollback paths:
+
+| From | To | When | What Happens |
+|------|----|------|-------------|
+| VERIFICATION_FAILED | EXECUTING | Fixable issues (test failures, missing docs) | Re-execute only failed breath tasks |
+| VERIFICATION_FAILED | PLANNING | Design issues (wrong architecture, missing requirements) | Re-plan the phase with lessons learned |
+| EXECUTION_BLOCKED | DEBUGGING | Unknown root cause | Launch `/fire-debug` investigation |
+| EXECUTION_BLOCKED | PLANNING | Known architectural issue | Re-plan with constraint documented |
+| EXECUTING | EXECUTION_PAUSED | Context limit reached | Save state, prepare for `/fire-6-resume` |
+
+---
+
+## State Persistence
+
+Phase state is tracked in `.planning/STATE.md`:
+
+```markdown
+## Current State
+- Phase: {N}
+- State: EXECUTING
+- Entered: 2026-03-06T14:30:00Z
+- Previous: PLAN_APPROVED (2026-03-06T14:15:00Z)
+- Breaths completed: 2/4
+- Next transition: VERIFYING (when all breaths complete)
+```
+
+The handoff cycle (`/fire-5-handoff` → `/fire-6-resume`) preserves state across sessions. The resuming session reads STATE.md to determine exactly where to continue.
+
+---
+
+## Anti-Patterns
+
+These transitions are **explicitly forbidden**:
+
+| Forbidden Transition | Why |
+|---------------------|-----|
+| INITIALIZED → EXECUTING | Cannot execute without a plan |
+| PLANNING → VERIFYING | Cannot verify unbuilt code |
+| EXECUTING → COMPLETE | Cannot skip verification |
+| VERIFICATION_FAILED → COMPLETE | Cannot ignore failed verification |
+| Any state → HANDOFF (without saving) | Must save state before handoff |
+
+---
+
+## Integration
+
+This state machine is enforced by:
+- **`/fire-3-execute`** — Checks current state before starting execution
+- **`/fire-4-verify`** — Only runs if state is EXECUTING with all breaths complete
+- **`/fire-autonomous`** — Follows state machine transitions automatically
+- **`/fire-6-resume`** — Reads STATE.md to determine re-entry point
+- **`/fire-transition`** — Explicit phase transition command with guard validation