sillyspec 3.33.7 → 3.33.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.33.7",
+  "version": "3.33.8",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/change-delete.js

@@ -106,12 +106,23 @@ export async function deleteChange({ cwd, specDir = null, changeName, confirm =
 
   const dirFiles = dirExists ? countFiles(dirPath) : 0;
   const worktreeInfo = await probeWorktree(cwd, changeName);
+  // 影子存档探测（2026-10-28-shadow-checkpoint）：dry-run 也报存档链规模——「删了丢多少存档」
+  // 与「删了丢代码」同级的决策信息。非 git 仓/无 ref 静默 null。
+  let checkpointInfo = null;
+  try {
+    const { hasCheckpointRef, listCheckpoints } = await import('./checkpoint.js');
+    if (hasCheckpointRef(cwd, changeName)) {
+      const list = await listCheckpoints({ repoRoot: cwd, changeName });
+      checkpointInfo = { ref: `refs/sillyspec/checkpoints/${changeName}`, count: list.length };
+    }
+  } catch { /* 非 git 仓/探测失败：无存档面 */ }
 
   if (!confirm) {
     return {
       ok: true, action: 'dry_run', change: changeName,
       db_row: row, dir: dirExists ? { path: dirPath, files: dirFiles } : null,
       worktree: worktreeInfo,
+      checkpoints: checkpointInfo,
       already_deleted: alreadyDeleted,
     };
   }
@@ -149,6 +160,18 @@ export async function deleteChange({ cwd, specDir = null, changeName, confirm =
   } catch (e) {
     warnings.push(`worktree 清理失败（不阻断删除）：${e.message}`);
   }
+  // 3.5 影子存档 ref 清理（2026-10-28-shadow-checkpoint FR-05）：删除是终态，存档链随变更
+  // 一并清 ref（对象交 git gc 自然回收）；归档不删（审计面保留）。best-effort：失败仅警告。
+  let checkpointsRemoved = false;
+  try {
+    const { hasCheckpointRef, deleteCheckpointRef } = await import('./checkpoint.js');
+    if (hasCheckpointRef(cwd, changeName)) {
+      checkpointsRemoved = deleteCheckpointRef(cwd, changeName);
+      if (!checkpointsRemoved) warnings.push(`影子存档 ref 删除失败（不阻断，可手删 refs/sillyspec/checkpoints/${changeName}）`);
+    }
+  } catch (e) {
+    warnings.push(`影子存档 ref 清理异常（不阻断删除）：${e.message}`);
+  }
   // 4. git 暂存目录删除（best-effort：非 git 仓 / specBase 在仓外时跳过，git status 照常可见）
   try {
     const relDir = relative(cwd, dirPath).split('\\').join('/');
@@ -178,6 +201,6 @@ export async function deleteChange({ cwd, specDir = null, changeName, confirm =
   return {
     ok: true, action: 'deleted', change: changeName,
     db_updated: dbUpdated, dir_removed: dirExists, files_removed: dirFiles,
-    worktree: worktreeInfo, warnings,
+    worktree: worktreeInfo, checkpoints_removed: checkpointsRemoved, warnings,
   };
 }

package/src/checkpoint.js

@@ -0,0 +1,258 @@
+/**
+ * checkpoint.js — 任务级影子提交存档（tick 即快照，2026-10-28-shadow-checkpoint）
+ *
+ * 定位：断点恢复从「进度级」（tasks.md 记做到哪）升级到「内容级」（工作区长什么样）——
+ * task tick 成功翻格后落一个 git 影子提交到 refs/sillyspec/checkpoints/<change>，agent
+ * 跑歪/改崩时 git restore --source 一键读档。git 对象库本身是内容寻址存储：增量成本=
+ * 只哈希变化文件，相同内容全局一份——零新依赖即得 CAS 快照性质。
+ *
+ * 机制（多 agent 共享仓安全是第一约束）：
+ *   - 临时索引 GIT_INDEX_FILE=.git/sillyspec-cp-index-<session>（会话隔离）——read-tree HEAD
+ *     起底 → add -A（硬排除清单）→ write-tree → commit-tree 成链（父=上一存档，首档父=
+ *     当时 HEAD）→ update-ref。共享 index 全程零读写（staged 面不可能被卷走，规则 11 纪律）。
+ *   - 无变化 no-op：write-tree 结果与现 ref 树 SHA 相同即跳过（零对象零 ref 翻转）。
+ *   - fail-open 铁律：本模块任何失败只返回 skipped（reason 留痕），绝不抛出阻断 tick。
+ *
+ * 边界：worktree 会话跳过（v1 主仓形态——git-dir ≠ common-dir 判定）；未忽略 untracked
+ * 总量超阈值（缺省 200MB，checkpoint.maxUntrackedMB）早停跳过；.sillyspec/.runtime 与
+ * 常见产物目录/.env* 硬排除不进快照（gitignore 之外的第二道防线）。
+ */
+import { existsSync, readFileSync, rmSync, statSync } from 'fs'
+import { join, resolve as resolvePath } from 'path'
+import { git, gitQuiet } from './git-helper.js'
+
+const REF_PREFIX = 'refs/sillyspec/checkpoints/'
+const DEFAULT_MAX_UNTRACKED_MB = 200
+const SUBJECT_PREFIX = 'sillyspec-cp: '
+const NOOP_GUARD_TREE_TIMEOUT_MS = 60000
+
+/** 硬排除清单（add 后在临时索引上 reset 的路径）。目录用 glob 双星任意深度形态
+ * （:(glob) 魔法 + 前置双星斜杠 + 尾部斜杠双星——实证 2.45：缺尾部 /** 时零匹配，
+ * 根级与嵌套 packages/x/node_modules 一并排除，2026-10-28-cp-review-debt FR-01）；
+ * .env* 与 .sillyspec/.runtime 维持根级语义。 */
+const EXCLUDE_DIRS = ['node_modules', 'dist', 'build', 'target', '.venv', 'venv', '__pycache__', '.next', '.cache', 'coverage']
+const RESET_SPECS = [...EXCLUDE_DIRS.map((d) => `:(glob)**/${d}/**`), '.env', '.env.*', '.sillyspec/.runtime']
+
+/** 与 EXCLUDE_SPECS 同口径的 JS 判定（体积护栏用——只计真会进快照的文件）。 */
+function isHardExcluded(p) {
+  const segs = p.split('/')
+  if (segs.some((s) => EXCLUDE_DIRS.includes(s))) return true
+  const root = segs[0]
+  if (root === '.env' || /^\.env\..+$/.test(root)) return true
+  if (p === '.sillyspec/.runtime' || p.startsWith('.sillyspec/.runtime/')) return true
+  return false
+}
+
+const SAFE_CHANGE_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+
+/**
+ * 读 .sillyspec/local.yaml 的 checkpoint 块（手解析单一键路径，沿 worktree supplyFiles
+ * 先例零 yaml 依赖）。fail-open：文件缺失/解析异常一律返回缺省（enabled=true）。
+ * @returns {{enabled: boolean, maxUntrackedMB: number}}
+ */
+export function readCheckpointConfig(repoRoot) {
+  const defaults = { enabled: true, maxUntrackedMB: DEFAULT_MAX_UNTRACKED_MB }
+  try {
+    const p = join(repoRoot, '.sillyspec', 'local.yaml')
+    if (!existsSync(p)) return defaults
+    const vals = {}
+    let inBlock = false
+    for (const rawLine of readFileSync(p, 'utf8').split(/\r?\n/)) {
+      const line = rawLine.replace(/\t/g, '  ')
+      if (/^checkpoint:\s*(#.*)?$/.test(line)) { inBlock = true; continue }
+      if (!inBlock) continue
+      if (/^\S/.test(line)) break // 出块：下一个顶层键
+      const m = line.match(/^\s+([\w.-]+):\s*(.*?)\s*(#.*)?$/)
+      if (m && m[2] !== '') vals[m[1]] = m[2]
+    }
+    const enabled = vals.enabled === undefined ? true : !/^(false|off|no|0)$/i.test(String(vals.enabled))
+    const mb = Number(vals.maxUntrackedMB)
+    return { enabled, maxUntrackedMB: Number.isFinite(mb) && mb > 0 ? mb : DEFAULT_MAX_UNTRACKED_MB }
+  } catch {
+    return defaults
+  }
+}
+
+/** 主仓判定：worktree 会话（git-dir ≠ common-dir）v1 跳过存档。 */
+function isWorktreeSession(repoRoot) {
+  const gitDir = gitQuiet(repoRoot, ['rev-parse', '--absolute-git-dir'])
+  const commonDir = gitQuiet(repoRoot, ['rev-parse', '--git-common-dir'])
+  if (!gitDir || !commonDir) return false // 探测失败不拦（留给后续 git 调用自然 fail-open）
+  if (commonDir === '.git') return false // 主仓：两者同指
+  try {
+    return resolvePath(repoRoot, gitDir) !== resolvePath(repoRoot, commonDir)
+  } catch {
+    return gitDir !== commonDir
+  }
+}
+
+/**
+ * 落一个影子提交（fail-open：任何失败返回 {kind:'skipped', reason}，绝不抛出）。
+ * @param {{repoRoot: string, changeName: string, session?: string, taskId?: string}} opts
+ * @returns {Promise<{kind:'created'|'noop'|'skipped', sha?: string, treeSha?: string,
+ *   parent?: string, files?: number, reason?: string, detail?: string}>}
+ */
+export async function createCheckpoint({ repoRoot, changeName, session, taskId }) {
+  const name = String(changeName || '')
+  if (!SAFE_CHANGE_NAME_RE.test(name)) return { kind: 'skipped', reason: 'invalid-change-name', detail: name }
+  const cfg = readCheckpointConfig(repoRoot)
+  if (!cfg.enabled) return { kind: 'skipped', reason: 'checkpoint-disabled' }
+  if (isWorktreeSession(repoRoot)) return { kind: 'skipped', reason: 'worktree-session' }
+
+  const ref = REF_PREFIX + name
+  const gitDir = gitQuiet(repoRoot, ['rev-parse', '--absolute-git-dir'])
+  if (!gitDir) return { kind: 'skipped', reason: 'not-a-git-repo' }
+  const sessionId = String(session || process.env.SILLYSPEC_SESSION_ID || 'anon').replace(/[^A-Za-z0-9._-]/g, '_')
+  const tmpIndex = join(gitDir, `sillyspec-cp-index-${sessionId}`)
+  // env 展开铁律（git-helper 终批-③）：裸替换丢 SystemRoot/TEMP 在 Windows 必炸
+  const idxEnv = { ...process.env, GIT_INDEX_FILE: tmpIndex }
+  const head = gitQuiet(repoRoot, ['rev-parse', 'HEAD'])
+  if (!head) return { kind: 'skipped', reason: 'no-head-commit' }
+
+  try {
+    rmSync(tmpIndex, { force: true }) // 清上次中断残留（同会话同路径幂等）
+    git(repoRoot, ['read-tree', 'HEAD'], { env: idxEnv })
+
+    // 体积护栏：只计真会进快照的 untracked（硬排除同口径），累计超限早停
+    const maxBytes = cfg.maxUntrackedMB * 1024 * 1024
+    const othersRaw = gitQuiet(repoRoot, ['ls-files', '--others', '--exclude-standard', '-z'])
+    if (othersRaw) {
+      let bytes = 0
+      for (const p of othersRaw.split('\0')) {
+        if (!p || isHardExcluded(p)) continue
+        try {
+          bytes += statSync(join(repoRoot, p)).size
+        } catch { /* 文件瞬失：计 0 不拦 */}
+        if (bytes > maxBytes) return { kind: 'skipped', reason: 'untracked-size-over-limit', detail: `${Math.round(bytes / 1048576)}MB > ${cfg.maxUntrackedMB}MB` }
+      }
+    }
+
+    // 裸 add -A（无 pathspec）：ignored 文件静默跳过——显式 pathspec 形态遇 gitignored
+    // 候选会整体报错拒加（"paths are ignored by .gitignore"，.sillyspec/ 被忽略的仓必炸）。
+    // 硬排除随后以 reset 收窄：临时索引上把排除路径退回 HEAD 态（不在 HEAD 的即整条移出）。
+    git(repoRoot, ['add', '-A'], { env: idxEnv, timeout: NOOP_GUARD_TREE_TIMEOUT_MS })
+    git(repoRoot, ['reset', '-q', '--', ...RESET_SPECS], { env: idxEnv })
+    const treeSha = git(repoRoot, ['write-tree'], { env: idxEnv })
+
+    const current = gitQuiet(repoRoot, ['rev-parse', '--verify', ref])
+    if (current) {
+      const currentTree = gitQuiet(repoRoot, ['rev-parse', `${ref}^{tree}`])
+      if (currentTree === treeSha) return { kind: 'noop', treeSha } // 无变化：零对象零翻转
+    }
+
+    const parent = current || head
+    const subject = `${SUBJECT_PREFIX}${name} ${taskId || '-'} ${new Date().toISOString()}`
+    const message = `${subject}\n\nshadow checkpoint for ${name}\ntask: ${taskId || '-'}\nsession: ${sessionId}\n`
+    // 身份兜底（沿 worktree baseline checkpoint 先例）：未配置 user.email 时注入临时身份，
+    // 已配置则用真实身份——存档提交可归属
+    const cpEnv = { ...process.env }
+    if (!gitQuiet(repoRoot, ['config', 'user.email'])) {
+      cpEnv.GIT_AUTHOR_NAME = 'sillyspec-checkpoint'
+      cpEnv.GIT_AUTHOR_EMAIL = 'checkpoint@sillyspec.local'
+      cpEnv.GIT_COMMITTER_NAME = 'sillyspec-checkpoint'
+      cpEnv.GIT_COMMITTER_EMAIL = 'checkpoint@sillyspec.local'
+    }
+    const sha = git(repoRoot, ['commit-tree', treeSha, '-p', parent, '-F', '-'], { input: message, env: cpEnv })
+    git(repoRoot, ['update-ref', ref, sha])
+
+    let files = 0
+    const changed = gitQuiet(repoRoot, ['diff-tree', '--no-commit-id', '--name-only', '-r', sha])
+    if (changed) files = changed.split('\n').filter(Boolean).length
+    return { kind: 'created', sha, treeSha, parent, files }
+  } catch (e) {
+    return { kind: 'skipped', reason: 'git-error', detail: e && e.message ? e.message : String(e) }
+  } finally {
+    try { rmSync(tmpIndex, { force: true }) } catch { /* 清理失败：同会话下次覆盖 */ }
+  }
+}
+
+/**
+ * 列出变更的存档链（按时间倒序；链尾混入主历史，按 subject 前缀过滤）。
+ * @returns {Promise<Array<{sha: string, taskId: string|null, ts: number, files: number}>>}
+ */
+export async function listCheckpoints({ repoRoot, changeName }) {
+  const name = String(changeName || '')
+  if (!SAFE_CHANGE_NAME_RE.test(name)) return []
+  const ref = REF_PREFIX + name
+  const log = gitQuiet(repoRoot, ['log', '--format=%H%x09%at%x09%s', '-n', '200', ref])
+  if (!log) return []
+  const out = []
+  for (const line of log.split('\n')) {
+    if (!line) continue
+    const [sha, at, subject] = line.split('\t')
+    if (!subject || !subject.startsWith(SUBJECT_PREFIX)) continue // 链尾以下的主历史止步
+    const m = /^sillyspec-cp: \S+ (task-\d+|-) /.exec(subject)
+    const files = gitQuiet(repoRoot, ['diff-tree', '--no-commit-id', '--name-only', '-r', sha])
+    out.push({ sha, taskId: m && m[1] !== '-' ? m[1] : null, ts: Number(at) * 1000, files: files ? files.split('\n').filter(Boolean).length : 0 })
+  }
+  return out
+}
+
+/**
+ * 恢复预览：工作区 vs 存档点的 diff（patch 与 stat 各一份）。
+ * @returns {Promise<{stat: string, patch: string}>}
+ */
+export async function previewRestore({ repoRoot, sha, paths = [] }) {
+  const spec = ['--', ...(paths && paths.length ? paths : ['.'])]
+  const stat = git(repoRoot, ['diff', '--stat', sha, ...spec])
+  const patch = git(repoRoot, ['diff', sha, ...spec])
+  return { stat, patch }
+}
+
+/**
+ * 链内校验（无上限）：subject 前缀过滤全链——不复用 listCheckpoints 的 -n 200 显示帽
+ * （截断解耦，2026-10-28-cp-review-debt FR-03：超帽旧档同样可读，主历史普通提交仍拒）。
+ */
+function isCheckpointInChain(repoRoot, ref, sha) {
+  const subjects = gitQuiet(repoRoot, ['log', '--format=%H %s', ref])
+  if (!subjects) return false
+  for (const line of subjects.split('\n')) {
+    if (!line) continue
+    const commitSha = line.slice(0, 40)
+    const subject = line.slice(41)
+    if (!subject.startsWith(SUBJECT_PREFIX)) break // 链尾以下为主历史，止步
+    if (commitSha === sha) return true
+  }
+  return false
+}
+
+/**
+ * 读档：git restore --source（仅写工作区，零触碰 index）。调用方负责 --yes 确认纪律。
+ * @param {{repoRoot: string, sha: string, paths?: string[], all?: boolean}} opts
+ * @returns {Promise<{ok: boolean, reason?: string, restored: string[]}>}
+ */
+export async function restoreCheckpoint({ repoRoot, sha, changeName, paths = [], all = false }) {
+  const name = String(changeName || '')
+  const ref = REF_PREFIX + name
+  if (!SAFE_CHANGE_NAME_RE.test(name) || !isCheckpointInChain(repoRoot, ref, sha)) {
+    return { ok: false, reason: 'sha 不在该变更存档链中（用 checkpoint --change 列出可用 SHA）', restored: [] }
+  }
+  const target = (all || !paths.length) ? ['.'] : paths
+  try {
+    git(repoRoot, ['restore', `--source=${sha}`, '--', ...target])
+    return { ok: true, restored: target }
+  } catch (e) {
+    return { ok: false, reason: e && e.message ? e.message : String(e), restored: [] }
+  }
+}
+
+/** 删除变更的存档 ref（change-delete 清理步用；best-effort 不抛出）。 */
+export function deleteCheckpointRef(repoRoot, changeName) {
+  const name = String(changeName || '')
+  if (!SAFE_CHANGE_NAME_RE.test(name)) return false
+  try {
+    git(repoRoot, ['update-ref', '-d', REF_PREFIX + name])
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** ref 存在性探测（dry-run 报告面用）。 */
+export function hasCheckpointRef(repoRoot, changeName) {
+  const name = String(changeName || '')
+  if (!SAFE_CHANGE_NAME_RE.test(name)) return false
+  return Boolean(gitQuiet(repoRoot, ['rev-parse', '--verify', REF_PREFIX + name]))
+}
+
+export default { createCheckpoint, listCheckpoints, previewRestore, restoreCheckpoint, deleteCheckpointRef, hasCheckpointRef, readCheckpointConfig }

package/src/config-schema.js

@@ -78,6 +78,15 @@ export const LOCAL_YAML_SCHEMA = {
         { path: 'commands.scan:check', type: 'string', optional: true, status: 'live', readers: ['scan 漂移检查（scripts/scan-drift-check.py 经 scan 流程调用）'], desc: '【2026-10-23-schema-registration-debt 平台仓 dogfood 补登】scan 产物漂移自检命令。', example: 'python scripts/scan-drift-check.py' },
       ],
     },
+    {
+      id: 'checkpoint',
+      title: '影子存档（task tick 快照）',
+      note: '机制先落代码缺省（fail-open，缺省零回归）——键只用于仓主显式调优（2026-10-28-shadow-checkpoint）。',
+      keys: [
+        { path: 'checkpoint.enabled', type: 'boolean', optional: true, status: 'live', readers: ['readCheckpointConfig (src/checkpoint.js)'], desc: '影子存档开关——task tick 成功翻格后落 git 影子提交到 refs/sillyspec/checkpoints/<change>（临时索引零触碰共享暂存区，断点恢复从进度级升到内容级）。缺省 true；false 关闭（tick 照常）。解析失败 fail-open 取缺省。', example: 'false' },
+        { path: 'checkpoint.maxUntrackedMB', type: 'number', optional: true, status: 'live', readers: ['readCheckpointConfig (src/checkpoint.js)'], desc: '体积护栏——未忽略 untracked 总量超过该 MB 数时跳过本次存档并留痕（早停判定，不遍历全树；硬排除目录不计入）。缺省 200。', example: '50' },
+      ],
+    },
     {
       id: 'knowledge',
       title: '知识检索（平台向量语义召回）',
@@ -425,6 +434,11 @@ commands:
   # lint_timeout_sec: 600    # commands.lint 超时秒数（缺省 180）
   # knowledge-gate: false    # 方案步 --done 知识检索命中回显开关（缺省 true 开；false 关回显）
 
+# ── 影子存档（task tick 快照；缺省开启零配置，仅在显式调优时写）──
+# checkpoint:
+#   enabled: true             # 影子存档开关（false 关闭，tick 照常）
+#   maxUntrackedMB: 200       # 体积护栏——未忽略 untracked 总量超此 MB 数跳过存档留痕
+
 # ── 知识检索（平台向量语义召回）──
 # 缺省（未写整段）跟随平台能力自动探测：端点在场自动启用、未部署自动跳过（部署后自动
 # 启用，零配置）。仅显式逃生阀时才需要写：

package/src/flow.js

@@ -2942,6 +2942,13 @@ async function cmdFlowVerifyDrafts({ change, cwd, specBase, runtimeRootOpt = nul
     for (const a of r.advisories) console.warn(`⚠️ [门柱漂移 advisory] ${a}（不阻断批准）`)
     if (r.degraded) console.log(`ℹ️ 自查降级：draft-ledger 不在此机（.runtime 机本位/存量变更）——空槽兜底校验通过（v2 纯 markdown 无法对锚校验，如实降级）`)
     console.log(`✅ spec 面自查通过（0 violations）——通过≠批准：请把摘要给用户看，用户确认后 sillyspec flow approve --change ${change}（批准留痕后动码）`)
+    // 重叠路由 advisory（2026-10-28-overlap-route FR-04）：批准前最后一个高频触点——当前
+    // 变更声明与他人活跃变更相交时一行分流提示。fail-open 静默：检测异常不拦批准不影响退出码。
+    try {
+      const { overlapAdvisoryFor } = await import('./overlap-detect.js')
+      const line = overlapAdvisoryFor(change, { cwd, specBase })
+      if (line) console.warn(line)
+    } catch { /* advisory 静默：检测失败不拦批准 */ }
   } else {
     for (const a of r.advisories) console.warn(`⚠️ [门柱漂移 advisory] ${a}（不阻断批准）`)
     if (hasViolations) {

package/src/foreign-declared.js

@@ -174,7 +174,8 @@ export function collectForeignDeclaredFiles(cwd, currentChangeName, opts = {}) {
  * （退回旧 foreign-first 行为，fail-closed 不放大放行面）。
  * @returns {Set<string>} 正斜杠归一后的声明路径集
  */
-function loadOwnDeclaredSet(specBase, runtimeRoot, currentChangeName) {
+// export 补齐（2026-10-28-overlap-route）：重叠检测复用声明加载单一源，防口径漂移
+export function loadOwnDeclaredSet(specBase, runtimeRoot, currentChangeName) {
   const set = new Set()
   if (!currentChangeName) return set
   const norm = (p) => String(p || '').replace(/\\/g, '/')

package/src/index.js

@@ -148,6 +148,11 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec change-rename <旧变更名> <新变更名>
   sillyspec change-delete <变更名> [--confirm]  删除变更（DB status='deleted' 与归档语义分离 +
                                       移目录 + 清 worktree + 推平台墓碑；默认 dry-run）
+  sillyspec checkpoint --change <名> [--diff <sha> [--path <p>]] [--restore <sha>
+                                      [--path <p>|--all] --yes] [--delete-ref]
+                                      影子存档面：列出 task tick 自动落的存档链，预览/按路径读档
+  sillyspec overlap                  查询活跃变更 target-file 声明重叠（advisory——检出即附
+                                      worktree 分流与落地序列指引）
   sillyspec knowledge <search --query "..." --limit N
                         | inspect --id "..."
                         | validate | refresh
@@ -5055,6 +5060,96 @@ checkbox 行；depends_on 自动反填行内注解 "(depends_on: task-01,02)"；
       process.exitCode = r.ok ? 0 : 1;
       break;
     }
+    case 'checkpoint': {
+      // 2026-10-28-shadow-checkpoint：影子存档面——task tick 自动落档（refs/sillyspec/
+      // checkpoints/<change>），本动词提供列出/预览/读档/清 ref 的人工面。恢复纪律（FR-03）：
+      // --restore 必须显式 --yes；先 --diff 同参预览再执行是推荐路径。
+      const cpVal = (flag) => {
+        const i = filteredArgs.indexOf(flag);
+        return i >= 0 && filteredArgs[i + 1] && !String(filteredArgs[i + 1]).startsWith('--')
+          ? filteredArgs[i + 1] : null;
+      };
+      const cpChange = cpVal('--change');
+      if (!cpChange) {
+        console.error('❌ 用法: sillyspec checkpoint --change <名> [--diff <sha> [--path <p>]] [--restore <sha> [--path <p>|--all] --yes] [--delete-ref]');
+        process.exitCode = 2;
+        break;
+      }
+      const { listCheckpoints, previewRestore, restoreCheckpoint, deleteCheckpointRef } = await import('./checkpoint.js');
+      const cpDiffSha = cpVal('--diff');
+      const cpRestoreSha = cpVal('--restore');
+      const pathArgs = [];
+      for (let i = 0; i < filteredArgs.length - 1; i++) {
+        if (filteredArgs[i] === '--path' && !String(filteredArgs[i + 1]).startsWith('--')) pathArgs.push(filteredArgs[i + 1]);
+      }
+      const cpAll = filteredArgs.includes('--all');
+      const cpYes = filteredArgs.includes('--yes');
+      const cpDeleteRef = filteredArgs.includes('--delete-ref');
+      if (cpDeleteRef) {
+        const okDel = deleteCheckpointRef(dir, cpChange);
+        console.log(okDel ? `🗑️  已删除 refs/sillyspec/checkpoints/${cpChange}` : `ℹ️  无 refs/sillyspec/checkpoints/${cpChange}（无可删）`);
+        break;
+      }
+      if (cpDiffSha) {
+        try {
+          const pv = await previewRestore({ repoRoot: dir, sha: cpDiffSha, paths: pathArgs });
+          console.log(pv.stat || '（无差异）');
+          if (pv.patch) console.log(pv.patch);
+        } catch (e) {
+          console.error(`❌ 预览失败：${e && e.message ? e.message : e}`);
+          process.exitCode = 1;
+        }
+        break;
+      }
+      if (cpRestoreSha) {
+        if (!cpYes) {
+          console.error(`❌ 恢复需显式 --yes（建议先 --diff 同参预览）：sillyspec checkpoint --change ${cpChange} --diff <sha> [--path p] 再 --restore <sha> --path <p> --yes`);
+          process.exitCode = 2;
+          break;
+        }
+        if (!cpAll && pathArgs.length === 0) {
+          console.error('❌ 整树恢复需 --all（按路径恢复用 --path <p>，可多次）');
+          process.exitCode = 2;
+          break;
+        }
+        const rr = await restoreCheckpoint({ repoRoot: dir, sha: cpRestoreSha, changeName: cpChange, paths: pathArgs, all: cpAll });
+        if (rr.ok) console.log(`🗂️  已读档 ${cpRestoreSha.slice(0, 8)} → ${(cpAll ? ['.'] : pathArgs).join(' ')}（仅写工作区，共享暂存区未动）`);
+        else { console.error(`❌ ${rr.reason}`); process.exitCode = 1; }
+        break;
+      }
+      const list = await listCheckpoints({ repoRoot: dir, changeName: cpChange });
+      if (!list.length) {
+        console.log(`ℹ️  变更 ${cpChange} 暂无影子存档（task tick 成功勾选时自动落档；checkpoint.enabled=false 时关闭）`);
+        break;
+      }
+      console.log(`🗂️  变更 ${cpChange} 影子存档链（${list.length} 档，新→旧）：`);
+      for (const c of list) {
+        const when = new Date(c.ts).toISOString().replace('T', ' ').slice(0, 19);
+        console.log(`   ${c.sha.slice(0, 8)}  ${when}  ${c.taskId || '-'}  ${c.files} 文件`);
+      }
+      console.log(`\n预览：sillyspec checkpoint --change ${cpChange} --diff <sha> [--path p]｜读档：--restore <sha> --path <p> --yes${list.length >= 200 ? '\nℹ️  列表显示截 200 档（仅展示面）——全量走 git：git log --format="%H %s" refs/sillyspec/checkpoints/' + cpChange : ''}`);
+      break;
+    }
+    case 'overlap': {
+      // 2026-10-28-overlap-route：target-file 声明重叠仓级查询（advisory 恒 exit 0）——
+      // 事前路由信号：检出重叠附 worktree 分流与落地序列指引（不是禁止是分流）。
+      const { detectDeclaredOverlaps } = await import('./overlap-detect.js');
+      let overlaps = [];
+      try { overlaps = detectDeclaredOverlaps({ cwd: dir, specBase: resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec') }); }
+      catch (e) { console.log(`ℹ️  重叠检测不可用（advisory 面静默退化）：${e && e.message ? e.message : e}`); break; }
+      if (!overlaps.length) {
+        console.log(`✅ 无 target-file 声明重叠——各活跃变更声明面互不相交（落地零冲突预期）`);
+        break;
+      }
+      console.log(`⚠️  ${overlaps.length} 个文件被多个活跃变更声明（并行改同一文件是冲突地带）：`);
+      for (const o of overlaps) {
+        console.log(`   ${o.file} ← ${o.changes.join('、')}`);
+      }
+      console.log(`\n🔀 分流建议：其一转 worktree 形态并行——sillyspec worktree apply <后到变更名>（隔离干活，互不可见互不干扰）。`);
+      console.log(`   落地序列（既有机器）：先落地者干净进主线；后落地者 apply --3way 三方合并（同文件不同区域自动过，同段冲突摆出裁决）；并发落地由 main-repo.lock 串行。`);
+      console.log(`   确认某方已死：归档后其声明自动退出重叠判定（归档件只读）。`);
+      break;
+    }
     case 'flow': {
       // R7 切片二：2-调用轻量协议命令族（start/done/amend-draft）——协议必需交互=2。
       // --json 全局透传（2026-10-06-flow-status-json）：该 flag 在上方全局解析段被剥出
@@ -5806,7 +5901,7 @@ SillySpec pull — 拉取服务器 spec 快照到本地（X2 / FR-07）
       break;
     }
     default: {
-      const topCommands = ['init', 'setup', 'run', 'progress', 'worktree', 'dispatch', 'agent-log', 'local', 'workflow', 'gate', 'derive', 'backfill-reviews', 'register-stage-review', 'modules', 'change-rename', 'change-delete', 'knowledge', 'platform', 'pull', 'scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore', 'status', 'doctor', 'auto', 'runtime', 'watcher', 'commit', 'push'];
+      const topCommands = ['init', 'setup', 'run', 'progress', 'worktree', 'dispatch', 'agent-log', 'local', 'workflow', 'gate', 'derive', 'backfill-reviews', 'register-stage-review', 'modules', 'change-rename', 'change-delete', 'checkpoint', 'overlap', 'knowledge', 'platform', 'pull', 'scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore', 'status', 'doctor', 'auto', 'runtime', 'watcher', 'commit', 'push'];
       const suggestion = didYouMean(command, topCommands);
       console.error(`❌ 未知命令: ${command}`);
       if (command === '--status') {

package/src/overlap-detect.js

@@ -0,0 +1,68 @@
+/**
+ * overlap-detect.js — 活跃变更 target-file 声明重叠检测（2026-10-28-overlap-route）
+ *
+ * 定位：同 target-file 并行的事前路由信号——落地侧机器已厚（worktree apply --3way 三方
+ * 合并、main-repo.lock 全仓串行、guard 相交预检、base 漂移 re-anchor），缺的是干活期的
+ * 「两个活跃变更声明了同一文件」检测：重叠拖到落地才撞见，错失把后到者分流进 worktree
+ * 的窗口。本模块只做检测与呈现（advisory），不做调度不做阻断——「不是禁止，是分流」。
+ *
+ * 机制：声明加载单一源复用 foreign-declared.loadOwnDeclaredSet（design §6 文件变更
+ * 清单 ∪ task 卡 allowed_paths/target_files，quick 会话 guard 形态），构建文件→变更集
+ * 反查表，声明同一文件的变更数 ≥2 即重叠条目。瞬时快照零持久状态；归档（目录移入
+ * changes/archive/）天然退出反查表。
+ *
+ * 消费面：sillyspec overlap 仓级查询动词；flow verify-drafts 通过分支的路由 advisory。
+ */
+import { readdirSync } from 'fs'
+import { join } from 'path'
+import { loadOwnDeclaredSet } from './foreign-declared.js'
+
+/**
+ * 检测活跃变更间的 target-file 声明重叠。
+ * @param {{cwd?: string, specBase?: string}} opts 二选一（specBase 优先）
+ * @returns {Array<{file: string, changes: string[]}>} file 正斜杠归一、changes 字典序、
+ *   条目按 file 排序；无重叠返回 []。任何读取失败 fail-open（该变更空集），绝不抛出。
+ */
+export function detectDeclaredOverlaps({ cwd, specBase } = {}) {
+  const base = specBase || join(cwd || process.cwd(), '.sillyspec')
+  const runtimeRoot = join(base, '.runtime')
+  let names = []
+  try {
+    names = readdirSync(join(base, 'changes'), { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name !== 'archive')
+      .map((e) => e.name)
+  } catch {
+    return [] // 无 changes/ 目录：零活跃变更
+  }
+  const byFile = new Map()
+  for (const name of names) {
+    const own = loadOwnDeclaredSet(base, runtimeRoot, name) // 内部 fail-open：解析失败空集
+    if (!own || own.size === 0) continue
+    for (const f of own) {
+      if (!byFile.has(f)) byFile.set(f, new Set())
+      byFile.get(f).add(name)
+    }
+  }
+  const overlaps = []
+  for (const [file, changes] of byFile) {
+    if (changes.size >= 2) overlaps.push({ file, changes: [...changes].sort() })
+  }
+  return overlaps.sort((a, b) => a.file.localeCompare(b.file))
+}
+
+/**
+ * 指定变更的重叠路由提示文案（verify-drafts 通过分支钩子用）。
+ * @returns {string|null} null=该变更无重叠（调用方零输出）；有则返回一行提示
+ *   （分流建议 + 落地序列 + 详查指引）。纯函数：检测异常由上层 try/catch fail-open。
+ */
+export function overlapAdvisoryFor(changeName, { cwd, specBase } = {}) {
+  const name = String(changeName || '')
+  if (!name) return null
+  const mine = detectDeclaredOverlaps({ cwd, specBase }).filter((o) => o.changes.includes(name))
+  if (mine.length === 0) return null
+  const others = [...new Set(mine.flatMap((o) => o.changes).filter((c) => c !== name))].join('、')
+  const files = mine.slice(0, 3).map((o) => `${o.file}←${o.changes.join(',')}`).join('；') + (mine.length > 3 ? ` 等 ${mine.length} 个` : '')
+  return `⚠️ [重叠路由] 本变更与活跃变更 ${others} 声明了相同文件（${files}）——并行改同一文件是冲突地带，建议其一转 worktree 形态（sillyspec worktree apply <名>）；落地序列：先落地干净进、后落地 apply --3way 三方合并（并发由 main-repo.lock 串行）。详见 sillyspec overlap`
+}
+
+export default { detectDeclaredOverlaps, overlapAdvisoryFor }

package/src/run/shared.js

@@ -109,7 +109,10 @@ export function assertDatedChangeName(name, label = '变更名') {
 
 import { buildExecuteSteps } from '../stages/execute.js'
 import { buildPlanSteps } from '../stages/plan.js'
-import { stageRegistry } from '../stages/index.js'
+// stageRegistry 不静态引 stages/index.js（2026-10-28-stages-cycle-root-fix）：execute.js 子树
+// （knowledge-hits → agent-session-log → run/shared）回边使 index.js 首次求值 stageRegistry
+// 时 execute 绑定仍在 TDZ（execute.js:19-21 注释记载的坑形态再犯）——唯一使用点
+// getStageSteps 已是 async，点用动态 import 断环（同函数 await import 惰性先例）。
 import { parseRepo, parseRepoRegistry } from '../stages/plan-postcheck.js'
 import { MultiRepoContext } from './multi-repo-context.js'
 
@@ -2505,6 +2508,9 @@ export async function getStageSteps(stageName, cwd, progress, specDir = null) {
       return buildQuickScanSteps()
     }
   }
+  // 动态取注册表（断环点，见文件头 import 区注释）：首次求值时机后移到调用点，
+  // 此处到达时 stages/index.js 及其全部阶段定义必已完成初始化
+  const { stageRegistry } = await import('../stages/index.js')
   const def = stageRegistry[stageName]
   return def ? def.steps : null
 }

package/src/task-tick.js

@@ -158,6 +158,22 @@ export async function runTaskTick({ changeName, cwd, taskId, specBase, evidence
     } catch (e) {
       console.warn(`⚠️ 勾选留痕写失败（task-ticks.jsonl：${e && e.code ? e.code : e}）——翻格不受影响，timeline 勾选时刻退事件流推断`)
     }
+    // 影子存档（2026-10-28-shadow-checkpoint）：勾选即快照——tasks.md 翻格+侧车落盘后落一个
+    // git 影子提交到 refs/sillyspec/checkpoints/<change>，断点恢复从进度级升到内容级。
+    // best-effort fail-open（模块内零抛出，此处再兜一层）：任何失败只回显一行，绝不影响翻格。
+    try {
+      const { createCheckpoint } = await import('./checkpoint.js')
+      const cp = await createCheckpoint({
+        repoRoot: cwd, changeName,
+        session: process.env.SILLYSPEC_SESSION_ID,
+        taskId: normalizeTaskId(taskId) || taskId,
+      })
+      if (cp.kind === 'created') console.log(`🗂️  影子存档 ${String(cp.sha).slice(0, 8)}（${cp.files} 文件变更）→ refs/sillyspec/checkpoints/${changeName}`)
+      else if (cp.kind === 'noop') console.log(`🗂️  影子存档 noop（工作区无变化，零对象）`)
+      else console.log(`🗂️  影子存档跳过：${cp.reason}${cp.detail ? `（${cp.detail}）` : ''}`)
+    } catch (e) {
+      console.warn(`⚠️ 影子存档失败（不阻断勾选）：${e && e.message ? e.message : e}`)
+    }
     // 工件即时重推（2026-10-07-allticked-gate-docs-resync）：翻格即任务面变更——顺带触发
     // spec-sync，平台不再停留 start 时点快照（真实会话实证：改写后平台恒显初稿）。best-effort。
     try {