sillyspec 3.26.13 → 3.26.15

package/src/run/command.js

@@ -44,6 +44,8 @@ const VALUE_FLAGS = new Set([
   '--output', '--input', '--change', '--linked-changes',
   '--spec-dir', '--spec-root', '--runtime-root', '--workspace-id', '--scan-run-id',
   '--files', '--file-notes', '--from-step', '--mode', '--dir', '--confirm-mode',
+  '--req', '--cause', '--solution', '--result', // quick 末步四字段参数（合成 --output，见 outputText 解析段）
+  '--ql', // quick --cancel 显式指定 qlId（缺省读会话 guard.json）
   '--base', // scan diff 基线 commit（吃值；只在 run scan --diff 转发路径消费）
 ])
 
@@ -232,6 +234,18 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   const isStatus = flags.includes('--status')
   const isReset = flags.includes('--reset')
   const isReopen = flags.includes('--reopen')
+  // --cancel（2026-08-21 审计第四批 C-2）：quick 误启动会话的官方取消口。取消 = QUICKLOG 条目
+  // 翻「已取消」+ tasks.md 挂载行移除 + 会话 guard 目录清理 + db 行注销（取消 quick 会话行，
+  // 非真实变更）。fail-closed：已完成/已勾选的拒绝（真实工作记录）。
+  const isCancel = flags.includes('--cancel')
+  if (isCancel && stageName !== 'quick') {
+    console.error('❌ --cancel 仅支持 quick 阶段（sillyspec run quick --cancel --change <quick-会话ID>）')
+    process.exit(2)
+  }
+  if (isCancel && (isDone || isSkip || isReset || isReopen || isStatus)) {
+    console.error('❌ --cancel 与 --done/--skip/--reset/--reopen/--status 互斥')
+    process.exit(2)
+  }
   const fromStepValue = getFlagValue('--from-step')
   const isConfirm = flags.includes('--confirm')
   const isSkipApproval = flags.includes('--skip-approval')
@@ -368,8 +382,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 +431,48 @@ 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
+
+  // 解析 quick 末步四字段参数（2026-08-21 agent-手工产出审计第二批 F6）：--req/--cause/
+  // --solution/--result 各传一项，CLI 合成单行四字段 outputText（quicklog 落盘侧
+  // splitSingleLineFields 会归一为多行字段块）。消灭 agent 手拼「需求：… 根因：…」模板的
+  // 格式事故面（嵌套全角冒号拆分误判 / 缺字段被 --done 拒 / 标题截断规则踩坑）。
+  // 任一四参数出现即要求全四；与 --output 互斥（两路同时给说明意图不明，fail-fast）。
+  {
+    const FOUR = [['--req', '需求：'], ['--cause', '根因：'], ['--solution', '方案：'], ['--result', '结果：']]
+    const fourVals = FOUR.map(([f]) => [f, getFlagValue(f)])
+    if (fourVals.some(([, v]) => v !== null)) {
+      if (outputText !== null) {
+        console.error('❌ --req/--cause/--solution/--result 与 --output 互斥——四参数由 CLI 合成结构化 output，勿混用');
+        process.exit(2)
+      }
+      const missing = fourVals.filter(([, v]) => v === null).map(([f]) => f)
+      if (missing.length > 0) {
+        console.error(`❌ quick 末步四字段参数缺项：${missing.join(' ')}（--req/--cause/--solution/--result 必须全给，或缺字段 --done 会被拒）`);
+        process.exit(2)
+      }
+      outputText = FOUR.map(([f, label]) => `${label}${getFlagValue(f)}`).join(' ')
+    }
   }
 
   // 解析 --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 +480,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 +524,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 +586,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)
 
@@ -587,10 +624,11 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
 
   // 未知参数 fail-fast
   const knownFlags = new Set([
-    '--done', '--skip', '--status', '--reset', '--confirm', '--skip-approval',
+    '--done', '--skip', '--status', '--reset', '--confirm', '--skip-approval', '--cancel', '--ql',
     '--wait', '--continue', '--non-interactive', '--interactive',
     '--reason', '--options', '--answer', '--confirm-mode',
     '--output', '--input', '--change', '--linked-changes',
+    '--req', '--cause', '--solution', '--result',
     '--spec-dir', '--spec-root', '--runtime-root', '--workspace-id', '--scan-run-id',
     '--files', '--file-notes', '--allow-new', '--allow-delete', '--force-baseline', '--force-rescan',
     '--json', '--dir', '--help',
@@ -771,16 +809,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)
             }
           }
@@ -825,6 +867,15 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
         changeName = autoName
       } else {
         console.error('❌ 未找到进度数据，请先运行 sillyspec init 或指定 --change <变更名>')
+        // 自愈引导（坑 suggestion-command-missing-change 同族）：多活跃变更仓不带 --change 时
+        // pm.read 无法自动定位（单活跃可自动），列出候选让 agent 一步补对，而非盲猜变更名
+        try {
+          const activeChanges = pm.listChanges(cwd)
+          if (activeChanges.length > 1) {
+            console.error(`   当前有 ${activeChanges.length} 个活跃变更（无法自动定位），请显式指定：`)
+            for (const c of activeChanges) console.error(`   - --change ${c}`)
+          }
+        } catch { /* 列举失败不掩盖原报错 */ }
         process.exit(2) // 环境错（未 init / 未传 --change）→ exit 2
       }
     }
@@ -887,12 +938,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
       }
@@ -937,6 +996,54 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     }
   }
 
+  // ── quick --cancel：误启动会话的取消口（数据源 quicklog.js cancelQuickSession）──
+  // --change 取 quick-<uuid8> 会话 ID（quick 启动时 CLI echo 的 sessionId）；qlId 从会话 guard
+  // 或 --ql 显式参数解析。取消后 db 行注销（quick 会话行非真实变更，直接 unregister 安全）。
+  if (stageName === 'quick' && isCancel) {
+    const cancelSessionRaw = quickSessionId || changeName
+    const qlFlag = getFlagValue('--ql')
+    if (!cancelSessionRaw || cancelSessionRaw === 'quick-unknown') {
+      console.error('用法: sillyspec run quick --cancel --change <quick-会话ID> [--ql <ql-xxx>]\n  取消误启动的 quick 会话：QUICKLOG 条目翻「已取消」+ tasks.md 挂载行移除 + 会话目录清理 + db 行注销。\n  已完成/已勾选的会话拒绝取消（真实工作记录）')
+      process.exit(2)
+    }
+    const specBase = resolveSpecDir(cwd, { specDir })
+    // qlId 优先 --ql 显式；否则读会话 guard.json（allocate 时 CLI 写入）；再退 current marker 旁的会话
+    let qlId = qlFlag
+    if (!qlId) {
+      const guardPath = join(specBase, '.runtime', 'quick-sessions', cancelSessionRaw, 'guard.json')
+      try {
+        if (existsSync(guardPath)) qlId = JSON.parse(readFileSync(guardPath, 'utf8')).qlId
+      } catch { /* guard 损坏 → 下面按找不到报错 */ }
+    }
+    if (!qlId) {
+      console.error(`❌ 无法定位会话 ${cancelSessionRaw} 的 qlId（guard.json 缺失/损坏）——显式传 --ql <ql-xxx>（QUICKLOG 条目头）`)
+      process.exit(1)
+    }
+    let gitUser = 'unknown'
+    try { gitUser = (await import('../git-helper.js')).git(cwd, ['config', 'user.name']) || 'unknown' } catch {}
+    const { cancelQuickSession } = await import('../quicklog.js')
+    let result
+    try {
+      result = await cancelQuickSession({ specBase, gitUser, qlId, sessionId: cancelSessionRaw })
+    } catch (e) {
+      console.error(`❌ 取消失败: ${e.message}`)
+      process.exit(1)
+    }
+    if (!result.ok) {
+      console.error(`❌ 取消失败: ${result.reason}`)
+      process.exit(1)
+    }
+    // db 侧：quick 会话行注销（quick-<uuid8> 是进度库里的会话行，非真实变更目录）
+    try {
+      pm.unregisterChange(cwd, cancelSessionRaw)
+    } catch { /* 行不存在/平台模式 → 会话目录清理已完成，db 无行可注销不算失败 */ }
+    console.log(`🗑️  已取消 quick 会话 ${cancelSessionRaw}（qlId ${qlId}）`)
+    console.log(`   QUICKLOG 条目翻「已取消」: ${result.quicklogFile}`)
+    if (result.removedTaskRows.length > 0) console.log(`   tasks.md 挂载行已移除: ${result.removedTaskRows.join('、')}`)
+    console.log('   会话 guard 目录与 current marker 已清理（已完成条目不会被取消）')
+    return
+  }
+
   // quick 启动（非 --done）：reset steps + 写 current-quick-run-id（本会话 sessionId，作 --done fallback）。
   // sessionId 已在参数解析阶段生成（quickSessionId == changeName == quick-<uuid8>），
   // 这里复用同一值写 current-quick-run-id，保证两处一致。
@@ -1148,15 +1255,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 +1302,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 +1481,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 {}
@@ -278,7 +283,10 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase, platfo
     const alreadyArchivedDir = findAlreadyArchivedDir(archiveDir, archiveChangeName)
     if (alreadyArchivedDir) {
       console.log(`ℹ️  源目录不存在但变更已在 archive/（${basename(alreadyArchivedDir)}），判定已归档，自愈进度 DB`)
-      pm.unregisterChange(cwd, archiveChangeName)
+      // 终态一致化（坑 manual-archive-desync-status-only）：手动搬目录绕过标准归档后，本自愈路径
+      // 不能只翻 status——同时收尾 archive 阶段（steps/stages/current_stage），否则推送平台的终态
+      // 是「已归档 + 归档 0/5 + 停在 execute」的矛盾体，详情页渲染成「进度丢失」
+      pm.unregisterChange(cwd, archiveChangeName, { archiveStepNames: typeof pm.archiveStepNamesForArchive === 'function' ? pm.archiveStepNamesForArchive() : null })
       await archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts)
       console.log(`📦 已自愈归档：${archiveChangeName} → archive/${basename(alreadyArchivedDir)}/`)
       return alreadyArchivedDir
@@ -327,7 +335,9 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase, platfo
     process.exit(1)
   }
 
-  pm.unregisterChange(cwd, archiveChangeName)
+  // 正常路径同样走终态一致化（坑 manual-archive-desync-status-only）：标准 --done --confirm 流程
+  // 中 completeStep 随后也会逐项完成，此处先收尾是幂等写同值——保证任何走出本函数的归档终态一致
+  pm.unregisterChange(cwd, archiveChangeName, { archiveStepNames: typeof pm.archiveStepNamesForArchive === 'function' ? pm.archiveStepNamesForArchive() : null })
 
   // CLI 下沉 git add（坑4，FR-04）：确定性暂存归档目录 + 模块文档，不靠 step5 prompt 驱动。
   // step5 prompt 的 git add 保留作幂等兜底；POSIX 路径跨平台（git 接受正斜杠）。
@@ -338,6 +348,53 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase, platfo
     safeGit(cwd, ['add', '--', '.sillyspec/docs/'])
   } catch {}
 
+  // ── 他者半归档残留探测（坑 archive-other-residual-rename，2026-08-21 实证）──
+  // 并行变更的手动归档把 R 残留（源目录 rename 目标行）留在暂存区；本变更归档提交时
+  // git status 显示它们，agent 会误判「还没提交完 / 要做第二次提交」。区分：
+  //   本变更：未暂存的源侧移动（` D changes/<me>/...` + 未跟踪 archive/<me>/...）→ 补暂存
+  //           让归档成单次原子提交；
+  //   他者：已暂存的 rename（`R  changes/<他人>/... -> changes/archive/<他人>/...`）→ 只 warn
+  //         提示归属（不 stage 不动——别人的归别人的）。
+  try {
+    const raw = gitQuiet(cwd, ['status', '--porcelain'], { trim: false, timeout: 30000 })
+    if (raw && raw.trim()) {
+      const changesPrefix = '.sillyspec/changes/'
+      const minePaths = []
+      const othersResidual = []
+      for (const line of raw.split('\n')) {
+        if (!line || line.length < 4) continue
+        const x = line[0], y = line[1]
+        const body = line.slice(3).trim()
+        const arrow = body.indexOf(' -> ')
+        const src = arrow !== -1 ? body.slice(0, arrow).replace(/^"|"$/g, '') : null
+        const dst = (arrow !== -1 ? body.slice(arrow + 4) : body).replace(/^"|"$/g, '')
+        if (x === 'R' && y === ' ' && arrow !== -1 && dst.startsWith(changesPrefix + 'archive/')) {
+          // 已暂存 rename → 半归档残留；按目标目录名归属他者变更
+          const m = /^\.sillyspec\/changes\/archive\/([^/]+)\//.exec(dst)
+          const owner = m ? m[1] : '?'
+          if (owner !== archiveChangeName) othersResidual.push(owner)
+        } else if (x === ' ' && (y === 'D' || y === 'A' || y === 'M')) {
+          // 未暂存的源侧移动：源目录 D / 新位置 A——指向本变更的补暂存
+          const p = dst || src
+          if (p && (p.startsWith(changesPrefix + archiveChangeName + '/')
+                    || p.startsWith(changesPrefix + 'archive/' + archiveChangeName + '/'))) {
+            minePaths.push(p)
+          }
+        }
+      }
+      if (minePaths.length > 0) {
+        try { safeGit(cwd, ['add', '-A', '--', changesPrefix]) } catch {}
+        console.log(`🧾 已补暂存本变更归档的源侧移动（${minePaths.length} 项，归档成单次原子提交）`)
+      }
+      if (othersResidual.length > 0) {
+        const owners = [...new Set(othersResidual)].filter(Boolean)
+        console.warn(`⚠️  检测到「他者半归档」残留（暂存区存在其他变更的 rename 记录）：${owners.join('、')}`)
+        console.warn(`   这些是别的变更此前手动归档留下的暂存项，不属于本次归档——git status 里看到它们是正常的，`)
+        console.warn(`   本变更归档已完成，无需为其做第二次提交；如需清理走它们自己的收尾（或 git restore --staged 后核对）。`)
+      }
+    }
+  } catch { /* 探测失败不阻断归档（advisory） */ }
+
   // 归档时清理可能残留的 worktree（自愈路径也复用，见上方 srcDir 缺失分支）。
   await archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts)
 
@@ -1032,7 +1089,8 @@ async function closeSingleQuickLinkedChange({ pm, cwd, specBase, changeName, pla
     return { closed: false, reason: `移动目录失败：${e.message}` }
   }
 
-  pm.unregisterChange(cwd, changeName)
+  // 终态一致化同标准归档（坑 manual-archive-desync-status-only）：轻量归档路径不能只翻 status
+  pm.unregisterChange(cwd, changeName, { archiveStepNames: typeof pm.archiveStepNamesForArchive === 'function' ? pm.archiveStepNamesForArchive() : null })
   await archiveWorktreeCleanup(cwd, changeName, specBase, platformOpts)
   safeGit(cwd, ['add', '--', `.sillyspec/changes/archive/${destName}/`])
 

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(', '))
         }
@@ -451,7 +456,7 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
         console.log(`\n${summary}`)
       } catch (e) {
         // summary 失败不影响主流程
-        console.log('\n👉 下一步：sillyspec run verify（验证通过后才能归档）')
+        console.log(`\n👉 下一步：sillyspec run verify${changeName ? ` --change ${changeName}` : ''}（验证通过后才能归档）`)
       }
     } else if (stageName === 'archive') {
       console.log('\n👉 归档完成！现在可以提交了：git commit -m "..."')
@@ -529,12 +534,9 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     // 易被 tail 截断），agent 常到 --done 被拦才第一次见到模板。推进到末步的此刻用底部短块预告
     // 模板 + 可照抄命令，省一轮拦截往返（拦截路径保留兜底）。
     if (stageName === 'quick' && nextPendingIdx === steps.length - 1) {
-      console.log(`\n📌 本步是 quick 末步：--done 的 --output 必须含四字段（CLI 硬校验，缺任一项会被拒、补全重跑不丢进度）。预告模板：`)
-      console.log(`   sillyspec run quick --done${changeName ? ` --change ${changeName}` : ''} --output "需求：一句话语义化短标题（即 QUICKLOG 条目标题）`)
-      console.log(`   根因：为什么这样改（纯新增/样式则写「无，纯新增/纯样式」）`)
-      console.log(`   方案：怎么改的`)
-      console.log(`   结果：验证情况（测试数 / lint / typecheck / 部署状态）"`)
-      console.log(`   四字段逐项一句话、不可「见前述」；可选 --file-notes "path::括注 || path2" 落多行文件括注`)
+      console.log(`\n📌 本步是 quick 末步：--done 必须给全四字段（CLI 硬校验，缺任一项会被拒、补全重跑不丢进度）。推荐四参数形式（CLI 自动合成，无格式事故面）：`)
+      console.log(`   sillyspec run quick --done${changeName ? ` --change ${changeName}` : ''} --req "一句话语义化短标题（即 QUICKLOG 条目标题）" --cause "为什么这样改（纯新增/样式则写「无，纯新增/纯样式」）" --solution "怎么改的" --result "验证情况（测试数 / lint / typecheck / 部署状态）"`)
+      console.log(`   兼容旧形式：--output "需求：… 根因：… 方案：… 结果：…"（四字段逐项一句话、不可「见前述」，正文内禁嵌套全角冒号）；可选 --file-notes "path::括注 || path2" 落多行文件括注`)
     }
   }
   return { stageCompleted: false, currentIdx, nextPendingIdx }

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

@@ -65,9 +65,43 @@ 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
+  const lines = [
+    '# 符号影响面报告',
+    '',
+    '> 骨架由 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（进度不推进）。非目标步骤/阶段直接放行。
@@ -88,10 +122,42 @@ 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 {
+        writeFileSync(reportPath, skeleton)
+        skeletonNote = `\n   📄 已代生成逐 task 骨架：${reportPath}（逐行替换 <!--TODO--> 为结论，无签名级变更也显式写「无」）`
+      } catch { /* 写失败只影响提示，不掩盖原始错误 */ }
+    }
+  }
+  console.error(`   修复：按「加载上下文」步操作 11 完成符号影响面扫描，逐 task 写结论后重跑 execute --done。${skeletonNote}`)
   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（保守过门）。
@@ -175,7 +241,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) {
@@ -272,6 +338,18 @@ export async function enforceDepsGate(stageName, cwd, changeName, step, steps, c
  */
 export async function enforceReviewJsonGate(stageName, cwd, changeName, step, steps, currentIdx, specBase, platformOpts) {
   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')
@@ -320,7 +398,7 @@ 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。')
   process.exit(1)
 }
 
@@ -511,7 +589,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)
         }
@@ -854,6 +932,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)
   }