sillyspec 3.28.2 → 3.28.4

package/src/index.js

@@ -93,13 +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 fourpiece-init --change <name>     生成 proposal/requirements/decisions 骨架（frontmatter+章节+模板占位；已存在不覆盖）
   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 module-docs-sync --change <name> [--note ...]  diff 归属模块 → sidecar 追加变更索引行 + 卡 updated_at 戳（幂等）
   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（幂等）
@@ -114,6 +119,7 @@ SillySpec CLI — 规范驱动开发工具包
     （无子命令）                       跑诊断，列出问题
     --align-execute-progress [--change <名>] [--confirm]   基于 plan.md 对齐 execute 派生戳（默认 dry-run）
     --cleanup-remnant [--confirm]      删除 0 字节空占位 db（默认 dry-run，仅 --confirm 落盘）
+    --gc-unstamped-runs [--confirm]    回收已归档变更留下的无 change 戳 execute-runs（默认 dry-run）
     --dump-db --path <db 路径>         dump 指定 db 内容到文件（取证用）
     --json                             结构化诊断 + 落盘 .sillyspec/.runtime/doctor-diagnosis.json
   sillyspec modules <rebuild | status | migrate>
@@ -565,6 +571,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
@@ -873,10 +945,53 @@ async function main() {
           writeFileSync(vpReportPath, generateVerifyResultSkeleton(vpResult));
           console.log(`\n📄 已生成 verify-result.md 骨架: ${vpReportPath}（探针已预填；结论必须写明 PASS/FAIL，留待填会被 gate 判不过）`);
         }
-        writeVerifyFacts(join(vpSpecBase, 'changes', vpChange), vpResult, vpChange); // P3b：facts 底稿随 --init 刷新（骨架已存在也刷新，最近快照语义）
+        writeVerifyFacts(join(vpSpecBase, 'changes', vpChange), vpResult, vpChange); // P3b：facts 底稿随 --init 刷新（骨架已存在也刷新；v2 起分段合并保留固化段）
+        // 2026-09-08-ir-verify-facts R-02：已存在 md 缺证据账/回执槽段时仅追加骨架（幂等二跑
+        // 零改动）；task 行按 verify-required-evidence.json 预填（存在时）。
+        if (existsSync(vpReportPath)) {
+          let vpReqItems = []
+          try {
+            const vpReqPath = join(vpSpecBase, 'changes', vpChange, 'verify-required-evidence.json')
+            if (existsSync(vpReqPath)) {
+              const vpReq = JSON.parse(readFileSync(vpReqPath, 'utf8'))
+              vpReqItems = Array.isArray(vpReq.items) ? vpReq.items.map(it => ({ task: it.task, evidence: it.evidence || [] })) : []
+            }
+          } catch { /* 读取失败 → 空预填，不阻断 */ }
+          const { backfillMissingEvidenceSlots } = await import('./verify-probes.js')
+          const vpAdded = backfillMissingEvidenceSlots(vpReportPath, vpReqItems)
+          if (vpAdded.added.length > 0) {
+            console.log(`📄 已补齐缺失槽段（不触碰既有正文）: ${vpAdded.added.join('、')}`)
+          }
+        }
       }
       break;
     }
+    case 'module-docs-sync': {
+      // 模块文档 sidecar 同步命令化（2026-09-09 刀批）：diff 归属模块 → sidecar 追加变更索引行 +
+      // 卡 updated_at 戳——机械部分 CLI 代算，卡片正文语义更新仍归 agent/归档流程。幂等。
+      const mdsChangeIdx = args.indexOf('--change');
+      const mdsChange = mdsChangeIdx >= 0 && args[mdsChangeIdx + 1] ? args[mdsChangeIdx + 1] : null;
+      const mdsNoteIdx = args.indexOf('--note');
+      const mdsNote = mdsNoteIdx >= 0 && args[mdsNoteIdx + 1] ? args[mdsNoteIdx + 1] : null;
+      if (!mdsChange) {
+        console.error('用法: sillyspec module-docs-sync --change <name> [--note "一句话"] [--json]\n  diff 归属模块 → sidecar 追加变更索引行 + 卡 updated_at 戳（幂等；卡片正文语义更新仍归 agent）');
+        process.exit(2);
+      }
+      const { syncModuleDocSidecars } = await import('./module-impact.js');
+      const mdsResult = syncModuleDocSidecars({ cwd: dir, changeName: mdsChange, note: mdsNote, specDir });
+      if (json) {
+        console.log(JSON.stringify({ command: 'module-docs-sync', change: mdsChange, ...mdsResult }, null, 2));
+        break;
+      }
+      if (mdsResult.reason) console.log(mdsResult.reason);
+      if (mdsResult.synced.length > 0) {
+        console.log(String.fromCharCode(9989) + ' sidecar 已同步 ' + mdsResult.synced.length + ' 个模块: ' + mdsResult.synced.join(', '));
+        console.log('   卡 updated_at 已戳；卡片正文语义更新（如需要）仍归归档流程/agent。');
+      }
+      if (mdsResult.skipped.length > 0) console.log(String.fromCharCode(8505) + ' 已含本变更行跳过: ' + mdsResult.skipped.join(', '));
+      if (mdsResult.unmatched.length > 0) console.log(String.fromCharCode(9888) + ' 未匹配模块的文件 ' + mdsResult.unmatched.length + ' 个（不入 sidecar）: ' + mdsResult.unmatched.slice(0, 5).join(', '));
+      break;
+    }
     case 'plan-adopt-waves': {
       // plan.md Wave 段一键重排（坑 wave-manual-mismatch-noise，2026-08-24 用户反馈二期）：
       // 手排 Wave 与拓扑比对不一致需手改；依赖方向硬拦（plan-postcheck）落地后给一条零手写出路。
@@ -1244,6 +1359,94 @@ async function main() {
       console.log('   逐行替换 <!--TODO--> 为结论（无签名级变更也显式写「无」）；gate 拒绝未替换的占位行。');
       break;
     }
+    case 'fourpiece-init': {
+      // 四件套骨架预生成（2026-09-09 ql-20260909-003，轮次经济学 §3.2）：brainstorm 期 agent
+      // 手写 proposal/requirements/decisions 的 frontmatter/章节骨架是格式返工根源——本命令
+      // 逐文件生成骨架（已存在不覆盖），agent 只填语义。与 design-init 同族（幂等）。
+      const fpChangeIdx = args.indexOf('--change');
+      const fpChange = fpChangeIdx >= 0 && args[fpChangeIdx + 1] ? args[fpChangeIdx + 1] : null;
+      if (!fpChange) {
+        console.error('用法: sillyspec fourpiece-init --change <name> [--json] [--spec-dir <path>]\n  生成 proposal.md/requirements.md/decisions.md 骨架（frontmatter+章节标题+模板占位；已存在不覆盖；design.md 归 design-init）');
+        process.exit(2);
+      }
+      const fpSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+      const fpDir = join(fpSpecBase, 'changes', fpChange);
+      mkdirSync(fpDir, { recursive: true });
+      const fpNow = new Date();
+      const fpDate = fpNow.toISOString().slice(0, 10);
+      const fpStamp = fpNow.toISOString().slice(0, 19).replace('T', ' ');
+      const generated = [];
+      const mk = (fname, body) => {
+        const p = join(fpDir, fname);
+        if (existsSync(p)) { console.log(`ℹ️  ${fname} 已存在，不覆盖`); return; }
+        writeFileSync(p, body);
+        generated.push(fname);
+        console.log(`✅ 已生成 ${fname} 骨架: ${p}`);
+      };
+      mk('proposal.md', `---
+author: qinyi
+created_at: ${fpStamp}
+---
+# 提案书（Proposal）
+
+## 动机
+<!--TODO: 为什么做、解决什么核心问题-->
+
+## 关键问题
+<!--TODO: 为什么现有方案不够（2-3 个痛点）-->
+
+## 变更范围
+<!--TODO: 本次做什么-->
+
+## 不在范围内（显式清单）
+- <!--TODO: 不做 X-->
+
+## 成功标准（可验证）
+- <!--TODO: 可验证条目-->
+`);
+      mk('requirements.md', `---
+author: qinyi
+created_at: ${fpStamp}
+---
+# 需求规格（Requirements）
+
+## 角色
+| 角色 | 说明 |
+|---|---|
+| <!--TODO--> | <!--TODO--> |
+
+## 功能需求
+
+### FR-01: <!--TODO-->
+Given <!--TODO-->
+When <!--TODO-->
+Then <!--TODO-->
+
+## 非功能需求
+- 兼容性：<!--TODO-->
+
+## 决策覆盖矩阵（如存在 decisions.md）
+| 决策 ID | 覆盖的 FR | 说明 |
+|---|---|---|
+`);
+      mk('decisions.md', `---
+author: qinyi
+created_at: ${fpStamp}
+change: ${fpChange}
+---
+
+# 决策记录（Decisions）
+
+<!-- 增量落盘：每解决一个有实现影响的问题当场追加一条（格式见 brainstorm Step 3 模板）；幂等按 D-xxx@vN 判重 -->
+`);
+      if (json) {
+        console.log(JSON.stringify({ command: 'fourpiece-init', change: fpChange, generated }, null, 2));
+      } else if (generated.length > 0) {
+        console.log(`
+${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语义内容（骨架勿手删章节）；design.md 用 sillyspec design-init。`);
+      }
+      break;
+    }
     case 'design-init': {
       // design.md 十三章节骨架生成（change: 2026-09-07-ir-stage-p3c，task-02，FR-03）：agent 此前
       // 从零手写整份设计文档，章节漏项到 stage-contract/plan 门禁才暴露。本命令从 decisions.md
@@ -1328,16 +1531,29 @@ async function main() {
       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({
+      // 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: null,
+        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;
@@ -1419,8 +1635,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）。
@@ -1433,14 +1681,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) {
@@ -1450,9 +1698,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);
@@ -1471,6 +1719,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 的行号部分替换为
@@ -1491,6 +1740,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 吞并提示）。
@@ -1503,7 +1777,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 {
@@ -1514,7 +1788,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) {
@@ -1522,26 +1799,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 逐字节一致；决策规则族同款
@@ -1622,7 +1904,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;
@@ -1660,9 +1944,10 @@ async function main() {
     // slice(1) 去掉的是 'run' 字面量，这里 command 本身就是 stage 名不能丢。
     case 'doctor': {
       const doctorEffectiveDir = specDir ? dir : resolveEffectiveDir(dir);
-      // 执行流：--cleanup-remnant / --cleanup-ghosts / --dump-db（结构化诊断之外的修复/取证动作）
+      // 执行流：--cleanup-remnant / --cleanup-ghosts / --gc-unstamped-runs / --dump-db（结构化诊断之外的修复/取证动作）
       const cleanupRemnant = filteredArgs.includes('--cleanup-remnant');
       const cleanupGhosts = filteredArgs.includes('--cleanup-ghosts');
+      const gcUnstampedRuns = filteredArgs.includes('--gc-unstamped-runs');
       const dumpDbFlag = filteredArgs.includes('--dump-db');
       const doctorConfirm = filteredArgs.includes('--confirm');
       const pathIdx = filteredArgs.indexOf('--path');
@@ -1768,6 +2053,29 @@ async function main() {
         process.exitCode = r.errors.length > 0 ? 1 : 0;
         break;
       }
+      if (gcUnstampedRuns) {
+        // ql-20260908-006-5f04：无戳 execute-runs 一次性清扫。默认 dry-run，--confirm 才删。
+        // 不进 archive 热路径（pruneArchivedChangeRuntime 故意不猜无戳 run）。
+        const { gcUnstampedExecuteRuns } = await import('./doctor-diagnostics.js');
+        const r = await gcUnstampedExecuteRuns({ cwd: doctorEffectiveDir, specDir, confirm: doctorConfirm });
+        if (json) {
+          console.log(JSON.stringify(r, null, 2));
+        } else {
+          const verb = doctorConfirm ? '已删除' : '待删除（dry-run）';
+          console.log(`🧹 无戳 execute-runs（仅已归档变更、交叉核验通过）${verb}：${r.count} 个  [runtime: ${r.runtime_root || '(无)'}]`);
+          for (const c of r.candidates || []) {
+            console.log(`   ${doctorConfirm ? '✅' : '-'} ${c.runId} ← ${c.owner}（via ${c.via}）`);
+          }
+          for (const s of r.skipped || []) console.log(`   ⏭️  ${s.runId}（${s.reason}）`);
+          for (const e of r.errors || []) console.log(`   ❌ ${e.runId || ''}: ${e.error}`);
+          if (!doctorConfirm && r.count > 0) {
+            console.log(`\n加 --confirm 执行删除（只删上面列出的无戳 run，有 change 戳 / 命中活跃变更 / 归属不明一律不动）。`);
+          }
+          if (r.reason) console.log(`ℹ️ ${r.reason}`);
+        }
+        process.exitCode = (r.errors && r.errors.length > 0) ? 1 : 0;
+        break;
+      }
       if (dumpDbFlag) {
         if (!dbPath) { console.error('❌ --dump-db 需要 --path <db 路径>'); process.exitCode = 2; break; }
         const { dumpDb } = await import('./doctor-diagnostics.js');
@@ -1794,9 +2102,21 @@ async function main() {
         process.exitCode = output.overall_status === 'pass' ? 0 : 1;
         break;
       }
-      // 否则：保持原有 prompt 驱动的 bash 自检流程
-      const { runCommand } = await import('./run.js');
-      await runCommand([command, ...filteredArgs.slice(1)], doctorEffectiveDir, specDir, { json });
+      // 2026-09-09-doctor-noai：--status 拦截（审查 B-03：等价只读渲染——阶段进度视图，
+      // 零副作用）；非 --json 其余形态改道直跑诊断 + renderDoctorSummary（不走
+      // runCommand/initChange/不刷 lastActive——只读零副作用承诺保真）。
+      if (filteredArgs.includes('--status')) {
+        // 等价只读渲染：复用 progress show（cwd 无活跃变更时提示无——与原只读短路视图同语义级）
+        const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(dir, specDir) });
+        pm.show(doctorEffectiveDir);
+        break;
+      }
+      {
+        const { runDoctorDiagnostics, renderDoctorSummary, writeDoctorDiagnosis } = await import('./doctor-diagnostics.js')
+        const diag = await runDoctorDiagnostics({ cwd: doctorEffectiveDir })
+        console.log(renderDoctorSummary(diag))
+        try { writeDoctorDiagnosis(diag, resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec')) } catch { /* fail-soft */ }
+      }
       break;
     }
     case 'scan': {
@@ -2770,7 +3090,12 @@ checkbox 行；depends_on 自动反填行内注解 "(depends_on: task-01,02)"；
 
       const { cmdTaskcard } = await import('./taskcard.js');
       try {
-        const result = cmdTaskcard(tcName, { cwd: dir, specDir, taskIds, title: titleVal, titleZh: titleZhVal, force, sets });
+        // 坑 platform-sync-progress-rollback-and-db-corruption 坑4：taskcard 此前只走
+        // resolveSpecDir（祖先遍历本地 .sillyspec），不感知平台接管指针——平台模式下
+        // 仓库根裸跑报「变更目录不存在」，需显式 --spec-dir（与 run/plan 系列不一致）。
+        // 对齐 endpoints 等命令：先 resolvePlatformSpecDir（指针 fail-closed 语义同源）。
+        const tcPlatformSpecDir = resolvePlatformSpecDir(dir, specDir) || specDir;
+        const result = cmdTaskcard(tcName, { cwd: dir, specDir: tcPlatformSpecDir, taskIds, title: titleVal, titleZh: titleZhVal, force, sets });
         for (const f of result.created) console.log(`✅ 已生成: ${f}`);
         for (const f of result.skipped) console.log(`⏭️  已存在，跳过（--force 覆盖）: ${f}`);
         if (result.created.length > 0) {