sillyspec 3.26.4 → 3.26.6

package/src/run/complete.js

@@ -5,25 +5,30 @@
  * completion path 收尾 + single-step path）+ skipStep/waitStep/continueStep（W6 Step7b-2 续搬）。
  * 本 commit（7b-1）先搬 completeStep + 2 独占 helper（validateMetadata/validateFileLocations）。
  *
- * 安全锚：run.js 始终 barrel。completeStep 由 run.js import 回来；_completeStepForTest 被 9 个
- * run-complete-step-* characterization 测试直接 import，run.js barrel re-export（export { completeStep as
- * _completeStepForTest } 沿用 imported-binding re-export）契约保留。
+ * 安全锚：run.js 始终 barrel。completeStep 由 run/command.js 在 --done 路径调用，无测试专用导出
+ * （曾以 `_completeStepForTest` 别名 re-export 供 characterization 测试直驱动，2026-08-13 这些测试
+ * 全部迁到 CLI 子进程 `sillyspec run <stage> --done`，导出已移除——见 run.js barrel 注释）。
  *
  * 依赖（completeStep 仅用已抽叶子 + 随搬 helper，零 run.js 闭包，零动态 import）：
  *   - shared.js: triggerSync/WAIT_MARKER_RE/getStageSteps；prompt.js: outputStep；gates.js: enforceDepsGate/runStageCompletionGates
  *   - complete-handlers.js: 8 handler；stages/index.js: stageRegistry；worktree-apply.js: formatExecuteSummary
+ *   - scan-profile.js: executeScanPreflight/executeScanPostcheck/computeScanProfile（noAI 硬门）
+ *   - stages/plan-postcheck.js: executePlanPostcheck（noAI 硬门）
  *   - node: join(path) + existsSync/readdirSync/readFileSync/mkdirSync/writeFileSync/appendFileSync/statSync(fs)
  */
 import { join } from 'node:path'
 import { existsSync, readFileSync, mkdirSync, writeFileSync, appendFileSync } from 'node:fs'
 import { writeAtomicSync } from '../fs-atomic.js'
 import { withFileLock } from '../quicklog.js'
-import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions, resolveRuntimeRoot, getOrCreateMultiRepoContext } from './shared.js'
+import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions, resolveRuntimeRoot, getOrCreateMultiRepoContext, resolveChangeDir } from './shared.js'
+import { executeScanPreflight, executeScanPostcheck, computeScanProfile } from './scan-profile.js'
+import { executePlanPostcheck as runPlanPostcheckLib } from '../stages/plan-postcheck.js'
 import { outputStep } from './prompt.js'
 import { enforceDepsGate, enforceReviewJsonGate, completeStageGates, readDesignScale } from './gates.js'
 import { handleArchiveConfirmStep, handlePlanGeneratePlanStep, handleScanProjectListStep, handleWorkflowPostCheck, handleQuickStageCompletion, handleExecuteWaveArtifact } from './complete-handlers.js'
 import { formatExecuteSummary } from '../worktree-apply.js'
 import { isEndToEndTaskText } from '../change-risk-profile.js'
+import { deriveTitleFromLinkedChange } from '../quicklog.js'
 
 // validateMetadata / readDesignScale / validateFileLocations 已迁至 ./gates.js（completeStageGates
 // 共享收尾管线，消除 noAI 末步 / continueStep 完成分支绕过 gate 的 S1/S2/S3 不对称）。
@@ -59,8 +64,34 @@ export function resolveWaitingStepWithAnswer(steps, doneAnswer, nowStr) {
   return waitIdx
 }
 
+/**
+ * wait 选项单选校验（坑 wait-choice-enforcement）：定义了 waitOptions 的 requiresWait/
+ * repeatableWait 步骤，--answer 必须命中预设选项之一——防止 agent 一句话代答绕过人工
+ * 选择（方案选择类 wait 的 answer 本就该是选项本身）。开放回答型步骤（澄清追问，answer
+ * 为自由文本）在 step 定义显式声明 waitFreeAnswer: true 豁免。
+ * 校验失败打印选项清单 + exit 1（fail-loud，与 requiresWait 门同风格）。
+ *
+ * waitOptions 优先取 stepDef（运行时构建的步骤定义，与 brainstorm/plan 静态定义同源），
+ * 回退 DB step entry（--continue 路径 waiting 步骤的 waitOptions 已落盘）。
+ */
+function enforceWaitChoice(stepDef, stepEntry, answer, stageName, changeName) {
+  if (answer == null) return
+  const opts = Array.isArray(stepDef?.waitOptions) ? stepDef.waitOptions
+    : (Array.isArray(stepEntry?.waitOptions) ? stepEntry.waitOptions : null)
+  if (!opts || opts.length === 0) return
+  if (stepDef?.waitFreeAnswer === true) return
+  if (opts.includes(answer)) return
+  console.error(`❌ Step "${stepEntry?.name || '当前步骤'}" 是封闭单选 wait，--answer 必须命中预设选项之一（防 AI 代答绕过人工选择）。`)
+  console.error(`   你的 --answer: ${JSON.stringify(answer)}`)
+  console.error(`   可选值（复制其一）: ${opts.join(' / ')}`)
+  console.error(`   自由文本回答的场景，该步骤应声明 waitFreeAnswer（当前未声明）。`)
+  if (changeName) console.error(`   重试：sillyspec run ${stageName} --done --answer "<选项>" --change ${changeName}`)
+  else console.error(`   重试：sillyspec run ${stageName} --done --answer "<选项>"`)
+  process.exit(1)
+}
+
 export async function completeStep(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
-  const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, isForceBaseline = false, isAllowNew = false } = options
+  const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, isForceBaseline = false, isAllowNew = false, isAllowDelete = false } = options
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
   const stageData = progress.stages[stageName]
 
@@ -117,6 +148,10 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   const defStepsForCurrent = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
   const currentStepDef = defStepsForCurrent?.[currentIdx] || {}
   const currentStep = steps[currentIdx]
+  // --done --answer 解 waiting 的路径同样过单选校验（与下方 requiresWait doneAnswer 分支同规则）
+  if (_resolvedWaitIdx !== -1 && _doneAnswer) {
+    enforceWaitChoice(currentStepDef, currentStep, _doneAnswer, stageName, changeName)
+  }
   if (currentStepDef.requiresWait === true && !currentStep.waitAnswer) {
     // 检查 --done 是否带了 --answer：如果是，自动补全 waitAnswer 状态，一步完成
     const doneAnswer = typeof options !== 'undefined' && options.doneAnswer ? options.doneAnswer : null
@@ -133,6 +168,7 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       currentStep.waitReason = currentStepDef.waitReason || '等待用户输入'
       console.log(`⚠️  Step "${currentStep.name}" 的确认（${currentStepDef.waitReason}）已在前置步骤完成，自动跳过。`)
     } else if (doneAnswer) {
+      enforceWaitChoice(currentStepDef, currentStep, doneAnswer, stageName, changeName)
       currentStep.status = 'waiting'
       currentStep.waitAnswer = doneAnswer
       currentStep.waitReason = currentStepDef.waitReason || '等待用户输入'
@@ -156,6 +192,27 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   // 提前到每次 --done 校验（而非等 Task Review Gate 在整阶段收尾才暴露，迫使用户事后批量补）。
   await enforceReviewJsonGate(stageName, cwd, changeName, steps[currentIdx], steps, currentIdx, specBase, platformOpts)
 
+  // ── noAI 步骤硬门（坑 noai-done-bypass）：noAI 步骤的确定性校验不可被 --done 绕过 ──
+  // 正常路径 agent 跑 `run <stage>` 推进到 noAI step 时，runStage 自动执行 _cliAction
+  // （stage.js noAI 分支，不写 step output）；若 agent 对 noAI step 直接 --done，此前
+  // completeStep 无 noAI 检测直接标 completed，executePlanPostcheck 等 CLI 确定性校验被
+  // 静默跳过（实证：multi-agent-platform 2026-08-13-spec-sync-visibility tasks/ 从未
+  // 生成但 plan 阶段 completed——step4 output 为 agent 口吻 178 字符而非 CLI 自动路径的
+  // 空 output）。修复：--done 落到 noAI step 时同样执行 _cliAction，校验 throw →
+  // completeStep 不推进（step 保持 pending）。分支对齐 stage.js 的 noAI 自动执行。
+  const _isNoAIStep = currentStepDef.noAI === true || currentStep?.noAI === true
+  if (_isNoAIStep) {
+    const _cliAction = currentStepDef._cliAction || currentStep?._cliAction
+    console.log(`⚙️ Step ${currentIdx + 1}/${steps.length}: ${steps[currentIdx].name}（noAI，--done 路径执行 CLI 校验）`)
+    if (_cliAction === 'scanPreflight') {
+      await executeScanPreflight(cwd, platformOpts, stageData.scanProfile || computeScanProfile(cwd, platformOpts))
+    } else if (_cliAction === 'scanPostcheck') {
+      await executeScanPostcheck(cwd, platformOpts, stageData.scanProfile || computeScanProfile(cwd, platformOpts))
+    } else if (_cliAction === 'planPostcheck') {
+      await runPlanPostcheckLib({ cwd, specRoot: platformOpts?.specRoot, resolveChangeDir, progress })
+    }
+  }
+
   steps[currentIdx].status = 'completed'
   steps[currentIdx].completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
   if (outputText) {
@@ -248,7 +305,7 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       return { stageCompleted: false, currentIdx, nextPendingIdx: -1 }
     }
     // quick 收尾（W6 Step6b 抽至 complete-handlers.js handleQuickStageCompletion）
-    await handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, platformOpts, pm })
+    await handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, isAllowDelete, platformOpts, pm })
 
     // ── reopen --done 回填（坑 brainstorm-reopen-step-state-desync）──
     // nextPendingIdx === -1 且无 waiting，说明要进阶段完成分支。此时若存在 stale 步骤
@@ -299,6 +356,16 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     const _stageGatesResult = await completeStageGates({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps, currentIdx, outputText, ctx: _completeCtx })
     if (_stageGatesResult) return _stageGatesResult
 
+    // 完整流程 change title 刷新：proposal/design 落盘后（brainstorm/plan 完成），从 proposal 首个 #
+    // 标题刷新 changes.title（人类可读中文标题，用户可随时刷新）。quick-<hex> 无 proposal 目录 →
+    // deriveTitleFromLinkedChange 返回 '' 不刷新（quick 走 handleQuickStageCompletion 的 extractTitleFromResult）。
+    if (changeName && !/^quick-[0-9a-f]{8}$/.test(changeName)) {
+      try {
+        const refinedTitle = deriveTitleFromLinkedChange(specBase, changeName)
+        if (refinedTitle) pm.updateChangeMeta(cwd, changeName, { title: refinedTitle })
+      } catch { /* title 刷新失败不阻断完成 */ }
+    }
+
     // gate 全过：persist completed（task-01 移后）。此处到 _write 之间若崩，DB 仍 in-progress（内存已 completed 但未落盘），下次进 CLI 读 DB 即 in-progress，不产生"假 completed"。
     pm._write(cwd, progress, changeName)
     triggerSync(cwd, changeName, platformOpts)
@@ -677,6 +744,7 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
   const prevOutput = currentStep.output || ''
   const waitRound = (currentStep.waitRound || 0) + 1
   currentStep.waitRound = waitRound
+  enforceWaitChoice(currentStepDef, currentStep, answer, stageName, changeName)
   currentStep.waitAnswer = answer
   currentStep.waitAnswers = Array.isArray(currentStep.waitAnswers) ? currentStep.waitAnswers : []
   currentStep.waitAnswers.push({
@@ -764,6 +832,13 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
     }
     const _stageGatesResult = await completeStageGates({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps: stageData.steps, currentIdx, outputText: null, ctx: _contCtx })
     if (_stageGatesResult) return _stageGatesResult
+    // 完整流程 change title 刷新（同 completeStep 完成分支，wait 解除后阶段完成也刷新）。
+    if (changeName && !/^quick-[0-9a-f]{8}$/.test(changeName)) {
+      try {
+        const refinedTitle = deriveTitleFromLinkedChange(specBase, changeName)
+        if (refinedTitle) pm.updateChangeMeta(cwd, changeName, { title: refinedTitle })
+      } catch { /* title 刷新失败不阻断完成 */ }
+    }
     // gate 全过：persist completed（task-03 移后；此处无 triggerSync）。
     pm._write(cwd, progress, changeName)
     console.log(`\n✅ ${stageName} 阶段已完成（${stageData.steps.length}/${stageData.steps.length} 步）`)

package/src/run/gates.js

@@ -309,7 +309,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 })
+        printStageReviewResult(reviewResult, { stage: stageName, reviewRunId, runtimeRoot })
         if (!reviewResult.ok) {
           return await rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx, cwd, changeName, platformOpts)
         }

package/src/run/prompt.js

@@ -7,9 +7,10 @@
  * loadModuleContextIndex/buildModuleContextInjection/parseModuleMapSimple
  * （_module-map.yaml 模块上下文匹配注入，仅 outputStep 用）。
  *
- * 安全锚：run.js 始终 barrel。outputStep + applyRootPlaceholders 由 run.js import 回来；
- * _outputStepForTest（output-step-render 测试）+ applyRootPlaceholders（prompt-placeholders
- * 测试）被 test 直接 import，run.js barrel re-export 契约保留。
+ * 安全锚：run.js 始终 barrel。applyRootPlaceholders 由 run.js import 回来；
+ * outputStep（output-step-render / archive-task-completion-injection 测试）+ applyRootPlaceholders
+ * （prompt-placeholders 测试）被 test 直接 import 本模块（outputStep 不经 barrel，2026-08-13 起 test
+ * 直 import 源模块，`_outputStepForTest` 别名已移除）。
  *
  * 路径修正（相对 src/run/）：
  *   - stageRegistry 从 '../stages/index.js'；resolvePromptIncludes/safeGit/WAIT_MARKER_RE 从 './shared.js'
@@ -33,18 +34,18 @@ import { REVIEW_SCHEMA_VERSION } from '../task-review.js'
  * @param {string} projectName - 项目名
  * @returns {object|null} 解析后的模块索引，null 表示无索引
  */
-function loadModuleContextIndex(specBase, projectName) {
+export function loadModuleContextIndex(specBase, projectName) {
   try {
     const mapPath = join(specBase, 'docs', projectName, 'modules', '_module-map.yaml')
     if (!existsSync(mapPath)) return null
     const content = readFileSync(mapPath, 'utf8')
-    // schema_version 校验（advisory）：modules.js 写 schema_version: 2；缺失或非 2 → warn，
-    // 提示 v1/v2 格式混用风险（旧格式字段解析会静默错位）。正常生成的文件不触发。
+    // schema_version 校验：仅缺失 schema_version（真 malformed，parseModuleMapSimple 必错位）时 warn；
+    // schema_version=1（旧格式）静默——读端 buildModuleContextInjection 已 v1/v2 双兼容
+    // （data.paths || data.core_files），v1 解析正常。原 v1 warn 是过激噪声（每步渲染 prompt 刷屏）。
+    // v1→v2 根因在 scan prompt 模板仍写 schema_version:1，升级 scan.js 是单独改动（见 troubleshooting）。
     const sv = content.match(/^schema_version:\s*(\d+)/m)
     if (!sv) {
       console.warn(`⚠️  _module-map.yaml 缺少 schema_version 声明（期望 2），模块解析可能错位：${mapPath}（跑 \`sillyspec modules rebuild\` 升级到 schema_version: 2 可消除此警告）`)
-    } else if (sv[1] !== '2') {
-      console.warn(`⚠️  _module-map.yaml schema_version=${sv[1]}（期望 2），可能为旧格式，模块解析可能错位：${mapPath}（跑 \`sillyspec modules rebuild\` 升级到 schema_version: 2 可消除此警告）`)
     }
     return parseModuleMapSimple(content)
   } catch {
@@ -116,6 +117,19 @@ function buildModuleContextInjection(taskDescription, moduleIndex, specBase, pro
 
 // parseModuleMapSimple 复用 modules.js 的 canonical 实现（合并历史 copy-paste 副本，2026-08-07；
 // 无循环依赖：modules.js 仅 import fs/path/db.js，prompt.js → modules.js 单向）。
+/**
+ * 提示词路径根的单一解析：specRoot(平台) > specDriftAnchor(worktree 漂移锚定主仓) > cwd/.sillyspec(本地)。
+ * 治 execute review.json 提示路径写 worktree 副本、--done 校验读主仓的分裂（坑 execute-prompt-spec-drift）：
+ * CLI 自动锚定主仓 spec（command.js detectWorktreeSpecDrift → platformOpts.specDriftAnchor）只修正了
+ * resolveRuntimeRoot 的 runtime 落点，outputStep 拼 {SPEC_ROOT}/.runtime/execute-runs/… 若仍用 cwd
+ * （worktree）→ 提示的 review.json 路径落到 worktree 副本 .sillyspec，而 gate/checkbox 从主仓
+ * resolveRuntimeRoot 读 → agent 落盘错位，marker 漂移改用他 run / task 未勾。specDriftAnchor 非空即主仓
+ * specBase，优先于 cwd。平台模式 specRoot 优先语义不变。
+ */
+export function resolvePromptSpecBase(platformOpts, cwd) {
+  return platformOpts?.specRoot || platformOpts?.specDriftAnchor || join(cwd, '.sillyspec')
+}
+
 /**
  * 输出当前步骤的 prompt
  */
@@ -236,7 +250,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   // 替换 <quicklog-id> 占位符（quick 阶段：从 session guard.json 读 CLI 分配的 ql-ID，
   // 供 agent 在模块文档变更索引等处引用）
   if (promptText.includes('<quicklog-id>')) {
-    const specBaseQl = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    const specBaseQl = resolvePromptSpecBase(platformOpts, cwd)
     let qlIdVal = ''
     try {
       const sessionGuardFile = join(specBaseQl, '.runtime', 'quick-sessions', changeName, 'guard.json')
@@ -248,7 +262,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   }
   // 替换 <linked-changes> 占位符（quick 阶段：从 .runtime/quick-sessions/<sessionId>/guard.json 读关联变更）
   if (promptText.includes('<linked-changes>')) {
-    const specBaseLc = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    const specBaseLc = resolvePromptSpecBase(platformOpts, cwd)
     let linkedChanges = []
     try {
       // D-002：guard 按 session 存。changeName == quick-<uuid8>（见 runStage 参数解析）。回退读旧单文件（兼容 task-03 前）
@@ -266,7 +280,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   if (platformOpts?.specRoot || platformOpts?.runtimeRoot) {
     const projectName = dbProjectName || basename(cwd)
     // platformOpts.specRoot 现在指向 specDir 本身（可能是 cwd/.sillyspec 或外部路径）
-    const specSillyspec = platformOpts.specRoot || join(cwd, '.sillyspec')
+    const specSillyspec = resolvePromptSpecBase(platformOpts, cwd)
     const docsRoot = join(specSillyspec, 'docs', projectName)
     const projectsRoot = join(specSillyspec, 'projects')
     const changesRoot = join(specSillyspec, 'changes')
@@ -328,7 +342,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     // 常规模式（无平台 specRoot）：占位符替换为 cwd/.sillyspec 下对应路径
     // 让用 {SPEC_ROOT}/{DOCS_ROOT} 等占位符的 prompt（如 quick/scan）在常规模式也写到正确位置
     const projectName = dbProjectName || basename(cwd)
-    const specSillyspec = join(cwd, '.sillyspec')
+    const specSillyspec = resolvePromptSpecBase(platformOpts, cwd)
     promptText = applyRootPlaceholders(promptText, {
       specRoot: specSillyspec,
       docsRoot: join(specSillyspec, 'docs', projectName),
@@ -356,7 +370,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
 
     // scanProfile 分支也要替换占位符（非 platform 模式也会走到这里）
     const _pName = dbProjectName || basename(cwd)
-    const _specSS = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    const _specSS = resolvePromptSpecBase(platformOpts, cwd)
     const _docsRoot = join(_specSS, 'docs', _pName)
     promptText = applyRootPlaceholders(promptText, {
       specRoot: _specSS,
@@ -368,7 +382,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   } else {
     // 非 platform 模式也要替换占位符
     const projectName = dbProjectName || basename(cwd)
-    const specSillyspec = join(cwd, '.sillyspec')
+    const specSillyspec = resolvePromptSpecBase(platformOpts, cwd)
     const docsRoot = join(specSillyspec, 'docs', projectName)
     const projectsRoot = join(specSillyspec, 'projects')
     const workflowsRoot = join(specSillyspec, 'workflows')
@@ -380,7 +394,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   if (stageName === 'execute' && promptText.includes('{KNOWLEDGE_HIT_REPORT}')) {
     try {
       const { matchKnowledge } = await import('../knowledge-match.js')
-      const effectiveSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+      const effectiveSpecBase = resolvePromptSpecBase(platformOpts, cwd)
       const knowledgeDir = join(effectiveSpecBase, 'knowledge')
       // taskContext: changeName + plan.md task names for better matching
       let taskContext = changeName || ''
@@ -409,7 +423,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   // Execute: 注入 currentExecuteRunId（从变更专属标记文件读取）
   if (stageName === 'execute' && promptText.includes('{EXECUTE_RUN_ID}')) {
     let runId = ''
-    const execSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    const execSpecBase = resolvePromptSpecBase(platformOpts, cwd)
     const runtimeRoot = resolveRuntimeRoot(platformOpts, execSpecBase)
     const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
     try {
@@ -433,7 +447,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     try {
       const { classifyReviewTier } = await import('../review-tier.js')
       const { generateStageReviewRunId, renderReviewJsonContract, stageReviewMarkerPath } = await import('../stage-review.js')
-      const tierSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+      const tierSpecBase = resolvePromptSpecBase(platformOpts, cwd)
       const tierChangeDir = changeName ? join(tierSpecBase, 'changes', changeName) : null
       const designPath = tierChangeDir ? join(tierChangeDir, 'design.md') : null
       let planLevel = null
@@ -491,7 +505,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   if (stageName === 'archive' && promptText.includes('{TASK_COMPLETION_REPORT}')) {
     try {
       const { summarizeTaskCompletion } = await import('../task-review.js')
-      const tcrSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+      const tcrSpecBase = resolvePromptSpecBase(platformOpts, cwd)
       const tcrRuntimeRoot = resolveRuntimeRoot(platformOpts, tcrSpecBase)
       const tcrChangeDir = changeName ? join(tcrSpecBase, 'changes', changeName) : null
       const summary = tcrChangeDir
@@ -505,7 +519,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
 
   // 注入模块上下文（brainstorm/plan/execute 阶段，基于 Module Context Index）
   if (['brainstorm', 'plan', 'execute'].includes(stageName) && projectName) {
-    const effectiveSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    const effectiveSpecBase = resolvePromptSpecBase(platformOpts, cwd)
     const moduleIndex = loadModuleContextIndex(effectiveSpecBase, projectName)
     if (moduleIndex && Object.keys(moduleIndex).length > 0) {
       // 尝试从 step prompt / changeName 匹配模块
@@ -563,7 +577,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   if (platformOpts?.specRoot || platformOpts?.runtimeRoot || changeName) {
     if (stepIndex !== 0) console.log(`\n### ⚠️ 路径与平台规则（每步提醒，通用铁律见首步）`)
     if (platformOpts?.specRoot || platformOpts?.runtimeRoot) {
-      const specSillyspec = platformOpts.specRoot || join(cwd, '.sillyspec')
+      const specSillyspec = resolvePromptSpecBase(platformOpts, cwd)
       console.log(`- **平台模式：所有文件只能写入 \`${specSillyspec}/\` 下的对应子目录，严禁写入源码目录。**`)
       console.log('- **平台模式：Write 工具失败时，不允许用 cat > / tee / heredoc 等方式绕过。先 Read 再 Write，仍失败则记录并停止。**')
       console.log('- **平台模式：local.yaml 中的 commands 必须在 package.json scripts 中真实存在，不存在的标记 unavailable。**')

package/src/run/quick-audit.js

@@ -24,17 +24,16 @@ export function printQuickAuditReview(review) {
     console.error(`\n   quick 已停止：请恢复/拆分这些变更，或重新运行 quick 并显式声明范围。`)
     // 解锁咒语须在 BLOCKED 分支也给出 —— 原只在 confirm/review 分支打印，
     // 普通 --done 走这里只看到「恢复/拆分」反方向指引，正确解法（带 flag 重跑）根本不出现。
-    // 但删除是例外：deletedFiles.length>0 是裸判定（auditQuickCompletion 判定行不受任何 flag
-    // 门控），--force-baseline / --allow-new 都救不回。此时甩 flag 建议会误导调用者照加后继续
-    // 被拦——改提示走完整流程 execute（有意设计：删除是高危操作，须 review 把关）。
+    // 删除：默认 fail-closed（高危操作），但 --allow-delete 显式 opt-in 可解锁（对称 --allow-new）。
     if (review.deletedFiles && review.deletedFiles.length > 0) {
       console.error(`\n   ⛔ 本次含删除文件 ${review.deletedFiles.length} 个：${review.deletedFiles.join(', ')}`)
-      console.error(`   quick 不支持删除——--force-baseline / --allow-new 均无法解锁（有意设计，高危操作须走 review 把关）。`)
-      console.error(`   请改走完整流程：sillyspec run execute（在 plan 的 task allowed_paths 内删除），或先 git restore 撤回删除后再 --done。`)
+      console.error(`   删除是破坏性操作默认 fail-closed，确认删除这些文件请带 --allow-delete 显式解锁：`)
+      console.error(`     sillyspec run quick --done --allow-delete --change <id> --output "..."`)
+      console.error(`   （--force-baseline / --allow-new 不能解锁删除；不确认请 git restore 撤回删除后再 --done，或走完整流程 execute 由 review 把关）`)
     } else {
       console.error(`   如确认接受这些变更，重新运行 --done 时带上对应 flag 即可解锁：`)
       console.error(`     sillyspec run quick --done --force-baseline --allow-new --change <id> --output "..."`)
-      console.error(`     （--force-baseline 覆盖受保护/危险文件如 src/run.js；--allow-new 允许新增文件）`)
+      console.error(`     （--force-baseline 覆盖受保护/危险文件如 src/run.js；--allow-new 允许新增文件；--allow-delete 允许删除文件）`)
     }
   } else if (review.status === 'warning') {
     console.warn(`\n⚠️ quick 变更边界审计 — WARNING：`)

package/src/run/shared.js

@@ -17,6 +17,7 @@ import { fileURLToPath } from 'node:url'
 // safeGit 收口至 src/git-helper.js：import 建本地词法绑定（本模块内部 L128/130/431 调用）+
 // re-export 供 run/ 层现有调用方继续从 shared.js 引用（pure re-export 不建本地绑定，会致内部 ReferenceError）。
 import { safeGit } from '../git-helper.js'
+import { createHash } from 'node:crypto'
 export { safeGit }
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -494,7 +495,7 @@ export function isQuickMetadata(p, linkedChanges = []) {
  * @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 { baselineFiles, allowedFiles = [], allowNew = false, forceBaseline = false, allowDelete = false } = guard
   const { isConfirm } = options
   // stagedTotal：当前所有非 quick 元数据的未提交条目（含前序 baseline 残留）。
   // 与 changedFiles（扣 baseline 后的本轮新增）区分，供审计文案同时展示「本轮新增 vs 累计暂存」，
@@ -506,7 +507,10 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
     // 外层 catch 吞成 warning（multi-agent-review Q3）。safeGit 返回 {value,error} 不抛；若仍有 error
     // 说明真读不到 git 状态，保守阻断（审计无锚点不能放行），不静默降级。
     // trim:false 必传：porcelain 首行前导空格是状态码一部分，trim 会削掉致 parsePorcelainPath 丢首字符。
-    const statusResult = safeGit(cwd, ['status', '--porcelain'], { trim: false })
+    // timeout 15000 + retryOnTimeout：机器忙时 git 子进程启动慢，默认 5s 偏紧易瞬时超时（ETIMEDOUT），
+    // 审计锚点失败即 blocked 中断 quick。加大到 15s 并对 ETIMEDOUT 重试一次（重试 30s），消化绝大多数
+    // 瞬时抖动，免去用户手工重跑（实测反馈：审计 git 偶发 ETIMEDOUT，重试即过）。
+    const statusResult = safeGit(cwd, ['status', '--porcelain'], { trim: false, timeout: 15000, retryOnTimeout: true })
     if (statusResult.error) {
       result.reasons.push(`审计失败（git status）: ${statusResult.error}`)
       result.status = 'blocked'
@@ -584,9 +588,11 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
       }
     }
 
-    // 检查 deleted files
-    for (const f of result.deletedFiles) {
-      result.reasons.push(`删除文件: ${f}`)
+    // 检查 deleted files（--allow-delete 显式放行：删除是破坏性操作，默认 fail-closed，flag 即知情 opt-in）
+    if (!allowDelete) {
+      for (const f of result.deletedFiles) {
+        result.reasons.push(`删除文件: ${f}`)
+      }
     }
 
     // 检查 baseline hit（除非 force-baseline）
@@ -614,9 +620,10 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
       }
     }
 
-    // 判定结果（force-baseline 降级 baselineHit → 非 blocked；allow-new 降级新增文件 → 非 warning。
-    // reasons 文案本就受这两个 flag 控制，但原判定直接看数组长度，致 flag 对 status 失效。）
-    if ((!forceBaseline && result.baselineHit.length > 0) || result.deletedFiles.length > 0 || result.reasons.some(r => r.startsWith('危险') || r.startsWith('删除'))) {
+    // 判定结果（force-baseline 降级 baselineHit → 非 blocked；allow-new 降级新增文件 → 非 warning；
+    // allow-delete 降级删除文件 → 非 blocked。reasons 文案本就受 flag 控制，但原判定直接看数组长度，
+    // 致 flag 对 status 失效。）
+    if ((!forceBaseline && result.baselineHit.length > 0) || (!allowDelete && result.deletedFiles.length > 0) || result.reasons.some(r => r.startsWith('危险') || r.startsWith('删除'))) {
       result.status = 'blocked'
     } else if ((!allowNew && result.newFiles.length > 0) || (allowedFiles.length > 0 && result.reasons.some(r => r.startsWith('超出')))) {
       result.status = 'warning'
@@ -637,6 +644,28 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
       }
     } catch {}
 
+    // task-02: 同文件并发检测——allowedFile 在 baseline（他者改过）且当前 hash ≠ step1 hash（我也改了）
+    // → commit 整文件 pathspec 会夹带他者 hunk，warn 给分离指引（advisory，不阻断，D-002）
+    if (allowedFiles.length > 0 && guard.allowedFilesHash) {
+      const sameFileHits = []
+      for (const f of allowedFiles) {
+        if (isBaselineFile(f) && guard.allowedFilesHash[f] !== undefined) {
+          try {
+            const cur = createHash('sha256').update(readFileSync(join(cwd, f))).digest('hex')
+            if (cur !== guard.allowedFilesHash[f]) sameFileHits.push(f)
+          } catch {} // 文件读失败（删除等）跳过
+        }
+      }
+      if (sameFileHits.length > 0) {
+        result.reasons.push(`同文件并发: ${sameFileHits.length} 个 allowedFile 含他者+你的改动（${sameFileHits.join(', ')}）`)
+        console.warn(`\n⚠️ 同文件并发（${sameFileHits.length} 个 allowedFile 含他者改动+你的改动，commit 整文件会夹带他者 hunk）：`)
+        for (const f of sameFileHits) {
+          console.warn(`   - ${f}`)
+          console.warn(`     分离：git add -p ${f}（交互选你的 hunk）或 git diff ${f} > mine.patch（编辑留你的）+ git apply --cached mine.patch`)
+        }
+      }
+    }
+
     // --confirm 模式：展示 diff 并等待确认
     if (isConfirm && (result.status === 'warning' || result.status === 'blocked')) {
       console.log(`\n📋 quick 变更概览：`)
@@ -658,12 +687,17 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
         }
       }
       if (result.deletedFiles.length > 0) {
-        console.log(`\n   ⛔ 本次含删除文件 ${result.deletedFiles.length} 个——quick 不支持删除，--force-baseline / --allow-new 均无法解锁（有意设计，高危操作须走 review 把关）。`)
-        console.log(`     请改走完整流程：sillyspec run execute（在 plan 的 task allowed_paths 内删除），或先 git restore 撤回删除后再 --done。`)
+        if (guard.allowDelete) {
+          console.log(`\n   ℹ️ 已确认删除文件 ${result.deletedFiles.length} 个（--allow-delete 显式解锁）：${result.deletedFiles.join(', ')}`)
+        } else {
+          console.log(`\n   ⛔ 本次含删除文件 ${result.deletedFiles.length} 个——删除是破坏性操作默认 fail-closed，确认删除请带 --allow-delete 显式解锁：`)
+          console.log(`     sillyspec run quick --done --allow-delete --change <id> --output "..."`)
+          console.log(`     （--force-baseline / --allow-new 不能解锁删除；不确认请 git restore 撤回删除后再 --done，或走完整流程 execute 由 review 把关）`)
+        }
       } else {
         console.log(`\n   如确认接受这些变更，重新运行 --done 时带上对应 flag 即可解锁：`)
         console.log(`     sillyspec run quick --done --force-baseline --allow-new --change <id> --output "..."`)
-        console.log(`     （--force-baseline 覆盖受保护/危险文件如 src/run.js；--allow-new 允许新增文件）`)
+        console.log(`     （--force-baseline 覆盖受保护/危险文件如 src/run.js；--allow-new 允许新增文件；--allow-delete 允许删除文件）`)
         console.log(`   或在首个 sillyspec run quick 启动（step 1）时就声明这些 flag，持久化进 guard。`)
       }
     }

package/src/run/stage.js

@@ -23,6 +23,7 @@ import { resolveSpecDir, resolveChangeDir, resolveRuntimeRoot, resolveQuickSessi
 import { computeScanProfile, applyScanProfileSteps, executeScanPreflight, executeScanPostcheck } from './scan-profile.js'
 import { outputStep } from './prompt.js'
 import { allocateQuicklogEntry, deriveTitleFromLinkedChange, sanitizeDesc } from '../quicklog.js'
+import { createHash } from 'node:crypto'
 import { checkTransition } from '../stage-contract.js'
 import { completeStageGates } from './gates.js'
 
@@ -248,6 +249,7 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
           .filter(Boolean)
         const allowedFiles = quickOpts?.quickFiles || []
         const allowNew = quickOpts?.isAllowNew || false
+        const allowDelete = quickOpts?.isAllowDelete || false
         const forceBaseline = quickOpts?.isForceBaseline || false
         const linkedChanges = Array.isArray(quickOpts?.linkedChanges) ? quickOpts.linkedChanges : []
         // CLI 接管：分配 ql-ID + 写 QUICKLOG「进行中」条目 + 关联 tasks.md（持锁、当天唯一）
@@ -273,7 +275,14 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
           baselineCommit: safeGit(cwd, ['rev-parse', 'HEAD']).value,
           baselineFiles,
           allowedFiles,
+          // task-01: 录每个 allowedFile 内容 sha256，供 --done auditQuickCompletion 检测同文件并发
+          // （allowedFile 在 baseline 且当前 hash ≠ 此值 = 我也改了 → 同文件并发 warn）。文件不存在/读失败跳过。
+          allowedFilesHash: Object.fromEntries(allowedFiles.flatMap(f => {
+            try { return [[f, createHash('sha256').update(readFileSync(join(cwd, f))).digest('hex')]] }
+            catch { return [] }
+          })),
           allowNew,
+          allowDelete,
           forceBaseline,
           linkedChanges,
           quicklogId: qlId,
@@ -286,6 +295,7 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         const parts = [`${baselineFiles.length} 个已有脏文件`]
         if (allowedFiles.length > 0) parts.push(`${allowedFiles.length} 个 allowedFiles`)
         if (allowNew) parts.push('允许新增文件')
+        if (allowDelete) parts.push('允许删除文件')
         console.log(`🛡️ quick 变更边界已记录: ${parts.join(', ')}`)
         console.log(`📝 QUICKLOG 条目已创建: ${qlId}`)
         // 回填 DB changes 行的 title + quicklog_id，让 quick-<hex> 可读、DB↔QUICKLOG 可对账。

package/src/run.js

@@ -6,9 +6,12 @@
  * 外部 import 契约通过 re-export 保留（run.js 是 index.js 懒加载入口，零入边叶子，
  * 外部 import 零感知）。
  *
- * test 直接 import 的契约（9 个）：runCommand / ensureStageSteps /
- * _completeStepForTest / _outputStepForTest / parsePorcelainPath / auditQuickCompletion /
+ * test 直接 import 的契约（7 个）：runCommand / ensureStageSteps /
+ * parsePorcelainPath / auditQuickCompletion /
  * applyRootPlaceholders / sanitizeProjectName / validateParsedProjects。
+ * （outputStep 由 test/output-step-render + archive-task-completion-injection 直接自
+ * ./run/prompt.js import，无需 barrel 转出；completeStep/outputStep 的 `_xxxForTest` 测试别名
+ * 2026-08-13 全部移除——completion 行为走 CLI 子进程，纯渲染器 outputStep 直 import 源模块。）
  */
 // W6 Step8c: 主命令分发（runCommand）+ auto 模式 + ensureStageSteps 搬至 ./run/command.js
 export { runCommand, ensureStageSteps } from './run/command.js'
@@ -18,6 +21,3 @@ export { parsePorcelainPath, auditQuickCompletion, isQuickMetadata } from './run
 export { applyRootPlaceholders } from './run/prompt.js'
 // barrel re-export: sanitizeProjectName + validateParsedProjects 被 test 直接 import（随 handleScan 搬走，契约保留）
 export { sanitizeProjectName, validateParsedProjects } from './run/complete-handlers.js'
-// 测试专用导出：completeStep 是 step 完成处理核心、outputStep 是 prompt 渲染器，characterization 测试直接驱动
-export { completeStep as _completeStepForTest } from './run/complete.js'
-export { outputStep as _outputStepForTest } from './run/prompt.js'

package/src/stage-contract-spec.js

@@ -262,6 +262,17 @@ const PLAN_RULES = [
     spec: '产出 `plan.md`(任务拆解与规划,缺失即阻断)',
     failMessage: 'plan.md 缺失: ${path}',
   },
+  // module-impact 首版(D-001@v2):large 变更(scale≠small)在 plan review_plan 步生成 module-impact.md
+  // 首版(活文档全程演化——execute/verify 更新、archive 终审)。small 豁免(走 quick,module-impact 无用)。
+  // condition 生效依赖 validatePlanOutputs 把 design.md scale 传入 ctx(stage-contract.js D-009)。
+  {
+    id: 'plan.module-impact.exists', stage: 'plan', source: 'validatePlanOutputs', severity: 'error', kind: 'file-exists',
+    target: { root: 'change', path: 'module-impact.md' },
+    data: {},
+    condition: { ctxField: 'scale', ne: 'small' },
+    spec: 'large 变更产出 `module-impact.md` 首版(plan review_plan 步生成;scale=small 豁免)',
+    failMessage: 'module-impact.md 缺失: ${path}（large 变更应在 plan 审查计划步生成模块影响分析首版）',
+  },
   // entry-point-wiring(custom):design.md 命中入口实例化/启动路径模式时,被提到的入口文件
   // (cli.ts/main.ts/server.(js|ts)/index.(js|ts))必须出现在某 task allowed_paths 或 plan.md
   // 文件变更清单中,否则需 design.md 紧邻写明豁免。判定算法(多源 allowed_paths 收集 + 逐文件对账 +

package/src/stage-contract.js

@@ -328,8 +328,18 @@ function validatePlanOutputs(cwd, changeName, context = {}) {
   const changeDir = resolveChangeDir(cwd, changeName, specRoot)
   const planFile = join(changeDir, 'plan.md')
 
+  // 读 design.md frontmatter scale(若有)传入引擎 ctx,供 plan.module-impact.exists 的 condition
+  // (scale≠small)判定——large 要求 module-impact 首版,small 豁免(走 quick)。fail-safe:无 scale→null→
+  // condition(ne 'small')成立→保守要求 module-impact(同 brainstorm scale 读取模式,line 264-272)。
+  const designPathForScale = join(changeDir, 'design.md')
+  let scale = null
+  if (existsSync(designPathForScale)) {
+    const fm = readFileSync(designPathForScale, 'utf8').match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/)
+    const sm = fm && fm[1].match(/^scale:[ \t]*['"]?(\w+)/m)
+    if (sm) scale = sm[1]
+  }
   // plan.md 存在性由引擎消费 manifest。entryPoint/id-trace/decisions 为 custom kind(下方保留)。
-  const engineResult = evaluateRules('plan', { changeDir })
+  const engineResult = evaluateRules('plan', { changeDir, scale })
   const errors = [...engineResult.errors]
   const warnings = [...engineResult.warnings]
 

package/src/stage-review.js

@@ -414,7 +414,7 @@ export function validateStageReview(opts) {
  * @param {object} context - { stage, reviewRunId } 用于错误提示路径
  */
 export function printStageReviewResult(result, context = {}) {
-  const { stage } = context
+  const { stage, reviewRunId, runtimeRoot } = context
   if (result.ok && result.warnings.length === 0) {
     console.log(`\n✅ Stage Review Gate — ${stage} 阶段独立审查通过`)
     return
@@ -425,6 +425,14 @@ export function printStageReviewResult(result, context = {}) {
     for (const err of result.errors) {
       console.error(`   - ${err}`)
     }
+    // echo 完整 review.json 路径：runId + marker 已由 CLI 自动生成写入（prompt.js review step
+    // 渲染 / gate 触发），agent 直接派独立子代理把 review.json 写到此路径，勿手算 runId、勿手写
+    // marker（历史坑：agent 撞 gate 后自己算 runId 猜错 review- 前缀，填 exec-/裸 ts 被 CLI 忽略）。
+    if (reviewRunId) {
+      const reviewDir = runtimeRoot ? `${runtimeRoot}/stage-reviews/${stage}-${reviewRunId}` : `.sillyspec/.runtime/stage-reviews/${stage}-${reviewRunId}`
+      console.error(`\n   📁 review.json 直接写此路径（runId/marker CLI 已生成写入，勿手算 runId、勿手写 marker）：`)
+      console.error(`      ${reviewDir}/review.json`)
+    }
     console.error(`\n   提示：tier=independent 要求独立审查子代理产出 review.json，补全后重新 --done`)
     console.error(`   可用 sillyspec register-stage-review --change <名> --stage ${stage} [--from <已有review.json>] 一步生成 run 目录 + review.json 骨架（docHash 自动算）+ 写 marker + 自检，省掉手动建目录/写 marker`)
   }