sillyspec 3.26.11 → 3.26.14

package/src/run/command.js

@@ -23,7 +23,7 @@ import { basename, join, resolve, dirname } from 'node:path'
 import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
 import { randomBytes, randomUUID } from 'node:crypto'
 import { writeAtomicSync } from '../fs-atomic.js'
-import { resolveSpecDir, countAncestorSpecDirs, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, writePlatformPointer, checkPlatformManaged, PLATFORM_MANAGED_FILENAME } from './shared.js'
+import { resolveSpecDir, countAncestorSpecDirs, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, warnApprovalUnknown, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, writePlatformPointer, checkPlatformManaged, PLATFORM_MANAGED_FILENAME } from './shared.js'
 import { resolveQuickLinkedChanges } from './quick-audit.js'
 import { outputStep } from './prompt.js'
 import { completeStep, skipStep, waitStep, continueStep } from './complete.js'
@@ -108,6 +108,11 @@ export async function ensureStageSteps(progress, stageName, cwd, specDir = null)
   // 检查步骤数量是否匹配（execute 动态步骤可能变化）
   if (progress.stages[stageName].steps.length !== steps.length) {
     const oldSteps = progress.stages[stageName].steps
+    // 漂移显式化（坑 execute-step-table-drift，2026-08-20 实证）：plan.md Wave 数在 execute
+    // 中途被改后 DB 步骤表与重算定义错位（17/12 交替），重播种本身按名保留完成态是对的，
+    // 但此前完全静默——agent 只见各处计数打架的报错，不知道发生了什么、该不该继续
+    console.warn(`⚠️ ${stageName} 步骤表与当前定义漂移（DB ${oldSteps.length} 步 → 定义 ${steps.length} 步，常见原因：execute 中途修改了 plan.md 的 Wave 结构）`)
+    console.warn(`   已按步骤名保留完成态重播种（新增步骤置 pending；Wave 重编号时同名步骤继承旧状态，勾选真相以 tasks.md/review.json 为准）`)
     progress.stages[stageName].steps = steps.map(s => {
       const old = oldSteps.find(step => step.name === s.name)
       if (old) return old  // 精确名命中 → 保留旧状态
@@ -195,10 +200,13 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // ── cwd 纠正：向上查找真实项目根 ──
   // 防止多 project 工作区中 cwd 停在子目录（如 backend/）时
   // 状态写入子目录下误建的 .sillyspec，导致状态分裂
-  if (!specDir && !existsSync(join(cwd, '.sillyspec-platform.json'))) {
-    // 平台模式（cwd 有 .sillyspec-platform.json 指针）不做 cwd 纠正：指针已明确 specDir，
-    // 向上找 .sillyspec 反而会撞到无关项目（如用户 home 的 .sillyspec），导致 --done 恢复
-    // 读写 ~/.sillyspec-platform.json 出错的 specRoot。
+  // HUB-12c：守卫须同时查平台接管声明——指针被 cleanup、声明还在、祖先有别的 .sillyspec
+  //（monorepo 嵌套）时，cwd 被上移后 checkPlatformManaged 在新 cwd 扑空 → 静默落本地库，
+  // 双入口 fail-closed 被绕过（状态分裂正是它要防的）
+  if (!specDir && !existsSync(join(cwd, '.sillyspec-platform.json')) && !checkPlatformManaged(cwd)) {
+    // 平台模式（cwd 有 .sillyspec-platform.json 指针或接管声明）不做 cwd 纠正：指针已明确
+    // specDir，向上找 .sillyspec 反而会撞到无关项目（如用户 home 的 .sillyspec），导致
+    // --done 恢复读写 ~/.sillyspec-platform.json 出错的 specRoot。
     const resolvedRoot = resolveSpecDir(cwd)
     if (resolvedRoot && resolvedRoot !== join(cwd, '.sillyspec')) {
       const realRoot = dirname(resolvedRoot)
@@ -360,8 +368,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // 纯只读比较：零会话/QUICKLOG 副作用，仅解析 --base/--full/--report 后转发 scan-diff 退出码。
   if (stageName === 'scan' && flags.includes('--diff')) {
     const { runScanDiff } = await import('../scan-diff.js')
-    const diffBaseIdx = flags.indexOf('--base')
-    const diffBase = diffBaseIdx >= 0 && flags[diffBaseIdx + 1] ? flags[diffBaseIdx + 1] : null
+    const diffBase = getFlagValue('--base')
     process.exitCode = runScanDiff({
       projectRoot: cwd,
       specBase,
@@ -410,26 +417,26 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   }
 
   // 解析 --output
+  // F4 守卫统一走 getFlagValue（坑 raw-flag-value-bypass）：裸 flags[idx+1] 会把漏值后紧跟的
+  // flag 名当值（--output --input x → output="--input"），--change --done 甚至会建出名为
+  // --done 的变更目录（assertSafeChangeName 的 [\w.-] 恰好放行）。getFlagValue 的 F4 注释
+  // 点名过本坑，此前只有 from-step 等少数 flag 用了它。
   let outputText = null
-  const outputIdx = flags.indexOf('--output')
-  if (outputIdx !== -1 && flags[outputIdx + 1]) {
-    outputText = flags[outputIdx + 1]
-  }
+  const outputValue = getFlagValue('--output')
+  if (outputValue !== null) outputText = outputValue
 
   // 解析 --input
   let inputText = null
-  const inputIdx = flags.indexOf('--input')
-  if (inputIdx !== -1 && flags[inputIdx + 1]) {
-    inputText = flags[inputIdx + 1]
-  }
+  const inputValue = getFlagValue('--input')
+  if (inputValue !== null) inputText = inputValue
 
   // 解析 --linked-changes <a,b|none>（quick 专用：显式声明关联变更，CI/脚本友好）
   // 与 --change 解耦：--linked-changes 语义清晰（关联变更），不与「指定变更名」混淆。
   // null = 未指定（走持久化/交互/兼容回退）；[] = 显式 none（不关联）；[...] = 显式列表
   let explicitLinked = null
-  const linkedIdx = flags.indexOf('--linked-changes')
-  if (linkedIdx !== -1 && flags[linkedIdx + 1]) {
-    const v = flags[linkedIdx + 1].trim()
+  const linkedValue = getFlagValue('--linked-changes')
+  if (linkedValue !== null) {
+    const v = linkedValue.trim()
     explicitLinked = v.toLowerCase() === 'none' ? [] : v.split(',').map(s => s.trim()).filter(Boolean)
   }
 
@@ -437,9 +444,9 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // 历史写法，语义与「指定变更名」冲突，新用法建议改用 --linked-changes）
   let changeName = null
   let linkedChanges = []
-  const changeIdx = flags.indexOf('--change')
-  if (changeIdx !== -1 && flags[changeIdx + 1]) {
-    changeName = flags[changeIdx + 1]
+  const changeValue = getFlagValue('--change')
+  if (changeValue !== null) {
+    changeName = changeValue
     if (stageName === 'quick') {
       linkedChanges = changeName.split(',').map(s => s.trim()).filter(Boolean)
       changeName = null
@@ -481,7 +488,9 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     // 1373-1376 已把 quick 的 --change 值清进 linkedChanges、changeName 置 null。
     // 此处回看 --change 原始值：若恰好是单个 quick-<8hex> → 识别为本会话 sessionId（精确恢复），
     // 并撤销把它当 linkedChanges 的误判。多值或不匹配 → 维持 linkedChanges 语义（旧兼容）。
-    const rawChange = changeIdx !== -1 && flags[changeIdx + 1] ? flags[changeIdx + 1].trim() : null
+    // F4 守卫同款（changeIdx 变量已随裸读清理移除，此处改 getFlagValue 复读原始值）
+    const rawChangeValue = getFlagValue('--change')
+    const rawChange = rawChangeValue !== null ? rawChangeValue.trim() : null
     const rawIsSingleSid = rawChange && rawChange.indexOf(',') === -1 && QUICK_SID_RE.test(rawChange)
     if (rawIsSingleSid) {
       // --done --change quick-<uuid8>：精确恢复（撤销 1373-1376 把它误当 linkedChanges）
@@ -541,18 +550,18 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     process.exit(2) // 用法错 → exit 2
   }
   let quickFiles = []
-  const filesIdx = flags.indexOf('--files')
-  if (filesIdx !== -1 && flags[filesIdx + 1]) {
-    quickFiles = flags[filesIdx + 1].split(',').map(f => f.trim()).filter(Boolean)
+  const filesValue = getFlagValue('--files')
+  if (filesValue !== null) {
+    quickFiles = filesValue.split(',').map(f => f.trim()).filter(Boolean)
   }
 
   // 解析 --file-notes "path::括注 || path::括注"（quick 专用：QUICKLOG「文件：」行落盘多行括注）。
   // 旁路注入 quicklog.js（per-process setter），不经 complete 收尾路径透传（避碰多 agent 并发改的收尾热点）。
   // completeQuicklogEntry 读后即清；不传 → '' → 回填审计到的实际文件单行（向后兼容）。
   let quickFileNotes = ''
-  const fileNotesIdx = flags.indexOf('--file-notes')
-  if (fileNotesIdx !== -1 && flags[fileNotesIdx + 1]) {
-    quickFileNotes = flags[fileNotesIdx + 1]
+  const fileNotesValue = getFlagValue('--file-notes')
+  if (fileNotesValue !== null) {
+    quickFileNotes = fileNotesValue
   }
   setQuickFileNotes(quickFileNotes)
 
@@ -763,16 +772,20 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       let autoName = changeName || resolveChangeNameAuto(cwd, specRoot) || 'default'
       // archive 特例：归档后变更从活跃列表排除（listChanges WHERE status='active'），
       // 不带 --change 回退 default 会读错变更。无活跃变更时取最新归档变更，读其现有 progress。
+      // 归档目录名 = 原变更名恒等迁移（archiveDestDirName 不改名），直接原名对读——此前按
+      // 「日期前缀过滤 + 剥日期」找，剥出的短名与 DB 行名（含日期）恒不符 → pm.read 返回
+      // null → initChange 凭空建幻影变更再跑 archive（坑 archive-fallback-phantom-change）。
       if (stageName === 'archive' && autoName === 'default') {
         try {
           const archiveDir = join(specBase, 'changes', 'archive')
           if (existsSync(archiveDir)) {
-            const latest = readdirSync(archiveDir)
-              .filter(d => /^\d{4}-\d{2}-\d{2}-.+/.test(d))
+            const latest = readdirSync(archiveDir, { withFileTypes: true })
+              .filter(d => d.isDirectory())
+              .map(d => d.name)
               .sort()
               .pop()
             if (latest) {
-              autoName = latest.replace(/^\d{4}-\d{2}-\d{2}-/, '')
+              autoName = latest
               progress = pm.read(cwd, autoName)
             }
           }
@@ -879,12 +892,20 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     // stale/revising 阶段可能 steps 为空，或者 execute 阶段的 steps 需要从最新 plan.md 刷新
     const stageDataPre = progress.stages[stageName]
     const needsInit = !stageDataPre || !stageDataPre.steps || stageDataPre.steps.length === 0
-    // execute 阶段在 reopen 时需要从最新 plan.md 重新解析 steps（plan 可能已变更）
+    // execute 阶段在 reopen 时需要从最新 plan.md 重新解析 steps（plan 可能已变更）。
+    // 按名保留旧状态（坑 execute-reopen-wipes-prior-completion）：reopenStage 的语义是
+    // 「i < fromStep 保持原状（completed）」，此前预置全 pending 会把 fromStep 之前已完成的
+    // 步骤一并清空——CLI 打印「从步骤 N 开始修订」、prompt 注入「之前已完成不需要重做」，
+    // 实际 currentIdx 却回到 0，agent 被迫从头重做，修订语义完全失效。
     if (needsInit || stageName === 'execute') {
       const freshSteps = await getStageSteps(stageName, cwd, progress, specRoot)
       if (freshSteps && freshSteps.length > 0) {
         if (!progress.stages[stageName]) progress.stages[stageName] = { status: 'stale', steps: [] }
-        progress.stages[stageName].steps = freshSteps.map(s => ({ name: s.name, status: 'pending' }))
+        const oldSteps = progress.stages[stageName].steps || []
+        progress.stages[stageName].steps = freshSteps.map(s => {
+          const old = oldSteps.find(step => step.name === s.name)
+          return old ? { ...old } : { name: s.name, status: 'pending' }
+        })
         pm._write(cwd, progress, effectiveChange)
         progress = pm.read(cwd, effectiveChange) || progress
       }
@@ -1140,15 +1161,17 @@ async function resetStage(pm, progress, stageName, cwd, changeName, platformOpts
 async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts = {}) {
   const flowStages = ['brainstorm', 'plan', 'execute', 'verify', 'archive']
   const isDone = flags.includes('--done')
-  const outputIdx = flags.indexOf('--output')
-  const outputText = outputIdx !== -1 && flags[outputIdx + 1] ? flags[outputIdx + 1] : null
-  const inputIdx = flags.indexOf('--input')
-  const inputText = inputIdx !== -1 && flags[inputIdx + 1] ? flags[inputIdx + 1] : null
+  // F4 守卫（坑 raw-flag-value-bypass，与 runCommand getFlagValue 同款）：裸 flags[idx+1] 会把
+  // 漏值后紧跟的 flag 名当值（--output --done → outputText="--done" 污染落盘 output）。
+  const autoFlagValue = (name) => {
+    const i = flags.indexOf(name)
+    const next = i !== -1 ? flags[i + 1] : undefined
+    return next && !String(next).startsWith('--') ? next : null
+  }
+  const outputText = autoFlagValue('--output')
+  const inputText = autoFlagValue('--input')
   const skipApproval = flags.includes('--skip-approval')
-  const explicitMode = (() => {
-    const m = flags.indexOf('--mode')
-    return m !== -1 && flags[m + 1] ? flags[m + 1] : null
-  })()
+  const explicitMode = autoFlagValue('--mode')
   const specBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
 
   // Helper: 在 auto 模式下获取步骤定义
@@ -1185,7 +1208,10 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
         return progress
       }
     }
-    const changed = await ensureStageSteps(progress, stage, cwd)
+    // specRoot 必传（坑 auto-mode-specroot-miss）：平台模式 specRoot 是外部目录，漏传时
+    // getStageSteps 从 cwd 推导 miss 掉 plan/execute 动态步骤（buildPlanSteps(null) 只剩
+    // 2 步 fixedPrefix），种出的步骤表两次 --done 即判阶段完成，与 getAutoSteps 渲染双轨失配
+    const changed = await ensureStageSteps(progress, stage, cwd, platformOpts?.specRoot || null)
     if (stageChanged || changed) {
       pm._write(cwd, progress, changeName)
       triggerSync(cwd, changeName, platformOpts)
@@ -1271,8 +1297,9 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
           console.log(`⏳ 变更 ${changeName} 的执行审批待处理中...`)
           console.log('  提示：使用 --skip-approval 跳过审批检查')
         }
+        // HUB-07：unknown 醒目警告 + 留痕（原单行 warn 不显眼且无记录）
         if (approval.status === 'unknown') {
-          console.warn(`⚠️ 变更 ${changeName} 的审批状态未知（${approval.reason || '请求失败'}），按本地模式放行（非审批中，无需等待）`)
+          warnApprovalUnknown(cwd, changeName, approval.reason)
         }
       }
     }
@@ -1288,6 +1315,12 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
   const result = await completeStep(pm, progress, currentStage, cwd, outputText, inputText, { printNext: false, changeName, platformOpts })
   if (!result) return
   progress = pm.read(cwd, changeName)
+  // change 行被并发归档/删除时 read 返回 null（体检 BUG-05）：引导排查而非 TypeError 崩溃
+  if (!progress) {
+    console.error(`❌ 完成步骤后进度数据消失（变更 ${changeName} 可能被并发归档/删除），请用 sillyspec progress show 核对当前状态`)
+    process.exitCode = 1
+    return
+  }
 
   const nextPendingIdx = progress.stages[currentStage]?.steps?.findIndex(step => step.status === 'pending' || step.status === 'in-progress') ?? -1
   if (nextPendingIdx !== -1) {
@@ -1304,8 +1337,9 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
           console.log(`⏳ 变更 ${changeName} 的执行审批待处理中...`)
           console.log('  提示：使用 --skip-approval 跳过审批检查')
         }
+        // HUB-07：unknown 醒目警告 + 留痕（原单行 warn 不显眼且无记录）
         if (approval.status === 'unknown') {
-          console.warn(`⚠️ 变更 ${changeName} 的审批状态未知（${approval.reason || '请求失败'}），按本地模式放行（非审批中，无需等待）`)
+          warnApprovalUnknown(cwd, changeName, approval.reason)
         }
       }
     }
@@ -1353,10 +1387,17 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
     progress.stages[next].startedAt = new Date().toLocaleString('zh-CN',{hour12:false})
   }
   progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
-  await ensureStageSteps(progress, next, cwd)
+  // specRoot 同上（坑 auto-mode-specroot-miss）：平台模式动态步骤表必须从外部 specRoot 构建
+  await ensureStageSteps(progress, next, cwd, platformOpts?.specRoot || null)
   pm._write(cwd, progress, changeName)
   triggerSync(cwd, changeName, platformOpts)
   progress = pm.read(cwd, changeName)
+  // 同 BUG-05：写入后被并发删除的窗口，null 直接解引用会 TypeError
+  if (!progress) {
+    console.error(`❌ 阶段推进后进度数据消失（变更 ${changeName} 可能被并发归档/删除），请用 sillyspec progress show 核对当前状态`)
+    process.exitCode = 1
+    return
+  }
 
   console.log(`\n${currentStage} complete. Auto advanced to ${next}.`)
   const nextSteps = await getAutoSteps(next)
@@ -1374,8 +1415,9 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
           console.log(`⏳ 变更 ${changeName} 的执行审批待处理中...`)
           console.log('  提示：使用 --skip-approval 跳过审批检查')
         }
+        // HUB-07：unknown 醒目警告 + 留痕（原单行 warn 不显眼且无记录）
         if (approval.status === 'unknown') {
-          console.warn(`⚠️ 变更 ${changeName} 的审批状态未知（${approval.reason || '请求失败'}），按本地模式放行（非审批中，无需等待）`)
+          warnApprovalUnknown(cwd, changeName, approval.reason)
         }
       }
     }

package/src/run/complete-handlers.js

@@ -98,10 +98,9 @@ export function validateParsedProjects(projects, sourceRoot) {
 /**
  * 在 changes/archive/ 下查找变更 <changeName> 是否已被归档（archive 脱钩自愈用）。
  *
- * 归档目录名 = archiveDestDirName(date, changeName) = `<归档日期>-<剥前导日期的描述>`；
- * 但手动 / 部分流程归档可能保留原 changeName（含前导日期）或用别的日期前缀。
- * 按「描述部分」（剥前导 YYYY-MM-DD-）匹配，并要求目录含 plan.md（归档必备产物，
- * 防止同名巧合误判）。issue: archive-stage-physical-tracking-desync。
+ * 归档目录名 = 原变更名（直接移入 archive/，不重命名）。
+ * 精确匹配 + 要求目录含 plan.md（归档必备产物，防止同名巧合误判）。
+ * issue: archive-stage-physical-tracking-desync。
  *
  * @param {string} archiveDir - changes/archive 绝对路径
  * @param {string} changeName - 变更名（currentChange）
@@ -115,15 +114,9 @@ export function findAlreadyArchivedDir(archiveDir, changeName) {
   } catch {
     return null
   }
-  const descOf = (n) => String(n).replace(/^\d{4}-\d{2}-\d{2}-/, '')
-  const targetDesc = descOf(changeName)
-  if (!targetDesc) return null
-  // 1. 精确原名命中（手动 mv 保留原 changeName）
+  // 精确原名命中
   const exact = entries.find((e) => e === changeName && existsSync(join(archiveDir, e, 'plan.md')))
   if (exact) return join(archiveDir, exact)
-  // 2. 描述部分命中（archiveDestDirName 产出的 <date>-<desc>，或手动剥前导日期的目录）
-  const descMatch = entries.find((e) => descOf(e) === targetDesc && existsSync(join(archiveDir, e, 'plan.md')))
-  if (descMatch) return join(archiveDir, descMatch)
   return null
 }
 
@@ -142,9 +135,14 @@ async function archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platform
   try {
     const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
     if (existsSync(runtimeRoot)) {
+      // stage-review marker 精确匹配（坑 marker-suffix-overmatch）：marker 名是
+      // current-stage-review-run-id-<stage>-<change>，按 endsWith('-'+change) 后缀匹配会在归档
+      // 手工短名变更（如 login）时误删自动日期前缀变更（2026-08-01-login 天然以 '-login' 结尾）
+      // 的 marker。stage 集合与写入侧 stageReviewMarkerPath 的调用方一致。
+      const REVIEW_STAGES = ['brainstorm', 'plan', 'execute', 'verify', 'archive']
       const markers = readdirSync(runtimeRoot).filter((f) =>
         f === `current-execute-run-id-${archiveChangeName}` ||
-        (f.startsWith('current-stage-review-run-id-') && f.endsWith(`-${archiveChangeName}`)),
+        REVIEW_STAGES.some(st => f === `current-stage-review-run-id-${st}-${archiveChangeName}`),
       )
       for (const m of markers) {
         try { unlinkSync(join(runtimeRoot, m)) } catch {}
@@ -506,9 +504,12 @@ export async function handleScanProjectListStep({ stageName, steps, currentIdx,
         const yamlContent = readFileSync(join(projectsDir, yf), 'utf8')
         const pathMatch = yamlContent.match(/^path:\s*(.+)/m)
         const pPath = pathMatch ? pathMatch[1].trim() : pName
-        // 校验 path 是否存在且在 source_root 内
+        // 校验 path 是否存在且在 source_root 内。
+        // 用 relative 判越界（与 validateParsedProjects 同口径）：startsWith 前缀比较
+        // 无分隔符，C:\repo 会放行兄弟目录 C:\repository2（体检 BUG-13）
         const absPath = resolve(cwd, pPath)
-        if (pPath.includes('..') || (!absPath.startsWith(resolve(cwd)) && absPath !== resolve(cwd))) {
+        const rel = relative(resolve(cwd), absPath)
+        if (rel.startsWith('..') || isAbsolute(rel)) {
           fallbackSkipped.push(`${pName} (path 越界: ${pPath})`)
           continue
         }
@@ -1162,7 +1163,9 @@ export async function handleExecuteWaveArtifact({ stageName, steps, currentIdx,
 export async function collectExecuteChangedFiles({ runtimeRoot, changeName }) {
   if (!runtimeRoot || !changeName) return []
   const { resolveLatestExecuteRunIdWithTasks, readReview, normalizeRepoKey } = await import('../task-review.js')
-  const runId = resolveLatestExecuteRunIdWithTasks({ runtimeRoot })
+  // changeName 透传：run 解析按 change 戳优先归属（坑 worktree-cleanup-marker-chain），
+  // 避免 marker 断裂后聚合到其他变更 run 的 changedFiles 误报 missing
+  const runId = resolveLatestExecuteRunIdWithTasks({ runtimeRoot, changeName })
   if (!runId) return []
   const tasksDir = join(runtimeRoot, 'execute-runs', runId, 'tasks')
   if (!existsSync(tasksDir)) return []
@@ -1300,6 +1303,15 @@ export async function handleExecuteWorktreeCleanup({ stageName, changeName, cwd
 export async function handleScanStageCompleted({ stageName, currentIdx, cwd, progress, pm, stageData, changeName, outputText, platformOpts }) {
   // 平台模式：scan 完成后生成 manifest.json + post-check
   if (stageName === 'scan' && (platformOpts.specRoot || platformOpts.runtimeRoot)) {
+    if (!platformOpts.specRoot) {
+      // 只传 runtimeRoot 无 specRoot（command.js 允许的组合）：manifest 无处落盘。
+      // 显式 fail-closed 报错——此前 mkdirSync(null) 抛 TypeError 被外层 catch 吞掉，
+      // postcheck/指针升级/阻断全部静默跳过，scan 失败也"干净成功"（体检 BUG-12）
+      console.error(`❌ 平台模式缺少 --spec-root，无法写 manifest.json（scan postcheck 中止）`)
+      stageData.scanMeta = stageData.scanMeta || {}; stageData.scanMeta.manifestWritten = false
+      stageData.scanMeta.manifestError = 'missing specRoot'
+      return
+    }
     try {
       stageData.scanMeta = stageData.scanMeta || {}; stageData.scanMeta.manifestWritten = false; // 默认失败
       const manifestDir = platformOpts.specRoot