sillyspec 3.20.7 → 3.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.20.7",
+  "version": "3.22.0",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/change-list.js

@@ -1,52 +1,163 @@
-import { readFileSync, existsSync } from 'fs'
-
-/**
- * 从 design.md 解析文件变更清单
- * @param {string} designMdPath - design.md 文件路径
- * @returns {Set<string>} 文件路径集合（相对路径，如 "src/worktree.js"）
- */
-export function parseFileChangeList(designMdPath) {
-  const result = new Set()
-
-  if (!designMdPath || !existsSync(designMdPath)) return result
-
-  const content = readFileSync(designMdPath, 'utf8')
-
-  // 定位"文件变更清单"标题
-  const sectionRegex = /^#{2,3}\s*文件变更清单/m
-  const sectionMatch = content.match(sectionRegex)
-  if (!sectionMatch) return result
-
-  // 从标题后开始，截取到下一个 ## 标题或文件末尾
-  const afterSection = content.slice(sectionMatch.index + sectionMatch[0].length)
-  const nextSectionMatch = afterSection.match(/^##\s/m)
-  const relevantContent = nextSectionMatch
-    ? afterSection.slice(0, nextSectionMatch.index)
-    : afterSection
-
-  // 解析表格行
-  const lines = relevantContent.split('\n')
-  let headerSkipped = false
-  for (const line of lines) {
-    // 跳过分隔行和非表格行
-    if (!line.startsWith('|') || /^\|[-:\s|]+\|$/.test(line)) continue
-
-    const cells = line.split('|').slice(1, -1) // 去掉首尾空元素
-    if (cells.length < 2) continue
-
-    // 跳过 header 行（包含「文件路径」的表头）
- if (!headerSkipped) {
-      headerSkipped = true
-      continue
-    }
-
-    const filePath = cells[1].trim().replace(/^`|`$/g, '')
-
-    // 忽略空路径、注释、.sillyspec/ 内的路径
-    if (!filePath || filePath === '—' || filePath === '-' || filePath.startsWith('.sillyspec/')) continue
-
-    result.add(filePath)
-  }
-
-  return result
-}
+import { readFileSync, existsSync } from 'fs'
+
+/**
+ * 路径项归一化：去反引号、去行内括号注释（`src/foo.js (新增)` / `src/foo.js（说明）`）、
+ * 统一为正斜杠、去首尾空白与尾部斜杠。
+ * design 清单 cell 与 task allowed_paths 共用此归一化（两处写法都可能带注释/反引号）。
+ * @param {string} raw
+ * @returns {string}
+ */
+export function normalizePath(raw) {
+  if (!raw) return ''
+  return raw
+    .replace(/`/g, '')
+    .replace(/\s*（[^）]*）\s*$/, '')
+    .replace(/\s*\([^)]*\)\s*$/, '')
+    .replace(/\\/g, '/')
+    .replace(/\/+$/, '')
+    .trim()
+}
+
+/**
+ * glob → 正则：双星（globstar）跨零或多段目录（含零段，bash 语义）、
+ * 单星 → 单段（[^/]*）、问号 → 单字符（[^/]），其余转义。
+ * pattern 不含通配符时返回 false（调用方先用完全相等判断）。
+ * 不支持字符类（design/allowed_paths 实际不写，遇方括号按字面转义）。
+ * @param {string} str
+ * @param {string} pattern
+ * @returns {boolean}
+ */
+export function globMatch(str, pattern) {
+  if (!/[*?]/.test(pattern)) return false
+  let re = '^'
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i]
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') {
+        // ** 跨零或多段：吞掉紧随的 /，输出 (?:.*/)? 让 src/**/a.js 也能匹配 src/a.js
+        if (pattern[i + 2] === '/') { re += '(?:.*/)?'; i += 2 }
+        else { re += '.*'; i++ }
+      } else {
+        re += '[^/]*'
+      }
+    } else if (ch === '?') {
+      re += '[^/]'
+    } else {
+      re += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    }
+  }
+  re += '$'
+  try { return new RegExp(re).test(str) } catch { return false }
+}
+
+/**
+ * 双向容差匹配：design 清单文件 vs task allowed_paths（或脏文件 vs 清单）。
+ * 命中条件（任一）：完全相等 / 目录前缀包含（双向）/ glob 通配（双向）。
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function pathMatches(a, b) {
+  a = normalizePath(a)
+  b = normalizePath(b)
+  if (!a || !b) return false
+  if (a === b) return true
+  if (a.startsWith(b + '/') || b.startsWith(a + '/')) return true
+  if (globMatch(a, b) || globMatch(b, a)) return true
+  return false
+}
+
+/**
+ * 「文件变更清单」章节标题同义词（与 src/stage-contract.js 的识别集对齐，
+ * 避免两个校验器对「有没有清单」给出矛盾结论）。
+ */
+const FILE_LIST_SECTION_RE = /^#{2,3}\s*(文件变更清单|变更文件清单|文件清单|File Changes|Files to Change)/im
+
+/**
+ * exclude 子标题词集：「不修改/暂缓/保留」类 —— 其下路径从清单移除，不强制 task 覆盖。
+ * 用排除集而非白名单：容忍「改动/变更/涉及」等近义 include 写法。
+ */
+const EXCLUDE_SUBSECTION_RE = /不修改|不变|保留|无变更|未变更|不改动|暂不|暂缓|暂定|待定|后续|未改|无需|不涉及/
+
+function isPlaceholder(p) {
+  return !p || p === '—' || p === '-' || /^(n\/?a|无|none|-+)$/i.test(p)
+}
+
+/** 表头列定位：cell 整体匹配路径类词 */
+function isPathHeaderCell(c) {
+  return /^(文件路径|文件名|文件|路径|filepath|filename|file\s*path|path)$/i.test(c)
+}
+
+/**
+ * 从 design.md 解析文件变更清单。兼容两种真实写法：
+ *   ① 表格：`| 操作 | 文件路径 | 说明 |`（brainstorm 模板默认）
+ *   ② 分类列表：`### 新增文件` / `### 修改文件` / `### 不修改文件` 下的 `- path`
+ * 表头列顺序自适应（定位「文件/路径/file/path」列，列顺序写反时不会把操作名当路径）；
+ * 忽略 `.sillyspec/` 与占位符（`—`/`-`/`N/A`/`无`）；「不修改/暂缓」子段下的路径会被排除；
+ * CRLF 容错。
+ * @param {string} designMdPath - design.md 文件路径
+ * @returns {Set<string>} 文件路径集合（相对路径，如 "src/worktree.js"）
+ */
+export function parseFileChangeList(designMdPath) {
+  const result = new Set()
+  if (!designMdPath || !existsSync(designMdPath)) return result
+
+  const content = readFileSync(designMdPath, 'utf8').replace(/\r\n/g, '\n')
+
+  const sectionMatch = content.match(FILE_LIST_SECTION_RE)
+  if (!sectionMatch) return result
+
+  // 从标题后开始，截取到下一个 ## 标题或文件末尾
+  const afterSection = content.slice(sectionMatch.index + sectionMatch[0].length)
+  const nextSectionMatch = afterSection.match(/^##\s/m)
+  const relevantContent = nextSectionMatch
+    ? afterSection.slice(0, nextSectionMatch.index)
+    : afterSection
+
+  const lines = relevantContent.split('\n')
+  let headerSkipped = false
+  let pathColIdx = 1            // 默认第 2 列；解析表头后可重定位
+  let listMode = 'include'      // include | exclude（分类列表子段）
+
+  for (const line of lines) {
+    // 分类列表子标题：### 新增文件 / ### 修改文件 / ### 不修改文件
+    const subHeader = line.match(/^###\s+(.+?)\s*$/)
+    if (subHeader) {
+      listMode = EXCLUDE_SUBSECTION_RE.test(subHeader[1]) ? 'exclude' : 'include'
+      continue
+    }
+
+    // 表格行
+    if (line.startsWith('|')) {
+      if (/^\|[-:\s|]+\|$/.test(line)) continue // 分隔行
+      const cells = line.split('|').slice(1, -1).map(c => c.trim())
+      if (cells.length < 2) continue
+
+      if (!headerSkipped) {
+        headerSkipped = true
+        // 表头列定位：找「文件/路径/file/path」列，找不到保持默认第 2 列
+        const idx = cells.findIndex(isPathHeaderCell)
+        if (idx >= 0) pathColIdx = idx
+        continue
+      }
+
+      const filePath = normalizePath(cells[pathColIdx] || '')
+      // 列定位兜底：取到纯操作词（表头未命中且列顺序异常）→ 跳过，避免把「修改」当路径
+      if (/^(新增|修改|删除|重命名|new|modify|update|delete|create|rename)$/i.test(filePath)) continue
+      if (isPlaceholder(filePath) || filePath.startsWith('.sillyspec/')) continue
+      result.add(filePath)
+      continue
+    }
+
+    // 分类列表项：`- path` / `- \`path\``
+    const listItem = line.match(/^\s*-\s+(.+)/)
+    if (listItem) {
+      const filePath = normalizePath(listItem[1])
+      if (isPlaceholder(filePath) || filePath.startsWith('.sillyspec/')) continue
+      if (listMode === 'exclude') result.delete(filePath)
+      else result.add(filePath)
+    }
+  }
+
+  return result
+}

package/src/contract-matrix.js

@@ -15,6 +15,7 @@ import {
   scanFrontendApiCalls,
   normalizePath,
 } from './endpoint-extractor.js'
+import { parseTaskContracts } from './stages/plan-postcheck.js'
 
 // ─── 关键词检测 ─────────────────────────────────────────────────────────
 
@@ -218,6 +219,72 @@ export function buildConsumerInjection(changeDir, specBase, taskName, contracts)
   return parts.join('\n')
 }
 
+/**
+ * 为 consumer task 构建字段级契约注入：对比 expects_from.needs vs provider.provides.fields
+ *
+ * 让 consumer 子代理带着明确的字段清单核验上游产出：
+ * - provider 已承诺 → 编码时只使用 provides.fields，运行时缺字段上报
+ * - provider 未承诺某 needs 字段 → 标 CONTRACT_GAP，要求 stop and report（禁止 fallback 编造）
+ *
+ * 命中场景：provider task 漏实现某字段（如 DaemonRuntimeRead 缺 daemon_instance_id），
+ * consumer 若 fallback 编造 → 运行时 403/500。此处把"缺字段"暴露在子代理启动前。
+ *
+ * 注：plan-postcheck 已对账 expects_from↔provides，此处是 execute 时的二次保险，
+ * 拦截 plan-postcheck 之后 task 文件被手改、或 provider 实际实现漏字段的情况。
+ *
+ * @param {string} changeDir - changes/<name>/ 目录
+ * @param {string} taskName - consumer task（如 task-11）
+ * @returns {string|null} 注入文本，无 expects_from 时返回 null
+ */
+export function buildContractFieldInjection(changeDir, taskName) {
+  const consumerFile = join(changeDir, 'tasks', `${taskName}.md`)
+  if (!existsSync(consumerFile)) return null
+  const { expectsFrom } = parseTaskContracts(readFileSync(consumerFile, 'utf8'))
+  const providers = Object.keys(expectsFrom)
+  if (providers.length === 0) return null
+
+  const lines = []
+  lines.push('## Upstream Contract Fields（字段级核验）')
+  lines.push('')
+
+  for (const providerTask of providers) {
+    const providerFile = join(changeDir, 'tasks', `${providerTask}.md`)
+    let providerProvides = []
+    if (existsSync(providerFile)) {
+      providerProvides = parseTaskContracts(readFileSync(providerFile, 'utf8')).provides
+    }
+
+    for (const c of expectsFrom[providerTask]) {
+      const providerEntry = providerProvides.find(p => p.contract === c.contract)
+      if (!providerEntry) {
+        lines.push(`### ⚠️ CONTRACT_GAP: ${providerTask} → ${c.contract}`)
+        lines.push(`你需要字段 [${c.needs.join(', ')}]，但 ${providerTask} 的 provides 未声明此契约。`)
+        lines.push(`**立即停止编码并上报**：不要 fallback、不要编造字段，先确认 ${providerTask} 是否应产出此契约。`)
+      } else {
+        const providerFields = new Set(providerEntry.fields)
+        const missing = c.needs.filter(f => !providerFields.has(f))
+        if (missing.length > 0) {
+          lines.push(`### ⚠️ CONTRACT_GAP: ${providerTask} → ${c.contract}`)
+          lines.push(`你需要字段 [${missing.join(', ')}]，但 ${providerTask}.provides 仅承诺 [${providerEntry.fields.join(', ')}]。`)
+          lines.push(`**立即停止编码并上报**：不要 fallback、不要编造字段，先要求 ${providerTask} 在 provides.fields 补上 [${missing.join(', ')}]。`)
+        } else {
+          lines.push(`### ✅ ${providerTask} → ${c.contract}`)
+          lines.push(`你需要的字段 [${c.needs.join(', ')}] 均在 ${providerTask}.provides 承诺内：[${providerEntry.fields.join(', ')}]。`)
+          lines.push(`编码时**只使用上述字段**；若运行时实际返回缺字段，说明 provider 实现漏了 → 上报 CONTRACT_GAP，不要 fallback。`)
+        }
+      }
+      lines.push('')
+    }
+  }
+
+  lines.push('### 字段级铁律')
+  lines.push('1. 禁止 fallback 编造：若上游返回缺字段，停止并上报 CONTRACT_GAP，不要用 `x || defaultValue` 之类的防御性回退掩盖契约破裂。')
+  lines.push('2. 只消费 provides 承诺的字段；需要新字段必须先让 provider 更新 provides。')
+  lines.push('3. 启动子代理前，先读 provider task 的 review.json / acceptance，确认其已声明完成上述契约字段。')
+
+  return lines.join('\n')
+}
+
 // ─── Verify 阶段：parity check ──────────────────────────────────────────
 
 /**

package/src/quick-recommend.js

@@ -8,7 +8,7 @@
  */
 import { join } from 'path'
 import { existsSync, readFileSync } from 'fs'
-import { parseFileChangeList } from './change-list.js'
+import { parseFileChangeList, pathMatches } from './change-list.js'
 
 function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
@@ -60,13 +60,13 @@ function readProposalContext(specDir, changeName) {
 
 /**
  * 判断单个脏文件是否命中 design.md 声明的文件清单。
- * 支持精确匹配 + 目录前缀匹配（design 可能写目录、脏文件是目录下文件，或反之）。
+ * 复用 change-list.js 的 pathMatches：完全相等 / 目录前缀（双向）/ glob 通配（双向），
+ * 与 plan-postcheck 的文件覆盖对账共用同一套匹配语义；并修复了 design 清单含 glob
+ * （如 `src/stages/scan/*.md`）时纯前缀匹配漏召回的问题。
  */
 function fileHitsList(dirtyFile, fileList) {
-  if (fileList.has(dirtyFile)) return true
   for (const declared of fileList) {
-    if (declared === dirtyFile) continue
-    if (dirtyFile.startsWith(declared + '/') || declared.startsWith(dirtyFile + '/')) return true
+    if (pathMatches(dirtyFile, declared)) return true
   }
   return false
 }

package/src/stages/execute.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'fs'
 import path from 'path'
+import { buildContractMatrix, buildConsumerInjection, buildContractFieldInjection } from '../contract-matrix.js'
 
 /**
  * 校验 plan.md 是否满足 execute 执行契约
@@ -430,42 +431,60 @@ function buildWavePrompt(wave, waveIndex, changeDir, worktreePath) {
   let contractInjection = ''
   if (changeDir) {
     try {
-      const { buildContractMatrix, buildConsumerInjection } = require('../contract-matrix.js')
       const planFile = path.join(changeDir, 'plan.md')
       if (existsSync(planFile)) {
         const planContent = readFileSync(planFile, 'utf8')
+        // 收集本 wave 所有 task（端点注入与字段注入共用）
+        const waveTasks = wave.tasks.map((t, ti) => {
+          const num = String(t.index || (ti + 1)).padStart(2, '0')
+          return `task-${num}`
+        })
+
+        // 1) 端点级契约（provider/consumer via buildContractMatrix）
         const contracts = buildContractMatrix(planContent, changeDir)
-        if (contracts.length > 0) {
-          // 收集本 wave 所有 task 的注入内容
-          const waveTasks = wave.tasks.map((t, ti) => {
-            const num = String(t.index || (ti + 1)).padStart(2, '0')
-            return `task-${num}`
-          })
-          const relevantContracts = contracts.filter(c => waveTasks.includes(c.consumer))
-          if (relevantContracts.length > 0) {
-            contractInjection = `
+        const relevantContracts = contracts.filter(c => waveTasks.includes(c.consumer))
+        if (relevantContracts.length > 0) {
+          contractInjection = `
 ### API Contract Matrix
 本 Wave 存在前端/后端跨 task 契约：
 ${relevantContracts.map(c => `- **${c.consumer}** 消费 **${c.provider}** 产出的 API`).join('\n')}
 `
-            // 为每个 consumer task 生成详细注入
-            for (const taskName of waveTasks) {
-              const injection = buildConsumerInjection(changeDir, join(changeDir, '..', '..'), taskName, contracts)
-              if (injection) {
-                contractInjection += `
-### 子代理 ${taskName} 的契约注入
+          for (const taskName of waveTasks) {
+            const injection = buildConsumerInjection(changeDir, path.join(changeDir, '..', '..'), taskName, contracts)
+            if (injection) {
+              contractInjection += `
+### 子代理 ${taskName} 的端点契约注入
 为 ${taskName} 启动子代理时，在子代理 prompt 末尾追加以下内容：
 
 <contract-injection>
 ${injection}
 </contract-injection>
 `
-              }
             }
           }
         }
+
+        // 2) 字段级契约（expects_from ↔ provides）
+        // 命中「provider 漏字段、consumer fallback 编造 → 运行时 403/500」这类 bug：
+        // 把 consumer 期望字段 vs provider 承诺字段显式注入子代理 prompt
+        for (const taskName of waveTasks) {
+          const fi = buildContractFieldInjection(changeDir, taskName)
+          if (fi) {
+            contractInjection += `
+### 子代理 ${taskName} 的字段契约注入
+为 ${taskName} 启动子代理时，在子代理 prompt 末尾追加以下内容：
+
+<contract-field-injection>
+${fi}
+</contract-field-injection>
+`
+          }
+        }
       }
-    } catch {}
+    } catch (e) {
+      // 契约注入是 best-effort：失败不阻断 execute，只记录
+      console.warn(`  ⚠️ 契约注入跳过: ${e?.message || e}`)
+    }
   }
 
   // 构建任务摘要（不再内联完整蓝图，减少上下文污染）

package/src/stages/plan-postcheck.js

@@ -11,6 +11,8 @@
  */
 import { existsSync, readFileSync, readdirSync } from 'fs'
 import { join as pJoin } from 'path'
+import jsYaml from 'js-yaml'
+import { parseFileChangeList, pathMatches } from '../change-list.js'
 
 // ═══════════════════════════════════════════════════════════════
 // 解析工具（从 plan.js 迁移）
@@ -90,6 +92,47 @@ function hasTddOrVerify(content) {
   return /##\s*TDD/.test(content) || /##\s*验证/.test(content) || /##\s*Verify/.test(content)
 }
 
+/**
+ * 解析 task-NN.md 的跨任务契约字段 provides / expects_from
+ * 用 js-yaml 解析 frontmatter（嵌套结构，正则不可靠）。
+ * provides/expects_from 为可选字段；缺失或解析失败时返回空（不阻断）。
+ * @param {string} content - task 文件内容
+ * @returns {{ provides: Array<{contract, fields}>, expectsFrom: Record<string, Array<{contract, needs}>> }}
+ */
+export function parseTaskContracts(content) {
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/)
+  if (!fmMatch) return { provides: [], expectsFrom: {} }
+  let fm
+  try {
+    fm = jsYaml.load(fmMatch[1]) || {}
+  } catch {
+    // frontmatter 非合法 YAML（老格式/手写不规范）—— 当作无契约字段，不阻断
+    return { provides: [], expectsFrom: {} }
+  }
+
+  const provides = Array.isArray(fm.provides)
+    ? fm.provides.map(p => ({
+        contract: String(p?.contract || ''),
+        fields: Array.isArray(p?.fields) ? p.fields.map(String) : [],
+      })).filter(p => p.contract)
+    : []
+
+  const expectsFrom = {}
+  if (fm.expects_from && typeof fm.expects_from === 'object' && !Array.isArray(fm.expects_from)) {
+    for (const [providerTask, contracts] of Object.entries(fm.expects_from)) {
+      if (!Array.isArray(contracts)) continue
+      expectsFrom[providerTask] = contracts
+        .map(c => ({
+          contract: String(c?.contract || ''),
+          needs: Array.isArray(c?.needs) ? c.needs.map(String) : [],
+        }))
+        .filter(c => c.contract)
+    }
+  }
+
+  return { provides, expectsFrom }
+}
+
 // ═══════════════════════════════════════════════════════════════
 // 核心逻辑
 // ═══════════════════════════════════════════════════════════════
@@ -222,6 +265,151 @@ export function validateBlueprintConsistency(changeDir) {
   return { ok: errors.length === 0, errors, warnings }
 }
 
+/**
+ * 跨任务契约校验器：对账 consumer.expects_from ↔ provider.provides
+ *
+ * 修复场景：consumer task 声明期望 provider 产出某 DTO 的某字段，
+ * 但 provider 的 provides 未承诺（或字段缺失）→ plan 阶段阻断，
+ * 避免到 execute/verify 才暴露（典型表现：前端 fallback 错误字段 → 403/500）。
+ *
+ * provides / expects_from 均为可选字段：未声明时不校验（向后兼容）。
+ * @param {string} changeDir - 变更目录
+ * @returns {{ ok: boolean, errors: string[], warnings: string[] }}
+ */
+export function validateCrossTaskContracts(changeDir) {
+  const errors = []
+  const warnings = []
+
+  const tasksDir = pJoin(changeDir, 'tasks')
+  if (!existsSync(tasksDir)) {
+    return { ok: true, errors, warnings }
+  }
+
+  const taskFiles = readdirSync(tasksDir).filter(f => /^task-\d+\.md$/.test(f))
+  if (taskFiles.length === 0) {
+    return { ok: true, errors, warnings }
+  }
+
+  // 第一遍：收集每个 task 的 provides（taskId → Map(contract → Set(fields))）
+  const providesByTask = new Map()
+  for (const file of taskFiles) {
+    const content = readFileSync(pJoin(tasksDir, file), 'utf8')
+    const taskId = parseTaskId(content, file)
+    if (!taskId) continue
+    const { provides } = parseTaskContracts(content)
+    const contractMap = new Map()
+    for (const p of provides) {
+      contractMap.set(p.contract, new Set(p.fields))
+    }
+    providesByTask.set(taskId, contractMap)
+  }
+
+  // 第二遍：校验每个 consumer 的 expects_from 是否被 provider.provides 覆盖
+  for (const file of taskFiles) {
+    const content = readFileSync(pJoin(tasksDir, file), 'utf8')
+    const consumerId = parseTaskId(content, file)
+    if (!consumerId) continue
+    const { expectsFrom } = parseTaskContracts(content)
+
+    for (const [providerTask, contracts] of Object.entries(expectsFrom)) {
+      if (!providesByTask.has(providerTask)) {
+        for (const c of contracts) {
+          errors.push(`${consumerId}: expects_from 引用了不存在的 ${providerTask}（contract "${c.contract}", needs [${c.needs.join(', ')}]）`)
+        }
+        continue
+      }
+
+      const providerContracts = providesByTask.get(providerTask)
+      for (const c of contracts) {
+        const providerFields = providerContracts.get(c.contract)
+        if (providerFields === undefined) {
+          errors.push(`${consumerId}: expects_from ${providerTask} contract "${c.contract}" needs [${c.needs.join(', ')}] — ${providerTask} 的 provides 未声明此契约`)
+          continue
+        }
+        const missing = c.needs.filter(f => !providerFields.has(f))
+        if (missing.length > 0) {
+          errors.push(`${consumerId}: expects_from ${providerTask} contract "${c.contract}" needs [${missing.join(', ')}] — ${providerTask}.provides 仅含 [${[...providerFields].join(', ')}]`)
+        }
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+// 路径容差匹配（normalizePath / globMatch / pathMatches）复用自 change-list.js，
+// design 清单解析与 allowed_paths 对账共用同一套匹配语义，避免两处逻辑漂移。
+
+/**
+ * design.md 文件变更清单 → tasks allowed_paths 覆盖对账
+ *
+ * 修复场景：design.md 声明要改某源码文件（如 access-guide UI），但没有任何 task 的
+ * allowed_paths 覆盖它 → execute 子代理被 allowed_paths 锁死不能碰它 → UI 没改
+ * （「页面还是错的」），而 verify 一路对照 task 卡片循环验证照样 PASS。
+ *
+ * 在 plan-postcheck（execute 前）确定性拦截：design 清单中每个源码文件必须被
+ * 至少一个 task 的 allowed_paths 覆盖（前缀 / glob 容差匹配）。
+ *
+ * fail-open 边界（不阻断）：design.md 不存在、无 task 卡片（none 级别）、
+ * task 卡片均无 allowed_paths（由 validatePlanFeasibility 把关）。
+ * 阻断边界：有 task 卡片但 design 缺清单章节（light/full 已生成 task → design 必有清单）、
+ * 清单文件未被任何 task 的 allowed_paths 覆盖。
+ *
+ * @param {string} changeDir - 变更目录
+ * @returns {{ ok: boolean, errors: string[], warnings: string[], designFiles: string[], uncovered: string[] }}
+ */
+export function validateDesignFileCoverage(changeDir) {
+  const errors = []
+  const warnings = []
+
+  const designPath = pJoin(changeDir, 'design.md')
+  if (!existsSync(designPath)) {
+    return { ok: true, errors, warnings, designFiles: [], uncovered: [] }
+  }
+
+  const tasksDir = pJoin(changeDir, 'tasks')
+  const taskFiles = existsSync(tasksDir)
+    ? readdirSync(tasksDir).filter(f => /^task-\d+\.md$/.test(f))
+    : []
+
+  // 无 task 卡片（plan_level=none 或老变更）→ 无对账对象，fail-open
+  if (taskFiles.length === 0) {
+    return { ok: true, errors, warnings, designFiles: [], uncovered: [] }
+  }
+
+  const designFiles = [...parseFileChangeList(designPath)]
+  if (designFiles.length === 0) {
+    // 走到 plan-postcheck 说明已生成 task 卡片（light/full），brainstorm 模板规定清单必填。
+    // 无清单 = design↔execute 偏差温床（覆盖对账无从对起），阻断，不让它静默放过。
+    errors.push(
+      'design.md 缺少「文件变更清单」章节（或清单解析为空），无法做文件覆盖对账。' +
+      '该章节在 brainstorm 模板中为必填；请在 design.md 补上完整的文件变更清单（列出本次新增/修改/删除的源码文件）后重试。'
+    )
+    return { ok: false, errors, warnings, designFiles: [], uncovered: [] }
+  }
+  const allAllowed = []
+  for (const file of taskFiles) {
+    const content = readFileSync(pJoin(tasksDir, file), 'utf8')
+    allAllowed.push(...parseAllowedPaths(content))
+  }
+  if (allAllowed.length === 0) {
+    return { ok: true, errors, warnings, designFiles, uncovered: [] }
+  }
+
+  const uncovered = designFiles.filter(df => !allAllowed.some(ap => pathMatches(df, ap)))
+  if (uncovered.length > 0) {
+    errors.push(
+      `design.md 文件变更清单中 ${uncovered.length} 个文件未被任何 task 的 allowed_paths 覆盖：\n` +
+      uncovered.map(f => `     • ${f}`).join('\n') +
+      `\n   这些文件在 execute 阶段将无 task 有权修改 → 必然漏改。` +
+      `\n   修复：为每个遗漏文件新建/补充 task 并在其 allowed_paths 声明，` +
+      `或在 design.md「不修改文件」章节说明不改原因。`
+    )
+  }
+
+  return { ok: errors.length === 0, errors, warnings, designFiles, uncovered }
+}
+
 /**
  * Plan 可行性校验器（本地代码证明 execute 前置条件）
  * 检查 TaskCard 的完整性和可行性
@@ -426,6 +614,32 @@ export async function executePlanPostcheck(context) {
     for (const w of feasibility.warnings) console.warn(`   - ${w}`)
   }
 
+  // ── 1c. 跨任务契约校验 ──
+  // 对账 consumer.expects_from ↔ provider.provides，拦截「consumer 期望字段
+  // 但 provider 未承诺」的契约断裂（避免到 execute/verify 才暴露成 403/500）
+  const crossTask = validateCrossTaskContracts(changeDir)
+  if (crossTask.errors.length > 0) {
+    console.error('\n❌ 跨任务契约校验失败（consumer 期望的字段未被 provider 承诺）：')
+    for (const err of crossTask.errors) console.error(`   - ${err}`)
+    console.error('\n   修复方式：要么在 provider task 的 provides.fields 补上缺失字段，')
+    console.error('   要么修正 consumer task 的 expects_from.needs（确认依赖是否真实）。')
+    throw new Error('planPostcheck: cross-task contract check failed')
+  }
+
+  // ── 1d. design 文件覆盖对账 ──
+  // design.md 清单中的每个源码文件必须被某 task 的 allowed_paths 覆盖，
+  // 否则 execute 子代理无权改它 → 漏改（典型表现：「页面还是错的」）。
+  const coverage = validateDesignFileCoverage(changeDir)
+  for (const w of coverage.warnings) console.warn(`\n  ⚠️  ${w}`)
+  if (coverage.errors.length > 0) {
+    console.error('\n❌ design.md 文件覆盖对账失败（清单中的文件未被任何 task 覆盖）：')
+    for (const err of coverage.errors) console.error(`   - ${err}`)
+    throw new Error('planPostcheck: design file coverage check failed')
+  }
+  if (coverage.designFiles.length > 0 && coverage.uncovered.length === 0) {
+    console.log(`  ✅ design.md ${coverage.designFiles.length} 个文件全部被 task allowed_paths 覆盖`)
+  }
+
   // ── 2. Wave 重排 ──
   const tasksDir = pJoin(changeDir, 'tasks')
   if (existsSync(tasksDir)) {