sillyspec 3.33.0 → 3.33.1

package/src/friction-ledger.js

@@ -31,6 +31,7 @@
  * 本模块自身不打印任何输出。
  */
 import { readFileSync, mkdirSync } from 'fs'
+import { runtimeStatePath } from './runtime-paths.js'
 import { dirname, join } from 'path'
 import { writeAtomicSync } from './fs-atomic.js'
 import { withFileLock } from './quicklog.js'
@@ -45,7 +46,7 @@ const LEDGER_CAP = 200
 const LEDGER_FILENAME = 'friction-ledger.json'
 
 function ledgerFilePath(runtimeRoot) {
-  return join(runtimeRoot, LEDGER_FILENAME)
+  return runtimeStatePath(runtimeRoot, LEDGER_FILENAME)
 }
 
 /**

package/src/friction-tally.js

@@ -24,6 +24,7 @@
  * 不打印任何输出，提示何时打印由调用方决定。
  */
 import { existsSync, mkdirSync, readFileSync, rmSync } from 'fs'
+import { runtimeStatePath } from './runtime-paths.js'
 import { dirname, join } from 'path'
 import { writeAtomicSync } from './fs-atomic.js'
 import { withFileLock } from './quicklog.js'
@@ -76,7 +77,7 @@ function frictionTallyPath({ cwd, platformOpts, changeName }) {
   if (QUICK_SESSION_ID_RE.test(changeName)) {
     return join(resolveQuickSessionsDir(platformOpts, specBase), changeName, 'friction-tally.json')
   }
-  return join(resolveRuntimeRoot(platformOpts, specBase), `friction-tally-${changeName}.json`)
+  return runtimeStatePath(resolveRuntimeRoot(platformOpts, specBase), `friction-tally-${changeName}.json`)
 }
 
 /** YAML 布尔值宽松解析：仅显式 false（含引号形态）为关，其余值一律默认开（R-05） */
@@ -174,10 +175,12 @@ export function renderFrictionHintLine(counts) {
 export async function recordFrictionEvent({ cwd, platformOpts, changeName, type, detail }) {
   try {
     if (!FRICTION_TYPES.has(type)) return null
+    // enabled=false 直通：record/consume 双 no-op，.runtime 零写入（D-003 一键全关）。
+    // 必须先于 frictionTallyPath（2026-10-18 起路径助手带 mkdir-p 目录保证，关闭态
+    // 构造路径即建 state/ 目录=破坏零写入契约）
+    if (!readFrictionHintEnabled(deriveSpecBase(cwd, platformOpts))) return null
     const tallyPath = frictionTallyPath({ cwd, platformOpts, changeName })
     if (!tallyPath) return null
-    // enabled=false 直通：record/consume 双 no-op，.runtime 零写入（D-003 一键全关）
-    if (!readFrictionHintEnabled(deriveSpecBase(cwd, platformOpts))) return null
     return await withFileLock(tallyPath + ".lock", async () => {
     const tally = readFrictionTally(tallyPath)
     const at = new Date().toISOString()
@@ -207,9 +210,10 @@ export async function recordFrictionEvent({ cwd, platformOpts, changeName, type,
  */
 export async function consumeFrictionHint({ cwd, platformOpts, changeName }) {
   try {
+    // enabled 检查先于路径构造（同 record：关闭态零写入，路径助手 mkdir-p 不触发）
+    if (!readFrictionHintEnabled(deriveSpecBase(cwd, platformOpts))) return { hint: null, counts: {} }
     const tallyPath = frictionTallyPath({ cwd, platformOpts, changeName })
     if (!tallyPath || !existsSync(tallyPath)) return { hint: null, counts: {} }
-    if (!readFrictionHintEnabled(deriveSpecBase(cwd, platformOpts))) return { hint: null, counts: {} }
     return await withFileLock(tallyPath + ".lock", async () => {
     const tally = readFrictionTally(tallyPath)
     const counts = {}

package/src/handoff.js

@@ -15,6 +15,7 @@
  *      整块 80 行帽（HANDOFF_LINE_CAP），超限从上下文段尾截，粘贴块与警示行永不动。
  */
 import { ProgressManager, resolveSpecDir } from './progress.js';
+import { runtimeStatePath } from './runtime-paths.js'
 import { MAIN_FLOW_ORDER, STAGE_LABELS } from './progress/shared.js';
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
@@ -199,7 +200,7 @@ export async function buildHandoff({ cwd, specBase, changeName } = {}) {
   // 保持不变——SESSION_ID 相同不能当硬续证据）。本命令执行即切割：best-effort 给
   // stage-session ledger 盖 handoffAt 章，墙据此放行新会话的 execute/verify 首入。
   try {
-    const ledgerPath = join(specRoot, '.runtime', `stage-session-ledger-${target}.json`);
+    const ledgerPath = runtimeStatePath(join(specRoot, '.runtime'), `stage-session-ledger-${target}.json`);
     let ledger = null;
     try { ledger = JSON.parse(readFileSync(ledgerPath, 'utf8')); } catch { /* 无账本（阶段未收口）→ 无墙可放行，零动作 */ }
     if (ledger && typeof ledger === 'object') {

package/src/hooks/worktree-guard.js

@@ -61,7 +61,7 @@ const STAGE_HINTS = {
     '你需要先启动一个任务流程才能修改源码（调用对应的 sillyspec skill）：',
     '',
     '  轻量变更/BUG修复（默认快道，skill sillyspec-flow）——--input 引号内换行合法，下例可照抄：',
-    '  sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句中文概括（首行即变更标题）；随后动机与背景',
+    '  sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句 10-30 字中文概括（首行即变更标题，硬区间 10-30 必须、建议 ~20 字）；随后动机与背景',
     '',
     '  成功标准：',
     '  - <可验证标准>"',
@@ -80,7 +80,7 @@ const STAGE_HINTS = {
   'verify': [
     '当前在 verify（验证）阶段，只做代码审查和测试验证，不修改源码。',
     '如需修改，请先回到 execute 阶段，或收口后开轻量变更（--input 引号内换行合法，可照抄）：',
-    '  sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句中文概括（首行即变更标题）；随后动机与背景',
+    '  sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句 10-30 字中文概括（首行即变更标题，硬区间 10-30 必须、建议 ~20 字）；随后动机与背景',
     '',
     '  成功标准：',
     '  - <可验证标准>"',
@@ -88,7 +88,7 @@ const STAGE_HINTS = {
   'archive': [
     '当前在 archive（归档）阶段，不修改源码。',
     '如需修改，请开启新变更（--input 引号内换行合法，可照抄）：',
-    '  sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句中文概括（首行即变更标题）；随后动机与背景',
+    '  sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句 10-30 字中文概括（首行即变更标题，硬区间 10-30 必须、建议 ~20 字）；随后动机与背景',
     '',
     '  成功标准：',
     '  - <可验证标准>"',
@@ -190,8 +190,8 @@ function getScanDocInfo(filePath) {
 
 function readScanGuard(scanDocInfo, projectRoot) {
   const candidates = [
-    path.join(scanDocInfo.specRoot, '.runtime', 'scan-guard.json'),
-    path.join(projectRoot, '.sillyspec', '.runtime', 'scan-guard.json'),
+    path.join(scanDocInfo.specRoot, '.runtime', 'state', 'scan-guard.json'),
+    path.join(projectRoot, '.sillyspec', '.runtime', 'state', 'scan-guard.json'),
   ]
   for (const p of candidates) {
     if (!existsSync(p)) continue

package/src/index.js

@@ -7,6 +7,7 @@
  * 状态管理通过 sillyspec.db（SQLite）完成，使用 `sillyspec progress` 命令。
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, unlinkSync } from 'fs';
+import { runtimeStatePath } from './runtime-paths.js'
 import { writeAtomicSync } from './fs-atomic.js';
 import { basename, dirname, extname, join, resolve, isAbsolute, sep, relative } from 'path';
 import { safeGit, git, gitQuiet } from './git-helper.js';
@@ -173,7 +174,7 @@ SillySpec CLI — 规范驱动开发工具包
 示例:
   sillyspec init
   sillyspec run brainstorm --change 2026-07-03-add-login
-  sillyspec flow start --change 2026-07-03-my-fix --input "<一句中文概括（首行即变更标题）＋动机与背景详述＋独立一行『成功标准：』＋每行一条『- 可验证标准』>"   # 轻量变更（默认快道，2 次调用；变更名须 YYYY-MM-DD-<简短描述> 日期前缀)
+  sillyspec flow start --change 2026-07-03-my-fix --input "<一句 10-30 字中文概括（首行即变更标题，硬区间 10-30 必须、建议 ~20 字）＋动机与背景详述＋独立一行『成功标准：』＋每行一条『- 可验证标准』>"   # 轻量变更（默认快道，2 次调用；变更名须 YYYY-MM-DD-<简短描述> 日期前缀)
   sillyspec run verify --done --output "验证通过，测试全绿"
   sillyspec run archive --done --confirm --output "归档完成"
   sillyspec run plan --reopen --from-step 2          # 修订 plan，从第 2 步重做
@@ -228,7 +229,7 @@ function refuseRetiredQuickFreshStart(stageArgs) {
   console.error('❌ quick 通道已退役，不再接受新会话（v3.30.0 起）。')
   // 可照抄实例（2026-10-05-input-teach-copyable）：引号内换行合法，行级 trim 容忍缩进
   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('   - <可验证标准>"')
@@ -323,6 +324,26 @@ async function main() {
     process.exit(2);
   }
 
+  // ── 旧布局迁移（2026-10-18 runtime-relayout）：per-change 散文件入 state/、可删产物入 temp/。
+  // 每次入口跑一遍（幂等：已收敛后 readdir 一轮零写入）；fail-open 绝不阻断命令。
+  // init 除外——目标仓尚无 .sillyspec 可迁。resolveEffectiveDir 是函数声明（提升后可调）。
+  if (filteredArgs[0] !== 'init') {
+    try {
+      const { migrateRuntimeLayout } = await import('./runtime-paths.js')
+      const roots = new Set()
+      const direct = join(specDir || join(targetDir, '.sillyspec'), '.runtime')
+      roots.add(direct)
+      if (!existsSync(direct)) {
+        try { roots.add(join(resolveEffectiveDir(targetDir), '.sillyspec', '.runtime')) } catch { /* cwd 无仓 = 无可迁 */ }
+      }
+      try {
+        const po = resolvePlatformOpts(targetDir)
+        if (po && po.runtimeRoot) roots.add(po.runtimeRoot)
+      } catch { /* 平台指针不可达 = 无平台侧可迁 */ }
+      for (const rt of roots) migrateRuntimeLayout(rt)
+    } catch { /* 迁移失败不阻断任何命令 */ }
+  }
+
   const command = filteredArgs[0];
   // 支持 sillyspec init /path/to/project 语法：如果第二个参数看起来像路径，当作 targetDir
   if (command === 'init' && filteredArgs[1] && !filteredArgs[1].startsWith('-')) {
@@ -5371,10 +5392,10 @@ SillySpec config — local.yaml 配置键速查
         'sillyspec.db': '进度库 SQLite（stages/steps/changes 表）',
         'sillyspec.db.bak': '进度库备份（sql.js 时代写前快照遗留，node:sqlite 不再写入，仅 _openWithFallback 向后兼容恢复用）',
         'sillyspec.db.schema-version': '进度库 schema 版本标记',
-        'doctor-diagnosis.json': 'doctor --json 结构化诊断快照',
+        'doctor-diagnosis.json': 'doctor --json 结构化诊断快照（可再生，落 temp/ 子目录）',
         'doctor-dumps': 'doctor --dump-db 取证输出目录',
         'workflow-runs': 'workflow check --save 归档目录',
-        'scan-guard.json': 'scan 覆盖保护记录',
+        'scan-guard.json': 'scan 覆盖保护记录（2026-10-18 起落 state/ 子目录）',
         'quick-sessions': 'quick 会话记录目录',
         'quick-guard.json': 'quick baseline 守卫（旧位置）',
         'worktrees': 'worktree meta（hooks 侧）',
@@ -5388,6 +5409,8 @@ SillySpec config — local.yaml 配置键速查
         'history': '历史记录目录（init 预建）',
         'logs': '日志目录（init 预建）',
         'templates': '工作流模板目录（init 预建）',
+        'state': '按 change 命名的派生状态目录（watcher 事件流/账本/冲突标记等，归档时随变更精确回收）',
+        'temp': '可随时整体删除的临时产物（日志/db 备份/锁残留 tmp——删后自动重建，无状态语义）',
       };
       let entries;
       try {
@@ -5429,7 +5452,7 @@ SillySpec config — local.yaml 配置键速查
 SillySpec pull — 拉取服务器 spec 快照到本地（X2 / FR-07）
 
 用法:
-  sillyspec pull --spec [--force]
+  sillyspec pull --spec [--force] [--restore-deleted]
 
 说明:
   从 SillyHub 平台拉取当前工作区的 .sillyspec 整树快照（tar 解压到 specDir，
@@ -5444,6 +5467,10 @@ SillySpec pull — 拉取服务器 spec 快照到本地（X2 / FR-07）
      本命令不自动同步、不在会话中自动刷新；拉取后本地的改动仍需正常推送。
      daemon 模式下任务/会话开始时会按 spec_version 自动取新，无需手动跑本命令。
 
+  防复活抑制（默认开启）：本地已删除、但删除尚未同步到服务器的文件（基线快照有、
+     盘面无），不会从快照写回本地（防「同步失败窗口内删除的任务卡被服务器旧文件复活」）；
+     确要从快照恢复这类文件用 --restore-deleted（纯快照回放语义）。
+
   拉取进度六表（多机进度同步）请用：sillyspec platform pull [--change <name>]
 `);
       if (pullWantsHelp || !pullWantsSpec) {
@@ -5456,6 +5483,10 @@ SillySpec pull — 拉取服务器 spec 快照到本地（X2 / FR-07）
       }
 
       const pullSpecForce = pullSpecArgs.includes('--force');
+      // 防复活抑制（坑 spec-tree-file-resurrect）的显式恢复通道：默认把「基线有、盘面无」的
+      // 本地已删文件挡在快照回放外（删除 op 未上行成功时不被服务器旧文件复活）；
+      // --restore-deleted = 用户显式意志优先，恢复纯快照回放语义。
+      const pullSpecRestoreDeleted = pullSpecArgs.includes('--restore-deleted');
       const syncModule = await import('./sync.js');
       // 未连接明确提示不崩（对齐 platform pull :2289 先例）
       const smForSpecPull = new syncModule.SyncManager(dir);
@@ -5463,10 +5494,13 @@ SillySpec pull — 拉取服务器 spec 快照到本地（X2 / FR-07）
         console.error('❌ 未连接平台，请先 sillyspec platform connect');
         process.exit(1);
       }
-      const specR = await syncModule.pullSpecBundle(dir, { force: pullSpecForce, specDir });
+      const specR = await syncModule.pullSpecBundle(dir, { force: pullSpecForce, specDir, restoreDeleted: pullSpecRestoreDeleted });
       if (specR.ok && specR.pulled) {
         console.log(`✅ 已拉取 spec 快照 → ${specR.specDir}${specR.specVersion ? `（平台 spec_version: ${specR.specVersion}）` : ''}`);
         console.log('   快照语义：打包时刻快照非实时，无自动同步；本地后续改动仍需正常推送。');
+        if (Array.isArray(specR.resurrectSkipped) && specR.resurrectSkipped.length > 0) {
+          console.log('   防复活抑制已生效：本地已删除文件未从快照恢复（基线有、盘面无=本地删除尚未上行成功，抑制防被服务器旧文件复活）；确要从快照恢复用 --restore-deleted。');
+        }
       } else if (/非空/.test(specR.reason || '')) {
         console.error(`❌ ${specR.reason}`);
         console.error('   确认整树替换请加 --force（先删除本地 .sillyspec 整树再解包，进度 DB 等本地文件一并丢失；连接凭据 local.yaml 保留，无需重新 connect）');
@@ -5529,7 +5563,7 @@ SillySpec pull — 拉取服务器 spec 快照到本地（X2 / FR-07）
         }
         if (!tRes.exists) {
           console.error(`📭 ${tChange} 无事件流（未跑过 watcher），无从合成时间线`);
-          console.error(`   事件流路径：${join(tRuntimeRoot, `watcher-events-${tChange}.jsonl`)}；活跃变更跑任意 flow/run 命令会拉起 watcher`);
+          console.error(`   事件流路径：${runtimeStatePath(tRuntimeRoot, `watcher-events-${tChange}.jsonl`)}；活跃变更跑任意 flow/run 命令会拉起 watcher`);
           process.exit(2);
         }
         const { changeDir, tasksMd, tickLog } = loadChangeTasks(tSpecBase, tChange);

package/src/knowledge-hits.js

@@ -12,12 +12,13 @@
  */
 
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'fs'
+import { runtimeStatePath } from './runtime-paths.js'
 import { join } from 'path'
 
 const HITS_FILENAME = 'knowledge-hits.jsonl'
 
 function hitsFilePath(runtimeDir) {
-  return join(runtimeDir, HITS_FILENAME)
+  return runtimeStatePath(runtimeDir, HITS_FILENAME)
 }
 
 /**

package/src/knowledge-vector.js

@@ -35,6 +35,7 @@
  * 404 另有进程级死信短路（端点死信不再空转探测）。
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { runtimeStatePath } from './runtime-paths.js'
 import { join, dirname } from 'path'
 import { readPlatformConfig } from './sync.js'
 import { matchByRouting, fallbackByQueryShingles, parseDecisionEntries } from './knowledge-match.js'
@@ -49,7 +50,7 @@ const CAPABILITY_RETRY_MS = 60 * 60 * 1000
 // 机器态的标准落点（knowledge-hits 同款）。写盘全 fail-soft；按平台 URL 匹配（换平台即失效）。
 
 function capabilityCachePath(cwd) {
-  return join(cwd, '.sillyspec', '.runtime', 'vector-capability.json')
+  return runtimeStatePath(join(cwd, '.sillyspec', '.runtime'), 'vector-capability.json')
 }
 
 function readCapabilityCache(cwd) {

package/src/progress/consistency-doctor.js

@@ -1,7 +1,9 @@
 // W6 Step9a: Revision v1 状态一致性检查 + 修复 + --force 审计日志。
 // 从 src/progress.js 单体 ProgressManager 抽出。持有 pm 引用（构造注入），调 pm.read / pm._write /
 // pm._ensureRuntimeDir / pm._runtimePath（persistence-core 留 facade 本体）。
-import { appendFileSync, existsSync, readFileSync, readdirSync } from 'fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'fs';
+import { dirname } from 'path';
+import { RUNTIME_TEMP_DIRNAME } from '../runtime-paths.js'
 import { join, resolve } from 'path';
 import { DB } from '../db.js';
 import { openDatabase } from '../db-engine.js';
@@ -122,8 +124,9 @@ export class ConsistencyDoctor {
   _appendAuditLog(cwd, entry) {
     try {
       this.pm._ensureRuntimeDir(cwd);
-      const auditPath = this.pm._runtimePath(cwd, 'audit.log');
+      const auditPath = this.pm._runtimePath(cwd, RUNTIME_TEMP_DIRNAME, 'audit.log');
       const line = JSON.stringify({ at: new Date().toISOString(), ...entry });
+      try { mkdirSync(dirname(auditPath), { recursive: true }); } catch { /* fail-open */ }
       appendFileSync(auditPath, line + '\n');
     } catch (e) {
       console.warn(`⚠️  审计日志写入失败: ${e.message}`);

package/src/progress/stage-machine.js

@@ -361,8 +361,12 @@ export class StageMachine {
   /** 未决同步冲突列表（overview 数据源；与 sync.js listConflictFiles 同前缀同字段，fs-only） */
   _listPendingConflicts(specDir) {
     const runtimeDir = join(specDir, '.runtime');
+    // 2026-10-18 布局分层：冲突文件落 state/；根目录扫描保留旧布局兜底
     let files = [];
-    try { files = readdirSync(runtimeDir); } catch { return []; }
+    for (const dir of [join(runtimeDir, 'state'), runtimeDir]) {
+      try { files.push(...readdirSync(dir)); } catch { /* 可选层缺失跳过 */ }
+    }
+    const fileDir = (f) => (existsSync(join(runtimeDir, 'state', f)) ? join(runtimeDir, 'state') : runtimeDir)
     const conflicts = [];
     for (const f of files) {
       const isProgress = f.startsWith('sync-conflict-');
@@ -371,7 +375,7 @@ export class StageMachine {
       let createdAt = null;
       let kind = null;
       try {
-        const cf = JSON.parse(readFileSync(join(runtimeDir, f), 'utf8'));
+        const cf = JSON.parse(readFileSync(join(fileDir(f), f), 'utf8'));
         change = cf.change || change;
         createdAt = cf.created_at || null;
         kind = typeof cf.kind === 'string' ? cf.kind : null;

package/src/progress.js

@@ -11,6 +11,7 @@
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, appendFileSync, copyFileSync, readdirSync, statSync, realpathSync } from 'fs';
+import { RUNTIME_TEMP_DIRNAME, runtimeTempPath } from './runtime-paths.js'
 import { join, basename, dirname, resolve, sep } from 'path';
 import { tmpdir, hostname } from 'os';
 import { writeAtomicSync } from './fs-atomic.js';
@@ -122,7 +123,7 @@ export function resolveSessionIdentity({ flagSession = null, quickChangeName = n
       try {
         const markerDir = join(cwd, SPEC_DIR_NAME, RUNTIME_SUBDIR);
         mkdirSync(markerDir, { recursive: true });
-        const markerPath = join(markerDir, ANON_SESSION_WARN_MARKER);
+        const markerPath = runtimeTempPath(markerDir, ANON_SESSION_WARN_MARKER);
         const now = Date.now();
         try {
           const m = JSON.parse(readFileSync(markerPath, 'utf8'));
@@ -348,7 +349,7 @@ export class ProgressManager {
     const runtimeDir = this._runtimePath(cwd);
     if (!existsSync(runtimeDir)) {
       mkdirSync(runtimeDir, { recursive: true });
-      for (const d of ['artifacts', 'history', 'logs', 'templates']) {
+      for (const d of ['artifacts', 'history', 'logs', 'templates', 'state', 'temp']) {
         mkdirSync(join(runtimeDir, d), { recursive: true });
       }
     }
@@ -746,7 +747,8 @@ export class ProgressManager {
       throw new Error(`本地进度库不存在，无法 import：${dbPath}`);
     }
     const bakTs = new Date().toISOString().replace(/[:.]/g, '-');
-    const bakPath = this._runtimePath(cwd, `sillyspec.db.pre-import-${bakTs}.bak`);
+    const bakPath = this._runtimePath(cwd, RUNTIME_TEMP_DIRNAME, `sillyspec.db.pre-import-${bakTs}.bak`);
+    try { mkdirSync(dirname(bakPath), { recursive: true }); } catch { /* import 主流程 fail-open */ }
     // 体检 BUG-18：WAL 模式下最近已提交事务可能仍在 -wal 侧车，直接 copy 主库文件会拿到
     // 缺尾部提交的快照（恢复时静默回退进度）。先尽力 checkpoint(TRUNCATE) 把 WAL 合并回主库；
     // 他进程持连接致 checkpoint 不完全时，把 -wal 侧车一并备份，恢复侧才有完整提交
@@ -880,17 +882,25 @@ export class ProgressManager {
     let keep = Number(process.env.SILLYSPEC_PREIMPORT_BAK_KEEP);
     if (!Number.isInteger(keep) || keep < 1) keep = PRE_IMPORT_BAK_KEEP_DEFAULT;
 
-    const runtimeDir = this._runtimePath(cwd);
-    const baks = readdirSync(runtimeDir).filter(f => PRE_IMPORT_BAK_RE.test(f)).sort();
+    // 快照 2026-10-18 起落 temp/；根目录扫描保留旧布局兜底（迁移幂等收敛后清零）。
+    // 契约：根 runtime 目录缺失仍如实抛 ENOENT（fail-loud 不静默假成功）；temp/ 是可选
+    // 层（迁移前不存在），缺失按空集处理。
+    const rootDir = this._runtimePath(cwd)
+    const scanDirs = [this._runtimePath(cwd, RUNTIME_TEMP_DIRNAME), rootDir]
+    const baks = [...new Set([
+      ...(() => { try { return readdirSync(scanDirs[0]) } catch { return [] } })(),
+      ...readdirSync(rootDir),
+    ])].filter(f => PRE_IMPORT_BAK_RE.test(f)).sort();
     const keepName = keepPath ? basename(keepPath) : null;
     const doomed = baks.slice(0, Math.max(0, baks.length - keep)).filter(f => f !== keepName);
 
     let removed = 0;
     for (const f of doomed) {
       // 单份删除失败（他进程持句柄 / 权限）不连坐其余份：跳过即可，下次 import 再收。
-      try { unlinkSync(join(runtimeDir, f)); } catch { continue; }
+      const fDir = scanDirs.find(d => { try { return existsSync(join(d, f)) } catch { return false } }) || scanDirs[0]
+      try { unlinkSync(join(fDir, f)); } catch { continue; }
       removed++;
-      const wal = join(runtimeDir, `${f}-wal`);
+      const wal = join(fDir, `${f}-wal`);
       if (existsSync(wal)) {
         try { unlinkSync(wal); } catch { /* 侧车残留无害：不参与恢复链，下次裁剪再收 */ }
       }
@@ -937,7 +947,8 @@ export class ProgressManager {
   _maybeSnapshotBak(cwd) {
     try {
       const dbPath = this._runtimePath(cwd, 'sillyspec.db');
-      const bakPath = dbPath + '.bak';
+      // 2026-10-18 布局分层：可删备份归 temp/（db.js _openWithFallback 双路径回读）
+      const bakPath = runtimeTempPath(dirname(dbPath), 'sillyspec.db.bak');
       const st = existsSync(bakPath) ? statSync(bakPath) : null;
       if (st && Date.now() - st.mtimeMs < ProgressManager.SNAPSHOT_INTERVAL_MS) return;
       const tmpPath = bakPath + '.tmp';

package/src/quicklog.js

@@ -118,18 +118,74 @@ export function sanitizeDesc(description) {
   return s.length > 120 ? s.slice(0, 120) + '…' : s
 }
 
+// ── 短标题提炼（2026-10-16-short-change-title，变更中心标题治理·工具侧）──
+
+// 提炼参数：目标 20 字 / 上限 30 字 / 截点下限 6 字（更短的截点宁可不切——残词标题比
+// 硬切长句更难读，如「修复，…」切出「修复」）。平台侧回填脚本须与此处口径对齐。
+const SHORT_TITLE_DEFAULTS = Object.freeze({ target: 20, max: 30, floor: 6 })
+// 全角/语义截点：无条件可切。ASCII 标点仅在后随空白/CJK/串尾时才算截点（防 3.5 / 1,000 /
+// e.g. 误切——小数点后随数字是最常见误切源，rpc-budget 标题实证）。
+const SHORT_TITLE_CJK_CUT = new Set([...'。！？；：、，…—～·'])
+const SHORT_TITLE_ASCII_CUT = new Set([...'.,;:!?'])
+const SHORT_TITLE_CJK_RE = /[\u3400-\u4dbf\u4e00-\u9fff]/
+// 截断后尾部清理：剥句读尾标点（引号括号不入此集——「xxx」收尾是平衡结构不能剥）；
+// 再剥截点切进引号体时留下的悬空开口引号/括号。
+const SHORT_TITLE_TRAIL_RE = /[\s。．.!！?？；;：:，,、…—~～·]+$/u
+const SHORT_TITLE_DANGLING_RE = /[「『（《"']+$/u
+
 /**
- * 变更标题推导（用户需求 2026-09-29：changes.title 应为中文描述，≤50 字、建议 ~20 字）。
- * 取 --input 首个非空行（「成功标准：」引导行即止——那是验收面不是标题素材），剥
- * 「需求：/动机：」类标签前缀，空白折叠单行，超长截断加 …；空输入返回 ''（调用方兜底
- * change 名）。agent 在 --input 首行写一句中文概括即成标题（flow start 横幅有指引），
- * --title 显式覆盖一切推导。
+ * 短标题提炼（2026-10-16-short-change-title）。病根：deriveChangeTitle 旧口径对超长首行
+ * 50 字硬切加 …（残句难读），纯靠 agent 自觉写短首行（本地 20 条实证 7 条变更名兜底 +
+ * 8 条硬切残句）。提炼口径：超 max 长句在自然标点处截断——截点取「距 target 最近、
+ * 落在 [floor, max] 区间」者（同距取更短），截后剥尾部标点；无可用截点才硬切
+ * slice(0,max)+'…' 并标 hardCut=true（调用方可据此打 --title 软提示）。
+ * 返回 { title, hardCut }；空输入 { title:'', hardCut:false }。
+ */
+export function distillShortTitleEx(raw, opts = {}) {
+  const { target, max, floor } = { ...SHORT_TITLE_DEFAULTS, ...opts }
+  const s = String(raw || '').replace(/\s+/g, ' ').trim()
+  if (!s) return { title: '', hardCut: false }
+  if (s.length <= max) {
+    return { title: s.replace(SHORT_TITLE_TRAIL_RE, ''), hardCut: false }
+  }
+  // 截点收集：候选标题=标点前缀（去重后按距 target 最近择优）
+  const seen = new Set()
+  const cands = []
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i]
+    let cut = SHORT_TITLE_CJK_CUT.has(ch)
+    if (!cut && SHORT_TITLE_ASCII_CUT.has(ch)) {
+      const nx = s[i + 1]
+      cut = nx === undefined || /\s/.test(nx) || SHORT_TITLE_CJK_RE.test(nx)
+    }
+    if (!cut) continue
+    const t = s.slice(0, i).replace(SHORT_TITLE_TRAIL_RE, '').replace(SHORT_TITLE_DANGLING_RE, '').trim()
+    if (t && !seen.has(t)) { seen.add(t); cands.push(t) }
+  }
+  const valid = cands.filter((t) => t.length >= floor && t.length <= max)
+  if (valid.length > 0) {
+    valid.sort((a, b) => (Math.abs(a.length - target) - Math.abs(b.length - target)) || (a.length - b.length))
+    return { title: valid[0], hardCut: false }
+  }
+  return { title: s.slice(0, max) + '…', hardCut: true }
+}
+
+/** distillShortTitleEx 的字符串简版（不需要 hardCut 观测的调用方）。 */
+export function distillShortTitle(raw, opts) {
+  return distillShortTitleEx(raw, opts).title
+}
+
+/**
+ * 变更标题首行提取（不截断）：取 --input 首个非空行（「成功标准：」引导行即止——那是验收
+ * 面不是标题素材），剥「需求：/动机：」类标签前缀，空白折叠单行。截断口径由此分治：
+ * deriveChangeTitle（≤50 硬切，模块摘要用）与 deriveShortChangeTitle（≤30 提炼，标题面用）
+ * 共享本提取，两个口径互不牵连。空输入返回 ''（调用方兜底变更名）。
  * 段头行防御（2026-10-15-title-label-skip）：过门格式示例曾被读成段头形态——agent 把
  * 「动机与背景：」独立成行照抄，白名单无复合词致整行成标题（进度库 6 变更实证）。两道
  * 防御：白名单补复合词（动机与背景/背景与动机）；任意短段头行（≤12 字非冒号内容+行尾
  * 冒号，如「变更背景：」「详细说明：」）整行跳过取次非空行——冒号后无内容不成标题。
  */
-export function deriveChangeTitle(input, max = 50) {
+function deriveChangeTitleRaw(input) {
   for (const l of String(input || '').replace(/\r\n/g, '\n').split('\n')) {
     const t = l.trim()
     if (!t) continue
@@ -137,12 +193,105 @@ export function deriveChangeTitle(input, max = 50) {
     if (/^[^:：]{1,12}[:：]$/.test(t)) continue
     const stripped = t.replace(/^(?:需求|动机|背景|任务|标题|动机与背景|背景与动机)\s*[:：]\s*/, '').trim()
     if (!stripped) continue
-    const one = stripped.replace(/\s+/g, ' ')
-    return one.length > max ? one.slice(0, max) + '…' : one
+    return stripped.replace(/\s+/g, ' ')
   }
   return ''
 }
 
+/**
+ * 变更标题推导（用户需求 2026-09-29：changes.title 应为中文描述，≤50 字、建议 ~20 字）。
+ * --title 显式覆盖一切推导。agent 在 --input 首行写一句中文概括即成标题（flow start 横幅
+ * 有指引）。**2026-10-16-short-change-title 起标题面改走 deriveShortChangeTitle 提炼口径
+ * （目标 20/上限 30，50 字硬切残句实证淘汰）**；本函数 ≤50 硬切口径保持不变——
+ * motiveFromInput 模块变更索引摘要与其同源（flow-parity），勿在此改截断行为。
+ */
+export function deriveChangeTitle(input, max = 50) {
+  const one = deriveChangeTitleRaw(input)
+  if (!one) return ''
+  return one.length > max ? one.slice(0, max) + '…' : one
+}
+
+/**
+ * 变更标题推导·提炼口径（2026-10-16-short-change-title）：deriveChangeTitleRaw 提取首行后
+ * 过 distillShortTitle——目标 20 字上限 30 字、自然标点截断、无截点才硬切。changes.title
+ * 落库面统一入口（flow start/resume/adopt、run initChange）；--title 显式值由调用方直传，
+ * 不经本函数（用户原话不做二次加工）。
+ */
+export function deriveShortChangeTitleEx(input, opts) {
+  const raw = deriveChangeTitleRaw(input)
+  if (!raw) return { title: '', hardCut: false }
+  return distillShortTitleEx(raw, opts)
+}
+
+export function deriveShortChangeTitle(input, opts) {
+  return deriveShortChangeTitleEx(input, opts).title
+}
+
+// ── 标题硬区间门（2026-10-16-title-range-gate，用户硬性要求：10-30 字必须、建议 ~20、可强制命名）──
+
+/** 标题是否落在硬区间（去首尾空白后按字符数计 10..30）。变更名兜底/短句/超长均 false。 */
+export function isValidChangeTitle(title) {
+  const n = [...String(title || '').trim()].length
+  return n >= 10 && n <= 30
+}
+
+/**
+ * fresh 启动标题解析：--title 显式 > --input 首行提炼 > 变更名兜底。
+ * enforce=true（agent 命名时刻，flow start fresh 非平台 writer）：不在区间/兜底 → ok=false，
+ * 调用方必须在任何状态写入前拒绝启动（强制 agent 命名）。
+ * enforce=false（平台 writer 预建空目录自动派发，无 agent 对话面可强制）：恒 ok=true，
+ * 超界/兜底由调用方 ⚠️ 留痕（best-effort 标题优于阻断派发）。
+ */
+export function resolveStartTitle({ titleFlag, input, change, enforce = true }) {
+  if (titleFlag) {
+    return { title: titleFlag, ok: !enforce || isValidChangeTitle(titleFlag), kind: 'flag', hardCut: false }
+  }
+  const derived = deriveShortChangeTitleEx(input)
+  // enforce 下 hardCut（30 字+… 残句）与超区间同样拒绝：残句正是「让人认不出变更做什么」
+  // 的形态，CLI 提炼救不了就让 agent 自己命名（补标点/写短句/--title 三选一）。
+  // enforce=false（平台豁免）任何非空提炼值照用，超界/残句由调用方 ⚠️ 留痕。
+  if (derived.title && (!enforce || (!derived.hardCut && isValidChangeTitle(derived.title)))) {
+    return { title: derived.title, ok: true, kind: 'derived', hardCut: false }
+  }
+  return {
+    title: change,
+    ok: !enforce,
+    kind: 'fallback',
+    hardCut: Boolean(derived && derived.hardCut),
+    rejectedTitle: (derived && derived.title) || null,
+  }
+}
+
+/** hardCut 软提示（fresh/resume 共用单源）。文案口径=「6..30 字内无可用截点」——hardCut 判定
+ * 是候选截点经 [floor,max] 过滤后为空（标点存在但全在区间外也硬切），禁用「无自然断点」旧
+ * 措辞（2026-10-16-short-change-title 评审 P3 清偿）。 */
+export const SHORT_TITLE_HARDCUT_HINT = '💡 标题超 30 字且 6..30 字内无可用自然标点截点，已硬切——重入 flow start --title "<10-30 字中文概括>" 可给更短标题（不阻断）'
+
+/** 超界不阻断面的强提示行（adopt 收编/resume 补写/平台 writer 豁免共用单源）。 */
+export function shortTitleRangeWarnLine(title) {
+  const n = [...String(title || '').trim()].length
+  return `⚠️ 标题「${title}」${n} 字不在 10-30 硬区间（建议 ~20 字）——重入 flow start --title "<10-30 字中文概括>" 可改（不阻断）`
+}
+
+/** 硬门拒绝报错（flow start fresh exit 2 用）。状态/原因/修复一次给全（cli-copy-selfsufficient）。 */
+export function shortTitleRejectMessage(title) {
+  const fix = [
+    '   ① 重跑时把 --input 首行写成一句 10-30 字中文概括（首行即变更标题）',
+    '   ② 或追加参数 --title "<10-30 字中文概括>"',
+  ]
+  if (title == null || title === '') {
+    return [
+      '❌ 变更标题未命名——flow start 全新启动必须带 10-30 字标题（必须，建议 ~20 字）：标题是变更中心展示面，须让人一眼认出本变更做什么。两条修复：',
+      ...fix,
+    ].join('\n')
+  }
+  const n = [...String(title).trim()].length
+  return [
+    `❌ 变更标题必须为 10-30 字（当前：${JSON.stringify(title)}，${n} 字；必须，建议 ~20 字）——标题是变更中心展示面，须让人一眼认出本变更做什么。两条修复：`,
+    ...fix,
+  ].join('\n')
+}
+
 
 // ── 平台推送（best-effort，2026-08-16-change-center-quick-tab task-06 / D-003）──
 
@@ -337,6 +486,10 @@ function sanitizeQuicklogUser(user) {
 // 从关联变更的 proposal/design 提取首个 # 标题（去「提案书（Proposal）— / 设计文档（Design）—」固定前缀）。
 // 让 quick --linked-changes 启动时（用户常不带 --input）也能拿到语义标题，而非 (quick 任务) 占位。
 // 读不到任何标题返回 ''（调用方再回退占位符，保持向后兼容）。
+// 2026-10-16-short-change-title：① 返回前过提炼封顶 ≤30 字（超长 dash-desc 不直落标题）；
+// ② 两文档皆无语义标题（纯模板 H1，brainstorm 模板正文即「# 提案书（Proposal）」形态）时
+// 回退读 proposal「## 动机」节首行过提炼——动机首句本是一句概括素材，旧口径放弃致标题
+// 恒变更名兜底（平台变更中心 7/20 实证）。无动机节/无内容行仍返回 ''（空串不刷新契约不变）。
 export function deriveTitleFromLinkedChange(specBase, change) {
   if (!change) return ''
   for (const f of ['proposal.md', 'design.md']) {
@@ -355,7 +508,39 @@ export function deriveTitleFromLinkedChange(specBase, change) {
     if (!raw) continue
     const dash = raw.match(/[—-]\s*(.+)$/)
     const title = dash ? dash[1].trim() : raw
-    if (title) return title
+    if (title) return distillShortTitle(title)
+  }
+  const motive = extractMotivationFirstLine(specBase, change)
+  return motive ? distillShortTitle(motive) : ''
+}
+
+// proposal「## 动机」节首个内容行（动机回退素材，2026-10-16-short-change-title）。
+// 节标题形态对齐 stage-templates（## 动机）与 flow-draft SECTION_HEAD_RE：2-6 级标题行含
+// 「动机」即命中（H1 本身是标题不参与）。内容行跳过空行/表格分隔行/HTML 注释（AGENT 槽）/
+// 模板占位行（「为什么做、解决什么核心问题」），剥 markdown bullet 与「任务原话转写：」
+// 前缀（flow-draft 机器稿动机段固定前缀，剥后即 input 首行，与 deriveShortChangeTitle 同源）。
+// 读不到文件/无节/无合格内容行返回 ''。
+function extractMotivationFirstLine(specBase, change) {
+  let content
+  try { content = readFileSync(join(specBase, 'changes', change, 'proposal.md'), 'utf8') } catch { return '' }
+  let inMotivation = false
+  for (const line of String(content).replace(/\r\n/g, '\n').split('\n')) {
+    const t = line.trim()
+    if (/^#{2,6}\s/.test(t)) {
+      if (inMotivation) return '' // 动机节内直到下一节标题都无合格内容行
+      inMotivation = /^#{2,6}\s*(?:\d+(?:[.、)]\s*)?)?[^\n]*动机/.test(t)
+      continue
+    }
+    if (!inMotivation || !t) continue
+    if (/^[\s|:-]+$/.test(t)) continue // 表格分隔/装饰行
+    if (/^<!--/.test(t)) continue // AGENT 槽等 HTML 注释
+    const stripped = t
+      .replace(/^(?:[-*+]|\d+[.、)])\s+/, '')
+      .replace(/^>\s*/, '')
+      .replace(/^任务原话转写[:：]\s*/, '')
+      .trim()
+    if (!stripped || stripped === '（未提供 --input）' || stripped === '为什么做、解决什么核心问题') continue
+    return stripped
   }
   return ''
 }