sillyspec 3.26.14 → 3.27.1

package/src/progress/stage-machine.js

@@ -282,13 +282,18 @@ export class StageMachine {
    * @returns {{ text: string, command?: string }|null}
    */
   _getNextSuggestion(data) {
+    // 建议命令携带 --change（坑 suggestion-command-missing-change，2026-08-21 实证）：
+    // 多活跃变更仓 pm.read(cwd, null) 无法自动定位变更 → 照抄建议命令（不带 --change）执行
+    // 报「未找到进度数据」，阶段完结后的 --wait 确认门也登记不上。progress 带 currentChange
+    // 时附加；无（测试 fixture / 旧数据）保持裸命令（存量断言零回归）。
+    const cc = data.currentChange ? ` --change ${data.currentChange}` : '';
     // 找到第一个 revising 阶段
     const revisingStage = STAGE_ORDER.find(s => data.stages[s]?.status === 'revising');
     if (revisingStage) {
       const sd = data.stages[revisingStage];
       return {
         text: `${STAGE_LABELS[revisingStage] || revisingStage} 正在修订中（revision ${sd.revision || 1}），请继续完成修订。`,
-        command: `sillyspec run ${revisingStage}`,
+        command: `sillyspec run ${revisingStage}${cc}`,
       };
     }
 
@@ -298,7 +303,7 @@ export class StageMachine {
       const sd = data.stages[staleStage];
       return {
         text: `${STAGE_LABELS[staleStage] || staleStage} 已失效（${sd.staleReason || '上游修订'}），需要从第一步重建。`,
-        command: `sillyspec run ${staleStage} --reopen --from-step 1`,
+        command: `sillyspec run ${staleStage} --reopen --from-step 1${cc}`,
       };
     }
 
@@ -318,14 +323,14 @@ export class StageMachine {
           const ws = sd.steps[waitIdx];
           return {
             text: `${STAGE_LABELS[s] || s} 进行中，Step ${waitIdx + 1}「${ws.name}」等待用户输入${ws.waitReason ? `（${ws.waitReason}）` : ''}，用 --answer 恢复。`,
-            command: `sillyspec run ${s} --continue --answer "用户回答"`,
+            command: `sillyspec run ${s} --continue --answer "用户回答"${cc}`,
           };
         }
         const hasPending = sd.steps.some(st => ['pending', 'waiting', 'failed'].includes(st.status));
         if (hasPending) {
           return {
             text: `${STAGE_LABELS[s] || s} 进行中，继续执行下一步。`,
-            command: `sillyspec run ${s}`,
+            command: `sillyspec run ${s}${cc}`,
           };
         }
       }
@@ -349,7 +354,7 @@ export class StageMachine {
       if (upstreamOk) {
         return {
           text: `可以开始 ${STAGE_LABELS[s] || s}。`,
-          command: `sillyspec run ${s}`,
+          command: `sillyspec run ${s}${cc}`,
         };
       }
     }

package/src/progress/step-store.js

@@ -88,16 +88,16 @@ export class StepStore {
     }
     const stageId = stageRow.id;
 
-    // 重复步骤名检查
-    const dupRow = sqlDb.prepare('SELECT id FROM steps WHERE stage_id = ? AND name = ?').get(stageId, stepName);
-    if (dupRow !== undefined) {
-      console.log(`ℹ️  步骤 "${stepName}" 已存在于 ${stage}`);
-      return;
-    }
-
-    // INSERT INTO steps（ordering 递增）
+    // 重复步骤名检查 + INSERT 同事务（2026-08-21 审查 BUG-8）：查重在事务外时，
+    // 并发 add-step 同名可双双通过检查双插（steps 无 UNIQUE 约束），另一份 status 后续被 _write 覆盖丢失
+    let dupFound = false;
     db.transaction(() => {
       const tDb = db.getDb();
+      const dupRow = tDb.prepare('SELECT id FROM steps WHERE stage_id = ? AND name = ?').get(stageId, stepName);
+      if (dupRow !== undefined) {
+        dupFound = true;
+        return;
+      }
       tDb.prepare(
         `INSERT INTO steps (stage_id, name, ordering, status)
          VALUES (?, ?, (SELECT COALESCE(MAX(ordering), 0) + 1 FROM steps WHERE stage_id = ?), 'pending')`
@@ -106,6 +106,10 @@ export class StepStore {
       // 本地脏度（D-013 / task-04）：添加步骤是本地推进
       this.pm._touchLocalModified(cwd, cn);
     });
+    if (dupFound) {
+      console.log(`ℹ️  步骤 "${stepName}" 已存在于 ${stage}`);
+      return;
+    }
 
     console.log(`✅ 已添加步骤: ${stage}/${stepName}`);
   }

package/src/progress.js

@@ -13,12 +13,14 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, appendFileSync, copyFileSync, readdirSync, statSync } from 'fs';
 import { join, basename, dirname, resolve, sep } from 'path';
 import { tmpdir } from 'os';
+import { writeAtomicSync } from './fs-atomic.js';
 import { DB } from './db.js';
 import { checkExecuteCodeEvidence } from './stage-contract.js';
 import { ConsistencyDoctor } from './progress/consistency-doctor.js';
 import { ChangeRegistry } from './progress/change-registry.js';
 import { StepStore } from './progress/step-store.js';
 import { StageMachine } from './progress/stage-machine.js';
+import { stageRegistry } from './stages/index.js';
 import { STAGE_ORDER, MAIN_FLOW_ORDER, VALID_STAGES, STAGE_LABELS, SPEC_DIR_NAME, CURRENT_VERSION, emptyStage } from './progress/shared.js';
 // resolveSpecDir 单一真相源在 src/run/shared.js（含 home 拒绝守卫，坑 cwd-correction-home-collision
 // 根治：home 下 .sillyspec 恒不命中，防 smoke/临时目录污染自我延续）。此处 re-export 保持
@@ -812,7 +814,18 @@ export class ProgressManager {
 
   renameChange(cwd, oldName, newName) { return this._changeRegistry.renameChange(cwd, oldName, newName); }
 
-  unregisterChange(cwd, changeName) { return this._changeRegistry.unregisterChange(cwd, changeName); }
+  // opts.archiveStepNames 给定时做归档终态一致化收尾（见 change-registry.unregisterChange 注释，
+  // 坑 manual-archive-desync-status-only）；archiveStepNamesForArchive() 取 stageRegistry 单一真相
+  //（stages/* 不反向依赖 progress.js，静态 import 无环）。
+  unregisterChange(cwd, changeName, opts) { return this._changeRegistry.unregisterChange(cwd, changeName, opts); }
+
+  archiveStepNamesForArchive() {
+    if (!this._archiveStepNamesCache) {
+      const defs = stageRegistry?.archive?.steps
+      this._archiveStepNamesCache = Array.isArray(defs) ? defs.map(s => s.name) : []
+    }
+    return this._archiveStepNamesCache
+  }
 
   updateChangeMeta(cwd, changeName, meta) { return this._changeRegistry.updateChangeMeta(cwd, changeName, meta); }
 
@@ -1003,9 +1016,12 @@ export class ProgressManager {
     if (existsSync(gitignorePath)) {
       const content = readFileSync(gitignorePath, 'utf8');
       if (content.includes(rule)) return;
-      writeFileSync(gitignorePath, content.trimEnd() + '\n' + rule + '\n');
+      // 按既有 EOL 追加（2026-08-21 审查 BUG-9）：CRLF 检出的文件混入 LF 行产生全文件
+      // diff 噪声/autocrlf 折腾；写走原子 rename 防并发 init 双跑交错
+      const eol = content.includes('\r\n') ? '\r\n' : '\n';
+      writeAtomicSync(gitignorePath, content.trimEnd() + eol + rule + eol);
     } else {
-      writeFileSync(gitignorePath, rule + '\n');
+      writeAtomicSync(gitignorePath, rule + '\n');
     }
   }
 

package/src/quicklog.js

@@ -14,7 +14,7 @@ import { join, dirname, basename } from 'path'
 import { getRule } from './stage-contract-spec.js'
 import {
   openSync, closeSync, unlinkSync, statSync, mkdirSync, existsSync,
-  readFileSync, writeFileSync, writeSync, readdirSync, renameSync, appendFileSync,
+  readFileSync, writeFileSync, writeSync, readdirSync, renameSync, appendFileSync, rmSync,
 } from 'fs'
 import { randomBytes } from 'crypto'
 
@@ -722,3 +722,108 @@ export function findQuicklogEntry(specBase, gitUser, qlId) {
   }
   return false
 }
+
+/**
+ * 取消一个 quick 会话（2026-08-21 agent-手工产出审计第四批 C-2，`run quick --cancel` 数据源）。
+ *
+ * 误启动/放弃的 quick 会话此前无取消出口：QUICKLOG「进行中」条目 + 关联变更 tasks.md 挂载行
+ * + .runtime/quick-sessions/<id>/ 永久残留，doctor --cleanup-ghosts 只清 db 幽灵行不清这三处。
+ * 本函数做 allocateQuicklogEntry 的反操作（三步全是已有函数的反面）：
+ *   1. QUICKLOG 条目状态翻「已取消」（非删除——保留痕迹可审计，与 doctor 宁漏勿杀口径一致）
+ *   2. tasks.md 里该 qlId 的挂载行整行移除（未勾的空壳行，勾了说明实际做了工作 → 拒绝取消）
+ *   3. 会话 guard 目录删除（quick-sessions/<sessionId>/，含 guard.json）
+ *   4. current-quick-run-id 若指向本会话则删除（防后续 --done fallback 命中死会话）
+ * db 侧 change 行由调用方 unregisterChange（quick 会话行，非真实变更）。
+ *
+ * fail-closed：已翻「已完成」的条目拒绝取消（那是真实工作）；tasks.md 挂载行已勾选同样拒绝。
+ *
+ * @param {{ specBase: string, gitUser: string, qlId: string, sessionId: string|null }} opts
+ * @returns {Promise<{ ok: boolean, reason?: string, quicklogFile?: string, removedTaskRows: string[] }>}
+ */
+export async function cancelQuickSession({ specBase, gitUser, qlId, sessionId = null }) {
+  if (!qlId) return { ok: false, reason: '缺 qlId（--change <quick-会话ID> 或 --ql <ql-xxx>）' }
+  const quicklogDir = join(specBase, 'quicklog')
+  const user = sanitizeQuicklogUser(gitUser) || 'unknown'
+  const lockPath = join(quicklogDir, `.QUICKLOG-${user}.md.lock`)
+
+  // 1. QUICKLOG 翻「已取消」：找到条目，校验未完成，就地改状态行
+  let quicklogFile = null
+  let flipped = false
+  await withFileLock(lockPath, async () => {
+    // 用户文件缺失时扫全部 QUICKLOG 文件（条目可能在别的 user 文件里，如 CI 场景 user 漂移）
+    const files = existsSync(join(quicklogDir, `QUICKLOG-${user}.md`))
+      ? [`QUICKLOG-${user}.md`]
+      : listQuicklogFiles(quicklogDir)
+    for (const f of files) {
+      const p = join(quicklogDir, f)
+      const content = existsSync(p) ? readFileSync(p, 'utf8') : ''
+      if (!content.includes(`## ${qlId} |`)) continue
+      quicklogFile = p
+      const lines = content.split('\n')
+      const startIdx = lines.findIndex(l => l.startsWith(`## ${qlId} |`))
+      let endIdx = lines.length
+      for (let i = startIdx + 1; i < lines.length; i++) {
+        if (lines[i].startsWith('## ')) { endIdx = i; break }
+      }
+      for (let i = startIdx + 1; i < endIdx; i++) {
+        if (/^状态：已完成/.test(lines[i])) {
+          throw new Error(`${qlId} 已完成（真实工作记录），拒绝取消；如需修正请手改 QUICKLOG`)
+        }
+      }
+      for (let i = startIdx + 1; i < endIdx; i++) {
+        if (/^状态：进行中/.test(lines[i])) {
+          lines[i] = '状态：已取消'
+          flipped = true
+          break
+        }
+      }
+      if (flipped) {
+        const eol = content.includes('\r\n') ? '\r\n' : '\n'
+        writeFileSync(p, lines.join(eol === '\r\n' ? '\r\n' : '\n'))
+      }
+      break
+    }
+  })
+  if (!quicklogFile) return { ok: false, reason: `未在任何 QUICKLOG 文件找到条目 ${qlId}` }
+  if (!flipped) return { ok: false, reason: `${qlId} 状态行异常（非进行中也非已完成），请手查 QUICKLOG` }
+
+  // 2. tasks.md 挂载行移除（所有活跃变更统一扫——allocate 时可能挂多个关联变更）
+  const removedTaskRows = []
+  const changesRoot = join(specBase, 'changes')
+  if (existsSync(changesRoot)) {
+    for (const c of readdirSync(changesRoot, { withFileTypes: true })) {
+      if (!c.isDirectory() || c.name === 'archive') continue
+      const tp = tasksPath(specBase, c.name)
+      if (!existsSync(tp)) continue
+      await withFileLock(tasksLockPath(tp), () => {
+        const content = readFileSync(tp, 'utf8')
+        if (!content.includes(qlId)) return
+        const lines = content.split('\n')
+        const kept = lines.filter(l => {
+          const m = l.match(/^[-*]\s*\[([ xX])\]\s*(\S+)/)
+          if (m && m[2] === qlId) {
+            if (m[1] !== ' ') throw new Error(`${c.name}/tasks.md 的 ${qlId} 行已勾选（实际做了工作），拒绝取消`)
+            removedTaskRows.push(`${c.name}/tasks.md`)
+            return false
+          }
+          return true
+        })
+        if (kept.length !== lines.length) {
+          const eol = content.includes('\r\n') ? '\r\n' : '\n'
+          writeFileSync(tp, kept.join(eol === '\r\n' ? '\r\n' : '\n'))
+        }
+      })
+    }
+  }
+
+  // 3+4. 会话目录与 current marker
+  if (sessionId) {
+    try { rmSync(join(specBase, '.runtime', 'quick-sessions', sessionId), { recursive: true, force: true }) } catch {}
+    const marker = join(specBase, '.runtime', 'current-quick-run-id')
+    try {
+      if (existsSync(marker) && readFileSync(marker, 'utf8').trim() === sessionId) unlinkSync(marker)
+    } catch {}
+  }
+
+  return { ok: true, quicklogFile, removedTaskRows }
+}

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')
@@ -425,6 +439,28 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   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 inputValue = getFlagValue('--input')
@@ -588,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',
@@ -830,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
       }
     }
@@ -950,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，保证两处一致。

package/src/run/complete-handlers.js

@@ -127,7 +127,7 @@ export function findAlreadyArchivedDir(archiveDir, changeName) {
  * 见 stage.js execute 启动固定 executeRunId / stage-review.js stageReviewMarkerPath）。
  * 从 archiveChangeDirectory 抽出，供正常归档 + 自愈归档复用。
  */
-async function archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts = {}) {
+export async function archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts = {}) {
   // ── 清理 runId marker：execute（current-execute-run-id-<change>）与 stage-review
   //    （current-stage-review-run-id-<stage>-<change>）。marker 只服务 execute→verify→archive
   //    期间，归档后无读者；不删则 .runtime 随变更数无限累积。runtimeRoot 解析同写入侧
@@ -158,7 +158,17 @@ async function archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platform
     const { WorktreeManager } = await import('../worktree.js')
     const wm = new WorktreeManager({ cwd })
     const meta = wm.getMeta(archiveChangeName)
-    if (!meta) return
+    if (!meta) {
+      // 无 meta 兜底（坑 archive-cleanup-orphan-physical-dir，2026-08-21 实证）：meta 已被先行
+      // 流程注销（apply 自动 cleanup / doctor 幽灵清理）时此前直接 return——若物理目录因中途
+      // 失败残留下就是孤儿（无 meta=无锚定基准，残留即孤儿）。force 清理（幂等：什么都不存在
+      // 时 cleanup 返回 skipped 零副作用）。
+      const orphan = wm.cleanup(archiveChangeName, { force: true })
+      if (orphan.result === 'cleaned' || orphan.result === 'force-cleaned' || orphan.result === 'partial') {
+        console.log(`🧹 归档清理孤儿 worktree 残留（meta 已注销）: ${archiveChangeName}${orphan.residual?.length ? '（残留: ' + orphan.residual.join('; ') + '）' : ''}`)
+      }
+      return
+    }
     const check = meta.mode !== 'in-place-fallback' ? wm.hasUnappliedChanges(archiveChangeName) : { hasChanges: false }
     if (check.hasChanges) {
       console.warn(`⚠️  归档时 worktree 仍有 ${check.changedFiles.length} 个未 apply 变更，保留 worktree`)
@@ -283,7 +293,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
@@ -332,7 +345,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 接受正斜杠）。
@@ -343,6 +358,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)
 
@@ -371,6 +433,11 @@ export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, c
   }
   const archivedDir = await archiveChangeDirectory(pm, cwd, progress, specBase, platformOpts)
   if (archivedDir && existsSync(archivedDir)) {
+    // 内存快照同步（坑 archive-progress-show-stale，2026-08-21 实证）：archiveChangeDirectory 内
+    // unregisterChange 已在 DB 写 current_stage='archive'（终态一致化），但本进程 progress 是命令
+    // 开始时读的旧快照——不同步的话，completeStep 后续 _write 会用旧值（如停在 verify）把
+    // DB 覆盖回去，progress show 就一直显示归档前的阶段
+    progress.currentStage = 'archive'
     const recommendedDocs = ['design.md', 'module-impact.md']
     const missingRecommended = recommendedDocs.filter(d => !existsSync(join(archivedDir, d)))
     if (missingRecommended.length > 0) {
@@ -1037,7 +1104,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

@@ -222,10 +222,13 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   }
 
   // ── execute deps 验证硬门（change 2026-06-28-worktree-deps-provision）──
-  await enforceDepsGate(stageName, cwd, changeName, steps[currentIdx], steps, currentIdx, specBase, platformOpts)
+  // persist 回调：gate 置 step=blocked 后 exit(1) 前落库（否则 blocked 只在内存，
+  // progress show/doctor 看到的仍是 pending，误导诊断）
+  const persistBlocked = () => pm._write(cwd, progress, changeName)
+  await enforceDepsGate(stageName, cwd, changeName, steps[currentIdx], steps, currentIdx, specBase, platformOpts, persistBlocked)
   // review.json 字段硬门（坑 review-json-field-gap）：已勾 [x] task 的 review.json 必须 schema 完整，
   // 提前到每次 --done 校验（而非等 Task Review Gate 在整阶段收尾才暴露，迫使用户事后批量补）。
-  await enforceReviewJsonGate(stageName, cwd, changeName, steps[currentIdx], steps, currentIdx, specBase, platformOpts)
+  await enforceReviewJsonGate(stageName, cwd, changeName, steps[currentIdx], steps, currentIdx, specBase, platformOpts, persistBlocked)
   // 符号影响面报告硬门（ql-20260816-005-3d7f）：execute「加载上下文」步产出落盘核验——
   // symbol-impact.md 存在 + plan 每 task 有结论行；防前缀步被一句「上下文在会话内」盖章跳过。
   await enforceSymbolImpactGate(stageName, changeName, steps[currentIdx]?.name, specBase)
@@ -456,7 +459,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 "..."')
@@ -534,12 +537,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 }
@@ -597,6 +597,22 @@ async function buildDraftContext(cwd, changeName) {
   }
 }
 
+/**
+ * 预取 base..head 全量 diff 文件集（一次 git spawn），供草稿零 diff 守卫按 task 内存归属判定。
+ * 此前每草稿 task 一次 `git diff --name-only base..head -- <files>`（同一对 base..head 查 N 次，
+ * 8 task ≈ 8-16 次串行 spawn）。失败返回 null → 调用方回退逐 task 实测路径。
+ */
+function prefetchDiffFileSet(ctx) {
+  if (!ctx?.gitDir || !ctx.base || !ctx.head) return ctx
+  try {
+    const out = gitQuiet(ctx.gitDir, ['diff', '--name-only', `${ctx.base}..${ctx.head}`], { trim: true })
+    if (!out) return ctx
+    return { ...ctx, diffFileSet: new Set(out.split('\n').filter(Boolean)) }
+  } catch {
+    return ctx
+  }
+}
+
 /**
  * 判定 task 是否该被 autoCheckPlanFromReviews 自动勾选。
  * 端到端/deployment-critical task 要求 review spec+quality 双 pass（cannot_verify 不算，防批量完成
@@ -631,6 +647,16 @@ export function shouldAutoCheckTask(r, endToEnd, ctx = null) {
       console.warn(`⚠️ ctx 信息不完整（gitDir=${ctx.gitDir}, base=${ctx.base}, head=${ctx.head}），跳过草稿 diff 校验，保守不勾`)
       return false
     }
+    // 预取路径：一次全量 diff 文件集内存归属（autoCheckPlanFromReviews/批量路径已 prefetch）
+    if (ctx.diffFileSet) {
+      const hit = changedFiles.filter(f => ctx.diffFileSet.has(f))
+      if (hit.length === 0) {
+        console.warn(`⚠️ 草稿 review 实测 diff 为空（base=${ctx.base.slice(0, 8)}, head=${ctx.head.slice(0, 8)}, files=${changedFiles.length}），跳过自动勾选`)
+        return false
+      }
+      console.log(`   ✓ 草稿 diff 校验通过（实测 ${hit.length}/${changedFiles.length} 个声明文件有改动）`)
+      return true
+    }
     try {
       // 实测 diff：git diff --name-only <base>..<head> -- <changedFiles>
       // 用数组参数避免 shell 拆词，复用 git-helper 安全模式
@@ -673,7 +699,7 @@ async function autoCheckPlanFromReviews({ stageName, changeName, cwd, platformOp
     const executeRunId = c
 
     // W2 task-04 FR-03：构造 ctx 供草稿零 diff 守卫用（与 task-review.js generateTaskReviewDrafts 同源）
-    const ctx = await buildDraftContext(cwd, changeName)
+    const ctx = prefetchDiffFileSet(await buildDraftContext(cwd, changeName))
 
     // tasks.md 是 agent 与 CLI 都会写的共享文件（agent 勾 checkbox、此处 autoCheck 也勾选）。
     // 读-改-写必须整体持锁（withFileLock 串行化多进程），否则并发 execute --done / 手动勾选互相覆盖
@@ -751,7 +777,7 @@ async function detectExecuteBatchFinish({ pm, stageName, changeName, cwd, specBa
     }
 
     // 构造 ctx 供草稿零 diff 校验用（与 task-04 同源）
-    const ctx = await buildDraftContext(cwd, changeName)
+    const ctx = prefetchDiffFileSet(await buildDraftContext(cwd, changeName))
     const runtimeRoot = resolveRuntimeRoot({ specRoot: specBase }, specBase)
     const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
     const blockedTasks = []
@@ -786,11 +812,18 @@ async function detectExecuteBatchFinish({ pm, stageName, changeName, cwd, specBa
           blockedTasks.push(taskId)
           continue
         }
-        // 草稿且有 changedFiles → 实测 diff 校验（ctx 与 task-04 同源）
+        // 草稿且有 changedFiles → 实测 diff 校验（ctx 与 task-04 同源；优先用预取全量集，
+        // 免去每 task 一次 spawn——与 shouldAutoCheckTask 同口径）
         if (ctx && ctx.gitDir && ctx.base && ctx.head) {
           try {
-            const diffResult = gitQuiet(ctx.gitDir, ['diff', '--name-only', `${ctx.base}..${ctx.head}`, '--', ...changedFiles], { trim: true })
-            if (!diffResult || diffResult.trim() === '') {
+            let hit = null
+            if (ctx.diffFileSet) {
+              hit = changedFiles.filter(f => ctx.diffFileSet.has(f))
+            } else {
+              const diffResult = gitQuiet(ctx.gitDir, ['diff', '--name-only', `${ctx.base}..${ctx.head}`, '--', ...changedFiles], { trim: true })
+              hit = diffResult && diffResult.trim() !== '' ? changedFiles : []
+            }
+            if (hit.length === 0) {
               blockedTasks.push(taskId)
             }
           } catch (e) {