iterate-plugin 2.7.3 → 2.8.1

package/dist/tools/fix.js

@@ -20,6 +20,7 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { loadEffectiveConfig, resolveProjectRoot } from "../config-loader.js";
+import { countTouchedMethods } from "../method-scope.js";
 import { fixBackupPath, fixRegistryPath, fixesDir } from "../paths.js";
 import { appendDecisionEntry } from "./decision-log.js";
 // ─── Constants ───────────────────────────────────────────────────────────────
@@ -218,7 +219,7 @@ export function registerFixTool(ctx) {
         name: 'iterate_fix',
         description: 'Apply ONE atomic fix to a file. Pass the target relative `file`, the finding that motivated ' +
             'the fix, the NEW full `content` of that file (after your edit), and the current `round`. ' +
-            'The tool backs up the original, enforces the atomic `max_lines` threshold (unless `force`), ' +
+            'The tool backs up the original, enforces the atomic `max_lines` and `max_adjacent_methods` thresholds (unless `force`), ' +
             'writes the new content, and records the fix for later diff/rollback. ' +
             'This is the ONLY sanctioned way to apply fixes in normal mode.',
         parameters: {
@@ -278,6 +279,7 @@ export function registerFixTool(ctx) {
             const projectRoot = resolved.root;
             const { config } = loadEffectiveConfig(projectRoot);
             const maxLines = config.atomic?.max_lines ?? 20;
+            const maxAdjacentMethods = config.atomic?.max_adjacent_methods ?? 3;
             const file = typeof args.file === 'string' ? args.file : '';
             if (!file)
                 return { ok: false, error: 'file is required' };
@@ -305,6 +307,7 @@ export function registerFixTool(ctx) {
             const current = readProjectFile(projectRoot, file);
             if (!current.ok)
                 return { ok: false, error: current.reason };
+            const hunks = diffLines(current.content, args.content);
             const { added, removed } = countChangedLines(current.content, args.content);
             if (!args.force && (added > maxLines || removed > maxLines)) {
                 return {
@@ -313,6 +316,14 @@ export function registerFixTool(ctx) {
                         'Either split it into smaller atomic fixes or pass force:true if this is a deliberate architectural change.',
                 };
             }
+            const touchedMethods = countTouchedMethods(current.content, args.content, hunks);
+            if (!args.force && touchedMethods > maxAdjacentMethods) {
+                return {
+                    ok: false,
+                    error: `Change to ${file} touches ${touchedMethods} adjacent method(s), exceeds atomic.max_adjacent_methods (${maxAdjacentMethods}). ` +
+                        'Split it into smaller atomic fixes or pass force:true if this is a deliberate multi-method change.',
+                };
+            }
             const id = fixId(finding);
             const registry = readRegistry(projectRoot);
             if (findFixRecord(registry, id)) {
@@ -336,7 +347,6 @@ export function registerFixTool(ctx) {
             catch (err) {
                 return { ok: false, error: `failed to write file: ${String(err)}` };
             }
-            const hunks = diffLines(current.content, args.content);
             const record = {
                 id,
                 timestamp,

package/dist/tools/review.js

@@ -1,7 +1,10 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { loadEffectiveConfig, resolveProjectRoot } from "../config-loader.js";
-import { buildReviewPlan, buildReviewReport } from "../review.js";
+import { buildReviewPlan, buildReviewReport, sanitizeRounds, validateRoundsSchema, } from "../review.js";
 import { buildFinalReviewReport, metaReviewReport } from "../meta-review.js";
+import { evidenceToPlain, verifyFindings } from "../evidence.js";
+import { collectScopeFiles, computeCoverage, coverageToDict, } from "../review-scope.js";
+import { resolveChangedFiles } from "../git-scope.js";
 /** Default round cap when neither the arg nor config provides one. */
 const DEFAULT_MAX_REVIEW_ROUNDS = 3;
 /**
@@ -82,6 +85,19 @@ export function registerReviewTool(ctx) {
                     found: { type: 'boolean' },
                     plan: { type: 'json' },
                     report: { type: 'json' },
+                    schemaValidation: {
+                        type: 'json',
+                        description: 'For `aggregate`: per-round schema validation results (round, valid, issues). ' +
+                            'Present only when reviewer.output_schema_validation is enabled; the workflow ' +
+                            'retries rounds with valid=false (≤2 times) before forwarding findings.',
+                    },
+                    evidence: { type: 'json' },
+                    coverage: {
+                        type: 'json',
+                        description: 'For `meta-review`: prompt-informative scope coverage result ' +
+                            '(assigned vs self-reported reads). Present only when ' +
+                            'reviewer.coverage_validation is enabled and readFiles were supplied.',
+                    },
                     finalReport: { type: 'json' },
                     error: { type: 'string' },
                 },
@@ -104,7 +120,23 @@ export function registerReviewTool(ctx) {
                 const maxReviewRounds = args.maxReviewRounds ?? config.max_rounds ?? DEFAULT_MAX_REVIEW_ROUNDS;
                 const knownIntentional = config.personalization
                     ?.known_intentional;
-                const plan = buildReviewPlan({ config, mode, maxReviewRounds, knownIntentional });
+                // changed-only scope: resolve the changed-file set against
+                // git.target_branch before building the plan so reviewers get the
+                // concrete file list (and the plan auto-falls back to full when there
+                // are no changes). git failures degrade to a full-scope plan.
+                let changedFiles;
+                if (config.review?.scope === 'changed-only') {
+                    const gitScope = await resolveChangedFiles(projectRoot, config.git?.target_branch ?? 'main');
+                    changedFiles = gitScope.changedFiles;
+                }
+                // Full-codebase review: pre-collect the source inventory so
+                // buildReviewPlan can batch it into per-chunk reviewer tasks
+                // (coverage enforcement).
+                let scopeFiles;
+                if (config.review?.scope === 'full') {
+                    scopeFiles = collectScopeFiles(projectRoot, { scope: 'full' });
+                }
+                const plan = buildReviewPlan({ config, mode, maxReviewRounds, knownIntentional, changedFiles, scopeFiles });
                 return { operation: 'plan', mode, found: true, plan: plan };
             }
             if (args.operation === 'aggregate') {
@@ -126,16 +158,32 @@ export function registerReviewTool(ctx) {
                 const maxReviewRounds = args.maxReviewRounds ?? config.max_rounds ?? DEFAULT_MAX_REVIEW_ROUNDS;
                 const goal = args.goal ?? config.goal ?? '';
                 const dimensions = config.dimensions ?? [];
+                // Output schema validation gate (reviewer.output_schema_validation,
+                // default true): validate every round's findings against the findings
+                // schema, then drop schema-invalid entries before the deterministic
+                // core so malformed reviewer output can never crash dedupe/sort or
+                // leak into fixes. The `schemaValidation` array is surfaced so the
+                // workflow can retry failing rounds (≤2 times) with a strict-JSON
+                // nudge. When disabled, non-object entries are still dropped for
+                // crash-safety.
+                const schemaEnabled = config.reviewer?.output_schema_validation !== false;
+                const schemaValidation = schemaEnabled ? validateRoundsSchema(rounds) : null;
+                const cleanRounds = sanitizeRounds(rounds, schemaValidation);
                 const report = buildReviewReport({
                     mode,
                     goal,
                     dimensions,
                     maxReviewRounds,
-                    rounds,
+                    rounds: cleanRounds,
                     knownIntentional: args.knownIntentional,
                     fixedCount: typeof args.fixedCount === 'number' ? args.fixedCount : undefined,
                 });
-                return { operation: 'aggregate', mode, report: report };
+                return {
+                    operation: 'aggregate',
+                    mode,
+                    report: report,
+                    schemaValidation: schemaValidation,
+                };
             }
             if (args.operation === 'meta-review') {
                 const source = args.report;
@@ -147,12 +195,36 @@ export function registerReviewTool(ctx) {
                     };
                 }
                 const audit = metaReviewReport(source);
-                const finalReport = buildFinalReviewReport(source);
+                // Hard code-evidence gate (default on): every finding's file/line is
+                // validated against real files on disk before folding into the final
+                // verdict. Disable via config `reviewer.evidence_validation: false`.
+                const evidenceEnabled = config.reviewer?.evidence_validation !== false;
+                const findings = Array.isArray(source.findings) ? source.findings : [];
+                const evidence = evidenceEnabled ? verifyFindings(projectRoot, findings) : null;
+                // Prompt-informative coverage: compare the reviewer's self-reported
+                // reads against the assigned scope inventory (never flips the
+                // verdict). Disable via config `reviewer.coverage_validation: false`.
+                const coverageEnabled = config.reviewer?.coverage_validation !== false;
+                let coverage = null;
+                if (coverageEnabled) {
+                    const assigned = collectScopeFiles(projectRoot, {
+                        scope: config.review?.scope === 'changed-only' ? 'changed-only' : 'full',
+                    });
+                    const readFiles = Array.isArray(source.readFiles)
+                        ? source.readFiles
+                        : null;
+                    if (readFiles && readFiles.length > 0) {
+                        coverage = computeCoverage(assigned, readFiles);
+                    }
+                }
+                const finalReport = buildFinalReviewReport(source, { evidence, coverage });
                 return {
                     operation: 'meta-review',
                     mode,
                     found: true,
                     report: audit,
+                    evidence: evidence ? evidenceToPlain(evidence) : null,
+                    coverage: coverage ? coverageToDict(coverage) : null,
                     finalReport: finalReport,
                 };
             }

package/lib/client.js

@@ -983,19 +983,6 @@ function setThemeEnabled(enabled) {
   if (enabled) applyThemeSkin();
   else clearThemeSkin();
 }
-function sessionSnapshot(props) {
-  let session = null;
-  const useSession = props && typeof props.useSession === "function" ? props.useSession : null;
-  if (useSession) {
-    try {
-      session = useSession();
-    } catch (err) {
-      log("useSession failed", err);
-    }
-  }
-  if (!session && props && props.session) session = props.session;
-  return session;
-}
 function latestReport(session) {
   if (!session) return null;
   const raw = scanSessionForReport(session) || findReportInObject(session, void 0, 24);
@@ -1017,7 +1004,9 @@ function TrendChart({ points }) {
 }
 function ConvergenceDashboard(props) {
   const [pulseKey, setPulseKey] = React.useState(0);
-  const report = latestReport(sessionSnapshot(props));
+  const useSession = props && typeof props.useSession === "function" ? props.useSession : null;
+  const session = useSession ? useSession((s) => s) : props && props.session ? props.session : null;
+  const report = latestReport(session);
   React.useEffect(() => {
     if (!report) return;
     const cur = getCurrentRound(report);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "2.7.3",
+  "version": "2.8.1",
   "description": "dsh plugin that turns the iterate skill into an autonomous closed-loop harness: plan -> parallel review xN -> atomic fixes -> validate -> loop -> auto-stop, plus a dry-run pure-review mode with multi-round convergence and a meta-review that audits the report and emits a final review report.",
   "type": "module",
   "license": "MIT",

package/src/client/index.ts

@@ -492,17 +492,6 @@ function setThemeEnabled(enabled: boolean): void {
 
 // ─── Components (React.createElement trees) ──────────────────────────────────
 
-/** Obtain a session snapshot defensively from the slot props. */
-function sessionSnapshot(props: SlotProps) {
-  let session: unknown = null
-  const useSession = props && typeof props.useSession === 'function' ? props.useSession as () => unknown : null
-  if (useSession) {
-    try { session = useSession() } catch (err) { log('useSession failed', err) }
-  }
-  if (!session && props && props.session) session = props.session
-  return session
-}
-
 /** Find the latest report inside a session snapshot (normalized). */
 function latestReport(session: unknown): ReviewReport | null {
   if (!session) return null
@@ -529,7 +518,15 @@ function TrendChart({ points }: { points: Array<{ round: number; count: number }
 /** Dashboard: live convergence strip above the composer. */
 function ConvergenceDashboard(props: SlotProps) {
   const [pulseKey, setPulseKey] = React.useState(0)
-  const report = latestReport(sessionSnapshot(props))
+  // useSession is a SnapshotSelectorHook — it requires a selector fn (identity
+  // returns the whole snapshot). Call it unconditionally at the top level to
+  // satisfy the React hooks contract; the owner share (props.session) is the
+  // fallback when the hook is absent.
+  const useSession = props && typeof props.useSession === 'function'
+    ? props.useSession as (sel: (s: unknown) => unknown) => unknown
+    : null
+  const session = useSession ? useSession((s: unknown) => s) : (props && props.session ? props.session : null)
+  const report = latestReport(session)
 
   React.useEffect(() => {
     if (!report) return

package/src/config-loader.ts

@@ -49,7 +49,12 @@ export function defaultConfig(): IterateConfig {
       auto_merge: false,
     },
     validation: { command_whitelist: [], commands: {} },
-    reviewer: { output_schema_validation: true },
+    reviewer: {
+      output_schema_validation: true,
+      evidence_validation: true,
+      coverage_validation: true,
+      scope_chunk_size: 25,
+    },
   }
 }
 

package/src/evidence.ts

@@ -0,0 +1,213 @@
+/**
+ * Deterministic code-evidence verification for review findings.
+ *
+ * Mirror of `iterate_harness/iterate/evidence.py` for the iterate-plugin.
+ *
+ * The iterate review loop requires that reviewer subagent findings ANCHOR to
+ * real code instead of speculating. This module enforces it:
+ *
+ * - a finding's `file` must resolve to an existing file under the project root
+ *   (traversal-safe), otherwise evidence is poisoned (`file_not_found`);
+ * - a finding with an explicit line must reference a line that actually exists
+ *   in that file (`line_out_of_range`);
+ * - a whole-file finding (line 0 / undefined) must still reference an existing
+ *   file, so even structural findings cannot point at nothing;
+ * - `readVerified` is a best-effort, NON-gating hint: the plugin's reviewers are
+ *   subagents whose reads are not aggregated here, so it is only set when a
+ *   read set is explicitly provided and never fails the audit.
+ *
+ * Gate rule (user preference): ANY localizable finding with poisoned evidence
+ * flips the whole audit to `passed: false`, so the meta-review forces revision.
+ *
+ * The pure math (`countLines`, `verifyLineBounds`) is separated from the
+ * filesystem half (`verifyFinding`) to stay unit-testable without touching disk.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve, sep } from 'node:path'
+import type { ReviewFinding } from './types.ts'
+
+/** Sentinel for whole-file findings (line 0 or omitted means the whole file). */
+export const WHOLE_FILE_LINE = 0
+
+export type EvidenceError = 'file_not_found' | 'line_out_of_range'
+
+/** Per-finding attestation result. */
+export interface FindingEvidence {
+  file: string
+  line: number | null
+  lineTotal: number | null
+  resolvedPath: string | null
+  verified: boolean
+  error?: EvidenceError
+  /** True/False only when a read-set is supplied; undefined = not checkable. */
+  readVerified?: boolean
+}
+
+/** Aggregate attestation over a findings list. */
+export interface EvidenceAudit {
+  checked: number
+  results: FindingEvidence[]
+}
+
+/** A single finding object that exposes `file` / `line` (for verification). */
+interface Locatable {
+  file?: string
+  line?: number
+}
+
+/** Number of physical lines in `text`. A trailing newline does not add a line. */
+export function countLines(text: string): number {
+  if (text === '') return 0
+  // Mirrors Python `str.splitlines()`: split on every line separator, not just
+  // \r\n|\r|\n — otherwise line counts diverge from the harness on files
+  // containing \v \f \x1c-\x1e \x85 \u2028 \u2029.
+  const parts = text.split(/\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029]/)
+  // A trailing newline leaves an empty final element that is NOT a line
+  // (mirrors Python `str.splitlines()` used by the harness).
+  if (parts[parts.length - 1] === '') return parts.length - 1
+  return parts.length
+}
+
+/** Resolve `root/rel` and reject any path escaping `root` (returns null). */
+export function resolveWithin(root: string, rel: string): string | null {
+  const resolved = resolve(root, rel)
+  const rootResolved = resolve(root)
+  if (resolved === rootResolved) return resolved
+  const prefix = rootResolved.endsWith(sep) ? rootResolved : rootResolved + sep
+  if (!resolved.startsWith(prefix)) return null
+  return resolved
+}
+
+/**
+ * Pure check that `line` (if anchored) exists in `text`.
+ * Whole-file findings (undefined/0) are always bounds-valid.
+ */
+export function verifyLineBounds(
+  line: number | null | undefined,
+  text: string,
+): { inBounds: boolean; lineTotal: number } {
+  const lineTotal = countLines(text)
+  if (line === undefined || line === null || line === WHOLE_FILE_LINE) {
+    return { inBounds: true, lineTotal }
+  }
+  if (line < 1) return { inBounds: false, lineTotal }
+  return { inBounds: line <= lineTotal, lineTotal }
+}
+
+/** Verify a single finding's location against the real filesystem. */
+export function verifyFinding(
+  root: string,
+  input: Locatable,
+  opts: { readSet?: Set<string> } = {},
+): FindingEvidence {
+  const relFile = input.file ?? ''
+  const line = typeof input.line === 'number' ? input.line : null
+  const resolved = resolveWithin(root, relFile)
+
+  if (resolved === null || !existsSync(resolved)) {
+    return {
+      file: relFile,
+      line,
+      lineTotal: null,
+      resolvedPath: resolved,
+      verified: false,
+      error: 'file_not_found',
+    }
+  }
+
+  let raw: Buffer
+  try {
+    raw = readFileSync(resolved)
+  } catch {
+    return {
+      file: relFile,
+      line,
+      lineTotal: null,
+      resolvedPath: resolved,
+      verified: false,
+      error: 'file_not_found',
+    }
+  }
+
+  // A file is not line-addressable if it contains a NUL byte (binary payload).
+  // Anchored line numbers on a binary file cannot be trusted, so treat them the
+  // same as an out-of-range line rather than credulously accepting them
+  // (mirrors the harness `evidence.py` NUL check).
+  if (raw.includes(0)) {
+    return {
+      file: relFile,
+      line,
+      lineTotal: null,
+      resolvedPath: resolved,
+      verified: false,
+      error: 'line_out_of_range',
+    }
+  }
+
+  const text = raw.toString('utf-8')
+  const { inBounds, lineTotal } = verifyLineBounds(line, text)
+  if (!inBounds) {
+    return {
+      file: relFile,
+      line,
+      lineTotal,
+      resolvedPath: resolved,
+      verified: false,
+      error: 'line_out_of_range',
+    }
+  }
+
+  const outcome: FindingEvidence = {
+    file: relFile,
+    line,
+    lineTotal,
+    resolvedPath: resolved,
+    verified: true,
+  }
+  if (opts.readSet !== undefined) {
+    outcome.readVerified = opts.readSet.has(resolved)
+  }
+  return outcome
+}
+
+/** Attest every finding in a list. */
+export function verifyFindings(
+  root: string,
+  findings: Locatable[],
+  opts: { readSet?: Set<string> } = {},
+): EvidenceAudit {
+  const results = findings.map((f) => verifyFinding(root, f, opts))
+  return { checked: results.length, results }
+}
+
+/** `passed` is true only when no real existence failure exists (read is a hint). */
+export function evidencePassed(audit: EvidenceAudit): boolean {
+  return audit.results.every((r) => r.error === undefined)
+}
+
+/** Violating (non-grounded) results. */
+export function evidenceViolations(audit: EvidenceAudit): FindingEvidence[] {
+  return audit.results.filter((r) => r.error !== undefined)
+}
+
+/** Serialize an audit for tool payloads (pure). */
+export function evidenceToPlain(audit: EvidenceAudit): Record<string, unknown> {
+  const computable = audit.results.filter((r) => r.readVerified !== undefined)
+  const readRatio =
+    computable.length === 0
+      ? null
+      : Number(
+          (
+            computable.filter((r) => r.readVerified === true).length / computable.length
+          ).toFixed(3),
+        )
+  return {
+    checked: audit.checked,
+    passed: evidencePassed(audit),
+    violations: audit.results
+      .filter((r) => r.error !== undefined)
+      .map((r) => ({ file: r.file, line: r.line, lineTotal: r.lineTotal, verified: r.verified, error: r.error })),
+    readVerifiedRatio: readRatio,
+  }
+}

package/src/git-scope.ts

@@ -0,0 +1,129 @@
+/**
+ * src/git-scope.ts — resolve the `changed-only` review scope for the iterate
+ * workflow.
+ *
+ * When `iterate.config.yaml` sets `review.scope: changed-only`, reviewers must
+ * only examine files that changed against `git.target_branch`. This module
+ * resolves that file set deterministically:
+ *
+ *   1. run `git diff --name-only <target_branch> --` in the project root
+ *      (working-tree diff vs the target branch — captures both staged and
+ *      unstaged changes, which is what an iterate round produces);
+ *   2. keep only entries that resolve to an existing file under the project
+ *      root (path-traversal-safe — a hostile diff line must never leak a path
+ *      outside the root);
+ *   3. when the configured scope is `changed-only` but ZERO files changed, the
+ *      plan auto-falls back to `full` (mirrors SKILL.md: "无改动文件时自动
+ *      fallback 为 full").
+ *
+ * The pure math (`parseChangedFiles`, `filterExistingFiles`, `decideScope`) is
+ * separated from the process call (`runGit`) so it is unit-testable without a
+ * git repo.
+ */
+
+import { execFile } from 'node:child_process'
+import { existsSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** A resolved changed-only scope result. */
+export interface GitScopeResult {
+  /** Effective scope for the review plan. */
+  scope: 'full' | 'changed-only'
+  /** Files to review (relative paths). Empty for `full` / fallback. */
+  changedFiles: string[]
+  /** True when the configured scope was changed-only but no changes were found. */
+  fallbackToFull: boolean
+  /** Non-empty when git resolution itself failed (scope falls back to full). */
+  error?: string
+}
+
+/**
+ * Parse `git diff --name-only` stdout into a list of relative paths.
+ * Pure: strips blank lines, trims whitespace, drops quotes (git can quote
+ * paths with special characters).
+ */
+export function parseChangedFiles(stdout: string): string[] {
+  return stdout
+    .split('\n')
+    .map((line) => line.trim().replace(/^"|"$/g, ''))
+    .filter((line) => line.length > 0)
+}
+
+/**
+ * Keep only entries that resolve to an existing regular file under `root`.
+ * Traversal-safe: rejects absolute paths and any relative path that would
+ * escape `root` via `..` (resolved against the root before stat).
+ */
+export function filterExistingFiles(root: string, files: string[]): string[] {
+  const out: string[] = []
+  for (const rel of files) {
+    if (rel.startsWith('/') || rel.includes('\0')) continue
+    const candidate = join(root, rel)
+    if (!candidate.startsWith(root + '/') && candidate !== root) continue
+    try {
+      if (existsSync(candidate) && statSync(candidate).isFile()) out.push(rel)
+    } catch {
+      // Unreadable entry (e.g. a broken symlink) is not a valid review target.
+      continue
+    }
+  }
+  return out
+}
+
+/**
+ * Decide the effective scope from the changed-file set.
+ * changed-only + zero files → fall back to full (SKILL.md auto-fallback).
+ * Pure and deterministic.
+ */
+export function decideScope(changedFiles: string[]): {
+  scope: 'full' | 'changed-only'
+  fallbackToFull: boolean
+} {
+  const hasChanges = changedFiles.length > 0
+  return {
+    scope: hasChanges ? 'changed-only' : 'full',
+    fallbackToFull: !hasChanges,
+  }
+}
+
+/**
+ * Run a git command in `cwd` and return stdout/stderr/exit code.
+ * Uses execFile (no shell), so a model-controlled branch name can never be
+ * interpreted as shell syntax.
+ */
+export function runGit(
+  args: string[],
+  cwd: string,
+): Promise<{ ok: boolean; stdout: string; stderr: string; exitCode: number }> {
+  return new Promise((resolve) => {
+    execFile(
+      'git',
+      args,
+      { cwd, timeout: 30_000, maxBuffer: 10 * 1024 * 1024, env: { ...process.env, PAGER: 'cat' } },
+      (error, stdout, stderr) => {
+        const exitCode = error ? (typeof error.code === 'number' ? error.code : 1) : 0
+        resolve({ ok: exitCode === 0, stdout: stdout ?? '', stderr: stderr ?? '', exitCode })
+      },
+    )
+  })
+}
+
+/**
+ * Resolve the changed-file set for a project.
+ * Any git failure (not a repo, missing target branch, etc.) degrades to a
+ * `full`-scope result with `error` set — the reviewer must never crash the
+ * plan because git is unavailable.
+ */
+export async function resolveChangedFiles(
+  root: string,
+  targetBranch: string,
+): Promise<GitScopeResult> {
+  const { ok, stdout, stderr } = await runGit(['diff', '--name-only', targetBranch, '--'], root)
+  if (!ok) {
+    const reason = stderr.trim() || `git diff --name-only ${targetBranch} failed`
+    return { scope: 'full', changedFiles: [], fallbackToFull: true, error: reason }
+  }
+  const existing = filterExistingFiles(root, parseChangedFiles(stdout))
+  const decided = decideScope(existing)
+  return { scope: decided.scope, changedFiles: existing, fallbackToFull: decided.fallbackToFull }
+}