cardbuddy 0.14.2 → 0.15.0

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

@@ -36,10 +36,13 @@ 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 { createRenderSession, renderCardScreenshot } from './render_card.mjs'
 import { copyCardDesignImage } from './lib/design_image.mjs'
 import { cardsDir, cardSchemaPath, cardDataPath, readJson, repoRoot } from './lib/paths.mjs'
@@ -227,6 +230,210 @@ function diffHotspots(renderPng, designPng, { cols = 4, rows = 8, floorPct = 3,
   return cells.slice(0, maxCells)
 }
 
+/* ── 分项归因（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
+    const r = buildFidelityReport({ spec: specPath, schema: schemaPath, card: idx + 1 })
+    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,
+    }
+  } 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,6 +498,72 @@ function hashFile(p) {
   }
 }
 
+/**
+ * 停滞判据（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
+}
+
 /** preflight.mjs = quickref「Pre-flight Checklist」12 条里可机械化的 10 条。
  *  此前它没被任何协议阶段点名，模型从来不知道它存在 —— 这里直接并进每轮迭代报告。 */
 function runPreflight({ cardId, specPath }) {
@@ -314,8 +587,42 @@ 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 = [
@@ -323,26 +630,145 @@ function evaluateGate(r) {
     { 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 掉下来 → 改回去」之间震荡几十步。
+  const structureOk = !failed.some((c) => c.name !== 'pixelDiff.match' && !c.name.startsWith('pixelDiff') && c.name !== 'contentOffset1x')
+  const gate = {
     passed: failed.length === 0,
+    stage: failed.length === 0 ? 'pass' : 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('，')}`,
   }
+  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)
+  }
+  // 几何隐形项：把具体节点写进 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 }) {
+  const failed = (gate?.failed || []).slice(0, 2).map((c) => `${c.name}=${c.value}（要求 ${c.required}）`)
+  // 回退命令里的 `--ir` 必须是**本次跑的那份工作 IR**（persistReport 手里就有），不能猜路径：
+  // 模型把 IR 放哪儿由它自己决定（实测有 UI/_gen/<draft>/、.cache/ai-scratch/ 等多种落点），
+  // 猜错的结果是回退命令直接报「工作 IR 不存在」，白烧一步。
+  const irTarget = irRel || `.cache/ai-scratch/${cardId}.ir.json`
+  const lines = [
+    `已连续 ${roundsSinceBest} 轮没有刷新最好成绩：最好 ${best.match}% @ r${best.round}，本轮 ${cur.match}%${regressed && last ? `（比上轮 ${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')
+}
+
+/** 报告落盘 + 轮次历史 + 停滞检测（连续多轮没刷新最好成绩 = 微调到天花板，必须叫停并回退）。 */
+export function persistReport(result, { sp, dp, irPath }) {
   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'))
@@ -351,33 +777,116 @@ function persistReport(result, { sp, dp }) {
     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
-    }
-    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,
       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 }
   } catch {
     return null
   }
@@ -387,6 +896,10 @@ function persistReport(result, { sp, dp }) {
 async function runPipeline({ ir: irPath, out: outDir, design: designPath, width, session, alwaysDiffImage, withElements, sets, specPath, skipPreflight, slicesDir: slicesDirArg }) {
   const t0 = performance.now()
 
+  // 设计稿侧元素（供 contributors 的 designH/deltaH）：只有给了 --spec 才可用。
+  // 拿不到就不给 deltaH —— 宁缺勿滥，编不出可证伪的数字比没有数字更坏。
+  const designSide = loadDesignElements(specPath, designPath)
+
   // 1. Read IR（可选 --set 编辑，原子写回）→ expand
   let ir
   let appliedSets = null
@@ -434,17 +947,30 @@ 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}`] }
   }
 
   // 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) {
@@ -497,6 +1023,53 @@ async function runPipeline({ ir: irPath, out: outDir, design: designPath, width,
   // 5.5 preflight（quickref Pre-flight Checklist 的机械化 10 条）并入本轮报告
   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 +1097,39 @@ async function runPipeline({ ir: irPath, out: outDir, design: designPath, width,
       : undefined,
     designImage,
     preflight: preflight || undefined,
+    fidelity: fidelityReport || undefined,
+    // 尺寸口径警告：宽度不对时下面所有像素指标都不可信，必须最先修
+    widthMismatch: widthMismatch || 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 })
   if (saved) {
     result.report = saved.reportPath
     result.rounds = saved.rounds
     result.gate = saved.gate
+    // 显式结论一路带到工具输出：模型与用户都能一眼看出这卡是 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>'),
       }
     }
   }
@@ -581,12 +1159,14 @@ function parseArgs(argv) {
       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）。`)
+  ∧ 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）。`)
       process.exit(0)
     }
   }
@@ -620,9 +1200,22 @@ 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 / iterating。三者之外不允许「无声退出」——
+  // 实测建卡回合里模型跑完 2 轮就直接转去做下一张卡，卡在「既没过门禁、也没判停滞」的
+  // 中间态，界面上完全看不出这卡是被放弃了还是还在迭代。
+  const conclusion = gate.passed ? 'pass' : report.stalled ? 'stalled' : 'iterating'
+  if (conclusion === 'iterating') {
+    gate.verdict +=
+      '；结论=iterating：既未过门禁、也未判停滞 —— 不允许无声退出。' +
+      '要么继续 iterate（一轮只改一项，拿到新报告再判），要么在正文里显式写明放弃理由（例：设计稿本身自相矛盾 / 缺关键切图）再停手。'
+  }
   const out = {
     ok: gate.passed,
     cardId,
+    conclusion,
+    stalled: report.stalled
+      ? { reason: report.stalled.reason || 'match', rounds: report.stalled.rounds, hint: report.stalled.hint }
+      : null,
     report: reportPath,
     gate,
     summary: {
@@ -631,6 +1224,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 +1232,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() {
@@ -694,7 +1291,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)
+  })
+}