# SOP: Cross-Model Code Review (Claude ↔ GPT)

Cross-model review is an optional independent-review workflow. Use it only
when the task, configured review gate, issue owner, or release owner explicitly
requires a different model.

---

## When to Trigger

| Work Type                        | Review Required?         |
| -------------------------------- | ------------------------ |
| Application code, infra, scripts | When explicitly required |
| Docs/content                     | When explicitly required |
| Research summaries               | When explicitly required |

If no review requirement is present, use focused self-verification and the
normal human/CI review path.

---

## Workflow

1. **Authoring task completes** (status remains `in-progress`).
2. **Create review task** referencing the original:
   - Title: `Review: <orig task title>`
   - Type: `code`
   - Sprint/project identical
   - Description includes acceptance criteria + diff link(s)
3. **Assign to opposite model** (via OpenClaw or other orchestrator):
   ```
   Hey Codex, review PR for task_1234. Checklist below.
   ```
4. **Reviewer steps**:
   - Pull branch / run tests (if applicable)
   - Use `docs/SOP-agent-task-workflow.md` for lifecycle
   - Log findings as subtasks or checklist entries
   - Severity tagging: High / Medium / Low / Nit
5. **Outcomes**:
   - ✅ No issues → comment summary + mark review task done → original task can go to `done`
   - ❌ Issues → create fix subtasks on original task, set status `blocked` until resolved
6. **Comms**: Reviewer leaves structured comment:
   ```
   ## Findings
   - [High] Path traversal (see notes)
   - [Low] Missing aria-label
   ## Verdict
   Changes required.
   ```
7. **Audit trail**: Update commit message or PR description with `[author: claude-sonnet-4-5][reviewed-by: gpt-5.1-codex]`.

---

## Review Checklist

| Category          | Questions                                                        |
| ----------------- | ---------------------------------------------------------------- |
| **Security**      | Auth enforced? Input validated? Path traversal? Secrets handled? |
| **Reliability**   | Error handling? Race conditions? Timeouts? File locking?         |
| **Performance**   | Avoid O(n²)? Streaming vs buffering? Caching appropriate?        |
| **Accessibility** | Keyboard support? aria-labels? Color contrast?                   |
| **Docs**          | README/docs updated? Migration notes? Tests updated?             |

Adapt per task type.

---

## Prompt Template (Reviewer)

```
You are the cross-model reviewer. The code was authored by <model>. Apply the checklist:
1. Pull latest branch <branch>.
2. Run tests (if any).
3. For each issue, note severity (High/Medium/Low/Nit) + file/line + fix suggestion.
4. Summarize verdict: Approve or Changes Required.
5. Update task <id> with findings and completion summary.
```

Store in `prompt-registry/cross-model-review.md`.

---

## Recording Findings

- Add subtasks under the original task for each confirmed bug.
- Reference GitHub issues if they existed.
- Use Lessons Learned to capture systemic insights (e.g., “Always use withFileLock() when touching JSON stores”).

---

## Escalation

| Scenario                                        | Action                                            |
| ----------------------------------------------- | ------------------------------------------------- |
| Reviewer disagrees with author but fix is minor | Leave comment + request change.                   |
| Reviewer finds high severity bug                | Block task, ping human immediately.               |
| Author disputes reviewer findings               | Create triage meeting or ask human to adjudicate. |

---

## Review Gates (Veritas Kanban Enforcement)

VK's built-in enforcement gates can make this optional workflow a structural
requirement for selected workspaces or tasks:

1. **reviewGate** — Blocks task completion unless all four reviewScores (security, reliability, performance, accessibility) are 10. This is the automated enforcement layer that ensures the cross-model review checklist has been completed rigorously.

2. **closingComments** — Requires a substantive review comment (≥20 characters) before task completion. Ensures the reviewer leaves documented findings, not just scores.

3. **How they work together**:
   - Author (Model A) completes code; task remains `in-progress`
   - Reviewer (Model B) runs the cross-model review checklist
   - Reviewer scores all 4 dimensions via the API: `PATCH /api/tasks/{id}` with `reviewScores`
   - Reviewer leaves findings as comments (must be ≥20 chars if closingComments enabled)
   - If reviewGate is enabled, task **cannot** move to `done` until all scores are 10
   - If closingComments is enabled, at least one substantive comment is required

4. **Enabling gates**:

   ```bash
   curl -X PATCH http://localhost:3001/api/settings/features \
     -H 'Content-Type: application/json' \
     -d '{"enforcement": {"reviewGate": true, "closingComments": true}}'
   ```

5. **Handling gate failures** — If task completion returns a 400 error with `REVIEW_GATE_FAILED` or `CLOSING_COMMENT_REQUIRED`, the reviewer must address the deficiency (raise a score, add a comment) and retry.

6. **Recommendation**: Enable `reviewGate` and `closingComments` only when the
   workspace deliberately requires independent scored review. Leave them off
   when normal task verification and human/CI review are sufficient.

7. Full documentation: See [Enforcement Gates](enforcement.md) for all available gates, configuration options, and API reference.

---

RF-002 recorded a 91% accuracy rate for this review method. That result supports
using the method when selected; it does not make it a universal gate.
