# Luka Loop (Generalized Ralph Loop)

This section defines how to scaffold and run the Luka Loop in any repo.

## Required Folder Layout (self-contained)

All artifacts live under `.rct/`:

```
.rct/
  spec.yaml           # Authoritative specification (ONLY spec source)
  plan.yaml           # Implementation plan
  checklist.yaml      # Task checklist (source of truth for status)
  blockers.yaml       # Generated by gate when blockers found
  outputs/
    CHECKLIST.md      # Rendered view only (NOT source of truth)
    phase-N/          # Per-phase reviewer outputs
  agents/             # Reviewer prompt templates
  prompts/            # Loop prompts (IMPL, ROLLBACK, FINALIZE)
  scripts/            # Loop scripts
```

**IMPORTANT:** There is NO `CHECKLIST.md` at repo root. The `docs/` folder may contain legacy/outdated content and should be ignored.

## Phase Status State Machine

```
in_progress ──(all tasks done)──► ready_for_gate ──(gate pass)──► ready_for_final ──(gate pass)──► approved
     ▲                                  │                              │
     │                              (blockers)                     (blockers)
     │                                  │                              │
     │                                  ▼                              │
     └────────(fixes done)──────── blockers ◄──────────────────────────┘
```

### Status Values

| Status | Meaning | Next Action |
|--------|---------|-------------|
| `in_progress` | Working on tasks | Impl agent works |
| `ready_for_gate` | All tasks done, first gate pass | Gate runs ALL reviewers |
| `ready_for_final` | First pass approved, final confirmation | Gate runs ALL reviewers again |
| `blockers` | Gate found issues | Impl agent fixes blockers |
| `approved` | Phase complete | Move to next phase |

### Automatic Transitions

- **Stale blockers**: If status=`blockers` but `blockers.yaml` is empty, auto-transitions to `ready_for_gate`
- **Gate timeout**: After 1 hour, creates timeout blocker and sets status to `blockers` (continues loop)

## Scaffold

Use the scaffold script to create the structure and templates:

```bash
python /path/to/skills/rct-methodology/scripts/luka_scaffold.py /path/to/repo
```

## Prompts

- `.rct/prompts/LUKA_IMPL.md` - Implementation agent instructions
- `.rct/prompts/LUKA_ROLLBACK.md` - Rollback agent for earlier-phase issues
- `.rct/prompts/LUKA_FINALIZE.md` - Final commit after all phases approved

## Scripts

| Script | Purpose |
|--------|---------|
| `luka_loop.sh` | Main orchestrator loop |
| `review_harness.sh` | Spawn reviewer agents |
| `gate_aggregate.py` | Aggregate verdicts, update status |
| `render_checklist.py` | Render human-readable CHECKLIST.md |
| `validate_checklist.py` | Validate checklist YAML structure |

## Reviewers

Default reviewer templates in `.rct/agents/`:
- `rct-guardian.md` - Representation contract tests
- `integration-sheriff.md` - Cross-component wiring
- `spec-auditor.md` - Requirements compliance
- `methodology-integrity.md` - Process abuse detection

Customize per project and add extra reviewers as needed.

## Safety Features

- **Atomic locking**: Uses `mkdir` for POSIX-atomic lock to prevent concurrent loops
- **Verdict race protection**: Uses `.done` marker files to detect complete writes
- **PID verification**: Checks process is actually codex before killing stale processes
- **Log size limits**: Caps reviewer logs at 10MB to prevent disk exhaustion
- **Phase ordering**: Always sorts phases by ID to ensure correct order

## Loop Behavior

1. **Implementation**: Codex uses LUKA_IMPL prompt
2. **Gate**: Reviewers run via review_harness (spawns codex per reviewer)
3. **Aggregate**: gate_aggregate writes gate_results + blockers to checklist.yaml
4. **Rollback**: If blockers have origin_phase, runs LUKA_ROLLBACK
5. **Finalize**: After all phases approved, runs LUKA_FINALIZE

## Commit Convention

Finalize prompt commits with prefix:

```
[Luka Loop] <summary>
```
