devlyn-cli 1.12.4 → 1.13.0

package/CLAUDE.md

@@ -1,5 +1,15 @@
 # Project Instructions
 
+## Quick Start
+
+For most work, the recommended sequence is:
+
+1. `/devlyn:ideate` — turn an idea into roadmap-ready specs
+2. `/devlyn:auto-resolve "Implement per spec at docs/roadmap/phase-N/X-name.md"` — hands-free build → evaluate → polish
+3. `/devlyn:preflight` — verify the implementation matches the roadmap before shipping
+
+All three default to `--engine auto`, which routes each phase to the optimal model (Codex GPT-5.4 for hard coding, Claude Opus 4.7 for evaluation/critique). The cross-model GAN dynamic — different models build vs critique — catches what single-model pipelines miss.
+
 ## General
 
 - Proactively use subagents and skills where needed
@@ -20,7 +30,7 @@
 When investigating bugs, analyzing features, or exploring code:
 
 1. **Define exit criteria upfront** - Ask "What does 'done' look like?" before starting
-2. **Checkpoint progress** - Use TodoWrite every 5-10 minutes to save findings
+2. **Checkpoint progress** - Use the task tools (TaskCreate / TaskUpdate) every 5-10 minutes to save findings
 3. **Output intermediate summaries** - Provide "Current Understanding" snapshots so work isn't lost if interrupted
 4. **Always deliver findings** - Never end mid-analysis; at minimum output:
    - Files examined
@@ -28,7 +38,7 @@ When investigating bugs, analyzing features, or exploring code:
    - Remaining unknowns
    - Recommended next steps
 
-For complex investigations, use `/devlyn:team-resolve` to assemble a multi-perspective investigation team, or spawn parallel Task agents to explore different areas simultaneously.
+For complex investigations, use `/devlyn:team-resolve` to assemble a multi-perspective investigation team, or spawn parallel Agent subagents to explore different areas simultaneously.
 
 ## UI/UX Workflow
 
@@ -42,11 +52,11 @@ The full design-to-implementation pipeline:
 ## Feature Development
 
 1. **Plan first** - Always output a concrete implementation plan with specific file changes before writing code
-2. **Track progress** - Use TodoWrite to checkpoint each phase
+2. **Track progress** - Use the task tools (TaskCreate / TaskUpdate) to checkpoint each phase
 3. **Test validation** - Write tests alongside implementation; iterate until green
 4. **Small commits** - Commit working increments rather than large changesets
 
-For complex features, use the Plan agent to design the approach before implementation.
+For complex features, spawn the `Plan` subagent (`Agent` tool with `subagent_type: "Plan"`) to design the approach before implementation.
 
 ## Automated Pipeline (Recommended Starting Point)
 
@@ -72,8 +82,7 @@ Optional flags:
 - `--skip-review` — skip team-review phase
 - `--skip-clean` — skip clean phase
 - `--skip-docs` — skip update-docs phase
-- `--engine auto|codex|claude` — intelligent model routing. `auto` (default) routes each phase and team role to the optimal model (Claude or Codex GPT-5.4) based on benchmark data. `codex` forces Codex for implementation, Claude for evaluation. `claude` uses Claude for everything. Requires codex-mcp-server for `auto` and `codex` modes.
-- `--with-codex [evaluate|review|both]` — (legacy, superseded by `--engine`) use OpenAI Codex as cross-model evaluator/reviewer (requires codex-mcp-server)
+- `--engine auto|codex|claude` — intelligent model routing. `auto` (default) routes each phase and team role to the optimal model based on benchmark data: Codex GPT-5.4 handles BUILD and FIX (SWE-bench Pro lead), Claude Opus 4.7 handles EVALUATE and CHALLENGE (long-context retrieval + skeptical reasoning). Different models build vs critique — the cross-model GAN dynamic catches what single-model pipelines miss. `codex` forces Codex for implementation, Claude for orchestration and Chrome MCP. `claude` uses Claude for everything. Requires codex-mcp-server for `auto` and `codex` modes.
 
 ## Preflight Check (Post-Roadmap Verification)
 
@@ -92,7 +101,7 @@ Optional flags:
 - `--autofix` — auto-promote CRITICAL/HIGH findings and run auto-resolve
 - `--skip-browser` — skip browser validation
 - `--skip-docs` — skip documentation audit
-- `--engine auto|codex|claude` — route code-auditor to Codex (better at code analysis), docs/browser to Claude
+- `--engine auto|codex|claude` — `auto` (default) routes the code-auditor to Codex (SWE-bench Pro +11.7pp on code analysis); the docs-auditor and browser-auditor always use Claude regardless of `--engine` (writing-quality strength on docs drift; Chrome MCP tools are session-bound to Claude Code)
 
 **Recommended workflow**: `/devlyn:ideate` → `/devlyn:auto-resolve` (repeat) → `/devlyn:preflight` → fix gaps → `/devlyn:preflight` (verify)
 
@@ -152,11 +161,13 @@ Steps 4-6 are optional depending on the scope of changes. `/simplify` should alw
 
 ## Context Window Management
 
-When a conversation approaches context limits (50k+ tokens):
-1. Check usage with `/context`
-2. Create a HANDOFF.md summarizing: what was attempted, what succeeded, what failed, and next steps
-3. Start a new session with `/clear`
-4. Load context: `@HANDOFF.md Read this file and continue the work`
+Claude 4.5 / 4.6 / 4.7 models auto-compact the conversation as it approaches the context limit, so you can keep working indefinitely without manual handoffs in most cases. Don't stop early due to token-budget concerns — the model continues from where it left off after compaction.
+
+For genuinely multi-context-window work (e.g., a roadmap with many phases), persist state to disk so the next instance can resume:
+- All `auto-resolve` and `preflight` runs already write durable state to `.devlyn/*.md` (done-criteria, BUILD-GATE, EVAL-FINDINGS, BROWSER-RESULTS, CHALLENGE-FINDINGS, PREFLIGHT-REPORT) and to git commits — pick up by reading those files plus `git log`.
+- For long investigations, write progress notes to a `HANDOFF.md` and resume with `@HANDOFF.md continue from where this left off` if you need a fresh window.
+
+Manually clearing with `/clear` is rarely necessary — only do it when context is genuinely irrelevant to the next task.
 
 ## Communication Style
 

package/README.md

@@ -146,19 +146,6 @@ Works across the full pipeline:
 
 </details>
 
-<details>
-<summary>Legacy: <code>--with-codex</code> (superseded by <code>--engine</code>)</summary>
-
-```
-/devlyn:auto-resolve "fix the auth bug" --with-codex
-```
-
-> `--with-codex evaluate` (default) · `--with-codex review` · `--with-codex both`
-
-`--engine auto` subsumes `--with-codex both` with broader coverage — Codex is used for build, fix, and 4 team roles, not just evaluate/review.
-
-</details>
-
 ---
 
 ## Manual Commands
@@ -258,7 +245,7 @@ Selected during install. Run `npx devlyn-cli` again to add more.
 
 | Server | Description |
 |---|---|
-| `codex-cli` | Codex MCP server — enables `--engine auto/codex` intelligent model routing and legacy `--with-codex` mode |
+| `codex-cli` | Codex MCP server — enables `--engine auto/codex` intelligent model routing |
 | `playwright` | Playwright MCP — powers browser-validate Tier 2 |
 
 </details>

package/config/skills/devlyn:auto-resolve/SKILL.md

@@ -11,6 +11,14 @@ $ARGUMENTS
 
 <pipeline_workflow>
 
+<orchestrator_context>
+This pipeline is long-horizon agentic work. As the orchestrator, you spawn many subagents and read their handoff files; your own context grows over the run.
+
+- Your context window is auto-compacted as it approaches its limit, so do not stop tasks early due to token-budget concerns. Keep the run going.
+- All durable state lives in `.devlyn/*.md` (done-criteria, BUILD-GATE, EVAL-FINDINGS, BROWSER-RESULTS, CHALLENGE-FINDINGS) and in git commits. If your context is cleared mid-run, the next instance can resume from those files plus `git log`. Keep them up to date.
+- Best results come from `xhigh` effort. If you are running on lower effort and notice shallow reasoning during phase decisions, escalate.
+</orchestrator_context>
+
 <autonomy_contract>
 This pipeline runs hands-free. The user launches it to walk away and come back to finished work, so the quality of this run is measured by how far it gets without human intervention. Apply these behaviors throughout every phase:
 
@@ -21,6 +29,17 @@ This pipeline runs hands-free. The user launches it to walk away and come back t
 5. **Treat questions as a signal to act instead.** If you notice yourself drafting a question to the user mid-pipeline, convert it into a decision + log entry and spawn the next phase.
 </autonomy_contract>
 
+<engine_routing_convention>
+Every phase in this pipeline routes its work to the optimal model per `references/engine-routing.md`. The convention is the same everywhere:
+
+- The phase prompt body below is **engine-agnostic** — same instructions whether Codex or Claude executes it.
+- For phases routed to **Codex** (per the routing table), call `mcp__codex-cli__codex` per the patterns in `engine-routing.md` (How to Spawn a Codex BUILD/FIX Agent / How to Spawn a Codex Role / How to Spawn a Dual Role).
+- For phases routed to **Claude**, spawn an Agent subagent with `mode: "bypassPermissions"` and pass the prompt body verbatim.
+- `--engine claude` forces all phases to Claude. `--engine codex` forces implementation/analysis to Codex (Claude still handles orchestration and Chrome MCP). `--engine auto` (default) uses the routing table per phase.
+
+Phase-level "Engine routing" notes below are short reminders only — `engine-routing.md` is the single source of truth.
+</engine_routing_convention>
+
 ## PHASE 0: PARSE INPUT
 
 1. Extract the task/issue description from `<pipeline_config>`.
@@ -33,22 +52,21 @@ This pipeline runs hands-free. The user launches it to walk away and come back t
    - `--skip-docs` (false) — skip update-docs phase
    - `--skip-build-gate` (false) — skip the deterministic build gate (Phase 1.4). Not recommended — the build gate is the primary defense against "tests pass locally, breaks in CI/Docker/production" class of bugs.
    - `--build-gate MODE` (auto) — controls build gate behavior. `auto`: detect project type and run appropriate build/typecheck/lint commands; if Dockerfile(s) are present, Docker builds are included automatically. `strict`: auto + treat warnings as errors. `no-docker`: auto but skip Docker builds even if Dockerfiles exist (for faster iteration). `skip`: same as --skip-build-gate.
-   - `--with-codex` (false) — use OpenAI Codex as a cross-model evaluator/reviewer via `mcp__codex-cli__*` MCP tools. Accepts: `evaluate`, `review`, or `both` (default when flag is present without value). When enabled, Codex provides an independent second opinion from a different model family, creating a GAN-like dynamic where Claude builds and Codex critiques. **Ignored if `--engine` is set** (engine routing subsumes this).
    - `--engine MODE` (auto) — controls which model handles each pipeline phase and team role. Modes:
-     - `auto` (default): each phase and team role routes to the optimal model based on benchmark data. Requires Codex MCP server. Subsumes `--with-codex both`.
+     - `auto` (default): each phase and team role routes to the optimal model based on benchmark data. Requires Codex MCP server. Codex handles BUILD/FIX (SWE-bench Pro lead) and several team roles; Claude handles EVALUATE, CHALLENGE, BROWSER, and orchestration — creating a GAN-like dynamic where the builder and critic are always different models.
      - `codex`: Codex handles implementation/analysis phases, Claude handles orchestration, evaluation, and Chrome MCP.
      - `claude`: all phases use Claude subagents. No Codex calls.
 
    Flags can be passed naturally: `/devlyn:auto-resolve fix the auth bug --max-rounds 3 --skip-docs`
    Engine examples: `--engine auto`, `--engine codex`, `--engine claude`
-   Codex examples (legacy): `--with-codex` (both), `--with-codex evaluate`, `--with-codex review`
-   If no flags are present, use defaults. **The default engine is `auto` — if the user does not pass `--engine`, treat it as `--engine auto`.**
+   If no flags are present, use defaults. The default engine is `auto` — if the user does not pass `--engine`, treat it as `--engine auto`.
+
+   **Consolidated flag**: `--with-codex` (and its variants `evaluate`/`review`/`both`) was rolled into the smarter `--engine auto` default. If the user passes it, inform them once and proceed with `--engine auto`: "Note: `--with-codex` was consolidated into `--engine auto` (default), which provides broader Codex coverage — Codex now handles BUILD, FIX, and several team roles automatically. No flag needed. Continuing with `--engine auto`."
 
 3. **Engine pre-flight** (runs unless `--engine claude` was explicitly passed):
-   - The default engine is `auto`. If the user did not pass `--engine`, the engine is `auto` — NOT `claude`.
+   - The default engine is `auto`. If the user did not pass `--engine`, the engine is `auto` — not `claude`.
    - Read `references/engine-routing.md` for the full routing table.
    - Call `mcp__codex-cli__ping` to verify the Codex MCP server is available. If ping fails, warn the user and offer: [1] Continue with `--engine claude` (fallback), [2] Abort.
-   - Exception: if `--engine` is not set AND `--with-codex` is explicitly enabled (legacy), read `references/codex-integration.md` instead and run its pre-flight check.
 
 4. Announce the pipeline plan:
 ```
@@ -57,16 +75,13 @@ Task: [extracted task description]
 Engine: [auto / codex / claude]
 Phases: Build → Build Gate → [Browser] → Evaluate → [Fix loop if needed] → Simplify → [Review] → Challenge → [Security] → [Clean] → [Docs]
 Max evaluation rounds: [N]
-Cross-model evaluation (Codex): [evaluate / review / both / disabled / subsumed by --engine]
 ```
 
 ## PHASE 1: BUILD
 
-**Engine routing**: If `--engine` is `auto` or `codex`, read `references/engine-routing.md` "How to Spawn a Codex BUILD/FIX Agent" section. Call `mcp__codex-cli__codex` with `model: "gpt-5.4"`, `reasoningEffort: "xhigh"`, `sandbox: "workspace-write"`, `fullAuto: true`, and the full agent prompt below as the `prompt` parameter. If `--engine` is `claude`, spawn a Claude subagent as described below.
+**Engine**: BUILD row of the routing table — Codex on `auto`/`codex`, Claude on `claude`. Per `<engine_routing_convention>` above. Subagents do not have access to skills, so the prompt below includes everything they need inline.
 
-Spawn a subagent using the Agent tool with `mode: "bypassPermissions"` to investigate and implement the fix. The subagent does NOT have access to skills, so include all necessary instructions inline.
-
-Agent prompt — pass this to the Agent tool (or to `mcp__codex-cli__codex` prompt if engine routes to Codex):
+Agent prompt — pass this to the spawned executor:
 
 Investigate and implement the following task. Work through these phases in order:
 
@@ -84,9 +99,7 @@ Read relevant files in parallel. Build a clear picture of what exists and what n
 - Feature: implementation-planner + test-engineer (+ ux-designer, architecture-reviewer, api-designer as needed)
 - Refactor: architecture-reviewer + test-engineer
 - UI/UX: product-designer + ux-designer + ui-designer (+ accessibility-auditor as needed)
-Each teammate investigates from their perspective and sends findings back.
-
-**Engine routing for teammates**: If the orchestrator's `--engine` is `auto` or `codex`, read `references/engine-routing.md` for per-role routing. Roles marked **Codex** are called via `mcp__codex-cli__codex` instead of spawning Agent teammates — include the full role prompt and issue context inline. Roles marked **Claude** use normal Agent teammates. Roles marked **Dual** run both in parallel and merge findings. The orchestrator relays Codex role outputs to Claude teammates that need them.
+Each teammate investigates from their perspective and sends findings back. Per-role engine routing follows the team-resolve table in `references/engine-routing.md`; Dual roles run both models in parallel.
 
 **Phase D — Synthesize and implement**: After all teammates report, compile findings into a unified plan. Implement the solution — no workarounds, no hardcoded values, no silent error swallowing. For bugs: write a failing test first, then fix. For features: implement following existing patterns, then write tests. For refactors: ensure tests pass before and after.
 
@@ -139,13 +152,11 @@ For failures: include the FULL error output (not truncated) and extract root fil
 
 Triggered only when PHASE 1.4 returns FAIL.
 
-Track a round counter (shared with the main fix loop counter against `max-rounds`). If `round >= max-rounds`, stop with a clear failure report — do NOT continue to evaluate/browser/etc. Code that doesn't build cannot be meaningfully evaluated or tested.
+Track a round counter. The build-gate fix loop and the main evaluate fix loop share **one global round counter** capped at `max-rounds` — increments from this loop and from PHASE 2.5 both count against the same total. If `round >= max-rounds`, stop with a clear failure report and do not continue to evaluate/browser/etc. Code that doesn't build cannot be meaningfully evaluated or tested.
 
-**Engine routing**: Same as PHASE 2.5 FIX LOOP — if `--engine` is `auto` or `codex`, use `mcp__codex-cli__codex` with `workspace-write` and `fullAuto: true`. If `--engine` is `claude`, spawn a Claude subagent.
+**Engine**: FIX LOOP row of the routing table.
 
-Spawn a subagent using the Agent tool with `mode: "bypassPermissions"`.
-
-Agent prompt — pass this to the Agent tool (or to `mcp__codex-cli__codex` prompt if engine routes to Codex):
+Agent prompt — pass this to the spawned executor:
 
 Read `.devlyn/BUILD-GATE.md` — it contains deterministic build/typecheck/lint failures from real compiler output. These are not opinions; the compiler rejected this code. Fix every listed failure at the root cause level.
 
@@ -158,7 +169,7 @@ For each failure:
 
 **After the agent completes**:
 1. **Checkpoint**: `git add -A && git commit -m "chore(pipeline): build gate fix round [N]"`
-2. Increment round counter
+2. Increment the global round counter (shared with PHASE 2.5)
 3. Go back to PHASE 1.4 (re-run the gate)
 
 ## PHASE 1.5: BROWSER VALIDATE (conditional)
@@ -186,11 +197,23 @@ You are a browser validation agent. Read the skill instructions at `.claude/skil
 
 ## PHASE 2: EVALUATE
 
-Spawn a subagent using the Agent tool with `mode: "bypassPermissions"` to evaluate the work. Include all evaluation instructions inline.
+**Engine**: EVALUATE row of the routing table — Claude on every engine. When `--engine auto`, Codex built the code, so Claude evaluating Codex's work is the GAN dynamic by default; no separate Codex evaluation pass is needed.
 
-Agent prompt — pass this to the Agent tool:
+Spawn a subagent using the Agent tool with `mode: "bypassPermissions"`. Include all evaluation instructions inline (subagents do not have access to skills).
+
+Agent prompt — pass this to the spawned executor:
 
-You are an independent evaluator. Your job is to grade work produced by another agent, not to praise it. You will be too lenient by default — fight this tendency. When in doubt, score DOWN, not up. A false negative (missing a bug) ships broken code. A false positive (flagging a non-issue) costs minutes of review. The cost is asymmetric.
+You are an independent evaluator. Your job is to grade work produced by another agent against a specific rubric, not to praise it.
+
+<investigate_before_answering>
+Never claim a file:line or assert a behavior you have not opened and read. The done-criteria file is the rubric — read it first. Then read every changed/new file in full before marking anything VERIFIED or FAILED. Findings without a real file:line behind them are speculation; exclude them.
+</investigate_before_answering>
+
+<coverage_over_filtering>
+Your goal is coverage at this stage, not severity filtering. Report every issue you find — uncertain ones, low-severity ones, all of them. The fix loop and the orchestrator's verdict logic do the filtering downstream. Each finding includes its severity and your confidence so the downstream layers can rank them; your job is to surface them, not pre-decide which ones matter.
+
+This matters because under-reporting is the asymmetric cost: a missed bug ships broken code, a flagged non-issue costs a few minutes of review.
+</coverage_over_filtering>
 
 **Step 1 — Read the done criteria**: Read `.devlyn/done-criteria.md`. This is your primary grading rubric. Every criterion must be verified with evidence.
 
@@ -215,56 +238,64 @@ You are an independent evaluator. Your job is to grade work produced by another
 - [ ] criterion — FAILED: what's wrong, file:line
 ## Findings Requiring Action
 ### CRITICAL
-- `file:line` — description — Fix: suggested approach
+- `file:line` — description — Confidence: high/med/low — Fix: suggested approach
 ### HIGH
-- `file:line` — description — Fix: suggested approach
+- `file:line` — description — Confidence: high/med/low — Fix: suggested approach
+### MEDIUM / LOW
+- `file:line` — description — Confidence: high/med/low — Fix: suggested approach
 ## Cross-Cutting Patterns
 - pattern description
 ```
 
-Verdict rules: BLOCKED = any CRITICAL issues. NEEDS WORK = HIGH or MEDIUM issues that should be fixed. PASS WITH ISSUES = only LOW cosmetic notes. PASS = clean.
+Verdict rules:
+- `BLOCKED` — any CRITICAL issues
+- `NEEDS WORK` — HIGH or MEDIUM issues
+- `PASS WITH ISSUES` — only LOW cosmetic notes
+- `PASS` — clean
 
-Important: Do NOT label findings as "pre-existing" or "out of scope" to avoid fixing them. If a problem exists in the current code and relates to the done criteria, it's a finding regardless of when it was introduced. The goal is working software, not blame attribution.
+Findings labeled "pre-existing" or "out of scope" still count if they relate to the done criteria. The goal is working software, not blame attribution.
 
-Calibration examples to guide your judgment:
-- A catch block that logs but doesn't surface error to user = HIGH (not MEDIUM). Logging is not error handling.
-- A `let` that could be `const` = LOW note only. Linters catch this.
-- "The error handling is generally quite good" = WRONG. Count the instances. Name the files. "3 of 7 async ops have error states. 4 are missing: file:line, file:line..."
+Calibration examples:
+- A catch block that logs but doesn't surface the error to the user → HIGH (not MEDIUM). Logging is not error handling.
+- A `let` that could be `const` → LOW. Linters catch this.
+- "The error handling is generally quite good" is not a finding. Count the instances and name the files. "3 of 7 async ops have error states. 4 are missing: file:line, file:line…"
 
-Do NOT delete `.devlyn/done-criteria.md` or `.devlyn/EVAL-FINDINGS.md` — the orchestrator needs them.
+Do not delete `.devlyn/done-criteria.md` or `.devlyn/EVAL-FINDINGS.md` — the orchestrator needs them.
 
 **After the agent completes**:
 1. Read `.devlyn/EVAL-FINDINGS.md`
 2. Extract the verdict
-3. **If `--engine` is `auto` or `codex`**: The evaluate phase always uses Claude (see `references/engine-routing.md`). When `--engine auto`, the builder was Codex — Claude evaluating Codex's work creates the GAN dynamic automatically. No separate Codex evaluation pass is needed.
-   **If `--engine` is not set and `--with-codex` includes `evaluate` or `both`** (legacy): Read `references/codex-integration.md` and follow the "PHASE 2-CODEX: CROSS-MODEL EVALUATE" section. This runs Codex as a second evaluator and merges findings into `EVAL-FINDINGS.md`.
-4. Branch on verdict (from the merged findings if Codex was used):
+3. Branch on verdict:
    - `PASS` → skip to PHASE 3
    - `PASS WITH ISSUES` → go to PHASE 2.5 (fix loop) — LOW-only issues are still issues; fix them
    - `NEEDS WORK` → go to PHASE 2.5 (fix loop)
    - `BLOCKED` → go to PHASE 2.5 (fix loop)
-5. If `.devlyn/EVAL-FINDINGS.md` was not created, treat as NEEDS WORK and log a warning — absence of evidence is not evidence of absence
+4. If `.devlyn/EVAL-FINDINGS.md` was not created, treat as NEEDS WORK and log a warning — absence of evidence is not evidence of absence
 
 ## PHASE 2.5: FIX LOOP (conditional)
 
 Track the current round number. If `round >= max-rounds`, stop the loop and proceed to PHASE 3 with a warning that unresolved findings remain.
 
-**Engine routing**: If `--engine` is `auto` or `codex`, call `mcp__codex-cli__codex` with `model: "gpt-5.4"`, `reasoningEffort: "xhigh"`, `sandbox: "workspace-write"`, `fullAuto: true`, and the fix prompt below. Use a fresh call each round (no sessionId reuse — sandbox/fullAuto only apply on first call of a session). If `--engine` is `claude`, spawn a Claude subagent as below.
+**Engine**: FIX LOOP row of the routing table. Use a fresh Codex call each round (no `sessionId` reuse — sandbox/fullAuto only apply on the first call of a session).
 
-Spawn a subagent using the Agent tool with `mode: "bypassPermissions"` to fix the evaluation findings.
+Agent prompt — pass this to the spawned executor:
 
-Agent prompt — pass this to the Agent tool (or to `mcp__codex-cli__codex` prompt if engine routes to Codex):
+Read every findings file present in `.devlyn/`:
+- `.devlyn/EVAL-FINDINGS.md` — issues from the independent evaluator (PHASE 2)
+- `.devlyn/BROWSER-RESULTS.md` — issues from browser validation (PHASE 1.5), if present and the verdict is `NEEDS WORK` or `BLOCKED`
 
-Read `.devlyn/EVAL-FINDINGS.md` — it contains specific issues found by an independent evaluator. Fix every finding regardless of severity (CRITICAL, HIGH, MEDIUM, and LOW). The pipeline loops until the evaluator returns PASS — there is no "shippable with issues" shortcut.
+Fix every finding regardless of severity (CRITICAL, HIGH, MEDIUM, and LOW). The pipeline loops until the relevant verdict returns PASS — there is no "shippable with issues" shortcut.
 
 The original done criteria are in `.devlyn/done-criteria.md` — your fixes must still satisfy those criteria. Do not delete or weaken criteria to make them pass.
 
-For each finding: read the referenced file:line, understand the issue, implement the fix. No workarounds — fix the actual root cause. Run tests after fixing. Update `.devlyn/done-criteria.md` to mark fixed items.
+For each finding: read the referenced file:line (or browser step / console error), understand the issue, implement the fix. No workarounds — fix the actual root cause. Run tests after fixing. Update `.devlyn/done-criteria.md` to mark fixed items.
 
 **After the agent completes**:
 1. **Checkpoint**: Run `git add -A && git commit -m "chore(pipeline): fix round [N] complete"` to preserve the fix
-2. Increment round counter
-3. Go back to PHASE 2 (re-evaluate)
+2. Increment the global round counter (shared with PHASE 1.4-fix)
+3. Re-run the phase that triggered the fix:
+   - If invoked from PHASE 2 (eval failure) → go back to PHASE 2 to re-evaluate
+   - If invoked from PHASE 1.5 (browser failure) → go back to PHASE 1.5 to re-validate the browser, then proceed to PHASE 2 only if browser passes
 
 ## PHASE 3: SIMPLIFY
 
@@ -281,21 +312,18 @@ Review the recently changed files (use `git diff HEAD~1` to see what changed). L
 
 Skip if `--skip-review` was set.
 
-Spawn a subagent using the Agent tool with `mode: "bypassPermissions"` for a multi-perspective review.
+**Engine**: REVIEW (team) — per-role routing per the team-review table in `references/engine-routing.md`. Dual roles run both models in parallel and merge findings.
 
-Agent prompt — pass this to the Agent tool:
+Spawn a subagent using the Agent tool with `mode: "bypassPermissions"`.
 
-Review all recent changes in this codebase (use `git diff main` and `git status` to determine scope). Assemble a review team using TeamCreate with specialized reviewers: security reviewer, quality reviewer, test analyst. Add UX reviewer, performance reviewer, or API reviewer based on the changes.
+Agent prompt — pass this to the spawned executor:
 
-**Engine routing for reviewers**: If the orchestrator passed `--engine auto` or `--engine codex`, read `references/engine-routing.md` for per-role routing in the "team-review roles" table. Route each reviewer to Claude Agent or `mcp__codex-cli__codex` accordingly. For Dual roles (security-reviewer), run both models in parallel and merge findings per the "How to Spawn a Dual Role" section. For `--engine claude`, all reviewers are Claude Agent teammates.
+Review all recent changes in this codebase (use `git diff main` and `git status` to determine scope). Assemble a review team using TeamCreate with specialized reviewers: security reviewer, quality reviewer, test analyst. Add UX reviewer, performance reviewer, or API reviewer based on the changes. Per-role engine routing follows the team-review table in `references/engine-routing.md`; Dual roles run both models in parallel and merge findings.
 
-Each reviewer evaluates from their perspective, sends findings with file:line evidence grouped by severity (CRITICAL, HIGH, MEDIUM, LOW). After all reviewers report, synthesize findings, deduplicate, and fix any CRITICAL issues directly. For HIGH issues, fix if straightforward.
+Each reviewer reports findings with file:line evidence grouped by severity (CRITICAL, HIGH, MEDIUM, LOW) and a confidence level. After all reviewers report, synthesize findings, deduplicate, and fix any CRITICAL issues directly. For HIGH issues, fix if straightforward.
 
 Clean up the team after completion.
 
-**If `--engine` is set**: engine routing already handles cross-model review via per-role routing — skip the legacy `--with-codex` review step below.
-**If `--with-codex` includes `review` or `both`** (legacy, only when `--engine` is not set): Read `references/codex-integration.md` and follow the "PHASE 4B: CODEX REVIEW" section. This runs Codex's independent code review and reconciles findings with the Claude team review.
-
 **After the review phase completes**:
 1. If CRITICAL issues remain unfixed, log a warning in the final report
 2. **Checkpoint**: Run `git add -A && git commit -m "chore(pipeline): review fixes complete"` if there are changes
@@ -306,23 +334,27 @@ Every prior phase used checklists, done-criteria, or structured categories. This
 
 This is what catches the things structured reviews miss — subtle logic that technically works but isn't the right approach, assumptions nobody questioned, patterns that are fine but not best-practice, and integration seams that look correct in isolation but feel wrong when you read the whole changeset.
 
+**Engine**: CHALLENGE row — Claude on every engine. The diff was likely produced by Codex on `--engine auto`; Claude reading it cold preserves the cross-model dynamic.
+
 Spawn a subagent using the Agent tool with `mode: "bypassPermissions"`.
 
-Agent prompt — pass this to the Agent tool:
+Agent prompt — pass this to the spawned executor:
 
-You are a senior engineer doing a final skeptical review before this code ships to production. You have NOT seen any prior reviews, test results, or design docs — read the code cold.
+You are a senior engineer doing a final skeptical review before this code ships to production. You have not seen any prior reviews, test results, or design docs — read the code cold.
 
-Run `git diff main` to see all changes. Read every changed file in full (not just the diff hunks — you need surrounding context).
+<investigate_before_answering>
+Anchor every finding in code you have actually opened. Run `git diff main` for the change surface, then read each changed file in full (not just the hunks — surrounding context matters). Findings without a real file:line and a quote from the code are speculation; exclude them.
+</investigate_before_answering>
 
-Your job is NOT to check boxes. Your job is to find the things that would make a staff engineer say "hold on, let's talk about this before we ship." Think about:
+Your job is not to check boxes. Your job is to find the things that would make a staff engineer say "hold on, let's talk about this before we ship." Think about:
 
 - Would this approach survive a 10x traffic spike? A midnight oncall page? A junior dev maintaining it 6 months from now?
 - Are there assumptions baked in that nobody stated out loud? Hardcoded limits, implicit ordering, missing edge cases in business logic?
 - Is the error handling actually helpful, or does it just prevent crashes while leaving the user confused?
 - Are there simpler, more idiomatic ways to do what this code does? Not "clever" alternatives — genuinely better approaches?
-- Would you mass-confidence approve this PR, or would you leave comments?
+- Would you confidently approve this PR, or would you leave comments?
 
-Be brutally honest. Do NOT start with praise. Do NOT soften findings. Every finding must include `file:line` and a concrete fix — not "consider improving" but "change X to Y because Z."
+Be direct and concrete. Do not open with praise. Every finding must include `file:line` and a concrete fix — not "consider improving" but "change X to Y because Z."
 
 Write `.devlyn/CHALLENGE-FINDINGS.md`:
 
@@ -334,7 +366,27 @@ Write `.devlyn/CHALLENGE-FINDINGS.md`:
 - `file:line` — what's wrong — Fix: concrete change
 ```
 
-Verdict: PASS only if you would mass-confidently mass-ship this code with your name on it. If you found anything CRITICAL or HIGH, verdict is NEEDS WORK.
+<examples>
+<example index="1">
+GOOD finding (anchored, specific, fixable):
+### CRITICAL
+- `src/api/orders/cancel.ts:42` — `await db.transaction(...)` is missing — the read of `order.status` and the write of `order.status = "cancelled"` are not atomic, so two concurrent cancellations both succeed and the inventory hook fires twice. Fix: wrap the read+write in `db.transaction()` and re-check `order.status === "pending"` inside the transaction before the update.
+</example>
+<example index="2">
+BAD finding (vague, unanchored, not actionable):
+### HIGH
+- The error handling could be improved. Consider being more defensive throughout.
+
+Why this is bad: no file:line, no specific failure, no concrete fix. Either delete the finding or replace it with a real one anchored to a specific call site.
+</example>
+<example index="3">
+GOOD finding (idiom / approach issue):
+### MEDIUM
+- `src/components/UserList.tsx:18-34` — fetching `/api/users` inside `useEffect` and managing loading/error state by hand re-implements what the project already does with the `useFetch` hook in `src/hooks/useFetch.ts`. Fix: replace the manual `useState`+`useEffect` with `useFetch('/api/users')` so this list inherits retry, cache, and abort handling.
+</example>
+</examples>
+
+Verdict: `PASS` only if you would confidently ship this code with your name on it. If you found anything CRITICAL or HIGH, verdict is `NEEDS WORK`.
 
 **After the agent completes**:
 1. Read `.devlyn/CHALLENGE-FINDINGS.md`
@@ -402,9 +454,37 @@ Skip if `--skip-docs` was set.
 
 Spawn a subagent using the Agent tool with `mode: "bypassPermissions"`.
 
-Agent prompt — pass this to the Agent tool:
+Agent prompt — pass this to the Agent tool (include the original task description from `<pipeline_config>` so the agent can detect spec paths):
+
+You are the Docs phase of the auto-resolve pipeline. You have two jobs, in this order.
+
+**Job 1 — Roadmap Sync** (run first, only if this task implemented a roadmap item)
+
+The ideate skill produces specs at `docs/roadmap/phase-N/{id}-{slug}.md` and tracks them in `docs/ROADMAP.md`. When auto-resolve finishes a task for one of those specs, the index lies until someone flips it — and nobody does, so it rots. Your job is to flip it.
+
+1. **Detect whether this task was a spec implementation.** Look at the original task description you were passed. Match against this regex: `docs/roadmap/phase-\d+/[^\s"'\`)]+\.md`. If there is no match, or if `docs/ROADMAP.md` does not exist in the repo, Job 1 is a no-op — skip straight to Job 2.
+2. **Sanity-check against the diff.** Run `git diff main --stat` (or `git diff HEAD~N --stat` if on main). If the diff is empty or contains only doc changes, the build phase produced nothing — do NOT flip any status. Leave Job 1 untouched and continue to Job 2.
+3. **Read the spec file** at the matched path. If its frontmatter already has `status: done`, Job 1 is already done — skip to Job 2. Otherwise:
+   - Set `status: done` in the frontmatter.
+   - Add a `completed: YYYY-MM-DD` field (use today's date from `date +%Y-%m-%d`).
+   - Do not change any other fields, and do not touch the body of the spec.
+4. **Update `docs/ROADMAP.md`.** Find the row whose `#` column matches the spec's `id` (e.g., row starting `| 2.3 |`). Change its Status column to `Done`. Do not touch any other row, and do not reformat the table.
+5. **Check whether the phase is now fully Done.** Read every row of the phase's table (the one containing the just-flipped row). If every row's Status is `Done`, archive the phase:
+   - Cut the phase's `## Phase N: …` heading and table out of the active section of ROADMAP.md.
+   - If no `## Completed` section exists at the bottom of the file, create one just above end-of-file (below Decisions if Decisions exists).
+   - Add a `<details>` block for the phase inside Completed, using the format defined in the devlyn:ideate skill's Context Archiving section. Pull each item's completion date from its spec file's `completed:` frontmatter; if a spec has none, use today's date.
+   - Item spec files stay on disk — do not delete them. Only the index row moves.
+6. **Report.** In your summary, say explicitly what you did: "Flipped spec 2.3 to done, updated ROADMAP.md row." And if applicable: "Phase 2 was fully Done — archived to Completed block."
+
+**Safety invariants** — violating any of these means stop Job 1 and report it:
+- Never flip a spec to `done` without a non-empty `git diff` touching non-doc files.
+- Never flip multiple specs in one run — one task, one spec.
+- Never edit a row whose `#` doesn't exactly match the spec's `id`.
+- Never delete spec files.
+
+**Job 2 — General doc sync**
 
-Synchronize documentation with recent code changes. Use `git log --oneline -20` and `git diff main` to understand what changed. Update any docs that reference changed APIs, features, or behaviors. Do not create new documentation files unless the changes introduced entirely new features with no existing docs. Preserve all forward-looking content: roadmaps, future plans, visions, open questions.
+Synchronize the rest of the documentation with recent code changes. Use `git log --oneline -20` and `git diff main` to understand what changed. Update any docs that reference changed APIs, features, or behaviors. Do not create new documentation files unless the changes introduced entirely new features with no existing docs. Preserve all forward-looking content: future plans, visions, open questions. (Job 1 already handled the roadmap index — don't second-guess it here.)
 
 **After the agent completes**:
 1. **Checkpoint**: Run `git add -A && git commit -m "chore(pipeline): docs updated"` if there are changes
@@ -430,22 +510,20 @@ After all phases complete:
 **Pipeline Summary**:
 | Phase | Status | Notes |
 |-------|--------|-------|
-| Build (team-resolve) | [completed] | [brief summary] |
+| Build (team-resolve) | [completed] | [brief summary; engine that ran it] |
 | Build gate | [completed / skipped / FAIL after N rounds] | [project types detected, commands run, pass/fail per command] |
 | Browser validate | [completed / skipped / auto-skipped] | [verdict, tier used, console errors, flow results] |
-| Evaluate (Claude) | [PASS/NEEDS WORK after N rounds] | [verdict + key findings] |
-| Evaluate (Codex) | [completed / skipped] | [Codex-only findings count, merged verdict] |
+| Evaluate | [PASS/NEEDS WORK after N rounds] | [verdict + key findings] |
 | Fix rounds | [N rounds / skipped] | [what was fixed] |
 | Simplify | [completed / skipped] | [changes made] |
-| Review (Claude team) | [completed / skipped] | [findings summary] |
-| Review (Codex) | [completed / skipped] | [Codex-only findings, agreed findings] |
+| Review (team) | [completed / skipped] | [findings summary; per-role engines if --engine auto] |
 | Challenge | [PASS / NEEDS WORK] | [findings count, fixes applied] |
 | Security review | [completed / skipped / auto-skipped] | [findings or "no security-sensitive changes"] |
 | Clean | [completed / skipped] | [items cleaned] |
 | Docs (update-docs) | [completed / skipped] | [docs updated] |
 
-**Evaluation Rounds**: [N] of [max-rounds] used
-**Final Verdict**: [last evaluation verdict]
+**Evaluation Rounds**: [N] of [max-rounds] used (shared budget across PHASE 1.4-fix and PHASE 2.5)
+**Final Verdict**: [last evaluation verdict, or "BUILD GATE FAILED — code does not compile" if PHASE 1.4 exhausted the round budget before PHASE 2 ran]
 
 **Commits created**:
 [git log output]

package/config/skills/devlyn:auto-resolve/references/engine-routing.md

@@ -116,7 +116,7 @@ Rationale for `--engine auto` choices:
 
 Rationale:
 - FRAME/EXPLORE/CONVERGE: Claude — ambiguous intent handling, multi-perspective reasoning.
-- CHALLENGE: When `--engine auto`, Codex runs the rubric pass as critic (same role as `--with-codex` but automatic). When `--engine codex`, Claude runs the challenge (role reversal — builder and critic are always different models).
+- CHALLENGE: When `--engine auto`, Codex runs the rubric pass as critic — automatic on every run. When `--engine codex`, Claude runs the challenge (role reversal — builder and critic are always different models).
 - DOCUMENT: Claude — writing quality for spec generation.
 
 ---
@@ -127,10 +127,12 @@ Rationale:
 |-------|--------------|----------------|-----------------|
 | EXTRACT COMMITMENTS | Claude | Codex | Claude |
 | CODE AUDIT | **Codex** | Codex | Claude |
-| DOCS AUDIT | **Claude** | Codex | Claude |
+| DOCS AUDIT | **Claude** | **Claude** | Claude |
 | BROWSER AUDIT | Claude (Chrome MCP) | Claude | Claude |
 | SYNTHESIZE | Claude | Claude | Claude |
 
+DOCS AUDIT is always Claude regardless of `--engine` — writing-quality strength on documentation drift detection (READMEs, VISION.md prose, spec status accuracy) is the deciding factor, not code analysis. BROWSER AUDIT is always Claude because Chrome MCP tools are session-bound to Claude Code.
+
 ---
 
 ## How to Spawn a Codex Role
@@ -199,7 +201,4 @@ mcp__codex-cli__codex({
 
 - `--engine claude` → all roles and phases use Claude (no Codex calls)
 - `--engine codex` → all phases use Codex for implementation/analysis, Claude only for orchestration and Chrome MCP
-- `--engine auto` → each role and phase routes to the optimal model per this table
-- `--engine auto` is the recommended default when Codex MCP server is available
-
-`--engine` and `--with-codex` are **mutually exclusive**. `--engine auto` subsumes `--with-codex both` — it uses Codex where it's optimal (broader than just evaluate/review). If both flags are passed, `--engine` takes precedence and `--with-codex` is ignored with a warning.
+- `--engine auto` (default) → each role and phase routes to the optimal model per this table

package/config/skills/devlyn:ideate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: devlyn:ideate
-description: Transforms unstructured ideas into implementation-ready planning documents through structured brainstorming, research, and a built-in self-skeptical rubric pass. Produces a three-layer document architecture (Vision, Roadmap index, auto-resolve-ready specs) to eliminate context pollution in the implementation pipeline. Optional --with-codex flag adds OpenAI Codex as a cross-model critic. Use when the user wants to brainstorm, plan a new project or feature set, create a vision and roadmap, or structure scattered ideas into an actionable plan. Triggers on "let's brainstorm", "let's plan", "ideate", "I have an idea for", "help me think through", "let's explore", new project planning, feature discovery, roadmap creation, or when the user is throwing ideas that need structuring.
+description: Transforms unstructured ideas into implementation-ready planning documents through structured brainstorming, research, and a built-in self-skeptical rubric pass. Produces a three-layer document architecture (Vision, Roadmap index, auto-resolve-ready specs) to eliminate context pollution in the implementation pipeline. Default `--engine auto` routes the CHALLENGE rubric pass to OpenAI Codex (GPT-5.4) as a cross-model critic for a GAN dynamic. Use when the user wants to brainstorm, plan a new project or feature set, create a vision and roadmap, or structure scattered ideas into an actionable plan. Triggers on "let's brainstorm", "let's plan", "ideate", "I have an idea for", "help me think through", "let's explore", new project planning, feature discovery, roadmap creation, or when the user is throwing ideas that need structuring.
 ---
 
 # Ideation to Implementation Bridge
@@ -24,18 +24,17 @@ Concretely:
 
 Parse these from the user's invocation message:
 
-- `--with-codex` (default: off) — bare flag. When set, OpenAI Codex runs an independent rubric pass during Phase 3.5 CHALLENGE via `mcp__codex-cli__*` MCP tools, using the same rubric as the solo pass. Codex always runs at `reasoningEffort: "xhigh"` — the entire reason for the flag is maximum reasoning from a second model family. **Ignored if `--engine` is set** (engine routing subsumes this).
 - `--engine MODE` (auto) — controls which model handles each ideation phase. Modes:
-  - `auto` (default): Claude handles FRAME/EXPLORE/CONVERGE/DOCUMENT (ambiguous intent, writing quality), Codex runs the CHALLENGE rubric pass as critic (GAN dynamic). Subsumes `--with-codex`. Requires Codex MCP server.
+  - `auto` (default): Claude handles FRAME/EXPLORE/CONVERGE/DOCUMENT (ambiguous intent, writing quality), Codex runs the CHALLENGE rubric pass as critic (GAN dynamic). Requires Codex MCP server.
   - `codex`: Codex handles FRAME/EXPLORE/CONVERGE/DOCUMENT, Claude runs CHALLENGE (role reversal — builder and critic are always different models).
   - `claude`: all phases use Claude. No Codex calls.
 
 **Engine pre-flight** (runs unless `--engine claude` was explicitly passed):
-- The default engine is `auto`. If the user did not pass `--engine`, the engine is `auto` — NOT `claude`.
+- The default engine is `auto`. If the user did not pass `--engine`, the engine is `auto` — not `claude`.
 - Call `mcp__codex-cli__ping` to verify the Codex MCP server is available. If ping fails, warn the user and offer: [1] Continue with `--engine claude`, [2] Abort.
-- Also read `references/challenge-rubric.md` up front. The engine routing table is defined in the auto-resolve skill's `references/engine-routing.md` under "Pipeline Phase Routing (ideate)".
+- Read `references/challenge-rubric.md` up front. The engine routing table lives in the auto-resolve skill's `references/engine-routing.md` under "Pipeline Phase Routing (ideate)" — read that on demand when routing decisions are needed.
 
-**If `--engine` is not set and `--with-codex` is explicitly set** (legacy): read `references/challenge-rubric.md` and `references/codex-debate.md` up front, then run the pre-flight check described in `codex-debate.md` to verify the Codex MCP server is available before starting the pipeline. If the server is unavailable and the user opts to continue without Codex, the solo CHALLENGE pass still runs — only the cross-model rubric pass is disabled.
+**Consolidated flag**: `--with-codex` was rolled into the smarter `--engine auto` default. If the user passes it, inform them once and proceed with `--engine auto`: "Note: `--with-codex` was consolidated into `--engine auto` (default), which routes the CHALLENGE rubric pass to Codex automatically. No flag needed. Continuing with `--engine auto`."
 
 <why_this_matters>
 When ideas flow directly from conversation to `/devlyn:auto-resolve`, context degrades at each handoff:
@@ -115,7 +114,8 @@ Expand is the most common mode after initial setup — the user already has Visi
 **On entry:**
 1. Read `docs/VISION.md`, `docs/ROADMAP.md`, and existing phase `_overview.md` files to understand the established context
 2. Scan existing item specs to understand what's built and what's planned
-3. Summarize your understanding: "Here's what exists: [phases, item count, current status]. You want to add [new area]. Does this expand an existing phase or warrant a new one?"
+3. **Run the Archive Pass** (see Context Archiving below) before summarizing. Summarizing a stale roadmap to the user wastes the exchange — they'll see "Phase 1 has 4 items" when really all 4 are already Done and the phase should be collapsed.
+4. Summarize your understanding: "Here's what exists: [phases, item count, current status]. You want to add [new area]. Does this expand an existing phase or warrant a new one?"
 
 **During ideation:**
 - FRAME is lighter — the vision already exists, focus on framing the NEW area only
@@ -129,7 +129,7 @@ Expand is the most common mode after initial setup — the user already has Visi
 - New item specs can reference existing items in their Dependencies section
 - If new items change the meaning of existing items, flag this: "Adding [X] may affect the scope of existing item [Y]. Should we update [Y]'s spec?"
 
-In Replan mode, also read existing docs first, then focus on the Converge phase to reprioritize.
+In Replan mode: read existing docs first, **run the Archive Pass** (see Context Archiving below) before any reprioritization — you can't sensibly reorder work that's already finished — then focus on the Converge phase to reprioritize what remains. The Archive Pass also surfaces Backlog items whose Revisit date has passed, which are natural candidates when replanning.
 
 ### Quick Add Mode Detail
 
@@ -137,8 +137,9 @@ Quick Add is for when the user has a single concrete idea, bug report, or improv
 
 **On entry:**
 1. Read `docs/ROADMAP.md` and relevant phase `_overview.md` files
-2. Identify the best-fit phase for the new item (or suggest a new phase if it doesn't fit)
-3. Determine the next available item ID (e.g., if phase 2 has 2.1-2.4, the new item is 2.5)
+2. **Run the Archive Pass first** (see Context Archiving below). Do this *before* you figure out where the new item goes — a stale roadmap will mislead phase selection and ID numbering. If the pass moves a phase out of the active section, the new item's natural home may change.
+3. Identify the best-fit phase for the new item (or suggest a new phase if it doesn't fit)
+4. Determine the next available item ID (e.g., if phase 2 has 2.1-2.4, the new item is 2.5)
 
 **Workflow (minimal — no full Frame/Explore/Converge):**
 1. Confirm the idea with the user: "I'll add this as [item title] in Phase [N]. That sound right?"
@@ -157,12 +158,25 @@ To implement:
 
 ### Context Archiving
 
-As projects progress, completed work accumulates and dilutes the active roadmap. Archive stale context at these trigger points:
+ROADMAP.md is the tactical index. Every row that isn't Planned / In Progress / Blocked is noise — it dilutes attention, pads the file past its 150-line target, and makes future ideation sessions read stale context they'll have to mentally filter out. Done work should move; it shouldn't disappear.
 
-**When an entire phase is complete:**
-1. Move the phase's table from the active section to a `## Completed` section at the bottom of ROADMAP.md
-2. Keep it collapsed — just phase name, completion date, and item count
-3. Item spec files stay in place (they're self-contained and may be referenced by dependencies)
+The goal state: the active section of ROADMAP.md only lists work that still needs doing. Everything completed lives under a collapsed `## Completed` block at the bottom. Item spec files themselves stay in place — they remain on disk at `docs/roadmap/phase-N/{id}.md` because other specs may reference them — only the index row moves.
+
+#### The Archive Pass
+
+Run this at the start of every Quick Add, Expand, and Replan session (each mode's "On entry" checklist tells you when). It's deterministic and cheap. Never skip it to "save time" — the time you save by skipping it is immediately spent by you and the user arguing about a roadmap that shows phantom work.
+
+1. **Read `docs/ROADMAP.md`.** For each phase, look at the Status column of every row.
+2. **For each phase where every row is `Done`:** archive the whole phase.
+   - Cut the phase's `## Phase N: …` heading and table out of the active section.
+   - If no `## Completed` section exists yet at the bottom of the file, create one.
+   - Add a `<details>` block inside Completed for this phase (see format below). Use the latest completion date you can find in the item spec frontmatter (`completed:` field, or today's date if absent). Item count is the row count.
+3. **For individual `Done` rows inside an otherwise-active phase:** leave them in place. A row only moves when its whole phase is finished. (Mixed-state phases stay mixed so the user can see recent wins alongside open work.)
+4. **Scan the Backlog table.** Surface any row whose "Revisit" date has passed — mention it to the user as a replan candidate. Don't auto-promote it; that's a conversation.
+5. **Scan `docs/roadmap/decisions/`.** Flag any decision whose status is `accepted` but whose reasoning is visibly contradicted by the work that's now Done. Don't silently edit decisions; raise them as open questions.
+6. **Report what you did.** Before moving on to the mode's main work, tell the user in one short paragraph: "Archived Phase 1 (3 items). Active roadmap is now Phase 2 (2 items). Proceeding with [Quick Add / Expand / Replan]." Skip the report only if nothing changed.
+
+**Completed block format** (place at the bottom of ROADMAP.md, below Decisions):
 
 ```markdown
 ## Completed
@@ -178,16 +192,13 @@ As projects progress, completed work accumulates and dilutes the active roadmap.
 </details>
 ```
 
-**When entering Expand or Replan mode:**
-1. Scan ROADMAP.md for items marked Done — if all items in a phase are Done, archive that phase
-2. Check Backlog for items whose "Revisit" date has passed — surface them as candidates for the new phase
-3. Review decisions — flag any marked `accepted` that may need revisiting given new context
+If the `## Completed` section already exists and you're archiving an additional phase, append a new `<details>` block — don't rewrite existing ones.
 
-**When a decision becomes outdated:**
-- Don't delete it — mark status as `superseded` and add a note pointing to the replacement decision
-- This preserves the reasoning history for future reference
+#### Outdated decisions
 
-The goal: ROADMAP.md's active section should only show work that's planned, in-progress, or blocked. Everything else moves to Completed or gets re-evaluated.
+When a decision becomes wrong because the world changed under it:
+- Don't delete it — set its `status:` to `superseded` in the decision file's frontmatter and add a one-line pointer to the replacement decision record.
+- This preserves the reasoning history for future reference, which matters more than a tidy decisions table.
 
 ## Phase 1: FRAME
 
@@ -211,6 +222,10 @@ Don't write documents yet. The output of this phase is a shared mental model bet
 
 This is the creative core — the phase that should take the most conversational turns. The user chose to ideate with AI because they want perspectives, research, and creative expansion they wouldn't get alone.
 
+<use_parallel_tool_calls>
+EXPLORE often needs several independent lookups: web search for prior art, doc fetches, repo greps for existing patterns. When tool calls have no dependencies on each other, issue them in parallel in the same response. Spawn subagents in parallel when fanning out across distinct research topics. Only chain calls that depend on a previous call's output. Pace research across turns rather than front-loading every lookup before the user has framed direction — EXPLORE is dialogue-driven, parallel is just for the lookups inside any single turn.
+</use_parallel_tool_calls>
+
 <research_protocol>
 When relevant, actively research before and during brainstorming:
 - **Existing solutions**: What's already out there? (web search, documentation)
@@ -316,13 +331,60 @@ For Quick Add with one new item, one solo pass is enough. For a full greenfield
 
 If the plan came from one model in one pass, it almost always fails at least one axis somewhere. Nodding along to your own draft defeats the entire point of the phase.
 
-### Codex pass (engine-routed or legacy `--with-codex`)
+### Codex critic pass (engine-routed)
+
+**If `--engine auto`** (default): Codex runs the CHALLENGE rubric pass automatically as critic.
+
+Call `mcp__codex-cli__codex` with `model: "gpt-5.4"`, `reasoningEffort: "xhigh"`, `sandbox: "read-only"`, `workingDirectory: <project root>`. The `prompt` parameter is built from the packaged plan + the inlined rubric + the appended Codex instructions. Codex has no filesystem access to this project, so everything it needs travels in the prompt.
+
+**Step 1 — Package the post-solo plan.** Build the prompt with these sections in this order:
+
+```
+## Problem framing (from FRAME phase)
+[problem statement, constraints, success criteria, anti-goals]
+
+## Confirmed facts vs assumptions
+Confirmed by user: [list each fact the user explicitly confirmed]
+Assumptions (not yet confirmed): [list each assumption the agent made]
+
+## Plan (post-solo-CHALLENGE)
+Vision: [one sentence]
+Phase 1 ([theme]): [items with one-line descriptions and dependencies]
+Phase 2 ([theme]): ...
+Architecture decisions: [each with what / why / alternatives considered]
+Deferred to backlog: [items + reason]
+
+## Findings from the solo rubric pass
+[list each with: severity, axis, quote, why, fix, whether applied]
+
+## Rubric
+[INLINE the full text of references/challenge-rubric.md here verbatim — Codex needs the rubric definition in the prompt itself]
+
+## Your job
+You are applying an independent rubric pass to the PLANNING document above. This is a roadmap, not code — judge the shape of the plan, not implementation details. The user explicitly asked to be challenged because soft-pedaled plans waste their time.
+
+You are running AFTER a solo pass by Claude. Catch what the solo pass missed; do not just agree with what it already caught. For each existing solo finding, reply either "confirmed" (with one-line agreement) or "I would frame this differently" (with a reason). Then add your own findings that the solo pass missed.
+
+Use the finding format from the rubric above: Severity / Quote / Axis / Why / Fix. The Quote field is load-bearing — anchor each finding to a specific line from the plan.
+
+Respect explicit user intent. If the user confirmed something in the "Confirmed facts" section, the rubric does not override it silently. Raise the conflict as a note and let the orchestrator surface it to the user.
+
+End with a verdict: PASS / PASS WITH MINOR FIXES / FAIL — REVISION REQUIRED, plus a one-line explanation.
+```
+
+**Step 2 — Reconcile.** Merge the two finding lists:
+- Same finding from both → keep the more specific wording, mark "confirmed by both"
+- Codex-only → prefix `[codex]` in internal notes so the user-facing summary can attribute correctly
+- Solo-only → keep as-is
+- Conflicts (solo says X, Codex says not-X) → record both, do not silently pick one; if material, surface as an open question in the user-facing summary
+
+If Codex raised CRITICAL or HIGH findings the solo pass missed, apply the fixes to the plan before presenting the user-facing summary — unless fixing would change something the user explicitly confirmed, in which case follow the rubric's "Respect explicit user intent" rule.
 
-**If `--engine auto`**: Codex runs the CHALLENGE rubric pass automatically. Call `mcp__codex-cli__codex` with `model: "gpt-5.4"`, `reasoningEffort: "xhigh"`, `sandbox: "read-only"`, and the packaged plan + rubric as prompt (same format as `codex-debate.md` Step 2). Reconcile findings: same finding from both → "confirmed by both", Codex-only → prefix `[codex]`.
+**Do not loop.** One Codex pass is enough. If the result is still FAIL after reconciliation, the plan has structural problems that belong in the user-facing summary as open questions rather than further iteration.
 
-**If `--engine codex`**: Role reversal — Codex built the plan (FRAME/EXPLORE/CONVERGE/DOCUMENT), so Claude runs the solo CHALLENGE pass. Do NOT also run Codex on CHALLENGE — builder and critic must be different models. Skip this section entirely.
+**If `--engine codex`**: Role reversal — Codex built the plan, so Claude runs the solo CHALLENGE pass and that is the only pass. Do not also run Codex on CHALLENGE — builder and critic should always be different models. Skip this section.
 
-**If `--engine claude` or `--engine` not set, and `--with-codex` is set** (legacy): follow `references/codex-debate.md` "PHASE 3.5-CODEX" section. Codex applies the rubric from `challenge-rubric.md` independently at `reasoningEffort: "xhigh"`. Reconcile findings as `codex-debate.md` describes — findings raised by both sides get "confirmed by both", Codex-only findings get prefixed `[codex]` in internal notes so the user can see where each push came from.
+**If `--engine claude`**: No Codex calls. The solo pass is the only pass.
 
 ### Respect explicit user intent
 
@@ -344,7 +406,7 @@ Deferred: [items with reasons]
 ## CHALLENGE results
 
 Solo pass: [N findings, M applied]
-Codex pass: [N findings, M applied]   ← only if --with-codex was set
+Codex pass: [N findings, M applied]   ← only on --engine auto
 
 Changes applied during CHALLENGE:
 - [item]: [what changed and which axis triggered it]
@@ -457,7 +519,7 @@ Before finalizing, verify:
 - [ ] No spec requires reading VISION.md to be understood (self-contained)
 - [ ] Dependencies between items are documented in both specs
 - [ ] Architecture decisions include reasoning and alternatives considered
-- [ ] CHALLENGE ran against `references/challenge-rubric.md` (solo, plus Codex if `--with-codex` was set); no item still fails any axis at CRITICAL or HIGH severity
+- [ ] CHALLENGE ran against `references/challenge-rubric.md` (solo, plus Codex critic on `--engine auto`); no item still fails any axis at CRITICAL or HIGH severity
 - [ ] User saw the post-challenge plan as the first and only confirmation prompt — no pre-challenge draft was shown first
 - [ ] Any rubric finding that conflicted with explicit user intent was surfaced as an open question, not silently applied
 

package/config/skills/devlyn:ideate/references/challenge-rubric.md

@@ -7,7 +7,7 @@
 - Finding format
 - Examples (good vs bad findings, plus a detour-sequencing example)
 
-The 5-axis rubric applied in Phase 3.5 CHALLENGE of `devlyn:ideate`. Both the solo Claude pass and the Codex pass (when `--with-codex` is set) use this file — there is exactly one definition of the rubric, and both paths read it directly from SKILL.md.
+The 5-axis rubric applied in Phase 3.5 CHALLENGE of `devlyn:ideate`. Both the solo Claude pass and the Codex critic pass (on `--engine auto`) use this file — there is exactly one definition of the rubric, and `SKILL.md` instructs both passes to read it directly from here.
 
 The rubric exists because plans produced in a single pass, by a single model, in a single conversation almost always fail at least one axis somewhere. The user's historical experience: every time they asked "is this really no-workaround, no-guesswork, no-overengineering, world-class, optimized?", the honest answer was no. This phase makes the answer honestly yes before the user even has to ask.
 

package/config/skills/devlyn:preflight/SKILL.md

@@ -58,6 +58,10 @@ Example with engine: `/devlyn:preflight --engine auto`
 
 ## PHASE 0: DISCOVER & SCOPE
 
+<use_parallel_tool_calls>
+Phase 0 and Phase 1 do many independent reads (planning docs, item specs, prior state). When tool calls have no dependencies between them, issue them in parallel in a single response — that includes globbing for spec files and reading several specs at once. Only chain calls that depend on values from a previous call.
+</use_parallel_tool_calls>
+
 1. **Find planning documents** — search in parallel:
    - `docs/VISION.md`
    - `docs/ROADMAP.md`
@@ -80,7 +84,7 @@ Scope: [Phase N / All phases]
 Documents: VISION.md, ROADMAP.md, [N] item specs
 Deferred items (excluded): [N]
 Previous run: [found — will show delta / none]
-Phases: Extract → Audit → [Browser] → [Docs] → Report → Triage
+Phases: 1 Extract → 2 Audit (code + docs + browser) → 3 Report → 4 Triage
 ```
 
 ## PHASE 1: EXTRACT COMMITMENTS
@@ -102,9 +106,9 @@ Read all in-scope planning documents and build a **commitment registry** — eve
    - Items with `status: cut` in ROADMAP.md
    - Out of Scope entries — these are anti-commitments (things promised NOT to build)
 
-5. **Separate planned items**: Items with `status: planned` in their spec frontmatter or "Planned" in ROADMAP.md are NOT expected to be implemented yet. Include them in a `[PLANNED]` section of the registry for visibility, but do NOT audit them or report them as findings. This distinction matters — flagging planned items as MISSING creates noise and buries the real gaps in work that was supposed to be done.
+5. **Separate planned items**: Items with `status: planned` in their spec frontmatter or "Planned" in ROADMAP.md are not expected to be implemented yet. Include them in a `[PLANNED]` section of the registry for visibility, but do **not** audit them or report them as findings. Flagging planned items as MISSING creates noise and buries the real gaps in work that was supposed to be done.
 
-5. **Write to `.devlyn/commitment-registry.md`**:
+6. **Write to `.devlyn/commitment-registry.md`**:
 
 ```markdown
 # Commitment Registry
@@ -137,20 +141,20 @@ Spawn all applicable auditors in parallel. Each reads `.devlyn/commitment-regist
 
 ### code-auditor (always)
 
-**Engine routing**: If `--engine auto` or `--engine codex`, call `mcp__codex-cli__codex` with `model: "gpt-5.4"`, `reasoningEffort: "xhigh"`, `sandbox: "read-only"`, and the full code-auditor prompt (read from `references/auditors/code-auditor.md`). Include the commitment registry content inline in the prompt since Codex cannot read `.devlyn/commitment-registry.md` directly in read-only sandbox. If `--engine claude`, spawn a Claude subagent as below.
-
-Spawn a subagent with `mode: "bypassPermissions"`. Read the full prompt from `references/auditors/code-auditor.md` and pass it to the subagent.
+Engine routes per the auto-resolve skill's `references/engine-routing.md` ("Pipeline Phase Routing (preflight)" → CODE AUDIT row): Codex on `--engine auto`/`codex`, Claude on `--engine claude`. When the route is **Codex**, call `mcp__codex-cli__codex` with the auditor prompt inline (Codex cannot read `.devlyn/commitment-registry.md` directly under `read-only` sandbox, so paste the registry into the prompt). When the route is **Claude**, spawn a subagent with `mode: "bypassPermissions"`. Read the auditor prompt from `references/auditors/code-auditor.md` either way.
 
 The code-auditor classifies each commitment as IMPLEMENTED, MISSING, INCOMPLETE, DIVERGENT, or BROKEN — with file:line evidence. Also catches cross-feature integration gaps and constraint violations. Writes to `.devlyn/audit-code.md`.
 
 ### docs-auditor (unless --skip-docs)
 
-Spawn a subagent with `mode: "bypassPermissions"`. Read the full prompt from `references/auditors/docs-auditor.md` and pass it to the subagent.
+Always Claude (writing-quality strength) regardless of `--engine`. Spawn a subagent with `mode: "bypassPermissions"`. Read the full prompt from `references/auditors/docs-auditor.md` and pass it to the subagent.
 
 Checks: ROADMAP.md status accuracy, README alignment, API doc coverage, VISION.md currency, item spec status. Writes to `.devlyn/audit-docs.md`.
 
 ### browser-auditor (conditional)
 
+Always Claude (Chrome MCP tools are session-bound) regardless of `--engine`.
+
 **Skip conditions** (check in order):
 1. `--skip-browser` flag → skip
 2. No web-relevant files in project (no `*.tsx`, `*.jsx`, `*.vue`, `*.svelte`, `*.html`, `page.*`, `layout.*`) → skip with note "Browser validation skipped — no web files detected"
@@ -340,7 +344,7 @@ Triage complete.
 
 Next steps:
 - To implement fixes: /devlyn:auto-resolve "Implement per spec at docs/roadmap/phase-N/[id]-[name].md"
-  - For high-stakes fixes (CRITICAL severity or complex DIVERGENT findings), add `--with-codex both` to cross-validate the fix and review with Codex
+  - For CRITICAL severity or complex DIVERGENT findings, the default `--engine auto` already routes BUILD/FIX to Codex and EVALUATE/CHALLENGE to Claude (cross-model GAN dynamic). No extra flag needed.
 - To re-run preflight after fixes: /devlyn:preflight [same flags]
 - To add new features discovered during audit: /devlyn:ideate expand
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "1.12.4",
+  "version": "1.13.0",
   "description": "AI development toolkit for Claude Code — ideate, auto-resolve, and ship with context engineering and agent orchestration",
   "homepage": "https://github.com/fysoul17/devlyn-cli#readme",
   "bin": {

package/config/skills/devlyn:auto-resolve/references/codex-integration.md

@@ -1,106 +0,0 @@
-# Codex Cross-Model Integration (Legacy)
-
-> **Note**: This file is the legacy `--with-codex` integration. For the newer `--engine` flag (which subsumes `--with-codex`), see `references/engine-routing.md`. Only read this file when `--with-codex` is enabled AND `--engine` is NOT set.
-
-Instructions for using OpenAI Codex as an independent evaluator/reviewer in the auto-resolve pipeline.
-
-Codex is accessed via `mcp__codex-cli__*` MCP tools (provided by codex-mcp-server). This creates a GAN-like adversarial dynamic — Claude builds and Codex critiques, reducing shared blind spots between model families.
-
----
-
-## PRE-FLIGHT CHECK
-
-Before starting the pipeline, verify the Codex MCP server is available by calling `mcp__codex-cli__ping`.
-
-- **If ping succeeds**: continue normally.
-- **If ping fails or `mcp__codex-cli__ping` tool is not found**: warn the user and ask how to proceed:
-  ```
-  ⚠ Codex MCP server not detected. --with-codex requires codex-mcp-server.
-
-  To install:
-    npm i -g @openai/codex
-    claude mcp add codex-cli -- npx -y codex-mcp-server
-
-  Options:
-    [1] Continue without --with-codex (Claude-only evaluation/review)
-    [2] Abort pipeline
-  ```
-  If the user chooses [1], disable `--with-codex` and continue. If [2], stop.
-
----
-
-## PHASE 2-CODEX: CROSS-MODEL EVALUATE
-
-Run after the Claude evaluator (Phase 2) completes, only if `--with-codex` includes `evaluate` or `both`.
-
-### Step 1 — Get Codex's evaluation
-
-Call `mcp__codex-cli__codex` with:
-- `prompt`: Include the full content of `.devlyn/done-criteria.md` and the output of `git diff HEAD~1`. Ask Codex to evaluate the changes against the done criteria and report issues by severity (CRITICAL, HIGH, MEDIUM, LOW) with file:line references.
-- `workingDirectory`: the project root
-- `sandbox`: `"read-only"` (Codex should only read, not modify files)
-- `reasoningEffort`: `"high"` (note: for `--engine auto`, the engine-routing.md uses `"xhigh"` by default)
-- `model`: `"gpt-5.4"` (pass explicitly — the MCP schema default may be outdated)
-
-Example prompt to pass:
-```
-You are an independent code evaluator. Grade the following code changes against the done criteria below. Be strict — when in doubt, flag it.
-
-## Done Criteria
-[paste contents of .devlyn/done-criteria.md]
-
-## Code Changes
-[paste output of git diff HEAD~1]
-
-For each criterion, mark VERIFIED (with evidence) or FAILED (with file:line and what's wrong).
-Then list all issues found grouped by severity: CRITICAL, HIGH, MEDIUM, LOW.
-For each issue provide: file:line, description, and suggested fix.
-End with a verdict: PASS, PASS WITH ISSUES, NEEDS WORK, or BLOCKED.
-```
-
-### Step 2 — Merge findings
-
-Spawn a subagent using the Agent tool with `mode: "bypassPermissions"` to merge Claude's and Codex's evaluations.
-
-Agent prompt:
-
-Read `.devlyn/EVAL-FINDINGS.md` (Claude's evaluation) and the Codex evaluation output below. Merge them into a single unified `.devlyn/EVAL-FINDINGS.md` following the existing format. Rules:
-- Take the MORE SEVERE verdict between the two evaluators
-- Deduplicate findings that reference the same file:line or describe the same issue
-- When both evaluators flag the same issue, keep the more detailed description
-- Prefix Codex-only findings with `[codex]` so the fix loop knows the source
-- Preserve the exact structure: Verdict, Done Criteria Results, Findings Requiring Action (CRITICAL/HIGH), Cross-Cutting Patterns
-
-Codex evaluation:
-[paste Codex's response here]
-
----
-
-## PHASE 4B: CODEX REVIEW
-
-Run after the Claude team review (Phase 4A) completes, only if `--with-codex` includes `review` or `both`.
-
-### Step 1 — Run Codex review
-
-Call `mcp__codex-cli__review` with:
-- `base`: `"main"` — review all changes since main
-- `workingDirectory`: the project root
-- `title`: `"Cross-model review (Codex)"`
-
-This runs OpenAI Codex's built-in code review against the diff. The review tool returns structured findings automatically — no custom prompt needed.
-
-### Step 2 — Reconcile both reviews
-
-Spawn a subagent using the Agent tool with `mode: "bypassPermissions"` to reconcile both reviews.
-
-Agent prompt:
-
-Two independent reviews have been conducted on recent changes — one by a Claude team review and one by OpenAI Codex. Reconcile them:
-
-Claude team review findings: [paste Phase 4A agent's output summary]
-Codex review findings: [paste mcp__codex-cli__review output]
-
-1. Deduplicate findings that describe the same issue
-2. For unique Codex findings not caught by Claude's team, prefix with `[codex]` and assess severity
-3. Fix any CRITICAL issues directly. For HIGH issues, fix if straightforward.
-4. Write a brief reconciliation summary to stdout listing: findings from both (agreed), Claude-only, Codex-only, and what was fixed

package/config/skills/devlyn:ideate/references/codex-debate.md

@@ -1,112 +0,0 @@
-# Codex Cross-Model Rubric Pass (Legacy)
-
-> **Note**: This file is the legacy `--with-codex` integration for ideate. For the newer `--engine` flag (which subsumes `--with-codex`), see the engine routing section in SKILL.md. Only read this file when `--with-codex` is set AND `--engine` is NOT set.
-
-## Contents
-- Pre-flight check (verify Codex MCP server availability)
-- PHASE 3.5-CODEX: packaging the plan, calling Codex, reconciling findings with the solo pass
-- Cost notes (one Codex call per ideation session)
-
-Instructions for using OpenAI Codex as an independent critic during Phase 3.5 CHALLENGE.  The 5-axis rubric itself lives in `challenge-rubric.md` — Claude loads that file directly from SKILL.md, not via this file.
-
-Codex is accessed via `mcp__codex-cli__*` MCP tools (provided by codex-mcp-server). The intent: one opinionated rubric pass from a different model family, applied right before the user sees the plan. Two model families catch different blind spots; one pass at maximum effort catches more than multiple shallow passes.
-
-**Always use `model: "gpt-5.4"`, `reasoningEffort: "xhigh"` and `sandbox: "read-only"` for every Codex call in this file.** Maximum reasoning is the whole reason the `--with-codex` flag exists — lowering it defeats the purpose of bringing in a second model. Pass `model: "gpt-5.4"` explicitly as the MCP schema default may be outdated.
-
----
-
-## PRE-FLIGHT CHECK
-
-Before starting the pipeline, verify the Codex MCP server is available by calling `mcp__codex-cli__ping`.
-
-- **If ping succeeds**: continue.
-- **If ping fails or `mcp__codex-cli__ping` is not found**: warn the user and ask:
-  ```
-  ⚠ Codex MCP server not detected. --with-codex requires codex-mcp-server.
-
-  To install:
-    npm i -g @openai/codex
-    claude mcp add codex-cli -- npx -y codex-mcp-server
-
-  Options:
-    [1] Continue without --with-codex (Claude-only solo CHALLENGE pass)
-    [2] Abort
-  ```
-  If [1], disable `--with-codex` and continue with the solo CHALLENGE. If [2], stop.
-
----
-
-## PHASE 3.5-CODEX: Codex rubric pass
-
-Run after the solo CHALLENGE pass completes, before the user-facing summary.
-
-### Step 1 — Package the post-solo plan
-
-Use the plan as it stands after the solo rubric pass. Package the full context Codex needs:
-
-```
-## Problem framing (from FRAME phase)
-[problem statement, constraints, success criteria, anti-goals]
-
-## Confirmed facts vs assumptions
-Confirmed by user: [list]
-Assumptions (not yet confirmed): [list]
-
-## Plan (post-solo-CHALLENGE)
-Vision: [one sentence]
-Phase 1 ([theme]): [items, dependencies, one-line descriptions]
-Phase 2 ([theme]): ...
-Architecture decisions: [each with what / why / alternatives]
-Deferred to backlog: [items + reason]
-
-## Findings from the solo rubric pass
-[list each with: axis, quote, why, fix, whether applied]
-```
-
-Include the framing and assumptions — Codex can only judge whether the plan fits the user's reality if it sees what the user actually said.
-
-### Step 2 — Codex challenge pass
-
-Call `mcp__codex-cli__codex` with:
-- `prompt`: the packaged context above, followed by the instructions below
-- `workingDirectory`: the project root
-- `sandbox`: `"read-only"`
-- `model`: `"gpt-5.4"` — pass explicitly; the MCP schema default may still show `gpt-5.3-codex`
-- `reasoningEffort`: `"xhigh"` — the highest setting in the Codex enum (`none < minimal < low < medium < high < xhigh`). Always pick the top level; this is the entire reason for the flag.
-
-Instructions to append to the packaged context. **Before sending, inline the full text of `references/challenge-rubric.md` into the prompt under a `## Rubric` heading** — Codex does not have filesystem access to this project, so Claude must ship the rubric itself. Claude already has the rubric loaded from Phase 3.5 setup.
-
-Template for the appended instructions:
-
-```
-You are applying an independent rubric pass to the PLANNING document above. This is a roadmap, not code — judge the shape of the plan, not implementation details. The user has explicitly asked to be challenged because soft-pedaled plans waste their time.
-
-## Rubric
-[Claude inlines the full text of references/challenge-rubric.md here]
-
-## Your job
-- You are running AFTER a solo pass by Claude. Catch what the solo pass missed, do not just agree with what it already caught. For each existing solo finding, reply either "confirmed" or "I would frame this differently" with a reason. Then add your own findings that the solo pass missed.
-- Use the finding format from the rubric above: Severity / Quote / Axis / Why / Fix. The Quote field is load-bearing — anchor each finding to a specific line from the plan.
-- Respect explicit user intent. If the user confirmed something in the "Confirmed facts" section, the rubric does not override it silently. Raise the conflict as a note and let Claude surface it to the user.
-
-End with a verdict: PASS / PASS WITH MINOR FIXES / FAIL — REVISION REQUIRED, and a one-line explanation.
-```
-
-### Step 3 — Reconcile solo and Codex findings
-
-Merge the two finding lists:
-- Same finding from both → keep the more specific wording, mark "confirmed by both".
-- Codex-only → prefix `[codex]` in internal notes so the user-facing summary can show where each push came from.
-- Solo-only → keep as-is.
-- Conflicts (solo says X, Codex says not-X) → record both, do not silently pick one; if the conflict is material, include it as an open question in the user-facing summary.
-
-If Codex raised CRITICAL or HIGH findings that the solo pass missed, apply the fixes to the plan before presenting the user-facing summary. If fixing would change something the user explicitly asked for, follow the "Respect explicit user intent" rule already loaded from the rubric: do not silently rewrite — surface it.
-
-Do not loop. One Codex pass is enough. If the result is still FAIL after one pass, that is signal that the plan has structural problems the user should see directly, not signal to keep iterating in the background.
-
----
-
-## Cost notes
-
-- One Codex call at `reasoningEffort: "xhigh"` typically takes 30–90s and is not cheap. This integration is bounded: exactly one Codex call per ideation session.
-- In Quick Add mode on a single new item, one Codex call is still worth it — small scope, huge signal, and single-item additions are exactly where workarounds slip in unnoticed.