sillyspec 3.28.0 → 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, dirname, 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   多项目工作区登记与状态探测
@@ -833,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 存在时
@@ -851,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;
     }
@@ -945,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');
@@ -1156,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
@@ -1610,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/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 - 项目根目录

package/src/progress/consistency-doctor.js

@@ -1,8 +1,9 @@
 // W6 Step9a: Revision v1 状态一致性检查 + 修复 + --force 审计日志。
 // 从 src/progress.js 单体 ProgressManager 抽出。持有 pm 引用（构造注入），调 pm.read / pm._write /
 // pm._ensureRuntimeDir / pm._runtimePath（persistence-core 留 facade 本体）。
-import { appendFileSync, existsSync, readdirSync } from 'fs';
-import { join } from 'path';
+import { appendFileSync, existsSync, readFileSync, readdirSync } from 'fs';
+import { join, resolve } from 'path';
+import { DB } from '../db.js';
 import { summarizeTaskCompletion } from '../task-review.js';
 import { STAGE_ORDER, MAIN_FLOW_ORDER } from './shared.js';
 
@@ -11,6 +12,104 @@ export class ConsistencyDoctor {
     this.pm = pm;
   }
 
+  /**
+   * 双进度库分裂探测（坑 progress-repair-dual-library-blind，2026-09-04 用户实证②：
+   * 接管指针切换库后 progress repair 只看当前库，旧库残留的活跃变更进度完全不可见，
+   * 报告「未发现问题，无需修复」的假阴性）。
+   *
+   * 判据：cwd 存在平台接管指针（.sillyspec-platform.json 指向库 A = 当前修复目标），
+   * 同时 cwd/.sillyspec/.runtime/sillyspec.db（库 B = 切库前旧库）也存在且 ≠ 库 A
+   * → 双库并存。自指指针（specRoot 解析回本地 .sillyspec）不算。
+   *
+   * 只读探测：另一库仅在 sillyspec.db 已存在时直读（DB 类 + 存在性前置检查，绝不新建库文件）；
+   * 读失败 fail-open 返回库存在但活跃清单不可读，不阻断 check/repair 主流程。
+   *
+   * @param {string} cwd - 进度库锚定 cwd（index.js 传入 progDir）
+   * @param {string|null} [changeName] - check/repair 的 --change 目标（判「操作错了库」用）
+   * @returns {{ split: boolean, dualDb: boolean, bothActive: boolean, targetInOther: boolean, lines: string[] }}
+   */
+  detectLibrarySplit(cwd, changeName = null) {
+    const out = { split: false, dualDb: false, bothActive: false, targetInOther: false, lines: [] };
+    const pointerPath = join(cwd, '.sillyspec-platform.json');
+    if (!existsSync(pointerPath)) return out;
+    let ptr = null;
+    try {
+      ptr = JSON.parse(readFileSync(pointerPath, 'utf8'));
+    } catch {
+      return out; // 指针损坏由 resolvePlatformSpecDir fail-closed 负责，此处不重复报
+    }
+    if (!ptr.specRoot) return out;
+
+    const localRoot = join(cwd, '.sillyspec');
+    const localDbPath = join(localRoot, '.runtime', 'sillyspec.db');
+    if (resolve(ptr.specRoot) === resolve(localRoot)) return out; // 自指/同库
+    if (!existsSync(localDbPath)) return out; // 旧库无 DB → 无分裂
+
+    out.dualDb = true;
+    const currentSpecDir = this.pm._getSpecDir(cwd);
+    // 当前库：DB 已存在才读（readGlobal 走 pm 连接池，不新开连接；不存在时 readGlobal 会
+    // 隐式建库，须前置 existsSync 挡住——探测绝不产生写副作用）
+    let current = null;
+    if (existsSync(join(currentSpecDir, '.runtime', 'sillyspec.db'))) {
+      try {
+        const g = this.pm.readGlobal(cwd);
+        current = { activeChanges: (g && g.activeChanges) || [] };
+      } catch (e) {
+        current = { activeChanges: [], unreadable: true, error: e.message };
+      }
+    }
+    const other = this._readActiveQuiet(localRoot, cwd);
+    const currentActive = current?.activeChanges || [];
+    const otherActive = other?.activeChanges || [];
+
+    out.lines.push(
+      `双进度库并存（接管指针 ${pointerPath} → ${currentSpecDir}；切库前旧库残留 ${localRoot}）` +
+      `——本次 check/repair 只作用于当前库，旧库状态不可见`
+    );
+    out.lines.push(
+      `  当前库活跃变更: ${currentActive.length > 0 ? currentActive.join('、') : '(无)'}${current?.unreadable ? '（读取失败：' + current.error + '）' : ''}`
+    );
+    out.lines.push(
+      `  旧库活跃变更: ${otherActive.length > 0 ? otherActive.join('、') : '(无)'}${other?.unreadable ? '（读取失败：' + other.error + '）' : ''}`
+    );
+    out.lines.push(
+      `  处理：确认权威库后收尾/归档弃用库的活跃变更；或 sillyspec platform pointer --cleanup 删指针后重跑平台 scan 指向正确库；临时读旧库用 --spec-dir ${localRoot}`
+    );
+
+    if (currentActive.length > 0 && otherActive.length > 0) {
+      out.bothActive = true;
+      out.split = true;
+    }
+    // 目标变更只在旧库活跃（当前库查无）→ 本次操作几乎必然找错了库，最强信号
+    if (changeName && otherActive.includes(changeName) && !currentActive.includes(changeName)) {
+      out.targetInOther = true;
+      out.split = true;
+      out.lines.push(
+        `  ⚠️ 目标变更 "${changeName}" 不在当前库，但旧库有同名活跃变更——本次操作错了库，修复应带上 --spec-dir ${localRoot}（或修正指针）`
+      );
+    }
+    return out;
+  }
+
+  /**
+   * 只读读一个库的活跃变更清单（detectLibrarySplit 专用）。
+   * sillyspec.db 不存在返回 null（绝不新建库）；打开/读取失败返回 { unreadable, error }
+   * 不上抛——分裂探测 fail-open，不阻断主流程。
+   */
+  _readActiveQuiet(specDir, cwd) {
+    const dbPath = join(specDir, '.runtime', 'sillyspec.db');
+    if (!existsSync(dbPath)) return null;
+    let db = null;
+    try {
+      db = new DB(dbPath);
+      db.init();
+      const rows = db.getDb().prepare("SELECT name FROM changes WHERE status = 'active' ORDER BY name").all();
+      return { activeChanges: rows.map(r => r.name) };
+    } catch (e) {
+      return { activeChanges: [], unreadable: true, error: e.message };
+    }
+  }
+
   /**
    * 强制状态变更的审计记录（--force 逃生口专用）。
    * 追加到 .runtime/audit.log，供人工/doctor 追溯"谁在什么时候绕过了校验"。
@@ -36,12 +135,26 @@ export class ConsistencyDoctor {
   checkConsistency(cwd, changeName = null) {
     const data = this.pm.read(cwd, changeName);
     if (!data) {
-      return { ok: false, issues: ['无法读取进度数据'], warnings: [] };
+      // 双库分裂探测不依赖单变更 progress 可读（read 失败时更要看见另一库，坑
+      // progress-repair-dual-library-blind）：无 progress 也要报分裂，不能只报「无法读取」
+      const splitNoData = this.detectLibrarySplit(cwd, changeName);
+      const issuesNoData = ['无法读取进度数据'];
+      if (splitNoData.targetInOther || splitNoData.bothActive) issuesNoData.push(...splitNoData.lines);
+      return { ok: false, issues: issuesNoData, warnings: splitNoData.dualDb && !splitNoData.split ? splitNoData.lines : [] };
     }
 
     const issues = [];
     const warnings = [];
 
+    // 双库分裂（2026-09-04 ②）：目标变更只在旧库 / 两库皆有活跃 → issue；
+    // 仅双库并存（单侧活跃）→ warning（平台模式本地库保留真实资产是容忍态，避免常态误报）
+    const libSplit = this.detectLibrarySplit(cwd, changeName);
+    if (libSplit.targetInOther || libSplit.bothActive) {
+      issues.push(...libSplit.lines);
+    } else if (libSplit.dualDb) {
+      warnings.push(...libSplit.lines);
+    }
+
     for (const stageName of STAGE_ORDER) {
       const sd = data.stages[stageName];
       if (!sd) continue;
@@ -186,14 +299,20 @@ export class ConsistencyDoctor {
   repairConsistency(cwd, opts = {}) {
     const { apply = false, changeName = null } = opts;
 
+    // 双库分裂（2026-09-04 ②）：repair 修不了「哪边是权威库」，只能把另一库的存在与活跃
+    // 变更亮出来进 manual 清单。放 read 之前——多活跃/读不了库时 read 早退，探测不能跟着瞎。
+    const libSplit = this.detectLibrarySplit(cwd, changeName);
+    const splitManual = libSplit.dualDb ? [...libSplit.lines] : [];
+
     const data = this.pm.read(cwd, changeName);
     if (!data) {
       console.log('❌ 无法读取进度数据');
-      return { fixable: [], manual: ['无法读取进度数据'], applied: [] };
+      for (const m of splitManual) console.log(`   - ${m}`);
+      return { fixable: [], manual: ['无法读取进度数据', ...splitManual], applied: [] };
     }
 
     const fixable = []; // { stage, action, description, apply: (data) => void }
-    const manual = [];  // string
+    const manual = [...splitManual];  // string
 
     const now = new Date().toLocaleString('zh-CN', { hour12: false });
 

package/src/progress/stage-machine.js

@@ -7,8 +7,19 @@ import { mkdirSync, existsSync, readdirSync, readFileSync } from 'fs';
 import { join, resolve, basename } from 'path';
 import { writeAtomicSync } from '../fs-atomic.js';
 import { runValidators } from '../stage-contract.js';
+import { QUICK_SID_RE } from '../run/shared.js';
 import { VALID_STAGES, STAGE_LABELS, STAGE_ORDER, MAIN_FLOW_ORDER, SPEC_DIR_NAME, CURRENT_VERSION, STALL_WARN_DAYS, emptyStage } from './shared.js';
 
+// quick 会话行（quick-<8hex>）按设计无实体 changes/ 目录（progress.js initChange 跳过建目录），
+// 「DB active + changes/ 无同名目录」的 ghost 判定对它是类别错误——进行中的 quick 从写库那
+// 一刻起即命中误报（2026-09-07 quick-inflight-ghost-misjudge，面板「一键清理」清了又长：
+// 每次清理都成功，新 ghost 是清理后才启动的 quick）。show 与 overview 统一经此判定排除。
+// 注意：排除的只是「判定」，doctor --cleanup-ghosts 仍保留 quick 行归档能力（QUICKLOG 已
+// 完成但 DB 行未注销的收尾中断形态，那是兜底出口，不在此排除）。
+function _isGhostChange(changesRoot, cn) {
+  return !QUICK_SID_RE.test(cn) && !existsSync(join(changesRoot, cn));
+}
+
 /**
  * 归一化步骤的已记录等待回答（show 渲染用，跨会话恢复数据源）。
  * waitAnswers 走 pm.read 时已 JSON.parse，但容错字符串/损坏；单值列 wait_answer（旧路径）并入第 1 轮。
@@ -209,7 +220,7 @@ export class StageMachine {
     const pendingConflicts = this._listPendingConflicts(this.pm._getSpecDir(cwd));
     for (const cn of changes) {
       const data = this.pm.read(cwd, cn);
-      const dirMissing = !existsSync(join(changesRoot, cn));
+      const dirMissing = _isGhostChange(changesRoot, cn);
       if (!data) {
         console.log(`  📂 ${cn} — (无法读取)${dirMissing ? ' ⚠️ 目录缺失（残留记录，sillyspec doctor --cleanup-ghosts --confirm 可归档清理）' : ''}`);
         continue;
@@ -272,7 +283,7 @@ export class StageMachine {
     const list = [];
     for (const cn of changes) {
       const data = this.pm.read(cwd, cn);
-      const dirMissing = !existsSync(join(changesRoot, cn));
+      const dirMissing = _isGhostChange(changesRoot, cn);
       const entry = {
         name: cn,
         readable: !!data,

package/src/progress.js

@@ -868,6 +868,9 @@ export class ProgressManager {
 
   updateChangeMeta(cwd, changeName, meta) { return this._changeRegistry.updateChangeMeta(cwd, changeName, meta); }
 
+  // quick --done 兜底复用启动 ql-ID（坑 platform-takeover-phantom-progress-db 同日变体）
+  getQuicklogId(cwd, changeName) { return this._changeRegistry.getQuicklogId(cwd, changeName); }
+
   // ── CLI 命令 ──
 
   init(cwd) {