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

package/dist/reviewers/persistence.js

@@ -0,0 +1,55 @@
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { appendActivity } from './progress-tracker.js';
+export const logIteration = async (reviewersDir, reviewer, iteration, findings, toolCalls, contextIds) => {
+    await appendActivity(reviewersDir, reviewer, `## Iteration ${iteration}
+
+**Status**: ${findings.validated ? 'Validated' : 'Needs re-review'}
+
+**Findings Count**: ${findings.findings.length}
+
+**ContextRail Contexts Used**:
+${contextIds.length > 0 ? contextIds.map((id) => `- ${id}`).join('\n') : 'None'}
+
+**Tool Calls**:
+${toolCalls.length > 0 ? toolCalls.map((tc) => `- **${tc.tool}**: ${JSON.stringify(tc.input, null, 2)}`).join('\n\n') : 'None'}
+
+${findings.notes ? `**Notes**:\n${findings.notes}\n` : ''}`);
+};
+export const logContinuation = async (reviewersDir, reviewer, nextIteration) => {
+    await appendActivity(reviewersDir, reviewer, `**Action**: Findings not validated, continuing to iteration ${nextIteration}`);
+};
+export const writeFindings = async (reviewerDir, findings) => {
+    await writeFile(path.join(reviewerDir, 'findings.json'), JSON.stringify(findings, null, 2), 'utf-8');
+};
+export const logCompletion = async (reviewersDir, reviewer, iteration, findings) => {
+    await appendActivity(reviewersDir, reviewer, `## Completed
+
+**Total Iterations**: ${iteration}
+**Final Findings Count**: ${findings.findings.length}
+**Status**: Validated and complete`);
+};
+/**
+ * Write token usage metrics for a reviewer.
+ */
+export const writeTokenMetrics = async (reviewerDir, reviewer, iterationTokenData) => {
+    if (iterationTokenData.length === 0) {
+        return; // No token usage data to write
+    }
+    // Calculate total usage across all iterations
+    const totalUsage = {
+        promptTokens: iterationTokenData.reduce((sum, it) => sum + it.usage.promptTokens, 0),
+        completionTokens: iterationTokenData.reduce((sum, it) => sum + it.usage.completionTokens, 0),
+        totalTokens: iterationTokenData.reduce((sum, it) => sum + it.usage.totalTokens, 0),
+    };
+    const metrics = {
+        reviewer,
+        totalUsage,
+        iterations: iterationTokenData.map((it) => ({
+            iteration: it.iteration,
+            usage: it.usage,
+            chunks: it.chunks,
+        })),
+    };
+    await writeFile(path.join(reviewerDir, 'token-budget.json'), JSON.stringify(metrics, null, 2), 'utf-8');
+};

package/dist/reviewers/progress-tracker.d.ts

@@ -0,0 +1,115 @@
+import { z } from 'zod';
+/**
+ * Progress state schema for reviewer execution tracking.
+ * Based on context://agentic/execution/progress-tracking
+ */
+export declare const progressSchema: z.ZodObject<{
+    reviewer: z.ZodString;
+    status: z.ZodEnum<["pending", "in-progress", "done", "blocked"]>;
+    attempts: z.ZodNumber;
+    startedAt: z.ZodOptional<z.ZodString>;
+    lastAttempt: z.ZodOptional<z.ZodString>;
+    completedAt: z.ZodOptional<z.ZodString>;
+    lastFailure: z.ZodOptional<z.ZodObject<{
+        gate: z.ZodString;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+        gate: string;
+        details?: string | undefined;
+    }, {
+        message: string;
+        gate: string;
+        details?: string | undefined;
+    }>>;
+    evidence: z.ZodArray<z.ZodString, "many">;
+    notes: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "in-progress" | "done" | "blocked";
+    reviewer: string;
+    attempts: number;
+    evidence: string[];
+    notes?: string | undefined;
+    startedAt?: string | undefined;
+    lastAttempt?: string | undefined;
+    completedAt?: string | undefined;
+    lastFailure?: {
+        message: string;
+        gate: string;
+        details?: string | undefined;
+    } | undefined;
+}, {
+    status: "pending" | "in-progress" | "done" | "blocked";
+    reviewer: string;
+    attempts: number;
+    evidence: string[];
+    notes?: string | undefined;
+    startedAt?: string | undefined;
+    lastAttempt?: string | undefined;
+    completedAt?: string | undefined;
+    lastFailure?: {
+        message: string;
+        gate: string;
+        details?: string | undefined;
+    } | undefined;
+}>;
+export type Progress = z.infer<typeof progressSchema>;
+/**
+ * Initialize progress.json for a reviewer.
+ * Creates the initial state file with default values.
+ *
+ * @param outputDir - Base output directory
+ * @param reviewer - Reviewer name
+ * @returns Initial progress state
+ */
+export declare const initProgress: (outputDir: string, reviewer: string) => Promise<Progress>;
+/**
+ * Read current progress state for a reviewer.
+ * Returns default state if file doesn't exist.
+ *
+ * @param outputDir - Base output directory
+ * @param reviewer - Reviewer name
+ * @returns Current progress state
+ */
+export declare const readProgress: (outputDir: string, reviewer: string) => Promise<Progress>;
+/**
+ * Update progress state atomically.
+ * Uses temp file + rename pattern to prevent corruption.
+ *
+ * @param outputDir - Base output directory
+ * @param reviewer - Reviewer name
+ * @param updates - Partial progress updates
+ * @returns Updated progress state
+ */
+export declare const updateProgress: (outputDir: string, reviewer: string, updates: Partial<Progress>) => Promise<Progress>;
+/**
+ * Format ISO 8601 timestamp.
+ * Utility for consistent timestamp formatting.
+ *
+ * @returns ISO 8601 timestamp string
+ */
+export declare const formatTimestamp: () => string;
+/**
+ * Append entry to activity.md log.
+ * Creates file if it doesn't exist, appends otherwise.
+ *
+ * @param outputDir - Base output directory
+ * @param reviewer - Reviewer name
+ * @param entry - Activity log entry (markdown formatted)
+ */
+export declare const appendActivity: (outputDir: string, reviewer: string, entry: string) => Promise<void>;
+/**
+ * Append failure entry to failures.md log.
+ * Creates file if it doesn't exist, appends otherwise.
+ *
+ * @param outputDir - Base output directory
+ * @param reviewer - Reviewer name
+ * @param failure - Failure information object
+ */
+export declare const appendFailure: (outputDir: string, reviewer: string, failure: {
+    gate: string;
+    message: string;
+    details?: string;
+    timestamp?: string;
+}) => Promise<void>;

package/dist/reviewers/progress-tracker.js

@@ -0,0 +1,194 @@
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+/**
+ * Progress state schema for reviewer execution tracking.
+ * Based on context://agentic/execution/progress-tracking
+ */
+export const progressSchema = z.object({
+    reviewer: z.string().describe('Reviewer name'),
+    status: z.enum(['pending', 'in-progress', 'done', 'blocked']).describe('Current execution status'),
+    attempts: z.number().int().min(0).describe('Number of attempts made'),
+    startedAt: z.string().datetime().optional().describe('ISO timestamp when execution started'),
+    lastAttempt: z.string().datetime().optional().describe('ISO timestamp of last attempt'),
+    completedAt: z.string().datetime().optional().describe('ISO timestamp when execution completed'),
+    lastFailure: z
+        .object({
+        gate: z.string().describe('Gate that failed (build|test|lint|types|contextrail)'),
+        message: z.string().describe('Error message'),
+        details: z.string().optional().describe('Additional error details'),
+    })
+        .optional()
+        .describe('Last failure information if status is not done'),
+    evidence: z.array(z.string()).describe('Evidence links (file paths, test files, etc.)'),
+    notes: z.string().optional().describe('Additional notes'),
+});
+/**
+ * Initialize progress.json for a reviewer.
+ * Creates the initial state file with default values.
+ *
+ * @param outputDir - Base output directory
+ * @param reviewer - Reviewer name
+ * @returns Initial progress state
+ */
+export const initProgress = async (outputDir, reviewer) => {
+    const reviewerDir = path.join(outputDir, reviewer);
+    await mkdir(reviewerDir, { recursive: true });
+    const progress = {
+        reviewer,
+        status: 'pending',
+        attempts: 0,
+        evidence: [],
+    };
+    await writeProgressAtomically(reviewerDir, progress);
+    return progress;
+};
+/**
+ * Read current progress state for a reviewer.
+ * Returns default state if file doesn't exist.
+ *
+ * @param outputDir - Base output directory
+ * @param reviewer - Reviewer name
+ * @returns Current progress state
+ */
+export const readProgress = async (outputDir, reviewer) => {
+    const reviewerDir = path.join(outputDir, reviewer);
+    const progressPath = path.join(reviewerDir, 'progress.json');
+    try {
+        const content = await readFile(progressPath, 'utf-8');
+        const parsed = JSON.parse(content);
+        return progressSchema.parse(parsed);
+    }
+    catch (error) {
+        // If file doesn't exist or is invalid, return default state
+        if (error.code === 'ENOENT') {
+            return {
+                reviewer,
+                status: 'pending',
+                attempts: 0,
+                evidence: [],
+            };
+        }
+        throw error;
+    }
+};
+/**
+ * Update progress state atomically.
+ * Uses temp file + rename pattern to prevent corruption.
+ *
+ * @param outputDir - Base output directory
+ * @param reviewer - Reviewer name
+ * @param updates - Partial progress updates
+ * @returns Updated progress state
+ */
+export const updateProgress = async (outputDir, reviewer, updates) => {
+    const reviewerDir = path.join(outputDir, reviewer);
+    await mkdir(reviewerDir, { recursive: true });
+    const current = await readProgress(outputDir, reviewer);
+    const updated = {
+        ...current,
+        ...updates,
+        reviewer, // Ensure reviewer name is preserved
+    };
+    // Validate updated state
+    const validated = progressSchema.parse(updated);
+    await writeProgressAtomically(reviewerDir, validated);
+    return validated;
+};
+/**
+ * Atomic write pattern: write to temp file, then rename.
+ * Prevents corruption if process is interrupted.
+ *
+ * @param reviewerDir - Reviewer-specific directory
+ * @param progress - Progress state to write
+ */
+const writeProgressAtomically = async (reviewerDir, progress) => {
+    const progressPath = path.join(reviewerDir, 'progress.json');
+    const tempPath = `${progressPath}.tmp.${randomUUID()}`;
+    try {
+        // Write to temp file
+        await writeFile(tempPath, JSON.stringify(progress, null, 2), 'utf-8');
+        // Atomic rename
+        await rename(tempPath, progressPath);
+    }
+    catch (error) {
+        // Clean up temp file on error
+        try {
+            await unlink(tempPath);
+        }
+        catch {
+            // Temp file doesn't exist or already cleaned up, ignore
+        }
+        throw error;
+    }
+};
+/**
+ * Format ISO 8601 timestamp.
+ * Utility for consistent timestamp formatting.
+ *
+ * @returns ISO 8601 timestamp string
+ */
+export const formatTimestamp = () => {
+    return new Date().toISOString();
+};
+/**
+ * Append entry to activity.md log.
+ * Creates file if it doesn't exist, appends otherwise.
+ *
+ * @param outputDir - Base output directory
+ * @param reviewer - Reviewer name
+ * @param entry - Activity log entry (markdown formatted)
+ */
+export const appendActivity = async (outputDir, reviewer, entry) => {
+    const reviewerDir = path.join(outputDir, reviewer);
+    await mkdir(reviewerDir, { recursive: true });
+    const activityPath = path.join(reviewerDir, 'activity.md');
+    const timestamp = formatTimestamp();
+    const entryWithTimestamp = `\n## ${timestamp}\n\n${entry}\n`;
+    try {
+        // Read existing content
+        const existing = await readFile(activityPath, 'utf-8');
+        await writeFile(activityPath, existing + entryWithTimestamp, 'utf-8');
+    }
+    catch (error) {
+        // File doesn't exist, create new
+        if (error.code === 'ENOENT') {
+            const header = `# Activity Log\n\n**Reviewer**: ${reviewer}\n**Started**: ${timestamp}\n`;
+            await writeFile(activityPath, header + entryWithTimestamp, 'utf-8');
+        }
+        else {
+            throw error;
+        }
+    }
+};
+/**
+ * Append failure entry to failures.md log.
+ * Creates file if it doesn't exist, appends otherwise.
+ *
+ * @param outputDir - Base output directory
+ * @param reviewer - Reviewer name
+ * @param failure - Failure information object
+ */
+export const appendFailure = async (outputDir, reviewer, failure) => {
+    const reviewerDir = path.join(outputDir, reviewer);
+    await mkdir(reviewerDir, { recursive: true });
+    const failuresPath = path.join(reviewerDir, 'failures.md');
+    const timestamp = failure.timestamp ?? formatTimestamp();
+    const failureEntry = `\n## Failure — ${timestamp}\n\n**Gate Failed**: ${failure.gate}\n\n**Error**:\n\`\`\`\n${failure.message}\n\`\`\`\n\n${failure.details ? `**Details**:\n\n${failure.details}\n\n` : ''}---\n`;
+    try {
+        // Read existing content
+        const existing = await readFile(failuresPath, 'utf-8');
+        await writeFile(failuresPath, existing + failureEntry, 'utf-8');
+    }
+    catch (error) {
+        // File doesn't exist, create new
+        if (error.code === 'ENOENT') {
+            const header = `# Failures Log\n\n**Reviewer**: ${reviewer}\n\n`;
+            await writeFile(failuresPath, header + failureEntry, 'utf-8');
+        }
+        else {
+            throw error;
+        }
+    }
+};

package/dist/reviewers/prompt.d.ts

@@ -0,0 +1,42 @@
+import { type ReviewInputs } from '../review-inputs/index.js';
+import type { ReviewerFindings } from '../output/schema.js';
+export type PromptMessage = {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+};
+/**
+ * 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";
+export declare const buildPromptMessages: (promptResult: {
+    messages: {
+        role: string;
+        content: {
+            type: string;
+            text?: string;
+        };
+    }[];
+    metadata?: unknown;
+}) => PromptMessage[];
+export declare const buildReviewerUserMessage: (inputs: ReviewInputs, understanding: string, iteration: number, findings: ReviewerFindings | null, prDescription?: string, reviewDomains?: string[]) => string;

package/dist/reviewers/prompt.js

@@ -0,0 +1,246 @@
+import { isDiffInputs } from '../review-inputs/index.js';
+/**
+ * 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).
+`;
+export const buildPromptMessages = (promptResult) => {
+    return promptResult.messages.map((message) => {
+        const role = message.role === 'user' ? 'user' : message.role === 'assistant' ? 'assistant' : 'system';
+        let content = message.content.type === 'text' ? (message.content.text ?? '') : '';
+        // Inject severity calibration block into system prompts
+        if (role === 'system' && content) {
+            content = `${content}\n\n${SEVERITY_CALIBRATION_BLOCK}`;
+        }
+        return { role, content };
+    });
+};
+/**
+ * Build a critic prompt that challenges findings from a previous iteration.
+ * The critic pass validates findings, removes false positives, and enforces evidence/standards.
+ */
+const buildCriticPrompt = (inputs, understanding, findings, prDescription, reviewDomains) => {
+    const diffBlock = isDiffInputs(inputs)
+        ? `\nDiffs:\n${Object.entries(inputs.diffs)
+            .map(([file, diff]) => `\n## ${file}\n\`\`\`diff\n${diff}\n\`\`\``)
+            .join('\n')}`
+        : '';
+    const contextBlock = inputs.context && Object.keys(inputs.context).length > 0
+        ? `\n\nSurrounding Code Context:\n${Object.entries(inputs.context)
+            .map(([file, context]) => `\n## ${file}\n\`\`\`\n${context}\n\`\`\``)
+            .join('\n')}`
+        : '';
+    const prDescriptionBlock = prDescription ? `\n\nPR Description:\n${prDescription}\n` : '';
+    const reviewDomainsBlock = reviewDomains && reviewDomains.length > 0
+        ? `\n\nReview Focus Domains:\n${reviewDomains.map((domain) => `- ${domain}`).join('\n')}\n`
+        : '';
+    return `You are performing a CRITIC PASS to validate and challenge findings from the previous iteration.
+
+Your role is to:
+1. Challenge each finding - require concrete evidence from the code or ContextRail standards
+2. Remove false positives - findings that lack evidence or don't violate actual standards
+3. Enforce ContextRail standards - each finding MUST be grounded in retrieved contexts
+4. Validate severity - ensure severity matches the actual risk level using the severity validation rules below
+5. Only keep findings that are:
+   - Supported by evidence in the code/diffs
+   - Linked to specific ContextRail standards (contextIdsUsed or contextIdsViolated)
+   - Accurately categorized by severity
+
+${SEVERITY_VALIDATION_RULES}
+${CONTEXTRAIL_TOOLING_BLOCK}
+
+Context:
+${understanding}
+${prDescriptionBlock}${reviewDomainsBlock}
+Files:
+${inputs.files.map((f) => `- ${f}`).join('\n')}
+${diffBlock}${contextBlock}
+
+Previous findings (iteration 1) - CRITICALLY REVIEW THESE:
+${JSON.stringify(findings.findings, null, 2)}
+
+For each finding, ask yourself:
+- Is there concrete evidence in the code/diffs that supports this finding?
+- Does this finding reference specific ContextRail standards (contextIdsUsed or contextIdsViolated)?
+- Is the severity appropriate for the actual risk? (Apply severity validation rules above)
+- Could this be a false positive that should be removed?
+- Should the severity be downgraded based on the validation rules?
+
+Output requirements:
+- Remove any findings that lack evidence
+- Remove findings that claim ContextRail impact but do not include retrieved context attribution
+- Keep only findings that are well-supported and properly attributed
+- Validate severity using the rules above - downgrade if evidence doesn't support the assigned level
+- Set validated: true only if all remaining findings meet these criteria
+- Always include notes field: use a string when you have notes, or null when none
+- If you remove findings or downgrade severity, explain why in notes
+- In notes, summarize which ContextRail contexts were retrieved (or state that none were relevant after tool lookup)
+
+${OUTPUT_CONTRACT_BLOCK}
+${FINAL_CHECKLIST_BLOCK}`;
+};
+/**
+ * Build a standard reviewer prompt for initial review (iteration 1).
+ */
+const buildStandardReviewPrompt = (inputs, understanding, prDescription, reviewDomains) => {
+    const diffBlock = isDiffInputs(inputs)
+        ? `\nDiffs:\n${Object.entries(inputs.diffs)
+            .map(([file, diff]) => `\n## ${file}\n\`\`\`diff\n${diff}\n\`\`\``)
+            .join('\n')}`
+        : '';
+    const contextBlock = inputs.context && Object.keys(inputs.context).length > 0
+        ? `\n\nSurrounding Code Context:\n${Object.entries(inputs.context)
+            .map(([file, context]) => `\n## ${file}\n\`\`\`\n${context}\n\`\`\``)
+            .join('\n')}`
+        : '';
+    const prDescriptionBlock = prDescription ? `\n\nPR Description:\n${prDescription}\n` : '';
+    const reviewDomainsBlock = reviewDomains && reviewDomains.length > 0
+        ? `\n\nReview Focus Domains:\n${reviewDomains.map((domain) => `- ${domain}`).join('\n')}\n`
+        : '';
+    return `Review these changes using the reviewer prompt guidance.
+
+Context:
+${understanding}
+${prDescriptionBlock}${reviewDomainsBlock}
+Files:
+${inputs.files.map((f) => `- ${f}`).join('\n')}
+${diffBlock}${contextBlock}
+
+Please review these changes and provide findings.
+
+${CONTEXTRAIL_TOOLING_BLOCK}
+${OUTPUT_CONTRACT_BLOCK}
+${FINAL_CHECKLIST_BLOCK}`;
+};
+export const buildReviewerUserMessage = (inputs, understanding, iteration, findings, prDescription, reviewDomains) => {
+    // Use critic pass for iteration 2+
+    if (iteration > 1 && findings) {
+        return buildCriticPrompt(inputs, understanding, findings, prDescription, reviewDomains);
+    }
+    // Use standard review for iteration 1
+    return buildStandardReviewPrompt(inputs, understanding, prDescription, reviewDomains);
+};

package/dist/reviewers/tool-call-tracker.d.ts

@@ -0,0 +1,18 @@
+import type { ReviewerIterationResult, ToolCallEntry } from './types.js';
+import type { TokenUsage } from '../output/schema.js';
+export declare const collectToolCalls: (toolCalls: {
+    toolName: string;
+    input?: unknown;
+}[] | undefined) => {
+    toolCalls: ToolCallEntry[];
+    contextIds: string[];
+};
+export declare const mergeIterationTracking: (current: {
+    toolCalls: ToolCallEntry[];
+    contextIds: string[];
+}, iteration: ReviewerIterationResult) => void;
+/**
+ * Merge token usage from multiple sources.
+ * Sums promptTokens, completionTokens, and totalTokens.
+ */
+export declare const mergeTokenUsage: (usages: (TokenUsage | undefined)[]) => TokenUsage | undefined;