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

package/prompts/approval/generate.md

@@ -16,6 +16,10 @@ Before running this flow, the SKILL.md has confirmed:
 - All four artifacts exist: `proposal.md`, `specs/**/*.md`, `design.md`, `tasks.md`
 - `artifacts.language` resolved (default `en`)
 - Tech stack detected (Node/Go/Python/Rust/unknown)
+- `projectMode` (`greenfield` | `brownfield`) and `stackCoverage` (`complete` | `partial` | `missing`)
+- Tech Stack Intake gate completed when greenfield or stack dimensions are missing
+  (user confirmed 前端 / 后端 / 数据库与缓存 / 基础设施, or marked「不涉及」)
+- `uiInScope` resolved; when yes, FE 五元组 confirmed (or marked pending refine)
 - Anchor files extracted from `design.md` + `tasks.md`
 - Optional: `specflow/specs/` baseline exists (for Pass 7)
 
@@ -338,32 +342,57 @@ Generate `approval.md` following this exact structure. Adapt narrative language
 
 1. 绪论与边界 — proposal + optional explore + AI; absorbs What/Impact; **no 变更摘要 chapter**
 2. 技术方案评估 — decisions / risks / design quality
-3. 架构整体设计 — diagrams + **图要点说明** + components (before acceptance)
-4. 方案详细设计 — 设计要点 + Happy Path + 业务场景(+说明) + data/API/…
-5. 验收标准 — **after** architecture & detailed design
-6. 测试策略 → 7. 部署 → 8. 闭环 → 9. 可实施性 → 10. 审批
+3. 架构整体设计 — 架构图 + **图要点说明** + 组件(置于验收之前)
+4. 方案详细设计 — 设计要点 + Happy Path + 业务场景(+说明) + 数据/接口/**前端(若有 UI)**…
+5. 验收标准 — **可选**(须先询问用户;选「要」则放在设计之后;选「不要」则整章省略)
+6. 测试策略 — 默认输出(若无 §5,矩阵改为映射 delta specs 的 Requirement/Scenario)
+7. 部署/发布/回滚 — **可选**(须先询问用户)
+8. 闭环性检查 — **可选**(须先询问用户;内部仍跑 Pass 1–7,仅「要」时写入正文表)
+9. 可实施性评估 → 10. 审批意见(**仅人工签字栏**;AI 预审只在对话中反馈,不写入文档)
 
-### ⚠️ 质量红线 (Quality Gates) — 必须严格执行
+### 可选章节门禁(写入前必须询问)
 
-生成 `approval.md` 全文时下列红线**缺一不可**;违反则详细设计/接口/数据章节视为不合格,确认前必须补全。
+在写入 `approval.md` 之前,向用户明确询问(可合并进确认摘要):
 
-| # | 红线 | 要求 |
-|---|------|------|
-| G1 | 一图胜千言 | 任何超过 **5 行**的文字流程描述,**必须**改为 Mermaid 代码块(`sequenceDiagram` / `flowchart` / `stateDiagram-v2`),禁止长段落散文流程 |
-| G2 | 必须有「失败」示例 | §4.5 每个「新增/修改/行为扩展」接口:除成功请求/响应示例外,**必须**另附 ≥1 组**报错**请求或响应示例(如参数校验失败、租约过期、未认证);仅有错误码表、无 HTTP/正文示例 → 不合格 |
-| G3 | 必须有「数据迁移方案」 | 凡涉及 **JSON 字段形状变更**或**新增列**:必须写明**存量数据的默认值填充策略**(回填脚本 / 读时默认 / 禁止空读等);零 DDL 但改 JSON 语义同样适用 |
-| G4 | 必须有「回滚兼容」说明 | 若发布失败回滚:新代码已写入的数据,旧版代码是否能**安全跳过/忽略**?必须给出明确方案(如 `omitempty`、忽略未知字段、`schema_version` 分派、双写兼容窗口);禁止只写「回滚镜像」而无数据兼容结论 |
+```text
+以下章节是否写入审批文档?(默认均可选「不要」以保持精简)
+- [ ] §5 验收标准(从 specs 展开全部 Requirement/Scenario)
+- [ ] §7 部署/发布/回滚方案
+- [ ] §8 闭环性检查表(Pass 1–7 结论表)
+```
+
+- 用户选「要」→ 按下方骨架生成该章。
+- 用户选「不要」→ **整章省略**(不要写「不涉及…」占位段)。
+- 未得到明确答复前,**不要**写入文件。
+
+### ⚠️ 质量红线 — 必须严格执行
 
-### Style & Tone (文风要求) — 全文适用
+生成 `approval.md` 时,下列红线**缺一不可**;违反则详细设计/接口/数据相关章节视为不合格,确认写入前必须补全。
 
-1. **通俗易懂**:面向要动手的开发同学;避免生僻英文缩写,**首次出现必须注解**(例:`DDL`(数据定义语言)、`RPC`(远程过程调用));协议字段名/路径/代码标识符保持原文。
-2. **逻辑严密**:拒绝模棱两可词 —— **禁止**使用「尽量」「大概」「一般情况下」「可能需要」「酌情」「视情况」等;应使用「**必须**」「**禁止**」「**采用 XX 方案**」「固定为…」。若确有分支,写成显式条件表(若 A → 做 X;若 B → 做 Y),不得用含糊副词搪塞。
+| 编号 | 红线名称 | 要求 |
+|------|----------|------|
+| G1 | 一图胜千言 | 任何超过 **5 行**的文字流程描述,**必须**改为 Mermaid 图(`sequenceDiagram` / `flowchart` / `stateDiagram-v2`),禁止用长段落散文写流程 |
+| G2 | 必须有失败示例 | §4.5 每个「新增 / 修改 / 行为扩展」的接口:除成功请求与成功响应示例外,**还必须**附 ≥1 组**失败**请求或响应示例(如参数校验失败、租约过期、未认证)。只有错误码表、没有具体 HTTP/正文示例 → 不合格 |
+| G3 | 必须有数据迁移/填充方案 | 凡涉及 **JSON 字段形状变更**或**新增列**:必须写明**存量数据的默认值填充策略**(回填脚本 / 读时默认值 / 禁止空读等)。即使本迭代不做表结构变更、只改 JSON 语义,同样适用 |
+| G4 | 必须有回滚数据兼容说明 | 若发布失败需要回滚:新版本已经写入的数据,旧版本代码能否**安全跳过或忽略**?必须给出明确方案(例如忽略未知字段、按数据版本分派、兼容窗口双写等)。禁止只写「回滚镜像/回滚应用」却不说明数据兼容结论 |
+| G5 | 前端须有页面/路由清单 | 当 `uiInScope=yes`:§4.6 **必须**给出本迭代页面/路由清单与栈五元组(Framework/Styling/State/UI kit/FE testing)。禁止只写「用 React」 |
+| G6 | 关键页须有空/加载/错态 | 当 `uiInScope=yes`:每个关键 `Page · …` **至少**覆盖空态 / 加载 / 错误之一,并标明依赖的 §4.5 接口编号 |
+
+### 文风要求 — 全文适用
+
+1. **通俗易懂**:面向要动手实现的开发同学;避免生僻英文缩写,**首次出现必须中文注解**(例:DDL(数据定义语言)、RPC(远程过程调用))。
+2. **叙述用可读中文,禁止「代码腔」堆砌**:
+   - §2.1 现状与约束、§3 架构说明、§4 设计要点等**正文/列表**,用业务与模块语言书写(例:「调度侧编译目前只认接口用例类型,运行时打成扁平的 HTTP 请求规格」)。
+   - **禁止**把路径、函数名、类型名、结构体字段当作句子主干连写(反例:`compileOne` in `internal/scheduler/...` only accepts `ref_type=api_case`…)。
+   - 若确需锚定实现位置:同一条约束最多用括号**点名一次**可读定位(模块中文名 + 必要时一个路径或符号),或把路径/符号放到表格「证据」列;细节接口形状仍放在 §4.5 的字段表与示例中。
+   - Mermaid、DDL、HTTP 示例、字段表中的协议名/列名保持技术原文(不受本条限制)。
+3. **逻辑严密**:拒绝模棱两可 —— **禁止**「尽量」「大概」「一般情况下」「可能需要」「酌情」「视情况」;应使用「**必须**」「**禁止**」「**采用 XX 方案**」「固定为…」。若有分支,写成显式条件表(若 A → 做 X;若 B → 做 Y)。
 
 ```markdown
 # 技术方案审批文档: <change-name>
 
 > 本文档由 `/specflow:approval` 基于 refine 收敛后的四件套 + 现有代码与 spec 基线生成,
-> 经 AI 7 维闭环检查、架构整体设计、方案详细设计、测试策略、部署/发布/回滚、设计质量评估与可实施性评估,供人工审批使用。
+> 经 AI 闭环检查与设计质量/可实施性评估(结论在对话中反馈),并含架构与详细设计等章节,供人工审批使用。
 > 生成时间: YYYY-MM-DD HH:MM | phase: refined | 产物语言: <lang> | 技术栈: <stack>
 
 ---
@@ -443,24 +472,51 @@ AI 从 proposal `## What Changes` / `## Impact`(及 explore 相关结论)提炼,
 ## 2. 技术方案评估 (Technical Design Review)
 
 ### 2.1 现状与约束 (Context & Constraints)
-[整合 design.md Context + AI 补充的隐含约束]
 
-### 2.2 目标与非目标 (Goals & Non-Goals)
+> 用**可读中文**归纳现状与硬约束(含「本迭代禁止…」类红线)。禁止代码腔堆砌;需要锚点时见上文「文风要求」第 2 条。  
+> **0→1 绿场**:可写「尚无存量业务代码;约束来自用户确认的技术选型与组织规范」。
+
+[整合 design.md Context + AI 从锚点代码提炼的隐含约束 — 写成中文要点列表]
+
+### 2.2 技术选型 (Tech Stack Selection)
+
+> **何时必须有本章节**:  
+> - `projectMode=greenfield`(从 0 到 1),或  
+> - 四件套未写清且本变更需要的维度缺失(前端 / 后端 / 数据库与缓存 / 基础设施)。  
+> **来源优先级**:用户在 Tech Stack Intake 门禁中的确认 **>** design 决策表 **>** 仓库信号。  
+> **禁止**在未提问、未确认时由模型臆造全栈。  
+> 若本变更为棕地小改且选型沿用现网 → 可写一行「沿用现网栈:<摘要>」并跳过详表。
+
+**选型总表**(绿场或补选型时强制):
+
+| 方向 | 选定方案 | 备选(若有) | 选择理由 | 来源 |
+|------|----------|------------|----------|------|
+| 前端 | Framework / Styling / State / UI kit / FE testing | | | 用户确认 / design / 沿用现网 / 不涉及 |
+| 后端 | | | | |
+| 数据库与缓存 | | | | |
+| 基础设施 | | | | |
+| 其它(消息/搜索/… ) | | | | |
+
+> 前端行在 `uiInScope=yes` 时**必须**写成五元组(见 `frontend-guidance.md`);禁止只填「React」。
+
+将关键选型同步写入下方 **§2.4 决策评审表**(如 D-FE / D-BE / D-DB / D-Infra)。
+
+### 2.3 目标与非目标 (Goals & Non-Goals)
 [整合 design.md Goals/Non-Goals]
 
-### 2.3 决策评审表 (Decision Review)
+### 2.4 决策评审表 (Decision Review)
 
 | 决策 | 选定方案 | 备选方案 | 理由 | 影响评估 | 状态 |
 |------|---------|---------|------|---------|------|
 | D1: <name> | <方案> | <A/B> | <理由> | <评估> | Proposed |
 
-### 2.4 风险与权衡 (Risks & Trade-offs)
+### 2.5 风险与权衡 (Risks & Trade-offs)
 
 | 风险 | 严重等级 | 缓解措施 | 就绪度 |
 |------|---------|---------|--------|
 | <name> | 高/中/低 | <措施> | ✅/⚠️/❌ |
 
-### 2.5 设计质量评估 (Design Quality)
+### 2.6 设计质量评估 (Design Quality)
 
 #### 过度设计检查
 | # | 信号 | 检测到? | 证据(design/tasks 位置) |
@@ -493,6 +549,11 @@ AI 从 proposal `## What Changes` / `## Impact`(及 explore 相关结论)提炼,
 > 聚焦**宏观结构**;与 §4 方案详细设计(模块内部实现 / 时序)互补。
 > 质量标杆:`scenario-job-compile` §3 —— **图 + 图要点说明 + 核心组件表**。
 
+> **项目约定(先于起草)**:执行 `prompts/approval/project-conventions-guidance.md`,`topic=architecture`。  
+> 懒加载 Read 项目 architecture skill/rule/docs(跨 IDE 路径见该路由)。  
+> **优先级**:项目约定 + 锚点代码 **>** 通用架构常识。将硬边界/禁令写入图要点(可读中文)。  
+> 总则式标注:在图要点第 1 条或组件表注记「项目约定: <path|未发现>」。
+
 ### 3.1 总体架构 (Architecture Overview)
 
 用 Mermaid 绘制 **模块依赖/分层图**(推荐),并可附加 **系统交互总览**。
@@ -589,13 +650,12 @@ sequenceDiagram
 
 **适用范围**:涉及持久化、状态存储、数据模型的变更。纯 CLI/库项目若无数据库,覆盖配置结构 / 状态文件 / 缓存结构 / YAML schema 等"数据模型"(走下方「非库表路径」)。
 
-> **DB 技能路由(先于起草)**:执行 `prompts/approval/database-guidance.md`。  
-> - **命中** `mysql` / `postgresql` / `oracle`(及确需时的 redis/es):按路径优先级 `Read`  
->   `{ide}/specflow/guidance/database/<stack>/SKILL.md`(init 安装的 guidance pack)  
->   或包内回退 `skills/database/<stack>/SKILL.md`,以及路由表中的 DDL/索引/JSON 参考。  
-> - **未命中**(`dbStack=none`)或文件缺失:不硬套某厂商 skill,**交给大模型**按下方 SpecFlow 硬门槛生成。  
-> - 技能是 **Read 知识包**,不是 MCP tool / IDE skill;不得「invoke `/mysql`」。  
-> - 在总则「DB 技能」列注明**实际路径**(如 `.cursor/specflow/guidance/database/mysql`)或 `LLM-fallback`。
+> **项目约定 + DB 技能(先于起草,固定顺序)**:  
+> 1. 执行 `prompts/approval/project-conventions-guidance.md`,`topic=database` — Read 项目 DB 约定(若有)。  
+> 2. 执行 `prompts/approval/database-guidance.md` — 探测 `dbStack` 并 Read SpecFlow `{ide}/specflow/guidance/database/<stack>/`(或包内回退)。  
+> 3. Read 现网 DDL/迁移/锚点(Pass 6)。  
+> **优先级**:项目约定 + 现网 DDL **>** SpecFlow DB guidance **>** LLM。  
+> 不得「invoke `/mysql`」;总则须同时填写「项目约定」「DB 技能」「DDL 来源」。
 
 > **质量硬门槛(库表路径)**:只要本变更读写/依赖任何数据库表(含"零 DDL、只改读写语义"),§4.4 **必须**按下列结构输出,不得用一句话带过、不得省略 ER / DDL / 字段说明表。参考质量标杆:`scenario-job-compile` 类审批文档的「表与数据设计」章(总则结论表 → ER → 表一览 → 逐表 DDL+字段表 → 非表字段与回滚)。
 
@@ -628,6 +688,7 @@ sequenceDiagram
 | 新增 / 修改 / 删除列 | 列清单 / **无** |
 | 新增索引 | 索引清单 / **无** |
 | DDL 来源 | 仓库基线路径 或 本迭代新增 |
+| 项目约定 | 实际 Read 路径(可多个用 `; `) / **未发现** |
 | DB 技能 | `{ide}/specflow/guidance/database/<stack>` / `skills/database/<stack>`(fallback) / `LLM-fallback` |
 
 紧接一段 **本迭代变更语句** 代码块:
@@ -703,7 +764,8 @@ erDiagram
 - [ ] **G4**:回滚数据兼容有明确方案或显式「无新旧互读问题」
 - [ ] 无「仅文字描述表结构、无 DDL」或「DDL 缺 ENGINE/CHARSET」的偷懒写法
 - [ ] 零 DDL 迭代禁止假装「不涉及数据库」—— 只要读写表,仍走库表路径并展示现网 DDL
-- [ ] **大纲干净**:§4.4 目录仅为 `4.4.1–4.4.4` + 各表 `##### \`name\``;**无**「DDL / 字段说明 / JSON 形状」标题节点
+- [ ] 总则含「项目约定」列(路径或「未发现」)+「DB 技能」列+「DDL 来源」
+- [ ] 若探测到项目 DB 约定,正文已体现其硬禁令;否则确认摘要 WARNING
 
 #### C. 非库表路径(CLI / 库 / 配置 / 状态文件)
 
@@ -747,6 +809,12 @@ CREATE TABLE `orders` (
 **适用范围**:暴露 API / RPC / CLI 命令 / 跨模块函数接口的变更(含「协议不变但本迭代新消费」)。
 **项目类型适配**:Web/服务 → HTTP(+RPC);CLI → commander 等命令参数;库 → 导出函数签名。
 
+> **项目约定(先于起草)**:执行 `prompts/approval/project-conventions-guidance.md`,`topic=api`。  
+> 懒加载项目 API/错误码/鉴权/契约约定。有 UI 时 **§4.6** 另跑 `topic=frontend` + `frontend-guidance.md`
+> (勿把页面树塞进 §4.5)。  
+> **优先级**:项目约定 + 现网 OpenAPI/proto **>** SpecFlow §4.5 骨架 **>** LLM。  
+> 在 §4.5.1 总览用一行注明「项目约定: <path|未发现>」。
+
 > **质量硬门槛(对外/跨端接口路径)**:只要本变更新增、修改、行为扩展或**新消费**对外接口,§4.5 **必须**按下列结构输出。参考质量标杆:`scenario-job-compile`「接口设计」章(总览与约定 → 接口清单 → 通用错误码 → 逐接口字段表+HTTP 示例 → 调用关系)。禁止只有路径名、无字段表、无错误约定、无请求/响应示例。
 
 > **大纲 / 标题层级(硬门槛 — 防 TOC 爆炸)**:大纲**只允许**下列标题;「请求体字段」「请求示例」「响应示例」「错误」等**禁止**写成标题,一律 `**加粗**`。
@@ -876,7 +944,95 @@ specflow init --artifact-language <language>
 
 **完全不涉及接口变更时写**:`不涉及接口变更(内部实现调整,无对外/跨模块接口变化)`。
 
-### 4.6 核心算法 / 逻辑说明 (Core Logic)
+### 4.6 前端 / UI 设计 (Frontend / UI Design)
+
+**适用范围**:本变更含控制台 / Web / App UI / 页面 / 路由 / 组件(见 `frontend-guidance.md` → `uiInScope`)。  
+**不涉及时**:整章省略,或在详细设计自检处写一行 `不涉及前端/UI 变更` —— **禁止**臆造页面树。
+
+> **项目约定 + IDE 落地规约 + FE 路由(先于起草)**:  
+> 1. 执行 `project-conventions-guidance.md`,`topic=frontend`。  
+> 2. 执行 `prompts/approval/frontend-guidance.md` §3 — **强制**扫描 IDE skills/rules
+>    (`.cursor` / `.claude` / `.agents`)与落地文档(组件/路由/状态/表单/样式/a11y/测试/lint);
+>    合计 ≤5 文件;`Read` 路径,禁止 `invoke`。  
+> 3. Read 现网路由/布局/API client 锚点(Pass 6 深度:仅文件)。  
+> **优先级**:项目约定 + IDE skills/rules + 现网 UI **>** §4.6 骨架 **>** LLM。
+
+> **质量硬门槛**:`uiInScope=yes` 时必须输出下列结构。禁止只有「用 React/Vue」一句话;禁止把完整目录树堆进 §2.1。  
+> **大纲 / 标题层级**:只允许 `#### 4.6.1–4.6.5` + `##### Page · <短名>`;「空态/加载/错误/依赖接口」等用 `**加粗**`。
+
+```text
+### 4.6 前端 / UI 设计
+├── #### 4.6.1 总则与本迭代结论
+├── #### 4.6.2 信息架构与路由
+├── #### 4.6.3 关键页面 / 组件详设
+│   └── ##### Page · <短名>
+├── #### 4.6.4 状态与数据获取
+└── #### 4.6.5 视觉与验证回路
+```
+
+#### 4.6.1 总则与本迭代结论
+
+| 项 | 结论 |
+|----|------|
+| Surface | Web / Mobile / Desktop / 混合 |
+| Framework | |
+| Styling / 设计系统 | |
+| State | |
+| UI kit | |
+| FE testing | |
+| 本迭代页面 | 列表 / **无新增页(仅改组件)** |
+| 项目约定 | config + 中立 docs 路径 / **未发现** |
+| IDE skills/rules | `.cursor`/`.claude`/`.agents` 下实际 Read 路径 / **未发现** |
+| 本迭代不涉及 | 例:无设计系统重建 / 无 RN |
+
+栈五元组须与 §2.2 前端行、Intake 确认一致。  
+落地禁令(组件库、禁止全局 CSS、表单校验库等)用可读中文写入本节与 §2.1;路径放本表。
+
+#### 4.6.2 信息架构与路由
+
+| 路由 / 入口 | 页面短名 | 对应 Journey / Scenario | 本迭代动作 |
+|-------------|----------|-------------------------|------------|
+| | | | 新增 / 修改 / 不动 |
+
+可用简短 Mermaid `flowchart` 画页面关系(G1:超 5 行散文改图)。
+
+#### 4.6.3 关键页面 / 组件详设
+
+对清单中每个需展开的页面输出 `##### Page · <短名>`(**仅此一级**进大纲):
+
+1. **目的**:一句话用户目标  
+2. **关键组件**:布局 / 列表 / 表单 / 抽屉…(中文名;边界「不做什么」)  
+3. **依赖接口**:§4.5 `In` 编号(无接口则写「无」并说明纯本地态)  
+4. **状态要点**:进入页需要的数据;提交后的成功态  
+5. **空态 / 加载 / 错误**(G6 — 至少一项写清文案或行为;推荐三项都写)  
+6. **权限 / 可见性**(若有)
+
+#### 4.6.4 状态与数据获取
+
+| 类别 | 方案 | 说明 |
+|------|------|------|
+| Server state | 例:React Query / SWR / 仅页面内 fetch | |
+| Client state | 例:Zustand / 组件本地 | |
+| 表单与校验 | 例:Zod + RHF / 现网表单库 | |
+| 错误呈现 | Toast / 页内 Alert / 错误边界 | 须用户可理解 |
+
+#### 4.6.5 视觉与验证回路
+
+- **响应式 / a11y**:本迭代必须覆盖的断点与可达性抽查(有则写;无则「沿用现网,本迭代不改视觉体系」)。  
+- **Visual Loop**:Generate → Render → Inspect → Refine(写清本项目的 preview / 截图 / 浏览器检查方式)。  
+- **命令**:`dev` / `test` / `e2e` / `browser check`(来自约定或 Intake;未知则 `[待 refine 澄清: FE 验证命令]`)。  
+- **AI builder**(若用):导出、本地可构建、密钥、退出计划 — 一小节即可。
+
+#### 前端路径 —— 质量自检
+
+- [ ] `uiInScope=yes` 时有 §4.6.1 五元组 + 页面清单(**G5**) + **项目约定/IDE skills/rules** 列  
+- [ ] 每个关键 Page 有依赖接口与空/加载/错态(**G6**)  
+- [ ] 页面可被 §4.2/§1.3 引用;接口编号对齐 §4.5  
+- [ ] 状态/表单/测试命令与已 Read 的 IDE/仓规约一致(有则引用路径)  
+- [ ] 大纲仅为 `4.6.1–4.6.5` + `Page · …`;无「空态」等标题节点  
+- [ ] 正文可读中文,无代码腔目录树堆砌,无整段粘贴 skill 原文
+
+### 4.7 核心算法 / 逻辑说明 (Core Logic)
 
 **适用范围**:有非平凡算法或数据处理逻辑的变更。
 | 元素 | 内容 |
@@ -887,7 +1043,7 @@ specflow init --artifact-language <language>
 
 **不涉及非平凡算法时写**:`不涉及非平凡算法(逻辑简单,无复杂数据处理)`。
 
-### 4.7 配置与运行环境 (Configuration & Runtime)
+### 4.8 配置与运行环境 (Configuration & Runtime)
 
 **适用范围**:新增配置项、环境变量、运行时依赖的变更。
 | 元素 | 内容 |
@@ -898,7 +1054,7 @@ specflow init --artifact-language <language>
 
 **不涉及配置变更时写**:`不涉及配置或运行环境变更`。
 
-### 4.8 兼容性与迁移 (Compatibility & Migration)
+### 4.9 兼容性与迁移 (Compatibility & Migration)
 
 **适用范围**:破坏性变更、JSON/列变更、或任何「新版本写入、旧版本仍可能读」的发布窗口。
 
@@ -918,12 +1074,13 @@ specflow init --artifact-language <language>
 - [ ] 有 §4.2 Happy Path **完整**时序图 + 设计要点说明
 - [ ] 每个 §4.3 业务场景均有图 + **设计要点说明**(无裸图)
 - [ ] **G1**:超过 5 行的文字流程已改为 Mermaid,无长散文流程
-- [ ] 每个详细设计元素可追溯到 §5 Requirement/Scenario 与 §2 决策
+- [ ] 每个详细设计元素可追溯到 §5 Requirement/Scenario(若有 §5)或 delta specs 中的同名条目,以及 §2 决策
 - [ ] 涉及数据/接口的均非留空;不涉及类别显式标注
 - [ ] **§4.4**:ER + DDL + 字段说明;若 JSON/新列变更则有**存量填充策略(G3)**与回滚数据兼容(G4)
 - [ ] **§4.5**:通道/清单/错误码 + 字段/成功示例 + **失败示例(G2)** + 错误表
-- [ ] **§4.4/§4.5 大纲**:目录仅含 `4.4.x`/`4.5.x` + 表名/`In` 小节;字段/示例/DDL/错误均为加粗标签,无标题节点
-- [ ] **§4.8**:回滚兼容结论明确(或显式声明无新旧数据互读问题)
+- [ ] **§4.6**(若 `uiInScope`):五元组 + 页面清单(**G5**) + 空/加载/错态(**G6**) + Visual Loop
+- [ ] **§4.4/§4.5/§4.6 大纲**:目录仅含规定小节 + 表名/`In`/`Page`;字段/示例/DDL/空态等均为加粗标签
+- [ ] **§4.9**:回滚兼容结论明确(或显式声明无新旧数据互读问题)
 - [ ] **文风**:无「尽量/大概/一般情况下」等含糊词;生僻缩写首次已注解
 - [ ] 若无法写出实现级细节,标记 `[待 refine 澄清: <元素>]`
 
@@ -931,7 +1088,10 @@ specflow init --artifact-language <language>
 
 ## 5. 验收标准 (Acceptance Criteria)
 
-[按 capability 分组,完整列出所有 Requirement + Scenario,每个 Scenario 3 级可测试性标注]
+> **可选章**:仅当用户在写入前确认「要 §5」时输出;否则整章省略。  
+> 若输出:放在架构与详细设计之后;按 capability 完整列出 Requirement + Scenario,并做 3 级可测试性标注。
+
+[仅在用户确认需要时展开]
 
 ### 5.1 Capability: <name>
 [Delta 操作类型: ADDED / MODIFIED / REMOVED / RENAMED]
@@ -947,8 +1107,8 @@ specflow init --artifact-language <language>
 
 ## 6. 测试策略 (Test Strategy)
 
-> 本章从"§5 验收标准可不可测"升级为"**用分层测试证明方案正确**"。它回答:
-> 每个验收标准(WHEN/THEN)由哪一层测试覆盖、用什么工具、目标是证明什么。
+> 本章回答:用分层测试证明方案正确。  
+> **与 §5 的关系**:若文档含 §5,矩阵必须映射到具体 Scenario;若用户未要 §5,则映射到 delta specs 中的 Requirement/Scenario **名称**(仍须可追溯,不得空泛)。
 > **选择性呈现**:只列出本变更实际需要的测试层级;不涉及的层级显式标注"不涉及"。
 
 ### 6.1 分层测试矩阵
@@ -969,6 +1129,8 @@ specflow init --artifact-language <language>
 2. 每个层级标注**工具/框架**(呼应 full-stack-skills 的"阶段→技能映射":测试阶段→test-writer/playwright/pytest)
 3. **目标要可验证**("证明 P95 < 200ms" 而非 "测性能")
 4. 新增测试 vs 修改既有测试要区分
+5. 若 `uiInScope=yes`:矩阵须覆盖组件/E2E 或 browser 检查,并与 §4.6.5 Visual Loop
+   (Generate→Render→Inspect→Refine)命令一致
 
 **示例**:
 
@@ -1001,8 +1163,8 @@ specflow init --artifact-language <language>
 
 ## 7. 部署/发布/回滚方案 (Deployment & Release)
 
-> 本章回答"方案实现后如何上线、如何发布、出问题如何回滚、上线后如何监控"。
-> **选择性呈现**:对有运行系统的项目必须;对纯库/CLI/文档项目可显式标注"不涉及运行时部署"。
+> **可选章**:仅当用户确认「要 §7」时输出;否则整章省略。  
+> 若输出:回答如何上线、如何发布、出问题如何回滚、上线后如何监控。纯库/CLI/文档项目若用户仍要本章,可写精简的「包发布/版本发布」方案,勿用空话充数。
 
 ### 7.1 部署方案 (Deployment)
 
@@ -1052,10 +1214,9 @@ specflow init --artifact-language <language>
 
 ## 8. 闭环性检查 (Closed-Loop Verification)
 
-> **写法要简练**:内部仍跑完 Pass 1–7,但写入本文只保留下表。  
-> - `PASS` / `SKIPPED`:「关键证据」一句话即可(不必贴大表)。  
-> - `WARNING` / `FAIL`:「关键证据」写清缺口(文件/Requirement/Scenario/任务 ID),最多 2–3 条要点。  
-> - **禁止**为每个 Pass 再开长小节、禁止重复贴总评表。
+> **可选章**:仅当用户确认「要 §8」时输出;否则整章省略。  
+> 无论是否写入文档,**内部分析仍必须跑完 Pass 1–7**,并在对话确认摘要中给出整体闭环结论。  
+> 若写入本文:只保留下表 —— `PASS`/`SKIPPED` 一句话;`WARNING`/`FAIL` 最多 2–3 条要点;禁止每 Pass 长小节。
 
 | Pass | 检查项 | 结论 | 关键证据(一句话;⚠️/❌ 可列 2–3 条要点) |
 |------|--------|------|--------------------------------------|
@@ -1091,12 +1252,10 @@ specflow init --artifact-language <language>
 
 ## 10. 审批意见 (Approval Decision)
 
-### 10.1 AI 预审建议
-
-**建议:** 建议批准 / 有条件批准 / 退回 refine / 拒绝
-**理由:** <1-2 句话,引用具体 verdict>
+> **禁止**在本文写入「AI 预审建议」小节。AI 预审结论(建议批准 / 有条件批准 / 退回 refine / 拒绝 + 理由)只在**对话中**向用户反馈。  
+> 本文仅保留人工签字栏。
 
-### 10.2 人工审批签字栏
+### 10.1 人工审批签字栏
 
 | 角色 | 姓名 | 审批结论 | 日期 | 意见 |
 |------|------|---------|------|------|
@@ -1116,12 +1275,12 @@ specflow init --artifact-language <language>
 | 技术方案评估 | design.md | 决策表 + 风险表 + 设计质量 |
 | 架构整体设计 | design + 锚点代码 + specs | Mermaid 图 + **图要点说明** + 组件边界表;追溯 §2 |
 | 方案详细设计 | design + specs + 锚点 + 现网 DDL/API | 设计要点 + Happy Path + 业务场景(+说明) + 数据/接口等;追溯 §5+§2 |
-| 验收标准 | specs/**/*.md | **置于设计之后**;3 级可测试性 |
-| 测试策略 | §5 验收标准 + 项目测试栈 | 分层矩阵映射验收标准 |
-| 部署/发布/回滚 | §2 决策 + 运行环境 | 部署/发布/回滚/监控 |
-| 闭环性检查 | 四件套 + 锚点 + 主 specs | 内部跑 Pass 1–7;**正文只输出一张结论表**(PASS 一句话;⚠️/❌ 要点化) |
-| 可实施性评估 | tasks + design + specs + 代码 | AI 推理 |
-| 审批意见 | 三重 verdict | AI 预审 + 人工签字栏 |
+| 验收标准 | specs/**/*.md | **可选**;用户确认后置于设计之后;3 级可测试性 |
+| 测试策略 | §5(若有)或 delta specs + 项目测试栈 | 分层矩阵可追溯 |
+| 部署/发布/回滚 | §2 决策 + 运行环境 | **可选**;用户确认后输出 |
+| 闭环性检查 | 四件套 + 锚点 + 主 specs | 内部必跑 Pass 1–7;正文表**可选** |
+| 可实施性评估 | tasks + design + specs + 代码 | AI 推理写入文档 |
+| 审批意见 | 人工签字 | **仅签字栏**;AI 预审只在对话反馈 |
 ```
 
 ### Generation Rules
@@ -1129,33 +1288,42 @@ specflow init --artifact-language <language>
 1. **§1 绪论 must be truthful and precise**: every pain point in the current-flow diagram
    must be grounded in proposal.md `## Why` / design.md Context / confirmed explore.md
    (do not invent pains). Absorb What Changes + Impact into §1.2 (no separate 变更摘要
-   chapter). Every User Journey step must trace to a §5 acceptance criterion. Every
-   Non-Goal must state its "不做理由".
-
-2. **Acceptance Criteria (§5) is exhaustive and placed after design**: include every
-   Requirement and Scenario from every delta spec. Do not summarize or omit. Do NOT place
-   acceptance before architecture/detailed design.
-
-3. **Pass 6 evidence must cite real code**: when Pass 6 is ⚠️/❌, §8「关键证据」must cite
-   actual anchor paths and concrete findings. PASS may be one line
+   chapter). Every User Journey step must trace to a §5 acceptance criterion **when §5 is
+   included**, otherwise to a named delta-spec Requirement/Scenario. Every Non-Goal must
+   state its "不做理由".
+
+2. **§5 / §7 / §8 are optional (hard rule)**: before writing `approval.md`, ask the user
+   whether to include 验收标准、部署/发布/回滚、闭环性检查表. Include a chapter only on
+   explicit yes; on no/omit, delete the whole chapter (no「不涉及」filler). When §5 is
+   included it must be exhaustive (every Requirement/Scenario) and placed after §3/§4.
+
+3. **Pass 6 evidence must cite real code**: when Pass 6 is ⚠️/❌, if §8 is included its
+   「关键证据」must cite actual anchor paths and concrete findings; always surface the
+   same evidence in the **chat** confirmation summary. PASS may be one line
    (e.g. `锚点 N 个均存在,结构可扩展`). Greenfield → `⊘` with the SKIPPED reason.
 
 4. **Pass 7 evidence must cite baseline specs**: when ⚠️/❌, cite capability/requirement
-   names compared. PASS → one line; no baseline → `⊘`.
+   names compared (in §8 if included, and always in chat). PASS → one line; no baseline → `⊘`.
 
 5. **Over-engineering evidence must cite design/tasks location**: "Signal 2 detected in
    `design.md` § D3, which defines a `ReviewerFactory` for a single reviewer type" — not
-   just "over-engineered".
+   just "over-engineered". Prefer readable Chinese in narrative; put paths/symbols in
+   evidence columns.
 
-6. **Language policy + Style & Tone**: narrative follows `artifacts.language`; protocol
-   markers, IDs, paths, commands, code stay in original form. Apply Style & Tone hard
-   rule (通俗 + 首次注解缩写 + 禁止含糊词) to all human-readable narrative.
+6. **Language policy + Style & Tone**: narrative follows `artifacts.language`. Apply
+   Style & Tone hard rules: 通俗、缩写首次注解、禁止含糊词、**禁止正文代码腔**(路径/函数名
+   堆砌 → 可读中文;协议字段/DDL/HTTP 示例除外). Protocol markers (`Requirement:` /
+   `WHEN` / `THEN`) stay in original form.
 
 7. **No file modification**: this prompt only generates `approval.md`. Do not modify the
    four artifacts, project code, or main specs.
 
 8. **Sign-off table is empty**: human sign-off fields must be blank.
 
+8b. **AI 预审不入库 (hard rule)**: never write「AI 预审建议」/§10.1 recommendation into
+    `approval.md`. Deliver 建议批准/有条件批准/退回 refine/拒绝 + 理由 only in the chat
+    confirmation summary. Document §10 contains **only** the human sign-off table.
+
 9. **§4.4 database section quality (hard rule)**: if the change reads/writes any
    relational table (including zero-DDL semantic-only changes), §4.4 MUST include:
    (a) structure-change conclusion table + explicit change SQL (or explicit「无」),
@@ -1186,39 +1354,74 @@ specflow init --artifact-language <language>
     complete Happy Path `sequenceDiagram`, and each §4.3 business scenario MUST include
     post-diagram「设计要点」explanations. Bare diagrams without notes are a quality failure.
 
-13. **Quality Gates G1–G4 (hard rule)**:
+13. **Quality Gates G1–G6 (hard rule)**:
     - **G1**: any process description longer than 5 prose lines MUST be a Mermaid
       `sequenceDiagram` / `flowchart` / `stateDiagram-v2` (no long prose flows).
     - **G2**: every added/modified/behavior-extended interface in §4.5 MUST include ≥1
       failure request/response example (validation failure, lease expiry, etc.), not only
       an error-code table.
     - **G3**: JSON shape changes or new columns MUST document存量数据默认值填充策略 in
-      §4.4.4 / §4.8.
+      §4.4.4 / §4.9.
     - **G4**: MUST state rollback data compatibility — whether old code can safely
       ignore/skip data written by new code (`omitempty`, unknown-field ignore,
       `schema_version`, etc.). "Rollback the image" alone is insufficient.
+    - **G5**: when `uiInScope=yes`, §4.6 MUST include page/route inventory + FE stack
+      五元组 (Framework / Styling / State / UI kit / FE testing). "用 React" alone fails.
+    - **G6**: when `uiInScope=yes`, each key `Page · …` MUST cover at least one of
+      空态 / 加载 / 错误, and cite §4.5 `In` ids when calling APIs.
 
 14. **Style & Tone (hard rule)**: plain language for implementers; obscure English
     abbreviations MUST be glossed on first use. Ban weasel words「尽量」「大概」
     「一般情况下」「可能需要」「酌情」「视情况」; use「必须」「禁止」「采用 XX 方案」
-    or explicit if/then tables instead.
-
-15. **§8 closed-loop must be concise (hard rule)**: write exactly one summary table
-    (Pass | 检查项 | 结论 | 关键证据). Do NOT open seven Pass subsections or a second
-    summary table. PASS/SKIPPED → one short phrase; WARNING/FAIL → ≤3 concrete bullets.
-
-16. **§4.4 database skill routing**: before drafting relational DDL, run
-    `prompts/approval/database-guidance.md`. On stack hit, resolve then Read
-    `{ide}/specflow/guidance/database/<stack>/…` (init guidance pack) or package
-    fallback `skills/database/<stack>/…`; on miss, LLM-only SpecFlow §4.4 rules.
-    Do not invent MCP tools; do not `npx skills add`; do not install packs under
-    IDE `skills/` discovery. Record the **actual path** or `LLM-fallback` in §4.4.1.
-
-17. **§4.4 / §4.5 outline hygiene (hard rule)**: Markdown TOC must stay shallow.
+    or explicit if/then tables instead. **Ban code-dump narrative** in §2.1/§3/§4 prose:
+    rewrite into readable Chinese; at most one parenthetical locator per bullet; keep
+    protocol names inside tables/DDL/HTTP examples only.
+
+15. **§8 closed-loop body is optional but analysis is not (hard rule)**: always run
+    Passes 1–7 for the chat summary. If the user opted into §8, write exactly one summary
+    table (Pass | 检查项 | 结论 | 关键证据). Do NOT open seven Pass subsections. If the
+    user opted out, omit §8 entirely from `approval.md`.
+
+16. **§4.4 database grounding (hard rule)**: before drafting relational DDL:
+    (a) run `project-conventions-guidance.md` with `topic=database` and Read up to 3
+    project convention files; (b) run `database-guidance.md` for SpecFlow pack /
+    `dbStack`; (c) Read live DDL/migrations/anchors. Priority:
+    **project conventions + live DDL > SpecFlow guidance > LLM**. Record both
+    `项目约定` and `DB 技能` (or 未发现 / LLM-fallback) in §4.4.1. Do not invent MCP
+    tools; do not `npx skills add`.
+
+17. **§4.4 / §4.5 / §4.6 outline hygiene (hard rule)**: Markdown TOC must stay shallow.
     - §4.4 headings only: `#### 4.4.1–4.4.4` + per-table `##### \`table\`(中文名)`.
     - §4.5 headings only: `#### 4.5.1–4.5.3` + per-interface `##### In · <短名>(类型)`.
+    - §4.6 headings only: `#### 4.6.1–4.6.5` + per-page `##### Page · <短名>`.
     - Labels such as「请求体字段」「请求示例」「响应示例」「错误」「DDL」「字段说明」
-      「JSON 形状」「通用错误码约定」MUST be `**bold**` body labels — **never**
-      `####` / `#####` / `######` headings. Multiple examples use bold sub-labels
-      (e.g. `**响应示例(失败 · 无启用步)**`), not extra heading nodes.
+      「JSON 形状」「通用错误码约定」「空态」「加载」「错误」「依赖接口」MUST be
+      `**bold**` body labels — **never** `####` / `#####` / `######` headings.
+      Multiple examples use bold sub-labels, not extra heading nodes.
+
+18. **Project conventions lazy-load (hard rule)**: before §3 / §4.4 / §4.5 / §4.6,
+    run `project-conventions-guidance.md` for the matching topic (`architecture` /
+    `database` / `api` / `frontend`). Prefer `specflow/config.yaml` `conventions.<topic>`
+    paths; else activeIde → other IDEs → repo-neutral docs. Max 3 files per topic. If
+    convention files exist but hard bans are ignored in the draft, emit WARNING in the
+    chat summary (and §8 if included).
+
+19. **Tech stack intake for greenfield / missing selection (hard rule)**: if
+    `projectMode=greenfield` or the four artifacts lack needed stack dimensions
+    (frontend / backend / database&cache / infrastructure), **ask the user in chat**
+    before inventing architecture or DDL. Record answers in §2.2 技术选型 and §2.4
+    decisions. Do not fabricate a full stack. Dimensions marked「不涉及」may be skipped.
+    Refusal to choose when required → `[待 refine 澄清: 技术选型]` and block guessed stacks.
+    When `uiInScope=yes`, frontend answers MUST cover the 五元组 (see
+    `frontend-guidance.md`); do not accept「React」alone.
+
+20. **§4.6 frontend section quality (hard rule)**: if `uiInScope=yes`, before drafting
+    §4.6: (a) run `topic=frontend` conventions; (b) run `frontend-guidance.md` §3 and
+    **Read** matching IDE skills/rules + implementation docs (components, routing, state,
+    forms, API client, styling, a11y, test commands, lint bans) — max 5 files, no
+    `invoke`; (c) Read live UI anchors. §4.6.1 MUST cite `项目约定` and `IDE skills/rules`
+    (or 未发现). §4.6 MUST include 4.6.1–4.6.5 (or mark `[待 refine 澄清]` for unknown
+    commands only after pages/states are specified). Cross-link pages to §4.5 `In` and
+    §4.2 journeys. Omit the whole chapter when UI is out of scope — never invent a page
+    tree. Do not paste skill bodies verbatim into `approval.md`.