Opt-In feature to use /codex:review from claude cli to improve the quality of a /review mission

[atoomic]

Feature: Support structured JSON output for Codex reviews

Summary

Investigate integrating codex-plugin-cc into Koan so review results
can be consumed programmatically instead of parsing Markdown.

Findings

/codex:review --json

Although the companion script accepts a --json flag, the actual review
findings are not returned as structured JSON.

The JSON envelope looks roughly like:

{
  "review": "Review",
  "threadId": "...",
  "codex": {
    "status": 0,
    "stdout": "### Findings\n- [P1] ...",
    "stderr": "",
    "reasoning": "..."
  }
}

The review itself is still Markdown contained in codex.stdout.

Implication for Koan

Koan can reliably parse the outer JSON envelope but would still need to
parse Markdown or free-form text to extract findings.

This is brittle and provider-specific.

Better alternative

The plugin already provides an adversarial-review mode which uses a
JSON Schema.

Example schema:

{
  "verdict": "approve | needs-attention",
  "summary": "...",
  "findings": [
    {
      "severity": "critical | high | medium | low",
      "title": "...",
      "body": "...",
      "file": "...",
      "line_start": 10,
      "line_end": 15,
      "confidence": 0.95,
      "recommendation": "..."
    }
  ],
  "next_steps": [
    "..."
  ]
}

This format is much better suited for Koan.

Recommendation

Instead of consuming /codex:review --json, Koan should:

1. Prefer adversarial-review --json.
2. Convert the structured output into an internal provider-independent
   review model.
3. Keep the raw provider output for debugging.

Example:

ReviewResult
 ├── verdict
 ├── summary
 ├── findings[]
 ├── next_steps[]
 ├── provider
 └── raw_output

Proposed Koan model

@dataclass
class ReviewFinding:
    severity: str
    title: str
    body: str
    file: str
    line_start: int
    line_end: int
    confidence: float
    recommendation: str

@dataclass
class ReviewResult:
    verdict: str
    summary: str
    findings: list[ReviewFinding]
    next_steps: list[str]
    provider: str
    raw_output: str | None = None

Possible future improvement

If Koan still wants to use the standard review command, consider
extending codex-plugin-cc with a dedicated structured mode that emits
the same JSON schema as adversarial-review.

That would allow all review commands to expose a stable machine-readable
API.

Benefits

• No Markdown parsing
• Stable integration
• Provider-independent architecture
• Easier Slack/GitHub/Telegram formatting
• Easier analytics and severity filtering
• Future support for Claude, Copilot and other review providers

Acceptance Criteria

• Koan can execute Codex review commands and receive structured
  JSON.
• Findings map to an internal ReviewResult.
• Presentation is handled entirely by Koan.
• Raw provider output is preserved for debugging.
• Architecture supports multiple review providers.

References

• https://github.com/openai/codex-plugin-cc

[atoomic]

The /codex:adversarial-review --json is clearly what could improve the quality of a /review mission from koan as it returns a well structured output.
Once enabled (using config), we should then try using it for review and use the same format output we currently use.

[Grokki-Bot]

I'll explore the codebase and docs around /review missions and any Codex review integration so the updated plan matche

Next I'll inspect the review skill pipeline, schema, and config so the plan can plug Codex structured reviews into the existing flow.
I have enough context: the durable review contract, adversarial JSON schema, and atoomic’s opt-in guidance. Writing the consolidated plan next.
Opt-in Codex adversarial-review backend for /review missions

Changes in this iteration

• Incorporated atoomic’s direction: make this opt-in via config, prefer /codex:adversarial-review --json, and keep Koan’s existing review presentation format (not a parallel markdown/parser path).
• Dropped the original plan’s primary ReviewResult dataclass as the public model. Map Codex structured output into the existing REVIEW_SCHEMA (file_comments + review_summary) so posting, LGTM derivation, inline comments, sidecars, and evals keep working unchanged. Preserve the raw provider payload for debugging only.
• Chose direct headless invocation of codex-companion.mjs adversarial-review --json (not Claude Code slash-command plumbing, which is interactive-oriented).
• Verified against current code: run_review → _run_review_analysis → _run_claude_review → validate_review / _format_review_as_markdown in koan/app/review_runner.py and koan/app/review_schema.py.
• Confirmed Codex plugin schema at plugins/codex/schemas/review-output.schema.json (verdict, summary, findings[], next_steps[] with severities critical|high|medium|low).
• Documented that durable skill contract (specs/skills/review.md) is an architectural surface and must be updated contract-first.

Summary

Add an opt-in /review analysis backend that runs OpenAI’s codex-plugin-cc adversarial-review mode with structured JSON, converts findings into Koan’s existing review schema, and continues to post/format/verdict through the current pipeline. Default path is unchanged. When enabled and Codex is available, review quality improves via adversarial structured findings without Markdown parsing and without rewriting presentation.

Context (docs / specs)

• wiki/index.md → specs/skills/review.md: /review posts findings as a comment; verdict follows severity (lgtm true only when no critical/warning); output contract is review_schema.py; presentation is Koan-owned.
• specs/components/skills.md: review is scored via validate_review against that schema.
• docs/providers/codex.md: covers Codex as a CLI provider for missions — different from the Claude Code plugin companion used here. No existing doc covers codex-plugin-cc adversarial review.
• Nothing relevant was found for an existing codex-plugin review backend in Koan.
• Architectural surface: yes — specs/skills/review.md (and a short docs note). Declare as architectural in the PR.

Alternatives Considered

• Approach A (chosen): Opt-in config; invoke codex-companion.mjs adversarial-review --json headlessly; map result into existing REVIEW_SCHEMA; fall back to the current provider review on failure. Trade-off: depends on Node + Codex CLI + companion install, but reuses a stable schema and all existing presentation code.
• Approach B: Parse /codex:review --json Markdown from codex.stdout. Trade-off: brittle Markdown parsing; rejected by the original investigation and by atoomic’s preference for adversarial structured output.
• Approach C: Introduce a new first-class ReviewResult model and rewrite formatters/verdicts around it. Trade-off: large blast radius for little gain; conflicts with “use the same format output we currently use.” Keep only a thin internal mapper + optional raw payload.

File Map

Action	File	Responsibility
Modify	specs/skills/review.md	Contract: opt-in Codex adversarial backend, mapping rules, fallback, invariants
Create	koan/app/codex_adversarial_review.py	Companion discovery, PR git prep, invoke, parse payload, map to REVIEW_SCHEMA
Modify	koan/app/config.py	get_review_codex_adversarial_config()
Modify	koan/app/review_runner.py	Branch in _run_review_analysis when enabled; attribution when Codex path used
Modify	instance.example/config.yaml	Documented opt-in section
Modify	docs/users/skills.md	Short operator note for the opt-in backend
Modify	docs/providers/codex.md	Setup for companion-based adversarial reviews (distinct from provider mode)
Test	koan/tests/test_codex_adversarial_review.py	Mapper, parser, config, invoke mocking, fallback
Test	koan/tests/test_review_runner.py	Integration: enabled path skips default provider analysis and still formats

Implementation Phases

Phase 1: Contract-first skill spec + config surface

Files: specs/skills/review.md, koan/app/config.py, instance.example/config.yaml, koan/tests/test_codex_adversarial_review.py

• What: Declare the opt-in backend in the skill contract, then add config getter + example YAML.

• Why: Durable contracts change first (specs discipline). Config defaults keep behavior off.

• Gotchas: This is an architectural change — PR must check the architectural-change box. Default must remain enabled: false.

• Step 1: Write the failing config test

  Test code

  # koan/tests/test_codex_adversarial_review.py
  import os
  from pathlib import Path
  
  import yaml
  
  
  def test_review_codex_adversarial_config_defaults(tmp_path, monkeypatch):
      root = tmp_path / "koan-root"
      inst = root / "instance"
      inst.mkdir(parents=True)
      (inst / "config.yaml").write_text("cli_provider: claude\n")
      monkeypatch.setenv("KOAN_ROOT", str(root))
      # force config reload if cached
      import app.config as config_mod
      if hasattr(config_mod, "_load_config"):
          config_mod._load_config.cache_clear() if hasattr(config_mod._load_config, "cache_clear") else None
  
      from app.config import get_review_codex_adversarial_config
  
      cfg = get_review_codex_adversarial_config()
      assert cfg["enabled"] is False
      assert cfg["fallback_to_default"] is True
      assert cfg["timeout_seconds"] == 900
      assert cfg["companion_script"] == ""
      assert cfg["model"] == ""
      assert cfg["run_reflection"] is True
  
  
  def test_review_codex_adversarial_config_enabled(tmp_path, monkeypatch):
      root = tmp_path / "koan-root"
      inst = root / "instance"
      inst.mkdir(parents=True)
      (inst / "config.yaml").write_text(
          yaml.dump({
              "review_codex_adversarial": {
                  "enabled": True,
                  "companion_script": "/opt/codex-companion.mjs",
                  "timeout_seconds": 600,
                  "model": "gpt-5.4",
                  "fallback_to_default": False,
                  "run_reflection": False,
              }
          })
      )
      monkeypatch.setenv("KOAN_ROOT", str(root))
      import app.config as config_mod
      if hasattr(config_mod._load_config, "cache_clear"):
          config_mod._load_config.cache_clear()
  
      from app.config import get_review_codex_adversarial_config
  
      cfg = get_review_codex_adversarial_config()
      assert cfg["enabled"] is True
      assert cfg["companion_script"] == "/opt/codex-companion.mjs"
      assert cfg["timeout_seconds"] == 600
      assert cfg["model"] == "gpt-5.4"
      assert cfg["fallback_to_default"] is False
      assert cfg["run_reflection"] is False

• Step 2: Implement config getter

  Implementation

  # koan/app/config.py — add near other get_review_* helpers
  
  def get_review_codex_adversarial_config() -> dict:
      """Opt-in Codex adversarial-review backend for /review analysis.
  
      Config key: review_codex_adversarial::
  
          review_codex_adversarial:
            enabled: false
            companion_script: ""      # path to codex-companion.mjs; empty = auto-discover
            timeout_seconds: 900
            model: ""                 # optional Codex model override
            fallback_to_default: true # on failure, use normal provider review
            run_reflection: true      # run existing reflection pass after mapping
  
      Defaults keep the feature off. Malformed values fail closed to safe defaults.
      """
      config = _load_config()
      section = config.get("review_codex_adversarial", {})
      if not isinstance(section, dict):
          section = {}
  
      def _bool(key: str, default: bool) -> bool:
          val = section.get(key, default)
          return val if isinstance(val, bool) else default
  
      timeout = section.get("timeout_seconds", 900)
      try:
          timeout = int(timeout)
      except (TypeError, ValueError):
          timeout = 900
      timeout = max(60, min(timeout, 3600))
  
      companion = section.get("companion_script", "")
      if not isinstance(companion, str):
          companion = ""
      model = section.get("model", "")
      if not isinstance(model, str):
          model = ""
  
      return {
          "enabled": _bool("enabled", False),
          "companion_script": companion.strip(),
          "timeout_seconds": timeout,
          "model": model.strip(),
          "fallback_to_default": _bool("fallback_to_default", True),
          "run_reflection": _bool("run_reflection", True),
      }

• Step 3: Update skill spec + example config

  Spec excerpt to add under Invariants / Integration

  ## Opt-in Codex adversarial backend
  
  When `review_codex_adversarial.enabled` is true, the analysis step may invoke
  the local `codex-plugin-cc` companion:
  
      node <companion> adversarial-review --json --base <base> [--model <m>]
  
  instead of the normal `review_mode` provider prompt. Requirements:
  
  - **Opt-in only** (default off). Disabled = byte-identical current behavior.
  - Prefer **adversarial-review** structured JSON (`result` field). Do **not**
    parse Markdown from plain `/codex:review`.
  - Map provider findings into existing `REVIEW_SCHEMA` (`file_comments` +
    `review_summary`). Presentation, LGTM derivation, inline comments, and
    sidecars remain unchanged.
  - Severity map: `critical→critical`, `high→critical`, `medium→warning`,
    `low→suggestion`. `lgtm` is **always re-derived from mapped severities**
    (ignore provider `verdict` for the formal GitHub verdict).
  - Preserve raw companion JSON payload in logs/debug only — never post raw
    provider JSON to the PR.
  - On companion missing/failure: if `fallback_to_default`, run the normal
    provider path; else fail the review with a clear error.
  - Does not change pause-label, draft-skip, or `--force` gates.

  Example config

  # instance.example/config.yaml — near other review_* sections
  # Opt-in Codex adversarial-review backend for /review analysis.
  # Requires Node + Codex CLI + codex-plugin-cc companion script.
  # review_codex_adversarial:
  #   enabled: false
  #   companion_script: ""      # empty = auto-discover common install paths
  #   timeout_seconds: 900
  #   model: ""                 # optional Codex model override
  #   fallback_to_default: true
  #   run_reflection: true

• Step 4: Verify

  Command

  KOAN_ROOT=/tmp/test-koan .venv/bin/pytest koan/tests/test_codex_adversarial_review.py -v -k config
  # Expected: PASS

• Step 5: Commit

  docs(review): contract-first opt-in Codex adversarial review backend

Done when: Spec documents the backend; config defaults off; tests pass.

---

Phase 2: Structured JSON → existing review schema mapper

Files: koan/app/codex_adversarial_review.py, koan/tests/test_codex_adversarial_review.py

• What: Pure functions: parse companion --json payload; map result into REVIEW_SCHEMA; validate with validate_review.

• Why: Keeps presentation identical (atoomic); no Markdown parsing.

• Gotchas: Companion JSON is a payload envelope (result, rawOutput, parseError, codex). Use payload["result"], not codex.stdout. Do not use find("{")…rfind("}") on stdout. Derive lgtm from mapped severities only.

• Step 1: Write mapper tests

  Test code

  from app.codex_adversarial_review import (
      map_adversarial_to_review,
      parse_companion_payload,
  )
  from app.review_schema import validate_review
  
  
  def test_parse_companion_payload_extracts_result():
      payload = {
          "review": "Adversarial Review",
          "result": {
              "verdict": "needs-attention",
              "summary": "Race on token refresh can drop sessions.",
              "findings": [
                  {
                      "severity": "high",
                      "title": "TOCTOU on session refresh",
                      "body": "Concurrent refresh can invalidate a valid token.",
                      "file": "src/auth.py",
                      "line_start": 42,
                      "line_end": 55,
                      "confidence": 0.9,
                      "recommendation": "Serialize refresh under a lock.",
                  }
              ],
              "next_steps": ["Add a concurrency test"],
          },
          "rawOutput": '{"verdict":"..."}',
          "parseError": None,
      }
      result, raw = parse_companion_payload(payload)
      assert result["verdict"] == "needs-attention"
      assert raw  # preserves raw for debugging
  
  
  def test_map_adversarial_to_review_schema_and_lgtm():
      adversarial = {
          "verdict": "needs-attention",
          "summary": "Ship-blockers present.",
          "findings": [
              {
                  "severity": "high",
                  "title": "SQL injection",
                  "body": "User input concatenated into query.",
                  "file": "db.py",
                  "line_start": 10,
                  "line_end": 12,
                  "confidence": 0.95,
                  "recommendation": "Use parameterized queries.",
              },
              {
                  "severity": "low",
                  "title": "Naming nit",
                  "body": "Prefer clearer name.",
                  "file": "util.py",
                  "line_start": 1,
                  "line_end": 1,
                  "confidence": 0.5,
                  "recommendation": "",
              },
          ],
          "next_steps": ["Add fuzz tests"],
      }
      review = map_adversarial_to_review(adversarial)
      ok, errors = validate_review(review)
      assert ok, errors
      severities = {c["severity"] for c in review["file_comments"]}
      assert "critical" in severities  # high → critical
      assert "suggestion" in severities  # low → suggestion
      assert review["review_summary"]["lgtm"] is False
      assert "Add fuzz tests" in review["review_summary"]["summary"]
      # recommendation folded into comment body
      sql = next(c for c in review["file_comments"] if c["file"] == "db.py")
      assert "parameterized" in sql["comment"].lower()
  
  
  def test_map_approve_with_no_findings_is_lgtm():
      adversarial = {
          "verdict": "approve",
          "summary": "No material risks found.",
          "findings": [],
          "next_steps": [],
      }
      review = map_adversarial_to_review(adversarial)
      ok, errors = validate_review(review)
      assert ok, errors
      assert review["review_summary"]["lgtm"] is True
      assert review["file_comments"] == []

• Step 2: Implement mapper module

  Implementation

  # koan/app/codex_adversarial_review.py
  """Codex adversarial-review backend for /review (opt-in).
  
  Invokes codex-plugin-cc's companion script and maps structured output into
  Koan's existing REVIEW_SCHEMA so presentation stays provider-independent.
  """
  
  from __future__ import annotations
  
  import json
  from typing import Any, Optional, Tuple
  
  # Codex adversarial severities → Koan severities
  _SEVERITY_MAP = {
      "critical": "critical",
      "high": "critical",
      "medium": "warning",
      "low": "suggestion",
  }
  
  
  def parse_companion_payload(payload: Any) -> Tuple[Optional[dict], Optional[str]]:
      """Extract structured adversarial result + raw debug string from companion JSON.
  
      Returns (result_dict_or_None, raw_output_or_None).
      """
      if not isinstance(payload, dict):
          return None, None
      raw = payload.get("rawOutput")
      if not isinstance(raw, str):
          # Fall back to serializing the whole payload for debug retention
          try:
              raw = json.dumps(payload)
          except (TypeError, ValueError):
              raw = None
      if payload.get("parseError"):
          return None, raw
      result = payload.get("result")
      if not isinstance(result, dict):
          return None, raw
      return result, raw
  
  
  def map_adversarial_to_review(adversarial: dict) -> dict:
      """Convert adversarial-review schema into Koan REVIEW_SCHEMA dict."""
      findings_in = adversarial.get("findings") or []
      if not isinstance(findings_in, list):
          findings_in = []
  
      file_comments: list = []
      for item in findings_in:
          if not isinstance(item, dict):
              continue
          sev = _SEVERITY_MAP.get(str(item.get("severity", "")).lower(), "suggestion")
          title = str(item.get("title") or "Finding").strip() or "Finding"
          body = str(item.get("body") or "").strip() or "No details provided."
          rec = str(item.get("recommendation") or "").strip()
          if rec:
              body = f"{body}\n\n**Recommendation:** {rec}"
          try:
              line_start = int(item.get("line_start") or 0)
          except (TypeError, ValueError):
              line_start = 0
          try:
              line_end = int(item.get("line_end") or line_start)
          except (TypeError, ValueError):
              line_end = line_start
          if line_start < 0:
              line_start = 0
          if line_end < line_start:
              line_end = line_start
  
          file_comments.append({
              "file": str(item.get("file") or "unknown").strip() or "unknown",
              "line_start": line_start,
              "line_end": line_end,
              "severity": sev,
              "title": title,
              "comment": body,
              "code_snippet": "",
          })
  
      summary = str(adversarial.get("summary") or "").strip() or "Review completed."
      next_steps = adversarial.get("next_steps") or []
      if isinstance(next_steps, list):
          steps = [str(s).strip() for s in next_steps if str(s).strip()]
          if steps:
              summary = summary + "\n\n**Next steps:**\n" + "\n".join(f"- {s}" for s in steps)
  
      has_blocker = any(c["severity"] in {"critical", "warning"} for c in file_comments)
      return {
          "file_comments": file_comments,
          "review_summary": {
              "lgtm": not has_blocker,
              "summary": summary,
              "checklist": [],
          },
      }

• Step 3: Verify

  Command

  KOAN_ROOT=/tmp/test-koan .venv/bin/pytest koan/tests/test_codex_adversarial_review.py -v -k "map_ or parse_"
  # Expected: PASS

• Step 4: Commit

  feat(review): map Codex adversarial JSON into REVIEW_SCHEMA

Done when: Mapper produces validate_review-clean dicts; severity/lgtm rules match skill invariants.

---

Phase 3: Companion discovery + headless invoke

Files: koan/app/codex_adversarial_review.py, koan/tests/test_codex_adversarial_review.py

• What: Resolve companion path; run node <script> adversarial-review --json --base <ref> … with cwd = prepared worktree; parse entire stdout as JSON.

• Why: Headless Koan cannot rely on Claude Code slash commands.

• Gotchas: Mock subprocess in tests — never call real Codex. Timeout via subprocess.run(..., timeout=…). Non-zero exit with empty/unparseable stdout is failure. PATH must include node and codex.

• Step 1: Write discovery + invoke tests

  Test code

  import json
  from pathlib import Path
  from unittest.mock import MagicMock
  
  from app.codex_adversarial_review import (
      discover_companion_script,
      run_adversarial_review,
  )
  
  
  def test_discover_explicit_path(tmp_path):
      script = tmp_path / "codex-companion.mjs"
      script.write_text("// stub\n")
      assert discover_companion_script(str(script)) == str(script.resolve())
  
  
  def test_discover_missing_returns_none(tmp_path):
      assert discover_companion_script(str(tmp_path / "nope.mjs")) is None
  
  
  def test_run_adversarial_review_parses_json_stdout(monkeypatch, tmp_path):
      script = tmp_path / "codex-companion.mjs"
      script.write_text("// stub\n")
      payload = {
          "result": {
              "verdict": "approve",
              "summary": "Clean.",
              "findings": [],
              "next_steps": [],
          },
          "rawOutput": "{}",
          "parseError": None,
      }
  
      def fake_run(cmd, **kwargs):
          m = MagicMock()
          m.returncode = 0
          m.stdout = json.dumps(payload)
          m.stderr = ""
          return m
  
      monkeypatch.setattr("app.codex_adversarial_review.subprocess.run", fake_run)
      review, raw, err = run_adversarial_review(
          project_path=str(tmp_path),
          base_ref="main",
          companion_script=str(script),
          timeout_seconds=30,
      )
      assert err == ""
      assert review is not None
      assert review["review_summary"]["lgtm"] is True
      assert raw  # raw companion payload retained

• Step 2: Implement discovery + invoke

  Implementation

  # append to koan/app/codex_adversarial_review.py
  import os
  import subprocess
  import sys
  from pathlib import Path
  
  _DISCOVERY_CANDIDATES = (
      # Explicit env wins after config path (checked by caller)
      # Common Claude Code plugin cache layouts (versioned dirs):
      # ~/.claude/plugins/cache/**/codex-companion.mjs — searched shallowly
  )
  
  
  def discover_companion_script(configured: str = "") -> Optional[str]:
      """Return absolute path to codex-companion.mjs or None."""
      if configured:
          p = Path(configured).expanduser()
          if p.is_file():
              return str(p.resolve())
          return None
      env = os.environ.get("CODEX_PLUGIN_ROOT", "").strip()
      if env:
          candidate = Path(env).expanduser() / "scripts" / "codex-companion.mjs"
          if candidate.is_file():
              return str(candidate.resolve())
      home = Path.home()
      roots = [
          home / ".claude" / "plugins" / "cache",
          home / ".claude" / "plugins" / "marketplaces",
      ]
      for root in roots:
          if not root.is_dir():
              continue
          # Bounded search: only *codex*/**/scripts/codex-companion.mjs
          for match in root.glob("**/scripts/codex-companion.mjs"):
              if match.is_file() and "codex" in str(match).lower():
                  return str(match.resolve())
      return None
  
  
  def run_adversarial_review(
      *,
      project_path: str,
      base_ref: str,
      companion_script: str = "",
      timeout_seconds: int = 900,
      model: str = "",
      focus_text: str = "",
  ) -> Tuple[Optional[dict], str, str]:
      """Run companion adversarial-review --json and return (review_data, raw, error)."""
      script = discover_companion_script(companion_script)
      if not script:
          return None, "", "codex companion script not found"
  
      cmd = [
          "node", script,
          "adversarial-review",
          "--json",
          "--base", base_ref,
      ]
      if model:
          cmd.extend(["--model", model])
      if focus_text.strip():
          cmd.append(focus_text.strip())
  
      try:
          proc = subprocess.run(
              cmd,
              cwd=project_path,
              capture_output=True,
              text=True,
              timeout=timeout_seconds,
              check=False,
          )
      except FileNotFoundError:
          return None, "", "node binary not found"
      except subprocess.TimeoutExpired:
          return None, "", f"codex adversarial-review timed out after {timeout_seconds}s"
  
      stdout = (proc.stdout or "").strip()
      stderr = (proc.stderr or "").strip()
      if not stdout:
          return None, stderr, (
              f"codex adversarial-review produced no stdout (exit={proc.returncode})"
              + (f": {stderr[:200]}" if stderr else "")
          )
  
      try:
          payload = json.loads(stdout)
      except json.JSONDecodeError as exc:
          return None, stdout, f"companion stdout is not JSON: {exc}"
  
      adversarial, raw = parse_companion_payload(payload)
      if adversarial is None:
          pe = payload.get("parseError") if isinstance(payload, dict) else None
          return None, raw or stdout, f"structured result missing ({pe or 'no result'})"
  
      review = map_adversarial_to_review(adversarial)
      from app.review_schema import validate_review
      ok, errors = validate_review(review)
      if not ok:
          return None, raw or stdout, "mapped review failed validation: " + "; ".join(errors)
      return review, raw or stdout, ""

• Step 3: Verify

  Command

  KOAN_ROOT=/tmp/test-koan .venv/bin/pytest koan/tests/test_codex_adversarial_review.py -v
  # Expected: PASS

• Step 4: Commit

  feat(review): invoke codex-companion adversarial-review --json headlessly

Done when: Discovery + mocked invoke path returns validated review data.

---

Phase 4: PR git preparation for local Codex context

Files: koan/app/codex_adversarial_review.py, koan/tests/test_codex_adversarial_review.py

• What: Fetch PR head + base into temp refs; create a disposable worktree at head; run companion there; always clean up.

• Why: Current /review only feeds GitHub diffs into the LLM — it does not checkout the PR. Codex companion reviews local git (base...HEAD).

• Gotchas: Do not leave the main project on a random branch. Prefer temp worktree under .worktrees/. Fail clearly if fetch fails (fork PRs may need pull/<n>/head).

• Step 1: Write git-prep tests (mock git)

  Test code

  from unittest.mock import patch
  from app.codex_adversarial_review import prepare_pr_worktree, cleanup_pr_worktree
  
  
  def test_prepare_pr_worktree_uses_temp_paths(tmp_path, monkeypatch):
      project = tmp_path / "proj"
      project.mkdir()
      (project / ".git").mkdir()
  
      calls = []
  
      def fake_git(args, cwd):
          calls.append(list(args))
          class R:
              returncode = 0
              stdout = "abc123\n"
              stderr = ""
          return R()
  
      monkeypatch.setattr("app.codex_adversarial_review._git", fake_git)
      # create_worktree path: simulate success by making the dir
      def fake_git_wt(args, cwd):
          calls.append(list(args))
          class R:
              returncode = 0
              stdout = ""
              stderr = ""
          if args[:2] == ["worktree", "add"]:
              Path(args[2]).mkdir(parents=True, exist_ok=True)
          return R()
  
      monkeypatch.setattr("app.codex_adversarial_review._git", fake_git_wt)
      wt, base_ref, err = prepare_pr_worktree(
          str(project), pr_number="42", base_branch="main",
      )
      assert err == ""
      assert wt is not None
      assert Path(wt).is_dir()
      cleanup_pr_worktree(str(project), wt)

• Step 2: Implement prepare/cleanup

  Implementation

  def _git(args: list, cwd: str) -> subprocess.CompletedProcess:
      return subprocess.run(
          ["git", *args],
          cwd=cwd,
          capture_output=True,
          text=True,
          check=False,
      )
  
  
  def prepare_pr_worktree(
      project_path: str,
      *,
      pr_number: str,
      base_branch: str,
  ) -> Tuple[Optional[str], str, str]:
      """Fetch PR head/base and create a disposable worktree.
  
      Returns (worktree_path, base_ref_for_companion, error).
      """
      import time
      import uuid
  
      head_ref = f"refs/koan-tmp/codex-review-{pr_number}-head"
      base_ref = f"refs/koan-tmp/codex-review-{pr_number}-base"
      token = uuid.uuid4().hex[:8]
      wt_path = str(Path(project_path) / ".worktrees" / f"codex-review-{pr_number}-{token}")
  
      # Prefer pull/N/head so fork PRs work
      r = _git(["fetch", "--no-tags", "origin", f"pull/{pr_number}/head:{head_ref}"], project_path)
      if r.returncode != 0:
          return None, "", f"fetch PR head failed: {r.stderr.strip()}"
      r = _git(["fetch", "--no-tags", "origin", f"{base_branch}:{base_ref}"], project_path)
      if r.returncode != 0:
          # base branch name may already exist as origin/<base>
          r2 = _git(["rev-parse", "--verify", f"origin/{base_branch}"], project_path)
          if r2.returncode != 0:
              return None, "", f"fetch base {base_branch} failed: {r.stderr.strip()}"
          base_ref = f"origin/{base_branch}"
  
      Path(wt_path).parent.mkdir(parents=True, exist_ok=True)
      r = _git(["worktree", "add", "--detach", wt_path, head_ref], project_path)
      if r.returncode != 0:
          return None, "", f"worktree add failed: {r.stderr.strip()}"
      return wt_path, base_ref, ""
  
  
  def cleanup_pr_worktree(project_path: str, worktree_path: Optional[str]) -> None:
      if not worktree_path:
          return
      _git(["worktree", "remove", "--force", worktree_path], project_path)
      # best-effort prune
      _git(["worktree", "prune"], project_path)

• Step 3: Verify + commit

  Command

  KOAN_ROOT=/tmp/test-koan .venv/bin/pytest koan/tests/test_codex_adversarial_review.py -v
  # Expected: PASS

  feat(review): prepare disposable worktree for Codex adversarial PR review

Done when: Worktree prep is isolated and cleaned up; no permanent branch checkout of the main tree.

---

Phase 5: Wire into _run_review_analysis (opt-in branch)

Files: koan/app/review_runner.py, koan/tests/test_review_runner.py, koan/tests/test_codex_adversarial_review.py

• What: When config enabled, attempt Codex path before _run_claude_review. On success, optionally run reflection. On failure, fallback or error per config. Attribution should show Codex when that path ran.

• Why: Single integration point shared by run_review and run_private_review.

• Gotchas: Pass base from PR context and pr_number. Focus flags (architecture, errors) can become focus text. Keep reflection behind run_reflection. Do not post raw companion JSON.

• Step 1: Write integration test

  Test code

  # in koan/tests/test_review_runner.py or test_codex_adversarial_review.py
  from unittest.mock import patch
  from app.review_runner import _run_review_analysis
  
  
  def test_run_review_analysis_uses_codex_when_enabled(monkeypatch):
      mapped = {
          "file_comments": [],
          "review_summary": {"lgtm": True, "summary": "ok", "checklist": []},
      }
  
      monkeypatch.setattr(
          "app.config.get_review_codex_adversarial_config",
          lambda: {
              "enabled": True,
              "companion_script": "/x.mjs",
              "timeout_seconds": 60,
              "model": "",
              "fallback_to_default": True,
              "run_reflection": False,
          },
      )
  
      with patch(
          "app.codex_adversarial_review.try_codex_adversarial_review",
          return_value=(mapped, '{"result":{}}', ""),
      ) as codex, patch(
          "app.review_runner._run_claude_review"
      ) as claude:
          data, raw, err = _run_review_analysis(
              prompt="unused",
              project_path="/tmp/p",
              diff="diff",
              project_name="demo",
              pr_number="7",
              base_branch="main",
          )
          assert data is not None
          assert data["review_summary"]["lgtm"] is True
          codex.assert_called_once()
          claude.assert_not_called()
  
  
  def test_run_review_analysis_falls_back_when_codex_fails(monkeypatch):
      monkeypatch.setattr(
          "app.config.get_review_codex_adversarial_config",
          lambda: {
              "enabled": True,
              "companion_script": "",
              "timeout_seconds": 60,
              "model": "",
              "fallback_to_default": True,
              "run_reflection": False,
          },
      )
      valid_json = (
          '{"file_comments":[],'
          '"review_summary":{"lgtm":true,"summary":"ok","checklist":[]}}'
      )
      with patch(
          "app.codex_adversarial_review.try_codex_adversarial_review",
          return_value=(None, "", "companion missing"),
      ), patch(
          "app.review_runner._run_claude_review",
          return_value=(valid_json, ""),
      ):
          data, raw, err = _run_review_analysis(
              prompt="p", project_path="/tmp/p", diff="", project_name="",
              pr_number="1", base_branch="main",
          )
          assert data is not None
          assert data["review_summary"]["lgtm"] is True

• Step 2: Implement wiring

  Implementation

  # koan/app/codex_adversarial_review.py
  def try_codex_adversarial_review(
      *,
      project_path: str,
      pr_number: str,
      base_branch: str,
      cfg: dict,
      focus_text: str = "",
  ) -> Tuple[Optional[dict], str, str]:
      """Full path: prep worktree → invoke → cleanup. Returns (review, raw, err)."""
      wt, base_ref, err = prepare_pr_worktree(
          project_path, pr_number=pr_number, base_branch=base_branch or "main",
      )
      if err:
          return None, "", err
      try:
          return run_adversarial_review(
              project_path=wt,
              base_ref=base_ref,
              companion_script=cfg.get("companion_script", ""),
              timeout_seconds=int(cfg.get("timeout_seconds", 900)),
              model=cfg.get("model", ""),
              focus_text=focus_text,
          )
      finally:
          cleanup_pr_worktree(project_path, wt)
  
  
  # koan/app/review_runner.py — extend _run_review_analysis signature carefully
  def _run_review_analysis(
      prompt: str,
      project_path: str,
      diff: str,
      skill_dir: Optional[Path] = None,
      project_name: Optional[str] = None,
      pr_number: Optional[str] = None,
      base_branch: Optional[str] = None,
      focus_text: str = "",
  ) -> Tuple[Optional[dict], str, Optional[str]]:
      pname = project_name or ""
      from app.config import get_review_codex_adversarial_config
      codex_cfg = get_review_codex_adversarial_config()
  
      if codex_cfg["enabled"] and pr_number:
          from app.codex_adversarial_review import try_codex_adversarial_review
          review_data, raw_output, error = try_codex_adversarial_review(
              project_path=project_path,
              pr_number=str(pr_number),
              base_branch=base_branch or "main",
              cfg=codex_cfg,
              focus_text=focus_text,
          )
          if review_data is not None:
              if codex_cfg.get("run_reflection", True) and review_data.get("file_comments"):
                  # reuse existing reflection block (same as below)
                  ...  # call _reflect_findings + _reconcile_review_after_reflection
              return review_data, raw_output, None
          if not codex_cfg.get("fallback_to_default", True):
              return None, raw_output or "", error or "codex adversarial review failed"
          print(
              f"[review_runner] codex adversarial path failed ({error}); "
              "falling back to default provider review",
              file=sys.stderr,
          )
  
      # existing _run_claude_review path unchanged …

  Also update call sites in run_review / run_private_review to pass pr_number=pr_number, base_branch=context.get("base") or context.get("base_branch") or "main", and optional focus text from architecture/errors flags.

  For footer attribution when Codex path was used, either:

  • set a thread-local / return flag, or
  • prefer a simple approach: if codex_cfg["enabled"] and analysis returned without calling Claude, pass provider_name="codex" / model from config in run_review. Cleanest: have _run_review_analysis return a 4th optional source ("codex-adversarial" | "provider") — only if existing tuple breakage is handled carefully. Prefer returning the same 3-tuple and setting review_data["_provider"] = "codex-adversarial" stripped before post, or track via a small out-param. Simplest safe approach: log only; keep existing _review_attribution unless easy to extend without API churn. Chosen: pop a private key:

  review_data["_koan_review_backend"] = "codex-adversarial"
  # strip before validate/post if needed — actually validate_review may reject unknown keys

  So do not put extra keys in the validated dict. Instead return Tuple[Optional[dict], str, Optional[str], str] backend name — update the two call sites only.

• Step 3: Verify

  Command

  KOAN_ROOT=/tmp/test-koan .venv/bin/pytest \
    koan/tests/test_codex_adversarial_review.py \
    koan/tests/test_review_runner.py \
    koan/tests/test_review_schema.py -v
  # Expected: PASS

• Step 4: Commit

  feat(review): opt-in Codex adversarial backend in review analysis path

Done when: Enabled config uses Codex path; disabled is unchanged; fallback works; reflection still optional.

---

Phase 6: Docs, lint, Capture

Files: docs/users/skills.md, docs/providers/codex.md, wiki/index.md (if description changes), frontmatter dates

• What: Operator-facing docs for enabling the feature and prerequisites.

• Why: Capture after implement; docs-first discipline.

• Gotchas: Distinguish Codex CLI provider (cli_provider: codex) from adversarial companion backend (this feature). No private identifiers.

• Step 1: Document usage

  Docs snippet

  ### Opt-in Codex adversarial review backend
  
  When `review_codex_adversarial.enabled: true` in `instance/config.yaml`,
  `/review` analysis runs OpenAI's codex-plugin-cc **adversarial-review**
  mode (`--json`) instead of the normal `review_mode` provider prompt.
  
  Prerequisites:
  - Node.js 18.18+
  - Codex CLI installed and authenticated (`codex login`)
  - `codex-plugin-cc` companion available (`companion_script` or auto-discover)
  
  Findings are mapped into Koan's normal review format (Blocking / Important /
  Suggestions, LGTM from severity). If the companion fails and
  `fallback_to_default: true` (default), Koan falls back to the standard
  provider review path.

• Step 2: Lint + full targeted tests

  Command

  make lint
  KOAN_ROOT=/tmp/test-koan .venv/bin/pytest \
    koan/tests/test_codex_adversarial_review.py \
    koan/tests/test_review_runner.py \
    koan/tests/test_review_schema.py \
    koan/tests/test_config.py -v --tb=short
  # Expected: PASS, ruff clean

• Step 3: Commit

  docs(review): document opt-in Codex adversarial-review backend

Done when: Docs explain enablement/prereqs/fallback; lint and tests green.

Corner Cases

• Config disabled → zero behavior change.
• Companion missing / node missing / Codex not logged in → fallback or hard fail per fallback_to_default.
• Companion returns parseError / empty findings with needs-attention → map safely; empty findings ⇒ lgtm true after severity derivation (provider verdict ignored).
• Fork PRs: fetch pull/<n>/head; if fetch fails, fallback/error.
• Dirty main worktree: disposable worktree avoids checkout conflicts.
• Focus flags: pass short focus text; do not require Koan review prompts for the Codex path.
• Large PRs / timeout: honor timeout_seconds; fallback if configured.
• Unknown severities: map to suggestion.
• Reflection removing all blockers: existing reconcile logic still applies when run_reflection is true.
• Private review gate: shares _run_review_analysis so it inherits the backend when enabled.
• Never post raw companion JSON or model narration to GitHub.

Testing Strategy

• Unit: mapper, severity/lgtm, payload parse, config defaults, discovery.
• Integration (mocked): _run_review_analysis with enabled/disabled/fallback; subprocess fully mocked.
• Env: always KOAN_ROOT=/tmp/test-koan (or pytest tmp).
• Boundaries mocked: subprocess.run / companion invoke — never real Codex, Telegram, or Claude.
• Regression: existing test_review_runner.py and test_review_schema.py must stay green with default config.
• Evals: offline review evals unchanged (still score REVIEW_SCHEMA). No new live eval requirement for this backend in v1.

Risks & Alternatives

Risk	Mitigation
Companion install path varies by machine	Config companion_script + CODEX_PLUGIN_ROOT + bounded auto-discover
Extra Codex quota cost	Opt-in only; document usage impact
Local git prep fails for private forks	Clear error + default fallback
Severity mapping too harsh (high→critical)	Documented mapping; easy to tune later without API break
Durable spec change	Contract-first Phase 1; declare architectural in PR
Upstream schema drift	Validate after map via validate_review; fail/fallback

Out of scope (future): multi-provider abstract ReviewResult hierarchy; upstream structured mode for plain /codex:review; making adversarial the default; replacing enrichment passes.

Verification Criteria

• Given review_codex_adversarial.enabled: false, when /review runs, then analysis still uses _run_claude_review only (existing tests pass).
• Given enabled config and a mocked companion payload with one high finding, when analysis runs, then file_comments[0].severity == "critical" and lgtm is False, and _format_review_as_markdown produces the normal bucketed PR comment.
• Given enabled config and companion failure with fallback_to_default: true, when analysis runs, then the default provider path is used.
• Given enabled config and companion failure with fallback_to_default: false, when analysis runs, then the review fails with a clear error (no unparseable placeholder from raw JSON).
• Given adversarial approve + empty findings, when mapped, then validate_review passes and lgtm is True.
• KOAN_ROOT=/tmp/test-koan .venv/bin/pytest koan/tests/test_codex_adversarial_review.py koan/tests/test_review_runner.py -v passes.
• make lint passes.

Open Questions

• Confirm severity mapping preference: high → critical (stricter, proposed) vs high → warning (looser). Affects how often formal REQUEST_CHANGES fires.
• Should auto-discover search be limited to a single known marketplace path for speed, or is a shallow **/scripts/codex-companion.mjs glob acceptable?
• When Codex path succeeds, should footer attribution show codex / configured model even if cli.review_mode is Claude? (Recommended: yes.)

---

Generated by Kōan