@gordon.gan/specflow 1.4.6-beta → 1.7.0-beta

package/prompts/approval/generate.md

@@ -20,8 +20,9 @@ Before running this flow, the SKILL.md has confirmed:
 - Tech Stack Intake gate completed when greenfield or stack dimensions are missing
   (user confirmed 前端 / 后端 / 数据库与缓存 / 基础设施, or marked「不涉及」)
 - `uiInScope` resolved; when yes, FE 五元组 confirmed (or marked pending refine)
-- Anchor files extracted from `design.md` + `tasks.md`
+- Anchor files extracted from **each in-scope repo** when `multi_repo.enabled` (Stage 1b)
 - Optional: `specflow/specs/` baseline exists (for Pass 7)
+- When multi-repo: `multi_repo.document_mode` + (`primary_repo` if unified) confirmed by user
 
 You MUST read, in this order, before any analysis:
 
@@ -37,6 +38,11 @@ You MUST read, in this order, before any analysis:
 Do not skip any of the four required artifacts. If any is missing, stop and tell the
 SKILL.md caller which are missing.
 
+When **`multi_repo.enabled=true`**, read **`prompts/approval/multi-repo-guidance.md`** first.
+Load four artifacts **from every repo** in `multi_repo.repos[]` before analysis. Unified mode
+merges cross-repo content into **one** document stored under **`primary_repo`**; per_repo mode
+writes **separate** `approval.md` per repo (see §G).
+
 ---
 
 ## Part A: Closed-Loop Verification (7 Passes)
@@ -809,7 +815,7 @@ CREATE TABLE `orders` (
 **适用范围**:暴露 API / RPC / CLI 命令 / 跨模块函数接口的变更(含「协议不变但本迭代新消费」)。
 **项目类型适配**:Web/服务 → HTTP(+RPC);CLI → commander 等命令参数;库 → 导出函数签名。
 
-> **项目约定(先于起草)**:执行 `prompts/approval/project-conventions-guidance.md`,`topic=api`。  
+> **项目约定(先于起草)**:执行 `prompts/approval/project-conventions-guidance.md`,`topic=api`;再执行 **`prompts/approval/api-guidance.md`**(分层、RPC 锁名、proto/OpenAPI 可生成包)。  
 > 懒加载项目 API/错误码/鉴权/契约约定。有 UI 时 **§4.6** 另跑 `topic=frontend` + `frontend-guidance.md`
 > (勿把页面树塞进 §4.5)。  
 > **优先级**:项目约定 + 现网 OpenAPI/proto **>** SpecFlow §4.5 骨架 **>** LLM。  
@@ -859,6 +865,17 @@ CREATE TABLE `orders` (
 
 > **清单规则(硬)**:本迭代**不调用、不消费**的接口 **不列入** §4.5 清单。**一旦列入清单,无论变更类型是否为「不变」,均须按 §4.5.2 完整骨架输出**,不得精简、不得只写路径、不得跳过示例。
 
+> **分层规则(硬 — 防 B2 类混写)**:同一业务链上的 **Worker HTTP(L2)**、**平台 gRPC+HTTP 绑定(L3)**、**东向 client RPC(L4)** 必须是 **独立 `In`**,各自完整展开。禁止在 L2 写满 HTTP 后,用「内部经 I6/I7 调用」一行代替 L4 详设。见 `api-guidance.md` §1。
+
+**2b) 契约面分层(合订/三端推荐)**:
+
+| 层 | 面 | 清单要求 |
+|----|-----|----------|
+| L1 | 控制台 HTTP | 字段表 + 示例 + 错误 |
+| L2 | Worker→Gateway HTTP | OpenAPI schema 草案 + **完整** work 鉴权头示例 |
+| L3 | Gateway 转码 RPC | **冻结** RPC 名 + proto 字段号 + `google.api.http` + **Gateway 注册点** |
+| L4 | 平台 `client/<svc>/` RPC | 完整骨架;不变亦须字段表+示例,禁止 stub |
+
 **3) 通用错误码约定**(强制;按项目现网风格映射):
 
 | 错误类别 / 状态 | 典型 HTTP 或退出码 | 含义(本迭代) |
@@ -876,6 +893,8 @@ CREATE TABLE `orders` (
 3. **幂等 / 终态语义**:若存在上报类接口,写清「成功 ≠ 资源终态」等不变量(对齐 §2 决策)。
 4. **兼容缺省**:可选字段缺省时的兼容行为写进字段表「默认」列。
 5. **与流程对齐**:接口编号可被 §4.2/§4.3 时序与 §6 测试引用。
+6. **RPC 锁名(硬)**:新增/修改 gRPC **禁止**「暂定」「如 XxxRpc」「实现时命名/对齐」。须写死 `package.ServiceMethod`,并在决策表或 §4.5 元信息一致。见 `api-guidance.md` §2。
+7. **错误映射唯一(硬)**:条件 → **唯一** gRPC code → **唯一** HTTP;禁止「403/409(与 progress 同类)」「或现网」。
 
 ##### 4.5.2 逐接口详设(强制骨架)
 
@@ -888,8 +907,9 @@ CREATE TABLE `orders` (
 | 应用场景 | 谁、在什么用户动作/系统时机下调用 |
 | 协议 | 方法 + 路径(或 CLI 命令 / 导出函数签名) |
 | Content-Type / 编码 | 如 `application/json`(若适用) |
-| 对应 RPC / 内部名 | 若有(可写暂定名 +「实现时与 OpenAPI/proto 对齐」) |
+| 对应 RPC / 内部名 | **冻结**全名(例 `scheduler.SubmitStepResult`);proto 路径;**禁止**暂定/如/实现时 |
 | 鉴权 | 本接口鉴权要点(可引用通道表) |
+| Gateway 注册 | 新增 HTTP 绑定时:**文件+函数名**或 ProtoSets 路径(禁止只写「含新绑定」) |
 | 本迭代变更 | 一句话(新增字段 / 行为扩展 / 不变仅消费 …) |
 
 2. **请求体字段**(有则写;路径参数 / Query / CLI flags 用同级加粗标签分块,如 `**Query 参数**`,仍**不要**升为标题):
@@ -912,6 +932,13 @@ CREATE TABLE `orders` (
 
 7. **处理顺序**(可选):多步服务端合同用编号列表;与 §4.2/§4.3、§4.4 对齐。
 
+8. **Proto / OpenAPI 契约包**( **新增** 或 **修改 HTTP 绑定** 的 RPC — 硬):在接口小节末尾用加粗标签 `**Proto 草案**` / `**OpenAPI 指针**` 输出:
+   - proto:`rpc` 全名 + `message` 字段号表 + `google.api.http` 原文
+   - Gateway:与现网同类 RPC **同一注册点**的文件/函数,或 ProtoSets 条目
+   - Worker:OpenAPI 路径 + schema 字段与 L3 一致;HTTP 示例含 **全部** 必填头
+   - status/enum **闭合**,与现网 ingest 校验一致(禁止「等」、禁止逐步 ingest 写 `running` 除非同步改白名单)
+   详见 `api-guidance.md` §3。
+
 ##### 4.5.3 调用关系(推荐)
 
 用短文本或 Mermaid 概括调用方如何串起 `I1…In`(主路径一条线即可),便于实现与联调对照。
@@ -925,6 +952,8 @@ CREATE TABLE `orders` (
 
 - [ ] 有通道/鉴权表(或多通道说明)+ 本迭代接口清单(编号+变更类型+场景)
 - [ ] 有通用错误码约定 + 命名/错误风格约定
+- [ ] **分层**:L2 Worker HTTP / L3 RPC / L4 东向 RPC 各有独立 `In`,无「内部调用」stub
+- [ ] **RPC 已冻结**:无暂定/如/实现时;新增 RPC 含 proto 字段号 + http option + Gateway 注册点
 - [ ] 清单中**每个**接口(含**不变**)具备:元信息、字段表、成功请求/响应示例、**失败示例(G2)**、错误表
 - [ ] **不变**接口未因「无协议变更」而省略字段表/示例;内容与现网契约或锚点一致
 - [ ] 无「只有路径、无字段/无示例/无错误」的偷懒写法;示例与字段表一致
@@ -1312,14 +1341,16 @@ specflow init --artifact-language <language>
    (d) 每张表字段说明表(含「本迭代用法」)。
    禁止仅用散文描述 schema。MySQL DDL 禁止省略 ENGINE/CHARSET。零 DDL 迭代仍须展示当前基线 DDL —— 当表处于读/写路径时,禁止声称「不涉及数据库」。
 
-10. **§4.5 接口章节质量(硬规则)**:若变更涉及对外/跨服务/跨模块接口(含新增、修改、行为扩展、**协议不变但本迭代消费或调用**),§4.5 **必须**包含:
+10. **§4.5 接口章节质量(硬规则)**:起草前执行 `project-conventions-guidance.md` `topic=api` + **`api-guidance.md`**.若变更涉及对外/跨服务/跨模块接口(含新增、修改、行为扩展、**协议不变但本迭代消费或调用**),§4.5 **必须**包含:
     (a) 调用方/通道 + 鉴权总览,
     (b) 编号稳定的接口清单(变更类型含 新增/修改/行为扩展/不变·本迭代消费/不变·协议不变),
-    (c) 通用错误码映射与命名/错误风格约定,
-    (d) 清单中**每个**接口的元信息表、字段表(名/型/必填/默认/说明)、≥1 组成功请求示例与成功响应示例,
-    **(e) 每个接口 ≥1 组失败请求/响应示例(G2)**(「不变」接口亦须典型失败场景),
-    (f) 错误条件表。
-    禁止只写路径名的 stub。**一旦列入 §4.5 清单,无论协议是否变更,均须完整格式输出**;禁止因「与现网一致」而省略字段表/示例/错误约定(可标注「与现网一致」并仍给出完整骨架)。
+    (c) **契约面分层**:Worker HTTP / 平台 RPC+HTTP 绑定 / 东向 RPC **各自独立 `In`**,禁止 L2 详写、L4 一句 stub,
+    (d) 通用错误码映射(**唯一** gRPC code → **唯一** HTTP;禁止「或」「同类映射」),
+    (e) 清单中**每个**接口的元信息表、字段表、≥1 组成功请求/响应示例,
+    **(f) 每个接口 ≥1 组失败示例(G2)**,
+    (g) 错误条件表,
+    **(h) 新增/改 HTTP 绑定的 RPC**:冻结 RPC 全名 + proto 字段号 + `google.api.http` + Gateway 注册点 + Worker OpenAPI schema(禁止「暂定」「如」「实现时对齐」)。
+    禁止 stub。**一旦列入清单,无论是否不变,均须完整骨架**;可标注「与现网一致」但仍须贴字段表与示例。
 
 11. **§3 架构图须附设计要点(硬规则)**:每个架构 Mermaid 图后**必须**跟编号「设计说明 / 图要点」列表(边界/不变式/复用) —— 禁止仅复述节点名。仅有组件表不够。
 
@@ -1381,7 +1412,8 @@ When `approval/index.yaml` has `mode: segmented` (default for non-trivial §4),
 2. **Gate** — user confirms index inventory + optional chapters + mode
 3. **12b Map Append** — batched `04.4*` / `04.5*` / `04.6*` / `04.7–04.9`
 4. **12c Optional** — `05*` / `07` / `08` only when opted in
-5. **12d CLI Reduce** — `specflow approval check` then `specflow approval assemble --force`
+5. **12e AI Review** — fix parts; write `review-result.json` with `part_hashes` (see `ai-review.md`)
+6. **12f Finalize** — `specflow approval finalize <change>` (lint → review-check → check → assemble → bundle)
 
 **Reduce 禁止 LLM** — never stitch parts in chat or paste from memory.
 
@@ -1389,16 +1421,18 @@ When `approval/index.yaml` has `mode: segmented` (default for non-trivial §4),
 
 | # | Forbidden | Required |
 |---|-----------|----------|
-| L1 | One-shot full `approval.md` when `mode=segmented` | Write parts; CLI assemble |
+| L1 | One-shot full `approval.md` when `mode=segmented` | Write parts; `specflow approval finalize` |
 | L2 | Empty part, `< 20` chars, placeholder-only | Full section per Part E |
 | L3 | `TODO` / `待补充` / `此处省略` / bare `TBD` | Concrete text or `[待 refine 澄清: <元素>]` |
 | L4 | `详见 design/tasks` without §/In/Page id | Cross-ref `§4.5 I2` / `Page·列表` / `P1` |
 | L5 | New table/interface/page ids not in index | Update `index.yaml` first |
-| L6 | Skip DDL/字段表/失败示例 because "same as design" or "unchanged API" | G2–G6 minimum per entity; **不变**接口仍须完整 §4.5 骨架 |
+| L6 | Skip DDL/字段表/失败示例 because "same as design" or "unchanged API" | G2–G6 minimum; **不变**仍须完整 §4.5 骨架 |
+| L6b | Collapse L4 RPC into「内部调用 I7」; L2-only HTTP without proto | **分层**: L2/L3/L4 各独立 `In`;见 `api-guidance.md` §1 |
+| L6c | RPC「暂定/如/实现时命名」 | **冻结** `Service.Method` + proto 字段号;见 `api-guidance.md` §2–§3 |
 | L7 | Skip IDE skills/rules scan for §4.6 | `frontend-guidance.md` §3 before Map |
 | L8 | Paste skill/rule bodies verbatim | Readable Chinese + path in §4.6.1 |
 | L9 | Foreign `## N.` headings in parts | `###`/`####` only; CLI injects chapter headers |
-| L10 | Mark done without `specflow approval check` passing | Fix diagnostics; then assemble |
+| L10 | Mark done without finalize passing | Fix diagnostics; run `specflow approval finalize` |
 
 CLI lazy validation mirrors L2–L3 (`lazy_part_content` on assemble/check).
 
@@ -1430,3 +1464,120 @@ Do not reload entire four artifacts each batch.
 
 Do not rerun Pass 1–7 unless analysis is stale.
 
+---
+
+## Part G: Multi-Repo Approval (多仓)
+
+> Router: `prompts/approval/multi-repo-guidance.md`
+
+### G.1 Trigger
+
+User natural language, workset, or cross-repo design → `multi_repo.enabled=true`.
+
+### G.2 User gates (hard, before Stage 12a)
+
+1. **Document mode**: **A** bundle (per_repo + CLI bundle, recommended) **or** **B** per_repo only **or** **C** legacy unified LLM merge (discourage).
+2. If **A or C**: **主仓** `primary_repo` — playbook/bundle or unified workspace path.
+3. Record in `index.yaml`; set `acp.pipeline: acp/v2`; do not assemble until answered.
+
+### G.3 Bundle 合订视图 (recommended)
+
+- Each repo: own `approval/` + `specflow approval assemble <repo.change>`.
+- Primary repo: `approval-playbook.yaml` + `specflow approval bundle <primary.change>`.
+- Output: `approval-unified.md` (readonly concatenation, no LLM merge).
+
+### G.4 Legacy unified LLM 合订 (discouraged)
+
+- Read **every** repo's four artifacts + anchors.
+- `index.change` **should equal** primary repo's change name.
+- Header lists all repos; §2.3 / 附录 B per-repo tables.
+- CLI: `specflow approval assemble <primary.change>` from **primary** planning root.
+
+### G.5 Per-repo 分仓
+
+- Separate `approval/` (or monolithic `approval.md`) **in each repo**.
+- Each document scoped to that repo only; cross-ref sibling paths.
+- Separate assemble per repo.
+
+### G.6 Inventory
+
+Recommend `repo` on `tables[]` / `interfaces[]` / `pages[]` entries for unified mode traceability.
+
+---
+
+## Part H: ACP Pipeline (Approval Compiler Pipeline)
+
+> Router: `prompts/approval/acp-pipeline.md` · AI review: `prompts/approval/ai-review.md`
+
+### H.1 When to use
+
+| Signal | Action |
+|--------|--------|
+| Segmented mode (`approval/parts/`) | **Always** run ACP Verify before assemble |
+| Multi-repo bundle | per_repo assemble → `approval bundle` |
+| Long doc / cross-part inconsistency risk | Enable `acp.review` (Stage 12e) |
+
+### H.2 Pipeline stages
+
+```text
+Analyze (Pass 1–7) → IR Freeze (index.yaml + interfaces[].frozen)
+→ Map (batched parts) → lint → review-pack → AI Review (12e) → review-check
+→ check → assemble → bundle (optional)
+```
+
+### H.3 index.yaml `acp` block
+
+```yaml
+acp:
+  pipeline: acp/v2
+  review:
+    enabled: true
+    required_pass: true   # assemble --require-review gates on this
+```
+
+Also freeze RPC names in `interfaces[].frozen` before Map batches.
+
+### H.4 CLI
+
+**Preferred (skill default)**:
+
+```bash
+specflow approval finalize <change> [--bundle] [--workspace-root <root>]
+```
+
+| Command | Purpose |
+|---------|---------|
+| `specflow approval review-hashes <change> [--json]` | Emit `part_hashes[]` for `review-result.json` |
+| `specflow approval finalize <change>` | One-shot: lint → review-check → check → assemble → bundle |
+| `specflow approval lint <change> [--strict]` | Debug / CI: cross-part consistency |
+| `specflow approval review-pack <change>` | Debug: generate review packet |
+| `specflow approval review-check <change>` | Debug: validate review-result |
+| `specflow approval check <change>` | Debug: parts/index validation |
+| `specflow approval assemble <change> [--require-review]` | Debug: merge parts only |
+| `specflow approval bundle <change>` | Debug: multi-repo readonly merge |
+
+### H.5 Stage 12e AI Review (mandatory when `acp.review.enabled`)
+
+Runs **inside `/specflow-approval`** — not as separate user steps:
+
+1. `specflow approval finalize <change>` — pauses with `review-packet.json` if needed
+2. Agent reads `prompts/approval/ai-review.md` + parts; fixes parts; writes `review-result.json`
+3. Re-run `specflow approval finalize <change>`
+
+AI review targets **long-document failure modes**: cross-part naming drift, inventory/body mismatch, depth imbalance across batches, unclosed branches, diagram/prose divergence, §4.6/§4.5 misalignment — not product-specific case rules.
+
+Optional domain packs (`runtime-guidance.md`, `api-guidance.md`) apply **only when** design/analysis mentions those topics.
+
+### H.6 Render (MD → HTML)
+
+```bash
+specflow approval render <change> [--input approval.md] [--output approval.html]
+specflow approval finalize <change> --render   # optional: render after finalize
+```
+
+Standalone HTML with embedded CSS; Mermaid diagrams load from CDN when present.
+
+### H.7 Playbook bundle (multi-repo)
+
+Template: `templates/approval-playbook.yaml`. Lists per-repo `approval.md` paths; `bundle` concatenates with repo headers — **no LLM merge**.
+

package/prompts/approval/multi-repo-guidance.md

@@ -0,0 +1,238 @@
+# Approval · Multi-Repo (多仓) Guidance
+
+> Used by `/specflow:approval` when the user **自然语言指定多仓**、workset 含多个规划根、或
+> design/tasks 明确跨 `talos` / `talos-web` / `talos-worker` 等仓库。
+>
+> **目的**:按各仓四件套与锚点生成技术审批文档,并 **询问用户** 产出 **一份合订** 还是 **多份分仓**;
+> 合订时 **必须** 指定 **主仓** 存放 `approval.md` 与 `approval/` 工作区。
+
+---
+
+## 0. When to run
+
+| 信号 | 动作 |
+|------|------|
+| 用户说「三仓 / talos+web+worker / 多仓合订 / 前后端一体」 | 启用 `multi_repo.enabled=true` |
+| `specflow workset` / 会话上下文含多个 git 规划根 | 列出候选仓,请用户确认 |
+| 仅单仓 change,无跨仓表述 | `multi_repo.enabled=false`,走单仓流程 |
+| Hub + Spoke 联邦 | 见 §5;各 Spoke 可有不同 change id |
+
+Announce:
+
+```text
+Multi-repo approval: enabled | single-repo
+Repos in scope: talos(scenario-job-compile), talos-web(web-scenario-cases), …
+Document mode: (pending user) unified | per_repo
+Primary repo (if unified): (pending user)
+```
+
+---
+
+## 1. Resolve repos (硬顺序)
+
+1. **Parse user natural language** — 仓名、别名(平台/控制台/Worker)、change 名。
+2. **Cross-check workset** — `specflow workset list` / 用户给出的绝对路径;成员顺序 **不** 等于主仓。
+3. **Per repo, verify** (Read-only):
+   - `specflow/changes/<change>/.specflow.yaml` → `phase: refined`
+   - 四件套:`proposal.md`, `specs/**`, `design.md`, `tasks.md`
+4. **Record** in `approval/index.yaml` → `multi_repo.repos[]`:
+
+```yaml
+multi_repo:
+  enabled: true
+  document_mode: unified   # unified | per_repo — 用户确认后写入
+  primary_repo: talos      # unified 时必填
+  repos:
+    - id: talos
+      label: 平台
+      role: platform
+      change: scenario-job-compile
+      root_hint: /path/to/talos    #  agent 读取用,可选
+    - id: talos-web
+      label: 控制台
+      role: web
+      change: web-scenario-cases
+    - id: talos-worker
+      label: Worker
+      role: worker
+      change: scenario-execution
+```
+
+**禁止**在未 Read 各仓四件套前假设内容一致;change id **可以** 各仓不同。
+
+---
+
+## 2. User gate — 一份还是多份 (硬)
+
+在 Pass 1 之前或 Stage 12a 之前,**必须** 询问:
+
+```text
+本需求跨 N 个仓库,审批技术文档如何产出?
+
+A) 一份合订视图 (bundle) — 各仓 per_repo 真源 + CLI bundle 只读合订 (**推荐**)
+B) 多份分仓 (per_repo) — 每仓各自 approval.md（默认 Map 模式）
+C) 一份 LLM 合订 (legacy unified) — 仅当用户明确要求且无 bundle；不推荐
+
+请选择 A、B 或 C。
+```
+
+### 2.1 Bundle（推荐 — A）
+
+**真源**: 各仓 **per_repo** `approval.md` + `approval/parts/`（ACP Map 分片）。
+
+**只读合订**: 主仓 `approval-playbook.yaml` + `specflow approval bundle <primary.change>` → `approval-unified.md`（**无 LLM 合并**）。
+
+再询问主仓:
+
+```text
+合订 playbook 与 bundle 输出存放在哪个主仓?
+1) talos (平台)
+2) talos-web (控制台)
+…
+```
+
+**硬规则**:
+
+- `multi_repo.document_mode: per_repo`
+- `multi_repo.bundle.enabled: true`
+- `multi_repo.primary_repo: <id>` — playbook 与 bundle 输出路径
+- 各仓独立 Stage 12 + assemble；**全部 assemble 通过后** 在主仓执行 bundle
+- `acp.pipeline: acp/v2` 写入 `index.yaml`
+
+```yaml
+multi_repo:
+  document_mode: per_repo
+  primary_repo: talos
+  bundle:
+    enabled: true
+    output: approval-unified.md
+outputs:
+  per_repo: [ …各仓路径… ]
+  bundle:
+    repo: talos
+    change: scenario-job-compile
+    path: specflow/changes/scenario-job-compile/approval-unified.md
+```
+
+### 2.2 Per-repo only（B）
+
+见 §2.3；`bundle.enabled: false`。
+
+### 2.3 Legacy unified LLM 合订（C — 不推荐）
+
+仅在用户 **明确要求** 且拒绝 bundle 时使用。再询问主仓:
+
+```text
+合订文档存放在哪个主仓?(approval.md 与 approval/ 工作区写在该仓 change 目录下)
+```
+
+**硬规则**:
+
+- `multi_repo.document_mode: unified`
+- `multi_repo.primary_repo: <id>` **必填**
+- **工作区路径**(分片模式):
+  - `specflow/changes/<primary.change>/approval/index.yaml`
+  - `specflow/changes/<primary.change>/approval/parts/*.md`
+  - 产出:`specflow/changes/<primary.change>/approval.md`
+- CLI:`specflow approval assemble <primary.change>` **在主仓规划根**执行
+- 文档 §1.2 / §2.3 / 附录 B **必须** 按仓分表;Pass 6 锚点 **分仓列举**
+- 合订 **不是** 只写主仓 design;须合并各仓 specs/design/tasks 的跨端语义
+
+写入 `multi_repo.outputs.unified`:
+
+```yaml
+outputs:
+  unified:
+    repo: talos
+    change: scenario-job-compile
+    path: specflow/changes/scenario-job-compile/approval.md
+```
+
+### 2.4 Per-repo（B 详情）
+
+**硬规则**:
+
+- `multi_repo.document_mode: per_repo`
+- **每个** `repos[]` 条目独立:
+  - 在该仓 `specflow/changes/<repo.change>/approval/`(分片)或 `approval.md`(单体)
+  - 内容 **仅** 本仓 scope;交叉引用用「见 `<other-repo>` approval §x」
+- 各仓分别 `specflow approval assemble <repo.change>`(若在主仓 CLI,需 `--store` 或 cd 到该根)
+- **禁止**只在主仓写一份然后复制到其它仓
+
+写入 `multi_repo.outputs.per_repo[]`:
+
+```yaml
+outputs:
+  per_repo:
+    - repo: talos
+      change: scenario-job-compile
+      path: specflow/changes/scenario-job-compile/approval.md
+    - repo: talos-web
+      change: web-scenario-cases
+      path: specflow/changes/web-scenario-cases/approval.md
+```
+
+---
+
+## 3. Analysis & Map 上下文
+
+| 模式 | Read 范围 | index 库存 |
+|------|-----------|------------|
+| unified | 各仓四件套 + 各仓锚点 + 各仓约定 | `interfaces/pages/tables` 带 `repo` 字段(推荐) |
+| per_repo | **当前仓**四件套 + 本仓锚点 | 仅本仓实体 |
+
+**Unified 分片建议**:
+
+- `02-design-review` — 三仓决策表
+- `04.5-api` — 按 `repo` 或 L1/L2/L3/L4 分批;Worker 切片须 Read `api-guidance.md` + worker OpenAPI 路径
+- `04.6-*` — 仅 `ui_in_scope` 且 web 仓
+- 附录 B — 按仓允许/禁止路径
+
+**Inventory 扩展**(可选列):
+
+```yaml
+interfaces:
+  - id: I4
+    short: 逐步上报
+    change: scenario-job-compile
+    part: 04.5-api-worker
+    repo: talos-worker
+```
+
+---
+
+## 4. Document header (unified)
+
+合订 `approval.md` 头部 **必须** 声明:
+
+```markdown
+> **覆盖变更（多仓合订,主仓: talos）**:
+> - 平台 `talos/scenario-job-compile`
+> - 控制台 `talos-web/web-scenario-cases`
+> - Worker `talos-worker/scenario-execution`
+> **存放路径**: `specflow/changes/scenario-job-compile/approval.md`
+```
+
+---
+
+## 5. Hub / Federated 注意
+
+- Hub change id 可与 Spoke change id **同名或不同**;`multi_repo.repos[].change` 用 **各规划根内真实目录名**。
+- Hub 合同摘要可读 `--store`;Spoke approval **不**替代 Hub archive。
+- `coordination.yaml`(若有)可 Read;无则 chat 列出各仓 phase。
+
+---
+
+## 6. 自检
+
+- [ ] 用户已选 unified **或** per_repo
+- [ ] unified → `primary_repo` 已选且工作区在该仓
+- [ ] per_repo → 每仓输出路径已写入 `outputs.per_repo`
+- [ ] 各仓四件套已 Read;非主仓内容已进合订正文或分仓文档
+- [ ] Gate 摘要中列出 **所有** 将写入的 `approval.md` 路径
+
+---
+
+## 7. 与单仓关系
+
+`multi_repo.enabled=false` 时忽略本章;`change` 字段为当前规划根 change,行为与旧版一致。

package/prompts/approval/project-conventions-guidance.md

@@ -33,7 +33,7 @@ Conflict policy: project > SpecFlow guidance > LLM
 |--------------|----------------------|----------------|
 | `architecture` | 起草 **§3** 前 | 分层、模块边界、目录约定、禁止直连 |
 | `database` | 起草 **§4.4** 前(且有持久化) | 迁移工具禁令、命名、字符集、现网表规范 |
-| `api` | 起草 **§4.5** 前(且有对外/跨端接口) | 错误码、鉴权、契约/OpenAPI、通道 |
+| `api` | 起草 **§4.5** 前(且有对外/跨端接口) | 错误码、鉴权、契约/OpenAPI、通道;然后 **`api-guidance.md`**(分层、RPC 锁名、proto 可生成包) |
 | `frontend` | 起草 **§4.6** 前(且 `uiInScope=yes`) | 组件/状态/路由/API client/设计系统/**表单/测试/a11y** 等落地约定;须含 IDE skills/rules 扫描(见 `frontend-guidance.md` §3) |
 
 每个主题 **最多 Read 5 个文件**(配置列出的优先;自动探测时取最相关的前 5 个)。细节 references 仅在入口文件点名时再读(禁止 reference 链式跳转)。

package/prompts/approval/runtime-guidance.md

@@ -0,0 +1,64 @@
+# Approval · Runtime Semantics Guidance (optional domain pack)
+
+> **Optional** — load only when the change design touches async execution, leases, retries,
+> cancellation, LWW/idempotency keys, or result-ingest validation.
+>
+> **Not** part of default Stage 12e checklist. Use when analysis/design mentions these topics;
+> then add checks from §2 to AI review findings for **this change only**.
+
+---
+
+## 1. When to load
+
+| Signal in design/analysis | Action |
+|---------------------------|--------|
+| Job lease, reclaim, retry, duplicate execution | §1.1 |
+| User/system cancel, abort, teardown | §1.2 |
+| Step/job status enum vs ingest validator | §1.3 |
+| None of the above | **Skip this file** |
+
+---
+
+## 2. Mandatory decisions (pick one per topic — when in scope)
+
+### 2.1 Retry / reclaim vs accumulated state
+
+When the same execution key can run again, document how prior partial state is handled:
+
+| Option | Write in approval |
+|--------|-------------------|
+| **A wipe** | Clear prior results before re-run |
+| **B epoch/version** | Reads/writes scoped by epoch or version |
+| **C no retry** | Disable retry for this execution type |
+
+**Hard**: add decision row + §4 scenario + testable AC. **Forbidden**: leave unspecified when retry exists in design.
+
+### 2.2 Cancel / abort
+
+When cancel is in scope:
+
+- Document abort behavior (in-flight work, teardown, partial commit)
+- Terminal status for cancelled runs
+- §4.3 sequence for cancel path
+
+### 2.3 Status ingest / validator alignment
+
+When external ingest validates status values:
+
+- Document the **closed** allowed set
+- **Forbidden**: doc lists values outside validator unless same iteration changes validator
+
+---
+
+## 3. AI review hook (when loaded)
+
+Add targeted findings (category `runtime_semantics`) — do not apply to changes without these topics.
+
+```yaml
+design_points: [P<n>-retry-policy, P<n>-cancel]
+acp:
+  review:
+    enabled: true
+```
+
+Cross-links: `api-guidance.md` (contract layers), `ai-review.md` (generic R9 unclosed branches).

package/prompts/approval/segmented-generation.md

@@ -1,7 +1,7 @@
 # Approval · Segmented Generation (Map → CLI Reduce)
 
 > Used by `/specflow:approval` **Stage 12** when `mode=segmented` (default for non-trivial §4).
-> **Reduce 禁止 LLM**：拼接必须 `specflow approval assemble <change>` 或 `specflow approval check <change>`。
+> **Reduce 禁止 LLM**：拼接必须 `specflow approval finalize <change>`（或 debug：`check` / `assemble`）。
 
 ---
 
@@ -24,7 +24,8 @@ Copy template: `templates/approval-index.yaml` → `approval/index.yaml`.
 Gate                  →  user confirms index + optional chapters + mode
 12b Map Append        →  parts 04.4* / 04.5* / 04.6* / 04.7–04.9 (batched)
 12c Optional          →  parts 05* / 07 / 08 (only if optional.s5/s7/s8)
-12d CLI Reduce        →  specflow approval check → specflow approval assemble --force
+12e AI Review         →  fix parts; review-result.json + part_hashes
+12f Finalize          →  specflow approval finalize <change>
 ```
 
 **Never** skip 12d. **Never** paste assembled markdown from memory instead of running CLI.
@@ -40,7 +41,9 @@ Gate                  →  user confirms index + optional chapters + mode
 | L3 | `TODO` / `待补充` / `此处省略` / bare `TBD` | Concrete text or `[待 refine 澄清: <元素>]` with reason |
 | L4 | `详见 design/tasks` without §/In/Page id | Cross-ref `§4.5 I2` / `Page·列表` / `P1` |
 | L5 | Invent new table/interface/page ids not in index | Update index.yaml first, then write part |
-| L6 | Skip §4.4 DDL/字段表/失败示例 because "same as design" | Minimum viable implementer-ready detail per G2–G6 |
+| L6 | Skip §4.4 DDL/字段表/失败示例 because "same as design" | Minimum per G2–G6; **不变**仍须完整 §4.5 |
+| L6b | L2 HTTP only +「内部 I7」stub; or L4 one-liner | **分层** L2/L3/L4 各 `In`; `api-guidance.md` §1 |
+| L6c | RPC「暂定/如/实现时」 | **冻结**名 + proto 字段号; `api-guidance.md` §2–§3 |
 | L7 | Skip IDE skills/rules scan for §4.6 | frontend-guidance.md §3 before Map |
 | L8 | Paste skill/rule bodies verbatim | Readable Chinese + path in §4.6.1 table |
 | L9 | Write `## 4.` or foreign `## N.` in parts | Parts use `###`/`####`/`#####` only; CLI injects `## 4` |
@@ -86,8 +89,12 @@ For each batch, **Read only**:
 
 ### §4.5 part minimum (per interface)
 
-- meta table + fields + success req/resp + **failure example (G2)** + error table
-- **不变**接口亦须完整骨架(元信息/字段/成功与失败示例/错误表);禁止因「协议无变更」精简
+- Run **`api-guidance.md`** before batch
+- **One `In` per contract surface** (L2 Worker HTTP / L3 RPC+http / L4 client RPC) — no B2-style collapse
+- meta + fields + success req/resp + **failure example (G2)** + error table (**含不变**)
+- **新增/改 HTTP binding**: `**Proto 草案**` block — frozen RPC name, field numbers, `google.api.http`, Gateway registration, Worker OpenAPI path
+- HTTP examples for L2: **all** required work auth headers (not body-only)
+- **Forbidden**: 暂定 / 如 XxxRpc / 实现时命名 / 内部经 I7 一行代替 L4 详设
 
 ### §4.6 part minimum (per page)
 
@@ -104,16 +111,21 @@ Only if user opted in AND `optional.s5/s7/s8: true` in index:
 
 ---
 
-## 6. Stage 12d — CLI Reduce
+## 6. Stage 12e–12f — AI Review + Finalize
+
+**12e (in-session)**: Read `prompts/approval/ai-review.md`; fix parts; write `approval/review-result.json`.
+
+**12f (one CLI)**:
 
 ```bash
-specflow approval check <change>
-specflow approval assemble <change> --force
+specflow approval finalize <change> [--bundle] [--workspace-root <root>]
 ```
 
-- `check` MUST pass with **zero errors** before assemble  
-- Warnings (orphan parts) should be fixed or removed  
-- Report paths: `specflow/changes/<name>/approval.md`
+- First run without `review-result.json`: pauses, writes `review-packet.json`, agent completes 12e, re-run finalize
+- Chains lint → review-check → check → assemble → bundle (when enabled)
+- Subcommands (`lint`, `assemble`, …) are for CI/debug only
+
+See **`prompts/approval/acp-pipeline.md`**.
 
 ---
 

package/skills/GUIDANCE_PACKS.md

@@ -24,9 +24,9 @@ Workflow 通过路由 `Read` 路径加载 guidance；禁止写成「invoke `/mys
 | 主题 | `architecture` → §3；`database` → §4.4；`api` → §4.5；`frontend` → §4.6（有 UI；含 IDE skills/rules 落地扫描） |
 | 上限 | 每主题约定文件最多 **3**（helper）；前端专题合计约定+IDE skills/rules ≤ **5**（见 `frontend-guidance.md` §3） |
 
-另：前端详设结构由 `prompts/approval/frontend-guidance.md` 驱动（`uiInScope`、栈五元组、G5/G6、Visual Loop）；与 DB 的 `database-guidance.md` 对称，**暂无**独立 `skills/frontend` guidance pack。
+另：前端详设结构由 `prompts/approval/frontend-guidance.md` 驱动；接口/RPC 可生成契约由 **`prompts/approval/api-guidance.md`** 驱动（分层 L2/L3/L4、RPC 锁名、proto/OpenAPI 包）。与 DB 的 `database-guidance.md` 对称。
 
-**分片生成（非 trivial §4）**：`prompts/approval/segmented-generation.md` + `templates/approval-index.yaml`；Map 写 `approval/parts/`，Reduce 用 `specflow approval assemble`（禁止 LLM 拼接）。
+**分片生成（非 trivial §4）**：`prompts/approval/segmented-generation.md` + `prompts/approval/acp-pipeline.md` + `templates/approval-index.yaml`；Map 写 `approval/parts/`，Stage 12e AI Review 后 **`specflow approval finalize`**（一键 lint → review-check → assemble → bundle）。多仓合订用 `templates/approval-playbook.yaml`。
 
 ```yaml
 # specflow/config.yaml（可选，优先于自动探测）