@xulthekl/team-flow 0.22.4

package/skills/architecture-design/chapters/ch03-architecture-outputs.md

@@ -0,0 +1,25 @@
+# ch03 · 架构产出三层 + 治理三支柱
+
+## 架构产出三层（管理从元素层抓起）
+乐高类比：元素=积木、制品=图纸、交付件=成品。
+| 层 | 定位 | 例子 | 4A 映射 |
+|---|---|---|---|
+| 元素 | 最小构建单元 | 活动/数据实体/功能/技术服务 | 跨四域的一等元素 |
+| 制品 | 元素按规则组合 | 流程图/数据模型/架构蓝图 | Context Map、CQRS 模型 |
+| 交付件 | 面向受众的完整输出 | 评审报告/选型书 | 系统架构设计文档 |
+
+- 元素是"积木"，制品是"图纸"（一份功能规格说明书引用多个功能元素，但功能元素≠制品）。
+- 治理从**标准化元素层**抓起：建立命名注册表，避免语义漂移。
+
+## 治理三支柱（保障非束缚）
+| 支柱 | 类比 | 核心机制 |
+|---|---|---|
+| 生命周期管理 | 红绿灯 | 资产六态：草稿→评审中→已发布→已退役→已归档→已废弃 |
+| 审批流程 | 驾照考试 | 影响分析→方案评审→批准发布（三步才进"已发布"） |
+| 成熟度评估 | 年检 | 五级：初始→可重复→已定义→已管理→优化；维度=覆盖率/一致性达标率/变更响应速度 |
+
+> 三支柱缺一不可：只红绿灯无驾照=乱；只驾照无年检=坏；只年检无红绿灯=瘫。
+
+## 应用提示（一人创业适配）
+- 全局 ARCHITECTURE.md 用"三层"组织：元素层(实体/聚合/技术服务清单)、制品层(Context Map/CQRS)、交付件层(评审文档，可**生成视图**而非手写巨著)。
+- 一人创业不必跑完整委员会审批；用"当前态视图 + 演进日志"替代重审批（见 ch06），成熟度评估降级为自查清单。

package/skills/architecture-design/chapters/ch04-entity-to-aggregate.md

@@ -0,0 +1,27 @@
+# ch04 · 业务实体→聚合→限界上下文
+
+## 业务实体（识别起点）
+- 定义：BA 流程中的**表证单书**（订单/合同/工单/客户档案/库存记录），是业务概念而非数据库表。
+- 全生命周期：创建→变更→归档（如订单：提交→状态流转→可查历史）。
+
+## 活动对象矩阵（实体发现+合并）
+- 横轴=BA 的 L5 活动，纵轴=初步筛出的业务对象；交叉格符号：●主对象 ◐从对象 ○被关联 △新产生。
+- 用途：① 出现任何符号的列即业务实体；② 两对象符号模式重叠度 **>70% 应合并**（如"车辆"与"库存车辆"）。
+
+## DDD 聚合四要素（核心框架 F4）
+- 实体：唯一标识（订单号），属性可变标识不变。
+- 值对象：无独立标识（如地址），属性变即另一对象。
+- 聚合根：外部唯一入口，通过根访问内部对象。
+- 事务边界：聚合内所有操作须在一个事务完成（如创建订单同时建头/行项目/算总价）。
+- **硬规则**：聚合仅存在于业务服务；数据服务（跨聚合查询分析）、技术服务（消息队列）**无聚合**。
+
+## 限界上下文 / Context Map（核心框架 F5）
+- 限界上下文=语义边界，对应 L3 应用服务；相关聚合组成上下文。
+- 同术语异义须显式映射（映射类型）：
+  - **Shared Kernel（共享内核）**：两上下文共享部分模型。
+  - **Anti-Corruption Layer（防腐层）**：下游翻译上游模型，防止概念泄漏。
+  - **Open Host Service（开放主机）**：上游暴露标准协议供多下游消费。
+
+## 应用提示
+- 每变更设计先画"涉及实体的活动对象矩阵"；再定聚合根与事务边界；最后落到全局 Context Map。
+- 全局 ARCHITECTURE.md 的"元素层"须显式列出四域一等元素：BA 活动 / IA 数据实体 / AA 功能与聚合 / TA 技术服务。

package/skills/architecture-design/chapters/ch05-cqrs.md

@@ -0,0 +1,32 @@
+# ch05 · 写/读模型(CQRS)、指令分流、三维判定
+
+## 两类业务对象（性质决定模型）
+| 类型 | 判断 | 映射 | 特征 |
+|---|---|---|---|
+| 事务型 | 操作它时业务世界发生变化？有 | 写模型（聚合） | 有生命周期，事务边界，不可重复计算 |
+| 分析型 | 能否重复计算（跑两遍结果一致）？能 | 读模型 | 派生洞察，无事务，按维度组织 |
+
+> 同一业务名词可能既是事务型又是分析型（"订单"记交易，"订单汇总"是分析）——同一数据源的两个投影，即 CQRS 本质。
+
+## L6 指令与两类聚合（核心框架 F6）
+- **Command** → 写模型：改变聚合状态（创建订单、扣库存）。
+- **Read** → 写模型：有业务逻辑但**不改**状态（校验优惠券适用性）。
+- **Query** → 需分流（见阻断测试）：纯查询。
+- **CRUDL**：C/U/D/L = Command → 业务服务；R 判 Read/Query。
+
+## 阻断测试（Query 分流核心判据）
+> 将此服务**阻断（延迟）1 小时**，下游业务操作能否继续？
+> - 不能继续 → **业务服务**（支撑主干流程，如查可点菜品、跨聚合宽表）
+> - 能继续 → **数据服务**（分析决策支撑，如销售报表、经营分析）
+
+**关键洞察**：分流依据是"它在业务流程中扮演什么角色"，不是"它是读还是写"。把支撑流程的 Query（只读但阻断）误归数据服务，会导致异步加载、体验崩溃。
+
+## 三维判定（验证工具，核心框架 F7）
+决策树：
+1. **失忆测试**：清空业务记忆还能工作？能→技术服务(TA)，结束；不能→进入 2。
+2. **阻断测试**：阻断 1h 下游能继续？不能→业务服务；能→数据服务。
+3. **孤岛测试**：谁在调用？私有层 / 领域共通层 / 企业共通层（定层级）。
+
+## 应用提示
+- API 设计（api.md）须对每个端点标 Command/Read/Query，Query 标注经阻断测试的服务归属。
+- 全局 DATABASE.md 记录读写模型派生机理：读模型派生自写模型（CQRS）。

package/skills/architecture-design/chapters/ch06-integration.md

@@ -0,0 +1,54 @@
+# ch06 · 与 team-flow / compound-engineering 的集成
+
+本章把 F1–F7 落到两个工作流：team-flow（开发过程，change-centric）+ compound-engineering（全局产物+复利）。融合四方专家会审的硬伤修正。
+
+## 产物布局
+```
+项目根/
+├── STRATEGY.md              # 产品/BA 锚点（compound，不动）
+├── CONCEPTS.md              # 领域词汇（追加 DDD 术语，复利累积）
+├── docs/architecture/       # 【技术锚点层，独立于 STRATEGY.md】
+│   ├── ARCHITECTURE.md      # 全局架构（瘦锚点：Context Map+聚合清单+关键决策）
+│   └── DATABASE.md          # 全局 DB（实体+读写模型+OLTP/OLAP）
+
+changes/<name>/              # change 容器
+├── change-brief.md          # 上游交接物（orchestrator S4）
+├── proposal.md              # spec-writer：why + scope
+├── design.md                # spec-writer：decisions + trade-offs
+├── tasks.md                 # spec-writer：implementation steps
+├── execution-contract.md    # contract-builder：execution handshake
+├── specs/                   # 行为规格（spec-writer）
+│   └── <cap>.md             # SHALL/MUST + Scenario + WHEN/THEN
+├── architecture/            # ★ 架构设计（architecture-design，独立一等产物）
+│   ├── architecture.md      # 每变更 DDD 增量（聚合/限界上下文/CQRS）
+│   ├── database.md          # 每变更 DB 增量（实体/读写模型变更）
+│   └── api.md               # 每变更 API 设计（Command/Read/Query 分流）
+└── prototype/               # 原型（prototype skill）
+```
+
+> **语义分离**：架构产出独立 `architecture/` 目录，不混入 `specs/`（行为规格）。目录存在 = 有架构产出，目录不存在 = 判定为不需要。下游消费方（spec-writer / release-archivist）显式读取此目录。
+
+## 每变更增量设计（SOP 步骤）
+1. (LLM) 读全局 ARCHITECTURE.md 作 grounding；用活动对象矩阵识别限界上下文/聚合。
+2. (LLM) 出 To-Be：新增/调整聚合、Context Map 关系、CQRS 读写模型、4A 跨域对齐。
+3. **As-Is 冻结**（核心修正）：复制全局相关章节**当前原文** + 记版本锚点（`ARCHITECTURE.md@<change_id>#<章节>`），变更内不可变——杜绝活引用漂移。
+4. (脚本) 填 frontmatter 并校验：`cap_id/date/change_type/bounded_contexts/aggregates_affected/cqrs`。
+5. (LLM) 写 ADR 理由；API 标 Command/Read/Query + 阻断测试归属。
+6. (脚本) 回写全局 + 生成 API 索引。
+
+## 复利回写（借鉴 ce-compound，已正名）
+- **one change per run**：一次回写一个变更 delta，可追溯、不混杂。
+- 全局 ARCHITECTURE.md 维护双视图：`## 当前态`（覆盖式，每 BC/聚合仅留最新有效定义）+ `## 演进日志`（append-only，含 change_id+来源）。
+- **架构一致性/漂移检查**（独立于 Discoverability）：①结构冲突（重复 BC/聚合 key）②语义冲突（同义异名，如客户vs用户）③跨域一致性门禁（AA≥1 IA 实体，反之亦然）。
+- **Discoverability 正名**：在 AGENTS.md/CLAUDE.md 暴露 `docs/architecture/`，使代理设计前"发现并查阅"（存在/结构/何时检索）——这是 compound 原义，勿与内容冲突检查混淆。
+- 下游检索复用：下一 change 设计前从 `docs/architecture/` 检索相关上下文/聚合（grounding 用 CONCEPTS.md）。
+
+## 集成纪律（来自 team-flow 源码事实）
+- **design.md 不可变**：原型覆盖层 never mutate design.md/tasks.md。原型结论走 `handoff --type prototype` → 新 requirement delta → 正常 `specifying→closing→spec-merger` 闭环，不得直接改 design.md。
+- **guard 软集成**：三份增量文档为推荐产出、非阻断；全局回写经独立 `arch-compound` skill/overlay，不进状态机硬矩阵；frontmatter 校验仅 advisory 脚本（正则提取 key，不引第三方 YAML 依赖），保全零依赖。
+- **术语正名**：IA/AA 非"技术架构"（仅 TA 是）；4A 是四域非三层；技术架构对 STRATEGY.md 是"补位 compound 缺位"而非"修正其错误"，且 ARCHITECTURE.md 是 anchor 而非评审巨著。
+
+## 第二大脑整合（ima「LT的知识库」）
+- 方法层(kb)：存 4A/DDD 方法 skill + 每限界上下文一个 `architecture-anchor`（frontmatter 索引）。
+- 项目层(repo)：`docs/architecture/` 为权威源；设计前检索 kb skill + 读全局 ARCHITECTURE.md；回写后**批量**同步 Context Map 索引入 kb，避免每 delta 双写。
+- API 留债：脚本化 `API-INDEX.md`（扫描所有 `changes/*/architecture/api.md` 抽取端点/方法/错误码/幂等），反对手写全局 API 文档。

package/skills/architecture-design/cheatsheet.md

@@ -0,0 +1,51 @@
+# Cheatsheet · 速查
+
+## 4A 分叉公式
+`BA → (IA ∥ AA) → TA` — BA 先稳，再并行 IA/AA 双向对齐，最后汇聚 TA。定义不可逆。
+
+## 跨域一致性检查（发布门禁）
+- [ ] 每个 AA 功能有 ≥1 IA 数据实体？  (结构)
+- [ ] 每个 IA 实体被 ≥1 AA 功能消费？  (结构)
+- [ ] 命名统一？用户/客户/consumer 不并存 (语义)
+
+## 变更影响三层次（逐项打勾）
+- [ ] 直接依赖 (BA→AA/IA)
+- [ ] 间接依赖 (AA/IA→TA, IA↔AA 对齐)
+- [ ] 隐式依赖 (表面无关却牵动) ← 最危险
+
+## 聚合识别四要素
+实体(唯一标识) + 值对象(无标识) + 聚合根(唯一入口) + 事务边界(一事务)。
+仅业务服务有聚合。
+
+## 三维判定决策树
+```
+失忆测试: 清空业务记忆还能工作? ──能──> TA(技术服务)
+          │否
+阻断测试: 阻断1h下游能继续? ──不能──> 业务服务(写模型)
+          │能
+          └──> 数据服务(读模型)
+孤岛测试: 谁调用? 私有 / 领域共通 / 企业共通  (定层级)
+```
+
+## CQRS 指令分流
+| 指令 | 模型 | 服务 |
+|---|---|---|
+| Command | 写模型 | 业务服务 |
+| Read | 写模型 | 业务服务 |
+| Query | 需分流 | 阻断测试: 不能→业务 / 能→数据 |
+
+## 每变更架构设计 SOP
+1. 读全局 ARCHITECTURE.md grounding
+2. 活动对象矩阵 → 聚合/限界上下文
+3. **As-Is 冻结**(版本锚点) — 防漂移
+4. To-Be: 聚合+Context Map+CQRS+4A 对齐
+5. 填 frontmatter + ADR
+6. 回写全局(当前态+演进日志) + 生成 API-INDEX
+
+## 反模式警示
+- ✗ 先选技术再补流程（定义反）
+- ✗ IA/AA 统称"技术架构"（仅 TA 是）
+- ✗ As-Is 用活引用全局章节（会漂移 → 必须冻结复制）
+- ✗ 把支撑流程的 Query 误归数据服务（阻断测试判）
+- ✗ 直接改 design.md 回写原型（必须 handoff→delta 闭环）
+- ✗ 全局回写进 team-flow 硬 guard（破零依赖 → 软 overlay）

package/skills/architecture-design/glossary.md

@@ -0,0 +1,23 @@
+# Glossary · 架构设计术语表
+
+- **BA / IA / AA / TA**：业务/信息(数据)/应用(功能)/技术 架构四域。仅 TA 是技术架构。
+- **分叉依赖**：`BA→(IA∥AA)→TA`，BA 先行、IA/AA 并行双向对齐、TA 最后。
+- **跨域一致性（双对齐）**：AA 功能≥1 IA 实体支撑，IA 实体≥1 AA 功能消费；结构+语义双对齐。
+- **架构产出三层**：元素(积木)/制品(图纸)/交付件(成品)。
+- **业务实体**：BA 流程中的表证单书，有全生命周期。
+- **活动对象矩阵**：横轴 L5 活动、纵轴业务对象，用符号标注操作关系，重叠>70% 合并。
+- **聚合(Aggregate)**：实体+值对象+聚合根+事务边界；仅存业务服务。
+- **聚合根(Aggregate Root)**：聚合外部唯一入口。
+- **值对象(Value Object)**：无独立标识，属性变即另一对象。
+- **限界上下文(Bounded Context)**：语义边界，对应 L3 应用服务。
+- **Context Map**：限界上下文间关系图；映射类型 Shared Kernel / Anti-Corruption Layer / Open Host Service。
+- **CQRS**：写模型(事务型,聚合)与读模型(分析型,查询模型)分离建模。
+- **写模型(Write Model)**：事务型对象在 AA 的表达，有聚合根/事务边界，Command/Read 操作。
+- **读模型(Read Model)**：分析型对象在 AA 的表达，无事务，Query 操作，派生自写模型。
+- **L6 指令**：Command(改状态)/Read(有逻辑不改状态)/Query(纯查询)。
+- **阻断测试**：阻断 1h 下游能否继续？不能→业务服务，能→数据服务。
+- **三维判定**：失忆(归属 AA/TA)+阻断(类型 业务/数据)+孤岛(层级 私有/领域共通/企业共通)。
+- **As-Is 冻结**：每变更设计时复制全局相关章节当前原文+版本锚点，变更内不可变。
+- **瘦锚点**：ARCHITECTURE.md 作为短稳的技术 anchor（Context Map+聚合清单+关键决策），非评审巨著。
+- **Discoverability Check**：在 AGENTS.md 暴露 docs/architecture/，使代理设计前发现并查阅（compound 原义）。
+- **架构一致性/漂移检查**：回写前的结构+语义+跨域一致性门禁（独立于 Discoverability）。

package/skills/architecture-design/patterns.md

@@ -0,0 +1,32 @@
+# Patterns · 技术与模式
+
+## P1 · 活动对象矩阵（实体发现）
+横轴 L5 活动、纵轴业务对象；符号 ●主 ◐从 ○关联 △新。出现任何符号=实体；重叠>70% 合并。→ 产出实体清单供聚合设计。
+
+## P2 · 聚合识别（四要素落位）
+对每个实体：定聚合根(唯一入口)、拆值对象、画事务边界(一事务内完成的操作集)。硬规则：仅业务服务有聚合；数据/技术服务无。
+
+## P3 · Context Map 映射选型
+- 两团队共享模型 → **Shared Kernel**
+- 下游需隔离上游概念泄漏 → **Anti-Corruption Layer**
+- 上游供多下游标准消费 → **Open Host Service**
+
+## P4 · CQRS 读写模型划分
+事务型对象→写模型(聚合)；分析型对象→读模型(查询模型)。Command/Read→写模型；Query 经阻断测试分流到业务/数据服务。读模型派生自写模型。
+
+## P5 · 增量设计 + 复利回写（工作流衔接）
+每变更：As-Is 冻结复制(版本锚点 change_id+章节+commit) → To-Be(DDD) → 全局 ARCHITECTURE.md(当前态覆盖+演进日志追加)。one change per run。回写前跑架构一致性检查（结构+语义+跨域）。
+
+## P6 · 架构 frontmatter（脚本可校验）
+每变更 architecture.md/database.md 头部：
+```
+cap_id / date / change_type(new|modify) /
+bounded_contexts / aggregates_affected / cqrs(write/read_model)
+```
+用正则提取 key 做 advisory 校验，不引第三方 YAML 依赖（保全 team-flow 零依赖）。
+
+## P7 · API 指令映射（每变更 api.md）
+对每个端点标 Command/Read/Query；Query 标注阻断测试归属(业务/数据服务)。下游脚本扫所有 api.md 生成 API-INDEX.md。
+
+## P8 · 全局锚点暴露（Discoverability）
+在 AGENTS.md 追加一节：存在 docs/architecture/；其结构(Context Map/聚合/DB)；何时检索(每变更设计前)。使代理自动 grounding。

package/skills/bug-investigator/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: bug-investigator
+description: Use when encountering any bug, test failure, or unexpected behavior during team-flow execution, before proposing fixes. Invoked automatically when build-executor hits a blockage.
+---
+
+# Bug Investigator
+
+**Core principle:** Find root cause before attempting fixes. Symptom fixes are failure.
+
+## The Iron Law
+
+No fixes without root cause investigation first. If you haven't completed Phase 1, you cannot propose fixes.
+
+## When to Use
+
+Use for ANY technical issue: test failures, bugs, unexpected behavior, performance problems, build failures, integration issues. Especially when under time pressure, "one quick fix" seems obvious, you've already tried multiple fixes, or you don't fully understand the issue.
+
+Don't skip because issue "seems simple" or you're "in a hurry" — systematic debugging is faster than thrashing.
+
+## The Four Phases
+
+Complete each phase before proceeding.
+
+### Phase 1: Root Cause Investigation
+
+1. **Read error messages carefully**: stack traces, line numbers, file paths, error codes — they often contain the exact solution
+2. **Reproduce consistently**: exact steps, every time? If not reproducible → gather more data, don't guess
+3. **Check recent changes**: git diff, recent commits, new dependencies, config changes, environment differences
+4. **Multi-component systems**: add diagnostic instrumentation at each component boundary. Log what enters and exits each layer. Run once to gather evidence, then analyze which component fails
+5. **Trace data flow**: backward tracing — where does the bad value originate? Keep tracing up until you find the source. Fix at source, not symptom
+
+### Phase 2: Pattern Analysis
+
+1. Find working examples of similar code in the same codebase
+2. Compare against references — read reference implementation completely
+3. Identify every difference between working and broken, however small
+4. Understand dependencies: other components, settings, config, environment, assumptions
+
+### Phase 3: Hypothesis and Testing
+
+Scientific method: form a single hypothesis ("I think X is the root cause because Y"), test with the smallest possible change (one variable at a time), verify before continuing. If it didn't work, form a NEW hypothesis — don't add more fixes. When you don't know, say so and ask for help.
+
+### Phase 4: Implementation
+
+1. **Create failing test case** — simplest reproduction, automated if possible. Follow TDD rules from build-executor
+2. **Implement single fix** — address root cause, one change at a time, no "while I'm here" improvements
+3. **Verify fix** — test passes? no regressions? issue resolved?
+4. **If fix doesn't work**: count attempts. < 3 → return to Phase 1. **≥ 3 → STOP and question architecture (DP-5)**
+
+### DP-5: Debug Escalation (3+ Failures)
+
+3+ failed fixes = architectural problem. Each fix revealing new problems elsewhere = wrong architecture. Record: `npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> dp_5_result <decision>`. Discuss with user before attempting more fixes.
+
+## Red Flags — Return to Phase 1
+
+"Quick fix, investigate later" / "Just try changing X" / "Skip the test, I'll verify manually" / "It's probably X, let me fix that" / "I don't fully understand but this might work" / "One more fix attempt" (after 2+) / Proposing solutions before tracing data flow.
+
+**All of these mean: STOP. Return to Phase 1.** If 3+ fixes failed, question the architecture.
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| 1. Root Cause | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
+| 2. Pattern | Find working examples, compare | Identify differences |
+| 3. Hypothesis | Form theory, test minimally | Confirmed or new hypothesis |
+| 4. Implementation | Create test, fix, verify | Bug resolved, tests pass |
+
+## When No Root Cause Found
+
+If truly environmental/timing-dependent/external: document what you investigated, implement appropriate handling (retry, timeout, error message), add monitoring. But 95% of "no root cause" cases are incomplete investigation.
+
+## Exception Handling
+
+- **Parse failures**: Report raw output, ask for clarification — don't guess
+- **Missing files**: Escalate immediately — not a normal debugging scenario
+- **User interruption**: Re-read investigation report on resume, continue from last completed phase

package/skills/build-executor/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: build-executor
+description: Govern implementation from an approved execution contract. Invoke when execution-contract.md is approved and the user wants disciplined build work, TDD execution, or guarded batch-by-batch implementation.
+---
+
+# Build Executor
+
+Controls the implementation phase. Uses `execution-contract.md` as the workflow authority.
+
+## Required Inputs
+
+Read: `execution-contract.md`, `tasks.md`, relevant `specs/`, relevant `design.md`. (Skip contract/spec requirements when workflow is `tweak`.)
+
+Check workflow mode first: `npx --yes --package @xulthekl/team-flow@0.22.4 tf state get <change-dir> workflow`. If `tweak` → direct edit mode. If `hotfix` or `full` → standard contract-first discipline.
+
+Branch/worktree preflight before ANY implementation edit (mandatory — do not skip):
+1. Run the isolation check:
+   ```bash
+   npx --yes --package @xulthekl/team-flow@0.22.4 tf isolate <change-dir>
+   ```
+   This script enforces git isolation: if you are on `main`/`master` it creates a
+   git worktree (preferred) or a new branch, and exits non-zero if it cannot and you
+   have not approved `--force`.
+2. If `npx --yes --package @xulthekl/team-flow@0.22.4 tf isolate` exits non-zero: STOP. Do not edit `main`/`master` in place.
+   Ask the user for explicit approval (and re-run with `npx --yes --package @xulthekl/team-flow@0.22.4 tf isolate <change-dir> --force`
+   only after they approve).
+3. If it succeeds, report the chosen branch/worktree and make all implementation
+   edits there.
+
+## Core Laws
+
+### Law 1: Contract First
+The execution contract is the approved handoff artifact, not chat history.
+
+### Law 2: TDD Iron Law — No Production Code Without a Failing Test First
+RED (write test, see it fail) → GREEN (write minimal code, see it pass) → REFACTOR (clean up, suite stays green).
+
+**Red Flags**: "Quick implementation first, test later" / "Skip the test, manually verify" / "I already know it works" / "Just this one time without tests." ALL mean STOP and write the test first.
+
+### Law 3: Review Before Drift
+Block on: logic defects, spec violations, missing required tests, unintended scope expansion.
+
+### Law 4: Rewind on Contract Break
+Return to `specifying` or `bridging` if: new behavior appears, interfaces change materially, design assumptions fail, artifacts no longer define intended implementation.
+
+## Execution Mode Selection
+
+For `full`/`hotfix`, generate proposed waves from the approved contract, then use the recommendation as a decision aid rather than silently defaulting a mode:
+
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf execution recommend <change-dir> \
+  --wave <wave-id>:<parallel|serial>:<task,...>[:<depends-on,...>] --json
+# Show every available mode, the observed facts, and the recommendation to the user.
+# The command writes a receipt tied to the artifacts, contract, and waves. After the user chooses, record that explicit confirmation:
+npx --yes --package @xulthekl/team-flow@0.22.4 tf execution plan <change-dir> \
+  --mode <selected-mode> --confirm --reason "user-selected execution mode" \
+  --wave <wave-id>:<parallel|serial>:<task,...>[:<depends-on,...>]
+# Add --acknowledge-recommendation when the selection differs from the recommendation.
+npx --yes --package @xulthekl/team-flow@0.22.4 tf execution show <change-dir> --json
+```
+
+The optional fourth `--wave` segment names prerequisite wave IDs. `execution show --json` reports `current`, plus each wave's `depends_on`, `receipt`, `blockers`, `retryable`, and `eligible` status. A wave with `retryable: true` has a current `fail` receipt and is eligible only for its focused repair and re-review; its dependents remain blocked until its replacement `pass` receipt. Report the saved plan revision, selected mode, ordered waves, dependencies, and whether every `parallel` wave can actually be dispatched concurrently on the current platform. If concurrency is unavailable, state the capability and reason plainly; retain the planned `parallel` strategy and do not silently execute it as a serial or Batch Inline plan.
+
+The recommendation uses task count, configured `execution.inlineThreshold`, and declared wave strategy. It never auto-selects: present every available mode and the recommendation to the user. `--confirm` records any user-selected mode; a choice that differs from the recommendation requires `--acknowledge-recommendation` so the plan captures an informed risk decision.
+
+| Mode | Criteria |
+|------|----------|
+| **SDD** | Recommended for parallel waves, multiple waves, or work beyond the inline threshold |
+| **Inline** | Recommended for a single sequential task; always available for a user-confirmed choice |
+| **Batch Inline** | Recommended for a bounded sequential batch; it remains serial and is never presented as parallel |
+
+Do not transition to `executing` until `execution show` reports `current: true` and the phase guard passes. A revised plan must repeat `npx --yes --package @xulthekl/team-flow@0.22.4 tf execution recommend` and use `npx --yes --package @xulthekl/team-flow@0.22.4 tf execution revise --confirm`; it creates a new revision and invalidates receipts from the prior revision.
+
+## Batch Inline Execution
+
+Only when the user explicitly confirms `batch-inline` after seeing the recommendation. Current agent executes directly and serially. TDD Iron Law still applies.
+
+Procedure: announce mode → write failing test → confirm failure → implement → run suite → refactor → lightweight checkpoint (files exist, no placeholders, test passed, no unintended changes) → report.
+
+Boundaries: if any task touches >1 module, involves schema/API/config changes, or has open questions → downgrade to Inline or SDD.
+
+## SDD Workflow
+
+For full/hotfix by default. Dispatch according to the persisted plan, review each planned wave, and run a final broad review after all waves.
+
+### Planned-Wave Loop
+1. Read the current plan with `npx --yes --package @xulthekl/team-flow@0.22.4 tf execution show <change-dir> --json`; only waves shown with `current: true` and `eligible: true` may start. A `retryable: true` wave may only be repaired and re-reviewed; do not dispatch its dependents until its replacement receipt is `pass`. The CLI encodes dependencies in `--wave <id>:<strategy>:<tasks>[:<depends-on,...>]` and rejects a review receipt for a wave whose prerequisites lack current `pass` receipts.
+2. A `parallel` wave may dispatch independent tasks simultaneously only when the platform supports concurrent dispatch. If it does not, disclose the unavailable capability and execute the same wave one task at a time without changing its stored strategy.
+3. A `serial` wave dispatches one task at a time in listed order.
+4. After every wave, write a non-empty persisted regular-file review report (separate from the implementer's report), then record exactly one receipt that names that review report:
+   ```bash
+   npx --yes --package @xulthekl/team-flow@0.22.4 tf execution review <change-dir> \
+     --wave <wave-id> --base <sha> --head <sha> --report <review-report-path> --verdict <pass|fail>
+   ```
+   Do not begin a dependent wave until its predecessor receipt is `pass`.
+5. Critical/Important findings require a `fail` receipt, a focused repair, re-review, then a replacement `pass` receipt. Never advance or close with a missing or failed receipt.
+
+### Per-Task Loop
+1. **Dispatch implementer**: Load the template with `npx --yes --package @xulthekl/team-flow@0.22.4 tf runtime asset read skills/build-executor/implementer-prompt.md`. Extract task brief with `scripts/task-brief PLAN_FILE N`. Include: where task fits, brief path, interfaces from prior tasks, report file path.
+2. **Handle response**: DONE → generate review package + dispatch reviewer. DONE_WITH_CONCERNS → assess. NEEDS_CONTEXT → provide context. BLOCKED → re-dispatch with better model or escalate.
+3. **Review**: Load `npx --yes --package @xulthekl/team-flow@0.22.4 tf runtime asset read skills/build-executor/task-reviewer-prompt.md`. Reviewer returns spec compliance + code quality verdicts with the wave ID, git range, report path, and `pass`/`fail` receipt command.
+4. **Fix**: If Critical or Important issues, write the `fail` receipt, dispatch fix subagent, re-review, and write the replacement `pass` receipt.
+5. **Mark complete**: Append to `.superpowers/sdd/progress.md`: `Task N: complete (commits <base7>..<head7>, review clean)`
+
+### Model Selection
+Use the configured profile that matches the task role. Resolve it before dispatch:
+
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf runtime config --resolve-model <profile>
+```
+
+| Profile | Role |
+|---|---|
+| `mechanical` | Cheap, routine edits |
+| `standard` | Integration and judgment work |
+| `strong` | Architecture, design, and final review |
+| `review` | Review that matches the diff |
+
+For platforms whose dispatch supports a `model` field, explicitly pass the resolved `model` value. If the result is `configured: false`, automatic selection is unavailable: do not invent a provider model and do not bypass the existing requirement to specify `model` explicitly. Resolution only reads configuration; it does not switch models.
+
+### Progress Ledger
+Track in `.superpowers/sdd/progress.md`. Check for existing ledger — completed tasks are done. After each batch: `npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> batches_completed <N>`.
+
+## Inline Execution Mode
+
+Only after a user-confirmed `inline` selection is recorded by `npx --yes --package @xulthekl/team-flow@0.22.4 tf execution plan --confirm`; a non-recommended selection also records `--acknowledge-recommendation`. Executes in the current session and still writes one review receipt per planned wave.
+
+Per-task: extract brief → write failing test → confirm failure → implement → confirm green → checkpoint review (done-when criteria, SHALL/MUST verification) → commit → save a task-level recovery checkpoint when another task remains → append to progress ledger.
+
+After a task is committed and reviewed, when another task remains, save the
+recovery context with real evidence:
+
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf checkpoint save <change-dir> \
+  --task <completed-task-id> --next "<next task>" --completed "<completed work>" \
+  --verification "<verification report path>" --review "<review report path>" \
+  --risk "<open risk or None>" --commit-start <base-sha> --commit-end <head-sha>
+```
+
+This augments `.superpowers/sdd/progress.md`; it does not replace the progress
+ledger or add a new core workflow state. Do not claim a checkpoint is current
+when `npx --yes --package @xulthekl/team-flow@0.22.4 tf checkpoint list` reports it as stale.
+
+If task hits BLOCKED (3+ fix failures or changes outside declared scope), escalate to SDD.
+
+## Tweak Mode
+
+Skip TDD. Apply changes directly. Verify file integrity (exists, non-empty, valid syntax). No batch execution — sequential changes.
+
+## DP Records
+
+DP-4 is written by `npx --yes --package @xulthekl/team-flow@0.22.4 tf execution plan`; do not write it with raw `state set`.
+DP-5 (debug escalation): `npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> dp_5_result "<resolution>"` + timestamp.
+
+## Completion Standard
+
+Don't report completion until: tests pass, contract obligations satisfied, review blockers resolved, every planned wave has a current `pass` receipt, final review is complete, and workflow is ready for `release-archivist`.
+
+## Exception Handling
+
+- **Parse failures**: Stop and report exact line/format issue. Route back to `contract-builder`.
+- **Missing artifacts**: Route back to appropriate upstream skill. Don't guess.
+- **User interruption**: Progress ledger enables recovery. Check ledger on resume.