iterate-plugin 3.10.0 → 3.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "3.10.0",
+  "version": "3.12.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",
@@ -52,7 +52,9 @@
         "0.2.1-alpha.5": "compatible",
         "0.2.1-rc.1": "compatible",
         "0.2.1-rc.2": "compatible",
-        "0.2.1-rc.3": "compatible"
+        "0.2.1-rc.3": "compatible",
+        "0.2.1-rc.4": "compatible",
+        "0.2.2-alpha.2": "compatible"
       }
     },
     "client": {
@@ -93,10 +95,10 @@
     "js-yaml": "4.3.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.5-alpha.2",
-    "@deepseek-ai/dsh-session": "0.1.1-rc.1 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3",
-    "@deepseek-ai/dsh-tools": "0.1.1-rc.1 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3",
-    "@deepseek-ai/dsh-util-values": "0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3"
+    "@deepseek-ai/cordis": "^4.0.5-alpha.2 || ~4.0.6-alpha.1",
+    "@deepseek-ai/dsh-session": "0.1.1-rc.1 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.2-alpha.2",
+    "@deepseek-ai/dsh-tools": "0.1.1-rc.1 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.2-alpha.2",
+    "@deepseek-ai/dsh-util-values": "0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.2-alpha.2"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {
@@ -113,20 +115,20 @@
     }
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.5",
-    "@deepseek-ai/dsh-agent": "0.2.1-rc.3",
-    "@deepseek-ai/dsh-jobs": "0.2.1-rc.3",
-    "@deepseek-ai/dsh-llm": "0.2.1-rc.3",
-    "@deepseek-ai/dsh-ptc-runtime": "0.2.1-rc.3",
-    "@deepseek-ai/dsh-sandbox": "0.2.1-rc.3",
-    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-rc.3",
-    "@deepseek-ai/dsh-scope": "0.2.1-rc.3",
-    "@deepseek-ai/dsh-session": "0.2.1-rc.3",
-    "@deepseek-ai/dsh-system-prompt": "0.2.1-rc.3",
-    "@deepseek-ai/dsh-tools": "0.2.1-rc.3",
-    "@deepseek-ai/dsh-user-approval": "0.2.1-rc.3",
-    "@deepseek-ai/dsh-util-values": "0.2.1-rc.3",
-    "@deepseek-ai/dsh-working-directory": "0.2.1-rc.3",
+    "@deepseek-ai/cordis": "4.0.6-alpha.1",
+    "@deepseek-ai/dsh-agent": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-jobs": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-ptc-runtime": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-sandbox": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-scope": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-session": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-tools": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-user-approval": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-util-values": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-working-directory": "0.2.2-alpha.2",
     "@types/js-yaml": "4.0.9",
     "@types/node": "22.15.0",
     "@types/react": "19.2.2",

package/src/client/i18n.ts

@@ -259,6 +259,9 @@ export const EN: Record<string, string> = {
   '导出 SARIF': 'Export SARIF',
   '导出 SARIF 2.1.0（供 CI / GitHub Code Scanning 消费）':
     'Export SARIF 2.1.0 for CI / GitHub Code Scanning',
+  '导出 JSON 报告': 'Export JSON report',
+  '导出完整运行模型的 JSON（供 CI 仪表盘 / PR 机器人消费，无损格式）':
+    'Export the complete run model as JSON (lossless, for CI dashboards / PR bots)',
   '观测台页签（快捷键 1-9 / 0 / -）': 'Observatory tabs (keys 1-9 / 0 / -)',
   '{a0}（按 {a1} 切换）': '{a0} (press {a1})',
   '{a0}（按 - 切换）': '{a0} (press -)',
@@ -443,11 +446,50 @@ export const EN: Record<string, string> = {
   '防线：{a0}': 'Defense: {a0}',
   没有匹配该类型的防御事件: 'No defense events of this type',
 
+  // ── F11 preflight ────────────────────────────────────────────────────────
+  开跑预检: 'Preflight',
+  待预检: 'Not run yet',
+  未就绪: 'Not ready',
+  '复制 iterate_preflight 预检指令（含 JSON 参数）':
+    'Copy the iterate_preflight readiness instruction (JSON arguments included)',
+  运行预检: 'Run preflight',
+  开跑预检清单: 'Preflight checklist',
+  预检结果: 'Preflight result',
+  '开跑前先预检：确认验证命令、Git、工作区、陈旧门禁与中断断点都已就绪，避免开跑后才发现环境问题。':
+    'Run preflight first: confirm validation commands, git, the working tree, a stale gate and an interrupted checkpoint are ready, so you do not discover an environment problem mid-run.',
+  复制预检指令: 'Copy preflight instruction',
+  验证命令: 'Validation commands',
+  '已配置 {a0} 条验证命令': '{a0} validation command(s) configured',
+  '未配置 validation.commands —— 本轮无法证明修复，属阻断项':
+    'validation.commands is not configured — the run cannot prove fixes (blocking)',
+  'Git 仓库': 'Git repository',
+  '已检测到 Git 仓库': 'Git repository detected',
+  '不是 Git 仓库 —— changed-only 范围与 iterate_diff 需要它':
+    'Not a git repository — changed-only scope and iterate_diff need one',
+  工作区: 'Working tree',
+  '未提交改动：未知': 'Uncommitted changes: unknown',
+  '{a0} 个未提交/未跟踪文件 —— 建议先 commit 或 stash':
+    '{a0} uncommitted/untracked file(s) — commit or stash first',
+  工作区干净: 'Working tree clean',
+  陈旧门禁: 'Stale gate',
+  '磁盘上残留 FAIL 质量门禁 —— 开新轮前先清除':
+    'A stale FAIL quality gate is persisted — clear it before a fresh run',
+  '质量门禁：{a0}': 'Quality gate: {a0}',
+  无持久化质量门禁: 'No persisted quality gate',
+  中断断点: 'Interrupted checkpoint',
+  '存在中断断点（已恢复 {a0} 次）—— 恢复或清除后再开跑':
+    'An interrupted checkpoint is waiting (resumed {a0}x) — resume or clear it first',
+  无中断断点: 'No interrupted checkpoint',
+  配置验证命令: 'Configure validation',
+  恢复断点: 'Resume checkpoint',
+  '阻断 {a0} · 警告 {a1}': 'Blocking {a0} · warnings {a1}',
+  '预检失败：{a0}': 'Preflight failed: {a0}',
+  '预检只读，不会修改配置或文件。': 'Preflight is read-only; it never modifies config or files.',
+
   // ── copy feedback ────────────────────────────────────────────────────────
   已复制: 'Copied',
   复制失败: 'Copy failed',
 }
-
 let current: Lang = 'zh'
 let storage: LangStorage | null = null
 const listeners = new Set<(lang: Lang) => void>()

package/src/client/index.ts

@@ -75,6 +75,8 @@ import {
   scanSessionForQualityGate,
   scanSessionForExperienceBank,
   scanSessionForDefenseEvents,
+  scanSessionForPreflight,
+  buildPreflightInstruction,
   filterLiveEntries,
   filterTimelineEntries,
   serializeObservatoryExport,
@@ -113,6 +115,7 @@ import {
 import {
   renderRunReportMarkdown, // Markdown run report (PR-pasteable)
   renderRunReportSarif, // SARIF 2.1.0 log (CI / Code Scanning)
+  renderRunReportJson, // full normalized run model (CI dashboards / PR bots)
   runReportFilename, // deterministic download filename
 } from '../report-render.ts'
 import {
@@ -335,6 +338,24 @@ interface ObsQualityGate {
   dimensions?: ObsQualityGateDimension[]
 }
 
+/** One readiness check from `iterate_preflight` (F11). `detail` is structured
+ *  facts the panel localizes into a sentence. */
+interface ObsPreflightCheck {
+  id?: string
+  status?: string
+  detail?: Record<string, unknown>
+}
+
+/** Latest `iterate_preflight` report scanned out of the session stream. */
+interface ObsPreflight {
+  ok?: boolean
+  ready?: boolean
+  blocking?: number
+  warnings?: number
+  error?: string | null
+  checks?: ObsPreflightCheck[]
+}
+
 interface ObsExperienceEntry {
   id?: string
   timestamp?: string
@@ -582,6 +603,7 @@ const ITERATE_CSS = `
 .iterate-gate[data-status="pass"] { color: var(--dsw-alias-state-success-primary); background: color-mix(in srgb, var(--dsw-alias-state-success-primary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-state-success-primary) 28%, transparent); }
 .iterate-gate[data-status="fail"] { color: var(--dsw-alias-state-error-primary); background: color-mix(in srgb, var(--dsw-alias-state-error-primary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-state-error-primary) 28%, transparent); }
 .iterate-gate[data-status="pending"] { color: var(--dsw-alias-label-secondary); background: color-mix(in srgb, var(--dsw-alias-label-secondary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-label-secondary) 28%, transparent); }
+.iterate-gate[data-status="warn"] { color: var(--dsw-alias-state-warn-primary); background: color-mix(in srgb, var(--dsw-alias-state-warn-primary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-state-warn-primary) 28%, transparent); }
 
 /* v3.0: Experience bank hit highlight */
 .iterate-exp-hit { display: inline-flex; align-items: center; gap: 6px; padding: 2px 8px; border-radius: 6px; background: color-mix(in srgb, var(--dsw-alias-state-success-primary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-state-success-primary) 28%, transparent); font-size: 11px; color: var(--dsw-alias-state-success-primary); }
@@ -2178,6 +2200,8 @@ const OBS_TABS = [
   { key: 'f8', label: { zh: '质量门禁', en: 'Quality gate' }, hotkey: '8' },
   { key: 'f9', label: { zh: '经验银行', en: 'Experience bank' }, hotkey: '9' },
   { key: 'f10', label: { zh: '防御事件', en: 'Defense events' }, hotkey: '0' },
+  // v3.12: pre-run readiness checklist (validation/git/dirty-tree/stale-gate/checkpoint)
+  { key: 'f11', label: { zh: '开跑预检', en: 'Preflight' }, hotkey: '' },
 ] as const
 
 /** Digit → tab id. `1-9` map to F1–F9, `0` to F10, `-` back to the live feed
@@ -2266,6 +2290,12 @@ function latestDefenseEvents(session: unknown): ObsDefenseResult | null {
   return scanSessionForDefenseEvents(session) as ObsDefenseResult | null
 }
 
+/** Find the latest preflight report inside a session snapshot. */
+function latestPreflight(session: unknown): ObsPreflight | null {
+  if (!session) return null
+  return scanSessionForPreflight(session) as ObsPreflight | null
+}
+
 /** Build a human-pasteable `iterate_fix` instruction for one finding.
  *  Gap #10: delegates to the shared builder so the payload always names the
  *  four required `iterate_fix` params (file / content / finding / round) and
@@ -2294,6 +2324,7 @@ function ObservatoryPanel(props: SlotProps) {
   const qualityGate = latestQualityGate(session)
   const experienceBank = latestExperienceBank(session)
   const defenseEvents = latestDefenseEvents(session)
+  const preflight = latestPreflight(session)
 
   const [open, setOpen] = React.useState(false)
   const [tab, setTab] = React.useState('live')
@@ -2419,12 +2450,14 @@ function ObservatoryPanel(props: SlotProps) {
    *  SARIF 2.1.0 (CI / GitHub Code Scanning). Rendered from the SAME shared
    *  data model as the `iterate_report` tool, so the button and the tool can
    *  never disagree. Download-first with a copy fallback, like `exportObservatory`. */
-  const exportReport = (format: 'markdown' | 'sarif') => {
+  const exportReport = (format: 'markdown' | 'sarif' | 'json') => {
     if (!manifest) return
     const extra = { qualityGate, experienceBank, defenseEvents }
     const content = format === 'sarif'
       ? JSON.stringify(renderRunReportSarif(manifest, extra), null, 2)
-      : renderRunReportMarkdown(manifest, extra, { lang: getLang() })
+      : format === 'json'
+        ? JSON.stringify(renderRunReportJson(manifest, extra), null, 2)
+        : renderRunReportMarkdown(manifest, extra, { lang: getLang() })
     const filename = runReportFilename(format)
     const key = `report-${format}`
     const flash = () => {
@@ -3353,6 +3386,176 @@ function ObservatoryPanel(props: SlotProps) {
     )
   }
 
+  // ── F11: Preflight readiness ──────────────────────────────────────────────
+  // v3.12: renders the latest iterate_preflight checklist scanned from the
+  // session stream. Each warn/fail row offers the exact fix instruction
+  // (configure validation, clear a stale gate, resume an interrupted
+  // checkpoint) so the environment is repaired BEFORE a round is spent on it.
+  const renderPreflight = () => {
+    const preflightInstruction = buildPreflightInstruction()
+    const report = preflight
+    const hasReport = report !== null && Array.isArray(report.checks)
+    const ready = report !== null && report.ready === true
+    const blocking = Number(report && report.blocking != null ? report.blocking : 0)
+    const warnings = Number(report && report.warnings != null ? report.warnings : 0)
+    const statusLabel = !hasReport ? t('待预检') : ready ? t('就绪') : t('未就绪')
+    const statusTone = !hasReport ? 'pending' : ready ? 'pass' : 'fail'
+    const headerBar = React.createElement('div', { className: 'iterate-obs-bar', style: { marginBottom: 8 } },
+      React.createElement('b', {}, t('开跑预检')),
+      React.createElement('span', { className: 'iterate-gate', 'data-status': statusTone }, statusLabel),
+      React.createElement('button', {
+        className: 'iterate-btn', 'data-primary': '', 'data-copied': copiedKey === 'preflight' ? '' : undefined,
+        onClick: () => copyInstruction('preflight', preflightInstruction),
+        title: t('复制 iterate_preflight 预检指令（含 JSON 参数）'),
+      }, copiedKey === 'preflight' ? t('已复制') : t('运行预检')),
+    )
+
+    if (!hasReport) {
+      return React.createElement('div', {},
+        headerBar,
+        React.createElement('div', { className: 'iterate-obs-block' },
+          React.createElement('div', { className: 'iterate-obs-block-head' },
+            React.createElement('span', {}, t('开跑预检清单')),
+            React.createElement('span', { className: 'iterate-obs-badge' }, 'v3.12'),
+          ),
+          React.createElement('div', { className: 'iterate-obs-block-body' },
+            React.createElement('div', { className: 'iterate-obs-msg' },
+              // Gap #4: separate "pulled and empty" from "never pulled".
+              diskEmptyStateText(toolCalledInSession(session, 'iterate_preflight'), t('预检结果'), getLang()),
+            ),
+            React.createElement('div', { className: 'iterate-obs-msg', style: { marginTop: 6 } },
+              t('开跑前先预检：确认验证命令、Git、工作区、陈旧门禁与中断断点都已就绪，避免开跑后才发现环境问题。'),
+            ),
+            React.createElement('div', { className: 'iterate-obs-bar', style: { marginTop: 8 } },
+              React.createElement('button', {
+                className: 'iterate-btn', 'data-copied': copiedKey === 'preflight-instr' ? '' : undefined,
+                onClick: () => copyInstruction('preflight-instr', preflightInstruction),
+                title: t('复制预检指令'),
+              }, copiedKey === 'preflight-instr' ? t('已复制') : t('复制预检指令')),
+            ),
+          ),
+        ),
+      )
+    }
+
+    // A tool-level failure (bad path, root refused) carries no usable checks —
+    // surface the error instead of a misleading "ready, 0 blocking" summary.
+    if (report && report.ok === false) {
+      return React.createElement('div', {},
+        headerBar,
+        React.createElement('div', { className: 'iterate-obs-block' },
+          React.createElement('div', { className: 'iterate-obs-block-head' },
+            React.createElement('span', {}, t('开跑预检清单')),
+            React.createElement('span', { className: 'iterate-obs-badge' }, 'v3.12'),
+          ),
+          React.createElement('div', { className: 'iterate-obs-block-body' },
+            React.createElement('div', { className: 'iterate-obs-msg' },
+              tf('预检失败：{a0}', { a0: String(report.error || '') }),
+            ),
+          ),
+        ),
+      )
+    }
+
+    // Localized label + detail per check id. Detail is structured facts from
+    // the tool, so the panel — not the tool — owns the wording/language.
+    const CHECK_META: Record<string, { label: string; detail: (d: Record<string, unknown>) => string }> = {
+      validation: {
+        label: t('验证命令'),
+        detail: (d) => {
+          const n = Number(d.commandCount ?? 0)
+          return n > 0
+            ? tf('已配置 {a0} 条验证命令', { a0: n })
+            : t('未配置 validation.commands —— 本轮无法证明修复，属阻断项')
+        },
+      },
+      git: {
+        label: t('Git 仓库'),
+        detail: (d) => (d.isRepo === true ? t('已检测到 Git 仓库') : t('不是 Git 仓库 —— changed-only 范围与 iterate_diff 需要它')),
+      },
+      'dirty-tree': {
+        label: t('工作区'),
+        detail: (d) => {
+          const n = d.changedFiles
+          if (n === null || n === undefined) return t('未提交改动：未知')
+          const num = Number(n)
+          return num > 0
+            ? tf('{a0} 个未提交/未跟踪文件 —— 建议先 commit 或 stash', { a0: num })
+            : t('工作区干净')
+        },
+      },
+      'stale-gate': {
+        label: t('陈旧门禁'),
+        detail: (d) => {
+          const s = d.overallStatus
+          if (s === 'fail') return t('磁盘上残留 FAIL 质量门禁 —— 开新轮前先清除')
+          return s ? tf('质量门禁：{a0}', { a0: String(s) }) : t('无持久化质量门禁')
+        },
+      },
+      'interrupted-checkpoint': {
+        label: t('中断断点'),
+        detail: (d) => {
+          if (d.interrupted === true) {
+            const rc = Number(d.resumeCount ?? 0)
+            return tf('存在中断断点（已恢复 {a0} 次）—— 恢复或清除后再开跑', { a0: rc })
+          }
+          return t('无中断断点')
+        },
+      },
+    }
+
+    // Repair action per check id; null = guidance only (no tool can fix it).
+    const fixFor = (id: string): { key: string; label: string; instruction: string } | null => {
+      switch (id) {
+        case 'validation':
+          return { key: 'preflight-fix-validation', label: t('配置验证命令'), instruction: buildConfigFieldInstruction('validation.commands') }
+        case 'stale-gate':
+          return { key: 'preflight-fix-gate', label: t('清除门禁'), instruction: buildQualityGateClearInstruction() }
+        case 'interrupted-checkpoint':
+          return { key: 'preflight-fix-checkpoint', label: t('恢复断点'), instruction: buildCheckpointResumeInstruction() }
+        default:
+          return null
+      }
+    }
+
+    const rows = (report.checks || []).map((c, i) => {
+      const id = String(c.id || '')
+      const status = String(c.status || 'warn')
+      const meta = CHECK_META[id]
+      const label = meta ? meta.label : id || '?'
+      const detail = meta ? meta.detail(c.detail || {}) : ''
+      const fix = status !== 'pass' ? fixFor(id) : null
+      return React.createElement('div', { key: `pf-${i}`, className: 'iterate-obs-row' },
+        React.createElement('span', { className: 'iterate-gate', 'data-status': status }, status.toUpperCase()),
+        React.createElement('b', {}, label),
+        React.createElement('span', { className: 'iterate-obs-msg' }, detail),
+        fix
+          ? React.createElement('button', {
+              className: 'iterate-btn', 'data-copied': copiedKey === fix.key ? '' : undefined,
+              onClick: () => copyInstruction(fix.key, fix.instruction),
+              title: fix.instruction,
+            }, copiedKey === fix.key ? t('已复制') : fix.label)
+          : null,
+      )
+    })
+
+    return React.createElement('div', {},
+      headerBar,
+      React.createElement('div', { className: 'iterate-obs-block' },
+        React.createElement('div', { className: 'iterate-obs-block-head' },
+          React.createElement('span', {}, t('开跑预检清单')),
+          React.createElement('span', { className: 'iterate-obs-head-meta' },
+            tf('阻断 {a0} · 警告 {a1}', { a0: blocking, a1: warnings }),
+          ),
+        ),
+        React.createElement('div', { className: 'iterate-obs-block-body' },
+          React.createElement('div', { className: 'iterate-obs-msg' }, t('预检只读，不会修改配置或文件。')),
+          ...rows,
+        ),
+      ),
+    )
+  }
+
   // ── Live: real-time secondary-subagent activity stream (newest first) ─────
   const renderLive = () => {
     const liveEntries = manifest.live || []
@@ -3437,6 +3640,7 @@ function ObservatoryPanel(props: SlotProps) {
       case 'f8': return renderQualityGate()
       case 'f9': return renderExperienceBank()
       case 'f10': return renderDefenseEvents()
+      case 'f11': return renderPreflight()
       default: return null
     }
   }
@@ -3481,8 +3685,8 @@ function ObservatoryPanel(props: SlotProps) {
               title: t('将观测台全部数据导出为 JSON（优先下载，失败则复制）'),
             }, copiedKey === 'export' ? t('已导出') : t('导出 JSON')),
             // v3.9: portable report export — Markdown for a PR body, SARIF for
-            // CI / GitHub Code Scanning. Rendered from the same data model as
-            // the `iterate_report` tool.
+            // CI / GitHub Code Scanning, JSON for CI dashboards / PR bots.
+            // Rendered from the same data model as the `iterate_report` tool.
             React.createElement('button', {
               className: 'iterate-btn', 'data-copied': copiedKey === 'report-markdown' ? '' : undefined,
               onClick: () => exportReport('markdown'),
@@ -3493,6 +3697,14 @@ function ObservatoryPanel(props: SlotProps) {
               onClick: () => exportReport('sarif'),
               title: t('导出 SARIF 2.1.0（供 CI / GitHub Code Scanning 消费）'),
             }, copiedKey === 'report-sarif' ? t('已导出') : t('导出 SARIF')),
+            // v3.11: lossless JSON export — the complete normalized run model
+            // (findings + fixes + validations + quality gate + experience bank
+            // + defense events) for CI dashboards and PR bots.
+            React.createElement('button', {
+              className: 'iterate-btn', 'data-copied': copiedKey === 'report-json' ? '' : undefined,
+              onClick: () => exportReport('json'),
+              title: t('导出完整运行模型的 JSON（供 CI 仪表盘 / PR 机器人消费，无损格式）'),
+            }, copiedKey === 'report-json' ? t('已导出') : t('导出 JSON 报告')),
             // Gap #4: `.iterate/` artifacts are unreachable from the browser;
             // this copies the one instruction that makes the model echo them
             // into the session stream (which is what every panel scans).

package/src/index.ts

@@ -46,6 +46,7 @@ import { registerExperienceBankTool } from './tools/experience-bank.ts'
 import { registerQualityGateTool } from './tools/quality-gate.ts'
 import { registerDefenseEventsTool } from './tools/defense-events.ts'
 import { registerReportTool } from './tools/report.ts'
+import { registerPreflightTool } from './tools/preflight.ts'
 import { registerSessionHooks } from './session-hooks.ts'
 import { registerLiveCapture } from './live.ts'
 import { installWorkingDirectoryContext } from './working-directory.ts'
@@ -71,11 +72,11 @@ export function apply(ctx: Context): void {
   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: Array<[string, () => void]> = [
     ['iterate_config', () => registerConfigTool(ctx)],
     ['iterate_validate', () => registerValidateTool(ctx)],
@@ -97,6 +98,8 @@ export function apply(ctx: Context): void {
     ['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/src/report-render.ts

@@ -20,10 +20,15 @@
  *   - **sarif**    — SARIF 2.1.0 for CI / GitHub Code Scanning (ruleId =
  *     review dimension, severity → error | warning | note, file+line
  *     locations, suggested fix attached).
+ *   - **json**     — the complete normalized run model (see {@link RunReportData})
+ *     as a machine-readable JSON document. This is the ONLY format that carries
+ *     the full model (findings + fixes + validations + quality gate + experience
+ *     bank + defense events) without lossy projection, so CI dashboards and PR
+ *     bots can consume the exact same facts the human report shows.
  */
 
 /** Report formats accepted by the tool and the export buttons. */
-export const REPORT_FORMATS = ['markdown', 'sarif'] as const
+export const REPORT_FORMATS = ['markdown', 'sarif', 'json'] as const
 
 /** Severity ordering (lowest index = most severe). */
 const SEVERITY_ORDER = ['critical', 'high', 'medium', 'low'] as const
@@ -563,6 +568,66 @@ export function renderRunReportSarif(
   }
 }
 
+/**
+ * Render the complete normalized run model as a JSON document.
+ *
+ * This is the lossless format: unlike Markdown (human projection) and SARIF
+ * (findings-only code-scanning log), the JSON carries EVERY fact the run
+ * recorded — findings, fixes, validations, convergence, the quality gate, the
+ * experience bank, and defense events — as structured data. CI dashboards and
+ * PR bots can consume it without re-parsing a human report. A missing or
+ * partial transcript still yields a valid document (empty arrays, null stores),
+ * so an export never fails because a run was interrupted.
+ */
+export interface RunReportJson {
+  $schema: 'iterate-run-report/1'
+  project: string
+  goal: string
+  mode: string | null
+  taskMode: string | null
+  round: number
+  maxRounds: number
+  active: boolean
+  stoppedReason: string | null
+  updatedAt: string
+  convergence: number[]
+  severityCounts: { critical: number; high: number; medium: number; low: number }
+  findings: ReportFinding[]
+  fixes: ReportFix[]
+  validations: ReportValidation[]
+  qualityGate: Record<string, unknown> | null
+  experienceBank: Record<string, unknown> | null
+  defenseEvents: Record<string, unknown> | null
+}
+
+/** Render a JSON document from the same normalized data. */
+export function renderRunReportJson(
+  manifest: unknown,
+  extra?: { qualityGate?: unknown; experienceBank?: unknown; defenseEvents?: unknown } | null,
+): RunReportJson {
+  const data = buildRunReportData(manifest, extra)
+  return {
+    $schema: 'iterate-run-report/1',
+    project: data.project,
+    goal: data.goal,
+    mode: data.mode,
+    taskMode: data.taskMode,
+    round: data.round,
+    maxRounds: data.maxRounds,
+    active: data.active,
+    stoppedReason: data.stoppedReason,
+    updatedAt: data.updatedAt,
+    convergence: data.convergence,
+    severityCounts: data.severityCounts,
+    findings: data.findings,
+    fixes: data.fixes,
+    validations: data.validations,
+    qualityGate: data.qualityGate,
+    experienceBank: data.experienceBank,
+    defenseEvents: data.defenseEvents,
+  }
+}
+
 /**
  * Render a report in the requested format. Unknown formats fall back to
  * Markdown (the tool's default).
@@ -572,8 +637,9 @@ export function renderRunReport(
   manifest: unknown,
   extra?: { qualityGate?: unknown; experienceBank?: unknown; defenseEvents?: unknown } | null,
   opts?: ReportRenderOptions,
-): string | SarifLog {
+): string | SarifLog | RunReportJson {
   if (format === 'sarif') return renderRunReportSarif(manifest, extra, opts)
+  if (format === 'json') return renderRunReportJson(manifest, extra)
   return renderRunReportMarkdown(manifest, extra, opts)
 }
 
@@ -582,7 +648,7 @@ export function renderRunReport(
  * `iterate-report-2026-10-18T01-02-03-000Z.md`.
  */
 export function runReportFilename(format: string, opts?: { now?: string }): string {
-  const ext = format === 'sarif' ? 'sarif' : 'md'
+  const ext = format === 'sarif' ? 'sarif' : format === 'json' ? 'json' : 'md'
   const stamp =
     opts?.now && opts.now ? opts.now.replace(/[:.]/g, '-') : new Date().toISOString().replace(/[:.]/g, '-')
   return `iterate-report-${stamp}.${ext}`