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

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（可选，优先于自动探测）

package/skills/specflow-approval/SKILL.md

@@ -116,21 +116,129 @@ 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):
+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`).
+
+---
+
+## Stage 1c: Multi-Repo Subagent Orchestration (主仓一键 · 子仓并行)
+
+**Trigger**: `multi_repo.enabled=true` **and** user chose **A (bundle)** or **B (per_repo only)** **and** session supports **Task** subagents (Cursor Agent / compatible harness).
+
+**User-facing promise**: user starts **once** from the **primary** repo (`/specflow:approval <primary.change>`). Orchestrator runs spoke approvals **in parallel**; primary **waits** for all spokes to finish `finalize` successfully, then runs **primary Map + finalize + bundle** (mode A).
+
+Read **`prompts/approval/multi-repo-spoke-subagent.md`** before dispatching subagents.
+
+### 1c.1 Preconditions (hard)
+
+1. User gate **A** answered → `document_mode: per_repo` + `multi_repo.bundle.enabled: true` + `primary_repo` set.
+2. Primary `approval/index.yaml` lists every `multi_repo.repos[]` with `id`, `change`, **`root_hint`** (absolute planning root).
+3. Primary `approval/approval-playbook.yaml` exists (copy from `templates/approval-playbook.yaml` or `templates/approval-playbook-talos-scenario-job-compile.yaml`); every **non-primary** source has explicit `root:` in playbook. **Spoke** `index.yaml` must set `multi_repo.bundle.enabled: false` (only primary enables bundle).
+4. **Scope map** recorded: which `parts` / `interfaces` / `pages` / `capabilities` belong to each repo (from primary index inventory — **split**, do not duplicate bodies across repos).
+5. If migrating from legacy **unified** (mode C): **split parts first** — move `04.6-ui` → web, Worker L2 → worker, platform keeps L3/DDL/compile; add cross-refs. Do not bundle until split is done.
+
+### 1c.2 Phase diagram
 
 ```text
-合订文档存放在哪个主仓? (talos / talos-web / talos-worker / …)
+[Primary orchestrator]
+  Stage 1b intake + user gate A + playbook + scope map
+  Stage 2–11 (closed-loop) — primary reads ALL repos' four artifacts
+  Stage 12a — primary index + playbook + overlay only (optional skeleton on primary)
+
+  ═══ PARALLEL (Task subagent × each non-primary repo) ═══
+  For each spoke in multi_repo.repos[] where repo.id != primary_repo:
+    Launch Task (generalPurpose) with multi-repo-spoke-subagent.md brief
+    Inputs: repo_id, planning_root=root_hint, change, role, scope, workset_root, primary_change
+    Spoke runs: 12a → 12b → 12e → finalize <spoke.change>  (NO --bundle)
+
+  ═══ WAIT GATE (orchestrator blocks) ═══
+  Collect each spoke return payload → all finalize_ok: true
+  If any blocked → STOP; report failing repo + diagnostics; do NOT bundle
+
+  ═══ PRIMARY (sequential) ═══
+  Stage 12b Map primary-scoped parts only
+  Stage 12e AI Review + finalize <primary.change>   # no --bundle yet if review pauses
+  Re-run finalize until primary ok
+
+  ═══ BUNDLE (primary only) ═══
+  specflow approval finalize <primary.change> --bundle --workspace-root <primary.planning_root> [--render]
+  Report: each per_repo approval.md path + approval-unified.md (readonly)
 ```
 
-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).
+**`--workspace-root`**: use the **primary repo planning root** (directory containing `specflow/changes/`), not the workset parent — unless every playbook `sources[]` entry sets explicit `root:` (recommended for web/worker).
 
-Single-repo → skip (`multi_repo.enabled=false`).
+### 1c.3 Subagent dispatch template
+
+For each spoke, launch **one** Task in parallel (same turn when possible):
+
+```text
+Task · Spoke approval · <repo_id>
+
+Read prompts/approval/multi-repo-spoke-subagent.md and execute spoke approval end-to-end.
+
+repo_id: <id>
+planning_root: <root_hint absolute path>
+change: <spoke change name>
+role: platform | web | worker
+primary_repo_id: <primary_repo>
+primary_change: <primary change name>
+workset_root: <parent containing all repos, optional>
+scope:
+  parts: [<part ids for this repo only>]
+  interfaces: [<I ids>]
+  pages: [<page ids>]
+  capabilities: [<cap ids>]
+cross_ref_policy: 跨仓细节用「见 <other-repo> approval §x」；禁止复制平台 DDL/Worker OpenAPI 全文到本仓
+
+Return the YAML payload from multi-repo-spoke-subagent.md § Return payload.
+```
+
+**Parallelism**: launch all spoke Tasks in **one** assistant message. Do **not** start primary Map §4 batches that belong to a spoke until spoke Tasks are dispatched (orchestrator may prepare primary skeleton while spokes run).
+
+### 1c.4 Wait gate & bundle (hard)
+
+Before primary `--bundle`:
+
+| Check | Action |
+|-------|--------|
+| Each spoke `finalize_ok: true` | else STOP |
+| Each spoke `approval.md` exists | Read path from return payload |
+| Primary `finalize` ok (no lint/review errors) | else fix primary parts first |
+| Playbook sources match actual per-repo parts | `specflow approval bundle <primary.change>` dry path via finalize |
+
+On success announce:
+
+```text
+Multi-repo approval complete (mode A):
+- talos/.../approval.md (platform)
+- talos-web/.../approval.md (web)
+- talos-worker/.../approval.md (worker)
+- talos/.../approval-unified.md (readonly bundle)
+Apply uses per_repo approval.md only.
+```
+
+### 1c.5 Fallback (no Task / subagent)
+
+If subagents unavailable, run spokes **sequentially** in the same session: `cd <root_hint>` → full spoke flow → return to primary. Same wait gate before bundle. **Never** skip per-repo finalize.
+
+### 1c.6 User confirmation
+
+After Stage 12a + scope map, ask once:
+
+```text
+将并行在 N-1 个子仓生成 approval（<repo list>），主仓完成后合订 bundle。确认继续?
+```
+
+On confirm: dispatch subagents + proceed. User does **not** run spoke CLIs manually.
 
 ---
 
@@ -455,7 +563,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 +577,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 +614,45 @@ 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`, **only the primary orchestrator** runs `finalize --bundle` **after** all spokes (Stage 1c wait gate) and primary finalize succeed. Produces readonly `approval-unified.md` from `approval-playbook.yaml`. **Apply 只用各仓 approval.md 真源。**
+
+Spoke subagents **must not** pass `--bundle`. See **Stage 1c**.
+
+Optional HTML: `specflow approval render <change>` or `finalize --render` → `approval.html` (browser-readable; mermaid via CDN).
 
 ### Monolithic fast path
 
@@ -586,22 +723,23 @@ 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 并写入各仓 `approval.md`?（多仓时将并行子仓 approval，完成后主仓合订 bundle）"
 
-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. **Multi-repo mode A/B**: run **Stage 1c** — dispatch spoke subagents in parallel → wait gate → primary Map/12e/finalize → `finalize --bundle --workspace-root <primary.planning_root>`.
+2. **Segmented (single-repo)**: `specflow approval finalize <change>` — do not paste assembled markdown manually; do not run lint/assemble subcommands separately unless debugging.
+3. **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-talos-scenario-job-compile.yaml

@@ -0,0 +1,29 @@
+# specflow.approval.playbook/v1 — TALOS scenario-job-compile 三仓合订示例
+# Copy to: specflow/changes/scenario-job-compile/approval/approval-playbook.yaml
+# Used after per_repo split: each repo has its own approval/parts + approval.md
+schema: specflow.approval.playbook/v1
+change: scenario-job-compile
+title: 场景作业编译与逐步上报（三仓合订）
+primary_repo: talos
+
+sources:
+  - repo: talos
+    change: scenario-job-compile
+    include_parts: all
+  - repo: talos-web
+    change: web-scenario-cases
+    root: /Users/gankang/TALOS-WORK/talos-web
+    include_parts: all
+  - repo: talos-worker
+    change: scenario-execution
+    root: /Users/gankang/TALOS-WORK/talos-worker
+    include_parts: all
+
+overlay:
+  - overlays/01-unified-scope.md
+
+assemble:
+  inject_headers: true
+  dedupe_appendix: true
+  output: approval-unified.md
+  readonly: true

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