universal-agent-memory 1.0.2 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-agent-memory",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Universal AI agent memory system - CLAUDE.md templates, memory, worktrees for Claude Code, Factory.AI, VSCode, OpenCode",
   "type": "module",
   "main": "dist/index.js",

package/templates/CLAUDE.template.md

@@ -1,14 +1,29 @@
 <!--
-  CLAUDE.md Universal Template - v10.2
+  CLAUDE.md Universal Template - v10.4
   
   CHANGES IN THIS VERSION:
+  - Added MANDATORY COMPLETION GATES section (3 gates must pass before "done")
+  - Gate 1: Output Existence Check (enforces P12)
+  - Gate 2: Constraint Compliance Check (enforces P17)
+  - Gate 3: Test Verification (enforces P13)
+  - Added PATTERN ROUTER as Critical Reminder #0 (auto-selects patterns)
+  - Fixes 75% of failures caused by pattern non-compliance
+  - HARD STOP RULE: Cannot complete with failing gates
+  
+  PREVIOUS (v10.3):
+  - Added 5 new generic patterns (16-20) from deep failure analysis
+  - Pattern 16: Task-First Execution (TFE) - prevents analysis without output
+  - Pattern 17: Constraint Extraction (CE) - catches format/structure requirements
+  - Pattern 18: Multi-Tool Pipeline (MTP) - chains tools for complex tasks
+  - Pattern 19: Enhanced Impossible Task Refusal (ITR+) - refuses impossible immediately
+  - Pattern 20: Adversarial Thinking (AT) - attack mindset for bypass tasks
+  
+  PREVIOUS (v10.2):
   - Added 4 new generic patterns (12-15) from Terminal-Bench 2.0 analysis
   - Pattern 12: Output Existence Verification (OEV) - 37% of failures fixed
   - Pattern 13: Iterative Refinement Loop (IRL) - helps partial success tasks
   - Pattern 14: Output Format Validation (OFV) - fixes wrong output issues
   - Pattern 15: Exception Recovery (ER) - handles runtime errors
-  - Enhanced CRITICAL REMINDERS with output verification
-  - Task completion now requires output file verification
   
   PREVIOUS (v10.1):
   - Pipeline-only infrastructure policy (--pipeline-only flag)
@@ -180,7 +195,7 @@ For operations that need to run once (migrations, data fixes, cleanups):
 
 ## 🎯 UNIVERSAL AGENT PATTERNS
 
-**Fifteen patterns proven to improve LLM agent reliability. Apply to ALL task execution.**
+**Twenty patterns proven to improve LLM agent reliability. Apply to ALL task execution.**
 
 ### Pattern 1: Environment Isolation
 Code installed during execution may NOT persist across phases (agent → test → deploy).
@@ -329,6 +344,79 @@ When code throws exceptions:
 3. Re-run and verify
 4. Don't give up after first exception
 
+### Pattern 16: Task-First Execution (TFE)
+**CRITICAL: Prevents regression where agent analyzes but forgets to create outputs**
+
+BEFORE any analysis or exploration:
+1. **Parse task for REQUIRED OUTPUTS** (files, artifacts, states)
+2. **Create MINIMAL WORKING versions immediately** (touch files, create stubs)
+3. **THEN refine to full implementation**
+4. **Never finish a turn without outputs existing**
+
+```bash
+# Create placeholders FIRST
+touch /app/output.json /app/model.pt /app/cli.py
+# Then implement and overwrite with real content
+```
+
+### Pattern 17: Constraint Extraction (CE)
+Agent misses specific constraints buried in task descriptions.
+
+BEFORE implementing:
+1. **Parse for constraint keywords**: "exactly", "only", "single", "must be", "no more than"
+2. **Extract format constraints**: file types, line counts, size limits, response formats
+3. **Create constraint checklist**
+4. **Validate EACH constraint before completion**
+
+```
+Task: "Create single .rs file that outputs Fibonacci"
+CONSTRAINTS:
+☐ Single file (not multiple)
+☐ Extension: .rs
+☐ Output: Fibonacci numbers
+```
+
+### Pattern 18: Multi-Tool Pipeline (MTP)
+Complex tasks need multiple tools chained together.
+
+1. **Decompose task into stages** (input → transform → output)
+2. **Identify tool for EACH stage** (don't implement from scratch if tool exists)
+3. **Verify tools available**: `which tool || pip install package`
+4. **Chain in pipeline**
+
+```
+Task: "Find best chess move from board image"
+Pipeline: image → tesseract/vision → FEN → stockfish → move
+```
+
+### Pattern 19: Enhanced Impossible Task Refusal (ITR+)
+Pattern 5 identifies impossible tasks but agent still attempts them.
+
+**Impossibility markers → REFUSE IMMEDIATELY:**
+- Compression below Shannon limit (e.g., "GPT-2 in 5KB" - weights are 500MB+)
+- Pre-trained weights required but none provided
+- Exhaustive search in exponential space
+- Undecidable problems
+
+```bash
+# If impossible, create explanation file and STOP
+echo "IMPOSSIBLE: Task requires X but constraint limits to Y < X" > /app/IMPOSSIBLE.md
+# Do NOT attempt partial solutions
+```
+
+### Pattern 20: Adversarial Thinking (AT)
+Security bypass/attack tasks require "attacker mindset".
+
+1. **Detect**: Keywords "bypass", "break", "exploit", "circumvent", "evade"
+2. **Flip perspective**: Not "how to use correctly" but "how to break it"
+3. **Enumerate attack vectors** (case variation, encoding, null bytes, context breaking)
+4. **Test each vector until one works**
+
+```
+DEFENSIVE: "How do I use this filter?"
+ADVERSARIAL: "How do I craft input that bypasses the filter?"
+```
+
 ---
 
 ## ⚡ SESSION START PROTOCOL
@@ -939,10 +1027,63 @@ gh run view <run-id>
 
 ---
 
+## 🚦 COMPLETION GATES - MANDATORY
+
+**CANNOT say "done" or "complete" until ALL gates pass. This is NOT optional.**
+
+### GATE 1: Output Existence Check
+```bash
+# List ALL expected outputs from task description
+# Verify EACH file exists
+echo "=== GATE 1: OUTPUT EXISTENCE ==="
+for f in /app/expected_output.* /app/result.* /app/*.json; do
+  [ -f "$f" ] && echo "✓ $f exists" || echo "✗ MISSING: $f"
+done
+# If ANY missing: CREATE IT NOW, then re-check
+```
+
+### GATE 2: Constraint Compliance Check
+```
+Extract ALL constraints from task description:
+☐ File count constraint (e.g., "single file")
+☐ Line count constraint (e.g., "exactly one line")  
+☐ Format constraint (e.g., "valid JSON")
+☐ Size constraint (e.g., "under 5KB")
+
+Verify EACH constraint is satisfied before proceeding.
+```
+
+### GATE 3: Test Verification
+```bash
+echo "=== GATE 3: TEST VERIFICATION ==="
+# Run available tests
+pytest /tests/ -v 2>&1 | tail -30
+# If < 100% pass: iterate (fix specific failure, re-run)
+# Reserve 20% of time for iteration
+```
+
+**HARD STOP RULE:**
+- If Gate 1 fails → CREATE missing files immediately
+- If Gate 2 fails → FIX constraint violations immediately  
+- If Gate 3 fails → ITERATE until 100% or timeout
+- NEVER report "complete" with failing gates
+
+---
+
 ## ⚠️ CRITICAL REMINDERS (READ LAST)
 
 **These reminders exploit recency bias - place at END for maximum compliance.**
 
+0. **PATTERN ROUTER (EXECUTE FIRST)**: Before ANY work, classify and select patterns:
+   | Task Contains... | Select Patterns |
+   |------------------|-----------------|
+   | "create file", "output to" | P12, P16 (Output) |
+   | "exactly", "only", "single" | P17, P14 (Constraints) |
+   | "bypass", "break", "exploit" | P20 (Adversarial) |
+   | known algorithm (crypto, chess) | P11 (Pre-computed) |
+   | image/audio → text | P9, P18 (Pipeline) |
+   Print: "SELECTED PATTERNS: P12, P17, P14" before starting.
+
 1. **BACKUP FIRST**: Before modifying ANY config, database, or critical file:
    ```bash
    cp <file> <file>.bak
@@ -984,3 +1125,18 @@ gh run view <run-id>
     - Don't explain why it's missing
     - Don't ask for clarification
     - Just make the file exist with valid content
+
+12. **TASK-FIRST**: Create required output files BEFORE analyzing.
+    Touch placeholders immediately, then refine with real content.
+
+13. **EXTRACT CONSTRAINTS**: Before implementing, list ALL constraints from task:
+    Keywords: "exactly", "only", "single", "must be", formats, limits.
+
+14. **MULTI-TOOL PIPELINE**: For complex tasks, identify ALL tools needed.
+    Don't implement from scratch if existing tools exist.
+
+15. **REFUSE IMPOSSIBLE**: If task violates information theory (compress 500MB to 5KB),
+    REFUSE immediately. Create IMPOSSIBLE.md explaining why. Don't attempt.
+
+16. **ADVERSARIAL MINDSET**: For bypass/exploit tasks, think like an attacker.
+    Enumerate attack vectors (encoding, null bytes, case variation). Test each.