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

package/dist/orchestrator/agentic-orchestrator.js

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+import { DEFAULT_MAX_STEPS } from '../config/defaults.js';
+import { generateUserMessagePrompt } from './prompts.js';
+import { writeOrchestratorOutputs } from './writer.js';
+import { filterValidReviewers, formatReviewerSelectionError } from './validation.js';
+import { extractFilePatterns } from '../reviewers/executor.js';
+import { fileMatchesPatterns } from '../review-inputs/file-patterns.js';
+import { createLlmService } from '../llm/factory.js';
+const extractSystemPrompt = (text) => {
+    const start = text.indexOf('<system_prompt>');
+    const end = text.indexOf('</system_prompt>');
+    if (start === -1 || end === -1 || end <= start) {
+        return null;
+    }
+    const inner = text.slice(start + '<system_prompt>'.length, end).trim();
+    return inner.length > 0 ? inner : null;
+};
+const orchestratorOutputSchema = z.object({
+    understanding: z.string().describe('Understanding of the changes based on the summary'),
+    reviewers: z.array(z.string()).min(1).describe('Selected reviewer names from available list'),
+});
+export const runOrchestrator = async (inputs, outputDir, deps) => {
+    const { mcpClient, config, logger } = deps;
+    // Fetch review-orchestration prompt from MCP
+    const promptResult = await mcpClient.getPrompt({ name: 'review-orchestration' });
+    const promptMessages = [];
+    for (const message of promptResult.messages) {
+        const raw = message.content.type === 'text' ? (message.content.text ?? '') : '';
+        const systemPrompt = extractSystemPrompt(raw);
+        if (systemPrompt) {
+            promptMessages.push({ role: 'system', content: systemPrompt });
+            continue;
+        }
+        const role = message.role === 'user' ? 'user' : message.role === 'assistant' ? 'assistant' : 'system';
+        promptMessages.push({ role, content: raw });
+    }
+    // Extract reviewer catalog from prompt
+    const promptText = promptMessages.map((m) => m.content).join('\n');
+    const reviewerMatches = Array.from(promptText.matchAll(/reviewer-[a-z-]+/g)).map((match) => match[0]);
+    const availableReviewers = Array.from(new Set(reviewerMatches));
+    // Pre-fetch reviewer file patterns before orchestrator runs
+    logger?.debug(`Pre-fetching file patterns for ${availableReviewers.length} reviewers...`);
+    const reviewerFilePatterns = new Map();
+    const patternFetchPromises = availableReviewers.map(async (reviewer) => {
+        try {
+            const reviewerPromptResult = await mcpClient.getPrompt({ name: reviewer });
+            const patterns = extractFilePatterns(reviewerPromptResult.metadata);
+            reviewerFilePatterns.set(reviewer, patterns);
+            return { reviewer, patterns };
+        }
+        catch (error) {
+            logger?.warn(`Failed to fetch patterns for ${reviewer}:`, error);
+            reviewerFilePatterns.set(reviewer, undefined);
+            return { reviewer, patterns: undefined };
+        }
+    });
+    await Promise.all(patternFetchPromises);
+    logger?.debug(`Pre-fetched file patterns for ${reviewerFilePatterns.size} reviewers`);
+    // Build user message with change summary and reviewer file patterns
+    const userMessage = generateUserMessagePrompt(inputs, availableReviewers, config.prDescription, reviewerFilePatterns, config.reviewDomains);
+    // Create LLM service with MCP tools
+    const { service: llmService } = createLlmService({
+        openRouterApiKey: config.openRouterApiKey,
+        mcpClient,
+        logger,
+    });
+    // Prepare messages
+    const messages = [
+        ...promptMessages,
+        {
+            role: 'user',
+            content: userMessage,
+        },
+    ];
+    logger?.debug('Orchestrator prompt messages:', messages);
+    // Call LLM service with structured output
+    const maxSteps = config.maxSteps ?? DEFAULT_MAX_STEPS;
+    const result = await llmService.generateStructuredOutput(messages, orchestratorOutputSchema, {
+        model: config.orchestratorModel,
+        maxSteps,
+        metadata: {
+            operation: 'orchestrator',
+            model: config.orchestratorModel,
+        },
+    });
+    // Extract tool calls and context IDs for activity log
+    const toolCalls = [];
+    const contextIds = [];
+    if (result.toolCalls) {
+        for (const call of result.toolCalls) {
+            toolCalls.push({ tool: call.toolName, input: call.input });
+            if (call.toolName === 'get_context' && call.input && typeof call.input === 'object') {
+                const maybeId = call.input.contextId;
+                if (maybeId && !contextIds.includes(maybeId)) {
+                    contextIds.push(maybeId);
+                }
+            }
+        }
+    }
+    const output = result.output;
+    // Validate reviewers are in available list
+    let validReviewers = filterValidReviewers(output.reviewers, availableReviewers);
+    if (validReviewers.length === 0) {
+        throw new Error(formatReviewerSelectionError(output.reviewers, availableReviewers));
+    }
+    // Post-selection validation: check that each reviewer's file patterns match at least one PR file
+    const validatedReviewers = [];
+    const skippedReviewers = [];
+    for (const reviewer of validReviewers) {
+        const patterns = reviewerFilePatterns.get(reviewer);
+        // If no patterns defined, include the reviewer (backward compatible)
+        if (!patterns) {
+            validatedReviewers.push(reviewer);
+            continue;
+        }
+        // Check if at least one file matches the reviewer's patterns
+        const hasMatch = inputs.files.some((file) => fileMatchesPatterns(file, patterns));
+        if (hasMatch) {
+            validatedReviewers.push(reviewer);
+        }
+        else {
+            skippedReviewers.push(reviewer);
+            const includePatterns = patterns.include?.join(', ') || 'none';
+            logger?.info(`Skipped ${reviewer}: no matching files in PR (patterns: ${includePatterns})`);
+        }
+    }
+    if (validatedReviewers.length === 0) {
+        throw new Error(`[ORCH] All selected reviewers were skipped due to file pattern mismatches. Selected: ${validReviewers.join(', ')}, Skipped: ${skippedReviewers.join(', ')}`);
+    }
+    // Write outputs to orchestrator/ subfolder
+    await writeOrchestratorOutputs(outputDir, output.understanding, validatedReviewers, toolCalls, contextIds);
+    return {
+        understanding: output.understanding,
+        reviewers: validatedReviewers,
+    };
+};

package/dist/orchestrator/prompts.d.ts

@@ -0,0 +1,25 @@
+import { ReviewInputs } from '../review-inputs/index.js';
+import type { FilePatterns } from '../review-inputs/file-patterns.js';
+/**
+ * Generate the activity content for the orchestrator.
+ * @param understanding - The understanding of the changes.
+ * @param reviewers - The selected reviewers.
+ * @param toolCalls - The tool calls.
+ * @param contextIds - The context IDs.
+ * @returns The activity content.
+ */
+declare const generateActivityContentPrompt: (understanding: string, reviewers: string[], toolCalls: Array<{
+    tool: string;
+    input?: unknown;
+}>, contextIds: string[]) => string;
+/**
+ * Generate the user message for the orchestrator.
+ * @param inputs - The review inputs.
+ * @param availableReviewers - The available reviewers.
+ * @param prDescription - Optional PR description to include as context.
+ * @param reviewerFilePatterns - Map of reviewer names to their file patterns.
+ * @param reviewDomains - Optional review focus domains to prioritize.
+ * @returns The user message.
+ */
+declare const generateUserMessagePrompt: (inputs: ReviewInputs, availableReviewers: string[], prDescription?: string, reviewerFilePatterns?: Map<string, FilePatterns | undefined>, reviewDomains?: string[]) => string;
+export { generateActivityContentPrompt, generateUserMessagePrompt };

package/dist/orchestrator/prompts.js

@@ -0,0 +1,98 @@
+import { isDiffInputs } from '../review-inputs/index.js';
+import { generateDiffSummary } from '../review-inputs/diff-summary.js';
+import dedent from 'dedent';
+/**
+ * Generate the activity content for the orchestrator.
+ * @param understanding - The understanding of the changes.
+ * @param reviewers - The selected reviewers.
+ * @param toolCalls - The tool calls.
+ * @param contextIds - The context IDs.
+ * @returns The activity content.
+ */
+const generateActivityContentPrompt = (understanding, reviewers, toolCalls, contextIds) => dedent(`# Orchestration Activity Log
+
+            **Phase**: Orchestration
+            **Completed**: ${new Date().toISOString()}
+
+            ## Understanding
+
+            ${understanding}
+
+            ## Selected Reviewers
+
+            ${reviewers.map((r) => `- ${r}`).join('\n')}
+
+            ## Tool Calls
+
+            ${toolCalls.length > 0 ? toolCalls.map((tc) => `- **${tc.tool}**: ${JSON.stringify(tc.input, null, 2)}`).join('\n\n') : 'None'}
+
+            ## ContextRail Contexts Used
+
+            ${contextIds.length > 0 ? contextIds.map((id) => `- ${id}`).join('\n') : 'None'}
+`);
+/**
+ * Generate the user message for the orchestrator.
+ * @param inputs - The review inputs.
+ * @param availableReviewers - The available reviewers.
+ * @param prDescription - Optional PR description to include as context.
+ * @param reviewerFilePatterns - Map of reviewer names to their file patterns.
+ * @param reviewDomains - Optional review focus domains to prioritize.
+ * @returns The user message.
+ */
+const generateUserMessagePrompt = (inputs, availableReviewers, prDescription, reviewerFilePatterns, reviewDomains) => {
+    const diffSummary = generateDiffSummary(inputs);
+    const prDescriptionBlock = prDescription ? `\n\nPR Description:\n${prDescription}\n` : '';
+    // Build reviewer scope information block
+    const reviewerScopeBlock = reviewerFilePatterns
+        ? `\n\nReviewer file patterns (use this to select reviewers that match the changed files):
+${availableReviewers
+            .map((reviewer) => {
+            const patterns = reviewerFilePatterns.get(reviewer);
+            if (!patterns || !patterns.include || patterns.include.length === 0) {
+                return `- ${reviewer}: matches all files (no patterns defined)`;
+            }
+            const includePatterns = patterns.include.join(', ');
+            const excludePatterns = patterns.exclude && patterns.exclude.length > 0 ? ` (excludes: ${patterns.exclude.join(', ')})` : '';
+            return `- ${reviewer}: ${includePatterns}${excludePatterns}`;
+        })
+            .join('\n')}
+`
+        : '';
+    const reviewDomainsBlock = reviewDomains && reviewDomains.length > 0
+        ? `\n\nReview focus domains:\n${reviewDomains.map((domain) => `- ${domain}`).join('\n')}\n`
+        : '';
+    return dedent(`
+    You are selecting reviewers for this change set.
+    ${prDescriptionBlock}${reviewerScopeBlock}${reviewDomainsBlock}
+    Change summary (read-only):
+    ${JSON.stringify({
+        mode: inputs.mode,
+        files: inputs.files,
+        fileCount: inputs.files.length,
+        hasDiffs: isDiffInputs(inputs) && Object.keys(inputs.diffs).length > 0,
+        diffSummary: isDiffInputs(inputs) && diffSummary.files.length > 0
+            ? {
+                totalFiles: diffSummary.totalFiles,
+                totalAdded: diffSummary.totalAdded,
+                totalRemoved: diffSummary.totalRemoved,
+                perFile: diffSummary.files.map((f) => ({
+                    file: f.file,
+                    fileType: f.fileType,
+                    added: f.added,
+                    removed: f.removed,
+                })),
+            }
+            : undefined,
+    }, null, 2)}
+
+    Available reviewers (choose from this list only):
+    ${availableReviewers.map((r) => `- ${r}`).join('\n')}
+
+    Output requirements:
+    - Provide a short, plain-language understanding of the changes.
+    - Select the minimal set of reviewers needed to cover the risks.
+    - Consider reviewer file patterns when selecting (reviewers will be automatically skipped if their patterns don't match any PR files).
+    - If review focus domains are provided, prioritize reviewers and rationale aligned to those domains.
+`);
+};
+export { generateActivityContentPrompt, generateUserMessagePrompt };

package/dist/orchestrator/validation.d.ts

@@ -0,0 +1,2 @@
+export declare const filterValidReviewers: (selected: string[], available: string[]) => string[];
+export declare const formatReviewerSelectionError: (selected: string[], available: string[]) => string;

package/dist/orchestrator/validation.js

@@ -0,0 +1,7 @@
+export const filterValidReviewers = (selected, available) => {
+    if (available.length === 0) {
+        return [];
+    }
+    return selected.filter((reviewer) => available.includes(reviewer));
+};
+export const formatReviewerSelectionError = (selected, available) => `[ORCH] No valid reviewers selected. Selected: ${selected.join(', ')}, Available: ${available.join(', ')}`;

package/dist/orchestrator/writer.d.ts

@@ -0,0 +1,4 @@
+export declare const writeOrchestratorOutputs: (outputDir: string, understanding: string, reviewers: string[], toolCalls: Array<{
+    tool: string;
+    input?: unknown;
+}>, contextIds: string[]) => Promise<void>;

package/dist/orchestrator/writer.js

@@ -0,0 +1,17 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { generateActivityContentPrompt } from './prompts.js';
+export const writeOrchestratorOutputs = async (outputDir, understanding, reviewers, toolCalls, contextIds) => {
+    const orchestratorDir = path.join(outputDir, 'orchestrator');
+    await mkdir(orchestratorDir, { recursive: true });
+    await writeFile(path.join(orchestratorDir, 'understanding.json'), JSON.stringify({ understanding }, null, 2));
+    await writeFile(path.join(orchestratorDir, 'selection.json'), JSON.stringify({ reviewers }, null, 2));
+    await writeFile(path.join(orchestratorDir, 'progress.json'), JSON.stringify({
+        phase: 'orchestration',
+        status: 'completed',
+        completedAt: new Date().toISOString(),
+        reviewers,
+    }, null, 2));
+    const activityContent = generateActivityContentPrompt(understanding, reviewers, toolCalls, contextIds);
+    await writeFile(path.join(orchestratorDir, 'activity.md'), activityContent);
+};

package/dist/output/aggregator.d.ts

@@ -0,0 +1,30 @@
+import type { ReviewerResult, ReviewDecision, AggregationTokenUsage, SynthesisResult } from './schema.js';
+import type { Logger } from '../logging/logger.js';
+export type AggregationConfig = {
+    openRouterApiKey: string;
+    model: string;
+    maxSteps?: number;
+    logger?: Logger;
+};
+export declare const validateAggregationMaxSteps: (value: number | undefined) => number;
+/**
+ * Synthesize findings from multiple reviewers.
+ * Deduplicates findings, flags contradictions, and surfaces compound risks.
+ *
+ * @param reviewerResults - Array of reviewer results with findings
+ * @param config - Aggregation configuration
+ * @returns Synthesis result with deduplicated findings, contradictions, and compound risks
+ */
+export declare const synthesizeFindings: (reviewerResults: ReviewerResult[], config: AggregationConfig) => Promise<{
+    synthesis: SynthesisResult;
+    usage?: AggregationTokenUsage;
+}>;
+export declare const generateReviewDecision: (understanding: string, synthesisResult: SynthesisResult, config: AggregationConfig) => Promise<{
+    decision: ReviewDecision;
+    usage?: AggregationTokenUsage;
+}>;
+/**
+ * Enforce deterministic decision consistency with synthesized evidence.
+ * If there are no critical/major findings, request-changes is not allowed.
+ */
+export declare const normalizeDecisionWithSynthesis: (decision: ReviewDecision, synthesisResult: SynthesisResult) => ReviewDecision;

package/dist/output/aggregator.js

@@ -0,0 +1,132 @@
+import { reviewDecisionSchema, synthesisResultSchema, cleanFinding } from './schema.js';
+import { buildReviewDecisionPrompt, buildSynthesisPrompt } from './prompts.js';
+import { createLlmService } from '../llm/factory.js';
+const DEFAULT_AGGREGATION_STEPS = 5;
+const MIN_AGGREGATION_STEPS = 1;
+const MAX_AGGREGATION_STEPS = 20;
+export const validateAggregationMaxSteps = (value) => {
+    const maxSteps = value ?? DEFAULT_AGGREGATION_STEPS;
+    if (!Number.isInteger(maxSteps) || maxSteps < MIN_AGGREGATION_STEPS || maxSteps > MAX_AGGREGATION_STEPS) {
+        throw new Error(`Invalid aggregation maxSteps: ${String(value)}. Expected an integer between ${MIN_AGGREGATION_STEPS} and ${MAX_AGGREGATION_STEPS}.`);
+    }
+    return maxSteps;
+};
+/**
+ * Synthesize findings from multiple reviewers.
+ * Deduplicates findings, flags contradictions, and surfaces compound risks.
+ *
+ * @param reviewerResults - Array of reviewer results with findings
+ * @param config - Aggregation configuration
+ * @returns Synthesis result with deduplicated findings, contradictions, and compound risks
+ */
+export const synthesizeFindings = async (reviewerResults, config) => {
+    const { service: llmService } = createLlmService({
+        openRouterApiKey: config.openRouterApiKey,
+        logger: config.logger,
+        enableMetrics: true,
+    });
+    const maxSteps = validateAggregationMaxSteps(config.maxSteps);
+    const totalInputFindings = reviewerResults.reduce((sum, rr) => sum + rr.findings.length, 0);
+    config.logger?.debug(`Synthesis evidence input: reviewers=${reviewerResults.length}, totalFindings=${totalInputFindings}, byReviewer=${JSON.stringify(reviewerResults.map((rr) => ({
+        reviewer: rr.reviewer,
+        findings: rr.findings.length,
+        validated: rr.validated,
+    })))}`);
+    const result = await llmService.generateStructuredOutput([
+        {
+            role: 'system',
+            content: 'You are a synthesis agent that deduplicates findings across multiple reviewers, flags contradictions, and identifies compound risks. Produce structured output matching the provided schema.',
+        },
+        {
+            role: 'user',
+            content: buildSynthesisPrompt(reviewerResults),
+        },
+    ], synthesisResultSchema, {
+        model: config.model,
+        maxSteps,
+        metadata: {
+            operation: 'synthesis',
+            model: config.model,
+        },
+    });
+    // Normalize optional finding fields for stable downstream processing.
+    const cleanedSynthesis = {
+        ...result.output,
+        findings: result.output.findings.map((f) => {
+            const cleaned = cleanFinding(f);
+            // Preserve sourceReviewers from synthesized finding
+            return {
+                ...cleaned,
+                sourceReviewers: f.sourceReviewers,
+            };
+        }),
+    };
+    const synthesisSeverityCounts = cleanedSynthesis.findings.reduce((acc, finding) => {
+        acc[finding.severity] += 1;
+        return acc;
+    }, { critical: 0, major: 0, minor: 0, info: 0, pass: 0 });
+    config.logger?.debug(`Synthesis evidence output: dedupedFindings=${cleanedSynthesis.findings.length}, contradictions=${cleanedSynthesis.contradictions.length}, compoundRisks=${cleanedSynthesis.compoundRisks.length}, severity=${JSON.stringify(synthesisSeverityCounts)}`);
+    const usage = result.usage
+        ? {
+            operation: 'synthesis',
+            usage: result.usage,
+        }
+        : undefined;
+    return { synthesis: cleanedSynthesis, usage };
+};
+export const generateReviewDecision = async (understanding, synthesisResult, config) => {
+    const { service: llmService } = createLlmService({
+        openRouterApiKey: config.openRouterApiKey,
+        logger: config.logger,
+        enableMetrics: true,
+    });
+    const maxSteps = validateAggregationMaxSteps(config.maxSteps);
+    const blockingFindings = synthesisResult.findings.filter((finding) => finding.severity === 'critical' || finding.severity === 'major');
+    config.logger?.debug(`Decision evidence input: findings=${synthesisResult.findings.length}, blockingFindings=${blockingFindings.length}, contradictions=${synthesisResult.contradictions.length}, compoundRisks=${synthesisResult.compoundRisks.length}`);
+    const result = await llmService.generateStructuredOutput([
+        {
+            role: 'system',
+            content: 'You are a senior code reviewer. Produce a concise, structured decision that matches the provided schema.',
+        },
+        {
+            role: 'user',
+            content: buildReviewDecisionPrompt(understanding, synthesisResult),
+        },
+    ], reviewDecisionSchema, {
+        model: config.model,
+        maxSteps,
+        metadata: {
+            operation: 'review-decision',
+            model: config.model,
+        },
+    });
+    const usage = result.usage
+        ? {
+            operation: 'review-decision',
+            usage: result.usage,
+        }
+        : undefined;
+    return { decision: result.output, usage };
+};
+/**
+ * Enforce deterministic decision consistency with synthesized evidence.
+ * If there are no critical/major findings, request-changes is not allowed.
+ */
+export const normalizeDecisionWithSynthesis = (decision, synthesisResult) => {
+    const hasBlockingFindings = synthesisResult.findings.some((finding) => finding.severity === 'critical' || finding.severity === 'major');
+    if (!hasBlockingFindings && decision.decision === 'request-changes') {
+        return {
+            decision: 'approve',
+            summary: 'No critical or major synthesized findings were identified, so this review is approved.',
+            rationale: 'Decision normalized to approve because synthesized findings contain no critical or major issues.',
+        };
+    }
+    if (hasBlockingFindings && decision.decision === 'approve') {
+        return {
+            decision: 'request-changes',
+            summary: 'Critical or major synthesized findings are present and must be addressed before approval.',
+            rationale: 'Decision normalized to request-changes because synthesized findings include critical/major issues.',
+        };
+    }
+    return decision;
+};

package/dist/output/prompts.d.ts

@@ -0,0 +1,32 @@
+import type { ReviewerResult } from './schema.js';
+/**
+ * Generate a human-readable pre-summary from reviewer results.
+ * Includes severity counts and top findings per reviewer.
+ *
+ * @param reviewerResults - Array of reviewer results to summarize
+ * @returns Formatted pre-summary string
+ */
+export declare const generatePreSummary: (reviewerResults: ReviewerResult[]) => string;
+/**
+ * Build synthesis prompt for cross-reviewer synthesis.
+ * Takes all reviewer findings and produces deduplicated findings, contradictions, and compound risks.
+ *
+ * @param reviewerResults - Array of reviewer results with findings
+ * @returns Synthesis prompt string
+ */
+export declare const buildSynthesisPrompt: (reviewerResults: ReviewerResult[]) => string;
+export declare const buildReviewDecisionPrompt: (understanding: string, synthesisResult: {
+    findings: Array<{
+        severity: string;
+        title: string;
+        description: string;
+    }>;
+    contradictions: Array<{
+        context: string;
+    }>;
+    compoundRisks: Array<{
+        description: string;
+        affectedFindings: string[];
+        severity: string;
+    }>;
+}) => string;

package/dist/output/prompts.js

@@ -0,0 +1,153 @@
+/**
+ * Generate a human-readable pre-summary from reviewer results.
+ * Includes severity counts and top findings per reviewer.
+ *
+ * @param reviewerResults - Array of reviewer results to summarize
+ * @returns Formatted pre-summary string
+ */
+export const generatePreSummary = (reviewerResults) => {
+    const summaries = [];
+    for (const result of reviewerResults) {
+        const { reviewer, findings, validated, notes } = result;
+        // Count findings by severity
+        const severityCounts = {
+            critical: findings.filter((f) => f.severity === 'critical').length,
+            major: findings.filter((f) => f.severity === 'major').length,
+            minor: findings.filter((f) => f.severity === 'minor').length,
+            info: findings.filter((f) => f.severity === 'info').length,
+            pass: findings.filter((f) => f.severity === 'pass').length,
+        };
+        const totalIssueFindings = findings.filter((f) => f.severity !== 'pass').length;
+        // Build reviewer summary
+        const parts = [`## ${reviewer}`];
+        parts.push(`Status: ${validated ? '✓ Validated' : '✗ Not validated'}`);
+        parts.push(`Issue findings: ${totalIssueFindings}`);
+        parts.push(`Pass signals: ${severityCounts.pass}`);
+        if (totalIssueFindings > 0) {
+            const severityParts = [];
+            if (severityCounts.critical > 0)
+                severityParts.push(`${severityCounts.critical} critical`);
+            if (severityCounts.major > 0)
+                severityParts.push(`${severityCounts.major} major`);
+            if (severityCounts.minor > 0)
+                severityParts.push(`${severityCounts.minor} minor`);
+            if (severityCounts.info > 0)
+                severityParts.push(`${severityCounts.info} info`);
+            parts.push(`Severity breakdown: ${severityParts.join(', ')}`);
+            // Include top findings (up to 3, prioritizing critical/major)
+            const sortedFindings = [...findings]
+                .filter((f) => f.severity !== 'pass')
+                .sort((a, b) => {
+                const severityOrder = { critical: 0, major: 1, minor: 2, info: 3, pass: 4 };
+                return severityOrder[a.severity] - severityOrder[b.severity];
+            });
+            const topFindings = sortedFindings.slice(0, 3);
+            if (topFindings.length > 0) {
+                parts.push('\nTop findings:');
+                for (const finding of topFindings) {
+                    const location = finding.file
+                        ? `${finding.file}${finding.line ? `:${finding.line}` : ''}`
+                        : 'general';
+                    parts.push(`- [${finding.severity.toUpperCase()}] ${finding.title} (${location})`);
+                }
+            }
+        }
+        else if (severityCounts.pass > 0) {
+            parts.push('No issues reported. Pass signal(s) recorded.');
+        }
+        else {
+            parts.push('No findings reported.');
+        }
+        if (notes) {
+            parts.push(`Notes: ${notes}`);
+        }
+        summaries.push(parts.join('\n'));
+    }
+    return summaries.join('\n\n');
+};
+/**
+ * Build synthesis prompt for cross-reviewer synthesis.
+ * Takes all reviewer findings and produces deduplicated findings, contradictions, and compound risks.
+ *
+ * @param reviewerResults - Array of reviewer results with findings
+ * @returns Synthesis prompt string
+ */
+export const buildSynthesisPrompt = (reviewerResults) => {
+    const reviewerSections = [];
+    for (const result of reviewerResults) {
+        const { reviewer, findings } = result;
+        const findingsJson = JSON.stringify(findings.map((f) => ({
+            severity: f.severity,
+            title: f.title,
+            description: f.description,
+            rationale: f.rationale,
+            suggestedFix: f.suggestedFix,
+            file: f.file,
+            line: f.line,
+            endLine: f.endLine,
+            contextIdsUsed: f.contextIdsUsed,
+            contextIdsViolated: f.contextIdsViolated,
+            contextTitles: f.contextTitles,
+        })), null, 2);
+        reviewerSections.push(`## ${reviewer}\n\nFindings:\n\`\`\`json\n${findingsJson}\n\`\`\``);
+    }
+    return `You are synthesizing findings from multiple code reviewers to produce a coherent, deduplicated review.
+
+Your task:
+1. **Deduplicate findings**: When multiple reviewers identify the same issue (same file, overlapping line range, similar title/description), merge them into a single finding. Keep the highest severity, merge descriptions, and track which reviewers identified it in \`sourceReviewers\`.
+
+2. **Flag contradictions**: Identify cases where reviewers disagree about the same code location (e.g., "Reviewer A says X is a security issue, Reviewer B says X is fine"). List these in the \`contradictions\` array.
+
+3. **Surface compound risks**: Identify cases where multiple findings together create a higher risk than individually (e.g., "Multiple SQL injection points + missing input validation = critical compound risk"). List these in \`compoundRisks\`.
+
+Matching criteria for deduplication:
+- Same file path
+- Overlapping line ranges (or same line if both have line numbers)
+- Similar title/description (>80% semantic similarity)
+
+When merging duplicates:
+- Keep the highest severity level
+- Combine descriptions (avoid repetition)
+- Include all source reviewers in \`sourceReviewers\`
+- Merge context IDs and context titles if present
+
+Reviewer findings:
+${reviewerSections.join('\n\n')}
+
+Output requirements:
+- \`findings\`: Array of deduplicated findings with \`sourceReviewers\` field
+- \`contradictions\`: Array of contradictions (can be empty)
+- \`compoundRisks\`: Array of compound risks (can be empty)
+- \`notes\`: Always include this field; use a string when useful, otherwise \`null\`
+`;
+};
+export const buildReviewDecisionPrompt = (understanding, synthesisResult) => {
+    const findingsSummary = synthesisResult.findings.length > 0
+        ? synthesisResult.findings
+            .map((f) => `- [${f.severity.toUpperCase()}] ${f.title}: ${f.description}`)
+            .join('\n')
+        : '- None';
+    const contradictionsText = synthesisResult.contradictions.length > 0
+        ? `\n\nContradictions:\n${synthesisResult.contradictions.map((c) => `- ${c.context}`).join('\n')}`
+        : '';
+    const compoundRisksText = synthesisResult.compoundRisks.length > 0
+        ? `\n\nCompound Risks:\n${synthesisResult.compoundRisks.map((r) => `- [${r.severity.toUpperCase()}] ${r.description}`).join('\n')}`
+        : '';
+    return `You are making a final review decision based on synthesized findings from multiple reviewers.
+
+Return "approve" only when there are no critical or major findings.
+Return "request-changes" when there are any critical/major findings.
+Hard rule: if synthesized findings contain zero critical/major items, decision MUST be "approve".
+
+Provide:
+- decision: approve | request-changes
+- summary: 2-4 sentences, plain language
+- rationale: explain why the decision was made, referencing key findings or lack thereof
+
+Review context:
+${understanding}
+
+Synthesized findings:
+${findingsSummary}${contradictionsText}${compoundRisksText}
+`;
+};