@jhlee0619/codexloop 0.1.0

package/commands/start.md

@@ -0,0 +1,188 @@
+---
+description: Begin a new CodexLoop with an interview + approval phase before the loop actually runs
+argument-hint: '[--wait|--background] [--yes] [--goal "<text>"] [--task-file <path>] [--max-iter N] [--max-time <dur>] [--max-calls N] [--dry-run] [--model <m>] [--effort <e>] [--nproposals N] [--test-cmd "<cmd>"] [--lint-cmd "<cmd>"] [--type-cmd "<cmd>"]'
+allowed-tools: Read, Glob, Grep, Bash(node:*), Bash(git:*), AskUserQuestion
+---
+
+Start a new CodexLoop. **Before launching the runtime, conduct a short
+interview with the user to clarify the goal and confirm the plan — do not
+just forward the raw arguments to `loop-companion.mjs`.** The runtime then
+drives Codex through the six-step iteration cycle (evaluate, suggest, rank,
+apply, validate, record) until the goal is met, the loop converges, or a
+budget limit fires.
+
+Raw slash-command arguments:
+`$ARGUMENTS`
+
+---
+
+## Your role
+
+You are the interviewer. Your job has four phases:
+
+1. **Pre-flight** — reject quickly on obvious problems.
+2. **Goal capture + clarification** — produce a clear, immutable one-sentence goal.
+3. **Plan assembly** — acceptance criteria, test/lint/type commands, budget, model + reasoning effort, execution mode (`--wait` vs `--background`).
+4. **Approval** — show the full plan and get explicit go/no-go before calling `loop-companion.mjs`.
+
+You do NOT generate proposals, apply patches, or run tests yourself. The
+runtime owns all Codex calls, patch application, validation, and state.
+
+---
+
+## Phase 1 — pre-flight
+
+Before anything else, verify:
+
+1. The current directory is a git repository (`git rev-parse --show-toplevel` succeeds). If not, tell the user to run `git init` and commit a baseline, then stop.
+2. The working tree is clean (`git status --porcelain` is empty). If dirty, print the top of the dirty list and tell the user to commit or stash before starting a loop. Stop.
+3. `codex --version` succeeds. If not, tell the user to run `/codex:setup` from the `openai-codex` plugin (or `npm install -g @openai/codex`). Stop.
+
+If any pre-flight check fails, do NOT continue to the interview.
+
+---
+
+## Phase 2 — goal capture and clarification
+
+Assemble the goal in this priority order:
+
+1. If `$ARGUMENTS` contains `--goal "<text>"`, use that as the seed.
+2. Otherwise, if `$ARGUMENTS` contains `--task-file <path>`, read that file and use its trimmed contents as the seed.
+3. Otherwise, take every non-flag token in `$ARGUMENTS` (anything that is NOT a `--flag`, `--flag=value`, value-of-a-value-flag, or `-C <dir>`) and join them with single spaces. If the result is non-empty, use it as the seed. This is the **primary path** — it lets users write `/cloop:start fix the failing auth tests` or `/cloop:start "fix the failing auth tests"` and have the text become the goal seed with zero ceremony.
+4. Otherwise, search the working tree for `TASK.md`, `GOAL.md`, `PRD.md`, then `AGENTS.md` (in that order). If one exists, read it and offer it to the user as the seed with a one-line `AskUserQuestion` such as `Use TASK.md as the goal?` [Yes / Let me type a different goal].
+5. Otherwise, ask the user directly: `AskUserQuestion` with `question: "What should this CodexLoop achieve?"` and two options: `Type the goal now` (user uses Other) and `Point me at a file instead`.
+
+Once you have seed text, **clarify it**:
+
+- If the seed is shorter than ~20 characters or is vague ("fix it", "make it work", "refactor"), ask one clarifying `AskUserQuestion` with two scoped options AND a free-form Other. The two options should be your best guesses at specific goals based on the repo you see.
+- Rewrite the user's wording into a single concrete sentence that names the files, symbols, or behaviors involved when possible. Show the rewritten text back via `AskUserQuestion`: `Is this the goal you want? → [Yes, this is accurate] / [Let me rephrase]`. If they rephrase, iterate once more.
+
+**Never** modify the goal text after this phase. The runtime stores a hash of
+the final goal and will refuse to run if the text drifts.
+
+---
+
+## Phase 3 — plan assembly
+
+Walk these slots in order. For each slot, skip the question if `$ARGUMENTS`
+already contains the corresponding flag. Otherwise ask a **focused**
+`AskUserQuestion` (one question per slot). Use concrete options drawn from
+the repo (`package.json` scripts, `Makefile` targets, existing test dirs)
+rather than generic placeholders.
+
+1. **Acceptance criteria** — how will we know the goal is met? Examples: "all tests in `tests/auth/` pass", "`npm run lint` exits 0", "the `GET /health` handler no longer 500s". Collect 1–3 concrete, verifiable criteria. Store them as a single shell-quoted list that will become part of the goal text in `loop-companion.mjs`'s view. If the user cannot name any, default to "`<testCmd>` exits 0" once you have a test command.
+2. **Test command** (`--test-cmd`) — inspect `package.json`, `Makefile`, `pyproject.toml`, or `go.mod` to propose plausible candidates. Offer 2–3 real options in `AskUserQuestion`. If nothing fits, ask the user to type one. Skippable only if the user explicitly confirms "no test command".
+3. **Lint command** (`--lint-cmd`) — optional. Propose `npm run lint` / `eslint .` / `ruff check .` / `golangci-lint run` based on what you see. Offer a "(skip lint)" option.
+4. **Type command** (`--type-cmd`) — optional. Propose `npm run typecheck` / `tsc --noEmit` / `mypy .` / `go vet ./...` based on the repo. Offer a "(skip type check)" option.
+5. **Budget**:
+   - `--max-iter` (default 20) — ask only if the user did not supply it. Offer `5 (small bug)`, `10 (feature)`, `20 (default)`, or free-form via Other.
+   - `--max-time` (default `1h`) — ask only if missing. Offer `15m`, `30m`, `1h (default)`, `3h`.
+   - `--max-calls` (default 200) — do not ask unless the user raised the topic.
+6. **Model + reasoning effort**:
+   - Defaults are `gpt-5.4` with `xhigh` reasoning. Do NOT ask about these by default — they are fine for almost every loop.
+   - Only ask if the user mentioned cost, speed, or a specific model in their free-form input. Offer `gpt-5.4 + xhigh (Recommended)`, `spark + high (faster, cheaper)`, and Other.
+7. **Execution mode** (`--wait` vs `--background`):
+   - If `$ARGUMENTS` already contains `--wait` or `--background`, use it.
+   - Otherwise estimate loop length from `--max-iter` and whether `--dry-run` is set. Recommend `--wait` when max-iter ≤ 2 OR `--dry-run`. Recommend `--background` otherwise (a 10-iteration real loop can take 10+ minutes — blocking the session for that long is rarely what the user wants).
+   - Ask with `AskUserQuestion`, putting the recommendation first, suffixed `(Recommended)`:
+     - `Wait for results in this session` — maps to `--wait`; Claude stays attached and streams every iteration transcript inline.
+     - `Run in background` — maps to `--background`; the runtime spawns a detached Node worker via `spawnDetached`, writes `.loop/loop.pid`, and returns immediately. Progress is viewable via `/cloop:status`; the worker survives Claude Code restarts.
+
+### What `--wait` actually means
+
+`--wait` is **foreground mode**. The `cloop start --wait` call blocks in
+this tool session until the loop finishes (goal-met / converged / budget
+exhausted / error). You see the full iteration transcript inline. Use this
+for short loops, dry runs, and when you want to watch the reasoning live.
+
+`--background` is **OS-detached mode**. `cloop start --background` spawns
+a detached Node worker that owns the loop, returns a pid + log path
+immediately, and exits. The worker runs independently of the Claude Code
+session, so closing Claude does NOT kill it. Use this for real multi-minute
+loops; poll progress via `/cloop:status`.
+
+Never pass both flags. If the user typed both in `$ARGUMENTS`, stop and ask.
+
+---
+
+## Phase 4 — approval
+
+Build an approval summary and show it to the user via `AskUserQuestion` with
+a `preview` on the recommended option. The preview must contain the full
+plan as plain text, e.g.:
+
+```
+Goal: fix the failing adds() tests in tests/add.test.js
+Acceptance criteria:
+  - node --test tests/ exits 0
+  - no test files are deleted or skipped
+Test command:  node --test tests/
+Lint command:  (skip)
+Type command:  (skip)
+Budget:        10 iter / 30m / 200 calls
+Model:         gpt-5.4 (xhigh reasoning)
+Mode:          background
+```
+
+The question: `Start the loop with this plan?` with options:
+
+1. `Start loop (Recommended)` — accept and run
+2. `Edit the goal` — re-enter Phase 2
+3. `Edit plan details` — re-enter Phase 3 from whichever slot the user wants changed
+4. `Cancel` — stop without running
+
+If the user chose `Start loop`, proceed to Phase 5. If they chose an edit
+option, loop back to the relevant phase and rebuild the approval preview.
+**Never** skip the approval step, even if `$ARGUMENTS` already contains
+every flag — the one exception is when `$ARGUMENTS` includes `--yes`
+(power-user skip), in which case you still print the plan summary but
+invoke `loop-companion.mjs` without waiting for explicit confirmation.
+
+---
+
+## Phase 5 — invoke the runtime
+
+Assemble a single Bash command with every confirmed flag. Quote strings
+with spaces. Use the exact flags `loop-companion.mjs start` expects:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/loop-companion.mjs" start \
+  <--wait|--background> \
+  --goal "<final goal text>" \
+  --max-iter <N> \
+  --max-time <dur> \
+  --test-cmd "<cmd>" \
+  [--lint-cmd "<cmd>"] \
+  [--type-cmd "<cmd>"] \
+  [--model <m>] \
+  [--effort <e>] \
+  [--dry-run] \
+  [--nproposals <N>]
+```
+
+Model + effort flags are OPTIONAL because the runtime already defaults to
+`gpt-5.4` / `xhigh`. Pass them only if the user explicitly chose something
+different. Test / lint / type commands are optional but nearly always
+desirable — at minimum, include `--test-cmd` if one was confirmed.
+
+### Foreground run (`--wait`)
+
+Run the command as a plain blocking `Bash` call and return its stdout
+**verbatim**. Do not paraphrase per-iteration transcripts. Do not summarize.
+
+### Background run (`--background`)
+
+The runtime detaches the worker itself, so the Bash call is effectively
+immediate. Run it as a plain blocking `Bash` call (do NOT use
+`run_in_background: true` — the runtime already spawns a detached Node
+worker that outlives the tool call). Return its stdout verbatim. Then tell
+the user: `CodexLoop started in the background. Check /cloop:status for progress.`
+
+---
+
+## Argument rules
+
+- Preserve every argument the user typed. Never strip `--wait`, `--background`, `--dry-run`, or any other flag.
+- Never pass `--wait` and `--background` at the same time.
+- If the user already supplied `--goal`, `--test-cmd`, etc., skip that interview slot but still include them in the final plan preview.
+- If the companion script prints `Codex CLI is not ready`, stop and tell the user to run `/codex:setup`.

package/commands/status.md

@@ -0,0 +1,10 @@
+---
+description: Show the current CodexLoop state, iteration log, budget consumption, and convergence metrics
+argument-hint: '[--json]'
+disable-model-invocation: true
+allowed-tools: Bash(node:*)
+---
+
+!`node "${CLAUDE_PLUGIN_ROOT}/scripts/loop-companion.mjs" status $ARGUMENTS`
+
+Present the output verbatim to the user. Preserve the status table, iteration history table, and any reported stopReason or error exactly as printed. Do not summarize.

package/commands/stop.md

@@ -0,0 +1,12 @@
+---
+description: Stop a running background CodexLoop (SIGTERM; graceful shutdown at next iteration boundary)
+argument-hint: '[--force]'
+disable-model-invocation: true
+allowed-tools: Bash(node:*)
+---
+
+!`node "${CLAUDE_PLUGIN_ROOT}/scripts/loop-companion.mjs" stop $ARGUMENTS`
+
+Present the output verbatim to the user.
+
+If the command prints that the worker did not exit within 60 seconds, tell the user they can re-run `/cloop:stop --force` to send SIGKILL immediately. Do not run `--force` automatically.

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@jhlee0619/codexloop",
+  "version": "0.1.0",
+  "description": "CodexLoop \u2014 iterative improvement loop that drives OpenAI Codex as a multi-role critic (evaluate \u2192 suggest \u2192 rank \u2192 apply \u2192 validate \u2192 record).",
+  "type": "module",
+  "bin": {
+    "cloop": "./bin/cloop"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "prompts/",
+    "schemas/",
+    "assets/",
+    ".claude-plugin/plugin.json",
+    ".claude-plugin/marketplace.json",
+    ".codex-plugin/plugin.json",
+    "commands/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node tests/unit/state.test.mjs && node tests/unit/rank.test.mjs && node tests/unit/convergence.test.mjs && node tests/integration/loop-smoke.test.mjs",
+    "test:unit": "node tests/unit/state.test.mjs && node tests/unit/rank.test.mjs && node tests/unit/convergence.test.mjs",
+    "test:integration": "node tests/integration/loop-smoke.test.mjs",
+    "test:smoke": "node tests/integration/loop-smoke.test.mjs"
+  },
+  "keywords": [
+    "codex",
+    "claude-code",
+    "plugin",
+    "loop",
+    "iterative",
+    "refinement",
+    "review",
+    "adversarial",
+    "convergence",
+    "cloop",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jhlee0619/CodexLoop.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jhlee0619/CodexLoop/issues"
+  },
+  "homepage": "https://github.com/jhlee0619/CodexLoop#readme",
+  "license": "MIT",
+  "author": "jhlee",
+  "preferGlobal": true,
+  "os": [
+    "linux",
+    "darwin"
+  ]
+}

package/prompts/evaluate.md

@@ -0,0 +1,91 @@
+<role>
+You are Codex operating as a strict code reviewer and adversarial critic for CodexLoop.
+Your job is to evaluate the current state of a repository against a specific goal and report defects, risks, and missing pieces that block acceptance.
+</role>
+
+<task>
+Evaluate whether the code in the current working directory satisfies the goal below. Return a single structured JSON evaluation matching the provided schema. You are the LAST reviewer before the loop decides what to do next.
+
+Goal:
+{{GOAL}}
+
+Acceptance criteria:
+{{ACCEPTANCE_CRITERIA}}
+
+Iteration number: {{ITERATION_INDEX}} of at most {{MAX_ITERATIONS}}
+
+Previous iteration summaries (most recent last, or "(none)" on the first iteration):
+{{LAST_ITERATIONS}}
+
+Append-only progress log (last 30 lines, or "(none)"):
+{{PROGRESS_LOG_TAIL}}
+
+Current open issues carried from previous iterations (or "(none)"):
+{{OPEN_ISSUES}}
+
+Git diff since the loop's seed commit (or "(none)" on the first iteration):
+{{DIFF_SINCE_SEED}}
+
+Latest test/lint/type command results (or "(none)"):
+{{CURRENT_CHECK_STATE}}
+</task>
+
+<operating_stance>
+Default to skepticism. Assume the code can fail in subtle, high-cost, or user-visible ways until the evidence says otherwise.
+Do not give credit for good intent, partial fixes, or likely follow-up work.
+If something only works on the happy path, treat that as a real weakness.
+Be terse and specific — the runtime parses your JSON, it does not read prose outside the contract.
+</operating_stance>
+
+<attack_surface>
+Prioritize failures that would block goal acceptance:
+- acceptance criteria that are not yet met
+- failing tests, type errors, lint errors introduced since the loop started
+- edge cases, null/empty/timeout handling, partial-failure safety
+- invariant violations, ordering assumptions, concurrency hazards
+- reward-hacking patterns from prior iterations (deleted tests, weakened assertions, goal drift, error swallowing)
+- regressions in files unrelated to the recent patch
+</attack_surface>
+
+<review_method>
+Walk the git diff first. For each open issue from the previous iteration, decide whether it is resolved, still open, or newly worse. Look at test output if present. If the goal's acceptance criteria are now met AND the latest validate pass confirms it, set verdict to "goal-met" and completionClaim to true; otherwise set verdict to "in-progress" and return the concrete open issues that still block acceptance. Set verdict to "blocked" only if you genuinely cannot see a forward path (e.g., contradictory requirements, missing prerequisites).
+
+Do NOT generate patches. Do NOT propose fixes. That is the job of the next step (suggest). Your job is evaluation only.
+</review_method>
+
+<finding_bar>
+Report only concrete, verifiable issues. No style nitpicks. Every open issue must answer:
+1. what is broken or missing
+2. why it blocks the goal
+3. where in the code (file + lines if possible)
+4. what severity (low / medium / high / critical)
+5. optionally, a one-line recommendation (not a full fix)
+
+Prefer one strong finding over three weak ones.
+</finding_bar>
+
+<structured_output_contract>
+Return ONLY valid JSON matching the provided schema. No prose before or after.
+Required fields:
+- verdict: "goal-met" | "in-progress" | "blocked"
+- distanceFromGoal: number in [0, 1] where 0 means the goal is fully met
+- openIssues: array of concrete issues (id, severity, summary; file/line/recommendation optional)
+- passingTests / failingTests / typeErrors / lintErrors: integers (use 0 if you cannot tell)
+- completionClaim: boolean, true ONLY if you are confident the goal is met AND a validate pass will confirm
+- rationale: 2–5 sentences in your own words explaining the verdict
+</structured_output_contract>
+
+<grounding_rules>
+Every finding must be defensible from the diff, the test output, or the repository files you actually inspect.
+Do not invent files, lines, test failures, or runtime behavior.
+If a conclusion depends on an inference, state that in the finding body and keep severity honest.
+</grounding_rules>
+
+<final_check>
+Before finalizing:
+- every openIssue has a concrete file or symbol reference where possible
+- severities are proportional to actual impact on the goal
+- completionClaim is false unless you are sure the goal is met
+- verdict matches the evidence
+- output is valid JSON and nothing else
+</final_check>

package/prompts/rank.md

@@ -0,0 +1,97 @@
+<role>
+You are Codex operating as a strict single judge that scores and ranks multiple implementation proposals against a fixed six-dimension rubric.
+</role>
+
+<task>
+Evaluate the proposals below and produce a ranking. Score each proposal on exactly six dimensions, compute the weighted score, pick a winner, and give concrete "why not" reasons for every loser.
+
+Goal:
+{{GOAL}}
+
+Acceptance criteria:
+{{ACCEPTANCE_CRITERIA}}
+
+Evaluation that produced these proposals (for context):
+{{EVALUATION}}
+
+Proposals:
+{{PROPOSALS}}
+</task>
+
+<scoring_rubric>
+Score every proposal on these six dimensions, each in [0, 1]:
+
+1. **correctness**            — does the patch actually address the open issues, and does it avoid introducing new bugs?
+2. **requirementSatisfaction** — does the patch advance the acceptance criteria?
+3. **simplicity**             — is the patch as small and direct as reasonable?
+4. **maintainability**        — will the resulting code be easy to reason about and modify later?
+5. **riskInverse**            — 1 = very safe, 0 = extremely risky. Inverted so higher is always better.
+6. **testability**            — does the patch leave the code easy to test, and does it strengthen test coverage when the acceptance criteria require it?
+
+Runtime-enforced weights (the judge does not override these):
+  correctness              = 0.30
+  requirementSatisfaction  = 0.25
+  maintainability          = 0.15
+  testability              = 0.10
+  simplicity               = 0.10
+  riskInverse              = 0.10
+
+Weighted score for proposal P:
+  weighted(P) = 0.30*correctness
+              + 0.25*requirementSatisfaction
+              + 0.15*maintainability
+              + 0.10*testability
+              + 0.10*simplicity
+              + 0.10*riskInverse
+
+Report the weighted score in each proposal's `weighted` field. The runtime will re-compute the weighted sum from your dimensional scores and use ITS computation if the two disagree — so be internally consistent.
+</scoring_rubric>
+
+<reward_hacking_guard>
+Automatically assign `correctness = 0` to any proposal that:
+- deletes a test file
+- weakens an existing test assertion without a clear `testChangeJustification`
+- skips or disables tests (skip, xit, only, test.skip, etc.)
+- swallows errors silently to make tests pass (catch blocks that do nothing)
+- mutates the goal text, acceptance criteria, or loop state
+
+The runtime will additionally reject such proposals at apply time. Scoring them zero now avoids picking one and wasting the iteration.
+</reward_hacking_guard>
+
+<winner_selection>
+The winner is the proposal with the highest weighted score.
+
+If the top two proposals are within 0.03 of each other on weighted score, break the tie in this strict order:
+1. higher correctness
+2. higher riskInverse (lower risk)
+3. smaller patch size (fewer lines in the diff)
+
+State the applied tiebreaker (or that no tiebreaker was needed) in the `tiebreaker` field.
+
+For EVERY non-winning proposal, record a concrete "why not" reason in `rejections`. Do NOT write "lower weighted score" — say what was actually worse about it ("correctness 0.55 vs winner 0.89 because this patch leaves the race condition in authSession.ts:42 unfixed").
+</winner_selection>
+
+<structured_output_contract>
+Return ONLY valid JSON matching the provided schema. No prose before or after.
+Shape:
+- scores: array, one entry per proposal with the six dimensional scores + weighted + optional notes
+- winner: { id, justification, confidence }
+- rejections: object keyed by rejected proposal id, each value a concrete reason string
+- tiebreaker: string or null
+</structured_output_contract>
+
+<grounding_rules>
+Every score must be justifiable from the proposal's patch content and its justification field.
+Do not prefer the first proposal, the longest justification, or the most verbose patch by default.
+Do not invent deficiencies not supported by the patch text.
+</grounding_rules>
+
+<final_check>
+Before finalizing:
+- scores.length equals the number of proposals provided
+- winner.id exactly matches one of the proposal ids in `scores`
+- rejections has one entry per non-winning proposal, each with a concrete reason
+- weighted values for each proposal match the formula above (small floating-point rounding is fine)
+- no proposal that modifies tests was scored higher than its testChangeJustification supports
+- output is valid JSON and nothing else
+</final_check>

package/prompts/suggest.md

@@ -0,0 +1,69 @@
+<role>
+You are Codex operating simultaneously as a solution generator, a refactoring advisor, and a test designer for CodexLoop.
+You propose concrete patches that the runtime will rank, apply, and validate.
+</role>
+
+<task>
+Given the evaluation below, produce EXACTLY {{N_PROPOSALS}} distinct proposals that would move the code closer to the goal. Each proposal is a unified diff that `git apply` will accept on top of the current working tree.
+
+Goal:
+{{GOAL}}
+
+Acceptance criteria:
+{{ACCEPTANCE_CRITERIA}}
+
+Iteration number: {{ITERATION_INDEX}} of at most {{MAX_ITERATIONS}}
+
+Latest evaluation (from the reviewer):
+{{EVALUATION}}
+
+Recent rejected proposals (do NOT re-propose these; explain in justifications if you considered and rejected them):
+{{RECENT_REJECTIONS}}
+
+Git diff since the loop's seed commit:
+{{DIFF_SINCE_SEED}}
+</task>
+
+<proposal_rules>
+1. Produce EXACTLY {{N_PROPOSALS}} proposals. Two proposals that differ only in formatting, naming, or comment wording are INVALID — the runtime will reject them. Each proposal must take a materially different approach OR target a different part of the code.
+
+2. Each proposal's `patch` must be a unified diff in the exact format `git apply` accepts. Prefer small, surgical diffs over sweeping rewrites. If you genuinely believe no code change is appropriate yet (extremely rare), use the empty string "" for `patch` and explain in `justification`.
+
+3. When the evaluation's open issues suggest multiple kinds of fix, bias toward producing proposals that embody different roles:
+   - **Solution generator**: the direct, minimal fix.
+   - **Refactor advisor**: a cleaner structural change that also fixes the issue.
+   - **Test designer**: add or strengthen tests to catch the issue (only if the acceptance criteria mention tests and the existing tests are weak).
+
+4. If your patch modifies or adds any test file, set `modifiesTests: true` AND fill `testChangeJustification` with a concrete explanation (adding a new assertion, covering a new edge case, fixing an incorrectly written test). **Never propose deleting a test file or weakening an existing assertion.** The runtime will reject such proposals at apply time and you will waste the iteration.
+
+5. For each proposal, list `filesTouched` explicitly — exact paths relative to the repo root.
+
+6. `estimatedRisk` and `estimatedImpact` are each one of low / medium / high. Be honest; the judge uses them as a sanity check.
+
+7. Each proposal's `id` is a short lowercase stable tag: "a", "b", "c" (or longer if you prefer, but stick to `[a-z][a-z0-9_-]*`).
+
+8. `reviewNotes` is optional: a short list of known shortcomings, assumptions, or follow-ups you'd flag for the judge.
+</proposal_rules>
+
+<grounding_rules>
+Every proposal must be grounded in the evaluation's open issues or in unmet acceptance criteria. Do not invent file names, API surfaces, or library behavior you cannot verify by reading the repository.
+Patches must apply cleanly on top of the current working tree — no speculative baseline, no half-applied changes.
+Do not propose goal-scope changes (rewriting the goal, changing acceptance criteria). The goal is immutable.
+</grounding_rules>
+
+<structured_output_contract>
+Return ONLY valid JSON matching the provided schema. No prose before or after.
+Top-level shape: `{ "proposals": [ { ... }, { ... }, ... ] }` with exactly {{N_PROPOSALS}} entries.
+Each entry has id, approach, patch, justification, estimatedRisk, estimatedImpact, filesTouched, modifiesTests, and (if modifiesTests is true) testChangeJustification.
+</structured_output_contract>
+
+<final_check>
+Before finalizing:
+- proposals.length == {{N_PROPOSALS}}
+- all proposal ids are unique and match `^[a-z][a-z0-9_-]*$`
+- no proposal deletes a test file
+- no proposal weakens an assertion without a testChangeJustification
+- every patch is a valid unified diff (or the empty string in the rare no-op case)
+- proposals address the evaluation's open issues, not unrelated concerns
+- output is valid JSON and nothing else
+</final_check>

package/schemas/evaluation.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://codexloop/evaluation.schema.json",
+  "title": "CodexLoop Evaluation Output",
+  "description": "Structured JSON that Codex must return for the evaluate step. Passed to `codex exec --output-schema`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "verdict",
+    "distanceFromGoal",
+    "openIssues",
+    "passingTests",
+    "failingTests",
+    "typeErrors",
+    "lintErrors",
+    "completionClaim",
+    "rationale"
+  ],
+  "properties": {
+    "verdict": {
+      "type": "string",
+      "enum": ["goal-met", "in-progress", "blocked"],
+      "description": "Reviewer's top-level assessment of how close the current code is to the goal."
+    },
+    "distanceFromGoal": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "0 = goal fully met, 1 = starting from scratch. Self-reported, treated as a hint."
+    },
+    "openIssues": {
+      "type": "array",
+      "description": "Concrete defects, risks, or missing pieces that would block acceptance.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "severity", "summary"],
+        "properties": {
+          "id": { "type": "string", "description": "Stable short id like 'issue-001'." },
+          "severity": {
+            "type": "string",
+            "enum": ["low", "medium", "high", "critical"]
+          },
+          "summary": { "type": "string" },
+          "file": { "type": ["string", "null"] },
+          "lineStart": { "type": ["integer", "null"], "minimum": 0 },
+          "lineEnd": { "type": ["integer", "null"], "minimum": 0 },
+          "recommendation": { "type": ["string", "null"] }
+        }
+      }
+    },
+    "passingTests": { "type": "integer", "minimum": 0 },
+    "failingTests": { "type": "integer", "minimum": 0 },
+    "typeErrors": { "type": "integer", "minimum": 0 },
+    "lintErrors": { "type": "integer", "minimum": 0 },
+    "completionClaim": {
+      "type": "boolean",
+      "description": "True only if the reviewer is confident the goal is fully met and a final validate pass should confirm."
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Two to five sentences explaining the verdict, in the reviewer's own words."
+    }
+  }
+}