sillyspec 3.33.0 → 3.33.1

package/src/run/gates.js

@@ -28,6 +28,7 @@
  * 不搬：ensureDepsFreshness（execute 入口 deps 自检，调用方 runStage 非 completeStep，归属未来 execute-handler）
  */
 import { basename, join, relative, dirname } from 'node:path'
+import { runtimeStatePath } from '../runtime-paths.js'
 import { createHash } from 'node:crypto'
 import { execFileSync } from 'node:child_process'
 import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs'
@@ -444,8 +445,8 @@ export async function enforceDepsGate(stageName, cwd, changeName, step, steps, c
   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`))
+      const legitimatelyEnded = existsSync(runtimeStatePath(runtimeRoot, `apply-pathspec-${changeName}.txt`))
+        || existsSync(runtimeStatePath(runtimeRoot, `execute-cleanup-${changeName}.json`))
       if (legitimatelyEnded) {
         console.log('ℹ️  worktree 已在 apply/execute 收尾时正当清理（凭据在 .runtime），deps 门放行')
         return true
@@ -549,7 +550,7 @@ function rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx,
 
 /** 档位状态文件路径（runtimeRoot 下 per-change；命名对齐 apply-pathspec-<change>.txt 先例） */
 function ceremonyTierFilePath(runtimeRoot, changeName) {
-  return join(runtimeRoot, `ceremony-tier-${changeName}.json`)
+  return runtimeStatePath(runtimeRoot, `ceremony-tier-${changeName}.json`)
 }
 
 /**
@@ -1100,17 +1101,24 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     // 变更文档随快照（test_strategy 消费）。并行会话在途文件物理不进快照、不参与本门判定。
     // 快照基建失败 → 回退主仓现行为（失败路径沿用 renderVerifyTestAttribution 归因提示）。
     let verifyGateSnap = null
+    let snapshotFailRef = null // createVerifyGateSnapshot 出参：结构化失败原因（FR-04，替代硬编码笼统文案）
     if (!process.env.SILLYSPEC_VERIFY_GATE_SNAPSHOT_OFF) {
       try {
         const { createVerifyGateSnapshot } = await import('./gate-snapshot.js')
-        verifyGateSnap = await createVerifyGateSnapshot({ cwd, changeName, specBase, platformOpts })
+        snapshotFailRef = {}
+        verifyGateSnap = await createVerifyGateSnapshot({ cwd, changeName, specBase, platformOpts, failRef: snapshotFailRef })
         if (verifyGateSnap) {
           console.log(`🧪 Verify 实测隔离快照（根：${verifyGateSnap.snapshotRoot}）：HEAD + 本变更 ${verifyGateSnap.changeFileCount} 个文件${verifyGateSnap.sourceRoot ? '（overlay 自 worktree——本变更分支内容定向跑）' : ''}（并行会话脏文件不参与门判定）`)
         } else {
-          // FR-02（2026-10-09-verify-reuse-friction）：null 回退与异常回退同等可见 + 记账
+          // FR-02（2026-10-09-verify-reuse-friction）：null 回退与异常回退同等可见 + 记账；
+          // FR-04（2026-10-16-fix-downstream-tool-defects）：reason 消费 failRef 结构化原因
+          // （pnpm 布局拒建 / 文件集为空三分成因 / junction 失败 / 基建异常详情），不再笼统
           try {
             const { reportGateSnapshotFallback } = await import('./gate-snapshot.js')
-            if (typeof reportGateSnapshotFallback === 'function') await reportGateSnapshotFallback({ cwd, changeName, platformOpts, where: 'verify --done 实测门', reason: 'createVerifyGateSnapshot 返回 null（变更文件集为空 / 快照基建不可用）' })
+            const fbReason = snapshotFailRef && snapshotFailRef.reason
+              ? `createVerifyGateSnapshot 返回 null：${snapshotFailRef.reason}`
+              : 'createVerifyGateSnapshot 返回 null（变更文件集为空 / 快照基建不可用）'
+            if (typeof reportGateSnapshotFallback === 'function') await reportGateSnapshotFallback({ cwd, changeName, platformOpts, where: 'verify --done 实测门', reason: fbReason })
           } catch { /* 报告失败不改变回退行为（含测试 mock 模块缺导出的形态） */ }
         }
       } catch (e) {
@@ -1120,6 +1128,22 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
         } catch { /* 报告失败不改变回退行为（含测试 mock 模块缺导出的形态） */ }
       }
     }
+    // FR-04 降级事实落盘：used_snapshot 与失败原因随 test-result.json extra 持久化（快照在场
+    // 时记录随快照销毁；回退主仓时恰好落在主仓 .runtime——降级证据存活面与用途一致）。
+    // 评审 P3-2 整改：OFF 开关是主动关闸，不得记成「基建故障/文件集为空」的笼统回退原因。
+    let snapObsFields
+    if (process.env.SILLYSPEC_VERIFY_GATE_SNAPSHOT_OFF) {
+      snapObsFields = { used_snapshot: false, snapshot_fallback_reason: 'SILLYSPEC_VERIFY_GATE_SNAPSHOT_OFF=1 主动关闸（快照未尝试，非基建故障）' }
+    } else if (verifyGateSnap) {
+      snapObsFields = { used_snapshot: true }
+    } else {
+      try {
+        const { snapshotObservability } = await import('./gate-snapshot.js')
+        snapObsFields = snapshotObservability(false, snapshotFailRef)
+      } catch {
+        snapObsFields = { used_snapshot: false, snapshot_fallback_reason: snapshotFailRef && snapshotFailRef.reason ? String(snapshotFailRef.reason) : 'createVerifyGateSnapshot 返回 null（变更文件集为空 / 快照基建不可用）' }
+      }
+    }
     const gateCwd = verifyGateSnap ? verifyGateSnap.snapshotRoot : cwd
     const gateSpecBase = verifyGateSnap ? join(verifyGateSnap.snapshotRoot, '.sillyspec') : specBase
     let testCheck
@@ -1220,7 +1244,7 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
         `质量扫描: ${reusableScan ? '命中（上层未消费）' : '指纹失配/无记录'}`,
         `green-cache: ${greenHit ? '命中（上层未消费）' : '指纹失配/过期/无记录'}`,
       ].join('；')
-      testCheck = runVerifyTestCheck({ cwd: gateCwd, specBase: gateSpecBase, changeName, ctx, observability: { fingerprint: _obsFingerprint, reuse_decision: { layer: 'real-run', hit: false, reason: _missReason } }, ...(Array.isArray(_restrict) && _restrict.length > 0 ? { restrictFiles: _restrict } : {}) })
+      testCheck = runVerifyTestCheck({ cwd: gateCwd, specBase: gateSpecBase, changeName, ctx, observability: { fingerprint: _obsFingerprint, reuse_decision: { layer: 'real-run', hit: false, reason: _missReason }, ...snapObsFields }, ...(Array.isArray(_restrict) && _restrict.length > 0 ? { restrictFiles: _restrict } : {}) })
       printVerifyTestCheck(testCheck)
       // 自动绑定补全（full-autopilot-parity，R21 thin 迁移）：测试已跑、test-result.json 已落盘，
       // verify --done 收口时从测试结果自动补全 requirements.md 的空绑定槽——与 thin 同逻辑（逐行扫描）。

package/src/run/prompt.js

@@ -19,6 +19,7 @@
  *   - loadModuleContextIndex/buildModuleContextInjection 内 require('fs'/'path') 改顶部静态 import
  */
 import { basename, dirname, join } from 'node:path'
+import { runtimeStatePath } from '../runtime-paths.js'
 import { existsSync, readFileSync, mkdirSync, readdirSync, writeFileSync, rmSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import jsYaml from 'js-yaml'
@@ -868,7 +869,7 @@ export async function renderPreflightFailures({ stageName, stepName, cwd, specBa
 export function shouldInjectFullContext({ changeName, stageName, runtimeRoot } = {}) {
   try {
     if (!runtimeRoot || !changeName || !stageName) return { full: true }
-    const ledgerPath = join(runtimeRoot, `prompt-inject-${changeName}.json`)
+    const ledgerPath = runtimeStatePath(runtimeRoot, `prompt-inject-${changeName}.json`)
     if (!existsSync(ledgerPath)) return { full: true }
     const ledger = JSON.parse(readFileSync(ledgerPath, 'utf8'))
     const rec = (ledger && ledger.stages && typeof ledger.stages === 'object') ? ledger.stages[stageName] : null
@@ -906,7 +907,7 @@ function renderPromptInjectSummaryLine({ firstStep, digest, specBase, projectNam
  * @param {{ runtimeRoot: string, changeName: string, stageName: string, firstStep: number, digest: string }} args
  */
 async function recordPromptInjectLedger({ runtimeRoot, changeName, stageName, firstStep, digest }) {
-  const ledgerPath = join(runtimeRoot, `prompt-inject-${changeName}.json`)
+  const ledgerPath = runtimeStatePath(runtimeRoot, `prompt-inject-${changeName}.json`)
   await withFileLock(ledgerPath + '.lock', () => {
     let ledger = null
     try { ledger = JSON.parse(readFileSync(ledgerPath, 'utf8')) } catch { ledger = null }
@@ -1428,7 +1429,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       // 注入结果同步落 runtime JSON（与既有 KNOWLEDGE_HIT_REPORT 落盘口径一致）
       const decRuntimeDir = join(decSpecBase, '.runtime')
       mkdirSync(decRuntimeDir, { recursive: true })
-      writeAtomicSync(join(decRuntimeDir, 'decision-hits.json'), JSON.stringify({ matched: decResult.matched, decisionHits: decResult.decisionHits || [] }, null, 2) + '\n')
+      writeAtomicSync(runtimeStatePath(decRuntimeDir, 'decision-hits.json'), JSON.stringify({ matched: decResult.matched, decisionHits: decResult.decisionHits || [] }, null, 2) + '\n')
     } catch (e) {
       substitute(/\{DECISION_HITS\}/g, `[decisions] 决策命中检测异常（${e.message}），跳过`)
     }
@@ -1495,7 +1496,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       )
       // 写入 runtime JSON（既有机制照旧，新旧遥测共存）
       mkdirSync(runtimeDir, { recursive: true })
-      writeAtomicSync(join(runtimeDir, 'knowledge-hit-report.json'), JSON.stringify(knowledgeInjection.json, null, 2) + '\n')
+      writeAtomicSync(runtimeStatePath(runtimeDir, 'knowledge-hit-report.json'), JSON.stringify(knowledgeInjection.json, null, 2) + '\n')
     } catch (e) {
       substitute(/\{KNOWLEDGE_HIT_REPORT\}/g, 'Status: no matches (error: ' + e.message + ')')
     }
@@ -1552,7 +1553,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     let runId = ''
     const execSpecBase = resolvePromptSpecBase(platformOpts, cwd)
     const runtimeRoot = resolveRuntimeRoot(platformOpts, execSpecBase)
-    const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
+    const runIdFile = runtimeStatePath(runtimeRoot, `current-execute-run-id-${changeName}`)
     try {
       if (existsSync(runIdFile)) {
         const c = readFileSync(runIdFile, 'utf8').trim()

package/src/run/scan-profile.js

@@ -9,6 +9,7 @@
  *   - executeScanPostcheck 原冗余动态 import('fs'/'path'/'child_process') 删除，改顶部静态（execSync 实际未直接用，纯遗留）
  */
 import { join, basename, extname } from 'node:path'
+import { runtimeStatePath } from '../runtime-paths.js'
 import { existsSync, readdirSync, statSync, mkdirSync, writeFileSync, unlinkSync, readFileSync } from 'node:fs'
 import { safeGit, resolveRuntimeRoot } from './shared.js'
 import { SCAN_REQUIRED_DOCS } from '../constants.js'
@@ -332,7 +333,7 @@ export async function executeScanResumeCheck(cwd, platformOpts) {
   // .runtime/last-delta.json（归档/delta 补跑写入的最近变更快照），14 天窗口内提示本轮
   // scan 优先核对其涉及模块——advisory 不阻断不改变步骤结构；缺失/过期/解析失败静默。
   try {
-    const sidecarPath = join(resolveRuntimeRoot(platformOpts, specBase), 'last-delta.json')
+    const sidecarPath = runtimeStatePath(resolveRuntimeRoot(platformOpts, specBase), 'last-delta.json')
     if (existsSync(sidecarPath)) {
       const sidecar = JSON.parse(readFileSync(sidecarPath, 'utf8'))
       const ageMs = Date.now() - Date.parse(sidecar.updatedAt || '')

package/src/run/shared.js

@@ -11,6 +11,7 @@
  *     本模块仅 re-export，run/ 层现有调用方路径与行为不变。
  */
 import { basename, join, resolve, dirname, sep } from 'node:path'
+import { runtimeTempPath } from '../runtime-paths.js'
 import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, appendFileSync, realpathSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import os from 'node:os'
@@ -644,7 +645,7 @@ export function warnSelfRefPointerOnce(cwd, specRoot, message) {
   try {
     const dir = join(cwd, '.sillyspec', '.runtime')
     mkdirSync(dir, { recursive: true })
-    const markerPath = join(dir, SELFREF_WARN_MARKER)
+    const markerPath = runtimeTempPath(dir, SELFREF_WARN_MARKER)
     const now = Date.now()
     try {
       const m = JSON.parse(readFileSync(markerPath, 'utf8'))
@@ -943,7 +944,9 @@ async function raceWithAbort(op, timeoutMs = resolveSyncTotalTimeoutMs()) {
   const controller = new AbortController()
   let timer
   try {
-    await Promise.race([
+    // 透传 op 结果（2026-10-17 终态强校验消费）：历史调用方（triggerSync 等）忽略返回值
+    // 不受影响；超时分支 resolve(null)——消费方以 null 判「预算熔断」。
+    return await Promise.race([
       op({ signal: controller.signal }),
       new Promise((resolve) => { timer = setTimeout(() => { controller.abort(); resolve(null) }, timeoutMs) }),
     ])
@@ -1039,6 +1042,86 @@ export async function triggerSync(cwd, changeName, platformOpts = {}, opts = {})
   }
 }
 
+/**
+ * 终态强校验同步（2026-10-17-archive-half-state-location-stuck-active）。
+ *
+ * 背景（坑档案 docs/sillyspec/archive-half-state-location-stuck-active.md，生产实证）：
+ * triggerSync 全链 best-effort + 后台化，重试是事件驱动（「下一条命令」）——而归档/删除
+ * 是变更生命周期最后一个动作，之后大概率没有下一条命令。平台慢窗口内 DB 通道
+ * （status=archived）成功而文件树通道（location）失败 → 半态：平台「进行中」列表
+ * 幽灵滞留已归档变更，无人再碰则无限期。
+ *
+ * 与 triggerSync 的三点差异：
+ *   1. **终态判定驱动**：仅当 DB 该变更 status ∈ (archived, deleted) 才走强校验；
+ *      非终态（普通阶段完成的 completion 同步等）原样委托 triggerSync（后台化不变，
+ *      零行为变化）。归档收尾允许阻塞换一致性——终态动作没有「下次再推」的假设。
+ *   2. **内联有界**：绕过后台化（结果不再藏进 bg 日志文件），sync() 直跑 + raceWithAbort
+ *      预算 = max(env SILLYSPEC_SYNC_TIMEOUT_MS 可调值, 45s 后台轮下限同款)；opts.timeoutMs
+ *      显式传入时直接生效（测试注入短窗）。
+ *   3. **失败显性化**：sync() 返回 treeOk!==true（syncSpecTree ok 契约，fail-closed——
+ *      无 ok 字段视同未确认）→ 🚨 告警 + 自救命令 + process.exitCode = 1（对齐
+ *      _submitApproval 的「终态网络失败必须可见」先例）。未决冲突（result.conflict）
+ *      不在此列——冲突面已有自己的 resolve 处置横幅，重复告警是噪音。
+ *
+ * @returns {{confirmed: boolean, delegated?: boolean, skipped?: string, result?: object}}
+ */
+export async function triggerSyncTerminalStrict(cwd, changeName, platformOpts = {}, opts = {}) {
+  // quick 会话无实体变更目录（无归档/删除终态）——沿用既有 best-effort 语义
+  if (changeName && QUICK_SID_RE.test(changeName)) {
+    await triggerSync(cwd, changeName, platformOpts, opts)
+    return { confirmed: false, delegated: true }
+  }
+  const syncMod = await import('../sync.js')
+  // 未连接平台：静默 no-op（本地合法状态；强校验只在平台模式下有意义）
+  if (!syncMod.peekPlatformConnected(cwd, platformOpts)) {
+    return { confirmed: false, skipped: 'not-connected' }
+  }
+  // 终态判定（fail-open：DB 读不到/解析失败 → 非终态委托既有语义，不因校验层故障阻断主链）
+  // opts.changeStatus / opts.syncImpl：测试注入缝（对齐 bakeArchiveTimeline writeImpl 惯例）
+  let dbStatus = opts.changeStatus ?? null
+  if (dbStatus === null) {
+    try {
+      const { resolvePlatformSpecDir, ProgressManager } = await import('../progress.js')
+      const specDir = resolvePlatformSpecDir(cwd)
+      if (specDir && existsSync(join(specDir, '.runtime', 'sillyspec.db'))) {
+        const pm = new ProgressManager({ specDir })
+        const row = pm._ensureDB(cwd).getDb().prepare(
+          'SELECT status FROM changes WHERE name = ?'
+        ).get(changeName)
+        dbStatus = row ? row.status : null
+      }
+    } catch { /* 判定失败按非终态处理 */ }
+  }
+  if (dbStatus !== 'archived' && dbStatus !== 'deleted') {
+    await triggerSync(cwd, changeName, platformOpts, opts)
+    return { confirmed: false, delegated: true }
+  }
+  // 终态：内联有界同步（绕过后台化——结果必须当场可判）
+  const timeoutMs = opts.timeoutMs ?? Math.max(resolveSyncTotalTimeoutMs(), 45_000)
+  let result = null
+  try {
+    // raceWithAbort 向 op 传入 { signal } 形状对象（非裸 AbortSignal，与既有 triggerSync
+    // 内联用法 `sync(name, cwd, sig)` 同一形状）——默认路径原样透传，禁止二次包装
+    //（dogfood 实证：包装成 { signal: sig } 会把套娃对象传进 AbortSignal.any → TypeError，
+    //  强校验当场以 🚨 告警兜住——安全网本身工作正常，此处修被网住的 bug）。
+    const runSync = opts.syncImpl || ((syncOpts) => syncMod.sync(changeName, cwd, syncOpts))
+    result = await raceWithAbort(runSync, timeoutMs)
+  } catch (e) {
+    result = { synced: 0, errors: [(e && e.message) || String(e)] }
+  }
+  if (result === null) result = { synced: 0, errors: [`同步总预算 ${timeoutMs}ms 熔断`] }
+  // 未决冲突：已有 resolve 处置横幅（syncSpecTree 冲突分支自带），不重复告警
+  if (result.conflict === true) return { confirmed: false, skipped: 'conflict', result }
+  const confirmed = result.treeOk === true
+  if (!confirmed) {
+    const detail = ((result.errors && result.errors[0]) || '文件树通道未确认收敛（见上方 [spec-sync]/[sync] 行）').slice(0, 200)
+    console.error(`🚨 [终态同步] 本地${dbStatus === 'deleted' ? '删除' : '归档'}已完成，但平台文件树推送未确认：${detail}`)
+    console.error(`   平台变更中心可能滞留「进行中」半态。自救（幂等）：sillyspec platform sync --change ${changeName}`)
+    if (opts.exitOnUnconfirmed !== false) process.exitCode = 1
+  }
+  return { confirmed, result }
+}
+
 /**
  * 触发步骤开始上报（X3 / design §8.2，变更 2026-08-29-change-delete-closure-and-spec-pull task-13）。
  *
@@ -1087,7 +1170,8 @@ const AUTO_PULL_THROTTLE_MS = 10_000
 const AUTO_PULL_TIMEOUT_MS = 2_000
 
 function _autoPullThrottlePath(cwd) {
-  return join(cwd, '.sillyspec', '.runtime', 'auto-pull-throttle.json')
+  // 2026-10-18 布局分层：节流戳是可再生产物归 temp/；路径助手自带 mkdir-p
+  return runtimeTempPath(join(cwd, '.sillyspec', '.runtime'), 'auto-pull-throttle.json')
 }
 
 function _autoPullRecently(cwd) {
@@ -1546,15 +1630,35 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
     // gen:types 重写行尾制造假 M）：git diff --ignore-cr-at-eol HEAD 的变更名单是「真实内容变更」
     // 集——tracked 修改出现在 porcelain 但不在此集 = 纯行尾重写。单次对照调用，剔出 changedFiles
     // 归 eolOnlyFiles 软警告（.gitattributes 指引），不再计入文件行/触发各门。
+    // 探测必须走 --numstat：--name-only 不吃 --ignore-cr-at-eol（git 实测怪癖——git ≤2.43 仍把
+    // 行尾-only 文件列进名单，Debian 12 git 2.39.5 / Ubuntu 24.04 git 2.43.0 实测；git ≥2.54 才
+    // 听话），走 --name-only 会让本过滤在老 git 上静默失效、假 M 坑复活。同
+    // verify-postcheck reconcileActualFiles 的 eolOnlyFiles 探测同口径（该处已按此结论实装）。
     // 注意：gitQuiet 不在本模块 import 面（safeGit 才是）——首版用 gitQuiet 触发
     // ReferenceError 被 catch 吞成 null，又被 new Set(null) 包装成空集 → 全部 tracked 修改
     // 被误判 EOL-only 剔除（audit-quick-completion 回归抓出）。改用 safeGit（已 import，
     // 返回 {value,error}），失败显式落 null 透传不过滤。
+    // -z 记录文法（od 实测，git 2.39.5 与 2.54 同形）：普通条目 `<A>\t<D>\t<path>\0`；
+    // rename `<A>\t<D>\t\0<old>\0<new>\0`（计数后路径字段为空，旧/新名各占一个 NUL 字段）——
+    // 按位置取新名。非 -z 的 `old => new` 文本形态与「文件名里字面含 ` => `」不可区分（实测
+    // `sub/a => b.js` 真实内容变更会被误判 rename 而剔出 changedFiles——审计放宽），-z 消歧。
+    // -z 同时不做引号/C 转义，路径原样出（与 porcelain 侧键更一致）。
+    const numstatZPaths = (out) => {
+      const toks = String(out).split('\0')
+      const paths = []
+      for (let i = 0; i < toks.length; i++) {
+        const m = toks[i].match(/^(?:\d+|-)\t(?:\d+|-)\t(.*)$/s)
+        if (!m) continue
+        if (m[1] === '') { paths.push(String(toks[i + 2] || '')); i += 2 }
+        else paths.push(m[1])
+      }
+      return paths.filter(Boolean)
+    }
     const eolRawList = (() => {
       try {
-        const res = safeGit(cwd, ['diff', '--name-only', '--ignore-cr-at-eol', 'HEAD'], { timeout: 30000 })
+        const res = safeGit(cwd, ['diff', '--numstat', '-z', '--ignore-cr-at-eol', 'HEAD'], { timeout: 30000 })
         if (!res || res.error) return null
-        return String(res.value || '').split('\n').filter(Boolean).map(p => p.replace(/\\/g, '/'))
+        return numstatZPaths(String(res.value || ''))
       } catch { return null }
     })()
     const eolRealChanged = eolRawList === null ? null : new Set(eolRawList)

package/src/run/stage.js

@@ -17,6 +17,7 @@
  *   - 'child_process'（execSync）裸模块名不变
  */
 import { join, dirname } from 'node:path'
+import { runtimeStatePath } from '../runtime-paths.js'
 import { existsSync, readdirSync, readFileSync, mkdirSync, rmSync, unlinkSync } from 'node:fs'
 import { writeAtomicSync } from '../fs-atomic.js'
 import { resolveSpecDir, resolveChangeDir, resolveRuntimeRoot, resolveQuickSessionsDir, triggerSync, safeGit, formatWaitOptions, checkApproval, getStageSteps, warnApprovalUnknown, predictProtectedQuickFiles, mergeQuickBoundaryFiles, readStageBurst, STAGE_BURST_STAGES, readStageWall, STAGE_WALL_STAGES } from './shared.js'
@@ -55,7 +56,7 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         const curSession = process.env.SILLYSPEC_SESSION_ID || ''
         const wallStageData = progress.stages && progress.stages[stageName]
         const firstEntry = !wallStageData || !Array.isArray(wallStageData.steps) || wallStageData.steps.length === 0
-        const wallLedgerPath = join(specBase, '.runtime', `stage-session-ledger-${changeName}.json`)
+        const wallLedgerPath = runtimeStatePath(join(specBase, '.runtime'), `stage-session-ledger-${changeName}.json`)
         if (curSession && firstEntry && existsSync(wallLedgerPath)) {
           const wallLedger = JSON.parse(readFileSync(wallLedgerPath, 'utf8'))
           const { isStageWallBlocked } = await import('./shared.js')
@@ -151,7 +152,7 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
     const { generateExecuteRunId, isValidExecuteRunId, claimExecuteRunId } = await import('../task-review.js')
     const execSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
     const runtimeRoot = resolveRuntimeRoot(platformOpts, execSpecBase)
-    const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
+    const runIdFile = runtimeStatePath(runtimeRoot, `current-execute-run-id-${changeName}`)
     mkdirSync(runtimeRoot, { recursive: true })
     // 优先读取已有的变更专属标记文件（agent 可写内容，格式校验防注入/穿越，非法视为缺失重生成）
     try {
@@ -325,7 +326,7 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         startedAt: new Date().toISOString(),
         forceRescan: quickOpts?.isForceRescan || false,
       }
-      const guardFile = join(specBase, '.runtime', 'scan-guard.json')
+      const guardFile = runtimeStatePath(join(specBase, '.runtime'), 'scan-guard.json')
       mkdirSync(dirname(guardFile), { recursive: true })
       // 原子写：hook 进程（worktree-guard 的 readScanGuard）并发读，裸 truncate→write 的
       // 半截窗口会被 JSON.parse 吞成 null → 覆盖保护静默失效（fail-open）
@@ -417,7 +418,7 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
       // 进程内直调 runCommand 的入口（测试/编程调用）与 --change 指向不存在会话的形态。
       console.error(`❌ quick 通道已退役，无法启动 quick 会话（若带 --change 则该会话不存在或已清理）。`)
       console.error(`   新工作请走轻量变更（--input 引号内换行合法，可照抄）：`)
-      console.error('   sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句中文概括（首行即变更标题）；随后动机与背景')
+      console.error('   sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句 10-30 字中文概括（首行即变更标题，硬区间 10-30 必须、建议 ~20 字）；随后动机与背景')
       console.error('')
       console.error('   成功标准：')
       console.error('   - <可验证标准>"')

package/src/run/test-ledger.js

@@ -36,6 +36,7 @@
  * （meta.json 并发读先例同款约束）。
  */
 import { createHash } from 'crypto'
+import { runtimeStatePath } from '../runtime-paths.js'
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
 import { join, relative, isAbsolute } from 'path'
 import { gitQuiet } from '../git-helper.js'
@@ -209,7 +210,7 @@ function ledgerKeyFor({ runtimeRoot, changeName, projectRoot, testRoot, specBase
 
 /** 账本路径（per-change 单文件） */
 export function testLedgerPath(runtimeRoot, changeName) {
-  return join(runtimeRoot, `test-ledger-${changeName}.json`)
+  return runtimeStatePath(runtimeRoot, `test-ledger-${changeName}.json`)
 }
 
 /**

package/src/run/verify-quality-scan.js

@@ -27,6 +27,7 @@
  *      刻意区分）。指纹已含 commands 段原文——配置 smoke 前后指纹自动变化，代码未变不重跑。
  */
 import { createHash } from 'node:crypto'
+import { runtimeStatePath } from '../runtime-paths.js'
 import { execSync, spawnSync } from 'node:child_process'
 import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs'
 import { join, dirname } from 'node:path'
@@ -43,7 +44,7 @@ const RECORD_SCHEMA_VERSION = 1
 
 export function qualityScanRecordPath(specBase, changeName) {
   if (!changeName) return null
-  return join(specBase, '.runtime', `verify-quality-scan-${changeName}.json`)
+  return runtimeStatePath(join(specBase, '.runtime'), `verify-quality-scan-${changeName}.json`)
 }
 
 /**
@@ -365,7 +366,7 @@ export async function renderVerifyTestAttribution({ cwd, changeName, specBase, r
     // 第二判据（坑 derived-artifact-stale-baseline / verify-attr2-foreign-wip-misdirection）：
     // 完整语义见 gates.js filterStaleBaselineOverlap 注释——两道过滤（必须 dirty + 剔除他者声明集）。
     try {
-      const pathspecFile = join(runtimeRoot, `apply-pathspec-${changeName}.txt`)
+      const pathspecFile = runtimeStatePath(runtimeRoot, `apply-pathspec-${changeName}.txt`)
       if (changeName && existsSync(pathspecFile)) {
         const ownFiles = new Set(readFileSync(pathspecFile, 'utf8').split('\n').map((l) => l.trim()).filter(Boolean).map((f) => f.replace(/\\/g, '/')))
         if (ownFiles.size > 0) {
@@ -655,14 +656,19 @@ export async function executeVerifyQualityScan({ cwd, specBase, changeName, plat
     } else {
     try {
       const { createVerifyGateSnapshot } = await import('./gate-snapshot.js')
-      snap = await createVerifyGateSnapshot({ cwd, changeName, specBase, platformOpts })
+      const snapshotFailRef = {} // FR-04：结构化失败原因（pnpm 布局拒建/文件集三分成因/junction/基建异常）
+      snap = await createVerifyGateSnapshot({ cwd, changeName, specBase, platformOpts, failRef: snapshotFailRef })
       if (snap) {
         console.log(`🧪 noAI 扫描隔离快照（根：${snap.snapshotRoot}）：HEAD + 本变更 ${snap.changeFileCount} 个文件${snap.sourceRoot ? '（overlay 自 worktree——本变更分支内容定向跑）' : ''}（并行会话脏文件不参与判定）`)
       } else {
-        // FR-02（2026-10-09-verify-reuse-friction）：null 回退与异常回退同等可见 + 记账
+        // FR-02（2026-10-09-verify-reuse-friction）：null 回退与异常回退同等可见 + 记账；
+        // FR-04（2026-10-16-fix-downstream-tool-defects）：reason 消费 failRef 结构化原因，不再笼统
         try {
           const { reportGateSnapshotFallback } = await import('./gate-snapshot.js')
-          if (typeof reportGateSnapshotFallback === 'function') await reportGateSnapshotFallback({ cwd, changeName, platformOpts, where: 'noAI 质量扫描步', reason: 'createVerifyGateSnapshot 返回 null（变更文件集为空 / 快照基建不可用）' })
+          const fbReason = snapshotFailRef && snapshotFailRef.reason
+            ? `createVerifyGateSnapshot 返回 null：${snapshotFailRef.reason}`
+            : 'createVerifyGateSnapshot 返回 null（变更文件集为空 / 快照基建不可用）'
+          if (typeof reportGateSnapshotFallback === 'function') await reportGateSnapshotFallback({ cwd, changeName, platformOpts, where: 'noAI 质量扫描步', reason: fbReason })
         } catch { /* 报告失败不改变回退行为（含测试 mock 模块缺导出的形态） */ }
       }
     } catch (e) {

package/src/runtime-paths.js

@@ -0,0 +1,189 @@
+/**
+ * runtime-paths.js — .runtime 布局分层（state/ 与 temp/）与旧布局一次性迁移。
+ *
+ * 背景（2026-10-18 用户反馈）：.runtime 根目录堆积 1649 个条目——22 类按 change 命名
+ * 等 24 类散文件不在归档回收名单、日志/db 备份与核心
+ * 状态混放。分野沿用 runtime-hygiene.js 的定界思路，按「删除是否安全」切两层：
+ * - **state/**：按 change 命名的派生状态（watcher 事件流、draft ledger、冲突标记…）。
+ *   活跃变更在读，归档/删除后无读者——由 pruneArchivedChangeRuntime 精确回收。
+ * - **temp/**：可随时整体删除的产物（watcher.log / spec-sync-bg.log / audit.log /
+ *   db 备份 .bak|.corrupt-*|.pre-import-* / 锁残留 *.tmp）。无不可再生的状态语义。
+ *
+ * 家族表是唯一清单源（写入点路径助手 + 归档回收精确名 + 迁移前缀匹配三方共源，
+ * 防三处清单漂移）。契约：
+ * - 迁移幂等：目标已存在则跳过（不覆盖——混版本窗口防旧进程迟到文件盖掉新文件）；
+ *   逐条 try/catch fail-open，绝不抛（卫生动作不阻断主流程，与 runtime-hygiene 同族）。
+ * - 迁移只动已知家族与已知临时产物，未知文件一律不动（用户/工具自置文件无归属语义）。
+ * - 文件名一概保持原样，仅目录前缀变化——写入点改动=一行 join 换助手，读写面零重命名。
+ */
+import { existsSync, mkdirSync, readdirSync, renameSync } from 'fs'
+import { join } from 'path'
+
+export const RUNTIME_STATE_DIRNAME = 'state'
+export const RUNTIME_TEMP_DIRNAME = 'temp'
+
+/**
+ * state/ 家族表：prefix 用于迁移匹配与回收名生成；ext 是文件名后缀；
+ * stages 特例仅 current-stage-review-run-id（无扩展名且内嵌 stage 枚举
+ * brainstorm|plan|execute——stage-review.js stageReviewMarkerPath 的构造形态）。
+ */
+const STATE_FAMILIES = [
+  { prefix: 'sync-docs-lastpush-', ext: '.json' },
+  { prefix: 'draft-ledger-', ext: '.json' },
+  { prefix: 'route-hindsight-baseline-', ext: '.json' },
+  { prefix: 'watcher-events-', ext: '.jsonl' },
+  { prefix: 'watcher-stage-timing-', ext: '.json' },
+  { prefix: 'watcher-last-snapshot-', ext: '.json' },
+  { prefix: 'test-rerun-', ext: '.json' },
+  { prefix: 'test-ledger-', ext: '.json' },
+  { prefix: 'ceremony-tier-', ext: '.json' },
+  { prefix: 'stage-session-ledger-', ext: '.json' },
+  { prefix: 'wave-session-ledger-', ext: '.json' },
+  { prefix: 'verify-draft-', ext: '.json' },
+  { prefix: 'verify-quality-scan-', ext: '.json' },
+  { prefix: 'verify-result-hwm-', ext: '.json' },
+  { prefix: 'review-dispatch-', ext: '.json' },
+  { prefix: 'review-dispatch-shadow-', ext: '.json' },
+  { prefix: 'execute-cleanup-', ext: '.json' },
+  { prefix: 'friction-tally-', ext: '.json' },
+  { prefix: 'prompt-inject-', ext: '.json' },
+  { prefix: 'sync-conflict-', ext: '.json' },
+  { prefix: 'spec-sync-conflict-', ext: '.json' },
+  { prefix: 'apply-pathspec-', ext: '.txt' },
+  { prefix: 'scope-audit-', ext: '.json' },
+  { prefix: 'scan-refresh-', ext: '.json' },
+  { prefix: 'current-execute-run-id-', ext: '' },
+  { prefix: 'current-stage-review-run-id-', ext: '', stages: ['brainstorm', 'plan', 'execute'] },
+]
+
+/**
+ * 全局面单例（无 change 归属但有读者）→ state/（2026-10-18 二轮收敛：根目录只留
+ * db/锁/会话身份/global/spec-version/user-inputs 六件核心）。迁移精确名匹配。
+ */
+export const RUNTIME_STATE_SINGLETONS = [
+  'friction-ledger.json',
+  'deleted-changes.jsonl',
+  'active-gate-snapshots.json',
+  'scan-guard.json',
+  'verify-lint-tally.json',
+  'decision-hits.json',
+  'knowledge-hits.jsonl',
+  'knowledge-hit-report.json',
+  'vector-capability.json',
+  'spec-sync-base.json',
+  'spec-sync-last-success.json',
+  'spec-sync-fail-streak.json',
+  'spec-sync-follow-reported.json',
+  'sync-noise-self-heal.json',
+  'last-delta.json',
+]
+
+/** 可再生全局单例产物（删后可重建、无不可再生状态）→ temp/。 */
+export const RUNTIME_TEMP_SINGLETONS = [
+  'doctor-diagnosis.json',
+  'flow-telemetry.jsonl',
+  'write-audit.jsonl',
+  'anon-session-warn.json',
+  'selfref-pointer-warn.json',
+  'auto-pull-throttle.json',
+]
+
+/** temp/ 侧已知产物：精确名 + 带时间戳/pid 尾的正则（corrupt/pre-import/lock-tmp）。 */
+const TEMP_EXACT = new Set(['watcher.log', 'spec-sync-bg.log', 'audit.log', 'sillyspec.db.bak'])
+const TEMP_PATTERNS = [
+  /^sillyspec\.db\.corrupt-/,
+  /^sillyspec\.db\.pre-import-/,
+  /^watcher\.lock\.\d+\.tmp$/,
+]
+
+/**
+ * state/ 下某变更的全家族精确文件名清单（归档/删除回收用；禁 glob 的精确名形态）。
+ * @param {string} changeName
+ * @returns {string[]}
+ */
+export function runtimeStateFileNames(changeName) {
+  const names = []
+  for (const f of STATE_FAMILIES) {
+    if (f.stages) {
+      for (const s of f.stages) names.push(`${f.prefix}${s}-${changeName}`)
+    } else {
+      names.push(`${f.prefix}${changeName}${f.ext}`)
+    }
+  }
+  return names
+}
+
+/**
+ * 路径助手自带目录保证（mkdir -p 语义，幂等 fail-open）：库级直调（测试/embedded）不经
+ * CLI 入口迁移，裸 writeFileSync/appendFileSync 落 state|temp 会 ENOENT——写点分散逐个补
+ * mkdir 是打地鼠（2026-10-18 实证四起），在唯一路径构造点收口。读检查顺带建空目录无害
+ * （init 预建面与入口迁移本就常态建这两层）。
+ */
+function _pathWithDir(runtimeRoot, dirname_, filename) {
+  const p = join(runtimeRoot, dirname_, filename)
+  try { mkdirSync(join(runtimeRoot, dirname_), { recursive: true }) } catch { /* fail-open：写入侧自抛真实原因 */ }
+  return p
+}
+
+/** @param {string} runtimeRoot @param {string} filename @returns {string} */
+export function runtimeStatePath(runtimeRoot, filename) {
+  return _pathWithDir(runtimeRoot, RUNTIME_STATE_DIRNAME, filename)
+}
+
+/** @param {string} runtimeRoot @param {string} filename @returns {string} */
+export function runtimeTempPath(runtimeRoot, filename) {
+  return _pathWithDir(runtimeRoot, RUNTIME_TEMP_DIRNAME, filename)
+}
+
+function _isTempArtifact(name) {
+  return TEMP_EXACT.has(name) || TEMP_PATTERNS.some((re) => re.test(name))
+}
+
+/**
+ * 旧布局一次性迁移：把 .runtime 根目录下已知家族文件移动到 state/ 或 temp/。
+ * 幂等（目标存在跳过）、fail-open（单条失败/目录缺失零副作用）、未知文件不动。
+ * @param {string} runtimeRoot .runtime 绝对路径
+ * @returns {{ stateMoved: number, tempMoved: number, skipped: number }}
+ */
+export function migrateRuntimeLayout(runtimeRoot) {
+  const out = { stateMoved: 0, tempMoved: 0, skipped: 0 }
+  let entries
+  try {
+    entries = readdirSync(runtimeRoot, { withFileTypes: true })
+  } catch {
+    return out // 目录缺失（该仓库从未跑过流程）= 无可迁
+  }
+  const prefixes = STATE_FAMILIES.map((f) => f.prefix)
+  const stateSingletons = new Set(RUNTIME_STATE_SINGLETONS)
+  const tempSingletons = new Set(RUNTIME_TEMP_SINGLETONS)
+  const moves = [] // { name, dest }
+  for (const e of entries) {
+    if (!e.isFile()) continue
+    const name = e.name
+    if (prefixes.some((p) => name.startsWith(p)) || stateSingletons.has(name)) moves.push({ name, dest: RUNTIME_STATE_DIRNAME })
+    else if (_isTempArtifact(name) || tempSingletons.has(name)) moves.push({ name, dest: RUNTIME_TEMP_DIRNAME })
+    // 未知归属：不动（用户/工具自置文件无生命周期语义，迁移不猜）
+  }
+  // 无条件预建两层目录（幂等廉价）：CLI 入口路径保证 state/ 在一切写入前就位——
+  // 新仓首跑无文件可搬，靠这里兜住「迁移零动作、写入点裸写 ENOENT」的窗口
+  for (const d of [RUNTIME_STATE_DIRNAME, RUNTIME_TEMP_DIRNAME]) {
+    try { mkdirSync(join(runtimeRoot, d), { recursive: true }) } catch { /* fail-open */ }
+  }
+  const madeDirs = new Set()
+  for (const { name, dest } of moves) {
+    const dst = join(runtimeRoot, dest, name)
+    try {
+      if (existsSync(dst)) { out.skipped++; continue } // 不覆盖：防旧进程迟到文件盖新文件
+      if (!madeDirs.has(dest)) {
+        mkdirSync(join(runtimeRoot, dest), { recursive: true }) // 并发 mkdir recursive 不抛
+        madeDirs.add(dest)
+      }
+      renameSync(join(runtimeRoot, name), dst) // 同卷原子；跨进程竞争失败即跳过下次再收
+      if (dest === RUNTIME_STATE_DIRNAME) out.stateMoved++
+      else out.tempMoved++
+    } catch {
+      out.skipped++
+    }
+  }
+  return out
+}