iterate-plugin 2.7.3 → 2.8.1

package/dist/review-scope.js

@@ -0,0 +1,187 @@
+/**
+ * File-inventory collection, chunking, and coverage scoring for review scope.
+ *
+ * Mirrors `harness/iterate-harness/.../review_scope.py`. The iterate review
+ * loop must force each reviewer subagent to actually open EVERY file in the
+ * scope it is responsible for (not silently skip or assume files). This
+ * module supplies the deterministic building blocks:
+ *
+ * - `collectScopeFiles`: produce the sorted relative-path inventory for a
+ *   review scope (changed-only delta, or a full walk filtered to source files
+ *   and stripped of dependency/build/vendor dirs).
+ * - `chunkFiles`: split a large inventory into stable batches so `full`
+ *   reviews stay bounded; consecutive files from the same directory are kept
+ *   together to avoid splitting a module's review across two reviewers.
+ * - `computeCoverage`: compare a reviewer's self-reported `readFiles` against
+ *   the inventory it was assigned, returning a coverage ratio plus the list of
+ *   files that were not opened. Consumed by meta-review as a
+ *   *prompt-informative* metric (never a hard gate).
+ *
+ * Pure math (chunkFiles / computeCoverage) has no I/O so it unit-tests
+ * cleanly; collectScopeFiles walks the filesystem.
+ */
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/** Relative-scope sentinel for whole-module findings. */
+export const WHOLE_FILE_LINE = 0;
+/** Source extensions a full-scope walk includes. */
+const SOURCE_EXTENSIONS = new Set([
+    '.py', '.pyi', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+    '.go', '.java', '.rs', '.c', '.h', '.cc', '.cpp', '.cs',
+    '.swift', '.kt', '.scala', '.rb', '.php', '.sh', '.bash', '.zsh',
+    '.sql', '.html', '.htm', '.css', '.scss', '.vue', '.svelte',
+]);
+/** Directory names always excluded from a full-scope walk. */
+const IGNORED_DIRS = new Set([
+    '.git', '.hg', '.svn', 'node_modules', '.venv', 'venv', 'env',
+    '__pycache__', '.cache', '.pytest_cache', '.mypy_cache', 'dist',
+    'build', 'out', '.next', '.nuxt', 'coverage', '.tox', '.idea',
+    '.vscode', 'target', '.release', '.dist_tmp',
+]);
+/** Default chunk size for a `full` scope review (files per batch). */
+export const DEFAULT_SCOPE_CHUNK_SIZE = 25;
+/** Coverage ratio at/above which a scope is fully covered. */
+export const COVERAGE_TARGET = 0.95;
+const SEP = '/';
+/**
+ * Canonicalize separators + dot-segments. Leading `..` PATH segments are
+ * PRESERVED (mirrors Python `os.path.normpath`, which never resolves beyond
+ * the root), so callers can still detect path-escaping (`..`) after
+ * normalization — a full `..`-driven traversal must not be silently folded
+ * into a bare filename.
+ */
+function normalizePath(path) {
+    const cleaned = path.replace(/\\/g, SEP);
+    const parts = [];
+    for (const part of cleaned.split(SEP)) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..') {
+            if (parts.length > 0)
+                parts.pop();
+            else
+                parts.push(part); // no root segment to pop — keep the leading '..'
+            continue;
+        }
+        parts.push(part);
+    }
+    return parts.join(SEP);
+}
+function sourceExt(path) {
+    const dot = path.lastIndexOf('.');
+    if (dot < 0)
+        return false;
+    return SOURCE_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+function isIgnoredDir(name) {
+    return IGNORED_DIRS.has(name);
+}
+/** Collect the sorted relative-path inventory for a review scope. */
+export function collectScopeFiles(root, opts) {
+    if (opts.scope === 'changed-only')
+        return collectChanged(opts.changedFiles ?? []);
+    return collectFull(root);
+}
+function collectChanged(changedFiles) {
+    const out = new Set();
+    for (const rel of changedFiles) {
+        if (typeof rel !== 'string' || !rel.trim())
+            continue;
+        if (rel === String(WHOLE_FILE_LINE))
+            continue;
+        const cleaned = normalizePath(rel);
+        if (cleaned.startsWith('..'))
+            continue;
+        if (!sourceExt(cleaned))
+            continue;
+        out.add(cleaned);
+    }
+    return [...out].sort();
+}
+function collectFull(root) {
+    // Deterministic recursive walk built on Node's fs; a code reviewer never
+    // anchors findings to lock files, images, or vendored builds.
+    const out = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const abs = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!isIgnoredDir(entry.name))
+                    walk(abs);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (!sourceExt(entry.name))
+                continue;
+            const rel = abs.startsWith(root + SEP) ? abs.slice(root.length + 1) : abs;
+            out.push(rel.split(SEP).join(SEP));
+        }
+    };
+    walk(root);
+    return out.sort();
+}
+/** Split `files` into stable batches, keeping directory runs together. */
+export function chunkFiles(files, perChunk) {
+    const size = perChunk === undefined || perChunk < 1 ? DEFAULT_SCOPE_CHUNK_SIZE : perChunk;
+    const ordered = [...files].sort();
+    const chunks = [];
+    let current = [];
+    let lastDir;
+    for (const rel of ordered) {
+        const parent = rel.includes(SEP) ? rel.slice(0, rel.lastIndexOf(SEP)) : '.';
+        if (current.length > 0 && lastDir !== undefined && parent !== lastDir) {
+            chunks.push(current);
+            current = [];
+            lastDir = undefined;
+        }
+        current.push(rel);
+        lastDir = parent;
+        if (current.length >= size) {
+            chunks.push(current);
+            current = [];
+            lastDir = undefined;
+        }
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+}
+/** Score self-reported reads against the assigned inventory. */
+export function computeCoverage(assigned, readFiles) {
+    const readNorm = new Set();
+    for (const p of readFiles ?? []) {
+        if (typeof p === 'string' && p)
+            readNorm.add(normalizePath(p));
+    }
+    const assignedSorted = [...assigned].sort();
+    const covered = assignedSorted.filter((rel) => readNorm.has(normalizePath(rel)));
+    const uncovered = assignedSorted.filter((rel) => !readNorm.has(normalizePath(rel)));
+    const rawRatio = assignedSorted.length === 0 ? 1 : covered.length / assignedSorted.length;
+    const ratio = Math.round(rawRatio * 1000) / 1000;
+    return {
+        assigned: assignedSorted,
+        read: [...new Set((readFiles ?? []).filter((p) => typeof p === 'string'))].sort(),
+        covered,
+        uncovered,
+        ratio,
+    };
+}
+/** Serialize a coverage result for the tool-layer JSON wire shape. */
+export function coverageToDict(c) {
+    return {
+        assigned: c.assigned,
+        read: c.read,
+        covered: c.covered,
+        uncovered: c.uncovered,
+        ratio: c.ratio,
+        met: c.ratio >= COVERAGE_TARGET,
+    };
+}

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.');
     }
@@ -290,9 +459,17 @@ export function reviewerTaskPrompt(input) {
     else {
         parts.push('This is round 1 — report every issue you find in this dimension.');
     }
-    parts.push(`Return a JSON object: {"findings": [...]}.`, `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), ' +
+    parts.push('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 (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}.`);
     return parts.join('\n');
 }
@@ -307,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
@@ -121,10 +139,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)
@@ -168,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)
@@ -319,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).
@@ -328,11 +367,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" }\`.