sillyspec 3.27.12 → 3.28.2

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, isAbsolute } from 'path';
+import { basename, dirname, extname, join, resolve, isAbsolute, sep } from 'path';
 import { safeGit, git } from './git-helper.js';
 import { getVersion } from './version.js';
 
@@ -94,11 +94,14 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec derive <facet> --change <name> [--json]    单项事实核验（facet: execute-evidence|verify-test|task-reviews|artifacts）
   sillyspec backfill-reviews --change <name> [--adopt] [--json]  缺 review.json 的 task 生成草稿；--adopt 重算代填已有 review 的 base/head 等机械字段（verdict 保留）
   sillyspec symbol-impact --change <name>      生成 symbol-impact.md 逐 task <!--TODO--> 骨架（gate 拒绝未替换占位，防骨架直接过门）
+  sillyspec design-init --change <name> [--force]  从 decisions.md 生成 design.md 十三章节骨架（决策追踪表预填；已存在不覆盖）
+  sillyspec delta --change <name> [--json]   生成变更 delta.md（Before/Delta/After 三段式聚合；幂等覆盖重跑即刷新）
   sillyspec next                            项目状态探测：输出当前状态 + 下一步命令 + 依据（吸收 continue/resume 手工探测表）
   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 | --all-tasks] [--dir <dir>|--files <a.py,b.js>]  静态扫描路由装饰器生成 endpoints.json
+  sillyspec endpoints baseline --change <name> [--spec-dir <path>] [--json]  拍变更前端点基线（幂等不覆盖；worktree 内跑自动锚主仓；归档 delta 端点增删 before 侧）
   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   多项目工作区登记与状态探测
@@ -151,6 +154,7 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec run plan --reopen --from-step 2          # 修订 plan，从第 2 步重做
   sillyspec run quick --non-interactive --done --output "CI 内的快修"  # 脚本/CI
   sillyspec progress show
+  sillyspec progress show --json        # 全局总览 envelope（面板/脚本消费）
   sillyspec worktree apply 2026-07-03-add-login
 `);
 }
@@ -266,6 +270,25 @@ async function main() {
     // QUAL-01 收口：原 execSync 字符串拼接（经 shell）→ git-helper 数组形式
     const r = safeGit(baseDir, ['rev-parse', '--show-toplevel'])
     if (r.value && existsSync(join(r.value, '.sillyspec'))) return r.value
+    // P1-1 第四层锚定（2026-09-02 跨 agent 工单）：.sillyspec 被 gitignore 的仓，linked worktree
+    // 内无 .sillyspec 副本 → 上面两级全 miss，返回 baseDir 会在 worktree 里新建分裂进度库
+    // （run 链路的 D-03 守卫只覆盖「有副本」场景、quick drift 守卫只覆盖「已有 session guard」
+    // 场景，均拦不住新会话）。判据与 worktree.js detectIsolation/_resolveMainRepoRoot 同源：
+    // --git-dir ≠ --git-common-dir 且非 submodule = linked worktree → common-dir 父目录即主仓根。
+    const gd = safeGit(baseDir, ['rev-parse', '--git-dir'])
+    const gcd = safeGit(baseDir, ['rev-parse', '--git-common-dir'])
+    const superProj = safeGit(baseDir, ['rev-parse', '--show-superproject-working-tree'])
+    if (gd.value && gcd.value && gd.value !== gcd.value && !superProj.value) {
+      // common-dir 可能是相对路径，须相对 baseDir 绝对化（与 worktree.js _resolveMainRepoRoot 同坑同解）
+      const absCommonDir = resolve(baseDir, gcd.value)
+      if (existsSync(absCommonDir)) {
+        const mainRoot = dirname(absCommonDir)
+        if (mainRoot !== baseDir && existsSync(join(mainRoot, '.sillyspec'))) {
+          console.warn(`⚠️ cwd 位于 linked worktree，进度库已自动锚定主仓：${mainRoot}（治 worktree 分裂进度库，P1-1）。如确要在 worktree 内独立建进度库，请显式 --spec-dir。`)
+          return mainRoot
+        }
+      }
+    }
     return baseDir
   }
 
@@ -306,9 +329,20 @@ async function main() {
           pm.init(progDir);
           break;
         case 'status':
-        case 'show':
+        case 'show': {
+          // --json：全局总览 envelope（machine-interface，2026-09-02 单一状态源）——多变更
+          // 列表 + 进度/ghost/stall 标记，供 SillyHub 面板 / 跨 agent 程序化消费（与 dump 的
+          // 单变更视角互补）。overview 是纯数据方法不发 console，stdout 直接留 JSON，无需劫持。
+          if (json) {
+            const { runStatusOverview } = await import('./machine-interface.js');
+            const { envelope, exitCode } = runStatusOverview({ cwd: progDir, specBase: resolvePlatformSpecDir(dir, specDir) });
+            console.log(JSON.stringify(envelope));
+            process.exitCode = exitCode;
+            break;
+          }
           pm.show(progDir, progChangeName);
           break;
+        }
         case 'check': {
           const result = pm.checkConsistency(progDir, progChangeName);
           // checkConsistency 只返回 {ok, issues, warnings}，不打印——必须在此输出，
@@ -418,7 +452,7 @@ async function main() {
           break;
         }
         default:
-          console.log('用法: sillyspec progress <init|show|validate|reset|set-stage|add-step|update-step|complete-stage|dump>');
+          console.log('用法: sillyspec progress <init|show|validate|reset|set-stage|add-step|update-step|complete-stage|dump>\n  show 支持 --json：全局总览 envelope（活跃变更列表 + 进度 + ghost/stall，面板/脚本消费）');
           process.exit(2);
       }
       break;
@@ -539,14 +573,14 @@ async function main() {
       // 缺失草稿，独立可随时跑（不必再 execute --done）。缺数据（无 tasks/ 目录 / 改动未 commit / 无 worktree meta）
       // 时 generateTaskReviewDrafts 提前返回 reason，如实打印不报错。
       // --adopt（2026-08-21 agent-手工产出审计项①）：已存在 review.json 的 mechanics 字段
-      // （schemaVersion/task/base/head/changedFiles/repo）一键重算代填，agent/子代理只写
+      // （schemaVersion/task/base/head/changedFiles/diffPaths/repo）一键重算代填，agent/子代理只写
       // verdict——手算 hash、手抄 diff 清单是纯错误面，gate 校验的恰是这些字段。与草稿互补：
       // 草稿补「缺失」，adopt 修「已存在但 mechanics 错/缺」，verdict 原样保留。
       const brChangeIdx = args.indexOf('--change');
       const brChange = brChangeIdx >= 0 && args[brChangeIdx + 1] ? args[brChangeIdx + 1] : null;
       const brAdopt = args.includes('--adopt');
       if (!brChange) {
-        console.error('用法: sillyspec backfill-reviews --change <name> [--adopt] [--json] [--spec-dir <path>]\n  缺失 review.json → 生成 cannot_verify 草稿（解 archive 客观完成度阻断）\n  --adopt → 已存在 review.json 的 base/head/changedFiles 等 mechanics 字段一键重算代填（verdict 保留）');
+        console.error('用法: sillyspec backfill-reviews --change <name> [--adopt] [--json] [--spec-dir <path>]\n  缺失 review.json → 生成 cannot_verify 草稿（解 archive 客观完成度阻断）\n  --adopt → 已存在 review.json 的 base/head/changedFiles/diffPaths 等 mechanics 字段一键重算代填（verdict 保留；统一 commit 模式 diffPaths=task 卡 allowed_paths）');
         process.exit(2);
       }
       // 与 run 入口同源消毒（防路径穿越；backfill 下游拼 marker/changes/review 路径）
@@ -802,7 +836,7 @@ async function main() {
         process.exit(2);
       }
       assertSafeChangeName(vpChange, '--change 变更名');
-      const { runVerifyProbes, renderVerifyProbesReport, generateVerifyResultSkeleton, resolveVerifyProbesSpecBase } = await import('./verify-probes.js');
+      const { runVerifyProbes, renderVerifyProbesReport, generateVerifyResultSkeleton, resolveVerifyProbesSpecBase, writeVerifyFacts } = await import('./verify-probes.js');
       // spec 根统一走漂移锚定（坑 worktree-spec-artifact-misplace）：在 worktree 内跑时锚回主仓，
       // 探针读取与 --init 骨架都落主仓——与 plan/execute/verify/archive 的 command.js 守卫同口径。
       // resolvePlatformSpecDir 仍先调（保留平台接管 fail-closed 检查副作用），但仅 pointer 存在时
@@ -820,11 +854,26 @@ async function main() {
       if (vpInit) {
         const vpReportPath = join(vpSpecBase, 'changes', vpChange, 'verify-result.md');
         if (existsSync(vpReportPath)) {
-          console.log(`\nℹ️  verify-result.md 已存在，不覆盖: ${vpReportPath}`);
+          const vpExisting = readFileSync(vpReportPath, 'utf8');
+          // 检测正则与提取侧（parseProbePrefillAnchors 的 /^#### 探针 (\d+)[：:]/）对齐要求冒号——
+          // 对抗复审 BUG-1（2026-09-07）：agent 手写无冒号走样标题 `#### 探针 1` 会被宽松检测误判
+          // 「已有子节」跳过注入，而提取侧不认 → 死路复活（--init no-op + gate error 无解）。
+          if (!/^#### 探针 \d+[：:]/m.test(vpExisting)) {
+            // P1 修复（2026-09-07）：存量旧格式（九章节）报告 + --init 曾是死路——facts 无条件刷新
+            // 而正文不补，checkProbeConsistency 判别子判「疑似 agent 删除预填段」error 阻断，而修复
+            // 指引「重跑 --init」对已存在报告是 no-op。修法：探针段是 CLI 拥有的机械段，检测缺失时
+            // 尾部补注入（正文其余不动），判别子自此有子节可对账。
+            const vpSection = `\n## 探针结果（CLI 机械预填，--init 补注入） [层：可复跑探针——gate 抽查防篡改]\n${renderVerifyProbesReport(vpResult)}\n`;
+            writeFileSync(vpReportPath, vpExisting.replace(/\s*$/, '\n') + vpSection);
+            console.log(`\n📄 存量旧格式 verify-result.md 已补注入探针预填段: ${vpReportPath}（正文其余未动；补注后按新预填段如实核对结论）`);
+          } else {
+            console.log(`\nℹ️  verify-result.md 已存在，不覆盖: ${vpReportPath}`);
+          }
         } else {
           writeFileSync(vpReportPath, generateVerifyResultSkeleton(vpResult));
           console.log(`\n📄 已生成 verify-result.md 骨架: ${vpReportPath}（探针已预填；结论必须写明 PASS/FAIL，留待填会被 gate 判不过）`);
         }
+        writeVerifyFacts(join(vpSpecBase, 'changes', vpChange), vpResult, vpChange); // P3b：facts 底稿随 --init 刷新（骨架已存在也刷新，最近快照语义）
       }
       break;
     }
@@ -914,8 +963,78 @@ async function main() {
       // 产生大量假 missing）：聚合模式——逐 task 卡提取，各自落 contract-artifacts/<change>/<task>/，
       // 与 verifyApiParity 的聚合读侧（contract-artifacts/<change>/*/endpoints.json 全量并集）对齐。
       const epSub = filteredArgs[1];
+      // 子分发（变更 2026-09-07-endpoint-baseline task-02）：baseline（变更前基线）+ extract（原样）。
+      if (epSub === 'baseline') {
+        // 端点基线（D-002 gap-1）：变更起点全仓现扫端点集快照 → .runtime/endpoint-baselines/
+        // <change>.json（幂等，已拍过不覆盖——首次跑即变更前状态，重跑保持原快照）。归档 delta
+        // 端点增删的 before 侧；扫描/落盘在 endpoint-baseline.js 纯函数，此处只做参数解析 +
+        // worktree 主仓锚定 + 输出。
+        const ebChangeIdx = args.indexOf('--change');
+        const ebChange = ebChangeIdx >= 0 && args[ebChangeIdx + 1] ? args[ebChangeIdx + 1] : null;
+        if (!ebChange) {
+          console.error('用法: sillyspec endpoints baseline --change <name> [--spec-dir <path>] [--json]\n  拍变更前端点基线（全仓现扫，幂等已拍过不覆盖）→ .runtime/endpoint-baselines/<change>.json；归档 delta 端点增删的 before 侧。\n  execute worktree 内跑：扫描根与落点自动锚定主仓（变更前代码在主仓；worktree 内是交付态且其 .runtime 随清理丢失）');
+          process.exit(2);
+        }
+        assertSafeChangeName(ebChange, '--change 变更名');
+        // worktree 主仓锚定（D-002 gap-1 关键）：cwd 在 execute worktree 内时——
+        // ① 扫描 cwd 若保持 worktree：扫到的是 baseline 检出 + 本变更改动（非「变更前」端点集）；
+        // ② runtimeRoot 若随 cwd 落 worktree 副本 .runtime：基线随 worktree 清理静默丢失。
+        // 判据同 resolveEffectiveDir（P1-1）/ worktree.js _resolveMainRepoRoot：--git-dir ≠
+        // --git-common-dir 且非 submodule = linked worktree，common-dir（可能是相对路径，须相对
+        // dir 绝对化）父目录即主仓根 → 扫描根与 spec 解析都锚过去（--spec-dir 显式指定仍优先）。
+        let ebScanCwd = dir;
+        let ebSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+        // --json 纪律（design §8）：机器输出模式下人类提示走 stderr，stdout 只留最终 JSON
+        const ebNote = (msg) => { (json ? console.error : console.log)(msg); };
+        try {
+          const gd = git(dir, ['rev-parse', '--git-dir']);
+          const gcd = git(dir, ['rev-parse', '--git-common-dir']);
+          const superProj = git(dir, ['rev-parse', '--show-superproject-working-tree']);
+          if (gd && gcd && gd !== gcd && !superProj) {
+            const ebMainRoot = dirname(resolve(dir, gcd));
+            if (ebMainRoot !== dir && existsSync(ebMainRoot)) {
+              ebNote(`⚠️ cwd 在 linked worktree 内，基线扫描根与落点已锚定主仓: ${ebMainRoot}（变更前代码在主仓；worktree 内是交付态且其 .runtime 随清理丢失，防基线静默失效）`);
+              ebScanCwd = ebMainRoot;
+              ebSpecBase = resolvePlatformSpecDir(ebMainRoot, specDir) || join(ebMainRoot, '.sillyspec');
+              // 显式 --spec-dir 指向 worktree 副本（任意形态——手建目录/检出副本；下方 drift 只认
+              // .runtime/worktrees 检出形态，覆盖不了手建副本）→ 重算结果仍在 worktree 内时锚回主仓
+              if (!resolve(ebSpecBase).toLowerCase().startsWith(resolve(ebMainRoot).toLowerCase() + sep)) {
+                ebNote(`⚠️ 显式 spec 命中 worktree 副本（${ebSpecBase}），基线落点一并锚定主仓: ${join(ebMainRoot, '.sillyspec')}`);
+                ebSpecBase = join(ebMainRoot, '.sillyspec');
+              }
+            }
+          }
+        } catch { /* git 不可用/非仓库 → 不锚定，按原 cwd 继续 */ }
+        // 终局兜底（同下方 extract 分支 detectWorktreeSpecDrift 用法，无论上面是否已锚定都跑：
+        // --spec-dir 显式指向 worktree 副本 spec 时，上面重算 resolvePlatformSpecDir 仍原样
+        // 返回该显式路径）——spec 命中副本 → 锚回主仓，防 runtimeRoot 落副本 .runtime。
+        const ebDrift = detectWorktreeSpecDrift(ebSpecBase);
+        if (ebDrift) {
+          ebNote(`⚠️ 已自动锚定主仓 spec: ${ebDrift.mainSpecBase}（基线落主仓；当前 spec 命中 worktree 副本 ${ebDrift.changeName}，流程继续）`);
+          ebSpecBase = ebDrift.mainSpecBase;
+        }
+        const ebRuntimeRoot = (await import('./run/shared.js')).resolveRuntimeRoot({ specRoot: specDir }, ebSpecBase);
+        const { captureEndpointBaseline } = await import('./endpoint-baseline.js');
+        const ebResult = captureEndpointBaseline({ cwd: ebScanCwd, changeName: ebChange, runtimeRoot: ebRuntimeRoot });
+        if (json) {
+          console.log(JSON.stringify({ command: 'endpoints-baseline', change: ebChange, ok: !ebResult.error, ...ebResult }, null, 2));
+          if (ebResult.error) process.exit(1);
+          break;
+        }
+        if (ebResult.error) {
+          console.error(`❌ 端点基线拍摄失败: ${ebResult.error}`);
+          process.exit(1);
+        }
+        if (!ebResult.written) {
+          console.log(`ℹ️  端点基线已存在，跳过（幂等不覆盖）: ${join(ebRuntimeRoot, 'endpoint-baselines', `${ebChange}.json`)}`);
+          break;
+        }
+        console.log(`✅ 已拍变更前端点基线（${ebResult.count} 个端点）→ ${ebResult.path}`);
+        console.log('   幂等：已拍过不覆盖（重跑保持首次快照）；归档 delta 用它计算端点增删（before 侧）。');
+        break;
+      }
       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 聚合读侧一致，推荐）。\n  execute worktree 模式：allowed_paths 自动按 worktree 根解析，产物恒落主仓 spec（坑 endpoints-extract-worktree-pitfalls）');
+        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）\nsillyspec endpoints baseline --change <name> [--spec-dir <path>] [--json]\n  拍变更前端点基线（全仓现扫，幂等已拍过不覆盖）→ .runtime/endpoint-baselines/<change>.json；归档 delta 端点增删的 before 侧。worktree 内跑自动锚定主仓。');
         process.exit(2);
       }
       const epChangeIdx = args.indexOf('--change');
@@ -1125,6 +1244,108 @@ async function main() {
       console.log('   逐行替换 <!--TODO--> 为结论（无签名级变更也显式写「无」）；gate 拒绝未替换的占位行。');
       break;
     }
+    case 'design-init': {
+      // design.md 十三章节骨架生成（change: 2026-09-07-ir-stage-p3c，task-02，FR-03）：agent 此前
+      // 从零手写整份设计文档，章节漏项到 stage-contract/plan 门禁才暴露。本命令从 decisions.md
+      // 当前版本 D 条目预填决策追踪表，章节标题逐字取自 brainstorm Step 6 模板（R-03，渲染本体在
+      // design-facts.js generateDesignSkeleton——本 case 只负责读盘/幂等保护/落盘）。已存在不覆盖
+      // （幂等，agent 产出优先），--force 覆盖重生成。
+      const diChangeIdx = args.indexOf('--change');
+      const diChange = diChangeIdx >= 0 && args[diChangeIdx + 1] ? args[diChangeIdx + 1] : null;
+      const diForce = args.includes('--force');
+      if (!diChange) {
+        console.error('用法: sillyspec design-init --change <name> [--force] [--json] [--spec-dir <path>]\n  从变更 decisions.md 生成 design.md 十三章节骨架（决策追踪表按当前版本 D 条目预填；已存在不覆盖，--force 覆盖）');
+        process.exit(2);
+      }
+      assertSafeChangeName(diChange, '--change 变更名');
+      const diSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+      const diChangeDir = join(diSpecBase, 'changes', diChange);
+      const diDecisionsPath = join(diChangeDir, 'decisions.md');
+      if (!existsSync(diDecisionsPath)) {
+        console.error(`❌ decisions.md 不存在: ${diDecisionsPath}`);
+        console.error('   先跑 sillyspec run brainstorm 推进决策环节（形成技术决策落盘 decisions.md），再生成 design 骨架。');
+        if (json) console.log(JSON.stringify({ command: 'design-init', change: diChange, ok: false, error: `decisions.md 不存在: ${diDecisionsPath}` }, null, 2));
+        process.exit(1);
+      }
+      const { generateDesignSkeleton } = await import('./design-facts.js');
+      // author/created_at 与 taskcard/scan-postcheck 同口径：git user.name（回退 unknown）+ 本地墙钟
+      let diAuthor = 'unknown';
+      try { diAuthor = git(dir, ['config', 'user.name']) || 'unknown' } catch { /* git 不可用 → unknown */ }
+      const { nowWallClock } = await import('./datetime.js');
+      const diSkeleton = generateDesignSkeleton({
+        changeName: diChange,
+        decisionsText: readFileSync(diDecisionsPath, 'utf8'),
+        author: diAuthor,
+        now: nowWallClock(),
+      });
+      const diDesignPath = join(diChangeDir, 'design.md');
+      const diExisted = existsSync(diDesignPath);
+      if (diExisted && !diForce) {
+        if (json) {
+          console.log(JSON.stringify({ command: 'design-init', change: diChange, ok: true, path: diDesignPath, written: false, reason: 'exists' }, null, 2));
+        } else {
+          console.log(`ℹ️  design.md 已存在，不覆盖: ${diDesignPath}（确要重新生成骨架加 --force）`);
+        }
+        break;
+      }
+      writeFileSync(diDesignPath, diSkeleton);
+      if (json) {
+        console.log(JSON.stringify({ command: 'design-init', change: diChange, ok: true, path: diDesignPath, written: true, overwritten: diExisted }, null, 2));
+        break;
+      }
+      console.log(`✅ 已生成 design.md 骨架: ${diDesignPath}${diExisted ? '（--force 覆盖既有文件）' : ''}`);
+      console.log('   决策追踪表已按 decisions.md 当前版本 D 条目预填；回到 brainstorm Step 6（写设计文档并自审）逐节填散文，填毕删除生成注释。');
+      break;
+    }
+    case 'delta': {
+      // delta.md 生成（change: 2026-09-07-ir-stage-p3d，task-02）：task-01 buildDeltaReport
+      // 四源 fail-soft 聚合（reconcile/verify-facts/module-map/decisions）的 CLI 落盘入口——
+      // 归档确认步（handleArchiveConfirmStep）自动生成失败时的手动补跑通道。幂等覆盖
+      // （重跑即刷新）：与 design-init「agent 产出优先不覆盖」语义相反——delta 是源数据
+      // （verify-runs/module-map）时点快照，旧报告天然过期，重新生成即对齐。
+      const dlChangeIdx = args.indexOf('--change');
+      const dlChange = dlChangeIdx >= 0 && args[dlChangeIdx + 1] ? args[dlChangeIdx + 1] : null;
+      if (!dlChange) {
+        console.error('用法: sillyspec delta --change <name> [--spec-dir <path>] [--json]\n  生成变更 delta.md（Before/Delta/After 三段式；四源 fail-soft，缺源逐段降级注记；幂等覆盖重跑即刷新）');
+        process.exit(2);
+      }
+      assertSafeChangeName(dlChange, '--change 变更名');
+      const dlSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+      const dlChangeDir = join(dlSpecBase, 'changes', dlChange);
+      if (!existsSync(dlChangeDir)) {
+        console.error(`❌ 变更目录不存在: ${dlChangeDir}`);
+        if (json) console.log(JSON.stringify({ command: 'delta', change: dlChange, ok: false, error: `变更目录不存在: ${dlChangeDir}` }, null, 2));
+        process.exit(1);
+      }
+      // runtimeRoot 解析同 register-stage-review 先例（resolvePlatformOpts > resolveRuntimeRoot）：
+      // reconcile（verify-runs/<ts>/reconcile-result.json）与 apply-pathspec 兜底清单都在 runtime 下。
+      const dlPlatformOpts = {};
+      const dlResolved = resolvePlatformOpts(dir, specDir);
+      if (dlResolved) {
+        dlPlatformOpts.specRoot = dlResolved.specRoot;
+        if (dlResolved.runtimeRoot) dlPlatformOpts.runtimeRoot = dlResolved.runtimeRoot;
+      }
+      const { resolveRuntimeRoot } = await import('./run/shared.js');
+      const dlRuntimeRoot = resolveRuntimeRoot(dlPlatformOpts, dlSpecBase);
+      const { buildDeltaReport } = await import('./archive-delta.js');
+      // CLI 不收 --project：project=null 走 loadModuleMap 降级路径（报告内「无 module-map」注记），
+      // 与归档确认步自动生成（progress.project 有值时命中 module-map）形成口径互补。
+      const dlMarkdown = buildDeltaReport({
+        changeDir: dlChangeDir,
+        specRoot: dlSpecBase,
+        project: null,
+        runtimeRoot: dlRuntimeRoot,
+      });
+      const dlPath = join(dlChangeDir, 'delta.md');
+      writeFileSync(dlPath, dlMarkdown);
+      if (json) {
+        console.log(JSON.stringify({ command: 'delta', change: dlChange, ok: true, path: dlPath, written: true }, null, 2));
+        break;
+      }
+      console.log(`✅ 已生成 delta.md: ${dlPath}（幂等覆盖，重跑即刷新）`);
+      console.log('   Before/Delta/After 三段式快照；归档确认步自动生成失败时可用本命令手动补。');
+      break;
+    }
     case 'register-stage-review': {
       // 手动注册 stage 级 review（brainstorm/plan/execute-acceptance）的确定性 writer ——
       // 生成 run 目录 + review.json 骨架（cannot_verify，待独立审查子代理填 verdict）或 adopt
@@ -1579,6 +1800,25 @@ async function main() {
       break;
     }
     case 'scan': {
+      // scan facts 子命令（archify 借鉴：机械事实预咀嚼，2026-09-05）。
+      // CLI 确定性抽取端点/依赖/规模/git 基线 → docs/<project>/scan/_facts.md，
+      // 供 scan 步骤 3/5 的子代理共享（禁止各自 grep 重复发现）。与 diff 同为纯只读旁路。
+      if (filteredArgs[1] === 'facts') {
+        const { buildAndWriteScanFacts } = await import('./scan-facts.js')
+        const factsEffectiveDir = specDir ? dir : resolveEffectiveDir(dir)
+        const projIdx = filteredArgs.indexOf('--project')
+        const pathIdx = filteredArgs.indexOf('--path')
+        const r = buildAndWriteScanFacts({
+          cwd: factsEffectiveDir,
+          specDir: resolvePlatformSpecDir(dir, specDir) || join(factsEffectiveDir, '.sillyspec'),
+          projectName: projIdx >= 0 && filteredArgs[projIdx + 1] ? filteredArgs[projIdx + 1] : basename(factsEffectiveDir),
+          projectPath: pathIdx >= 0 && filteredArgs[pathIdx + 1] ? filteredArgs[pathIdx + 1] : null,
+        })
+        const f = r.facts
+        console.log(`scan facts 已写入: ${r.outPath}`)
+        console.log(`  类型 ${f.type} · 依赖 ${f.deps.length} · 端点 ${f.endpoints.backendTotal}（后端）/ ${f.endpoints.frontendTotal}（前端调用）· 源文件 ${f.size.fileCount}`)
+        break
+      }
       // scan diff 子命令（D-001@v1：接线唯一入口 index.js，非 command.js 裸 token 静默吞）。
       // 纯只读比较命令：跳过下方共享块的 triggerPullActiveChange（不触发网络 pull），
       // 也不走 scan 主流程（--standard/--deep 分支不动）。解析 --base/--full/--report 后转发 scan-diff。

package/src/machine-interface.js

@@ -541,3 +541,66 @@ export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot,
     return { envelope, exitCode: EXIT_UNKNOWN };
   }
 }
+
+// ============ 全局状态总览（单一状态源，2026-09-02 跨 agent 协作改进 P0-1）============
+
+/**
+ * 全局状态总览：全部活跃变更列表 + 各自阶段/步骤进度 + ghost/stall 标记。
+ *
+ * 与 gate/derive（单变更粒度）和 progress dump（单变更视角、daemon 轮询）互补——
+ * 本命令回答「这个项目现在有谁在动哪些变更」，供 SillyHub 面板 / 跨 agent 消费
+ * （`sillyspec progress show --json`）。
+ *
+ * 只读契约（同 runGate D-002@v1）：仅 ProgressManager 读路径，不写 sillyspec.db；
+ * DB 不存在 → fail-closed 返回 exit 2（项目未初始化，无从总览），不建库。
+ * 数据组装单点在 StageMachine.overview（与 show 汇总视图同源 listChanges/_stallSignal），
+ * 本函数只做 envelope 封装——沿「只聚合不新增校验」的模块定位。
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd - 项目根目录
+ * @param {string} [opts.specBase] - .sillyspec（或平台 specRoot）目录；默认 resolveSpecDir(cwd)
+ * @returns {{ envelope: object, exitCode: number }} exitCode：0 总览成功（含空列表）/ 2 无法核验
+ */
+export function runStatusOverview({ cwd, specBase } = {}) {
+  const specRoot = specBase || resolveSpecDir(cwd);
+
+  try {
+    const dbPath = join(specRoot, '.runtime', 'sillyspec.db');
+    if (!existsSync(dbPath)) {
+      const envelope = buildEnvelope({
+        command: 'progress show',
+        ok: false,
+        errors: [`无法核验：进度库不存在（${dbPath}）——项目尚未初始化进度，只读总览不会为其建库`],
+      });
+      return { envelope, exitCode: EXIT_UNKNOWN };
+    }
+
+    const pm = new ProgressManager({ specDir: specRoot });
+    const data = pm.overview(cwd);
+
+    // ghost（目录缺失残留记录）升 warnings：不阻断 ok（总览本身是成功的，ghost 是待清理事实）
+    const warnings = data.changes
+      .filter(c => c.ghost)
+      .map(c => `${c.name}: 目录缺失（残留记录，sillyspec doctor --cleanup-ghosts --confirm 可归档清理）`);
+    // P2-2-①：未决同步冲突同样升 warnings（冲突可见性——daemon/面板看顶层即知有冲突待处理）
+    for (const cf of (data.pending_conflicts || [])) {
+      warnings.push(`${cf.change}: 未决同步冲突（${cf.type === 'progress' ? '进度' : 'spec 树'}，sillyspec platform resolve 处理）`);
+    }
+
+    const envelope = buildEnvelope({
+      command: 'progress show',
+      ok: true,
+      warnings,
+      data,
+    });
+    return { envelope, exitCode: EXIT_OK };
+  } catch (e) {
+    // 内部异常兜底（同 runDerive）：stdout 永远合法 JSON，exit 2
+    const envelope = buildEnvelope({
+      command: 'progress show',
+      ok: false,
+      errors: [`internal: ${e.message}`],
+    });
+    return { envelope, exitCode: EXIT_UNKNOWN };
+  }
+}

package/src/modules.js

@@ -212,21 +212,42 @@ export function splitChangelog(cwd, { force = false } = {}) {
     for (const f of cards) {
       const cardPath = join(modulesDir, f);
       const content = readFileSync(cardPath, 'utf8');
-      // 提取「## 变更索引」节（CRLF 归一后行级匹配，与 modules.js 其余解析同防线）
+      // 提取「## 变更索引」节（CRLF 归一后行级匹配，与 modules.js 其余解析同防线）。
+      // 标题正则允许后缀（如「（表格，初始为空）」——2026-09-07 实证 core-engine 形态漏迁）；
+      // miss 时再试 MANUAL_NOTES 区（stages/runtime 形态：<!-- MANUAL_NOTES_END --> 前的尾部
+      // 行块——全或无：块内行须全部为「- <变更名> | 摘要」形态才整体迁出，防误迁散文）
       const lines = content.replace(/\r\n/g, '\n').split('\n');
-      const startIdx = lines.findIndex(l => /^##\s*变更索引\s*$/.test(l));
-      if (startIdx < 0) { skipped++; continue; }
-      let endIdx = lines.length;
-      for (let i = startIdx + 1; i < lines.length; i++) {
-        if (/^##\s/.test(lines[i])) { endIdx = i; break; }
+      const startIdx = lines.findIndex(l => /^##\s*变更索引/.test(l));
+      let kind = 'index';
+      let segStart = -1, segEnd = -1, body = '';
+      if (startIdx >= 0) {
+        let endIdx = lines.length;
+        for (let i = startIdx + 1; i < lines.length; i++) {
+          if (/^##\s/.test(lines[i])) { endIdx = i; break; }
+        }
+        const b = lines.slice(startIdx + 1, endIdx).join('\n').trim();
+        // 已迁出（只剩指针行）或本就为空 → 跳过
+        if (!b || /^见\s/.test(b) || b.includes('.changelog.md')) { skipped++; continue; }
+        kind = 'index'; segStart = startIdx + 1; segEnd = endIdx; body = b;
+      } else {
+        const endMark = lines.findIndex(l => l.includes('<!-- MANUAL_NOTES_END -->'));
+        if (endMark < 0) { skipped++; continue; }
+        // 块首 = END 标记向上、以空行为界的连续内容块起点
+        let bs = endMark - 1;
+        while (bs >= 0 && lines[bs].trim() !== '') bs--;
+        // 块内剔除 HTML 注释行（区开标记 <!-- MANUAL_NOTES ... --> 等）后须全为变更行形态
+        const block = lines.slice(bs + 1, endMark).filter(l => {
+          const t = l.trim()
+          return t !== '' && !/^<!--.*-->$/.test(t)
+        });
+        const CHG_LINE = /^- [A-Za-z0-9][\w\-./]* \| /;
+        if (block.length === 0 || !block.every(l => CHG_LINE.test(l))) { skipped++; continue; }
+        kind = 'manual-notes'; segStart = bs + 1; segEnd = endMark; body = block.join('\n');
       }
-      const body = lines.slice(startIdx + 1, endIdx).join('\n').trim();
-      // 已迁出（只剩指针行）或本就为空 → 跳过
-      if (!body || /^见\s/.test(body) || body.includes('.changelog.md')) { skipped++; continue; }
       const bytesMoved = Buffer.byteLength(body, 'utf8');
       const stem = f.replace(/\.md$/, '');
       const sidecarPath = join(modulesDir, `${stem}.changelog.md`);
-      results.push({ card: cardPath, sidecar: sidecarPath, bytesMoved, _lines: lines, _startIdx: startIdx, _endIdx: endIdx, _body: body });
+      results.push({ card: cardPath, sidecar: sidecarPath, bytesMoved, kind, _lines: lines, _segStart: segStart, _segEnd: segEnd, _body: body });
     }
   }
 
@@ -253,9 +274,17 @@ export function splitChangelog(cwd, { force = false } = {}) {
       sidecarContent = header + '\n' + r._body + '\n';
     }
     writeFileSync(r.sidecar, sidecarContent, 'utf8');
-    // 卡内节体替换为指针行（只动该节，其余逐字保留；_lines 已是 LF 归一）
+    // 卡内替换（只动该段，其余逐字保留；_lines 已是 LF 归一）：
+    // index → 节体换指针行；manual-notes → 尾部块清空 + END 标记前留迁移指针注释
     const stem = r.card.split(/[\\/]/).pop().replace(/\.md$/, '');
-    const newLines = [...r._lines.slice(0, r._startIdx + 1), '', `见 \`${stem}.changelog.md\`——历史条目已迁出；新条目直接追加 sidecar，勿写回本卡。`, '', ...r._lines.slice(r._endIdx)];
+    let newLines;
+    if (r.kind === 'manual-notes') {
+      newLines = [...r._lines.slice(0, r._segStart),
+        `<!-- MANUAL_NOTES 区变更条目已迁出至 ${stem}.changelog.md（split-changelog）；新条目追加 sidecar，勿写回本卡 -->`,
+        ...r._lines.slice(r._segEnd)];
+    } else {
+      newLines = [...r._lines.slice(0, r._segStart), '', `见 \`${stem}.changelog.md\`——历史条目已迁出；新条目直接追加 sidecar，勿写回本卡。`, '', ...r._lines.slice(r._segEnd)];
+    }
     writeFileSync(r.card, newLines.join('\n'), 'utf8');
     console.log(`✅ ${r.card} → ${r.sidecar}（迁出 ${(r.bytesMoved / 1024).toFixed(1)}KB，卡内留指针）`);
   }

package/src/progress/change-registry.js

@@ -126,6 +126,26 @@ export class ChangeRegistry {
     }
   }
 
+  /**
+   * 读取变更回填的 quicklog_id（quick 启动时 stage.js 写入的分配 ql-ID）。
+   * quick --done 兜底路径复用启动 ql-ID 用（坑 platform-takeover-phantom-progress-db
+   * 同日变体：guard 缺失时补分配新号制造引用劈叉——落码注释/模块文档的 ql-ID 是启动
+   * 时就给出的，兜底换号必然劈叉；启动 ID 进度库里可查）。
+   * @param {string} cwd
+   * @param {string} changeName
+   * @returns {string|null} 行缺失/未回填/读取失败返回 null
+   */
+  getQuicklogId(cwd, changeName) {
+    if (!changeName) return null;
+    try {
+      const db = this.pm._ensureDB(cwd);
+      const row = db.getDb().prepare('SELECT quicklog_id FROM changes WHERE name = ?').get(changeName);
+      return (row && typeof row.quicklog_id === 'string' && row.quicklog_id) || null;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * 读取变更的隔离状态
    * @param {string} cwd - 项目根目录