sillyspec 3.29.5 → 3.31.0

package/src/flow-parity.js

@@ -0,0 +1,236 @@
+/**
+ * flow-parity.js — 轻量变更资产对齐三件（2026-09-25-thin-parity-assets，能力/资产对照表终核收口）。
+ *
+ * ① reconcileModuleDocs：模块文档同步对账——厚道 module-impact 死信门的轻量变更等价物（advisory）：
+ *    交付文件命中模块图 → 点名模块与文档路径；模块代码变了而文档未动 → 强提示。模块文档是
+ *    后续变更 module 命中/门禁收窄/知识注入的原料（verify -68% 那笔账的来源），失供是复利折旧。
+ *    （2026-09-27-thin-module-scope-persist：同一计算增加结构化返回面 modules/uncoveredDirs/
+ *    moduleMaps，随 change-patch.json 落盘供平台展示轻量变更影响模块范围。）
+ * ② renderVerifyReceipt：verify-result 机器回执——人类可读收口结论（实测面/评审/绑定/冻结 sha），
+ *    厚道有轻量变更缺的审计资产；机器合成勿手改。
+ * ③ harvestSlot4Decision：design 槽4（风险与死路）实质作答收割合成 decisions.md——轻量变更决策
+ *    产出为零的补口（死路与风险取舍正是 decisions.md 该记的内容；已有文件不覆盖）。
+ */
+import { existsSync, readFileSync, writeFileSync, readdirSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { splitOwnVsForeignDiffFiles } from './foreign-declared.js'
+import { collectModuleMaps, normalizeMapPath } from './module-resolve.js'
+import { writeAtomicSync } from './fs-atomic.js'
+
+/**
+ * 模块文档对账（advisory）+ 结构化落盘面（2026-09-27-thin-module-scope-persist）。
+ * @param cwd 仓库根（子项目前缀判定 + specBase→仓根相对换算）
+ * @param ownFiles 交付文件（posix；.sillyspec/ 治理面内部滤除——模块命中只对账代码交付面，
+ * 否则本变更目录工件会污染未登记清单）
+ * @param committedRaw 含 .sillyspec 的原始提交面（仓根相对——模块文档是否随变更更新以此判定）
+ * @returns {{lines: string[], hits: number,
+ *   modules: Array<{id: string, files: number, doc: string|null, docTouched: boolean, docMissing: boolean}>,
+ *   uncoveredDirs: Array<{dir: string, files: number}>, moduleMaps: string[]}}
+ *   lines 为空=无命中零输出；结构化三键恒在场（无图/零命中=空数组），随 change-patch.json 落盘。
+ * 口径对齐 module-resolve.collectModuleMaps（2026-09-27-thin-module-scope-persist 修复旧实现
+ * 四缺陷：js-yaml 顶层迭代不进 modules: 包层致命中恒 0、字母序取首个项目图致多项目仓读错图、
+ * 子项目 paths 前缀缺失、docTouched 拿 specBase 相对路径比仓根相对 committedRaw 恒 false）。
+ */
+export function reconcileModuleDocs({ cwd, specBase, ownFiles, committedRaw }) {
+  let maps = []
+  try { maps = collectModuleMaps({ cwd: cwd || specBase, specBase }) } catch { maps = [] }
+  if (maps.length === 0) return { lines: [], hits: 0, modules: [], uncoveredDirs: [], moduleMaps: [] }
+  const deliverables = [...new Set((ownFiles || []).map((f) => String(f).replace(/\\/g, '/')))]
+    .filter((f) => !f.startsWith('.sillyspec/'))
+  const committed = new Set((committedRaw || []).map((f) => String(f).replace(/\\/g, '/')))
+  // specBase 相对 → 仓根相对（docTouched 比对基准：committedRaw 是 git diff 仓根相对输出）
+  const specRel = (() => {
+    if (!cwd) return ''
+    try {
+      const r = relative(cwd, specBase).replace(/\\/g, '/')
+      if (!r || r === '.') return ''
+      return r.replace(/\/+$/, '') + '/'
+    } catch { return '' }
+  })()
+  const lines = []
+  const modules = []
+  let hits = 0
+  for (const map of maps) {
+    for (const [modId, entry] of map.entries) {
+      const effs = (entry.paths || [])
+        .map((pp) => (map.prefix + normalizeMapPath(pp)).replace(/\/+$/, ''))
+        .filter(Boolean)
+      if (effs.length === 0) continue
+      const hitFiles = deliverables.filter((f) => effs.some((e) => f === e || f.startsWith(e + '/')))
+      if (hitFiles.length === 0) continue
+      hits++
+      const docRel = entry.doc ? `docs/${map.project}/${String(entry.doc).replace(/^\/+/, '')}` : null
+      const docAbs = docRel ? join(specBase, docRel) : null
+      const docTouched = docRel ? committed.has(specRel + docRel) : false
+      const docMissing = docAbs ? !existsSync(docAbs) : false
+      modules.push({ id: modId, files: hitFiles.length, doc: docRel, docTouched, docMissing })
+      if (docTouched) lines.push(`   ✓ ${modId}（${hitFiles.length} 文件）——文档 ${docRel} 已同步`)
+      else lines.push(`   ⚠️ ${modId}（${hitFiles.length} 文件）——文档${docAbs && existsSync(docAbs) ? ` ${docRel} ` : '（缺失）'}未随变更更新：若行为/接口有变请先补文档（模块文档是后续变更门禁收窄与知识注入的原料）`)
+    }
+  }
+  // 未登记模块目录检测（2026-09-25-thin-fr-quality，R16 实证：observation 新模块不在图 → FR
+  // 落伪域 auto-frontend）：交付目录不在任何模块 paths 下时点名提示登记——首个变更把家建好，
+  // 后续变更的模块命中/门禁收窄/知识注入才能吃到
+  const allPaths = []
+  for (const map of maps) {
+    for (const entry of map.entries.values()) {
+      for (const pp of entry.paths || []) allPaths.push((map.prefix + normalizeMapPath(pp)).replace(/\/+$/, ''))
+    }
+  }
+  const isCovered = (f) => allPaths.some((pp) => pp && (f === pp || f.startsWith(pp + '/')))
+  const uncoveredMap = new Map()
+  for (const f of deliverables) {
+    if (isCovered(f)) continue
+    const dir = String(f).split('/').slice(0, -1).join('/')
+    if (dir) uncoveredMap.set(dir, (uncoveredMap.get(dir) || 0) + 1)
+  }
+  const uncoveredDirs = [...uncoveredMap.entries()].sort((a, b) => b[1] - a[1]).map(([dir, files]) => ({ dir, files }))
+  const topDirs = uncoveredDirs.slice(0, 3)
+  const out = [...lines]
+  if (hits > 0) out.unshift(`📎 模块文档对账（advisory）：交付面命中 ${hits} 个模块——`)
+  if (topDirs.length > 0) {
+    out.push(`🗺️ 未登记模块图的交付目录（${topDirs.map((e) => `${e.dir}（${e.files} 文件）`).join('、')}${uncoveredDirs.length > 3 ? ' 等' : ''}）——本变更的 FR 将落伪域 auto-*`)
+    out.push(`   建议收口前在模块图（docs/<project>/modules/_module-map.yaml）登记模块条目（模块 id + paths 指向目录 + doc），后续变更的模块命中/门禁收窄/知识注入才能吃到`)
+  }
+  return { lines: out, hits, modules, uncoveredDirs, moduleMaps: maps.map((m) => `docs/${m.project}/modules/_module-map.yaml`) }
+}
+
+/**
+ * verify-result 机器回执（归档前合成，随变更目录留档）。
+ */
+export function renderVerifyReceipt({ change, baseline, head, gateSummary, review, traceCount, patchMeta, generatedAt }) {
+  const sha = patchMeta && patchMeta.patchSha256 ? patchMeta.patchSha256.slice(0, 12) : null
+  const reviewLine = review
+    ? review.verdict === 'exempt'
+      ? '豁免（低风险证据齐全' + (review.sampled ? '' : '') + '）'
+      : `${review.verdict}（reviewer 见 review.json${Number.isFinite(review.findingsP1) ? `，P1 ${review.findingsP1}` : ''}）`
+    : '—'
+  const headNote = head && baseline && head === baseline
+    ? '（等于基线——交付代码尚未提交，冻结面以 change.patch 实际内容为准）'
+    : ''
+  return [
+    `---`,
+    `author: flow-machine-draft`,
+    `created_at: ${generatedAt}`,
+    `---`,
+    `# 验证回执（flow）— ${change}`,
+    ``,
+    `- **结论**：PASS（flow done 2/2 协议调用收口）`,
+    `- **基线..收口时 HEAD**：${baseline ? baseline.slice(0, 10) : '?'}..${head ? head.slice(0, 10) : '?'}${headNote}`,
+    `- **实测面**：${gateSummary || '—'}`,
+    `- **独立评审**：${reviewLine}`,
+    `- **测试绑定**：${traceCount > 0 ? `${traceCount} 行（test-trace.json，已随发号提升）` : '0（无锚行）'}`,
+    `- **交付冻结**：${sha ? `change.patch（sha256 ${sha}…）` : '（无冻结件）'}`,
+    `- **生成**：${generatedAt}（机器合成，勿手改；明细见 flow-telemetry.jsonl / change-patch.json）`,
+    ``,
+  ].join('\n')
+}
+
+/**
+ * design 槽4（风险与死路）实质作答收割 → decisions.md（已有不覆盖）。
+ * @returns {{harvested: boolean, reason?: string}}
+ */
+export function harvestSlot4Decision({ changeDir, change }) {
+  const decPath = join(changeDir, 'decisions.md')
+  if (existsSync(decPath)) return { harvested: false, reason: 'decisions.md 已在场（不覆盖）' }
+  let dText
+  try { dText = readFileSync(join(changeDir, 'design.md'), 'utf8') } catch { return { harvested: false, reason: '无 design.md' } }
+  const lines = dText.replace(/\r\n/g, '\n').split('\n')
+  let inSlot = false
+  const buf = []
+  for (const line of lines) {
+    if (/^<!--\s*AGENT:槽4/.test(line)) { inSlot = true; continue }
+    if (inSlot && (/^<!--/.test(line) || /^#{1,6}\s/.test(line))) break
+    if (inSlot) buf.push(line)
+  }
+  const answer = buf.join('\n').trim()
+  if (!answer || /^不适用/.test(answer)) return { harvested: false, reason: '槽4 空/不适用' }
+  const text = [
+    '---',
+    `author: flow-machine-draft`,
+    `created_at: ${new Date().toISOString()}`,
+    '---',
+    `# 决策记录（Decisions）— ${change}`,
+    '',
+    `## D-001@v1: 风险与死路（design 槽4 收割）`,
+    `- 类型：process`,
+    `- 状态：confirmed`,
+    // 类型/状态字段（2026-09-26-slot4-distill-fix）：蒸馏链入选要 status∈{confirmed|accepted|rejected}
+    // 且 type∈七类白名单，字段解析只认 `- 字段：值` 列表行形态——此前收割条目零字段致永不入选，
+    // 「随蒸馏链进 knowledge」断链（thin-agent-tasks 教训留档归档而 knowledge 零落地的实证）。
+    // 槽4 是定案的流程/方法论取舍，process+confirmed 语义成立。
+    `- 答案：${answer.replace(/\s*\n+\s*/g, ' ')}`,
+    // 正文用「答案」标签（同修）：distill 落盘「理由：」行取 entry.answer——此前「- 决策：」非白名单
+    // 字段，正文不随条目进 knowledge（骨架落盘内容丢失）。一行展平（评审 P1 清偿）：字段解析是
+    // 单行契约，多行槽4 作答经 \n 续行会静默丢后续行——收割端压平为单行（空格分隔）保全文。
+    '',
+  ].join('\n')
+  writeAtomicSync(decPath, text)
+  return { harvested: true }
+}
+
+export default { reconcileModuleDocs, renderVerifyReceipt, harvestSlot4Decision, collectFreezeFiles, backfillGateSummary }
+
+/**
+ * patch 冻结面的提交面过滤（2026-09-27-tool-debt-cleanup 抽出为纯函数供单测锁定）：
+ * 非 .sillyspec/ 全留 + 本变更目录（治理工件）+ .sillyspec/docs/ 交付文档（dogfood 模块卡
+ * 是交付物——2026-09-27-gate-docs-cleanup 评审 P2 实证旧口径把已提交模块卡漏出审计 patch）。
+ * 他侧 .sillyspec/changes/**（quicklog/knowledge WIP）仍滤除。反斜杠归一。
+ */
+export function filterCommittedFace(committedRaw, ownPrefix) {
+  return committedRaw
+    .map((f) => String(f).replace(/\\/g, '/'))
+    .filter((p) => !p.startsWith('.sillyspec/') || p.startsWith(ownPrefix) || p.startsWith('.sillyspec/docs/'))
+}
+
+/**
+ * patch 冻结面收集（2026-09-25-thin-r16-patches 修复①，R16 P2：agent 提交晚于 done →
+ * 冻结件只有治理件）。committed 提交面为主；exclusive（会话专属 worktree，调用方按
+ * gate-snapshot 同款判定注入）时未提交 dirty 交付面一并入冻结——独占树内 dirty 全归属本变更；
+ * 共享主仓无法归属 → 不入面只警告（他侧声明的 dirty 连警告都免）。
+ */
+export function collectFreezeFiles({ cwd, specBase, change, committed, exclusive }) {
+  const deliverable = (f) => !String(f).replace(/\\/g, '/').startsWith('.sillyspec/')
+  let dirty = []
+  try {
+    const out = execFileSync('git', ['status', '--porcelain'], { cwd, encoding: 'utf8', timeout: 30000, windowsHide: true })
+    for (const line of String(out).split('\n')) {
+      if (!line || line.length < 4) continue
+      const p = line.slice(3).trim().replace(/^"|"$/g, '')
+      const arrow = p.indexOf(' -> ')
+      const path = (arrow !== -1 ? p.slice(arrow + 4) : p).replace(/\\/g, '/')
+      if (deliverable(path) && !dirty.includes(path)) dirty.push(path)
+    }
+  } catch { /* git 失败零 dirty 面 */ }
+  // 归属切分单点：exclusive（worktree/--freeze-dirty）与共享主仓共用——他侧已声明 dirty 永不入冻
+  // （评审 P2 修复：--freeze-dirty 承诺「非他侧声明」，全量冻入会造成跨变更审计双计；worktree
+  // 下 own 恒为全量，切分无伤）
+  let ownDirty = dirty
+  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 }
+}
+
+/**
+ * 实测面回填（修复③：ledger 子步断点续跑 skip 后回执不失忆）——从 verify-runs 最近
+ * test-result.json（带 change 键）重建摘要；无匹配返回 null。
+ */
+export function backfillGateSummary(runtimeRoot, change) {
+  try {
+    const runsDir = join(runtimeRoot, 'verify-runs')
+    if (!existsSync(runsDir)) return null
+    for (const d of [...readdirSync(runsDir)].sort().reverse()) {
+      const p = join(runsDir, d, 'test-result.json')
+      if (!existsSync(p)) continue
+      let r
+      try { r = JSON.parse(readFileSync(p, 'utf8')) } catch { continue }
+      if (r && r.change === change) {
+        return `test: ${r.status ?? '?'}${r.command ? ` ← ${r.command}` : ''}${typeof r.duration_ms === 'number' ? `（${(r.duration_ms / 1000).toFixed(1)}s）` : ''} 结果：${p}`
+      }
+    }
+  } catch { /* 回填 best-effort */ }
+  return null
+}

package/src/flow-review.js

@@ -0,0 +1,184 @@
+/**
+ * flow-review.js — 轻量变更独立评审（2026-09-25-thin-review-slice）。
+ *
+ * 定档哲学：危险证据累积制，体积/文件数出局（撞实验 F-02 实证——几行 ref 清零的小改是 P1，
+ * 30 文件的改名无风险）。信号五路，任一命中即需评审；缺省要评审、豁免要多证并举：
+ *   ① 高危交付语义词（一票升级，任何信号压不住——唯⑤声明通道 --no-review 显式豁免除外；
+ *      实现即此优先序：--no-review 先判，fr-governance-sweep 头注释清偿）——at-least-once/
+ *      exactly-once/不丢失/
+ *      不重复/串台类承诺是 P1 高发区（R15-F-01 即承诺-实现落差）；
+ *   ② 盲维四问实质作答——设计记录「边界与并发」槽有非「不适用」开头的作答=该维风险面存在
+ *      （作答即信号：没有那个维度就不会写出实质内容；adopted 无槽设计退化为机制词全文扫描）；
+ *   ③ 交付 diff 原语——冻结 patch 里的并发/冲突/游标/取消类原语（物证，不依赖自述）；
+ *   ④ 决策密度——edit_ratio 超阈（amend 改写比例=真实取舍密度的机械代理）；
+ *   ⑤ 声明通道——--review / --no-review 一票（上下文最全的人直接表态）。
+ *
+ * 豁免 ≠ 免责：全信号不命中而豁免的变更按 1/4 定额抽查采样（确定性哈希分桶），采样命中照评
+ * 并进遥测——误豁免率可测量可校准（先例：review-dispatch shadow 影子期 N=10 转正判据）。
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 高危交付语义承诺词（一票升级）。2026-09-25-platform-feedback-batch2 D 收敛：移除「幂等」
+ * （实现手段非交付语义，由 diff 原语面覆盖）；保留的七个词均为面向用户的交付语义承诺。 */
+const PROMISE_RE = /at[- ]least[- ]once|exactly[- ]once|不丢失|不重复|不丢不重|不重不漏|串台/i
+
+/** adopted（头脑风暴预段）design 无槽时的机制词全文扫描（窄表防误报）。 */
+const MECHANISM_RE = /乱序|并发写|竞态|死锁|事务隔离|AbortSignal|多实例串|游标推进/
+
+/** 交付 diff 危险原语（物证面）。 */
+const PRIMITIVE_RE = /asyncio\.(?:Lock|Event|Queue|gather)|threading\.|with_for_update|IntegrityError|ON CONFLICT|AbortSignal|AbortController|signal\.abort|\.rollback\(|since=|\bcursor\b/i
+
+/** 豁免抽查采样：确定性哈希 1/4 定额（SALT 防碰巧连坐，调表需同步核对既有夹具零碰撞）。 */
+const SAMPLE_SALT = 7
+export function sampleBucket(name) {
+  let h = 0
+  for (const ch of String(name || '')) h = (h * 31 + ch.codePointAt(0)) >>> 0
+  return (((h ^ SAMPLE_SALT) >>> 0) % 4) === 0
+}
+
+/** 读 AGENT 槽作答（标记行之后到下一标记/标题之前的非空行拼接）。 */
+function readSlotAnswer(text, markerRe) {
+  const lines = String(text || '').replace(/\r\n/g, '\n').split('\n')
+  let inSlot = false
+  const buf = []
+  for (const line of lines) {
+    if (markerRe.test(line)) { inSlot = true; continue }
+    if (inSlot && (/^<!--/.test(line) || /^#{1,6}\s/.test(line))) break
+    if (inSlot) buf.push(line)
+  }
+  return buf.join('\n').trim()
+}
+
+/** 剥 MACHINE-DRAFT 机器段（design.md 的问题模板自带「串台」等承诺词字样——模板自污染面，
+ * 扫描只看 agent 作答面；proposal/requirements 的机器段承载用户原话不剥）。 */
+function stripMachineSections(text) {
+  return String(text || '')
+    .replace(/<!--\s*MACHINE-DRAFT:[\w.-]+:[0-9a-f]{64}:begin[^\n]*-->[\s\S]*?<!--\s*MACHINE-DRAFT:[\w.-]+:end\s*-->/g, '')
+    .replace(/<!--\s*MACHINE-DRAFT:[\w.-]+:[^\n]*:begin[^\n]*-->[\s\S]*?<!--\s*MACHINE-DRAFT:[\w.-]+:end\s*-->/g, '')
+}
+
+/**
+ * 危险证据定档。@returns {{required: boolean, reasons: string[], exemptEvidence: string[], sampled: boolean}}
+ */
+export function classifyReviewNeed({ changeDir, input = '', patchText = null, editRatio = null, reviewForce = null, change = '' }) {
+  if (reviewForce === true) return { required: true, reasons: ['显式 --review 声明（一票）'], exemptEvidence: [], sampled: false }
+  if (reviewForce === false) return { required: false, reasons: [], exemptEvidence: ['显式 --no-review 声明（一票）'], sampled: false }
+  const reasons = []
+  const exemptEvidence = []
+
+  // ① 承诺词：input + 治理工件全文（design 只扫作答面——机器问题模板含「串台」字样属模板自污染）
+  const texts = [String(input || '')]
+  for (const f of ['proposal.md', 'requirements.md', 'design.md']) {
+    try {
+      const t = readFileSync(join(changeDir, f), 'utf8').replace(/\r\n/g, '\n')
+      texts.push(f === 'design.md' ? stripMachineSections(t) : t)
+    } catch { /* 缺件由 redraft/槽位门兜底 */ }
+  }
+  const all = texts.join('\n')
+  const hit = all.match(PROMISE_RE)
+  if (hit) reasons.push(`高危交付语义承诺词命中「${hit[0]}」（一票升级）`)
+  else exemptEvidence.push('无高危承诺词')
+
+  // ② 盲维四问作答：实质作答=风险面（adopted 无槽退化机制词扫描）
+  try {
+    const dText = readFileSync(join(changeDir, 'design.md'), 'utf8').replace(/\r\n/g, '\n')
+    if (/<!--\s*AGENT:槽3/.test(dText)) {
+      const answer = readSlotAnswer(dText, /^<!--\s*AGENT:槽3/)
+      if (!answer) exemptEvidence.push('盲维四问未作答（将由槽位门拦收）')
+      else if (/^不适用/.test(answer)) exemptEvidence.push('盲维四问自述不适用')
+      else reasons.push('盲维四问有实质作答（存在时序/并发/切换/作用域风险面）')
+    } else if (MECHANISM_RE.test(dText)) {
+      reasons.push('头脑风暴设计含并发/时序类机制词（adopted 扫描）')
+    } else {
+      exemptEvidence.push('adopted 设计无机制词命中')
+    }
+  } catch { /* 无 design → 槽位门/redraft 面兜底 */ }
+
+  // ③ 交付 diff 原语
+  // 分径（fr-governance-sweep 评审 P3 清偿）：null=patch 采集失败（flow.js patch 子步 fail-soft
+  // 的 catch 传 null）≠ 空=真无交付 diff——前者不能作为「纯治理面变更」豁免证据（有真实交付但
+  // patch 恰好失败的变更会凭误标证据整体豁免评审——防线虚焊），改判需评审。
+  if (patchText != null && String(patchText).trim()) {
+    if (PRIMITIVE_RE.test(patchText)) reasons.push('交付 diff 含并发/游标/取消类原语')
+    else exemptEvidence.push('diff 无危险原语')
+  } else if (patchText != null) {
+    exemptEvidence.push('无交付 diff（纯治理面变更）')
+  } else {
+    reasons.push('交付 diff 不可得（patch 留档失败）——豁免证据不成立，需评审')
+  }
+
+  // ④ 决策密度
+  if (typeof editRatio === 'number' && editRatio > 0.5) reasons.push(`决策密度高（edit_ratio=${editRatio}）`)
+  else exemptEvidence.push('决策密度低（无 amend 或未超阈）')
+
+  if (reasons.length > 0) return { required: true, reasons, exemptEvidence, sampled: false }
+  if (sampleBucket(change)) return { required: true, reasons: ['豁免抽查采样（1/4 定额）'], exemptEvidence, sampled: true }
+  return { required: false, reasons, exemptEvidence, sampled: false }
+}
+
+/**
+ * 评审员任务书（flow done 首次命中需评审时打印——agent 起干净上下文子代理执行）。
+ * 材料有界（change.patch 为冻结件；治理工件已含字节帽意识）；请求预算硬帽防失控勘察（R14 教训）。
+ */
+export function renderReviewerTaskbook({ change, changeDir }) {
+  return [
+    `⚖️ 独立评审任务书 — ${change}`,
+    `══════════════════════════════════════`,
+    `【角色】你是独立评审员（干净上下文，未参与实现）——拿承诺对代码，不信自述，零误报标准。`,
+    ``,
+    `【材料（按需 Read，请求预算硬帽 12 次——超帽即止，包不足以作答写 cannot_verify）】`,
+    `  - ${join(changeDir, 'requirements.md')}（FR 承诺 + 每条 FR 的测试绑定作答）`,
+    `  - ${join(changeDir, 'design.md')}（设计承诺：做法/接口契约/盲维四问作答/风险）`,
+    `  - ${join(changeDir, 'change.patch')}（交付 diff 冻结件——代码事实的唯一来源）`,
+    ``,
+    `【检查单（逐条作答，P1=承诺被违反或有数据正确性风险）】`,
+    `  1. FR↔实现↔测试三方一致：每条 FR 的实现兑现承诺？绑定作答声称的测试真存在且断言该行为？`,
+    `  2. 盲维四问真实性：design 作答说「不适用」的维度，diff 代码真的没有该风险面吗？（重点：乱序到达/并发写/切换清理/多工作区作用域）`,
+    `  3. 披露边界显式裁决（必答，不许默认放行——R16 实证：已披露的取舍最易被放行）：design/requirements 里每条**声明的设计边界或取舍**`,
+    `     （如「晚到事件不再重发，是交付语义的显式边界」），逐条写明「可接受/不可接受」+一句理由——`,
+    `     可接受 → dimensionNotes 对应维度写「边界已裁决：可接受」；不可接受 → 按严重度进 findings（P1=数据正确性风险）。`,
+    `     没有任何声明边界时写「无声明边界」。未裁决=未审。`,
+    `  4. 作答中的防护声明（如有）：声称的防护机制在代码里真实存在且生效？`,
+    `  5. 生成物同步（如涉及）：类型/契约文件与实现对齐？`,
+    ``,
+    `【纪律】只读——禁止修改任何文件、禁止 git 操作；唯一产物是 review.json。`,
+    ``,
+    `【产物 schema（写到 ${join(changeDir, 'review.json')}，UTF-8 JSON）】`,
+    `{`,
+    `  "schemaVersion": 1, "change": "${change}", "reviewer": "subagent",`,
+    `  "verdict": "PASS" | "FAIL",`,
+    `  "findings": [ { "severity": "P1|P2|P3", "title": "…", "evidence": "代码锚点+机理一句话", "location": "file:line" } ],`,
+    `  "dimensionNotes": { "乱序": "ok|finding|n/a", "并发": "ok|finding|n/a", "切换": "ok|finding|n/a", "作用域": "ok|finding|n/a" },`,
+    `  "reviewedAt": "<ISO 时间>"`,
+    `}`,
+    ``,
+    `完成后由主会话重跑：sillyspec flow done --change ${change}（断点续，已完成子步幂等跳过）`,
+  ].join('\n')
+}
+
+/**
+ * review.json 校验（三态：ok / schema 错误清单）。FAIL 或含 P1 由调用方拦截。
+ */
+export function validateReviewJson(path) {
+  let raw
+  try { raw = readFileSync(path, 'utf8') } catch { return { ok: false, errors: [`review.json 不可读：${path}`], review: null } }
+  let r
+  try { r = JSON.parse(raw) } catch (e) { return { ok: false, errors: [`review.json 不是合法 JSON：${e.message}`], review: null } }
+  const errors = []
+  if (r.schemaVersion !== 1) errors.push('schemaVersion 必须为 1')
+  if (!['PASS', 'FAIL'].includes(r.verdict)) errors.push('verdict 必须为 PASS|FAIL')
+  if (!Array.isArray(r.findings)) errors.push('findings 必须为数组')
+  else {
+    r.findings.forEach((f, i) => {
+      if (!f || typeof f !== 'object') { errors.push(`findings[${i}] 非对象`); return }
+      if (!/^P[123]$/i.test(String(f.severity || ''))) errors.push(`findings[${i}].severity 必须 P1|P2|P3`)
+      if (!f.title) errors.push(`findings[${i}].title 缺失`)
+    })
+  }
+  if (!r.reviewer || typeof r.reviewer !== 'string') errors.push('reviewer 缺失')
+  if (errors.length > 0) return { ok: false, errors, review: null }
+  return { ok: true, errors: [], review: r }
+}
+
+export default { classifyReviewNeed, renderReviewerTaskbook, validateReviewJson, sampleBucket }