sillyspec 3.27.9 → 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/commit-suggest.js

@@ -71,6 +71,28 @@ function classifyStagePath(p) {
   return null
 }
 
+/**
+ * 暂存区快照（坑 same-main-staging-pollution，2026-08-28 用户实证：同 main 两个活跃会话
+ * 共享同一暂存区，A 的 commit 把 B 暂存的文件扫入——本轮竞态事故根因，无任何防护）。
+ * 防护 = 提交前可见：commit 提示里带 `git diff --cached --name-only` 快照 + 他者文件告警。
+ * @param {{ cwd: string, ownFiles?: string[]|null }} opts
+ *   ownFiles：本会话/本变更的精确文件集（apply-pathspec 等）；提供时对快照做差集，
+ *   不在集内的暂存文件 = 他者会话暂存（告警对象）。null/空数组 = 只出快照不做归属判定。
+ * @returns {{ available: boolean, staged: string[], foreign: string[] }}
+ *   available=false：git 不可用/非仓库（调用方静默跳过，不误报）。
+ */
+export function collectStagedArea({ cwd, ownFiles = null }) {
+  const raw = gitQuiet(cwd, ['diff', '--cached', '--name-only'])
+  if (raw === null) return { available: false, staged: [], foreign: [] }
+  const staged = raw.split('\n').filter(Boolean).map(f => f.replace(/\\/g, '/'))
+  let foreign = []
+  if (Array.isArray(ownFiles) && ownFiles.length > 0) {
+    const own = new Set(ownFiles.map(f => String(f).replace(/\\/g, '/')))
+    foreign = staged.filter(f => !own.has(f))
+  }
+  return { available: true, staged, foreign }
+}
+
 /**
  * 收集提交上下文并生成建议 message。
  * @param {{ cwd: string, specDir?: string|null }} opts

package/src/contract-matrix.js

@@ -392,10 +392,13 @@ export function _readWorktreeMeta(specBase, scanRoot, changeName) {
 
 /**
  * 取本变更 diff 文件集（parity 前端调用收窄用，坑 probe5-fullrepo-frontend-noise）。
- * 优先 worktree meta 锚点 diff（与 verify 同源）；无 meta 退主仓 git diff HEAD。
+ * 优先 worktree meta 锚点 diff（与 verify 同源）；无 meta 退主仓 git diff HEAD；
+ * 两者皆空再退 apply-pathspec-<change>.txt（apply 落盘的精确清单）。
+ * 兜底链每级都空才返回 null/[]（调用方回退全仓——坑 probe5-single-task-artifact-scope，
+ * 2026-08-28 实证：apply+commit/cleanup 后 diff 为空 → 全仓调用 × 局部端点 = 150 条假 missing）。
  * @returns {string[]|null}
  */
-function _resolveDiffFilesForParity(specBase, scanRoot, changeName) {
+function _resolveDiffFilesForParity(specBase, scanRoot, changeName, runtimeRoot) {
   try {
     const wt = _readWorktreeMeta(specBase, scanRoot, changeName)
     if (wt) {
@@ -429,7 +432,20 @@ function _resolveDiffFilesForParity(specBase, scanRoot, changeName) {
     if (foreign.length > 0) {
       console.warn(`⚠️ parity 对账已排除 ${foreign.length} 个并行会话声明的文件（${foreign.slice(0, 5).map(x => x.file).join(', ')}${foreign.length > 5 ? ' 等' : ''}）`)
     }
-    return own
+    if (own.length > 0) return own
+    // 主仓 diff 空（apply 后已 commit / cleanup 完毕）→ apply-pathspec 兜底：apply 成功时落盘的
+    // 本变更精确文件清单（与 gates 归因提示②同源）。仍拿不到才回 null（调用方退全仓）。
+    try {
+      const pathspecFile = join(runtimeRoot || join(specBase, '.runtime'), `apply-pathspec-${changeName}.txt`)
+      if (existsSync(pathspecFile)) {
+        const fromPathspec = readFileSync(pathspecFile, 'utf8').split('\n').map(l => l.trim()).filter(Boolean)
+        if (fromPathspec.length > 0) {
+          console.log(`ℹ️ parity 前端范围用 apply-pathspec 兜底（主仓 diff 为空，${fromPathspec.length} 文件）`)
+          return fromPathspec
+        }
+      }
+    } catch { /* 兜底失败 → null 交调用方全仓 */ }
+    return null
   } catch { return null }
 }
 
@@ -526,7 +542,7 @@ export function verifyApiParity(specBase, scanRoot, runtimeRoot, changeName = nu
   const frontendRootLabel = frontendRoot === scanRoot ? 'scan-root' : 'worktree'
   if (changeName) {
     try {
-      const changed = _resolveDiffFilesForParity(specBase, scanRoot, changeName)
+      const changed = _resolveDiffFilesForParity(specBase, scanRoot, changeName, runtimeRoot)
       if (changed && changed.length > 0) {
         const changedSet = new Set(changed.map(f => f.replace(/\\/g, '/')))
         frontendCalls = scanFrontendApiCalls(frontendRoot).filter(c => {

package/src/decision-distill.js

@@ -22,7 +22,7 @@
  * 零输出：无 decisions.md 或无入选条目 → skipped 带原因，不写任何文件、不动 INDEX。
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { basename, dirname, join } from 'node:path'
 
 /** FR-02：有实现影响的五类 type（scope 与未知 type 的 confirmed/accepted 不入选） */
 const IMPLEMENTED_TYPES = new Set(['architecture', 'compatibility', 'boundary', 'definition', 'process'])
@@ -244,10 +244,14 @@ function newDomainPreamble(domain) {
   ]
 }
 
-/** 单条目段落渲染（design 接口定义的条目格式，逐字对齐：状态/锚点/最近确认/理由 + rejected 专属两行） */
-function renderBlockLines(entry, headHash, supersedesNote) {
+/** 单条目段落渲染（design 接口定义的条目格式，逐字对齐：状态/锚点/最近确认/理由 + rejected 专属两行）。
+ * 变更：行（2026-08-28，坑 distill-cross-change-supersede）：D-xxx 编号是变更内局部序号，
+ * 跨变更同号（两个 D-002）互不相干——条目必须携带变更名限定，消费方（knowledge-match/
+ * docs-check 的字段行解析）只认各自标签，新增字段行是增量安全。 */
+function renderBlockLines(entry, headHash, supersedesNote, changeName) {
   const lines = [`## ${entry.id} ${oneLine(entry.title)}`.replace(/\s+$/, '')]
   lines.push(`状态：${entry.selected}`)
+  if (changeName) lines.push(`变更：${oneLine(changeName)}`)
   lines.push(`锚点：${oneLine(entry.anchor) || NOT_RECORDED}`)
   lines.push(`最近确认：${oneLine(headHash) || NOT_RECORDED}`)
   lines.push(`理由：${oneLine(entry.answer || entry.normalizedRequirement || entry.question)}`)
@@ -259,7 +263,9 @@ function renderBlockLines(entry, headHash, supersedesNote) {
   return lines
 }
 
-/** 知识文件切段：preamble 行 + D-xxx@vN 条目段（段边界 = 下一 `## D-` 头） */
+/** 知识文件切段：preamble 行 + D-xxx@vN 条目段（段边界 = 下一 `## D-` 头）。
+ * 段的变更归属取段内 `变更：<name>` 行；无该行的历史条目 → change=null（legacy：
+ * 升级前落库的条目，不参与新条目的同号匹配/supersede——只共存不误删）。 */
 function splitKnowledgeSections(content) {
   const sections = []
   const preamble = []
@@ -275,7 +281,11 @@ function splitKnowledgeSections(content) {
     else preamble.push(line)
   }
   if (cur) sections.push(cur)
-  for (const s of sections) s.id = `${s.number}@v${s.version}`
+  for (const s of sections) {
+    s.id = `${s.number}@v${s.version}`
+    const cm = s.lines.find(l => /^变更[：:]/.test(l))
+    s.change = cm ? cm.replace(/^变更[：:]\s*/, '').trim() || null : null
+  }
   return { preamble, sections }
 }
 
@@ -293,15 +303,20 @@ function joinKnowledgeFile(preamble, sections) {
 
 /**
  * 单条目写入一个域文件的段落集（就地修改 sections）。
- * @returns {{ action: 'append'|'update'|'supersede' }|null} null = 高版本已落库，迟到低版本不降级。
+ * 坑 distill-cross-change-supersede（2026-08-28 用户实证：跨变更同号 D-002 在 knowledge
+ * 里互相 supersede）：幂等键从「号」改为「号+变更」——同号匹配、版本守卫、旧版本段清除
+ * 全部限定在 entry.change 内；他者变更的同号段不参与（共存）。legacy 段（change=null，
+ * 升级前落库）不与任何新条目互认，只共存不误删。
+ * @returns {{ action: 'append'|'update'|'supersede' }|null} null = 同变更同号高版本已落库，迟到低版本不降级。
  */
 function applyEntryToSections(sections, entry, headHash) {
-  const sameNumber = sections.filter(s => s.number === entry.number)
+  const change = entry.change || null
+  const sameNumber = sections.filter(s => s.number === entry.number && (s.change || null) === change)
   if (sameNumber.some(s => s.version > entry.version)) return null
   let action
   let supersedesNote = oneLine(entry.supersedes) || null
   if (sameNumber.length === 0) {
-    sections.push({ number: entry.number, version: entry.version, id: entry.id, title: entry.title, lines: renderBlockLines(entry, headHash, supersedesNote) })
+    sections.push({ number: entry.number, version: entry.version, id: entry.id, title: entry.title, change, lines: renderBlockLines(entry, headHash, supersedesNote, change || undefined) })
     action = 'append'
   } else {
     const same = sameNumber.find(s => s.version === entry.version)
@@ -309,10 +324,10 @@ function applyEntryToSections(sections, entry, headHash) {
     if (!same && !supersedesNote) supersedesNote = `${slot.number}@v${slot.version}`
     slot.version = entry.version
     slot.title = entry.title
-    slot.lines = renderBlockLines(entry, headHash, supersedesNote)
-    // 同号旧版本段（< 新版本）就地清除——同文件内同号只留一个段
+    slot.lines = renderBlockLines(entry, headHash, supersedesNote, change || undefined)
+    // 同变更同号旧版本段（< 新版本）就地清除——同文件内同变更同号只留一个段
     for (let i = sections.length - 1; i >= 0; i--) {
-      if (sections[i].number === entry.number && sections[i] !== slot) sections.splice(i, 1)
+      if (sections[i].number === entry.number && (sections[i].change || null) === change && sections[i] !== slot) sections.splice(i, 1)
     }
     action = same ? 'update' : 'supersede'
   }
@@ -412,6 +427,9 @@ function syncIndexRoutingLines(knowledgeRoot) {
  *   缺否决理由/复潮条件被拦下（该条目未写盘，其余条目照常提炼）。
  */
 export function distillIntoKnowledge(changeDir, knowledgeRoot, headHash, moduleIndex = null) {
+  // 变更名限定（坑 distill-cross-change-supersede）：条目幂等键 = 号+变更。changeDir 末段
+  // 即变更名（changes/<name> 与 archive 后的 changes/archive/<name> 同为 <name>）。
+  const changeName = basename(changeDir)
   const parsed = parseDecisions(changeDir)
   if (parsed.missing) {
     return { written: [], skipped: `decisions.md 不存在（${join(changeDir, 'decisions.md')}），零输出`, needsWait: null }
@@ -450,7 +468,7 @@ export function distillIntoKnowledge(changeDir, knowledgeRoot, headHash, moduleI
   const taken = new Set()
   for (const e of distillable) {
     const keep = highestByNumber.get(e.number)
-    if (keep && !taken.has(e.number)) { taken.add(e.number); batch.push(keep) }
+    if (keep && !taken.has(e.number)) { taken.add(e.number); keep.change = changeName; batch.push(keep) }
   }
 
   const decisionsDir = join(knowledgeRoot, 'decisions')
@@ -489,7 +507,8 @@ export function distillIntoKnowledge(changeDir, knowledgeRoot, headHash, moduleI
     }
   }
 
-  // 跨文件清理：同号 ≤ 新版本的旧段散落其他域文件时移除（同号全局只留最高版本/目标文件）
+  // 跨文件清理：同变更同号 ≤ 新版本的旧段散落其他域文件时移除（同变更同号全局只留最高
+  // 版本/目标文件）；他者变更的同号段不参与（共存，坑 distill-cross-change-supersede）
   let onDisk = []
   try { onDisk = readdirSync(decisionsDir).filter(f => f.endsWith('.md')).map(f => f.replace(/\.md$/, '')) } catch { /* 刚创建，走 store */ }
   const allDomains = [...new Set([...onDisk, ...store.keys()])]
@@ -498,7 +517,7 @@ export function distillIntoKnowledge(changeDir, knowledgeRoot, headHash, moduleI
     for (const d of allDomains) {
       if (targets.has(d)) continue
       const st = loadDomain(d)
-      const removed = st.sections.filter(s => s.number === entry.number && s.version <= entry.version)
+      const removed = st.sections.filter(s => s.number === entry.number && s.version <= entry.version && (s.change || null) === (entry.change || null))
       if (removed.length === 0) continue
       st.sections = st.sections.filter(s => !removed.includes(s))
       st.dirty = true

package/src/docs-check.js

@@ -630,10 +630,20 @@ function extractKnownFailureKeys(yamlText) {
   if (inline) {
     return inline[1].split(',').map(s => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean)
   }
-  const block = yaml.match(/^known_failures:\s*\n((?:[ \t]+-[ \t].+\n?)+)/m)
+  // 坑 verify-known-failures-comment-line-truncation 同款（与 verify-postcheck.extractKnownFailures
+  // 口径互指对齐）：块内注释行/空行打断连续列表项捕获链 → 注释后的键静默丢失。块定义放行
+  // 注释行与空行；提取侧只认 - 项行；行尾注释须 # 前有空白（裸 # 不截）；引号值原样保留。
+  const block = yaml.match(/^known_failures:\s*\n((?:[ \t]+-[ \t].+\n?|[ \t]*#[^\n]*\n?|[ \t]*\n)+)/m)
   if (block) {
     return (block[1].match(/^[ \t]+-[ \t]+(.+)/gm) || [])
-      .map(s => s.replace(/^[ \t]+-[ \t]+/, '').trim().replace(/^['"]|['"]$/g, '').replace(/#.*$/, '').trim())
+      .map(s => {
+        const item = s.replace(/^[ \t]+-[ \t]+/, '').trim()
+        const full = item.match(/^(['"])(.*)\1$/)
+        if (full) return full[2]
+        const stripped = item.replace(/[ \t]+#.*$/, '').trim()
+        const q2 = stripped.match(/^(['"])(.*)\1$/)
+        return q2 ? q2[2] : stripped
+      })
       .filter(Boolean)
   }
   return []
@@ -823,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) })