sillyspec 3.27.9 → 3.27.12

package/src/run/gates.js

@@ -363,6 +363,23 @@ export async function enforceDepsGate(stageName, cwd, changeName, step, steps, c
   try {
     worktreeGone = !!(wm && changeName) && !existsSync(wm.getWorktreePath(changeName))
   } catch {}
+  // ── 正当收尾放行（坑 deps-gate-cleanup-order，2026-08-28 实证：apply 后 / execute 空变更
+  // cleanup 后重试 --done，被本门拦「worktree 不可用」逼 doctor --align-execute-progress 手工
+  // 对齐——顺序矛盾：cleanup 是流程自己做的收尾，门却当意外丢失拦）。两凭据二选一：
+  //   - apply-pathspec-<change>.txt：applyWorktree 成功后落盘（apply 后自动 cleanup 删 meta）；
+  //   - execute-cleanup-<change>.json：handleExecuteWorktreeCleanup 正当清理回执。
+  // 有凭据 = 隔离期已正当结束（交付已落主仓或本无交付），deps 能力要求不再适用 → 放行。
+  if (worktreeGone && changeName) {
+    try {
+      const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
+      const legitimatelyEnded = existsSync(join(runtimeRoot, `apply-pathspec-${changeName}.txt`))
+        || existsSync(join(runtimeRoot, `execute-cleanup-${changeName}.json`))
+      if (legitimatelyEnded) {
+        console.log('ℹ️  worktree 已在 apply/execute 收尾时正当清理（凭据在 .runtime），deps 门放行')
+        return true
+      }
+    } catch { /* 凭据读取失败 → 维持原判定 */ }
+  }
   // ── fail-loud 块（Phase 3，D-005@v1：仅改拒绝侧 stderr）──
   console.error('❌ ── deps 门控阻断（本次 --done 未完成，进度未推进）──')
   if (worktreeGone) {
@@ -559,6 +576,19 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     }
   }
 
+  // plan 门 facade 候选预检（坑 plan-facade-files-manual-backfill，2026-08-28 用户实证 ×2：
+  // daemon/service.py 类「透传必经文件」不在 allowed_paths → 执行期 apply Gate1 拦截 →
+  // 手工回补两轮）。allowed 集与 Gate1 同源（resolveApplyAllowSet 主仓切片），
+  // 静态引用/聚合扫描亮候选，advisory 不阻断。
+  if (stageName === 'plan' && changeName) {
+    try {
+      const { resolveApplyAllowSet } = await import('../worktree-apply.js')
+      const { warnFacadeCandidateFiles } = await import('../facade-hint.js')
+      const allowMap = resolveApplyAllowSet(cwd, changeName)
+      warnFacadeCandidateFiles({ cwd, changeName, allowSet: allowMap.get('main') })
+    } catch { /* 预检失败不阻断 plan 完成 */ }
+  }
+
   // verify 产物校验通过 + 结论非 FAIL（否则上面已阻断）。
   // 再由 CLI 亲自执行 local.yaml 的测试命令，与 verify-result.md 的自报告对账：
   // 自报告 PASS 但实测失败 → 阻断（防止"文案通过"绕过验证）。
@@ -576,16 +606,23 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
         const { collectForeignDeclaredFiles } = await import('../verify-postcheck.js')
         const { gitQuiet } = await import('../git-helper.js')
         const foreignMap = collectForeignDeclaredFiles(cwd, changeName, { specBase, runtimeRoot: resolveRuntimeRoot(platformOpts, specBase) })
+        // dirty 集提前算好：归因提示①（他者在途）与②（生成产物旧基线）共用
+        const dirty = (gitQuiet(cwd, ['diff', '--name-only', 'HEAD']) || '')
+          .split('\n').filter(Boolean).map(f => f.replace(/\\/g, '/'))
+        const dirtySet = new Set(dirty)
         if (foreignMap.size > 0) {
-          const dirty = (gitQuiet(cwd, ['diff', '--name-only', 'HEAD']) || '')
-            .split('\n').filter(Boolean).map(f => f.replace(/\\/g, '/'))
           const hitForeign = dirty.filter(f => foreignMap.has(f))
           if (hitForeign.length > 0) {
             console.error(`   ℹ️ 归因提示：主仓检出 ${hitForeign.length} 个并行会话声明的在途文件（${hitForeign.slice(0, 5).join(', ')}${hitForeign.length > 5 ? ' 等' : ''}）——实测失败可能混入他者 WIP 而非本变更问题。待其提交/收尾后复验，仍失败才是本变更的。`)
           }
         }
         // 第二判据（坑 derived-artifact-stale-baseline）：本变更 apply 的文件（apply-pathspec 落盘）
-        // 与主仓近期提交重叠——本变更旧基线的生成产物可能覆盖了已合入内容，先在新基线重跑生成命令再复验
+        // 与主仓近期提交重叠——本变更旧基线的生成产物可能覆盖了已合入内容，先在新基线重跑生成命令再复验。
+        // 坑 verify-attr2-foreign-wip-misdirection（2026-08-28 实证）：并行会话在途/近期收尾文件
+        // 让重叠集虚高（51 文件），每轮误导 agent 重跑 gen:types，实际失败源是他者 WIP。两道过滤：
+        //   - 必须 dirty：apply 落盘的旧内容此刻物理在场（verify gate 时本变更未提交，旧基线覆盖
+        //     必然表现为对 HEAD 的修改）——内容与 HEAD 一致时重跑生成命令改变不了本轮实测；
+        //   - 剔除他者声明集：那是归因提示①的领地（待其收尾后复验），不是生成产物过期。
         try {
           const pathspecFile = join(resolveRuntimeRoot(platformOpts, specBase), `apply-pathspec-${changeName}.txt`)
           if (changeName && existsSync(pathspecFile)) {
@@ -594,8 +631,9 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
               const recent = (gitQuiet(cwd, ['log', '-n', '10', '--name-only', '--pretty=format:']) || '')
                 .split('\n').map(l => l.trim().replace(/\\/g, '/')).filter(Boolean)
               const overlap = [...new Set(recent)].filter(f => ownFiles.has(f))
-              if (overlap.length > 0) {
-                console.error(`   ℹ️ 归因提示②：本变更有 ${overlap.length} 个文件与主仓最近 10 条提交重叠（${overlap.slice(0, 5).join(', ')}${overlap.length > 5 ? ' 等' : ''}）——若为生成产物（api-types 等），本变更可能在旧基线生成并覆盖了已合入内容；先在新基线重跑生成命令（如 gen:types）再复验。`)
+              const actionable = filterStaleBaselineOverlap(overlap, dirtySet, foreignMap)
+              if (actionable.length > 0) {
+                console.error(`   ℹ️ 归因提示②：本变更有 ${actionable.length} 个文件与主仓最近 10 条提交重叠且旧内容仍在工作区（${actionable.slice(0, 5).join(', ')}${actionable.length > 5 ? ' 等' : ''}）——若为生成产物（api-types 等），本变更可能在旧基线生成并覆盖了已合入内容；先在新基线重跑生成命令（如 gen:types）再复验。（重叠共 ${overlap.length} 个，其余未在工作区改动或属他者会话在途文件，已归提示①/无需处理）`)
               }
             }
           }
@@ -1112,6 +1150,25 @@ export async function completeStageGates({ stageName, cwd, changeName, platformO
 }
 
 
+/**
+ * 归因提示②（生成产物旧基线覆盖）的重叠集过滤（坑 verify-attr2-foreign-wip-misdirection）。
+ *
+ * 原始重叠 = 本变更 apply-pathspec ∩ 主仓最近提交。并行会话场景下该集合被在途/刚收尾的
+ * 他者文件虚高，逐轮误导 agent 重跑生成命令。只保留两个必要条件都成立的文件：
+ *   - dirty（此刻对 HEAD 有改动）：verify gate 时本变更未提交，旧基线覆盖必然物理在场；
+ *     内容与 HEAD 一致时重跑生成命令改变不了本轮实测。
+ *   - 非他者声明集（collectForeignDeclaredFiles）：他者在途文件归归因提示①（待其收尾
+ *     复验），不是生成产物过期。
+ *
+ * @param {string[]} overlap 原始重叠文件（POSIX 路径）
+ * @param {Set<string>} dirtySet 主仓当前对 HEAD 的改动集
+ * @param {Set<string>|Map} foreignDeclared 他者会话声明集（Map 亦可用 has 判定）
+ * @returns {string[]} 可行动子集（空 = 不出提示②，避免误导）
+ */
+export function filterStaleBaselineOverlap(overlap, dirtySet, foreignDeclared) {
+  return (overlap || []).filter(f => dirtySet?.has(f) && !(foreignDeclared?.has(f)))
+}
+
 /**
  * verify 服务进程回收（verify --done 收尾调用）。
  *

package/src/run/prompt.js

@@ -26,6 +26,7 @@ import { resolvePromptIncludes, resolveRuntimeRoot, safeGit, WAIT_MARKER_RE, QUI
 import { renderStageContract } from '../stage-contract-spec.js'
 import { nowWallClock } from '../datetime.js'
 import { parseModuleMapSimple } from '../modules.js'
+import { readModuleRecentChanges } from '../module-changelog.js'
 import { REVIEW_SCHEMA_VERSION, isValidExecuteRunId } from '../task-review.js'
 
 /**
@@ -111,6 +112,12 @@ function buildModuleContextInjection(taskDescription, moduleIndex, specBase, pro
     if (deps.length > 0) injection += `- **依赖**: ${deps.join(', ')}\n`
     const usedBy = data.used_by || []
     if (usedBy.length > 0) injection += `- **被引用**: ${usedBy.join(', ')}\n`
+    // 最近变更（模块卡「变更索引」惯例解析，2026-08-31 变更关联审计）：三阶段免扫描即知
+    // 该模块最近被谁动过。懒读命中模块的卡 + sidecar（matched 通常 ≤3 个，不做全目录扫描）
+    const recentChanges = readModuleRecentChanges(join(specBase, 'docs', projectName, 'modules'), moduleId)
+    if (recentChanges.length > 0) {
+      injection += `- **最近变更**: ${recentChanges.slice(0, 3).map(e => e.name).join('、')}\n`
+    }
     injection += '\n'
   }
 
@@ -868,6 +875,10 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   const mayNeedWait = WAIT_MARKER_RE.test(stepPrompt) || requiresWait || conditionalWait
 
   console.log(`\n### 完成后执行`)
+  // requiresConfirm 步骤（如 archive「确认归档」）的完成命令必须带 --confirm——坑
+  // archive-batch-31-tool-notes ②：通用 --done 模板不带该 flag，agent 照抄执行撞
+  // 「请添加 --confirm」确认门，误以为参数没带。
+  const confirmFlag = step.requiresConfirm === true ? ' --confirm' : ''
   if (requiresWait) {
     console.log(`本步骤必须等待用户输入，不能直接 --done：`)
     console.log(`sillyspec run ${stageName} --wait --reason "${step.waitReason || '等待用户输入'}" --options "${(step.waitOptions || ['确认']).join(',')}"${changeFlag} --output "你的问题/方案摘要"`)
@@ -882,7 +893,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     console.log(``)
     console.log(`如果不需要用户决策，正常完成：`)
   }
-  console.log(`sillyspec run ${stageName} --done${changeFlag} --input "用户原始需求/反馈" --output "你的摘要"`)
+  console.log(`sillyspec run ${stageName} --done${confirmFlag}${changeFlag} --input "用户原始需求/反馈" --output "你的摘要"`)
 }
 /**
  * 替换 prompt 文本中的路径根占位符 {SPEC_ROOT}/{DOCS_ROOT}/{PROJECTS_ROOT}/

package/src/run/shared.js

@@ -616,6 +616,38 @@ export async function triggerSync(cwd, changeName, platformOpts = {}, opts = {})
   }
 }
 
+/**
+ * 触发步骤开始上报（X3 / design §8.2，变更 2026-08-29-change-delete-closure-and-spec-pull task-13）。
+ *
+ * 步骤启动时同端点同结构补推一次 progress：CLI 状态机的步骤行 DB 侧种子是 pending，
+ * 本推送在载荷层把 current_stage 的第一个未完成步投影为 in-progress（sync.js
+ * _projectStepStart，不写 DB，--done 推送路径不受影响）。真实效果 = 平台
+ * last_pushed_at 以步骤起点刷新（投影 current_step_status 对下一个 pending 步本就
+ * 推导为 active，X3 不改变其值，只让「最后信号」时间可信，停滞判定不再失真）。
+ * 与 triggerSync 同款契约：quick 会话降级跳过（无 progress 实体）、未连接平台在
+ * sync() 内部静默跳过、8s 总熔断（raceWithAbort + abort 在飞请求）、失败只 warn 不抛。
+ *
+ * 接线说明（本变更 allowed_paths 约束）：步骤 prompt 渲染点（run/stage.js outputStep
+ * 前段 / run/prompt.js）不在本变更可改文件集内——本导出即「步骤开始钩子」本体，
+ * 渲染侧一行 `triggerStepStartSync(cwd, changeName, platformOpts)` 的接线由后续
+ * 变更补上；execute 阶段的任务粒度信号已由 X4（stages/execute.js Wave prompt
+ * 每任务上报指引）覆盖。
+ */
+export async function triggerStepStartSync(cwd, changeName, platformOpts = {}, opts = {}) {
+  try {
+    const tsSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    if (changeName && QUICK_SID_RE.test(changeName) && !existsSync(join(tsSpecBase, 'changes', changeName))) {
+      return // quick 会话无 progress 实体（与 triggerSync 同判），无步骤可报
+    }
+    // shared.js 在 src/run/，sync.js 在 src/ → 退一层
+    const syncMod = await import('../sync.js')
+    await raceWithAbort((sig) => syncMod.sync(changeName, cwd, { ...sig, stepStart: true }), opts.timeoutMs)
+  } catch (e) {
+    // Best Effort：步骤开始上报失败不影响主流程（下次 --done 的 triggerSync 兜底）
+    console.warn('⚠️ 步骤开始上报失败:', e.message)
+  }
+}
+
 /**
  * 自动 pull 节流（体检 PERF-02）：triggerPull/triggerPullActiveChange 在每条 stage 命令
  * 启动时注入，agent 命令往往是秒级连发——每次都发 HTTP GET（daemon 挂/慢时单命令最多
@@ -813,6 +845,54 @@ export function isQuickMetadata(p, linkedChanges = []) {
   return false
 }
 
+// 危险文件清单（auditQuickCompletion 危险门与 predictProtectedQuickFiles 预告共用单一真相源）。
+// SillySpec 核心流程代码。W6 重构后 src/run.js（23 行 barrel）/ src/progress.js（facade）
+// 把真正逻辑下沉到 src/run/、src/progress/ 子目录——旧的精确文件名匹配
+// （file === 'src/run.js'）命中不到 src/run/command.js（. 与 / 不可混同），致危险文件门
+// 静默失效。改用「目录前缀（带尾斜杠，startsWith 不会误伤 src/runtime-* 等同名前缀）+
+// barrel/facade 本体精确名」双重覆盖。重构 src/ 模块时须同步本清单（multi-agent-review Q5）。
+const QUICK_DANGEROUS_PATTERNS = [
+  'package.json',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  '.eslintrc',
+  'tsconfig.json',
+  'src/run.js',
+  'src/run/',
+  'src/progress.js',
+  'src/progress/',
+  'src/db.js',
+  'src/stage-contract.js',
+  'src/stage-contract-spec.js',
+  'src/worktree.js',
+  'src/worktree-apply.js',
+  'src/hooks/',
+]
+
+/**
+ * 预告：--files 声明中哪些文件会在 --done 审计被危险/基线门拦截（坑 quick-protected-late-hint，
+ * 2026-08-28 用户实证：scan 类文档 ARCHITECTURE/CONCERNS 属受保护基线，--files 声明了照样拦、
+ * 必须 --force-baseline——设计合理但提示太晚，要等审计轮才发现，白跑一轮往返）。
+ * 判定与 auditQuickCompletion 危险门逐字同口径（isQuickMetadata 豁免 + 关联变更目录退栈 +
+ * DANGEROUS_PATTERNS 前缀/精确匹配），forceBaseline 已带 → 无预告。
+ * @param {string[]} files 声明文件（--files）
+ * @param {{ linkedChanges?: string[], forceBaseline?: boolean }} opts
+ * @returns {string[]} 将被拦截的声明文件子集
+ */
+export function predictProtectedQuickFiles(files, { linkedChanges = [], forceBaseline = false } = {}) {
+  if (forceBaseline) return []
+  const linked = (Array.isArray(linkedChanges) ? linkedChanges : []).map(c => String(c).replace(/\\/g, '/'))
+  const isUnderLinkedChange = (f) => linked.some(lc => f.startsWith(`.sillyspec/changes/${lc}/`))
+  return (files || [])
+    .filter(Boolean)
+    .map(f => String(f).replace(/\\/g, '/'))
+    .filter(f => {
+      if (f.startsWith('.sillyspec/') && !isQuickMetadata(f, linked) && !isUnderLinkedChange(f)) return true
+      return QUICK_DANGEROUS_PATTERNS.some(p => p === f || f.startsWith(p))
+    })
+}
+
 /**
  * quick 完成审计：对比 baseline 与实际变更。
  * @returns {{ status: 'safe'|'warning'|'blocked', reasons: string[], changedFiles: string[], newFiles: string[], deletedFiles: string[], baselineHit: string[], stagedTotal: number, attributedFiles: string[], undeclaredFiles: string[], foreignSessionDeclared: Array<{file: string, sessions: string[]}> }}
@@ -990,29 +1070,7 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
       }
       return foreignDeclaredIndex.get(f) || null
     }
-    const DANGEROUS_PATTERNS = [
-      'package.json',
-      'package-lock.json',
-      'yarn.lock',
-      'pnpm-lock.yaml',
-      '.eslintrc',
-      'tsconfig.json',
-      // SillySpec 核心流程代码。W6 重构后 src/run.js（23 行 barrel）/ src/progress.js（facade）
-      // 把真正逻辑下沉到 src/run/、src/progress/ 子目录——旧的精确文件名匹配
-      // （file === 'src/run.js'）命中不到 src/run/command.js（. 与 / 不可混同），致危险文件门
-      // 静默失效。改用「目录前缀（带尾斜杠，startsWith 不会误伤 src/runtime-* 等同名前缀）+
-      // barrel/facade 本体精确名」双重覆盖。重构 src/ 模块时须同步本清单（multi-agent-review Q5）。
-      'src/run.js',
-      'src/run/',
-      'src/progress.js',
-      'src/progress/',
-      'src/db.js',
-      'src/stage-contract.js',
-      'src/stage-contract-spec.js',
-      'src/worktree.js',
-      'src/worktree-apply.js',
-      'src/hooks/',
-    ]
+    const DANGEROUS_PATTERNS = QUICK_DANGEROUS_PATTERNS
 
     for (const entry of currentEntries) {
       // porcelain 两字符状态码（X=暂存区 Y=工作区）不能先 trim：' D'.trim()==='D' 使第二分支恒假、

package/src/run/stage.js

@@ -19,7 +19,7 @@
 import { join, dirname } from 'node:path'
 import { existsSync, readdirSync, readFileSync, mkdirSync } from 'node:fs'
 import { writeAtomicSync } from '../fs-atomic.js'
-import { resolveSpecDir, resolveChangeDir, resolveRuntimeRoot, resolveQuickSessionsDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps, warnApprovalUnknown } from './shared.js'
+import { resolveSpecDir, resolveChangeDir, resolveRuntimeRoot, resolveQuickSessionsDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps, warnApprovalUnknown, predictProtectedQuickFiles } from './shared.js'
 import { computeScanProfile, applyScanProfileSteps, executeScanPreflight, executeScanPostcheck } from './scan-profile.js'
 import { outputStep, collectStageWaitHistory } from './prompt.js'
 import { allocateQuicklogEntry, deriveTitleFromLinkedChange, sanitizeDesc } from '../quicklog.js'
@@ -328,6 +328,15 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
   // （D-003@v1：顶层 quickGuard 不跨进程持久化；agent 在 step 间用 `run quick` 取下一步
   // prompt 时每个新进程都进此块，按文件判幂等才不会重复分配 ql-ID / 重复写条目）。
   if (stageName === 'quick') {
+    // 受保护文件预告打印（坑 quick-protected-late-hint，2026-08-28 用户实证：scan 类文档
+    // ARCHITECTURE/CONCERNS 属受保护基线，--files 声明了照样拦、必须 --force-baseline——
+    // 设计合理但提示太晚。step1 即预告哪些声明文件会触发拦截，省一轮跑到 --done 才发现的往返）
+    const warnProtectedQuickFiles = (protectedFiles) => {
+      console.warn(`⚠️ 声明文件中 ${protectedFiles.length} 个属受保护/危险范围，--done 审计将拦截（--files 只声明归属，不解锁拦截）：`)
+      for (const f of protectedFiles) console.warn(`   - ${f}`)
+      console.warn(`   确认要改这类文件：本会话收尾带 --force-baseline（sillyspec run quick --done --force-baseline ...）；`)
+      console.warn(`   属误判或不该由本会话改：换出 --files 声明，或走完整流程（execute 有 review 把关）。`)
+    }
     // quick-sessions 目录经 resolveQuickSessionsDir 单一解析（multi-agent-review Q4）：
     // 平台模式 runtimeRoot 与 specBase/.runtime 不同时，写/读须对齐，否则 guard 写一处、收尾读另一处。
     const sessionGuardDir = join(resolveQuickSessionsDir(platformOpts, specBase), changeName)
@@ -348,6 +357,13 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         const known = new Set(progress.quickGuard.allowedFiles || [])
         const added = resumeFiles.filter(f => !known.has(f))
         if (added.length > 0) {
+          // 受保护文件预告（坑 quick-protected-late-hint）：追加声明若含审计将拦的文件，
+          // 追加时即点破（省一轮跑到 --done 才发现）。--files 只声明归属，不解锁拦截。
+          const protectedPreview = predictProtectedQuickFiles(added, {
+            linkedChanges: progress.quickGuard.linkedChanges || [],
+            forceBaseline: quickOpts?.isForceBaseline || false,
+          })
+          if (protectedPreview.length > 0) warnProtectedQuickFiles(protectedPreview)
           progress.quickGuard.allowedFiles = [...(progress.quickGuard.allowedFiles || []), ...added]
           progress.quickGuard.allowedFilesHash = { ...(progress.quickGuard.allowedFilesHash || {}) }
           for (const f of added) {
@@ -385,6 +401,10 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         const allowDelete = quickOpts?.isAllowDelete || false
         const forceBaseline = quickOpts?.isForceBaseline || false
         const linkedChanges = Array.isArray(quickOpts?.linkedChanges) ? quickOpts.linkedChanges : []
+        // 受保护文件预告（坑 quick-protected-late-hint）：会话起步（step1）即点破，
+        // 判定与 --done 审计危险门同口径（predictProtectedQuickFiles）
+        const protectedPreview = predictProtectedQuickFiles(allowedFiles, { linkedChanges, forceBaseline })
+        if (protectedPreview.length > 0) warnProtectedQuickFiles(protectedPreview)
         // CLI 接管：分配 ql-ID + 写 QUICKLOG「进行中」条目 + 关联 tasks.md（持锁、当天唯一）
         const gitUser = safeGit(cwd, ['config', 'user.name']).value || 'unknown'
         // 标题回退：启动 quick 不带 --input 时，从关联变更的 proposal/design 提取语义标题，

package/src/spec-sync.js

@@ -8,6 +8,11 @@
  *
  * 复用 daemon 已验证的排除口径（UPLOAD_EXCLUDE_TOP_BASE / UPLOAD_PRUNE_NAMES_BASE），
  * 与 daemon 共用同一套清单语义（base_version 乐观锁、conflict 提示但不阻塞）。
+ *
+ * 并行会话 fail-closed 护栏（computeSpecOps 空树/changes 整删守卫 + filterStaleUpdates
+ * 旧副本回推守卫）：共享同一平台工作空间的多会话/多机场景下，错锚或滞后本地的破坏性
+ * ops（整删 changes/、旧版内容回推）在发出前拦下——服务器侧一旦被破坏会经同步链路
+ * 落地回各端本地（2026-08-26/27 两次实证）。
  */
 
 import { createHash } from 'crypto';
@@ -140,6 +145,20 @@ export function computeSpecOps(serverManifest, localFiles) {
     return [];
   }
 
+  // 并行会话护栏（坑 spec-sync-parallel-changes-wipe，2026-08-26/27 两次实证：平台同步
+  // 删整个 changes 目录）：本地树非空但 changes/ 子树一个文件都没有、服务器却有——
+  // 几乎必然是错锚/新机未先落地，而非用户真删光了所有变更（archive 是移动不是清空）。
+  // 放行即服务器 changes/ 整树清空，再经 daemon/对端同步落地回本地（破坏本地）。
+  // 逐个变更目录的合法删除不受影响（本地仍有其他 changes/ 文件时不触发本护栏）。
+  const serverChanges = serverPaths.filter((p) => p.startsWith('changes/'));
+  const localChanges = localFiles.filter((f) => f.path.startsWith('changes/'));
+  if (localFiles.length > 0 && serverChanges.length > 0 && localChanges.length === 0) {
+    console.warn(
+      `[spec-sync] 本地 spec 树无 changes/ 文件但服务器有 ${serverChanges.length} 个，跳过同步（防并行会话/错锚整删 changes/；请检查 spec 目录锚点，新环境先完成平台侧文件落地）`
+    );
+    return [];
+  }
+
   // rename 检测：旧路径（服务器有、本地无）↔ 新路径（本地有、服务器无）hash 相同
   const renames = [];
   const consumedNew = new Set();
@@ -248,6 +267,62 @@ function collectChangeDir(dirs, p) {
   }
 }
 
+/**
+ * 过滤「旧副本回推」型 update op（坑 spec-sync-parallel-stale-overwrite，2026-08-26/27
+ * 两次实证：平台同步把本地文件覆盖回旧版）。
+ *
+ * 判据：本地文件 mtime 早于上次成功同步（mtime + 1s 缓冲）= 该文件自上次同步后本地从未
+ * 改动——此刻服务器 hash 却不同，只可能是他者会话/他机推进了服务器内容。本地这份是旧
+ * 副本，照推 update 就是把服务器内容回退到旧版（再经 daemon/对端落地破坏各端本地）。
+ * 本地改过的文件（mtime 晚于上次同步）不受影响，正常 last-writer-wins。
+ *
+ * 被滤掉的文件如确需以本地为准覆盖服务器：本地重存（touch/再编辑）后重推。
+ *
+ * @param {Array} ops computeSpecOps 产物
+ * @param {Array} localFiles hashFiles 产物（含 mtime，Unix 秒）
+ * @param {number|null} lastSyncTs 上次成功同步完成时刻（ms）；null/0 → 不过滤
+ * @returns {{ ops: Array, stale: string[] }} 过滤后 ops + 被拦下的路径
+ */
+export function filterStaleUpdates(ops, localFiles, lastSyncTs) {
+  if (!lastSyncTs || !Array.isArray(ops) || ops.length === 0) {
+    return { ops, stale: [] };
+  }
+  const mtimeByPath = new Map(localFiles.map((f) => [f.path, f.mtime]));
+  const stale = [];
+  const kept = [];
+  for (const op of ops) {
+    if (op.op === 'update') {
+      const mtime = mtimeByPath.get(op.path);
+      if (mtime !== undefined && mtime * 1000 + 1000 <= lastSyncTs) {
+        stale.push(op.path);
+        continue;
+      }
+    }
+    kept.push(op);
+  }
+  return { ops: kept, stale };
+}
+
+// 上次成功同步标记（本地 .runtime 下，walk 排除不上传）：filterStaleUpdates 的时间锚。
+const LAST_SUCCESS_MARKER = 'spec-sync-last-success.json';
+
+function readLastSyncTs(specRoot) {
+  try {
+    const raw = readFileSync(join(specRoot, '.runtime', LAST_SUCCESS_MARKER), 'utf8');
+    const ts = JSON.parse(raw).ts;
+    return Number.isFinite(ts) ? ts : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeLastSyncTs(specRoot) {
+  try {
+    mkdirSync(join(specRoot, '.runtime'), { recursive: true });
+    writeFileSync(join(specRoot, '.runtime', LAST_SUCCESS_MARKER), JSON.stringify({ ts: Date.now() }) + '\n', 'utf8');
+  } catch { /* 标记失败只损失下次的防回推过滤，不影响本次同步结果 */ }
+}
+
 /**
  * 同步本地 .sillyspec 树到平台（CLI 直跑增量同步入口）。
  *
@@ -292,7 +367,17 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
   // 2. walk/hash/diff
   const entries = walkSpecTree(specRoot);
   const localFiles = hashFiles(entries);
-  const ops = computeSpecOps(serverManifest, localFiles);
+  let ops = computeSpecOps(serverManifest, localFiles);
+
+  // 旧副本回推防护（并行会话一致性）：上次同步后本地从未改动的文件不回推覆盖服务器新内容
+  const lastSyncTs = readLastSyncTs(specRoot);
+  const filtered = filterStaleUpdates(ops, localFiles, lastSyncTs);
+  if (filtered.stale.length > 0) {
+    console.warn(
+      `[spec-sync] 拦下 ${filtered.stale.length} 个旧副本回推（本地自上次同步未改动而服务器已前进，如确需以本地为准：重存后重推）: ${filtered.stale.slice(0, 5).join(', ')}${filtered.stale.length > 5 ? ' 等' : ''}`
+    );
+  }
+  ops = filtered.ops;
 
   if (ops.length === 0) {
     debugLog(`[spec-sync] 无差异，跳过同步: ${changeName}`);
@@ -342,6 +427,7 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
       return { synced: 0, conflict: true, serverVersions, conflictPath };
     }
     console.log(`[spec-sync] 已同步 ${ops.length} 个文件变更: ${changeName}`);
+    writeLastSyncTs(specRoot);
     return { synced: ops.length };
   } catch (err) {
     console.warn(`[spec-sync] 同步异常（文件树本次未同步，下次自动重试）: ${changeName}: ${err.message}`);
@@ -354,5 +440,6 @@ export default {
   hashFiles,
   computeSpecOps,
   extractChangeDirs,
+  filterStaleUpdates,
   syncSpecTree,
 };

package/src/stages/archive.js

@@ -177,6 +177,11 @@ created_at: <now-datetime>
 ### 输出
 归档完成 + archive 目录路径`,
       outputHint: '归档确认',
+      // 坑 archive-batch-31-tool-notes ②：完成本步必须带 --confirm（complete-handlers 门控），
+      // 但 outputStep 机器生成的「完成后执行」提示原是通用 --done 模板不带 --confirm——agent
+      // 照抄执行就撞「请添加 --confirm」。requiresConfirm 让提示行带上该 flag（数据驱动，其他
+      // 阶段未来有确认步同样声明即可）。
+      requiresConfirm: true,
       optional: false
     },
     {

package/src/stages/execute.js

@@ -1214,6 +1214,7 @@ ${taskList}
 4. 每个任务完成后：
    - **在 worktree 内 git add -A && git commit -m "<task-NN 摘要>"**（坑 subagent-uncommitted-newfile-apply3way，2026-08-22 实证：纯新增文件不 commit 时 apply 的 git apply --3way 报 "does not exist in index" 直接炸——未 commit 的新文件不在 base commit 也不在 index，patch 生成取不到。commit 后 base..HEAD diff 完整、apply 顺畅，review.json 的 head 也有真实锚点）
    - **先写 review.json 再勾选 checkbox**（见下方 Task Review Gate）
+   - **任务边界上报（每任务一次，主仓根目录）**：勾选 checkbox 后跑一次 \`sillyspec platform sync --change <change-name>\`——以任务粒度把「最后信号」（last_pushed_at）与 tasks.md 勾选状态推上平台（变更中心「进行中」可见性）；未连接平台时该命令静默跳过，无需先检查连接状态
    - **既跑 lint check 也跑 formatter**：凡变更涉及的源码跑项目的 lint 检查 **和** 格式化（如 \`ruff format\` / \`prettier --write\`），不要只跑 check——只 check 不 format 会把格式问题留到 commit 时被 pre-commit hook 拦截（worktree 内二进制可能缺失，先 \`which <bin>\` 确认，缺则 \`uv tool install\` / \`uv sync\`）
    - 记录改动文件和测试结果
 5. 遇到 BLOCKED → 记录原因，选择：重试/跳过/停止
@@ -1265,10 +1266,11 @@ task-XX 对应：{SPEC_ROOT}/.runtime/execute-runs/{EXECUTE_RUN_ID}/tasks/task-X
 
 ### 完成后
 1. 为每个后端 router task 生成 API 端点 artifact——**用 CLI 命令，勿手扫装饰器手写（易漏 endpoint）**：
-   - 逐 task 运行：sillyspec endpoints extract --change <change> --task <task-NN>（<change> = 当前变更名）
+   - 聚合一次跑全：sillyspec endpoints extract --change <change> --all-tasks（逐 task 卡 allowed_paths 各自提取落盘，<change> = 当前变更名；与 verify 探针 5 聚合对账口径一致）
    - CLI 静态扫描变更文件（FastAPI @router.* / Express router.* / Spring @*Mapping）生成
      {SPEC_ROOT}/.runtime/contract-artifacts/<task-name>/endpoints.json
    - 格式: { "task": "task-XX", "type": "backend_endpoints", "endpoints": [{ "method": "GET", "path": "/api/ppm/xxx" }] }（CLI 已按此格式写好，verify 探针 5 直接消费）
+   - 只提单 task（--task task-NN）会让探针 5 用局部端点集对账放大假 missing——多 task 变更必用 --all-tasks
 `
 }