@cluesmith/codev 2.0.2 → 2.0.6

package/dist/commands/consult/index.js

@@ -9,15 +9,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, findProjectRoot, hasLocalOverride } from '../../lib/skeleton.js';
+import { Codex } from '@openai/codex-sdk';
+import { readCodevFile, findWorkspaceRoot, hasLocalOverride } 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 },
 };
-// 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,6 +27,36 @@ const MODEL_ALIASES = {
     gpt: 'codex',
     opus: 'claude',
 };
+// 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)}`);
+    }
+}
 // Valid review types
 const VALID_REVIEW_TYPES = [
     'spec-review',
@@ -46,8 +76,8 @@ function isValidRoleName(roleName) {
  * List available roles in codev/roles/
  * Excludes non-role files like README.md, review-types/, etc.
  */
-function listAvailableRoles(projectRoot) {
-    const rolesDir = path.join(projectRoot, 'codev', 'roles');
+function listAvailableRoles(workspaceRoot) {
+    const rolesDir = path.join(workspaceRoot, 'codev', 'roles');
     if (!fs.existsSync(rolesDir))
         return [];
     const excludePatterns = ['readme', 'review-types', 'overview', 'index'];
@@ -64,7 +94,7 @@ function listAvailableRoles(projectRoot) {
  * Load a custom role from codev/roles/<name>.md
  * Falls back to embedded skeleton if not found locally.
  */
-function loadCustomRole(projectRoot, roleName) {
+function loadCustomRole(workspaceRoot, roleName) {
     // Validate role name to prevent directory traversal
     if (!isValidRoleName(roleName)) {
         throw new Error(`Invalid role name: '${roleName}'\n` +
@@ -72,9 +102,9 @@ function loadCustomRole(projectRoot, roleName) {
     }
     // Use readCodevFile which handles local-first with skeleton fallback
     const rolePath = `roles/${roleName}.md`;
-    const roleContent = readCodevFile(rolePath, projectRoot);
+    const roleContent = readCodevFile(rolePath, workspaceRoot);
     if (!roleContent) {
-        const available = listAvailableRoles(projectRoot);
+        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/';
@@ -86,8 +116,8 @@ function loadCustomRole(projectRoot, roleName) {
  * Load the consultant role.
  * Checks local codev/roles/consultant.md first, then falls back to embedded skeleton.
  */
-function loadRole(projectRoot) {
-    const role = readCodevFile('roles/consultant.md', projectRoot);
+function loadRole(workspaceRoot) {
+    const role = readCodevFile('roles/consultant.md', workspaceRoot);
     if (!role) {
         throw new Error('consultant.md not found.\n' +
             'Checked: local codev/roles/consultant.md and embedded skeleton.\n' +
@@ -100,21 +130,21 @@ function loadRole(projectRoot) {
  * Checks consult-types/{type}.md first (new location),
  * then falls back to roles/review-types/{type}.md (deprecated) with a warning.
  */
-function loadReviewTypePrompt(projectRoot, reviewType) {
+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, projectRoot)) {
-        return readCodevFile(primaryPath, projectRoot);
+    if (hasLocalOverride(primaryPath, workspaceRoot)) {
+        return readCodevFile(primaryPath, workspaceRoot);
     }
     // 2. Check LOCAL roles/review-types/ (deprecated location with warning)
-    if (hasLocalOverride(fallbackPath, projectRoot)) {
+    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, projectRoot);
+        return readCodevFile(fallbackPath, workspaceRoot);
     }
     // 3. Fall back to embedded skeleton consult-types/ (default)
-    const skeletonPrompt = readCodevFile(primaryPath, projectRoot);
+    const skeletonPrompt = readCodevFile(primaryPath, workspaceRoot);
     if (skeletonPrompt) {
         return skeletonPrompt;
     }
@@ -123,8 +153,8 @@ function loadReviewTypePrompt(projectRoot, reviewType) {
 /**
  * Load .env file if it exists
  */
-function loadDotenv(projectRoot) {
-    const envFile = path.join(projectRoot, '.env');
+function loadDotenv(workspaceRoot) {
+    const envFile = path.join(workspaceRoot, '.env');
     if (!fs.existsSync(envFile))
         return;
     const content = fs.readFileSync(envFile, 'utf-8');
@@ -151,8 +181,8 @@ function loadDotenv(projectRoot) {
 /**
  * Find a spec file by number
  */
-function findSpec(projectRoot, number) {
-    const specsDir = path.join(projectRoot, 'codev', 'specs');
+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);
@@ -167,8 +197,8 @@ function findSpec(projectRoot, number) {
 /**
  * Find a plan file by number
  */
-function findPlan(projectRoot, number) {
-    const plansDir = path.join(projectRoot, 'codev', 'plans');
+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);
@@ -183,9 +213,9 @@ function findPlan(projectRoot, number) {
 /**
  * Log query to history file
  */
-function logQuery(projectRoot, model, query, duration) {
+function logQuery(workspaceRoot, model, query, duration) {
     try {
-        const logDir = path.join(projectRoot, '.consult');
+        const logDir = path.join(workspaceRoot, '.consult');
         if (!fs.existsSync(logDir)) {
             fs.mkdirSync(logDir, { recursive: true });
         }
@@ -211,13 +241,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, projectRoot, 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.
@@ -240,7 +366,7 @@ async function runClaudeConsultation(queryText, role, projectRoot, outputPath) {
                 model: 'claude-opus-4-6',
                 maxTurns: CLAUDE_MAX_TURNS,
                 maxBudgetUsd: 25,
-                cwd: projectRoot,
+                cwd: workspaceRoot,
                 env,
             },
         });
@@ -254,9 +380,14 @@ async function runClaudeConsultation(queryText, role, projectRoot, 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,21 +399,42 @@ async function runClaudeConsultation(queryText, role, projectRoot, 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
  */
-async function runConsultation(model, query, projectRoot, dryRun, reviewType, customRole, outputPath) {
+async function runConsultation(model, query, workspaceRoot, dryRun, reviewType, customRole, outputPath, metricsCtx) {
     // Use custom role if specified, otherwise use default consultant role
-    let role = customRole ? loadCustomRole(projectRoot, customRole) : loadRole(projectRoot);
+    let role = customRole ? loadCustomRole(workspaceRoot, customRole) : loadRole(workspaceRoot);
     // Append review type prompt if specified
     if (reviewType) {
-        const typePrompt = loadReviewTypePrompt(projectRoot, reviewType);
+        const typePrompt = loadReviewTypePrompt(workspaceRoot, reviewType);
         if (typePrompt) {
             role = role + '\n\n---\n\n' + typePrompt;
             console.error(`Review type: ${reviewType}`);
@@ -291,7 +443,7 @@ async function runConsultation(model, query, projectRoot, dryRun, reviewType, cu
             console.error(chalk.yellow(`Warning: Review type prompt not found: ${reviewType}`));
         }
     }
-    // Claude uses the Agent SDK — handle separately from CLI-based models
+    // SDK-based models — handle separately from CLI subprocess models
     if (model === 'claude') {
         if (dryRun) {
             console.log(chalk.yellow(`[claude] Would invoke Agent SDK:`));
@@ -304,9 +456,26 @@ async function runConsultation(model, query, projectRoot, dryRun, reviewType, cu
             return;
         }
         const startTime = Date.now();
-        await runClaudeConsultation(query, role, projectRoot, outputPath);
+        await runClaudeConsultation(query, role, workspaceRoot, outputPath, metricsCtx);
         const duration = (Date.now() - startTime) / 1000;
-        logQuery(projectRoot, model, query, duration);
+        logQuery(workspaceRoot, model, query, duration);
+        console.error(`\n[${model} completed in ${duration.toFixed(1)}s]`);
+        return;
+    }
+    if (model === 'codex') {
+        if (dryRun) {
+            console.log(chalk.yellow(`[codex] Would invoke Codex SDK:`));
+            console.log(`  Model: gpt-5.2-codex`);
+            console.log(`  Sandbox: read-only`);
+            console.log(`  Reasoning effort: medium`);
+            const promptPreview = query.substring(0, 200) + (query.length > 200 ? '...' : '');
+            console.log(`  Prompt: ${promptPreview}`);
+            return;
+        }
+        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]`);
         return;
     }
@@ -327,21 +496,7 @@ async function runConsultation(model, query, projectRoot, dryRun, reviewType, cu
         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=low', // Faster responses (10-20% improvement)
-            '--full-auto',
-            query,
-        ];
+        cmd = [config.cli, ...config.args, '--output-format', 'json', query];
     }
     else {
         throw new Error(`Unknown model: ${model}`);
@@ -369,35 +524,56 @@ async function runConsultation(model, query, projectRoot, dryRun, reviewType, cu
     // 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';
+    const stdoutMode = 'pipe'; // Always pipe to capture structured output for metrics
     return new Promise((resolve, reject) => {
         const proc = spawn(cmd[0], cmd.slice(1), {
+            cwd: workspaceRoot,
             env: fullEnv,
             stdio: ['ignore', stdoutMode, '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);
+                // Gemini: buffer only (JSON is one blob, text emitted on close)
             });
         }
         proc.on('close', (code) => {
             const duration = (Date.now() - startTime) / 1000;
-            logQuery(projectRoot, model, query, duration);
+            logQuery(workspaceRoot, model, query, duration);
             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 extracted text to stdout for Gemini (was fully buffered)
+            if (model === 'gemini') {
+                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}`));
@@ -410,6 +586,19 @@ async function runConsultation(model, query, projectRoot, dryRun, reviewType, cu
             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);
         });
     });
@@ -418,9 +607,9 @@ async function runConsultation(model, query, projectRoot, dryRun, reviewType, cu
  * 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(projectRoot, ref) {
-    const stat = execSync(`git diff --stat ${ref}`, { cwd: projectRoot, encoding: 'utf-8' }).toString();
-    const nameOnly = execSync(`git diff --name-only ${ref}`, { cwd: projectRoot, encoding: 'utf-8' }).toString();
+function getDiffStat(workspaceRoot, ref) {
+    const stat = execSync(`git diff --stat ${ref}`, { cwd: workspaceRoot, encoding: 'utf-8' }).toString();
+    const nameOnly = execSync(`git diff --name-only ${ref}`, { cwd: workspaceRoot, encoding: 'utf-8' }).toString();
     const files = nameOnly.trim().split('\n').filter(Boolean);
     return { stat, files };
 }
@@ -450,7 +639,7 @@ function fetchPRData(prNumber) {
  * Build query for PR review.
  * Provides file list and instructs reviewers to read files from disk.
  */
-function buildPRQuery(prNumber, _projectRoot) {
+function buildPRQuery(prNumber, _workspaceRoot) {
     const prData = fetchPRData(prNumber);
     const fileList = prData.changedFiles.map(f => `- ${f}`).join('\n');
     return `Review Pull Request #${prNumber}
@@ -466,7 +655,7 @@ ${fileList}
 ## 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.
+Do NOT rely on git diffs to determine the current state of code — diffs miss uncommitted changes in worktrees.
 
 ## Comments
 ${prData.comments}
@@ -504,6 +693,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
@@ -527,15 +721,17 @@ 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.
  */
-function buildImplQuery(projectNumber, projectRoot, planPhase) {
-    const specPath = findSpec(projectRoot, projectNumber);
-    const planPath = findPlan(projectRoot, projectNumber);
+function buildImplQuery(projectNumber, workspaceRoot, planPhase) {
+    const specPath = findSpec(workspaceRoot, projectNumber);
+    const planPath = findPlan(workspaceRoot, projectNumber);
     // Get compact diff summary against base branch
     let diffStat = '';
     let changedFiles = [];
     try {
-        const mergeBase = execSync('git merge-base HEAD main', { cwd: projectRoot, encoding: 'utf-8' }).trim();
-        const result = getDiffStat(projectRoot, `${mergeBase}..HEAD`);
+        const mergeBase = execSync('git merge-base HEAD main', { cwd: workspaceRoot, encoding: 'utf-8' }).trim();
+        // Use mergeBase (not mergeBase..HEAD) to include uncommitted working tree changes.
+        // The ..HEAD syntax is commit-to-commit and misses uncommitted work in builder worktrees.
+        const result = getDiffStat(workspaceRoot, mergeBase);
         diffStat = result.stat;
         changedFiles = result.files;
     }
@@ -569,7 +765,7 @@ function buildImplQuery(projectNumber, projectRoot, 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`;
@@ -606,6 +802,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
@@ -641,8 +842,20 @@ export async function consult(options) {
     if (reviewType && !VALID_REVIEW_TYPES.includes(reviewType)) {
         throw new Error(`Invalid review type: ${reviewType}\nValid types: ${VALID_REVIEW_TYPES.join(', ')}`);
     }
-    const projectRoot = findProjectRoot();
-    loadDotenv(projectRoot);
+    const workspaceRoot = findWorkspaceRoot();
+    loadDotenv(workspaceRoot);
+    // Capture timestamp at invocation start (before subprocess/SDK)
+    const timestamp = new Date().toISOString();
+    // Build metrics context with protocol/project defaults
+    const metricsCtx = {
+        timestamp,
+        model,
+        reviewType: reviewType ?? null,
+        subcommand,
+        protocol: options.protocol ?? 'manual',
+        projectId: options.projectId ?? null,
+        workspacePath: workspaceRoot,
+    };
     console.error(`[${subcommand} review]`);
     console.error(`Model: ${model}`);
     // Log custom role if specified
@@ -659,7 +872,7 @@ export async function consult(options) {
             if (isNaN(prNumber)) {
                 throw new Error(`Invalid PR number: ${args[0]}`);
             }
-            query = buildPRQuery(prNumber, projectRoot);
+            query = buildPRQuery(prNumber, workspaceRoot);
             break;
         }
         case 'spec': {
@@ -670,11 +883,11 @@ export async function consult(options) {
             if (isNaN(specNumber)) {
                 throw new Error(`Invalid spec number: ${args[0]}`);
             }
-            const specPath = findSpec(projectRoot, specNumber);
+            const specPath = findSpec(workspaceRoot, specNumber);
             if (!specPath) {
                 throw new Error(`Spec ${specNumber} not found`);
             }
-            const planPath = findPlan(projectRoot, specNumber);
+            const planPath = findPlan(workspaceRoot, specNumber);
             query = buildSpecQuery(specPath, planPath);
             console.error(`Spec: ${specPath}`);
             if (planPath)
@@ -689,11 +902,11 @@ export async function consult(options) {
             if (isNaN(planNumber)) {
                 throw new Error(`Invalid plan number: ${args[0]}`);
             }
-            const planPath = findPlan(projectRoot, planNumber);
+            const planPath = findPlan(workspaceRoot, planNumber);
             if (!planPath) {
                 throw new Error(`Plan ${planNumber} not found`);
             }
-            const specPath = findSpec(projectRoot, planNumber);
+            const specPath = findSpec(workspaceRoot, planNumber);
             query = buildPlanQuery(planPath, specPath);
             console.error(`Plan: ${planPath}`);
             if (specPath)
@@ -715,9 +928,9 @@ export async function consult(options) {
             if (isNaN(implNumber)) {
                 throw new Error(`Invalid project number: ${args[0]}`);
             }
-            const specPath = findSpec(projectRoot, implNumber);
-            const planPath = findPlan(projectRoot, implNumber);
-            query = buildImplQuery(implNumber, projectRoot, options.planPhase);
+            const specPath = findSpec(workspaceRoot, implNumber);
+            const planPath = findPlan(workspaceRoot, implNumber);
+            query = buildImplQuery(implNumber, workspaceRoot, options.planPhase);
             console.error(`Project: ${implNumber}`);
             if (specPath)
                 console.error(`Spec: ${specPath}`);
@@ -752,8 +965,8 @@ export async function consult(options) {
     console.error(`[${model.toUpperCase()}] Starting consultation...`);
     console.error('='.repeat(60));
     console.error('');
-    await runConsultation(model, query, projectRoot, dryRun, reviewType, customRole, outputPath);
+    await runConsultation(model, query, workspaceRoot, dryRun, reviewType, customRole, outputPath, metricsCtx);
 }
 // Exported for testing
-export { getDiffStat as _getDiffStat };
+export { getDiffStat as _getDiffStat, buildSpecQuery as _buildSpecQuery, buildPlanQuery as _buildPlanQuery };
 //# sourceMappingURL=index.js.map