sillyspec 3.27.11 → 3.28.0

package/src/endpoint-extractor.js

@@ -47,8 +47,10 @@ export function extractFastApiEndpoints(filePath) {
   }
 
   // 2. 装饰器全文匹配：单行 `@router.get("/path")`、分散式 `@router.get\n("/path")`、
-  //    多行参数 `@router.get(\n  "/path",\n  response_model=…)` 三态合一（\s* 跨换行）
-  const decoratorRe = /@(?:router|api_router)\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/g
+  //    多行参数 `@router.get(\n  "/path",\n  response_model=…)` 三态合一（\s* 跨换行）。
+  //    路径组 `[^"'`]*` 允许空串（坑 endpoints-extract-worktree-pitfalls ③：`@router.get("")`
+  //    空路径装饰器 = 前缀本身即路由，`+` 量词静默漏扫——GET /notifications 实证丢失）。
+  const decoratorRe = /@(?:router|api_router)\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]*)["'`]/g
   let m
   while ((m = decoratorRe.exec(content)) !== null) {
     endpoints.push({
@@ -82,8 +84,9 @@ export function extractExpressEndpoints(filePath) {
     if (useMatch) routerPrefix = useMatch[1]
   }
 
-  // 路由全文匹配（坑 endpoint-multiline-decorator-miss：`router.get(\n  "/path",\n  handler)` 同病）
-  const routeRe = /\b(?:app|router)\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/gi
+  // 路由全文匹配（坑 endpoint-multiline-decorator-miss：`router.get(\n  "/path",\n  handler)` 同病；
+  // 空串路径与 FastAPI 同理允许——`router.get("")` = use 前缀本身）
+  const routeRe = /\b(?:app|router)\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]*)["'`]/gi
   let m
   while ((m = routeRe.exec(content)) !== null) {
     endpoints.push({ method: m[1].toUpperCase(), path: routerPrefix + m[2], source: filePath, line: lineOfIndex(content, m.index) })
@@ -140,6 +143,69 @@ export function extractSpringEndpoints(filePath) {
   return endpoints
 }
 
+/**
+ * 从单个文件提取路由挂载前缀（挂载点侧，与 router 文件分离）。
+ * - FastAPI：`app.include_router(xxx_router, prefix="/api")`（含多行形态，`[^)]*?` 跨参数/换行）
+ * - Express：`app.use("/api", router)`
+ * 跨文件前缀无法在提取端点时合并（挂载点与 router 文件分离，静态扫描不做导入图关联），
+ * 收集为前缀集合供对账端剥除对齐（坑 endpoints-mount-prefix-gap）。
+ *
+ * @param {string} filePath - 文件绝对路径
+ * @returns {string[]} 挂载前缀列表
+ */
+export function extractMountPrefixes(filePath) {
+  const content = readFileSync(filePath, 'utf8')
+  const prefixes = []
+  for (const m of content.matchAll(/\.include_router\s*\([^)]*?prefix\s*=\s*["'`]([^"'`]+)["'`]/g)) {
+    prefixes.push(m[1])
+  }
+  for (const m of content.matchAll(/\bapp\.use\s*\(\s*["'`]([^"'`]+)["'`]/g)) {
+    prefixes.push(m[1])
+  }
+  return prefixes
+}
+
+// backend 扫描目录排除清单（端点提取与挂载前缀收集共用）。
+// 对齐 scanFrontendApiCalls（坑 parity-scan-stale-dirs：.claude/worktrees 陈旧检出
+// 与各类 build 产物混入端点扫描全是噪音）——backend 侧另含 __pycache__/.gradle/maven target
+const BACKEND_DIR_EXCLUDE = [
+  /^__pycache__$/, /^node_modules$/, /^\.venv$/, /^venv$/, /^\.git$/, /^\.gradle$/,
+  /^\.claude$/, /^\.vscode$/, /^\.idea$/, /^\.cursor$/, /^\.next$/, /^\.nuxt$/,
+  /^\.output$/, /^\.turbo$/, /^\.parcel-cache$/, /^coverage$/,
+  /^\.sillyspec$/, /^\.worktrees$/, /^\.d\.ts$/,
+  /^(dist|build|target|out)$/i,
+  /test/i,
+]
+
+/**
+ * 递归扫描目录收集路由挂载前缀集合（include_router prefix / app.use 路径）。
+ * @param {string} dir
+ * @param {{ excludePatterns?: RegExp[] }} opts
+ * @returns {string[]} 去重后的挂载前缀列表
+ */
+export function scanMountPrefixes(dir, opts = {}) {
+  const excludePatterns = opts.excludePatterns || BACKEND_DIR_EXCLUDE
+  const prefixes = new Set()
+  if (!existsSync(dir)) return [...prefixes]
+  function walk(d) {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, entry.name)
+      if (entry.isDirectory()) {
+        if (excludePatterns.some(p => p.test(entry.name))) continue
+        walk(full)
+      } else if (entry.isFile()) {
+        const ext = extname(entry.name).toLowerCase()
+        if (ext !== '.py' && ext !== '.js' && ext !== '.ts') continue
+        try {
+          for (const p of extractMountPrefixes(full)) prefixes.add(p)
+        } catch {}
+      }
+    }
+  }
+  walk(dir)
+  return [...prefixes]
+}
+
 /**
  * 从目录递归扫描后端端点（多框架）。
  * 按扩展名分派：.py→FastAPI / .js,.ts→Express / .java→Spring。
@@ -149,16 +215,7 @@ export function extractSpringEndpoints(filePath) {
  * @returns {Array<{ method: string, path: string, source: string, line: number }>}
  */
 export function scanBackendEndpoints(dir, opts = {}) {
-  // 排除清单对齐 scanFrontendApiCalls（坑 parity-scan-stale-dirs：.claude/worktrees 陈旧检出
-  // 与各类 build 产物混入端点扫描全是噪音）——backend 侧另含 __pycache__/.gradle/maven target
-  const excludePatterns = opts.excludePatterns || [
-    /^__pycache__$/, /^node_modules$/, /^\.venv$/, /^venv$/, /^\.git$/, /^\.gradle$/,
-    /^\.claude$/, /^\.vscode$/, /^\.idea$/, /^\.cursor$/, /^\.next$/, /^\.nuxt$/,
-    /^\.output$/, /^\.turbo$/, /^\.parcel-cache$/, /^coverage$/,
-    /^\.sillyspec$/, /^\.worktrees$/, /^\.d\.ts$/,
-    /^(dist|build|target|out)$/i,
-    /test/i,
-  ]
+  const excludePatterns = opts.excludePatterns || BACKEND_DIR_EXCLUDE
 
   const results = []
   if (!existsSync(dir)) return results
@@ -323,16 +380,30 @@ export function normalizePath(rawPath) {
 // ─── 对账 ───────────────────────────────────────────────────────────────
 
 /**
- * 比较前端调用的路径和后端注册的端点，返回差异
+ * 比较前端调用的路径和后端注册的端点，返回差异。
+ *
+ * 挂载前缀对齐（坑 endpoints-mount-prefix-gap，2026-08-31 用户实证）：后端提取到的是
+ * 「router 自身前缀 + 装饰器路径」，不含挂载点前缀（main.py 的 include_router(prefix=)/
+ * app.use 与 router 文件分离，静态扫描不做导入图关联）→ 前端全路径调用（/api/xxx）对不上
+ * 欠前缀端点（/xxx）→ probe5 全量假 missing（17 个实证，人工定性成本高）。传入
+ * mountPrefixes 时前端调用路径按前缀集合逐个剥除生成候选，任一候选命中即匹配；原始路径
+ * 恒在候选集首位——装饰器自带全路径的仓（提取路径=真实路径）行为不变。
  *
  * @param {Array<{ path: string, method: string, source: string }>} frontendCalls
  * @param {Array<{ path: string, method: string, source: string }>} backendEndpoints
+ * @param {string[]} [mountPrefixes] 挂载前缀集合（scanMountPrefixes 收集）
  * @returns {{
  *   missingBackend: Array<{ path: string, method: string, consumerFile: string, consumerLine: number }>,
- *   unusedBackend: Array<{ path: string, method: string, providerFile: string }>
+ *   unusedBackend: Array<{ path: string, method: string, providerFile: string }>,
+ *   prefixAlignedCount: number,
+ *   ok: boolean
  * }}
  */
-export function diffApiParity(frontendCalls, backendEndpoints) {
+export function diffApiParity(frontendCalls, backendEndpoints, mountPrefixes = []) {
+  // 前缀降序（长的先剥）：/api/ppm 先于 /api，避免剥短前缀后路径失配
+  const prefixes = [...new Set((mountPrefixes || []).filter(p => p && p !== '/'))]
+    .sort((a, b) => b.length - a.length)
+
   // 构建 backend 注册表：归一化 path + method → endpoint
   const backendMap = new Map()
   for (const ep of backendEndpoints) {
@@ -341,27 +412,32 @@ export function diffApiParity(frontendCalls, backendEndpoints) {
   }
 
   const missingBackend = []
+  const frontendKeySet = new Set()
+  let prefixAlignedCount = 0
   for (const call of frontendCalls) {
-    const key = `${call.method}:${normalizePath(call.path)}`
-    if (!backendMap.has(key)) {
+    const base = normalizePath(call.path)
+    const candidates = [base]
+    for (const p of prefixes) {
+      if (base.startsWith(p + '/')) candidates.push(base.slice(p.length))
+    }
+    for (const c of candidates) frontendKeySet.add(`${call.method}:${c}`)
+    const matched = candidates.find(c => backendMap.has(`${call.method}:${c}`))
+    if (!matched) {
       missingBackend.push({
-        path: normalizePath(call.path),
+        path: base,
         method: call.method,
         consumerFile: call.source,
         consumerLine: call.line,
       })
+    } else if (matched !== base) {
+      prefixAlignedCount++
     }
   }
 
-  // 构建 frontend 调用表
-  const frontendSet = new Set(
-    frontendCalls.map(c => `${c.method}:${normalizePath(c.path)}`)
-  )
-
   const unusedBackend = []
   for (const ep of backendEndpoints) {
     const key = `${ep.method}:${normalizePath(ep.path)}`
-    if (!frontendSet.has(key)) {
+    if (!frontendKeySet.has(key)) {
       unusedBackend.push({
         path: normalizePath(ep.path),
         method: ep.method,
@@ -370,7 +446,7 @@ export function diffApiParity(frontendCalls, backendEndpoints) {
     }
   }
 
-  return { missingBackend, unusedBackend, ok: missingBackend.length === 0 }
+  return { missingBackend, unusedBackend, prefixAlignedCount, ok: missingBackend.length === 0 }
 }
 
 // ─── CLI 入口 ────────────────────────────────────────────────────────────
@@ -391,7 +467,9 @@ export async function contractScan(args, cwd) {
 
   const backendEndpoints = scanBackendEndpoints(backendDir)
   const frontendCalls = scanFrontendApiCalls(frontendDir)
-  const { missingBackend, unusedBackend } = diffApiParity(frontendCalls, backendEndpoints)
+  // 挂载前缀收集（坑 endpoints-mount-prefix-gap）：backend 根的挂载点（include_router/app.use）
+  const mountPrefixes = scanMountPrefixes(backendDir)
+  const { missingBackend, unusedBackend, prefixAlignedCount } = diffApiParity(frontendCalls, backendEndpoints, mountPrefixes)
 
   return {
     backend: backendEndpoints.map(e => ({ method: e.method, path: normalizePath(e.path), file: e.source })),
@@ -403,6 +481,7 @@ export async function contractScan(args, cwd) {
       frontendCallCount: frontendCalls.length,
       missingBackendCount: missingBackend.length,
       unusedBackendCount: unusedBackend.length,
+      prefixAlignedCount,
       ok: missingBackend.length === 0,
     },
   }

package/src/index.js

@@ -8,7 +8,7 @@
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'fs';
 import { writeAtomicSync } from './fs-atomic.js';
-import { basename, extname, join, resolve } from 'path';
+import { basename, dirname, extname, join, resolve, isAbsolute } from 'path';
 import { safeGit, git } from './git-helper.js';
 import { getVersion } from './version.js';
 
@@ -118,6 +118,8 @@ SillySpec CLI — 规范驱动开发工具包
                                       生成 Windows 安全 TaskCard 骨架（LF 行尾 + frontmatter 闭合 +
                                       硬校验 9 字段齐全，标题自动取自 plan.md，Edit 填占位符即可）
   sillyspec change-rename <旧变更名> <新变更名>
+  sillyspec change-delete <变更名> [--confirm]  删除变更（DB status='deleted' 与归档语义分离 +
+                                      移目录 + 清 worktree + 推平台墓碑；默认 dry-run）
   sillyspec knowledge <search --query "..." --limit N
                         | inspect --id "..."
                         | validate | refresh
@@ -127,6 +129,8 @@ SillySpec CLI — 规范驱动开发工具包
                       | sync [--change <name>] | sync-docs [--change <name>]
                       | status | pointer [--cleanup]
                       | approve <change> | reject <change> [--reason <r>]>
+  sillyspec pull --spec [--force]         拉取服务器 spec 快照到本地 .sillyspec（打包时刻
+                                          快照非实时、无自动同步；进度六表拉取用 platform pull）
   sillyspec docs migrate
   sillyspec dashboard [--port <N>] [--no-open]
 
@@ -147,6 +151,7 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec run plan --reopen --from-step 2          # 修订 plan，从第 2 步重做
   sillyspec run quick --non-interactive --done --output "CI 内的快修"  # 脚本/CI
   sillyspec progress show
+  sillyspec progress show --json        # 全局总览 envelope（面板/脚本消费）
   sillyspec worktree apply 2026-07-03-add-login
 `);
 }
@@ -262,6 +267,25 @@ async function main() {
     // QUAL-01 收口：原 execSync 字符串拼接（经 shell）→ git-helper 数组形式
     const r = safeGit(baseDir, ['rev-parse', '--show-toplevel'])
     if (r.value && existsSync(join(r.value, '.sillyspec'))) return r.value
+    // P1-1 第四层锚定（2026-09-02 跨 agent 工单）：.sillyspec 被 gitignore 的仓，linked worktree
+    // 内无 .sillyspec 副本 → 上面两级全 miss，返回 baseDir 会在 worktree 里新建分裂进度库
+    // （run 链路的 D-03 守卫只覆盖「有副本」场景、quick drift 守卫只覆盖「已有 session guard」
+    // 场景，均拦不住新会话）。判据与 worktree.js detectIsolation/_resolveMainRepoRoot 同源：
+    // --git-dir ≠ --git-common-dir 且非 submodule = linked worktree → common-dir 父目录即主仓根。
+    const gd = safeGit(baseDir, ['rev-parse', '--git-dir'])
+    const gcd = safeGit(baseDir, ['rev-parse', '--git-common-dir'])
+    const superProj = safeGit(baseDir, ['rev-parse', '--show-superproject-working-tree'])
+    if (gd.value && gcd.value && gd.value !== gcd.value && !superProj.value) {
+      // common-dir 可能是相对路径，须相对 baseDir 绝对化（与 worktree.js _resolveMainRepoRoot 同坑同解）
+      const absCommonDir = resolve(baseDir, gcd.value)
+      if (existsSync(absCommonDir)) {
+        const mainRoot = dirname(absCommonDir)
+        if (mainRoot !== baseDir && existsSync(join(mainRoot, '.sillyspec'))) {
+          console.warn(`⚠️ cwd 位于 linked worktree，进度库已自动锚定主仓：${mainRoot}（治 worktree 分裂进度库，P1-1）。如确要在 worktree 内独立建进度库，请显式 --spec-dir。`)
+          return mainRoot
+        }
+      }
+    }
     return baseDir
   }
 
@@ -302,9 +326,20 @@ async function main() {
           pm.init(progDir);
           break;
         case 'status':
-        case 'show':
+        case 'show': {
+          // --json：全局总览 envelope（machine-interface，2026-09-02 单一状态源）——多变更
+          // 列表 + 进度/ghost/stall 标记，供 SillyHub 面板 / 跨 agent 程序化消费（与 dump 的
+          // 单变更视角互补）。overview 是纯数据方法不发 console，stdout 直接留 JSON，无需劫持。
+          if (json) {
+            const { runStatusOverview } = await import('./machine-interface.js');
+            const { envelope, exitCode } = runStatusOverview({ cwd: progDir, specBase: resolvePlatformSpecDir(dir, specDir) });
+            console.log(JSON.stringify(envelope));
+            process.exitCode = exitCode;
+            break;
+          }
           pm.show(progDir, progChangeName);
           break;
+        }
         case 'check': {
           const result = pm.checkConsistency(progDir, progChangeName);
           // checkConsistency 只返回 {ok, issues, warnings}，不打印——必须在此输出，
@@ -414,7 +449,7 @@ async function main() {
           break;
         }
         default:
-          console.log('用法: sillyspec progress <init|show|validate|reset|set-stage|add-step|update-step|complete-stage|dump>');
+          console.log('用法: sillyspec progress <init|show|validate|reset|set-stage|add-step|update-step|complete-stage|dump>\n  show 支持 --json：全局总览 envelope（活跃变更列表 + 进度 + ghost/stall，面板/脚本消费）');
           process.exit(2);
       }
       break;
@@ -535,14 +570,14 @@ async function main() {
       // 缺失草稿，独立可随时跑（不必再 execute --done）。缺数据（无 tasks/ 目录 / 改动未 commit / 无 worktree meta）
       // 时 generateTaskReviewDrafts 提前返回 reason，如实打印不报错。
       // --adopt（2026-08-21 agent-手工产出审计项①）：已存在 review.json 的 mechanics 字段
-      // （schemaVersion/task/base/head/changedFiles/repo）一键重算代填，agent/子代理只写
+      // （schemaVersion/task/base/head/changedFiles/diffPaths/repo）一键重算代填，agent/子代理只写
       // verdict——手算 hash、手抄 diff 清单是纯错误面，gate 校验的恰是这些字段。与草稿互补：
       // 草稿补「缺失」，adopt 修「已存在但 mechanics 错/缺」，verdict 原样保留。
       const brChangeIdx = args.indexOf('--change');
       const brChange = brChangeIdx >= 0 && args[brChangeIdx + 1] ? args[brChangeIdx + 1] : null;
       const brAdopt = args.includes('--adopt');
       if (!brChange) {
-        console.error('用法: sillyspec backfill-reviews --change <name> [--adopt] [--json] [--spec-dir <path>]\n  缺失 review.json → 生成 cannot_verify 草稿（解 archive 客观完成度阻断）\n  --adopt → 已存在 review.json 的 base/head/changedFiles 等 mechanics 字段一键重算代填（verdict 保留）');
+        console.error('用法: sillyspec backfill-reviews --change <name> [--adopt] [--json] [--spec-dir <path>]\n  缺失 review.json → 生成 cannot_verify 草稿（解 archive 客观完成度阻断）\n  --adopt → 已存在 review.json 的 base/head/changedFiles/diffPaths 等 mechanics 字段一键重算代填（verdict 保留；统一 commit 模式 diffPaths=task 卡 allowed_paths）');
         process.exit(2);
       }
       // 与 run 入口同源消毒（防路径穿越；backfill 下游拼 marker/changes/review 路径）
@@ -911,7 +946,7 @@ async function main() {
       // 与 verifyApiParity 的聚合读侧（contract-artifacts/<change>/*/endpoints.json 全量并集）对齐。
       const epSub = filteredArgs[1];
       if (epSub !== 'extract') {
-        console.error('用法: sillyspec endpoints extract --change <name> [--task task-NN | --all-tasks] [--dir <backendRoot> | --files <a.py,b.js...>] [--spec-dir <path>]\n  静态扫描后端路由装饰器生成 endpoints.json（FastAPI/Express/Spring）；verify 探针 5 消费。\n  --all-tasks：聚合逐 task 卡 allowed_paths 各自提取（对账口径与探针 5 聚合读侧一致，推荐）');
+        console.error('用法: sillyspec endpoints extract --change <name> [--task task-NN | --all-tasks] [--dir <backendRoot> | --files <a.py,b.js...>] [--spec-dir <path>]\n  静态扫描后端路由装饰器生成 endpoints.json（FastAPI/Express/Spring）；verify 探针 5 消费。\n  --all-tasks：聚合逐 task 卡 allowed_paths 各自提取（对账口径与探针 5 聚合读侧一致，推荐）。\n  execute worktree 模式：allowed_paths 自动按 worktree 根解析，产物恒落主仓 spec（坑 endpoints-extract-worktree-pitfalls）');
         process.exit(2);
       }
       const epChangeIdx = args.indexOf('--change');
@@ -934,14 +969,44 @@ async function main() {
       assertSafeChangeName(epChange, '--change 变更名');
       const { extractFastApiEndpoints, extractExpressEndpoints, extractSpringEndpoints, scanBackendEndpoints } = await import('./endpoint-extractor.js');
       const endpoints = [];
-      const epSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+      let epSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+      // 坑 endpoints-extract-worktree-pitfalls ②（2026-08-29 实测）：CLI 在 execute worktree 内跑时
+      // spec 命中副本（worktree 内 checkout 出来的 .sillyspec）→ 产物落 worktree 自己的
+      // contract-artifacts/，主仓 verify 探针 5 读不到。复用 detectWorktreeSpecDrift 判据锚回
+      // 主仓 spec：产物落点恒主仓，扫描面（--dir/--files 绝对路径）不受影响。
+      const epDrift = (await import('./run/shared.js')).detectWorktreeSpecDrift(epSpecBase);
+      if (epDrift) {
+        console.log(`⚠️ 已自动锚定主仓 spec：${epDrift.mainSpecBase}（endpoints 产物落主仓；当前 cwd 命中 worktree 副本 ${epDrift.changeName}，流程继续）`);
+        epSpecBase = epDrift.mainSpecBase;
+      }
       const epChangeDir = join(epSpecBase, 'changes', epChange);
       if (!existsSync(epChangeDir)) {
         console.error(`❌ 变更目录不存在: ${epChangeDir}`);
         process.exit(1);
       }
+      // 坑 endpoints-extract-worktree-pitfalls ①（2026-08-29 实测 13 task 全 0 端点）：
+      // execute worktree 模式下变更代码只在 worktree 里，allowed_paths 按主仓（cwd）相对
+      // 解析 0 命中。活跃 worktree meta 存在时相对路径优先按 worktree 根解析——worktree =
+      // baseline 检出 + 本变更改动，扫描结果即交付态；不在 worktree 的文件回落主仓（显式
+      // --files 绝对路径原样通过）。WorktreeManager 从 worktree 内跑也会经 git-common-dir
+      // 锚定主仓 meta（构造器注释），meta 读取失败按无 worktree 处理不阻断。
+      let epWorktreeRoot = null;
+      try {
+        const { WorktreeManager } = await import('./worktree.js');
+        const epWtMeta = new WorktreeManager(dir).getMeta(epChange);
+        if (epWtMeta?.worktreePath && existsSync(epWtMeta.worktreePath)) epWorktreeRoot = epWtMeta.worktreePath;
+      } catch { /* meta 读取失败按无 worktree 处理 */ }
+      const resolveScoped = (p) => {
+        if (isAbsolute(p)) return p;
+        if (epWorktreeRoot) {
+          const inWt = join(epWorktreeRoot, p);
+          if (existsSync(inWt)) return inWt;
+        }
+        return resolve(p);
+      };
+      if (epWorktreeRoot) console.log(`ℹ️  变更有活跃 worktree，扫描面优先按其根解析：${epWorktreeRoot}`);
       const collectFile = (f) => {
-        const abs = resolve(f)
+        const abs = resolveScoped(f)
         if (!existsSync(abs)) return
         const ext = extname(abs).toLowerCase()
         try {
@@ -984,7 +1049,7 @@ async function main() {
           const taskName = card.replace(/\.md$/, '')
           const eps = []
           const perFile = (f) => {
-            const abs = resolve(f)
+            const abs = resolveScoped(f)
             if (!existsSync(abs)) return
             const ext = extname(abs).toLowerCase()
             try {
@@ -1019,10 +1084,10 @@ async function main() {
         }
         let scanned = 0
         for (const p of candidates) {
-          const abs = join(dir, p)
+          const abs = resolveScoped(p)
           if (!existsSync(abs)) continue
           scanned++
-          collectFile(p)
+          collectFile(abs)
         }
         if (candidates.size === 0) {
           console.error('❌ 无扫描面：--task 卡无 allowed_paths 且 design.md 无具体文件清单——显式传 --dir <backendRoot> 或 --files <a.py,b.js>，或用 --all-tasks 聚合逐卡提取');
@@ -1205,7 +1270,7 @@ async function main() {
             docsCheckFlags.push(a);
           }
         }
-        const { runDocsCheck, readDocsCheckConfig, DocsCheckConfigError, applyFixes } = await import('./docs-check.js');
+        const { runDocsCheck, readDocsCheckConfig, DocsCheckConfigError, applyFixes, runChangeNameAdvisory } = await import('./docs-check.js');
         try {
           // 配置优先级：--paths > local.yaml docs-check.paths > 缺省 docs/**/*.md
           const cfg = readDocsCheckConfig(dir);
@@ -1236,10 +1301,20 @@ async function main() {
             }
           }
           const fixResult = fixActive ? applyFixes(dir, fixes, dryRun ? { dryRun: true } : {}) : null;
+          // 变更名提名 advisory（2026-08-31 变更关联审计 P2）：铁律同决策规则族——只 warn，
+          // 不进 invalid、不影响下方 exit code 与 docs gate。降级容错：advisory 自身异常
+          // 不拖垮主检查（try-catch 吞并提示）。
+          let changeNameReport = null;
+          try {
+            changeNameReport = runChangeNameAdvisory({ projectRoot: dir });
+          } catch (e) {
+            console.warn(`⚠️ 变更名提名检查执行失败（advisory 降级跳过）：${e.message}`);
+          }
           if (json) {
             // --fix 与 --json 组合保持 stdout 纯 JSON 可解析（constraints）：修复统计作 result.fixReport
             // 附加后整体 stringify，主体仍是 runDocsCheck 返回（invalid[].fix 是 task-01 设计内增量）
             if (fixResult) result.fixReport = { applied: fixResult.applied, skipped: fixResult.skipped.length, dryRun };
+            if (changeNameReport) result.changeNameReport = changeNameReport;
             console.log(JSON.stringify(result, null, 2));
           } else {
             for (const w of result.warnings) console.warn(`⚠️  ${w}`);
@@ -1278,6 +1353,16 @@ async function main() {
               console.error(`\n修复指引：行号漂移 → 更新文档行号到当前源码；文件删改名 → 更新引用路径；`);
               console.error(`关键词缺失但行号正确 → 确认符号是否改名，改文档 token 或行号。`);
             }
+            // 变更名提名 advisory 段（主结果之后、exit 之前；不参与 ok/invalid 与 exit code）。
+            // 零输出原则（docs-check-fix 契约：无新 flag 时 stdout 逐字节一致；决策规则族同款
+            // 「无信号零输出」）：仅 findings 非空才输出——悬空即信号，无悬空不打扰。
+            if (changeNameReport && changeNameReport.findings.length > 0) {
+              console.warn(`⚠️ 变更名提名悬空 ${changeNameReport.findings.length}/${changeNameReport.mentions} 处（advisory 不阻断、不进 docs gate）：`);
+              for (const f of changeNameReport.findings) console.warn(`   - ${f.message}`);
+              if (changeNameReport.exempted.length > 0) {
+                console.log(`ℹ️ 另有 ${changeNameReport.exempted.length} 处经 known_failures change-name.* 键豁免`);
+              }
+            }
           }
           // exit code（design §5.2 行为矩阵逐字对齐）：全绿 → 0（--fix 无操作）；--fix 后全部
           // fixable 修复完且无 needs-manual 残留 → 0；仍有 needs-manual 或写回 skipped → 1；
@@ -2142,6 +2227,9 @@ SillySpec platform — SillyHub 平台同步
   sillyspec platform pointer [--cleanup]
   sillyspec platform approve <change-name>
   sillyspec platform reject <change-name> [--reason <reason>]
+
+注: platform pull 拉的是进度六表（多机进度同步）；拉取 spec 文件整树快照请用
+    sillyspec pull --spec（X2，打包时刻快照非实时）。
 `);
         break;
       }
@@ -2504,6 +2592,53 @@ checkbox 行；depends_on 自动反填行内注解 "(depends_on: task-01,02)"；
       pm.renameChange(dir, oldName, newName);
       break;
     }
+    case 'change-delete': {
+      // 2026-08-30 用户反馈①：一等删除路径——此前删变更靠 git rm + 借道幽灵清理，
+      // 且幽灵清理把删除行写成 archived，DB 无法区分归档与删除。两段式（默认 dry-run）。
+      // 变更名：位置参数（对齐 change-rename）或 --change（对齐 gate/derive）二选一。
+      let delName = filteredArgs[1];
+      if (!delName || delName.startsWith('-')) {
+        const idx = filteredArgs.indexOf('--change');
+        if (idx >= 0 && filteredArgs[idx + 1]) delName = filteredArgs[idx + 1];
+      }
+      if (!delName || delName.startsWith('-')) {
+        console.error('❌ 用法: sillyspec change-delete <变更名> [--confirm]（或 --change <变更名>）');
+        process.exitCode = 2;
+        break;
+      }
+      const delConfirm = filteredArgs.includes('--confirm');
+      const { deleteChange } = await import('./change-delete.js');
+      const r = await deleteChange({
+        cwd: dir,
+        specDir: resolvePlatformSpecDir(dir, specDir),
+        changeName: delName,
+        confirm: delConfirm,
+      });
+      if (json) {
+        console.log(JSON.stringify(r, null, 2));
+      } else if (!r.ok) {
+        console.error(`❌ ${r.reason}`);
+      } else if (r.action === 'dry_run') {
+        console.log(`🗑️  变更 ${delName} 待删除（dry-run，未执行）：`);
+        if (r.db_row) console.log(`   DB 行：status=${r.db_row.status}${r.already_deleted ? '（已删除，本次仅清残留）' : ` → deleted（与 archived 语义分离，审计可直接区分）`}`);
+        else console.log('   DB 行：无（孤儿目录，仅删目录）');
+        if (r.dir) console.log(`   目录：${r.dir.path}（${r.dir.files} 个文件，git tracked 文件可从历史回溯）`);
+        else console.log('   目录：不存在（仅 DB 行翻 deleted——取代 git rm 后借道幽灵清理的老路径）');
+        if (r.worktree) {
+          console.log(`   worktree：${r.worktree.mode}${r.worktree.unappliedChanges > 0
+            ? `（⚠️ ${r.worktree.unappliedChanges} 个未 apply 变更——删除时保留 worktree 不丢代码，确认废弃后手动 cleanup）`
+            : '（将一并清理）'}`);
+        }
+        console.log(`\n加 --confirm 执行删除（DB status='deleted' + 移除目录 + 清理 worktree + 暂存 git 删除 + 推平台墓碑）。`);
+      } else {
+        console.log(`🗑️  变更 ${delName} 已删除：`);
+        if (r.db_updated) console.log(`   ✅ DB status='deleted'（与 archived 语义分离，审计可直接区分）`);
+        if (r.dir_removed) console.log(`   ✅ 目录已移除（${r.files_removed} 个文件，git 历史可回溯）`);
+        for (const w of r.warnings || []) console.log(`   ⚠️ ${w}`);
+      }
+      process.exitCode = r.ok ? 0 : 1;
+      break;
+    }
     case 'workflow': {
       const wfSub = filteredArgs[1];
       if (!wfSub || wfSub === 'help' || wfSub === '--help') {
@@ -2936,8 +3071,68 @@ SillySpec config — local.yaml 配置键速查
       }
       break;
     }
+    case 'pull': {
+      // X2（task-14 / design §7.1 §7.4 / FR-07 / FR-08）：拉取服务器 spec 整树快照。
+      // 注意与 platform pull（进度六表 DB import，多机进度同步）语义正交——本命令操作
+      // .sillyspec 文件树；命名 pull --spec 显式区分，防误用。
+      const pullSpecArgs = filteredArgs.slice(1);
+      const pullWantsHelp = pullSpecArgs.length === 0
+        || pullSpecArgs.includes('help') || pullSpecArgs.includes('--help') || pullSpecArgs.includes('-h');
+      const pullWantsSpec = pullSpecArgs.includes('--spec');
+      const printPullSpecHelp = () => console.log(`
+SillySpec pull — 拉取服务器 spec 快照到本地（X2 / FR-07）
+
+用法:
+  sillyspec pull --spec [--force]
+
+说明:
+  从 SillyHub 平台拉取当前工作区的 .sillyspec 整树快照（tar 解压到 specDir，
+  含 tar 顶层 PLATFORM-BUNDLE.json 快照元数据，可离线辨认快照新旧）。
+  覆盖语义：specDir 为空 → 直接解压；非空 → 必须加 --force 整树替换
+  （先删除本地整棵 .sillyspec 再解包——.runtime（进度 DB）等本地文件会一并丢失；
+  --force 保留连接凭据 local.yaml（服务端 bundle 恒排除它），覆盖后无需重新 connect；
+  崩溃安全：覆盖前凭据先备份为 .sillyspec.local.yaml.bak，成功后自动清理，
+  中途失败可从该备份文件恢复）。
+
+  ⚠️ 快照语义：拉取的是服务器「打包时刻」的快照，非实时镜像——
+     本命令不自动同步、不在会话中自动刷新；拉取后本地的改动仍需正常推送。
+     daemon 模式下任务/会话开始时会按 spec_version 自动取新，无需手动跑本命令。
+
+  拉取进度六表（多机进度同步）请用：sillyspec platform pull [--change <name>]
+`);
+      if (pullWantsHelp || !pullWantsSpec) {
+        printPullSpecHelp();
+        if (!pullWantsHelp) {
+          console.error('❌ 缺少 --spec（本命令拉取 spec 整树快照；进度六表拉取用 sillyspec platform pull）');
+          process.exit(1);
+        }
+        break;
+      }
+
+      const pullSpecForce = pullSpecArgs.includes('--force');
+      const syncModule = await import('./sync.js');
+      // 未连接明确提示不崩（对齐 platform pull :2289 先例）
+      const smForSpecPull = new syncModule.SyncManager(dir);
+      if (!smForSpecPull._getPlatform()) {
+        console.error('❌ 未连接平台，请先 sillyspec platform connect');
+        process.exit(1);
+      }
+      const specR = await syncModule.pullSpecBundle(dir, { force: pullSpecForce, specDir });
+      if (specR.ok && specR.pulled) {
+        console.log(`✅ 已拉取 spec 快照 → ${specR.specDir}${specR.specVersion ? `（平台 spec_version: ${specR.specVersion}）` : ''}`);
+        console.log('   快照语义：打包时刻快照非实时，无自动同步；本地后续改动仍需正常推送。');
+      } else if (/非空/.test(specR.reason || '')) {
+        console.error(`❌ ${specR.reason}`);
+        console.error('   确认整树替换请加 --force（先删除本地 .sillyspec 整树再解包，进度 DB 等本地文件一并丢失；连接凭据 local.yaml 保留，无需重新 connect）');
+        process.exit(1);
+      } else {
+        console.error(`❌ 拉取 spec 快照失败: ${specR.reason || '未知'}`);
+        process.exit(1);
+      }
+      break;
+    }
     default: {
-      const topCommands = ['init', 'setup', 'run', 'progress', 'worktree', 'dispatch', 'agent-log', 'local', 'workflow', 'gate', 'derive', 'backfill-reviews', 'register-stage-review', 'modules', 'change-rename', 'knowledge', 'platform', 'scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore', 'status', 'doctor', 'auto', 'runtime'];
+      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'];
       const suggestion = didYouMean(command, topCommands);
       console.error(`❌ 未知命令: ${command}`);
       if (command === '--status') {