sillyspec 3.28.8 → 3.28.10

package/src/task-review.js

@@ -10,6 +10,7 @@
 
 import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync, statSync } from 'fs'
 import { join, resolve, basename, dirname } from 'path'
+import { execFileSync } from 'child_process'
 import { git, unquoteGitPath } from './git-helper.js'
 import { pathMatches } from './change-list.js'
 import { parseAllowedPaths, parseRepo, parseBaseCommit, parseHeadCommit } from './stages/plan-postcheck.js'
@@ -17,6 +18,7 @@ import { resolveVerifyChangedFiles } from './verify-postcheck.js'
 import { splitOwnVsForeignDiffFiles } from './foreign-declared.js'
 import { WorktreeManager } from './worktree.js'
 import { resolveRuntimeRoot } from './run/shared.js'
+import { DB } from './db.js'
 
 // ── review.json schema version ──
 //
@@ -334,6 +336,26 @@ export function readReview(reviewPath) {
   return { ok: true, review: parsed, errors: [] }
 }
 
+/**
+ * 判定 review 是否经显式 CLI 命令式写入（`sillyspec review write` → writeTaskReview）。
+ * （ql-20260915-001 修复②，坑 review-write-draft-marker-stuck：execute 期间反复
+ * 「草稿 review changedFiles 为空，跳过自动勾选」，主仓文档面任务自动勾选断链。）
+ *
+ * 判据：reviewProvenanceStamp 落的 writtenBy 以 'writeTaskReview' 开头（含 ':force' 变体）。
+ * 显式写入带 agent 供给的 verdict（非草稿兜底通道），即使 reviewerNotes 字面残留
+ * 'auto-generated draft'（agent 升级草稿时 --notes 引用/复述草稿文案、或 adopt 通道合并
+ * 保留旧 notes 的变体）也一律按非草稿处理——verdict 判定不再受草稿零 diff 守卫限制。
+ *
+ * 无 writtenBy 的存量 review（provenance 机制引入前手写）按非显式处理，走原 notes
+ * 启发式判定（向后兼容，行为不回退）。
+ *
+ * @param {object|null} review readReview 返回的 review 对象
+ * @returns {boolean}
+ */
+export function isExplicitReviewWrite(review) {
+  return typeof review?.writtenBy === 'string' && review.writtenBy.startsWith('writeTaskReview')
+}
+
 /**
  * 校验 plan.md 里所有「已勾选 [x]」task 的 review.json 是否 schema 完整（坑 review-json-field-gap）。
  *
@@ -1103,6 +1125,194 @@ export function resolveExecuteRunForChange({ runtimeRoot, changeName, taskIds =
   }
 }
 
+// ── 归因模式分流（2026-09-14-change-ownership-guards task-03 / D-004@v1 / FR-03）──
+// 草稿/changedFiles 归因的取数源路由：判定源=changes.isolation_mode 列（DB 读，meta 缺失也可判，
+// 与 change-registry.readChangeIsolation 同列；此处直连 db.js 读——task-review 是叶子模块，
+// 静态 import progress.js 会成环 progress→consistency-doctor→task-review）。进程内按
+// dbPath+change 缓存（CLI 短进程生命周期内 isolation_mode 不变，避免重复 open/init）。
+const _isolationModeCache = new Map()
+
+/**
+ * 读 changes.isolation_mode（只读；无库/无行/读失败 → null）。DB 路径候选序：
+ * platformOpts.specRoot > specDriftAnchor > specBase > cwd/.sillyspec（首个存在 sillyspec.db 的根）。
+ * 模块内函数（非 export——check-syntax 22e-b 死码门禁：无跨文件消费不导出）。
+ * @param {{ cwd: string, specBase: string, platformOpts?: object, changeName: string }} opts
+ * @returns {string|null} isolation_mode（'worktree'|'native-worktree'|'in-place-fallback'）或 null
+ */
+function readChangeIsolationMode({ cwd, specBase, platformOpts = {}, changeName }) {
+  if (!changeName) return null
+  const roots = []
+  const addRoot = (r) => { if (r && !roots.includes(r)) roots.push(r) }
+  addRoot(platformOpts && platformOpts.specRoot)
+  addRoot(platformOpts && platformOpts.specDriftAnchor)
+  addRoot(specBase)
+  addRoot(join(cwd, '.sillyspec'))
+  for (const root of roots) {
+    const dbPath = join(root, '.runtime', 'sillyspec.db')
+    if (!existsSync(dbPath)) continue
+    const key = dbPath + '::' + changeName
+    if (_isolationModeCache.has(key)) return _isolationModeCache.get(key)
+    let mode = null
+    try {
+      const db = new DB(dbPath)
+      db.init()
+      const row = db.getDb().prepare('SELECT isolation_mode FROM changes WHERE name = ?').get(changeName)
+      mode = (row && typeof row.isolation_mode === 'string' && row.isolation_mode) || null
+    } catch { mode = null }
+    _isolationModeCache.set(key, mode)
+    return mode
+  }
+  return null
+}
+
+/**
+ * 归因取数源路由（单一入口，草稿生成 generateTaskReviewDrafts 与 mechanics 代算 writeTaskReview
+ * 两处共用）。判定优先级（D-004）：
+ *   1. DB isolation_mode ∈ {worktree, native-worktree} → worktree 归因：worktree 目录活则原口径
+ *      （resolveVerifyChangedFiles meta 路径 + porcelain 并入，零回归）；meta 缺失/in-place meta/
+ *      目录已删 → 分支 ref 口径（merge-base(主仓 HEAD, 分支 tip)..tip 的 commit diff + worktree
+ *      目录在则 porcelain 并入，与 verify reconcile 同口径）。分支 ref 也已删（cleanup 后态）→
+ *      fail-closed 空集 +「不可归因（worktree 已清理）」注记，绝不回退主仓窗口（复审残留①）。
+ *   2. DB in-place-fallback 但 meta 判 worktree 且目录活 → 仍取 worktree（fail-safe：不因 DB 行
+ *      陈旧切向主仓共享脏窗口——归因源只会更隔离不会更共享），注记不一致。
+ *   3. 其余（DB in-place / NULL）→ 主仓窗口原行为零回归；NULL 且 meta 缺失加存量路由注记
+ *      （存量态不追求完美只保安全，D-004 残留②/R-04）。
+ * meta 在时交叉校验不一致以 DB 为准（方向 1 的 worktree 覆盖）；返回 notes 逐条说明路由依据。
+ *
+ * @param {{ cwd: string, changeName: string, specBase: string, platformOpts?: object }} opts
+ * @returns {{ mode: 'worktree'|'worktree-branch'|'worktree-cleaned'|'main-window', diffFiles: string[]|null, notes: string[], meta: object|null, mergeGitDir: string|null, branch?: string, branchBase?: string, branchHead?: string }}
+ */
+function resolveAttributionDiffFiles({ cwd, changeName, specBase, platformOpts = {} }) {
+  const notes = []
+  const wm = new WorktreeManager({ cwd })
+  let meta = null
+  try { meta = wm.getMeta(changeName) } catch { meta = null }
+  const iso = readChangeIsolationMode({ cwd, specBase, platformOpts, changeName })
+  const isoWorktree = iso === 'worktree' || iso === 'native-worktree'
+
+  if (isoWorktree) {
+    const wtGitDir = (meta && meta.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath))
+      ? meta.worktreePath
+      : null
+    if (wtGitDir) {
+      if (meta.mode !== iso) notes.push(`meta.mode=${meta.mode} 与 DB isolation_mode=${iso} 不一致——以 DB 为准（同属 worktree 族，归因源不变）`)
+      return { mode: 'worktree', diffFiles: resolveVerifyChangedFiles(cwd, changeName, null, { specBase }), notes, meta, mergeGitDir: wtGitDir }
+    }
+    // meta 缺失 / in-place meta / worktree 目录已删：分支 ref 判定（不落主仓窗口）
+    const branch = (meta && meta.branch) || `sillyspec/${changeName}`
+    let branchTip = null
+    try { branchTip = runGit(cwd, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`]) } catch { branchTip = null }
+    if (!branchTip) {
+      notes.push(`不可归因（worktree 已清理）——DB 判 worktree（isolation_mode=${iso}）但分支 ref ${branch} 不存在（cleanup 后态），fail-closed 空集，不回退主仓窗口`)
+      return { mode: 'worktree-cleaned', diffFiles: [], notes, meta, mergeGitDir: null }
+    }
+    let branchBase = null
+    let files = []
+    try {
+      const mainHead = runGit(cwd, ['rev-parse', 'HEAD'])
+      const mb = mainHead ? runGit(cwd, ['merge-base', branchTip, mainHead]) : null
+      branchBase = mb || mainHead || null
+      if (branchBase) {
+        files = String(runGit(cwd, ['diff', '--name-only', branchBase, branchTip]) || '')
+          .split('\n').map(p => p.replace(/^"|"$/g, '').replace(/\\/g, '/').trim())
+          .filter(p => p && p !== '.sillyspec' && !p.startsWith('.sillyspec/'))
+      }
+    } catch { /* 已提交口径 git 失败 → 空集 fail-closed（不回退主仓窗口） */ }
+    // 未提交并入：约定路径 worktree 目录仍在（meta 失联孤儿）→ porcelain（与 verify reconcile 同口径）
+    const wtDirGuess = join(wm.worktreeBase, changeName)
+    if (existsSync(wtDirGuess)) {
+      try {
+        const st = runGit(wtDirGuess, ['status', '--porcelain', '--untracked-files=all'], { trim: false })
+        const wtFiles = parsePorcelainFiles(st)
+          .map(p => String(p).replace(/\\/g, '/'))
+          .filter(p => p !== '.sillyspec' && !p.startsWith('.sillyspec/'))
+        files = [...new Set([...files, ...wtFiles])]
+      } catch { /* porcelain 失败退回 commit diff 口径 */ }
+    }
+    notes.push(`meta 缺失/失效，DB isolation_mode=${iso} 判 worktree——归因源=worktree 分支 ${branch} diff（base..HEAD+porcelain，与 verify reconcile 同口径），不落主仓共享脏窗口`)
+    return { mode: 'worktree-branch', diffFiles: files, notes, meta, mergeGitDir: null, branch, branchBase, branchHead: branchTip }
+  }
+
+  if (iso === 'in-place-fallback' && meta && meta.mode !== 'in-place-fallback'
+    && meta.worktreePath && existsSync(meta.worktreePath)) {
+    notes.push(`DB isolation_mode=in-place-fallback 但 meta.mode=${meta.mode}——worktree 分支仍是隔离归因源（fail-safe：不因 DB 行陈旧切向主仓共享窗口），按 meta 取 worktree 归因`)
+    return { mode: 'worktree', diffFiles: resolveVerifyChangedFiles(cwd, changeName, null, { specBase }), notes, meta, mergeGitDir: meta.worktreePath }
+  }
+
+  // in-place（DB 或 meta）与 NULL 存量：主仓窗口（原行为零回归）
+  if (!meta && iso === null) {
+    notes.push('isolation_mode 未登记（存量变更/无 DB 行）且 worktree meta 缺失——按主仓窗口归因（存量兼容路由，D-004 残留②：不追求完美只保安全）')
+  }
+  const mergeGitDir = meta
+    ? ((meta.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath)) ? meta.worktreePath : cwd)
+    : null
+  return { mode: 'main-window', diffFiles: resolveVerifyChangedFiles(cwd, changeName, null, { specBase }), notes, meta, mergeGitDir }
+}
+
+/**
+ * worktree/in-place 改动文件集：porcelain 未提交 ∪ committed merge-base 补齐——口径单一化。
+ * 口径出处：D-004@v1（worktree 归因唯一事实源 = worktree 分支 diff + porcelain，决策库
+ * decisions/worktree.md）+ 变更 2026-09-15-worktree-dual-truth-gates §4 / FR-04；坑④
+ * worktree-tick-guard-commit-only（2026-09-15 实证）：勾选守卫 prefetchDiffFileSet
+ * （run/complete.js）只算 base..head（已提交），子代理默认不 commit 时守卫恒空跳过勾选——
+ * 本 helper 是「草稿归属并入段（generateTaskReviewDrafts）」与「勾选守卫（prefetchDiffFileSet）」
+ * 两处的单一真相。已知残留 R-09：resolveVerifyChangedFiles（verify-postcheck.js）内另有同型
+ * 补齐段（form A 专属：滤网保 .sillyspec/docs/** 交付物，与本 helper 的整前缀滤网不同），
+ * 本次不动，待该函数下次触碰时统一。
+ *
+ * 行为契约：
+ *   - meta 缺省时内部 WorktreeManager.getMeta 自取（try/catch → null）。
+ *   - gitDir = meta.worktreePath（mode 非 in-place-fallback 且目录存在）否则 cwd——
+ *     in-place 退化取 cwd（保住现状 in-place 主仓 porcelain 并入，不丢，R-08）；
+ *     meta 完全缺失时同样取 cwd（与被并入段 mergeGitDir 语义一致）。
+ *   - porcelain：status --porcelain --untracked-files=all（parsePorcelainFiles 解析），
+ *     滤 .sillyspec 前缀（与被替换的草稿并入段同口径）。
+ *   - committed 补齐（仅 gitDir !== cwd，防双并）：merge-base(主仓 HEAD, wtHEAD)..wtHEAD
+ *     的 diff --name-only——worktree 内已 commit 的改动对主仓 base..head 与 status 双不可见
+ *     （「先提交则 diff 空」时序两难）；git 失败 fail-open 忽略。
+ *   - 返回正斜杠归一去重数组；任何 git 异常 → 已收集部分或 []（fail-open，不阻断调用方）。
+ *
+ * @param {string} cwd 主仓根
+ * @param {string} changeName 变更名
+ * @param {object|null} [meta] 预取的 worktree meta（缺省内部 getMeta 自取）
+ * @param {object} [opts] 预留（对齐 design 接口签名）
+ * @returns {string[]} 正斜杠归一文件集（git 失败 → 已收集部分或 []，fail-open）
+ */
+export function collectWorktreeChangedFiles(cwd, changeName, meta = null, opts = {}) {
+  const files = new Set()
+  if (!cwd || !changeName) return []
+  let m = meta
+  if (m == null) {
+    try { m = new WorktreeManager({ cwd }).getMeta(changeName) } catch { m = null }
+  }
+  const gitDir = (m?.worktreePath && m.mode !== 'in-place-fallback' && existsSync(m.worktreePath))
+    ? m.worktreePath
+    : cwd
+  const keep = (p) => p && p !== '.sillyspec' && !p.startsWith('.sillyspec/')
+  // 未提交：worktree（in-place 退化=主仓）porcelain 全量（含 untracked）
+  try {
+    const st = runGit(gitDir, ['status', '--porcelain', '--untracked-files=all'], { trim: false })
+    for (const p of parsePorcelainFiles(st)) if (keep(p)) files.add(p)
+  } catch { /* porcelain 失败 → 返回已收集部分（fail-open） */ }
+  // 已提交补齐：merge-base(主仓 HEAD, wtHEAD)（= 创建锚点）..wtHEAD 的 commit diff。
+  // in-place（gitDir===cwd）时已提交改动在主仓 diff 内，跳过防双并；失败 fail-open 忽略。
+  if (gitDir !== cwd) {
+    try {
+      const mainHead = runGit(cwd, ['rev-parse', 'HEAD'])
+      const wtHead = runGit(gitDir, ['rev-parse', 'HEAD'])
+      const mb = (mainHead && wtHead) ? runGit(gitDir, ['merge-base', wtHead, mainHead]) : null
+      if (mb) {
+        const out = String(runGit(gitDir, ['diff', '--name-only', mb, wtHead]) || '')
+        for (let p of out.split('\n')) {
+          p = p.replace(/^"|"$/g, '').replace(/\\/g, '/').trim()
+          if (keep(p)) files.add(p)
+        }
+      }
+    } catch { /* 已提交补齐失败忽略（fail-open，不拖垮未提交并入） */ }
+  }
+  return [...files]
+}
+
 /**
  * worktree execute「主 agent 直接实现」模式收尾兜底：per-task review.json 缺失时，
  * 据 git diff base..head 按 task allowed_paths 归属，自动落盘 cannot_verify 草稿。
@@ -1170,53 +1380,54 @@ export async function generateTaskReviewDrafts({ changeName, cwd, platformOpts =
     }
   }
 
+  // ── 归因模式分流（task-03 / D-004@v1）：判定源=changes.isolation_mode（DB 读）──
+  // worktree 模式（含 meta 缺失回退态）归因唯一源=worktree 分支 diff（绝不落主仓共享脏窗口，
+  // troubleshooting §65 事件②根因）；in-place 维持主仓窗口；NULL 存量按 meta 在场路由。
+  // 分流自身异常 → 退回原 resolveVerifyChangedFiles 口径（fail-open，不比修复前差）。
+  let attribution
+  try {
+    attribution = resolveAttributionDiffFiles({ cwd, changeName, specBase, platformOpts })
+  } catch (e) {
+    attribution = { mode: 'main-window', diffFiles: resolveVerifyChangedFiles(cwd, changeName, null, { specBase }), notes: [`归因分流解析异常（${e && e.message ? e.message : e}）——退回原口径`], meta: null, mergeGitDir: null }
+  }
+  for (const note of attribution.notes) console.log(`[sillyspec] 归因注记：${note}`)
   // base..head diff 文件集（worktree-aware；null=git 不可用，[]=无 commit diff）
-  let diffFiles = resolveVerifyChangedFiles(cwd, changeName, null, { specBase })
+  let diffFiles = attribution.diffFiles
   // ⚠️ 并入 worktree 未提交改动（坑 draft-attribution-uncommitted-worktree，2026-08-21 实证）：
   // 子代理默认不 commit（execute 复盘 a 同源事实），真实改动全在 worktree working-tree——只看
   // base..HEAD commit diff 时归属恒空，9/9 草稿全成「无归属」靠主代理手写升级。与
   // verifyReviewGitEvidence 的 working-tree 并入口径同源：status --porcelain 文件（排除
   // .sillyspec/ 运行时产物）并入归属集，按 allowed_paths 正常路径归属；review.head 仍为 HEAD
   // commit——evidence 校验对「commit diff 空 + working-tree 有改动」明示不判伪造，语义一致。
-  try {
-    const wm = new WorktreeManager({ cwd })
-    const meta = wm.getMeta(changeName)
-    if (meta) {
-      const wtGitDir = (meta.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath))
-        ? meta.worktreePath
-        : cwd
-      const wtStatus = runGit(wtGitDir, ['status', '--porcelain', '--untracked-files=all'], { trim: false })
-      const wtFiles = parsePorcelainFiles(wtStatus)
-        .map(p => String(p).replace(/\\/g, '/'))
-        .filter(p => p !== '.sillyspec' && !p.startsWith('.sillyspec/'))
-      // 已提交口径补齐（2026-09-10 用户反馈②「先提交则 diff 空」：worktree 内已 commit 的改动
-      // 对主仓 base..head 与 status 双不可见，草稿 changedFiles 恒空）——merge-base(主仓 HEAD,
-      // worktree HEAD)（= 创建锚点）..worktree HEAD 的 commit diff 并入，与
-      // resolveVerifyChangedFiles 的同款补齐同源（verify-postcheck.js，两处口径须同步改）。
-      // in-place 退化（wtGitDir===cwd）时已提交改动在主仓 diff 内，跳过防双并；git 失败 fail-open。
-      let committedFiles = []
-      if (wtGitDir !== cwd) {
-        try {
-          const mainHead = runGit(cwd, ['rev-parse', 'HEAD'])
-          const wtHead = runGit(wtGitDir, ['rev-parse', 'HEAD'])
-          const mb = (mainHead && wtHead) ? runGit(wtGitDir, ['merge-base', wtHead, mainHead]) : null
-          if (mb) {
-            committedFiles = String(runGit(wtGitDir, ['diff', '--name-only', mb, wtHead]) || '')
-              .split('\n').map(p => p.replace(/^"|"$/g, '').replace(/\\/g, '/').trim())
-              .filter(p => p && p !== '.sillyspec' && !p.startsWith('.sillyspec/'))
-          }
-        } catch { /* 已提交补齐失败退回 status-only（fail-open，不拖垮未提交并入） */ }
-      }
-      if (wtFiles.length > 0 || committedFiles.length > 0) {
-        diffFiles = [...new Set([...(Array.isArray(diffFiles) ? diffFiles : []), ...wtFiles, ...committedFiles])]
-        console.log(`[sillyspec] 草稿归属并入 worktree 改动 ${wtFiles.length + committedFiles.length} 个（未提交 ${wtFiles.length} + 已提交 ${committedFiles.length}，按 allowed_paths 归属）`)
+  // D-004 后仅在归因源指向活跃 worktree 目录 / in-place meta（mergeGitDir）时执行——
+  // worktree-branch/cleaned 归因的未提交并入已在 resolveAttributionDiffFiles 内按同口径完成。
+  if (attribution.mergeGitDir) {
+    try {
+      // D-004@v1 口径单一化（坑④ worktree-tick-guard-commit-only，2026-09-15 实证）：原手写
+      // 并入段（porcelain 未提交 + committed merge-base 补齐两段）收口为
+      // collectWorktreeChangedFiles 单一真相——勾选守卫 prefetchDiffFileSet（run/complete.js）
+      // 与本草稿归属自此消费同一口径（原「两处口径须同步改」注记就此作废，单一真相在 helper）。
+      // in-place（mergeGitDir===cwd）时 helper 同取 cwd porcelain（现状主仓并入不丢）。
+      // resolveVerifyChangedFiles（verify-postcheck.js）内另有同型补齐段（form A 专属，滤网保
+      // .sillyspec/docs/** 交付物），已知残留 R-09，本次不动。
+      const mergedFiles = collectWorktreeChangedFiles(cwd, changeName, attribution.meta)
+      if (mergedFiles.length > 0) {
+        diffFiles = [...new Set([...(Array.isArray(diffFiles) ? diffFiles : []), ...mergedFiles])]
+        console.log(`[sillyspec] 草稿归属并入 worktree 改动 ${mergedFiles.length} 个（未提交 porcelain + 已提交 merge-base 补齐，按 allowed_paths 归属）`)
       }
-    }
-  } catch { /* working-tree 并入失败退回 commit diff 口径（fail-open，不阻断草稿） */ }
+    } catch { /* working-tree 并入失败退回 commit diff 口径（fail-open，不阻断草稿） */ }
+  }
   // 单仓模式（无 ctx）：主仓无 diff 即无任何 task 可生成 → 提前返回（原逻辑零回归）。
   // 有 ctx：主仓无 diff 不阻断——跨仓 task 的 diff 在跨仓仓根独立取（per-task），主仓 task 自然跳过（空 changedFiles）。
+  // 终态空源（D-004）：worktree-cleaned（DB 判 worktree 但分支 ref 已删）空集的 reason 显式
+  // 注记「不可归因」，与普通「无 diff」区分——绝不回退主仓窗口补救。
   if (!ctx && (!diffFiles || diffFiles.length === 0)) {
-    return { generated: 0, skipped: 0, unattributed: [], executeRunId, reason: 'base..head 无代码 diff（改动未 commit？）' }
+    return {
+      generated: 0, skipped: 0, unattributed: [], executeRunId,
+      reason: attribution.mode === 'worktree-cleaned'
+        ? '不可归因（worktree 已清理）——DB 判 worktree 但分支 ref 已删，fail-closed 空集（不回退主仓窗口）'
+        : 'base..head 无代码 diff（改动未 commit？）',
+    }
   }
 
   // base/head + gitDir：与 gates.js reviewGitDir 同源（worktree 优先，in-place 回退 cwd）
@@ -1248,6 +1459,15 @@ export async function generateTaskReviewDrafts({ changeName, cwd, platformOpts =
       // 有 ctx：主仓 HEAD 失败不阻断跨仓 task；head 留 null，主仓 task 后续按空 changedFiles 跳过
     }
   }
+  // worktree-branch 归因的 base/head 锚定（task-03 / D-004）：meta 缺失但分支 ref 活着时用
+  // merge-base(主仓 HEAD, 分支 tip)=创建锚点..分支 tip 锚定——DB 判 worktree 的回退态仍能
+  // 生成带真实 git 锚点的草稿（否则上方「无 meta.baseHash」早退白费分支归因成果）。分支 ref
+  // 在主仓共享 .git 内，reviewGitDir=cwd 可解析，evidence 校验的 base..head diff 与归因同源。
+  if (!base && attribution.branchBase && attribution.branchHead) {
+    base = attribution.branchBase
+    head = attribution.branchHead
+    reviewGitDir = cwd
+  }
 
   const taskFiles = readdirSync(tasksDir).filter(f => /^task-\d+\.md$/.test(f)).sort()
   let generated = 0
@@ -1652,6 +1872,89 @@ export async function adoptTaskReviewMechanics({ changeName, cwd, platformOpts =
  * @param {object} [opts.platformOpts]
  * @returns {Promise<{ok: boolean, reviewPath?: string, executeRunId?: string, errors: string[], warnings: string[]}>}
  */
+// ── ql-20260915-003 修复③（坑 interrupted-residue-detect，2026-09-15 用户实证：中断的
+// execute 子代理在工作区留下半成品 import 语法坏文件，无自动检测靠人工 diff 发现）──
+//
+// 对 changedFiles 中的 .js/.mjs/.cjs 逐个 `node --check`（子进程数组形式不经 shell，单文件
+// 5s 超时；总数 >60 抽样前 60 并提示——大变更全量查的耗时不可接受）。
+//
+// 判定分层（Node v24 实测：.js 的 file-check 受最近 package.json type 影响——无 type 时
+// ESM 半成品可能静默通过、合法 ESM 又会报 import 语句误错）：
+//   - .mjs/.cjs：file-check 权威（对应 module/commonjs 全量解析）
+//   - .js：file-check **与** stdin `--input-type=module` check 双跑，两者都报 SyntaxError
+//     才判残留（合法 ESM / 合法 CJS（含 sloppy-mode）必有一路通过，零假阳；真断档半成品
+//     两路都挂）。stdin check 不可用/无 SyntaxError 字样 → fail-open 跳过该文件。
+//
+// 语法失败 → 返回「疑似中断残留」warning（advisory：只提醒，不改 verdict / 勾选语义 /
+// 落盘行为——quick --done 的 test/lint 实测硬门才是卡点，这里补「中断半成品」的可见性）。
+// 文件在候选根下不存在（diff 里的删除态文件等）直接跳过；超时（e.killed）无法定论不报警。
+// 仅 review write 时点执行一次，非热路径。
+const SYNTAX_CHECK_EXT_RE = /\.(?:js|mjs|cjs)$/
+const SYNTAX_CHECK_MAX_FILES = 60
+// 严格 .js（.mjs/.cjs 也 endsWith('.js')，须排除——否则 sloppy-mode .cjs 会误入 stdin ESM
+// 复核路径产生假阳）
+const isPlainJs = (f) => f.endsWith('.js') && !f.endsWith('.mjs') && !f.endsWith('.cjs')
+function _syntaxErrLine(e) {
+  const raw = String((e.stderr && e.stderr.toString()) || e.message || '')
+  const line = raw.split('\n').find(l => l.includes('SyntaxError'))
+  return line ? line.trim() : null
+}
+function detectInterruptedSyntaxResidue(changedFiles, candidateRoots) {
+  const warnings = []
+  const jsFiles = (Array.isArray(changedFiles) ? changedFiles : [])
+    .filter(f => typeof f === 'string' && SYNTAX_CHECK_EXT_RE.test(f))
+  if (jsFiles.length === 0) return warnings
+  const overCap = jsFiles.length > SYNTAX_CHECK_MAX_FILES
+  for (const f of overCap ? jsFiles.slice(0, SYNTAX_CHECK_MAX_FILES) : jsFiles) {
+    let abs = null
+    for (const root of candidateRoots) {
+      if (!root) continue
+      const p = join(root, f)
+      if (existsSync(p)) { abs = p; break }
+    }
+    if (!abs) continue
+    try {
+      execFileSync(process.execPath, ['--check', abs], { timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] })
+      if (isPlainJs(f)) {
+        // 无 type:module 上下文的 .js：file-check 通过不代表语法完整（Node v24 实测假阴），
+        // 再跑 stdin ESM 全量解析兜底——两路都挂才判残留
+        let src = ''
+        try { src = readFileSync(abs, 'utf8') } catch { continue }
+        try {
+          execFileSync(process.execPath, ['--input-type=module', '--check'], { input: src, timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] })
+        } catch (e2) {
+          if (e2 && e2.killed) continue
+          const line = _syntaxErrLine(e2)
+          if (!line) continue // 非 SyntaxError（如版本不支持 stdin check）→ fail-open
+          warnings.push(`⚠️ 疑似中断残留：${f} 语法错误（${line}）——子代理异常退出可能留下半成品，请 diff 该文件确认还原或补完`)
+        }
+      }
+    } catch (e) {
+      if (e && e.killed) continue // 单文件超时：无法定论，不产假阳 warning
+      if (!isPlainJs(f)) {
+        const line = _syntaxErrLine(e)
+        if (line) warnings.push(`⚠️ 疑似中断残留：${f} 语法错误（${line}）——子代理异常退出可能留下半成品，请 diff 该文件确认还原或补完`)
+        continue
+      }
+      // .js file-check 挂可能是模块口径误错（合法 ESM 在无 type 上下文报 import 语句）——
+      // stdin ESM 解析仲裁：也挂才算真残留
+      let src = ''
+      try { src = readFileSync(abs, 'utf8') } catch { continue }
+      try {
+        execFileSync(process.execPath, ['--input-type=module', '--check'], { input: src, timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] })
+      } catch (e2) {
+        if (e2 && e2.killed) continue
+        const line = _syntaxErrLine(e2) || _syntaxErrLine(e)
+        if (line) warnings.push(`⚠️ 疑似中断残留：${f} 语法错误（${line}）——子代理异常退出可能留下半成品，请 diff 该文件确认还原或补完`)
+      }
+    }
+  }
+  if (overCap) {
+    warnings.push(`⚠️ 中断残留检测抽样：changedFiles 含 ${jsFiles.length} 个 .js 系文件，仅语法检查前 ${SYNTAX_CHECK_MAX_FILES} 个（interrupted-residue-detect）`)
+  }
+  return warnings
+}
+
 export async function writeTaskReview({
   changeName, cwd, taskId, specVerdict, qualityVerdict,
   reviewerNotes = '', requiredEvidence = [],
@@ -1758,22 +2061,30 @@ export async function writeTaskReview({
     changedFiles = changedFilesOverride.map(p => String(p).replace(/\\/g, '/'))
     warnings.push(`changedFiles 采用显式覆盖（${changedFiles.length} 个）——evidence 校验仍会与 git diff 相交比对`)
   } else {
-    let diffFiles = resolveVerifyChangedFiles(cwd, changeName, null, { specBase })
-    // 并入 worktree 未提交改动（与草稿生成同源口径：子代理默认不 commit）
+    // ── 归因模式分流（task-03 / D-004@v1）：与草稿生成同源路由（判定源=changes.isolation_mode）──
+    // worktree 模式（含 meta 缺失回退态）取 worktree 分支 diff，绝不落主仓共享脏窗口；
+    // in-place/NULL 存量维持主仓窗口原口径。分流异常退回原 resolveVerifyChangedFiles（fail-open）。
+    let attribution
     try {
-      const wm = new WorktreeManager({ cwd })
-      const meta = wm.getMeta(changeName)
-      if (meta) {
-        const wtGitDir = (meta.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath))
-          ? meta.worktreePath
-          : cwd
+      attribution = resolveAttributionDiffFiles({ cwd, changeName, specBase, platformOpts })
+    } catch (e) {
+      attribution = { mode: 'main-window', diffFiles: resolveVerifyChangedFiles(cwd, changeName, null, { specBase }), notes: [`归因分流解析异常（${e && e.message ? e.message : e}）——退回原口径`], meta: null, mergeGitDir: null }
+    }
+    for (const note of attribution.notes) warnings.push(`归因注记：${note}`)
+    let diffFiles = attribution.diffFiles
+    // 并入 worktree 未提交改动（与草稿生成同源口径：子代理默认不 commit）。D-004 后仅在
+    // 归因源指向活跃 worktree 目录 / in-place meta（mergeGitDir）时执行——worktree-branch/
+    // cleaned 归因的未提交并入已在 resolveAttributionDiffFiles 内按同口径完成。
+    if (attribution.mergeGitDir) {
+      try {
+        const wtGitDir = attribution.mergeGitDir
         const wtStatus = runGit(wtGitDir, ['status', '--porcelain', '--untracked-files=all'], { trim: false })
         const wtFiles = parsePorcelainFiles(wtStatus)
           .map(p => String(p).replace(/\\/g, '/'))
           .filter(p => p !== '.sillyspec' && !p.startsWith('.sillyspec/'))
         if (wtFiles.length > 0) diffFiles = [...new Set([...(Array.isArray(diffFiles) ? diffFiles : []), ...wtFiles])]
-      }
-    } catch { /* 退回 commit diff 口径 */ }
+      } catch { /* 退回 commit diff 口径 */ }
+    }
     const mainDiff = Array.isArray(diffFiles) ? diffFiles : []
     changedFiles = allowedPaths.length > 0
       ? mainDiff.filter(f => allowedPaths.some(p => pathMatches(f, p)))
@@ -1791,6 +2102,15 @@ export async function writeTaskReview({
     }
   }
 
+  // ── ql-20260915-003 修复③（坑 interrupted-residue-detect）：changedFiles 定稿后的
+  // 语法检查（advisory warning，见 detectInterruptedSyntaxResidue 注释）。候选根依次试
+  // reviewGitDir（meta 活跃时的 worktree 根）、cwd、worktree-branch 归因的孤儿目录兜底。
+  for (const w of detectInterruptedSyntaxResidue(changedFiles, [
+    reviewGitDir,
+    cwd,
+    join(cwd, '.sillyspec', '.runtime', 'worktrees', changeName),
+  ])) warnings.push(w)
+
   // ── 组装 + schema 自检 + 落盘 ──
   const review = {
     schemaVersion: REVIEW_SCHEMA_VERSION,