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

package/skills/specflow-approval/SKILL.md

@@ -116,19 +116,15 @@ Read **`prompts/approval/multi-repo-guidance.md`**.
 
 ```text
 跨 N 个仓库,审批技术文档如何产出?
-A) 一份合订 (unified) — 单份 approval.md
-B) 多份分仓 (per_repo) — 每仓各自 approval.md
+A) 一份合订视图 (bundle) — 各仓 per_repo 真源 + CLI bundle 只读合订 (**推荐**)
+B) 多份分仓 (per_repo) — 每仓各自 approval.md（默认 Map 模式）
+C) 一份 LLM 合订 (legacy unified) — 仅当用户明确要求且无 bundle；不推荐
 ```
 
-4. If **A** — ask **主仓** (stores `approval.md` + `approval/` workspace):
-
-```text
-合订文档存放在哪个主仓? (talos / talos-web / talos-worker / …)
-```
-
-5. Write `approval/index.yaml` → `multi_repo` with user choices + `outputs`.
-6. **Unified**: Stage 12 workspace + `specflow approval assemble` run in **primary** planning root only.
-7. **Per_repo**: repeat Stage 12 + assemble **per repo** (scope = that repo only).
+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`).
 
@@ -455,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`
@@ -469,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
 
@@ -506,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
 
@@ -586,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

@@ -51,11 +51,28 @@ meta:
   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: unified   # unified | per_repo — 用户确认后填写
-#   primary_repo: talos      # unified 时必填
+#   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: 平台
@@ -66,7 +83,11 @@ meta:
 #       role: web
 #       change: <web-change-name>
 #   outputs:
-#     unified:
+#     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.md
+#       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