sillyspec 3.33.0 → 3.33.2

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('-')) {
@@ -373,25 +394,32 @@ async function main() {
     process.exit(1);
   }
 
-  // ── worktree cwd 硬拦（坑 worktree-cwd-silent-split，2026-08-29 用户实证）──
-  // Bash cwd 残留让 agent 两次误在 worktree 内跑 sillyspec：status 类完全静默、进度写进
-  // worktree 副本 .sillyspec 与主仓进度库分裂。守卫在命令分发前拦截，--dir 显式指向主仓
-  // 或 --allow-worktree-cwd 逃生门放行；wt-commit 命令豁免（子代理 workdir=worktree 内合法）。
+  // ── worktree cwd 锚定（坑 worktree-cwd-silent-split 硬拦 → 坑 cli-cwd-coupling 拦→导，
+  // 2026-10-20-cli-worktree-cwd-anchor）──
+  // Bash cwd 残留让 agent 误在 worktree 内跑 sillyspec（生产实证会话 47e2ff1a 三次被拦、每次
+  // 1-2 个交互来回）。守卫建议的事（cd 回主仓根重跑）自动做掉：⚠️警告 + 重锚定主仓根执行——
+  // 写入恒落主仓（单源不变量延续，worktree 副本零 CLI 写入）；刻意以本 worktree 作独立实例跑
+  // 的显式路径（--allow-worktree-cwd --spec-dir）在警告中原样保留；wt-commit 豁免不变。
   if (!args.includes('--allow-worktree-cwd') && command !== 'wt-commit') {
     const guardDir = args.includes('--dir') ? dir : process.cwd();
     const wtInfo = detectCwdInsideWorktree(guardDir);
     if (wtInfo) {
-      console.error(`\n❌ 当前在隔离 worktree 内（${wtInfo.changeName}）：${guardDir}`);
-      console.error(`   主仓根：${wtInfo.mainRepoRoot}`);
-      console.error('   SillySpec 进度库只存在于主仓，worktree 内跑会产生分裂进度（坑 worktree-cwd-silent-split）。');
-      console.error('   修复：cd 到主仓根后重跑，或用 --dir <主仓根>，或用 --allow-worktree-cwd 强制放行。');
-      // 一键放行整行（R4-S-Q 实证：agent 试 3 次才拼对组合——worktree 守卫要 --allow-worktree-cwd，
-      // 而 worktree 嵌套在主仓 .sillyspec/.runtime/ 下又触发 monorepo 多实例拦，需再补 --spec-dir
-      // 指向 worktree 自己的 .sillyspec，两 flag 缺一不可。给整行可贴命令，不再让调用方试错拼装。）
       const wtSpecDir = (ancestorSpecDirs(guardDir)[0]) || join(guardDir, '.sillyspec');
-      console.error(`   一键放行（本 worktree 作独立实例跑，整行照贴）：`);
-      console.error(`   sillyspec ${args.join(' ')} --allow-worktree-cwd --spec-dir "${wtSpecDir}"`);
-      process.exit(2);
+      console.warn(`\n⚠️ cwd 在隔离 worktree 内（${wtInfo.changeName}）：${guardDir}`);
+      console.warn(`   已自动锚定主仓根执行：${wtInfo.mainRepoRoot}（进度库/变更状态以主仓单源为准——坑 worktree-cwd-silent-split / cli-cwd-coupling 拦→导）。`);
+      console.warn(`   如确需以本 worktree 作独立实例跑（整行照贴）：`);
+      console.warn(`   sillyspec ${args.join(' ')} --allow-worktree-cwd --spec-dir "${wtSpecDir}"`);
+      dir = wtInfo.mainRepoRoot;
+      // 评审 P2 清偿：显式 --spec-dir 指进同一 worktree（无逃生 flag）时一并锚定——否则警告
+      // 「已锚定主仓根」半真，写入仍可落 worktree 副本 .sillyspec（旧硬拦对该组合是全拦的，
+      // 锚定语义必须覆盖同款面）；刻意独立实例跑走 --allow-worktree-cwd（跳过整个守卫）。
+      if (specDir) {
+        const sdInfo = detectCwdInsideWorktree(specDir);
+        if (sdInfo && sdInfo.worktreeRoot === wtInfo.worktreeRoot) {
+          console.warn(`   ⚠️ --spec-dir 指向同一 worktree（${specDir}）——已一并锚定主仓 spec 根。`);
+          specDir = join(wtInfo.mainRepoRoot, '.sillyspec');
+        }
+      }
     }
   }
 
@@ -5371,10 +5399,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 +5416,8 @@ SillySpec config — local.yaml 配置键速查
         'history': '历史记录目录（init 预建）',
         'logs': '日志目录（init 预建）',
         'templates': '工作流模板目录（init 预建）',
+        'state': '按 change 命名的派生状态目录（watcher 事件流/账本/冲突标记等，归档时随变更精确回收）',
+        'temp': '可随时整体删除的临时产物（日志/db 备份/锁残留 tmp——删后自动重建，无状态语义）',
       };
       let entries;
       try {
@@ -5429,7 +5459,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 +5474,10 @@ SillySpec pull — 拉取服务器 spec 快照到本地（X2 / FR-07）
      本命令不自动同步、不在会话中自动刷新；拉取后本地的改动仍需正常推送。
      daemon 模式下任务/会话开始时会按 spec_version 自动取新，无需手动跑本命令。
 
+  防复活抑制（默认开启）：本地已删除、但删除尚未同步到服务器的文件（基线快照有、
+     盘面无），不会从快照写回本地（防「同步失败窗口内删除的任务卡被服务器旧文件复活」）；
+     确要从快照恢复这类文件用 --restore-deleted（纯快照回放语义）。
+
   拉取进度六表（多机进度同步）请用：sillyspec platform pull [--change <name>]
 `);
       if (pullWantsHelp || !pullWantsSpec) {
@@ -5456,6 +5490,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 +5501,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 +5570,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/init.js

@@ -85,18 +85,8 @@ const TOOL_LABELS = {
   cursor: 'Cursor',
   openclaw: 'OpenClaw',
   codex: 'OpenAI Codex (通过 AGENTS.md)',
-  gemini: 'Gemini CLI (通过 GEMINI.md)',
-  opencode: 'OpenCode (通过 INSTRUCTIONS.md)',
-};
-
-// 指令文件工具（gemini/opencode）。codex/claude/zcode 共用 AGENTS.md（跨工具通用标准内容源）；
-// gemini/opencode 写各自指令文件，内容与 AGENTS.md 同源同全文（改 @AGENTS.md 指针需先验证
-// 两家对 @ 导入语法的支持，留待后续变更）。
-const INSTRUCTION_TOOLS = ['gemini', 'opencode'];
-
-const INSTRUCTION_FILE_MAP = {
-  gemini: 'GEMINI.md',
-  opencode: 'INSTRUCTIONS.md',
+  gemini: 'Gemini CLI',
+  opencode: 'OpenCode',
 };
 
 // ── 注入指令文件（全量方案，2026-10-10-init-full-injection：完整模板是唯一注入源）──
@@ -145,7 +135,7 @@ function stripLegacySmallBlock(content) {
 
 /**
  * 向指引文件注入完整模板（版本感知幂等，三态四分支 + 旧标记迁移）。
- * AGENTS.md / GEMINI.md / INSTRUCTIONS.md 共用；完整模板（templates/agents-instruction.md）
+ * AGENTS.md 专用（GEMINI.md/INSTRUCTIONS.md 专属注入面 2026-10-19 下线）；完整模板（templates/agents-instruction.md）
  * 是唯一注入源。取代 design: 2026-08-02-init-claude-md 的 CLAUDE.md 单文件方案与
  * v≤3.32.3 的追加态小段方案（其 D-004 预留的「marker 方案迁移」即彼方案）。
  * - 不存在：写完整模板 + 顶部版本注释
@@ -210,12 +200,6 @@ export function injectAgentsInstructions(projectDir) {
   injectFullInstructions(join(projectDir, 'AGENTS.md'));
 }
 
-export function injectInstructions(tool, projectDir) {
-  const fileName = INSTRUCTION_FILE_MAP[tool];
-  if (!fileName) return;
-  injectFullInstructions(join(projectDir, fileName));
-}
-
 /**
  * 为 Claude Code 写 CLAUDE.md 指针（@AGENTS.md 导入，薄文件）。
  * - 不存在：写指针文件（版本头注释 + @AGENTS.md）
@@ -438,17 +422,10 @@ async function doInstall(projectDir, tools, subprojects = [], specDir = null, op
     }
   }
 
-  // 注入指令文件（gemini/opencode：与 AGENTS.md 同源同全文，共用全量注入器）
-  for (let i = 0; i < tools.length; i++) {
-    const toolName = tools[i];
-    if (INSTRUCTION_TOOLS.includes(toolName)) {
-      injectInstructions(toolName, projectDir);
-    }
-  }
-
-  // 注入 AGENTS.md 完整指引（claude/codex/zcode 共用：版本感知幂等三态四分支 + 旧 ## SillySpec 小段迁移；
-  // zcode 2026-09-21-flow-command-cards FR-05 入面——AGENTS.md 是跨工具通用标准内容源）
-  if (tools.includes('claude') || tools.includes('codex') || tools.includes('zcode')) {
+  // 注入 AGENTS.md 完整指引（版本感知幂等三态四分支 + 旧 ## SillySpec 小段迁移）。
+  // 2026-10-19 起全工具统一落 AGENTS.md：gemini/opencode 不再产 GEMINI.md/INSTRUCTIONS.md
+  // （OpenCode 原生读 AGENTS.md；Gemini CLI 现默认 GEMINI.md，需自行引用 AGENTS.md，边界见 file-lifecycle）
+  if (tools.some((t) => ['claude', 'codex', 'zcode', 'gemini', 'opencode'].includes(t))) {
     injectAgentsInstructions(projectDir);
   }
 

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';