sillyspec 3.20.7 → 3.21.0

package/package.json

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

package/src/change-list.js

@@ -1,7 +1,28 @@
 import { readFileSync, existsSync } from 'fs'
 
 /**
- * 从 design.md 解析文件变更清单
+ * 归一化清单/allowed_paths 中的路径项：
+ * - 去反引号、去行内括号注释（`src/foo.js (新增)` / `src/foo.js（说明）`）
+ * - 统一为正斜杠、去首尾空白与尾部斜杠
+ * @param {string} raw
+ * @returns {string}
+ */
+function normalizeEntry(raw) {
+  if (!raw) return ''
+  return raw
+    .replace(/`/g, '')
+    .replace(/\s*（[^）]*）\s*$/, '')
+    .replace(/\s*\([^)]*\)\s*$/, '')
+    .replace(/\\/g, '/')
+    .replace(/\/+$/, '')
+    .trim()
+}
+
+/**
+ * 从 design.md 解析文件变更清单。兼容两种真实写法：
+ *   ① 表格：`| 操作 | 文件路径 | 说明 |`（brainstorm 模板默认）
+ *   ② 分类列表：`### 新增文件` / `### 修改文件` / `### 不修改文件` 下的 `- path`
+ * 始终忽略 `.sillyspec/` 内的路径与占位符；「不修改/保留」子段下的路径会被排除。
  * @param {string} designMdPath - design.md 文件路径
  * @returns {Set<string>} 文件路径集合（相对路径，如 "src/worktree.js"）
  */
@@ -10,7 +31,7 @@ export function parseFileChangeList(designMdPath) {
 
   if (!designMdPath || !existsSync(designMdPath)) return result
 
-  const content = readFileSync(designMdPath, 'utf8')
+  const content = readFileSync(designMdPath, 'utf8').replace(/\r\n/g, '\n')
 
   // 定位"文件变更清单"标题
   const sectionRegex = /^#{2,3}\s*文件变更清单/m
@@ -24,28 +45,42 @@ export function parseFileChangeList(designMdPath) {
     ? afterSection.slice(0, nextSectionMatch.index)
     : afterSection
 
-  // 解析表格行
+  const isExcluded = (p) => !p || p === '—' || p === '-' || p.startsWith('.sillyspec/')
+
   const lines = relevantContent.split('\n')
   let headerSkipped = false
-  for (const line of lines) {
-    // 跳过分隔行和非表格行
-    if (!line.startsWith('|') || /^\|[-:\s|]+\|$/.test(line)) continue
+  // 分类列表的当前子段模式：include（新增/修改/删除）或 exclude（不修改/保留）
+  let listMode = 'include'
 
-    const cells = line.split('|').slice(1, -1) // 去掉首尾空元素
-    if (cells.length < 2) continue
-
-    // 跳过 header 行（包含「文件路径」的表头）
- if (!headerSkipped) {
-      headerSkipped = true
+  for (const line of lines) {
+    // 分类列表子标题：### 新增文件 / ### 修改文件 / ### 不修改文件
+    const subHeader = line.match(/^###\s+(.+?)\s*$/)
+    if (subHeader) {
+      listMode = /不修改|不变|保留|无变更|未变更|不改动/.test(subHeader[1]) ? 'exclude' : 'include'
       continue
     }
 
-    const filePath = cells[1].trim().replace(/^`|`$/g, '')
+    // 表格行
+    if (line.startsWith('|')) {
+      if (/^\|[-:\s|]+\|$/.test(line)) continue // 分隔行
+      const cells = line.split('|').slice(1, -1) // 去掉首尾空元素
+      if (cells.length < 2) continue
+      if (!headerSkipped) { headerSkipped = true; continue } // 跳过表头
 
-    // 忽略空路径、注释、.sillyspec/ 内的路径
-    if (!filePath || filePath === '—' || filePath === '-' || filePath.startsWith('.sillyspec/')) continue
+      const filePath = normalizeEntry(cells[1])
+      if (isExcluded(filePath)) continue
+      result.add(filePath)
+      continue
+    }
 
-    result.add(filePath)
+    // 分类列表项：`- path` / `- \`path\``
+    const listItem = line.match(/^\s*-\s+(.+)/)
+    if (listItem) {
+      const filePath = normalizeEntry(listItem[1])
+      if (isExcluded(filePath)) 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/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 } 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,171 @@ 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 }
+}
+
+// ── 路径匹配工具（与 change-list.js 的 normalizeEntry 同源语义）─────────
+// allowed_paths 真实写法常带行内注释（`src/worktree.js (新增)`），匹配前必须归一化。
+function normalizePath(raw) {
+  if (!raw) return ''
+  return raw
+    .replace(/`/g, '')
+    .replace(/\s*（[^）]*）\s*$/, '')
+    .replace(/\s*\([^)]*\)\s*$/, '')
+    .replace(/\\/g, '/')
+    .replace(/\/+$/, '')
+    .trim()
+}
+
+function globMatch(str, pattern) {
+  if (!pattern.includes('*')) return false
+  const re = '^' + pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*') + '$'
+  try { return new RegExp(re).test(str) } catch { return false }
+}
+
+/**
+ * 双向容差匹配：design 清单文件 vs task allowed_paths
+ * 命中条件（任一）：完全相等 / 目录前缀包含（双向）/ glob 通配（双向）
+ */
+function pathMatches(designFile, allowedPath) {
+  const a = normalizePath(designFile)
+  const b = normalizePath(allowedPath)
+  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
+}
+
+/**
+ * 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 不存在、无清单章节、解析为空、无 tasks/、
+ * 无 allowed_paths —— 保持与 none/light 级别及老变更向后兼容。
+ *
+ * @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 designFiles = [...parseFileChangeList(designPath)]
+  if (designFiles.length === 0) {
+    warnings.push('design.md 未找到「文件变更清单」或清单为空，跳过文件覆盖对账')
+    return { ok: true, errors, warnings, designFiles: [], uncovered: [] }
+  }
+
+  const tasksDir = pJoin(changeDir, 'tasks')
+  if (!existsSync(tasksDir)) {
+    return { ok: true, errors, warnings, designFiles, uncovered: [] }
+  }
+
+  const taskFiles = readdirSync(tasksDir).filter(f => /^task-\d+\.md$/.test(f))
+  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 +634,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)) {

package/src/stages/plan.js

@@ -358,6 +358,8 @@ full 计划的约束：
 - [ ] plan.md 与 design.md 的文件变更清单一致
 - [ ] 如果涉及构造函数/接口/DTO/client 方法变更，是否搜索了所有调用点并纳入任务范围？
 - [ ] 调用点搜索命令的输出是否记录在 plan.md 或 task-NN.md 中？
+- [ ] 跨任务契约自检：若 task-A 的产出（接口/DTO/响应）被 task-B 消费，consumer 是否在 TaskCard expects_from 里声明所需字段、provider 是否在 provides 里承诺这些字段、两边字段是否一致？（plan-postcheck 会硬校验，此处先自查）
+- [ ] 文件覆盖自检：design.md「文件变更清单」中的每个源码文件，是否都被至少一个 task 的 allowed_paths 覆盖？（plan-postcheck 会硬校验，漏覆盖 = execute 必然漏改，此处先自查）
 - [ ] 如果有 Mermaid 图，依赖关系确实非平凡（非线性/非全并行）
 - [ ] 没有泛泛风险分析（如"需要充分测试"）
 
@@ -407,6 +409,13 @@ requirement_ids: [FR-XX]
 decision_ids: [D-XXX@vN]
 allowed_paths:
   - frontend/src/lib/errors.ts
+provides:                              # 可选。仅当本 task 给其他 task 提供接口/DTO/响应时填
+  - contract: <DTO或响应类型名>          # 如 DaemonRuntimeRead
+    fields: [field_a, field_b]
+expects_from:                          # 可选。仅当本 task 消费其他 task 的契约时填
+  <provider-task-id>:                  # 如 task-05（占位符，不要照抄）
+    - contract: <DTO或响应类型名>
+      needs: [field_a]                 # 必须从该 provider 拿到的字段
 goal: >
   一句话说明这个 task 要做什么、为什么。
 implementation:
@@ -433,6 +442,9 @@ TaskCard 格式规则（必须严格遵守）：
 - verify: 列表，实际可执行的命令
 - constraints: 列表，明确边界（含 brownfield 兼容、异常处理）
 - 不需要：修改文件章节、覆盖来源章节、接口定义章节、TDD 步骤章节、参考章节
+- provides / expects_from 是可选字段：仅当跨 task 契约（一个 task 的接口/DTO/响应被另一个 task 消费）时才填，单 task 或无对外接口场景留空即可
+- 填写后 plan-postcheck 会做硬对账：consumer 的每个 expects_from[provider].needs 字段必须在对应 provider 的 provides.fields 里，否则 plan 阶段阻断（不进入 execute）
+- 不要把内部实现字段塞进 provides；只暴露给其他 task 的对外契约形状
 - 如果存在 decisions.md，无法覆盖的 D-xxx@vN 在 constraints 中标注
 - 写完后用 Write tool 保存到文件
 \`\`\``
@@ -471,6 +483,7 @@ ${subagentPrompts}
 - **一致性自查**：
   - allowed_paths 有无冲突
   - depends_on 与 plan.md Wave 分组是否一致
+  - provides/expects_from 契约自洽：每个 expects_from[provider].needs 字段都在该 provider task 的 provides.fields 里（plan-postcheck 会硬校验，这里提前自查）
   - 如发现矛盾，列出问题清单，不要自动修复`
 
   return {

package/docs/brainstorm-plan-contract.md

@@ -1,64 +0,0 @@
----
-author: qinyi
-created_at: 2026-06-19 00:45:00
----
-
-# Brainstorm → Plan Contract
-
-## 核心契约
-
-`design.md` 是 plan 阶段的**主要设计输入**。plan 不应该在空的或缺少关键决策的 design.md 上生成任务。
-
-## design.md 结构要求
-
-### 必须包含（error — 阻断 plan）
-
-| # | 章节 | 匹配关键词 |
-|---|------|-----------|
-| 1 | 目标/背景/问题描述 | 目标、goal、objective、背景、background、问题、problem、purpose、目的 |
-| 2 | 范围/总体方案/设计 | 范围、scope、总体方案、方案、approach、solution、设计、design |
-| 3 | 决策/方案选择 | 决策、decision、选择、choice、方案选择、D-xxx@vN（decisions.md 引用） |
-
-### 建议包含（warning — 不阻断 plan）
-
-| # | 章节 | 匹配关键词 |
-|---|------|-----------|
-| 4 | 非目标/Non-goals | 非目标、non-goals、不做、out of scope |
-| 5 | 约束/风险/Trade-off | 约束、constraint、风险、risk、trade-off |
-| 6 | 文件变更清单 | 文件变更、变更清单、changed files |
-
-## 校验规则
-
-plan 启动时（第一个步骤执行前）调用 `validateDesignForPlan(designContent)`：
-
-| 结果 | 行为 |
-|------|------|
-| 全部通过 | 正常进入 plan |
-| 有 warning | 继续执行，展示警告 |
-| 有 error | fail-fast，提示修复 design.md |
-
-## 第一版设计原则
-
-- **轻量 markdown 契约**：检查标题和关键词，不强 schema
-- **关键词宽泛**：中英文都支持
-- **decisions.md 引用也算决策**：`D-xxx@vN` 或 `decisions.md` 引用即满足决策检查
-- **不做 brainstorm postcheck 阻断**：brainstorm 完成时不校验此契约（brainstorm 可以产出不完整的 design.md），只在 plan 启动时校验
-
-## 错误处理
-
-| 场景 | 行为 |
-|------|------|
-| design.md 不存在 | 不校验（向后兼容，plan 可以独立运行） |
-| design.md 空 | fail-fast |
-| 缺目标/背景 | fail-fast |
-| 缺范围/方案 | fail-fast |
-| 缺决策 | fail-fast |
-| 缺非目标/约束/文件清单 | warning，继续执行 |
-
-## 完整契约链
-
-```
-brainstorm → design.md → [Plan Contract 校验] → plan → plan.md → [Execute Contract 校验] → execute
-```
-
-每个阶段启动前都校验上游产物，形成双重保险。