iterate-plugin 2.8.0 → 2.8.2

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
@@ -124,6 +142,7 @@ Key rules for dry-run:
 - **NEVER call a fixer / never edit files / never create branches or worktree.** Reviewers read only.
 - **Every reviewer MUST actually read each file it reports on (read_file) BEFORE judging it, and anchor every finding to a real location. Fabricated file paths or invented line numbers are poisoned evidence and fail the run.** Subagents never report on code they didn't inspect.
 - Each round feeds the already-known findings to reviewers so they hunt NEW issues only → that is what drives convergence.
+- **Schema validation & retry**: when \`reviewer.output_schema_validation\` is on (default), \`aggregate\` validates every finding against the findings schema and returns \`schemaValidation\` (per-round {round, valid, issues}). If the just-finished round is invalid, retry its reviewers up to 2 times with the strict-JSON nudge (see the loop above), then re-aggregate. Schema-invalid findings are dropped by \`aggregate\` and must NEVER be fed back as known findings or reported as converged.
 - Stop when a round reports 0 new findings (converged) or maxReviewRounds is reached.
 - The report (with per-round convergence stats + suggested fix priorities) is the deliverable.
 - **Meta-review**: after building the report, audit it with \`iterate_review({operation:"meta-review"})\` for internal consistency (counts, severity buckets, dimension sums, sort order, convergence math). The meta-review ALSO runs the hard code-evidence gate (default on): every finding's file/line is validated against real files on disk, so any fabricated location surfaces as a critical \`EVIDENCE_VIOLATION\` and flips the verdict to \`needs_revision\`. The \`finalReport.verdict\` is \`approved\` only when the report passes every check AND every finding anchors to real, read code; otherwise \`needs_revision\`. Surface the final report and its verdict as the closing deliverable.
@@ -170,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)
@@ -321,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).

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,

package/src/tools/review.ts

@@ -1,10 +1,22 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { loadEffectiveConfig, resolveProjectRoot } from '../config-loader.ts'
-import { buildReviewPlan, buildReviewReport } from '../review.ts'
+import {
+  buildReviewPlan,
+  buildReviewReport,
+  sanitizeRounds,
+  validateRoundsSchema,
+} from '../review.ts'
 import { buildFinalReviewReport, metaReviewReport } from '../meta-review.ts'
 import { evidenceToPlain, verifyFindings } from '../evidence.ts'
+import {
+  collectScopeFiles,
+  computeCoverage,
+  coverageToDict,
+} from '../review-scope.ts'
+import { resolveChangedFiles } from '../git-scope.ts'
 import type { KnownIntentional, ReviewFinding, ReviewReport, ReviewRound } from '../types.ts'
+import type { CoverageResult } from '../review-scope.ts'
 
 /** Default round cap when neither the arg nor config provides one. */
 const DEFAULT_MAX_REVIEW_ROUNDS = 3
@@ -95,7 +107,21 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
             found: { type: 'boolean' },
             plan: { type: 'json' },
             report: { type: 'json' },
+            schemaValidation: {
+              type: 'json',
+              description:
+                'For `aggregate`: per-round schema validation results (round, valid, issues). ' +
+                'Present only when reviewer.output_schema_validation is enabled; the workflow ' +
+                'retries rounds with valid=false (≤2 times) before forwarding findings.',
+            },
             evidence: { type: 'json' },
+            coverage: {
+              type: 'json',
+              description:
+                'For `meta-review`: prompt-informative scope coverage result ' +
+                '(assigned vs self-reported reads). Present only when ' +
+                'reviewer.coverage_validation is enabled and readFiles were supplied.',
+            },
             finalReport: { type: 'json' },
             error: { type: 'string' },
           },
@@ -120,7 +146,23 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
           const maxReviewRounds = args.maxReviewRounds ?? config.max_rounds ?? DEFAULT_MAX_REVIEW_ROUNDS
           const knownIntentional = (config.personalization as { known_intentional?: KnownIntentional[] } | undefined)
             ?.known_intentional
-          const plan = buildReviewPlan({ config, mode, maxReviewRounds, knownIntentional })
+          // changed-only scope: resolve the changed-file set against
+          // git.target_branch before building the plan so reviewers get the
+          // concrete file list (and the plan auto-falls back to full when there
+          // are no changes). git failures degrade to a full-scope plan.
+          let changedFiles: string[] | undefined
+          if (config.review?.scope === 'changed-only') {
+            const gitScope = await resolveChangedFiles(projectRoot, config.git?.target_branch ?? 'main')
+            changedFiles = gitScope.changedFiles
+          }
+          // Full-codebase review: pre-collect the source inventory so
+          // buildReviewPlan can batch it into per-chunk reviewer tasks
+          // (coverage enforcement).
+          let scopeFiles: string[] | undefined
+          if (config.review?.scope === 'full') {
+            scopeFiles = collectScopeFiles(projectRoot, { scope: 'full' })
+          }
+          const plan = buildReviewPlan({ config, mode, maxReviewRounds, knownIntentional, changedFiles, scopeFiles })
           return { operation: 'plan', mode, found: true, plan: plan as unknown as JsonValue }
         }
 
@@ -145,16 +187,34 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
           const maxReviewRounds = args.maxReviewRounds ?? config.max_rounds ?? DEFAULT_MAX_REVIEW_ROUNDS
           const goal = args.goal ?? config.goal ?? ''
           const dimensions = config.dimensions ?? []
+
+          // Output schema validation gate (reviewer.output_schema_validation,
+          // default true): validate every round's findings against the findings
+          // schema, then drop schema-invalid entries before the deterministic
+          // core so malformed reviewer output can never crash dedupe/sort or
+          // leak into fixes. The `schemaValidation` array is surfaced so the
+          // workflow can retry failing rounds (≤2 times) with a strict-JSON
+          // nudge. When disabled, non-object entries are still dropped for
+          // crash-safety.
+          const schemaEnabled = config.reviewer?.output_schema_validation !== false
+          const schemaValidation = schemaEnabled ? validateRoundsSchema(rounds) : null
+          const cleanRounds = sanitizeRounds(rounds, schemaValidation)
+
           const report = buildReviewReport({
             mode,
             goal,
             dimensions,
             maxReviewRounds,
-            rounds,
+            rounds: cleanRounds,
             knownIntentional: args.knownIntentional as KnownIntentional[] | undefined,
             fixedCount: typeof args.fixedCount === 'number' ? args.fixedCount : undefined,
           })
-          return { operation: 'aggregate', mode, report: report as unknown as JsonValue }
+          return {
+            operation: 'aggregate',
+            mode,
+            report: report as unknown as JsonValue,
+            schemaValidation: schemaValidation as unknown as JsonValue | undefined,
+          }
         }
 
         if (args.operation === 'meta-review') {
@@ -173,13 +233,30 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
           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 })
+          // Prompt-informative coverage: compare the reviewer's self-reported
+          // reads against the assigned scope inventory (never flips the
+          // verdict). Disable via config `reviewer.coverage_validation: false`.
+          const coverageEnabled = config.reviewer?.coverage_validation !== false
+          let coverage: CoverageResult | null = null
+          if (coverageEnabled) {
+            const assigned = collectScopeFiles(projectRoot, {
+              scope: config.review?.scope === 'changed-only' ? 'changed-only' : 'full',
+            })
+            const readFiles = Array.isArray((source as unknown as { readFiles?: unknown }).readFiles)
+              ? ((source as unknown as { readFiles?: unknown }).readFiles as string[])
+              : null
+            if (readFiles && readFiles.length > 0) {
+              coverage = computeCoverage(assigned, readFiles)
+            }
+          }
+          const finalReport = buildFinalReviewReport(source, { evidence, coverage })
           return {
             operation: 'meta-review',
             mode,
             found: true,
             report: audit as unknown as JsonValue,
             evidence: evidence ? (evidenceToPlain(evidence) as unknown as JsonValue) : null,
+            coverage: coverage ? (coverageToDict(coverage) as unknown as JsonValue) : null,
             finalReport: finalReport as unknown as JsonValue,
           }
         }

package/src/types.ts

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