sillyspec 3.26.15 → 3.27.2

package/src/doctor-diagnostics.js

@@ -582,6 +582,57 @@ function detectExecuteProgressPlanMismatch(authoritySpecRoot, authDb) {
 
 // ── 主入口 ────────────────────────────────────────────────────────────
 
+// ── 文档膨胀检测（token 成本优化 P0b/P2b，2026-08-22-token-cost-optimization）──
+// 模块卡与 knowledge/uncategorized.md 是每个 task 子代理的重复读取税：实测 backend.md
+// 18 天 15KB→55KB（变更索引段每变更追加、单调膨胀）、uncategorized.md 38KB 从未迁出。
+// 只读软检查（WARNING 级，不阻断）：超限给 safe_action 指路，不自动改文件。
+
+/** 模块卡整卡可读软上限（字节），与 module-resolve.js MODULE_CARD_SOFT_LIMIT_BYTES 同值 */
+const DOC_BLOAT_MODULE_CARD_LIMIT = 12 * 1024;
+/** knowledge/uncategorized.md 软上限（字节）——待确认条目应经知识审阅迁移，不该只增不减 */
+const DOC_BLOAT_UNCATEGORIZED_LIMIT = 20 * 1024;
+
+export function detectDocBloat(specRoot) {
+  const dim = { name: 'doc_bloat', label: '文档膨胀（模块卡/知识库读取税）', safe_actions: [] };
+  const findings = [];
+  if (!specRoot || !existsSync(specRoot)) {
+    return { ...dim, findings: ['无可达 specRoot，跳过文档膨胀检测'], pass: true, severity: null };
+  }
+  // 模块卡：docs/<p>/modules/*.md（排除 _module-map.yaml 与 *.changelog.md sidecar）
+  try {
+    for (const proj of readdirSync(join(specRoot, 'docs'), { withFileTypes: true })) {
+      if (!proj.isDirectory()) continue;
+      const modulesDir = join(specRoot, 'docs', proj.name, 'modules');
+      if (!existsSync(modulesDir)) continue;
+      for (const f of readdirSync(modulesDir)) {
+        if (!f.endsWith('.md') || f === '_module-map.yaml' || f.endsWith('.changelog.md')) continue;
+        const size = statSync(join(modulesDir, f)).size;
+        if (size > DOC_BLOAT_MODULE_CARD_LIMIT) {
+          findings.push(`模块卡超软上限 ${DOC_BLOAT_MODULE_CARD_LIMIT / 1024}KB：docs/${proj.name}/modules/${f}（${(size / 1024).toFixed(1)}KB）——子代理每次整读都是读取税`);
+        }
+      }
+    }
+  } catch { /* docs 不可读 → 跳过该项 */ }
+  if (findings.length > 0) {
+    dim.safe_actions.push({ action: '跑 sillyspec modules split-changelog（先 dry-run 预览，确认后 --force）把「变更索引」历史段迁出大卡', risk: 'low' });
+  }
+  // knowledge/uncategorized.md
+  try {
+    const uncPath = join(specRoot, 'knowledge', 'uncategorized.md');
+    if (existsSync(uncPath)) {
+      const size = statSync(uncPath).size;
+      if (size > DOC_BLOAT_UNCATEGORIZED_LIMIT) {
+        findings.push(`knowledge/uncategorized.md 超软上限 ${DOC_BLOAT_UNCATEGORIZED_LIMIT / 1024}KB（${(size / 1024).toFixed(1)}KB）——已确认/已修复条目应迁入专题文件后从待确认清单删除，而非只增不减`);
+        dim.safe_actions.push({ action: 'execute 末步「知识库审阅」把已确认条目归档迁出 uncategorized.md（迁入专题文件后删除原条目）', risk: 'low' });
+      }
+    }
+  } catch { /* knowledge 不可读 → 跳过该项 */ }
+
+  dim.findings = findings;
+  return findings.length === 0
+    ? { ...dim, findings: ['模块卡与知识库体量在软限内'], pass: true, severity: CHECK_SEVERITY.PASSED }
+    : { ...dim, pass: false, severity: CHECK_SEVERITY.WARNING };
+}
 export async function runDoctorDiagnostics({ cwd }) {
   const pointer = resolvePointer(cwd);
   const multiDb = detectMultiDb(cwd, pointer);
@@ -598,8 +649,9 @@ export async function runDoctorDiagnostics({ cwd }) {
         : null;
   const authDb = (multiDb.dbs || []).find((d) => d.role === DB_ROLE.AUTHORITY);
   const executeMismatch = detectExecuteProgressPlanMismatch(authoritySpecDir, authDb);
+  const docBloat = detectDocBloat(authoritySpecDir);
 
-  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch];
+  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat];
 
   return {
     dimensions,

package/src/endpoint-extractor.js

@@ -160,8 +160,13 @@ export function extractSpringEndpoints(filePath) {
  * @returns {Array<{ method: string, path: string, source: string, line: number }>}
  */
 export function scanBackendEndpoints(dir, opts = {}) {
+  // 排除清单对齐 scanFrontendApiCalls（坑 parity-scan-stale-dirs：.claude/worktrees 陈旧检出
+  // 与各类 build 产物混入端点扫描全是噪音）——backend 侧另含 __pycache__/.gradle/maven target
   const excludePatterns = opts.excludePatterns || [
-    /^__pycache__$/, /^node_modules$/, /^\.venv$/, /^\.git$/, /^\.gradle$/,
+    /^__pycache__$/, /^node_modules$/, /^\.venv$/, /^venv$/, /^\.git$/, /^\.gradle$/,
+    /^\.claude$/, /^\.vscode$/, /^\.idea$/, /^\.cursor$/, /^\.next$/, /^\.nuxt$/,
+    /^\.output$/, /^\.turbo$/, /^\.parcel-cache$/, /^coverage$/,
+    /^\.sillyspec$/, /^\.worktrees$/, /^\.d\.ts$/,
     /^(dist|build|target|out)$/i,
     /test/i,
   ]
@@ -273,7 +278,19 @@ export function extractFrontendApiCalls(filePath) {
  */
 export function scanFrontendApiCalls(dir, opts = {}) {
   const filePattern = opts.filePattern || /\.(ts|tsx|js|jsx)$/
-  const excludePatterns = opts.excludePatterns || [/node_modules/, /\.next/, /dist/, /__tests__/, /\.d\.ts$/]
+  // 排除清单（坑 parity-scan-stale-dirs，2026-08-21 实证：扫进 .claude/worktrees/agent-* 陈旧
+  // 检出与 build 产物，872 条调用全是噪音）——目录名匹配，覆盖：
+  //   版本控制/编辑器：.git .claude（含 worktrees/agent-* 陈旧检出）.vscode .idea .cursor
+  //   构建产物：dist build out .next .nuxt .output .turbo .parcel-cache coverage
+  //   依赖/运行时：node_modules .venv venv target（rust/java）__pycache__
+  //   本工具自身：.sillyspec .sillyspec-platform.json 所在 .worktrees
+  // 文件级：.d.ts 声明、*.min.js / *.bundle.js 压缩产物（正则命中即跳）
+  const excludePatterns = opts.excludePatterns || [
+    /^node_modules$/, /^\.git$/, /^\.claude$/, /^\.vscode$/, /^\.idea$/, /^\.cursor$/,
+    /^dist$/, /^build$/, /^out$/, /^\.next$/, /^\.nuxt$/, /^\.output$/, /^\.turbo$/,
+    /^\.parcel-cache$/, /^coverage$/, /^\.venv$/, /^venv$/, /^target$/, /^__pycache__$/,
+    /^\.sillyspec$/, /^\.worktrees$/, /^__tests__$/, /^\.d\.ts$/,
+  ]
 
   const results = []
   if (!existsSync(dir)) return results
@@ -285,6 +302,8 @@ export function scanFrontendApiCalls(dir, opts = {}) {
         if (excludePatterns.some(p => p.test(entry.name))) continue
         walk(full)
       } else if (entry.isFile() && filePattern.test(entry.name)) {
+        if (/\.d\.ts$/.test(entry.name)) continue
+        if (/\.min\.(js|ts)$/.test(entry.name) || /\.bundle\.(js|ts)$/.test(entry.name)) continue
         try {
           results.push(...extractFrontendApiCalls(full))
         } catch {}

package/src/fs-atomic.js

@@ -8,6 +8,7 @@
  * 不经此处的 writeAtomicSync；sillyspec.db 不走原子写改名。
  */
 import { writeFileSync, renameSync, unlinkSync } from 'fs';
+import { randomBytes } from 'node:crypto';
 import { dirname, basename, join } from 'path';
 
 // Windows 上杀毒 / 索引 / IDE 占用文件时，rename 偶发这些错误，短退避重试即可
@@ -58,8 +59,9 @@ export function renameSyncRetry(from, to, retries = 5) {
  */
 export function writeAtomicSync(filePath, content) {
   const dir = dirname(filePath);
-  // pid + 随机段双因子：Windows PID 重用激进，两进程可能撞同 pid，tmp 名碰撞 rename 互相覆盖
-  const rnd = Math.random().toString(36).slice(2, 10);
+  // pid + 随机段双因子：Windows PID 重用激进，两进程可能撞同 pid，tmp 名碰撞 rename 互相覆盖。
+  // crypto 随机源（Math.random 可预测，tmp 名被预猜中有 symlink 预放置理论面）
+  const rnd = randomBytes(6).toString('hex');
   const tmpPath = join(dir, `.${basename(filePath)}.${process.pid}.${rnd}.tmp`);
   writeFileSync(tmpPath, content);
   try {

package/src/git-helper.js

@@ -14,6 +14,69 @@
  */
 import { execFileSync } from 'node:child_process'
 
+/**
+ * git C 风格引号路径解码：`\\` `\"` `\n` `\t` 与 `\NNN` 八进制**原始字节**。
+ * 八进制转义的字节需聚合后按 UTF-8 解码（quotepath 关闭前非 ASCII 整段转义、
+ * 关闭后控制字符路径仍会转义），逐字节单独 toString 会拆出 U+FFFD。
+ * @param {string} s 已去外层引号的内容
+ * @returns {string}
+ */
+export function unquoteGitPath(s) {
+  const parts = []
+  let out = ''
+  let bytes = []
+  const flushText = () => {
+    if (bytes.length) {
+      parts.push(Buffer.from(bytes).toString('utf8'))
+      bytes = []
+    }
+  }
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i]
+    if (ch !== '\\') {
+      out += ch
+      continue
+    }
+    const n = s[i + 1]
+    if (n === 'n' || n === 't' || n === '"' || n === '\\') {
+      flushText()
+      out += n === 'n' ? '\n' : n === 't' ? '\t' : n
+      i++
+      continue
+    }
+    const m = /^[0-7]{3}/.exec(s.slice(i + 1, i + 4))
+    if (m) {
+      if (out) {
+        parts.push(out)
+        out = ''
+      }
+      bytes.push(parseInt(m[0], 8))
+      i += 3
+      continue
+    }
+    out += ch // 未知转义保留原样
+  }
+  flushText()
+  if (out) parts.push(out)
+  return parts.join('')
+}
+
+/**
+ * 构造带统一 per-command 配置的 git 参数前缀。
+ * core.quotepath=false：非 ASCII 路径在 porcelain/diff 输出原始 UTF-8 而非 "\346\226\207" 八进制
+ * 转义（中文文件名经 parsePorcelainPath 的 \\(.) 解引会被拆成裸数字拼坏路径）。
+ */
+function buildFullArgs(cwd, args) {
+  return ['-c', `safe.directory=${cwd}`, '-c', 'core.quotepath=false', '-C', cwd, ...args]
+}
+
+// maxBuffer：execFileSync 默认 1MB，untracked 清单/大 diff 超限抛 ENOBUFS——
+// safeGit 吞成 null、调用方 `|| ''` 会把"输出很大"静默变成"输出为空"（补丁漏文件级联）。
+// 32MB 对齐 verify-postcheck 的 diff 读取口径。
+// 256MB（坑 apply-spawnsync-enobufs，2026-08-22 实证：大 diff binary patch 超 32MB 抛
+// ENOBUFS 只能 git merge 绕行）——上限只在真输出那么大时才占用
+const GIT_MAX_BUFFER = 256 * 1024 * 1024
+
 /**
  * 安全执行 git：失败不抛，返回 { value, error } 结构。
  * @param {string} cwd
@@ -29,12 +92,12 @@ import { execFileSync } from 'node:child_process'
  */
 export function safeGit(cwd, args, opts = {}) {
   const { trim = true, timeout = 5000, retryOnTimeout = false } = opts
-  const fullArgs = ['-c', `safe.directory=${cwd}`, '-C', cwd, ...args]
+  const fullArgs = buildFullArgs(cwd, args)
   // 单次尝试：返回 { value, errorObj }（errorObj 为原始 Error 或 null），不在内部格式化 message。
   // 格式化（取首行）推迟到最终返回，避免重试分支重复格式化，并保留原始 code 供重试判定。
   const attempt = (t) => {
     try {
-      let value = execFileSync('git', fullArgs, { encoding: 'utf8', timeout: t, stdio: ['ignore', 'pipe', 'pipe'] })
+      let value = execFileSync('git', fullArgs, { encoding: 'utf8', timeout: t, maxBuffer: GIT_MAX_BUFFER, stdio: ['ignore', 'pipe', 'pipe'] })
       if (trim) value = value.trim()
       return { value, errorObj: null }
     } catch (e) {
@@ -60,14 +123,16 @@ export function safeGit(cwd, args, opts = {}) {
  */
 export function git(cwd, args, opts = {}) {
   const { trim = true, timeout = 5000, encoding = 'utf8' } = opts
-  const fullArgs = ['-c', `safe.directory=${cwd}`, '-C', cwd, ...args]
-  const value = execFileSync('git', fullArgs, { encoding, timeout, stdio: ['ignore', 'pipe', 'pipe'] })
+  const fullArgs = buildFullArgs(cwd, args)
+  const value = execFileSync('git', fullArgs, { encoding, timeout, maxBuffer: GIT_MAX_BUFFER, stdio: ['ignore', 'pipe', 'pipe'] })
   if (Buffer.isBuffer(value)) return value
   return trim ? value.trim() : value
 }
 
 /**
  * 静默版 git：内部调 git，失败 catch 返回 null（对齐 worktree 本地 gitQuiet() 语义）。
+ * ENOBUFS（输出超 32MB）不是"无输出"，静默成 null 会让调用方把大输出误当空清单——
+ * 至少 stderr 留一行，不与正常空结果同语义。
  * @param {string} cwd
  * @param {string[]} args
  * @param {{ trim?: boolean, timeout?: number }} [opts]
@@ -76,7 +141,10 @@ export function git(cwd, args, opts = {}) {
 export function gitQuiet(cwd, args, opts = {}) {
   try {
     return git(cwd, args, opts)
-  } catch {
+  } catch (e) {
+    if (e && e.code === 'ENOBUFS') {
+      console.error(`[sillyspec] git 输出超过 32MB 上限被截断：git ${args.join(' ')}`)
+    }
     return null
   }
 }

package/src/hooks/claude-pre-tool-use.cjs

@@ -33,16 +33,18 @@ async function main() {
   let input = ''
   try {
     input = await readStdin()
-  } catch {
-    // 无法读取 stdin → 放行（安全优先于阻断）
+  } catch (e) {
+    // 无法读取 stdin → 放行（安全优先于阻断），但留痕——本 hook 是阶段门禁唯一执行点，
+    // 静默解除全部防护会让故障无从诊断
+    console.error(`[sillyspec-hook] stdin 读取失败（放行）: ${e.message}`)
     process.exit(0)
   }
 
   let parsed
   try {
     parsed = JSON.parse(input)
-  } catch {
-    // 非法 JSON → 放行
+  } catch (e) {
+    console.error(`[sillyspec-hook] stdin JSON 解析失败（放行）: ${e.message}；input 长度 ${input.length}`)
     process.exit(0)
   }
 
@@ -122,4 +124,7 @@ function readStdin() {
   })
 }
 
-main().catch(() => process.exit(0))
+main().catch(e => {
+  console.error(`[sillyspec-hook] 未捕获异常（放行）: ${e && e.message}`)
+  process.exit(0)
+})

package/src/hooks/worktree-guard.js

@@ -177,7 +177,10 @@ function readScanGuard(scanDocInfo, projectRoot) {
     if (!existsSync(p)) continue
     try {
       return JSON.parse(readFileSync(p, 'utf8'))
-    } catch {
+    } catch (e) {
+      // 半截 JSON（写入窗口读到 truncate 中间态等）不能静默当"无 guard"放行覆盖——
+      // stderr 留痕便于诊断；放行语义不变（fail-open 是既定策略，见 DB 路径对照注释）
+      console.error(`[sillyspec hook] scan-guard.json 解析失败（${e.message.split('\n')[0]}）：${p}`)
       return null
     }
   }
@@ -404,6 +407,12 @@ function parseSimpleYaml(content) {
     return trimmed
   }
 
+  // 原型污染防护：local.yaml 是 agent 可写输入。`__proto__:` 顶层标量行赋值被
+  // setter 忽略但 topKey 落在 '__proto__'，随后缩进子键行经原型链读到的是
+  // Object.prototype（typeof 'object' 跳过重建）直接全局污染——危险键整节拒绝，
+  // 既不进结果也不作为子键挂载点。
+  const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
   for (const line of content.split('\n')) {
     const noComment = line.replace(/\s+#.*$/, '')
     const trimmed = noComment.trim()
@@ -415,6 +424,11 @@ function parseSimpleYaml(content) {
       if (!topLevelMatch) continue
       const key = topLevelMatch[1]
       const value = topLevelMatch[2]
+      if (UNSAFE_KEYS.has(key.trim())) {
+        topKey = null
+        childKey = null
+        continue
+      }
       topKey = key
       childKey = null
 
@@ -437,6 +451,7 @@ function parseSimpleYaml(content) {
     if (indent === 2) {
       const childMatch = trimmed.match(/^([^:]+):\s*(.*)$/)
       if (!childMatch) continue
+      if (UNSAFE_KEYS.has(childMatch[1].trim())) continue
       childKey = childMatch[1]
       const value = childMatch[2]
       if (typeof result[topKey] !== 'object' || Array.isArray(result[topKey])) result[topKey] = {}
@@ -500,8 +515,12 @@ function isSingleCommandReadonly(cmd, extraReadonlyCommands = []) {
     return true
   }
 
-  // local.yaml 扩展
-  if (extraReadonlyCommands.includes(cmdName)) return true
+  // local.yaml 扩展：配置面文档化（config-schema），但 local.yaml 本身是 agent 可写路径——
+  // 命中扩展而非内置白名单时 stderr 留痕，提醒人工复核该放行来源（防 agent 预写扩权静默生效）
+  if (extraReadonlyCommands.includes(cmdName)) {
+    console.error(`[sillyspec hook] 放行依据 = local.yaml worktreeHook.readonlyCommands 扩展（${cmdName}），非内置只读白名单`)
+    return true
+  }
 
   // git 只读子命令
   if (cmdName === 'git') {

package/src/index.js

@@ -85,6 +85,7 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec config cat [--json]           读取 local.yaml 实际内容（自动定位真实路径，worktree 内解析到主仓）
   sillyspec runtime list [--json]         枚举 .sillyspec/.runtime/ 运行时产物（只读，看手上有哪些证据/状态文件）
   sillyspec dispatch <probe | hint>       SillyHub 派发能力探测 + 策略生成（agent 调用桥，仅渲染不执行 tool）
+  sillyspec agent-log [--detect] [--json]  本地 agent 会话日志查询/现场探测（run 命令自动上报平台 POST /api/agent-logs 并本地留底）
 
   sillyspec workflow check <name> [--project <p>] [--change <c>] [--json] [--save]
                                       全局 workflow 校验（--save 归档到 .sillyspec/.runtime/workflow-runs/）
@@ -1843,6 +1844,13 @@ SillySpec worktree — git worktree 隔离管理
       }
       break;
     }
+    case 'agent-log': {
+      // 本地 agent 会话日志路径查询/探测（平台会话解析入口）：读 <runtimeRoot>/agent-session-log.json
+      //（run 命令在 agent 环境内自动登记），--detect 现场探测不落盘。协议见 docs/platform-agent-log-protocol.md。
+      const { cmdAgentLog } = await import('./agent-session-log.js');
+      await cmdAgentLog(filteredArgs.slice(1), { json, cwd: dir, specDir });
+      break;
+    }
     case 'dispatch': {
       // SillyHub 派发抽象层的 agent 调用桥（design.md §Phase2 / D-007@v1）：
       // 仅做能力探测（probe）与派发策略生成（hint），**不执行任何 tool 调用**——
@@ -2209,11 +2217,12 @@ SillySpec platform — SillyHub 平台同步
 SillySpec taskcard — 生成 Windows 安全的 TaskCard 骨架
 
 用法:
-  sillyspec taskcard <change-name> --task task-01[,task-02...] [--title <t>] [--title-zh <t>] [--force]
-  sillyspec taskcard <change-name> --all [--force]
+  sillyspec taskcard <change-name> --task task-01[,task-02...] [--title <t>] [--title-zh <t>] [--set key=value]... [--force]
+  sillyspec taskcard <change-name> --all [--set key=value]... [--force]
 
-骨架由 CLI 直写（LF 行尾 + frontmatter 闭合 + 硬校验 9 字段齐全），标题自动取自 plan.md
-checkbox 行；之后用 Edit 填充占位符即可，勿手写整卡（CRLF/漏闭合 ---/漏字段的源头治理）。
+骨架由 CLI 直写（LF 行尾 + frontmatter 闭合 + 硬校验 9 字段齐全），标题自动取自 tasks.md
+checkbox 行；depends_on 自动反填行内注解 "(depends_on: task-01,02)"；--set 批量注入 design
+提炼的字段值（priority 等，yamlScalar 转义）。之后用 Edit 填充占位符即可，勿手写整卡。
 `);
         break;
       }
@@ -2230,6 +2239,20 @@ checkbox 行；之后用 Edit 填充占位符即可，勿手写整卡（CRLF/漏
       const taskVal = getVal('--task');
       const titleVal = getVal('--title');
       const titleZhVal = getVal('--title-zh');
+      // --set key=value（可重复，坑 taskcard-design-field-conflicts）：批量生成时从 design/
+      // plan 提炼的字段值直接注入骨架（yamlScalar 转义、白名单键校验在 buildTaskcardSkeleton），
+      // 省主代理逐卡 Edit 裁决
+      const sets = {};
+      for (let i = 0; i < filteredArgs.length; i++) {
+        if (filteredArgs[i] === '--set' && filteredArgs[i + 1]) {
+          const m = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(filteredArgs[i + 1]);
+          if (!m) {
+            console.error(`❌ --set 格式非法：${filteredArgs[i + 1]}（应为 key=value，可重复）`);
+            process.exit(2);
+          }
+          sets[m[1]] = m[2];
+        }
+      }
 
       if (all && taskVal) {
         console.error('❌ --all 与 --task 互斥（--all 取 plan.md 全部任务，--task 显式指定）');
@@ -2255,7 +2278,7 @@ checkbox 行；之后用 Edit 填充占位符即可，勿手写整卡（CRLF/漏
 
       const { cmdTaskcard } = await import('./taskcard.js');
       try {
-        const result = cmdTaskcard(tcName, { cwd: dir, specDir, taskIds, title: titleVal, titleZh: titleZhVal, force });
+        const result = cmdTaskcard(tcName, { cwd: dir, specDir, 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) {
@@ -2431,6 +2454,12 @@ SillySpec modules — 模块文档管理
   sillyspec modules rebuild [--force]  从模块卡片 + 源码重建 _module-map.yaml（默认 dry-run 预览，--force 才覆盖）
   sillyspec modules status         显示模块索引状态
   sillyspec modules migrate        旧格式模块文档迁移到新格式
+  sillyspec modules resolve --change <名> [--spec-dir <path>] [--json]
+                                   per-task 模块卡级联解析（跨全部 _module-map.yaml 最长前缀匹配，
+                                   子项目细卡优先于根层大卡）——execute 加载上下文同源注入
+  sillyspec modules split-changelog [--force]
+                                   把模块卡「变更索引」历史段迁出到 <module>.changelog.md sidecar
+                                   （默认 dry-run 预览，--force 才写入；治大卡单调膨胀）
 `);
         break;
       }
@@ -2444,8 +2473,30 @@ SillySpec modules — 模块文档管理
       } else if (modulesSub === 'migrate') {
         const { migrateModuleDocs } = await import('./modules.js');
         await migrateModuleDocs(dir);
+      } else if (modulesSub === 'split-changelog') {
+        const { splitChangelog } = await import('./modules.js');
+        const scForce = filteredArgs.includes('--force');
+        splitChangelog(dir, { force: scForce });
+      } else if (modulesSub === 'resolve') {
+        // per-task 模块卡级联解析（token 成本优化 P0a）：execute「加载上下文」步的
+        // {MODULE_RESOLVE_TABLE} 注入同源；独立命令供 agent/人随时查（细卡优先，防整读大卡）
+        const mrChangeIdx = args.indexOf('--change');
+        const mrChange = mrChangeIdx >= 0 && args[mrChangeIdx + 1] ? args[mrChangeIdx + 1] : null;
+        if (!mrChange) {
+          console.error('用法: sillyspec modules resolve --change <名> [--spec-dir <path>] [--json]\n  输出 per-task 最优模块卡表（跨全部 _module-map.yaml 最长前缀匹配，细卡优先）');
+          process.exit(2);
+        }
+        assertSafeChangeName(mrChange, '--change 变更名');
+        const mrSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+        const { resolveChangeModuleCards, renderModuleResolveTable } = await import('./module-resolve.js');
+        if (filteredArgs.includes('--json')) {
+          const r = resolveChangeModuleCards({ cwd: dir, specBase: mrSpecBase, changeName: mrChange });
+          console.log(JSON.stringify(r, null, 2));
+        } else {
+          console.log(renderModuleResolveTable({ cwd: dir, specBase: mrSpecBase, changeName: mrChange }));
+        }
       } else {
-        const modSubs = ['rebuild', 'status', 'migrate'];
+        const modSubs = ['rebuild', 'status', 'migrate', 'resolve', 'split-changelog'];
         const sug = didYouMean(modulesSub, modSubs);
         console.error(`❌ 未知子命令: modules ${modulesSub}`);
         if (sug) console.error(`   你是想输入「modules ${sug}」吗？`);
@@ -2653,6 +2704,7 @@ SillySpec config — local.yaml 配置键速查
         'quick-guard.json': 'quick baseline 守卫（旧位置）',
         'worktrees': 'worktree meta（hooks 侧）',
         'user-inputs.md': '步骤输出/输入历史追加日志',
+        'agent-session-log.json': '本地 agent 会话日志登记留底（run 命令自动 REST 上报平台 POST /api/agent-logs，见 docs/platform-agent-log-protocol.md）',
         'current-quick-run-id': '当前 quick sessionId 指针（--done 无 --change 时 fallback）',
         'scan-runs': '平台模式 scan/workflow 取证目录',
         'artifacts': '派生产物目录（init 预建）',
@@ -2690,7 +2742,7 @@ SillySpec config — local.yaml 配置键速查
       break;
     }
     default: {
-      const topCommands = ['init', 'setup', 'run', 'progress', 'worktree', 'dispatch', 'local', 'workflow', 'gate', 'derive', 'backfill-reviews', 'register-stage-review', 'modules', 'change-rename', 'knowledge', 'platform', 'scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore', 'status', 'doctor', 'auto', 'runtime'];
+      const topCommands = ['init', 'setup', 'run', 'progress', 'worktree', 'dispatch', 'agent-log', 'local', 'workflow', 'gate', 'derive', 'backfill-reviews', 'register-stage-review', 'modules', 'change-rename', 'knowledge', 'platform', 'scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore', 'status', 'doctor', 'auto', 'runtime'];
       const suggestion = didYouMean(command, topCommands);
       console.error(`❌ 未知命令: ${command}`);
       if (command === '--status') {

package/src/module-impact.js

@@ -92,7 +92,9 @@ export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null }
   const modulePaths = parseModuleMapPaths(readFileSync(moduleMapPath, 'utf8'))
   if (modulePaths.size === 0) return null
 
-  const diffFiles = resolveVerifyChangedFiles(cwd, changeName) || []
+  // includeWorkingTree 同 verify module 子集（坑 module-subset-zero-hit-uncommitted）：
+  // worktree 未提交改动也计入模块影响面（module-impact 按实际 diff 归属模块）
+  const diffFiles = resolveVerifyChangedFiles(cwd, changeName, null, { includeWorkingTree: true }) || []
   const sourceFiles = diffFiles.map(f => f.split('\\').join('/')).filter(f => !f.startsWith('.sillyspec/'))
   if (sourceFiles.length === 0) return null
 
@@ -141,6 +143,24 @@ export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null }
   L.push('')
   L.push('逻辑变更 / 数据结构变更 / 接口变更 / 调用关系变更 / 配置变更 / 新增；不确定的影响标 needs review。')
   L.push('')
+  // 「更新结果」表骨架（2026-08-21 审查 CLI-3）：verify --done 死信门（extractPendingDocSyncRows）
+  // 与 archive 移动前校验同一口径硬校验本表无 pending 行，但骨架此前不产出该表——agent 只能
+  // 从 gate 报错反推格式（plan.js prompt 自认的坑）。此处按矩阵命中模块机械生成行，agent 只回填状态。
+  L.push('## 更新结果')
+  L.push('')
+  L.push('| 目标 | 操作 | 状态 |')
+  L.push('|------|------|------|')
+  for (const [moduleId] of rows) {
+    L.push(`| \`modules/${moduleId}.md\` | 更新${moduleId}模块卡（本次变更涉及） | pending |`)
+  }
+  if (unmatched.length > 0) {
+    L.push('| `_module-map.yaml` | <!--TODO: 有未匹配文件，判定模块索引是否需增改（modules rebuild）--> | pending |')
+  } else {
+    L.push('| `_module-map.yaml` | 无变化（未增删模块） | skipped |')
+  }
+  L.push('')
+  L.push('规则：execute/verify 完成文档同步后把对应行回填 done；确定不同步的行改 skipped 并在操作列写明原因。')
+  L.push('')
 
   return { markdown: L.join('\n'), matchedCount: sourceFiles.length - unmatched.length, unmatchedCount: unmatched.length }
 }