sillyspec 3.18.1 → 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) {
@@ -1253,7 +1371,8 @@ export async function runCommand(args, cwd, specDir = null) {
 
   // --done
   if (isDone) {
-    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, confirmMode })
+    const doneAnswer = getFlagValue('--answer')
+    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, confirmMode, doneAnswer })
   }
 
   // 默认：输出当前步骤
@@ -1301,6 +1420,26 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
     }
   }
 
+  // execute 阶段：CLI 自动创建 worktree（不等 AI agent）
+  if (stageName === 'execute' && changeName) {
+    const effectiveChange = changeName
+    const { WorktreeManager } = await import('./worktree.js')
+    const wm = new WorktreeManager({ cwd })
+    const existingMeta = wm.getMeta(effectiveChange)
+    if (existingMeta) {
+      console.log(`🔗 worktree 已存在: ${existingMeta.worktreePath} (${existingMeta.mode})`)
+    } else {
+      try {
+        const result = wm.create(effectiveChange)
+        console.log(`🔗 worktree 已创建: ${result.worktreePath} (分支: ${result.branch}, 模式: ${result.mode})`)
+      } catch (e) {
+        console.error(`❌ worktree 创建失败: ${e.message}`)
+        console.error(`   继续执行前请解决上述问题，或使用 --no-worktree 跳过。`)
+        process.exit(1)
+      }
+    }
+  }
+
   // 自动探测 currentChange
   if (autoDetectChange(progress, cwd)) {
     progress.lastActive = new Date().toLocaleString('zh-CN', { hour12: false })
@@ -1337,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) {
@@ -1432,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 参与）
@@ -1832,14 +2001,24 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
   const currentStepDef = defStepsForCurrent?.[currentIdx] || {}
   const currentStep = steps[currentIdx]
   if (currentStepDef.requiresWait === true && !currentStep.waitAnswer) {
-    console.error(`❌ Step "${currentStep.name}" 必须先等待用户输入，不能直接 --done。`)
-    console.error(`   原因：${currentStepDef.waitReason || '该步骤需要人工确认/回答'}`)
-    if (currentStepDef.waitOptions) {
-      console.error(`   选项：${currentStepDef.waitOptions.join(', ')}`)
+    // 检查 --done 是否带了 --answer：如果是，自动补全 waitAnswer 状态，一步完成
+    const doneAnswer = typeof options !== 'undefined' && options.doneAnswer ? options.doneAnswer : null
+    if (doneAnswer) {
+      currentStep.status = 'waiting'
+      currentStep.waitAnswer = doneAnswer
+      currentStep.waitReason = currentStepDef.waitReason || '等待用户输入'
+      console.log(`⚠️  Step "${currentStep.name}" 需要 wait，但 --done 带了 --answer，自动补全 wait 状态。`)
+    } else {
+      console.error(`❌ Step "${currentStep.name}" 必须先等待用户输入，不能直接 --done。`)
+      console.error(`   原因：${currentStepDef.waitReason || '该步骤需要人工确认/回答'}`)
+      if (currentStepDef.waitOptions) {
+        console.error(`   选项：${currentStepDef.waitOptions.join(', ')}`)
+      }
+      console.error(`   请先执行：`)
+      console.error(`   sillyspec run ${stageName} --wait --reason "${currentStepDef.waitReason || '等待用户输入'}" --options "${(currentStepDef.waitOptions || ['确认']).join(',')}"${changeName ? ` --change ${changeName}` : ''} --output "你的问题/方案摘要"`)
+      console.error(`   或使用 --done --answer "用户回答" 一步完成 wait + done`)
+      process.exit(1)
     }
-    console.error(`   请先执行：`)
-    console.error(`   sillyspec run ${stageName} --wait --reason "${currentStepDef.waitReason || '等待用户输入'}" --options "${(currentStepDef.waitOptions || ['确认']).join(',')}"${changeName ? ` --change ${changeName}` : ''} --output "你的问题/方案摘要"`)
-    process.exit(1)
   }
 
   steps[currentIdx].status = 'completed'
@@ -2234,10 +2413,16 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       }
     }
 
+    // 防御性守卫变量：确认所有步骤确实标记为 completed
+    const actualCompleted = steps.filter(s => s.status === 'completed').length
+    const actualTotal = steps.length
+
     validateMetadata(cwd, stageName, specBase)
 
-    // 验证关键文件是否在正确的变更目录下
-    validateFileLocations(cwd, stageName, progress, changeName, specBase)
+    // 验证关键文件是否在正确的变更目录下（仅当所有步骤确实完成时才校验）
+    if (actualCompleted === actualTotal && actualTotal > 0) {
+      validateFileLocations(cwd, stageName, progress, changeName, specBase)
+    }
 
     // 辅助阶段完成后重置步骤
     const stageDef = stageRegistry[stageName]
@@ -2281,24 +2466,58 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
     } else {
       console.log(`\n下一步由你决定：sillyspec run <stage>（brainstorm/plan/execute/verify/archive 等）`)
     }
-    return { stageCompleted: true, currentIdx, nextPendingIdx: -1 }
-  }
 
-  // 阶段完成校验
-  const projectName = progress.project || basename(cwd)
-  const contractResult = runValidators(stageName, cwd, changeName, { projectName, specRoot: platformOpts?.specRoot })
-  if (contractResult.errors.length > 0) {
-    console.error(`\n❌ 阶段 ${stageName} 校验失败：`)
-    for (const err of contractResult.errors) {
-      console.error(`   - ${err}`)
-    }
-    console.error(`\n   提示：修复缺失产物后重新运行此步骤，或使用 --skip-approval 跳过校验`)
-  }
-  if (contractResult.warnings.length > 0) {
-    console.warn(`\n⚠️ 阶段 ${stageName} 校验警告：`)
-    for (const w of contractResult.warnings) {
-      console.warn(`   - ${w}`)
+    // 阶段完成校验 — 防御性守卫：仅当所有步骤确实标记为 completed 时才跑 validator
+    if (actualCompleted === actualTotal && actualTotal > 0) {
+      const projectName = progress.project || basename(cwd)
+      const contractResult = runValidators(stageName, cwd, changeName, { projectName, specRoot: platformOpts?.specRoot })
+      if (contractResult.errors.length > 0) {
+        console.error(`\n❌ 阶段 ${stageName} 校验失败：`)
+        for (const err of contractResult.errors) {
+          console.error(`   - ${err}`)
+        }
+        console.error(`\n   提示：修复缺失产物后重新运行此步骤，或使用 --skip-approval 跳过校验`)
+      }
+      if (contractResult.warnings.length > 0) {
+        console.warn(`\n⚠️ 阶段 ${stageName} 校验警告：`)
+        for (const w of contractResult.warnings) {
+          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 确认。`)
     }
+
+    return { stageCompleted: true, currentIdx, nextPendingIdx: -1 }
   }
 
   progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
@@ -2466,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
   }
 
@@ -2475,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,6 +600,11 @@ export function checkTransition(fromStage, toStage) {
     return { allowed: true }
   }
 
+  // 同阶段内重复运行：允许（继续执行当前阶段的下一步、或修订模式继续）
+  if (fromStage === toStage) {
+    return { allowed: true }
+  }
+
   // archive 特殊处理：从 verify 来的允许，从其他主流程阶段来的需要校验
   if (toStage === 'archive') {
     if (fromStage === 'verify') {
@@ -532,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. 全部通过 → 进入下一步