---
name: phase-driver
description: 统一阶段循环驱动（后端模块 / 前端阶段共用，由 phase 参数区分）。定位当前未完成单元并派发 feature-spec，全完成则派发 milestone。幂等可重入。
user-invocable: false
allowed-tools: Read Write Edit Skill Glob Grep AskUserQuestion Bash(git branch *) Bash(git checkout *) Bash(git rev-parse *) Bash(git status *) Bash(git symbolic-ref *) Bash(git tag *) Bash(find *) Bash(ls *)
---

**所有输出必须使用中文。**

# phase-driver

## 职责说明

统一阶段循环驱动，由 `phase` 参数区分后端模块循环（`phase=backend`）与前端阶段循环（`phase=frontend`）。由 `coding-start` 初次派发，`feature-review` approve 后回调，均携带 `{ phase }` 参数。幂等可重入。

---

## phase=backend（后端模块循环）

### 步骤 B1：定位当前模块与 REQ 列表

读取 `docs/08-模块任务管理.md § 二`，按文中模块顺序扫描，找到第一个未完成的模块作为 `current_module`，并从其条目中提取 `module_id`（后续分支名 `module-<module_id>` / 里程碑判定都用它）。

**模块完成判定**（双重校验，二者皆满足才算完成）：
- 该模块条目下 `里程碑:` 字段 == `milestone/<module_id>`
- `git tag -l 'milestone/<module_id>'` 能查到对应 tag

二者任一缺失 → 视为未完成。

找到 `current_module` 后，从 `docs/08 § 二` 该模块条目下的 REQ 子项中，按列出顺序提取 `req_list[]`（docs/08 § 二 是 REQ 顺序权威，不读 docs/02）。

约束：
- 任何文件读取或解析失败 → 打印错误并停止

### 步骤 B2：未找到未完成后端模块的处理

若步骤 B1 未找到任何未完成后端模块（理论上由 `coding-start` / `feature-review` approve 后的回调触发，属异常路径）：

- 打印诊断："`phase-driver(backend)` 未发现未完成后端模块。请通过 `/erp-workflow:coding-start` 入口重新驱动——coding-start 会按 docs/08 § 二/§ 三 自动路由到正确阶段。"
- 结束本 skill，不派发下游

### 步骤 B3：确保处于模块分支

目标分支：`module-<module_id>`（例：`module-sys`）

- 当前已在该分支 → 继续步骤 B4
- 该分支已存在但当前不在 → `git checkout module-<module_id>`
- 该分支不存在 → 先切到本地默认分支（`main` 或 `master`，已由 `milestone` 的本地 merge 累积所有已完成模块）作为干净 base，再 `git checkout -b module-<module_id>`

任何错误（定位不到默认分支 / 切换前工作树脏 / checkout 失败）→ 打印诊断信息后硬停，不自动 stash，不强制覆盖。

### 步骤 B4：计算已完成 REQ 集合 `done_reqs[]`

对 `req_list[]` 中每个 REQ，检查 `docs/superpowers/reviews/` 下是否存在该 REQ 的 review 文件（文件名含 REQ id），且文件中 `verdict:` 字段为 `approve`。两条件皆满足 → 收入 `done_reqs[]`。

每次进入本 skill 都重新计算（不缓存），保证中断 / 重跑后能从最新进度继续。

### 步骤 B5：打印状态

内联打印（不引用任何模板文件），格式示例：

```
[phase-driver] 阶段=backend
  分支：module-<module_id>
  进度：<done_count>/<total_count> REQ 完成
  下一：<first_incomplete_REQ_id> <REQ_title>
```

### 步骤 B6：派发

- 存在未完成 REQ → `Skill(feature-spec)`，参数 `{ phase: "backend", id: <first_incomplete_REQ_id>, name: <REQ_title> }`
- 本模块所有 REQ 全部完成 → `Skill(milestone)`

---

## phase=frontend（前端阶段循环）

### 步骤 F1：prototype 门禁

用 `find <project-root>/prototype -name "*.html"` 或 `ls <project-root>/prototype/` 检查项目根 `prototype/` 目录：

- 找到 ≥1 个 `*.html` → 通过，进入步骤 F2
- 未找到（目录不存在或无 html 文件）→ `AskUserQuestion` 告知用户需要在 `prototype/` 下放置至少一个 HTML mockup 文件后重跑入口，然后停止

### 步骤 F2：准备 FE 清单

读 `docs/08-模块任务管理.md § 三` 中"功能:"项：

**情形 A：已有 FE bullet**

若已存在 `- [ ] FE-NN ...` 或 `- [x] FE-NN ...` 行 → **加载**：逐行解析得 `fe_list[]`，每项为 `{ fe_id, name, status, associated_reqs[], associated_prototypes[] }`。行格式不符规范 → 硬停并打印问题行。

**情形 B：仅有 HTML 注释占位（无 FE bullet）**

→ **推导**：

1. 读取 `prototype/**/*.html`、`docs/01-需求清单/**/*.md`、`docs/05-API接口契约.md`
2. 以**业务功能**为单位拆分（同流程多屏可合 1 个 FE；一个 HTML 含多功能可拆多个 FE；无 UI 的 REQ 不产生 FE）。每个 FE 含：`{ fe_id: FE-NN, name, associated_reqs[], associated_prototypes[] }`，prototype 路径可带 anchor 区分文件内多区域
3. **写入 § 三 "功能:" 项**（替换 HTML 注释占位），每行格式：

   ```
   - [ ] FE-NN 功能名 ｜ 关联 REQ：REQ-A, REQ-B ｜ 关联原型：prototype/<file>.html
   ```

   保留 `- 整体里程碑: —` 行不动；写入后解析得 `fe_list[]`，继续步骤 F3

### 步骤 F3：检查前端里程碑状态

读 `docs/08 § 三 整体里程碑:` 字段，并用 `git tag -l 'milestone/frontend-phase'` 校验：

- 字段为 `milestone/frontend-phase` 且 tag 存在 → 打印"前端阶段已完成"并停止（冗余保护，正常由 `coding-start` 拦截）
- 否则（字段为 `—` 或 tag 不存在）→ 进入步骤 F4

### 步骤 F4：确保处于 frontend-phase 分支

目标分支：`frontend-phase`

- 当前已在该分支 → 继续步骤 F5
- 该分支已存在但当前不在 → `git checkout frontend-phase`
- 该分支不存在 → 先切到本地默认分支（`main` 或 `master`）作为干净 base，再 `git checkout -b frontend-phase`

任何错误（定位不到默认分支 / 工作树脏 / checkout 失败）→ 打印诊断信息后硬停，不自动 stash，不强制覆盖。

### 步骤 F5：识别已完成的 FE

扫 `docs/superpowers/reviews/` 下文件名含 `-FE-` 的 review 文件（如 `<YYYY-MM-DD>-FE-NN.md`），`verdict: approve` 的收入 `done_fes[]`。每次进入重新计算，不缓存。

### 步骤 F6：打印状态

内联打印（不引用任何模板文件），格式示例：

```
[phase-driver] 阶段=frontend
  分支：frontend-phase
  prototype HTML 数：<n> 个
  进度：<done_count>/<total_count> FE 完成
  下一：<FE-NN> <FE_name>
```

### 步骤 F7：派发

- 存在未完成 FE → `Skill(feature-spec)`，参数 `{ phase: "frontend", id: <FE-NN>, name: <FE_name>, associated_reqs: [...], associated_prototypes: [...] }`
- 所有 FE 全部完成 → `Skill(milestone)`

---

## 参考

- `docs/08-模块任务管理.md § 二`（后端模块元数据 + REQ 顺序权威，含 `里程碑:` 字段）
- `docs/08-模块任务管理.md § 三`（前端阶段元数据：整体里程碑 + FE 清单）
- `docs/superpowers/reviews/*.md`（REQ / FE 级进度事实——`verdict: approve` 即完成）
- 上游：`coding-start`（初次派发，携带 `{ phase }`）；`feature-review`（approve 后回调，携带 `{ phase }`）
- 下游：`feature-spec`（每个未完成 REQ / FE）；`milestone`（全部完成时）