@contextrail/code-review-agent 0.1.1-alpha.0

package/dist/reviewers/executor.js

@@ -0,0 +1,357 @@
+import path from 'node:path';
+import { chunkReviewInputs } from '../review-inputs/chunking.js';
+import { filterDiffInputsByPatterns, filterFilesByPatterns, } from '../review-inputs/file-patterns.js';
+import { isDiffInputs } from '../review-inputs/index.js';
+import { DEFAULT_MAX_ITERATIONS, DEFAULT_MAX_STEPS } from '../config/defaults.js';
+import { initProgress, updateProgress, appendFailure, formatTimestamp } from './progress-tracker.js';
+import { buildPromptMessages } from './prompt.js';
+import { runReviewerIteration } from './iteration.js';
+import { logCompletion, logContinuation, logIteration, writeFindings, writeTokenMetrics } from './persistence.js';
+import { mergeIterationTracking, mergeTokenUsage } from './tool-call-tracker.js';
+import { mergeChunkFindings } from './findings-merge.js';
+import { createLlmService } from '../llm/factory.js';
+const formatIssuePath = (pathSegments) => {
+    if (!Array.isArray(pathSegments) || pathSegments.length === 0) {
+        return '(root)';
+    }
+    return pathSegments.map((segment) => String(segment)).join('.');
+};
+const extractValidationIssues = (error) => {
+    const candidates = [];
+    const seen = new Set();
+    let current = error;
+    for (let i = 0; i < 4 && current && typeof current === 'object' && !seen.has(current); i++) {
+        seen.add(current);
+        candidates.push(current);
+        current = current.cause;
+    }
+    for (const candidate of candidates) {
+        const issues = candidate.issues;
+        if (!Array.isArray(issues)) {
+            continue;
+        }
+        return issues
+            .map((issue) => {
+            const entry = issue;
+            return {
+                path: formatIssuePath(entry.path ?? []),
+                message: entry.message ?? 'Unknown validation issue',
+            };
+        })
+            .slice(0, 10);
+    }
+    return [];
+};
+const buildFailureDetails = (error, fallbackDetails) => {
+    const details = [fallbackDetails];
+    if (error && typeof error === 'object') {
+        const name = error.name;
+        if (name) {
+            details.push(`Error type: ${name}`);
+        }
+        const causeMessage = error.cause?.message;
+        if (causeMessage) {
+            details.push(`Cause: ${causeMessage}`);
+        }
+        const issues = extractValidationIssues(error);
+        if (issues.length > 0) {
+            details.push('Schema validation issues:');
+            for (const issue of issues) {
+                details.push(`- ${issue.path}: ${issue.message}`);
+            }
+        }
+        const rawText = error.text;
+        if (rawText) {
+            const snippet = rawText.length > 4000 ? `${rawText.slice(0, 4000)}\n...[truncated]` : rawText;
+            details.push(`Model raw output:\n\`\`\`json\n${snippet}\n\`\`\``);
+        }
+    }
+    return details.join('\n\n');
+};
+/**
+ * Extract filePatterns from prompt metadata.
+ *
+ * @param metadata - Prompt metadata (may be undefined or have nested structure)
+ * @returns FilePatterns if found, undefined otherwise
+ */
+export function extractFilePatterns(metadata) {
+    if (!metadata || typeof metadata !== 'object') {
+        return undefined;
+    }
+    // Handle nested metadata.scope.filePatterns structure from YAML
+    const meta = metadata;
+    const scope = meta.scope;
+    if (scope && typeof scope === 'object') {
+        const filePatterns = scope.filePatterns;
+        if (filePatterns && typeof filePatterns === 'object') {
+            const patterns = filePatterns;
+            return {
+                include: Array.isArray(patterns.include) ? patterns.include : undefined,
+                exclude: Array.isArray(patterns.exclude) ? patterns.exclude : undefined,
+            };
+        }
+    }
+    // Handle direct filePatterns structure
+    const directPatterns = meta.filePatterns;
+    if (directPatterns && typeof directPatterns === 'object') {
+        const patterns = directPatterns;
+        return {
+            include: Array.isArray(patterns.include) ? patterns.include : undefined,
+            exclude: Array.isArray(patterns.exclude) ? patterns.exclude : undefined,
+        };
+    }
+    return undefined;
+}
+/**
+ * Run reviewer loop with self-validation.
+ * Each iteration is a fresh generateText call (no history bleed).
+ * Based on context://agentic/execution/loop-orchestration
+ *
+ * @param reviewer - Reviewer name (e.g., 'reviewer-security')
+ * @param inputs - Review inputs (files, diffs)
+ * @param understanding - Orchestrator's understanding of changes
+ * @param outputDir - Base output directory
+ * @param deps - Dependencies (MCP client, config)
+ * @returns Reviewer findings
+ */
+export const runReviewerLoop = async (reviewer, inputs, understanding, outputDir, deps) => {
+    const { mcpClient, config, logger } = deps;
+    const maxIterations = config.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+    const reviewersDir = path.join(outputDir, 'reviewers');
+    const reviewerDir = path.join(reviewersDir, reviewer);
+    // Initialize progress for this reviewer
+    let progress = await initProgress(reviewersDir, reviewer);
+    // Track context IDs used across iterations
+    const contextIds = [];
+    const toolCalls = [];
+    // Track token usage per iteration (with chunk details)
+    const iterationTokenData = [];
+    const recordFailureAndBlock = async (message, details) => {
+        await appendFailure(reviewersDir, reviewer, {
+            gate: 'validation',
+            message,
+            details,
+        });
+        await writeTokenMetrics(reviewerDir, reviewer, iterationTokenData);
+        progress = await updateProgress(reviewersDir, reviewer, {
+            status: 'blocked',
+            completedAt: formatTimestamp(),
+            lastFailure: {
+                gate: 'validation',
+                message,
+                details,
+            },
+            evidence: [`${reviewerDir}/failures.md`, `${reviewerDir}/progress.json`],
+        });
+    };
+    // Fetch reviewer-specific prompt from MCP
+    const promptResult = await mcpClient.getPrompt({ name: reviewer });
+    const promptMessages = buildPromptMessages(promptResult);
+    // Extract filePatterns from prompt metadata
+    const filePatterns = extractFilePatterns(promptResult.metadata);
+    // Filter inputs based on filePatterns from prompt metadata
+    let filteredInputs = inputs;
+    if (filePatterns) {
+        if (isDiffInputs(inputs)) {
+            const filtered = filterDiffInputsByPatterns(inputs.files, inputs.diffs, filePatterns);
+            filteredInputs = {
+                ...inputs,
+                files: filtered.files,
+                diffs: filtered.diffs,
+            };
+            // Also filter context if present
+            if (inputs.context) {
+                const filteredContext = {};
+                for (const file of filtered.files) {
+                    if (file in inputs.context && inputs.context[file]) {
+                        filteredContext[file] = inputs.context[file];
+                    }
+                }
+                filteredInputs.context = filteredContext;
+            }
+        }
+        else {
+            // File list mode - filter files and context
+            const filteredFiles = filterFilesByPatterns(inputs.files, filePatterns);
+            filteredInputs = {
+                ...inputs,
+                files: filteredFiles,
+            };
+            // Also filter context if present
+            if (inputs.context) {
+                const filteredContext = {};
+                for (const file of filteredFiles) {
+                    if (file in inputs.context && inputs.context[file]) {
+                        filteredContext[file] = inputs.context[file];
+                    }
+                }
+                filteredInputs.context = filteredContext;
+            }
+        }
+        logger?.debug(`[${reviewer}] File pattern scope applied: include=${JSON.stringify(filePatterns.include ?? [])}, exclude=${JSON.stringify(filePatterns.exclude ?? [])}, before=${inputs.files.length}, after=${filteredInputs.files.length}`);
+    }
+    else {
+        logger?.debug(`[${reviewer}] No file pattern scope found in prompt metadata; reviewing all ${inputs.files.length} files`);
+    }
+    // Create LLM service with MCP tools
+    const { service: llmService } = createLlmService({
+        openRouterApiKey: config.openRouterApiKey,
+        mcpClient,
+        logger,
+    });
+    const maxSteps = config.maxSteps ?? DEFAULT_MAX_STEPS;
+    let findings = null;
+    let iteration = 0;
+    // Chunk inputs if needed
+    const chunks = chunkReviewInputs(filteredInputs, config.chunking);
+    const isChunked = chunks.length > 1;
+    logger?.debug(`[${reviewer}] Execution plan: chunked=${isChunked}, chunks=${chunks.length}, maxIterations=${maxIterations}, reviewerModel=${config.reviewerModel}, criticModel=${config.criticModel ?? 'none'}`);
+    // Loop: review → confirm → re-review if needed
+    while (iteration < maxIterations) {
+        iteration += 1;
+        const iterationStartTime = formatTimestamp();
+        logger?.debug(`[${reviewer}] Iteration ${iteration}/${maxIterations} starting (criticPass=${iteration > 1 && findings !== null}, priorFindings=${findings?.findings.length ?? 0})`);
+        // Update progress to in-progress
+        progress = await updateProgress(reviewersDir, reviewer, {
+            status: 'in-progress',
+            attempts: progress.attempts + 1,
+            startedAt: progress.startedAt ?? iterationStartTime,
+            lastAttempt: iterationStartTime,
+        });
+        let iterationResult;
+        if (isChunked) {
+            // Process chunks sequentially and merge findings
+            const chunkFindings = [];
+            const chunkToolCalls = [];
+            const chunkContextIds = [];
+            const chunkUsages = [];
+            for (let chunkIdx = 0; chunkIdx < chunks.length; chunkIdx++) {
+                const chunk = chunks[chunkIdx];
+                if (!chunk) {
+                    continue;
+                }
+                logger?.debug(`[${reviewer}] Iteration ${iteration}: processing chunk ${chunkIdx + 1}/${chunks.length} (files=${chunk.files.length})`);
+                try {
+                    const chunkResult = await runReviewerIteration(chunk, understanding, iteration, chunkIdx === 0 ? findings : null, // Only pass previous findings to first chunk
+                    {
+                        promptMessages,
+                        llmService,
+                        modelName: config.reviewerModel,
+                        criticModelName: config.criticModel,
+                        maxSteps,
+                        reviewer,
+                        logger,
+                    }, config.prDescription, config.reviewDomains);
+                    chunkFindings.push(chunkResult.findings);
+                    mergeIterationTracking({ toolCalls: chunkToolCalls, contextIds: chunkContextIds }, chunkResult);
+                    if (chunkResult.usage) {
+                        chunkUsages.push({ chunkIndex: chunkIdx, usage: chunkResult.usage });
+                    }
+                }
+                catch (error) {
+                    const errorMsg = error instanceof Error
+                        ? error.message
+                        : `[REVIEWER] Failed to run reviewer iteration for chunk ${chunkIdx + 1}`;
+                    const details = buildFailureDetails(error, `Chunk ${chunkIdx + 1} of ${chunks.length} failed`);
+                    await recordFailureAndBlock(errorMsg, details);
+                    throw error;
+                }
+            }
+            // Merge findings from all chunks
+            const mergedFindings = mergeChunkFindings(chunkFindings);
+            findings = mergedFindings;
+            logger?.debug(`[${reviewer}] Iteration ${iteration}: merged chunk findings=${mergedFindings.findings.length}, validated=${mergedFindings.validated}`);
+            // Merge token usage from all chunks
+            const iterationUsage = mergeTokenUsage(chunkUsages.map((c) => c.usage));
+            iterationResult = {
+                findings: mergedFindings,
+                toolCalls: chunkToolCalls,
+                contextIds: chunkContextIds,
+                usage: iterationUsage,
+            };
+            // Track token usage for this iteration with chunk details
+            if (iterationUsage) {
+                iterationTokenData.push({
+                    iteration,
+                    usage: iterationUsage,
+                    chunks: chunkUsages,
+                });
+            }
+        }
+        else {
+            // Single chunk (or no chunking needed) - process normally
+            try {
+                iterationResult = await runReviewerIteration(inputs, understanding, iteration, findings, {
+                    promptMessages,
+                    llmService,
+                    modelName: config.reviewerModel,
+                    criticModelName: config.criticModel,
+                    maxSteps,
+                    reviewer,
+                    logger,
+                }, config.prDescription, config.reviewDomains);
+            }
+            catch (error) {
+                const errorMsg = error instanceof Error ? error.message : '[REVIEWER] Failed to run reviewer iteration';
+                const details = buildFailureDetails(error, 'generateText returned no object output');
+                await recordFailureAndBlock(errorMsg, details);
+                throw error;
+            }
+            findings = iterationResult.findings;
+        }
+        mergeIterationTracking({ toolCalls, contextIds }, iterationResult);
+        // Track token usage for this iteration (non-chunked case)
+        if (!isChunked && iterationResult.usage) {
+            iterationTokenData.push({
+                iteration,
+                usage: iterationResult.usage,
+            });
+        }
+        // Log activity for this iteration
+        if (findings) {
+            await logIteration(reviewersDir, reviewer, iteration, findings, toolCalls, contextIds);
+        }
+        // Confirmation step: validate findings quality
+        if (findings && findings.validated) {
+            logger?.debug(`[${reviewer}] Validation complete at iteration ${iteration}: findings=${findings.findings.length}, toolCallsTracked=${toolCalls.length}, contextIdsTracked=${contextIds.length}`);
+            // Mark complete
+            progress = await updateProgress(reviewersDir, reviewer, {
+                status: 'done',
+                completedAt: formatTimestamp(),
+                evidence: [`${reviewerDir}/findings.json`, `${reviewerDir}/activity.md`],
+            });
+            await writeFindings(reviewerDir, findings);
+            await logCompletion(reviewersDir, reviewer, iteration, findings);
+            await writeTokenMetrics(reviewerDir, reviewer, iterationTokenData);
+            return findings;
+        }
+        // If not validated and we have more iterations, continue
+        if (iteration < maxIterations) {
+            logger?.debug(`[${reviewer}] Findings not validated at iteration ${iteration}; continuing to iteration ${iteration + 1}`);
+            await logContinuation(reviewersDir, reviewer, iteration + 1);
+        }
+    }
+    // Max iterations reached without validation
+    const errorMsg = `Reviewer ${reviewer} reached max iterations (${maxIterations}) without validation`;
+    await appendFailure(reviewersDir, reviewer, {
+        gate: 'validation',
+        message: errorMsg,
+        details: `Findings were not validated after ${maxIterations} iterations`,
+    });
+    // Write findings anyway (may be partially complete)
+    if (findings) {
+        await writeFindings(reviewerDir, findings);
+    }
+    // Write token metrics even if max iterations reached
+    await writeTokenMetrics(reviewerDir, reviewer, iterationTokenData);
+    // Update progress to blocked
+    await updateProgress(reviewersDir, reviewer, {
+        status: 'blocked',
+        lastFailure: {
+            gate: 'validation',
+            message: errorMsg,
+            details: `Max iterations reached without validation`,
+        },
+    });
+    throw new Error(errorMsg);
+};

package/dist/reviewers/findings-merge.d.ts

@@ -0,0 +1,9 @@
+import type { ReviewerFindings } from '../output/schema.js';
+/**
+ * Merge findings from multiple chunks deterministically.
+ * Findings are deduplicated based on file, line, and title.
+ *
+ * @param chunkFindings - Array of findings from each chunk
+ * @returns Merged findings
+ */
+export declare const mergeChunkFindings: (chunkFindings: ReviewerFindings[]) => ReviewerFindings;

package/dist/reviewers/findings-merge.js

@@ -0,0 +1,131 @@
+/**
+ * Get severity order value, defaulting to 'info' if invalid.
+ */
+const getSeverityOrder = (severity) => {
+    const severityOrder = {
+        critical: 4,
+        major: 3,
+        minor: 2,
+        info: 1,
+    };
+    return severityOrder[severity ?? 'info'] ?? 1;
+};
+/**
+ * Merge findings from multiple chunks deterministically.
+ * Findings are deduplicated based on file, line, and title.
+ *
+ * @param chunkFindings - Array of findings from each chunk
+ * @returns Merged findings
+ */
+export const mergeChunkFindings = (chunkFindings) => {
+    if (chunkFindings.length === 0) {
+        return {
+            findings: [],
+            validated: false,
+            notes: null,
+        };
+    }
+    if (chunkFindings.length === 1) {
+        const singleChunk = chunkFindings[0];
+        if (!singleChunk) {
+            return {
+                findings: [],
+                validated: false,
+                notes: null,
+            };
+        }
+        return singleChunk;
+    }
+    // Collect all findings
+    const allFindings = [];
+    for (const chunk of chunkFindings) {
+        allFindings.push(...chunk.findings);
+    }
+    // Deduplicate findings based on file, line, and title
+    // Use a map keyed by file+line+title for deduplication
+    const findingsMap = new Map();
+    for (const finding of allFindings) {
+        const key = `${finding.file ?? ''}:${finding.line ?? ''}:${finding.title}`;
+        const existing = findingsMap.get(key);
+        if (!existing) {
+            // New finding
+            findingsMap.set(key, finding);
+        }
+        else {
+            // Merge context IDs if present
+            const mergedContextIds = new Set();
+            const mergedContextIdsViolated = new Set();
+            const mergedContextTitles = new Set();
+            if (existing.contextIdsUsed) {
+                existing.contextIdsUsed.forEach((id) => mergedContextIds.add(id));
+            }
+            if (finding.contextIdsUsed) {
+                finding.contextIdsUsed.forEach((id) => mergedContextIds.add(id));
+            }
+            if (existing.contextIdsViolated) {
+                existing.contextIdsViolated.forEach((id) => mergedContextIdsViolated.add(id));
+            }
+            if (finding.contextIdsViolated) {
+                finding.contextIdsViolated.forEach((id) => mergedContextIdsViolated.add(id));
+            }
+            if (existing.contextTitles) {
+                existing.contextTitles.forEach((title) => mergedContextTitles.add(title));
+            }
+            if (finding.contextTitles) {
+                finding.contextTitles.forEach((title) => mergedContextTitles.add(title));
+            }
+            // Keep the finding with higher severity (critical > major > minor > info)
+            const keepExisting = getSeverityOrder(existing.severity) >= getSeverityOrder(finding.severity);
+            if (!keepExisting) {
+                // Replace with new finding, but merge context IDs
+                // Azure workaround: use null instead of undefined for optional fields
+                findingsMap.set(key, {
+                    ...finding,
+                    contextIdsUsed: mergedContextIds.size > 0 ? Array.from(mergedContextIds) : null,
+                    contextIdsViolated: mergedContextIdsViolated.size > 0 ? Array.from(mergedContextIdsViolated) : null,
+                    contextTitles: mergedContextTitles.size > 0 ? Array.from(mergedContextTitles) : null,
+                });
+            }
+            else {
+                // Update existing finding with merged context IDs
+                // Azure workaround: use null instead of undefined for optional fields
+                findingsMap.set(key, {
+                    ...existing,
+                    contextIdsUsed: mergedContextIds.size > 0 ? Array.from(mergedContextIds) : null,
+                    contextIdsViolated: mergedContextIdsViolated.size > 0 ? Array.from(mergedContextIdsViolated) : null,
+                    contextTitles: mergedContextTitles.size > 0 ? Array.from(mergedContextTitles) : null,
+                });
+            }
+        }
+    }
+    // Convert map back to array
+    const mergedFindings = Array.from(findingsMap.values());
+    // Sort findings deterministically: by severity (desc), then by file, then by line
+    mergedFindings.sort((a, b) => {
+        const severityDiff = getSeverityOrder(b.severity) - getSeverityOrder(a.severity);
+        if (severityDiff !== 0) {
+            return severityDiff;
+        }
+        const fileA = a.file ?? '';
+        const fileB = b.file ?? '';
+        const fileDiff = fileA.localeCompare(fileB);
+        if (fileDiff !== 0) {
+            return fileDiff;
+        }
+        const lineA = a.line ?? 0;
+        const lineB = b.line ?? 0;
+        return lineA - lineB;
+    });
+    // Validated only if all chunks were validated
+    const allValidated = chunkFindings.every((chunk) => chunk.validated);
+    // Merge notes if present
+    const notes = chunkFindings
+        .map((chunk) => chunk.notes)
+        .filter((note) => Boolean(note))
+        .join('\n\n');
+    return {
+        findings: mergedFindings,
+        validated: allValidated,
+        notes: notes || null,
+    };
+};

package/dist/reviewers/iteration.d.ts

@@ -0,0 +1,17 @@
+import type { ReviewInputs } from '../review-inputs/index.js';
+import type { ReviewerFindings } from '../output/schema.js';
+import { type PromptMessage } from './prompt.js';
+import type { ReviewerIterationResult } from './types.js';
+import type { Logger } from '../logging/logger.js';
+import type { LlmService } from '../llm/service.js';
+type IterationDeps = {
+    promptMessages: PromptMessage[];
+    llmService: LlmService;
+    modelName: string;
+    criticModelName?: string;
+    maxSteps: number;
+    reviewer?: string;
+    logger?: Logger;
+};
+export declare const runReviewerIteration: (inputs: ReviewInputs, understanding: string, iteration: number, findings: ReviewerFindings | null, deps: IterationDeps, prDescription?: string, reviewDomains?: string[]) => Promise<ReviewerIterationResult>;
+export {};

package/dist/reviewers/iteration.js

@@ -0,0 +1,95 @@
+import { reviewerFindingsSchema, cleanFinding } from '../output/schema.js';
+import { buildReviewerUserMessage } from './prompt.js';
+import { collectToolCalls } from './tool-call-tracker.js';
+import { applyAttributionGuardrails, applyDeterministicValidationRules } from './validation-rules.js';
+export const runReviewerIteration = async (inputs, understanding, iteration, findings, deps, prDescription, reviewDomains) => {
+    const userMessage = buildReviewerUserMessage(inputs, understanding, iteration, findings, prDescription, reviewDomains);
+    const previousFindingsCount = findings?.findings.length ?? 0;
+    // Determine which model to use: critic model for iteration 2+, reviewer model for iteration 1
+    const isCriticPass = iteration > 1 && findings !== null;
+    const modelName = isCriticPass && deps.criticModelName ? deps.criticModelName : deps.modelName;
+    if (isCriticPass && deps.criticModelName) {
+        deps.logger?.info(`Critic pass starting (iteration ${iteration}, model: ${deps.criticModelName})`);
+        deps.logger?.debug(`Using critic model: ${deps.criticModelName} (iteration ${iteration})`);
+        deps.logger?.debug(`Critic evidence input (iteration ${iteration}): previous findings=${previousFindingsCount}, validated=${findings?.validated ?? false}`);
+    }
+    // Convert prompt messages to ModelMessage format
+    const messages = deps.promptMessages.map((msg) => ({
+        role: msg.role,
+        content: msg.content,
+    }));
+    // Add user message
+    messages.push({
+        role: 'user',
+        content: userMessage,
+    });
+    // Call LLM service with structured output
+    const result = await deps.llmService.generateStructuredOutput(messages, reviewerFindingsSchema, {
+        model: modelName,
+        maxSteps: deps.maxSteps,
+        metadata: {
+            operation: isCriticPass ? 'reviewer-critic' : 'reviewer-iteration',
+            model: modelName,
+            iteration,
+            reviewer: deps.reviewer,
+        },
+    });
+    let parsed = result.output;
+    // Normalize optional finding fields for stable downstream processing.
+    if (parsed.findings) {
+        parsed.findings = parsed.findings.map(cleanFinding);
+    }
+    // Apply non-negotiable attribution guardrails on every iteration.
+    const attributionResult = applyAttributionGuardrails(parsed.findings);
+    if (attributionResult.rejected.length > 0) {
+        deps.logger?.info(`Attribution guardrails rejected ${attributionResult.rejected.length} finding(s) in iteration ${iteration}`);
+        for (const { finding, reason } of attributionResult.rejected) {
+            deps.logger?.debug(`Attribution rejection: "${finding.title}" - ${reason}`);
+        }
+    }
+    parsed = {
+        ...parsed,
+        findings: attributionResult.passed,
+        notes: attributionResult.rejected.length > 0
+            ? parsed.notes
+                ? `${parsed.notes}\n\nAttribution guardrails removed ${attributionResult.rejected.length} finding(s).`
+                : `Attribution guardrails removed ${attributionResult.rejected.length} finding(s).`
+            : parsed.notes,
+    };
+    // Apply deterministic validation rules before LLM critic (for critic pass only)
+    if (isCriticPass) {
+        const beforeValidationCount = parsed.findings.length;
+        const validationResult = applyDeterministicValidationRules(parsed.findings);
+        if (validationResult.rejected.length > 0) {
+            deps.logger?.info(`Deterministic validation rejected ${validationResult.rejected.length} finding(s) in iteration ${iteration}`);
+            for (const { finding, reason } of validationResult.rejected) {
+                deps.logger?.debug(`Rejected finding: "${finding.title}" - ${reason}`);
+            }
+        }
+        // Update findings with validated set
+        parsed = {
+            ...parsed,
+            findings: validationResult.passed,
+            notes: parsed.notes
+                ? `${parsed.notes}\n\nDeterministic validation removed ${validationResult.rejected.length} finding(s).`
+                : `Deterministic validation removed ${validationResult.rejected.length} finding(s).`,
+        };
+        deps.logger?.info(`Critic pass complete (iteration ${iteration}): ${validationResult.passed.length} finding(s) remaining`);
+        deps.logger?.debug(`Critic validation delta (iteration ${iteration}): before=${beforeValidationCount}, rejected=${validationResult.rejected.length}, after=${validationResult.passed.length}`);
+    }
+    const tracking = collectToolCalls(result.toolCalls);
+    const severityCounts = parsed.findings.reduce((acc, finding) => {
+        acc[finding.severity] += 1;
+        return acc;
+    }, { critical: 0, major: 0, minor: 0, info: 0, pass: 0 });
+    deps.logger?.debug(`Iteration ${iteration} evidence: findings=${parsed.findings.length}, validated=${parsed.validated}, toolCalls=${tracking.toolCalls.length}, contextIds=${tracking.contextIds.length}, severity=${JSON.stringify(severityCounts)}`);
+    if (result.usage) {
+        deps.logger?.debug(`Iteration ${iteration} token usage: prompt=${result.usage.promptTokens}, completion=${result.usage.completionTokens}, total=${result.usage.totalTokens}`);
+    }
+    return {
+        findings: parsed,
+        toolCalls: tracking.toolCalls,
+        contextIds: tracking.contextIds,
+        usage: result.usage,
+    };
+};

package/dist/reviewers/persistence.d.ts

@@ -0,0 +1,17 @@
+import type { ReviewerFindings, TokenUsage } from '../output/schema.js';
+import type { ToolCallEntry } from './types.js';
+export declare const logIteration: (reviewersDir: string, reviewer: string, iteration: number, findings: ReviewerFindings, toolCalls: ToolCallEntry[], contextIds: string[]) => Promise<void>;
+export declare const logContinuation: (reviewersDir: string, reviewer: string, nextIteration: number) => Promise<void>;
+export declare const writeFindings: (reviewerDir: string, findings: ReviewerFindings) => Promise<void>;
+export declare const logCompletion: (reviewersDir: string, reviewer: string, iteration: number, findings: ReviewerFindings) => Promise<void>;
+/**
+ * Write token usage metrics for a reviewer.
+ */
+export declare const writeTokenMetrics: (reviewerDir: string, reviewer: string, iterationTokenData: Array<{
+    iteration: number;
+    usage: TokenUsage;
+    chunks?: Array<{
+        chunkIndex: number;
+        usage: TokenUsage;
+    }>;
+}>) => Promise<void>;