sillyspec 3.26.11 → 3.26.14

package/src/run/concurrent-detect.js

@@ -104,8 +104,10 @@ export function detectConcurrentChanges(cwd, { changeName, linkedChanges = [], o
     if (!file) continue
 
     // rule1：落 .sillyspec/changes/<dir>/ 且 <dir> 非本变更非关联 → otherActiveChanges 去重。
+    // 'archive' 排除（坑 archive-dir-as-other-change）：归档移动产生 .sillyspec/changes/archive/...
+    // 脏路径，extractChangeDir 返回 'archive'，不排除会把归档动作误报成「他者活跃变更: archive」。
     const dir = extractChangeDir(file)
-    if (dir && !ownChangeSet.has(normalizeGitPath(dir))) {
+    if (dir && dir !== 'archive' && !ownChangeSet.has(normalizeGitPath(dir))) {
       otherActiveSet.add(dir)
       continue
     }

package/src/run/gates.js

@@ -26,15 +26,16 @@ import { runValidators } from '../stage-contract.js'
 import { handleScanStageCompleted, handleExecuteWorktreeCleanup } from './complete-handlers.js'
 import { detectConcurrentChanges, formatConcurrentWarning } from './concurrent-detect.js'
 import { stageRegistry } from '../stages/index.js'
+import { normalizeTaskId } from '../taskcard.js'
 
 /**
- * 从 plan.md 提取全部 task id（task-XX）——符号影响面覆盖度校验用。
- * 只认 checkbox 行 `- [ ] task-XX:` / `- [x] task-XX:`（与 execute.js parseWavesFromPlan 的
- * 收容口径一致：### 标题式 task / 非 task 区 checkbox 不算），light plan 的 `## Tasks` 段同样收。
+ * 从任务注册表（tasks.md）提取全部 task id（task-XX）——符号影响面覆盖度校验用。
+ * 只认 checkbox 行 `- [ ] task-XX:` / `- [x] task-XX:`（与 execute.js parseTaskRegistry 同口径）。
+ * 2026-08-20-task-truth-unify：源从 plan.md 迁 tasks.md（任务唯一真相）；ql-xxx 行不收。
  */
-function extractTaskIdsFromPlan(planContent) {
-  if (!planContent) return []
-  return [...String(planContent).matchAll(/^[-*]\s*\[[ x]\]\s*(?:.*\b)?task-(\d+)\b/gim)]
+function extractTaskIdsFromRegistry(tasksContent) {
+  if (!tasksContent) return []
+  return [...String(tasksContent).matchAll(/^[-*]\s*\[[ xX]\]\s*task-(\d+)\b/gim)]
     .map(m => `task-${m[1].padStart(2, '0')}`)
 }
 
@@ -56,8 +57,10 @@ export function validateSymbolImpactReport({ reportContent, planContent }) {
   if (!reportContent || !String(reportContent).trim()) {
     return { ok: false, errors: ['symbol-impact.md 不存在或内容为空——「加载上下文」步的符号影响面报告必须落盘（逐 task 一行结论，「无签名级变更」也要显式写）'] }
   }
-  const taskIds = extractTaskIdsFromPlan(planContent)
-  if (taskIds.length === 0) return { ok: true, errors } // plan 无 task 可列（默认兜底形态）→ 无可校验对象
+  // 2026-08-20-task-truth-unify：task 清单源迁 tasks.md（参数名 planContent 保持兼容既有调用，
+  // 语义=任务注册表内容；调用方 enforceSymbolImpactGate 已改读 tasks.md）
+  const taskIds = extractTaskIdsFromRegistry(planContent)
+  if (taskIds.length === 0) return { ok: true, errors } // 注册表无 task 可列（默认兜底形态）→ 无可校验对象
   const missing = taskIds.filter(id => !String(reportContent).includes(id))
   for (const id of missing) {
     errors.push(`${id} 未在 symbol-impact.md 中出现——每个 task 都要有一行结论（含「无签名级变更」的显式声明）`)
@@ -72,14 +75,14 @@ export function validateSymbolImpactReport({ reportContent, planContent }) {
 export async function enforceSymbolImpactGate(stageName, changeName, currentStepName, specBase) {
   if (stageName !== 'execute') return
   if (!currentStepName || !currentStepName.includes('加载上下文')) return
-  const planPath = join(specBase, 'changes', changeName || '', 'plan.md')
+  const tasksPath = join(specBase, 'changes', changeName || '', 'tasks.md')
   const reportPath = join(specBase, 'changes', changeName || '', 'symbol-impact.md')
-  if (!existsSync(planPath)) return // plan.md 缺失场景已有 plan 阶段 gate 把关，此处不重复拦
-  let planContent = ''
-  try { planContent = readFileSync(planPath, 'utf8') } catch { return }
+  if (!existsSync(tasksPath)) return // 注册表缺失场景已有 plan 阶段 gate 把关，此处不重复拦
+  let tasksContent = ''
+  try { tasksContent = readFileSync(tasksPath, 'utf8') } catch { return }
   let reportContent = null
   try { reportContent = readFileSync(reportPath, 'utf8') } catch { /* 缺失由 validate 报 */ }
-  const result = validateSymbolImpactReport({ reportContent, planContent })
+  const result = validateSymbolImpactReport({ reportContent, planContent: tasksContent })
   if (result.ok) return
   console.error('❌ ── 符号影响面报告校验阻断（本次 --done 未完成，进度未推进）──')
   console.error(`   「加载上下文」步的符号影响面检查报告未落盘或不完整：`)
@@ -89,6 +92,26 @@ export async function enforceSymbolImpactGate(stageName, changeName, currentStep
   process.exit(1)
 }
 
+/**
+ * UI 原型软提醒（非阻断）：brainstorm「生成规范文件」步 --done 时，design.md 命中前端文件
+ * 但变更目录无 prototype-*.html → console.warn 一行，用户可否决。程度判断（布局级才必须出）
+ * 是语义判断，CLI 不硬卡只提示——治 agent 对明显 UI 改造静默跳过原型的坑。
+ */
+export function warnMissingUiPrototype(stageName, changeName, currentStepName, specBase) {
+  if (stageName !== 'brainstorm' || !currentStepName || !currentStepName.includes('生成规范文件')) return
+  if (!changeName || !specBase) return
+  const changeDir = join(specBase, 'changes', changeName)
+  const designPath = join(changeDir, 'design.md')
+  if (!existsSync(designPath)) return
+  try {
+    if (readdirSync(changeDir).some(f => /^prototype-.*\.html$/i.test(f))) return
+  } catch { return } // 目录不可读（平台模式 specRoot 差异等）→ 静默跳过，不制造噪音
+  const design = readFileSync(designPath, 'utf8')
+  const feExts = [...new Set((design.match(/\.(vue|svelte|astro|tsx|jsx|css|scss|sass|less|styl|html)\b/gi) || []).map(s => s.replace('.', '').toLowerCase()))]
+  if (feExts.length === 0) return
+  console.warn(`   ⚠️ design.md 命中前端文件类型（${feExts.join('/')}）但变更目录无 prototype-*.html——轻微样式改动可忽略；布局/交互流程级变化应补原型（sillyspec run brainstorm --reopen 回到「分段展示设计」，或直接让 agent 补生成）`)
+}
+
 /**
  * 判断当前 execute step 所在 wave 是否全部 task 都声明 no_deps_verify: true（D-006@v2）。
  * 仅 wave 执行步骤（名如 "Wave N 执行"）可 opt-out；非 wave 步骤恒返回 false（保守过门）。
@@ -105,10 +128,13 @@ function isCurrentWaveAllNoDepsVerify(stepName, changeDir) {
   const waveRe = new RegExp(`^##\\s*Wave\\s+${waveN}\\b[^\\n]*\\n([\\s\\S]*?)(?=\\n##\\s|\\n#\\s|$)`, 'm')
   const waveMatch = plan.match(waveRe)
   if (!waveMatch) return false
-  const taskIds = [...waveMatch[1].matchAll(/^[-*]\s*\[[ x]\]\s*(task-\d+)/gim)].map(x => x[1])
+  // 2026-08-20-task-truth-unify：Wave 段任务为纯 ID 引用行（"- task-XX"），不再有 checkbox
+  const taskIds = [...waveMatch[1].matchAll(/^[-*]\s+(task-\d+)\s*$/gim)].map(x => x[1])
   if (taskIds.length === 0) return false
   for (const id of taskIds) {
-    const cardPath = join(changeDir, 'tasks', `${id}.md`)
+    // 体检 BUG-19：plan 常态写补零 task-01，但 AI 写出 task-3 时卡片实际是 task-03.md——
+    // 未归一则 existsSync 恒 false，wave 级 no_deps_verify 豁免静默失效（保守方向）
+    const cardPath = join(changeDir, 'tasks', `${normalizeTaskId(id)}.md`)
     if (!existsSync(cardPath)) return false // 卡片缺失 → 保守不跳
     const card = readFileSync(cardPath, 'utf8')
     const fm = card.match(/^---\n([\s\S]*?)\n---/)
@@ -118,6 +144,99 @@ function isCurrentWaveAllNoDepsVerify(stepName, changeDir) {
   return true
 }
 
+/**
+ * doctor --align-execute-progress --confirm 的前置 review 门（坑 doctor-align-bypass-review-gate，
+ * 2026-08-20 实证）：alignExecuteToPlan 直写 completed「绕过 completeStep 推导」，此前 execute 的
+ * Stage Review Gate 与 Task Review Gate 被整体跳过——而 worktree 清理后的恢复场景恰是最需要
+ * review 审计的时刻（实证靠 15 份 task review + verify 全程补足覆盖才没出事）。
+ *
+ * 本函数供 CLI 层（index.js doctor align 分支）在 confirm 落盘前调用，跑与正常完成路径同源的
+ * 只读校验（不自动生成 marker/runId——恢复读场景缺失就是缺失，如实报告）：
+ *   1. Stage Review：tier=independent 时须存在有效 execute stage review.json（verdict 非 fail）；
+ *      tier=self 放行（与正常 gate 分级一致）。
+ *   2. Task Review：所有 task 的 review.json 齐备且 verdict 非 fail（runId 解析同 Task Review Gate：
+ *      marker → 含 tasks/ 目录扫描；不 generate）。
+ *
+ * @param {{ cwd: string, changeName: string, specBase: string, platformOpts?: object }} opts
+ * @returns {Promise<boolean>} true=被门阻断（CLI 应放弃 align 并 exit 1）；false=校验通过可继续
+ */
+export async function enforceAlignExecuteReviewGate({ cwd, changeName, specBase, platformOpts = {} }) {
+  const effectiveSpecBase = platformOpts?.specRoot || specBase
+  const runtimeRoot = resolveRuntimeRoot(platformOpts, effectiveSpecBase)
+  const reviewChangeDir = resolveChangeDir(cwd, { currentChange: changeName }, platformOpts?.specRoot || null)
+  const blocked = (msgs) => {
+    console.error('\n❌ doctor --align-execute-progress 前置 review 校验未过——execute 完成审计不能绕过：')
+    for (const m of msgs) console.error('   - ' + m)
+    console.error('   解法：补齐上述 review 后重跑 align（stage review：sillyspec register-stage-review --change ' + changeName + ' --stage execute；task review：按报错路径补 review.json）')
+    return true
+  }
+
+  // 1. Stage Review（tier 分级同正常 gate）
+  try {
+    const { classifyReviewTier } = await import('../review-tier.js')
+    const { validateStageReview, getLatestStageReviewRunId, printStageReviewResult } = await import('../stage-review.js')
+    const designPath = reviewChangeDir ? join(reviewChangeDir, 'design.md') : null
+    let planLevel = null
+    if (reviewChangeDir) {
+      const planPath = join(reviewChangeDir, 'plan.md')
+      if (existsSync(planPath)) {
+        const fmLine = readFileSync(planPath, 'utf8').split('\n').find(l => l.trim().startsWith('plan_level:'))
+        if (fmLine) planLevel = fmLine.split(':')[1].trim()
+      }
+    }
+    const tier = classifyReviewTier({ planLevel, designPath })
+    if (tier.tier === 'self') {
+      console.log('ℹ️  Stage Review: execute tier=self（' + tier.reason + '），align 前置门放行（不强制独立审查）')
+    } else {
+      // 只读解析（不 generate/写 marker）：恢复场景下缺失即缺失
+      const reviewRunId = getLatestStageReviewRunId(runtimeRoot, 'execute', changeName)
+      if (!reviewRunId) {
+        return blocked(['execute stage review runId 无法定位（marker 缺失且 stage-reviews/ 无含 review 的 run 目录）'])
+      }
+      const searchDirs = [effectiveSpecBase, reviewChangeDir, cwd].filter(Boolean)
+      const reviewResult = validateStageReview({ stage: 'execute', reviewType: 'acceptance', runtimeRoot, reviewRunId, searchDirs })
+      printStageReviewResult(reviewResult, { stage: 'execute', reviewRunId, runtimeRoot })
+      if (!reviewResult.ok) return true // printStageReviewResult 已给明细，不再重复列
+    }
+  } catch (e) {
+    // fail-closed：门自身异常阻断 align（与正常 gate 一致），不静默放行
+    console.error('❌ align 前置 Stage Review 校验异常，阻断对齐: ' + e.message)
+    return true
+  }
+
+  // 2. Task Review（runId 只读解析：marker → 含 tasks/ 扫描；不 generate）
+  try {
+    const { validateTaskReviews, printReviewResult, resolveLatestExecuteRunIdWithTasks, isValidExecuteRunId } = await import('../task-review.js')
+    const planPath = reviewChangeDir ? join(reviewChangeDir, 'plan.md') : null
+    if (!planPath || !existsSync(planPath)) {
+      return blocked(['plan.md 不存在，Task Review 无从校验（align 的 checkbox 判定依赖同目录，疑似路径解析异常）'])
+    }
+    const planContent = readFileSync(planPath, 'utf8')
+    const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
+    let executeRunId = ''
+    try {
+      if (existsSync(runIdFile)) {
+        const c = readFileSync(runIdFile, 'utf8').trim()
+        if (c && isValidExecuteRunId(c)) executeRunId = c
+      }
+    } catch {}
+    if (!executeRunId) {
+      executeRunId = resolveLatestExecuteRunIdWithTasks({ runtimeRoot, changeName }) || ''
+    }
+    if (!executeRunId) {
+      return blocked(['execute runId 无法定位（marker 缺失且 execute-runs/ 无含 review 的 run 目录）——15/N 份 task review 所在 run 不可寻，无法对账'])
+    }
+    const reviewResult = validateTaskReviews({ planContent, runtimeRoot, executeRunId, changeDir: reviewChangeDir, gitDir: cwd })
+    printReviewResult(reviewResult, { runtimeRoot, executeRunId })
+    if (!reviewResult.ok) return true // 报错明细已在 printReviewResult 输出
+    console.log('✅ align 前置 review 校验通过（stage review + task review 均齐备），继续对齐')
+  } catch (e) {
+    console.error('❌ align 前置 Task Review 校验异常，阻断对齐: ' + e.message)
+    return true
+  }
+  return false
+}
+
 /**
  * execute deps 验证硬门（change 2026-06-28-worktree-deps-provision / D-001@v1, D-003@v1, D-006@v2）。
  * depsStatus 不达标且非 wave 级 opt-out 时阻断 --done：置 step=blocked + exit(1)，与 requiresWait 同范式。
@@ -178,19 +297,34 @@ export async function enforceReviewJsonGate(stageName, cwd, changeName, step, st
   const planPath = join(specBase, 'changes', changeName, 'plan.md')
   if (!existsSync(runIdFile) || !existsSync(planPath)) return true
   const { validateCheckedTaskReviews, resolveLatestExecuteRunIdWithTasks, isValidExecuteRunId } = await import('../task-review.js')
-  let executeRunId = readFileSync(runIdFile, 'utf8').trim()
+  // existsSync 与 read 之间 marker 可能被并发 cleanup/归档删除（多 agent 场景）：读失败按
+  //「marker 缺失」处理，走漂移兜底重定位，不让 ENOENT 冒成顶层 stack（与 :426-435 口径对齐）
+  let executeRunId = ''
+  try {
+    executeRunId = readFileSync(runIdFile, 'utf8').trim()
+  } catch {
+    console.warn('⚠️ execute run marker 读取失败（可能被并发清理），改扫真实 run 目录')
+    executeRunId = resolveLatestExecuteRunIdWithTasks({ runtimeRoot, changeName }) || ''
+  }
   // marker 是 agent 可写内容：格式校验防注入/穿越，非法视为缺失走漂移兜底重定位
   if (executeRunId && !isValidExecuteRunId(executeRunId)) {
     console.warn(`⚠️ execute run marker 内容非法（期望 exec-YYYY-MM-DD-HHMMSS，实得 ${JSON.stringify(executeRunId.slice(0, 60))}），改扫真实 run 目录`)
     executeRunId = ''
   }
-  const planContent = readFileSync(planPath, 'utf8')
+  // 2026-08-20-task-truth-unify：已勾 task 清单源迁 tasks.md（勾选唯一落点）；tasks.md 缺失
+  // 回退 planPath 内容（旧变更兼容读侧）。planPath 存在性已在上方把关。
+  const tasksRegistryPath = join(specBase, 'changes', changeName, 'tasks.md')
+  const planContent = existsSync(tasksRegistryPath)
+    ? readFileSync(tasksRegistryPath, 'utf8')
+    : readFileSync(planPath, 'utf8')
+  // marker 读失败且重定位无果（无任何含 tasks/ 的 run）：无 run 可校验，放行（下游 Task Review Gate 兜底）
+  if (!executeRunId) return true
   // marker 漂移兜底（gate-atom-a 正确修法）：marker 指向的 run 缺 tasks/（generateExecuteRunId 只写
   // marker 不建目录，漂移后新 run 不继承旧 review）时，无视 marker 改扫 execute-runs/ 取 mtime 最新
   // 且真正含 tasks/ 的 run，用其齐备的 review.json 校验，避免误报「review.json 不存在」。注意不能用
   // resolveLatestExecuteRunId——它见 marker 非空即原样返回（不校验目录），恰是本场景要绕开的值。
   if (executeRunId && !existsSync(join(runtimeRoot, 'execute-runs', executeRunId, 'tasks'))) {
-    const relocated = resolveLatestExecuteRunIdWithTasks({ runtimeRoot })
+    const relocated = resolveLatestExecuteRunIdWithTasks({ runtimeRoot, changeName })
     if (relocated && relocated !== executeRunId) {
       console.warn(`⚠️ execute run marker 漂移：${executeRunId} 无 tasks/，改用真实含 review 的 run ${relocated}`)
       executeRunId = relocated
@@ -331,18 +465,21 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     console.log('\n✅ 验证通过，下一步：sillyspec run archive')
   }
 
-  // ── Plan postcheck contract：plan.md 必须满足 execute 契约 ──
+  // ── Plan postcheck contract：tasks.md（注册表）× plan.md（Wave 引用）须满足 execute 契约 ──
   if (stageName === 'plan') {
     const planFile = resolveChangeDir(cwd, progress, platformOpts?.specRoot)
     const planPath = planFile ? join(planFile, 'plan.md') : null
     if (planPath && existsSync(planPath)) {
       const { validatePlanForExecute } = await import('../stages/execute.js')
-      const planContent = readFileSync(planPath, 'utf8')
-      const planValidation = validatePlanForExecute(planContent)
+      // CRLF 归一：Windows 编辑器/python 写文件可产生 CRLF，归一后交校验（与 plan-postcheck.js 同口径）
+      const planContent = readFileSync(planPath, 'utf8').replace(/\r\n/g, '\n')
+      const tasksPath = join(planFile, 'tasks.md')
+      const tasksContent = existsSync(tasksPath) ? readFileSync(tasksPath, 'utf8').replace(/\r\n/g, '\n') : ''
+      const planValidation = validatePlanForExecute(tasksContent, planContent)
       if (!planValidation.ok) {
         console.error(`\n❌ Plan → Execute Contract 校验失败：`)
         for (const err of planValidation.errors) console.error(`   - ${err}`)
-        console.error(`\n   plan.md 不满足 execute 契约，请修复后重新完成此步骤。`)
+        console.error(`\n   tasks.md/plan.md 不满足 execute 契约，请修复后重新完成此步骤。`)
         // 阻断 completed
         return await rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx, cwd, changeName, platformOpts)
       }
@@ -415,7 +552,12 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
       const planPath = planFile ? join(planFile, 'plan.md') : null
 
       if (planPath && existsSync(planPath)) {
-        const planContent = readFileSync(planPath, 'utf8')
+        // 2026-08-20-task-truth-unify：任务清单源迁 tasks.md（validateTaskReviews 内按
+        // checkbox 行解析，tasks.md 行格式兼容原正则）；缺失回退 plan.md（旧变更兼容读侧）
+        const tasksRegistryPath = join(planFile, 'tasks.md')
+        const planContent = existsSync(tasksRegistryPath)
+          ? readFileSync(tasksRegistryPath, 'utf8')
+          : readFileSync(planPath, 'utf8')
         const runtimeRoot = resolveRuntimeRoot(platformOpts, effectiveSpecBase)
 
         // execute run id：从变更专属标记文件读取（agent 可写内容，格式校验防注入/穿越）
@@ -436,7 +578,7 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
           // marker 缺失：先扫描 execute-runs/ 既有目录找回真实 runId（与 getLatestStageReviewRunId
           // 目录扫描兜底同语义），避免 marker 丢失而 agent 已用旧 runId 落盘时，直接 generate 新 ID
           // 找不到旧 review、误判缺 review.json。仅当确实无既有 run 才 generate 新 ID 并落盘。
-          const { generateExecuteRunId, resolveLatestExecuteRunId } = await import('../task-review.js')
+          const { generateExecuteRunId, resolveLatestExecuteRunId, stampExecuteRunChange } = await import('../task-review.js')
           executeRunId = resolveLatestExecuteRunId({ runtimeRoot, changeName }) || ''
           if (!executeRunId) {
             executeRunId = generateExecuteRunId()
@@ -446,6 +588,7 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
             //（gate 自身写 run 目录失败不能静默放行完成）。
             mkdirSync(join(runtimeRoot, 'execute-runs', executeRunId, 'tasks'), { recursive: true })
             writeFileSync(runIdFile, executeRunId + '\n')
+            stampExecuteRunChange(runtimeRoot, executeRunId, changeName)
           }
         }
 
@@ -480,7 +623,7 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
           // 检查是否存在 checkbox 已勾但 review 不通过的情况
           const uncheckedTasks = reviewResult.errors.filter(e => e.includes('缺少 review.json'))
           if (uncheckedTasks.length > 0) {
-            console.error('\n⚠️  部分任务已在 plan.md 中勾选，但 review.json 不存在。')
+            console.error('\n⚠️  部分任务已在 tasks.md 中勾选，但 review.json 不存在。')
             console.error(`   请取消勾选这些任务的 checkbox，或补充对应的 review.json（execute run ID: ${executeRunId}）。`)
           }
           return await rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx, cwd, changeName, platformOpts)
@@ -731,6 +874,10 @@ export async function completeStageGates({ stageName, cwd, changeName, platformO
     stageData.steps = freshSteps
     stageData.status = 'pending'
     stageData.completedAt = null
+    // scan 的 quick 档 profile 随步骤表一并失效（坑 scan-quick-profile-step-mismatch 收尾）：
+    // getStageSteps 感知 scanProfile 返回 3 步表，重置后 DB 是 11 步注册表，残留 profile 会让
+    // 下次 --status 走 ensureStageSteps 时 11 vs 3 误报漂移重播种。下次 run scan 会重算 profile。
+    if (stageName === 'scan' && stageData.scanProfile) delete stageData.scanProfile
     if (progress.currentStage === stageName) progress.currentStage = ''
     pm._write(cwd, progress, changeName)
   }

package/src/run/prompt.js

@@ -183,8 +183,11 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   console.log(`project: ${projectName}`)
   if (changeName) {
     console.log(`change: ${changeName}`)
-    const isPlatform = platformOpts?.specRoot || platformOpts?.runtimeRoot
-    const changeDirBase = isPlatform ? platformOpts.specRoot : '.sillyspec'
+    // changeDir 根（坑 change-dir-base-mismatch）：平台/漂移锚定用绝对根（specDriftAnchor 防
+    // worktree 副本错位），普通本地保持相对 '.sillyspec' 展示契约（test 钉死）。此前
+    // isPlatform 用 specRoot||runtimeRoot 判定、取值只拿 specRoot——runtimeRoot-only 平台组合
+    // join(null,...) 直接 TypeError。
+    const changeDirBase = platformOpts?.specRoot || platformOpts?.specDriftAnchor || '.sillyspec'
     const changeDir = join(changeDirBase, 'changes', changeName)
     console.log(`changeDir: ${changeDir}`)
   }
@@ -257,7 +260,9 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       if (existsSync(sessionGuardFile)) {
         qlIdVal = JSON.parse(readFileSync(sessionGuardFile, 'utf8')).quicklogId || ''
       }
-    } catch {}
+    } catch (err) {
+      console.warn(`⚠️ quicklog-id 占位符读取 guard.json 失败: ${err && err.message ? err.message : err}`);
+    }
     promptText = promptText.replace(/<quicklog-id>/g, qlIdVal || '(未分配)')
   }
   // 替换 <linked-changes> 占位符（quick 阶段：从 .runtime/quick-sessions/<sessionId>/guard.json 读关联变更）
@@ -414,14 +419,16 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       const { matchKnowledge } = await import('../knowledge-match.js')
       const effectiveSpecBase = resolvePromptSpecBase(platformOpts, cwd)
       const knowledgeDir = join(effectiveSpecBase, 'knowledge')
-      // taskContext: changeName + plan.md task names for better matching
+      // taskContext: changeName + tasks.md 任务名（注册表唯一真相，2026-08-20-task-truth-unify）
       let taskContext = changeName || ''
       if (changeName) {
+        const tasksMdPath = join(effectiveSpecBase, 'changes', changeName, 'tasks.md')
         const planPath = join(effectiveSpecBase, 'changes', changeName, 'plan.md')
+        const srcPath = existsSync(tasksMdPath) ? tasksMdPath : planPath
         try {
-          const planContent = readFileSync(planPath, 'utf8')
-          // match both "- [ ] task-01: title" and "## task-01: title" formats
-          const taskLines = [...planContent.matchAll(/(?:^\- \[[ x]\] |^## )task-\d+[^:]*:?\s*(.+)/gm)]
+          const registryContent = readFileSync(srcPath, 'utf8')
+          // match "- [ ] task-01: title" / "## task-01: title"（兼容旧 plan.md 内联两种形态）
+          const taskLines = [...registryContent.matchAll(/(?:^\- \[[ x]\] |^## )task-\d+[^:]*:?\s*(.+)/gm)]
           if (taskLines.length > 0) {
             taskContext += ' ' + taskLines.map(t => t[1]).join(' ')
           }
@@ -711,8 +718,9 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       console.log('- **平台模式：local.yaml 中的 commands 必须在 package.json scripts 中真实存在，不存在的标记 unavailable。**')
     }
     if (changeName) {
-      const isPlatform = platformOpts?.specRoot || platformOpts?.runtimeRoot
-      const changeDirBase = isPlatform ? platformOpts.specRoot : '.sillyspec'
+      // changeDir 根与上方头部同源（坑 change-dir-base-mismatch）：平台/漂移锚定绝对根，
+      // 普通本地保持相对 '.sillyspec' 展示；runtimeRoot-only 组合不再 join(null) 崩溃
+      const changeDirBase = platformOpts?.specRoot || platformOpts?.specDriftAnchor || '.sillyspec'
       const changeDir = join(changeDirBase, 'changes', changeName)
       console.log(`- **文件路径规则：所有变更文件必须写入 \`${changeDir}/\` 目录下。不要自己拼接路径，直接使用 changeDir 值。示例：\`${changeDir}/proposal.md\`**`)
     }

package/src/run/scan-profile.js

@@ -105,21 +105,15 @@ export function computeScanProfile(cwd, platformOpts) {
 }
 
 /**
- * 根据 scanProfile 裁剪步骤
- * quick:   3 步 — CLI preflight / AI generate / CLI postcheck
- * standard: 跳过续扫检测(4), 跳过可选步骤(9)
+ * quick 档 3 步表构建（唯一真相）：applyScanProfileSteps（首进程裁剪）与 getStageSteps
+ * （后续进程重取定义）共用。此前 quick 步骤表只在首进程 applyScanProfileSteps 里内联构建，
+ * getStageSteps('scan') 恒返回 11 步注册表 → 同进程 outputStep 用注册表 defSteps[1] 渲染错位
+ * prompt；跨进程 ensureStageSteps 见 3 vs 11 触发长度漂移重播种，quick 已完成步丢失、
+ * agent 从未做过的注册表步骤被 --done（坑 scan-quick-profile-step-mismatch）。
  */
-export function applyScanProfileSteps(stageData, profile, cwd, platformOpts) {
-  const steps = stageData.steps
-  const mode = profile.mode
-
-  if (mode === 'quick') {
-    const specBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
-    const projectName = basename(cwd)
-    const docsRoot = join(specBase, 'docs', projectName)
-
-    // Step 1: CLI preflight（不调 AI，自动完成）
-    const step1 = {
+export function buildQuickScanSteps() {
+  return [
+    {
       name: '项目概览（自动探测）',
       status: 'pending',
       noAI: true,
@@ -127,9 +121,8 @@ export function applyScanProfileSteps(stageData, profile, cwd, platformOpts) {
       prompt: '',
       outputHint: 'preflight 结果',
       optional: false
-    }
-    // Step 2: AI 生成核心文档（唯一 AI roundtrip）
-    const step2 = {
+    },
+    {
       name: '生成核心文档',
       status: 'pending',
       prompt: `## Quick Scan — 核心文档生成
@@ -156,13 +149,32 @@ export function applyScanProfileSteps(stageData, profile, cwd, platformOpts) {
 生成的文件列表`,
       outputHint: '文件列表',
       optional: false
+    },
+    {
+      // 名字与注册表末步一致（按名匹配/迁移语义）；prompt 清空、noAI postcheck 自动执行
+      name: '自检和提交',
+      status: 'pending',
+      prompt: '',
+      outputHint: '结果',
+      optional: false,
+      noAI: true,
+      _cliAction: 'scanPostcheck'
     }
-    // Step 3: CLI postcheck（不调 AI，自动完成）
-    const selfCheck = steps.find(s => s.name === '自检和提交') || {
-      name: '自检和提交', status: 'pending', prompt: '', outputHint: '结果', optional: false
-    }
-    const step3 = { ...selfCheck, status: 'pending', noAI: true, _cliAction: 'scanPostcheck', prompt: '' }
-    stageData.steps = [step1, step2, step3]
+  ]
+}
+
+/**
+ * 根据 scanProfile 裁剪步骤
+ * quick:   3 步 — CLI preflight / AI generate / CLI postcheck
+ * standard: 跳过续扫检测(4), 跳过可选步骤(9)
+ */
+export function applyScanProfileSteps(stageData, profile, cwd, platformOpts) {
+  const steps = stageData.steps
+  const mode = profile.mode
+
+  if (mode === 'quick') {
+    // 3 步表构建抽至 buildQuickScanSteps（getStageSteps 同源复用，防跨进程 3 vs 11 漂移）
+    stageData.steps = buildQuickScanSteps()
     return
   }