@cluesmith/codev 2.0.3 → 2.0.7

package/dist/commands/consult/index.js

@@ -1,7 +1,10 @@
 /**
  * consult - AI consultation with external models
  *
- * Provides unified interface to gemini-cli, codex, and Claude Agent SDK.
+ * Three modes:
+ * 1. General — ad-hoc prompts via --prompt or --prompt-file
+ * 2. Protocol — structured reviews via --protocol + --type
+ * 3. Stats — consultation metrics (delegated to stats.ts, handled in cli.ts)
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -9,15 +12,15 @@ import { spawn, execSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import chalk from 'chalk';
 import { query as claudeQuery } from '@anthropic-ai/claude-agent-sdk';
-import { readCodevFile, findWorkspaceRoot, hasLocalOverride } from '../../lib/skeleton.js';
+import { Codex } from '@openai/codex-sdk';
+import { readCodevFile, findWorkspaceRoot } from '../../lib/skeleton.js';
+import { MetricsDB } from './metrics.js';
+import { extractUsage, extractReviewText } from './usage-extractor.js';
 const MODEL_CONFIGS = {
-    gemini: { cli: 'gemini', args: ['--yolo'], envVar: 'GEMINI_SYSTEM_MD' },
-    // Codex uses experimental_instructions_file config flag (not env var)
-    // See: https://github.com/openai/codex/discussions/3896
-    codex: { cli: 'codex', args: ['exec', '-m', 'gpt-5.2-codex', '--full-auto'], envVar: null },
+    gemini: { cli: 'gemini', args: [], envVar: 'GEMINI_SYSTEM_MD' },
 };
-// Models that use the Agent SDK instead of CLI subprocess
-const SDK_MODELS = ['claude'];
+// Models that use an Agent SDK instead of CLI subprocess
+const SDK_MODELS = ['claude', 'codex'];
 // Claude Agent SDK turn limit. Claude explores the codebase with Read/Glob/Grep
 // tools before producing its verdict, so it needs a generous turn budget.
 const CLAUDE_MAX_TURNS = 200;
@@ -27,60 +30,42 @@ const MODEL_ALIASES = {
     gpt: 'codex',
     opus: 'claude',
 };
-// Valid review types
-const VALID_REVIEW_TYPES = [
-    'spec-review',
-    'plan-review',
-    'impl-review',
-    'pr-ready',
-    'integration-review',
-];
-/**
- * Validate role name to prevent directory traversal attacks.
- * Only allows alphanumeric, hyphen, and underscore characters.
- */
-function isValidRoleName(roleName) {
-    return /^[a-zA-Z0-9_-]+$/.test(roleName);
-}
-/**
- * List available roles in codev/roles/
- * Excludes non-role files like README.md, review-types/, etc.
- */
-function listAvailableRoles(workspaceRoot) {
-    const rolesDir = path.join(workspaceRoot, 'codev', 'roles');
-    if (!fs.existsSync(rolesDir))
-        return [];
-    const excludePatterns = ['readme', 'review-types', 'overview', 'index'];
-    return fs.readdirSync(rolesDir)
-        .filter(f => {
-        if (!f.endsWith('.md'))
-            return false;
-        const basename = f.replace('.md', '').toLowerCase();
-        return !excludePatterns.some(pattern => basename.includes(pattern));
-    })
-        .map(f => f.replace('.md', ''));
+// Helper to record a metrics entry, opening and closing the DB
+function recordMetrics(ctx, extra) {
+    try {
+        const db = new MetricsDB();
+        try {
+            db.record({
+                timestamp: ctx.timestamp,
+                model: ctx.model,
+                reviewType: ctx.reviewType,
+                subcommand: ctx.subcommand,
+                protocol: ctx.protocol,
+                projectId: ctx.projectId,
+                durationSeconds: extra.durationSeconds,
+                inputTokens: extra.inputTokens,
+                cachedInputTokens: extra.cachedInputTokens,
+                outputTokens: extra.outputTokens,
+                costUsd: extra.costUsd,
+                exitCode: extra.exitCode,
+                workspacePath: ctx.workspacePath,
+                errorMessage: extra.errorMessage,
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (err) {
+        console.error(`[warn] Failed to record metrics: ${err instanceof Error ? err.message : String(err)}`);
+    }
 }
 /**
- * Load a custom role from codev/roles/<name>.md
- * Falls back to embedded skeleton if not found locally.
+ * Validate name to prevent directory traversal attacks.
+ * Only allows alphanumeric, hyphen, and underscore characters.
  */
-function loadCustomRole(workspaceRoot, roleName) {
-    // Validate role name to prevent directory traversal
-    if (!isValidRoleName(roleName)) {
-        throw new Error(`Invalid role name: '${roleName}'\n` +
-            'Role names can only contain letters, numbers, hyphens, and underscores.');
-    }
-    // Use readCodevFile which handles local-first with skeleton fallback
-    const rolePath = `roles/${roleName}.md`;
-    const roleContent = readCodevFile(rolePath, workspaceRoot);
-    if (!roleContent) {
-        const available = listAvailableRoles(workspaceRoot);
-        const availableStr = available.length > 0
-            ? `\n\nAvailable roles:\n${available.map(r => `  - ${r}`).join('\n')}`
-            : '\n\nNo custom roles found in codev/roles/';
-        throw new Error(`Role '${roleName}' not found.${availableStr}`);
-    }
-    return roleContent;
+function isValidRoleName(name) {
+    return /^[a-zA-Z0-9_-]+$/.test(name);
 }
 /**
  * Load the consultant role.
@@ -96,29 +81,24 @@ function loadRole(workspaceRoot) {
     return role;
 }
 /**
- * Load a review type prompt.
- * Checks consult-types/{type}.md first (new location),
- * then falls back to roles/review-types/{type}.md (deprecated) with a warning.
+ * Resolve protocol prompt template.
+ * 1. If --protocol given → codev/protocols/<protocol>/consult-types/<type>-review.md
+ * 2. If --type alone → codev/consult-types/<type>-review.md
+ * 3. Error if file not found
  */
-function loadReviewTypePrompt(workspaceRoot, reviewType) {
-    const primaryPath = `consult-types/${reviewType}.md`;
-    const fallbackPath = `roles/review-types/${reviewType}.md`;
-    // 1. Check LOCAL consult-types/ first (preferred location)
-    if (hasLocalOverride(primaryPath, workspaceRoot)) {
-        return readCodevFile(primaryPath, workspaceRoot);
-    }
-    // 2. Check LOCAL roles/review-types/ (deprecated location with warning)
-    if (hasLocalOverride(fallbackPath, workspaceRoot)) {
-        console.error(chalk.yellow('Warning: Review types in roles/review-types/ are deprecated.'));
-        console.error(chalk.yellow('Move your custom types to consult-types/ for future compatibility.'));
-        return readCodevFile(fallbackPath, workspaceRoot);
-    }
-    // 3. Fall back to embedded skeleton consult-types/ (default)
-    const skeletonPrompt = readCodevFile(primaryPath, workspaceRoot);
-    if (skeletonPrompt) {
-        return skeletonPrompt;
+function resolveProtocolPrompt(workspaceRoot, protocol, type) {
+    const templateName = `${type}-review.md`;
+    const relativePath = protocol
+        ? `protocols/${protocol}/consult-types/${templateName}`
+        : `consult-types/${templateName}`;
+    const content = readCodevFile(relativePath, workspaceRoot);
+    if (!content) {
+        const location = protocol
+            ? `codev/protocols/${protocol}/consult-types/${templateName}`
+            : `codev/consult-types/${templateName}`;
+        throw new Error(`Prompt template not found: ${location}`);
     }
-    return null;
+    return content;
 }
 /**
  * Load .env file if it exists
@@ -149,37 +129,83 @@ function loadDotenv(workspaceRoot) {
     }
 }
 /**
- * Find a spec file by number
+ * Find a spec file by number. Returns null if not found.
+ * Errors if multiple matches found.
  */
 function findSpec(workspaceRoot, number) {
     const specsDir = path.join(workspaceRoot, 'codev', 'specs');
     const pattern = String(number).padStart(4, '0');
     if (fs.existsSync(specsDir)) {
-        const files = fs.readdirSync(specsDir);
-        for (const file of files) {
-            if (file.startsWith(pattern) && file.endsWith('.md')) {
-                return path.join(specsDir, file);
-            }
+        const matches = fs.readdirSync(specsDir).filter(f => f.startsWith(pattern) && f.endsWith('.md'));
+        if (matches.length > 1) {
+            const list = matches.map(f => `  - codev/specs/${f}`).join('\n');
+            throw new Error(`Multiple spec files match '${pattern}*':\n${list}`);
+        }
+        if (matches.length === 1) {
+            return path.join(specsDir, matches[0]);
         }
     }
     return null;
 }
 /**
- * Find a plan file by number
+ * Find a plan file by number. Returns null if not found.
+ * Errors if multiple matches found.
  */
 function findPlan(workspaceRoot, number) {
     const plansDir = path.join(workspaceRoot, 'codev', 'plans');
     const pattern = String(number).padStart(4, '0');
     if (fs.existsSync(plansDir)) {
-        const files = fs.readdirSync(plansDir);
-        for (const file of files) {
-            if (file.startsWith(pattern) && file.endsWith('.md')) {
-                return path.join(plansDir, file);
-            }
+        const matches = fs.readdirSync(plansDir).filter(f => f.startsWith(pattern) && f.endsWith('.md'));
+        if (matches.length > 1) {
+            const list = matches.map(f => `  - codev/plans/${f}`).join('\n');
+            throw new Error(`Multiple plan files match '${pattern}*':\n${list}`);
+        }
+        if (matches.length === 1) {
+            return path.join(plansDir, matches[0]);
         }
     }
     return null;
 }
+/**
+ * Check if running in a builder worktree
+ */
+function isBuilderContext() {
+    return process.cwd().includes('/.builders/');
+}
+/**
+ * Get builder project state from status.yaml
+ */
+function getBuilderProjectState(workspaceRoot) {
+    const projectsDir = path.join(workspaceRoot, 'codev', 'projects');
+    if (!fs.existsSync(projectsDir)) {
+        throw new Error('No project state found. Are you in a builder worktree?');
+    }
+    const entries = fs.readdirSync(projectsDir);
+    const projectDirs = entries.filter(e => {
+        return fs.statSync(path.join(projectsDir, e)).isDirectory();
+    });
+    if (projectDirs.length === 0) {
+        throw new Error('No project found in codev/projects/');
+    }
+    if (projectDirs.length > 1) {
+        throw new Error(`Multiple projects found: ${projectDirs.join(', ')}`);
+    }
+    const dir = projectDirs[0];
+    const statusPath = path.join(projectsDir, dir, 'status.yaml');
+    if (!fs.existsSync(statusPath)) {
+        throw new Error(`status.yaml not found in ${dir}`);
+    }
+    const content = fs.readFileSync(statusPath, 'utf-8');
+    // Simple YAML parsing for the fields we need
+    const idMatch = content.match(/^id:\s*'?(\d+)'?\s*$/m);
+    const titleMatch = content.match(/^title:\s*(.+)$/m);
+    const phaseMatch = content.match(/^current_plan_phase:\s*(.+)$/m);
+    const id = idMatch?.[1] ?? '';
+    const title = titleMatch?.[1]?.trim() ?? '';
+    const rawPhase = phaseMatch?.[1]?.trim() ?? 'null';
+    const currentPlanPhase = rawPhase === 'null' ? null : rawPhase;
+    return { id, title, currentPlanPhase };
+}
 /**
  * Log query to history file
  */
@@ -211,13 +237,109 @@ function commandExists(cmd) {
         return false;
     }
 }
+// Codex pricing for cost computation (matches values from old SUBPROCESS_MODEL_PRICING)
+const CODEX_PRICING = { inputPer1M: 2.00, cachedInputPer1M: 1.00, outputPer1M: 8.00 };
+/**
+ * Run Codex consultation via @openai/codex-sdk.
+ * Mirrors runClaudeConsultation() — streams events, captures usage, records metrics.
+ */
+export async function runCodexConsultation(queryText, role, workspaceRoot, outputPath, metricsCtx) {
+    const chunks = [];
+    const startTime = Date.now();
+    let usageData = null;
+    let errorMessage = null;
+    let exitCode = 0;
+    // Write role to temp file — SDK requires file path for instructions
+    const tempFile = path.join(tmpdir(), `codev-role-${Date.now()}.md`);
+    fs.writeFileSync(tempFile, role);
+    try {
+        const codex = new Codex({
+            config: {
+                experimental_instructions_file: tempFile,
+            },
+        });
+        const thread = codex.startThread({
+            model: 'gpt-5.2-codex',
+            sandboxMode: 'read-only',
+            modelReasoningEffort: 'medium',
+            workingDirectory: workspaceRoot,
+        });
+        const { events } = await thread.runStreamed(queryText);
+        for await (const event of events) {
+            if (event.type === 'item.completed') {
+                const item = event.item;
+                if (item.type === 'agent_message') {
+                    process.stdout.write(item.text);
+                    chunks.push(item.text);
+                }
+            }
+            if (event.type === 'turn.completed') {
+                const input = event.usage.input_tokens;
+                const cached = event.usage.cached_input_tokens;
+                const output = event.usage.output_tokens;
+                const uncached = input - cached;
+                const cost = (uncached / 1_000_000) * CODEX_PRICING.inputPer1M
+                    + (cached / 1_000_000) * CODEX_PRICING.cachedInputPer1M
+                    + (output / 1_000_000) * CODEX_PRICING.outputPer1M;
+                usageData = { inputTokens: input, cachedInputTokens: cached, outputTokens: output, costUsd: cost };
+            }
+            if (event.type === 'turn.failed') {
+                errorMessage = event.error.message ?? 'Codex turn failed';
+                exitCode = 1;
+                throw new Error(errorMessage);
+            }
+            if (event.type === 'error') {
+                errorMessage = event.message ?? 'Codex stream error';
+                exitCode = 1;
+                throw new Error(errorMessage);
+            }
+        }
+        // Write output file
+        if (outputPath) {
+            const outputDir = path.dirname(outputPath);
+            if (!fs.existsSync(outputDir))
+                fs.mkdirSync(outputDir, { recursive: true });
+            fs.writeFileSync(outputPath, chunks.join(''));
+            console.error(`\nOutput written to: ${outputPath}`);
+        }
+    }
+    catch (err) {
+        if (!errorMessage) {
+            errorMessage = (err instanceof Error ? err.message : String(err)).substring(0, 500);
+            exitCode = 1;
+        }
+        throw err;
+    }
+    finally {
+        // Clean up temp file
+        if (fs.existsSync(tempFile))
+            fs.unlinkSync(tempFile);
+        // Record metrics (always, even on error)
+        if (metricsCtx) {
+            const duration = (Date.now() - startTime) / 1000;
+            recordMetrics(metricsCtx, {
+                durationSeconds: duration,
+                inputTokens: usageData?.inputTokens ?? null,
+                cachedInputTokens: usageData?.cachedInputTokens ?? null,
+                outputTokens: usageData?.outputTokens ?? null,
+                costUsd: usageData?.costUsd ?? null,
+                exitCode,
+                errorMessage,
+            });
+        }
+    }
+}
 /**
  * Run Claude consultation via Agent SDK.
  * Uses the SDK's query() function instead of CLI subprocess.
  * This avoids the CLAUDECODE nesting guard and enables tool use during reviews.
  */
-async function runClaudeConsultation(queryText, role, workspaceRoot, outputPath) {
+async function runClaudeConsultation(queryText, role, workspaceRoot, outputPath, metricsCtx) {
     const chunks = [];
+    const startTime = Date.now();
+    let sdkResult;
+    let errorMessage = null;
+    let exitCode = 0;
     // The SDK spawns a Claude Code subprocess that checks process.env.CLAUDECODE.
     // We must remove it from process.env (not just the options env) to avoid
     // the nesting guard. Restore it after the SDK call.
@@ -254,9 +376,14 @@ async function runClaudeConsultation(queryText, role, workspaceRoot, outputPath)
                 }
             }
             if (message.type === 'result') {
-                if (message.subtype !== 'success') {
+                if (message.subtype === 'success') {
+                    sdkResult = message;
+                }
+                else {
                     const errors = 'errors' in message ? message.errors : [];
-                    throw new Error(`Claude SDK error (${message.subtype}): ${errors.join(', ')}`);
+                    errorMessage = `Claude SDK error (${message.subtype}): ${errors.join(', ')}`.substring(0, 500);
+                    exitCode = 1;
+                    throw new Error(errorMessage);
                 }
             }
         }
@@ -268,43 +395,49 @@ async function runClaudeConsultation(queryText, role, workspaceRoot, outputPath)
             console.error(`\nOutput written to: ${outputPath}`);
         }
     }
+    catch (err) {
+        if (!errorMessage) {
+            errorMessage = (err instanceof Error ? err.message : String(err)).substring(0, 500);
+            exitCode = 1;
+        }
+        throw err;
+    }
     finally {
         if (savedClaudeCode !== undefined) {
             process.env.CLAUDECODE = savedClaudeCode;
         }
+        // Record metrics (always, even on error)
+        if (metricsCtx) {
+            const duration = (Date.now() - startTime) / 1000;
+            const usage = sdkResult ? extractUsage('claude', '', sdkResult) : null;
+            recordMetrics(metricsCtx, {
+                durationSeconds: duration,
+                inputTokens: usage?.inputTokens ?? null,
+                cachedInputTokens: usage?.cachedInputTokens ?? null,
+                outputTokens: usage?.outputTokens ?? null,
+                costUsd: usage?.costUsd ?? null,
+                exitCode,
+                errorMessage,
+            });
+        }
     }
 }
 /**
- * Run the consultation
+ * Run the consultation — dispatches to the correct model runner.
  */
-async function runConsultation(model, query, workspaceRoot, dryRun, reviewType, customRole, outputPath) {
-    // Use custom role if specified, otherwise use default consultant role
-    let role = customRole ? loadCustomRole(workspaceRoot, customRole) : loadRole(workspaceRoot);
-    // Append review type prompt if specified
-    if (reviewType) {
-        const typePrompt = loadReviewTypePrompt(workspaceRoot, reviewType);
-        if (typePrompt) {
-            role = role + '\n\n---\n\n' + typePrompt;
-            console.error(`Review type: ${reviewType}`);
-        }
-        else {
-            console.error(chalk.yellow(`Warning: Review type prompt not found: ${reviewType}`));
-        }
-    }
-    // Claude uses the Agent SDK — handle separately from CLI-based models
+async function runConsultation(model, query, workspaceRoot, role, outputPath, metricsCtx, generalMode) {
+    // SDK-based models
     if (model === 'claude') {
-        if (dryRun) {
-            console.log(chalk.yellow(`[claude] Would invoke Agent SDK:`));
-            console.log(`  Model: claude-opus-4-6`);
-            console.log(`  Tools: Read, Glob, Grep`);
-            console.log(`  Max turns: ${CLAUDE_MAX_TURNS}`);
-            console.log(`  Max budget: $25.00`);
-            const promptPreview = query.substring(0, 200) + (query.length > 200 ? '...' : '');
-            console.log(`  Prompt: ${promptPreview}`);
-            return;
-        }
         const startTime = Date.now();
-        await runClaudeConsultation(query, role, workspaceRoot, outputPath);
+        await runClaudeConsultation(query, role, workspaceRoot, outputPath, metricsCtx);
+        const duration = (Date.now() - startTime) / 1000;
+        logQuery(workspaceRoot, model, query, duration);
+        console.error(`\n[${model} completed in ${duration.toFixed(1)}s]`);
+        return;
+    }
+    if (model === 'codex') {
+        const startTime = Date.now();
+        await runCodexConsultation(query, role, workspaceRoot, outputPath, metricsCtx);
         const duration = (Date.now() - startTime) / 1000;
         logQuery(workspaceRoot, model, query, duration);
         console.error(`\n[${model} completed in ${duration.toFixed(1)}s]`);
@@ -314,74 +447,41 @@ async function runConsultation(model, query, workspaceRoot, dryRun, reviewType,
     if (!config) {
         throw new Error(`Unknown model: ${model}`);
     }
-    // Check if CLI exists (skip for dry-run mode)
-    if (!dryRun && !commandExists(config.cli)) {
+    // Check if CLI exists
+    if (!commandExists(config.cli)) {
         throw new Error(`${config.cli} not found. Please install it first.`);
     }
     let tempFile = null;
     const env = {};
-    // Prepare command and environment based on model
     let cmd;
     if (model === 'gemini') {
         // Gemini uses GEMINI_SYSTEM_MD env var for role
         tempFile = path.join(tmpdir(), `codev-role-${Date.now()}.md`);
         fs.writeFileSync(tempFile, role);
         env['GEMINI_SYSTEM_MD'] = tempFile;
-        cmd = [config.cli, ...config.args, query];
-    }
-    else if (model === 'codex') {
-        // Codex uses experimental_instructions_file config flag (not env var)
-        // This is the official approach per https://github.com/openai/codex/discussions/3896
-        tempFile = path.join(tmpdir(), `codev-role-${Date.now()}.md`);
-        fs.writeFileSync(tempFile, role);
-        cmd = [
-            config.cli,
-            'exec',
-            '-c', `experimental_instructions_file=${tempFile}`,
-            '-c', 'model_reasoning_effort=medium', // Balance speed vs review quality
-            '-c', 'sandbox=read-only', // Consult is read-only — no test execution
-            '--full-auto',
-            query,
-        ];
+        // Use --output-format json to capture token usage/cost in structured output.
+        // Only use --yolo in protocol mode (structured reviews).
+        // General mode must NOT use --yolo to prevent unintended file writes (#370).
+        const yoloArgs = generalMode ? [] : ['--yolo'];
+        cmd = [config.cli, ...yoloArgs, '--output-format', 'json', ...config.args, query];
     }
     else {
         throw new Error(`Unknown model: ${model}`);
     }
-    if (dryRun) {
-        console.log(chalk.yellow(`[${model}] Would execute:`));
-        console.log(`  Command: ${cmd.join(' ')}`);
-        if (Object.keys(env).length > 0) {
-            for (const [key, value] of Object.entries(env)) {
-                if (key === 'GEMINI_SYSTEM_MD') {
-                    console.log(`  Env: ${key}=<temp file with consultant role>`);
-                }
-                else {
-                    const preview = value.substring(0, 50) + (value.length > 50 ? '...' : '');
-                    console.log(`  Env: ${key}=${preview}`);
-                }
-            }
-        }
-        if (tempFile)
-            fs.unlinkSync(tempFile);
-        return;
-    }
     // Execute with passthrough stdio
     // Use 'ignore' for stdin to prevent blocking when spawned as subprocess
-    // When outputPath is set, capture stdout to write to file (used by porch)
     const fullEnv = { ...process.env, ...env };
     const startTime = Date.now();
-    const stdoutMode = outputPath ? 'pipe' : 'inherit';
     return new Promise((resolve, reject) => {
         const proc = spawn(cmd[0], cmd.slice(1), {
+            cwd: workspaceRoot,
             env: fullEnv,
-            stdio: ['ignore', stdoutMode, 'inherit'],
+            stdio: ['ignore', 'pipe', 'inherit'],
         });
         const chunks = [];
-        if (outputPath && proc.stdout) {
+        if (proc.stdout) {
             proc.stdout.on('data', (chunk) => {
                 chunks.push(chunk);
-                // Also write to stdout so the user can still see output
-                process.stdout.write(chunk);
             });
         }
         proc.on('close', (code) => {
@@ -390,15 +490,34 @@ async function runConsultation(model, query, workspaceRoot, dryRun, reviewType,
             if (tempFile && fs.existsSync(tempFile)) {
                 fs.unlinkSync(tempFile);
             }
-            // Write captured output to file
-            if (outputPath && chunks.length > 0) {
+            const rawOutput = Buffer.concat(chunks).toString('utf-8');
+            // Extract review text from structured output (JSON/JSONL → plain text)
+            const reviewText = extractReviewText(model, rawOutput);
+            const outputContent = reviewText ?? rawOutput; // Fallback to raw on parse failure
+            // Write text to stdout (was fully buffered)
+            process.stdout.write(outputContent);
+            // Write to output file
+            if (outputPath && outputContent.length > 0) {
                 const outputDir = path.dirname(outputPath);
                 if (!fs.existsSync(outputDir)) {
                     fs.mkdirSync(outputDir, { recursive: true });
                 }
-                fs.writeFileSync(outputPath, Buffer.concat(chunks).toString('utf-8'));
+                fs.writeFileSync(outputPath, outputContent);
                 console.error(`\nOutput written to: ${outputPath}`);
             }
+            // Record metrics
+            if (metricsCtx) {
+                const usage = extractUsage(model, rawOutput);
+                recordMetrics(metricsCtx, {
+                    durationSeconds: duration,
+                    inputTokens: usage?.inputTokens ?? null,
+                    cachedInputTokens: usage?.cachedInputTokens ?? null,
+                    outputTokens: usage?.outputTokens ?? null,
+                    costUsd: usage?.costUsd ?? null,
+                    exitCode: code ?? 1,
+                    errorMessage: code !== 0 ? `Process exited with code ${code}` : null,
+                });
+            }
             console.error(`\n[${model} completed in ${duration.toFixed(1)}s]`);
             if (code !== 0) {
                 reject(new Error(`Process exited with code ${code}`));
@@ -411,13 +530,25 @@ async function runConsultation(model, query, workspaceRoot, dryRun, reviewType,
             if (tempFile && fs.existsSync(tempFile)) {
                 fs.unlinkSync(tempFile);
             }
+            // Record metrics for spawn failures
+            if (metricsCtx) {
+                const duration = (Date.now() - startTime) / 1000;
+                recordMetrics(metricsCtx, {
+                    durationSeconds: duration,
+                    inputTokens: null,
+                    cachedInputTokens: null,
+                    outputTokens: null,
+                    costUsd: null,
+                    exitCode: 1,
+                    errorMessage: (error.message || String(error)).substring(0, 500),
+                });
+            }
             reject(error);
         });
     });
 }
 /**
  * Get a compact diff stat summary and list of changed files.
- * Returns { stat, files } where stat is the `--stat` output and files is the list of paths.
  */
 function getDiffStat(workspaceRoot, ref) {
     const stat = execSync(`git diff --stat ${ref}`, { cwd: workspaceRoot, encoding: 'utf-8' }).toString();
@@ -426,7 +557,7 @@ function getDiffStat(workspaceRoot, ref) {
     return { stat, files };
 }
 /**
- * Fetch PR metadata (no diff — reviewers read files from disk)
+ * Fetch PR metadata (no diff — that's fetched separately)
  */
 function fetchPRData(prNumber) {
     console.error(`Fetching PR #${prNumber} data...`);
@@ -447,12 +578,24 @@ function fetchPRData(prNumber) {
         throw new Error(`Failed to fetch PR data: ${err}`);
     }
 }
+/**
+ * Fetch the full PR diff via gh pr diff
+ */
+function fetchPRDiff(prNumber) {
+    try {
+        return execSync(`gh pr diff ${prNumber}`, { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
+    }
+    catch (err) {
+        throw new Error(`Failed to fetch PR diff for #${prNumber}: ${err}`);
+    }
+}
 /**
  * Build query for PR review.
- * Provides file list and instructs reviewers to read files from disk.
+ * Includes full PR diff + file list; model reads surrounding context from disk.
  */
-function buildPRQuery(prNumber, _workspaceRoot) {
+function buildPRQuery(prNumber) {
     const prData = fetchPRData(prNumber);
+    const diff = fetchPRDiff(prNumber);
     const fileList = prData.changedFiles.map(f => `- ${f}`).join('\n');
     return `Review Pull Request #${prNumber}
 
@@ -464,10 +607,13 @@ ${prData.info}
 ## Changed Files
 ${fileList}
 
+## PR Diff
+\`\`\`diff
+${diff}
+\`\`\`
+
 ## How to Review
-**Read the changed files from disk** to review their current content. You have full filesystem access.
-For each changed file listed above, read it and evaluate the code quality, correctness, and test coverage.
-Use \`git diff HEAD~1 -- <file>\` or \`git log -p -- <file>\` if you need to see what specifically changed.
+Review the PR diff above for the changes. You also have **full filesystem access** — read files from disk for surrounding context beyond what the diff shows.
 
 ## Comments
 ${prData.comments}
@@ -505,6 +651,11 @@ Please read and review this specification:
         query += `- Plan file: ${planPath}\n`;
     }
     query += `
+## How to Review
+**Read the files listed above directly from disk.** You have full filesystem access.
+Do NOT rely on \`git diff\` or \`git log\` to review content — diffs may be truncated or miss uncommitted work.
+Open the spec file, read it in full, and evaluate it directly.
+
 Please review:
 1. Clarity and completeness of requirements
 2. Technical feasibility
@@ -526,24 +677,22 @@ KEY_ISSUES: [List of critical issues if any, or "None"]`;
 }
 /**
  * Build query for implementation review.
- * Provides diff stat + file list and instructs reviewers to read files from disk.
+ * Accepts spec/plan paths and optional diff reference override.
  */
-function buildImplQuery(projectNumber, workspaceRoot, planPhase) {
-    const specPath = findSpec(workspaceRoot, projectNumber);
-    const planPath = findPlan(workspaceRoot, projectNumber);
-    // Get compact diff summary against base branch
+function buildImplQuery(workspaceRoot, specPath, planPath, planPhase, diffRef) {
+    // Get compact diff summary
     let diffStat = '';
     let changedFiles = [];
     try {
-        const mergeBase = execSync('git merge-base HEAD main', { cwd: workspaceRoot, encoding: 'utf-8' }).trim();
-        const result = getDiffStat(workspaceRoot, `${mergeBase}..HEAD`);
+        const ref = diffRef ?? execSync('git merge-base HEAD main', { cwd: workspaceRoot, encoding: 'utf-8' }).trim();
+        const result = getDiffStat(workspaceRoot, ref);
         diffStat = result.stat;
         changedFiles = result.files;
     }
     catch {
         // If git diff fails, reviewer will explore filesystem
     }
-    let query = `Review Implementation for Project ${projectNumber}`;
+    let query = `Review Implementation`;
     if (planPhase) {
         query += ` — Phase: ${planPhase}`;
     }
@@ -570,7 +719,7 @@ function buildImplQuery(projectNumber, workspaceRoot, planPhase) {
         query += `\n\n## How to Review\n`;
         query += `**Read the changed files from disk** to review their actual content. You have full filesystem access.\n`;
         query += `For each file listed above, read it and evaluate the implementation against the spec/plan.\n`;
-        query += `Use \`git diff main -- <file>\` if you need to see what specifically changed in a file.\n`;
+        query += `Do NOT rely on git diffs to determine the current state of code — diffs miss uncommitted changes in worktrees.\n`;
     }
     else {
         query += `\n## Instructions\n\nRead the spec and plan files above, then explore the filesystem to find and review the implementation changes.\n`;
@@ -607,6 +756,11 @@ Please read and review this implementation plan:
         query += `- Spec file: ${specPath} (for context)\n`;
     }
     query += `
+## How to Review
+**Read the files listed above directly from disk.** You have full filesystem access.
+Do NOT rely on \`git diff\` or \`git log\` to review content — diffs may be truncated or miss uncommitted work.
+Open the plan file (and spec if provided), read them in full, and evaluate the plan directly.
+
 Please review:
 1. Alignment with specification requirements
 2. Implementation approach and architecture
@@ -627,109 +781,304 @@ KEY_ISSUES: [List of critical issues if any, or "None"]`;
     return query;
 }
 /**
- * Main consult entry point
+ * Build query for phase-scoped review.
+ * Uses git show HEAD for the phase's atomic commit diff.
  */
-export async function consult(options) {
-    const { model: modelInput, subcommand, args, dryRun = false, reviewType, role: customRole, output: outputPath } = options;
-    // Resolve model alias
-    const model = MODEL_ALIASES[modelInput.toLowerCase()] || modelInput.toLowerCase();
-    // Validate model
-    if (!MODEL_CONFIGS[model] && !SDK_MODELS.includes(model)) {
-        const validModels = [...Object.keys(MODEL_CONFIGS), ...SDK_MODELS, ...Object.keys(MODEL_ALIASES)];
-        throw new Error(`Unknown model: ${modelInput}\nValid models: ${validModels.join(', ')}`);
+function buildPhaseQuery(workspaceRoot, planPhase, specPath, planPath) {
+    let phaseDiff = '';
+    try {
+        phaseDiff = execSync('git show HEAD', { cwd: workspaceRoot, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
+    }
+    catch {
+        // If git show fails, reviewer explores filesystem
     }
-    // Validate review type if provided
-    if (reviewType && !VALID_REVIEW_TYPES.includes(reviewType)) {
-        throw new Error(`Invalid review type: ${reviewType}\nValid types: ${VALID_REVIEW_TYPES.join(', ')}`);
+    let query = `Review Phase Implementation: "${planPhase}"\n\n## Context Files\n`;
+    if (specPath)
+        query += `- Spec: ${specPath}\n`;
+    if (planPath)
+        query += `- Plan: ${planPath}\n`;
+    query += `
+## REVIEW SCOPE — CURRENT PLAN PHASE ONLY
+You are reviewing **plan phase "${planPhase}" ONLY**.
+Read the plan, find the section for "${planPhase}", and scope your review to ONLY the work described in that phase.
+
+**DO NOT** request changes for work that belongs to other plan phases.
+**DO NOT** flag missing functionality that is scheduled for a later phase.
+**DO** verify that this phase's deliverables are complete and correct.
+
+## Phase Commit Diff
+\`\`\`
+${phaseDiff}
+\`\`\`
+
+## How to Review
+The diff above shows the atomic commit for this phase. You also have **full filesystem access** — read files from disk to understand surrounding code.
+
+Please review:
+1. **Spec Adherence**: Does the code fulfill the spec requirements for this phase?
+2. **Code Quality**: Is the code readable, maintainable, and bug-free?
+3. **Test Coverage**: Are there adequate tests for the changes in this phase?
+4. **Error Handling**: Are edge cases and errors handled properly?
+5. **Plan Alignment**: Does the implementation follow the plan for phase "${planPhase}"?
+
+End your review with a verdict in this EXACT format:
+
+---
+VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
+SUMMARY: [One-line summary of your review]
+CONFIDENCE: [HIGH | MEDIUM | LOW]
+---
+
+KEY_ISSUES: [List of critical issues if any, or "None"]`;
+    return query;
+}
+/**
+ * Find PR number for the current branch
+ */
+function findPRForCurrentBranch(workspaceRoot) {
+    const branchName = execSync('git branch --show-current', { cwd: workspaceRoot, encoding: 'utf-8' }).trim();
+    const prJson = execSync(`gh pr list --head "${branchName}" --json number --jq '.[0].number'`, { cwd: workspaceRoot, encoding: 'utf-8' }).trim();
+    if (!prJson) {
+        throw new Error(`No PR found for branch: ${branchName}`);
     }
-    const workspaceRoot = findWorkspaceRoot();
-    loadDotenv(workspaceRoot);
-    console.error(`[${subcommand} review]`);
-    console.error(`Model: ${model}`);
-    // Log custom role if specified
-    if (customRole) {
-        console.error(`Role: ${customRole}`);
+    const prNumber = parseInt(prJson, 10);
+    if (isNaN(prNumber)) {
+        throw new Error(`No PR found for branch: ${branchName}`);
     }
-    let query;
-    switch (subcommand.toLowerCase()) {
+    return prNumber;
+}
+/**
+ * Find PR number for a given issue number (architect mode)
+ */
+function findPRForIssue(workspaceRoot, issueNumber) {
+    const prJson = execSync(`gh pr list --search "${issueNumber}" --json number,headRefName --jq '.[0]'`, { cwd: workspaceRoot, encoding: 'utf-8' }).trim();
+    if (!prJson || prJson === 'null') {
+        throw new Error(`No PR found for issue #${issueNumber}`);
+    }
+    return JSON.parse(prJson);
+}
+/**
+ * Resolve query for builder context (auto-detected from porch state)
+ */
+function resolveBuilderQuery(workspaceRoot, type, options) {
+    const projectState = getBuilderProjectState(workspaceRoot);
+    const projectNumber = parseInt(projectState.id, 10);
+    switch (type) {
+        case 'spec': {
+            const specPath = findSpec(workspaceRoot, projectNumber);
+            if (!specPath)
+                throw new Error(`Spec ${projectState.id} not found in codev/specs/`);
+            const planPath = findPlan(workspaceRoot, projectNumber);
+            console.error(`Spec: ${specPath}`);
+            if (planPath)
+                console.error(`Plan: ${planPath}`);
+            return buildSpecQuery(specPath, planPath);
+        }
+        case 'plan': {
+            const planPath = findPlan(workspaceRoot, projectNumber);
+            if (!planPath)
+                throw new Error(`Plan ${projectState.id} not found in codev/plans/`);
+            const specPath = findSpec(workspaceRoot, projectNumber);
+            console.error(`Plan: ${planPath}`);
+            if (specPath)
+                console.error(`Spec: ${specPath}`);
+            return buildPlanQuery(planPath, specPath);
+        }
+        case 'impl': {
+            const specPath = findSpec(workspaceRoot, projectNumber);
+            const planPath = findPlan(workspaceRoot, projectNumber);
+            console.error(`Project: ${projectState.id}`);
+            if (specPath)
+                console.error(`Spec: ${specPath}`);
+            if (planPath)
+                console.error(`Plan: ${planPath}`);
+            if (options.planPhase)
+                console.error(`Plan phase: ${options.planPhase}`);
+            return buildImplQuery(workspaceRoot, specPath, planPath, options.planPhase);
+        }
         case 'pr': {
-            if (args.length === 0) {
-                throw new Error('PR number required\nUsage: consult -m <model> pr <number>');
-            }
-            const prNumber = parseInt(args[0], 10);
-            if (isNaN(prNumber)) {
-                throw new Error(`Invalid PR number: ${args[0]}`);
+            const prNumber = findPRForCurrentBranch(workspaceRoot);
+            console.error(`PR: #${prNumber}`);
+            return buildPRQuery(prNumber);
+        }
+        case 'phase': {
+            const currentPhase = options.planPhase ?? projectState.currentPlanPhase;
+            if (!currentPhase) {
+                throw new Error('No current plan phase detected. Use --plan-phase to specify.');
             }
-            query = buildPRQuery(prNumber, workspaceRoot);
-            break;
+            const specPath = findSpec(workspaceRoot, projectNumber);
+            const planPath = findPlan(workspaceRoot, projectNumber);
+            console.error(`Phase: ${currentPhase}`);
+            if (specPath)
+                console.error(`Spec: ${specPath}`);
+            if (planPath)
+                console.error(`Plan: ${planPath}`);
+            return buildPhaseQuery(workspaceRoot, currentPhase, specPath, planPath);
+        }
+        case 'integration': {
+            const prNumber = findPRForCurrentBranch(workspaceRoot);
+            console.error(`PR: #${prNumber} (integration review)`);
+            return buildPRQuery(prNumber);
         }
+        default:
+            throw new Error(`Unknown review type: ${type}\nValid types: spec, plan, impl, pr, phase, integration`);
+    }
+}
+/**
+ * Resolve query for architect context (requires --issue)
+ */
+function resolveArchitectQuery(workspaceRoot, type, options) {
+    if (type === 'phase') {
+        throw new Error('--type phase requires a builder worktree. Phases only exist in builders and require the phase commit to exist.');
+    }
+    if (!options.issue) {
+        throw new Error(`--issue is required from architect context for --type ${type}.\n` +
+            `Example: consult -m gemini --protocol spir --type ${type} --issue 42`);
+    }
+    const issueNumber = parseInt(options.issue, 10);
+    if (isNaN(issueNumber)) {
+        throw new Error(`Invalid issue number: ${options.issue}`);
+    }
+    switch (type) {
         case 'spec': {
-            if (args.length === 0) {
-                throw new Error('Spec number required\nUsage: consult -m <model> spec <number>');
-            }
-            const specNumber = parseInt(args[0], 10);
-            if (isNaN(specNumber)) {
-                throw new Error(`Invalid spec number: ${args[0]}`);
-            }
-            const specPath = findSpec(workspaceRoot, specNumber);
-            if (!specPath) {
-                throw new Error(`Spec ${specNumber} not found`);
-            }
-            const planPath = findPlan(workspaceRoot, specNumber);
-            query = buildSpecQuery(specPath, planPath);
+            const specPath = findSpec(workspaceRoot, issueNumber);
+            if (!specPath)
+                throw new Error(`Spec ${issueNumber} not found in codev/specs/`);
+            const planPath = findPlan(workspaceRoot, issueNumber);
             console.error(`Spec: ${specPath}`);
             if (planPath)
                 console.error(`Plan: ${planPath}`);
-            break;
+            return buildSpecQuery(specPath, planPath);
         }
         case 'plan': {
-            if (args.length === 0) {
-                throw new Error('Plan number required\nUsage: consult -m <model> plan <number>');
-            }
-            const planNumber = parseInt(args[0], 10);
-            if (isNaN(planNumber)) {
-                throw new Error(`Invalid plan number: ${args[0]}`);
-            }
-            const planPath = findPlan(workspaceRoot, planNumber);
-            if (!planPath) {
-                throw new Error(`Plan ${planNumber} not found`);
-            }
-            const specPath = findSpec(workspaceRoot, planNumber);
-            query = buildPlanQuery(planPath, specPath);
+            const planPath = findPlan(workspaceRoot, issueNumber);
+            if (!planPath)
+                throw new Error(`Plan ${issueNumber} not found in codev/plans/`);
+            const specPath = findSpec(workspaceRoot, issueNumber);
             console.error(`Plan: ${planPath}`);
             if (specPath)
                 console.error(`Spec: ${specPath}`);
-            break;
-        }
-        case 'general': {
-            if (args.length === 0) {
-                throw new Error('Query required\nUsage: consult -m <model> general "<query>"');
-            }
-            query = args.join(' ');
-            break;
+            return buildPlanQuery(planPath, specPath);
         }
         case 'impl': {
-            if (args.length === 0) {
-                throw new Error('Project number required\nUsage: consult -m <model> impl <number>');
+            const pr = findPRForIssue(workspaceRoot, issueNumber);
+            // Fetch the branch and diff from merge-base
+            try {
+                execSync(`git fetch origin ${pr.headRefName}`, { cwd: workspaceRoot, stdio: 'pipe' });
             }
-            const implNumber = parseInt(args[0], 10);
-            if (isNaN(implNumber)) {
-                throw new Error(`Invalid project number: ${args[0]}`);
+            catch {
+                // May already be fetched
             }
-            const specPath = findSpec(workspaceRoot, implNumber);
-            const planPath = findPlan(workspaceRoot, implNumber);
-            query = buildImplQuery(implNumber, workspaceRoot, options.planPhase);
-            console.error(`Project: ${implNumber}`);
+            const mergeBase = execSync(`git merge-base main origin/${pr.headRefName}`, { cwd: workspaceRoot, encoding: 'utf-8' }).trim();
+            const specPath = findSpec(workspaceRoot, issueNumber);
+            const planPath = findPlan(workspaceRoot, issueNumber);
+            console.error(`Project: ${issueNumber} (PR #${pr.number}, branch: ${pr.headRefName})`);
             if (specPath)
                 console.error(`Spec: ${specPath}`);
             if (planPath)
                 console.error(`Plan: ${planPath}`);
-            if (options.planPhase)
-                console.error(`Plan phase: ${options.planPhase}`);
-            break;
+            return buildImplQuery(workspaceRoot, specPath, planPath, options.planPhase, `${mergeBase}..origin/${pr.headRefName}`);
+        }
+        case 'pr': {
+            const pr = findPRForIssue(workspaceRoot, issueNumber);
+            console.error(`PR: #${pr.number}`);
+            return buildPRQuery(pr.number);
+        }
+        case 'integration': {
+            const pr = findPRForIssue(workspaceRoot, issueNumber);
+            console.error(`PR: #${pr.number} (integration review)`);
+            return buildPRQuery(pr.number);
         }
         default:
-            throw new Error(`Unknown subcommand: ${subcommand}\nValid subcommands: pr, spec, plan, impl, general`);
+            throw new Error(`Unknown review type: ${type}\nValid types: spec, plan, impl, pr, phase, integration`);
+    }
+}
+/**
+ * Main consult entry point
+ */
+export async function consult(options) {
+    const hasPrompt = !!options.prompt || !!options.promptFile;
+    const hasType = !!options.type;
+    // --- Input validation ---
+    // Mode conflict: --prompt/--prompt-file + --type
+    if (hasPrompt && hasType) {
+        throw new Error('Mode conflict: cannot use --prompt/--prompt-file with --type.\n' +
+            'Use --prompt or --prompt-file for general queries.\n' +
+            'Use --type (with optional --protocol) for protocol reviews.');
+    }
+    // --prompt + --prompt-file together
+    if (options.prompt && options.promptFile) {
+        throw new Error('Cannot use both --prompt and --prompt-file. Choose one.');
+    }
+    // --protocol without --type
+    if (options.protocol && !options.type) {
+        throw new Error('--protocol requires --type. Example: consult -m gemini --protocol spir --type spec');
+    }
+    // Neither mode specified
+    if (!hasPrompt && !hasType) {
+        throw new Error('No mode specified.\n' +
+            'General mode: consult -m <model> --prompt "question"\n' +
+            'Protocol mode: consult -m <model> --protocol <name> --type <type>\n' +
+            'Stats mode: consult stats');
+    }
+    // Validate --protocol and --type for path traversal
+    if (options.protocol && !isValidRoleName(options.protocol)) {
+        throw new Error(`Invalid protocol name: '${options.protocol}'. Only alphanumeric characters, hyphens, and underscores allowed.`);
+    }
+    if (options.type && !isValidRoleName(options.type)) {
+        throw new Error(`Invalid type name: '${options.type}'. Only alphanumeric characters, hyphens, and underscores allowed.`);
+    }
+    // --- Resolve model ---
+    const model = MODEL_ALIASES[options.model.toLowerCase()] || options.model.toLowerCase();
+    if (!MODEL_CONFIGS[model] && !SDK_MODELS.includes(model)) {
+        const validModels = [...Object.keys(MODEL_CONFIGS), ...SDK_MODELS, ...Object.keys(MODEL_ALIASES)];
+        throw new Error(`Unknown model: ${options.model}\nValid models: ${validModels.join(', ')}`);
+    }
+    // --- Setup ---
+    const workspaceRoot = findWorkspaceRoot();
+    loadDotenv(workspaceRoot);
+    const timestamp = new Date().toISOString();
+    const metricsCtx = {
+        timestamp,
+        model,
+        reviewType: options.type ?? null,
+        subcommand: options.type ?? 'general',
+        protocol: options.protocol ?? 'manual',
+        projectId: options.projectId ?? null,
+        workspacePath: workspaceRoot,
+    };
+    console.error(`Model: ${model}`);
+    let query;
+    let role = loadRole(workspaceRoot);
+    // --- Build query based on mode ---
+    if (hasType) {
+        // Protocol mode
+        const type = options.type;
+        // Load and append protocol prompt template
+        const promptTemplate = resolveProtocolPrompt(workspaceRoot, options.protocol, type);
+        role = role + '\n\n---\n\n' + promptTemplate;
+        console.error(`Review type: ${type}${options.protocol ? ` (protocol: ${options.protocol})` : ''}`);
+        // Determine context: builder (auto-detect) vs architect (--issue or not in builder)
+        const inBuilder = isBuilderContext() && !options.issue;
+        if (inBuilder) {
+            query = resolveBuilderQuery(workspaceRoot, type, options);
+        }
+        else {
+            query = resolveArchitectQuery(workspaceRoot, type, options);
+        }
+    }
+    else {
+        // General mode
+        if (options.prompt) {
+            query = options.prompt;
+        }
+        else {
+            const filePath = options.promptFile;
+            if (!fs.existsSync(filePath)) {
+                throw new Error(`Prompt file not found: ${filePath}`);
+            }
+            query = fs.readFileSync(filePath, 'utf-8');
+        }
     }
     // Prepend iteration context if provided (for stateful reviews)
     if (options.context) {
@@ -742,6 +1091,10 @@ export async function consult(options) {
             console.error(chalk.yellow(`Warning: Could not read context file: ${options.context}`));
         }
     }
+    // Add file access instruction for Gemini
+    if (model === 'gemini') {
+        query += '\n\nYou have file access. Read files directly from disk to review code.';
+    }
     // Show the query/prompt being sent
     console.error('');
     console.error('='.repeat(60));
@@ -753,8 +1106,9 @@ export async function consult(options) {
     console.error(`[${model.toUpperCase()}] Starting consultation...`);
     console.error('='.repeat(60));
     console.error('');
-    await runConsultation(model, query, workspaceRoot, dryRun, reviewType, customRole, outputPath);
+    const isGeneralMode = !hasType;
+    await runConsultation(model, query, workspaceRoot, role, options.output, metricsCtx, isGeneralMode);
 }
 // Exported for testing
-export { getDiffStat as _getDiffStat };
+export { getDiffStat as _getDiffStat, buildSpecQuery as _buildSpecQuery, buildPlanQuery as _buildPlanQuery };
 //# sourceMappingURL=index.js.map