ctx-cc 4.1.0 → 4.1.2

package/README.md

@@ -13,7 +13,7 @@
 
 [![npm version](https://img.shields.io/npm/v/ctx-cc.svg?style=flat-square)](https://www.npmjs.com/package/ctx-cc)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![Tests](https://img.shields.io/badge/tests-264%20passing-brightgreen.svg?style=flat-square)](#testing)
+[![Tests](https://img.shields.io/badge/tests-149%20passing-brightgreen.svg?style=flat-square)](#testing)
 [![Zero deps](https://img.shields.io/badge/dependencies-0-brightgreen.svg?style=flat-square)](#)
 
 ```bash
@@ -493,7 +493,7 @@ Options:
 ```bash
 git clone https://github.com/jufjuf/CTX.git
 cd CTX
-npm test    # 264 tests, node:test runner
+npm test    # 149 tests, node:test runner
 ```
 
 **Project structure:**
@@ -504,8 +504,8 @@ ctx-cc/
 ├── skills/          7 skill directories (each contains SKILL.md)
 ├── commands/        26 slash command definitions (.md)
 ├── hooks/           3 enforcement hook scripts (.js)
-├── src/             17 source modules (.js)
-├── test/            19 test files (.test.js)
+├── src/              5 source modules (.js)
+├── test/             8 test files (.test.js)
 ├── templates/       config.json, PRD.json, state templates
 ├── bin/ctx.js       CLI entry point (installer only)
 ├── plugin.json      Marketplace manifest
@@ -518,7 +518,7 @@ ctx-cc/
 
 ```bash
 npm test
-# 264 tests, 0 failures, ~2s
+# 149 tests, 0 failures, ~1s
 ```
 
 **Coverage:**

package/commands/cross-review.md

@@ -0,0 +1,142 @@
+---
+name: ctx:cross-review
+description: On-demand cross-model code review via OpenAI Codex. Works in any project.
+argument-hint: [commit-range] [--focus=area]
+---
+
+<objective>
+Dispatch the current diff to OpenAI Codex (GPT-5.x) via MCP for adversarial cross-model review. Catches bugs Claude's same-model review tends to miss — different training data, different blind spots.
+
+Wraps the `ctx-codex-reviewer` agent with the same skip logic and threadId carryforward used by Stage 3 of the CTX review gate, but invocable on demand from any Claude Code project (not just CTX-managed ones).
+</objective>
+
+<usage>
+```
+/ctx:cross-review                          # review staged + unstaged diff
+/ctx:cross-review HEAD~3..HEAD             # review last 3 commits
+/ctx:cross-review --focus=security         # review with focus area hint
+/ctx:cross-review HEAD~1 --focus=concurrency
+```
+
+Argument parsing (lenient — any order):
+- A git revision range (e.g. `HEAD~3..HEAD`, `main..HEAD`, `<sha1>..<sha2>`) selects what to review. If absent, defaults to `git diff` (working tree).
+- `--focus=<area>` hints Codex to weight specific concerns (security, perf, concurrency, error-handling, contract).
+- Bare positional after a range is treated as commentary appended to the prompt.
+</usage>
+
+<prerequisites>
+This command is a no-op without the Codex MCP. If `mcp__codex__codex` is not registered, the agent will return `VERDICT: SKIP` and tell the user how to set it up:
+
+```bash
+# One-time setup:
+codex login                                       # ChatGPT Plus auth
+claude mcp add codex -- codex mcp-server          # register MCP
+```
+
+Do NOT block the command on missing MCP — surface the SKIP reason and suggest the install commands.
+</prerequisites>
+
+<workflow>
+
+## Step 1: Resolve scope
+
+Parse `$ARGUMENTS`:
+- Extract any token matching `<rev>..<rev>` or `<sha>~N` as the range.
+- Extract `--focus=<area>` as a hint string.
+- Treat remaining text as freeform commentary.
+
+If no range, default: `git diff` (staged + unstaged).
+If range given, the agent will use `git diff <range>`.
+
+## Step 2: Detect CTX context (optional)
+
+```bash
+[ -f .ctx/STATE.json ] && jq -r '.activeStory // "none"' .ctx/STATE.json
+```
+
+If a CTX story is active, include it in the prompt so the agent can pull acceptance criteria from `.ctx/PRD.json`. If not, skip — review still works against raw diff.
+
+## Step 3: Spawn the cross-reviewer agent
+
+```
+Task:
+  subagent_type: "ctx-codex-reviewer"
+  prompt: |
+    On-demand cross-model review (not part of an automated review gate).
+
+    Scope:    {{range or "working tree (staged + unstaged)"}}
+    Focus:    {{--focus value or "general — bugs, security, contracts"}}
+    Story:    {{.activeStory or "n/a — not a CTX project"}}
+    Notes:    {{freeform commentary or empty}}
+
+    Run your standard playbook:
+      1. Gather the diff for the scope above.
+      2. Apply skip short-circuits (docs-only, test-only, <20 LOC).
+      3. Dispatch via mcp__codex__codex.
+      4. Parse verdict.
+
+    Output format (final line MUST be one of):
+      VERDICT: PASS
+      VERDICT: FAIL
+      VERDICT: SKIP
+
+    Append `THREAD: <id>` if a Codex thread was opened.
+  description: "Cross-model review"
+```
+
+## Step 4: Render the verdict to the user
+
+After the agent returns:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► CROSS-REVIEW
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+For each verdict:
+
+- `PASS`: green checkmark, "Codex found no issues in {{scope}}."
+- `FAIL`: red X, list the issues by `file:line — description`. Group by severity if Codex provided it.
+- `SKIP`: muted ○, surface the skip reason verbatim. If reason is "MCP unavailable" or "auth expired", include the install commands from `<prerequisites>`.
+
+If the agent emitted `THREAD: <id>`, mention it for follow-ups:
+```
+Follow up with: ask Codex to expand on issue 2 in thread <id>
+```
+
+## Step 5: Optionally persist (CTX projects only)
+
+If `.ctx/` exists, write the result alongside Stage 3 reviews:
+
+```
+.ctx/reviews/cross-review-{{ISO-timestamp}}.json
+{
+  "command": "/ctx:cross-review",
+  "scope": "{{range or working-tree}}",
+  "focus": "{{focus or null}}",
+  "verdict": "PASS|FAIL|SKIP",
+  "issues": [...],
+  "threadId": "..."
+}
+```
+
+If not in a CTX project, just print and exit — no file output.
+
+</workflow>
+
+<guardrails>
+- Never fail on infra problems. Codex MCP missing, auth expired, or rate-limited → SKIP with actionable message, not error.
+- Never call Codex on docs-only, test-only, or sub-20-LOC diffs (the agent enforces this; do not override).
+- Rate-limit aware: the user's ChatGPT Plus quota is shared with everything else they use Codex for. One invocation = one message against the 5h window. Do not retry on transient failures.
+- Read-only sandbox: the agent uses `sandbox: read-only` when calling Codex. Do not pass arguments that would change this.
+</guardrails>
+
+<comparison>
+| When to use what | Tool |
+|---|---|
+| On-demand cross-review of current changes (any project) | `/ctx:cross-review` (this command) |
+| Story-scoped review inside CTX gate (auto, every story) | Stage 3 of `runReviewGate` (no command — fires on its own) |
+| Direct same-model review without Codex | `/ctx:verify` or `/ctx:quick` |
+| Just want to send a single prompt to Codex (not review) | `/codex` (if installed) |
+</comparison>

package/commands/help.md

@@ -115,6 +115,7 @@ Or use commands directly:
 | `/ctx plan [goal]` | Force research + planning |
 | `/ctx verify` | Force three-level verification |
 | `/ctx quick "task"` | Quick task bypass |
+| `/ctx cross-review [range] [--focus=area]` | On-demand Codex cross-model review (any project) |
 
 ### Debug
 | Command | Purpose |

package/package.json

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

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ctx",
-  "version": "4.0.0",
+  "version": "4.1.2",
   "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",

package/src/auto.js

@@ -1,287 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import { readState, writeState, initState, transitionPhase } from './state.js';
-import { executePipeline } from './pipeline.js';
-import { runReviewGate, isReviewGateEnabled } from './review-gate.js';
-import { selectStory, listPendingStories } from './lifecycle.js';
-import { commitTask } from './commits.js';
-
-const STOP_FILE = 'STOP';
-const AUTO_LOG = 'AUTO-LOG.md';
-
-const DEFAULTS = {
-  maxIterationsPerStory: 5,
-  maxTotalTimeMs: 2 * 60 * 60 * 1000, // 2 hours
-  pipeline: ['plan', 'execute'],
-};
-
-/**
- * Run autonomous execution loop across all P1 stories (or a single story).
- *
- * Options:
- *   ctxDir, projectDir, agentsDir, config
- *   storyId      — single story to process (null = all P1)
- *   retryFailed  — only retry previously failed stories
- *   streaming    — stream agent output
- *   timeout      — per-agent timeout in ms
- *   onEvent      — callback({ type, story, message, ... })
- */
-export async function runAutoLoop({ ctxDir, projectDir, agentsDir, config = {}, storyId = null, retryFailed = false, streaming = true, timeout = 300000, onEvent = null }) {
-  const maxIterations = config.maxIterationsPerStory || DEFAULTS.maxIterationsPerStory;
-  const maxTime = config.maxTotalTimeMs || DEFAULTS.maxTotalTimeMs;
-  const startTime = Date.now();
-
-  // Initialize auto log
-  const logPath = path.join(ctxDir, AUTO_LOG);
-  appendLog(logPath, `# CTX Auto Loop — ${new Date().toISOString()}\n`);
-
-  // Determine stories to process
-  const stories = resolveStories(ctxDir, storyId, retryFailed);
-  if (stories.length === 0) {
-    emit(onEvent, { type: 'no_stories', message: 'No stories to process.' });
-    return { completed: [], failed: [], skipped: [], totalTime: 0 };
-  }
-
-  emit(onEvent, { type: 'start', storyCount: stories.length, maxIterations, maxTime });
-  appendLog(logPath, `\nProcessing ${stories.length} stories. Max ${maxIterations} iterations each.\n`);
-
-  const completed = [];
-  const failed = [];
-  const skipped = [];
-
-  for (const story of stories) {
-    // Check stop file
-    if (shouldStop(ctxDir)) {
-      emit(onEvent, { type: 'stopped', message: 'STOP file detected. Halting after current story.' });
-      appendLog(logPath, `\n⏹ Stopped by STOP file at ${new Date().toISOString()}\n`);
-      skipped.push(...stories.slice(stories.indexOf(story)));
-      break;
-    }
-
-    // Check time limit
-    if (Date.now() - startTime > maxTime) {
-      emit(onEvent, { type: 'timeout', message: `Time limit (${maxTime / 1000 / 60}min) exceeded.` });
-      appendLog(logPath, `\n⏱ Time limit exceeded at ${new Date().toISOString()}\n`);
-      skipped.push(...stories.slice(stories.indexOf(story)));
-      break;
-    }
-
-    emit(onEvent, { type: 'story_start', story: story.id, title: story.title });
-    appendLog(logPath, `\n## ${story.id} — ${story.title}\nStarted: ${new Date().toISOString()}\n`);
-
-    const result = await processStory({
-      story, ctxDir, projectDir, agentsDir, config,
-      maxIterations, streaming, timeout, onEvent, logPath,
-    });
-
-    if (result.success) {
-      completed.push(story.id);
-      appendLog(logPath, `Result: ✓ COMPLETED (${result.iterations} iterations)\n`);
-    } else {
-      failed.push({ id: story.id, reason: result.reason });
-      appendLog(logPath, `Result: ✗ FAILED — ${result.reason}\n`);
-    }
-  }
-
-  // Write summary
-  const totalTime = Date.now() - startTime;
-  const summary = buildSummary(completed, failed, skipped, totalTime);
-  appendLog(logPath, `\n---\n${summary}`);
-
-  emit(onEvent, { type: 'complete', completed, failed, skipped, totalTime });
-
-  // Clean up stop file if it exists
-  cleanupStopFile(ctxDir);
-
-  return { completed, failed, skipped, totalTime };
-}
-
-/**
- * Create a STOP file to gracefully halt the auto loop.
- */
-export function createStopFile(ctxDir) {
-  const stopPath = path.join(ctxDir, STOP_FILE);
-  fs.writeFileSync(stopPath, `Stop requested at ${new Date().toISOString()}\n`);
-}
-
-/**
- * Format auto loop results for display.
- */
-export function formatAutoResult({ completed, failed, skipped, totalTime }) {
-  const lines = [];
-  const mins = Math.round(totalTime / 1000 / 60);
-
-  lines.push(`  Total time: ${mins} minutes`);
-  lines.push('');
-
-  if (completed.length > 0) {
-    lines.push(`  ✓ Completed (${completed.length}):`);
-    for (const id of completed) lines.push(`    ${id}`);
-  }
-
-  if (failed.length > 0) {
-    lines.push(`  ✗ Failed (${failed.length}):`);
-    for (const f of failed) lines.push(`    ${f.id} — ${f.reason}`);
-  }
-
-  if (skipped.length > 0) {
-    lines.push(`  ○ Skipped (${skipped.length}):`);
-    for (const s of skipped) lines.push(`    ${s.id || s}`);
-  }
-
-  if (failed.length > 0) {
-    lines.push('');
-    lines.push('  Retry failed: ctx-cc auto --retry-failed');
-  }
-
-  return lines.join('\n');
-}
-
-// --- internal ---
-
-async function processStory({ story, ctxDir, projectDir, agentsDir, config, maxIterations, streaming, timeout, onEvent, logPath }) {
-  // Select story
-  selectStory(ctxDir, story.id);
-
-  for (let iteration = 1; iteration <= maxIterations; iteration++) {
-    emit(onEvent, { type: 'iteration', story: story.id, iteration, max: maxIterations });
-    appendLog(logPath, `  Iteration ${iteration}/${maxIterations}: `);
-
-    // Run pipeline: plan → execute
-    try {
-      transitionPhase(ctxDir, 'init'); // Reset to init for fresh pipeline
-      const pipeResult = await executePipeline({
-        steps: ['plan', 'execute'],
-        message: `Implement story ${story.id}: ${story.title}\n\n${story.description || ''}\n\nAcceptance criteria:\n${(story.acceptanceCriteria || []).map((c, i) => `${i + 1}. ${c}`).join('\n')}`,
-        ctxDir, projectDir, agentsDir,
-        streaming, timeout,
-      });
-
-      if (pipeResult.failed) {
-        appendLog(logPath, `pipeline failed at ${pipeResult.failed}\n`);
-        if (iteration === maxIterations) {
-          return { success: false, iterations: iteration, reason: `Pipeline failed: ${pipeResult.error}` };
-        }
-        continue; // Retry
-      }
-    } catch (err) {
-      appendLog(logPath, `pipeline error: ${err.message}\n`);
-      if (iteration === maxIterations) {
-        return { success: false, iterations: iteration, reason: err.message };
-      }
-      continue;
-    }
-
-    // Run review gate (if enabled)
-    if (isReviewGateEnabled(config)) {
-      try {
-        const reviewResult = await runReviewGate({
-          ctxDir, projectDir, agentsDir, streaming, timeout, config,
-        });
-
-        if (reviewResult.escalated) {
-          return { success: false, iterations: iteration, reason: 'Review loop exceeded — human review required.' };
-        }
-
-        if (!reviewResult.passed) {
-          appendLog(logPath, `review failed (cycle ${reviewResult.cycle})\n`);
-          if (iteration === maxIterations) {
-            return { success: false, iterations: iteration, reason: `Review failed: ${reviewResult.feedback}` };
-          }
-          continue; // Retry with feedback
-        }
-      } catch (err) {
-        appendLog(logPath, `review error: ${err.message}\n`);
-        // Review errors don't block — continue
-      }
-    }
-
-    // If we get here, story passed
-    appendLog(logPath, `passed\n`);
-
-    // Commit
-    commitTask({
-      projectDir, ctxDir,
-      agentName: 'auto',
-      taskId: story.id,
-      taskTitle: story.title,
-      criteriaIds: story.acceptanceCriteria || [],
-    });
-
-    // Mark story as passed in PRD
-    markStoryPassed(ctxDir, story.id);
-
-    return { success: true, iterations: iteration, reason: null };
-  }
-
-  return { success: false, iterations: maxIterations, reason: `Max iterations (${maxIterations}) exceeded.` };
-}
-
-function resolveStories(ctxDir, storyId, retryFailed) {
-  if (storyId) {
-    // Single story mode
-    try {
-      const prd = JSON.parse(fs.readFileSync(path.join(ctxDir, 'PRD.json'), 'utf-8'));
-      const story = (prd.stories || []).find(s => s.id === storyId);
-      return story ? [story] : [];
-    } catch {
-      return [];
-    }
-  }
-
-  const pending = listPendingStories(ctxDir);
-
-  if (retryFailed) {
-    // Read auto log for failed stories
-    const state = readState(ctxDir);
-    const failedIds = new Set((state?.autoFailedStories || []).map(f => f.id || f));
-    return pending.filter(s => failedIds.has(s.id));
-  }
-
-  // All P1 stories first, then P2, etc.
-  return pending.sort((a, b) => (a.priority || 99) - (b.priority || 99));
-}
-
-function markStoryPassed(ctxDir, storyId) {
-  try {
-    const prdPath = path.join(ctxDir, 'PRD.json');
-    const prd = JSON.parse(fs.readFileSync(prdPath, 'utf-8'));
-    const story = (prd.stories || []).find(s => s.id === storyId);
-    if (story) {
-      story.passes = true;
-      story.verifiedAt = new Date().toISOString();
-      prd.metadata = prd.metadata || {};
-      prd.metadata.passedStories = (prd.metadata.passedStories || 0) + 1;
-      fs.writeFileSync(prdPath, JSON.stringify(prd, null, 2) + '\n');
-    }
-  } catch {}
-}
-
-function shouldStop(ctxDir) {
-  return fs.existsSync(path.join(ctxDir, STOP_FILE));
-}
-
-function cleanupStopFile(ctxDir) {
-  const stopPath = path.join(ctxDir, STOP_FILE);
-  try { fs.unlinkSync(stopPath); } catch {}
-}
-
-function appendLog(logPath, text) {
-  fs.appendFileSync(logPath, text);
-}
-
-function buildSummary(completed, failed, skipped, totalTime) {
-  const mins = Math.round(totalTime / 1000 / 60);
-  return [
-    `## Summary`,
-    `- Completed: ${completed.length}`,
-    `- Failed: ${failed.length}`,
-    `- Skipped: ${skipped.length}`,
-    `- Total time: ${mins} minutes`,
-    `- Finished: ${new Date().toISOString()}`,
-  ].join('\n') + '\n';
-}
-
-function emit(fn, event) {
-  if (fn) fn(event);
-}

package/src/commits.js

@@ -1,94 +0,0 @@
-import { execSync } from 'child_process';
-import { readState, writeState, recordCompletedTask } from './state.js';
-
-/**
- * Create an atomic git commit for a completed task.
- *
- * Checks that there are staged or unstaged changes before committing.
- * Commit message format: ctx(<agent>): <task-title>
- * Body includes acceptance criteria satisfied.
- *
- * Returns { committed: boolean, hash: string|null, error: string|null }
- */
-export function commitTask({ projectDir, ctxDir, agentName, taskId, taskTitle, criteriaIds = [] }) {
-  try {
-    // Check for changes
-    const status = execSync('git status --porcelain', {
-      cwd: projectDir, encoding: 'utf-8', timeout: 5000,
-    }).trim();
-
-    if (!status) {
-      return { committed: false, hash: null, error: 'No changes to commit.' };
-    }
-
-    // Stage all changes (excluding .ctx/ state files to avoid noise)
-    execSync('git add -A -- . ":!.ctx/STATE.json" ":!.ctx/STATE.lock" ":!.ctx/HANDOFF.json"', {
-      cwd: projectDir, timeout: 5000,
-    });
-
-    // Build commit message
-    const subject = `ctx(${agentName}): ${taskTitle}`;
-    const body = buildCommitBody(taskId, criteriaIds);
-    const message = `${subject}\n\n${body}`;
-
-    // Commit
-    execSync(`git commit -m ${shellEscape(message)}`, {
-      cwd: projectDir, encoding: 'utf-8', timeout: 10000,
-    });
-
-    // Get commit hash
-    const hash = execSync('git rev-parse --short HEAD', {
-      cwd: projectDir, encoding: 'utf-8', timeout: 5000,
-    }).trim();
-
-    // Record in state
-    recordCompletedTask(ctxDir, taskId, taskTitle, criteriaIds);
-
-    // Log commit in agent history
-    const state = readState(ctxDir);
-    if (state) {
-      state.lastCommit = { hash, taskId, taskTitle, committedAt: new Date().toISOString() };
-      writeState(ctxDir, state);
-    }
-
-    return { committed: true, hash, error: null };
-  } catch (err) {
-    return { committed: false, hash: null, error: err.message };
-  }
-}
-
-/**
- * Show CTX commit log for the current story.
- */
-export function getCtxCommitLog(projectDir, limit = 20) {
-  try {
-    const log = execSync(`git log --oneline --grep="^ctx(" -${limit} --no-color`, {
-      cwd: projectDir, encoding: 'utf-8', timeout: 5000,
-    }).trim();
-    return log || 'No CTX commits found.';
-  } catch {
-    return 'No CTX commits found.';
-  }
-}
-
-// --- internal ---
-
-function buildCommitBody(taskId, criteriaIds) {
-  const lines = [];
-  if (taskId) lines.push(`Task: ${taskId}`);
-  if (criteriaIds.length > 0) {
-    lines.push('');
-    lines.push('Acceptance criteria satisfied:');
-    for (const id of criteriaIds) {
-      lines.push(`  - ${id}`);
-    }
-  }
-  lines.push('');
-  lines.push('Co-Authored-By: Claude <noreply@anthropic.com>');
-  return lines.join('\n');
-}
-
-function shellEscape(str) {
-  // Use $'...' syntax for strings with newlines
-  return "$'" + str.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n') + "'";
-}