iterate-plugin 2.8.0 → 2.8.2

package/dist/review.js

@@ -16,6 +16,7 @@
  * and stop when a round yields 0 new findings or the round cap is reached.
  * All deterministic math lives here so it can be unit-tested.
  */
+import { DEFAULT_SCOPE_CHUNK_SIZE, chunkFiles } from "./review-scope.js";
 /** Severity ordering: lower rank = more severe. */
 export const SEVERITY_RANK = {
     critical: 0,
@@ -269,10 +270,163 @@ export function findingsSchema() {
                     ],
                 },
             },
+            readFiles: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Every file you actually opened with read_file while reviewing your assigned scope. Used to audit coverage; files you never opened count as un-reviewed.',
+            },
         },
-        required: ['findings'],
+        required: ['findings', 'readFiles'],
     };
 }
+// ─── Output schema validation ──────────────────────────────────────────────
+//
+// `config.reviewer.output_schema_validation` (default true) turns on a
+// deterministic schema gate at the `aggregate` boundary: reviewer subagent
+// outputs are parsed as JSON by the orchestrator, but models sometimes return
+// malformed findings (missing fields, wrong types, out-of-range severity).
+// Before any finding reaches the deterministic core (dedupe/sort/report) —
+// which would crash on e.g. a missing `summary` — we validate every entry
+// against the same shape `findingsSchema()` describes and surface the issues
+// so the workflow can retry that round (≤2 times) with a strict-JSON nudge.
+// Schema-invalid findings are dropped from the report; the workflow never
+// forwards them into fixes.
+/** Fields every finding object MUST carry (mirrors findingsSchema().required). */
+export const REQUIRED_FINDING_FIELDS = [
+    'dimension',
+    'file',
+    'severity',
+    'summary',
+    'failure_scenario',
+    'suggested_fix',
+    'is_atomic',
+];
+/** Allowed severity values (mirrors the schema enum). */
+export const SEVERITY_VALUES = ['critical', 'high', 'medium', 'low'];
+/** String-typed finding fields (type check only, presence handled by REQUIRED). */
+const STRING_FINDING_FIELDS = [
+    'dimension',
+    'file',
+    'summary',
+    'failure_scenario',
+    'suggested_fix',
+];
+/**
+ * Validate an arbitrary parsed value against the findings schema shape.
+ * Accepts the `{findings: [...]}` wrapper OR a bare findings array, so callers
+ * can validate either the raw reviewer output object or a round's findings.
+ * Pure and deterministic — never touches the filesystem.
+ */
+export function validateFindingsSchema(input) {
+    const raw = input?.findings ?? input;
+    if (!Array.isArray(raw)) {
+        return [
+            {
+                index: -1,
+                field: 'findings',
+                message: 'expected a JSON array of finding objects',
+            },
+        ];
+    }
+    const issues = [];
+    for (let i = 0; i < raw.length; i++) {
+        const item = raw[i];
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            issues.push({
+                index: i,
+                field: `findings[${i}]`,
+                message: 'expected a finding object',
+            });
+            continue;
+        }
+        const f = item;
+        for (const key of REQUIRED_FINDING_FIELDS) {
+            if (f[key] === undefined || f[key] === null) {
+                issues.push({
+                    index: i,
+                    field: `findings[${i}].${key}`,
+                    message: `required field "${key}" is missing`,
+                });
+            }
+        }
+        for (const key of STRING_FINDING_FIELDS) {
+            if (f[key] !== undefined && f[key] !== null && typeof f[key] !== 'string') {
+                issues.push({
+                    index: i,
+                    field: `findings[${i}].${key}`,
+                    message: `"${key}" must be a string`,
+                });
+            }
+        }
+        if (f.severity !== undefined &&
+            f.severity !== null &&
+            !SEVERITY_VALUES.includes(f.severity)) {
+            issues.push({
+                index: i,
+                field: `findings[${i}].severity`,
+                message: `severity must be one of: ${SEVERITY_VALUES.join(', ')}`,
+            });
+        }
+        if (f.is_atomic !== undefined &&
+            f.is_atomic !== null &&
+            typeof f.is_atomic !== 'boolean') {
+            issues.push({
+                index: i,
+                field: `findings[${i}].is_atomic`,
+                message: 'is_atomic must be a boolean',
+            });
+        }
+        if (f.line !== undefined &&
+            f.line !== null &&
+            (typeof f.line !== 'number' || !Number.isInteger(f.line) || f.line < 0)) {
+            issues.push({
+                index: i,
+                field: `findings[${i}].line`,
+                message: 'line must be a non-negative integer (0 = whole-file)',
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Validate every round's findings against the findings schema.
+ * Round order matches the input `rounds` array.
+ */
+export function validateRoundsSchema(rounds) {
+    return rounds.map((r) => {
+        const issues = validateFindingsSchema(r.findings);
+        return { round: r.round, valid: issues.length === 0, issues };
+    });
+}
+/**
+ * Drop schema-invalid findings before they reach the deterministic core.
+ *
+ * - With a non-null `schemaValidation` (validation enabled): drop every finding
+ *   flagged by a schema issue; a round-level issue (index -1) empties the round.
+ * - With `schemaValidation === null` (validation disabled): still drop entries
+ *   that are not plain objects, which would crash `findingKey`/dedupe.
+ *
+ * Round order and round numbers are preserved so downstream convergence math
+ * keeps working on the sanitized stream.
+ */
+export function sanitizeRounds(rounds, schemaValidation) {
+    return rounds.map((r, i) => {
+        if (schemaValidation) {
+            const issues = schemaValidation[i]?.issues ?? [];
+            if (issues.some((iss) => iss.index === -1))
+                return { round: r.round, findings: [] };
+            const bad = new Set(issues.map((iss) => iss.index));
+            return {
+                round: r.round,
+                findings: r.findings.filter((_, fi) => !bad.has(fi)),
+            };
+        }
+        return {
+            round: r.round,
+            findings: r.findings.filter((f) => Boolean(f) && typeof f === 'object' && !Array.isArray(f)),
+        };
+    });
+}
 /**
  * Build the task prompt for one dimension's reviewer subagent.
  * In dry-run mode, pass `alreadyKnown` (the findings from earlier rounds) so the
@@ -281,6 +435,21 @@ export function findingsSchema() {
 export function reviewerTaskPrompt(input) {
     const parts = [];
     parts.push(`You are the "${input.dimension}" reviewer for the iterate review.`, `Goal: ${input.goal}`, `Scope: ${input.scope === 'full' ? 'entire codebase' : 'changed files only'}.`);
+    if (input.scopeFiles && input.scopeFiles.length > 0) {
+        parts.push('COVERAGE RULE (mandatory): below is the exact file inventory you are ' +
+            'assigned to review. You MUST open EVERY file in this inventory with ' +
+            'the read_file tool before judging it — do not skip, skim-declare, or ' +
+            'assume any file without reading it. Files you did not actually open ' +
+            'are considered un-reviewed and will lower your coverage score. ' +
+            'Return a `readFiles` array listing every file you actually opened.', 'Assigned file inventory:', input.scopeFiles.map((p) => `- ${p}`).join('\n'));
+    }
+    else if (input.scope === 'changed-only' &&
+        input.changedFiles &&
+        input.changedFiles.length > 0) {
+        parts.push('Changed files to review (review ONLY these files; they are the diff against ' +
+            'the target branch). You MUST open EVERY listed file with read_file ' +
+            'before judging it — never skip or assume a file:', input.changedFiles.map((p) => `- ${p}`).join('\n'));
+    }
     if (input.mode === 'dry-run') {
         parts.push('MODE: dry-run / pure review. You MUST NOT modify, create, or delete ANY file. Read-only analysis only.');
     }
@@ -295,7 +464,7 @@ export function reviewerTaskPrompt(input) {
         'actually read — speculation about code you never inspected is a ' +
         'disqualifying failure, and fabricated line numbers are treated as ' +
         'poisoned evidence. Anchor every finding to real code.');
-    parts.push(`Return a JSON object: {"findings": [...]}.`, `Each finding: dimension (must be "${input.dimension}"), file (relative path), ` +
+    parts.push(`Return a JSON object: {"findings": [...], "readFiles": [...]}.`, `Each finding: dimension (must be "${input.dimension}"), file (relative path), ` +
         'line (REQUIRED positive integer — the exact line you READ for an ' +
         'anchored, line-targeted issue; use 0 for whole-file/module-level ' +
         'issues), severity (critical/high/medium/low), summary (one line), ' +
@@ -315,27 +484,58 @@ export function buildReviewPlan(input) {
     // throwing an uncaught TypeError inside the tool's `execute`.
     const language = input.config.language === 'zh' ? 'Chinese (中文)' : 'English';
     const goal = input.config.goal ?? '';
-    const scope = input.config.review?.scope ?? 'full';
+    const configuredScope = input.config.review?.scope ?? 'full';
     const dimensions = Array.isArray(input.config.dimensions) ? input.config.dimensions : [];
     const maxLines = input.config.atomic?.max_lines ?? 20;
+    const changedFiles = Array.isArray(input.changedFiles) ? input.changedFiles : [];
+    // changed-only with zero detected changes → auto-fallback to full scope.
+    const effectiveChangedOnly = configuredScope === 'changed-only' && changedFiles.length > 0;
+    const scope = effectiveChangedOnly ? 'changed-only' : 'full';
+    const fallbackToFull = configuredScope === 'changed-only' && changedFiles.length === 0;
+    // Scope batching (coverage enforcement): changed-only is a single batch
+    // owning the full delta; full scope splits the collected inventory into
+    // per-chunk reviewer tasks when scopeFiles is supplied.
+    const chunkSize = Number(input.config.reviewer?.scope_chunk_size);
+    const perChunk = Number.isFinite(chunkSize) && chunkSize > 0 ? chunkSize : DEFAULT_SCOPE_CHUNK_SIZE;
+    let batches;
+    if (effectiveChangedOnly) {
+        batches = [undefined];
+    }
+    else if (input.scopeFiles && input.scopeFiles.length > 0) {
+        batches = chunkFiles(input.scopeFiles, perChunk).filter((b) => b.length > 0);
+    }
+    else {
+        batches = [undefined];
+    }
+    const dimensionTasks = [];
+    for (const d of dimensions) {
+        batches.forEach((batch, index) => {
+            const dimensionId = batches.length === 1 ? d : `${d}#${index + 1}`;
+            dimensionTasks.push({
+                id: dimensionId,
+                reviewerPrompt: reviewerTaskPrompt({
+                    dimension: d,
+                    goal,
+                    scope,
+                    mode: input.mode,
+                    alreadyKnown: [],
+                    outputLanguage: language,
+                    maxLines,
+                    changedFiles: effectiveChangedOnly ? changedFiles : undefined,
+                    scopeFiles: batch,
+                }),
+                findingsSchema: findingsSchema(),
+            });
+        });
+    }
     return {
         mode: input.mode,
         goal,
         scope,
-        dimensions: dimensions.map((d) => ({
-            id: d,
-            reviewerPrompt: reviewerTaskPrompt({
-                dimension: d,
-                goal,
-                scope,
-                mode: input.mode,
-                alreadyKnown: [],
-                outputLanguage: language,
-                maxLines,
-            }),
-            findingsSchema: findingsSchema(),
-        })),
+        dimensions: dimensionTasks,
         maxReviewRounds: input.maxReviewRounds,
         knownIntentional: input.knownIntentional ?? [],
+        changedFiles: effectiveChangedOnly ? changedFiles : [],
+        fallbackToFull,
     };
 }

package/dist/skill-prompt.js

@@ -13,7 +13,7 @@ You have the iterate plugin installed, which registers these tools:
 - \`iterate_validate\` — run a whitelisted validation command
 - \`iterate_decision_log\` — append to the decision log, or read entries back for review
 - \`iterate_context\` — read SKILL.md / ITERATE.md project context
-- \`iterate_review\` — deterministic review engine: \`plan\` builds the review plan; \`aggregate\` dedupes/merges findings and computes convergence; \`meta-review\` audits a built report for internal consistency (counts, buckets, sorting, convergence math) and returns a final report with an \`approved\` / \`needs_revision\` verdict. Purely computational.
+- \`iterate_review\` — deterministic review engine: \`plan\` builds the review plan (for \`review.scope: changed-only\`, it resolves the git-diff file set against \`git.target_branch\` and auto-falls back to \`full\` when nothing changed); \`aggregate\` dedupes/merges findings, validates every finding against the findings schema when \`reviewer.output_schema_validation\` is on (dropping invalid entries and reporting them via \`schemaValidation\`), and computes convergence; \`meta-review\` audits a built report for internal consistency (counts, buckets, sorting, convergence math) and returns a final report with an \`approved\` / \`needs_revision\` verdict. Purely computational.
 - \`iterate_triage\` — manage "known_intentional" entries in the config (list / apply, with dedupe + backup + rollback)
 - \`iterate_fix\` — apply ONE atomic fix: backs up the file, enforces the atomic max_lines threshold, writes the new content, and records the fix (id + diff summary) in \`.iterate/fixes/registry.json\`
 - \`iterate_diff\` — show the accumulated diff for a fixed file (vs its original backup) or a per-file summary of all fixes
@@ -61,18 +61,36 @@ const rounds = []           // raw per-round findings
 phase('review')
 for (let r = 1; r <= maxRounds; r++) {
   log('round ' + r + ' of ' + maxRounds + ' — finding NEW issues only')
-  const raw = await parallel(dims.map(dim => () => agent(
-    'Review dimension "' + dim + '". Already-known findings (do NOT re-report): ' +
-    JSON.stringify(known) + '\\nReturn the findings JSON object.',
-    { label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }
-  )))
-  const thisRound = { round: r, findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])) }
-  rounds.push(thisRound)
-  // Deterministic aggregate: cross-round dedupe + known_intentional filter + severity sort.
-  const agg = await agent(
-    'Call iterate_review({operation:"aggregate", mode:"dry-run", rounds:' + JSON.stringify(rounds) + ', maxReviewRounds:' + maxRounds + ', knownIntentional:' + JSON.stringify(knownIntentional) + '}) and return the report JSON.',
-    { label: 'review:aggregate:r' + r }
-  )
+  let agg = null
+  let schemaInvalid = false
+  let retries = 0
+  do {
+    // Schema validation retry: on the 2nd+ pass, nudge reviewers toward strict JSON.
+    const nudge = retries > 0
+      ? '\\nSTRICT JSON REQUIRED: your previous output failed schema validation. Return ONLY a JSON object {"findings":[...]} where EVERY finding has dimension, file, line (non-negative integer; 0 = whole-file), severity (critical|high|medium|low), summary, failure_scenario, suggested_fix, is_atomic (boolean).'
+      : ''
+    const raw = await parallel(dims.map(dim => () => agent(
+      'Review dimension "' + dim + '". Already-known findings (do NOT re-report): ' +
+      JSON.stringify(known) + nudge + '\\nReturn the findings JSON object.',
+      { label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }
+    )))
+    const thisRound = { round: r, findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])) }
+    if (rounds.length >= r) rounds[r - 1] = thisRound; else rounds.push(thisRound)
+    // Deterministic aggregate: cross-round dedupe + known_intentional filter + severity sort.
+    agg = await agent(
+      'Call iterate_review({operation:"aggregate", mode:"dry-run", rounds:' + JSON.stringify(rounds) + ', maxReviewRounds:' + maxRounds + ', knownIntentional:' + JSON.stringify(knownIntentional) + '}) and return the report JSON.',
+      { label: 'review:aggregate:r' + r }
+    )
+    // reviewer.output_schema_validation (default on): aggregate returns per-round
+    // schemaValidation; retry the just-finished round (≤2 times) when invalid.
+    schemaInvalid = agg && agg.schemaValidation && agg.schemaValidation.length > 0
+      ? agg.schemaValidation[agg.schemaValidation.length - 1].valid === false
+      : false
+    if (schemaInvalid && retries < 2) {
+      retries += 1
+      log('retry ' + retries + ': round ' + r + ' output failed schema validation — re-running reviewers with strict-JSON emphasis')
+    }
+  } while (schemaInvalid && retries <= 2)
   // Feed the DEDUPED + already-filtered set back (not raw findings) so the known
   // list stays bounded and reviewers never see the same issue twice.
   if (agg && agg.report && Array.isArray(agg.report.findings)) known = agg.report.findings
@@ -123,6 +141,7 @@ Key rules for dry-run:
 - **NEVER call a fixer / never edit files / never create branches or worktree.** Reviewers read only.
 - **Every reviewer MUST actually read each file it reports on (read_file) BEFORE judging it, and anchor every finding to a real location. Fabricated file paths or invented line numbers are poisoned evidence and fail the run.** Subagents never report on code they didn't inspect.
 - Each round feeds the already-known findings to reviewers so they hunt NEW issues only → that is what drives convergence.
+- **Schema validation & retry**: when \`reviewer.output_schema_validation\` is on (default), \`aggregate\` validates every finding against the findings schema and returns \`schemaValidation\` (per-round {round, valid, issues}). If the just-finished round is invalid, retry its reviewers up to 2 times with the strict-JSON nudge (see the loop above), then re-aggregate. Schema-invalid findings are dropped by \`aggregate\` and must NEVER be fed back as known findings or reported as converged.
 - Stop when a round reports 0 new findings (converged) or maxReviewRounds is reached.
 - The report (with per-round convergence stats + suggested fix priorities) is the deliverable.
 - **Meta-review**: after building the report, audit it with \`iterate_review({operation:"meta-review"})\` for internal consistency (counts, severity buckets, dimension sums, sort order, convergence math). The meta-review ALSO runs the hard code-evidence gate (default on): every finding's file/line is validated against real files on disk, so any fabricated location surfaces as a critical \`EVIDENCE_VIOLATION\` and flips the verdict to \`needs_revision\`. The \`finalReport.verdict\` is \`approved\` only when the report passes every check AND every finding anchors to real, read code; otherwise \`needs_revision\`. Surface the final report and its verdict as the closing deliverable.
@@ -169,21 +188,39 @@ let failedCommands = []
 phase('loop')
 for (let r = startRound; r <= maxRounds; r++) {
   log('round ' + r + ' of ' + maxRounds + ' — review current state, fix atomics via iterate_fix, validate')
-  const raw = await parallel(dims.map(dim => () => agent(
-    'Review dimension "' + dim + '" on the CURRENT code state (previous atomic findings are fixed). ' +
-    'Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + '\\nReturn the findings JSON object.',
-    { label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }
-  )))
-  const thisRound = { round: r, findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])) }
-  rounds.push(thisRound)
+  let agg = null
+  let schemaInvalid = false
+  let retries = 0
+  do {
+    // Schema validation retry: on the 2nd+ pass, nudge reviewers toward strict JSON.
+    const nudge = retries > 0
+      ? '\\nSTRICT JSON REQUIRED: your previous output failed schema validation. Return ONLY a JSON object {"findings":[...]} where EVERY finding has dimension, file, line (non-negative integer; 0 = whole-file), severity (critical|high|medium|low), summary, failure_scenario, suggested_fix, is_atomic (boolean).'
+      : ''
+    const raw = await parallel(dims.map(dim => () => agent(
+      'Review dimension "' + dim + '" on the CURRENT code state (previous atomic findings are fixed). ' +
+      'Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + nudge + '\\nReturn the findings JSON object.',
+      { label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }
+    )))
+    const thisRound = { round: r, findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])) }
+    if (rounds.length >= r) rounds[r - 1] = thisRound; else rounds.push(thisRound)
 
-  // Deterministic dedupe / known_intentional filter / severity sort for this round.
-  // \`fixedCount\` is threaded into the report summary so the client dashboard can
-  // show a running "fixes applied" metric for normal mode.
-  const agg = await agent(
-    'Call iterate_review({operation:"aggregate", mode:"normal", rounds:' + JSON.stringify([thisRound]) + ', knownIntentional:' + JSON.stringify(knownIntentional) + ', fixedCount:' + fixedCount + '}) and return the report JSON.',
-    { label: 'review:aggregate:r' + r }
-  )
+    // Deterministic dedupe / known_intentional filter / severity sort for this round.
+    // \`fixedCount\` is threaded into the report summary so the client dashboard can
+    // show a running "fixes applied" metric for normal mode.
+    agg = await agent(
+      'Call iterate_review({operation:"aggregate", mode:"normal", rounds:' + JSON.stringify([thisRound]) + ', knownIntentional:' + JSON.stringify(knownIntentional) + ', fixedCount:' + fixedCount + '}) and return the report JSON.',
+      { label: 'review:aggregate:r' + r }
+    )
+    // reviewer.output_schema_validation (default on): aggregate returns per-round
+    // schemaValidation; retry the just-finished round (≤2 times) when invalid.
+    schemaInvalid = agg && agg.schemaValidation && agg.schemaValidation.length > 0
+      ? agg.schemaValidation[agg.schemaValidation.length - 1].valid === false
+      : false
+    if (schemaInvalid && retries < 2) {
+      retries += 1
+      log('retry ' + retries + ': round ' + r + ' output failed schema validation — re-running reviewers with strict-JSON emphasis')
+    }
+  } while (schemaInvalid && retries <= 2)
   const findings = (agg && agg.report && agg.report.findings) ? agg.report.findings : thisRound.findings
   const atomic = findings.filter(f => f.is_atomic === true)
   const remaining = findings.filter(f => f.is_atomic !== true)
@@ -320,6 +357,7 @@ return {
 Key rules for normal mode:
 - Fixers are the ONLY agents allowed to write files, and they must go through \`iterate_fix\` — never edit files directly. That is what gives every change a backup, a diff, and a rollback path. Reviewers read only. Architectural findings are reported, never auto-fixed.
 - Aggregate the current round deterministically (\`report.findings\`) before fixing, so fixes act on deduped/filtered/sorted findings.
+- **Schema validation & retry**: when \`reviewer.output_schema_validation\` is on (default), retry the round's reviewers up to 2 times when \`aggregate\` reports \`schemaValidation\` valid=false for it, then re-aggregate. Never forward schema-invalid findings into \`iterate_fix\`.
 - Apply atomic fixes **per file**: one fixer agent handles all findings for a given file serially (so the same file is never edited concurrently); different files are fixed in parallel.
 - **Resume**: load the checkpoint first; if a previous run left one, continue from \`checkpoint.round + 1\` (its \`fixedCount\` and deduped \`findings\` are carried forward).
 - **Validate after every round** of fixes; on ANY validation failure, roll back the round's fixes via \`iterate_rollback\` and stop (the checkpoint is left in place so the run can be resumed).

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,8 +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;
 /**
@@ -83,7 +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' },
                 },
@@ -106,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') {
@@ -128,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;
@@ -155,13 +201,30 @@ export function registerReviewTool(ctx) {
                 const evidenceEnabled = config.reviewer?.evidence_validation !== false;
                 const findings = Array.isArray(source.findings) ? source.findings : [];
                 const evidence = evidenceEnabled ? verifyFindings(projectRoot, findings) : null;
-                const finalReport = buildFinalReviewReport(source, { evidence });
+                // 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,
                 };
             }