sillyspec 3.33.6 → 3.33.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.33.6",
+  "version": "3.33.8",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",
@@ -24,7 +24,7 @@
   ],
   "license": "MIT",
   "scripts": {
-    "test:core": "node --test test/preview-migration.test.mjs test/preview-progress.test.mjs test/preview-outlet.test.mjs test/preview-gc.test.mjs test/preview-gate-isolation.test.mjs test/db-engine.test.mjs test/db-concurrency.test.mjs test/db-atomic-write.test.mjs test/platform-sync-schema.test.mjs test/platform-sync-serialization.test.mjs test/change-ownership-guards.test.mjs test/watcher.test.mjs test/watcher-alerts.test.mjs test/watcher-timeline.test.mjs test/sentinel-rules.test.mjs test/handoff.test.mjs test/execution-mode-render.test.mjs test/knowledge-inbox.test.mjs test/knowledge-baseline.test.mjs test/quick-laststep-fourfields-preview.test.mjs test/doctor-align-execute-progress.test.mjs test/test-ledger.test.mjs test/test-bindings.test.mjs test/flow-draft-binding-extract.test.mjs test/gate-snapshot-lifecycle.test.mjs test/gate-snapshot-cleanup.test.mjs test/verify-trace-residual.test.mjs test/platform-creds-fallback.test.mjs test/archive-timeline-bake.test.mjs test/doc-ref-check.test.mjs test/flow-status-json.test.mjs test/flow-status-title.test.mjs test/flow-resume-title.test.mjs test/datetime-timeago.test.mjs test/resume-domain-flip.test.mjs test/fr-regress-cap-drop.test.mjs test/fr-priority-overlap.test.mjs test/archive-commit-suggest-race.test.mjs test/flow-done-fail-brief.test.mjs test/verify-probes-refresh-backup.test.mjs test/taskcard-yaml-triage-validate.test.mjs test/gate-last-reader.test.mjs test/status-multi-active-list.test.mjs test/gate-docs-only.test.mjs test/probe7-fr-prefill.test.mjs test/plan-fill-batch-config.test.mjs test/step-guide-prune.test.mjs test/gate-stage-review-hint.test.mjs test/design-ref-suggest.test.mjs test/flow-friction-batch3.test.mjs test/wave-auto-adopt.test.mjs test/test-incremental-rerun.test.mjs test/knowledge-graph.test.mjs test/explore-graph-guidance.test.mjs test/git-helper-input.test.mjs test/push-plan.test.mjs test/push-cli.test.mjs test/push-skill.test.mjs test/flow-guidance.test.mjs",
+    "test:core": "node --test test/preview-migration.test.mjs test/preview-progress.test.mjs test/preview-outlet.test.mjs test/preview-gc.test.mjs test/preview-gate-isolation.test.mjs test/db-engine.test.mjs test/db-concurrency.test.mjs test/db-atomic-write.test.mjs test/platform-sync-schema.test.mjs test/platform-sync-serialization.test.mjs test/change-ownership-guards.test.mjs test/watcher.test.mjs test/watcher-alerts.test.mjs test/watcher-timeline.test.mjs test/sentinel-rules.test.mjs test/handoff.test.mjs test/execution-mode-render.test.mjs test/knowledge-inbox.test.mjs test/knowledge-baseline.test.mjs test/quick-laststep-fourfields-preview.test.mjs test/doctor-align-execute-progress.test.mjs test/test-ledger.test.mjs test/test-bindings.test.mjs test/flow-draft-binding-extract.test.mjs test/gate-snapshot-lifecycle.test.mjs test/gate-snapshot-cleanup.test.mjs test/verify-trace-residual.test.mjs test/platform-creds-fallback.test.mjs test/archive-timeline-bake.test.mjs test/doc-ref-check.test.mjs test/flow-status-json.test.mjs test/flow-status-title.test.mjs test/flow-resume-title.test.mjs test/datetime-timeago.test.mjs test/resume-domain-flip.test.mjs test/fr-regress-cap-drop.test.mjs test/fr-priority-overlap.test.mjs test/archive-commit-suggest-race.test.mjs test/flow-done-fail-brief.test.mjs test/verify-probes-refresh-backup.test.mjs test/taskcard-yaml-triage-validate.test.mjs test/gate-last-reader.test.mjs test/status-multi-active-list.test.mjs test/gate-docs-only.test.mjs test/probe7-fr-prefill.test.mjs test/plan-fill-batch-config.test.mjs test/step-guide-prune.test.mjs test/gate-stage-review-hint.test.mjs test/design-ref-suggest.test.mjs test/flow-friction-batch3.test.mjs test/wave-auto-adopt.test.mjs test/test-incremental-rerun.test.mjs test/target-files-main-docs-rescue.test.mjs test/knowledge-graph.test.mjs test/explore-graph-guidance.test.mjs test/git-helper-input.test.mjs test/push-plan.test.mjs test/push-cli.test.mjs test/push-skill.test.mjs test/flow-guidance.test.mjs",
     "test": "node test/run-tests.mjs",
     "lint": "node test/check-syntax.mjs",
     "eval:dry": "node eval/run.mjs --dry-run",

package/src/agent-session-log.js

@@ -994,7 +994,10 @@ export function detectAgentLogEntries(opts) {
  * specBase/local.yaml platform 段（url + token，与链路 A 同源）。
  * @returns {{url:string, token:string}|null} 未配置返回 null（合法状态，静默跳过上报）
  */
-function readPlatformPushConfig(specBase, env = process.env) {
+export function readPlatformPushConfig(specBase, env = process.env) {
+  // 2026-10-28-knowledge-hits-cli-push：export 化（签名与行为零变化）——
+  // knowledge-hits.js 写后直报复用同一配置解析（单一源，不复制 local.yaml
+  // 解析逻辑）。
   if (env.SILLYHUB_PLATFORM_URL && env.SILLYHUB_PLATFORM_TOKEN) {
     return { url: env.SILLYHUB_PLATFORM_URL, token: env.SILLYHUB_PLATFORM_TOKEN };
   }

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/knowledge-hits.js

@@ -14,16 +14,92 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'fs'
 import { runtimeStatePath } from './runtime-paths.js'
 import { join } from 'path'
+import { readPlatformPushConfig } from './agent-session-log.js'
 
 const HITS_FILENAME = 'knowledge-hits.jsonl'
 
+// 直报超时上限（2026-10-28-knowledge-hits-cli-push）：对齐 agent-log PUSH_TIMEOUT_MS
+// 量级——最坏情况下进程退出被活跃 socket 拖住的时长有界。
+const HITS_PUSH_TIMEOUT_MS = 10_000
+
 function hitsFilePath(runtimeDir) {
   return runtimeStatePath(runtimeDir, HITS_FILENAME)
 }
 
+/**
+ * runtimeDir → specBase 反推（剥尾 `.runtime` 段；跨平台：正反斜杠与尾分隔符容忍）。
+ *
+ * 全部 appendKnowledgeHit 调用形态的 runtimeDir 最终都是 `<specBase>/.runtime`
+ * （join(specBase,'.runtime') 或 resolveRuntimeRoot 产物）——统一剥最后一段反推
+ * specBase 供平台配置读取（local.yaml 在 specBase 根）。结果保留输入的分隔符
+ * 形态（不做平台归一——Node fs 对 / 与 \ 双向兼容，归一反而扭曲 POSIX 形态输入）。
+ *
+ * @param {string} runtimeDir
+ * @returns {string} specBase（runtimeDir 末段不是 .runtime 时原样返回——容错面）
+ */
+export function specBaseFromRuntimeDir(runtimeDir) {
+  const raw = String(runtimeDir)
+  const norm = raw.replace(/\\/g, '/').replace(/\/+$/, '')
+  const idx = norm.lastIndexOf('/')
+  const last = idx === -1 ? norm : norm.slice(idx + 1)
+  if (last !== '.runtime') return runtimeDir
+  // \→/ 等长替换、去尾 / 只动末尾——norm 前 idx 字符与原串位置一一对应，
+  // 直接按剥点切片即保留原分隔符形态的 specBase。
+  return raw.slice(0, idx)
+}
+
+/**
+ * 单行遥测直报平台（2026-10-28-knowledge-hits-cli-push FR-01）。
+ *
+ * POST {url}/api/changes/-/hits-sync（Bearer shpsync_ 令牌——workspace 由令牌派生），
+ * body {lines:[line], daemon_local_id:'cli'}；接收端行级幂等（行 sha256 去重，
+ * 平台仓 2026-10-28-knowledge-hits-cli-direct）。best-effort 语义照
+ * pushAgentLogToPlatform 先例：无配置/被禁用静默跳过（返回 pushed:null）；
+ * 网络/非 2xx/超时 warn 一行不抛（返回 pushed:false, reason）——本地行已落盘、
+ * daemon 周期上行与平台按钮 flush 为兜底通道。
+ *
+ * @param {object} p
+ * @param {string} p.specBase - local.yaml 所在 spec 基路径
+ * @param {object} [p.env]    - env（默认 process.env；测试注入用）
+ * @param {string} p.line     - 已落盘的遥测行（JSON 字符串）
+ * @returns {Promise<{pushed:boolean|null, reason?:string}>}
+ */
+export async function pushKnowledgeHitToPlatform({ specBase, env = process.env, line }) {
+  if (env.SILLYSPEC_HITS_PUSH === '0') {
+    return { pushed: null, reason: 'disabled' }
+  }
+  const cfg = readPlatformPushConfig(specBase, env)
+  if (!cfg) return { pushed: null, reason: 'no-config' }
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), HITS_PUSH_TIMEOUT_MS)
+  try {
+    const res = await fetch(`${cfg.url.replace(/\/+$/, '')}/api/changes/-/hits-sync`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${cfg.token}` },
+      body: JSON.stringify({ lines: [line], daemon_local_id: 'cli' }),
+      signal: controller.signal,
+    })
+    if (!res.ok) {
+      console.warn(`[knowledge-hits-push] → HTTP ${res.status}（本地行已落盘，daemon 兜底）`)
+      return { pushed: false, reason: `http-${res.status}` }
+    }
+    return { pushed: true }
+  } catch (err) {
+    const msg = err && err.name === 'AbortError' ? '超时' : (err && err.message ? err.message : err)
+    console.warn(`[knowledge-hits-push] 直报失败: ${msg}（本地行已落盘，daemon 兜底）`)
+    return { pushed: false, reason: 'network' }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
 /**
  * 追加一条遥测记录（目录/文件缺失自动创建）。
  *
+ * 2026-10-28-knowledge-hits-cli-push：落盘成功后 void fire 平台直报（FR-01/02）——
+ * 不 await 不抛（失败 warn 一行由 pushKnowledgeHitToPlatform 内部收口），主流程
+ * 同步语义与返回值不变；无配置/被禁用时零行为差异。
+ *
  * @param {string} runtimeDir - .runtime 目录
  * @param {object} hit - 记录对象，常用字段 { type:'inject'|'classify', change, query, matchedFiles, at }
  *   （at 缺省时补当前 ISO 时间；其余字段原样序列化，classify 的 qlId/targetFile 等照写）
@@ -35,7 +111,10 @@ export function appendKnowledgeHit(runtimeDir, hit) {
     record.at = new Date().toISOString()
   }
   mkdirSync(runtimeDir, { recursive: true })
-  appendFileSync(hitsFilePath(runtimeDir), JSON.stringify(record) + '\n', 'utf8')
+  const line = JSON.stringify(record)
+  appendFileSync(hitsFilePath(runtimeDir), line + '\n', 'utf8')
+  // 写后直报（void fire）：本地已落盘，直报成败不影响本函数语义（FR-02）。
+  void pushKnowledgeHitToPlatform({ specBase: specBaseFromRuntimeDir(runtimeDir), line }).catch(() => {})
   return record
 }
 

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 {

package/src/verify-postcheck.js

@@ -4806,6 +4806,51 @@ export function reconcileTargetFiles({ cwd, specBase = null, changeName = null,
   if (rescuedCount > 0) {
     notes.push(`对账救赎：${rescuedCount} 个声明文件经近窗提交触及面命中（isolated worktree per-task commit 形态，porcelain 恒空——R9/R11 四连拦根治）`)
   }
+  // 主仓治理文档救赎（坑 target-files-worktree-docs-mismatch，2026-10-26-session-stage-progress
+  // verify 实证）：模块卡等主仓 .sillyspec/ 文档按 CLI 铁律「一律写主仓，绝不写 worktree 副本」
+  // ——worktree 形态 actual（wt diff+porcelain）结构性看不见主仓侧改动，声明主仓治理路径恒落
+  // ②类假红（「写 worktree=产物蒸发，写主仓=对账 missing」两规则打架）。救赎面=主仓 .sillyspec/
+  // 的 status（未提交）∪ baseline..HEAD diff（已提交），仅救赎「声明而 missing」的主仓治理路径
+  // （不扩 undeclared 面——与 R9/R11 窗口救赎同语义）。fail-open：主仓读取失败走既有 missing 判定。
+  if (actual.form === 'worktree') {
+    const govDeclared = declaredPaths.filter((p) => {
+      const clean = String(p).replace(/\\/g, '/').replace(/^NEW:/, '')
+      return clean.startsWith('.sillyspec/')
+    })
+    if (govDeclared.length > 0) {
+      let mainDocsRescued = 0
+      try {
+        const mainFace = new Set()
+        // -uall：未跟踪目录缺省折叠成目录条目（?? .sillyspec/docs/<proj>/ 整目录一行）——
+        // 模块卡常为新建文件，折叠形态对不上文件级声明，逐文件展开（scope-audit 同款口径）
+        const st = gitQuiet(cwd, ['status', '--porcelain', '--untracked-files=all', '--', '.sillyspec/'], { timeout: 30000, trim: false })
+        for (const line of String(st || '').split('\n')) {
+          if (!line || line.length < 4) continue
+          const p = line.slice(3).trim().replace(/^"|"$/g, '')
+          const arrow = p.indexOf(' -> ')
+          const f = (arrow !== -1 ? p.slice(arrow + 4) : p).replace(/\\/g, '/')
+          if (f) mainFace.add(pathKey(f))
+        }
+        if (actual.baseAnchor) {
+          const df = gitQuiet(cwd, ['diff', '--name-only', `${actual.baseAnchor}..HEAD`, '--', '.sillyspec/'], { timeout: 30000 })
+          for (const f of String(df || '').split('\n')) {
+            const t = f.trim().replace(/\\/g, '/')
+            if (t) mainFace.add(pathKey(t))
+          }
+        }
+        for (const p of govDeclared) {
+          const clean = String(p).replace(/\\/g, '/').replace(/^NEW:/, '')
+          if (!actualKeySet.has(pathKey(p)) && mainFace.has(pathKey(clean))) {
+            actualKeySet.add(pathKey(p))
+            mainDocsRescued++
+          }
+        }
+      } catch { /* 主仓治理面读取失败 → 走既有 missing 判定（fail-open 不新造阻断） */ }
+      if (mainDocsRescued > 0) {
+        notes.push(`主仓治理文档救赎：${mainDocsRescued} 个 .sillyspec/ 声明经主仓实际改动面命中（worktree 对账面看不见主仓侧模块卡等治理文档——「治理文档一律写主仓」铁律与 worktree actual 的结构性错配，2026-10-26 实证）`)
+      }
+    }
+  }
   // ①交集（计数进 evidence）：唯一路径口径（多卡声明同文件只计一次）
   for (const path of declaredPaths) {
     if (actualKeySet.has(pathKey(path))) matched.push(path)