iterate-plugin 3.4.1 → 3.5.1

package/README.md

@@ -123,7 +123,7 @@ Beyond the 17 registered tools (full reference further down), the plugin closes
 - **Structured fix system** — each fix backs up first, writes a registry entry, records the diff; a failed validation can be reverted with `iterate_rollback`
 - **Breakpoint resume** — checkpoints saved at the start of each round; interrupted long iterations can resume
 - **History audit** — `iterate_history` reads the decision log (filtered by type / time / count) and the fix-registry summary to audit run process and fix details
-- **Runtime cleanup** — `iterate_prune` removes stale decision-log entries, stale checkpoints, orphaned fix backups and empty rounds; dry-run by default (report-only), real cleanup requires `dryRun:false`, and every cleanup is logged
+- **Runtime cleanup** — `iterate_prune` removes stale decision-log entries, stale checkpoints, orphaned fix backups, empty rounds and stray temp files left by crashed atomic writes; dry-run by default (report-only), real cleanup requires `dryRun:false`, and every cleanup is logged
 - **Config read / write** — `iterate_config` supports validated, backed-up, rollback-capable partial writes
 - **v3.2 Experience Bank** — `iterate_experience` queries historical fixes and patterns with search / filter / adopt, and can persist new verified fixes (`add`) — re-adding the same pattern+dimension bumps its hit count instead of duplicating it
 - **v3.2 Quality Gate** — `iterate_quality_gate` reads quality gate status with per-dimension convergence rates and PASS/FAIL, and can recompute + persist a fresh certificate (`compute`) from this round's findings / validation results (real convergence from `findingsByRound`)
@@ -258,10 +258,10 @@ 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_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_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), or `add` a new verified fix: re-adding the same pattern+dimension bumps its hit count instead of duplicating it. 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
+- `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)
 
 ---

package/README.zh-CN.md

@@ -122,7 +122,7 @@ UI 层为**防御式设计**：`slots` / `theme` / `React` 任一不可用时自
 - **结构化修复系统** — 每次修复先备份、写注册表、记录 diff，验证失败可 `iterate_rollback` 还原
 - **断点续跑** — 长迭代在每轮开头保存 checkpoint，中断后可恢复进度
 - **历史审计** — `iterate_history` 读取决策日志（按类型/时间/数量过滤）与修复注册表汇总，审查运行过程与修复明细
-- **运行时清理** — `iterate_prune` 清理过期的决策日志条目、陈旧断点、孤儿修复备份与空轮次；默认 dry-run 只报告不删除，显式 `dryRun:false` 才真正清理，每次清理写入决策日志
+- **运行时清理** — `iterate_prune` 清理过期的决策日志条目、陈旧断点、孤儿修复备份、空轮次与原子写入崩溃残留的临时文件；默认 dry-run 只报告不删除，显式 `dryRun:false` 才真正清理，每次清理写入决策日志
 - **配置读写** — `iterate_config` 支持带校验、备份、回滚的局部写入
 - **v3.2 经验银行** — `iterate_experience` 以检索 / 过滤 / 采纳查阅历史修复与模式，并可 `add` 持久化新的已验证修复——重复添加同一 pattern + dimension 时累加命中次数而非重复写入
 - **v3.2 质量门禁** — `iterate_quality_gate` 读取质量门禁状态（各维度收敛率 + PASS/FAIL），并可基于本轮 findings / 验证结果 `compute` 重新计算并持久化一份新的质量凭证（收敛率来自 `findingsByRound` 的真实收敛序列）
@@ -257,10 +257,10 @@ validation:
 - `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_prune` — 清理运行时产物：过期决策日志条目（按 `retainDays`，默认 30 天）、陈旧断点、孤儿修复备份、空轮次、崩溃原子写入残留的临时文件。默认 dry-run 只报告不删除；`dryRun:false` 才真正清理，每次清理写入决策日志
 - `iterate_transcript` — 运行时观测台：把审查转录、线程、修复与 nudge 指令持久化到 `.iterate/transcript.json`，供客户端观测台读取
-- `iterate_experience` — **v3.2** 查询经验银行（list / search / get），或 `add` 一条新的已验证修复：重复添加同一 pattern + dimension 累加命中次数而非重复写入。持久化到 `.iterate/experience.json`
-- `iterate_quality_gate` — **v3.2** 读取质量凭证（`read`），或基于 findings、验证结果、`findingsByRound` 与 `fixedByDimension` 重新计算并持久化一份新凭证（`compute`）。真实的逐维度收敛率
+- `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）
 
 ---

package/dist/atomic-fs.js

@@ -0,0 +1,77 @@
+/**
+ * src/atomic-fs.ts — crash-safe file writes for all plugin state.
+ *
+ * Every JSON/YAML artifact the plugin persists (.iterate/*.json,
+ * iterate.config.yaml) is written through here: content goes to a
+ * uniquely-named temp file in the SAME directory as the target (rename is
+ * only atomic within one filesystem), then is `renameSync`ed over the
+ * destination. A crash mid-write can therefore leave a stale temp file
+ * behind, but never a truncated / half-written state file — readers
+ * (which all tolerate missing/corrupt files) see either the previous or
+ * the new content, never a mixture.
+ */
+import { dirname, join } from 'node:path';
+import { renameSync, rmSync, writeFileSync } from 'node:fs';
+import { rename, rm, writeFile } from 'node:fs/promises';
+/** Best-effort unlink of a leftover temp file (never throws). */
+function cleanupTemp(tmp) {
+    try {
+        rmSync(tmp, { force: true });
+    }
+    catch {
+        /* ignore — temp files follow the prunable `.tmp-<pid>-<rand>` convention */
+    }
+}
+/** Best-effort async unlink of a leftover temp file (never throws). */
+async function cleanupTempAsync(tmp) {
+    try {
+        await rm(tmp, { force: true });
+    }
+    catch {
+        /* ignore — temp files follow the prunable `.tmp-<pid>-<rand>` convention */
+    }
+}
+/**
+ * Unique temp file path for `filePath`, in the same directory, following the
+ * prunable `.<basename>.tmp-<pid>-<random>` convention (see prune.ts
+ * `isPrunableTemp`). The pid+random suffix makes concurrent writers safe.
+ */
+function tempPathFor(filePath) {
+    return join(dirname(filePath), `.${filePath.split('/').pop() ?? 'file'}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`);
+}
+/**
+ * Write `data` to `filePath` atomically (temp file + rename, same dir).
+ * Temp files follow the `<name>.tmp-<pid>-<random>` convention also used by
+ * prune.ts / checkpoint.ts so they are recognizable and prunable.
+ * Throws on failure (callers own error reporting — they map failures to
+ * structured tool results).
+ */
+export function writeTextAtomic(filePath, data) {
+    const tmp = tempPathFor(filePath);
+    writeFileSync(tmp, data, 'utf-8');
+    try {
+        renameSync(tmp, filePath);
+    }
+    catch (err) {
+        // Best-effort temp cleanup so a failed write never litters the directory.
+        cleanupTemp(tmp);
+        throw err;
+    }
+}
+/** Async variant of {@link writeTextAtomic} (same temp naming convention). */
+export async function writeTextAtomicAsync(filePath, data) {
+    const tmp = tempPathFor(filePath);
+    await writeFile(tmp, data, 'utf-8');
+    try {
+        await rename(tmp, filePath);
+    }
+    catch (err) {
+        // Best-effort temp cleanup so a failed write never litters the directory.
+        await cleanupTempAsync(tmp);
+        throw err;
+    }
+}
+/** JSON.stringify (2-space indent) + atomic write in one call. */
+export function writeJsonAtomic(filePath, value) {
+    writeTextAtomic(filePath, JSON.stringify(value, null, 2));
+}

package/dist/config-write.js

@@ -9,9 +9,10 @@
  * The security posture mirrors the triage tool: never overwrite a malformed
  * config, always back up before writing, roll back on failure.
  */
-import { copyFileSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import yaml from 'js-yaml';
+import { writeTextAtomic } from "./atomic-fs.js";
 /** Config file name (must match config-loader). */
 export const CONFIG_FILE = 'iterate.config.yaml';
 /** Backup suffix helper (filesystem-safe timestamp). */
@@ -185,7 +186,7 @@ export function writeConfigFile(projectRoot, config) {
         }
     }
     try {
-        writeFileSync(configPath, yaml.dump(config, { noRefs: true }), 'utf-8');
+        writeTextAtomic(configPath, yaml.dump(config, { noRefs: true }));
     }
     catch (err) {
         let rollbackError = '';

package/dist/live.js

@@ -23,8 +23,9 @@
  *   - Any capture failure is swallowed (fire-and-forget) so it can never block
  *     or crash a tool call.
  */
-import { mkdir, readFile, writeFile, stat, appendFile, rename } from 'node:fs/promises';
+import { mkdir, readFile, stat, appendFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
+import { writeTextAtomicAsync } from "./atomic-fs.js";
 import { join } from 'node:path';
 import { resolveProjectRoot } from "./config-loader.js";
 /** Keep at most this many live activity entries. */
@@ -68,6 +69,11 @@ export function classifyTool(name, args, projectRoot) {
         iterate_status: 'info',
         iterate_config: 'info',
         iterate_context: 'info',
+        // v3.0 quality command-center tools — surface their activity in the live
+        // feed too (previously these three never produced a live entry).
+        iterate_experience: 'info',
+        iterate_quality_gate: 'info',
+        iterate_defense_events: 'info',
     };
     const type = records[name];
     if (!type)
@@ -101,9 +107,9 @@ export async function appendLive(projectRoot, entry) {
             const raw = await readFile(file, 'utf-8');
             const lines = raw.split('\n').filter(Boolean);
             const tail = lines.slice(-LIVE_MAX_ENTRIES);
-            const tmp = `${file}.trim.tmp`;
-            await writeFile(tmp, tail.join('\n') + '\n', 'utf-8');
-            await rename(tmp, file);
+            // Atomic rewrite (unique temp + rename) so a crash mid-trim never
+            // truncates the live feed; the temp file is prunable by iterate_prune.
+            await writeTextAtomicAsync(file, tail.join('\n') + '\n');
         }
         await appendFile(file, line, 'utf-8');
     }

package/dist/skill-prompt.js

@@ -23,8 +23,8 @@ You have the iterate plugin installed, which registers these tools:
 - \`iterate_history\` — inspect the runtime state in detail: decision-log entries and applied fixes (optionally scoped to a round or a fixed file)
 - \`iterate_prune\` — remove stale runtime artifacts (\`.iterate/\` entries). Defaults to a read-only dry-run that reports what WOULD be removed; pass \`dryRun:false\` to actually prune.
 - \`iterate_transcript\` — runtime observatory file (\`.iterate/transcript.json\`). \`read\` fetches the persisted manifest including any steering \`nudge\` for this run's reviewers; \`capture\` (call once after the final report) persists the per-reviewer threads, convergence trend, findings, fixes, checkpoint, and timeline so the client observatory panel reflects the run; \`nudge\` sets/clears steering text the next round's reviewers read. Purely local, never touches source files.
-- \`iterate_experience\` — experience bank (\`.iterate/experience.json\`): \`list\`/\`search\`/\`get\` recall verified fixes and patterns from past sessions (read the bank before fixing so proven fixes are applied first); \`add\` records a new verified fix — re-adding the same pattern+dimension bumps its hit count instead of duplicating it.
-- \`iterate_quality_gate\` — quality certificate: \`read\` loads the persisted dimension convergence rates / verification pass rate / PASS-FAIL status; \`compute\` recomputes a fresh snapshot from this round's findings + validation results (supply \`findingsByRound\` for real convergence) and persists it to \`.iterate/quality-gate.json\`.
+- \`iterate_experience\` — experience bank (\`.iterate/experience.json\`): \`list\`/\`search\`/\`get\` recall verified fixes and patterns from past sessions (read the bank before fixing so proven fixes are applied first); \`add\` records a new verified fix — re-adding the same pattern+dimension bumps its hit count instead of duplicating it; \`remove\` deletes a stale or incorrect entry by \`id\` so bad experiences never resurface.
+- \`iterate_quality_gate\` — quality certificate: \`read\` loads the persisted dimension convergence rates / verification pass rate / PASS-FAIL status; \`compute\` recomputes a fresh snapshot from this round's findings + validation results (supply \`findingsByRound\` for real convergence) and persists it to \`.iterate/quality-gate.json\`; \`clear\` removes the persisted certificate to reset a stale gate before a fresh iteration.
 - \`iterate_defense_events\` — defense event stream (\`.iterate/defense-events.json\`): \`list\`/\`counts\` review precondition failures, rollbacks, invariant violations, and falsified assumptions; \`record\` logs a new event when a defense fires. Human-readable labels follow the project \`language\` (en/zh).
 
 ### When to use

package/dist/tools/checkpoint.js

@@ -8,9 +8,10 @@
  *
  * Checkpoint layout: `.iterate/checkpoint.json`.
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
+import { writeJsonAtomic } from "../atomic-fs.js";
 import { checkpointPath, iterateDir, transcriptPath } from "../paths.js";
 import { readRegistry } from "./fix.js";
 import { readDecisionEntries } from "./decision-log.js";
@@ -192,10 +193,7 @@ export function registerCheckpointTool(ctx) {
                 };
                 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);
+                    writeJsonAtomic(checkpointPath(projectRoot), resumed);
                 }
                 catch (err) {
                     return { operation: 'resume', ok: false, error: `failed to persist resumed checkpoint: ${String(err)}` };
@@ -238,12 +236,10 @@ export function registerCheckpointTool(ctx) {
                 };
                 try {
                     mkdirSync(iterateDir(projectRoot), { recursive: true });
-                    // Atomic write (temp + rename): a crash mid-write must not corrupt
-                    // the checkpoint and silently lose the interruption state.
-                    const cpPath = checkpointPath(projectRoot);
-                    const tmpPath = `${cpPath}.tmp-${Date.now()}`;
-                    writeFileSync(tmpPath, JSON.stringify(checkpoint, null, 2), 'utf-8');
-                    renameSync(tmpPath, cpPath);
+                    // Atomic write (temp + rename, via writeJsonAtomic): a crash
+                    // mid-write must not corrupt the checkpoint and silently lose the
+                    // interruption state.
+                    writeJsonAtomic(checkpointPath(projectRoot), checkpoint);
                 }
                 catch (err) {
                     return { operation: 'save', ok: false, error: `failed to write checkpoint: ${String(err)}` };
@@ -262,6 +258,9 @@ export function registerCheckpointTool(ctx) {
 export function registerStatusTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_status',
+        // Read-only aggregation of on-disk state → safe to join a parallel
+        // dispatch group alongside other read-only sibling calls.
+        isConcurrencySafe: () => true,
         description: 'Summarize the current iterate run: mode, current round vs total, fixes applied, architectural ' +
             'findings remaining, decision-log size, and whether a resume checkpoint exists.',
         parameters: {
@@ -303,6 +302,27 @@ export function registerStatusTool(ctx) {
                     `Checkpoint: ${value.hasCheckpoint ? 'yes' : 'no'}${value.interrupted ? ' (interrupted — resumable)' : ''}${value.resumeCount ? ` · resumed ${value.resumeCount}x` : ''}`,
                     value.lastUpdated ? `Last updated: ${value.lastUpdated}` : '',
                 ];
+                // v3.0 quality command-center summaries (surfaced here so a single
+                // status read reports the whole run state in text too).
+                const gate = value.qualityGate;
+                if (gate) {
+                    lines.push(`Quality gate: ${gate.overallStatus.toUpperCase()} · score ${gate.overallScore} · ` +
+                        `verification ${gate.passedChecks}/${gate.totalChecks} passed` +
+                        (gate.failReason ? ` · ${gate.failReason}` : ''));
+                }
+                const exp = value.experienceBank;
+                if (exp) {
+                    lines.push(`Experience bank: ${exp.totalEntries ?? 0} entries · ${exp.totalHits ?? 0} cumulative hits`);
+                }
+                const def = value.defenseEvents;
+                if (def) {
+                    const counts = def.counts ?? {};
+                    const total = Object.values(counts).reduce((s, n) => s + (n || 0), 0);
+                    lines.push(`Defense events: ${def.totalEvents ?? total} recorded` +
+                        (total > 0
+                            ? ` (precondition_failed:${counts.precondition_failed ?? 0}, rollback:${counts.rollback ?? 0}, invariant_violated:${counts.invariant_violated ?? 0}, assumption_falsified:${counts.assumption_falsified ?? 0})`
+                            : ''));
+                }
                 return [{ type: 'text', text: lines.filter(Boolean).join('\n') }];
             },
         },

package/dist/tools/config.js

@@ -11,6 +11,20 @@ import { applyConfigUpdates, readRawConfig, validateConfigUpdates, writeConfigFi
 export function registerConfigTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_config',
+        // `read` never writes; `write` persists a config update → only read
+        // joins a parallel dispatch group.
+        isConcurrencySafe: (args) => args.operation !== 'write',
+        // Pending-call card: a config read vs a validated write.
+        presentCall: (args) => {
+            const a = args;
+            const isWrite = a.operation === 'write';
+            return {
+                card: 'generic',
+                title: isWrite ? 'Update iterate.config.yaml' : 'Read iterate.config.yaml',
+                kind: isWrite ? 'edit' : 'read',
+                ...(typeof a.section === 'string' && a.section ? { rawInput: { section: a.section } } : {}),
+            };
+        },
         description: 'Read or update the iterate.config.yaml configuration from the project root. ' +
             'Returns the full parsed config, a specific section, or validation errors. ' +
             'Use this to discover available dimensions, validation commands, git settings, and personalization rules, ' +

package/dist/tools/context.js

@@ -161,6 +161,9 @@ export { findSkillMd };
 export function registerContextTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_context',
+        // Read-only (reads SKILL.md / ITERATE.md) → safe to join a parallel
+        // dispatch group alongside other read-only sibling calls.
+        isConcurrencySafe: () => true,
         description: 'Read project context files (SKILL.md and/or ITERATE.md). ' +
             'SKILL.md contains the original iterate skill instructions; it is searched in ' +
             'the skill directory (auto-detected), the project root, or an explicit `skillDir`. ' +

package/dist/tools/decision-log.js

@@ -71,34 +71,44 @@ export function appendDecisionEntry(projectRoot, entry) {
     return { count, path: filePath };
 }
 /**
- * Read all entries from the decision log.
+ * Read all entries from the decision log, plus the count of corrupt lines.
  * A single corrupt line (partial write, hand-edit) is SKIPPED, not fatal —
- * one bad line must never empty the whole history for every reader.
+ * one bad line must never empty the whole history for every reader — but it
+ * is counted in `invalidLines` so it never disappears silently.
  */
-export function readDecisionEntries(projectRoot) {
+export function readDecisionLogDetailed(projectRoot) {
     const filePath = join(projectRoot, LOG_DIR, LOG_FILE);
     if (!existsSync(filePath))
-        return [];
+        return { entries: [], invalidLines: 0 };
     let content;
     try {
         content = readFileSync(filePath, 'utf-8');
     }
     catch {
-        return [];
+        return { entries: [], invalidLines: 0 };
     }
-    const out = [];
+    const entries = [];
+    let invalidLines = 0;
     for (const line of content.split('\n')) {
         const trimmed = line.trim();
         if (trimmed.length === 0)
             continue;
         try {
-            out.push(JSON.parse(trimmed));
+            entries.push(JSON.parse(trimmed));
         }
         catch {
-            // skip the corrupt line, keep the rest
+            invalidLines += 1;
         }
     }
-    return out;
+    return { entries, invalidLines };
+}
+/**
+ * Read all entries from the decision log.
+ * A single corrupt line (partial write, hand-edit) is SKIPPED, not fatal —
+ * one bad line must never empty the whole history for every reader.
+ */
+export function readDecisionEntries(projectRoot) {
+    return readDecisionLogDetailed(projectRoot).entries;
 }
 /**
  * Register the `iterate_decision_log` tool.
@@ -108,6 +118,9 @@ export function readDecisionEntries(projectRoot) {
 export function registerDecisionLogTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_decision_log',
+        // `read` never writes; `append` extends the audit log → only read joins
+        // a parallel dispatch group.
+        isConcurrencySafe: (args) => args.operation === 'read',
         description: 'Append-only decision log for the iterate loop. ' +
             'Use `append` to record a round start, review finding, fix, validation result, or decision. ' +
             'Use `read` to retrieve all entries for review. ' +
@@ -156,6 +169,7 @@ export function registerDecisionLogTool(ctx) {
                 properties: {
                     operation: { type: 'string', required: true },
                     entryCount: { type: 'integer' },
+                    invalidLines: { type: 'integer' },
                     logPath: { type: 'string' },
                     entries: { type: 'json' },
                     success: { type: 'boolean' },
@@ -174,10 +188,11 @@ export function registerDecisionLogTool(ctx) {
             }
             const projectRoot = resolved.root;
             if (args.operation === 'read') {
-                const entries = readDecisionEntries(projectRoot);
+                const { entries, invalidLines } = readDecisionLogDetailed(projectRoot);
                 return {
                     operation: 'read',
                     entryCount: entries.length,
+                    invalidLines,
                     logPath: join(projectRoot, LOG_DIR, LOG_FILE),
                     entries: entries,
                 };

package/dist/tools/defense-events.js

@@ -72,6 +72,9 @@ function validateRecordInput(args) {
 export function registerDefenseEventsTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_defense_events',
+        // List/counts never write; only `record` persists an event → read shapes
+        // join a parallel dispatch group.
+        isConcurrencySafe: (args) => args.operation !== 'record',
         description: 'Query or record defense events: precondition failures, rollbacks, invariant violations, ' +
             'and assumption falsifications. ' +
             'List/counts return events with descriptions, outcomes, and summary counts; ' +

package/dist/tools/defense-store.js

@@ -6,6 +6,8 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { iterateDir } from "../paths.js";
+import { writeJsonAtomic } from "../atomic-fs.js";
 const DEFENSE_EVENTS_FILE = 'defense-events.json';
 /** Valid defense event types (must stay in sync with DefenseEventType). */
 const VALID_EVENT_TYPES = new Set([
@@ -70,13 +72,15 @@ export function readDefenseEvents(projectRoot) {
  * an event that was never persisted.
  */
 export function writeDefenseEvents(projectRoot, stream) {
-    const dirPath = path.join(projectRoot, '.iterate');
+    const dirPath = iterateDir(projectRoot);
     const filePath = path.join(dirPath, DEFENSE_EVENTS_FILE);
     try {
         if (!fs.existsSync(dirPath)) {
             fs.mkdirSync(dirPath, { recursive: true });
         }
-        fs.writeFileSync(filePath, JSON.stringify(stream, null, 2), 'utf-8');
+        // Atomic (temp + rename): a crash mid-write can never leave a truncated
+        // defense event stream behind.
+        writeJsonAtomic(filePath, stream);
     }
     catch (err) {
         return { ok: false, error: `unable to write ${filePath}: ${String(err)}` };

package/dist/tools/experience-bank.js

@@ -7,7 +7,7 @@
  */
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
-import { readExperienceBank, writeExperienceBank, searchExperienceEntries, upsertExperience } from "./experience-store.js";
+import { readExperienceBank, writeExperienceBank, searchExperienceEntries, upsertExperience, removeExperience } from "./experience-store.js";
 const DEFAULT_LIMIT = 50;
 const MAX_LIMIT = 100;
 /** Clamp a caller-supplied limit to a sane range. */
@@ -67,17 +67,21 @@ function normalizeExperienceInput(raw) {
 export function registerExperienceBankTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_experience',
+        // List/search/get never write; only `add` upserts the bank → read shapes
+        // join a parallel dispatch group.
+        isConcurrencySafe: (args) => args.operation !== 'add',
         description: 'Query or extend the experience bank: browse/search historical fixes and patterns, ' +
             'or record a new verified fix (operation:"add"). ' +
             'List/search/get return matching entries with hit counts, verified fixes, and related context. ' +
             '"add" upserts an experience entry into .iterate/experience.json — a repeat of the same ' +
             'pattern+dimension increments its hit count instead of duplicating it. ' +
+            '"remove" deletes an entry by id (useful for pruning stale or incorrect experiences). ' +
             'Use it to remember fixes that worked so future rounds apply them first.',
         parameters: {
             operation: {
                 type: 'string',
-                description: 'Operation: list (browse all), search (by query), get (by id), add (add a new experience). Default: list.',
-                enum: ['list', 'search', 'get', 'add'],
+                description: 'Operation: list (browse all), search (by query), get (by id), add (add a new experience), remove (delete by id). Default: list.',
+                enum: ['list', 'search', 'get', 'add', 'remove'],
             },
             query: {
                 type: 'string',
@@ -144,6 +148,9 @@ export function registerExperienceBankTool(ctx) {
                                 `Tags: ${entry.tags.join(', ')}`,
                             ].join('\n') }];
                 }
+                if (value.operation === 'remove') {
+                    return [{ type: 'text', text: `Removed experience entry. Bank now holds ${value.count ?? 0} entries (${value.totalHits ?? 0} cumulative hits).` }];
+                }
                 if (value.operation === 'get' && value.entry) {
                     const entry = value.entry;
                     return [{ type: 'text', text: [
@@ -201,6 +208,38 @@ export function registerExperienceBankTool(ctx) {
                     totalHits: next.totalHits,
                 };
             }
+            if (operation === 'remove') {
+                const id = typeof args.id === 'string' && args.id ? args.id : '';
+                if (!id) {
+                    return {
+                        ok: false,
+                        kind: 'experience',
+                        operation: 'remove',
+                        error: 'id is required for remove',
+                    };
+                }
+                const bank = readExperienceBank(projectRoot);
+                const { bank: next, removed } = removeExperience(bank, id);
+                if (!removed) {
+                    return {
+                        ok: false,
+                        kind: 'experience',
+                        operation: 'remove',
+                        error: `Experience not found: ${id}`,
+                    };
+                }
+                const write = writeExperienceBank(projectRoot, next);
+                if (!write.ok) {
+                    return { ok: false, kind: 'experience', operation: 'remove', error: write.error };
+                }
+                return {
+                    ok: true,
+                    kind: 'experience',
+                    operation: 'remove',
+                    count: next.entries.length,
+                    totalHits: next.totalHits,
+                };
+            }
             const bank = readExperienceBank(projectRoot);
             if (operation === 'get' && typeof args.id === 'string') {
                 const entry = bank.entries.find((e) => e.id === args.id);

package/dist/tools/experience-store.js

@@ -6,6 +6,8 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { iterateDir } from "../paths.js";
+import { writeJsonAtomic } from "../atomic-fs.js";
 const EXPERIENCE_FILE = 'experience.json';
 /** Default empty experience bank. */
 function emptyBank() {
@@ -37,13 +39,15 @@ export function readExperienceBank(projectRoot) {
  * an entry that was never persisted.
  */
 export function writeExperienceBank(projectRoot, bank) {
-    const dirPath = path.join(projectRoot, '.iterate');
+    const dirPath = iterateDir(projectRoot);
     const filePath = path.join(dirPath, EXPERIENCE_FILE);
     try {
         if (!fs.existsSync(dirPath)) {
             fs.mkdirSync(dirPath, { recursive: true });
         }
-        fs.writeFileSync(filePath, JSON.stringify(bank, null, 2), 'utf-8');
+        // Atomic (temp + rename): a crash mid-write can never leave a truncated
+        // experience bank behind.
+        writeJsonAtomic(filePath, bank);
     }
     catch (err) {
         return { ok: false, error: `unable to write ${filePath}: ${String(err)}` };
@@ -136,3 +140,27 @@ export function upsertExperience(bank, entry) {
         entryId: id,
     };
 }
+/**
+ * Remove an experience entry by id.
+ * Returns the resulting bank plus whether an entry was actually removed. An
+ * unknown id is a no-op (the caller decides how to surface it). Never mutates
+ * the input bank.
+ */
+export function removeExperience(bank, id) {
+    const target = typeof id === 'string' && id ? id : '';
+    if (!target)
+        return { bank, removed: false };
+    const entries = bank.entries.filter((e) => e.id !== target);
+    if (entries.length === bank.entries.length)
+        return { bank, removed: false };
+    const lastUpdated = new Date().toISOString();
+    return {
+        bank: {
+            ...bank,
+            entries,
+            lastUpdated,
+            totalHits: bank.totalHits ?? 0,
+        },
+        removed: true,
+    };
+}