iterate-plugin 2.4.0 → 2.6.0

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

package/src/tools/checkpoint.ts

@@ -0,0 +1,285 @@
+/**
+ * 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 type { JsonValue } from '@deepseek-ai/dsh-session'
+import { resolveProjectRoot } from '../config-loader.ts'
+import { checkpointPath, iterateDir } from '../paths.ts'
+import { readRegistry } from './fix.ts'
+import { readDecisionEntries } from './decision-log.ts'
+import type { IterationCheckpoint, IterationStatus } from '../types.ts'
+
+// ─── Pure helpers (exported for unit tests) ─────────────────────────────────
+
+/** Read a checkpoint from disk (missing/corrupt → null). */
+export function readCheckpoint(projectRoot: string): IterationCheckpoint | null {
+  const file = checkpointPath(projectRoot)
+  if (!existsSync(file)) return null
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf-8')) as IterationCheckpoint
+    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: {
+  mode: unknown
+  round: unknown
+  maxRounds: unknown
+  fixedCount: unknown
+  architecturalCount: unknown
+}): string | null {
+  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: {
+  checkpoint: IterationCheckpoint | null
+  decisionEntries: { timestamp: string; type: string; round?: number; data?: Record<string, unknown> }[]
+  fixRegistry: { rounds: { round: number; fixedCount: number; failedCount: number }[] }
+}): IterationStatus {
+  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: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  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 as unknown as JsonValue | null) ?? 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: IterationCheckpoint = {
+            mode: args.mode as 'dry-run' | 'normal',
+            round: args.round as number,
+            maxRounds: args.maxRounds as number,
+            fixedCount: args.fixedCount as number,
+            architecturalCount: args.architecturalCount as number,
+            findings: (Array.isArray(args.findings) ? args.findings : []) as unknown as IterationCheckpoint['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 as unknown as JsonValue }
+        }
+
+        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: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  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,
+        }
+      },
+    }),
+  )
+}

package/src/tools/config.ts

@@ -1,10 +1,18 @@
+import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { loadEffectiveConfig, validateConfig, resolveProjectRoot } from '../config-loader.ts'
+import {
+  applyConfigUpdates,
+  readRawConfig,
+  validateConfigUpdates,
+  writeConfigFile,
+} from '../config-write.ts'
 
 /**
  * Register the `iterate_config` tool.
- * Reads and returns the iterate.config.yaml configuration.
+ * Reads and returns the iterate.config.yaml configuration, or writes a
+ * validated partial update back to it (with backup + rollback).
  * Model-facing: returns JSON with the full config, a specific section, or validation errors.
  */
 export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
@@ -12,11 +20,17 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
     defineTool({
       name: 'iterate_config',
       description:
-        'Read the iterate.config.yaml configuration from the project root. ' +
+        'Read or update the iterate.config.yaml configuration from the project root. ' +
         'Returns the full parsed config, a specific section, or validation errors. ' +
-        'Use this to discover available dimensions, validation commands, git settings, and personalization rules.',
+        'Use this to discover available dimensions, validation commands, git settings, and personalization rules, ' +
+        'or to write back validated changes (goal, dimensions, max_rounds, review, atomic, validation, git, etc.).',
 
       parameters: {
+        operation: {
+          type: 'string',
+          description: 'Default "read". "write" validates and applies a partial config update (backed up first).',
+          enum: ['read', 'write'],
+        },
         path: {
           type: 'string',
           description: 'Project root directory (default: current working directory).',
@@ -30,6 +44,13 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
           type: 'boolean',
           description: 'If true, validate the config schema and return any missing fields.',
         },
+        updates: {
+          type: 'json',
+          description:
+            'For operation "write": a partial config object to merge in, e.g. ' +
+            '{"goal":"...","dimensions":["correctness","security"],"max_rounds":5}. ' +
+            'Supported keys: goal, language, dimensions, max_rounds, review, atomic, git, validation, personalization, onboarding.',
+        },
       },
 
       output: {
@@ -44,6 +65,9 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
             data: { type: 'json' },
             config: { type: 'json' },
             availableSections: { type: 'array', items: { type: 'string' } },
+            operation: { type: 'string' },
+            ok: { type: 'boolean' },
+            backupPath: { type: 'string' },
             error: { type: 'string' },
           },
         },
@@ -58,9 +82,43 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
           return { found: false, error: resolved.reason }
         }
         const projectRoot = resolved.root
-        // Effective config = defaults (Master) merged with any project-root
-        // overrides. Never null: a project without a config file runs on the
-        // built-in defaults, so the workflow stays usable out of the box.
+
+        // ── Write operation ────────────────────────────────────────────────
+        if (args.operation === 'write') {
+          const updates = args.updates as Record<string, unknown> | undefined
+          const updateErrors = validateConfigUpdates(updates ?? {})
+          if (updateErrors.length > 0) {
+            return { operation: 'write', ok: false, found: false, errors: updateErrors }
+          }
+          let base: Record<string, unknown>
+          try {
+            base = readRawConfig(join(projectRoot, 'iterate.config.yaml'))
+          } catch (err) {
+            return { operation: 'write', ok: false, found: false, error: `failed to read config: ${String(err)}` }
+          }
+          const merged = applyConfigUpdates(base, updates ?? {})
+          const schemaErrors = validateConfig(merged)
+          if (schemaErrors.length > 0) {
+            return {
+              operation: 'write',
+              ok: false,
+              found: false,
+              errors: schemaErrors.map((e) => `missing/required field: ${e}`),
+            }
+          }
+          const result = writeConfigFile(projectRoot, merged)
+          if (!result.ok) return { operation: 'write', ok: false, found: false, error: result.error }
+          const { config } = loadEffectiveConfig(projectRoot)
+          return {
+            operation: 'write',
+            ok: true,
+            found: true,
+            backupPath: result.backupPath ?? undefined,
+            config: config as unknown as JsonValue,
+          }
+        }
+
+        // ── Read operations (original behavior) ────────────────────────────
         const { config, source } = loadEffectiveConfig(projectRoot)
         const hasOverride = source === 'override'
 

package/src/tools/decision-log.ts

@@ -23,7 +23,7 @@ function logPath(projectRoot: string): string {
  * Append one entry to the decision log (JSONL format).
  * Returns the entry count after appending.
  */
-function appendEntry(projectRoot: string, entry: DecisionLogEntry): { count: number; path: string } {
+export function appendDecisionEntry(projectRoot: string, entry: DecisionLogEntry): { count: number; path: string } {
   const filePath = logPath(projectRoot)
   const line = JSON.stringify(entry) + '\n'
   appendFileSync(filePath, line, 'utf-8')
@@ -41,7 +41,7 @@ function appendEntry(projectRoot: string, entry: DecisionLogEntry): { count: num
 /**
  * Read all entries from the decision log.
  */
-function readEntries(projectRoot: string): DecisionLogEntry[] {
+export function readDecisionEntries(projectRoot: string): DecisionLogEntry[] {
   const filePath = join(projectRoot, LOG_DIR, LOG_FILE)
   if (!existsSync(filePath)) return []
   try {
@@ -134,7 +134,7 @@ export function registerDecisionLogTool(ctx: { tools: { register: (def: ReturnTy
         const projectRoot = resolved.root
 
         if (args.operation === 'read') {
-          const entries = readEntries(projectRoot)
+          const entries = readDecisionEntries(projectRoot)
           return {
             operation: 'read',
             entryCount: entries.length,
@@ -158,7 +158,7 @@ export function registerDecisionLogTool(ctx: { tools: { register: (def: ReturnTy
             data: (args.data as Record<string, unknown>) ?? {},
           }
 
-          const result = appendEntry(projectRoot, entry)
+          const result = appendDecisionEntry(projectRoot, entry)
           return {
             operation: 'append',
             success: true,