@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/references/circuit-breaker.md

@@ -200,7 +200,6 @@ The circuit breaker state is tracked in the loop file:
 
 ### 4. Confidence-Outcome Divergence (v7.0 — Process Reward Hacking Detection)
 
-> **Research basis:** AUQ (Jan 2026) + AgentPRM (Feb 2025) — when step-level confidence
 > rises while actual outcomes degrade, the agent is "reward hacking" — optimizing for
 > feeling confident rather than producing results.
 
@@ -236,7 +235,6 @@ THRESHOLD: CONFIDENCE_OUTCOME_DIVERGENCE
 
 ### 5. KPI Drift Bounds (v11.0 — Agent Behavioral Contracts)
 
-> **Research basis:** ABC: Agent Behavioral Contracts (Feb 2026) — monitoring KPI drift
 > during execution detects when the agent is active but drifting from plan goals.
 > Unlike stall/spin detection, this catches "productive but wrong" behavior.
 
@@ -267,6 +265,99 @@ THRESHOLD: KPI_DRIFT
 
 ---
 
+## Self-Testing Feedback Loop (v10.1)
+
+> agents that run tests after each change attempt and feed failures back into the next
+> iteration achieve 37% higher fix rates. Combined with error classification, this creates
+> a closed feedback loop: change → test → classify result → adjust approach.
+
+### The Loop
+
+After every approach rotation or significant change during WARNING state, the circuit
+breaker enforces a test-feedback cycle:
+
+```
+SELF_TEST_FEEDBACK_LOOP:
+
+  AFTER approach_rotation():
+
+    1. RUN available tests:
+       test_result = run_tests()  # npm test, pytest, etc.
+
+       Priority order:
+         a. Specific failing test (if known from error hash)
+         b. Test file for modified module
+         c. Full test suite (if quick, <30s)
+
+    2. CLASSIFY test result:
+       IF test_result == PASS:
+         → PROGRESS. Clear warning state. New approach works.
+         → Record: "Approach rotation successful: {new_approach}"
+
+       IF test_result == FAIL with NEW error:
+         → PROGRESS. Different error = forward movement.
+         → Feed new error into next iteration context.
+         → Record: "New error after rotation: {new_error_hash}"
+
+       IF test_result == FAIL with SAME error:
+         → SPINNING. Rotation didn't help.
+         → Increment spin counter.
+         → Record: "Rotation ineffective: same error {error_hash}"
+
+       IF test_result == NO_TESTS:
+         → Cannot self-verify. Log warning.
+         → Rely on file-change and output metrics only.
+         → Record: "No tests available — manual verification needed"
+
+    3. FEED BACK into context:
+       Inject test result into next iteration's context:
+
+       "SELF-TEST RESULT after approach rotation:
+        Test: {test_command}
+        Result: {PASS|FAIL}
+        Error (if any): {error_message}
+        Diagnosis: {PROGRESS|SPINNING|NEW_ERROR}
+        Action: {what to do next based on classification}"
+
+    4. ADJUST thresholds:
+       IF self-test shows PROGRESS after rotation:
+         → Reset stall_counter to 0
+         → Reset spin_counter to 0 (new approach succeeded)
+
+       IF self-test shows SPINNING despite rotation:
+         → Double-increment spin_counter (+2 instead of +1)
+         → This accelerates circuit break for approaches that
+           look different but produce the same error
+```
+
+### Integration with Error Classification
+
+```
+The self-testing loop closes the gap between error classification and
+approach rotation:
+
+  BEFORE (v10.0):
+    Error detected → Classify → Rotate approach → Hope it works
+
+  AFTER (v10.1):
+    Error detected → Classify → Rotate approach → Test → Classify result
+                                                     ↓
+                                           Feed back into next iteration
+
+This prevents the "blind rotation" problem where the agent tries
+a different approach but doesn't verify whether it actually fixed
+anything before continuing.
+```
+
+### Skip Conditions
+
+- Skip self-testing if no test runner is detected in the project
+- Skip if the change is documentation-only (no testable code)
+- Skip if circuit breaker state is TRIPPED (we're already stopping)
+- Skip if `--skip-verify` flag is set (user opted out)
+
+---
+
 ## Configuration
 
 ```yaml

package/references/context-engineering.md

@@ -259,6 +259,102 @@ dynamic_exclude(task):
 
 ---
 
+## 3.5 Tiered Context Architecture (v10.1 — Hot/Warm/Cold)
+
+> with hot/warm/cold layers reduces context-related failures by 40%. Agents that explicitly
+> categorize context by access frequency make better compaction decisions and extend useful
+> context life by 60%.
+
+### The Three Tiers
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ HOT CONTEXT (always in window — never compress)         │
+│                                                          │
+│ • Current task description from BLUEPRINT.md             │
+│ • Active error messages (current + last iteration)       │
+│ • Recitation block (rewritten each iteration)            │
+│ • Circuit breaker state + health classification          │
+│ • Failed approaches list (what NOT to do)                │
+│                                                          │
+│ Budget: ~15% of context window (~30K tokens)             │
+├─────────────────────────────────────────────────────────┤
+│ WARM CONTEXT (in window but compressible)                │
+│                                                          │
+│ • Plan context (BLUEPRINT.md — full during execution)    │
+│ • Loaded skills (relevant to current phase)              │
+│ • Recent file contents (read in last 3 iterations)       │
+│ • CONSCIENCE.md decisions (last 5)                       │
+│ • Episodic recall results (top 3 memories)               │
+│ • Shared-state.json (SWARM mode reasoning traces)        │
+│                                                          │
+│ Budget: ~45% of context window (~90K tokens)             │
+│ Compression: When exceeding budget, compress to 50%      │
+├─────────────────────────────────────────────────────────┤
+│ COLD CONTEXT (evicted from window, retrievable)          │
+│                                                          │
+│ • File contents read >5 iterations ago                   │
+│ • Completed task details (summarized to commit hash)     │
+│ • Resolved errors (compressed to one-line summary)       │
+│ • Old iteration history (>5 iterations back)             │
+│ • Skills loaded but never referenced                     │
+│ • Previous breath RECORD.md content                      │
+│                                                          │
+│ Budget: 0 tokens (evicted, saved to disk if needed)      │
+│ Retrieval: Re-read from disk on demand                   │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Tier Assignment Algorithm
+
+```
+assign_tier(context_segment):
+  # HOT — critical for current iteration
+  IF segment.type IN ["current_task", "active_error", "recitation",
+                       "circuit_breaker", "failed_approaches"]:
+    RETURN HOT
+
+  # WARM — useful for current phase
+  IF segment.last_accessed <= 3 iterations ago:
+    RETURN WARM
+  IF segment.type IN ["plan_context", "loaded_skill", "episodic_recall"]:
+    RETURN WARM
+
+  # COLD — no longer actively needed
+  RETURN COLD
+```
+
+### Tier Transitions
+
+| Transition | Trigger | Action |
+|-----------|---------|--------|
+| WARM → HOT | Segment referenced by current task | Promote, protect from compression |
+| WARM → COLD | Not accessed for 5+ iterations | Evict, save summary to disk |
+| COLD → WARM | Re-read from disk (file needed again) | Load back into window |
+| HOT → WARM | Task changes (new breath starts) | Previous task details demote |
+| HOT → COLD | Error resolved + committed | Compress to one-line summary |
+
+### Integration with /fire-cost
+
+The `/fire-cost` command uses tier budgets to generate specific compaction recommendations:
+
+```
+IF /fire-cost reports YELLOW (50-70%):
+  → Compress WARM tier to 50% (keep key points, drop examples)
+
+IF /fire-cost reports ORANGE (70-85%):
+  → Evict all COLD to disk
+  → Compress WARM to 30%
+  → Keep HOT untouched
+
+IF /fire-cost reports RED (85-95%):
+  → Evict COLD + WARM to disk
+  → Keep only HOT context
+  → Trigger /fire-5-handoff recommendation
+```
+
+---
+
 ## Context Budget Tracking
 
 ### Awareness of Context Usage
@@ -337,9 +433,6 @@ Per-task execution:
 ---
 
 ## 4. Compaction Stop-Signal Preservation
-
-> **Research basis (v6.0):** JetBrains "Cutting Through the Noise" (Dec 2025) found that LLM summarization during compaction smooths over stop signals — errors, BLOCKED indicators, and failure counts get lost. This extends agent runs by ~15%, often past the point where they should have stopped.
-
 ### Problem
 
 When context approaches its limit, the system compacts (summarizes) earlier messages. Standard summarization optimizes for coherence, which means it:
@@ -405,7 +498,6 @@ GOOD (after compaction):
 
 ### Actionable Error Preservation Protocol (v10.0)
 
-> **Research basis (v10.0):** Manus AI "Context Engineering for AI Agents" (Feb 2026) —
 > error preservation during context compaction improved recovery rate by preventing
 > repeated failed approaches. Errors are the most valuable context — they tell you
 > what NOT to do.
@@ -455,9 +547,6 @@ tells you what worked (which you can rediscover). An error tells you what NOT to
 ---
 
 ## 5. Difficulty-Aware Routing Tiers (v7.0)
-
-> **Research basis:** Difficulty-Aware Agent Orchestration (Sep 2025) — +11.21% accuracy at 64% cost
-
 Not every task needs the full pipeline. Routing by difficulty saves context and time:
 
 | Tier | Steps Skipped | Token Savings | Example Tasks |
@@ -480,7 +569,6 @@ Not every task needs the full pipeline. Routing by difficulty saves context and
 
 ## 6. Active Context Compression (v10.0 — ACON)
 
-> **Research basis (v10.0):** ACON "Active Context Compression" (2025-2026, score 4.85) —
 > 26-54% token reduction via selective compression. Instead of treating all context equally,
 > ACON scores each context segment by relevance to the current task and compresses
 > low-relevance segments aggressively while preserving high-relevance segments verbatim.
@@ -555,7 +643,6 @@ the output quality degrades more slowly with compressed context.
 
 ### PAACE Integration (Plan-Aware Context)
 
-> **Research basis (v10.0):** PAACE "Plan-Aware Agent Context Engineering" (2025, score 4.70) —
 > context compression should be plan-aware. Segments related to upcoming plan tasks should
 > be preserved even if not currently relevant, because they'll be needed soon.
 
@@ -573,6 +660,135 @@ WHEN compressing context, check BLUEPRINT.md for upcoming tasks:
 
 ---
 
+## 6.5 FoldAgent Context Folding (v13.0 — Cross-Turn Compression)
+
+> reduction via selective cross-turn folding. Unlike ACON (Section 6) which compresses WITHIN
+> a turn's context, FoldAgent folds ACROSS turns — previous turn outputs that are no longer
+> needed for current reasoning are collapsed to a semantic summary.
+
+### Problem
+
+ACON compresses context within the current window, but accumulated turn history still grows
+linearly. After 10+ iterations in fire-loop, previous turns consume 60-80% of context even
+after ACON compression, because ACON preserves recent turns verbatim.
+
+### Solution: Cross-Turn Folding
+
+```
+EVERY 5 iterations (complements ACON's every-3 schedule):
+
+  1. PARTITION turn history into segments:
+     - ACTIVE TURN:    current iteration (NEVER fold)
+     - RECENT TURNS:   last 2 iterations (preserve verbatim)
+     - FOLDABLE TURNS: iterations 3+ ago
+
+  2. FOR each FOLDABLE turn:
+     CLASSIFY content:
+       DECISION:   architectural choice, API contract, naming convention
+                   → FOLD to: "{decision}: {choice} (iter {N})" (~20 tokens)
+       ERROR:      error message + resolution
+                   → FOLD to: "Resolved: {error_type} in {file} — {fix}" (~15 tokens)
+       FILE_READ:  file contents read for reference
+                   → FOLD to: "Read {file} ({lines} lines)" (~5 tokens)
+       CODE_WRITE: implementation output
+                   → FOLD to: "Wrote {file}: {summary}" (~10 tokens)
+       EXPLORATORY: searches, reads that led nowhere
+                   → FOLD to: nothing (evict entirely)
+
+  3. REPLACE foldable turns with folded summaries
+     Savings: ~92% reduction on folded turns (from paper's reported results)
+
+  4. PRESERVE in full (never fold):
+     - Current playbook entries (Step 3.25)
+     - Active error messages (current + last turn)
+     - Circuit breaker state
+     - Failed approaches list
+```
+
+### Folding Schedule (Combined with ACON)
+
+```
+Iteration 3:  ACON compression (within-turn)
+Iteration 5:  FoldAgent folding (cross-turn) + ACON
+Iteration 6:  ACON compression
+Iteration 9:  ACON compression
+Iteration 10: FoldAgent folding + ACON
+Iteration 12: ACON compression
+Iteration 15: FoldAgent folding + ACON
+...
+
+Combined effect:
+  WITHOUT either:  ~15 iterations before rot
+  WITH ACON only:  ~25 iterations before rot
+  WITH ACON+Fold:  ~35-40 iterations before rot
+```
+
+### Integration with Sabbath Rest
+
+FoldAgent extends the pre-Sabbath-Rest runway by an additional 40-60% beyond ACON alone.
+The combined ACON+Fold pipeline means most phases complete before Sabbath Rest triggers.
+
+---
+
+## 7. Variation Injection (v13.0 — Attention Loop Breaking)
+
+> breaks attention loops when agents get stuck repeating the same patterns. Deliberate
+> perturbation of context forces the model to explore different solution paths.
+
+### Problem
+
+When an agent is stuck (FIXATION or SPINNING state), the context itself becomes the trap.
+The same prompt structure, same file contents, same error messages create an attention loop
+where the model keeps producing the same output. Standard approach rotation ("try something
+different") doesn't work because the context still primes the old approach.
+
+### Solution: Inject Variation Into Context
+
+```
+WHEN execution health is SPINNING or FIXATION (from Step 3.6):
+
+  BEFORE retrying the task, inject ONE of these variations:
+
+  1. REFRAME — Restate the task from a different perspective:
+     Original: "Add authentication middleware to Express routes"
+     Reframed: "What would a security audit find missing in these routes?"
+
+  2. CONSTRAINT FLIP — Add or remove a constraint:
+     Original: "Use JWT tokens for session management"
+     Variation: "What if sessions were stateless? What if we used cookies instead?"
+     → This isn't changing the requirement, it's forcing the model to
+        consider alternatives before returning to the original constraint
+
+  3. EXEMPLAR SWAP — Replace the reference pattern:
+     Original: looked at auth middleware in src/middleware/auth.ts
+     Variation: look at a DIFFERENT middleware (e.g., rate-limiter) for structural patterns
+     → Same problem, different reference material breaks the attention loop
+
+  4. SCALE SHIFT — Change the scope temporarily:
+     Original: "Implement the full auth flow"
+     Variation: "Just make ONE route work with hardcoded credentials"
+     → Smaller scope often reveals the actual blocker
+
+  SELECT variation type based on stuck classification:
+    FIXATION → REFRAME or EXEMPLAR SWAP (break the mental model)
+    SPINNING → CONSTRAINT FLIP or SCALE SHIFT (break the approach)
+```
+
+### Integration Points
+
+| Trigger | Variation Applied |
+|---------|------------------|
+| Step 3.5 circuit breaker at WARNING | Inject variation before retry |
+| Step 3.6 SPINNING classification | MANDATORY variation before next attempt |
+| Step 3.6 FIXATION classification | MANDATORY variation before next attempt |
+| Articulation Protocol (3.5.6) self-resolves | No variation needed (articulation was enough) |
+
+### Anti-Pattern: Random Variation
+
+Don't inject variation randomly or on healthy execution. Variation injection is a **recovery mechanism**, not a creativity tool. Healthy execution should follow the plan directly.
+
+---
+
 ## References
 
 - **Recitation:** Manus AI "todo.md rewrite" pattern (restate plan each iteration)
@@ -585,3 +801,5 @@ WHEN compressing context, check BLUEPRINT.md for upcoming tasks:
 - **Active forgetting:** Focus (ACL 2025) — proactively drop irrelevant context
 - **Related:** `references/circuit-breaker.md` — output decline threshold uses context awareness
 - **Related:** `references/error-classification.md` — DEGRADED state is context-rot driven
+- **Variation injection:** Manus AI (Jul 2025) — deliberate context perturbation breaks attention loops
+- **Cross-turn folding:** FoldAgent/FoldGRPO (Feb 2025) — 92% reduction via selective cross-turn compression

package/references/honesty-protocols.md

@@ -298,7 +298,76 @@ Every agent using Dominion Flow commits to:
 3. **Ask for help rather than fake competence**
 4. **Document what you don't know, not just what you do**
 5. **Treat the user's codebase with respect it deserves**
+6. **Accept mistakes immediately — never pass blame to previous instances, the user, or external tools**
+7. **Encourage honesty in other agents** — if a downstream agent's output seems dishonest, flag it
 
 ---
 
-*Honesty isn't about being perfect. It's about being trustworthy.*
+## Honesty Gate — Universal Enforcement (v11.2)
+
+> **This is the single most impactful feature in the WARRIOR methodology.** It prevents the #1 failure mode of AI agents: confidently wrong execution that wastes hours before anyone notices.
+
+### The Gate
+
+The Honesty Gate is a **mandatory checkpoint** — not a suggestion. Every agent MUST pass through it before producing output. It is wired into:
+
+| Agent | Gate Location | What Gets Checked |
+|-------|-------------|-------------------|
+| fire-planner | Step 2 (before planning) | "Do I know enough to plan this? What am I assuming?" |
+| fire-executor | Before each breath | "Am I confident in this implementation? What could go wrong?" |
+| fire-verifier | Before scoring | "Am I rubber-stamping or actually verifying? Would I bet on this?" |
+| fire-researcher | Before recommending | "Is this research thorough or am I settling for first result?" |
+| fire-vision-architect | Before generating branches | "Am I recommending what fits, or what I know?" |
+
+### Why This Works
+
+1. **Acceptance over blame** — When Claude admits "I don't know how to do X" instead of faking it, the user gets truth in 5 seconds instead of discovering a broken implementation 2 hours later
+2. **Compounding trust** — Each honest checkpoint builds confidence. The user learns to trust Claude's "done" because Claude's "I'm stuck" was always honest too
+3. **Faster debugging** — Honest uncertainty markers in code comments and handoffs mean the NEXT instance knows exactly where the risk is
+4. **Better handoffs** — WARRIOR handoffs that admit "this part is untested" are 10x more useful than ones that claim everything works
+
+### Anti-Patterns the Gate Prevents
+
+| Without Honesty Gate | With Honesty Gate |
+|---------------------|-------------------|
+| "Done!" (but tests are skipped) | "Done — 47 tests pass, 3 edge cases untested (documented)" |
+| Silently picks familiar stack | "I recommend Next.js because it fits, not because it's my default" |
+| Hides error, works around it | "Hit error X. Tried A and B. Recommending C because..." |
+| Blames previous Claude instance | "Previous approach failed. Here's what I'll do differently and why" |
+| Claims 100% confidence | "90% confident on core logic, 60% on edge cases — here's why" |
+
+### Wiring the Gate into New Agents
+
+Every new agent created for Dominion Flow MUST include:
+
+```markdown
+<honesty_protocol>
+
+## Honesty Gate (WARRIOR Foundation — MANDATORY)
+
+Before producing output, answer The Three Questions:
+
+### Q1: What do I KNOW?
+### Q2: What DON'T I know?
+### Q3: Am I tempted to FAKE or RUSH this?
+
+If Q3 = yes → STOP → Address it → Then proceed
+
+</honesty_protocol>
+```
+
+This is not optional. This is not a nice-to-have. **This is the foundation.**
+
+### Handoff Integration
+
+The Honesty Gate feeds directly into session handoffs:
+
+- **Honest admissions** are captured so the next instance doesn't repeat failures
+- **Honest uncertainty** is documented so solutions are captured once resolved
+- **Honest assumptions** are validated and become project conventions
+
+This creates a **compounding honesty effect**: each session is more honest than the last because it reads the previous session's honest admissions.
+
+---
+
+*Honesty isn't about being perfect. It's about being trustworthy. The agent that says "I don't know" saves more time than the one that says "done" and isn't.*