@xulthekl/team-flow 0.44.0 → 0.45.0

package/skills/contract-builder/references/glaf4-delegation.md

@@ -0,0 +1,130 @@
+# GLAF4 Delegation 段产出协议（v2.1 §6.1/§6.2）
+
+> 设计溯源（工作区开发期文档，非运行时加载路径）：`docs/plan/glaf4-dev-integration-design.md` v2.1（glaf4-dev 集成增强方案，位于 team-flow-workspace 工作区根）。
+> 职责：contract-builder 在产出 execution-contract.md 时，对 GLAF4 Java change 追加 `## GLAF4 Delegation` 段，
+> 作为**实施委托交接**（非矩阵设计委托）。经 DP-4 批准后生效。
+
+## 1. 运行时探测（v2.1 §4 接口①）
+
+contract-builder 产出 execution-contract 时（DP-4 前）实时探测——**显式运行 CLI 命令**（第三轮复评接线统一：探测必须写 config，纯库函数不落盘）：
+
+```bash
+tf glaf4-delegation detect <target_root> [--delegation-mode <auto|manual|off>]
+```
+
+`detect` 内部调用 `conventions-generator.mjs` 的 `detectGlaf4Delegation(root)` 解析 `~/.claude/plugins/installed_plugins.json`（glaf4-dev 条目含 installPath + version），产出三态：
+
+- `is_glaf4_java`（技术栈命中：pom.xml/build.gradle + Spring Boot/JUnit5/Mockito）
+- `glaf4_dev_available`（插件可用，含 version）
+- `delegation_mode`（auto/manual/off，用户可开关）
+
+探测结果写 `team-flow.config.json` 的 `glaf4_dev: {enabled, version, delegation_mode}` 段
+（git root ≠ target_root 时写 git root 冗余副本，monorepo 下多服务 OR 聚合；未传 `--delegation-mode` 保留已有值）。
+
+**判定**：`is_glaf4_java && glaf4_dev_available && delegation_mode !== 'off'` → 产出 GLAF4 Delegation 段。
+**依赖**：`recommendExecutionModesForChange` 读 `config.glaf4_dev.enabled` 决定是否注入 glaf4-delegation——**必须**先跑 detect 写 config，否则委托链不可达。
+
+## 2. change 性质 → 委托模式映射（v2.1 §6.1）
+
+| change 性质 | glaf4-dev 模式 | 权限位 |
+|---|---|---|
+| 新功能 / 新增接口 / 新增模块 | FEATURE_TDD | after-red |
+| 缺陷修复 | BUGFIX_REGRESSION | after-red |
+| 行为不变重构 | REFACTOR_PROTECTED | allowed + baseline_green_required |
+| 补单元测试(存量) | COMPLETE_UNIT_TESTS | none(test-only) |
+| 补集成测试(存量) | COMPLETE_INTEGRATION_TESTS | none(test-only) |
+| 测试环境冷启动(零测试) | TEST_BOOTSTRAP | none(test-only) |
+
+> REFACTOR 委托前置：存量基线不绿时委托必 NEEDS_INPUT → 先走 TEST_BOOTSTRAP/COMPLETE_UNIT_TESTS 补基线。
+
+## 3. GLAF4 Delegation 段结构
+
+execution-contract.md 追加段（write_set_boundary 权威源，不落 state YAML）：
+
+```markdown
+## GLAF4 Delegation
+
+- mode: FEATURE_TDD
+- permission: after-red
+- write_set_boundary:
+  - src/main/java/com/example/OrderService.java
+  - src/main/java/com/example/OrderRepository.java
+- target_root: <工程根绝对路径>
+- delegation_mode: auto
+- glaf4_dev_version: 0.3.0
+```
+
+## 4. DP-4 委托方案确认（v2.1 §6.6）
+
+先走 S1 执行模式选择（v2.1 §6.6），选 `glaf4-delegation` 产单 wave 计划：
+
+```bash
+# 0. 选模式（DP-4 决策门；单 wave = 委托 glaf4-dev 完成 change）
+tf execution plan <change-dir> --mode glaf4-delegation --wave w1:serial:delegate --confirm --reason "<委托理由>"
+```
+
+模式选定后，确认 5 项并写状态：
+
+```bash
+# 1. 写 write-set.json（边界文件清单）+ dp_4_glaf4_mode + dp_4_write_set_hash
+tf glaf4-delegation confirm <change-dir> --mode FEATURE_TDD --write-set <write-set.json>
+
+# 2. 置 delegation_status（委托进行中）
+tf state set <change-dir> delegation_status in_progress
+```
+
+5 项确认：① change→mode 映射 ② write_set_boundary ③ 串行特征 ④ 两级门预期 ⑤ 授权委托。
+`dp_4_glaf4_mode` 入 state；`dp_4_write_set_boundary`（文件清单）不落 state YAML（writeState 硬编码字段列表 +
+parseYaml 仅标量），落 `.superpowers/glaf4/write-set.json`，state 只存 `dp_4_write_set_hash` 引用 hash。
+`dp_4_result` 由 `tf execution plan --confirm` 程序化写入，手工 set 会被覆写。
+
+## 5. 委托 run 后对账（v2.1 §6.3）
+
+```bash
+# write-set 对账（门禁级 FAIL，阻断 closing）
+tf glaf4-delegation verify-write-set <change-dir> --run-dir <run-dir>
+
+# task 完成度审计（WARN，人工核对）
+tf glaf4-delegation verify-tasks <change-dir>
+```
+
+允许集（change 边界之外允许写入）：pom.xml/build.gradle、src/test/java/**、src/test/resources/**、
+.glaf4-dev/runs/**、test-environment.json。这是唯一约束 change 边界的机械机制。
+
+## 6. 委托失败恢复（v2.1 §6.7）
+
+- delegation_status=failed → guard 阻断 closing 直到人工重置（三选一）
+- ① 重试（retry_count 封顶 3，达上限禁止继续重试）② 降级（reset 删 plan 重走 DP-4）③ 标记阻塞转人工
+- 环境错误（environment_error=true）直接转 ②/③，不浪费重试
+- BLOCKED 残留 partial writes：`tf glaf4-delegation record-partial <change-dir> --run-dir <run-dir>` 落 `delegation_partial_writes` 清单，人工核对从"扫盘"降为"确认清单"
+
+## 7. 骨架矩阵先行时序（v2.1 §5，I6 固化防 H1 死锁复发）
+
+**顺序写死，不可颠倒**——否则骨架矩阵缺失 → GLAF4 change 进不了 executing（原 H1 死锁复发）：
+
+```
+bridging：contract-builder 产非空骨架矩阵 test-matrix.md（过 test-matrix-ready 入口门）
+  → tf state rebuild（捕获骨架矩阵 hash）
+  → 委托 run（glaf4-dev 七模式流）
+  → run 终局 → 矩阵回灌覆盖骨架（test-matrix-export v2 转 MD）
+  → tf state rebuild（过 test-matrix-complete 出口门）
+```
+
+## 8. closing 时序协议（v2.1 §6.3，I5 固化防 plan 过期卡死）
+
+**顺序不可乱**——tasks.md 翻转/矩阵回灌改变 artifacts_hash → plan 过期（receipt 失效）；必须先 refresh-hash 再记录 review：
+
+```
+run 终局 PASS
+  → 矩阵回灌（test-matrix-export v2 + 覆盖 test-matrix.md）
+  → tf state rebuild（只改 state 文件，不动 plan JSON）
+  → tf execution refresh-hash（更新 plan.artifacts_hash，防 plan 过期）
+  → 委托代理 commit glaf4-dev 产物
+  → code-reviewer 独立审查 base..head（报告落 .superpowers/sdd/reviews/）
+  → tf execution review --wave w1 --verdict pass
+  → tf glaf4-delegation verify-write-set（门禁级对账，FAIL 阻断）
+  → tf state set delegation_status success
+  → tf state transition ... closing
+```
+
+> `tf state rebuild` 不能替代 `refresh-hash`（前者不动 plan JSON）；review 需真实 git base≠head，必须 commit 后取 SHA。

package/skills/workflow-start/SKILL.md

@@ -88,7 +88,7 @@ Full protocol in `references/routing-rules.md`「Route to architecture-design」
 Guard: `tf runtime guard check <dir> exploring specifying --json` → fail = BLOCK. **arch_design_decision must not be null** → fail = BLOCK (v0.9 §26). User knows what they want, artifacts missing/incomplete.
 
 ### Route to contract-builder (dispatch sub-agent)
-Guard: `... check <dir> specifying bridging --json` → fail = BLOCK. Artifacts exist, implementation requested, contract missing/stale. Include `DP-3: 契约批准`. **full workflow 必产 test-matrix.md（v0.13 §52 B1）**：契约 `## Test Matrix` 段 + 非空矩阵文件 + `tf state rebuild` 捕获 hash；确无测试需求只能显式 skip + 理由（`test_matrix_skipped=true` + `test_matrix_skip_reason`）。GLAF4 Java 项目矩阵生成的工具选择见 `references/routing-rules.md`「Route to glaf4-tests」。
+Guard: `... check <dir> specifying bridging --json` → fail = BLOCK. Artifacts exist, implementation requested, contract missing/stale. Include `DP-3: 契约批准`. **full workflow 必产 test-matrix.md（v0.13 §52 B1）**：契约 `## Test Matrix` 段 + 非空矩阵文件 + `tf state rebuild` 捕获 hash；确无测试需求只能显式 skip + 理由（`test_matrix_skipped=true` + `test_matrix_skip_reason`）。GLAF4 Java 项目实施委托（glaf4-dev）与矩阵工具选择见 `references/routing-rules.md`「Route to glaf4-dev 实施委托」。
 
 ### Route to build-executor (dispatch sub-agent)
 Contract exists and approved, contract matches artifacts. Include `DP-4: 执行模式选择`: propose waves, run `tf execution recommend <change-dir> [--wave ...]`, show the user every available mode plus evidence and the recommendation, then obtain a clear selection. The command saves a current receipt; before the first implementation edit, `build-executor` must run `tf execution plan <change-dir> --mode <selected> --confirm ...` (and `--acknowledge-recommendation` when the selected mode differs from the recommendation) using matching artifacts, contract, and waves, then `tf execution show <change-dir> --json`; report the saved revision, selected mode, recommendation alignment, ordered waves, and actual concurrent-dispatch capability. A revision must repeat recommend and confirmation. Do not transition to `executing` until `show` reports `current: true`; then run `... check <dir> approved-for-build executing --json` → fail = BLOCK. **v0.13 §49 门禁前移**：该 guard 含 `test-matrix-ready` 维度——full 模式非存量 change 必须"带着矩阵开工"（矩阵存在非空 OR 显式 skip 附理由）；FAIL 时回 bridging 让 contract-builder 补矩阵，或按指引显式 skip，禁止绕过。

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

@@ -313,23 +313,23 @@ Inference: **hotfix** (≤2 tasks, ≤2 files, no schema/API/new modules), **twe
 ## Post-transition
 💡 `tf inject <change-dir>` to update phase-guard artifacts.
 
-## Route to glaf4-tests (v0.12 §46, v0.31.0, v0.13 §52 B3 归位)
+## Route to glaf4-dev 实施委托 (v0.12 §46, v0.31.0, v0.13 §52 B3 归位; v2.1 §1.3 统一到 glaf4-dev)
 
-**归位说明（v0.13）**：本段的触发主体是 **bridging 阶段的 contract-builder 子代理**（矩阵生成者），workflow-start 主路由表不包含 glaf4-tests 条目——放在本文件仅作 bridging 期参考。
+**归位说明**：本段的触发主体是 **bridging 阶段的 contract-builder 子代理**（矩阵生成者 + GLAF4 Delegation 段产出者）。glaf4-test 已统一到 glaf4-dev（v2.1 §1.3），矩阵设计委托改为 glaf4-dev 实施委托全链路。
 
-**强制性澄清（v0.13 §52 B1）**：full workflow 生成 test-matrix.md 本身是**必选动作**（`test-matrix-ready`/`test-matrix-complete` 门禁强制）；**可选的是工具选择**——GLAF4 Java 项目可选用 glaf4-tests 流水线做精细矩阵设计，非 GLAF4 项目用内置 test-strategy skill。两条路都必须产出非空 `test-matrix.md` + contract `## Test Matrix` 段 + `tf state rebuild`。
+**强制性澄清（v0.13 §52 B1 + v2.1）**：full workflow 生成 test-matrix.md 本身是**必选动作**（`test-matrix-ready`/`test-matrix-complete` 门禁强制）；GLAF4 Java change 走 glaf4-dev 实施委托（生产+测试整体委托七模式流），team-flow 矩阵骨架定位为**审计基线**（回灌后对比 vNext 覆盖）。
 
-**触发条件**：`project_type == glaf4-java`（Spring Boot / JUnit 5 / Mockito）。
+**触发条件**：`project_type == glaf4-java`（pom.xml/build.gradle + Spring Boot/JUnit5/Mockito）∧ glaf4-dev 插件可用（运行时探测 delegation_mode ≠ off）。
 
 **协议**：
-1. contract-builder 检测项目技术栈（读取 `pom.xml` / `build.gradle` 判断是否 GLAF4 Java）
-2. GLAF4 项目 → 提示用户：「检测到 GLAF4 Java 项目，是否调用 `glaf4-test:glaf4-tests` 做精细测试矩阵设计？」
-3. 用户同意 → 调用 `glaf4-test:glaf4-tests-design` 生成 `test-matrix.json`
-4. `glaf4-tests-validate` 校验矩阵完整性
-5. `tf test-matrix-export <test-matrix.json> <change-dir>/test-matrix.md` 转换为 team-flow 格式
-6. 用户确认（轻量版 DP-A）
-7. contract 中添加 `## Test Matrix` 段引用 + `tf state rebuild` 捕获 test_matrix_hash
+1. contract-builder 运行时探测（`detectGlaf4Delegation`，v2.1 §4）
+2. 命中 GLAF4 Java → 产出 `## GLAF4 Delegation` 段（mode + write_set_boundary + 权限位，v2.1 §6.1/§6.2），**实施委托交接**——完整协议见 contract-builder `references/glaf4-delegation.md`
+3. 委托 run 回灌 → `tf test-matrix-export`（v2，支持 vNext）转 team-flow 12 列 MD 作为**审计基线**（v2.1 §5）
+4. 证据回灌：`tf glaf4-evidence-export` → `tf test record --from`（v2.1 §7）
+5. `tf glaf4-delegation confirm`（DP-4 委托确认 5 项）+ `verify-write-set`/`verify-tasks`（双层对账，v2.1 §6.3/§6.6）
+
+**混合栈串行承接（v2.1 §6.8，L1 明确）**：委托仅限 Java 文件边界（src/main/**、src/test/** 的 Java 面）；change 内非 Java 文件（SQL DDL / src/main/resources / 前端）由 build-executor 在委托 run 终局后、closing 前**串行承接**（S1 单 wave 计划不新增 wave）。这是与 glaf4-dev 租约模型唯一兼容的选项——委托 run 期间主线程零写入，非 Java 承接必须在 run 终局释放租约后。
 
 **非 GLAF4 项目**：contract-builder 使用预加载的 test-strategy skill 直接生成 `test-matrix.md`（同等强制）。
 
-**用户拒绝 glaf4-tests 时**：回退内置 test-strategy 生成（不是跳过矩阵）。确无测试需求的特例走显式 skip + 理由。
+**委托不可用（glaf4-dev 未装 / delegation_mode=off / 用户拒绝）**：回退 build-executor 实施 + 内置 test-strategy 生成矩阵（不是跳过矩阵）。**两类 skip 区分**：① 委托路径（glaf4-delegation 模式）矩阵是审计基线，`test_matrix_skipped` 被禁止（v2.1 §6.3 skip 禁令，唯一例外 TEST_BOOTSTRAP 零测试）；② 非委托路径确无测试需求（纯文档/纯配置）才走显式 skip + 理由（v0.13 §48.2 可审计豁免）。

package/templates/execution-contract.md

@@ -69,13 +69,25 @@ wave 才可以开始。`parallel` 只表示允许在宿主支持并发派发时
 ## Execution Mode
 
 - **可用方式与推荐**：`tf execution recommend <change-dir> [--wave <id>:<parallel|serial>:<task,...>[:<depends-on,...>]]`
-- **用户确认的模式**：`sdd` | `inline` | `batch-inline`
+- **用户确认的模式**：`sdd` | `inline` | `batch-inline` | `glaf4-delegation`
 - **推荐理由 / 项目事实**：
 - **非推荐选择的风险确认**：`--acknowledge-recommendation`（若适用）
 - **执行计划命令**：`tf execution plan <change-dir> --mode <mode> --confirm --reason <text> --wave <id>:<parallel|serial>:<task,...>[:<depends-on,...>] [--acknowledge-recommendation]`
 - **允许的修订**：将已有计划保留/升级为 `sdd`；先重新 recommend，并以 `--confirm` 生成新 revision 和清除旧 receipt；不允许降级：`tf execution revise <change-dir> --mode sdd --confirm --reason <text> --wave <id>:<parallel|serial>:<task,...>[:<depends-on,...>] [--acknowledge-recommendation]`
 - **计划 revision / artifact hash**：
 
+## GLAF4 Delegation（v2.1 §6.1/§6.2，GLAF4 Java change 实施委托时填写）
+
+> 运行时探测（`tf glaf4-delegation detect <root>`）命中 GLAF4 Java 且 glaf4-dev 可用时产出本段。write_set_boundary 权威源 = 本段；机械对账读 `.superpowers/glaf4/write-set.json`（`tf glaf4-delegation confirm` 写入）。
+
+- mode: FEATURE_TDD | BUGFIX_REGRESSION | REFACTOR_PROTECTED | COMPLETE_UNIT_TESTS | COMPLETE_INTEGRATION_TESTS | TEST_BOOTSTRAP
+- permission: after-red | none(test-only) | allowed+baseline_green_required
+- write_set_boundary:
+  - <相对 target_root 的 Java 文件路径，如 src/main/java/com/example/OrderService.java>
+- target_root: <工程根绝对路径>
+- delegation_mode: auto | manual | off
+- glaf4_dev_version: <运行时探测的插件版本，如 0.3.0>
+
 ## Verification Dimensions
 
 | 维度 | 状态 | 发现 |