sillyspec 3.26.14 → 3.27.1

package/src/init.js

@@ -308,7 +308,7 @@ function doInstall(projectDir, tools, subprojects = [], specDir = null, options
   mkdirSync(knowledgeDir, { recursive: true });
   const indexPath = join(knowledgeDir, 'INDEX.md');
   if (!existsSync(indexPath)) {
-    writeFileSync(indexPath, `# Knowledge Index\n\n> 子代理任务开始前查询此文件，按关键词匹配，只读命中的知识文件。\n> execute/quick 执行中发现的坑自动追加到 uncategorized.md，经用户确认后归类到对应文件。\n\n<!-- 格式：关键词1|关键词2|关键词3 → 文件路径 -->\n<!-- 示例：mybatis-plus|分页|Page → pagination.md -->\n<!-- 示例：跨域|CORS|preflight → cors.md -->\n`);
+    writeFileSync(indexPath, `# Knowledge Index\n\n> 子代理任务开始前查询此文件，按关键词匹配，只读命中的知识文件。\n> 只有遇到真正的项目特有坑（跨变更可复用、未来 agent 可能再次踩到）时才追加到 uncategorized.md；不要为了完成任务硬凑条目。经用户确认后归类到对应文件并更新本索引。\n\n<!-- 格式：关键词1|关键词2|关键词3 → 文件路径 -->\n<!-- 示例：mybatis-plus|分页|Page → pagination.md -->\n<!-- 示例：跨域|CORS|preflight → cors.md -->\n`);
   }
   const uncatPath = join(knowledgeDir, 'uncategorized.md');
   if (!existsSync(uncatPath)) {

package/src/local-register.js

@@ -0,0 +1,98 @@
+/**
+ * local-register.js — `sillyspec local register-repo <key> <path>` 的 repos: 段外科手术式写入。
+ *
+ * 背景（2026-08-21 agent-手工产出审计项④）：跨仓 change 的 repo key 必须在 local.yaml
+ * `repos:` 段注册（MultiRepoContext 约束② fail-closed），此前靠 agent 手编 YAML——正是
+ * agent 满目录找/在根目录乱建 local.yaml 的上游。本模块只动 `repos:` 段：已有该 key 就地
+ * 改值，没有就插入段内；其余内容（注释/凭据段/手调配置）逐行原样保留，绝不整文件重序列化。
+ *
+ * 写入口径与 parseRepoRegistry（plan-postcheck.js，读侧）成对：
+ *   repos:
+ *     sillyspec: C:/Users/you/IdeaProjects/sillyspec
+ *     # main 不用注册（隐式 = cwd）
+ *
+ * 文件不存在时新建只含 repos: 段的 minimal local.yaml（真实 local.yaml 其余段由
+ * `sillyspec local detect` / `platform connect` 各自补齐）。落盘走 writeAtomicSync
+ * （tmp+rename，防多会话并发写半截，与 local detect 写入口径一致）。
+ */
+import { existsSync, readFileSync, mkdirSync } from 'fs'
+import { dirname } from 'path'
+import { writeAtomicSync } from './fs-atomic.js'
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * 把 `<key>: <path>` 注册进 local.yaml 的 repos: 段（幂等，已有该 key 则改值）。
+ *
+ * @param {string} yamlPath - local.yaml 绝对路径（不存在则新建）
+ * @param {string} key - repo key（限 [A-Za-z0-9_.\-]+，'main' 隐式禁止注册）
+ * @param {string} repoPath - 跨仓仓根绝对路径（写入时统一正斜杠，与示例格式一致）
+ * @returns {{ fileCreated: boolean, sectionCreated: boolean, replaced: boolean }}
+ * @throws {Error} key 非法 / key='main' / repoPath 空 / 读写失败
+ */
+export function registerRepoInLocalYaml(yamlPath, key, repoPath) {
+  if (!yamlPath) throw new Error('registerRepoInLocalYaml: yamlPath 不能为空')
+  if (!key || !/^[A-Za-z0-9_.\-]+$/.test(key)) {
+    throw new Error(`repo key 非法: "${key}"（限字母数字 . _ -，与 parseRepoRegistry 读侧口径一致）`)
+  }
+  if (key === 'main') {
+    throw new Error("repo key 'main' 不用注册（隐式 = 主仓 cwd），跨仓仓才需要 register-repo")
+  }
+  if (!repoPath) throw new Error('registerRepoInLocalYaml: repoPath 不能为空')
+
+  const existed = existsSync(yamlPath)
+  // CRLF 归一后按 LF 写回（同 task 卡锚点写入的 CRLF 坑；local.yaml 各 CLI 写入口径均 LF）
+  const raw = existed ? readFileSync(yamlPath, 'utf8').replace(/\r\n?/g, '\n') : ''
+  const posixPath = String(repoPath).replace(/\\/g, '/')
+  const entryLine = `  ${key}: ${posixPath}`
+
+  const write = (text) => {
+    mkdirSync(dirname(yamlPath), { recursive: true })
+    writeAtomicSync(yamlPath, text)
+  }
+
+  const lines = raw.split('\n')
+  // repos: 段起点（顶层 key 行，与 parseRepoRegistry 同口径）
+  let reposIdx = -1
+  for (let i = 0; i < lines.length; i++) {
+    if (/^repos:\s*(?:#.*)?$/.test(lines[i])) { reposIdx = i; break }
+  }
+
+  if (reposIdx === -1) {
+    // 无 repos: 段 → 文件尾追加（保留既有内容与注释；空文件/新文件直接起段）
+    const sep = raw.trim() === '' ? '' : (raw.endsWith('\n') ? '' : '\n') + '\n'
+    write(raw + sep + `repos:\n${entryLine}\n`)
+    return { fileCreated: !existed, sectionCreated: true, replaced: false }
+  }
+
+  // 段范围：reposIdx+1 起到下一个顶层 key（行首非空白非注释）为止（与 parseRepoRegistry 同口径）
+  let end = lines.length
+  for (let i = reposIdx + 1; i < lines.length; i++) {
+    const l = lines[i]
+    if (l.length > 0 && !/^[\s#]/.test(l) && l.trim() !== '') { end = i; break }
+  }
+
+  // 已有该 key → 就地改值（幂等）
+  const keyRe = new RegExp(`^\\s+${escapeRe(key)}:\\s`)
+  for (let i = reposIdx + 1; i < end; i++) {
+    if (keyRe.test(lines[i])) {
+      if (lines[i] === entryLine) {
+        return { fileCreated: false, sectionCreated: false, replaced: false } // 值未变，幂等跳过
+      }
+      lines[i] = entryLine
+      write(lines.join('\n'))
+      return { fileCreated: false, sectionCreated: false, replaced: true }
+    }
+  }
+
+  // 无该 key → 插到段内最后一个非空行（条目或段内注释）之后
+  let insertAt = reposIdx + 1
+  for (let i = reposIdx + 1; i < end; i++) {
+    if (lines[i].trim() !== '') insertAt = i + 1
+  }
+  lines.splice(insertAt, 0, entryLine)
+  write(lines.join('\n'))
+  return { fileCreated: false, sectionCreated: false, replaced: false }
+}

package/src/module-impact.js

@@ -0,0 +1,166 @@
+/**
+ * module-impact.js — `sillyspec module-impact` 的归类骨架生成
+ * （2026-08-21 agent-手工产出审计第三批 D3）。
+ *
+ * archive 阶段的 module-impact.md 要求「模块影响矩阵」+「未匹配文件」两章节、≥20 行，
+ * agent 此前从零手写整份矩阵。文件 × 模块的归属是纯机械分类（module-map paths 前缀匹配，
+ * 与 scan diff 归属同源），影响类型判定（逻辑/数据结构/接口/调用关系/配置/新增）是语义——
+ * 骨架预填「模块|文件|状态」三列，影响类型列留 <!--TODO--> 由 agent 逐行填。
+ *
+ * diff 源：resolveVerifyChangedFiles（worktree-aware，与 task-review 同源）；
+ * module-map：.sillyspec/docs/<p>/modules/_module-map.yaml 的 modules.<id>.paths
+ * （目录条目以 / 结尾按前缀匹配，与模块上下文索引读侧口径一致）。
+ */
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { join } from 'path'
+import { resolveVerifyChangedFiles } from './verify-postcheck.js'
+import { resolveSpecDir } from './run/shared.js'
+
+/**
+ * 轻量解析 _module-map.yaml：modules.<id>.paths 列表（手写解析同 parseRepoRegistry 风格，
+ * 只取 paths 平面信息，status/doc 等忽略）。
+ * @returns {Map<string, string[]>} moduleId → paths（posix）
+ */
+export function parseModuleMapPaths(yamlText) {
+  const map = new Map()
+  if (!yamlText) return map
+  let currentModule = null
+  let inPaths = false
+  for (const line of yamlText.split('\n')) {
+    if (!line.trim() || line.trim().startsWith('#')) continue
+    if (!/^\s/.test(line)) {
+      inPaths = line.startsWith('modules:')
+      currentModule = null
+      continue
+    }
+    const modMatch = line.match(/^  ([A-Za-z0-9_.\-]+):\s*$/)
+    if (modMatch) {
+      currentModule = modMatch[1]
+      inPaths = false
+      continue
+    }
+    if (currentModule && /^    paths:\s*$/.test(line)) {
+      inPaths = true
+      if (!map.has(currentModule)) map.set(currentModule, [])
+      continue
+    }
+    if (inPaths && currentModule) {
+      const item = line.match(/^      - (.+)$/)
+      if (item) map.get(currentModule).push(item[1].trim().replace(/\\/g, '/'))
+    }
+  }
+  return map
+}
+
+function classifyFile(posixPath, modulePaths) {
+  for (const [moduleId, paths] of modulePaths) {
+    for (const p of paths) {
+      // 目录条目以 / 结尾 → 前缀匹配；文件条目 → 精确或子路径（与模块上下文索引读侧口径一致）
+      if (p.endsWith('/')) {
+        if (posixPath.startsWith(p)) return moduleId
+      } else if (posixPath === p || posixPath.startsWith(p + '/')) {
+        return moduleId
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * 生成 module-impact.md 骨架。
+ * @param {{ cwd: string, changeName: string, specDir?: string|null }} opts
+ * @returns {{ markdown: string, matchedCount: number, unmatchedCount: number }|null}
+ *   无 module-map / 无 diff → null（无可归类输入，agent 全手写）
+ */
+export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null }) {
+  const specBase = resolveSpecDir(cwd, { specDir })
+
+  // 找 _module-map.yaml（docs/<p>/modules/；多项目取首个含 modules 索引的）
+  let moduleMapPath = null
+  try {
+    for (const p of readdirSync(join(specBase, 'docs'), { withFileTypes: true })) {
+      if (!p.isDirectory()) continue
+      const candidate = join(specBase, 'docs', p.name, 'modules', '_module-map.yaml')
+      if (existsSync(candidate)) {
+        moduleMapPath = candidate
+        break
+      }
+    }
+  } catch { /* 无 docs/ */ }
+  if (!moduleMapPath) return null
+
+  const modulePaths = parseModuleMapPaths(readFileSync(moduleMapPath, 'utf8'))
+  if (modulePaths.size === 0) return null
+
+  // 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
+
+  const byModule = new Map()
+  const unmatched = []
+  for (const f of sourceFiles) {
+    const mod = classifyFile(f, modulePaths)
+    if (mod) {
+      if (!byModule.has(mod)) byModule.set(mod, [])
+      byModule.get(mod).push(f)
+    } else {
+      unmatched.push(f)
+    }
+  }
+
+  const L = [
+    '# 模块影响分析（骨架由 `sillyspec module-impact --change <变更名>` 生成）',
+    '',
+    '> 文件×模块归属由 CLI 按 _module-map.yaml paths 前缀匹配预填；',
+    '> **影响类型**（逻辑变更/数据结构变更/接口变更/调用关系变更/配置变更/新增）与 review 标记是语义判断，',
+    '> 逐行把 <!--TODO--> 替换为真实结论——以 git diff 为准（真实 > 声明）。',
+    '',
+    '## 模块影响矩阵',
+    '',
+    '| 模块 | 变更文件 | 影响类型 | 需 review |',
+    '|---|---|---|---|',
+  ]
+  const rows = [...byModule.entries()].sort((a, b) => a[0].localeCompare(b[0]))
+  for (const [moduleId, files] of rows) {
+    for (const f of files) {
+      L.push(`| ${moduleId} | \`${f}\` | <!--TODO--> | <!--TODO--> |`)
+    }
+  }
+  L.push('')
+  L.push('## 未匹配文件')
+  L.push('')
+  if (unmatched.length === 0) {
+    L.push('无（全部变更文件已归属到模块）。')
+  } else {
+    L.push('以下变更文件未命中 _module-map.yaml 任何模块 paths——确认是模块索引过期（该跑 `sillyspec modules rebuild`）还是真的游离文件：')
+    L.push('')
+    for (const f of unmatched) L.push(`- \`${f}\` <!--TODO: 归属判定-->`)
+  }
+  L.push('')
+  L.push('## 影响类型说明')
+  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 }
+}

package/src/module-resolve.js

@@ -0,0 +1,211 @@
+/**
+ * module-resolve.js — 模块卡两级级联解析（token 成本优化 P0a，2026-08-22-token-cost-optimization）
+ *
+ * 背景（multi-agent-platform 2026-08-22 实测）：monorepo 根层 _module-map.yaml 把整个子项目
+ * （backend/**）映射到单张大卡（backend.md 58KB），而子项目细粒度卡（docs/backend/modules/
+ * agent.md，~6KB）由 scan 生成却无人消费——execute 每个 task 子代理都被指引去读整张大卡，
+ * 单卡一项全流程烧 20 万+ tokens 输入，且大卡「变更索引」段每变更追加、单调膨胀。
+ *
+ * 本模块 = 纯机械分类（与 module-impact.js 同性质，CLI 算事实）：
+ *   - collectModuleMaps：收齐 <spec>/docs/<project>/modules/_module-map.yaml 全部层级；
+ *     project 名恰为仓库顶层目录（monorepo 子项目，如 backend/）→ 其 paths 视为相对该
+ *     子目录（effective = `<project>/` + path）；否则视为仓库根相对（根层粗粒度 map）
+ *   - matchModuleCard：跨全部 map 最长有效前缀匹配（细卡 agent/** 胜过粗卡 backend/**）
+ *   - resolveChangeModuleCards：tasks.md 注册表 × tasks/task-NN.md allowed_paths → per-task
+ *     最优卡表；卡的体量（字节数）一并给出，读取建议按体量分级（>12KB 按节读）
+ *
+ * 铁律（对齐仓内先例）：
+ *   - 纯读：不写任何文件，不跑 git
+ *   - 无 map / 无 tasks.md / 无 task 卡 → 空结果（调用方注入占位说明，不抛）
+ *   - 判定语义（哪个模块才是「对的」）仍归 agent——本表只是机械最优匹配
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
+import { join, relative } from 'path'
+import { parseModuleMapSimple } from './modules.js'
+import { parseTaskRegistry } from './stages/execute.js'
+import { parseAllowedPaths } from './stages/plan-postcheck.js'
+
+/** 模块卡「整卡可读」软上限（字节）。超过则建议按节读（契约摘要/注意事项/定位），跳过历史累积段。 */
+export const MODULE_CARD_SOFT_LIMIT_BYTES = 12 * 1024
+
+/**
+ * 收齐 spec 下全部模块映射层。
+ * @param {{ cwd: string, specBase: string }} opts
+ * @returns {Array<{ project: string, mapPath: string, modulesDir: string, prefix: string,
+ *            entries: Map<string, { paths: string[], doc: string|null }> }>}
+ *   prefix：project 名为仓库顶层目录时 `<project>/`（子项目细 map），否则 ''（根层粗 map）
+ */
+export function collectModuleMaps({ cwd, specBase }) {
+  const maps = []
+  const docsDir = join(specBase, 'docs')
+  if (!existsSync(docsDir)) return maps
+  let projects = []
+  try {
+    projects = readdirSync(docsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name)
+  } catch { return maps }
+  for (const project of projects) {
+    const modulesDir = join(docsDir, project, 'modules')
+    const mapPath = join(modulesDir, '_module-map.yaml')
+    if (!existsSync(mapPath)) continue
+    let parsed = {}
+    try {
+      parsed = parseModuleMapSimple(readFileSync(mapPath, 'utf8'))
+    } catch { continue }
+    const entries = new Map()
+    for (const [id, data] of Object.entries(parsed)) {
+      const paths = Array.isArray(data?.paths) ? data.paths : []
+      if (paths.length === 0) continue
+      entries.set(id, { paths, doc: typeof data?.doc === 'string' ? data.doc : null })
+    }
+    if (entries.size === 0) continue
+    // 子项目判定：project 名恰为仓库顶层目录 → map 的 paths 相对该子目录（monorepo 细 map）。
+    // 根层 map（project = 仓名）paths 本就仓库根相对，prefix=''。
+    let prefix = ''
+    try {
+      const topDir = join(cwd, project)
+      if (existsSync(topDir) && statSync(topDir).isDirectory()) prefix = `${project}/`
+    } catch { /* stat 失败按根层处理 */ }
+    maps.push({ project, mapPath, modulesDir, prefix, entries })
+  }
+  return maps
+}
+
+/**
+ * 路径归一：反斜杠→正斜杠，剥尾部 glob（/** 与 /*）与目录斜杠。
+ * `backend/**` / `backend/` / `backend` → `backend`。
+ */
+function normalizeMapPath(raw) {
+  return String(raw).replace(/\\/g, '/').replace(/\/\*\*$/, '').replace(/\/\*$/, '').replace(/\/$/, '')
+}
+
+/**
+ * 跨全部 map 最长有效前缀匹配一个仓库根相对路径。
+ * @param {string} posixPath 仓库根相对 posix 路径
+ * @param {Array} maps collectModuleMaps 产物
+ * @returns {{ moduleId: string, map: object, effectivePrefix: string }|null}
+ */
+export function matchModuleCard(posixPath, maps) {
+  const p = String(posixPath).replace(/\\/g, '/')
+  let best = null
+  for (const map of maps) {
+    for (const [moduleId, entry] of map.entries) {
+      for (const raw of entry.paths) {
+        const effective = (map.prefix + normalizeMapPath(raw)).replace(/\/+$/, '')
+        if (!effective) continue
+        if (p === effective || p.startsWith(effective + '/')) {
+          if (!best || effective.length > best.effectivePrefix.length) {
+            best = { moduleId, map, effectivePrefix: effective }
+          }
+        }
+      }
+    }
+  }
+  return best
+}
+
+/**
+ * 解析变更全部 task 的最优模块卡。
+ * @param {{ cwd: string, specBase: string, changeName: string }} opts
+ * @returns {{ hasMaps: boolean, rows: Array<{ taskId: string, taskName: string,
+ *            moduleId: string|null, granularity: 'fine'|'coarse'|null,
+ *            cardPath: string|null, cardBytes: number, advice: string,
+ *            matchedCount: number, pathCount: number }> }}
+ *   granularity：按胜者有效前缀段数判——1 段（整子项目）=coarse 大卡，≥2 段=fine 细卡
+ */
+export function resolveChangeModuleCards({ cwd, specBase, changeName }) {
+  const maps = collectModuleMaps({ cwd, specBase })
+  const changeDir = join(specBase, 'changes', changeName || '')
+  let registry = []
+  const tasksMd = join(changeDir, 'tasks.md')
+  if (existsSync(tasksMd)) {
+    registry = parseTaskRegistry(readFileSync(tasksMd, 'utf8'))
+  }
+  const rows = []
+  for (const task of registry) {
+    // 任务路径源：task 卡 allowed_paths（主）> 注册表行内 (文件路径) 尾注（兜底）
+    let paths = []
+    const cardFile = join(changeDir, 'tasks', `${task.id}.md`)
+    if (existsSync(cardFile)) {
+      paths = parseAllowedPaths(readFileSync(cardFile, 'utf8'))
+    }
+    if (paths.length === 0 && task.file) paths = [task.file]
+    paths = paths.map(p => p.replace(/\\/g, '/')).filter(Boolean)
+
+    // 全路径逐个匹配，取「最长有效前缀」的模块为该 task 的最优卡。粒度按有效前缀段数判：
+    // 1 段（backend/frontend 整子项目）=粗层大卡；≥2 段=细层卡（段数与卡体量正相关，
+    // SillyHub 这类根相对细 map 同样正确——不能按 map 的 prefix 有无判，会误标）
+    let winner = null
+    let matchedCount = 0
+    for (const p of paths) {
+      const m = matchModuleCard(p, maps)
+      if (!m) continue
+      matchedCount++
+      if (!winner || m.effectivePrefix.length > winner.effectivePrefix.length) winner = m
+    }
+    let granularity = null
+    if (winner) {
+      const segs = winner.effectivePrefix.split('/').filter(Boolean).length
+      granularity = segs >= 2 ? 'fine' : 'coarse'
+    }
+
+    let cardPath = null
+    let cardBytes = 0
+    let advice = '—'
+    if (winner) {
+      const docRel = winner.map.entries.get(winner.moduleId)?.doc || `modules/${winner.moduleId}.md`
+      const abs = join(winner.map.modulesDir, '..', docRel)
+      if (existsSync(abs)) {
+        const rel = relative(cwd, abs).replace(/\\/g, '/')
+        cardPath = rel.startsWith('..') ? abs.replace(/\\/g, '/') : rel
+        try { cardBytes = statSync(abs).size } catch { cardBytes = 0 }
+        advice = cardBytes > MODULE_CARD_SOFT_LIMIT_BYTES
+          ? `按节读（契约摘要/注意事项/定位；跳过变更索引/人工备注）`
+          : '整卡可读'
+      } else {
+        cardPath = relative(cwd, abs).replace(/\\/g, '/')
+        advice = '卡文件缺失（modules rebuild？）'
+      }
+    }
+    rows.push({
+      taskId: task.id,
+      taskName: task.name,
+      moduleId: winner ? winner.moduleId : null,
+      granularity,
+      cardPath,
+      cardBytes,
+      advice,
+      matchedCount,
+      pathCount: paths.length,
+    })
+  }
+  return { hasMaps: maps.length > 0, rows }
+}
+
+/**
+ * 渲染 per-task 模块卡表（注入 execute「加载上下文」步 prompt 用）。
+ * 无 map → 提示跳过；有 map 无命中行 → 单行说明。恒返回非空字符串（占位符必被替换）。
+ */
+export function renderModuleResolveTable({ cwd, specBase, changeName }) {
+  const { hasMaps, rows } = resolveChangeModuleCards({ cwd, specBase, changeName })
+  if (!hasMaps) return '（未找到 _module-map.yaml——本项目无模块卡，跳过模块文档加载）'
+  const withMatch = rows.filter(r => r.moduleId)
+  if (withMatch.length === 0) {
+    return '（已找到 _module-map.yaml，但当前变更任务未命中任何模块 paths——跳过模块文档加载；游离文件可在 Wave 收尾后跑 `sillyspec modules rebuild`）'
+  }
+  const kb = (n) => n > 0 ? `${(n / 1024).toFixed(1)}KB` : '?'
+  const L = [
+    '| task | 模块 | 粒度 | 模块卡（只读命中的卡，勿按目录整读） | 体量 | 读取建议 |',
+    '|---|---|---|---|---|---|',
+  ]
+  for (const r of rows) {
+    if (r.moduleId) {
+      L.push(`| ${r.taskId} | ${r.moduleId} | ${r.granularity === 'fine' ? '细' : '粗'} | \`${r.cardPath}\` | ${kb(r.cardBytes)} | ${r.advice} |`)
+    } else {
+      L.push(`| ${r.taskId} | — | — | （无命中，跳过模块文档） | — | — |`)
+    }
+  }
+  L.push('')
+  L.push('> 匹配规则：全部 _module-map.yaml 跨层最长前缀（子项目细卡优先于根层大卡），源=tasks 卡 allowed_paths。')
+  L.push('> 细卡整卡可读；仅粗卡命中且体量大时**按节读**——只读「契约摘要/注意事项/定位」，跳过「变更索引/人工备注」历史累积段。')
+  return L.join('\n')
+}

package/src/modules.js

@@ -181,11 +181,91 @@ export async function rebuildModuleMap(cwd, { force = false } = {}) {
   return { dryRun: false, path: mapPath, modules: allModuleIds.size }
 }
 
+/**
+ * split-changelog：把模块卡的「变更索引」历史段迁出到同目录 <module>.changelog.md sidecar
+ * （token 成本优化 P0b，2026-08-22-token-cost-optimization）。
+ *
+ * 背景：变更索引段每变更追加、单调膨胀（multi-agent-platform backend.md 实测 19.9KB/占整卡
+ * 36%，18 天 3.6 倍），而子代理实现新 task 只需要卡的「定位/契约摘要/注意事项」当前态——
+ * 历史段是纯读取税。迁出后卡只留指针行，新条目由 prompt 约定直接追加 sidecar。
+ *
+ * 安全（对齐 rebuild 的破坏性保护）：默认 dry-run 只预览不写，--force 才落盘。
+ * 只动「## 变更索引」一节，卡内其他节原样保留；sidecar 已存在则追加（幂等可重跑）。
+ *
+ * @param {string} cwd 项目根
+ * @param {{ force?: boolean }} opts
+ * @returns {{ dryRun: boolean, files: Array<{ card: string, sidecar: string, bytesMoved: number }>, skipped: number }}
+ */
+export function splitChangelog(cwd, { force = false } = {}) {
+  const docsDir = join(cwd, '.sillyspec', 'docs');
+  const results = [];
+  let skipped = 0;
+  const projects = existsSync(docsDir)
+    ? readdirSync(docsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name)
+    : [];
+
+  for (const project of projects) {
+    const modulesDir = join(docsDir, project, 'modules');
+    if (!existsSync(modulesDir)) continue;
+    const cards = readdirSync(modulesDir).filter(f => f.endsWith('.md') && f !== '_module-map.yaml');
+    for (const f of cards) {
+      const cardPath = join(modulesDir, f);
+      const content = readFileSync(cardPath, 'utf8');
+      // 提取「## 变更索引」节（CRLF 归一后行级匹配，与 modules.js 其余解析同防线）
+      const lines = content.replace(/\r\n/g, '\n').split('\n');
+      const startIdx = lines.findIndex(l => /^##\s*变更索引\s*$/.test(l));
+      if (startIdx < 0) { skipped++; continue; }
+      let endIdx = lines.length;
+      for (let i = startIdx + 1; i < lines.length; i++) {
+        if (/^##\s/.test(lines[i])) { endIdx = i; break; }
+      }
+      const body = lines.slice(startIdx + 1, endIdx).join('\n').trim();
+      // 已迁出（只剩指针行）或本就为空 → 跳过
+      if (!body || /^见\s/.test(body) || body.includes('.changelog.md')) { skipped++; continue; }
+      const bytesMoved = Buffer.byteLength(body, 'utf8');
+      const stem = f.replace(/\.md$/, '');
+      const sidecarPath = join(modulesDir, `${stem}.changelog.md`);
+      results.push({ card: cardPath, sidecar: sidecarPath, bytesMoved, _lines: lines, _startIdx: startIdx, _endIdx: endIdx, _body: body });
+    }
+  }
+
+  if (!force) {
+    if (results.length === 0) {
+      console.log('📭 没有需要迁出的「变更索引」段（无模块卡 / 已迁出 / 段为空）');
+    } else {
+      console.log('⚠️  split-changelog 默认不写入（破坏性保护）：会把模块卡「变更索引」节迁出到同目录 <module>.changelog.md');
+      for (const r of results) {
+        console.log(`    ${r.card} → ${r.sidecar}（${(r.bytesMoved / 1024).toFixed(1)}KB）`);
+      }
+      console.log('    本次为预览，未写入磁盘。确认迁出请运行：sillyspec modules split-changelog --force');
+    }
+    return { dryRun: true, files: results.map(({ card, sidecar, bytesMoved }) => ({ card, sidecar, bytesMoved })), skipped };
+  }
+
+  for (const r of results) {
+    // sidecar：已存在追加（分隔线 + 迁出来源），否则新建带头部
+    const header = `# ${r.card.split(/[\\/]/).pop().replace(/\.md$/, '')} 变更索引\n\n> 由 sillyspec modules split-changelog 自模块卡迁出；新条目继续追加到本文件，勿写回模块卡。\n`;
+    let sidecarContent = header;
+    if (existsSync(r.sidecar)) {
+      sidecarContent = readFileSync(r.sidecar, 'utf8').replace(/\s*$/, '') + '\n\n---\n\n' + r._body + '\n';
+    } else {
+      sidecarContent = header + '\n' + r._body + '\n';
+    }
+    writeFileSync(r.sidecar, sidecarContent, 'utf8');
+    // 卡内节体替换为指针行（只动该节，其余逐字保留；_lines 已是 LF 归一）
+    const stem = r.card.split(/[\\/]/).pop().replace(/\.md$/, '');
+    const newLines = [...r._lines.slice(0, r._startIdx + 1), '', `见 \`${stem}.changelog.md\`——历史条目已迁出；新条目直接追加 sidecar，勿写回本卡。`, '', ...r._lines.slice(r._endIdx)];
+    writeFileSync(r.card, newLines.join('\n'), 'utf8');
+    console.log(`✅ ${r.card} → ${r.sidecar}（迁出 ${(r.bytesMoved / 1024).toFixed(1)}KB，卡内留指针）`);
+  }
+  if (results.length === 0) console.log('📭 没有需要迁出的「变更索引」段');
+  return { dryRun: false, files: results.map(({ card, sidecar, bytesMoved }) => ({ card, sidecar, bytesMoved })), skipped };
+}
+
 /**
  * status: 显示模块索引状态
  */
-export async function showModuleStatus(cwd) {
-  const mapPath = findModuleMapPath(cwd);
+export async function showModuleStatus(cwd) {  const mapPath = findModuleMapPath(cwd);
   if (!mapPath || !existsSync(mapPath)) {
     console.log('📭 未找到 _module-map.yaml');
     console.log('   提示：先运行 sillyspec run scan 生成模块文档');

package/src/progress/change-registry.js

@@ -276,8 +276,15 @@ export class ChangeRegistry {
   /**
    * 从活跃列表移除变更（归档时调用，不物理删除）
    * SQL: UPDATE changes SET status = 'archived'
+   *
+   * 归档终态一致化（坑 manual-archive-desync-status-only，2026-08-21 实证）：手动搬目录绕过
+   * `run archive --done --confirm` 后，自愈/幽灵清理路径只改 status 一个字段，留下「已归档 +
+   * current_stage 停在 execute + 归档 0/5 步」的自相矛盾终态，推送平台后渲染成「进度丢失」。
+   * opts.archiveStepNames（调用方取自 stageRegistry 单一真相）给定时同事务收尾：
+   * current_stage='archive' + stages.archive=completed + 其步骤行全 completed
+   * （缺行按定义补种——平台按步骤数展示完成度，零行会显示 0/5）。
    */
-  unregisterChange(cwd, changeName) {
+  unregisterChange(cwd, changeName, opts = {}) {
     if (!changeName) {
       console.warn('⚠️  unregisterChange: changeName 为空，跳过');
       return;
@@ -286,9 +293,41 @@ export class ChangeRegistry {
     db.transaction(() => {
       const sqlDb = db.getDb();
       const now = new Date().toISOString();
-      sqlDb.prepare(
-        `UPDATE changes SET status = 'archived', last_active = ? WHERE name = ?`
-      ).run(now, changeName);
+      let sql = `UPDATE changes SET status = 'archived', last_active = ?`;
+      const params = [now];
+      if (Array.isArray(opts.archiveStepNames)) sql += `, current_stage = 'archive'`;
+      sql += ` WHERE name = ?`;
+      params.push(changeName);
+      sqlDb.prepare(sql).run(...params);
+      if (Array.isArray(opts.archiveStepNames)) {
+        const row = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(changeName);
+        if (row) {
+          sqlDb.prepare(
+            `INSERT INTO stages (change_id, stage, status, started_at, completed_at)
+             VALUES (?, 'archive', 'completed', ?, ?)
+             ON CONFLICT(change_id, stage) DO UPDATE SET status = 'completed', completed_at = excluded.completed_at`
+          ).run(row.id, now, now);
+          const stageRow = sqlDb.prepare(
+            'SELECT id FROM stages WHERE change_id = ? AND stage = ?'
+          ).get(row.id, 'archive');
+          if (stageRow) {
+            // 现有步骤行（含 pending/waiting）全收尾；定义里有而行里没有的（阶段从未初始化）按定义补种
+            sqlDb.prepare(
+              `UPDATE steps SET status = 'completed', completed_at = ? WHERE stage_id = ?`
+            ).run(now, stageRow.id);
+            const existing = new Set(
+              sqlDb.prepare('SELECT name FROM steps WHERE stage_id = ?').all(stageRow.id).map(r => r.name)
+            );
+            let order = existing.size;
+            const ins = sqlDb.prepare(
+              `INSERT INTO steps (stage_id, name, status, completed_at, ordering) VALUES (?, ?, 'completed', ?, ?)`
+            );
+            for (const name of opts.archiveStepNames) {
+              if (!existing.has(name)) { ins.run(stageRow.id, name, now, order++) }
+            }
+          }
+        }
+      }
       // 本地脏度（D-013 / task-04）：归档也是本地状态推进
       this.pm._touchLocalModified(cwd, changeName, now);
     });