iterate-plugin 2.7.3 → 2.8.1

package/src/review.ts

@@ -24,6 +24,7 @@ import type {
   ReviewReport,
   ReviewRound,
 } from './types.ts'
+import { DEFAULT_SCOPE_CHUNK_SIZE, chunkFiles } from './review-scope.ts'
 
 /** Severity ordering: lower rank = more severe. */
 export const SEVERITY_RANK: Record<ReviewFinding['severity'], number> = {
@@ -312,9 +313,201 @@ export function findingsSchema(): Record<string, unknown> {
           ],
         },
       },
+      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',
+] as const
+
+/** Allowed severity values (mirrors the schema enum). */
+export const SEVERITY_VALUES = ['critical', 'high', 'medium', 'low'] as const
+
+/** String-typed finding fields (type check only, presence handled by REQUIRED). */
+const STRING_FINDING_FIELDS = [
+  'dimension',
+  'file',
+  'summary',
+  'failure_scenario',
+  'suggested_fix',
+] as const
+
+/** One schema violation for a single finding entry. */
+export interface FindingSchemaIssue {
+  /** Index into the findings array; -1 when the whole `findings` is malformed. */
+  index: number
+  /** Field path, e.g. "findings[2].severity". */
+  field: string
+  /** Human-readable reason. */
+  message: string
+}
+
+/**
+ * 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: unknown): FindingSchemaIssue[] {
+  const raw = (input as { findings?: unknown } | null)?.findings ?? input
+  if (!Array.isArray(raw)) {
+    return [
+      {
+        index: -1,
+        field: 'findings',
+        message: 'expected a JSON array of finding objects',
+      },
+    ]
   }
+
+  const issues: FindingSchemaIssue[] = []
+  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 as Record<string, unknown>
+
+    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 as (typeof SEVERITY_VALUES)[number])
+    ) {
+      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
+}
+
+/** Per-round schema validation outcome. */
+export interface RoundSchemaValidation {
+  round: number
+  /** True when every finding in the round conforms to the schema. */
+  valid: boolean
+  issues: FindingSchemaIssue[]
+}
+
+/**
+ * Validate every round's findings against the findings schema.
+ * Round order matches the input `rounds` array.
+ */
+export function validateRoundsSchema(rounds: ReviewRound[]): RoundSchemaValidation[] {
+  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: ReviewRound[],
+  schemaValidation: RoundSchemaValidation[] | null,
+): ReviewRound[] {
+  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): f is ReviewFinding =>
+          Boolean(f) && typeof f === 'object' && !Array.isArray(f),
+      ),
+    }
+  })
 }
 
 /**
@@ -331,6 +524,21 @@ export function reviewerTaskPrompt(input: {
   outputLanguage: string
   /** Atomic fix threshold from config.atomic. */
   maxLines: number
+  /**
+   * Files to review under `changed-only` scope (relative paths, resolved via
+   * git diff against `git.target_branch`). Omitted/empty for `full` scope or
+   * when no changes were detected (auto-fallback to full).
+   */
+  changedFiles?: string[]
+  /**
+   * The exact file inventory this reviewer is RESPONSIBLE for. When provided,
+   * a mandatory COVERAGE RULE is injected: the reviewer must actually open
+   * every listed file with read_file and return a `readFiles` array of what it
+   * opened (the enforcement half of "每个子 agent 必须逐文件读取自己负责的审查
+   * 范围"). Used for the chunked full-scope case; takes precedence over
+   * `changedFiles`.
+   */
+  scopeFiles?: string[]
 }): string {
   const parts: string[] = []
   parts.push(
@@ -338,6 +546,29 @@ export function reviewerTaskPrompt(input: {
     `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.',
@@ -352,10 +583,20 @@ export function reviewerTaskPrompt(input: {
     parts.push('This is round 1 — report every issue you find in this dimension.')
   }
   parts.push(
-    `Return a JSON object: {"findings": [...]}.`,
+    'EVIDENCE RULE (mandatory): read every file you report on with the ' +
+      'read_file tool BEFORE judging it. NEVER report a location you did not ' +
+      '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": [...], "readFiles": [...]}.`,
     `Each finding: dimension (must be "${input.dimension}"), file (relative path), ` +
-      'line (optional integer), severity (critical/high/medium/low), summary (one line), ' +
-      'failure_scenario (how/when it fails, specific evidence), suggested_fix (the concrete fix), ' +
+      '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), ' +
+      'failure_scenario (how/when it fails, backed by the code you actually ' +
+      'read), suggested_fix (the concrete fix), ' +
       `is_atomic (true if the fix is <= ${input.maxLines} lines within a SINGLE file/function, else false).`,
     `Write summaries and details in ${input.outputLanguage}.`,
   )
@@ -372,6 +613,20 @@ export function buildReviewPlan(input: {
   mode: 'normal' | 'dry-run'
   maxReviewRounds: number
   knownIntentional?: KnownIntentional[]
+  /**
+   * Files changed against `git.target_branch` (relative paths), resolved by the
+   * tool when `review.scope` is `changed-only`. When the configured scope is
+   * `changed-only` but no changes are detected, the plan auto-falls back to
+   * `full` (mirrors SKILL.md: "无改动文件时自动 fallback 为 full").
+   */
+  changedFiles?: string[]
+  /**
+   * Pre-collected source inventory for a `full`-scope review. When provided,
+   * it is split into `config.reviewer.scope_chunk_size` batches and every
+   * (dimension × batch) pair gets its own reviewer task owning a bounded,
+   * complete inventory it must open file-by-file.
+   */
+  scopeFiles?: string[]
 }): {
   mode: 'normal' | 'dry-run'
   goal: string
@@ -379,33 +634,73 @@ export function buildReviewPlan(input: {
   dimensions: { id: string; reviewerPrompt: string; findingsSchema: Record<string, unknown> }[]
   maxReviewRounds: number
   knownIntentional: KnownIntentional[]
+  /** Files reviewed under `changed-only` scope (empty for `full` / fallback). */
+  changedFiles: string[]
+  /** True when scope was `changed-only` but no changes were found. */
+  fallbackToFull: boolean
 } {
   // Defensive reads: a malformed config (e.g. `dimensions` as a non-array, or
   // `review`/`atomic` missing) must degrade to sane defaults instead of
   // 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: 'full' | 'changed-only' = 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: (string[] | undefined)[]
+  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: {
+    id: string
+    reviewerPrompt: string
+    findingsSchema: Record<string, unknown>
+  }[] = []
+  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/src/skill-prompt.ts

@@ -14,7 +14,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
@@ -62,18 +62,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
@@ -122,10 +140,12 @@ return {
 
 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 \`finalReport.verdict\` is \`approved\` only when the report passes every check; otherwise \`needs_revision\`. Surface the final report and its verdict as the closing 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.
 - Only a single \`report\` entry may be appended to the decision log; nothing else is written.
 
 ### Normal-mode workflow (autonomous closed loop)
@@ -169,21 +189,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 +358,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).
@@ -329,11 +368,12 @@ Key rules for normal mode:
 - Close with \`iterate_status\` metrics and surface the convergence indicators (fixed count, remaining architectural count, abort reason) in the final summary.
 
 ### Finding schema (for reviewer agents)
-{ "dimension": string, "file": string (relative path), "line": number (optional),
+{ "dimension": string, "file": string (relative path), "line": number (REQUIRED for line-targeted issues — the exact line you READ; use 0 for whole-file/module-level issues),
   "severity": "critical" | "high" | "medium" | "low", "summary": string (one line),
   "failure_scenario": string (how/when it fails), "suggested_fix": string (the concrete fix),
   "is_atomic": boolean (true if fix ≤ max_lines within a single file/function) }
 Atomic = is_atomic true (single file, single function, ≤ config.atomic.max_lines lines change). Architectural = everything else.
+Every finding MUST reference a file the reviewer actually read (read_file) and a real location — never speculate about code that was never inspected. Fabricated paths/lines are poisoned evidence and fail the meta-review evidence gate.
 
 ### Workflow meta
 Always pass \`meta: { name: "iterate", description: "Autonomous iterate loop" }\`.

package/src/tools/fix.ts

@@ -22,6 +22,7 @@ import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { loadEffectiveConfig, resolveProjectRoot } from '../config-loader.ts'
+import { countTouchedMethods } from '../method-scope.ts'
 import { fixBackupPath, fixRegistryPath, fixesDir } from '../paths.ts'
 import { appendDecisionEntry } from './decision-log.ts'
 import type { FileDiffHunk, FixRecord, FixRegistry, ReviewFinding } from '../types.ts'
@@ -228,7 +229,7 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
       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: {
@@ -289,6 +290,7 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
         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' }
@@ -316,6 +318,7 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
         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 {
@@ -325,6 +328,15 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
           }
         }
 
+        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)) {
@@ -349,7 +361,6 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
           return { ok: false, error: `failed to write file: ${String(err)}` }
         }
 
-        const hunks = diffLines(current.content, args.content)
         const record: FixRecord = {
           id,
           timestamp,