sillyspec 3.33.0 → 3.33.2

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
+}

package/src/scan-refresh.js

@@ -25,6 +25,7 @@
  * 无引用论断检不出。refresh 只声称「核对至 HEAD 的检出项已处理」，不声称「一致」。
  */
 import { existsSync, readFileSync, readdirSync, mkdirSync } from 'node:fs'
+import { runtimeStatePath } from './runtime-paths.js'
 import { join } from 'node:path'
 import { createHash } from 'node:crypto'
 import { safeGit } from './git-helper.js'
@@ -227,7 +228,7 @@ export function computeRefreshPlan({ projectRoot, specBase, projectName, force =
     try {
       const guardDir = join(specBase, '.runtime')
       mkdirSync(guardDir, { recursive: true })
-      writeAtomicSync(join(guardDir, 'scan-guard.json'), JSON.stringify({
+      writeAtomicSync(runtimeStatePath(guardDir, 'scan-guard.json'), JSON.stringify({
         name_zh: '增量刷新守卫',
         mode: 'scan-refresh',
         refreshDocs,
@@ -381,7 +382,7 @@ export async function finalizeRefresh(opts = {}) {
   const scanDir = join(specBase, 'docs', projectName, 'scan')
   // ①拍 guard 会话态必须存在（握手文件=工单受影响集与内容哈希的唯一来源）
   let guard = null
-  const guardPath = join(specBase, '.runtime', 'scan-guard.json')
+  const guardPath = runtimeStatePath(join(specBase, '.runtime'), 'scan-guard.json')
   try { guard = JSON.parse(readFileSync(guardPath, 'utf8')) } catch { /* 缺失/坏 JSON → 下方拒绝 */ }
   if (!guard || guard.mode !== 'scan-refresh') {
     console.error('scan refresh --done：未找到增量刷新会话态（.runtime/scan-guard.json 无 mode=scan-refresh）')
@@ -453,7 +454,7 @@ export async function finalizeRefresh(opts = {}) {
     const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
     mkdirSync(runtimeRoot, { recursive: true })
     const ts = new Date().toISOString().replace(/[-:T.]/g, '').slice(0, 14)
-    auditPath = join(runtimeRoot, `scan-refresh-${ts}.json`)
+    auditPath = runtimeStatePath(runtimeRoot, `scan-refresh-${ts}.json`)
     writeAtomicSync(auditPath, JSON.stringify({
       changeType: 'scan-refresh',
       head: headShort,

package/src/scope-audit.js

@@ -32,6 +32,7 @@
  * degraded 仓退 v1 ⊘ 形态不炸主仓表；预执行形态不调内核（跨仓行保持清单形态）。
  */
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { runtimeStatePath } from './runtime-paths.js'
 import { createHash } from 'node:crypto'
 import { join, dirname } from 'node:path'
 import { locateQuickSessionGuard, auditQuickCompletion, resolveRuntimeRoot, collectOtherQuickSessionDeclarations, ancestorSpecDirs, isQuickMetadata } from './run/shared.js'
@@ -40,6 +41,7 @@ import { loadSpanRiskPatternsAllProjects } from './span-risk-surface.js'
 import { safeGit } from './git-helper.js'
 import { parseFileChangeListDetailed, pathMatches } from './change-list.js'
 import { classifyToolScaffold, filterDeliverableFiles } from './worktree-apply.js'
+import { isToolGovernancePath } from './flow-parity.js'
 import { parseRepoRegistry } from './stages/plan-postcheck.js'
 // 跨仓 per-repo 采集共享内核（2026-09-20 scope-audit-cross-repo task-02 消费 task-01 产物）。
 // 无环确认：cross-repo-reconcile 的静态依赖链（git-helper/plan-postcheck/worktree-apply/
@@ -263,7 +265,7 @@ function readScopeSnapshot(changeDir, runtimeRoot, changeName) {
     } catch { /* 缺失/损坏 → 下一源 */ }
   }
   try {
-    const snap = JSON.parse(readFileSync(join(runtimeRoot, `scope-audit-${changeName}.json`), 'utf8'))
+    const snap = JSON.parse(readFileSync(runtimeStatePath(runtimeRoot, `scope-audit-${changeName}.json`), 'utf8'))
     if (snap && typeof snap === 'object' && Array.isArray(snap.rows)) return snap
   } catch { /* 缺失/损坏 → null */ }
   return null
@@ -859,10 +861,10 @@ async function computeFullFlowAudit({ cwd, specBase, changeName, platformOpts, c
   })() : false
   const hasSnapshotFile = hasMergedScopeAudit
     || (changeDirInfo
-      ? existsSync(join(changeDirInfo.dir, 'scope-audit.json')) || existsSync(join(runtimeRoot, `scope-audit-${changeName}.json`))
-      : existsSync(join(runtimeRoot, `scope-audit-${changeName}.json`)))
-  const hasApplyPathspec = existsSync(join(runtimeRoot, `apply-pathspec-${changeName}.txt`))
-  const hasCleanupReceipt = existsSync(join(runtimeRoot, `execute-cleanup-${changeName}.json`))
+      ? existsSync(join(changeDirInfo.dir, 'scope-audit.json')) || existsSync(runtimeStatePath(runtimeRoot, `scope-audit-${changeName}.json`))
+      : existsSync(runtimeStatePath(runtimeRoot, `scope-audit-${changeName}.json`)))
+  const hasApplyPathspec = existsSync(runtimeStatePath(runtimeRoot, `apply-pathspec-${changeName}.txt`))
+  const hasCleanupReceipt = existsSync(runtimeStatePath(runtimeRoot, `execute-cleanup-${changeName}.json`))
   let hasExecuteRunStamp = false
   if (!hasWorktreeMeta && !hasBranch && !hasAuditTag && !hasSnapshotFile && !hasApplyPathspec && !hasCleanupReceipt) {
     try {
@@ -1016,7 +1018,7 @@ async function computeFullFlowAudit({ cwd, specBase, changeName, platformOpts, c
   let narrowNote = null
   if (freshActual && collectPatch) {
     try {
-      const pathspecFile = join(runtimeRoot, `apply-pathspec-${changeName}.txt`)
+      const pathspecFile = runtimeStatePath(runtimeRoot, `apply-pathspec-${changeName}.txt`)
       const owned = readFileSync(pathspecFile, 'utf8').split('\n').map(l => toPosix(l.trim())).filter(Boolean)
       if (owned.length > 0) {
         const ownedSet = new Set(owned)
@@ -1372,7 +1374,11 @@ export function reconcileCrossRepoPlan({ cwd, specBase, runtimeRoot, changeName,
     }
     // 真实三态：该仓 actual（filterDeliverableFiles 过滤，主仓口径）× 该组声明面 pathMatches
     // 双向容差（glob/目录前缀兼容，design 清单可写 glob）→ planned / unplanned / untouched
-    const repoFiles = [...new Set(filterDeliverableFiles(repoActual.files).filter(Boolean))].map(toPosix).sort()
+    // 工具治理模板同源剔除（2026-10-19-cross-repo-face-tool-filter）：跨仓面（rows/totals/
+    // patch）与主仓冻结面同口径，不让 .claude/.codex 等注入面刷屏跨仓交付。
+    const repoFiles = [...new Set(filterDeliverableFiles(repoActual.files).filter(Boolean))]
+      .filter((f) => !isToolGovernancePath(f))
+      .map(toPosix).sort()
     const repoStats = collectNumstatByPath(repoActual.repoPath, repoFiles, { baseRef: repoActual.anchor.base })
     const repoMatched = new Set()
     for (const f of repoFiles) {

package/src/sentinel-assertions.js

@@ -207,6 +207,43 @@ export function detectTickBurst(tickLog, opts = {}) {
   };
 }
 
+/**
+ * 勾选时点判定·换源版（2026-10-17-tick-timing-source，纯函数）：task-ticks.jsonl 侧车的逐格
+ * 墙钟时戳 → 勾选是「边干边勾」还是「末尾集中」。旧判据（tasks.md git 首次提交 == 收口最后
+ * 提交）已退役——git 历史形态被官方允许的 reset --soft 压扁无声摧毁（tick-timing-squash-
+ * blindspot 坑：边干边勾的渐进提交被并行会话压扁后警告照出，结构性误报；且 tasks.md 不进
+ * 交付 pathspec 的纪律下「untracked 直至归档」恒复现）。墙钟时戳是侧车文件事实，压扁/
+ * rebase 均不可改写——与「审计真相锚 change.patch sha256、不依赖 git 形态」口径对齐。
+ * 判定序（豁免优先）：
+ *   'no-ticks'    侧车无记录（agent 全程直接 Edit）——不判（调用方给一行 task tick 教学）；
+ *   'single'      仅 1 格——单格无节奏可言；
+ *   'spread'      时戳跨度 > clusterWindowMs（缺省 120s）——天然分散，边干边勾确认
+ *                 （超窗即铁证，无需存活锚）；
+ *   'no-anchor'   lifespanMs 非有限或 ≤0（baseline 缺失）——fail-open 不判（防误报）；
+ *   'concentrated' 跨度 ≤ clusterWindowMs 且 lifespanMs ≥ ratio×max(跨度,1ms)（缺省 10）
+ *                 ——格子全挤在收口前短窗且变更活得够久，末尾集中勾选形态；
+ *   其余（挤短窗但存活比不足）→ 'spread'——快变更快勾是合法形态，不告。
+ * 输入 ticks 为 [{ts, task}]（parseTickLog 产物或同形）；行序不保证，内部按 ts 排序。
+ * 坏行（ts 非有限/≤0）静默剔除。watcher 采样事件刻意不作判据（部分观测会把分散勾选采样
+ * 成尾窗聚集，与采样合并跳系列坑同源——缺观测宁可教学不判）。
+ * @param {{ticks?:Array<{ts:number,task:string}>, lifespanMs?:number, clusterWindowMs?:number, ratio?:number}} args
+ * @returns {{status:'spread'|'concentrated'|'single'|'no-ticks'|'no-anchor', count:number, spanMs:number}}
+ */
+export function detectTickTiming({ ticks, lifespanMs, clusterWindowMs = 120_000, ratio = 10 } = {}) {
+  const list = (Array.isArray(ticks) ? ticks : [])
+    .map((r) => Number(r && r.ts))
+    .filter((ts) => Number.isFinite(ts) && ts > 0)
+    .sort((a, b) => a - b);
+  if (list.length === 0) return { status: 'no-ticks', count: 0, spanMs: 0 };
+  if (list.length === 1) return { status: 'single', count: 1, spanMs: 0 };
+  const spanMs = list[list.length - 1] - list[0];
+  if (spanMs > clusterWindowMs) return { status: 'spread', count: list.length, spanMs };
+  const life = Number(lifespanMs);
+  if (!Number.isFinite(life) || life <= 0) return { status: 'no-anchor', count: list.length, spanMs };
+  if (life >= ratio * Math.max(spanMs, 1)) return { status: 'concentrated', count: list.length, spanMs };
+  return { status: 'spread', count: list.length, spanMs };
+}
+
 /**
  * 单拍勾选门决策（2026-09-29-batch-tick-gate，纯函数）：检出单拍跳（batchTick 非 null）
  * 时的收口动作裁决。镜像豁免分支退役（2026-10-07-thin-tasks-v3——任务面统一为 agent