ctx-cc 3.5.0 → 4.1.0

package/src/agents.js

@@ -0,0 +1,109 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Parse YAML-like frontmatter from a markdown file.
+ * Returns { attrs: {}, body: string } or null if no frontmatter.
+ */
+export function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return null;
+
+  const attrs = {};
+  for (const line of match[1].split('\n')) {
+    const sep = line.indexOf(':');
+    if (sep === -1) continue;
+    const key = line.slice(0, sep).trim();
+    const val = line.slice(sep + 1).trim();
+    attrs[key] = val;
+  }
+
+  return { attrs, body: match[2] };
+}
+
+/**
+ * Derive a CLI command name from an agent filename.
+ * ctx-planner.md → plan
+ * ctx-arch-mapper.md → arch-map
+ * ctx-quality-mapper.md → quality-map
+ */
+export function deriveCommandName(filename) {
+  const base = filename.replace(/\.md$/, '').replace(/^ctx-/, '');
+
+  // Special mapping: *-mapper → *-map (shorter CLI names)
+  if (base.endsWith('-mapper')) return base.replace(/-mapper$/, '-map');
+  // Special mapping: *-suggester → base (e.g. criteria-suggester → criteria)
+  if (base.endsWith('-suggester')) return base.replace(/-suggester$/, '');
+  // Special mapping: *-coordinator → coordinate
+  if (base.endsWith('-coordinator')) return base.replace(/-coordinator$/, '');
+
+  // Common verb forms for shorter commands
+  const verbMap = {
+    'planner': 'plan',
+    'executor': 'execute',
+    'researcher': 'research',
+    'debugger': 'debug',
+    'reviewer': 'review',
+    'designer': 'design',
+    'verifier': 'verify',
+    'discusser': 'discuss',
+    'learner': 'learn',
+    'predictor': 'predict',
+    'auditor': 'audit',
+    'parallelizer': 'parallelize',
+    'mapper': 'map',
+    'handoff': 'handoff',
+    'team': 'team',
+    'qa': 'qa',
+  };
+
+  return verbMap[base] || base;
+}
+
+/**
+ * Discover all agents from a directory.
+ * Returns an array of { file, command, name, description, tools, color }.
+ */
+export function discoverAgents(agentsDir) {
+  if (!fs.existsSync(agentsDir)) return [];
+
+  const agents = [];
+  const entries = fs.readdirSync(agentsDir).filter(f => f.startsWith('ctx-') && f.endsWith('.md')).sort();
+
+  for (const file of entries) {
+    try {
+      const content = fs.readFileSync(path.join(agentsDir, file), 'utf-8');
+      const fm = parseFrontmatter(content);
+      if (!fm || !fm.attrs.name) {
+        process.stderr.write(`Warning: skipping ${file} (missing or invalid frontmatter)\n`);
+        continue;
+      }
+
+      agents.push({
+        file,
+        command: deriveCommandName(file),
+        name: fm.attrs.name,
+        description: fm.attrs.description || '',
+        tools: fm.attrs.tools || '',
+        color: fm.attrs.color || 'white',
+      });
+    } catch (err) {
+      process.stderr.write(`Warning: skipping ${file} (${err.message})\n`);
+    }
+  }
+
+  return agents;
+}
+
+/**
+ * Format agents as a table for display.
+ */
+export function formatAgentTable(agents) {
+  const maxCmd = Math.max(12, ...agents.map(a => a.command.length));
+  const header = `  ${'Command'.padEnd(maxCmd)}  Description`;
+  const sep = `  ${'─'.repeat(maxCmd)}  ${'─'.repeat(50)}`;
+
+  const rows = agents.map(a => `  ${a.command.padEnd(maxCmd)}  ${a.description}`);
+
+  return [header, sep, ...rows].join('\n');
+}

package/src/auto.js

@@ -0,0 +1,287 @@
+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/capabilities.js

@@ -0,0 +1,226 @@
+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 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
+  planning: {
+    agents: ['ctx-planner.md', 'ctx-predictor.md', 'ctx-criteria-suggester.md', 'ctx-parallelizer.md'],
+    allowed: ['Read', 'Glob', 'Grep', 'Write', 'Agent', 'AskUserQuestion'],
+    denied: ['Edit', 'Bash', 'NotebookEdit'],
+    reason: 'Planning agents should not modify code directly.',
+  },
+
+  // Execution agents — full code access, no orchestration
+  execution: {
+    agents: ['ctx-executor.md', 'ctx-debugger.md'],
+    allowed: ['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep'],
+    denied: ['Agent'],
+    reason: 'Execution agents should not spawn other agents.',
+  },
+
+  // Review agents — read + run tests + Codex cross-review, no modifications
+  review: {
+    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'],
+    allowed: ['Read', 'Glob', 'Grep', 'Bash', 'Write'],
+    denied: ['Edit'],
+    reason: 'Mapper agents analyze but should not modify existing code.',
+  },
+
+  // Knowledge agents — read + web research
+  knowledge: {
+    agents: ['ctx-researcher.md', 'ctx-learner.md'],
+    allowed: ['Read', 'Glob', 'Grep', 'Bash', 'Write', 'WebSearch', 'WebFetch'],
+    denied: ['Edit'],
+    reason: 'Knowledge agents gather info but should not modify code.',
+  },
+
+  // Coordination agents — state management
+  coordination: {
+    agents: ['ctx-team-coordinator.md', 'ctx-handoff.md', 'ctx-discusser.md'],
+    allowed: ['Read', 'Write', 'Glob', 'Grep', 'AskUserQuestion'],
+    denied: ['Edit', 'Bash'],
+    reason: 'Coordination agents manage state, not code.',
+  },
+
+  // Design agents — read + generate
+  design: {
+    agents: ['ctx-designer.md'],
+    allowed: ['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash'],
+    denied: [],
+    reason: 'Design agents may need full access for asset generation.',
+  },
+
+  // QA agents — full read + browser
+  qa: {
+    agents: ['ctx-qa.md'],
+    allowed: ['Read', 'Write', 'Glob', 'Grep', 'Bash'],
+    denied: ['Edit'],
+    reason: 'QA agents test but should not fix code.',
+  },
+
+  // 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 };
+    }
+  }
+  return null;
+}
+
+/**
+ * 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) {
+    return { allowed: true, reason: null };
+  }
+
+  if (category.denied.includes(toolName)) {
+    return {
+      allowed: false,
+      reason: `Tool "${toolName}" denied for ${category.category} agents. ${category.reason}`,
+    };
+  }
+
+  return { allowed: true, reason: null };
+}
+
+/**
+ * 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 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;
+}
+
+/**
+ * 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 readManifestVersion(ctxDir) {
+  const manifestPath = path.join(ctxDir, 'capability-manifest.json');
+  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,
+  };
+}
+
+/**
+ * Format capabilities for display.
+ */
+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(', ')}`);
+    if (config.denied.length > 0) {
+      lines.push(`    Denied:  ${config.denied.join(', ')}`);
+    }
+    lines.push(`    Reason:  ${config.reason}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+export { DEFAULT_CAPABILITIES };