sillyspec 3.33.3 → 3.33.5

package/src/decision-distill.js

@@ -479,15 +479,36 @@ function applyEntryToSections(sections, entry, headHash, sectionNumber, originId
 // INDEX.md decisions 路由行幂等维护（FR-05：写入责任在本模块；只动 ## Decisions 段内指向 decisions/ 的行）
 // ---------------------------------------------------------------------------
 
+/** 路由行共享泛词（FR-02，2026-10-21-knowledge-tier-denoise）：decisions 面 decision|决策 /
+ *  FR 面 FR|需求|承接 曾是全体域共享关键词——查询含泛词即命中全部路由行，注入席位退化为
+ *  INDEX 行序抽签（本仓 Decisions 段 30 行全带泛词实证）。模板侧已删；存量行由
+ *  syncIndexRoutingLines(stripTokens) 幂等剥离。 */
+export const DECISIONS_ROUTE_STRIP_TOKENS = ['decision', '决策']
+export const FR_ROUTE_STRIP_TOKENS = ['FR', '需求', '承接']
+
+/** 路由行关键词表剥泛词：`- kw1|kw2 → [..](..)` 关键词段剔除 tokens（精确等值，trim 后判），
+ *  域名与其余关键词保留；关键词表剥空则整行原样保留（不造坏行）。幂等：已剥行再剥零漂移。 */
+function stripRouteTokens(line, tokens) {
+  if (!Array.isArray(tokens) || tokens.length === 0) return line
+  const m = String(line).match(/^(\s*-\s+)([^→]+?)(\s*→[\s\S]*)$/)
+  if (!m) return line
+  const kept = m[2].split('|').map((k) => k.trim()).filter(Boolean).filter((k) => !tokens.includes(k))
+  if (kept.length === 0) return line
+  return `${m[1]}${kept.join('|')}${m[3]}`
+}
+
 /**
  * 域文件实况 ↔ INDEX 段路由行对账：缺行补、失效行删、重复行去重；不动其他类别行。
  * 2026-09-18-fr-index-l1 参数化：section/subdir/makeLine/matchTarget 经参（decisions 缺省不变），
  * fr 侧传 'FR 需求索引' 段与 fr/ 子目录——两类路由行各守各段互不干扰。
+ * stripTokens（FR-02）：对保留行与新行关键词表幂等剥离共享泛词（缺省 [] 行为不变）。
  */
 export function syncIndexRoutingLines(knowledgeRoot, opts = {}) {
   const sectionName = opts.section || 'Decisions'
   const subdir = opts.subdir || 'decisions'
-  const makeLine = opts.makeLine || ((d) => `- ${d}|decision|决策 → [${subdir}/${d}.md](${subdir}/${d}.md)`)
+  const stripTokens = Array.isArray(opts.stripTokens) ? opts.stripTokens : []
+  // 路由键=域名（FR-02 泛词退役后的唯一共享形态）；makeLine 传参者自定（fr 面 auto- 伪域附裸段关键词）
+  const makeLine = opts.makeLine || ((d) => `- ${d} → [${subdir}/${d}.md](${subdir}/${d}.md)`)
   const esc = subdir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
   const targetRe = opts.matchTarget || new RegExp(`^-\\s+.*→\\s*\\[[^\\]]*\\]\\(${esc}/([^)#]+?)(?:\\.md)?(?:#[^)]*)?\\)\\s*$`)
   const domainDir = join(knowledgeRoot, subdir)
@@ -528,15 +549,15 @@ export function syncIndexRoutingLines(knowledgeRoot, opts = {}) {
     for (const l of body) {
       const m = l.match(targetRe)
       if (!m) { kept.push(l); continue } // 非路由行（注释/空行）原样保留
-      // 目标域文件仍存在的路由行原样保留（关键词可能被人工扩充）；失效行（文件已不存在）与重复行删
-      if (domainSet.has(m[1]) && !seen.has(m[1])) { seen.add(m[1]); kept.push(l) }
+      // 目标域文件仍存在的路由行保留（关键词可能被人工扩充——剥共享泛词，其余原样）；失效行（文件已不存在）与重复行删
+      if (domainSet.has(m[1]) && !seen.has(m[1])) { seen.add(m[1]); kept.push(stripRouteTokens(l, stripTokens)) }
     }
     // 补行插在段尾空行之前（段尾空行是与下一 `## ` 的分隔，新行追加其后会出现行间空洞）
     const tail = []
     while (kept.length > 0 && kept[kept.length - 1].trim() === '') tail.unshift(kept.pop())
     for (const d of desired) {
       const m = d.match(targetRe)
-      if (m && !seen.has(m[1])) kept.push(d) // 缺行补
+      if (m && !seen.has(m[1])) kept.push(stripRouteTokens(d, stripTokens)) // 缺行补（新模板本无泛词，剥是对旧式 makeLine 的防御）
     }
     kept.push(...tail)
     const sepNeeded = secEnd < lines.length && kept.length > 0 && kept[kept.length - 1].trim() !== ''
@@ -710,7 +731,7 @@ export function distillIntoKnowledge(changeDir, knowledgeRoot, headHash, moduleI
   }
 
   // INDEX 路由行对账（仅在实际有条目写入时；零输出场景不动 INDEX）
-  if (written.length > 0) syncIndexRoutingLines(knowledgeRoot)
+  if (written.length > 0) syncIndexRoutingLines(knowledgeRoot, { stripTokens: DECISIONS_ROUTE_STRIP_TOKENS })
 
   return { written, skipped: null, needsWait }
 }

package/src/decision-redomain.js

@@ -18,7 +18,7 @@
  */
 import { existsSync, readFileSync, unlinkSync } from 'fs'
 import { join } from 'path'
-import { splitKnowledgeSections, joinKnowledgeFile, syncIndexRoutingLines } from './decision-distill.js'
+import { splitKnowledgeSections, joinKnowledgeFile, syncIndexRoutingLines, DECISIONS_ROUTE_STRIP_TOKENS } from './decision-distill.js'
 import { writeAtomicSync } from './fs-atomic.js'
 
 const DECISION_HEADER_RE = /^## (D-(?:[A-Za-z0-9_\-\u4e00-\u9fff]+-)?\d+)@v(\d+)\s*(.*)$/
@@ -33,8 +33,9 @@ function newDomainPreamble(domain) {
   ]
 }
 
-/** 段 → {id, number, version, title, change}（id=number@version 即迁域不换号的身份） */
-function sectionMeta(s) {
+/** 段 → {id, number, version, title, change}（id=number@version 即迁域不换号的身份）。
+ *  导出供 redomain-unmapped 批量清偿驱动复用（FR-04，2026-10-21-knowledge-tier-denoise）。 */
+export function sectionMeta(s) {
   const m = DECISION_HEADER_RE.exec(s.lines[0] || '')
   if (!m) return null
   const id = `${m[1]}@v${m[2]}`
@@ -135,7 +136,7 @@ export function redomainDecisionEntries({ knowledgeRoot, from, to, anchors = nul
   // INDEX 路由行：decisions 面默认参数（幂等；缺席行补上）
   const indexPath = join(knowledgeRoot, 'INDEX.md')
   const before = existsSync(indexPath) ? readFileSync(indexPath, 'utf8') : ''
-  try { syncIndexRoutingLines(knowledgeRoot) } catch { /* INDEX 缺席/同步失败不拦迁移 */ }
+  try { syncIndexRoutingLines(knowledgeRoot, { stripTokens: DECISIONS_ROUTE_STRIP_TOKENS }) } catch { /* INDEX 缺席/同步失败不拦迁移 */ }
   const after = existsSync(indexPath) ? readFileSync(indexPath, 'utf8') : ''
 
   return {

package/src/docs-check.js

@@ -18,6 +18,7 @@ import { join, resolve as pathResolve, relative as pathRelative, sep as pathSep
 import { execFileSync } from 'node:child_process'
 import jsYaml from 'js-yaml'
 import { parseModuleMapSimple } from './modules.js'
+import { unquoteYamlScalar } from './yaml-scalar-unquote.js'
 
 // ── HEAD 模式内容解析层（坑 docs-gate-shared-worktree-parallel-block，2026-09-08 实证）──
 // pre-push gate 校验的语义对象是「被推送的提交树」，而磁盘工作区混有并行会话的未提交
@@ -967,10 +968,12 @@ export function extractKnownFailureKeys(yamlText) {
   if (!yamlText) return []
   const yaml = String(yamlText).replace(/\r\n?/g, '\n')
   // 贪婪 .* 同 verify-postcheck.extractKnownFailures（坑 known-failures-inline-nested-bracket：
-  // 值内 ] 使 [^\]]* 截断、整表静默清空；两处复刻必须同口径互指）
+  // 值内 ] 使 [^\]]* 截断、整表静默清空；两处复刻必须同口径互指）。条目规范化三读侧统一走
+  // yaml-scalar-unquote（2026-10-21-known-failures-unescape：双引号反转义——写侧按 YAML 规范
+  // 转义的 \\. 读侧不还原会把豁免键留成字面双反斜杠）
   const inline = yaml.match(/^known_failures:\s*\[(.*)\]\s*(?:#.*)?$/m)
   if (inline) {
-    return inline[1].split(',').map(s => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean)
+    return inline[1].split(',').map(s => unquoteYamlScalar(s)).filter(Boolean)
   }
   // 坑 verify-known-failures-comment-line-truncation → verify-known-failures-block-fragile-chain
   // （与 verify-postcheck.extractKnownFailures 口径互指对齐，逐字同步）：块式捕获曾要求
@@ -995,10 +998,11 @@ export function extractKnownFailureKeys(yamlText) {
     .map(s => {
       const item = s.trim()
       const full = item.match(/^(['"])(.*)\1$/)
-      if (full) return full[2]
+      // 引号值经 unquoteYamlScalar 反转义（与流式/verify-postcheck 三读侧同口径）；裸值照旧剥行尾注释
+      if (full) return unquoteYamlScalar(item)
       const stripped = item.replace(/[ \t]+#.*$/, '').trim()
       const q2 = stripped.match(/^(['"])(.*)\1$/)
-      return q2 ? q2[2] : stripped
+      return q2 ? unquoteYamlScalar(stripped) : stripped
     })
     .filter(Boolean)
 }

package/src/doctor-diagnostics.js

@@ -25,6 +25,8 @@
 import { openDatabase, pluckGet, pluckAll } from './db-engine.js';
 import { runtimeTempPath } from './runtime-paths.js'
 import { safeGit } from './git-helper.js';
+import { batchCatFileExists } from './git-helper.js';
+import { batchStageBlobSha256 } from './git-helper.js';
 import { createHash } from 'crypto';
 import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, writeFileSync, unlinkSync, rmSync } from 'fs';
 import { join, relative, resolve, dirname } from 'path';
@@ -630,6 +632,59 @@ function localYamlHasPlatformSection(cwd) {
   }
 }
 
+// ── local.yaml 完整性维度（2026-10-21-p0-p1-hardening FR-07 / dsh z2 实证）────────────
+// agent 手改 local.yaml（PS5.1 Set-Content -Encoding UTF8）把 50KB 文件写成 GBK mojibake
+// （不可逆，510 个 ?）——commands/known_failures/门禁全部 reader 对坏文件 fail-open/降级，
+// doctor 却零提示（agent 原话推理实证「Doctor doesn't complain about local.yaml」），最终等
+// 用户人工贴备份 2h13m。本维度把「文件存在但不可解析 / 含 BOM」显性化（只读，绝不自动修）。
+export function detectLocalYamlIntegrity(cwd) {
+  const dim = {
+    name: 'local_yaml_integrity',
+    label: 'local.yaml 完整性',
+    safe_actions: [],
+    findings: [],
+  };
+  const p = join(cwd, '.sillyspec', 'local.yaml');
+  if (!existsSync(p)) return dim; // 无文件是合法状态（本地模式），不报
+  let text;
+  try {
+    text = readFileSync(p, 'utf8');
+  } catch (e) {
+    dim.findings.push(
+      `local_yaml_unreadable: local.yaml 读取失败（${String(e && e.message ? e.message : e).split('\n')[0]}）——` +
+      `权限/占用问题；修复后用 sillyspec config known-failures list 校验键面`
+    );
+    return dim;
+  }
+  if (text.charCodeAt(0) === 0xfeff) {
+    dim.findings.push(
+      `local_yaml_bom: local.yaml 含 UTF-8 BOM——PS5.1 写文件常见（-Encoding UTF8 恒写 BOM）；` +
+      `YAML 解析器多可容忍，但定向行扫描 reader 与 PowerShell 工具链易致盲。` +
+      `修复：node -e "const fs=require('fs');const p=process.argv[1];fs.writeFileSync(p,fs.readFileSync(p,'utf8').replace(/^\\uFEFF/,''))" ${p}`
+    );
+  }
+  try {
+    jsYaml.load(text);
+  } catch (e) {
+    dim.findings.push(
+      `local_yaml_unparsable: local.yaml YAML 解析失败（${String(e && e.message ? e.message : e).split('\n')[0]}）——` +
+      `commands/known_failures/门禁等全部 reader 对坏文件 fail-open 或降级，后续 gate 行为不可信` +
+      `（dsh z2 实证：手改炸文件后 doctor 失明，人工恢复耗时 2h13m）。` +
+      `修复：从备份/git 历史恢复或按 sillyspec config schema 重建；known_failures 键改用 ` +
+      `sillyspec config known-failures add/remove 管理（坏文件上该命令拒改并给指引）`
+    );
+    dim.safe_actions.push({
+      dimension: 'local_yaml_integrity',
+      action: 'restore_local_yaml',
+      target: p,
+      risk: 'confirm_required',
+      rationale: '坏配置是所有门的输运层——文件不可解析时任何 reader 行为都不可信，必须先恢复再谈其他',
+      next_step: `从备份/git 历史恢复或重建 ${p}，然后 sillyspec config known-failures list 校验`,
+    });
+  }
+  return dim;
+}
+
 function detectRepoNativeChain(cwd, pointer) {
   const dim = {
     name: 'repo_native_chain',
@@ -1023,6 +1078,17 @@ function detectApplyManifestDrift(cwd, specDir) {
     const scanned = manifests.slice(0, 5)
     const findings = []
     let checked = 0
+    // ── staged 态批量预取（2026-10-21-protocol-tax task-07 / FR-07）──
+    // 旧实现逐文件 `git show :<path>`（最近 5 份 manifest × 全部文件逐个 spawn，Windows 税
+    // 可观）；单次 `git cat-file --batch` 按输入序回流等价替换。miss=null=未暂存，与旧
+    // gitQuiet null 同语义；整批失败空表全 miss（不洗白：暂存面查不到就当未暂存处理）。
+    const stagedEntries = []
+    for (const m of scanned) {
+      for (const ent of m.files) {
+        if (ent && typeof ent.path === 'string' && typeof ent.sha256 === 'string') stagedEntries.push(ent)
+      }
+    }
+    const stagedMap = batchStageBlobSha256(cwd, stagedEntries.map((e) => e.path))
     for (const m of scanned) {
       for (const ent of m.files) {
         if (!ent || typeof ent.path !== 'string' || typeof ent.sha256 !== 'string') continue // 坏条目跳过
@@ -1036,10 +1102,8 @@ function detectApplyManifestDrift(cwd, specDir) {
             .update(Buffer.from(raw.toString('latin1').replace(/\r\n/g, '\n'), 'latin1'))
             .digest('hex')
         } catch { /* 盘上无 → 丢失分支候选 */ }
-        // staged 态：git show :<path> buffer 直接 sha256（staged blob 即 LF 规范态，与写侧同基）
-        let stagedHash = null
-        const blob = gitQuiet(cwd, ['show', `:${ent.path}`], { encoding: 'buffer', timeout: 15000 })
-        if (Buffer.isBuffer(blob)) stagedHash = createHash('sha256').update(blob).digest('hex')
+        // staged 态：查批量预取表（task-07；staged blob 即 LF 规范态，与写侧同基）
+        const stagedHash = stagedMap.get(ent.path) ?? null
         const tag = `${m.change}×${ent.path}`
         if (worktreeHash === null && stagedHash === null) {
           findings.push(`${tag} 丢失（盘上与暂存区皆无；期望 ${short(ent.sha256)}）`)
@@ -1233,6 +1297,22 @@ export function detectArchiveIntegrity(cwd, authoritySpecDir) {
     };
   }
   const offenders = [];
+  // ── 锚点批量预检（2026-10-21-protocol-tax task-07 / FR-07）──
+  // 旧实现主循环内逐 SHA 起 `git cat-file -e`（消费仓 681 归档 × ≤2 SHA × Windows 单 spawn
+  // ~130ms ≈ 25s+，doctor 实测 41.8s 的 70% 在此）。改为循环前收集全量 40-hex SHA、单次
+  // `git cat-file --batch-check` 判存，主循环 anchorOk 查表。等价性：missing/探针失败 =
+  // 旧 safeGit error → 均按不可解析=悬空同向 fail；change-patch.json 缺失/不可解析 →
+  // 两版同样不计锚点欠账（主循环 catch 语义原样）。
+  const anchorShas = new Set();
+  for (const name of names) {
+    try {
+      const cpMetaPre = JSON.parse(readFileSync(join(archiveDir, name, 'change-patch.json'), 'utf8'));
+      for (const sha of [cpMetaPre?.head, cpMetaPre?.baseline]) {
+        if (sha && /^[0-9a-f]{40}$/i.test(String(sha))) anchorShas.add(String(sha).toLowerCase());
+      }
+    } catch { /* change-patch.json 缺失/不可解析：主循环既有语义不变（不计锚点欠账） */ }
+  }
+  const anchorExists = batchCatFileExists(cwd, [...anchorShas]);
   // FR 索引面（D14 第四检查数据源，循环外一次扫描复用；fr/ 不存在=仓未启用，全跳不误报）
   const frKnowledgeRoot = join(authoritySpecDir, 'knowledge');
   const frEnabled = existsSync(join(frKnowledgeRoot, 'fr'));
@@ -1323,7 +1403,7 @@ export function detectArchiveIntegrity(cwd, authoritySpecDir) {
         const cpMeta = JSON.parse(readFileSync(cpJsonPath, 'utf8'));
         const anchorOk = (sha) => {
           if (!sha || !/^[0-9a-f]{40}$/i.test(String(sha))) return !sha; // 空锚不算悬空（无 git 基线形态）
-          return !safeGit(cwd, ['cat-file', '-e', `${sha}^{commit}`]).error;
+          return anchorExists.get(String(sha).toLowerCase()) === true; // 查批量预检表（task-07/FR-07）
         };
         const headDangling = !anchorOk(cpMeta.head);
         const baseDangling = !anchorOk(cpMeta.baseline);
@@ -1606,7 +1686,10 @@ export async function runDoctorDiagnostics({ cwd }) {
   } catch { gateLeakRuntimeRoot = null }
   const gateSnapshotLeak = detectGateSnapshotLeak({ runtimeRoot: gateLeakRuntimeRoot })
   const knowledgeGraphIntegrity = detectKnowledgeGraphIntegrity(cwd, authoritySpecDir || join(cwd, '.sillyspec'))
-  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat, repoNativeChain, lifecycleDoc, worktreeHealth, crossWorktreeHealth, buildEnv, mcpEndpoints, applyManifestDrift, selfMaintenanceTax, archiveIntegrity, ceremonyShadow, gateSnapshotLeak, knowledgeGraphIntegrity];
+  // FR-07（2026-10-21-p0-p1-hardening / dsh z2 实证）：local.yaml 完整性——此前 doctor 对
+  // mojibake 坏文件完全失明（agent 手改炸文件后 doctor 报一堆别项零提示，等用户人工恢复 2h13m）
+  const localYamlIntegrity = detectLocalYamlIntegrity(cwd);
+  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat, repoNativeChain, lifecycleDoc, worktreeHealth, crossWorktreeHealth, buildEnv, mcpEndpoints, applyManifestDrift, selfMaintenanceTax, archiveIntegrity, ceremonyShadow, gateSnapshotLeak, knowledgeGraphIntegrity, localYamlIntegrity];
 
   return {
     dimensions,

package/src/flow-parity.js

@@ -522,6 +522,20 @@ export function detectPatchDrift({ cwd, change, freezeHead }) {
  * gate-snapshot 同款判定注入）时未提交 dirty 交付面一并入冻结——独占树内 dirty 全归属本变更；
  * 共享主仓无法归属 → 不入面只警告（他侧声明的 dirty 连警告都免）。
  */
+/**
+ * dirty_gate_ignore 读取（2026-10-23-dirty-gate-ignore，module_gate_ignore/readFlowConfig
+ * 同款逐键正则防线）：local.yaml 单行逗号串（目录/文件前缀，posix），列表块形态不支持。
+ * 三态 fail-soft——未配置/键值非法/local.yaml 不可读 → 空清单（dirty 门行为与现状逐字一致）。
+ */
+export function readDirtyGateIgnore(specBase) {
+  try {
+    const raw = readFileSync(join(specBase, 'local.yaml'), 'utf8')
+    const m = raw.match(/^\s*dirty_gate_ignore\s*:\s*(.+)$/m)
+    if (!m) return []
+    return m[1].split(',').map((s) => s.trim().replace(/\\/g, '/')).filter(Boolean)
+  } catch { return [] }
+}
+
 export function collectFreezeFiles({ cwd, specBase, change, committed, exclusive }) {
   const deliverable = (f) => !String(f).replace(/\\/g, '/').startsWith('.sillyspec/')
     && !isToolGovernancePath(f)
@@ -540,6 +554,12 @@ export function collectFreezeFiles({ cwd, specBase, change, committed, exclusive
       if (deliverable(path) && !dirty.includes(path)) dirty.push(path)
     }
   } catch { /* git 失败零 dirty 面 */ }
+  // 已知残渣前缀剔除（2026-10-23-dirty-gate-ignore，单一源）：仓主显式声明的残渣面
+  // （quicklog/、测试夹具运行库等）不进 dirty 冻结缺口——剔除进 dirtyIgnored 随返回值
+  // 留证（权威门打 ℹ️ 留痕行）；预检（flow-preflight.js）经本函数自动同源继承。
+  const ignorePrefixes = readDirtyGateIgnore(specBase)
+  const dirtyIgnored = ignorePrefixes.length > 0 ? dirty.filter((f) => ignorePrefixes.some((pfx) => f.startsWith(pfx))) : []
+  if (dirtyIgnored.length > 0) dirty = dirty.filter((f) => !dirtyIgnored.includes(f))
   // 归属切分单点：exclusive（worktree/--freeze-dirty）与共享主仓共用——他侧已声明 dirty 永不入冻
   // （评审 P2 修复：--freeze-dirty 承诺「非他侧声明」，全量冻入会造成跨变更审计双计；worktree
   // 下 own 恒为全量，切分无伤）
@@ -547,8 +567,8 @@ export function collectFreezeFiles({ cwd, specBase, change, committed, exclusive
   try {
     ownDirty = splitOwnVsForeignDiffFiles(cwd, change, dirty, { specBase }).own
   } catch { /* 归属切分失败：exclusive 保留全量（声明即边界），共享主仓退全量警告 */ }
-  if (exclusive) return { files: [...new Set([...committed, ...ownDirty])], dirtyAdded: ownDirty, dirtyWarned: [] }
-  return { files: [...committed], dirtyAdded: [], dirtyWarned: ownDirty }
+  if (exclusive) return { files: [...new Set([...committed, ...ownDirty])], dirtyAdded: ownDirty, dirtyWarned: [], dirtyIgnored }
+  return { files: [...committed], dirtyAdded: [], dirtyWarned: ownDirty, dirtyIgnored }
 }
 
 /**

package/src/flow-preflight.js

@@ -0,0 +1,67 @@
+/**
+ * flow-preflight.js — 收口预检（fail-together 一次报全，2026-10-23-flow-done-preflight）
+ *
+ * 背景（收口画像实证）：621 次 flow done 调用/255 变更=2.44 次/变更，净浪费 152 次 RTT（24.5%）
+ * 源于逐门 fail-fast 串行拒绝；dirty-gap 门在实测门之后——56% 触发率的门每次拦截都先付一轮
+ * 完整实测（58s 起、大仓分钟级）。
+ *
+ * 本模块是纯前移报告层：实测门前只读收集「独立可算的便宜阻断条件」，由 flow.js 侧渲染一次
+ * 报全后拦在付费实测之前。判定与权威门同源同判定（复用同一批函数而非重写），旗标与守卫
+ * 逐条镜像 patch 子步：
+ *   - dirty-gap 预判镜像 collectFreezeFiles dirtyWarned 非空 && !freezeDirty && !acceptDirtyGap
+ *     && !turbo（turbo 下权威门降 advisory，镜像不拦）
+ *   - orphan-face 预判镜像仅会话独占 worktree（shouldSkipGateSnapshotForWorktree）且
+ *     !acceptOrphanFace
+ *   - 守卫：baseline 缺席跳过（patch 子步整体跳过面）；patch 子步已 done 跳过——预检绝不
+ *     重复拦已过权威门的面（断点续不误拦）
+ *
+ * 放弃项（评审已裁决，见 design 风险与死路）：review.json schema 预验不做——schema 违规的
+ * 成本是「修正文件+重跑」一轮 RTT，与检测时点无关（同轮提前检测不省轮次）；且豁免轮
+ * （--no-review）权威门不读文件，预检先验会多拦权威门不拦的面（判定漂移），三路皆负。
+ *
+ * fail-safe 单向：预检异常静默放行（返回空 findings）——漏报由权威门兜底（仍在原子步原序），
+ * 预检不构成新失败面；全程零写盘（不落冻结件、不 mark 子步、不写 flow-state）。
+ */
+import { gitQuiet } from './git-helper.js'
+
+/**
+ * 收集收口预检阻断条件（纯计算零打印）。
+ * @returns {{ findings: Array<{id:'dirty-gap',count:number,files:string[]} | {id:'orphan-face',commits:string[],count:number,files:string[]}> }}
+ */
+export async function collectCloseoutPreflight({ cwd, specBase, change, st, freezeDirty = false, acceptDirtyGap = false, acceptOrphanFace = false, turbo = false }) {
+  const findings = []
+  const patchDone = st?.substeps?.patch === 'done'
+  // ── dirty-gap / orphan-face 预判（镜像 patch 子步判定链）──
+  if (!patchDone && st?.baseline_commit) {
+    try {
+      let exclusiveFrom = freezeDirty === true ? 'flag' : null
+      if (exclusiveFrom == null) {
+        try {
+          const { shouldSkipGateSnapshotForWorktree } = await import('./run/gate-snapshot.js')
+          if (shouldSkipGateSnapshotForWorktree(cwd)) exclusiveFrom = 'worktree'
+        } catch { /* 判定异常按共享主仓（权威门同款） */ }
+      }
+      const exclusive = exclusiveFrom != null
+      const committedRaw = String(gitQuiet(cwd, ['diff', '--name-only', `${st.baseline_commit}..HEAD`]) || '')
+        .split('\n').map((s) => s.trim().replace(/\\/g, '/')).filter(Boolean)
+      const { filterCommittedFace, collectFreezeFiles, scanOrphanFace } = await import('./flow-parity.js')
+      const ownPrefix = `.sillyspec/changes/${change}/`
+      const committed = filterCommittedFace(committedRaw, ownPrefix)
+      const freeze = collectFreezeFiles({ cwd, specBase, change, committed, exclusive })
+      if (freeze.dirtyWarned.length > 0 && !freezeDirty && !acceptDirtyGap && !turbo) {
+        findings.push({ id: 'dirty-gap', count: freeze.dirtyWarned.length, files: freeze.dirtyWarned })
+      }
+      if (exclusiveFrom === 'worktree' && !acceptOrphanFace) {
+        try {
+          const orphan = scanOrphanFace(cwd, { baseline: st.baseline_commit })
+          if (orphan.files.length > 0) {
+            findings.push({ id: 'orphan-face', commits: orphan.commits, count: orphan.files.length, files: orphan.files })
+          }
+        } catch { /* orphan 预判 fail-safe（权威门同款不阻断） */ }
+      }
+    } catch { /* 预检 fail-safe：异常静默放行（权威门仍在 patch 子步原序原判定） */ }
+  }
+  return { findings }
+}
+
+export default { collectCloseoutPreflight }