sillyspec 3.26.11 → 3.26.13

package/src/task-review.js

@@ -10,7 +10,7 @@
 
 import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync, statSync } from 'fs'
 import { join, resolve } from 'path'
-import { execFileSync } from 'child_process'
+import { git } from './git-helper.js'
 import { pathMatches } from './change-list.js'
 import { parseAllowedPaths, parseRepo, parseBaseCommit, parseHeadCommit } from './stages/plan-postcheck.js'
 import { resolveVerifyChangedFiles } from './verify-postcheck.js'
@@ -105,64 +105,63 @@ export function summarizeTaskCompletion({ changeDir, runtimeRoot, changeName })
   }
   if (!changeDir) return noPlan
 
+  // 2026-08-20-task-truth-unify：任务清单唯一真相在 tasks.md，优先读注册表；plan.md 回退
+  // （旧归档变更兼容读侧——新契约 plan.md 为纯 ID 引用行，无 checkbox 可解析）
   const planPath = join(changeDir, 'plan.md')
   const tasksPath = join(changeDir, 'tasks.md')
   let planContent = null
-  if (existsSync(planPath)) planContent = readFileSync(planPath, 'utf8')
-  else if (existsSync(tasksPath)) planContent = readFileSync(tasksPath, 'utf8')
+  if (existsSync(tasksPath)) planContent = readFileSync(tasksPath, 'utf8')
+  else if (existsSync(planPath)) planContent = readFileSync(planPath, 'utf8')
   else return noPlan
 
   const taskIds = parseTaskIdsFromPlan(planContent)
   if (taskIds.length === 0) {
     return { source: 'no-tasks', total: 0, completed: 0, pending: [],
-      report: '⚠️ plan.md 未解析出任何 task-NN 条目（plan 可能未按规范写 checkbox 列表）。' }
+      report: '⚠️ tasks.md 未解析出任何 task-NN 条目（任务注册表可能未按规范写 checkbox 列表）。' }
   }
 
-  // runId 解析：marker → 扫描最新目录（marker 是 agent 可写内容，格式校验防注入/穿越）
-  let runId = null
-  const marker = join(runtimeRoot, `current-execute-run-id-${changeName}`)
-  try {
-    if (existsSync(marker)) {
-      const c = readFileSync(marker, 'utf8').trim()
-      if (c && !isValidExecuteRunId(c)) console.warn(`[sillyspec] execute run marker 内容非法（期望 exec-YYYY-MM-DD-HHMMSS，实得 ${JSON.stringify(c.slice(0, 60))}），忽略并回退目录扫描`)
-      if (isValidExecuteRunId(c)) runId = c
-    }
-  } catch {}
+  // runId 解析（坑 worktree-cleanup-marker-chain 根治）：归属化解析 resolveExecuteRunForChange——
+  // marker 优先但校验覆盖度；marker 断裂（worktree cleanup / 归档清理 / 并行误删）时按 change 戳
+  // 精确归属，旧 run 退覆盖度启发。不再盲目 mtime 最新（曾把其他变更的 run 错配给本变更 →
+  // 全部 task 误报「review.json 缺失」→ 手工回填 7 份实际存在于正确 run 里的 review）。
+  const resolved = resolveExecuteRunForChange({ runtimeRoot, changeName, taskIds })
+  const runId = resolved ? resolved.runId : null
+  if (resolved && resolved.relocated) {
+    console.warn(`[sillyspec] execute run 归属修正：marker 指向的 run 对变更 ${changeName} 零覆盖，改用 ${resolved.origin === 'stamp' ? 'change 戳' : '覆盖度'}命中的 run ${runId}（真实 review 所在）`)
+  }
+
+  // 无归属 run → 降级 plan.md checkbox 统计；报告区分「无法归属」与「没跑过 execute」，
+  // 避免把定位失败误导成「review 全缺、需手工回填」
   if (!runId) {
+    const { total, checked } = countPlanCheckboxes(planContent)
+    let runsNote = '无 execute-runs 目录（本变更未跑过 execute？）'
     try {
       const runsDir = join(runtimeRoot, 'execute-runs')
       if (existsSync(runsDir)) {
-        const entries = readdirSync(runsDir)
-          .map(e => ({ e, p: join(runsDir, e) }))
-          .filter(x => { try { return statSync(x.p).isDirectory() } catch { return false } })
-          .map(x => ({ e: x.e, mtime: statSync(x.p).mtimeMs }))
-          .sort((a, b) => b.mtime - a.mtime)
-        if (entries.length > 0) runId = entries[0].e
+        const n = readdirSync(runsDir).filter(e => { try { return statSync(join(runsDir, e)).isDirectory() } catch { return false } }).length
+        if (n > 0) runsNote = `execute-runs/ 有 ${n} 个 run 但无一能归属到本变更（无 change 戳且零覆盖——marker 链断裂且 review 可能从未生成）`
       }
     } catch {}
-  }
-
-  // 无 runId → 降级 plan.md checkbox 统计
-  if (!runId) {
-    const { total, checked } = countPlanCheckboxes(planContent)
     return {
       source: 'plan-checkbox-fallback', total, completed: checked,
       pending: taskIds.slice(0, Math.max(0, total - checked)).map(id => ({ id, reason: 'checkbox 未勾（降级口径）' })),
       report:
-        '⚠️ 客观源不可用（无 execute runId marker，review.json 无法定位）→ 降级用 plan.md checkbox。\n' +
+        '⚠️ 客观源不可用（execute run 无法归属到本变更：' + runsNote + '）→ 降级用 plan.md checkbox。\n' +
         `- 总任务：${total}\n- plan.md 已勾选：${checked}\n` +
         '⚠️ checkbox 可能因 autoCheckPlanFromReviews 回填断裂而失真，务必交叉核对 .runtime/execute-runs/*/tasks/task-NN/review.json 的 verdict 再下结论。'
     }
   }
 
-  // 有 runId → 读 review.json verdict
+  // 有 runId → 读 review.json verdict；cannot_verify 草稿单列（不是真正复核，归档前应可见）
   const completed = []
   const pending = []
+  let cannotVerifyCount = 0
   for (const id of taskIds) {
     const reviewPath = join(runtimeRoot, 'execute-runs', runId, 'tasks', id, 'review.json')
     const r = readReview(reviewPath)
     if (r.ok && r.review && r.review.specVerdict !== 'fail' && r.review.qualityVerdict !== 'fail') {
       completed.push(id)
+      if (r.review.specVerdict === 'cannot_verify' || r.review.qualityVerdict === 'cannot_verify') cannotVerifyCount++
     } else if (r.ok && r.review) {
       pending.push({ id, reason: `verdict 未通过（spec=${r.review.specVerdict}, quality=${r.review.qualityVerdict}）` })
     } else {
@@ -173,12 +172,17 @@ export function summarizeTaskCompletion({ changeDir, runtimeRoot, changeName })
   const pendingLines = pending.length > 0
     ? pending.map(p => `  - ${p.id}: ${p.reason}`).join('\n')
     : '  （无）'
+  const draftLines = cannotVerifyCount > 0
+    ? `- cannot_verify 草稿（未真正复核）: ${cannotVerifyCount}\n` +
+      '  ⚠️ 这些 task 的 review 是 cannot_verify（含自动草稿兜底）而非 pass——归档前应确认 verify 阶段已兑现其 requiredEvidence，否则派独立子代理对照 task brief + git diff 补真实复核，勿静默放行\n'
+    : ''
   return {
-    source: 'review.json', total: taskIds.length, completed: completed.length, pending,
+    source: 'review.json', total: taskIds.length, completed: completed.length, pending, cannotVerify: cannotVerifyCount, runId,
     report:
-      `客观任务完成度（真相源 = review.json verdict，runId=${runId}）:\n` +
+      `客观任务完成度（真相源 = review.json verdict，runId=${runId}${resolved.origin !== 'marker' ? `，归属=${resolved.origin}` : ''}）:\n` +
       `- 总任务：${taskIds.length}\n` +
       `- 已通过（spec + quality verdict 均非 fail）：${completed.length}\n` +
+      draftLines +
       `- 未通过 / 缺失：${pending.length}\n` +
       `- 未完成列表:\n${pendingLines}\n` +
       '注：以 review.json verdict 为准；plan.md checkbox 仅作显示态（回填断裂时会与客观 verdict 不一致，以下方客观点为准）。'
@@ -387,6 +391,9 @@ export function validateTaskReviews(opts) {
   const errors = []
   const warnings = []
   const requiredEvidence = []
+  // PERF-01：整个循环共享一份 git 结果缓存（同 gitDir 的探测/status、同 (base,head) 的
+  // diff 在多 task 间高度重复；N task 从 5N 个 git 子进程降到 ~2+去重后数量）
+  const evidenceCache = {}
 
   for (const taskId of taskIds) {
     const reviewDir = join(runtimeRoot, 'execute-runs', executeRunId, 'tasks', taskId)
@@ -447,7 +454,7 @@ export function validateTaskReviews(opts) {
       }
     }
     if (reviewGitDir) {
-      const evidence = verifyReviewGitEvidence(review, reviewGitDir)
+      const evidence = verifyReviewGitEvidence(review, reviewGitDir, evidenceCache)
       for (const w of evidence.warnings) warnings.push(`${taskId}: ${w}`)
       if (!evidence.ok) {
         for (const err of evidence.errors) errors.push(`${taskId}: ${err}`)
@@ -516,13 +523,10 @@ export function validateTaskReviews(opts) {
 
 // ── Git 真实性交叉校验 ──
 
+// QUAL-01 收口：原为本地 execFileSync('git')（无 safe.directory、与 git-helper 口径分裂），
+// 现走统一入口；抛错/trim 语义不变，timeout 15000 保留（rev-parse/diff 大仓余量）
 function runGit(gitDir, args) {
-  return execFileSync('git', args, {
-    cwd: gitDir,
-    encoding: 'utf8',
-    timeout: 15000,
-    stdio: ['ignore', 'pipe', 'pipe'],
-  }).trim()
+  return git(gitDir, args, { timeout: 15000 })
 }
 
 // porcelain 状态行 → 变更文件路径（对齐 shared.js:343 parsePorcelainPath：`XY path`、引号包裹、
@@ -552,31 +556,57 @@ function parsePorcelainFiles(statusOut) {
  * git 环境不可用（非 git 仓库 / git 缺失）时返回 unavailable，由调用方降级为
  * warning——不因环境问题误杀，但记录在输出中。
  *
+/**
  * @param {object} review - 已通过 schema 校验的 review 对象
  * @param {string} gitDir - 执行 git 命令的目录（worktree 优先，回退主仓库）
+ * @param {object} [cache] - 进程内单次校验批的共享缓存（体检 PERF-01：N task × 5 个 git
+ *   子进程去重——gitDir 探测与 status --porcelain 结果按 gitDir 恒同，commit 校验按
+ *   (gitDir,hash)、diff 按 (gitDir,base,head) 在多 task 间高度重复。validateTaskReviews
+ *   整个循环传同一份；不传则退化为逐次执行（单测/独立调用零回归）。缓存生命周期 =
+ *   一次校验批：working-tree status 是快照语义，跨批复用会读到陈旧状态。
  * @returns {{ ok: boolean, emptyDiff: boolean, errors: string[], warnings: string[], unavailable: boolean }}
  */
-export function verifyReviewGitEvidence(review, gitDir) {
+export function verifyReviewGitEvidence(review, gitDir, cache = null) {
   const errors = []
   const warnings = []
-
-  // git 环境探测：失败即 unavailable，交由调用方降级
-  try {
-    runGit(gitDir, ['rev-parse', '--git-dir'])
-  } catch (e) {
+  const c = cache || (cache = {})
+  c.gitOk = c.gitOk || new Map()
+  c.verified = c.verified || new Set()
+  c.diffs = c.diffs || new Map()
+  c.wtStatus = c.wtStatus || new Map()
+
+  // git 环境探测：失败即 unavailable，交由调用方降级（同 gitDir 结果恒同，批内缓存）
+  if (!c.gitOk.has(gitDir)) {
+    try {
+      runGit(gitDir, ['rev-parse', '--git-dir'])
+      c.gitOk.set(gitDir, true)
+    } catch (e) {
+      c.gitOk.set(gitDir, false)
+      return {
+        ok: true,
+        emptyDiff: false,
+        errors: [],
+        warnings: [`git 环境不可用（${gitDir}），跳过 review 真实性交叉校验: ${e.message?.split('\n')[0] || e.message}`],
+        unavailable: true,
+      }
+    }
+  } else if (c.gitOk.get(gitDir) === false) {
     return {
       ok: true,
       emptyDiff: false,
       errors: [],
-      warnings: [`git 环境不可用（${gitDir}），跳过 review 真实性交叉校验: ${e.message?.split('\n')[0] || e.message}`],
+      warnings: [`git 环境不可用（${gitDir}），跳过 review 真实性交叉校验（批内缓存判定）`],
       unavailable: true,
     }
   }
 
   for (const field of ['base', 'head']) {
     const hash = review[field]
+    const vkey = `${gitDir}\u0000${hash}`
+    if (c.verified.has(vkey)) continue
     try {
       runGit(gitDir, ['rev-parse', '--verify', '--quiet', `${hash}^{commit}`])
+      c.verified.add(vkey)
     } catch {
       errors.push(`${field} "${hash}" 不是仓库中的真实 commit — review.json 疑似伪造`)
     }
@@ -586,21 +616,32 @@ export function verifyReviewGitEvidence(review, gitDir) {
   }
 
   let diffFiles = []
-  try {
-    const out = runGit(gitDir, ['diff', '--name-only', `${review.base}..${review.head}`])
-    diffFiles = out ? out.split('\n').filter(Boolean) : []
-  } catch (e) {
-    warnings.push(`git diff ${review.base}..${review.head} 执行失败，跳过 diff 校验: ${e.message?.split('\n')[0] || e.message}`)
-    return { ok: true, emptyDiff: false, errors, warnings, unavailable: false }
+  const dkey = `${gitDir}\u0000${review.base}\u0000${review.head}`
+  if (c.diffs.has(dkey)) {
+    diffFiles = c.diffs.get(dkey)
+  } else {
+    try {
+      const out = runGit(gitDir, ['diff', '--name-only', `${review.base}..${review.head}`])
+      diffFiles = out ? out.split('\n').filter(Boolean) : []
+      c.diffs.set(dkey, diffFiles)
+    } catch (e) {
+      warnings.push(`git diff ${review.base}..${review.head} 执行失败，跳过 diff 校验: ${e.message?.split('\n')[0] || e.message}`)
+      return { ok: true, emptyDiff: false, errors, warnings, unavailable: false }
+    }
   }
 
   // 并入 working-tree 未提交改动（execute 复盘 a）：子代理默认不 commit，base..head 无 commit diff 时
   // diffFiles 留空 → 下方交叉比对拿空集对非空 changedFiles 必判「完全不相交」伪造，逼 agent 强制 commit
   // + 改 7 个 review head。对齐 checkExecuteCodeEvidence（stage-contract.js 同时查 working-tree）语义，
   // 未提交改动也算有效对账源。working-tree 有改动时无条件并入（覆盖「部分 commit + 未提交」）。
+  // PERF-01：同 gitDir 的 status 快照按批缓存（单次校验批内恒同，跨批复用会读到陈旧状态）
   const commitDiffFiles = diffFiles.slice()
   try {
-    const wtStatus = runGit(gitDir, ['status', '--porcelain'])
+    let wtStatus = c.wtStatus.get(gitDir)
+    if (wtStatus === undefined) {
+      wtStatus = runGit(gitDir, ['status', '--porcelain'])
+      c.wtStatus.set(gitDir, wtStatus)
+    }
     if (wtStatus && wtStatus.trim().length > 0) {
       const wtFiles = parsePorcelainFiles(wtStatus)
       if (wtFiles.length > 0) diffFiles = diffFiles.concat(wtFiles)
@@ -700,7 +741,7 @@ export function isValidExecuteRunId(runId) {
  * @param {{ runtimeRoot: string }} opts
  * @returns {string|null} 含 tasks/ 的最新 runId，无则 null
  */
-export function resolveLatestExecuteRunIdWithTasks({ runtimeRoot }) {
+export function resolveLatestExecuteRunIdWithTasks({ runtimeRoot, changeName = null }) {
   try {
     const runsDir = join(runtimeRoot, 'execute-runs')
     if (!existsSync(runsDir)) return null
@@ -710,7 +751,19 @@ export function resolveLatestExecuteRunIdWithTasks({ runtimeRoot }) {
       .filter(x => { try { return statSync(join(x.p, 'tasks')).isDirectory() } catch { return false } })
       .map(x => ({ e: x.e, mtime: statSync(x.p).mtimeMs }))
       .sort((a, b) => b.mtime - a.mtime)
-    return entries.length > 0 ? entries[0].e : null
+    if (entries.length === 0) return null
+    // changeName 给定时优先 change 戳等值的 run（坑 worktree-cleanup-marker-chain：mtime 最新
+    // 会错拿其他变更的 run）；无戳命中退回 mtime 最新（向后兼容，调用方多为 marker 漂移兜底，
+    // 宁可拿最新 run 也不空手而归——覆盖度由调用方 validateTaskReviews 复校验）
+    if (changeName) {
+      for (const x of entries) {
+        try {
+          const c = readFileSync(join(runsDir, x.e, 'change'), 'utf8').trim()
+          if (c === changeName) return x.e
+        } catch {}
+      }
+    }
+    return entries[0].e
   } catch {
     return null
   }
@@ -725,20 +778,145 @@ export function resolveLatestExecuteRunId({ runtimeRoot, changeName }) {
       if (isValidExecuteRunId(c)) return c
     }
   } catch {}
+  // marker 缺失（worktree cleanup / 归档清理 / 并行会话误删——坑 worktree-cleanup-marker-chain）
+  // 时不再盲目取 mtime 最新（会拿到其他变更的 run）：先按 change 归属戳过滤，命中才返回；
+  // 无戳（旧 run）退回 mtime 最新保持向后兼容。
   try {
-    const runsDir = join(runtimeRoot, 'execute-runs')
-    if (existsSync(runsDir)) {
-      const entries = readdirSync(runsDir)
-        .map(e => ({ e, p: join(runsDir, e) }))
-        .filter(x => { try { return statSync(x.p).isDirectory() } catch { return false } })
-        .map(x => ({ e: x.e, mtime: statSync(x.p).mtimeMs }))
-        .sort((a, b) => b.mtime - a.mtime)
-      if (entries.length > 0) return entries[0].e
-    }
+    const candidates = listExecuteRunCandidates(runtimeRoot, changeName)
+    if (candidates.stamped.length > 0) return candidates.stamped[0]
+    if (candidates.all.length > 0) return candidates.all[0]
   } catch {}
   return null
 }
 
+// ── execute run 的 change 归属戳（坑 worktree-cleanup-marker-chain 根治）──
+//
+// 背景：run 目录 execute-runs/<runId>/ 本身不带变更身份，change→run 的唯一链接是
+// current-execute-run-id-<change> marker；worktree cleanup / 归档 marker 清理 / 并行会话
+// 误删后链即断，各 fallback（mtime 最新）会错拿其他变更的 run → archive 完成度报告把
+// 已实现 task 全报「review.json 缺失」，只能手工回填。
+// 修法：marker 写入点同步在 run 目录落 `change` 戳；marker 断裂后按戳精确归属，
+// 旧 run（无戳）退回覆盖度启发式（run 的 tasks/ 含本变更 task-NN review 才算命中）。
+
+/**
+ * 在 run 目录写入 change 归属戳（execute-runs/<runId>/change，内容为 changeName）。
+ * 与 marker 写入点同步调用（stage.js 主点 + gates.js/task-review.js 补写点）。
+ * best-effort：失败仅 warn 不抛（戳是归属优化的载体，缺了退回覆盖度启发式，不阻断主流程）。
+ * @param {string} runtimeRoot
+ * @param {string} runId
+ * @param {string} changeName
+ */
+export function stampExecuteRunChange(runtimeRoot, runId, changeName) {
+  if (!runtimeRoot || !runId || !changeName) return
+  try {
+    // run 目录可能尚未创建（本 helper 先于 review 落盘调用的路径）——mkdir 保证自洽
+    mkdirSync(join(runtimeRoot, 'execute-runs', runId), { recursive: true })
+    writeFileSync(join(runtimeRoot, 'execute-runs', runId, 'change'), changeName + '\n')
+  } catch (e) {
+    console.warn(`[sillyspec] execute run change 戳写入失败（归属 fallback 退回覆盖度启发式，不阻断）: ${e.message}`)
+  }
+}
+
+/**
+ * 读 run 目录的 change 归属戳。
+ * @returns {string|null} 戳内容（trim 后非空），无戳/读失败返回 null
+ */
+function readExecuteRunChangeStamp(runtimeRoot, runId) {
+  try {
+    const c = readFileSync(join(runtimeRoot, 'execute-runs', runId, 'change'), 'utf8').trim()
+    return c || null
+  } catch { return null }
+}
+
+/**
+ * 扫描 execute-runs/ 候选 run（mtime 最新优先），按 change 归属戳分组。
+ * @returns {{ stamped: string[], all: string[] }} stamped=戳等 changeName 的 runId（新→旧）；
+ *   all=全部 runId（新→旧，含无戳旧 run，供覆盖度启发式与向后兼容 fallback）
+ */
+function listExecuteRunCandidates(runtimeRoot, changeName) {
+  const runsDir = join(runtimeRoot, 'execute-runs')
+  const out = { stamped: [], all: [] }
+  if (!existsSync(runsDir)) return out
+  const entries = readdirSync(runsDir)
+    .map(e => ({ e, p: join(runsDir, e) }))
+    .filter(x => { try { return statSync(x.p).isDirectory() } catch { return false } })
+    .map(x => ({ e: x.e, mtime: statSync(x.p).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime)
+  for (const x of entries) {
+    out.all.push(x.e)
+    if (changeName && readExecuteRunChangeStamp(runtimeRoot, x.e) === changeName) out.stamped.push(x.e)
+  }
+  return out
+}
+
+/**
+ * 判定 run 对本变更 taskIds 的覆盖度：tasks/ 下存在多少个 task-NN/review.json ∈ taskIds。
+ * taskIds 为空时退化为「tasks/ 下存在任意 task-NN/review.json」（保守启发）。
+ * @returns {number} 命中的 review 数
+ */
+function executeRunCoverage(runtimeRoot, runId, taskIds) {
+  try {
+    const tasksDir = join(runtimeRoot, 'execute-runs', runId, 'tasks')
+    if (!existsSync(tasksDir)) return 0
+    const entries = readdirSync(tasksDir).filter(e => /^task-\d+$/.test(e))
+    if (taskIds.length > 0) return entries.filter(e => taskIds.includes(e) && existsSync(join(tasksDir, e, 'review.json'))).length
+    return entries.filter(e => existsSync(join(tasksDir, e, 'review.json'))).length
+  } catch { return 0 }
+}
+
+/**
+ * 归属化解析本变更的 execute run（marker 链断裂的根治入口）。
+ *
+ * 解析顺序：
+ *   1. marker（格式校验）指向的 run，若其对本变更有覆盖（tasks/ 有本变更 review）或戳匹配 → 用它；
+ *   2. marker 缺失/非法/零覆盖（坑10 型漂移：marker 指向空 run）→ 扫描候选：
+ *      a. change 戳等值的最新的 run；
+ *      b.（旧 run 无戳）覆盖度 ≥1 的最新 run；
+ *   3. 都不命中 → null（调用方降级，报告明确「run 无法归属」而非「review 全缺」）。
+ *
+ * fail-safe：任何异常 → null，绝不抛。
+ * @param {{ runtimeRoot: string, changeName: string, taskIds?: string[] }} opts
+ * @returns {{ runId: string, origin: 'marker'|'stamp'|'coverage', relocated?: boolean }|null}
+ */
+export function resolveExecuteRunForChange({ runtimeRoot, changeName, taskIds = [] }) {
+  try {
+    // 1. marker
+    let markerRunId = null
+    try {
+      const marker = join(runtimeRoot, `current-execute-run-id-${changeName}`)
+      if (existsSync(marker)) {
+        const c = readFileSync(marker, 'utf8').trim()
+        if (c && !isValidExecuteRunId(c)) console.warn(`[sillyspec] execute run marker 内容非法（期望 exec-YYYY-MM-DD-HHMMSS，实得 ${JSON.stringify(c.slice(0, 60))}），忽略并回退归属扫描`)
+        if (isValidExecuteRunId(c)) markerRunId = c
+      }
+    } catch {}
+    if (markerRunId) {
+      const stamped = readExecuteRunChangeStamp(runtimeRoot, markerRunId) === changeName
+      const covered = executeRunCoverage(runtimeRoot, markerRunId, taskIds)
+      if (stamped || covered > 0) return { runId: markerRunId, origin: 'marker' }
+      // marker 零覆盖且无戳：疑似漂移（坑10：marker 在、真实 review 在别的 run），下探扫描
+    }
+
+    // 2. 扫描：戳优先 → 覆盖度启发（旧 run）。
+    // 覆盖度启发跳过「戳属他变更」的 run：task-NN 命名跨变更同构（都从 task-01 起），只看覆盖度
+    // 会把他变更 run 的 task-01 review 误配给本变更；戳存在且不等值 = 该 run 有明确主人，排除。
+    const candidates = listExecuteRunCandidates(runtimeRoot, changeName)
+    if (candidates.stamped.length > 0) {
+      return { runId: candidates.stamped[0], origin: 'stamp', relocated: markerRunId ? markerRunId !== candidates.stamped[0] : true }
+    }
+    for (const runId of candidates.all) {
+      const stamp = readExecuteRunChangeStamp(runtimeRoot, runId)
+      if (stamp && stamp !== changeName) continue
+      if (executeRunCoverage(runtimeRoot, runId, taskIds) > 0) {
+        return { runId, origin: 'coverage', relocated: markerRunId ? markerRunId !== runId : true }
+      }
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
 /**
  * worktree execute「主 agent 直接实现」模式收尾兜底：per-task review.json 缺失时，
  * 据 git diff base..head 按 task allowed_paths 归属，自动落盘 cannot_verify 草稿。
@@ -798,6 +976,7 @@ export async function generateTaskReviewDrafts({ changeName, cwd, platformOpts =
     try {
       mkdirSync(join(runtimeRoot, 'execute-runs', executeRunId, 'tasks'), { recursive: true })
       writeFileSync(runIdFile, executeRunId + '\n')
+      stampExecuteRunChange(runtimeRoot, executeRunId, changeName)
     } catch (e) {
       console.error(`[sillyspec] execute run marker/目录写入失败（降级继续，草稿落盘仍尝试）: ${e.message}`)
     }
@@ -907,6 +1086,12 @@ export async function generateTaskReviewDrafts({ changeName, cwd, platformOpts =
       skipped++
       continue
     }
+    // 主仓 task 缺 base/head（meta 缺失 / HEAD 解析失败，见上方 :968-981 注释承诺的"后续跳过"）：
+    // 跳过留给 agent 手补。此前 null.slice(0,8) 直接 TypeError 崩掉整个草稿生成（体检 BUG-06）
+    if (!crossEntry && (!taskBase || !taskHead)) {
+      skipped++
+      continue
+    }
     // unattributed 只统计主仓 diff（跨仓 diff 路径相对跨仓仓根，与主仓 unattributed 语义无关）
     if (!crossEntry) {
       taskChangedFiles.forEach(f => attributed.add(f))

package/src/taskcard.js

@@ -0,0 +1,178 @@
+/**
+ * sillyspec taskcard — 生成 Windows 安全的 TaskCard 骨架
+ *
+ * 背景：plan postcheck 任务卡被拒的根因集中在「LLM 子代理手写 frontmatter 不可靠」——
+ * CRLF 行尾、漏闭合 ---、缺 constraints 等硬校验字段（校验侧已对 CRLF 容错，但闭合/字段
+ * 缺失仍拦）。本命令从源头消灭这类格式错误：骨架由 CLI 用 writeFileSync 直写（字符串
+ * 只含 \n，天然 LF），frontmatter 闭合与硬校验 9 字段由代码保证，子代理只需 Edit 填充
+ * 占位符，不再手写整卡。
+ *
+ * 任务编号/标题从 plan.md checkbox 行自动带出（与 plan.js parseTaskNames 同源，
+ * 保编号不跳号、名称与 plan.md 一致）。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { git } from './git-helper.js'
+import { assertSafeChangeName, resolveSpecDir } from './run/shared.js'
+import { parseTaskNames } from './stages/plan.js'
+
+/**
+ * 任务号归一：接受 task-01 / task-1 / 01 / 1，统一为 task-NN（两位补零，与任务卡文件名一致）。
+ * @param {string} raw
+ * @returns {string} 形如 task-01
+ */
+export function normalizeTaskId(raw) {
+  const s = String(raw || '').trim()
+  const m = s.match(/^(?:task-)?(\d+)$/i)
+  if (!m) {
+    throw new Error(`任务号格式非法: "${s}"（应为 task-NN 或 NN，可逗号分隔多个）`)
+  }
+  return `task-${String(m[1]).padStart(2, '0')}`
+}
+
+/**
+ * YAML 标量安全序列化（坑 taskcard-title-backtick-yaml，2026-08-20 实证）：plan checkbox 行名
+ * 是自由文本，带反引号（如 "`-p` 参数支持"）时裸插值进 frontmatter——`` ` `` 与 @ 是 YAML 保留
+ * 指示符，js-yaml 直接抛错，契约字段（allowed_paths/constraints 等）随整个 frontmatter 静默丢失，
+ * 靠 plan postcheck 才兜住。统一单引号包裹 + 内部 ' 双写（YAML 标准转义），无边界字符要判。
+ * @param {string} v
+ * @returns {string}
+ */
+function yamlScalar(v) {
+  const s = String(v ?? '')
+  return `'${s.replace(/'/g, "''")}'`
+}
+
+/**
+ * 生成 TaskCard 骨架字符串（纯函数）。
+ *
+ * 硬校验 9 字段（plan-postcheck feasibility）+ 规范字段全部就位，占位符由子代理 Edit 填充；
+ * 可选字段（provides/expects_from/related_tests）默认不生成——缩小 YAML 出错面，何时加的
+ * 判据写在文件尾注释（规则详情见 templates/prompts/taskcard-rules.md）。
+ * 字符串只含 \n：writeFileSync 直写不经任何行尾转换，Windows 下天然 LF 安全。
+ * title/title_zh/author 经 yamlScalar 转义（自由文本防 YAML 指示符炸解析）。
+ *
+ * @param {{ taskId: string, title: string, titleZh: string, author: string, now: string }} p
+ * @returns {string}
+ */
+export function buildTaskcardSkeleton({ taskId, title, titleZh, author, now }) {
+  return `---
+id: ${taskId}
+title: ${yamlScalar(title)}
+title_zh: ${yamlScalar(titleZh)}
+author: ${yamlScalar(author)}
+created_at: ${now}
+priority: P0
+depends_on: []
+blocks: []
+requirement_ids: [FR-XX]
+decision_ids: [D-XXX@vN]
+allowed_paths:
+  - src/example/file.ts
+goal: >
+  一句话说明这个 task 要做什么、为什么。
+implementation:
+  - 具体步骤 1
+  - 具体步骤 2
+acceptance:
+  - 可验证的验收条件 1
+  - 可验证的验收条件 2
+verify:
+  - cd frontend && pnpm exec tsc --noEmit
+constraints:
+  - 边界约束 1（如：不加测试）
+  - 边界约束 2（如：不修改传入参数）
+---
+
+<!-- 骨架由 sillyspec taskcard 生成（LF 行尾 + frontmatter 已闭合 + 硬校验 9 字段齐全）。
+     用 Edit tool 填充上方占位符（allowed_paths/goal/implementation/acceptance/verify/constraints 等），
+     勿用 Write 整文件重写——会引入 CRLF 行尾/漏闭合 ---/漏字段回归。
+     可选字段按需插进上方 frontmatter（规则见 taskcard-rules）：
+     provides:      仅当本 task 给其他 task 提供接口/DTO/响应时填
+     expects_from:  仅当本 task 消费其他 task 的契约时填
+     related_tests: 仅当本 task 改动导致既有测试断言失效时填（测试路径须同时进 allowed_paths） -->
+`
+}
+
+/**
+ * taskcard 命令主逻辑：定位变更目录 → 解析任务清单（--task 显式列表 / 'all' 从 plan.md 取）→
+ * 逐个写骨架。
+ *
+ * @param {string} changeName 变更名（.sillyspec/changes/ 下目录名）
+ * @param {{ cwd: string, specDir?: string|null, taskIds: string[]|'all', title?: string|null,
+ *           titleZh?: string|null, force?: boolean }} opts
+ *   taskIds：normalizeTaskId 归一后的数组；或字面 'all' 表示从 plan.md 取全部 checkbox 任务
+ * @returns {{ created: string[], skipped: string[], tasksDir: string }}
+ */
+export function cmdTaskcard(changeName, opts = {}) {
+  const { cwd, specDir = null, taskIds, title = null, titleZh = null, force = false } = opts
+  assertSafeChangeName(changeName, '变更名')
+
+  const changeDir = join(resolveSpecDir(cwd, { specDir }), 'changes', changeName)
+  if (!existsSync(changeDir)) {
+    throw new Error(`变更目录不存在: ${changeDir}（先完成 plan 前置步骤，或检查 --change 名）`)
+  }
+
+  // 任务注册表 tasks.md（2026-08-20-task-truth-unify 唯一真相；CRLF 归一后解析，
+  // --all 时强依赖）。tasks.md 缺失回退 plan.md（旧归档变更兼容读侧）
+  let planTasks = []
+  const tasksMdPath = join(changeDir, 'tasks.md')
+  const planPath = join(changeDir, 'plan.md')
+  const registryPath = existsSync(tasksMdPath) ? tasksMdPath : planPath
+  if (existsSync(registryPath)) {
+    const registryContent = readFileSync(registryPath, 'utf8').replace(/\r\n/g, '\n')
+    planTasks = parseTaskNames(registryContent)
+  }
+
+  let ids
+  if (taskIds === 'all') {
+    if (planTasks.length === 0) {
+      throw new Error(
+        `--all 需要 tasks.md 中存在 checkbox 任务行（格式 "- [ ] task-XX: 任务名"）` +
+        (existsSync(registryPath) ? '，当前任务清单未解析到任何任务行' : '，且变更目录下未找到 tasks.md/plan.md')
+      )
+    }
+    ids = planTasks.map(t => `task-${t.num}`)
+  } else if (Array.isArray(taskIds) && taskIds.length > 0) {
+    ids = taskIds
+  } else {
+    throw new Error('缺少任务清单：需 --task task-01[,task-02...] 或 --all')
+  }
+
+  // 标题优先级：--title/--title-zh 参数 > plan.md checkbox 行名称 > 占位符。
+  // 参数仅单任务时可用（多任务各卡标题不同，统一参数必错）。
+  if ((title || titleZh) && ids.length > 1) {
+    throw new Error('--title/--title-zh 仅在 --task 指定单个任务时可用（多任务标题自动取自 plan.md checkbox 行）')
+  }
+
+  const author = (() => {
+    try {
+      // QUAL-01 收口：原 execSync 字符串拼接（经 shell，违反自家注入规约）→ git-helper 数组形式
+      return git(cwd, ['config', 'user.name']) || 'unknown'
+    } catch {
+      return 'unknown'
+    }
+  })()
+  const now = new Date().toISOString().slice(0, 19).replace('T', ' ')
+
+  const tasksDir = join(changeDir, 'tasks')
+  mkdirSync(tasksDir, { recursive: true })
+
+  const created = []
+  const skipped = []
+  for (const id of ids) {
+    const planMatch = planTasks.find(t => `task-${t.num}` === id)
+    const finalTitle = title || (planMatch ? planMatch.name : null) || `${id} fill-english-title`
+    const finalTitleZh = titleZh || (planMatch ? planMatch.name : null) || finalTitle
+    const filePath = join(tasksDir, `${id}.md`)
+    if (existsSync(filePath) && !force) {
+      skipped.push(filePath)
+      continue
+    }
+    writeFileSync(filePath, buildTaskcardSkeleton({
+      taskId: id, title: finalTitle, titleZh: finalTitleZh, author, now,
+    }), 'utf8')
+    created.push(filePath)
+  }
+  return { created, skipped, tasksDir }
+}