sillyspec 3.27.11 → 3.27.12

package/src/change-delete.js

@@ -0,0 +1,181 @@
+/**
+ * change-delete.js — 变更删除命令（2026-08-30 用户反馈①）
+ *
+ * 背景：此前删除一个变更要靠「git rm 目录 + 借道 doctor --cleanup-ghosts 清 DB 行」两步，
+ * 且幽灵清理把删除行的 status 写成 archived——DB 无法区分「流程正常收尾的归档」与
+ * 「中途废弃的删除」，事后审计只能回溯 git。
+ *
+ * 本命令提供一等删除路径：
+ *   - DB：status='deleted'（与 archived 语义分离，DB 可直接审计区分，行保留不物理删）
+ *   - 目录：changes/<name>/ 物理移除（git tracked 文件删除后照常 commit，历史仍可回溯）
+ *   - worktree：复用 archiveWorktreeCleanup（有未 apply 变更时保留 worktree 只警告——
+ *     不因删变更丢用户唯一副本的代码；顺带清 execute/stage-review runId marker）
+ *   - git：safeGit add -A 暂存目录删除（best-effort，对齐 archive CLI 下沉 git add）
+ *   - 平台：triggerSync 推终态（sync.js 对 status='deleted' 上行墓碑，平台收敛软删）
+ *
+ * 两段式安全（对齐 --cleanup-remnant / --cleanup-ghosts / --align-execute-progress 家族）：
+ * 默认 dry-run 只报告将发生什么，--confirm 才执行。
+ *
+ * 执行序（DB-first + 失败补偿，对齐 renameChange 的回滚模式）：DB 翻 deleted → 删目录，
+ * 目录删除失败则把 DB 行翻回原 status，避免「目录还在但行已 deleted」的分裂态。
+ */
+import { existsSync, readdirSync, rmSync, statSync } from 'fs';
+import { join, relative } from 'path';
+import { safeGit } from './git-helper.js';
+import { assertSafeChangeName, triggerSync } from './run/shared.js';
+import { archiveWorktreeCleanup } from './run/complete-handlers.js';
+
+function countFiles(dir) {
+  let n = 0;
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return 0; }
+  for (const e of entries) {
+    if (e.isDirectory()) n += countFiles(join(dir, e.name));
+    else n++;
+  }
+  return n;
+}
+
+/**
+ * 探测变更的 worktree 状态（dry-run 也报——「删了会不会丢代码」是关键决策信息）。
+ * meta 缺失 / 探测失败 → null（无 worktree），不阻断。
+ */
+async function probeWorktree(cwd, changeName) {
+  try {
+    const { WorktreeManager } = await import('./worktree.js');
+    const wm = new WorktreeManager({ cwd });
+    const meta = wm.getMeta(changeName);
+    if (!meta) return null;
+    const info = { mode: meta.mode || null, worktreePath: meta.worktreePath || null, unappliedChanges: 0 };
+    if (meta.mode !== 'in-place-fallback') {
+      const check = wm.hasUnappliedChanges(changeName);
+      if (check && check.hasChanges) info.unappliedChanges = (check.changedFiles || []).length;
+    }
+    return info;
+  } catch { return null; }
+}
+
+/**
+ * 删除变更（两段式）。
+ * @param {{cwd: string, specDir?: string|null, changeName: string, confirm?: boolean}} opts
+ * @returns {Promise<{ok: boolean, reason?: string, action?: 'dry_run'|'deleted', change?: string,
+ *   db_row?: {status: string, current_stage: string|null, last_active: string|null}|null,
+ *   dir?: {path: string, files: number}|null, worktree?: object|null,
+ *   db_updated?: boolean, dir_removed?: boolean, files_removed?: number, warnings?: string[]}>}
+ */
+export async function deleteChange({ cwd, specDir = null, changeName, confirm = false }) {
+  if (!changeName) return { ok: false, reason: '缺少变更名（sillyspec change-delete <名> 或 --change <名>）' };
+  try {
+    assertSafeChangeName(changeName, '变更名');
+  } catch (e) {
+    return { ok: false, reason: e.message };
+  }
+
+  const { ProgressManager } = await import('./progress.js');
+  const pm = new ProgressManager({ specDir: specDir || null });
+  const specBase = specDir || join(cwd, '.sillyspec');
+  const dirPath = join(specBase, 'changes', changeName);
+
+  // 只读探测 DB 行（不存在 DB 时 _ensureDB 会建空库——先探目录避免为纯孤儿目录凭空建库）
+  const dirExists = existsSync(dirPath);
+  let row = null;
+  if (dirExists || existsSync(join(specBase, '.runtime', 'sillyspec.db')) || existsSync(join(specBase, 'sillyspec.db'))) {
+    try {
+      const sqlDb = pm._ensureDB(cwd).getDb();
+      const r = sqlDb.prepare('SELECT name, status, current_stage, last_active FROM changes WHERE name = ?').get(changeName);
+      if (r !== undefined) row = { status: r.status, current_stage: r.current_stage, last_active: r.last_active };
+    } catch (e) {
+      return { ok: false, reason: `读取进度库失败：${e.message}` };
+    }
+  }
+
+  if (!row && !dirExists) {
+    return { ok: false, reason: `变更 ${changeName} 不存在（DB 无行且目录缺失）` };
+  }
+  if (row && row.status === 'archived') {
+    return {
+      ok: false,
+      reason: `变更 ${changeName} 已是归档态（archived）——change-delete 面向活跃/残留变更；归档历史如需清理请直接处理 changes/archive/ 目录（git 层操作）`,
+    };
+  }
+  const alreadyDeleted = row && row.status === 'deleted';
+  if (alreadyDeleted && !dirExists) {
+    return { ok: false, reason: `变更 ${changeName} 已是删除态（deleted）且无残留目录，无需重复删除` };
+  }
+
+  const dirFiles = dirExists ? countFiles(dirPath) : 0;
+  const worktreeInfo = await probeWorktree(cwd, changeName);
+
+  if (!confirm) {
+    return {
+      ok: true, action: 'dry_run', change: changeName,
+      db_row: row, dir: dirExists ? { path: dirPath, files: dirFiles } : null,
+      worktree: worktreeInfo,
+      already_deleted: alreadyDeleted,
+    };
+  }
+
+  const warnings = [];
+  // 1. DB 翻 deleted（已是 deleted 的残留目录清理跳过——幂等）
+  let dbUpdated = false;
+  if (row && !alreadyDeleted) {
+    try {
+      pm.deleteChange(cwd, changeName);
+      dbUpdated = true;
+    } catch (e) {
+      return { ok: false, reason: `更新进度库失败：${e.message}` };
+    }
+  }
+  // 2. 删目录（失败回滚 DB，对齐 renameChange 的补偿模式）
+  if (dirExists) {
+    try {
+      rmSync(dirPath, { recursive: true, force: true });
+    } catch (e) {
+      if (dbUpdated) {
+        try {
+          const sqlDb = pm._ensureDB(cwd).getDb();
+          sqlDb.prepare('UPDATE changes SET status = ? WHERE name = ?').run(row.status, changeName);
+        } catch (re) {
+          warnings.push(`目录删除失败且 DB 回滚也失败（状态分裂，跑 sillyspec doctor --json 排查）：${re.message}`);
+        }
+      }
+      return { ok: false, reason: `删除目录失败：${e.message}`, warnings };
+    }
+  }
+  // 3. worktree 清理（archiveWorktreeCleanup 内建「未 apply 变更保留」护栏，不丢代码）
+  try {
+    await archiveWorktreeCleanup(cwd, changeName, specBase, {});
+  } catch (e) {
+    warnings.push(`worktree 清理失败（不阻断删除）：${e.message}`);
+  }
+  // 4. git 暂存目录删除（best-effort：非 git 仓 / specBase 在仓外时跳过，git status 照常可见）
+  try {
+    const relDir = relative(cwd, dirPath).split('\\').join('/');
+    if (relDir && !relDir.startsWith('../')) {
+      safeGit(cwd, ['add', '-A', '--', relDir]);
+    }
+  } catch { /* 非 git 仓等场景：删除在 git status 可见，暂存非必需 */ }
+  // 5. 平台终态/墓碑上行（triggerSync 内建 8s 熔断 + 未连接静默；change-delete 是终态
+  //    一次性命令，await 保证墓碑发出后再退出，输出顺序确定）
+  try {
+    await triggerSync(cwd, changeName, { specRoot: specBase });
+  } catch (e) {
+    warnings.push(`平台终态同步失败（不阻断删除，下次常规同步重试）：${e.message}`);
+  }
+  // 6. 审计留痕（破坏性操作，对齐 complete-stage --force 的审计口径）
+  try {
+    pm._appendAuditLog(cwd, {
+      action: 'change-delete',
+      change: changeName,
+      db_status_before: row ? row.status : null,
+      dir_removed: dirExists,
+      files_removed: dirFiles,
+    });
+  } catch { /* 审计失败不阻断 */ }
+
+  return {
+    ok: true, action: 'deleted', change: changeName,
+    db_updated: dbUpdated, dir_removed: dirExists, files_removed: dirFiles,
+    worktree: worktreeInfo, warnings,
+  };
+}

package/src/docs-check.js

@@ -833,3 +833,129 @@ export async function runDecisionRules(opts) {
   exempted.sort((a, b) => a.key.localeCompare(b.key))
   return { empty: false, domains: domainFiles.length, entries: entriesTotal, implemented: implementedTotal, threshold, findings, exempted }
 }
+
+// ---------------------------------------------------------------------------
+// 变更名提名规则族（advisory，2026-08-31 变更关联审计 P2）
+//
+// 校验对象：文档正文里提名的变更名 token（`2026-NN-NN-<slug>`）。背景实测：变更间关联
+// 的真实形态是散文提名（全仓 265 处他者提名，85% 属实质依赖/溯源/叙事），而非路径链接
+// 或声明式字段；提名当前完全不受校验——拼错、归档改名（历史 3 单）后静默烂掉没人发现。
+// 规则单一：提名的名字在「活跃 ∪ 归档」变更名单中存在；不存在 = 悬空。
+// 铁律（与决策规则族同款，docs-consistency 模块卡）：advisory 只 warn 不进 runDocsCheck
+// 的 invalid 阻断链——ok/invalid 判定、exit code、docs gate 阻断行为均不受影响；只读零写盘。
+// 豁免走 known_failures `change-name.<名字>` 键（decisions.* 同款机制）：prompt 模板示例名、
+// 跨仓变更名（repo:// 语义但散文书写）按名豁免，披露不隐藏。
+// 结构化排除（非豁免，正则层面）：
+//   - lookbehind [A-Za-z0-9-]：x- 前缀化合物不拆半名（review-2026-08-08.md 文档名、
+//     brainstorm-review-2026-08-23-205426 run-id 时间戳、双日期前缀目录名整体不命中）；
+//   - slug 字母开头：纯数字 slug（HHMMSS 时间戳类）不命中；
+//   - ql-* quicklog id 不是变更目录名，天然不命中（quick 关联另有 CLI 悬空守卫）。
+// ---------------------------------------------------------------------------
+
+/** 缺省扫描集：主链路 docs 两侧 + 变更文档。强制 skip 追加 archive/（归档文档是冻结
+ *  历史事实，当时提名不追改）与 docs/prompt/（agent 指令模板，示例变更名 by-design 虚构） */
+export const CHANGE_NAME_DEFAULT_PATHS = ['docs/**/*.md', '.sillyspec/docs/**/*.md', '.sillyspec/changes/**/*.md']
+const CHANGE_NAME_FORCED_SKIP = ['.sillyspec/changes/archive', 'docs/prompt']
+
+/** 变更名 token：日期前缀 + 字母开头 slug（≥3 字符） */
+const CHANGE_NAME_TOKEN_RE = /(?<![A-Za-z0-9-])(\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]{2,})/g
+
+/**
+ * 纯函数：提取文本里的变更名提名 token（matchAll 对共享 /g 正则内部克隆，无 lastIndex 竞态）。
+ * 紧随 `.md` 的 token 排除——那是文件名提及（.sillyspec/plans/ 计划快照、他仓 docs 路径），
+ * 不是变更目录提名（目录提名后随 `/` 或独立成词）。
+ * @param {string} text 行文本或全文
+ * @returns {string[]} 名字列表（含重复，调用方自行聚合计数）
+ */
+export function collectChangeNameTokens(text) {
+  const md = String(text || '')
+  return [...md.matchAll(CHANGE_NAME_TOKEN_RE)]
+    .filter(m => md.slice(m.index + m[0].length, m.index + m[0].length + 3).toLowerCase() !== '.md')
+    .map(m => m[1])
+}
+
+/**
+ * 变更名单收集：活跃目录 ∪ 归档目录（+ 调用方注入额 extraNames，如 DB 名单——DB 与目录
+ * 历史上曾分叉，并集口径防假阳性）。目录缺失 → 跳过不抛。
+ * @param {string} specBase 规范根（<root>/.sillyspec 或平台 specRoot）
+ * @param {string[]} [extraNames]
+ * @returns {Set<string>}
+ */
+export function collectKnownChangeNames(specBase, extraNames = []) {
+  const names = new Set()
+  for (const sub of ['changes', join('changes', 'archive')]) {
+    try {
+      for (const e of readdirSync(join(specBase, sub), { withFileTypes: true })) {
+        if (e.isDirectory()) names.add(e.name)
+      }
+    } catch { /* 目录缺失 → 跳过 */ }
+  }
+  for (const n of extraNames) if (n && typeof n === 'string') names.add(n)
+  return names
+}
+
+/**
+ * IO 入口（advisory）：扫文档集报告悬空的变更名提名。不进 invalid 阻断链、不写盘。
+ * @param {{ projectRoot: string, specBase?: string|null, paths?: string[]|null, skip?: string[]|null,
+ *   knownFailures?: string[]|null, extraNames?: string[] }} opts
+ *   paths 缺省 CHANGE_NAME_DEFAULT_PATHS（与主链路不同：多扫 .sillyspec/changes/——变更
+ *   design/proposal 是实质依赖提名的主阵地）；skip 缺省读 local.yaml 并强制追加
+ *   .sillyspec/changes/archive；knownFailures 缺省读 local.yaml known_failures
+ * @returns {{ empty: boolean, scannedDocs: number, mentions: number, uniqueNames: number,
+ *   findings: Array<{ doc: string, docLine: number, name: string, message: string }>,
+ *   exempted: Array<{ key: string, name: string }> }}
+ */
+export function runChangeNameAdvisory(opts) {
+  const { projectRoot, specBase = null, paths = null, skip = null, knownFailures = null, extraNames = [] } = opts || {}
+  const emptyResult = { empty: true, scannedDocs: 0, mentions: 0, uniqueNames: 0, findings: [], exempted: [] }
+  if (!projectRoot) return emptyResult
+
+  const cfg = readDocsCheckConfig(projectRoot)
+  const globs = paths || cfg.paths || CHANGE_NAME_DEFAULT_PATHS
+  const skipList = [...(skip || cfg.skip || []), ...CHANGE_NAME_FORCED_SKIP]
+  let failures = knownFailures
+  if (!Array.isArray(failures)) {
+    try {
+      failures = extractKnownFailureKeys(readFileSync(join(projectRoot, '.sillyspec', 'local.yaml'), 'utf8'))
+    } catch { failures = [] }
+  }
+
+  // 名单口径：本仓活跃∪归档 ∪ 调用方注入（如 DB 名）∪ 跨仓根（docs-check.cross_repo_roots
+  // 已配置的兄弟仓——散文跨仓提名无 repo:// 标记，出现在任一已配置根的变更名录即有效；
+  // 未配置根不参与，与 repo:// 行号校验的「未配映射跳过」同语义）
+  const known = collectKnownChangeNames(specBase || join(projectRoot, '.sillyspec'), extraNames)
+  for (const root of Object.values(cfg.crossRepoRoots || {})) {
+    for (const n of collectKnownChangeNames(join(root, '.sillyspec'))) known.add(n)
+  }
+
+  const docs = new Set()
+  for (const g of globs) for (const rel of walkGlob(projectRoot, g, skipList)) docs.add(rel)
+
+  const findings = []
+  const exempted = []
+  const seenNames = new Set()
+  let mentions = 0
+  let scanned = 0
+  for (const rel of [...docs].sort()) {
+    let lines
+    try { lines = readFileSync(join(projectRoot, rel), 'utf8').replace(/\r\n?/g, '\n').split('\n') } catch { continue }
+    scanned++
+    lines.forEach((line, i) => {
+      for (const name of collectChangeNameTokens(line)) {
+        mentions++
+        seenNames.add(name)
+        if (known.has(name)) continue
+        if (failures.includes(`change-name.${name}`)) {
+          exempted.push({ key: `change-name.${name}`, name })
+          continue
+        }
+        findings.push({
+          doc: rel, docLine: i + 1, name,
+          message: `[${rel}:L${i + 1}] 提名「${name}」在活跃∪归档变更名单中不存在——拼错 / 改名未同步 / 他仓变更？确认后修正，或在 local.yaml known_failures 加 "change-name.${name}" 豁免（advisory 不阻断）`,
+        })
+      }
+    })
+  }
+  findings.sort((a, b) => a.doc.localeCompare(b.doc) || a.docLine - b.docLine || a.name.localeCompare(b.name))
+  return { empty: scanned === 0, scannedDocs: scanned, mentions, uniqueNames: seenNames.size, findings, exempted }
+}

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) })

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, 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]
 
@@ -911,7 +915,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 +938,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 +1018,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 +1053,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 +1239,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 +1270,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 +1322,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 +2196,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 +2561,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 +3040,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') {