@in-the-loop-labs/pair-review 3.1.1 → 3.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@in-the-loop-labs/pair-review",
-  "version": "3.1.1",
+  "version": "3.1.3",
   "description": "Your AI-powered code review partner - Close the feedback loop with AI coding agents",
   "main": "src/server.js",
   "bin": {

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pair-review",
-  "version": "3.1.1",
+  "version": "3.1.3",
   "description": "pair-review app integration — Open PRs and local changes in the pair-review web UI, run server-side AI analysis, and address review feedback. Requires the pair-review MCP server.",
   "author": {
     "name": "in-the-loop-labs",

package/plugin-code-critic/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "code-critic",
-  "version": "3.1.1",
+  "version": "3.1.3",
   "description": "AI-powered code review analysis — Run three-level AI analysis and implement-review-fix loops directly in your coding agent. Works standalone, no server required.",
   "author": {
     "name": "in-the-loop-labs",

package/public/js/components/DiffOptionsDropdown.js

@@ -57,11 +57,29 @@ class DiffOptionsDropdown {
     this._outsideClickHandler = null;
     this._escapeHandler = null;
 
-    // Scope state
-    const LS = window.LocalScope;
+    // Scope state — resolve LocalScope with inline fallback so the scope selector
+    // renders even if window.LocalScope failed to load (race condition guard).
+    const FALLBACK_STOPS = ['branch', 'staged', 'unstaged', 'untracked']; // Keep in sync with local-scope.js:STOPS
+    const FALLBACK_DEFAULT = { start: 'unstaged', end: 'untracked' };
+    this._localScope = window.LocalScope || {
+      STOPS: FALLBACK_STOPS,
+      DEFAULT_SCOPE: FALLBACK_DEFAULT,
+      isValidScope: (s, e) => {
+        const si = FALLBACK_STOPS.indexOf(s);
+        const ei = FALLBACK_STOPS.indexOf(e);
+        return si !== -1 && ei !== -1 && si <= ei;
+      },
+      scopeIncludes: (s, e, stop) => {
+        const si = FALLBACK_STOPS.indexOf(s);
+        const ei = FALLBACK_STOPS.indexOf(e);
+        const ti = FALLBACK_STOPS.indexOf(stop);
+        return ti !== -1 && ti >= si && ti <= ei;
+      }
+    };
+    const LS = this._localScope;
     this._branchAvailable = Boolean(branchAvailable);
-    this._scopeStart = (initialScope && initialScope.start) || (LS ? LS.DEFAULT_SCOPE.start : 'unstaged');
-    this._scopeEnd = (initialScope && initialScope.end) || (LS ? LS.DEFAULT_SCOPE.end : 'untracked');
+    this._scopeStart = (initialScope && initialScope.start) || LS.DEFAULT_SCOPE.start;
+    this._scopeEnd = (initialScope && initialScope.end) || LS.DEFAULT_SCOPE.end;
     this._scopeStops = [];
     this._scopeTrackEl = null;
     this._scopeDebounceTimer = null;
@@ -144,7 +162,7 @@ class DiffOptionsDropdown {
   /** Programmatically set scope. */
   set scope(val) {
     if (!val) return;
-    const LS = window.LocalScope;
+    const LS = this._localScope;
     if (LS && !LS.isValidScope(val.start, val.end)) return;
     this._scopeStart = val.start;
     this._scopeEnd = val.end;
@@ -188,8 +206,11 @@ class DiffOptionsDropdown {
     popover.style.zIndex = '1100';
     popover.style.transition = 'opacity 0.15s ease, transform 0.15s ease';
 
-    // Scope selector first — only in local mode
-    if (window.PAIR_REVIEW_LOCAL_MODE && window.LocalScope) {
+    // Scope selector first — only in local mode.
+    // Belt-and-suspenders: also render when scope callbacks were explicitly provided,
+    // in case a race condition prevents the globals from being set in time.
+    const hasLocalScope = (window.PAIR_REVIEW_LOCAL_MODE && window.LocalScope) || this._onScopeChange;
+    if (hasLocalScope) {
       this._renderScopeSelector(popover);
 
       // Divider between scope selector and whitespace checkbox
@@ -261,7 +282,7 @@ class DiffOptionsDropdown {
   }
 
   _renderScopeSelector(popover) {
-    const LS = window.LocalScope;
+    const LS = this._localScope;
 
     // Section container — generous horizontal padding so dots/labels breathe
     const section = document.createElement('div');
@@ -362,13 +383,43 @@ class DiffOptionsDropdown {
       stopEl.appendChild(dot);
       stopEl.appendChild(labelEl);
 
+      // Custom tooltip element (positioned above the dot, hidden by default)
+      const tooltipEl = document.createElement('div');
+      tooltipEl.style.position = 'absolute';
+      tooltipEl.style.bottom = '100%';
+      tooltipEl.style.left = '50%';
+      tooltipEl.style.transform = 'translateX(-50%)';
+      tooltipEl.style.marginBottom = '6px';
+      tooltipEl.style.padding = '4px 8px';
+      tooltipEl.style.fontSize = '11px';
+      tooltipEl.style.lineHeight = '1.3';
+      tooltipEl.style.color = 'var(--color-text-on-emphasis, #ffffff)';
+      tooltipEl.style.background = 'var(--color-neutral-emphasis, #24292f)';
+      tooltipEl.style.borderRadius = '4px';
+      tooltipEl.style.whiteSpace = 'nowrap';
+      tooltipEl.style.pointerEvents = 'none';
+      tooltipEl.style.opacity = '0';
+      tooltipEl.style.transition = 'opacity 0.12s ease';
+      tooltipEl.style.zIndex = '2';
+      stopEl.style.position = 'relative';
+      stopEl.appendChild(tooltipEl);
+
+      stopEl.addEventListener('mouseenter', () => {
+        if (tooltipEl.textContent) {
+          tooltipEl.style.opacity = '1';
+        }
+      });
+      stopEl.addEventListener('mouseleave', () => {
+        tooltipEl.style.opacity = '0';
+      });
+
       stopEl.addEventListener('click', (e) => {
         e.stopPropagation();
         this._handleStopClick(stop, e);
       });
 
       stopsRow.appendChild(stopEl);
-      this._scopeStops.push({ stop, dotEl: dot, labelEl, containerEl: stopEl });
+      this._scopeStops.push({ stop, dotEl: dot, labelEl, containerEl: stopEl, tooltipEl });
     });
 
     trackContainer.appendChild(stopsRow);
@@ -382,7 +433,7 @@ class DiffOptionsDropdown {
   }
 
   _handleStopClick(clickedStop, event) {
-    const LS = window.LocalScope;
+    const LS = this._localScope;
     if (!LS) return;
 
     // Branch disabled? Ignore.
@@ -396,10 +447,14 @@ class DiffOptionsDropdown {
     let newStart = this._scopeStart;
     let newEnd = this._scopeEnd;
 
-    // Alt/Option-click: solo-select this single stop
+    // 'unstaged' is always included — the AI reads files from the working
+    // tree, so the diff must always cover at least the unstaged state.
+    const ui = stops.indexOf('unstaged');
+
+    // Alt/Option-click: select this stop with minimum scope including unstaged
     if (event && event.altKey) {
-      newStart = clickedStop;
-      newEnd = clickedStop;
+      newStart = stops[Math.min(ci, ui)];
+      newEnd = stops[Math.max(ci, ui)];
     } else {
       // Checkbox-like toggle with contiguity constraint
       const included = ci >= si && ci <= ei;
@@ -407,6 +462,7 @@ class DiffOptionsDropdown {
       if (included) {
         // Toggling OFF — only allowed at boundaries, and range must have >1 stop
         if (si === ei) return;
+        if (clickedStop === 'unstaged') return; // unstaged is mandatory
         if (ci === si) {
           newStart = stops[si + 1];
         } else if (ci === ei) {
@@ -457,30 +513,48 @@ class DiffOptionsDropdown {
   }
 
   _updateScopeUI() {
-    const LS = window.LocalScope;
+    const LS = this._localScope;
     if (!LS || !this._scopeStops.length) return;
 
     const stops = LS.STOPS;
     const si = stops.indexOf(this._scopeStart);
     const ei = stops.indexOf(this._scopeEnd);
 
-    this._scopeStops.forEach(({ stop, dotEl, labelEl, containerEl }, i) => {
+    this._scopeStops.forEach(({ stop, dotEl, labelEl, containerEl, tooltipEl }, i) => {
       const included = LS.scopeIncludes(this._scopeStart, this._scopeEnd, stop);
       const isBranch = stop === 'branch';
       const disabled = isBranch && !this._branchAvailable;
 
-      // Determine if clicking this stop would do anything (for cursor hint)
-      const isBoundary = included && (i === si || i === ei) && si !== ei;
+      // Determine if clicking this stop would do anything (for cursor hint).
+      // 'unstaged' is mandatory and cannot be toggled off, so it is never a
+      // clickable boundary even when it sits at a range edge.
+      const isMandatory = stop === 'unstaged';
+      const atRangeEdge = included && (i === si || i === ei) && si !== ei;
+      const isBoundary = atRangeEdge && !isMandatory;
       const isAdjacent = !included && (i === si - 1 || i === ei + 1);
       const clickable = !disabled && (isBoundary || isAdjacent);
 
+      // Tooltip for disabled branch stop
+      containerEl.title = disabled ? 'No feature branch detected' : '';
+
+      // Mandatory stop sitting at a range edge — user might expect to toggle
+      // it off but can't.  Show not-allowed cursor and explanatory tooltip.
+      const mandatoryEdge = isMandatory && atRangeEdge;
+
+      // Update tooltip text (empty string hides the tooltip on hover)
+      if (tooltipEl) {
+        tooltipEl.textContent = mandatoryEdge
+          ? 'Unstaged changes are always included \u2014 the agent reads from your working tree'
+          : '';
+      }
+
       if (disabled) {
         // Disabled state
         dotEl.style.background = 'var(--color-bg-tertiary, #f6f8fa)';
         dotEl.style.borderColor = 'var(--color-border-secondary, #e1e4e8)';
         dotEl.style.boxShadow = 'none';
         labelEl.style.color = 'var(--color-text-tertiary, #8b949e)';
-        containerEl.style.cursor = 'not-allowed';
+        containerEl.style.cursor = 'default';
         containerEl.style.opacity = '0.5';
       } else if (included) {
         // Included (filled) state
@@ -489,7 +563,7 @@ class DiffOptionsDropdown {
         dotEl.style.boxShadow = '0 0 0 2px rgba(139, 92, 246, 0.2)';
         labelEl.style.color = 'var(--color-text-primary, #24292f)';
         labelEl.style.fontWeight = '600';
-        containerEl.style.cursor = clickable ? 'pointer' : 'default';
+        containerEl.style.cursor = clickable ? 'pointer' : (mandatoryEdge ? 'not-allowed' : 'default');
         containerEl.style.opacity = '1';
       } else {
         // Excluded (empty) state

package/src/ai/analyzer.js

@@ -126,8 +126,8 @@ async function runExecutableVoice(voiceProvider, reviewId, worktreePath, prMetad
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'pair-review-exec-'));
   try {
     const executableContext = {
-      title: prMetadata.title || '',
-      description: prMetadata.description || '',
+      title: prMetadata.title || null,
+      description: prMetadata.description || null,
       cwd: worktreePath,
       outputDir: tmpDir,
       model: voiceProvider.resolvedModel !== undefined ? voiceProvider.resolvedModel : (voiceProvider.model || null),
@@ -176,11 +176,16 @@ async function runExecutableVoice(voiceProvider, reviewId, worktreePath, prMetad
     });
 
     if (!result?.success || !result?.data) {
+      if (progressCallback) {
+        progressCallback({ level: 'exec', status: 'failed', progress: 'External tool returned no data' });
+      }
       throw new Error(`${logPrefix || ''}Executable provider returned no data`);
     }
 
+    const suggestions = result.data.suggestions || [];
+
     return {
-      suggestions: result.data.suggestions || [],
+      suggestions,
       summary: result.data.summary || ''
     };
   } finally {
@@ -2948,6 +2953,10 @@ File-level suggestions should NOT have a line number. They apply to the entire f
         const finalSuggestions = this.validateAndFinalizeSuggestions(result.suggestions, fileLineCountMap, validFiles);
         await this.storeSuggestions(reviewId, parentRunId, finalSuggestions, null, validFiles);
 
+        if (progressCallback) {
+          progressCallback({ level: 'exec', status: 'completed', progress: `External tool complete: ${finalSuggestions.length} suggestions` });
+        }
+
         try {
           await analysisRunRepo.update(parentRunId, {
             status: 'completed',
@@ -3074,6 +3083,10 @@ File-level suggestions should NOT have a line number. They apply to the entire f
           // Store validated voice suggestions
           await commentRepo.bulkInsertAISuggestions(reviewId, childRunId, validatedSuggestions, null);
 
+          if (voiceProgressCallback) {
+            voiceProgressCallback({ level: 'exec', status: 'completed', progress: `External tool complete: ${validatedSuggestions.length} suggestions` });
+          }
+
           const validatedResult = { ...result, suggestions: validatedSuggestions };
           return { voiceKey, reviewerLabel, childRunId, result: validatedResult, provider: voice.provider, model: voice.model, isExecutable: true, customInstructions: voice.customInstructions || null };
         }
@@ -3121,6 +3134,11 @@ File-level suggestions should NOT have a line number. They apply to the entire f
         } catch (err) {
           logger.warn(`[ReviewerCouncil] Failed to update child run ${childRunId}: ${err.message}`);
         }
+        // Notify the progress dialog so the voice row stops spinning
+        if (isExecutable && voiceProgressCallback) {
+          const terminalStatus = error.isCancellation ? 'cancelled' : 'failed';
+          voiceProgressCallback({ level: 'exec', status: terminalStatus, progress: error.message || 'Voice failed' });
+        }
         throw error;
       }
     });

package/src/chat/prompt-builder.js

@@ -8,7 +8,7 @@
  */
 
 const logger = require('../utils/logger');
-const { scopeGitHints, DEFAULT_SCOPE } = require('../local-scope');
+const { scopeGitHints, reviewScope } = require('../local-scope');
 
 /**
  * Build a lean system prompt for chat sessions.
@@ -142,8 +142,7 @@ function buildReviewContext(review, prData) {
     lines.push('');
     lines.push('## Viewing Code Changes');
 
-    const scopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
-    const scopeEnd = review.local_scope_end || DEFAULT_SCOPE.end;
+    const { start: scopeStart, end: scopeEnd } = reviewScope(review);
     const baseBranch = review.local_base_branch || null;
     const hints = scopeGitHints(scopeStart, scopeEnd, baseBranch);
 

package/src/config.js

@@ -385,6 +385,7 @@ function showWelcomeMessage() {
  */
 function expandPath(p) {
   if (!p) return p;
+  if (p === '~') return os.homedir();
   if (p.startsWith('~/')) {
     return path.join(os.homedir(), p.slice(2));
   }

package/src/database.js

@@ -20,7 +20,7 @@ function getDbPath() {
 /**
  * Current schema version - increment this when adding new migrations
  */
-const CURRENT_SCHEMA_VERSION = 35;
+const CURRENT_SCHEMA_VERSION = 36;
 
 /**
  * Database schema SQL statements
@@ -1605,6 +1605,36 @@ const MIGRATIONS = {
     addColumnIfNotExists('comments', 'severity', 'TEXT');
 
     console.log('Migration to schema version 35 complete');
+  },
+
+  // Migration to version 36: Normalize diff scopes to always include 'unstaged'.
+  // AI models read files from the working tree, so the diff scope must always
+  // cover at least the unstaged state for review context to be coherent.
+  36: (db) => {
+    console.log('Running migration to schema version 36...');
+
+    // Expand scopes where end < unstaged (branch-only, branch-staged, staged-only)
+    const expandEnd = db.prepare(
+      `UPDATE reviews SET local_scope_end = 'unstaged'
+       WHERE local_scope_end IN ('branch', 'staged') AND review_type = 'local'`
+    );
+    const expandResult = expandEnd.run();
+    if (expandResult.changes > 0) {
+      console.log(`  Expanded scope end to 'unstaged' for ${expandResult.changes} review(s)`);
+    }
+
+    // Fix untracked-only → unstaged..untracked
+    const fixUntracked = db.prepare(
+      `UPDATE reviews SET local_scope_start = 'unstaged'
+       WHERE local_scope_start = 'untracked' AND local_scope_end = 'untracked'
+       AND review_type = 'local'`
+    );
+    const fixResult = fixUntracked.run();
+    if (fixResult.changes > 0) {
+      console.log(`  Normalized untracked-only scope for ${fixResult.changes} review(s)`);
+    }
+
+    console.log('Migration to schema version 36 complete');
   }
 };
 

package/src/github/parser.js

@@ -30,7 +30,7 @@ class PRArgumentParser {
     // Check if input is a PR number
     const prNumber = parseInt(input);
     if (isNaN(prNumber) || prNumber <= 0) {
-      throw new Error('Invalid input format. Expected: PR number, GitHub URL (https://github.com/owner/repo/pull/number), Graphite URL (https://app.graphite.com/github/pr/owner/repo/number), or pair-review:// URL');
+      throw new Error('Invalid input format. Expected: PR number, GitHub URL (https://github.com/owner/repo/pull/number), Graphite URL (https://app.graphite.com/github/pr/owner/repo/number or https://app.graphite.com/github/owner/repo/pull/number), or pair-review:// URL');
     }
 
     // Parse repository from current directory's git remote
@@ -112,14 +112,18 @@ class PRArgumentParser {
    * @returns {Object} Parsed information { owner, repo, number }
    */
   parseGraphiteURL(url) {
-    // Match Graphite PR URL pattern: https://app.graphite.{dev|com}/github/pr/owner/repo/number[/optional-title]
-    const match = url.match(/^https:\/\/app\.graphite\.(?:dev|com)\/github\/pr\/([^\/]+)\/([^\/]+)\/(\d+)(?:\/[^?]*)?(?:\?.*)?$/);
+    // Match Graphite PR URL patterns:
+    //   https://app.graphite.{dev|com}/github/pr/owner/repo/number[/optional-title]
+    //   https://app.graphite.{dev|com}/github/owner/repo/pull/number[/optional-title]
+    const match = url.match(/^https:\/\/app\.graphite\.(?:dev|com)\/github\/(?:pr\/([^\/]+)\/([^\/]+)\/(\d+)|([^\/]+)\/([^\/]+)\/pull\/(\d+))(?:\/[^?]*)?(?:\?.*)?$/);
 
     if (!match) {
-      throw new Error('Invalid Graphite URL format. Expected: https://app.graphite.com/github/pr/owner/repo/number');
+      throw new Error('Invalid Graphite URL format. Expected: https://app.graphite.com/github/pr/owner/repo/number or https://app.graphite.com/github/owner/repo/pull/number');
     }
 
-    const [, owner, repo, numberStr] = match;
+    const owner = match[1] || match[4];
+    const repo = match[2] || match[5];
+    const numberStr = match[3] || match[6];
     return this._createPRInfo(owner, repo, numberStr, 'Graphite');
   }
 
@@ -156,7 +160,7 @@ class PRArgumentParser {
         ? 'https://github.com/owner/repo/pull/number'
         : source === 'pair-review://'
           ? 'pair-review://pr/owner/repo/number'
-          : 'https://app.graphite.com/github/pr/owner/repo/number';
+          : 'https://app.graphite.com/github/pr/owner/repo/number or https://app.graphite.com/github/owner/repo/pull/number';
       throw new Error(`Invalid ${source} URL format. Expected: ${exampleUrl}`);
     }
 

package/src/local-review.js

@@ -10,7 +10,7 @@ const { fireHooks, hasHooks } = require('./hooks/hook-runner');
 const { buildReviewStartedPayload, buildReviewLoadedPayload, getCachedUser } = require('./hooks/payloads');
 
 const execAsync = promisify(exec);
-const { STOPS, scopeIncludes, includesBranch, DEFAULT_SCOPE, scopeLabel } = require('./local-scope');
+const { STOPS, scopeIncludes, includesBranch, DEFAULT_SCOPE, scopeLabel, reviewScope } = require('./local-scope');
 const { initializeDatabase, ReviewRepository, RepoSettingsRepository } = require('./database');
 const { startServer } = require('./server');
 const { localReviewDiffs } = require('./routes/shared');
@@ -472,6 +472,13 @@ async function generateScopedDiff(repoPath, scopeStart, scopeEnd, baseBranch, op
   const hasUnstaged = scopeIncludes(scopeStart, scopeEnd, 'unstaged');
   const hasUntracked = scopeIncludes(scopeStart, scopeEnd, 'untracked');
 
+  // Fail fast if the scope is invalid. scopeIncludes returns false for all
+  // stops when the scope is invalid, so all four flags would be false and the
+  // branching logic below would silently produce a wrong diff.
+  if (!hasUnstaged) {
+    throw new Error(`Invalid scope ${scopeStart}..${scopeEnd}: scope must include 'unstaged'`);
+  }
+
   let mergeBaseSha = null;
   let diff = '';
 
@@ -483,46 +490,30 @@ async function generateScopedDiff(repoPath, scopeStart, scopeEnd, baseBranch, op
     mergeBaseSha = await findMergeBase(repoPath, baseBranch);
   }
 
-  // Build the git diff command based on scope range
+  // Build the git diff command based on scope range.
+  // hasUnstaged is always true by invariant — isValidScope requires the scope
+  // to include 'unstaged', since AI models read files from the working tree
+  // and the diff must cover at least the unstaged state.
   try {
-    if (hasBranch && !hasStaged && !hasUnstaged) {
-      // Branch only → committed changes since merge-base
-      diff = execSync(`git diff ${mergeBaseSha}..HEAD ${GIT_DIFF_FLAGS}${contextFlag}${extraArgsStr}${wFlag}`, {
-        cwd: repoPath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
-        maxBuffer: 50 * 1024 * 1024
-      });
-    } else if (hasBranch && hasStaged && !hasUnstaged) {
-      // Branch–Staged → staged changes relative to merge-base
-      diff = execSync(`git diff --cached ${mergeBaseSha} ${GIT_DIFF_FLAGS}${contextFlag}${extraArgsStr}${wFlag}`, {
-        cwd: repoPath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
-        maxBuffer: 50 * 1024 * 1024
-      });
-    } else if (hasBranch && hasUnstaged) {
-      // Branch–Unstaged (or Branch–Untracked) → working tree vs merge-base
+    if (hasBranch) {
+      // Branch scope → working tree vs merge-base (includes committed + staged + unstaged)
       diff = execSync(`git diff ${mergeBaseSha} ${GIT_DIFF_FLAGS}${contextFlag}${extraArgsStr}${wFlag}`, {
         cwd: repoPath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
         maxBuffer: 50 * 1024 * 1024
       });
-    } else if (hasStaged && !hasUnstaged) {
-      // Staged only → cached changes
-      diff = execSync(`git diff --cached ${GIT_DIFF_FLAGS}${contextFlag}${extraArgsStr}${wFlag}`, {
-        cwd: repoPath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
-        maxBuffer: 50 * 1024 * 1024
-      });
-    } else if (hasStaged && hasUnstaged) {
-      // Staged–Unstaged (or Staged–Untracked) → all changes vs HEAD
+    } else if (hasStaged) {
+      // Staged + Unstaged scope → all changes vs HEAD
       diff = execSync(`git diff HEAD ${GIT_DIFF_FLAGS}${contextFlag}${extraArgsStr}${wFlag}`, {
         cwd: repoPath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
         maxBuffer: 50 * 1024 * 1024
       });
-    } else if (hasUnstaged) {
-      // Unstaged only or Unstaged–Untracked → working tree changes
+    } else {
+      // Unstaged only (or Unstaged–Untracked) → working tree changes
       diff = execSync(`git diff ${GIT_DIFF_FLAGS}${contextFlag}${extraArgsStr}${wFlag}`, {
         cwd: repoPath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
         maxBuffer: 50 * 1024 * 1024
       });
     }
-    // hasUntracked-only: no git diff needed, just untracked files below
   } catch (error) {
     if (error.message && error.message.includes('maxBuffer')) {
       throw new Error('Diff output exceeded maximum buffer size (50MB).');
@@ -798,8 +789,8 @@ async function handleLocalReview(targetPath, flags = {}) {
     }
 
     // Read scope from session (or use defaults for new sessions)
-    const scopeStart = existingReview?.local_scope_start || DEFAULT_SCOPE.start;
-    const scopeEnd = existingReview?.local_scope_end || DEFAULT_SCOPE.end;
+    // Use reviewScope() to normalize legacy scopes that may not include 'unstaged'
+    const { start: scopeStart, end: scopeEnd } = existingReview ? reviewScope(existingReview) : DEFAULT_SCOPE;
 
     // Fire review hook (non-blocking)
     const hookEvent = existingReview ? 'review.loaded' : 'review.started';
@@ -937,7 +928,7 @@ async function computeLocalDiffDigest(localPath) {
  * @returns {Promise<{diff: string, stats: Object, mergeBaseSha: string}>}
  */
 async function generateBranchDiff(repoPath, baseBranch, options = {}) {
-  return generateScopedDiff(repoPath, 'branch', 'branch', baseBranch, options);
+  return generateScopedDiff(repoPath, 'branch', 'unstaged', baseBranch, options);
 }
 
 /**

package/src/local-scope.js

@@ -4,10 +4,29 @@ const STOPS = ['branch', 'staged', 'unstaged', 'untracked'];
 
 const DEFAULT_SCOPE = { start: 'unstaged', end: 'untracked' };
 
+const UNSTAGED_INDEX = STOPS.indexOf('unstaged');
+
 function isValidScope(start, end) {
   const si = STOPS.indexOf(start);
   const ei = STOPS.indexOf(end);
-  return si !== -1 && ei !== -1 && si <= ei;
+  // Scope must be contiguous AND must include the 'unstaged' stop.
+  // This ensures the diff always covers the working tree state that AI models
+  // see when reading files, since we cannot modify local git state.
+  return si !== -1 && ei !== -1 && si <= ei && si <= UNSTAGED_INDEX && ei >= UNSTAGED_INDEX;
+}
+
+function normalizeScope(start, end) {
+  if (isValidScope(start, end)) return { start, end };
+  const si = STOPS.indexOf(start);
+  const ei = STOPS.indexOf(end);
+  if (si === -1 || ei === -1) return { start: DEFAULT_SCOPE.start, end: DEFAULT_SCOPE.end };
+  const newEi = Math.max(ei, UNSTAGED_INDEX);
+  const newSi = Math.min(si, UNSTAGED_INDEX);
+  const finalSi = Math.min(newSi, newEi);
+  const newStart = STOPS[finalSi];
+  const newEnd = STOPS[newEi];
+  if (isValidScope(newStart, newEnd)) return { start: newStart, end: newEnd };
+  return { start: DEFAULT_SCOPE.start, end: DEFAULT_SCOPE.end };
 }
 
 function scopeIncludes(start, end, stop) {
@@ -27,11 +46,18 @@ function fromLegacyMode(localMode) {
     return { start: 'unstaged', end: 'untracked' };
   }
   if (localMode === 'branch') {
-    return { start: 'branch', end: 'branch' };
+    return { start: 'branch', end: 'unstaged' };
   }
   return { start: DEFAULT_SCOPE.start, end: DEFAULT_SCOPE.end };
 }
 
+function reviewScope(review) {
+  return normalizeScope(
+    review.local_scope_start || DEFAULT_SCOPE.start,
+    review.local_scope_end || DEFAULT_SCOPE.end
+  );
+}
+
 function scopeLabel(start, end) {
   if (!isValidScope(start, end)) return '';
   const label = s => s.charAt(0).toUpperCase() + s.slice(1);
@@ -57,16 +83,6 @@ function scopeGitHints(start, end, baseBranch) {
 
   const key = start + '-' + end;
   const hints = {
-    'branch-branch': {
-      description: 'Committed changes on this branch since the merge-base.',
-      diffCommand: 'git diff --no-ext-diff ' + mb + '..HEAD',
-      excludes: 'Staged, unstaged, and untracked changes are NOT included in the review.'
-    },
-    'branch-staged': {
-      description: 'Committed changes plus staged changes, relative to the merge-base.',
-      diffCommand: 'git diff --no-ext-diff --cached ' + mb,
-      excludes: 'Unstaged and untracked changes are NOT included in the review.'
-    },
     'branch-unstaged': {
       description: 'All tracked changes (committed, staged, and unstaged) relative to the merge-base.',
       diffCommand: 'git diff --no-ext-diff ' + mb,
@@ -77,11 +93,6 @@ function scopeGitHints(start, end, baseBranch) {
       diffCommand: 'git diff --no-ext-diff ' + mb,
       excludes: ''
     },
-    'staged-staged': {
-      description: 'Only staged changes (added to the index but not yet committed).',
-      diffCommand: 'git diff --no-ext-diff --cached',
-      excludes: 'Unstaged, untracked, and committed branch changes are NOT included in the review.'
-    },
     'staged-unstaged': {
       description: 'Staged and unstaged changes relative to HEAD.',
       diffCommand: 'git diff --no-ext-diff HEAD',
@@ -101,11 +112,6 @@ function scopeGitHints(start, end, baseBranch) {
       description: 'Unstaged and untracked local changes.',
       diffCommand: 'git diff --no-ext-diff',
       excludes: 'Staged changes (`git diff --no-ext-diff --cached`) are treated as already reviewed.'
-    },
-    'untracked-untracked': {
-      description: 'Only untracked files (new files not yet added to git).',
-      diffCommand: 'git ls-files --others --exclude-standard',
-      excludes: 'Tracked file changes (staged, unstaged, committed) are NOT included in the review.'
     }
   };
 
@@ -117,7 +123,7 @@ function scopeGitHints(start, end, baseBranch) {
     description: entry.description,
     diffCommand: entry.diffCommand,
     excludes: entry.excludes,
-    includesUntracked: incUntracked && key !== 'untracked-untracked'
+    includesUntracked: incUntracked
   };
 }
 
@@ -125,6 +131,8 @@ const LocalScope = {
   STOPS,
   DEFAULT_SCOPE,
   isValidScope,
+  normalizeScope,
+  reviewScope,
   scopeIncludes,
   includesBranch,
   fromLegacyMode,

package/src/routes/executable-analysis.js

@@ -55,15 +55,10 @@ async function generateDiffForExecutable(cwd, context, diffArgs, outputPath) {
   let diff;
   const extraFlags = diffArgs.length > 0 ? ' ' + diffArgs.join(' ') : '';
 
-  if (context.baseSha && context.headSha) {
-    // PR mode: straightforward base...head diff
-    const { stdout } = await execPromise(
-      `git diff ${GIT_DIFF_FLAGS}${extraFlags} ${context.baseSha}...${context.headSha}`,
-      { cwd, maxBuffer: 50 * 1024 * 1024 }
-    );
-    diff = stdout;
-  } else if (context.scopeStart && context.scopeEnd) {
-    // Local mode: scope-aware diff generation
+  if (context.scopeStart && context.scopeEnd) {
+    // Local mode: scope-aware diff generation (checked first because local reviews
+    // may also carry baseSha/headSha pointing at the same commit, which would
+    // produce an empty diff if the SHA path ran instead).
     // Note: diffArgs are passed as extraArgs to generateScopedDiff, which handles
     // appending them to the git diff command internally (extraFlags is not used here).
     const result = await generateScopedDiff(
@@ -74,6 +69,13 @@ async function generateDiffForExecutable(cwd, context, diffArgs, outputPath) {
       { contextLines: 3, extraArgs: diffArgs }
     );
     diff = result.diff;
+  } else if (context.baseSha && context.headSha) {
+    // PR mode: straightforward base...head diff
+    const { stdout } = await execPromise(
+      `git diff ${GIT_DIFF_FLAGS}${extraFlags} ${context.baseSha}...${context.headSha}`,
+      { cwd, maxBuffer: 50 * 1024 * 1024 }
+    );
+    diff = stdout;
   } else {
     // Fallback: simple working-tree diff
     const { stdout } = await execPromise(

package/src/routes/local.js

@@ -26,7 +26,7 @@ const { buildReviewStartedPayload, buildReviewLoadedPayload, buildAnalysisStarte
 const { mergeInstructions } = require('../utils/instructions');
 const { getGitHubToken } = require('../config');
 const { generateScopedDiff, computeScopedDigest, getBranchCommitCount, getFirstCommitSubject, detectAndBuildBranchInfo, findMergeBase, getCurrentBranch, getRepositoryName } = require('../local-review');
-const { STOPS, isValidScope, scopeIncludes, includesBranch, DEFAULT_SCOPE } = require('../local-scope');
+const { STOPS, isValidScope, normalizeScope, reviewScope, includesBranch, DEFAULT_SCOPE } = require('../local-scope');
 const { getGeneratedFilePatterns } = require('../git/gitattributes');
 const { getShaAbbrevLength } = require('../git/sha-abbrev');
 const { validateCouncilConfig, normalizeCouncilConfig } = require('./councils');
@@ -77,9 +77,10 @@ function deleteLocalReviewDiff(reviewId) {
  * Returns true if the guard fired (response already sent), false otherwise.
  */
 async function rejectIfEmptyScope(res, review, localPath) {
+  const { start: scopeStart, end: scopeEnd } = reviewScope(review);
   const scopeContext = {
-    scopeStart: review.local_scope_start || DEFAULT_SCOPE.start,
-    scopeEnd: review.local_scope_end || DEFAULT_SCOPE.end,
+    scopeStart,
+    scopeEnd,
     baseBranch: review.local_base_branch || null,
   };
   const changedFiles = await getChangedFiles(localPath, scopeContext);
@@ -461,8 +462,7 @@ router.post('/api/local/start', async (req, res) => {
     const config = req.app.get('config') || {};
     // Generate diff using default scope
     logger.log('API', `Starting local review for ${repoPath}`, 'cyan');
-    const scopeStart = existing?.local_scope_start || DEFAULT_SCOPE.start;
-    const scopeEnd = existing?.local_scope_end || DEFAULT_SCOPE.end;
+    const { start: scopeStart, end: scopeEnd } = existing ? reviewScope(existing) : DEFAULT_SCOPE;
 
     // Fire review hook (non-blocking, after scope is resolved)
     const hookEvent = existing ? 'review.loaded' : 'review.started';
@@ -580,9 +580,11 @@ router.get('/api/local/:reviewId', async (req, res) => {
       }
     }
 
-    // Build scope info for the response
-    const scopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
-    const scopeEnd = review.local_scope_end || DEFAULT_SCOPE.end;
+    // Build scope info for the response.
+    // normalizeScope clamps any legacy invalid scopes (e.g. branch-only,
+    // staged-only) to always include 'unstaged', since AI models read files
+    // from the working tree and the diff must match what they see.
+    const { start: scopeStart, end: scopeEnd } = reviewScope(review);
     const baseBranch = review.local_base_branch || null;
 
     // When scope does NOT include branch, check for branch detection info
@@ -693,8 +695,7 @@ router.get('/api/local/:reviewId', async (req, res) => {
     const hookConfig = req.app.get('config') || {};
     if (hasHooks('review.loaded', hookConfig)) {
       getCachedUser(hookConfig).then(user => {
-        const hookScopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
-        const hookScopeEnd = review.local_scope_end || DEFAULT_SCOPE.end;
+        const { start: hookScopeStart, end: hookScopeEnd } = reviewScope(review);
         const si = STOPS.indexOf(hookScopeStart);
         const ei = STOPS.indexOf(hookScopeEnd);
         const scope = STOPS.slice(si, ei + 1);
@@ -787,8 +788,7 @@ router.get('/api/local/:reviewId/diff', async (req, res) => {
     // When ?w=1 or ?base=<branch>, regenerate the diff (transient view, not cached)
     const hideWhitespace = req.query.w === '1';
     const baseBranchOverride = req.query.base;
-    const scopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
-    const scopeEnd = review.local_scope_end || DEFAULT_SCOPE.end;
+    const { start: scopeStart, end: scopeEnd } = reviewScope(review);
     const baseBranch = baseBranchOverride || review.local_base_branch;
     let diffData;
 
@@ -900,8 +900,7 @@ router.get('/api/local/:reviewId/check-stale', async (req, res) => {
       });
     }
 
-    const scopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
-    const scopeEnd = review.local_scope_end || DEFAULT_SCOPE.end;
+    const { start: scopeStart, end: scopeEnd } = reviewScope(review);
 
     // Always check HEAD SHA for supplementary fields
     let headShaChanged = false;
@@ -1042,19 +1041,22 @@ async function handleExecutableAnalysis(req, res, {
     registerProcessForCancellation
   }, {
     logLabel: `Review #${reviewId}`,
-    buildContext: (r, { selectedModel: model, requestInstructions: customInstructions }) => ({
-      title: null,
-      description: null,
-      cwd: localPath,
-      model,
-      baseSha: null,
-      headSha: r.local_head_sha || null,
-      baseBranch: r.local_base_branch || null,
-      headBranch: r.local_head_branch || null,
-      scopeStart: r.local_scope_start || DEFAULT_SCOPE.start,
-      scopeEnd: r.local_scope_end || DEFAULT_SCOPE.end,
-      customInstructions: customInstructions || null
-    }),
+    buildContext: (r, { selectedModel: model, requestInstructions: customInstructions }) => {
+      const { start: scopeStart, end: scopeEnd } = reviewScope(r);
+      return {
+        title: null,
+        description: null,
+        cwd: localPath,
+        model,
+        baseSha: null,
+        headSha: r.local_head_sha || null,
+        baseBranch: r.local_base_branch || null,
+        headBranch: r.local_head_branch || null,
+        scopeStart,
+        scopeEnd,
+        customInstructions: customInstructions || null
+      };
+    },
     buildHookPayload: () => ({
       mode: review.review_type || 'local',
       localContext: { path: localPath, branch: review.local_head_branch, headSha: review.local_head_sha }
@@ -1185,8 +1187,7 @@ router.post('/api/local/:reviewId/analyses', async (req, res) => {
     }
 
     // Extract scope early — needed for both analysis run creation and diff generation
-    const scopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
-    const scopeEnd = review.local_scope_end || DEFAULT_SCOPE.end;
+    const { start: scopeStart, end: scopeEnd } = reviewScope(review);
 
     // Create DB analysis_runs record immediately so it's queryable for polling
     const analysisRunRepo = new AnalysisRunRepository(db);
@@ -1281,13 +1282,14 @@ router.post('/api/local/:reviewId/analyses', async (req, res) => {
       reviewType: 'local'
     };
 
-    // Get changed files for local mode path validation
-    // When branch is in scope, pass null so analyzer falls through to getChangedFilesList
-    // which correctly uses git diff base_sha...head_sha --name-only
-    const hasStaged = scopeIncludes(scopeStart, scopeEnd, 'staged');
-    const changedFiles = hasBranch
-      ? null
-      : await analyzer.getLocalChangedFiles(localPath, { includeStaged: hasStaged });
+    // Get changed files for local mode path validation.
+    // Use the scope-aware helper so the file list matches the generated diff
+    // (covers branch, staged, unstaged, and untracked stops as appropriate).
+    const changedFiles = await getChangedFiles(localPath, {
+      scopeStart,
+      scopeEnd,
+      baseBranch: review.local_base_branch || null,
+    });
 
     // Log analysis start
     logger.section(`Local AI Analysis Request - Review #${reviewId}`);
@@ -1297,7 +1299,7 @@ router.post('/api/local/:reviewId/analyses', async (req, res) => {
     logger.log('API', `Provider: ${selectedProvider}`, 'cyan');
     logger.log('API', `Model: ${selectedModel}`, 'cyan');
     logger.log('API', `Tier: ${tier}`, 'cyan');
-    logger.log('API', `Changed files: ${changedFiles ? changedFiles.length : '(branch mode)'}`, 'cyan');
+    logger.log('API', `Changed files: ${changedFiles.length}`, 'cyan');
     if (combinedInstructions) {
       logger.log('API', `Custom instructions: ${combinedInstructions.length} chars`, 'cyan');
     }
@@ -1508,8 +1510,7 @@ router.post('/api/local/:reviewId/refresh', async (req, res) => {
 
     // Check if HEAD has changed
     const { getHeadSha } = require('../local-review');
-    const scopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
-    const scopeEnd = review.local_scope_end || DEFAULT_SCOPE.end;
+    const { start: scopeStart, end: scopeEnd } = reviewScope(review);
     const hasBranch = includesBranch(scopeStart);
     let currentHeadSha;
     let headShaChanged = false;
@@ -1627,8 +1628,7 @@ router.post('/api/local/:reviewId/resolve-head-change', async (req, res) => {
       return res.status(400).json({ error: 'Local review is missing path information' });
     }
 
-    const scopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
-    const scopeEnd = review.local_scope_end || DEFAULT_SCOPE.end;
+    const { start: scopeStart, end: scopeEnd } = reviewScope(review);
 
     if (action === 'update') {
       // Read live branch — may differ from stored value after a checkout.
@@ -1788,7 +1788,7 @@ router.post('/api/local/:reviewId/set-scope', async (req, res) => {
     await reviewRepo.updateLocalHeadSha(reviewId, headSha);
 
     // Auto-name review from first commit subject when branch is newly in scope
-    const oldScopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
+    const { start: oldScopeStart } = reviewScope(review);
     if (!review.name && includesBranch(scopeStart) && !includesBranch(oldScopeStart) && baseBranch) {
       const firstSubject = await getFirstCommitSubject(localPath, baseBranch);
       if (firstSubject) {
@@ -2021,8 +2021,7 @@ router.post('/api/local/:reviewId/analyses/council', async (req, res) => {
     // Guard: reject if scope resolves to zero changed files
     if (await rejectIfEmptyScope(res, review, localPath)) return;
 
-    const councilScopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
-    const councilScopeEnd = review.local_scope_end || DEFAULT_SCOPE.end;
+    const { start: councilScopeStart, end: councilScopeEnd } = reviewScope(review);
     const councilHasBranch = includesBranch(councilScopeStart);
 
     // Compute merge-base when branch is in scope
@@ -2038,8 +2037,8 @@ router.post('/api/local/:reviewId/analyses/council', async (req, res) => {
     const prMetadata = {
       reviewType: 'local',
       repository: review.repository,
-      title: review.name || (councilHasBranch ? `Branch changes: ${review.local_base_branch}..HEAD` : 'Local changes'),
-      description: '',
+      title: null,
+      description: null,
       base_sha: analysisBaseSha,
       head_sha: review.local_head_sha,
       base_branch: review.local_base_branch || null,
@@ -2049,10 +2048,13 @@ router.post('/api/local/:reviewId/analyses/council', async (req, res) => {
     };
 
     const analyzer = new Analyzer(db, 'council', 'council');
-    const councilHasStaged = scopeIncludes(councilScopeStart, councilScopeEnd, 'staged');
-    const changedFiles = councilHasBranch
-      ? null
-      : await analyzer.getLocalChangedFiles(localPath, { includeStaged: councilHasStaged });
+    // Use the scope-aware helper so the file list matches the generated diff
+    // (covers branch, staged, unstaged, and untracked stops as appropriate).
+    const changedFiles = await getChangedFiles(localPath, {
+      scopeStart: councilScopeStart,
+      scopeEnd: councilScopeEnd,
+      baseBranch: review.local_base_branch || null,
+    });
 
     // Generate and cache diff
     try {

package/src/routes/setup.js

@@ -15,7 +15,7 @@ const crypto = require('crypto');
 const { activeSetups, broadcastSetupProgress } = require('./shared');
 const { setupPRReview } = require('../setup/pr-setup');
 const { setupLocalReview } = require('../setup/local-setup');
-const { getGitHubToken } = require('../config');
+const { getGitHubToken, expandPath } = require('../config');
 const { queryOne } = require('../database');
 const { normalizeRepository } = require('../utils/paths');
 const logger = require('../utils/logger');
@@ -143,12 +143,13 @@ router.post('/api/setup/pr/:owner/:repo/:number', async (req, res) => {
  */
 router.post('/api/setup/local', async (req, res) => {
   try {
-    const { path: targetPath } = req.body;
+    const { path: rawPath } = req.body;
 
-    if (!targetPath) {
+    if (!rawPath) {
       return res.status(400).json({ error: 'Missing required field: path' });
     }
 
+    const targetPath = expandPath(rawPath);
     const db = req.app.get('db');
 
     // Concurrency guard

package/src/setup/local-setup.js

@@ -1,10 +1,10 @@
 // Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
-const { findGitRoot, getHeadSha, getCurrentBranch, getRepositoryName, generateLocalDiff, generateLocalReviewId, computeLocalDiffDigest, findMainGitRoot } = require('../local-review');
+const { findGitRoot, getHeadSha, getCurrentBranch, getRepositoryName, generateScopedDiff, generateLocalReviewId, computeScopedDigest, findMainGitRoot } = require('../local-review');
 const { ReviewRepository, RepoSettingsRepository } = require('../database');
 const { localReviewDiffs } = require('../routes/shared');
 const { fireHooks, hasHooks } = require('../hooks/hook-runner');
 const { buildReviewStartedPayload, buildReviewLoadedPayload, getCachedUser } = require('../hooks/payloads');
-const { STOPS, DEFAULT_SCOPE } = require('../local-scope');
+const { STOPS, DEFAULT_SCOPE, reviewScope } = require('../local-scope');
 const logger = require('../utils/logger');
 const path = require('path');
 const fs = require('fs').promises;
@@ -102,13 +102,16 @@ async function setupLocalReview({ db, targetPath, onProgress, config }) {
   // ── Step: diff ──────────────────────────────────────────────────────
   let diff, stats, digest;
   try {
+    const { start: scopeStart, end: scopeEnd } = existingReview ? reviewScope(existingReview) : DEFAULT_SCOPE;
+    const baseBranch = existingReview?.local_base_branch || null;
+
     progress({ step: 'diff', status: 'running', message: 'Generating diff for local changes...' });
 
-    const diffResult = await generateLocalDiff(repoPath);
+    const diffResult = await generateScopedDiff(repoPath, scopeStart, scopeEnd, baseBranch);
     diff = diffResult.diff;
     stats = diffResult.stats;
 
-    digest = await computeLocalDiffDigest(repoPath);
+    digest = await computeScopedDigest(repoPath, scopeStart, scopeEnd);
 
     progress({ step: 'diff', status: 'completed', message: `Diff ready: ${stats.unstagedChanges} unstaged, ${stats.untrackedFiles} untracked` });
   } catch (err) {
@@ -152,8 +155,7 @@ async function setupLocalReview({ db, targetPath, onProgress, config }) {
   if (config && hasHooks(hookEvent, config)) {
     getCachedUser(config).then(user => {
       const builder = existingReview ? buildReviewLoadedPayload : buildReviewStartedPayload;
-      const scopeStart = existingReview?.local_scope_start || DEFAULT_SCOPE.start;
-      const scopeEnd = existingReview?.local_scope_end || DEFAULT_SCOPE.end;
+      const { start: scopeStart, end: scopeEnd } = existingReview ? reviewScope(existingReview) : DEFAULT_SCOPE;
       const si = STOPS.indexOf(scopeStart);
       const ei = STOPS.indexOf(scopeEnd);
       const scope = STOPS.slice(si, ei + 1);