infinite-agents-public/infinite_variants/infinite_variant_6/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code when working with the Stateful Infinite Loop variant.

## Project Overview

This is a variant of the Infinite Agentic Loop pattern that adds robust **state management** with **self-consistency validation**. The system enables resumable, auditable, and deduplication-guaranteed infinite loop execution.

### Key Innovation

Applies **self-consistency prompting** (multiple sampling + majority voting) to state validation:
- 6 independent validation checks verify state integrity
- Majority voting produces consistency score (0.0-1.0)
- High-confidence validation even if individual checks have edge cases
- Proven AI technique adapted to state management

## Key Commands

### Running Stateful Infinite Loops

```bash
claude
```

Then use these commands:

### /infinite-stateful

Main orchestration command with state management.

```bash
# Basic usage
/infinite-stateful <spec_path> <output_dir> <count> [url_strategy] [run_id]

# Examples:
/infinite-stateful specs/example_spec.md outputs 5
/infinite-stateful specs/example_spec.md outputs 10 specs/urls.json
/infinite-stateful specs/example_spec.md outputs infinite specs/urls.json
/infinite-stateful specs/example_spec.md outputs infinite specs/urls.json run_20250310_143022
```

**Features:**
- Persistent state in `.claude/state/run_*.json`
- Automatic URL deduplication
- Self-consistency validation
- Graceful interruption handling
- Resume capability

### /status

View run status and validate consistency.

```bash
# List all runs
/status

# Detailed status for specific run
/status run_20250310_143022
```

**Output:**
- Run information (spec, progress, timing)
- Self-consistency validation (6 checks + score)
- Recent iterations
- Resumability status
- URL usage summary

### /resume

Resume interrupted run.

```bash
/resume <run_id>
```

**Process:**
1. Validates state consistency
2. Loads original parameters
3. Continues from last completed iteration
4. No duplicate URLs or iterations

### /reset-state

State management utilities.

```bash
# Verify state integrity
/reset-state <run_id>

# Rebuild state from files
/reset-state <run_id> --rebuild

# Delete state (with backup)
/reset-state <run_id> --delete
```

## Architecture & Structure

### Command System

`.claude/commands/`:
- `infinite-stateful.md` - Main orchestration with state management
- `resume.md` - Resume interrupted runs
- `status.md` - View and validate run status
- `reset-state.md` - State management utilities

`.claude/settings.json`:
- Permissions: Write, Edit, Read, Bash, Task, WebFetch, WebSearch
- Custom instructions for state management

### State Management

`.claude/state/`:
- `run_*.json` - Individual run state files
- `README.md` - State system documentation

**State File Structure:**
```json
{
  "run_id": "run_YYYYMMDD_HHMMSS",
  "spec_path": "specs/example_spec.md",
  "output_dir": "outputs",
  "total_count": 10,
  "status": "in_progress",
  "completed_iterations": 3,
  "iterations": [...],
  "used_urls": [...],
  "validation": {
    "consistency_score": 1.0,
    "issues": []
  }
}
```

### Specification System

`specs/`:
- `example_spec.md` - Example specification with state integration
- Custom specs can be added

**Spec Requirements:**
- Output file naming pattern
- Content structure
- Quality standards
- Web learning integration
- **Metadata embedding** (required for state tracking)

### Utility Files

- `state_manager.py` - Python utilities for state operations
- `validators/check_state_consistency.sh` - Bash validation script
- `templates/` - State, URL tracker, and iteration templates
- `docs/state_management_guide.md` - Complete usage guide

## State Management Principles

### 1. Single Source of Truth

State file is authoritative:
- File system is secondary
- State determines what exists
- Validation checks consistency

### 2. Self-Consistency Validation

6 independent checks with majority voting:
1. Schema validation
2. File count matching
3. Iteration record consistency
4. URL uniqueness
5. File existence
6. Timestamp validity

**Consistency Score** = (passed checks) / 6
- ≥0.8: State is reliable
- 0.5-0.79: Warnings
- <0.5: Corrupted

### 3. Deduplication Guarantee

- All URLs tracked in `used_urls`
- URL strategy filtered against used URLs
- Fallback to web search for new URLs
- Iteration numbers never collide

### 4. Resumability

- Any run can resume by `run_id`
- State tracks exact progress point
- Graceful handling of interruptions
- No re-generation of completed iterations

### 5. Atomicity

- State updates are atomic (temp + rename)
- Prevents corruption from partial writes
- Safe concurrent reads
- Single writer at a time

### 6. Auditability

- Complete iteration history
- Timestamped state changes
- URL tracking
- Validation results

## Implementation Details

### State Updates

After each batch completion:
1. Load current state
2. Add iteration records
3. Update completion counters
4. Add URLs to used list
5. Update timestamp
6. Save atomically (temp + rename)

### Self-Consistency Validation

Between batches and at resume:
1. Run 6 independent checks
2. Each check returns pass/fail
3. Compute consistency score
4. If score < 0.8, pause and report
5. User decides: continue, fix, or abort

### URL Deduplication

For each iteration:
1. Load URL strategy
2. Filter out URLs in `state.used_urls`
3. Select next available URL
4. If exhausted, fallback to web search
5. Add used URL to state

### Resume Process

1. Locate state file by `run_id`
2. Validate state consistency (pre-check)
3. Extract original parameters
4. Determine next iteration number
5. Continue generation
6. Validate state consistency (post-check)

### Rebuild Process

When state corrupted:
1. Scan output directory
2. Extract iteration numbers from filenames
3. Read metadata from files (if embedded)
4. Reconstruct iteration records
5. Compute file hashes
6. Deduplicate URLs
7. Create new state file
8. Validate rebuilt state

## Usage Patterns

### Pattern 1: Long-Running Generation

```bash
# Start
/infinite-stateful specs/viz.md outputs 100

# ... interrupted after 47 ...
# State auto-saved

# Resume
/resume run_20250310_143022
# Continues from 48
```

### Pattern 2: Infinite Mode

```bash
# Start infinite
/infinite-stateful specs/viz.md outputs infinite specs/urls.json

# ... hits context limit ...
# State saved

# New session
/resume run_20250310_143022
# Continues indefinitely
```

### Pattern 3: State Recovery

```bash
# Check
/status run_20250310_143022
# Score: 0.67 (WARNING)

# Rebuild
/reset-state run_20250310_143022 --rebuild

# Verify
/status run_20250310_143022
# Score: 1.00 (CONSISTENT)
```

## Best Practices

### For Claude Code Users

**State Management:**
- Let system manage state automatically
- Use `/status` to check consistency regularly
- Resume interrupted runs rather than restart
- Trust self-consistency validation

**Resumability:**
- Use consistent spec and output_dir
- Preserve output directory between sessions
- Check state before resuming
- Let system determine next iteration

**URL Deduplication:**
- Use URL strategy files
- Let state track URLs automatically
- Trust deduplication system
- Provide fallback search terms

**Validation:**
- Run validation before critical operations
- Investigate low consistency scores
- Use multiple validation approaches
- Trust majority voting results

### For Spec Authors

**Required Metadata:**

Specs MUST require embedded metadata in outputs:

```html
<div id="metadata" style="display:none;">
{
  "iteration": 1,
  "web_source": "https://example.com/tutorial",
  "techniques_learned": ["technique1", "technique2"],
  "created": "2025-03-10T14:30:00Z"
}
</div>
```

This enables:
- State reconstruction from files
- URL deduplication
- Quality validation
- Learning tracking

### For Command Authors

**State-Aware Commands:**

New commands should:
- Load state from `.claude/state/`
- Validate consistency before operations
- Update state atomically
- Document state changes

Example:
```python
from state_manager import StateManager

sm = StateManager()
state = sm.load_state(run_id)

# Validate
score, checks = sm.validate_consistency(state)
if score < 0.8:
    # Handle low consistency

# Operate on state
# ...

# Save atomically
sm.save_state(state)
```

## Troubleshooting

### Common Issues

**Low Consistency Score:**
- Run `/status <run_id>` for details
- Use `/reset-state <run_id> --rebuild` to fix
- Investigate specific failed checks

**Cannot Resume:**
- Verify state file exists: `ls .claude/state/`
- Use `/status` to list available runs
- Check state consistency before resume

**Duplicate URLs:**
- Run `/status <run_id>` to check uniqueness
- Rebuild state: `/reset-state <run_id> --rebuild`
- Verify URL strategy has unique URLs

**Missing Files:**
- Files manually deleted after generation
- Rebuild state: `/reset-state <run_id> --rebuild`
- Or accept loss and continue

### Validation Tools

**Bash Validator:**
```bash
./validators/check_state_consistency.sh run_20250310_143022
```

**Python Utilities:**
```bash
python state_manager.py list
python state_manager.py validate run_20250310_143022
python state_manager.py info run_20250310_143022
```

## Web Learning Integration

This variant demonstrates learning from **self-consistency prompting** research:

**Source Concept:** Self-consistency improves AI reliability by:
1. Generating multiple independent reasoning paths
2. Analyzing consistency across paths
3. Using majority voting to select consensus answer

**Applied Here:** State validation uses:
1. Multiple independent validation checks (6 different approaches)
2. Consistency analysis (pass/fail for each check)
3. Majority voting (consistency score from passed/total)

**Result:** High-confidence state validation even if individual checks have edge cases or limitations.

## Extension Points

### Add Custom Commands

Create new commands in `.claude/commands/`:
- Analysis commands
- Export commands
- Reporting commands
- Integration commands

### Add Custom Validation

Extend `state_manager.py`:
```python
def validate_custom(state):
    # Domain-specific checks
    pass
```

### Add State Metadata

Extend state schema:
```python
def add_metadata(state, key, value):
    if 'metadata' not in state:
        state['metadata'] = {}
    state['metadata'][key] = value
```

### Integrate External Systems

Export state:
```python
from state_manager import StateManager

sm = StateManager()
state = sm.load_state('run_20250310_143022')

# Export to external system
send_to_external(state)
```

## Success Criteria

A successful stateful run:

1. **Completes Reliably**: Handles interruptions gracefully
2. **Maintains Consistency**: Validation score ≥0.8
3. **Deduplicates URLs**: No duplicate web sources
4. **Resumes Correctly**: Exact continuation from interrupt point
5. **Provides Audit Trail**: Complete iteration history
6. **Recovers from Errors**: Rebuild capability for corruption

## Documentation

- **README.md**: Overview and quick start
- **docs/state_management_guide.md**: Complete usage guide
- **.claude/state/README.md**: State system reference
- **This file (CLAUDE.md)**: Project instructions

## Notes

- State files are JSON for human readability
- Atomic writes prevent corruption
- Multiple validation approaches ensure reliability
- Self-consistency principle proven in AI research
- System designed for production use cases

When working with this project, prioritize state integrity and trust the self-consistency validation system.