sillyspec 3.29.5 → 3.31.0

package/src/knowledge-classify.js

@@ -101,7 +101,7 @@ function resolveKeywords(keywords, title) {
  * @returns {{ start: number, end: number, headingText: string, qlIdPrefix: string|null,
  *             title: string, body: string, text: string }[]}
  */
-function parseUncategorizedEntries(normalizedContent) {
+export function parseUncategorizedEntries(normalizedContent) {
   const lines = normalizedContent.split('\n')
   const boundaryRe = /^#{1,3}\s+\S/
   const entryHeadingRe = /^#{2,3}\s+\S/
@@ -380,3 +380,49 @@ export async function cmdKnowledgeClassify(dir, args, opts = {}) {
     }, result.error)
   }
 }
+
+/**
+ * `sillyspec knowledge inbox` 子命令——知识收件箱按需视图（2026-09-23 知识可见性 quick）。
+ *
+ * 背景：uncategorized 待审条目与 quick 资产尾蒸馏产出此前只落文件、不在聊天面露头，
+ * 用户全程无感（2026-09-23 用户反馈「聊天过程中完全不知道」）。收件箱给出待审清单
+ * （标题 + ql 前缀 + 一行摘要）与基线状态；--json 结构化供面板/脚本消费。纯读零副作用。
+ */
+export async function cmdKnowledgeInbox(dir, args, opts = {}) {
+  const base = opts.specDir || join(dir, '.sillyspec')
+  const knowledgeDir = join(base, 'knowledge')
+  const wantJson = args.includes('--json')
+  const uncPath = join(knowledgeDir, 'uncategorized.md')
+  let entries = []
+  if (existsSync(uncPath)) {
+    entries = parseUncategorizedEntries(readFileSync(uncPath, 'utf8').replace(/\r\n/g, '\n'))
+  }
+  let baseline = null
+  try {
+    const bp = join(base, 'knowledge-baseline')
+    if (existsSync(bp)) {
+      const n = parseInt(readFileSync(bp, 'utf8').trim(), 10)
+      if (Number.isFinite(n) && n >= 0) baseline = n
+    }
+  } catch { /* 基线读失败按未启用 */ }
+  const over = baseline !== null && entries.length > baseline
+  const items = entries.map((e) => ({
+    title: e.title,
+    qlId: e.qlIdPrefix || null,
+    summary: String(e.body || '').replace(/\s+/g, ' ').slice(0, 80),
+  }))
+  if (wantJson) {
+    output(true, { inbox: { count: entries.length, baseline, over, items } })
+    return
+  }
+  if (entries.length === 0) {
+    console.log('📚 知识收件箱：空——uncategorized 无待审条目')
+    return
+  }
+  console.log(`📚 知识收件箱：待审 ${entries.length} 条${baseline !== null ? `（基线 ${baseline}${over ? '，已超 ⚠️' : ''}）` : ''}`)
+  items.forEach((it, i) => {
+    console.log(`  ${i + 1}. 《${it.title}》${it.qlId ? `（${it.qlId}）` : ''}`)
+    if (it.summary) console.log(`     ${it.summary}`)
+  })
+  console.log('   归类：sillyspec knowledge classify --title "…" --file conventions|patterns|known-issues.md')
+}

package/src/knowledge-digest.js

@@ -0,0 +1,162 @@
+/**
+ * knowledge-digest.js — 知识资产治理信号收集器（2026-09-27-knowledge-digest）
+ *
+ * 现状：通用知识走 propose→平台人工合并闭环，规格资产（FR 索引/绑定）全自动入库零人审——
+ * 四类信号沉睡库内无人工出口（R23-full 载体仓收件箱积压 40 条实证）。本模块把沉睡数据
+ * 变结构化摘要：`sillyspec knowledge digest`（人读文本）/ `--json`（平台 RPC 消费）。
+ *
+ * 四信号（阈值内静默、超阈才进摘要——安静即健康态，防仪式化）：
+ *   ① rot 待复核标记：knowledge/fr/*.md 条目内「待复核：」行，按域计数（阈值 100）
+ *   ② 收件箱积压：knowledge/uncategorized.md 的 `## <qlId> | <标题>` 条目（阈值 20）
+ *   ③ 伪域落库：auto-* 域文件条目数 + unmapped 池条目数（阈值 0——伪域本不该增长）
+ *   ④ 绑定路径解析失败：fr/*.md 绑定行经 resolveTestFileRel（与 repair-paths/门禁读侧
+ *      同口径单源）无法自仓根解析（阈值 0）
+ *
+ * 只读扫描，零写入——动作（迁移/清账/repair）由消费方另行执行。
+ */
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { join } from 'path'
+import { readFrBindings, resolveTestFileRel, testAnchorFile } from './test-bindings.js'
+
+/** 伪域判定：auto- 前缀（scaffold 时代机器蒸馏域）或 unmapped 池 */
+const isPseudoDomain = (domain) => /^auto[-_]/.test(domain) || domain === 'unmapped'
+
+/** 交付路径 → 建议域（落域机械改进的建议器，与 indexRequirements 的告警共用单源） */
+export function suggestDomainFromFiles(files) {
+  for (const raw of files || []) {
+    const p = String(raw || '').replace(/\\/g, '/')
+    let m
+    if ((m = /^backend\/app\/modules\/([\w-]+)\//.exec(p))) return m[1] // backend 模块归属最强
+    if ((m = /^sillyhub-daemon\//.exec(p))) return 'daemon'
+    if ((m = /^frontend\//.exec(p))) return 'frontend'
+    if ((m = /^backend\//.exec(p))) return 'backend'
+    if ((m = /^([\w-]+)\/src\//.exec(p))) return m[1]
+    if ((m = /^([\w-]+)\//.exec(p))) return m[1]
+  }
+  return null
+}
+
+/** 条目级解析：fr/<域>.md 的 `## <id> <标题>` 段头与「待复核：」行 */
+function scanFrFile(text) {
+  const entries = []
+  let cur = null
+  for (const line of text.split(/\r?\n/)) {
+    const h = /^## (FR-[\w.-]+-\d+|FR-\d+)\s*(.*)$/.exec(line)
+    if (h) { cur = { id: h[1], needsReview: null }; entries.push(cur); continue }
+    if (cur) {
+      const r = /^待复核：(.+)$/.exec(line)
+      if (r) cur.needsReview = r[1].trim()
+    }
+  }
+  return entries
+}
+
+/**
+ * 收集治理信号（纯函数，只读）。
+ * @returns {{ generated_at: string, healthy: boolean, signals: Array<{kind, level, title, count, detail, suggestion?}>, totals: object }}
+ */
+export function collectKnowledgeDigest({ specBase, projectRoot }) {
+  const knowledgeRoot = join(specBase, 'knowledge')
+  const frDir = join(knowledgeRoot, 'fr')
+  const signals = []
+  const totals = { rot: 0, inbox: 0, pseudo: 0, unresolvedBindings: 0 }
+
+  const rotByDomain = new Map()
+  const pseudoByDomain = new Map()
+  const unresolved = []
+  const frFiles = existsSync(frDir) ? readdirSync(frDir).filter(f => f.endsWith('.md')).sort() : []
+  // unmapped 基线消音（与 fr-index 落库告警同口径）：跨仓历史基线不刷信号，只报增量
+  let unmappedBaseline = 0
+  try {
+    const raw = readFileSync(join(specBase, 'local.yaml'), 'utf8')
+    const m = raw.match(/^fr_unmapped_baseline:\s*(\d+)\s*$/m)
+    if (m) unmappedBaseline = parseInt(m[1], 10)
+  } catch { /* 无 local.yaml = 无基线 */ }
+
+  for (const f of frFiles) {
+    const domain = f.replace(/\.md$/, '')
+    const text = readFileSync(join(frDir, f), 'utf8')
+    const entries = scanFrFile(text)
+    const rot = entries.filter(e => e.needsReview).length
+    if (rot > 0) { rotByDomain.set(domain, rot); totals.rot += rot }
+    if (isPseudoDomain(domain) && entries.length > 0) {
+      // 基线内的 unmapped 池不计（历史跨仓基线，非新增堆积）；auto-* 伪域无基线语义恒计
+      const count = domain === 'unmapped' ? Math.max(0, entries.length - unmappedBaseline) : entries.length
+      if (count > 0) { pseudoByDomain.set(domain, count); totals.pseudo += count }
+    }
+    // 绑定解析失败（与 repair-paths 同口径：先根相对直取，再 resolveTestFileRel）
+    for (const e of entries) {
+      const rows = readFrBindings({ knowledgeRoot, frId: e.id })
+      for (const row of rows) {
+        for (const t of row.tests || []) {
+          // 锚剥离单源（评审 P1 清偿）：testAnchorFile 吃全部分隔形态（#/::/「」/>）——
+          // 手搓 split('#').split('::') 漏「」锚致 7/8 假阳性（目标文件全在场），与 repair-paths 口径对拍实证
+          const filePart = testAnchorFile(String(t))
+          const rel = resolveTestFileRel(filePart, { projectRoot })
+          if (!rel && !existsSync(join(projectRoot, filePart.replace(/\\/g, '/')))) {
+            totals.unresolvedBindings++
+            unresolved.push(`${e.id}:${t}`)
+          }
+        }
+      }
+    }
+  }
+
+  // ② 收件箱（uncategorized.md 的 `## <qlId> | <标题>` 行）
+  let inboxTitles = []
+  const uncPath = join(knowledgeRoot, 'uncategorized.md')
+  if (existsSync(uncPath)) {
+    inboxTitles = readFileSync(uncPath, 'utf8').split(/\r?\n/)
+      .map(l => /^## (.+)$/.exec(l)?.[1]).filter(Boolean)
+    totals.inbox = inboxTitles.length
+  }
+
+  const mk = (kind, level, title, count, detail, suggestion) =>
+    signals.push({ kind, level, title, count, detail, ...(suggestion ? { suggestion } : {}) })
+
+  if (totals.rot > 100) {
+    mk('rot', 'warn', `rot 待复核批量标记（${totals.rot} 条 > 100）`, totals.rot,
+      [...rotByDomain.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([d, n]) => `${d} ${n}`).join('、'),
+      '批量复核：文案漂移类可批量承接，行为类逐条对账')
+  }
+  if (totals.inbox > 20) {
+    mk('inbox', 'warn', `知识收件箱积压（${totals.inbox} 条 > 20）`, totals.inbox,
+      inboxTitles.slice(0, 5).join('；') + (inboxTitles.length > 5 ? ' 等' : ''),
+      'sillyspec knowledge inbox 逐条 classify 清账')
+  }
+  if (totals.pseudo > 0) {
+    mk('pseudo-domain', 'warn', `伪域在库（auto-*/unmapped 共 ${totals.pseudo} 条）`, totals.pseudo,
+      [...pseudoByDomain.entries()].map(([d, n]) => `${d} ${n}`).join('、'),
+      '按 suggestDomainFromFiles 建议迁移域（平台信号卡一键/手工 redomain）')
+  }
+  if (totals.unresolvedBindings > 0) {
+    mk('binding-unresolved', 'warn', `绑定路径解析失败（${totals.unresolvedBindings} 个）`, totals.unresolvedBindings,
+      unresolved.slice(0, 5).join('、') + (unresolved.length > 5 ? ' 等' : ''),
+      'sillyspec tests repair-paths（干跑预览 → --write 归一）')
+  }
+
+  return {
+    generated_at: new Date().toISOString(),
+    healthy: signals.length === 0,
+    signals,
+    totals,
+  }
+}
+
+/** 人读文本渲染（CLI 出口；平台走 --json） */
+export function renderKnowledgeDigestText(d) {
+  const lines = []
+  lines.push(`📬 知识资产治理摘要（${d.generated_at.slice(0, 16).replace('T', ' ')}）`)
+  if (d.healthy) {
+    lines.push('✅ 四类信号全部在阈内（rot/inbox/伪域/坏绑定）——安静即健康态，无需动作')
+  } else {
+    lines.push(`⚠️ ${d.signals.length} 类信号超阈：`)
+    for (const s of d.signals) {
+      lines.push(`  [${s.kind}] ${s.title}`)
+      if (s.detail) lines.push(`     明细：${s.detail}`)
+      if (s.suggestion) lines.push(`     处置：${s.suggestion}`)
+    }
+  }
+  lines.push(`底数：rot 待复核 ${d.totals.rot}｜收件箱 ${d.totals.inbox}｜伪域条目 ${d.totals.pseudo}｜坏绑定 ${d.totals.unresolvedBindings}`)
+  return lines.join('\n')
+}

package/src/knowledge-quicklog.js

@@ -0,0 +1,246 @@
+/**
+ * knowledge-quicklog.js — quicklog 历史检索面（知识可见性导线）
+ *
+ * 缺口（2026-09-21 R5R 实证）：quick 产出（quicklog 条目 + patch）不在任何检索面——
+ * knowledge-match 只扫 INDEX 路由与 decisions；主仓唯一核验过键名的先例
+ * （ql-20260920-007-d0dd）因 linked 变更未归档而 distill 缺席，FR 检索面零覆盖，
+ * 后续三个独立会话全部猜错同一外部键。本模块把 quicklog 历史拉进注入面：
+ * 纯读、fail-open、top-3 一行制——注入的是「发生过什么」的历史事实（条目说的是
+ * 当时做了什么），不是权威断言；消费方要用契约细节按 ql-ID 回源读全文或读代码。
+ *
+ * 与 knowledge-match.js 分工：那边消费 INDEX/decisions（结构化知识），这边消费双信号源——
+ * quicklog/QUICKLOG-*.md（append-only 历史）+ changes/archive/<变更>/flow-state.yaml（flow 族归档
+ * 变更伪条目，2026-09-23 扩源：flow 变更不产生 quicklog 条目，扩源后检索面才看得见）。
+ * 条目头与字段行是 allocateQuicklogEntry
+ * 的机械解析契约：`## ql-<id> | <时间> | <标题>` + `文件：` 段（`- path（注记）` 行）。
+ * run/prompt.js（execute 确认步 + quick step1）与 stages/execute.js（Wave 孪生）两处
+ * 注入点共用本模块——格式等价由 test/knowledge-inject.test.mjs 锁定，改渲染必同步两处。
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
+import { join } from 'path'
+
+const QUICKLOG_ENTRY_RE = /^##\s+(ql-[\w-]+)\s*\|\s*([^|]+)\s*\|\s*(.+)$/
+// 文件注记行：`- path（中文括注）` / `- path(ascii)` / 裸 `- path`（allocateQuicklogEntry
+// 均可产出；path 本身不含空白，故止于首个空白或括号）
+const QUICKLOG_FILE_LINE_RE = /^-\s+([^\s（(]+)/
+// 文件：段结束边界——出现其他字段标签行即收段（状态/需求/根因/方案/结果/审计/关联变更）
+const QUICKLOG_FIELD_RE = /^(状态|关联变更|需求|根因|方案|结果|审计)\s*[：:]/
+
+/**
+ * 解析 quicklog 全量条目——双信号源（资产三小件①，2026-09-23 扩源）：
+ *   ① quicklog/QUICKLOG-*.md（append-only 历史条目，含按日归档的分片文件）；
+ *   ② .sillyspec/changes/archive/<变更>/flow-state.yaml（flow 族归档变更）——flow 变更不产生
+ *      quicklog 条目，检索面此前看不见 flow 变更的知识（与 ql-011 治的病同族）。伪条目
+ *      三料合成：qlId=变更目录名 / date=目录名日期前缀（缺前缀退 flow-state.yaml mtime）/
+ *      title=proposal.md 首个 `# ` 标题行（缺文件退变更名）；solution 恒空、files 恒空。
+ * 双源命中时 quicklog 条目排前（matchQuicklogContext 排序 source 键）。
+ * @param {string} specBase - .sillyspec 根
+ * @returns {{ qlId: string, date: string, title: string, solution: string, files: string[], source: 'quicklog'|'flow' }[]}
+ *   两源都不存在 / 全部不可读 → []（调用方零注入零阻断）
+ */
+export function parseQuicklogEntries(specBase) {
+  return [...parseQuicklogFileEntries(specBase), ...parseFlowArchiveEntries(specBase)]
+}
+
+/** 源①：quicklog/QUICKLOG-*.md 条目解析（原 parseQuicklogEntries 主体，行为不变）。 */
+function parseQuicklogFileEntries(specBase) {
+  const dir = join(specBase, 'quicklog')
+  let files
+  try {
+    files = readdirSync(dir).filter((f) => /^QUICKLOG-.*\.md$/i.test(f))
+  } catch {
+    return []
+  }
+  const entries = []
+  for (const f of files) {
+    let content
+    try {
+      content = readFileSync(join(dir, f), 'utf8')
+    } catch {
+      continue
+    }
+    let cur = null
+    let inFiles = false
+    const flush = () => {
+      if (cur) entries.push(cur)
+      cur = null
+    }
+    for (const line of content.replace(/\r\n/g, '\n').split('\n')) {
+      const h = line.match(QUICKLOG_ENTRY_RE)
+      if (h) {
+        flush()
+        cur = { qlId: h[1].trim(), date: h[2].trim(), title: h[3].trim(), solution: '', files: [], source: 'quicklog' }
+        inFiles = false
+        continue
+      }
+      if (!cur) continue
+      if (QUICKLOG_FIELD_RE.test(line)) {
+        inFiles = false
+        const m = line.match(/^方案\s*[：:]\s*(.*)$/)
+        if (m) cur.solution = m[1].trim()
+        continue
+      }
+      if (/^文件\s*[：:]/.test(line)) {
+        inFiles = true
+        continue
+      }
+      if (inFiles) {
+        const m = line.match(QUICKLOG_FILE_LINE_RE)
+        if (m) cur.files.push(m[1].replace(/\\/g, '/'))
+      }
+    }
+    flush()
+  }
+  return entries
+}
+
+/** 源②：flow 归档变更伪条目——目录内 flow-state.yaml 在场即认（不校验 yaml 内容：伪条目
+ * 只需「这曾是一个 flow 变更」的存在信号，字段全来自目录名与 proposal.md，缺件逐项降级）。 */
+function parseFlowArchiveEntries(specBase) {
+  const archiveDir = join(specBase, 'changes', 'archive')
+  let dirs
+  try {
+    dirs = readdirSync(archiveDir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const out = []
+  for (const d of dirs) {
+    if (!d.isDirectory()) continue
+    try {
+      const dir = join(archiveDir, d.name)
+      if (!existsSync(join(dir, 'flow-state.yaml'))) continue
+      const dm = d.name.match(/^(\d{4}-\d{2}-\d{2})-/)
+      let date = dm ? dm[1] : ''
+      if (!date) {
+        try { date = new Date(statSync(join(dir, 'flow-state.yaml')).mtime).toISOString().slice(0, 10) } catch { /* mtime 不可得 → 空日期（排序自然靠后） */ }
+      }
+      let title = ''
+      try {
+        const prop = readFileSync(join(dir, 'proposal.md'), 'utf8')
+        const h = prop.replace(/\r\n/g, '\n').split('\n').find((l) => /^#\s+/.test(l))
+        if (h) title = h.replace(/^#\s+/, '').trim()
+      } catch { /* 无 proposal.md → 标题退变更名 */ }
+      out.push({ qlId: d.name, date, title: title || d.name, solution: '', files: [], source: 'flow' })
+    } catch { /* 单目录读取异常 → 跳过该目录（fail-open，不影响其余源） */ }
+  }
+  return out
+}
+
+// ── 匹配打分 ─────────────────────────────────────────────────────────────────
+// 查询侧 token：ASCII 词（≥3 字符，词边界匹配）+ CJK 连续段（≥2 字，子串匹配）——
+// 与 knowledge-match.keywordMatchesContext 同判法，方向相反（那边条目出关键词查上下文，
+// 这边上下文出 token 查条目——quicklog 条目没有 INDEX 关键词行，只能反向）。
+const ASCII_TOKEN_RE = /[a-z][a-z0-9._-]{2,}/g
+const CJK_RUN_RE = /[\u4e00-\u9fff]{2,}/g
+
+function contextTokens(taskContext) {
+  const s = String(taskContext || '').toLowerCase()
+  const out = new Set()
+  for (const t of s.match(ASCII_TOKEN_RE) || []) out.add(t)
+  for (const t of s.match(CJK_RUN_RE) || []) out.add(t)
+  return [...out]
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/** 文件命中权重：路径/文件名是强信号（同一文件被改过 ≈ 同域修补） */
+const FILE_HIT_WEIGHT = 5
+/** 命中门槛：≥1 文件命中，或 ≥2 个不同 token 命中（单 token 命中多为噪音词，不注入） */
+const MIN_TOKEN_HITS = 2
+
+/** 源排序权重：quicklog 条目 0（排前），flow 伪条目 1——双源命中时 quicklog 优先（更新鲜）。 */
+function sourceRank(entry) {
+  return entry && entry.source === 'flow' ? 1 : 0
+}
+
+/**
+ * 任务上下文 × quicklog 条目匹配（双源条目统一打分，排序 source 键优先）。
+ * @param {string} specBase - .sillyspec 根
+ * @param {string} taskContext - 任务描述串（与 matchKnowledge 的 query 同源）
+ * @param {{ limit?: number }} [opts] - 注入上限（默认 3）
+ * @returns {{ hits: Array<{ qlId: string, date: string, title: string, files: string[] }>, report: string }}
+ *   无 quicklog / 无命中 / 任何异常 → { hits: [], report: '' }（fail-open，永不抛）
+ */
+export function matchQuicklogContext(specBase, taskContext, { limit = 3 } = {}) {
+  try {
+    if (!specBase || !taskContext) return { hits: [], report: '' }
+    const entries = parseQuicklogEntries(specBase)
+    if (entries.length === 0) return { hits: [], report: '' }
+    const tokens = contextTokens(taskContext)
+    if (tokens.length === 0) return { hits: [], report: '' }
+
+    const scored = []
+    for (const e of entries) {
+      const hay = [e.title, e.solution, e.files.join(' ')].join(' ').toLowerCase()
+      const basenames = new Set(e.files.map((f) => f.split('/').pop().toLowerCase()))
+      let score = 0
+      let tokenHits = 0
+      let fileHit = 0
+      for (const t of tokens) {
+        let hit = false
+        if (/[^\x00-\x7f]/.test(t)) {
+          hit = hay.includes(t)
+        } else {
+          hit = new RegExp(`(^|[^a-z0-9])${escapeRegex(t)}([^a-z0-9]|$)`).test(hay)
+          if (!hit && t.length >= 4) {
+            for (const b of basenames) {
+              if (b.includes(t)) {
+                hit = true
+                fileHit++
+                score += FILE_HIT_WEIGHT
+                break
+              }
+            }
+          }
+        }
+        if (hit) {
+          score += 1
+          tokenHits++
+        }
+      }
+      if (fileHit >= 1 || tokenHits >= MIN_TOKEN_HITS) {
+        scored.push({ entry: e, score, fileHit })
+      }
+    }
+    scored.sort((a, b) =>
+      (sourceRank(a.entry) - sourceRank(b.entry)) ||
+      (b.fileHit - a.fileHit) ||
+      (b.score - a.score) ||
+      String(b.entry.date).localeCompare(String(a.entry.date))
+    )
+    const top = scored.slice(0, Math.max(1, limit)).map((s) => ({
+      qlId: s.entry.qlId,
+      date: String(s.entry.date).slice(0, 10),
+      title: s.entry.title,
+      files: s.entry.files,
+    }))
+    return { hits: top, report: renderQuicklogSection(top) }
+  } catch {
+    return { hits: [], report: '' }
+  }
+}
+
+/**
+ * 注入段渲染（prompt.js 与 execute.js 孪生共用——仅段头层级不同）。
+ * 一行一条：ql-ID · 标题（截 60）· 日期 · 至多 2 个触碰文件。零正文注入——
+ * quicklog 条目正文可能很长，注入面只做「知道有这回事 + 回源指针」。
+ * @param {Array<{qlId,date,title,files}>} hits
+ * @param {{ h3?: boolean }} [opts] - execute.js Wave prompt 内用 h3（### ）对齐知识段层级
+ */
+export function renderQuicklogSection(hits, { h3 = false } = {}) {
+  if (!Array.isArray(hits) || hits.length === 0) return ''
+  const lines = [
+    `${h3 ? '### ' : ''}🕘 近期 quick 修补（quicklog 机械匹配，top-${hits.length}——历史记录非权威断言，细节按 ql-ID 回源 .sillyspec/quicklog/ 或读代码）`,
+  ]
+  for (const h of hits) {
+    const files = (h.files || []).slice(0, 2).join(', ')
+    const title = String(h.title || '').slice(0, 60)
+    const date = String(h.date || '').slice(0, 10)
+    lines.push(` - ${h.qlId} · ${title} · ${date}${files ? ` · ${files}` : ''}`)
+  }
+  return lines.join('\n')
+}

package/src/machine-draft.js

@@ -0,0 +1,128 @@
+/**
+ * machine-draft.js — MACHINE-DRAFT 指纹三件套泛化（R7 切片三 task-04 / D-004 / FR-08）。
+ *
+ * 从 verify-draft.js（verify 填槽制 v2 件二）抽出通用原语，供 flow 四件机器稿（flow-draft）
+ * 复用；verify-draft 改为消费方（导出签名与行为逐字不动，零回归硬门）。
+ *
+ * 三件套语义（护栏#2：守卫必须是验收侧的机制，永远不是生成侧的劝说）：
+ *   - wrapSection：机器预填段以 MACHINE-DRAFT begin/end 注释对包裹，begin 内嵌段内容
+ *     sha256（CRLF 归一）；amendCmd 按消费方参数化（verify-result 指向 verify-probes
+ *     --amend-draft，flow 稿指向 flow amend-draft——勿把 agent 引向错误命令）；
+ *   - verifyMarkers：三态拒收判定——标记缺失（被删/整份重写）/内容哈希失配（改写）/
+ *     手工重锚未审计（标记哈希与台账不一致）；
+ *   - reanchorText：按当前内容重锚哈希的纯文本变换（amend 留痕通道的机械半边；
+ *     台账审计与落盘归消费方）。
+ *
+ * 本模块纯函数（无 fs）——md 文本与台账对象由消费方读写；段 key 命名空间归消费方
+ * （verify-result 单文件段键 / flow 按文件名+段键组合）。
+ */
+import { createHash } from 'node:crypto'
+
+export const MARK_BEGIN_RE = /^<!--\s*MACHINE-DRAFT:([\w.-]+):([0-9a-f]{64}):begin.*-->\s*$/
+const MARK_END_RE = /^<!--\s*MACHINE-DRAFT:([\w.-]+):end.*-->\s*$/
+
+/**
+ * 任务勾选态归一（2026-09-25-thin-done-gate-calibration 坑1）：勾选是 flow start 横幅教的
+ * 预期写面（收口哨兵的证据面），不该参与「被改写」判定——哈希前把 `- [x] task-NN` 归一回
+ * `- [ ]`（draft 产出恒 [ ]，存量台账两侧归一后同哈希，兼容；真实改写任务文本/增删行仍失配）。
+ * 口径只认 task-NN 行，普通清单勾选行不归一（不扩大书写面）。
+ */
+const TASK_CHECK_STATE_RE = /^([-*] \[)[ xX]\](?= task-\d)/gm
+function normalizeTaskCheckboxState(s) {
+  return String(s).replace(TASK_CHECK_STATE_RE, '$1 ]')
+}
+
+/** 段内容哈希（CRLF 归一——跨平台写盘行尾漂移不炸指纹；task-NN 勾选态归一——见上）。 */
+export function bodyHash(s) {
+  return createHash('sha256').update(normalizeTaskCheckboxState(String(s).replace(/\r\n/g, '\n'))).digest('hex')
+}
+
+/**
+ * 包裹机器段（begin 标记 + body + end 标记 + 尾空行）。标记格式与既有 MARK_*_RE 逐字兼容。
+ * @returns {string} 四行块（含尾空行，消费方按原位替换）
+ */
+export function wrapSection({ key, body, amendCmd, guardNote = '整段改写会被 verify --done 拒收' }) {
+  return [
+    `<!-- MACHINE-DRAFT:${key}:${bodyHash(body)}:begin 机器预填段——${guardNote}；确要修改：${amendCmd} 留痕重锚 -->`,
+    body,
+    `<!-- MACHINE-DRAFT:${key}:end -->`,
+    '',
+  ].join('\n')
+}
+
+/**
+ * 解析 md 中全部标记段（CRLF 归一）。
+ * @returns {{key:string, markerHash:string, contentLines:string[]}[]}
+ */
+export function parseMarkerBlocks(text) {
+  const lines = String(text).replace(/\r\n/g, '\n').split('\n')
+  const blocks = []
+  let current = null
+  for (const line of lines) {
+    const b = line.match(MARK_BEGIN_RE)
+    if (b) { current = { key: b[1], markerHash: b[2], contentLines: [] }; blocks.push(current); continue }
+    const e = line.match(MARK_END_RE)
+    if (e) { current = null; continue }
+    if (current) current.contentLines.push(line)
+  }
+  return blocks
+}
+
+/**
+ * 三态拒收判定（--done 验收侧承重件的纯函数半边）。
+ * @param {object} p
+ * @param {string} p.text md 全文
+ * @param {Object<string,{hash:string}>} p.sections 台账段哈希（sidecar.sections 形态）
+ * @param {string} p.amendCmd 修复指引命令文案（消费方参数化）
+ * @returns {string[]} violations（空=干净；文案含修复指引）
+ */
+export function verifyMarkers({ text, sections, amendCmd }) {
+  const blocks = parseMarkerBlocks(text)
+  const byKey = new Map(blocks.map((b) => [b.key, b]))
+  const violations = []
+  const fix = (key) => `还原机器段原文，或确要修改时跑 ${amendCmd} 留痕重锚（段键 ${key}）`
+  for (const [key, rec] of Object.entries(sections || {})) {
+    const b = byKey.get(key)
+    if (!b) {
+      violations.push(`机器段「${key}」的 MACHINE-DRAFT 标记缺失（被删除或整份重写）——${fix(key)}`)
+      continue
+    }
+    const actual = bodyHash(b.contentLines.join('\n'))
+    if (actual !== rec.hash) {
+      violations.push(`机器段「${key}」内容与指纹失配（被改写）——${fix(key)}`)
+    } else if (b.markerHash !== rec.hash) {
+      // 内容未动但标记哈希与台账不一致 = 标记被手工重锚而未经 amend 审计
+      violations.push(`机器段「${key}」标记指纹与 sidecar 台账不一致（未经 --amend-draft 的手工重锚）——${fix(key)}`)
+    }
+  }
+  return violations
+}
+
+/**
+ * 按当前内容重锚全部标记段（纯文本变换；不落盘不记台账——消费方持 mdPath/台账）。
+ * @returns {{text:string, keys:string[], contentByKey:Object<string,string>}}
+ */
+export function reanchorText({ text, amendCmd, guardNote = '整段改写会被 verify --done 拒收' }) {
+  const lines = String(text).replace(/\r\n/g, '\n').split('\n')
+  const contentLinesByKey = new Map()
+  let current = null
+  for (const line of lines) {
+    const b = line.match(MARK_BEGIN_RE)
+    if (b) { current = b[1]; contentLinesByKey.set(current, []); continue }
+    const e = line.match(MARK_END_RE)
+    if (e) { current = null; continue }
+    if (current) contentLinesByKey.get(current).push(line)
+  }
+  const keys = [...contentLinesByKey.keys()]
+  const next = lines.map((line) => {
+    const b = line.match(MARK_BEGIN_RE)
+    if (!b) return line
+    const content = (contentLinesByKey.get(b[1]) || []).join('\n')
+    return `<!-- MACHINE-DRAFT:${b[1]}:${bodyHash(content)}:begin 机器预填段——${guardNote}；确要修改：${amendCmd} 留痕重锚 -->`
+  }).join('\n')
+  const contentByKey = {}
+  for (const k of keys) contentByKey[k] = (contentLinesByKey.get(k) || []).join('\n')
+  return { text: next, keys, contentByKey }
+}
+
+export default { wrapSection, parseMarkerBlocks, verifyMarkers, reanchorText, bodyHash, MARK_BEGIN_RE }