sillyspec 3.27.2 → 3.27.6

package/.worktrees/8d2d0392/src/decision-distill.js

@@ -0,0 +1,517 @@
+/**
+ * decision-distill — 决策提炼纯函数（change: 2026-08-23-adopt-harness-practices，FR-02/03/04，D-007@v1）
+ *
+ * 职责：把变更 decisions.md 中「有实现影响」的决策幂等提炼进 knowledge/decisions/<模块域>.md，
+ * 并幂等维护 knowledge/INDEX.md 的 decisions 路由行。写入责任全部在本模块——task-03（archive
+ * 接线）只调用，task-04（knowledge-match）只消费，本模块不 import 它们（也不接 DB/网络）。
+ *
+ * 入选规则（FR-02，rejected 优先）：任意 type 的 status=rejected → rejected（留痕防复潮）；
+ *   type∈{architecture,compatibility,boundary,definition,process} 且 status∈{confirmed,accepted}
+ *   → implemented；type=scope 与 status=superseded 等其余组合不入选（解析保留在 entries 里）。
+ * 域三级兜底（FR-03）：条目「模块域」字段优先 → 缺失按 impacts 文本中的路径与 _module-map.yaml
+ *   paths/core_files 前缀匹配（moduleIndex 由调用方注入；未注入时按 knowledgeRoot 同级
+ *   docs/<项目>/modules/_module-map.yaml 尽力发现）→ 仍未中归 unmapped 域。
+ * 条目契约（FR-04，provides decisions_entry 八字段）：id/status/anchor/domains/last_confirmed/
+ *   rationale/reject_reason/revisit_when——implemented/rejected 条目逐字落「状态：/锚点：/最近确认：/
+ *   理由：」字段行（rejected 追加「否决理由：/复潮条件：」），domains 由条目所在文件
+ *   decisions/<域>.md 编码（多域 = 条目扇出到多个域文件）。
+ * 幂等：同 ID 同版本重写该条目段落不重复追加；@vN+1 整段替换旧版本段并注 supersedes；旧版本段
+ *   散落在其他域文件时同步移除（同号全局只留最高版本；高版本已落库时迟到的低版本不降级）。
+ * needsWait：rejected 条目缺否决理由/复潮条件 → 该条目不写盘，needsWait 返回缺失描述
+ *   （其余条目照常提炼；步骤层把 needsWait 转 --wait 请用户裁决）。
+ * 零输出：无 decisions.md 或无入选条目 → skipped 带原因，不写任何文件、不动 INDEX。
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/** FR-02：有实现影响的五类 type（scope 与未知 type 的 confirmed/accepted 不入选） */
+const IMPLEMENTED_TYPES = new Set(['architecture', 'compatibility', 'boundary', 'definition', 'process'])
+/** FR-02：implemented 入选的 status（superseded 等其余状态不入选） */
+const IMPLEMENTED_STATUSES = new Set(['confirmed', 'accepted'])
+/** 三级兜底终点域（仍不中归此；域文件由本模块自管） */
+const UNMAPPED_DOMAIN = 'unmapped'
+/** 旧格式容错占位值（FR-01：缺锚点/缺 headHash 不阻断） */
+const NOT_RECORDED = '未记录'
+
+/** 多行/带空白值压成单行字段值（条目行是单行契约） */
+function oneLine(s) {
+  return String(s ?? '').replace(/\s*\r?\n\s*/g, ' ').trim()
+}
+
+/** 取列表字段首 token：`superseded（被 D-005@v2 取代…）` → `superseded` */
+function firstToken(value) {
+  return value.split(/[\s（(]/)[0] || ''
+}
+
+/** 模块域值解析：`[a, b]` / `a、b` / `a b` → ['a','b'] */
+function parseListValue(v) {
+  return v.replace(/^\[/, '').replace(/\]$/, '')
+    .split(/[,，、\s]+/)
+    .map(s => s.trim())
+    .filter(Boolean)
+}
+
+/** 域名净化为安全文件名段（防路径注入；空值归 unmapped） */
+function sanitizeDomain(d) {
+  const s = String(d || '').trim().replace(/\.md$/i, '').replace(/[^A-Za-z0-9_\-\u4e00-\u9fff]/g, '-')
+  return s || UNMAPPED_DOMAIN
+}
+
+/** FR-02 入选裁决：'implemented' | 'rejected' | null（null = 解析保留但不入选） */
+function dispositionOf(entry) {
+  const t = (entry.type || '').toLowerCase()
+  const s = (entry.status || '').toLowerCase()
+  if (s === 'rejected') return 'rejected' // 任意 type（含 scope）的 rejected 都留痕
+  if (IMPLEMENTED_TYPES.has(t) && IMPLEMENTED_STATUSES.has(s)) return 'implemented'
+  return null
+}
+
+/** decisions.md 列表字段标签 → entry 字段（兼容中英标签与中英冒号；其余字段仅留在 raw） */
+function applyField(entry, label, value) {
+  switch (label) {
+    case 'type': entry.type = firstToken(value); break
+    case 'status': entry.status = firstToken(value); break
+    case 'question': case '问题': entry.question = value; break
+    case 'answer': case '答案': entry.answer = value; break
+    case '锚点': case 'anchor': entry.anchor = value; break
+    case '模块域': case '模块': case 'domains': case 'domain': entry.domains = parseListValue(value); break
+    case '否决理由': case 'reject_reason': case 'rejectreason': entry.rejectReason = value; break
+    case '复潮条件': case 'revisit_when': case 'revisitwhen': entry.revisitWhen = value; break
+    case 'supersedes': entry.supersedes = value; break
+    case 'impacts': case '影响': entry.impacts = value; break
+    case 'normalized_requirement': entry.normalizedRequirement = value; break
+    default: break
+  }
+}
+
+/**
+ * 纯函数：解析变更 decisions.md 的 D-xxx@vN 决策条目（FR-01 四字段全可选容旧格式）。
+ * @param {string} changeDir 变更目录（含 decisions.md）
+ * @returns {{ entries: Array<{
+ *   id: string, number: string, version: number, title: string,
+ *   type?: string, status?: string, question?: string, answer?: string,
+ *   anchor?: string, domains?: string[], rejectReason?: string, revisitWhen?: string,
+ *   supersedes?: string, impacts?: string, normalizedRequirement?: string,
+ *   selected: 'implemented'|'rejected'|null, raw: string }>, missing: boolean }}
+ *   missing=true = decisions.md 不存在；selected = FR-02 入选裁决，null 表示解析保留但不入选。
+ */
+export function parseDecisions(changeDir) {
+  const filePath = join(changeDir, 'decisions.md')
+  if (!existsSync(filePath)) return { entries: [], missing: true }
+  let content
+  try { content = readFileSync(filePath, 'utf8') } catch { return { entries: [], missing: true } }
+
+  const entries = []
+  let cur = null
+  const flush = () => {
+    if (!cur) return
+    cur.selected = dispositionOf(cur)
+    cur.raw = cur.rawLines.join('\n')
+    delete cur.rawLines
+    entries.push(cur)
+  }
+  for (const line of content.replace(/\r\n/g, '\n').split('\n')) {
+    const h = line.match(/^##\s+(D-\d+)(?:@v(\d+))?\s*(.*)$/)
+    if (h) {
+      flush()
+      const version = h[2] ? parseInt(h[2], 10) : 1
+      cur = { id: `${h[1]}@v${version}`, number: h[1], version, title: h[3].trim(), rawLines: [line] }
+      continue
+    }
+    if (!cur) continue
+    cur.rawLines.push(line)
+    const f = line.match(/^-\s+([^\s：:]+)\s*[：:]\s*(.*)$/)
+    if (f) applyField(cur, f[1].toLowerCase(), f[2].trim())
+  }
+  flush()
+  return { entries, missing: false }
+}
+
+// ---------------------------------------------------------------------------
+// 域三级兜底（FR-03）
+// ---------------------------------------------------------------------------
+
+/** moduleIndex 形状归一：parseModuleMapSimple 平铺 {id:{paths}} 或包裹 {modules:{id:{paths}}} */
+function normalizeModules(moduleIndex) {
+  if (!moduleIndex) return {}
+  return moduleIndex.modules ? moduleIndex.modules : moduleIndex
+}
+
+/** _module-map.yaml 子集解析（仅模块 id → paths/core_files；不复用 modules.js 以保零依赖纯函数） */
+function parseModulePathsSubset(content) {
+  const modules = {}
+  let cur = null
+  let key = null
+  for (const line of content.replace(/\r\n/g, '\n').split('\n')) {
+    const mm = line.match(/^  ([a-zA-Z0-9_-]+):$/)
+    if (mm) { cur = mm[1]; modules[cur] = { paths: [] }; key = null; continue }
+    if (!cur) continue
+    const inline = line.match(/^    (paths|core_files): \[(.*)\]$/)
+    if (inline) {
+      modules[cur][inline[1]] = inline[2].split(',').map(s => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean)
+      key = null; continue
+    }
+    const block = line.match(/^    (paths|core_files):$/)
+    if (block) { key = block[1]; modules[cur][key] = modules[cur][key] || []; continue }
+    const item = line.match(/^      - (.+)$/)
+    if (item && key) modules[cur][key].push(item[1].trim().replace(/^['"]|['"]$/g, ''))
+  }
+  return modules
+}
+
+/** 未注入 moduleIndex 时的尽力发现：knowledgeRoot 同级 docs/<项目>/modules/_module-map.yaml。
+ * 多子项目仓（如本仓 sillyspec+dashboard）各项目有自己的 map——dogfood 实证（2026-08-24）：
+ * 只取首个命中会把主项目条目全部误落 unmapped（dashboard 的 map 按字母序先命中）。
+ * 改为合并全部项目的 map（同名模块合并 paths/core_files 去重），失败归 null → 全部 unmapped。 */
+function discoverModuleIndex(knowledgeRoot) {
+  try {
+    const docsDir = join(dirname(knowledgeRoot), 'docs')
+    if (!existsSync(docsDir)) return null
+    const merged = {}
+    for (const d of readdirSync(docsDir, { withFileTypes: true })) {
+      if (!d.isDirectory()) continue
+      const mapPath = join(docsDir, d.name, 'modules', '_module-map.yaml')
+      if (!existsSync(mapPath)) continue
+      const sub = parseModulePathsSubset(readFileSync(mapPath, 'utf8'))
+      for (const [id, m] of Object.entries(sub)) {
+        if (!merged[id]) merged[id] = { paths: m.paths || [], core_files: m.core_files || [] }
+        else {
+          merged[id].paths = [...new Set([...(merged[id].paths || []), ...(m.paths || [])])]
+          merged[id].core_files = [...new Set([...(merged[id].core_files || []), ...(m.core_files || [])])]
+        }
+      }
+    }
+    return Object.keys(merged).length > 0 ? merged : null
+  } catch { /* 尽力而为，失败归 null */ }
+  return null
+}
+
+/** impacts 文本中的路径 token：含 / 或带扩展名的词（`src/stages/archive.js、quicklog.js:486` → 前者 + `quicklog.js`） */
+function extractPathTokens(text) {
+  if (!text) return []
+  const tokens = String(text).match(/[A-Za-z0-9_\-.\\/]+/g) || []
+  return tokens
+    .map(t => t.replace(/\\/g, '/').replace(/\/+$/, ''))
+    .filter(t => t && (t.includes('/') || /\.[A-Za-z0-9]+$/.test(t)) && t !== '.' && t !== '..')
+}
+
+/** impacts 路径 token × module paths 前缀匹配（全路径优先，基名兜底——卡内裸文件名引用先例） */
+function matchImpactsToModules(impacts, moduleIndex) {
+  const flat = normalizeModules(moduleIndex)
+  const modPaths = []
+  for (const [id, m] of Object.entries(flat)) {
+    for (const p of [...(m.paths || []), ...(m.core_files || [])]) {
+      const ps = String(p).replace(/\\/g, '/').replace(/\/+$/, '')
+      if (ps) modPaths.push({ id, p: ps })
+    }
+  }
+  const tokens = extractPathTokens(impacts)
+  const hits = []
+  for (const t of tokens) {
+    for (const { id, p } of modPaths) {
+      if (t === p || t.startsWith(p + '/')) { if (!hits.includes(id)) hits.push(id); break }
+    }
+  }
+  if (hits.length === 0) {
+    for (const t of tokens) {
+      const base = t.slice(t.lastIndexOf('/') + 1)
+      for (const { id, p } of modPaths) {
+        if (p.slice(p.lastIndexOf('/') + 1) === base && !hits.includes(id)) hits.push(id)
+      }
+    }
+  }
+  return hits
+}
+
+/** 三级兜底：模块域字段 → impacts × moduleIndex 前缀 → unmapped */
+function resolveDomains(entry, moduleIndex) {
+  if (entry.domains && entry.domains.length > 0) return entry.domains.map(sanitizeDomain)
+  const matched = moduleIndex ? matchImpactsToModules(entry.impacts, moduleIndex) : []
+  if (matched.length > 0) return matched.map(sanitizeDomain)
+  return [UNMAPPED_DOMAIN]
+}
+
+// ---------------------------------------------------------------------------
+// knowledge/decisions/<域>.md 条目读写（FR-04 契约条目，幂等）
+// ---------------------------------------------------------------------------
+
+/** 新域文件头（preamble） */
+function newDomainPreamble(domain) {
+  return [
+    `# 决策知识 — ${domain}`,
+    '',
+    '> decision-distill 从变更 decisions.md 幂等提炼（「最近确认」= 归档时 HEAD）。条目字段行为 docs-check 机械解析契约，勿手改。',
+  ]
+}
+
+/** 单条目段落渲染（design 接口定义的条目格式，逐字对齐：状态/锚点/最近确认/理由 + rejected 专属两行） */
+function renderBlockLines(entry, headHash, supersedesNote) {
+  const lines = [`## ${entry.id} ${oneLine(entry.title)}`.replace(/\s+$/, '')]
+  lines.push(`状态：${entry.selected}`)
+  lines.push(`锚点：${oneLine(entry.anchor) || NOT_RECORDED}`)
+  lines.push(`最近确认：${oneLine(headHash) || NOT_RECORDED}`)
+  lines.push(`理由：${oneLine(entry.answer || entry.normalizedRequirement || entry.question)}`)
+  if (supersedesNote) lines.push(`supersedes：${oneLine(supersedesNote)}`)
+  if (entry.selected === 'rejected') {
+    lines.push(`否决理由：${oneLine(entry.rejectReason)}`)
+    lines.push(`复潮条件：${oneLine(entry.revisitWhen)}`)
+  }
+  return lines
+}
+
+/** 知识文件切段：preamble 行 + D-xxx@vN 条目段（段边界 = 下一 `## D-` 头） */
+function splitKnowledgeSections(content) {
+  const sections = []
+  const preamble = []
+  let cur = null
+  for (const line of content.replace(/\r\n/g, '\n').split('\n')) {
+    const m = line.match(/^## (D-\d+)@v(\d+)\s*(.*)$/)
+    if (m) {
+      if (cur) sections.push(cur)
+      cur = { number: m[1], version: parseInt(m[2], 10), title: m[3].trim(), lines: [line] }
+      continue
+    }
+    if (cur) cur.lines.push(line)
+    else preamble.push(line)
+  }
+  if (cur) sections.push(cur)
+  for (const s of sections) s.id = `${s.number}@v${s.version}`
+  return { preamble, sections }
+}
+
+/** 段落重组落盘文本（幂等归一：段间恰好一个空行 + 文件单一尾换行） */
+function joinKnowledgeFile(preamble, sections) {
+  const parts = []
+  const pre = preamble.join('\n').replace(/\s+$/, '')
+  if (pre) parts.push(pre)
+  for (const s of sections) {
+    const block = s.lines.join('\n').replace(/\s+$/, '')
+    if (block) parts.push(block)
+  }
+  return parts.join('\n\n') + '\n'
+}
+
+/**
+ * 单条目写入一个域文件的段落集（就地修改 sections）。
+ * @returns {{ action: 'append'|'update'|'supersede' }|null} null = 高版本已落库，迟到低版本不降级。
+ */
+function applyEntryToSections(sections, entry, headHash) {
+  const sameNumber = sections.filter(s => s.number === entry.number)
+  if (sameNumber.some(s => s.version > entry.version)) return null
+  let action
+  let supersedesNote = oneLine(entry.supersedes) || null
+  if (sameNumber.length === 0) {
+    sections.push({ number: entry.number, version: entry.version, id: entry.id, title: entry.title, lines: renderBlockLines(entry, headHash, supersedesNote) })
+    action = 'append'
+  } else {
+    const same = sameNumber.find(s => s.version === entry.version)
+    const slot = same || sameNumber[0]
+    if (!same && !supersedesNote) supersedesNote = `${slot.number}@v${slot.version}`
+    slot.version = entry.version
+    slot.title = entry.title
+    slot.lines = renderBlockLines(entry, headHash, supersedesNote)
+    // 同号旧版本段（< 新版本）就地清除——同文件内同号只留一个段
+    for (let i = sections.length - 1; i >= 0; i--) {
+      if (sections[i].number === entry.number && sections[i] !== slot) sections.splice(i, 1)
+    }
+    action = same ? 'update' : 'supersede'
+  }
+  return { action }
+}
+
+// ---------------------------------------------------------------------------
+// INDEX.md decisions 路由行幂等维护（FR-05：写入责任在本模块；只动 ## Decisions 段内指向 decisions/ 的行）
+// ---------------------------------------------------------------------------
+
+/** INDEX 路由行格式与 knowledge-match 解析口径一致：`- <域>|decision|决策 → [decisions/<域>.md](decisions/<域>.md)` */
+function routingLine(domain) {
+  return `- ${domain}|decision|决策 → [decisions/${domain}.md](decisions/${domain}.md)`
+}
+
+const ROUTING_TARGET_RE = /^-\s+.*→\s*\[[^\]]*\]\(decisions\/([^)#]+?)(?:\.md)?(?:#[^)]*)?\)\s*$/
+
+/** 域文件实况 ↔ ## Decisions 段路由行对账：缺行补、失效行删、重复行去重；不动其他类别行 */
+function syncIndexRoutingLines(knowledgeRoot) {
+  const decisionsDir = join(knowledgeRoot, 'decisions')
+  let domains
+  try {
+    domains = readdirSync(decisionsDir).filter(f => f.endsWith('.md')).map(f => f.replace(/\.md$/, ''))
+  } catch { return false }
+  if (domains.length === 0) return false
+
+  const indexPath = join(knowledgeRoot, 'INDEX.md')
+  let original = null
+  if (existsSync(indexPath)) {
+    try { original = readFileSync(indexPath, 'utf8') } catch { return false }
+  }
+  const lines = original ? original.replace(/\r\n/g, '\n').split('\n') : ['# Knowledge Index', '']
+
+  // 定位 ## Decisions 段边界
+  let secStart = -1
+  let secEnd = lines.length
+  for (let i = 0; i < lines.length; i++) {
+    const h = lines[i].match(/^##\s+(.+?)\s*$/)
+    if (!h) continue
+    if (secStart === -1) {
+      if (h[1] === 'Decisions') secStart = i + 1
+    } else { secEnd = i; break }
+  }
+
+  const desired = domains.map(routingLine)
+  if (secStart === -1) {
+    // 无段则追加（保留原文件其余内容）
+    while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop()
+    lines.push('', '## Decisions', ...desired)
+  } else {
+    const body = lines.slice(secStart, secEnd)
+    const kept = []
+    const seen = new Set()
+    const domainSet = new Set(domains)
+    for (const l of body) {
+      const m = l.match(ROUTING_TARGET_RE)
+      if (!m) { kept.push(l); continue } // 非路由行（注释/空行）原样保留
+      // 目标域文件仍存在的路由行原样保留（关键词可能被人工扩充）；失效行（文件已不存在）与重复行删
+      if (domainSet.has(m[1]) && !seen.has(m[1])) { seen.add(m[1]); kept.push(l) }
+    }
+    // 补行插在段尾空行之前（段尾空行是与下一 `## ` 的分隔，新行追加其后会出现行间空洞）
+    const tail = []
+    while (kept.length > 0 && kept[kept.length - 1].trim() === '') tail.unshift(kept.pop())
+    for (const d of desired) {
+      const m = d.match(ROUTING_TARGET_RE)
+      if (m && !seen.has(m[1])) kept.push(d) // 缺行补
+    }
+    kept.push(...tail)
+    const sepNeeded = secEnd < lines.length && kept.length > 0 && kept[kept.length - 1].trim() !== ''
+    lines.splice(secStart, secEnd - secStart, ...kept, ...(sepNeeded ? [''] : []))
+  }
+
+  let next = lines.join('\n').replace(/\n{3,}$/, '\n')
+  if (!next.endsWith('\n')) next += '\n'
+  if (next === original) return false
+  writeFileSync(indexPath, next)
+  return true
+}
+
+// ---------------------------------------------------------------------------
+// IO 入口：提炼（FR-03）
+// ---------------------------------------------------------------------------
+
+/**
+ * 纯函数入口：把 changeDir/decisions.md 的入选决策幂等提炼进 knowledgeRoot/decisions/<域>.md，
+ * 并幂等维护 knowledgeRoot/INDEX.md 的 decisions 路由行（仅在有实际写入时）。
+ * @param {string} changeDir 变更目录（含 decisions.md）
+ * @param {string} knowledgeRoot knowledge 目录（如 <specBase>/knowledge）
+ * @param {string} headHash 归档时 HEAD hash（落「最近确认」；空值容错为 未记录）
+ * @param {object|null} [moduleIndex] 域兜底用模块索引（{modules:{id:{paths,core_files}}} 或平铺形；
+ *   缺省时按 knowledgeRoot 同级 docs/<项目>/modules/_module-map.yaml 尽力发现）
+ * @returns {{ written: Array<{file: string, id: string, action: 'append'|'update'|'supersede'}>,
+ *   skipped: string|null, needsWait: string|null }}
+ *   file 为 knowledgeRoot 相对 POSIX 路径（decisions/<域>.md）；跨文件旧版本移除记
+ *   { file: 所在文件, id: 被替换旧版本, action: 'supersede' }。
+ *   skipped 非空 = 无 decisions.md / 无入选条目（零输出）；needsWait 非空 = 有 rejected 条目
+ *   缺否决理由/复潮条件被拦下（该条目未写盘，其余条目照常提炼）。
+ */
+export function distillIntoKnowledge(changeDir, knowledgeRoot, headHash, moduleIndex = null) {
+  const parsed = parseDecisions(changeDir)
+  if (parsed.missing) {
+    return { written: [], skipped: `decisions.md 不存在（${join(changeDir, 'decisions.md')}），零输出`, needsWait: null }
+  }
+  const selected = parsed.entries.filter(e => e.selected)
+  if (selected.length === 0) {
+    return { written: [], skipped: `无入选条目（解析 ${parsed.entries.length} 条，0 条入选：scope/非五类 type/非 confirmed|accepted|rejected 状态均不入选），零输出`, needsWait: null }
+  }
+
+  // needsWait：rejected 缺否决理由/复潮条件 → 该条目不写盘（其余照常）
+  const waitParts = []
+  const distillable = []
+  for (const e of selected) {
+    if (e.selected === 'rejected' && (!e.rejectReason || !e.revisitWhen)) {
+      const missing = []
+      if (!e.rejectReason) missing.push('否决理由')
+      if (!e.revisitWhen) missing.push('复潮条件')
+      waitParts.push(`${e.id} 缺${missing.join('、')}`)
+    } else {
+      distillable.push(e)
+    }
+  }
+  const needsWait = waitParts.length > 0
+    ? `${waitParts.join('；')}——rejected 条目必填，补齐后重跑提炼`
+    : null
+  if (distillable.length === 0) return { written: [], skipped: null, needsWait }
+
+  // 同批同号只提炼最高可写版本（decisions.md 里 v1+v2 并存时 v1 不先落后清——落了也会被 v2
+  // 整段替换，跳过避免空转写与日志抖动；v2 被 needsWait 拦下时 v1 仍是最高可写版，照常提炼）
+  const highestByNumber = new Map()
+  for (const e of distillable) {
+    const prev = highestByNumber.get(e.number)
+    if (!prev || e.version > prev.version) highestByNumber.set(e.number, e)
+  }
+  const batch = []
+  const taken = new Set()
+  for (const e of distillable) {
+    const keep = highestByNumber.get(e.number)
+    if (keep && !taken.has(e.number)) { taken.add(e.number); batch.push(keep) }
+  }
+
+  const decisionsDir = join(knowledgeRoot, 'decisions')
+  mkdirSync(decisionsDir, { recursive: true })
+  const idx = moduleIndex || discoverModuleIndex(knowledgeRoot)
+
+  // 域文件 store：域 → { preamble, sections, dirty }（按需加载，批量写盘）
+  const store = new Map()
+  const loadDomain = (domain) => {
+    let st = store.get(domain)
+    if (st) return st
+    const p = join(decisionsDir, `${domain}.md`)
+    if (existsSync(p)) {
+      let parsedFile = { preamble: [], sections: [] }
+      try { parsedFile = splitKnowledgeSections(readFileSync(p, 'utf8')) } catch { /* 按新文件处理 */ }
+      st = { ...parsedFile, dirty: false }
+    } else {
+      st = { preamble: newDomainPreamble(domain), sections: [], dirty: false }
+    }
+    store.set(domain, st)
+    return st
+  }
+
+  const written = []
+  const targetSets = new Map() // entry → Set(域)（跨文件清理时排除目标文件）
+  for (const entry of batch) {
+    const domains = resolveDomains(entry, idx)
+    targetSets.set(entry, new Set(domains))
+    for (const d of domains) {
+      const st = loadDomain(d)
+      const res = applyEntryToSections(st.sections, entry, headHash)
+      if (res) {
+        st.dirty = true
+        written.push({ file: `decisions/${d}.md`, id: entry.id, action: res.action })
+      }
+    }
+  }
+
+  // 跨文件清理：同号 ≤ 新版本的旧段散落其他域文件时移除（同号全局只留最高版本/目标文件）
+  let onDisk = []
+  try { onDisk = readdirSync(decisionsDir).filter(f => f.endsWith('.md')).map(f => f.replace(/\.md$/, '')) } catch { /* 刚创建，走 store */ }
+  const allDomains = [...new Set([...onDisk, ...store.keys()])]
+  for (const entry of batch) {
+    const targets = targetSets.get(entry)
+    for (const d of allDomains) {
+      if (targets.has(d)) continue
+      const st = loadDomain(d)
+      const removed = st.sections.filter(s => s.number === entry.number && s.version <= entry.version)
+      if (removed.length === 0) continue
+      st.sections = st.sections.filter(s => !removed.includes(s))
+      st.dirty = true
+      for (const r of removed) written.push({ file: `decisions/${d}.md`, id: r.id, action: 'supersede' })
+    }
+  }
+
+  for (const [domain, st] of store) {
+    if (st.dirty) writeFileSync(join(decisionsDir, `${domain}.md`), joinKnowledgeFile(st.preamble, st.sections))
+  }
+
+  // INDEX 路由行对账（仅在实际有条目写入时；零输出场景不动 INDEX）
+  if (written.length > 0) syncIndexRoutingLines(knowledgeRoot)
+
+  return { written, skipped: null, needsWait }
+}

package/.worktrees/8d2d0392/src/dispatch/backends/local-agent.js

@@ -0,0 +1,155 @@
+/**
+ * Local 后端派发指令模板（task-dispatcher 抽象层）— task-03
+ *
+ * 定位（D-007）：dispatcher **不是 JS 执行体**。本机 Agent tool（Claude Code Task 工具）
+ * 只有 agent 能调，CLI（Node）进程调不了。所以本文件 = **派发指令模板生成器**：
+ * 生成注入 execute prompt 的「派发指令文本」，告诉 agent 如何用本机 Agent tool 启动
+ * 子代理；实际 Agent tool 调用由 agent 执行，本模块不调任何 tool。
+ *
+ * Local 后端 = **默认与降级路径**（D-005），保留现有 buildWavePrompt（src/stages/execute.js）
+ * 的本机 Agent tool 派发行为：每任务一个独立子代理、workdir 强制 = worktreePath、
+ * worker 终态后 SillySpec 对 worktree 工作区 git diff 写 review.json（复用既有
+ * task-review 契约）。SillyHub MCP 不可用 / 未配置 / 路径 A 未落地时全程走此路径，零回归。
+ *
+ * Local 后端**忽略** contract 中的 modelHint / agentProfileHint：本机 Agent tool 不做
+ * 异构模型 / agent 分配，这两字段仅 SillyHub 后端消费。
+ */
+
+/**
+ * Local 后端结果回收约定（worker 终态 → review.json）。
+ *
+ * 抽成独立常量供 strategy.js 在拼接「兜底 / 降级 / SillyHub 回收」段时复用，避免 Local
+ * 与 SillyHub 两份回收文案重复维护（R-07：回收统一走 review.json，屏蔽后端差异）。
+ *
+ * 含 `<runId>` 占位符，使用方按实际 contract.runId 替换（见 renderLocalInstruction）。
+ */
+export const LOCAL_RECYCLE_RULE = `### 回收约定（worker 终态 → review.json）
+
+worker 子代理结束后，**回收不依赖 worker 自报结果，也不依赖 worker git commit**：
+SillySpec 主体（你，调度 agent）对 worktree **工作区**做 git diff，按既有 task-review
+契约写 review.json。
+
+1. 读取该 task 在 worktree 工作区的 git diff（task 开始 → 完成的变更）
+2. 对照 plan.md 与 tasks/task-XX.md 检查实现（不信任 implementer 自报，只看当前 task 的 diff）
+3. 写入 review.json：\`{SPEC_ROOT}/.runtime/execute-runs/<runId>/tasks/task-XX/review.json\`（{SPEC_ROOT} 由 CLI 渲染时替换为主仓绝对路径——调度者 cwd 无论在哪都写主仓 .runtime，不写 worktree 副本）
+4. review.json 写入成功后，该 task 的派发回收完成
+
+review.json 复用既有 task-review 契约（必填字段：schemaVersion / task / base / head /
+changedFiles / specVerdict / qualityVerdict / reviewerNotes / requiredEvidence），不发明
+新契约。回收屏蔽后端差异：无论 Local 还是 SillyHub worker，SillySpec 都自己 diff worktree
+工作区写 review.json。`
+
+/**
+ * @typedef {object} DispatchContract
+ * @property {string}  brief              - 任务目标 + 蓝图路径（注入子代理 prompt）
+ * @property {string}  worktreePath       - SillySpec worktree 绝对路径（子代理 cwd）
+ * @property {string}  branch             - worktree 当前分支
+ * @property {string[]} allowedPaths      - task 边界（子代理 prompt 里声明，SillySpec 侧 assess/apply 校验）
+ * @property {boolean} readOnly           - execute 写模式=false；true=只读 QA（仅读/diff/写 review.json）
+ * @property {string}  [modelHint]        - tasks.md [model:xxx]（Local 忽略，仅 SillyHub 消费）
+ * @property {string}  [agentProfileHint] - agent profile（Local 忽略，仅 SillyHub 消费）
+ * @property {string}  runId              - SillySpec execute-run id（关联 review.json 路径）
+ * @property {string}  [missionId]        - Wave 级 mission id（D-008，SillyHub 专属，Local 忽略）
+ */
+
+/**
+ * 渲染 Local 后端派发指令文本。
+ *
+ * 纯模板生成器：不校验 contract 完整性、不调任何 tool，只把 contract 字段拼成可注入
+ * execute prompt 的中文指令字符串。contract 缺字段时回退到醒目占位符（`<未提供 ...>`），
+ * 让 agent 在 prompt 里一眼看到派发前必须补齐的参数，而非静默产出错位指令。
+ *
+ * @param {DispatchContract} [contract] - 派发契约（见 design.md DispatchContract 接口定义）
+ * @returns {string} 注入 execute prompt 的 Local 后端派发指令文本
+ */
+export function renderLocalInstruction(contract) {
+  const c = contract || {}
+  const worktreePath = c.worktreePath
+  const branch = c.branch
+  const allowedPaths = Array.isArray(c.allowedPaths) ? c.allowedPaths : null
+  const readOnly = !!c.readOnly
+  const brief = c.brief
+  const runId = c.runId
+
+  // 回收约定：替换 <runId> 占位符；runId 缺失保留占位符让 agent 警觉
+  const recycleRule = LOCAL_RECYCLE_RULE.replaceAll(
+    '<runId>',
+    runId ? String(runId) : '<未提供 runId>'
+  )
+
+  const workdirDisplay = worktreePath
+    ? String(worktreePath)
+    : '<未提供 contract.worktreePath — 派发前必须补齐，否则破坏 worktree 隔离>'
+
+  const branchLine = branch
+    ? `- worktree 当前分支：\`${branch}\``
+    : '- worktree 当前分支：未提供（沿用 worktree 检出时的既有分支）'
+
+  const allowedLine = allowedPaths && allowedPaths.length
+    ? `- 本次任务边界（allowedPaths）：${allowedPaths.map(p => `\`${p}\``).join(' / ')}`
+    : '- 本次任务边界（allowedPaths）：未提供，按蓝图 tasks/task-XX.md 的 allowed_paths 为准'
+
+  const briefLine = brief
+    ? String(brief)
+    : '<未提供 contract.brief — 派发前必须补齐任务目标与蓝图路径>'
+
+  const modeLine = readOnly
+    ? '5. **只读模式（readOnly=true）**：本子代理只读 / 审查 / 写 review.json，**不改源码**'
+    : '5. **写模式（readOnly=false）**：按蓝图实现源码（TDD：先读后写 → 写测试 → 写实现）'
+
+  return `### 派发后端：Local（本机 Agent tool）— 默认与降级路径
+
+本指令用**本机 Agent tool**（Claude Code Task 工具）启动子代理执行任务。这是默认与降级
+路径：SillyHub MCP 不可用 / 未配置 / 路径 A 未落地时全程走此路径，派发行为与既有 execute
+波次派发等价（零回归）。
+
+**你的角色是调度者 + 审查者，不要自己写代码。** 每个任务由一个独立子代理执行，同 Wave 内
+可并行启动多个子代理。
+
+### 启动子代理（必须严格遵守）
+
+调用本机 Agent tool（Task 工具）为该 task 启动一个独立子代理，参数结构范例：
+
+\`\`\`json
+{
+  "subagent_type": "general",
+  "workdir": "${workdirDisplay}",
+  "prompt": "在此编写任务描述：任务目标 + 蓝图路径 + 编码铁律（见下方要点）"
+}
+\`\`\`
+
+### workdir 强制必传 = contract.worktreePath（关键）
+
+**workdir 参数是强制必传的，值必须为 \`${workdirDisplay}\`（contract.worktreePath）。**
+
+- **不传 workdir，子代理会在主工作区（主仓库根）而非 worktree 里读写文件**，把改动写到
+  主工作区、**破坏 worktree 隔离**，后续 assess / apply / review.json 全部错位，并可能
+  撞其他并行 agent 的改动。
+${branchLine}
+- 蓝图文件（tasks.md / design.md / tasks/task-XX.md）在主工作区 \`{SPEC_ROOT}/changes/<change>/\`
+  下（{SPEC_ROOT} 由 CLI 渲染时替换为主仓绝对路径），可能不在 worktree 中——**读蓝图用主工作区绝对路径，不要拼接到 worktree 路径下**；
+  写代码必须落在 workdir（worktree）内。
+
+### 子代理 prompt 要点
+
+在子代理 prompt 里写明：
+1. 任务目标（brief）：${briefLine}
+2. 蓝图文件路径（让子代理按需读取详情，不要内联整份蓝图污染上下文）
+3. 编码铁律：先读后写、TDD、不编造方法、只做蓝图里写的事、遵守边界处理规则、不超出 allowedPaths
+4. 如存在模块文档（\`{SPEC_ROOT}/docs/*/modules/\`），按需读取涉及模块的 <module>.md 参考接口约定与数据流（读主仓路径，不读 worktree 副本）
+5. 任务含测试代码时，把下方「测试用例设计」整段复制进子代理 prompt，要求子代理按此设计测试用例
+
+{{include: testcase-design}}
+${modeLine}
+${allowedLine}
+
+### Local 后端忽略的字段（不消费）
+
+本机 Agent tool 不做异构模型 / agent 分配，故 Local 后端**忽略** contract 中的以下字段
+（仅 SillyHub 后端消费，此处列出仅为避免 agent 误把它们塞进 Agent tool 参数）：
+- \`modelHint\` → SillyHub model 映射，Local 不传给本机 Agent tool
+- \`agentProfileHint\` → SillyHub agent_profile_id 映射，Local 不传给本机 Agent tool
+- \`missionId\` → SillyHub「一 Wave 一 mission」概念（D-008），Local 无 mission
+
+${recycleRule}`
+}