iterate-plugin 2.6.0 → 2.7.0

package/dist/review.js

@@ -0,0 +1,328 @@
+/**
+ * Deterministic review engine for the iterate review loop (dry-run and normal).
+ *
+ * This module contains NO I/O and NO agent spawning — it is the pure,
+ * testable core of the multi-round convergence loop:
+ *
+ *   1. dedupe findings across rounds (file + dimension + normalized summary)
+ *   2. filter out `known_intentional` entries from personalization
+ *   3. sort by severity (critical > high > medium > low)
+ *   4. compute multi-round convergence stats ("纯反复审查" 收敛统计)
+ *   5. assemble the ReviewReport
+ *   6. build reviewer task prompts + structured-output schema for subagents
+ *
+ * The workflow script (see skill-prompt.ts) does the orchestration:
+ * spawn parallel reviewers, feed back already-known findings each round,
+ * 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.
+ */
+/** Severity ordering: lower rank = more severe. */
+export const SEVERITY_RANK = {
+    critical: 0,
+    high: 1,
+    medium: 2,
+    low: 3,
+};
+/** Sort findings by severity (most severe first), then by file path. */
+export function sortFindings(findings) {
+    return [...findings].sort((a, b) => {
+        // Guard against an out-of-spec severity string (e.g. from a model that
+        // bypassed the schema): treat it as the least severe so NaN never enters
+        // the comparator and ordering stays deterministic.
+        const rankA = SEVERITY_RANK[a.severity] ?? SEVERITY_RANK.low;
+        const rankB = SEVERITY_RANK[b.severity] ?? SEVERITY_RANK.low;
+        const bySeverity = rankA - rankB;
+        if (bySeverity !== 0)
+            return bySeverity;
+        const byFile = a.file.localeCompare(b.file);
+        if (byFile !== 0)
+            return byFile;
+        return (a.line ?? 0) - (b.line ?? 0);
+    });
+}
+/** Normalize a summary so near-identical duplicates collapse to one key. */
+export function normalizeSummary(summary) {
+    return summary
+        .trim()
+        .toLowerCase()
+        .replace(/[\s\n\t]+/g, ' ');
+}
+/** Dedupe key: same file + same dimension + similar summary. */
+export function findingKey(f) {
+    return `${f.file}|${f.dimension}|${normalizeSummary(f.summary)}`;
+}
+/**
+ * Remove duplicate findings within a list.
+ * Keeps the first occurrence of each dedupe key.
+ */
+export function dedupeFindings(findings) {
+    const seen = new Set();
+    const out = [];
+    for (const f of findings) {
+        const key = findingKey(f);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(f);
+    }
+    return out;
+}
+/**
+ * Filter out findings that match a `known_intentional` entry.
+ * Match rule (mirrors SKILL.md Phase 1 FILTER):
+ *  - same `file` AND same `dimension`, AND
+ *  - entry `line` is 0/undefined (whole file) OR equals the finding's line.
+ */
+export function filterKnownIntentional(findings, known) {
+    if (!known || known.length === 0)
+        return findings;
+    return findings.filter((f) => {
+        const matched = known.some((k) => {
+            const sameFile = k.file === f.file;
+            const sameDim = k.dimension === f.dimension;
+            if (!sameFile || !sameDim)
+                return false;
+            const wholeFile = k.line === undefined || k.line === 0;
+            if (wholeFile)
+                return true;
+            return k.line === f.line;
+        });
+        return !matched;
+    });
+}
+/**
+ * Merge per-round findings into one globally-deduped stream while tracking
+ * which round first surfaced each finding. This is the deterministic core of
+ * "反复多轮审查直至收敛":
+ *  - `findingsByRound` = number of GLOBALLY new findings first seen in round r,
+ *    indexed by the actual `round` number (round r → index r-1). The array is
+ *    sized to the highest round number encountered, so non-contiguous round
+ *    numbers (e.g. a resumed run that starts at round 5, or a caller that only
+ *    passes `[{round: 3}]`) still yield correct counts instead of being
+ *    collapsed onto wrong indices.
+ *  - `converged` = the last executed round produced 0 new findings
+ *  - `stoppedReason` = 'converged' | 'max_rounds_reached'
+ */
+export function aggregateRounds(rounds, maxReviewRounds) {
+    const seen = new Set();
+    const firstRoundByKey = new Map();
+    const merged = [];
+    // Guard: round numbers are expected to be positive integers. Skip malformed
+    // entries defensively rather than letting `firstRoundByKey` key on NaN/0.
+    let maxRound = 0;
+    for (const round of rounds) {
+        if (typeof round.round !== 'number' || !Number.isInteger(round.round) || round.round < 1)
+            continue;
+        if (round.round > maxRound)
+            maxRound = round.round;
+        for (const f of round.findings) {
+            const key = findingKey(f);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            firstRoundByKey.set(key, round.round);
+            merged.push(f);
+        }
+    }
+    const findingsByRound = [];
+    for (let r = 1; r <= maxRound; r++) {
+        let count = 0;
+        for (const key of firstRoundByKey.keys()) {
+            if (firstRoundByKey.get(key) === r)
+                count++;
+        }
+        findingsByRound.push(count);
+    }
+    return { findings: dedupeFindings(merged), findingsByRound, firstRoundByKey };
+}
+/**
+ * Compute convergence statistics for a dry-run review.
+ */
+export function computeConvergence(rounds, maxReviewRounds) {
+    const { findingsByRound } = aggregateRounds(rounds, maxReviewRounds);
+    const totalRounds = rounds.length;
+    // `findingsByRound` is indexed by the actual round number (round r → index
+    // r-1), so convergence must read the LAST PRESENT round's count using its
+    // reported round number — not `totalRounds - 1`, which is only valid for
+    // contiguous 1..N round numbers.
+    const lastRound = totalRounds > 0 ? rounds[totalRounds - 1].round : 0;
+    const lastRoundCount = lastRound > 0 ? (findingsByRound[lastRound - 1] ?? 0) : 0;
+    const converged = totalRounds > 0 && lastRoundCount === 0;
+    return {
+        totalRounds,
+        findingsByRound,
+        converged,
+        stoppedReason: totalRounds === 0
+            ? 'max_rounds_reached'
+            : converged
+                ? 'converged'
+                : 'max_rounds_reached',
+    };
+}
+/** Build a severity/summary breakdown map for the report. */
+function summarize(findings) {
+    const summary = {
+        totalFindings: findings.length,
+        critical: 0,
+        high: 0,
+        medium: 0,
+        low: 0,
+        byDimension: {},
+    };
+    for (const f of findings) {
+        if (f.severity === 'critical')
+            summary.critical++;
+        else if (f.severity === 'high')
+            summary.high++;
+        else if (f.severity === 'medium')
+            summary.medium++;
+        else
+            summary.low++;
+        summary.byDimension[f.dimension] = (summary.byDimension[f.dimension] ?? 0) + 1;
+    }
+    return summary;
+}
+/**
+ * Assemble the final ReviewReport from raw per-round findings.
+ * Applies known_intentional filtering, cross-round dedupe, severity sort,
+ * and convergence stats in one deterministic pass. Shared by dry-run (pure
+ * review) and normal (autonomous loop) modes — the mode only records intent;
+ * the math is identical.
+ */
+export function buildReviewReport(input) {
+    // 1. Filter known-intentional per round (before cross-round dedupe).
+    const filteredRounds = input.rounds.map((r) => ({
+        round: r.round,
+        findings: filterKnownIntentional(r.findings, input.knownIntentional),
+    }));
+    // 2. Cross-round dedupe + per-round "first seen" tracking.
+    const { findings, findingsByRound } = aggregateRounds(filteredRounds, input.maxReviewRounds);
+    // 3. Severity sort the global result.
+    const sorted = sortFindings(findings);
+    // 4. Convergence. Must be identical to `computeConvergence`: `findingsByRound`
+    //    is indexed by the actual round number (round r → index r-1) and sized to
+    //    the highest round, so convergence reads the LAST PRESENT round's count
+    //    using its reported round number — NOT `filteredRounds.length - 1`, which
+    //    is only valid for contiguous 1..N round numbers (resumed iterations and
+    //    non-contiguous round sets would otherwise read the wrong count).
+    const lastRound = filteredRounds.length > 0 ? filteredRounds[filteredRounds.length - 1].round : 0;
+    const lastRoundCount = lastRound > 0 ? (findingsByRound[lastRound - 1] ?? 0) : 0;
+    const converged = filteredRounds.length > 0 && lastRoundCount === 0;
+    return {
+        mode: input.mode,
+        goal: input.goal,
+        dimensions: input.dimensions,
+        maxReviewRounds: input.maxReviewRounds,
+        rounds: filteredRounds,
+        findings: sorted,
+        convergence: {
+            totalRounds: filteredRounds.length,
+            findingsByRound,
+            converged,
+            stoppedReason: filteredRounds.length === 0
+                ? 'max_rounds_reached'
+                : converged
+                    ? 'converged'
+                    : 'max_rounds_reached',
+        },
+        summary: summarize(sorted),
+    };
+}
+/**
+ * JSON Schema for reviewer subagent structured output.
+ * Object-rooted (dsh `agent` opts.schema requires object-rooted schemas with
+ * only type/properties/required/additionalProperties/items/enum/const/oneOf).
+ */
+export function findingsSchema() {
+    return {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            findings: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        dimension: { type: 'string' },
+                        file: { type: 'string' },
+                        line: { type: 'integer' },
+                        severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] },
+                        summary: { type: 'string' },
+                        failure_scenario: { type: 'string' },
+                        suggested_fix: { type: 'string' },
+                        is_atomic: { type: 'boolean' },
+                    },
+                    required: [
+                        'dimension',
+                        'file',
+                        'severity',
+                        'summary',
+                        'failure_scenario',
+                        'suggested_fix',
+                        'is_atomic',
+                    ],
+                },
+            },
+        },
+        required: ['findings'],
+    };
+}
+/**
+ * Build the task prompt for one dimension's reviewer subagent.
+ * In dry-run mode, pass `alreadyKnown` (the findings from earlier rounds) so the
+ * reviewer hunts for NEW issues only — that is what makes "反复审查" converge.
+ */
+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.mode === 'dry-run') {
+        parts.push('MODE: dry-run / pure review. You MUST NOT modify, create, or delete ANY file. Read-only analysis only.');
+    }
+    if (input.alreadyKnown && input.alreadyKnown.length > 0) {
+        parts.push('Already-known findings from earlier rounds (do NOT re-report these; find NEW issues only):', JSON.stringify(input.alreadyKnown, null, 2));
+    }
+    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), ' +
+        `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');
+}
+/**
+ * Build a review plan: how many rounds, which dimensions, and the reviewer
+ * prompt template for each dimension. Used by the `iterate_review` tool's
+ * `plan` operation to give the orchestrator a canonical spec.
+ */
+export function buildReviewPlan(input) {
+    // Defensive reads: a malformed config (e.g. `dimensions` as a non-array, or
+    // `review`/`atomic` missing) must degrade to sane defaults instead of
+    // throwing an uncaught TypeError inside the tool's `execute`.
+    const language = input.config.language === 'zh' ? 'Chinese (中文)' : 'English';
+    const goal = input.config.goal ?? '';
+    const scope = input.config.review?.scope ?? 'full';
+    const dimensions = Array.isArray(input.config.dimensions) ? input.config.dimensions : [];
+    const maxLines = input.config.atomic?.max_lines ?? 20;
+    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(),
+        })),
+        maxReviewRounds: input.maxReviewRounds,
+        knownIntentional: input.knownIntentional ?? [],
+    };
+}

package/dist/skill-prompt.js

@@ -0,0 +1,337 @@
+/**
+ * The iterate skill prompt injected into the system prompt.
+ *
+ * This teaches the model how to write a correct `workflow` script that
+ * performs the iterate autonomous closed-loop (or dry-run pure review),
+ * using the registered tools via subagents.
+ */
+export const ITERATE_SKILL_PROMPT = `
+## Iterate Workflow (autonomous code iteration)
+
+You have the iterate plugin installed, which registers these tools:
+- \`iterate_config\` — read iterate.config.yaml (dimensions, validation commands, personalization) or write a validated partial update (operation:"write", with automatic backup + rollback)
+- \`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. 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
+- \`iterate_rollback\` — revert a fix by id: restore the file from its backup, remove the fix from the registry, log a \`revert\` entry. Use when a round's validation fails
+- \`iterate_checkpoint\` — save / load / clear an iteration checkpoint (\`.iterate/checkpoint.json\`) so a long run can resume where it left off
+- \`iterate_status\` — summarize the current run: mode, round, fixes applied, architectural remaining, decision-log size, checkpoint presence
+
+### When to use
+When the user asks to review or iterate on the project (e.g. "review this project", "iterate on error handling", "check the codebase for issues", "dry-run review", "反复审查"), run an iterate **workflow** by calling the \`workflow\` tool.
+- If the user says "review only" / "dry run" / "不要改文件" / "反复审查" → use \`mode: "dry-run"\`.
+- Otherwise → use \`mode: "normal"\`.
+
+### Workflow script contract
+Write a plain-JS script (top-level await, ends with \`return <json>\`). Available globals:
+- \`agent(prompt, opts?): Promise<value>\` — spawn a subagent. \`opts.schema\` gives structured output (object-rooted JSON Schema: type/properties/required/additionalProperties/items/enum/const/oneOf only). Resolves \`null\` on child failure. Other opts: \`label\`, \`phase\`.
+- \`parallel(thunks): Promise<value[]>\` — run zero-arg async functions concurrently, await all.
+- \`phase(title)\`, \`log(message)\` — progress narration.
+- \`args\` — the args object passed to the workflow tool.
+
+The script CANNOT call tools directly. Subagents are the ones who call tools.
+
+### Dry-run mode workflow (pure review — the ONLY mode that never touches files)
+This is iterate's read-only health-check: repeated review rounds until findings converge,
+then produce an auditable report, then audit the report itself (meta-review) and give a
+final review report. NO file writes, NO git, NO branches, NO worktree.
+
+Canonical script — reproduce this structure exactly (adjust dims via the plan):
+
+\`\`\`js
+phase('plan')
+const planRes = await agent(
+  'Call iterate_review({operation:"plan", mode:"dry-run"}) and return the plan JSON.',
+  { label: 'review:plan' }
+)
+const plan = (planRes && planRes.plan) ? planRes.plan : null
+if (!plan || !Array.isArray(plan.dimensions)) throw new Error('plan failed: iterate_review did not return a valid plan')
+const dims = plan.dimensions.map(d => d.id)
+const maxRounds = plan.maxReviewRounds
+const knownIntentional = (plan.knownIntentional || [])   // config personalization filter, applied in aggregate
+let known = []              // cumulative DEDUPED findings fed back to reviewers
+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 }
+  )
+  // 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
+  if (agg && agg.report && agg.report.convergence && agg.report.convergence.findingsByRound[r-1] === 0) {
+    log('round ' + r + ' found 0 new findings — converged')
+    break
+  }
+}
+
+phase('report')
+const finalAgg = 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:final' }
+)
+const report = (finalAgg && finalAgg.report) ? finalAgg.report : null
+if (!report || !report.convergence) throw new Error('aggregate failed: no valid report was produced')
+await agent(
+  'Call iterate_decision_log({operation:"append", type:"report", round:' + report.convergence.totalRounds + ', data:{mode:"dry-run", totalFindings:' + report.summary.totalFindings + '}})',
+  { label: 'review:log' }
+)
+
+phase('meta-review')
+// Audit the report itself for internal consistency, then produce the final report.
+const metaRes = await agent(
+  'Call iterate_review({operation:"meta-review", report:' + JSON.stringify(report) + '}) and return the finalReport JSON.',
+  { label: 'review:meta' }
+)
+const finalReport = metaRes && metaRes.finalReport ? metaRes.finalReport : null
+const metaAudit = finalReport && finalReport.metaReview ? finalReport.metaReview : null
+
+return {
+  mode: 'dry-run',
+  goal: report.goal,
+  rounds: rounds.length,
+  converged: report.convergence.converged,
+  stoppedReason: report.convergence.stoppedReason,
+  findingsByRound: report.convergence.findingsByRound,
+  totalFindings: report.summary.totalFindings,
+  bySeverity: { critical: report.summary.critical, high: report.summary.high, medium: report.summary.medium, low: report.summary.low },
+  byDimension: report.summary.byDimension,
+  report,
+  metaReview: metaAudit ? { verdict: finalReport.verdict, issues: metaAudit.issues || [], checksRun: metaAudit.checksRun || 0 } : null,
+  finalReport
+}
+\`\`\`
+
+Key rules for dry-run:
+- **NEVER call a fixer / never edit files / never create branches or worktree.** Reviewers read only.
+- 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.
+- Only a single \`report\` entry may be appended to the decision log; nothing else is written.
+
+### Normal-mode workflow (autonomous closed loop)
+Set \`args.mode = "normal"\`. Loop: resume → plan → parallel review ×N → atomic fixes via \`iterate_fix\` → validate → rollback on failure → checkpoint → loop → auto-stop when zero findings remain.
+Canonical script — reproduce this structure exactly (adjust dims via the plan):
+
+\`\`\`js
+// args = { mode: "normal", maxRounds? }
+phase('resume')
+// If a previous run was interrupted, resume from its checkpoint instead of restarting.
+const ckRes = await agent(
+  'Call iterate_checkpoint({ operation: "load" }) and return the checkpoint JSON.',
+  { label: 'checkpoint:load' }
+)
+const checkpoint = (ckRes && ckRes.checkpoint) ? ckRes.checkpoint : null
+const startRound = (checkpoint && typeof checkpoint.round === 'number') ? checkpoint.round + 1 : 1
+
+phase('plan')
+const configRes = await agent(
+  'Call iterate_config({ validate: true }) and return the config JSON.',
+  { label: 'config:read' }
+)
+const cfg = (configRes && configRes.config) ? configRes.config : null
+const atomicMaxLines = (cfg && cfg.atomic && cfg.atomic.max_lines) ? cfg.atomic.max_lines : 20
+const planRes = await agent(
+  'Call iterate_review({operation:"plan", mode:"normal", maxReviewRounds:' + (args.maxRounds || 3) + '}) and return the plan JSON.',
+  { label: 'review:plan' }
+)
+const plan = (planRes && planRes.plan) ? planRes.plan : null
+if (!plan || !Array.isArray(plan.dimensions)) throw new Error('plan failed: iterate_review did not return a valid plan')
+const knownIntentional = (plan.knownIntentional || [])   // config personalization filter, applied in aggregate
+const dims = plan.dimensions.map(d => d.id)
+const maxRounds = plan.maxReviewRounds
+const rounds = []          // findings per review round (each on the then-current code state)
+const architectural = []   // findings deliberately left unfixed (reported at the end)
+let fixedCount = (checkpoint && typeof checkpoint.fixedCount === 'number') ? checkpoint.fixedCount : 0
+let converged = false
+let abortedByValidation = false
+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)
+
+  // Deterministic dedupe / known_intentional filter / severity sort for this round.
+  const agg = await agent(
+    'Call iterate_review({operation:"aggregate", mode:"normal", rounds:' + JSON.stringify([thisRound]) + ', knownIntentional:' + JSON.stringify(knownIntentional) + '}) and return the report JSON.',
+    { label: 'review:aggregate:r' + r }
+  )
+  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)
+
+  const roundFixIds = []
+  if (atomic.length > 0) {
+    // Group atomic fixes by file. One fixer agent handles a whole file serially —
+    // calling iterate_fix per finding (the ONLY sanctioned writer), then
+    // iterate_diff to verify — so the same file is never edited concurrently;
+    // different files still run in parallel.
+    const byFile = {}
+    atomic.forEach(f => { (byFile[f.file] = byFile[f.file] || []).push(f) })
+    const fixRes = await parallel(Object.keys(byFile).map(file => () => agent(
+      'Apply the fixes for ' + file + ' using iterate_fix. For EACH finding in this list, ' +
+      'read the current file, compute the edited full content (change <= ' + atomicMaxLines + ' lines), and call ' +
+      'iterate_fix({ file: "' + file + '", content: <full new file content>, finding: <that finding>, round: ' + r + ' }). ' +
+      'Apply the findings IN ORDER. After all fixes, call iterate_diff({ file: "' + file + '" }) to verify the accumulated diff. ' +
+      'Findings: ' + JSON.stringify(byFile[file]) + '. Return the array of {id, ok, error} per iterate_fix call.',
+      { label: 'fix:' + file, phase: 'fix', schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          fixes: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { id: { type: 'string' }, ok: { type: 'boolean' }, error: { type: 'string' } }, required: ['id', 'ok'] } }
+        },
+        required: ['fixes'] } }
+    )))
+    for (const res of fixRes) {
+      if (res && Array.isArray(res.fixes)) {
+        for (const fx of res.fixes) {
+          if (fx && fx.ok === true) { fixedCount += 1; roundFixIds.push(fx.id) }
+        }
+      }
+    }
+  }
+
+  // Cross-round dedupe of architectural findings before accumulating.
+  const seenKeys = architectural.map(a => a.file + '|' + a.dimension + '|' + a.summary)
+  for (const f of remaining) {
+    const key = f.file + '|' + f.dimension + '|' + f.summary
+    if (seenKeys.indexOf(key) < 0) { architectural.push(f); seenKeys.push(key) }
+  }
+
+  // Validate every configured command; on ANY failure roll back this round's fixes.
+  const valRes = await agent(
+    'Read iterate.config.yaml validation.commands, then call iterate_validate({ command: <cmd> }) for EACH configured command ' +
+    '(one tool call per command). Return all results as {command, exitCode} entries.',
+    { label: 'validate:r' + r, phase: 'validate', schema: {
+      type: 'object', additionalProperties: false,
+      properties: {
+        results: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { command: { type: 'string' }, exitCode: { type: 'integer' } }, required: ['command', 'exitCode'] } }
+      },
+      required: ['results'] } }
+  )
+  failedCommands = (valRes && Array.isArray(valRes.results)) ? valRes.results.filter(v => v.exitCode !== 0).map(v => v.command) : []
+  if (failedCommands.length > 0) {
+    log('round ' + r + ' validation FAILED on: ' + failedCommands.join(', ') + ' — rolling back this round')
+    abortedByValidation = true
+    if (roundFixIds.length > 0) {
+      await agent(
+        'Call iterate_rollback({ id: <id> }) for EACH of these fix ids (one call per id): ' + JSON.stringify(roundFixIds) + '. Return the array of {id, ok, error}.',
+        { label: 'rollback:r' + r, phase: 'rollback', schema: {
+          type: 'object', additionalProperties: false,
+          properties: {
+            results: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { id: { type: 'string' }, ok: { type: 'boolean' }, error: { type: 'string' } }, required: ['id', 'ok'] } }
+          },
+          required: ['results'] } }
+      )
+    }
+    await agent(
+      'Call iterate_decision_log({operation:"append", type:"round_failed", round:' + r + ', data:{failedCommands:' + JSON.stringify(failedCommands) + ', rolledBack:' + roundFixIds.length + '}})',
+      { label: 'log:failed:r' + r }
+    )
+    break
+  }
+
+  await agent(
+    'Call iterate_decision_log({operation:"append", type:"review_result", round:' + r +
+    ', data:{atomic:' + atomic.length + ', architectural:' + remaining.length + ', fixedSoFar:' + fixedCount + '}})',
+    { label: 'log:r' + r }
+  )
+
+  // Persist progress so an interrupted run can resume from the next round.
+  await agent(
+    'Call iterate_checkpoint({ operation: "save", mode: "normal", round:' + r + ', maxRounds:' + maxRounds + ', fixedCount:' + fixedCount + ', architecturalCount:' + architectural.length + ', findings:' + JSON.stringify(architectural) + ' }) and return the checkpoint JSON.',
+    { label: 'checkpoint:save:r' + r }
+  )
+
+  if (atomic.length === 0 && remaining.length === 0) {
+    log('round ' + r + ' found nothing to fix — converged')
+    converged = true
+    break
+  }
+}
+
+phase('report')
+await agent(
+  'Call iterate_decision_log({operation:"append", type:"report", round:' + rounds.length +
+  ', data:{mode:"normal", fixed:' + fixedCount + ', architectural:' + architectural.length + '}})',
+  { label: 'report:log' }
+)
+const statusRes = await agent(
+  'Call iterate_status() and return the status JSON.',
+  { label: 'status:final' }
+)
+const status = (statusRes && statusRes.ok) ? statusRes : null
+if (!abortedByValidation) {
+  // Iteration finished cleanly → clear the checkpoint so the next run starts fresh.
+  await agent(
+    'Call iterate_checkpoint({ operation: "clear" }) and return {ok, existed}.',
+    { label: 'checkpoint:clear' }
+  )
+}
+return {
+  mode: 'normal',
+  goal: plan.goal,
+  roundsExecuted: rounds.length,
+  maxRounds: maxRounds,
+  converged: converged,
+  abortedByValidation: abortedByValidation,
+  failedCommands: failedCommands,
+  findingsFixed: fixedCount,
+  remainingArchitecturalCount: architectural.length,
+  remainingArchitectural: architectural,
+  status: status ? {
+    currentRound: status.currentRound,
+    totalRounds: status.totalRounds,
+    fixedCount: status.fixedCount,
+    architecturalCount: status.architecturalCount,
+    findingsCount: status.findingsCount,
+    hasCheckpoint: status.hasCheckpoint
+  } : null
+}
+\`\`\`
+
+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.
+- 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).
+- **Checkpoint after every round**; clear it only when the iteration completes cleanly.
+- Stop when a round produces nothing to fix (converged) or maxReviewRounds is reached.
+- Every round, every rollback, and the final report go to the append-only decision log.
+- 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),
+  "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.
+
+### Workflow meta
+Always pass \`meta: { name: "iterate", description: "Autonomous iterate loop" }\`.
+
+Always end with a clear summary: total findings, count by severity, fixes applied (normal) or convergence stats (dry-run), and remaining architectural findings.
+`;