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

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

@@ -0,0 +1,202 @@
+# 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) 一份合订文档 (unified) — 单份 approval.md,含各仓决策/接口/前端/Worker 切片
+B) 多份分仓文档 (per_repo) — 每个仓库各自一份 approval.md,仅写本仓范围
+
+请选择 A 或 B。
+```
+
+### 2.1 Unified（一份合订）
+
+再询问:
+
+```text
+合订文档存放在哪个主仓?(approval.md 与 approval/ 工作区写在该仓 change 目录下)
+
+1) talos (平台)
+2) talos-web (控制台)
+3) talos-worker (Worker)
+…
+
+请选主仓 id。
+```
+
+**硬规则**:
+
+- `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.2 Per-repo（多份分仓）
+
+**硬规则**:
+
+- `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/segmented-generation.md

@@ -0,0 +1,151 @@
+# 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>`。
+
+---
+
+## 0. When to segment
+
+| Condition | Mode |
+|-----------|------|
+| `tables > 2` OR `interfaces > 3` OR `pages > 2` OR `optional.s5=true` | **segmented** (mandatory) |
+| Else | ask user: segmented (recommended) or monolithic |
+| User chose monolithic | write `approval.md` directly OR parts + single assemble |
+
+Copy template: `templates/approval-index.yaml` → `approval/index.yaml`.
+
+---
+
+## 1. Pipeline (hard order)
+
+```text
+12a Index + Skeleton  →  index.yaml + analysis.json + parts 01–03 + 04-detail-core + stubs
+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
+```
+
+**Never** skip 12d. **Never** paste assembled markdown from memory instead of running CLI.
+
+---
+
+## 2. Anti-lazy rules (Map — LLM MUST NOT)
+
+| # | Forbidden | Required instead |
+|---|-----------|------------------|
+| L1 | One-shot full `approval.md` when `mode=segmented` | Write parts; assemble via CLI |
+| L2 | Empty part, `< 20` chars, or only HTML comments | Full section content per generate.md |
+| 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 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` |
+| L10 | Mark part `ok` without `specflow approval check` passing | Run check; fix errors; then assemble |
+
+---
+
+## 3. Stage 12a — Index + Skeleton
+
+**Write first:**
+
+1. `approval/index.yaml` — full `parts_order`, all `tables[]`/`interfaces[]`/`pages[]` with `part` paths  
+2. `approval/analysis.json` — Pass 1–7 + quality + implementability (chat-only fields ok)  
+3. Parts (minimum):
+   - `01-intro.md` … `03-architecture.md`
+   - `04-detail-core.md` (§4.1–4.3 only)
+   - `06-test.md`, `09-implementability.md`, `10-signoff.md` (may be stub-length only for structure in 12a, fill before assemble)
+
+**Chat gate:** show table/interface/page list from index; ask user to confirm before 12b.
+
+---
+
+## 4. Stage 12b — Map Append
+
+For each batch, **Read only**:
+
+- `approval/index.yaml`
+- `approval/analysis.json` (verdicts, not full Pass essays)
+- design/tasks/specs **snippets** for this batch's ids
+- lazy-loaded conventions (per topic caps)
+- anchor files for this batch (Pass 6 depth: file only)
+
+**Batching:** use `index.batching.*_per_call`. One part file per batch unit OR per index `part` field.
+
+**After each part write:** update `approval/manifest.json` part entry (`status: draft|ok`).
+
+### §4.4 part minimum (per table batch)
+
+- 4.4.1 row in batch leader file if first batch
+- ER if new entities
+- per-table: CREATE TABLE + 字段说明 + 本迭代用法
+- G3/G4 when applicable
+
+### §4.5 part minimum (per interface)
+
+- 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)
+
+- route + components + states + ≥1 of 空/加载/错态 (G6) + §4.5 `In` refs
+
+---
+
+## 5. Stage 12c — Optional chapters
+
+Only if user opted in AND `optional.s5/s7/s8: true` in index:
+
+- Insert `05-*` / `07-deploy` / `08-closed-loop` into `parts_order` at correct positions
+- §8: **one table only** (from analysis.json)
+
+---
+
+## 6. Stage 12d — CLI Reduce
+
+```bash
+specflow approval check <change>
+specflow approval assemble <change> --force
+```
+
+- `check` MUST pass with **zero errors** before assemble  
+- Warnings (orphan parts) should be fixed or removed  
+- Report paths: `specflow/changes/<name>/approval.md`
+
+---
+
+## 7. manifest.json (agent-maintained)
+
+```json
+{
+  "schema": "specflow.approval.manifest/v1",
+  "change": "<name>",
+  "parts": [
+    { "id": "01-intro", "path": "approval/parts/01-intro.md", "status": "ok" }
+  ]
+}
+```
+
+CLI overwrites manifest on successful assemble with sha256 sums.
+
+---
+
+## 8. Retry
+
+| Failure | Action |
+|---------|--------|
+| `lazy_part_content` on one part | Rewrite that part only; re-check |
+| `missing_part` | Write missing part or fix index |
+| `id_part_mismatch` | Align index `part` field with filename |
+| index wrong | Edit index.yaml; delete wrong parts; rerun affected Map batches |
+
+Do **not** rerun Pass 1–7 unless analysis is stale.

package/skills/GUIDANCE_PACKS.md

@@ -24,7 +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 拼接）。
 
 ```yaml
 # specflow/config.yaml（可选，优先于自动探测）

package/skills/specflow-approval/SKILL.md

@@ -103,6 +103,37 @@ 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) 一份合订 (unified) — 单份 approval.md
+B) 多份分仓 (per_repo) — 每仓各自 approval.md
+```
+
+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).
+
+Single-repo → skip (`multi_repo.enabled=false`).
+
+---
+
 ## Gate: Tech Stack Intake (0→1 / 四件套缺选型)
 
 **Trigger** (any):
@@ -344,8 +375,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`;
@@ -418,10 +452,74 @@ Each dimension produces a verdict (`READY` | `NEEDS REFINEMENT` | `BLOCKED`) wit
 
 ---
 
-## Stage 12: Generate approval.md
+## 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`.
+
+**Output artifact**: `specflow/changes/<name>/approval.md`  
+**Workspace** (segmented): `specflow/changes/<name>/approval/` — `index.yaml`, `analysis.json`, `parts/*.md`, `manifest.json`
+
+### 12.0 Mode selection (before writing)
+
+| Trigger | Mode |
+|---------|------|
+| `tables > 2` OR `interfaces > 3` OR `pages > 2` OR user opted §5 | **segmented** (mandatory) |
+| Else | ask user: **segmented** (recommended) or **monolithic** |
+
+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).
+
+### 12a Index + Skeleton
+
+Write **first** (Gate depends on this):
+
+1. `approval/index.yaml` — full `parts_order`, entity inventory, `optional.s5/s7/s8`, `mode`
+2. `approval/analysis.json` — Pass 1–7 + quality + implementability summaries
+3. `approval/parts/` skeleton:
+   - `01-intro.md` … `03-architecture.md`
+   - `04-detail-core.md` (§4.1–4.3 only)
+   - `06-test.md`, `09-implementability.md`, `10-signoff.md`
 
-Following the document structure and generation rules in `generate.md` Part E, produce
-`approval.md` inside the change directory at `specflow/changes/<name>/approval.md`.
+Use `templates/approval-part.md` fragment header; parts use `###`/`####` only — **no** foreign `## N.` headings.
+
+### 12b Map Append (batched §4.4 / §4.5 / §4.6 / §4.7–§4.9)
+
+Per batch, Read only: `index.yaml`, `analysis.json` digests, design/tasks/spec snippets for batch ids, lazy-loaded conventions (caps per topic), anchor files.
+
+Respect `index.batching.*_per_call`. After each part: update `approval/manifest.json` entry.
+
+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: **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
+
+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)
+
+```bash
+specflow approval check <change>
+specflow approval assemble <change> --force
+```
+
+- `check` must pass with **zero errors** before assemble
+- Reduce is **deterministic** — no LLM stitching
+- Report final path: `specflow/changes/<name>/approval.md`
+
+### Monolithic fast path
+
+When user chose `mode: monolithic` and lightweight inventory: write `approval.md` directly **or** parts + single assemble. Same Part E quality bars apply.
 
 Document chapter order (hard for included chapters):
 
@@ -436,7 +534,7 @@ Document chapter order (hard for included chapters):
 9. §9 可实施性评估
 10. §10 审批 — **仅人工签字栏**(无 AI 预审小节)
 
-Key rules:
+Key rules (all modes):
 
 - §1 truthful; Journey traces to §5 if present else named specs; Non-Goals with reasons.
 - **§2.2 技术选型**: required for greenfield or when four artifacts lack needed stack
@@ -461,9 +559,11 @@ 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**:
+Ask explicitly about **optional chapters** (record in `approval/index.yaml` → `optional.s5/s7/s8`):
 
 ```text
 是否将以下章节写入审批文档?
@@ -472,20 +572,36 @@ Ask explicitly about **optional chapters**:
 - §8 闭环性检查表: 要 / 不要
 ```
 
+If not forced segmented, ask generation mode:
+
+```text
+审批文档生成方式:
+- segmented (推荐): 分片写入 approval/parts/，CLI 拼接 approval.md
+- monolithic: 一次性写入 approval.md（仅轻量变更）
+```
+
+**After Stage 12a**, show index inventory (tables / interfaces / pages) and ask:
+
+> "确认 index 与可选章节后继续 Map 生成?"
+
+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.
+
 Then ask:
 
-> "确认生成审批文档并写入 `specflow/changes/<name>/approval.md`?"
+> "确认拼接并写入 `specflow/changes/<name>/approval.md`?"
 
-Do NOT write the file until the user answers the optional-chapter choices **and** confirms.
-If the user wants changes to the assessment, re-run the relevant Pass or dimension and
-update the summary before re-asking.
+Do NOT assemble until the user confirms (unless they already confirmed end-to-end generation).
 
 On confirmation:
 
-1. Write `approval.md` including only the optional chapters the user accepted.
-2. Do **not** include「AI 预审建议」in the file.
-3. Do NOT change `phase` — it remains `refined`.
-4. Report the file path and next-step suggestions.
+1. **Segmented**: `specflow approval assemble <change> --force` — do not paste assembled markdown manually.
+2. **Monolithic**: write `approval.md` directly (or parts + assemble).
+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.
 
 ---
 

package/templates/approval-index.yaml

@@ -0,0 +1,72 @@
+# specflow.approval.index/v1 — copy to specflow/changes/<name>/approval/index.yaml
+schema: specflow.approval.index/v1
+change: <change-name>
+generated_at: 2026-08-26T12:00:00+08:00
+mode: segmented
+ui_in_scope: false
+db_in_scope: true
+api_in_scope: true
+
+optional:
+  s5: false
+  s7: false
+  s8: false
+
+parts_order:
+  - 01-intro
+  - 02-design-review
+  - 03-architecture
+  - 04-detail-core
+  - 04.4-data
+  - 04.5-api
+  - 04.7-logic
+  - 04.8-config
+  - 04.9-compat
+  - 06-test
+  - 09-implementability
+  - 10-signoff
+
+design_points: [P1]
+decisions: [D1]
+
+tables: []
+interfaces: []
+pages: []
+capabilities: []
+
+batching:
+  tables_per_call: 3
+  interfaces_per_call: 3
+  pages_per_call: 3
+  capabilities_per_call: 1
+
+conventions:
+  architecture: []
+  database: []
+  api: []
+  frontend: []
+
+meta:
+  language: zh-CN
+  tech_stack: unknown
+  project_mode: brownfield
+
+# 多仓时启用 (见 prompts/approval/multi-repo-guidance.md)
+# multi_repo:
+#   enabled: true
+#   document_mode: unified   # unified | per_repo — 用户确认后填写
+#   primary_repo: talos      # unified 时必填
+#   repos:
+#     - id: talos
+#       label: 平台
+#       role: platform
+#       change: <change-name>
+#     - id: talos-web
+#       label: 控制台
+#       role: web
+#       change: <web-change-name>
+#   outputs:
+#     unified:
+#       repo: talos
+#       change: <change-name>
+#       path: specflow/changes/<change-name>/approval.md

package/templates/approval-part.md

@@ -0,0 +1,15 @@
+<!--
+  Approval part fragment — NOT a standalone document.
+  Written under specflow/changes/<name>/approval/parts/<part-id>.md
+  Assembled by: specflow approval assemble <change>
+-->
+
+<!-- part-id: <must match filename without .md> -->
+<!-- index-ref: approval/index.yaml parts_order -->
+
+<!-- FORBIDDEN in parts:
+  - Top-level "# 技术方案审批文档"
+  - Foreign chapter headings "## N." not owned by this part
+  - TODO / 待补充 / 此处省略 / 详见 design (without §ref)
+  - Empty or placeholder-only body
+-->