sillyspec 3.28.3 → 3.28.5

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, sep } from 'path';
+import { basename, dirname, extname, join, resolve, isAbsolute, sep, relative } from 'path';
 import { safeGit, git } from './git-helper.js';
 import { getVersion } from './version.js';
 
@@ -98,11 +98,14 @@ SillySpec CLI — 规范驱动开发工具包
                                       单 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 scope-audit --change <name> [--json]  变更范围对账：计划×实际三态全表 + 行数（✓ 计划内/⚠️ 计划外/⚠️ 计划未动；quick 会话传 quick-<id> 出归属表；已归档变更可查——快照记录态；advisory 只读不设门禁）
+  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（幂等）
@@ -117,6 +120,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>
@@ -625,6 +629,13 @@ async function main() {
       } else if (rwResult.ok) {
         console.log(`✅ review.json 已写入：${rwResult.reviewPath}`);
         console.log(`   executeRunId: ${rwResult.executeRunId}`);
+        // P2-f（noai-ir-roadmap §5）task 真源归一：review 落盘即由 CLI 渲染 checkbox——
+        // agent 永不手勾（review.json verdict 是唯一真源，tasks.md 勾选是它的显示态）。
+        try {
+          const { autoCheckPlanFromReviews } = await import('./run/complete.js');
+          const ac = await autoCheckPlanFromReviews({ stageName: 'execute', changeName: rwChange, cwd: dir, platformOpts: rwPlatformOpts });
+          if (ac.autoChecked && ac.checkedCount > 0) console.log(`   ✅ tasks.md checkbox 已按 review verdict 自动勾选（${ac.checkedCount} 个；task 真源 = review.json，CLI 唯一勾选者——勿手动勾选）`);
+        } catch { /* 勾选 fail-soft：--done 时 autoCheck 兜底 */ }
         for (const w of rwResult.warnings) console.log(`⚠️  ${w}`);
       } else {
         console.error('❌ review write 失败：');
@@ -814,8 +825,22 @@ async function main() {
       // 项目状态探测（2026-08-21 审计第二批 G7/G8）：吸收 continue/resume 两个 skill 的
       // 手工探测表（文件存在性状态机），一条命令输出「状态 + 下一步命令 + 依据」。
       // 纯 fs 零 token；活跃进度的权威状态仍归 progress show，本命令管无活跃进度时反推。
+      // --apply（P2，noai-ir-roadmap §5）：建议是本 CLI 命令形态时直接代跑（恢复链 noAI——
+      // 只建议不执行让 agent 当转述员）；非 CLI 命令形态的建议（自由文本）不代跑。
       const { detectNextStep } = await import('./run/next.js');
       const nxResult = detectNextStep({ cwd: dir, specDir });
+      if (args.includes('--apply')) {
+        const m = String(nxResult.next || '').match(/^sillyspec\s+(.+)$/);
+        if (!m) {
+          console.error(`❌ next --apply：建议不是可代跑的 CLI 命令形态（实得「${nxResult.next}」）——按建议手动执行`);
+          process.exit(2);
+        }
+        const childArgs = m[1].trim().split(/\s+/);
+        console.log(`🤖 next --apply 代跑：sillyspec ${childArgs.join(' ')}\n`);
+        const { spawnSync } = await import('node:child_process');
+        const r = spawnSync(process.execPath, [join(__dirname, '..', 'bin', 'sillyspec.js'), '--dir', dir, ...childArgs], { stdio: 'inherit' });
+        process.exit(r.status === null ? 1 : r.status);
+      }
       if (json) {
         console.log(JSON.stringify({ command: 'next', ...nxResult }, null, 2));
         break;
@@ -837,7 +862,30 @@ async function main() {
       // 智能提交建议（2026-08-21 审计第二批 G1-G3）：commit skill 此前让 agent 手工收集
       // 语义（LAST_COMMIT_TIME / cat QUICKLOG / 扫变更目录 / 按路径模式分类）——进度库、
       // quicklog、git 全在 CLI 手里。一条命令产出统计 + 语义来源 + conventional 建议 +
-      // 可照抄的 git 命令。**只建议不执行**（确认权在人，对齐 skill 绝对规则「不要自动提交」）。
+      // 可照抄的 git 命令。**默认只建议不执行**（确认权在人，对齐 skill 绝对规则「不要自动提交」）；
+      // --apply（P1-6，noai-ir-roadmap §4）唯一例外且只限归档语境（文件已验收 + pathspec
+      // 显式 + pathspec 限定 commit 不扫并行会话暂存）——agent 上下文「需人确认」是伪约束，
+      // 通用自动 git 在多会话仓是历史重灾区，故收窄到这一处。
+      if (args.includes('--apply')) {
+        const apChangeIdx = args.indexOf('--change');
+        const apChange = apChangeIdx >= 0 && args[apChangeIdx + 1] ? args[apChangeIdx + 1] : null;
+        if (!apChange) {
+          console.error('用法: sillyspec commit --apply --change <名>\n  只限归档语境（changes.status=archived 或 current_stage=archive）执行归档产物提交');
+          process.exit(2);
+        }
+        assertSafeChangeName(apChange, '--change 变更名');
+        const { applyArchiveCommit } = await import('./commit-suggest.js');
+        const r = applyArchiveCommit({ cwd: dir, specDir, changeName: apChange });
+        if (!r.ok) {
+          console.error(`❌ commit --apply 拒绝: ${r.reason}`);
+          process.exit(1);
+        }
+        console.log(`✅ 归档提交完成（pathspec 限定 ${r.paths.length} 个路径，不含并行会话暂存）：`);
+        for (const p of r.paths) console.log(`   - ${p}`);
+        console.log(`\n💬 ${r.subject}`);
+        if (r.output) console.log(r.output.split('\n').map(l => '   ' + l).join('\n'));
+        break;
+      }
       const { collectCommitContext } = await import('./commit-suggest.js');
       const cc = collectCommitContext({ cwd: dir, specDir });
       if (json) {
@@ -884,7 +932,8 @@ async function main() {
           console.log(cc.suggestion.body.split('\n').map(l => '   ' + l).join('\n'));
         }
         const bodyArgs = cc.suggestion.body ? ` -m "${cc.suggestion.body.replace(/"/g, '\\"').replace(/\n/g, ' ')}"` : '';
-        console.log(`\n   执行：git add -A && git commit -m "${cc.suggestion.subject.replace(/"/g, '\\"')}"${bodyArgs}`);
+        // 规则 18（2026-09-10 目录级 git add 事故）：建议命令用显式 pathspec，不再教 git add -A
+        console.log(`\n   执行：git add -- <本次文件…> && git commit -m "${cc.suggestion.subject.replace(/"/g, '\\"')}"${bodyArgs} -- <本次文件…>`);
       } else {
         console.log('\n💡 无语义来源匹配——请结合上方 diff stat 手写 message');
       }
@@ -905,7 +954,7 @@ async function main() {
         process.exit(2);
       }
       assertSafeChangeName(vpChange, '--change 变更名');
-      const { runVerifyProbes, renderVerifyProbesReport, generateVerifyResultSkeleton, resolveVerifyProbesSpecBase, writeVerifyFacts } = await import('./verify-probes.js');
+      const { runVerifyProbes, renderVerifyProbesReport, generateVerifyResultSkeleton, resolveVerifyProbesSpecBase, writeVerifyFacts, formatPlatformPathNote } = await import('./verify-probes.js');
       // spec 根统一走漂移锚定（坑 worktree-spec-artifact-misplace）：在 worktree 内跑时锚回主仓，
       // 探针读取与 --init 骨架都落主仓——与 plan/execute/verify/archive 的 command.js 守卫同口径。
       // resolvePlatformSpecDir 仍先调（保留平台接管 fail-closed 检查副作用），但仅 pointer 存在时
@@ -914,6 +963,19 @@ async function main() {
       const vpResolved = resolvePlatformSpecDir(dir, specDir);
       const vpPlatformBase = existsSync(join(dir, '.sillyspec-platform.json')) ? vpResolved : null;
       const vpSpecBase = resolveVerifyProbesSpecBase(dir, specDir, vpPlatformBase);
+      // 平台模式回显注记（2026-09-10 驾驭小结②）：物理路径在 hub 镜像根，产物经 daemon
+      // spec-sync 落主仓——回显补主仓同步位置，消「回显镜像路径 / 核对主仓路径」的显示混乱
+      const vpPlatformNote = formatPlatformPathNote(vpPlatformBase, vpChange, 'verify-result.md');
+      // 平台模式双写镜像（坑 platform-init-artifact-daemon-dir-only，2026-09-10 驾驭小结第三批②）：
+      // agent 本地（pointer 态、非显式 --spec-dir）--init 产物同时镜像主仓 changeDir，不再单点
+      // 依赖 spec-sync 回程（用户两次实锤产物落 daemon specs 同步目录）。
+      const mirrorInitArtifact = async (platformPath, file, content) => {
+        if (!vpPlatformBase || specDir) return null
+        try {
+          const { mirrorPlatformArtifactToMainRepo } = await import('./run/shared.js')
+          return mirrorPlatformArtifactToMainRepo({ cwd: dir, changeName: vpChange, file, content, platformBase: vpPlatformBase })
+        } catch { return null }
+      }
       const vpResult = runVerifyProbes({ cwd: dir, changeName: vpChange, specDir: vpSpecBase });
       if (json) {
         console.log(JSON.stringify({ command: 'verify-probes', change: vpChange, ...vpResult }, null, 2));
@@ -933,17 +995,155 @@ async function main() {
             // 指引「重跑 --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}（正文其余未动；补注后按新预填段如实核对结论）`);
+            const vpInjected = vpExisting.replace(/\s*$/, '\n') + vpSection;
+            writeFileSync(vpReportPath, vpInjected);
+            await mirrorInitArtifact(vpReportPath, 'verify-result.md', vpInjected);
+            console.log(`\n📄 存量旧格式 verify-result.md 已补注入探针预填段: ${vpReportPath}（正文其余未动；补注后按新预填段如实核对结论）${vpPlatformNote}`);
           } else {
-            console.log(`\nℹ️  verify-result.md 已存在，不覆盖: ${vpReportPath}`);
+            console.log(`\nℹ️  verify-result.md 已存在，不覆盖: ${vpReportPath}${vpPlatformNote}`);
           }
         } else {
-          writeFileSync(vpReportPath, generateVerifyResultSkeleton(vpResult));
-          console.log(`\n📄 已生成 verify-result.md 骨架: ${vpReportPath}（探针已预填；结论必须写明 PASS/FAIL，留待填会被 gate 判不过）`);
+          const vpSkeleton = generateVerifyResultSkeleton(vpResult);
+          writeFileSync(vpReportPath, vpSkeleton);
+          await mirrorInitArtifact(vpReportPath, 'verify-result.md', vpSkeleton);
+          console.log(`\n📄 已生成 verify-result.md 骨架: ${vpReportPath}（探针已预填；结论必须写明 PASS/FAIL，留待填会被 gate 判不过）${vpPlatformNote}`);
+        }
+        const vpFacts = writeVerifyFacts(join(vpSpecBase, 'changes', vpChange), vpResult, vpChange, {
+          platformNote: formatPlatformPathNote(vpPlatformBase, vpChange, 'verify-facts.json'),
+        }); // P3b：facts 底稿随 --init 刷新（骨架已存在也刷新；v2 起分段合并保留固化段）
+        if (vpFacts && vpFacts.path) {
+          try { await mirrorInitArtifact(vpFacts.path, 'verify-facts.json', readFileSync(vpFacts.path, 'utf8')) } catch { /* 读回失败跳过镜像 */ }
+        }
+        // 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('、')}`)
+          }
         }
-        writeVerifyFacts(join(vpSpecBase, 'changes', vpChange), vpResult, vpChange); // P3b：facts 底稿随 --init 刷新（骨架已存在也刷新，最近快照语义）
+        // P0-1（noai-ir-roadmap §3）两件机械预填，均幂等 fail-soft：
+        //   ①决策追踪矩阵机械半边——D→FR→task 链自 decisions.md × tasks/*.md frontmatter
+        //     结构化字段构建，Evidence/状态两列留 agent 逐格复核；
+        //   ②结论草稿——机械事实全绿（noAI 实测 + 探针 1/3/5/6 + 风险门）才预填 PASS，
+        //     「草稿待确认」形态，gate 判定链不动（前置三）。
+        try {
+          const { injectDecisionChainDraft } = await import('./verify-probes.js')
+          const vpChain = injectDecisionChainDraft(vpReportPath, join(vpSpecBase, 'changes', vpChange))
+          if (vpChain) {
+            try { await mirrorInitArtifact(vpReportPath, 'verify-result.md', readFileSync(vpReportPath, 'utf8')) } catch { /* 镜像失败不阻断 */ }
+            console.log(`🔗 决策追踪矩阵机械半边已预填：${vpChain.decisions} 条决策 × ${vpChain.tasks} 张 task 卡（Evidence/状态两列待逐格复核；未闭环行须在报告标注风险）`)
+          }
+        } catch { /* 链路预填失败不阻断 --init */ }
+        try {
+          const { extractVerifyConclusionSlot } = await import('./stage-contract.js')
+          const { evaluateConclusionDraft } = await import('./run/verify-quality-scan.js')
+          const { applyConclusionDraftToText } = await import('./verify-probes.js')
+          const vpMd = readFileSync(vpReportPath, 'utf8')
+          if (extractVerifyConclusionSlot(vpMd) === '') {
+            const vpDraftEval = evaluateConclusionDraft({ cwd: dir, specBase: vpSpecBase, changeName: vpChange, changeDir: join(vpSpecBase, 'changes', vpChange), probesResult: vpResult })
+            if (vpDraftEval.draft) {
+              const vpNext = applyConclusionDraftToText(vpMd, vpDraftEval.draft)
+              writeFileSync(vpReportPath, vpNext)
+              try { await mirrorInitArtifact(vpReportPath, 'verify-result.md', vpNext) } catch { /* 镜像失败不阻断 */ }
+              console.log(`🤖 结论草稿已预填 ${vpDraftEval.draft}（机械事实全绿：noAI 实测通过 + 探针 1/3/5/6 干净 + 风险门非 integration/deployment）——草稿待确认，复核后不同意即改写槽行；gate 独立复核不受预填影响。`)
+            } else {
+              console.log(`ℹ️  结论草稿未预填（${vpDraftEval.reasons.join('；')}）——槽行由你填写。`)
+            }
+          }
+        } catch { /* 草稿预填失败不阻断 --init */ }
+      }
+      break;
+    }
+    case 'review-dispatch': {
+      // tier=independent 独立审查的平台派发命令（2026-09-10-review-dispatch FR-01~04 / D-001~003@1）：
+      // 三形态——缺省=create（probe 三层前置 + createMission(external) + dispatchWorker(read_only)，
+      // 异步立即返回）、--status=轮询+停滞检测+终态回收（artifacts→schema/docHash 校验→落盘既有
+      // stage-reviews 路径）、--kill=清在途记录+平台处置指引（处置权在人）。薄壳：全部逻辑在
+      // src/review-dispatch.js（可测核心），此处只做 flag 解析与退出码。
+      const rdChangeIdx = args.indexOf('--change');
+      const rdChange = rdChangeIdx >= 0 && args[rdChangeIdx + 1] ? args[rdChangeIdx + 1] : null;
+      const rdStageIdx = args.indexOf('--stage');
+      const rdStage = rdStageIdx >= 0 && args[rdStageIdx + 1] ? args[rdStageIdx + 1] : null;
+      const rdStatus = args.includes('--status');
+      const rdKill = args.includes('--kill');
+      const rdMode = rdKill ? 'kill' : rdStatus ? 'status' : 'create';
+      const rdUsage = '用法: sillyspec review-dispatch --change <名> --stage <brainstorm|plan|execute> [--status] [--kill]\n' +
+        '  缺省=派发（probe 前置→create_mission(external)→dispatch_worker(read_only)，异步返回 missionId）\n' +
+        '  --status=轮询状态+停滞提示；worker completed 自动回收落盘 review.json（reviewer.channel=platform）\n' +
+        '  --kill=清本地在途记录+平台处置指引（不自动 kill，处置权在人）';
+      if (!rdChange) { console.error(rdUsage); process.exit(2); }
+      assertSafeChangeName(rdChange, '--change 变更名');
+      if (rdMode === 'create' && !['brainstorm', 'plan', 'execute'].includes(rdStage)) {
+        console.error(`❌ create 形态必须 --stage ∈ brainstorm|plan|execute（实际：${rdStage || '缺'}）\n${rdUsage}`);
+        process.exit(2);
+      }
+      const { runReviewDispatch, readReviewDispatchConfig } = await import('./review-dispatch.js');
+      const rdCfg = readReviewDispatchConfig(dir);
+      // MCP client：kill 不需要网络；create/status 需要（未配置时核心层 probe no-config 退出并给降级指引）
+      let rdClient = null;
+      if (rdMode !== 'kill') {
+        const { SillyHubMcpClient } = await import('./sillyhub-mcp/client.js');
+        rdClient = new SillyHubMcpClient({ cwd: dir });
+      }
+      // specBase：与其他顶级命令同口径（平台接管优先；无 pointer 回退本地 .sillyspec）
+      const rdSpecBase = resolvePlatformSpecDir(dir, specDir);
+      const r = await runReviewDispatch({
+        mode: rdMode, cwd: dir, specBase: rdSpecBase, changeName: rdChange, stage: rdStage,
+        client: rdClient, budgetUsd: rdCfg.budget_usd, stallMs: rdCfg.stall_ms,
+      });
+      if (r.ok) {
+        if (r.statusLine) console.log(`🛰️ ${r.statusLine}`);
+        if (r.state === 'completed') {
+          console.log(`✅ 平台审查回收完成：review.json 已落 ${r.reviewPath}（verdict ${r.verdict}）——重跑阶段 --done 走 Stage Review Gate`);
+        } else if (rdMode === 'create') {
+          console.log(`✅ 已派发：mission ${r.missionId} / worker ${r.workerId}（reviewRunId ${r.reviewRunId}）`);
+        }
+        if (r.stalled) console.warn(`⚠️ ${r.stallHint}`);
+        if (r.nextStep && rdMode !== 'kill') console.log(`👉 ${r.nextStep}`);
+        if (rdMode === 'kill') console.log(`👉 ${r.platformHint}`);
+      } else {
+        console.error(`❌ review-dispatch（${rdMode}）: ${r.reason}`);
+        if (r.statusLine) console.error(`   ${r.statusLine}`);
+        if (r.errors) for (const e of r.errors) console.error(`   - ${e}`);
+        if (r.guidance) console.error(`   下一步：\n${r.guidance}`);
+        process.exitCode = 1;
+      }
+      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': {
@@ -1023,6 +1223,96 @@ async function main() {
       console.log(`   归类 ${miResult.matchedCount} 个文件，未匹配 ${miResult.unmatchedCount} 个；影响类型列逐行替换 <!--TODO-->。`);
       break;
     }
+    case 'scope-audit': {
+      // 变更范围对账命令化（2026-09-10-change-scope-audit task-03，FR-02）：Wave 1 纯函数
+      // computeChangeScopeAudit 的 CLI 形态——用户与 agent 不依赖阶段 --done 时点，随时查
+      // 「计划改动 × 实际改动」三态全表（✓ 计划内 / ⚠️ 计划外 / ⚠️ 计划未动；quick 会话出
+      // 归属表）。advisory only（D-006）：只读不落盘、不写门禁状态、既有命令行为零变化；
+      // 路由形态对齐 verify-probes（:897）/ module-impact（:1041）先例——--change 必填缺参
+      // 用法错 exit 2、assertSafeChangeName 消毒、动态 import、--json 结构化输出、运行错
+      // fail-soft 出错误摘要 exit 1 不抛栈。
+      const saChangeIdx = args.indexOf('--change');
+      const saChange = saChangeIdx >= 0 && args[saChangeIdx + 1] ? args[saChangeIdx + 1] : null;
+      if (!saChange) {
+        console.error('用法: sillyspec scope-audit --change <name> [--file <path>] [--json] [--spec-dir <path>]\n  变更范围对账：计划×实际三态全表 + 行数（quick 会话传 quick-<8hex> 出归属表；已归档变更可查——快照冻结记录态）；--file <path> 看单文件变化内容（对账同源锚点的 git diff）；advisory 只读展示，不构成门禁');
+        process.exit(2);
+      }
+      assertSafeChangeName(saChange, '--change 变更名');
+      // --file（quick-63776328）：单文件 diff 内容查看——锚点与表格行数同源（getFileDiff 内部
+      // 复用 computeChangeScopeAudit 锚 + resolveDiffRoot），用户无需手记基点/worktree 路径。
+      const saFileIdx = args.indexOf('--file');
+      const saFile = saFileIdx >= 0 && args[saFileIdx + 1] && !String(args[saFileIdx + 1]).startsWith('--') ? args[saFileIdx + 1] : null;
+      const { computeChangeScopeAudit, renderScopeAuditTable, getFileDiff } = await import('./scope-audit.js');
+      // specBase 解析对齐 verify-probes 的 worktree 锚定主仓口径（坑 worktree-spec-artifact-misplace）：
+      // resolvePlatformSpecDir 仍先调（保留平台接管 fail-closed 检查副作用），但仅 pointer 存在时才把
+      // 返回值当平台根——无 pointer 时它回退 resolveSpecDir(cwd) 会返回 worktree 副本根，误当
+      // platformBase 会让锚定被跳过。无显式 --spec-dir 时 detectWorktreeSpecDrift 锚回主仓
+      // （worktree 副本里查不到主仓 change 目录——dogfood 自测即此形态）。
+      const saResolved = resolvePlatformSpecDir(dir, specDir);
+      const saPlatformBase = existsSync(join(dir, '.sillyspec-platform.json')) ? saResolved : null;
+      let saSpecBase = saPlatformBase || resolveSpecDir(dir, { specDir: specDir || undefined });
+      let saDriftAnchor = null;
+      if (!saPlatformBase && !specDir) {
+        const saWt = detectWorktreeSpecDrift(saSpecBase);
+        if (saWt) {
+          console.warn(`⚠️ 已自动锚定主仓 spec：${saWt.mainSpecBase}（原 cwd 命中 worktree 副本 ${saWt.changeName}，scope-audit 对账读主仓，流程继续）`);
+          saSpecBase = saWt.mainSpecBase;
+          saDriftAnchor = saWt.mainSpecBase;
+        }
+      }
+      // full-flow 变更目录存在性预检（endpoints baseline 先例同款）：post-apply 形态下实际侧三源
+      // 对「变更不存在」不敏感（status 成功即 ok=true，会把主仓脏区误当实际侧），靠预检给明确
+      // 错误摘要 exit 1；quick 会话 id 无 changes/ 目录（guard 祖先链定位），不预检。
+      // 归档形态兼容（quick-8aa52289）：changes/<名> 不在 → 接受 changes/archive/<名>（scope-audit
+      // 内部走快照记录态/HEAD 未提交窗口兜底）。
+      if (!/^quick-[0-9a-f]{8}$/.test(saChange)
+        && !existsSync(join(saSpecBase, 'changes', saChange))
+        && !existsSync(join(saSpecBase, 'changes', 'archive', saChange))) {
+        console.error(`❌ 变更目录不存在（活跃与归档区均未找到）: ${join(saSpecBase, 'changes', saChange)}（确认 --change 名，或 --spec-dir 指向主仓 .sillyspec）`);
+        process.exit(1);
+      }
+      // --file 分支：单文件 diff（预检同表模式——锚点依赖变更上下文；json 面出结构化）
+      if (saFile) {
+        let fd;
+        try {
+          fd = await getFileDiff({ cwd: dir, specBase: saSpecBase, changeName: saChange, platformOpts: saDriftAnchor ? { specDriftAnchor: saDriftAnchor } : null, filePath: saFile });
+        } catch (e) {
+          console.error(`❌ scope-audit --file 执行失败: ${e && e.message ? String(e.message).split('\n')[0] : e}`);
+          process.exit(1);
+        }
+        if (json) {
+          console.log(JSON.stringify({ command: 'scope-audit', change: saChange, file: saFile, ...fd }, null, 2));
+        } else if (fd.ok && fd.diff) {
+          console.log(`📄 ${saFile}（${fd.mode}｜锚点 ${fd.anchorLabel}｜git diff 原生格式）`);
+          console.log(fd.diff);
+        } else {
+          console.log(`ℹ️ ${saFile}（${fd.mode}｜锚点 ${fd.anchorLabel || '—'}）：${fd.note || '无 diff'}`);
+        }
+        if (!fd.ok) process.exitCode = 1;
+        break;
+      }
+      // 计算包在 withJsonOutput 内（gate/derive 先例同款）：quick 模式重跑 auditQuickCompletion
+      // 的既有 console 输出（并发 warn 等，R-07）不污染 --json 的 stdout。
+      let saResult;
+      try {
+        saResult = await withJsonOutput(json, () => computeChangeScopeAudit({ cwd: dir, specBase: saSpecBase, changeName: saChange, platformOpts: saDriftAnchor ? { specDriftAnchor: saDriftAnchor } : null }));
+      } catch (e) {
+        console.error(`❌ scope-audit 计算失败: ${e && e.message ? String(e.message).split('\n')[0] : e}`);
+        process.exit(1);
+      }
+      if (json) {
+        console.log(JSON.stringify({ command: 'scope-audit', change: saChange, ...saResult }, null, 2));
+      } else {
+        console.log(renderScopeAuditTable(saResult));
+      }
+      // ok=false（quick 会话不存在 / 实际侧整体失败）→ 明确错误摘要 + exit 1（json 面摘要走
+      // stderr，stdout 保持合法 JSON）
+      if (saResult && saResult.ok === false) {
+        console.error(`❌ scope-audit 对账不可用: ${saResult.degradedReason || '未知原因'}`);
+        process.exitCode = 1;
+      }
+      break;
+    }
     case 'endpoints': {
       // endpoints artifact 生成（2026-08-21 审计第三批 H6）：后端 router task 的 endpoints.json
       // 此前靠 agent 手扫装饰器手写（易漏 endpoint）。CLI 复用 endpoint-extractor 全套提取器
@@ -1313,6 +1603,97 @@ 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}
+generated_by: sillyspec-fourpiece-init
+---
+# 提案书（Proposal）
+
+## 动机
+<!--TODO: 为什么做、解决什么核心问题-->
+
+## 关键问题
+<!--TODO: 为什么现有方案不够（2-3 个痛点）-->
+
+## 变更范围
+<!--TODO: 本次做什么-->
+
+## 不在范围内（显式清单）
+- <!--TODO: 不做 X-->
+
+## 成功标准（可验证）
+- <!--TODO: 可验证条目-->
+`);
+      mk('requirements.md', `---
+author: qinyi
+created_at: ${fpStamp}
+generated_by: sillyspec-fourpiece-init
+---
+# 需求规格（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}
+generated_by: sillyspec-fourpiece-init
+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
@@ -1358,6 +1739,17 @@ async function main() {
         break;
       }
       writeFileSync(diDesignPath, diSkeleton);
+      // 平台模式双写镜像（坑 platform-init-artifact-daemon-dir-only，2026-09-10 驾驭小结第三批②）：
+      // agent 本地（pointer 态、非显式 --spec-dir）跑 design-init 时 design.md 同时镜像主仓
+      // changeDir——不再单点依赖 spec-sync 回程（两次实锤产物落 daemon specs 同步目录）。
+      try {
+        const { mirrorPlatformArtifactToMainRepo } = await import('./run/shared.js');
+        mirrorPlatformArtifactToMainRepo({
+          cwd: dir, changeName: diChange, file: 'design.md', content: diSkeleton,
+          platformBase: existsSync(join(dir, '.sillyspec-platform.json')) ? diSpecBase : null,
+          specDirExplicit: Boolean(specDir),
+        });
+      } catch { /* 镜像失败不阻断主写入 */ }
       if (json) {
         console.log(JSON.stringify({ command: 'design-init', change: diChange, ok: true, path: diDesignPath, written: true, overwritten: diExisted }, null, 2));
         break;
@@ -1658,23 +2050,36 @@ async function main() {
               // 只读 stdout 可捕获）；stderr 仅留 ⚠️ 诊断（console.warn）与配置错误（exit 2 路径）。
               // 文本逐字不变，只改通道。
               console.log(`\n❌ docs check: ${result.invalid.length}/${result.total} 处引用失效：`);
+              // 显示去重（2026-09-10 驾驭小结第二批③）：同 doc+docLine+ref 的重复 invalid（同一
+              // 引用在行内多次出现时逐条收集）只显示一次、带 ×N 次数——invalid 集与 exit code
+              // 不动，纯渲染降噪。
+              const shownInvalid = [];
+              const dupCountByIdentity = new Map();
+              for (const inv of result.invalid) {
+                const key = `${inv.doc}#${inv.docLine}#${inv.ref}`;
+                dupCountByIdentity.set(key, (dupCountByIdentity.get(key) || 0) + 1);
+                if (dupCountByIdentity.get(key) === 1) shownInvalid.push(inv);
+              }
+              const dupTotal = result.invalid.length - shownInvalid.length;
               let appliedLeft = fixResult ? fixResult.applied : 0;
               const skippedQueue = fixResult ? [...fixResult.skipped] : [];
-              for (const inv of result.invalid) {
+              for (const inv of shownInvalid) {
+                const dupN = dupCountByIdentity.get(`${inv.doc}#${inv.docLine}#${inv.ref}`);
+                const dupTag = dupN > 1 ? `（同引用重复 ×${dupN}）` : '';
                 const newRef = newRefByInv.get(inv);
                 if (newRef !== undefined && appliedLeft > 0) {
                   // 已应用（dry-run 为将应用）：归因按构造顺序消耗 applied 计数——写回 skipped 仅
                   // 防御路径（文档消失/行内失配）触发，CLI 正常流 fixable 必然落位
-                  console.log(`  ✅ [${inv.doc}:L${inv.docLine}] ${inv.ref} → ${newRef}${dryRun ? '（dry-run 未写盘）' : ''}`);
+                  console.log(`  ✅ [${inv.doc}:L${inv.docLine}] ${inv.ref} → ${newRef}${dryRun ? '（dry-run 未写盘）' : ''}${dupTag}`);
                   appliedLeft--;
                 } else if (newRef !== undefined) {
                   const s = skippedQueue.shift();
-                  console.log(`  ⚠️ [${inv.doc}:L${inv.docLine}] ${inv.ref} → 写回跳过：${s ? s.reason : '未知原因'}`);
+                  console.log(`  ⚠️ [${inv.doc}:L${inv.docLine}] ${inv.ref} → 写回跳过：${s ? s.reason : '未知原因'}${dupTag}`);
                 } else if (fixResult) {
                   // needs-manual：多命中歧义/零命中/无 token——fix.reason 含候选行号，交人工
-                  console.log(`  ❌ [${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}（待人工）${dupTag}`);
                 } else {
-                  console.log(`  ❌ [${inv.doc}:L${inv.docLine}] ${inv.ref} → ${inv.reason}`);
+                  console.log(`  ❌ [${inv.doc}:L${inv.docLine}] ${inv.ref} → ${inv.reason}${dupTag}`);
                 }
                 if (inv.suggest && inv.suggest.length > 0) {
                   // 2026-09-07-ir-hardening task-08：原 --suggest 旗标删除（no-op 首选路径退役），
@@ -1682,6 +2087,9 @@ async function main() {
                   console.log(`     💡 候选行号: ${inv.suggest.join(', ')}（token 命中行，人工确认后更新文档锚）`);
                 }
               }
+              if (dupTotal > 0) {
+                console.log(`  ℹ️ 已折叠 ${dupTotal} 条同文档行同引用的重复条目（计数 ×N 已并入上文）。`);
+              }
               if (fixResult) {
                 console.log(`\n🔧 重锚报告：${fixResult.applied} 处已${dryRun ? '预览' : '改写'}${dryRun ? '（dry-run 未写盘）' : ''}、${result.invalid.length - fixes.length} 处待人工${fixResult.skipped.length > 0 ? `、${fixResult.skipped.length} 处写回跳过` : ''}。`);
               if (fixReceipt) {
@@ -1694,9 +2102,21 @@ async function main() {
             // 变更名提名 advisory 段（主结果之后、exit 之前；不参与 ok/invalid 与 exit code）。
             // 零输出原则（docs-check-fix 契约：无新 flag 时 stdout 逐字节一致；决策规则族同款
             // 「无信号零输出」）：仅 findings 非空才输出——悬空即信号，无悬空不打扰。
+            // 输出降噪（2026-09-10 驾驭小结第二批③）：①advisory 固定尾部分区（硬失效区块与
+            // 修复指引之后），标题明示「不阻断、不进 exit code」，与硬失效 ❌ 视觉分离；②同一
+            // 悬空名多处提名按名聚合一行（名 + 提及处数 + 首处定位），不再逐处刷屏。
             if (changeNameReport && changeNameReport.findings.length > 0) {
-              console.warn(`⚠️ 变更名提名悬空 ${changeNameReport.findings.length}/${changeNameReport.mentions} 处（advisory 不阻断、不进 docs gate）：`);
-              for (const f of changeNameReport.findings) console.warn(`   - ${f.message}`);
+              console.log(`\n⚠️ ── 变更名提名悬空（advisory：不阻断、不进 exit code / docs gate）──`);
+              const byName = new Map(); // name -> { count, first }
+              for (const f of changeNameReport.findings) {
+                const e = byName.get(f.name) || { count: 0, first: f };
+                e.count++;
+                byName.set(f.name, e);
+              }
+              for (const [name, e] of byName) {
+                console.log(`   - 「${name}」${e.count} 处提及悬空（活跃∪归档变更名单中不存在；首处 ${e.first.doc}:L${e.first.docLine}）——拼错 / 改名未同步 / 他仓变更？修正后复跑，或 local.yaml known_failures 加 "change-name.${name}" 豁免`);
+              }
+              console.log(`   （共 ${changeNameReport.findings.length} 处 / ${changeNameReport.uniqueNames} 个名字，全文提及 ${changeNameReport.mentions} 处）`);
               if (changeNameReport.exempted.length > 0) {
                 console.log(`ℹ️ 另有 ${changeNameReport.exempted.length} 处经 known_failures change-name.* 键豁免`);
               }
@@ -1810,9 +2230,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');
@@ -1918,6 +2339,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');
@@ -1944,9 +2388,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': {
@@ -2852,6 +3308,108 @@ SillySpec platform — SillyHub 平台同步
       }
       break;
     }
+    case 'mcp': {
+      // MCP Phase 2（P2-g，noai-ir-roadmap §5）：最小 stdio MCP server——只读 tools
+      //（next/gate/derive/progress）经子进程 --json 隔离执行，schema 化参数锁死 flag 幻觉面。
+      // hosts 配 command=sillyspec args=[mcp]。Phase 3（--done 状态推进走 MCP）另计。
+      const { startMcpServer } = await import('./mcp-server.js');
+      await startMcpServer();
+      break;
+    }
+    case 'validate': {
+      // 产物 schema 校验总命令（P2-d，noai-ir-roadmap §5）：聚合既有校验器（verify-facts /
+      // task review / stage review / module-map）+ 轻形状检查（required-evidence / endpoints）
+      // 为一把伞——「新解析器写之前先过 schema」的统一落点。skip = 未生成不算失败。
+      const vaChangeIdx = args.indexOf('--change');
+      const vaChange = vaChangeIdx >= 0 && args[vaChangeIdx + 1] ? args[vaChangeIdx + 1] : null;
+      if (!vaChange) {
+        console.error('用法: sillyspec validate --change <名> [--json]');
+        console.error('  校验该变更的全部结构化产物（verify-facts/required-evidence/task reviews/stage reviews/endpoints + module-map）');
+        process.exit(2);
+      }
+      assertSafeChangeName(vaChange, '--change 变更名');
+      const { validateChangeArtifacts, renderValidateReport } = await import('./validate-artifacts.js');
+      const vaSpecBase = resolveSpecDir(dir, specDir && typeof specDir === 'string' ? { specDir } : undefined);
+      const vaResult = await validateChangeArtifacts({ cwd: dir, specBase: vaSpecBase, changeName: vaChange });
+      if (json) {
+        console.log(JSON.stringify({ command: 'validate', change: vaChange, ok: vaResult.ok, checks: vaResult.checks }, null, 2));
+      } else {
+        console.log(renderValidateReport(vaResult));
+      }
+      if (!vaResult.ok) process.exit(1);
+      break;
+    }
+    case 'decisions': {
+      // P1-5（noai-ir-roadmap §4）：decisions.md 单一写入者——canonical 格式只此一家（标题式
+      // 条目 + applyField 白名单中文标签），agent 不再手拼自由 markdown（扁平列表静默 0 条 /
+      // 字段拼写漂移事故族退役；读取侧 parseDecisions 零改动双向兼容）。
+      //   decisions add --change <c> --id D-001 [--version N] --title "…" [--status confirmed]
+      //     [--type architecture] [--domain a（可重复）] [--question/--answer/--anchor]
+      //     [--reject-reason/--revisit-when/--supersedes/--impacts] [--note "散文行（可重复）"]
+      //     同 id@v 整块替换（幂等）；新 id/version 追加。
+      //   decisions list --change <c>——parseDecisions 只读视图（id/状态/类型/模块域/标题）。
+      const decSub = filteredArgs[1];
+      const decChangeIdx = args.indexOf('--change');
+      const decChange = decChangeIdx >= 0 && args[decChangeIdx + 1] ? args[decChangeIdx + 1] : null;
+      if (!decChange || !['add', 'list'].includes(decSub)) {
+        console.error('用法: sillyspec decisions add --change <名> --id D-001 --title "…" [--version N] [--status confirmed] [--type architecture] [--domain x（可重复）] [--question/--answer/--anchor/--reject-reason/--revisit-when/--supersedes/--impacts/--note]\n  sillyspec decisions list --change <名>');
+        process.exit(2);
+      }
+      assertSafeChangeName(decChange, '--change 变更名');
+      const decChangeDir = join(resolveSpecDir(dir), 'changes', decChange);
+      if (decSub === 'list') {
+        const { parseDecisions } = await import('./decision-distill.js');
+        const parsed = parseDecisions(decChangeDir);
+        if (parsed.missing) { console.error(`❌ decisions.md 不存在: ${join(decChangeDir, 'decisions.md')}`); process.exit(1); }
+        for (const e of parsed.entries) {
+          console.log(`${e.id}  [${e.status || '?'}${e.type ? '/' + e.type : ''}]${(e.domains || []).length ? `[${e.domains.join(',')}]` : ''}  ${e.title || '(无标题)'}`);
+        }
+        console.log(`共 ${parsed.entries.length} 条`);
+        break;
+      }
+      // add：flag 收集（多值 --domain/--note 重复收集）
+      const decFlag = (name) => { const i = args.indexOf(name); return i >= 0 && args[i + 1] && !String(args[i + 1]).startsWith('--') ? args[i + 1] : null; };
+      const decMulti = (name) => { const out = []; for (let i = 0; i < args.length; i++) if (args[i] === name && args[i + 1] && !String(args[i + 1]).startsWith('--')) out.push(args[i + 1]); return out; };
+      const decId = decFlag('--id');
+      const decTitle = decFlag('--title');
+      if (!decId || !decTitle) { console.error('❌ decisions add 需要 --id D-xxx 与 --title'); process.exit(2); }
+      if (!/^D-\d+$/.test(decId)) { console.error(`❌ --id 形态非法（期望 D-xxx，实得 ${decId}）`); process.exit(2); }
+      const decVersionRaw = decFlag('--version');
+      const decVersion = decVersionRaw === null ? null : parseInt(decVersionRaw, 10);
+      const { parseDecisions } = await import('./decision-distill.js');
+      const decParsed = parseDecisions(decChangeDir);
+      let version = decVersion;
+      if (!Number.isInteger(version) || version < 1) {
+        const maxV = decParsed.entries.filter(e => e.number === decId).reduce((m, e) => Math.max(m, e.version), 0);
+        version = maxV + 1;
+      }
+      const decision = {
+        number: decId,
+        version,
+        title: decTitle,
+        status: decFlag('--status') || undefined,
+        type: decFlag('--type') || undefined,
+        domains: decMulti('--domain'),
+        question: decFlag('--question') || undefined,
+        answer: decFlag('--answer') || undefined,
+        anchor: decFlag('--anchor') || undefined,
+        rejectReason: decFlag('--reject-reason') || undefined,
+        revisitWhen: decFlag('--revisit-when') || undefined,
+        supersedes: decFlag('--supersedes') || undefined,
+        impacts: decFlag('--impacts') || undefined,
+        body: decMulti('--note'),
+      };
+      const { upsertDecision } = await import('./decisions-io.js');
+      try {
+        const r = upsertDecision(decChangeDir, decision);
+        console.log(`📝 决策 ${decId}@v${version} 已${r.action === 'replaced' ? '整块替换（幂等）' : '追加'}: ${r.path}`);
+        if (!decVersionRaw) console.log(`   版本缺省 → 既有最高 v${version - 1} + 1（显式版本用 --version）`);
+      } catch (e) {
+        console.error(`❌ 决策写入被拒: ${e.message}`);
+        process.exit(1);
+      }
+      break;
+    }
     case 'taskcard': {
       const tcName = filteredArgs.slice(1).find(a => !a.startsWith('-'));
       if (!tcName || tcName === 'help' || tcName === '--help' || tcName === '-h') {
@@ -2920,7 +3478,33 @@ 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 });
+        // 平台模式产物双写镜像（坑 platform-init-artifact-daemon-dir-only 同族，2026-09-10 驾驭
+        // 小结第六批①，用户实证 taskcard --all 落 daemon 镜像「中间一度两份副本」）：agent 本地
+        // （pointer 态、非显式 --spec-dir）生成的卡片即时镜像主仓 changeDir——不再等 spec-sync
+        // 回程。镜像失败不阻断（镜像根照写，spec-sync 仍是兜底）。
+        if (result.created.length > 0 && existsSync(join(dir, '.sillyspec-platform.json')) && !specDir) {
+          try {
+            const { mirrorPlatformArtifactToMainRepo } = await import('./run/shared.js');
+            const changesAbs = join(tcPlatformSpecDir, 'changes', tcName);
+            for (const created of result.created) {
+              const rel = relative(changesAbs, created).split('\\').join('/');
+              if (!rel || rel.startsWith('..')) continue;
+              try {
+                mirrorPlatformArtifactToMainRepo({
+                  cwd: dir, changeName: tcName, file: rel,
+                  content: readFileSync(created, 'utf8'),
+                  platformBase: tcPlatformSpecDir, ensureParentDir: true,
+                });
+              } catch { /* 单卡镜像失败不连坐 */ }
+            }
+          } catch { /* 镜像链路异常不阻断主命令 */ }
+        }
         for (const f of result.created) console.log(`✅ 已生成: ${f}`);
         for (const f of result.skipped) console.log(`⏭️  已存在，跳过（--force 覆盖）: ${f}`);
         if (result.created.length > 0) {