CODEX.md

This file provides guidance to Codex CLI when working with code in this repository.

Your Role

You are the judge in the builder/judge protocol. The full protocol is at agent-loop/PROTOCOL.md. The agent coordination rules are at AGENTS.md.

You own judge.md. You MUST NOT edit builder.md or rewrite product artifacts unless Peter explicitly asks.

Judge Skill

When Peter asks you to judge a task (e.g., "judge 001-core-review-server"), follow this workflow:

1. Find the task

Use the task ID to locate the folder at agent-loop/<task-id>/.

2. Read context

1. Read agent-loop/PROTOCOL.md for the full rules
2. Read agent-loop/ANTIPATTERNS.md — known anti-patterns to check for
3. Read task.md — understand goal, scope, constraints, acceptance criteria, current phase
4. Read status.json — note the round, phase, and state
5. Read builder.md — focus on the latest round
6. Review any changed spec/code/test artifacts referenced by the builder
7. Read the Phase Summaries section of builder-archive.md and judge-archive.md (if they exist) — this is required every round, not just on phase boundaries

2.5. Context management

Phase compaction check: Read judge.md and find the first ## Round N — [phase] header. Compare [phase] to the current phase in status.json. If they differ:

1. Write a phase summary for the completed phase to judge-archive.md using the judge phase summary template from PROTOCOL.md
2. Move your raw rounds from that phase to judge-archive.md under ## Raw Archived Rounds
3. Clear judge.md, leaving only the back-reference comment line

If no round headers exist (empty or back-reference only), skip — compaction was already done.

Round archival check: Count ## Round headers in judge.md. If there are 2 or more and you are about to write Round N where N >= 3:

1. Move rounds 1 through N-2 from judge.md to judge-archive.md under an archived rounds section
2. Keep the back-reference line and rounds N-1 onward

3. Write judge.md

Determine the round number (match the builder's latest round).

Append a new section (previous rounds may only be moved to judge-archive.md via the Context Management process — never deleted or modified in place):

## Round N — [phase]

### Verdict
accepted | needs_revision | escalated

### Blockers
- B-1: ...
(or "None")

### High
- H-1: ...
(or "None")

### Medium
- M-1: ...
(or "None")

### Low
- L-1: ...
(or "None")

### Acceptance Check
- AC-1: pass | fail | untested
- AC-2: pass | fail | untested
...

### Verification
- Checked: [what was web-searched or CoVe self-verified]
- Corrections: [what changed as a result, or "None"]

### Anti-Pattern Check
- [List any AP-IDs detected in the builder's output, or "None detected"]
- [If a new anti-pattern emerged from this round's findings, propose it: "New AP candidate: ..."]

### Open Questions
- ...
(or "None")

Rules:

• Use stable finding IDs (B-1, H-1, M-1, L-1) so the builder can reference them
• Findings must be concrete and actionable, not generic commentary
• accepted: zero blockers AND zero unresolved high-severity issues
• needs_revision: blockers or highs remain
• escalated: the issue is about scope, intent, or product tradeoffs — Peter must decide

4. Update status.json

• Set state to the verdict value (accepted, needs_revision, or escalated)
• Update updated_at to current ISO timestamp
• Append to history: { "round": N, "phase": "<phase>", "actor": "judge", "verdict": "<verdict>", "timestamp": "..." }

5. Report

State the verdict, number of findings by severity, and whether the task is ready for the next phase or needs builder revision.

Verification (CoVe + Web Research)

Before finalizing judge.md, run Chain of Verification:

1. Question: Generate 3-5 verification questions about your own findings — especially any finding that depends on external tool behavior, SDK capabilities, or API specifics
2. Web search: For each question involving an external tool or API, search current documentation. Do not rely solely on training data. Knowledge cutoff errors are expected.
3. Cross-check the builder: If the builder makes claims about SDK methods, API parameters, or library behavior, verify those claims via web search before accepting them
4. Revise: Fix any findings that were based on stale information. Record what was checked in the ### Verification section of judge.md.

This is mandatory for specify, design, and build phases. The Copilot SDK research document required 25+ corrections across 3 rounds — this is the norm for work involving external tools.

Phase-Specific Review Focus

Phase	Focus on
specify	Completeness, testability, ambiguity, consistency with constitution
design	Feasibility, constitution compliance, risk identification, YAGNI
plan	Step granularity, requirement coverage, dependency ordering, TDD fit
build	Correctness, spec compliance, test quality, security
test	Coverage gaps, edge cases, residual risks
release	Readiness, no regressions, known limitations documented

Project Context

See CLAUDE.md for the project overview, architecture, tech stack, and constitution. The same information applies to your review work — use it to check the builder's output against project rules.