iterate-plugin 2.5.0 → 2.7.0

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.
+`;

package/dist/tools/checkpoint.js

@@ -0,0 +1,260 @@
+/**
+ * src/tools/checkpoint.ts — iteration checkpoint + status tools.
+ *
+ *   iterate_checkpoint — save / load / clear a resume checkpoint so a long
+ *                        iteration can continue where it left off.
+ *   iterate_status     — summarize the current iteration state from the
+ *                        decision log, fix registry, and checkpoint.
+ *
+ * Checkpoint layout: `.iterate/checkpoint.json`.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { resolveProjectRoot } from "../config-loader.js";
+import { checkpointPath, iterateDir } from "../paths.js";
+import { readRegistry } from "./fix.js";
+import { readDecisionEntries } from "./decision-log.js";
+// ─── Pure helpers (exported for unit tests) ─────────────────────────────────
+/** Read a checkpoint from disk (missing/corrupt → null). */
+export function readCheckpoint(projectRoot) {
+    const file = checkpointPath(projectRoot);
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        if (parsed.mode !== 'dry-run' && parsed.mode !== 'normal')
+            return null;
+        if (typeof parsed.round !== 'number')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Validate a checkpoint payload (returns error string or null). */
+export function validateCheckpoint(input) {
+    if (input.mode !== 'dry-run' && input.mode !== 'normal') {
+        return 'mode must be "dry-run" or "normal"';
+    }
+    if (typeof input.round !== 'number' || !Number.isInteger(input.round) || input.round < 0) {
+        return 'round must be a non-negative integer';
+    }
+    if (typeof input.maxRounds !== 'number' || !Number.isInteger(input.maxRounds) || input.maxRounds < 1) {
+        return 'maxRounds must be a positive integer';
+    }
+    if (typeof input.fixedCount !== 'number' || !Number.isInteger(input.fixedCount) || input.fixedCount < 0) {
+        return 'fixedCount must be a non-negative integer';
+    }
+    if (typeof input.architecturalCount !== 'number' || !Number.isInteger(input.architecturalCount) || input.architecturalCount < 0) {
+        return 'architecturalCount must be a non-negative integer';
+    }
+    return null;
+}
+/**
+ * Compute a status summary from the runtime artifacts.
+ * Pure (no I/O) — all reads are injected, so it is unit-testable.
+ */
+export function computeStatus(input) {
+    const checkpoint = input.checkpoint;
+    const entries = input.decisionEntries;
+    const registry = input.fixRegistry;
+    const lastEntry = entries.length > 0 ? entries[entries.length - 1] : null;
+    const lastUpdated = lastEntry?.timestamp ?? checkpoint?.updatedAt ?? null;
+    // Round = checkpoint.round (explicit) or max round seen in the decision log.
+    let currentRound = checkpoint?.round ?? 0;
+    if (!checkpoint) {
+        for (const e of entries) {
+            if (typeof e.round === 'number' && e.round > currentRound)
+                currentRound = e.round;
+        }
+    }
+    const totalRounds = checkpoint?.maxRounds ?? currentRound;
+    const registryFixed = registry.rounds.reduce((sum, r) => sum + r.fixedCount, 0);
+    const failedCount = registry.rounds.reduce((sum, r) => sum + r.failedCount, 0);
+    // When a checkpoint exists, its snapshot fields are authoritative for resume
+    // (fixedCount / architecturalCount / findings); otherwise derive from the
+    // live fix registry and decision log.
+    const fixedCount = checkpoint ? checkpoint.fixedCount : registryFixed;
+    const architecturalCount = checkpoint?.architecturalCount ?? 0;
+    return {
+        mode: checkpoint?.mode ?? null,
+        currentRound,
+        totalRounds,
+        fixedCount,
+        architecturalCount,
+        findingsCount: checkpoint?.findings.length ?? 0,
+        totalDecisionLogEntries: entries.length,
+        hasCheckpoint: checkpoint !== null,
+        checkpoint,
+        lastUpdated,
+    };
+}
+// ─── iterate_checkpoint ──────────────────────────────────────────────────────
+/**
+ * Register the `iterate_checkpoint` tool.
+ * Saves progress so the orchestrator can resume a long iteration.
+ */
+export function registerCheckpointTool(ctx) {
+    ctx.tools.register(defineTool({
+        name: 'iterate_checkpoint',
+        description: 'Save / load / clear the iteration checkpoint. The workflow saves a checkpoint at the start of ' +
+            'each round (so a long run can resume) and clears it when the iteration completes.',
+        parameters: {
+            operation: {
+                type: 'string',
+                required: true,
+                description: '"save" to persist the current progress, "load" to read it back, "clear" to remove it.',
+                enum: ['save', 'load', 'clear'],
+            },
+            mode: { type: 'string', description: 'Required for save: "dry-run" or "normal".' },
+            round: { type: 'integer', description: 'Required for save: current round number (0 = none started).' },
+            maxRounds: { type: 'integer', description: 'Required for save: total round cap.' },
+            fixedCount: { type: 'integer', description: 'Required for save: number of fixes applied so far.' },
+            architecturalCount: { type: 'integer', description: 'Required for save: architectural findings left unfixed.' },
+            findings: { type: 'json', description: 'Optional for save: the current deduped findings to resume from.' },
+            path: { type: 'string', description: 'Project root directory (default: current working directory).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    operation: { type: 'string', required: true },
+                    ok: { type: 'boolean', required: true },
+                    checkpoint: { type: 'json' },
+                    existed: { type: 'boolean' },
+                    error: { type: 'string' },
+                },
+            },
+            render: (_args, value) => [
+                { type: 'text', text: JSON.stringify(value, null, 2) },
+            ],
+        },
+        async execute(args) {
+            const resolved = resolveProjectRoot(args.path);
+            if (!resolved.ok)
+                return { operation: args.operation, ok: false, error: resolved.reason };
+            const projectRoot = resolved.root;
+            if (args.operation === 'load') {
+                const checkpoint = readCheckpoint(projectRoot);
+                return { operation: 'load', ok: true, checkpoint: checkpoint ?? undefined };
+            }
+            if (args.operation === 'clear') {
+                const existed = existsSync(checkpointPath(projectRoot));
+                if (existed) {
+                    try {
+                        rmSync(checkpointPath(projectRoot), { force: true });
+                    }
+                    catch (err) {
+                        return { operation: 'clear', ok: false, existed, error: `failed to clear checkpoint: ${String(err)}` };
+                    }
+                }
+                return { operation: 'clear', ok: true, existed };
+            }
+            if (args.operation === 'save') {
+                const invalid = validateCheckpoint({
+                    mode: args.mode,
+                    round: args.round,
+                    maxRounds: args.maxRounds,
+                    fixedCount: args.fixedCount,
+                    architecturalCount: args.architecturalCount,
+                });
+                if (invalid)
+                    return { operation: 'save', ok: false, error: invalid };
+                const checkpoint = {
+                    mode: args.mode,
+                    round: args.round,
+                    maxRounds: args.maxRounds,
+                    fixedCount: args.fixedCount,
+                    architecturalCount: args.architecturalCount,
+                    findings: (Array.isArray(args.findings) ? args.findings : []),
+                    startedAt: readCheckpoint(projectRoot)?.startedAt ?? new Date().toISOString(),
+                    updatedAt: new Date().toISOString(),
+                };
+                try {
+                    mkdirSync(iterateDir(projectRoot), { recursive: true });
+                    writeFileSync(checkpointPath(projectRoot), JSON.stringify(checkpoint, null, 2), 'utf-8');
+                }
+                catch (err) {
+                    return { operation: 'save', ok: false, error: `failed to write checkpoint: ${String(err)}` };
+                }
+                return { operation: 'save', ok: true, checkpoint: checkpoint };
+            }
+            return { operation: args.operation, ok: false, error: 'unknown operation. Use "save", "load", or "clear".' };
+        },
+    }));
+}
+// ─── iterate_status ──────────────────────────────────────────────────────────
+/**
+ * Register the `iterate_status` tool.
+ * Summarizes the current iteration state (mode, round, fixed count, findings).
+ */
+export function registerStatusTool(ctx) {
+    ctx.tools.register(defineTool({
+        name: 'iterate_status',
+        description: 'Summarize the current iterate run: mode, current round vs total, fixes applied, architectural ' +
+            'findings remaining, decision-log size, and whether a resume checkpoint exists.',
+        parameters: {
+            path: { type: 'string', description: 'Project root directory (default: current working directory).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    ok: { type: 'boolean', required: true },
+                    mode: { type: 'string' },
+                    currentRound: { type: 'integer' },
+                    totalRounds: { type: 'integer' },
+                    fixedCount: { type: 'integer' },
+                    architecturalCount: { type: 'integer' },
+                    findingsCount: { type: 'integer' },
+                    totalDecisionLogEntries: { type: 'integer' },
+                    hasCheckpoint: { type: 'boolean' },
+                    lastUpdated: { type: 'string' },
+                    error: { type: 'string' },
+                },
+            },
+            render: (_args, value) => {
+                if (!value.ok)
+                    return [{ type: 'text', text: `status failed: ${value.error}` }];
+                const lines = [
+                    `Mode: ${value.mode ?? 'none'}`,
+                    `Round: ${value.currentRound} / ${value.totalRounds}`,
+                    `Fixed: ${value.fixedCount} · Architectural remaining: ${value.architecturalCount}`,
+                    `Findings in checkpoint: ${value.findingsCount}`,
+                    `Decision-log entries: ${value.totalDecisionLogEntries}`,
+                    `Checkpoint: ${value.hasCheckpoint ? 'yes' : 'no'}`,
+                    value.lastUpdated ? `Last updated: ${value.lastUpdated}` : '',
+                ];
+                return [{ type: 'text', text: lines.filter(Boolean).join('\n') }];
+            },
+        },
+        async execute(args) {
+            const resolved = resolveProjectRoot(args.path);
+            if (!resolved.ok)
+                return { ok: false, error: resolved.reason };
+            const projectRoot = resolved.root;
+            const status = computeStatus({
+                checkpoint: readCheckpoint(projectRoot),
+                decisionEntries: readDecisionEntries(projectRoot),
+                fixRegistry: readRegistry(projectRoot),
+            });
+            return {
+                ok: true,
+                mode: status.mode ?? undefined,
+                currentRound: status.currentRound,
+                totalRounds: status.totalRounds,
+                fixedCount: status.fixedCount,
+                architecturalCount: status.architecturalCount,
+                findingsCount: status.findingsCount,
+                totalDecisionLogEntries: status.totalDecisionLogEntries,
+                hasCheckpoint: status.hasCheckpoint,
+                lastUpdated: status.lastUpdated ?? undefined,
+            };
+        },
+    }));
+}