ctx-cc 4.0.0 → 4.1.0

package/commands/monitor.md

@@ -4,7 +4,7 @@ description: Self-healing deployments - connect to error tracking (Sentry/LogRoc
 ---
 
 <objective>
-CTX 3.5 Self-Healing Deployments - Monitor production errors and automatically create fix stories or even auto-fix with PR creation.
+CTX 4.0 Self-Healing Deployments - Monitor production errors and automatically create fix stories or even auto-fix with PR creation.
 </objective>
 
 <usage>

package/commands/voice.md

@@ -4,7 +4,7 @@ description: Voice control for CTX - speak your requirements and commands using
 ---
 
 <objective>
-CTX 3.5 Voice Control - Speak your requirements instead of typing. Natural language processing converts speech to CTX commands and story descriptions.
+CTX 4.0 Voice Control - Speak your requirements instead of typing. Natural language processing converts speech to CTX commands and story descriptions.
 </objective>
 
 <usage>

package/hooks/pre-tool-use.js

@@ -63,7 +63,8 @@ if (agentName && agentName.startsWith('ctx-')) {
     if (fs.existsSync(manifestPath)) {
       const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
       for (const [category, cfg] of Object.entries(manifest)) {
-        if (cfg.agents.includes(agentName + '.md') && cfg.denied.includes(toolName)) {
+        if (category.startsWith('_')) continue; // skip metadata keys like _version
+        if (cfg?.agents?.includes(agentName + '.md') && cfg.denied.includes(toolName)) {
           process.stderr.write(`CTX: Tool "${toolName}" blocked for ${category} agent "${agentName}".\n`);
           fs.appendFileSync(
             path.join(ctxDir, 'violations.log'),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ctx-cc",
-  "version": "4.0.0",
-  "description": "CTX 4.0 — Intelligent workflow orchestration for Claude Code. 21 subagents, 3 skills, deterministic hooks. Phase-based lifecycle with autonomous execution.",
+  "version": "4.1.0",
+  "description": "CTX 4.0 — Intelligent workflow orchestration for Claude Code. 26 subagents, 7 skills, deterministic hooks. Phase-based lifecycle with autonomous execution.",
   "keywords": [
     "claude",
     "claude-code",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ctx",
   "version": "4.0.0",
-  "description": "CTX — Intelligent workflow orchestration for Claude Code. 21 specialized agents, phase-based lifecycle, two-stage review gate, autonomous execution.",
+  "description": "CTX — Intelligent workflow orchestration for Claude Code. Specialized agents, phase-based lifecycle, three-stage review gate with OpenAI Codex cross-model review, autonomous execution.",
   "author": "jufjuf",
   "license": "MIT",
   "homepage": "https://github.com/jufjuf/CTX",
@@ -38,6 +38,7 @@
   },
   "settings": {
     "reviewGate": true,
+    "codexReview": true,
     "tddMode": "off",
     "maxReviewCycles": 3,
     "maxAutoIterations": 5

package/skills/ctx-review-gate/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: ctx-review-gate
 description: |
-  WHEN: Code has been implemented and needs quality verification before marking a story complete. Runs two-stage review: spec compliance then code quality.
+  WHEN: Code has been implemented and needs quality verification before marking a story complete. Runs three-stage review: spec compliance, code quality, and optional cross-model adversarial review via OpenAI Codex.
   WHEN NOT: During planning, research, or when review gate is disabled in config.
 ---
 
-# CTX Two-Stage Review Gate
+# CTX Three-Stage Review Gate
 
 Automated quality gate that runs after execution and before verification.
 
-## Two Stages
+## Three Stages
 
 ### Stage 1: Spec Compliance (ctx-reviewer)
 Checks whether the code satisfies the story's acceptance criteria.
@@ -23,18 +23,39 @@ Agent({
 })
 ```
 
-### Stage 2: Code Quality (ctx-auditor)
-Checks security, performance, and code quality. **Only runs if Stage 1 passes.**
+### Stage 2: Code Quality (ctx-reviewer)
+Reuses ctx-reviewer with a quality-focused prompt: security, performance, error handling, style. **Only runs if Stage 1 passes.**
+
+(Note: earlier versions of this skill called `ctx-auditor` here. That was a miscast — `ctx-auditor` is an audit-trail/compliance agent, not a code-quality reviewer. `ctx-reviewer` already covers type checks, imports, security scans, and best-practice enforcement, so it handles both stages with different framings.)
 
 Spawn:
 ```
 Agent({
-  subagent_type: "ctx-auditor",
+  subagent_type: "ctx-reviewer",
   prompt: "Review recent changes for CODE QUALITY. Check: security vulnerabilities, performance, error handling, style. Output VERDICT: PASS or FAIL with ISSUES list.",
-  description: "Code quality audit"
+  description: "Code quality review"
 })
 ```
 
+### Stage 3: Cross-Model Review (ctx-codex-reviewer) — optional
+Sends the diff to OpenAI Codex via MCP for a second-pair-of-eyes review with different model priors. **Only runs if Stage 2 passes AND `config.codexReview !== false`.**
+
+Short-circuits on docs-only, test-only, or trivial (<20 LOC) diffs. Fails soft — if the Codex MCP is unavailable, rate-limited, or unauthenticated, returns `SKIP` rather than `FAIL` so infrastructure problems never block the gate.
+
+Spawn:
+```
+Agent({
+  subagent_type: "ctx-codex-reviewer",
+  prompt: "Cross-model review story <ID>. Dispatch the current diff to Codex via mcp__codex__codex with sandbox=read-only. Acceptance criteria: <list>. Output VERDICT: PASS, FAIL, or SKIP.",
+  description: "Codex adversarial review"
+})
+```
+
+Prerequisites (user-side, not automated by CTX):
+- Codex CLI installed (`npm i -g @openai/codex`)
+- Signed in via ChatGPT subscription (`codex login` — no `--api-key` flag)
+- MCP registered (`claude mcp add codex -- codex mcp-server`)
+
 ## Flow
 
 ```
@@ -51,6 +72,12 @@ Stage 2: ctx-auditor (code quality)
     ├── FAIL → Feed issues back to executor, increment cycle
     │
     ▼ PASS
+Stage 3: ctx-codex-reviewer (cross-model, if enabled)
+    │
+    ├── FAIL → Feed issues back to executor, increment cycle
+    ├── SKIP → Treat as pass (infra problem, not code problem)
+    │
+    ▼ PASS
 Mark story for verification
 ```
 
@@ -85,27 +112,36 @@ Update `.ctx/STATE.json`:
   "reviewGate": {
     "cycle": 2,
     "history": [
-      { "cycle": 1, "timestamp": "ISO", "stage1": { "passed": true }, "stage2": { "passed": false, "issues": "..." }, "result": "fail" },
-      { "cycle": 2, "timestamp": "ISO", "stage1": { "passed": true }, "stage2": { "passed": true }, "result": "pass" }
+      { "cycle": 1, "timestamp": "ISO", "stage1": { "passed": true }, "stage2": { "passed": false, "issues": "..." }, "stage3": null, "result": "fail" },
+      { "cycle": 2, "timestamp": "ISO", "stage1": { "passed": true }, "stage2": { "passed": true }, "stage3": { "passed": true, "threadId": "thr_...", "skipped": false }, "result": "pass" }
     ]
   }
 }
 ```
 
+`stage3` is `null` when Stage 2 fails (not reached) or when `codexReview` is disabled. When Stage 3 runs, record `threadId` so follow-ups reuse the same Codex session.
+
 ## Save Review Artifacts
 
 Write review results to `.ctx/reviews/<story-id>-<timestamp>.json`.
 
 ## Configuration
 
-Review gate can be disabled:
+Review gate can be disabled entirely:
 - Check `.ctx/config.json` for `"reviewGate": false`
 - If disabled, skip directly to verification
 
+Stage 3 (Codex cross-review) can be disabled independently:
+- Check `.ctx/config.json` for `"codexReview": false`
+- Useful when offline, when the ChatGPT rate-limit budget is depleted, or when the change is trivial
+- Stages 1 and 2 continue to run normally
+
 ## Rules
 
-- ALWAYS run Stage 1 before Stage 2
-- NEVER run Stage 2 if Stage 1 fails (fail-fast)
+- ALWAYS run Stage 1 before Stage 2, Stage 2 before Stage 3 (fail-fast ordering)
+- NEVER run Stage 2 if Stage 1 fails
+- NEVER run Stage 3 if Stage 2 fails, or if `codexReview === false`
+- Stage 3 SKIP (infrastructure failure) is NOT a gate failure — treat as pass
 - ALWAYS feed review issues back to executor as context on retry
 - Max 3 cycles — then escalate to human
-- Record every cycle in state
+- Record every cycle in state, including `stage3: null` when not reached

package/src/capabilities.js

@@ -1,9 +1,26 @@
 import fs from 'fs';
 import path from 'path';
 
+/**
+ * Schema version for the on-disk capability manifest.
+ * Bump when adding categories, renaming fields, or changing policy semantics
+ * so stale project manifests can be detected and regenerated.
+ */
+export const MANIFEST_VERSION = 1;
+
 /**
  * Default capability manifests per agent category.
- * Defines which tools each agent type is allowed to use.
+ * Defines which tools each ctx-* agent category is allowed to use.
+ *
+ * The runtime enforcement point is `hooks/pre-tool-use.js`, which reads
+ * `.ctx/capability-manifest.json` (written at project init from this table)
+ * and blocks tool calls whose name appears in the agent's `denied` list.
+ *
+ * `allowed` is the declared whitelist and is used for documentation and tests;
+ * the hook itself is denylist-driven so unknown tools default to permissive.
+ *
+ * Iterators over a loaded manifest MUST skip keys starting with `_`
+ * (reserved for metadata like `_version`).
  */
 const DEFAULT_CAPABILITIES = {
   // Planning agents — read-only + write plans
@@ -22,14 +39,22 @@ const DEFAULT_CAPABILITIES = {
     reason: 'Execution agents should not spawn other agents.',
   },
 
-  // Review agents — read + run tests, no modifications
+  // Review agents — read + run tests + Codex cross-review, no modifications
   review: {
-    agents: ['ctx-reviewer.md', 'ctx-auditor.md', 'ctx-verifier.md'],
-    allowed: ['Read', 'Glob', 'Grep', 'Bash'],
+    agents: ['ctx-reviewer.md', 'ctx-verifier.md', 'ctx-codex-reviewer.md', 'ctx-ml-reviewer.md'],
+    allowed: ['Read', 'Glob', 'Grep', 'Bash', 'mcp__codex__codex'],
     denied: ['Write', 'Edit', 'NotebookEdit'],
     reason: 'Review agents should not modify code.',
   },
 
+  // Audit agents — write audit trails, but never modify source
+  audit: {
+    agents: ['ctx-auditor.md'],
+    allowed: ['Read', 'Write', 'Bash', 'Glob', 'Grep'],
+    denied: ['Edit', 'Agent', 'NotebookEdit'],
+    reason: 'Audit agents record trails but should not modify source or spawn agents.',
+  },
+
   // Mapper agents — read-only analysis
   mapping: {
     agents: ['ctx-mapper.md', 'ctx-arch-mapper.md', 'ctx-tech-mapper.md', 'ctx-quality-mapper.md', 'ctx-concerns-mapper.md'],
@@ -69,25 +94,23 @@ const DEFAULT_CAPABILITIES = {
     denied: ['Edit'],
     reason: 'QA agents test but should not fix code.',
   },
-};
 
-/**
- * Load capability manifest from file, or return defaults.
- */
-export function loadCapabilityManifest(ctxDir) {
-  const manifestPath = path.join(ctxDir, 'capability-manifest.json');
-  try {
-    return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-  } catch {
-    return DEFAULT_CAPABILITIES;
-  }
-}
+  // ML agents — implement and analyze ML pipelines
+  ml: {
+    agents: ['ctx-ml-scientist.md', 'ctx-ml-engineer.md', 'ctx-ml-analyst.md'],
+    allowed: ['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep'],
+    denied: ['Agent', 'NotebookEdit'],
+    reason: 'ML agents implement and analyze pipelines but should not orchestrate.',
+  },
+};
 
 /**
  * Find the category for a given agent file.
+ * Skips metadata keys (prefix `_`) so a versioned on-disk manifest still works.
  */
 export function findAgentCategory(agentFile, manifest = DEFAULT_CAPABILITIES) {
   for (const [category, config] of Object.entries(manifest)) {
+    if (category.startsWith('_')) continue;
     if (config.agents.includes(agentFile)) {
       return { category, ...config };
     }
@@ -97,12 +120,14 @@ export function findAgentCategory(agentFile, manifest = DEFAULT_CAPABILITIES) {
 
 /**
  * Check if a tool is allowed for an agent.
+ * Denylist-driven (matches the runtime hook in hooks/pre-tool-use.js).
+ * Unknown agents are permissive by default.
+ *
  * Returns { allowed: boolean, reason: string|null }.
  */
 export function checkToolAllowed(agentFile, toolName, manifest = DEFAULT_CAPABILITIES) {
   const category = findAgentCategory(agentFile, manifest);
   if (!category) {
-    // Unknown agent — allow everything (permissive for custom agents)
     return { allowed: true, reason: null };
   }
 
@@ -117,37 +142,66 @@ export function checkToolAllowed(agentFile, toolName, manifest = DEFAULT_CAPABIL
 }
 
 /**
- * Generate a PreToolUse hook command that enforces capability restrictions.
- * Returns the hook command string.
+ * Save the capability manifest to `<ctxDir>/capability-manifest.json`.
+ * Called from the install flow to seed the template and from the project
+ * init command to materialize the manifest that the PreToolUse hook reads.
  */
-export function generateCapabilityHookCommand(ctxDir) {
-  return `node -e "
-    const fs=require('fs'),p=require('path');
-    const tool=process.env.TOOL_NAME||'';
-    const agent=process.env.CURRENT_AGENT||'';
-    if(!agent||!tool)process.exit(0);
-    const mPath=p.join('${ctxDir}','capability-manifest.json');
-    let manifest;
-    try{manifest=JSON.parse(fs.readFileSync(mPath,'utf-8'));}catch{process.exit(0);}
-    for(const[cat,cfg]of Object.entries(manifest)){
-      if(cfg.agents.includes(agent)&&cfg.denied.includes(tool)){
-        console.error('CTX: Tool '+tool+' blocked for '+cat+' agent '+agent);
-        const logDir=p.join('${ctxDir}','violations.log');
-        fs.appendFileSync(logDir,new Date().toISOString()+' | '+agent+' | '+tool+' | BLOCKED\\n');
-        process.exit(2);
-      }
-    }
-  "`.replace(/\n\s*/g, ' ').trim();
+export function saveCapabilityManifest(ctxDir) {
+  const manifestPath = path.join(ctxDir, 'capability-manifest.json');
+  if (!fs.existsSync(ctxDir)) fs.mkdirSync(ctxDir, { recursive: true });
+  const payload = { _version: MANIFEST_VERSION, ...DEFAULT_CAPABILITIES };
+  fs.writeFileSync(manifestPath, JSON.stringify(payload, null, 2) + '\n');
+  return manifestPath;
 }
 
 /**
- * Save default capability manifest to .ctx/ for customization.
+ * Read the `_version` field from an on-disk manifest.
+ * Returns 0 for pre-versioned manifests, null if file missing/invalid.
+ * Callers compare against MANIFEST_VERSION to decide whether to regenerate.
  */
-export function saveCapabilityManifest(ctxDir) {
+export function readManifestVersion(ctxDir) {
   const manifestPath = path.join(ctxDir, 'capability-manifest.json');
-  if (!fs.existsSync(ctxDir)) fs.mkdirSync(ctxDir, { recursive: true });
-  fs.writeFileSync(manifestPath, JSON.stringify(DEFAULT_CAPABILITIES, null, 2) + '\n');
-  return manifestPath;
+  try {
+    const data = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    return typeof data._version === 'number' ? data._version : 0;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Migrate an existing project's capability manifest to the current version.
+ * - Missing:  writes a fresh manifest, returns { action: 'created' }.
+ * - Current:  no-op, returns { action: 'current' }.
+ * - Stale:    backs up old manifest as `capability-manifest.v<N>.backup.json`
+ *             and regenerates, returns { action: 'migrated', backup }.
+ *
+ * Used by the `ctx-cc update-manifest` CLI subcommand so projects that
+ * predate MANIFEST_VERSION can pick up policy changes without re-initting.
+ */
+export function updateProjectManifest(ctxDir) {
+  const manifestPath = path.join(ctxDir, 'capability-manifest.json');
+  const current = readManifestVersion(ctxDir);
+
+  if (current === null) {
+    saveCapabilityManifest(ctxDir);
+    return { action: 'created', from: null, to: MANIFEST_VERSION, path: manifestPath };
+  }
+
+  if (current === MANIFEST_VERSION) {
+    return { action: 'current', from: current, to: current, path: manifestPath };
+  }
+
+  const backupPath = path.join(ctxDir, `capability-manifest.v${current}.backup.json`);
+  fs.copyFileSync(manifestPath, backupPath);
+  saveCapabilityManifest(ctxDir);
+  return {
+    action: 'migrated',
+    from: current,
+    to: MANIFEST_VERSION,
+    path: manifestPath,
+    backup: backupPath,
+  };
 }
 
 /**
@@ -156,6 +210,7 @@ export function saveCapabilityManifest(ctxDir) {
 export function formatCapabilities(manifest = DEFAULT_CAPABILITIES) {
   const lines = [];
   for (const [category, config] of Object.entries(manifest)) {
+    if (category.startsWith('_')) continue;
     lines.push(`  ${category}:`);
     lines.push(`    Agents:  ${config.agents.map(a => a.replace('ctx-', '').replace('.md', '')).join(', ')}`);
     lines.push(`    Allowed: ${config.allowed.join(', ')}`);

package/src/install.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { saveCapabilityManifest } from './capabilities.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -28,7 +29,7 @@ function printBanner() {
 `));
   console.log(`  ${bold('CTX 4.0')} ${dim(`v${VERSION}`)}`);
   console.log('  Intelligent workflow orchestration for Claude Code.');
-  console.log('  21 agents. Skills. Hooks. Phase-based lifecycle.\n');
+  console.log('  26 agents. 7 skills. Hooks. Phase-based lifecycle.\n');
 }
 
 function copyDir(src, dest) {
@@ -170,6 +171,12 @@ export async function install(options) {
     console.log(green(`  ✓`) + ` Installed templates (${count} files)`);
   }
 
+  // Generate capability-manifest.json template from DEFAULT_CAPABILITIES.
+  // /ctx:init copies this into each project's .ctx/ so the PreToolUse hook
+  // (hooks/pre-tool-use.js) has a manifest to enforce against.
+  saveCapabilityManifest(destTemplates);
+  console.log(green(`  ✓`) + ` Generated capability-manifest.json template`);
+
   // Write VERSION file
   fs.writeFileSync(path.join(ctxDir, 'VERSION'), VERSION);
   console.log(green(`  ✓`) + ` Wrote VERSION (${VERSION})`);
@@ -178,8 +185,8 @@ export async function install(options) {
   console.log(`\n  ${green('Done!')} Launch Claude Code and run ${cyan('/ctx:help')}.`);
   console.log(`
   ${bold('What was installed:')}
-    ${dim('Agents:')}   ~/.claude/agents/ctx-*.md     (21 subagents)
-    ${dim('Skills:')}   ~/.claude/skills/ctx-*/        (3 skills)
+    ${dim('Agents:')}   ~/.claude/agents/ctx-*.md     (26 subagents)
+    ${dim('Skills:')}   ~/.claude/skills/ctx-*/        (7 skills)
     ${dim('Commands:')} ~/.claude/commands/ctx/         (slash commands)
     ${dim('Hooks:')}    ~/.claude/hooks/ctx-*.js        (3 hook scripts)
     ${dim('Config:')}   ~/.claude/settings.json         (hooks registered)

package/src/review-gate.js

@@ -7,19 +7,21 @@ import { runAgent } from './runner.js';
 const MAX_REVIEW_CYCLES = 3;
 
 /**
- * Run the two-stage review gate.
+ * Run the three-stage review gate.
  *
  * Stage 1: ctx-reviewer checks spec compliance (acceptance criteria)
- * Stage 2: ctx-auditor checks code quality (security, performance, style)
+ * Stage 2: ctx-reviewer (quality framing) checks code quality (security, performance, style)
+ * Stage 3: ctx-codex-reviewer performs cross-model review via OpenAI Codex MCP
+ *          (only runs if Stages 1 and 2 pass, and `config.codexReview !== false`).
  *
- * If either fails, returns feedback for re-execution.
+ * If any stage fails, returns feedback for re-execution.
  * Max cycles before requiring human intervention.
  *
  * Options:
  *   ctxDir, projectDir, agentsDir, streaming, timeout, config
  *
  * Returns:
- *   { passed: boolean, stage1: {...}, stage2: {...}, cycle: number, feedback: string|null }
+ *   { passed, stage1, stage2, stage3, cycle, feedback, escalated }
  */
 export async function runReviewGate({ ctxDir, projectDir, agentsDir, streaming = true, timeout = 300000, config = {} }) {
   const state = readState(ctxDir);
@@ -49,19 +51,49 @@ export async function runReviewGate({ ctxDir, projectDir, agentsDir, streaming =
     ctxDir, projectDir, agentsDir, streaming, timeout,
   });
 
-  // Stage 2: Code quality (auditor) — only if Stage 1 passes
+  // Stage 2: Code quality — only if Stage 1 passes. Reuses ctx-reviewer with quality framing;
+  // ctx-auditor is an audit-trail agent, not a code reviewer, so using it here was a miscast.
   let stage2 = null;
   if (stage1.passed) {
     stage2 = await runReviewStage({
       stageName: 'code-quality',
-      agentFile: 'ctx-auditor.md',
-      agentCommand: 'audit',
+      agentFile: 'ctx-reviewer.md',
+      agentCommand: 'review',
       prompt: buildReviewPrompt(state, 'quality'),
       ctxDir, projectDir, agentsDir, streaming, timeout,
     });
   }
 
-  const passed = stage1.passed && (stage2 ? stage2.passed : false);
+  // Stage 3: Cross-model review via Codex — only if Stages 1 and 2 pass and not disabled.
+  // The agent may return VERDICT: SKIP (trivial changes, MCP unavailable, rate-limited);
+  // SKIP is treated as pass-through so infrastructure issues never block the gate.
+  // Across retry cycles we pipe the prior Codex threadId forward so the agent can
+  // reuse the cheaper codex-reply path instead of starting a fresh session.
+  let stage3 = null;
+  if (stage1.passed && stage2 && stage2.passed && config.codexReview !== false) {
+    const priorThreadId = priorCodexThreadId(reviewState);
+    stage3 = await runReviewStage({
+      stageName: 'codex-review',
+      agentFile: 'ctx-codex-reviewer.md',
+      agentCommand: 'review',
+      prompt: buildReviewPrompt(state, 'codex', { priorThreadId }),
+      ctxDir, projectDir, agentsDir, streaming, timeout,
+    });
+    const { skipped, threadId } = parseStage3Markers(stage3.output);
+    stage3.threadId = threadId;
+    if (skipped) {
+      stage3.passed = true;
+      stage3.skipped = true;
+      stage3.issues = null;
+    }
+  }
+
+  // stage2 defaults to false when null (stage1 failed → never ran → not passed).
+  // stage3 defaults to true when null (disabled or earlier stage failed → absence is not a fail).
+  const passed =
+    stage1.passed &&
+    (stage2 ? stage2.passed : false) &&
+    (stage3 ? stage3.passed : true);
 
   // Build feedback for re-execution if failed
   let feedback = null;
@@ -69,15 +101,26 @@ export async function runReviewGate({ ctxDir, projectDir, agentsDir, streaming =
     const issues = [];
     if (!stage1.passed) issues.push(`Spec compliance: ${stage1.issues}`);
     if (stage2 && !stage2.passed) issues.push(`Code quality: ${stage2.issues}`);
+    if (stage3 && !stage3.passed) issues.push(`Codex review: ${stage3.issues}`);
     feedback = issues.join('\n');
   }
 
+  const stage3History = stage3
+    ? {
+        passed: stage3.passed,
+        issues: stage3.issues,
+        skipped: stage3.skipped || false,
+        threadId: stage3.threadId || null,
+      }
+    : null;
+
   // Record in state
   reviewState.history.push({
     cycle: reviewState.cycle,
     timestamp: new Date().toISOString(),
     stage1: { passed: stage1.passed, issues: stage1.issues },
     stage2: stage2 ? { passed: stage2.passed, issues: stage2.issues } : null,
+    stage3: stage3History,
     result: passed ? 'pass' : 'fail',
   });
 
@@ -91,6 +134,7 @@ export async function runReviewGate({ ctxDir, projectDir, agentsDir, streaming =
     passed,
     stage1: { passed: stage1.passed, issues: stage1.issues },
     stage2: stage2 ? { passed: stage2.passed, issues: stage2.issues } : null,
+    stage3: stage3History,
     cycle: reviewState.cycle,
     feedback,
     escalated: false,
@@ -104,6 +148,22 @@ export function isReviewGateEnabled(config) {
   return config.reviewGate !== false;
 }
 
+/**
+ * Parse Stage 3 output markers.
+ * - `skipped` is true when the agent emitted `VERDICT: SKIP` (trivial change,
+ *   MCP unavailable, auth expired, rate-limited).
+ * - `threadId` is the value after `THREAD: <id>`, used to resume cheaper
+ *   `codex-reply` sessions across review cycles.
+ *
+ * Exported for unit testing; consumed by runReviewGate internally.
+ */
+export function parseStage3Markers(output) {
+  const text = output || '';
+  const skipped = /verdict:\s*skip/i.test(text);
+  const threadMatch = /THREAD:\s*([^\s]+)/i.exec(text);
+  return { skipped, threadId: threadMatch ? threadMatch[1] : null };
+}
+
 /**
  * Get review history from state.
  */
@@ -130,6 +190,14 @@ export function formatReviewResult(result) {
     const s2Icon = result.stage2.passed ? '✓' : '✗';
     lines.push(`    ${s2Icon} Stage 2 (code quality): ${result.stage2.passed ? 'pass' : result.stage2.issues || 'fail'}`);
   }
+  if (result.stage3) {
+    if (result.stage3.skipped) {
+      lines.push(`    ○ Stage 3 (codex review): skipped`);
+    } else {
+      const s3Icon = result.stage3.passed ? '✓' : '✗';
+      lines.push(`    ${s3Icon} Stage 3 (codex review): ${result.stage3.passed ? 'pass' : result.stage3.issues || 'fail'}`);
+    }
+  }
 
   if (result.escalated) {
     lines.push('');
@@ -182,7 +250,17 @@ async function runReviewStage({ stageName, agentFile, agentCommand, prompt, ctxD
   }
 }
 
-function buildReviewPrompt(state, type) {
+function priorCodexThreadId(reviewState) {
+  const hist = reviewState?.history;
+  if (!Array.isArray(hist)) return null;
+  for (let i = hist.length - 1; i >= 0; i--) {
+    const tid = hist[i]?.stage3?.threadId;
+    if (tid) return tid;
+  }
+  return null;
+}
+
+function buildReviewPrompt(state, type, opts = {}) {
   if (type === 'spec') {
     return [
       'Review the recent code changes for SPEC COMPLIANCE.',
@@ -197,6 +275,22 @@ function buildReviewPrompt(state, type) {
     ].join('\n');
   }
 
+  if (type === 'codex') {
+    const lines = [
+      'Stage 3 — cross-model review via OpenAI Codex.',
+      'Stages 1 (spec) and 2 (quality) already passed under Claude review.',
+      `Active story: ${state.activeStory || 'unknown'}`,
+    ];
+    if (opts.priorThreadId) {
+      lines.push(`Prior Codex thread: ${opts.priorThreadId} — reuse via mcp__codex__codex-reply if context is still relevant.`);
+    }
+    lines.push(
+      '',
+      'Run your playbook and output VERDICT: PASS | FAIL | SKIP on the final line. Append `THREAD: <id>` if a new thread was opened.',
+    );
+    return lines.join('\n');
+  }
+
   return [
     'Review the recent code changes for CODE QUALITY.',
     'Check: security vulnerabilities, performance issues, code style, error handling.',

package/templates/config.json

@@ -91,6 +91,9 @@
 
   "activeProfile": "balanced",
 
+  "reviewGate": true,
+  "codexReview": true,
+
   "git": {
     "autoCommit": true,
     "commitPerTask": true,