sillyspec 3.25.5 → 3.25.7

package/src/run/complete.js

@@ -18,7 +18,7 @@ import { join } from 'node:path'
 import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, appendFileSync, statSync } from 'node:fs'
 import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions } from './shared.js'
 import { outputStep } from './prompt.js'
-import { enforceDepsGate, runStageCompletionGates } from './gates.js'
+import { enforceDepsGate, enforceReviewJsonGate, runStageCompletionGates } from './gates.js'
 import { handleArchiveConfirmStep, handlePlanGeneratePlanStep, handleScanProjectListStep, handleWorkflowPostCheck, handleQuickStageCompletion, handleExecuteWaveArtifact, handleExecuteWorktreeCleanup, handleScanStageCompleted } from './complete-handlers.js'
 import { stageRegistry } from '../stages/index.js'
 import { formatExecuteSummary } from '../worktree-apply.js'
@@ -54,6 +54,22 @@ function validateMetadata(cwd, stageName, specBase) {
   }
 }
 
+/**
+ * 读取 design.md frontmatter 的 scale 字段（brainstorm 末步写入 'small'|'large'）。
+ * completeStep 的下一步提示据此分叉：small→quick，large/读不到→plan（fail-safe 走重流程）。
+ * 只解析首个 YAML frontmatter 块，避免误读正文里的 "scale:"。
+ */
+function readDesignScale(specBase, changeName) {
+  if (!changeName) return null
+  const designPath = join(specBase, 'changes', changeName, 'design.md')
+  if (!existsSync(designPath)) return null
+  const text = readFileSync(designPath, 'utf8')
+  const fm = text.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/)
+  if (!fm) return null
+  const m = fm[1].match(/^scale:[ \t]*['"]?(\w+)/m)
+  return m ? m[1] : null
+}
+
 /**
  * 验证关键文件是否存在于正确的变更目录下
  * 防止 AI 将文件写到错误的路径
@@ -100,6 +116,36 @@ function validateFileLocations(cwd, stageName, progress, changeName, specBase) {
   }
 }
 
+/**
+ * 坑1：用 --done --answer 解掉「已 waiting 的步骤」。
+ *
+ * completeStep 的 currentIdx 选择（findIndex pending||in-progress）排除 waiting，导致
+ * --done --answer 落到已 --wait 暂停的 requiresWait 步骤时跳过它、--answer 静默丢失、步骤永久
+ * 卡 WAITING、末步报「Step N 等待用户输入」无法 finish。本函数把首个 waiting 步骤拉回 pending
+ * + 补 waitAnswer（对齐 continueStep 对 requiresWait 的 shouldReturnToCurrentStep=回 pending 语义），
+ * 让主流程 requiresWait 门控见 waitAnswer 已置→不阻断→正常 completed。
+ *
+ * @param {object[]} steps - stageData.steps（原地修改）
+ * @param {string|null|undefined} doneAnswer - --answer 值；空则不触发（返回 -1）
+ * @param {string} nowStr - 时间戳字符串（用于 waitAnswers[].answeredAt）
+ * @returns {number} 被解的 waiting 步骤 idx；无 waiting 或无 answer 返回 -1
+ */
+export function resolveWaitingStepWithAnswer(steps, doneAnswer, nowStr) {
+  if (!doneAnswer) return -1
+  const waitIdx = steps.findIndex(s => s && s.status === 'waiting')
+  if (waitIdx === -1) return -1
+  const ws = steps[waitIdx]
+  ws.waitAnswer = doneAnswer
+  ws.waitAnswers = Array.isArray(ws.waitAnswers) ? ws.waitAnswers : []
+  ws.waitAnswers.push({ round: (ws.waitRound || 0) + 1, answer: doneAnswer, answeredAt: nowStr })
+  delete ws.waitReason
+  delete ws.waitOptions
+  delete ws.waitedAt
+  ws.status = 'pending'
+  ws.completedAt = null
+  return waitIdx
+}
+
 export async function completeStep(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
   const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, confirmMode = null, isForceBaseline = false, isAllowNew = false } = options
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
@@ -129,7 +175,17 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   }
 
   const steps = stageData.steps
-  const currentIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
+  let currentIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
+  // ── 坑1：--done --answer 解「已 waiting 的步骤」──
+  // findIndex 仅查 pending/in-progress，排除 waiting；故 --done --answer 落到已 --wait 暂停的
+  // requiresWait 步骤时会跳过它、把 --answer 静默丢弃，步骤永久卡 WAITING、末步报「等待用户输入」。
+  // 修复：带 doneAnswer 且存在 waiting 步骤时，把首个 waiting 拉回 pending + 补 waitAnswer，主流程
+  // requiresWait 门控见 waitAnswer 已置→不阻断→正常 completed。仅 --answer 触发，普通 --done 零变化。
+  const _resolvedWaitIdx = resolveWaitingStepWithAnswer(steps, options && options.doneAnswer, new Date().toLocaleString('zh-CN', { hour12: false }))
+  if (_resolvedWaitIdx !== -1) {
+    currentIdx = _resolvedWaitIdx
+    console.log(`⚠️  Step "${steps[_resolvedWaitIdx].name}" 此前处于 waiting，--done --answer 已补回答并拉回待完成。`)
+  }
   if (currentIdx === -1) {
     console.error('没有待完成的步骤')
     process.exit(1)
@@ -174,6 +230,9 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
 
   // ── execute deps 验证硬门（change 2026-06-28-worktree-deps-provision）──
   await enforceDepsGate(stageName, cwd, changeName, steps[currentIdx], steps, currentIdx, specBase, platformOpts)
+  // review.json 字段硬门（坑 review-json-field-gap）：已勾 [x] task 的 review.json 必须 schema 完整，
+  // 提前到每次 --done 校验（而非等 Task Review Gate 在整阶段收尾才暴露，迫使用户事后批量补）。
+  await enforceReviewJsonGate(stageName, cwd, changeName, steps[currentIdx], steps, currentIdx, specBase, platformOpts)
 
   steps[currentIdx].status = 'completed'
   steps[currentIdx].completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
@@ -226,6 +285,22 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     if (_bf.batched && _bf.aligned > 0) {
       console.log(`\n🚀 execute 批量完成：plan 全勾 + 代码核验通过，一次性补完 ${_bf.aligned} 个剩余 step → 进入阶段完成分支`)
     }
+
+    // per-task review 草稿兜底（坑 worktree-execute-apply-friction 坑2）：主 agent 直接实现模式
+    // 无子代理 review 落盘 → Task Review Gate 报缺 review.json 阻断。每次 execute --done 跑（幂等，
+    // 已存在跳过），据 git diff base..head 按 allowed_paths 归属生成 cannot_verify 草稿，进 gate 前就位。
+    try {
+      const { generateTaskReviewDrafts } = await import('../task-review.js')
+      const _drafts = await generateTaskReviewDrafts({ changeName, cwd, platformOpts })
+      if (_drafts.generated > 0) {
+        console.log('   📄 自动补写 ' + _drafts.generated + ' 个 per-task review.json 草稿（cannot_verify，主 agent 实现模式兜底，需 agent 复核后升级为 pass/fail）')
+        if (_drafts.unattributed && _drafts.unattributed.length > 0) {
+          console.warn('   ⚠️ ' + _drafts.unattributed.length + ' 个变更文件未归属任何 task（顺带修复/非源码），草稿未覆盖：' + _drafts.unattributed.join(', '))
+        }
+      }
+    } catch (e) {
+      console.warn('   ⚠️ per-task review 草稿生成失败（不阻断 execute 完成）：' + (e && e.message ? e.message : e))
+    }
   }
 
   const nextPendingIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
@@ -313,6 +388,22 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     } else if (stageName === 'verify') {
       // verify 的"验证通过"提示延后到下方 validator 通过后才打印，
       // 避免校验失败（FAIL / 缺 verify-result.md）时仍声称"验证通过可以归档"。
+    } else if (stageName === 'brainstorm') {
+      // brainstorm 下一步按 design.md 的 scale 分叉（与末步 prompt 的 large→plan / small→quick 对齐），
+      // 不走下方 _getNextSuggestion —— 后者按全局状态机「第一个未完成且上游就绪的阶段」推荐，
+      // 当 scan 未完成时会误推 scan（回头路），与 brainstorm 已完成、应进入 plan/quick 矛盾。
+      // 历史教训：曾因此让 agent 在 brainstorm 完成后被误导去跑 scan。
+      const _bscale = readDesignScale(specBase, changeName)
+      if (_bscale === 'small') {
+        console.log(`\n👉 brainstorm 已完成（small）。下一步：sillyspec run quick --linked-changes ${changeName}`)
+      } else {
+        console.log(`\n👉 brainstorm 已完成。下一步：sillyspec run plan${changeName ? ` --change ${changeName}` : ''}（scale=large 或未标 small 走完整 plan）`)
+      }
+    } else if (stageName === 'quick') {
+      // quick 是收尾阶段（辅助流程，不走主链 scan→archive），完成后该提交，而非推 scan。
+      // 走下方 _getNextSuggestion 会因 scan 是 STAGE_ORDER 首位、永未完成而误推 scan（回头路），
+      // 与 brainstorm 同类问题（见上注释），故给 quick 专属分支。
+      console.log('\n👉 quick 已完成。下一步：提交本次改动（git commit / sillyspec-commit），或 sillyspec run <stage> 继续其他阶段。')
     } else {
       // D1 暗衔接修：阶段刚完成，CLI 本就知道状态机下一步是哪个阶段（_getNextSuggestion），
       // 却只丢一句「下一步由你决定」让 agent 自己猜命令。改为按 progress 实际状态给出精确命令。
@@ -719,7 +810,16 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
     // 阶段完成后明确下一步（agent 常卡：stageData completed 但不知要 run <下一阶段> 推进 currentStage）
     const nextStageHint = { brainstorm: 'plan', plan: 'execute', execute: 'verify', verify: 'archive' }[stageName]
     if (nextStageHint) {
-      console.log(`\n👉 ${stageName} 已完成。下一步：sillyspec run ${nextStageHint}${changeName ? ` --change ${changeName}` : ''}`)
+      // brainstorm 按 design.md frontmatter 的 scale 分叉（与末步 prompt 对齐）：
+      //   small → quick --linked-changes（小变更免走完整 plan）；large / 读不到 scale → plan（保守默认）。
+      // 修历史 bug：此处曾硬编码 brainstorm→plan 不读 scale，small 档与末步 prompt（quick）矛盾、误导小变更进 plan。
+      let hintStage = nextStageHint
+      let hintChangeFlag = changeName ? ` --change ${changeName}` : ''
+      if (stageName === 'brainstorm' && changeName && readDesignScale(specBase, changeName) === 'small') {
+        hintStage = 'quick'
+        hintChangeFlag = ` --linked-changes ${changeName}`
+      }
+      console.log(`\n👉 ${stageName} 已完成。下一步：sillyspec run ${hintStage}${hintChangeFlag}`)
       if (stageName === 'execute') {
         console.log(`   ⚠️ 若 worktree 改动还没 apply 到主工作区，先：sillyspec worktree apply ${changeName}`)
         console.log(`   （apply 不需要先 commit，支持 working tree 未提交改动）`)

package/src/run/gates.js

@@ -96,6 +96,39 @@ export async function enforceDepsGate(stageName, cwd, changeName, step, steps, c
   }
   process.exit(1)
 }
+
+/**
+ * execute --done 硬门：已勾 [x] task 的 review.json 必须 schema 完整（坑 review-json-field-gap）。
+ *
+ * Task Review Gate（validateTaskReviews）只在 execute 整阶段完成时跑（complete.js 阶段完成分支的
+ * actualCompleted===actualTotal 守卫），单 task --done 不校验 → 子代理勾 checkbox 却漏写/漏字段
+ * review.json，要到收尾才暴露，用户被迫事后批量补。本门提前到每次 --done：校验 plan 里所有已勾
+ * task 的 review.json，缺字段/不存在/JSON 坏 → 置 step=blocked + exit(1)，与 enforceDepsGate 同范式。
+ * 未勾 task 不校验（还没做）。平台模式/无 marker/无 plan 时放行（下游 Task Review Gate 兜底）。
+ */
+export async function enforceReviewJsonGate(stageName, cwd, changeName, step, steps, currentIdx, specBase, platformOpts) {
+  if (stageName !== 'execute' || !changeName) return true
+  const runtimeRoot = platformOpts?.runtimeRoot || join(specBase, '.runtime')
+  const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
+  const planPath = join(specBase, 'changes', changeName, 'plan.md')
+  if (!existsSync(runIdFile) || !existsSync(planPath)) return true
+  const executeRunId = readFileSync(runIdFile, 'utf8').trim()
+  const planContent = readFileSync(planPath, 'utf8')
+  const { validateCheckedTaskReviews } = await import('../task-review.js')
+  const result = validateCheckedTaskReviews({ planContent, runtimeRoot, executeRunId })
+  if (result.ok) return true
+  if (steps && steps[currentIdx]) steps[currentIdx].status = 'blocked'
+  console.error('❌ ── review.json 字段校验阻断（本次 --done 未完成，进度未推进）──')
+  console.error('   已勾选 [x] 的 task review.json 不完整（铁律：勾 checkbox 前必须先写完整 review.json）:')
+  for (const f of result.failures) {
+    const kindLabel = f.kind === 'missing' ? 'review.json 不存在' : (f.kind === 'parseError' ? 'JSON 解析失败' : '字段缺失')
+    console.error(`   • ${f.taskId}（${kindLabel}）: ${f.reviewPath}`)
+    for (const e of f.errors) console.error(`       - ${e}`)
+  }
+  console.error('   修复：补全上述 review.json 字段后重跑 execute --done。')
+  process.exit(1)
+}
+
 /**
  * 阶段完成校验失败时回滚状态。
  *
@@ -183,6 +216,10 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     const { runVerifyParityCheck, printVerifyParityCheck } = await import('../verify-postcheck.js')
     const parityCheck = runVerifyParityCheck({ cwd, specBase, changeName, runtimeRoot: platformOpts?.runtimeRoot })
     printVerifyParityCheck(parityCheck)
+    // ── 删除探针（advisory，不阻断）：切斯特顿栅栏护栏，用 git 事实对账静默删除代码 ──
+    const { runVerifyDeletionCheck, printVerifyDeletionCheck } = await import('../verify-postcheck.js')
+    const deletionCheck = runVerifyDeletionCheck({ cwd, specBase, changeName })
+    printVerifyDeletionCheck(deletionCheck)
     console.log('\n✅ 验证通过，下一步：sillyspec run archive')
   }
 

package/src/run/quick-audit.js

@@ -34,7 +34,14 @@ export function printQuickAuditReview(review) {
       console.warn(`   - ${r}`)
     }
   } else {
-    console.log(`\n✅ quick 变更边界审计 — SAFE (变更 ${review.changedFiles.length} 个文件)`)
+    // 区分「本轮新增」（changedFiles，已扣前序 baseline）vs「累计暂存」（stagedTotal，全部未提交）。
+    // 仅当存在前序 baseline 残留（累计 > 本轮新增）时才追加括注，避免普通场景冗余。
+    const stagedTotal = typeof review.stagedTotal === 'number' ? review.stagedTotal : review.changedFiles.length
+    if (stagedTotal > review.changedFiles.length) {
+      console.log(`\n✅ quick 变更边界审计 — SAFE (本轮新增变更 ${review.changedFiles.length} 个文件；累计暂存 ${stagedTotal} 个，含前序 baseline ${stagedTotal - review.changedFiles.length} 个未计入本轮)`)
+    } else {
+      console.log(`\n✅ quick 变更边界审计 — SAFE (本轮新增变更 ${review.changedFiles.length} 个文件)`)
+    }
   }
 }
 

package/src/run/scan-profile.js

@@ -15,23 +15,36 @@ import { safeGit } from './shared.js'
 /**
  * 估算源码规模（文件数 + 字节数）—— 跨平台 Node 遍历，替代 Unix `find`（原生 Windows 无 find，
  * 原 find 失效会让所有 Windows 项目永远 fallback 到 standard profile）。
- * 扩展名与排除目录与原 find 命令逐字一致；maxFiles 封顶避免超大仓库遍历过久
- * （超限时 fileCount 已远超 quick/standard 阈值，不影响 profile 判定）。
+ * 扩展名限定源码后缀；skipDirs 排除依赖/构建产物/覆盖率等非源码目录；maxFiles 封顶避免超大仓库遍历过久
+ * （超限时 fileCount 已远超 quick/standard 阈值，不影响 profile 判定）；maxDepth 兜底防极深嵌套产物。
  */
-export function estimateSourceSize(cwd, maxFiles = 5000) {
+export function estimateSourceSize(cwd, maxFiles = 5000, maxDepth = 6) {
   const sourceExts = new Set(['.js','.ts','.tsx','.py','.java','.go','.rs','.rb','.php','.c','.cpp','.h','.jsx','.vue','.svelte'])
-  const skipDirs = new Set(['node_modules','.git','dist','build','__pycache__','.sillyspec','.claude'])
+  // skipDirs：排除依赖、版本控制、构建产物、覆盖率、临时目录等非源码目录。
+  // 原清单只排了 node_modules/.git/dist/build 等，漏了 .next/.nuxt/coverage/.svelte-kit 等构建产物，
+  // 导致带构建产物的小项目被产物里的海量 .js 拉高 fileCount/sourceBytes → 误判 deep。
+  const skipDirs = new Set([
+    'node_modules', '.git', 'dist', 'build', 'out', 'target',
+    '__pycache__', '.venv', 'venv',
+    '.next', '.nuxt', '.output', '.svelte-kit', '.astro', '.turbo', '.parcel-cache',
+    'coverage', '.nyc_output', '.vitest', '.cache',
+    'vendor', 'bower_components',
+    'dist-types',
+    '.sillyspec', '.claude',
+    'tmp', 'temp', '.tmp', 'logs',
+  ])
   let fileCount = 0
   let sourceBytes = 0
-  const stack = [cwd]
+  // stack 存 [dir, depth]：maxDepth 兜底，防极深嵌套的产物/生成目录在 skipDirs 漏网时被全遍历。
+  const stack = [[cwd, 0]]
   while (stack.length) {
-    const dir = stack.pop()
+    const [dir, depth] = stack.pop()
     let entries
     try { entries = readdirSync(dir, { withFileTypes: true }) }
     catch { continue }
     for (const e of entries) {
       if (e.isDirectory()) {
-        if (!skipDirs.has(e.name)) stack.push(join(dir, e.name))
+        if (!skipDirs.has(e.name) && depth < maxDepth) stack.push([join(dir, e.name), depth + 1])
       } else if (e.isFile() && sourceExts.has(extname(e.name))) {
         fileCount++
         try { sourceBytes += statSync(join(dir, e.name)).size } catch {}
@@ -49,8 +62,14 @@ export function estimateSourceSize(cwd, maxFiles = 5000) {
  * deep:    大项目或 --deep → 完整流程
  */
 export function computeScanProfile(cwd, platformOpts) {
-  // --deep 标志强制 deep
+  // 显式 profile flag 优先于自动判定（三档互斥由 command.js 检测；此处取首个命中即可）
   const flags = process.argv.slice(2)
+  if (flags.includes('--quick')) {
+    return { mode: 'quick', reason: '用户指定 --quick', maxAgentCalls: 0, maxDocs: 5 }
+  }
+  if (flags.includes('--standard')) {
+    return { mode: 'standard', reason: '用户指定 --standard', maxAgentCalls: 1, maxDocs: 8 }
+  }
   if (flags.includes('--deep')) {
     return { mode: 'deep', reason: '用户指定 --deep', maxAgentCalls: 4, maxDocs: 99 }
   }
@@ -115,7 +134,7 @@ export function applyScanProfileSteps(stageData, profile, cwd, platformOpts) {
       status: 'pending',
       prompt: `## Quick Scan — 核心文档生成
 
-项目规模较小（quick profile），请一次性生成所有核心文档。
+当前为 quick profile（小项目自动判定 或 用户显式 --quick），一次性生成核心文档用于快速接入。
 
 ### 操作
 1. 读取项目结构和关键文件（package.json / pyproject.toml / README / 入口文件）
@@ -126,7 +145,7 @@ export function applyScanProfileSteps(stageData, profile, cwd, platformOpts) {
    - **STRUCTURE.md** — 目录树 + 模块说明
 3. 如发现子项目，注册到 \`{PROJECTS_ROOT}/\` 下
 
-每份文档头必须包含 frontmatter：\`author\` 和 \`created_at\`。
+每份文档 frontmatter 必须包含：\`author\`、\`created_at\`、\`scan_depth: quick\`（标记快速接入的浅层版本；后续深度扫描 --deep 会识别此标记并覆盖升级为完整文档）。
 
 ### ⛔ 硬约束
 - **严禁使用子代理（Agent/Task 工具）。** 所有文档在一个 turn 内完成。

package/src/run/shared.js

@@ -9,8 +9,8 @@
  *   - triggerSync 的动态 import './sync.js' → '../sync.js'（src/sync.js）
  *   - safeGit 原用顶层 require('child_process')，改静态 import execSync（更 ESM-native）
  */
-import { basename, join, resolve, dirname } from 'node:path'
-import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { basename, join, resolve, dirname, sep } from 'node:path'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { execSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 
@@ -104,6 +104,156 @@ export function resolveSpecDir(cwd, opts = {}) {
   return join(resolve(cwd), '.sillyspec')
 }
 
+/**
+ * 枚举 cwd 祖先链（含自身）上所有 .sillyspec 目录的绝对路径，上界 = git root。
+ *
+ * 返回顺序：从 cwd 最近开始向上到 git root（含两端命中项）。单实例项目任意子目录恒返回 [自身]。
+ *
+ * 上界 = git root（monorepo 天然边界）。必须有限上界：一路数到文件系统根会撞 home 等
+ * 无关祖先的孤立 .sillyspec（home 下任何项目都被误报多实例）。非 git 仓库：不向上数，
+ * 只看 cwd 自身（≤1，永不误报）。
+ *
+ * 被 countAncestorSpecDirs（漂移提醒 warn）与 locateQuickSessionGuard（quick 漂移 fail-fast
+ * 守卫，坑 quick-cwd-drift-splits-specdir）共用 —— 单一真相源，避免两处各自重写祖先枚举漂移。
+ */
+export function ancestorSpecDirs(cwd) {
+  const resolved = resolve(cwd)
+  // 上界 = git root。但 linked worktree 内 --show-toplevel 返回 worktree 根(非主仓根),
+  // 祖先链到不了主仓 .sillyspec → 漂移提醒/quick 守卫全哑(坑 worktree-execute-spec-drift)。
+  // 复刻 worktree.js _resolveMainRepoRoot:--git-common-dir 的 dirname 才是主仓根,取更靠上者作 ceiling。
+  // (git 可能返回相对路径,须 resolve(cwd, commonDir) 绝对化,否则相对 process.cwd 误解析。)
+  const topLevel = safeGit(resolved, ['rev-parse', '--show-toplevel']).value
+  let ceiling = topLevel ? resolve(topLevel) : null
+  const commonDir = safeGit(resolved, ['rev-parse', '--git-common-dir']).value
+  if (commonDir) {
+    const absCommonDir = resolve(resolved, commonDir)
+    if (existsSync(absCommonDir) && statSync(absCommonDir).isDirectory()) {
+      const mainRoot = dirname(absCommonDir)
+      // 主仓根是 worktree 根的祖先时取它(更靠上);monorepo/单仓两者相等不替换,行为不变
+      if (!ceiling || resolve(ceiling).startsWith(resolve(mainRoot) + sep)) ceiling = mainRoot
+    }
+  }
+  const dirs = []
+  let dir = resolved
+  while (true) {
+    if (existsSync(join(dir, '.sillyspec'))) dirs.push(join(dir, '.sillyspec'))
+    if (!ceiling || resolve(dir) === resolve(ceiling)) break
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return dirs
+}
+
+/**
+ * 统计 cwd 祖先链上有多少个 .sillyspec 目录（= ancestorSpecDirs(cwd).length）。
+ *
+ * ≥2 个 = monorepo 多实例（子项目独立 .sillyspec + 根 .sillyspec 并存），resolveSpecDir 命中的
+ * 「最近」实例未必是用户意图的项目（如 cd 进被独立 scan 的子项目跑测试后忘回根）→ 漂移风险。
+ * 单实例项目在任意子目录工作恒返回 1，不误报。
+ */
+export function countAncestorSpecDirs(cwd) {
+  return ancestorSpecDirs(cwd).length
+}
+
+/**
+ * 在 cwd 祖先链的各 specBase 中查找 quick 会话 guard.json（坑 quick-cwd-drift-splits-specdir）。
+ *
+ * sessionId（quick-<uuid8>）全局唯一，但 guard.json 按 specBase 分散落盘
+ * （<specBase>/.runtime/quick-sessions/<sessionId>/guard.json）。cd 漂移到子项目后，当前 specBase
+ * 下读不到本 session 的 guard，但祖先链别处的 specBase（创建 session 的根）仍有它 → 据此定位
+ * session 真正归属，供 detectQuickSessionDrift 的 fail-fast 守卫判断。
+ *
+ * 遍历顺序 = ancestorSpecDirs（cwd 最近 → git root），返回第一个命中。
+ *
+ * @param {string} cwd
+ * @param {string} sessionId - quick-<uuid8>
+ * @returns {{ specBase: string, guard: object } | null}
+ */
+export function locateQuickSessionGuard(cwd, sessionId) {
+  if (!sessionId) return null
+  for (const specBase of ancestorSpecDirs(cwd)) {
+    const guardFile = join(specBase, '.runtime', 'quick-sessions', sessionId, 'guard.json')
+    if (existsSync(guardFile)) {
+      try {
+        const guard = JSON.parse(readFileSync(guardFile, 'utf8'))
+        return { specBase, guard }
+      } catch {
+        // guard.json 损坏：当作不存在，继续找下一个（不阻断主流程）
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * 检测 quick 会话是否跨 specDir 漂移（坑 quick-cwd-drift-splits-specdir）。
+ *
+ * quick 被 validateChangeExists 的 sessionId 豁免（quick-<8hex> 不在 changes/ 下），故 quick
+ * 漂移除 countAncestorSpecDirs 的 warn 外无硬守卫 → 无声分裂（progress/artifact/QUICKLOG 落
+ * 子项目、根 session 停滞）。本函数补这个口：
+ *   - 当前 specBase 已有本 session guard → null（同一 specDir，无漂移）
+ *   - 当前 specBase 没有，但祖先链别处有同 sessionId guard → 判漂移，返回引导信息供调用方 fail-fast
+ *   - 别处也没有 → null（真·新会话首次启动，guard 尚未建，放行 —— 不误伤子项目主动启新 quick）
+ *
+ * 风格仿 validateChangeExists：null = 通过，对象 = 失败（含 message）。
+ *
+ * @param {string} cwd
+ * @param {string} currentSpecBase - 当前命中的 specBase
+ * @param {string} sessionId - quick-<uuid8>
+ * @returns {{ realSpecBase: string, message: string } | null}
+ */
+export function detectQuickSessionDrift(cwd, currentSpecBase, sessionId) {
+  if (!sessionId || !currentSpecBase) return null
+  // 当前 specBase 已有本 session guard → 同一 specDir，无漂移
+  const currentGuard = join(currentSpecBase, '.runtime', 'quick-sessions', sessionId, 'guard.json')
+  if (existsSync(currentGuard)) return null
+  // 当前没有 → 看祖先链别处有没有同 sessionId 的 guard
+  const located = locateQuickSessionGuard(cwd, sessionId)
+  if (!located) return null // 别处也没有 = 真·新会话首次启动，放行
+  return {
+    realSpecBase: located.specBase,
+    message: `quick 会话 "${sessionId}" 创建于 ${located.specBase}，当前 cwd 解析到 ${currentSpecBase}（跨 specDir 漂移）。` +
+      `继续会把 progress/artifact/QUICKLOG 写到错误的 spec，与原会话分裂。` +
+      `排查：① cd 回 ${dirname(located.specBase)}（原 spec 所属项目根）再跑；② 或显式 --spec-dir ${located.specBase} 指定原 spec。`,
+  }
+}
+
+/**
+ * 检测 specBase 是否命中 worktree 内 checkout 出来的 .sillyspec 副本（坑 worktree-execute-spec-drift）。
+ *
+ * worktree 根 = <mainRepo>/.sillyspec/.runtime/worktrees/<changeName>/（worktree.js WORKTREES_REL）。
+ * worktree 是主仓完整 checkout,若 .sillyspec/changes/ 被跟踪 → 副本里 change 目录真实存在,
+ * validateChangeExists 被骗放行 → 进度/产出写进副本,与主仓 .sillyspec 分裂(副本随工作树清理丢失)。
+ *
+ * 判据:specBase 路径含 `.sillyspec/.runtime/worktrees/<seg>/.sillyspec`。主仓 specBase=<mainRepo>/.sillyspec
+ * 无此段 → null,零误伤。返回 null=通过;对象=漂移(含 mainSpecBase/changeName/message),风格仿
+ * validateChangeExists。覆盖 plan/execute/verify/archive(同 Set)——都要求 change 已存在、都会被副本骗过。
+ * 平台模式/--spec-dir 已明确指定,由调用方跳过。
+ */
+export function detectWorktreeSpecDrift(specBase) {
+  if (!specBase) return null
+  const seg = resolve(specBase).split(sep)
+  // specBase 恒以 .sillyspec 结尾(command.js specBase=join(cwd,'.sillyspec'))。worktree 副本形如
+  // <mainRepo>/.sillyspec/.runtime/worktrees/<change>/.sillyspec —— 尾段也须是 .sillyspec,
+  // 否则 worktree 根目录本身(<.../worktrees/<change>)会被误判(它不是 spec,不会作 specBase 传入)。
+  if (seg[seg.length - 1] !== '.sillyspec') return null
+  for (let i = 0; i + 3 < seg.length; i++) {
+    if (seg[i] === '.sillyspec' && seg[i + 1] === '.runtime' && seg[i + 2] === 'worktrees') {
+      const changeName = seg[i + 3]
+      const mainSpec = seg.slice(0, i + 1).join(sep) // <mainRepo>/.sillyspec
+      return {
+        changeName,
+        mainSpecBase: mainSpec,
+        message: `当前 spec 命中 worktree 副本(${specBase})——这是 ${changeName} 隔离工作树内 checkout 出来的 .sillyspec,不是主仓 spec。\n` +
+          `   在此跑 plan/execute/verify/archive 会把进度与产出写到副本,与主仓 .sillyspec 分裂(副本随工作树清理而丢失)。\n` +
+          `   排查:① cd 回 ${dirname(mainSpec)}(主仓根)再跑;② 或 --spec-dir ${mainSpec} 显式指定主仓 spec。`,
+      }
+    }
+  }
+  return null
+}
+
 /**
  * 统一查找变更目录（与 progress.js 的变更检测逻辑一致）。
  */
@@ -128,6 +278,11 @@ export function resolveChangeDir(cwd, progress, specDir = null) {
 /**
  * 触发 sync（平台模式走自己的链路，跳过；否则 await import sync.js）。
  */
+// sync 总超时熔断：sync.js 是 best-effort 后台回传（每请求已有 10s 超时），但 sync() 可能串行多次
+// fetchJson 累积等待、阻塞 --done。给 8s 总超时，超时放弃（best-effort，失败不影响正确性，下次 --done 重试）。
+// 历史痛点：--done 在 sync 慢时体感 hang，用户被迫用外部 timeout 兜底。
+const SYNC_TOTAL_TIMEOUT_MS = 8_000
+
 export async function triggerSync(cwd, changeName, platformOpts = {}) {
   // 平台模式（SillyHub）走自己的回传链路，不走 CLI 内置 sync
   if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return
@@ -135,7 +290,15 @@ export async function triggerSync(cwd, changeName, platformOpts = {}) {
     if (changeName && !existsSync(join(cwd, '.sillyspec', 'changes', changeName))) return
     // shared.js 在 src/run/，sync.js 在 src/ → 退一层
     const syncMod = await import('../sync.js')
-    await syncMod.sync(changeName, cwd)
+    let timer
+    try {
+      await Promise.race([
+        syncMod.sync(changeName, cwd),
+        new Promise((resolve) => { timer = setTimeout(resolve, SYNC_TOTAL_TIMEOUT_MS) }),
+      ])
+    } finally {
+      clearTimeout(timer) // sync 先完成则清掉未触发的 timer，避免泄漏
+    }
   } catch (e) {
     // sync.js 不存在或同步失败，静默跳过
     console.warn('⚠️ 同步失败:', e.message)
@@ -222,12 +385,15 @@ export function isQuickMetadata(p, linkedChanges = []) {
 
 /**
  * quick 完成审计：对比 baseline 与实际变更。
- * @returns {{ status: 'safe'|'warning'|'blocked', reasons: string[], changedFiles: string[], newFiles: string[], deletedFiles: string[], baselineHit: string[] }}
+ * @returns {{ status: 'safe'|'warning'|'blocked', reasons: string[], changedFiles: string[], newFiles: string[], deletedFiles: string[], baselineHit: string[], stagedTotal: number }}
  */
 export async function auditQuickCompletion(cwd, guard, options = {}) {
   const { baselineFiles, allowedFiles = [], allowNew = false, forceBaseline = false } = guard
   const { isConfirm } = options
-  const result = { status: 'safe', reasons: [], changedFiles: [], newFiles: [], deletedFiles: [], baselineHit: [] }
+  // stagedTotal：当前所有非 quick 元数据的未提交条目（含前序 baseline 残留）。
+  // 与 changedFiles（扣 baseline 后的本轮新增）区分，供审计文案同时展示「本轮新增 vs 累计暂存」，
+  // 避免叠加 quick 会话时把前序会话未提交文件误读为「本会话只动了 N 个」。
+  const result = { status: 'safe', reasons: [], changedFiles: [], newFiles: [], deletedFiles: [], baselineHit: [], stagedTotal: 0 }
 
   try {
     const gitStatus = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
@@ -268,6 +434,10 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
       const file = parsePorcelainPath(entry)   // 已去引号/处理 rename/归一化，修正首行丢首字符
       if (!file) continue
 
+      // 累计暂存计数：所有非 quick 元数据的未提交条目（含下方将被 baseline 跳过的前序残留）。
+      // 放在 isBaselineFile 跳过之前，确保 baseline 内文件也计入「累计暂存」。
+      if (!isQuickMetadata(file, guard.linkedChanges)) result.stagedTotal++
+
       // 预存脏文件：step1 baseline 已记录，非本次 quick 产生，跳过审计（含折叠目录前缀匹配）
       if (isBaselineFile(file)) continue
 

package/src/run/stage.js

@@ -22,7 +22,7 @@ import { writeAtomicSync } from '../fs-atomic.js'
 import { resolveSpecDir, resolveChangeDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps } from './shared.js'
 import { computeScanProfile, applyScanProfileSteps, executeScanPreflight, executeScanPostcheck } from './scan-profile.js'
 import { outputStep } from './prompt.js'
-import { allocateQuicklogEntry } from '../quicklog.js'
+import { allocateQuicklogEntry, deriveTitleFromLinkedChange } from '../quicklog.js'
 import { checkTransition } from '../stage-contract.js'
 
 export async function runStage(pm, progress, stageName, cwd, changeName, skipApproval = false, platformOpts = {}, quickOpts = {}) {
@@ -239,13 +239,23 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         const linkedChanges = Array.isArray(quickOpts?.linkedChanges) ? quickOpts.linkedChanges : []
         // CLI 接管：分配 ql-ID + 写 QUICKLOG「进行中」条目 + 关联 tasks.md（持锁、当天唯一）
         const gitUser = safeGit(cwd, ['config', 'user.name']).value || 'unknown'
+        // 标题回退：启动 quick 不带 --input 时，从关联变更的 proposal/design 提取语义标题，
+        // 避免 QUICKLOG/tasks.md 落 (quick 任务) 占位（deriveTitleFromLinkedChange 读不到则空→sanitizeDesc 回退占位）。
+        let quickDesc = quickOpts?.taskDescription || ''
+        if (!quickDesc && linkedChanges.length > 0) {
+          quickDesc = deriveTitleFromLinkedChange(specBase, linkedChanges[0])
+        }
         const { qlId } = await allocateQuicklogEntry(specBase, gitUser, {
-          description: quickOpts?.taskDescription || '',
+          description: quickDesc,
           linkedChanges,
           allowedFiles,
         })
         progress.quickGuard = {
           sessionId: changeName,
+          // 锚定创建时的 specBase（坑 quick-cwd-drift-splits-specdir）：sessionId 全局复用但
+          // guard 按 specDir 落盘，记下归属让漂移可自证（detectQuickSessionDrift 靠目录定位即可，
+          // 此字段供诊断/未来一致性校验）。
+          specDir: specBase,
           name_zh: '快速任务守卫',
           baselineCommit: safeGit(cwd, ['rev-parse', 'HEAD']).value,
           baselineFiles,