second-opinion-mcp 0.4.0 → 0.5.0

package/README.md

@@ -21,14 +21,59 @@ Then in Claude Code:
 
 That's it. The review appears in `second-opinions/`.
 
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Claude Code                               │
+│                                                                  │
+│  You: "Add user authentication"                                  │
+│  Claude: [reads files, writes code, runs tests]                  │
+│  You: "/second-opinion"                                          │
+│                                                                  │
+└─────────────────────┬───────────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Second Opinion MCP                            │
+│                                                                  │
+│  1. Parse Claude Code session logs                               │
+│  2. Collect files read/written + their content                   │
+│  3. Resolve dependencies and dependents                          │
+│  4. Find related tests and types                                 │
+│  5. Collect branch diff (feature branch vs base)                 │
+│  6. Bundle within token budget                                   │
+│  7. Send to Gemini + GPT (consensus mode)                        │
+│  8. Write response to second-opinions/                           │
+│                                                                  │
+└─────────────────────┬───────────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────────────────────┐
+│          second-opinions/add-auth.consensus.review.md            │
+│                                                                  │
+│  # Consensus Code Review                                         │
+│                                                                  │
+│  ## Synthesis                                                    │
+│  [Claude merges both perspectives with full context]             │
+│                                                                  │
+│  ## Gemini's Review                                              │
+│  [BLOCKING] Missing rate limiting on login endpoint              │
+│                                                                  │
+│  ## OpenAI's Review                                              │
+│  [SUGGESTION] Consider adding refresh token rotation             │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
 ## Features
 
 ### Automatic Context Collection
 
-Second Opinion reads your Claude Code session to understand what you're working on:
+Your session is the context. Second Opinion reads it automatically:
 
 - **Session files** — Files you read, edited, or created
-- **Conversation** — What you asked Claude to do (code blocks stripped to avoid stale references)
+- **Conversation** — What you asked Claude to do
 - **Dependencies** — Files imported by your modified code
 - **Dependents** — Files that import your modified code
 - **Tests** — Test files related to your changes
@@ -47,43 +92,31 @@ Don't just get code reviews—ask for anything:
 /second-opinion openai Identify potential performance bottlenecks
 ```
 
-### Multiple Providers
+### Consensus & Providers
 
-Switch between Gemini and GPT, or use both:
+By default, Second Opinion calls both Gemini and OpenAI in parallel. Claude then synthesizes the findings using its full session context—merging agreements, surfacing unique insights, and resolving disagreements.
 
 ```
-/second-opinion gemini Review this code    # Uses Gemini (default)
-/second-opinion openai Review this code    # Uses GPT
-/second-opinion consensus Review this code # Uses BOTH in parallel
+/second-opinion                        # Consensus (default) — both providers
+/second-opinion gemini Review this     # Gemini only
+/second-opinion openai Review this     # GPT only
 ```
 
-### Consensus Mode
+Consensus mode:
+- Calls both providers simultaneously
+- Claude synthesizes findings using the unified review framework
+- **Smart fallback**: if only one API key is configured, uses that single provider
 
-Get perspectives from both Gemini and OpenAI in a single request:
+### Diff-Scoped Reviews
 
-```
-/second-opinion consensus
-```
+On feature branches, Second Opinion automatically includes the git diff (branch vs base). Reviewers distinguish issues introduced by your changes from pre-existing issues in the codebase:
 
-Consensus mode:
-- Calls both providers simultaneously (faster than sequential calls)
-- Returns combined output with each model's perspective
-- Highlights areas of agreement and differences
-- Requires both `GEMINI_API_KEY` and `OPENAI_API_KEY` to be configured
+- **Findings** — Issues in the diff (your changes)
+- **Pre-existing Issues** — Legitimate issues NOT introduced by this change (lower priority)
 
 ### Smart Token Budgeting
 
-Context is prioritized to fit within token limits:
-
-1. Explicitly included files (highest priority)
-2. Session files (what you worked on)
-3. Git changes
-4. Dependencies
-5. Dependents
-6. Tests
-7. Type definitions
-
-Files that don't fit are listed in the output so you know what was omitted.
+Context is prioritized by category: explicitly included files first, then session files, git changes, dependencies, dependents, tests, and type definitions. Unused budget spills over to later categories. Files that don't fit are listed so you know what was omitted.
 
 ### Include Additional Files
 
@@ -100,10 +133,10 @@ Reference files outside your session:
 ```
 > /second-opinion
 
-Review complete! Written to second-opinions/add-auth-flow.gemini.review.md
+Consensus review complete! Written to second-opinions/add-auth-flow.consensus.review.md
 - Analyzed 14 files (52,000 tokens)
-- Key findings: Missing input validation in login handler,
-  consider rate limiting for auth endpoints
+- Key findings: [BLOCKING] Missing input validation in login handler,
+  [IMPORTANT] Consider rate limiting for auth endpoints
 ```
 
 ### Security Audit
@@ -129,21 +162,9 @@ Analysis complete! Written to second-opinions/add-auth-flow.openai.security-audi
   Include request/response examples.
 ```
 
-### Compare Perspectives
+### Single Provider
 
-Get reviews from both providers at once:
-
-```
-> /second-opinion consensus Review this implementation
-
-Consensus review complete! Written to second-opinions/auth-flow.consensus.review.md
-- Both models analyzed 14 files
-- Agreement: Both flagged the missing null check on line 42
-- Gemini highlighted: Performance concern with nested loops
-- OpenAI highlighted: Inconsistent error message formats
-```
-
-Or separately:
+When you want one model's perspective:
 
 ```
 > /second-opinion gemini Review this implementation
@@ -258,10 +279,11 @@ claude mcp add second-opinion \
 |----------|---------|-------------|
 | `GEMINI_API_KEY` | — | API key for Google Gemini |
 | `OPENAI_API_KEY` | — | API key for OpenAI |
-| `GEMINI_MODEL` | `gemini-2.0-flash-exp` | Gemini model to use |
-| `OPENAI_MODEL` | `gpt-4o` | OpenAI model to use |
-| `DEFAULT_PROVIDER` | `gemini` | Default provider when not specified |
-| `MAX_CONTEXT_TOKENS` | `100000` | Maximum tokens for context |
+| `GEMINI_MODEL` | `gemini-3-flash-preview` | Gemini model to use |
+| `OPENAI_MODEL` | `gpt-5.2` | OpenAI model to use |
+| `DEFAULT_PROVIDER` | `consensus` | Default provider (`gemini`, `openai`, or `consensus`) |
+| `MAX_CONTEXT_TOKENS` | `200000` | Maximum tokens for context |
+| `MAX_OUTPUT_TOKENS` | `32768` | Maximum tokens for reviewer's response |
 | `TEMPERATURE` | `0.3` | Default LLM temperature (0-1) |
 | `RATE_LIMIT_WINDOW_MS` | `60000` | Rate limit window (1 minute) |
 | `RATE_LIMIT_MAX_REQUESTS` | `10` | Max requests per window |
@@ -275,10 +297,11 @@ Create `~/.config/second-opinion/config.json`:
 {
   "geminiApiKey": "your-key",
   "openaiApiKey": "your-key",
-  "defaultProvider": "gemini",
-  "geminiModel": "gemini-2.0-flash-exp",
-  "openaiModel": "gpt-4o",
-  "maxContextTokens": 100000,
+  "defaultProvider": "consensus",
+  "geminiModel": "gemini-3-flash-preview",
+  "openaiModel": "gpt-5.2",
+  "maxContextTokens": 200000,
+  "maxOutputTokens": 32768,
   "temperature": 0.3,
   "rateLimitWindowMs": 60000,
   "rateLimitMaxRequests": 10,
@@ -311,7 +334,7 @@ When calling the MCP tool directly:
 
 | Parameter | Required | Default | Description |
 |-----------|----------|---------|-------------|
-| `provider` | Yes | — | `"gemini"`, `"openai"`, or `"consensus"` |
+| `provider` | Yes | — | `"gemini"`, `"openai"`, or `"consensus"` (falls back to single provider if only one key configured) |
 | `projectPath` | Yes | — | Absolute path to project |
 | `task` | No | — | Custom prompt (defaults to code review) |
 | `sessionId` | No | latest | Claude Code session ID |
@@ -324,55 +347,11 @@ When calling the MCP tool directly:
 | `includeDependents` | No | `true` | Include importing files |
 | `includeTests` | No | `true` | Include test files |
 | `includeTypes` | No | `true` | Include type definitions |
-| `maxTokens` | No | `100000` | Context token budget |
+| `maxInputTokens` | No | `200000` | Context token budget |
+| `maxOutputTokens` | No | `32768` | Max tokens for reviewer's response |
 | `temperature` | No | `0.3` | LLM temperature (0-1) |
 | `focusAreas` | No | — | Specific areas to focus on |
 
-## How It Works
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        Claude Code                               │
-│                                                                  │
-│  You: "Add user authentication"                                  │
-│  Claude: [reads files, writes code, runs tests]                  │
-│  You: "/second-opinion"                                          │
-│                                                                  │
-└─────────────────────┬───────────────────────────────────────────┘
-                      │
-                      ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                    Second Opinion MCP                            │
-│                                                                  │
-│  1. Parse Claude Code session logs                               │
-│  2. Collect files read/written + their content                   │
-│  3. Resolve dependencies and dependents                          │
-│  4. Find related tests and types                                 │
-│  5. Bundle within token budget                                   │
-│  6. Send to Gemini/GPT                                           │
-│  7. Write response to second-opinions/                           │
-│                                                                  │
-└─────────────────────┬───────────────────────────────────────────┘
-                      │
-                      ▼
-┌─────────────────────────────────────────────────────────────────┐
-│              second-opinions/add-auth.gemini.review.md           │
-│                                                                  │
-│  # Code Review - add-auth                                        │
-│  **Provider:** gemini                                            │
-│                                                                  │
-│  ## Summary                                                      │
-│  The authentication implementation is solid...                   │
-│                                                                  │
-│  ## Critical Issues                                              │
-│  - Missing rate limiting on login endpoint                       │
-│                                                                  │
-│  ## Suggestions                                                  │
-│  - Consider adding refresh token rotation                        │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-```
-
 ## Requirements
 
 - Node.js 18+

package/dist/config.js

@@ -34,7 +34,7 @@ export function loadConfig() {
             fileConfig = JSON.parse(fs.readFileSync(configPath, "utf-8"));
         }
         catch (error) {
-            console.error(`Warning: Invalid JSON in config file ${configPath}. Using defaults.`);
+            console.error(`Warning: Invalid JSON in config file ${configPath}. Using defaults.`, error instanceof Error ? error.message : String(error));
         }
     }
     const config = ConfigSchema.parse({
@@ -95,6 +95,12 @@ Work through these phases in order:
 ### Phase 3: Detailed Analysis
 - Correctness, security, performance, error handling, edge cases
 
+When a branch diff is provided:
+- Primary focus: code that appears in the diff (new/changed lines)
+- Use the diff to determine if an issue is newly introduced or pre-existing
+- Findings section = only issues in the diff
+- Pre-existing Issues section = legitimate issues NOT in the diff
+
 ### Phase 4: Self-Interrogation
 For each finding: form it as a question, search the code for evidence, then:
 - Confirmed → include as a finding with evidence
@@ -119,11 +125,18 @@ Brief overall assessment.
 
 ### Findings
 Ordered by severity, every finding grounded in specific code.
+When a branch diff is provided, only include issues introduced by the diff.
+
+### Pre-existing Issues
+(Include only when a branch diff is provided and pre-existing issues are found.)
+Issues found in reviewed files that were NOT introduced by this change.
+Same severity labels and evidence requirements as Findings.
 
 ### Questions
 Findings that couldn't be fully grounded.
 
 ### Upstream/Downstream Opportunities
+Architectural suggestions beyond the current change.
 - **What/Where** · **Why** · **Risk Level**: Safe / Worth Investigating / Bold
 
 ### What's Done Well

package/dist/context/bundler.d.ts

@@ -1,3 +1,4 @@
+import { BudgetCategory } from "../utils/tokens.js";
 export interface BlockedFile {
     path: string;
     reason: "sensitive_path" | "outside_project_requires_allowExternalFiles";
@@ -48,6 +49,8 @@ export interface ContextBundle {
         commentsCount: number;
         reviewsCount: number;
     };
+    /** Unified diff of branch changes (from base branch), kept separate from file markdown */
+    branchDiff?: string;
     files: FileEntry[];
     omittedFiles: OmittedFile[];
     totalTokens: number;
@@ -74,8 +77,43 @@ export interface ContextBundle {
         message: string;
     };
 }
+export interface CandidateFile {
+    path: string;
+    content: string;
+    category: FileEntry["category"];
+    tokenEstimate: number;
+    annotation?: string;
+    redactionCount: number;
+    redactedTypes: string[];
+}
+export interface CategoryCandidates {
+    category: BudgetCategory;
+    files: CandidateFile[];
+    totalDemand: number;
+}
+export interface AllocationResult {
+    included: FileEntry[];
+    omitted: OmittedFile[];
+    categoryTokens: Record<BudgetCategory, number>;
+}
+/**
+ * Two-pass budget allocator.
+ *
+ * If total demand <= filePool, include everything (common case, fixes the original bug).
+ * If total demand > filePool, redistribute surplus from low-demand categories to high-demand ones.
+ *
+ * Within each category:
+ * - explicit/session: preserve insertion order (user intent)
+ * - all others: sort smallest first (maximize file count)
+ */
+export declare function allocateBudget(candidates: CategoryCandidates[], filePool: number, budgetWeights: Record<BudgetCategory, number>, priorityOrder: BudgetCategory[]): AllocationResult;
 /**
- * Collect and bundle all context for review
+ * Collect and bundle all context for review.
+ *
+ * Two-pass architecture:
+ *   Pass 1 (Collection): Gather all candidate files per category without committing budget.
+ *   Deduplication: Assign each file to its highest-priority category.
+ *   Pass 2 (Allocation): Distribute the file pool across categories via allocateBudget().
  */
 export declare function bundleContext(options: BundleOptions): Promise<ContextBundle>;
 /**