sillyspec 3.27.1 → 3.27.5

package/src/run/shared.js

@@ -11,7 +11,7 @@
  *     本模块仅 re-export，run/ 层现有调用方路径与行为不变。
  */
 import { basename, join, resolve, dirname, sep } from 'node:path'
-import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, appendFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, appendFileSync, realpathSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import os from 'node:os'
 
@@ -329,6 +329,55 @@ export function resolveQuickSessionsDir(platformOpts, localSpecBase) {
   return join(resolveRuntimeRoot(platformOpts, localSpecBase), 'quick-sessions')
 }
 
+// 他者会话声明豁免的僵尸阈值：超龄会话的声明不再作为豁免依据。与 doctor 幽灵清理
+// GHOST_EMPTY_DIR_STALE_MS 同口径（7 天）——正常并发会话间隔在分钟/小时级，7 天未收尾的
+// 会话按僵尸处理，防崩溃残留的 guard 永久「认领」文件侵蚀危险门。
+const FOREIGN_SESSION_STALE_MS = 7 * 24 * 60 * 60 * 1000
+
+/**
+ * 枚举其他 active quick 会话的显式文件声明（坑 foreign-session-declared-false-block）。
+ *
+ * 多 agent 并发时，并行 quick 会话在**本会话启动后**改的文件不在本会话 baseline →
+ * auditQuickCompletion 把它算进本会话窗口 → 命中危险清单（src/run/、package.json 等）或
+ * .sillyspec/ 判定即 blocked，只能 --force-baseline 无差别逃生。豁免口径 = 他者会话的
+ * **显式声明**（guard.allowedFiles，--files 传入）——他者的 baselineFiles 是「启动时已脏」
+ * 快照而非所有权声明，不作豁免依据（否则任何预存脏文件都能被洗白）。
+ *
+ * fail-open：目录不存在/损坏 guard.json/超龄僵尸/任何异常 → 跳过或整体返回 []，
+ * 采集失败回到无豁免现状（不放大豁免面）。
+ *
+ * @param {object} [platformOpts] 平台选项（resolveQuickSessionsDir 同参）
+ * @param {string} localSpecBase 本地 specBase（resolveQuickSessionsDir 同参）
+ * @param {string} currentSessionId 当前会话 sessionId（quick-<hex8>），枚举时排除
+ * @param {number} [nowMs] 当前时间戳（可注入，测试用）
+ * @returns {Array<{sessionId: string, files: string[]}>} 其他 active 会话的声明清单
+ */
+export function collectOtherQuickSessionDeclarations(platformOpts, localSpecBase, currentSessionId, nowMs = Date.now()) {
+  const out = []
+  try {
+    const sessionsDir = resolveQuickSessionsDir(platformOpts, localSpecBase)
+    let sessionDirs = []
+    try {
+      sessionDirs = readdirSync(sessionsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name)
+    } catch { return out } // 目录不存在/不可读 → 无他者会话
+    for (const sessionName of sessionDirs) {
+      if (sessionName === currentSessionId) continue
+      const guardFile = join(sessionsDir, sessionName, 'guard.json')
+      let guard = null
+      try { guard = JSON.parse(readFileSync(guardFile, 'utf8')) } catch { continue } // 损坏/缺失跳过
+      // 僵尸防御：超龄会话（崩溃残留，--done/--cancel 都不会再走）的声明不再认领文件
+      if (guard.startedAt) {
+        const startedAtMs = Date.parse(guard.startedAt)
+        if (Number.isFinite(startedAtMs) && nowMs - startedAtMs > FOREIGN_SESSION_STALE_MS) continue
+      }
+      const files = (Array.isArray(guard.allowedFiles) ? guard.allowedFiles : []).filter(f => typeof f === 'string' && f)
+      if (files.length === 0) continue
+      out.push({ sessionId: guard.sessionId || sessionName, files })
+    }
+  } catch { /* fail-open：整体异常返回已采集部分 */ }
+  return out
+}
+
 /**
  * 平台指针三写（单一数据源，runCommand scan 与 cmdInit 平台模式共用）。
  *
@@ -355,6 +404,15 @@ export const PLATFORM_MANAGED_FILENAME = '.sillyspec-platform-managed'
 
 export function writePlatformPointer(cwd, platformOpts, extra = {}) {
   if (!platformOpts || (!platformOpts.specRoot && !platformOpts.runtimeRoot)) return false
+  // 自指写入拦截（FR-4，变更 2026-08-23-repo-native-spec-backfill）：specRoot 经 realpath
+  // 解析回本地 .sillyspec（repo-native junction 回环）时拒绝三写（主文件/指针/声明全不落盘）。
+  // 单点收口同时覆盖 runCommand 与 cmdInit(writeInitPlatformPointer) 两调用方——旧模板
+  // scan flag / init 平台模式显式传自指 specRoot 也不再重新投毒。runtimeRoot-only 组合
+  // 无 specRoot 可判（isSelfReferentialSpecRoot 对 null 恒 false），原语义不变。
+  if (isSelfReferentialSpecRoot(cwd, platformOpts.specRoot)) {
+    console.warn(`⚠️ 检测到自指平台指针（repo-native junction 回环，specRoot 指回本地 .sillyspec），已跳过指针写入并按本地模式运行: ${platformOpts.specRoot}`)
+    return false
+  }
   // HUB-05：合并保留既有生命周期字段。scan 完成时指针被写入 status/completedAt/scanStatus
   //（complete-handlers），但下一次任何平台模式 run（含只读 --status）都会重写指针——
   // 恢复链只回填 specRoot 等四字段，不保留 status → 指针永远回 active、isPointerStale
@@ -427,6 +485,48 @@ export function checkPlatformManaged(cwd) {
   }
 }
 
+/**
+ * 自指 specRoot 判定（repo-native junction 回环检测，变更 2026-08-23-repo-native-spec-backfill）。
+ *
+ * daemon repo-native 工作区把缓存目录（--spec-root 入参，~/.sillyhub/daemon/specs/{ws}）以
+ * junction/symlink 指回源项目 <cwd>/.sillyspec——该 specRoot 经 realpath 解析后与本地
+ * .sillyspec 同物理目录，属"自指回环"：不应让 CLI 进入平台模式（内置 sync / auto-pull
+ * 按本地模式语义运行，断链修复见 design.md Phase 2）。
+ *
+ * 双方 fs.realpathSync（native，junction/symlink 跨平台穿透）后严格相等 → true；
+ * specRoot 空 / 任一路径不存在 / realpath 抛错 → false（按外部目录处理，保守不干预）。
+ * 约束：cwd 必须为项目根（与指针查找 join(cwd,'.sillyspec-platform.json') 同基准）。
+ *
+ * @param {string} cwd - 项目根
+ * @param {string|null} [specRoot] - 平台 specRoot（可 null/undefined/空串）
+ * @returns {boolean} 是否自指回环
+ */
+export function isSelfReferentialSpecRoot(cwd, specRoot) {
+  if (!specRoot || typeof specRoot !== 'string') return false
+  try {
+    return realpathSync(specRoot) === realpathSync(join(cwd, '.sillyspec'))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 平台模式判定单一数据源（自指免疫，变更 2026-08-23-repo-native-spec-backfill）。
+ *
+ * 语义：(specRoot || runtimeRoot) 存在且非自指 → 平台模式；自指回环（repo-native
+ * junction）按本地模式处理。本模块内平台模式门禁统一经本函数，裸表达式仅此一处
+ * （grep 验证：triggerSync/triggerPull/triggerPullActiveChange/checkApproval 四处收敛）。
+ * runtimeRoot 落在 specRoot 内，自指判定以 specRoot 为准即可覆盖；runtimeRoot-only
+ * 组合无 specRoot 可判，不触发自指豁免（保持平台模式）。
+ *
+ * @param {object} [platformOpts] - { specRoot?, runtimeRoot?, ... }（可 null/undefined）
+ * @param {string} cwd - 项目根（isSelfReferentialSpecRoot 同基准）
+ * @returns {boolean}
+ */
+export function isPlatformMode(platformOpts, cwd) {
+  return Boolean((platformOpts?.specRoot || platformOpts?.runtimeRoot) && !isSelfReferentialSpecRoot(cwd, platformOpts?.specRoot))
+}
+
 /**
  * 统一查找变更目录（与 progress.js 的变更检测逻辑一致）。
  */
@@ -483,8 +583,8 @@ async function raceWithAbort(op, timeoutMs = SYNC_TOTAL_TIMEOUT_MS) {
 export const QUICK_SID_RE = /^quick-[0-9a-f]{8}$/
 
 export async function triggerSync(cwd, changeName, platformOpts = {}, opts = {}) {
-  // 平台模式（SillyHub）走自己的回传链路，不走 CLI 内置 sync
-  if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return
+  // 平台模式（SillyHub）走自己的回传链路，不走 CLI 内置 sync；自指回环（repo-native junction）按本地模式处理
+  if (isPlatformMode(platformOpts, cwd)) return
   try {
     // ql-20260818-011：quick 会话按设计无实体变更目录（progress.js initChange 同款
     // 跳过建目录），progress/四件套上行对它是孤儿数据；但 spec 树增量（QUICKLOG/
@@ -556,8 +656,8 @@ function _stampAutoPull(cwd) {
  * @param {object} [platformOpts] - 平台模式 opts（specRoot/runtimeRoot 存在则跳过，走平台自有链路）
  */
 export async function triggerPull(cwd, changeName, platformOpts = {}, opts = {}) {
-  // 平台模式（SillyHub）走自己的链路，跳过
-  if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return
+  // 平台模式（SillyHub）走自己的链路，跳过；自指回环（repo-native junction）按本地模式处理
+  if (isPlatformMode(platformOpts, cwd)) return
   try {
     const syncMod = await import('../sync.js')
     const sm = new syncMod.SyncManager(cwd)
@@ -579,7 +679,8 @@ export async function triggerPull(cwd, changeName, platformOpts = {}, opts = {})
  * 供 index.js 在 stage 命令（run/--done/archive）与 approve 决策点注入一行调用。
  */
 export async function triggerPullActiveChange(cwd, platformOpts = {}) {
-  if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return
+  // 平台模式走自己的链路，跳过；自指回环（repo-native junction）按本地模式处理
+  if (isPlatformMode(platformOpts, cwd)) return
   // 先检查是否连接平台：未连接直接 return，避免 _ensureDB 在无 local.yaml 的 cwd 创建空 DB 污染
   let sm = null
   try {
@@ -645,8 +746,8 @@ export function warnApprovalUnknown(cwd, changeName, reason) {
  * 平台模式走自己的链路，跳过；否则 await import sync.js。
  * @returns {{ status: string, reason?: string } | null}
  */export async function checkApproval(cwd, changeName, platformOpts = {}) {
-  // 平台模式不需要 CLI 内置审批检查
-  if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return null
+  // 平台模式不需要 CLI 内置审批检查；自指回环（repo-native junction）按本地模式处理
+  if (isPlatformMode(platformOpts, cwd)) return null
   try {
     // shared.js 在 src/run/，sync.js 在 src/ → 退一层
     const syncMod = await import('../sync.js')
@@ -708,7 +809,7 @@ export function isQuickMetadata(p, linkedChanges = []) {
 
 /**
  * quick 完成审计：对比 baseline 与实际变更。
- * @returns {{ status: 'safe'|'warning'|'blocked', reasons: string[], changedFiles: string[], newFiles: string[], deletedFiles: string[], baselineHit: string[], stagedTotal: number, attributedFiles: string[], undeclaredFiles: string[] }}
+ * @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[]}> }}
  */
 /**
  * D-8 O-1 模块归属（2026-08-15 docs-signals-o12）：quick 欠账 hint 从"改了 N 文件"升级为
@@ -818,7 +919,7 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
   // stagedTotal：当前所有非 quick 元数据的未提交条目（含前序 baseline 残留）。
   // 与 changedFiles（扣 baseline 后的本轮新增）区分，供审计文案同时展示「本轮新增 vs 累计暂存」，
   // 避免叠加 quick 会话时把前序会话未提交文件误读为「本会话只动了 N 个」。
-  const result = { status: 'safe', reasons: [], changedFiles: [], newFiles: [], deletedFiles: [], baselineHit: [], stagedTotal: 0, attributedFiles: [], undeclaredFiles: [] }
+  const result = { status: 'safe', reasons: [], changedFiles: [], newFiles: [], deletedFiles: [], baselineHit: [], stagedTotal: 0, attributedFiles: [], undeclaredFiles: [], foreignSessionDeclared: [] }
 
   try {
     // safeGit 带 -c safe.directory，避免 linked worktree/容器异 uid/挂载点下裸 `git status` 抛错被
@@ -851,6 +952,38 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
       const f = normalizeGitPath(p)
       return baselineExact.has(f) || baselineDirs.some(d => f.startsWith(d))
     }
+    // 他者 active 会话声明索引（坑 foreign-session-declared-false-block，2026-08-23 实证：多 agent
+    // 并发时并行会话窗口内改的文件——尤其命中危险清单的（daemon/router.py 之于本仓是 src/run/*、
+    // package.json）或 .sillyspec/ 下的——不在本会话 baseline，被算进本会话窗口直接 blocked，
+    // 只能 --force-baseline 无差别逃生）。声明即归属的他向版本：他者会话显式声明（--files）的文件
+    // 退栈归该会话审计。本会话也声明同一文件（--files 重叠）时不退栈——同文件并发归本会话审计
+    // （sameFileHits advisory 管辖）。豁免面 = 他者显式声明，不含他者 baseline 快照（那是「启动时
+    // 已脏」非所有权声明，当豁免依据会洗白任何预存脏文件）。
+    const ownDeclaredNorm = new Set((allowedFiles || []).map(f => normalizeGitPath(f)))
+    const foreignDeclaredIndex = new Map()
+    for (const s of Array.isArray(guard.otherSessionsDeclared) ? guard.otherSessionsDeclared : []) {
+      if (!s || typeof s !== 'object') continue
+      for (const f of Array.isArray(s.files) ? s.files : []) {
+        const nf = normalizeGitPath(f)
+        if (!nf || ownDeclaredNorm.has(nf)) continue
+        if (!foreignDeclaredIndex.has(nf)) foreignDeclaredIndex.set(nf, [])
+        if (!foreignDeclaredIndex.get(nf).includes(s.sessionId)) foreignDeclaredIndex.get(nf).push(s.sessionId)
+      }
+    }
+    const findForeignDeclaredOwner = (p) => {
+      const f = normalizeGitPath(p)
+      if (f.endsWith('/')) {
+        // 折叠目录 token（porcelain 把全新未跟踪目录折成 `dir/`）：目录下任一文件被他者声明 →
+        // 整目录归他者；但本会话在同目录下有声明时不退栈——目录内混有双方文件，留给各门判定
+        // （fail-closed：宁可误拦不可漏放，误拦有 --files 追加声明的明确出口）。
+        if ([...ownDeclaredNorm].some(x => x.startsWith(f))) return null
+        for (const [nf, owners] of foreignDeclaredIndex) {
+          if (nf.startsWith(f)) return owners
+        }
+        return null
+      }
+      return foreignDeclaredIndex.get(f) || null
+    }
     const DANGEROUS_PATTERNS = [
       'package.json',
       'package-lock.json',
@@ -891,6 +1024,15 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
       // 预存脏文件：step1 baseline 已记录，非本次 quick 产生，跳过审计（含折叠目录前缀匹配）
       if (isBaselineFile(file)) continue
 
+      // 他者 active 会话已声明 → 完全退栈归该会话审计（危险/删除/新增/越界/baseline 全部门跳过），
+      // 收进 foreignSessionDeclared 供 printQuickAuditReview 软警告——放行可见可审计不静默
+      // （与 linkedChangeLeftovers 同哲学）。stagedTotal 已在上方计数，累计暂存口径不受退栈影响。
+      const foreignOwners = findForeignDeclaredOwner(file)
+      if (foreignOwners) {
+        result.foreignSessionDeclared.push({ file, sessions: foreignOwners })
+        continue
+      }
+
       result.changedFiles.push(file)
       if (rawStatus[0] === 'D' || rawStatus[1] === 'D') result.deletedFiles.push(file)
       if (status === '??') result.newFiles.push(file)
@@ -902,10 +1044,26 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
 
       // 检查危险文件（除非 force-baseline）
       if (file.startsWith('.sillyspec/') && !isQuickMetadata(file, guard.linkedChanges) && !forceBaseline) {
+        // 关联变更目录遗留放行（坑 linked-change-leftover-false-block，2026-08-22 实证：并发下
+        // 关联变更目录里他者/上个 session 的遗留脏文件——审计时不在本会话 baseline（启动后出现）
+        // 且 isQuickMetadata 对关联变更目录不豁免 → 落「危险文件」blocked，只能 --force-baseline。
+        // quick 无法区分「他者遗留」与「本次偷改」，按用户裁决放行降 warning：完全剔除出本会话
+        // 归属（changedFiles/newFiles/deletedFiles 均退栈），不计文件行、不触发危险/新增/越界
+        // 三道门，遗留给关联变更自己的流程收尾。非关联的 .sillyspec/ 仍 blocked。
+        const linkedDir = (Array.isArray(guard.linkedChanges) ? guard.linkedChanges : [])
+          .find(lc => file.startsWith(`.sillyspec/changes/${String(lc).replace(/\\/g, '/')}/`))
+        if (linkedDir) {
+          result.changedFiles.pop()
+          if (status === '??') result.newFiles.pop()
+          if (rawStatus[0] === 'D' || rawStatus[1] === 'D') result.deletedFiles.pop()
+          result.linkedChangeLeftovers = result.linkedChangeLeftovers || []
+          result.linkedChangeLeftovers.push(file)
+          continue
+        }
         result.reasons.push(`危险文件变更: ${file}`)
       }
 
-      if (DANGEROUS_PATTERNS.some(p => file === p || file.startsWith(p)) && !forceBaseline) {
+      if (DANGEROUS_PATTERNS.some(p => p === file || file.startsWith(p)) && !forceBaseline) {
         result.reasons.push(`危险文件变更: ${file}`)
       }
     }
@@ -1069,6 +1227,13 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
           console.warn(`   - ${f}`)
           console.warn(`     分离：git add -p ${f}（交互选你的 hunk）或 git diff ${f} > mine.patch（编辑留你的）+ git apply --cached mine.patch`)
         }
+        // 宽严差异明示（坑 concurrent-policy-inconsistency，2026-08-22 实证：quick 同文件并发只
+        // warn 不阻断、plan 阶段同 Wave 同文件却硬拦——两阶段宽严不一致易误判边界）。差异是设计
+        // 使然：quick 是轻量流程无子代理并行，同文件并发最坏后果是 commit 夹带他者 hunk（git 可
+        // 分离，提示分离命令即可）；plan 的同 Wave 同文件会让 execute 的并行子代理互相覆盖（不可
+        // 自动恢复），必须设计期硬拦。
+        console.warn(`   ℹ️ 边界说明：quick 对同文件并发只提示不阻断（最坏后果=commit 夹带他者 hunk，git 可分离）；`)
+        console.warn(`      plan 阶段同 Wave 同文件是硬错误（execute 并行子代理会互相覆盖，不可自动恢复）——两阶段宽严不同是设计使然，勿以 quick 的宽松推断 plan 的边界。`)
       }
     }
 

package/src/run/stage.js

@@ -162,6 +162,29 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
     } catch { /* 预警失败不阻断 execute */ }
   }
 
+  // ── 共享主仓竞态防护（坑 parallel-shared-main-race，2026-08-23 实证：并行会话共享主仓
+  // 工作区/共享部署库的竞态——文件被清、alembic 被推进、staged 混入他者文件）。execute/verify
+  // 启动时探测三类信号并 advisory（不阻断——并发是合法工作模式，但要让 agent 知道环境在变）：
+  //   1. 主仓未提交改动中含非本变更文件（staged 混入：commit 时注意 pathspec）
+  //   2. worktree 存在时 base..HEAD 主仓推进（主仓在他者 apply 后已前进，diff 口径注意）
+  // best-effort：异常静默。
+  if ((stageName === 'execute' || stageName === 'verify') && changeName) {
+    try {
+      const mainDirty = (safeGit(cwd, ['status', '--porcelain'], { trim: false }).value || '')
+        .split('\n').filter(Boolean).map(l => l.slice(3).trim().split(' -> ').pop() || '')
+        .map(p => p.replace(/^"|"$/g, '').replace(/\\/g, '/'))
+        .filter(p => p && !p.startsWith('.sillyspec/'))
+      const myFiles = (await import('../verify-postcheck.js')).resolveVerifyChangedFiles(cwd, changeName, null, { includeWorkingTree: true }) || []
+      const mySet = new Set(myFiles.map(f => f.replace(/\\/g, '/')))
+      const foreign = mainDirty.filter(p => !mySet.has(p))
+      if (foreign.length > 0) {
+        console.warn(`⚠️ 主仓含 ${foreign.length} 个非本变更的未提交文件（并行会话工作/部署产物混入）——`)
+        console.warn(`   提交时用精确 pathspec（勿 git add -A / 目录级 add 夹带）：${foreign.slice(0, 4).join(', ')}${foreign.length > 4 ? ` …` : ''}`)
+        console.warn(`   交接物核对（文件被清/迁移被推进类异常）先确认是否他者会话所谓，再判定本变更问题。`)
+      }
+    } catch { /* 探测失败不阻断 */ }
+  }
+
   // 自动探测 currentChange
   if (autoDetectChange(progress, cwd)) {
     progress.lastActive = new Date().toLocaleString('zh-CN', { hour12: false })

package/src/run.js

@@ -15,8 +15,8 @@
  */
 // W6 Step8c: 主命令分发（runCommand）+ auto 模式 + ensureStageSteps 搬至 ./run/command.js
 export { runCommand, ensureStageSteps } from './run/command.js'
-// barrel re-export: parsePorcelainPath + auditQuickCompletion + isQuickMetadata 被 test 直接 import（契约保留）
-export { parsePorcelainPath, auditQuickCompletion, isQuickMetadata } from './run/shared.js'
+// barrel re-export: parsePorcelainPath + auditQuickCompletion + isQuickMetadata + collectOtherQuickSessionDeclarations 被 test 直接 import（契约保留）
+export { parsePorcelainPath, auditQuickCompletion, isQuickMetadata, collectOtherQuickSessionDeclarations } from './run/shared.js'
 // barrel re-export: applyRootPlaceholders 被 test/prompt-placeholders.test.mjs 直接 import（契约保留）
 export { applyRootPlaceholders } from './run/prompt.js'
 // barrel re-export: sanitizeProjectName + validateParsedProjects 被 test 直接 import（随 handleScan 搬走，契约保留）

package/src/scan-postcheck.js

@@ -10,6 +10,7 @@ import { join, basename } from 'path'
 import { SCAN_STATUS, CHECK_SEVERITY, SCAN_REQUIRED_DOCS, SCAN_REQUIRED_DOCS_QUICK } from './constants.js'
 import { validateScriptCommands } from './stages/cmd-existence.js'
 import { git } from './git-helper.js'
+import { nowWallClock } from './datetime.js'
 
 const REQUIRED_SCAN_DOCS = SCAN_REQUIRED_DOCS
 
@@ -394,7 +395,7 @@ export function fixScanDocHeaders({ cwd, specDir = null, project = null }) {
   try {
     author = git(cwd, ['config', 'user.name']) || 'unknown'
   } catch { /* git 不可用 → unknown */ }
-  const now = new Date().toISOString().slice(0, 19).replace('T', ' ')
+  const now = nowWallClock()
 
   const fixed = []
   const skipped = []
@@ -410,26 +411,13 @@ export function fixScanDocHeaders({ cwd, specDir = null, project = null }) {
       } catch {
         continue
       }
-      const header = content.slice(0, 512)
-      const hasAuthor = /author\s*:/.test(header)
-      const hasCreated = /created_at\s*:/.test(header)
-      if (hasAuthor && hasCreated) {
+      const r = backfillFrontmatter(content, { author, createdAt: now })
+      if (!r.changed) {
         skipped.push(filePath)
         continue
       }
-      const inserts = []
-      if (!hasAuthor) inserts.push(`author: ${author}`)
-      if (!hasCreated) inserts.push(`created_at: ${now}`)
-      let newContent
-      if (content.startsWith('---\n') || content.startsWith('---\r\n')) {
-        // 有 frontmatter：插到开标签后（CRLF 归一写回，与其它 CLI 写入口径一致）
-        const normalized = content.replace(/\r\n?/g, '\n')
-        newContent = normalized.replace(/^---\n/, `---\n${inserts.join('\n')}\n`)
-      } else {
-        newContent = `---\n${inserts.join('\n')}\n---\n\n` + content
-      }
       try {
-        writeFileSync(filePath, newContent)
+        writeFileSync(filePath, r.content)
         fixed.push(filePath)
       } catch { /* 只读文件等写失败 → 跳过不抛 */ }
     }
@@ -437,6 +425,31 @@ export function fixScanDocHeaders({ cwd, specDir = null, project = null }) {
   return { fixed, skipped }
 }
 
+/**
+ * 通用 frontmatter 补齐（纯函数）：首 512 字节缺 author:/created_at: 时补缺失键。
+ * 有 frontmatter（--- 开头）→ 插到开标签后（CRLF 归一 LF 写回）；无 → 头部整块前置。
+ * fixScanDocHeaders 与 decisions.md 自动补（stage-contract.js ensureDecisionDocHeader）共用，
+ * 单一实现杜绝两处行尾/插入位置漂移。
+ * @param {string} content
+ * @param {{ author: string, createdAt: string }} p
+ * @returns {{ changed: boolean, content: string }}
+ */
+export function backfillFrontmatter(content, { author, createdAt }) {
+  const header = String(content || '').slice(0, 512)
+  const hasAuthor = /author\s*:/.test(header)
+  const hasCreated = /created_at\s*:/.test(header)
+  if (hasAuthor && hasCreated) return { changed: false, content }
+  const inserts = []
+  if (!hasAuthor) inserts.push(`author: ${author}`)
+  if (!hasCreated) inserts.push(`created_at: ${createdAt}`)
+  if (content.startsWith('---\n') || content.startsWith('---\r\n')) {
+    // 有 frontmatter：插到开标签后（CRLF 归一写回，与其它 CLI 写入口径一致）
+    const normalized = content.replace(/\r\n?/g, '\n')
+    return { changed: true, content: normalized.replace(/^---\n/, `---\n${inserts.join('\n')}\n`) }
+  }
+  return { changed: true, content: `---\n${inserts.join('\n')}\n---\n\n` + content.replace(/\r\n?/g, '\n') }
+}
+
 /**
  * source_root 污染一键修复（2026-08-21 agent-手工产出审计第四批 C-3）。
  *

package/src/stage-contract-spec.js

@@ -403,8 +403,9 @@ const PLAN_RULES = [
       messageVerify: '${id}: 缺少 verify 字段',
       messageConstraints: '${id}: 缺少 constraints 字段',
       messageDependsOnMissing: '${id}: depends_on 引用了不存在的 ${dep}',
+      messagePlaceholder: '${id}: task 卡仍是未填充的生成骨架（${fields} 里的占位符未替换）——占位符视同缺字段。用 Edit 填充 tasks/${id}.md 后重跑（勿删字段勿留 FR-XX/src/example/file.ts/具体步骤 等占位值）',
     },
-    spec: 'task 卡片完整 TaskCard schema(可行性,只认 frontmatter 字段,均 error):YAML frontmatter 必备;frontmatter 需 id、title;allowed_paths 非空;frontmatter 需 goal、implementation、acceptance、verify、constraints 五字段;depends_on 引用的 task 必须存在。',
+    spec: 'task 卡片完整 TaskCard schema(可行性,只认 frontmatter 字段,均 error):YAML frontmatter 必备;frontmatter 需 id、title;allowed_paths 非空;frontmatter 需 goal、implementation、acceptance、verify、constraints 五字段;depends_on 引用的 task 必须存在;骨架占位符(FR-XX/D-XXX/src/example/file.ts/一句话说明这个 task/具体步骤 1/可验证的验收条件 1/边界约束 1)未替换视同缺字段。',
     failMessage: '${id}: task 卡片 frontmatter 缺少必要字段(id/title/allowed_paths/goal/implementation/acceptance/verify/constraints)',
   },
 ]

package/src/stage-contract.js

@@ -5,13 +5,15 @@
  * CLI 不再相信 prompt 完成，completeStep 后必须过 validator。
  */
 
-import { existsSync, readdirSync, readFileSync } from 'fs'
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'fs'
 import { join, basename } from 'path'
 import { safeGit } from './git-helper.js'
+import { nowWallClock } from './datetime.js'
 import { detectChangeRisk, checkIntegrationEvidence, VERIFICATION_NEEDS, RISK_LEVEL_CAUSES } from './change-risk-profile.js'
 import { SCAN_REQUIRED_DOCS, AUXILIARY_STAGES } from './constants.js'
 import { evaluateRules } from './stage-contract-engine.js'
 import { getRule } from './stage-contract-spec.js'
+import { backfillFrontmatter } from './scan-postcheck.js'
 import { parseAllowedPaths } from './stages/plan-postcheck.js'
 
 /**
@@ -163,6 +165,31 @@ function parseDecisionRecords(content) {
   return records
 }
 
+/**
+ * decisions.md 缺 author/created_at header 时自动补齐（坑 decisions-header-late-warning，
+ * 2026-08-24 用户反馈二期：brainstorm step8 模板曾自带无 frontmatter 的 decisions 样例——
+ * agent 照抄生成必缺 header，拖到后续环节才提示。模板已修；本函数兜存量：gate 前幂等补
+ * 机械字段（author=git user / created_at=now），与 scan-fix-headers 同一 backfillFrontmatter 实现。
+ * @param {string} changeDir - changes/<name> 目录
+ * @returns {boolean} true = 本次补齐过（false = 无 decisions.md / header 已齐 / 写失败）
+ */
+export function ensureDecisionDocHeader(changeDir) {
+  try {
+    const decisionPath = join(changeDir, 'decisions.md')
+    if (!existsSync(decisionPath)) return false
+    const content = readFileSync(decisionPath, 'utf8')
+    let author = 'unknown'
+    const gitUser = safeGit(changeDir, ['config', 'user.name'])
+    if (gitUser && gitUser.value) author = String(gitUser.value).trim() || 'unknown'
+    const r = backfillFrontmatter(content, { author, createdAt: nowWallClock() })
+    if (!r.changed) return false
+    writeFileSync(decisionPath, r.content)
+    console.log(`ℹ️  已自动补齐 decisions.md 缺失的 author/created_at header: ${decisionPath}`)
+    return true
+  } catch { /* 补齐失败不阻断 gate——decisions 内容校验照常进行 */ }
+  return false
+}
+
 function extractCurrentDecisionIds(content) {
   const records = parseDecisionRecords(content)
   if (records.length === 0) return extractIds(content, 'D')
@@ -286,6 +313,27 @@ function validateBrainstormOutputs(cwd, changeName, context = {}) {
         }
       }
     }
+
+    // ── 风险判级提前提示（坑 risk-first-use-opaque，2026-08-24 用户实证）──
+    // verify --done 的 risk gate 既往只在流程末段暴露，首次使用者撞墙后才知道 frontmatter
+    // risk_level 覆盖通道。design --done 即按同款 detectChangeRisk 预判一次（此时 plan.md 尚未
+    // 产出，verify 时会连 plan 一起重判、级别可能上浮——本提示 advisory 不作为定论）：
+    // 高危关键词命中 / 存在否定抑制 → 透出判级结果 + 覆盖指引，把机制可见性提前到 design 阶段。
+    {
+      const profile = detectChangeRisk({ designContent: content })
+      if (['integration-critical', 'deployment-critical'].includes(profile.level) && !profile.explicit) {
+        warnings.push(
+          `[risk] 本次 design 判级 ${profile.level}（命中关键词：${profile.triggers.join('、')}）——verify --done 将强制真实集成证据门控。` +
+          `若属关键词误伤（实际未触碰 daemon/session/启动入口），现在就在 design.md frontmatter 加 risk_level: <真实等级>（如 unit-sufficient）显式覆盖，免得到 verify 阶段才发现而返工。`
+        )
+      }
+      if ((profile.suppressedTriggers || []).length > 0) {
+        warnings.push(
+          `[risk] 关键词命中 ${profile.suppressedTriggers.join('、')} 已被同句否定语境抑制，当前判级 ${profile.level}。` +
+          `若实际涉及对应改动，请在 design.md frontmatter 声明高危级（抑制可审计，防静默降级逃证据门控）。`
+        )
+      }
+    }
   }
 
   const decisionsFile = join(changeDir, 'decisions.md')
@@ -461,11 +509,22 @@ function validateVerifyOutputs(cwd, changeName, context = {}) {
       planContent: readIfExists(join(changeDir, 'plan.md')),
     })
     const conclusion = extractVerifyConclusion(verify)
+    // ── 否定抑制审计（坑 risk-negation-blindness）──
+    // 关键词命中被同句否定语境抑制而不参与判级时必须透出：抑制是把双刃剑（「本次不新增
+    // daemon」真豁免 vs 靠堆否定措辞静默降级逃证据门控），这里让每次抑制可见可核对；
+    // frontmatter risk_level 仍是双向权威覆盖通道。
+    if ((changeRiskProfile.suppressedTriggers || []).length > 0) {
+      warnings.push(
+        `[${changeRiskProfile.level}] 风险判级：关键词命中 ${changeRiskProfile.suppressedTriggers.join(', ')} 已被同句否定语境（不/未/无/避免…）抑制，未参与判级。` +
+        `若本变更实际涉及跨进程/状态机/启动入口改动，请在 design.md frontmatter 加 risk_level: integration-critical（或 deployment-critical）显式声明或提供真实集成证据——抑制可审计，不许用来静默降级。`
+      )
+    }
     if (['integration-critical', 'deployment-critical'].includes(changeRiskProfile.level)) {
       // 关键词误伤早期引导（坑2，FR-02）：命中高危关键词且无 frontmatter risk_level 时，
       // 无条件透出 frontmatter 覆盖指引（不依赖 conclusion / evidence），让 agent 早期即可
-      // 判断是否属误判并显式覆盖，而非撞到 evidence gate 末尾才发现出路③。遵 6417a27：不做
-      // body 否定语境扫描，只走 frontmatter 显式覆盖通道。
+      // 判断是否属误判并显式覆盖，而非撞到 evidence gate 末尾才发现出路③。含否定语境的
+      // 命中已在 detectChangeRisk 内被同句否定抑制（见 change-risk-profile.js NEGATION_CUES），
+      // 此处命中的都是无否定语境的真命中；仍误伤的走 frontmatter 显式覆盖通道。
       if (!changeRiskProfile.explicit) {
         warnings.push(
           `[${changeRiskProfile.level}] 本次变更被关键词判级（命中：${changeRiskProfile.triggers.join(', ')}）。` +
@@ -485,7 +544,12 @@ function validateVerifyOutputs(cwd, changeName, context = {}) {
         // 的结构化证据，作为附加匹配文本——有回执不依赖 agent 措辞；无回执维持原字面匹配
         let receiptText = ''
         try {
-          const receiptPath = join(cwd, '.sillyspec', '.runtime', 'verify-services.receipt.json')
+          // 回执按变更分片（坑 verify-pids-cross-session-kill：原单份被并行会话后写覆盖），
+          // 优先读本变更分片，兼容旧单份名（升级过渡期 receipt.change 过滤仍生效）
+          const runtimeDir = join(cwd, '.sillyspec', '.runtime')
+          const receiptPath = existsSync(join(runtimeDir, `verify-services-${changeName}.receipt.json`))
+            ? join(runtimeDir, `verify-services-${changeName}.receipt.json`)
+            : join(runtimeDir, 'verify-services.receipt.json')
           if (existsSync(receiptPath)) {
             const receipt = JSON.parse(readFileSync(receiptPath, 'utf8'))
             if (receipt && (receipt.reapedPidCount || 0) > 0 && (!receipt.change || receipt.change === changeName)) {

package/src/stages/archive.js

@@ -44,9 +44,17 @@ export const definition = {
     },
     {
       name: 'sync-module-docs',
-      // 坑 verify-archive-flow-pitfalls 坑4：缺 requiresWait 时 --continue --answer 会直接标 completed、
-      // agent 无机会按 module-impact.md 写入模块卡片。加 requiresWait 使 --continue 确认后回到本步执行写入
-      requiresWait: true,
+      // conditionalWait（坑 archive-subconfirm-redundant，2026-08-23 实证：requiresWait 硬门强制
+      // 三段式 --wait → --continue --answer → --done，与 verify 文档同步阻断门、归档移动前死信
+      // 校验、下一步「确认归档 --confirm」四层确认重复，交互碎。改 conditionalWait（brainstorm-auto
+      // 同款先例）：常规同步直接写入 + --done（agent 写入动作在 --done 前完成，坑 verify-archive-
+      // flow-pitfalls 坑4 的「无机会写入」不回归）；仅异常（needs_review/未映射/标记缺失）才 --wait
+      // 请用户裁决。用户确认收敛到「确认归档 --confirm」一处。
+      conditionalWait: true,
+      repeatableWait: true,
+      maxWaitRounds: 3,
+      waitReason: '等待用户裁决模块文档同步异常',
+      waitOptions: ['确认写入', '跳过同步'],
       prompt: `根据 module-impact.md 同步更新模块索引和卡片文档。
 
 ### ⚠️ 核心原则：结构化事实改 _module-map.yaml，语义解释改模块卡片
@@ -109,20 +117,52 @@ created_at: <now-datetime>
 <!-- MANUAL_NOTES_END -->
 \`\`\`
 
-4. 展示所有更新内容（diff 摘要），**必须暂停等待用户确认**
-   - 调用：\`sillyspec run archive --wait --reason "等待用户确认模块文档同步" --options "确认写入,跳过同步" --output "diff 摘要"\`
-5. **只有用户通过 --continue --answer "确认写入" 后才写入文件**
-   - 写入 _module-map.yaml 和受影响的模块卡片
-6. 用户拒绝时，不写入，但提示"module-impact.md 已保留，可稍后手动同步"
-7. 回填 module-impact.md 的"更新结果"表格，区分目标：
+4. 展示所有更新内容（diff 摘要），按同步状态分流：
+   - **常规**（无 needs_review 影响、无 unmapped 模块、人工备注标记齐全）→ **直接写入** _module-map.yaml 和受影响的模块卡片，diff 摘要写入 --output 后 --done（本步不单独弹确认——用户确认收敛到下一步「确认归档 --confirm」，该步展示同一 diff 摘要）
+   - **异常**（含 needs_review 影响项 / unmapped 模块 / 人工备注标记缺失或重复 / 覆盖会丢失手动维护字段）→ 暂停请用户裁决：
+     \`sillyspec run archive --wait --reason "等待用户裁决模块文档同步异常" --options "确认写入,跳过同步" --output "diff 摘要 + 异常说明"\`
+     用户 --continue --answer "确认写入" 后写入；"跳过同步" 则不写入，提示 "module-impact.md 已保留，可稍后手动同步"
+5. 回填 module-impact.md 的"更新结果"表格，区分目标：
    - 目标列写 "\`_module-map.yaml: <module-id>\`" 或 "\`modules/<module-id>.md\`"
-8. **同步完成后**，如需刷新 \`_module-map.yaml\` 索引：\`sillyspec modules rebuild --force\`（默认 dry-run 只预览不写；\`--force\` 才覆盖，但会清空 tags/entrypoints/main_symbols/depends_on/used_by 等手动维护字段——与 archive-impact 的「人工备注保护」约束冲突，仅当手动字段已并入骨架或可接受覆盖时用；优先手动更新 dependencies.md / 模块卡片）
+6. **同步完成后**，如需刷新 \`_module-map.yaml\` 索引：\`sillyspec modules rebuild --force\`（默认 dry-run 只预览不写；\`--force\` 才覆盖，但会清空 tags/entrypoints/main_symbols/depends_on/used_by 等手动维护字段——与 archive-impact 的「人工备注保护」约束冲突，仅当手动字段已并入骨架或可接受覆盖时用；优先手动更新 dependencies.md / 模块卡片）
 
 ### 输出
-已更新的文件路径列表 + 用户确认状态`,
+已更新的文件路径列表 + diff 摘要（异常时附裁决结果）`,
       outputHint: '模块文档更新结果',
       optional: false
     },
+    {
+      name: 'decision-distill 决策提炼',
+      // conditionalWait（同 sync-module-docs 先例）：常规提炼直接写入 + --done；仅异常（rejected
+      // 条目缺否决理由/复潮条件 → distillIntoKnowledge 返回 needsWait 非空）才 --wait 请用户裁决
+      // （补录后重跑幂等 / 跳过该条）。勿引入 requiresWait 硬门——与下一步「确认归档 --confirm」
+      // 重复确认（坑 archive-subconfirm-redundant）。
+      conditionalWait: true,
+      repeatableWait: true,
+      maxWaitRounds: 3,
+      waitReason: '等待用户裁决 rejected 决策缺字段',
+      waitOptions: ['补录后继续', '跳过该条'],
+      prompt: `读取变更 decisions.md，把有实现影响的决策提炼进决策知识库（提炼/幂等/INDEX 路由行本体在 CLI 纯函数 src/decision-distill.js，本步只接线，勿手工改写条目格式）。
+
+### 操作
+1. 定位参数：changeDir = \`.sillyspec/changes/<change-name>\`（decisions.md 所在——本步在「确认归档」移动目录之前，仍在原位）；knowledgeRoot = \`.sillyspec/knowledge\`；headHash = \`git rev-parse --short HEAD\`（落条目「最近确认」）
+2. 调用纯函数 \`distillIntoKnowledge(changeDir, knowledgeRoot, headHash)\`，按返回的 \`{ written, skipped, needsWait }\` 分流（见第 3 点）：
+   - 能解析到 sillyspec 源码/安装位置时（如 sillyspec 仓内 dogfood）直接 import 调用：\`node --input-type=module -e "import { distillIntoKnowledge } from './src/decision-distill.js'; console.log(JSON.stringify(distillIntoKnowledge(changeDir, knowledgeRoot, headHash), null, 2))"\`
+   - 解析不到（consumer 仓库无源码，node import 会 ERR_MODULE_NOT_FOUND）→ 按其语义执行：解析 D-xxx@vN 条目；入选规则 = 任意 type 的 status=rejected 留痕 + 五类 type（architecture/compatibility/boundary/definition/process）且 status∈{confirmed,accepted} 提炼 implemented，type=scope 不入选；条目幂等落 \`.sillyspec/knowledge/decisions/<模块域>.md\`（同 ID 同版本重写不重复追加、@vN+1 整段替换旧版并注 supersedes；「模块域」缺失按 impacts 路径与 _module-map.yaml paths 前缀匹配兜底，仍未中归 unmapped）；implemented 条目写「状态：implemented + 锚点：<src 路径:行号，未记录则填"未记录"> + 最近确认：<headHash> + 理由：<一句话>」，rejected 条目写「状态：rejected + 否决理由： + 复潮条件：」；\`knowledge/INDEX.md\` 的 decisions 路由行（\`- <域>|decision|决策 → [decisions/<域>.md](decisions/<域>.md)\`）幂等增删
+3. 分流规则：
+   - **常规**（needsWait 为空且 written 非空）→ 写入已由函数完成，written 摘要（decisions/<域>.md × D-xxx@vN × append/update/supersede）写入 --output 后直接 --done（本步不单独弹确认——用户确认收敛到下一步「确认归档 --confirm」）
+   - **needsWait 非空**（rejected 条目缺否决理由/复潮条件，该条目未写盘、其余条目照常提炼）→ 暂停请用户裁决：
+     \`sillyspec run archive --wait --reason "等待用户裁决 rejected 决策缺字段" --options "补录后继续,跳过该条" --output "needsWait 描述 + 已提炼摘要"\`
+     - 「补录后继续」→ 按 needsWait 描述在 changes/<change-name>/decisions.md 补齐缺失的否决理由/复潮条件，重跑第 2 步（幂等，重跑安全）
+     - 「跳过该条」→ 该条目不入库，--output 注记跳过原因后 --done
+   - **零输出**（skipped 非空 = 无 decisions.md / 无入选条目）→ 不创建任何文件、不动 INDEX，--output 注一句 skipped 原因后直接 --done（同 docs-debt 无债零输出原则）
+4. 降级：调用或解析异常（模块加载失败 / decisions.md 结构异常抛错）→ warn 记录异常摘要后跳过本步 --done（best-effort，同 agent-session-log 先例），不阻断归档——决策提炼失败不挡归档移动
+
+### 输出
+已提炼条目清单（decisions/<域>.md × D-xxx@vN × action）或零输出/跳过/降级原因`,
+      outputHint: '决策提炼结果',
+      optional: false
+    },
     {
       name: '确认归档',
       prompt: `确认归档内容，由 CLI 执行目录移动。
@@ -147,7 +187,8 @@ created_at: <now-datetime>
 1. 如果 \`.sillyspec/ROADMAP.md\` 存在，标记对应 Phase 为已完成
 2. \`git add .sillyspec/changes/archive/\` — 暂存归档结果（archive/ 下仅本次归档新增，不会裹挟 changes/ 下其他活跃变更；不要 commit，由用户通过统一提交工具处理）
 3. \`git add .sillyspec/docs/<project>/modules/\` — 暂存模块文档更新（如有；精确到本次同步的模块文档，勿 add 整个 .sillyspec/docs/）
-4. 确认 sillyspec.db 中该变更已不再 active（确认归档步骤由 CLI 调用 unregisterChange）
+4. \`git add .sillyspec/knowledge/decisions/\` — 暂存决策知识库更新（如有；decision-distill 步骤的提炼产物，精确到 decisions 子目录，勿 add 整个 .sillyspec/knowledge/；不要 commit，由用户通过统一提交工具处理）
+5. 确认 sillyspec.db 中该变更已不再 active（确认归档步骤由 CLI 调用 unregisterChange）
 
 ### 输出
 归档完成确认 + 累积规范统计`,