iterate-plugin 2.7.2 → 2.8.0

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>
 }