sillyspec 3.26.13 → 3.26.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.26.13",
+  "version": "3.26.14",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/index.js

@@ -90,7 +90,7 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec gate <stage> --change <name> [--json]      机器门控：阶段能否标记完成（只读）
   sillyspec derive <facet> --change <name> [--json]    单项事实核验（facet: execute-evidence|verify-test|task-reviews|artifacts）
   sillyspec backfill-reviews --change <name> [--json]  为手动补的 task 生成 review.json 草稿（cannot_verify，解 archive 客观完成度阻断）
-  sillyspec register-stage-review --change <name> --stage <brainstorm|plan|execute> [--from <review.json>] [--json]
+  sillyspec register-stage-review --change <name> (--stage <brainstorm|plan|execute> | --all) [--from <review.json>] [--refresh-hash] [--json]
                                       生成/adopt stage 级 review.json（docHash 自动算 + 写 marker，治 tier=independent marker 死锁）
 
   sillyspec doctor [子命令]            进度库健康检查 + 修复（顶层命令，非 worktree doctor）
@@ -574,8 +574,14 @@ async function main() {
       const rsrStage = rsrStageIdx >= 0 && args[rsrStageIdx + 1] ? args[rsrStageIdx + 1] : null;
       const rsrFromIdx = args.indexOf('--from');
       const rsrFrom = rsrFromIdx >= 0 && args[rsrFromIdx + 1] ? args[rsrFromIdx + 1] : null;
-      if (!rsrChange || !rsrStage) {
-        console.error('用法: sillyspec register-stage-review --change <名> --stage <brainstorm|plan|execute> [--from <review.json>] [--spec-dir <path>] [--json]\n  生成/adopt stage 级 review.json（docHash 自动算 + 写 marker），治 tier=independent marker 死锁');
+      // docHash 联动（坑 stage-review-dochash-manual-resync，2026-08-21 实证）：改一版 design 要
+      // 重算 2-3 个 stage review 的 docHash，手工易漏、gate 报错才补。--refresh-hash 就地刷新单个
+      // 既有 review 的 hash（保留结论）；--all 一次处理三个 stage（有 review 刷 hash，无 review
+      // 生成骨架——改版后一条命令完成全部联动）。
+      const rsrRefreshHash = filteredArgs.includes('--refresh-hash');
+      const rsrAll = filteredArgs.includes('--all');
+      if (!rsrChange || (!rsrStage && !rsrAll) || (rsrAll && rsrStage)) {
+        console.error('用法: sillyspec register-stage-review --change <名> (--stage <brainstorm|plan|execute> | --all) [--from <review.json>] [--refresh-hash] [--spec-dir <path>] [--json]\n  生成/adopt/刷新 stage 级 review.json（docHash 自动算 + 写 marker）；--all 一次处理三个 stage（有 review 刷新 hash、无 review 生成骨架）；--refresh-hash 就地刷新既有 review 的 docHash（保留 verdict 待确认续用）');
         process.exit(2);
       }
       // 与 run 入口同源消毒（防路径穿越；register 下游写 marker、拼 changes/review 路径）
@@ -583,20 +589,38 @@ async function main() {
       const { registerStageReview } = await import('./stage-review.js');
       const rsrPlatformOpts = {};
       if (specDir) rsrPlatformOpts.specRoot = specDir;
-      try {
-        const result = registerStageReview({ changeName: rsrChange, stage: rsrStage, fromFile: rsrFrom, cwd: dir, platformOpts: rsrPlatformOpts });
-        if (json) {
-          process.stdout.write(JSON.stringify({ ok: true, command: 'register-stage-review', change: rsrChange, stage: rsrStage, ...result }));
-        } else {
-          console.log(`✅ 已注册 ${rsrStage} stage review [${result.reviewRunId}] → ${result.reviewPath}（mode: ${result.mode}）`);
-          console.log(`   marker → ${result.markerPath}`);
-          console.log(`   下一步：独立审查子代理对照 ${result.mainDoc} 填 verdict/checklist 后重跑 --done`);
+      const rsrStages = rsrAll ? ['brainstorm', 'plan', 'execute'] : [rsrStage];
+      const rsrResults = [];
+      let rsrFailed = 0;
+      for (const st of rsrStages) {
+        try {
+          // --all 的单 stage 语义：有既有 review → refresh-hash；无 → 骨架。显式 --refresh-hash
+          // 则强制 refresh（无既有 review 时报错，提示先生成骨架）
+          const { getLatestStageReviewRunId, stageReviewMarkerPath } = await import('./stage-review.js');
+          const { resolveRuntimeRoot } = await import('./run/shared.js');
+          const rsrRuntimeRoot = resolveRuntimeRoot(rsrPlatformOpts, rsrPlatformOpts.specRoot || join(dir, '.sillyspec'));
+          const hasExisting = !!getLatestStageReviewRunId(rsrRuntimeRoot, st, rsrChange);
+          const wantRefresh = rsrRefreshHash || (rsrAll && hasExisting);
+          const result = registerStageReview({ changeName: rsrChange, stage: st, fromFile: rsrFrom, cwd: dir, platformOpts: rsrPlatformOpts, refreshHash: wantRefresh });
+          rsrResults.push({ stage: st, ...result });
+          if (json) {
+            process.stdout.write(JSON.stringify({ ok: true, command: 'register-stage-review', change: rsrChange, stage: st, ...result }) + '\n');
+          } else {
+            console.log(`✅ 已注册 ${st} stage review [${result.reviewRunId}] → ${result.reviewPath}（mode: ${result.mode}）`);
+            console.log(`   marker → ${result.markerPath}`);
+            if (result.mode === 'refreshed') {
+              console.log(`   docHash 已按当前 ${result.mainDoc} 重算（verdict 结论是否仍适用需人工确认）`);
+            } else {
+              console.log(`   下一步：独立审查子代理对照 ${result.mainDoc} 填 verdict/checklist 后重跑 --done`);
+            }
+          }
+        } catch (e) {
+          rsrFailed++;
+          if (json) process.stdout.write(JSON.stringify({ ok: false, command: 'register-stage-review', change: rsrChange, stage: st, error: e.message }) + '\n');
+          else console.error(`❌ [${st}] ` + e.message);
         }
-      } catch (e) {
-        if (json) process.stdout.write(JSON.stringify({ ok: false, command: 'register-stage-review', error: e.message }));
-        else console.error('❌ ' + e.message);
-        process.exitCode = 1;
       }
+      if (rsrFailed > 0) process.exitCode = 1;
       break;
     }
     case 'docs': {

package/src/progress.js

@@ -1188,8 +1188,11 @@ export class ProgressManager {
     if (projectRow === undefined) return null;
     const projectName = projectRow.name;
 
-    // 2. 活跃变更（取第一个，或空）
-    const changeRows = sqlDb.prepare("SELECT id, name, current_stage, last_active FROM changes WHERE status = 'active' ORDER BY name").all();
+    // 2. 活跃变更（取 last_active 最新的一个）
+    // ql-20260821-003：多活跃仓（变更隔离是常态，单仓可同时存在 N 个 active）下
+    // 原 ORDER BY name 恒取字典序最前（通常是最老的变更），「当前变更/最后活动」
+    // 停留在历史数据。dump 语义是「当前工作流状态」→ 取最近活跃的那个。
+    const changeRows = sqlDb.prepare("SELECT id, name, current_stage, last_active FROM changes WHERE status = 'active' ORDER BY last_active DESC").all();
     if (changeRows.length === 0) {
       // 无活跃变更 → 返回仅含 project 的骨架
       return {

package/src/run/command.js

@@ -368,8 +368,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // 纯只读比较：零会话/QUICKLOG 副作用，仅解析 --base/--full/--report 后转发 scan-diff 退出码。
   if (stageName === 'scan' && flags.includes('--diff')) {
     const { runScanDiff } = await import('../scan-diff.js')
-    const diffBaseIdx = flags.indexOf('--base')
-    const diffBase = diffBaseIdx >= 0 && flags[diffBaseIdx + 1] ? flags[diffBaseIdx + 1] : null
+    const diffBase = getFlagValue('--base')
     process.exitCode = runScanDiff({
       projectRoot: cwd,
       specBase,
@@ -418,26 +417,26 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   }
 
   // 解析 --output
+  // F4 守卫统一走 getFlagValue（坑 raw-flag-value-bypass）：裸 flags[idx+1] 会把漏值后紧跟的
+  // flag 名当值（--output --input x → output="--input"），--change --done 甚至会建出名为
+  // --done 的变更目录（assertSafeChangeName 的 [\w.-] 恰好放行）。getFlagValue 的 F4 注释
+  // 点名过本坑，此前只有 from-step 等少数 flag 用了它。
   let outputText = null
-  const outputIdx = flags.indexOf('--output')
-  if (outputIdx !== -1 && flags[outputIdx + 1]) {
-    outputText = flags[outputIdx + 1]
-  }
+  const outputValue = getFlagValue('--output')
+  if (outputValue !== null) outputText = outputValue
 
   // 解析 --input
   let inputText = null
-  const inputIdx = flags.indexOf('--input')
-  if (inputIdx !== -1 && flags[inputIdx + 1]) {
-    inputText = flags[inputIdx + 1]
-  }
+  const inputValue = getFlagValue('--input')
+  if (inputValue !== null) inputText = inputValue
 
   // 解析 --linked-changes <a,b|none>（quick 专用：显式声明关联变更，CI/脚本友好）
   // 与 --change 解耦：--linked-changes 语义清晰（关联变更），不与「指定变更名」混淆。
   // null = 未指定（走持久化/交互/兼容回退）；[] = 显式 none（不关联）；[...] = 显式列表
   let explicitLinked = null
-  const linkedIdx = flags.indexOf('--linked-changes')
-  if (linkedIdx !== -1 && flags[linkedIdx + 1]) {
-    const v = flags[linkedIdx + 1].trim()
+  const linkedValue = getFlagValue('--linked-changes')
+  if (linkedValue !== null) {
+    const v = linkedValue.trim()
     explicitLinked = v.toLowerCase() === 'none' ? [] : v.split(',').map(s => s.trim()).filter(Boolean)
   }
 
@@ -445,9 +444,9 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // 历史写法，语义与「指定变更名」冲突，新用法建议改用 --linked-changes）
   let changeName = null
   let linkedChanges = []
-  const changeIdx = flags.indexOf('--change')
-  if (changeIdx !== -1 && flags[changeIdx + 1]) {
-    changeName = flags[changeIdx + 1]
+  const changeValue = getFlagValue('--change')
+  if (changeValue !== null) {
+    changeName = changeValue
     if (stageName === 'quick') {
       linkedChanges = changeName.split(',').map(s => s.trim()).filter(Boolean)
       changeName = null
@@ -489,7 +488,9 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     // 1373-1376 已把 quick 的 --change 值清进 linkedChanges、changeName 置 null。
     // 此处回看 --change 原始值：若恰好是单个 quick-<8hex> → 识别为本会话 sessionId（精确恢复），
     // 并撤销把它当 linkedChanges 的误判。多值或不匹配 → 维持 linkedChanges 语义（旧兼容）。
-    const rawChange = changeIdx !== -1 && flags[changeIdx + 1] ? flags[changeIdx + 1].trim() : null
+    // F4 守卫同款（changeIdx 变量已随裸读清理移除，此处改 getFlagValue 复读原始值）
+    const rawChangeValue = getFlagValue('--change')
+    const rawChange = rawChangeValue !== null ? rawChangeValue.trim() : null
     const rawIsSingleSid = rawChange && rawChange.indexOf(',') === -1 && QUICK_SID_RE.test(rawChange)
     if (rawIsSingleSid) {
       // --done --change quick-<uuid8>：精确恢复（撤销 1373-1376 把它误当 linkedChanges）
@@ -549,18 +550,18 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     process.exit(2) // 用法错 → exit 2
   }
   let quickFiles = []
-  const filesIdx = flags.indexOf('--files')
-  if (filesIdx !== -1 && flags[filesIdx + 1]) {
-    quickFiles = flags[filesIdx + 1].split(',').map(f => f.trim()).filter(Boolean)
+  const filesValue = getFlagValue('--files')
+  if (filesValue !== null) {
+    quickFiles = filesValue.split(',').map(f => f.trim()).filter(Boolean)
   }
 
   // 解析 --file-notes "path::括注 || path::括注"（quick 专用：QUICKLOG「文件：」行落盘多行括注）。
   // 旁路注入 quicklog.js（per-process setter），不经 complete 收尾路径透传（避碰多 agent 并发改的收尾热点）。
   // completeQuicklogEntry 读后即清；不传 → '' → 回填审计到的实际文件单行（向后兼容）。
   let quickFileNotes = ''
-  const fileNotesIdx = flags.indexOf('--file-notes')
-  if (fileNotesIdx !== -1 && flags[fileNotesIdx + 1]) {
-    quickFileNotes = flags[fileNotesIdx + 1]
+  const fileNotesValue = getFlagValue('--file-notes')
+  if (fileNotesValue !== null) {
+    quickFileNotes = fileNotesValue
   }
   setQuickFileNotes(quickFileNotes)
 
@@ -771,16 +772,20 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       let autoName = changeName || resolveChangeNameAuto(cwd, specRoot) || 'default'
       // archive 特例：归档后变更从活跃列表排除（listChanges WHERE status='active'），
       // 不带 --change 回退 default 会读错变更。无活跃变更时取最新归档变更，读其现有 progress。
+      // 归档目录名 = 原变更名恒等迁移（archiveDestDirName 不改名），直接原名对读——此前按
+      // 「日期前缀过滤 + 剥日期」找，剥出的短名与 DB 行名（含日期）恒不符 → pm.read 返回
+      // null → initChange 凭空建幻影变更再跑 archive（坑 archive-fallback-phantom-change）。
       if (stageName === 'archive' && autoName === 'default') {
         try {
           const archiveDir = join(specBase, 'changes', 'archive')
           if (existsSync(archiveDir)) {
-            const latest = readdirSync(archiveDir)
-              .filter(d => /^\d{4}-\d{2}-\d{2}-.+/.test(d))
+            const latest = readdirSync(archiveDir, { withFileTypes: true })
+              .filter(d => d.isDirectory())
+              .map(d => d.name)
               .sort()
               .pop()
             if (latest) {
-              autoName = latest.replace(/^\d{4}-\d{2}-\d{2}-/, '')
+              autoName = latest
               progress = pm.read(cwd, autoName)
             }
           }
@@ -887,12 +892,20 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     // stale/revising 阶段可能 steps 为空，或者 execute 阶段的 steps 需要从最新 plan.md 刷新
     const stageDataPre = progress.stages[stageName]
     const needsInit = !stageDataPre || !stageDataPre.steps || stageDataPre.steps.length === 0
-    // execute 阶段在 reopen 时需要从最新 plan.md 重新解析 steps（plan 可能已变更）
+    // execute 阶段在 reopen 时需要从最新 plan.md 重新解析 steps（plan 可能已变更）。
+    // 按名保留旧状态（坑 execute-reopen-wipes-prior-completion）：reopenStage 的语义是
+    // 「i < fromStep 保持原状（completed）」，此前预置全 pending 会把 fromStep 之前已完成的
+    // 步骤一并清空——CLI 打印「从步骤 N 开始修订」、prompt 注入「之前已完成不需要重做」，
+    // 实际 currentIdx 却回到 0，agent 被迫从头重做，修订语义完全失效。
     if (needsInit || stageName === 'execute') {
       const freshSteps = await getStageSteps(stageName, cwd, progress, specRoot)
       if (freshSteps && freshSteps.length > 0) {
         if (!progress.stages[stageName]) progress.stages[stageName] = { status: 'stale', steps: [] }
-        progress.stages[stageName].steps = freshSteps.map(s => ({ name: s.name, status: 'pending' }))
+        const oldSteps = progress.stages[stageName].steps || []
+        progress.stages[stageName].steps = freshSteps.map(s => {
+          const old = oldSteps.find(step => step.name === s.name)
+          return old ? { ...old } : { name: s.name, status: 'pending' }
+        })
         pm._write(cwd, progress, effectiveChange)
         progress = pm.read(cwd, effectiveChange) || progress
       }
@@ -1148,15 +1161,17 @@ async function resetStage(pm, progress, stageName, cwd, changeName, platformOpts
 async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts = {}) {
   const flowStages = ['brainstorm', 'plan', 'execute', 'verify', 'archive']
   const isDone = flags.includes('--done')
-  const outputIdx = flags.indexOf('--output')
-  const outputText = outputIdx !== -1 && flags[outputIdx + 1] ? flags[outputIdx + 1] : null
-  const inputIdx = flags.indexOf('--input')
-  const inputText = inputIdx !== -1 && flags[inputIdx + 1] ? flags[inputIdx + 1] : null
+  // F4 守卫（坑 raw-flag-value-bypass，与 runCommand getFlagValue 同款）：裸 flags[idx+1] 会把
+  // 漏值后紧跟的 flag 名当值（--output --done → outputText="--done" 污染落盘 output）。
+  const autoFlagValue = (name) => {
+    const i = flags.indexOf(name)
+    const next = i !== -1 ? flags[i + 1] : undefined
+    return next && !String(next).startsWith('--') ? next : null
+  }
+  const outputText = autoFlagValue('--output')
+  const inputText = autoFlagValue('--input')
   const skipApproval = flags.includes('--skip-approval')
-  const explicitMode = (() => {
-    const m = flags.indexOf('--mode')
-    return m !== -1 && flags[m + 1] ? flags[m + 1] : null
-  })()
+  const explicitMode = autoFlagValue('--mode')
   const specBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
 
   // Helper: 在 auto 模式下获取步骤定义
@@ -1193,7 +1208,10 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
         return progress
       }
     }
-    const changed = await ensureStageSteps(progress, stage, cwd)
+    // specRoot 必传（坑 auto-mode-specroot-miss）：平台模式 specRoot 是外部目录，漏传时
+    // getStageSteps 从 cwd 推导 miss 掉 plan/execute 动态步骤（buildPlanSteps(null) 只剩
+    // 2 步 fixedPrefix），种出的步骤表两次 --done 即判阶段完成，与 getAutoSteps 渲染双轨失配
+    const changed = await ensureStageSteps(progress, stage, cwd, platformOpts?.specRoot || null)
     if (stageChanged || changed) {
       pm._write(cwd, progress, changeName)
       triggerSync(cwd, changeName, platformOpts)
@@ -1369,7 +1387,8 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
     progress.stages[next].startedAt = new Date().toLocaleString('zh-CN',{hour12:false})
   }
   progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
-  await ensureStageSteps(progress, next, cwd)
+  // specRoot 同上（坑 auto-mode-specroot-miss）：平台模式动态步骤表必须从外部 specRoot 构建
+  await ensureStageSteps(progress, next, cwd, platformOpts?.specRoot || null)
   pm._write(cwd, progress, changeName)
   triggerSync(cwd, changeName, platformOpts)
   progress = pm.read(cwd, changeName)

package/src/run/complete-handlers.js

@@ -135,9 +135,14 @@ async function archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platform
   try {
     const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
     if (existsSync(runtimeRoot)) {
+      // stage-review marker 精确匹配（坑 marker-suffix-overmatch）：marker 名是
+      // current-stage-review-run-id-<stage>-<change>，按 endsWith('-'+change) 后缀匹配会在归档
+      // 手工短名变更（如 login）时误删自动日期前缀变更（2026-08-01-login 天然以 '-login' 结尾）
+      // 的 marker。stage 集合与写入侧 stageReviewMarkerPath 的调用方一致。
+      const REVIEW_STAGES = ['brainstorm', 'plan', 'execute', 'verify', 'archive']
       const markers = readdirSync(runtimeRoot).filter((f) =>
         f === `current-execute-run-id-${archiveChangeName}` ||
-        (f.startsWith('current-stage-review-run-id-') && f.endsWith(`-${archiveChangeName}`)),
+        REVIEW_STAGES.some(st => f === `current-stage-review-run-id-${st}-${archiveChangeName}`),
       )
       for (const m of markers) {
         try { unlinkSync(join(runtimeRoot, m)) } catch {}

package/src/run/complete.js

@@ -24,7 +24,7 @@ import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions, resolveR
 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, enforceSymbolImpactGate, completeStageGates, readDesignScale } from './gates.js'
+import { enforceDepsGate, enforceReviewJsonGate, enforceSymbolImpactGate, warnMissingUiPrototype, 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'
@@ -229,6 +229,8 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   // 符号影响面报告硬门（ql-20260816-005-3d7f）：execute「加载上下文」步产出落盘核验——
   // symbol-impact.md 存在 + plan 每 task 有结论行；防前缀步被一句「上下文在会话内」盖章跳过。
   await enforceSymbolImpactGate(stageName, changeName, steps[currentIdx]?.name, specBase)
+  // UI 原型软提醒（非阻断）：brainstorm 收尾步 design.md 命中前端文件但无 prototype → 提示用户可否决
+  warnMissingUiPrototype(stageName, changeName, steps[currentIdx]?.name, specBase)
 
   // ── noAI 步骤硬门（坑 noai-done-bypass）：noAI 步骤的确定性校验不可被 --done 绕过 ──
   // 正常路径 agent 跑 `run <stage>` 推进到 noAI step 时，runStage 自动执行 _cliAction
@@ -321,6 +323,9 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       const _drafts = await generateTaskReviewDrafts({ changeName, cwd, platformOpts, ctx: _draftCtx })
       if (_drafts.generated > 0) {
         console.log('   📄 自动补写 ' + _drafts.generated + ' 个 per-task review.json 草稿（cannot_verify，主 agent 实现模式兜底，需 agent 复核后升级为 pass/fail）')
+        if (_drafts.noAttribution > 0) {
+          console.warn('   ⚠️ 其中 ' + _drafts.noAttribution + ' 个 task 的 allowed_paths 未命中本次 diff（无归属草稿，changedFiles 为空）——需人工确认实际改动后升级 verdict，确属未实现则回 fail')
+        }
         if (_drafts.unattributed && _drafts.unattributed.length > 0) {
           console.warn('   ⚠️ ' + _drafts.unattributed.length + ' 个变更文件未归属任何 task（顺带修复/非源码），草稿未覆盖：' + _drafts.unattributed.join(', '))
         }

package/src/run/concurrent-detect.js

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

package/src/run/gates.js

@@ -92,6 +92,26 @@ export async function enforceSymbolImpactGate(stageName, changeName, currentStep
   process.exit(1)
 }
 
+/**
+ * UI 原型软提醒（非阻断）：brainstorm「生成规范文件」步 --done 时，design.md 命中前端文件
+ * 但变更目录无 prototype-*.html → console.warn 一行，用户可否决。程度判断（布局级才必须出）
+ * 是语义判断，CLI 不硬卡只提示——治 agent 对明显 UI 改造静默跳过原型的坑。
+ */
+export function warnMissingUiPrototype(stageName, changeName, currentStepName, specBase) {
+  if (stageName !== 'brainstorm' || !currentStepName || !currentStepName.includes('生成规范文件')) return
+  if (!changeName || !specBase) return
+  const changeDir = join(specBase, 'changes', changeName)
+  const designPath = join(changeDir, 'design.md')
+  if (!existsSync(designPath)) return
+  try {
+    if (readdirSync(changeDir).some(f => /^prototype-.*\.html$/i.test(f))) return
+  } catch { return } // 目录不可读（平台模式 specRoot 差异等）→ 静默跳过，不制造噪音
+  const design = readFileSync(designPath, 'utf8')
+  const feExts = [...new Set((design.match(/\.(vue|svelte|astro|tsx|jsx|css|scss|sass|less|styl|html)\b/gi) || []).map(s => s.replace('.', '').toLowerCase()))]
+  if (feExts.length === 0) return
+  console.warn(`   ⚠️ design.md 命中前端文件类型（${feExts.join('/')}）但变更目录无 prototype-*.html——轻微样式改动可忽略；布局/交互流程级变化应补原型（sillyspec run brainstorm --reopen 回到「分段展示设计」，或直接让 agent 补生成）`)
+}
+
 /**
  * 判断当前 execute step 所在 wave 是否全部 task 都声明 no_deps_verify: true（D-006@v2）。
  * 仅 wave 执行步骤（名如 "Wave N 执行"）可 opt-out；非 wave 步骤恒返回 false（保守过门）。
@@ -854,6 +874,10 @@ export async function completeStageGates({ stageName, cwd, changeName, platformO
     stageData.steps = freshSteps
     stageData.status = 'pending'
     stageData.completedAt = null
+    // scan 的 quick 档 profile 随步骤表一并失效（坑 scan-quick-profile-step-mismatch 收尾）：
+    // getStageSteps 感知 scanProfile 返回 3 步表，重置后 DB 是 11 步注册表，残留 profile 会让
+    // 下次 --status 走 ensureStageSteps 时 11 vs 3 误报漂移重播种。下次 run scan 会重算 profile。
+    if (stageName === 'scan' && stageData.scanProfile) delete stageData.scanProfile
     if (progress.currentStage === stageName) progress.currentStage = ''
     pm._write(cwd, progress, changeName)
   }

package/src/run/prompt.js

@@ -183,8 +183,11 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   console.log(`project: ${projectName}`)
   if (changeName) {
     console.log(`change: ${changeName}`)
-    const isPlatform = platformOpts?.specRoot || platformOpts?.runtimeRoot
-    const changeDirBase = isPlatform ? platformOpts.specRoot : '.sillyspec'
+    // changeDir 根（坑 change-dir-base-mismatch）：平台/漂移锚定用绝对根（specDriftAnchor 防
+    // worktree 副本错位），普通本地保持相对 '.sillyspec' 展示契约（test 钉死）。此前
+    // isPlatform 用 specRoot||runtimeRoot 判定、取值只拿 specRoot——runtimeRoot-only 平台组合
+    // join(null,...) 直接 TypeError。
+    const changeDirBase = platformOpts?.specRoot || platformOpts?.specDriftAnchor || '.sillyspec'
     const changeDir = join(changeDirBase, 'changes', changeName)
     console.log(`changeDir: ${changeDir}`)
   }
@@ -715,8 +718,9 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       console.log('- **平台模式：local.yaml 中的 commands 必须在 package.json scripts 中真实存在，不存在的标记 unavailable。**')
     }
     if (changeName) {
-      const isPlatform = platformOpts?.specRoot || platformOpts?.runtimeRoot
-      const changeDirBase = isPlatform ? platformOpts.specRoot : '.sillyspec'
+      // changeDir 根与上方头部同源（坑 change-dir-base-mismatch）：平台/漂移锚定绝对根，
+      // 普通本地保持相对 '.sillyspec' 展示；runtimeRoot-only 组合不再 join(null) 崩溃
+      const changeDirBase = platformOpts?.specRoot || platformOpts?.specDriftAnchor || '.sillyspec'
       const changeDir = join(changeDirBase, 'changes', changeName)
       console.log(`- **文件路径规则：所有变更文件必须写入 \`${changeDir}/\` 目录下。不要自己拼接路径，直接使用 changeDir 值。示例：\`${changeDir}/proposal.md\`**`)
     }

package/src/run/scan-profile.js

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

package/src/run/shared.js

@@ -367,8 +367,14 @@ export function writePlatformPointer(cwd, platformOpts, extra = {}) {
     declaredAt: new Date().toISOString(),
   }
   try {
-    mkdirSync(join(platformOpts.specRoot, '.runtime'), { recursive: true })
-    writeFileSync(join(platformOpts.specRoot, '.runtime', 'platform-scan.json'), JSON.stringify(payload, null, 2) + '\n')
+    // platform-scan.json 只在 specRoot 存在时可写（坑 pointer-runtime-root-only-null-join）：
+    // runtimeRoot-only 平台组合（command.js 明确允许）下 specRoot 为 null，此前 join(null,…)
+    // 抛 ERR_INVALID_ARG_TYPE 落入总 catch → 指针与接管声明也一并静默未写，双入口 fail-closed
+    // 对该组合整体失效。分步写：specRoot 缺失只跳过 platform-scan.json，指针/声明照写。
+    if (platformOpts.specRoot) {
+      mkdirSync(join(platformOpts.specRoot, '.runtime'), { recursive: true })
+      writeFileSync(join(platformOpts.specRoot, '.runtime', 'platform-scan.json'), JSON.stringify(payload, null, 2) + '\n')
+    }
     writeFileSync(join(cwd, '.sillyspec-platform.json'), JSON.stringify(payload, null, 2) + '\n')
     writeFileSync(join(cwd, PLATFORM_MANAGED_FILENAME), JSON.stringify(declaration, null, 2) + '\n')
     return true
@@ -913,13 +919,17 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
     // 致 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('超出')))) {
+    } else if ((!allowNew && result.newFiles.some(f => !isQuickMetadata(f, guard.linkedChanges))) || (allowedFiles.length > 0 && result.reasons.some(r => r.startsWith('超出')))) {
+      // newFiles 按元数据过滤后判定（坑 quick-metadata-warning-no-reason）：.sillyspec/ 被 git
+      // 跟踪的仓库里 quick 新建的 quicklog/*.md 是合法元数据，不过滤会 status=warning 而
+      // reasons 为空（reasons 侧已过滤），打印空原因的 WARNING 噪声。
       result.status = 'warning'
     }
 
-    // quicklog 存在性检查
+    // quicklog 存在性检查（specBase 感知：平台模式 quicklog 写在 specRoot 下，stage.js
+    // allocateQuicklogEntry 同源；硬编码 cwd/.sillyspec 会恒误报「目录不存在」抬 warning）
     try {
-      const quicklogDir = join(cwd, '.sillyspec', 'quicklog')
+      const quicklogDir = join(specBase || join(cwd, '.sillyspec'), 'quicklog')
       if (existsSync(quicklogDir)) {
         const qlFiles = readdirSync(quicklogDir).filter(f => f.endsWith('.md'))
         if (qlFiles.length === 0) {
@@ -1342,6 +1352,17 @@ export async function getStageSteps(stageName, cwd, progress, specDir = null) {
     const changeDir = resolveChangeDir(cwd, progress, specDir)
     return buildPlanSteps(changeDir)
   }
+  if (stageName === 'scan') {
+    // quick 档感知（坑 scan-quick-profile-step-mismatch）：scan 的 scanProfile 在首进程
+    // runStage 里算出并持久化（stageData.scanProfile），quick 档把 11 步注册表裁成 3 步。
+    // 此处恒返回注册表会让后续进程 ensureStageSteps 见 3 vs 11 触发漂移重播种（quick 已完成
+    // 步丢失、从未执行的注册表步骤被 --done），同进程 outputStep 也用错位 defSteps 渲染。
+    // quick 档 → 与 applyScanProfileSteps 同源返回 3 步表；standard/deep 与注册表同长度零影响。
+    if (progress?.stages?.scan?.scanProfile?.mode === 'quick') {
+      const { buildQuickScanSteps } = await import('./scan-profile.js')
+      return buildQuickScanSteps()
+    }
+  }
   const def = stageRegistry[stageName]
   return def ? def.steps : null
 }

package/src/stage-review.js

@@ -465,7 +465,7 @@ export function printStageReviewResult(result, context = {}) {
  * @returns {{ ok: boolean, reviewRunId: string, reviewPath: string, markerPath: string, mode: 'skeleton'|'adopted', mainDoc: string, review: object }}
  * @throws {Error} changeName 空 / stage 非法 / 主文档缺失 / --from 不存在或 schema 不过
  */
-export function registerStageReview({ changeName, stage, fromFile, cwd, platformOpts = {} }) {
+export function registerStageReview({ changeName, stage, fromFile, cwd, platformOpts = {}, refreshHash = false }) {
   if (!changeName) throw new Error('register-stage-review: changeName 不能为空')
   if (!stage || !STAGE_MAIN_DOC[stage]) {
     throw new Error(`register-stage-review: stage 无效 "${stage}"（应为 brainstorm|plan|execute）`)
@@ -486,6 +486,45 @@ export function registerStageReview({ changeName, stage, fromFile, cwd, platform
   }
   const reviewedFiles = [`changes/${changeName}/${mainDoc}`]
 
+  // ── refresh-hash 模式（坑 stage-review-dochash-manual-resync，2026-08-21 实证）：改一版 design
+  // 要重算 2-3 个 stage review 的 docHash（brainstorm/execute 都锚 design.md），手工易漏、gate
+  // 报错才补。就地更新 marker 指向的已有 review.json——保留 verdict/checklist/requiredEvidence
+  // （结论是否仍适用由人确认），仅重算 docHash + reviewerNotes 追加刷新记录；不换 run 目录
+  // （换新 run 会把 marker 重定向到骨架，丢已审结论）。无既有 review → 报错（该用骨架模式生成）。
+  if (refreshHash) {
+    if (fromFile) throw new Error('register-stage-review: --refresh-hash 与 --from 互斥（refresh 就地更新既有 review，adopt 引入新文件）')
+    const existingRunId = getLatestStageReviewRunId(runtimeRoot, stage, changeName)
+    const existingPath = existingRunId
+      ? join(runtimeRoot, 'stage-reviews', `${stage}-${existingRunId}`, 'review.json')
+      : null
+    if (!existingPath || !existsSync(existingPath)) {
+      throw new Error(`register-stage-review: --refresh-hash 找不到 ${stage} 的既有 review.json（marker ${existingRunId || '无'} 无对应 run）——先去掉 --refresh-hash 生成骨架，或派审查子代理产出 review`)
+    }
+    let existing
+    try {
+      existing = JSON.parse(readFileSync(existingPath, 'utf8'))
+    } catch (e) {
+      throw new Error(`register-stage-review: 既有 review.json 解析失败 ${existingPath}: ${e.message}`)
+    }
+    const refreshedAt = new Date().toISOString().slice(0, 19).replace('T', ' ')
+    const review = {
+      ...existing,
+      docHash,
+      reviewedFiles,
+      reviewerNotes: `${existing.reviewerNotes || ''}\ndocHash refreshed at ${refreshedAt}（主文档改版后机械重算；verdict 结论是否仍适用需人工确认）`.trim(),
+    }
+    writeFileSync(existingPath, JSON.stringify(review, null, 2) + '\n')
+    const schemaRecheck = validateStageReviewSchema(review)
+    if (!schemaRecheck.ok) {
+      throw new Error(`register-stage-review: refresh 后 schema 自检失败 — ${schemaRecheck.errors.join('; ')}（原 review 字段异常，先修原文件）`)
+    }
+    const hashRecheck = verifyStageReviewDocHash(review, [specBase, changeDir, cwd])
+    if (!hashRecheck.ok) {
+      throw new Error(`register-stage-review: refresh 后 docHash 自检失败（不应发生）— ${hashRecheck.errors.join('; ')}`)
+    }
+    return { ok: true, reviewRunId: existingRunId, reviewPath: existingPath, markerPath: stageReviewMarkerPath(runtimeRoot, stage, changeName), mode: 'refreshed', mainDoc, review }
+  }
+
   let review
   let mode
   if (fromFile) {

package/src/stages/brainstorm.js

@@ -218,32 +218,44 @@ export const definition = {
       migratedFrom: ['HTML 原型生成'],
       requiresWait: true,
       waitReason: '等待用户确认设计方案',
-      waitOptions: ['确认', '需要修改', '推翻重来'],
-      prompt: `展示完整设计方案供用户确认；如适合可视化，顺带生成 HTML 原型。
+      waitOptions: ['确认', '需要修改', '补原型', '推翻重来'],
+      prompt: `展示完整设计方案供用户确认；涉及 UI 改动时按下方分级决定是否生成 HTML 原型——原型动作必须在暂停之前落定，不能"等确认后再补"。
 
 ### 操作
 1. 简单项目：几句话整体描述
 2. 复杂项目：按模块/Phase 分段展示，每段 200-300 字
 3. 展示完整设计方案（不要逐段停顿，一次性展示）
 4. 确认变更名（格式：\`YYYY-MM-DD-<简短描述>\`，例如 \`2026-05-13-user-auth\`）
-5. 暂停等待用户确认或修改意见
-
-### HTML 原型生成（适合可视化时）
-判断本次设计是否适合生成 HTML 原型：
-- 适合：有 UI 组件/布局/交互流程/状态转换/架构图
-- 不适合：纯后端逻辑/配置修改/无可视化意义
-如果适合，生成一个独立的 HTML 文件（内联 CSS + JS），保存到：
-\`{SPEC_ROOT}/changes/<change-name>/prototype-<名称>.html\`
+5. 按「HTML 原型分级」生成原型或写出跳过原因（二选一必填，见下）
+6. 暂停等待用户确认或修改意见
+
+### HTML 原型分级（按改动程度，不是"是否碰前端文件"）
+判定对象是**改造后的界面相对现状的变化程度**：
+- **必须生成**（布局/结构/流程级变化）：
+  - 新增页面、视图、路由
+  - 页面布局变化：区域增删、骨架重排、信息层级调整（如单栏改多栏、列表改看板）
+  - 新交互流程：多步流程、跨页流转、状态驱动的界面变化
+  - 用户提供了截图/设计稿要求按其改造（原型即对照基准）
+- **建议生成**（组件级变化、页面骨架不变）：
+  - 表单重构、列表列调整、弹窗/抽屉流程等局部组件变化
+  - 拿不准时默认生成——宁多勿漏，原型在 execute 阶段可直接对照复用
+- **跳过**（无需生成，但必须声明原因）：
+  - 文案、颜色、间距、字号、图标等样式微调
+  - 纯后端逻辑/CLI/配置/文档，无任何界面变化
+
+### 生成要求
+生成一个独立的 HTML 文件（内联 CSS + JS），保存到：
+\`{SPEC_ROOT}/changes/<change-name>/prototype-<名称>.html\`（目录不存在则先创建）
 - 单文件，浏览器直接打开
 - 高保真：布局/组件/交互流程按真实效果呈现，后续 execute 阶段可直接对照复用
 - 与项目代码风格一致：优先复用项目现有技术栈/组件库/设计 token（先查 scan 文档与现有前端代码），不另起风格
-展示给用户确认设计方向。不适合则跳过。
 
 ### 铁律 — 必须等待用户确认设计
 - 展示完整设计方案后必须暂停等用户确认，**不要自己说"设计已充分确认"然后推进**（命令由 CLI 在下方注入）
+- 原型生成或跳过声明必须在暂停**之前**完成——暂停是本步骤最后动作，用户确认后直接进入写 design.md，不会回头补
 
 ### 输出
-完整设计方案 + 变更名（+ 原型文件路径，如生成）
+完整设计方案 + 变更名 + 原型文件路径 或 跳过原因（二选一必填；跳过时写明分级依据，用户可当场否决要求补）
 
 ### 注意
 - 不要一次输出大段文字，按模块/Phase 分段
@@ -333,6 +345,7 @@ design.md 第一行标题必须用中文：# 设计文档（Design）— <变更
    - design.md 含「自审」字面命中章节（自审 / Self-Review / Self-review）——「生成规范文件」步完成契约 brainstorm.design.self-review 硬要求，写在本步自审段即可
    - 如存在 decisions.md，design.md 是否引用所有当前版本 D-xxx@vN
    - 涉及 session/lease/agent_run/daemon/lifecycle 等关键词时，是否含「生命周期契约表」
+   - UI 原型核对：文件清单含前端文件（.vue/.tsx/.jsx/.svelte/.html/.css 等）且改动达到「必须生成/建议生成」原型级别（分级见「分段展示设计」步）时，变更目录应已有 \`prototype-*.html\`——没有则本步补生成；确不生成时把跳过原因记入 design.md 风险登记，不得静默缺位
 5. 缺章节 → 补齐后重检；章节齐全 → 进入下一步（Design Grill 做语义层交叉审查）
 
 ### 输出

package/src/stages/doctor.js

@@ -73,16 +73,14 @@ const dir = '.sillyspec/changes';
 const subs = fs.existsSync(dir) ? fs.readdirSync(dir).filter(f => { try { return fs.statSync(dir+'/'+f).isDirectory() && f !== 'archive'; } catch { return false; } }) : [];
 let known;
 try { const db = new DatabaseSync('.sillyspec/.runtime/sillyspec.db', { readOnly: true }); known = new Set(db.prepare(\"SELECT name FROM changes WHERE status='active'\").all().map(r => r.name)); db.close(); } catch (e) { console.log('⚠️ db 读取失败: ' + e.message + '（跳过孤儿判定，不做任何清理建议）'); known = null; }
+// known 为 null（db 不可读）时只列目录不判定孤儿，后续僵尸检查同样跳过——不守卫会 TypeError 半途崩
 if (known) subs.forEach(s => {
   console.log(known.has(s) ? '✅ ' + s + ' — 已关联' : '⚠️ ' + s + ' — 孤儿目录（先 dump 取证再手工归位，勿直接 rm）');
 });
-subs.forEach(s => {
-  console.log(known.has(s) ? '✅ ' + s + ' — 已关联' : '⚠️ ' + s + ' — 孤儿目录（可清理）');
-});
 // 反向检查（multi-agent-review Q1）：DB active 且匹配 quick-<hex> 但无目录 → 僵尸 quick 会话
 // （quick 收尾未注销，active 行累积污染 listChanges/doctor）。新代码已修收尾，此项清理历史残留。
 const QUICK_RE = /^quick-[0-9a-f]{8}$/;
-const zombieQuick = [...known].filter(n => QUICK_RE.test(n) && !subs.includes(n));
+const zombieQuick = known ? [...known].filter(n => QUICK_RE.test(n) && !subs.includes(n)) : [];
 if (zombieQuick.length > 0) {
   console.log('⚠️ 检测到 ' + zombieQuick.length + ' 个僵尸 quick 会话（DB active 但无目录）:');
   zombieQuick.forEach(n => console.log('   - ' + n));

package/src/stages/execute.js

@@ -118,7 +118,8 @@ export function validatePlanForExecute(tasksContent, planContent) {
     if (count > 1) errors.push(`task id 重复: ${id} 在 tasks.md 出现 ${count} 次`)
   }
 
-  // 检查 3: task id 连续性（从 1 开始）
+  // 检查 3: task id 连续性（从 1 开始；ids[0]!==1 时整体跳过 = 兼容旧变更编号不从 1 起，
+  // 契约由 test/plan-execute-contract.test.mjs Case 10 钉死，勿改）
   const ids = allTasks.map(t => t.index).sort((a, b) => a - b)
   if (ids.length > 0 && ids[0] === 1) {
     for (let i = 0; i < ids.length; i++) {
@@ -577,6 +578,10 @@ function writeBaseCommitToTaskCard(taskFilePath, baseCommit) {
   } catch {
     return false
   }
+  // CRLF 归一（坑 base-commit-crlf-frontmatter，plan-postcheck.js 同款）：跨仓 task 卡被
+  // 编辑器/子代理写成 CRLF 后 `^---\n` 匹配失败 → base_commit 锚点静默不落盘，而 Wave
+  // prompt 仍声称「CLI 已落盘」。归一后按 LF 写回（taskcard 生成侧本就强制 LF）。
+  content = content.replace(/\r\n?/g, '\n')
   const fmMatch = content.match(/^---\n([\s\S]*?)\n---/)
   if (!fmMatch) return false
   const fm = fmMatch[1]

package/src/stages/knowledge.js

@@ -276,10 +276,25 @@ export async function cmdRefresh(dir, args, opts = {}) {
   // refresh 只写 generated/ 区
   mkdirSync(generatedDir, { recursive: true })
 
-  // 扫描 scan 文档
+  // 扫描 scan 文档。项目名用 DB 注册名优先（坑 knowledge-basename-project-mismatch）：
+  // scan 写侧 docs/<project> 的 project 来自 dbProjectName || basename(cwd)，注册名 ≠ 目录名
+  // （projects yaml name/path 分离、平台模式 specRoot≠sourceRoot）时，用 basename(dir) 拼
+  // scanDir 永远找不到 → refresh 恒报 scan_docs_missing。DB 读失败回退 basename（与写侧
+  // default 同口径）。查不到注册名对应目录时再回退 basename 试一次（双形态兼容）。
   const base = opts.specDir || join(dir, '.sillyspec')
-  const projectName = basename(dir)
-  const scanDir = join(base, 'docs', projectName, 'scan')
+  let projectName = null
+  try {
+    const { DatabaseSync } = await import('node:sqlite')
+    const db = new DatabaseSync(join(base, '.runtime', 'sillyspec.db'), { readOnly: true })
+    const row = db.prepare('SELECT name FROM project LIMIT 1').get()
+    db.close()
+    if (row && row.name) projectName = row.name
+  } catch { /* db 不可读 → 走 basename 兜底 */ }
+  if (!projectName) projectName = basename(dir)
+  let scanDir = join(base, 'docs', projectName, 'scan')
+  if (!existsSync(scanDir) && projectName !== basename(dir)) {
+    scanDir = join(base, 'docs', basename(dir), 'scan')
+  }
 
   if (!existsSync(scanDir)) {
     output(false, {}, { code: 'scan_docs_missing', path: scanDir })

package/src/stages/plan-postcheck.js

@@ -348,7 +348,10 @@ function parseTaskWavesFromPlan(planPath) {
     // （旧变更读侧兼容——新格式由 validatePlanForExecute 拦旧形态，此处不重复把关）
     const tm = line.match(/^[-*]\s+(?:\[[ x]\]\s*)?(task-\d+)\s*[:：\s]*$/i)
       || line.match(/^[-*]\s*\[[ x]\]\s*(task-\d+)\b/i)
-    if (tm && currentWave !== null) map.set(tm[1], currentWave)
+    // id 归一补零（与卡片/注册表 task-01 口径一致，坑 wave-ref-unpadded）：plan.md 写
+    // `- task-1` 时裸用捕获原文做 key，永远匹配不到卡片 id task-01 → 被判「未列入任何
+    // Wave」，同 Wave 共享文件检测静默跳过。execute.js parseWavesFromPlan 已补零，对齐。
+    if (tm && currentWave !== null) map.set(String(tm[1]).replace(/^task-(\d+)$/i, (_, n) => `task-${n.padStart(2, '0')}`), currentWave)
   }
   return map
 }
@@ -614,16 +617,19 @@ export function parseLocalYamlModules(yamlText) {
   const modules = {}
   for (let i = startIdx + 1; i < lines.length; i++) {
     const line = lines[i]
-    const entry = line.match(/^  ([A-Za-z0-9_.\-]+):\s*(.*)$/)
+    const entry = line.match(/^([ \t]+)([A-Za-z0-9_.\-]+):\s*(.*)$/)
     if (!entry) {
       // 遇到新的顶层 key（行首非空格且非注释）→ modules 块结束
       if (line.length > 0 && !line.startsWith(' ') && !line.startsWith('#') && line.trim() !== '') break
       continue
     }
-    const rest = entry[2] || ''
+    // 条目缩进放宽为「任意非零空白」（坑 modules-indent-hardcoded）：此前硬编码恰 2 空格，
+    // 4 空格/Tab 缩进的条目不匹配且不触发块结束 → 被静默跳过 → modules 丢失 →
+    // validateScriptCommands 退化为只查根 package.json，monorepo 子包命令被误报不存在。
+    const rest = entry[3] || ''
     // path 值：带引号或不带引号（flow mapping），取第一个匹配
     const pathMatch = rest.match(/path:\s*"([^"]+)"/) || rest.match(/path:\s*([^,\s}]+)/)
-    if (pathMatch) modules[entry[1]] = { path: pathMatch[1] }
+    if (pathMatch) modules[entry[2]] = { path: pathMatch[1] }
   }
   return Object.keys(modules).length > 0 ? modules : null
 }
@@ -669,9 +675,14 @@ export function validateTaskCommands(changeDir, projectRoot, modules = null) {
       continue // 非法 YAML 由 feasibility 处理，不重复
     }
 
-    // 合并 verify + implementation 文本（命令可能出现在任一字段）
-    const verifyText = typeof fm.verify === 'string' ? fm.verify : ''
-    const implText = typeof fm.implementation === 'string' ? fm.implementation : ''
+    // 合并 verify + implementation 文本（命令可能出现在任一字段）。
+    // 字段两形态都收（坑 taskcard-block-list-noop）：规范格式（taskcard.js 骨架 / plan 模板）的
+    // verify/implementation 是 YAML 块列表 → js-yaml 解析为数组；此前只收 string，规范卡片
+    // 恒落空 → 「命令存在性校验」（hard-error）对合规 TaskCard 整体 no-op，只有违规写成
+    // 纯标量的卡片才被校验。数组按行 join 回文本，与标量同管道。
+    const toCmdText = (v) => Array.isArray(v) ? v.map(String).join('\n') : (typeof v === 'string' ? v : '')
+    const verifyText = toCmdText(fm.verify)
+    const implText = toCmdText(fm.implementation)
     const text = `${verifyText}\n${implText}`
     if (!text.trim()) continue
 
@@ -1047,8 +1058,10 @@ export function validatePlanFeasibility(changeDir, projectRoot = null) {
   if (allTaskIds.length > 0) {
     const nums = allTaskIds.map(id => {
       const m = id.match(/task-(\d+)/i)
-      return m ? parseInt(m[1]) : null
+      return m ? parseInt(m[1], 10) : null
     }).filter(n => n !== null).sort((a, b) => a - b)
+    // nums[0]!==1 时跳过 = 兼容旧变更编号不从 1 起（契约同 validatePlanForExecute 检查 3，
+    // test/plan-execute-contract.test.mjs Case 10 钉死，勿改）
     if (nums.length > 0 && nums[0] === 1) {
       for (let i = 0; i < nums.length; i++) {
         if (nums[i] !== i + 1) {
@@ -1280,11 +1293,12 @@ export async function executePlanPostcheck(context) {
               currentWaveTasks = null
               continue
             }
-            // 2026-08-20-task-truth-unify：Wave 段下纯 ID 引用行（- task-NN）；旧 checkbox 行同收
+            // 2026-08-20-task-truth-unify：Wave 段下纯 ID 引用行（- task-NN）；旧 checkbox 行同收。
+            // 编号补零对齐卡片口径（坑 wave-ref-unpadded，同 parseTaskWavesFromPlan）
             const tm = line.match(/^[-*]\s+(?:\[[ x]\]\s*)?task-(\d+)\s*[:：\s]*$/i)
               || line.match(/^[-*]\s*\[[ x]\]\s*task-(\d+)/i)
             if (tm && currentWaveTasks) {
-              currentWaveTasks.push(`task-${tm[1]}`)
+              currentWaveTasks.push(`task-${String(tm[1]).padStart(2, '0')}`)
             }
           }
           if (currentWaveTasks) existingWaves.push(currentWaveTasks)

package/src/stages/plan.js

@@ -564,7 +564,9 @@ export const fixedSuffix = [] // postcheck 是动态生成的（需要 changeDir
  */
 function parseTaskCount(registryContent) {
   if (!registryContent || typeof registryContent !== 'string') return 0
-  const matches = registryContent.match(/^[-*]\s*\[[ x]\]\s*task-\d+/gm)
+  // [ xX] + i（坑 taskcount-uppercase-x）：parseTaskNames / gates.js extractTaskIdsFromRegistry
+  // 均收大写 [X]，此处漏收 → 全大写勾选的注册表计数 0 → 误走「无任务」分支丢 coordinator 步
+  const matches = registryContent.match(/^[-*]\s*\[[ xX]\]\s*task-\d+/gim)
   return matches ? matches.length : 0
 }
 
@@ -624,15 +626,18 @@ export function buildPlanSteps(changeDir = null, planContent = null) {
     return [...fixedPrefix, ...postcheck]
   }
 
-  // 解析任务名
+  // 解析任务名（源与计数同口径，坑 plan-tasknames-empty-under-registry-contract）：新契约
+  // （2026-08-20-task-truth-unify）下 plan.md Wave 段是纯 ID 引用行（无 checkbox 无任务名），
+  // 此前只从 planContent/plan.md 解析 → taskNames 恒空 → coordinator 步骤任务清单空白，
+  // 主 agent 只能自行读 tasks.md 兜底易漏派。tasks.md 优先（与 readTaskRegistryContent 同序）。
   let taskNames = []
-  if (planContent) {
-    taskNames = parseTaskNames(planContent)
-  } else if (changeDir) {
-    const planFile = path.join(changeDir, 'plan.md')
-    if (existsSync(planFile)) {
-      taskNames = parseTaskNames(readFileSync(planFile, 'utf8'))
-    }
+  let namesSource = planContent || null
+  if (changeDir) {
+    const registryContent = readTaskRegistryContent(changeDir)
+    if (registryContent != null) namesSource = registryContent
+  }
+  if (namesSource) {
+    taskNames = parseTaskNames(namesSource)
   }
 
   // 生成协调器步骤（TaskCard 生成）+ postcheck

package/src/sync.js

@@ -9,6 +9,7 @@
  */
 
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, unlinkSync, chmodSync } from 'fs';
+import { writeAtomicSync } from './fs-atomic.js';
 import { join } from 'path';
 import { resolvePlatformSpecDir } from './progress.js';
 import { safeGit } from './git-helper.js';
@@ -131,12 +132,14 @@ function replaceTopLevelSection(text, name, body) {
   return `${stripped}\n\n${name}:\n${body}\n`;
 }
 
-/** 文本级写 local.yaml（保留传入 text 的注释/结构）；确保 .sillyspec 目录存在。 */
+/** 文本级写 local.yaml（保留传入 text 的注释/结构）；确保 .sillyspec 目录存在。
+ *  原子写（fs-atomic 契约：local.yaml 被 hook/probe 等其他进程并发读，裸 writeFileSync 的
+ *  写入窗口可读到半截文件 → mcp 段解析失败回退 env → 误判 no-config 降级）。 */
 function writeLocalYamlRaw(cwd, text) {
   const dir = join(cwd, '.sillyspec');
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   const yamlPath = join(cwd, LOCAL_YAML);
-  writeFileSync(yamlPath, text, 'utf8');
+  writeAtomicSync(yamlPath, text, 'utf8');
   // 体检 SEC-04：local.yaml 含明文 token，收紧为仅属主可读写。POSIX chmod 0600 生效；
   // Windows 上 Node chmod 只映射只读位（近似 no-op），属可接受 best-effort
   try { chmodSync(yamlPath, 0o600); } catch { /* chmod 失败不阻断连接流程 */ }
@@ -364,7 +367,7 @@ export class SyncManager {
           // 删段后纯空白（无任何段也无注释）→ 删除整个文件；注释算内容，有注释则保留
           try { unlinkSync(p); } catch { /* best effort */ }
         } else {
-          writeFileSync(p, newText, 'utf8');
+          writeAtomicSync(p, newText, 'utf8');
         }
       }
     }
@@ -609,7 +612,10 @@ export class SyncManager {
       return { synced: 0, errors: ['未指定变更名称'] };
     }
 
-    const changeDir = join(this.cwd, CHANGES_DIR, changeName);
+    // 树根与进度/spec 树同源（safePlatformSpecDir，BUG-01 同族）：此前硬编码 cwd/.sillyspec/changes，
+    // 平台模式（specRoot 指向外部）下路径不存在 → syncDocuments 恒报「变更不存在」且调用方不查
+    // 返回值 → 文档在平台模式下静默永不同步。
+    const changeDir = join(safePlatformSpecDir(this.cwd) || join(this.cwd, '.sillyspec'), 'changes', changeName);
     if (!existsSync(changeDir)) {
       console.warn(`[sync] 变更不存在: ${changeName}`);
       return { synced: 0, errors: [`变更不存在: ${changeName}`] };
@@ -997,7 +1003,10 @@ export class SyncManager {
         const { ProgressManager } = await import('./progress.js');
         const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
         const db = pm._ensureDB(this.cwd).getDb();
-        db.prepare('UPDATE changes SET last_synced_platform_ts = MAX(?, COALESCE(last_synced_platform_ts, ?)) WHERE name = ?')
+        // 参数侧同样 COALESCE（坑 keep-local-base-ts-null-param）：SQLite 标量 MAX() 任一参数
+        // 为 NULL 即返回 NULL——冲突文件 platform_last_pushed_at 为 null 时 MAX(NULL, 旧值)
+        // 会把已回填的 base_ts 清空，恰好违背本注释的单调防回退意图。
+        db.prepare('UPDATE changes SET last_synced_platform_ts = MAX(COALESCE(?, last_synced_platform_ts), COALESCE(last_synced_platform_ts, ?)) WHERE name = ?')
           .run(platformPushedAt, platformPushedAt, changeName);
       } catch (err) {
         return { ok: false, resolved: false, reason: `keep-local 更新 base_ts 失败: ${err.message}` };
@@ -1024,9 +1033,12 @@ export class SyncManager {
     }
 
     if (mode === 'take-platform' && cf) {
-      // 用冲突文件的 platform_progress 调 import 覆盖本地（保隔离：import 不覆盖 isolation_*）
+      // 用冲突文件的 platform_progress 调 import 覆盖本地（保隔离：import 不覆盖 isolation_*）。
+      // fail-closed（坑 take-platform-empty-import）：缺 platform_progress 时必须直接返回——
+      // { ...null } 展开为 {}，import 会照常跑完整事务（DELETE stages 后按空 JSON 重建 =
+      // 清空本地进度），返回值却报 ok:false「未执行」，用户以为无事发生实则数据已丢。
       if (!cf.platform_progress) {
-        progressOutcome = { ok: false, resolved: false, reason: '冲突文件缺 platform_progress，无法 take-platform（建议先 platform pull）' };
+        return { ok: false, resolved: false, reason: '冲突文件缺 platform_progress，无法 take-platform（建议先 platform pull）' };
       }
       try {
         const { ProgressManager } = await import('./progress.js');

package/src/task-review.js

@@ -1023,6 +1023,7 @@ export async function generateTaskReviewDrafts({ changeName, cwd, platformOpts =
   const taskFiles = readdirSync(tasksDir).filter(f => /^task-\d+\.md$/.test(f)).sort()
   let generated = 0
   let skipped = 0
+  let noAttributionCount = 0
   const attributed = new Set()
 
   for (const tf of taskFiles) {
@@ -1081,11 +1082,6 @@ export async function generateTaskReviewDrafts({ changeName, cwd, platformOpts =
         : []
     }
 
-    // 空 changedFiles 的 task 不生成（verifyReviewGitEvidence 判空 diff 伪造，留给 agent 手补）
-    if (taskChangedFiles.length === 0) {
-      skipped++
-      continue
-    }
     // 主仓 task 缺 base/head（meta 缺失 / HEAD 解析失败，见上方 :968-981 注释承诺的"后续跳过"）：
     // 跳过留给 agent 手补。此前 null.slice(0,8) 直接 TypeError 崩掉整个草稿生成（体检 BUG-06）
     if (!crossEntry && (!taskBase || !taskHead)) {
@@ -1097,6 +1093,42 @@ export async function generateTaskReviewDrafts({ changeName, cwd, platformOpts =
       taskChangedFiles.forEach(f => attributed.add(f))
     }
 
+    // 空 changedFiles 的 task 也生成「无归属」草稿（坑 task-review-draft-skip-leak，2026-08-21
+    // 实证：task-08/task-10 两次都因 allowed_paths 未命中 diff 被静默跳过，--done gate 拦截后
+    // agent 只能从零手写 review.json）。cannot_verify 草稿本就待复核（verify 阶段兑现
+    // requiredEvidence），空 changedFiles 不触发 emptyDiff 伪造误判（该判定看真实 git diff 而非
+    // review.changedFiles），shouldAutoCheckTask 零 diff 守卫也保证不会被自动勾选——草稿从
+    // 「漏了让 agent 从零写」变成「给了骨架让 agent 升级 verdict」。
+    if (taskChangedFiles.length === 0) {
+      const draft = {
+        schemaVersion: REVIEW_SCHEMA_VERSION,
+        task: taskId,
+        base: taskBase,
+        head: taskHead,
+        changedFiles: [],
+        specVerdict: 'cannot_verify',
+        qualityVerdict: 'cannot_verify',
+        requiredEvidence: ['auto-generated draft (no-attributed-diff): ' + taskId +
+          ' 的 allowed_paths 未命中本次 diff 任何文件（task 未实现 / 改动与他人同文件 / 路径不匹配）——' +
+          '需人工确认实际改动后升级 verdict，确属未实现则回 fail'],
+        reviewerNotes: 'auto-generated draft from git diff ' + taskBase.slice(0, 8) + '..' + taskHead.slice(0, 8) +
+          ';verdict=未评审（无归属 diff 兜底草稿，坑 task-review-draft-skip-leak）',
+      }
+      if (draftRepo) draft.repo = draftRepo
+      // fail-open（对齐函数头契约 + execute-run-dir-fail-loud 测试锁定的「写失败返回统计不抛」）：
+      // 无归属草稿写入失败（如 tasks/ 被普通文件占位 ENOTDIR）降级 skipped，不崩整个草稿生成
+      try {
+        mkdirSync(reviewDir, { recursive: true })
+        writeFileSync(reviewPath, JSON.stringify(draft, null, 2) + '\n')
+        generated++
+        noAttributionCount++
+      } catch (e) {
+        console.error(`[sillyspec] task ${taskId} 无归属草稿落盘失败（降级留给 agent 手补）: ${e.message}`)
+        skipped++
+      }
+      continue
+    }
+
     const draft = {
       schemaVersion: REVIEW_SCHEMA_VERSION,
       task: taskId,
@@ -1115,7 +1147,7 @@ export async function generateTaskReviewDrafts({ changeName, cwd, platformOpts =
   }
 
   const unattributed = (Array.isArray(diffFiles) ? diffFiles : []).filter(f => !attributed.has(f))
-  return { generated, skipped, unattributed, executeRunId }
+  return { generated, skipped, noAttribution: noAttributionCount, unattributed, executeRunId }
 }
 
 /**