sillyspec 3.33.0 → 3.33.1

package/src/review-dispatch.js

@@ -18,6 +18,7 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs'
+import { runtimeStatePath } from './runtime-paths.js'
 import { join, dirname } from 'node:path'
 import jsYaml from 'js-yaml'
 import { writeAtomicSync } from './fs-atomic.js'
@@ -41,7 +42,7 @@ const DISPATCH_STATES = ['dispatching', 'in-flight', 'completed', 'failed', 'aba
 
 /** 在途记录路径：{SPEC_ROOT}/.runtime/review-dispatch-<change>.json */
 function dispatchRecordPath(specBase, changeName) {
-  return join(specBase, '.runtime', `review-dispatch-${changeName}.json`)
+  return runtimeStatePath(join(specBase, '.runtime'), `review-dispatch-${changeName}.json`)
 }
 
 /** 读在途记录（无/坏 → null，fail-open 调用方按无在途处理）。 */
@@ -459,7 +460,7 @@ function appendShadowLedgerSkip(runtimeRoot, skip) {
  */
 function readCeremonyTierForShadow(runtimeRoot, changeName) {
   try {
-    const p = join(runtimeRoot, `ceremony-tier-${changeName}.json`)
+    const p = runtimeStatePath(runtimeRoot, `ceremony-tier-${changeName}.json`)
     if (!existsSync(p)) return null
     const doc = JSON.parse(readFileSync(p, 'utf8'))
     if (!doc || typeof doc !== 'object' || Array.isArray(doc)) return null
@@ -480,7 +481,7 @@ function generateShadowReviewRunId() {
 //    stage-review.js:751 的主线在途提示内联读的也是主线文件名，不会被影子记录污染）──
 
 function shadowRecordPath(specBase, changeName) {
-  return join(specBase, '.runtime', `review-dispatch-shadow-${changeName}.json`)
+  return runtimeStatePath(join(specBase, '.runtime'), `review-dispatch-shadow-${changeName}.json`)
 }
 
 function readShadowRecord(specBase, changeName) {

package/src/review-tier.js

@@ -35,6 +35,7 @@
  */
 
 import { parseFileChangeList } from './change-list.js'
+import { runtimeStatePath } from './runtime-paths.js'
 import { computeCeremonyTier, CEREMONY_TIERS } from './ceremony-tier.js'
 import { readCeremonyPricingConfig } from './ceremony-config.js'
 import { resolveChangeRisk, extractExplicitRiskLevel } from './change-risk-profile.js'
@@ -151,7 +152,7 @@ export function classifyReviewTier({ planLevel, designPath, riskDetection, frict
   if (designPath) {
     try {
       const changeDir = dirname(designPath)
-      const tierPath = join(dirname(dirname(changeDir)), '.runtime', `ceremony-tier-${basename(changeDir)}.json`)
+      const tierPath = runtimeStatePath(join(dirname(dirname(changeDir)), '.runtime'), `ceremony-tier-${basename(changeDir)}.json`)
       if (existsSync(tierPath)) {
         const tf = JSON.parse(readFileSync(tierPath, 'utf8'))
         if (tf && CEREMONY_TIERS.includes(tf.tier)) tierFileTier = tf.tier

package/src/route-hindsight.js

@@ -37,6 +37,7 @@ import { createHash } from 'node:crypto'
 import { join, basename, dirname } from 'node:path'
 import { writeAtomicSync } from './fs-atomic.js'
 import { computeEditRatio } from './flow-draft.js'
+import { runtimeStatePath } from './runtime-paths.js'
 
 /** 超阈判定常量（可调；口径：比例两路为严格大于——恰等于阈值不算超，保守防误标 R-01；
  * 计数两路为大于等于——2 维/2 次即系统性信号）。 */
@@ -107,7 +108,7 @@ function num(v) {
 export function snapshotBaseline({ specBase, change, changeDir }) {
   try {
     const runtimeRoot = join(specBase, '.runtime')
-    const p = join(runtimeRoot, `${BASELINE_PREFIX}${change}.json`)
+    const p = runtimeStatePath(runtimeRoot, `${BASELINE_PREFIX}${change}.json`)
     if (existsSync(p)) return { captured: false, reason: 'already-exists（首写者胜）' }
     const payload = {
       schemaVersion: 1,
@@ -130,7 +131,7 @@ export function snapshotBaseline({ specBase, change, changeDir }) {
  */
 export function baselineSha256({ specBase, change }) {
   try {
-    const p = join(specBase, '.runtime', `${BASELINE_PREFIX}${change}.json`)
+    const p = runtimeStatePath(join(specBase, '.runtime'), `${BASELINE_PREFIX}${change}.json`)
     if (!existsSync(p)) return null
     return createHash('sha256').update(readTextSafe(p)).digest('hex')
   } catch {
@@ -161,7 +162,7 @@ export function computeHindsightMetrics({ changeDir, reviewJson, flowState }) {
   // ① 首版快照 → 终稿行级改写比
   let designRewriteRatio = 0
   let tasksRewriteRatio = 0
-  const baselineRaw = readTextSafe(join(specBase, '.runtime', `${BASELINE_PREFIX}${change}.json`))
+  const baselineRaw = readTextSafe(runtimeStatePath(join(specBase, '.runtime'), `${BASELINE_PREFIX}${change}.json`))
   let baseline = null
   if (baselineRaw != null) { try { const j = JSON.parse(baselineRaw); baseline = j && typeof j === 'object' ? j : null } catch { baseline = null } }
   if (baseline) {

package/src/run/bg-sync.js

@@ -36,12 +36,18 @@
  * 刻意不赌）；父进程内 shared.js 已加载，动态 import 走缓存无额外成本。
  */
 import { spawn } from 'child_process';
+import { runtimeTempPath } from '../runtime-paths.js'
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'fs';
 import { join } from 'path';
 
 export const BG_LOCK_FILENAME = 'spec-sync-bg.lock';
 export const BG_LOG_FILENAME = 'spec-sync-bg.log';
 
+/** 后台同步日志路径（2026-10-18 布局分层：可随时删除的产物归 temp/）。 */
+export function bgSyncLogPath(runtimeRoot) {
+  return runtimeTempPath(runtimeRoot, BG_LOG_FILENAME);
+}
+
 // 后台轮参数：单轮预算下限（与 env SILLYSPEC_SYNC_TIMEOUT_MS 取 max）、轮数与总预算帽
 // （防慢平台下无限续轮）；锁时效（pid 活性之外的第二道判死——pid 复用假活兜底，
 // 子进程自身总预算 ~2.5min + 收尾余量远小于该值，超时必是异常残留）。
@@ -108,7 +114,7 @@ export function isBgSyncLockLive(lock, now = Date.now()) {
 /** 子进程起步截尾日志（>1MB 保后 512KB，从整行边界起）。失败只影响日志体积。 */
 function truncateLogIfNeeded(runtimeRoot) {
   try {
-    const p = join(runtimeRoot, BG_LOG_FILENAME);
+    const p = bgSyncLogPath(runtimeRoot);
     if (statSync(p).size <= LOG_TRUNCATE_THRESHOLD) return;
     const buf = readFileSync(p);
     const keep = buf.subarray(Math.max(0, buf.length - LOG_TRUNCATE_KEEP));
@@ -143,15 +149,16 @@ export async function spawnBackgroundSync(cwd, changeName, platformOpts = {}, op
     // 单飞合并：活后台轮在跑，把「还有新状态要同步」并入其下一轮。置位失败（并发写锁）
     // 只损失合并信号——后台轮收尾锁自清，下一条命令重新 spawn，收敛不丢。
     try { writeBgSyncLock(runtimeRoot, { ...lock, rerunQueued: true }); } catch { /* 见上 */ }
-    return { status: 'coalesced', logPath: join(runtimeRoot, BG_LOG_FILENAME) };
+    return { status: 'coalesced', logPath: bgSyncLogPath(runtimeRoot) };
   }
 
   // 日志 fd：子进程 stdout/stderr 直接 append 进日志文件（跨平台 fd 继承）；开不了退 ignore
-  const logPath = join(runtimeRoot, BG_LOG_FILENAME);
+  const logPath = bgSyncLogPath(runtimeRoot);
   let stdio = ['ignore', 'ignore', 'ignore'];
   let logFd = null;
   try {
     mkdirSync(runtimeRoot, { recursive: true });
+    mkdirSync(join(runtimeRoot, 'temp'), { recursive: true }); // temp/ 可被整体删除，写前重建
     logFd = openSync(logPath, 'a');
     stdio = ['ignore', logFd, logFd];
   } catch {

package/src/run/command.js

@@ -20,6 +20,7 @@
  *     './run/stage.js' → './shared.js' 等同级
  */
 import { basename, join, resolve, dirname } from 'node:path'
+import { runtimeStatePath } from '../runtime-paths.js'
 import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync, rmSync, unlinkSync, statSync } from 'node:fs'
 import { randomBytes, randomUUID } from 'node:crypto'
 import { fileURLToPath } from 'node:url'
@@ -29,7 +30,7 @@ import { resolveQuickLinkedChanges } from './quick-audit.js'
 import { outputStep, collectStageWaitHistory } from './prompt.js'
 import { completeStep, completeStepBurst, skipStep, waitStep, continueStep, synthesizeStepOutput } from './complete.js'
 import { runStage } from './stage.js'
-import { sanitizeDesc, deriveChangeTitle } from '../quicklog.js'
+import { sanitizeDesc, deriveShortChangeTitle } from '../quicklog.js'
 import { ProgressManager, resolveSessionIdentity } from '../progress.js'
 import { validateChangeExists, checkTransition } from '../stage-contract.js'
 import { READONLY_AUXILIARY_STAGES } from '../constants.js'
@@ -232,7 +233,7 @@ export async function ensureStageSteps(progress, stageName, cwd, specDir = null)
 function emitReadonlyEmptyGuide() {
   console.log('ℹ️ 未找到进度数据（只读查询不建变更）')
   console.log('   → 可开始轻量变更（--input 引号内换行合法，下例可照抄）：')
-  console.log('     sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句中文概括（首行即变更标题）；随后动机与背景')
+  console.log('     sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句 10-30 字中文概括（首行即变更标题，硬区间 10-30 必须、建议 ~20 字）；随后动机与背景')
   console.log('')
   console.log('     成功标准：')
   console.log('     - <可验证标准>"')
@@ -858,7 +859,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
             quickFallbackUsed = true
           } else {
             console.log('   本仓无近期 quick 会话记录（current marker 与 quick-sessions 均空）——新工作请走轻量变更（--input 引号内换行合法，可照抄）：')
-            console.log('   sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句中文概括（首行即变更标题）；随后动机与背景')
+            console.log('   sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句 10-30 字中文概括（首行即变更标题，硬区间 10-30 必须、建议 ~20 字）；随后动机与背景')
             console.log('')
             console.log('   成功标准：')
             console.log('   - <可验证标准>"')
@@ -1301,11 +1302,12 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
           }
         }
       } catch { /* 守卫异常不拦正常注册（fail-open）*/ }
-      // 创建时即写 title（与 name/KEY 同时落 db）：--input 首行推导 deriveChangeTitle（≤50 字，
-      // 用户需求 2026-09-29）优先，长输入兜底 sanitizeDesc 压行，无则用 name 兜底。
+      // 创建时即写 title（与 name/KEY 同时落 db）：--input 首行过提炼 deriveShortChangeTitle
+      // （目标 20/上限 30 自然标点截断；2026-10-16-short-change-title，50 字硬切残句淘汰）
+      // 优先，长输入兜底 sanitizeDesc 压行，无则用 name 兜底。
       // proposal 还没写、无权威标题来源，这是临时值；brainstorm/plan 完成 proposal/design 落盘后由
       // complete.js 通用完成路径 deriveTitleFromLinkedChange 刷新为真实 # 标题（与 quick 启动 title 同源）。
-      progress = pm.initChange(cwd, autoChange, { title: inputText ? (deriveChangeTitle(inputText) || sanitizeDesc(inputText)) : autoChange })
+      progress = pm.initChange(cwd, autoChange, { title: inputText ? (deriveShortChangeTitle(inputText) || sanitizeDesc(inputText)) : autoChange })
     } else if (isAuxiliary) {
       let autoName = changeName || resolveChangeNameAuto(cwd, specRoot) || 'default'
       // archive 特例：归档后变更从活跃列表排除（listChanges WHERE status='active'），
@@ -1332,7 +1334,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       changeName = autoName
       if (!progress) {
         // auxiliary 创建也写 title（--input 优先 / name 兜底），同上完整流程语义。
-        progress = pm.initChange(cwd, autoName, { title: inputText ? (deriveChangeTitle(inputText) || sanitizeDesc(inputText)) : autoName })
+        progress = pm.initChange(cwd, autoName, { title: inputText ? (deriveShortChangeTitle(inputText) || sanitizeDesc(inputText)) : autoName })
         // initChange 可能因 project 表为空返回 null
         if (!progress) {
           progress = { currentStage: stageName, stages: {}, lastActive: new Date().toLocaleString('zh-CN', { hour12: false }), project: '' }
@@ -1354,7 +1356,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
         // initChangeIfNoActive 单语句原子抢占，败者走同一引导。
         const date = new Date().toISOString().slice(0, 10)
         const autoName = `${date}-new-change-${randomBytes(4).toString('hex')}`
-        const claim = pm.initChangeIfNoActive(cwd, autoName, { title: inputText ? (deriveChangeTitle(inputText) || sanitizeDesc(inputText)) : autoName })
+        const claim = pm.initChangeIfNoActive(cwd, autoName, { title: inputText ? (deriveShortChangeTitle(inputText) || sanitizeDesc(inputText)) : autoName })
         if (!claim.created) {
           const activeChanges = claim.activeChanges || []
           console.error(`❌ 已存在 ${activeChanges.length} 个活跃变更，run brainstorm 无 --change 不会自动创建新变更。`)
@@ -1377,7 +1379,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
         // 正是并发双建的温床）——1 活跃现与多活跃同走 exit 2 引导。
         const date = new Date().toISOString().slice(0, 10)
         const autoName = `${date}-new-change-${randomBytes(4).toString('hex')}`
-        const claim = pm.initChangeIfNoActive(cwd, autoName, { title: inputText ? (deriveChangeTitle(inputText) || sanitizeDesc(inputText)) : autoName })
+        const claim = pm.initChangeIfNoActive(cwd, autoName, { title: inputText ? (deriveShortChangeTitle(inputText) || sanitizeDesc(inputText)) : autoName })
         if (!claim.created) {
           const activeCount = claim.activeChanges || []
           console.error(`❌ 已存在 ${activeCount.length} 个活跃变更，run auto 无法自动定位目标。`)
@@ -2076,7 +2078,7 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
     if (classification.mode === 'quick') {
       console.log(`📊 auto 模式分类：${classification.reason} 判为小变更`)
       console.log(`   小变更请走轻量变更（quick 通道已退役，v3.30.0 起拒绝新会话；--input 引号内换行合法，可照抄）：`)
-      console.log('   sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句中文概括（首行即变更标题）；随后动机与背景')
+      console.log('   sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句 10-30 字中文概括（首行即变更标题，硬区间 10-30 必须、建议 ~20 字）；随后动机与背景')
       console.log('')
       console.log('   成功标准：')
       console.log('   - <可验证标准>"')
@@ -2382,7 +2384,7 @@ function printAutoCompletionSummary(pm, cwd, changeName, flowStages, specBase) {
     // last-delta 模块清单（sidecar 缺失跳过）
     try {
       const runtimeRoot = join((specBase || join(cwd, '.sillyspec')), '.runtime')
-      const sidecarPath = join(runtimeRoot, 'last-delta.json')
+      const sidecarPath = runtimeStatePath(runtimeRoot, 'last-delta.json')
       if (existsSync(sidecarPath)) {
         const sidecar = JSON.parse(readFileSync(sidecarPath, 'utf8'))
         if (Array.isArray(sidecar.affectedModules) && sidecar.affectedModules.length > 0) {

package/src/run/complete-handlers.js

@@ -30,6 +30,7 @@
  * （非被外层吞）；process.exit 不可被 try 捕获 → 搬迁行为完全等价。
  */
 import { basename, dirname, join, resolve, relative, isAbsolute } from 'node:path'
+import { runtimeStatePath, runtimeStateFileNames } from '../runtime-paths.js'
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, rmSync, renameSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import { renameSyncRetry, writeAtomicSync } from '../fs-atomic.js'
@@ -161,8 +162,9 @@ function ownerFromReviewedFiles(reviewedFiles) {
  * 归档 / change-delete 无 delta 同样可删。
  *
  * 归属 fail-closed（禁 mtime 猜、禁后缀匹配）：
- *   apply-pathspec-<change>.txt 精确文件名
- *   prompt-inject-<change>.json 精确文件名（2026-09-18-preflight-slimming：注入分叉账本回收登记）
+ *   state/ 全家族散文件 + 根目录同名兜底（runtime-paths.js runtimeStateFileNames 唯一清单：
+ *   draft-ledger / watcher 三件套 / test 台账 / ceremony 档位 / 冲突标记 / marker 等，
+ *   含 apply-pathspec-<change>.txt、prompt-inject-<change>.json 两个历史登记家族）
  *   execute-runs/<runId>/ 仅当 `change` 戳全等（无戳旧 run 留下，不按覆盖度启发式删）
  *   stage-reviews/<dir>/ 仅当 review.json reviewedFiles 首段 === changeName
  *   verify-runs/<ts>/ 仅当目录内 JSON 的 change 字段集合 size=1 且等于本变更
@@ -193,33 +195,26 @@ export function pruneArchivedChangeRuntime(runtimeRoot, changeName) {
     } catch { /* 单份失败不连坐，下次归档/删变更再收 */ }
   }
 
+  // 2026-10-18 布局分层：per-change 散文件全部落 state/，回收名单从三家族扩到全家族
+  // （runtime-paths.js STATE_FAMILIES 唯一清单源，禁 glob 的精确名形态不变）。
+  // 每个精确名试双路径：state/（新布局）+ 根目录（未迁移旧仓/混版本迟到文件兜底——
+  // 迁移幂等收敛后根路径命中恒为零）。friction-tally 删前残余滚台账语义保留（见函数头）。
   try {
-    const pathspec = join(runtimeRoot, `apply-pathspec-${changeName}.txt`)
-    if (existsSync(pathspec)) gone(pathspec)
-  } catch {}
-
-  // prompt-inject 账本（2026-09-18-preflight-slimming Phase 2 / D-002，Grill 评审 fail②）：
-  // .runtime/prompt-inject-<change>.json 是 change 级派生文件（阶段感知注入分叉的账本），
-  // 变更归档/删除后无读者——不登记回收则按变更数累积孤儿。精确文件名，对齐上方
-  // apply-pathspec / 下方 friction-tally 同款形态（禁 glob/后缀匹配）。
-  try {
-    const ledger = join(runtimeRoot, `prompt-inject-${changeName}.json`)
-    if (existsSync(ledger)) gone(ledger)
-  } catch {}
-
-  // friction tally（friction-signal-hint FR-05）：摩擦计数随变更终态一并回收——真实变更的
-  // friction-tally-<change>.json 落 runtimeRoot，变更归档/删除后无读者，残留即孤儿文件。
-  // 删前残余先滚台账（tax-governance FR-02 兜底滚动点，见函数头注释）。
-  try {
-    const fp = join(runtimeRoot, `friction-tally-${changeName}.json`)
-    if (existsSync(fp)) {
-      const merged = mergeFrictionEntrySync(runtimeRoot, {
-        change: changeName,
-        counts: residualFrictionCounts(fp),
-        archivedAt: new Date().toISOString(),
-      })
-      ledgerAppend = !!(merged && merged.ok && !merged.skipped)
-      gone(fp)
+    for (const name of runtimeStateFileNames(changeName)) {
+      for (const p of [runtimeStatePath(runtimeRoot, name), join(runtimeRoot, name)]) {
+        try {
+          if (!existsSync(p)) continue
+          if (name === `friction-tally-${changeName}.json`) {
+            const merged = mergeFrictionEntrySync(runtimeRoot, {
+              change: changeName,
+              counts: residualFrictionCounts(p),
+              archivedAt: new Date().toISOString(),
+            })
+            ledgerAppend = !!(merged && merged.ok && !merged.skipped)
+          }
+          gone(p)
+        } catch { /* 单路径失败不连坐 */ }
+      }
     }
   } catch {}
 
@@ -320,15 +315,22 @@ export async function archiveWorktreeCleanup(cwd, archiveChangeName, specBase, p
       // 手工短名变更（如 login）时误删自动日期前缀变更（2026-08-01-login 天然以 '-login' 结尾）
       // 的 marker。stage 集合与写入侧 stageReviewMarkerPath 的调用方一致。
       const REVIEW_STAGES = ['brainstorm', 'plan', 'execute', 'verify', 'archive']
-      const markers = readdirSync(runtimeRoot).filter((f) =>
-        f === `current-execute-run-id-${archiveChangeName}` ||
-        REVIEW_STAGES.some(st => f === `current-stage-review-run-id-${st}-${archiveChangeName}`),
-      )
-      for (const m of markers) {
-        try { unlinkSync(join(runtimeRoot, m)) } catch {}
+      // 2026-10-18 布局分层后 marker 落 state/；根目录扫描保留为旧布局兜底（迁移幂等收敛）
+      const markerDirs = [join(runtimeRoot, 'state'), runtimeRoot]
+      let markerCleaned = 0
+      for (const markerDir of markerDirs) {
+        let names = []
+        try { names = readdirSync(markerDir) } catch { continue }
+        const markers = names.filter((f) =>
+          f === `current-execute-run-id-${archiveChangeName}` ||
+          REVIEW_STAGES.some(st => f === `current-stage-review-run-id-${st}-${archiveChangeName}`),
+        )
+        for (const m of markers) {
+          try { unlinkSync(join(markerDir, m)); markerCleaned++ } catch {}
+        }
       }
-      if (markers.length > 0) {
-        console.log(`🧹 归档清理 ${markers.length} 个 runId marker（execute/stage-review）`)
+      if (markerCleaned > 0) {
+        console.log(`🧹 归档清理 ${markerCleaned} 个 runId marker（execute/stage-review）`)
       }
       // 取证回收必须在下方 worktree 块的 `if (!meta) return` 之前：无 meta 早退是常态
       // （apply 已 cleanup），漏接就会让 execute-runs/verify-runs 继续按变更数累积。
@@ -2803,7 +2805,8 @@ export async function handleExecuteWorktreeCleanup({ stageName, changeName, cwd
               try {
                 const runtimeDir = join(cwd, '.sillyspec', '.runtime');
                 mkdirSync(runtimeDir, { recursive: true });
-                writeFileSync(join(runtimeDir, `execute-cleanup-${changeName}.json`), JSON.stringify({
+                try { mkdirSync(join(runtimeDir, 'state'), { recursive: true }); } catch { /* 回执 fail-open */ }
+                writeFileSync(runtimeStatePath(runtimeDir, `execute-cleanup-${changeName}.json`), JSON.stringify({
                   change: changeName, cleanedAt: new Date().toISOString(),
                   reason: 'execute-completed-no-unapplied-changes',
                 }, null, 2) + '\n', 'utf8');

package/src/run/complete.js

@@ -17,12 +17,13 @@
  *   - node: join(path) + existsSync/readdirSync/readFileSync/mkdirSync/writeFileSync/appendFileSync/statSync(fs)
  */
 import { join, isAbsolute, resolve } from 'node:path'
+import { runtimeStatePath } from '../runtime-paths.js'
 import { existsSync, readFileSync, mkdirSync, writeFileSync, appendFileSync } from 'node:fs'
 import { writeAtomicSync } from '../fs-atomic.js'
 import { gitQuiet } from '../git-helper.js'
 import { writeCloseTraceArtifacts, projectTraceFaceRows } from '../flow-parity.js'
 import { withFileLock } from '../quicklog.js'
-import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions, resolveRuntimeRoot, getOrCreateMultiRepoContext, resolveChangeDir, writePlatformDocsPointer, isRetiredAutoBrainstormTable, printRetiredAutoBrainstormRefusal } from './shared.js'
+import { triggerSync, triggerSyncTerminalStrict, WAIT_MARKER_RE, getStageSteps, formatWaitOptions, resolveRuntimeRoot, getOrCreateMultiRepoContext, resolveChangeDir, writePlatformDocsPointer, isRetiredAutoBrainstormTable, printRetiredAutoBrainstormRefusal } from './shared.js'
 import { isExplicitReviewWrite, collectWorktreeChangedFiles } from '../task-review.js'
 
 // 退役自动道守门（2026-10-14-brainstorm-auto-retire）：brainstorm-auto 4 步表已随自动道删除。
@@ -828,7 +829,10 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
 
     // gate 全过：persist completed（task-01 移后）。此处到 _write 之间若崩，DB 仍 in-progress（内存已 completed 但未落盘），下次进 CLI 读 DB 即 in-progress，不产生"假 completed"。
     pm._write(cwd, progress, changeName)
-    triggerSync(cwd, changeName, platformOpts, { completion: true })
+    // 终态强校验（2026-10-17-archive-half-state-location-stuck-active）：状态机驱动——仅
+    // DB status 已达 archived/deleted（archive 阶段完成即此态）走内联强校验，其余阶段
+    // 原样委托 triggerSync（后台化不变，非终态零行为变化）。见 run/shared.js 契约注释。
+    await triggerSyncTerminalStrict(cwd, changeName, platformOpts, { completion: true })
 
     const total = steps.length
     console.log(`✅ ${stageName} 阶段已完成（${total}/${total} 步）`)
@@ -843,7 +847,7 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       let stageLedger = null
       let crossStage = false
       try {
-        const ledgerPath = join(specBase, '.runtime', `stage-session-ledger-${changeName}.json`)
+        const ledgerPath = runtimeStatePath(join(specBase, '.runtime'), `stage-session-ledger-${changeName}.json`)
         try { stageLedger = JSON.parse(readFileSync(ledgerPath, 'utf8')) } catch { /* 首阶段 */ }
         const r = updateStageSessionLedger(stageLedger, process.env.SILLYSPEC_SESSION_ID, stageName)
         stageLedger = r.ledger
@@ -1018,7 +1022,7 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     if (stageName === 'execute' && changeName && defSteps && defSteps[currentIdx] && defSteps[nextPendingIdx] &&
         /Wave \d+ 执行/.test(defSteps[currentIdx].name || '') && /Wave \d+ 执行/.test(defSteps[nextPendingIdx].name || '')) {
       try {
-        const ledgerPath = join(specBase, '.runtime', `wave-session-ledger-${changeName}.json`)
+        const ledgerPath = runtimeStatePath(join(specBase, '.runtime'), `wave-session-ledger-${changeName}.json`)
         let ledger = null
         try { ledger = JSON.parse(readFileSync(ledgerPath, 'utf8')) } catch { /* 首 Wave */ }
         const { ledger: nextLedger, crossWaveAdvisory } = updateWaveSessionLedger(ledger, process.env.SILLYSPEC_SESSION_ID, defSteps[currentIdx].name)
@@ -1141,7 +1145,7 @@ async function printVerifyScopeDrift({ cwd, changeName, specBase, platformOpts,
       snapshot = JSON.parse(readFileSync(join(specBase, 'changes', changeName, 'scope-audit.json'), 'utf8'))
     } catch {
       try {
-        snapshot = JSON.parse(readFileSync(join(resolveRuntimeRoot(platformOpts, specBase), `scope-audit-${changeName}.json`), 'utf8'))
+        snapshot = JSON.parse(readFileSync(runtimeStatePath(resolveRuntimeRoot(platformOpts, specBase), `scope-audit-${changeName}.json`), 'utf8'))
       } catch { /* 快照缺失/损坏 → 跳过对比只打当前 totals */ }
     }
   }
@@ -1559,7 +1563,7 @@ export async function autoTickTasksFromCommitSubjects({ changeName, cwd, specBas
   try {
     const _tasksMdPath = join(specBase, 'changes', changeName, 'tasks.md')
     if (!existsSync(_tasksMdPath)) return { ticked: 0, skippedNoAnchor: 0 }
-    const _runIdFile = join(resolveRuntimeRoot(platformOpts, specBase), `current-execute-run-id-${changeName}`)
+    const _runIdFile = runtimeStatePath(resolveRuntimeRoot(platformOpts, specBase), `current-execute-run-id-${changeName}`)
     let _tickLog = ''
     try {
       if (existsSync(_runIdFile)) {
@@ -1640,7 +1644,7 @@ export async function autoCheckPlanFromReviews({ stageName, changeName, cwd, pla
     // plan.md Wave 引用行无 checkbox，无处可勾）。tasks.md 存在性作前置。
     const tasksMdPath = join(changeDir, 'tasks.md')
     const runtimeRoot = resolveRuntimeRoot(platformOpts, specBaseLc)
-    const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
+    const runIdFile = runtimeStatePath(runtimeRoot, `current-execute-run-id-${changeName}`)
     if (!existsSync(tasksMdPath) || !existsSync(runIdFile)) {
       return { autoChecked: false, checkedCount: 0, skippedCount: 0 }
     }
@@ -1798,7 +1802,7 @@ export async function detectExecuteBatchFinish({ pm, stageName, changeName, cwd,
     // 平台模式 runtimeRoot / worktree 漂移 specDriftAnchor 不透传时 marker 恒读不到
     // → 每个 task 进 blockedTasks → 批量完成静默失效
     const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
-    const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
+    const runIdFile = runtimeStatePath(runtimeRoot, `current-execute-run-id-${changeName}`)
     // ── 缺席草稿自动补齐（坑 task-review-retired-archive-mismatch，2026-10-15 归档门口实证）──
     // Task Review 层退役（2026-09-26）后 execute 批量完成不再产 per-task review.json，但本函数
     // 下方复核循环与 archive step2 完成度判定（真相源=review.json verdict）仍以它在场为前提——

package/src/run/gate-snapshot-ledger.js

@@ -16,6 +16,7 @@
  * 异常面：全部 fail-open 吞掉（账本/回收任一异常零阻断，退现状残留）。
  */
 import { execFileSync } from 'node:child_process'
+import { runtimeStatePath } from '../runtime-paths.js'
 import { existsSync, mkdirSync, readFileSync } from 'node:fs'
 import { basename, dirname, join, resolve, sep } from 'node:path'
 import { tmpdir } from 'node:os'
@@ -28,7 +29,7 @@ const STALE_HOURS_DEFAULT = 24
 
 /** 账本文件路径（runtime 域：.sillyspec/.runtime/active-gate-snapshots.json） */
 export function gateSnapshotLedgerPath(runtimeRoot) {
-  return join(runtimeRoot, LEDGER_FILE)
+  return runtimeStatePath(runtimeRoot, LEDGER_FILE)
 }
 
 /** 读账本（损坏/缺失/非数组 → 空数组，fail-open） */

package/src/run/gate-snapshot.js

@@ -494,7 +494,12 @@ export function applyGateSnapshotCopy(cwd, snapshotRoot) {
  * @param {{ cwd: string, files: string[] }} opts cwd=主仓根；files=本会话变更文件（仓库根相对 POSIX）
  * @returns {{ snapshotRoot: string, cleanup: () => void, reason?: string }|null} 失败返回 null（调用方回退主仓）
  */
-export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSmoke = false, mergeBase = null, runtimeRoot = null }) {
+export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSmoke = false, mergeBase = null, runtimeRoot = null, failRef = null }) {
+  // failRef 可选出参（坑 snapshot-fallback-reason-blind，2026-10-16 下游实证）：所有失败分支
+  // 把结构化原因写进 failRef.reason——调用方（verify --done 实测门 / noAI 质量扫描）消费它
+  // 替换硬编码笼统文案，降级原因可直读（pnpm 布局拒建 ≠ 文件集为空 ≠ junction 失败）。
+  // 返回契约不变（失败恒 null）；不传 failRef 行为与既有逐字节一致。
+  const setFail = (reason) => { if (failRef && typeof failRef === 'object') failRef.reason = reason }
   let snapshotRoot = null
   try {
     // 前置：主仓须是 git 仓且有 HEAD（无 git 环境回退主仓现行为）
@@ -519,6 +524,7 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
     // 与其让沙箱报无关错误逼 advisory，不如布局命中即作废快照回退主仓（宁可主仓口径）。
     const layoutHit = detectSymlinkStoreLayout(cwd)
     if (layoutHit) {
+      setFail(`symlink-store 布局拒建（${layoutHit}）：node_modules 符号链接 store 经 junction 跨根失效，实测必假败——设计性回退主仓实测`)
       console.warn(`⚠️ 门禁快照对 ${layoutHit} 布局不可靠（node_modules 符号链接 store 经 junction 跨根失效，实测必假败）——跳过快照回退主仓实测；主仓失败再做污染归属鉴定`)
       return null
     }
@@ -625,6 +631,7 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
     // 回退主仓现行为（主仓口径可能被并行脏文件污染，但环境真实；两害取轻 + 回退原因可见）。
     const envMissing = envDirsLinked(cwd, snapshotRoot)
     if (envMissing.length > 0) {
+      setFail(`环境目录链接不完整（${envMissing.join('、')} 在主仓存在、快照内缺失）——快照作废回退主仓实测`)
       console.warn(`⚠️ 门禁快照环境不完整（${envMissing.join('、')} 在主仓存在、快照内缺失）——快照作废回退主仓实测（宁可主仓口径不可假沙箱硬挂；回退后失败先做污染归属鉴定）`)
       // 与正常 cleanup/失败 catch 同一清理体：双清确认才销账（该早退曾残留旧式 --quiet
       // 清理与无重试 rmSync——独立审查 P1-1 根因未除尽的漏网面）
@@ -723,7 +730,10 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
     return { snapshotRoot, cleanup, overlaid, pinnedCacheLinks }
   } catch (e) {
     // 基建失败（worktree add 拒绝/磁盘满/…）：尽力清理后回退主仓；销账同走双清确认
-    // （D-004@v2：清不掉的条目保留待回收——它不是悬空条目，是待回收记录）
+    // （D-004@v2：清不掉的条目保留待回收——它不是悬空条目，是待回收记录）。
+    // 异常细节不再静默（坑 snapshot-fallback-reason-blind）：failRef 带原因 + warn 落日志。
+    setFail(`快照基建异常: ${e && e.message ? e.message : e}`)
+    try { console.warn(`⚠️ 门禁快照基建失败（回退主仓实测）: ${e && e.message ? e.message : e}`) } catch { /* 输出失败不影响回退 */ }
     if (snapshotRoot) {
       try {
         const { dirRemoved, worktreeCleaned } = cleanupSnapshot({ snapshotRoot, cwd })
@@ -870,7 +880,8 @@ export function printSnapshotFailureHint(snapInfo, { offEnv = 'SILLYSPEC_VERIFY_
  * @param {{ cwd: string, changeName: string, specBase: string, platformOpts?: object }} opts
  * @returns {Promise<{snapshotRoot: string, cleanup: () => void, overlaid: number, changeFileCount: number}|null>}
  */
-export async function createVerifyGateSnapshot({ cwd, changeName, specBase, platformOpts = {} }) {
+export async function createVerifyGateSnapshot({ cwd, changeName, specBase, platformOpts = {}, failRef = null }) {
+  const setFail = (reason) => { if (failRef && typeof failRef === 'object') failRef.reason = reason }
   try {
     const { resolveVerifyChangedFiles } = await import('../verify-postcheck.js')
     const { resolveRuntimeRoot } = await import('./shared.js')
@@ -879,10 +890,19 @@ export async function createVerifyGateSnapshot({ cwd, changeName, specBase, plat
     let verifyRuntimeRoot = null
     try { verifyRuntimeRoot = resolveRuntimeRoot(platformOpts, specBase) } catch { verifyRuntimeRoot = null }
     const { splitOwnVsForeignDiffFiles } = await import('../foreign-declared.js')
-    let changeFiles = resolveVerifyChangedFiles(cwd, changeName, null, {
+    // 变更文件集为空三分成因区分（坑 snapshot-fallback-reason-blind）：null=git 不可用/解析
+    // 失败；[]=HEAD 无 diff；他者声明过滤清空在下方单独计——三者处置同为回退主仓，但排查
+    // 出路完全不同，笼统「变更文件集为空」曾把 pnpm 布局拒建也误标成它。
+    const rawChangeFiles = resolveVerifyChangedFiles(cwd, changeName, null, {
       specBase, includeWorkingTree: true,
-    }) || []
-    if (changeFiles.length === 0) return null // 无变更文件集 → 无从定向，回退主仓
+    })
+    let changeFiles = rawChangeFiles || []
+    if (changeFiles.length === 0) {
+      setFail(rawChangeFiles === null
+        ? '变更文件集为空（git 不可用/解析失败——非 git 仓或 git 异常，无从定向 overlay）'
+        : '变更文件集为空（HEAD 无 diff——改动可能已全部提交，无可隔离面）')
+      return null // 无变更文件集 → 无从定向，回退主仓
+    }
     // 他者声明归属过滤（坑 verify-reconcile-foreign-wip 同款）：in-place 模式 working-tree
     // 并入后主仓全部在途文件进场——他者活跃变更显式声明的文件（quick --files / 他者 design
     // 清单）剔除，只留本变更相关面（无主文件保留，fail-closed 口径与 probe6 一致）。
@@ -891,7 +911,10 @@ export async function createVerifyGateSnapshot({ cwd, changeName, specBase, plat
       if (foreign.length > 0) {
         const foreignSet = new Set(foreign.map(x => x.file))
         changeFiles = changeFiles.filter(f => !foreignSet.has(f))
-        if (changeFiles.length === 0) return null
+        if (changeFiles.length === 0) {
+          setFail(`变更文件集为空（${foreign.length} 个 diff 文件全部被他者声明过滤——并行会话声明面覆盖了本变更全部在途文件）`)
+          return null
+        }
       }
     } catch { /* 过滤失败退全量（fail-closed：宁可多 overlay 不漏本变更文件） */ }
 
@@ -920,8 +943,12 @@ export async function createVerifyGateSnapshot({ cwd, changeName, specBase, plat
       }
     } catch { /* meta 读取失败 → 主仓 cwd 源（files 已含本变更 working-tree 改动） */ }
 
-    const snap = createGateSnapshot({ cwd, files: changeFiles, sourceRoot, mergeBase: snapMergeBase, runtimeRoot: verifyRuntimeRoot })
-    if (!snap) return null
+    const snap = createGateSnapshot({ cwd, files: changeFiles, sourceRoot, mergeBase: snapMergeBase, runtimeRoot: verifyRuntimeRoot, failRef })
+    if (!snap) {
+      // createGateSnapshot 已把具体原因写进同一 failRef；无 reason（旧形态兜底）补笼统口径
+      if (failRef && typeof failRef === 'object' && !failRef.reason) setFail('快照基建不可用（createGateSnapshot 返回 null，无更细原因）')
+      return null
+    }
 
     // 变更文档随快照：module-impact.md（test_strategy=evidence-auto 消费）/tasks.md 等
     // 在 .sillyspec（gitignore）不进 HEAD，从主仓 specBase 复制 changes/<name>/**
@@ -940,7 +967,26 @@ export async function createVerifyGateSnapshot({ cwd, changeName, specBase, plat
     } catch { /* 文档复制失败不连坐快照（test_strategy 降级 module 集仍可跑） */ }
 
     return { ...snap, changeFileCount: changeFiles.length, sourceRoot }
-  } catch {
-    return null // 任一链路异常 → 回退主仓现行为
+  } catch (e) {
+    // 任一链路异常 → 回退主仓现行为。异常细节不再静默（坑 snapshot-fallback-reason-blind）：
+    // failRef 带原因 + warn 落日志，排查不再靠 stdout 考古。
+    setFail(`快照链路异常: ${e && e.message ? e.message : e}`)
+    try { console.warn(`⚠️ 门禁快照链路异常（回退主仓实测）: ${e && e.stack ? e.stack.split('\n')[0] : e}`) } catch { /* 输出失败不影响回退 */ }
+    return null
   }
 }
+
+/**
+ * 快照口径观测字段（坑 snapshot-fallback-reason-blind，FR-04 落盘面）：--done 实测门把
+ * used_snapshot 与降级原因经 runVerifyTestCheck 的 observability 通道带进 test-result.json
+ * extra（对齐 2026-10-09 复用观测先例）。快照在场时记录随快照销毁（无可降级事实）；
+ * 回退主仓时记录恰好落在主仓 .runtime——降级证据存活在主仓，与用途一致。
+ * @param {boolean} used 快照是否真实在场
+ * @param {{ reason?: string }|null} failRef createVerifyGateSnapshot 的出参（可 null）
+ * @returns {{ used_snapshot: boolean, snapshot_fallback_reason?: string }}
+ */
+export function snapshotObservability(used, failRef) {
+  if (used) return { used_snapshot: true }
+  const reason = failRef && failRef.reason ? String(failRef.reason) : 'createVerifyGateSnapshot 返回 null（变更文件集为空 / 快照基建不可用）'
+  return { used_snapshot: false, snapshot_fallback_reason: reason }
+}