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

package/skills/specflow-approval/SKILL.md

@@ -418,10 +418,71 @@ Each dimension produces a verdict (`READY` | `NEEDS REFINEMENT` | `BLOCKED`) wit
 
 ---
 
-## Stage 12: Generate approval.md
+## Stage 12: Generate approval.md (Index → Map → CLI Reduce)
 
-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`.
+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`
+
+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: meta + fields + success examples + **failure example (G2)** + error table per interface (**含不变**;完整格式,禁止精简)
+- §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 +497,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
@@ -463,7 +524,7 @@ Present a summary to the user (**chat only** — these are not document chapters
 - **AI pre-approval recommendation** (建议批准 / 有条件批准 / 退回 refine / 拒绝) + 理由
 - The path where `approval.md` will be written
 
-Ask explicitly about **optional chapters**:
+Ask explicitly about **optional chapters** (record in `approval/index.yaml` → `optional.s5/s7/s8`):
 
 ```text
 是否将以下章节写入审批文档?
@@ -472,20 +533,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,52 @@
+# 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

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
+-->