sillyspec 3.27.7 → 3.27.11

package/src/index.js

@@ -98,7 +98,7 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec commit [--json]                 智能提交建议：收集 QUICKLOG/已勾 task/阶段产出语义，生成建议 message（只建议不执行）
   sillyspec verify-probes --change <name> [--init]  verify 机械探针（TODO 标记/测试覆盖/API 对账/删除对账）；--init 生成 verify-result.md 骨架
   sillyspec module-impact --change <name>       生成 module-impact.md 骨架（文件×模块归属按 module-map 预填 + 未匹配清单）
-  sillyspec endpoints extract --change <name> [--task task-NN] [--dir <dir>|--files <a.py,b.js>]  静态扫描路由装饰器生成 endpoints.json
+  sillyspec endpoints extract --change <name> [--task task-NN | --all-tasks] [--dir <dir>|--files <a.py,b.js>]  静态扫描路由装饰器生成 endpoints.json
   sillyspec scan-fix-headers [--project <名>]   scan 文档补 author/created_at header（幂等）
   sillyspec plan-adopt-waves --change <名> [--dry-run]   plan.md Wave 段一键重排为 depends_on 拓扑分组（同步任务总表 W 列，幂等）
   sillyspec workspace add <名> <路径> [--role] [--repo] | remove <名> | status   多项目工作区登记与状态探测
@@ -743,6 +743,20 @@ async function main() {
       }
       console.log(`📦 待提交变更（${cc.changedCount} 个文件${cc.untrackedCount > 0 ? `，其中未跟踪 ${cc.untrackedCount} 个` : ''}；上方 stat 仅列已跟踪文件的改动）`);
       if (cc.stat) console.log(cc.stat.split('\n').map(l => '   ' + l).join('\n'));
+      // 暂存区快照（坑 same-main-staging-pollution，2026-08-28 实证：同 main 双会话共享暂存区，
+      // A 的 commit 扫入 B 暂存的文件）：git commit 只含暂存内容——提交前把快照亮出来供核对。
+      {
+        const { collectStagedArea } = await import('./commit-suggest.js');
+        const staged = collectStagedArea({ cwd: dir });
+        if (staged.available && staged.staged.length > 0) {
+          console.log(`\n📌 暂存区快照（git diff --cached --name-only，你的下一次 git commit 将恰好含这 ${staged.staged.length} 个文件）：`);
+          for (const f of staged.staged.slice(0, 15)) console.log(`   - ${f}`);
+          if (staged.staged.length > 15) console.log(`   … 共 ${staged.staged.length} 个`);
+          console.log(`   ⚠️ 同 main 并行会话共享同一暂存区——快照里非本会话的文件请先 git restore --staged <file> 剔除，否则会被你的 commit 扫入`);
+        } else if (staged.available) {
+          console.log(`\n📌 暂存区为空（git commit 前需先 git add；用 pathspec 级 add 防扫入无关文件）`);
+        }
+      }
       if (cc.quickEntries.length > 0) {
         console.log(`\n📝 QUICKLOG（上次提交 ${cc.lastCommitTime || '（无）'} 之后 ${cc.quickEntries.length} 条）：`);
         for (const q of cc.quickEntries) {
@@ -892,15 +906,19 @@ async function main() {
       // 此前靠 agent 手扫装饰器手写（易漏 endpoint）。CLI 复用 endpoint-extractor 全套提取器
       // （FastAPI @router.* / Express router.* / Spring @*Mapping）静态扫描生成，
       // verify 探针 5（verifyApiParity）直接消费该产物。
+      // --all-tasks（坑 probe5-single-task-artifact-scope，2026-08-28 实证：单 task 产物对账
+      // 产生大量假 missing）：聚合模式——逐 task 卡提取，各自落 contract-artifacts/<change>/<task>/，
+      // 与 verifyApiParity 的聚合读侧（contract-artifacts/<change>/*/endpoints.json 全量并集）对齐。
       const epSub = filteredArgs[1];
       if (epSub !== 'extract') {
-        console.error('用法: sillyspec endpoints extract --change <name> [--task task-NN] [--dir <backendRoot> | --files <a.py,b.js...>] [--spec-dir <path>]\n  静态扫描后端路由装饰器生成 endpoints.json（FastAPI/Express/Spring）；verify 探针 5 消费');
+        console.error('用法: sillyspec endpoints extract --change <name> [--task task-NN | --all-tasks] [--dir <backendRoot> | --files <a.py,b.js...>] [--spec-dir <path>]\n  静态扫描后端路由装饰器生成 endpoints.json（FastAPI/Express/Spring）；verify 探针 5 消费。\n  --all-tasks：聚合逐 task 卡 allowed_paths 各自提取（对账口径与探针 5 聚合读侧一致，推荐）');
         process.exit(2);
       }
       const epChangeIdx = args.indexOf('--change');
       const epChange = epChangeIdx >= 0 && args[epChangeIdx + 1] ? args[epChangeIdx + 1] : null;
       const epTaskIdx = args.indexOf('--task');
       const epTask = epTaskIdx >= 0 && args[epTaskIdx + 1] ? args[epTaskIdx + 1] : null;
+      const epAllTasks = args.includes('--all-tasks');
       const epDirIdx = args.indexOf('--dir');
       const epDir = epDirIdx >= 0 && args[epDirIdx + 1] ? args[epDirIdx + 1] : null;
       const epFilesIdx = args.indexOf('--files');
@@ -909,6 +927,10 @@ async function main() {
         console.error('❌ 缺 --change <变更名>');
         process.exit(2);
       }
+      if (epAllTasks && (epTask || epDir || epFilesRaw)) {
+        console.error('❌ --all-tasks 与 --task/--dir/--files 互斥（聚合模式逐 task 卡自动取 allowed_paths）');
+        process.exit(2);
+      }
       assertSafeChangeName(epChange, '--change 变更名');
       const { extractFastApiEndpoints, extractExpressEndpoints, extractSpringEndpoints, scanBackendEndpoints } = await import('./endpoint-extractor.js');
       const endpoints = [];
@@ -928,10 +950,56 @@ async function main() {
           else if (ext === '.java') endpoints.push(...extractSpringEndpoints(abs))
         } catch { /* 单文件解析失败不阻断整体 */ }
       }
+      // 单 task 产物写盘（taskName 归属目录）；返回提取数
+      const epRuntimeRoot = (await import('./run/shared.js')).resolveRuntimeRoot({ specRoot: specDir }, epSpecBase);
+      const writeArtifact = (taskName, eps) => {
+        const artifact = {
+          generated_at: new Date().toISOString().slice(0, 19).replace('T', ' '),
+          generator: 'sillyspec endpoints extract',
+          endpoints: eps.map(e => ({ method: e.method, path: e.path, source: e.source })),
+        }
+        const epOutDir = join(epRuntimeRoot, 'contract-artifacts', epChange, taskName);
+        mkdirSync(epOutDir, { recursive: true });
+        const epOutPath = join(epOutDir, 'endpoints.json');
+        writeFileSync(epOutPath, JSON.stringify(artifact, null, 2) + '\n');
+        return epOutPath;
+      }
       if (epDir) {
-        endpoints.push(...scanBackendEndpoints(resolve(epDir)))
+        endpoints.push(...scanBackendEndpoints(resolve(epDir)));
       } else if (epFilesRaw) {
         for (const f of epFilesRaw.split(',').map(s => s.trim()).filter(Boolean)) collectFile(f)
+      } else if (epAllTasks) {
+        // 聚合模式：逐 task 卡 allowed_paths 提取，各自落产物目录（对齐 verifyApiParity 聚合读侧）
+        const { parseAllowedPaths } = await import('./stages/plan-postcheck.js')
+        const tasksDir = join(epChangeDir, 'tasks')
+        const taskCards = existsSync(tasksDir)
+          ? readdirSync(tasksDir).filter(f => /^task-[\w.-]+\.md$/.test(f)).sort()
+          : []
+        if (taskCards.length === 0) {
+          console.error(`❌ --all-tasks 无 task 卡（${tasksDir} 不存在或无 task-*.md）——先跑 plan 生成 TaskCard`);
+          process.exit(1);
+        }
+        let total = 0
+        for (const card of taskCards) {
+          const taskName = card.replace(/\.md$/, '')
+          const eps = []
+          const perFile = (f) => {
+            const abs = resolve(f)
+            if (!existsSync(abs)) return
+            const ext = extname(abs).toLowerCase()
+            try {
+              if (ext === '.py') eps.push(...extractFastApiEndpoints(abs))
+              else if (ext === '.js' || ext === '.ts') eps.push(...extractExpressEndpoints(abs))
+              else if (ext === '.java') eps.push(...extractSpringEndpoints(abs))
+            } catch { /* 单文件解析失败不阻断整体 */ }
+          }
+          for (const p of parseAllowedPaths(readFileSync(join(tasksDir, card), 'utf8'))) perFile(p)
+          const outPath = writeArtifact(taskName, eps)
+          total += eps.length
+          console.log(`ℹ️  ${taskName}: ${eps.length} 个端点 → ${outPath}`)
+        }
+        console.log(`✅ 聚合提取完成：${taskCards.length} 个 task 卡共 ${total} 个端点（探针 5 对账时全量并集消费）`);
+        break;
       } else {
         // 默认扫描面：task 卡 allowed_paths ∪ design §6 清单里的具体源码文件
         const { parseFileChangeListDetailed } = await import('./change-list.js')
@@ -957,22 +1025,13 @@ async function main() {
           collectFile(p)
         }
         if (candidates.size === 0) {
-          console.error('❌ 无扫描面：--task 卡无 allowed_paths 且 design.md 无具体文件清单——显式传 --dir <backendRoot> 或 --files <a.py,b.js>');
+          console.error('❌ 无扫描面：--task 卡无 allowed_paths 且 design.md 无具体文件清单——显式传 --dir <backendRoot> 或 --files <a.py,b.js>，或用 --all-tasks 聚合逐卡提取');
           process.exit(1);
         }
         console.log(`ℹ️  扫描 ${scanned}/${candidates.size} 个清单文件（不存在的跳过）`);
       }
-      const artifact = {
-        generated_at: new Date().toISOString().slice(0, 19).replace('T', ' '),
-        generator: 'sillyspec endpoints extract',
-        endpoints: endpoints.map(e => ({ method: e.method, path: e.path, source: e.source })),
-      }
-      const epRuntimeRoot = (await import('./run/shared.js')).resolveRuntimeRoot({ specRoot: specDir }, epSpecBase);
-      const epOutDir = join(epRuntimeRoot, 'contract-artifacts', epChange, epTask || 'scan');
-      mkdirSync(epOutDir, { recursive: true });
-      const epOutPath = join(epOutDir, 'endpoints.json');
-      writeFileSync(epOutPath, JSON.stringify(artifact, null, 2) + '\n');
-      console.log(`✅ 提取 ${endpoints.length} 个端点 → ${epOutPath}`);
+      const outPath = writeArtifact(epTask || 'scan', endpoints);
+      console.log(`✅ 提取 ${endpoints.length} 个端点 → ${outPath}`);
       console.log(`   verify 阶段探针 5（API 契约对账）自动消费该产物；FastAPI/Express/Spring 装饰器均支持。`);
       break;
     }
@@ -1692,6 +1751,19 @@ SillySpec worktree — git worktree 隔离管理
             for (const f of result.changedFiles) {
               console.log(`   ${f}`);
             }
+            // 跨仓 worktree 回落报告（坑 cross-repo-no-worktree-isolation）：跨仓文件不进主仓
+            // changedFiles（在其所属仓的 diff 里），单独列出防漏看
+            if (Array.isArray(result.crossRepoApplied) && result.crossRepoApplied.length > 0) {
+              for (const c of result.crossRepoApplied) {
+                if (c.changedFiles.length > 0) {
+                  console.log(`✅ 跨仓 repo ${c.repoKey} 已回落 ${c.changedFiles.length} 个文件变更（worktree 已清理，分支保留作 review 锚点）:`);
+                  for (const f of c.changedFiles.slice(0, 20)) console.log(`   ${f}`);
+                  if (c.changedFiles.length > 20) console.log(`   … 共 ${c.changedFiles.length} 个`);
+                } else {
+                  console.log(`ℹ️ 跨仓 repo ${c.repoKey} 无交付变更（worktree 已清理）`);
+                }
+              }
+            }
             // filterDeliverableFiles 精细化排除（保留 .sillyspec/docs/，排 changes/+.runtime/+quicklog/ + meta.json）：
             // 模块文档（.sillyspec/docs/）= 交付物，会 auto-apply 到主工作区；变更文档/运行时/quicklog 不 apply。
             // 须告知 agent 哪些未落地，否则它期望这些文件落地却找不到（memory: worktree-apply-excludes-module-docs）。
@@ -1706,6 +1778,20 @@ SillySpec worktree — git worktree 隔离管理
                 console.log(`   git add --pathspec-from-file="${result.pathspecFile}"`);
               }
               console.log(`   （完整清单 ${result.commitPathspec.length} 个文件已存 ${result.pathspecFile}，可 --pathspec-from-file 复用）`);
+              // 他者暂存差集（坑 same-main-staging-pollution）：暂存区已有非本变更文件时，
+              // 普通 git commit 会把它们一并扫入——提交前亮出来。pathspec 级 commit
+              // （git commit -m <msg> -- <paths>）只提交指定路径、不动他者暂存，双出口都给。
+              try {
+                const { collectStagedArea } = await import('./commit-suggest.js');
+                const stagedNow = collectStagedArea({ cwd: dir, ownFiles: result.commitPathspec });
+                if (stagedNow.available && stagedNow.foreign.length > 0) {
+                  console.warn(`\n⚠️  暂存区已有 ${stagedNow.foreign.length} 个非本变更文件（很可能为他者并行会话暂存，普通 git commit 会扫入）：`);
+                  for (const f of stagedNow.foreign.slice(0, 10)) console.warn(`   - ${f}`);
+                  if (stagedNow.foreign.length > 10) console.warn(`   … 共 ${stagedNow.foreign.length} 个`);
+                  console.warn(`   推荐用 pathspec 级 commit（不动他者暂存）：git commit -m "<msg>" --pathspec-from-file="${result.pathspecFile}"`);
+                  console.warn(`   或先剔除：git restore --staged -- <文件>（工作区内容不丢，对方可重新 add）`);
+                }
+              } catch { /* 暂存区快照失败不影响 apply 结果展示 */ }
             }
           }
           if (result.warnings && result.warnings.length > 0) {
@@ -1878,6 +1964,18 @@ SillySpec worktree — git worktree 隔离管理
             // 与并行会话的 apply/cleanup 互踩会互相清——与其他写主仓操作共用一把 main-repo.lock
             const { withMainRepoLock } = await import('./worktree-apply.js');
             const result = await withMainRepoLock(dir, wtName, 'worktree-cleanup', () => wm.cleanup(wtName, { force: forceFlag }));
+            // 跨仓 worktree（坑 cross-repo-no-worktree-isolation）：与主仓同锁清理——跨仓 worktree
+            // 注册在各跨仓仓 .git 内，但目录/meta 在主仓 .sillyspec 运行时区，同样怕并发互踩
+            const { cleanupCrossWorktrees } = await import('./worktree-cross.js');
+            const crossResult = cleanupCrossWorktrees({ cwd: dir, changeName: wtName, specBase: resolvePlatformSpecDir(dir, specDir), force: forceFlag });
+            for (const cr of crossResult.results) {
+              if (cr.result === 'cleaned') {
+                console.log(`✅ 跨仓 worktree 已清理: repo=${cr.repoKey}（${(cr.details || []).filter(d => d.startsWith('分支')).join('；') || '详情见上'}）`);
+              } else if (cr.result === 'partial') {
+                console.error(`🚫 跨仓 repo=${cr.repoKey} 清理受阻：${(cr.details || []).join('; ')}`);
+                for (const r of cr.residual || []) console.error(`   残留: ${r}`);
+              }
+            }
             if (result.result === 'cleaned' || result.result === 'force-cleaned') {
               console.log(`✅ worktree 已清理: ${wtName} (mode: ${result.mode})`);
               if (result.details?.length > 0) {

package/src/progress/stage-machine.js

@@ -349,7 +349,9 @@ export class StageMachine {
             command: `sillyspec run ${s} --continue --answer "用户回答"${cc}`,
           };
         }
-        const hasPending = sd.steps.some(st => ['pending', 'waiting', 'failed'].includes(st.status));
+        // blocked（deps/review.json 门控阻断标记）也计入待办（坑 deps-gate-blocked-invisible）：
+        // 漏计会让全局「下一步」建议跳过被阻断的阶段/步骤，误导 agent 去跑更后面的阶段。
+        const hasPending = sd.steps.some(st => ['pending', 'waiting', 'failed', 'blocked'].includes(st.status));
         if (hasPending) {
           return {
             text: `${STAGE_LABELS[s] || s} 进行中，继续执行下一步。`,

package/src/run/command.js

@@ -23,7 +23,7 @@ import { basename, join, resolve, dirname } from 'node:path'
 import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
 import { randomBytes, randomUUID } from 'node:crypto'
 import { writeAtomicSync } from '../fs-atomic.js'
-import { resolveSpecDir, countAncestorSpecDirs, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, warnApprovalUnknown, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, writePlatformPointer, checkPlatformManaged, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME } from './shared.js'
+import { resolveSpecDir, countAncestorSpecDirs, ancestorSpecDirs, resolveAncestorCeiling, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, warnApprovalUnknown, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, writePlatformPointer, checkPlatformManaged, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME } from './shared.js'
 import { resolveQuickLinkedChanges } from './quick-audit.js'
 import { outputStep, collectStageWaitHistory } from './prompt.js'
 import { completeStep, skipStep, waitStep, continueStep } from './complete.js'
@@ -75,6 +75,38 @@ export function detectSpaceSeparatedFiles(flags) {
   return suspects
 }
 
+/**
+ * 检测 prose 参数值是否疑似被 Git Bash(MSYS) 路径转换污染（坑 quick-req-msys-path-mangling）。
+ *
+ * MSYS2 对以 / 开头的命令行参数做 POSIX→Windows 自动转换：--req "/sessions 页修复" 到达
+ * CLI 时已是 "<Git 安装目录>/sessions 页修复"（如 E:/Software/Git/sessions 页修复），无感
+ * 写入 QUICKLOG 标题与「需求：」行（该标题也是平台「快速修复」列表展示标题）。启发式：
+ * 盘符绝对路径开头 + 紧随空白与中文正文——人写的 Windows 路径引用不会以「盘符路径+中文
+ * 句子」形态开头；纯英文正文检不出（v1 取零误报优先，本仓主流为中文文案）。
+ *
+ * 纯函数：无副作用，供 command.js 解析层告警 + 单测复用。只告警不阻断——无法确定性区分
+ * 误报（合法值确可能以盘符路径开头），由 agent 看到 stderr 告警后自查重发。
+ * @param {string|null} v 待检值
+ * @returns {boolean} 疑似污染返回 true
+ */
+export function looksLikeMsysMangledPath(v) {
+  if (typeof v !== 'string' || v.length === 0) return false
+  const m = v.match(/^[A-Za-z]:[\\/]\S+/) // 盘符绝对路径 token（吃到首个空白）
+  if (!m) return false
+  const rest = v.slice(m[0].length)
+  return /^\s/.test(rest) && /[\u4e00-\u9fff]/.test(rest)
+}
+
+/**
+ * MSYS 污染告警出口：命中嗅探时向 stderr 打 flag 名 + 值前缀 + 修复指引（不阻断）。
+ */
+function warnMsysMangledFlag(flag, value) {
+  if (!looksLikeMsysMangledPath(value)) return
+  console.error(`⚠️ ${flag} 的值疑似被 Git Bash(MSYS) 路径转换污染：「${value.slice(0, 60)}${value.length > 60 ? '…' : ''}」`)
+  console.error('   以 / 开头的文案在 Git Bash 下会被展开成 <Git 安装目录>/… 绝对路径后才传入 CLI。')
+  console.error('   非本意 → 去掉前导 / 或改写表述后重发本命令；确需原样 → 命令前加 MSYS_NO_PATHCONV=1。')
+}
+
 /**
  * 从 progress 或变更目录推导变更名
  */
@@ -385,14 +417,26 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // let：下方 worktree 副本漂移守卫命中时锚回 wt.mainSpecBase（task-05/D-03）
   let specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
 
-  // 漂移提醒:cwd 祖先链 ≥2 个 .sillyspec = monorepo 多实例,当前命中的「最近」实例
+  // 漂移阻断:cwd 祖先链 ≥2 个 .sillyspec = monorepo 多实例,当前命中的「最近」实例
   // 可能不是用户意图的项目(如 cd 进被独立 scan 的子项目跑测试后忘回根)。
-  // 平台模式 / 显式 --spec-dir 跳过(已明确指定,无歧义)。仅提醒不阻断。
+  // 平台模式 / 显式 --spec-dir 跳过(已明确指定,无歧义)。
+  // 当前实例 ≠ git 顶层仓库实例 → 默认拒绝(坑 monorepo-cwd-wrong-spec-instance)。
   if (!platformOpts.specRoot && !specDir) {
-    const ancestorCount = countAncestorSpecDirs(cwd)
-    if (ancestorCount >= 2) {
-      console.warn(`⚠️  检测到祖先链有 ${ancestorCount} 个 .sillyspec 实例(monorepo 多实例),当前使用: ${specBase}`)
-      console.warn(`    若意图是另一个项目:cd 回该项目根,或用 --spec-dir <根>/.sillyspec 显式指定。`)
+    const ancestorSpecs = ancestorSpecDirs(cwd)
+    if (ancestorSpecs.length >= 2) {
+      // 判断当前命中的 .sillyspec 是否在 git 顶层仓库根下
+      const gitRoot = resolveAncestorCeiling(resolve(cwd))
+      const currentSpecParent = dirname(resolve(specBase))
+      const isAtGitRoot = gitRoot && resolve(currentSpecParent) === resolve(gitRoot)
+      if (!isAtGitRoot) {
+        console.error(`❌ 检测到祖先链有 ${ancestorSpecs.length} 个 .sillyspec 实例(monorepo 多实例)，当前使用: ${specBase}`)
+        console.error(`   当前 cwd 不在 git 顶层仓库根下，静默绑定到子项目实例会导致进度/QUICKLOG 分裂。`)
+        console.error(`   修复：cd 回项目根目录，或用 --spec-dir <根>/.sillyspec 显式指定。`)
+        process.exit(2)
+      }
+      // 在 git 根下但有多实例(子项目也有 .sillyspec)→ 仅警告(正确实例已命中)
+      console.warn(`⚠️  检测到祖先链有 ${ancestorSpecs.length} 个 .sillyspec 实例(monorepo 多实例)，当前使用: ${specBase}`)
+      console.warn(`    当前已绑定 git 顶层仓库实例。若意图是子项目:用 --spec-dir 显式指定。`)
     }
   }
 
@@ -461,6 +505,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   let outputText = null
   const outputValue = getFlagValue('--output')
   if (outputValue !== null) outputText = outputValue
+  warnMsysMangledFlag('--output', outputValue)
 
   // 解析 quick 末步四字段参数（2026-08-21 agent-手工产出审计第二批 F6）：--req/--cause/
   // --solution/--result 各传一项，CLI 合成单行四字段 outputText（quicklog 落盘侧
@@ -480,6 +525,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
         console.error(`❌ quick 末步四字段参数缺项：${missing.join(' ')}（--req/--cause/--solution/--result 必须全给，或缺字段 --done 会被拒）`);
         process.exit(2)
       }
+      for (const [f] of FOUR) warnMsysMangledFlag(f, getFlagValue(f))
       outputText = FOUR.map(([f, label]) => `${label}${getFlagValue(f)}`).join(' ')
     }
   }
@@ -502,6 +548,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       break
     }
   }
+  warnMsysMangledFlag('--input', inputText)
 
   // 解析 --linked-changes <a,b|none>（quick 专用：显式声明关联变更，CI/脚本友好）
   // 与 --change 解耦：--linked-changes 语义清晰（关联变更），不与「指定变更名」混淆。
@@ -896,7 +943,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     if (readonlySteps && readonlySteps.length > 0) {
       // 已有进度（历史 seed 过）则渲染当前待办步；无进度从首步开始
       const existingSteps = progress.stages?.[stageName]?.steps
-      const pendingIdx = existingSteps ? existingSteps.findIndex(s => s.status === 'pending' || s.status === 'in-progress') : -1
+      const pendingIdx = existingSteps ? existingSteps.findIndex(s => s.status === 'pending' || s.status === 'in-progress' || s.status === 'blocked') : -1
       const stepIdx = pendingIdx !== -1 ? pendingIdx : 0
       await outputStep(stageName, stepIdx, readonlySteps, cwd, readOnlyChange, progress.project || null, platformOpts, null, collectStageWaitHistory(progress, stageName))
     }
@@ -1295,7 +1342,7 @@ function showStatus(progress, stageName, nextSuggestion = null) {
 
   console.log('')
 
-  const firstPending = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
+  const firstPending = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress' || s.status === 'blocked')
 
   if (progress.batchProgress) {
     const bp = progress.batchProgress
@@ -1314,10 +1361,13 @@ function showStatus(progress, stageName, nextSuggestion = null) {
   }
 
   steps.forEach((step, i) => {
-    const icon = step.status === 'completed' ? '✅' : step.status === 'skipped' ? '⏭️' : step.status === 'waiting' ? '⏸️' : '⬜'
-    const isCurrent = (step.status === 'pending' || step.status === 'in-progress') && i === firstPending
+    const icon = step.status === 'completed' ? '✅' : step.status === 'skipped' ? '⏭️' : step.status === 'waiting' ? '⏸️' : step.status === 'blocked' ? '🚫' : '⬜'
+    const isCurrent = (step.status === 'pending' || step.status === 'in-progress' || step.status === 'blocked') && i === firstPending
     const isWaiting = step.status === 'waiting'
-    console.log(`${icon} Step ${i + 1}: ${step.name}${isCurrent ? ' ← 当前' : ''}${isWaiting ? ' [WAITING]' : ''}`)
+    console.log(`${icon} Step ${i + 1}: ${step.name}${isCurrent ? ' ← 当前' : ''}${isWaiting ? ' [WAITING]' : ''}${step.status === 'blocked' ? ' [BLOCKED]' : ''}`)
+    if (step.status === 'blocked') {
+      console.log(`       此前被门控阻断——${step.blockReason || 'deps 未就绪 / review.json 不完整'}；修复后重跑 --done 即恢复，无需 --reset`)
+    }
     if (isWaiting) {
       if (step.waitReason) console.log(`       原因：${step.waitReason}`)
       if (step.waitOptions) console.log(`       选项：${formatWaitOptions(step.waitOptions)}`)
@@ -1355,6 +1405,22 @@ async function resetStage(pm, progress, stageName, cwd, changeName, platformOpts
     } catch (e) {
       console.warn(`⚠️  reset 清理 worktree 失败（不阻断 reset）: ${e.message}`)
     }
+    // 跨仓 worktree 一并清理（坑 cross-repo-no-worktree-isolation）：否则下次 execute 因 meta
+    // 存在复用带脏状态的旧跨仓 worktree
+    try {
+      const { cleanupCrossWorktrees } = await import('../worktree-cross.js')
+      const cross = cleanupCrossWorktrees({
+        cwd, changeName,
+        specBase: platformOpts?.specRoot || join(cwd, '.sillyspec'),
+        force: true,
+      })
+      for (const cr of cross.results) {
+        if (cr.result === 'cleaned') console.log(`🧹 已清理跨仓 worktree repo=${cr.repoKey}，下次 execute 将重建`)
+        else if (cr.result === 'partial') console.warn(`⚠️ 跨仓 repo=${cr.repoKey} 清理残留: ${(cr.details || []).join('; ')} ${(cr.residual || []).join('; ')}`)
+      }
+    } catch (e) {
+      console.warn(`⚠️  reset 清理跨仓 worktree 失败（不阻断 reset）: ${e.message}`)
+    }
   }
   const defSteps = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
   progress.stages[stageName] = {
@@ -1484,7 +1550,7 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
     console.log('')
 
     const defSteps = await getAutoSteps(currentStage)
-    const pendingIdx = progress.stages[currentStage]?.steps?.findIndex(step => step.status === 'pending' || step.status === 'in-progress') ?? -1
+    const pendingIdx = progress.stages[currentStage]?.steps?.findIndex(step => step.status === 'pending' || step.status === 'in-progress' || step.status === 'blocked') ?? -1
     if (pendingIdx === -1) {
       const wsIdx = progress.stages[currentStage]?.steps?.findIndex(step => step.status === 'waiting') ?? -1
       if (wsIdx !== -1) {
@@ -1536,7 +1602,7 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
     return
   }
 
-  const nextPendingIdx = progress.stages[currentStage]?.steps?.findIndex(step => step.status === 'pending' || step.status === 'in-progress') ?? -1
+  const nextPendingIdx = progress.stages[currentStage]?.steps?.findIndex(step => step.status === 'pending' || step.status === 'in-progress' || step.status === 'blocked') ?? -1
   if (nextPendingIdx !== -1) {
     const defSteps = await getAutoSteps(currentStage)
     // execute 阶段启动前检查审批
@@ -1615,7 +1681,7 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
 
   console.log(`\n${currentStage} complete. Auto advanced to ${next}.`)
   const nextSteps = await getAutoSteps(next)
-  const firstPending = progress.stages[next]?.steps?.findIndex(step => step.status === 'pending' || step.status === 'in-progress') ?? -1
+  const firstPending = progress.stages[next]?.steps?.findIndex(step => step.status === 'pending' || step.status === 'in-progress' || step.status === 'blocked') ?? -1
   if (firstPending !== -1) {
     // execute 阶段启动前检查审批
     if (next === 'execute' && !skipApproval) {

package/src/run/complete-handlers.js

@@ -1365,6 +1365,20 @@ export async function handleExecuteWorktreeCleanup({ stageName, changeName, cwd
             console.log(`   下一步: sillyspec worktree apply ${changeName}`);
           } else {
             console.log(`🔗 Worktree: ${cleanResult.result.result}`);
+            // 正当清理回执（坑 deps-gate-cleanup-order，2026-08-28 实证：cleanup 后重试 --done 被
+            // deps 门拦「worktree 不可用」，逼 doctor --align-execute-progress 手工对齐）：execute 完成时的
+            // 正当清理（无未应用变更）落 durable 标记，enforceDepsGate 读它区分「正当收尾」与「意外丢失」。
+            // apply 路径不写——apply-pathspec-<change>.txt 已是既定 apply 凭据，双标记冗余。
+            if (['cleaned', 'force-cleaned', 'partial'].includes(cleanResult.result.result)) {
+              try {
+                const runtimeDir = join(cwd, '.sillyspec', '.runtime');
+                mkdirSync(runtimeDir, { recursive: true });
+                writeFileSync(join(runtimeDir, `execute-cleanup-${changeName}.json`), JSON.stringify({
+                  change: changeName, cleanedAt: new Date().toISOString(),
+                  reason: 'execute-completed-no-unapplied-changes',
+                }, null, 2) + '\n', 'utf8');
+              } catch { /* 回执失败只损失 deps 门的放行判据，不影响 cleanup 结果 */ }
+            }
             if (cleanResult.result.residual?.length > 0) {
               console.warn(`   ⚠️ 清理残留: ${cleanResult.result.residual.join('; ')}`);
               console.warn(`   手动处理: sillyspec worktree cleanup ${changeName} --force`);
@@ -1385,6 +1399,26 @@ export async function handleExecuteWorktreeCleanup({ stageName, changeName, cwd
     } catch (e) {
       console.warn(`🔗 Worktree: check failed — ${e.message}`);
     }
+    // 跨仓 worktree（坑 cross-repo-no-worktree-isolation）：execute 完成时不自动清——交付还在
+    // 跨仓 worktree 分支上未回落主工作副本，与主仓「pending apply」同语义，报状态 + 下一步指引
+    try {
+      const { listCrossWorktreeMetas } = await import('../worktree-cross.js')
+      const specBase = join(cwd, '.sillyspec')
+      for (const { repoKey, meta: cm } of listCrossWorktreeMetas(specBase, changeName)) {
+        let pending = 0
+        try {
+          const d = safeGit(cm.worktreePath, ['diff', '--name-only', cm.baseHash], { timeout: 30000 })
+          const u = safeGit(cm.worktreePath, ['ls-files', '--others', '--exclude-standard'], { timeout: 30000 })
+          pending = ((d.value || '') + '\n' + (u.value || '')).split('\n').filter(Boolean).length
+        } catch { /* 状态探测失败按未知处理 */ }
+        if (pending > 0) {
+          console.log(`🔗 跨仓 worktree repo=${repoKey}: pending apply (${pending} 个未回落变更)`)
+          console.log(`   下一步: sillyspec worktree apply ${changeName}（跨仓与主仓一并回落）`)
+        } else {
+          console.log(`🔗 跨仓 worktree repo=${repoKey}: 无未回落变更（apply 时将自动清理）`)
+        }
+      }
+    } catch { /* 跨仓状态报告 best-effort */ }
   }
   return null
 }

package/src/run/complete.js

@@ -103,7 +103,16 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   }
 
   const steps = stageData.steps
-  let currentIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
+  // blocked（deps/review.json 门控阻断标记）也视为当前步骤（坑 deps-gate-blocked-invisible，
+  // 2026-08-27 实证）：门控阻断时 enforceDepsGate/enforceReviewJsonGate 把当前步置 blocked 后
+  // exit(1)，若谓词漏 blocked，被阻断步骤对 findIndex 永久隐身——重试 --done 落到其后第一个
+  // pending 步骤上（错步记账，DB 显示与事实脱节），且 blocked 步骤无任何恢复路径（状态机卡死，
+  // 只能 --reset 丢进度）。门控本身在下方会重新校验：deps 已修复 → 正常完成；未修复 → 再次
+  // 阻断同一步（幂等，不污染后续步骤）。
+  let currentIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress' || s.status === 'blocked')
+  if (currentIdx !== -1 && steps[currentIdx].status === 'blocked') {
+    console.log(`⚠️  Step "${steps[currentIdx].name}" 此前被门控阻断（blocked），本次 --done 重新校验门控后继续推进。`)
+  }
   // ── 坑1：--done --answer 解「已 waiting 的步骤」──
   // findIndex 仅查 pending/in-progress，排除 waiting；故 --done --answer 落到已 --wait 暂停的
   // requiresWait 步骤时会跳过它、把 --answer 静默丢弃，步骤永久卡 WAITING、末步报「等待用户输入」。