@xulthekl/team-flow 0.36.0 → 0.36.2

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

@@ -1,3 +1,3 @@
-# team-flow v0.36.0 | 阶段: {{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.0",
+      "version": "0.36.2",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.36.0",
+  "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.0",
+  "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.0"
+    "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.0",
+  "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.0"
+    "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.0",
+      "version": "0.36.2",
       "source": ".",
       "author": {
         "name": "LT",

package/AGENTS.md

@@ -60,7 +60,7 @@ spec 驱动开发过程。8 态变更机：`exploring → specifying → bridgin
 - 用法：`/e2e [原型|集成|验收] [spec路径]`
 
 ### 6. workflow-orchestrator（1 skill，产品级编排，v0.7 重设计 + v0.15.0 多需求）
-- 编排产品级工作流：S1 路径路由（含需求选择）→ S2 PRD+原型（循环上提，orchestrator 直接编排，**冻结前 PRD 完整性评审**）→ S3 ce-plan（pipeline 快速路径，**入口问定 plan_mode**）→ S4 拆分验证+分发 → S5 全局监控
+- 编排产品级工作流：S1 路径路由（含需求选择）→ S2 PRD+原型（循环上提，orchestrator 直接编排，**冻结前 PRD 完整性评审**）→ S3 ce-plan（pipeline 快速路径，**入口问定 plan_mode**）→ **ARCH 产品级架构设计（v0.36.0：architecture-design product 模式 8 步 → iterations/vN/architecture.md 快照 → 评审门 PASS 才进 S4）** → S4 拆分验证+分发 → S5 全局监控
 - v0.7 关键变更：原型循环从 ce-brainstorm 内部上提到 orchestrator 层直接编排；新增反馈环路（vN 内修订+变更履历，非升版）；新增增量入口（S1 路径路由器，**7 种入口路径**，v0.20.0 增「原型补跑/重跑」）；S5 多 change 并行时必选
 - **v0.20.0**：S1 路由新增第 7 种入口「原型补跑/重跑」（PRD 冻结 ∧ prototype 缺失/需重做 → 部分重入 S2 原型循环，PRD 不动、保留有效 S3/S4）；后台子代理等待范式（依赖完成通知，禁 TaskOutput 轮询）（设计 §22）
 - **v0.15.0 多需求并行**：`.team-flow/registry.yaml` 注册表 + 每需求一份 `.team-flow/requirements/<req-id>/orchestrator.yaml`，状态天然隔离
@@ -136,7 +136,10 @@ STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
   S3 计划阶段 → ce-plan（pipeline 快速路径，入口问定 plan_mode）
      plan.md：change 拆分 + 依赖 DAG + 高阶技术方向（不含接口清单）
      反馈环路：plan 暴露 PRD 问题可回退 S2
-  S4 拆分验证与分发 → change-split-auditor 审计（必选门禁）→ 创建 change → 进入 team-flow
+  [ARCH 产品级架构设计（v0.36.0）] → architecture-design product 模式 8 步设计
+     → docs/architecture/iterations/vN/architecture.md（6 产物快照，预测态不写全局）→ 评审门 PASS 才进 S4
+     skip 须物化（iterations/vN/SKIPPED）；旧项目首轮 arch_baseline 缺失 → 逆向重建
+  S4 拆分验证与分发 → arch-readiness 门（快照覆盖 change 触及 BC）→ change-split-auditor 审计（必选门禁）→ 创建 change → 进入 team-flow
      并行策略建议 + 验收标准预分配；反馈环路：依赖图不可执行可回退 S3
   S5 全局监控（change≥2 必选）→ 跨 change 一致性 + 复利晋升 + 动态重规划
   │

package/CHANGELOG.md

@@ -6,6 +6,16 @@ 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
+- **workflow-orchestrator 流程缺口修复**：0.36.0 的 `references/state-model.md` 已定义 ARCH（S3.5 产品级架构设计）阶段，但 SKILL.md 主体 Execution Flow（S1-S5）/ AGENTS.md / README 未同步该阶段——LLM 执行 orchestrator 会走 S3→S4 跳过架构设计。已同步 11 处：SKILL.md（定位表/Execution Flow 标题/ARCH 阶段节/反馈环路/增量入口/状态模型/Guardrails/Output Standard）+ AGENTS.md（产品级工作流/SOP）+ README（SOP）
+
 ## [0.36.0] - 2026-08-05
 
 ### Added（产品级架构设计增强——设计增强方案 v0.14 §57-§66）

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.0 | 阶段: {{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.0**。
+当前发布版本：**v0.36.2**。
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.36.0`
+> 当前版本：`v0.36.2`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
 
@@ -108,7 +108,8 @@ Skills 命名保留其来源前缀，作为功能分组的自然标识：
   → S1 路径路由器 → 判断入口路径（全新/续版/重新计划/继续执行/快速通道/Hotfix）
   → S2 PRD + 原型阶段 → ce-brainstorm + 原型循环上提（prototype → 自动评审 → 人工评审 → 冻结）
   → S3 计划阶段 → ce-plan（pipeline 快速路径）→ plan.md（change 拆分+依赖+技术方向）
-  → S4 拆分验证与分发 → change-split-auditor 审计（必选门禁）→ 创建 change → 进入 team-flow
+  → [ARCH 产品级架构设计（v0.36.0 新增）] → 8 步设计 → iterations/vN/architecture.md 快照 → 评审门
+  → S4 拆分验证与分发 → arch-readiness 门 → change-split-auditor 审计（必选门禁）→ 创建 change → 进入 team-flow
   → S5 全局监控（change≥2 必选）→ 跨 change 一致性 + 复利晋升 + 动态重规划
   → [复利贯穿层] 每个阶段转换点：检测→捕获→索引→注入
   → change 完成：arch-merge → prototype-sync（顺序提交）+ 复利晋升

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.0`
+- 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.0",
+  "version": "0.36.2",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.36.0: 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.0"
+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.0.
+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.0",
+  "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.0",
+  "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-orchestrator/SKILL.md

@@ -16,7 +16,7 @@ description: >-
 
 | 层级 | 编排器 | 管辖范围 |
 |------|--------|---------|
-| 产品级 | **workflow-orchestrator**（本 skill） | 路径路由 → PRD+原型循环 → 计划 → 拆分验证 → 分发 → 监控 |
+| 产品级 | **workflow-orchestrator**（本 skill） | 路径路由 → PRD+原型循环 → 计划 → **架构设计（ARCH，v0.36.0）** → 拆分验证 → 分发 → 监控 |
 | 变更级 | workflow-start（不变） | exploring → ... → closing（8 态状态机） |
 
 **分层原则**：本 skill 管「做什么、什么顺序」（产品级策略），workflow-start 管「怎么做」（变更级执行）。二者通过 change 目录 + `.team-flow.yaml` 衔接。
@@ -34,7 +34,7 @@ Do NOT invoke for:
 - 单一 change 的实施（用 `/build-executor`）
 - 独立工具操作（`/ce-ideate`、`/ce-strategy`、`/prototype`、`/architecture-design` 等）
 
-## Execution Flow（S1-S5）
+## Execution Flow（S1-S5 + ARCH 产品级架构设计）
 
 ### S1: 路径路由器
 **先做需求选择**（v0.15.0 多需求）：读 `.team-flow/registry.yaml`，确定 `active_requirement`（多需求则询问操作哪个/新建）。再判断 7 种入口路径之一；检查 baseline.md / CONCEPTS.md 并注入；复利注入（INDEX.md top-5）。**路由结果必须向用户显式确认**（路由是建议非决定）。详见 `references/s1-path-router.md`。
@@ -69,7 +69,21 @@ prd_draft → user_review → prototype_loop → prd_frozen → completed
 调用 `/ce-brainstorm`（mode: orchestrated）产出 PRD 草稿；**冻结前派 `prd-completeness-reviewer` 子代理做 PRD 完整性评审**（v0.15.0，管"说得全不全"）；原型循环由编排层直接编排（prototype skill 内部编排产出 → prototype-reviewer 自动评审 → 人工评审 → 冻结）；冻结语义为 `frozen_downstream`（迭代内变更不升版）。反馈环路检查点：scope 是否合理。详见 `references/s2-prd-prototype-loop.md`。
 
 ### S3: 计划阶段
-**入口一次性问定计划模式**（业务/一人公司），调用 `/ce-plan`（`pipeline_mode: orchestrator` + `plan_mode: business|solo`，跳过仪式开销、保留 repo research + change splitting + 依赖 DAG + 技术方向）产出 `prd/vN/plan.md`。plan 只到产品级策略 + 高阶技术设计，**不含接口清单**（属各 change 的 spec-writer）。反馈环路检查点：plan 是否暴露 PRD scope 问题（是→回退 S2）。详见 `references/s3-plan-pipeline.md`。
+**入口一次性问定计划模式**（业务/一人公司），调用 `/ce-plan`（`pipeline_mode: orchestrator` + `plan_mode: business|solo`，跳过仪式开销、保留 repo research + change splitting + 依赖 DAG + 技术方向）产出 `prd/vN/plan.md`。plan 只到产品级策略 + 高阶技术设计，**不含接口清单**（属各 change 的 spec-writer）。反馈环路检查点：plan 是否暴露 PRD scope 问题（是→回退 S2）。详见 `references/s3-plan-pipeline.md`。完成条件：plan.md 产出 + S3 状态 = completed，**下一步进 ARCH**（v0.36.0）。
+
+### ARCH: 产品级架构设计（v0.36.0 新增，S3 之后、S4 之前）
+
+**⛔ MANDATORY：执行 ARCH 阶段前，必须先读取 `references/state-model.md`「architecture 阶段」+ `architecture-design/references/s3.5-product-architecture.md`**
+
+产品级架构设计：基于迭代版本 vN 产出覆盖所有模块的整体详细架构（预测态快照，P1：只写快照不写全局）。
+
+**场景判定（入口三态）**：全新项目 → 正向设计（首轮不可跳过）；旧项目首轮（`arch_baseline` 缺失）→ 逆向重建 L0 骨架 → 渐进深化；已建档 + 迭代无结构性变更 → 跳过（**skip 必须物化**：写 `docs/architecture/iterations/vN/SKIPPED` 标记 + 理由，判定者=编排器+用户确认）。
+
+**执行**：调用 architecture-design skill 的 **product 模式**子代理（8 步设计：限界上下文/聚合注册表/指令事件/状态机/概念 ER/时序），产出 `docs/architecture/iterations/vN/architecture.md`（6 产物，provenance 标注）。
+
+**评审门**：产出经 architecture-reviewer product 视角（`review_mode: product`，A1-A6）评审，**PASS 才进 S4**。
+
+**输出契约**：`docs/architecture/iterations/vN/architecture.md` + 评审 verdict；`orchestrator.yaml` 中 ARCH phase 状态 = completed（`workflow_phase: architecture`）。
 
 ### S4: 拆分验证与分发
 
@@ -145,6 +159,8 @@ plan_hash: sha256:<plan.md 内容摘要>    # 检测产品层改动后变更层
 ## 反馈环路（保守策略：只允许相邻回退）
 
 - **S3 → S2**：plan 暴露 PRD scope 问题 → PRD vN 内修订（非升版）+ 变更履历，plan.md 归档为 .revN
+- **ARCH → S3**（v0.36.0）：架构设计暴露 plan 拆分问题 → 调整拆分策略，plan.md 归档为 .revN
+- **S4 → ARCH**（v0.36.0）：架构快照不覆盖 change 触及的 BC / 架构产物缺失 → 回 ARCH 补快照，change 拆分保留
 - **S4 → S3**：依赖图不可执行/粒度不合理 → 调整拆分策略，已建 change 目录保留增量调整
 - **S5 → S4**：跨 change 冲突需重新拆分 → 按在途 change 红/绿/灰区处置
 
@@ -156,15 +172,15 @@ plan_hash: sha256:<plan.md 内容摘要>    # 检测产品层改动后变更层
 |------|------|------|
 | 全新需求 | 无 PRD，需求模糊 | → S2 |
 | 续版需求 | 有 PRD vN，要加功能 | → S2（vN+1） |
-| 重新计划 | PRD 已冻结，plan 需调整 | → S3 |
-| 继续执行 | changes 已拆分，继续下一个 | → S4/S5（先输出状态恢复简报） |
+| 重新计划 | PRD 已冻结，plan 需调整 | → S3（完成后进 ARCH，v0.36.0） |
+| 继续执行 | changes 已拆分，继续下一个 | → S4/S5（先输出状态恢复简报；若 `workflow_phase: architecture` 则恢复 ARCH 阶段） |
 | 单 change 快速通道 | 需求极清晰、无 UI、无跨模块依赖的极小变更 | → 直接建 change → workflow-start |
 | 紧急修复（Hotfix） | bug/生产问题，最小范围修复 | → 建 change（type: hotfix）→ workflow-start |
 | **原型补跑/重跑**（v0.20.0） | PRD 已冻结（`frozen_downstream`）∧ `prototype/` 缺失/为空，或用户显式要求重做原型 | → 部分重入 S2 原型循环（S2 步骤 2→3→4）；PRD 不动，保留有效 S3/S4，闭环后恢复原 phase |
 
 ## 状态模型
 
-**多需求并行（v0.15.0）**：`.team-flow/registry.yaml`（需求注册表 + `active_requirement` 活跃指针）+ 每需求一份 `.team-flow/requirements/<req-id>/orchestrator.yaml`（持久化记忆 / checkpointer）。各需求状态天然隔离，支持并行。单需求 orchestrator.yaml 含 requirement_id / workflow_phase / phases / replan_log / change_dag / prd_version。双层冻结（frozen_downstream / frozen_absolute），frozen 以 PRD frontmatter 为单一真相源。迁移兼容：检测旧 `<root>/.workflow-orchestrator.yaml` 自动迁入。动态重规划（三级意图分类器 + 红/绿/灰区 + DP-R 确认）见 `references/state-model.md`。
+**多需求并行（v0.15.0）**：`.team-flow/registry.yaml`（需求注册表 + `active_requirement` 活跃指针）+ 每需求一份 `.team-flow/requirements/<req-id>/orchestrator.yaml`（持久化记忆 / checkpointer）。各需求状态天然隔离，支持并行。单需求 orchestrator.yaml 含 requirement_id / workflow_phase / phases / replan_log / change_dag / prd_version。**v0.36.0：phases 增加 ARCH（产品级架构设计）阶段，`workflow_phase: architecture`**；项目级架构基线状态存 `.team-flow/arch-state.json`（`arch_baseline`，`tf arch init` 打戳，缺失 = 存量 → arch 门禁 WARN 不 FAIL）。双层冻结（frozen_downstream / frozen_absolute），frozen 以 PRD frontmatter 为单一真相源。迁移兼容：检测旧 `<root>/.workflow-orchestrator.yaml` 自动迁入。动态重规划（三级意图分类器 + 红/绿/灰区 + DP-R 确认）见 `references/state-model.md`。
 
 ## Guardrails
 
@@ -173,6 +189,7 @@ plan_hash: sha256:<plan.md 内容摘要>    # 检测产品层改动后变更层
 - **后台子代理等待范式（v0.20.0）**：派发后台子代理（prototype-builder / reviewer / architecture-design 等长任务）后**依赖完成通知（`<task-notification>`）再行动**，**禁止反复 `TaskOutput(block=true)` 阻塞轮询**——其对长任务超时返回会倾泻完整子代理 transcript，撑爆主上下文、抵消"只编排"的轻上下文优势。长任务派发后可先处理可并行工作或结束本轮等待通知，**不空转死等**；确需中途观察用 `block=false` 轻量查询（仍返转录，尽量不用）。（设计 §22.2）
 - **不跳过 PRD 冻结**：PRD 必须经原型循环（或显式跳过）后才能进 ce-plan
 - **不跳过拆分审计**：change-split-auditor 审计 verdict = PASS 是创建 change 脚手架的前置条件（S4 必选门禁）
+- **架构门禁（v0.36.0）**：ARCH 阶段 skip 必须物化（`iterations/vN/SKIPPED` + 理由）；arch-readiness（S4 拆分：快照覆盖 change 触及 BC）与 arch-snapshot（change closing）为 guard 门禁，`arch_baseline` 缺失 → WARN 不 FAIL（存量豁免）
 - **路由是建议非决定**：S1 路由判断必须用户确认；重规划必须 DP-R 阻塞确认
 - **回退必写 replan_log**：active → pending 回退必须记录；受影响制品归档为 .revN，重入不读旧制品
 - **不阻断流程**：所有复利操作为 advisory 级，INDEX.md 读取失败时静默跳过
@@ -181,7 +198,7 @@ plan_hash: sha256:<plan.md 内容摘要>    # 检测产品层改动后变更层
 ## Output Standard
 
 每次交互结束时说明：
-1. 当前所处阶段（S1-S5）与 `.team-flow/requirements/<req-id>/orchestrator.yaml` 状态
+1. 当前所处阶段（S1-S5 / ARCH）与 `.team-flow/requirements/<req-id>/orchestrator.yaml` 状态
 2. 已产出的制品（PRD/原型/plan/changes）
 3. 下一步建议（调用哪个 skill / 进入哪个 change）
 

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**：记录已完成的批次数量