iterate-plugin 3.5.2 → 3.5.4

package/src/skill-prompt.ts

@@ -95,10 +95,11 @@ for (let r = 1; r <= maxRounds; r++) {
   log('round ' + r + ' of ' + maxRounds + ' — finding NEW issues only')
   let agg = null
   let schemaInvalid = false
-  let retries = 0
+  let attempts = 0
   do {
+    attempts += 1
     // Schema validation retry: on the 2nd+ pass, nudge reviewers toward strict JSON.
-    const nudge = retries > 0
+    const nudge = attempts > 1
       ? '\\nSTRICT JSON REQUIRED: your previous output failed schema validation. Return ONLY a JSON object {"findings":[...]} where EVERY finding has dimension, file, line (non-negative integer; 0 = whole-file), severity (critical|high|medium|low), summary, failure_scenario, suggested_fix, is_atomic (boolean).'
       : ''
     const raw = await parallel(dims.map(dim => () => {
@@ -135,11 +136,15 @@ for (let r = 1; r <= maxRounds; r++) {
     schemaInvalid = agg && agg.schemaValidation && agg.schemaValidation.length > 0
       ? agg.schemaValidation[agg.schemaValidation.length - 1].valid === false
       : false
-    if (schemaInvalid && retries < 2) {
-      retries += 1
-      log('retry ' + retries + ': round ' + r + ' output failed schema validation — re-running reviewers with strict-JSON emphasis')
+    if (schemaInvalid && attempts < 3) {
+      log('retry ' + attempts + ': round ' + r + ' output failed schema validation — re-running reviewers with strict-JSON emphasis')
     }
-  } while (schemaInvalid && retries <= 2)
+  } while (schemaInvalid && attempts < 3)
+  if (schemaInvalid) {
+    // Bounded exit: never loop forever. Surface the failure so the run's
+    // final summary can explain WHY the round was inconclusive.
+    log('round ' + r + ' output STILL schema-invalid after 3 attempts — marking round inconclusive (NOT converged)')
+  }
   // 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
@@ -270,6 +275,7 @@ let fixedCount = (checkpoint && typeof checkpoint.fixedCount === 'number') ? che
 let converged = false
 let abortedByValidation = false
 let failedCommands = []
+let configErrors = []          // validation commands NOT in validation.commands (config gap, no rollback)
 const fixRecords = []        // observatory fix records collected round by round
 
 // Read any steering nudge intended for this run's reviewers.
@@ -289,10 +295,11 @@ for (let r = startRound; r <= maxRounds; r++) {
   )
   let agg = null
   let schemaInvalid = false
-  let retries = 0
+  let attempts = 0
   do {
+    attempts += 1
     // Schema validation retry: on the 2nd+ pass, nudge reviewers toward strict JSON.
-    const nudge = retries > 0
+    const nudge = attempts > 1
       ? '\\nSTRICT JSON REQUIRED: your previous output failed schema validation. Return ONLY a JSON object {"findings":[...]} where EVERY finding has dimension, file, line (non-negative integer; 0 = whole-file), severity (critical|high|medium|low), summary, failure_scenario, suggested_fix, is_atomic (boolean).'
       : ''
     const raw = await parallel(dims.map(dim => () => {
@@ -328,11 +335,15 @@ for (let r = startRound; r <= maxRounds; r++) {
     schemaInvalid = agg && agg.schemaValidation && agg.schemaValidation.length > 0
       ? agg.schemaValidation[agg.schemaValidation.length - 1].valid === false
       : false
-    if (schemaInvalid && retries < 2) {
-      retries += 1
-      log('retry ' + retries + ': round ' + r + ' output failed schema validation — re-running reviewers with strict-JSON emphasis')
+    if (schemaInvalid && attempts < 3) {
+      log('retry ' + attempts + ': round ' + r + ' output failed schema validation — re-running reviewers with strict-JSON emphasis')
     }
-  } while (schemaInvalid && retries <= 2)
+  } while (schemaInvalid && attempts < 3)
+  if (schemaInvalid) {
+    // Bounded exit: never loop forever. Surface the failure so the run's
+    // final summary can explain WHY the round was inconclusive.
+    log('round ' + r + ' output STILL schema-invalid after 3 attempts — marking round inconclusive (NOT converged)')
+  }
   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)
@@ -387,18 +398,33 @@ for (let r = startRound; r <= maxRounds; r++) {
     if (seenKeys.indexOf(key) < 0) { architectural.push(f); seenKeys.push(key) }
   }
 
-  // Validate every configured command; on ANY failure roll back this round's fixes.
+  // Validate every configured command; on ANY *executed* failure roll back this
+  // round's fixes. iterate_validate returns \`allowed:false\` + \`rejectReason\`
+  // when a command is NOT in validation.commands (a config gap, NOT a code
+  // failure) — those abort the run WITHOUT rolling back (the code changes are
+  // fine; the trust list just needs fixing).
   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.',
+    '(one tool call per command). Return all results as {command, exitCode, allowed, rejectReason} entries — include \`allowed\` and \`rejectReason\` exactly as returned by iterate_validate (allowed:false means the command is not in validation.commands).',
     Object.assign({ 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'] } }
+        results: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { command: { type: 'string' }, exitCode: { type: 'integer' }, allowed: { type: 'boolean' }, rejectReason: { type: 'string' } }, required: ['command', 'exitCode'] } }
       },
       required: ['results'] } }, backend)
   )
-  failedCommands = (valRes && Array.isArray(valRes.results)) ? valRes.results.filter(v => v.exitCode !== 0).map(v => v.command) : []
+  const valResults = (valRes && Array.isArray(valRes.results)) ? valRes.results : []
+  configErrors = valResults.filter(v => v.allowed === false).map(v => v.rejectReason || (v.command + ' was rejected'))
+  failedCommands = valResults.filter(v => !(v.allowed === false) && v.exitCode !== 0).map(v => v.command)
+  if (configErrors.length > 0) {
+    log('round ' + r + ' validation CONFIG error (not in validation.commands): ' + configErrors.join(' | ') + ' — aborting WITHOUT rollback (code changes are kept; the command trust list needs updating)')
+    abortedByValidation = true
+    await agent(
+      'Call iterate_decision_log({operation:"append", type:"round_failed", round:' + r + ', data:{configErrors:' + JSON.stringify(configErrors) + ', rolledBack:0, reason:"command not in validation.commands"}})',
+      Object.assign({ label: 'log:configError:r' + r }, backend)
+    )
+    break
+  }
   if (failedCommands.length > 0) {
     log('round ' + r + ' validation FAILED on: ' + failedCommands.join(', ') + ' — rolling back this round')
     abortedByValidation = true
@@ -459,17 +485,23 @@ if (!abortedByValidation) {
 }
 // Persist the run's observatory transcript (threads, trend, fixes, checkpoint)
 // so the client observatory panel reflects the run. Writes ONLY .iterate/transcript.json.
-const obsCheckpoint = abortedByValidation ? null : {
-  mode: 'normal',
-  round: rounds.length,
-  maxRounds: maxRounds,
-  fixedCount: fixedCount,
-  resumeCount: effectiveResumeCount,
-}
-await agent(
-  'Call iterate_transcript({operation:"capture", mode:"normal", goal:' + JSON.stringify(plan.goal) + ', maxRounds:' + maxRounds + ', roundsExecuted:' + rounds.length + ', findingsByRound:' + JSON.stringify(rounds.map(rr => (rr.findings && rr.findings.length) ? rr.findings.length : 0)) + ', fixes:' + JSON.stringify(fixRecords) + ', checkpoint:' + JSON.stringify(obsCheckpoint) + ', rounds:' + JSON.stringify(rounds.map(rr => ({ round: rr.round, findings: rr.findings, readFiles: rr.readFiles }))) + '}). Return {operation:"ok"}.',
-  { label: 'transcript:capture' }
-)
+// The checkpoint survives on disk for aborted runs (that is how resumption
+  // works), so the transcript must mirror that reality — a null checkpoint here
+  // would hide the very thing F5 is meant to resume. Reflect what is on disk.
+  const obsCheckpoint = {
+    mode: 'normal',
+    round: rounds.length,
+    maxRounds: maxRounds,
+    fixedCount: fixedCount,
+    resumeCount: effectiveResumeCount,
+  }
+  const stopReason = abortedByValidation
+    ? (configErrors.length > 0 ? 'aborted_by_config' : 'aborted_by_validation')
+    : (converged ? 'converged' : 'max_rounds_reached')
+  await agent(
+    'Call iterate_transcript({operation:"capture", mode:"normal", goal:' + JSON.stringify(plan.goal) + ', maxRounds:' + maxRounds + ', roundsExecuted:' + rounds.length + ', findingsByRound:' + JSON.stringify(rounds.map(rr => (rr.findings && rr.findings.length) ? rr.findings.length : 0)) + ', stoppedReason:"' + stopReason + '", fixes:' + JSON.stringify(fixRecords) + ', checkpoint:' + JSON.stringify(obsCheckpoint) + ', rounds:' + JSON.stringify(rounds.map(rr => ({ round: rr.round, findings: rr.findings, readFiles: rr.readFiles }))) + '}). Return {operation:"ok"}.',
+    { label: 'transcript:capture' }
+  )
 return {
   mode: 'normal',
   goal: plan.goal,
@@ -478,6 +510,8 @@ return {
   converged: converged,
   abortedByValidation: abortedByValidation,
   failedCommands: failedCommands,
+  configErrors: configErrors,
+  stoppedReason: stopReason,
   findingsFixed: fixedCount,
   remainingArchitecturalCount: architectural.length,
   remainingArchitectural: architectural,
@@ -495,10 +529,10 @@ return {
 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.
-- **Schema validation & retry**: when \`reviewer.output_schema_validation\` is on (default), retry the round's reviewers up to 2 times when \`aggregate\` reports \`schemaValidation\` valid=false for it, then re-aggregate. Never forward schema-invalid findings into \`iterate_fix\`.
+- **Schema validation & retry**: when \`reviewer.output_schema_validation\` is on (default), retry the round's reviewers up to 2 times (3 attempts total) when \`aggregate\` reports \`schemaValidation\` valid=false for it, then re-aggregate. Never forward schema-invalid findings into \`iterate_fix\`. If the output is still schema-invalid after the 3rd attempt, mark the round inconclusive (never report it as a clean convergence).
 - 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).
+- **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). EXCEPTION: \`iterate_validate\` returning \`allowed:false\` means the command is simply not in \`validation.commands\` — a config gap, not broken code. In that case abort WITHOUT rolling back the round's fixes and surface the missing command + file so the user can fix the trust list.
 - **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.

package/src/tools/checkpoint.ts

@@ -24,16 +24,41 @@ import type { DefenseEventType, IterationCheckpoint, IterationStatus, QualityGat
 
 // ─── Pure helpers (exported for unit tests) ─────────────────────────────────
 
+/** Max findings persisted in a checkpoint (a model-authored findings payload is
+ *  bounded, mirroring MAX_FIX_CONTENT_CHARS for fix content). */
+export const MAX_CHECKPOINT_FINDINGS = 1000
+
 /** Read the current 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
+    const parsed = JSON.parse(readFileSync(file, 'utf-8')) as Partial<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
+    // Strict round gate: non-numeric (incl. NaN — `NaN <= 0` is false and
+    // `NaN < 0` also false) round values must not survive into the status.
+    const round =
+      typeof parsed.round === 'number' && Number.isFinite(parsed.round)
+        ? Math.floor(parsed.round)
+        : null
+    if (round === null || round < 0) return null
+    const num = (v: unknown, fallback: number): number =>
+      typeof v === 'number' && Number.isFinite(v) ? v : fallback
+    // Normalize every field so a hand-edited/corrupt checkpoint (string
+    // maxRounds, missing fixedCount, …) can never leak a non-numeric value
+    // into the status output or crash a consumer.
+    return {
+      mode: parsed.mode,
+      round,
+      maxRounds: num(parsed.maxRounds, round),
+      fixedCount: num(parsed.fixedCount, 0),
+      architecturalCount: num(parsed.architecturalCount, 0),
+      resumeCount: num(parsed.resumeCount, 0),
+      findings: Array.isArray(parsed.findings) ? (parsed.findings as IterationCheckpoint['findings']) : [],
+      startedAt: typeof parsed.startedAt === 'string' ? parsed.startedAt : new Date().toISOString(),
+      updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
+    }
   } catch {
     return null
   }
@@ -82,6 +107,17 @@ export function validateCheckpoint(input: {
   ) {
     return 'resumeCount must be a non-negative integer'
   }
+  // A round that claims to be past the configured cap is an inconsistent save —
+  // the status would render `Round X / Y` with X > Y, which is never legitimate
+  // for a resumed run (resume continues AT the checkpoint, it does not exceed
+  // the cap).
+  if (
+    typeof input.round === 'number' &&
+    typeof input.maxRounds === 'number' &&
+    input.round > input.maxRounds
+  ) {
+    return 'round must not exceed maxRounds'
+  }
   return null
 }
 
@@ -118,8 +154,11 @@ export function computeStatus(input: {
   }
 
   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)
+  // Coerce the registry's per-round counts defensively: a hand-edited registry
+  // round missing fixedCount/failedCount would otherwise feed NaN into the
+  // status integer fields.
+  const registryFixed = registry.rounds.reduce((sum, r) => sum + (Number(r.fixedCount) || 0), 0)
+  const failedCount = registry.rounds.reduce((sum, r) => sum + (Number(r.failedCount) || 0), 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.
@@ -258,7 +297,7 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
             fixedCount: args.fixedCount as number,
             architecturalCount: args.architecturalCount as number,
             resumeCount: (typeof args.resumeCount === 'number' ? args.resumeCount : 0),
-            findings: (Array.isArray(args.findings) ? args.findings : []) as unknown as IterationCheckpoint['findings'],
+            findings: (Array.isArray(args.findings) ? args.findings.slice(0, MAX_CHECKPOINT_FINDINGS) : []) as unknown as IterationCheckpoint['findings'],
             startedAt: readCheckpoint(projectRoot)?.startedAt ?? new Date().toISOString(),
             updatedAt: new Date().toISOString(),
           }

package/src/tools/config.ts

@@ -1,7 +1,8 @@
 import { join } from 'node:path'
+import { existsSync } from 'node:fs'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
-import { loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from '../config-loader.ts'
+import { defaultConfig, loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from '../config-loader.ts'
 import {
   applyConfigUpdates,
   readRawConfig,
@@ -106,7 +107,15 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
           }
           let base: Record<string, unknown>
           try {
-            base = readRawConfig(join(projectRoot, 'iterate.config.yaml'))
+            // Partial updates must be mergeable on a FRESH project (no config
+            // file yet): otherwise `{max_rounds: 5}` alone fails schema
+            // validation with a misleading "missing goal". Merge against the
+            // built-in defaults when there is no file to read, so the written
+            // config captures the effective config (defaults + update) and the
+            // documented "write a partial update" contract works out of the box.
+            base = existsSync(join(projectRoot, 'iterate.config.yaml'))
+              ? readRawConfig(join(projectRoot, 'iterate.config.yaml'))
+              : (defaultConfig() as unknown as Record<string, unknown>)
           } catch (err) {
             return { operation: 'write', ok: false, found: false, error: `failed to read config: ${String(err)}` }
           }

package/src/tools/context.ts

@@ -336,7 +336,11 @@ export function registerContextTool(ctx: { tools: { register: (def: ReturnType<t
               // skillDir point at arbitrary filesystem locations (e.g. /etc)
               // whose contents would be injected wholesale into the context.
               if (isAllowedSkillDir(args.skillDir, [projectRoot, PLUGIN_SRC_DIR])) {
-                candidates.push(resolve(args.skillDir))
+                // Read from the REAL (symlink-resolved) path that was actually
+                // validated — never the raw path. Validating one path and then
+                // reading through a different (swappable) symlink would leave a
+                // check-vs-read TOCTOU gap; using the realpath here closes it.
+                candidates.push(realpathSync(resolve(args.skillDir)))
               }
             } catch {
               // unreadable/invalid skillDir — skip it

package/src/tools/defense-events.ts

@@ -12,7 +12,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec, loadEffectiveConfig } from '../config-loader.ts'
-import { readDefenseEvents, writeDefenseEvents, addDefenseEvent } from './defense-store.ts'
+import { readDefenseEvents, writeDefenseEvents, addDefenseEvent, clearDefenseEvents } from './defense-store.ts'
 import type { DefenseEvent, DefenseEventType } from '../types.ts'
 
 const DEFAULT_LIMIT = 50
@@ -91,20 +91,26 @@ export function registerDefenseEventsTool(ctx: { tools: { register: (def: Return
   ctx.tools.register(
     defineTool({
       name: 'iterate_defense_events',
-      // List/counts never write; only `record` persists an event → read shapes
-      // join a parallel dispatch group.
-      isConcurrencySafe: (args) => (args as { operation?: unknown }).operation !== 'record',
+      // List/counts never write; `record` persists an event and `clear` removes
+      // the persisted stream, so only the read shapes may join a parallel
+      // dispatch group.
+      isConcurrencySafe: (args) => {
+        const op = (args as { operation?: unknown }).operation
+        return op !== 'record' && op !== 'clear'
+      },
       description:
-        'Query or record defense events: precondition failures, rollbacks, invariant violations, ' +
+        'Query, record, or clear defense events: precondition failures, rollbacks, invariant violations, ' +
         'and assumption falsifications. ' +
         'List/counts return events with descriptions, outcomes, and summary counts; ' +
-        '"record" persists a new event to .iterate/defense-events.json. ' +
+        '"record" persists a new event to .iterate/defense-events.json; ' +
+        '"clear" resets the persisted event stream (use it to start a fresh iteration without stale ' +
+        'defense data). ' +
         'Use it to review defensive actions taken, or to log one when a defense fires.',
       parameters: {
         operation: {
           type: 'string',
-          description: 'Operation: list (browse all), counts (summary by type), record (log a new event). Default: list.',
-          enum: ['list', 'counts', 'record'],
+          description: 'Operation: list (browse all), counts (summary by type), record (log a new event), clear (reset the stream). Default: list.',
+          enum: ['list', 'counts', 'record', 'clear'],
         },
         type: {
           type: 'string',
@@ -162,6 +168,7 @@ export function registerDefenseEventsTool(ctx: { tools: { register: (def: Return
             kind: { type: 'string' },
             operation: { type: 'string' },
             count: { type: 'integer' },
+            counted: { type: 'boolean', description: 'clear only: true when a persisted stream was removed.' },
             events: { type: 'json' },
             counts: { type: 'json' },
             event: { type: 'json' },
@@ -174,6 +181,17 @@ export function registerDefenseEventsTool(ctx: { tools: { register: (def: Return
           if (!value.ok) return [{ type: 'text', text: `defense events query failed: ${value.error}` }]
           const language: 'zh' | 'en' = value.language === 'zh' ? 'zh' : 'en'
 
+          if (value.operation === 'clear') {
+            // Fresh stream: counts are all zero and the event list is empty.
+            return [{ type: 'text', text: [
+              value.counted === true
+                ? 'Defense event stream cleared — a fresh iteration starts with an empty stream.'
+                : 'No persisted defense event stream to clear.',
+              'Defense Event Summary:',
+              ...EVENT_TYPES.map((type) => `  ${labelFor(type, language)}: 0`),
+            ].join('\n') }]
+          }
+
           if (value.operation === 'counts' && value.counts) {
             const counts = value.counts as Record<DefenseEventType, number>
             const lines = [
@@ -220,12 +238,35 @@ export function registerDefenseEventsTool(ctx: { tools: { register: (def: Return
         if (!resolved.ok) return { ok: false, kind: 'defense_events', error: resolved.reason }
         const projectRoot = resolved.root
 
-        const configLang = loadEffectiveConfig(projectRoot).config.language
+        // A hand-edited `language` value outside zh/en must not leak out of the
+        // declared 'zh' | 'en' enum (labelFor would return undefined for it) —
+        // normalize any non-'zh' config value to 'en'.
+        const rawConfigLang = loadEffectiveConfig(projectRoot).config.language
+        const configLang: 'zh' | 'en' = rawConfigLang === 'zh' ? 'zh' : 'en'
         const language: 'zh' | 'en' = args.language === 'zh' || args.language === 'en' ? args.language : configLang
 
         const operation = typeof args.operation === 'string' ? args.operation : 'list'
         const limit = clampLimit(args.limit as number | undefined)
 
+        if (operation === 'clear') {
+          // Reset the persisted event stream so a fresh iteration does not carry
+          // stale defensive data (mirrors iterate_quality_gate clear / clearQualityGate).
+          const result = clearDefenseEvents(projectRoot)
+          if (!result.ok) {
+            return { ok: false, kind: 'defense_events', operation: 'clear', error: result.error }
+          }
+          const empty = readDefenseEvents(projectRoot)
+          return {
+            ok: true,
+            kind: 'defense_events',
+            operation: 'clear',
+            counted: result.existed,
+            language,
+            counts: empty.counts as unknown as JsonValue,
+            events: empty.events as unknown as JsonValue,
+          }
+        }
+
         if (operation === 'record') {
           const errors = validateRecordInput(args)
           if (errors.length > 0) {

package/src/tools/defense-store.ts

@@ -9,6 +9,7 @@ import * as fs from 'node:fs'
 import * as path from 'node:path'
 import { iterateDir } from '../paths.ts'
 import { writeJsonAtomic } from '../atomic-fs.ts'
+import { hashString } from './fix.ts'
 import type { DefenseEvent, DefenseEventStream, DefenseEventType } from '../types.ts'
 
 const DEFENSE_EVENTS_FILE = 'defense-events.json'
@@ -46,11 +47,45 @@ function emptyStream(): DefenseEventStream {
   }
 }
 
+/** Valid severity values (kept in sync with DefenseEvent). */
+const VALID_SEVERITIES: ReadonlySet<string> = new Set(['critical', 'high', 'medium', 'low'])
+
+/**
+ * Normalize one persisted event. Hand-edited files can carry events missing
+ * `timestamp`/`round`/`description`/`defense`/`outcome`/`severity` — readers
+ * (list sort by timestamp, render label selection) must never crash or emit
+ * NaN for those. Returns null when the entry is not an object or has no usable
+ * `type`; otherwise fills every required field with a safe default. An event
+ * missing its `id` gets a DETERMINISTIC id derived from its content and
+ * position (never a random one) so a read→write cycle cannot silently churn
+ * ids on every mutation.
+ */
+function normalizeEvent(raw: unknown, index: number): DefenseEvent | null {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const e = raw as Record<string, unknown>
+  if (typeof e.type !== 'string' || !VALID_EVENT_TYPES.has(e.type as DefenseEventType)) return null
+  const derivedId = `def-${hashString(`${index}|${String(e.timestamp ?? '')}|${e.type}|${String(e.description ?? '')}|${String(e.defense ?? '')}`)}`
+  return {
+    id: typeof e.id === 'string' && e.id ? e.id : derivedId,
+    timestamp: typeof e.timestamp === 'string' && e.timestamp ? e.timestamp : new Date().toISOString(),
+    round: typeof e.round === 'number' && Number.isFinite(e.round) ? Math.floor(e.round) : 0,
+    type: e.type as DefenseEventType,
+    description: typeof e.description === 'string' ? e.description : '',
+    defense: typeof e.defense === 'string' ? e.defense : '',
+    outcome: typeof e.outcome === 'string' ? e.outcome : '',
+    ...(typeof e.file === 'string' && e.file.length > 0 ? { file: e.file } : {}),
+    ...(typeof e.line === 'number' && Number.isFinite(e.line) && e.line >= 0 ? { line: e.line } : {}),
+    severity: VALID_SEVERITIES.has(String(e.severity)) ? (e.severity as DefenseEvent['severity']) : 'low',
+  }
+}
+
 /**
  * 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.
+ * malformed, every type key is guaranteed present, and every surviving event is
+ * shape-normalized so consumers (timestamp sort, render label selection) cannot
+ * throw on missing fields.
  */
 export function readDefenseEvents(projectRoot: string): DefenseEventStream {
   const filePath = path.join(projectRoot, '.iterate', DEFENSE_EVENTS_FILE)
@@ -58,10 +93,9 @@ export function readDefenseEvents(projectRoot: string): DefenseEventStream {
     const content = fs.readFileSync(filePath, 'utf-8')
     const parsed = JSON.parse(content) as Partial<DefenseEventStream>
     if (parsed && Array.isArray(parsed.events)) {
-      const events = parsed.events.filter(
-        (e): e is DefenseEvent =>
-          !!e && typeof e === 'object' && typeof (e as DefenseEvent).type === 'string',
-      )
+      const events = parsed.events
+        .map((raw, i) => normalizeEvent(raw, i))
+        .filter((e): e is DefenseEvent => e !== null)
       const counts = computeCounts(events)
       return {
         events,
@@ -101,16 +135,38 @@ export function writeDefenseEvents(
   return { ok: true }
 }
 
+/**
+ * Clear the persisted defense-event stream (`.iterate/defense-events.json`).
+ * Mirrors `clearQualityGate` in quality-store.ts: a stale event stream from a
+ * previous iteration must be resettable before a fresh run. Returns whether a
+ * file existed and was removed, or a structured error when removal fails.
+ */
+export function clearDefenseEvents(
+  projectRoot: string,
+): { ok: true; existed: boolean } | { ok: false; error: string } {
+  const filePath = path.join(iterateDir(projectRoot), DEFENSE_EVENTS_FILE)
+  const existed = fs.existsSync(filePath)
+  if (!existed) return { ok: true, existed: false }
+  try {
+    fs.rmSync(filePath, { force: true })
+  } catch (err) {
+    return { ok: false, error: `unable to remove ${filePath}: ${String(err)}` }
+  }
+  return { ok: true, existed: true }
+}
+
 /** Add a defense event to the stream. */
 export function addDefenseEvent(
   stream: DefenseEventStream,
   event: Omit<DefenseEvent, 'id' | 'timestamp'>
 ): DefenseEventStream {
-  const id = `def-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  // Spread the caller-shaped event FIRST so the store-generated `id` and
+  // `timestamp` always win — a caller-supplied id/timestamp must never
+  // override the stream's own identity fields.
   const newEvent: DefenseEvent = {
-    id,
-    timestamp: new Date().toISOString(),
     ...event,
+    id: `def-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    timestamp: new Date().toISOString(),
   }
 
   // Always recompute from the events array instead of mutating a possibly

package/src/tools/experience-bank.ts

@@ -72,9 +72,12 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
   ctx.tools.register(
     defineTool({
       name: 'iterate_experience',
-      // List/search/get never write; only `add` upserts the bank → read shapes
-      // join a parallel dispatch group.
-      isConcurrencySafe: (args) => (args as { operation?: unknown }).operation !== 'add',
+      // List/search/get never write; `add` upserts the bank and `remove`
+      // rewrites it → only the read shapes may join a parallel dispatch group.
+      isConcurrencySafe: (args) => {
+        const op = (args as { operation?: unknown }).operation
+        return op !== 'add' && op !== 'remove'
+      },
       description:
         'Query or extend the experience bank: browse/search historical fixes and patterns, ' +
         'or record a new verified fix (operation:"add"). ' +
@@ -151,8 +154,8 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
               `Dimension: ${entry.dimension}`,
               `Description: ${entry.description}`,
               `Fix: ${entry.verifiedFix}`,
-              `Files: ${entry.files.join(', ')}`,
-              `Tags: ${entry.tags.join(', ')}`,
+              `Files: ${Array.isArray(entry.files) ? entry.files.join(', ') : ''}`,
+              `Tags: ${Array.isArray(entry.tags) ? entry.tags.join(', ') : ''}`,
             ].join('\n') }]
           }
           if (value.operation === 'remove') {
@@ -165,9 +168,9 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
               `Pattern: ${entry.pattern}`,
               `Description: ${entry.description}`,
               `Fix: ${entry.verifiedFix}`,
-              `Files: ${entry.files.join(', ')}`,
+              `Files: ${Array.isArray(entry.files) ? entry.files.join(', ') : ''}`,
               `Hits: ${entry.hitCount}`,
-              `Tags: ${entry.tags.join(', ')}`,
+              `Tags: ${Array.isArray(entry.tags) ? entry.tags.join(', ') : ''}`,
             ].join('\n') }]
           }
           const entries = (value.entries as unknown as ExperienceEntry[] | undefined) ?? []
@@ -264,7 +267,7 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
             operation: 'get',
             count: 1,
             entry: entry as unknown as JsonValue,
-            totalHits: bank.totalHits,
+            totalHits: bank.totalHits ?? 0,
           }
         }
 
@@ -280,7 +283,7 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
             operation: 'search',
             count: entries.length,
             entries: entries as unknown as JsonValue,
-            totalHits: bank.totalHits,
+            totalHits: bank.totalHits ?? 0,
           }
         }
 
@@ -290,7 +293,7 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
           entries = entries.filter((e) => e.dimension === args.dimension)
         }
         if (Array.isArray(args.tags) && args.tags.length > 0) {
-          entries = entries.filter((e) => args.tags!.every((t: string) => e.tags.includes(t)))
+          entries = entries.filter((e) => args.tags!.every((t: string) => Array.isArray(e.tags) && e.tags.includes(t)))
         }
 
         return {
@@ -299,7 +302,7 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
           operation: 'list',
           count: Math.min(entries.length, limit),
           entries: entries.slice(0, limit) as unknown as JsonValue,
-          totalHits: bank.totalHits,
+          totalHits: bank.totalHits ?? 0,
         }
       },
     }),