@xulthekl/team-flow 0.36.1 → 0.36.2

package/.claude/always/phase-guard.md

@@ -1,3 +1,3 @@
-# team-flow v0.36.1 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.36.2 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "team-flow",
       "description": "8-state spec workflow + compound global compounding + architecture-design (4A/DDD) + local HTML prototype + product-level orchestration + bootstrap + e2e + session handoff + workflow feedback. 24 skills + 15 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.36.1",
+      "version": "0.36.2",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.36.1",
+  "version": "0.36.2",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 24 skills + 15 agents, one install.",
   "source": "./",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.36.1",
+  "version": "0.36.2",
   "description": "Spec-first workflow that bridges OpenSpec-style planning and Superpowers-style execution discipline.",
   "author": {
     "name": "MageByte",

package/.cursor-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Unified workflow plugin marketplace for Cursor (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.36.1"
+    "version": "0.36.2"
   },
   "plugins": [
     {

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "team-flow",
   "displayName": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 24 skills + 15 agents, one install.",
-  "version": "0.36.1",
+  "version": "0.36.2",
   "author": {
     "name": "LT",
     "url": "https://github.com/LT"

package/.github/plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Unified workflow plugins and skills for AI coding agents (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.36.1"
+    "version": "0.36.2"
   },
   "plugins": [
     {
       "name": "team-flow",
       "description": "Unified workflow with planning artifacts, execution contracts, TDD, review gates, systematic debugging, delta spec sync, architecture-design, and local HTML prototyping.",
-      "version": "0.36.1",
+      "version": "0.36.2",
       "source": ".",
       "author": {
         "name": "LT",

package/CHANGELOG.md

@@ -6,6 +6,11 @@ The format loosely follows Keep a Changelog.
 
 ## [Unreleased]
 
+## [0.36.2] - 2026-08-05
+
+### Fixed
+- **变更级架构设计输入链缺口修复**：0.36.0 在 architecture-design/SKILL.md 声明产品级快照（`iterations/vN/architecture.md`）为主输入，但 workflow-start 实际 dispatch 子代理的输入列表（`routing-rules.md`）未传该路径——变更级架构设计不会将产品级架构设计作为输入。已同步：routing-rules.md（architecture-design + architecture-reviewer dispatch 输入）、workflow-start/SKILL.md（Step 1）、architecture-reviewer（A5 基线一致性对照产品级快照）
+
 ## [0.36.1] - 2026-08-05
 
 ### Fixed

package/GEMINI.md

@@ -8,7 +8,7 @@ The workflow is self-contained and does not require OpenSpec or Superpowers at r
 
 
 <!-- team-flow-phase-guard-start -->
-# team-flow v0.36.1 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.36.2 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。
 <!-- team-flow-phase-guard-end -->

package/INSTALL.md

@@ -7,7 +7,7 @@
 - [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) — 规划引擎（Schema 验证、Delta Spec、工件解析）
 - [obra/superpowers](https://github.com/obra/superpowers) — 执行纪律（TDD 铁律、SDD、系统化调试、代码审查）
 
-当前发布版本：**v0.36.1**。
+当前发布版本：**v0.36.2**。
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.36.1`
+> 当前版本：`v0.36.2`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
 

package/agents/architecture-reviewer.md

@@ -103,6 +103,7 @@ Dimensions requiring semantic understanding, marked as "advisory, false positive
    - Read global `ARCHITECTURE.md` → check naming conventions, BC boundaries
    - Read global `PHYSICAL-MODEL.md` → check table naming patterns, field conventions
    - Read global `API-INDEX.md` → check API routing patterns
+   - Read product snapshot `docs/architecture/iterations/<vN>/architecture.md`（若存在，v0.36.0）→ 对照产品级 BC 边界/聚合注册表（变更级增量不得与产品级决策矛盾）
    - Compare incremental design against baseline:
      - Aggregate naming conflicts with existing aggregates → Critical
      - Table naming conflicts with PHYSICAL-MODEL → Critical

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.36.1`
+- Current: `v0.36.2`
 - v0.9.1 highlights: DP-4 execution-mode recommendations, a portable runtime across 17 platforms, and a raw-package smoke with no plugin-root variable.
 - Self-contained — no OpenSpec or Superpowers runtime required
 - Upstream: [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec), [obra/superpowers](https://github.com/obra/superpowers)

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev) + compound-engineering core subset + architecture-design (4A/DDD) + prototype (local HTML). 24 skills, one install.",
-  "version": "0.36.1",
+  "version": "0.36.2",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.36.1: auto-sync CLI version with plugin version
+# v0.36.2: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.36.1"
+PLUGIN_VERSION="0.36.2"
 
 # ═══════════════════════════════════════════════════════════════
 # Step 1: Auto-sync CLI version with plugin version

package/llms.txt

@@ -3,7 +3,7 @@
 ## Overview
 spec-superflow is a self-contained workflow integration plugin for Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, and Trae. It merges spec-driven planning artifacts (proposal, specs, design, tasks) with disciplined execution guardrails (TDD, review gates, controlled handoff) into one unified workflow.
 
-Current version: v0.36.1.
+Current version: v0.36.2.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xulthekl/team-flow",
-  "version": "0.36.1",
+  "version": "0.36.2",
   "description": "Unified plugin (24 skills + 15 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback for multi-agent coding tools.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.36.1",
+  "version": "0.36.2",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 24 skills + 15 agents, one install.",
   "author": {
     "name": "LT"

package/skills/workflow-start/SKILL.md

@@ -76,7 +76,7 @@ Guard: `arch_design_decision` in `.team-flow.yaml` is `null` → must run before
 
 > **⛔ 串行约束（v0.30.0）**：四步严格串行。**修复子代理（architecture-design）完成前 MUST NOT dispatch 审查子代理（architecture-reviewer）**——并行会使审查跑在修复之前、误报"全部未修复"FAIL（来源：workflow-feedback 2026-08-01）。并行白名单：仅多个独立 change 的工作可并行；修复→审查、设计→审查必须串行。
 
-1. **Dispatch**: `architecture-design` as sub-agent → returns `decision` + `reason` + `artifacts`。**⛔ 记录子代理 ID**（后续循环修正和 DP-A 调整必须通过此 ID 恢复，禁止启动新子代理）
+1. **Dispatch**: `architecture-design` as sub-agent（**输入含 `docs/architecture/iterations/<vN>/architecture.md` 产品级架构快照**，v0.36.0——变更级只引用产品级聚合注册表，不重定义）→ returns `decision` + `reason` + `artifacts`。**⛔ 记录子代理 ID**（后续循环修正和 DP-A 调整必须通过此 ID 恢复，禁止启动新子代理）
 2. **Auto-review** (decision=required 时触发): 校验产物文件存在且非空 → dispatch `architecture-reviewer` sub-agent（**记录子代理 ID**）→ FAIL 则通过 **SendMessage 恢复原 architecture-design 子代理**修正（≤3 轮 + 收敛检测，不收敛转人工）→ 报告落盘 `changes/<name>/architecture/auto-review.md`
 3. **Reasonableness check + state write**: PASS/PASS_WITH_WARNINGS → write `arch_design_decision` + `arch_review_*` to yaml; skipped + brief 含架构关键词 → BLOCK; required + artifacts 缺失 → BLOCK; required + auto-review FAIL → BLOCK
 4. **DP-A 用户确认门（v0.29.0 §37）**: 输出架构决策摘要 → AskUserQuestion 确认 → 需要调整时**必须通过 SendMessage 恢复原子代理**修改（禁止主代理直接修改，禁止启动新子代理）→ 修改后 SendMessage 恢复原 reviewer 重新 auto-review → 回到本步骤重新确认。含项目规范变更提示（advisory）。详见 `references/routing-rules.md`「Step 4: DP-A」

package/skills/workflow-start/references/routing-rules.md

@@ -14,8 +14,9 @@ Guard: `arch_design_decision` in `.team-flow.yaml` is `null` → must run before
 Dispatch `architecture-design` as sub-agent with inputs:
 - `change-brief.md`（scope / AC / 技术方向）
 - `prd/vN/plan.md` 高阶技术设计段
+- `docs/architecture/iterations/<vN>/architecture.md`（**产品级架构快照，主输入**，v0.36.0）——BC 边界/聚合所有权/全局契约唯一事实源；vN 从 change-brief 的 `upstream_plan_ref`（prd/vN/plan.md）推导；变更级只引用不重定义（触及产品级决策 → 架构修订决策门；仅 change 内细节 → 增量设计）
 - existing `specs/`
-- global `docs/architecture/`（As-Is 基线）
+- global `docs/architecture/`（As-Is 基线 + 已落地部分）
 
 **⛔ 子代理 ID 记录（v0.29.0 §37，必须执行）**：dispatch 后**立即记录**子代理 ID（Agent 工具返回的 `agentId` 或 task-notification 中的 `task-id`），后续 Step 2 审查循环和 Step 4 DP-A 调整**必须通过此 ID 恢复子代理**，不得启动新子代理。记录格式：
 ```
@@ -41,6 +42,7 @@ artifacts:                       # required 时必填
 When `decision: required`, dispatch `architecture-reviewer` as sub-agent with inputs:
 - `prd_path`, `plan_path`, `change_brief_path`
 - `architecture_dir`（Step 1 产出目录）
+- `product_snapshot_path`（`docs/architecture/iterations/<vN>/architecture.md`，v0.36.0——A5 基线一致性对照产品级决策）
 - `global_arch_dir`（`docs/architecture/`）
 - `conventions_config`（从 `team-flow.config.json` 读取）
 

package/wave-batch-receipt-analysis-report.md

@@ -0,0 +1,561 @@
+# Wave/Batch/Receipt 实现分析报告
+
+## 1. Execution Plan 相关文件
+
+### 核心文件路径
+- `/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/scripts/lib/execution-plan.mjs`
+- `/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/scripts/lib/cmd-execution.mjs`
+- `/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/scripts/lib/execution-recommendation.mjs`
+
+### Wave 数据结构定义
+
+```javascript
+// 从 execution-plan.mjs 和测试文件中提取
+{
+  id: string,           // wave 唯一标识，如 'wave-1', 'foundation'
+  strategy: 'serial' | 'parallel',  // 执行策略
+  tasks: string[],      // 任务 ID 列表，如 ['1.1', '1.2']
+  depends_on: string[]  // 依赖的其他 wave ID 列表，如 ['wave-1', 'foundation']
+}
+```
+
+### Execution Plan 完整数据结构
+
+```javascript
+{
+  mode: 'inline' | 'batch-inline' | 'sdd',  // 执行模式（EXECUTION_MODES）
+  source: string,           // 计划来源，如 'user-confirmed', 'user-confirmed-revision'
+  rationale: string,        // 选择该模式的理由
+  waves: Wave[],            // wave 数组
+  artifacts_hash: string,   // 制品哈希（sha256:...）
+  contract_hash: string,    // 契约哈希（sha256:...）
+  workflow: string,         // 工作流类型：'full' | 'hotfix' | 'tweak'
+  revision: number,         // 修订版本号
+  hash: string,             // 计划内容哈希（sha256:...）
+  recommendation?: {        // 推荐信息（full/hotfix 必需）
+    available_modes: string[],
+    recommendation: {
+      mode: string,
+      reasons: string[]
+    },
+    facts: object
+  },
+  recommendation_receipt?: {  // 推荐凭证（full/hotfix 必需）
+    recommendation: object,
+    waves: Wave[],
+    artifacts_hash: string,
+    contract_hash: string,
+    workflow: string,
+    execution_plan_revision_at_recommendation: number | null,
+    created_at: string,
+    hash: string
+  },
+  selection?: {             // 用户选择信息（full/hotfix 必需）
+    confirmed: boolean,
+    followed_recommendation: boolean,
+    acknowledged_non_recommendation: boolean
+  }
+}
+```
+
+### 关键代码片段
+
+**创建计划 (execution-plan.mjs:14-33)**
+```javascript
+export function createPlan(changeDir, input) {
+  const state = readState(changeDir);
+  const plan = {
+    mode: input?.mode,
+    source: input?.source,
+    rationale: input?.rationale,
+    waves: input?.waves,
+    artifacts_hash: computeArtifactsHash(changeDir),
+    contract_hash: computeContractHash(changeDir),
+    workflow: state.workflow,
+    revision: input?.revision ?? state.revision ?? 1,
+  };
+  // ... validation and hash computation
+}
+```
+
+**Wave 解析 (cmd-execution.mjs:163-178)**
+```javascript
+function parseWaves(values) {
+  // 格式: <id>:<strategy>:<task,...>[:<depends-on,...>]
+  // 示例: 'wave-1:parallel:1.1,1.2' 或 'wave-2:serial:2.1:wave-1'
+  return values.map(value => {
+    const [id, strategy, taskList, dependencyList, ...extra] = value.split(':');
+    const tasks = taskList.split(',').map(task => task.trim()).filter(Boolean);
+    const depends_on = dependencyList === undefined ? [] : dependencyList.split(',').map(id => id.trim()).filter(Boolean);
+    return { id, strategy, tasks, depends_on };
+  });
+}
+```
+
+---
+
+## 2. Receipt 相关实现
+
+### 核心文件路径
+- `/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/scripts/lib/execution-plan.mjs` (recordReview, readCurrentReview)
+- `/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/scripts/guard/checks/execution-reviews-passed.mjs`
+
+### Review Receipt 数据结构
+
+```javascript
+{
+  status: 'pass' | 'fail',  // 审查状态
+  base: string,             // git base commit hash（完整 SHA）
+  head: string,             // git head commit hash（完整 SHA）
+  report: string,           // 审查报告文件路径（相对于 change 目录）
+  tests?: {                 // 可选的测试统计（v0.13 §51.2）
+    total: number,          // 测试总数
+    passed: number,         // 通过数
+    failed: number          // 失败数
+  },
+  plan_hash: string,        // 关联的执行计划哈希
+  plan_revision: number,    // 关联的执行计划修订版本
+  recorded_at: string       // 记录时间（ISO 格式）
+}
+```
+
+### Receipt 存储位置
+```
+<change-dir>/.superpowers/sdd/reviews/<base64url-encoded-wave-id>.json
+```
+
+### Receipt 校验逻辑 (execution-plan.mjs:133-177)
+
+```javascript
+export function recordReview(changeDir, waveId, receipt) {
+  // 1. 验证计划有效性
+  const plan = readPlan(changeDir);
+  const validation = validatePlan(changeDir, plan);
+  if (!validation.valid) throw new Error(...);
+
+  // 2. 验证 wave 是否存在于计划中
+  const wave = plan.waves.find(candidate => candidate?.id === waveId);
+  if (!wave) throw new Error(`Review receipt references unknown wave '${waveId}'`);
+
+  // 3. 检查依赖是否已通过（阻塞依赖检查）
+  const blockedBy = blockedDependencies(changeDir, plan, wave);
+  if (blockedBy.length > 0) {
+    throw new Error(`Wave '${waveId}' cannot be reviewed before dependencies have passing receipts: ${blockedBy.join(', ')}`);
+  }
+
+  // 4. 验证 status
+  if (!REVIEW_STATUSES.has(receipt?.status)) {
+    throw new Error("Review receipt status must be 'pass' or 'fail'");
+  }
+
+  // 5. 验证 base 和 head
+  for (const field of ['base', 'head']) requireText(receipt?.[field], `receipt.${field}`);
+
+  // 6. 验证 report 文件
+  const report = validateReviewReportEvidence(changeDir, receipt?.report);
+
+  // 7. 验证 git 范围（禁止空 diff）
+  const { base, head } = validateReviewRange(changeDir, receipt.base, receipt.head);
+  // 关键校验：base !== head（禁止 base==head 空 diff review）
+  if (resolvedBase === resolvedHead) {
+    throw new Error('Review receipt base must differ from head...');
+  }
+
+  // 8. 验证 base 是 head 的祖先
+  execFileSync('git', ['-C', gitRoot, 'merge-base', '--is-ancestor', resolvedBase, resolvedHead]);
+
+  // 9. 保存 receipt
+  const savedReceipt = {
+    status: receipt.status,
+    base, head, report,
+    ...(tests ? { tests } : {}),
+    plan_hash: plan.hash,
+    plan_revision: plan.revision,
+    recorded_at: new Date().toISOString(),
+  };
+  atomicWrite(join(paths.reviews, `${safeFileName(waveId)}.json`), JSON.stringify(savedReceipt));
+}
+```
+
+### 读取当前 Receipt (execution-plan.mjs:183-200)
+
+```javascript
+export function readCurrentReview(changeDir, waveId, plan = readPlan(changeDir)) {
+  // 1. 检查 receipt 文件是否存在
+  // 2. 验证 plan_hash 和 plan_revision 匹配当前计划
+  // 3. 验证 base/head 范围仍然有效
+  // 4. 对于 passing receipt，验证 report 文件仍然安全可读
+  if (receipt?.status === 'pass') validateReviewReportEvidence(changeDir, receipt.report);
+  return receipt;
+}
+```
+
+---
+
+## 3. state-loader.mjs 中的字段
+
+### 核心文件路径
+- `/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/scripts/lib/state-loader.mjs`
+
+### BUILTIN_DEFAULTS 中的相关字段
+
+```javascript
+const BUILTIN_DEFAULTS = {
+  // 核心状态
+  state: 'exploring',
+  workflow: 'auto',
+  revision: null,
+
+  // 哈希校验
+  artifacts_hash: null,
+  contract_hash: null,
+
+  // 执行进度（与 wave/batch/execution 相关）
+  execution_mode: null,           // 执行模式：'inline' | 'batch-inline' | 'sdd'
+  execution_plan_hash: null,      // 执行计划哈希
+  execution_plan_revision: null,  // 执行计划修订版本
+  batches_completed: 0,           // 已完成的批次数量
+  test_result: null,              // 测试结果
+  spec_merged: false,             // 规格是否已合并
+
+  // 其他字段...
+};
+```
+
+### 关键代码片段
+
+**写入状态 (state-loader.mjs:92-188)**
+```javascript
+export function writeState(changeDir, state) {
+  // 序列化到 .team-flow.yaml
+  lines.push('# === Execution progress ===');
+  lines.push(`execution_mode: ${state.execution_mode ?? 'null'}`);
+  lines.push(`execution_plan_hash: ${state.execution_plan_hash ?? 'null'}`);
+  lines.push(`execution_plan_revision: ${state.execution_plan_revision ?? 'null'}`);
+  lines.push(`batches_completed: ${state.batches_completed ?? 0}`);
+  lines.push(`test_result: ${state.test_result ?? 'null'}`);
+  lines.push(`spec_merged: ${state.spec_merged ?? false}`);
+}
+```
+
+---
+
+## 4. guard.mjs 中的 Wave 门控逻辑
+
+### 核心文件路径
+- `/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/scripts/guard/guard.mjs`
+- `/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/scripts/guard/checks/execution-plan-ready.mjs`
+- `/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/scripts/guard/checks/execution-reviews-passed.mjs`
+
+### 门控转换矩阵
+
+```javascript
+// guard.mjs 中定义的转换检查维度
+const TRANSITION_CHECKS = {
+  'approved-for-build:executing': [
+    'artifacts-exist',
+    'contract-fresh',
+    'dp-gate-passed',
+    'execution-plan-ready',    // ★ 执行计划就绪检查
+    'test-matrix-ready'
+  ],
+  'executing:closing': [
+    'tasks-complete',
+    'tests-passing',
+    'specs-merged',
+    'execution-plan-ready',    // ★ 执行计划就绪检查
+    'execution-reviews-passed', // ★ 所有 wave receipt 通过检查
+    'compound-captured',
+    'test-matrix-complete',
+    'arch-snapshot'
+  ],
+  'debugging:executing': [
+    'contract-fresh',
+    'execution-plan-ready'     // ★ 从 debugging 返回时也检查
+  ],
+};
+
+// Workflow 特定检查
+const WORKFLOW_TRANSITION_CHECKS = {
+  hotfix: {
+    'approved-for-build:executing': ['contract-current', 'dp3-approved', 'execution-plan-ready'],
+    'executing:closing': ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured'],
+  },
+  tweak: {
+    // Tweak 豁免 execution-plan 和 review receipt 检查
+    'approved-for-build:executing': ['artifacts-exist', 'contract-fresh', 'dp-gate-passed'],
+    'executing:closing': ['tasks-complete', 'tests-passing', 'specs-merged'],
+  },
+};
+```
+
+### execution-plan-ready 检查逻辑 (execution-plan-ready.mjs)
+
+```javascript
+export function checkExecutionPlanReady(changeDir) {
+  // 1. 检查执行计划是否存在
+  const plan = readPlan(changeDir);
+  if (!plan) {
+    return { pass: false, failures: ['execution plan is missing...'] };
+  }
+
+  // 2. 验证计划有效性
+  const validation = validatePlan(changeDir, plan);
+  if (!validation.valid) {
+    return { pass: false, failures: validation.failures };
+  }
+
+  // 3. 验证 DP-4 引用了当前计划修订版本
+  const state = readState(changeDir);
+  const revisionReference = new RegExp(`\\bplan revision\\s+${plan.revision}\\b`, 'i');
+  if (!revisionReference.test(decision)) {
+    return { pass: false, failures: [`DP-4 must precisely reference current plan revision...`] };
+  }
+
+  return { pass: true, failures: [] };
+}
+```
+
+### execution-reviews-passed 检查逻辑 (execution-reviews-passed.mjs)
+
+```javascript
+export function checkExecutionReviewsPassed(changeDir) {
+  // 1. 读取执行计划
+  const plan = readPlan(changeDir);
+  if (!plan) return { pass: true, failures: [] }; // tweak 豁免
+
+  // 2. 验证计划有效性
+  const validation = validatePlan(changeDir, plan);
+  if (!validation.valid) return { pass: false, failures: validation.failures };
+
+  // 3. 遍历所有 wave，检查 receipt
+  const failures = [];
+  for (const wave of plan.waves) {
+    const receipt = readCurrentReview(changeDir, wave.id, plan);
+    if (!receipt) {
+      failures.push(`review receipt missing for planned wave '${wave.id}'`);
+      continue;
+    }
+    if (receipt?.status !== 'pass') {
+      failures.push(`review receipt for planned wave '${wave.id}' has status '${receipt?.status}'`);
+    }
+  }
+
+  return { pass: failures.length === 0, failures };
+}
+```
+
+---
+
+## 5. depends_on 和拓扑相关实现
+
+### 核心文件路径
+- `/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/scripts/lib/execution-plan.mjs`
+
+### 依赖验证逻辑 (execution-plan.mjs:381-433)
+
+```javascript
+function validateStructure(plan) {
+  // ...
+
+  // 验证每个 wave 的 depends_on
+  for (const [index, wave] of plan.waves.entries()) {
+    // 1. depends_on 必须是数组
+    if (!Array.isArray(wave.depends_on)) failures.push(`${label} depends_on must be an array`);
+
+    // 2. 依赖项必须是非空字符串
+    else if (wave.depends_on.some(id => !isNonEmptyText(id))) failures.push(`${label} dependencies must be non-empty strings`);
+  }
+
+  // 3. 验证依赖引用的有效性
+  for (const wave of plan.waves.filter(isObject)) {
+    for (const dependency of wave.depends_on) {
+      // 不能自依赖
+      if (dependency === wave.id) failures.push(`wave '${wave.id}' cannot depend on itself`);
+      // 不能依赖不存在的 wave
+      else if (!ids.has(dependency)) failures.push(`wave '${wave.id}' depends on unknown wave '${dependency}'`);
+    }
+  }
+
+  // 4. 检测循环依赖
+  if (canCheckCycles && hasDependencyCycle(plan.waves)) {
+    failures.push('execution plan waves contain a dependency cycle');
+  }
+}
+```
+
+### 循环依赖检测算法 (execution-plan.mjs:436-452)
+
+```javascript
+function hasDependencyCycle(waves) {
+  // 使用 DFS 检测有向图中的环
+  const dependencies = new Map(waves.map(wave => [wave.id, wave.depends_on]));
+  const visiting = new Set();  // 当前正在访问的节点（用于检测后向边）
+  const visited = new Set();   // 已完成访问的节点
+
+  const visit = id => {
+    if (visiting.has(id)) return true;   // 发现环！
+    if (visited.has(id)) return false;   // 已经检查过，无环
+    visiting.add(id);
+    for (const dependency of dependencies.get(id) || []) {
+      if (visit(dependency)) return true;
+    }
+    visiting.delete(id);
+    visited.add(id);
+    return false;
+  };
+
+  return [...dependencies.keys()].some(visit);
+}
+```
+
+### 阻塞依赖检查 (execution-plan.mjs:324-327)
+
+```javascript
+function blockedDependencies(changeDir, plan, wave) {
+  if (!Array.isArray(wave?.depends_on)) return [];
+  // 返回所有未通过的依赖 wave
+  return wave.depends_on.filter(dependency =>
+    readCurrentReview(changeDir, dependency, plan)?.status !== 'pass'
+  );
+}
+```
+
+### Wave 可执行性判断 (execution-plan.mjs:207-224)
+
+```javascript
+export function describeWaves(changeDir, plan = readPlan(changeDir)) {
+  return plan.waves.map(wave => {
+    const receipt = readCurrentReview(changeDir, wave.id, plan);
+    const blockers = blockedDependencies(changeDir, plan, wave);
+    const retryable = receipt?.status === 'fail';
+    return {
+      id: wave.id,
+      strategy: wave.strategy,
+      tasks: wave.tasks,
+      depends_on: wave.depends_on,
+      eligible: (receipt === null || retryable) && blockers.length === 0,  // 可执行条件
+      retryable,
+      receipt,
+      blockers,
+    };
+  });
+}
+```
+
+---
+
+## 6. 测试文件中的示例
+
+### 核心测试文件路径
+- `/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/tests/lib/execution-plan.test.mjs`
+- `/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/tests/lib/guard.test.mjs`
+
+### Wave 定义示例
+
+```javascript
+// 单 wave，无依赖
+waves: [{ id: 'wave-1', strategy: 'serial', tasks: ['1.1'], depends_on: [] }]
+
+// 多 wave，有依赖
+waves: [
+  { id: 'wave-1', strategy: 'parallel', tasks: ['1.1', '1.2'], depends_on: [] },
+  { id: 'wave-2', strategy: 'serial', tasks: ['2.1'], depends_on: ['wave-1'] }
+]
+
+// 循环依赖（会被拒绝）
+waves: [
+  { id: 'wave-1', strategy: 'serial', tasks: ['1.1'], depends_on: ['wave-2'] },
+  { id: 'wave-2', strategy: 'serial', tasks: ['1.2'], depends_on: ['wave-1'] }
+]
+
+// 自依赖（会被拒绝）
+waves: [{ id: 'wave-1', strategy: 'parallel', tasks: ['1.1'], depends_on: ['wave-1'] }]
+
+// 依赖不存在的 wave（会被拒绝）
+waves: [{ id: 'wave-1', strategy: 'parallel', tasks: ['1.1'], depends_on: ['missing'] }]
+```
+
+### Receipt 记录示例
+
+```javascript
+// 记录通过的 receipt
+const receipt = recordReview(changeDir, 'wave-1', {
+  status: 'pass',
+  base: gitRefs.base,    // git base commit
+  head: gitRefs.head,    // git head commit
+  report: reportPath,    // 审查报告路径
+  tests: {               // 可选测试统计
+    total: 12,
+    passed: 11,
+    failed: 1
+  }
+});
+
+// 记录失败的 receipt
+const receipt = recordReview(changeDir, 'wave-2', {
+  status: 'fail',
+  base: gitRefs.base,
+  head: gitRefs.head,
+  report: reportPath
+});
+```
+
+### Guard 测试示例
+
+```javascript
+// 测试：所有 wave 必须有 passing receipt 才能 closing
+it('blocks closing until every planned wave has a passing review receipt', () => {
+  // 1. 创建计划（wave-1 和 wave-2）
+  createCurrentPlan();
+
+  // 2. 尝试 closing，应该失败（没有 receipt）
+  let result = run('executing', 'closing');
+  assert.equal(result.exitCode, 1);
+  assert.match(reviewCheck.failures.join('\n'), /wave-1|receipt/i);
+
+  // 3. 记录 wave-1 passing，wave-2 failing
+  runNodeScript(CLI_PATH, ['execution', 'review', dir, '--wave', 'wave-1', ...]);
+  runNodeScript(CLI_PATH, ['execution', 'review', dir, '--wave', 'wave-2', ..., '--verdict', 'fail']);
+
+  // 4. 尝试 closing，应该失败（wave-2 failing）
+  result = run('executing', 'closing');
+  assert.match(reviewCheck.failures.join('\n'), /wave-2.*fail/i);
+
+  // 5. 修复 wave-2 为 passing
+  runNodeScript(CLI_PATH, ['execution', 'review', dir, '--wave', 'wave-2', ..., '--verdict', 'pass']);
+
+  // 6. 尝试 closing，应该成功
+  result = run('executing', 'closing');
+  assert.equal(result.exitCode, 0);
+});
+```
+
+---
+
+## 7. 关键设计要点总结
+
+### Wave 设计
+1. **Wave 是执行计划的基本单位**，每个 wave 包含一组任务和执行策略
+2. **策略类型**：`serial`（顺序执行）和 `parallel`（并行执行）
+3. **依赖关系**：通过 `depends_on` 字段定义 wave 之间的依赖
+4. **拓扑约束**：禁止自依赖、禁止依赖不存在的 wave、禁止循环依赖
+
+### Receipt 设计
+1. **Receipt 是 wave 级别的审查证据**，记录在 `.superpowers/sdd/reviews/` 目录
+2. **必须包含**：status、base、head、report
+3. **可选包含**：tests（测试统计）
+4. **关联性**：receipt 通过 plan_hash 和 plan_revision 关联到特定的执行计划版本
+5. **有效性**：receipt 在计划变更后自动失效（hash 不匹配）
+
+### 门控设计
+1. **execution-plan-ready**：在进入 executing 和 closing 时检查
+2. **execution-reviews-passed**：在 closing 时检查，要求所有 wave 都有 passing receipt
+3. **依赖阻塞**：wave 的 receipt 记录依赖其所有 depends_on wave 的 receipt 先通过
+4. **Workflow 豁免**：tweak workflow 豁免 execution-plan 和 review receipt 检查
+
+### 状态持久化
+1. **execution_mode**：记录选择的执行模式
+2. **execution_plan_hash**：记录当前执行计划的哈希
+3. **execution_plan_revision**：记录当前执行计划的修订版本
+4. **batches_completed**：记录已完成的批次数量