iterate-plugin 3.3.0 → 3.4.0

package/README.md

@@ -255,8 +255,8 @@ 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, `clear` removes it. 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
+- `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_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. 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
@@ -286,6 +286,56 @@ All runtime state lives under `.iterate/` at the project root (can be excluded v
 
 ---
 
+## 🔐 Permissions, dependencies & compatibility
+
+### Node.js / DSH compatibility
+
+- **Node.js**: `>=20` (`package.json` `engines.node`).
+- **DSH**: declares `dsh.compatibility.dshReleases` — `compatible` for the official
+  `0.1.2-alpha.4`, `0.1.2-alpha.5`, and `0.1.2-rc.1` releases. The plugin is built
+  against `@deepseek-ai/dsh-tools` / `@deepseek-ai/dsh-util-values` `0.1.2-rc.1`
+  and uses only public contracts (tool registration, client slots + theme, bundle patch).
+
+### Runtime permissions (conservative disclosure)
+
+The plugin runs with the **same process capabilities as the DSH host** and touches the
+following capabilities; elevated capability means a DSH Profile install stays
+`user-reviewed`/guarded rather than auto-approved:
+
+- **Files** — reads and writes project-local state under `<projectRoot>/.iterate/`
+  (decision log, checkpoint, transcript, fix backups/registry, quality gate,
+  experience bank, defense events). `iterate_fix` / `iterate_triage` also apply
+  in-place edits to the user's source files (path-traversal protected to the
+  resolved project root, backups taken before every fix, rollback on failure).
+  The client half persists triage verdicts to `localStorage`.
+- **Commands** — the plugin registers model-facing tools; any shell execution that
+  the model performs (build / test / `git`) is run by the **host**, not by this
+  plugin. The client "command buttons" only copy paste-able instruction text; they
+  do not spawn processes.
+- **Credentials** — this plugin does **not** read or transmit credentials at
+  runtime. The sibling **iterate-skill / iterate-harness** components may read git
+  credentials / GitHub tokens when the user runs their own Git/API operations; those
+  are separate packages and are never loaded by this plugin.
+- **Network** — no network access at runtime (everything is local to the project).
+
+### Dependencies
+
+Runtime dependencies: `@deepseek-ai/cordis`, `@deepseek-ai/dsh-tools`,
+`@deepseek-ai/dsh-util-values`, `js-yaml` — all pinned exact versions. No
+install-time lifecycle scripts (`preinstall`/`install`/`postinstall`/`prepare`);
+only `prepublishOnly` (build) runs on publish.
+
+### Failure bounds
+
+- All writes are atomic (temp + rename) and confined under `.iterate/`; a crash
+  mid-write cannot corrupt the checkpoint/transcript.
+- Persistence failures surface as structured `{ ok: false, error }` results instead
+  of silent success.
+- Fix edits are applied to backups first and rolled back on validation failure.
+- The UI degrades gracefully when a slot/service is unavailable.
+
+---
+
 ## 🎨 Design
 
 The plugin follows dsh's "everything-is-a-plugin" architecture:

package/README.zh-CN.md

@@ -254,8 +254,8 @@ 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` 读回，`clear` 清除。长迭代可中断续跑
-- `iterate_status` — 汇总当前迭代状态：模式、当前轮/总轮、已修复数、剩余 architectural、决策日志条数、是否存在 checkpoint
+- `iterate_checkpoint` — 迭代断点：`save` 保存当前进度到 `.iterate/checkpoint.json`，`load` 读回，`resume` 加载并累加恢复计数（中断恢复），`clear` 清除。长迭代可中断续跑
+- `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`，供客户端观测台读取
@@ -285,6 +285,49 @@ validation:
 
 ---
 
+## 🔐 权限、依赖与兼容性
+
+### Node.js / DSH 兼容范围
+
+- **Node.js**：`>=20`（`package.json` 的 `engines.node`）。
+- **DSH**：在 `dsh.compatibility.dshReleases` 中声明官方 `0.1.2-alpha.4`、
+  `0.1.2-alpha.5`、`0.1.2-rc.1` 三个版本为 `compatible`。插件基于
+  `@deepseek-ai/dsh-tools` / `@deepseek-ai/dsh-util-values` `0.1.2-rc.1` 构建，
+  只使用公开契约（工具注册、客户端 slots + theme、bundle patch）。
+
+### 运行时权限（保守披露）
+
+插件与 DSH 宿主共享同一进程能力，涉及以下能力；具备高权限意味着 DSH Profile
+安装仍需 `user-reviewed`/守卫，不会自动放行：
+
+- **文件（files）** — 读写 `<projectRoot>/.iterate/` 下的项目本地状态（决策日志、
+  检查点、transcript、修复备份/注册表、质量门禁、经验银行、防御事件）。
+  `iterate_fix` / `iterate_triage` 还会就地修改用户源码（路径遍历防护限定在解析后
+  的项目根目录内，每次修复前备份、失败回滚）。客户端侧把分诊判定持久化到 `localStorage`。
+- **命令（commands）** — 插件只注册模型可调用工具；模型要执行的任何 shell 操作
+  （build / test / `git`）都由**宿主**执行，不是本插件。客户端"指挥按钮"只复制可粘贴
+  的指令文本，不启动任何进程。
+- **凭据（credentials）** — 本插件运行时**不**读取或传输凭据。同生态的
+  **iterate-skill / iterate-harness** 组件在用户自行执行 Git/API 操作时可能读取
+  git 凭据 / GitHub token；它们是独立包，本插件从不加载它们。
+- **网络（network）** — 运行时无任何网络访问（全部本地）。
+
+### 依赖
+
+运行时依赖：`@deepseek-ai/cordis`、`@deepseek-ai/dsh-tools`、
+`@deepseek-ai/dsh-util-values`、`js-yaml`——全部精确锁版。无安装期生命周期脚本
+（`preinstall`/`install`/`postinstall`/`prepare`）；仅 `prepublishOnly`（构建）在发布时运行。
+
+### 失败边界
+
+- 所有写入都是原子的（临时文件 + rename），且限定在 `.iterate/` 下；写入中途崩溃
+  不会损坏 checkpoint / transcript。
+- 持久化失败以结构化 `{ ok: false, error }` 返回，而不是静默成功。
+- 修复编辑先备份再应用，验证失败自动回滚。
+- 某个 slot / 服务不可用时 UI 优雅降级。
+
+---
+
 ## 🎨 设计
 
 插件遵循 dsh "everything-is-a-plugin" 架构：

package/dist/config-write.js

@@ -91,6 +91,27 @@ export function validateConfigUpdates(updates) {
             errors.push('updates.validation.commands must be an object of command arrays');
         }
     }
+    if ('observatory' in updates) {
+        const o = updates.observatory;
+        if (!o || typeof o !== 'object') {
+            errors.push('updates.observatory must be an object');
+        }
+        else {
+            if (o.capture !== undefined && typeof o.capture !== 'boolean') {
+                errors.push('updates.observatory.capture must be a boolean');
+            }
+            // The approval policy is the AUTHORITATIVE human-consent seam for
+            // destructive iterate tools (session-hooks.ts reads it at call time).
+            // Letting the model flip it to `allow` via a config write would bypass
+            // the gate entirely, so model-driven approval changes are refused
+            // fail-closed — the value can only be set by editing the config file
+            // directly (a human action the approval seam can trust).
+            if ('approval' in o) {
+                errors.push('updates.observatory.approval cannot be changed through iterate_config — ' +
+                    'edit iterate.config.yaml directly (the approval gate is human-controlled)');
+            }
+        }
+    }
     if ('personalization' in updates && (!updates.personalization || typeof updates.personalization !== 'object')) {
         errors.push('updates.personalization must be an object');
     }
@@ -105,6 +126,12 @@ export function applyConfigUpdates(base, updates) {
     for (const [key, value] of Object.entries(updates)) {
         if (value === undefined)
             continue;
+        // Prototype-pollution guard (mirrors config-loader.mergeConfig): a
+        // caller-supplied `__proto__`/`constructor`/`prototype` key must never be
+        // plain-assigned — on a plain object `out['__proto__'] = value` would set
+        // the object's prototype instead of an own property.
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+            continue;
         const baseValue = out[key];
         if (baseValue &&
             typeof baseValue === 'object' &&

package/dist/review-scope.js

@@ -21,7 +21,7 @@
  * cleanly; collectScopeFiles walks the filesystem.
  */
 import { readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, relative } from 'node:path';
 /** Relative-scope sentinel for whole-module findings. */
 export const WHOLE_FILE_LINE = 0;
 /** Source extensions a full-scope walk includes. */
@@ -124,8 +124,16 @@ function collectFull(root) {
                 continue;
             if (!sourceExt(entry.name))
                 continue;
-            const rel = abs.startsWith(root + SEP) ? abs.slice(root.length + 1) : abs;
-            out.push(rel.split(SEP).join(SEP));
+            // Derive the inventory path relative to the root via path.relative (then
+            // canonicalize separators). The old `abs.slice(root.length + 1)` string
+            // prefix was only correct on POSIX: on Windows path.join emits '\\' while
+            // this module's SEP is '/', so the prefix never matched and the ABSOLUTE
+            // path leaked into the inventory. path.relative is separator-agnostic and
+            // always yields a path strictly inside `root`.
+            const rel = normalizePath(relative(root, abs));
+            if (rel === '' || rel === '.' || rel.startsWith('../') || rel === '..')
+                continue;
+            out.push(rel);
         }
     }
     return out.sort();

package/dist/review.js

@@ -219,11 +219,17 @@ function summarize(findings) {
  */
 export function buildReviewReport(input) {
     // 1. Filter known-intentional per round (before cross-round dedupe).
-    const filteredRounds = input.rounds.map((r) => ({
+    const filteredRounds = input.rounds
+        .map((r) => ({
         round: typeof r?.round === 'number' ? r.round : 0,
         findings: filterKnownIntentional(Array.isArray(r?.findings) ? r.findings : [], input.knownIntentional),
         readFiles: Array.isArray(r?.readFiles) ? r.readFiles : [],
-    }));
+    }))
+        // Sort by round number so convergence math below (and the meta-review
+        // audit, which reads the LAST element as the highest round) never depends
+        // on the caller's array order. A resumed run that only passes [round 5]
+        // must be audited as round 5, not as "one round with no number".
+        .sort((a, b) => a.round - b.round);
     // 2. Cross-round dedupe + per-round "first seen" tracking.
     const { findings, findingsByRound } = aggregateRounds(filteredRounds, input.maxReviewRounds);
     // 3. Severity sort the global result.
@@ -234,7 +240,11 @@ export function buildReviewReport(input) {
     //    using its reported round number — NOT `filteredRounds.length - 1`, which
     //    is only valid for contiguous 1..N round numbers (resumed iterations and
     //    non-contiguous round sets would otherwise read the wrong count).
-    const lastRound = filteredRounds.length > 0 ? filteredRounds[filteredRounds.length - 1].round : 0;
+    let lastRound = 0;
+    for (const r of filteredRounds) {
+        if (typeof r.round === 'number' && r.round > lastRound)
+            lastRound = r.round;
+    }
     const lastRoundCount = lastRound > 0 ? (findingsByRound[lastRound - 1] ?? 0) : 0;
     const converged = filteredRounds.length > 0 && lastRoundCount === 0;
     // Attach the normal-mode fix count to the summary (dry-run leaves it absent).

package/dist/tools/checkpoint.js

@@ -14,6 +14,9 @@ import { resolveProjectRootForExec } from "../config-loader.js";
 import { checkpointPath, iterateDir, transcriptPath } from "../paths.js";
 import { readRegistry } from "./fix.js";
 import { readDecisionEntries } from "./decision-log.js";
+import { readQualityGate } from "./quality-store.js";
+import { readExperienceBank } from "./experience-store.js";
+import { readDefenseEvents } from "./defense-store.js";
 // ─── Pure helpers (exported for unit tests) ─────────────────────────────────
 /** Read the current checkpoint from disk (missing/corrupt → null). */
 export function readCheckpoint(projectRoot) {
@@ -116,6 +119,12 @@ export function computeStatus(input) {
         resumeCount: checkpoint?.resumeCount ?? 0,
         checkpoint,
         lastUpdated,
+        // v3.0: quality command-center snapshots (present only when the caller
+        // supplied a real snapshot — the status never fabricates one that is not
+        // on disk, and never emits null for an absent optional field).
+        ...(input.qualityGate != null ? { qualityGate: input.qualityGate } : {}),
+        ...(input.experienceBank != null ? { experienceBank: input.experienceBank } : {}),
+        ...(input.defenseEvents != null ? { defenseEvents: input.defenseEvents } : {}),
     };
 }
 // ─── iterate_checkpoint ──────────────────────────────────────────────────────
@@ -126,14 +135,16 @@ export function computeStatus(input) {
 export function registerCheckpointTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_checkpoint',
-        description: 'Save / load / clear the iteration checkpoint. The workflow saves a checkpoint at the start of ' +
-            'each round (so a long run can resume) and clears it when the iteration completes.',
+        description: 'Save / load / resume / clear the iteration checkpoint. The workflow saves a checkpoint at the start of ' +
+            'each round (so a long run can resume) and clears it when the iteration completes. ' +
+            '`resume` loads an existing checkpoint, bumps its resumeCount, and persists it back — ' +
+            'call it when continuing an interrupted run so the resume counter stays accurate.',
         parameters: {
             operation: {
                 type: 'string',
                 required: true,
-                description: '"save" to persist the current progress, "load" to read it back, "clear" to remove it.',
-                enum: ['save', 'load', 'clear'],
+                description: '"save" to persist the current progress, "load" to read it back, "resume" to load + count a resumption, "clear" to remove it.',
+                enum: ['save', 'load', 'resume', 'clear'],
             },
             mode: { type: 'string', description: 'Required for save: "dry-run" or "normal".' },
             round: { type: 'integer', description: 'Required for save: current round number (0 = none started).' },
@@ -169,6 +180,28 @@ export function registerCheckpointTool(ctx) {
                 const checkpoint = readCheckpoint(projectRoot);
                 return { operation: 'load', ok: true, checkpoint: checkpoint };
             }
+            if (args.operation === 'resume') {
+                const current = readCheckpoint(projectRoot);
+                if (!current) {
+                    return { operation: 'resume', ok: false, error: 'no checkpoint to resume — run `save` first' };
+                }
+                const resumed = {
+                    ...current,
+                    resumeCount: (current.resumeCount ?? 0) + 1,
+                    updatedAt: new Date().toISOString(),
+                };
+                try {
+                    mkdirSync(iterateDir(projectRoot), { recursive: true });
+                    const cpPath = checkpointPath(projectRoot);
+                    const tmpPath = `${cpPath}.tmp-${Date.now()}`;
+                    writeFileSync(tmpPath, JSON.stringify(resumed, null, 2), 'utf-8');
+                    renameSync(tmpPath, cpPath);
+                }
+                catch (err) {
+                    return { operation: 'resume', ok: false, error: `failed to persist resumed checkpoint: ${String(err)}` };
+                }
+                return { operation: 'resume', ok: true, checkpoint: resumed };
+            }
             if (args.operation === 'clear') {
                 const existed = existsSync(checkpointPath(projectRoot));
                 if (existed) {
@@ -217,7 +250,7 @@ export function registerCheckpointTool(ctx) {
                 }
                 return { operation: 'save', ok: true, checkpoint: checkpoint };
             }
-            return { operation: args.operation, ok: false, error: 'unknown operation. Use "save", "load", or "clear".' };
+            return { operation: args.operation, ok: false, error: 'unknown operation. Use "save", "load", "resume", or "clear".' };
         },
     }));
 }
@@ -252,6 +285,9 @@ export function registerStatusTool(ctx) {
                     interrupted: { type: 'boolean', description: 'True when a checkpoint exists, meaning the previous run was interrupted before finishing.' },
                     resumeCount: { type: 'integer', description: 'How many times the current checkpoint has already been resumed.' },
                     lastUpdated: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+                    qualityGate: { type: 'json', description: 'v3.0: persisted quality-gate snapshot (.iterate/quality-gate.json), when present.' },
+                    experienceBank: { type: 'json', description: 'v3.0: experience bank summary (.iterate/experience.json), when present.' },
+                    defenseEvents: { type: 'json', description: 'v3.0: defense events summary (.iterate/defense-events.json), when present.' },
                     error: { type: 'string' },
                 },
             },
@@ -275,11 +311,30 @@ export function registerStatusTool(ctx) {
             if (!resolved.ok)
                 return { ok: false, error: resolved.reason };
             const projectRoot = resolved.root;
+            // v3.0: surface the persisted quality command-center snapshots so a
+            // single `iterate_status` call reports the whole run state — the gate,
+            // the experience bank, and the defense event stream. Each read is
+            // defensive (missing/malformed files yield an empty snapshot), so the
+            // status never crashes on absent artifacts.
+            const qualityGate = readQualityGate(projectRoot);
+            const experienceBank = readExperienceBank(projectRoot);
+            const defenseEvents = readDefenseEvents(projectRoot);
             const status = computeStatus({
                 checkpoint: readCheckpoint(projectRoot),
                 taskMode: readTranscriptTaskMode(projectRoot),
                 decisionEntries: readDecisionEntries(projectRoot),
                 fixRegistry: readRegistry(projectRoot),
+                qualityGate: qualityGate.dimensions.length > 0 || qualityGate.overallStatus === 'pass' || qualityGate.overallStatus === 'fail'
+                    ? qualityGate
+                    : null,
+                experienceBank: {
+                    totalEntries: experienceBank.entries.length,
+                    totalHits: experienceBank.totalHits ?? 0,
+                },
+                defenseEvents: {
+                    totalEvents: defenseEvents.events.length,
+                    counts: defenseEvents.counts,
+                },
             });
             return {
                 ok: true,
@@ -295,6 +350,9 @@ export function registerStatusTool(ctx) {
                 interrupted: status.interrupted,
                 resumeCount: status.resumeCount,
                 lastUpdated: status.lastUpdated ?? null,
+                qualityGate: status.qualityGate ? status.qualityGate : null,
+                experienceBank: status.experienceBank ? status.experienceBank : null,
+                defenseEvents: status.defenseEvents ? status.defenseEvents : null,
             };
         },
     }));

package/dist/tools/defense-events.js

@@ -56,6 +56,9 @@ function validateRecordInput(args) {
     if (typeof args.outcome !== 'string' || !args.outcome.trim()) {
         errors.push('outcome is required');
     }
+    if (args.line !== undefined && (typeof args.line !== 'number' || !Number.isInteger(args.line) || args.line < 0)) {
+        errors.push('line must be a non-negative integer when present');
+    }
     const severity = args.severity;
     if (severity !== 'critical' && severity !== 'high' && severity !== 'medium' && severity !== 'low') {
         errors.push('severity must be one of critical, high, medium, low');

package/dist/tools/defense-store.js

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

package/dist/tools/history.js

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

package/dist/tools/quality-store.js

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

package/dist/transcript.js

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

package/lib/client.js

@@ -1525,6 +1525,7 @@ var ITERATE_CSS = `
 /* Dashboard empty/onboarding state */
 .iterate-dashboard-empty { opacity: 0.75; }
 .iterate-empty-hint { font-size: 12px; color: var(--dsw-alias-label-secondary); }
+.iterate-dashboard-launch { display: inline-flex; align-items: center; gap: 6px; }
 
 /* Convergence-completed progress fill */
 .iterate-progress-fill-done { background: var(--dsw-alias-state-success-primary); }
@@ -1748,6 +1749,31 @@ function TrendChart({ points }) {
     "aria-label": `\u5404\u8F6E\u53D1\u73B0\u6570\u91CF\u8D8B\u52BF\uFF1A${summary}`
   }, ...bars);
 }
+function StartIterationButton() {
+  const [copied, setCopied] = React.useState(null);
+  const copy = (key, text) => {
+    copyText(text).then((ok) => {
+      if (ok) {
+        setCopied(key);
+        setTimeout(() => setCopied((cur) => cur === key ? null : cur), 1600);
+      }
+    });
+  };
+  const btn = (key, label, command, primary, title) => React.createElement("button", {
+    key,
+    className: "iterate-cmd",
+    "data-primary": primary ? "" : void 0,
+    "data-copied": copied === key ? "" : void 0,
+    onClick: () => copy(key, command),
+    title
+  }, copied === key ? "\u5DF2\u590D\u5236" : label);
+  return React.createElement(
+    "span",
+    { className: "iterate-dashboard-launch" },
+    btn("start-full", "\u5B8C\u6574\u8FED\u4EE3", "/iterate", true, "\u590D\u5236\u542F\u52A8\u547D\u4EE4\uFF1A\u5B8C\u6574\u300C\u5BA1\u67E5 \u2192 \u4FEE\u590D \u2192 \u9A8C\u8BC1\u300D\u95ED\u73AF"),
+    btn("start-review", "\u4EC5\u8BC4\u5BA1", "/iterate review-only", false, "\u590D\u5236\u542F\u52A8\u547D\u4EE4\uFF1A\u53EA\u5BA1\u67E5\u4E0D\u4FEE\u6539\uFF08dry-run\uFF09")
+  );
+}
 function ConvergenceDashboard(props) {
   const [pulseKey, setPulseKey] = React.useState(0);
   const session = props && props.session ? props.session : null;
@@ -1764,7 +1790,8 @@ function ConvergenceDashboard(props) {
       "div",
       { "data-iterate-root": "", "data-iterate": "dashboard", className: "iterate-dashboard iterate-dashboard-empty" },
       React.createElement("span", { className: "iterate-round-badge" }, "iterate"),
-      React.createElement("span", { className: "iterate-empty-hint" }, "\u8FD0\u884C\u4E00\u6B21\u8BC4\u5BA1\u540E\uFF0C\u8FD9\u91CC\u4F1A\u663E\u793A\u6536\u655B\u8FDB\u5EA6\u4E0E\u53D1\u73B0\u7EDF\u8BA1\u3002\u8BD5\u8BD5\u300Creview this project\u300D\u6216\u300C/iterate review-only\u300D")
+      React.createElement("span", { className: "iterate-empty-hint" }, "\u8FD0\u884C\u4E00\u6B21\u8BC4\u5BA1\u540E\uFF0C\u8FD9\u91CC\u4F1A\u663E\u793A\u6536\u655B\u8FDB\u5EA6\u4E0E\u53D1\u73B0\u7EDF\u8BA1\u3002"),
+      React.createElement(StartIterationButton, null)
     );
   }
   const round = getCurrentRound(report);
@@ -3060,7 +3087,7 @@ ${JSON.stringify({
           "data-primary": "",
           "data-copied": copiedKey === "cp-resume" ? "" : void 0,
           onClick: () => copyInstruction("cp-resume", resumeText),
-          title: "\u590D\u5236 iterate_checkpoint \u7EFC/\u6062\u590D\u6307\u4EE4\u6587\u672C"
+          title: "\u590D\u5236 iterate_checkpoint resume \u6307\u4EE4\u6587\u672C\uFF08\u52A0\u8F7D\u65AD\u70B9\u5E76\u8BA1\u6570\u4E00\u6B21\u6062\u590D\uFF09"
         }, copiedKey === "cp-resume" ? "\u5DF2\u590D\u5236" : "\u590D\u5236\u6062\u590D\u6307\u4EE4")
       )
     );

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "iterate-plugin",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "dsh plugin that turns the iterate skill into an autonomous closed-loop harness with quality command center and experience bank (v3.3). Features: plan -> parallel review xN -> atomic fixes -> validate -> loop -> auto-stop, plus dry-run pure-review mode, quality gate compute/persist, writable experience bank, defense events stream (record + bilingual labels), and native command buttons — with a live quality command center (F8/F9/F10 render real session data), §8 assign-fix instruction, and task_mode indicator wired end to end.",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jingzhao-l/iterate-plugin.git"
+    "url": "https://github.com/jingzhao-l/iterate-skill.git",
+    "directory": "harness/iterate-plugin"
   },
-  "homepage": "https://github.com/jingzhao-l/iterate-plugin#readme",
+  "homepage": "https://github.com/jingzhao-l/iterate-skill/tree/main/harness/iterate-plugin",
   "bugs": {
-    "url": "https://github.com/jingzhao-l/iterate-plugin/issues"
+    "url": "https://github.com/jingzhao-l/iterate-skill/issues"
   },
   "keywords": [
     "dsh-plugin",
@@ -26,6 +27,13 @@
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
+    "compatibility": {
+      "dshReleases": {
+        "0.1.2-alpha.4": "compatible",
+        "0.1.2-alpha.5": "compatible",
+        "0.1.2-rc.1": "compatible"
+      }
+    },
     "client": {
       "platform": "web",
       "inject": [

package/src/client/index.ts

@@ -567,6 +567,7 @@ const ITERATE_CSS = `
 /* Dashboard empty/onboarding state */
 .iterate-dashboard-empty { opacity: 0.75; }
 .iterate-empty-hint { font-size: 12px; color: var(--dsw-alias-label-secondary); }
+.iterate-dashboard-launch { display: inline-flex; align-items: center; gap: 6px; }
 
 /* Convergence-completed progress fill */
 .iterate-progress-fill-done { background: var(--dsw-alias-state-success-primary); }
@@ -834,6 +835,36 @@ function TrendChart({ points }: { points: Array<{ round: number; count: number }
   }, ...bars)
 }
 
+/** Start-iteration launcher shown on the empty dashboard: copies a runnable
+ *  command (the browser cannot invoke harness tools directly, so every action
+ *  follows the panel's copy-to-command pattern). */
+function StartIterationButton() {
+  const [copied, setCopied] = React.useState<string | null>(null)
+  const copy = (key: string, text: string) => {
+    copyText(text).then((ok) => {
+      if (ok) {
+        setCopied(key)
+        setTimeout(() => setCopied((cur) => (cur === key ? null : cur)), 1600)
+      }
+    })
+  }
+  const btn = (key: string, label: string, command: string, primary: boolean, title: string) =>
+    React.createElement('button', {
+      key,
+      className: 'iterate-cmd',
+      'data-primary': primary ? '' : undefined,
+      'data-copied': copied === key ? '' : undefined,
+      onClick: () => copy(key, command),
+      title,
+    }, copied === key ? '已复制' : label)
+  return React.createElement(
+    'span',
+    { className: 'iterate-dashboard-launch' },
+    btn('start-full', '完整迭代', '/iterate', true, '复制启动命令：完整「审查 → 修复 → 验证」闭环'),
+    btn('start-review', '仅评审', '/iterate review-only', false, '复制启动命令：只审查不修改（dry-run）'),
+  )
+}
+
 /** Dashboard: live convergence strip above the composer.
  *
  * The `conversation.input.dock` slot's owner share is `InputZone`, which
@@ -859,12 +890,15 @@ function ConvergenceDashboard(props: SlotProps) {
 
   if (!report) {
     // Empty/onboarding state: first-time users otherwise see nothing and have
-    // no idea the plugin exists or how to start.
+    // no idea the plugin exists or how to start. Provide a one-click command
+    // that launches the loop (copied for paste — the browser cannot call
+    // harness tools directly).
     return React.createElement(
       'div',
       { 'data-iterate-root': '', 'data-iterate': 'dashboard', className: 'iterate-dashboard iterate-dashboard-empty' },
       React.createElement('span', { className: 'iterate-round-badge' }, 'iterate'),
-      React.createElement('span', { className: 'iterate-empty-hint' }, '运行一次评审后，这里会显示收敛进度与发现统计。试试「review this project」或「/iterate review-only」'),
+      React.createElement('span', { className: 'iterate-empty-hint' }, '运行一次评审后，这里会显示收敛进度与发现统计。'),
+      React.createElement(StartIterationButton, null),
     )
   }
 
@@ -2151,7 +2185,7 @@ function ObservatoryPanel(props: SlotProps) {
         React.createElement('button', {
           className: 'iterate-btn', 'data-primary': '', 'data-copied': copiedKey === 'cp-resume' ? '' : undefined,
           onClick: () => copyInstruction('cp-resume', resumeText),
-          title: '复制 iterate_checkpoint 综/恢复指令文本',
+          title: '复制 iterate_checkpoint resume 指令文本（加载断点并计数一次恢复）',
         }, copiedKey === 'cp-resume' ? '已复制' : '复制恢复指令'),
       ),
     )

package/src/config-write.ts

@@ -92,6 +92,28 @@ export function validateConfigUpdates(updates: Record<string, unknown>): string[
       errors.push('updates.validation.commands must be an object of command arrays')
     }
   }
+  if ('observatory' in updates) {
+    const o = updates.observatory as Record<string, unknown> | undefined
+    if (!o || typeof o !== 'object') {
+      errors.push('updates.observatory must be an object')
+    } else {
+      if (o.capture !== undefined && typeof o.capture !== 'boolean') {
+        errors.push('updates.observatory.capture must be a boolean')
+      }
+      // The approval policy is the AUTHORITATIVE human-consent seam for
+      // destructive iterate tools (session-hooks.ts reads it at call time).
+      // Letting the model flip it to `allow` via a config write would bypass
+      // the gate entirely, so model-driven approval changes are refused
+      // fail-closed — the value can only be set by editing the config file
+      // directly (a human action the approval seam can trust).
+      if ('approval' in o) {
+        errors.push(
+          'updates.observatory.approval cannot be changed through iterate_config — ' +
+          'edit iterate.config.yaml directly (the approval gate is human-controlled)',
+        )
+      }
+    }
+  }
   if ('personalization' in updates && (!updates.personalization || typeof updates.personalization !== 'object')) {
     errors.push('updates.personalization must be an object')
   }
@@ -109,6 +131,11 @@ export function applyConfigUpdates(
   const out: Record<string, unknown> = { ...base }
   for (const [key, value] of Object.entries(updates)) {
     if (value === undefined) continue
+    // Prototype-pollution guard (mirrors config-loader.mergeConfig): a
+    // caller-supplied `__proto__`/`constructor`/`prototype` key must never be
+    // plain-assigned — on a plain object `out['__proto__'] = value` would set
+    // the object's prototype instead of an own property.
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') continue
     const baseValue = out[key]
     if (
       baseValue &&

package/src/review-scope.ts

@@ -22,7 +22,7 @@
  */
 
 import { readdirSync } from 'node:fs'
-import { join } from 'node:path'
+import { join, relative } from 'node:path'
 
 export interface CoverageResult {
   assigned: string[]
@@ -135,8 +135,15 @@ function collectFull(root: string): string[] {
       }
       if (!entry.isFile()) continue
       if (!sourceExt(entry.name)) continue
-      const rel = abs.startsWith(root + SEP) ? abs.slice(root.length + 1) : abs
-      out.push(rel.split(SEP).join(SEP))
+      // Derive the inventory path relative to the root via path.relative (then
+      // canonicalize separators). The old `abs.slice(root.length + 1)` string
+      // prefix was only correct on POSIX: on Windows path.join emits '\\' while
+      // this module's SEP is '/', so the prefix never matched and the ABSOLUTE
+      // path leaked into the inventory. path.relative is separator-agnostic and
+      // always yields a path strictly inside `root`.
+      const rel = normalizePath(relative(root, abs))
+      if (rel === '' || rel === '.' || rel.startsWith('../') || rel === '..') continue
+      out.push(rel)
     }
   }
   return out.sort()

package/src/review.ts

@@ -247,14 +247,20 @@ export function buildReviewReport(input: {
   fixedCount?: number
 }): ReviewReport {
   // 1. Filter known-intentional per round (before cross-round dedupe).
-  const filteredRounds = input.rounds.map((r) => ({
-    round: typeof r?.round === 'number' ? r.round : 0,
-    findings: filterKnownIntentional(
-      Array.isArray(r?.findings) ? r.findings : [],
-      input.knownIntentional,
-    ),
-    readFiles: Array.isArray(r?.readFiles) ? r.readFiles : [],
-  }))
+  const filteredRounds = input.rounds
+    .map((r) => ({
+      round: typeof r?.round === 'number' ? r.round : 0,
+      findings: filterKnownIntentional(
+        Array.isArray(r?.findings) ? r.findings : [],
+        input.knownIntentional,
+      ),
+      readFiles: Array.isArray(r?.readFiles) ? r.readFiles : [],
+    }))
+    // Sort by round number so convergence math below (and the meta-review
+    // audit, which reads the LAST element as the highest round) never depends
+    // on the caller's array order. A resumed run that only passes [round 5]
+    // must be audited as round 5, not as "one round with no number".
+    .sort((a, b) => a.round - b.round)
 
   // 2. Cross-round dedupe + per-round "first seen" tracking.
   const { findings, findingsByRound } = aggregateRounds(
@@ -271,8 +277,10 @@ export function buildReviewReport(input: {
   //    using its reported round number — NOT `filteredRounds.length - 1`, which
   //    is only valid for contiguous 1..N round numbers (resumed iterations and
   //    non-contiguous round sets would otherwise read the wrong count).
-  const lastRound =
-    filteredRounds.length > 0 ? filteredRounds[filteredRounds.length - 1]!.round : 0
+  let lastRound = 0
+  for (const r of filteredRounds) {
+    if (typeof r.round === 'number' && r.round > lastRound) lastRound = r.round
+  }
   const lastRoundCount =
     lastRound > 0 ? (findingsByRound[lastRound - 1] ?? 0) : 0
   const converged = filteredRounds.length > 0 && lastRoundCount === 0

package/src/tools/checkpoint.ts

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

package/src/tools/defense-events.ts

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

package/src/tools/defense-store.ts

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

package/src/tools/history.ts

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

package/src/tools/quality-store.ts

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

package/src/transcript.ts

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