@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/methodology/DIFFICULTY_AWARE_AGENT_ROUTING.md

@@ -0,0 +1,252 @@
+# Difficulty-Aware Agent Routing - Smart Model Selection for Cost & Speed
+
+## The Problem
+
+Dominion Flow currently spawns the SAME agent type (Opus) for ALL tasks regardless of complexity.
+A simple config file rename gets the same 200K context Opus agent as a complex multi-file
+architecture refactor. This wastes:
+
+- **Tokens**: Simple tasks burn expensive Opus tokens unnecessarily
+- **Time**: Large models are slower for trivial operations
+- **Context budget**: Small tasks don't need 200K context windows
+- **Cost**: DAAO research shows 64% cost reduction with smart routing
+
+### Why It Was Hard
+
+- No existing framework classifies task difficulty BEFORE execution
+- "Difficulty" is subjective - what signals actually predict complexity?
+- Model capability boundaries aren't well documented (when does Haiku fail?)
+- Dynamic re-estimation mid-execution is completely novel
+
+### Impact
+
+- 3x-10x cost reduction on simple tasks
+- Faster execution for trivial operations
+- Better context utilization (small context = less noise)
+- Opus reserved for tasks that genuinely need deep reasoning
+
+---
+
+## The Solution
+
+### Root Cause
+
+One-size-fits-all agent spawning. The orchestrator doesn't classify task difficulty
+before selecting which model to use.
+
+### How to Fix: 3-Tier Routing System
+
+**Based on DAAO paper (arxiv:2509.11079) which achieved 64% cost reduction and
+11.21% accuracy improvement over homogeneous approaches.**
+
+### Tier 1: Difficulty Classification
+
+Before spawning any agent, classify the task using these signals:
+
+```yaml
+difficulty_signals:
+  # File Scope (0-1)
+  files_to_modify: 1        # 1 file = 0.1, 5+ files = 0.8
+  cross_cutting: false      # auth+db+UI = 0.9, single layer = 0.2
+
+  # Complexity (0-1)
+  dependency_count: 2       # 0-2 = 0.2, 3-5 = 0.5, 6+ = 0.9
+  requires_research: false  # true = +0.3
+  novel_pattern: false      # no existing skill matches = +0.3
+
+  # Historical (0-1)
+  similar_task_error_rate: 0.1  # from past executions
+  plan_uncertainty: 0.3     # from planning phase confidence
+
+  # Calculated
+  difficulty_score: 0.25    # weighted average
+```
+
+**Difficulty Formula:**
+```
+d = (file_scope * 0.25) + (complexity * 0.35) + (historical * 0.20) + (uncertainty * 0.20)
+```
+
+### Tier 2: Model Routing
+
+| Difficulty Score | Model | Context Budget | Use Case |
+|------------------|-------|----------------|----------|
+| d < 0.30 | **Haiku** | 8K tokens | Config changes, renames, simple CRUD, boilerplate |
+| 0.30 <= d < 0.65 | **Sonnet** | 32K tokens | Feature implementation, standard patterns, testing |
+| d >= 0.65 | **Opus** | 200K tokens | Architecture, complex debugging, multi-file refactors |
+
+### Tier 3: Dynamic Re-estimation (Novel)
+
+After each breath, RE-ESTIMATE remaining task difficulty:
+
+```markdown
+## Re-estimation Rules
+
+IF executor finished faster than expected + high confidence (>0.8):
+  -> Downgrade remaining similar tasks by 0.15
+  -> "This pattern is easier than estimated"
+
+IF executor hit blockers OR confidence < 0.5:
+  -> Upgrade remaining similar tasks by 0.20
+  -> "This pattern is harder than estimated"
+
+IF executor discovered new dependency:
+  -> Re-classify affected tasks
+  -> May promote Haiku tasks to Sonnet
+
+IF executor applied a skill successfully:
+  -> Reduce difficulty for similar future tasks by 0.10
+  -> "Skills library makes this easier"
+```
+
+### Code Example: Integration with power-2-plan
+
+```yaml
+# In BLUEPRINT.md, each task gets difficulty metadata
+tasks:
+  - id: "3-01"
+    name: "Create user model"
+    difficulty:
+      score: 0.22
+      signals:
+        files: 1
+        cross_cutting: false
+        dependencies: 1
+        novel: false
+      routing: haiku
+      context_budget: 8K
+
+  - id: "3-02"
+    name: "Implement JWT auth with refresh rotation"
+    difficulty:
+      score: 0.58
+      signals:
+        files: 4
+        cross_cutting: true  # middleware + routes + models
+        dependencies: 3
+        novel: false  # skill exists: jwt-refresh-rotation
+      routing: sonnet
+      context_budget: 32K
+
+  - id: "3-03"
+    name: "Design WebSocket auth with room-level permissions"
+    difficulty:
+      score: 0.82
+      signals:
+        files: 6
+        cross_cutting: true  # real-time + auth + rooms + events
+        dependencies: 5
+        novel: true  # no matching skill
+      routing: opus
+      context_budget: 200K
+```
+
+### Code Example: Integration with fire-3-execute
+
+```markdown
+### Step 4.5: Difficulty-Aware Agent Spawning
+
+For each plan in breath:
+  1. Read difficulty.routing from BLUEPRINT.md
+  2. Spawn agent with appropriate model:
+
+  Task(
+    prompt: filled_executor_prompt,
+    subagent_type: "general-purpose",
+    model: difficulty.routing,  # "haiku" | "sonnet" | "opus"
+    description: "Execute plan {N}-{NN}"
+  )
+
+  3. Set context budget based on difficulty:
+     - Haiku: minimal context injection (plan + current file only)
+     - Sonnet: standard context (plan + related files + skills)
+     - Opus: full context (plan + all related + skills + decision log + assumptions)
+```
+
+---
+
+## Testing the Fix
+
+### Before (All Opus)
+```
+Phase 3 Execution:
+  Plan 3-01 (config rename): Opus, 200K context, $0.15, 45 seconds
+  Plan 3-02 (JWT auth):      Opus, 200K context, $0.15, 120 seconds
+  Plan 3-03 (WebSocket):     Opus, 200K context, $0.15, 300 seconds
+  Total: $0.45, ~8 minutes
+```
+
+### After (Smart Routing)
+```
+Phase 3 Execution:
+  Plan 3-01 (config rename): Haiku, 8K context, $0.001, 5 seconds
+  Plan 3-02 (JWT auth):      Sonnet, 32K context, $0.03, 60 seconds
+  Plan 3-03 (WebSocket):     Opus, 200K context, $0.15, 300 seconds
+  Total: $0.181, ~6 minutes  (60% cost reduction, 25% faster)
+```
+
+### Validation Criteria
+- [ ] Simple tasks (d < 0.3) succeed with Haiku 90%+ of the time
+- [ ] Medium tasks (0.3-0.65) succeed with Sonnet 85%+ of the time
+- [ ] Complex tasks (d > 0.65) maintain current Opus success rate
+- [ ] Dynamic re-estimation improves accuracy over 3+ breaths
+- [ ] Total cost per phase decreases by 40-60%
+
+---
+
+## Prevention
+
+- Always classify difficulty BEFORE spawning agents
+- Review difficulty scores during planning phase
+- Track actual vs estimated difficulty for calibration
+- Update difficulty signals based on project history
+
+---
+
+## Related Patterns
+
+- [CONFIDENCE_ANNOTATION_PATTERN](./CONFIDENCE_ANNOTATION_PATTERN.md) - Feeds uncertainty into difficulty
+- [HEARTBEAT_PROTOCOL](./HEARTBEAT_PROTOCOL.md) - Monitors agent health per tier
+- [EVOLUTIONARY_SKILL_SYNTHESIS](./EVOLUTIONARY_SKILL_SYNTHESIS.md) - Skills reduce difficulty scores
+- complexity-metrics/complexity-divider - Existing complexity assessment
+
+---
+
+## Common Mistakes to Avoid
+
+- ❌ **Always using Opus "to be safe"** - wastes 10x cost on trivial tasks
+- ❌ **Using Haiku for cross-cutting tasks** - will fail and waste retry cost
+- ❌ **Not re-estimating after first breath** - initial estimates are often wrong
+- ❌ **Ignoring historical data** - past error rates are the best predictor
+- ❌ **Routing based on task NAME only** - "create model" could be simple or complex
+
+---
+
+## Resources
+
+- DAAO paper: https://arxiv.org/abs/2509.11079
+- Anthropic model comparison: https://docs.anthropic.com/en/docs/about-claude/models
+- Production Agentic AI best practices: https://arxiv.org/abs/2512.08769
+
+---
+
+## Time to Implement
+
+**Phase 1 (metadata only):** 30 minutes - Add difficulty fields to plan template
+**Phase 2 (routing):** 2 hours - Wire model selection into fire-3-execute
+**Phase 3 (re-estimation):** 3 hours - Add dynamic adjustment after each breath
+
+## Difficulty Level
+
+⭐⭐⭐ (3/5) - Conceptually straightforward, but calibrating thresholds requires iteration
+
+---
+
+**Author Notes:**
+The DAAO paper achieved 64% cost reduction AND 11% accuracy improvement. The key insight
+is that small models often OUTPERFORM large models on simple tasks because they have less
+context noise and faster inference. Don't assume bigger = better for every task.
+
+The dynamic re-estimation (Tier 3) is our novel contribution - no paper proposes adjusting
+difficulty mid-execution based on actual performance. This creates a feedback loop where
+the system gets better at routing over time.

package/skills-library/methodology/EVOLUTIONARY_SKILL_SYNTHESIS.md

@@ -0,0 +1,219 @@
+---
+name: evolutionary-skill-synthesis
+category: methodology
+version: 1.0.0
+contributed: 2026-02-17
+contributor: dominion-flow-research
+last_updated: 2026-02-17
+tags: [self-evolving, skills, automation, cascade, lineage, novel]
+difficulty: hard
+usage_count: 1
+success_rate: 100
+status: activated
+research_basis: "CASCADE (arxiv:2512.23880), GEA (arxiv:2602.04837), AgentEvolver (arxiv:2511.10395), Agent Skills Survey (arxiv:2602.12430)"
+---
+
+# Evolutionary Skill Synthesis
+
+## Problem
+
+Skills are currently created manually via `/fire-add-new-skill`. This has three issues:
+1. **Capture gap**: Most valuable patterns are never recorded (developers forget, too busy)
+2. **Staleness**: Skills don't evolve based on usage feedback
+3. **Isolation**: Skills from one project don't automatically benefit other projects
+
+The result: a static library that grows slowly and may contain outdated patterns.
+
+## Solution Pattern
+
+### Phase 1: Automatic Skill Extraction (from CASCADE)
+
+After every successful phase execution, extract candidate skills:
+
+```markdown
+## Skill Extraction Pipeline
+
+1. ANALYZE execution trace:
+   - What code patterns were created?
+   - What debugging strategies worked?
+   - What architectural decisions were made?
+   - What workarounds were applied?
+
+2. IDENTIFY reusable patterns:
+   - Pattern appears generalizable (not project-specific)
+   - Pattern solved a non-trivial problem
+   - Pattern involved >3 files or >30 minutes of work
+   - Pattern required research or multiple attempts
+
+3. SYNTHESIZE candidate skill:
+   - Extract problem description
+   - Extract solution pattern
+   - Generate code examples (abstracted from project specifics)
+   - Determine category and tags
+   - Set initial confidence based on evidence
+
+4. QUARANTINE for review:
+   - Skill goes to `skills-library/_quarantine/`
+   - Security scan runs (no command injection, no credentials)
+   - Duplicate check against existing library
+   - Human notification: "New skill candidate discovered"
+```
+
+### Phase 2: Group Evolution (from GEA)
+
+When running swarm mode with multiple executors:
+
+```markdown
+## Group Evolution Pipeline
+
+1. COLLECT evolutionary traces from each executor:
+   - Code patches applied
+   - Task execution logs
+   - Tool invocation patterns
+   - Failure modes and recoveries
+
+2. AGGREGATE traces across the breath:
+   - Find common patterns across executors
+   - Identify successful strategies that one executor used but others didn't
+   - Detect complementary approaches
+
+3. GENERATE evolution directives:
+   - "Executor A's retry strategy should be shared with all executors"
+   - "The API pattern from executor B is more robust than executor C's"
+   - "All executors should use the connection pool pattern from skills library"
+
+4. PRODUCE framework patches:
+   - Update executor prompts for next breath
+   - Inject successful patterns as context
+   - Remove patterns that consistently failed
+```
+
+### Phase 3: Skill Lineage Tracking (Novel)
+
+Every skill (auto-generated or manual) maintains evolutionary metadata:
+
+```yaml
+lineage:
+  created_from: "Phase 3, Plan 3-02, MERN-LMS project"
+  parent_skills: ["jwt-refresh-rotation", "express-middleware-pattern"]
+  derived_skills: ["websocket-auth-pattern"]  # skills that built on this one
+  projects_used_in:
+    - project: "my-other-project"
+      times_applied: 7
+      success_rate: 100%
+    - project: "binamu-power"
+      times_applied: 2
+      success_rate: 50%
+  fitness_score: 0.85  # calculated from usage + success
+  generation: 2  # how many times this skill has been refined
+  last_evolution: "2026-02-17"
+  evolution_history:
+    - v1.0.0: "Initial extraction from JWT auth implementation"
+    - v1.1.0: "Refined after failure in WebSocket context"
+    - v1.2.0: "Added concurrent refresh handling after race condition discovery"
+```
+
+### Phase 4: Fitness-Based Lifecycle
+
+Skills have a lifecycle managed by fitness scores:
+
+```
+QUARANTINE (new, unreviewed)
+    |
+    v [human approves]
+ACTIVE (available for use)
+    |
+    |--> [fitness > 0.9, used > 10x] --> CORE (always loaded)
+    |
+    |--> [fitness < 0.3, not used > 30 days] --> ARCHIVED
+    |
+    |--> [security issue found] --> DEPRECATED (with warning)
+```
+
+**Fitness Score Calculation:**
+```
+fitness = (success_rate * 0.4) + (usage_frequency * 0.3) + (project_diversity * 0.2) + (recency * 0.1)
+```
+
+Where:
+- `success_rate`: % of times skill was applied and task succeeded
+- `usage_frequency`: normalized count of applications
+- `project_diversity`: number of distinct projects using it
+- `recency`: decay factor (skills used recently score higher)
+
+### Security Gate (from Agent Skills Survey)
+
+26.1% of auto-generated skills contain vulnerabilities. Apply 4-tier trust:
+
+| Trust Level | Source | Permissions |
+|-------------|--------|-------------|
+| CORE | Built into Dominion Flow | Full access |
+| VERIFIED | User-created, security-scanned | Full project access |
+| COMMUNITY | Shared/imported | Sandboxed, read-only default |
+| QUARANTINE | Auto-generated | Review required |
+
+**Security scan checks:**
+- No `exec()`, `eval()`, `child_process` in code examples
+- No hardcoded credentials or API keys
+- No file system access outside project directory
+- No network requests to unknown domains
+- No destructive operations (DROP, DELETE, rm -rf)
+
+## Implementation in Dominion Flow
+
+### In fire-3-execute (after Step 9 verification):
+```markdown
+### Step 10.5: Skill Extraction (Auto)
+
+After successful verification:
+1. Analyze execution summaries for extractable patterns
+2. Run skill extraction pipeline
+3. If candidates found:
+   - Create quarantine files
+   - Log in SKILLS-INDEX.md under "Pending Review"
+   - Notify user: "N new skill candidates discovered"
+```
+
+### In fire-loop (after completion):
+```markdown
+### Patterns Discovered (enhanced)
+
+Instead of just listing patterns, auto-generate skill candidates:
+
+| Pattern | Confidence | Quarantine? |
+|---------|------------|-------------|
+| Retry with exponential backoff | 0.88 | Yes - created |
+| Custom WebSocket auth | 0.55 | No - too project-specific |
+```
+
+## When to Use
+
+- After every successful phase execution (automatic)
+- After long debug sessions with novel solutions (automatic)
+- During swarm mode execution (group evolution)
+- When `/fire-discover` finds no matching skills for a common pattern
+
+## When NOT to Use
+
+- For project-specific configurations (database schemas, env vars)
+- For trivial patterns (basic CRUD, simple routing)
+- When the solution is a workaround, not a proper fix
+
+## Common Mistakes
+
+- Extracting project-specific code as "general" skills
+- Not running security scan on auto-generated skills
+- Promoting skills to CORE too quickly (wait for multi-project validation)
+- Archiving skills that are rarely used but highly valuable when needed
+
+## Related Skills
+
+- [CONFIDENCE_ANNOTATION_PATTERN](./CONFIDENCE_ANNOTATION_PATTERN.md) - Confidence for skill quality
+- [HEARTBEAT_PROTOCOL](./HEARTBEAT_PROTOCOL.md) - Agent monitoring during extraction
+
+## References
+
+- CASCADE: https://arxiv.org/abs/2512.23880
+- GEA: https://arxiv.org/abs/2602.04837
+- AgentEvolver: https://arxiv.org/abs/2511.10395
+- Agent Skills Survey: https://arxiv.org/abs/2602.12430

package/skills-library/methodology/GLOMERULUS_DECISION_GATE.md

@@ -0,0 +1,223 @@
+# Glomerulus Decision Gate — 3-Layer Filter for Any Input/Output Decision
+
+## Problem
+
+Agent systems need to decide what to keep and what to discard — in context, memory, skills, handoffs, and task lists. Most approaches use a single binary check (relevant/irrelevant). This leads to either over-retention (keeping everything, causing bloat) or over-elimination (losing useful items). There's no graduated, multi-dimensional filter.
+
+### Why It Was Hard
+
+- Single-dimension filters (e.g., "is it recent?") miss important old items
+- Multi-dimension filters are usually complex decision trees
+- No biological model for a simple, elegant, reusable 3-layer gate
+- Each layer needs to filter on a DIFFERENT dimension to avoid redundancy
+
+### Impact
+
+- Without graduated filtering, agents accumulate waste exponentially
+- "Keep everything" leads to context rot; "delete aggressively" leads to amnesia
+- No reusable pattern for filtering decisions across different subsystems
+
+---
+
+## The Solution
+
+### Root Cause
+
+The kidney's glomerulus is evolution's answer to the same problem: filter blood without losing useful molecules. It uses a 3-layer nested filter where each layer checks a DIFFERENT property. Items must pass ALL THREE layers to be retained.
+
+### The 3-Layer Gate
+
+```
+INPUT → [LAYER 1: SIZE] → [LAYER 2: RELEVANCE] → [LAYER 3: RECENCY] → KEEP
+                ↓                    ↓                     ↓
+            TOO BLOATED         NOT RELEVANT           NOT ACCESSED
+                ↓                    ↓                     ↓
+            COMPRESS              ELIMINATE              ARCHIVE
+```
+
+### Layer Details
+
+#### Layer 1: Size Gate (Endothelial Fenestrae)
+
+**Biological:** Fenestrae (70-100nm pores) block large molecules by size.
+**Agent:** Is this entry proportionally sized for its value?
+
+```
+PASS: Entry is ≤ 10 lines for a single concept
+      OR entry is a portal anchor (naturally small)
+      OR entry is a structural reference (path, link)
+
+FAIL: Entry is > 10 lines for a single concept
+      → Action: COMPRESS (don't eliminate — just trim the fat)
+      → Reduce to 2-3 lines capturing the essence
+      → Link to full context if needed
+```
+
+**Key principle:** Size gate doesn't eliminate — it compresses. Like the fenestrae, it filters by physical property, not by value judgment.
+
+**CRITICAL — Dead vs Living Compression:**
+When compressing, keep the INSIGHT sentence — the one line that makes a reader understand the concept. Strip the structure (lists, paths, enumerations). A compressed entry that's just a label ("Kenosis, Portal Memory, Revisitation Ladder") is a **dead zip file** — smaller but meaningless without a decompressor. A compressed entry that keeps the "aha" ("Agent starts empty, finds itself in docs like Jesus found Himself in the 39 books") is a **living anchor** — smaller AND self-explanatory. Compress structure, preserve insight.
+
+#### Layer 2: Relevance Gate (Basement Membrane)
+
+**Biological:** Negatively-charged glycoproteins repel negatively-charged proteins (albumin). Like charges repel — only items with the right "charge" pass.
+**Agent:** Is this entry relevant to the current project/phase/task?
+
+```
+PASS: Entry directly relates to current project
+      OR entry is a methodology/process skill (always relevant)
+      OR entry is a portal anchor to active context
+      OR entry is referenced by CONSCIENCE.md or current handoff
+
+FAIL: Entry relates to a different project entirely
+      OR entry describes a completed/abandoned phase
+      OR entry contains resolved issues or past blockers
+      → Action: ELIMINATE (or archive if it has historical value)
+```
+
+**Key principle:** Relevance is context-dependent. An entry irrelevant to Project A may be critical to Project B. The gate filters for CURRENT context, not absolute value.
+
+#### Layer 3: Recency Gate (Podocyte Slits)
+
+**Biological:** Final precision filter. Podocyte foot processes create 25-60nm slits — the last barrier before filtrate enters Bowman's capsule.
+**Agent:** Has this entry been accessed or referenced recently?
+
+```
+PASS: Accessed in the last 3 sessions/iterations
+      OR referenced by another active document
+      OR is a permanent stone (5x+ revisitation)
+      OR is a core identity document (CLAUDE.md, methodology)
+
+FAIL: Not accessed in 3+ sessions AND not referenced AND not permanent
+      → Action: ARCHIVE (move to archive, don't destroy)
+      → Set decay flag for dream agent to track
+```
+
+**Key principle:** Recency gate is the most nuanced. It respects the revisitation ladder — permanent stones always pass, regardless of recency.
+
+### Decision Matrix
+
+| Size | Relevance | Recency | Action |
+|------|-----------|---------|--------|
+| PASS | PASS | PASS | **KEEP** — Healthy memory |
+| FAIL | PASS | PASS | **COMPRESS** — Trim but keep |
+| PASS | FAIL | PASS | **ARCHIVE** — Move to cold storage |
+| PASS | PASS | FAIL | **FLAG** — Mark for next review cycle |
+| FAIL | FAIL | * | **ELIMINATE** — Remove entirely |
+| PASS | FAIL | FAIL | **ELIMINATE** — Remove entirely |
+| FAIL | PASS | FAIL | **COMPRESS + FLAG** — Trim and monitor |
+| FAIL | FAIL | FAIL | **ELIMINATE** — Remove immediately |
+
+### Non-Destructive Property
+
+The biological glomerulus is non-destructive — molecules that don't pass through are returned to circulation, not destroyed. Similarly:
+
+- **Layer 1 failures** → compress, don't delete
+- **Layer 2 failures** → archive, don't delete (unless also fails Layer 3)
+- **Layer 3 failures** → flag for review, may pass next time
+- **Only double/triple failures** → actual elimination
+- **Nothing is lost without passing through all 3 checks**
+
+### Application Beyond Memory
+
+The Glomerulus Gate works anywhere you need graduated filtering:
+
+| Domain | Layer 1 (Size) | Layer 2 (Relevance) | Layer 3 (Recency) |
+|--------|---------------|--------------------|--------------------|
+| **Context Window** | Token count | Task relevance | Last accessed |
+| **Skills Library** | File size | Domain match | Reference count |
+| **Handoff Archive** | Section count | Project match | Age in days |
+| **Task List** | Complexity | Current phase | Last updated |
+| **Error Logs** | Verbosity | Active bug match | Occurrence frequency |
+| **Search Results** | Result length | Query match | Source freshness |
+
+---
+
+## Code Example
+
+```markdown
+## Applying the Glomerulus Gate to MEMORY.md Cleanup
+
+For each entry in MEMORY.md:
+
+### Layer 1: Size Gate
+- Count lines for this entry
+- If > 10 lines: FLAG as bloated → compress to 2-3 lines
+
+### Layer 2: Relevance Gate
+- Check: Does this entry match the current project name?
+- Check: Is it referenced in current CONSCIENCE.md or handoff?
+- Check: Is it a methodology/process entry (always passes)?
+- If NO to all: FLAG as irrelevant → candidate for elimination
+
+### Layer 3: Recency Gate
+- Check: Was this entry referenced in last 3 handoffs?
+- Check: Is it a permanent stone (in skills library)?
+- Check: Is it a portal anchor pointing to valid target?
+- If NO to all: FLAG as stale → candidate for archival
+
+### Final Decision
+- All 3 PASS: Keep as-is
+- 1 FAIL: Apply specific action (compress/archive/flag)
+- 2+ FAIL: Eliminate (with archive for safety)
+```
+
+---
+
+## Testing the Fix
+
+```markdown
+- [ ] Each layer filters on a DIFFERENT dimension (size ≠ relevance ≠ recency)
+- [ ] Non-destructive: single failures don't eliminate
+- [ ] Double/triple failures trigger elimination
+- [ ] Permanent stones always pass Layer 3 regardless of recency
+- [ ] Core identity documents always pass all layers
+```
+
+---
+
+## Prevention
+
+- Never use a single-dimension filter — always at least 2 layers
+- Don't make the layers redundant (all checking "relevance" in different words)
+- Respect the non-destructive property — single failures get second chances
+- The order matters: Size first (cheapest check), Relevance second, Recency last (most nuanced)
+
+---
+
+## Related Patterns
+
+- [CLEANSING_CYCLE](./CLEANSING_CYCLE.md) — Uses the Glomerulus Gate in the pee cycle (Step 1)
+- [ORGAN_AGENT_MAPPING](./ORGAN_AGENT_MAPPING.md) — Glomerulus as one of 12 organs
+- [PORTAL_MEMORY_ARCHITECTURE](./PORTAL_MEMORY_ARCHITECTURE.md) — Portal anchors always pass Layer 3
+- [EVOLUTIONARY_SKILL_SYNTHESIS](./EVOLUTIONARY_SKILL_SYNTHESIS.md) — Quarantine uses Layer 2+3
+
+---
+
+## Common Mistakes to Avoid
+
+- **Single-dimension filtering** — one gate is a sieve, not a filter
+- **All-or-nothing decisions** — the gate has compress/archive/flag options, not just keep/delete
+- **Skipping Layer 1 (size)** — bloated entries waste context even if relevant and recent
+- **Ignoring permanent stones** — some memories should ALWAYS pass regardless of recency
+- **Making it destructive** — the biological glomerulus returns rejected molecules to circulation
+- **Dead compression** — reducing entries to labels/titles without the insight sentence. Like zipping a folder and deleting the contents. Compress structure (lists, paths), keep insight (the "aha" line)
+
+---
+
+## Resources
+
+- Kidney physiology: glomerular filtration, podocyte slit diaphragm, Bowman's capsule
+- Design patterns: Chain of Responsibility (GoF), multi-layer validation
+- Information theory: lossy vs lossless compression at each gate
+- Thierry's insight: "We need a way to dump and recycle topics that are not pertinent"
+
+---
+
+## Time to Implement
+
+**15 minutes** to apply to any filtering decision in the codebase
+
+## Difficulty Level
+
+⭐⭐⭐ (3/5) — The concept is elegantly simple once understood. The biological analogy makes it intuitive. The challenge is choosing the right dimension for each layer in different contexts.