@xulthekl/team-flow 0.22.4 → 0.23.0

package/skills/architecture-design/SKILL.md

@@ -112,6 +112,8 @@ artifacts:                       # required 时必填，skipped 时为空
   - architecture/api.md
 ```
 
+**职责边界**：architecture-design 负责**判断+产出**（五项检查判断是否涉及架构变更，涉及则产出架构设计文档），workflow-start 负责**reasonableness check + 状态写入**（确认判断合理性后写入 yaml）。
+
 ### 产出目录
 
 架构设计产出放在 change 目录下的独立 `architecture/` 子目录：
@@ -121,20 +123,57 @@ changes/<name>/
 └── architecture/                # ★ 架构设计独立一等产物
     ├── architecture.md          # DDD 增量（聚合/限界上下文/CQRS/Context Map）
     ├── database.md              # DB 增量（实体/读写模型/schema 变更）
-    └── api.md                   # API 增量（Command/Read/Query 分流 + 端点设计）
+    ├── api.md                   # 架构路由表（Command/Read/Query 分流 + 聚合归属 + 阻断测试结果）
+    └── sql/                     # DDL / Migration 脚本（独立可执行文件，不嵌入 markdown）
+        ├── ddl/                 # 表结构定义脚本
+        └── migration/           # 增量迁移脚本
 ```
 
 **语义分离**：架构设计与行为规格（`specs/`）是不同专业领域，独立目录避免混杂。
 
+**api.md 定位——架构路由表**：
+- 记录内容：Command/Read/Query 分类、聚合归属（哪个聚合拥有该操作）、阻断测试结果（写模型 vs 读模型分流依据）
+- **不**重复 Swagger 管理的内容：请求/响应 schema、错误码定义、参数明细等由 Swagger/OpenAPI 规范承载
+- frontmatter 须声明 `api_contract_manager: swagger`，表明详细契约由 Swagger 工具链管理
+- sql/ 目录中的 DDL 和 migration 脚本为独立可执行 `.sql` 文件，不嵌入 markdown 文档
+
 **下游消费**：
 - `architecture/architecture.md` → spec-writer：design.md Decisions 约束
 - `architecture/database.md` → spec-writer：design.md + tasks.md 数据层约束
-- `architecture/api.md` → spec-writer：tasks.md 接口定义约束
-- 全部 → release-archivist → arch-merge → 全局 `docs/architecture/` 回写
+- `architecture/api.md` → spec-writer：tasks.md 接口路由与分流约束（详细 schema 由 Swagger 提供）
+- `architecture/sql/` → build-executor：直接执行 DDL/migration 脚本
+- 全部 → release-archivist → `tf arch-merge` → 全局 `docs/architecture/` 回写
+
+### 架构制品合并（arch-merge）
+
+change 进入 closing 阶段时，由 release-archivist 调用 `tf arch-merge` CLI 命令，将 `changes/<name>/architecture/` 下的增量制品合并回全局 `docs/architecture/`，完成 As-Is → To-Be 基线更新。architecture-design 本身不执行合并，只负责产出增量制品。
 
 ### 独立调用
 
 除 workflow-start 编排调用外，本 skill 仍支持用户显式独立调用（`/team-flow:architecture-design`），此时不走五项检查判定门，直接执行完整 4A+DDD 设计。
 
+## 上下文加载协议
+
+architecture-design 执行时的上下文组装：
+
+**始终加载**：
+1. `Read docs/architecture/INDEX.md`（~50行摘要）
+2. `Read changes/<name>/change-brief.md`（如有）
+3. `Read changes/<name>/proposal.md`（如有）
+
+**根据五项检查按需加载**：
+4. [聚合变更] → `Read PHYSICAL-MODEL.md` 对应业务域段落 + `Read ARCHITECTURE.md` 对应 BC 段落
+5. [读写模型变更] → `Read PHYSICAL-MODEL.md` 对应域段落
+6. [API 变更] → `Read API-INDEX.md` 对应分流区域
+7. [DB schema 变更] → `Read schema-baseline.sql` 对应表的 DDL
+8. [限界上下文变更] → `Read ARCHITECTURE.md` 全文
+
+**绝不加载**：
+- `baseline.md`（项目全景，arch-design 不需要）
+- 未涉及的业务域段落
+- 历史变更脚本（`changelog/`）
+
+**上下文预算**：单次执行 ~2K tokens（L1 INDEX + 1-2 个 L2 域段 + L3 变更层）
+
 ## Scope & Limits
 本 skill 覆盖 4A+DDD 架构设计方法及其与 team-flow/compound-engineering 的衔接。落地实现结合项目具体工具；超出本范围见相关 skill 或直接问 agent。

package/skills/architecture-design/templates/api.md

@@ -0,0 +1,71 @@
+---
+change_id: <change-name>
+date: YYYY-MM-DD
+arch_design_decision: required | skipped
+api_contract_manager: swagger
+---
+# API 增量设计: <change-name>
+
+> **定位**：架构路由表——记录端点的分流归属、聚合归属、存在理由。
+> 精确的请求/响应 Schema、错误码、参数定义由 Swagger 管理，本文档不重复。
+
+## 1. As-Is 基线（冻结复制）
+
+> 从 API-INDEX.md 复制变更涉及的端点到此处。
+
+### 1.1 现有 Command API
+
+| 端点 | 方法 | 聚合 | 事务边界 | 说明 |
+|------|------|------|---------|------|
+
+### 1.2 现有 Read API
+
+| 端点 | 方法 | 聚合 | 数据来源 | 说明 |
+|------|------|------|---------|------|
+
+### 1.3 现有 Query API
+
+| 端点 | 方法 | 查询模型 | 阻断测试 | 说明 |
+|------|------|---------|---------|------|
+
+## 2. To-Be 增量设计
+
+### 2.1 Command API（改状态）
+
+| 端点 | 方法 | 聚合 | 事务边界 | 说明 |
+|------|------|------|---------|------|
+| /api/xxx | POST | XxxAggregate | t_xxx 事务 | 简要说明 |
+
+### 2.2 Read API（有逻辑不改状态）
+
+| 端点 | 方法 | 聚合 | 数据来源 | 说明 |
+|------|------|------|---------|------|
+| /api/xxx/{id}/detail | GET | XxxAggregate | t_xxx + JOIN | 简要说明 |
+
+### 2.3 Query API（纯查询）
+
+| 端点 | 方法 | 查询模型 | 阻断测试 | 说明 |
+|------|------|---------|---------|------|
+| /api/dashboard/xxx-stats | GET | XxxStatsView | 阻断=继续 → 数据服务 | 简要说明 |
+
+> **阻断测试说明**：将服务阻断 1h，下游不能继续 → 业务服务；能继续 → 数据服务
+
+## 3. 跨域一致性检查
+
+> 检查 API 端点与数据实体的对齐情况。
+
+| API 端点 | 对应数据实体 | 对齐状态 | 不一致说明 |
+|---------|------------|---------|-----------|
+| /api/xxx | t_xxx | ✅ 对齐 | — |
+
+### 3.1 术语命名统一性
+
+| 术语 | API 层命名 | 数据层命名 | 一致性 |
+|------|-----------|-----------|-------|
+| xxx | xxxId | xxx_id | ✅ 统一 |
+
+## 4. 演进日志
+
+| 日期 | 变更 ID | 内容 | 影响范围 |
+|------|---------|------|---------|
+| YYYY-MM-DD | <change-name> | 初始设计 | 新建 |

package/skills/architecture-design/templates/architecture.md

@@ -0,0 +1,82 @@
+---
+change_id: <change-name>
+date: YYYY-MM-DD
+arch_design_decision: required | skipped
+---
+# Architecture 增量设计: <change-name>
+
+## 1. As-Is 基线（冻结复制）
+
+> 从全局 ARCHITECTURE.md 复制当前相关 BC/聚合/Context Map 到此处。
+
+### 1.1 现有聚合
+
+| 聚合名称 | 聚合根 | 所属限界上下文 | 事务边界 |
+|---------|-------|-------------|---------|
+
+### 1.2 现有限界上下文
+
+| 上下文名称 | 职责 | 包含聚合 | 语言类型 |
+|-----------|------|---------|---------|
+
+### 1.3 现有 Context Map
+
+| 上游 | 下游 | 映射类型 | 说明 |
+|------|------|---------|------|
+
+## 2. To-Be 增量设计（DDD）
+
+### 2.1 聚合变更
+
+| 聚合名称 | 操作 | 聚合根 | 实体/值对象 | 事务边界 | 所属 BC |
+|---------|------|-------|-----------|---------|--------|
+
+### 2.2 限界上下文变更
+
+| 上下文名称 | 操作 | 职责 | 包含聚合 | 语言类型 |
+|-----------|------|------|---------|---------|
+
+### 2.3 Context Map 变更
+
+| 上游 | 下游 | 操作 | 映射类型 | 说明 |
+|------|------|------|---------|------|
+
+### 2.4 CQRS 写/读模型变更
+
+| 聚合 | 操作类型 | 命令/查询 | 事务边界 | 说明 |
+|------|---------|---------|---------|------|
+
+## 3. 变更分叉级联分析
+
+### 3.1 直接依赖
+
+| 依赖项 | 影响说明 | 处理方式 |
+|-------|---------|---------|
+
+### 3.2 间接依赖
+
+| 依赖项 | 影响说明 | 处理方式 |
+|-------|---------|---------|
+
+### 3.3 隐式依赖（最危险）
+
+| 依赖项 | 影响说明 | 处理方式 |
+|-------|---------|---------|
+
+## 4. 跨域一致性检查
+
+### 4.1 结构一致性（AA ↔ IA）
+
+| AA 功能 | IA 实体 | 对齐状态 | 说明 |
+|--------|--------|---------|------|
+
+### 4.2 语义一致性（命名统一）
+
+| 概念 | AA 命名 | IA 命名 | 一致性 |
+|------|--------|--------|-------|
+
+## 5. 演进日志
+
+| 日期 | 变更 ID | 内容 | 影响范围 |
+|------|---------|------|---------|
+| YYYY-MM-DD | <change-name> | 初始设计 | 新建 |

package/skills/architecture-design/templates/change-brief.md

@@ -0,0 +1,29 @@
+---
+upstream_source: orchestrator | manual | null
+upstream_req_id: <req-id>
+upstream_plan_ref: prd/vN/plan.md
+upstream_change_id: C2
+plan_hash: sha256:<plan.md 内容摘要>
+---
+# Change Brief: <change-name>
+
+## Scope
+
+<用户故事/功能模块级 scope，与 plan.md 该 change 的 Scope 一致>
+
+## 约束
+
+<来自 plan.md 的全局约束 / 该 change 的已知约束>
+
+## AC 列表
+
+<取自 auditor 报告 Dim1 覆盖矩阵中映射到本 change 的 AC，逐条>
+
+## 全局技术方向
+
+<取自 plan.md 高阶技术设计段要点：模块边界/技术选型/数据流方向>
+
+## PRD & plan 引用
+
+- PRD: prd/vN/prd.md §<相关章节>
+- Plan: prd/vN/plan.md ### <C-ID>

package/skills/architecture-design/templates/database.md

@@ -0,0 +1,69 @@
+---
+change_id: <change-name>
+date: YYYY-MM-DD
+arch_design_decision: required | skipped
+---
+# Database 增量设计: <change-name>
+
+## 1. As-Is 基线（冻结复制）
+
+> 从 PHYSICAL-MODEL.md 复制变更涉及的表的当前字段定义到此处。
+> 仅复制涉及的表，不要全量复制。
+
+### 1.1 现有写模型
+
+| 表名 | 所属聚合 | 写模型类型 | 关键字段 |
+|------|---------|-----------|---------|
+| t_xxx | XxxAggregate | 事务型 | ... |
+
+### 1.2 现有读模型
+
+| 视图/表名 | 所属查询 | 读模型类型 | 数据来源 |
+|----------|---------|-----------|---------|
+| v_xxx | XxxQuery | 分析型 | t_xxx JOIN t_yyy |
+
+## 2. To-Be 增量设计
+
+### 2.1 写模型变更（事务型）
+
+| 表名 | 操作 | 聚合 | 事务边界 | 变更说明 |
+|------|------|------|---------|---------|
+| t_xxx | ALTER | XxxAggregate | 现有事务 | 新增字段 xxx_type |
+
+### 2.2 读模型变更（分析型）
+
+| 视图/表名 | 操作 | 查询 | 阻断测试结果 | 变更说明 |
+|----------|------|------|------------|---------|
+| v_xxx | CREATE | XxxStatsQuery | 阻断=继续 → 数据服务 | 新增统计视图 |
+
+## 3. Schema 变更详情
+
+> 可执行脚本位于 `sql/ddl/` 目录，以下为变更概要。
+
+| 脚本文件 | 操作类型 | 目标表 | 说明 |
+|---------|---------|-------|------|
+| `sql/ddl/YYYYMMDD_desc.sql` | CREATE TABLE / ALTER TABLE | t_xxx | 简要说明 |
+
+### 3.1 变更影响
+
+<对现有物理模型的影响说明：哪些表受影响、是否有数据迁移需求>
+
+## 4. 实体关系变更
+
+| 实体 | 操作 | 聚合 | 类型 | 唯一标识 | 说明 |
+|------|------|------|------|---------|------|
+| XxxEntity | 新增 | XxxAggregate | 实体 | id (bigint) | ... |
+
+## 5. 数据迁移脚本
+
+> 可执行脚本位于 `sql/migration/` 目录。
+
+| 脚本文件 | 说明 | 幂等性 | 回滚方式 |
+|---------|------|-------|---------|
+| `sql/migration/YYYYMMDD_desc.sql` | 简要说明 | 是/否 | DROP + 重跑 / 反向 DML |
+
+## 6. 演进日志
+
+| 日期 | 变更 ID | 内容 | 影响范围 |
+|------|---------|------|---------|
+| YYYY-MM-DD | <change-name> | 初始设计 | 新建 |

package/skills/architecture-design/templates/index.md

@@ -0,0 +1,33 @@
+# Architecture Index
+
+> 本文件始终加载，各产物按需 Read。
+> Last updated: change=<change-name>, YYYY-MM-DD
+
+## ARCHITECTURE.md
+- 限界上下文: <数量>
+- 聚合数量: <数量>
+- 最后更新: change=<change-name>, YYYY-MM-DD
+- 读取建议: 按 BC 段落读取
+
+## PHYSICAL-MODEL.md
+- 表数量: <数量>
+- 业务域:
+  - <域名1>: <表名列表> (N表)
+  - <域名2>: <表名列表> (N表)
+- 最后更新: change=<change-name>, YYYY-MM-DD
+- 读取建议: 按业务域段落读取
+
+## schema-baseline.sql
+- 表数量: <数量>
+- 最后更新: change=<change-name>, YYYY-MM-DD
+- 读取建议: 通常不需加载，DDL 由 sql/ 目录独立管理
+
+## API-INDEX.md
+- 端点数量: <数量>
+- 分流统计: Command=N / Read=N / Query=N
+- 最后更新: change=<change-name>, YYYY-MM-DD
+- 读取建议: 按分流区域读取
+
+## CONCEPTS.md
+- 术语数量: <数量>
+- 最后更新: bootstrap, YYYY-MM-DD

package/skills/architecture-design/templates/physical-model.md

@@ -0,0 +1,93 @@
+# <项目名>数据库物理模型
+
+> 生成时间: YYYY-MM-DD
+> 最后更新: change=<change-name>, YYYY-MM-DD
+
+---
+
+## <业务域名1>（限界上下文）
+
+### 1. <表中文名> (<表名>)
+
+| ID | | 表名 | <表名> | | | | | | | | |
+| ---- | ---- | -------------- | ------------ | ---- | ---- | ----------- | ------ | ---- | ---- | ---- | ---- |
+| No | 字段名 | 字段ID | NOTN | UNIQ | 属性 | 字节数 | PK | EK | 索引 | 索引 | 索引 | 说明 |
+| 1 | 主键ID | id | N | | bigint | | Y | | | | | auto_increment |
+| 2 | <字段中文名> | <field_id> | N | | <type> | | | | | | | <说明> |
+| 3 | 创建者 | create_by | Y | | bigint | | | | | | | |
+| 4 | 创建时间 | create_time | Y | | datetime | | | | | | | |
+| 5 | 更新者 | update_by | Y | | bigint | | | | | | | |
+| 6 | 更新时间 | update_time | Y | | datetime | | | | | | | 默认CURRENT_TIMESTAMP |
+| 7 | 删除标识 | del_flag | Y | | tinyint(1) | | | | | | | 默认0:未删除 1已删除 |
+| 8 | 备注 | remark | Y | | varchar(500) | | | | | | | |
+
+---
+
+### 2. <表中文名> (<表名>)
+
+| ID | | 表名 | <表名> | | | | | | | | |
+| ---- | ---- | -------------- | ------------ | ---- | ---- | ----------- | ------ | ---- | ---- | ---- | ---- |
+| No | 字段名 | 字段ID | NOTN | UNIQ | 属性 | 字节数 | PK | EK | 索引 | 索引 | 索引 | 说明 |
+| 1 | 主键ID | id | N | | bigint | | Y | | | | | auto_increment |
+| 2 | <关联表>ID | <fk_field_id> | N | | bigint | | | Y | Y | | | FK→<关联表名> |
+| 3 | <字段中文名> | <field_id> | N | | <type> | | | | | | | <说明> |
+| 4 | <JSON字段中文名> | <json_field_id> | Y | | json | | | | | | | 条件必填 |
+| 5 | 创建者 | create_by | Y | | bigint | | | | | | | |
+| 6 | 创建时间 | create_time | Y | | datetime | | | | | | | |
+| 7 | 更新者 | update_by | Y | | bigint | | | | | | | |
+| 8 | 更新时间 | update_time | Y | | datetime | | | | | | | 默认CURRENT_TIMESTAMP |
+| 9 | 删除标识 | del_flag | Y | | tinyint(1) | | | | | | | 默认0:未删除 1已删除 |
+| 10 | 备注 | remark | Y | | varchar(500) | | | | | | | |
+
+---
+
+## <业务域名2>（限界上下文）
+
+### 3. <表中文名> (<表名>)
+
+| ID | | 表名 | <表名> | | | | | | | | |
+| ---- | ---- | -------------- | ------------ | ---- | ---- | ----------- | ------ | ---- | ---- | ---- | ---- |
+| No | 字段名 | 字段ID | NOTN | UNIQ | 属性 | 字节数 | PK | EK | 索引 | 索引 | 索引 | 说明 |
+| 1 | 主键ID | id | N | | bigint | | Y | | | | | auto_increment |
+| 2 | <字段中文名> | <field_id> | N | | varchar(100) | | | | | | | <说明> |
+| 3 | <枚举字段中文名> | <enum_field_id> | N | | char | 1 | | | | | | <枚举说明，如 1:是 0:否> |
+| 4 | 创建者 | create_by | Y | | bigint | | | | | | | |
+| 5 | 创建时间 | create_time | Y | | datetime | | | | | | | |
+| 6 | 更新者 | update_by | Y | | bigint | | | | | | | |
+| 7 | 更新时间 | update_time | Y | | datetime | | | | | | | 默认CURRENT_TIMESTAMP |
+| 8 | 删除标识 | del_flag | Y | | tinyint(1) | | | | | | | 默认0:未删除 1已删除 |
+| 9 | 备注 | remark | Y | | varchar(500) | | | | | | | |
+
+---
+
+## 附录：物理模型图例说明
+
+| 标识 | 含义 |
+|------|------|
+| **NOTN** | NOT NULL，Y=可为空，N=不可为空 |
+| **UNIQ** | UNIQUE，Y=唯一约束 |
+| **PK** | Primary Key，主键 |
+| **EK** | External Key，外键（关联其他表） |
+| **索引** | 该字段上有索引 |
+| **属性** | 数据类型，如 bigint、varchar(50)、decimal(15,4) 等 |
+| **说明** | 字段业务含义、枚举值、默认值等说明 |
+
+### 通用字段说明
+
+所有表均包含以下标准字段（审计字段）：
+
+| 字段名 | 字段ID | 属性 | 说明 |
+|--------|--------|------|------|
+| 创建者 | create_by | bigint | 创建人ID |
+| 创建时间 | create_time | datetime | |
+| 更新者 | update_by | bigint | 更新人ID |
+| 更新时间 | update_time | datetime | 默认CURRENT_TIMESTAMP，自动更新 |
+| 删除标识 | del_flag | tinyint(1) | 默认0:0未删除 1已删除（逻辑删除） |
+| 备注 | remark | varchar(500) | |
+
+### 枚举字段速查
+
+| 表名 | 字段名 | 枚举值 |
+|------|--------|--------|
+| <表中文名1> | <字段中文名1> | <枚举值说明> |
+| <表中文名2> | <字段中文名2> | <枚举值说明> |

package/skills/bug-investigator/SKILL.md

@@ -49,7 +49,7 @@ Scientific method: form a single hypothesis ("I think X is the root cause becaus
 
 ### 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.
+3+ failed fixes = architectural problem. Each fix revealing new problems elsewhere = wrong architecture. Record: `npx --yes --package @xulthekl/team-flow@0.23.0 tf state set <change-dir> dp_5_result <decision>`. Discuss with user before attempting more fixes.
 
 ## Red Flags — Return to Phase 1
 

package/skills/build-executor/SKILL.md

@@ -11,18 +11,22 @@ Controls the implementation phase. Uses `execution-contract.md` as the workflow
 
 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.
+When `architecture/sql/` exists, also read:
+- `architecture/sql/ddl/*.sql` — executable DDL scripts; reference directly for DB schema change tasks instead of hand-writing DDL
+- `architecture/sql/migration/*.sql` — data migration scripts; execute as-is for data transformation tasks
+
+Check workflow mode first: `npx --yes --package @xulthekl/team-flow@0.23.0 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>
+   npx --yes --package @xulthekl/team-flow@0.23.0 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`
+2. If `npx --yes --package @xulthekl/team-flow@0.23.0 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.23.0 tf isolate <change-dir> --force`
    only after they approve).
 3. If it succeeds, report the chosen branch/worktree and make all implementation
    edits there.
@@ -48,15 +52,15 @@ Return to `specifying` or `bridging` if: new behavior appears, interfaces change
 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> \
+npx --yes --package @xulthekl/team-flow@0.23.0 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> \
+npx --yes --package @xulthekl/team-flow@0.23.0 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
+npx --yes --package @xulthekl/team-flow@0.23.0 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.
@@ -69,7 +73,7 @@ The recommendation uses task count, configured `execution.inlineThreshold`, and
 | **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.
+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.23.0 tf execution recommend` and use `npx --yes --package @xulthekl/team-flow@0.23.0 tf execution revise --confirm`; it creates a new revision and invalidates receipts from the prior revision.
 
 ## Batch Inline Execution
 
@@ -84,21 +88,21 @@ Boundaries: if any task touches >1 module, involves schema/API/config changes, o
 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.
+1. Read the current plan with `npx --yes --package @xulthekl/team-flow@0.23.0 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> \
+   npx --yes --package @xulthekl/team-flow@0.23.0 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.
+1. **Dispatch implementer**: Load the template with `npx --yes --package @xulthekl/team-flow@0.23.0 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.
+3. **Review**: Load `npx --yes --package @xulthekl/team-flow@0.23.0 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)`
 
@@ -106,7 +110,7 @@ For full/hotfix by default. Dispatch according to the persisted plan, review eac
 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>
+npx --yes --package @xulthekl/team-flow@0.23.0 tf runtime config --resolve-model <profile>
 ```
 
 | Profile | Role |
@@ -119,11 +123,11 @@ npx --yes --package @xulthekl/team-flow@0.22.4 tf runtime config --resolve-model
 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>`.
+Track in `.superpowers/sdd/progress.md`. Check for existing ledger — completed tasks are done. After each batch: `npx --yes --package @xulthekl/team-flow@0.23.0 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.
+Only after a user-confirmed `inline` selection is recorded by `npx --yes --package @xulthekl/team-flow@0.23.0 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.
 
@@ -131,7 +135,7 @@ 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> \
+npx --yes --package @xulthekl/team-flow@0.23.0 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>
@@ -139,7 +143,7 @@ npx --yes --package @xulthekl/team-flow@0.22.4 tf checkpoint save <change-dir> \
 
 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.
+when `npx --yes --package @xulthekl/team-flow@0.23.0 tf checkpoint list` reports it as stale.
 
 If task hits BLOCKED (3+ fix failures or changes outside declared scope), escalate to SDD.
 
@@ -149,8 +153,8 @@ Skip TDD. Apply changes directly. Verify file integrity (exists, non-empty, vali
 
 ## 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.
+DP-4 is written by `npx --yes --package @xulthekl/team-flow@0.23.0 tf execution plan`; do not write it with raw `state set`.
+DP-5 (debug escalation): `npx --yes --package @xulthekl/team-flow@0.23.0 tf state set <change-dir> dp_5_result "<resolution>"` + timestamp.
 
 ## Completion Standard
 

package/skills/build-executor/implementer-prompt.md

@@ -22,7 +22,7 @@ Subagent (general-purpose):
     ## Planned Wave
 
     You are assigned to planned wave [WAVE_ID] with strategy [WAVE_STRATEGY].
-    Read `npx --yes --package @xulthekl/team-flow@0.22.4 tf execution show <change-dir> --json` before editing. Do not start
+    Read `npx --yes --package @xulthekl/team-flow@0.23.0 tf execution show <change-dir> --json` before editing. Do not start
     unless all declared dependencies have `pass` review receipts. A `parallel`
     label permits concurrent dispatch only when the controller confirms the
     platform supports it; never change the saved wave strategy yourself.

package/skills/build-executor/references/execution-modes.md

@@ -7,14 +7,14 @@
 For `full`/`hotfix`, generate proposed waves from the approved contract, then use the recommendation as a decision aid:
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.22.4 tf execution recommend <change-dir> \
+npx --yes --package @xulthekl/team-flow@0.23.0 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.
-npx --yes --package @xulthekl/team-flow@0.22.4 tf execution plan <change-dir> \
+npx --yes --package @xulthekl/team-flow@0.23.0 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
+npx --yes --package @xulthekl/team-flow@0.23.0 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.
@@ -37,7 +37,7 @@ Dispatch according to the persisted plan, review each planned wave, and run a fi
 3. A `serial` wave dispatches one task at a time in listed order.
 4. After every wave, write a review report, then record one receipt:
    ```bash
-   npx --yes --package @xulthekl/team-flow@0.22.4 tf execution review <change-dir> \
+   npx --yes --package @xulthekl/team-flow@0.23.0 tf execution review <change-dir> \
      --wave <wave-id> --base <sha> --head <sha> --report <review-report-path> --verdict <pass|fail>
    ```
 5. Critical/Important findings require a `fail` receipt, focused repair, re-review, then replacement `pass` receipt.
@@ -66,7 +66,7 @@ Per-task: extract brief → write failing test → confirm failure → implement
 ## Model Selection
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.22.4 tf runtime config --resolve-model <profile>
+npx --yes --package @xulthekl/team-flow@0.23.0 tf runtime config --resolve-model <profile>
 ```
 
 | Profile | Role |
@@ -79,7 +79,7 @@ npx --yes --package @xulthekl/team-flow@0.22.4 tf runtime config --resolve-model
 ## Recovery Checkpoint
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.22.4 tf checkpoint save <change-dir> \
+npx --yes --package @xulthekl/team-flow@0.23.0 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>