**RESET STATE UTILITY**

Reset or rebuild state for a run. Use when state becomes corrupted or needs to be reconstructed from output files.

---

**USAGE:**
```
/reset-state <run_id> [--mode]
```

**PARAMETERS:**
- `run_id`: The run identifier to reset
- `--mode`: (Optional) Reset mode: `delete`, `rebuild`, or `verify` (default: verify)

**MODES:**
- `verify`: Check state integrity without changes
- `rebuild`: Reconstruct state from output files
- `delete`: Completely remove state file (WARNING: irreversible)

**EXAMPLES:**
```bash
# Verify state integrity
/reset-state run_20250310_143022

# Rebuild state from output files
/reset-state run_20250310_143022 --rebuild

# Delete state completely
/reset-state run_20250310_143022 --delete
```

---

**MODE 1: VERIFY (Default)**

Check state consistency without modifications:

```python
import json
import os
from glob import glob

state_file = f".claude/state/{run_id}.json"

if not os.path.exists(state_file):
    print(f"ERROR: State file not found: {state_file}")
    exit(1)

# Load state
with open(state_file, 'r') as f:
    state = json.load(f)

print("VERIFYING STATE CONSISTENCY...")
print("")

# Run all consistency checks
checks = []

# Check 1: Schema validation
required_fields = [
    "run_id", "spec_path", "output_dir", "total_count",
    "status", "created_at", "updated_at", "completed_iterations",
    "iterations", "used_urls", "validation"
]
schema_valid = all(field in state for field in required_fields)
checks.append({
    "name": "Schema Validation",
    "passed": schema_valid,
    "details": "All required fields present" if schema_valid else f"Missing fields"
})

# Check 2: File count
output_dir = state['output_dir']
file_count = len(glob(f"{output_dir}/*")) if os.path.exists(output_dir) else 0
expected_count = state['completed_iterations']
file_check = file_count >= expected_count
checks.append({
    "name": "File Count",
    "passed": file_check,
    "details": f"Expected: >={expected_count}, Actual: {file_count}"
})

# Check 3: Iteration consistency
iteration_count = len([i for i in state['iterations'] if i['status'] == 'completed'])
iteration_check = iteration_count == expected_count
checks.append({
    "name": "Iteration Records",
    "passed": iteration_check,
    "details": f"Expected: {expected_count}, Actual: {iteration_count}"
})

# Check 4: URL uniqueness
total_urls = len(state['used_urls'])
unique_urls = len(set(state['used_urls']))
url_check = total_urls == unique_urls
checks.append({
    "name": "URL Uniqueness",
    "passed": url_check,
    "details": f"Total: {total_urls}, Unique: {unique_urls}"
})

# Check 5: File existence
missing_files = []
for iteration in state['iterations']:
    if iteration['status'] == 'completed':
        if not os.path.exists(iteration['output_file']):
            missing_files.append(iteration['output_file'])
existence_check = len(missing_files) == 0
checks.append({
    "name": "File Existence",
    "passed": existence_check,
    "details": f"Missing: {len(missing_files)} files" if missing_files else "All files exist"
})

# Check 6: Timestamp validity
try:
    from datetime import datetime
    created = datetime.fromisoformat(state['created_at'].replace('Z', '+00:00'))
    updated = datetime.fromisoformat(state['updated_at'].replace('Z', '+00:00'))
    timestamp_check = updated >= created
    checks.append({
        "name": "Timestamp Validity",
        "passed": timestamp_check,
        "details": "Valid chronology" if timestamp_check else "Updated before created"
    })
except:
    checks.append({
        "name": "Timestamp Validity",
        "passed": False,
        "details": "Invalid timestamp format"
    })

# Display results
for check in checks:
    status = "✓ PASS" if check["passed"] else "✗ FAIL"
    print(f"{status}: {check['name']}")
    print(f"  {check['details']}")
    print("")

# Compute self-consistency score
consistency_score = sum(c["passed"] for c in checks) / len(checks)
print(f"Consistency Score: {consistency_score:.2f} ({consistency_score * 100:.0f}%)")
print("")

# Recommendations
if consistency_score >= 0.8:
    print("STATUS: State is consistent and reliable")
    print("ACTION: No action needed")
elif consistency_score >= 0.5:
    print("STATUS: State has issues but may be recoverable")
    print("ACTION: Consider running with --rebuild to fix")
else:
    print("STATUS: State is significantly corrupted")
    print("ACTION: Rebuild with --rebuild or delete with --delete")

print("")
```

---

**MODE 2: REBUILD**

Reconstruct state from output directory:

```python
import json
import os
from glob import glob
from datetime import datetime
import hashlib

state_file = f".claude/state/{run_id}.json"

# Load original state or create minimal
if os.path.exists(state_file):
    print("Loading original state for reference...")
    with open(state_file, 'r') as f:
        original_state = json.load(f)
    spec_path = original_state.get('spec_path', 'unknown')
    output_dir = original_state['output_dir']
    total_count = original_state.get('total_count', 'unknown')
else:
    print("No original state found. Building from scratch...")
    print("Enter required information:")
    spec_path = input("Spec path: ")
    output_dir = input("Output directory: ")
    total_count = input("Total count (or 'infinite'): ")

# Verify output directory exists
if not os.path.exists(output_dir):
    print(f"ERROR: Output directory not found: {output_dir}")
    exit(1)

print("")
print("REBUILDING STATE FROM OUTPUT DIRECTORY...")
print("")

# Scan output directory
output_files = sorted(glob(f"{output_dir}/*"))
print(f"Found {len(output_files)} files in {output_dir}")
print("")

# Extract iteration numbers and build records
iterations = []
used_urls = set()

for file_path in output_files:
    # Try to extract iteration number from filename
    filename = os.path.basename(file_path)
    # Assume pattern: *_<number>.<ext> or iteration_<number>.<ext>
    import re
    match = re.search(r'_(\d+)\.[^.]+$', filename)
    if match:
        iteration_num = int(match.group(1))
    else:
        # Fallback: use file order
        iteration_num = len(iterations) + 1

    # Compute file hash for validation
    with open(file_path, 'rb') as f:
        file_hash = hashlib.sha256(f.read()).hexdigest()[:16]

    # Try to extract web URL from file content
    web_url = "unknown"
    try:
        with open(file_path, 'r') as f:
            content = f.read(1000)  # Read first 1000 chars
            # Look for common URL patterns in comments
            url_match = re.search(r'https?://[^\s<>"]+', content)
            if url_match:
                web_url = url_match.group(0)
                used_urls.add(web_url)
    except:
        pass

    # Get file modification time
    mtime = os.path.getmtime(file_path)
    completed_at = datetime.fromtimestamp(mtime).isoformat() + 'Z'

    iterations.append({
        "number": iteration_num,
        "status": "completed",
        "output_file": file_path,
        "web_url": web_url,
        "started_at": completed_at,  # Approximate
        "completed_at": completed_at,
        "validation_hash": file_hash,
        "metadata": {"rebuilt": True}
    })

# Sort by iteration number
iterations.sort(key=lambda x: x['number'])

# Rebuild state structure
rebuilt_state = {
    "run_id": run_id,
    "spec_path": spec_path,
    "output_dir": output_dir,
    "total_count": total_count,
    "url_strategy_path": original_state.get('url_strategy_path') if 'original_state' in locals() else None,
    "status": "paused",  # Safe default
    "created_at": iterations[0]['completed_at'] if iterations else datetime.now().isoformat() + 'Z',
    "updated_at": iterations[-1]['completed_at'] if iterations else datetime.now().isoformat() + 'Z',
    "completed_iterations": len(iterations),
    "failed_iterations": 0,
    "iterations": iterations,
    "used_urls": list(used_urls),
    "validation": {
        "last_check": datetime.now().isoformat() + 'Z',
        "consistency_score": 1.0,  # Freshly rebuilt
        "issues": [],
        "rebuilt": True
    }
}

# Backup original if exists
if os.path.exists(state_file):
    backup_file = f"{state_file}.backup_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
    os.rename(state_file, backup_file)
    print(f"Original state backed up to: {backup_file}")

# Write rebuilt state
with open(state_file, 'w') as f:
    json.dump(rebuilt_state, f, indent=2)

print(f"State rebuilt successfully!")
print(f"  Iterations: {len(iterations)}")
print(f"  URLs discovered: {len(used_urls)}")
print(f"  State file: {state_file}")
print("")
print("Verifying rebuilt state...")
print("")

# Run verification on rebuilt state
# (Re-run MODE 1 verification logic)
```

---

**MODE 3: DELETE**

Completely remove state file:

```python
import os
from datetime import datetime

state_file = f".claude/state/{run_id}.json"

if not os.path.exists(state_file):
    print(f"State file not found: {state_file}")
    exit(0)

# Load state for summary
with open(state_file, 'r') as f:
    state = json.load(f)

print("WARNING: You are about to DELETE the following state:")
print("")
print(f"  Run ID: {state['run_id']}")
print(f"  Spec: {state['spec_path']}")
print(f"  Output Dir: {state['output_dir']}")
print(f"  Iterations: {state['completed_iterations']}")
print(f"  Created: {state['created_at']}")
print("")
print("This action is IRREVERSIBLE.")
print("Output files will NOT be deleted, only state tracking.")
print("")

response = input("Type 'DELETE' to confirm: ")

if response == "DELETE":
    # Backup before deletion
    backup_file = f"{state_file}.deleted_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
    os.rename(state_file, backup_file)

    print(f"State deleted.")
    print(f"Backup saved to: {backup_file}")
    print("")
    print("To completely remove: rm {backup_file}")
else:
    print("Deletion cancelled.")
```

---

**SELF-CONSISTENCY VALIDATION:**

All modes apply self-consistency principle:

**Verify Mode:**
- Samples 6 independent validation approaches
- Uses majority voting for consistency score
- Multiple checks ensure comprehensive validation

**Rebuild Mode:**
- Cross-validates rebuilt state against filesystem
- Verifies file hashes for integrity
- Re-runs full verification after rebuild

**Delete Mode:**
- Creates backup before deletion
- Provides detailed confirmation
- Enables recovery if needed

---

**COMMON USE CASES:**

**Case 1: State-File Mismatch**
```
Problem: Manual file deletions created inconsistency
Solution: /reset-state <run_id> --rebuild
Result: State reconstructed from actual files
```

**Case 2: Corruption Investigation**
```
Problem: Uncertain if state is reliable
Solution: /reset-state <run_id> --verify
Result: Detailed consistency report
```

**Case 3: Clean Slate**
```
Problem: Want to restart with same run_id
Solution: /reset-state <run_id> --delete
Result: State removed, can create new run
```

**Case 4: URL List Corruption**
```
Problem: Duplicate URLs in state
Solution: /reset-state <run_id> --rebuild
Result: URLs re-extracted from files, deduplicated
```

---

**SAFETY FEATURES:**

**Backup Protection:**
- Original state always backed up before changes
- Backup includes timestamp
- Can restore from backup if needed

**Confirmation Required:**
- Delete mode requires explicit confirmation
- User sees summary before deletion
- Can cancel at any point

**Non-Destructive:**
- Never deletes output files
- Only modifies state tracking
- Rebuild can be re-run if needed

**Verification:**
- All modes validate their results
- Self-consistency checks applied
- Clear reporting of issues

---

**TROUBLESHOOTING:**

**Rebuild produces wrong iteration count:**
```
Check filename patterns in output directory
Verify iteration numbers in filenames
Consider manual state editing
```

**Verify shows low score but rebuild fails:**
```
Output directory may be corrupted too
Check file permissions
Inspect sample output files manually
```

**Delete backup grows large:**
```
Old backups can be manually removed
Check .claude/state/*.backup_* files
Delete old backups: rm .claude/state/*.backup_*
```

---

**NOTES:**

- Always run verify before rebuild
- Rebuild is best-effort based on filesystem
- Some metadata may be lost in rebuild (e.g., exact timing)
- Delete provides recovery window via backup
- Self-consistency score indicates reliability