sillyspec 3.27.2 → 3.27.5

package/src/foreign-declared.js

@@ -0,0 +1,78 @@
+/**
+ * 他者会话显式声明文件集（坑 verify-reconcile-foreign-wip，2026-08-23 实证：verify 实测
+ * 对账在主仓共享工作区取 git diff，无 meta 回退时把并行会话在途 WIP 全量算进本变更——误
+ * 命中他者模块跑他者测试 / 他者删除进本变更删除对账误报）。
+ *
+ * 归属口径与坑 35（quick 审计豁免，run/shared 的 collectOtherQuickSessionDeclarations）
+ * 同款：只认**显式声明**——其他 quick 会话 guard.allowedFiles + 其他变更 design §6 清单；
+ * 无主文件保留参与判定（fail-closed，不放松「未声明删除/越界」的抓取底线）。
+ *
+ * 独立零环模块：被 verify-postcheck / verify-probes / contract-matrix 共用（verify-
+ * postcheck import contract-matrix，parity 侧不能反向 import verify-postcheck）。
+ */
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { join } from 'path'
+import { parseFileChangeListDetailed } from './change-list.js'
+
+/**
+ * @param {string} cwd 项目根
+ * @param {string|null} currentChangeName 本变更名（quick 会话名或 change 名，排除自身）
+ * @returns {Map<string, string[]>} file → 声明者列表（quick-<hex> 或变更名）
+ */
+export function collectForeignDeclaredFiles(cwd, currentChangeName) {
+  const foreign = new Map()
+  const add = (file, owner) => {
+    const f = String(file || '').replace(/\\/g, '/')
+    if (!f) return
+    if (!foreign.has(f)) foreign.set(f, [])
+    if (!foreign.get(f).includes(owner)) foreign.get(f).push(owner)
+  }
+  try {
+    const specBase = join(cwd, '.sillyspec')
+    // ① 其他 quick 会话的 --files 显式声明（guard.json）
+    const sessionsDir = join(specBase, '.runtime', 'quick-sessions')
+    let sessionDirs = []
+    try { sessionDirs = readdirSync(sessionsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name) } catch {}
+    for (const sid of sessionDirs) {
+      if (sid === currentChangeName) continue
+      try {
+        const guard = JSON.parse(readFileSync(join(sessionsDir, sid, 'guard.json'), 'utf8'))
+        for (const f of Array.isArray(guard.allowedFiles) ? guard.allowedFiles : []) add(f, sid)
+      } catch { /* 损坏/缺失跳过 */ }
+    }
+    // ② 其他变更的 design §6 清单（目录在即视为在途变更；archive/ 下不算）
+    const changesDir = join(specBase, 'changes')
+    let changeDirs = []
+    try { changeDirs = readdirSync(changesDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name) } catch {}
+    for (const cn of changeDirs) {
+      if (cn === currentChangeName || cn === 'archive') continue
+      const designPath = join(changesDir, cn, 'design.md')
+      if (!existsSync(designPath)) continue
+      try {
+        for (const e of parseFileChangeListDetailed(designPath)) add(e.path, cn)
+      } catch { /* 清单解析失败跳过该变更 */ }
+    }
+  } catch { /* 整体异常 → 空集（等价不过滤，回到原行为） */ }
+  return foreign
+}
+
+/**
+ * 按他者声明集切分 diff 文件（collectForeignDeclaredFiles 的消费端快捷封装）。
+ * @param {string} cwd 项目根
+ * @param {string|null} currentChangeName 本变更名
+ * @param {string[]|null} diffFiles 待切分文件列表（null 透传，保持调用方 null 语义）
+ * @returns {{ own: string[]|null, foreign: Array<{file: string, owners: string[]}> }}
+ */
+export function splitOwnVsForeignDiffFiles(cwd, currentChangeName, diffFiles) {
+  if (!Array.isArray(diffFiles)) return { own: diffFiles, foreign: [] }
+  const foreignMap = collectForeignDeclaredFiles(cwd, currentChangeName)
+  if (foreignMap.size === 0) return { own: diffFiles, foreign: [] }
+  const own = []
+  const foreign = []
+  for (const f of diffFiles) {
+    const owners = foreignMap.get(String(f).replace(/\\/g, '/'))
+    if (owners) foreign.push({ file: f, owners })
+    else own.push(f)
+  }
+  return { own, foreign }
+}

package/src/index.js

@@ -100,6 +100,7 @@ SillySpec CLI — 规范驱动开发工具包
   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 plan-adopt-waves --change <名> [--dry-run]   plan.md Wave 段一键重排为 depends_on 拓扑分组（同步任务总表 W 列，幂等）
   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 翻已取消 + 挂载行移除）
@@ -778,15 +779,22 @@ async function main() {
         process.exit(2);
       }
       assertSafeChangeName(vpChange, '--change 变更名');
-      const { runVerifyProbes, renderVerifyProbesReport, generateVerifyResultSkeleton } = await import('./verify-probes.js');
-      const vpResult = runVerifyProbes({ cwd: dir, changeName: vpChange, specDir });
+      const { runVerifyProbes, renderVerifyProbesReport, generateVerifyResultSkeleton, resolveVerifyProbesSpecBase } = await import('./verify-probes.js');
+      // spec 根统一走漂移锚定（坑 worktree-spec-artifact-misplace）：在 worktree 内跑时锚回主仓，
+      // 探针读取与 --init 骨架都落主仓——与 plan/execute/verify/archive 的 command.js 守卫同口径。
+      // resolvePlatformSpecDir 仍先调（保留平台接管 fail-closed 检查副作用），但仅 pointer 存在时
+      // 才把它的返回值当平台根——无 pointer 时它回退 resolveSpecDir(cwd)，会返回 worktree 副本
+      // 根，当作 platformBase 传入会让锚定被跳过（骨架落回副本）。
+      const vpResolved = resolvePlatformSpecDir(dir, specDir);
+      const vpPlatformBase = existsSync(join(dir, '.sillyspec-platform.json')) ? vpResolved : null;
+      const vpSpecBase = resolveVerifyProbesSpecBase(dir, specDir, vpPlatformBase);
+      const vpResult = runVerifyProbes({ cwd: dir, changeName: vpChange, specDir: vpSpecBase });
       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}`);
@@ -797,6 +805,52 @@ async function main() {
       }
       break;
     }
+    case 'plan-adopt-waves': {
+      // plan.md Wave 段一键重排（坑 wave-manual-mismatch-noise，2026-08-24 用户反馈二期）：
+      // 手排 Wave 与拓扑比对不一致需手改；依赖方向硬拦（plan-postcheck）落地后给一条零手写出路。
+      // depMap 与 postcheck 同源（collectTaskDepMap）→ topoSortWaves → 重写 Wave 段 + 同步任务总表 W 列。
+      const pawChangeIdx = args.indexOf('--change');
+      const pawChange = pawChangeIdx >= 0 && args[pawChangeIdx + 1] ? args[pawChangeIdx + 1] : null;
+      const pawDryRun = args.includes('--dry-run');
+      if (!pawChange) {
+        console.error('用法: sillyspec plan-adopt-waves --change <name> [--dry-run] [--json] [--spec-dir <path>]\n  把 plan.md 的 Wave 段一键重排为 depends_on 拓扑分组（同步任务总表 W 列；--dry-run 只看不写）');
+        process.exit(2);
+      }
+      assertSafeChangeName(pawChange, '--change 变更名');
+      const { adoptPlanWaves } = await import('./plan-adopt-waves.js');
+      const pawSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+      const pawResult = adoptPlanWaves({ changeDir: join(pawSpecBase, 'changes', pawChange), dryRun: pawDryRun });
+      if (json) {
+        console.log(JSON.stringify({ command: 'plan-adopt-waves', change: pawChange, ...pawResult }, null, 2));
+        break;
+      }
+      if (!pawResult.ok) {
+        console.error(`❌ ${pawResult.error}`);
+        process.exit(1);
+      }
+      console.log('📊 拓扑分组（depends_on）：');
+      pawResult.waves.forEach((wave, i) => {
+        console.log(`   Wave ${i + 1}: ${wave.join(', ')}`);
+      });
+      if (pawDryRun) {
+        console.log(`\n👁️ dry-run——将写入 ${pawResult.planPath} 的 Wave 段预览：`);
+        for (const l of pawResult.waveBlock) console.log(`   ${l}`);
+      } else {
+        console.log(`\n✅ plan.md Wave 段已重排: ${pawResult.planPath}（任务总表 W 列更新 ${pawResult.tableRowsUpdated} 行${pawResult.tableRowsSkipped > 0 ? `，${pawResult.tableRowsSkipped} 行非模板格式未改` : ''}；行尾统一 LF）`);
+      }
+      if (pawResult.postcheck) {
+        const pc = pawResult.postcheck;
+        if ((pc.errors || []).length > 0) {
+          console.warn(`⚠️ 重排后 blueprint 一致性问题（topo 只看依赖不看文件重叠——同 Wave 共享路径需手动拆分或补 depends_on）：`);
+          for (const e of pc.errors.slice(0, 10)) console.warn(`   ${e}`);
+          if (pc.errors.length > 10) console.warn(`   …等共 ${pc.errors.length} 条`);
+        } else {
+          console.log('✅ 重排后 blueprint 一致性校验通过（无同 Wave 共享路径冲突）');
+        }
+        for (const w of (pc.warnings || []).slice(0, 5)) console.warn(`⚠️ ${w}`);
+      }
+      break;
+    }
     case 'module-impact': {
       // archive 模块影响矩阵骨架（2026-08-21 审计第三批 D3）：文件×模块归属按 _module-map.yaml
       // paths 前缀匹配预填（机械），影响类型/review 标记留 <!--TODO-->（语义）。已存在不覆盖。
@@ -1547,11 +1601,12 @@ SillySpec worktree — git worktree 隔离管理
         }
         case 'apply': {
           if (!wtName) {
-            console.error('❌ 用法: sillyspec worktree apply <change-name> [--check-only] [--base merge-base|baseline] [--merge]');
+            console.error('❌ 用法: sillyspec worktree apply <change-name> [--check-only] [--base merge-base|baseline] [--merge] [--skip-overlap]');
             process.exit(1);
           }
           const checkOnly = args.includes('--check-only');
           const merge = args.includes('--merge');
+          const skipOverlap = args.includes('--skip-overlap');
 
           // 解析 --base 参数（默认 merge-base）
           let base = 'merge-base';
@@ -1565,7 +1620,7 @@ SillySpec worktree — git worktree 隔离管理
             base = baseVal;
           }
 
-          const { applyWorktree } = await import('./worktree-apply.js');
+          const { applyWorktree, withMainRepoLock } = await import('./worktree-apply.js');
           // W3 task-09：apply 链路构造 ctx（D-013），让 task-05 applyWorktree 按 ctx 区分主仓 A5 / 跨仓 no-op。
           // 跨仓 apply=no-op（G1 D-009）：校验 review.head 是跨仓真实 commit + 跳过 wm.cleanup。
           // ctx 构造 fail-closed（约束②）——跨仓配置错时 apply 必须阻断（走错仓=数据所有权事故），不降级。
@@ -1577,7 +1632,17 @@ SillySpec worktree — git worktree 隔离管理
             console.error(`❌ apply 失败：跨仓 MultiRepoContext 构造失败（${e.message}）`);
             process.exit(1);
           }
-          const result = applyWorktree(wtName, { cwd: dir, checkOnly, merge, base, ctx: _applyCtx });
+          // 主仓 apply 互斥锁（坑 main-apply-no-mutex）：真 apply（非 checkOnly）在锁内跑——
+          // apply 链（rollback/merge/cleanup）直接改主仓工作区，两会话并发互踩会互相清文件。
+          let result;
+          try {
+            result = checkOnly
+              ? applyWorktree(wtName, { cwd: dir, checkOnly, merge, base, ctx: _applyCtx, skipOverlap })
+              : await withMainRepoLock(dir, wtName, 'apply', () => applyWorktree(wtName, { cwd: dir, checkOnly, merge, base, ctx: _applyCtx, skipOverlap }));
+          } catch (lockErr) {
+            console.error(`❌ ${lockErr.message}`);
+            process.exit(1);
+          }
 
           if (result.errors.length > 0) {
             console.error(`❌ 校验失败:`);
@@ -1685,8 +1750,15 @@ SillySpec worktree — git worktree 隔离管理
           console.log('');
           if (assessment.decision === 'SAFE' || assessment.decision === 'WARNING') {
             console.log('Action: auto-applying...');
-            const { applyWorktree } = await import('./worktree-apply.js');
-            const applyResult = applyWorktree(wtName, { cwd: dir, ctx: _assessCtx });
+            const { applyWorktree, withMainRepoLock } = await import('./worktree-apply.js');
+            // 主仓互斥锁（与手动 apply 同款）：自动 apply 同样改主仓工作区，必须互斥
+            let applyResult;
+            try {
+              applyResult = await withMainRepoLock(dir, wtName, 'assess-auto-apply', () => applyWorktree(wtName, { cwd: dir, ctx: _assessCtx }));
+            } catch (lockErr) {
+              console.error(`❌ 自动 apply 未执行：${lockErr.message}`);
+              break;
+            }
             if (applyResult.errors.length > 0) {
               console.error('❌ apply 失败:', applyResult.errors.join('; '));
             } else {
@@ -1785,7 +1857,10 @@ SillySpec worktree — git worktree 隔离管理
           }
           const forceFlag = args.includes('--force');
           try {
-            const result = wm.cleanup(wtName, { force: forceFlag });
+            // 主仓互斥锁（坑 main-repo-no-mutex 二批）：cleanup 删 worktree 注册表/分支/目录，
+            // 与并行会话的 apply/cleanup 互踩会互相清——与其他写主仓操作共用一把 main-repo.lock
+            const { withMainRepoLock } = await import('./worktree-apply.js');
+            const result = await withMainRepoLock(dir, wtName, 'worktree-cleanup', () => wm.cleanup(wtName, { force: forceFlag }));
             if (result.result === 'cleaned' || result.result === 'force-cleaned') {
               console.log(`✅ worktree 已清理: ${wtName} (mode: ${result.mode})`);
               if (result.details?.length > 0) {
@@ -1798,6 +1873,11 @@ SillySpec worktree — git worktree 隔离管理
               console.log(`   原因: in-place 模式没有隔离目录需要清理`);
             } else if (result.result === 'blocked') {
               console.error(`🚫 拒绝清理：有未落主仓交付变更，请先 sillyspec worktree apply ${wtName} 或 --force`);
+            } else if (result.result === 'partial') {
+              // 坑 ghost-dir-junction-pierce：partial 残留此前落进 else 打成「未找到」，用户误以为
+              // 干净、人工 rm -rf 穿透 junction——必须明示残留 + 安全清理指引
+              console.warn(`⚠️ 部分清理（残留：${(result.residual || []).join('; ') || 'worktree 目录'}）`);
+              console.warn(`   Windows 手动清理勿 rm -rf（穿透 node_modules junction 删主仓依赖）：先 cmd /c rmdir "<worktree>\\node_modules" 解链再删，或 sillyspec worktree doctor --fix`);
             } else {
               console.log(`ℹ️  worktree 未找到: ${wtName}`);
             }

package/src/init.js

@@ -23,6 +23,9 @@ const __dirname = dirname(__filename);
 // 详见 docs/sillyspec/runtime-cleanup-destroys-worktree-meta.md
 //
 // 策略：白名单保留权威状态，逐项删除可重建的缓存子项；未知子项默认保留（安全侧倾斜）。
+// local.yaml 同样保留：gitignored 凭据文件（平台 init lease 第 5 步下发 / local detect /
+// platform connect 写入，含用户手调 mcp 段），删除即永久丢失无法从 git 找回。本函数曾把它
+// 当非权威残留整删，与 platformMode 跳过清理的保护语义自相矛盾，2026-08-23 起不再删。
 const RUNTIME_KEEP = new Set([
   'worktrees',          // worktree 目录 + meta.json（worktree.js:17）
   'sillyspec.db',       // SQLite 进度库（权威状态源，progress.js:7）
@@ -33,15 +36,14 @@ const RUNTIME_KEEP = new Set([
 
 /**
  * 清理 .sillyspec/ 下的运行时残留，保留权威状态。
- * 同时清理 local.yaml、codebase/（这些非权威，整删安全）。
+ * 同时清理 codebase/（非权威，整删安全）。local.yaml 受保护不删——
+ * 平台 init 下发的凭据配置，见上方策略注释。
  * @param {string} legacyDir - 源码目录的 .sillyspec/ 路径
  */
 export function cleanupRuntimeResidue(legacyDir) {
-  // local.yaml、codebase/ 非权威，整删
-  for (const residue of ['local.yaml', 'codebase']) {
-    const p = join(legacyDir, residue);
-    if (existsSync(p)) { try { rmSync(p, { recursive: true, force: true }) } catch {} }
-  }
+  // codebase/ 非权威，整删；local.yaml 是凭据配置，保留
+  const codebasePath = join(legacyDir, 'codebase');
+  if (existsSync(codebasePath)) { try { rmSync(codebasePath, { recursive: true, force: true }) } catch {} }
   // .runtime/ 逐项清理，白名单保留
   const runtimeDir = join(legacyDir, '.runtime');
   if (existsSync(runtimeDir)) {
@@ -251,7 +253,7 @@ function doInstall(projectDir, tools, subprojects = [], specDir = null, options
       // 真实资产存在：拒绝整体删除，仅清理运行时残留
       console.error('❌ [sillyspec] 拒绝删除源码目录的 .sillyspec/：检测到真实资产（changes/、projects/ 或 sillyspec.db）。');
       console.error('   该项目似乎本身就用 SillySpec 管理。如需改用外部 spec 目录，请先手动迁移/备份。');
-      console.error('   本次仅清理运行时残留（.runtime/ 缓存、local.yaml、codebase/），保留 worktrees 与进度状态。');
+      console.error('   本次仅清理运行时残留（.runtime/ 缓存、codebase/），保留 local.yaml、worktrees 与进度状态。');
       cleanupRuntimeResidue(legacyDir);
     } else {
       // 无真实资产：确属旧版本残留，安全删除

package/src/knowledge-match.js

@@ -1,6 +1,10 @@
 /**
  * knowledge-match.js — knowledge 关键词匹配引擎
- * 从 INDEX.md 解析知识条目，按任务上下文匹配并生成 hit report
+ * 从 INDEX.md 解析知识条目，按任务上下文匹配并生成 hit report；
+ * 扫描范围含 decisions 决策库（knowledge/decisions/<域>.md，经 INDEX.md ## Decisions 段
+ * 路由行发现——路由行由 decision-distill 幂等写入，本引擎只消费不写）——命中路由行的
+ * 决策文件解析为 decisionHits（rejected 优先），供 brainstorm Step2 防复潮注入（task-04，FR-05）。
+ * decisions 库不存在时（INDEX 无 Decisions 段/文件不存在）一切行为与无 decisions 库时一致。
  */
 
 import { existsSync, readFileSync } from 'fs'
@@ -41,6 +45,86 @@ export function parseKnowledgeIndex(indexDir) {
   return entries
 }
 
+// ---------------------------------------------------------------------------
+// decisions 决策库扫描（task-04，FR-05）：经 INDEX.md ## Decisions 段路由行发现
+// knowledge/decisions/<域>.md 并解析 D-xxx@vN 条目。条目格式与 decision-distill 的
+// renderBlockLines 逐字对齐（字段行是机械解析契约）：`## D-xxx@vN <短标题>` +
+// `状态：implemented|rejected` / `锚点：` / `最近确认：` / `理由：`（rejected 追加
+// `否决理由：` / `复潮条件：`）。
+// ---------------------------------------------------------------------------
+
+/** INDEX 条目是否为 decisions 库路由行（目标文件在 decisions/ 下） */
+function isDecisionRoute(entry) {
+  return /^decisions\//.test(String(entry.file || '').replace(/\\/g, '/'))
+}
+
+const DECISION_HEADER_RE = /^##\s+(D-\d+@v\d+)\s*(.*)$/
+const DECISION_FIELD_RE = /^(状态|理由|否决理由|复潮条件)\s*[：:]\s*(.*)$/
+
+/**
+ * 解析单个 decisions/<域>.md 的 D-xxx@vN 条目。
+ * reason 语义：rejected 条目取「否决理由」（expects_from task-02 的 reject_reason），
+ * 其余条目回退「理由」一句话；revisitWhen 仅 rejected 条目非空（复潮条件）。
+ * @param {string} filePath 决策文件绝对路径
+ * @param {string} file INDEX 相对路径（decisions/<域>.md），原样进 decisionHits.file
+ * @returns {{ file: string, id: string, title: string, status: string, reason: string, revisitWhen: string }[]}
+ */
+function parseDecisionFile(filePath, file) {
+  let content
+  try { content = readFileSync(filePath, 'utf8') } catch { return [] }
+  const hits = []
+  let cur = null
+  const flush = () => {
+    if (cur) hits.push(cur)
+    cur = null
+  }
+  for (const line of content.replace(/\r\n/g, '\n').split('\n')) {
+    const h = line.match(DECISION_HEADER_RE)
+    if (h) {
+      flush()
+      cur = { file, id: h[1], title: h[2].trim(), status: '', reason: '', revisitWhen: '' }
+      continue
+    }
+    if (!cur) continue
+    const f = line.match(DECISION_FIELD_RE)
+    if (!f) continue
+    const value = f[2].trim()
+    if (f[1] === '状态') cur.status = value.toLowerCase()
+    else if (f[1] === '否决理由') cur.reason = value
+    else if (f[1] === '复潮条件') cur.revisitWhen = value
+    else if (!cur.reason) cur.reason = value // 理由：仅作 implemented（或否决理由缺失）时的回填
+  }
+  flush()
+  return hits
+}
+
+/**
+ * 解析 knowledge/decisions/ 决策库——扫描范围扩到 decisions/*.md，但只经 INDEX.md
+ * Decisions 段路由行发现目标文件（路由行由 decision-distill 幂等维护）。
+ * @param {string} indexDir knowledge 目录路径
+ * @param {Array} [indexEntries] parseKnowledgeIndex 输出（缺省时自行解析 INDEX；传入时
+ *   只解析这些条目中指向 decisions/ 的路由行，matchKnowledge 用它做「路由行已命中」过滤）
+ * @returns {{ file: string, id: string, title: string, status: string, reason: string, revisitWhen: string }[]}
+ *   路由行不存在/目标文件不存在/解析失败 → []（与无 decisions 库时行为完全一致）
+ */
+export function parseDecisionEntries(indexDir, indexEntries = null) {
+  const routes = (indexEntries || parseKnowledgeIndex(indexDir)).filter(isDecisionRoute)
+  const hits = []
+  for (const route of routes) {
+    const filePath = join(indexDir, route.file)
+    if (!existsSync(filePath)) continue // 路由行失效（域文件已删）→ 跳过不阻断
+    hits.push(...parseDecisionFile(filePath, route.file))
+  }
+  // 多条路由行指向同一域文件时按 file+id 去重
+  const seen = new Set()
+  return hits.filter(h => {
+    const key = `${h.file}#${h.id}`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+}
+
 function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
@@ -62,7 +146,11 @@ function keywordMatchesContext(keyword, contextLower) {
  * 用任务上下文匹配知识条目
  * @param {string} indexDir - knowledge 目录路径
  * @param {string} taskContext - 任务上下文（task 名称 + 描述，用于关键词匹配）
- * @returns {{ matched: boolean, entries: Array, report: string, json: object }}
+ * @returns {{ matched: boolean, entries: Array, report: string, json: object,
+ *   decisionHits: Array<{ file: string, id: string, title: string, status: string, reason: string, revisitWhen: string }> }}
+ *   matched/entries/report/json 既有四字段结构与语义不变；decisionHits（task-04 新增）= 任务上下文
+ *   命中的 Decisions 路由行所指向 decisions/<域>.md 内的全部 D-xxx@vN 条目，rejected 优先排序；
+ *   无 decisions 库 / 路由行未命中 → decisionHits: []（其余字段行为与现状一致）。
  */
 export function matchKnowledge(indexDir, taskContext) {
   const indexPath = join(indexDir, 'INDEX.md')
@@ -73,7 +161,8 @@ export function matchKnowledge(indexDir, taskContext) {
       matched: false,
       entries: [],
       report: 'Status: no matches (INDEX.md not found)',
-      json: { matched: false, entry_count: 0, entries: [] }
+      json: { matched: false, entry_count: 0, entries: [] },
+      decisionHits: []
     }
   }
 
@@ -83,7 +172,8 @@ export function matchKnowledge(indexDir, taskContext) {
       matched: false,
       entries: [],
       report: 'Status: no matches',
-      json: { matched: false, entry_count: 0, entries: [] }
+      json: { matched: false, entry_count: 0, entries: [] },
+      decisionHits: []
     }
   }
 
@@ -97,7 +187,8 @@ export function matchKnowledge(indexDir, taskContext) {
       matched: false,
       entries: [],
       report: 'Status: no matches',
-      json: { matched: false, entry_count: 0, entries: [] }
+      json: { matched: false, entry_count: 0, entries: [] },
+      decisionHits: []
     }
   }
 
@@ -126,5 +217,15 @@ export function matchKnowledge(indexDir, taskContext) {
     }))
   }
 
-  return { matched: true, entries: matched, report, json }
+  // decisionHits（task-04）：任务上下文命中的 Decisions 路由行 → 解析其指向的
+  // decisions/<域>.md 内全部条目；rejected 优先排序（防复潮信息最先可见，组内保持文件序）。
+  // 不引入新顶层 hits 字段，不改 matched/entries/report/json 四个既有键。
+  const decisionRoutes = matched.filter(isDecisionRoute)
+  const allDecisionHits = decisionRoutes.length > 0 ? parseDecisionEntries(indexDir, decisionRoutes) : []
+  const decisionHits = [
+    ...allDecisionHits.filter(h => h.status === 'rejected'),
+    ...allDecisionHits.filter(h => h.status !== 'rejected')
+  ]
+
+  return { matched: true, entries: matched, report, json, decisionHits }
 }

package/src/local-register.js

@@ -44,7 +44,9 @@ export function registerRepoInLocalYaml(yamlPath, key, 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 raw0 = existed ? readFileSync(yamlPath, 'utf8') : ''
+  const hadCr = raw0.includes('\r') // 磁盘原文带 CRLF → 幂等路径也要落盘治愈（见下方幂等分支）
+  const raw = existed ? raw0.replace(/\r\n?/g, '\n') : ''
   const posixPath = String(repoPath).replace(/\\/g, '/')
   const entryLine = `  ${key}: ${posixPath}`
 
@@ -79,6 +81,10 @@ export function registerRepoInLocalYaml(yamlPath, key, repoPath) {
   for (let i = reposIdx + 1; i < end; i++) {
     if (keyRe.test(lines[i])) {
       if (lines[i] === entryLine) {
+        // 坑 register-repo-crlf-idempotent-loop：磁盘原文带 CRLF 时（agent Write 工具/Windows
+        // 编辑器写入），内存归一后比对相等直接跳过 → 磁盘永不治愈 + CLI 报 ✅ 假成功 → 解析侧
+        // （修复前）空 Map → MultiRepoContext 报「未注册」→ 死循环。幂等路径也落盘一次治愈。
+        if (hadCr) write(lines.join('\n'))
         return { fileCreated: false, sectionCreated: false, replaced: false } // 值未变，幂等跳过
       }
       lines[i] = entryLine

package/src/module-resolve.js

@@ -20,6 +20,11 @@
  *   - 判定语义（哪个模块才是「对的」）仍归 agent——本表只是机械最优匹配
  */
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
+
+/** 模块卡字数预算（字节）：超限在 resolve 表标 ⚠️ 并提示精简——文档是 agent 的读取税
+ * （对标 deepseek-harness verify-doc-budgets 理念：预算只降不升；2026-08-24 起 runtime.md
+ * 28KB/worktree.md 24KB 已在付税）。advisory 不阻断，16 为 dogfood 校准前缺省。 */
+const MODULE_CARD_BUDGET_BYTES = 16 * 1024
 import { join, relative } from 'path'
 import { parseModuleMapSimple } from './modules.js'
 import { parseTaskRegistry } from './stages/execute.js'
@@ -197,9 +202,12 @@ export function renderModuleResolveTable({ cwd, specBase, changeName }) {
     '| task | 模块 | 粒度 | 模块卡（只读命中的卡，勿按目录整读） | 体量 | 读取建议 |',
     '|---|---|---|---|---|---|',
   ]
+  const budgetBreached = new Set()
   for (const r of rows) {
     if (r.moduleId) {
-      L.push(`| ${r.taskId} | ${r.moduleId} | ${r.granularity === 'fine' ? '细' : '粗'} | \`${r.cardPath}\` | ${kb(r.cardBytes)} | ${r.advice} |`)
+      const over = r.cardBytes > MODULE_CARD_BUDGET_BYTES
+      if (over) budgetBreached.add(r.moduleId)
+      L.push(`| ${r.taskId} | ${r.moduleId} | ${r.granularity === 'fine' ? '细' : '粗'} | \`${r.cardPath}\` | ${kb(r.cardBytes)}${over ? ' ⚠️超预算' : ''} | ${r.advice} |`)
     } else {
       L.push(`| ${r.taskId} | — | — | （无命中，跳过模块文档） | — | — |`)
     }
@@ -207,5 +215,8 @@ export function renderModuleResolveTable({ cwd, specBase, changeName }) {
   L.push('')
   L.push('> 匹配规则：全部 _module-map.yaml 跨层最长前缀（子项目细卡优先于根层大卡），源=tasks 卡 allowed_paths。')
   L.push('> 细卡整卡可读；仅粗卡命中且体量大时**按节读**——只读「契约摘要/注意事项/定位」，跳过「变更索引/人工备注」历史累积段。')
+  if (budgetBreached.size > 0) {
+    L.push(`> ⚠️ 模块卡超预算（>${Math.round(MODULE_CARD_BUDGET_BYTES / 1024)}KB）：${[...budgetBreached].join('、')}——文档是 agent 的读取税，本次变更触及该模块，收尾时顺手 \`sillyspec modules split-changelog\` 迁出历史段或精简正文（对标 deepseek-harness verify-doc-budgets：预算只降不升）。`)
+  }
   return L.join('\n')
 }

package/src/modules.js

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { gitQuiet } from './git-helper.js';
+import { nowWallClock } from './datetime.js';
 
 
 /**
@@ -112,7 +113,7 @@ export async function rebuildModuleMap(cwd, { force = false } = {}) {
 
   // 生成新的 _module-map.yaml
   // 保留已有的完整字段，补齐新卡片
-  const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+  const now = nowWallClock();
   let headCommit = '';
   try {
     // QUAL-01 收口：走 git-helper 统一入口（safe.directory + 数组形式）

package/src/plan-adopt-waves.js

@@ -0,0 +1,126 @@
+/**
+ * plan-adopt-waves.js — `sillyspec plan-adopt-waves` 把 plan.md 的 Wave 段一键重排为
+ * depends_on 拓扑分组（坑 wave-manual-mismatch-noise，2026-08-24 用户反馈二期：主控手排
+ * Wave 与 CLI 拓扑比对不一致只能手动改；依赖方向违规修复后，本命令给一条零手写出路）。
+ *
+ * 行为：
+ *   - depMap（tasks/*.md 的 depends_on，collectTaskDepMap 与 postcheck 同源）→ topoSortWaves
+ *   - 重写 plan.md 的 `## Wave N` 段块（段内按编号排序；首段「并行，无依赖」、其余「依赖前序 Wave」）
+ *   - 无显式 Wave 标题 → 插在「## 任务总表」前（无总表则文末追加）
+ *   - best-effort 同步任务总表的 W 列（仅认 7 列模板行；不匹配的行 warn 不强改）
+ *   - Wave 段内若含非引用内容（正文/表格）→ 拒绝重写（防误删），提示先手动整理
+ *   - 写后复跑 validateBlueprintConsistency 打印结果（防 adopt 把手工安全串行收敛出
+ *     同 Wave 共享路径冲突——topo 只看依赖不看文件重叠）
+ *   - --dry-run 只打印将写入的 Wave 段不落盘；幂等（重复跑产出相同结构）；行尾统一 LF
+ */
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { topoSortWaves, collectTaskDepMap, validateBlueprintConsistency } from './stages/plan-postcheck.js'
+
+const WAVE_HEADING_RE = /^#+\s*Wave\s+\d+/i
+const TASK_REF_RE = /^[-*]\s+(?:\[[ x]\]\s*)?task-\d+\s*[:：\s]*$/i
+const LEGACY_TASK_REF_RE = /^[-*]\s*\[[ x]\]\s*task-\d+/i
+const SUMMARY_HEADING_RE = /^#+\s*任务总表/
+
+/** 渲染标准 Wave 段块（段落间空行分隔，结尾不带多余空行——由调用方控制拼接） */
+function renderWaveBlock(waves) {
+  const L = []
+  waves.forEach((wave, i) => {
+    const sorted = [...wave].sort((a, b) =>
+      parseInt(String(a).replace(/\D/g, ''), 10) - parseInt(String(b).replace(/\D/g, ''), 10))
+    L.push(`## Wave ${i + 1}（${i === 0 ? '并行，无依赖' : '依赖前序 Wave'}）`)
+    for (const t of sorted) L.push(`- ${t}`)
+    if (i < waves.length - 1) L.push('')
+  })
+  return L
+}
+
+/** best-effort 更新任务总表 W 列：仅认 `| task-XX | … | W1 | … |` 形态的 7+ 列模板行 */
+function updateSummaryWaveColumn(lines, waveOf) {
+  let inSummary = false
+  let updated = 0
+  let skipped = 0
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (/^#+\s/.test(line)) { inSummary = SUMMARY_HEADING_RE.test(line); continue }
+    if (!inSummary) continue
+    const m = line.match(/^\|\s*task-(\d+)\s*\|/)
+    if (!m) continue
+    const cells = line.split('|')
+    // 模板 7 列：| 编号 | 任务 | Wave | 优先级 | 依赖 | 覆盖 FR/D | 说明 | → split 后首尾空串
+    if (cells.length < 8 || !/^\s*W\d+\s*$/.test(cells[3] || '')) { skipped++; continue }
+    const taskId = `task-${String(m[1]).padStart(2, '0')}`
+    const waveIdx = waveOf.get(taskId)
+    if (waveIdx === undefined) { skipped++; continue }
+    cells[3] = ` W${waveIdx + 1} `
+    lines[i] = cells.join('|')
+    updated++
+  }
+  return { updated, skipped }
+}
+
+/**
+ * @param {{ changeDir: string, dryRun?: boolean }} opts
+ * @returns {{ ok: boolean, error?: string, waves?: string[][], planPath: string, dryRun: boolean,
+ *             waveBlock?: string[], tableRowsUpdated?: number, tableRowsSkipped?: number,
+ *             postcheck?: { errors: string[], warnings: string[] } }}
+ */
+export function adoptPlanWaves({ changeDir, dryRun = false }) {
+  const planPath = join(changeDir, 'plan.md')
+  if (!existsSync(planPath)) return { ok: false, error: `plan.md 不存在: ${planPath}`, planPath, dryRun }
+  const tasksDir = join(changeDir, 'tasks')
+  if (!existsSync(tasksDir)) return { ok: false, error: `tasks/ 目录不存在: ${tasksDir}`, planPath, dryRun }
+  const depMap = collectTaskDepMap(tasksDir)
+  if (depMap.size === 0) return { ok: false, error: 'tasks/ 下没有 task-NN.md 卡片，无从推导 Wave 分组', planPath, dryRun }
+
+  const { waves, error: topoError } = topoSortWaves(depMap)
+  if (topoError) return { ok: false, error: `拓扑排序失败: ${topoError}`, planPath, dryRun }
+
+  const original = readFileSync(planPath, 'utf8')
+  const lines = original.split(/\r?\n/)
+  const waveBlock = renderWaveBlock(waves)
+  const waveOf = new Map()
+  waves.forEach((ws, i) => { for (const t of ws) waveOf.set(t, i) })
+
+  const firstWaveIdx = lines.findIndex(l => WAVE_HEADING_RE.test(l))
+  if (firstWaveIdx >= 0) {
+    // Wave 段块末尾 = 最后一个 Wave 标题之后连续的任务引用行（空行容忍但不断段；
+    // 遇非 Wave 标题即止）。段内混入非引用内容 → 拒绝重写（防误删正文/表格）。
+    let endIdx = firstWaveIdx
+    for (let i = firstWaveIdx; i < lines.length; i++) {
+      if (WAVE_HEADING_RE.test(lines[i])) { endIdx = i; continue }
+      if (TASK_REF_RE.test(lines[i]) || LEGACY_TASK_REF_RE.test(lines[i])) { endIdx = i; continue }
+      if (lines[i].trim() === '') continue
+      if (/^#+\s/.test(lines[i])) break
+      return { ok: false, error: `Wave 段内含非引用内容（第 ${i + 1} 行「${lines[i].slice(0, 40)}」）——为防误删拒绝重写，请先把 Wave 段整理为纯 "- task-XX" 引用行`, planPath, dryRun }
+    }
+    lines.splice(firstWaveIdx, endIdx - firstWaveIdx + 1, ...waveBlock)
+  } else {
+    // 无显式 Wave 标题：插在「## 任务总表」前；无总表则文末追加
+    const summaryIdx = lines.findIndex(l => SUMMARY_HEADING_RE.test(l))
+    if (summaryIdx >= 0) {
+      lines.splice(summaryIdx, 0, ...waveBlock, '')
+    } else {
+      while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop()
+      lines.push('', ...waveBlock)
+    }
+  }
+
+  const { updated, skipped } = updateSummaryWaveColumn(lines, waveOf)
+  const content = lines.join('\n').replace(/\n*$/, '\n')
+
+  if (dryRun) {
+    return { ok: true, waves, planPath, dryRun: true, waveBlock, tableRowsUpdated: updated, tableRowsSkipped: skipped }
+  }
+
+  writeFileSync(planPath, content, 'utf8')
+  // 复跑 blueprint 一致性（advisory 打印）：topo 只看依赖不看文件重叠——adopt 可能把手工
+  // 安全串行收敛出同 Wave 共享路径冲突，立即暴露而非留到 execute 撞
+  let postcheck = null
+  try {
+    postcheck = validateBlueprintConsistency(changeDir)
+  } catch (e) {
+    postcheck = { errors: [`复跑校验异常: ${e?.message || e}`], warnings: [] }
+  }
+  return { ok: true, waves, planPath, dryRun: false, waveBlock, tableRowsUpdated: updated, tableRowsSkipped: skipped, postcheck }
+}