sillyspec 3.26.14 → 3.27.1

package/src/run/gates.js

@@ -19,8 +19,10 @@
  *
  * 不搬：ensureDepsFreshness（execute 入口 deps 自检，调用方 runStage 非 completeStep，归属未来 execute-handler）
  */
-import { basename, join } from 'node:path'
-import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, writeFileSync } from 'node:fs'
+import { basename, join, relative, dirname } from 'node:path'
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs'
+import { writeAtomicSync } from '../fs-atomic.js'
 import { triggerSync, resolveChangeDir, resolveRuntimeRoot } from './shared.js'
 import { runValidators } from '../stage-contract.js'
 import { handleScanStageCompleted, handleExecuteWorktreeCleanup } from './complete-handlers.js'
@@ -65,12 +67,55 @@ export function validateSymbolImpactReport({ reportContent, planContent }) {
   for (const id of missing) {
     errors.push(`${id} 未在 symbol-impact.md 中出现——每个 task 都要有一行结论（含「无签名级变更」的显式声明）`)
   }
+  // 防骨架直接过门（2026-08-21 agent-手工产出审计项⑤）：CLI 会代生成逐 task TODO 骨架
+  //（generateSymbolImpactSkeleton），占位未替换即拦——骨架消灭的是「从零手写/漏 task」错误面，
+  // 不是把「逐 task 结论」本身变成走过场。
+  const report = String(reportContent)
+  const todoPending = taskIds.filter(id => new RegExp(`^[-*]\\s*${id}[^\\n]*<!--TODO-->`, 'm').test(report))
+  for (const id of todoPending) {
+    errors.push(`${id} 的结论仍是骨架 <!--TODO--> 占位——替换为真实结论（无签名级变更也显式写「无」）`)
+  }
   return { ok: errors.length === 0, errors }
 }
 
+/**
+ * 生成 symbol-impact.md 逐 task TODO 骨架（2026-08-21 审计项⑤「报错即生成」）。
+ *
+ * gate 此前只报错不代填 → agent 从零手写整份报告，忘一个 task 就被拦、再补再撞。
+ * 骨架从 tasks.md 注册表生成逐 task 占位行，agent 只需逐行填结论；占位 <!--TODO-->
+ * 由 validateSymbolImpactReport 拒绝，骨架不能直接过门（防偷懒）。
+ *
+ * @param {string} tasksContent - 任务注册表（tasks.md，回退 plan.md）内容
+ * @returns {string|null} 骨架全文（LF）；注册表无 task 行 → null
+ */
+export function generateSymbolImpactSkeleton(tasksContent) {
+  const taskIds = extractTaskIdsFromRegistry(tasksContent)
+  if (taskIds.length === 0) return null
+  // tasks.md 内容指纹（token 成本优化 P2a）：中断续跑/阶段重开时若指纹一致且结论完整，
+  // 「加载上下文」步按 prompt 指引直接沿用既有报告，不重做调用点扫描（team-session-unify
+  // 实测该步 3h06min，重入重做是纯浪费）。指纹只作提示锚，gate 校验逻辑不变。
+  let fingerprint = ''
+  try {
+    fingerprint = createHash('sha256').update(String(tasksContent)).digest('hex').slice(0, 16)
+  } catch { /* 指纹失败不阻断骨架生成 */ }
+  const lines = [
+    '# 符号影响面报告',
+    '',
+    `> tasks.md 内容指纹（生成时）: ${fingerprint}——重入本步时若与当前 tasks.md 指纹一致且结论已填全，直接沿用不重做扫描。`,
+    '> 骨架由 CLI 生成（`sillyspec symbol-impact --change <变更名>`，gate 失败时也会自动落一份）。',
+    '> 逐行把 `<!--TODO-->` 替换为真实结论：涉及签名级变更（构造函数参数/接口/DTO/方法签名增删改）',
+    '> 写变更类型 + 受影响调用点 + 是否在任务范围内；无签名级变更也要显式写「无签名级变更」。',
+    '> **gate 拒绝仍含 <!--TODO--> 的行**——骨架不能直接过门。',
+    '',
+  ]
+  for (const id of taskIds) lines.push(`- ${id}: <!--TODO-->`)
+  return lines.join('\n') + '\n'
+}
+
 /**
  * 符号影响面报告硬门：execute「加载上下文」步 --done 时校验 symbol-impact.md 落盘 + task 覆盖度。
- * fail-closed：不通过 → 当前步标 blocked + exit 1（进度不推进）。非目标步骤/阶段直接放行。
+ * fail-closed：不通过 → exit 1（进度不推进；步骤状态保持 pending，无 steps 句柄不标 blocked）。
+ * 非目标步骤/阶段直接放行。
  */
 export async function enforceSymbolImpactGate(stageName, changeName, currentStepName, specBase) {
   if (stageName !== 'execute') return
@@ -88,7 +133,19 @@ export async function enforceSymbolImpactGate(stageName, changeName, currentStep
   console.error(`   「加载上下文」步的符号影响面检查报告未落盘或不完整：`)
   console.error(`   期望路径：${reportPath}`)
   for (const e of result.errors) console.error(`   • ${e}`)
-  console.error('   修复：按「加载上下文」步操作 11 完成符号影响面扫描，逐 task 写结论（无签名级变更也要显式写「无」），落盘后重跑 execute --done。')
+  // 报错即生成（2026-08-21 审计项⑤）：报告缺失时自动落一份逐 task TODO 骨架，agent 从
+  // 「从零手写整份」变「逐行填结论」；TODO 占位由 validate 拒绝，骨架不能直接过门。
+  let skeletonNote = ''
+  if (!existsSync(reportPath)) {
+    const skeleton = generateSymbolImpactSkeleton(tasksContent)
+    if (skeleton) {
+      try {
+        writeAtomicSync(reportPath, skeleton)
+        skeletonNote = `\n   📄 已代生成逐 task 骨架：${reportPath}（逐行替换 <!--TODO--> 为结论，无签名级变更也显式写「无」）`
+      } catch { /* 写失败只影响提示，不掩盖原始错误 */ }
+    }
+  }
+  console.error(`   修复：按「加载上下文」步操作 11 完成符号影响面扫描，逐 task 写结论后重跑 execute --done。${skeletonNote}`)
   process.exit(1)
 }
 
@@ -195,7 +252,7 @@ export async function enforceAlignExecuteReviewGate({ cwd, changeName, specBase,
       }
       const searchDirs = [effectiveSpecBase, reviewChangeDir, cwd].filter(Boolean)
       const reviewResult = validateStageReview({ stage: 'execute', reviewType: 'acceptance', runtimeRoot, reviewRunId, searchDirs })
-      printStageReviewResult(reviewResult, { stage: 'execute', reviewRunId, runtimeRoot })
+      printStageReviewResult(reviewResult, { stage: 'execute', reviewRunId, runtimeRoot, changeName })
       if (!reviewResult.ok) return true // printStageReviewResult 已给明细，不再重复列
     }
   } catch (e) {
@@ -240,9 +297,10 @@ export async function enforceAlignExecuteReviewGate({ cwd, changeName, specBase,
 /**
  * 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 同范式。
- * 放行返回 true；阻断时 process.exit(1) 不返回。
+ * 放行返回 true；阻断时经 persist 回调落盘 blocked 后 exit(1)（此前只改内存不落库，
+ * progress show/doctor 看到的仍是 pending，与 docstring 承诺不符、误导诊断）。
  */
-export async function enforceDepsGate(stageName, cwd, changeName, step, steps, currentIdx, specBase, platformOpts) {
+export async function enforceDepsGate(stageName, cwd, changeName, step, steps, currentIdx, specBase, platformOpts, persist) {
   if (stageName !== 'execute') return true
   let meta = null
   let wm = null
@@ -278,6 +336,7 @@ export async function enforceDepsGate(stageName, cwd, changeName, step, steps, c
     console.error('   或在 worktree 内手动安装依赖后重试。')
     if (meta?.depsError) console.error(`   上次供给错误：${meta.depsError}`)
   }
+  if (persist) { try { await persist() } catch { /* 落盘失败不吞阻断语义 */ } }
   process.exit(1)
 }
 
@@ -287,11 +346,24 @@ export async function enforceDepsGate(stageName, cwd, changeName, step, steps, c
  * 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 的 review.json，缺字段/不存在/JSON 坏 → 置 step=blocked + exit(1)，与 enforceDepsGate 同范式
+ * （阻断前经 persist 回调落盘 blocked）。
  * 未勾 task 不校验（还没做）。平台模式/无 marker/无 plan 时放行（下游 Task Review Gate 兜底）。
  */
-export async function enforceReviewJsonGate(stageName, cwd, changeName, step, steps, currentIdx, specBase, platformOpts) {
+export async function enforceReviewJsonGate(stageName, cwd, changeName, step, steps, currentIdx, specBase, platformOpts, persist) {
   if (stageName !== 'execute' || !changeName) return true
+  // head 锡点自动落盘（2026-08-21 审计项③，D-010 补对称）：跨仓 task base_commit 已在派发时
+  // CLI 落盘，head_commit 此前靠主 agent 按 prompt 手跑 rev-parse 手写（漏抄/抄错炸 review gate）。
+  // 每次 --done 时机幂等补齐（已存在不覆盖）。best-effort：失败只 warn，不阻断 --done 主流程。
+  try {
+    const { stampCrossRepoHeadCommits } = await import('../stages/execute.js')
+    const stamped = await stampCrossRepoHeadCommits({ changeName, cwd, specBase, platformOpts })
+    if (stamped && stamped.stamped > 0) {
+      console.log(`📌 已自动落盘跨仓 task head_commit 锡点：${stamped.stampedTasks.join(', ')}（幂等，此后 --done 不再重复写）`)
+    }
+  } catch (e) {
+    console.warn(`⚠️ head_commit 锡点自动落盘失败（降级留给 agent 手写）: ${e.message}`)
+  }
   const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
   const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
   const planPath = join(specBase, 'changes', changeName, 'plan.md')
@@ -340,7 +412,8 @@ export async function enforceReviewJsonGate(stageName, cwd, changeName, step, st
     console.error(`   • ${f.taskId}（${kindLabel}）: ${f.reviewPath}`)
     for (const e of f.errors) console.error(`       - ${e}`)
   }
-  console.error('   修复：补全上述 review.json 字段后重跑 execute --done。')
+  console.error('   修复：mechanics 字段（base/head/changedFiles/schemaVersion）缺错可跑 sillyspec backfill-reviews --change ' + changeName + ' --adopt 一键代填（verdict 保留）；verdict/证据缺失需人工补全后重跑 execute --done。')
+  if (persist) { try { await persist() } catch { /* 落盘失败不吞阻断语义 */ } }
   process.exit(1)
 }
 
@@ -428,6 +501,14 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
       console.error('   请修复失败的测试并更新 verify-result.md 后重新完成此步骤。')
       return await rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx, cwd, changeName, platformOpts)
     }
+    // lint 对账（2026-08-21 审查 CLI-1）：test 侧"自报告 PASS 但实测失败→阻断"已闭环，
+    // lint 侧此前纯口头——CLI 亲自执行 commands.lint，advisory 起步（失败打印不阻断，观察期后升级）
+    const { runVerifyLintCheck, printVerifyLintCheck } = await import('../verify-postcheck.js')
+    const lintCheck = runVerifyLintCheck({ cwd, specBase })
+    if (lintCheck.status !== 'skipped') {
+      console.log(`\n⏳ Verify lint 对账：CLI 亲自执行 local.yaml 的 commands.lint…`)
+    }
+    printVerifyLintCheck(lintCheck)
     // 契约 parity 对账：扫前端 API 调用 vs execute 提取的 provider endpoint artifact。
     // 接线自 contract-matrix pipeline（verifyApiParity 的 CLI 入口）。
     const { runVerifyParityCheck, printVerifyParityCheck } = await import('../verify-postcheck.js')
@@ -462,6 +543,31 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
         }
       }
     }
+    // ── verify 服务进程回收（坑 verify-service-process-leak，2026-08-21 实证：真实启动验证
+    // 起的 uvicorn 漏挂一天多）。verify prompt 要求长驻服务 PID 登记 .runtime/verify-services.pids，
+    // 此处收尾逐个 kill + 清文件。best-effort：ESRCH（已退出）静默，kill 失败 warn 不阻断 verify。
+    try {
+      const servicesPath = join(resolveRuntimeRoot(platformOpts, specBase), 'verify-services.pids')
+      if (existsSync(servicesPath)) {
+        const pids = readFileSync(servicesPath, 'utf8').split('\n').map(l => l.trim()).filter(l => /^\d+$/.test(l))
+        const reaped = []; const failed = []
+        for (const pid of pids) {
+          try { process.kill(parseInt(pid, 10), 'SIGTERM'); reaped.push(pid) }
+          catch (e) { if (e.code !== 'ESRCH') failed.push(`${pid}(${e.code || e.message})`) }
+        }
+        try { unlinkSync(servicesPath) } catch {}
+        if (reaped.length > 0) console.log(`🧹 verify 服务进程已回收 ${reaped.length} 个（PID: ${reaped.join(', ')}）`)
+        // CLI 回执（坑 verify-literal-evidence-mismatch）：回收即真实启动的结构化证据——
+        // checkIntegrationEvidence（stage-contract）读回执注入匹配，agent 措辞差异不再误拦
+        try {
+          writeFileSync(join(dirname(servicesPath), 'verify-services.receipt.json'), JSON.stringify({
+            change: changeName || null, reapedPidCount: reaped.length, reapedAt: new Date().toISOString(),
+          }, null, 2) + '\n')
+        } catch {}
+        if (failed.length > 0) console.warn(`⚠️ 服务进程回收失败 ${failed.length} 个：${failed.join(', ')} — 手动处理：taskkill /PID <pid> /F（Windows）/ kill -9 <pid>`)
+      }
+    } catch (e) { console.warn(`⚠️ verify 服务进程回收异常（不阻断）: ${e.message}`) }
+
     console.log('\n✅ 验证通过，下一步：sillyspec run archive')
   }
 
@@ -523,7 +629,7 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
           reviewRunId = generateStageReviewRunId()
           try {
             mkdirSync(runtimeRoot, { recursive: true })
-            writeFileSync(stageReviewMarkerPath(runtimeRoot, stageName, changeName), reviewRunId + '\n')
+            writeAtomicSync(stageReviewMarkerPath(runtimeRoot, stageName, changeName), reviewRunId + '\n')
           } catch {}
         }
         const reviewType = stageName === 'brainstorm' ? 'design'
@@ -531,7 +637,7 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
           : 'acceptance'
         const searchDirs = [effectiveSpecBase, reviewChangeDir, cwd].filter(Boolean)
         const reviewResult = validateStageReview({ stage: stageName, reviewType, runtimeRoot, reviewRunId, searchDirs })
-        printStageReviewResult(reviewResult, { stage: stageName, reviewRunId, runtimeRoot })
+        printStageReviewResult(reviewResult, { stage: stageName, reviewRunId, runtimeRoot, changeName })
         if (!reviewResult.ok) {
           return await rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx, cwd, changeName, platformOpts)
         }
@@ -543,6 +649,26 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     }
   }
 
+  // ── module-impact pending 死信 execute 收尾提示（坑 module-impact-debt-late-warn，
+  // 2026-08-22 实证：死信门在 verify 才硬拦，文档债拖到 verify 末尾才暴露、上次也拦）。
+  // execute --done 即 advisory 提示（不阻断 execute——execute 期间可能仍在迭代模块文档；
+  // verify 的硬拦不变），让 agent 当场清债而非攒到 verify 撞门。
+  if (stageName === 'execute') {
+    try {
+      const execChangeDir = resolveChangeDir(cwd, progress, platformOpts?.specRoot)
+      const execImpactPath = execChangeDir ? join(execChangeDir, 'module-impact.md') : null
+      if (execImpactPath && existsSync(execImpactPath)) {
+        const { extractPendingDocSyncRows } = await import('./complete-handlers.js')
+        const execPendingRows = extractPendingDocSyncRows(readFileSync(execImpactPath, 'utf8'))
+        if (execPendingRows.length > 0) {
+          console.warn(`\n⚠️ module-impact.md「更新结果」表有 ${execPendingRows.length} 个 pending/待办项（文档同步债）——verify 阶段会硬拦：`)
+          for (const row of execPendingRows) console.warn(`   - ${row}`)
+          console.warn('   建议 execute 收尾就完成模块文档同步并回填 done/skipped（说明原因），别把债拖到 verify 末尾。')
+        }
+      }
+    } catch { /* 提示失败不阻断 execute */ }
+  }
+
   // ── Execute Task Review Gate：所有 task 必须有 review.json 且 verdict 通过 ──
   if (stageName === 'execute') {
     try {
@@ -587,7 +713,7 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
             // marker 在则目录在）。不 try/catch——异常直穿外层 catch 走 fail-closed 阻断
             //（gate 自身写 run 目录失败不能静默放行完成）。
             mkdirSync(join(runtimeRoot, 'execute-runs', executeRunId, 'tasks'), { recursive: true })
-            writeFileSync(runIdFile, executeRunId + '\n')
+            writeAtomicSync(runIdFile, executeRunId + '\n')
             stampExecuteRunChange(runtimeRoot, executeRunId, changeName)
           }
         }
@@ -695,7 +821,7 @@ export function validateMetadata(cwd, stageName, specBase) {
   const unique = [...new Set(missing)]
   if (unique.length > 0) {
     console.log(`\n⚠️  以下文件缺少 author 或 created_at 元数据：`)
-    unique.forEach(f => console.log(`  - ${f.replace(cwd + '/', '')}`))
+    unique.forEach(f => console.log(`  - ${relative(cwd, f) || f}`))
     console.log('请在文件头部添加 author（git 用户名）和 created_at（精确到秒）')
   }
 }
@@ -736,13 +862,14 @@ export function validateFileLocations(cwd, stageName, progress, changeName, spec
 
   if (missing.length > 0) {
     console.log(`\n⚠️  文件位置验证：以下文件未在变更目录中找到`)
-    console.log(`  变更目录：${changeDir.replace(cwd + '/', '')}/`)
+    // relative(cwd, x)：Windows 下 join() 产物是反斜杠绝对路径，正斜杠拼接的 cwd 前缀裁剪永不命中
+    console.log(`  变更目录：${relative(cwd, changeDir) || changeDir}/`)
     for (const f of missing) {
       // 检查是否写到了错误的位置
       const wrongPath = join(specBase, 'changes', 'change', effectiveChange, f)
       if (existsSync(wrongPath)) {
-        console.log(`  ❌ ${f} — 不存在，但发现了错误路径：${wrongPath.replace(cwd + '/', '')}`)
-        console.log(`     提示：应该写入 ${changeDir.replace(cwd + '/', '')}/${f}`)
+        console.log(`  ❌ ${f} — 不存在，但发现了错误路径：${relative(cwd, wrongPath) || wrongPath}`)
+        console.log(`     提示：应该写入 ${relative(cwd, changeDir) || changeDir}/${f}`)
       } else {
         console.log(`  ⬜ ${f} — 未找到（该阶段可能未产出此文件）`)
       }

package/src/run/multi-repo-context.js

@@ -79,7 +79,9 @@ export class MultiRepoContext {
       throw new Error(
         `MultiRepoContext: 以下 repo 未在 local.yaml repos: 段注册：[${unregistered.join(', ')}]。` +
         `当前已注册 repo：[${registered.join(', ')}]。` +
-        `请在 local.yaml repos: 段补注册后再启动 execute（约束② fail-closed，跨仓 apply 走错仓=数据所有权事故）。`
+        `一键注册（每个缺的 key 各跑一次，勿手编 YAML）：` +
+        unregistered.map(k => `sillyspec local register-repo ${k} <${k} 仓根路径>`).join('；') +
+        `。补注册后再启动 execute（约束② fail-closed，跨仓 apply 走错仓=数据所有权事故）。`
       );
     }
 

package/src/run/next.js

@@ -0,0 +1,128 @@
+/**
+ * next.js — `sillyspec next` 项目状态探测（吸收 continue/resume 两个 skill 的手工探测表，
+ * 2026-08-21 agent-手工产出审计第二批 G7/G8）。
+ *
+ * 两个 skill 各自维护一套「文件存在性状态机」推断表且内容重复，agent 每次手工跑
+ * ls/cat 探测再查表——纯机械探测是 CLI 的本职。本模块输出「状态描述 + 下一步命令 +
+ * 依据文件」，agent 按输出执行即可；skill 保留作兜底（CLI 不可用/输出异常时）。
+ *
+ * 纯 fs 探测（零 DB 依赖、零 token、快）：进度库的权威状态归 `sillyspec progress show`，
+ * 本命令管「没有活跃进度时从产物文件反推该干什么」。决策表（两个 skill 合并）：
+ *
+ *   1. HANDOFF.json 存在 → 交接恢复
+ *   2. 活跃变更（changes/ 非 archive）逐个推断：
+ *      无文件→补 proposal / 无 design.md→brainstorm / 无 tasks.md→brainstorm 末步 /
+ *      无 plan.md→plan / tasks.md 有未勾→execute / 全勾无 verify-result.md→verify /
+ *      有 verify-result.md→archive
+ *   3. 有 docs/<p>/scan/ 无活跃变更 → brainstorm（已扫描待开变更）
+ *   4. 有 REQUIREMENTS.md/ROADMAP.md 无变更 → brainstorm（绿地已有需求）
+ *   5. 什么都没有 → init（新项目）或 scan（棕地）
+ */
+import { existsSync, readdirSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { resolveSpecDir } from './shared.js'
+
+/**
+ * 数 tasks.md checkbox：返回 { checked, total }（无文件 → {checked:0,total:0}）
+ */
+function countTasks(tasksPath) {
+  if (!existsSync(tasksPath)) return { checked: 0, total: 0 }
+  let checked = 0
+  let total = 0
+  for (const line of readFileSync(tasksPath, 'utf8').split('\n')) {
+    const m = line.match(/^[-*]\s*\[([ xX])\]\s*task-\d+\b/)
+    if (!m) continue
+    total++
+    if (m[1] !== ' ') checked++
+  }
+  return { checked, total }
+}
+
+/**
+ * 单个活跃变更的产物推断：返回 { state, next, evidence }
+ */
+function inferChange(changeDir, name) {
+  const has = (f) => existsSync(join(changeDir, f))
+  const ev = (f) => join('.sillyspec', 'changes', name, f)
+  const t = countTasks(join(changeDir, 'tasks.md'))
+
+  if (!has('proposal.md') && !has('design.md') && !has('tasks.md') && !has('plan.md')) {
+    return { state: `${name}：变更目录为空`, next: 'sillyspec run brainstorm（完善 proposal）或清理该空目录', evidence: [ev('（无产物）')] }
+  }
+  if (!has('design.md')) {
+    return { state: `${name}：有 proposal 缺 design.md`, next: `sillyspec run brainstorm --change ${name}（推进到设计产物）`, evidence: [ev('proposal.md')] }
+  }
+  if (!has('tasks.md')) {
+    return { state: `${name}：有 design 缺 tasks.md`, next: `sillyspec run brainstorm --change ${name}（末步生成规范文件）`, evidence: [ev('design.md')] }
+  }
+  if (!has('plan.md')) {
+    return { state: `${name}：有 tasks.md 缺 plan.md`, next: `sillyspec run plan --change ${name}`, evidence: [ev('tasks.md')] }
+  }
+  if (t.total > 0 && t.checked < t.total) {
+    return {
+      state: `${name}：执行中（task ${t.checked}/${t.total}）`,
+      next: `sillyspec run execute --change ${name}`,
+      evidence: [ev('plan.md'), ev('tasks.md')],
+    }
+  }
+  if (!has('verify-result.md')) {
+    return { state: `${name}：task 全勾，待验证`, next: `sillyspec run verify --change ${name}`, evidence: [ev('tasks.md'), ev('plan.md')] }
+  }
+  return { state: `${name}：已验证，待归档`, next: `sillyspec run archive --change ${name}`, evidence: [ev('verify-result.md')] }
+}
+
+/**
+ * 探测当前项目状态与下一步命令。
+ * @param {{ cwd: string, specDir?: string|null }} opts
+ * @returns {{ state: string, next: string, evidence: string[], activeChanges: Array<{name,checked,total}> }}
+ *   activeChanges 附带各变更 task 勾选进度（供 --json 消费）；evidence 为相对 spec 根的路径
+ */
+export function detectNextStep({ cwd, specDir = null }) {
+  const specBase = resolveSpecDir(cwd, { specDir })
+  const changesRoot = join(specBase, 'changes')
+
+  // 1. HANDOFF 交接
+  for (const handoff of [join(cwd, 'HANDOFF.json'), join(specBase, 'HANDOFF.json')]) {
+    if (existsSync(handoff)) {
+      return { state: '存在 HANDOFF.json（上次会话交接）', next: '读 HANDOFF.json 后从交接点继续（sillyspec progress show 看活跃进度）', evidence: [handoff], activeChanges: [] }
+    }
+  }
+
+  // 2. 活跃变更（排除 archive）
+  let active = []
+  try {
+    active = readdirSync(changesRoot, { withFileTypes: true })
+      .filter(e => e.isDirectory() && e.name !== 'archive')
+      .map(e => e.name)
+      .sort()
+  } catch { /* 无 changes/ 目录 */ }
+  if (active.length > 0) {
+    // 多活跃时逐个推断全报告，next 取第一个（字典序最前）的；调用方输出含全部状态行
+    const inferences = active.map(name => inferChange(join(changesRoot, name), name))
+    const progress = active.map((name, i) => {
+      const t = countTasks(join(changesRoot, name, 'tasks.md'))
+      return { name, checked: t.checked, total: t.total, state: inferences[i].state }
+    })
+    return { state: inferences.map(i => i.state).join('；'), next: inferences[0].next, evidence: inferences[0].evidence, activeChanges: progress }
+  }
+
+  // 3. 已扫描无变更
+  const docsDir = join(specBase, 'docs')
+  try {
+    const scanned = readdirSync(docsDir, { withFileTypes: true })
+      .filter(e => e.isDirectory() && existsSync(join(docsDir, e.name, 'scan')))
+    if (scanned.length > 0) {
+      return { state: `已扫描（${scanned.length} 个项目文档），无活跃变更`, next: 'sillyspec run brainstorm "你的想法"', evidence: [join('.sillyspec', 'docs', scanned[0].name, 'scan')], activeChanges: [] }
+    }
+  } catch { /* 无 docs/ */ }
+
+  // 4. 绿地已有需求
+  for (const f of ['REQUIREMENTS.md', 'ROADMAP.md']) {
+    if (existsSync(join(specBase, f))) {
+      return { state: `绿地项目已有 ${f}，无活跃变更`, next: 'sillyspec run brainstorm "你的想法"', evidence: [join('.sillyspec', f)], activeChanges: [] }
+    }
+  }
+
+  // 5. 什么都没有
+  return { state: '未初始化（无 .sillyspec 产物）', next: 'sillyspec init（新项目）或 sillyspec scan（棕地项目）', evidence: [], activeChanges: [] }
+}

package/src/run/prompt.js

@@ -21,7 +21,7 @@
 import { basename, join } from 'node:path'
 import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs'
 import { stageRegistry } from '../stages/index.js'
-import { resolvePromptIncludes, resolveRuntimeRoot, safeGit, WAIT_MARKER_RE } from './shared.js'
+import { resolvePromptIncludes, resolveRuntimeRoot, safeGit, WAIT_MARKER_RE, QUICK_SID_RE } from './shared.js'
 import { renderStageContract } from '../stage-contract-spec.js'
 import { parseModuleMapSimple } from '../modules.js'
 import { REVIEW_SCHEMA_VERSION, isValidExecuteRunId } from '../task-review.js'
@@ -236,6 +236,16 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   promptText = promptText.replace(/<now-datetime>/g, nowDatetime)
   promptText = promptText.replace(/<now-timestamp>/g, nowTimestamp)
   promptText = promptText.replace(/<now-date>/g, nowDate)
+  // <now-iso-datetime>（scan frontmatter updated_at 用；与 scan-fix-headers 同款秒级格式）
+  promptText = promptText.replace(/<now-iso-datetime>/g, now.toISOString().slice(0, 19).replace('T', ' '))
+  // <git-head-short>（scan frontmatter source_commit 用；CLI 代查，agent 勿自跑 rev-parse）
+  if (promptText.includes('<git-head-short>')) {
+    let headShort = 'unknown'
+    try {
+      headShort = safeGit(cwd, ['rev-parse', '--short', 'HEAD']).value || 'unknown'
+    } catch { /* git 不可用 → unknown，scan-postcheck 失配时再核 */ }
+    promptText = promptText.replace(/<git-head-short>/g, headShort)
+  }
   // 替换 {REVIEW_SCHEMA_VERSION} 占位符（task review 示例模板用，值=CLI 当前 REVIEW_SCHEMA_VERSION 常量，
   // 避免 agent 照抄 design 目标版本与 CLI 写侧常量漂移；与 stage review 契约 renderReviewJsonContract 动态注入同源）
   if (promptText.includes('{REVIEW_SCHEMA_VERSION}')) {
@@ -500,6 +510,21 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     }
   }
 
+  // 模块卡分级表注入（token 成本优化 P0a，2026-08-22-token-cost-optimization）：execute
+  // 「加载上下文」步 {MODULE_RESOLVE_TABLE} → resolveChangeModuleCards（tasks 卡 allowed_paths
+  // × 全部 _module-map.yaml 跨层最长前缀匹配，子项目细卡优先于根层大卡）。全降级不抛
+  // （异常 → 单行说明），无 map 由渲染函数给出跳过提示——占位符恒被替换。
+  if (stageName === 'execute' && promptText.includes('{MODULE_RESOLVE_TABLE}')) {
+    try {
+      const { renderModuleResolveTable } = await import('../module-resolve.js')
+      const mrSpecBase = resolvePromptSpecBase(platformOpts, cwd)
+      const table = renderModuleResolveTable({ cwd, specBase: mrSpecBase, changeName })
+      promptText = promptText.replace(/\{MODULE_RESOLVE_TABLE\}/g, table)
+    } catch (e) {
+      promptText = promptText.replace(/\{MODULE_RESOLVE_TABLE\}/g, `[modules-resolve] 模块卡分级解析异常（${e.message}），跳过——可手跑 sillyspec modules resolve --change <变更名>`)
+    }
+  }
+
   // Execute: 注入 currentExecuteRunId（从变更专属标记文件读取）
   if (stageName === 'execute' && promptText.includes('{EXECUTE_RUN_ID}')) {
     let runId = ''
@@ -722,7 +747,15 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       // 普通本地保持相对 '.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\`**`)
+      // quick 会话（quick-<hex8>）按设计无实体变更目录（progress.js initChange 同款跳过），
+      // 纯代码 quick 根本不产 spec 文档——「所有变更文件必须写入 changes/<change>/」的硬规则
+      // 对它是误导（ql-20260821-011 实证：CLI 反复提示一个用不到的目录）。改述条件化：
+      // 仅「若本 quick 决定补文档」才落该目录，代码改动照常写源码目录。
+      if (QUICK_SID_RE.test(changeName)) {
+        console.log(`- **文件路径规则（quick 会话）：纯代码改动直接写源码目录，无目录限制。仅当本 quick 需要落 spec 文档（design/plan 等，复杂任务建议升级完整流程）时才写 \`${changeDir}/\`；QUICKLOG/tasks.md 记录由 CLI 接管，不要手建。**`)
+      } else {
+        console.log(`- **文件路径规则：所有变更文件必须写入 \`${changeDir}/\` 目录下。不要自己拼接路径，直接使用 changeDir 值。示例：\`${changeDir}/proposal.md\`**`)
+      }
     }
   }
   const changeFlag = changeName ? ` --change ${changeName}` : ''
@@ -764,6 +797,5 @@ export function applyRootPlaceholders(text, roots) {
     .replaceAll('{DOCS_ROOT}', roots.docsRoot)
     .replaceAll('{PROJECTS_ROOT}', roots.projectsRoot)
     .replaceAll('{WORKFLOWS_ROOT}', roots.workflowsRoot)
-    .replaceAll('{KNOWLEDGE_ROOT}', roots.knowledgeRoot)
-}
+    .replaceAll('{KNOWLEDGE_ROOT}', roots.knowledgeRoot)}
 

package/src/run/quick-audit.js

@@ -7,9 +7,10 @@
  * 路径修正（相对 src/run/）：
  *   - resolveQuickLinkedChanges 的 quick-recommend.js 动态 import './quick-recommend.js' → '../quick-recommend.js'
  *   - 脏文件信号改用 safeGit（带 safe.directory，Q3）；不再 import execSync
- *   - parsePorcelainPath 从 ./shared.js 重 import；checkbox 顶部 import
+ *   - parsePorcelainPath 从 ./shared.js 重 import；checkbox 改交互分支内动态 import——
+ *     本模块被 command.js 静态 import，顶部静态拉 @inquirer/prompts 会进**每条** run 命令
+ *     启动路径（实测冷加载 100-150ms），而 checkbox 仅"≥2 活跃变更 + TTY"分支用到
  */
-import { checkbox } from '@inquirer/prompts'
 import { parsePorcelainPath, safeGit } from './shared.js'
 
 /**
@@ -150,6 +151,8 @@ export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles,
   if (recommendedSet.size > 0) {
     console.log('   ⭐ = 基于脏文件/任务描述推荐，已默认勾选')
   }
+  // 动态 import：@inquirer/prompts 只在本交互分支加载，不进 run 命令通用启动路径
+  const { checkbox } = await import('@inquirer/prompts')
   const selected = await checkbox({ message: '关联变更（空格切换，回车确认）', choices })
   return selected
 }