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

package/skills/specflow-approval/SKILL.md

@@ -1,778 +0,0 @@
----
-name: specflow-approval
-description: "Post-refine technical approval document -- AI closed-loop check + code/baseline grounding + over-design guard + implementability assessment"
----
-
-# SpecFlow: Approval
-
-> **HARD GATE**: phase must be `refined`. Run `/specflow:refine` first if not.
-> **HARD GATE**: User must confirm before `approval.md` is written to the change directory.
-> Approval does NOT advance phase — it produces an optional review artifact for human sign-off.
-
-## Purpose
-
-Approval is the **post-refine, pre-apply technical review pass**: it reads the four
-refined artifacts (`proposal.md`, delta `specs/`, `design.md`, `tasks.md`), **grounds them
-against existing project code and spec baseline**, and produces a single `approval.md`
-technical-approval document for human sign-off.
-
-It is **optional**. Skip it when you want to go straight from refine to apply. Use it when
-the change is significant enough to warrant formal technical review before implementation
-begins — architecture decisions, cross-team impact, regulatory exposure, or any change where
-"should we even build this, this way?" deserves a documented answer.
-
-Unlike `/specflow:review` (which reviews code after implementation) and `/specflow:verify`
-(which validates implementation against specs), approval reviews the **plan** before any
-code is written. It fills the gap between refine convergence and apply execution.
-
-Approval does five things a deterministic CLI cannot:
-
-1. **Integrates** the four artifacts into a single narrative with cross-references.
-2. **Checks closed-loop coherence** across requirements ↔ design ↔ specs ↔ tasks using
-   semantic reasoning (fuzzy wording detection, coverage gaps, traceability).
-3. **Grounds the plan against reality** — reads existing project code (anchor files) and
-   the main spec baseline to verify the plan can actually land on this codebase.
-4. **Guards design quality** — detects over-engineering (YAGNI violations) while confirming
-   reasonable extensibility is preserved.
-5. **Assesses implementability** — can an engineer execute this plan without getting stuck?
-
-## Invocation
-
-```text
-/specflow:approval <change-name>
-```
-
-Cursor: `specflow:approval <change-name>`;Codex: `$specflow-approval <change-name>`.
-
-## Prerequisites
-
-- An active change exists with `.specflow.yaml` and `phase: refined`.
-  - If phase is not `refined`, REFUSE to proceed and suggest: "This change is in phase
-    `<phase>`. Run `/specflow:refine` first to complete deep review before generating an
-    approval document."
-- All four refined artifacts exist in `specflow/changes/<name>/`:
-  - `proposal.md`
-  - `specs/**/*.md` (at least one delta spec)
-  - `design.md`
-  - `tasks.md`
-- `specflow` CLI is available on PATH (for `specflow validate` and optional status lookup).
-- Optional: `explore.md` with `Status: confirmed` (enriches the approval's "why" section).
-
-## Artifact Language Setup
-
-Read `.claude/specflow/prompts/shared/artifact-language.md` and resolve the active planning
-root's `specflow/config.yaml` before generating `approval.md`. Apply the policy to all
-human-readable narrative content (summaries, assessments, evidence). Preserve protocol
-markers (`### Requirement:`, `#### Scenario:`, `- **WHEN**`, `- **THEN**`), capability IDs,
-change names, file paths, commands, and code in their original form.
-
----
-
-## Stage 1: Pre-flight Validation
-
-1. Read `.specflow.yaml` and confirm `phase: refined`. If not, refuse and suggest `/specflow:refine`.
-2. Confirm all four artifacts exist. If any is missing, stop and tell the user which are missing.
-3. Read `specflow/config.yaml` and resolve `artifacts.language` (default `en`).
-4. Detect project tech stack signals at the project root only (do not recurse):
-   - `package.json` → Node/TS/JS ecosystem
-   - `go.mod` → Go
-   - `pyproject.toml` / `requirements.txt` → Python
-   - `Cargo.toml` → Rust
-   - `tsconfig.json` → TypeScript (refines Node detection)
-   - If none match, set `techStack: unknown`
-5. Set `projectMode`:
-   - `greenfield` — no meaningful application source yet (no `src/`/`app/`/`internal/`/`lib/`
-     with real code, or only empty scaffold); Pass 6 will be SKIPPED greenfield
-   - `brownfield` — existing product code to ground against
-6. **Detect database stack** (for §4.4 guidance). Follow
-   `prompts/approval/database-guidance.md` §1 — set
-   `dbStack: mysql|postgresql|oracle|redis|elasticsearch|none`. Prefer OLTP
-   (`mysql`/`postgresql`/`oracle`) over cache/search when multiple match.
-7. **Scan four artifacts for tech selection coverage** (proposal / design / tasks / specs):
-   look for explicit choices on: 前端、后端、数据库与缓存、基础设施(含 CI/部署/云)。
-   Set `stackCoverage: complete | partial | missing`.
-8. **Detect `uiInScope`** (follow `prompts/approval/frontend-guidance.md` §1):
-   UI/控制台/页面/组件 signals → `uiInScope=yes|no`. When yes, check FE 五元组 coverage
-   (Framework / Styling / State / UI kit / FE testing); incomplete counts as
-   `stackCoverage=partial` for 前端.
-9. Read `specflow/specs/` baseline if it exists (for Pass 7 baseline cross-check).
-
-Announce: "Generating technical approval document for change `<name>` (phase=refined,
-language=<lang>, projectMode=<greenfield|brownfield>, techStack=<stack>, dbStack=<db>,
-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) 一份合订视图 (bundle) — 各仓 per_repo 真源 + CLI bundle 只读合订 (**推荐**)
-B) 多份分仓 (per_repo) — 每仓各自 approval.md（默认 Map 模式）
-C) 一份 LLM 合订 (legacy unified) — 仅当用户明确要求且无 bundle；不推荐
-```
-
-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
-[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)
-```
-
-**`--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).
-
-### 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.
-
----
-
-## Gate: Tech Stack Intake (0→1 / 四件套缺选型)
-
-**Trigger** (any):
-
-- `projectMode = greenfield`, **or**
-- `stackCoverage = missing | partial` for dimensions this change needs
-  (e.g. UI change needs 前端; persistence needs 数据库与缓存; ship needs 基础设施)
-
-**Do NOT** invent a full stack. **STOP and ask the user** in chat (structured), then wait:
-
-```text
-本变更需要补全技术选型（四件套未写清 / 0→1 绿场）。请确认或补充下列方向
-（可写「本变更不涉及」跳过某一维）:
-
-1. 前端：Framework / Styling / State / UI kit / FE testing（五元组；或不涉及前端）
-2. 后端：语言/框架、API 风格(HTTP/gRPC/…)、进程模型
-3. 数据库与缓存：主存(MySQL/PG/…)、缓存(Redis/…)、搜索(若有)
-4. 基础设施：运行环境(K8s/VM/Serverless)、CI/CD、对象存储/消息队列(若有)
-5. 其它约束：公司强制栈、禁止项、必须复用的现网组件
-
-若本变更含 UI 且前端仍不清，追问（可合并一次问完）:
-- 关键页面/路由清单（或「沿用现网，本迭代只改某页」）
-- 验证命令（dev / test / e2e / browser）
-- （可选）若用 v0/Lovable 等 AI builder：导出与本地可构建计划
-
-回复示例：
-前端 Next.js+TS / Tailwind / Zustand / shadcn / Vitest+Playwright；
-后端 Go+Gin；DB MySQL 8 + Redis；基础设施 K8s + GitHub Actions；
-禁止自建消息队列，复用公司 Kafka。
-```
-
-After the user answers:
-
-1. Record answers for §2.2 技术选型 + fold into §2.4 决策评审表 (new D-rows).
-2. Suggest (do not force) updating `design.md` via `/specflow:refine` later; approval may
-   proceed with chat-confirmed stack for this `approval.md` only.
-3. Re-run dbStack detection if the user named a DB; re-check FE 五元组 if UI in scope.
-4. Continue subsequent stages.
-
-If the user refuses to choose and the change clearly needs a stack → mark
-`[待 refine 澄清: 技术选型]` and **do not** fabricate architecture/DDL/页面树 around a
-guessed stack.
-
----
-
-## Stage 2: Load Execution Instructions
-
-Read these files and follow them:
-
-1. `.claude/specflow/prompts/approval/generate.md` (or repo `prompts/approval/generate.md`)
-2. `prompts/approval/database-guidance.md` — SpecFlow DB **guidance pack** router
-3. `prompts/approval/frontend-guidance.md` — UI scope + FE 五元组 + §4.6 contract
-4. `prompts/approval/project-conventions-guidance.md` — **project** skill/rule/docs
-   lazy-load (architecture / api / database / frontend); cross-IDE path resolve;
-   priority **project > SpecFlow guidance > LLM**
-
-`generate.md` + convention/DB/FE routers together specify:
-
-- The 7-dimension closed-loop verification (Passes 1–7)
-- Design quality, architecture, detailed design, test/deploy (optional chapters), implementability
-- Document order: §1 → §2 → §3 → §4 → **(optional §5)** → §6 → **(optional §7/§8)** → §9 → §10(签字栏 only)
-- **Quality Gates G1–G6** + **Style & Tone**(含禁止正文代码腔)
-- **Optional chapters** §5 / §7 / §8 — ask before write; **AI 预审** chat-only
-- **Project conventions** lazy-load before §3/§4.4/§4.5/§4.6; **project > SpecFlow guidance > LLM**
-- **DB guidance** after project DB conventions; resolve
-  `{ide}/specflow/guidance/database/<stack>/` (or package `skills/database/`); record
-  项目约定 + DB 技能 + `dbStack` in §4.4.1; never fetch remote / MCP
-- **FE guidance** when `uiInScope=yes`: `frontend-guidance.md` §3 **must** scan
-  IDE skills/rules + 落地文档(组件/路由/状态/表单/样式/a11y/测试) + `topic=frontend`;
-  §4.6 cites 项目约定 + IDE skills/rules; G5/G6; Visual Loop; never invent page trees
-- **Tech stack intake**: greenfield or four-artifacts missing 前端/后端/数据库与缓存/基础设施
-  → ask user before inventing stacks; FE needs 五元组; record in §2.2; never fabricate
-
-You MUST read `generate.md` before any analysis or writing `approval.md`.
-
----
-
-## Stage 3: Extract Anchor Files
-
-Before running the closed-loop passes, extract the set of **anchor files** that the plan
-references. These are the files Pass 6 (Code Grounding) will read.
-
-**Extraction rules** (defined in detail in `generate.md` Part A → Pass 6):
-
-1. Scan `design.md` and `tasks.md` for file path references (backtick-quoted paths, code
-   blocks, or inline paths like `src/core/...`).
-2. Collect only paths under the project root that look like source files (`.ts`, `.js`,
-   `.py`, `.go`, `.rs`, `.kt`, `.java`, etc.) or config files (`package.json`, `tsconfig.json`,
-   etc.).
-3. Deduplicate. Do NOT read directories, only files.
-4. **Depth limit: read the anchor file itself only.** Do not follow imports, do not recurse.
-5. If no anchor files are found and the project has no source code (greenfield), Pass 6
-   will emit `skipped (greenfield — no existing code)`. If the project HAS source code but
-   the plan references no existing files, that is a `FAIL` (plan is ungrounded).
-
-Announce the extracted anchor file list to the user before Pass 1 begins.
-
----
-
-## Stage 4: AI Closed-Loop Verification
-
-Perform the 7 closed-loop passes defined in `generate.md`, in order:
-
-### Internal coherence (Passes 1–5)
-
-1. **Pass 1 — Requirement Closure**: proposal ↔ specs coverage
-2. **Pass 2 — Design Closure**: design decisions ↔ spec requirements
-3. **Pass 3 — Spec Closure**: scenario completeness + testability (3-level grading) + delta integrity
-4. **Pass 4 — Implementation Closure**: tasks ↔ spec requirements coverage + granularity
-5. **Pass 5 — Risk Closure**: risks ↔ mitigations + BREAKING migration + unidentified risks
-
-### External grounding (Passes 6–7)
-
-6. **Pass 6 — Code Grounding**: design/tasks anchor files exist in the project + structure
-   compatibility + tech-stack consistency. Reads actual project code (anchor files only).
-7. **Pass 7 — Baseline Cross-Check**: delta specs vs `specflow/specs/` main baseline —
-   conflict detection, duplicate-definition detection, MODIFIED name matching.
-
-Each Pass must produce a brief result for the conversation (verdict + one-line evidence).
-Do **not** dump full coverage matrices into chat unless the user asks or a Pass is
-`WARNING`/`FAIL`.
-
-### Closed-Loop Overall Verdict
-
-After all 7 Passes:
-
-- `FAIL` if any Pass is `FAIL`
-- `PASS WITH WARNINGS` if no `FAIL` but at least one `WARNING`
-- `PASS` if all Passes are `PASS` (a `SKIPPED` Pass does not affect the verdict)
-
-When writing `approval.md` **§8** (only if the user opted in), use the **single compact
-table** only (see generate.md Part E §8). Always run Passes 1–7 for the **chat** summary
-even when §8 is omitted from the document. Expand evidence only for ⚠️/❌ rows
-(max 2–3 bullets); PASS/SKIPPED stay one line.
-
----
-
-## Stage 5: Design Quality Assessment
-
-Perform the two design-quality checks defined in `generate.md` Part B:
-
-### Over-Engineering Check
-
-Scan `design.md` and `tasks.md` for the 5 over-engineering signals:
-
-1. Interface for unrequested requirements
-2. Unnecessary abstraction layers
-3. Pre-built unused infrastructure
-4. Config fields beyond current needs
-5. Complexity exceeding problem scale
-
-**Verdict rule**: 1 signal → `WARNING`; 3+ signals → `FAIL`; 0 signals → `PASS`.
-
-### Extensibility Assessment
-
-Scan `design.md` for the 5 extensibility signals:
-
-1. Namespace reservation
-2. Stable interface, replaceable implementation
-3. Explicit Non-Goals
-4. Backward-compatibility path
-5. Decision rationale mentions extensibility trade-off
-
-**Verdict rule**: 4-5 signals present → `PASS`; 2-3 → `WARNING`; 0-1 → `WARNING`.
-
-### Combined Design Quality Verdict
-
-- `FAIL` if over-engineering is `FAIL`
-- `WARNING` if either check is `WARNING`
-- `PASS` if both are `PASS`
-- **Special**: if over-engineering = `WARNING`/`FAIL` AND extensibility = `WARNING` →
-  escalate to `FAIL` (the plan is both bloated AND not extensible)
-
----
-
-## Stage 6: Architecture Design
-
-**Before drafting §3**: follow `project-conventions-guidance.md` with `topic=architecture`
-(lazy-load ≤3 project convention files). Apply project bans to 图要点; cite path or「未发现」.
-
-Produce the **architecture design** section (approval.md **§3**) defined in
-`generate.md` Part E.
-
-It is complementary to Detailed Design: architecture is about **module-to-module
-relationships** (macro), detailed design is about **module-internal implementation**
-(micro). Architecture is placed **before** acceptance criteria so implementers read
-structure first.
-
-### 3.1 Overall Architecture
-
-Draw Mermaid diagram(s) — module dependency / layered and optionally system interaction:
-
-Requirements:
-
-1. **Mark changed modules** (`[新增]` / `[修改]`) so the change surface is visible.
-2. Label edges with dependency direction or interaction messages.
-3. Project-type mapping: CLI/library → `src/core/*`, `src/cli/*`; Web → services/components;
-   multi-repo → repositories/services.
-4. Consistent with **§2** decisions.
-5. **Hard rule — 图要点说明**: every architecture diagram MUST be followed by a numbered
-   「设计说明 / 图要点」list (boundaries, invariants, reuse vs new) — not a restatement of
-   node names. Align with scenario-job-compile §3 style.
-
-### 3.2 Core Components
-
-| Component | Responsibility | Boundary (does / does NOT) | Depends on | Change type |
-|-----------|---------------|----------------------------|-----------|-------------|
-
-Requirements: list added+modified components;「不做什么」boundaries; 1:1 with diagram;
-trace to §2 decisions. Optional short「组件边界总原则」list.
-
-**If no architecture change**: write explicit `不涉及架构变更(...)` marker.
-
-### 3.3 Architecture Consistency Self-check
-
-- Diagrams mark added/modified modules; each has 图要点说明.
-- Each component has a "does NOT do" boundary; diagram ↔ table 1:1.
-- Boundaries trace to §2 decisions.
-
-Present the architecture design to the user as part of the confirmation summary.
-
----
-
-## Stage 7: Detailed Design
-
-Produce the **detailed design** section (approval.md **§4** 方案详细设计) defined in
-`generate.md` Part E.
-
-**Selective** categories; uninvolved ones get explicit「不涉及 X」markers.
-
-Order and hard requirements (from `generate.md` §4.1–4.9):
-
-1. **设计要点一览** — P1…Pn invariants from design decisions (required).
-2. **核心业务时序 · Happy Path** — complete Mermaid `sequenceDiagram` for the main success
-   path + post-diagram「设计要点」(required).
-3. **业务场景时序** — each scenario: purpose + diagram + **设计要点说明** (required notes;
-   bare diagrams fail quality).
-4. **数据结构** — Before §4.4: (1) `project-conventions-guidance.md` `topic=database`;
-   (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: (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`;
-   (2) **`frontend-guidance.md` §3** — 强制扫描 IDE skills/rules(`.cursor`/`.claude`/`.agents`)
-       与落地文档(组件命名、路由、状态、表单、API client、样式/token、a11y、测试命令、lint 禁令);
-       合计 ≤5 文件,禁止 `invoke` skill;
-   (3) live UI anchors from design/tasks.
-   Then write 五元组 + 页面/路由 + Page 详设(空/加载/错态) + 状态 + Visual Loop.
-   §4.6.1 must list **项目约定** + **IDE skills/rules**.
-   **Outline**: only `4.6.1–4.6.5` + `##### Page · …`. **G5/G6**. Omit chapter if no UI.
-7. **核心算法 / 配置 / 兼容性** — §4.7–4.9 as applicable.
-
-**Traceability**: every element → **§5** Requirement/Scenario and **§2** decision.
-If not implementer-ready, mark `[待 refine 澄清: <元素>]`.
-
-Present the detailed design to the user as part of the confirmation summary.
-
----
-
-## Stage 8: Acceptance Criteria (optional)
-
-**Ask the user** whether to include **§5 验收标准** in `approval.md`.
-
-- If **yes**: produce §5 only **after** §3/§4 are drafted; exhaustive Requirement +
-  Scenario list with 3-level testability.
-- If **no**: omit the entire chapter (no placeholder).
-
----
-
-## Stage 9: Test Strategy
-
-Produce **§6 测试策略**. If §5 is included, every criterion maps to ≥1 test layer.
-If §5 was omitted, map layers to named Requirement/Scenario from delta specs.
-
----
-
-## Stage 10: Deployment & Release (optional)
-
-**Ask the user** whether to include **§7 部署/发布/回滚**. If yes, produce the section;
-if no, omit entirely.
-
----
-
-## Stage 10b: Closed-Loop table (optional)
-
-Closed-loop **analysis** (Passes 1–7) always runs. **Ask the user** whether to include
-**§8 闭环性检查表** in the document. If no, omit §8; still report overall verdict in chat.
-
----
-
-## Stage 11: Implementability Assessment
-
-Perform the 7 implementability dimensions defined in `generate.md` Part C.
-
-1. **Completeness** — no TODOs, placeholders, vague tasks
-2. **Spec Alignment** — tasks cover all spec requirements, no scope creep
-3. **Task Actionability** — can an engineer execute each task without ambiguity
-4. **Technical Feasibility** — design decisions are achievable in the detected tech stack
-5. **Dependency Clarity** — task dependencies and external dependencies are explicit
-6. **Architecture Consistency** — design choices match project's existing tech stack, directory structure, error-handling patterns, and test framework (grounded in code reading from Pass 6)
-7. **Implementation Risk** — high-risk module changes, data migration, concurrency, external API breaks, team tech-stack unfamiliarity
-
-Each dimension produces a verdict (`READY` | `NEEDS REFINEMENT` | `BLOCKED`) with evidence.
-
-### Implementability Overall Verdict
-
-- `BLOCKED` if any dimension is `BLOCKED`
-- `NEEDS REFINEMENT` if no `BLOCKED` but any dimension is `NEEDS REFINEMENT`
-- `READY` if all 7 are `READY`
-
----
-
-## 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/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`
-
-### 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 `specflow approval finalize` (Stage 12f).
-
-### 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: **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)
-
-### 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 finalize <change> [--bundle] [--workspace-root <workset-root>]
-```
-
-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
-
-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):
-
-1. §1 绪论与边界
-2. §2 技术方案评估 — **可读中文**写现状与约束(禁止代码腔堆砌)
-3. §3 架构整体设计
-4. §4 方案详细设计
-5. §5 验收标准 — **仅用户确认要时**
-6. §6 测试策略
-7. §7 部署 — **仅用户确认要时**
-8. §8 闭环表 — **仅用户确认要时**(分析仍必做)
-9. §9 可实施性评估
-10. §10 审批 — **仅人工签字栏**(无 AI 预审小节)
-
-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
-  dimensions; only after Tech Stack Intake (user confirm); never invent full stack.
-  Frontend (when UI) needs 五元组, not「React」alone.
-- Decision Review includes every `design.md` decision (plus D-FE/D-BE/D-DB/D-Infra when intake ran).
-- §5 when included: exhaustive + after §3/§4.
-- §3/§4 hard bars + outline hygiene; **G1–G6**; Style & Tone including **no code-dump prose**.
-- §4.6 when `uiInScope`: pages/routes + G5/G6 + Visual Loop; **must Read** IDE
-  skills/rules/落地规约 before draft; cite paths in §4.6.1; omit if no UI.
-- §8 when included: one compact table; always report closed-loop verdict in chat.
-- Test Strategy maps to §5 or specs names; Deployment only if opted in.
-- Sign-off blank; **never** write AI pre-approval into the file; never recommend approve if any verdict is `FAIL`.
-
----
-
-## Gate: User Confirmation
-
-Present a summary to the user (**chat only** — these are not document chapters):
-
-- Closed-loop overall verdict (PASS / PASS WITH WARNINGS / FAIL)
-- 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 (**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** (record in `approval/index.yaml` → `optional.s5/s7/s8`):
-
-```text
-是否将以下章节写入审批文档?
-- §5 验收标准: 要 / 不要
-- §7 部署/发布/回滚: 要 / 不要
-- §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 **Stage 12e AI Review** (fix parts, write `review-result.json` with `part_hashes`).
-
-Then ask:
-
-> "确认 finalize 并写入各仓 `approval.md`?（多仓时将并行子仓 approval，完成后主仓合订 bundle）"
-
-Do NOT finalize until the user confirms (unless they already confirmed end-to-end generation).
-
-On confirmation:
-
-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 bundle path if multi-repo) and next-step suggestions.
-
----
-
-## Stage 13: Next-Step Suggestions
-
-Based on the assessment results:
-
-- **If closed-loop = PASS, design quality = PASS, and implementability = READY**:
-  Suggest `/specflow:apply` to begin implementation.
-
-- **If any verdict is WARNING**:
-  Suggest the user either (a) proceed to `/specflow:apply` after acknowledging the warnings
-  in the approval document, or (b) return to `/specflow:refine` to close the gaps first.
-
-- **If any verdict is FAIL or implementability = BLOCKED**:
-  Strongly recommend `/specflow:refine` to resolve the failures before implementation.
-  Do NOT suggest `/specflow:apply` — the plan is not ready.
-
-In all cases, remind the user that `approval.md` is an optional artifact: it does not block
-`/specflow:apply` (which only requires `phase=refined`), and it does not affect
-`/specflow:archive` (which scans `specs/`, not `approval.md`).
-
----
-
-## Not Covered by Approval
-
-- No code implementation — `/specflow:apply` owns that.
-- No phase transition — phase stays `refined` until `/specflow:apply` advances it.
-- No spec validation — `/specflow:verify` owns delta + main spec regression checks.
-- No code review — `/specflow:review` owns post-implementation code quality checks.
-- No artifact modification — approval reads the four artifacts (and project code, read-only)
-  but never modifies them. If a Pass reveals a gap, the user returns to `/specflow:refine`
-  to fix it; approval only documents the finding.
-- No full codebase scan — approval reads only the anchor files extracted in Stage 3. Full
-  codebase investigation is `/specflow:explore`'s job.
-- Approval is **not** a gate for apply. It is a decision-support artifact for human review.