iterate-plugin 3.11.0 → 3.12.0

package/README.md

@@ -61,7 +61,7 @@ dsh plugin --profile web add iterate-plugin
 
 **v3.2 Quality Command Center**: the plugin has grown from a "passive observation panel" into an "active command center + knowledge base". It now ships quality gate view + writable compute, an experience bank with search / adopt / add, a defense events stream (record + bilingual labels), native command buttons, and a `task_mode` indicator.
 
-Besides 17 pure-function tools, it carries a **build-free Web UI layer** (convergence dashboard, triage panel, stats card, 11-tab runtime observatory — live activity stream + F1–F10 —, theme skin, etc.) that plugs straight into dsh's existing UI slots. Configuration (`iterate.config.yaml` and the review dimensions) is identical across the other two components of the iterate ecosystem ([skill](https://github.com/jingzhao-l/iterate-skill) / [headless engine](https://github.com/jingzhao-l/iterate-harness)) — zero migration cost.
+Besides 19 pure-function tools, it carries a **build-free Web UI layer** (convergence dashboard, triage panel, stats card, 12-tab runtime observatory — live activity stream + F1–F11 —, theme skin, etc.) that plugs straight into dsh's existing UI slots. Configuration (`iterate.config.yaml` and the review dimensions) is identical across the other two components of the iterate ecosystem ([skill](https://github.com/jingzhao-l/iterate-skill) / [headless engine](https://github.com/jingzhao-l/iterate-harness)) — zero migration cost.
 
 ---
 
@@ -104,10 +104,10 @@ Both modes share:
 - Validates after each round's fixes
 - Rolls back failed fixes, and can save / resume progress
 
-### UI layer (build-free client slots, v3.7: 11 tabs, bilingual)
+### UI layer (build-free client slots, v3.12: 12 tabs, bilingual)
 
 - **ConvergenceDashboard** (`conversation.input.dock`) — live round progress bar, severity stats, dimension badges, trend mini-chart above the input; normal mode also shows fix-count badges; plus a live workflow-phase chip (current phase + running/stopped) and a **task_mode indicator (code / iterate)**, now backed by the persisted transcript (`iterate_status` / `iterate_transcript` emit `taskMode`). While a run is active the dashboard switches to a running state (round + phase) instead of the static empty state, and the start buttons are hidden.
-- **ObservatoryPanel** (`conversation.input.dock`) — an **eleven-tab** runtime observatory below the input: **live activity stream** (default tab, type filter) + **F1** review threads (expand / collapse all), **F2** convergence trend (incl. the per-round comparison table: findings raised / fixed / severity mix / validation outcomes), **F3** finding locations (severity / dimension / search filter), **F4** fixes + rollback, **F5** checkpoint resume, **F6** run console, **F7** decision timeline (type / round filter + search), **F8** Quality Gate, **F9** Experience Bank, **F10** Defense Events. Number-key shortcuts: `1`–`9` jump to F1–F9, `0` to F10, `-` back to the live stream. **F8/F9/F10 are live** — they scan the session stream for the latest `iterate_quality_gate` / `iterate_experience` / `iterate_defense_events` results and render real data (PASS/FAIL chip + per-dimension score bars, experience entries with adopt buttons + client-side search, defense type-count chips + filtered event stream); when the session stream has none they distinguish "no data on disk" from "not pulled yet" and offer a **拉取磁盘快照 (pull disk snapshot)** instruction that has the model call the read-side tools and echo the `.iterate/` artifacts back into the stream. One-click JSON export of all observatory data — manifest + live + `qualityGate` / `experienceBank` / `defenseEvents` / `report` (download, copy fallback). **v3.9: report-export buttons** (导出报告 / 导出 SARIF, **v3.11 + 导出 JSON 报告**) render the *same shared data model* as the `iterate_report` tool — a PR-pasteable Markdown run report, a SARIF 2.1.0 log for CI / GitHub Code Scanning, and (v3.11) the complete normalized run model as machine-readable JSON. **v3.5.3: reset actions surfaced** — F5 copies an `iterate_checkpoint clear` instruction, F8 an `iterate_quality_gate clear` instruction, F10 an `iterate_defense_events clear` instruction.
+- **ObservatoryPanel** (`conversation.input.dock`) — a **twelve-tab** runtime observatory below the input: **live activity stream** (default tab, type filter) + **F1** review threads (expand / collapse all), **F2** convergence trend (incl. the per-round comparison table: findings raised / fixed / severity mix / validation outcomes), **F3** finding locations (severity / dimension / search filter), **F4** fixes + rollback, **F5** checkpoint resume, **F6** run console, **F7** decision timeline (type / round filter + search), **F8** Quality Gate, **F9** Experience Bank, **F10** Defense Events, **F11** Preflight. Number-key shortcuts: `1`–`9` jump to F1–F9, `0` to F10, `-` back to the live stream (F11 is click-only). **F8/F9/F10 are live** — they scan the session stream for the latest `iterate_quality_gate` / `iterate_experience` / `iterate_defense_events` results and render real data (PASS/FAIL chip + per-dimension score bars, experience entries with adopt buttons + client-side search, defense type-count chips + filtered event stream); when the session stream has none they distinguish "no data on disk" from "not pulled yet" and offer a **拉取磁盘快照 (pull disk snapshot)** instruction that has the model call the read-side tools and echo the `.iterate/` artifacts back into the stream. One-click JSON export of all observatory data — manifest + live + `qualityGate` / `experienceBank` / `defenseEvents` / `report` (download, copy fallback). **v3.9: report-export buttons** (导出报告 / 导出 SARIF, **v3.11 + 导出 JSON 报告**) render the *same shared data model* as the `iterate_report` tool — a PR-pasteable Markdown run report, a SARIF 2.1.0 log for CI / GitHub Code Scanning, and (v3.11) the complete normalized run model as machine-readable JSON. **v3.5.3: reset actions surfaced** — F5 copies an `iterate_checkpoint clear` instruction, F8 an `iterate_quality_gate clear` instruction, F10 an `iterate_defense_events clear` instruction. **v3.12: pre-run readiness (Preflight)** — F11 renders the latest `iterate_preflight` checklist scanned from the session stream (validation commands configured / git repo / dirty tree / stale FAIL gate / interrupted checkpoint), each warn/fail row offering the exact fix instruction (configure `validation.commands`, clear the stale gate, resume the checkpoint) so the environment is repaired BEFORE a round is spent on it; the empty state offers a **运行预检** instruction that has the model call `iterate_preflight`.
 - **TriagePanel** (`conversation.chat.turnTail`) — per-finding triage with `y` (keep → fix), `n` (skip), `a` (known-intentional) keyboard shortcuts and `↑`/`↓` navigation (focus-guarded: only active while the panel has focus), filtering, batch ops (incl. select-all), localStorage persistence. **Write-back closed loop**: the primary button copies an `iterate_triage apply` instruction for the marked entries (the tool validates, dedupes, backs up, rolls back on failure); a secondary button copies the raw `known_intentional` YAML; **回读已写入条目** copies an `iterate_triage list` instruction to confirm what actually landed. Copy payloads are aligned to the target tool schemas. **v3.2: native command buttons** (approve architectural fix, trigger new round, rollback to checkpoint). **v3.3: §8 指派修复 (assign)** — one click copies an `iterate_fix` instruction carrying every in-scope finding (respecting the batch toggle).
 - **StatsCard** (`conversation.chat.turnTail`) — convergence stats, round history, trend chart and completion summary when no findings remain.
 - **iterate theme skin** (`theme.overrideTokens`) — a warm-amber 13-token `--dsw-*` override, light/dark modes, togglable in settings.
@@ -196,9 +196,9 @@ To write verdicts back, mark entries with `a` and click **生成应用指令**
 
 ### Observatory tabs & shortcuts
 
-The observatory below the input carries **11 tabs**: the live activity stream (default) plus **F1**–**F10**:
+The observatory below the input carries **12 tabs**: the live activity stream (default) plus **F1**–**F11**:
 
-`F1` review threads · `F2` convergence trend (incl. per-round comparison) · `F3` finding locations · `F4` fixes + rollback · `F5` checkpoint resume · `F6` run console · `F7` decision timeline · `F8` quality gate · `F9` experience bank · `F10` defense events
+`F1` review threads · `F2` convergence trend (incl. per-round comparison) · `F3` finding locations · `F4` fixes + rollback · `F5` checkpoint resume · `F6` run console · `F7` decision timeline · `F8` quality gate · `F9` experience bank · `F10` defense events · `F11` preflight
 
 Press `1`–`9` to jump to F1–F9, `0` for F10, and `-` to return to the live stream.
 
@@ -288,7 +288,7 @@ validation:
 
 ---
 
-## 🔧 Registered tools (17)
+## 🔧 Registered tools (19)
 
 - `iterate_config` — read / write `iterate.config.yaml`. `operation=read` returns the full config or a named section; `operation=write` schema-validates, backs up, then merges and writes — auto rollback on failure
 - `iterate_validate` — run a whitelisted validation command, return the result
@@ -308,6 +308,7 @@ validation:
 - `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), `record` a new one, or **v3.5.3 `clear` the persisted stream** so a fresh iteration starts without stale defensive data. Human-readable labels follow the project language (en / zh)
 - `iterate_report` — **v3.9** export the run as a portable report. `format:"markdown"` (default) renders a PR-pasteable report (run header, quality gate, findings, fixes, validations, defense events, experience bank); `format:"sarif"` renders a SARIF 2.1.0 log for CI / GitHub Code Scanning (one rule per review dimension, severity → error/warning/note, file+line locations, suggested fix attached). **v3.11: `format:"json"` renders the COMPLETE normalized run model as machine-readable JSON** (findings, fixes, validations, convergence, quality gate, experience bank, defense events — the lossless format for CI dashboards / PR bots). `write:true` persists it to `.iterate/report.md` / `.iterate/report.sarif` / `.iterate/report.json`; `lang` (zh | en) selects the report language. Read-only apart from the optional report file
+- `iterate_preflight` — **v3.12** read-only pre-run readiness check. Returns a structured checklist: `validation.commands` configured (an empty set means the loop cannot prove fixes — **blocking**), whether the project is a git repository, how many files are uncommitted, whether a stale FAIL quality gate is persisted, and whether an interrupted checkpoint is waiting. Each check carries structured facts (`{ id, status: pass|warn|fail, detail }`) the observatory F11 panel localizes into a sentence + offers the exact fix instruction. Never mutates config, files, or artifacts
 
 ---
 
@@ -466,7 +467,7 @@ only `prepublishOnly` (build) runs on publish.
 
 The plugin follows dsh's "everything-is-a-plugin" architecture:
 
-- **Does exactly two things** — injects the system prompt teaching the model the iterate workflow + registers 17 pure-function tools
+- **Does exactly two things** — injects the system prompt teaching the model the iterate workflow + registers 19 pure-function tools
 - **All orchestration runs through dsh native `workflow` + `agent` + `parallel`**
 - **Core logic is entirely pure functions** (dedupe / filter / sort / converge / meta-audit / diff computation / history filtering / cleanup reporting) — unit-testable, no I/O
 - **Security model** — file writes confined to the resolved project root (path-traversal protection); always back up before writing, roll back on failure; config writes also back up + roll back; `iterate_prune` is dry-run by default and only clears artifacts under `.iterate/` with every cleanup logged; `iterate_fix` caps content length and `iterate_triage` caps entry count to fend off abnormal oversized payloads

package/README.zh-CN.md

@@ -60,7 +60,7 @@ dsh plugin --profile web add iterate-plugin
 
 **v3.2 质量指挥中心**：插件已从"被动观察面板"升级为"主动指挥中心 + 知识库"。新增质量门禁读取与可写计算（compute）、经验银行（检索 / 采纳 / 新增 add）、防御事件流（记录 + 中英双语标签）、原生命令按钮与 `task_mode` 指示器。
 
-除 17 个纯函数工具外，还内置一套**免构建的 Web UI 层**（收敛看板、分诊面板、统计卡片、11 页签运行时观测台——实时活动流 + F1–F10——、主题皮肤等），直接挂在 dsh 客户端的既有 UI 槽位上。配置方式（`iterate.config.yaml` 与审查维度）与迭代生态的另外两个组件（[技能](https://github.com/jingzhao-l/iterate-skill) / [无头引擎](https://github.com/jingzhao-l/iterate-harness)）完全一致，迁移零成本。
+除 19 个纯函数工具外，还内置一套**免构建的 Web UI 层**（收敛看板、分诊面板、统计卡片、12 页签运行时观测台——实时活动流 + F1–F11——、主题皮肤等），直接挂在 dsh 客户端的既有 UI 槽位上。配置方式（`iterate.config.yaml` 与审查维度）与迭代生态的另外两个组件（[技能](https://github.com/jingzhao-l/iterate-skill) / [无头引擎](https://github.com/jingzhao-l/iterate-harness)）完全一致，迁移零成本。
 
 ---
 
@@ -103,10 +103,10 @@ dsh plugin --profile web add iterate-plugin
 - 每轮修复后验证
 - 修复失败自动回滚
 
-### UI 层（客户端免构建槽位，v3.7：11 个页签，双语）
+### UI 层（客户端免构建槽位，v3.12：12 个页签，双语）
 
 - **收敛看板 `ConvergenceDashboard`**（`conversation.input.dock`）— 输入框上方实时显示轮次进度条、严重度统计、维度徽章、趋势迷你图；normal 模式另显示修复计数徽章；还有运行阶段芯片（当前工作流阶段 + 运行中/已结束）与 **task_mode 指示器（code / iterate）**。运行期间看板切换为"运行中"状态（显示轮次与阶段），并隐藏启动按钮。
-- **运行时观测台 `ObservatoryPanel`**（`conversation.input.dock`）— 输入框下方**十一个页签**运行时观测台：**实时活动流**（默认页，支持按活动类型筛选）+ **F1** 审查线程（全部展开/全部收起）、**F2** 收敛趋势（含跨轮对比表：每轮 findings / fixed / 严重度分布 / 验证结果）、**F3** 发现定位（按严重度/维度/关键词筛选）、**F4** 修复与回滚、**F5** 断点恢复、**F6** 运行控制台、**F7** 决策时间线（按类型/轮次筛选与关键词搜索）、**F8** 质量门禁、**F9** 经验银行、**F10** 防御事件。数字键快捷键：`1`–`9` 跳到 F1–F9，`0` 到 F10，`-` 回实时活动流。**F8/F9/F10 为实时数据**——扫描会话流中最近一次 `iterate_quality_gate` / `iterate_experience` / `iterate_defense_events` 结果并渲染真实数据（PASS/FAIL 徽章 + 分维度评分条、经验条目（含采纳按钮 + 客户端搜索）、防御类型计数芯片 + 筛选后的事件流）；会话流中没有数据时区分"磁盘无数据"与"尚未拉取"，并提供**拉取磁盘快照**指令（让模型调用只读工具、把 `.iterate/` 产物回显进会话流）。一键导出全部观测数据为 JSON——manifest + live + `qualityGate` / `experienceBank` / `defenseEvents` / `report`（优先下载，失败回退复制）。**v3.9 新增报告导出按钮**（导出报告 / 导出 SARIF，**v3.11 新增导出 JSON 报告**），与 `iterate_report` 工具共用同一份数据模型——分别产出可直接粘贴进 PR 的 Markdown 运行报告、供 CI / GitHub Code Scanning 消费的 SARIF 2.1.0 日志，以及（v3.11）完整的归一化运行模型 JSON（无损格式）。**v3.5.3 新增重置操作**：F5 复制 `iterate_checkpoint clear`、F8 复制 `iterate_quality_gate clear`、F10 复制 `iterate_defense_events clear` 指令。
+- **运行时观测台 `ObservatoryPanel`**（`conversation.input.dock`）— 输入框下方**十二个页签**运行时观测台：**实时活动流**（默认页，支持按活动类型筛选）+ **F1** 审查线程（全部展开/全部收起）、**F2** 收敛趋势（含跨轮对比表：每轮 findings / fixed / 严重度分布 / 验证结果）、**F3** 发现定位（按严重度/维度/关键词筛选）、**F4** 修复与回滚、**F5** 断点恢复、**F6** 运行控制台、**F7** 决策时间线（按类型/轮次筛选与关键词搜索）、**F8** 质量门禁、**F9** 经验银行、**F10** 防御事件、**F11** 开跑预检。数字键快捷键：`1`–`9` 跳到 F1–F9，`0` 到 F10，`-` 回实时活动流（F11 仅点击进入）。**F8/F9/F10 为实时数据**——扫描会话流中最近一次 `iterate_quality_gate` / `iterate_experience` / `iterate_defense_events` 结果并渲染真实数据（PASS/FAIL 徽章 + 分维度评分条、经验条目（含采纳按钮 + 客户端搜索）、防御类型计数芯片 + 筛选后的事件流）；会话流中没有数据时区分"磁盘无数据"与"尚未拉取"，并提供**拉取磁盘快照**指令（让模型调用只读工具、把 `.iterate/` 产物回显进会话流）。一键导出全部观测数据为 JSON——manifest + live + `qualityGate` / `experienceBank` / `defenseEvents` / `report`（优先下载，失败回退复制）。**v3.9 新增报告导出按钮**（导出报告 / 导出 SARIF，**v3.11 新增导出 JSON 报告**），与 `iterate_report` 工具共用同一份数据模型——分别产出可直接粘贴进 PR 的 Markdown 运行报告、供 CI / GitHub Code Scanning 消费的 SARIF 2.1.0 日志，以及（v3.11）完整的归一化运行模型 JSON（无损格式）。**v3.5.3 新增重置操作**：F5 复制 `iterate_checkpoint clear`、F8 复制 `iterate_quality_gate clear`、F10 复制 `iterate_defense_events clear` 指令。**v3.12 新增开跑预检（Preflight）**——F11 渲染会话流中最近一次 `iterate_preflight` 清单（验证命令是否配置 / 是否 Git 仓库 / 脏工作区 / 陈旧 FAIL 门禁 / 中断断点），每个 warn/fail 行都给出精确的修复指令（配置 `validation.commands`、清除陈旧门禁、恢复断点），让环境在**花掉一轮之前**就被修好；空态提供**运行预检**指令（让模型调用 `iterate_preflight`）。
 - **Findings 分诊面板 `TriagePanel`**（`conversation.chat.turnTail`）— 逐条分诊，键盘快捷键 `y`（保留→修复）、`n`（跳过）、`a`（已知有意）与 `↑`/`↓` 移动（焦点守卫：仅面板内焦点时生效），支持筛选、批量（含一键全选所有 findings）、localStorage 持久化。**写回闭环**：主按钮复制已标记条目的 `iterate_triage apply` 指令（工具负责校验、去重、备份、失败回滚）；次按钮复制裸 `known_intentional` YAML；**回读已写入条目**复制 `iterate_triage list` 指令核对实际落盘内容。复制载荷与目标工具 schema 对齐。**v3.2：原生命令按钮**（批准架构修复、触发新一轮、回滚到断点）。
 - **收敛统计卡片 `StatsCard`**（`conversation.chat.turnTail`）— 无 findings 时显示收敛统计、历史轮次、趋势图、完成摘要。
 - **iterate 主题皮肤**（`theme.overrideTokens`）— 暖琥珀配色的 13 个 `--dsw-*` token 覆盖，明暗双模式，可在设置页开关。
@@ -118,7 +118,7 @@ UI 层为**防御式设计**：`slots` / `theme` / `React` 任一不可用时自
 
 ### 工具之外的闭环行为
 
-除 17 个注册工具（完整参考见下文）外，插件还端到端打通了几条关键闭环：
+除 19 个注册工具（完整参考见下文）外，插件还端到端打通了几条关键闭环：
 
 - **findings 分诊闭环** — 审查 → UI 分诊（y/n/a）→ `iterate_triage` 写回 `known_intentional` → 下一轮自动过滤
 - **结构化修复系统** — 每次修复先备份、写注册表、记录 diff，验证失败可 `iterate_rollback` 还原
@@ -195,9 +195,9 @@ pnpm add /path/to/iterate-skill/harness/iterate-plugin
 
 ### 观测台页签与快捷键
 
-输入框下方的观测台共 **11 个页签**：实时活动流（默认页）+ **F1–F10**：
+输入框下方的观测台共 **12 个页签**：实时活动流（默认页）+ **F1–F11**：
 
-`F1` 审查线程 · `F2` 收敛趋势（含跨轮对比）· `F3` 发现定位 · `F4` 修复与回滚 · `F5` 断点恢复 · `F6` 运行控制台 · `F7` 决策时间线 · `F8` 质量门禁 · `F9` 经验银行 · `F10` 防御事件
+`F1` 审查线程 · `F2` 收敛趋势（含跨轮对比）· `F3` 发现定位 · `F4` 修复与回滚 · `F5` 断点恢复 · `F6` 运行控制台 · `F7` 决策时间线 · `F8` 质量门禁 · `F9` 经验银行 · `F10` 防御事件 · `F11` 开跑预检
 
 按 `1`–`9` 跳到 F1–F9，`0` 到 F10，`-` 回实时活动流。
 
@@ -287,7 +287,7 @@ validation:
 
 ---
 
-## 🔧 注册工具（17 个）
+## 🔧 注册工具（19 个）
 
 - `iterate_config` — 读取 / 写入 `iterate.config.yaml`。`operation=read` 返回完整配置或指定 section；`operation=write` 做 schema 校验、备份后局部合并写入，失败自动回滚
 - `iterate_validate` — 运行白名单验证命令，返回结果
@@ -307,6 +307,7 @@ validation:
 - `iterate_quality_gate` — **v3.2** 读取质量凭证（`read`），或基于 findings、验证结果、`findingsByRound` 与 `fixedByDimension` 重新计算并持久化一份新凭证（`compute`）。真实的逐维度收敛率。**v3.5 新增 `clear`：删除持久化的质量凭证**，用于新一轮迭代前重置陈旧的门禁
 - `iterate_defense_events` — **v3.2** 查询防御事件（list / counts），`record` 记录一条新事件，或 **v3.5.3 `clear` 清除持久化事件流**，让新一轮迭代不带陈旧防御数据起跑。可读标签跟随项目语言（en / zh）
 - `iterate_report` — **v3.9** 把本次运行导出为可移植报告。`format:"markdown"`（默认）产出可直接粘贴进 PR 的报告（运行头部、质量门禁、发现、修复、验证、防御事件、经验银行）；`format:"sarif"` 产出 SARIF 2.1.0 日志供 CI / GitHub Code Scanning 消费（每个审查维度一条规则，严重度 → error/warning/note，携带文件+行号位置与建议修复）。**v3.11：`format:"json"` 产出完整归一化运行模型为机器可读 JSON**（发现、修复、验证、收敛率、质量门禁、经验银行、防御事件——供 CI 仪表盘 / PR 机器人消费的无损格式）。`write:true` 持久化到 `.iterate/report.md` / `.iterate/report.sarif` / `.iterate/report.json`；`lang`（zh | en）选择报告语言。除可选的报告文件外均为只读
+- `iterate_preflight` — **v3.12** 开跑前只读预检。返回结构化清单：`validation.commands` 是否已配置（为空意味着本轮无法证明修复——**阻断项**）、是否 Git 仓库、多少个未提交文件、磁盘上是否残留 FAIL 质量门禁、是否有中断断点在等待。每项都携带结构化事实（`{ id, status: pass|warn|fail, detail }`），观测台 F11 面板据此本地化为一句话并给出精确修复指令。绝不修改配置、文件或产物
 
 ---
 
@@ -423,7 +424,7 @@ validation:
 
 插件遵循 dsh "everything-is-a-plugin" 架构：
 
-- **只做两件事** — 注入系统 prompt 教模型写 iterate workflow + 注册 17 个纯函数工具
+- **只做两件事** — 注入系统 prompt 教模型写 iterate workflow + 注册 19 个纯函数工具
 - **所有 orchestration 通过 dsh 原生 `workflow` + `agent` + `parallel` 完成**
 - **核心逻辑全部纯函数**（去重 / 过滤 / 排序 / 收敛 / meta-audit / diff 计算 / 历史过滤 / 清理报告），可单元测试，无 I/O
 - **安全模型** — 文件写入限定在解析后的项目根目录内（路径遍历防护）；写文件前必备份，失败回滚；配置写入同样备份 + 回滚；`iterate_prune` 默认 dry-run、只清理 `.iterate/` 下产物、每次清理写日志；`iterate_fix` 对 content 设字符上限、`iterate_triage` 对 entries 设数量上限，防止异常超大负载

package/dist/index.js

@@ -44,6 +44,7 @@ import { registerExperienceBankTool } from "./tools/experience-bank.js";
 import { registerQualityGateTool } from "./tools/quality-gate.js";
 import { registerDefenseEventsTool } from "./tools/defense-events.js";
 import { registerReportTool } from "./tools/report.js";
+import { registerPreflightTool } from "./tools/preflight.js";
 import { registerSessionHooks } from "./session-hooks.js";
 import { registerLiveCapture } from "./live.js";
 import { installWorkingDirectoryContext } from "./working-directory.js";
@@ -66,11 +67,11 @@ export function apply(ctx) {
     installWorkingDirectoryContext(ctx);
     registerSessionHooks(ctx);
     registerLiveCapture(ctx);
-    // 1. Register the 17 tools (14 original + 3 v3.0). Each registration is
-    //    isolated: one failing tool must not take down the other 16, the gate
-    //    above, or the prompt below (a partial plugin that still gates and
-    //    teaches the workflow beats an aborted `apply`). Failures are logged,
-    //    never swallowed silently.
+    // 1. Register the 19 tools (14 original + 3 v3.0 + report + preflight). Each
+    //    registration is isolated: one failing tool must not take down the other
+    //    18, the gate above, or the prompt below (a partial plugin that still
+    //    gates and teaches the workflow beats an aborted `apply`). Failures are
+    //    logged, never swallowed silently.
     const toolRegistrations = [
         ['iterate_config', () => registerConfigTool(ctx)],
         ['iterate_validate', () => registerValidateTool(ctx)],
@@ -92,6 +93,8 @@ export function apply(ctx) {
         ['iterate_defense_events', () => registerDefenseEventsTool(ctx)],
         // v3.9: PR-ready / CI-ready report export
         ['iterate_report', () => registerReportTool(ctx)],
+        // v3.12: pre-run readiness check (validation/git/stale-gate/interrupted)
+        ['iterate_preflight', () => registerPreflightTool(ctx)],
     ];
     for (const [toolName, register] of toolRegistrations) {
         try {

package/dist/tools/preflight.js

@@ -0,0 +1,239 @@
+/**
+ * src/tools/preflight.ts — `iterate_preflight` tool.
+ *
+ * Answers one question BEFORE a run starts: "is this project ready to iterate
+ * safely, and what must be fixed first?" It reads only local state (config,
+ * git, persisted artifacts, checkpoint) and returns a structured checklist the
+ * observatory renders as a preflight panel (F11).
+ *
+ * Why it exists: the most expensive failure mode is starting a run that cannot
+ * prove anything — an empty `validation.commands` means the loop has no way to
+ * tell a fix from a regression, and a stale FAIL certificate or a leftover
+ * interrupted checkpoint makes the first round lie about its starting state.
+ * Preflight surfaces those conditions before the model spends a round
+ * discovering them mid-flight.
+ *
+ * Read-only: never mutates config, files, or artifacts.
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { resolveProjectRootForExec, loadEffectiveConfig, flattenCommands } from "../config-loader.js";
+import { runGit } from "../git-scope.js";
+import { readQualityGate } from "./quality-store.js";
+import { readCheckpoint, computeStatus } from "./checkpoint.js";
+import { readDecisionEntries } from "./decision-log.js";
+import { readRegistry } from "./fix.js";
+import { resultHeadline } from "./present.js";
+/**
+ * Build the readiness checklist from already-gathered facts (pure).
+ *
+ * The five checks and why each exists:
+ *   1. `validation`            — empty command set ⇒ the loop cannot prove a
+ *                                fix; the product is fail-closed here, so this
+ *                                is a BLOCKING `fail`, not a warning.
+ *   2. `git`                   — changed-only scope + `iterate_diff` need a
+ *                                repository; full-scope review still works, so
+ *                                absent is a `warn`.
+ *   3. `dirty-tree`            — a run over uncommitted work mixes the user's
+ *                                WIP with the plugin's fixes; advisory `warn`.
+ *                                Unknown (null) is treated as pass so a git
+ *                                hiccup never fabricates a warning.
+ *   4. `stale-gate`            — a persisted FAIL certificate makes the first
+ *                                round read stale; `warn` + clear before a
+ *                                fresh run.
+ *   5. `interrupted-checkpoint`— a leftover checkpoint from a run that never
+ *                                progressed; `warn` + resume or clear.
+ */
+export function buildPreflightReport(input) {
+    const checks = [
+        {
+            id: 'validation',
+            status: input.validationCommandCount > 0 ? 'pass' : 'fail',
+            detail: { commandCount: input.validationCommandCount },
+        },
+        {
+            id: 'git',
+            status: input.isGitRepo ? 'pass' : 'warn',
+            detail: { isRepo: input.isGitRepo },
+        },
+        {
+            id: 'dirty-tree',
+            status: input.changedFiles !== null && input.changedFiles > 0 ? 'warn' : 'pass',
+            detail: { changedFiles: input.changedFiles },
+        },
+        {
+            id: 'stale-gate',
+            status: input.gateOverallStatus === 'fail' ? 'warn' : 'pass',
+            detail: { overallStatus: input.gateOverallStatus },
+        },
+        {
+            id: 'interrupted-checkpoint',
+            status: input.interrupted ? 'warn' : 'pass',
+            detail: { interrupted: input.interrupted, resumeCount: input.resumeCount },
+        },
+    ];
+    const blocking = checks.filter((c) => c.status === 'fail').length;
+    const warnings = checks.filter((c) => c.status === 'warn').length;
+    return { ok: true, ready: blocking === 0, blocking, warnings, checks };
+}
+/** Human-readable (English, for the model-facing render) description per check. */
+function describeCheck(id, detail) {
+    switch (id) {
+        case 'validation': {
+            const n = Number(detail.commandCount ?? 0);
+            return n > 0
+                ? `${n} validation command(s) configured`
+                : 'no validation.commands configured — the run cannot prove fixes (blocking)';
+        }
+        case 'git':
+            return detail.isRepo === true
+                ? 'git repository detected'
+                : 'not a git repository — changed-only scope and iterate_diff need one';
+        case 'dirty-tree': {
+            const n = detail.changedFiles;
+            if (n === null || n === undefined)
+                return 'uncommitted changes: unknown';
+            const num = Number(n);
+            return num > 0
+                ? `${num} uncommitted/untracked file(s) — commit or stash before a run`
+                : 'working tree clean';
+        }
+        case 'stale-gate': {
+            const s = detail.overallStatus;
+            if (s === 'fail')
+                return 'a stale FAIL quality gate is persisted — clear it before a fresh run';
+            return s ? `quality gate: ${String(s)}` : 'no persisted quality gate';
+        }
+        case 'interrupted-checkpoint': {
+            if (detail.interrupted === true) {
+                const rc = Number(detail.resumeCount ?? 0);
+                return `an interrupted checkpoint is waiting (resumed ${rc}x) — resume or clear it`;
+            }
+            return 'no interrupted checkpoint';
+        }
+        default:
+            return '';
+    }
+}
+/**
+ * Register the `iterate_preflight` tool.
+ */
+export function registerPreflightTool(ctx) {
+    ctx.tools.register(defineTool({
+        name: 'iterate_preflight',
+        // Pure read of on-disk state + git → safe to join a parallel group.
+        isConcurrencySafe: () => true,
+        presentResult: (_args, result) => {
+            const title = resultHeadline(result);
+            return title ? { card: 'generic', title } : undefined;
+        },
+        description: 'Read-only readiness check to run BEFORE starting an iterate run. Returns a checklist: whether ' +
+            'validation.commands is configured (an empty set means the loop cannot prove fixes — blocking), ' +
+            'whether the project is a git repository, how many files are uncommitted, whether a stale FAIL ' +
+            'quality gate is persisted, and whether an interrupted checkpoint is waiting. Use it before a fresh ' +
+            'run so you fix the environment first instead of discovering it mid-round.',
+        parameters: {
+            path: { type: 'string', description: 'Project root directory (default: current working directory).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    ok: { type: 'boolean', required: true },
+                    ready: { type: 'boolean' },
+                    blocking: { type: 'integer' },
+                    warnings: { type: 'integer' },
+                    checks: { type: 'json', description: 'Per-check outcomes: { id, status: pass|warn|fail, detail }.' },
+                    error: { type: 'string' },
+                },
+            },
+            render: (_args, value) => {
+                if (!value.ok)
+                    return [{ type: 'text', text: `preflight failed: ${value.error}` }];
+                const checks = Array.isArray(value.checks) ? value.checks : [];
+                const warnings = Number(value.warnings ?? 0);
+                const noun = warnings === 1 ? 'warning' : 'warnings';
+                const head = value.ready
+                    ? `Preflight: READY (${Number(value.blocking ?? 0)} blocking, ${warnings} ${noun})`
+                    : `Preflight: NOT READY (${Number(value.blocking ?? 0)} blocking, ${warnings} ${noun})`;
+                const lines = checks.map((c) => {
+                    const check = c;
+                    const id = String(check.id ?? '?');
+                    const status = String(check.status ?? '?').toUpperCase();
+                    return `  ${status} ${id} — ${describeCheck(id, check.detail ?? {})}`;
+                });
+                return [{ type: 'text', text: [head, ...lines].join('\n') }];
+            },
+        },
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
+            if (!resolved.ok) {
+                return { ok: false, ready: false, blocking: 0, warnings: 0, checks: [], error: resolved.reason };
+            }
+            const projectRoot = resolved.root;
+            // 1. validation.commands — the load-bearing check.
+            let validationCommandCount = 0;
+            try {
+                const effective = loadEffectiveConfig(projectRoot);
+                validationCommandCount = flattenCommands(effective.config.validation?.commands).length;
+            }
+            catch {
+                validationCommandCount = 0;
+            }
+            // 2/3. git repo + dirty tree (best-effort; any failure degrades to unknown).
+            let isGitRepo = false;
+            let changedFiles = null;
+            try {
+                const inside = await runGit(['rev-parse', '--is-inside-work-tree'], projectRoot, { signal: exec.signal });
+                isGitRepo = inside.ok && inside.stdout.trim() === 'true';
+                if (isGitRepo) {
+                    const status = await runGit(['status', '--porcelain', '-z'], projectRoot, { signal: exec.signal });
+                    if (status.ok) {
+                        // `-z` NUL-terminates each entry; a rename emits two NUL-separated
+                        // paths for one entry, but counting non-empty tokens is still a
+                        // faithful "there is uncommitted work" signal (>=1 when dirty).
+                        changedFiles = status.stdout.split('\u0000').filter((s) => s.length > 0).length;
+                    }
+                }
+            }
+            catch {
+                isGitRepo = false;
+                changedFiles = null;
+            }
+            // 4. stale quality gate.
+            let gateOverallStatus = null;
+            try {
+                gateOverallStatus = readQualityGate(projectRoot).overallStatus ?? null;
+            }
+            catch {
+                gateOverallStatus = null;
+            }
+            // 5. interrupted checkpoint (reuse the exact status logic so preflight
+            //    and iterate_status can never disagree about "interrupted").
+            let interrupted = false;
+            let resumeCount = 0;
+            try {
+                const status = computeStatus({
+                    checkpoint: readCheckpoint(projectRoot),
+                    decisionEntries: readDecisionEntries(projectRoot),
+                    fixRegistry: readRegistry(projectRoot),
+                });
+                interrupted = status.interrupted;
+                resumeCount = status.resumeCount;
+            }
+            catch {
+                interrupted = false;
+                resumeCount = 0;
+            }
+            const report = buildPreflightReport({
+                validationCommandCount,
+                isGitRepo,
+                changedFiles,
+                gateOverallStatus,
+                interrupted,
+                resumeCount,
+            });
+            return { ...report, checks: report.checks };
+        },
+    }));
+}