@contextrail/code-review-agent 0.1.2-alpha.1 → 0.1.2-alpha.3

package/dist/pipeline.js

@@ -1,6 +1,7 @@
 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';
@@ -29,6 +30,12 @@ export const runReview = async (input) => {
         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();
@@ -91,6 +98,7 @@ export const runReview = async (input) => {
         }
         const orchestratorOutput = await runOrchestrator(inputs, outputDir, {
             mcpClient,
+            llmService,
             config: {
                 openRouterApiKey: config.openRouterApiKey,
                 orchestratorModel: config.orchestratorModel ?? DEFAULT_ORCHESTRATOR_MODEL,
@@ -111,6 +119,7 @@ export const runReview = async (input) => {
             try {
                 const rawFindings = await runReviewerLoop(reviewer, inputs, orchestratorOutput.understanding, outputDir, {
                     mcpClient,
+                    llmService,
                     config: {
                         openRouterApiKey: config.openRouterApiKey,
                         reviewerModel: config.reviewerModel ?? DEFAULT_REVIEWER_MODEL,
@@ -196,7 +205,7 @@ export const runReview = async (input) => {
         // 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, {
-            openRouterApiKey: config.openRouterApiKey,
+            llmService,
             model: config.orchestratorModel ?? DEFAULT_ORCHESTRATOR_MODEL,
             maxSteps: config.aggregationMaxSteps,
             logger: log,
@@ -213,7 +222,7 @@ export const runReview = async (input) => {
         // 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, {
-            openRouterApiKey: config.openRouterApiKey,
+            llmService,
             model: config.orchestratorModel ?? DEFAULT_ORCHESTRATOR_MODEL,
             maxSteps: config.aggregationMaxSteps,
             logger: log,

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 };

package/dist/prompts/reviewer.d.ts

@@ -0,0 +1,12 @@
+import { type ReviewInputs } from '../review-inputs/index.js';
+import type { ReviewerFindings } from '../output/schema.js';
+/**
+ * Build a critic prompt that challenges findings from a previous iteration.
+ * The critic pass validates findings, removes false positives, and enforces evidence/standards.
+ */
+export declare const buildCriticPrompt: (inputs: ReviewInputs, understanding: string, findings: ReviewerFindings, prDescription?: string, reviewDomains?: string[]) => string;
+/**
+ * Build a standard reviewer prompt for initial review (iteration 1).
+ */
+export declare const buildStandardReviewPrompt: (inputs: ReviewInputs, understanding: string, prDescription?: string, reviewDomains?: string[]) => string;
+export declare const buildReviewerUserMessage: (inputs: ReviewInputs, understanding: string, iteration: number, findings: ReviewerFindings | null, prDescription?: string, reviewDomains?: string[]) => string;

package/dist/prompts/reviewer.js

@@ -0,0 +1,107 @@
+import { isDiffInputs } from '../review-inputs/index.js';
+import { SEVERITY_VALIDATION_RULES, CONTEXTRAIL_TOOLING_BLOCK, OUTPUT_CONTRACT_BLOCK, FINAL_CHECKLIST_BLOCK, } from './blocks.js';
+/**
+ * Build a critic prompt that challenges findings from a previous iteration.
+ * The critic pass validates findings, removes false positives, and enforces evidence/standards.
+ */
+export 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).
+ */
+export 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/{output/prompts.d.ts → prompts/synthesis.d.ts}

@@ -1,4 +1,4 @@
-import type { ReviewerResult } from './schema.js';
+import type { ReviewerResult } from '../output/schema.js';
 /**
  * Generate a human-readable pre-summary from reviewer results.
  * Includes severity counts and top findings per reviewer.
@@ -15,18 +15,3 @@ export declare const generatePreSummary: (reviewerResults: ReviewerResult[]) =>
  * @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 → prompts/synthesis.js}

@@ -121,33 +121,3 @@ Output requirements:
 - \`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}
-`;
-};

package/dist/reviewers/executor.d.ts

@@ -3,7 +3,9 @@ import { type ChunkingConfig } from '../review-inputs/chunking.js';
 import { type FilePatterns } from '../review-inputs/file-patterns.js';
 import type { McpClient } from '../mcp/client.js';
 import type { ReviewerFindings } from '../output/schema.js';
+import type { SharedAgentOpConfig } from '../config/index.js';
 import type { Logger } from '../logging/logger.js';
+import type { LlmService } from '../llm/service.js';
 /**
  * Extract filePatterns from prompt metadata.
  *
@@ -11,18 +13,15 @@ import type { Logger } from '../logging/logger.js';
  * @returns FilePatterns if found, undefined otherwise
  */
 export declare function extractFilePatterns(metadata: unknown): FilePatterns | undefined;
-export type AgenticExecutorConfig = {
-    openRouterApiKey: string;
+export type AgenticExecutorConfig = SharedAgentOpConfig & {
     reviewerModel: string;
     criticModel?: string;
-    maxSteps?: number;
     maxIterations?: number;
     chunking?: ChunkingConfig;
-    prDescription?: string;
-    reviewDomains?: string[];
 };
 export type AgenticExecutorDeps = {
     mcpClient: McpClient;
+    llmService: LlmService;
     config: AgenticExecutorConfig;
     logger?: Logger;
 };

package/dist/reviewers/executor.js

@@ -9,7 +9,6 @@ import { runReviewerIteration } from './iteration.js';
 import { logCompletion, logContinuation, logIteration, writeFindings, writeTokenMetrics } from './persistence.js';
 import { mergeIterationTracking, mergeTokenUsage } from './tool-call-tracker.js';
 import { mergeChunkFindings } from './findings-merge.js';
-import { createLlmService } from '../llm/factory.js';
 const formatIssuePath = (pathSegments) => {
     if (!Array.isArray(pathSegments) || pathSegments.length === 0) {
         return '(root)';
@@ -115,7 +114,7 @@ export function extractFilePatterns(metadata) {
  * @returns Reviewer findings
  */
 export const runReviewerLoop = async (reviewer, inputs, understanding, outputDir, deps) => {
-    const { mcpClient, config, logger } = deps;
+    const { mcpClient, llmService, config, logger } = deps;
     const maxIterations = config.maxIterations ?? DEFAULT_MAX_ITERATIONS;
     const reviewersDir = path.join(outputDir, 'reviewers');
     const reviewerDir = path.join(reviewersDir, reviewer);
@@ -193,12 +192,6 @@ export const runReviewerLoop = async (reviewer, inputs, understanding, outputDir
     else {
         logger?.debug(`[${reviewer}] No file pattern scope found in prompt metadata; reviewing all ${inputs.files.length} files`);
     }
-    // Create LLM service with MCP tools
-    const { service: llmService } = createLlmService({
-        openRouterApiKey: config.openRouterApiKey,
-        mcpClient,
-        logger,
-    });
     const maxSteps = config.maxSteps ?? DEFAULT_MAX_STEPS;
     let findings = null;
     let iteration = 0;

package/dist/reviewers/prompt.d.ts

@@ -1,34 +1,9 @@
-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 { SEVERITY_CALIBRATION_BLOCK, SEVERITY_VALIDATION_RULES, CONTEXTRAIL_TOOLING_BLOCK, OUTPUT_CONTRACT_BLOCK, FINAL_CHECKLIST_BLOCK, } from '../prompts/blocks.js';
+export { buildCriticPrompt, buildStandardReviewPrompt, buildReviewerUserMessage } from '../prompts/reviewer.js';
 export declare const buildPromptMessages: (promptResult: {
     messages: {
         role: string;
@@ -39,4 +14,3 @@ export declare const buildPromptMessages: (promptResult: {
     }[];
     metadata?: unknown;
 }) => PromptMessage[];
-export declare const buildReviewerUserMessage: (inputs: ReviewInputs, understanding: string, iteration: number, findings: ReviewerFindings | null, prDescription?: string, reviewDomains?: string[]) => string;