sillyspec 3.18.2 → 3.18.3

package/src/run.js

@@ -547,6 +547,18 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
   const total = steps.length
   const projectName = dbProjectName || basename(cwd)
 
+  // ── Revision context injection ──
+  const revisionCtx = platformOpts?._revision
+  if (revisionCtx) {
+    console.log(`### 🔄 Revision Context`)
+    console.log(`本阶段处于修订模式（revision ${revisionCtx.revision}），不是首次执行。`)
+    console.log(`- 修订起始步骤：${revisionCtx.fromStep}`)
+    console.log(`- 当前步骤之前已完成的步骤仍然有效，不需要重做。`)
+    console.log(`- 当前步骤及之后的步骤需要重新生成或调整已有产物。`)
+    console.log(`- 已有产物文件（design.md、plan.md 等）被保留，审视并更新它们，而不是从零创建。`)
+    console.log(`- 不要绕过 CLI 进度追踪。\n`)
+  }
+
   const personas = {
     brainstorm: `### 🎯 你的角色：资深架构师
 你是一位有 15 年经验的系统架构师。先理解业务本质，再设计技术方案。决策附理由，方案列 trade-off。不确定就说不确定，不猜。`,
@@ -708,6 +720,36 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
     promptText = promptText.replace(/\{SPEC_ROOT\}/g, specSillyspec)
   }
 
+  // Knowledge hit report: execute 阶段注入匹配结果
+  if (stageName === 'execute' && promptText.includes('{KNOWLEDGE_HIT_REPORT}')) {
+    try {
+      const { matchKnowledge } = await import('./knowledge-match.js')
+      const effectiveSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+      const knowledgeDir = join(effectiveSpecBase, 'knowledge')
+      // taskContext: changeName + plan.md task names for better matching
+      let taskContext = changeName || ''
+      if (changeName) {
+        const planPath = join(effectiveSpecBase, 'changes', changeName, 'plan.md')
+        try {
+          const planContent = readFileSync(planPath, 'utf8')
+          // match both "- [ ] task-01: title" and "## task-01: title" formats
+          const taskLines = [...planContent.matchAll(/(?:^\- \[[ x]\] |^## )task-\d+[^:]*:?\s*(.+)/gm)]
+          if (taskLines.length > 0) {
+            taskContext += ' ' + taskLines.map(t => t[1]).join(' ')
+          }
+        } catch {}
+      }
+      const knowledgeResult = matchKnowledge(knowledgeDir, taskContext)
+      promptText = promptText.replace(/\{KNOWLEDGE_HIT_REPORT\}/g, knowledgeResult.report)
+      // 写入 runtime JSON
+      const runtimeDir = join(effectiveSpecBase, '.runtime')
+      mkdirSync(runtimeDir, { recursive: true })
+      writeFileSync(join(runtimeDir, 'knowledge-hit-report.json'), JSON.stringify(knowledgeResult.json, null, 2) + '\n')
+    } catch (e) {
+      promptText = promptText.replace(/\{KNOWLEDGE_HIT_REPORT\}/g, 'Status: no matches (error: ' + e.message + ')')
+    }
+  }
+
   // 注入模块上下文（brainstorm/plan/execute 阶段，基于 Module Context Index）
   if (['brainstorm', 'plan', 'execute'].includes(stageName) && projectName) {
     const effectiveSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
@@ -1016,6 +1058,8 @@ export async function runCommand(args, cwd, specDir = null) {
   const isSkip = flags.includes('--skip')
   const isStatus = flags.includes('--status')
   const isReset = flags.includes('--reset')
+  const isReopen = flags.includes('--reopen')
+  const fromStepValue = getFlagValue('--from-step')
   const isConfirm = flags.includes('--confirm')
   const isSkipApproval = flags.includes('--skip-approval')
   const isWait = flags.includes('--wait')
@@ -1153,6 +1197,7 @@ export async function runCommand(args, cwd, specDir = null) {
     '--spec-dir', '--spec-root', '--runtime-root', '--workspace-id', '--scan-run-id',
     '--files', '--allow-new', '--force-baseline', '--force-rescan',
     '--json', '--dir', '--help',
+    '--reopen', '--from-step',
   ])
   for (let i = 0; i < flags.length; i++) {
     const f = flags[i]
@@ -1223,6 +1268,79 @@ export async function runCommand(args, cwd, specDir = null) {
     return await resetStage(pm, progress, stageName, cwd, effectiveChange, platformOpts)
   }
 
+  // ── 规则 1：completed 阶段直接 run，拒绝（但 --status 放行）──
+  const stageStatus = progress.stages[stageName]?.status
+  if (stageStatus === 'completed' && !isReopen && !isStatus) {
+    console.error(`\n❌ ${stageName} 阶段已完成。`)
+    console.error(`   使用 --reopen 进行修订，或 --reset 从头开始。`)
+    console.error(`   修订示例: sillyspec run ${stageName} --reopen --from-step <步骤序号或名称>`)
+    process.exit(1)
+  }
+
+  // ── 规则 5：stale 阶段直接 run，拒绝（但 --status / --reset 放行）──
+  if (stageStatus === 'stale' && !isReopen && !isStatus && !isReset) {
+    const staleReason = progress.stages[stageName]?.staleReason || '上游阶段已修订'
+    console.error(`\n⚠️ ${stageName} 阶段已失效（stale）。`)
+    console.error(`   原因：${staleReason}`)
+    console.error(`   使用 --reopen --from-step <步骤> 进行修订，或 --reset 从头开始。`)
+    process.exit(1)
+  }
+
+  // ── --reopen 处理 ──
+  if (isReopen) {
+    // stale/revising 阶段可能 steps 为空，或者 execute 阶段的 steps 需要从最新 plan.md 刷新
+    const stageDataPre = progress.stages[stageName]
+    const needsInit = !stageDataPre || !stageDataPre.steps || stageDataPre.steps.length === 0
+    // execute 阶段在 reopen 时需要从最新 plan.md 重新解析 steps（plan 可能已变更）
+    if (needsInit || stageName === 'execute') {
+      const freshSteps = await getStageSteps(stageName, cwd, progress, specRoot)
+      if (freshSteps && freshSteps.length > 0) {
+        if (!progress.stages[stageName]) progress.stages[stageName] = { status: 'stale', steps: [] }
+        progress.stages[stageName].steps = freshSteps.map(s => ({ name: s.name, status: 'pending' }))
+        await pm._write(cwd, progress, effectiveChange)
+        progress = await pm.read(cwd, effectiveChange) || progress
+      }
+    }
+
+    const result = await pm.reopenStage(cwd, stageName, {
+      fromStep: fromStepValue,
+      changeName: effectiveChange,
+    })
+    if (!result.ok) {
+      console.error(`\n❌ ${result.error}`)
+      if (stageStatus === 'completed') {
+        console.error(`\n   提示：sillyspec run ${stageName} --reopen --from-step <步骤序号或名称>`)
+      }
+      process.exit(1)
+    }
+    console.log(`\n🔧 ${stageName} 阶段已重新打开（revision ${result.revision}）`)
+    console.log(`   从步骤「${result.fromStep}」开始修订`)
+    console.log(`   该步骤及之后的产出需要重新生成。`)
+    if (stageName === 'execute') console.log(`   ⚡ execute 步骤已从最新 plan.md 重新解析。`)
+    console.log('')
+
+    // 重新读取 progress
+    progress = await pm.read(cwd, effectiveChange) || progress
+
+    // 注入 revision context 到 platformOpts，供 outputStep 使用
+    const stageData = progress.stages[stageName]
+    if (stageData && stageData.revision > 0) {
+      platformOpts._revision = {
+        revision: stageData.revision,
+        fromStep: stageData.reopenedFromStep,
+      }
+    }
+  } else {
+    // 非 reopen 的正常执行：如果阶段处于 revising 状态，也注入 revision context
+    const revStageData = progress.stages[stageName]
+    if (revStageData && revStageData.status === 'revising' && revStageData.revision > 0 && !platformOpts._revision) {
+      platformOpts._revision = {
+        revision: revStageData.revision,
+        fromStep: revStageData.reopenedFromStep,
+      }
+    }
+  }
+
   // 确保步骤已初始化
   const changed = await ensureStageSteps(progress, stageName, cwd, specRoot)
   if (changed && effectiveChange) {
@@ -1358,6 +1476,13 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
 
   let currentIdx = steps.findIndex(s => s.status !== 'completed' && s.status !== 'skipped')
 
+  // stale 步骤视为可执行（等同于 pending）
+  if (currentIdx !== -1 && steps[currentIdx].status === 'stale') {
+    steps[currentIdx].status = 'pending'
+    await pm._write(cwd, progress, changeName)
+    triggerSync(cwd, changeName, platformOpts)
+  }
+
   // ── scanProfile: 根据 project 规模动态裁剪步骤 ──
   let scanProfile = null
   if (stageName === 'scan' && steps.length > 0 && currentIdx === 0) {
@@ -1453,6 +1578,29 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
     console.log(`  继续执行将从中断处恢复，用 --reset 可重新开始。\n`)
   }
 
+  // ── Brainstorm → Plan Contract：plan 启动前校验 design.md ──
+  if (stageName === 'plan' && currentIdx === 0) {
+    const changeDir = resolveChangeDir(cwd, progress, platformOpts?.specRoot || null)
+    const designPath = changeDir ? join(changeDir, 'design.md') : null
+    if (designPath && existsSync(designPath)) {
+      const { validateDesignForPlan } = await import('./stages/plan.js')
+      const designContent = readFileSync(designPath, 'utf8')
+      const designValidation = validateDesignForPlan(designContent)
+      if (!designValidation.ok) {
+        console.error(`\n❌ Brainstorm → Plan Contract 校验失败：`)
+        for (const err of designValidation.errors) console.error(`   - ${err}`)
+        console.error(`\n   design.md 不满足 plan 契约，请先修复后重试。`)
+        console.error(`   提示：sillyspec run brainstorm --reopen --from-step <步骤> 修订设计文档`)
+        process.exit(1)
+      }
+      if (designValidation.warnings.length > 0) {
+        console.log(`⚠️  Design contract 警告（不阻断）：`)
+        for (const w of designValidation.warnings) console.log(`   - ${w}`)
+        console.log()
+      }
+    }
+  }
+
   const defSteps = await getStageSteps(stageName, cwd, progress)
   if (defSteps && defSteps[currentIdx]) {
     // noAI 步骤自动完成（CLI-only，不需要 Agent 参与）
@@ -2336,6 +2484,34 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
           console.warn(`   - ${w}`)
         }
       }
+
+      // ── Plan postcheck contract：plan.md 必须满足 execute 契约 ──
+      if (stageName === 'plan') {
+        const planFile = resolveChangeDir(cwd, progress, platformOpts?.specRoot)
+        const planPath = planFile ? join(planFile, 'plan.md') : null
+        if (planPath && existsSync(planPath)) {
+          const { validatePlanForExecute } = await import('./stages/execute.js')
+          const planContent = readFileSync(planPath, 'utf8')
+          const planValidation = validatePlanForExecute(planContent)
+          if (!planValidation.ok) {
+            console.error(`\n❌ Plan → Execute Contract 校验失败：`)
+            for (const err of planValidation.errors) console.error(`   - ${err}`)
+            console.error(`\n   plan.md 不满足 execute 契约，请修复后重新完成此步骤。`)
+            // 阻断 completed
+            progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
+            await pm._write(cwd, progress, changeName)
+            triggerSync(cwd, changeName, platformOpts)
+            return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
+          }
+          if (planValidation.warnings.length > 0) {
+            console.warn(`\n⚠️  Plan contract 警告（不阻断完成）：`)
+            for (const w of planValidation.warnings) console.warn(`   - ${w}`)
+          }
+          if (planValidation.ok) {
+            console.log(`\n✅ Plan → Execute Contract 校验通过（${planValidation.tasks.length} tasks, ${planValidation.waves.length} waves）`)
+          }
+        }
+      }
     } else if (actualCompleted < actualTotal) {
       // 实际步骤未全部完成，跳过 validator（状态可能不同步）
       console.log(`\n⚠️ 阶段校验跳过：${actualTotal} 步中仅 ${actualCompleted} 步标记为已完成，可能存在状态不同步。如确认阶段已完成，请运行 --status 确认。`)
@@ -2509,8 +2685,12 @@ function showStatus(progress, stageName) {
   const stageDef = stageRegistry[stageName]
 
   if (!stageData || !stageData.steps || stageData.steps.length === 0) {
-    console.log(`阶段：${stageName}（${stageDef.title}）`)
+    console.log(`阶段：${stageName}（${stageDef?.title || stageName}）`)
     console.log(`进度：未初始化`)
+    if (stageData?.status) {
+      console.log(`状态：${stageData.status}`)
+      if (stageData.staleReason) console.log(`⚠️ 失效原因：${stageData.staleReason}`)
+    }
     return
   }
 
@@ -2518,8 +2698,25 @@ function showStatus(progress, stageName) {
   const completed = steps.filter(s => s.status === 'completed' || s.status === 'skipped').length
   const bar = '█'.repeat(completed) + '░'.repeat(steps.length - completed)
 
-  console.log(`阶段：${stageName}（${stageDef.title}）`)
-  console.log(`进度：[${bar}] ${completed}/${steps.length}\n`)
+  console.log(`阶段：${stageName}（${stageDef?.title || stageName}）`)
+  console.log(`进度：[${bar}] ${completed}/${steps.length}`)
+
+  // ── Revision v1 信息 ──
+  if (stageData.status === 'revising') {
+    console.log(`\n🔧 修订中 (revision ${stageData.revision || 1})`)
+    if (stageData.reopenedFromStep) console.log(`   从步骤：${stageData.reopenedFromStep}`)
+    if (stageData.reopenedAt) console.log(`   重开时间：${stageData.reopenedAt}`)
+  }
+  if (stageData.status === 'stale') {
+    console.log(`\n⚠️ 已失效`)
+    if (stageData.staleReason) console.log(`   原因：${stageData.staleReason}`)
+    console.log(`   建议：sillyspec run ${stageName} --reopen --from-step 1`)
+  }
+  if (stageData.status === 'completed') {
+    console.log(`\n✅ 已完成`)
+  }
+
+  console.log('')
 
   const firstPending = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
 

package/src/scan-postcheck.js

@@ -95,12 +95,13 @@ export function runScanPostCheck({ cwd, specDir, outputText = '', scanMeta = {}
     })
   }
 
-  // 3. 检查文档 header（author / created_at）
+  // 3. 检查文档 header（author / created_at）— 只看文件头部，避免正文出现同名词被误判
   const existingDocs = REQUIRED_SCAN_DOCS.filter(f => existsSync(join(specScanDir, f)))
   const docsMissingHeader = []
   for (const doc of existingDocs) {
     const content = readFileSync(join(specScanDir, doc), 'utf8')
-    if (!content.includes('author') || !content.includes('created_at')) {
+    const headerSlice = content.slice(0, 512)
+    if (!/author\s*:/.test(headerSlice) || !/created_at\s*:/.test(headerSlice)) {
       docsMissingHeader.push(doc)
     }
   }
@@ -183,6 +184,37 @@ export function runScanPostCheck({ cwd, specDir, outputText = '', scanMeta = {}
     })
   }
 
+  // 7.5 knowledge 产物校验
+  const knowledgeDir = join(specDir, 'knowledge')
+  if (existsSync(knowledgeDir)) {
+    const indexPath = join(knowledgeDir, 'INDEX.md')
+    if (!existsSync(indexPath)) {
+      checks.push({
+        name: 'knowledge_index_missing',
+        severity: CHECK_SEVERITY.WARNING,
+        detail: `knowledge/INDEX.md 不存在`
+      })
+    } else {
+      // 检查 INDEX.md 引用的文件是否真实存在
+      const indexContent = readFileSync(indexPath, 'utf8')
+      const referencedFiles = [...indexContent.matchAll(/\(([^)]+\.md)/g)].map(m => m[1])
+      const missingRefs = referencedFiles.filter(f => !existsSync(join(knowledgeDir, f)))
+      if (missingRefs.length > 0) {
+        checks.push({
+          name: 'knowledge_broken_refs',
+          severity: CHECK_SEVERITY.WARNING,
+          detail: `INDEX.md 引用了不存在的文件: ${missingRefs.join(', ')}`
+        })
+      }
+    }
+  } else {
+    checks.push({
+      name: 'knowledge_dir_missing',
+      severity: CHECK_SEVERITY.WARNING,
+      detail: `knowledge/ 目录不存在`
+    })
+  }
+
   // 8. 计算 finalStatus
   const hasFailed = checks.some(c => c.severity === CHECK_SEVERITY.FAILED)
   const hasWarning = checks.some(c => c.severity === CHECK_SEVERITY.WARNING)

package/src/stage-contract.js

@@ -7,6 +7,7 @@
 
 import { existsSync, readdirSync, readFileSync } from 'fs'
 import { join, basename } from 'path'
+import { detectChangeRisk, checkIntegrationEvidence } from './change-risk-profile.js'
 
 /**
  * 校验结果
@@ -233,6 +234,17 @@ function validateBrainstormOutputs(cwd, changeName, context = {}) {
     if (!content.includes('自审') && !content.includes('Self-Review') && !content.includes('Self-review')) {
       warnings.push('design.md 缺少「自审」章节')
     }
+
+    // P1: 涉及生命周期关键词时，design.md 必须包含生命周期契约表
+    const hasLifecycleKeyword = /\b(session|lease|agent[._-]?run|daemon|lifecycle|state[._-]?transition|claim|heartbeat)\b/i.test(content)
+    if (hasLifecycleKeyword) {
+      const hasLifecycleTable =
+        /生命周期契约表|lifecycle[._-]?contract|lifecycle[._-]?matrix|Lifecycle Contract/i.test(content) ||
+        /事件.*发起方.*接收方.*必需字段.*状态变化/.test(content)
+      if (!hasLifecycleTable) {
+        errors.push('design.md 涉及生命周期关键词（session/lease/agent_run/daemon/lifecycle）但缺少「生命周期契约表」— 必须列出完整的事件×状态转换矩阵')
+      }
+    }
   }
 
   if (existsSync(join(changeDir, 'tasks.md'))) {
@@ -294,12 +306,62 @@ function validatePlanOutputs(cwd, changeName, context = {}) {
     const decisionIds = extractCurrentDecisionIds(decisions)
     warnMissingIds(warnings, decisionIds, plan, 'plan.md', 'decisions.md')
   }
+  // ── P0: 生产接线路径检查：design 提到入口但 task 的 allowed_paths 不含入口文件 ──
+  const designContent = readIfExists(join(changeDir, 'design.md'))
+  if (designContent) {
+    const entryPointPatterns = [
+      /\b(cli\.ts|main\.ts|server\.(?:js|ts)|index\.(?:js|ts))\b.*\b(?:实例化|instantiate|构造|new\s)/gi,
+      /\bnew\s+(Daemon|SessionManager|App|Server|Application)\b/gi,
+      /\b(?:在|from)\s+['"]?(cli\.ts|main\.ts|server\.(?:js|ts)|index\.(?:js|ts))['"]?/gi,
+      /\b(?:注入|inject)\b.*\b(?:构造|constructor|初始化|init|实例化|instantiate)\b/gi,
+      /\b(?:启动路径|startup|entrypoint|bootstrap|daemon[._-]?start|main.*entry)\b/gi,
+    ]
+    const mentionedFiles = new Set()
+    for (const pattern of entryPointPatterns) {
+      pattern.lastIndex = 0
+      for (const match of designContent.matchAll(pattern)) {
+        const fileMatch = match[0].match(/\b(cli\.ts|main\.ts|server\.(?:js|ts)|index\.(?:js|ts))\b/i)
+        if (fileMatch) mentionedFiles.add(fileMatch[1].toLowerCase())
+      }
+    }
+    if (mentionedFiles.size > 0) {
+      const tasksDir = join(changeDir, 'tasks')
+      const allAllowedPaths = new Set()
+      if (existsSync(tasksDir)) {
+        const taskFiles = readdirSync(tasksDir).filter(f => /^task-\d+\.md$/i.test(f))
+        for (const taskFile of taskFiles) {
+          const taskContent = readFileSync(join(tasksDir, taskFile), 'utf8')
+          const allowedSection = taskContent.match(/allowed_paths:\s*\n((?:\s+-\s+.+\n?)+)/)
+          if (allowedSection) {
+            const paths = allowedSection[1].match(/-\s+(.+)/g) || []
+            for (const p of paths) allAllowedPaths.add(p.replace(/^-\s+/, '').trim().toLowerCase())
+          }
+        }
+      }
+      // 也从 plan.md 文件变更清单中收集
+      if (existsSync(planFile)) {
+        const planContent = readFileSync(planFile, 'utf8')
+        const planFileChanges = planContent.match(/\|\s*(?:新增|修改|new|modify|update)\s*\|\s*`?([^`|]+)`?\s*\|/gi) || []
+        for (const line of planFileChanges) {
+          const file = line.match(/\|\s*(?:新增|修改|new|modify|update)\s*\|\s*`?([^`|]+)`?\s*\|/i)
+          if (file) allAllowedPaths.add(file[1].trim().toLowerCase())
+        }
+      }
+      for (const mentionedFile of mentionedFiles) {
+        const found = [...allAllowedPaths].some(p => p.includes(mentionedFile))
+        if (!found) {
+          const noChangePattern = new RegExp(`不需要改.*${mentionedFile}|${mentionedFile}.*不需要|不修改.*${mentionedFile}|${mentionedFile}.*不变|${mentionedFile}.*no.?change`, 'i')
+          if (!noChangePattern.test(designContent)) {
+            errors.push(`生产接线路径矛盾: design.md 提到了入口文件 "${mentionedFile}" 但所有 task 的 allowed_paths 中均不含该文件`)
+            warnings.push(`提示: 如果确实不需要修改 ${mentionedFile}，请在 design.md 中明确写明理由`)
+          }
+        }
+      }
+    }
+  }
+
   return { ok: errors.length === 0, errors, warnings }
 }
-
-/**
- * verify 完成校验：检查变更目录和 verify 产物
- */
 function validateVerifyOutputs(cwd, changeName, context = {}) {
   const { specRoot } = context
   const changeDir = resolveChangeDir(cwd, changeName, specRoot)
@@ -334,6 +396,24 @@ function validateVerifyOutputs(cwd, changeName, context = {}) {
     }
     const decisionIds = extractCurrentDecisionIds(decisions)
     warnMissingIds(warnings, decisionIds, verify, 'verify-result.md', 'decisions.md')
+
+    // ── P0: Change Risk Gate — 核心功能缺少真实集成验证时 FAIL ──
+    const changeRiskProfile = detectChangeRisk({
+      designContent: readIfExists(join(changeDir, 'design.md')),
+      planContent: readIfExists(join(changeDir, 'plan.md')),
+    })
+    if (['integration-critical', 'deployment-critical'].includes(changeRiskProfile.level)) {
+      const conclusionMatch = verify.match(/^## 结论\s*\n\s*(PASS|PASS WITH NOTES|FAIL)/im)
+      const conclusion = conclusionMatch ? conclusionMatch[1] : ''
+      if (conclusion === 'PASS WITH NOTES' || conclusion === 'PASS') {
+        const evidenceCheck = checkIntegrationEvidence(verify, changeRiskProfile.requiredVerification)
+        if (!evidenceCheck.ok) {
+          errors.push(`[${changeRiskProfile.level}] 验证结论为 ${conclusion}，但缺少真实集成证据：${evidenceCheck.errors.join('; ')}`)
+          errors.push(`触发词: ${changeRiskProfile.triggers.join(', ')} — PASS WITH NOTES 不被允许，必须 FAIL 或提供集成证据`)
+        }
+        warnings.push(...evidenceCheck.warnings)
+      }
+    }
   }
 
   return { ok: errors.length === 0, errors, warnings }
@@ -520,7 +600,7 @@ export function checkTransition(fromStage, toStage) {
     return { allowed: true }
   }
 
-  // 同阶段内重复运行：允许（继续执行当前阶段的下一步）
+  // 同阶段内重复运行：允许（继续执行当前阶段的下一步、或修订模式继续）
   if (fromStage === toStage) {
     return { allowed: true }
   }
@@ -537,7 +617,7 @@ export function checkTransition(fromStage, toStage) {
     return { allowed: false, reason: 'archive 的前置阶段是 verify，不能从 ' + fromStage + ' 跳转' }
   }
 
-  // 从辅助阶段进入主流程：允许（用户可能 scan 完直接 brainstorm 或 plan）
+  // 从辅助阶段进入主流程：允许
   if (auxiliaryStages.includes(fromStage)) {
     return { allowed: true }
   }

package/src/stages/brainstorm.js

@@ -344,6 +344,28 @@ HTML 原型文件路径（或"跳过"如果不适合）`,
 | 删除 | src/xxx/OldFile.java | 已被 xx 替代 |
 
 7. **接口定义**：方法签名、数据结构（代码类任务必填）
+7.5. **生命周期契约表**（涉及以下关键词时必填，否则可省略）：
+
+   如果本次变更涉及以下任何关键词：
+   session / lease / agent_run / daemon / lifecycle / state transition / complete / end / claim / heartbeat
+
+   则必须在 design.md 中包含「生命周期契约表」章节，格式如下：
+
+   | 事件 | 发起方 | 接收方 | 必需字段 | 状态变化 |
+   |---|---|---|---|---|
+   | claim lease | daemon | backend | leaseId, claimToken, agentRunId | pending → running |
+   | create session | backend | daemon | sessionId, leaseId, claimToken | session active |
+   | submit message | daemon | backend | leaseId, claimToken, agentRunId | append messages |
+   | turn result | daemon | backend | runId, status, output | running → completed/failed |
+   | session end | daemon | backend | sessionId, reason | active → ended |
+
+   判断规则：
+   - design.md 或需求中出现上述关键词 → 必须生成此表
+   - 表中的每个事件 → 必须有对应代码任务、接口任务、测试任务
+   - 表中的必需字段 → 必须出现在相关 DTO/interface 定义中
+   - 缺少任一事件 → 在 design.md 风险登记中明确记录
+
+   **判定方法**：在自审阶段，如果检测到上述关键词但 design.md 中没有此表 → 自审不通过
 8. **数据模型**（如涉及）：表结构/字段变更
 9. **兼容策略**（brownfield 必填）：
    - 未配置新功能时行为不变
@@ -382,6 +404,7 @@ HTML 原型文件路径（或"跳过"如果不适合）`,
    - 非目标清晰：是否明确界定了不做的事
    - 兼容策略（brownfield）：是否说明了回退路径
    - 风险识别：是否识别了关键技术风险和对策
+   - **生命周期契约表**（如涉及 session/lease/agent_run/daemon/lifecycle/claim/heartbeat 等关键词）：design.md 是否包含完整的生命周期契约表？每个事件是否有必需字段定义？字段是否出现在 DTO/interface 中？
 5. 自审发现问题 → 修改后重新检查
 6. 全部通过 → 进入下一步
 

package/src/stages/execute.js

@@ -1,6 +1,86 @@
 import { existsSync, readFileSync } from 'fs'
 import path from 'path'
 
+/**
+ * 校验 plan.md 是否满足 execute 执行契约
+ * @param {string} planContent - plan.md 文件内容
+ * @returns {{ ok: boolean, errors: string[], warnings: string[], tasks: object[], waves: object[] }}
+ */
+export function validatePlanForExecute(planContent) {
+  const errors = []
+  const warnings = []
+
+  if (!planContent || !planContent.trim()) {
+    return { ok: false, errors: ['plan.md 内容为空'], warnings, tasks: [], waves: [] }
+  }
+
+  const waves = parseWavesFromPlan(planContent)
+
+  // 收集所有 task
+  const allTasks = []
+  for (const wave of waves) {
+    for (const task of wave.tasks) {
+      allTasks.push(task)
+    }
+  }
+
+  // 检查 1: 至少有一个 checkbox task
+  if (allTasks.length === 0) {
+    errors.push('plan.md 中没有找到 checkbox task（格式: "- [ ] task-XX: 任务名"）')
+    return { ok: false, errors, warnings, tasks: allTasks, waves }
+  }
+
+  // 检查 2: task id 唯一性
+  const idCounts = {}
+  for (const task of allTasks) {
+    if (task.index != null) {
+      const key = `task-${task.index}`
+      idCounts[key] = (idCounts[key] || 0) + 1
+    }
+  }
+  for (const [id, count] of Object.entries(idCounts)) {
+    if (count > 1) {
+      errors.push(`task id 重复: ${id} 出现 ${count} 次`)
+    }
+  }
+
+  // 检查 3: task id 连续性（从 1 开始）
+  const ids = allTasks
+    .map(t => t.index)
+    .filter(i => i != null)
+    .sort((a, b) => a - b)
+  if (ids.length > 0) {
+    const expected = Array.from({ length: ids.length }, (_, i) => ids[0] + i)
+    // 只检查以 task-01 起始的情况（常见模式）
+    if (ids[0] === 1) {
+      for (let i = 0; i < ids.length; i++) {
+        if (ids[i] !== i + 1) {
+          errors.push(`task id 不连续: 期望 task-${String(i + 1).padStart(2, '0')}, 实际 task-${String(ids[i]).padStart(2, '0')}`)
+          break
+        }
+      }
+    }
+  }
+
+  // 检查 4: task name 非空
+  for (const task of allTasks) {
+    if (!task.name || !task.name.trim()) {
+      errors.push(`task-${String(task.index || '?').padStart(2, '0')}: 任务名为空`)
+    }
+  }
+
+  // 检查 5: task 无 id 的 warning（不限制只在有 id 时检查）
+  for (const wave of waves) {
+    for (const task of wave.tasks) {
+      if (task.index == null) {
+        warnings.push(`Wave ${wave.index}: task "${task.name}" 没有 task id（建议格式 task-XX: 名称）`)
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings, tasks: allTasks, waves }
+}
+
 export const definition = {
   name: 'execute',
   title: '波次执行',
@@ -46,6 +126,27 @@ const fixedPrefix = [
     - 用 main_symbols 字段找到核心类/函数的定义位置
     - 子代理优先读模块卡片理解语义，再读 entrypoints/main_symbols 对应的源码
 
+### 符号影响面扩展检查
+11. **符号影响面扫描**（Critical — execute 前必做）：
+    - 读取所有 tasks/task-NN.md，提取每个任务涉及的修改文件
+    - 对每个修改文件，检查是否涉及以下变更类型：
+      - class 构造函数参数变更（新增/删除/修改参数）
+      - 接口（interface）定义变更
+      - DTO / 类型定义变更
+      - API client 方法签名变更
+      - 函数/方法签名变更（参数增删改）
+    - 如果涉及上述变更类型，执行调用点搜索：
+      \`\`\`bash
+      rg "new ClassName\(" src/
+      rg "ClassName\(" src/
+      rg "methodName\(" src/
+      rg "import.*from.*filePath" src/
+      \`\`\`
+    - 将搜索到的调用点与 plan.md 和 tasks/task-NN.md 的 allowed_paths 对比
+    - **发现调用点不在任何 task 的 allowed_paths 中 → 直接阻断 execute**
+    - 报告：列出每个受影响符号、调用点位置、是否在任务范围内
+    - 如果调用点不在范围内但任务明确写了"不改原因"，记录但不阻断
+
 ### 输出
 已加载的上下文摘要（含模块文档 + 源码锚点）`,
     outputHint: '上下文摘要',
@@ -91,6 +192,12 @@ sillyspec run execute --done --output "worktree 路径 + 分支名 + 模式"`,
    - auto — 全部自动执行
 5. 查询知识库：读取 \`.sillyspec/knowledge/INDEX.md\`，根据 Task 关键词匹配
 
+### 知识命中报告
+{KNOWLEDGE_HIT_REPORT}
+
+如上所示的知识条目与本次任务相关。请阅读这些条目以获取项目约定和已知模式。
+如无命中条目（Status: no matches），跳过本节。
+
 ### 铁律
 - **不要询问用户确认频率**，确认模式由 CLI \`--confirm-mode\` 参数决定
 - 如果未检测到 \`--confirm-mode\`，默认使用 wave 模式`,
@@ -403,12 +510,13 @@ export function buildExecuteSteps(planFilePath = null, options = {}) {
 
   if (planFilePath && existsSync(planFilePath)) {
     const planContent = readFileSync(planFilePath, 'utf8')
+    // Plan → Execute 契约由 plan 阶段完成时的 postcheck 把关（run.js completeStep），
+    // 此处只负责解析 waves，避免 buildExecuteSteps 与进程退出耦合。
     waves = parseWavesFromPlan(planContent)
-    // 从 planFilePath 推导 changeDir: .sillyspec/changes/<name>/plan.md
     changeDir = path.dirname(planFilePath)
   }
 
-  // 如果没解析出 Wave，生成默认 3 个
+  // 没解析出 Wave（plan 不存在或不含可识别 task）→ 默认 3 Wave（向后兼容）
   if (!waves || waves.length === 0) {
     waves = []
     for (let i = 1; i <= 3; i++) {