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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.5.0-beta",
+  "version": "1.7.0-beta",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [
@@ -58,6 +58,7 @@
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "js-yaml": "^4.1.0",
+    "marked": "^15.0.12",
     "zod": "^3.24.4"
   },
   "devDependencies": {

package/prompts/approval/acp-pipeline.md

@@ -0,0 +1,104 @@
+# Approval · ACP Pipeline (Approval Compiler Pipeline)
+
+> Router for `/specflow:approval` **Stage 12** when `acp.pipeline=acp/v2` (recommended for non-lightweight changes).
+> Legacy segmented flow remains valid; ACP adds **lint**, **AI review**, and **bundle** gates.
+
+---
+
+## Pipeline (hard order)
+
+```text
+Phase 1  Analyze     → analysis.json + IR planner (chat gate)
+Phase 2  IR Freeze   → index.yaml (+ interfaces[].frozen, feature_slices, acp.review)
+Phase 3  Skeleton    → parts 01–03, 04-detail-core, 06/09/10
+Phase 4  Slot Map    → batched parts 04.4–04.9 (vertical slice first)
+Phase 5  AI Review    → Stage 12e in-session (prompts/approval/ai-review.md) — **inside /specflow-approval**
+Phase 6  finalize      → specflow approval finalize <change> [--bundle] [--render]
+Phase 7  render        → specflow approval render <change> [--input] [--output]
+
+**Preferred**: one `finalize` after Map + AI review. Subcommands (`lint`, `assemble`, …) are for CI/debug only.
+```
+
+**Never** skip Phase 6a–6b with LLM paste. **Never** write `approval-unified.md` by hand when bundle is enabled.
+
+---
+
+## index.yaml ACP block
+
+```yaml
+acp:
+  pipeline: acp/v2
+  context_budget_tokens: 40000
+  output_budget_tokens: 8000
+  feature_slices:
+    - id: step-reporting
+      parts: [04.5-api-worker, 04.5-api-east, 04-detail-core]
+      interfaces: [I13, I14, I16, I17]
+  review:
+    enabled: true
+    required_pass: true
+```
+
+## interfaces[].frozen (IR freeze before Map)
+
+```yaml
+interfaces:
+  - id: I14
+    short: SubmitStepResult
+    change: scenario-job-compile
+    part: 04.5-api-worker
+    pairs_with: I13
+    layers: [L3]
+    frozen:
+      rpc: scheduler.Scheduler.SubmitStepResult
+      http_path: POST /internal/v1/tasks/{job_id}/step-results
+      status_enum: [passed, failed, skipped, error]
+```
+
+---
+
+## Multi-repo default
+
+- **True source**: `per_repo` — each repo `approval/` + `approval.md`
+- **Read-only view**: `approval bundle` from `approval-playbook.yaml`
+- Do **not** LLM-unify three repos into one primary `approval/parts`
+
+See `multi-repo-guidance.md` + `templates/approval-playbook.yaml`.
+
+---
+
+## Context packet (Map batch)
+
+Read only:
+
+1. `index.yaml` subset for this batch (ids + frozen fields)
+2. `analysis.json` verdicts (not full Pass essays)
+3. design/spec **snippets** for batch entities
+4. 1–2 anchor files for this batch
+5. guidance router (path only, not full paste)
+
+Do **not** reload entire four-artifact sets each batch.
+
+---
+
+## CLI reference
+
+| Command | Purpose |
+|---------|---------|
+| `approval render` | MD → standalone HTML (tables, GFM, mermaid via CDN) |
+| `approval finalize` | **Preferred** — full lint → review-check → check → assemble → bundle |
+| `approval lint` | Cross-part consistency (CI / debug) |
+| `approval review-pack` | Emit `review-packet.json` (debug; finalize auto-runs when needed) |
+| `approval review-check` | Validate `review-result.json` (debug) |
+| `approval check` | Part presence + lazy stub (debug) |
+| `approval assemble` | Deterministic Reduce (debug) |
+| `approval bundle` | Multi-repo readonly merge (debug; finalize can auto-run) |
+
+---
+
+## Related guidance
+
+- `segmented-generation.md` — Map anti-lazy L1–L10
+- `ai-review.md` — Stage 12e AI approval/revision
+- `runtime-guidance.md` — optional async/lease/cancel (when in scope)
+- `api-guidance.md` — optional multi-layer API contracts (when api_in_scope)

package/prompts/approval/ai-review.md

@@ -0,0 +1,145 @@
+# Approval · Stage 12e AI Review (审批 / 修订)
+
+> Runs **after** Map parts written, **before** `specflow approval finalize` completes.
+> Purpose: catch **long-document / multi-part semantic drift** that mechanical lint cannot judge; **revise parts in place**.
+
+**Scope**: checks apply to **any** segmented approval — not tied to a specific product, repo, or domain.
+Use `index.yaml` + `analysis.json` as the contract; do not inject checks from unrelated case studies.
+
+---
+
+## 0. Trigger
+
+Run when **any**:
+
+- `acp.review.enabled=true` in `index.yaml` (default for non-lightweight)
+- User asks for AI 审批 / 方案审查 / 一致性检查
+- `specflow approval finalize` paused at `review-required`
+
+---
+
+## 1. Prep (hard)
+
+```bash
+specflow approval finalize <change>   # pauses + writes review-packet.json if needed
+```
+
+Read:
+
+- `approval/review-packet.json` (checklist + lint diagnostics)
+- `approval/index.yaml` (inventory, design_points, frozen fields, parts_order)
+- `approval/analysis.json` (Pass verdicts — gaps to close)
+- **All** `approval/parts/*.md` in `parts_order`
+
+Optional domain packs (only when design **actually** touches that topic):
+
+- `runtime-guidance.md` — async job / lease / retry / cancel semantics
+- `api-guidance.md` — multi-layer API contracts
+- `frontend-guidance.md` — §4.6 depth
+
+---
+
+## 2. Review dimensions (long-document generic)
+
+These target **failure modes of long, batched documents** — inconsistency across parts written at different times.
+
+| ID | Category | Check (generic) |
+|----|----------|-----------------|
+| R1 | **Cross-part naming** | Same entity (service, table, interface, page, enum) uses **one** canonical name/id across §2, §4, diagrams, and `index.yaml`. No 「暂定 / 实现时 / 如 Xxx / TBD」 for listed inventory ids. |
+| R2 | **Decision traceability** | Each `decisions[]` / §2 row appears in §4 with concrete behavior — not only repeated in summary. |
+| R3 | **Inventory ↔ body** | Every `tables[]` / `interfaces[]` / `pages[]` / `design_points[]` entry in index has **substantive** content in its assigned `part`. No orphan ids; no body content for ids missing from index. |
+| R4 | **Depth parity** | Parts in the same `feature_slices` or batch have **comparable** depth. No pattern of one part fully detailed while sibling parts are one-line stubs. |
+| R5 | **Cross-reference integrity** | Internal refs use stable ids (`§4.5 I2`, `P3`, `Page·列表`, `T1`) — not bare 「详见 design/tasks」. Ref targets exist and match. |
+| R6 | **Diagram ↔ prose** | Sequence / flow diagrams agree with adjacent prose (actors, message names, order, error branches). |
+| R7 | **Contract completeness** | Each listed interface/page-api has minimum skeleton from Part E (fields, success example, **failure example**, error table) — depth scaled to `api_in_scope` / `ui_in_scope`. |
+| R8 | **Enum / state closure** | Status, enum, and terminal-state sets are **explicit and closed** wherever the doc defines them — no 「等」 or open-ended lists unless explicitly extensible by design. |
+| R9 | **Unclosed branches** | Every **mentioned** branch (retry, cancel, timeout, idempotency, rollback, concurrency) has a documented outcome — or is flagged `[待 refine 澄清: …]` with owner. Do **not** assume domain-specific branches (e.g. lease reclaim) unless design/analysis mentions them. |
+| R10 | **UI ↔ API alignment** | When `ui_in_scope`: §4.6 field names, types, and api refs align with §4.5 / `pages[].apis`. |
+| R11 | **Multi-repo parity** | When `multi_repo.enabled`: each repo slice in scope has proportionate depth; no 「主仓详、他仓 stub」 unless explicitly out of scope. |
+| R12 | **Stub purge** | No `TODO` / `待补充` / `此处省略` / placeholder-only sections in parts slated for assemble. |
+| R13 | **Verdict coherence** | §9 implementability / readiness matches §4 depth — no READY alongside unexplained NEEDS REFINEMENT or contradictory gates. |
+
+**Not in default scope**: product-specific rules (talos lease wipe, ingest whitelist, L2/L3 layering) — load the matching guidance pack **only** when the change design requires it.
+
+---
+
+## 3. Revision rules (hard)
+
+1. **Edit `approval/parts/*.md` only** — never edit assembled `approval.md` directly
+2. **Update `index.yaml` first** when changing frozen ids, rpc names, or inventory
+3. Each finding → fix in named `part` OR waive (`minor` only) with `waiver_reason`
+4. Re-run:
+
+```bash
+specflow approval finalize <change>
+```
+
+---
+
+## 4. Write review-result.json
+
+Path: `approval/review-result.json`
+
+```json
+{
+  "schema": "specflow.approval.review/v1",
+  "change": "<change-name>",
+  "reviewed_at": "2026-08-26T12:00:00Z",
+  "reviewer": "ai",
+  "verdict": "pass",
+  "summary": "Fixed cross-part naming for I3; expanded P2 error path in 04-detail-core",
+  "part_hashes": [
+    { "id": "04.5-api", "sha256": "<sha256-after-fixes>" },
+    { "id": "04-detail-core", "sha256": "<sha256-after-fixes>" }
+  ],
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "critical",
+      "category": "cross_part_naming",
+      "message": "I3 RPC name differs between §2 and 04.5-api",
+      "part": "04.5-api",
+      "status": "fixed"
+    },
+    {
+      "id": "F2",
+      "severity": "important",
+      "category": "unclosed_branch",
+      "message": "Retry path mentioned in §4.3 but no terminal outcome",
+      "part": "04-detail-core",
+      "status": "fixed"
+    }
+  ]
+}
+```
+
+| verdict | When |
+|---------|------|
+| `pass` | All findings `fixed`; strict lint pass; **`part_hashes` match current parts** |
+| `pass_with_waivers` | Only `minor` waived with `waiver_reason` |
+| `fail` | Any `critical` / `important` still `open` |
+
+**Waive policy**: only `minor` may be waived; critical/important must fix or escalate to user.
+
+**part_hashes (required when `acp.review.enabled`)**: After fixing parts, run `specflow approval review-hashes <change> --json` and copy the array into `review-result.json`. `review-check` fails if parts change after review without updating review-result.
+
+---
+
+## 5. User gate
+
+When a finding requires a **product/architecture choice** the artifacts do not resolve:
+
+```text
+[待用户确认] <topic>: options A / B / C — record choice as new decision + update affected parts
+```
+
+Stop finalize until user chooses; do not invent policy.
+
+---
+
+## 6. Announce
+
+```text
+AI Review: findings=<n> fixed=<n> waived=<n> verdict=pass|fail
+Next: specflow approval finalize <change>
+```

package/prompts/approval/generate.md

@@ -1412,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.
 
@@ -1420,7 +1421,7 @@ 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` |
@@ -1431,7 +1432,7 @@ When `approval/index.yaml` has `mode: segmented` (default for non-trivial §4),
 | 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).
 
@@ -1475,24 +1476,108 @@ User natural language, workset, or cross-repo design → `multi_repo.enabled=tru
 
 ### G.2 User gates (hard, before Stage 12a)
 
-1. **Document mode**: `unified` (一份合订) **or** `per_repo` (多份分仓).
-2. If **unified**: **主仓** `primary_repo` — only this repo holds `approval/` + final `approval.md`.
-3. Record in `index.yaml`; do not assemble until both answered.
+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 Unified 合订
+### 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.4 Per-repo 分仓
+### 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.5 Inventory
+### 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

@@ -69,25 +69,61 @@ multi_repo:
 ```text
 本需求跨 N 个仓库,审批技术文档如何产出?
 
-A) 一份合订文档 (unified) — 单份 approval.md,含各仓决策/接口/前端/Worker 切片
-B) 多份分仓文档 (per_repo) — 每个仓库各自一份 approval.md,仅写本仓范围
+A) 一份合订视图 (bundle) — 各仓 per_repo 真源 + CLI bundle 只读合订 (**推荐**)
+B) 多份分仓 (per_repo) — 每仓各自 approval.md（默认 Map 模式）
+C) 一份 LLM 合订 (legacy unified) — 仅当用户明确要求且无 bundle；不推荐
 
-请选择 A 或 B。
+请选择 A、B 或 C。
 ```
 
-### 2.1 Unified（一份合订）
+### 2.1 Bundle（推荐 — A）
 
-再询问:
+**真源**: 各仓 **per_repo** `approval.md` + `approval/parts/`（ACP Map 分片）。
 
-```text
-合订文档存放在哪个主仓?(approval.md 与 approval/ 工作区写在该仓 change 目录下)
+**只读合订**: 主仓 `approval-playbook.yaml` + `specflow approval bundle <primary.change>` → `approval-unified.md`（**无 LLM 合并**）。
+
+再询问主仓:
 
+```text
+合订 playbook 与 bundle 输出存放在哪个主仓?
 1) talos (平台)
 2) talos-web (控制台)
-3) talos-worker (Worker)
 …
+```
+
+**硬规则**:
+
+- `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）
 
-请选主仓 id。
+见 §2.3；`bundle.enabled: false`。
+
+### 2.3 Legacy unified LLM 合订（C — 不推荐）
+
+仅在用户 **明确要求** 且拒绝 bundle 时使用。再询问主仓:
+
+```text
+合订文档存放在哪个主仓?(approval.md 与 approval/ 工作区写在该仓 change 目录下)
 ```
 
 **硬规则**:
@@ -112,7 +148,7 @@ outputs:
     path: specflow/changes/scenario-job-compile/approval.md
 ```
 
-### 2.2 Per-repo（多份分仓）
+### 2.4 Per-repo（B 详情）
 
 **硬规则**:
 

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.
@@ -110,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

@@ -26,7 +26,7 @@ Workflow 通过路由 `Read` 路径加载 guidance；禁止写成「invoke `/mys
 
 另：前端详设结构由 `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（可选，优先于自动探测）