iterate-plugin 3.3.1 → 3.4.1

package/src/skill-prompt.ts

@@ -143,9 +143,20 @@ for (let r = 1; r <= maxRounds; 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
+  // A round counts as "converged" ONLY when the aggregate accepted it
+  // (schema-valid) AND it genuinely found zero NEW findings. If reviewers all
+  // failed or their output stayed schema-invalid after retries, the round is
+  // INCONCLUSIVE — never report an empty-but-broken round as converged (an
+  // invalid/failed round must fail the run, not masquerade as a clean pass).
+  if (!schemaInvalid) {
+    const newCount =
+      agg && agg.report && agg.report.convergence
+        ? agg.report.convergence.findingsByRound[r - 1]
+        : thisRound.findings.length
+    if (newCount === 0) {
+      log('round ' + r + ' found 0 new findings — converged')
+      break
+    }
   }
 }
 
@@ -238,7 +249,7 @@ if (checkpoint) {
 
 phase('plan')
 const configRes = await agent(
-  'Call iterate_config({ validate: true }) and return the config JSON.',
+  'Call iterate_config({}) and return the config JSON.',
   Object.assign({ label: 'config:read' }, backend)
 )
 const cfg = (configRes && configRes.config) ? configRes.config : null
@@ -421,7 +432,7 @@ for (let r = startRound; r <= maxRounds; r++) {
     Object.assign({ label: 'checkpoint:save:r' + r }, backend)
   )
 
-  if (atomic.length === 0 && remaining.length === 0) {
+  if (atomic.length === 0 && remaining.length === 0 && !schemaInvalid) {
     log('round ' + r + ' found nothing to fix — converged')
     converged = true
     break

package/src/tools/checkpoint.ts

@@ -16,7 +16,10 @@ import { resolveProjectRootForExec } from '../config-loader.ts'
 import { checkpointPath, iterateDir, transcriptPath } from '../paths.ts'
 import { readRegistry } from './fix.ts'
 import { readDecisionEntries } from './decision-log.ts'
-import type { IterationCheckpoint, IterationStatus } from '../types.ts'
+import { readQualityGate } from './quality-store.ts'
+import { readExperienceBank } from './experience-store.ts'
+import { readDefenseEvents } from './defense-store.ts'
+import type { DefenseEventType, IterationCheckpoint, IterationStatus, QualityGateSnapshot } from '../types.ts'
 
 // ─── Pure helpers (exported for unit tests) ─────────────────────────────────
 
@@ -90,6 +93,12 @@ export function computeStatus(input: {
   taskMode?: 'code' | 'iterate' | null
   decisionEntries: { timestamp: string; type: string; round?: number; data?: Record<string, unknown> }[]
   fixRegistry: { rounds: { round: number; fixedCount: number; failedCount: number }[] }
+  /** v3.0: persisted quality-gate snapshot (optional; absent → omitted). */
+  qualityGate?: QualityGateSnapshot | null
+  /** v3.0: experience bank summary (optional; absent → omitted). */
+  experienceBank?: { totalEntries: number; totalHits: number } | null
+  /** v3.0: defense events summary (optional; absent → omitted). */
+  defenseEvents?: { totalEvents: number; counts: Record<DefenseEventType, number> } | null
 }): IterationStatus {
   const checkpoint = input.checkpoint
   const taskMode = input.taskMode ?? null
@@ -134,6 +143,12 @@ export function computeStatus(input: {
     resumeCount: checkpoint?.resumeCount ?? 0,
     checkpoint,
     lastUpdated,
+    // v3.0: quality command-center snapshots (present only when the caller
+    // supplied a real snapshot — the status never fabricates one that is not
+    // on disk, and never emits null for an absent optional field).
+    ...(input.qualityGate != null ? { qualityGate: input.qualityGate } : {}),
+    ...(input.experienceBank != null ? { experienceBank: input.experienceBank } : {}),
+    ...(input.defenseEvents != null ? { defenseEvents: input.defenseEvents } : {}),
   }
 }
 
@@ -148,14 +163,16 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
     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.',
+        'Save / load / resume / 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. ' +
+        '`resume` loads an existing checkpoint, bumps its resumeCount, and persists it back — ' +
+        'call it when continuing an interrupted run so the resume counter stays accurate.',
       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'],
+          description: '"save" to persist the current progress, "load" to read it back, "resume" to load + count a resumption, "clear" to remove it.',
+          enum: ['save', 'load', 'resume', '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).' },
@@ -194,6 +211,28 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
           return { operation: 'load', ok: true, checkpoint: checkpoint as unknown as JsonValue | null }
         }
 
+        if (args.operation === 'resume') {
+          const current = readCheckpoint(projectRoot)
+          if (!current) {
+            return { operation: 'resume', ok: false, error: 'no checkpoint to resume — run `save` first' }
+          }
+          const resumed: IterationCheckpoint = {
+            ...current,
+            resumeCount: (current.resumeCount ?? 0) + 1,
+            updatedAt: new Date().toISOString(),
+          }
+          try {
+            mkdirSync(iterateDir(projectRoot), { recursive: true })
+            const cpPath = checkpointPath(projectRoot)
+            const tmpPath = `${cpPath}.tmp-${Date.now()}`
+            writeFileSync(tmpPath, JSON.stringify(resumed, null, 2), 'utf-8')
+            renameSync(tmpPath, cpPath)
+          } catch (err) {
+            return { operation: 'resume', ok: false, error: `failed to persist resumed checkpoint: ${String(err)}` }
+          }
+          return { operation: 'resume', ok: true, checkpoint: resumed as unknown as JsonValue }
+        }
+
         if (args.operation === 'clear') {
           const existed = existsSync(checkpointPath(projectRoot))
           if (existed) {
@@ -239,7 +278,7 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
           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".' }
+        return { operation: args.operation, ok: false, error: 'unknown operation. Use "save", "load", "resume", or "clear".' }
       },
     }),
   )
@@ -280,6 +319,9 @@ export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<ty
             interrupted: { type: 'boolean', description: 'True when a checkpoint exists, meaning the previous run was interrupted before finishing.' },
             resumeCount: { type: 'integer', description: 'How many times the current checkpoint has already been resumed.' },
             lastUpdated: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+            qualityGate: { type: 'json', description: 'v3.0: persisted quality-gate snapshot (.iterate/quality-gate.json), when present.' },
+            experienceBank: { type: 'json', description: 'v3.0: experience bank summary (.iterate/experience.json), when present.' },
+            defenseEvents: { type: 'json', description: 'v3.0: defense events summary (.iterate/defense-events.json), when present.' },
             error: { type: 'string' },
           },
         },
@@ -302,11 +344,31 @@ export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<ty
         const resolved = resolveProjectRootForExec(exec, args.path)
         if (!resolved.ok) return { ok: false, error: resolved.reason }
         const projectRoot = resolved.root
+        // v3.0: surface the persisted quality command-center snapshots so a
+        // single `iterate_status` call reports the whole run state — the gate,
+        // the experience bank, and the defense event stream. Each read is
+        // defensive (missing/malformed files yield an empty snapshot), so the
+        // status never crashes on absent artifacts.
+        const qualityGate = readQualityGate(projectRoot)
+        const experienceBank = readExperienceBank(projectRoot)
+        const defenseEvents = readDefenseEvents(projectRoot)
         const status = computeStatus({
           checkpoint: readCheckpoint(projectRoot),
           taskMode: readTranscriptTaskMode(projectRoot),
           decisionEntries: readDecisionEntries(projectRoot),
           fixRegistry: readRegistry(projectRoot),
+          qualityGate:
+            qualityGate.dimensions.length > 0 || qualityGate.overallStatus === 'pass' || qualityGate.overallStatus === 'fail'
+              ? qualityGate
+              : null,
+          experienceBank: {
+            totalEntries: experienceBank.entries.length,
+            totalHits: experienceBank.totalHits ?? 0,
+          },
+          defenseEvents: {
+            totalEvents: defenseEvents.events.length,
+            counts: defenseEvents.counts,
+          },
         })
         return {
           ok: true,
@@ -322,6 +384,9 @@ export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<ty
           interrupted: status.interrupted,
           resumeCount: status.resumeCount,
           lastUpdated: status.lastUpdated ?? null,
+          qualityGate: status.qualityGate ? (status.qualityGate as unknown as JsonValue) : null,
+          experienceBank: status.experienceBank ? (status.experienceBank as unknown as JsonValue) : null,
+          defenseEvents: status.defenseEvents ? (status.defenseEvents as unknown as JsonValue) : null,
         }
       },
     }),

package/src/tools/defense-events.ts

@@ -55,6 +55,7 @@ function validateRecordInput(args: {
   defense?: unknown
   outcome?: unknown
   severity?: unknown
+  line?: unknown
 }): string[] {
   const errors: string[] = []
   if (typeof args.type !== 'string' || !EVENT_TYPES.includes(args.type as DefenseEventType)) {
@@ -72,6 +73,9 @@ function validateRecordInput(args: {
   if (typeof args.outcome !== 'string' || !args.outcome.trim()) {
     errors.push('outcome is required')
   }
+  if (args.line !== undefined && (typeof args.line !== 'number' || !Number.isInteger(args.line) || args.line < 0)) {
+    errors.push('line must be a non-negative integer when present')
+  }
   const severity = args.severity
   if (severity !== 'critical' && severity !== 'high' && severity !== 'medium' && severity !== 'low') {
     errors.push('severity must be one of critical, high, medium, low')

package/src/tools/defense-store.ts

@@ -44,14 +44,28 @@ function emptyStream(): DefenseEventStream {
   }
 }
 
-/** Read the defense events stream from disk. */
+/**
+ * Read the defense events stream from disk.
+ * Normalizes the persisted stream so a hand-edited / partial file can never
+ * produce NaN counts: `counts` is recomputed from the events when missing or
+ * malformed, and every type key is guaranteed present.
+ */
 export function readDefenseEvents(projectRoot: string): DefenseEventStream {
   const filePath = path.join(projectRoot, '.iterate', DEFENSE_EVENTS_FILE)
   try {
     const content = fs.readFileSync(filePath, 'utf-8')
-    const parsed = JSON.parse(content) as DefenseEventStream
+    const parsed = JSON.parse(content) as Partial<DefenseEventStream>
     if (parsed && Array.isArray(parsed.events)) {
-      return parsed
+      const events = parsed.events.filter(
+        (e): e is DefenseEvent =>
+          !!e && typeof e === 'object' && typeof (e as DefenseEvent).type === 'string',
+      )
+      const counts = computeCounts(events)
+      return {
+        events,
+        lastUpdated: typeof parsed.lastUpdated === 'string' ? parsed.lastUpdated : emptyStream().lastUpdated,
+        counts,
+      }
     }
   } catch {
     // File not found or invalid JSON
@@ -95,7 +109,10 @@ export function addDefenseEvent(
     ...event,
   }
 
-  const newCounts = { ...stream.counts }
+  // Always recompute from the events array instead of mutating a possibly
+  // stale/malformed persisted `counts` object — guarantees the stream counts
+  // can never drift from (or NaN out against) its events.
+  const newCounts = computeCounts(stream.events)
   bumpCount(newCounts, event.type)
 
   return {

package/src/tools/history.ts

@@ -130,7 +130,7 @@ export function registerHistoryTool(ctx: { tools: { register: (def: ReturnType<t
               ? `Fixes: ${fixes.totalFixed} applied · ${fixes.totalFailed} failed · across ${fixes.roundCount} round(s)`
               : 'Fixes: none',
             '',
-            ...log.map((e) => `[${e.timestamp}] r${e.round} ${e.type}: ${JSON.stringify(e.data ?? {})}`),
+            ...log.map((e) => `[${e.timestamp}] r${e.round ?? '?'} ${e.type}: ${JSON.stringify(e.data ?? {})}`),
           ]
           return [{ type: 'text', text: lines.join('\n') }]
         },

package/src/tools/quality-store.ts

@@ -31,14 +31,59 @@ function emptySnapshot(): QualityGateSnapshot {
   }
 }
 
-/** Read the quality gate snapshot from disk. */
+/**
+ * Read the quality gate snapshot from disk.
+ * Normalizes a hand-edited / partial file so readers and the tool's `render`
+ * never crash on missing arrays or non-numeric fields: `dimensions` is
+ * guaranteed to be an array and every numeric field degrades to 0.
+ */
 export function readQualityGate(projectRoot: string): QualityGateSnapshot {
   const filePath = path.join(projectRoot, '.iterate', QUALITY_GATE_FILE)
   try {
     const content = fs.readFileSync(filePath, 'utf-8')
-    const parsed = JSON.parse(content) as QualityGateSnapshot
+    const parsed = JSON.parse(content) as Partial<QualityGateSnapshot> | null
     if (parsed && typeof parsed === 'object') {
-      return parsed
+      const num = (v: unknown): number =>
+        typeof v === 'number' && Number.isFinite(v) ? v : 0
+      const status: QualityGateSnapshot['overallStatus'] =
+        parsed.overallStatus === 'pass' || parsed.overallStatus === 'fail' || parsed.overallStatus === 'pending'
+          ? parsed.overallStatus
+          : 'pending'
+      const dimensions = Array.isArray(parsed.dimensions)
+        ? (parsed.dimensions as unknown as Array<Record<string, unknown>>)
+            .filter((d): d is Record<string, unknown> => !!d && typeof d === 'object' && typeof d.dimension === 'string')
+            .map((d) => {
+              const dimStatus: QualityGateDimension['status'] =
+                d.status === 'pass' || d.status === 'fail' || d.status === 'warn' ? d.status : 'warn'
+              return {
+                dimension: d.dimension as string,
+                convergenceRate: num(d.convergenceRate),
+                findingsCount: num(d.findingsCount),
+                fixedCount: num(d.fixedCount),
+                score: num(d.score),
+                status: dimStatus,
+              }
+            })
+        : []
+      return {
+        timestamp: typeof parsed.timestamp === 'string' ? parsed.timestamp : emptySnapshot().timestamp,
+        overallStatus: status,
+        overallScore: num(parsed.overallScore),
+        dimensions,
+        verificationPassRate: num(parsed.verificationPassRate),
+        totalChecks: num(parsed.totalChecks),
+        passedChecks: num(parsed.passedChecks),
+        failedChecks: num(parsed.failedChecks),
+        totalFindings: num(parsed.totalFindings),
+        criticalCount: num(parsed.criticalCount),
+        highCount: num(parsed.highCount),
+        mediumCount: num(parsed.mediumCount),
+        lowCount: num(parsed.lowCount),
+        // Only carry an own failReason when it is a real string — an absent
+        // persisted reason must not surface as `failReason: undefined` (which
+        // deep-equals differently than the JSON round-trip of computeQualityGate).
+        ...(typeof parsed.failReason === 'string' ? { failReason: parsed.failReason } : {}),
+      }
     }
   } catch {
     // File not found or invalid JSON

package/src/transcript.ts

@@ -49,6 +49,10 @@ const MAX_FINDINGS_TOTAL = 2000
 /** Max timeline entries kept (newest wins). */
 const MAX_TIMELINE = 500
 
+/** Max applied-fix records kept (newest wins; bounded so a long run cannot
+ *  grow the manifest payload without limit). */
+const MAX_FIXES = 200
+
 /** Thresholds applied when reducing a string list under a cap. */
 function clampStringList(source: string[], cap: number): string[] {
   const out: string[] = []
@@ -317,6 +321,9 @@ export class ReviewTranscriptBuilder {
         typeof record.linesRemoved === 'number' ? Math.floor(record.linesRemoved) : 0,
       success: record.success !== false,
     })
+    if (this.fixes.length > MAX_FIXES) {
+      this.fixes.splice(0, this.fixes.length - MAX_FIXES)
+    }
     this.touch()
   }