iterate-plugin 3.15.0 → 3.17.0

package/README.md

@@ -107,7 +107,7 @@ Both modes share:
 ### 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`) — 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`. **v3.13: the blocking validation row auto-detects commands from the project manifest and offers a one-click 「应用建议」 (copies an `iterate_config write` payload).**
+- **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, plus **v3.16 a cross-session comparison**: save the current run as a baseline (`存为对比基准`), then compare any later run against it side by side (`与基准对比`) with per-metric deltas tinted by direction, **v3.17 the comparison is copyable as a Markdown table** (`复制对比表`, paste it straight into a PR / issue / CI comment)), **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 (query / **v3.17 one-click recompute** — the `compute` payload's per-dimension per-round convergence series is derived from the session transcript, so you no longer hand-write the `findingsByRound` JSON), **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`. **v3.13: the blocking validation row auto-detects commands from the project manifest and offers a one-click 「应用建议」 (copies an `iterate_config write` payload).**
 - **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.
@@ -121,7 +121,7 @@ The UI layer is **defensive by design**: it degrades gracefully if any of `slots
 
 ### Behavior beyond the tools
 
-Beyond the 17 registered tools (full reference further down), the plugin closes several loops end to end:
+Beyond the 19 registered tools (full reference further down), the plugin closes several loops end to end:
 
 - **Findings triage loop** — review → UI triage (y/n/a) → `iterate_triage` writes back `known_intentional` → auto-filtered next round
 - **Structured fix system** — each fix backs up first, writes a registry entry, records the diff; a failed validation can be reverted with `iterate_rollback`
@@ -202,6 +202,8 @@ The observatory below the input carries **12 tabs**: the live activity stream (d
 
 `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
 
+**Cross-session comparison (v3.16)** — the F2 tab also carries a **跨会话对比 (cross-session comparison)** block: **存为对比基准** saves the current run's summary (rounds / findings / critical+high / fixes applied / failed fixes / validation pass rate / quality-gate score, persisted to `localStorage`) and **与基准对比** renders the next run against it side by side with a directional delta (better / worse tinted). This replaces the old "export two JSONs and diff by hand" chore; a corrupt / stale saved baseline reads as "no baseline", never a phantom run.
+
 Press `1`–`9` to jump to F1–F9, `0` for F10, and `-` to return to the live stream.
 
 ### Disk snapshot pull & export

package/README.zh-CN.md

@@ -106,7 +106,7 @@ dsh plugin --profile web add iterate-plugin
 ### 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** 防御事件、**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`）。**v3.13：阻断的验证命令行自动检测项目 manifest，提供一键「应用建议」**（复制 `iterate_config` 的 `operation:"write"` 指令，携带完整 `validation.commands.default` 载荷）。
+- **运行时观测台 `ObservatoryPanel`**（`conversation.input.dock`）— 输入框下方**十二个页签**运行时观测台：**实时活动流**（默认页，支持按活动类型筛选）+ **F1** 审查线程（全部展开/全部收起）、**F2** 收敛趋势（含跨轮对比表：每轮 findings / fixed / 严重度分布 / 验证结果；**v3.16 新增跨会话对比**：把当前运行**存为对比基准**，下次运行一键**与基准对比**，逐项并排 + 带方向的差值着色，**v3.17 新增「复制对比表」**：把并排表复制成 Markdown 表格，可直接粘贴进 PR / issue / CI 注释）、**F3** 发现定位（按严重度/维度/关键词筛选）、**F4** 修复与回滚、**F5** 断点恢复、**F6** 运行控制台、**F7** 决策时间线（按类型/轮次筛选与关键词搜索）、**F8** 质量门禁（查询 / **v3.17 一键重算**——`compute` 载荷里每维度每轮的收敛序列直接从当前会话 transcript 推导，无需再手写 `findingsByRound` JSON）、**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`）。**v3.13：阻断的验证命令行自动检测项目 manifest，提供一键「应用建议」**（复制 `iterate_config` 的 `operation:"write"` 指令，携带完整 `validation.commands.default` 载荷）。
 - **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 覆盖，明暗双模式，可在设置页开关。
@@ -201,6 +201,8 @@ pnpm add /path/to/iterate-skill/harness/iterate-plugin
 
 `F1` 审查线程 · `F2` 收敛趋势（含跨轮对比）· `F3` 发现定位 · `F4` 修复与回滚 · `F5` 断点恢复 · `F6` 运行控制台 · `F7` 决策时间线 · `F8` 质量门禁 · `F9` 经验银行 · `F10` 防御事件 · `F11` 开跑预检
 
+**跨会话对比（v3.16）**——F2 页签还带一个**跨会话对比**块：**存为对比基准**把当前运行摘要（轮次 / 发现 / critical+high / 修复成功 / 修复失败 / 验证通过率 / 门禁得分，持久化到 `localStorage`）保存下来，**与基准对比**把下一次运行与它并排对比，差值按「更好 / 更差」方向着色。这取代了以前「导出两份 JSON 手工并排对比」的繁琐做法；损坏 / 过期的已存基准读作「无基准」，绝不变成幽灵运行。
+
 按 `1`–`9` 跳到 F1–F9，`0` 到 F10，`-` 回实时活动流。
 
 ### 磁盘快照拉取与导出

package/dist/index.js

@@ -2,16 +2,17 @@
  * iterate-plugin — dsh plugin for the iterate autonomous closed-loop workflow
  *
  * Architecture:
- * - The plugin registers 18 tools (14 original + 3 v3.0 quality command center
- *   tools + 1 v3.9 report export)
+ * - The plugin registers 19 tools (14 original + 3 v3.0 quality command center
+ *   tools + 1 v3.9 report export + 1 v3.12 pre-run preflight)
  *   Original: config, validate, decision-log, context, review, triage, fix, diff,
  *   rollback, checkpoint, status, history, prune, transcript
  *   v3.0: experience, quality_gate, defense_events
  *   v3.9: report
+ *   v3.12: preflight
  * - The plugin injects a system prompt section teaching the iterate workflow pattern
  * - The model (prompted by the skill) writes a workflow script using dsh's `workflow` tool
  * - The workflow script uses `agent()` / `parallel()` / `phase()` / `log()` to orchestrate
- * - Subagents use the 18 tools to do real work (read config, run validation, log decisions,
+ * - Subagents use the 19 tools to do real work (read config, run validation, log decisions,
  *   review, triage, apply/rollback/fixing, checkpoint, status, history, prune, transcript,
  *   query experience bank, check quality gates, query defense events, export a report)
  * - A `tools/pre-execute` hook gates destructive iterate calls behind human approval
@@ -25,7 +26,7 @@
  *
  * Key files:
  * - src/index.ts      — Plugin entry: register tools + inject skill prompt
- * - src/tools/        — 18 tool implementations (14 original + 3 v3.0 + 1 v3.9)
+ * - src/tools/        — 19 tool implementations (14 original + 3 v3.0 + 1 v3.9 + 1 v3.12)
  * - src/config-loader.ts — YAML config loading
  * - src/types.ts     — Shared types
  */

package/dist/tools/decision-log.js

@@ -265,6 +265,26 @@ function decodedLines(filePath) {
     }
     return out;
 }
+/**
+ * Rebuild the exact ledger text the kernel verifies, dropping only the artifact a
+ * trailing newline leaves. Unlike `decodedLines` this keeps interior blank lines:
+ * `kernelVerifyLedgerText` splits on "\n" and `JSON.parse`s each line, so an interior
+ * blank line is a corrupt entry it must report — renumbering the lines that follow it
+ * (by dropping it here) would mask a real break as a healthy ledger.
+ */
+function ledgerTextForVerify(filePath) {
+    let text;
+    try {
+        text = readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return '';
+    }
+    const lines = text.endsWith('\n') ? text.slice(0, -1) : text;
+    if (lines.length === 0)
+        return '';
+    return `${lines}\n`;
+}
 /** The 1-based line number of the first legacy record AFTER the chain began, else `null`. */
 export function contestedLedgerLine(filePath) {
     const kinds = decodedLines(filePath).map((l) => classifyDecisionLine(l.decoded));
@@ -670,8 +690,7 @@ export function readDecisionEntries(projectRoot) {
 export function verifyDecisionLedger(projectRoot) {
     const filePath = decisionLogPath(projectRoot);
     try {
-        const lines = decodedLines(filePath);
-        const body = `${lines.map((l) => l.raw).join('\n')}${lines.length > 0 ? '\n' : ''}`;
+        const body = ledgerTextForVerify(filePath);
         const verified = kernelVerifyLedgerText(body);
         return {
             ok: verified.ok,