sillyspec 3.27.2 → 3.27.6

package/src/knowledge-match.js

@@ -1,6 +1,10 @@
 /**
  * knowledge-match.js — knowledge 关键词匹配引擎
- * 从 INDEX.md 解析知识条目，按任务上下文匹配并生成 hit report
+ * 从 INDEX.md 解析知识条目，按任务上下文匹配并生成 hit report；
+ * 扫描范围含 decisions 决策库（knowledge/decisions/<域>.md，经 INDEX.md ## Decisions 段
+ * 路由行发现——路由行由 decision-distill 幂等写入，本引擎只消费不写）——命中路由行的
+ * 决策文件解析为 decisionHits（rejected 优先），供 brainstorm Step2 防复潮注入（task-04，FR-05）。
+ * decisions 库不存在时（INDEX 无 Decisions 段/文件不存在）一切行为与无 decisions 库时一致。
  */
 
 import { existsSync, readFileSync } from 'fs'
@@ -41,6 +45,86 @@ export function parseKnowledgeIndex(indexDir) {
   return entries
 }
 
+// ---------------------------------------------------------------------------
+// decisions 决策库扫描（task-04，FR-05）：经 INDEX.md ## Decisions 段路由行发现
+// knowledge/decisions/<域>.md 并解析 D-xxx@vN 条目。条目格式与 decision-distill 的
+// renderBlockLines 逐字对齐（字段行是机械解析契约）：`## D-xxx@vN <短标题>` +
+// `状态：implemented|rejected` / `锚点：` / `最近确认：` / `理由：`（rejected 追加
+// `否决理由：` / `复潮条件：`）。
+// ---------------------------------------------------------------------------
+
+/** INDEX 条目是否为 decisions 库路由行（目标文件在 decisions/ 下） */
+function isDecisionRoute(entry) {
+  return /^decisions\//.test(String(entry.file || '').replace(/\\/g, '/'))
+}
+
+const DECISION_HEADER_RE = /^##\s+(D-\d+@v\d+)\s*(.*)$/
+const DECISION_FIELD_RE = /^(状态|理由|否决理由|复潮条件)\s*[：:]\s*(.*)$/
+
+/**
+ * 解析单个 decisions/<域>.md 的 D-xxx@vN 条目。
+ * reason 语义：rejected 条目取「否决理由」（expects_from task-02 的 reject_reason），
+ * 其余条目回退「理由」一句话；revisitWhen 仅 rejected 条目非空（复潮条件）。
+ * @param {string} filePath 决策文件绝对路径
+ * @param {string} file INDEX 相对路径（decisions/<域>.md），原样进 decisionHits.file
+ * @returns {{ file: string, id: string, title: string, status: string, reason: string, revisitWhen: string }[]}
+ */
+function parseDecisionFile(filePath, file) {
+  let content
+  try { content = readFileSync(filePath, 'utf8') } catch { return [] }
+  const hits = []
+  let cur = null
+  const flush = () => {
+    if (cur) hits.push(cur)
+    cur = null
+  }
+  for (const line of content.replace(/\r\n/g, '\n').split('\n')) {
+    const h = line.match(DECISION_HEADER_RE)
+    if (h) {
+      flush()
+      cur = { file, id: h[1], title: h[2].trim(), status: '', reason: '', revisitWhen: '' }
+      continue
+    }
+    if (!cur) continue
+    const f = line.match(DECISION_FIELD_RE)
+    if (!f) continue
+    const value = f[2].trim()
+    if (f[1] === '状态') cur.status = value.toLowerCase()
+    else if (f[1] === '否决理由') cur.reason = value
+    else if (f[1] === '复潮条件') cur.revisitWhen = value
+    else if (!cur.reason) cur.reason = value // 理由：仅作 implemented（或否决理由缺失）时的回填
+  }
+  flush()
+  return hits
+}
+
+/**
+ * 解析 knowledge/decisions/ 决策库——扫描范围扩到 decisions/*.md，但只经 INDEX.md
+ * Decisions 段路由行发现目标文件（路由行由 decision-distill 幂等维护）。
+ * @param {string} indexDir knowledge 目录路径
+ * @param {Array} [indexEntries] parseKnowledgeIndex 输出（缺省时自行解析 INDEX；传入时
+ *   只解析这些条目中指向 decisions/ 的路由行，matchKnowledge 用它做「路由行已命中」过滤）
+ * @returns {{ file: string, id: string, title: string, status: string, reason: string, revisitWhen: string }[]}
+ *   路由行不存在/目标文件不存在/解析失败 → []（与无 decisions 库时行为完全一致）
+ */
+export function parseDecisionEntries(indexDir, indexEntries = null) {
+  const routes = (indexEntries || parseKnowledgeIndex(indexDir)).filter(isDecisionRoute)
+  const hits = []
+  for (const route of routes) {
+    const filePath = join(indexDir, route.file)
+    if (!existsSync(filePath)) continue // 路由行失效（域文件已删）→ 跳过不阻断
+    hits.push(...parseDecisionFile(filePath, route.file))
+  }
+  // 多条路由行指向同一域文件时按 file+id 去重
+  const seen = new Set()
+  return hits.filter(h => {
+    const key = `${h.file}#${h.id}`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+}
+
 function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
@@ -62,7 +146,11 @@ function keywordMatchesContext(keyword, contextLower) {
  * 用任务上下文匹配知识条目
  * @param {string} indexDir - knowledge 目录路径
  * @param {string} taskContext - 任务上下文（task 名称 + 描述，用于关键词匹配）
- * @returns {{ matched: boolean, entries: Array, report: string, json: object }}
+ * @returns {{ matched: boolean, entries: Array, report: string, json: object,
+ *   decisionHits: Array<{ file: string, id: string, title: string, status: string, reason: string, revisitWhen: string }> }}
+ *   matched/entries/report/json 既有四字段结构与语义不变；decisionHits（task-04 新增）= 任务上下文
+ *   命中的 Decisions 路由行所指向 decisions/<域>.md 内的全部 D-xxx@vN 条目，rejected 优先排序；
+ *   无 decisions 库 / 路由行未命中 → decisionHits: []（其余字段行为与现状一致）。
  */
 export function matchKnowledge(indexDir, taskContext) {
   const indexPath = join(indexDir, 'INDEX.md')
@@ -73,7 +161,8 @@ export function matchKnowledge(indexDir, taskContext) {
       matched: false,
       entries: [],
       report: 'Status: no matches (INDEX.md not found)',
-      json: { matched: false, entry_count: 0, entries: [] }
+      json: { matched: false, entry_count: 0, entries: [] },
+      decisionHits: []
     }
   }
 
@@ -83,7 +172,8 @@ export function matchKnowledge(indexDir, taskContext) {
       matched: false,
       entries: [],
       report: 'Status: no matches',
-      json: { matched: false, entry_count: 0, entries: [] }
+      json: { matched: false, entry_count: 0, entries: [] },
+      decisionHits: []
     }
   }
 
@@ -97,7 +187,8 @@ export function matchKnowledge(indexDir, taskContext) {
       matched: false,
       entries: [],
       report: 'Status: no matches',
-      json: { matched: false, entry_count: 0, entries: [] }
+      json: { matched: false, entry_count: 0, entries: [] },
+      decisionHits: []
     }
   }
 
@@ -126,5 +217,15 @@ export function matchKnowledge(indexDir, taskContext) {
     }))
   }
 
-  return { matched: true, entries: matched, report, json }
+  // decisionHits（task-04）：任务上下文命中的 Decisions 路由行 → 解析其指向的
+  // decisions/<域>.md 内全部条目；rejected 优先排序（防复潮信息最先可见，组内保持文件序）。
+  // 不引入新顶层 hits 字段，不改 matched/entries/report/json 四个既有键。
+  const decisionRoutes = matched.filter(isDecisionRoute)
+  const allDecisionHits = decisionRoutes.length > 0 ? parseDecisionEntries(indexDir, decisionRoutes) : []
+  const decisionHits = [
+    ...allDecisionHits.filter(h => h.status === 'rejected'),
+    ...allDecisionHits.filter(h => h.status !== 'rejected')
+  ]
+
+  return { matched: true, entries: matched, report, json, decisionHits }
 }

package/src/local-register.js

@@ -44,7 +44,9 @@ export function registerRepoInLocalYaml(yamlPath, key, repoPath) {
 
   const existed = existsSync(yamlPath)
   // CRLF 归一后按 LF 写回（同 task 卡锚点写入的 CRLF 坑；local.yaml 各 CLI 写入口径均 LF）
-  const raw = existed ? readFileSync(yamlPath, 'utf8').replace(/\r\n?/g, '\n') : ''
+  const raw0 = existed ? readFileSync(yamlPath, 'utf8') : ''
+  const hadCr = raw0.includes('\r') // 磁盘原文带 CRLF → 幂等路径也要落盘治愈（见下方幂等分支）
+  const raw = existed ? raw0.replace(/\r\n?/g, '\n') : ''
   const posixPath = String(repoPath).replace(/\\/g, '/')
   const entryLine = `  ${key}: ${posixPath}`
 
@@ -79,6 +81,10 @@ export function registerRepoInLocalYaml(yamlPath, key, repoPath) {
   for (let i = reposIdx + 1; i < end; i++) {
     if (keyRe.test(lines[i])) {
       if (lines[i] === entryLine) {
+        // 坑 register-repo-crlf-idempotent-loop：磁盘原文带 CRLF 时（agent Write 工具/Windows
+        // 编辑器写入），内存归一后比对相等直接跳过 → 磁盘永不治愈 + CLI 报 ✅ 假成功 → 解析侧
+        // （修复前）空 Map → MultiRepoContext 报「未注册」→ 死循环。幂等路径也落盘一次治愈。
+        if (hadCr) write(lines.join('\n'))
         return { fileCreated: false, sectionCreated: false, replaced: false } // 值未变，幂等跳过
       }
       lines[i] = entryLine

package/src/module-resolve.js

@@ -20,6 +20,11 @@
  *   - 判定语义（哪个模块才是「对的」）仍归 agent——本表只是机械最优匹配
  */
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
+
+/** 模块卡字数预算（字节）：超限在 resolve 表标 ⚠️ 并提示精简——文档是 agent 的读取税
+ * （对标 deepseek-harness verify-doc-budgets 理念：预算只降不升；2026-08-24 起 runtime.md
+ * 28KB/worktree.md 24KB 已在付税）。advisory 不阻断，16 为 dogfood 校准前缺省。 */
+const MODULE_CARD_BUDGET_BYTES = 16 * 1024
 import { join, relative } from 'path'
 import { parseModuleMapSimple } from './modules.js'
 import { parseTaskRegistry } from './stages/execute.js'
@@ -197,9 +202,12 @@ export function renderModuleResolveTable({ cwd, specBase, changeName }) {
     '| task | 模块 | 粒度 | 模块卡（只读命中的卡，勿按目录整读） | 体量 | 读取建议 |',
     '|---|---|---|---|---|---|',
   ]
+  const budgetBreached = new Set()
   for (const r of rows) {
     if (r.moduleId) {
-      L.push(`| ${r.taskId} | ${r.moduleId} | ${r.granularity === 'fine' ? '细' : '粗'} | \`${r.cardPath}\` | ${kb(r.cardBytes)} | ${r.advice} |`)
+      const over = r.cardBytes > MODULE_CARD_BUDGET_BYTES
+      if (over) budgetBreached.add(r.moduleId)
+      L.push(`| ${r.taskId} | ${r.moduleId} | ${r.granularity === 'fine' ? '细' : '粗'} | \`${r.cardPath}\` | ${kb(r.cardBytes)}${over ? ' ⚠️超预算' : ''} | ${r.advice} |`)
     } else {
       L.push(`| ${r.taskId} | — | — | （无命中，跳过模块文档） | — | — |`)
     }
@@ -207,5 +215,8 @@ export function renderModuleResolveTable({ cwd, specBase, changeName }) {
   L.push('')
   L.push('> 匹配规则：全部 _module-map.yaml 跨层最长前缀（子项目细卡优先于根层大卡），源=tasks 卡 allowed_paths。')
   L.push('> 细卡整卡可读；仅粗卡命中且体量大时**按节读**——只读「契约摘要/注意事项/定位」，跳过「变更索引/人工备注」历史累积段。')
+  if (budgetBreached.size > 0) {
+    L.push(`> ⚠️ 模块卡超预算（>${Math.round(MODULE_CARD_BUDGET_BYTES / 1024)}KB）：${[...budgetBreached].join('、')}——文档是 agent 的读取税，本次变更触及该模块，收尾时顺手 \`sillyspec modules split-changelog\` 迁出历史段或精简正文（对标 deepseek-harness verify-doc-budgets：预算只降不升）。`)
+  }
   return L.join('\n')
 }

package/src/modules.js

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { gitQuiet } from './git-helper.js';
+import { nowWallClock } from './datetime.js';
 
 
 /**
@@ -112,7 +113,7 @@ export async function rebuildModuleMap(cwd, { force = false } = {}) {
 
   // 生成新的 _module-map.yaml
   // 保留已有的完整字段，补齐新卡片
-  const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+  const now = nowWallClock();
   let headCommit = '';
   try {
     // QUAL-01 收口：走 git-helper 统一入口（safe.directory + 数组形式）

package/src/plan-adopt-waves.js

@@ -0,0 +1,126 @@
+/**
+ * plan-adopt-waves.js — `sillyspec plan-adopt-waves` 把 plan.md 的 Wave 段一键重排为
+ * depends_on 拓扑分组（坑 wave-manual-mismatch-noise，2026-08-24 用户反馈二期：主控手排
+ * Wave 与 CLI 拓扑比对不一致只能手动改；依赖方向违规修复后，本命令给一条零手写出路）。
+ *
+ * 行为：
+ *   - depMap（tasks/*.md 的 depends_on，collectTaskDepMap 与 postcheck 同源）→ topoSortWaves
+ *   - 重写 plan.md 的 `## Wave N` 段块（段内按编号排序；首段「并行，无依赖」、其余「依赖前序 Wave」）
+ *   - 无显式 Wave 标题 → 插在「## 任务总表」前（无总表则文末追加）
+ *   - best-effort 同步任务总表的 W 列（仅认 7 列模板行；不匹配的行 warn 不强改）
+ *   - Wave 段内若含非引用内容（正文/表格）→ 拒绝重写（防误删），提示先手动整理
+ *   - 写后复跑 validateBlueprintConsistency 打印结果（防 adopt 把手工安全串行收敛出
+ *     同 Wave 共享路径冲突——topo 只看依赖不看文件重叠）
+ *   - --dry-run 只打印将写入的 Wave 段不落盘；幂等（重复跑产出相同结构）；行尾统一 LF
+ */
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { topoSortWaves, collectTaskDepMap, validateBlueprintConsistency } from './stages/plan-postcheck.js'
+
+const WAVE_HEADING_RE = /^#+\s*Wave\s+\d+/i
+const TASK_REF_RE = /^[-*]\s+(?:\[[ x]\]\s*)?task-\d+\s*[:：\s]*$/i
+const LEGACY_TASK_REF_RE = /^[-*]\s*\[[ x]\]\s*task-\d+/i
+const SUMMARY_HEADING_RE = /^#+\s*任务总表/
+
+/** 渲染标准 Wave 段块（段落间空行分隔，结尾不带多余空行——由调用方控制拼接） */
+function renderWaveBlock(waves) {
+  const L = []
+  waves.forEach((wave, i) => {
+    const sorted = [...wave].sort((a, b) =>
+      parseInt(String(a).replace(/\D/g, ''), 10) - parseInt(String(b).replace(/\D/g, ''), 10))
+    L.push(`## Wave ${i + 1}（${i === 0 ? '并行，无依赖' : '依赖前序 Wave'}）`)
+    for (const t of sorted) L.push(`- ${t}`)
+    if (i < waves.length - 1) L.push('')
+  })
+  return L
+}
+
+/** best-effort 更新任务总表 W 列：仅认 `| task-XX | … | W1 | … |` 形态的 7+ 列模板行 */
+function updateSummaryWaveColumn(lines, waveOf) {
+  let inSummary = false
+  let updated = 0
+  let skipped = 0
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (/^#+\s/.test(line)) { inSummary = SUMMARY_HEADING_RE.test(line); continue }
+    if (!inSummary) continue
+    const m = line.match(/^\|\s*task-(\d+)\s*\|/)
+    if (!m) continue
+    const cells = line.split('|')
+    // 模板 7 列：| 编号 | 任务 | Wave | 优先级 | 依赖 | 覆盖 FR/D | 说明 | → split 后首尾空串
+    if (cells.length < 8 || !/^\s*W\d+\s*$/.test(cells[3] || '')) { skipped++; continue }
+    const taskId = `task-${String(m[1]).padStart(2, '0')}`
+    const waveIdx = waveOf.get(taskId)
+    if (waveIdx === undefined) { skipped++; continue }
+    cells[3] = ` W${waveIdx + 1} `
+    lines[i] = cells.join('|')
+    updated++
+  }
+  return { updated, skipped }
+}
+
+/**
+ * @param {{ changeDir: string, dryRun?: boolean }} opts
+ * @returns {{ ok: boolean, error?: string, waves?: string[][], planPath: string, dryRun: boolean,
+ *             waveBlock?: string[], tableRowsUpdated?: number, tableRowsSkipped?: number,
+ *             postcheck?: { errors: string[], warnings: string[] } }}
+ */
+export function adoptPlanWaves({ changeDir, dryRun = false }) {
+  const planPath = join(changeDir, 'plan.md')
+  if (!existsSync(planPath)) return { ok: false, error: `plan.md 不存在: ${planPath}`, planPath, dryRun }
+  const tasksDir = join(changeDir, 'tasks')
+  if (!existsSync(tasksDir)) return { ok: false, error: `tasks/ 目录不存在: ${tasksDir}`, planPath, dryRun }
+  const depMap = collectTaskDepMap(tasksDir)
+  if (depMap.size === 0) return { ok: false, error: 'tasks/ 下没有 task-NN.md 卡片，无从推导 Wave 分组', planPath, dryRun }
+
+  const { waves, error: topoError } = topoSortWaves(depMap)
+  if (topoError) return { ok: false, error: `拓扑排序失败: ${topoError}`, planPath, dryRun }
+
+  const original = readFileSync(planPath, 'utf8')
+  const lines = original.split(/\r?\n/)
+  const waveBlock = renderWaveBlock(waves)
+  const waveOf = new Map()
+  waves.forEach((ws, i) => { for (const t of ws) waveOf.set(t, i) })
+
+  const firstWaveIdx = lines.findIndex(l => WAVE_HEADING_RE.test(l))
+  if (firstWaveIdx >= 0) {
+    // Wave 段块末尾 = 最后一个 Wave 标题之后连续的任务引用行（空行容忍但不断段；
+    // 遇非 Wave 标题即止）。段内混入非引用内容 → 拒绝重写（防误删正文/表格）。
+    let endIdx = firstWaveIdx
+    for (let i = firstWaveIdx; i < lines.length; i++) {
+      if (WAVE_HEADING_RE.test(lines[i])) { endIdx = i; continue }
+      if (TASK_REF_RE.test(lines[i]) || LEGACY_TASK_REF_RE.test(lines[i])) { endIdx = i; continue }
+      if (lines[i].trim() === '') continue
+      if (/^#+\s/.test(lines[i])) break
+      return { ok: false, error: `Wave 段内含非引用内容（第 ${i + 1} 行「${lines[i].slice(0, 40)}」）——为防误删拒绝重写，请先把 Wave 段整理为纯 "- task-XX" 引用行`, planPath, dryRun }
+    }
+    lines.splice(firstWaveIdx, endIdx - firstWaveIdx + 1, ...waveBlock)
+  } else {
+    // 无显式 Wave 标题：插在「## 任务总表」前；无总表则文末追加
+    const summaryIdx = lines.findIndex(l => SUMMARY_HEADING_RE.test(l))
+    if (summaryIdx >= 0) {
+      lines.splice(summaryIdx, 0, ...waveBlock, '')
+    } else {
+      while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop()
+      lines.push('', ...waveBlock)
+    }
+  }
+
+  const { updated, skipped } = updateSummaryWaveColumn(lines, waveOf)
+  const content = lines.join('\n').replace(/\n*$/, '\n')
+
+  if (dryRun) {
+    return { ok: true, waves, planPath, dryRun: true, waveBlock, tableRowsUpdated: updated, tableRowsSkipped: skipped }
+  }
+
+  writeFileSync(planPath, content, 'utf8')
+  // 复跑 blueprint 一致性（advisory 打印）：topo 只看依赖不看文件重叠——adopt 可能把手工
+  // 安全串行收敛出同 Wave 共享路径冲突，立即暴露而非留到 execute 撞
+  let postcheck = null
+  try {
+    postcheck = validateBlueprintConsistency(changeDir)
+  } catch (e) {
+    postcheck = { errors: [`复跑校验异常: ${e?.message || e}`], warnings: [] }
+  }
+  return { ok: true, waves, planPath, dryRun: false, waveBlock, tableRowsUpdated: updated, tableRowsSkipped: skipped, postcheck }
+}

package/src/quicklog.js

@@ -32,13 +32,15 @@ const sleep = (ms) => new Promise(r => setTimeout(r, ms))
  * 与 rename 之间），相比旧实现的必现双进已可忽略。
  * @param {string} lockPath 锁文件路径（建议与被保护文件同目录）
  * @param {() => (any|Promise<any>)} fn 临界区
- * @param {{staleMs?:number, timeoutMs?:number, retryMs?:number}} opts
+ * @param {{staleMs?:number, timeoutMs?:number, retryMs?:number, content?:string}} opts
+ *   content：锁文件内容（默认 pid-randomId）。供超时报错时展示持有者语义（如 apply 锁写
+ *   {pid, changeName}）——仅展示用途，抢占/偷锁逻辑只比对内容一致性不解析语义。
  */
 export async function withFileLock(lockPath, fn, opts = {}) {
-  const { staleMs = 30000, timeoutMs = 10000, retryMs = 50 } = opts
+  const { staleMs = 30000, timeoutMs = 10000, retryMs = 50, content = null } = opts
   mkdirSync(dirname(lockPath), { recursive: true })
   const start = Date.now()
-  const myId = `${process.pid}-${randomBytes(6).toString('hex')}`
+  const myId = content || `${process.pid}-${randomBytes(6).toString('hex')}`
   let fd = null
   // 抢锁循环
   while (true) {
@@ -174,6 +176,9 @@ function buildPushPayloadFromRaw(rawBlock, { ql_id, author_raw, status, linked_c
     payload.timestamp = parts[1] || null
     payload.title = parts.slice(2).join('|').trim() || payload.title
   }
+  // 顶层标签白名单（^ 行首锚定）：D-004@v1 根因块嵌套四子字段（- 现象：/- 根因：/- 护栏：/- 证据： 列表行）
+  // 因「- 」前缀不匹配本正则——它们是根因块正文内的列表行续行，不是新顶层标签，经 lastLabel 挂载
+  // 进 body_sections[根因]（见下方 inFiles 复位注释）。顶层四字段边界解析不受影响（R-03）。
   const labelRe = /^(状态|关联变更|文件|审计|需求|根因|方案|结果)\s*[：:]\s*(.*)$/
   const bulletRe = /^-\s+(.*)$/
   let inFiles = false
@@ -190,7 +195,9 @@ function buildPushPayloadFromRaw(rawBlock, { ql_id, author_raw, status, linked_c
       else if (label === '关联变更') { payload.linked_changes = value.split(/[，,、+；;]/).map(s => s.trim()).filter(Boolean); inLinked = true; inFiles = false }
       else if (label === '文件') { if (value) payload.files.push(...value.split(/[，,、+；;]/).map(s => s.trim()).filter(Boolean).map(p => ({ path: p, note: null }))); inFiles = true; inLinked = false }
       else if (label === '审计') { /* D-8 advisory 行：只进 raw_block 不进结构化段（body_sections 不扩 schema），并阻断续行误挂 */ lastLabel = null; inFiles = false; inLinked = false }
-      else { payload.body_sections[label] = value; lastLabel = label }
+      // 进入 需求/根因/方案/结果 字段块须关闭 inFiles/inLinked 续行模式（task-07 / D-004@v1）：否则根因块内
+      // 嵌套子字段列表行（- 现象：… 等）会命中下方「文件 bullet」分支被劫进 payload.files，从根因正文截断丢失。
+      else { payload.body_sections[label] = value; lastLabel = label; inFiles = false; inLinked = false }
       continue
     }
     if (bulletRe.test(stripped) && inFiles) {
@@ -332,6 +339,37 @@ export function parseFileNotes(raw) {
     .filter(Boolean)
 }
 
+/**
+ * 校验 --file-notes 原文格式（坑 quick-file-notes-format-silent，2026-08-24 用户反馈二期②：
+ * 多文件分隔符是 `||` 双竖线，写错成 `|`/`,` 时整段被当成第一个文件的括注静默落盘，只能手工修
+ * QUICKLOG）。命令入口 fail-fast 用：每个 `||` 段必须是 `path::括注`（`::` 必填，括注可空）；
+ * 括注内再出现 `::` 视为疑似漏写 `||` 分隔符。返回问题清单供调用方拼报错。
+ * @param {string} raw
+ * @returns {{ ok: boolean, problems: Array<{ seg: string, reason: string, hint: string }> }}
+ */
+export function validateFileNotesFormat(raw) {
+  const problems = []
+  if (!raw) return { ok: true, problems }
+  for (const seg of String(raw).split('||')) {
+    const s = seg.trim()
+    if (!s) continue
+    const idx = s.indexOf('::')
+    if (idx === -1) {
+      problems.push({ seg: s, reason: '缺 `::` 路径/括注分隔符', hint: '格式为 path::括注；不要括注也要写 path::（括注可空）' })
+      continue
+    }
+    const path = s.slice(0, idx).trim()
+    if (!path) {
+      problems.push({ seg: s, reason: '`::` 前路径为空', hint: '格式为 path::括注' })
+      continue
+    }
+    if (s.slice(idx + 2).includes('::')) {
+      problems.push({ seg: s, reason: '括注内出现 `::`', hint: '疑似多文件漏写 `||` 分隔符（双竖线）——多文件写法：path1::括注1 || path2::括注2' })
+    }
+  }
+  return { ok: problems.length === 0, problems }
+}
+
 // 结果块必填字段（quick step3 --done --output 的结构化结果模板，见 src/stages/quick.js）。
 // 4 个必填字段标签从 manifest 同源(stage-contract-spec.js quick.result-labels),prompt 事前契约与本校验单源。
 const RESULT_REQUIRED_LABELS = getRule('quick.result-labels').data.literals
@@ -344,6 +382,8 @@ const RESULT_REQUIRED_LABELS = getRule('quick.result-labels').data.literals
  * @returns {{ ok: boolean, missing: string[] }} ok=true 通过；missing=缺失的字段名列表
  */
 export function validateQuickResult(text) {
+  // 子串包含判定：根因块含嵌套四子字段列表行（- 现象：… 等，task-07 / D-004@v1 合法形态）时，
+  // 顶层四标签仍须齐备（模板契约），嵌套行不影响判定（「- 」前缀不构成顶层标签，亦不缺字段）。
   const missing = RESULT_REQUIRED_LABELS.filter(label => !String(text || '').includes(label))
   return { ok: missing.length === 0, missing }
 }
@@ -486,6 +526,9 @@ async function checkTaskCheckbox(specBase, change, qlId) {
 // 前缀」或正则 split(/(?=需求：|根因：|方案：|结果：)/)）因前导是「/|( 等非边界字符而跳过。严格失败
 // （如真实标签前导是「，」这类弱标点）退回宽松顺序扫描（上一标签之后首次出现）。缺标签返回 null → 落单行
 // 兜底（--done 契约校验仍会拦缺字段）。残余边界：正文引用标签且前导恰好是空白/句末标点时仍可能错位。
+// task-07 / D-004@v1 声明：本切分只作用于「单行四字段压缩归一」路径，嵌套四子字段（- 现象：/- 根因：/
+// - 护栏：/- 证据： 列表行）必须以多行列表行形态写入根因块正文——按序扫描先命中顶层「根因：」标签，
+// 其后的嵌套「- 根因：」等字样落在根因字段正文内不构成新边界，无需改动三个边界函数即天然兼容（Grill C-15）。
 function isFieldBoundary(body, idx) {
   if (idx <= 0) return true
   const prev = body[idx - 1]
@@ -567,6 +610,9 @@ function flipEntryInContent(content, qlId, result, changedFiles = [], fileNotes
       if (segs) body = segs.join('\n')
     }
     // 多行结果（结构化 需求/根因/方案/结果 字段块）：逐行插入为独立字段行。
+    // 根因块嵌套四子字段（- 现象：/- 根因：/- 护栏：/- 证据： 列表行，D-004@v1 postmortem 形态）属
+    // 根因块正文：在此随多行结果逐行原样落盘（带「- 」前缀、保序含换行），不被字段边界扫描误切——
+    // 单行归一切分只认「- 」前缀之外的需求：/根因：/方案：/结果： 标签，嵌套行天然不参与边界判定。
     // 单行结果：保持「结果：<一句话>」一行，向后兼容简单用例。
     const resultLines = /\r?\n/.test(body)
       ? body.split(/\r?\n/).filter(l => l.trim() !== '')