---
name: step-03-commit
description: Commit PRD state after apex delegation
next_step: steps/step-04-check.md
---

# Step 3: Commit PRD State

> **CONTEXT OPTIMIZATION:** Read ONCE (first iteration). Subsequent iterations use compact-loop.md.

## YOUR TASK:

Commit PRD state changes after apex delegation. Apex already committed code — ralph commits orchestration state only.

---

## EXECUTION SEQUENCE:

### 1. Finalize Task in prd.json

> **BLOCKING:** If prd.tasks has any task with status='pending' that should be 'completed'
> based on actual code commits, FIX prd.json BEFORE committing.

```javascript
// PRD PATH RESOLUTION
const queuePath = '.ralph/modules-queue.json';
let currentPrdPath = '.ralph/prd.json';
if (fileExists(queuePath)) {
  const queue = readJSON(queuePath);
  currentPrdPath = queue.modules[queue.currentIndex].prdFile;
}

const prd = readJSON(currentPrdPath);
const now = new Date().toISOString();

// Apex updates individual task statuses. Ralph updates overall PRD state.
const allDone = prd.tasks.every(t => t.status === 'completed' || t.status === 'skipped');
prd.status = allDone ? 'completed' : prd.tasks.some(t => t.status === 'failed' || t.status === 'blocked') ? 'partial' : 'in_progress';

prd.config.current_iteration++;
prd.updated_at = now;

writeJSON(currentPrdPath, prd);
```

### 2. Update progress.txt

Append iteration summary (compact):
```markdown
## Iteration {iteration} — Delegated to /apex
Status: {status} | Completed: {completed}/{total}
Module: {current_module}
```

### 3. Stage and Commit (PRD state only)

```bash
git add {currentPrdPath} .ralph/progress.txt
[ -f .ralph/modules-queue.json ] && git add .ralph/modules-queue.json

git commit -m "$(cat <<'EOF'
chore(ralph): PRD state — iteration {iteration}, {completed}/{total} tasks

Module: {current_module}

Co-Authored-By: Claude AI <noreply@anthropic.com>
EOF
)"

COMMIT_HASH=$(git rev-parse --short HEAD)
```

### 4. Record Commit in History

```javascript
prd.history.push({
  iteration: prd.config.current_iteration - 1,
  action: 'iteration-completed',
  timestamp: now,
  commit_hash: COMMIT_HASH,
  notes: "Delegated to /apex"
});
writeJSON(currentPrdPath, prd);
```

### 5. Verify

```bash
git log -2 --oneline
```

---

## ERROR HANDLING:

- **Commit fails (pre-commit hook):** Fix issue, stage, create NEW commit (don't amend)
- **Task failed in apex:** PRD already reflects failure status — commit as-is

---

## NEXT STEP:

After commit, proceed to `./step-04-check.md`
