iterate-plugin 2.7.1 → 2.7.2

package/dist/index.js

@@ -2,11 +2,13 @@
  * iterate-plugin — dsh plugin for the iterate autonomous closed-loop workflow
  *
  * Architecture:
- * - The plugin registers 6 tools (config, validate, decision-log, context, review, triage)
+ * - The plugin registers 13 tools (config, validate, decision-log, context, review,
+ *   triage, fix, diff, rollback, checkpoint, status, history, prune)
  * - 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 6 tools to do real work (read config, run validation, log decisions, review, triage)
+ * - Subagents use the 13 tools to do real work (read config, run validation, log decisions,
+ *   review, triage, apply/rollback/fixing, checkpoint, status, history, prune)
  *
  * Tool invocation model:
  * - Workflow script CANNOT call tools directly (sandboxed vm, no Node API)
@@ -16,7 +18,7 @@
  *
  * Key files:
  * - src/index.ts      — Plugin entry: register tools + inject skill prompt
- * - src/tools/        — 6 tool implementations + meta-review/review engines
+ * - src/tools/        — 13 tool implementations + meta-review/review engines
  * - src/config-loader.ts — YAML config loading
  * - src/types.ts     — Shared types
  */
@@ -34,7 +36,7 @@ import { ITERATE_SKILL_PROMPT } from "./skill-prompt.js";
 export const name = 'iterate-plugin';
 export const inject = ['tools', 'systemPrompt'];
 export function apply(ctx) {
-    // 1. Register the 11 tools
+    // 1. Register the 13 tools
     registerConfigTool(ctx);
     registerValidateTool(ctx);
     registerDecisionLogTool(ctx);

package/dist/review.js

@@ -208,6 +208,11 @@ export function buildReviewReport(input) {
     const lastRound = filteredRounds.length > 0 ? filteredRounds[filteredRounds.length - 1].round : 0;
     const lastRoundCount = lastRound > 0 ? (findingsByRound[lastRound - 1] ?? 0) : 0;
     const converged = filteredRounds.length > 0 && lastRoundCount === 0;
+    // Attach the normal-mode fix count to the summary (dry-run leaves it absent).
+    const computed = summarize(sorted);
+    if (input.mode === 'normal' && typeof input.fixedCount === 'number' && Number.isInteger(input.fixedCount)) {
+        computed.fixedCount = input.fixedCount;
+    }
     return {
         mode: input.mode,
         goal: input.goal,
@@ -225,7 +230,7 @@ export function buildReviewReport(input) {
                     ? 'converged'
                     : 'max_rounds_reached',
         },
-        summary: summarize(sorted),
+        summary: computed,
     };
 }
 /**

package/dist/skill-prompt.js

@@ -13,13 +13,15 @@ You have the iterate plugin installed, which registers these tools:
 - \`iterate_validate\` — run a whitelisted validation command
 - \`iterate_decision_log\` — append to the decision log, or read entries back for review
 - \`iterate_context\` — read SKILL.md / ITERATE.md project context
-- \`iterate_review\` — deterministic review engine: \`plan\` builds the review plan; \`aggregate\` dedupes/merges findings and computes convergence. Purely computational.
+- \`iterate_review\` — deterministic review engine: \`plan\` builds the review plan; \`aggregate\` dedupes/merges findings and computes convergence; \`meta-review\` audits a built report for internal consistency (counts, buckets, sorting, convergence math) and returns a final report with an \`approved\` / \`needs_revision\` verdict. Purely computational.
 - \`iterate_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
+- \`iterate_history\` — inspect the runtime state in detail: decision-log entries and applied fixes (optionally scoped to a round or a fixed file)
+- \`iterate_prune\` — remove stale runtime artifacts (\`.iterate/\` entries). Defaults to a read-only dry-run that reports what WOULD be removed; pass \`dryRun:false\` to actually prune.
 
 ### 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.
@@ -175,8 +177,10 @@ for (let r = startRound; r <= maxRounds; r++) {
   rounds.push(thisRound)
 
   // Deterministic dedupe / known_intentional filter / severity sort for this round.
+  // \`fixedCount\` is threaded into the report summary so the client dashboard can
+  // show a running "fixes applied" metric for normal mode.
   const agg = await agent(
-    'Call iterate_review({operation:"aggregate", mode:"normal", rounds:' + JSON.stringify([thisRound]) + ', knownIntentional:' + JSON.stringify(knownIntentional) + '}) and return the report JSON.',
+    'Call iterate_review({operation:"aggregate", mode:"normal", rounds:' + JSON.stringify([thisRound]) + ', knownIntentional:' + JSON.stringify(knownIntentional) + ', fixedCount:' + fixedCount + '}) and return the report JSON.',
     { label: 'review:aggregate:r' + r }
   )
   const findings = (agg && agg.report && agg.report.findings) ? agg.report.findings : thisRound.findings

package/dist/tools/decision-log.js

@@ -4,6 +4,34 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRoot } from "../config-loader.js";
 const LOG_DIR = '.iterate';
 const LOG_FILE = 'decision-log.jsonl';
+/** All valid DecisionLogEntry `type` values (must stay in sync with Types). */
+const VALID_ENTRY_TYPES = new Set([
+    'round_start',
+    'review_result',
+    'atomic_fix',
+    'architectural_fix',
+    'revert',
+    'round_failed',
+    'validation',
+    'decision',
+    'report',
+]);
+/**
+ * Validate a candidate (type, round, data) triple for an append operation.
+ * Returns an error string on failure, or null when the entry is well-formed.
+ */
+function validateEntryInput(type, round, data) {
+    if (typeof type !== 'string' || !VALID_ENTRY_TYPES.has(type)) {
+        return `type must be one of: ${[...VALID_ENTRY_TYPES].join(', ')}.`;
+    }
+    if (typeof round !== 'number' || !Number.isInteger(round) || round < 1) {
+        return 'round must be a positive integer.';
+    }
+    if (data !== undefined && data !== null && typeof data !== 'object') {
+        return 'data must be an object (or omitted).';
+    }
+    return null;
+}
 /**
  * Resolve the log file path, creating the directory if needed.
  */
@@ -73,13 +101,14 @@ export function registerDecisionLogTool(ctx) {
             type: {
                 type: 'string',
                 description: 'Entry type (required for append): round_start, review_result, atomic_fix, ' +
-                    'architectural_fix, revert, validation, decision, report.',
+                    'architectural_fix, revert, round_failed, validation, decision, report.',
                 enum: [
                     'round_start',
                     'review_result',
                     'atomic_fix',
                     'architectural_fix',
                     'revert',
+                    'round_failed',
                     'validation',
                     'decision',
                     'report',
@@ -132,17 +161,23 @@ export function registerDecisionLogTool(ctx) {
                 };
             }
             if (args.operation === 'append') {
-                if (!args.type || !args.round) {
+                const invalid = validateEntryInput(args.type, args.round, args.data);
+                if (invalid !== null) {
                     return {
                         operation: 'append',
-                        error: 'type and round are required for append operation.',
+                        error: invalid,
                     };
                 }
+                const type = args.type;
+                const round = args.round;
+                const data = args.data === undefined || args.data === null
+                    ? {}
+                    : args.data;
                 const entry = {
                     timestamp: new Date().toISOString(),
-                    round: args.round,
-                    type: args.type,
-                    data: args.data ?? {},
+                    round,
+                    type,
+                    data,
                 };
                 const result = appendDecisionEntry(projectRoot, entry);
                 return {

package/dist/tools/review.js

@@ -62,6 +62,11 @@ export function registerReviewTool(ctx) {
                 description: 'For `meta-review`: the ReviewReport JSON (as returned by `aggregate`) to audit for ' +
                     'internal consistency and produce the final review report.',
             },
+            fixedCount: {
+                type: 'integer',
+                description: 'For `aggregate` (normal mode only): number of atomic fixes applied so far. ' +
+                    'Surfaces a running "fixes applied" metric on the report summary.',
+            },
             path: {
                 type: 'string',
                 description: 'Project root directory (default: current working directory).',
@@ -128,6 +133,7 @@ export function registerReviewTool(ctx) {
                     maxReviewRounds,
                     rounds,
                     knownIntentional: args.knownIntentional,
+                    fixedCount: typeof args.fixedCount === 'number' ? args.fixedCount : undefined,
                 });
                 return { operation: 'aggregate', mode, report: report };
             }

package/lib/client.js

@@ -24,6 +24,8 @@
 import {
   findReportInObject,
   scanSessionForReport,
+  scanSessionForRunSummary,
+  extractVerdict,
   normalizeReport,
   computeConvergenceProgress,
   getCurrentRound,
@@ -199,6 +201,15 @@ const ITERATE_CSS = `
 .iterate-chip[data-ok] { border-color: var(--dsw-alias-state-success-primary); color: var(--dsw-alias-state-success-primary); background: color-mix(in srgb, var(--dsw-alias-state-success-primary) 10%, transparent); }
 .iterate-batch-check { display: inline-flex; align-items: center; gap: 4px; padding: 3px 8px; border-radius: 6px; border: 1px solid var(--dsw-alias-border-l1); background: var(--dsw-alias-bg-layer-2); color: var(--dsw-alias-label-secondary); font-size: 11px; cursor: pointer; }
 .iterate-batch-check input { margin: 0; cursor: pointer; }
+
+/* Meta-review verdict banner (dry-run closing result) */
+.iterate-verdict { margin: 10px 0; padding: 10px 14px; border-radius: 12px; border: 1px solid var(--dsw-alias-border-l1); background: var(--dsw-alias-bg-layer-1); display: flex; align-items: center; gap: 10px; flex-wrap: wrap; font-size: 12px; color: var(--dsw-alias-label-primary); }
+.iterate-verdict-tag { display: inline-flex; align-items: center; gap: 6px; padding: 3px 10px; border-radius: 999px; font-weight: 600; white-space: nowrap; }
+.iterate-verdict-tag[data-ok] { color: var(--dsw-alias-state-success-primary); background: color-mix(in srgb, var(--dsw-alias-state-success-primary) 14%, transparent); }
+.iterate-verdict-tag[data-warn] { color: var(--dsw-alias-state-warn-primary); background: color-mix(in srgb, var(--dsw-alias-state-warn-primary) 14%, transparent); }
+.iterate-verdict-detail { display: inline-flex; align-items: center; gap: 10px; flex-wrap: wrap; color: var(--dsw-alias-label-secondary); }
+.iterate-verdict-item { white-space: nowrap; }
+.iterate-verdict-item b { color: var(--dsw-alias-label-primary); font-weight: 600; }
 `
 
 // ─── Small helpers ───────────────────────────────────────────────────────────
@@ -384,15 +395,18 @@ function ConvergenceDashboard(props) {
     ),
   )
 
-  // Fix-count badge: show when the report has a fixes summary.
+  // Fix-count badge: show a running "fixes applied" metric when the report
+  // carries a number (normal mode only — threaded through `fixedCount`).
   const mode = report.mode
   const summary = report.summary
   const isNormal = mode === 'normal'
   const fixCount = isNormal && summary && typeof summary.fixedCount === 'number' ? summary.fixedCount : null
   const fixBadge = fixCount !== null
-    ? React.createElement('span', { className: 'iterate-metric', key: 'fixes' },
-        '\u{1F527} ' + String(fixCount) + ' fixes',
-      )
+    ? React.createElement('span', {
+        className: 'iterate-metric',
+        key: 'fixes',
+        title: '本轮已应用的原子修复数（正常模式）',
+      }, `${String(fixCount)} fixes`)
     : null
 
   return React.createElement(
@@ -712,6 +726,33 @@ function TriagePanel(props) {
   )
 }
 
+/** Meta-review verdict banner: surfaces the closing dry-run audit result. */
+function VerdictBanner(props) {
+  const verdict = props.verdict
+  if (!verdict) return null
+  const ok = verdict.verdict === 'approved'
+  const item = (num, unit) =>
+    React.createElement('span', { className: 'iterate-verdict-item' },
+      React.createElement('b', {}, String(num)), ` ${unit}`)
+  const phrase = (text) =>
+    React.createElement('span', { className: 'iterate-verdict-item' }, text)
+  return React.createElement(
+    'div',
+    { 'data-iterate-root': '', 'data-iterate': 'verdict', className: 'iterate-verdict' },
+    React.createElement('span', { className: 'iterate-verdict-tag', 'data-ok': ok ? '' : undefined, 'data-warn': ok ? undefined : '' },
+      ok ? '报告已批准' : '报告需修订'),
+    React.createElement('span', { className: 'iterate-verdict-detail' },
+      item(verdict.totalFindings, '项发现'),
+      item(verdict.totalRounds, '轮'),
+      item(verdict.checksRun, '项审查'),
+      ok
+        ? phrase('报告通过全部一致性检查')
+        : item(verdict.reportIssues, '处报告缺陷'),
+      phrase(verdict.converged ? '已收敛' : '未收敛'),
+    ),
+  )
+}
+
 /** Turn-tail chain entry: triage when findings exist, stats card otherwise. */
 function TurnTailEntry(props) {
   const candidates = []
@@ -720,19 +761,32 @@ function TurnTailEntry(props) {
   if (props && props.data) candidates.push(props.data)
   candidates.push(props)
 
+  // Meta-review verdict (dry-run closing result), found before the report.
+  let verdict = null
+  for (const c of candidates) {
+    const run = scanSessionForRunSummary(c)
+    if (run) { verdict = extractVerdict(run); break }
+  }
+
   let report = null
   for (const c of candidates) {
     const raw = findReportInObject(c, undefined, 24) || scanSessionForReport(c)
     if (raw) { report = normalizeReport(raw); break }
   }
-  if (!report) return null
-  // Render through React.createElement so each panel is a real component with
-  // its own hook identity (calling them as functions would violate the Rules
-  // of Hooks and crash when the findings/empty branch flips between renders).
-  if (!report.findings || report.findings.length === 0) {
-    return React.createElement(StatsCard, { report })
+
+  const blocks = []
+  if (verdict) blocks.push(React.createElement(VerdictBanner, { key: 'verdict', verdict }))
+  if (report) {
+    // Render through React.createElement so each panel is a real component with
+    // its own hook identity (calling them as functions would violate the Rules
+    // of Hooks and crash when the findings/empty branch flips between renders).
+    const panel = !report.findings || report.findings.length === 0
+      ? React.createElement(StatsCard, { report })
+      : React.createElement(TriagePanel, { report })
+    blocks.push(React.createElement('div', { key: 'report' }, panel))
   }
-  return React.createElement(TriagePanel, { report })
+  if (blocks.length === 0) return null
+  return React.createElement('div', { 'data-iterate-root': '', className: 'iterate-turn-tail-root' }, ...blocks)
 }
 
 /** Progress capsule: briefly surfaces round-completion (incl. convergence). */
@@ -850,8 +904,9 @@ function SettingsPanel() {
  */
 function selectTurnTail(owner) {
   if (!owner) return null
-  const raw = findReportInObject(owner.turn, undefined, 24) || scanSessionForReport(owner.turn)
-  return raw ? { matched: true } : null
+  if (findReportInObject(owner.turn, undefined, 24) || scanSessionForReport(owner.turn)) return { matched: true }
+  if (scanSessionForRunSummary(owner.turn)) return { matched: true }
+  return null
 }
 
 /**

package/lib/parse.js

@@ -160,6 +160,139 @@ export function scanSessionForReport(session) {
   return null
 }
 
+// ─── Run-summary / meta-review verdict detection ─────────────────────────────
+
+/**
+ * Check whether `obj` is an iterate dry-run run-summary object (the structured
+ * object returned by the workflow at the end of a dry-run). It wraps the
+ * ReviewReport and carries the meta-review verdict:
+ *   { mode, goal, rounds, converged, ..., report, metaReview, finalReport }
+ * The discriminator is `finalReport.verdict`, which only the meta-review
+ * closing step produces ("approved" | "needs_revision"). This shape is distinct
+ * from a ReviewReport (which has `convergence`/`findings`/`rounds`), so it never
+ * collides with `isReviewReport`.
+ *
+ * @param {unknown} obj
+ * @returns {obj is Record<string, unknown>}
+ */
+export function isRunSummary(obj) {
+  if (!obj || typeof obj !== 'object') return false
+  const o = /** @type {Record<string, unknown>} */ (obj)
+  const final = o.finalReport
+  return !!final &&
+    typeof final === 'object' &&
+    (final.verdict === 'approved' || final.verdict === 'needs_revision')
+}
+
+/**
+ * Deep-scan an object tree for the first iterate run-summary (same traversal
+ * semantics as `findReportInObject`, with circular-reference + depth guards).
+ *
+ * @param {unknown} obj
+ * @param {Set<unknown>} [seen]
+ * @param {number} [maxDepth=20]
+ * @returns {Record<string, unknown> | null}
+ */
+export function findRunSummaryInObject(obj, seen, maxDepth = 20) {
+  if (maxDepth <= 0) return null
+  if (!obj || typeof obj !== 'object') return null
+
+  const s = seen || new Set()
+  if (s.has(obj)) return null
+  s.add(obj)
+
+  if (isRunSummary(obj)) return /** @type {Record<string, unknown>} */ (obj)
+
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      const found = findRunSummaryInObject(item, s, maxDepth - 1)
+      if (found) return found
+    }
+    return null
+  }
+
+  const o = /** @type {Record<string, unknown>} */ (obj)
+  for (const key of Object.keys(o)) {
+    const val = o[key]
+    if (val && typeof val === 'object') {
+      const found = findRunSummaryInObject(val, s, maxDepth - 1)
+      if (found) return found
+    }
+  }
+
+  return null
+}
+
+/**
+ * Scan a session snapshot (or any object) for the latest iterate dry-run
+ * run-summary that exposes a meta-review verdict. Prefers the most recent.
+ *
+ * @param {unknown} session
+ * @returns {Record<string, unknown> | null}
+ */
+export function scanSessionForRunSummary(session) {
+  if (!session || typeof session !== 'object') return null
+
+  const direct = findRunSummaryInObject(session)
+  if (direct) return direct
+
+  const s = /** @type {Record<string, unknown>} */ (session)
+
+  // Common pattern: session.toolCalls[].result contains a run summary.
+  if (Array.isArray(s.toolCalls)) {
+    const calls = /** @type {Array<Record<string, unknown>>} */ (s.toolCalls)
+    for (let i = calls.length - 1; i >= 0; i--) {
+      const call = calls[i]
+      if (!call) continue
+      if (call.tool === 'workflow' || String(call.tool ?? '').endsWith('workflow')) {
+        const found = findRunSummaryInObject(call.result, undefined, 24)
+        if (found) return found
+      }
+    }
+  }
+
+  // Common pattern: assistant message content holding the workflow return.
+  if (Array.isArray(s.messages)) {
+    const msgs = /** @type {Array<Record<string, unknown>>} */ (s.messages)
+    for (let i = msgs.length - 1; i >= 0; i--) {
+      const msg = msgs[i]
+      if (!msg) continue
+      const found = findRunSummaryInObject(msg.content)
+      if (found) return found
+    }
+  }
+
+  return null
+}
+
+/**
+ * Extract a compact, UI-friendly verdict from a run-summary object.
+ * Returns null when the object is not a valid run-summary.
+ *
+ * @param {Record<string, unknown> | null | undefined} runSummary
+ * @returns {{ verdict: 'approved' | 'needs_revision', reportIssues: number, checksRun: number, converged: boolean, totalRounds: number, totalFindings: number } | null}
+ */
+export function extractVerdict(runSummary) {
+  if (!isRunSummary(runSummary)) return null
+  const o = /** @type {Record<string, unknown>} */ (runSummary)
+  const final = /** @type {Record<string, unknown>} */ (o.finalReport)
+  const meta = final.metaReview && typeof final.metaReview === 'object'
+    ? /** @type {Record<string, unknown>} */ (final.metaReview)
+    : {}
+  const issues = Array.isArray(meta.issues) ? meta.issues : []
+  // `totalRounds` may be a bare number (dry-run returns `rounds`) or a count.
+  const roundsVal = o.rounds
+  const totalRounds = typeof roundsVal === 'number' ? roundsVal : (Array.isArray(roundsVal) ? roundsVal.length : 0)
+  return {
+    verdict: final.verdict === 'needs_revision' ? 'needs_revision' : 'approved',
+    reportIssues: issues.length,
+    checksRun: typeof meta.checksRun === 'number' ? meta.checksRun : 0,
+    converged: o.converged === true,
+    totalRounds,
+    totalFindings: typeof o.totalFindings === 'number' ? o.totalFindings : 0,
+  }
+}
+
 // ─── Normalization ───────────────────────────────────────────────────────────
 
 /**
@@ -193,7 +326,9 @@ export function normalizeReport(report) {
   }
 
   // Compute summary if missing. Always build a NEW object so the input's
-  // summary (or any other field) is never mutated.
+  // summary (or any other field) is never mutated. `fixedCount` (normal mode
+  // only) is carried through so the dashboard fix-count metric survives
+  // normalization.
   let summary = report.summary
   if (!summary || typeof summary !== 'object') {
     summary = computeSummaryFromFindings(findings)
@@ -209,6 +344,7 @@ export function normalizeReport(report) {
       byDimension: s.byDimension && typeof s.byDimension === 'object'
         ? s.byDimension
         : computed.byDimension,
+      ...(typeof s.fixedCount === 'number' ? { fixedCount: s.fixedCount } : {}),
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "2.7.1",
+  "version": "2.7.2",
   "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",

package/src/index.ts

@@ -2,11 +2,13 @@
  * iterate-plugin — dsh plugin for the iterate autonomous closed-loop workflow
  *
  * Architecture:
- * - The plugin registers 6 tools (config, validate, decision-log, context, review, triage)
+ * - The plugin registers 13 tools (config, validate, decision-log, context, review,
+ *   triage, fix, diff, rollback, checkpoint, status, history, prune)
  * - 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 6 tools to do real work (read config, run validation, log decisions, review, triage)
+ * - Subagents use the 13 tools to do real work (read config, run validation, log decisions,
+ *   review, triage, apply/rollback/fixing, checkpoint, status, history, prune)
  *
  * Tool invocation model:
  * - Workflow script CANNOT call tools directly (sandboxed vm, no Node API)
@@ -16,7 +18,7 @@
  *
  * Key files:
  * - src/index.ts      — Plugin entry: register tools + inject skill prompt
- * - src/tools/        — 6 tool implementations + meta-review/review engines
+ * - src/tools/        — 13 tool implementations + meta-review/review engines
  * - src/config-loader.ts — YAML config loading
  * - src/types.ts     — Shared types
  */
@@ -38,7 +40,7 @@ export const name = 'iterate-plugin'
 export const inject = ['tools', 'systemPrompt']
 
 export function apply(ctx: Context): void {
-  // 1. Register the 11 tools
+  // 1. Register the 13 tools
   registerConfigTool(ctx)
   registerValidateTool(ctx)
   registerDecisionLogTool(ctx)

package/src/review.ts

@@ -218,6 +218,8 @@ export function buildReviewReport(input: {
   maxReviewRounds: number
   rounds: ReviewRound[]
   knownIntentional?: KnownIntentional[]
+  /** Number of atomic fixes applied so far. Normal mode only; omitted in dry-run. */
+  fixedCount?: number
 }): ReviewReport {
   // 1. Filter known-intentional per round (before cross-round dedupe).
   const filteredRounds = input.rounds.map((r) => ({
@@ -246,6 +248,12 @@ export function buildReviewReport(input: {
     lastRound > 0 ? (findingsByRound[lastRound - 1] ?? 0) : 0
   const converged = filteredRounds.length > 0 && lastRoundCount === 0
 
+  // Attach the normal-mode fix count to the summary (dry-run leaves it absent).
+  const computed = summarize(sorted)
+  if (input.mode === 'normal' && typeof input.fixedCount === 'number' && Number.isInteger(input.fixedCount)) {
+    computed.fixedCount = input.fixedCount
+  }
+
   return {
     mode: input.mode,
     goal: input.goal,
@@ -264,7 +272,7 @@ export function buildReviewReport(input: {
             ? 'converged'
             : 'max_rounds_reached',
     },
-    summary: summarize(sorted),
+    summary: computed,
   }
 }
 

package/src/skill-prompt.ts

@@ -14,13 +14,15 @@ You have the iterate plugin installed, which registers these tools:
 - \`iterate_validate\` — run a whitelisted validation command
 - \`iterate_decision_log\` — append to the decision log, or read entries back for review
 - \`iterate_context\` — read SKILL.md / ITERATE.md project context
-- \`iterate_review\` — deterministic review engine: \`plan\` builds the review plan; \`aggregate\` dedupes/merges findings and computes convergence. Purely computational.
+- \`iterate_review\` — deterministic review engine: \`plan\` builds the review plan; \`aggregate\` dedupes/merges findings and computes convergence; \`meta-review\` audits a built report for internal consistency (counts, buckets, sorting, convergence math) and returns a final report with an \`approved\` / \`needs_revision\` verdict. Purely computational.
 - \`iterate_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
+- \`iterate_history\` — inspect the runtime state in detail: decision-log entries and applied fixes (optionally scoped to a round or a fixed file)
+- \`iterate_prune\` — remove stale runtime artifacts (\`.iterate/\` entries). Defaults to a read-only dry-run that reports what WOULD be removed; pass \`dryRun:false\` to actually prune.
 
 ### 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.
@@ -176,8 +178,10 @@ for (let r = startRound; r <= maxRounds; r++) {
   rounds.push(thisRound)
 
   // Deterministic dedupe / known_intentional filter / severity sort for this round.
+  // \`fixedCount\` is threaded into the report summary so the client dashboard can
+  // show a running "fixes applied" metric for normal mode.
   const agg = await agent(
-    'Call iterate_review({operation:"aggregate", mode:"normal", rounds:' + JSON.stringify([thisRound]) + ', knownIntentional:' + JSON.stringify(knownIntentional) + '}) and return the report JSON.',
+    'Call iterate_review({operation:"aggregate", mode:"normal", rounds:' + JSON.stringify([thisRound]) + ', knownIntentional:' + JSON.stringify(knownIntentional) + ', fixedCount:' + fixedCount + '}) and return the report JSON.',
     { label: 'review:aggregate:r' + r }
   )
   const findings = (agg && agg.report && agg.report.findings) ? agg.report.findings : thisRound.findings

package/src/tools/decision-log.ts

@@ -8,6 +8,36 @@ import type { DecisionLogEntry } from '../types.ts'
 const LOG_DIR = '.iterate'
 const LOG_FILE = 'decision-log.jsonl'
 
+/** All valid DecisionLogEntry `type` values (must stay in sync with Types). */
+const VALID_ENTRY_TYPES = new Set<DecisionLogEntry['type']>([
+  'round_start',
+  'review_result',
+  'atomic_fix',
+  'architectural_fix',
+  'revert',
+  'round_failed',
+  'validation',
+  'decision',
+  'report',
+])
+
+/**
+ * Validate a candidate (type, round, data) triple for an append operation.
+ * Returns an error string on failure, or null when the entry is well-formed.
+ */
+function validateEntryInput(type: unknown, round: unknown, data: unknown): string | null {
+  if (typeof type !== 'string' || !VALID_ENTRY_TYPES.has(type as DecisionLogEntry['type'])) {
+    return `type must be one of: ${[...VALID_ENTRY_TYPES].join(', ')}.`
+  }
+  if (typeof round !== 'number' || !Number.isInteger(round) || round < 1) {
+    return 'round must be a positive integer.'
+  }
+  if (data !== undefined && data !== null && typeof data !== 'object') {
+    return 'data must be an object (or omitted).'
+  }
+  return null
+}
+
 /**
  * Resolve the log file path, creating the directory if needed.
  */
@@ -81,13 +111,14 @@ export function registerDecisionLogTool(ctx: { tools: { register: (def: ReturnTy
           type: 'string',
           description:
             'Entry type (required for append): round_start, review_result, atomic_fix, ' +
-            'architectural_fix, revert, validation, decision, report.',
+            'architectural_fix, revert, round_failed, validation, decision, report.',
           enum: [
             'round_start',
             'review_result',
             'atomic_fix',
             'architectural_fix',
             'revert',
+            'round_failed',
             'validation',
             'decision',
             'report',
@@ -144,18 +175,24 @@ export function registerDecisionLogTool(ctx: { tools: { register: (def: ReturnTy
         }
 
         if (args.operation === 'append') {
-          if (!args.type || !args.round) {
+          const invalid = validateEntryInput(args.type, args.round, args.data)
+          if (invalid !== null) {
             return {
               operation: 'append',
-              error: 'type and round are required for append operation.',
+              error: invalid,
             }
           }
+          const type = args.type as DecisionLogEntry['type']
+          const round = args.round as number
+          const data = args.data === undefined || args.data === null
+            ? {}
+            : args.data as Record<string, unknown>
 
           const entry: DecisionLogEntry = {
             timestamp: new Date().toISOString(),
-            round: args.round,
-            type: args.type as DecisionLogEntry['type'],
-            data: (args.data as Record<string, unknown>) ?? {},
+            round,
+            type,
+            data,
           }
 
           const result = appendDecisionEntry(projectRoot, entry)

package/src/tools/review.ts

@@ -72,6 +72,12 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
             'For `meta-review`: the ReviewReport JSON (as returned by `aggregate`) to audit for ' +
             'internal consistency and produce the final review report.',
         },
+        fixedCount: {
+          type: 'integer',
+          description:
+            'For `aggregate` (normal mode only): number of atomic fixes applied so far. ' +
+            'Surfaces a running "fixes applied" metric on the report summary.',
+        },
         path: {
           type: 'string',
           description: 'Project root directory (default: current working directory).',
@@ -144,6 +150,7 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
             maxReviewRounds,
             rounds,
             knownIntentional: args.knownIntentional as KnownIntentional[] | undefined,
+            fixedCount: typeof args.fixedCount === 'number' ? args.fixedCount : undefined,
           })
           return { operation: 'aggregate', mode, report: report as unknown as JsonValue }
         }

package/src/types.ts

@@ -34,6 +34,7 @@ export interface DecisionLogEntry {
     | 'validation'
     | 'decision'
     | 'report'
+    | 'round_failed'
   data: Record<string, unknown>
 }
 
@@ -82,6 +83,8 @@ export interface ReviewReport {
     medium: number
     low: number
     byDimension: Record<string, number>
+    /** Number of atomic fixes applied so far (normal mode only; absent in dry-run). */
+    fixedCount?: number
   }
 }