sillyspec 3.28.10 → 3.28.12

package/src/quicklog.js

@@ -10,13 +10,14 @@
  * 本模块把分配与写入下沉到 CLI 进程内，O_EXCL lockfile 串行化，彻底消除上述问题。
  * 无新 npm 依赖（仅 fs/path/crypto）——匹配项目零 FS 工具依赖的风格。
  */
-import { join, dirname, basename } from 'path'
+import { join, dirname, basename, resolve, relative, isAbsolute } from 'path'
 import { getRule } from './stage-contract-spec.js'
 import {
   openSync, closeSync, unlinkSync, statSync, mkdirSync, existsSync,
   readFileSync, writeFileSync, writeSync, readdirSync, renameSync, appendFileSync, rmSync,
 } from 'fs'
 import { randomBytes } from 'crypto'
+import { safeGit } from './git-helper.js'
 
 const sleep = (ms) => new Promise(r => setTimeout(r, ms))
 
@@ -1168,3 +1169,232 @@ export async function cancelQuickSession({ specBase, gitUser, qlId, sessionId =
 
   return { ok: true, quicklogFile, removedTaskRows }
 }
+
+// ── quicklog commit（known-issues ④ v1：本会话条目切片提交，2026-09-16）──
+//
+// 坑 QUICKLOG 多会话条目交织：QUICKLOG 是多会话共享追加的单文件，某会话 `git add` 整文件
+// 会夹带并行会话未完成条目（违反显式 pathspec 隔离纪律，AGENTS.md 第 18 条），只能
+// 「备份 → 剥离并行条目 → commit pathspec → 恢复」四步舞（2026-09-15/16 单会话实证 6 次）。
+// 本命令把四步舞机制化：
+//   切片（工作区 = HEAD 基线 + 本会话条目块）→ git add/commit 显式 pathspec（含 patches
+//   sidecar 与额外 pathspec）→ finally 恢复工作区全量（并行条目留「未提交」预期态）。
+// 任一步失败 fail-fast 打印人工兜底；恢复在 finally，commit 失败也不留半态。
+// 「完整文件化」（entries sidecar 权威 + 聚合渲染）不在 v1 范围，见 known-issues 条目。
+
+// git 子操作退避重试：与 wt-commit.js gitWithLockRetry 同款（本文件锁只约束 quicklog 写方，
+// 锁队列外裸跑 git 的并行进程仍可能短暂持 index.lock/HEAD 锁，等待重试消化）。
+async function quicklogGitRetry(cwd, args, label, { retries = 6, waitMs = 1000 } = {}) {
+  for (let i = 0; ; i++) {
+    const { value, error } = safeGit(cwd, args, { timeout: 30000 })
+    if (!error) return value
+    const msg = String((error && error.message) || error)
+    if (/index\.lock|HEAD\.lock|cannot lock ref/i.test(msg) && i < retries) {
+      await sleep(waitMs)
+      continue
+    }
+    throw new Error(`${label} 失败：${msg.split('\n')[0].trim()}`)
+  }
+}
+
+// 行级条目头匹配（容错口径与 countQuicklogEntries 一致：## 后空白可省、ID 与 | 间空白可变）
+function findQuicklogEntryLineIdx(lines, qlId) {
+  const re = new RegExp(`^##[ \\t]*${escapeRe(qlId)}[ \\t]*\\|`)
+  return lines.findIndex(l => re.test(l))
+}
+
+/**
+ * 切片：工作区全量 → 「基线 + 指定条目块」。
+ * 块界 = `## ql-<id>` 头到下一个 `## ` 头/文件尾（extractRawBlock 同口径）；条目间补单空行
+ * 分隔（对齐 allocateQuicklogEntry 条目模板形态）。EOL 随工作区文件——HEAD blob 归一到
+ * 工作区 EOL 再拼（.gitattributes eol=lf + autocrlf=true 环境下 blob 是 LF、工作区 CRLF；
+ * git add 时按配置归一回去，不产生整文件行尾假差异）。条目头已在基线（先前提交过）→
+ * 跳过不重复（重跑幂等）。返回 null = 无任何目标条目；blocks 为空 = 全部已在基线
+ * （调用方不落盘不动文件，避免基线归一化重写制造假提交）。
+ */
+function sliceQuicklogFileContent(fullContent, baselineContent, qlIds) {
+  const eol = fullContent.includes('\r\n') ? '\r\n' : '\n'
+  const norm = (s) => String(s || '').replace(/\r\n/g, '\n')
+  const lines = norm(fullContent).split('\n')
+  const baseLines = norm(baselineContent).split('\n')
+  while (baseLines.length && baseLines[baseLines.length - 1].trim() === '') baseLines.pop()
+  const blocks = []
+  const blockIds = []
+  const alreadyIncluded = []
+  for (const qlId of qlIds) {
+    const startIdx = findQuicklogEntryLineIdx(lines, qlId)
+    if (startIdx === -1) continue
+    if (findQuicklogEntryLineIdx(baseLines, qlId) !== -1) { alreadyIncluded.push(qlId); continue }
+    let endIdx = lines.length
+    for (let i = startIdx + 1; i < lines.length; i++) {
+      if (/^##[ \t]*\S/.test(lines[i])) { endIdx = i; break }
+    }
+    const block = lines.slice(startIdx, endIdx)
+    while (block.length && block[block.length - 1].trim() === '') block.pop()
+    blocks.push(block)
+    blockIds.push(qlId)
+  }
+  if (blocks.length === 0 && alreadyIncluded.length === 0) return null
+  const outLines = [...baseLines]
+  for (const block of blocks) {
+    if (outLines.length > 0) outLines.push('') // 条目间空行分隔
+    outLines.push(...block)
+  }
+  let sliced = outLines.join('\n') + '\n'
+  if (eol === '\r\n') sliced = sliced.replace(/\n/g, '\r\n')
+  return { content: sliced, blockIds, alreadyIncluded }
+}
+
+const QUICKLOG_COMMIT_MANUAL_FALLBACK = [
+  '人工兜底（四步舞）：',
+  '  ① 备份 QUICKLOG 文件：cp <文件> /tmp/quicklog-backup.md',
+  '  ② 从工作区文件剥离并行会话条目（只留本会话条目，条目块 = "## ql-…" 行到下一个 "## " 头）',
+  '  ③ git add -- <QUICKLOG文件> .sillyspec/quicklog/patches/<ql-id>.* && git commit -m "..."',
+  '  ④ 从备份恢复工作区全量（并行条目回到未提交态）',
+].join('\n')
+
+/**
+ * 一键收编本会话 QUICKLOG 条目（`sillyspec quicklog commit`，known-issues ④ v1）。
+ *
+ * 持用户 QUICKLOG 锁（与 allocate/complete/cancel 同锁）跨「定位 → 切片 → 提交 → 恢复」
+ * 全程——锁内重读文件，并发追加的并行条目不丢（恢复用的就是锁内读到的最新全量）。
+ *
+ * @param {object} opts
+ * @param {string} opts.specBase .sillyspec 根目录
+ * @param {string} [opts.cwd] 调用方 cwd（git rev-parse --show-toplevel 的起点）
+ * @param {string} opts.gitUser git user.name（定位本用户 QUICKLOG 文件与锁）
+ * @param {string[]} [opts.qlIds] 显式 ql-ID（--ql，可含已取消条目——历史一并收编）
+ * @param {string|null} [opts.changeName] quick 会话 ID（缺 --ql 时读其 guard.json 的 quicklogId）
+ * @param {string|null} [opts.sessionsDir] quick-sessions 目录（平台模式异位时由 dispatch 传入）
+ * @param {string} opts.message 提交信息
+ * @param {string[]} [opts.extraPathspecs] 额外 pathspec（-- 后透传，随本次提交带上）
+ * @returns {Promise<{ok:boolean,skipped:boolean,head:string,shortHead:string,files:string[],
+ *   quicklogFiles:string[],committedQlIds:string[],skippedQlIds:string[],backupPaths:string[]}>}
+ */
+export async function runQuicklogCommit({ specBase, cwd = process.cwd(), gitUser, qlIds = [], changeName = null, sessionsDir = null, message = '', extraPathspecs = [] }) {
+  if (!message || !message.trim()) throw new Error('缺少 -m/--message <提交信息>（建议 "chore: 收编本会话 QUICKLOG 条目——<一句话>"）')
+  const ids = [...new Set((Array.isArray(qlIds) ? qlIds : []).filter(id => typeof id === 'string' && id.trim()).map(id => id.trim()))]
+
+  // ql-ID 解析优先级：--ql 显式 > 会话 guard.json（写侧字段 quicklogId，兼容旧 .qlId）
+  if (ids.length === 0 && changeName) {
+    const guardPath = join(sessionsDir || join(specBase, '.runtime', 'quick-sessions'), changeName, 'guard.json')
+    try {
+      if (existsSync(guardPath)) {
+        const g = JSON.parse(readFileSync(guardPath, 'utf8'))
+        const q = g.quicklogId || g.qlId
+        if (typeof q === 'string' && q.trim()) ids.push(q.trim())
+      }
+    } catch { /* guard 损坏 → 按缺失走下方 fail-fast */ }
+  }
+  if (ids.length === 0) {
+    throw new Error(`无法定位 ql-ID：--change 会话的 guard.json 缺失/损坏且未传 --ql——显式传 --ql <ql-xxx>（可重复传多个；含已取消条目，cancelled 也是历史一并收编；ID 即 QUICKLOG 条目头 "## ql-…" 的 ID）`)
+  }
+
+  const quicklogDir = join(specBase, 'quicklog')
+  const user = sanitizeQuicklogUser(gitUser) || 'unknown'
+  const lockPath = join(quicklogDir, `.QUICKLOG-${user}.md.lock`)
+  const repoRootRaw = safeGit(cwd, ['rev-parse', '--show-toplevel'], { timeout: 10000 }).value
+  if (!repoRootRaw) throw new Error(`git 仓库定位失败（cwd=${cwd} 的 git rev-parse --show-toplevel 无输出）`)
+  const repoRoot = resolve(repoRootRaw)
+  const toRel = (abs) => relative(repoRoot, abs).replace(/\\/g, '/')
+
+  const result = await withFileLock(lockPath, async () => {
+    // 锁内重扫（并发追加不丢）：主文件优先，恒扫全部 QUICKLOG 文件（含轮转归档——
+    // 2026-09-16 实证 ql-013 落轮转新文件、ql-014 又落回旧文件，新旧都可能有本会话条目）
+    const allFiles = listQuicklogFiles(quicklogDir)
+    const mainName = `QUICKLOG-${user}.md`
+    const ordered = existsSync(join(quicklogDir, mainName))
+      ? [mainName, ...allFiles.filter(f => f !== mainName)] : allFiles
+    const plans = []
+    const found = new Set()
+    for (const f of ordered) {
+      const p = join(quicklogDir, f)
+      let content = ''
+      try { content = readFileSync(p, 'utf8') } catch { continue }
+      const contentLines = content.split(/\r?\n/)
+      const hit = ids.filter(id => findQuicklogEntryLineIdx(contentLines, id) !== -1)
+      for (const id of hit) found.add(id)
+      if (hit.length > 0) plans.push({ file: p, rel: toRel(p), content, hitIds: hit })
+    }
+    // 工作区未命中者查 HEAD 基线：已在 = 幂等跳过；两边都无 = fail-fast（--ql 笔误防护）
+    const alreadyCommitted = []
+    for (const id of ids.filter(i => !found.has(i))) {
+      let inHead = false
+      for (const f of ordered) {
+        const blob = safeGit(repoRoot, ['show', `HEAD:${toRel(join(quicklogDir, f))}`], { trim: false, timeout: 10000 }).value
+        if (blob && findQuicklogEntryLineIdx(blob.replace(/\r\n/g, '\n').split('\n'), id) !== -1) { inHead = true; break }
+      }
+      if (inHead) alreadyCommitted.push(id)
+      else throw new Error(`条目 ${id} 在所有 QUICKLOG-*.md（含轮转归档）与 HEAD 中均未找到——核对 --ql 的 ql-ID。\n${QUICKLOG_COMMIT_MANUAL_FALLBACK}`)
+    }
+
+    // 切片 + 备份（.runtime 不入库，恢复失败时的最后兜底）。无新块的文件不动不落盘——
+    // 已收编条目重跑形态下按基线归一化重写会制造只差尾部空行的假提交。
+    const now = new Date()
+    const stamp = `${todayStamp(now)}-${String(now.getHours()).padStart(2, '0')}${String(now.getMinutes()).padStart(2, '0')}${String(now.getSeconds()).padStart(2, '0')}`
+    mkdirSync(join(specBase, '.runtime'), { recursive: true })
+    const backups = []
+    const originals = []
+    const slicePlans = []
+    for (const plan of plans) {
+      const baseline = safeGit(repoRoot, ['show', `HEAD:${plan.rel}`], { trim: false, timeout: 10000 }).value || ''
+      const sliced = sliceQuicklogFileContent(plan.content, baseline, plan.hitIds)
+      if (!sliced) continue // 不可能（plan.hitIds 非空才进 plans），防御
+      for (const id of sliced.alreadyIncluded) alreadyCommitted.push(id)
+      if (sliced.blockIds.length === 0) continue // 全部已在基线：文件不动、不进提交
+      const backupPath = join(specBase, '.runtime', `quicklog-slice-${stamp}-${basename(plan.file)}`)
+      writeFileSync(backupPath, plan.content)
+      backups.push(backupPath)
+      originals.push({ file: plan.file, content: plan.content })
+      await writeAtomic(plan.file, sliced.content)
+      slicePlans.push(plan)
+    }
+
+    // pathspec 组装：QUICKLOG 文件 + patches sidecar（--done 冻结件，存在才加）+ 额外透传
+    const addPaths = slicePlans.map(pl => pl.rel)
+    for (const id of ids) {
+      for (const ext of ['.json', '.patch']) {
+        const sp = join(quicklogDir, 'patches', id + ext)
+        if (existsSync(sp)) addPaths.push(toRel(sp))
+      }
+    }
+    for (const extra of (Array.isArray(extraPathspecs) ? extraPathspecs : []).filter(Boolean)) {
+      addPaths.push(toRel(isAbsolute(extra) ? extra : resolve(cwd, extra)))
+    }
+    if (addPaths.length === 0) {
+      // 条目均已收编且无 sidecar/额外 pathspec → 无事可做（幂等重跑）
+      return { skipped: true, head: safeGit(repoRoot, ['rev-parse', 'HEAD'], { timeout: 10000 }).value || '', addPaths: [], backups, alreadyCommitted, quicklogFiles: slicePlans.map(pl => basename(pl.file)) }
+    }
+
+    try {
+      await quicklogGitRetry(repoRoot, ['add', '--', ...addPaths], 'git add')
+      // pathspec 范围内无 staged 变更 = 条目均已收编（幂等重跑），HEAD 不动不算失败
+      const staged = safeGit(repoRoot, ['diff', '--cached', '--name-only', '--', ...addPaths], { timeout: 10000 }).value || ''
+      if (!staged.trim()) {
+        return { skipped: true, head: safeGit(repoRoot, ['rev-parse', 'HEAD'], { timeout: 10000 }).value || '', addPaths, backups, alreadyCommitted, quicklogFiles: slicePlans.map(pl => basename(pl.file)) }
+      }
+      await quicklogGitRetry(repoRoot, ['commit', '-m', message, '--', ...addPaths], 'git commit')
+      const head = safeGit(repoRoot, ['rev-parse', 'HEAD'], { timeout: 10000 }).value || ''
+      return { skipped: false, head, addPaths, backups, alreadyCommitted, quicklogFiles: slicePlans.map(pl => basename(pl.file)) }
+    } finally {
+      // 恢复：切片前工作区全量写回（并行会话条目回到「未提交」预期态；原子写防轮询读半截）
+      for (const o of originals) await writeAtomic(o.file, o.content)
+    }
+  }, {
+    staleMs: 120000, // 临界区含 git add/commit（AV 扫描的 Windows 上秒级起步），30s 默认会被误偷锁
+    timeoutMs: 120000,
+    content: JSON.stringify({ pid: process.pid, purpose: 'quicklog-commit' }),
+  })
+
+  const already = [...new Set(result.alreadyCommitted)]
+  return {
+    ok: true,
+    skipped: !!result.skipped,
+    head: result.head,
+    shortHead: (result.head || '').slice(0, 8),
+    files: result.addPaths,
+    quicklogFiles: result.quicklogFiles,
+    committedQlIds: ids.filter(id => !already.includes(id)),
+    skippedQlIds: already,
+    backupPaths: result.backups,
+  }
+}

package/src/run/complete-handlers.js

@@ -9,6 +9,9 @@
  *     srcDir 缺失时走 findAlreadyArchivedDir 幂等自愈（issue archive-stage-physical-tracking-desync）；
  *     archiveChangeDirectory + findAlreadyArchivedDir 已 export 供 test 直接 import
  *   - sanitizeProjectName / validateParsedProjects：项目名清洗 + 列表校验纯函数（handleScanProjectListStep 专用）
+ *   - assertWaveTasksComplete：execute「Wave N 执行」步骤 --done 前的完成度门（task-08 / FR-12——
+ *     本 Wave 任一 task 的 tasks.md checkbox 未勾 → exit 1；completeStep 在 status='completed' 赋值前
+ *     调用，异常 fail-open），实现收拢文件尾（同知识闭环段先例）
  *
  * 安全锚：run.js 始终 barrel。3 handler 由 run.js import 回来；sanitizeProjectName + validateParsedProjects
  * 被 test 直接 import（run-sanitize-project-name / run-scan-project-parse），run.js barrel re-export 契约保留。
@@ -46,7 +49,9 @@ import { resolveSessionIdentity } from '../progress.js'
 // ql-20260915-001 修复④：chunkPaths（argv 分批）供归档窄化 add / minePaths 精确补暂存用。
 // 无环：worktree-apply 静态闭包（worktree/task-review/quicklog 等）不引本文件；既有
 // withMainRepoLock 走动态 import 是归档链防环的历史形态，chunkPaths 纯函数无此约束。
-import { chunkPaths } from '../worktree-apply.js'
+// checkDbScriptDeclarationGate（task-04 / FR-05）同排静态引入：门函数自身纯文件集 ×
+// 文本声明对账（verify-probes 文法经 worktree-apply 顶层动态绑定），同样无环约束。
+import { chunkPaths, checkDbScriptDeclarationGate } from '../worktree-apply.js'
 
 /**
  * 清洗项目名：只保留 ASCII 字母/数字/横线/下划线/点，过滤中文和特殊字符。
@@ -785,6 +790,32 @@ export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, c
     console.log('⚠️  请添加 --confirm 确认归档，例如：sillyspec run archive --done --confirm --output "确认归档"')
     return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
   }
+  // ── db/*.sql 声明门·归档前置（2026-09-17-pass-cap-semantics task-04 / FR-05 / D-007/D-012
+  // 兜底第二门）── --confirm 已过、目录移动前：apply-manifest.json 的 files 过 worktree-apply
+  // 同款门（对账 verify-result.md 声明，含 db-script handover 互斥）。缺失/互斥 → 复用 !
+  // confirm 早退形态（status 回 pending + pm._write + early return），变更目录不动、输出修复
+  // 指引；apply-manifest.json 缺失 → 门空转不阻断（无 apply 面，主门在 verify 侧事实③）；
+  // manifest 读取/解析异常 → fail-open warn 放行（门异常不锁死归档）。
+  const dbGateManifestPath = join(specBase, 'changes', changeName, 'apply-manifest.json')
+  if (existsSync(dbGateManifestPath)) {
+    try {
+      const dbGateManifest = JSON.parse(readFileSync(dbGateManifestPath, 'utf8'))
+      const dbGateFiles = (dbGateManifest && Array.isArray(dbGateManifest.files) ? dbGateManifest.files : [])
+        .map((e) => (e && typeof e === 'object' ? e.path : e)).filter(Boolean)
+      const dbGate = checkDbScriptDeclarationGate({ projectRoot: cwd, specBase, changeName, files: dbGateFiles })
+      if (!dbGate.ok) {
+        steps[currentIdx].status = 'pending'
+        steps[currentIdx].completedAt = null
+        if (outputText) steps[currentIdx].output = null
+        pm._write(cwd, progress, changeName)
+        console.error(`⛔ db 脚本执行声明对账未过（归档阻断，变更目录未移动）：\n${dbGate.error}`)
+        return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
+      }
+      if (dbGate.warning) console.warn(`⚠️  ${dbGate.warning}`)
+    } catch (e) {
+      console.warn(`⚠️  db 声明门异常降级放行（apply-manifest.json 读取/解析失败，fail-open）: ${(e && e.message) || e}`)
+    }
+  }
   // ── 归档前 delta.md 自动生成（P3d task-02，fail-soft 零阻断）──
   // 目录移走前在 changes/<name>/ 落一份 Before/Delta/After 三段式快照（四源采集容缺，
   // buildDeltaReport 见 ../archive-delta.js），随归档包留存。失败只 console.error 留痕、
@@ -2481,3 +2512,143 @@ export function extractQuickCauseField(outputText) {
   return m[1].replace(/\s+/g, ' ').trim()
 }
 
+// ── Wave 步骤完成度门（2026-09-17-pass-cap-semantics task-08 / FR-12 / D-013@v1）──
+// 动机锚：2026-09-17 本变更执行中 Wave 2 越位实证——review write 退出码被 shell 管道吞掉后
+// --done 落在下一 Wave，「Wave 2 执行」步骤被静默标 completed；既有防护（--step 意图断言
+// 可选、并发 60s 横幅仅 warn）均非阻断。本门 fail-closed 补执行期缺口，放文件尾（函数声明
+// 提升 + B1 源码文本级断言窗口约束，同知识闭环段先例——门内含 process.exit，收拢在此避免
+// 推挪 handleQuickStageCompletion 附近 detectConcurrentChanges ±[200,600] 的断言锚）。
+
+/**
+ * 解析 plan.md 第 seq 个显式 Wave 段的任务 ID 列表。
+ *
+ * 同源口径孪生（不造第二套解析）：src/stages/execute.js 的 parseWavesFromPlan 未导出，且
+ * execute.js 不在本任务 allowed_paths，无法直接 import——正则与段边界守卫逐字对齐：
+ *   - Wave 标题 /^#+\s*Wave\s*(\d+)/i（空格可选、编号后缀任意——解析侧宁可多收不可静默丢）
+ *   - 引用行 /^[-*]\s+task-(\d+)\s*$/i → 归一 task-NN（padStart(2,'0')）
+ *   - 任何非 Wave 标题行（/^#{1,6}\s+/）退出当前段（「## 自检」等后续段的行不收）
+ *   - 段序 = 出现顺序（buildExecuteSteps 的步骤名 `Wave ${i+1} 执行` 取 waves 数组位次，
+ *     非段内编号——显式段存在时两者通常一致，乱序编号时位次与 prompt 实际下发任务一致）
+ * 差异（有意）：不做 parseWavesFromPlan 的隐式 Wave 合成——门只核对显式段，plan 无显式段
+ * 一律 null 交由调用方 warn 放行（D-003@v1 隐式串行语义无段可核对，不误伤）。
+ * 漂移风险由 test/wave-task-complete-gate.test.mjs 断言锁定。
+ *
+ * @param {string} planContent plan.md 全文
+ * @param {number} seq 1-based 显式段位次（步骤名编号同源）
+ * @returns {string[]|null} 该段 task ID 列表；null = 显式段不足 seq 个（隐式/light/兜底形态）
+ */
+function parseExplicitWaveTaskIds(planContent, seq) {
+  const WAVE_HEADING_RE = /^#+\s*Wave\s*(\d+)/i   // ← execute.js parseWavesFromPlan 同源正则
+  const waveRefRe = /^[-*]\s+task-(\d+)\s*$/i     // ← execute.js parseWavesFromPlan 同源正则
+  const sections = []   // [{ index, ids }] 按出现顺序（不合成隐式 Wave）
+  let current = null
+  for (const rawLine of String(planContent || '').split('\n')) {
+    const line = rawLine.replace(/\r$/, '')
+    const waveMatch = line.match(WAVE_HEADING_RE)
+    if (waveMatch) {
+      current = { index: parseInt(waveMatch[1], 10), ids: [] }
+      sections.push(current)
+      continue
+    }
+    if (/^#{1,6}\s+/.test(line)) { current = null; continue }
+    const refMatch = line.match(waveRefRe)
+    if (refMatch && current) current.ids.push(`task-${refMatch[1].padStart(2, '0')}`)
+  }
+  const target = sections[seq - 1]
+  return target ? target.ids : null
+}
+
+/**
+ * Wave 步骤完成度门（task-08 / FR-12 / D-013@v1）：execute 阶段名为「Wave N 执行」的步骤
+ * --done 时 fail-closed 核对本 Wave 全部 task 的 tasks.md checkbox 已勾（勾选唯一真源是
+ * CLI：review write 落盘即勾 + autoCheckPlanFromReviews 兜底）。任一未勾 → console.error
+ * 列未勾清单与两条出路 + process.exit(1)，步骤保持待完成（接线点在 completeStep 的
+ * status='completed' 赋值之前，exit 时 DB 不落假完成态）。
+ *
+ * 生效面与放行面：
+ *   - 仅 steps[currentIdx].name 匹配 /^Wave (\d+) 执行$/ 时生效，其他步骤名直接 return（零行为）
+ *   - ① autoCheckPlanFromReviews 幂等先行（review pass 自动勾选——先补勾再核对，「review 已
+ *     pass 但 checkbox 未回填」形态不误拦；该函数自身全路径 try/catch 从不抛）
+ *   - plan.md 无第 N 个显式 Wave 段（隐式 Wave/light 计划）→ warn 放行（D-003@v1 不误伤）
+ *   - plan.md/tasks.md 缺失或读取失败 → warn 放行（fail-open，文档瞬态不锁死流程）
+ *   - 门自身意外异常不在本函数内吞——上抛给接线层（complete.js）fail-open warn 放行；
+ *     正常判定路径（读到未勾）必须硬拦，process.exit 不受 try/catch 影响
+ *
+ * @param {{ steps: Array<{name:string}>, currentIdx: number, changeName: string, cwd: string, specBase?: string, platformOpts?: object }} opts
+ *   changeDir 锚定与 autoCheckPlanFromReviews 写入侧同口径（driftAnchor > specRoot > specBase >
+ *   cwd/.sillyspec）——tasks.md 是 autoCheck 写的，门必须读同一份，防双真源分裂。
+ */
+export async function assertWaveTasksComplete({ steps, currentIdx, changeName, cwd, specBase, platformOpts = {} }) {
+  const stepName = String(steps?.[currentIdx]?.name || '')
+  const waveMatch = /^Wave (\d+) 执行$/.exec(stepName)
+  if (!waveMatch) return   // 非「Wave N 执行」步骤：零行为（其他 execute 步骤 / 其他阶段不门）
+  const waveSeq = parseInt(waveMatch[1], 10)
+  if (!changeName || !cwd) {
+    console.warn(`⚠️ [wave-complete-gate] 缺 changeName/cwd，跳过「${stepName}」完成度核对（fail-open）`)
+    return
+  }
+
+  // ① autoCheck 幂等先行（D-013）：兜底 catch 仅防动态 import 自身失败——warn 后继续核对
+  //   （checkbox 才是门的判定依据；勾选补偿失败留给两条出路①重跑 --done 再试，不锁死）。
+  //   autoCheckPlanFromReviews 定义于 ./complete.js（grep 实证 :1172 export；任务卡原文写
+  //   ../task-review.js 系定位笔误，该文件仅有引用注释无定义）；动态 import 防顶层环
+  //   （complete.js 静态 import 本文件，运行时调用时 complete.js 已在模块缓存，无死锁）。
+  try {
+    const { autoCheckPlanFromReviews } = await import('./complete.js')
+    await autoCheckPlanFromReviews({ stageName: 'execute', changeName, cwd, platformOpts })
+  } catch (e) {
+    console.warn(`⚠️ [wave-complete-gate] autoCheck 先行勾选失败，按 tasks.md 现状继续核对: ${(e && e.message) || e}`)
+  }
+
+  const gateSpecBase = platformOpts?.specDriftAnchor || platformOpts?.specRoot || specBase || join(cwd, '.sillyspec')
+  const changeDir = join(gateSpecBase, 'changes', changeName)
+  const planPath = join(changeDir, 'plan.md')
+  const tasksPath = join(changeDir, 'tasks.md')
+
+  let planContent, tasksContent
+  try {
+    if (!existsSync(planPath) || !existsSync(tasksPath)) {
+      console.warn(`⚠️ [wave-complete-gate] plan.md/tasks.md 缺失（${changeDir}），跳过「${stepName}」完成度核对（fail-open 放行）`)
+      return
+    }
+    planContent = readFileSync(planPath, 'utf8')
+    tasksContent = readFileSync(tasksPath, 'utf8')
+  } catch (e) {
+    console.warn(`⚠️ [wave-complete-gate] plan.md/tasks.md 读取失败（${(e && e.message) || e}），跳过核对（fail-open 放行）`)
+    return
+  }
+
+  // ② 本 Wave 任务 ID 列表（parseExplicitWaveTaskIds：execute.js parseWavesFromPlan 同源孪生）
+  const waveTaskIds = parseExplicitWaveTaskIds(planContent, waveSeq)
+  if (waveTaskIds === null) {
+    console.warn(`⚠️ [wave-complete-gate] plan.md 无第 ${waveSeq} 个显式 Wave 段（隐式 Wave/light 计划无显式段头），跳过完成度核对（fail-open 放行——D-003@v1 隐式串行语义不误伤）`)
+    return
+  }
+  if (waveTaskIds.length === 0) {
+    // 段在但无引用行：execute 启动时 validatePlanForExecute 已拦（空 Wave 段诊断），不重复拦
+    return
+  }
+
+  // ③ tasks.md checkbox 逐 ID 核对（parseTaskRegistry 是 execute.js 导出的同源解析，复用不另造）
+  const { parseTaskRegistry } = await import('../stages/execute.js')
+  const registry = parseTaskRegistry(tasksContent)
+  const regById = new Map(registry.map(t => [t.id, t]))
+  const unchecked = waveTaskIds.filter(id => regById.get(id)?.done !== true)
+
+  if (unchecked.length > 0) {
+    // ④ fail-closed 硬拦：沿用仓内 console.error + process.exit(1) 既有形态（错误信息
+    //    process.exit 前同步打印完整——Windows 下 UV_HANDLE_CLOSING 退出码坑不复现）
+    console.error(`❌ Wave ${waveSeq} 完成度门未过：本 Wave ${waveTaskIds.length} 个 task 中 ${unchecked.length} 个的 tasks.md checkbox 未勾——本次 --done 未完成，步骤「${stepName}」保持待完成。`)
+    console.error('   未勾任务：')
+    for (const id of unchecked) {
+      const reg = regById.get(id)
+      console.error(`   - ${id}${reg && reg.name ? `（${reg.name}）` : '（tasks.md 注册表无此行——plan 悬空引用）'}`)
+    }
+    console.error('   两条出路：')
+    console.error(`   ① 任务确未完成：补实现与 review write（sillyspec review write --change ${changeName} --task <task-NN> --spec pass --quality pass --force --changed-files <文件>）后重跑 --done——review pass 落盘即自动勾选`)
+    console.error(`   ② 确属误推进（步骤被越位标完成）：sillyspec run execute --reopen --from-step ${currentIdx + 1}${changeName ? ` --change ${changeName}` : ''} 退回本步重走完成`)
+    process.exit(1)
+  }
+  console.log(`🛡️ 「${stepName}」完成度门通过：${waveTaskIds.length} 个 task checkbox 全勾（${waveTaskIds.join('、')}）`)
+}
+

package/src/run/complete.js

@@ -16,7 +16,7 @@
  *   - stages/plan-postcheck.js: executePlanPostcheck（noAI 硬门）
  *   - node: join(path) + existsSync/readdirSync/readFileSync/mkdirSync/writeFileSync/appendFileSync/statSync(fs)
  */
-import { join } from 'node:path'
+import { join, isAbsolute, resolve } from 'node:path'
 import { existsSync, readFileSync, mkdirSync, writeFileSync, appendFileSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import { writeAtomicSync } from '../fs-atomic.js'
@@ -43,10 +43,10 @@ async function getStageStepsAutoAware(stageName, cwd, progress, specDir) {
 import { executeScanPreflight, executeScanPostcheck, computeScanProfile, executeScanDetectProjects, executeScanResumeCheck, executeScanFinalize } from './scan-profile.js'
 import { executeProgressConfirm } from './progress-confirm.js'
 import { AUXILIARY_STAGES } from '../constants.js'
-import { executePlanPostcheck as runPlanPostcheckLib } from '../stages/plan-postcheck.js'
+import { executePlanPostcheck as runPlanPostcheckLib, parseRepoRegistry } from '../stages/plan-postcheck.js'
 import { outputStep, collectStageWaitHistory } from './prompt.js'
 import { enforceDepsGate, enforceReviewJsonGate, enforceSymbolImpactGate, warnMissingUiPrototype, completeStageGates, readDesignScale } from './gates.js'
-import { handleArchiveConfirmStep, handlePlanGeneratePlanStep, handleScanProjectListStep, handleWorkflowPostCheck, handleQuickStageCompletion, handleExecuteWaveArtifact } from './complete-handlers.js'
+import { handleArchiveConfirmStep, handlePlanGeneratePlanStep, handleScanProjectListStep, handleWorkflowPostCheck, handleQuickStageCompletion, handleExecuteWaveArtifact, assertWaveTasksComplete } from './complete-handlers.js'
 import { formatExecuteSummary } from '../worktree-apply.js'
 import { validateDecisionModuleRefs } from '../design-facts.js'
 import { isEndToEndTaskText } from '../change-risk-profile.js'
@@ -488,6 +488,19 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     process.exit(1)
   }
 
+  // ── Wave 步骤完成度门（2026-09-17-pass-cap-semantics task-08 / FR-12 / D-013@v1）──
+  // 动机锚：2026-09-17 本变更执行中 Wave 2 越位实证——review write 退出码被 shell 管道吞掉后
+  // --done 落在下一 Wave，步骤被静默标 completed；既有防护（--step 可选断言 / 60s 并发横幅）
+  // 均非阻断。本门 fail-closed：名为「Wave N 执行」的步骤 --done 时本 Wave 任一 task 的
+  // tasks.md checkbox 未勾 → exit 1（先 autoCheckPlanFromReviews 幂等补勾再核对，见
+  // complete-handlers.js assertWaveTasksComplete）。门自身异常 fail-open warn——门 bug 不
+  // 锁死完成路径，正常判定路径硬拦；exit 时 status 尚未赋 completed，DB 不落假完成态。
+  try {
+    await assertWaveTasksComplete({ steps, currentIdx, changeName, cwd, specBase, platformOpts })
+  } catch (e) {
+    console.warn(`⚠️ Wave 完成度门异常，fail-open 放行（不阻断本次完成）: ${(e && e.message) || e}`)
+  }
+
   steps[currentIdx].status = 'completed'
   steps[currentIdx].completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
   if (outputText) {
@@ -1009,7 +1022,33 @@ async function buildDraftContext(cwd, changeName) {
  * merge-base 补齐，与草稿归因同口径），再剔 meta.baselineFiles（R-07 防伪底线：merge-base..
  * wtHEAD 含 baseline checkpoint 提交，夹带文件=非本变更改动，不剔则「声明未做恰被夹带」的
  * task 误勾）。全空时仍不设 diffFileSet（退回逐 task 实测路径，原语义）。
+ *
+ * task-05 FR-08：另并入跨仓仓根双源（diff HEAD~1..HEAD ∪ status porcelain，见函数体
+ * collectCrossRepoDiffRoots 注记）——跨仓 task 的 changedFiles 按其仓根相对路径命中。
  */
+/**
+ * 跨仓仓根收集（task-05 / FR-08 diff 源层）：读侧口径 = <cwd>/.sillyspec/local.yaml 的
+ * parseRepoRegistry（与 design-facts.js 有段头分支 / execute MultiRepoContext 同款）；相对
+ * 注册路径按 cwd resolve，绝对路径原样，根不存在跳过。local.yaml 不可读/解析失败 fail-open
+ * 返回 []（不炸勾选主流程、不放大勾选面）。
+ */
+function collectCrossRepoDiffRoots(cwd) {
+  const roots = []
+  try {
+    if (!cwd) return roots
+    const localYamlPath = join(cwd, '.sillyspec', 'local.yaml')
+    if (!existsSync(localYamlPath)) return roots
+    const registry = parseRepoRegistry(readFileSync(localYamlPath, 'utf8'))
+    if (!registry) return roots
+    for (const raw of registry.values()) {
+      if (!raw) continue
+      const root = isAbsolute(raw) ? raw : resolve(cwd, raw)
+      if (root && existsSync(root)) roots.push(root)
+    }
+  } catch { /* registry 不可读 → 空表（fail-open） */ }
+  return roots
+}
+
 function prefetchDiffFileSet(ctx) {
   if (!ctx?.gitDir || !ctx.base || !ctx.head) return ctx
   try {
@@ -1030,6 +1069,37 @@ function prefetchDiffFileSet(ctx) {
       const n = String(b).replace(/\\/g, '/').trim()
       if (n) diffFileSet.delete(n)
     }
+    // task-05 FR-08：跨仓仓根 diff 双源并入（adopt 通道跨仓 review 的 changedFiles 是其仓根
+    // 相对路径，只算主仓源时 shouldAutoCheckTask 的 ctx.diffFileSet.has(f) 恒 miss → 跨仓
+    // task 自动勾选断链）。双源 = git diff --name-only HEAD~1..HEAD ∪ git status --porcelain
+    // --untracked-files=all（cross-repo-reconcile.js:94-106 双源口径只读复用，数组参数防
+    // shell 拆词），产物正斜杠归一；置于剔 baseline 之后（跨仓仓不含主仓 baseline checkpoint
+    // 提交，不被主仓夹带清单误剔）。git 失败/registry 不可读 fail-open 跳过该仓不炸主流程。
+    try {
+      for (const root of collectCrossRepoDiffRoots(ctx.cwd)) {
+        let anySource = false
+        const diffOut = gitQuiet(root, ['diff', '--name-only', 'HEAD~1..HEAD'], { timeout: 30 * 1000 })
+        if (diffOut !== null) {
+          anySource = true
+          for (const f of String(diffOut).split('\n')) {
+            const n = String(f || '').trim().replace(/^\.\//, '').replace(/\\/g, '/')
+            if (n) diffFileSet.add(n)
+          }
+        }
+        const statusOut = gitQuiet(root, ['status', '--porcelain', '--untracked-files=all'], { timeout: 30 * 1000, trim: false })
+        if (statusOut !== null) {
+          anySource = true
+          for (const line of String(statusOut).split('\n')) {
+            // porcelain 行 = XY<space>path（剥前 3 列）；rename 取 -> 后新路径；剥引号、正斜杠归一
+            let p = line.slice(3).trim()
+            if (p.includes(' -> ')) p = p.slice(p.lastIndexOf(' -> ') + 4).trim()
+            p = p.replace(/^"|"$/g, '').replace(/\\/g, '/')
+            if (p) diffFileSet.add(p)
+          }
+        }
+        if (!anySource) console.warn(`⚠️ 跨仓仓根 ${root} git 不可用/非仓库（diff 与 status 双失败），跳过该仓 diff 源（fail-open，不阻断勾选主流程）`)
+      }
+    } catch { /* 跨仓源异常 → 不炸主流程（fail-open） */ }
     if (diffFileSet.size === 0) return ctx
     return { ...ctx, diffFileSet }
   } catch {