codecritique 2.0.5 → 2.0.7

package/README.md

@@ -263,8 +263,13 @@ npx codecritique analyze --file src/components/Button.tsx
 # Analyze files matching patterns
 npx codecritique analyze --files "src/**/*.ts" "lib/*.js"
 
-# Analyze changes in feature-branch vs main branch (auto-detects base branch)
+# Review changes in a target branch against its auto-detected parent branch
 npx codecritique analyze --diff-with feature-branch
+
+# Review against an explicit base branch (overrides auto-detection).
+# Useful for stacked PRs where you know the real base, or in CI where the PR
+# base ref is authoritative.
+npx codecritique analyze --diff-with feature-B --base feature-A
 ```
 
 #### Using with Custom Guidelines
@@ -383,9 +388,6 @@ jobs:
       - name: ⬇️ Checkout repo
         uses: actions/checkout@v4
 
-      - name: Setup master branch for diff analysis
-        run: git fetch --no-tags --prune origin main:main
-
       - name: Code Review
         uses: cosmocoder/CodeCritique/.github/actions/pr-review@main
         with:
@@ -393,11 +395,16 @@ jobs:
           anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
 ```
 
+> No manual `git fetch` or `fetch-depth: 0` is needed. The action fetches the PR base
+> branch (the parent — which for a stacked PR is another feature branch) and deepens
+> the shallow checkout just enough to compute the diff, so parent auto-detection works
+> without the cost of a full-history clone.
+
 #### Required Setup
 
 1. **Anthropic API Key**: Store your Anthropic API key as a repository secret named `ANTHROPIC_API_KEY`
 2. **Permissions**: The workflow must have `contents: write`, `actions: read`, and `pull-requests: write` permissions
-3. **Git Setup**: Ensure the base branch is available for diff analysis (see example above)
+3. **Git Setup**: None required — the action fetches the PR base/parent branch and deepens the checkout only as much as the diff needs (no `fetch-depth: 0`)
 
 #### Input Parameters
 
@@ -450,7 +457,7 @@ codecritique analyze --file src/components/Button.tsx
 # Analyze files matching patterns
 codecritique analyze --files "src/**/*.ts" "lib/*.js"
 
-# Analyze branch diff
+# Review target branch changes against its auto-detected parent branch
 codecritique analyze --diff-with feature-branch
 
 # Generate embeddings

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecritique",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "description": "AI-powered code review tool for any programming language",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -29,7 +29,7 @@ import { cleanupClassifier, clearPRComments, getPRCommentsStats, hasPRComments }
 import { ProjectAnalyzer } from './project-analyzer.js';
 import { reviewFile, reviewFiles, reviewPullRequest } from './rag-review.js';
 import { execGitSafe } from './utils/command.js';
-import { ensureBranchExists, findBaseBranch } from './utils/git.js';
+import { ensureBranchExists, findParentBranch } from './utils/git.js';
 import { diagnosticLog, isDebugEnabled, isVerboseEnabled, verboseLog } from './utils/logging.js';
 import { collectPRLevelFindings, getFileLevelIssueCount, hasPRLevelFindings } from './utils/review-results.js';
 import { configureCleanStdoutForDataOutput, isBrokenStdoutPipeError, writeStdout } from './utils/stdout.js';
@@ -46,7 +46,11 @@ program.name('codecritique').description('CLI tool for AI-powered code review us
 program
   .command('analyze')
   .description('Analyze code using dynamic context (RAG approach)')
-  .option('-b, --diff-with <branch>', 'Analyze files changed compared to a branch (triggers PR review mode)')
+  .option(
+    '-b, --diff-with <branch>',
+    'Review the specified target branch against its auto-detected parent branch (triggers PR review mode)'
+  )
+  .option('--base <branch>', 'Base branch to diff the target against, overriding auto-detection (e.g. the authoritative PR base ref in CI)')
   .option('-f, --files <files...>', 'Specific files or glob patterns to review')
   .option('--file <file>', 'Analyze a single file')
   .option('-d, --directory <dir>', 'Working directory for git operations (use with --diff-with)')
@@ -163,12 +167,12 @@ Examples:
   $ codecritique analyze --directory src/components
   $ codecritique analyze --file src/utils/validation.ts
   $ codecritique analyze --files "src/**/*.tsx" "lib/*.js"
-  $ codecritique analyze -b main
+  $ codecritique analyze -b feature-branch
   $ codecritique analyze --doc "Our Eng Guidelines:./ENGINEERING_GUIDELINES.md" --file src/utils/validation.ts
   $ codecritique analyze --diff-with feature-branch -d /path/to/repo
   $ codecritique analyze --output json > review-results.json
   $ codecritique analyze --track-feedback --feedback-path ./feedback-artifacts --file src/utils/validation.ts
-  $ codecritique analyze --track-feedback --feedback-threshold 0.8 -b main
+  $ codecritique analyze --track-feedback --feedback-threshold 0.8 -b feature-branch
   $ codecritique embeddings:generate --directory src
   $ codecritique embeddings:generate --exclude "**/*.test.js" "**/*.spec.js"
   $ codecritique embeddings:generate --exclude-file .embedignore
@@ -357,23 +361,26 @@ async function runCodeReview(options) {
     diagnosticLog(chalk.bold.blue('AI Code Review (RAG Approach) - Starting analysis...'));
 
     // Determine the review mode based on options
-    // Only support: single file, specific files, or diff with branch
+    // Only support: single file, specific files, or target-branch diff review
     if (options.diffWith) {
+      const targetBranch = options.diffWith;
       // Use directory option as working directory for git commands if specified
       const gitWorkingDir = options.directory ? path.resolve(options.directory) : process.cwd();
-      const changedFiles = getChangedFiles(options.diffWith, gitWorkingDir);
+      const { changedFiles, baseBranch } = getChangedFiles(targetBranch, gitWorkingDir, options.base);
       if (changedFiles.length === 0) {
-        const message = `No changed files found compared to branch '${options.diffWith}'. Exiting.`;
+        const message = `No changed files found in target branch '${targetBranch}' compared to its detected parent branch. Exiting.`;
         diagnosticLog(chalk.yellow(message));
         await emitEmptyReviewOutputIfNeeded(options, { success: true, results: [], message });
         return;
       }
-      operationDescription = `${changedFiles.length} files changed vs ${options.diffWith}`;
-      // Add the actual branch name to reviewOptions
+      operationDescription = `${changedFiles.length} files changed in target branch ${targetBranch}`;
+      // Add the actual branch name to reviewOptions. Pass the already-detected
+      // parent branch so the review pipeline doesn't re-run parent detection.
       const enhancedReviewOptions = {
         ...reviewOptions,
-        actualBranch: options.diffWith,
-        diffWith: options.diffWith,
+        actualBranch: targetBranch,
+        diffWith: targetBranch,
+        baseBranch,
       };
       reviewTask = reviewPullRequest(changedFiles, enhancedReviewOptions);
     }
@@ -400,7 +407,7 @@ async function runCodeReview(options) {
       console.error(chalk.red('Error: You must specify one of the following:'));
       console.error(chalk.yellow('  --file <file>                    Analyze a single file'));
       console.error(chalk.yellow('  --files <files...>               Analyze specific files or glob patterns'));
-      console.error(chalk.yellow('  -b, --diff-with <branch>         Analyze files changed in a branch'));
+      console.error(chalk.yellow('  -b, --diff-with <branch>         Review a target branch against its auto-detected parent branch'));
       console.error(chalk.gray('\nOptional:'));
       console.error(chalk.gray('  -d, --directory <dir>            Working directory (for git operations with --diff-with)'));
       console.error(chalk.gray('\nExamples:'));
@@ -973,24 +980,36 @@ async function expandFilePatterns(patterns, baseDir = process.cwd()) {
 }
 
 /**
- * Get list of files changed in a branch compared to the base branch (main/master).
- * This shows what changes the specified branch has compared to the base.
+ * Get list of files changed in the target branch compared to its base branch.
+ * The supplied branch is the branch being reviewed, not the base branch.
+ *
+ * When `explicitBase` is given (e.g. the authoritative PR base ref in CI) it is
+ * used directly. Otherwise the parent is auto-detected (see findParentBranch),
+ * so stacked PRs are diffed against the branch they were forked from rather than
+ * always against main/master/develop.
  *
- * @param {string} branch - Branch to analyze (the feature/target branch)
+ * @param {string} targetBranch - Branch to analyze (the feature/target branch)
  * @param {string} workingDir - Directory to run git commands in (optional, defaults to cwd)
- * @returns {Array<string>} Array of changed file paths relative to git root
+ * @param {string} [explicitBase] - Base branch to diff against, overriding auto-detection
+ * @returns {{ changedFiles: Array<string>, baseBranch: string|null }} Changed file paths
+ *   (absolute) and the base branch they were diffed against (null on error).
  */
-function getChangedFiles(branch, workingDir = process.cwd()) {
+function getChangedFiles(targetBranch, workingDir = process.cwd(), explicitBase = undefined) {
   try {
     // Get git root directory
     const gitRoot = execSync('git rev-parse --show-toplevel', { cwd: workingDir }).toString().trim();
     diagnosticLog(chalk.gray(`Git repository: ${gitRoot}`));
 
-    // Ensure the branch exists locally (fetch if needed)
-    ensureBranchExists(branch, workingDir);
+    // Ensure the target branch exists locally (fetch if needed)
+    ensureBranchExists(targetBranch, workingDir);
 
-    // Find the base branch (main/master)
-    const baseBranch = findBaseBranch(workingDir);
+    // Use the explicitly provided base (authoritative, e.g. the PR base ref in CI)
+    // when given; otherwise detect the parent branch the target was forked from
+    // (main/master/develop, or another feature branch in stacked-PR workflows).
+    const baseBranch = explicitBase || findParentBranch(targetBranch, workingDir);
+    if (explicitBase) {
+      diagnosticLog(chalk.gray(`Using explicit base branch '${baseBranch}' (auto-detection skipped)`));
+    }
 
     // Ensure the base branch exists locally as well (crucial for diff operations)
     try {
@@ -1001,12 +1020,13 @@ function getChangedFiles(branch, workingDir = process.cwd()) {
       // Continue with the original baseBranch name, it might work with remote refs
     }
 
-    diagnosticLog(chalk.gray(`Comparing ${branch} against ${baseBranch}...`));
+    diagnosticLog(chalk.gray(`Reviewing target branch '${targetBranch}' against base branch '${baseBranch}'...`));
 
-    // Use three-dot notation to get changes in branch compared to base
-    // This shows commits that are in 'branch' but not in 'baseBranch'
+    // Use three-dot notation to get changes in the target branch compared to the base.
     // By adding --diff-filter=d, we exclude deleted files from the list.
-    const gitOutput = execGitSafe('git diff', ['--name-only', '--diff-filter=d', `${baseBranch}...${branch}`], { cwd: gitRoot }).toString();
+    const gitOutput = execGitSafe('git diff', ['--name-only', '--diff-filter=d', `${baseBranch}...${targetBranch}`], {
+      cwd: gitRoot,
+    }).toString();
 
     // Split, filter empty lines, resolve paths, and check existence
     const changedFiles = gitOutput
@@ -1015,14 +1035,14 @@ function getChangedFiles(branch, workingDir = process.cwd()) {
       .map((file) => path.resolve(gitRoot, file)); // Get absolute path
 
     if (changedFiles.length > 0) {
-      diagnosticLog(chalk.gray(`Found ${changedFiles.length} changed files in ${branch} vs ${baseBranch}`));
+      diagnosticLog(chalk.gray(`Found ${changedFiles.length} changed files in target branch '${targetBranch}' vs base '${baseBranch}'`));
     }
 
-    return changedFiles;
+    return { changedFiles, baseBranch };
   }
   catch (err) {
     console.error(chalk.red('Error getting git diff:'), err.message);
-    return [];
+    return { changedFiles: [], baseBranch: null };
   }
 }
 

package/src/llm.js

@@ -44,6 +44,44 @@ const DEFAULT_MODEL = 'claude-sonnet-4-5';
 // Maximum tokens for response
 const MAX_TOKENS = 4096;
 
+const MAX_CACHE_CONTROL_BLOCKS = 4;
+
+function normalizeSystemBlock(block, cacheControl) {
+  const normalizedBlock = typeof block === 'string' ? { type: 'text', text: block } : { type: 'text', ...block };
+
+  if (cacheControl) {
+    return {
+      ...normalizedBlock,
+      cache_control: normalizedBlock.cache_control || cacheControl,
+    };
+  }
+
+  return normalizedBlock;
+}
+
+function buildSystemContent(system, cachedSystemBlocks, cacheControl) {
+  if (!system && cachedSystemBlocks.length === 0) {
+    return 'You are an expert code reviewer with deep knowledge of software engineering principles, design patterns, and best practices.';
+  }
+
+  const systemBlocks = [];
+  const appendBlock = (block) => {
+    const cacheable = systemBlocks.filter((existingBlock) => existingBlock.cache_control).length < MAX_CACHE_CONTROL_BLOCKS;
+    systemBlocks.push(normalizeSystemBlock(block, cacheable ? cacheControl : null));
+  };
+
+  if (Array.isArray(system)) {
+    system.forEach(appendBlock);
+  }
+  else if (system) {
+    appendBlock(system);
+  }
+
+  cachedSystemBlocks.filter(Boolean).forEach(appendBlock);
+
+  return systemBlocks;
+}
+
 /**
  * Send a prompt to Claude and get a structured JSON response using tool calling.
  * Uses prompt caching for system prompts to reduce token costs.
@@ -51,12 +89,21 @@ const MAX_TOKENS = 4096;
  * @param {string} prompt - The prompt to send to Claude
  * @param {Object} options - Options for the request
  * @param {string} options.system - System prompt (will be cached for cost optimization)
+ * @param {Array<string|Object>} options.cachedSystemBlocks - Additional stable system blocks to cache when possible
  * @param {Object} options.jsonSchema - JSON schema for structured output
  * @param {string} options.cacheTtl - Cache TTL: '5m' (default, no extra cost) or '1h' (extended, extra cost for writes)
  * @returns {Promise<Object>} The response from Claude with structured data
  */
 async function sendPromptToClaude(prompt, options = {}) {
-  const { model = DEFAULT_MODEL, maxTokens = MAX_TOKENS, temperature = 0.7, system = '', jsonSchema = null, cacheTtl = '5m' } = options;
+  const {
+    model = DEFAULT_MODEL,
+    maxTokens = MAX_TOKENS,
+    temperature = 0.7,
+    system = '',
+    cachedSystemBlocks = [],
+    jsonSchema = null,
+    cacheTtl = '5m',
+  } = options;
 
   try {
     verboseLog(options, chalk.cyan('Sending prompt to Claude...'));
@@ -68,15 +115,7 @@ async function sendPromptToClaude(prompt, options = {}) {
     // TTL options: '5m' (default, no extra cost) or '1h' (extended, extra cost for cache writes)
     const cacheControl = cacheTtl === '1h' ? { type: 'ephemeral', ttl: '1h' } : { type: 'ephemeral' };
 
-    const systemContent = system
-      ? [
-          {
-            type: 'text',
-            text: system,
-            cache_control: cacheControl,
-          },
-        ]
-      : 'You are an expert code reviewer with deep knowledge of software engineering principles, design patterns, and best practices.';
+    const systemContent = buildSystemContent(system, cachedSystemBlocks, cacheControl);
 
     // Build base request parameters
     const requestParams = {

package/src/llm.test.js

@@ -241,6 +241,62 @@ describe('sendPromptToClaude', () => {
         })
       );
     });
+
+    it('should append additional cached system blocks', async () => {
+      mockMessagesCreate.mockResolvedValue({
+        content: [{ type: 'text', text: 'Response' }],
+        model: 'claude-sonnet-4-5',
+        usage: {},
+      });
+
+      await sendPromptToClaude('Test', {
+        system: 'Base review rules',
+        cachedSystemBlocks: ['Custom project instructions', 'Project architecture context'],
+      });
+
+      expect(mockMessagesCreate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          system: [
+            {
+              type: 'text',
+              text: 'Base review rules',
+              cache_control: { type: 'ephemeral' },
+            },
+            {
+              type: 'text',
+              text: 'Custom project instructions',
+              cache_control: { type: 'ephemeral' },
+            },
+            {
+              type: 'text',
+              text: 'Project architecture context',
+              cache_control: { type: 'ephemeral' },
+            },
+          ],
+        })
+      );
+    });
+
+    it('should include extra system blocks without exceeding cache breakpoint limits', async () => {
+      mockMessagesCreate.mockResolvedValue({
+        content: [{ type: 'text', text: 'Response' }],
+        model: 'claude-sonnet-4-5',
+        usage: {},
+      });
+
+      await sendPromptToClaude('Test', {
+        system: 'Base review rules',
+        cachedSystemBlocks: ['Block 1', 'Block 2', 'Block 3', 'Block 4'],
+      });
+
+      const request = mockMessagesCreate.mock.calls.at(-1)[0];
+      expect(request.system).toHaveLength(5);
+      expect(request.system.filter((block) => block.cache_control)).toHaveLength(4);
+      expect(request.system.at(-1)).toEqual({
+        type: 'text',
+        text: 'Block 4',
+      });
+    });
   });
 
   describe('message format', () => {

package/src/project-analyzer.js

@@ -16,6 +16,8 @@ import { isDocumentationFile, isTestFile } from './utils/file-validation.js';
 import { verboseLog } from './utils/logging.js';
 import { escapeSqlString } from './utils/string-utils.js';
 
+const TERM_SEARCH_CONTENT_CANDIDATE_LIMIT = 500;
+
 // Consolidated file classification configuration
 const FILE_PATTERNS = {
   config: {
@@ -383,14 +385,18 @@ export class ProjectAnalyzer {
       // Unified query function
       const queryFiles = async (config) => {
         try {
-          let query = table.query().select(['path', 'name', 'content', 'type', 'language']);
-
           if (config.whereClause) {
-            query = query.where(`${projectPathFilter} AND (${config.whereClause})`);
+            return await table
+              .query()
+              .select(['path', 'name', 'content', 'type', 'language'])
+              .where(`${projectPathFilter} AND (${config.whereClause})`)
+              .limit(config.limit || 30)
+              .toArray();
           }
           else if (config.terms) {
-            // For term-based searches, query ALL files and sort by depth to prioritize shallow config files
-            const allFiles = await table.query().select(['path', 'name', 'content', 'type', 'language']).where(projectPathFilter).toArray(); // NO LIMIT - get all files
+            // For term-based searches, query metadata first and only fetch content for
+            // the shallow candidate set used for matching.
+            const allFiles = await table.query().select(['path', 'name', 'type', 'language']).where(projectPathFilter).toArray();
 
             // Sort by path depth (shorter paths first) to prioritize config files
             allFiles.sort((a, b) => {
@@ -400,24 +406,54 @@ export class ProjectAnalyzer {
             });
 
             // Take only the first 500 after sorting to ensure we have shallow files
-            const sortedFiles = allFiles.slice(0, 500);
+            const sortedFiles = allFiles.slice(0, TERM_SEARCH_CONTENT_CANDIDATE_LIMIT);
+            if (sortedFiles.length === 0) {
+              return [];
+            }
 
-            return sortedFiles.filter((result) => {
-              const content = (result.content || '').toLowerCase();
-              const pathName = (result.path || '').toLowerCase();
-              const name = (result.name || '').toLowerCase();
-              const matches = config.terms.some(
-                (term) => content.includes(term.toLowerCase()) || pathName.includes(term.toLowerCase()) || name.includes(term.toLowerCase())
-              );
+            const candidatePaths = sortedFiles.map((file) => file.path).filter(Boolean);
+            const contentByPath = new Map();
+            if (candidatePaths.length > 0) {
+              const pathList = candidatePaths.map((candidatePath) => `'${escapeSqlString(candidatePath)}'`).join(', ');
+              const contentResults = await table
+                .query()
+                .select(['path', 'content'])
+                .where(`${projectPathFilter} AND path IN (${pathList})`)
+                .limit(TERM_SEARCH_CONTENT_CANDIDATE_LIMIT)
+                .toArray();
+
+              for (const result of contentResults) {
+                contentByPath.set(result.path, result.content || '');
+              }
+            }
 
-              return matches;
-            });
+            return sortedFiles
+              .filter((result) => {
+                const content = (contentByPath.get(result.path) || '').toLowerCase();
+                const pathName = (result.path || '').toLowerCase();
+                const name = (result.name || '').toLowerCase();
+                const matches = config.terms.some(
+                  (term) =>
+                    content.includes(term.toLowerCase()) || pathName.includes(term.toLowerCase()) || name.includes(term.toLowerCase())
+                );
+
+                return matches;
+              })
+              .map((result) => {
+                return {
+                  ...result,
+                  content: contentByPath.get(result.path) || '',
+                };
+              });
           }
           else {
-            query = query.where(projectPathFilter);
+            return await table
+              .query()
+              .select(['path', 'name', 'content', 'type', 'language'])
+              .where(projectPathFilter)
+              .limit(config.limit || 30)
+              .toArray();
           }
-
-          return await query.limit(config.limit || 30).toArray();
         }
         catch (error) {
           verboseLog({}, chalk.yellow(`     ⚠️ Query failed for ${config.category}: ${error.message}`));

package/src/project-analyzer.test.js

@@ -410,6 +410,79 @@ describe('ProjectAnalyzer', () => {
       expect(queryChain.where).toHaveBeenCalledWith(expect.stringContaining("/mock/we''re/project"));
     });
 
+    it('should bound content reads for term-based key file searches', async () => {
+      const queryCalls = [];
+      mockTable.query.mockImplementation(() => {
+        const call = {
+          select: [],
+          where: [],
+          limit: [],
+        };
+        queryCalls.push(call);
+
+        const chain = {
+          select: vi.fn((columns) => {
+            call.select.push(columns);
+            return chain;
+          }),
+          where: vi.fn((clause) => {
+            call.where.push(clause);
+            return chain;
+          }),
+          limit: vi.fn((limit) => {
+            call.limit.push(limit);
+            return chain;
+          }),
+          toArray: vi.fn(async () => {
+            const selectedColumns = call.select[0] || [];
+            if (selectedColumns.includes('content')) {
+              return [
+                {
+                  path: 'package.json',
+                  name: 'package.json',
+                  content: '{"name": "test-project"}',
+                  type: 'json',
+                  language: 'json',
+                },
+              ];
+            }
+
+            return [
+              {
+                path: 'package.json',
+                name: 'package.json',
+                type: 'json',
+                language: 'json',
+              },
+            ];
+          }),
+        };
+
+        return chain;
+      });
+
+      const result = await analyzer.mineKeyFilesFromEmbeddings(mockProjectPath);
+
+      expect(result.some((file) => file.path === 'package.json')).toBe(true);
+      expect(
+        queryCalls.some((call) => {
+          const selectedColumns = call.select[0] || [];
+          return selectedColumns.includes('content') && call.where[0] === "project_path = '/mock/project'" && call.limit.length === 0;
+        })
+      ).toBe(false);
+      expect(
+        queryCalls.some((call) => {
+          const selectedColumns = call.select[0] || [];
+          return (
+            selectedColumns.includes('path') &&
+            selectedColumns.includes('name') &&
+            !selectedColumns.includes('content') &&
+            call.where[0] === "project_path = '/mock/project'"
+          );
+        })
+      ).toBe(true);
+    });
+
     it('should handle table optimization errors gracefully', async () => {
       mockTable.optimize.mockRejectedValue(new Error('legacy format'));
       mockTable.query().toArray.mockResolvedValue([]);

package/src/rag-analyzer.js

@@ -42,6 +42,20 @@ const embeddingsSystem = getDefaultEmbeddingsSystem();
 // Track if semantic similarity has been initialized
 let semanticSimilarityInitialized = false;
 
+async function fileExists(filePath) {
+  try {
+    await fs.promises.access(filePath);
+    return true;
+  }
+  catch {
+    return false;
+  }
+}
+
+async function readTextFile(filePath) {
+  return await fs.promises.readFile(filePath, 'utf8');
+}
+
 /**
  * Initialize semantic similarity for feedback filtering
  * Uses the shared embeddings system from feedback-loader.js
@@ -448,7 +462,7 @@ async function runAnalysis(filePath, options = {}) {
     }
 
     // Check if file exists
-    if (!fs.existsSync(filePath)) {
+    if (!(await fileExists(filePath))) {
       throw new Error(`File not found: ${filePath}`);
     }
 
@@ -458,11 +472,11 @@ async function runAnalysis(filePath, options = {}) {
     if (options.diffOnly && options.diffContent) {
       content = options.diffContent;
       // For PR reviews, always read the full file content for context awareness
-      fullFileContent = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null;
+      fullFileContent = await readTextFile(filePath);
       verboseLog(options, chalk.blue(`Analyzing diff only for ${path.basename(filePath)}`));
     }
     else {
-      content = fs.readFileSync(filePath, 'utf8');
+      content = await readTextFile(filePath);
       fullFileContent = content;
       verboseLog(options, chalk.blue(`Analyzing full file ${path.basename(filePath)}`));
     }
@@ -835,6 +849,30 @@ MARKDOWN FORMATTING IN DESCRIPTIONS AND SUGGESTIONS:
 Your response must start with { and end with } with no additional text.`;
 }
 
+function buildCachedProjectContextBlocks({ roleDefinition, customDocsSection, projectArchitectureSection }) {
+  const blocks = [];
+
+  if (roleDefinition?.trim()) {
+    blocks.push(`REVIEW ROLE AND PROJECT INSTRUCTIONS
+
+${roleDefinition}`);
+  }
+
+  if (customDocsSection?.trim() && !customDocsSection.includes('No custom instructions provided.')) {
+    blocks.push(`CUSTOM PROJECT INSTRUCTIONS
+
+${customDocsSection}`);
+  }
+
+  if (projectArchitectureSection?.trim()) {
+    blocks.push(`PROJECT ARCHITECTURE CONTEXT
+
+${projectArchitectureSection}`);
+  }
+
+  return blocks;
+}
+
 // LLM call function - sends prompt with cached system content for cost optimization
 async function sendPromptToLLM(promptConfig, llmOptions) {
   try {
@@ -946,12 +984,14 @@ async function sendPromptToLLM(promptConfig, llmOptions) {
     verboseLog(llmOptions, chalk.gray(`  Prompt config has systemPrompt: ${!!promptConfig.systemPrompt}`));
     verboseLog(llmOptions, chalk.gray(`  Prompt config has userPrompt: ${!!promptConfig.userPrompt}`));
     verboseLog(llmOptions, chalk.gray(`  System prompt length: ${promptConfig.systemPrompt?.length || 0} chars`));
+    verboseLog(llmOptions, chalk.gray(`  Cached system blocks: ${promptConfig.cachedSystemBlocks?.length || 0}`));
     verboseLog(llmOptions, chalk.gray(`  User prompt length: ${promptConfig.userPrompt?.length || 0} chars`));
 
     // Send prompt with system (cached) and user (dynamic) content
     const response = await llm.sendPromptToClaude(promptConfig.userPrompt, {
       ...llmOptions,
       system: promptConfig.systemPrompt,
+      cachedSystemBlocks: promptConfig.cachedSystemBlocks || [],
       jsonSchema: codeReviewSchema,
     });
 
@@ -1096,21 +1136,21 @@ ${addLineNumbers(file.content)}
 
   // Build the cached system prompt (contains all static rules)
   const systemPrompt = buildCachedSystemPrompt('code');
+  const cachedSystemBlocks = buildCachedProjectContextBlocks({
+    roleDefinition,
+    customDocsSection,
+    projectArchitectureSection,
+  });
 
   // Build the dynamic user prompt (contains all variable content)
   const userPrompt = finalizePrompt(`
 ## REVIEW TYPE: CODE FILE ANALYSIS
 
-${roleDefinition}
-
 ${reviewInstructions}
 
-${customDocsSection}
-
 ${fileSection}
 
-CONTEXT FROM PROJECT:
-${projectArchitectureSection}
+Use the cached project context, project architecture, and custom instructions when evaluating this file.
 
 CONTEXT A: EXPLICIT GUIDELINES FROM DOCUMENTATION
 ${formattedGuidelines}
@@ -1136,7 +1176,7 @@ Analyze the FILE TO REVIEW above using the 4-stage methodology:
 - If you analyzed something and found it's fine, simply don't include it in the output
 `);
 
-  return { systemPrompt, userPrompt };
+  return { systemPrompt, userPrompt, cachedSystemBlocks };
 }
 
 /**
@@ -1215,22 +1255,22 @@ ${addLineNumbers(file.content)}
 
   // Build the cached system prompt (contains all static rules)
   const systemPrompt = buildCachedSystemPrompt('test');
+  const cachedSystemBlocks = buildCachedProjectContextBlocks({
+    roleDefinition,
+    customDocsSection,
+    projectArchitectureSection,
+  });
 
   // Build the dynamic user prompt (contains all variable content)
   const userPrompt = finalizePrompt(`
 ## REVIEW TYPE: TEST FILE ANALYSIS
 
-${roleDefinition}
-
 ${reviewInstructions}
 
 ${fileSection}
 
 ## ANALYSIS CONTEXT
-${customDocsSection}
-
-CONTEXT FROM PROJECT:
-${projectArchitectureSection}
+Use the cached project context, project architecture, and custom instructions when evaluating this test file.
 
 CONTEXT A: TESTING GUIDELINES AND BEST PRACTICES
 ${formattedGuidelines}
@@ -1253,7 +1293,7 @@ Analyze the TEST FILE above using the 5-stage methodology:
 - If you analyzed something and found it's fine, simply don't include it in the output
 `);
 
-  return { systemPrompt, userPrompt };
+  return { systemPrompt, userPrompt, cachedSystemBlocks };
 }
 
 /**
@@ -1371,20 +1411,23 @@ For each file in this PR, you have access to:
 
   // Build the cached system prompt (contains all static rules)
   const systemPrompt = buildCachedSystemPrompt('pr');
+  const cachedSystemBlocks = buildCachedProjectContextBlocks({
+    roleDefinition,
+    customDocsSection,
+    projectArchitectureSection,
+  });
 
   // Build the dynamic user prompt (contains all variable content)
   const userPrompt = finalizePrompt(`
 ## REVIEW TYPE: HOLISTIC PR ANALYSIS
 
-${roleDefinition}
-
 ## PULL REQUEST OVERVIEW
 - **Total Files**: ${prFiles.length}
 - **Source Files**: ${prFiles.filter((f) => !f.isTest).length}
 - **Test Files**: ${prFiles.filter((f) => f.isTest).length}
 
 ## UNIFIED CONTEXT FROM PROJECT
-${projectArchitectureSection}
+Use the cached project context, project architecture, and custom instructions when evaluating this pull request.
 
 ### PROJECT CODE EXAMPLES
 ${formattedCodeExamples}
@@ -1398,9 +1441,6 @@ ${formattedPRComments}
 ## PR FILES WITH CHANGES
 ${formattedPRFiles}
 
-## CUSTOM INSTRUCTIONS
-${customDocsSection}
-
 ## YOUR TASK
 
 Analyze ALL PR FILES above using the 5-stage methodology:
@@ -1418,7 +1458,7 @@ Analyze ALL PR FILES above using the 5-stage methodology:
 - If you analyzed something and found it's fine, simply don't include it in the output
 `);
 
-  return { systemPrompt, userPrompt };
+  return { systemPrompt, userPrompt, cachedSystemBlocks };
 }
 
 /**
@@ -1487,7 +1527,7 @@ async function getPRCommentContext(filePath, options = {}) {
       verboseLog(options, chalk.blue(`🔍 Using pre-computed query embedding for PR comment search`));
       // We still need the file content for the search function, but not for embedding
       try {
-        fileContent = fs.readFileSync(filePath, 'utf8');
+        fileContent = await readTextFile(filePath);
         const maxEmbeddingLength = 8000; // Keep consistent with original truncation
         contentForSearch = fileContent.length > maxEmbeddingLength ? fileContent.substring(0, maxEmbeddingLength) : fileContent;
       }
@@ -1505,7 +1545,7 @@ async function getPRCommentContext(filePath, options = {}) {
     else {
       // Fallback to original behavior if no pre-computed embedding provided
       try {
-        fileContent = fs.readFileSync(filePath, 'utf8');
+        fileContent = await readTextFile(filePath);
       }
       catch (readError) {
         debug(`[getPRCommentContext] Could not read file ${filePath}: ${readError.message}`);

package/src/rag-analyzer.test.js

@@ -41,6 +41,10 @@ vi.mock('node:fs', () => ({
   default: {
     readFileSync: vi.fn(),
     existsSync: vi.fn().mockReturnValue(true),
+    promises: {
+      access: vi.fn().mockResolvedValue(undefined),
+      readFile: vi.fn(),
+    },
   },
 }));
 
@@ -155,6 +159,8 @@ describe('rag-analyzer', () => {
     mockEmbeddingsSystem.updatePRCommentsIndex.mockReset().mockResolvedValue(undefined);
     fs.readFileSync.mockReturnValue('const x = 1;\nconsole.log(x);');
     fs.existsSync.mockReturnValue(true);
+    fs.promises.access.mockReset().mockResolvedValue(undefined);
+    fs.promises.readFile.mockReset().mockResolvedValue('const x = 1;\nconsole.log(x);');
   });
 
   afterEach(() => {
@@ -197,7 +203,7 @@ describe('rag-analyzer', () => {
     });
 
     it('should return error when file does not exist', async () => {
-      fs.existsSync.mockReturnValue(false);
+      fs.promises.access.mockRejectedValue(new Error('ENOENT'));
       const result = await runAnalysis('/test/nonexistent.js');
       expect(result.success).toBe(false);
       expect(result.error).toContain('File not found');
@@ -369,13 +375,13 @@ describe('rag-analyzer', () => {
       ['whitespace only', '   \n\n   '],
       ['normal content', 'const x = 1;\nfunction test() {}'],
     ])('should handle %s', async (_, content) => {
-      fs.readFileSync.mockReturnValue(content);
+      fs.promises.readFile.mockResolvedValue(content);
       const result = await runAnalysis('/test/file.js');
       expect(result).toBeDefined();
     });
 
     it('should handle very long files', async () => {
-      fs.readFileSync.mockReturnValue(createMockLongCode(1000));
+      fs.promises.readFile.mockResolvedValue(createMockLongCode(1000));
       const result = await runAnalysis('/test/long.js');
       expect(result.success).toBe(true);
     });
@@ -772,7 +778,9 @@ describe('rag-analyzer', () => {
         customDocs: [{ content: 'Mandatory internal review rule', document_title: 'Internal Standards' }],
       });
 
-      expect(llm.sendPromptToClaude).toHaveBeenCalledWith(expect.stringContaining('Mandatory internal review rule'), expect.any(Object));
+      const [, options] = llm.sendPromptToClaude.mock.calls.at(-1);
+      expect(options.cachedSystemBlocks.join('\n')).toContain('Mandatory internal review rule');
+      expect(llm.sendPromptToClaude.mock.calls.at(-1)[0]).not.toContain('Mandatory internal review rule');
     });
 
     it('should log selected chunks when verbose', async () => {
@@ -954,7 +962,7 @@ describe('rag-analyzer', () => {
 
   describe('gatherUnifiedContextForPR error handling', () => {
     it('should handle file context gathering errors', async () => {
-      fs.readFileSync.mockImplementation((path) => {
+      fs.promises.readFile.mockImplementation((path) => {
         if (path.includes('error-file')) {
           throw new Error('Read error');
         }
@@ -1181,7 +1189,7 @@ describe('rag-analyzer', () => {
           return <div>{data}</div>;
         }
       `;
-      fs.readFileSync.mockReturnValue(richCode);
+      fs.promises.readFile.mockResolvedValue(richCode);
       setupSuccessfulLLMResponse();
       const result = await runAnalysis('/test/Dashboard.jsx');
       expect(result.success).toBe(true);

package/src/rag-review.js

@@ -10,7 +10,7 @@ import path from 'path';
 import chalk from 'chalk';
 import { runAnalysis, gatherUnifiedContextForPR } from './rag-analyzer.js';
 import { shouldProcessFile } from './utils/file-validation.js';
-import { findBaseBranch, getChangedLinesInfo, getFileContentFromGit } from './utils/git.js';
+import { ensureBranchExists, findParentBranch, getChangedLinesInfo, getFileContentFromGit } from './utils/git.js';
 import { detectFileType, detectLanguageFromExtension } from './utils/language-detection.js';
 import { verboseLog } from './utils/logging.js';
 import { shouldChunkPR, chunkPRFiles, combineChunkResults } from './utils/pr-chunking.js';
@@ -209,8 +209,9 @@ async function reviewPullRequest(changedFilePaths, options = {}) {
  * @param {boolean} [options.verbose=false] - Enable verbose progress logging
  * @param {number} [options.concurrency=3] - Maximum number of fallback per-file reviews to run in parallel
  * @param {string} [options.directory] - Working directory for git operations
- * @param {string} [options.diffWith='HEAD'] - Branch or ref to compare against
+ * @param {string} [options.diffWith='HEAD'] - Target branch or ref being reviewed against the detected base branch
  * @param {string} [options.actualBranch] - Actual target branch used for content retrieval
+ * @param {string} [options.baseBranch] - Pre-detected parent/base branch to diff against; detected here if omitted
  * @param {boolean} [options.skipChunking=false] - Skip PR chunking, used internally for chunk review recursion
  * @returns {Promise<Object>} Aggregated review results
  */
@@ -221,12 +222,27 @@ async function reviewPullRequestWithCrossFileContext(filesToReview, options = {}
 
     // Step 1: Get the base branch and collect diff info for all files in the PR
     const workingDir = options.directory ? path.resolve(options.directory) : process.cwd();
-    const baseBranch = findBaseBranch(workingDir);
     const targetBranch = options.diffWith || 'HEAD'; // The feature branch being reviewed
 
     // Get the actual branch name from options passed from index.js
     const actualTargetBranch = options.actualBranch || targetBranch;
 
+    // Prefer the parent branch already detected (and materialized locally) by the
+    // caller to avoid re-running the O(branches) detection. Only detect here when
+    // this function is invoked directly without a pre-detected base.
+    let baseBranch = options.baseBranch;
+    if (!baseBranch) {
+      baseBranch = findParentBranch(actualTargetBranch, workingDir);
+      // Detection may return a branch that exists only on the remote; ensure it
+      // resolves locally before it is used for diffing.
+      try {
+        ensureBranchExists(baseBranch, workingDir);
+      }
+      catch (error) {
+        verboseLog(verbose, chalk.yellow(`Could not ensure base branch '${baseBranch}' exists locally: ${error.message}`));
+      }
+    }
+
     verboseLog(verbose, chalk.gray(`Base branch: ${baseBranch}, Target branch: ${targetBranch}`));
 
     const prFiles = [];
@@ -319,7 +335,9 @@ async function reviewPullRequestWithCrossFileContext(filesToReview, options = {}
     verboseLog(
       verbose,
       chalk.green(
-        `De-duplicated context: ${deduplicatedCodeExamples.length} code examples, ${deduplicatedGuidelines.length} guidelines, ${deduplicatedPRComments.length} PR comments, ${deduplicatedCustomDocChunks.length} custom doc chunks`
+        `De-duplicated context: ${deduplicatedCodeExamples.length} code examples, ${deduplicatedGuidelines.length} guidelines, ${
+          deduplicatedPRComments.length
+        } PR comments, ${deduplicatedCustomDocChunks.length} custom doc chunks`
       )
     );
 

package/src/rag-review.test.js

@@ -1,7 +1,7 @@
 import { runAnalysis, gatherUnifiedContextForPR } from './rag-analyzer.js';
 import { reviewFile, reviewFiles, reviewPullRequest } from './rag-review.js';
 import { shouldProcessFile } from './utils/file-validation.js';
-import { getChangedLinesInfo, getFileContentFromGit } from './utils/git.js';
+import { ensureBranchExists, findParentBranch, getChangedLinesInfo, getFileContentFromGit } from './utils/git.js';
 import { shouldChunkPR, chunkPRFiles, combineChunkResults } from './utils/pr-chunking.js';
 
 vi.mock('./rag-analyzer.js', () => ({
@@ -19,7 +19,8 @@ vi.mock('./utils/file-validation.js', () => ({
 }));
 
 vi.mock('./utils/git.js', () => ({
-  findBaseBranch: vi.fn().mockReturnValue('main'),
+  ensureBranchExists: vi.fn(),
+  findParentBranch: vi.fn().mockReturnValue('main'),
   getChangedLinesInfo: vi.fn().mockReturnValue({
     hasChanges: true,
     addedLines: [1, 2, 3],
@@ -210,6 +211,38 @@ describe('rag-review', () => {
       expect(result.results).toEqual([]);
     });
 
+    it('should use a pre-detected baseBranch without re-running parent detection', async () => {
+      findParentBranch.mockClear();
+      getChangedLinesInfo.mockClear();
+      runAnalysis.mockResolvedValue({
+        success: true,
+        results: { issues: [], crossFileIssues: [], summary: 'OK' },
+      });
+
+      await reviewPullRequest(['/src/file.js'], { actualBranch: 'feature-B', baseBranch: 'feature-A' });
+
+      // Detection is skipped when the caller supplies the base branch...
+      expect(findParentBranch).not.toHaveBeenCalled();
+      // ...and the supplied base is what the per-file diff is computed against.
+      expect(getChangedLinesInfo).toHaveBeenCalledWith('/src/file.js', 'feature-A', 'feature-B', expect.any(String));
+    });
+
+    it('should detect and ensure the parent branch when none is supplied', async () => {
+      findParentBranch.mockClear();
+      ensureBranchExists.mockClear();
+      findParentBranch.mockReturnValue('main');
+      runAnalysis.mockResolvedValue({
+        success: true,
+        results: { issues: [], crossFileIssues: [], summary: 'OK' },
+      });
+
+      await reviewPullRequest(['/src/file.js'], { actualBranch: 'feature-X' });
+
+      expect(findParentBranch).toHaveBeenCalledWith('feature-X', expect.any(String));
+      // A detected (possibly remote-only) base must be materialized locally before diffing.
+      expect(ensureBranchExists).toHaveBeenCalledWith('main', expect.any(String));
+    });
+
     it('should skip files based on exclusion rules', async () => {
       shouldProcessFile.mockReturnValue(false);