sillyspec 3.28.0 → 3.28.3

package/src/git-helper.js

@@ -13,6 +13,8 @@
  * safeGit 额外支持 opts.retryOnTimeout：ETIMEDOUT（机器忙瞬时抖动）时用 2× timeout 重试一次。
  */
 import { execFileSync } from 'node:child_process'
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
 
 /**
  * git C 风格引号路径解码：`\\` `\"` `\n` `\t` 与 `\NNN` 八进制**原始字节**。
@@ -148,3 +150,32 @@ export function gitQuiet(cwd, args, opts = {}) {
     return null
   }
 }
+
+/**
+ * 归档产物机械暂存（2026-09-05 全流程审计：原 archive 步骤 6 的 3 条 git add agent 指令 CLI 化）。
+ * 固定路径：changes/archive/（归档产物）、knowledge/decisions/（决策提炼）、docs/<project>/modules/
+ * （本次同步的模块文档——按已存在目录枚举，未变的目录 git add 是无害 no-op）。
+ * 只 add 不 commit（统一提交工具处理）；平台模式由调用方跳过（specRoot 在源码仓外）。
+ * @param {string} cwd 源码项目根
+ * @returns {{ staged: string[], skipped: string[] }}
+ */
+export function stageArchiveArtifacts(cwd) {
+  const specBase = join(cwd, '.sillyspec')
+  const candidates = [join(specBase, 'changes', 'archive'), join(specBase, 'knowledge', 'decisions')]
+  const docsRoot = join(specBase, 'docs')
+  try {
+    for (const e of readdirSync(docsRoot, { withFileTypes: true })) {
+      if (e.isDirectory()) candidates.push(join(docsRoot, e.name, 'modules'))
+    }
+  } catch { /* 无 docs 目录 → 跳过 */ }
+  const staged = []
+  const skipped = []
+  const existing = candidates.filter(p => existsSync(p))
+  if (existing.length === 0) return { staged, skipped }
+  const r = safeGit(cwd, ['add', ...existing])
+  if (r && r.error) {
+    console.warn(`  ⚠️ 归档产物 git add 失败（可手动处理）：${String(r.error).slice(0, 120)}`)
+    return { staged, skipped: existing }
+  }
+  return { staged: existing, skipped }
+}

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';
 
@@ -93,12 +93,18 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec gate <stage> --change <name> [--json]      机器门控：阶段能否标记完成（只读）
   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 review write --change <name> --task task-NN --spec <verdict> --quality <verdict>
+                                      [--notes ...] [--evidence ...] [--changed-files a,b] [--force]
+                                      单 task review.json 命令式写入：verdict/notes 你给，base/head/changedFiles/diffPaths CLI 代算
   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   多项目工作区登记与状态探测
@@ -562,6 +568,72 @@ async function main() {
       process.exitCode = exitCode;
       break;
     }
+    case 'review': {
+      // 单 task review.json 命令式写入（2026-09-07 noAI 主流程批次 T2-4）：agent 只给判断字段
+      // （verdict/notes/evidence），mechanics（executeRunId/base/head/changedFiles/diffPaths）全由
+      // CLI 代算——消灭「手拼 JSON→gate 拒→重写」循环与手算 hash 错误面。
+      //   sillyspec review write --change <名> --task task-NN --spec pass --quality pass
+      //     [--notes "..."] [--evidence "..."]（cannot_verify 必填）
+      //     [--changed-files a,b]（归属切片为空或纯验证任务时显式给出；""=空覆盖）
+      //     [--base <rev> --head <rev>]（无 worktree meta 时显式锡点）[--force]
+      const rwSub = filteredArgs[1];
+      if (rwSub !== 'write') {
+        console.error('用法: sillyspec review write --change <名> --task task-NN --spec <pass|fail|cannot_verify> --quality <verdict>\n  [--notes "评审备注"] [--evidence "cannot_verify 证据说明"] [--changed-files a,b] [--base <rev> --head <rev>] [--force] [--json]\n  单 task review.json 命令式写入：verdict/notes 由你给，executeRunId/base/head/changedFiles/diffPaths 由 CLI 从 git + task 卡代算；已存在默认拒覆盖（--force 越过）');
+        process.exit(2);
+      }
+      const rwVal = (flag) => {
+        const i = filteredArgs.indexOf(flag);
+        return i >= 0 && filteredArgs[i + 1] ? filteredArgs[i + 1] : null;
+      };
+      const rwChange = rwVal('--change');
+      const rwTask = rwVal('--task');
+      const rwSpec = rwVal('--spec');
+      const rwQuality = rwVal('--quality');
+      const rwNotes = rwVal('--notes');
+      const rwEvidence = rwVal('--evidence');
+      const rwBase = rwVal('--base');
+      const rwHead = rwVal('--head');
+      const rwFilesIdx = filteredArgs.indexOf('--changed-files');
+      // --changed-files 存在即视为显式覆盖（含空串=纯验证任务零 diff 声明）；不存在传 null 走归属切片
+      const rwFilesOverride = rwFilesIdx >= 0
+        ? (filteredArgs[rwFilesIdx + 1] || '').split(',').map(s => s.trim()).filter(Boolean)
+        : null;
+      if (!rwChange || !rwTask || !rwSpec || !rwQuality) {
+        console.error('用法: sillyspec review write --change <名> --task task-NN --spec <verdict> --quality <verdict> [--notes ...] [--evidence ...] [--changed-files a,b] [--base <rev> --head <rev>] [--force]');
+        process.exit(2);
+      }
+      assertSafeChangeName(rwChange, '--change 变更名');
+      const { writeTaskReview } = await import('./task-review.js');
+      const rwPlatformOpts = {};
+      const rwResolved = resolvePlatformOpts(dir, specDir);
+      if (rwResolved) {
+        rwPlatformOpts.specRoot = rwResolved.specRoot;
+        if (rwResolved.runtimeRoot) rwPlatformOpts.runtimeRoot = rwResolved.runtimeRoot;
+      }
+      const rwResult = await writeTaskReview({
+        changeName: rwChange, cwd: dir, taskId: rwTask,
+        specVerdict: rwSpec, qualityVerdict: rwQuality,
+        reviewerNotes: rwNotes || '',
+        requiredEvidence: rwEvidence ? [rwEvidence] : [],
+        baseOverride: rwBase, headOverride: rwHead,
+        changedFilesOverride: rwFilesOverride,
+        force: filteredArgs.includes('--force'),
+        platformOpts: rwPlatformOpts,
+      });
+      if (json) {
+        console.log(JSON.stringify({ ok: rwResult.ok, ...rwResult }, null, 2));
+      } else if (rwResult.ok) {
+        console.log(`✅ review.json 已写入：${rwResult.reviewPath}`);
+        console.log(`   executeRunId: ${rwResult.executeRunId}`);
+        for (const w of rwResult.warnings) console.log(`⚠️  ${w}`);
+      } else {
+        console.error('❌ review write 失败：');
+        for (const e of rwResult.errors) console.error(`   - ${e}`);
+        for (const w of rwResult.warnings) console.error(`⚠️  ${w}`);
+        process.exit(1);
+      }
+      break;
+    }
     case 'backfill-reviews': {
       // 手动补 task（reopen execute / 直接实现）缺 review.json 的官方入口（坑 verify-archive-flow-pitfalls 坑2）。
       // 复用 generateTaskReviewDrafts（execute --done 同源兜底，幂等、fail-open）：据 git diff base..head + working-tree
@@ -833,7 +905,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 +923,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 +1032,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 +1313,121 @@ 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');
+      // project 同口径修复（change: 2026-09-07-ir-hardening D-005@v1）：此前硬编码 null →
+      // 手动补跑恒走 loadModuleMap 降级（报告恒「无 module-map」注记）。改从 progress.project
+      // 取值（与归档确认步自动生成同源），null 兜底降级不变。
+      let dlProject = null;
+      try {
+        const { ProgressManager } = await import('./progress.js');
+        const dlPm = new ProgressManager({ specDir: dlSpecBase });
+        const dlProgress = dlPm.read(cwd, dlChange);
+        dlProject = dlProgress?.project || null;
+      } catch { /* 读 progress 失败 → null 兜底降级（fail-soft） */ }
+      const dlResult = buildDeltaReport({
+        changeDir: dlChangeDir,
+        specRoot: dlSpecBase,
+        project: dlProject,
+        runtimeRoot: dlRuntimeRoot,
+        withSummary: true,
+      });
+      const dlMarkdown = dlResult.markdown;
+      const dlPath = join(dlChangeDir, 'delta.md');
+      writeFileSync(dlPath, dlMarkdown);
+      // 回灌 sidecar（2026-09-07-ir-hardening D-006）：fail-soft，写失败不阻断 delta 输出
+      const { writeLastDeltaSidecar } = await import('./archive-delta.js');
+      writeLastDeltaSidecar(dlRuntimeRoot, dlResult);
+      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
@@ -1229,8 +1501,40 @@ async function main() {
     case 'docs': {
       const docsSubCmd = filteredArgs[1];
       if (docsSubCmd === 'migrate') {
-        const { migrateDocs } = await import('./migrate.js');
-        migrateDocs(dir);
+        // docs migrate 双形态（2026-09-08-docs-fix-capability / D-002+D-004）：
+        //   有 --from/--to → 新语义（路径引用前缀迁移，薄模块 docs-migrate.js）
+        //   无 flag → 旧语义（.sillyspec 结构一次性迁移 migrateDocs，兼容保留）
+        const rawMigrateArgs = filteredArgs.slice(2);
+        let mFrom = null, mTo = null, mApply = false;
+        for (let i = 0; i < rawMigrateArgs.length; i++) {
+          const a = rawMigrateArgs[i];
+          if (a === '--from' && rawMigrateArgs[i + 1] !== undefined) { mFrom = rawMigrateArgs[i + 1]; i++; }
+          else if (a === '--to' && rawMigrateArgs[i + 1] !== undefined) { mTo = rawMigrateArgs[i + 1]; i++; }
+          else if (a === '--apply') { mApply = true; }
+          else if (a === '--from' || a === '--to') {
+            console.error(`❌ docs migrate: ${a} 缺值（如 --from "modules/" --to "backend/app/modules/"）`);
+            process.exit(2);
+          } else if (a.startsWith('--')) {
+            console.error(`❌ docs migrate: 未知 flag「${a}」。已知 flag：--from --to --apply`);
+            process.exit(2);
+          }
+        }
+        if (mFrom !== null || mTo !== null) {
+          if (mFrom === null || mTo === null) {
+            console.error('❌ docs migrate: --from 与 --to 必须成对提供');
+            process.exit(2);
+          }
+          const { runDocsMigrate } = await import('./docs-migrate.js');
+          const result = runDocsMigrate({ projectRoot: dir, from: mFrom, to: mTo, apply: mApply });
+          // exit code 契约：0=dry-run 零计划或 --apply 后 postCheck 全绿；1=--apply 后仍失效或
+          // unverified>0；dry-run 有计划恒 0（预览不判成败）
+          if (!mApply) { process.exit(0); }
+          const fail = result.unverified > 0 || (result.postCheck && result.postCheck.invalid > 0);
+          process.exit(fail ? 1 : 0);
+        } else {
+          const { migrateDocs } = await import('./migrate.js');
+          migrateDocs(dir);
+        }
       } else if (docsSubCmd === 'check') {
         // docs check（2026-08-15 docs-check-productize D-6）：文档 file:line 引用校验。
         // exit code 三档（D-003）：0 全绿 / 1 存在无效引用 / 2 配置/IO 错误（DocsCheckConfigError）。
@@ -1243,14 +1547,14 @@ async function main() {
         // 写回）；--dry-run 预览不写盘，单独传（无 --fix）也走预览路径——design §5.2 行为矩阵
         // --dry-run 列独立存在（「报告修复预览 + exit 1」），即 dryRun 置位 = fix 语义自动生效
         // 但零写盘（本口径记录于此，防歧义）。
-        const BARE_FLAGS = ['--suggest', '--fix', '--dry-run'];
+        const BARE_FLAGS = ['--fix', '--dry-run', '--no-exempt'];
         const PAIRED_FLAGS = ['--paths'];
         const rawDocsArgs = filteredArgs.slice(2);
         const docsCheckFlags = [];
         let cliPaths = null;
-        let suggest = false;
         let fix = false;
         let dryRun = false;
+        let noExempt = false;
         for (let i = 0; i < rawDocsArgs.length; i++) {
           const a = rawDocsArgs[i];
           if (a === '--paths' && rawDocsArgs[i + 1] !== undefined) {
@@ -1260,9 +1564,9 @@ async function main() {
             console.error('❌ docs check: --paths 缺值（逗号分隔 glob，如 --paths "docs/**/*.md"）');
             process.exit(2);
           } else if (BARE_FLAGS.includes(a)) {
-            if (a === '--suggest') suggest = true;
-            else if (a === '--fix') fix = true;
+            if (a === '--fix') fix = true;
             else if (a === '--dry-run') dryRun = true;
+            else if (a === '--no-exempt') noExempt = true;
           } else if (a.startsWith('--')) {
             console.error(`❌ docs check: 未知 flag「${a}」。已知 flag：${[...BARE_FLAGS, ...PAIRED_FLAGS].join(' ')}（--json 为全局 flag）`);
             process.exit(2);
@@ -1281,6 +1585,7 @@ async function main() {
             skip: cfg.skip,
             keywordAssert: cfg.keywordAssert,
             crossRepoRoots: cfg.crossRepoRoots,
+            exempt: !noExempt,
           });
           // task-03 修复链路（FR-04，platform-map-auto-anchors）：fixActive 才构造 fixes——
           // 仅 fix.fixable===true 且 newLine 为整数的条目可重锚；newRef = ref 的行号部分替换为
@@ -1301,6 +1606,31 @@ async function main() {
             }
           }
           const fixResult = fixActive ? applyFixes(dir, fixes, dryRun ? { dryRun: true } : {}) : null;
+          // 修复回执（change: 2026-09-07-ir-hardening D-007@v1，FR-04）：--fix 落盘后用与首查
+          // 完全相同的口径重跑一次失效收集，得 after 计数——「前 N → 重锚 M → 后 K（消除 N-K）」
+          // 即修复建议被机器证明消除了多少诊断（acceptsFix 最小件）。仅 --fix（写盘）路径；
+          // --dry-run 不写盘重跑无意义，receipt 为 null；非 fix 路径零变化。
+          let fixReceipt = null;
+          if (fix && !dryRun && fixResult && fixResult.applied > 0) {
+            try {
+              const after = runDocsCheck({
+                projectRoot: dir,
+                docs: docsCheckFlags.length > 0 ? docsCheckFlags : null,
+                paths: cliPaths || cfg.paths,
+                skip: cfg.skip,
+                keywordAssert: cfg.keywordAssert,
+                crossRepoRoots: cfg.crossRepoRoots,
+              });
+              fixReceipt = {
+                invalidBefore: result.invalid.length,
+                reAnchored: fixResult.applied,
+                invalidAfter: after.invalid.length,
+                eliminated: result.invalid.length - after.invalid.length,
+              };
+            } catch (e) {
+              console.warn(`⚠️ 修复回执重算失败（不影响修复本身）：${e && e.message ? e.message : e}`);
+            }
+          }
           // 变更名提名 advisory（2026-08-31 变更关联审计 P2）：铁律同决策规则族——只 warn，
           // 不进 invalid、不影响下方 exit code 与 docs gate。降级容错：advisory 自身异常
           // 不拖垮主检查（try-catch 吞并提示）。
@@ -1313,7 +1643,7 @@ async function main() {
           if (json) {
             // --fix 与 --json 组合保持 stdout 纯 JSON 可解析（constraints）：修复统计作 result.fixReport
             // 附加后整体 stringify，主体仍是 runDocsCheck 返回（invalid[].fix 是 task-01 设计内增量）
-            if (fixResult) result.fixReport = { applied: fixResult.applied, skipped: fixResult.skipped.length, dryRun };
+            if (fixResult) result.fixReport = { applied: fixResult.applied, skipped: fixResult.skipped.length, dryRun, ...(fixReceipt ? { receipt: fixReceipt } : {}) };
             if (changeNameReport) result.changeNameReport = changeNameReport;
             console.log(JSON.stringify(result, null, 2));
           } else {
@@ -1324,7 +1654,10 @@ async function main() {
             if (result.ok) {
               console.log(`✅ docs check: ${result.total} 处引用全通过（其中 ${result.kwChecked} 处带关键词断言）`);
             } else {
-              console.error(`\n❌ docs check: ${result.invalid.length}/${result.total} 处引用失效：`);
+              // FR-5（D-005，2026-09-08-docs-fix-capability）：报告内容统一 stdout（脚本 capture_output
+              // 只读 stdout 可捕获）；stderr 仅留 ⚠️ 诊断（console.warn）与配置错误（exit 2 路径）。
+              // 文本逐字不变，只改通道。
+              console.log(`\n❌ docs check: ${result.invalid.length}/${result.total} 处引用失效：`);
               let appliedLeft = fixResult ? fixResult.applied : 0;
               const skippedQueue = fixResult ? [...fixResult.skipped] : [];
               for (const inv of result.invalid) {
@@ -1332,26 +1665,31 @@ async function main() {
                 if (newRef !== undefined && appliedLeft > 0) {
                   // 已应用（dry-run 为将应用）：归因按构造顺序消耗 applied 计数——写回 skipped 仅
                   // 防御路径（文档消失/行内失配）触发，CLI 正常流 fixable 必然落位
-                  console.error(`  ✅ [${inv.doc}:L${inv.docLine}] ${inv.ref} → ${newRef}${dryRun ? '（dry-run 未写盘）' : ''}`);
+                  console.log(`  ✅ [${inv.doc}:L${inv.docLine}] ${inv.ref} → ${newRef}${dryRun ? '（dry-run 未写盘）' : ''}`);
                   appliedLeft--;
                 } else if (newRef !== undefined) {
                   const s = skippedQueue.shift();
-                  console.error(`  ⚠️ [${inv.doc}:L${inv.docLine}] ${inv.ref} → 写回跳过：${s ? s.reason : '未知原因'}`);
+                  console.log(`  ⚠️ [${inv.doc}:L${inv.docLine}] ${inv.ref} → 写回跳过：${s ? s.reason : '未知原因'}`);
                 } else if (fixResult) {
                   // needs-manual：多命中歧义/零命中/无 token——fix.reason 含候选行号，交人工
-                  console.error(`  ❌ [${inv.doc}:L${inv.docLine}] ${inv.ref} → ${(inv.fix && inv.fix.reason) || inv.reason}（待人工）`);
+                  console.log(`  ❌ [${inv.doc}:L${inv.docLine}] ${inv.ref} → ${(inv.fix && inv.fix.reason) || inv.reason}（待人工）`);
                 } else {
-                  console.error(`  ❌ [${inv.doc}:L${inv.docLine}] ${inv.ref} → ${inv.reason}`);
+                  console.log(`  ❌ [${inv.doc}:L${inv.docLine}] ${inv.ref} → ${inv.reason}`);
                 }
-                if (suggest && inv.suggest && inv.suggest.length > 0) {
-                  console.error(`     💡 候选行号: ${inv.suggest.join(', ')}（token 命中行，人工确认后更新文档锚）`);
+                if (inv.suggest && inv.suggest.length > 0) {
+                  // 2026-09-07-ir-hardening task-08：原 --suggest 旗标删除（no-op 首选路径退役），
+                  // 候选行号提示改为 needs-manual 默认输出——旗标唯一用途，默认开更有信息量
+                  console.log(`     💡 候选行号: ${inv.suggest.join(', ')}（token 命中行，人工确认后更新文档锚）`);
                 }
               }
               if (fixResult) {
-                console.error(`\n🔧 重锚报告：${fixResult.applied} 处已${dryRun ? '预览' : '改写'}${dryRun ? '（dry-run 未写盘）' : ''}、${result.invalid.length - fixes.length} 处待人工${fixResult.skipped.length > 0 ? `、${fixResult.skipped.length} 处写回跳过` : ''}。`);
+                console.log(`\n🔧 重锚报告：${fixResult.applied} 处已${dryRun ? '预览' : '改写'}${dryRun ? '（dry-run 未写盘）' : ''}、${result.invalid.length - fixes.length} 处待人工${fixResult.skipped.length > 0 ? `、${fixResult.skipped.length} 处写回跳过` : ''}。`);
+              if (fixReceipt) {
+                console.log(`🔁 修复回执（机器复跑证明）：修复前 ${fixReceipt.invalidBefore} 处失效 → 重锚 ${fixReceipt.reAnchored} 处 → 修复后 ${fixReceipt.invalidAfter} 处（消除 ${fixReceipt.eliminated} 处）。`);
               }
-              console.error(`\n修复指引：行号漂移 → 更新文档行号到当前源码；文件删改名 → 更新引用路径；`);
-              console.error(`关键词缺失但行号正确 → 确认符号是否改名，改文档 token 或行号。`);
+              }
+              console.log(`\n修复指引：行号漂移 → 更新文档行号到当前源码；文件删改名 → 更新引用路径；`);
+              console.log(`关键词缺失但行号正确 → 确认符号是否改名，改文档 token 或行号。`);
             }
             // 变更名提名 advisory 段（主结果之后、exit 之前；不参与 ok/invalid 与 exit code）。
             // 零输出原则（docs-check-fix 契约：无新 flag 时 stdout 逐字节一致；决策规则族同款
@@ -1432,7 +1770,9 @@ async function main() {
         }
         process.exit(g.exitCode);
       } else {
-        console.log('用法: sillyspec docs migrate | sillyspec docs check [--paths <glob,...>] [--json] [--suggest] [--fix] [--dry-run] | sillyspec docs gate [--init-baseline] [--json]');
+        console.log('用法: sillyspec docs migrate [--from <旧前缀> --to <新前缀> [--apply]] | sillyspec docs check [--paths <glob,...>] [--json] [--fix] [--dry-run] [--no-exempt] | sillyspec docs gate [--init-baseline] [--json]');
+        console.log('  docs migrate：--from/--to 路径前缀迁移（默认 dry-run，--apply 写盘+自动复核）；无 flag = 旧 .sillyspec 结构迁移');
+        console.log('  docs check --no-exempt：archive/finished 与 doc_type: snapshot 文档照常校验（缺省豁免）');
         process.exit(2);
       }
       break;
@@ -1610,6 +1950,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。