README install fixes harvested from upstream + plan-codex command hardening

.gitignore

@@ -21,3 +21,4 @@ src/
 package.json
 package-lock.json
 node_modules/
+reviews/

BUGS.md

@@ -0,0 +1,23 @@
+## Medium priority (auto-fix pending)
+
+### Codex (2026-08-03T04:15Z)
+- [ ] MEDIUM: 1. The execute and TDD eval suites contain no WARNING-path cases. `skills/claude-codex/evals/evals.json:29` also covers remaining MEDIUM/LOW findings only after APPROVED. 2. `README.md:35-36` says Claude fixes all findings while users decide MEDIUM/LOW findings. `README.md:127` calls WARNING outcomes approved. 3. Changed Markdown retains prohibited em dashes and Oxford commas, contrary to the repository copy mandate.
+
+
+## High priority (from push reviews, fix first)
+
+### Codex (2026-08-03T04:51Z)
+- [ ] HIGH: `commands/plan-codex.md:50-53` validates the verdict line but not its consistency with severity findings. `VERDICT: APPROVED` accompanied by `CRITICAL:` or `HIGH:` still reaches Phase 3 and silently drops those findings. Treat contradictory severity and verdict combinations as malformed.
+- [ ] MEDIUM: `commands/plan-codex.md:48-55` does not specify whether a malformed retry uses the saved thread or starts a new one. A new call can return a replacement `threadId`, yet later re-audits may use the original thread.
+- [ ] MEDIUM: `commands/plan-codex.md:50` adds the Oxford comma in “no verdict line, multiple verdict lines, or a value,” violating the repository copy mandate.
+
+### Codex (2026-08-03T05:50Z)
+- [ ] HIGH: `skills/plan-codex/SKILL.md:51,61,76-87`: The CLI fallback provides no MCP `threadId`. A BLOCKED result or contested finding therefore reaches `mcp__codex__codex-reply` with no valid saved thread. Define a CLI follow-up path for the full audit loop.
+  - `commands/plan-codex.md:50-54`: Verdict validation ignores severity consistency. `VERDICT: APPROVED` with CRITICAL or HIGH findings still reaches Phase 3 and drops them.
+  - `commands/claude-codex.md:82,91-93` and `commands/plan-codex.md:51,54`: The new gate says rejected findings are not accepted, but later instructions require fixing every CRITICAL and HIGH finding. This defeats the gate on BLOCKED reviews.
+  - `SCOPE-CREEP`: `commands/claude-codex.md:82` expands the counterpart’s CRITICAL/HIGH evaluation gate to “ANY finding.” This can discard MEDIUM/LOW findings before the user decision in Step R3 without support in the stated intent.
+- [ ] MEDIUM: `commands/plan-codex.md:48-58`: The malformed-response retry does not specify whether it reuses the thread or replaces the saved `threadId`.
+  - `UNASKED-CHANGE`: More than 2,000 lines of derived state under `reviews/.cache`, `reviews/.routed` and `reviews/.verdicts` were committed without a trace to the stated intent. No repository code references these artifacts.
+  - `ENHANCEMENTS.md:5,8`: Both new entries are stale. Current `BUGS.md:12` is a heading, while current `commands/plan-codex.md:40` already says the old analyzer exists.
+  - Changed Markdown introduces prohibited em dashes and Oxford commas, including `commands/claude-codex.md:82,87`, `commands/plan-codex.md:51` and `skills/plan-codex/SKILL.md:51`.
+

ENHANCEMENTS.md

@@ -0,0 +1,11 @@
+
+## Low-priority enhancements
+
+### Codex (2026-08-03T04:15Z)
+- LOW: `BUGS.md:12` adds a trailing blank line flagged by `git diff --check`.
+
+### Codex (2026-08-03T04:31Z)
+- LOW: `commands/plan-codex.md:40` falsely says the old analyzer path does not exist. `prompts/codex/analyzer.md` is tracked, `README.md:84` installs it and the reviewed local symlink resolves it.
+
+### Codex (2026-08-03T05:50Z)
+- LOW: The range fails `git diff --check`: `ENHANCEMENTS.md:9` adds a blank line at EOF and the committed review-cache diffs contain extensive trailing whitespace.

README.md

@@ -8,7 +8,7 @@ Skills are the primary interface. They support eval-based testing via skill-crea
 
 | Skill | Trigger | Description |
 |-------|---------|-------------|
-| `plan-codex` | `/plan-codex <task>` | Claude plans with Opus, Codex audits for correctness/completeness/security until approved |
+| `plan-codex` | `/plan-codex <task>` | Claude plans with Opus, Codex audits once for correctness/completeness/security; re-audit only on BLOCKED |
 | `claude-codex` | `/claude-codex <task or plan>` | Claude implements, Codex reviews with APPROVED/WARNING/BLOCKED verdicts |
 | `execute-codex` | `/execute-codex <task or plan>` | Smart size-based routing: Claude (small) or Codex (large) implements, code-reviewer reviews |
 | `tdd-claude-codex` | `/tdd-claude-codex <task or plan>` | TDD: Claude writes tests, Codex audits tests, Claude implements, Codex reviews implementation |
@@ -32,7 +32,7 @@ Commands (`commands/`) are retained for backward compatibility — they support
 /claude-codex <task or plan file>
   Claude implements (any model)       → Edit/Write + self-verify
   Codex reviews uncommitted changes   → returns structured verdict (APPROVED/WARNING/BLOCKED)
-  Claude fixes CRITICAL/HIGH issues   → re-reviews (max 3 rounds)
+  Claude fixes findings               → re-review only on BLOCKED (max 3 rounds)
   MEDIUM/LOW issues                   → user decides before delivery
 ```
 
@@ -48,7 +48,13 @@ Install from [claude.ai/code](https://claude.ai/code).
 npm install -g @openai/codex
 ```
 
-Authenticate with your OpenAI API key:
+Authenticate with your ChatGPT account (recommended):
+
+```bash
+codex login
+```
+
+Or with your OpenAI API key:
 
 ```bash
 export OPENAI_API_KEY=your-key-here
@@ -61,7 +67,7 @@ This setup uses the `code-reviewer` agent from [claude-plugins-official](https:/
 Install the plugin in Claude Code:
 
 ```
-claude plugin add claude-plugins-official/feature-dev
+claude plugin install feature-dev@claude-plugins-official
 ```
 
 ## Installation
@@ -72,6 +78,8 @@ claude plugin add claude-plugins-official/feature-dev
 git clone https://github.com/<your-username>/claude-codex
 cd claude-codex
 
+mkdir -p ~/.claude/skills ~/.claude/prompts ~/.claude/commands
+
 cp -r skills/*   ~/.claude/skills/
 cp -r prompts/*  ~/.claude/prompts/
 cp -r commands/* ~/.claude/commands/   # optional: for model pinning / tool restrictions
@@ -85,13 +93,15 @@ Suppress reasoning tokens by adding the following to `~/.codex/config.toml`:
 hide_agent_reasoning = true
 ```
 
+Note: this is a top-level key. If your `config.toml` already has `[table]` sections, add it above the first one (TOML keys appended after a table header belong to that table).
+
 ### 3. Add Codex as an MCP server
 
 ```bash
-claude mcp add codex -s user -- codex -c model=gpt-5.3-codex -c model_reasoning_effort=high mcp-server
+claude mcp add codex -s user -- codex -c model=gpt-5.6-sol -c model_reasoning_effort=xhigh mcp-server
 ```
 
-Adjust `model` and `model_reasoning_effort` (`low`/`medium`/`high`/`xhigh`) to your preference.
+Adjust `model` and `model_reasoning_effort` (`low`/`medium`/`high`/`xhigh`) to your preference. Available models depend on your Codex plan, account type and CLI version: on ChatGPT-account auth the bare `gpt-5.6` alias is API-only and gets rejected, use `gpt-5.6-sol`. If Codex calls fail with an `invalid_request_error`, re-run with a model your account supports.
 
 ### 4. Restart Claude Code
 
@@ -146,7 +156,7 @@ Or for a direct task:
 
 Claude implements using the active model (default: Sonnet; override with `/model opus` for heavier tasks). Codex reviews the uncommitted diff via MCP, returning a structured verdict (APPROVED / WARNING / BLOCKED):
 - **BLOCKED** (CRITICAL issues) — Claude fixes, Codex re-reviews (max 3 rounds)
-- **WARNING** (HIGH issues) — Claude fixes, Codex re-reviews (max 3 rounds)
+- **WARNING** (HIGH issues) — Claude fixes them, verifies with tests/lint, and proceeds; no re-review call
 - **MEDIUM/LOW issues** — surfaced to user; user decides whether to fix before delivery
 
 ### Model Override

commands/claude-codex.md

@@ -79,12 +79,14 @@ LOW: <list or 'none'>
 
 Save the returned `threadId` for follow-up replies.
 
+**Critical evaluation gate** (before acting on ANY finding): assess whether it is technically accurate against the actual code, whether the reviewer had full context for intentional decisions, and whether it improves correctness/security or is a preference/false positive. Contest doubtful findings via `codex-reply` with specific reasoning; discussion replies do not count as iterations. Only findings that survive this gate are "accepted" below.
+
 Classify the verdict:
-- **APPROVED** — no CRITICAL or HIGH → go to Phase 4
-- **WARNING** — HIGH issues only → fix all, increment iteration, re-review
-- **BLOCKED** — CRITICAL issues → fix all, increment iteration, re-review
+- **APPROVED** — no CRITICAL or HIGH → handle any MEDIUM/LOW findings per Step R3, then go to Phase 4
+- **WARNING** — HIGH issues only → fix all accepted HIGHs in one batch, run available tests/lint, handle MEDIUM/LOW per Step R3, then go to Phase 4 with no re-review call
+- **BLOCKED** — CRITICAL issues → fix all accepted ones, increment iteration, re-review
 
-**Step R2 — Fix and Re-review**
+**Step R2 — Fix and Re-review (BLOCKED verdicts only)**
 
 Address ALL CRITICAL and HIGH issues before re-reviewing:
 - Collect every CRITICAL/HIGH finding from the last review
@@ -98,9 +100,9 @@ Run `git diff HEAD` again to see the updated changes after fixes, then re-review
 Return ONLY the structured verdict in the same format.
 ```
 
-One review per iteration, not one review per fix. Stop after 3 iterations without APPROVED.
+One review per iteration, not one review per fix. Only BLOCKED verdicts trigger a re-review.
 
-After 3 iterations without APPROVED, stop and report remaining issues to user.
+After 3 iterations still BLOCKED, stop and report remaining issues to user.
 
 **Step R3 — MEDIUM / LOW Issues**
 

commands/execute-codex.md

@@ -69,8 +69,8 @@ After all tasks complete (either path):
 2. Launch Task agent (subagent_type: "feature-dev:code-reviewer") with:
    - `git diff HEAD`
    - Original task requirements
-3. If reviewer finds CRITICAL/HIGH issues: fix directly with Edit/Write and re-review (max 2 rounds)
-4. Go to Phase 3
+3. CRITICAL issues → fix every CRITICAL and HIGH issue together with Edit/Write and re-review (max 2 rounds). HIGH-only issues → fix with Edit/Write, re-run self-verification, proceed with no re-review call. If CRITICAL issues remain after the final round, STOP and report them; do not deliver.
+4. Go to Phase 3, carrying any remaining MEDIUM/LOW findings into the delivery report (user decides whether to fix)
 
 ---
 
@@ -130,11 +130,12 @@ Launch Task agent (subagent_type: "feature-dev:code-reviewer") with:
 - Original task requirements
 
 Parse reviewer response:
-- No CRITICAL/HIGH issues → approved, go to Phase 3
-- Has CRITICAL/HIGH (3+ task path) → dispatch a Claude subagent per affected task with the reviewer feedback verbatim; there is no shared `threadId` to reply to, so do not call `mcp__codex__codex-reply`. After fixes, re-run `code-reviewer` (max 3 total iterations).
-- Has CRITICAL/HIGH (single Codex session path) → call `mcp__codex__codex-reply` with reviewer feedback verbatim, increment iteration count (max 3 total iterations).
+- No CRITICAL/HIGH issues → approved, go to Phase 3, carrying any MEDIUM/LOW findings into the delivery report (user decides whether to fix)
+- Has CRITICAL (3+ task path) → dispatch a Claude subagent per affected task with the reviewer feedback verbatim, covering every CRITICAL and HIGH finding together; there is no shared `threadId` to reply to, so do not call `mcp__codex__codex-reply`. After fixes, re-run `code-reviewer` (max 3 total iterations).
+- Has CRITICAL (single Codex session path) → call `mcp__codex__codex-reply` with reviewer feedback verbatim, covering every CRITICAL and HIGH finding together, increment iteration count (max 3 total iterations). After the fixes, re-run `code-reviewer` before proceeding.
+- HIGH only → apply fixes via the same path-specific mechanism (subagents for the 3+ task path, `mcp__codex__codex-reply` asking for fixes with no re-review verdict for the single-session path), verify with scoped lint/tests, proceed, carrying any MEDIUM/LOW findings into the delivery report.
 
-After 3 iterations without approval, stop and report status to user.
+After 3 iterations still finding CRITICALs, stop and report status to user.
 
 ---
 
@@ -151,6 +152,7 @@ After 3 iterations without approval, stop and report status to user.
 ### Review Result
 - Route: Small (Claude) / Large (Codex, N/3 iterations)
 - Code review: Passed / N issues resolved
+- Remaining MEDIUM/LOW findings: N (listed above, user decides) / none
 
 ### Recommended Next Steps
 1. [ ] <test step>

commands/plan-codex.md

@@ -1,5 +1,5 @@
 ---
-description: "Claude plans with Opus, Codex audits, loop until approved"
+description: "Claude plans with Opus, Codex audits once, re-audit only on BLOCKED"
 argument-hint: "<task description>"
 model: claude-opus-4-6
 allowed-tools: ["AskUserQuestion", "mcp__codex__codex", "mcp__codex__codex-reply", "Task", "Read", "Glob", "Grep", "Write", "Bash"]
@@ -37,25 +37,31 @@ Save the returned plan to `.claude/plan/<feature-name>.md`.
 
 ### Phase 2: Codex Audit Loop (max 3 iterations)
 
-Read `~/.claude/prompts/codex/analyzer.md` and inject as `developer-instructions`.
+Read `~/.claude/skills/plan-codex/codex-analyzer-role.md` and inject as `developer-instructions`. (That file defines the `VERDICT: APPROVED | WARNING | BLOCKED` grammar the parse step below branches on; `prompts/codex/analyzer.md` also exists but predates the verdict contract and defines no grammar, so it must not be used here.)
+
+**MANDATORY Codex availability check**: `mcp__codex__codex` MUST be listed in the available tools (either in the tool list or in `<available-deferred-tools>`). Do NOT skip or bypass this phase. If the tool is genuinely absent from both locations, **stop and tell the user**: "Codex MCP is not available. This command requires Codex for plan audit. Please add the Codex MCP server." Do not proceed without Codex.
+
+**MANDATORY mid-call failure handling**: a Codex call that errors, times out or is aborted mid-audit is NOT an approval and NOT a skippable step. Retry the call exactly once. If the MCP transport itself is failing, retry via the CLI with the full audit context supplied explicitly (a bare `codex exec` with no prompt hangs reading stdin): `codex exec --sandbox read-only "$(cat ~/.claude/skills/plan-codex/codex-analyzer-role.md)"$'\n\n'"Read the plan file at .claude/plan/<feature-name>.md and audit it for correctness, completeness, security, and edge cases. Return the structured verdict."` and validate the output against the same `VERDICT:` grammar below. If the retry also dies, **stop and tell the user**: "Codex audit incomplete. The review did not run. The plan is UNREVIEWED." Never proceed to Phase 3 on a dead audit.
 
 **Call `mcp__codex__codex`** (iteration 1):
-- prompt: "Read the plan file at `.claude/plan/<feature-name>.md` and audit it for correctness, completeness, security, and edge cases. Reply APPROVED if solid, or list specific issues to fix."
+- prompt: "Read the plan file at `.claude/plan/<feature-name>.md` and audit it for correctness, completeness, security, and edge cases. Return the structured verdict (VERDICT: APPROVED | WARNING | BLOCKED) with severity-prefixed findings per your instructions."
 - sandbox: "read-only"
 - approval-policy: "never"
-- developer-instructions: {content of ~/.claude/prompts/codex/analyzer.md} + "\nBe concise. Output result only, no reasoning process."
+- developer-instructions: {content of ~/.claude/skills/plan-codex/codex-analyzer-role.md} + "\nBe concise. Output result only, no reasoning process."
 
 Save the returned `threadId`.
 
-**Parse response**:
-- Contains "APPROVED" → update `.claude/plan/<feature-name>.md` with final version, go to Phase 3
-- Contains issues → address every issue, revise plan, update `.claude/plan/<feature-name>.md`
+**Parse the exact `VERDICT:` line** (line-anchored; exactly one must be present). The word APPROVED appearing inside prose or a finding is NOT approval. A response with no verdict line, multiple verdict lines, or a value other than APPROVED, WARNING or BLOCKED is malformed: retry the call once, and if the retry is also malformed, stop and tell the user the plan is UNREVIEWED.
+**Critical evaluation gate** (before acting on ANY finding): assess whether it is technically accurate against the actual codebase, whether the reviewer had full context for intentional decisions, and whether it improves the plan or is a preference/false positive. Contest doubtful findings via `codex-reply` with specific reasoning; discussion replies do not count as audit iterations. Only findings that survive this gate are "accepted" below.
+- `VERDICT: APPROVED` → fold any accompanying MEDIUM/LOW findings into the plan's notes (the analyzer role explicitly permits them), update `.claude/plan/<feature-name>.md` with final version, go to Phase 3
+- `VERDICT: WARNING` (no CRITICAL) → fold the accepted findings into the plan, update `.claude/plan/<feature-name>.md`, go to Phase 3 with no further Codex call
+- `VERDICT: BLOCKED` (CRITICAL findings) → address every CRITICAL and any accompanying HIGH findings, revise plan, update `.claude/plan/<feature-name>.md`, re-audit
 
 **Call `mcp__codex__codex-reply`** (iterations 2-3):
 - threadId: {saved threadId}
-- prompt: "The plan has been revised to address your feedback. Re-read the plan file at `.claude/plan/<feature-name>.md` and audit it again for correctness, completeness, security, and edge cases. Reply APPROVED if solid, or list specific issues to fix."
+- prompt: "The plan has been revised to address your feedback. Re-read the plan file at `.claude/plan/<feature-name>.md` and audit it again for correctness, completeness, security, and edge cases. Return the structured verdict (VERDICT: APPROVED | WARNING | BLOCKED) with severity-prefixed findings per your instructions."
 
-After 3 iterations without APPROVED, stop and ask user for direction.
+After 3 iterations still BLOCKED, stop and ask user for direction.
 
 ### Phase 3: Deliver
 

commands/tdd-claude-codex.md

@@ -99,9 +99,10 @@ Save the returned `threadId` (separate from the implementation review threadId).
 
 **Parse response**:
 - **APPROVED** → proceed to Phase 4
-- **WARNING/BLOCKED** → Claude fixes all CRITICAL/HIGH issues in the test files, re-verifies RED, then re-calls via `mcp__codex__codex-reply` (max 2 iterations)
+- **WARNING** (no CRITICAL) → Claude fixes the accepted issues in the test files, re-verifies RED, proceeds with no further Codex call
+- **BLOCKED** → Claude fixes all CRITICAL/HIGH issues in the test files, re-verifies RED, then re-calls via `mcp__codex__codex-reply` (max 2 iterations)
 
-After 2 iterations without APPROVED, stop and ask user for direction.
+After 2 iterations still BLOCKED, stop and ask user for direction.
 
 ### Phase 4: Claude Implements (GREEN)
 
@@ -158,11 +159,11 @@ LOW: <list or 'none'>
 Save the returned `threadId` for follow-up replies.
 
 Classify the verdict:
-- **APPROVED** — no CRITICAL or HIGH → go to Phase 7
-- **WARNING** — HIGH issues only → fix all, increment iteration, re-review
+- **APPROVED** — no CRITICAL or HIGH → handle any MEDIUM/LOW findings per Step R3, then go to Phase 7
+- **WARNING** — HIGH issues only → fix all accepted HIGHs in one batch, re-run the test suite (must stay GREEN), handle MEDIUM/LOW per Step R3, then go to Phase 7 with no re-review call
 - **BLOCKED** — CRITICAL issues → fix all, increment iteration, re-review
 
-**Step R2 — Fix and Re-review**
+**Step R2 — Fix and Re-review (BLOCKED verdicts only)**
 
 Address ALL CRITICAL and HIGH issues before re-reviewing:
 - Collect every CRITICAL/HIGH finding from the last review
@@ -176,8 +177,8 @@ Run `git diff $START_SHA` again to see the updated changes, then re-review.
 Return ONLY the structured verdict in the same format.
 ```
 
-One review per iteration, not one review per fix. Stop after 3 iterations without APPROVED.
-After 3 iterations without APPROVED, stop and report remaining issues to user.
+One review per iteration, not one review per fix. Only BLOCKED verdicts trigger a re-review.
+After 3 iterations still BLOCKED, stop and report remaining issues to user.
 
 **Step R3 — MEDIUM / LOW Issues**