@contextrail/code-review-agent 0.1.1 → 0.1.2-alpha.2

package/dist/output/summary-logger.d.ts

@@ -0,0 +1,3 @@
+import type { Logger } from '../logging/logger.js';
+import type { ReviewResult, ReviewerResult } from './schema.js';
+export declare const logReviewSummary: (log: Logger, result: ReviewResult, reviewerResults: ReviewerResult[]) => void;

package/dist/output/summary-logger.js

@@ -0,0 +1,81 @@
+export const logReviewSummary = (log, result, reviewerResults) => {
+    log.info('\n═══════════════════════════════════════════════════════════');
+    log.info('Review Summary');
+    log.info('═══════════════════════════════════════════════════════════');
+    log.info(`  Files reviewed: ${result.metadata.fileCount}`);
+    log.info(`  Reviewers executed: ${reviewerResults.length}`);
+    log.info(`  Total issue findings: ${result.summary.totalFindings}`);
+    log.info(`  Critical: ${result.summary.bySeverity.critical}`);
+    log.info(`  Major: ${result.summary.bySeverity.major}`);
+    log.info(`  Minor: ${result.summary.bySeverity.minor}`);
+    log.info(`  Info: ${result.summary.bySeverity.info}`);
+    log.info(`  Pass signals: ${result.summary.bySeverity.pass}`);
+    if (result.summary.totalFindings > 0) {
+        log.info('\n  Findings by reviewer:');
+        for (const [reviewer, count] of Object.entries(result.summary.byReviewer)) {
+            log.info(`    ${reviewer}: ${count} finding(s)`);
+        }
+    }
+    log.info(`\n  Decision: ${result.decision.decision.toUpperCase()}`);
+    log.info(`  Summary: ${result.decision.summary}`);
+    log.info(`  Rationale: ${result.decision.rationale}`);
+    const passReviewers = reviewerResults
+        .map((rr) => ({
+        reviewer: rr.reviewer,
+        passFinding: rr.findings.find((f) => f.severity === 'pass'),
+        notes: rr.notes,
+        validated: rr.validated,
+    }))
+        .filter((rr) => rr.validated && (rr.passFinding || rr.notes));
+    if (passReviewers.length > 0) {
+        log.info('\n  Reviewer pass summaries:');
+        for (const rr of passReviewers) {
+            const passLine = rr.notes?.trim() ?? rr.passFinding?.title ?? 'PASS';
+            log.info(`    ${rr.reviewer}: ${passLine.split('\n')[0] ?? passLine}`);
+        }
+    }
+    if (result.synthesis && result.synthesis.findings.length > 0) {
+        log.debug('\n  Deduplicated findings (synthesis):');
+        for (const finding of result.synthesis.findings) {
+            log.debug(`      [${finding.severity.toUpperCase()}] ${finding.title}`);
+            if (finding.file) {
+                log.debug(`        File: ${finding.file}${finding.line ? `:${finding.line}` : ''}`);
+            }
+            if (finding.sourceReviewers && finding.sourceReviewers.length > 0) {
+                log.debug(`        Source reviewers: ${finding.sourceReviewers.join(', ')}`);
+            }
+            if (finding.contextTitles && finding.contextTitles.length > 0) {
+                log.debug(`        ContextRail Standards: ${finding.contextTitles.join(', ')}`);
+            }
+            log.debug(`        ${finding.description}`);
+        }
+    }
+    else {
+        const hasAnyEntries = reviewerResults.some((rr) => rr.findings.length > 0);
+        if (hasAnyEntries) {
+            log.debug('\n  All findings:');
+            for (const rr of reviewerResults) {
+                if (rr.findings.length > 0) {
+                    log.debug(`\n    ${rr.reviewer}:`);
+                    for (const finding of rr.findings) {
+                        log.debug(`      [${finding.severity.toUpperCase()}] ${finding.title}`);
+                        if (finding.file) {
+                            log.debug(`        File: ${finding.file}${finding.line ? `:${finding.line}` : ''}`);
+                        }
+                        if (finding.contextTitles && finding.contextTitles.length > 0) {
+                            log.debug(`        ContextRail Standards: ${finding.contextTitles.join(', ')}`);
+                        }
+                        log.debug(`        ${finding.description}`);
+                    }
+                }
+            }
+        }
+    }
+    if (result.failures && result.failures.length > 0) {
+        log.warn('\n  Reviewer failures:');
+        for (const failure of result.failures) {
+            log.warn(`    ${failure.reviewer}: ${failure.message}`);
+        }
+    }
+    log.info('═══════════════════════════════════════════════════════════\n');
+};

package/dist/pipeline.d.ts

@@ -0,0 +1,25 @@
+import type { ValidatedReviewAgentConfig } from './config/index.js';
+import type { Logger } from './logging/logger.js';
+import { McpClient } from './mcp/client.js';
+export type PipelineInput = {
+    config: ValidatedReviewAgentConfig;
+    repoPath: string;
+    outputDir: string;
+    files?: string[];
+    from?: string;
+    to?: string;
+    prDescription?: string;
+    log: Logger;
+    onMcpClientReady?: (client: McpClient) => void;
+};
+export type PipelineResult = {
+    decision: string;
+    resultPath: string;
+    totalFindings: number;
+    hasValidationFailures: boolean;
+    failures: Array<{
+        reviewer: string;
+        message: string;
+    }>;
+};
+export declare const runReview: (input: PipelineInput) => Promise<PipelineResult>;

package/dist/pipeline.js

@@ -0,0 +1,276 @@
+import path from 'node:path';
+import { DEFAULT_ORCHESTRATOR_MODEL, DEFAULT_REVIEWER_MODEL } from './config/defaults.js';
+import { McpClient } from './mcp/client.js';
+import { createLlmService } from './llm/factory.js';
+import { buildReviewInputs, triagePr } from './review-inputs/index.js';
+import { runOrchestrator } from './orchestrator/agentic-orchestrator.js';
+import { runReviewerLoop } from './reviewers/executor.js';
+import { aggregateResults, writeResult, writeTokenBudgetMetrics } from './output/writer.js';
+import { logReviewSummary } from './output/summary-logger.js';
+import { metadataSchema, reviewerFindingsSchema } from './output/schema.js';
+import { generateReviewDecision, normalizeDecisionWithSynthesis, synthesizeFindings } from './output/aggregator.js';
+import { serializeError, toError } from './errors/error-utils.js';
+export const runReview = async (input) => {
+    const { config, repoPath, outputDir, files, from, to, prDescription, log, onMcpClientReady } = input;
+    log.info('Starting code review...');
+    log.info(`Repository: ${repoPath}`);
+    log.info(`Output: ${outputDir}`);
+    if (files && files.length > 0) {
+        log.info(`Files: ${files.join(', ')}`);
+    }
+    else {
+        log.info(`From: ${from}`);
+        log.info(`To: ${to}`);
+    }
+    const mcpClient = new McpClient({
+        serverUrl: config.mcpServerUrl,
+        authToken: config.mcpAuthToken,
+        clientName: 'code-review-agent',
+        clientVersion: '0.1.0',
+        logger: log,
+    });
+    onMcpClientReady?.(mcpClient);
+    // Create a single LLM service instance for the entire pipeline
+    const { service: llmService } = createLlmService({
+        openRouterApiKey: config.openRouterApiKey,
+        mcpClient,
+        logger: log,
+    });
+    try {
+        try {
+            await mcpClient.connect();
+            log.info('Connected to MCP server');
+        }
+        catch (error) {
+            const connectionError = toError(error);
+            log.error({
+                msg: 'Failed to connect to MCP server',
+                serverUrl: config.mcpServerUrl,
+                error: serializeError(connectionError),
+            });
+            throw new Error(`Failed to connect to MCP server at ${config.mcpServerUrl}: ${connectionError.message}`, {
+                cause: connectionError,
+            });
+        }
+        // Build review inputs
+        log.info('Building review inputs...');
+        const inputs = files && files.length > 0
+            ? await buildReviewInputs({
+                mode: 'file-list',
+                files,
+                basePath: repoPath,
+                surroundingContext: {
+                    enabled: true,
+                    maxTokensPerFile: config.maxTokensPerFile,
+                    contextLines: config.contextLines,
+                },
+            })
+            : await buildReviewInputs({
+                mode: 'diff',
+                repoPath,
+                from: from,
+                to: to,
+                surroundingContext: {
+                    enabled: true,
+                    maxTokensPerFile: config.maxTokensPerFile,
+                    contextLines: config.contextLines,
+                },
+            });
+        log.info(`Found ${inputs.files.length} files to review`);
+        if (inputs.files.length > 0) {
+            log.debug(`  Files: ${inputs.files.slice(0, 10).join(', ')}${inputs.files.length > 10 ? ` ... and ${inputs.files.length - 10} more` : ''}`);
+        }
+        // Triage PR to determine if it's trivial
+        const triageResult = triagePr(inputs);
+        log.info(`PR triage: ${triageResult.reason}`);
+        if (triageResult.isTrivial) {
+            log.info(`Trivial PR detected (${triageResult.isDocsOnly ? 'docs-only' : 'small'}). Skipping full reviewer flow.`);
+            // For trivial PRs, we still run orchestrator but with awareness
+            // The orchestrator can use this information to select fewer reviewers or skip entirely
+        }
+        // Run orchestrator
+        log.info('Running orchestrator...');
+        if (prDescription) {
+            log.debug('PR description provided, will be included in prompts');
+        }
+        if (config.reviewDomains && config.reviewDomains.length > 0) {
+            log.debug(`Review domains provided: ${config.reviewDomains.join(', ')}`);
+        }
+        const orchestratorOutput = await runOrchestrator(inputs, outputDir, {
+            mcpClient,
+            llmService,
+            config: {
+                openRouterApiKey: config.openRouterApiKey,
+                orchestratorModel: config.orchestratorModel ?? DEFAULT_ORCHESTRATOR_MODEL,
+                maxSteps: config.maxSteps,
+                prDescription,
+                reviewDomains: config.reviewDomains,
+            },
+            logger: log,
+        });
+        log.info(`Selected reviewers: ${orchestratorOutput.reviewers.join(', ')}`);
+        log.debug(`Orchestrator understanding:\n${orchestratorOutput.understanding}`);
+        // Run reviewers in parallel with progress logging
+        log.info(`Running ${orchestratorOutput.reviewers.length} reviewer(s) in parallel...`);
+        const reviewerFailures = [];
+        const reviewerResults = await Promise.all(orchestratorOutput.reviewers.map(async (reviewer) => {
+            const startTime = Date.now();
+            log.info(`[${reviewer}] Starting review...`);
+            try {
+                const rawFindings = await runReviewerLoop(reviewer, inputs, orchestratorOutput.understanding, outputDir, {
+                    mcpClient,
+                    llmService,
+                    config: {
+                        openRouterApiKey: config.openRouterApiKey,
+                        reviewerModel: config.reviewerModel ?? DEFAULT_REVIEWER_MODEL,
+                        criticModel: config.criticModel,
+                        maxSteps: config.maxSteps,
+                        maxIterations: config.maxIterations,
+                        prDescription,
+                        reviewDomains: config.reviewDomains,
+                    },
+                    logger: log,
+                });
+                const parsedFindings = reviewerFindingsSchema.safeParse(rawFindings);
+                if (!parsedFindings.success) {
+                    throw new Error(`Reviewer ${reviewer} returned invalid findings payload: ${parsedFindings.error.issues
+                        .slice(0, 3)
+                        .map((issue) => `${issue.path.join('.') || 'root'}: ${issue.message}`)
+                        .join('; ')}`, { cause: parsedFindings.error });
+                }
+                const findings = parsedFindings.data;
+                const result = {
+                    reviewer,
+                    findings: findings.findings,
+                    validated: findings.validated,
+                    notes: findings.notes ?? undefined,
+                };
+                const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+                log.info(`[${reviewer}] Completed in ${duration}s`);
+                const issueCount = findings.findings.filter((f) => f.severity !== 'pass').length;
+                const passCount = findings.findings.filter((f) => f.severity === 'pass').length;
+                if (issueCount === 0) {
+                    log.info(`  ✓ ${reviewer}: Clean pass (pass signals: ${passCount}, validated: ${findings.validated})`);
+                }
+                else {
+                    log.info(`  ✓ ${reviewer}: ${issueCount} issue(s) (pass signals: ${passCount}, validated: ${findings.validated})`);
+                }
+                log.debug(`    Findings: ${JSON.stringify(findings.findings, null, 2)}`);
+                if (findings.notes) {
+                    log.debug(`    Notes: ${findings.notes}`);
+                }
+                return result;
+            }
+            catch (error) {
+                const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+                const reviewerError = toError(error);
+                const message = reviewerError.message;
+                log.error({
+                    msg: `[${reviewer}] Failed after ${duration}s`,
+                    reviewer,
+                    durationSeconds: Number(duration),
+                    error: serializeError(reviewerError),
+                });
+                if (message.includes('No object generated') || message.includes('No output generated')) {
+                    log.error({
+                        msg: `[${reviewer}] TROUBLESHOOTING`,
+                        reviewer,
+                        guidance: [
+                            'The model may not support structured output well.',
+                            'Try using a different model (e.g., anthropic/claude-haiku-4.5).',
+                            'Check model compatibility with structured output.',
+                            "Review the model's response format requirements.",
+                        ],
+                    });
+                }
+                reviewerFailures.push({ reviewer, message });
+                return {
+                    reviewer,
+                    findings: [],
+                    validated: false,
+                    notes: `Error: ${message}`,
+                };
+            }
+        }));
+        // Aggregate results
+        log.info('Aggregating results...');
+        log.debug(`  Total issue findings to aggregate: ${reviewerResults.reduce((sum, rr) => sum + rr.findings.filter((f) => f.severity !== 'pass').length, 0)}`);
+        log.debug(`  Total pass signals to aggregate: ${reviewerResults.reduce((sum, rr) => sum + rr.findings.filter((f) => f.severity === 'pass').length, 0)}`);
+        log.debug(`  Reviewers validated: ${reviewerResults.filter((rr) => rr.validated).length}/${reviewerResults.length}`);
+        const metadata = metadataSchema.parse({
+            timestamp: new Date().toISOString(),
+            mode: inputs.mode,
+            fileCount: inputs.files.length,
+        });
+        // Synthesize findings across reviewers (deduplication, contradictions, compound risks)
+        log.info(`Synthesis pass starting (model: ${config.orchestratorModel ?? DEFAULT_ORCHESTRATOR_MODEL}, reviewers: ${reviewerResults.length})`);
+        const synthesisResult = await synthesizeFindings(reviewerResults, {
+            llmService,
+            model: config.orchestratorModel ?? DEFAULT_ORCHESTRATOR_MODEL,
+            maxSteps: config.aggregationMaxSteps,
+            logger: log,
+        });
+        log.info(`Synthesis pass complete: ${synthesisResult.synthesis.findings.length} deduped findings, ${synthesisResult.synthesis.contradictions.length} contradictions, ${synthesisResult.synthesis.compoundRisks.length} compound risks`);
+        log.debug(`  Synthesis: ${synthesisResult.synthesis.findings.length} deduplicated findings`);
+        log.debug(`  Contradictions: ${synthesisResult.synthesis.contradictions.length}`);
+        log.debug(`  Compound risks: ${synthesisResult.synthesis.compoundRisks.length}`);
+        const synthesisSeverityCounts = synthesisResult.synthesis.findings.reduce((acc, finding) => {
+            acc[finding.severity] += 1;
+            return acc;
+        }, { critical: 0, major: 0, minor: 0, info: 0, pass: 0 });
+        log.debug(`  Synthesis severity: ${JSON.stringify(synthesisSeverityCounts)}`);
+        // Generate review decision based on synthesized findings
+        log.info(`Decision pass starting (model: ${config.orchestratorModel ?? DEFAULT_ORCHESTRATOR_MODEL}, synthesis findings: ${synthesisResult.synthesis.findings.length})`);
+        const decisionResult = await generateReviewDecision(orchestratorOutput.understanding, synthesisResult.synthesis, {
+            llmService,
+            model: config.orchestratorModel ?? DEFAULT_ORCHESTRATOR_MODEL,
+            maxSteps: config.aggregationMaxSteps,
+            logger: log,
+        });
+        const normalizedDecision = normalizeDecisionWithSynthesis(decisionResult.decision, synthesisResult.synthesis);
+        const decisionEvidence = {
+            findings: synthesisResult.synthesis.findings.length,
+            blockingFindings: synthesisResult.synthesis.findings.filter((f) => f.severity === 'critical' || f.severity === 'major').length,
+            contradictions: synthesisResult.synthesis.contradictions.length,
+            compoundRisks: synthesisResult.synthesis.compoundRisks.length,
+            modelDecision: decisionResult.decision.decision,
+            normalizedDecision: normalizedDecision.decision,
+        };
+        log.debug(`  Decision evidence: ${JSON.stringify(decisionEvidence)}`);
+        if (normalizedDecision.decision !== decisionResult.decision.decision) {
+            log.warn(`Decision normalized from ${decisionResult.decision.decision} to ${normalizedDecision.decision} to match synthesized findings.`);
+        }
+        log.info(`Decision pass complete: ${normalizedDecision.decision}`);
+        log.debug(`  Aggregation decision: ${normalizedDecision.decision}`);
+        log.debug(`  Decision summary: ${normalizedDecision.summary}`);
+        log.debug(`  Decision rationale: ${normalizedDecision.rationale}`);
+        const result = aggregateResults(metadata, orchestratorOutput.understanding, normalizedDecision, reviewerResults, reviewerFailures, synthesisResult.synthesis);
+        // Write result.json
+        await writeResult(outputDir, result);
+        const resultPath = path.join(outputDir, 'result.json');
+        log.info(`Results written to ${resultPath}`);
+        log.debug(`  Full review results available at: ${resultPath}`);
+        // Write token budget metrics
+        const aggregationUsage = [];
+        if (synthesisResult.usage) {
+            aggregationUsage.push(synthesisResult.usage);
+        }
+        if (decisionResult.usage) {
+            aggregationUsage.push(decisionResult.usage);
+        }
+        await writeTokenBudgetMetrics(outputDir, orchestratorOutput.reviewers, aggregationUsage.length > 0 ? aggregationUsage : undefined);
+        log.info(`Token budget metrics written to ${path.join(outputDir, 'token-budget.json')}`);
+        // Print summary
+        logReviewSummary(log, result, reviewerResults);
+        return {
+            decision: result.decision.decision,
+            resultPath,
+            totalFindings: result.summary.totalFindings,
+            hasValidationFailures: reviewerResults.some((rr) => !rr.validated),
+            failures: result.failures ?? [],
+        };
+    }
+    finally {
+        await mcpClient.close();
+    }
+};

package/dist/prompts/blocks.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Severity calibration block with definitions and examples for each severity level.
+ * This block is injected into reviewer system prompts to ensure consistent severity assignment.
+ */
+export declare const SEVERITY_CALIBRATION_BLOCK = "\n## Severity Calibration\n\nYou must assign severity levels accurately based on the following definitions and examples:\n\n### Critical\n**Definition**: Blocks deployment, active exploit path, or data corruption risk. Findings that could lead to security breaches, data loss, or system compromise.\n\n**Examples**:\n- SQL injection vulnerability: `const query = `SELECT * FROM users WHERE id = ${userInput}`;` (user input directly interpolated)\n- Authentication bypass: `if (user.role === 'admin' || user.id === 1) { grantAccess(); }` (hardcoded admin check)\n- Missing input validation on sensitive operations: `await db.delete(userId);` (no validation that userId belongs to requester)\n\n**When to use**: Only when there is a clear exploit path or risk of data corruption/integrity violation.\n\n### Major\n**Definition**: Significant bug, breaks functionality, or violates established patterns. Findings that cause incorrect behavior or violate architectural standards.\n\n**Examples**:\n- Missing error handling: `const data = await fetch(url); return data.json();` (no try-catch, will crash on network error)\n- Tight coupling: `import { DatabaseConnection } from './db'; class UserService { private db = new DatabaseConnection(); }` (direct instantiation, violates dependency injection)\n- Race condition: `let count = 0; async function increment() { count++; await save(count); }` (non-atomic increment)\n\n**When to use**: When functionality is broken or architectural patterns are violated, but no immediate security/data risk.\n\n### Minor\n**Definition**: Code quality issue, convention violation, or maintainability concern. Findings that don't break functionality but reduce code quality.\n\n**Examples**:\n- Magic numbers: `if (user.age > 18) { ... }` (should be `const MIN_ADULT_AGE = 18`)\n- Inconsistent naming: `function getUserData() { ... }` but `function fetch_user_info() { ... }` (mixed naming conventions)\n- Missing JSDoc: `function calculateTotal(items) { ... }` (no documentation for complex logic)\n\n**When to use**: Code quality, readability, or maintainability issues that don't affect functionality.\n\n### Info\n**Definition**: Observation, suggestion, or educational note. Findings that provide helpful context or suggestions without indicating a problem.\n\n**Examples**:\n- Performance suggestion: `// Consider caching this query result if called frequently`\n- Pattern suggestion: `// This could use the Repository pattern for better testability`\n- Documentation opportunity: `// This algorithm implements the Fisher-Yates shuffle`\n\n**When to use**: Helpful suggestions or observations that don't indicate actual problems.\n";
+/**
+ * Severity validation rules for critic pass (iteration 2+).
+ * These rules help the critic validate and potentially downgrade severity.
+ */
+export declare const SEVERITY_VALIDATION_RULES = "\n## Severity Validation Rules\n\nDuring the critic pass, validate each finding's severity against these rules:\n\n1. **Critical findings MUST have exploit path or data integrity evidence**\n   - If a critical finding lacks a clear exploit path or data corruption risk described in the rationale, downgrade to major\n   - Example: \"SQL injection\" without showing how user input reaches the query \u2192 downgrade to major\n\n2. **Major findings MUST demonstrate functional impact**\n   - If a major finding doesn't show how functionality is broken or patterns violated, downgrade to minor\n   - Example: \"Missing error handling\" without showing what breaks \u2192 downgrade to minor\n\n3. **Minor findings MUST indicate code quality impact**\n   - If a minor finding is just a style preference without maintainability impact, consider downgrade to info\n   - Example: \"Use const instead of let\" without explaining why \u2192 consider info\n\n4. **Downgrade rules**:\n   - Critical \u2192 Major: No exploit path or data integrity risk described\n   - Major \u2192 Minor: No functional impact demonstrated\n   - Minor \u2192 Info: No code quality/maintainability impact shown\n\n5. **Never upgrade severity** - Only downgrade if evidence doesn't support the assigned level\n";
+/**
+ * ContextRail tooling workflow requirements.
+ * Forces reviewers to ground findings in retrieved contexts instead of guessing IDs/titles.
+ */
+export declare const CONTEXTRAIL_TOOLING_BLOCK = "\n## ContextRail Standards Workflow (Required)\n\nWhen you identify potential issues, you MUST ground them in retrieved ContextRail standards:\n\n1. Use `search_contexts` first to discover relevant standards for this change.\n2. Use `get_context` for each context you plan to cite in findings.\n3. Use `resolve_dependencies` when cited contexts have required dependencies.\n4. Perform at least one `search_contexts` call before finalizing your findings.\n\nAttribution rules:\n- NEVER invent context IDs or titles.\n- Only include `contextIdsUsed`, `contextIdsViolated`, and `contextTitles` from contexts you actually retrieved.\n- If no relevant ContextRail standard exists after tool lookup, set those fields to `null` (not empty arrays) and explain that briefly in `rationale`.\n";
+/**
+ * Compact output contract optimized for structured-output reliability.
+ * Keeps formatting constraints in one place for both standard and critic prompts.
+ */
+export declare const OUTPUT_CONTRACT_BLOCK = "\n## Output Contract (Strict)\n\nReturn a JSON object with:\n- `findings`: array\n- `validated`: boolean\n- `notes`: string | null\n\nFor each finding:\n- Required keys: `severity`, `title`, `description`, `rationale`\n- Optional-but-required-by-schema keys: `suggestedFix`, `file`, `line`, `endLine`, `contextIdsUsed`, `contextIdsViolated`, `contextTitles`\n\nSchema compatibility rules:\n- Include all keys (never omit)\n- Use `null` when a value is not available\n- Use `null` (not empty arrays) for context attribution fields when no standards apply\n";
+/**
+ * Final guardrail checklist near generation point.
+ * Repeats only non-negotiables to reduce mid-prompt loss on long inputs.
+ */
+export declare const FINAL_CHECKLIST_BLOCK = "\n## Final Checklist (Must Pass)\n1. Every finding is supported by concrete code/diff evidence.\n2. ContextRail workflow was used (`search_contexts` -> `get_context` -> `resolve_dependencies` as needed).\n3. Context attribution fields only reference retrieved contexts (or are `null`).\n4. Severity is calibrated to evidence.\n5. Output strictly matches the JSON contract, and `notes` summarizes retrieved contexts (or none found).\n";

package/dist/prompts/blocks.js

@@ -0,0 +1,129 @@
+/**
+ * Severity calibration block with definitions and examples for each severity level.
+ * This block is injected into reviewer system prompts to ensure consistent severity assignment.
+ */
+export const SEVERITY_CALIBRATION_BLOCK = `
+## Severity Calibration
+
+You must assign severity levels accurately based on the following definitions and examples:
+
+### Critical
+**Definition**: Blocks deployment, active exploit path, or data corruption risk. Findings that could lead to security breaches, data loss, or system compromise.
+
+**Examples**:
+- SQL injection vulnerability: \`const query = \`SELECT * FROM users WHERE id = \${userInput}\`;\` (user input directly interpolated)
+- Authentication bypass: \`if (user.role === 'admin' || user.id === 1) { grantAccess(); }\` (hardcoded admin check)
+- Missing input validation on sensitive operations: \`await db.delete(userId);\` (no validation that userId belongs to requester)
+
+**When to use**: Only when there is a clear exploit path or risk of data corruption/integrity violation.
+
+### Major
+**Definition**: Significant bug, breaks functionality, or violates established patterns. Findings that cause incorrect behavior or violate architectural standards.
+
+**Examples**:
+- Missing error handling: \`const data = await fetch(url); return data.json();\` (no try-catch, will crash on network error)
+- Tight coupling: \`import { DatabaseConnection } from './db'; class UserService { private db = new DatabaseConnection(); }\` (direct instantiation, violates dependency injection)
+- Race condition: \`let count = 0; async function increment() { count++; await save(count); }\` (non-atomic increment)
+
+**When to use**: When functionality is broken or architectural patterns are violated, but no immediate security/data risk.
+
+### Minor
+**Definition**: Code quality issue, convention violation, or maintainability concern. Findings that don't break functionality but reduce code quality.
+
+**Examples**:
+- Magic numbers: \`if (user.age > 18) { ... }\` (should be \`const MIN_ADULT_AGE = 18\`)
+- Inconsistent naming: \`function getUserData() { ... }\` but \`function fetch_user_info() { ... }\` (mixed naming conventions)
+- Missing JSDoc: \`function calculateTotal(items) { ... }\` (no documentation for complex logic)
+
+**When to use**: Code quality, readability, or maintainability issues that don't affect functionality.
+
+### Info
+**Definition**: Observation, suggestion, or educational note. Findings that provide helpful context or suggestions without indicating a problem.
+
+**Examples**:
+- Performance suggestion: \`// Consider caching this query result if called frequently\`
+- Pattern suggestion: \`// This could use the Repository pattern for better testability\`
+- Documentation opportunity: \`// This algorithm implements the Fisher-Yates shuffle\`
+
+**When to use**: Helpful suggestions or observations that don't indicate actual problems.
+`;
+/**
+ * Severity validation rules for critic pass (iteration 2+).
+ * These rules help the critic validate and potentially downgrade severity.
+ */
+export const SEVERITY_VALIDATION_RULES = `
+## Severity Validation Rules
+
+During the critic pass, validate each finding's severity against these rules:
+
+1. **Critical findings MUST have exploit path or data integrity evidence**
+   - If a critical finding lacks a clear exploit path or data corruption risk described in the rationale, downgrade to major
+   - Example: "SQL injection" without showing how user input reaches the query → downgrade to major
+
+2. **Major findings MUST demonstrate functional impact**
+   - If a major finding doesn't show how functionality is broken or patterns violated, downgrade to minor
+   - Example: "Missing error handling" without showing what breaks → downgrade to minor
+
+3. **Minor findings MUST indicate code quality impact**
+   - If a minor finding is just a style preference without maintainability impact, consider downgrade to info
+   - Example: "Use const instead of let" without explaining why → consider info
+
+4. **Downgrade rules**:
+   - Critical → Major: No exploit path or data integrity risk described
+   - Major → Minor: No functional impact demonstrated
+   - Minor → Info: No code quality/maintainability impact shown
+
+5. **Never upgrade severity** - Only downgrade if evidence doesn't support the assigned level
+`;
+/**
+ * ContextRail tooling workflow requirements.
+ * Forces reviewers to ground findings in retrieved contexts instead of guessing IDs/titles.
+ */
+export const CONTEXTRAIL_TOOLING_BLOCK = `
+## ContextRail Standards Workflow (Required)
+
+When you identify potential issues, you MUST ground them in retrieved ContextRail standards:
+
+1. Use \`search_contexts\` first to discover relevant standards for this change.
+2. Use \`get_context\` for each context you plan to cite in findings.
+3. Use \`resolve_dependencies\` when cited contexts have required dependencies.
+4. Perform at least one \`search_contexts\` call before finalizing your findings.
+
+Attribution rules:
+- NEVER invent context IDs or titles.
+- Only include \`contextIdsUsed\`, \`contextIdsViolated\`, and \`contextTitles\` from contexts you actually retrieved.
+- If no relevant ContextRail standard exists after tool lookup, set those fields to \`null\` (not empty arrays) and explain that briefly in \`rationale\`.
+`;
+/**
+ * Compact output contract optimized for structured-output reliability.
+ * Keeps formatting constraints in one place for both standard and critic prompts.
+ */
+export const OUTPUT_CONTRACT_BLOCK = `
+## Output Contract (Strict)
+
+Return a JSON object with:
+- \`findings\`: array
+- \`validated\`: boolean
+- \`notes\`: string | null
+
+For each finding:
+- Required keys: \`severity\`, \`title\`, \`description\`, \`rationale\`
+- Optional-but-required-by-schema keys: \`suggestedFix\`, \`file\`, \`line\`, \`endLine\`, \`contextIdsUsed\`, \`contextIdsViolated\`, \`contextTitles\`
+
+Schema compatibility rules:
+- Include all keys (never omit)
+- Use \`null\` when a value is not available
+- Use \`null\` (not empty arrays) for context attribution fields when no standards apply
+`;
+/**
+ * Final guardrail checklist near generation point.
+ * Repeats only non-negotiables to reduce mid-prompt loss on long inputs.
+ */
+export const FINAL_CHECKLIST_BLOCK = `
+## Final Checklist (Must Pass)
+1. Every finding is supported by concrete code/diff evidence.
+2. ContextRail workflow was used (\`search_contexts\` -> \`get_context\` -> \`resolve_dependencies\` as needed).
+3. Context attribution fields only reference retrieved contexts (or are \`null\`).
+4. Severity is calibrated to evidence.
+5. Output strictly matches the JSON contract, and \`notes\` summarizes retrieved contexts (or none found).
+`;

package/dist/prompts/decision.d.ts

@@ -0,0 +1,15 @@
+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/prompts/decision.js

@@ -0,0 +1,30 @@
+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}
+`;
+};

package/dist/prompts/index.d.ts

@@ -0,0 +1,5 @@
+export * from './blocks.js';
+export * from './reviewer.js';
+export * from './synthesis.js';
+export * from './decision.js';
+export * from './orchestrator.js';

package/dist/prompts/index.js

@@ -0,0 +1,5 @@
+export * from './blocks.js';
+export * from './reviewer.js';
+export * from './synthesis.js';
+export * from './decision.js';
+export * from './orchestrator.js';

package/dist/{orchestrator/prompts.d.ts → prompts/orchestrator.d.ts}

@@ -8,7 +8,7 @@ import type { FilePatterns } from '../review-inputs/file-patterns.js';
  * @param contextIds - The context IDs.
  * @returns The activity content.
  */
-declare const generateActivityContentPrompt: (understanding: string, reviewers: string[], toolCalls: Array<{
+export declare const generateActivityContentPrompt: (understanding: string, reviewers: string[], toolCalls: Array<{
     tool: string;
     input?: unknown;
 }>, contextIds: string[]) => string;
@@ -21,5 +21,4 @@ declare const generateActivityContentPrompt: (understanding: string, reviewers:
  * @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 };
+export declare const generateUserMessagePrompt: (inputs: ReviewInputs, availableReviewers: string[], prDescription?: string, reviewerFilePatterns?: Map<string, FilePatterns | undefined>, reviewDomains?: string[]) => string;

package/dist/{orchestrator/prompts.js → prompts/orchestrator.js}

@@ -9,7 +9,7 @@ import dedent from 'dedent';
  * @param contextIds - The context IDs.
  * @returns The activity content.
  */
-const generateActivityContentPrompt = (understanding, reviewers, toolCalls, contextIds) => dedent(`# Orchestration Activity Log
+export const generateActivityContentPrompt = (understanding, reviewers, toolCalls, contextIds) => dedent(`# Orchestration Activity Log
 
             **Phase**: Orchestration
             **Completed**: ${new Date().toISOString()}
@@ -39,7 +39,7 @@ const generateActivityContentPrompt = (understanding, reviewers, toolCalls, cont
  * @param reviewDomains - Optional review focus domains to prioritize.
  * @returns The user message.
  */
-const generateUserMessagePrompt = (inputs, availableReviewers, prDescription, reviewerFilePatterns, reviewDomains) => {
+export 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
@@ -95,4 +95,3 @@ ${availableReviewers
     - If review focus domains are provided, prioritize reviewers and rationale aligned to those domains.
 `);
 };
-export { generateActivityContentPrompt, generateUserMessagePrompt };