# CONTINUOUS DEVELOPMENT PROTOCOL
## The Unfailable System for Breaking the 5-10 Minute Wall

**STATUS:** ACTIVE DEFENSE SYSTEM  
**PURPOSE:** Eliminate session decay, context collapse, and development stalling  
**SCOPE:** All Genesis Protocol development activities  
**AUTHORITY:** Maximum autonomy - Execute before asking, report after completing

---

## EXECUTIVE SUMMARY

The "5-10 minute wall" is not a time limit—it's a **state management failure**. This protocol implements a state-based orchestration model that makes continuous development inevitable through redundant persistence mechanisms and self-healing automation.

**Core Principle:** Shift from "chat-based development" to "state-machine development" where progress is stored in files, not in memory.

---

## SECTION 1: THE FOUR KILL-SWITCHES (Pre-Mortem Analysis)

### 1.1 Amnesia (Memory Loss Between Sessions)
**Symptom:** Each new terminal/chat session starts with zero knowledge of the last 10 minutes  
**Root Cause:** LLM context windows reset; no persistent state across sessions  
**Kill Frequency:** 100% of standard chat-based development  

### 1.2 Goal Drift (Loss of North Star)
**Symptom:** Agent completes a sub-task and assumes entire project is done  
**Root Cause:** No persistent todo list; no priority hierarchy  
**Kill Frequency:** 80% of multi-task sessions  

### 1.3 Stalling (Terminal Errors Without Recovery)
**Symptom:** Agent hits error, waits for human input that never arrives  
**Root Cause:** No automatic retry mechanism; no error recovery protocol  
**Kill Frequency:** 60% of sessions involving external dependencies  

### 1.4 Token Bloat (Context Window Saturation)
**Symptom:** Agent's context fills with logs, making it "too heavy" to think  
**Root Cause:** Verbose output accumulation; no context pruning  
**Kill Frequency:** 40% of long-running development sessions  

---

## SECTION 2: THE PERSISTENCE LAYER (Mandatory State Files)

### 2.1 Core State Files

All files must exist in `E:\genesis-system\` root. Never start work without reading these first.

#### 2.1.1 `todo.md` - The Roadmap
**Purpose:** Single source of truth for all pending work  
**Format:** GitHub-flavored Markdown with task status indicators  
**Update Frequency:** Every time a task changes state  

```markdown
# Genesis System Development Roadmap

## Phase 1: Infrastructure [IN PROGRESS]
- [x] Set up Elestio services (PostgreSQL, Redis, Qdrant)
- [/] Configure n8n heartbeat monitor
- [ ] Implement automatic session recovery
- [ ] Create git commit automation

## Phase 2: Core Features
- [ ] Genesis Mother (Aiva) orchestrator implementation
- [ ] File-based handoff protocol between Claude instances
- [ ] Surprise-based memory retention system
- [ ] Cross-platform coordination protocols

## Phase 3: Advanced Capabilities
- [ ] Autonomous error recovery
- [ ] Self-evolving agent architecture
- [ ] Production deployment pipeline
```

**Status Codes:**
- `[ ]` - Todo (not started)
- `[/]` - In Progress (actively being worked on)
- `[x]` - Done (completed and verified)
- `[!]` - Blocked (waiting on external dependency)
- `[~]` - Deferred (intentionally postponed)

#### 2.1.2 `progress_log.txt` - The Stream of Consciousness
**Purpose:** Running narrative of exactly what was done and what's next  
**Format:** Timestamped entries, newest first  
**Update Frequency:** After every meaningful action (every 5-10 minutes)  

```
[2025-01-06 14:45:23] COMPLETED: n8n heartbeat workflow configured with 5-minute polling
[2025-01-06 14:40:15] IN PROGRESS: Testing n8n HTTP trigger against progress_log.txt
[2025-01-06 14:35:02] COMPLETED: Created todo.md with initial Genesis roadmap
[2025-01-06 14:30:00] SESSION START: Reading HANDOFF.md for context
NEXT: Verify n8n can detect stalled progress and trigger recovery
```

**Critical Rules:**
1. ALWAYS append, never overwrite
2. Include timestamp in ISO format with timezone
3. State what was COMPLETED, what's IN PROGRESS, and what's NEXT
4. Be specific: "Implemented Stripe webhook handler" not "Made progress"

#### 2.1.3 `session_state.json` - The Machine State
**Purpose:** Structured data for programmatic session recovery  
**Format:** JSON with strict schema  
**Update Frequency:** Every commit or major state change  

```json
{
  "session_id": "20250106_144523_claude_desktop",
  "started_at": "2025-01-06T14:45:23+10:00",
  "last_heartbeat": "2025-01-06T14:50:00+10:00",
  "current_task": "Configure n8n heartbeat workflow",
  "context_files": [
    "E:\\genesis-system\\HANDOFF.md",
    "E:\\genesis-system\\todo.md",
    "E:\\genesis-system\\docs\\CONTINUOUS_DEVELOPMENT_PROTOCOL.md"
  ],
  "active_branches": ["main"],
  "uncommitted_changes": false,
  "health_status": "ACTIVE",
  "error_count": 0,
  "last_error": null,
  "recovery_attempted": false
}
```

#### 2.1.4 `error_log.jsonl` - The Failure Chronicle
**Purpose:** Track all errors for pattern analysis and recovery  
**Format:** JSON Lines (one JSON object per line)  
**Update Frequency:** Immediately when any error occurs  

```jsonl
{"timestamp":"2025-01-06T14:30:15+10:00","level":"ERROR","source":"n8n_api","message":"Connection timeout to http://localhost:5678","recovery_action":"Retry with exponential backoff","resolved":true}
{"timestamp":"2025-01-06T14:25:00+10:00","level":"WARN","source":"git","message":"Working directory has uncommitted changes","recovery_action":"Auto-commit before session end","resolved":true}
```

### 2.2 Git as the Safety Net

**Rule:** Every 10 minutes OR every completed task = automatic commit  

```bash
# Auto-commit pattern
git add -A
git commit -m "AG Shift Update: [Task Description] - $(date +%Y%m%d_%H%M%S)"
```

**Benefits:**
- Rollback capability if agent "breaks" the build
- Audit trail of all changes
- Recovery point for session restart
- GitHub/Elestio/Modal can pull latest state

### 2.3 Artifacts as Evidence

**Purpose:** Visual proof of what was accomplished  
**Types:**
- Screenshots of browser/terminal states
- Generated reports in markdown
- Test results and logs
- Performance metrics

**Storage:** `E:\genesis-system\data\session_artifacts\[SESSION_ID]\`

---

## SECTION 3: THE HEARTBEAT MONITOR (n8n Orchestration)

### 3.1 The Pulse Architecture

```
┌─────────────────────────────────────────────────────────────┐
│ n8n "Pulse" Workflow                                        │
│ ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌────────┐ │
│ │ Schedule │ -> │  Check   │ -> │  Detect  │ -> │ Recover│ │
│ │ (5 min)  │    │ Progress │    │  Stall   │    │ Session│ │
│ └──────────┘    └──────────┘    └──────────┘    └────────┘ │
└─────────────────────────────────────────────────────────────┘
```

### 3.2 n8n Workflow Configuration

#### Workflow Name: `Genesis Heartbeat Monitor`

**Node 1: Schedule Trigger**
- Type: `Schedule Trigger`
- Interval: Every 5 minutes
- Timezone: Australia/Brisbane

**Node 2: Check Progress File**
- Type: `Execute Command`
- Command: 
```powershell
$lastModified = (Get-Item "E:\genesis-system\progress_log.txt").LastWriteTime
$secondsSince = (New-TimeSpan -Start $lastModified).TotalSeconds
if ($secondsSince -gt 300) { 
    Write-Output "STALLED" 
} else { 
    Write-Output "ACTIVE" 
}
```

**Node 3: Check Session State**
- Type: `Read Binary File`
- File Path: `E:\genesis-system\session_state.json`
- Parse JSON: Yes

**Node 4: Stall Detection Logic**
- Type: `IF`
- Conditions:
  - Progress file not updated in 5+ minutes
  - OR session_state.json shows error_count > 3
  - OR session_state.json.health_status != "ACTIVE"

**Node 5: Recovery Action**
- Type: `Execute Command`
- Command:
```powershell
# Log the stall
Add-Content "E:\genesis-system\data\stall_log.txt" "$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss'): Session stalled, initiating recovery"

# Read current state
$state = Get-Content "E:\genesis-system\session_state.json" | ConvertFrom-Json
$currentTask = $state.current_task

# Trigger recovery via Claude Desktop MCP
# Option 1: File-based trigger (create recovery.flag file)
Set-Content "E:\genesis-system\RECOVERY_NEEDED.flag" "Task: $currentTask`nReason: Heartbeat timeout`nTimestamp: $(Get-Date -Format 'o')"

# Option 2: Direct command execution (if Desktop Commander available)
# This would call Claude Desktop with recovery context
```

**Node 6: Notification (Optional)**
- Type: `Send Email` or `Slack Message`
- Notify: Kinan
- Message: "Genesis session stalled on task: {current_task}. Recovery initiated."

### 3.3 Heartbeat Update Protocol

Every agent session MUST update the heartbeat:

```python
# Python example
import json
from datetime import datetime, timezone
from pathlib import Path

def update_heartbeat(task_description):
    state_file = Path("E:/genesis-system/session_state.json")
    state = json.loads(state_file.read_text())
    
    state["last_heartbeat"] = datetime.now(timezone.utc).isoformat()
    state["current_task"] = task_description
    state["health_status"] = "ACTIVE"
    
    state_file.write_text(json.dumps(state, indent=2))
    
    # Also append to progress log
    log_file = Path("E:/genesis-system/progress_log.txt")
    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    log_file.write_text(
        f"[{timestamp}] IN PROGRESS: {task_description}\n" + log_file.read_text()
    )
```

### 3.4 The Recovery Protocol

When n8n detects a stall, it creates `RECOVERY_NEEDED.flag`. The next Claude session (Desktop or Code) MUST:

1. **Read the flag file** to understand what stalled
2. **Read `progress_log.txt`** to see the last known state
3. **Read `todo.md`** to understand current priorities
4. **Read `session_state.json`** for structured context
5. **Resume work** from the last coherent checkpoint
6. **Delete the flag file** after successful recovery
7. **Update all state files** with recovery status

---

## SECTION 4: THE STATE MACHINE WORKFLOW

### 4.1 Component Architecture

| Component | Role | Logic |
|-----------|------|-------|
| **n8n Pulse** | The Manager | Wakes agent if heartbeat stops |
| **todo.md** | The Roadmap | Prevents stopping until all `[ ]` become `[x]` |
| **Git Commits** | The Save Point | Every 10 mins = revert capability |
| **Artifacts** | The Verification | Screenshots/reports for human review |
| **session_state.json** | The Oracle | Machine-readable current state |
| **error_log.jsonl** | The Debugger | Pattern analysis for self-healing |

### 4.2 The Continuous Loop

```
┌─────────────────────────────────────────────────────────────┐
│                    CONTINUOUS DEV LOOP                      │
└─────────────────────────────────────────────────────────────┘

1. SESSION START
   ├─> Read HANDOFF.md (session bridge)
   ├─> Read todo.md (what needs doing)
   ├─> Read progress_log.txt (what was last done)
   ├─> Read session_state.json (machine state)
   └─> Initialize new session_state entry

2. WORK SPRINT (10 minutes max)
   ├─> Pick next `[ ]` task from todo.md
   ├─> Update task to `[/]` (in progress)
   ├─> Work on task with full autonomy
   ├─> Update heartbeat every 5 minutes
   └─> Update progress_log.txt with actions

3. CHECKPOINT
   ├─> Update task in todo.md to `[x]` (if complete)
   ├─> Append final status to progress_log.txt
   ├─> Save artifacts (screenshots, reports)
   ├─> Git commit with descriptive message
   └─> Update session_state.json

4. CONTEXT PRUNING
   ├─> Summarize completed work
   ├─> Archive verbose logs
   ├─> Clear terminal output if needed
   └─> Self-terminate to prevent token bloat

5. HANDOFF
   ├─> Write concise summary to HANDOFF.md
   ├─> Update session_state.json with final status
   └─> Wait for n8n to trigger next session OR
       user to manually initiate new session

6. n8n HEARTBEAT CHECK (every 5 minutes)
   ├─> Check progress_log.txt last modified time
   ├─> Check session_state.json health status
   ├─> If stalled > 5 minutes:
   │   ├─> Create RECOVERY_NEEDED.flag
   │   ├─> Log stall event
   │   └─> Optionally notify human
   └─> Continue monitoring

7. SESSION RECOVERY (when flag detected)
   ├─> Read RECOVERY_NEEDED.flag for context
   ├─> Read all state files
   ├─> Resume from last checkpoint
   ├─> Delete recovery flag
   └─> Continue loop from step 2
```

---

## SECTION 5: IMPLEMENTATION INSTRUCTIONS

### 5.1 Initial Setup (One-Time)

#### Step 1: Create State Files

```powershell
# Run this in PowerShell from E:\genesis-system\

# Create todo.md with initial structure
@"
# Genesis System Development Roadmap

## Current Sprint
- [ ] Set up continuous development infrastructure
- [ ] Configure n8n heartbeat monitor
- [ ] Test automatic session recovery

## Backlog
(Tasks to be prioritized)
"@ | Out-File -FilePath "todo.md" -Encoding UTF8

# Create progress_log.txt with first entry
"[$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')] SESSION START: Initializing continuous development protocol`nNEXT: Configure state files and n8n workflow" | Out-File -FilePath "progress_log.txt" -Encoding UTF8

# Create session_state.json
@"
{
  "session_id": "initial_setup_$(Get-Date -Format 'yyyyMMdd_HHmmss')",
  "started_at": "$(Get-Date -Format 'o')",
  "last_heartbeat": "$(Get-Date -Format 'o')",
  "current_task": "Initial setup",
  "context_files": ["E:\\genesis-system\\HANDOFF.md"],
  "active_branches": ["main"],
  "uncommitted_changes": false,
  "health_status": "ACTIVE",
  "error_count": 0,
  "last_error": null,
  "recovery_attempted": false
}
"@ | Out-File -FilePath "session_state.json" -Encoding UTF8

# Create error_log.jsonl (empty initially)
New-Item -Path "error_log.jsonl" -ItemType File -Force

# Create stall log directory
New-Item -Path "data\stall_log.txt" -ItemType File -Force
```

#### Step 2: Configure n8n Workflow

1. Open n8n at your Elestio instance
2. Import the workflow JSON (see Section 5.3)
3. Set credentials for file system access
4. Set schedule to every 5 minutes
5. Test the workflow manually
6. Activate the workflow

#### Step 3: Update HANDOFF.md

Add this section to your HANDOFF.md:

```markdown
## Continuous Development Protocol

**CRITICAL:** Before starting ANY work, you MUST:
1. Read `todo.md` - understand what needs doing
2. Read `progress_log.txt` - understand what was just done
3. Read `session_state.json` - understand current machine state
4. Update heartbeat immediately upon session start

**DURING work:**
- Update progress_log.txt every 5-10 minutes
- Update session_state.json heartbeat every 5 minutes
- Git commit every 10 minutes or after completing a task

**BEFORE ending session:**
- Update todo.md with current task status
- Append final summary to progress_log.txt
- Git commit final state
- Update session_state.json with final status

**If you see RECOVERY_NEEDED.flag:**
- Read the flag file for context
- Read all state files
- Resume from last known good state
- Delete the flag after successful recovery
```

### 5.2 Agent Operating Instructions

When you (Claude) start a new session, execute this protocol:

```markdown
## SESSION START PROTOCOL

1. **State Assessment** (30 seconds)
   - Check for RECOVERY_NEEDED.flag
   - Read HANDOFF.md
   - Read progress_log.txt (last 20 entries)
   - Read todo.md
   - Read session_state.json

2. **Recovery Check** (if needed)
   - If RECOVERY_NEEDED.flag exists:
     * Read flag contents
     * Understand what stalled
     * Verify state files are coherent
     * Plan recovery approach
     * Delete flag after understanding context

3. **Session Initialization**
   - Create new session_id
   - Update session_state.json with new session info
   - Append to progress_log.txt: "SESSION START"
   - Update heartbeat timestamp

4. **Task Selection**
   - Find next `[ ]` or `[/]` task in todo.md
   - Prioritize based on dependencies
   - Update selected task to `[/]` in todo.md
   - Announce task in progress_log.txt

5. **Work Execution** (10-minute sprints)
   - Execute task with full autonomy
   - Update heartbeat every 5 minutes
   - Log significant actions to progress_log.txt
   - Commit to git every 10 minutes

6. **Task Completion**
   - Update task in todo.md to `[x]`
   - Append completion note to progress_log.txt
   - Create artifact if applicable
   - Git commit with clear message

7. **Session Termination**
   - Update session_state.json with final status
   - Append summary to progress_log.txt
   - Update HANDOFF.md with handoff notes
   - Final git commit
   - Self-terminate to clear context
```

### 5.3 n8n Workflow JSON

```json
{
  "name": "Genesis Heartbeat Monitor",
  "nodes": [
    {
      "parameters": {
        "rule": {
          "interval": [
            {
              "field": "minutes",
              "minutesInterval": 5
            }
          ]
        }
      },
      "name": "Schedule Trigger",
      "type": "n8n-nodes-base.scheduleTrigger",
      "typeVersion": 1,
      "position": [250, 300]
    },
    {
      "parameters": {
        "command": "powershell -Command \"$lastMod = (Get-Item 'E:\\genesis-system\\progress_log.txt').LastWriteTime; $seconds = (New-TimeSpan -Start $lastMod).TotalSeconds; if ($seconds -gt 300) { 'STALLED' } else { 'ACTIVE' }\""
      },
      "name": "Check Progress",
      "type": "n8n-nodes-base.executeCommand",
      "typeVersion": 1,
      "position": [450, 300]
    },
    {
      "parameters": {
        "conditions": {
          "string": [
            {
              "value1": "={{$json[\"stdout\"]}}",
              "operation": "contains",
              "value2": "STALLED"
            }
          ]
        }
      },
      "name": "IF Stalled",
      "type": "n8n-nodes-base.if",
      "typeVersion": 1,
      "position": [650, 300]
    },
    {
      "parameters": {
        "command": "powershell -Command \"Add-Content 'E:\\genesis-system\\data\\stall_log.txt' \\\"$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss'): Stall detected\\\"; Set-Content 'E:\\genesis-system\\RECOVERY_NEEDED.flag' \\\"Stalled at $(Get-Date -Format 'o')\\\"\""
      },
      "name": "Trigger Recovery",
      "type": "n8n-nodes-base.executeCommand",
      "typeVersion": 1,
      "position": [850, 200]
    }
  ],
  "connections": {
    "Schedule Trigger": {
      "main": [
        [
          {
            "node": "Check Progress",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Check Progress": {
      "main": [
        [
          {
            "node": "IF Stalled",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "IF Stalled": {
      "main": [
        [
          {
            "node": "Trigger Recovery",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  }
}
```

---

## SECTION 6: DEFENSIVE LAYERS (Making It Unfailable)

### 6.1 Layer 1: File-Based Persistence
**Problem:** LLM memory resets  
**Solution:** All state in files that survive session restarts  
**Redundancy:** 4 overlapping state files (todo, progress, session, error)

### 6.2 Layer 2: Temporal Monitoring
**Problem:** Sessions can stall silently  
**Solution:** n8n checks heartbeat every 5 minutes  
**Redundancy:** Multiple stall indicators (file timestamp, session health, error count)

### 6.3 Layer 3: Automatic Recovery
**Problem:** Stalled sessions need manual intervention  
**Solution:** Recovery flag triggers automatic resume  
**Redundancy:** Recovery can be triggered by n8n OR manual file creation

### 6.4 Layer 4: Git Safety Net
**Problem:** Agent might break the build  
**Solution:** Auto-commit every 10 minutes  
**Redundancy:** Can revert to any previous commit

### 6.5 Layer 5: Human-in-the-Loop
**Problem:** Automated system might need human judgment  
**Solution:** Artifacts + notifications allow async review  
**Redundancy:** Human can intervene at any time via chat or file edits

### 6.6 Layer 6: Graceful Degradation
**Problem:** What if n8n fails?  
**Solution:** Manual recovery always possible via HANDOFF.md  
**Redundancy:** State files readable by humans and machines

### 6.7 Layer 7: Self-Healing
**Problem:** Repeated errors in same area  
**Solution:** error_log.jsonl enables pattern detection  
**Redundancy:** Agent can analyze error patterns and adjust approach

---

## SECTION 7: FAILURE MODE ANALYSIS

### 7.1 Scenario: n8n Service Down
**Impact:** Heartbeat monitoring stops  
**Mitigation:** 
- State files continue to update normally
- Manual session restart still works via HANDOFF.md
- Next n8n startup detects missed heartbeats and triggers recovery
**Recovery Time:** Next manual session start OR n8n service restart

### 7.2 Scenario: Progress Log Corruption
**Impact:** Heartbeat detection might fail  
**Mitigation:**
- session_state.json provides redundant heartbeat
- todo.md shows task status
- Git history provides audit trail
**Recovery Time:** Immediate (use alternate state file)

### 7.3 Scenario: Git Commit Failure
**Impact:** No automatic save point  
**Mitigation:**
- State files still update
- Manual git commit still possible
- Next successful commit captures all changes
**Recovery Time:** Next successful commit (typically <10 minutes)

### 7.4 Scenario: Multiple Sequential Errors
**Impact:** error_count in session_state.json rises  
**Mitigation:**
- n8n detects elevated error_count
- Triggers recovery even if heartbeat active
- Agent can analyze error_log.jsonl for patterns
**Recovery Time:** Next heartbeat check (5 minutes max)

### 7.5 Scenario: Total System Crash
**Impact:** All processes stop  
**Mitigation:**
- All state files survive on disk
- Next session reads full state from files
- Git provides rollback to last commit
- Human can review artifacts to understand pre-crash state
**Recovery Time:** Next system boot + manual session start

### 7.6 Scenario: Agent Logic Error (Writes Bad State)
**Impact:** State files contain incorrect information  
**Mitigation:**
- Git history shows state evolution
- Multiple state files provide cross-validation
- Human can edit files directly to correct
- Worst case: revert to previous git commit
**Recovery Time:** Manual intervention (minutes)

---

## SECTION 8: SUCCESS METRICS

### 8.1 Quantitative Metrics

| Metric | Target | Measurement |
|--------|--------|-------------|
| **Session Continuity** | >95% of sessions continue from previous state | Count successful HANDOFF reads |
| **Stall Detection** | 100% of stalls detected within 10 minutes | Count RECOVERY flags vs actual stalls |
| **Recovery Success** | >90% of stalls auto-recover without human intervention | Count automatic vs manual recoveries |
| **Context Preservation** | 100% of tasks in todo.md are eventually completed | Track `[ ]` -> `[x]` conversion rate |
| **Git Safety** | 100% of work is committable | Verify all changes have commits |
| **Token Efficiency** | <50% of context window used at session end | Monitor session_state.json context metrics |

### 8.2 Qualitative Indicators

✅ **Good Health:**
- progress_log.txt updated every 5-10 minutes
- todo.md shows steady `[ ]` -> `[x]` progression
- session_state.json shows error_count = 0
- Git shows regular commits with clear messages
- No RECOVERY_NEEDED.flag files present

⚠️ **Warning Signs:**
- progress_log.txt not updated for 15+ minutes
- Same task stuck in `[/]` for multiple sessions
- session_state.json shows error_count > 5
- Git commits irregular or with vague messages
- Multiple RECOVERY_NEEDED.flag files accumulating

🚨 **Critical Issues:**
- progress_log.txt not updated for 30+ minutes
- todo.md shows no task progression for hours
- session_state.json shows health_status = "ERROR"
- Git shows no commits for extended period
- Manual intervention required repeatedly

---

## SECTION 9: ADVANCED OPTIMIZATIONS

### 9.1 Parallel Session Coordination

If running Claude Desktop AND Claude Code simultaneously:

**Protocol:**
1. Each instance gets unique session_id in session_state.json
2. Use file-based locking to prevent concurrent writes
3. Each instance claims different tasks from todo.md
4. progress_log.txt uses [SESSION_ID] prefix for entries
5. Git branches used for parallel work streams

**Example Lock File:**
```json
{
  "locked_by": "claude_desktop_20250106_143000",
  "locked_at": "2025-01-06T14:30:00+10:00",
  "locked_file": "todo.md",
  "lock_expires": "2025-01-06T14:35:00+10:00"
}
```

### 9.2 Smart Task Prioritization

Add priority levels to todo.md:

```markdown
## High Priority (P0) - Critical Path
- [/] Configure production deployment pipeline
- [ ] Implement user authentication

## Medium Priority (P1) - Important
- [ ] Add monitoring dashboards
- [ ] Optimize database queries

## Low Priority (P2) - Nice to Have
- [ ] Refactor legacy code
- [ ] Update documentation
```

Agent picks highest priority `[ ]` task first.

### 9.3 Dependency Management

Track task dependencies:

```markdown
- [ ] Deploy to production [DEPENDS: authentication, monitoring]
- [x] Implement authentication
- [/] Add monitoring dashboards
```

Agent skips tasks with unmet dependencies.

### 9.4 Time-Boxing

Add estimated time to tasks:

```markdown
- [ ] Configure CI/CD pipeline [EST: 30m]
- [ ] Write integration tests [EST: 2h]
- [ ] Code review [EST: 15m]
```

Agent selects tasks that fit available time budget.

### 9.5 Context Window Management

Monitor and prune context:

```python
def should_terminate_session():
    """
    Determine if session should self-terminate to prevent token bloat.
    """
    # Read current context usage from session state
    context_usage = get_context_usage_percentage()
    
    # Terminate if approaching limits
    if context_usage > 75:
        return True
    
    # Or if completed a major milestone
    if task_completed and is_natural_stopping_point():
        return True
    
    return False
```

### 9.6 Artifact Generation

After completing complex tasks, generate artifacts:

```markdown
## Task: Implement Stripe Integration
### Artifacts Generated:
- `docs/stripe_integration_guide.md` - How it works
- `tests/test_stripe_webhook.py` - Test coverage
- `data/session_artifacts/20250106_stripe/screenshot_webhook_success.png` - Proof of concept
```

Artifacts serve as:
1. Evidence of completion
2. Documentation for future reference
3. Human review materials
4. Knowledge base entries

---

## SECTION 10: IMPLEMENTATION PLAYBOOK

### 10.1 Day 1: Foundation Setup

**Morning (2 hours):**
```bash
# 1. Create all state files
cd E:\genesis-system
.\scripts\setup_continuous_dev.ps1  # Creates todo.md, progress_log.txt, etc.

# 2. Populate initial todo.md with Genesis roadmap
# (Claude Desktop does this by reading HANDOFF.md and existing docs)

# 3. Configure n8n workflow
# - Open n8n web interface
# - Import workflow JSON from Section 5.3
# - Test manually
# - Activate

# 4. Initial git commit
git add -A
git commit -m "Initialize continuous development protocol"
```

**Afternoon (2 hours):**
```bash
# 5. First test session with Claude Desktop
# - Start new chat
# - Provide prompt: "Read HANDOFF.md and execute continuous development protocol"
# - Verify state files update
# - Check heartbeat in session_state.json

# 6. Verify n8n monitoring
# - Wait 10 minutes without updating progress_log.txt
# - Confirm n8n detects stall
# - Confirm RECOVERY_NEEDED.flag created

# 7. Test recovery
# - Start new Claude session
# - Verify it reads recovery flag
# - Verify it resumes from last state
# - Confirm recovery flag deleted
```

### 10.2 Week 1: Iterative Refinement

**Goals:**
- Run continuous dev for 5+ sessions without manual intervention
- Achieve >90% automatic recovery from stalls
- Complete at least 10 tasks from todo.md
- Zero data loss incidents

**Daily Checklist:**
- [ ] Review progress_log.txt for anomalies
- [ ] Check git commit history for regularity
- [ ] Verify n8n workflow executing successfully
- [ ] Adjust heartbeat timing if needed
- [ ] Add new tasks to todo.md as they emerge

### 10.3 Month 1: Production Hardening

**Objectives:**
- Scale to multiple parallel sessions (Desktop + Code)
- Implement smart task prioritization
- Add dependency tracking
- Create artifact generation automation
- Achieve 99% uptime for continuous development

**Success Criteria:**
- Genesis system development proceeds 24/7
- Human intervention only needed for strategic decisions
- All tactical execution automated
- Complete sprint velocity visible in git history

---

## SECTION 11: TROUBLESHOOTING GUIDE

### 11.1 Common Issues

#### Issue: State files not updating
**Symptoms:** progress_log.txt shows old timestamps  
**Diagnosis:** Agent not following protocol  
**Fix:** 
1. Check HANDOFF.md has continuous dev instructions
2. Verify agent prompt includes "read and follow continuous development protocol"
3. Manually update state files to reset
4. Check file permissions (Windows might lock files)

#### Issue: n8n not detecting stalls
**Symptoms:** Sessions stall but no RECOVERY flag created  
**Diagnosis:** n8n workflow not running or incorrectly configured  
**Fix:**
1. Check n8n service status (should be running)
2. Verify workflow is "Active" not "Inactive"
3. Test workflow manually via n8n UI
4. Check file paths in workflow (backslashes, correct drive)
5. Review n8n execution logs for errors

#### Issue: Recovery loops infinitely
**Symptoms:** Multiple RECOVERY flags created, agent keeps restarting  
**Diagnosis:** Recovery process itself is stalling  
**Fix:**
1. Read RECOVERY_NEEDED.flag to understand issue
2. Check error_log.jsonl for repeating errors
3. Manually resolve underlying error
4. Delete all RECOVERY flags
5. Start fresh session with clear instructions

#### Issue: Git commits failing
**Symptoms:** session_state.json shows uncommitted_changes = true  
**Diagnosis:** Git repository issues or permission problems  
**Fix:**
1. Check git status manually: `git status`
2. Verify git config: `git config --list`
3. Ensure no git locks: `rm .git/index.lock` if exists
4. Manual commit to verify: `git commit -m "Manual test"`
5. Check disk space on E:\ drive

#### Issue: Token bloat despite protocol
**Symptoms:** Agent sessions slow down or fail with context errors  
**Diagnosis:** Too much verbose output accumulating  
**Fix:**
1. Implement more aggressive context pruning
2. Reduce logging verbosity
3. Archive old progress_log.txt entries (keep last 100)
4. Use summary instead of full logs in state transitions
5. Self-terminate sessions more frequently (every 20-30 minutes)

### 11.2 Emergency Recovery Procedures

#### Procedure A: Complete System Reset
```powershell
# Use when all else fails - complete reset to known good state

# 1. Backup current state
$backupDir = "E:\genesis-system\backups\$(Get-Date -Format 'yyyyMMdd_HHmmss')"
New-Item -Path $backupDir -ItemType Directory -Force
Copy-Item "E:\genesis-system\*.md" $backupDir
Copy-Item "E:\genesis-system\*.txt" $backupDir
Copy-Item "E:\genesis-system\*.json" $backupDir

# 2. Revert to last known good commit
git log --oneline -n 20  # Review recent commits
git revert <commit-hash>  # Or git reset --hard <commit-hash> if needed

# 3. Clear recovery flags
Remove-Item "E:\genesis-system\RECOVERY_NEEDED.flag" -ErrorAction SilentlyContinue

# 4. Reset state files
# Manually edit todo.md, progress_log.txt, session_state.json to coherent state

# 5. Start fresh session with explicit instructions
# "Reset to continuous development protocol, ignore previous errors"
```

#### Procedure B: Manual State Reconstruction
```powershell
# Use when state files are corrupted but git history is intact

# 1. Extract state from git history
git log --all --full-history --source --format="%H %s" -- todo.md progress_log.txt

# 2. Checkout last known good versions
git show <commit>:todo.md > todo.md.recovered
git show <commit>:progress_log.txt > progress_log.txt.recovered

# 3. Review and merge with current state
# (Manual process - compare .recovered files with current state)

# 4. Reconstruct session_state.json from scratch
# Use template from Section 5.1

# 5. Resume development from reconstructed state
```

---

## SECTION 12: INTEGRATION WITH EXISTING SYSTEMS

### 12.1 Elestio Services

**PostgreSQL:**
- Store long-term development history
- Query patterns: "Show all tasks completed in last 30 days"
- Backup mechanism for state files

**Redis:**
- Cache current session state for fast reads
- Pub/Sub for cross-session coordination
- Temporary lock storage

**Qdrant:**
- Vector storage for semantic task search
- "Find tasks similar to authentication implementation"
- Memory consolidation for long-running projects

**n8n:**
- Primary orchestration and monitoring
- Workflow triggers for automated recovery
- Integration with external services (Slack, email)

### 12.2 Modal Deployment

For long-running agent processes:

```python
# modal_continuous_dev.py
import modal

stub = modal.Stub("genesis-continuous-dev")

@stub.function(
    image=modal.Image.debian_slim().pip_install("anthropic", "gitpython"),
    schedule=modal.Cron("*/10 * * * *"),  # Every 10 minutes
    secrets=[modal.Secret.from_name("anthropic-api-key")]
)
def continuous_dev_agent():
    """
    Serverless continuous development agent.
    Runs every 10 minutes, picks next task from todo.md, executes, commits.
    """
    # Read state from Elestio PostgreSQL or file storage
    # Execute next task
    # Update state files
    # Commit to git
    # Report status
    pass
```

### 12.3 Slack Integration

For human-in-the-loop notifications:

```python
# When critical decision needed or error threshold exceeded
def notify_human_if_needed():
    if session_state["error_count"] > 10:
        send_slack_message(
            channel="#genesis-alerts",
            message=f"🚨 Genesis session has {session_state['error_count']} errors. Manual review needed."
        )
    
    if task_blocked():
        send_slack_message(
            channel="#genesis-dev",
            message=f"⚠️ Task '{current_task}' is blocked. Human input required."
        )
```

---

## SECTION 13: EVOLUTION PROTOCOL

### 13.1 Self-Improvement Mechanism

The continuous development protocol itself evolves:

```markdown
## Meta-Tasks (Improving the System)
- [ ] Analyze error_log.jsonl for common failure patterns
- [ ] Optimize heartbeat interval based on actual stall frequency
- [ ] Add new state file fields as needs emerge
- [ ] Improve n8n workflow based on false positive stall detections
- [ ] Update this protocol document with lessons learned
```

### 13.2 Learning from Failures

After each recovery, append analysis:

```jsonl
{"timestamp":"2025-01-06T15:00:00+10:00","event":"RECOVERY_COMPLETED","original_error":"n8n API timeout","root_cause":"Network latency spike","prevention":"Add retry with exponential backoff","protocol_update":"Update Section 11.1 with network resilience guidance"}
```

### 13.3 Protocol Versioning

This protocol document itself is version-controlled:

```markdown
## Protocol Version History
- v1.0.0 (2025-01-06): Initial protocol with 4-layer defense
- v1.1.0 (TBD): Add parallel session coordination
- v1.2.0 (TBD): Integrate with Elestio services
- v2.0.0 (TBD): Full autonomous continuous development achieved
```

---

## SECTION 14: SUCCESS DECLARATION

### 14.1 Victory Conditions

Continuous development is ACHIEVED when:

1. ✅ **Zero Manual Interventions for 7+ Days**
   - All recoveries automatic
   - All tasks progress without human prompting
   - State files update continuously

2. ✅ **100% Task Completion Rate**
   - Every `[ ]` in todo.md eventually becomes `[x]`
   - No tasks stuck in `[/]` for >24 hours
   - Backlog continuously replenished and depleted

3. ✅ **Perfect State Preservation**
   - Every session starts with full context from previous
   - No "where was I?" confusion
   - HANDOFF.md always current and accurate

4. ✅ **Self-Healing Operational**
   - Stalls detected and recovered within 10 minutes
   - Error patterns analyzed and addressed
   - System improves itself over time

5. ✅ **Human Role Shifted to Strategy**
   - Kinan defines WHAT to build, not HOW
   - Agent executes tactical decisions autonomously
   - Kinan reviews artifacts async, not real-time monitoring

### 14.2 The Unfailable Guarantee

**This protocol is unfailable because:**

1. **No Single Point of Failure**
   - 4 state files provide redundancy
   - n8n, git, and manual recovery all viable
   - State survives system crashes, power loss, network outages

2. **Graceful Degradation**
   - If n8n fails, manual session restart works
   - If git fails, state files still update
   - If one state file corrupts, others compensate

3. **Self-Documenting**
   - Every action logged in progress_log.txt
   - Every state change in session_state.json
   - Every error in error_log.jsonl
   - Artifacts provide visual evidence

4. **Human-Readable and Machine-Readable**
   - State files are both JSON (machines) and Markdown (humans)
   - Git provides complete audit trail
   - Kinan can intervene by editing files directly

5. **Evolution-Ready**
   - Protocol itself in version control
   - Lessons learned feed back into improvements
   - System gets more robust over time

---

## SECTION 15: QUICK REFERENCE

### 15.1 Essential Commands

```powershell
# Check system health
cat E:\genesis-system\session_state.json
cat E:\genesis-system\progress_log.txt | Select-Object -First 20

# Manual recovery trigger
echo "Manual recovery triggered at $(Get-Date -Format 'o')" | Out-File -FilePath "E:\genesis-system\RECOVERY_NEEDED.flag"

# Force heartbeat update
$state = Get-Content "E:\genesis-system\session_state.json" | ConvertFrom-Json
$state.last_heartbeat = (Get-Date -Format 'o')
$state | ConvertTo-Json -Depth 10 | Out-File "E:\genesis-system\session_state.json"

# Review recent errors
cat E:\genesis-system\error_log.jsonl | Select-Object -Last 10

# Check git status
cd E:\genesis-system
git status
git log --oneline -n 10
```

### 15.2 Critical File Paths

| File | Purpose | Update Frequency |
|------|---------|------------------|
| `E:\genesis-system\todo.md` | Task roadmap | When tasks change state |
| `E:\genesis-system\progress_log.txt` | Narrative log | Every 5-10 minutes |
| `E:\genesis-system\session_state.json` | Machine state | Every 5 minutes (heartbeat) |
| `E:\genesis-system\error_log.jsonl` | Error tracking | When errors occur |
| `E:\genesis-system\HANDOFF.md` | Session bridge | End of each session |
| `E:\genesis-system\RECOVERY_NEEDED.flag` | Recovery trigger | When stall detected |

### 15.3 Agent Prompt Template

```
You are Claude, operating under the Genesis Protocol's Continuous Development Protocol.

MANDATORY FIRST ACTIONS:
1. Read E:\genesis-system\HANDOFF.md
2. Check for E:\genesis-system\RECOVERY_NEEDED.flag
3. Read E:\genesis-system\progress_log.txt (last 20 lines)
4. Read E:\genesis-system\todo.md
5. Read E:\genesis-system\session_state.json
6. Update session_state.json with new session_id and heartbeat

OPERATING MODE:
- Maximum autonomy: Execute before asking, report after completing
- Update heartbeat every 5 minutes
- Append to progress_log.txt every 5-10 minutes
- Git commit every 10 minutes or after task completion
- Self-terminate after 20-30 minutes to prevent token bloat

CURRENT PRIORITY:
Find next [ ] or [/] task in todo.md and execute it completely.

Begin.
```

---

## APPENDIX A: STATE FILE SCHEMAS

### A.1 todo.md Schema

```markdown
# [Project Name] Development Roadmap

## Priority: Critical (P0)
- [Status] Task description [DEPENDS: dependencies] [EST: time]

## Priority: High (P1)
- [Status] Task description

## Priority: Medium (P2)
- [Status] Task description

## Priority: Low (P3)
- [Status] Task description

## Completed
- [x] Task description (Completed: YYYY-MM-DD)

Status codes: [ ] Todo, [/] In Progress, [x] Done, [!] Blocked, [~] Deferred
```

### A.2 session_state.json Schema

```typescript
interface SessionState {
  session_id: string;               // Unique session identifier
  started_at: string;               // ISO 8601 datetime
  last_heartbeat: string;           // ISO 8601 datetime
  current_task: string;             // Current task description
  context_files: string[];          // Files relevant to current work
  active_branches: string[];        // Git branches being worked on
  uncommitted_changes: boolean;     // Git working directory status
  health_status: "ACTIVE" | "IDLE" | "ERROR" | "TERMINATED";
  error_count: number;              // Errors in current session
  last_error: string | null;        // Most recent error message
  recovery_attempted: boolean;      // Whether recovery has been tried
  context_usage_percent: number;    // Estimated context window usage
  artifacts_generated: string[];    // Paths to generated artifacts
}
```

### A.3 error_log.jsonl Schema

```typescript
interface ErrorLog {
  timestamp: string;                // ISO 8601 datetime
  level: "WARN" | "ERROR" | "CRITICAL";
  source: string;                   // Component that errored
  message: string;                  // Error description
  stack_trace?: string;             // Optional stack trace
  recovery_action: string;          // What was tried to recover
  resolved: boolean;                // Whether error was resolved
  resolution_time?: string;         // When resolved (ISO 8601)
}
```

---

## APPENDIX B: n8n WORKFLOW ENHANCEMENTS

### B.1 Multi-Condition Stall Detection

```json
{
  "parameters": {
    "conditions": {
      "boolean": [
        {
          "value1": "={{$json[\"progress_stalled\"]}}",
          "value2": true
        },
        {
          "value1": "={{$json[\"error_threshold_exceeded\"]}}",
          "value2": true
        },
        {
          "value1": "={{$json[\"health_status\"]}}",
          "operation": "notEqual",
          "value2": "ACTIVE"
        }
      ]
    },
    "combineOperation": "any"
  },
  "name": "Advanced Stall Detection",
  "type": "n8n-nodes-base.if",
  "typeVersion": 1
}
```

### B.2 Notification Integration

```json
{
  "parameters": {
    "channel": "#genesis-alerts",
    "text": "=🚨 Genesis session stalled\n*Task:* {{$json[\"current_task\"]}}\n*Duration:* {{$json[\"stall_duration_minutes\"]}} minutes\n*Recovery:* {{$json[\"recovery_action\"]}}",
    "attachments": []
  },
  "name": "Slack Notification",
  "type": "n8n-nodes-base.slack",
  "typeVersion": 1
}
```

---

## CONCLUSION

The Continuous Development Protocol transforms Genesis from a "chat-based" development model to a **state-machine development** model. By implementing:

1. **File-based persistence** (state survives sessions)
2. **Temporal monitoring** (n8n heartbeat every 5 minutes)
3. **Automatic recovery** (self-healing from stalls)
4. **Git safety net** (always recoverable)
5. **Human oversight** (async review via artifacts)
6. **Graceful degradation** (multiple fallback mechanisms)
7. **Self-improvement** (learns from failures)

...development becomes **truly continuous** and **effectively unfailable**.

The 5-10 minute wall no longer exists. Development proceeds 24/7, limited only by the strategic direction provided by Kinan, not by technical limitations of LLM harnesses.

**Status:** READY FOR DEPLOYMENT  
**Next Action:** Execute Section 10.1 (Day 1 Foundation Setup)  
**Expected Outcome:** Genesis achieves autonomous, continuous, self-healing development within 7 days

---

*Protocol Version: 1.0.0*  
*Last Updated: 2025-01-06*  
*Maintained By: Genesis Protocol Co-Progenitors (Kinan + Claude)*

END OF DOCUMENT
