cardbuddy 0.14.3 → 0.16.0

package/dist/vendored/skills/dsl-card-generator/scripts/iterate.mjs

@@ -36,23 +36,37 @@ import path from 'node:path'
 import readline from 'node:readline'
 import crypto from 'node:crypto'
 import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
 
 import { expandIR, runAutofixAndValidate, syncReferencedSlices } from './expand_ir.mjs'
 import { rewriteSliceRefs } from './lib/slice_dedupe.mjs'
+import { auditGeometry, describeGeometry } from './lib/geometry_audit.mjs'
 import { lint } from './lint_card.mjs'
+import { buildFidelityReport } from './check_fidelity.mjs'
+import { buildReadinessReport } from './readiness.mjs'
 import { createRenderSession, renderCardScreenshot } from './render_card.mjs'
 import { copyCardDesignImage } from './lib/design_image.mjs'
-import { cardsDir, cardSchemaPath, cardDataPath, readJson, repoRoot } from './lib/paths.mjs'
+import { cardsDir, cardSchemaPath, cardDataPath, readJson, repoRoot, scratchDir as SCRATCH_DIR } from './lib/paths.mjs'
 
 const { PNG } = await import('pngjs')
 
 const DEFAULT_DIFF_DIR = path.join(repoRoot, '.card-diffs')
 const DEFAULT_WIDTH = 375
-/** 报告落盘目录：门禁（--gate）只认这里的机器产物，不认模型自述 */
-const SCRATCH_DIR = path.join(repoRoot, '.cache', 'ai-scratch')
+/** 报告落盘目录：门禁（--gate）只认这里的机器产物，不认模型自述。
+ *  路径单源在 lib/paths.mjs（check_fidelity / readiness 也读同一份 —— 历史事故：
+ *  check_fidelity 自己拼 `<cardDir>/.audit.json`，真实位置却是 `.cache/ai-scratch/`）。 */
 const PREFLIGHT_SCRIPT = path.join(repoRoot, 'skills', 'dsl-card-generator', 'scripts', 'preflight.mjs')
-/** 收敛门禁阈值（协议 S5/S6 的机器化版本，改这里即改门禁） */
-const GATE = { match: 95, heightDelta: 0, widthDelta: 0, contentOffset1x: 2 }
+/** 收敛门禁阈值（协议 S5/S6 的机器化版本，改这里即改门禁）。
+ *  match 是**唯一权威**：SKILL.md 只引用这里的语义，不复制具体数字，
+ *  避免「文档写 85、代码判 95」导致模型提前收工被 --gate 判 FAIL 返工。
+ *  可用环境变量 DSL_CARD_GATE_MATCH 覆盖（非法/空值回落默认）。 */
+const GATE_MATCH_OVERRIDE = Number(process.env.DSL_CARD_GATE_MATCH)
+const GATE = {
+  match: Number.isFinite(GATE_MATCH_OVERRIDE) && GATE_MATCH_OVERRIDE > 0 ? GATE_MATCH_OVERRIDE : 95,
+  heightDelta: 0,
+  widthDelta: 0,
+  contentOffset1x: 2,
+}
 
 /* ── IR 原子编辑（--set）────────────────────────────────────
  * 点路径寻址，数字段按数组下标：children.0.s.margin.marginTop="7"
@@ -227,6 +241,268 @@ function diffHotspots(renderPng, designPng, { cols = 4, rows = 8, floorPct = 3,
   return cells.slice(0, maxCells)
 }
 
+/* ── 结构性缺口（structuralGaps）：逐行几乎全异的连续带区 ──
+ * 存在理由（gen-1 实测）：雷达图区块整块漏建 / 背景整卡错涂时，hotspots 只给碎片坐标、
+ * contributors 把注意力引到「10分/分」这类局部微调，模型调了 8 轮 padding/gap 也没碰到根因。
+ * 口径：逐行统计 design vs render 的像素差异率（色距 >30），连续 ≥40pt（1x）且差异率 ≥85%
+ * 的带区记为缺口带——要么该带内容整块漏建，要么底色/背景在该带整层错涂；只报事实不猜因。 */
+export function detectStructuralGaps(renderPng, designPng, { scale = 2, minGapPt = 40, maxGaps = 3, rowDiff = 0.85 } = {}) {
+  const h = Math.min(renderPng.height, designPng.height)
+  const w = Math.min(renderPng.width, designPng.width)
+  const step = 2
+  const rows = []
+  for (let y = 0; y < h; y += step) {
+    let diff = 0
+    let seen = 0
+    for (let x = 0; x < w; x += step) {
+      const i = (y * w + x) * 4
+      const dr = Math.abs(renderPng.data[i] - designPng.data[i])
+      const dg = Math.abs(renderPng.data[i + 1] - designPng.data[i + 1])
+      const db = Math.abs(renderPng.data[i + 2] - designPng.data[i + 2])
+      if (Math.max(dr, dg, db) > 30) diff++
+      seen++
+    }
+    rows.push({ y, ratio: diff / seen })
+  }
+  // 设计稿行墨量（供归因参考：该带在设计稿里有多少内容）
+  const isInk = (png, x, y) => {
+    const i = (y * png.width + x) * 4
+    if (png.data[i + 3] < 8) return false
+    return Math.abs(255 - png.data[i]) + Math.abs(255 - png.data[i + 1]) + Math.abs(255 - png.data[i + 2]) > 48
+  }
+  const gaps = []
+  let cur = null
+  for (const r of rows) {
+    if (r.ratio >= rowDiff) {
+      if (!cur) cur = { y0: r.y, y1: r.y, ink: [] }
+      else cur.y1 = r.y
+      cur.ink.push(isInk(designPng, Math.floor(w / 2), r.y) ? 1 : 0)
+    } else if (cur) {
+      gaps.push(cur)
+      cur = null
+    }
+  }
+  if (cur) gaps.push(cur)
+  return gaps
+    .filter((g) => (g.y1 - g.y0) / scale >= minGapPt)
+    .sort((a, b) => (b.y1 - b.y0) - (a.y1 - a.y0))
+    .slice(0, maxGaps)
+    .map((g) => ({
+      y: Math.round(g.y0 / scale),
+      h: Math.round((g.y1 - g.y0) / scale),
+      designInkPct: Number(((g.ink.reduce((a, b) => a + b, 0) / g.ink.length) * 100).toFixed(1)),
+    }))
+}
+
+/* ── 分项归因（contributors）：把差异热区落到具体渲染节点 ─────────
+ * 存在理由（2026-09-21 实测）：那一轮 23 次 iterate 的报告只说「match 90.04、高度差 2px」，
+ * 从不说是**哪个节点**差 —— 模型只能整份重写 IR 去试，16 次全量重写、12.4 万字符、约占全部输出的一半。
+ * 能力其实齐了（render_card.mjs 的 elementBoxes 逐元素度量、iterate 的 --elements），
+ * 缺的只是「热区 → 元素」这一步映射。
+ *
+ * 坐标系：hotspots 已由 diffHotspots 折算到 1x 卡内坐标，elementBoxes 本就是 .phone__screen
+ * 相对 CSS 像素 —— 两者同系，可直接相交。spec.json 的元素是**画板坐标**（1x，如 375 画板），
+ * 需减去 card.rect 的 (x,y) 平移到卡内。
+ *
+ * 归因原则：只给**可证伪的事实**（元素自己实测的 h / scrollH、同类中位高度、设计稿高度），
+ * 不猜「疑似哪个属性」以外的因果；宁缺勿滥 —— 匹配不上的元素就不给 designH。
+ */
+const CONTRIB_MAX_HOTSPOTS = 5
+const CONTRIB_MAX_ELEMENTS = 3
+/** 元素主体落在热区内的最小比例：低于此值说明只是擦边，不算这个热区的成因 */
+const CONTRIB_SELF_RATIO = 0.5
+/** 与设计稿文本匹配时允许的最大纵向位移（卡内 1x px）：超过就当同名不同节点，不给 deltaH */
+const CONTRIB_MATCH_DY = 24
+
+const r1 = (n) => Math.round(n * 10) / 10
+const normText = (t) => String(t ?? '').replace(/\s+/g, ' ').trim()
+
+/**
+ * 读设计稿侧的卡内元素（供 deltaH）。
+ * 卡索引按 `--design` 的 `card-N.png` 推断（多卡画板的聚焦裁切命名约定），缺省第一张。
+ */
+/**
+ * 跑一次要素清单比对（spec 文本 → schema 节点），失败不阻断本轮（宁缺勿滥：拿不到就不给门禁项）。
+ * 卡片序号与 loadDesignElements 同源（设计稿文件名 card-N.png），保证「比的是同一张卡」。
+ */
+export function loadFidelityReport({ specPath, schemaPath, designPath, cardId }) {
+  if (!specPath || !schemaPath || !fs.existsSync(specPath) || !fs.existsSync(schemaPath)) return null
+  try {
+    const spec = JSON.parse(fs.readFileSync(specPath, 'utf8'))
+    const cards = Array.isArray(spec.cards) ? spec.cards : []
+    const m = /card-(\d+)\.png$/i.exec(String(designPath || ''))
+    const idx = m ? Math.max(0, Math.min(cards.length - 1, Number(m[1]) - 1)) : 0
+    // cardId 显式传入：schema 可能写在临时 out 目录（`--out /tmp/...`），
+    // 而审计落点按**卡片 id** 命名（.cache/ai-scratch/<id>.audit.json），靠目录名推会取不到。
+    const r = buildFidelityReport({ spec: specPath, schema: schemaPath, card: idx + 1, id: cardId || '' })
+    return {
+      cardId,
+      total: r.elements.texts.total,
+      matched: r.elements.texts.matched,
+      missing: r.elements.texts.missing,
+      invented: r.elements.texts.invented,
+      slices: r.elements.slices,
+      // 全类型要素缺口（2026-09-25）：图标 / 分割线数量对账（warning 级信息项）
+      symbols: r.elements.symbols,
+      shapes: r.elements.shapes,
+    }
+  } catch {
+    return null
+  }
+}
+
+export function loadDesignElements(specPath, designPath) {
+  if (!specPath || !fs.existsSync(specPath)) return null
+  let spec
+  try {
+    spec = JSON.parse(fs.readFileSync(specPath, 'utf8'))
+  } catch {
+    return null
+  }
+  const cards = Array.isArray(spec.cards) ? spec.cards : []
+  if (!cards.length) return null
+  const m = /card-(\d+)\.png$/i.exec(String(designPath || ''))
+  const idx = m ? Math.max(0, Math.min(cards.length - 1, Number(m[1]) - 1)) : 0
+  const card = cards[idx]
+  const cr = card?.rect
+  if (!cr) return null
+  const src = Array.isArray(card.elements) && card.elements.length ? card.elements : Array.isArray(spec.elements) ? spec.elements : []
+  const tx = Number(cr.x) || 0
+  const ty = Number(cr.y) || 0
+  return {
+    cardIndex: idx,
+    width: Number(cr.width) || 0,
+    height: Number(cr.height) || 0,
+    /** y 已平移到卡内坐标，与渲染元素同系 */
+    texts: src
+      .filter((e) => e?.rect && normText(e.text))
+      .map((e) => ({ text: normText(e.text), h: Number(e.rect.height) || 0, y: (Number(e.rect.y) || 0) - ty })),
+  }
+}
+
+/** 分项归因：热区 → 覆盖率最高的最内层元素（+ 可选的设计稿高度差） */
+export function attributeContributors({ hotspots, elements, design, contentOffset1x }) {
+  if (!Array.isArray(hotspots) || !hotspots.length) return null
+  const els = (elements || []).filter((e) => e && e.w > 0 && e.h > 0)
+  if (!els.length) return null
+
+  // 同类元素高度中位数：抓「同类里某一项高度异常」。整体偏移/缩放会同时影响同类，
+  // 所以这个判据不会把「整卡都差 2px」误报成「某个元素有问题」。
+  const hByCls = new Map()
+  for (const e of els) {
+    const k = e.cls || '?'
+    if (!hByCls.has(k)) hByCls.set(k, [])
+    hByCls.get(k).push(e.h)
+  }
+  const hMed = new Map()
+  for (const [k, arr] of hByCls) {
+    const s = [...arr].sort((a, b) => a - b)
+    hMed.set(k, s[Math.floor(s.length / 2)])
+  }
+
+  // 设计稿文本 → 高度（同文本多条时取 y 最近的一条，且位移要在容差内）
+  const designTexts = design?.texts || []
+  const pick = (e) => {
+    const t = normText(e.text)
+    if (!t) return null
+    let hit = null
+    for (const d of designTexts) {
+      if (d.text !== t) continue
+      const dy = Math.abs(d.y - e.y)
+      if (dy > CONTRIB_MATCH_DY) continue
+      if (!hit || dy < hit.dy) hit = { d, dy }
+    }
+    return hit
+  }
+
+  const out = []
+  for (const hot of hotspots.slice(0, CONTRIB_MAX_HOTSPOTS)) {
+    const area = Math.max(1, hot.w * hot.h)
+    const inHot = []
+    for (const e of els) {
+      const ox = Math.max(0, Math.min(e.x + e.w, hot.x + hot.w) - Math.max(e.x, hot.x))
+      const oy = Math.max(0, Math.min(e.y + e.h, hot.y + hot.h) - Math.max(e.y, hot.y))
+      const inter = ox * oy
+      if (inter <= 0) continue
+      const selfRatio = inter / (e.w * e.h)
+      if (selfRatio < CONTRIB_SELF_RATIO) continue // 主体不在此热区，只是擦边
+      inHot.push({ e, inter })
+    }
+    if (!inHot.length) continue
+    // 面积升序 = 最具体的节点在前：热区里嵌套的父/子都命中时，最小的那个才是差异所在
+    inHot.sort((a, b) => a.e.w * a.e.h - b.e.w * b.e.h)
+
+    const picked = inHot.slice(0, CONTRIB_MAX_ELEMENTS).map(({ e, inter }) => {
+      const m = pick(e)
+      const dH = m ? r1(e.h - m.d.h) : null
+      const med = hMed.get(e.cls) ?? null
+      const flags = []
+      if (e.scrollH > e.clientH + 1) flags.push('text-clipped')
+      if (med != null && Math.abs(e.h - med) >= 1) flags.push(`vs-siblings ${r1(e.h - med) > 0 ? '+' : ''}${r1(e.h - med)}`)
+      if (dH != null && Math.abs(dH) >= 1) flags.push(`vs-design ${dH > 0 ? '+' : ''}${dH}`)
+      if (Math.abs(hot.y + hot.h - (e.y + e.h)) <= 2) flags.push('bottom-edge')
+      if (Math.abs(hot.x + hot.w - (e.x + e.w)) <= 2) flags.push('right-edge')
+      return {
+        cid: e.cid,
+        cls: e.cls,
+        text: String(e.text || '').slice(0, 24),
+        rect: [e.x, e.y, e.w, e.h],
+        h: e.h,
+        hSibling: med,
+        designH: m ? m.d.h : null,
+        dH,
+        hotCover: Math.round((inter / area) * 100) / 100,
+        flags,
+      }
+    })
+
+    const top = picked[0]
+    const acts = []
+    if (top.flags.includes('text-clipped')) acts.push('该节点文本被裁剪（scrollH > clientH）⇒ 查 isMaxLine / maxLine / lineHeight')
+    if (top.flags.some((f) => f.startsWith('vs-design'))) acts.push(`该节点高度与设计稿差 ${top.dH} ⇒ 查 paddingTop/Bottom 与 lineHeight`)
+    if (top.flags.some((f) => f.startsWith('vs-siblings'))) acts.push(`该节点高度与同类中位（${top.hSibling}）不同 ⇒ 查该节点的 padding/margin，而不是整层 gap`)
+    if (top.flags.includes('bottom-edge') || top.flags.includes('right-edge')) acts.push('热区贴该节点下/右边界 ⇒ 差异在边界外（下边距 / 圆角 / 阴影）或该节点比设计高')
+    if (!acts.length) acts.push('按热区内的具体节点逐个核对 padding / lineHeight / gap')
+    out.push({
+      hotspot: [hot.x, hot.y, hot.w, hot.h],
+      diffPct: hot.diffPct,
+      elements: picked,
+      hint: `热区 [${hot.x},${hot.y},${hot.w},${hot.h}]（差异 ${hot.diffPct}%）主要落在 ${top.cls || '?'}「${top.text || '无文本'}」(${top.cid}) 上：${acts[0]}。一轮只改这一项，改完立刻重跑 iterate 看是否刷新最好成绩${contentOffset1x && (Math.abs(contentOffset1x.dx) > 2 || Math.abs(contentOffset1x.dy) > 2) ? '；注意本轮内容整体偏移 dx=' + contentOffset1x.dx + ' dy=' + contentOffset1x.dy + '，先修对齐再动这里' : ''}。`,
+    })
+  }
+  return out.length ? out : null
+}
+
+/** 清除多余轮次快照：保留最近 keep 轮 + best（每次 iterate 收尾调用，避免无限堆积） */
+function pruneSnapshots(cardId, keep = 12) {
+  try {
+    const names = fs
+      .readdirSync(SCRATCH_DIR)
+      .filter((n) => n.startsWith(`${cardId}.ir.r`) && n.endsWith('.json'))
+    if (names.length <= keep) return 0
+    let bestRound = 0
+    try {
+      bestRound = Number(JSON.parse(fs.readFileSync(path.join(SCRATCH_DIR, `${cardId}.iterate.json`), 'utf8'))?.best?.round) || 0
+    } catch {}
+    const roundOf = (n) => Number(/(\d+)\.json$/.exec(n)?.[1] || 0)
+    // 先按轮次降序，保留最近 keep 轮；best 那一轮额外豁免（回退要按 --round 直取文件名）
+    const doomed = names
+      .sort((a, b) => roundOf(b) - roundOf(a))
+      .slice(keep)
+      .filter((n) => roundOf(n) !== bestRound)
+    let n = 0
+    for (const f of doomed) {
+      try {
+        fs.unlinkSync(path.join(SCRATCH_DIR, f))
+        n++
+      } catch {}
+    }
+    return n
+  } catch {
+    return 0
+  }
+}
+
 /* ── 合成并排对比图（内存，可选写盘） ──────────────────────── */
 function composeSideBySide(designBuf, renderBuf) {
   const designPng = PNG.sync.read(designBuf)
@@ -291,7 +567,95 @@ function hashFile(p) {
   }
 }
 
-/** preflight.mjs = quickref「Pre-flight Checklist」12 条里可机械化的 10 条。
+/**
+ * 停滞判据（2026-09-21 重写）：以**历史最好成绩**为基准，看连续多少轮没有刷新它。
+ *
+ * 旧判据要求「match 与上轮几乎相同（|Δ|<0.3）**且** top-3 热区坐标全等」才累加，而实测形态是
+ * **震荡下滑**（79.6→92.42→90.04，13 轮里 11 轮更差）——热区每轮都在动，23 份报告里 stalled
+ * 出现 0 次，模型却按提示词在等这个永不出现的信号，一路盲调到 707 万 token 才被人工中止。
+ * 「没有更好」比「一模一样」才是真正该叫停的形态。
+ */
+const STALL_ROUNDS = 3
+/**
+ * 高度差连续多少轮一模一样（且不为 0）即判「卡在同一处」。
+ * 门禁要求 heightDelta=0，而实测两次建卡回合都出现过「heightDelta 恒定 56、match 在原地打转」——
+ * 只盯 match 的判据会一直判「还在动」，模型就继续做像素微调，而那个撑高 56px 的结构问题从没被碰过。
+ * 高度一动不动 = 证据链该换了，不该再调像素。
+ */
+const HEIGHT_FROZEN_ROUNDS = 3
+/**
+ * 高度差得大到这个程度，冻结才算「结构问题」而不是「最后一轮才收的像素差」。
+ * 2px 这种量级可能是收尾一次性对齐掉的；56px 那种只可能是漏了/多了元素或间距累加。
+ * 没有这条下限，一条 match 从 79 一路涨到 92 的好轨迹会被误判成高度停滞（实测重放用例就是这种）。
+ */
+const HEIGHT_FROZEN_MIN_PX = 8
+/** match 提升多少才算刷新最好成绩（低于它是噪声，不算进步） */
+const STALL_EPS = 0.5
+/** 本轮比上轮低多少分算「明确变差」：连续变差时必须提示回退 */
+const REGRESS_DELTA = 1
+/**
+ * 每缺一条要素折算成多少「等效 match 分」。
+ *
+ * 判据三次演进（2026-09-21 二次修正，前两版都在真轨迹上翻车）：
+ *   ① 纯 match：把「删节点 / 换成自编占位文案换来 match 上升」记成进步，回退目标也存成那一轮。
+ *   ② 字典序「要素齐优先于任何像素分」：修好了 ①，却在 helloCard 真轨迹上更糟——
+ *      r1 要素齐（19/19）但 match 51.71 / heightDelta 800（结构整个塌掉、渲染高 888px），
+ *      r4 只缺 2 条但 match 89.71 / heightDelta 20。字典序判 r1 最好，于是 r5 起一路「停滞」，
+ *      并把回退目标指向那个 51.71 的破烂结构 —— 模型越回退越差。
+ *   ③ 折中（现行）：`score = match − PENALTY × elementsMissing`，同量纲相加。
+ *      权重取 6（1 条要素 ≈ 6 分）：
+ *      · 缺 4 条换来 +12 分（92 vs 80）→ 不算进步，保住 ① 的原意（6×4=24 > 12）；
+ *      · 缺 2 条但多 38 分（89.71 vs 51.71）→ 算进步，不再把塌掉的结构当标杆（6×2=12 < 38）。
+ */
+const MISSING_PENALTY = 6
+
+/**
+ * 最好成绩的排序分：要素缺失折算成扣分，与 match 同量纲。
+ * 没有要素报告（非设计稿链路 / 未传 --spec）时就是裸 match。
+ */
+function bestScore(h) {
+  if (!h || h.match == null) return null
+  const miss = Number.isFinite(h.elementsMissing) ? h.elementsMissing : null
+  return miss == null ? h.match : h.match - MISSING_PENALTY * miss
+}
+
+/**
+ * a 是否严格优于 b（带 STALL_EPS 噪声门槛）。
+ * 只在**两边都有要素报告**时才启用扣分口径；否则退化成纯 match 比较，
+ * 避免「有 fidelity 的轮次」与「无 fidelity 的轮次」混比时被凭空扣分。
+ */
+function isBetterThan(a, b) {
+  if (!a || a.match == null) return false
+  if (!b || b.match == null) return true
+  const comparable = Number.isFinite(a.elementsMissing) && Number.isFinite(b.elementsMissing)
+  const sa = comparable ? bestScore(a) : a.match
+  const sb = comparable ? bestScore(b) : b.match
+  return sa > sb + STALL_EPS
+}
+
+/**
+ * 内容就绪门禁（S4.9）——**in-process 调用**，不再 shell 出去：
+ * 它每轮都跑（挡在 render 前），起进程的冷启成本会把「省一轮 render」的收益吃掉。
+ * readiness.mjs 是纯声明性判定，不依赖 Chrome，直接 import 最划算。
+ *
+ * 失败不阻断调用方：拿不到就返回 null，门禁退化为「无此项」而不是误判未就绪。
+ */
+function runReadiness({ cardId, schemaPath, dataPath, specPath, designPath }) {
+  if (!fs.existsSync(schemaPath)) return null
+  try {
+    return buildReadinessReport({
+      cardId,
+      schemaPath,
+      dataPath,
+      specPath: specPath || '',
+      designPath: designPath || '',
+    })
+  } catch {
+    return null
+  }
+}
+
+/** preflight.mjs = 机械化的 14 项生成前/后检查（项数以 preflight.mjs 自身输出为准）。
  *  此前它没被任何协议阶段点名，模型从来不知道它存在 —— 这里直接并进每轮迭代报告。 */
 function runPreflight({ cardId, specPath }) {
   if (!fs.existsSync(PREFLIGHT_SCRIPT)) return null
@@ -314,78 +678,501 @@ function runPreflight({ cardId, specPath }) {
   }
 }
 
+/**
+ * 把「match 差多少分」翻译成「差在哪」。
+ *
+ * 实测（2026-09-21 建卡回合）：报告只说「match 79.86、高度差 56」，从不说是哪个区域、
+ * 哪个节点差 —— 模型只能整份重写 IR 去试（另一轮实测 16 次全量重写、12.4 万字符，
+ * 约占全部输出的一半）。热区与 contributors 本来就都在报告里，缺的只是把结论说出口。
+ *
+ * 只转述报告里已有的事实，不新造推断：热区坐标来自 diffHotspots，节点来自 attributeContributors。
+ */
+function describeMatchGap(r) {
+  const pd = r.pixelDiff || {}
+  const gap = Number((GATE.match - (pd.match ?? 0)).toFixed(2))
+  const parts = []
+  const hs = (pd.hotspots || []).slice(0, 3).map((h) => `(${h.x},${h.y}) ${h.w}×${h.h}`)
+  if (hs.length) parts.push(`最大差异区 ${hs.length} 处：${hs.join(' / ')}`)
+  const nodes = []
+  for (const c of (Array.isArray(r.contributors) ? r.contributors : []).slice(0, 2)) {
+    const el = (c.elements || [])[0]
+    if (!el) continue
+    const label = el.text ? `text="${String(el.text).slice(0, 18)}"` : el.cid || el.cls || '?'
+    const dH = el.dH != null ? ` 高差 ${el.dH > 0 ? '+' : ''}${el.dH}px` : ''
+    const flags = (el.flags || []).slice(0, 2).join(' ')
+    nodes.push(`${el.cls || '?'} ${label}${dH}${flags ? ` [${flags}]` : ''}`)
+  }
+  if (nodes.length) parts.push(`最可能的节点：${nodes.join('；')}`)
+  if (pd.size && (pd.size.heightDelta || pd.size.widthDelta)) {
+    parts.push(`尺寸差 height ${pd.size.heightDelta}px / width ${pd.size.widthDelta}px（门禁要求都为 0）`)
+  }
+  const co = r.contentOffset1x
+  if (co && (co.dx || co.dy)) parts.push(`整体内容偏移 ${co.dx}/${co.dy}px（门禁要求 |dx|,|dy|<=${GATE.contentOffset1x}）`)
+  if (!parts.length) return null
+  return `还差 ${gap} 分。差在这些地方：${parts.join('；')}。一轮只改一处、且先改最内层那个节点，改完立刻重跑 iterate 拿新报告。`
+}
+
 /** 门禁判定：全部数值项来自本轮报告，任何一项不达标 passed=false。 */
-function evaluateGate(r) {
+export function evaluateGate(r) {
   const pd = r.pixelDiff || {}
   const co = r.contentOffset1x || null
-  const checks = [
+  const contentBlocked = Boolean(r.readiness && r.readiness.ready === false)
+  const checks = []
+  // 内容就绪（S4.9）放**最前**：它是所有后续判定的前提 ——
+  // 要素没齐时 match 毫无参考价值（实测 gen-1：要素不全却刷到 90.46）。
+  if (r.readiness) {
+    checks.push({
+      name: 'readiness.content',
+      value: r.readiness.ready === false ? `未就绪(${r.readiness.stage})` : 'ready',
+      required: 'ready（要素齐全 ∧ 变量绑定完备 ∧ 图片地址已配置 ∧ 切图已落盘）',
+      ok: r.readiness.ready !== false,
+    })
+  }
+  // 渲染宽度基准（S4.9 同级前置）：宽度错了 match / dy / contentOffset 全部不可信。
+  // 历史事故（gen-1）：--width 375 跑了前两轮，best 25.5% 是错基准产物，模型从未注意
+  // 报告顶层的 widthMismatch 字段 —— 升级为 gate check（structure 阶段）让它出现在 gate.failed 前列。
+  if (r.widthMismatch) {
+    checks.push({
+      name: 'render.widthMismatch',
+      value: r.widthMismatch,
+      required: '--width 与设计稿卡面宽一致',
+      ok: false,
+    })
+  }
+  checks.push(
     { name: 'validate.errors', value: r.validate?.errors ?? null, required: '=0', ok: (r.validate?.errors ?? 1) === 0 },
     { name: 'lint.errors', value: r.lint?.errors ?? null, required: '=0', ok: (r.lint?.errors ?? 1) === 0 },
-  ]
+  )
   if (r.preflight) checks.push({ name: 'preflight.errors', value: r.preflight.errors, required: '=0', ok: r.preflight.errors === 0 })
+  // 要素线（内容真值）：设计稿里的文案必须在 schema 里找得到。
+  // 放在像素检查之前 —— 要素缺失时先补要素，调像素是白费（改样式不会把丢掉的文案变回来）。
+  if (r.fidelity) {
+    checks.push({
+      name: 'elements.missing',
+      value: r.fidelity.missing.length,
+      required: '=0',
+      ok: r.fidelity.missing.length === 0,
+    })
+  }
   if (pd.match != null) checks.push({ name: 'pixelDiff.match', value: pd.match, required: `>=${GATE.match}`, ok: pd.match >= GATE.match })
+  // 几何隐形项：不做像素对比也能判死 —— 「被压成 0」「跑出卡片」用户必然看不见。
+  // 放在像素项之前（结构阶段），避免模型为了刷 match 去动已经正确的结构。
+  const geo = r.geometry
+  if (geo) {
+    checks.push({ name: 'geometry.collapsed', value: geo.counts?.collapsed ?? geo.collapsed?.length ?? 0, required: '=0', ok: (geo.counts?.collapsed ?? geo.collapsed?.length ?? 0) === 0 })
+    checks.push({ name: 'geometry.outOfCard', value: geo.counts?.outOfCard ?? geo.outOfCard?.length ?? 0, required: '=0', ok: (geo.counts?.outOfCard ?? geo.outOfCard?.length ?? 0) === 0 })
+  }
   if (pd.size) {
     checks.push({ name: 'pixelDiff.size.heightDelta', value: pd.size.heightDelta, required: `=${GATE.heightDelta}`, ok: pd.size.heightDelta === GATE.heightDelta })
     checks.push({ name: 'pixelDiff.size.widthDelta', value: pd.size.widthDelta, required: `=${GATE.widthDelta}`, ok: pd.size.widthDelta === GATE.widthDelta })
   }
   if (co) checks.push({ name: 'contentOffset1x', value: `${co.dx}/${co.dy}`, required: `|dx|,|dy|<=${GATE.contentOffset1x}`, ok: Math.abs(co.dx) <= GATE.contentOffset1x && Math.abs(co.dy) <= GATE.contentOffset1x })
   const failed = checks.filter((c) => !c.ok)
-  return {
+  // 三段式门禁（内容 → 结构 → 像素）：先让「内容就绪」达标，再谈结构，最后才谈像素。
+  // 历史事故：两段混在一起时，模型会在「为满足 lint 改结构 → match 掉下来 → 改回去」之间震荡几十步；
+  // 而更贵的一次是内容没齐就开始刷像素（gen-1：623 万 token 报废）。
+  const structureOk = !failed.some((c) => c.name !== 'pixelDiff.match' && !c.name.startsWith('pixelDiff') && c.name !== 'contentOffset1x' && c.name !== 'readiness.content')
+  const gate = {
     passed: failed.length === 0,
+    stage: failed.length === 0 ? 'pass' : contentBlocked ? 'content' : structureOk ? 'pixel' : 'structure',
     checks,
     failed: failed.map((c) => `${c.name}=${c.value}（要求 ${c.required}）`),
     verdict: failed.length === 0 ? 'PASS' : `FAIL：${failed.map((c) => `${c.name}=${c.value}`).join('，')}`,
   }
+  // 结构性缺口提示：存在整片缺失带时，把「先补结构」顶到 hint 首位 ——
+  // 局部微调线索（contributors/hotspots）在整块漏建面前全是噪音（gen-1 实测 8 轮无效微调后熔断）。
+  const gaps = r.pixelDiff?.structuralGaps || []
+  if (gaps.length && typeof r.pixelDiff?.match === 'number' && r.pixelDiff.match < GATE.match) {
+    gate.structuralHint =
+      `渲染存在 ${gaps.length} 片逐行几乎全异的连续带区（1x 卡内 y/h）：` +
+      gaps.map((g) => `y=${g.y}~${g.y + g.h}（高 ${g.h}pt，设计稿该带中心有墨比例 ${g.designInkPct}%）`).join('；') +
+      ` —— 要么整块内容漏建（图表 / 分区 / 列表段），要么背景/底色整层错涂。对照 spec_audit 的 bands[] 先修结构，` +
+      `match<${GATE.match} 且缺口仍在时忽略 contributors 的局部微调线索。`
+  }
+  // 内容未就绪：把 blockers 全文写进 verdict，并**明确写出「本轮没跑 render」** ——
+  // 不说清楚的话模型会以为「报告里没像素分 = 迭代器坏了」，转而反复重跑空转。
+  if (contentBlocked) {
+    gate.blocked = true
+    gate.blockedBy = 'readiness'
+    gate.stage = 'content'
+    gate.readiness = { ready: false, stage: r.readiness.stage, blockers: r.readiness.blockers }
+    gate.verdict =
+      `BLOCKED（内容未就绪，stage=${r.readiness.stage}）：本轮**没有 render、没有 pixelDiff，也不消耗迭代轮次**。` +
+      `阻塞项 ${r.readiness.blockers.length} 条：\n` +
+      r.readiness.blockers.map((b) => `  · ${b}`).join('\n') +
+      (r.readiness.hint ? `\n修法：${r.readiness.hint}` : '') +
+      '\n补齐内容后再跑 iterate；内容没齐时的像素分没有参考价值，刷它纯属烧轮次。'
+  } else if (r.readiness && r.readiness.checks?.slices?.unreferenced?.length) {
+    // 设计稿声明了切图但 schema 里没有同名引用 —— 只提示不拦（名字匹配不可靠，见 readiness.mjs 头部说明）
+    gate.sliceHints = r.readiness.checks.slices.unreferenced
+  }
+  if (r.fidelity && r.fidelity.missing.length) {
+    gate.verdict +=
+      `；要素缺失 ${r.fidelity.missing.length} 条（设计稿有、schema 里找不到）：${r.fidelity.missing.slice(0, 5).map((t) => `「${t}」`).join('、')}` +
+      ' —— **先补要素再调像素**：把丢掉的文案补回对应节点（或把绑定变量的 defaultValue 改成设计稿真值），补完重跑一轮再判门禁。' +
+      '注意别用占位文案顶替：schema 里出现设计稿没有的文案同样算要素错误。'
+  }
+  if (r.fidelity && r.fidelity.invented && r.fidelity.invented.length) {
+    gate.invented = r.fidelity.invented.slice(0, 10)
+  }
+  // 非文本要素缺口（图标 / 分割线）：warning 级提示，不判红 —— symbol 可走 slice 位图实现、
+  // shape 可能是背景装饰，数量对账有结构性误差（无金标校准）；但必须每轮回喂给模型自查，
+  // 否则「图标漏建 / 分割线用 Row+背景色模拟」依旧静默（2026-09-25 用户实测抱怨点）。
+  const symGap = r.fidelity?.symbols?.gap || 0
+  const divGap = r.fidelity?.shapes?.dividerGap || 0
+  if (symGap || divGap) {
+    gate.elementHints = []
+    if (symGap) gate.elementHints.push(`图标：设计稿 symbol ${r.fidelity.symbols.spec} 个 vs schema Icon ${r.fidelity.symbols.schemaIcon} 个（缺 ${symGap}）—— 逐个核对图标是否都有 Icon 组件或 slice 落点`)
+    if (divGap) gate.elementHints.push(`分割线：设计稿细长条 shape ${r.fidelity.shapes.specDividerish} 条 vs schema Divider ${r.fidelity.shapes.schemaDivider} 个（缺 ${divGap}）—— 分割线必须用 Divider 组件（R-DIVIDER），禁止 Row+背景色模拟`)
+  }
+  // 几何隐形项：把具体节点写进 verdict —— 只说「collapsed=2」等于让模型自己找是哪两个。
+  if (geo && (geo.collapsed?.length || geo.outOfCard?.length)) {
+    gate.geometry = { collapsed: geo.collapsed, outOfCard: geo.outOfCard, overWrapped: geo.overWrapped }
+    const detail = describeGeometry(geo)
+    const fix =
+      ' 修法：这些节点全在布局里，**别动视觉样式**——按 cid 找到那个节点，' +
+      '① 被压成 0 宽：说明同排有个容器把整行吃光了（横向流里的容器若不写 rect.width，渲染器按默认「100%」出），' +
+      '给那两者按设计稿补显式 rect.width（itemValueFrom:"0"）；确实要占满剩余空间就用 flexGrow:1 + flexShrink:1。' +
+      '② 跑出卡片右缘：同上，横向兄弟宽度之和超了卡片宽（卡内宽 = 卡宽 − 左右 padding），按设计稿重新分配宽度。'
+    gate.geometryDetail = detail
+    gate.verdict = `${gate.verdict}；${detail}。${fix}`
+  }
+  // 像素类不达标时补一句「差在哪」：只报分数等于把「找哪里差」整段外包给模型的猜测试错。
+  if (failed.some((c) => c.name.startsWith('pixelDiff') || c.name === 'contentOffset1x')) {
+    const gapDetail = describeMatchGap(r)
+    if (gapDetail) {
+      gate.gapDetail = gapDetail
+      gate.verdict = `${gate.verdict}；${gapDetail}`
+    }
+  }
+  // validate 没跑起来（机器上没有可用 python）⇒ 谁都修不好这一项：继续 --set 只是烧步数。
+  // 与普通 FAIL 区分开，调用方（模型）照 verdict 停手 + 告知用户，而不是接着盲调。
+  if (r.validate?.envError === true) {
+    gate.passed = false
+    gate.blockedBy = 'validate-no-python'
+    gate.envBlocked = 'validate 没跑起来：本机没有可用的 python 解释器'
+    gate.checks.push({ name: 'validate.runnable', value: 'no-python', required: '能用 python 跑 validate_schema.py', ok: false })
+    gate.verdict =
+      'BLOCKED（环境问题，不是卡片的错）：validate 没跑起来，改 schema / 继续 --set 都修不好它。' +
+      '停手，如实告诉用户「装 Python 或设 DSL_CARD_PYTHON=<解释器路径>」后重跑 iterate；' +
+      `其余检查：${failed.length ? failed.map((c) => `${c.name}=${c.value}`).join('，') : '全部达标'}`
+  }
+  return gate
 }
 
-/** 报告落盘 + 轮次历史 + 停滞检测（同热区连调多轮 = 微调已无收益，必须换证据链）。 */
-function persistReport(result, { sp, dp }) {
+/**
+ * IR 轮次快照：每次 iterate 落一份 `<id>.ir.rNN.json`，刷新最好成绩时另存 `<id>.ir.best.json`。
+ * 以前没有任何历史版本 ⇒ 发现「越改越差」时唯一的办法是凭记忆全量重写整份 IR
+ * （实测 16 次 / 12.4 万字符 ≈ 全部输出的一半）。有快照，回退才是可执行的下一步。
+ */
+function snapshotIR(cardId, irPath, round) {
+  if (!cardId || !irPath || !fs.existsSync(irPath)) return null
+  const name = `${cardId}.ir.r${String(round).padStart(2, '0')}.json`
+  try {
+    fs.copyFileSync(irPath, path.join(SCRATCH_DIR, name))
+    return { name, path: path.join(SCRATCH_DIR, name) }
+  } catch {
+    return null
+  }
+}
+
+/** 停滞提示：只给可执行的下一步（回退 → 单分项 → 换证据链），不再罗列一堆可选分析。 */
+/** 高度差停滞提示：问题在「结构撑高」而不是「像素对齐」，别让它继续调像素。 */
+function heightStalledBlock({ cardId, cur }) {
+  const hd = cur?.heightDelta
+  return [
+    `⚠ 高度差已连续 ${HEIGHT_FROZEN_ROUNDS} 轮一动不动（heightDelta=${hd}，门禁要求 0）：**问题在结构、不在像素**。`,
+    '再调 match 也过不了门禁——先把高度这 ${hd}px 定位出来（逐带 dy/dh 会指出是哪一段把总高撑出去的：通常是一处被漏掉/多出的元素，或某层 margin/padding 累加），只改那一处结构（补元素 / 删元素 / 改间距），改完立刻重跑 iterate 拿新的 heightDelta 做判据。',
+  ].join('\n')
+}
+
+function stalledHint({ cardId, roundsSinceBest, best, cur, last, regressed, gate, irRel, reason }) {
+  // gate.failed 在 evaluateGate 里**已经是格式化好的字符串数组**（`name=value（要求 X）`），
+  // 这里再按对象取 c.name/c.value 会渲染成 `undefined=undefined（要求 undefined）`——
+  // 模型读到的是乱码建议（实测 r14 报告）。直接切片拼接即可。
+  const failed = (gate?.failed || []).slice(0, 2)
+  // 结构阶段（内容未就绪 / 无像素对比）没有 match 可比，别渲染成「本轮 undefined%」。
+  const fmtScore = (v) => (Number.isFinite(v) ? `${v}%` : '（本轮无像素分）')
+  // 回退命令里的 `--ir` 必须是**本次跑的那份工作 IR**（persistReport 手里就有），不能猜路径：
+  // 模型把 IR 放哪儿由它自己决定（实测有 UI/_gen/<draft>/、.cache/ai-scratch/ 等多种落点），
+  // 猜错的结果是回退命令直接报「工作 IR 不存在」，白烧一步。
+  const irTarget = irRel || `.cache/ai-scratch/${cardId}.ir.json`
+  const lines = [
+    `已连续 ${roundsSinceBest} 轮没有刷新最好成绩：最好 ${fmtScore(best.match)} @ r${best.round}，本轮 ${fmtScore(cur.match)}${regressed && last ? `（比上轮 ${fmtScore(last.match)} 还低）` : ''}。`,
+  ]
+  // 要素下滑单独点名：这类轮次**不该**继续调像素——像素分可能是靠删要素/换占位文案换来的。
+  if (cur.elementsMissing != null && best.elementsMissing != null && cur.elementsMissing > best.elementsMissing) {
+    lines.push(
+      `⚠ 本轮的要素比最好成绩还少 ${cur.elementsMissing - best.elementsMissing} 条（最好 r${best.round} 缺 ${best.elementsMissing} 条 / 本轮缺 ${cur.elementsMissing} 条）：**这是在删要素凑像素**。先把要素补回来（设计稿有、schema 里没有的文案见报告 elements.missing / gate.verdict），再谈 match。`,
+    )
+  }
+  lines.push(
+    '--set 微调已到天花板，禁止继续盲调、禁止再全量重写 IR。按序做：',
+    `① 回退到最好结构：skill_exec script=skills/dsl-card-generator/scripts/ir_restore.mjs args=["--best",".cache/ai-scratch/${cardId}.ir.best.json","--ir","${irTarget}"] —— 回退后必须重跑一轮 iterate 拿新报告，不要拿旧报告当门禁。`,
+    failed.length
+      ? `② 只修一个分项：本轮 gate.failed 前两项是 ${failed.join(' / ')}。一轮只改一项，改完立刻重跑 iterate（同时改多项无法归因）。`
+      : '② 只修一个分项：按本轮 gate.failed 的第一项，一轮只改一项，改完立刻重跑 iterate。',
+    `③ 同一项连改两轮都不动 ⇒ 换证据链：skill_exec script=skills/dsl-card-generator/scripts/diff_bands.mjs args=["--id","${cardId}","--design","<设计稿>","--render","<本轮 renderImage>"] 拿逐带 dy/dh 与分区主色，再对照 references/generation_pitfalls.md 的「类型开关+值 / 静默丢弃」清单。`,
+  )
+  // 高度线单独触发时，先插一段「问题在结构、不在像素」的定向说明，再照常给回退与单分项建议
+  //（回退命令在两种停滞形态下都有用，不该因为换了判据就被吞掉）。
+  if (reason === 'height') lines.unshift(heightStalledBlock({ cardId, cur }))
+  return lines.join('\n')
+}
+
+/**
+ * 迭代身份：**同一张卡换设计稿整卡重做**时必须把轮次历史与最好成绩全部作废。
+ *
+ * 为什么要（2026-09-24 实机事故）：持久化只按 cardId 认，`gen-1` 先按「理财卡」设计稿
+ * 迭代到 r17（best 91.64% @ r6 / 19 条要素），用户随后把同一张卡换成「收支分析」设计稿
+ * 重做 —— 新设计的第一轮 iterate 直接被记成 r18，撞上旧设计的 best：
+ * `score = 80.15 − 6×8 缺要素` 远不如 91.64 ⇒ roundsSinceBest = 18 − 6 = 12 ≥ STALL_ROUNDS
+ * ⇒ 当场判 stalled ⇒ ai-chat 的还原度熔断随即禁用 iterate / ir_patch，模型只能收尾交一张
+ * **stage=structure、缺 8 条要素、match 80%、高差 −76px** 的卡。整轮 96 万 prompt token 报废。
+ *
+ * 判据只用设计稿绝对路径：它换新就是另一张卡的内容真值，旧历史对像素/要素两条线都没有参照意义；
+ * 同一设计稿重跑则保留历史（`ir_restore --best` 仍可用，别把回退能力一起废掉）。
+ * 显式重置用 `--reset`（换设计稿但还是想从零计时）。
+ */
+function iterationIdentity(designPath, irPath) {
+  if (designPath) {
+    try {
+      return `design:${fs.realpathSync(path.resolve(designPath))}`
+    } catch {
+      return `design:${path.resolve(designPath)}`
+    }
+  }
+  // 没给 --design（纯结构迭代）时退回 IR 自身路径，至少不会跨卡串味
+  return `ir:${irPath ? path.resolve(irPath) : ''}`
+}
+
+/** 换设计稿重置：轮次快照与 best 都指向旧设计，留着会误导 ir_restore 把另一张卡的 IR 写回来 */
+function dropStaleSnapshots(cardId) {
+  const dropped = []
+  let names = []
+  try {
+    names = fs.readdirSync(SCRATCH_DIR)
+  } catch {
+    return dropped
+  }
+  const prefix = `${cardId}.ir.`
+  for (const n of names) {
+    if (n === `${cardId}.ir.best.json` || /\.ir\.r\d+\.json$/.test(n)) {
+      if (!n.startsWith(prefix)) continue
+      try {
+        fs.unlinkSync(path.join(SCRATCH_DIR, n))
+        dropped.push(n)
+      } catch {
+        /* 删不掉不致命：报告已被清空，最多留几个孤儿文件 */
+      }
+    }
+  }
+  return dropped
+}
+
+/** 报告落盘 + 轮次历史 + 停滞检测（连续多轮没刷新最好成绩 = 微调到天花板，必须叫停并回退）。 */
+export function persistReport(result, { sp, dp, irPath, reset = false, design = '' }) {
   try {
     fs.mkdirSync(SCRATCH_DIR, { recursive: true })
     const reportPath = path.join(SCRATCH_DIR, `${result.cardId}.iterate.json`)
+    const bestIrPath = path.join(SCRATCH_DIR, `${result.cardId}.ir.best.json`)
     let prev = null
     try {
       prev = JSON.parse(fs.readFileSync(reportPath, 'utf8'))
     } catch {}
+    // 设计稿换了（或显式 --reset）⇒ 轮次历史 / best / 快照全部作废，本轮记 r1。
+    // 判据见 iterationIdentity：只按 cardId 认会让新设计第 1 轮撞上旧设计的 best 而被误判停滞。
+    const identity = iterationIdentity(design, irPath)
+    let resetReason = ''
+    if (prev) {
+      if (reset) resetReason = '显式 --reset'
+      // 旧报告（本判据上线前落的）没有 identity，无从比对 ⇒ 按「无法证明是同一设计稿」处理，
+      // 一次性重置。代价只有「丢一次回退目标」，而误判停滞的代价是整轮生成报废（见上面注释）。
+      else if (!prev.identity) resetReason = '旧报告无迭代身份（判据上线前落的），无法证明与当前设计稿同一'
+      else if (prev.identity !== identity) resetReason = `设计稿已更换（${prev.identity} → ${identity}）`
+    }
+    const droppedSnapshots = resetReason ? dropStaleSnapshots(result.cardId) : []
+    if (resetReason) prev = null
     const pd = result.pixelDiff || {}
     const hotSig = (pd.hotspots || []).slice(0, 3).map((h) => `${h.x},${h.y}`).join('|')
     const history = Array.isArray(prev?.history) ? prev.history.slice(-9) : []
     const last = history[history.length - 1]
-    let stalledRounds = 1
-    if (last && pd.match != null && last.match != null) {
-      const sameScore = Math.abs(last.match - pd.match) < 0.3
-      const sameHot = hotSig && last.hotSig === hotSig
-      if (sameScore && sameHot) stalledRounds = (prev?.stalled?.rounds || 1) + 1
+
+    /* ── 内容未就绪：**不消耗迭代轮次** ────────────────────────────────
+     * 本轮根本没跑 render，谈「第几轮迭代」没有意义；更关键的是——
+     * 若照常 push 一条 history，那么模型「改内容 → 被拦一次 → 又改 → 又被拦」会白白把
+     * 历史窗口（只留 9 条）挤满、并把 `round` 抬高，进而污染 `roundsSinceBest` 与停滞判据
+     * （实测 gen-1 的 r12/r13 就是这种「什么都没变却各占一轮」的幽灵轮次）。
+     * 所以这里只刷新 gate / blockedAt，history 与 best 原样保留，不写 IR 快照。 */
+    if (result.readiness && result.readiness.ready === false) {
+      const blockedReport = {
+        ...result,
+        elements: undefined,
+        identity,
+        schemaHash: hashFile(sp),
+        dataHash: hashFile(dp),
+        history,
+        best: prev?.best,
+        round: history.length,
+        stalled: undefined,
+        blockedAt: {
+          ts: Date.now(),
+          stage: result.readiness.stage,
+          blockers: result.readiness.blockers,
+          hint: result.readiness.hint || null,
+        },
+      }
+      blockedReport.gate = evaluateGate(blockedReport)
+      blockedReport.conclusion = 'blocked-content'
+      fs.writeFileSync(reportPath, JSON.stringify(blockedReport, null, 2) + '\n')
+      return {
+        reportPath,
+        stalled: null,
+        gate: blockedReport.gate,
+        conclusion: 'blocked-content',
+        rounds: history.length,
+        blocked: true,
+      }
     }
-    history.push({
+
+    const round = (last?.round || history.length) + 1
+    const snapshot = snapshotIR(result.cardId, irPath, round)
+    // 历史最好成绩（不含本轮）：停滞判据的基准。
+    // 必须读上一份报告里**单独持久化**的 best —— history 只留最近 9 条，
+    // 最好成绩一旦被窗口挤出（实测 r10 的最好成绩到 r20 就没了），判据就会误判成「刚刷新过」。
+    const prevBest = prev?.best && Number.isFinite(prev.best.match) ? prev.best : null
+    // 注意：这里必须用 bestScore（= match − 6×缺要素）而不是裸 match，否则
+    // 「基准」与下面 isBetterThan 的口径不一致 —— 实测会出现「基准选了个 51.71 的塌陷轮次，
+    // 然后拿它当回退目标」的错位。
+    const bestBefore = [prevBest, ...history]
+      .filter((h) => h && h.match != null)
+      .reduce((a, h) => (a == null || bestScore(h) > bestScore(a) ? h : a), null)
+    // 要素线（内容真值）：设计稿的文案是固定要素，迭代只许改样式布局。
+    // 记进每轮历史，才能看出「越改越少节点/要素」这种下滑（用户实测反馈的形态）。
+    const fid = result.fidelity || null
+    const cur = {
       ts: Date.now(),
+      round,
       match: pd.match ?? null,
+      elementsTotal: fid?.total ?? null,
+      elementsMatched: fid?.matched ?? null,
+      elementsMissing: Array.isArray(fid?.missing) ? fid.missing.length : null,
+      elementsInvented: Array.isArray(fid?.invented) ? fid.invented.length : null,
       heightDelta: pd.size?.heightDelta ?? null,
       contentOffset1x: result.contentOffset1x || null,
       lintErrors: result.lint?.errors ?? null,
       validateErrors: result.validate?.errors ?? null,
       hotSig,
       sets: (result.appliedSets || []).map((a) => a.path),
-    })
+      irSnapshot: snapshot?.name || null,
+    }
+    history.push(cur)
+    // 最好成绩的判据：`score = match − 6×缺要素`（同量纲，见 MISSING_PENALTY 注释）。
+    // 为什么不纯比 match：要素是设计稿给定的真值，把真值换成占位文案（或删掉节点）会让 match 反而升——
+    // 实测 2026-09-21 demo 回合「产品名/利率/期限整批换成自编占位值」后像素照样 89%。
+    // 为什么不字典序优先要素：同一回合的 r1（要素齐 / 51.71 / 高差 800）会被判成优于
+    // r4（缺 2 条 / 89.71 / 高差 20），回退目标直接指向塌掉的结构。
+    const improved = bestBefore != null && isBetterThan(cur, bestBefore)
+    const best = bestBefore == null || improved ? cur : bestBefore
+    if (best === cur && irPath && fs.existsSync(irPath)) {
+      try {
+        fs.copyFileSync(irPath, bestIrPath)
+      } catch {}
+    }
+    const roundsSinceBest = best?.round ? round - best.round : 0
+    const regressed = Boolean(last && cur.match != null && last.match != null && cur.match < last.match - REGRESS_DELTA)
+    const stalledByMatch = cur.match != null && best?.match != null && roundsSinceBest >= STALL_ROUNDS
+    // 高度线：连续 HEIGHT_FROZEN_ROUNDS 轮 heightDelta 一模一样且不为 0。
+    // 只在门禁确实卡在高度上时才升格为停滞（heightDelta 已经在别的轮次里动过就不算）。
+    const heightSeq = history.map((h) => h.heightDelta).filter((v) => v != null)
+    const heightFrozen =
+      heightSeq.length >= HEIGHT_FROZEN_ROUNDS &&
+      Math.abs(heightSeq[heightSeq.length - 1]) >= HEIGHT_FROZEN_MIN_PX &&
+      heightSeq.slice(-HEIGHT_FROZEN_ROUNDS).every((v) => v === heightSeq[heightSeq.length - 1])
+    // 两条线各自独立触发：match 不刷新最好成绩，或高度差显著地冻住不动。
+    // 后者单独判停是因为门禁要求 heightDelta=0 —— 高度冻着不动时，再调像素也永远过不了。
+    const stalledBy = stalledByMatch ? 'match' : heightFrozen ? 'height' : null
+    const stalled = Boolean(stalledBy)
     const persisted = {
       ...result,
       elements: undefined,
+      // 迭代身份：下一轮据此判「还是同一张内容真值吗」，换了就重置（见 iterationIdentity）
+      identity,
       schemaHash: hashFile(sp),
       dataHash: hashFile(dp),
       history,
-      stalled: stalledRounds >= 2 ? { rounds: stalledRounds } : undefined,
+      best: best
+        ? {
+            match: best.match,
+            // 排序分一起落盘：下一轮据此比「谁才是真正的最好成绩」，与 isBetterThan 同口径
+            score: bestScore(best),
+            round: best.round,
+            // 要素线一起落盘：下一轮据此判「这轮是不是靠丢要素换的像素分」
+            elementsMissing: best.elementsMissing ?? null,
+            elementsMatched: best.elementsMatched ?? null,
+            irSnapshot: best.irSnapshot || null,
+            ts: best.ts || null,
+          }
+        : undefined,
+      stalled: undefined,
     }
     persisted.gate = evaluateGate(persisted)
+    if (stalled) {
+      persisted.stalled = {
+        reason: stalledBy,
+        rounds: roundsSinceBest,
+        best: best
+          ? { match: best.match, round: best.round, elementsMissing: best.elementsMissing ?? null, irSnapshot: best.irSnapshot }
+          : null,
+        regressed,
+        bestIr: fs.existsSync(bestIrPath) ? bestIrPath : null,
+        hint: stalledHint({
+          cardId: result.cardId,
+          roundsSinceBest,
+          best,
+          cur,
+          last,
+          regressed,
+          gate: persisted.gate,
+          irRel: irPath ? path.relative(repoRoot, path.resolve(irPath)) : '',
+          reason: stalledBy,
+        }),
+      }
+    }
+    // 显式落结论：一张卡目前处于哪种状态，必须一眼可读。
+    // 旧版只有 gate.passed 一个布尔——「没过但也没判停滞」时，模型可以直接停手、界面上
+    // 却看不出这卡是「还在迭代」还是「被放弃了」（实测 2 轮后无声转向下一张卡）。
+    persisted.conclusion = persisted.gate.passed ? 'pass' : stalledBy ? 'stalled' : 'iterating'
     fs.writeFileSync(reportPath, JSON.stringify(persisted, null, 2) + '\n')
-    return { reportPath, stalled: persisted.stalled, gate: persisted.gate, rounds: history.length }
+    // 轮次快照只留最近 12 轮 + best：这是个「每轮一份 IR 全文」的目录，长任务下会无限堆积
+    const pruned = pruneSnapshots(result.cardId)
+    return {
+      reportPath,
+      stalled: persisted.stalled,
+      gate: persisted.gate,
+      conclusion: persisted.conclusion,
+      rounds: history.length,
+      pruned,
+      // 重置必须显式回喂：模型看到「r1」才知道前面的历史已作废，否则会拿旧报告里的
+      // match / best 当参照继续谈收敛。
+      iterationReset: resetReason
+        ? { reason: resetReason, droppedSnapshots: droppedSnapshots.length, round: persisted.history?.[0]?.round ?? 1 }
+        : undefined,
+    }
   } catch {
     return null
   }
 }
 
 /* ── 核心管线 ──────────────────────────────────────────────── */
-async function runPipeline({ ir: irPath, out: outDir, design: designPath, width, session, alwaysDiffImage, withElements, sets, specPath, skipPreflight, slicesDir: slicesDirArg }) {
+async function runPipeline({ ir: irPath, out: outDir, design: designPath, width, session, alwaysDiffImage, withElements, sets, specPath, skipPreflight, slicesDir: slicesDirArg, reset: resetFlag, noReadiness: noReadinessArg }) {
   const t0 = performance.now()
+  /** 内容就绪门禁开关：--no-readiness 或环境变量（debug 用逃生门） */
+  const noReadiness = Boolean(noReadinessArg) || process.env.DSL_CARD_SKIP_READINESS === '1'
+
+  // 设计稿侧元素（供 contributors 的 designH/deltaH）：只有给了 --spec 才可用。
+  // 拿不到就不给 deltaH —— 宁缺勿滥，编不出可证伪的数字比没有数字更坏。
+  const designSide = loadDesignElements(specPath, designPath)
 
   // 1. Read IR（可选 --set 编辑，原子写回）→ expand
   let ir
@@ -434,17 +1221,71 @@ async function runPipeline({ ir: irPath, out: outDir, design: designPath, width,
     const errs = Array.isArray(v.errors) ? v.errors : []
     const warns = Array.isArray(v.warnings) ? v.warnings : []
     validateReport = { ok: !!v.ok, errors: errs.length, warnings: warns.length, details: errs.slice(0, 5) }
+    // 没找到可用 python ⇒ validate 根本没跑。带着 envError 进报告，门禁据此判「环境阻塞」，
+    // 不让模型把「装 Python 才能解决的事」当成「再调几轮就能过」的门禁缺口。
+    if (v.envError) validateReport.envError = true
   } catch (e) {
     validateReport = { ok: false, errors: 1, warnings: 0, details: [`validate 执行异常: ${e.message || e}`] }
   }
 
+  // 3.9 ★ 内容就绪门禁（S4.9）——**挡在最贵的 render + pixelDiff 之前**。
+  //
+  // 2026-09-24 gen-1 事故（用户原话）：「只有在确保内容和要素的齐全和准备再做像素自循环，
+  // 不然跟个傻逼一样浪费时间在像素循环里打转。这次卡片连基本的切图引入跑了半天都没为我添加上去」。
+  // 实测：两个回合 623 万 prompt token 全废；iterate 历史 r4–r13 十轮 match 卡在 87–90.46，
+  // `gate.stage` 全程 = 'pixel'（结构早过了），而 Image 的图片地址因属性键写成 `image`
+  // 被运行时静默丢弃、渲染成破图 —— **要素不全却已经在刷像素**。
+  //
+  // 门禁项 A 组件契约 / B 要素齐全 / C 变量绑定完备 / D 图片地址已配置 / E 切图路径已配置，
+  // 全是**声明性判定**（不渲染即可判），所以放在这里：不合格就直接 return，
+  // 一轮 render(≈486ms Chrome) + pixelDiff(全量 84 万像素) + 归因全部省掉。
+  //
+  // 判据选型（全仓 75 张卡实测）：71/75 ready，4 条未就绪**全是真实的 r31c 悬空引用**，0 误报。
+  const readiness = noReadiness ? null : runReadiness({ cardId, schemaPath: sp, dataPath: dp, specPath, designPath })
+  if (readiness && readiness.ready === false) {
+    const gateBlocked = evaluateGate({ validate: validateReport, lint: { errors: lintErrors.length }, readiness })
+    const result = {
+      ok: true,
+      cardId,
+      blocked: 'content',
+      readiness: { ready: false, stage: readiness.stage, blockers: readiness.blockers, hint: readiness.hint, checks: readiness.checks },
+      validate: validateReport,
+      lint: { errors: lintErrors.length, warnings: lintWarns.length, infos: lintInfos.length },
+      gate: gateBlocked,
+      conclusion: 'blocked-content',
+      readinessNote:
+        '内容未就绪 ⇒ 本轮**没有** render、**没有** pixelDiff、**不消耗迭代轮次**（不写快照、不进 history）。' +
+        '先按 blockers 把内容补齐（要素 / 变量绑定 / 图片地址 / 切图落盘），补完再跑 iterate。' +
+        '这一步的存在意义就是：内容没齐时像素分毫无参考价值，刷它纯属烧轮次。',
+      elapsedMs: Math.round(performance.now() - t0),
+    }
+    const saved = persistReport(result, { sp, dp, irPath, reset: resetFlag, design: designPath })
+    if (saved) {
+      result.report = saved.reportPath
+      result.rounds = saved.rounds
+      result.gate = saved.gate
+      result.conclusion = saved.conclusion
+    }
+    return result
+  }
+
   // 4. Render (reuse session if provided, else cold start)
-  const renderWidth = width || Number(schema.view?.width) || DEFAULT_WIDTH
+  // 宽度优先级：显式 --width > 设计稿卡面宽（spec 是 1x，卡面如 343）> schema.view.width > 默认。
+  // 实测事故：第 44 次调用用了默认 375 跑完一轮，第 46 次才改成 343（设计稿 686 = 343×2）—— 白烧一轮。
+  const renderWidth = width || (designSide?.width ? designSide.width : 0) || Number(schema.view?.width) || DEFAULT_WIDTH
+  // 显式宽度与设计稿卡面不符时响亮告警：宽度决定像素对比基准，错了 match 会被整体压低、且逐带 dy 全歪
+  const widthMismatch =
+    width && designSide?.width && Math.abs(width - designSide.width) > 1
+      ? `--width ${width} 与设计稿卡面宽 ${designSide.width} 不一致（设计稿坐标是 1x）：请改 --width ${designSide.width}，否则像素对比基准不对、match 与 dy 都不可信。`
+      : null
+  // 归因需要逐元素度量：有设计稿时默认抓（一次 Runtime.evaluate，几十毫秒），
+  // 相比「没有归因 ⇒ 模型整份重写 IR」的代价可以忽略
+  const captureElements = !!withElements || !!designPath
   let renderRes
   if (session) {
-    renderRes = await session.render({ id: cardId, width: renderWidth, format: 'png', hotReload: true, captureElements: !!withElements })
+    renderRes = await session.render({ id: cardId, width: renderWidth, format: 'png', hotReload: true, captureElements })
   } else {
-    renderRes = await renderCardScreenshot({ id: cardId, width: renderWidth, format: 'png', captureElements: !!withElements })
+    renderRes = await renderCardScreenshot({ id: cardId, width: renderWidth, format: 'png', captureElements })
   }
 
   if (renderRes.error) {
@@ -474,6 +1315,8 @@ async function runPipeline({ ir: irPath, out: outDir, design: designPath, width,
       const designPng = PNG.sync.read(designBuf)
       const scale = renderWidth ? renderPng.width / renderWidth : 2
       pixelDiffResult.hotspots = diffHotspots(renderPng, designPng, { scale })
+      // 结构性缺口：整块漏建的区域（高度差的主要实体）。放在报告里供 gate hint 引用。
+      try { pixelDiffResult.structuralGaps = detectStructuralGaps(renderPng, designPng, { scale }) } catch {}
     } catch {}
     if (true) {
       const composed = composeSideBySide(designBuf, renderBuf)
@@ -494,9 +1337,56 @@ async function runPipeline({ ir: irPath, out: outDir, design: designPath, width,
 
   const elapsed = Math.round(performance.now() - t0)
 
-  // 5.5 preflight（quickref Pre-flight Checklist 的机械化 10 条）并入本轮报告
+  // 5.5 preflight（机械化的 14 项）并入本轮报告
   const preflight = skipPreflight ? null : runPreflight({ cardId, specPath })
 
+  // 5.6 要素清单（内容真值）—— 只查得到就进报告，并作为**机器门禁的一项**（elements.missing=0）。
+  //
+  // 为什么必须进链路：实测（2026-09-21 demo 建卡回合）模型把设计稿的产品名 / 利率 / 期限
+  // 全换成自己编的占位值（「理财优选1号 / 2.45 / 每日申购」），像素照样刷到 89%、
+  // validate/lint 全绿，而卡片的内容真值**整批丢失**，直到人工比对设计稿才发现。
+  // 根因是门禁只有「结构 + 像素」两维，没有「要素是否还在」这一维：
+  // 设计稿的要素是固定真值，迭代只许改样式与布局 —— 丢了要素，再高的 match 也是错的。
+  const fidelityReport = loadFidelityReport({ specPath, schemaPath: sp, designPath, cardId })
+
+  // 内容偏移折算到 1x 设计像素 + 对齐提示（先算好，contributors 的 hint 要用它）
+  let contentOffset1x = null
+  let contentOffsetHint = null
+  if (pixelDiffResult?.contentOffset) {
+    const scale = renderWidth ? (renderRes.width || renderWidth) / renderWidth : 2
+    const co = pixelDiffResult.contentOffset
+    contentOffset1x = {
+      dx: Math.round(co.dx / (scale || 1)),
+      dy: Math.round(co.dy / (scale || 1)),
+    }
+    const { dx, dy } = contentOffset1x
+    if (Math.abs(dx) > GATE.contentOffset1x || Math.abs(dy) > GATE.contentOffset1x) {
+      contentOffsetHint = `内容整体偏移 dx=${dx} dy=${dy}（1x 设计像素，渲染相对设计）——这是对齐问题不是间距微调问题：先查 Root/首层容器的左右与上下 padding、首个子节点的 margin、以及是否漏了 marginType/paddingType:"1"；继续逐行调 gap/padding 不会收敛。`
+    }
+  }
+
+  // 分项归因：把热区落到具体节点。这是「门禁说差多少」之外唯一能让模型不盲改的东西
+  const contributors = attributeContributors({
+    hotspots: pixelDiffResult?.hotspots,
+    elements: renderRes.elementBoxes,
+    design: designSide,
+    contentOffset1x,
+  })
+
+  // 5.7 纯几何审计（隐形/出卡/折行）——「模型看不见渲染图」的机器替代品。
+  //
+  // 背景（2026-09-21）：card_screenshot 只给人看、不进模型上下文，模型可观测输入只有
+  // match/heightDelta/bands 三个数字，于是 Row 内横向容器默认 100% 吃掉整行这类
+  // 「几何上确凿、像素上模糊」的缺陷被拖了 30 分钟。这三条判定不需要看图：
+  // 被压成 0 尺寸、跑出卡片右缘、文本被折成一堆行，全是 getBoundingClientRect 的事实。
+  const geometry = renderRes.elementBoxes
+    ? auditGeometry({
+      elements: renderRes.elementBoxes,
+      degenerate: renderRes.elementBoxesDegenerate,
+      cardWidth: renderRes.width,
+    })
+    : null
+
   const result = {
     ok: true,
     cardId,
@@ -524,34 +1414,59 @@ async function runPipeline({ ir: irPath, out: outDir, design: designPath, width,
       : undefined,
     designImage,
     preflight: preflight || undefined,
+    fidelity: fidelityReport || undefined,
+    // 内容就绪结论带进每轮报告：模型不必再单独跑一次 readiness 才知道内容层状态
+    readiness: readiness
+      ? {
+          ready: readiness.ready,
+          stage: readiness.stage,
+          blockers: readiness.blockers,
+          // 声明了切图但 schema 里没有同名引用：只提示不拦（名字匹配不可靠，见 readiness.mjs 头部）
+          unreferencedSlices: readiness.checks?.slices?.unreferenced || [],
+        }
+      : undefined,
+    // 尺寸口径警告：宽度不对时下面所有像素指标都不可信，必须最先修
+    widthMismatch: widthMismatch || undefined,
+    // 结构性缺口：逐行几乎全异的连续带区 —— 整块漏建 / 背景错涂的第一信号。
+    // 存在它时先修结构，跟着 contributors 调 padding/lineHeight 是在 80% 缺失面前做 1% 微调（gen-1 实测烧 8 轮）。
+    structuralGaps: pixelDiffResult?.structuralGaps?.length
+      ? {
+        bands: pixelDiffResult.structuralGaps,
+        note: '检测到「逐行差异率 ≥85%」的连续带区（1x 卡内坐标，按高度降序）：该带要么整块内容漏建（图表 / 卡片分区 / 列表段），要么背景/底色整层错涂。对照 spec_audit 的 bands[] 找到该带区对应的元素群，先把它建出来或改对背景再谈别的；match<40 时 contributors/hotspots 的局部微调线索可以全部忽略。',
+      }
+      : undefined,
+    contentOffset1x: contentOffset1x || undefined,
+    contentOffsetHint: contentOffsetHint || undefined,
+    // 分项归因：每个热区给出「最可能的节点 + 它自己实测的 h / 同类中位 / 设计稿高度」
+    contributors: contributors || undefined,
+    // 纯几何隐形节点清单：不依赖看图，直接列出「用户看不见的东西」及其成因
+    geometry: geometry || undefined,
+    geometryNote: geometry
+      ? 'geometry 是本轮渲染的纯几何审计（round1 使用 1x 设计像素）：collapsed = 被压成零尺寸、outOfCard = 跑出卡片被裁、overWrapped = 文本折行数异常。**门禁只把 collapsed / outOfCard 当 ERROR**（这两类用户必然看不见）；逐条按 cid 去 schema 里改那一处布局，别整份重写。'
+      : undefined,
+    contributorsNote: contributors
+      ? 'contributors 按热区给出最可能出问题的**具体节点**（cid/cls/text）：先改最内层那个节点的 padding/lineHeight，一轮只改一项；flags 里 vs-siblings = 与该类元素中位高度不同，vs-design = 与设计稿高度不同，text-clipped = 文本被裁剪。'
+      : undefined,
     ...(withElements ? { elements: renderRes.elementBoxes || [] } : {}),
     elapsedMs: elapsed,
   }
 
-  // 内容偏移折算到 1x 设计像素 + 对齐提示
-  if (pixelDiffResult?.contentOffset) {
-    const scale = renderWidth ? (renderRes.width || renderWidth) / renderWidth : 2
-    const co = pixelDiffResult.contentOffset
-    result.contentOffset1x = {
-      dx: Math.round(co.dx / (scale || 1)),
-      dy: Math.round(co.dy / (scale || 1)),
-    }
-    const { dx, dy } = result.contentOffset1x
-    if (Math.abs(dx) > GATE.contentOffset1x || Math.abs(dy) > GATE.contentOffset1x) {
-      result.contentOffsetHint = `内容整体偏移 dx=${dx} dy=${dy}（1x 设计像素，渲染相对设计）——这是对齐问题不是间距微调问题：先查 Root/首层容器的左右与上下 padding、首个子节点的 margin、以及是否漏了 marginType/paddingType:"1"；继续逐行调 gap/padding 不会收敛。`
-    }
-  }
-
   // 报告落盘 + 门禁判定 + 停滞检测
-  const saved = persistReport(result, { sp, dp })
+  const saved = persistReport(result, { sp, dp, irPath, reset: resetFlag, design: designPath })
   if (saved) {
     result.report = saved.reportPath
     result.rounds = saved.rounds
     result.gate = saved.gate
+    // 换设计稿 / --reset 触发的重置必须显式回喂模型：否则它会拿旧报告里的 match/best 当参照
+    if (saved.iterationReset) result.iterationReset = saved.iterationReset
+    // 显式结论一路带到工具输出：模型与用户都能一眼看出这卡是 pass / stalled / 还在 iterating，
+    // 而不是只拿到一个 passed:false 的布尔（旧版因此出现「2 轮后无声转向下一张卡」）。
+    result.conclusion = saved.conclusion
     if (saved.stalled) {
+      // hint 由 persistReport 生成（那里才有历史与 bestIr 路径），这里只按设计稿路径补全 diff_bands 命令
       result.stalled = {
-        rounds: saved.stalled.rounds,
-        hint: `连续 ${saved.stalled.rounds} 轮 match 与热区几乎没变：--set 微调已无收益，禁止继续盲调。改按证据推进——① 跑 diff_bands.mjs（args=["--id","${cardId}","--design","${designPath || '<设计稿>'}","--render","${renderImagePath || '<renderImage>'}"]）拿逐带 dy/dh、内容底边、分区主色；② 对照 references/generation_pitfalls.md 的「类型开关+值」「静默丢弃」清单排查样式被忽略（marginType/paddingType/backgroundType/isBorder/isShadow）；③ 读报告里的 contentOffset1x 与 hotspots 判断是整体平移还是局部差异；④ 有 --spec 时看 preflight.details。`,
+        ...saved.stalled,
+        hint: String(saved.stalled.hint || '').replaceAll('<设计稿>', designPath || '<设计稿>').replaceAll('<本轮 renderImage>', renderImagePath || '<renderImage>'),
       }
     }
   }
@@ -561,7 +1476,7 @@ async function runPipeline({ ir: irPath, out: outDir, design: designPath, width,
 
 /* ── CLI ───────────────────────────────────────────────────── */
 function parseArgs(argv) {
-  const out = { ir: '', out: '', design: '', width: 0, keepAlive: false, diffImage: false, elements: false, sets: [], spec: '', gate: false, id: '', skipPreflight: false, slicesDir: '' }
+  const out = { ir: '', out: '', design: '', width: 0, keepAlive: false, diffImage: false, elements: false, sets: [], spec: '', gate: false, id: '', skipPreflight: false, slicesDir: '', reset: false, noReadiness: false }
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
     if (a === '--ir') out.ir = argv[++i] || ''
@@ -574,19 +1489,32 @@ function parseArgs(argv) {
     else if (a === '--id') out.id = argv[++i] || ''
     else if (a === '--gate') out.gate = true
     else if (a === '--no-preflight') out.skipPreflight = true
+    // 逃生门：跳过 S4.9 内容就绪门禁（debug 用；正常流程**不该**用它）
+    else if (a === '--no-readiness') out.noReadiness = true
     else if (a === '--keep-alive') out.keepAlive = true
     else if (a === '--diff-image') out.diffImage = true
     else if (a === '--elements') out.elements = true
+    // 换设计稿时轮次历史/best 会自动作废（见 iterationIdentity）；--reset 用于「设计稿没换但要从零计时」
+    else if (a === '--reset') out.reset = true
     else if (a === '-h' || a === '--help') {
       console.log(`Usage: node iterate.mjs --ir <IR.json> --out <cardDir> [--design <design.png>] [--width 343] [--elements]
                           [--spec <spec.json>]（跑 preflight 元素清单比对） [--no-preflight] [--slices-dir <要素包 slices 目录>]
                           [--set 'children.0.s.margin.marginTop="7"']（可重复；点路径数字段=数组下标；原子写回 IR）
-       node iterate.mjs --gate --out <cardDir>（或 --id <cardId>）：读最近一轮落盘报告做机器门禁判定，未达标 exit 1
+       node iterate.mjs --gate --out <cardDir>（或 --id <cardId>）：读最近一轮落盘报告做机器门禁判定，未达标 exit 2（gate-fail，不是脚本报错）
        node iterate.mjs --keep-alive  (stdin JSON lines → stdout JSON lines)
 
-门禁（--gate / 报告里的 gate 字段）：validate.errors=0 ∧ lint.errors=0 ∧ preflight.errors=0 ∧ match>=${GATE.match}
-  ∧ heightDelta=${GATE.heightDelta} ∧ widthDelta=${GATE.widthDelta} ∧ |contentOffset1x|<=${GATE.contentOffset1x}，且 schema 未在报告之后被改过。
-报告落盘：.cache/ai-scratch/<cardId>.iterate.json（含 gate / history / stalled）。`)
+阶段（gate.stage）：content → structure → pixel → pass，**逐段推进**。
+  · content  内容未就绪（S4.9）：要素 / 变量绑定 / 图片地址 / 切图落盘 有缺 ⇒ **跳过 render 与 pixelDiff、
+             不消耗迭代轮次**，按 gate.verdict 里的 blockers 补齐内容再来。跳过用 --no-readiness（或环境变量
+             DSL_CARD_SKIP_READINESS=1），正常流程不该用。
+  · structure validate/lint/preflight/geometry/要素线不达标 —— 先改结构，别碰像素。
+  · pixel    结构全过，只差 match / 尺寸 / 整体偏移。
+
+门禁（--gate / 报告里的 gate 字段）：readiness=ready ∧ validate.errors=0 ∧ lint.errors=0 ∧ preflight.errors=0
+  ∧ elements.missing=0 ∧ match>=${GATE.match} ∧ heightDelta=${GATE.heightDelta} ∧ widthDelta=${GATE.widthDelta}
+  ∧ |contentOffset1x|<=${GATE.contentOffset1x} ∧ geometry.collapsed=0 ∧ geometry.outOfCard=0，
+  且 schema 未在报告之后被改过。
+报告落盘：.cache/ai-scratch/<cardId>.iterate.json（含 gate / history / stalled / geometry / blockedAt）。`)
       process.exit(0)
     }
   }
@@ -620,9 +1548,31 @@ function runGateMode({ id, out: outDir }) {
     gate.verdict = `FAIL：报告已过期（schema.json 在报告之后被改过：${report.schemaHash} → ${schemaHash}）—— 重跑一轮 iterate.mjs 再判门禁`
     gate.checks.push({ name: 'reportFreshness', value: 'stale', required: 'schema 未变更', ok: false })
   }
+  // 显式结论：pass / stalled / blocked-content / iterating。四者之外不允许「无声退出」——
+  // 实测建卡回合里模型跑完 2 轮就直接转去做下一张卡，卡在「既没过门禁、也没判停滞」的
+  // 中间态，界面上完全看不出这卡是被放弃了还是还在迭代。
+  const blockedContent = Boolean(report.blockedAt) || report.conclusion === 'blocked-content'
+  const conclusion = gate.passed ? 'pass' : blockedContent ? 'blocked-content' : report.stalled ? 'stalled' : 'iterating'
+  if (blockedContent) {
+    gate.blocked = true
+    gate.stage = 'content'
+    gate.verdict =
+      `BLOCKED（内容未就绪，stage=${report.blockedAt?.stage || '?'}）：本轮没跑 render / 没跑 pixelDiff，也没消耗迭代轮次。\n` +
+      (report.blockedAt?.blockers || []).map((b) => `  · ${b}`).join('\n') +
+      (report.blockedAt?.hint ? `\n修法：${report.blockedAt.hint}` : '')
+  } else if (conclusion === 'iterating') {
+    gate.verdict +=
+      '；结论=iterating：既未过门禁、也未判停滞 —— 不允许无声退出。' +
+      '要么继续 iterate（一轮只改一项，拿到新报告再判），要么在正文里显式写明放弃理由（例：设计稿本身自相矛盾 / 缺关键切图）再停手。'
+  }
   const out = {
     ok: gate.passed,
     cardId,
+    conclusion,
+    blockedAt: report.blockedAt || null,
+    stalled: report.stalled
+      ? { reason: report.stalled.reason || 'match', rounds: report.stalled.rounds, hint: report.stalled.hint }
+      : null,
     report: reportPath,
     gate,
     summary: {
@@ -631,6 +1581,7 @@ function runGateMode({ id, out: outDir }) {
       widthDelta: report.pixelDiff?.size?.widthDelta ?? null,
       contentOffset1x: report.contentOffset1x || null,
       validateErrors: report.validate?.errors ?? null,
+      envBlocked: report.validate?.envError === true ? true : undefined,
       lintErrors: report.lint?.errors ?? null,
       preflightErrors: report.preflight?.errors ?? null,
       rounds: (report.history || []).length,
@@ -638,7 +1589,10 @@ function runGateMode({ id, out: outDir }) {
     },
   }
   console.log(JSON.stringify(out, null, 2))
-  process.exit(gate.passed ? 0 : 1)
+  // 门禁未达标 = 正常诊断结果（gate-fail），不是「脚本报错收尾」。
+  // 必须与 exit 1 分开：服务端按 exit 语义记账，exit 1 会被记成「连续失败」并触发短路
+  // （实测 2026-09-21 demo 建卡回合：--gate 被误判失败 1 次，模型因此被误导去改别的地方）。
+  process.exit(gate.passed ? 0 : 2)
 }
 
 async function main() {
@@ -658,7 +1612,7 @@ async function main() {
         if (!text) continue
         try {
           const req = JSON.parse(text)
-          const result = await runPipeline({ ...req, specPath: req.spec || req.specPath, session, alwaysDiffImage: req.diffImage || req.alwaysDiffImage, withElements: req.elements })
+          const result = await runPipeline({ ...req, specPath: req.spec || req.specPath, session, alwaysDiffImage: req.diffImage || req.alwaysDiffImage, withElements: req.elements, noReadiness: req.noReadiness || req.skipReadiness })
           console.log(JSON.stringify(result))
         } catch (e) {
           console.log(JSON.stringify({ ok: false, error: 'request-failed', message: e.message }))
@@ -686,6 +1640,8 @@ async function main() {
     specPath: args.spec,
     skipPreflight: args.skipPreflight,
     slicesDir: args.slicesDir,
+    reset: args.reset,
+    noReadiness: args.noReadiness,
   })
 
   console.log(JSON.stringify(result, null, 2))
@@ -694,7 +1650,12 @@ async function main() {
   if (result.gate && result.gate.passed === false) process.exitCode = 2
 }
 
-main().catch((e) => {
-  console.error(`iterate.mjs 未预期错误: ${e.message || e}`)
-  process.exit(1)
-})
+// 仅当作为 CLI 直接运行时才启动 main()（被 import 时不执行：停滞判据可离线重放验证）
+const _thisScript = fs.realpathSync(fileURLToPath(import.meta.url))
+const _invokedAs = process.argv[1] && fs.existsSync(process.argv[1]) ? fs.realpathSync(process.argv[1]) : process.argv[1]
+if (_invokedAs === _thisScript) {
+  main().catch((e) => {
+    console.error(`iterate.mjs 未预期错误: ${e.message || e}`)
+    process.exit(1)
+  })
+}