iterate-plugin 2.3.7 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "2.3.7",
+  "version": "2.5.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",
@@ -26,10 +26,17 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-connection"
+      ]
     }
   },
   "files": [
     "src",
+    "lib",
     "cordis.patch.yml",
     "README.md",
     "LICENSE"
@@ -38,7 +45,8 @@
     ".": {
       "types": "./src/index.ts",
       "default": "./src/index.ts"
-    }
+    },
+    "./client": "./lib/client.js"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
@@ -48,11 +56,10 @@
   "dependencies": {
     "@deepseek-ai/cordis": "4.0.1",
     "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-workflow": "0.1.0-rc.6",
-    "@deepseek-ai/schemastery": "3.18.1",
     "js-yaml": "4.3.1"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-session": "0.1.0-rc.6",
     "@types/js-yaml": "4.0.9",
     "@types/node": "22.15.0",
     "tsx": "4.20.3",

package/src/config-write.ts

@@ -0,0 +1,181 @@
+/**
+ * src/config-write.ts — shared helpers for safely WRITING iterate.config.yaml.
+ *
+ * Used by the `iterate_config` write operation. Provides:
+ *   - validateConfigUpdates : validate a caller-supplied partial update
+ *   - applyConfigUpdates    : merge a partial update into the current config
+ *   - writeConfigFile       : backup + write + rollback on failure
+ *
+ * The security posture mirrors the triage tool: never overwrite a malformed
+ * config, always back up before writing, roll back on failure.
+ */
+
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import yaml from 'js-yaml'
+
+/** Config file name (must match config-loader). */
+export const CONFIG_FILE = 'iterate.config.yaml'
+
+/** Backup suffix helper (filesystem-safe timestamp). */
+export function configBackupSuffix(now = new Date()): string {
+  return now.toISOString().replace(/[:.]/g, '-')
+}
+
+/**
+ * Validate a partial config update.
+ * Returns an array of error strings (empty when the update is valid).
+ */
+export function validateConfigUpdates(updates: Record<string, unknown>): string[] {
+  const errors: string[] = []
+  if (!updates || typeof updates !== 'object' || Array.isArray(updates)) {
+    return ['updates must be a JSON object']
+  }
+
+  if ('goal' in updates && typeof updates.goal !== 'string') {
+    errors.push('updates.goal must be a string')
+  }
+  if ('language' in updates && updates.language !== 'zh' && updates.language !== 'en') {
+    errors.push('updates.language must be "zh" or "en"')
+  }
+  if ('dimensions' in updates) {
+    if (!Array.isArray(updates.dimensions) || updates.dimensions.some((d) => typeof d !== 'string' || d.trim().length === 0)) {
+      errors.push('updates.dimensions must be an array of non-empty strings')
+    }
+  }
+  if ('max_rounds' in updates) {
+    if (typeof updates.max_rounds !== 'number' || !Number.isInteger(updates.max_rounds) || updates.max_rounds < 1) {
+      errors.push('updates.max_rounds must be a positive integer')
+    }
+  }
+  if ('review' in updates) {
+    const r = updates.review as Record<string, unknown> | undefined
+    if (!r || typeof r !== 'object') {
+      errors.push('updates.review must be an object')
+    } else if (r.scope !== undefined && r.scope !== 'full' && r.scope !== 'changed-only') {
+      errors.push('updates.review.scope must be "full" or "changed-only"')
+    }
+  }
+  if ('atomic' in updates) {
+    const a = updates.atomic as Record<string, unknown> | undefined
+    if (!a || typeof a !== 'object') {
+      errors.push('updates.atomic must be an object')
+    } else {
+      if (a.max_lines !== undefined && (typeof a.max_lines !== 'number' || !Number.isInteger(a.max_lines) || a.max_lines < 1)) {
+        errors.push('updates.atomic.max_lines must be a positive integer')
+      }
+      if (a.max_adjacent_methods !== undefined && (typeof a.max_adjacent_methods !== 'number' || a.max_adjacent_methods < 0)) {
+        errors.push('updates.atomic.max_adjacent_methods must be a non-negative number')
+      }
+    }
+  }
+  if ('git' in updates) {
+    const g = updates.git as Record<string, unknown> | undefined
+    if (!g || typeof g !== 'object') {
+      errors.push('updates.git must be an object')
+    } else {
+      if (g.target_branch !== undefined && typeof g.target_branch !== 'string') {
+        errors.push('updates.git.target_branch must be a string')
+      }
+      for (const boolKey of ['use_worktree', 'push_per_round', 'auto_merge'] as const) {
+        if (g[boolKey] !== undefined && typeof g[boolKey] !== 'boolean') {
+          errors.push(`updates.git.${boolKey} must be a boolean`)
+        }
+      }
+    }
+  }
+  if ('validation' in updates) {
+    const v = updates.validation as Record<string, unknown> | undefined
+    if (!v || typeof v !== 'object') {
+      errors.push('updates.validation must be an object')
+    } else if ('commands' in v && v.commands !== undefined && typeof v.commands !== 'object') {
+      errors.push('updates.validation.commands must be an object of command arrays')
+    }
+  }
+  if ('personalization' in updates && (!updates.personalization || typeof updates.personalization !== 'object')) {
+    errors.push('updates.personalization must be an object')
+  }
+  if ('onboarding' in updates && (!updates.onboarding || typeof updates.onboarding !== 'object')) {
+    errors.push('updates.onboarding must be an object')
+  }
+  return errors
+}
+
+/** Recursively merge `updates` over `base` (arrays replaced wholesale). */
+export function applyConfigUpdates(
+  base: Record<string, unknown>,
+  updates: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...base }
+  for (const [key, value] of Object.entries(updates)) {
+    if (value === undefined) continue
+    const baseValue = out[key]
+    if (
+      baseValue &&
+      typeof baseValue === 'object' &&
+      !Array.isArray(baseValue) &&
+      value &&
+      typeof value === 'object' &&
+      !Array.isArray(value)
+    ) {
+      out[key] = applyConfigUpdates(baseValue as Record<string, unknown>, value as Record<string, unknown>)
+    } else {
+      out[key] = value
+    }
+  }
+  return out
+}
+
+/**
+ * Read the raw config object from disk (empty object when missing).
+ * Throws when the file exists but cannot be parsed as a YAML mapping
+ * (never overwrite a malformed config).
+ */
+export function readRawConfig(configPath: string): Record<string, unknown> {
+  if (!existsSync(configPath)) return {}
+  const content = readFileSync(configPath, 'utf-8')
+  let parsed: unknown
+  try {
+    parsed = yaml.load(content)
+  } catch {
+    throw new Error('existing iterate.config.yaml is not a valid YAML mapping')
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error('existing iterate.config.yaml is not a valid YAML mapping')
+  }
+  return parsed as Record<string, unknown>
+}
+
+/**
+ * Write a config object to disk with backup + rollback.
+ * Returns `{ ok: true, backupPath }` or `{ ok: false, error }`.
+ */
+export function writeConfigFile(
+  projectRoot: string,
+  config: Record<string, unknown>,
+): { ok: true; backupPath: string | null } | { ok: false; error: string } {
+  const configPath = join(projectRoot, CONFIG_FILE)
+  const hadFile = existsSync(configPath)
+  const backupPath = hadFile ? `${configPath}.bak-${configBackupSuffix()}` : null
+
+  if (backupPath) {
+    try {
+      copyFileSync(configPath, backupPath)
+    } catch (err) {
+      return { ok: false, error: `failed to create backup: ${String(err)}` }
+    }
+  }
+
+  try {
+    writeFileSync(configPath, yaml.dump(config, { noRefs: true }), 'utf-8')
+  } catch (err) {
+    try {
+      if (backupPath) copyFileSync(backupPath, configPath)
+    } catch {
+      // Rollback failure is reported, never swallowed silently.
+    }
+    return { ok: false, error: `failed to write config: ${String(err)}` }
+  }
+
+  return { ok: true, backupPath }
+}

package/src/index.ts

@@ -2,11 +2,11 @@
  * iterate-plugin — dsh plugin for the iterate autonomous closed-loop workflow
  *
  * Architecture:
- * - The plugin registers 4 tools (config, validate, decision-log, context)
+ * - The plugin registers 6 tools (config, validate, decision-log, context, review, triage)
  * - The plugin injects a system prompt section teaching the iterate workflow pattern
  * - The model (prompted by the skill) writes a workflow script using dsh's `workflow` tool
  * - The workflow script uses `agent()` / `parallel()` / `phase()` / `log()` to orchestrate
- * - Subagents use the 4 tools to do real work (read config, run validation, log decisions)
+ * - Subagents use the 6 tools to do real work (read config, run validation, log decisions, review, triage)
  *
  * Tool invocation model:
  * - Workflow script CANNOT call tools directly (sandboxed vm, no Node API)
@@ -16,7 +16,7 @@
  *
  * Key files:
  * - src/index.ts      — Plugin entry: register tools + inject skill prompt
- * - src/tools/        — 4 tool implementations
+ * - src/tools/        — 6 tool implementations + meta-review/review engines
  * - src/config-loader.ts — YAML config loading
  * - src/types.ts     — Shared types
  */
@@ -27,18 +27,27 @@ import { registerValidateTool } from './tools/validate.ts'
 import { registerDecisionLogTool } from './tools/decision-log.ts'
 import { registerContextTool } from './tools/context.ts'
 import { registerReviewTool } from './tools/review.ts'
+import { registerTriageTool } from './tools/triage.ts'
+import { registerFixTool, registerDiffTool, registerRollbackTool } from './tools/fix.ts'
+import { registerCheckpointTool, registerStatusTool } from './tools/checkpoint.ts'
 import { ITERATE_SKILL_PROMPT } from './skill-prompt.ts'
 
 export const name = 'iterate-plugin'
 export const inject = ['tools', 'systemPrompt']
 
 export function apply(ctx: Context): void {
-  // 1. Register the 5 core tools
+  // 1. Register the 11 tools
   registerConfigTool(ctx)
   registerValidateTool(ctx)
   registerDecisionLogTool(ctx)
   registerContextTool(ctx)
   registerReviewTool(ctx)
+  registerTriageTool(ctx)
+  registerFixTool(ctx)
+  registerDiffTool(ctx)
+  registerRollbackTool(ctx)
+  registerCheckpointTool(ctx)
+  registerStatusTool(ctx)
 
   // 2. Inject the iterate skill prompt as a system prompt section
   // This teaches the model how to write iterate workflow scripts using the tools.

package/src/paths.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared filesystem layout for the iterate plugin's runtime state.
+ *
+ * All runtime artifacts live under `<projectRoot>/.iterate/`:
+ *   .iterate/decision-log.jsonl   — append-only decision log
+ *   .iterate/fixes/               — fix system: backups + fix registry
+ *   .iterate/checkpoint.json      — iteration checkpoint (resume support)
+ *
+ * Kept separate from config-loader so every tool points at the same dirs.
+ */
+
+import { join } from 'node:path'
+
+/** Runtime state root for a project (e.g. `<projectRoot>/.iterate`). */
+export function iterateDir(projectRoot: string): string {
+  return join(projectRoot, '.iterate')
+}
+
+/** Fix-system directory (backups + registry). */
+export function fixesDir(projectRoot: string): string {
+  return join(iterateDir(projectRoot), 'fixes')
+}
+
+/** Fix-registry file (JSON). */
+export function fixRegistryPath(projectRoot: string): string {
+  return join(fixesDir(projectRoot), 'registry.json')
+}
+
+/** Fix-backup file for one fix id + timestamp. */
+export function fixBackupPath(projectRoot: string, id: string, timestamp: string): string {
+  const safe = id.replace(/[^a-zA-Z0-9_-]/g, '_')
+  return join(fixesDir(projectRoot), `${safe}_${timestamp.replace(/[:.]/g, '-')}.bak`)
+}
+
+/** Iteration checkpoint file (JSON). */
+export function checkpointPath(projectRoot: string): string {
+  return join(iterateDir(projectRoot), 'checkpoint.json')
+}

package/src/review.ts

@@ -344,21 +344,28 @@ export function buildReviewPlan(input: {
   maxReviewRounds: number
   knownIntentional: KnownIntentional[]
 } {
+  // 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: input.config.goal,
-    scope: input.config.review.scope,
-    dimensions: input.config.dimensions.map((d) => ({
+    goal,
+    scope,
+    dimensions: dimensions.map((d) => ({
       id: d,
       reviewerPrompt: reviewerTaskPrompt({
         dimension: d,
-        goal: input.config.goal,
-        scope: input.config.review.scope,
+        goal,
+        scope,
         mode: input.mode,
         alreadyKnown: [],
         outputLanguage: language,
-        maxLines: input.config.atomic.max_lines,
+        maxLines,
       }),
       findingsSchema: findingsSchema(),
     })),

package/src/skill-prompt.ts

@@ -3,18 +3,24 @@
  *
  * 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 5 registered tools via subagents.
+ * 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)
+- \`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
+- \`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.
@@ -121,11 +127,20 @@ Key rules for dry-run:
 - 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: plan → parallel review ×N → fix atomic issues → validate → loop → auto-stop when zero findings remain.
+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.',
@@ -144,12 +159,14 @@ 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 = 0
+let fixedCount = (checkpoint && typeof checkpoint.fixedCount === 'number') ? checkpoint.fixedCount : 0
 let converged = false
+let abortedByValidation = false
+let failedCommands = []
 
 phase('loop')
-for (let r = 1; r <= maxRounds; r++) {
-  log('round ' + r + ' of ' + maxRounds + ' — review current state, fix atomics, validate')
+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.',
@@ -167,18 +184,34 @@ for (let r = 1; r <= maxRounds; r++) {
   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. All edits to the SAME file are applied by a
-    // single fixer agent (serial within a file), avoiding concurrent-write
-    // races; different files still run in parallel.
+    // 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) })
-    await parallel(Object.keys(byFile).map(file => () => agent(
-      'Apply ALL of these fixes to ' + file + ' in ONE pass with the smallest possible changes ' +
-      '(each <= ' + atomicMaxLines + ' lines, single function). ' + JSON.stringify(byFile[file]) + '. Verify the edit locally before finishing.',
-      { label: 'fix:' + file, phase: 'fix' }
+    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'] } }
     )))
-    fixedCount += atomic.length
+    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.
@@ -188,16 +221,51 @@ for (let r = 1; r <= maxRounds; r++) {
     if (seenKeys.indexOf(key) < 0) { architectural.push(f); seenKeys.push(key) }
   }
 
-  await agent(
-    'Call iterate_validate for each command in iterate.config.yaml validation.commands and return all {command, exitCode} results.',
-    { label: 'validate:r' + r, phase: 'validate' }
+  // 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
@@ -211,25 +279,50 @@ await agent(
   ', 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
+  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; reviewers read only. Architectural findings are reported, never auto-fixed.
+- 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.
-- Validate after every round of fixes; validation results are logged, not silently dropped.
+- 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 and the final report go to the append-only decision log.
+- 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),
@@ -242,4 +335,4 @@ Atomic = is_atomic true (single file, single function, ≤ config.atomic.max_lin
 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.
-`
+`