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

package/prompts/approval/project-conventions-guidance.md

@@ -0,0 +1,171 @@
+# Approval · Project Conventions Router
+
+> Used by `/specflow:approval` before drafting **§3 架构 / §4.4 数据 / §4.5 接口 / §4.6 前端**
+> (frontend when `uiInScope=yes`).  
+> **目的**:让方案贴合**本仓库**的 skill / rule / 工程约定，而不是只套 SpecFlow 通用 guidance。  
+> **懒加载**:按主题按需 `Read`，禁止一次灌入全部 IDE rules。  
+> **Not** an MCP tool; **禁止** `invoke /xxx skill` —— 一律解析路径后 `Read`。
+
+---
+
+## 0. Priority (冲突时必须遵守)
+
+```text
+① 项目约定 + 现网代码/DDL/OpenAPI   >   ② SpecFlow Guidance Pack   >   ③ LLM 常识
+```
+
+- ① 决定「能不能做、禁令、现网形状」。
+- ② 只补强「怎么写清楚」(如完整 CREATE TABLE、接口失败示例骨架)。
+- ②/③ **不得**覆盖 ①(例:项目约定「本迭代禁止迁移」时,不得按通用 skill 发明 `ALTER`)。
+
+Announce after resolve:
+
+```text
+Project conventions (architecture|api|database|frontend): <paths…> | none
+Conflict policy: project > SpecFlow guidance > LLM
+```
+
+---
+
+## 1. Topics (何时加载)
+
+| 主题 `topic` | 何时 **必须**跑本路由 | 典型要找的内容 |
+|--------------|----------------------|----------------|
+| `architecture` | 起草 **§3** 前 | 分层、模块边界、目录约定、禁止直连 |
+| `database` | 起草 **§4.4** 前(且有持久化) | 迁移工具禁令、命名、字符集、现网表规范 |
+| `api` | 起草 **§4.5** 前(且有对外/跨端接口) | 错误码、鉴权、契约/OpenAPI、通道 |
+| `frontend` | 起草 **§4.6** 前(且 `uiInScope=yes`) | 组件/状态/路由/API client/设计系统/**表单/测试/a11y** 等落地约定;须含 IDE skills/rules 扫描(见 `frontend-guidance.md` §3) |
+
+每个主题 **最多 Read 5 个文件**(配置列出的优先;自动探测时取最相关的前 5 个)。细节 references 仅在入口文件点名时再读(禁止 reference 链式跳转)。
+
+---
+
+## 2. Resolve paths (跨 IDE)
+
+### 2.1 显式配置(最高优先)
+
+读 `specflow/config.yaml` → `conventions.<topic>`(字符串路径数组,相对项目根)。  
+有配置则 **只 Read 这些路径**(仍受「最多 5 个」限制);缺文件 → WARNING。
+
+```yaml
+conventions:
+  architecture:
+    - docs/engineering/architecture.md
+  api:
+    - docs/api/guidelines.md
+  database:
+    - docs/db/conventions.md
+  frontend:
+    - docs/frontend/conventions.md
+```
+
+### 2.2 自动探测(无配置时)
+
+1. 判定 `activeIde`(本会话 IDE):Cursor / Claude / Codex。  
+2. **先**扫 activeIde 候选。  
+3. 若无命中:按 `cursor → claude → agents` 回退扫同主题候选。  
+4. 再扫**仓根中立**路径。  
+5. 仍无 → `none`(允许继续,但总则/架构说明须写「未发现项目级约定」)。
+
+#### 候选路径表
+
+**仓根中立(跨 IDE 推荐真相源)**
+
+| topic | 候选(存在则纳入) |
+|-------|------------------|
+| `architecture` | `docs/engineering/architecture.md`, `.specflow/conventions/architecture.md`, `ARCHITECTURE.md` |
+| `api` | `docs/api/guidelines.md`, `docs/engineering/api.md`, `.specflow/conventions/api.md` |
+| `database` | `docs/db/conventions.md`, `docs/engineering/database.md`, `.specflow/conventions/database.md` |
+| `frontend` | `docs/frontend/conventions.md`, `docs/frontend/patterns.md`, `docs/frontend/testing.md`, `docs/engineering/frontend.md`, `.specflow/conventions/frontend.md`, `agent_docs/tech_stack.md`, `agent_docs/code_patterns.md`, `agent_docs/testing.md` |
+
+**Cursor**
+
+| topic | 候选 |
+|-------|------|
+| 通用 | `.cursor/rules/**/*.mdc` 中文件名/标题含 architecture\|api\|database\|db\|frontend\|backend\|ui\|react\|vue\|component\|tailwind\|a11y\|playwright 的条目(每主题最多 2) |
+| skill | `.cursor/skills/**/SKILL.md` 目录名或 frontmatter `name`/`description` 匹配主题关键词 |
+
+**Claude**
+
+| topic | 候选 |
+|-------|------|
+| 通用 | `CLAUDE.md`, `.claude/CLAUDE.md`(整文件较大时只提取与主题相关章节) |
+| skill | `.claude/skills/**/SKILL.md`(主题关键词匹配) |
+| rules | `.claude/rules/**/*`(若存在;同名过滤) |
+
+**Codex**
+
+| topic | 候选 |
+|-------|------|
+| 通用 | `AGENTS.md`(提取与主题相关段落) |
+| skill | `.agents/skills/**/SKILL.md`(主题关键词匹配) |
+
+关键词提示:
+
+- `architecture|arch|分层|模块`
+- `api|openapi|rpc|接口|错误码`
+- `database|db|sql|迁移|schema`
+- `frontend|ui|react|vue|next|svelte|tailwind|component|控制台|页面|组件|表单|路由|a11y|playwright|vitest|样式|design.?system`
+
+> **前端专题**:`topic=frontend` 时 **必须**按 `frontend-guidance.md` §3 扩扫 IDE skills/rules
+> 与落地文档(状态/表单/测试/a11y 等);不要只命中一个泛化的「frontend」文件名就停。
+
+---
+
+## 3. How to apply (写入方案时)
+
+1. **用可读中文**把约定写进 §2.1 / §3 图要点 / §4.4 / §4.5 / §4.6(禁止代码腔堆砌)。
+2. **硬禁令**原样保留语义(例:「本迭代禁止 goose 迁移」)。  
+3. 与 SpecFlow DB/API 硬门槛同时满足:项目禁令优先;表达骨架用 SpecFlow 规则。  
+4. 在对应章节**标明来源路径**(总则「项目约定」列,或架构图要点首条)。  
+5. 若探测到约定文件但正文未体现关键禁令 → 确认摘要 / §8(若有)记 `WARNING`:  
+   `发现项目约定 <path> 但方案未采纳关键约束`。
+
+---
+
+## 4. Interaction with SpecFlow database guidance
+
+写 §4.4 时顺序固定:
+
+1. 本路由 `topic=database`(项目约定)  
+2. `prompts/approval/database-guidance.md`(SpecFlow pack + dbStack)  
+3. 现网 DDL / 迁移 / 锚点文件(Pass 6)  
+4. 起草:表形状与禁令 ← ①+③;DDL 完整度与类型惯例 ← ②  
+
+§4.4.1 总则必须同时填写:
+
+| 项 | 说明 |
+|----|------|
+| 项目约定 | 实际 Read 到的路径,或 **未发现** |
+| DB 技能 | SpecFlow guidance 路径或 `LLM-fallback` |
+| DDL 来源 | 迁移/基线路径或本迭代新增 |
+
+---
+
+## 4b. Interaction with frontend guidance
+
+写 §4.6 时顺序固定:
+
+1. 本路由 `topic=frontend`(项目约定 docs + IDE skills/rules 关键词匹配)  
+2. **强制**再跑 `prompts/approval/frontend-guidance.md` §3 —— 补扫开发落地维
+   (组件/路由/状态/表单/API client/样式/a11y/测试/lint);与步骤 1 **去重**,合计 ≤5 文件  
+3. 现网路由/布局/API client 锚点(Pass 6)  
+4. 起草:页面/组件边界与禁令 ← ①+②+③;章节骨架与 G5/G6 ← `frontend-guidance` 其余条款  
+
+§4.6.1 总则必须填写:
+
+| 项 | 说明 |
+|----|------|
+| 项目约定 | config + 中立 docs 路径,或 **未发现** |
+| IDE skills/rules | 实际 Read 的 `.cursor/.claude/.agents` skill/rule 路径,或 **未发现** |
+| FE 栈 | 五元组 |
+
+无 UI → 整章省略。发现约定但方案未采纳 → WARNING。
+
+---
+
+## 5. Why this shape
+
+- IDE 目录不同 → 用 **activeIde + 回退 + 中立 docs** 统一发现,不强迫业务仓只选一个 IDE。  
+- 上下文有限 → **按主题懒加载**,最多 3 文件。  
+- 贴合项目 → **优先级写死**,并要求总则可核对来源。

package/skills/GUIDANCE_PACKS.md

@@ -0,0 +1,70 @@
+# Guidance Packs 与项目约定
+
+审批写技术章时的取证优先级：
+
+```text
+① 项目约定 (conventions / IDE rules / docs)  >  ② SpecFlow Guidance Pack  >  ③ LLM
+```
+
+## SpecFlow 两层模型（包内）
+
+| 层 | 包内位置 | 业务仓落地 | IDE 可发现 |
+|----|----------|------------|------------|
+| **Workflow skill** | `skills/specflow-*` + `COMMAND_CATALOG` | `.cursor/skills/specflow-*`（及 claude/agents） | 是 |
+| **Guidance pack** | `skills/<pack>/` + [`guidance-packs.yaml`](guidance-packs.yaml) | `{ide}/specflow/guidance/<pack>/` | **否** |
+
+Workflow 通过路由 `Read` 路径加载 guidance；禁止写成「invoke `/mysql` skill」。
+
+## 项目约定（仓内，懒加载）
+
+| 项 | 说明 |
+|----|------|
+| 路由 | `prompts/approval/project-conventions-guidance.md` |
+| 解析辅助 | `src/core/project-conventions.ts`（config + 仓根中立路径） |
+| 主题 | `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。
+
+```yaml
+# specflow/config.yaml（可选，优先于自动探测）
+conventions:
+  database:
+    - docs/db/conventions.md
+  api:
+    - docs/api/guidelines.md
+  architecture:
+    - docs/engineering/architecture.md
+```
+
+无配置时：仓根中立文件（如 `docs/db/conventions.md`）+ Cursor/Claude/Codex 下 rules/skills（见路由文档，按 activeIde 优先再回退）。
+
+## Guidance Pack 注册表
+
+```yaml
+packs:
+  - id: database
+    source: skills/database
+    installAs: guidance/database
+    consumers: [approval]
+```
+
+## 新增 Guidance Pack
+
+1. 在 `skills/<id>/` 放置 `SKILL.md`（及可选 `references/`）。
+2. 在 `guidance-packs.yaml` 增加一行。
+3. 消费方 prompt 写清：业务仓 `{ide}/specflow/guidance/<id>/` → 包内回退 → fallback。
+
+## 数据库章节取证顺序
+
+1. 项目约定 `topic=database`
+2. SpecFlow `guidance/database/<stack>/`
+3. 现网 DDL / 迁移 / 锚点  
+
+§4.4.1 总则必须填写「项目约定」「DB 技能」「DDL 来源」。
+
+## 当前 packs
+
+| id | consumers | 说明 |
+|----|-----------|------|
+| `database` | approval | 按 `dbStack` 补强 DDL 写法；不得覆盖项目禁令 |

package/skills/database/README.md

@@ -1,15 +1,27 @@
 # SpecFlow 本地数据库技能 (`skills/database/`)
 
-本目录是 **SpecFlow 仓库内长期维护** 的数据库参考技能，供 `/specflow:approval` 生成 §4.4 时按项目栈按需 `Read`。
+本目录是 **Guidance Pack** `database`：SpecFlow 仓库内长期维护的数据库参考知识，供 `/specflow:approval` 生成 §4.4 时按项目栈按需 `Read`。
+
+详见 [`../GUIDANCE_PACKS.md`](../GUIDANCE_PACKS.md) 与 [`../guidance-packs.yaml`](../guidance-packs.yaml)。
 
 ## 硬性约定
 
 | 项 | 约定 |
 |----|------|
-| 运行时依赖 | **无远程仓库依赖**。审批流程只读本目录文件，禁止 `npx skills add`、禁止 clone/fetch 上游 |
-| 维护方式 | 在本仓库直接改 `SKILL.md` / `references/` / `examples/`，随 SpecFlow 发版 |
-| 加载方式 | `prompts/approval/database-guidance.md` 路由：命中栈 → Read 本目录；未命中 → LLM-fallback |
-| IDE 全局技能 | **不**自动安装到用户 `.claude/skills`（避免噪音）；仅 approval 按需读取 |
+| 与项目约定关系 | **项目约定优先**。先跑 `project-conventions-guidance.md`(`topic=database`)，再读本 pack |
+| 运行时依赖 | **无远程仓库依赖**。审批流程只读本地文件 |
+| 加载方式 | `database-guidance.md`：命中栈 → Read 本目录；未命中 → LLM-fallback |
+| init 安装目标 | `{ide}/specflow/guidance/database/` |
+| IDE 全局技能 | **不**安装到 `.cursor/skills` 等发现路径 |
+
+## 路径解析（业务仓 §4.4）
+
+1. 项目约定（`conventions.database` 或 `docs/db/conventions.md` 等）
+2. `.cursor/specflow/guidance/database/<stack>/`（或 `.claude` / `.agents`）
+3. 回退：包内 `skills/database/<stack>/`
+4. 仍缺失：`LLM-fallback` + WARNING
+
+§4.4.1 总则须同时填写「项目约定」「DB 技能」「DDL 来源」。
 
 ## 目录
 
@@ -24,6 +36,13 @@ skills/database/
   README.md        # 本文件
 ```
 
+业务仓 init 后对应：
+
+```text
+.cursor/specflow/guidance/database/mysql/SKILL.md
+…
+```
+
 ## 历史种子（非依赖）
 
 初版内容种子自 [full-stack-skills/database-skills](https://github.com/full-stack-skills/database-skills)（Apache-2.0）。  

package/skills/guidance-packs.yaml

@@ -0,0 +1,10 @@
+# Guidance packs: private knowledge installed under {ide}/specflow/guidance/
+# NOT copied into IDE skills discovery paths (.cursor/skills, .claude/skills, .agents/skills).
+# See skills/GUIDANCE_PACKS.md
+
+packs:
+  - id: database
+    source: skills/database
+    installAs: guidance/database
+    consumers:
+      - approval

package/skills/specflow-approval/SKILL.md

@@ -80,13 +80,71 @@ change names, file paths, commands, and code in their original form.
    - `Cargo.toml` → Rust
    - `tsconfig.json` → TypeScript (refines Node detection)
    - If none match, set `techStack: unknown`
-5. **Detect database stack** (for §4.4 guidance). Follow
+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.
-6. Read `specflow/specs/` baseline if it exists (for Pass 7 baseline cross-check).
+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>)."
 
-Announce: "Generating technical approval document for change `<name>` (phase=refined, language=<lang>, techStack=<stack>, dbStack=<db>)."
+---
+
+## 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.
 
 ---
 
@@ -95,33 +153,30 @@ Announce: "Generating technical approval document for change `<name>` (phase=ref
 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` — DB skill router for **local** packs under
-   `skills/database/` (in-repo maintenance; **no remote skill dependency**). **Not an MCP
-   tool**: on `dbStack` hit, `Read` matched `SKILL.md` + focused references; on `none`,
-   LLM-only §4.4.
-
-`generate.md` + `database-guidance.md` together specify:
-
-- The 7-dimension closed-loop verification (Passes 1–7, each with AI self-prompt, verdict rules, evidence format)
-- The design quality assessment (over-engineering signals + extensibility signals)
-- The architecture design (Mermaid diagrams + **图要点说明** + core-component table)
-- The detailed design generation (设计要点一览 + Happy Path 完整时序 + 业务场景时序与说明 +
-  data ER/DDL + interfaces inventory/fields/examples/errors + logic/config/compat)
-- The test strategy (layered test matrix mapped to §5 acceptance criteria)
-- The deployment/release/rollback plan
-- The implementability assessment (7 dimensions with verdict rules)
-- The approval document structure and generation rules
-- Protocol-marker preservation and language policy enforcement
-- §1 绪论与边界 (proposal + optional explore + AI; absorbs What/Impact; **no 变更摘要 chapter**;
-  pain-point diagram, User Journey, Non-Goals with reasons)
-- Document order: §1 绪论 → §2 评估 → §3 架构 → §4 详细设计 → **§5 验收标准** → §6 测试 → …
-- **Quality Gates G1–G4** + **Style & Tone** (hard rules in generate.md Part E)
-- **DB guidance router** (`database-guidance.md` + local `skills/database/`): match project
-  stack → Read in-repo skill; no hit → LLM fallback; **never** fetch remote skills / MCP wrap
-- Anchor-file extraction and code-reading rules (depth: anchor file only, no recursion)
-
-You MUST read `generate.md` before performing any analysis or writing `approval.md`. Do not
-invent the assessment dimensions or document structure — they are defined in that prompt.
+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`.
 
 ---
 
@@ -178,9 +233,10 @@ After all 7 Passes:
 - `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**, use the **single compact table** only (see generate.md
-Part E §8): no per-Pass long sections, no duplicate summary table. Expand evidence only
-for ⚠️/❌ rows (max 2–3 bullets).
+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.
 
 ---
 
@@ -224,9 +280,11 @@ Scan `design.md` for the 5 extensibility signals:
 
 ## Stage 6: Architecture Design
 
-Produce the **architecture design** section (approval.md **§3** 架构整体设计) defined in
-`generate.md` Part E. This answers "what modules make up the system, how they depend on
-and interact with each other, and what each module's responsibility and boundary is."
+**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**
@@ -275,20 +333,30 @@ Produce the **detailed design** section (approval.md **§4** 方案详细设计)
 
 **Selective** categories; uninvolved ones get explicit「不涉及 X」markers.
 
-Order and hard requirements (from `generate.md` §4.1–4.8):
+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 drafting §4.4: follow `database-guidance.md`. If `dbStack` hit,
-   `Read` `skills/database/<stack>/SKILL.md` (+ DDL/index/JSON refs as needed).
-   If `none`, LLM-only with SpecFlow §4.4 hard bar (ER + full CREATE TABLE + field tables…).
-   **Outline**: only `4.4.1–4.4.4` + `##### table`; DDL/字段说明/JSON = `**bold**`, not headings.
-5. **接口设计** — inventory + fields + examples + errors…
-   **Outline**: only `4.5.1–4.5.3` + `##### In`; 请求体字段/示例/错误 = `**bold**`, not headings.
-6. **核心算法 / 配置 / 兼容性** — as applicable.
+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: `project-conventions-guidance.md` `topic=api`.
+   Then inventory + fields + examples + errors…
+   **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 澄清: <元素>]`.
@@ -297,24 +365,34 @@ Present the detailed design to the user as part of the confirmation summary.
 
 ---
 
-## Stage 8: Acceptance Criteria (after design)
+## Stage 8: Acceptance Criteria (optional)
+
+**Ask the user** whether to include **§5 验收标准** in `approval.md`.
 
-Produce **§5 验收标准** only **after** §3 architecture and §4 detailed design are drafted
-in the document order. Exhaustive Requirement + Scenario list with 3-level testability.
-Do not place acceptance before the design chapters.
+- 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 the **test strategy** section (approval.md **§6** 测试策略). Every §5 acceptance
-criterion maps to ≥1 test layer with tools and verifiable goals.
+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
+## Stage 10: Deployment & Release (optional)
 
-Produce the **deployment / release / rollback** section (approval.md **§7**).
+**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.
 
 ---
 
@@ -345,52 +423,69 @@ Each dimension produces a verdict (`READY` | `NEEDS REFINEMENT` | `BLOCKED`) wit
 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`.
 
-Document chapter order (hard):
+Document chapter order (hard for included chapters):
 
-1. §1 绪论与边界 (proposal + optional explore + AI; includes What/Impact; **no 变更摘要**)
-2. §2 技术方案评估
-3. §3 架构整体设计 (图 + **图要点说明** + 组件)
-4. §4 方案详细设计 (设计要点 + Happy Path + 业务场景说明 + 数据/接口…)
-5. §5 验收标准 (**after** design)
-6. §6 测试策略 → §7 部署 → §8 闭环 → §9 可实施性 → §10 审批
+1. §1 绪论与边界
+2. §2 技术方案评估 — **可读中文**写现状与约束(禁止代码腔堆砌)
+3. §3 架构整体设计
+4. §4 方案详细设计
+5. §5 验收标准 — **仅用户确认要时**
+6. §6 测试策略
+7. §7 部署 — **仅用户确认要时**
+8. §8 闭环表 — **仅用户确认要时**(分析仍必做)
+9. §9 可实施性评估
+10. §10 审批 — **仅人工签字栏**(无 AI 预审小节)
 
 Key rules:
 
-- §1 truthful: pains from proposal/design/confirmed explore; User Journey → §5; Non-Goals with reasons; What/Impact in §1.2.
-- Decision Review includes every `design.md` decision.
-- §5 Acceptance exhaustive with 3-level testability; placed after §3/§4.
-- §3 every architecture diagram has「设计说明 / 图要点」; component table with「不做什么」.
-- §4 has 设计要点一览, complete Happy Path sequence + notes, each business scenario with 设计要点; DB/API hard bars (§4.4/§4.5); outline hygiene (no heading for 请求体字段/DDL/字段说明 — bold labels only).
-- **Quality Gates G1–G4**: >5-line prose flow → Mermaid; interfaces need failure examples; JSON/new-column need存量填充策略; rollback data compatibility explicit.
-- **Style & Tone**: plain language; gloss obscure abbreviations on first use; ban「尽量/大概/一般情况下」; use「必须/禁止/采用 XX 方案」.
-- **§8 闭环**: one compact table only; PASS one line; ⚠️/❌ ≤3 bullets; no per-Pass essays.
-- Test Strategy maps every §5 criterion to ≥1 layer.
-- Deployment selective; Code Grounding cites real files; sign-off blank; never recommend approve if any verdict is `FAIL`.
+- §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:
+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 / 拒绝)
+- **AI pre-approval recommendation** (建议批准 / 有条件批准 / 退回 refine / 拒绝) + 理由
 - The path where `approval.md` will be written
 
-Ask explicitly:
+Ask explicitly about **optional chapters**:
+
+```text
+是否将以下章节写入审批文档?
+- §5 验收标准: 要 / 不要
+- §7 部署/发布/回滚: 要 / 不要
+- §8 闭环性检查表: 要 / 不要
+```
+
+Then ask:
 
 > "确认生成审批文档并写入 `specflow/changes/<name>/approval.md`?"
 
-Do NOT write the file until the user 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 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.
 
 On confirmation:
 
-1. Write `approval.md` to the change directory.
-2. Do NOT change `phase` — it remains `refined`.
-3. Report the file path and next-step suggestions.
+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.
 
 ---