sillyspec 3.28.2 → 3.28.4

package/src/sync.js

@@ -17,6 +17,7 @@ import { safeGit } from './git-helper.js';
 import { openDatabase } from './db-engine.js';
 import { PLATFORM_MANAGED_FILENAME, QUICK_SID_RE } from './run/shared.js';
 import { syncSpecTree } from './spec-sync.js';
+import { bindSyncNoiseFromCwd, syncConnectionWarn, isConnectionClassStatus, noteSyncSuccess } from './sync-noise.js';
 
 // sync 是 best-effort（网络失败只 warn）：平台指针失效时不抛，跳过平台、回退本地。
 function safePlatformSpecDir(cwd) {
@@ -218,11 +219,18 @@ function combineSignals(external, timeoutMs = REQUEST_TIMEOUT_MS) {
 
 async function fetchJson(url, options = {}) {
   const signal = combineSignals(options.signal);
+  // noMute 是本模块的闸门开关不是 fetch 参数，先剥掉再透传
+  const { noMute, ...init } = options;
   try {
-    const res = await fetch(url, { ...options, signal });
+    const res = await fetch(url, { ...init, signal });
     if (!res.ok) {
       const text = await res.text().catch(() => '');
-      console.warn(`[sync] ${options.method || 'GET'} ${url} → ${res.status} ${text.slice(0, 200)}`);
+      const line = `[sync] ${options.method || 'GET'} ${url} → ${res.status} ${text.slice(0, 200)}`;
+      // 连接类失败（404=端点未就绪 / 5xx）走跨进程噪音闸：平台未就绪期每条命令的自动
+      // 同步都撞同一批失败，重复刷屏淹没门禁输出（见 sync-noise.js 模块头）。409 冲突与
+      // 其余 4xx 业务态每轮都该看见，不走闸。用户显式命令（connect health ping）传 noMute。
+      if (!noMute && isConnectionClassStatus(res.status)) syncConnectionWarn(line);
+      else console.warn(line);
       return null;
     }
     const ct = res.headers.get('content-type') || '';
@@ -231,11 +239,11 @@ async function fetchJson(url, options = {}) {
     }
     return null;
   } catch (err) {
-    if (err.name === 'AbortError') {
-      console.warn(`[sync] ${url} 请求超时/中断 (${REQUEST_TIMEOUT_MS}ms 上限或外部熔断)`);
-    } else {
-      console.warn(`[sync] ${url} 请求失败: ${err.message}`);
-    }
+    const line = err.name === 'AbortError' || err.name === 'TimeoutError'
+      ? `[sync] ${url} 请求超时/中断 (${REQUEST_TIMEOUT_MS}ms 上限或外部熔断)`
+      : `[sync] ${url} 请求失败: ${err.message}`;
+    if (!noMute) syncConnectionWarn(line);
+    else console.warn(line);
     return null;
   }
 }
@@ -247,23 +255,26 @@ async function fetchJson(url, options = {}) {
  */
 async function fetchJsonWithStatus(url, options = {}) {
   const signal = combineSignals(options.signal);
+  const { noMute, ...init } = options;
   try {
-    const res = await fetch(url, { ...options, signal });
+    const res = await fetch(url, { ...init, signal });
     const text = await res.text().catch(() => '');
     let body = null;
     if (text) {
       try { body = JSON.parse(text); } catch { body = null; }
     }
     if (!res.ok) {
-      console.warn(`[sync] ${options.method || 'GET'} ${url} → ${res.status} ${text.slice(0, 200)}`);
+      const line = `[sync] ${options.method || 'GET'} ${url} → ${res.status} ${text.slice(0, 200)}`;
+      if (!noMute && isConnectionClassStatus(res.status)) syncConnectionWarn(line);
+      else console.warn(line);
     }
     return { ok: res.ok, status: res.status, body };
   } catch (err) {
-    if (err.name === 'AbortError') {
-      console.warn(`[sync] ${url} 请求超时/中断 (${REQUEST_TIMEOUT_MS}ms 上限或外部熔断)`);
-    } else {
-      console.warn(`[sync] ${url} 请求失败: ${err.message}`);
-    }
+    const line = err.name === 'AbortError' || err.name === 'TimeoutError'
+      ? `[sync] ${url} 请求超时/中断 (${REQUEST_TIMEOUT_MS}ms 上限或外部熔断)`
+      : `[sync] ${url} 请求失败: ${err.message}`;
+    if (!noMute) syncConnectionWarn(line);
+    else console.warn(line);
     return { ok: false, status: 0, body: null };
   }
 }
@@ -399,6 +410,12 @@ export class SyncManager {
     // 归档尾声静默化旗标（坑 post-archive-sync-noise）：sync() 探测到已归档时置位，
     // 链内 syncDocuments 的「变更不存在」降 debug（每次 sync 调用重置）
     this._suppressDocsMissingWarn = false;
+    // 绑定连接类失败噪音闸的 marker 目录（sync-noise.js）：本实例所有 fetch 失败 warn 的
+    // 跨进程静默窗口落这里。bindSyncNoiseFromCwd 零副作用（只读指针 JSON，不触发
+    // resolvePlatformSpecDir 的指针守卫 warn——doctor 两路字节一致契约）。
+    try {
+      bindSyncNoiseFromCwd(cwd);
+    } catch { /* 未绑定 = 闸门直通（多一行 warn，无正确性影响） */ }
   }
 
   /**
@@ -423,7 +440,8 @@ export class SyncManager {
       console.warn(`[sync] platform.url 非 https（${normalizedUrl.slice(0, 60)}），同步 token 将明文传输——请确认为受控内网环境`);
     }
     const healthUrl = `${normalizedUrl}/api/health`;
-    const result = await fetchJson(healthUrl);
+    // noMute：connect 是用户显式命令，health ping 的失败细节不走静默闸（用户正在诊断连接）
+    const result = await fetchJson(healthUrl, { noMute: true });
     if (result === null) {
       console.warn(`[sync] 平台连接验证失败: ${url}`);
       return;
@@ -661,6 +679,9 @@ export class SyncManager {
       }
 
       if (res.ok) {
+        // 平台连接恢复信号（sync-noise.js）：此前静默窗口内的失败在恢复的第一笔成功时
+        // 打一行提示并清 marker；之后照常「成功不打扰」。
+        noteSyncSuccess();
         // 更新 platform_last_sync + 推进 base_ts（ql-20260818-008：值优先平台回执 last_pushed_at，
         // 缺省用本次 pushedAt——服务器 _apply 存的就是客户端 X-SillySpec-Pushed-At 原值，回写一致。
         // 修复前该列从不写，下次 push 永不带 X-SillySpec-Base-Ts、pull 脏度检测恒 false）
@@ -1268,8 +1289,12 @@ export class SyncManager {
       signal: opts.signal, // HUB-09：熔断 abort 传到底层请求
     });
     if (result === null) {
-      // sillyhub 未就绪 / 404 / 网络失败均 fetchJson 返回 null → Best Effort 降级
-      console.warn(`[sync] 拉取变更进度失败: ${changeName}（sillyhub 未就绪或变更不存在）`);
+      // sillyhub 未就绪 / 404 / 网络失败均 fetchJson 返回 null → Best Effort 降级。
+      // 自动注入点（triggerPull，opts.autoPull）走噪音闸防刷屏；手动 `platform pull`
+      // 是用户显式诊断动作，恒可见。
+      const line = `[sync] 拉取变更进度失败: ${changeName}（sillyhub 未就绪或变更不存在）`;
+      if (opts.autoPull) syncConnectionWarn(line);
+      else console.warn(line);
       return { ok: false, imported: false, conflict: false, reason: '拉取变更进度失败' };
     }
 

package/src/task-review.js

@@ -1398,7 +1398,21 @@ export async function adoptTaskReviewMechanics({ changeName, cwd, platformOpts =
         ? crossDiffFiles.filter(f => allowedPaths.some(p => pathMatches(f, p)))
         : crossDiffFiles
     } else {
-      const mainDiff = Array.isArray(diffFiles) ? diffFiles : []
+      // 坑 backfill-reviews-adopt-empties-changedfiles（2026-09-08 实证）：主仓 task 同样
+      // 优先卡锚点切片（base_commit/head_commit），不再共用「worktree 基线..当前 HEAD」——
+      // per-task commit 模式下 base 必须是本 task 起点commit，diff 才与 allowed_paths 对齐
+      // （跨仓路径本就按卡切片）；卡无锚点回落 change 级切片（旧语义，兼容 wave 级提交）。
+      const cardHead = parseHeadCommit(content)
+      const cardBase = parseBaseCommit(content)
+      let mainDiff = Array.isArray(diffFiles) ? diffFiles : []
+      if (cardHead) {
+        taskHead = cardHead
+        taskBase = cardBase || taskBase
+        try {
+          const out = runGit(reviewGitDir, ['diff', '--name-only', `${taskBase}..${taskHead}`])
+          mainDiff = out ? out.split('\n').filter(Boolean).map(p => p.replace(/\\/g, '/')) : []
+        } catch { /* 锚点不可解析（如卡记短 hash 仓内无引用）→ 回落 change 级切片 */ }
+      }
       taskChangedFiles = allowedPaths.length > 0
         ? mainDiff.filter(f => allowedPaths.some(p => pathMatches(f, p)))
         : []
@@ -1410,6 +1424,16 @@ export async function adoptTaskReviewMechanics({ changeName, cwd, platformOpts =
       continue
     }
 
+    // 切片空不冲声明（2026-09-08 用户反馈：backfill-reviews --adopt 冲掉 review）：task 卡
+    // 无 allowed_paths、或 allowed_paths 与 change 级 diff 的路径形态失配时，上方过滤产出
+    // 空 changedFiles——旧代码照样整字段覆写，reviewer 已声明且过证据校验的 changedFiles
+    // 被清空，gate（verifyReviewGitEvidence）随即按空集误判。adopt 的职责是重算 mechanics，
+    // 不是降级声明：计算切片为空而原声明非空时保留原声明并留 reason 可追溯。
+    if (taskChangedFiles.length === 0 && Array.isArray(prev.changedFiles) && prev.changedFiles.length > 0) {
+      taskChangedFiles = prev.changedFiles
+      reasons.push(`${taskId}: allowed_paths 未切出任何 diff 文件（卡无声明/路径形态失配），保留原 changedFiles ${prev.changedFiles.length} 条不冲空`)
+    }
+
     const merged = { ...prev }
     merged.schemaVersion = REVIEW_SCHEMA_VERSION
     merged.task = taskId
@@ -1468,6 +1492,206 @@ export async function adoptTaskReviewMechanics({ changeName, cwd, platformOpts =
   return { adopted, unchanged, skipped, missing, downgraded, reasons, executeRunId }
 }
 
+/**
+ * writeTaskReview —— 单 task review.json 的命令式写入（`sillyspec review write`，2026-09-07）。
+ *
+ * 背景（noAI 主流程批次 T2-4）：task 级 review.json 此前由 agent/子代理手拼 JSON + 手算
+ * base/head + 手抄 changedFiles——schemaVersion/目录创建/executeRunId 解析/git 锡点全部是
+ * 纯机械活（generateTaskReviewDrafts/adoptTaskReviewMechanics 已证明 CLI 可代算），agent 只
+ * 应贡献判断字段（verdict/notes/evidence）。命令式写入消灭「手拼 JSON→gate 拒→重写」循环。
+ *
+ * 职责分工：
+ *   - CLI 代算（mechanics）：executeRunId（marker 优先）、base/head（worktree meta 优先，
+ *     --base/--head 显式覆盖）、changedFiles（diff × allowed_paths 归属切片，--changed-files
+ *     显式覆盖）、diffPaths（allowed_paths 非空时）、repo 锡点（task 卡）。
+ *   - agent 供给（判断）：--spec/--quality verdict、--notes、--evidence。
+ *
+ * 防伪/防误写：
+ *   - review.json 已存在 → 拒绝覆盖（--force 显式越过，控制台留痕）——保护独立 reviewer 产物。
+ *   - verdict=cannot_verify 且未给 --evidence → 报错（schema 硬要求非空 requiredEvidence），
+ *     不静默填占位（与草稿语义不同：草稿是兜底待复核，这里是 agent 明确结论）。
+ *   - 归属切片为空（allowed_paths 未命中 diff）→ 报错并列出 diff 候选与 task allowed_paths
+ *     （帮 agent 当场发现「改了声明外文件 / 路径写错」），--changed-files 显式越过。
+ *
+ * @param {object} opts
+ * @param {string} opts.changeName
+ * @param {string} opts.cwd
+ * @param {string} opts.taskId - 形如 task-NN
+ * @param {string} opts.specVerdict - pass | fail | cannot_verify
+ * @param {string} opts.qualityVerdict - 同上
+ * @param {string} [opts.reviewerNotes]
+ * @param {string[]} [opts.requiredEvidence]
+ * @param {string|null} [opts.baseOverride] - 显式 base 锡点（无 worktree meta 时必填）
+ * @param {string|null} [opts.headOverride]
+ * @param {string[]|null} [opts.changedFilesOverride]
+ * @param {boolean} [opts.force] - 覆盖已存在 review.json
+ * @param {object} [opts.platformOpts]
+ * @returns {Promise<{ok: boolean, reviewPath?: string, executeRunId?: string, errors: string[], warnings: string[]}>}
+ */
+export async function writeTaskReview({
+  changeName, cwd, taskId, specVerdict, qualityVerdict,
+  reviewerNotes = '', requiredEvidence = [],
+  baseOverride = null, headOverride = null, changedFilesOverride = null,
+  force = false, platformOpts = {},
+}) {
+  const errors = []
+  const warnings = []
+  const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
+  const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
+  const changeDir = join(specBase, 'changes', changeName)
+
+  // ── 入参校验 ──
+  if (!changeName || typeof changeName !== 'string') errors.push('缺少 --change <变更名>')
+  if (!taskId || !/^task-\d+$/.test(taskId)) errors.push(`--task 格式应为 task-NN（实际 ${taskId}）`)
+  if (!VALID_VERDICTS.includes(specVerdict)) errors.push(`--spec verdict 无效：${specVerdict}（应为 ${VALID_VERDICTS.join('/')}）`)
+  if (!VALID_VERDICTS.includes(qualityVerdict)) errors.push(`--quality verdict 无效：${qualityVerdict}（应为 ${VALID_VERDICTS.join('/')}）`)
+  if ((specVerdict === 'cannot_verify' || qualityVerdict === 'cannot_verify')
+    && (!Array.isArray(requiredEvidence) || requiredEvidence.filter(Boolean).length === 0)) {
+    errors.push('verdict=cannot_verify 必须给 --evidence "<非空说明>"（schema 硬要求 requiredEvidence 非空）')
+  }
+  if (errors.length > 0) return { ok: false, errors, warnings }
+
+  // ── task 卡与 executeRunId 解析（与草稿生成同源）──
+  const taskCardPath = join(changeDir, 'tasks', `${taskId}.md`)
+  if (!existsSync(taskCardPath)) {
+    return { ok: false, errors: [`task 卡不存在：${taskCardPath}（先由 plan 阶段生成或手建）`], warnings }
+  }
+  const markerFile = join(runtimeRoot, 'current-execute-run-id-' + changeName)
+  let executeRunId = ''
+  try {
+    if (existsSync(markerFile)) {
+      const c = readFileSync(markerFile, 'utf8').trim()
+      if (isValidExecuteRunId(c)) executeRunId = c
+    }
+  } catch {}
+  if (!executeRunId) {
+    executeRunId = resolveLatestExecuteRunId({ runtimeRoot, changeName }) || ''
+  }
+  if (!executeRunId) {
+    executeRunId = generateExecuteRunId()
+    warnings.push(`无 execute run marker——已生成新 runId ${executeRunId} 并建目录（正常应先跑过 execute Wave 步）`)
+    try {
+      mkdirSync(join(runtimeRoot, 'execute-runs', executeRunId, 'tasks'), { recursive: true })
+      writeFileSync(markerFile, executeRunId + '\n')
+      stampExecuteRunChange(runtimeRoot, executeRunId, changeName)
+    } catch (e) {
+      return { ok: false, errors: [`execute run 目录/marker 写入失败：${e.message}`], warnings }
+    }
+  }
+
+  const reviewDir = join(runtimeRoot, 'execute-runs', executeRunId, 'tasks', taskId)
+  const reviewPath = join(reviewDir, 'review.json')
+
+  // ── 已存在保护（--force 越过）──
+  if (existsSync(reviewPath) && !force) {
+    return { ok: false, errors: [`review.json 已存在：${reviewPath}——拒绝覆盖（保护既有 reviewer 结论）；确认重写加 --force`], warnings }
+  }
+  if (existsSync(reviewPath)) warnings.push(`--force 覆盖已存在 review：${reviewPath}`)
+
+  // ── mechanics 代算：base/head（worktree meta 优先，显式覆盖次之）──
+  let base = baseOverride
+  let head = headOverride
+  let reviewGitDir = cwd
+  if (!base || !head) {
+    try {
+      const wm = new WorktreeManager({ cwd })
+      const meta = wm.getMeta(changeName)
+      if (!base) base = (meta && (meta.baselineCommit || meta.baseHash)) || null
+      if (meta && meta.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath)) {
+        reviewGitDir = meta.worktreePath
+      }
+    } catch { /* meta 读取失败走显式覆盖路径 */ }
+  }
+  if (!head) {
+    try { head = runGit(reviewGitDir, ['rev-parse', 'HEAD']) } catch { head = null }
+  }
+  if (!base || !head) {
+    return {
+      ok: false,
+      errors: [`无法确定 base/head（无 worktree meta 且未显式覆盖）——用 --base <commit> --head <commit> 显式给出（git rev-parse 取值）`],
+      warnings,
+    }
+  }
+
+  // ── mechanics 代算：changedFiles（diff × allowed_paths 归属切片；显式覆盖优先）──
+  const content = readFileSync(taskCardPath, 'utf8')
+  // 跨仓 task 守卫：base/head/changedFiles 的跨仓口径（task 卡锡点 + 跨仓仓 diff）本函数未实现
+  //（草稿生成有专门分支）——显式拒绝并引导既有路径，防主仓锡点被误配到跨仓改动上
+  const guardRepo = normalizeRepoKey(parseRepo(content))
+  if (guardRepo && guardRepo !== 'main') {
+    return {
+      ok: false,
+      errors: [`task 卡声明 repo=${guardRepo}（跨仓 task）——review write 暂不支持跨仓口径，请手写 review.json 后跑 sillyspec backfill-reviews --change ${changeName} --adopt 代填 mechanics（base/head 从 task 卡锡点取）`],
+      warnings,
+    }
+  }
+  const allowedPaths = parseAllowedPaths(content)
+  let changedFiles = null
+  if (Array.isArray(changedFilesOverride)) {
+    // 显式覆盖（含空数组=纯验证任务的合法零 diff 声明）
+    changedFiles = changedFilesOverride.map(p => String(p).replace(/\\/g, '/'))
+    warnings.push(`changedFiles 采用显式覆盖（${changedFiles.length} 个）——evidence 校验仍会与 git diff 相交比对`)
+  } else {
+    let diffFiles = resolveVerifyChangedFiles(cwd, changeName, null, { specBase })
+    // 并入 worktree 未提交改动（与草稿生成同源口径：子代理默认不 commit）
+    try {
+      const wm = new WorktreeManager({ cwd })
+      const meta = wm.getMeta(changeName)
+      if (meta) {
+        const wtGitDir = (meta.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath))
+          ? meta.worktreePath
+          : cwd
+        const wtStatus = runGit(wtGitDir, ['status', '--porcelain', '--untracked-files=all'], { trim: false })
+        const wtFiles = parsePorcelainFiles(wtStatus)
+          .map(p => String(p).replace(/\\/g, '/'))
+          .filter(p => p !== '.sillyspec' && !p.startsWith('.sillyspec/'))
+        if (wtFiles.length > 0) diffFiles = [...new Set([...(Array.isArray(diffFiles) ? diffFiles : []), ...wtFiles])]
+      }
+    } catch { /* 退回 commit diff 口径 */ }
+    const mainDiff = Array.isArray(diffFiles) ? diffFiles : []
+    changedFiles = allowedPaths.length > 0
+      ? mainDiff.filter(f => allowedPaths.some(p => pathMatches(f, p)))
+      : []
+    if (changedFiles.length === 0) {
+      return {
+        ok: false,
+        errors: [
+          `归属切片为空：task 卡 allowed_paths ${JSON.stringify(allowedPaths)} 未命中本次 diff 任何文件。` +
+          `本变更 diff 共 ${mainDiff.length} 个文件：${mainDiff.slice(0, 10).join('、')}${mainDiff.length > 10 ? '…' : ''}。` +
+          `确认改动确属本 task → 用 --changed-files <a,b> 显式给出；纯验证任务（无代码 diff 是本质属性）用 --changed-files ""（空覆盖）+ --evidence 披露验证区间`,
+        ],
+        warnings,
+      }
+    }
+  }
+
+  // ── 组装 + schema 自检 + 落盘 ──
+  const review = {
+    schemaVersion: REVIEW_SCHEMA_VERSION,
+    task: taskId,
+    base,
+    head,
+    changedFiles,
+    ...(allowedPaths.length > 0 ? { diffPaths: allowedPaths } : {}),
+    specVerdict,
+    qualityVerdict,
+    ...(requiredEvidence.filter(Boolean).length > 0 ? { requiredEvidence: requiredEvidence.filter(Boolean) } : {}),
+    reviewerNotes: reviewerNotes || `written by sillyspec review write (${base.slice(0, 8)}..${head.slice(0, 8)})`,
+  }
+  const schemaResult = validateReviewSchema(review)
+  if (!schemaResult.ok) {
+    return { ok: false, errors: schemaResult.errors, warnings }
+  }
+  try {
+    mkdirSync(reviewDir, { recursive: true })
+    writeFileSync(reviewPath, JSON.stringify(review, null, 2) + '\n')
+  } catch (e) {
+    return { ok: false, errors: [`review.json 落盘失败：${e.message}`], warnings }
+  }
+  return { ok: true, reviewPath, executeRunId, errors: [], warnings }
+}
+// 注：跨仓 task（repo≠main）在上方 mechanics 段前置守卫拒绝——review.repo 恒为 main，不再单独赋值
+
 /**
  * 获取当前（或最新）execute run id
  * 从 runtime 目录下查找 execute-runs/ 子目录

package/src/verify-facts-schema.js

@@ -0,0 +1,141 @@
+/**
+ * verify-facts-schema.js — verify-facts.json v2 schema 单点（2026-09-08-ir-verify-facts task-01 / D-005@v2）。
+ *
+ * facts v2 的字段/枚举/豁免形态/路径分类/槽段解析集中于此，builder（verify-probes.buildVerifyFacts）、
+ * 对账引擎（verify-postcheck.runVerifyRequiredEvidenceCheck）、集成证据（change-risk-profile 经
+ * stage-contract）、骨架渲染（generateVerifyResultSkeleton）四方 import 同源，禁复制。
+ *
+ * 双层写入模型（D-001@v2）：机器数据（probes/tests/factsConsistency）CLI 直写；判断层
+ * （结论枚举/证据状态/回执声明）经 verify-result.md 受控槽段录入、--done 时 CLI 解析固化
+ * （slot-backfill），单向渲染约束对象是机器数据。
+ */
+export const FACTS_SCHEMA_VERSION = 2
+
+/** 证据状态枚举单源（「## 证据账」槽行 + facts.requiredEvidence[].status 共用） */
+export const EVIDENCE_STATUS = ['satisfied', 'missing', 'partial']
+
+/** 豁免后缀形态：missing + （豁免：<理由>）——机器可解析，无括注的 missing 不算豁免（模块私有：parseEvidenceSlots 内部消费，外部读解析结果的 exempt 字段） */
+const EXEMPTION_RE = /（豁免：[^）]+）/
+
+/** 证据账槽段标题（与 generateVerifyResultSkeleton 渲染逐字一致——避开既有「## Runtime Evidence」人工判断章） */
+export const EVIDENCE_SLOT_HEADING = '## 证据账（cannot_verify 任务）'
+
+/** 集成验证回执槽段标题 */
+export const RECEIPT_SLOT_HEADING = '## 集成验证回执'
+
+/**
+ * verifiedFiles 路径分类：决定核验口径（design Phase 2）。
+ * artifact 类（.runtime/ 日志 / 文档——resolveVerifyChangedFiles 天然不覆盖）核 存在×mtime，
+ * diff 交集豁免；其余（code）核 存在×mtime×diff 交集。
+ * @param {string} path 仓根相对路径（posix）
+ * @returns {'code'|'artifact'}
+ */
+export function classifyVerifiedFile(path) {
+  const p = String(path || '').replace(/\\/g, '/')
+  if (p.startsWith('.runtime/') || p.startsWith('.sillyspec/.runtime/')) return 'artifact'
+  if (/\.(log|txt|out)$/i.test(p)) return 'artifact'
+  if (p.startsWith('.sillyspec/docs/') || p.startsWith('docs/')) return 'artifact'
+  if (p.endsWith('.md') || p.endsWith('.mdx')) return 'artifact'
+  return 'code'
+}
+
+/** 证据账 task 行：`- task-NN: <status> | verifiedFiles: a, b（豁免：…）`——占位 <待填：*> 不命中（fail-closed） */
+const EVIDENCE_LINE_RE = /^- (task-\d+):\s*(satisfied|missing|partial)\b([^\n]*)$/
+
+/** 回执行：`- claim: … | command: … | exit: 0 | log: path`——四字段行首锚定，占位不命中 */
+const RECEIPT_LINE_RE = /^- claim:\s*([^|]+)\|\s*command:\s*([^|]+)\|\s*exit:\s*(\d+)\s*\|\s*log:\s*([^\s|]+)/
+
+/**
+ * 解析 verify-result.md 的两个受控槽段（D-001@v2 slot-backfill 录入界面）。
+ * 占位形态（<待填：三选一> / <待填：0 或非 0>）不含枚举词，行首锚定 + 枚举词双保险 fail-closed。
+ * @param {string} mdText verify-result.md 全文（LF 归一由调用方 readFileSync 层负责或此处容错）
+ * @returns {{ requiredEvidence: Array<{task,status,exempt:boolean,exemptionReason:string|null,verifiedFiles:string[]}>, runtimeEvidence: Array<{claim,command,exitCode,logPath}>, hasEvidenceSlot: boolean, hasReceiptSlot: boolean }}
+ */
+export function parseEvidenceSlots(mdText) {
+  const text = String(mdText || '').replace(/\r\n/g, '\n')
+  const lines = text.split('\n')
+
+  // 槽段定位：标题行到下一个同级/更高级标题或文末
+  const sectionOf = (heading) => {
+    const start = lines.findIndex(l => l.startsWith(heading))
+    if (start === -1) return null
+    const body = []
+    for (let i = start + 1; i < lines.length; i++) {
+      if (/^#{1,2}\s/.test(lines[i])) break
+      body.push(lines[i])
+    }
+    return body
+  }
+
+  const evidenceBody = sectionOf(EVIDENCE_SLOT_HEADING)
+  const receiptBody = sectionOf(RECEIPT_SLOT_HEADING)
+
+  const requiredEvidence = []
+  if (evidenceBody) {
+    for (const line of evidenceBody) {
+      const m = line.match(EVIDENCE_LINE_RE)
+      if (!m) continue
+      const [, task, status, rest] = m
+      const exemptM = rest.match(EXEMPTION_RE)
+      const vfMatch = rest.match(/verifiedFiles:\s*([^\n（]*)/)
+      const verifiedFiles = (vfMatch ? vfMatch[1] : '')
+        .split(',')
+        .map(s => s.trim().replace(/^`|`$/g, ''))
+        .filter(s => s.length > 0 && !s.startsWith('<'))
+      requiredEvidence.push({
+        task,
+        status,
+        exempt: status === 'missing' && !!exemptM,
+        exemptionReason: exemptM ? exemptM[0] : null,
+        verifiedFiles,
+      })
+    }
+  }
+
+  const runtimeEvidence = []
+  if (receiptBody) {
+    for (const line of receiptBody) {
+      const m = line.match(RECEIPT_LINE_RE)
+      if (!m) continue
+      runtimeEvidence.push({
+        claim: m[1].trim(),
+        command: m[2].trim(),
+        exitCode: Number(m[3]),
+        logPath: m[4].trim().replace(/^`|`$/g, ''),
+      })
+    }
+  }
+
+  return {
+    requiredEvidence,
+    runtimeEvidence,
+    hasEvidenceSlot: evidenceBody !== null,
+    hasReceiptSlot: receiptBody !== null,
+  }
+}
+
+/**
+ * facts v2 结构校验（写入前/消费侧防线）。
+ * @param {object} facts
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateFactsV2(facts) {
+  const errors = []
+  if (!facts || typeof facts !== 'object') return { ok: false, errors: ['facts 非对象'] }
+  if (facts.schemaVersion !== FACTS_SCHEMA_VERSION) {
+    errors.push(`schemaVersion 应为 ${FACTS_SCHEMA_VERSION}，实际 ${facts.schemaVersion}`)
+  }
+  if (!Array.isArray(facts.probes ? Object.keys(facts.probes) : null)) {
+    errors.push('probes 段缺失或非对象')
+  }
+  if (facts.conclusion != null && !['PASS', 'PASS WITH NOTES', 'FAIL'].includes(facts.conclusion)) {
+    errors.push(`conclusion 非法枚举值：${facts.conclusion}`)
+  }
+  for (const item of facts.requiredEvidence || []) {
+    if (!EVIDENCE_STATUS.includes(item.status)) errors.push(`requiredEvidence[${item.task}] status 非法：${item.status}`)
+    if (item.status === 'satisfied' && (!Array.isArray(item.verifiedFiles) || item.verifiedFiles.length === 0)) {
+      errors.push(`requiredEvidence[${item.task}] satisfied 但 verifiedFiles 为空`)
+    }
+  }
+  return { ok: errors.length === 0, errors }
+}