ctx-cc 3.5.0 → 4.1.0

package/src/review-gate.js

@@ -0,0 +1,338 @@
+import fs from 'fs';
+import path from 'path';
+import { readState, writeState, logAgentInvocation, completeAgentInvocation } from './state.js';
+import { buildContext } from './context.js';
+import { runAgent } from './runner.js';
+
+const MAX_REVIEW_CYCLES = 3;
+
+/**
+ * Run the three-stage review gate.
+ *
+ * Stage 1: ctx-reviewer checks spec compliance (acceptance criteria)
+ * 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 any stage fails, returns feedback for re-execution.
+ * Max cycles before requiring human intervention.
+ *
+ * Options:
+ *   ctxDir, projectDir, agentsDir, streaming, timeout, config
+ *
+ * Returns:
+ *   { passed, stage1, stage2, stage3, cycle, feedback, escalated }
+ */
+export async function runReviewGate({ ctxDir, projectDir, agentsDir, streaming = true, timeout = 300000, config = {} }) {
+  const state = readState(ctxDir);
+  if (!state) throw new Error('No STATE.json found.');
+
+  const maxCycles = config.maxReviewCycles || MAX_REVIEW_CYCLES;
+  const reviewState = state.reviewGate || { cycle: 0, history: [] };
+  reviewState.cycle += 1;
+
+  if (reviewState.cycle > maxCycles) {
+    return {
+      passed: false,
+      stage1: null,
+      stage2: null,
+      cycle: reviewState.cycle,
+      feedback: `Review loop exceeded (${maxCycles} cycles). Human review required.`,
+      escalated: true,
+    };
+  }
+
+  // Stage 1: Spec compliance (reviewer)
+  const stage1 = await runReviewStage({
+    stageName: 'spec-compliance',
+    agentFile: 'ctx-reviewer.md',
+    agentCommand: 'review',
+    prompt: buildReviewPrompt(state, 'spec'),
+    ctxDir, projectDir, agentsDir, streaming, timeout,
+  });
+
+  // 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-reviewer.md',
+      agentCommand: 'review',
+      prompt: buildReviewPrompt(state, 'quality'),
+      ctxDir, projectDir, agentsDir, streaming, timeout,
+    });
+  }
+
+  // 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;
+  if (!passed) {
+    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',
+  });
+
+  state.reviewGate = reviewState;
+  writeState(ctxDir, state);
+
+  // Save review results
+  saveReviewResult(ctxDir, state.activeStory, reviewState);
+
+  return {
+    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,
+  };
+}
+
+/**
+ * Check if the review gate is enabled in config.
+ */
+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.
+ */
+export function getReviewHistory(ctxDir) {
+  const state = readState(ctxDir);
+  return state?.reviewGate?.history || [];
+}
+
+/**
+ * Format review gate result for display.
+ */
+export function formatReviewResult(result) {
+  if (!result) return '  No review results.';
+
+  const lines = [];
+  const icon = result.passed ? '✓' : '✗';
+  lines.push(`  Review cycle ${result.cycle}: ${icon} ${result.passed ? 'PASSED' : 'FAILED'}`);
+
+  if (result.stage1) {
+    const s1Icon = result.stage1.passed ? '✓' : '✗';
+    lines.push(`    ${s1Icon} Stage 1 (spec compliance): ${result.stage1.passed ? 'pass' : result.stage1.issues || 'fail'}`);
+  }
+  if (result.stage2) {
+    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('');
+    lines.push('  ⚠ Review loop exceeded — human review required.');
+  }
+
+  if (result.feedback) {
+    lines.push('');
+    lines.push('  Feedback for re-execution:');
+    for (const line of result.feedback.split('\n')) {
+      lines.push(`    ${line}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// --- internal ---
+
+async function runReviewStage({ stageName, agentFile, agentCommand, prompt, ctxDir, projectDir, agentsDir, streaming, timeout }) {
+  const agentPath = path.join(agentsDir, agentFile);
+
+  if (!fs.existsSync(agentPath)) {
+    return { passed: true, issues: null, output: 'Agent not found — skipping.' };
+  }
+
+  logAgentInvocation(ctxDir, agentFile, `Review gate: ${stageName}`);
+
+  const { context } = buildContext(agentCommand, projectDir, ctxDir);
+
+  try {
+    const result = await runAgent({
+      agentPath,
+      message: prompt,
+      streaming,
+      timeout,
+      context,
+    });
+
+    completeAgentInvocation(ctxDir, agentFile);
+
+    const output = result.stdout || '';
+    const passed = parseReviewVerdict(output);
+    const issues = passed ? null : extractIssues(output);
+
+    return { passed, issues, output: output.slice(0, 2000) };
+  } catch (err) {
+    completeAgentInvocation(ctxDir, agentFile);
+    return { passed: false, issues: `Agent error: ${err.message}`, output: '' };
+  }
+}
+
+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.',
+      'Check against the acceptance criteria for the current story.',
+      `Active story: ${state.activeStory || 'unknown'}`,
+      '',
+      'Output format:',
+      'VERDICT: PASS or FAIL',
+      'ISSUES: (list if FAIL)',
+      '',
+      'Be strict but fair. Focus on acceptance criteria satisfaction.',
+    ].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.',
+    '',
+    'Output format:',
+    'VERDICT: PASS or FAIL',
+    'ISSUES: (list if FAIL)',
+    '',
+    'Be strict on security. Be reasonable on style.',
+  ].join('\n');
+}
+
+function parseReviewVerdict(output) {
+  if (!output) return false;
+  const lower = output.toLowerCase();
+  // Look for explicit PASS verdict
+  if (/verdict:\s*pass/i.test(output)) return true;
+  // Look for explicit FAIL verdict
+  if (/verdict:\s*fail/i.test(output)) return false;
+  // Heuristic: if no critical issues mentioned, assume pass
+  if (lower.includes('all criteria') && lower.includes('pass')) return true;
+  if (lower.includes('no issues found')) return true;
+  // Default: fail (conservative)
+  return false;
+}
+
+function extractIssues(output) {
+  if (!output) return 'No output from reviewer.';
+  // Try to extract issues section
+  const issueMatch = output.match(/ISSUES?:\s*([\s\S]*?)(?=\n\n|$)/i);
+  if (issueMatch) return issueMatch[1].trim().slice(0, 500);
+  // Fallback: first 300 chars
+  return output.slice(0, 300);
+}
+
+function saveReviewResult(ctxDir, storyId, reviewState) {
+  const reviewDir = path.join(ctxDir, 'reviews');
+  if (!fs.existsSync(reviewDir)) fs.mkdirSync(reviewDir, { recursive: true });
+
+  const filename = `${storyId || 'unknown'}-${new Date().toISOString().replace(/[:.]/g, '-')}.json`;
+  fs.writeFileSync(
+    path.join(reviewDir, filename),
+    JSON.stringify(reviewState, null, 2) + '\n'
+  );
+}

package/src/runner.js

@@ -0,0 +1,120 @@
+import { spawn, execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+
+const DEFAULT_TIMEOUT_MS = 300_000; // 5 minutes
+
+/**
+ * Check if the claude CLI is available.
+ * Returns the path to the binary, or null.
+ */
+export function findClaudeBinary() {
+  try {
+    const result = execSync('which claude 2>/dev/null || where claude 2>/dev/null', {
+      encoding: 'utf-8',
+      timeout: 5000,
+    }).trim();
+    return result || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run an agent by reading its markdown file and invoking claude.
+ *
+ * Options:
+ *   agentPath   - absolute path to the agent .md file
+ *   message     - user message to pass to the agent
+ *   streaming   - stream output to stdout (default true)
+ *   timeout     - timeout in ms (default 300000)
+ *   context     - optional project context string to prepend
+ *   onStderr    - callback for stderr lines
+ *
+ * Returns { exitCode, stdout, stderr } (stdout only populated when !streaming)
+ */
+export function runAgent({ agentPath, message, streaming = true, timeout = DEFAULT_TIMEOUT_MS, context = '', onStderr = null }) {
+  return new Promise((resolve, reject) => {
+    // Validate agent file exists
+    if (!fs.existsSync(agentPath)) {
+      reject(new Error(`Agent file not found: ${agentPath}`));
+      return;
+    }
+
+    // Check claude binary
+    const claudeBin = findClaudeBinary();
+    if (!claudeBin) {
+      reject(new Error(
+        'Claude Code CLI not found. Install from https://claude.ai/download\n' +
+        'Then ensure "claude" is available in your PATH.'
+      ));
+      return;
+    }
+
+    const instructions = fs.readFileSync(agentPath, 'utf-8');
+    const fullPrompt = context
+      ? `${instructions}\n\n---\nProject Context:\n${context}\n\n---\nUser Request: ${message}`
+      : `${instructions}\n\n---\nUser Request: ${message}`;
+
+    const args = ['--print', '-p', fullPrompt];
+    if (streaming) args.unshift('--stream');
+
+    const child = spawn(claudeBin, args, {
+      stdio: streaming ? ['ignore', 'inherit', 'pipe'] : ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env },
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    if (!streaming && child.stdout) {
+      child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+    }
+
+    if (child.stderr) {
+      child.stderr.on('data', (chunk) => {
+        const text = chunk.toString();
+        stderr += text;
+        if (onStderr) onStderr(text);
+      });
+    }
+
+    // Timeout handling
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM');
+      // Give 5s for graceful shutdown, then force kill
+      setTimeout(() => {
+        if (!child.killed) child.kill('SIGKILL');
+      }, 5000);
+      reject(new Error(`Agent timed out after ${timeout / 1000}s. Increase timeout with: ctx config set agentTimeout ${timeout / 1000 * 2}`));
+    }, timeout);
+
+    // Forward SIGINT to child
+    const sigintHandler = () => {
+      child.kill('SIGTERM');
+      clearTimeout(timer);
+    };
+    process.on('SIGINT', sigintHandler);
+
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      process.removeListener('SIGINT', sigintHandler);
+
+      if (code !== 0 && code !== null) {
+        const errMsg = stderr.trim();
+        reject(new Error(
+          `Agent exited with code ${code}${errMsg ? `\n[stderr] ${errMsg}` : ''}`
+        ));
+        return;
+      }
+
+      resolve({ exitCode: code ?? 0, stdout, stderr });
+    });
+
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      process.removeListener('SIGINT', sigintHandler);
+      reject(new Error(`Failed to spawn claude: ${err.message}`));
+    });
+  });
+}

package/src/skills.js

@@ -0,0 +1,143 @@
+import fs from 'fs';
+import path from 'path';
+import { parseFrontmatter, discoverAgents } from './agents.js';
+
+/**
+ * Maximum tokens for a skill description (loaded at startup).
+ * Full instructions are loaded on-demand when the skill is invoked.
+ */
+const MAX_DESCRIPTION_TOKENS = 100;
+const CHARS_PER_TOKEN = 4;
+const MAX_DESCRIPTION_CHARS = MAX_DESCRIPTION_TOKENS * CHARS_PER_TOKEN;
+
+/**
+ * Analyze agent descriptions and report which exceed the token budget.
+ * Returns { agents: [...], totalTokens, overBudget: [...] }
+ */
+export function analyzeDescriptions(agentsDir) {
+  const agents = discoverAgents(agentsDir);
+  const results = [];
+  let totalTokens = 0;
+
+  for (const agent of agents) {
+    const tokens = Math.ceil(agent.description.length / CHARS_PER_TOKEN);
+    totalTokens += tokens;
+    results.push({
+      file: agent.file,
+      command: agent.command,
+      description: agent.description,
+      tokens,
+      overBudget: tokens > MAX_DESCRIPTION_TOKENS,
+    });
+  }
+
+  const overBudget = results.filter(r => r.overBudget);
+
+  return { agents: results, totalTokens, overBudget };
+}
+
+/**
+ * Generate a compact skill description from a verbose one.
+ * Truncates to ~100 tokens while preserving key info.
+ */
+export function compactDescription(description) {
+  if (description.length <= MAX_DESCRIPTION_CHARS) return description;
+
+  // Strategy: take first sentence, trim to budget
+  const firstSentence = description.split(/\.\s/)[0];
+  if (firstSentence.length <= MAX_DESCRIPTION_CHARS) {
+    return firstSentence + '.';
+  }
+
+  return description.slice(0, MAX_DESCRIPTION_CHARS - 3) + '...';
+}
+
+/**
+ * Generate a skill-format agent file from existing agent markdown.
+ * The skill format has:
+ *   - Compact description in frontmatter (~100 tokens)
+ *   - Full instructions in body (loaded on-demand)
+ *
+ * Returns the new file content.
+ */
+export function convertToSkillFormat(agentContent) {
+  const parsed = parseFrontmatter(agentContent);
+  if (!parsed) return agentContent; // Not a valid agent file
+
+  const attrs = parsed.attrs;
+  const compactDesc = compactDescription(attrs.description || '');
+
+  // Rebuild frontmatter with compact description
+  const newFrontmatter = Object.entries(attrs)
+    .map(([key, val]) => {
+      if (key === 'description') return `description: ${compactDesc}`;
+      return `${key}: ${val}`;
+    })
+    .join('\n');
+
+  return `---\n${newFrontmatter}\n---\n${parsed.body}`;
+}
+
+/**
+ * Convert all agents in a directory to skill format.
+ * Writes new files to outputDir (or modifies in place if same as input).
+ * Returns { converted: number, skipped: number, totalTokensSaved: number }
+ */
+export function convertAllAgents(agentsDir, outputDir = null) {
+  const targetDir = outputDir || agentsDir;
+  if (targetDir !== agentsDir && !fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  const files = fs.readdirSync(agentsDir).filter(f => f.startsWith('ctx-') && f.endsWith('.md'));
+  let converted = 0;
+  let skipped = 0;
+  let tokensSaved = 0;
+
+  for (const file of files) {
+    const content = fs.readFileSync(path.join(agentsDir, file), 'utf-8');
+    const parsed = parseFrontmatter(content);
+    if (!parsed) { skipped++; continue; }
+
+    const oldTokens = Math.ceil((parsed.attrs.description || '').length / CHARS_PER_TOKEN);
+    const newContent = convertToSkillFormat(content);
+    const newParsed = parseFrontmatter(newContent);
+    const newTokens = Math.ceil((newParsed?.attrs.description || '').length / CHARS_PER_TOKEN);
+
+    fs.writeFileSync(path.join(targetDir, file), newContent);
+    tokensSaved += Math.max(0, oldTokens - newTokens);
+    converted++;
+  }
+
+  return { converted, skipped, totalTokensSaved: tokensSaved };
+}
+
+/**
+ * Calculate total upfront context cost of all agent descriptions.
+ */
+export function calculateUpfrontTokens(agentsDir) {
+  const { totalTokens, agents } = analyzeDescriptions(agentsDir);
+  return { totalTokens, agentCount: agents.length };
+}
+
+/**
+ * Format analysis results for display.
+ */
+export function formatAnalysis(analysis) {
+  const lines = [];
+  lines.push(`  Total agents: ${analysis.agents.length}`);
+  lines.push(`  Total description tokens: ${analysis.totalTokens}`);
+  lines.push(`  Over budget (>${MAX_DESCRIPTION_TOKENS} tokens): ${analysis.overBudget.length}`);
+
+  if (analysis.overBudget.length > 0) {
+    lines.push('');
+    lines.push('  Over-budget agents:');
+    for (const a of analysis.overBudget) {
+      lines.push(`    ${a.command.padEnd(15)} ${a.tokens} tokens (${a.tokens - MAX_DESCRIPTION_TOKENS} over)`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export { MAX_DESCRIPTION_TOKENS, MAX_DESCRIPTION_CHARS };