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

package/prompts/approval/generate.md

@@ -20,8 +20,9 @@ Before running this flow, the SKILL.md has confirmed:
 - 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`
+- Anchor files extracted from **each in-scope repo** when `multi_repo.enabled` (Stage 1b)
 - Optional: `specflow/specs/` baseline exists (for Pass 7)
+- When multi-repo: `multi_repo.document_mode` + (`primary_repo` if unified) confirmed by user
 
 You MUST read, in this order, before any analysis:
 
@@ -37,6 +38,11 @@ You MUST read, in this order, before any analysis:
 Do not skip any of the four required artifacts. If any is missing, stop and tell the
 SKILL.md caller which are missing.
 
+When **`multi_repo.enabled=true`**, read **`prompts/approval/multi-repo-guidance.md`** first.
+Load four artifacts **from every repo** in `multi_repo.repos[]` before analysis. Unified mode
+merges cross-repo content into **one** document stored under **`primary_repo`**; per_repo mode
+writes **separate** `approval.md` per repo (see §G).
+
 ---
 
 ## Part A: Closed-Loop Verification (7 Passes)
@@ -372,7 +378,7 @@ Generate `approval.md` following this exact structure. Adapt narrative language
 | 编号 | 红线名称 | 要求 |
 |------|----------|------|
 | G1 | 一图胜千言 | 任何超过 **5 行**的文字流程描述,**必须**改为 Mermaid 图(`sequenceDiagram` / `flowchart` / `stateDiagram-v2`),禁止用长段落散文写流程 |
-| G2 | 必须有失败示例 | §4.5 每个「新增 / 修改 / 行为扩展」的接口:除成功请求与成功响应示例外,**还必须**附 ≥1 组**失败**请求或响应示例(如参数校验失败、租约过期、未认证)。只有错误码表、没有具体 HTTP/正文示例 → 不合格 |
+| G2 | 必须有失败示例 | §4.5 清单中**每个**接口(含**不变**):除成功请求与成功响应示例外,**还必须**附 ≥1 组**失败**请求或响应示例(如参数校验失败、租约过期、未认证)。只有错误码表、没有具体 HTTP/正文示例 → 不合格 |
 | G3 | 必须有数据迁移/填充方案 | 凡涉及 **JSON 字段形状变更**或**新增列**:必须写明**存量数据的默认值填充策略**(回填脚本 / 读时默认值 / 禁止空读等)。即使本迭代不做表结构变更、只改 JSON 语义,同样适用 |
 | G4 | 必须有回滚数据兼容说明 | 若发布失败需要回滚:新版本已经写入的数据,旧版本代码能否**安全跳过或忽略**?必须给出明确方案(例如忽略未知字段、按数据版本分派、兼容窗口双写等)。禁止只写「回滚镜像/回滚应用」却不说明数据兼容结论 |
 | G5 | 前端须有页面/路由清单 | 当 `uiInScope=yes`:§4.6 **必须**给出本迭代页面/路由清单与栈五元组(Framework/Styling/State/UI kit/FE testing)。禁止只写「用 React」 |
@@ -809,13 +815,13 @@ CREATE TABLE `orders` (
 **适用范围**:暴露 API / RPC / CLI 命令 / 跨模块函数接口的变更(含「协议不变但本迭代新消费」)。
 **项目类型适配**:Web/服务 → HTTP(+RPC);CLI → commander 等命令参数;库 → 导出函数签名。
 
-> **项目约定(先于起草)**:执行 `prompts/approval/project-conventions-guidance.md`,`topic=api`。  
+> **项目约定(先于起草)**:执行 `prompts/approval/project-conventions-guidance.md`,`topic=api`;再执行 **`prompts/approval/api-guidance.md`**(分层、RPC 锁名、proto/OpenAPI 可生成包)。  
 > 懒加载项目 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 示例 → 调用关系)。禁止只有路径名、无字段表、无错误约定、无请求/响应示例。
+> **质量硬门槛(对外/跨端接口路径)**:本迭代**列入 §4.5 清单**的每个接口(含**协议不变**、**本迭代消费**、**行为扩展**等),§4.5 **必须**按下列完整结构输出,**禁止**因「无协议变更」而精简、省略字段表/示例/错误约定。参考质量标杆:`scenario-job-compile`「接口设计」章(总览与约定 → 接口清单 → 通用错误码 → 逐接口字段表+HTTP 示例 → 调用关系)。禁止只有路径名、无字段表、无错误约定、无请求/响应示例。
 
 > **大纲 / 标题层级(硬门槛 — 防 TOC 爆炸)**:大纲**只允许**下列标题;「请求体字段」「请求示例」「响应示例」「错误」等**禁止**写成标题,一律 `**加粗**`。
 
@@ -853,9 +859,22 @@ CREATE TABLE `orders` (
 |------|------|---------------|
 | 新增 | 新路径或新 RPC | 完整展开(字段+示例+错误) |
 | 修改 | 请求/响应形状变化(加字段、改语义) | 完整展开,并标明**本迭代变更点** |
-| 行为扩展 | 消息形状不变,服务端认新取值/新分支 | 完整展开侧重点:行为差异与错误;可注明「请求/响应消息不变」 |
-| 不变(本迭代消费) | 协议不动,本迭代开始依赖 | 可精简:场景+协议+关键字段/查询约定+为何本迭代需要;仍建议有成功响应要点 |
-| 不变(不展开) | 已落地且本迭代不改、不新消费 | **清单可一句带过或不列入**,勿重复粘贴既有文档 |
+| 行为扩展 | 消息形状不变,服务端认新取值/新分支 | 完整展开;在「本迭代变更」写明行为差异;可注明「请求/响应消息不变」 |
+| 不变(本迭代消费) | 协议/消息形状不动,本迭代开始依赖或调用 | **完整展开**(与新增/修改同骨架);「本迭代变更」写「协议不变,本迭代消费」;禁止「详见 OpenAPI/既有文档」代替字段表与示例 |
+| 不变(协议不变) | 本迭代仍调用,协议与现网一致 | **完整展开**(同上);字段/示例须与现网 OpenAPI/proto/锚点对齐,可标注「与现网一致」 |
+
+> **清单规则(硬)**:本迭代**不调用、不消费**的接口 **不列入** §4.5 清单。**一旦列入清单,无论变更类型是否为「不变」,均须按 §4.5.2 完整骨架输出**,不得精简、不得只写路径、不得跳过示例。
+
+> **分层规则(硬 — 防 B2 类混写)**:同一业务链上的 **Worker HTTP(L2)**、**平台 gRPC+HTTP 绑定(L3)**、**东向 client RPC(L4)** 必须是 **独立 `In`**,各自完整展开。禁止在 L2 写满 HTTP 后,用「内部经 I6/I7 调用」一行代替 L4 详设。见 `api-guidance.md` §1。
+
+**2b) 契约面分层(合订/三端推荐)**:
+
+| 层 | 面 | 清单要求 |
+|----|-----|----------|
+| L1 | 控制台 HTTP | 字段表 + 示例 + 错误 |
+| L2 | Worker→Gateway HTTP | OpenAPI schema 草案 + **完整** work 鉴权头示例 |
+| L3 | Gateway 转码 RPC | **冻结** RPC 名 + proto 字段号 + `google.api.http` + **Gateway 注册点** |
+| L4 | 平台 `client/<svc>/` RPC | 完整骨架;不变亦须字段表+示例,禁止 stub |
 
 **3) 通用错误码约定**(强制;按项目现网风格映射):
 
@@ -874,10 +893,12 @@ CREATE TABLE `orders` (
 3. **幂等 / 终态语义**:若存在上报类接口,写清「成功 ≠ 资源终态」等不变量(对齐 §2 决策)。
 4. **兼容缺省**:可选字段缺省时的兼容行为写进字段表「默认」列。
 5. **与流程对齐**:接口编号可被 §4.2/§4.3 时序与 §6 测试引用。
+6. **RPC 锁名(硬)**:新增/修改 gRPC **禁止**「暂定」「如 XxxRpc」「实现时命名/对齐」。须写死 `package.ServiceMethod`,并在决策表或 §4.5 元信息一致。见 `api-guidance.md` §2。
+7. **错误映射唯一(硬)**:条件 → **唯一** gRPC code → **唯一** HTTP;禁止「403/409(与 progress 同类)」「或现网」。
 
 ##### 4.5.2 逐接口详设(强制骨架)
 
-对清单中每个需展开的编号 `In`,输出同构小节 `##### In · <短名>(<变更类型>)`(**仅此一级**进大纲;其下**禁止**再开 `####`/`#####`/`######`)。顺序固定,标签一律 `**加粗**`:
+对清单中**每个**编号 `In`(含**不变**类型),输出同构小节 `##### In · <短名>(<变更类型>)`(**仅此一级**进大纲;其下**禁止**再开 `####`/`#####`/`######`)。顺序固定,标签一律 `**加粗**`:
 
 1. **元信息**(强制表):
 
@@ -886,8 +907,9 @@ CREATE TABLE `orders` (
 | 应用场景 | 谁、在什么用户动作/系统时机下调用 |
 | 协议 | 方法 + 路径(或 CLI 命令 / 导出函数签名) |
 | Content-Type / 编码 | 如 `application/json`(若适用) |
-| 对应 RPC / 内部名 | 若有(可写暂定名 +「实现时与 OpenAPI/proto 对齐」) |
+| 对应 RPC / 内部名 | **冻结**全名(例 `scheduler.SubmitStepResult`);proto 路径;**禁止**暂定/如/实现时 |
 | 鉴权 | 本接口鉴权要点(可引用通道表) |
+| Gateway 注册 | 新增 HTTP 绑定时:**文件+函数名**或 ProtoSets 路径(禁止只写「含新绑定」) |
 | 本迭代变更 | 一句话(新增字段 / 行为扩展 / 不变仅消费 …) |
 
 2. **请求体字段**(有则写;路径参数 / Query / CLI flags 用同级加粗标签分块,如 `**Query 参数**`,仍**不要**升为标题):
@@ -901,7 +923,7 @@ CREATE TABLE `orders` (
 
 4. **成功响应字段** + **响应示例(成功)**(强制)。
 
-5. **响应示例(失败)**(质量红线 G2 — 强制):每个「新增/修改/行为扩展」接口 **≥1** 组报错示例(完整 HTTP 或等价);副标可写失败原因,例:`**响应示例(失败 · 无启用步)**`,仍**不是**标题。
+5. **响应示例(失败)**(质量红线 G2 — 强制):清单中**每个**接口 **≥1** 组报错示例(完整 HTTP 或等价);「不变」接口亦须给出典型失败场景(如参数非法、未认证、资源不存在);副标可写失败原因,例:`**响应示例(失败 · 无启用步)**`,仍**不是**标题。
 
 6. **错误**(强制表:条件 → 状态/退出码 → 说明):
 
@@ -910,6 +932,13 @@ CREATE TABLE `orders` (
 
 7. **处理顺序**(可选):多步服务端合同用编号列表;与 §4.2/§4.3、§4.4 对齐。
 
+8. **Proto / OpenAPI 契约包**( **新增** 或 **修改 HTTP 绑定** 的 RPC — 硬):在接口小节末尾用加粗标签 `**Proto 草案**` / `**OpenAPI 指针**` 输出:
+   - proto:`rpc` 全名 + `message` 字段号表 + `google.api.http` 原文
+   - Gateway:与现网同类 RPC **同一注册点**的文件/函数,或 ProtoSets 条目
+   - Worker:OpenAPI 路径 + schema 字段与 L3 一致;HTTP 示例含 **全部** 必填头
+   - status/enum **闭合**,与现网 ingest 校验一致(禁止「等」、禁止逐步 ingest 写 `running` 除非同步改白名单)
+   详见 `api-guidance.md` §3。
+
 ##### 4.5.3 调用关系(推荐)
 
 用短文本或 Mermaid 概括调用方如何串起 `I1…In`(主路径一条线即可),便于实现与联调对照。
@@ -923,8 +952,10 @@ CREATE TABLE `orders` (
 
 - [ ] 有通道/鉴权表(或多通道说明)+ 本迭代接口清单(编号+变更类型+场景)
 - [ ] 有通用错误码约定 + 命名/错误风格约定
-- [ ] 每个「新增/修改/行为扩展」接口具备:元信息、字段表、成功请求/响应示例、**失败示例(G2)**、错误表
-- [ ] 「不变·本迭代消费」接口至少有场景+协议+关键消费约定,不假装不存在
+- [ ] **分层**:L2 Worker HTTP / L3 RPC / L4 东向 RPC 各有独立 `In`,无「内部调用」stub
+- [ ] **RPC 已冻结**:无暂定/如/实现时;新增 RPC 含 proto 字段号 + http option + Gateway 注册点
+- [ ] 清单中**每个**接口(含**不变**)具备:元信息、字段表、成功请求/响应示例、**失败示例(G2)**、错误表
+- [ ] **不变**接口未因「无协议变更」而省略字段表/示例;内容与现网契约或锚点一致
 - [ ] 无「只有路径、无字段/无示例/无错误」的偷懒写法;示例与字段表一致
 - [ ] 接口编号可被 §4.2/§4.3 流程、§6 测试引用
 - [ ] **大纲干净**:§4.5 目录仅为 `4.5.1–4.5.3` + 各 `##### In · …`;**无**「请求体字段 / 请求示例 / 响应示例 / 错误」标题节点
@@ -1283,145 +1314,185 @@ specflow init --artifact-language <language>
 | 审批意见 | 人工签字 | **仅签字栏**;AI 预审只在对话反馈 |
 ```
 
-### Generation Rules
-
-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 **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 (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". Prefer readable Chinese in narrative; put paths/symbols in
-   evidence columns.
-
-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「无」),
-   (b) Mermaid `erDiagram` of core entities + a table-description legend
-   (表名/中文名/职责/结构/本迭代动作),
-   (c) per-table complete `CREATE TABLE` with storage engine + charset (MySQL:
-   `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4` …), and
-   (d) per-table field description table with「本迭代用法」.
-   Do NOT substitute prose-only schema descriptions. Do NOT omit ENGINE/CHARSET on
-   MySQL DDL. Zero-DDL iterations still show current-baseline DDL — never claim
-   「不涉及数据库」when tables are in the read/write path.
-
-10. **§4.5 interface section quality (hard rule)**: if the change adds, modifies,
-    behavior-extends, or newly consumes external/cross-service interfaces, §4.5 MUST
-    include: (a) caller/channel + auth overview, (b) numbered interface inventory with
-    change type (新增/修改/行为扩展/不变·本迭代消费), (c) common error-code mapping and
-    naming/error-style conventions, (d) per-interface meta table, field tables
-    (name/type/required/default/description), at least one success request example and
-    success response example, **(e) ≥1 failure request/response example (G2)**, and an
-    error-condition table. Do NOT ship path-only stubs without fields/examples/errors.
-    Unchanged APIs that this iteration does not consume need not be fully re-documented.
-
-11. **§3 architecture diagram key points (hard rule)**: every architecture Mermaid diagram
-    MUST be followed by a numbered「设计说明 / 图要点」list (boundary/invariants/reuse) —
-    not a mere restatement of node names. Component table alone is not enough.
-
-12. **§4 Happy Path + scenario design notes (hard rule)**: §4.1 design-points table, §4.2
-    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–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.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. **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, 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`.
+### 生成规则 (Generation Rules)
+
+1. **§1 绪论须真实准确**:现状流程图中的每个痛点必须有据于 `proposal.md` 的 `## Why`、`design.md` Context 或已确认的 `explore.md`(禁止臆造痛点)。将 What Changes + Impact 吸收进 §1.2(不设单独的「变更摘要」章)。每条 User Journey 步骤须能追溯到 §5 验收标准(**当 §5 纳入时**),否则追溯到具名 delta-spec 的 Requirement/Scenario。每条 Non-Goal 须写明「不做理由」。
+
+2. **§5 / §7 / §8 为可选章节(硬规则)**:写入 `approval.md` 前,须询问用户是否纳入验收标准、部署/发布/回滚、闭环性检查表。仅当用户明确选择「要」时才写入对应章节;选择「不要/省略」时整章删除(禁止用「不涉及」占位填充)。§5 纳入时须穷尽(覆盖每个 Requirement/Scenario),且放在 §3/§4 之后。
+
+3. **Pass 6 证据须引用真实代码**:当 Pass 6 为 ⚠️/❌ 时,若 §8 纳入,其「关键证据」须引用实际锚点路径与具体发现;**对话**确认摘要中亦须呈现相同证据。PASS 可一行带过(例:`锚点 N 个均存在,结构可扩展`)。绿场 → `⊘` 并注明 SKIPPED 原因。
+
+4. **Pass 7 证据须引用基线 specs**:当 ⚠️/❌ 时,须引用所比对的能力/requirement 名称(§8 纳入时写入正文,**对话中始终呈现**)。PASS → 一行带过;无基线 → `⊘`。
+
+5. **过度设计证据须引用 design/tasks 位置**:例:「Signal 2 见于 `design.md` § D3,为单一 reviewer 类型定义了 `ReviewerFactory`」——禁止只写「过度设计」。叙述优先可读中文;路径/符号放证据列。
+
+6. **语言策略与文风**:叙述遵循 `artifacts.language`。须遵守文风硬规则:通俗、缩写首次注解、禁止含糊词、**禁止正文代码腔**(路径/函数名堆砌 → 可读中文;协议字段/DDL/HTTP 示例除外)。协议标记(`Requirement:` / `WHEN` / `THEN`)保持原文形式。
+
+7. **禁止修改其他文件**:本 prompt 仅生成 `approval.md`。不得修改四件套、项目代码或主 specs。
+
+8. **签字栏须留空**:人工签字字段必须空白。
+
+8b. **AI 预审不入库(硬规则)**:禁止将「AI 预审建议」/§10.1 建议写入 `approval.md`。建议批准/有条件批准/退回 refine/拒绝 + 理由**仅在对话**确认摘要中交付。文档 §10 **仅**含人工签字表。
+
+9. **§4.4 数据库章节质量(硬规则)**:若变更读/写任何关系表(含零 DDL、仅语义变更),§4.4 **必须**包含:
+   (a) 结构变更结论表 + 明确变更 SQL(或明确写「无」),
+   (b) 核心实体的 Mermaid `erDiagram` + 表说明图例(表名/中文名/职责/结构/本迭代动作),
+   (c) 每张表完整 `CREATE TABLE`(含存储引擎与字符集;MySQL 须 `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4` …),
+   (d) 每张表字段说明表(含「本迭代用法」)。
+   禁止仅用散文描述 schema。MySQL DDL 禁止省略 ENGINE/CHARSET。零 DDL 迭代仍须展示当前基线 DDL —— 当表处于读/写路径时,禁止声称「不涉及数据库」。
+
+10. **§4.5 接口章节质量(硬规则)**:起草前执行 `project-conventions-guidance.md` `topic=api` + **`api-guidance.md`**.若变更涉及对外/跨服务/跨模块接口(含新增、修改、行为扩展、**协议不变但本迭代消费或调用**),§4.5 **必须**包含:
+    (a) 调用方/通道 + 鉴权总览,
+    (b) 编号稳定的接口清单(变更类型含 新增/修改/行为扩展/不变·本迭代消费/不变·协议不变),
+    (c) **契约面分层**:Worker HTTP / 平台 RPC+HTTP 绑定 / 东向 RPC **各自独立 `In`**,禁止 L2 详写、L4 一句 stub,
+    (d) 通用错误码映射(**唯一** gRPC code → **唯一** HTTP;禁止「或」「同类映射」),
+    (e) 清单中**每个**接口的元信息表、字段表、≥1 组成功请求/响应示例,
+    **(f) 每个接口 ≥1 组失败示例(G2)**,
+    (g) 错误条件表,
+    **(h) 新增/改 HTTP 绑定的 RPC**:冻结 RPC 全名 + proto 字段号 + `google.api.http` + Gateway 注册点 + Worker OpenAPI schema(禁止「暂定」「如」「实现时对齐」)。
+    禁止 stub。**一旦列入清单,无论是否不变,均须完整骨架**;可标注「与现网一致」但仍须贴字段表与示例。
+
+11. **§3 架构图须附设计要点(硬规则)**:每个架构 Mermaid 图后**必须**跟编号「设计说明 / 图要点」列表(边界/不变式/复用) —— 禁止仅复述节点名。仅有组件表不够。
+
+12. **§4 Happy Path 与场景设计要点(硬规则)**:§4.1 设计要点表、§4.2 完整 Happy Path `sequenceDiagram`、§4.3 每个业务场景**必须**在图后附「设计要点」说明。仅有图无说明视为质量不合格。
+
+13. **质量红线 G1–G6(硬规则)**:
+    - **G1**:超过 5 行散文的流程描述**必须**改为 Mermaid `sequenceDiagram` / `flowchart` / `stateDiagram-v2`(禁止长散文流程)。
+    - **G2**:§4.5 清单中**每个**接口(含**不变**)**必须**含 ≥1 组失败请求/响应示例(参数校验失败、租约过期等),禁止仅有错误码表。
+    - **G3**:JSON 形状变更或新增列**必须**在 §4.4.4 / §4.9 记录存量数据默认值填充策略。
+    - **G4**:**必须**说明回滚数据兼容性 —— 旧代码能否安全忽略/跳过新代码写入的数据(`omitempty`、未知字段忽略、`schema_version` 等)。仅写「回滚镜像」不够。
+    - **G5**:当 `uiInScope=yes` 时,§4.6 **必须**含页面/路由清单 + 前端栈五元组(Framework / Styling / State / UI kit / FE testing)。仅写「用 React」不合格。
+    - **G6**:当 `uiInScope=yes` 时,每个关键 `Page · …` **必须**覆盖空态/加载/错误至少一项,调用 API 时引用 §4.5 `In` 编号。
+
+14. **文风(硬规则)**:面向实现者的通俗语言;生僻英文缩写首次使用须注解。禁止含糊词「尽量」「大概」「一般情况下」「可能需要」「酌情」「视情况」;改用「必须」「禁止」「采用 XX 方案」或显式 if/then 表。**禁止** §2.1/§3/§4 正文代码腔:改写为可读中文;每条 bullet 括号内定位至多一次;协议名仅出现在表/DDL/HTTP 示例中。
+
+15. **§8 闭环正文可选但分析不可省(硬规则)**:对话摘要**始终**跑 Pass 1–7。用户选择纳入 §8 时,正文**仅**写一张汇总表(Pass | 检查项 | 结论 | 关键证据)。禁止展开七个 Pass 子节。用户选择省略时,`approval.md` 中**完全**不含 §8。
+
+16. **§4.4 数据库取证(硬规则)**:起草关系型 DDL 前:
+    (a) 执行 `project-conventions-guidance.md`,`topic=database`,Read 最多 3 份项目约定;
+    (b) 执行 `database-guidance.md` 取 SpecFlow pack / `dbStack`;
+    (c) Read 现网 DDL/迁移/锚点。优先级:**项目约定 + 现网 DDL > SpecFlow guidance > LLM**。§4.4.1 须记录 `项目约定` 与 `DB 技能`(或 未发现 / LLM-fallback)。禁止臆造 MCP 工具;禁止 `npx skills add`。
+
+17. **§4.4 / §4.5 / §4.6 大纲层级(硬规则)**:Markdown 目录须保持浅层。
+    - §4.4 标题仅:`#### 4.4.1–4.4.4` + 每表 `##### \`table\`(中文名)`。
+    - §4.5 标题仅:`#### 4.5.1–4.5.3` + 每接口 `##### In · <短名>(类型)`。
+    - §4.6 标题仅:`#### 4.6.1–4.6.5` + 每页 `##### Page · <短名>`。
+    - 「请求体字段」「请求示例」「响应示例」「错误」「DDL」「字段说明」「JSON 形状」「通用错误码约定」「空态」「加载」「错误」「依赖接口」等**必须**为 `**加粗**` 正文标签 —— **禁止** `####` / `#####` / `######` 标题。多组示例用加粗副标,禁止额外标题节点。
+
+18. **项目约定懒加载(硬规则)**:写 §3 / §4.4 / §4.5 / §4.6 前,执行 `project-conventions-guidance.md` 对应主题(`architecture` / `database` / `api` / `frontend`)。优先 `specflow/config.yaml` 的 `conventions.<topic>`;否则 activeIde → 其他 IDE → 仓根中立文档。每主题最多 3 文件。若约定文件存在但草稿违反硬禁令,在对话摘要(及 §8 若纳入)中发出 WARNING。
+
+19. **绿场/缺选型 Tech Stack Intake(硬规则)**:若 `projectMode=greenfield` 或四件套缺少所需栈维度(前端/后端/数据库与缓存/基础设施),**须在对话中询问用户**后再写架构或 DDL。答案写入 §2.2 技术选型与 §2.4 决策。禁止臆造全栈。标「不涉及」的维度可跳过。必选维度用户拒绝选择 → `[待 refine 澄清: 技术选型]` 并阻止猜测栈。`uiInScope=yes` 时前端答案须覆盖五元组(见 `frontend-guidance.md`);不接受仅「React」。
+
+20. **§4.6 前端章节质量(硬规则)**:若 `uiInScope=yes`,起草 §4.6 前:
+    (a) 执行 `topic=frontend` 约定;
+    (b) 执行 `frontend-guidance.md` §3 并 **Read** 匹配的 IDE skills/rules + 实现文档(组件/路由/状态/表单/API client/样式/a11y/测试命令/lint 禁令) —— 最多 5 文件,禁止 `invoke`;
+    (c) Read 现网 UI 锚点。§4.6.1 **必须**引用 `项目约定` 与 `IDE skills/rules`(或 未发现)。§4.6 **必须**含 4.6.1–4.6.5(页面/状态明确后,未知命令方可标 `[待 refine 澄清]`)。页面交叉引用 §4.5 `In` 与 §4.2 旅程。UI 不在范围时整章省略 —— 禁止臆造页面树。禁止将 skill 正文原文粘贴进 `approval.md`。
+
+---
+
+## Part F: Segmented Generation (Map → CLI Reduce)
+
+> Router detail: `prompts/approval/segmented-generation.md`  
+> Index template: `templates/approval-index.yaml` · Part fragment: `templates/approval-part.md`
+
+When `approval/index.yaml` has `mode: segmented` (default for non-trivial §4), follow
+**12a → Gate → 12b → 12c → 12d**. The external artifact remains `approval.md`; the
+`approval/` directory is agent workspace only.
+
+### F.1 When to segment
+
+| Condition | Mode |
+|-----------|------|
+| `tables > 2` OR `interfaces > 3` OR `pages > 2` OR `optional.s5=true` | **segmented** (mandatory) |
+| Else | ask user: segmented (recommended) or monolithic |
+
+### F.2 Pipeline (hard order)
+
+1. **12a Index + Skeleton** — write `index.yaml` + `analysis.json` + parts 01–03, 04-detail-core, 06/09/10
+2. **Gate** — user confirms index inventory + optional chapters + mode
+3. **12b Map Append** — batched `04.4*` / `04.5*` / `04.6*` / `04.7–04.9`
+4. **12c Optional** — `05*` / `07` / `08` only when opted in
+5. **12d CLI Reduce** — `specflow approval check` then `specflow approval assemble --force`
+
+**Reduce 禁止 LLM** — never stitch parts in chat or paste from memory.
+
+### F.3 Anti-lazy rules (Map — hard)
+
+| # | Forbidden | Required |
+|---|-----------|----------|
+| L1 | One-shot full `approval.md` when `mode=segmented` | Write parts; CLI assemble |
+| L2 | Empty part, `< 20` chars, placeholder-only | Full section per Part E |
+| L3 | `TODO` / `待补充` / `此处省略` / bare `TBD` | Concrete text or `[待 refine 澄清: <元素>]` |
+| L4 | `详见 design/tasks` without §/In/Page id | Cross-ref `§4.5 I2` / `Page·列表` / `P1` |
+| L5 | New table/interface/page ids not in index | Update `index.yaml` first |
+| L6 | Skip DDL/字段表/失败示例 because "same as design" or "unchanged API" | G2–G6 minimum; **不变**仍须完整 §4.5 骨架 |
+| L6b | Collapse L4 RPC into「内部调用 I7」; L2-only HTTP without proto | **分层**: L2/L3/L4 各独立 `In`;见 `api-guidance.md` §1 |
+| L6c | RPC「暂定/如/实现时命名」 | **冻结** `Service.Method` + proto 字段号;见 `api-guidance.md` §2–§3 |
+| L7 | Skip IDE skills/rules scan for §4.6 | `frontend-guidance.md` §3 before Map |
+| L8 | Paste skill/rule bodies verbatim | Readable Chinese + path in §4.6.1 |
+| L9 | Foreign `## N.` headings in parts | `###`/`####` only; CLI injects chapter headers |
+| L10 | Mark done without `specflow approval check` passing | Fix diagnostics; then assemble |
+
+CLI lazy validation mirrors L2–L3 (`lazy_part_content` on assemble/check).
+
+### F.4 Map context budget
+
+Per batch Read only:
+
+- `approval/index.yaml` + `approval/analysis.json` (verdicts, not full Pass essays)
+- design/tasks/spec **snippets** for batch ids
+- conventions (≤3 files/topic; frontend ≤5 total per frontend-guidance)
+- anchor files for batch entities
+
+Do not reload entire four artifacts each batch.
+
+### F.5 index.yaml contract
+
+- `parts_order` is source of truth for assemble order
+- `tables[]` / `interfaces[]` / `pages[]` entries MUST include `part` matching `approval/parts/<part>.md`
+- `optional.s5/s7/s8` gates §5/§7/§8 parts even if files exist on disk
+
+### F.6 Retry
+
+| CLI diagnostic | Action |
+|----------------|--------|
+| `lazy_part_content` | Rewrite that part only; re-check |
+| `missing_part` | Write part or fix index |
+| `id_part_mismatch` | Align index `part` with filename |
+| `orphan_part` | Add to index or delete file |
+
+Do not rerun Pass 1–7 unless analysis is stale.
+
+---
+
+## Part G: Multi-Repo Approval (多仓)
+
+> Router: `prompts/approval/multi-repo-guidance.md`
+
+### G.1 Trigger
+
+User natural language, workset, or cross-repo design → `multi_repo.enabled=true`.
+
+### G.2 User gates (hard, before Stage 12a)
+
+1. **Document mode**: `unified` (一份合订) **or** `per_repo` (多份分仓).
+2. If **unified**: **主仓** `primary_repo` — only this repo holds `approval/` + final `approval.md`.
+3. Record in `index.yaml`; do not assemble until both answered.
+
+### G.3 Unified 合订
+
+- Read **every** repo's four artifacts + anchors.
+- `index.change` **should equal** primary repo's change name.
+- Header lists all repos; §2.3 / 附录 B per-repo tables.
+- CLI: `specflow approval assemble <primary.change>` from **primary** planning root.
+
+### G.4 Per-repo 分仓
+
+- Separate `approval/` (or monolithic `approval.md`) **in each repo**.
+- Each document scoped to that repo only; cross-ref sibling paths.
+- Separate assemble per repo.
+
+### G.5 Inventory
+
+Recommend `repo` on `tables[]` / `interfaces[]` / `pages[]` entries for unified mode traceability.