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

package/skills/specflow-approval/SKILL.md

@@ -103,6 +103,33 @@ uiInScope=<yes|no>, stackCoverage=<complete|partial|missing>)."
 
 ---
 
+## Stage 1b: Multi-Repo Intake (多仓)
+
+**Trigger**: user **自然语言** specifies multiple repos (talos + talos-web + worker), workset
+with multiple planning roots, or cross-repo design/tasks.
+
+Read **`prompts/approval/multi-repo-guidance.md`**.
+
+1. Resolve `multi_repo.repos[]` — `id`, `label`, `role`, **per-repo `change`**, optional `root_hint`.
+2. **Read four refined artifacts from each repo** before Pass 1.
+3. **User gate (hard)** — ask before writing any approval file:
+
+```text
+跨 N 个仓库,审批技术文档如何产出?
+A) 一份合订视图 (bundle) — 各仓 per_repo 真源 + CLI bundle 只读合订 (**推荐**)
+B) 多份分仓 (per_repo) — 每仓各自 approval.md（默认 Map 模式）
+C) 一份 LLM 合订 (legacy unified) — 仅当用户明确要求且无 bundle；不推荐
+```
+
+4. **A (recommended)**: `document_mode: per_repo` + `multi_repo.bundle.enabled: true` + primary repo for playbook output; **B**: per_repo only; **C**: legacy unified (discourage).
+5. If **A or C** — ask **主仓** for playbook/bundle output path.
+6. Write `approval/index.yaml` → `multi_repo` + `acp.pipeline: acp/v2`.
+7. **Per_repo**: Stage 12 + ACP **per repo**; if **A**, run `specflow approval bundle` after all repos assemble.
+
+Single-repo → skip (`multi_repo.enabled=false`).
+
+---
+
 ## Gate: Tech Stack Intake (0→1 / 四件套缺选型)
 
 **Trigger** (any):
@@ -344,8 +371,11 @@ Order and hard requirements (from `generate.md` §4.1–4.9):
    (2) `database-guidance.md` + SpecFlow guidance pack / `dbStack`; (3) live DDL/anchors.
    Priority: **project + live DDL > SpecFlow pack > LLM**. §4.4.1 must list 项目约定 + DB 技能.
    **Outline**: only `4.4.1–4.4.4` + `##### table`; DDL/字段说明/JSON = `**bold**`.
-5. **接口设计** — Before §4.5: `project-conventions-guidance.md` `topic=api`.
-   Then inventory + fields + examples + errors…
+5. **接口设计** — Before §4.5: (1) `project-conventions-guidance.md` `topic=api`;
+   (2) **`api-guidance.md`** — 契约面分层(L2/L3/L4 各独立 `In`)、RPC 锁名、proto/OpenAPI 可生成包;
+   (3) live proto/OpenAPI/anchors.
+   Then inventory + **each surface** fields + examples + errors + **Proto 草案**(新增 RPC).
+   **禁止** L2 HTTP 详写 + L4「内部调用」stub; **禁止**「暂定/如/实现时」RPC 名。
    **Outline**: only `4.5.1–4.5.3` + `##### In`; 请求体字段/示例/错误 = `**bold**`.
 6. **前端 / UI** — When `uiInScope=yes`: before §4.6:
    (1) `project-conventions-guidance.md` `topic=frontend`;
@@ -421,7 +451,7 @@ Each dimension produces a verdict (`READY` | `NEEDS REFINEMENT` | `BLOCKED`) wit
 ## Stage 12: Generate approval.md (Index → Map → CLI Reduce)
 
 Follow `generate.md` Part E (structure) and Part F (segmented pipeline + anti-lazy rules).
-Read `prompts/approval/segmented-generation.md` when `mode=segmented`.
+Read `prompts/approval/segmented-generation.md` when `mode=segmented`; read `prompts/approval/acp-pipeline.md` for ACP verify/finalize flow.
 
 **Output artifact**: `specflow/changes/<name>/approval.md`  
 **Workspace** (segmented): `specflow/changes/<name>/approval/` — `index.yaml`, `analysis.json`, `parts/*.md`, `manifest.json`
@@ -435,7 +465,7 @@ Read `prompts/approval/segmented-generation.md` when `mode=segmented`.
 
 Copy `templates/approval-index.yaml` → `approval/index.yaml`; fill `tables[]` / `interfaces[]` / `pages[]` with stable ids and `part` paths **before** any Map batch.
 
-**Anti-lazy (hard)**: when segmented, **never** one-shot the full `approval.md`; **never** stub parts (`TODO` / `待补充` / empty); **always** finish with CLI Reduce (12d).
+**Anti-lazy (hard)**: when segmented, **never** one-shot the full `approval.md`; **never** stub parts (`TODO` / `待补充` / empty); **always** finish with `specflow approval finalize` (Stage 12f).
 
 ### 12a Index + Skeleton
 
@@ -459,7 +489,10 @@ Respect `index.batching.*_per_call`. After each part: update `approval/manifest.
 Minimums (no shortcuts — see Part E hard rules 9–10, 18–20):
 
 - §4.4 batch: DDL + 字段说明 + 本迭代用法 per table; G3/G4 when applicable
-- §4.5 batch: meta + fields + success examples + **failure example (G2)** + error table per interface (**含不变**;完整格式,禁止精简)
+- §4.5 batch: **Read `api-guidance.md`**; one `In` per contract surface (L2 Worker HTTP / L3 RPC / L4 client RPC — no collapsing)
+- meta + fields + success examples + **failure example (G2)** + error table per interface (**含不变**)
+- **新增 RPC**: frozen `Service.Method` + proto field numbers + `google.api.http` + Gateway registration + Worker OpenAPI pointer
+- **禁止** 暂定/如/实现时 RPC; **禁止** L4 stub when L2 is fully written
 - §4.6 batch (when `uiInScope`): IDE skills/rules scan first; page/route + states + G6; §4.5 `In` refs
 
 ### 12c Optional chapters
@@ -469,16 +502,43 @@ Only if user accepted **and** `optional.s5/s7/s8: true` in index:
 - Insert `05-*` / `07-deploy` / `08-closed-loop` into `parts_order`
 - §8: one table only (from analysis)
 
-### 12d CLI Reduce (mandatory for segmented)
+### 12e AI Review (ACP — in-session, mandatory for non-lightweight)
+
+Read **`prompts/approval/ai-review.md`**. This step runs **inside `/specflow-approval`** — not as separate user-facing commands.
+
+1. Run once (or when paused): `specflow approval finalize <change>` — if `review-result.json` missing, CLI pauses and writes `review-packet.json`.
+2. Read `review-packet.json` + all parts; fix **parts only**; write `approval/review-result.json` (use `specflow approval review-hashes <change> --json` for `part_hashes`).
+3. Use **generic long-document checks** in `ai-review.md` (R1–R13). Load optional packs (`runtime-guidance.md`, `api-guidance.md`) **only** when the change design requires them.
+
+Set in `index.yaml`:
+
+```yaml
+acp:
+  pipeline: acp/v2
+  review:
+    enabled: true
+    required_pass: true
+```
+
+### 12f Finalize (one CLI — preferred)
+
+After Map + AI Review, **one command** finishes Verify → Reduce → optional bundle:
 
 ```bash
-specflow approval check <change>
-specflow approval assemble <change> --force
+specflow approval finalize <change> [--bundle] [--workspace-root <workset-root>]
 ```
 
-- `check` must pass with **zero errors** before assemble
-- Reduce is **deterministic** — no LLM stitching
-- Report final path: `specflow/changes/<name>/approval.md`
+Chains: `lint --strict` → `review-check` → `check` → `assemble --force` → `bundle` (when `multi_repo.bundle.enabled`).
+
+**Do not** ask the user to run `lint` / `review-pack` / `review-check` / `assemble` separately unless debugging a single stage.
+
+Low-level subcommands (`lint`, `review-pack`, `assemble`, …) remain for CI hooks and troubleshooting — not the default skill path.
+
+### 12g Multi-repo bundle
+
+When `multi_repo.bundle.enabled`, `finalize --bundle` (or auto) produces readonly `approval-unified.md` from `approval-playbook.yaml`. **Apply 只用各仓 approval.md 真源。**
+
+Optional HTML: `specflow approval render <change>` or `finalize --render` → `approval.html` (browser-readable; mermaid via CDN).
 
 ### Monolithic fast path
 
@@ -522,7 +582,9 @@ Present a summary to the user (**chat only** — these are not document chapters
 - Design quality verdict (PASS / WARNING / FAIL)
 - Implementability overall verdict (READY / NEEDS REFINEMENT / BLOCKED)
 - **AI pre-approval recommendation** (建议批准 / 有条件批准 / 退回 refine / 拒绝) + 理由
-- The path where `approval.md` will be written
+- The path where `approval.md` will be written (**all paths** if `multi_repo.document_mode=per_repo`)
+
+If `multi_repo.enabled`, confirm document mode + primary repo (unified) are already in `index.yaml`.
 
 Ask explicitly about **optional chapters** (record in `approval/index.yaml` → `optional.s5/s7/s8`):
 
@@ -547,22 +609,22 @@ If not forced segmented, ask generation mode:
 
 Do NOT run 12b until index + optional choices are confirmed.
 
-After 12b/12c, run `specflow approval check` and fix all errors before asking final write.
+After 12b/12c, run **Stage 12e AI Review** (fix parts, write `review-result.json` with `part_hashes`).
 
 Then ask:
 
-> "确认拼接并写入 `specflow/changes/<name>/approval.md`?"
+> "确认 finalize 并写入 `specflow/changes/<name>/approval.md`?"
 
-Do NOT assemble until the user confirms (unless they already confirmed end-to-end generation).
+Do NOT finalize until the user confirms (unless they already confirmed end-to-end generation).
 
 On confirmation:
 
-1. **Segmented**: `specflow approval assemble <change> --force` — do not paste assembled markdown manually.
-2. **Monolithic**: write `approval.md` directly (or parts + assemble).
+1. **Segmented**: `specflow approval finalize <change>` — do not paste assembled markdown manually; do not run lint/assemble subcommands separately unless debugging.
+2. **Monolithic**: write `approval.md` directly (or parts + finalize).
 3. Include only optional chapters the user accepted.
 4. Do **not** include「AI 预审建议」in the file.
 5. Do NOT change `phase` — it remains `refined`.
-6. Report the file path and next-step suggestions.
+6. Report the file path (and bundle path if multi-repo) and next-step suggestions.
 
 ---
 

package/templates/approval-index.yaml

@@ -50,3 +50,44 @@ meta:
   language: zh-CN
   tech_stack: unknown
   project_mode: brownfield
+
+# ACP (recommended for non-lightweight) — see prompts/approval/acp-pipeline.md
+acp:
+  pipeline: acp/v2
+  context_budget_tokens: 40000
+  output_budget_tokens: 8000
+  review:
+    enabled: true
+    required_pass: true
+  # feature_slices:
+  #   - id: core-flow
+  #     parts: [04-detail-core, 04.5-api]
+
+# 多仓时启用 (见 prompts/approval/multi-repo-guidance.md)
+# multi_repo:
+#   enabled: true
+#   document_mode: per_repo          # per_repo + bundle (推荐 A) | per_repo only (B) | unified (C)
+#   primary_repo: talos              # bundle 或 unified 时必填
+#   bundle:
+#     enabled: true
+#     playbook: approval-playbook.yaml
+#     output: approval-unified.md
+#     readonly: true
+#   repos:
+#     - id: talos
+#       label: 平台
+#       role: platform
+#       change: <change-name>
+#     - id: talos-web
+#       label: 控制台
+#       role: web
+#       change: <web-change-name>
+#   outputs:
+#     per_repo:
+#       - repo: talos
+#         change: <change-name>
+#         path: specflow/changes/<change-name>/approval.md
+#     bundle:
+#       repo: talos
+#       change: <change-name>
+#       path: specflow/changes/<change-name>/approval-unified.md

package/templates/approval-part.md

@@ -1,7 +1,7 @@
 <!--
   Approval part fragment — NOT a standalone document.
   Written under specflow/changes/<name>/approval/parts/<part-id>.md
-  Assembled by: specflow approval assemble <change>
+  Assembled by: specflow approval finalize <change>
 -->
 
 <!-- part-id: <must match filename without .md> -->

package/templates/approval-playbook.yaml

@@ -0,0 +1,28 @@
+# specflow.approval.playbook/v1 — copy to specflow/changes/<change>/approval/approval-playbook.yaml
+schema: specflow.approval.playbook/v1
+change: <change-name>
+title: <合订标题>
+primary_repo: talos
+
+sources:
+  - repo: talos
+    change: <platform-change>
+    include_parts: all
+  - repo: talos-web
+    change: <web-change>
+    root: /path/to/talos-web/planning-root
+    include_parts: [04.6-ui, 06-test]
+  - repo: talos-worker
+    change: <worker-change>
+    root: /path/to/talos-worker/planning-root
+    include_parts: [04.5-api-worker, 04.7-logic]
+
+# optional overlay markdown under approval/overlays/
+# overlay:
+#   - overlays/01-unified-scope.md
+
+assemble:
+  inject_headers: true
+  dedupe_appendix: true
+  output: approval-unified.md
+  readonly: true