iterate-plugin 3.5.2 → 3.5.3

package/README.md

@@ -106,7 +106,7 @@ Both modes share:
 ### UI layer (build-free client slots, v3.2: 10 tabs)
 
 - **ConvergenceDashboard** (`conversation.input.dock`) — live round progress bar, severity stats, dimension badges, trend mini-chart above the input; normal mode also shows fix-count badges; plus a live workflow-phase chip (current phase + running/stopped) and a **v3.2 task_mode indicator (code / iterate)**, now backed by the persisted transcript (`iterate_status` / `iterate_transcript` emit `taskMode`).
-- **ObservatoryPanel** (`conversation.input.dock`) — a **ten-tab** runtime observatory below the input: live activity stream (type filter), review threads (expand / collapse all), convergence trend, finding locations (severity / dimension / search filter), fixes + rollback, checkpoint resume, decision timeline (type / round filter + search). **v3.2 tabs: Quality Gate (F8), Experience Bank (F9), Defense Events (F10)**; one-click JSON export of all observatory data (download, copy fallback). **v3.3: F8/F9/F10 are now live** — they scan the session stream for the latest `iterate_quality_gate` / `iterate_experience` / `iterate_defense_events` results and render real data (PASS/FAIL chip + per-dimension score bars, experience entries with adopt buttons + client-side search, defense type-count chips + filtered event stream), degrading to copy-able query instructions only when the session has none.
+- **ObservatoryPanel** (`conversation.input.dock`) — a **ten-tab** runtime observatory below the input: live activity stream (type filter), review threads (expand / collapse all), convergence trend, finding locations (severity / dimension / search filter), fixes + rollback, checkpoint resume, decision timeline (type / round filter + search). **v3.2 tabs: Quality Gate (F8), Experience Bank (F9), Defense Events (F10)**; one-click JSON export of all observatory data (download, copy fallback). **v3.3+: F8/F9/F10 are live** — they scan the session stream for the latest `iterate_quality_gate` / `iterate_experience` / `iterate_defense_events` results and render real data (PASS/FAIL chip + per-dimension score bars, experience entries with adopt buttons + client-side search, defense type-count chips + filtered event stream), degrading to copy-able query instructions only when the session has none. **v3.5.3: reset actions surfaced** — F5 copies an `iterate_checkpoint clear` instruction, F8 an `iterate_quality_gate clear` instruction, F10 an `iterate_defense_events clear` instruction.
 - **TriagePanel** (`conversation.chat.turnTail`) — per-finding y/n/a triage, filtering, batch ops (incl. select-all), keyboard shortcuts, localStorage persistence, copy-YAML / apply-instruction. **v3.2: native command buttons** (approve architectural fix, trigger new round, rollback to checkpoint). **v3.3: §8 指派修复 (assign)** — one click copies an `iterate_fix` instruction carrying every in-scope finding (respecting the batch toggle).
 - **StatsCard** (`conversation.chat.turnTail`) — convergence stats, round history, trend chart and completion summary when no findings remain.
 - **iterate theme skin** (`theme.overrideTokens`) — a warm-amber 13-token `--dsw-*` override, light/dark modes, togglable in settings.
@@ -255,14 +255,14 @@ validation:
 - `iterate_fix` — apply **one atomic fix**: validates the relative path, backs up the original file, enforces atomicity via `atomic.max_lines` (skippable with `force`), writes new content, records a FixRecord and an `atomic_fix` log. The only legal file-modifying entry in normal mode
 - `iterate_diff` — view accumulated fix changes: with `file`, returns the unified diff against the first backup; without it, a per-fixed-file summary
 - `iterate_rollback` — roll back an applied fix: restore the file from backup, remove that FixRecord from the registry, append a `revert` log. Used after a failed round validation
-- `iterate_checkpoint` — iteration breakpoint: `save` persists progress to `.iterate/checkpoint.json`, `load` reads it back, `resume` loads + bumps the resume counter (interruption recovery), `clear` removes it. Resumable interrupted long iterations
+- `iterate_checkpoint` — iteration breakpoint: `save` persists progress to `.iterate/checkpoint.json`, `load` reads it back, `resume` loads + bumps the resume counter (interruption recovery), `clear` removes it (bounded findings payload, `round ≤ maxRounds` enforced). Resumable interrupted long iterations
 - `iterate_status` — summarize current iteration state: mode, current/last round, fixes applied, remaining architectural, decision-log entry count, whether a checkpoint exists; **v3.4: also surfaces the persisted quality-gate snapshot, experience-bank summary, and defense-events summary** (`qualityGate` / `experienceBank` / `defenseEvents`)
 - `iterate_history` — read iteration history (read-only): decision-log entries (filter by `type` / `since` / `limit`, default latest 50, cap 200) + fix-registry summary (per-round fixed/failed counts). For auditing the run, tracing logs, and inventorying fixes
 - `iterate_prune` — clean runtime artifacts: stale decision-log entries (by `retainDays`, default 30), stale checkpoints, orphaned fix backups, empty rounds, stray temp files (crashed atomic writes). Dry-run by default (report-only); real cleanup with `dryRun:false`, each cleanup logged
 - `iterate_transcript` — runtime observatory: persist review transcripts, threads, fixes, and nudge directions to `.iterate/transcript.json` for the client observatory
 - `iterate_experience` — **v3.2** query the experience bank (list / search / get), `add` a new verified fix (re-adding the same pattern+dimension bumps its hit count instead of duplicating it), or **v3.5 remove a stale/incorrect entry by `id`** so bad experiences never resurface. Persists to `.iterate/experience.json`
 - `iterate_quality_gate` — **v3.2** read the quality certificate (`read`), or recompute + persist a fresh one (`compute`) from findings, validation results, `findingsByRound`, and `fixedByDimension`. Real per-dimension convergence rates. **v3.5: `clear` removes the persisted certificate to reset a stale gate before a fresh iteration**
-- `iterate_defense_events` — **v3.2** query defense events (list / counts), or `record` a new one. Human-readable labels follow the project language (en / zh)
+- `iterate_defense_events` — **v3.2** query defense events (list / counts), `record` a new one, or **v3.5.3 `clear` the persisted stream** so a fresh iteration starts without stale defensive data. Human-readable labels follow the project language (en / zh)
 
 ---
 

package/README.zh-CN.md

@@ -105,7 +105,7 @@ dsh plugin --profile web add iterate-plugin
 ### UI 层（客户端免构建槽位，v3.2：10 个标签页）
 
 - **收敛看板 `ConvergenceDashboard`**（`conversation.input.dock`）— 输入框上方实时显示轮次进度条、严重度统计、维度徽章、趋势迷你图；normal 模式另显示修复计数徽章；还有运行阶段芯片（当前工作流阶段 + 运行中/已结束）与 **v3.2 task_mode 指示器（code / iterate）**。
-- **运行时观测台 `ObservatoryPanel`**（`conversation.input.dock`）— 输入框下方**十个标签页**运行时观测台：实时活动流（支持按活动类型筛选）、审查线程（支持全部展开/全部收起）、收敛趋势、发现定位（支持按严重度/维度/关键词筛选）、修复与回滚、断点恢复、决策时间线（支持按类型/轮次筛选与关键词搜索）。**v3.2 新增标签：质量门禁（F8）、经验银行（F9）、防御事件（F10）**；支持一键导出全部观测数据为 JSON（优先下载，失败回退复制）。
+- **运行时观测台 `ObservatoryPanel`**（`conversation.input.dock`）— 输入框下方**十个标签页**运行时观测台：实时活动流（支持按活动类型筛选）、审查线程（支持全部展开/全部收起）、收敛趋势、发现定位（支持按严重度/维度/关键词筛选）、修复与回滚、断点恢复、决策时间线（支持按类型/轮次筛选与关键词搜索）。**v3.2 新增标签：质量门禁（F8）、经验银行（F9）、防御事件（F10）**；支持一键导出全部观测数据为 JSON（优先下载，失败回退复制）。**v3.5.3 新增重置操作**：F5 复制 `iterate_checkpoint clear`、F8 复制 `iterate_quality_gate clear`、F10 复制 `iterate_defense_events clear` 指令。
 - **Findings 分诊面板 `TriagePanel`**（`conversation.chat.turnTail`）— 逐条 y/n/a 判定，支持筛选、批量（含一键全选所有 findings）、键盘快捷键、localStorage 持久化、复制 YAML / 应用指令。**v3.2：原生命令按钮**（批准架构修复、触发新一轮、回滚到断点）。
 - **收敛统计卡片 `StatsCard`**（`conversation.chat.turnTail`）— 无 findings 时显示收敛统计、历史轮次、趋势图、完成摘要。
 - **iterate 主题皮肤**（`theme.overrideTokens`）— 暖琥珀配色的 13 个 `--dsw-*` token 覆盖，明暗双模式，可在设置页开关。
@@ -254,14 +254,14 @@ validation:
 - `iterate_fix` — 应用**一个原子修复**：校验相对路径、备份原文件、按 `atomic.max_lines` 强制原子性（可 `force` 跳过）、写入新内容、记录 FixRecord 与 `atomic_fix` 日志。normal 模式唯一合法的改文件入口
 - `iterate_diff` — 查看修复累积变更：指定 `file` 返回相对首个备份的 unified diff；省略则返回每个已修复文件的汇总
 - `iterate_rollback` — 回滚一个已应用的修复：从备份还原文件、从注册表移除该 FixRecord、追加 `revert` 日志。用于某轮验证失败后
-- `iterate_checkpoint` — 迭代断点：`save` 保存当前进度到 `.iterate/checkpoint.json`，`load` 读回，`resume` 加载并累加恢复计数（中断恢复），`clear` 清除。长迭代可中断续跑
+- `iterate_checkpoint` — 迭代断点：`save` 保存当前进度到 `.iterate/checkpoint.json`，`load` 读回，`resume` 加载并累加恢复计数（中断恢复），`clear` 清除（findings 载荷有上限，强制 `round ≤ maxRounds`）。长迭代可中断续跑
 - `iterate_status` — 汇总当前迭代状态：模式、当前轮/总轮、已修复数、剩余 architectural、决策日志条数、是否存在 checkpoint；**v3.4：同时返回持久化的质量门禁快照、经验银行摘要与防御事件摘要**（`qualityGate` / `experienceBank` / `defenseEvents`）
 - `iterate_history` — 读取迭代历史（只读）：决策日志条目（可按 `type` / `since` / `limit` 过滤，默认取最新 50 条，上限 200 条）+ 修复注册表汇总（各轮 fixed/failed 计数）。用于审查运行过程、审计日志、盘点修复
 - `iterate_prune` — 清理运行时产物：过期决策日志条目（按 `retainDays`，默认 30 天）、陈旧断点、孤儿修复备份、空轮次、崩溃原子写入残留的临时文件。默认 dry-run 只报告不删除；`dryRun:false` 才真正清理，每次清理写入决策日志
 - `iterate_transcript` — 运行时观测台：把审查转录、线程、修复与 nudge 指令持久化到 `.iterate/transcript.json`，供客户端观测台读取
 - `iterate_experience` — **v3.2** 查询经验银行（list / search / get），或 `add` 一条新的已验证修复：重复添加同一 pattern + dimension 累加命中次数而非重复写入。**v3.5 新增 `remove`：按 `id` 删除过时或错误的经验条目**。持久化到 `.iterate/experience.json`
 - `iterate_quality_gate` — **v3.2** 读取质量凭证（`read`），或基于 findings、验证结果、`findingsByRound` 与 `fixedByDimension` 重新计算并持久化一份新凭证（`compute`）。真实的逐维度收敛率。**v3.5 新增 `clear`：删除持久化的质量凭证**，用于新一轮迭代前重置陈旧的门禁
-- `iterate_defense_events` — **v3.2** 查询防御事件（list / counts），或 `record` 记录一条新事件。可读标签跟随项目语言（en / zh）
+- `iterate_defense_events` — **v3.2** 查询防御事件（list / counts），`record` 记录一条新事件，或 **v3.5.3 `clear` 清除持久化事件流**，让新一轮迭代不带陈旧防御数据起跑。可读标签跟随项目语言（en / zh）
 
 ---
 

package/dist/tools/checkpoint.js

@@ -19,6 +19,9 @@ import { readQualityGate } from "./quality-store.js";
 import { readExperienceBank } from "./experience-store.js";
 import { readDefenseEvents } from "./defense-store.js";
 // ─── 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) {
     const file = checkpointPath(projectRoot);
@@ -30,9 +33,28 @@ export function readCheckpoint(projectRoot) {
             return null;
         if (parsed.mode !== 'dry-run' && parsed.mode !== 'normal')
             return null;
-        if (typeof parsed.round !== 'number')
+        // 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;
-        return parsed;
+        const num = (v, fallback) => 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 : [],
+            startedAt: typeof parsed.startedAt === 'string' ? parsed.startedAt : new Date().toISOString(),
+            updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
+        };
     }
     catch {
         return null;
@@ -73,6 +95,15 @@ export function validateCheckpoint(input) {
         (typeof input.resumeCount !== 'number' || !Number.isInteger(input.resumeCount) || input.resumeCount < 0)) {
         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;
 }
 /**
@@ -95,8 +126,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.
@@ -230,7 +264,7 @@ export function registerCheckpointTool(ctx) {
                     fixedCount: args.fixedCount,
                     architecturalCount: args.architecturalCount,
                     resumeCount: (typeof args.resumeCount === 'number' ? args.resumeCount : 0),
-                    findings: (Array.isArray(args.findings) ? args.findings : []),
+                    findings: (Array.isArray(args.findings) ? args.findings.slice(0, MAX_CHECKPOINT_FINDINGS) : []),
                     startedAt: readCheckpoint(projectRoot)?.startedAt ?? new Date().toISOString(),
                     updatedAt: new Date().toISOString(),
                 };

package/dist/tools/config.js

@@ -1,6 +1,7 @@
 import { join } from 'node:path';
+import { existsSync } from 'node:fs';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from "../config-loader.js";
+import { defaultConfig, loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from "../config-loader.js";
 import { applyConfigUpdates, readRawConfig, validateConfigUpdates, writeConfigFile, } from "../config-write.js";
 /**
  * Register the `iterate_config` tool.
@@ -91,7 +92,15 @@ export function registerConfigTool(ctx) {
                 }
                 let base;
                 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();
                 }
                 catch (err) {
                     return { operation: 'write', ok: false, found: false, error: `failed to read config: ${String(err)}` };

package/dist/tools/defense-events.js

@@ -10,7 +10,7 @@
  */
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec, loadEffectiveConfig } from "../config-loader.js";
-import { readDefenseEvents, writeDefenseEvents, addDefenseEvent } from "./defense-store.js";
+import { readDefenseEvents, writeDefenseEvents, addDefenseEvent, clearDefenseEvents } from "./defense-store.js";
 const DEFAULT_LIMIT = 50;
 const MAX_LIMIT = 100;
 const EVENT_TYPES = [
@@ -75,16 +75,18 @@ export function registerDefenseEventsTool(ctx) {
         // List/counts never write; only `record` persists an event → read shapes
         // join a parallel dispatch group.
         isConcurrencySafe: (args) => args.operation !== 'record',
-        description: 'Query or record defense events: precondition failures, rollbacks, invariant violations, ' +
+        description: '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',
@@ -141,6 +143,7 @@ export function registerDefenseEventsTool(ctx) {
                     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' },
@@ -153,6 +156,16 @@ export function registerDefenseEventsTool(ctx) {
                 if (!value.ok)
                     return [{ type: 'text', text: `defense events query failed: ${value.error}` }];
                 const language = 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;
                     const lines = [
@@ -193,10 +206,32 @@ export function registerDefenseEventsTool(ctx) {
             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 = rawConfigLang === 'zh' ? 'zh' : 'en';
             const language = args.language === 'zh' || args.language === 'en' ? args.language : configLang;
             const operation = typeof args.operation === 'string' ? args.operation : 'list';
             const limit = clampLimit(args.limit);
+            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,
+                    events: empty.events,
+                };
+            }
             if (operation === 'record') {
                 const errors = validateRecordInput(args);
                 if (errors.length > 0) {

package/dist/tools/defense-store.js

@@ -39,11 +39,41 @@ function emptyStream() {
         },
     };
 }
+/** Valid severity values (kept in sync with DefenseEvent). */
+const VALID_SEVERITIES = 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.
+ */
+function normalizeEvent(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const e = raw;
+    if (typeof e.type !== 'string' || !VALID_EVENT_TYPES.has(e.type))
+        return null;
+    return {
+        id: typeof e.id === 'string' && e.id ? e.id : `def-${Math.random().toString(36).slice(2, 8)}`,
+        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,
+        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 : '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) {
     const filePath = path.join(projectRoot, '.iterate', DEFENSE_EVENTS_FILE);
@@ -51,7 +81,9 @@ export function readDefenseEvents(projectRoot) {
         const content = fs.readFileSync(filePath, 'utf-8');
         const parsed = JSON.parse(content);
         if (parsed && Array.isArray(parsed.events)) {
-            const events = parsed.events.filter((e) => !!e && typeof e === 'object' && typeof e.type === 'string');
+            const events = parsed.events
+                .map(normalizeEvent)
+                .filter((e) => e !== null);
             const counts = computeCounts(events);
             return {
                 events,
@@ -87,6 +119,25 @@ export function writeDefenseEvents(projectRoot, stream) {
     }
     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) {
+    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, event) {
     const id = `def-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;

package/dist/tools/experience-bank.js

@@ -144,8 +144,8 @@ export function registerExperienceBankTool(ctx) {
                                 `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') {
@@ -158,9 +158,9 @@ export function registerExperienceBankTool(ctx) {
                                 `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 ?? [];
@@ -252,7 +252,7 @@ export function registerExperienceBankTool(ctx) {
                     operation: 'get',
                     count: 1,
                     entry: entry,
-                    totalHits: bank.totalHits,
+                    totalHits: bank.totalHits ?? 0,
                 };
             }
             if (operation === 'search' && typeof args.query === 'string') {
@@ -266,7 +266,7 @@ export function registerExperienceBankTool(ctx) {
                     operation: 'search',
                     count: entries.length,
                     entries: entries,
-                    totalHits: bank.totalHits,
+                    totalHits: bank.totalHits ?? 0,
                 };
             }
             // Default: list with optional filters
@@ -275,7 +275,7 @@ export function registerExperienceBankTool(ctx) {
                 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) => e.tags.includes(t)));
+                entries = entries.filter((e) => args.tags.every((t) => Array.isArray(e.tags) && e.tags.includes(t)));
             }
             return {
                 ok: true,
@@ -283,7 +283,7 @@ export function registerExperienceBankTool(ctx) {
                 operation: 'list',
                 count: Math.min(entries.length, limit),
                 entries: entries.slice(0, limit),
-                totalHits: bank.totalHits,
+                totalHits: bank.totalHits ?? 0,
             };
         },
     }));

package/dist/tools/experience-store.js

@@ -17,6 +17,46 @@ function emptyBank() {
         totalHits: 0,
     };
 }
+/** Valid severity values (kept in sync with ExperienceEntry). */
+const VALID_SEVERITIES = new Set(['critical', 'high', 'medium', 'low']);
+/** String array guard for fields that must be arrays (`files`, `tags`). */
+function stringArray(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((x) => 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) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const e = raw;
+    const pattern = typeof e.pattern === 'string' ? e.pattern : '';
+    const dimension = typeof e.dimension === 'string' ? e.dimension : '';
+    const id = typeof e.id === 'string' && e.id ? e.id : `exp-${Math.random().toString(36).slice(2, 8)}`;
+    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 : 'low',
+    };
+}
 /** Read the experience bank from disk. Returns empty bank if not found. */
 export function readExperienceBank(projectRoot) {
     const filePath = path.join(projectRoot, '.iterate', EXPERIENCE_FILE);
@@ -24,7 +64,14 @@ export function readExperienceBank(projectRoot) {
         const content = fs.readFileSync(filePath, 'utf-8');
         const parsed = JSON.parse(content);
         if (parsed && Array.isArray(parsed.entries)) {
-            return parsed;
+            const entries = parsed.entries
+                .map(normalizeEntry)
+                .filter((e) => 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 {
@@ -58,17 +105,23 @@ export function writeExperienceBank(projectRoot, bank) {
 export function searchExperienceEntries(entries, query, opts = {}) {
     const lowerQuery = query.toLowerCase();
     return entries.filter((entry) => {
+        if (!entry || typeof entry !== 'object')
+            return false;
+        const rawEntry = entry;
+        const tags = stringArray(rawEntry.tags);
         // Dimension filter
         if (opts.dimension && entry.dimension !== opts.dimension) {
             return false;
         }
         // 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
+        // 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,
@@ -76,8 +129,8 @@ export function searchExperienceEntries(entries, query, opts = {}) {
                 entry.verifiedFix,
                 entry.findingSummary,
                 entry.dimension,
-                ...entry.files,
-                ...entry.tags,
+                ...stringArray(entry.files),
+                ...stringArray(entry.tags),
             ].join(' ').toLowerCase();
             if (!searchableText.includes(lowerQuery)) {
                 return false;

package/dist/tools/fix.js

@@ -120,9 +120,22 @@ export function readRegistry(projectRoot) {
         const parsed = JSON.parse(readFileSync(file, 'utf-8'));
         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 &&
+                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 {
@@ -611,20 +624,27 @@ export function registerDiffTool(ctx) {
                 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/dist/tools/history.js

@@ -46,8 +46,10 @@ export function filterDecisionEntries(entries, opts) {
 export function summarizeFixRegistry(registry) {
     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),
@@ -74,7 +76,7 @@ export function registerHistoryTool(ctx) {
             type: {
                 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',