sillyspec 3.27.9 → 3.27.12

package/src/facade-hint.js

@@ -0,0 +1,170 @@
+/**
+ * facade-hint.js — plan 门「透传必经文件」候选探测（advisory）。
+ *
+ * 坑 plan-facade-files-manual-backfill（2026-08-28 用户实证 ×2）：facade 文件（如
+ * daemon/service.py——新端点/新模块必须在它里面挂载/转发才对外生效）不进 design §6 /
+ * TaskCard allowed_paths，执行期子代理按现实改它 → apply Gate1 拦截 → 人工回补
+ * allowed_paths 两轮。本模块在 plan 完成时做静态引用扫描，把候选透传/聚合文件提前
+ * 亮给 agent（warning 不阻断）：判定是语义，agent 拍板补不补。
+ *
+ * 两个信号（语言覆盖 py/js/ts/mjs/cjs/jsx/tsx/java 的 import/require 静态文本匹配）：
+ *   - direct：仓内文件 import 了 allowed_paths 里的模块（改被 facade 引用的模块，
+ *     facade 常需同步改——转发签名/挂载点）；
+ *   - aggregate：仓内文件 import 了该模块同目录下 ≥2 个模块（聚合器/注册表形态，
+ *     新增同目录模块几乎必然要在此登记——service.py 挂 router 即此形态）。
+ *
+ * 启发式 → 恒 advisory：候选只列不改，由 agent 判定补 allowed_paths / design §6，
+ * 或确认无关忽略。性能护栏：allowed 条目 > 100 或仓内源码文件 > 5000 时静默跳过。
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
+import { join, dirname, basename, extname, resolve } from 'path'
+
+const SOURCE_EXTS = new Set(['.py', '.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs', '.java'])
+const SKIP_DIRS = new Set([
+  '.git', 'node_modules', 'dist', 'build', 'out', '.next', '__pycache__',
+  '.venv', 'venv', 'env', '.sillyspec', '.worktrees', '.claude', '.runtime',
+  'coverage', 'target', '.idea', '.vscode',
+])
+const MAX_ALLOWED_ENTRIES = 100
+const MAX_REPO_FILES = 5000
+const MAX_FILE_BYTES = 512 * 1024
+
+const toPosix = (p) => String(p).replace(/\\/g, '/')
+
+/** 递归收集仓内源码文件（posix 相对路径），带总量护栏。 */
+function walkSourceFiles(root, out = []) {
+  if (out.length > MAX_REPO_FILES) return out
+  let names
+  try { names = readdirSync(root) } catch { return out }
+  for (const name of names) {
+    if (SKIP_DIRS.has(name)) continue
+    const abs = join(root, name)
+    let st
+    try { st = statSync(abs) } catch { continue }
+    if (st.isDirectory()) walkSourceFiles(abs, out)
+    else if (st.isFile() && SOURCE_EXTS.has(extname(name).toLowerCase()) && st.size <= MAX_FILE_BYTES) {
+      out.push(toPosix(join(root, name)))
+      if (out.length > MAX_REPO_FILES) return out
+    }
+  }
+  return out
+}
+
+/** 从源码文本提取 import/require 说明符（py dotted + js/ts path-ish）。 */
+export function extractImportSpecifiers(text, ext) {
+  const specs = new Set()
+  if (ext === '.py') {
+    // from X import a, b → 记 pkg 本身 + 逐名拼 'X.a'/'X.b'（前者保 from X.y import sym 的
+    // 直接引用形态，后者保 service.py 聚合挂载形态：from daemon.routers import users, orders）
+    for (const m of text.matchAll(/\bfrom\s+([.\w]+)\s+import\s+([^\n#]+)/g)) {
+      specs.add(m[1])
+      const names = m[2].split(',')
+        .map(s => s.trim().split(/\s+as\s+/i)[0].trim())
+        .filter(n => /^\w+$/.test(n))
+      for (const n of names) specs.add(`${m[1]}.${n}`)
+    }
+    for (const m of text.matchAll(/(?:^|\n)\s*import\s+([\w.]+)/g)) specs.add(m[1])
+  } else if (ext === '.java') {
+    for (const m of text.matchAll(/\bimport\s+([\w.]+)\s*;/g)) specs.add(m[1])
+  } else {
+    for (const m of text.matchAll(/(?:from\s+|require\(\s*|import\(\s*)['"]([^'"]+)['"]/g)) specs.add(m[1])
+  }
+  return [...specs]
+}
+
+/** 说明符是否指向模块名 mod（`m` / `pkg.m` / `./m` / `../d/m` 等尾部命中形态）。 */
+export function specRefsModule(spec, mod) {
+  if (!spec || !mod) return false
+  if (spec === mod) return true
+  return spec.endsWith('.' + mod) || spec.endsWith('/' + mod)
+}
+
+/**
+ * 探测 allowed_paths 之外的 facade/聚合候选文件。
+ *
+ * @param {{ cwd: string, allowedPaths: string[] }} opts
+ * @returns {{ skipped: boolean, reason: string|null, candidates: Array<{file: string, via: string[]}> }}
+ */
+export function findFacadeCandidates({ cwd, allowedPaths }) {
+  const root = cwd || process.cwd()
+  const allowed = (allowedPaths || []).map(toPosix).filter(p => !p.includes('*'))
+  if (allowed.length === 0) return { skipped: true, reason: 'no-allowed-paths', candidates: [] }
+  if (allowed.length > MAX_ALLOWED_ENTRIES) return { skipped: true, reason: 'allowed-too-many', candidates: [] }
+
+  const files = walkSourceFiles(root)
+  if (files.length > MAX_REPO_FILES) return { skipped: true, reason: 'repo-too-large', candidates: [] }
+
+  const allowedSet = new Set(allowed)
+  const isAllowed = (abs) => allowed.some(a => abs === a || abs.endsWith('/' + a) || a.endsWith('/' + abs) || abs.replace(/\.[^.]+$/, '') === a.replace(/\.[^.]+$/, ''))
+
+  // 目录 → 该目录下模块名索引（聚合信号用：R import 同目录 ≥2 模块 = 聚合器）
+  const dirModules = new Map()
+  for (const f of files) {
+    const d = dirname(f)
+    if (!dirModules.has(d)) dirModules.set(d, new Set())
+    dirModules.get(d).add(basename(f, extname(f)))
+  }
+
+  // 预读一遍源码 import（file → specs），两信号共用
+  const fileSpecs = []
+  for (const f of files) {
+    if (isAllowed(f)) continue
+    let text
+    try { text = readFileSync(f, 'utf8') } catch { continue }
+    fileSpecs.push({ file: f, specs: extractImportSpecifiers(text, extname(f).toLowerCase()) })
+  }
+
+  // 逐 allowed 文件探测 direct + aggregate 命中
+  const byFile = new Map()
+  for (const p of allowed) {
+    const mod = basename(p, extname(p))
+    // allowed 是相对仓根路径，目录索引键是绝对路径（walk 产物）——resolve 对齐再查
+    const dirKey = toPosix(resolve(root, dirname(p)))
+    const dirLabel = toPosix(dirname(p))
+    const dirModSet = dirModules.get(dirKey) || new Set()
+    for (const { file, specs } of fileSpecs) {
+      const via = []
+      if (specs.some(s => specRefsModule(s, mod))) via.push(`direct import of ${mod}`)
+      // aggregate：R 引用 mod 同目录 ≥2 个不同仓内模块（mod 自身可不在——新增模块形态）
+      const hitMods = new Set()
+      for (const s of specs) {
+        for (const b of dirModSet) {
+          if (specRefsModule(s, b)) { hitMods.add(b); break }
+        }
+      }
+      if (hitMods.size >= 2) via.push(`aggregates ≥2 modules of ${dirLabel === '.' ? './' : dirLabel + '/'}`)
+      if (via.length === 0) continue
+      const existing = byFile.get(file) || []
+      for (const v of via) if (!existing.includes(v)) existing.push(v)
+      byFile.set(file, existing)
+    }
+  }
+  const candidates = [...byFile.entries()]
+    .map(([file, via]) => ({ file: toPosix(file), via }))
+    .sort((a, b) => a.file.localeCompare(b.file))
+  return { skipped: false, reason: null, candidates }
+}
+
+/**
+ * plan 门消费入口：探测 + 打印（advisory，不阻断）。allowed 集与 apply Gate1 同源
+ * （resolveApplyAllowSet 的主仓切片），确保「预检亮出的候选」与「执行期会拦的门」
+ * 用同一份清单口径。
+ */
+export function warnFacadeCandidateFiles({ cwd, changeName, allowSet }) {
+  try {
+    const r = findFacadeCandidates({ cwd, allowedPaths: [...(allowSet || [])] })
+    if (r.skipped || r.candidates.length === 0) return r
+    console.warn(`\n⚠️  plan 预检：${r.candidates.length} 个 allowed_paths 外的「透传/聚合」候选文件（advisory，不阻断）：`)
+    for (const c of r.candidates.slice(0, 10)) {
+      console.warn(`   - ${c.file}（${[...new Set(c.via)].join('; ')}）`)
+    }
+    if (r.candidates.length > 10) console.warn(`   …还有 ${r.candidates.length - 10} 个`)
+    console.warn('   若属「透传必经文件」（facade 转发/路由挂载/注册登记——改 allowed 模块必须同步改它才生效）：')
+    console.warn('   现在补进对应 TaskCard allowed_paths 或 design §6 清单，避免执行期 apply Gate1 拦截后手工回补；')
+    console.warn('   确认无关则忽略。执行期有据越界另有出口（review.json 声明 changedFiles，apply 有审计放行）。')
+    return r
+  } catch (e) {
+    console.warn(`⚠️  facade 候选探测失败（advisory 跳过）: ${e.message}`)
+    return { skipped: true, reason: 'error', candidates: [] }
+  }
+}

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';
 
@@ -98,7 +98,7 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec commit [--json]                 智能提交建议：收集 QUICKLOG/已勾 task/阶段产出语义，生成建议 message（只建议不执行）
   sillyspec verify-probes --change <name> [--init]  verify 机械探针（TODO 标记/测试覆盖/API 对账/删除对账）；--init 生成 verify-result.md 骨架
   sillyspec module-impact --change <name>       生成 module-impact.md 骨架（文件×模块归属按 module-map 预填 + 未匹配清单）
-  sillyspec endpoints extract --change <name> [--task task-NN] [--dir <dir>|--files <a.py,b.js>]  静态扫描路由装饰器生成 endpoints.json
+  sillyspec endpoints extract --change <name> [--task task-NN | --all-tasks] [--dir <dir>|--files <a.py,b.js>]  静态扫描路由装饰器生成 endpoints.json
   sillyspec scan-fix-headers [--project <名>]   scan 文档补 author/created_at header（幂等）
   sillyspec plan-adopt-waves --change <名> [--dry-run]   plan.md Wave 段一键重排为 depends_on 拓扑分组（同步任务总表 W 列，幂等）
   sillyspec workspace add <名> <路径> [--role] [--repo] | remove <名> | status   多项目工作区登记与状态探测
@@ -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]
 
@@ -743,6 +747,20 @@ async function main() {
       }
       console.log(`📦 待提交变更（${cc.changedCount} 个文件${cc.untrackedCount > 0 ? `，其中未跟踪 ${cc.untrackedCount} 个` : ''}；上方 stat 仅列已跟踪文件的改动）`);
       if (cc.stat) console.log(cc.stat.split('\n').map(l => '   ' + l).join('\n'));
+      // 暂存区快照（坑 same-main-staging-pollution，2026-08-28 实证：同 main 双会话共享暂存区，
+      // A 的 commit 扫入 B 暂存的文件）：git commit 只含暂存内容——提交前把快照亮出来供核对。
+      {
+        const { collectStagedArea } = await import('./commit-suggest.js');
+        const staged = collectStagedArea({ cwd: dir });
+        if (staged.available && staged.staged.length > 0) {
+          console.log(`\n📌 暂存区快照（git diff --cached --name-only，你的下一次 git commit 将恰好含这 ${staged.staged.length} 个文件）：`);
+          for (const f of staged.staged.slice(0, 15)) console.log(`   - ${f}`);
+          if (staged.staged.length > 15) console.log(`   … 共 ${staged.staged.length} 个`);
+          console.log(`   ⚠️ 同 main 并行会话共享同一暂存区——快照里非本会话的文件请先 git restore --staged <file> 剔除，否则会被你的 commit 扫入`);
+        } else if (staged.available) {
+          console.log(`\n📌 暂存区为空（git commit 前需先 git add；用 pathspec 级 add 防扫入无关文件）`);
+        }
+      }
       if (cc.quickEntries.length > 0) {
         console.log(`\n📝 QUICKLOG（上次提交 ${cc.lastCommitTime || '（无）'} 之后 ${cc.quickEntries.length} 条）：`);
         for (const q of cc.quickEntries) {
@@ -892,15 +910,19 @@ async function main() {
       // 此前靠 agent 手扫装饰器手写（易漏 endpoint）。CLI 复用 endpoint-extractor 全套提取器
       // （FastAPI @router.* / Express router.* / Spring @*Mapping）静态扫描生成，
       // verify 探针 5（verifyApiParity）直接消费该产物。
+      // --all-tasks（坑 probe5-single-task-artifact-scope，2026-08-28 实证：单 task 产物对账
+      // 产生大量假 missing）：聚合模式——逐 task 卡提取，各自落 contract-artifacts/<change>/<task>/，
+      // 与 verifyApiParity 的聚合读侧（contract-artifacts/<change>/*/endpoints.json 全量并集）对齐。
       const epSub = filteredArgs[1];
       if (epSub !== 'extract') {
-        console.error('用法: sillyspec endpoints extract --change <name> [--task task-NN] [--dir <backendRoot> | --files <a.py,b.js...>] [--spec-dir <path>]\n  静态扫描后端路由装饰器生成 endpoints.json（FastAPI/Express/Spring）；verify 探针 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');
       const epChange = epChangeIdx >= 0 && args[epChangeIdx + 1] ? args[epChangeIdx + 1] : null;
       const epTaskIdx = args.indexOf('--task');
       const epTask = epTaskIdx >= 0 && args[epTaskIdx + 1] ? args[epTaskIdx + 1] : null;
+      const epAllTasks = args.includes('--all-tasks');
       const epDirIdx = args.indexOf('--dir');
       const epDir = epDirIdx >= 0 && args[epDirIdx + 1] ? args[epDirIdx + 1] : null;
       const epFilesIdx = args.indexOf('--files');
@@ -909,17 +931,51 @@ async function main() {
         console.error('❌ 缺 --change <变更名>');
         process.exit(2);
       }
+      if (epAllTasks && (epTask || epDir || epFilesRaw)) {
+        console.error('❌ --all-tasks 与 --task/--dir/--files 互斥（聚合模式逐 task 卡自动取 allowed_paths）');
+        process.exit(2);
+      }
       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 {
@@ -928,10 +984,56 @@ async function main() {
           else if (ext === '.java') endpoints.push(...extractSpringEndpoints(abs))
         } catch { /* 单文件解析失败不阻断整体 */ }
       }
+      // 单 task 产物写盘（taskName 归属目录）；返回提取数
+      const epRuntimeRoot = (await import('./run/shared.js')).resolveRuntimeRoot({ specRoot: specDir }, epSpecBase);
+      const writeArtifact = (taskName, eps) => {
+        const artifact = {
+          generated_at: new Date().toISOString().slice(0, 19).replace('T', ' '),
+          generator: 'sillyspec endpoints extract',
+          endpoints: eps.map(e => ({ method: e.method, path: e.path, source: e.source })),
+        }
+        const epOutDir = join(epRuntimeRoot, 'contract-artifacts', epChange, taskName);
+        mkdirSync(epOutDir, { recursive: true });
+        const epOutPath = join(epOutDir, 'endpoints.json');
+        writeFileSync(epOutPath, JSON.stringify(artifact, null, 2) + '\n');
+        return epOutPath;
+      }
       if (epDir) {
-        endpoints.push(...scanBackendEndpoints(resolve(epDir)))
+        endpoints.push(...scanBackendEndpoints(resolve(epDir)));
       } else if (epFilesRaw) {
         for (const f of epFilesRaw.split(',').map(s => s.trim()).filter(Boolean)) collectFile(f)
+      } else if (epAllTasks) {
+        // 聚合模式：逐 task 卡 allowed_paths 提取，各自落产物目录（对齐 verifyApiParity 聚合读侧）
+        const { parseAllowedPaths } = await import('./stages/plan-postcheck.js')
+        const tasksDir = join(epChangeDir, 'tasks')
+        const taskCards = existsSync(tasksDir)
+          ? readdirSync(tasksDir).filter(f => /^task-[\w.-]+\.md$/.test(f)).sort()
+          : []
+        if (taskCards.length === 0) {
+          console.error(`❌ --all-tasks 无 task 卡（${tasksDir} 不存在或无 task-*.md）——先跑 plan 生成 TaskCard`);
+          process.exit(1);
+        }
+        let total = 0
+        for (const card of taskCards) {
+          const taskName = card.replace(/\.md$/, '')
+          const eps = []
+          const perFile = (f) => {
+            const abs = resolveScoped(f)
+            if (!existsSync(abs)) return
+            const ext = extname(abs).toLowerCase()
+            try {
+              if (ext === '.py') eps.push(...extractFastApiEndpoints(abs))
+              else if (ext === '.js' || ext === '.ts') eps.push(...extractExpressEndpoints(abs))
+              else if (ext === '.java') eps.push(...extractSpringEndpoints(abs))
+            } catch { /* 单文件解析失败不阻断整体 */ }
+          }
+          for (const p of parseAllowedPaths(readFileSync(join(tasksDir, card), 'utf8'))) perFile(p)
+          const outPath = writeArtifact(taskName, eps)
+          total += eps.length
+          console.log(`ℹ️  ${taskName}: ${eps.length} 个端点 → ${outPath}`)
+        }
+        console.log(`✅ 聚合提取完成：${taskCards.length} 个 task 卡共 ${total} 个端点（探针 5 对账时全量并集消费）`);
+        break;
       } else {
         // 默认扫描面：task 卡 allowed_paths ∪ design §6 清单里的具体源码文件
         const { parseFileChangeListDetailed } = await import('./change-list.js')
@@ -951,28 +1053,19 @@ 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>');
+          console.error('❌ 无扫描面：--task 卡无 allowed_paths 且 design.md 无具体文件清单——显式传 --dir <backendRoot> 或 --files <a.py,b.js>，或用 --all-tasks 聚合逐卡提取');
           process.exit(1);
         }
         console.log(`ℹ️  扫描 ${scanned}/${candidates.size} 个清单文件（不存在的跳过）`);
       }
-      const artifact = {
-        generated_at: new Date().toISOString().slice(0, 19).replace('T', ' '),
-        generator: 'sillyspec endpoints extract',
-        endpoints: endpoints.map(e => ({ method: e.method, path: e.path, source: e.source })),
-      }
-      const epRuntimeRoot = (await import('./run/shared.js')).resolveRuntimeRoot({ specRoot: specDir }, epSpecBase);
-      const epOutDir = join(epRuntimeRoot, 'contract-artifacts', epChange, epTask || 'scan');
-      mkdirSync(epOutDir, { recursive: true });
-      const epOutPath = join(epOutDir, 'endpoints.json');
-      writeFileSync(epOutPath, JSON.stringify(artifact, null, 2) + '\n');
-      console.log(`✅ 提取 ${endpoints.length} 个端点 → ${epOutPath}`);
+      const outPath = writeArtifact(epTask || 'scan', endpoints);
+      console.log(`✅ 提取 ${endpoints.length} 个端点 → ${outPath}`);
       console.log(`   verify 阶段探针 5（API 契约对账）自动消费该产物；FastAPI/Express/Spring 装饰器均支持。`);
       break;
     }
@@ -1146,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);
@@ -1177,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}`);
@@ -1219,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；
@@ -1719,6 +1832,20 @@ SillySpec worktree — git worktree 隔离管理
                 console.log(`   git add --pathspec-from-file="${result.pathspecFile}"`);
               }
               console.log(`   （完整清单 ${result.commitPathspec.length} 个文件已存 ${result.pathspecFile}，可 --pathspec-from-file 复用）`);
+              // 他者暂存差集（坑 same-main-staging-pollution）：暂存区已有非本变更文件时，
+              // 普通 git commit 会把它们一并扫入——提交前亮出来。pathspec 级 commit
+              // （git commit -m <msg> -- <paths>）只提交指定路径、不动他者暂存，双出口都给。
+              try {
+                const { collectStagedArea } = await import('./commit-suggest.js');
+                const stagedNow = collectStagedArea({ cwd: dir, ownFiles: result.commitPathspec });
+                if (stagedNow.available && stagedNow.foreign.length > 0) {
+                  console.warn(`\n⚠️  暂存区已有 ${stagedNow.foreign.length} 个非本变更文件（很可能为他者并行会话暂存，普通 git commit 会扫入）：`);
+                  for (const f of stagedNow.foreign.slice(0, 10)) console.warn(`   - ${f}`);
+                  if (stagedNow.foreign.length > 10) console.warn(`   … 共 ${stagedNow.foreign.length} 个`);
+                  console.warn(`   推荐用 pathspec 级 commit（不动他者暂存）：git commit -m "<msg>" --pathspec-from-file="${result.pathspecFile}"`);
+                  console.warn(`   或先剔除：git restore --staged -- <文件>（工作区内容不丢，对方可重新 add）`);
+                }
+              } catch { /* 暂存区快照失败不影响 apply 结果展示 */ }
             }
           }
           if (result.warnings && result.warnings.length > 0) {
@@ -2069,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;
       }
@@ -2431,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') {
@@ -2863,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') {