sillyspec 3.27.5 → 3.27.7

package/src/stage-contract.js

@@ -545,8 +545,11 @@ function validateVerifyOutputs(cwd, changeName, context = {}) {
         let receiptText = ''
         try {
           // 回执按变更分片（坑 verify-pids-cross-session-kill：原单份被并行会话后写覆盖），
-          // 优先读本变更分片，兼容旧单份名（升级过渡期 receipt.change 过滤仍生效）
-          const runtimeDir = join(cwd, '.sillyspec', '.runtime')
+          // 优先读本变更分片，兼容旧单份名（升级过渡期 receipt.change 过滤仍生效）。
+          // runtimeDir 与写入方 reapVerifyServices 同源解析（context.runtimeRoot > specRoot/.runtime
+          // > cwd/.sillyspec/.runtime）——平台/漂移模式下 cwd/.sillyspec 恒读不到回执
+          const runtimeDir = context.runtimeRoot
+            || join(context.specRoot || join(cwd, '.sillyspec'), '.runtime')
           const receiptPath = existsSync(join(runtimeDir, `verify-services-${changeName}.receipt.json`))
             ? join(runtimeDir, `verify-services-${changeName}.receipt.json`)
             : join(runtimeDir, 'verify-services.receipt.json')
@@ -602,9 +605,14 @@ export function archiveDestDirName(date, changeName) {
 
 /**
  * archive 完成校验：检查归档目录完整性
+ *
+ * context.specRoot（A4 同族）：平台模式下归档目录在 specRoot/changes/archive（gates.js /
+ * machine-interface.js 调 runValidators 已透传 specRoot: platformOpts?.specRoot），此前硬编码
+ * cwd/.sillyspec 平台模式恒报「归档目录缺失」。
  */
-function validateArchiveOutputs(cwd, changeName) {
-  const archiveDir = join(cwd, '.sillyspec', 'changes', 'archive')
+function validateArchiveOutputs(cwd, changeName, context = {}) {
+  const specBase = context.specRoot || join(cwd, '.sillyspec')
+  const archiveDir = join(specBase, 'changes', 'archive')
   const destDir = join(archiveDir, changeName)
 
   // 归档目录不存在 early return(引擎在存在时才跑)
@@ -620,14 +628,14 @@ function validateArchiveOutputs(cwd, changeName) {
 /**
  * archive 前置校验：所有主流程阶段完成
  */
-function validateChangeClosed(cwd, changeName) {
+function validateChangeClosed(cwd, changeName, context = {}) {
   const errors = []
   const warnings = []
 
-  // 检查前置阶段状态
-  const progressDir = join(cwd, '.sillyspec', '.runtime')
+  // context.specRoot：平台模式下变更目录在 specRoot/changes（同 validateArchiveOutputs）
+  const specBase = context.specRoot || join(cwd, '.sillyspec')
   // 这里只做文件层面的检查，DB 检查在 run.js 里做
-  const changeDir = join(cwd, '.sillyspec', 'changes', changeName)
+  const changeDir = join(specBase, 'changes', changeName)
   if (!existsSync(changeDir)) {
     errors.push(`变更目录不存在: ${changeDir}`)
     return { ok: false, errors, warnings }

package/src/stages/brainstorm-auto.js

@@ -149,7 +149,49 @@ AC-011: 不涉及业务规则/产品范围/默认行为/用户可见行为变更
 ### 产物文件
 
 #### design.md（必填，写入变更根目录 \`design.md\`）
-包含：背景、设计目标、非目标、总体方案、文件变更清单、接口定义、数据模型（如涉及）、兼容策略（brownfield）、风险登记、决策追踪。
+包含：背景、设计目标、非目标、总体方案、文件变更清单、接口定义、数据模型（如涉及）、兼容策略（brownfield）、风险登记、决策追踪、自审。
+**章节骨架必须按下述字面格式写**（校验器按字面短语匹配，措辞偏离会连环卡门——坑 literal-template-trap，2026-08-24 用户反馈五期②）：
+\`\`\`markdown
+# 设计文档（Design）— <变更简述>
+
+## 背景
+<为什么做、解决什么问题>
+
+## 设计目标
+<要达成什么>
+
+## 非目标
+<明确不做的事——标题必须字面含「非目标」（Non-Goals 也认，但大小写须完全一致）>
+
+## 总体方案
+<技术方案>
+
+## 文件变更清单
+| 操作 | 文件路径 | 说明 |
+|---|---|---|
+| 新增 | src/xxx/NewFile.ts | ... |
+| 修改 | src/xxx/ExistingFile.ts | ... |
+
+## 生命周期契约表
+<仅当涉及 session/lease/agent_run/daemon/lifecycle/state_transition/claim/heartbeat 关键词时必填；
+若不涉及，删掉本节或在正文写紧邻豁免短语：「不涉及生命周期契约」或「生命周期契约：无/N/A」
+——「无需 lifecycle 事件」这类宽写法不被识别（否定词必须紧邻「生命周期契约/lifecycle contract」）>
+
+| 事件 | 发起方 | 接收方 | 必需字段 | 状态变化 |
+|---|---|---|---|---|
+| <事件名> | <发起方> | <接收方> | <字段清单> | <初始态 → 终态> |
+
+## 风险登记
+| 编号 | 风险 | 等级 | 应对策略 |
+|---|---|---|---|
+| R-01 | ... | P0/P1/P2 | ... |
+
+## 决策追踪
+<列出 D-xxx@vN 决策 ID 及覆盖关系；无决策可写「无」>
+
+## 自审
+<对自身设计的校验——标题必须字面含「自审」或「Self-Review」（自我审查等宽写法不识别）>
+\`\`\`
 
 #### decisions.md（必填，写入变更根目录 \`decisions.md\`）
 记录所有决策：

package/src/stages/brainstorm.js

@@ -162,11 +162,15 @@ export const definition = {
 5. **场景压力测试**：用具体 case 逼出边界（失败重试、部分成功、历史数据、权限不足、并发修改、兼容旧配置）
 6. **前提挑战优先**：如果现有设计或代码已有简单路径，先说明"可能不该新增"
 
-**决策记录草稿**：每解决一个有实现影响的问题，生成一个稳定 ID 的记录草稿（不要把闲聊都记录进去）：
+**决策记录（增量落盘，防会话中断丢失）**：每解决一个有实现影响的问题（不要把闲聊都记录进去），**当场追加**写入 \`{SPEC_ROOT}/changes/<change-name>/decisions.md\`——不要只在对话里留草稿等「写设计文档」步统一落盘：会话随时可能中断，未落盘的决策无法跨会话恢复。落盘规则：
+
+- 文件不存在则先创建：变更目录缺失先 \`mkdir -p {SPEC_ROOT}/changes/<change-name>\`；文件头部写 YAML frontmatter（\`author: <git-user>\` / \`created_at: <now-datetime>\`）+ 标题 \`# 决策记录（Decisions）\`
+- 每条记录追加到文件末尾，格式如下：
 
 \`\`\`markdown
 ## D-001@v1: <短标题>
 - type: term | boundary | premise | architecture | compatibility | risk
+- priority: P0 | P1 | P2
 - status: accepted | rejected | superseded
 - source: user | code | docs
 - question: <被解决的问题>
@@ -176,6 +180,8 @@ export const definition = {
 - evidence: <文件路径/代码位置/用户回答轮次>
 \`\`\`
 
+- 幂等：写入前按 D-xxx@vN 查重，已存在的不重复追加；后续修正走新版本 D-001@v2 + supersedes（见 Design Grill 版本规则）
+
 ### 铁律 — 不要自问自答 / 等待用户
 - 这是人机协作步骤：提出问题后必须暂停等用户回答，**不要在输出里模拟用户回答然后说"需求已明确"**（命令由 CLI 在下方注入）
 - 需要拆分或批量模式时：列出方案并暂停等用户确认
@@ -183,12 +189,12 @@ export const definition = {
 - 2-3 轮问答即进入方案讨论；达到 maxWaitRounds=8 后必须总结已确认内容与剩余风险，不要无限追问
 
 ### 输出
-需求理解摘要（用户确认的需求点列表）+ 拆分/批量结论（如适用）+ D-xxx@vN 决策记录草稿 + 剩余风险（如有）
+需求理解摘要（用户确认的需求点列表）+ 拆分/批量结论（如适用）+ 本步新增落盘的 D-xxx@vN 清单 + 剩余风险（如有）
 
 ### 注意
 - 第一次进入此步骤时，按 A→D 顺序处理；有原型先分析，再探索，再判规模，再澄清
-- 用户通过 \`--continue --answer "回答"\` 回答后，本步骤会再次执行，此时检查是否需要追问或可以结束`,
-      outputHint: '需求理解与决策记录草稿',
+- 用户通过 \`--continue --answer "回答"\` 回答后，本步骤会再次执行，此时检查是否需要追问或可以结束；再次执行时输出只需增量汇报（新结论 + 新落盘决策），已落盘内容不要重复输出`,
+      outputHint: '需求理解与决策落盘清单',
       optional: false
     },
     {
@@ -202,6 +208,7 @@ export const definition = {
 1. 每种方案列出：核心思路、优势、劣势
 2. 如果上一步产生了 D-xxx@vN 决策记录，方案必须说明覆盖/违反哪些当前版本决策
 3. 给出推荐方案和理由
+4. 用户选定方案后，把选择结果**当场追加**到 \`{SPEC_ROOT}/changes/<change-name>/decisions.md\`（增量落盘规则同「对话式探索」步：目录/文件缺失先创建、按 D-xxx@vN 判重）：type 用 architecture、source 用 user、question 记方案取舍问题、answer 记用户所选方案与理由要点、evidence 记方案选择轮次——方案选择是本变更最关键的用户决策，必须随答随落盘，不能只留在对话里
 
 ### 铁律 — 必须等待用户选择方案
 - 列出方案对比表和推荐后必须暂停等用户选择，**不要自己说"推荐方案 A"然后当用户选了**（命令由 CLI 在下方注入）
@@ -287,9 +294,15 @@ design.md 第一行标题必须用中文：# 设计文档（Design）— <变更
 | 删除 | src/xxx/OldFile.java | 已被 xx 替代 |
 
    **字段数据流标注**（避免新增字段到 execute 才发现没透传）：当清单含「新增/修改对外字段、接口、DTO、响应体、事件 payload、配置键」时，对应行「说明」列必须交代 producer→consumer 数据流——产出方（producer）→ 每跳流转/归一化点（序列化/反序列化/字段映射/默认值兜底）→ 消费方（consumer）。漏标 = 字段在某跳 dormant（声明了却没透传），到 execute/verify 才暴露，属设计层缺口。
-   - 示例：「修改 daemon.ts：新增 budget_tokens，producer=backend/api-types.ts → ws_hub envelope 透传 → daemon.ts normalizeUsage 归一化（snake→camel）→ consumer=runtime/lease.ts 写 lease」
+   - 示例：「修改 daemon.ts：新增 budget_tokens，producer=backend/api-types.ts → ws_hub envelope 透传 → daemon.ts normalizeUsage（snake→camel）→ consumer=runtime/lease.ts 写 lease」
    - 仅改内部实现、无对外字段变动时，说明列照常写「新增 xx 方法」即可，无需数据流。
 
+   **跨仓变更写法**（本次变更涉及 local.yaml repos: 注册的其他仓时必读；纯主仓变更跳过）：
+   - 清单**按仓分段**：每个仓一个小节，标题格式固定 \`## <repo-key> 仓变更\`（如 \`## sub-grid-security 仓变更\`）。plan-postcheck 文件覆盖对账按此段头解析仓归属，写成「前端仓 / backend」等其他标题 → 对账不上
+   - 段内路径相对**该仓根**写（\`src/routes/x.js\`）；❌ 禁止带仓库名前缀（\`sub-grid-security/src/routes/x.js\`）、❌ 禁止绝对路径/盘符路径（\`C:/repo/src/...\`）——后续 TaskCard 的 allowed_paths 与 review 对账（\`git -C <仓根> diff\` 产仓根相对路径）都用同一口径，前缀/绝对路径永不命中
+   - 主仓文件放在第一个段头之前（无段头区域 = main），或单独写 \`## main 仓变更\` 段
+   - repo-key 必须是 local.yaml repos: 段已注册的键（未注册先跑 \`sillyspec local register-repo <key> <仓根路径>\`，main 隐式不用注册）
+
 7. **接口定义**：方法签名、数据结构（代码类任务必填）
 7.5. **生命周期契约表**（涉及以下关键词时必填，否则可省略）：
 
@@ -308,6 +321,8 @@ design.md 第一行标题必须用中文：# 设计文档（Design）— <变更
 
    判断规则：
    - design.md 或需求中出现上述关键词 → 必须生成此表
+   - 确实不涉及 → 写**紧邻豁免短语**（照抄其一）：「不涉及生命周期契约」「不适用 lifecycle contract」「生命周期契约：无/N/A」
+     ——「本变更无需 lifecycle 事件」「lifecycle 状态无变化」这类宽写法**不被识别**（否定词必须紧邻「生命周期契约/lifecycle contract」）
    - 表中的每个事件 → 必须有对应代码任务、接口任务、测试任务
    - 表中的必需字段 → 必须出现在相关 DTO/interface 定义中
    - 缺少任一事件 → 在 design.md 风险登记中明确记录
@@ -334,10 +349,11 @@ design.md 第一行标题必须用中文：# 设计文档（Design）— <变更
 1. 确认变更目录存在：\`mkdir -p {SPEC_ROOT}/changes/<change-name>\`（Windows 用 \`mkdir {SPEC_ROOT}/changes\\<变更名>\` 或 PowerShell \`New-Item -ItemType Directory -Force -Path {SPEC_ROOT}/changes/<change-name>\`）
    - 变更名格式必须为 \`YYYY-MM-DD-<简短描述>\`（如 \`2026-05-13-user-auth\`）
 2. 将确认的设计写入 \`{SPEC_ROOT}/changes/<change-name>/design.md\`
-3. 如果对话探索或方案讨论产生了实现相关决策，写入 \`{SPEC_ROOT}/changes/<change-name>/decisions.md\`：
+3. 对账整理 \`{SPEC_ROOT}/changes/<change-name>/decisions.md\`（「对话式探索」「提出方案」步已按增量规则随答落盘，本步做对账而非从零写入）：
    - decisions.md 是本次变更的决策台账，不是长期术语表
    - 只记录有实现/验收影响的决策，闲聊和低风险偏好不记录
-   - 每条记录必须有稳定版本 ID：D-001@v1、D-002@v1 ...
+   - 已落盘条目按 D-xxx@vN 判重，不重复追加；补全缺失的九字段与可选字段
+   - 前序遗漏未落盘、确有实现影响的决策（增量规则漏网的），此时补写；每条记录必须有稳定版本 ID：D-001@v1、D-002@v1 ...
    - 若后续 Design Grill 修正该决策，新记录使用 D-001@v2，并写明 supersedes: D-001@v1
    - 每条记录必须包含：type、status、source、question、answer、normalized_requirement、impacts、evidence、priority
    - 九字段之外可另加四个可选字段，按需填写、不强制全填（旧格式决策记录缺这些字段不受影响）：
@@ -570,7 +586,7 @@ created_at: <now-datetime>
 \`\`\`
 > 骨架只列任务名。plan 阶段会把展开后的清单**写回本文件**（checkbox 行带一句话名，可附 [model:xxx]/(depends_on: …) 标注；保留 frontmatter/标题/ql-xxx 等非 task-XX 行）；execute 勾选与 verify 对照都在本文件。
 
-### decisions.md 格式要求（仅在有 Grill/重大决策时生成）
+### decisions.md 格式要求（前序步骤已增量创建时对账即可；无决策的变更不生成）
 \`\`\`markdown
 ---
 author: <git-user>

package/src/stages/execute.js

@@ -717,6 +717,8 @@ export async function stampCrossRepoHeadCommits({ changeName, cwd, specBase, pla
   }
   let stamped = 0
   let skipped = 0
+  // 同仓多 task 只 spawn 一次 rev-parse（Windows 单次 spawn 30-100ms，N task × 同仓纯浪费）
+  const headCache = new Map()
   for (const f of readdirSync(tasksDir).filter(n => /^task-\d+\.md$/.test(n)).sort()) {
     const taskFile = path.join(tasksDir, f)
     let content
@@ -735,7 +737,8 @@ export async function stampCrossRepoHeadCommits({ changeName, cwd, specBase, pla
       reasons.push(`${f}: repo "${repoKey}" 无法解析 gitDir（local.yaml repos 未注册？）`)
       continue
     }
-    const head = gitQuiet(entry.gitDir, ['rev-parse', 'HEAD'])
+    if (!headCache.has(entry.gitDir)) headCache.set(entry.gitDir, gitQuiet(entry.gitDir, ['rev-parse', 'HEAD']))
+    const head = headCache.get(entry.gitDir)
     if (!head) {
       skipped++
       reasons.push(`${f}: git rev-parse HEAD 失败（${entry.gitDir}）`)
@@ -760,6 +763,22 @@ export async function stampCrossRepoHeadCommits({ changeName, cwd, specBase, pla
  */
 export function buildWavePrompt(wave, waveIndex, changeDir, worktreePath, options = {}) {
   const ctx = options.ctx || null
+  // 跨 Wave 共享缓存（性能收敛 O(W×T) → O(T)）：一次 buildExecuteSteps 期间 plan/契约矩阵/
+  // task 卡/模块卡表/design 行集不变，每 Wave 重读重解析是纯浪费（6-8 Wave × 15 task 的
+  // full 级变更 = 数百次冗余 fs + 契约矩阵全卡重扫）。缓存对象由 buildExecuteSteps 创建传入；
+  // 直接调用（tests / 单 Wave）不传 _execCache 时全部退化为即时计算，行为不变
+  const cache = options._execCache || null
+  const memo = (slot, compute) => {
+    if (!cache) return compute()
+    if (!(slot in cache)) cache[slot] = compute()
+    return cache[slot]
+  }
+  const memoMap = (slot, key, compute) => {
+    if (!cache) return compute()
+    if (!cache[slot]) cache[slot] = new Map()
+    if (!cache[slot].has(key)) cache[slot].set(key, compute())
+    return cache[slot].get(key)
+  }
   // ── Contract Matrix：检查是否有 provider/consumer 契约需要注入 ──
   let contractInjection = ''
   let prototypeInjection = ''
@@ -767,7 +786,7 @@ export function buildWavePrompt(wave, waveIndex, changeDir, worktreePath, option
     try {
       const planFile = path.join(changeDir, 'plan.md')
       if (existsSync(planFile)) {
-        const planContent = readFileSync(planFile, 'utf8')
+        const planContent = memo('plan', () => readFileSync(planFile, 'utf8'))
         // 收集本 wave 所有 task（端点注入与字段注入共用）
         const waveTasks = wave.tasks.map((t, ti) => {
           const num = String(t.index || (ti + 1)).padStart(2, '0')
@@ -775,7 +794,7 @@ export function buildWavePrompt(wave, waveIndex, changeDir, worktreePath, option
         })
 
         // 1) 端点级契约（provider/consumer via buildContractMatrix）
-        const contracts = buildContractMatrix(planContent, changeDir)
+        const contracts = memo('contracts', () => buildContractMatrix(planContent, changeDir))
         const relevantContracts = contracts.filter(c => waveTasks.includes(c.consumer))
         if (relevantContracts.length > 0) {
           contractInjection = `
@@ -802,7 +821,7 @@ ${injection}
         // 命中「provider 漏字段、consumer fallback 编造 → 运行时 403/500」这类 bug：
         // 把 consumer 期望字段 vs provider 承诺字段显式注入子代理 prompt
         for (const taskName of waveTasks) {
-          const fi = buildContractFieldInjection(changeDir, taskName)
+          const fi = memoMap('fieldInjections', taskName, () => buildContractFieldInjection(changeDir, taskName))
           if (fi) {
             contractInjection += `
 ### 子代理 ${taskName} 的字段契约注入
@@ -848,11 +867,12 @@ ${prototypes.map(p => `- \`${path.join(protoRelDir, p)}\``).join('\n')}
       // 平台模式（specRoot 异位）回退 process.cwd()——子项目目录前缀判定用，误差只降级匹配粒度
       const repoRoot = path.basename(specBase) === '.sillyspec' ? path.dirname(specBase) : process.cwd()
       const waveTaskIds = new Set(wave.tasks.map((t, ti) => `task-${String(t.index || (ti + 1)).padStart(2, '0')}`))
-      const { hasMaps, rows } = resolveChangeModuleCards({
+      // 模块卡表与 Wave 无关（按 change 全量解析后本 Wave 过滤）：memo 跨 Wave 共享
+      const { hasMaps, rows } = memo('moduleCards', () => resolveChangeModuleCards({
         cwd: repoRoot,
         specBase,
         changeName: path.basename(changeDir),
-      })
+      }))
       const hits = rows.filter(r => waveTaskIds.has(r.taskId) && r.moduleId)
       if (hasMaps && hits.length > 0) {
         const kb = n => (n > 0 ? `${(n / 1024).toFixed(1)}KB` : '?')
@@ -879,7 +899,7 @@ ${cardLines}
       const designPath = path.join(changeDir, 'design.md')
       if (existsSync(designPath)) {
         const SECTION_CHAR_LIMIT = 2400
-        const dLines = readFileSync(designPath, 'utf8').replace(/\r\n/g, '\n').split('\n')
+        const dLines = memo('designLines', () => readFileSync(designPath, 'utf8').replace(/\r\n/g, '\n').split('\n'))
         const sections = []
         let cur = null
         dLines.forEach((l, i) => {
@@ -988,11 +1008,13 @@ ${indexLines}
 
     // D-010 跨仓 task base 锡点：派发前实时 git rev-parse HEAD 落 task 卡 base_commit
     // 仅对跨仓 task（repo≠'main'）落盘，主仓 task 锚 meta.baseHash（MultiRepoContext 已处理）
+    const baseCommitCache = new Map() // 同仓多 task 只 spawn 一次
     for (const item of perTaskWorkdirs) {
       if (item.repo === 'main') continue
       const entry = ctx.resolve(item.repo)
       if (!entry) continue
-      const baseCommit = gitQuiet(entry.gitDir, ['rev-parse', 'HEAD'])
+      if (!baseCommitCache.has(entry.gitDir)) baseCommitCache.set(entry.gitDir, gitQuiet(entry.gitDir, ['rev-parse', 'HEAD']))
+      const baseCommit = baseCommitCache.get(entry.gitDir)
       if (!baseCommit) continue // git 不可达已由 MultiRepoContext 构造时 fail-closed 拦截，此处置防御
       const taskFile = changeDir
         ? path.join(changeDir, 'tasks', `task-${item.taskNum}.md`)
@@ -1022,6 +1044,7 @@ ${crossLines}
 
 **跨仓 task 子代理 prompt 必须注入：**
 > 该 task 改的是 \`<repo>\` 仓，workdir=\`<跨仓仓根>\`。**直接在该仓主干工作区改+commit（git add + git commit 到该仓主干），不经主仓 worktree、不建分支。** commit 到该仓主干即落盘，apply 阶段对跨仓 task 为 no-op（design §5.4 G1）。
+> task 卡 allowed_paths 是相对**该仓根**的路径（如 \`src/routes/x.js\`）——不带仓库名前缀（\`<repo>/src/...\` ❌）、不是绝对路径；在 workdir 下直接按相对路径定位文件。
 `
   }
 
@@ -1265,10 +1288,14 @@ export function buildExecuteSteps(planFilePath = null, options = {}) {
   // （D-013）。缺省=null → buildWavePrompt 退化为单仓单 worktreePath（零回归）。
   const ctx = options.ctx || null
 
+  // 跨 Wave 共享缓存：plan/契约矩阵/task 卡字段注入/模块卡表/design 行集在一次步骤表
+  // 构建期间不变，逐 Wave 重读重算是 O(W×T) 纯浪费（见 buildWavePrompt 内 memo 注释）
+  const execCache = {}
+
   const waveSteps = waves.map((wave, i) => ({
     name: `Wave ${i + 1} 执行`,
     mode: 'implementation',
-    prompt: buildWavePrompt(wave, i + 1, changeDir, worktreePath, { dispatchMode: options.dispatchMode, branch: options.branch, ctx }),
+    prompt: buildWavePrompt(wave, i + 1, changeDir, worktreePath, { dispatchMode: options.dispatchMode, branch: options.branch, ctx, _execCache: execCache }),
     outputHint: `Wave ${i + 1} 执行结果`,
     optional: false
   }))

package/src/stages/knowledge.js

@@ -14,8 +14,9 @@
  *   propose  — 提议新知识（写入 proposed/）
  */
 
-import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync, statSync } from 'fs'
+import { existsSync, readFileSync, readdirSync, mkdirSync, statSync } from 'fs'
 import { join, basename } from 'path'
+import { writeAtomicSync } from '../fs-atomic.js'
 import { parseKnowledgeIndex, matchKnowledge } from '../knowledge-match.js'
 
 // ── 工具函数 ──
@@ -305,6 +306,11 @@ export async function cmdRefresh(dir, args, opts = {}) {
   const scanFiles = readdirSync(scanDir).filter(f => f.endsWith('.md'))
   const generated = []
   const overwritten = []
+  // 同 run 文件名去重（坑 knowledge-slug-collision）：slug 只由章节标题生成，不同 scan 文件
+  // 的同名章节（如各自都有「## 概述」）后者 writeFileSync 静默覆盖前者，INDEX 却登记两条
+  // 指向同一路径的条目——知识条目无声丢失。碰撞时追加 -2/-3 后缀保双份（唯一命名零扰动，
+  // 每次 refresh 按相同文件顺序重跑，后缀分配稳定）
+  const usedNames = new Set()
 
   for (const scanFile of scanFiles) {
     const scanPath = join(scanDir, scanFile)
@@ -321,7 +327,13 @@ export async function cmdRefresh(dir, args, opts = {}) {
         .replace(/^-|-$/g, '')
         .slice(0, 60)
 
-      const fileName = `${slug}.md`
+      let fileName = `${slug}.md`
+      if (usedNames.has(fileName)) {
+        let n = 2
+        while (usedNames.has(`${slug}-${n}.md`)) n++
+        fileName = `${slug}-${n}.md`
+      }
+      usedNames.add(fileName)
       const genPath = join(generatedDir, fileName)
       const isNew = !existsSync(genPath)
 
@@ -337,7 +349,8 @@ export async function cmdRefresh(dir, args, opts = {}) {
         section.body,
       ].join('\n')
 
-      writeFileSync(genPath, entryContent)
+      // INDEX/generated 是 search/validate 的解析源（跨进程读），走原子写防半截
+      writeAtomicSync(genPath, entryContent)
       generated.push({ file: `generated/${fileName}`, title: `${title} — ${section.heading}`, new: isNew })
       if (!isNew) overwritten.push(`generated/${fileName}`)
     }
@@ -358,7 +371,7 @@ export async function cmdRefresh(dir, args, opts = {}) {
   for (const g of generated) {
     indexLines.push(`- ${g.title} → [${g.file}](${g.file})`)
   }
-  writeFileSync(genIndexPath, indexLines.join('\n'))
+  writeAtomicSync(genIndexPath, indexLines.join('\n'))
 
   output(true, {
     generated_count: generated.length,
@@ -416,7 +429,7 @@ export async function cmdPropose(dir, args, opts = {}) {
     '> This is a proposed knowledge entry. Review and merge into manual/ or generated/.',
   ].join('\n')
 
-  writeFileSync(propPath, content)
+  writeAtomicSync(propPath, content)
 
   output(true, {
     id: `proposed/${slug}`,

package/src/stages/plan-postcheck.js

@@ -387,11 +387,17 @@ export function collectTaskDepMap(tasksDir) {
 /**
  * 本地一致性校验器
  * @param {string} changeDir - 变更目录
+ * @param {{ repoRegistry?: Map<string,string> }} [opts]
+ *   repoRegistry：local.yaml repos: 段解析结果（executePlanPostcheck 传入）。提供时启用两类
+ *   跨仓口径校验：① task 卡 repo: 键未注册 → error（提前到 plan 期拦，不等 execute fail-closed）；
+ *   ② allowed_paths 带其他注册键前缀 → warning。缺省（plan-adopt-waves / 单仓旧调用）只做
+ *   无注册表依赖的形态校验（绝对路径 / 自仓前缀），零回归。
  * @returns {{ ok: boolean, errors: string[], warnings: string[] }}
  */
-export function validateBlueprintConsistency(changeDir) {
+export function validateBlueprintConsistency(changeDir, opts = {}) {
   const errors = []
   const warnings = []
+  const repoRegistry = opts.repoRegistry instanceof Map ? opts.repoRegistry : null
 
   const tasksDir = pJoin(changeDir, 'tasks')
   if (!existsSync(tasksDir)) {
@@ -441,6 +447,48 @@ export function validateBlueprintConsistency(changeDir) {
       warnings.push(bsRule.data.messageTdd.replaceAll('${id}', `${taskId} (${file})`))
     }
 
+    // ── 跨仓路径口径校验（坑 cross-repo-allowed-path-base，2026-08-26 实证）──
+    // allowed_paths 的统一口径 = task 卡 repo: 声明仓的**仓根相对路径**（review 归属按
+    // `git -C <仓根> diff` 产出的仓根相对路径匹配、design 覆盖对账按「## <repo> 仓变更」
+    // 段内相对路径匹配）。agent 生成跨仓 task 卡时易把仓库名前缀 / 绝对盘符路径写进
+    // allowed_paths（如 sub-grid-security/src/...），两种对账都永不命中——task 改完却判
+    // 「无归属」、design 报「未被覆盖」，错误信号在下游且误导。此处前置拦根因：
+    //   绝对路径 / 自仓前缀（repo: X + 路径以 X/ 开头）→ error 硬拦（无合法布局）；
+    //   其他注册键前缀 → warning（主仓内与 repo 同名目录的罕见合法布局不阻断）。
+    for (const p of allowedPaths) {
+      const isAbsoluteShape = p.startsWith('/') || p.startsWith('\\\\') || /^[A-Za-z]:[\\/]/.test(p)
+      if (isAbsoluteShape) {
+        errors.push(
+          `${taskId} (${file}): allowed_paths 含绝对路径「${p}」——必须写 repo 声明仓的仓根相对路径（如 src/routes/x.js）。` +
+          `绝对路径在 review 归属对账（git -C <仓根> diff 产仓根相对路径）与 design 覆盖对账中永不命中，task 改完会被判「无归属」。`
+        )
+        continue
+      }
+      const firstSeg = p.split(/[\\/]/)[0]
+      if (repo !== 'main' && firstSeg === repo) {
+        errors.push(
+          `${taskId} (${file}): allowed_paths「${p}」带了自仓前缀「${repo}/」——该 task 已声明 repo: ${repo}，子代理 workdir 即该仓根，` +
+          `路径应为仓根相对（${p.slice(repo.length + 1)}），去掉前缀「${repo}/」。带前缀路径在两种对账中永不命中。`
+        )
+      } else if (repoRegistry && firstSeg !== 'main' && repoRegistry.has(firstSeg)) {
+        warnings.push(
+          `${taskId} (${file}): allowed_paths「${p}」首段「${firstSeg}」是 local.yaml repos: 注册键——` +
+          `若本 task 属于该跨仓仓：补 repo: ${firstSeg} 并去掉路径前缀（仓根相对）；` +
+          `若主仓内确有同名目录（罕见合法布局）：忽略本警告。`
+        )
+      }
+    }
+
+    // repo: 键注册校验（仅注册表可用时；execute 启动 MultiRepoContext 也会 fail-closed 拦，
+    // 此处提前到 plan --done，报错即给注册命令，不等 execute 才发现）
+    if (repoRegistry && repo !== 'main' && !repoRegistry.has(repo)) {
+      errors.push(
+        `${taskId} (${file}): repo: ${repo} 未在 local.yaml repos: 段注册——先跑 ` +
+        `\`sillyspec local register-repo ${repo} <${repo} 仓根路径>\` 注册（main 隐式不用注册），` +
+        `否则 execute 启动 fail-closed 阻断。`
+      )
+    }
+
     for (const p of allowedPaths) {
       const key = `${repo}|${p}`
       if (!pathOwners.has(key)) pathOwners.set(key, { repo, path: p, owners: [] })
@@ -1199,8 +1247,20 @@ export async function executePlanPostcheck(context) {
     }
   }
 
+  // ── local.yaml 预读（跨仓 repos 注册表 + monorepo modules，一次读两用）──
+  // repos 喂检查 1 的 allowed_paths 路径口径校验 + repo: 键注册校验；
+  // modules 喂检查 1c-b 的命令存在性校验（monorepo 子包感知）。
+  const localYamlPath = pJoin(specDir, 'local.yaml')
+  let taskModules = null
+  let repoRegistry = null
+  if (existsSync(localYamlPath)) {
+    const localYamlText = readFileSync(localYamlPath, 'utf8')
+    taskModules = parseLocalYamlModules(localYamlText)
+    repoRegistry = parseRepoRegistry(localYamlText)
+  }
+
   // ── 1. 一致性校验 ──
-  const consistency = validateBlueprintConsistency(changeDir)
+  const consistency = validateBlueprintConsistency(changeDir, { repoRegistry })
   if (consistency.errors.length > 0) {
     failures.push({ name: '蓝图一致性校验', errors: consistency.errors, hint: '请修复上述问题后重新完成此步骤。' })
   }
@@ -1230,11 +1290,7 @@ export async function executePlanPostcheck(context) {
   // scripts 中存在（monorepo 子包感知——读 local.yaml modules 块定位）。
   // invalid → error 硬阻断，避免 execute 子代理跑死命令（design D-04 / 问题 3）。
   // modules 块可选：无块时仅查根 package.json（与 scan-postcheck 历史行为一致）。
-  const localYamlPath = pJoin(specDir, 'local.yaml')
-  let taskModules = null
-  if (existsSync(localYamlPath)) {
-    taskModules = parseLocalYamlModules(readFileSync(localYamlPath, 'utf8'))
-  }
+  // local.yaml 已在检查 1 前预读（taskModules），此处直接消费。
   const taskCmds = validateTaskCommands(changeDir, context.cwd, taskModules)
   if (taskCmds.errors.length > 0) {
     failures.push({

package/src/stages/plan.js

@@ -329,7 +329,7 @@ tier: {REVIEW_TIER}（{REVIEW_TIER_REASON}）
 - [ ] task 编号与 Wave checkbox 格式正确，execute 依赖此格式解析任务
 - [ ] plan_level 档位与实际复杂度匹配（none/light/full 没选错）
 - [ ] 跨任务契约：task-A 的产出（接口/DTO/响应）被 task-B 消费时，consumer 是否在 TaskCard expects_from 声明所需字段、provider 是否在 provides 承诺、两边字段一致？（plan-postcheck 会硬校验，此处是独立视角复查）
-- [ ] 文件覆盖：design.md 文件变更清单中的每个源码文件，是否都被至少一个 task 的 allowed_paths 覆盖？（漏覆盖 = execute 必然漏改）
+- [ ] 文件覆盖：design.md 文件变更清单中的每个源码文件，是否都被至少一个 task 的 allowed_paths 覆盖？（漏覆盖 = execute 必然漏改。跨仓变更对账口径：design 清单按「## <repo-key> 仓变更」分段、路径相对各仓根，task 卡 repo: + 同口径相对路径匹配——allowed_paths 带仓库名前缀或绝对路径 = 永不命中、对账不上）
 - [ ] 不存在 P0/P1 unresolved blocker 残留
 - [ ] 没有实现细节泄漏到 plan.md（接口签名/代码示例应在 tasks/task-NN.md）
 - [ ] 关键路径与 Wave 依赖合理（无循环依赖、无遗漏前置）
@@ -407,7 +407,8 @@ depends_on: []
 blocks: []
 requirement_ids: [FR-XX]
 decision_ids: [D-XXX@vN]
-allowed_paths:
+repo: <repo-key>                          # 可选。仅跨仓 task 填：local.yaml repos: 注册的仓 key（缺省=main，主仓 task 省略此行）
+allowed_paths:                            # ⚠️ 路径相对 repo 声明的仓根（跨仓=跨仓仓根，主仓=主仓根），禁止带仓库名前缀/绝对路径
   - frontend/src/lib/errors.ts
 provides:                              # 可选。仅当本 task 给其他 task 提供接口/DTO/响应时填
   - contract: <DTO或响应类型名>          # 如 DaemonRuntimeRead
@@ -456,7 +457,12 @@ ${taskList}
 
 **你必须使用 Agent tool 启动子代理来写卡片，不要自己写。**
 
-1. 确认 \`${changeDir}/tasks/\` 目录存在（不存在则创建）
+0. **先由你（主 agent）一次性预生成全部骨架**（2026-08-25 实证：并行子代理各自跑 taskcard CLI 撞进度库 SQLite 锁，主代理单进程预生成 + 子代理只 Edit 才稳）：
+   \`\`\`
+   sillyspec taskcard ${changeName} --all
+   \`\`\`
+   幂等，已存在的卡跳过不覆盖；骨架带 LF 行尾 + 闭合 frontmatter + 硬校验 9 字段 + depends_on 反填。**只有主 agent 跑这一次，子代理一律不再运行 taskcard CLI。**
+1. 确认 \`${changeDir}/tasks/\` 目录存在（上一步预生成会自动创建）
 2. **按 batch 分派子代理（减少总子代理数量，而不是一个 task 一个子代理）：**
    - 把任务按「同一 Wave + 同一模块/相近能力 + 无跨 batch 强依赖」原则分组
    - **每个 batch 包含 2~4 个 task**；Wave 内任务数 ≤4 时整个 Wave 可作为一个 batch
@@ -474,7 +480,7 @@ ${taskList}
 你是一个专注的 TaskCard 生成器。你的任务是为指定 batch 生成全部 TaskCard。
 
 ## ⚠️ 格式形态（第一眼必读，坑 taskcard-body-section-rework）
-TaskCard 的契约字段全部在 **frontmatter**（首对 --- 包裹的 YAML 键值对：id/title/title_zh/allowed_paths/goal/...）——**不是 body 章节**（## 标题下的段落）。goal 是 frontmatter 的 \`goal: >\` 多行标量、implementation/acceptance/verify/constraints 是 frontmatter 的列表项；写成 body 章节（\`## goal\` / \`## Goal\` 等）会三组校验全挂返工。先跑骨架命令再 Edit 填充，骨架即正确形态。
+TaskCard 的契约字段全部在 **frontmatter**（首对 --- 包裹的 YAML 键值对：id/title/title_zh/allowed_paths/goal/...）——**不是 body 章节**（## 标题下的段落）。goal 是 frontmatter 的 \`goal: >\` 多行标量、implementation/acceptance/verify/constraints 是 frontmatter 的列表项；写成 body 章节（\`## goal\` / \`## Goal\` 等）会三组校验全挂返工。骨架已由主 agent 预生成（正确形态），直接 Edit 填充即可。
 
 ## 输入
 - 变更目录：${changeDir}
@@ -486,8 +492,7 @@ TaskCard 的契约字段全部在 **frontmatter**（首对 --- 包裹的 YAML
 ## 操作
 1. 读取 ${changeDir}/design.md 和 ${changeDir}/plan.md 了解整体上下文
 2. 读取本 batch 涉及的相关源文件
-3. 为 batch 中的**每一个 task** 先运行 CLI 生成 Windows 安全骨架（在项目根目录执行；编号/标题自动取自 plan.md，author/created_at 自动填写）：
-   sillyspec taskcard ${changeName} --task <本 batch 任务号，逗号分隔，如 task-01,task-02>
+3. **骨架已由主 agent 预生成**（\`${changeDir}/tasks/task-NN.md\` 已存在，LF 行尾 + 闭合 frontmatter + 硬校验 9 字段齐全）。**禁止再运行 \`sillyspec taskcard\` CLI**——并行子代理各起 CLI 进程会撞进度库 SQLite 锁（2026-08-25 实证）；若发现本 batch 某卡骨架缺失，报告主 agent 补跑，不要自己跑
 4. 用 Edit tool 逐卡填充骨架占位符（allowed_paths/goal/implementation/acceptance/verify/constraints 等）。**禁止用 Write 整文件重写**——手写整卡是 CRLF 行尾/漏闭合 --- /漏硬校验字段三类 postcheck 拒绝的根源，骨架 + Edit 从源头消灭
 5. 骨架字段含义与可选字段（provides/expects_from/related_tests，按需插进 frontmatter）参考下述模板：
 
@@ -496,6 +501,7 @@ ${taskcardTemplate}
 ## 约束
 - 每个 task 20~40 行；禁止在 TaskCard 里写实现细节之外的冗长设计
 - 同 batch 内 task 的 allowed_paths 不要互相冲突
+- **跨仓 task 路径口径（涉及 local.yaml repos: 注册仓的变更必读）**：跨仓 task frontmatter 必须填 \`repo: <repo-key>\`（local.yaml repos: 注册键，缺省=main 省略不填）；allowed_paths 相对**该仓根**写（\`src/routes/x.js\`），从 design.md「\`## <repo-key> 仓变更\`」段内路径原样搬。❌ 禁止带仓库名前缀（\`sub-grid-security/src/...\`）、❌ 禁止绝对路径/盘符（\`C:/repo/src/...\`）——review 对账按 \`git -C <仓根> diff\` 的仓根相对路径匹配 allowed_paths，带前缀/绝对路径永不命中 → task 改完却判「无归属」对账不上
 - 若 task 之间有 provides/expects_from 契约，同 batch 生成时必须字段对齐
 - 只生成本 batch 声明的任务，不要多写或少写
 - 不要在 TaskCard 里泄露 plan.md 中未出现的实现假设
@@ -515,6 +521,7 @@ ${taskcardTemplate}
 - 每个 task 总长度 20~40 行
 - **一致性自查**：
   - allowed_paths 有无冲突
+  - 跨仓 task：repo: 键是 local.yaml repos: 已注册键；allowed_paths 全部为仓根相对路径（无仓库名前缀、无绝对路径/盘符）；与 design.md 对应「仓变更」段路径同口径
   - depends_on 与 plan.md Wave 分组是否一致
   - provides/expects_from 契约自洽：每个 expects_from[provider].needs 字段都在该 provider task 的 provides.fields 里（plan-postcheck 会硬校验，这里提前自查）
   - related_tests 判据 = 是否有既有测试因本次改动而失败（非「源文件是否共享」；UI 文案/常量/签名变更等单文件场景也算）；若填，测试路径必须都在本 task 或某 task 的 allowed_paths 内（否则子代理无权改 → execute 测试债、主代理事后兜底）

package/src/stages/verify.js

@@ -236,7 +236,7 @@ verify-result.md 路径 + 验证报告摘要 + 下一步命令
 
 ### 注意
 - PASS → 运行 \`sillyspec run archive\` 归档
-- FAIL → 修复后运行 \`sillyspec run verify\` 重新验证
+- FAIL → 修复后运行 \`sillyspec run verify\` 重新验证——注意重验时 CLI 会重新执行 commands.test 全量对账（长套件数分钟、同步无输出属正常；可 local.yaml test_strategy: module 收窄）
 - verify-result.md 是变更包的正式验收记录，归档后保留
 - **CLI 对账机制**：本步骤 --done 时 CLI 会亲自执行 local.yaml 的 commands.test；结论写 PASS 但实测失败 → verify 完成被阻断`,
       outputHint: '验证报告',