iterate-plugin 3.5.2 → 3.5.4

package/src/tools/experience-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 { ExperienceBank, ExperienceEntry } from '../types.ts'
 
 const EXPERIENCE_FILE = 'experience.json'
@@ -22,14 +23,65 @@ function emptyBank(): ExperienceBank {
   }
 }
 
+/** Valid severity values (kept in sync with ExperienceEntry). */
+const VALID_SEVERITIES: ReadonlySet<string> = new Set(['critical', 'high', 'medium', 'low'])
+
+/** String array guard for fields that must be arrays (`files`, `tags`). */
+function stringArray(v: unknown): string[] {
+  if (!Array.isArray(v)) return []
+  return v.filter((x): x is string => typeof x === 'string')
+}
+
+/**
+ * Normalize one persisted experience entry. A hand-edited bank entry can be
+ * missing `files`/`tags` arrays (or `hitCount`) — consumers rendering/searching
+ * entries (`render` `.join(', ')`, `searchExperienceEntries` spread) must never
+ * throw or emit NaN. Returns null for non-object entries; every required field
+ * gets a safe default.
+ */
+function normalizeEntry(raw: unknown, index: number): ExperienceEntry | null {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const e = raw as Record<string, unknown>
+  const pattern = typeof e.pattern === 'string' ? e.pattern : ''
+  const dimension = typeof e.dimension === 'string' ? e.dimension : ''
+  // Deterministic id (content + position based) so a read→write cycle never
+  // churns random ids on entries that were hand-edited without one.
+  const derivedId = `exp-${hashString(`${index}|${pattern}|${dimension}`)}`
+  const id = typeof e.id === 'string' && e.id ? e.id : derivedId
+  if (!pattern && !dimension) return null
+  const hitCount = typeof e.hitCount === 'number' && Number.isFinite(e.hitCount) ? e.hitCount : 0
+  return {
+    id,
+    timestamp: typeof e.timestamp === 'string' ? e.timestamp : new Date().toISOString(),
+    dimension,
+    pattern,
+    description: typeof e.description === 'string' ? e.description : '',
+    verifiedFix: typeof e.verifiedFix === 'string' ? e.verifiedFix : '',
+    findingSummary: typeof e.findingSummary === 'string' ? e.findingSummary : '',
+    files: stringArray(e.files),
+    hitCount,
+    ...(typeof e.lastHitAt === 'string' ? { lastHitAt: e.lastHitAt } : {}),
+    tags: stringArray(e.tags),
+    severity: VALID_SEVERITIES.has(String(e.severity)) ? (e.severity as ExperienceEntry['severity']) : 'low',
+  }
+}
+
 /** Read the experience bank from disk. Returns empty bank if not found. */
 export function readExperienceBank(projectRoot: string): ExperienceBank {
   const filePath = path.join(projectRoot, '.iterate', EXPERIENCE_FILE)
   try {
     const content = fs.readFileSync(filePath, 'utf-8')
-    const parsed = JSON.parse(content) as ExperienceBank
+    const parsed = JSON.parse(content) as Partial<ExperienceBank>
     if (parsed && Array.isArray(parsed.entries)) {
-      return parsed
+      const entries = parsed.entries
+        .map((raw, i) => normalizeEntry(raw, i))
+        .filter((e): e is ExperienceEntry => e !== null)
+      return {
+        entries,
+        lastUpdated: typeof parsed.lastUpdated === 'string' ? parsed.lastUpdated : emptyBank().lastUpdated,
+        totalHits:
+          typeof parsed.totalHits === 'number' && Number.isFinite(parsed.totalHits) ? parsed.totalHits : 0,
+      }
     }
   } catch {
     // File not found or invalid JSON
@@ -72,6 +124,9 @@ export function searchExperienceEntries(
   const lowerQuery = query.toLowerCase()
 
   return entries.filter((entry) => {
+    if (!entry || typeof entry !== 'object') return false
+    const rawEntry = entry as unknown as Record<string, unknown>
+    const tags = stringArray(rawEntry.tags)
     // Dimension filter
     if (opts.dimension && entry.dimension !== opts.dimension) {
       return false
@@ -79,22 +134,24 @@ export function searchExperienceEntries(
 
     // Tags filter (AND logic)
     if (opts.tags && opts.tags.length > 0) {
-      if (!opts.tags.every((t) => entry.tags.includes(t))) {
+      if (!opts.tags.every((t) => tags.includes(t))) {
         return false
       }
     }
 
-    // Text search across multiple fields
-    if (query) {
-      const searchableText = [
-        entry.pattern,
-        entry.description,
-        entry.verifiedFix,
-        entry.findingSummary,
-        entry.dimension,
-        ...entry.files,
-        ...entry.tags,
-      ].join(' ').toLowerCase()
+    // Text search across multiple fields. Guards against a hand-edited bank entry
+  // whose `files`/`tags` are missing or non-array (the spread below would
+  // otherwise throw a TypeError on a non-iterable).
+  if (query) {
+    const searchableText = [
+      entry.pattern,
+      entry.description,
+      entry.verifiedFix,
+      entry.findingSummary,
+      entry.dimension,
+      ...stringArray(entry.files),
+      ...stringArray(entry.tags),
+    ].join(' ').toLowerCase()
 
       if (!searchableText.includes(lowerQuery)) {
         return false
@@ -114,8 +171,11 @@ export type ExperienceEntryInput = Omit<
 /**
  * Add or update an experience entry.
  *
- * An entry with an `id` that already exists, OR a new entry whose
- * `pattern`+`dimension` pair matches an existing entry, is treated as a HIT:
+ * An entry with an `id` that already exists is treated as an UPDATE + HIT:
+ * the caller-supplied fields replace the stored ones and the hitCount is
+ * incremented (lastHitAt refreshed) — this fulfills the documented
+ * "update a specific entry via add" contract. A NEW entry whose
+ * `pattern`+`dimension` pair matches an existing entry is treated as a HIT:
  * the matching entry's hitCount is incremented (lastHitAt refreshed) so
  * repeated encounters of the same pattern do not create duplicates. Otherwise
  * a fresh entry is appended with hitCount 1. Never mutates the input bank.
@@ -133,11 +193,14 @@ export function upsertExperience(
     : bank.entries.find((e) => e.pattern === entry.pattern && e.dimension === entry.dimension)
 
   if (existing) {
-    const updated: ExperienceEntry = {
-      ...existing,
-      hitCount: (existing.hitCount ?? 0) + 1,
-      lastHitAt: lastUpdated,
-    }
+    // Explicit-id updates REPLACE the editable fields (fulfilling the
+    // documented "update a specific entry via add" contract); a pattern+
+    // dimension HIT only bumps the hit metadata so a repeat encounter never
+    // overwrites the curated entry.
+    const byId = typeof entry.id === 'string' && entry.id.length > 0
+    const updated: ExperienceEntry = byId
+      ? { ...existing, ...entry, id: existing.id, hitCount: (existing.hitCount ?? 0) + 1, lastHitAt: lastUpdated }
+      : { ...existing, hitCount: (existing.hitCount ?? 0) + 1, lastHitAt: lastUpdated }
     return {
       bank: {
         ...bank,
@@ -150,14 +213,16 @@ export function upsertExperience(
     }
   }
 
-  // Add new entry
+  // Add new entry. Spread the caller input FIRST so the store-generated
+  // `id`/`timestamp`/`hitCount`/`lastHitAt` always win — a hostile or
+  // malformed input can never forge its own identity or hit count.
   const id = entry.id || `exp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
   const newEntry: ExperienceEntry = {
+    ...entry,
     id,
     timestamp: lastUpdated,
     hitCount: 1,
     lastHitAt: lastUpdated,
-    ...entry,
   }
 
   return {

package/src/tools/fix.ts

@@ -126,11 +126,25 @@ export function readRegistry(projectRoot: string): FixRegistry {
   try {
     const parsed = JSON.parse(readFileSync(file, 'utf-8')) as FixRegistry
     if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.rounds)) return emptyRegistry()
-    // Defensive: a hand-edited or partially-written registry may contain a
-    // round without a `records` array — normalize instead of crashing readers.
-    parsed.rounds = parsed.rounds.filter(
-      (r) => r && typeof r === 'object' && Array.isArray(r.records),
-    )
+    // Defensive normalization: a hand-edited or partially-written registry may
+    // contain a round without a `records` array, or records that are missing
+    // their id / finding object — all of which would make readers
+    // (findFixRecord / recordsForFile / iterate_diff) throw or sum NaN.
+    parsed.rounds = parsed.rounds
+      .filter((r) => r && typeof r === 'object' && Array.isArray(r.records))
+      .map((r) => ({
+        ...r,
+        round: typeof r.round === 'number' && Number.isFinite(r.round) ? Math.floor(r.round) : 0,
+        records: r.records.filter(
+          (rec): rec is FixRecord =>
+            !!rec &&
+            typeof rec === 'object' &&
+            typeof rec.id === 'string' &&
+            !!rec.finding &&
+            typeof rec.finding === 'object',
+        ),
+      }))
+      .filter((r) => typeof r.round === 'number' && Number.isFinite(r.round))
     return parsed
   } catch {
     return emptyRegistry()
@@ -621,19 +635,25 @@ export function registerDiffTool(ctx: { tools: { register: (def: ReturnType<type
         for (const round of registry.rounds) {
           for (const r of round.records) {
             if (!r.success) continue
-            const existing = files.find((f) => f.file === r.finding.file)
+            const file = typeof r.finding.file === 'string' ? r.finding.file : ''
+            if (!file) continue
+            // Coerce defensively: a hand-edited registry record missing the
+            // numeric fields must not produce NaN in the accumulated summary.
+            const added = Number(r.linesAdded) || 0
+            const removed = Number(r.linesRemoved) || 0
+            const existing = files.find((f) => f.file === file)
             if (existing) {
-              existing.linesAdded += r.linesAdded
-              existing.linesRemoved += r.linesRemoved
+              existing.linesAdded += added
+              existing.linesRemoved += removed
               // Recompute the summary from the summed counts so a multi-fix
               // file's text does not contradict its accumulated numbers.
               existing.diffSummary = `+${existing.linesAdded}/-${existing.linesRemoved} lines`
             } else {
               files.push({
-                file: r.finding.file,
-                diffSummary: r.diffSummary,
-                linesAdded: r.linesAdded,
-                linesRemoved: r.linesRemoved,
+                file,
+                diffSummary: typeof r.diffSummary === 'string' ? r.diffSummary : `+${added}/-${removed} lines`,
+                linesAdded: added,
+                linesRemoved: removed,
               })
             }
           }

package/src/tools/history.ts

@@ -60,8 +60,10 @@ export function summarizeFixRegistry(registry: FixRegistry): {
 } {
   const rounds = (registry.rounds ?? []).map((r) => ({
     round: r.round,
-    fixedCount: r.fixedCount,
-    failedCount: r.failedCount,
+    // Coerce defensively so a hand-edited registry round missing either count
+    // can never propagate NaN into the integer output fields.
+    fixedCount: Number(r.fixedCount) || 0,
+    failedCount: Number(r.failedCount) || 0,
   }))
   return {
     totalFixed: rounds.reduce((s, r) => s + r.fixedCount, 0),
@@ -92,7 +94,7 @@ export function registerHistoryTool(ctx: { tools: { register: (def: ReturnType<t
           type: 'string',
           description:
             'Optional entry-type filter: round_start, review_result, atomic_fix, architectural_fix, ' +
-            'revert, validation, decision, report.',
+            'revert, round_failed, validation, decision, report, resume.',
         },
         since: {
           type: 'string',

package/src/tools/prune.ts

@@ -13,6 +13,10 @@
  *   - Empty fix rounds (rounds with 0 records).
  *   - Stray temp files left behind by a crashed atomic write (see
  *     `isPrunableTemp` for the recognized naming conventions).
+ *   - Experience bank entries beyond `MAX_EXPERIENCE_ENTRIES` (newest kept) —
+ *     the bank grows across sessions with no natural bound; a sweep caps it.
+ *   - Defense events older than `retainDays` (stale iteration streams that
+ *     were never cleared).
  *
  * Security model:
  *   - Only operates under the resolved project `.iterate/` directory.
@@ -28,14 +32,27 @@ import { resolveProjectRootForExec } from '../config-loader.ts'
 import { writeTextAtomic, writeJsonAtomic } from '../atomic-fs.ts'
 import { readDecisionEntries, appendDecisionEntry } from './decision-log.ts'
 import { readRegistry, removeRecord, recomputeRoundCounts } from './fix.ts'
+import { readExperienceBank, writeExperienceBank } from './experience-store.ts'
+import { readDefenseEvents, writeDefenseEvents } from './defense-store.ts'
 import { iterateDir, fixesDir, checkpointPath, fixRegistryPath } from '../paths.ts'
-import type { FixRegistry } from '../types.ts'
+import type { DefenseEventStream, ExperienceBank, FixRegistry } from '../types.ts'
 
 /** Default retention for decision-log entries (in days). */
 const DEFAULT_RETAIN_DAYS = 30
 const MIN_RETAIN_DAYS = 1
 const MAX_RETAIN_DAYS = 365
 
+/**
+ * Upper bound on experience-bank entries retained by a prune sweep. The bank
+ * accumulates curated knowledge across sessions and each entry is small, so a
+ * generous cap drops only the oldest tail of a pathologically large bank
+ * (never recent learning).
+ */
+export const MAX_EXPERIENCE_ENTRIES = 2000
+
+/** How many compare-and-append retries bound the decision-log rewrite race. */
+const MAX_LOG_REWRITE_RETRIES = 3
+
 /** Clamp retainDays to a sane range. */
 export function clampRetainDays(days: number | undefined): number {
   if (typeof days !== 'number' || !Number.isInteger(days) || days <= 0) {
@@ -71,6 +88,62 @@ export function isPrunableTemp(name: string): boolean {
   return name.startsWith('.') && name.includes('.tmp-')
 }
 
+/**
+ * Bound the experience bank to its newest `cap` entries (by timestamp; ties
+ * keep their original order via stable sort). Returns the trimmed bank plus
+ * how many entries would be dropped. Never mutates the input bank.
+ */
+export function sweepExperienceBank(bank: ExperienceBank, cap: number): { bank: ExperienceBank; removed: number } {
+  const size = Number.isFinite(cap) && (cap as number) >= 0 ? Math.floor(cap) : MAX_EXPERIENCE_ENTRIES
+  const total = bank.entries.length
+  if (total <= size) return { bank, removed: 0 }
+  const kept = [...bank.entries]
+    .sort((a, b) => (b.timestamp ?? '').localeCompare(a.timestamp ?? ''))
+    .slice(0, size)
+  // Preserve the original (insertion) order of the surviving entries.
+  const keptIds = new Set(kept.map((e) => e.id))
+  const ordered = bank.entries.filter((e) => keptIds.has(e.id))
+  return {
+    bank: { ...bank, entries: ordered, lastUpdated: new Date().toISOString() },
+    removed: total - ordered.length,
+  }
+}
+
+/**
+ * Drop defense events older than `cutoff` from the stream using an ISO
+ * timestamp comparison, recomputing the counts so they can never drift from
+ * the surviving events. Never mutates the input stream.
+ */
+export function sweepDefenseEvents(
+  stream: DefenseEventStream,
+  cutoff: string,
+): { stream: DefenseEventStream; removed: number } {
+  const kept = stream.events.filter((e) => e.timestamp >= cutoff)
+  if (kept.length === stream.events.length) return { stream, removed: 0 }
+  return {
+    stream: {
+      events: kept,
+      lastUpdated: new Date().toISOString(),
+      counts: computeDefenseCounts(kept),
+    },
+    removed: stream.events.length - kept.length,
+  }
+}
+
+/** Recompute per-type defense counts from a list of events. */
+function computeDefenseCounts(events: DefenseEventStream['events']): DefenseEventStream['counts'] {
+  const counts: DefenseEventStream['counts'] = {
+    precondition_failed: 0,
+    rollback: 0,
+    invariant_violated: 0,
+    assumption_falsified: 0,
+  }
+  for (const e of events) {
+    if (e.type in counts) counts[e.type]++
+  }
+  return counts
+}
+
 /**
  * Inspect the runtime state and report what would be pruned.
  * Pure (no deletions). Returns a structured report.
@@ -86,6 +159,10 @@ export function inspectPrune(
   emptyRounds: number[]
   totalLogEntries: number
   registryRounds: number
+  totalExperiences: number
+  experienceOversize: number
+  totalDefenseEvents: number
+  staleDefenseEvents: number
 } {
   const cutoff = cutoffTimestamp(retainDays)
 
@@ -106,16 +183,22 @@ export function inspectPrune(
   }
   const staleBackups: string[] = []
   const fixDir = fixesDir(projectRoot)
-  if (existsSync(fixDir)) {
-    for (const entry of readdirSync(fixDir)) {
-      if (!entry.endsWith('.bak')) continue
-      // Extract the fix-id prefix (up to the first underscore after the id).
-      // e.g. "fix-abc123_2026-08-17T00-00-00-000Z.bak" → "fix-abc123"
-      const match = entry.match(/^(fix-[a-z0-9]+)_/)
-      const id = match?.[1]
-      if (id && !activeIds.has(id)) {
-        staleBackups.push(entry)
-      }
+  // existsSync does not prove readability — a permissions failure must degrade
+  // to "nothing listable" (report skipped) instead of throwing out of execute.
+  let fixEntries: string[] = []
+  try {
+    if (existsSync(fixDir)) fixEntries = readdirSync(fixDir)
+  } catch {
+    fixEntries = []
+  }
+  for (const entry of fixEntries) {
+    if (!entry.endsWith('.bak')) continue
+    // Extract the fix-id prefix (up to the first underscore after the id).
+    // e.g. "fix-abc123_2026-08-17T00-00-00-000Z.bak" → "fix-abc123"
+    const match = entry.match(/^(fix-[a-z0-9]+)_/)
+    const id = match?.[1]
+    if (id && !activeIds.has(id)) {
+      staleBackups.push(entry)
     }
   }
 
@@ -126,10 +209,26 @@ export function inspectPrune(
 
   // 5. Stray atomic-write temp files left behind by a crashed writer. The
   // unique prefix makes them recognizable and safe to delete — no live writer
-  // ever reads another writer's temp file.
-  const staleTemps = existsSync(iterateDir(projectRoot))
-    ? readdirSync(iterateDir(projectRoot)).filter((f) => isPrunableTemp(f)).sort()
-    : []
+  // ever reads another writer's temp file. A permissions failure listing the
+  // dir degrades to "none found" (report-only) rather than throwing.
+  let iterateEntries: string[] = []
+  try {
+    iterateEntries = existsSync(iterateDir(projectRoot)) ? readdirSync(iterateDir(projectRoot)) : []
+  } catch {
+    iterateEntries = []
+  }
+  const staleTemps = iterateEntries.filter((f) => isPrunableTemp(f)).sort()
+
+  // 6. Experience-bank oversize (entries beyond the entry cap). The bank grows
+  // across sessions with no natural bound — a sweep reports the tail that a
+  // prune would drop (newest `MAX_EXPERIENCE_ENTRIES` preserved).
+  const bank = readExperienceBank(projectRoot)
+  const sweptBank = sweepExperienceBank(bank, MAX_EXPERIENCE_ENTRIES)
+
+  // 7. Defense events older than retainDays (a previous iteration's stream
+  // that was never cleared).
+  const defenseStream = readDefenseEvents(projectRoot)
+  const sweptDefense = sweepDefenseEvents(defenseStream, cutoff)
 
   return {
     oldLogEntries,
@@ -139,6 +238,10 @@ export function inspectPrune(
     emptyRounds,
     totalLogEntries: entries.length,
     registryRounds: registry.rounds.length,
+    totalExperiences: bank.entries.length,
+    experienceOversize: sweptBank.removed,
+    totalDefenseEvents: defenseStream.events.length,
+    staleDefenseEvents: sweptDefense.removed,
   }
 }
 
@@ -146,6 +249,45 @@ export function inspectPrune(
  * Actually prune the runtime artifacts (only called when dryRun=false).
  * Returns a detailed report of what was deleted.
  */
+/**
+ * Rewrite the decision log to the entries younger than `cutoff`.
+ *
+ * The read-before-rewrite is a TOCTOU hot spot: a concurrent worker can append
+ * a fresh audit line between our read and our atomic rewrite, and an atomic
+ * rename would silently discard it. So instead of a single read+write we use a
+ * bounded compare-and-append loop — after each rewrite we re-read the log and
+ * retry whenever the file grew (a concurrent append slipped in). The loop
+ * terminates when the file is stable or after `MAX_LOG_REWRITE_RETRIES`, and a
+ * failure here is surfaced as a structured error instead of truncating the log.
+ *
+ * @returns the number of entries removed (best-effort) or 0 on error.
+ */
+function rewriteDecisionLogKeepingRecent(projectRoot: string, cutoff: string): { deleted: number; error?: string } {
+  const logPath = join(iterateDir(projectRoot), 'decision-log.jsonl')
+  for (let attempt = 0; attempt < MAX_LOG_REWRITE_RETRIES; attempt++) {
+    try {
+      const entries = readDecisionEntries(projectRoot)
+      const kept = entries.filter((e) => e.timestamp >= cutoff)
+      const deleted = entries.length - kept.length
+      if (deleted === 0) return { deleted: 0 }
+      writeTextAtomic(logPath, kept.map((e) => JSON.stringify(e)).join('\n') + '\n')
+      // A concurrent appender may have landed new lines after our read. If the
+      // log grew during the write window, re-read and prune again instead of
+      // accepting a lost audit trail.
+      const after = readDecisionEntries(projectRoot)
+      if (after.length <= kept.length) return { deleted }
+    } catch (err) {
+      return { deleted: 0, error: `failed to rewrite decision log: ${String(err)}` }
+    }
+  }
+  return { deleted: 0, error: `failed to rewrite decision log after ${MAX_LOG_REWRITE_RETRIES} attempts` }
+}
+
+/**
+ * Execute the prune: apply every cleanable item reported by `inspectPrune`.
+ * Every step is individually hedged so a single disk failure degrades to a
+ * reported error rather than aborting the whole cleanup.
+ */
 export function executePrune(
   projectRoot: string,
   retainDays: number,
@@ -156,6 +298,8 @@ export function executePrune(
   deletedBackups: string[]
   deletedTemps: string[]
   trimmedEmptyRounds: number
+  deletedExperiences: number
+  deletedDefenseEvents: number
   errors: string[]
 } {
   const cutoff = cutoffTimestamp(retainDays)
@@ -165,22 +309,19 @@ export function executePrune(
     deletedBackups: [] as string[],
     deletedTemps: [] as string[],
     trimmedEmptyRounds: 0,
+    deletedExperiences: 0,
+    deletedDefenseEvents: 0,
     errors: [] as string[],
   }
 
   // 1. Rewrite the decision log, keeping only recent entries. Atomic
-  // (temp + rename) so a crash mid-write can never truncate the log.
-  try {
-    const entries = readDecisionEntries(projectRoot)
-    const kept = entries.filter((e) => e.timestamp >= cutoff)
-    result.deletedLogEntries = entries.length - kept.length
-    if (result.deletedLogEntries > 0) {
-      const logPath = join(iterateDir(projectRoot), 'decision-log.jsonl')
-      writeTextAtomic(logPath, kept.map((e) => JSON.stringify(e)).join('\n') + '\n')
-    }
-  } catch (err) {
-    result.errors.push(`failed to rewrite decision log: ${String(err)}`)
-    result.deletedLogEntries = 0
+  // (temp + rename) so a crash mid-write can never truncate the log; the
+  // bounded compare-and-append loop guards against a concurrent appender
+  // slipping a fresh audit line into the read-before-rewrite window.
+  {
+    const { deleted, error } = rewriteDecisionLogKeepingRecent(projectRoot, cutoff)
+    result.deletedLogEntries = deleted
+    if (error) result.errors.push(error)
   }
 
   // 2. Remove checkpoint.
@@ -233,6 +374,34 @@ export function executePrune(
     }
   }
 
+  // 6. Trim the experience bank to its entry cap (newest wins).
+  if (report.experienceOversize > 0) {
+    try {
+      const bank = readExperienceBank(projectRoot)
+      const { bank: swept, removed } = sweepExperienceBank(bank, MAX_EXPERIENCE_ENTRIES)
+      if (removed > 0) {
+        writeExperienceBank(projectRoot, swept)
+        result.deletedExperiences = removed
+      }
+    } catch (err) {
+      result.errors.push(`failed to trim experience bank: ${String(err)}`)
+    }
+  }
+
+  // 7. Drop defense events older than retainDays (recounted on write).
+  if (report.staleDefenseEvents > 0) {
+    try {
+      const stream = readDefenseEvents(projectRoot)
+      const { stream: swept, removed } = sweepDefenseEvents(stream, cutoff)
+      if (removed > 0) {
+        writeDefenseEvents(projectRoot, swept)
+        result.deletedDefenseEvents = removed
+      }
+    } catch (err) {
+      result.errors.push(`failed to sweep defense events: ${String(err)}`)
+    }
+  }
+
   return result
 }
 
@@ -249,7 +418,8 @@ export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typ
         'Inspect or clean up old iterate runtime artifacts (.iterate/). ' +
         'Defaults to dry-run (report-only, no deletion). Pass `dryRun: false` to actually prune. ' +
         'Manages: old decision-log entries, stale checkpoints, orphaned fix backups, empty fix rounds, ' +
-        'and stray temp files left by crashed atomic writes. ' +
+        'stray temp files left by crashed atomic writes, experience-bank entries beyond the entry cap, ' +
+        'and stale defense events. ' +
         'Each deletion is logged to the decision log.',
       parameters: {
         dryRun: {
@@ -291,6 +461,8 @@ export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typ
               `  Stale backups to delete: ${(report?.staleBackups as string[] | undefined)?.length ?? 0}`,
               `  Stray temp files to delete: ${(report?.staleTemps as string[] | undefined)?.length ?? 0}`,
               `  Empty rounds to trim: ${(report?.emptyRounds as number[] | undefined)?.length ?? 0}`,
+              `  Experience entries to drop (over ${report?.totalExperiences ?? '?'} cap): ${report?.experienceOversize ?? 0} of ${report?.totalExperiences ?? '?'}`,
+              `  Stale defense events to remove: ${report?.staleDefenseEvents ?? 0} (of ${report?.totalDefenseEvents ?? '?'})`,
               '',
               'Pass dryRun:false to execute the prune.',
             ]
@@ -303,6 +475,8 @@ export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typ
             `  Deleted ${(result?.deletedBackups as string[] | undefined)?.length ?? 0} stale backups.`,
             `  Deleted ${(result?.deletedTemps as string[] | undefined)?.length ?? 0} stray temp files.`,
             `  Trimmed ${result?.trimmedEmptyRounds ?? 0} empty rounds.`,
+            `  Trimmed ${result?.deletedExperiences ?? 0} experience entries (over the entry cap).`,
+            `  Removed ${result?.deletedDefenseEvents ?? 0} stale defense events.`,
           ]
           const errs = (result?.errors as string[] | undefined) ?? []
           if (errs.length > 0) {
@@ -345,6 +519,8 @@ export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typ
             deletedCheckpoint: result.deletedCheckpoint,
             deletedBackups: result.deletedBackups.length,
             trimmedEmptyRounds: result.trimmedEmptyRounds,
+            deletedExperiences: result.deletedExperiences,
+            deletedDefenseEvents: result.deletedDefenseEvents,
           },
         })
 

package/src/tools/quality-gate.ts

@@ -13,6 +13,9 @@ import { resolveProjectRootForExec } from '../config-loader.ts'
 import { readQualityGate, writeQualityGate, computeQualityGate, clearQualityGate } from './quality-store.ts'
 import type { QualityGateSnapshot } from '../types.ts'
 
+/** Valid severity values (kept in sync with QualityGateSnapshot counting). */
+const VALID_SEVERITIES: ReadonlySet<string> = new Set(['critical', 'high', 'medium', 'low'])
+
 /** Validate a single finding object; returns true when well-formed. */
 function isValidFinding(raw: unknown): raw is { dimension: string; severity: string; file: string; line?: number } {
   if (!raw || typeof raw !== 'object') return false
@@ -20,6 +23,7 @@ function isValidFinding(raw: unknown): raw is { dimension: string; severity: str
   return (
     typeof f.dimension === 'string' &&
     typeof f.severity === 'string' &&
+    VALID_SEVERITIES.has(f.severity) &&
     typeof f.file === 'string' &&
     (f.line === undefined || typeof f.line === 'number')
   )

package/src/tools/quality-store.ts

@@ -232,15 +232,20 @@ export function computeQualityGate(opts: {
     ? Math.round(dimensionGates.reduce((sum, d) => sum + d.score, 0) / dimensionGates.length)
     : 0
 
-  // Determine overall status
+  // Determine overall status. An empty review (no dimensions, no findings, no
+  // validation results) is NOT a failure — there is simply nothing to gate —
+  // so it reports `pending` (not-applicable) instead of a fabricated FAIL.
   const hasCritical = criticalCount > 0
   const hasHighFail = dimensionGates.some((d) => d.status === 'fail')
   const verificationFails = totalChecks > 0 && failedChecks > 0
+  const noData = dimensionGates.length === 0 && totalFindings === 0 && totalChecks === 0
 
   let overallStatus: 'pass' | 'fail' | 'pending' = 'pass'
   let failReason: string | undefined
 
-  if (hasCritical) {
+  if (noData) {
+    overallStatus = 'pending'
+  } else if (hasCritical) {
     overallStatus = 'fail'
     failReason = `${criticalCount} critical findings present`
   } else if (hasHighFail) {