sillyspec 3.26.13 → 3.26.15

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, join, resolve } from 'path';
+import { basename, extname, join, resolve } from 'path';
 import { safeGit, git } from './git-helper.js';
 import { getVersion } from './version.js';
 
@@ -80,7 +80,9 @@ SillySpec CLI — 规范驱动开发工具包
         --cleanup-ghosts [--confirm]     归档幽灵 active 记录（db 有行无目录 / 空壳目录 0 文件超 7 天，SS-2/2b）
 
   sillyspec local detect [--dir <path>]   生成本地配置 local.yaml（纯 fs 嗅探，零 token、不跑 scan）
+  sillyspec local register-repo <key> <path>  注册跨仓仓到 local.yaml repos: 段（外科手术式写入，其余内容保留）
   sillyspec config [schema] [--json]      打印 local.yaml 全部已知键 + 生效状态 + 读取点（堵外部 agent 配置发现缺口）
+  sillyspec config cat [--json]           读取 local.yaml 实际内容（自动定位真实路径，worktree 内解析到主仓）
   sillyspec runtime list [--json]         枚举 .sillyspec/.runtime/ 运行时产物（只读，看手上有哪些证据/状态文件）
   sillyspec dispatch <probe | hint>       SillyHub 派发能力探测 + 策略生成（agent 调用桥，仅渲染不执行 tool）
 
@@ -89,8 +91,18 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec workflow list
   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> [--json]  为手动补的 task 生成 review.json 草稿（cannot_verify，解 archive 客观完成度阻断）
-  sillyspec register-stage-review --change <name> --stage <brainstorm|plan|execute> [--from <review.json>] [--json]
+  sillyspec backfill-reviews --change <name> [--adopt] [--json]  缺 review.json 的 task 生成草稿；--adopt 重算代填已有 review 的 base/head 等机械字段（verdict 保留）
+  sillyspec symbol-impact --change <name>      生成 symbol-impact.md 逐 task <!--TODO--> 骨架（gate 拒绝未替换占位，防骨架直接过门）
+  sillyspec 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] [--dir <dir>|--files <a.py,b.js>]  静态扫描路由装饰器生成 endpoints.json
+  sillyspec scan-fix-headers [--project <名>]   scan 文档补 author/created_at header（幂等）
+  sillyspec workspace add <名> <路径> [--role] [--repo] | remove <名> | status   多项目工作区登记与状态探测
+  sillyspec scan-fix-leak --spec-dir <specRoot>  source_root 误写产物搬到平台 specRoot（污染一键修复）
+  sillyspec run quick --cancel --change <会话ID> [--ql <ql-id>]  取消误启动的 quick 会话（QUICKLOG 翻已取消 + 挂载行移除）
+  sillyspec register-stage-review --change <name> (--stage <brainstorm|plan|execute> | --all) [--from <review.json>] [--refresh-hash] [--json]
                                       生成/adopt stage 级 review.json（docHash 自动算 + 写 marker，治 tier=independent marker 死锁）
 
   sillyspec doctor [子命令]            进度库健康检查 + 修复（顶层命令，非 worktree doctor）
@@ -520,10 +532,15 @@ async function main() {
       // 无子代理 review 落盘 → archive step1 客观完成度（真相源=review.json verdict）判缺 → 阻断归档；本命令补齐
       // 缺失草稿，独立可随时跑（不必再 execute --done）。缺数据（无 tasks/ 目录 / 改动未 commit / 无 worktree meta）
       // 时 generateTaskReviewDrafts 提前返回 reason，如实打印不报错。
+      // --adopt（2026-08-21 agent-手工产出审计项①）：已存在 review.json 的 mechanics 字段
+      // （schemaVersion/task/base/head/changedFiles/repo）一键重算代填，agent/子代理只写
+      // verdict——手算 hash、手抄 diff 清单是纯错误面，gate 校验的恰是这些字段。与草稿互补：
+      // 草稿补「缺失」，adopt 修「已存在但 mechanics 错/缺」，verdict 原样保留。
       const brChangeIdx = args.indexOf('--change');
       const brChange = brChangeIdx >= 0 && args[brChangeIdx + 1] ? args[brChangeIdx + 1] : null;
+      const brAdopt = args.includes('--adopt');
       if (!brChange) {
-        console.error('用法: sillyspec backfill-reviews --change <name> [--json] [--spec-dir <path>]\n  为手动补的 task 生成 review.json 草稿（cannot_verify），解 archive 客观完成度阻断');
+        console.error('用法: sillyspec backfill-reviews --change <name> [--adopt] [--json] [--spec-dir <path>]\n  缺失 review.json → 生成 cannot_verify 草稿（解 archive 客观完成度阻断）\n  --adopt → 已存在 review.json 的 base/head/changedFiles 等 mechanics 字段一键重算代填（verdict 保留）');
         process.exit(2);
       }
       // 与 run 入口同源消毒（防路径穿越；backfill 下游拼 marker/changes/review 路径）
@@ -560,6 +577,399 @@ async function main() {
           console.log('   execute run id: ' + result.executeRunId);
         }
       }
+      if (brAdopt) {
+        const { adoptTaskReviewMechanics } = await import('./task-review.js');
+        const adoptResult = await adoptTaskReviewMechanics({ changeName: brChange, cwd: dir, platformOpts: brPlatformOpts, ctx: _brCtx });
+        if (json) {
+          process.stdout.write(JSON.stringify({ ok: true, command: 'backfill-reviews --adopt', change: brChange, ...adoptResult }));
+        } else {
+          if (adoptResult.adopted > 0) {
+            console.log('🔁 adopt: 重算代填 ' + adoptResult.adopted + ' 个已存在 review.json 的 mechanics 字段（verdict 原样保留） [' + brChange + ']');
+          }
+          if (adoptResult.unchanged > 0) {
+            console.log('   ' + adoptResult.unchanged + ' 个 mechanics 已一致，无需改写');
+          }
+          if (adoptResult.missing > 0) {
+            console.log('   ' + adoptResult.missing + ' 个 task 无 review.json（由上方草稿生成负责，adopt 不覆盖）');
+          }
+          if (adoptResult.downgraded.length > 0) {
+            console.warn('   ⚠️ ' + adoptResult.downgraded.join(', ') + ' 原 verdict 非法/缺失，已降级 cannot_verify（不猜本意，待人工复核升级）');
+          }
+          if (adoptResult.skipped > 0 || adoptResult.reasons.length > 0) {
+            console.log('   跳过 ' + adoptResult.skipped + ' 个：' + (adoptResult.reasons.join('；') || '原因见上'));
+          }
+          if (adoptResult.adopted === 0 && adoptResult.unchanged === 0 && adoptResult.skipped === 0 && adoptResult.missing === 0) {
+            console.log('ℹ️ adopt 无对象 [' + brChange + ']' + (adoptResult.reasons[0] ? '：' + adoptResult.reasons[0] : ''));
+          }
+        }
+      }
+      break;
+    }
+    case 'workspace': {
+      // 多项目工作区管理命令化（2026-08-21 审计第四批 C-1）：workspace skill 此前纯手写
+      // projects/*.yaml + bash for-loop 探测（skill 明言「CLI 无 workspace 命令」）。
+      // 机械面全命令化：add 外科写入（init 三字段 + role/repo 追加，已有值保留）、
+      // remove 删登记、status 三态探测表。
+      const wsSub = filteredArgs[1];
+      const wsArgs = filteredArgs.slice(2);
+      const wsFlag = (name) => {
+        const i = wsArgs.indexOf(name);
+        return i >= 0 && wsArgs[i + 1] ? wsArgs[i + 1] : null;
+      };
+      const { workspaceAdd, workspaceRemove, workspaceStatus } = await import('./workspace.js');
+      if (wsSub === 'add') {
+        const name = wsFlag('--name') || wsArgs[0];
+        const projPath = wsFlag('--path') || wsArgs[1];
+        if (!name || !projPath) {
+          console.error('用法: sillyspec workspace add <name> <相对路径> [--role <角色>] [--repo <仓库地址>]\n  登记子项目到 .sillyspec/projects/<name>.yaml（外科写入，已有字段保留；路径须存在）');
+          process.exit(2);
+        }
+        try {
+          const r = workspaceAdd({ cwd: dir, name, path: projPath, role: wsFlag('--role'), repo: wsFlag('--repo'), specDir });
+          console.log(`✅ ${r.created ? '已登记' : '已更新'}子项目 ${name}: ${r.file}`);
+          console.log(`   下一步：cd ${projPath} && sillyspec init（或 scan）`);
+        } catch (e) {
+          console.error(`❌ ${e.message}`);
+          process.exit(1);
+        }
+      } else if (wsSub === 'remove') {
+        const name = wsFlag('--name') || wsArgs[0];
+        if (!name) {
+          console.error('用法: sillyspec workspace remove <name>\n  删除子项目登记（.sillyspec/projects/<name>.yaml；不删项目本体）');
+          process.exit(2);
+        }
+        try {
+          const r = workspaceRemove({ cwd: dir, name, specDir });
+          console.log(`🗑️  已移除子项目登记 ${name}: ${r.file}（项目本体未动）`);
+          console.log('   记得 git add 该删除');
+        } catch (e) {
+          console.error(`❌ ${e.message}`);
+          process.exit(1);
+        }
+      } else if (!wsSub || wsSub === 'status') {
+        const r = workspaceStatus({ cwd: dir, specDir });
+        if (json) {
+          console.log(JSON.stringify({ command: 'workspace status', ...r }, null, 2));
+          break;
+        }
+        if (r.projects.length === 0) {
+          console.log('📭 无子项目登记（.sillyspec/projects/ 为空）——sillyspec workspace add <name> <路径> 登记后管理');
+          break;
+        }
+        console.log(`🏢 工作区（${r.projects.length} 个子项目）：`);
+        const icon = { scanned: '✅', initialized: '⚠️', unregistered: '❌', missing: '❌' };
+        for (const p of r.projects) {
+          console.log(`  ${icon[p.state] || '•'} ${p.name.padEnd(16)} ${(p.path || '').padEnd(18)} ${(p.role || '').padEnd(14)} ${p.detail}`);
+        }
+        if (r.sharedDocs.length > 0) {
+          console.log(`📄 共享规范：${r.sharedDocs.length} 份（${r.sharedDocs.join('、')}）`);
+        }
+        console.log('💡 操作：workspace add/remove <name> <路径>');
+      } else {
+        console.error('用法: sillyspec workspace add <name> <路径> [--role] [--repo] | remove <name> | status');
+        process.exit(2);
+      }
+      break;
+    }
+    case 'scan-fix-leak': {
+      // source_root 污染一键修复（2026-08-21 审计第四批 C-3）：平台模式 scan-postcheck 对
+      // 「agent 把产物写到 <source_root>/.sillyspec/ 而非 specRoot」只报 FAILED 不修，agent 手工
+      // 搬常搬错。本命令按检查同款清单搬到 specRoot（已存在不覆盖，报告 skipped）。
+      const sflSpecDir = specDir || (await import('./progress.js')).resolvePlatformSpecDir(dir, null);
+      if (!sflSpecDir || !existsSync(sflSpecDir)) {
+        console.error('❌ 缺 --spec-dir <specRoot>（平台模式 spec 根）——scan-fix-leak 把 <cwd>/.sillyspec/ 误写产物搬到 specRoot');
+        process.exit(2);
+      }
+      const { fixSourceRootLeak } = await import('./scan-postcheck.js');
+      const r = fixSourceRootLeak({ cwd: dir, specDir: sflSpecDir });
+      if (json) {
+        console.log(JSON.stringify({ command: 'scan-fix-leak', ...r }, null, 2));
+        break;
+      }
+      if (r.moved.length === 0 && r.skipped.length === 0) {
+        console.log('📭 无污染（<cwd>/.sillyspec/ 下无 docs/projects/workflows/knowledge/manifest/local 产物）');
+        break;
+      }
+      for (const m of r.moved) console.log(`📦 已搬移: ${m}`);
+      for (const d of r.removedDirs) console.log(`🧹 已清空目录: ${d}`);
+      for (const s of r.skipped) console.log(`⏭️  ${s}`);
+      if (r.moved.length > 0) console.log('   搬完重跑 sillyspec scan 的 postcheck 应转绿');
+      break;
+    }
+    case 'next': {
+      // 项目状态探测（2026-08-21 审计第二批 G7/G8）：吸收 continue/resume 两个 skill 的
+      // 手工探测表（文件存在性状态机），一条命令输出「状态 + 下一步命令 + 依据」。
+      // 纯 fs 零 token；活跃进度的权威状态仍归 progress show，本命令管无活跃进度时反推。
+      const { detectNextStep } = await import('./run/next.js');
+      const nxResult = detectNextStep({ cwd: dir, specDir });
+      if (json) {
+        console.log(JSON.stringify({ command: 'next', ...nxResult }, null, 2));
+        break;
+      }
+      console.log('🤖 SillySpec 状态探测');
+      console.log(`   状态：${nxResult.state}`);
+      if (nxResult.activeChanges.length > 0) {
+        for (const c of nxResult.activeChanges) {
+          console.log(`   - ${c.name}（task ${c.checked}/${c.total}）`);
+        }
+      }
+      console.log(`   👉 下一步：${nxResult.next}`);
+      if (nxResult.evidence.length > 0) {
+        console.log(`   依据：${nxResult.evidence.join('、')}`);
+      }
+      break;
+    }
+    case 'commit': {
+      // 智能提交建议（2026-08-21 审计第二批 G1-G3）：commit skill 此前让 agent 手工收集
+      // 语义（LAST_COMMIT_TIME / cat QUICKLOG / 扫变更目录 / 按路径模式分类）——进度库、
+      // quicklog、git 全在 CLI 手里。一条命令产出统计 + 语义来源 + conventional 建议 +
+      // 可照抄的 git 命令。**只建议不执行**（确认权在人，对齐 skill 绝对规则「不要自动提交」）。
+      const { collectCommitContext } = await import('./commit-suggest.js');
+      const cc = collectCommitContext({ cwd: dir, specDir });
+      if (json) {
+        console.log(JSON.stringify({ command: 'commit', ...cc }, null, 2));
+        break;
+      }
+      if (!cc.hasChanges) {
+        console.log('📭 没有需要提交的修改（工作区干净）');
+        break;
+      }
+      console.log(`📦 待提交变更（${cc.changedCount} 个文件${cc.untrackedCount > 0 ? `，其中未跟踪 ${cc.untrackedCount} 个` : ''}；上方 stat 仅列已跟踪文件的改动）`);
+      if (cc.stat) console.log(cc.stat.split('\n').map(l => '   ' + l).join('\n'));
+      if (cc.quickEntries.length > 0) {
+        console.log(`\n📝 QUICKLOG（上次提交 ${cc.lastCommitTime || '（无）'} 之后 ${cc.quickEntries.length} 条）：`);
+        for (const q of cc.quickEntries) {
+          console.log(`   ${q.status === '已完成' ? '✅' : '⏳'} ${q.qlId} | ${q.title}${q.status === '已完成' ? '' : '（进行中，不进 commit 语义）'}`);
+        }
+      }
+      if (cc.checkedTasks.length > 0) {
+        console.log(`\n✅ execute 已勾 task：`);
+        for (const t of cc.checkedTasks) console.log(`   - [${t.change}] ${t.item}`);
+      }
+      if (cc.stageArtifacts.length > 0) {
+        console.log(`\n📁 阶段产出：${cc.stageArtifacts.join(' / ')}`);
+      }
+      if (cc.suggestion) {
+        console.log(`\n💡 建议 commit message：`);
+        console.log(`   ${cc.suggestion.subject}`);
+        if (cc.suggestion.body) {
+          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}`);
+      } else {
+        console.log('\n💡 无语义来源匹配——请结合上方 diff stat 手写 message');
+      }
+      console.log('\n（本命令只建议不提交；确认后执行上面的命令）');
+      break;
+    }
+    case 'verify-probes': {
+      // verify 机械探针命令化（2026-08-21 审计第三批 H1/H3/H5/H7/F9）：verify-probes.md 模板
+      // 六探针中的纯机械四个（未实现标记 grep / 测试文件递归查找 / API 契约对账 / 删除对账）
+      // 一条命令跑完并渲染成可直接粘贴的 markdown；半语义探针（2/4 + 3.4/3.5）显式留 TODO。
+      // --init 顺带生成 verify-result.md 七章节骨架（探针结果预填；结论留「待填」——gate 找
+      // 不到 PASS/FAIL 即判不过，骨架不能直接过门）。已存在不覆盖。
+      const vpChangeIdx = args.indexOf('--change');
+      const vpChange = vpChangeIdx >= 0 && args[vpChangeIdx + 1] ? args[vpChangeIdx + 1] : null;
+      const vpInit = args.includes('--init');
+      if (!vpChange) {
+        console.error('用法: sillyspec verify-probes --change <name> [--init] [--json] [--spec-dir <path>]\n  跑机械探针（TODO 标记/测试覆盖/API 对账/删除对账）输出 markdown；--init 生成 verify-result.md 骨架（探针预填，已存在不覆盖）');
+        process.exit(2);
+      }
+      assertSafeChangeName(vpChange, '--change 变更名');
+      const { runVerifyProbes, renderVerifyProbesReport, generateVerifyResultSkeleton } = await import('./verify-probes.js');
+      const vpResult = runVerifyProbes({ cwd: dir, changeName: vpChange, specDir });
+      if (json) {
+        console.log(JSON.stringify({ command: 'verify-probes', change: vpChange, ...vpResult }, null, 2));
+        break;
+      }
+      console.log(renderVerifyProbesReport(vpResult));
+      if (vpInit) {
+        const vpSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+        const vpReportPath = join(vpSpecBase, 'changes', vpChange, 'verify-result.md');
+        if (existsSync(vpReportPath)) {
+          console.log(`\nℹ️  verify-result.md 已存在，不覆盖: ${vpReportPath}`);
+        } else {
+          writeFileSync(vpReportPath, generateVerifyResultSkeleton(vpResult));
+          console.log(`\n📄 已生成 verify-result.md 骨架: ${vpReportPath}（探针已预填；结论必须写明 PASS/FAIL，留待填会被 gate 判不过）`);
+        }
+      }
+      break;
+    }
+    case 'module-impact': {
+      // archive 模块影响矩阵骨架（2026-08-21 审计第三批 D3）：文件×模块归属按 _module-map.yaml
+      // paths 前缀匹配预填（机械），影响类型/review 标记留 <!--TODO-->（语义）。已存在不覆盖。
+      const miChangeIdx = args.indexOf('--change');
+      const miChange = miChangeIdx >= 0 && args[miChangeIdx + 1] ? args[miChangeIdx + 1] : null;
+      if (!miChange) {
+        console.error('用法: sillyspec module-impact --change <name> [--json] [--spec-dir <path>]\n  生成 module-impact.md 骨架（模块影响矩阵按 module-map 预填 + 未匹配文件清单；已存在不覆盖）');
+        process.exit(2);
+      }
+      assertSafeChangeName(miChange, '--change 变更名');
+      const { generateModuleImpactSkeleton } = await import('./module-impact.js');
+      const miResult = generateModuleImpactSkeleton({ cwd: dir, changeName: miChange, specDir });
+      if (!miResult) {
+        console.log('ℹ️ 无 module-map 或无 diff 文件可归类——骨架无从生成，agent 全手写（模块索引缺失可先跑 sillyspec modules rebuild）');
+        break;
+      }
+      const miSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+      const miPath = join(miSpecBase, 'changes', miChange, 'module-impact.md');
+      if (json) {
+        console.log(JSON.stringify({ command: 'module-impact', change: miChange, path: miPath, ...miResult }, null, 2));
+        break;
+      }
+      if (existsSync(miPath)) {
+        console.log(`ℹ️  module-impact.md 已存在，不覆盖: ${miPath}`);
+        break;
+      }
+      writeFileSync(miPath, miResult.markdown);
+      console.log(`✅ 已生成 module-impact.md 骨架: ${miPath}`);
+      console.log(`   归类 ${miResult.matchedCount} 个文件，未匹配 ${miResult.unmatchedCount} 个；影响类型列逐行替换 <!--TODO-->。`);
+      break;
+    }
+    case 'endpoints': {
+      // endpoints artifact 生成（2026-08-21 审计第三批 H6）：后端 router task 的 endpoints.json
+      // 此前靠 agent 手扫装饰器手写（易漏 endpoint）。CLI 复用 endpoint-extractor 全套提取器
+      // （FastAPI @router.* / Express router.* / Spring @*Mapping）静态扫描生成，
+      // verify 探针 5（verifyApiParity）直接消费该产物。
+      const epSub = filteredArgs[1];
+      if (epSub !== 'extract') {
+        console.error('用法: sillyspec endpoints extract --change <name> [--task task-NN] [--dir <backendRoot> | --files <a.py,b.js...>] [--spec-dir <path>]\n  静态扫描后端路由装饰器生成 endpoints.json（FastAPI/Express/Spring）；verify 探针 5 消费');
+        process.exit(2);
+      }
+      const epChangeIdx = args.indexOf('--change');
+      const epChange = epChangeIdx >= 0 && args[epChangeIdx + 1] ? args[epChangeIdx + 1] : null;
+      const epTaskIdx = args.indexOf('--task');
+      const epTask = epTaskIdx >= 0 && args[epTaskIdx + 1] ? args[epTaskIdx + 1] : null;
+      const epDirIdx = args.indexOf('--dir');
+      const epDir = epDirIdx >= 0 && args[epDirIdx + 1] ? args[epDirIdx + 1] : null;
+      const epFilesIdx = args.indexOf('--files');
+      const epFilesRaw = epFilesIdx >= 0 && args[epFilesIdx + 1] ? args[epFilesIdx + 1] : null;
+      if (!epChange) {
+        console.error('❌ 缺 --change <变更名>');
+        process.exit(2);
+      }
+      assertSafeChangeName(epChange, '--change 变更名');
+      const { extractFastApiEndpoints, extractExpressEndpoints, extractSpringEndpoints, scanBackendEndpoints } = await import('./endpoint-extractor.js');
+      const endpoints = [];
+      const epSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+      const epChangeDir = join(epSpecBase, 'changes', epChange);
+      if (!existsSync(epChangeDir)) {
+        console.error(`❌ 变更目录不存在: ${epChangeDir}`);
+        process.exit(1);
+      }
+      const collectFile = (f) => {
+        const abs = resolve(f)
+        if (!existsSync(abs)) return
+        const ext = extname(abs).toLowerCase()
+        try {
+          if (ext === '.py') endpoints.push(...extractFastApiEndpoints(abs))
+          else if (ext === '.js' || ext === '.ts') endpoints.push(...extractExpressEndpoints(abs))
+          else if (ext === '.java') endpoints.push(...extractSpringEndpoints(abs))
+        } catch { /* 单文件解析失败不阻断整体 */ }
+      }
+      if (epDir) {
+        endpoints.push(...scanBackendEndpoints(resolve(epDir)))
+      } else if (epFilesRaw) {
+        for (const f of epFilesRaw.split(',').map(s => s.trim()).filter(Boolean)) collectFile(f)
+      } else {
+        // 默认扫描面：task 卡 allowed_paths ∪ design §6 清单里的具体源码文件
+        const { parseFileChangeListDetailed } = await import('./change-list.js')
+        const candidates = new Set()
+        if (epTask) {
+          const cardPath = join(epChangeDir, 'tasks', `${epTask}.md`)
+          if (existsSync(cardPath)) {
+            const { parseAllowedPaths } = await import('./stages/plan-postcheck.js')
+            for (const p of parseAllowedPaths(readFileSync(cardPath, 'utf8'))) candidates.add(p)
+          }
+        }
+        const designPath = join(epChangeDir, 'design.md')
+        if (existsSync(designPath)) {
+          for (const e of parseFileChangeListDetailed(designPath)) {
+            if (!e.path.startsWith('.sillyspec/') && !/[*?[\]]/.test(e.path)) candidates.add(e.path)
+          }
+        }
+        let scanned = 0
+        for (const p of candidates) {
+          const abs = join(dir, p)
+          if (!existsSync(abs)) continue
+          scanned++
+          collectFile(p)
+        }
+        if (candidates.size === 0) {
+          console.error('❌ 无扫描面：--task 卡无 allowed_paths 且 design.md 无具体文件清单——显式传 --dir <backendRoot> 或 --files <a.py,b.js>');
+          process.exit(1);
+        }
+        console.log(`ℹ️  扫描 ${scanned}/${candidates.size} 个清单文件（不存在的跳过）`);
+      }
+      const artifact = {
+        generated_at: new Date().toISOString().slice(0, 19).replace('T', ' '),
+        generator: 'sillyspec endpoints extract',
+        endpoints: endpoints.map(e => ({ method: e.method, path: e.path, source: e.source })),
+      }
+      const epRuntimeRoot = (await import('./run/shared.js')).resolveRuntimeRoot({ specRoot: specDir }, epSpecBase);
+      const epOutDir = join(epRuntimeRoot, 'contract-artifacts', epChange, epTask || 'scan');
+      mkdirSync(epOutDir, { recursive: true });
+      const epOutPath = join(epOutDir, 'endpoints.json');
+      writeFileSync(epOutPath, JSON.stringify(artifact, null, 2) + '\n');
+      console.log(`✅ 提取 ${endpoints.length} 个端点 → ${epOutPath}`);
+      console.log(`   verify 阶段探针 5（API 契约对账）自动消费该产物；FastAPI/Express/Spring 装饰器均支持。`);
+      break;
+    }
+    case 'scan-fix-headers': {
+      // scan 文档 header 幂等补填（2026-08-21 审计第三批 E3）：scan-postcheck 对缺
+      // author/created_at 只 warning，agent 手改还常忘。本命令补齐（git user + 当前时间），
+      // 已有两键的文件不动；有 frontmatter 就地插入，无则补一段。
+      const sfhProjectIdx = args.indexOf('--project');
+      const sfhProject = sfhProjectIdx >= 0 && args[sfhProjectIdx + 1] ? args[sfhProjectIdx + 1] : null;
+      const { fixScanDocHeaders } = await import('./scan-postcheck.js');
+      const sfhResult = fixScanDocHeaders({ cwd: dir, specDir, project: sfhProject });
+      if (json) {
+        console.log(JSON.stringify({ command: 'scan-fix-headers', ...sfhResult }, null, 2));
+        break;
+      }
+      if (sfhResult.fixed.length > 0) {
+        for (const f of sfhResult.fixed) console.log(`✅ 已补 header: ${f}`);
+      }
+      if (sfhResult.skipped.length > 0) console.log(`ℹ️  ${sfhResult.skipped.length} 份已含 author/created_at，未动`);
+      if (sfhResult.fixed.length === 0 && sfhResult.skipped.length === 0) console.log('📭 未找到 scan 文档（无 docs/<project>/scan/ 目录）');
+      break;
+    }
+    case 'symbol-impact': {
+      // symbol-impact.md 骨架生成（2026-08-21 审计项⑤「报错即生成」的命令入口）：gate 此前
+      // 只报错不代填 → agent 从零手写整份报告，忘一个 task 就被拦。本命令从 tasks.md（回退
+      // plan.md）注册表生成逐 task <!--TODO--> 骨架；gate 拒绝未替换的占位（防骨架直接过门），
+      // agent 只需逐行填结论。已存在不覆盖（幂等，agent 产出优先）。
+      const siChangeIdx = args.indexOf('--change');
+      const siChange = siChangeIdx >= 0 && args[siChangeIdx + 1] ? args[siChangeIdx + 1] : null;
+      if (!siChange) {
+        console.error('用法: sillyspec symbol-impact --change <name> [--spec-dir <path>]\n  生成 symbol-impact.md 逐 task <!--TODO--> 骨架（已存在不覆盖）；gate 拒绝未替换的占位行');
+        process.exit(2);
+      }
+      assertSafeChangeName(siChange, '--change 变更名');
+      const siSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+      const siChangeDir = join(siSpecBase, 'changes', siChange);
+      const siTasksPath = join(siChangeDir, 'tasks.md');
+      const siPlanPath = join(siChangeDir, 'plan.md');
+      const siRegistryPath = existsSync(siTasksPath) ? siTasksPath : (existsSync(siPlanPath) ? siPlanPath : null);
+      if (!siRegistryPath) {
+        console.error(`❌ 变更目录缺 tasks.md/plan.md: ${siChangeDir}`);
+        process.exit(1);
+      }
+      const { generateSymbolImpactSkeleton } = await import('./run/gates.js');
+      const siSkeleton = generateSymbolImpactSkeleton(readFileSync(siRegistryPath, 'utf8'));
+      if (!siSkeleton) {
+        console.error(`❌ 任务清单无 checkbox task 行: ${siRegistryPath}`);
+        process.exit(1);
+      }
+      const siReportPath = join(siChangeDir, 'symbol-impact.md');
+      if (existsSync(siReportPath)) {
+        console.log(`ℹ️  symbol-impact.md 已存在，不覆盖: ${siReportPath}`);
+        break;
+      }
+      writeFileSync(siReportPath, siSkeleton);
+      console.log(`✅ 已生成逐 task 骨架: ${siReportPath}`);
+      console.log('   逐行替换 <!--TODO--> 为结论（无签名级变更也显式写「无」）；gate 拒绝未替换的占位行。');
       break;
     }
     case 'register-stage-review': {
@@ -574,8 +984,14 @@ async function main() {
       const rsrStage = rsrStageIdx >= 0 && args[rsrStageIdx + 1] ? args[rsrStageIdx + 1] : null;
       const rsrFromIdx = args.indexOf('--from');
       const rsrFrom = rsrFromIdx >= 0 && args[rsrFromIdx + 1] ? args[rsrFromIdx + 1] : null;
-      if (!rsrChange || !rsrStage) {
-        console.error('用法: sillyspec register-stage-review --change <名> --stage <brainstorm|plan|execute> [--from <review.json>] [--spec-dir <path>] [--json]\n  生成/adopt stage 级 review.json（docHash 自动算 + 写 marker），治 tier=independent marker 死锁');
+      // docHash 联动（坑 stage-review-dochash-manual-resync，2026-08-21 实证）：改一版 design 要
+      // 重算 2-3 个 stage review 的 docHash，手工易漏、gate 报错才补。--refresh-hash 就地刷新单个
+      // 既有 review 的 hash（保留结论）；--all 一次处理三个 stage（有 review 刷 hash，无 review
+      // 生成骨架——改版后一条命令完成全部联动）。
+      const rsrRefreshHash = filteredArgs.includes('--refresh-hash');
+      const rsrAll = filteredArgs.includes('--all');
+      if (!rsrChange || (!rsrStage && !rsrAll) || (rsrAll && rsrStage)) {
+        console.error('用法: sillyspec register-stage-review --change <名> (--stage <brainstorm|plan|execute> | --all) [--from <review.json>] [--refresh-hash] [--spec-dir <path>] [--json]\n  生成/adopt/刷新 stage 级 review.json（docHash 自动算 + 写 marker）；--all 一次处理三个 stage（有 review 刷新 hash、无 review 生成骨架）；--refresh-hash 就地刷新既有 review 的 docHash（保留 verdict 待确认续用）');
         process.exit(2);
       }
       // 与 run 入口同源消毒（防路径穿越；register 下游写 marker、拼 changes/review 路径）
@@ -583,20 +999,38 @@ async function main() {
       const { registerStageReview } = await import('./stage-review.js');
       const rsrPlatformOpts = {};
       if (specDir) rsrPlatformOpts.specRoot = specDir;
-      try {
-        const result = registerStageReview({ changeName: rsrChange, stage: rsrStage, fromFile: rsrFrom, cwd: dir, platformOpts: rsrPlatformOpts });
-        if (json) {
-          process.stdout.write(JSON.stringify({ ok: true, command: 'register-stage-review', change: rsrChange, stage: rsrStage, ...result }));
-        } else {
-          console.log(`✅ 已注册 ${rsrStage} stage review [${result.reviewRunId}] → ${result.reviewPath}（mode: ${result.mode}）`);
-          console.log(`   marker → ${result.markerPath}`);
-          console.log(`   下一步：独立审查子代理对照 ${result.mainDoc} 填 verdict/checklist 后重跑 --done`);
+      const rsrStages = rsrAll ? ['brainstorm', 'plan', 'execute'] : [rsrStage];
+      const rsrResults = [];
+      let rsrFailed = 0;
+      for (const st of rsrStages) {
+        try {
+          // --all 的单 stage 语义：有既有 review → refresh-hash；无 → 骨架。显式 --refresh-hash
+          // 则强制 refresh（无既有 review 时报错，提示先生成骨架）
+          const { getLatestStageReviewRunId, stageReviewMarkerPath } = await import('./stage-review.js');
+          const { resolveRuntimeRoot } = await import('./run/shared.js');
+          const rsrRuntimeRoot = resolveRuntimeRoot(rsrPlatformOpts, rsrPlatformOpts.specRoot || join(dir, '.sillyspec'));
+          const hasExisting = !!getLatestStageReviewRunId(rsrRuntimeRoot, st, rsrChange);
+          const wantRefresh = rsrRefreshHash || (rsrAll && hasExisting);
+          const result = registerStageReview({ changeName: rsrChange, stage: st, fromFile: rsrFrom, cwd: dir, platformOpts: rsrPlatformOpts, refreshHash: wantRefresh });
+          rsrResults.push({ stage: st, ...result });
+          if (json) {
+            process.stdout.write(JSON.stringify({ ok: true, command: 'register-stage-review', change: rsrChange, stage: st, ...result }) + '\n');
+          } else {
+            console.log(`✅ 已注册 ${st} stage review [${result.reviewRunId}] → ${result.reviewPath}（mode: ${result.mode}）`);
+            console.log(`   marker → ${result.markerPath}`);
+            if (result.mode === 'refreshed') {
+              console.log(`   docHash 已按当前 ${result.mainDoc} 重算（verdict 结论是否仍适用需人工确认）`);
+            } else {
+              console.log(`   下一步：独立审查子代理对照 ${result.mainDoc} 填 verdict/checklist 后重跑 --done`);
+            }
+          }
+        } catch (e) {
+          rsrFailed++;
+          if (json) process.stdout.write(JSON.stringify({ ok: false, command: 'register-stage-review', change: rsrChange, stage: st, error: e.message }) + '\n');
+          else console.error(`❌ [${st}] ` + e.message);
         }
-      } catch (e) {
-        if (json) process.stdout.write(JSON.stringify({ ok: false, command: 'register-stage-review', error: e.message }));
-        else console.error('❌ ' + e.message);
-        process.exitCode = 1;
       }
+      if (rsrFailed > 0) process.exitCode = 1;
       break;
     }
     case 'docs': {
@@ -1179,6 +1613,17 @@ SillySpec worktree — git worktree 隔离管理
             // 模块文档（.sillyspec/docs/）= 交付物，会 auto-apply 到主工作区；变更文档/运行时/quicklog 不 apply。
             // 须告知 agent 哪些未落地，否则它期望这些文件落地却找不到（memory: worktree-apply-excludes-module-docs）。
             console.log(`   ℹ️  注：.sillyspec/changes、.sillyspec/.runtime、.sillyspec/quicklog 下的文件按规则不自动 apply（模块文档 .sillyspec/docs/ 会自动 apply），如需请手动从 worktree 分支或 dangling commit 取（git show sillyspec/${wtName}:<path>）。`);
+            // 提交复用 pathspec（坑 apply-commit-pathspec-sweep）：主仓无关未提交文件易被目录级
+            // git add 误扫——给精确清单，勿用 git add <目录>/ 全扫
+            if (Array.isArray(result.commitPathspec) && result.commitPathspec.length > 0 && result.pathspecFile) {
+              console.log(`\n📌 提交时用本变更精确 pathspec（勿目录级 add 误扫无关文件）：`);
+              if (result.commitPathspec.length <= 30) {
+                console.log(`   git add -- ${result.commitPathspec.join(' ')}`);
+              } else {
+                console.log(`   git add --pathspec-from-file="${result.pathspecFile}"`);
+              }
+              console.log(`   （完整清单 ${result.commitPathspec.length} 个文件已存 ${result.pathspecFile}，可 --pathspec-from-file 复用）`);
+            }
           }
           if (result.warnings && result.warnings.length > 0) {
             for (const w of result.warnings) {
@@ -2013,8 +2458,52 @@ SillySpec modules — 模块文档管理
       // 本地配置探测（task-04 / D-001@v1）：纯 fs 嗅探项目类型 → 生成 local.yaml。
       // 轻量独立路由，不跑 scan、不消耗 token。探测逻辑归属 local-detect.js（task-02）。
       const localSubCmd = filteredArgs[1];
+      // register-repo（2026-08-21 审计项④）：跨仓 repo key 注册命令化。此前靠 agent 手编
+      // local.yaml repos: 段（正是 agent 满目录找/根目录乱建 local.yaml 的上游）；execute
+      // 启动 fail-closed 报错已列出缺的 key，本命令外科手术式写入——只动 repos: 段，
+      // 注释/凭据段逐行保留。写目标解析 worktree→主仓（config-cat.js 同源候选链）。
+      if (localSubCmd === 'register-repo') {
+        const rrKey = filteredArgs[2];
+        const rrPath = filteredArgs[3];
+        if (!rrKey || !rrPath || rrPath.startsWith('-')) {
+          console.error('用法: sillyspec local register-repo <key> <path>\n  注册跨仓仓到 local.yaml repos: 段（跨仓 task 卡 repo: 的 key 必须先注册，execute 启动 fail-closed 校验）\n  key 限字母数字._-；path 为跨仓仓根目录（相对路径按当前 cwd 解析，须是 git 仓）；main 隐式不用注册');
+          process.exit(2);
+        }
+        let rrSpecBase = null;
+        try {
+          rrSpecBase = resolvePlatformSpecDir(dir, specDir);
+        } catch (e) {
+          // fail-closed：平台 pointer 异常时不盲写（写错 local.yaml 比不写更糟），报修复引导
+          console.error(`❌ 无法解析 local.yaml 目标路径（平台指针异常）: ${e.message}`);
+          process.exit(1);
+        }
+        const absRepo = resolve(rrPath);
+        if (!existsSync(absRepo)) {
+          console.error(`❌ 路径不存在: ${absRepo}`);
+          process.exit(1);
+        }
+        if (!(await import('./git-helper.js')).gitQuiet(absRepo, ['rev-parse', '--git-dir'])) {
+          console.error(`❌ 不是 git 仓库: ${absRepo}（repos: 段注册的跨仓仓必须可 rev-parse，MultiRepoContext 会在其中跑 git）`);
+          process.exit(1);
+        }
+        const { resolveLocalYamlWriteTarget } = await import('./config-cat.js');
+        const target = resolveLocalYamlWriteTarget(dir, { specBase: rrSpecBase });
+        const { registerRepoInLocalYaml } = await import('./local-register.js');
+        let rrResult;
+        try {
+          rrResult = registerRepoInLocalYaml(target.path, rrKey, absRepo);
+        } catch (e) {
+          console.error(`❌ 注册失败: ${e.message}`);
+          process.exit(1);
+        }
+        const verb = rrResult.replaced ? '已更新（覆盖旧路径）' : '已注册';
+        console.log(`✅ repos.${rrKey} ${verb}: ${absRepo.replace(/\\/g, '/')}`);
+        console.log(`   写入: ${target.path}${rrResult.fileCreated ? '（新建文件）' : ''}${rrResult.sectionCreated ? '（新建 repos: 段）' : ''}`);
+        console.log('   查看: sillyspec config cat（真实配置）; main 隐式=主仓不用注册');
+        break;
+      }
       if (localSubCmd !== 'detect') {
-        console.error('用法: sillyspec local detect [--dir <path>]\n  纯 fs 嗅探项目类型并生成 local.yaml（不跑 scan、零 token）');
+        console.error('用法: sillyspec local detect [--dir <path>]\n       sillyspec local register-repo <key> <path>\n  detect: 纯 fs 嗅探项目类型并生成 local.yaml（不跑 scan、零 token）\n  register-repo: 注册跨仓仓到 local.yaml repos: 段（外科手术式写入，其余内容保留）');
         process.exit(2);
       }
 
@@ -2075,19 +2564,56 @@ SillySpec config — local.yaml 配置键速查
   sillyspec config schema         同上（显式子命令）
   sillyspec config --json         机读 JSON（程序化消费）
   sillyspec config schema --json  同上
+  sillyspec config cat            读取 local.yaml 实际内容（候选链：spec 根 → cwd 祖先链 →
+                                  git common-dir 主仓根；worktree 内 .sillyspec 是 checkout
+                                  副本无此文件，cat 自动解析到主仓）
+  sillyspec config cat --json     机读 JSON（dir/path/source/content；未找到退出 1）
 
 说明:
   - 数据源：src/config-schema.js（唯一真相；reader 见各键「读取点」）
   - 键分两类：【生效】配了即生效；【声明但未接线】代码/JSDoc 提及但无 reader，配了不生效
   - 脱敏示例文件：sillyspec init 生成 local.yaml.example（可提交；真实 local.yaml 是 gitignored）
+  - local.yaml 恒在 .sillyspec/ 下——项目根目录没有这个文件，别去那里找（写 .sillyspec/
+    之外的同名文件会被 hook 拦截）
 `);
         break;
       }
+      // config cat（2026-08-21 root-local-yaml 治理）：schema 只列键不含值，agent 拿实际配置
+      // 只能翻文件——worktree 内 .sillyspec 是 checkout 副本（gitignored 的 local.yaml 不随
+      // checkout 出现），找不到就漂去项目根乱找/乱建。cat = 唯一权威读取口，按「文件存在」
+      // 解析真实路径（config-cat.js：spec 根 → cwd 祖先链 → git common-dir 主仓根）。
+      // agent 本就有 shell 权限可自行 cat，CLI 回显明文不增加暴露面。
+      if (configSub === 'cat') {
+        let specBase = null
+        try { specBase = resolvePlatformSpecDir(dir, specDir) } catch { /* 平台 pointer 异常 → 走祖先链（真实 reader 各自 fail-closed，cat 只读不加重） */ }
+        const { resolveLocalYaml } = await import('./config-cat.js')
+        const r = resolveLocalYaml(dir, { specBase })
+        if (json) {
+          const payload = { cmd: 'config cat', dir: resolve(dir), exists: r.exists, path: r.path, source: r.source, searched: r.searched }
+          if (r.exists) payload.content = readFileSync(r.path, 'utf8')
+          console.log(JSON.stringify(payload, null, 2))
+          if (!r.exists) process.exitCode = 1
+          break
+        }
+        if (!r.exists) {
+          console.error(`📭 未找到 local.yaml（候选链均无此文件：${r.searched.slice(0, 3).join(' ; ')} …）`)
+          console.error('   注意：local.yaml 恒在 .sillyspec/ 下，项目根目录没有这个文件。')
+          console.error('   生成：sillyspec local detect（本地嗅探）/ sillyspec platform connect（平台凭据）')
+          console.error('   可用键清单：sillyspec config schema')
+          process.exitCode = 1
+          break
+        }
+        console.log(`📄 ${r.path}（来源：${r.source}）`)
+        const content = readFileSync(r.path, 'utf8')
+        process.stdout.write(content)
+        if (!content.endsWith('\n')) process.stdout.write('\n')
+        break;
+      }
       if (!isSchema) {
-        const sug = didYouMean(configSub, ['schema']);
+        const sug = didYouMean(configSub, ['schema', 'cat']);
         console.error(`❌ 未知子命令: config ${configSub}`);
         if (sug) console.error(`   你是想输入「config ${sug}」吗？`);
-        console.error('用法: sillyspec config [schema] [--json]   打印 local.yaml 配置键');
+        console.error('用法: sillyspec config [schema|cat] [--json]   打印 local.yaml 配置键 / 读取实际内容');
         process.exit(2);
       }
       const { renderSchemaHuman, renderSchemaJson } = await import('./config-schema.js');