sillyspec 3.27.11 → 3.28.0

package/.claude/skills/sillyspec-execute/SKILL.md

@@ -92,7 +92,7 @@ execute 完成时，每个 task 必须有 `review.json` 且 verdict 通过，否
 
 > 🔧 **mechanics 字段不要手算**：`schemaVersion`/`task`/`base`/`head`/`changedFiles`(/跨仓 `repo`) 全部可由 CLI 从 git + task 卡推导。子代理/你只需写**语义字段**（`specVerdict`/`qualityVerdict`/`reviewerNotes`/`requiredEvidence`），mechanics 字段可以瞎填占位（如 `"base": "TODO"`），写完跑 `sillyspec backfill-reviews --change <变更名> --adopt` 一键重算代填（verdict 原样保留）。gate 拦下 mechanics 错误时也跑同一条命令修复。
 
-- 后端 router task 另需产出 API 端点清单：`sillyspec endpoints extract --change <变更名> --all-tasks`（聚合逐 task 卡 allowed_paths 提取，与 verify 探针 5 聚合对账口径一致；单 task 可 `--task task-NN`，也可 `--dir`/`--files` 显式指定）。勿手扫装饰器手写——易漏 endpoint；勿只提单 task——局部端点集对账放大假 missing。
+- 后端 router task 另需产出 API 端点清单：`sillyspec endpoints extract --change <变更名> --task <task-NN>`（CLI 静态扫描 FastAPI/Express/Spring 路由装饰器生成 endpoints.json，verify 探针 5 消费；扫描面默认取 task 卡 allowed_paths ∪ design 清单，也可 `--dir`/`--files` 显式指定）。勿手扫装饰器手写——易漏 endpoint。
 
 ### Stage Review Gate（execute 末尾的 acceptance review.json）
 

package/README.md

@@ -41,9 +41,9 @@ npx sillyspec init
 
 | 工具 | `--tool` | 产物位置 |
 |---|---|---|
-| Claude Code（推荐） | `claude` | `.claude/skills/sillyspec-*/` |
+| Claude Code（推荐） | `claude` | `AGENTS.md`（完整指引）+ `CLAUDE.md`（`@AGENTS.md` 指针）+ `.claude/skills/sillyspec-*/` |
 | Cursor | `cursor` | `.cursor/skills/sillyspec-*/` |
-| OpenAI Codex | `codex` | `AGENTS.md` |
+| OpenAI Codex | `codex` | `AGENTS.md`（完整指引） |
 | OpenCode | `opencode` | `INSTRUCTIONS.md` |
 | OpenClaw | `openclaw` | `.openclaw/skills/sillyspec-*/` |
 | Gemini | `gemini` | `GEMINI.md` |
@@ -128,6 +128,7 @@ sillyspec init                   初始化（零交互，自动检测工具）
 sillyspec setup                  安装推荐 MCP 工具（交互式）
 sillyspec setup --list           查看已安装 MCP 状态
 sillyspec doctor                 全量自检 + 修复进度
+sillyspec change-delete <变更名>    删除变更（DB status=deleted 与归档语义分离；默认 dry-run，--confirm 执行）
 ```
 
 ## 核心特性

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.27.11",
+  "version": "3.28.0",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/agent-session-log.js

@@ -18,7 +18,11 @@
  *   - codex：无可靠 env 标记，按 mtime 活跃窗口扫 <home>/.codex/sessions/YYYY/MM/DD/
  *       rollout-*.jsonl，读首行 session_meta.cwd 精确匹配 CLI cwd（并带出 originator，
  *       如 sillyhub-daemon，供平台关联派发来源）
- *   - zcode：env ZCODE_* 门控；<home>/.zcode/cli/rollout/model-io-sess_<id>.jsonl
+ *   - zcode：env ZCODE_* 门控；<home>/.zcode/cli/rollout/model-io-sess_<id>.jsonl（含
+ *       subagent 会话，文件名带 sess_subagent_agent_ 前缀）。rollout 目录全局共享（所有
+ *       ZCode 窗口/项目混居），读首块系统提示词工作目录标记与 cwd 精确匹配——主会话
+ *       `Primary working directory:` / subagent `<env>` 块 `Working directory:` 两形态均
+ *       实证；标记读不出 fail-closed 不登（错登比漏登危害大，SILLYSPEC_AGENT_LOG 兜底）
  *   - pi：目录名即 cwd 编码（--<路径非字母数字替'-'>--），无需 env 门控；
  *       <home>/.pi/agent/sessions/<safePath>/session.jsonl
  *   - deepseek-dsh（@deepseek-ai/dsh）：同 pi 构但 ':' 删除；
@@ -121,6 +125,51 @@ function readFirstLineJson(filePath, maxBytes = 16384) {
   }
 }
 
+// zcode model-io 无结构化 cwd 字段，归属数据源 = 首行首个请求系统提示词的环境段工作目录标记。
+// 两形态均本机实证：主会话 `Primary working directory: <path>\n- Is a git repository: yes`；
+// subagent 会话 `<env>\nWorking directory: <path>\nIs directory a git repository`。
+const ZCODE_WORKDIR_RE = /[Ww]orking directory: /;
+
+/**
+ * 从 zcode model-io 文件首块字节提取会话工作目录（cwd 归属判定的数据源）。
+ *
+ * 文件是 JSONL：首行 = 首个模型请求（含完整系统提示词），路径以 JSON 字符串内嵌形态出现
+ * ——分隔符双写（`\\`）、行尾是字面 `\n` 两字符。因此取值不能裸 indexOf 截 `\n`：Windows
+ * 路径普遍含 `\n` 字面序列（`\node_modules`、`\notifications`…），须按转义逐字符扫描，
+ * 直到未转义的换行转义（提示词行边界）为止。只读首块不整行 JSON.parse（首行可达 MB 级）。
+ * @returns {string|null} 未命中标记/文件不可读/值为空返回 null（调用方 fail-closed 丢弃）
+ */
+function extractZcodeWorkdir(filePath, maxBytes = 64 * 1024) {
+  let fd = null;
+  try {
+    fd = openSync(filePath, 'r');
+    const buf = Buffer.alloc(maxBytes);
+    const n = readSync(fd, buf, 0, maxBytes, 0);
+    const text = buf.subarray(0, n).toString('utf8');
+    const m = ZCODE_WORKDIR_RE.exec(text);
+    if (!m) return null;
+    const s = text.slice(m.index + m[0].length);
+    let out = '';
+    for (let j = 0; j < s.length;) {
+      const c = s[j];
+      if (c !== '\\') { out += c; j += 1; continue; }
+      const e = s[j + 1];
+      if (e === undefined || e === 'n') break; // 行尾换行转义 → 值结束
+      if (e === 'u' && /^[0-9a-fA-F]{4}$/.test(s.slice(j + 2, j + 6))) {
+        out += String.fromCharCode(parseInt(s.slice(j + 2, j + 6), 16));
+        j += 6;
+      } else if (e === 'r') { out += '\r'; j += 2; }
+      else if (e === 't') { out += '\t'; j += 2; }
+      else { out += e === '/' ? '/' : e; j += 2; } // \\ \" \/ 等：取转义次字符
+    }
+    return out || null;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== null) { try { closeSync(fd) } catch { /* best effort */ } }
+  }
+}
+
 // 活跃文件收集：dir 内 suffix 结尾文件，mtime 在窗口内，mtime 新→旧
 function listActiveFiles(dir, { now, windowMs, limit }) {
   let names;
@@ -233,21 +282,39 @@ function detectCodex(ctx) {
 /**
  * ZCode：env ZCODE_* 门控（本机实证子进程可见 ZCODE_APP_VERSION/ZCODE_ENV 等）；
  * <home>/.zcode/cli/rollout/model-io-sess_<id>.jsonl（含 subagent 会话，文件名带
- * sess_subagent_agent_ 前缀），完整模型 I/O。无 cwd 字段 → env 门控即归属依据。
+ * sess_subagent_agent_ 前缀），完整模型 I/O。
+ *
+ * cwd 归属：rollout 目录全局共享（所有 ZCode 窗口/项目混居），env 门控只证明「CLI 正被
+ * 某个 ZCode 实例驱动」，证明不了「该文件属于本项目」——多窗口并行时另一项目的活跃会话
+ * 会被整体误登（2026-08-31 实证：sillyspec run 把 multi-agent-platform 会话上报为本地
+ * agent 日志）。修法对齐 codex 的 session_meta.cwd 精确匹配：读首块工作目录标记
+ * （extractZcodeWorkdir）与 cwdCandidates 等值比较；标记读不出 fail-closed 丢弃
+ * （错登比漏登危害大——平台把该文件当本会话权威日志解析展示；env 覆盖是兜底通道）。
  */
 function detectZcode(ctx) {
   const { cwdCandidates, env, homeDir, now, windowMs } = ctx;
   const inZcode = Boolean(env.ZCODE_APP_VERSION || env.ZCODE_ENV || env.ZCODE_RUNTIME_ENV);
   if (!inZcode) return [];
   const rolloutDir = join(homeDir, '.zcode', 'cli', 'rollout');
-  const cwdPosix = toPosix(cwdCandidates[0] || '');
-  return listActiveFiles(rolloutDir, { now, windowMs, limit: MAX_PER_HARNESS }).map(f => ({
-    harness: 'zcode', format: 'zcode-model-io-jsonl', detected_via: 'zcode-env-marker',
-    log_path: toPosix(f.full), agent_cwd: cwdPosix,
-    session_id: f.name.replace(/^model-io-sess_/, '').replace(/\.jsonl$/, ''),
-    originator: null,
-    mtime_ms: f.mtimeMs,
-  }));
+  // 预筛多扫一倍再按 cwd 过滤：窗口内其他项目的活跃会话不应在过滤前挤占 MAX_PER_HARNESS 名额
+  const candidates = listActiveFiles(rolloutDir, { now, windowMs, limit: MAX_PER_HARNESS * 2 });
+  const entries = [];
+  for (const f of candidates) {
+    const workdir = extractZcodeWorkdir(f.full);
+    if (!workdir || !cwdCandidates.some(c => c && cwdsMatch(c, workdir))) {
+      debugLog(`zcode rollout cwd 不匹配/无标记，跳过: ${f.name} workdir=${workdir || '(none)'}`);
+      continue;
+    }
+    entries.push({
+      harness: 'zcode', format: 'zcode-model-io-jsonl', detected_via: 'zcode-workdir-marker',
+      log_path: toPosix(f.full), agent_cwd: toPosix(workdir),
+      session_id: f.name.replace(/^model-io-sess_/, '').replace(/\.jsonl$/, ''),
+      originator: null,
+      mtime_ms: f.mtimeMs,
+    });
+    if (entries.length >= MAX_PER_HARNESS) break;
+  }
+  return entries;
 }
 
 /**

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/config-schema.js

@@ -68,8 +68,8 @@ export const LOCAL_YAML_SCHEMA = {
       note: 'detect 核验 package.json(或对应构建文件) scripts 存在性后才写对应键；缺失则不写。agent 可改。',
       keys: [
         { path: 'commands.build', type: 'string', optional: true, status: 'live', readers: ['detectLocalYaml (src/local-detect.js)', 'validateCommands (src/scan-postcheck.js)'], desc: '构建命令。', example: 'npm run build' },
-        { path: 'commands.test', type: 'string', optional: true, status: 'live', readers: ['extractTestCommand (src/verify-postcheck.js)', 'validateCommands (src/scan-postcheck.js)'], desc: '测试命令——verify 阶段 CLI 亲自执行此命令与 verify-result.md 对账，实测失败即阻断。', example: 'npm test' },
-        { path: 'commands.lint', type: 'string', optional: true, status: 'live', readers: ['detectLocalYaml (src/local-detect.js)', 'validateCommands (src/scan-postcheck.js)'], desc: 'lint 命令。', example: 'npm run lint' },
+        { path: 'commands.test', type: 'string', optional: true, status: 'live', readers: ['extractTestCommand (src/verify-postcheck.js)', 'runQuickTestLintGate (src/run/quick-audit.js)', 'validateCommands (src/scan-postcheck.js)'], desc: '测试命令——verify 阶段 CLI 亲自执行此命令与 verify-result.md 对账，实测失败即阻断；quick --done 触及 src/test 时同款实测（P0-2 门禁）。', example: 'npm test' },
+        { path: 'commands.lint', type: 'string', optional: true, status: 'live', readers: ['detectLocalYaml (src/local-detect.js)', 'runQuickTestLintGate (src/run/quick-audit.js)', 'validateCommands (src/scan-postcheck.js)'], desc: 'lint 命令——quick --done 触及 src/test 时 CLI 亲自执行（P0-2 门禁，失败阻断完成）。', example: 'npm run lint' },
         { path: 'commands.install', type: 'string', optional: true, status: 'live', readers: ['extractInstallCommand (src/worktree-deps.js)'], desc: '依赖安装命令（worktree 依赖 provisioning 用）。', example: 'npm install' },
       ],
     },

package/src/contract-matrix.js

@@ -15,6 +15,7 @@ import { splitOwnVsForeignDiffFiles } from './foreign-declared.js'
 import {
   scanBackendEndpoints,
   scanFrontendApiCalls,
+  scanMountPrefixes,
   normalizePath,
   diffApiParity,
 } from './endpoint-extractor.js'
@@ -558,7 +559,16 @@ export function verifyApiParity(specBase, scanRoot, runtimeRoot, changeName = nu
     frontendCalls = scanFrontendApiCalls(frontendRoot)
   }
 
-  const { missingBackend, unusedBackend } = diffApiParity(frontendCalls, mergedProviderEndpoints)
+  // ── 挂载前缀收集（坑 endpoints-mount-prefix-gap，2026-08-31 用户实证）：endpoints 提取的是
+  // 「router 自身前缀 + 装饰器路径」，不含挂载点前缀（main.py 的 include_router(prefix=)/app.use
+  // 与 router 文件分离，静态扫描不做导入图关联）→ 前端全路径调用（/api/xxx）对不上欠前缀端点
+  // （/xxx）→ 17 个存量端点全量假 missing、人工逐条定性。对账时按前缀集合剥除前端调用前缀对齐。
+  const mountPrefixes = new Set()
+  for (const { root } of liveByRoot) {
+    try { for (const p of scanMountPrefixes(root)) mountPrefixes.add(p) } catch { /* 单根失败不拖垮整体 */ }
+  }
+
+  const { missingBackend, unusedBackend, prefixAlignedCount } = diffApiParity(frontendCalls, mergedProviderEndpoints, [...mountPrefixes])
   // unusedBackend 收窄到现算端点（存量 artifact 的过期端点不参与——它不在当前代码里，
   // 「前端未调用」可能是端点已被重构掉而非真泄漏）
   const narrowedUnused = unusedBackend.filter(u => {
@@ -575,6 +585,9 @@ export function verifyApiParity(specBase, scanRoot, runtimeRoot, changeName = nu
   if (narrowedUnused.length > 0) {
     summary += ` | ${narrowedUnused.length} backend endpoints unused by frontend`
   }
+  if (prefixAlignedCount > 0) {
+    summary += ` | ${prefixAlignedCount} calls matched after mount-prefix alignment (artifact paths exclude include_router/app.use prefixes)`
+  }
 
-  return { ok, missingBackend, unusedBackend: narrowedUnused, summary, backendCount: mergedProviderEndpoints.length, frontendCount: frontendCalls.length, scanRoots: liveByRoot.map(r => r.root) }
+  return { ok, missingBackend, unusedBackend: narrowedUnused, summary, backendCount: mergedProviderEndpoints.length, frontendCount: frontendCalls.length, prefixAlignedCount, scanRoots: liveByRoot.map(r => r.root) }
 }

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/doctor-diagnostics.js

@@ -21,6 +21,7 @@
  * writer 落盘到 <authoritySpecDir>/.runtime/。
  */
 import { openDatabase, pluckGet, pluckAll } from './db-engine.js';
+import { safeGit } from './git-helper.js';
 import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, writeFileSync, unlinkSync, rmSync } from 'fs';
 import { join } from 'path';
 import jsYaml from 'js-yaml';
@@ -750,8 +751,10 @@ export async function runDoctorDiagnostics({ cwd }) {
   const executeMismatch = detectExecuteProgressPlanMismatch(authoritySpecDir, authDb);
   const docBloat = detectDocBloat(authoritySpecDir);
   const repoNativeChain = detectRepoNativeChain(cwd, pointer);
+  // P2-2-②：file-lifecycle 文档欠账（git behind 事实计算，治「改了生命周期代码忘同步文档」）
+  const lifecycleDoc = detectLifecycleDocStaleness(cwd);
 
-  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat, repoNativeChain];
+  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat, repoNativeChain, lifecycleDoc];
 
   return {
     dimensions,
@@ -763,6 +766,66 @@ export async function runDoctorDiagnostics({ cwd }) {
   };
 }
 
+// ── D8 file-lifecycle 文档欠账（P2-2-②，2026-09-02 跨 agent 工单）──────────────────
+
+/** 生命周期敏感路径（CLAUDE.md「文件生命周期文档同步」界定的触及面） */
+const LIFECYCLE_DOC_REL = 'docs/sillyspec/file-lifecycle.md';
+const LIFECYCLE_SENSITIVE_PATHS = ['src/stages/', 'src/run.js', 'src/run/', 'src/progress.js', 'src/progress/', 'src/db.js'];
+
+/**
+ * file-lifecycle.md 是否落后于生命周期代码改动（git 提交时间事实比较，只读）。
+ * 与 docs-debt（模块卡 behind 计算）同哲学：CLI 算事实、WARNING 提示不阻断——把 CLAUDE.md
+ * 的「更新检查清单」从人工 checklist 变 doctor 自动卡点（agent 忘同步 → 体检可见）。
+ * 降级语义：文档不存在 / 非 git 仓 / git 失败 → pass: true + findings 注记（不误报）。
+ */
+function detectLifecycleDocStaleness(cwd) {
+  const base = { name: 'lifecycle_doc_staleness', label: '生命周期文档同步', safe_actions: [] };
+  const docAbs = join(cwd, LIFECYCLE_DOC_REL);
+  if (!existsSync(docAbs)) {
+    return { ...base, pass: true, severity: null, findings: [`未找到 ${LIFECYCLE_DOC_REL}（本仓无生命周期总文档，跳过）`] };
+  }
+  // 文档最后提交时间（untracked = 从未提交 → 直接提示）
+  const docLog = safeGit(cwd, ['log', '-1', '--format=%ct', '--', LIFECYCLE_DOC_REL]);
+  if (!docLog.value) {
+    return {
+      ...base,
+      pass: false,
+      severity: CHECK_SEVERITY.WARNING,
+      findings: [`${LIFECYCLE_DOC_REL} 存在但从未提交（untracked）——首次提交后本检查生效`],
+    };
+  }
+  const docTs = Number(docLog.value);
+  if (!Number.isFinite(docTs)) {
+    return { ...base, pass: true, severity: null, findings: ['文档时间戳不可解析，跳过（不误报）'] };
+  }
+  // 生命周期代码侧最新提交（取各敏感路径 max %ct；任一路径 untracked 新文件不在 log 里，
+  // git 不可见性注记——工作树未提交改动本就不该由 doctor 报，提交后自然可见）
+  let srcTs = 0;
+  let srcPath = null;
+  for (const p of LIFECYCLE_SENSITIVE_PATHS) {
+    const r = safeGit(cwd, ['log', '-1', '--format=%ct', '--', p]);
+    const ts = Number(r.value);
+    if (Number.isFinite(ts) && ts > srcTs) { srcTs = ts; srcPath = p; }
+  }
+  if (srcTs === 0) {
+    return { ...base, pass: true, severity: null, findings: ['生命周期代码无提交历史，跳过'] };
+  }
+  if (docTs < srcTs) {
+    const days = Math.floor((srcTs - docTs) / 86400);
+    return {
+      ...base,
+      pass: false,
+      severity: CHECK_SEVERITY.WARNING,
+      findings: [
+        `${LIFECYCLE_DOC_REL} 落后生命周期代码改动（最新代码提交 ${srcPath}，文档已落后 ${days} 天）——` +
+        `请按 CLAUDE.md「文件生命周期文档同步」检查清单核对并更新文档 + updated_at 时间戳`,
+      ],
+      safe_actions: [{ dimension: 'lifecycle_doc_staleness', action: 'sync_file_lifecycle_doc', risk: 'manual_edit', rationale: '文档落后于生命周期代码', next_step: `按 CLAUDE.md 检查清单更新 ${LIFECYCLE_DOC_REL} 与头部 updated_at` }],
+    };
+  }
+  return { ...base, pass: true, severity: null, findings: ['file-lifecycle.md 与生命周期代码改动时间线一致'] };
+}
+
 /**
  * 转结构化 JSON（sillyspec doctor --json 输出 + 落盘格式）。
  * severity 口径对齐 scan-postcheck：CHECK_SEVERITY.FAILED → 'critical'。