iterate-plugin 2.7.3 → 2.8.0

package/README.md

@@ -229,6 +229,19 @@ All tests pass:
 - **212 unit tests green**, type-check clean
 - Coverage: dedupe, filter, sort, multi-round convergence, meta-review audit, path safety, timeout clamping, config read/write + rollback, triage merge, diff computation, checkpoint validation, fix registry, history read + filter, prune cleanup report + dry-run semantics, UI pure functions (select-all key, runtime status guide).
 
+## ⚠️ Disclaimer
+
+This project is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement.
+
+**Automated code review and fixing carries inherent risk.** All changes produced in normal mode are generated by AI models and may introduce bugs, regressions, or unintended behavior. Before merging, you should:
+
+- Review every diff before applying it to your main branch or pushing.
+- Make sure your project is under git control and can be rolled back (`git restore`, revert, or restore from backup).
+- Run your project's own test suite and build checks after each round of fixes.
+- Never run this on secrets, credentials, `.env`, or files that must not be modified — configure `protected_paths` accordingly.
+
+Users are solely responsible for the code that is generated, modified, or committed as a result of using this project. By using it, you acknowledge that neither the maintainers nor contributors are liable for any loss, damage, or legal consequences arising from its use.
+
 ## License
 
 MIT

package/README.zh-CN.md

@@ -229,6 +229,19 @@ npm test
 - **212 个单元测试全绿**，类型检查通过
 - 覆盖：去重、过滤、排序、多轮收敛、meta-review 审计、路径安全、超时钳制、配置读写与回滚、triage 合并、diff 计算、checkpoint 校验、修复注册表、历史读取与过滤、prune 清理报告与 dry-run 语义、UI 纯函数（select-all 键、运行时状态指引）等
 
+## ⚠️ 免责声明
+
+本项目按「现状」（AS IS）提供，不附带任何明示或暗示的担保，包括但不限于对适销性、特定用途适用性及不侵权性的担保。
+
+**自动化的代码审查与修复存在固有风险。** normal 模式下产生的改动均由 AI 模型生成，可能引入缺陷、回归或非预期行为。在合并改动前，你应当：
+
+- 在应用到主分支或推送前，逐条 review 每一处 diff。
+- 确保项目处于 git 版本控制之下，并可随时回滚（`git restore`、revert 或从备份恢复）。
+- 在每轮修复后运行项目自身的测试与构建检查。
+- 切勿在密钥、凭证、`.env` 或任何不允许修改的文件上运行本项目；请在配置中设置 `protected_paths` 予以保护。
+
+使用者需为本项目使用过程中所产生、修改或提交的代码负全部责任。使用本项目即表示你同意：维护者与贡献者不对因使用本项目而导致的任何损失、损害或法律后果承担责任。
+
 ## License
 
 MIT

package/dist/config-loader.js

@@ -48,7 +48,7 @@ export function defaultConfig() {
             auto_merge: false,
         },
         validation: { command_whitelist: [], commands: {} },
-        reviewer: { output_schema_validation: true },
+        reviewer: { output_schema_validation: true, evidence_validation: true },
     };
 }
 /**

package/dist/evidence.js

@@ -0,0 +1,143 @@
+/**
+ * Deterministic code-evidence verification for review findings.
+ *
+ * Mirror of `iterate_harness/iterate/evidence.py` for the iterate-plugin.
+ *
+ * The iterate review loop requires that reviewer subagent findings ANCHOR to
+ * real code instead of speculating. This module enforces it:
+ *
+ * - a finding's `file` must resolve to an existing file under the project root
+ *   (traversal-safe), otherwise evidence is poisoned (`file_not_found`);
+ * - a finding with an explicit line must reference a line that actually exists
+ *   in that file (`line_out_of_range`);
+ * - a whole-file finding (line 0 / undefined) must still reference an existing
+ *   file, so even structural findings cannot point at nothing;
+ * - `readVerified` is a best-effort, NON-gating hint: the plugin's reviewers are
+ *   subagents whose reads are not aggregated here, so it is only set when a
+ *   read set is explicitly provided and never fails the audit.
+ *
+ * Gate rule (user preference): ANY localizable finding with poisoned evidence
+ * flips the whole audit to `passed: false`, so the meta-review forces revision.
+ *
+ * The pure math (`countLines`, `verifyLineBounds`) is separated from the
+ * filesystem half (`verifyFinding`) to stay unit-testable without touching disk.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+/** Sentinel for whole-file findings (line 0 or omitted means the whole file). */
+export const WHOLE_FILE_LINE = 0;
+/** Number of physical lines in `text`. A trailing newline does not add a line. */
+export function countLines(text) {
+    if (text === '')
+        return 0;
+    const parts = text.split(/\r\n|\r|\n/);
+    // A trailing newline leaves an empty final element that is NOT a line
+    // (mirrors Python `str.splitlines()` used by the harness).
+    if (parts[parts.length - 1] === '')
+        return parts.length - 1;
+    return parts.length;
+}
+/** Resolve `root/rel` and reject any path escaping `root` (returns null). */
+export function resolveWithin(root, rel) {
+    const resolved = resolve(root, rel);
+    const rootResolved = resolve(root);
+    if (resolved === rootResolved)
+        return resolved;
+    const prefix = rootResolved.endsWith(sep) ? rootResolved : rootResolved + sep;
+    if (!resolved.startsWith(prefix))
+        return null;
+    return resolved;
+}
+/**
+ * Pure check that `line` (if anchored) exists in `text`.
+ * Whole-file findings (undefined/0) are always bounds-valid.
+ */
+export function verifyLineBounds(line, text) {
+    const lineTotal = countLines(text);
+    if (line === undefined || line === null || line === WHOLE_FILE_LINE) {
+        return { inBounds: true, lineTotal };
+    }
+    if (line < 1)
+        return { inBounds: false, lineTotal };
+    return { inBounds: line <= lineTotal, lineTotal };
+}
+/** Verify a single finding's location against the real filesystem. */
+export function verifyFinding(root, input, opts = {}) {
+    const relFile = input.file ?? '';
+    const line = typeof input.line === 'number' ? input.line : null;
+    const resolved = resolveWithin(root, relFile);
+    if (resolved === null || !existsSync(resolved)) {
+        return {
+            file: relFile,
+            line,
+            lineTotal: null,
+            resolvedPath: resolved,
+            verified: false,
+            error: 'file_not_found',
+        };
+    }
+    let text;
+    try {
+        text = readFileSync(resolved, 'utf-8');
+    }
+    catch {
+        return {
+            file: relFile,
+            line,
+            lineTotal: null,
+            resolvedPath: resolved,
+            verified: false,
+            error: 'file_not_found',
+        };
+    }
+    const { inBounds, lineTotal } = verifyLineBounds(line, text);
+    if (!inBounds) {
+        return {
+            file: relFile,
+            line,
+            lineTotal,
+            resolvedPath: resolved,
+            verified: false,
+            error: 'line_out_of_range',
+        };
+    }
+    const outcome = {
+        file: relFile,
+        line,
+        lineTotal,
+        resolvedPath: resolved,
+        verified: true,
+    };
+    if (opts.readSet !== undefined) {
+        outcome.readVerified = opts.readSet.has(resolved);
+    }
+    return outcome;
+}
+/** Attest every finding in a list. */
+export function verifyFindings(root, findings, opts = {}) {
+    const results = findings.map((f) => verifyFinding(root, f, opts));
+    return { checked: results.length, results };
+}
+/** `passed` is true only when no real existence failure exists (read is a hint). */
+export function evidencePassed(audit) {
+    return audit.results.every((r) => r.error === undefined);
+}
+/** Violating (non-grounded) results. */
+export function evidenceViolations(audit) {
+    return audit.results.filter((r) => r.error !== undefined);
+}
+/** Serialize an audit for tool payloads (pure). */
+export function evidenceToPlain(audit) {
+    const computable = audit.results.filter((r) => r.readVerified !== undefined);
+    const readRatio = computable.length === 0
+        ? null
+        : Number((computable.filter((r) => r.readVerified === true).length / computable.length).toFixed(3));
+    return {
+        checked: audit.checked,
+        passed: evidencePassed(audit),
+        violations: audit.results
+            .filter((r) => r.error !== undefined)
+            .map((r) => ({ file: r.file, line: r.line, lineTotal: r.lineTotal, verified: r.verified, error: r.error })),
+        readVerifiedRatio: readRatio,
+    };
+}

package/dist/meta-review.js

@@ -157,9 +157,37 @@ export function metaReviewReport(report) {
 /**
  * Build the final review report: pair the source report with its meta-review
  * verdict and a rolled-up summary. Pure and deterministic.
+ *
+ * `evidence` (an EvidenceAudit produced against the real repo) is the hard
+ * code-evidence gate: every finding whose file/line does not resolve to
+ * existing code is emitted as a critical EVIDENCE_VIOLATION and flips the
+ * verdict to `needs_revision`. The audit itself reads the filesystem; this
+ * function only folds the (pure, precomputed) result in.
  */
-export function buildFinalReviewReport(report) {
+export function buildFinalReviewReport(report, opts = {}) {
     const meta = metaReviewReport(report);
+    const evidence = opts.evidence ?? null;
+    if (evidence !== null) {
+        meta.checksRun += 1;
+        if (evidence.results.some((r) => r.error !== undefined)) {
+            for (const violation of evidence.results) {
+                if (violation.error === undefined)
+                    continue;
+                const detail = violation.error === 'line_out_of_range'
+                    ? `${violation.line} is beyond this file's ${violation.lineTotal} lines`
+                    : `${violation.file} does not exist at all (verifiable read required)`;
+                meta.issues.push({
+                    code: 'EVIDENCE_VIOLATION',
+                    severity: 'critical',
+                    summary: `Finding references non-existent code: ${violation.file}` +
+                        (violation.line ? `:${violation.line}` : ''),
+                    detail: detail + '. Review results must anchor to real, read code.',
+                });
+            }
+            meta.passed = false;
+            meta.verdict = 'revise';
+        }
+    }
     const summary = report?.summary ?? {};
     const verdict = meta.passed ? 'approved' : 'needs_revision';
     return {

package/dist/review.js

@@ -290,9 +290,17 @@ export function reviewerTaskPrompt(input) {
     else {
         parts.push('This is round 1 — report every issue you find in this dimension.');
     }
+    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": [...]}.`, `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}.`);
     return parts.join('\n');
 }

package/dist/skill-prompt.js

@@ -121,10 +121,11 @@ 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.
 - 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)
@@ -328,11 +329,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/dist/tools/review.js

@@ -2,6 +2,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import { loadEffectiveConfig, resolveProjectRoot } from "../config-loader.js";
 import { buildReviewPlan, buildReviewReport } from "../review.js";
 import { buildFinalReviewReport, metaReviewReport } from "../meta-review.js";
+import { evidenceToPlain, verifyFindings } from "../evidence.js";
 /** Default round cap when neither the arg nor config provides one. */
 const DEFAULT_MAX_REVIEW_ROUNDS = 3;
 /**
@@ -82,6 +83,7 @@ export function registerReviewTool(ctx) {
                     found: { type: 'boolean' },
                     plan: { type: 'json' },
                     report: { type: 'json' },
+                    evidence: { type: 'json' },
                     finalReport: { type: 'json' },
                     error: { type: 'string' },
                 },
@@ -147,12 +149,19 @@ export function registerReviewTool(ctx) {
                     };
                 }
                 const audit = metaReviewReport(source);
-                const finalReport = buildFinalReviewReport(source);
+                // Hard code-evidence gate (default on): every finding's file/line is
+                // validated against real files on disk before folding into the final
+                // verdict. Disable via config `reviewer.evidence_validation: false`.
+                const evidenceEnabled = config.reviewer?.evidence_validation !== false;
+                const findings = Array.isArray(source.findings) ? source.findings : [];
+                const evidence = evidenceEnabled ? verifyFindings(projectRoot, findings) : null;
+                const finalReport = buildFinalReviewReport(source, { evidence });
                 return {
                     operation: 'meta-review',
                     mode,
                     found: true,
                     report: audit,
+                    evidence: evidence ? evidenceToPlain(evidence) : null,
                     finalReport: finalReport,
                 };
             }

package/package.json

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

package/src/config-loader.ts

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

package/src/evidence.ts

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

package/src/meta-review.ts

@@ -15,6 +15,7 @@
  */
 
 import type { ReviewFinding, ReviewReport } from './types.ts'
+import type { EvidenceAudit } from './evidence.ts'
 import { sortFindings } from './review.ts'
 
 /** A single defect found while auditing a review report. */
@@ -278,9 +279,41 @@ export function metaReviewReport(report: ReviewReport): MetaReviewResult {
 /**
  * Build the final review report: pair the source report with its meta-review
  * verdict and a rolled-up summary. Pure and deterministic.
+ *
+ * `evidence` (an EvidenceAudit produced against the real repo) is the hard
+ * code-evidence gate: every finding whose file/line does not resolve to
+ * existing code is emitted as a critical EVIDENCE_VIOLATION and flips the
+ * verdict to `needs_revision`. The audit itself reads the filesystem; this
+ * function only folds the (pure, precomputed) result in.
  */
-export function buildFinalReviewReport(report: ReviewReport): FinalReviewReport {
+export function buildFinalReviewReport(
+  report: ReviewReport,
+  opts: { evidence?: EvidenceAudit | null } = {},
+): FinalReviewReport {
   const meta = metaReviewReport(report)
+  const evidence = opts.evidence ?? null
+  if (evidence !== null) {
+    meta.checksRun += 1
+    if (evidence.results.some((r) => r.error !== undefined)) {
+      for (const violation of evidence.results) {
+        if (violation.error === undefined) continue
+        const detail =
+          violation.error === 'line_out_of_range'
+            ? `${violation.line} is beyond this file's ${violation.lineTotal} lines`
+            : `${violation.file} does not exist at all (verifiable read required)`
+        meta.issues.push({
+          code: 'EVIDENCE_VIOLATION',
+          severity: 'critical',
+          summary:
+            `Finding references non-existent code: ${violation.file}` +
+            (violation.line ? `:${violation.line}` : ''),
+          detail: detail + '. Review results must anchor to real, read code.',
+        })
+      }
+      meta.passed = false
+      meta.verdict = 'revise'
+    }
+  }
   const summary = report?.summary ?? {}
   const verdict: FinalReviewVerdict = meta.passed ? 'approved' : 'needs_revision'
   return {

package/src/review.ts

@@ -351,11 +351,21 @@ export function reviewerTaskPrompt(input: {
   } else {
     parts.push('This is round 1 — report every issue you find in this dimension.')
   }
+  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": [...]}.`,
     `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}.`,
   )

package/src/skill-prompt.ts

@@ -122,10 +122,11 @@ 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.
 - 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)
@@ -329,11 +330,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/review.ts

@@ -3,6 +3,7 @@ import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { loadEffectiveConfig, resolveProjectRoot } from '../config-loader.ts'
 import { buildReviewPlan, buildReviewReport } from '../review.ts'
 import { buildFinalReviewReport, metaReviewReport } from '../meta-review.ts'
+import { evidenceToPlain, verifyFindings } from '../evidence.ts'
 import type { KnownIntentional, ReviewFinding, ReviewReport, ReviewRound } from '../types.ts'
 
 /** Default round cap when neither the arg nor config provides one. */
@@ -94,6 +95,7 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
             found: { type: 'boolean' },
             plan: { type: 'json' },
             report: { type: 'json' },
+            evidence: { type: 'json' },
             finalReport: { type: 'json' },
             error: { type: 'string' },
           },
@@ -165,12 +167,19 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
             }
           }
           const audit = metaReviewReport(source)
-          const finalReport = buildFinalReviewReport(source)
+          // Hard code-evidence gate (default on): every finding's file/line is
+          // validated against real files on disk before folding into the final
+          // verdict. Disable via config `reviewer.evidence_validation: false`.
+          const evidenceEnabled = config.reviewer?.evidence_validation !== false
+          const findings: ReviewFinding[] = Array.isArray(source.findings) ? source.findings : []
+          const evidence = evidenceEnabled ? verifyFindings(projectRoot, findings) : null
+          const finalReport = buildFinalReviewReport(source, { evidence })
           return {
             operation: 'meta-review',
             mode,
             found: true,
             report: audit as unknown as JsonValue,
+            evidence: evidence ? (evidenceToPlain(evidence) as unknown as JsonValue) : null,
             finalReport: finalReport as unknown as JsonValue,
           }
         }

package/src/types.ts

@@ -16,7 +16,7 @@ export interface IterateConfig {
     command_whitelist: string[]
     commands: Record<string, string[]>
   }
-  reviewer: { output_schema_validation: boolean }
+  reviewer: { output_schema_validation: boolean; evidence_validation: boolean }
   onboarding?: Record<string, unknown>
   personalization?: Record<string, unknown>
 }