@gordon.gan/specflow 1.4.1 → 1.4.2-beta

package/README.md

@@ -126,7 +126,7 @@ npm install -g @gordon.gan/specflow
 npm install -g github:Gordon-Gan-Jiang/specflow
 
 # 验证
-specflow --version   # 以 npm / package.json 为准（当前 1.4.1）
+specflow --version   # 以 npm / package.json 为准（当前 1.4.2-beta）
 specflow --help
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.4.1",
+  "version": "1.4.2-beta",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [

package/prompts/approval/generate.md

@@ -598,6 +598,20 @@ sequenceDiagram
 
 > **质量硬门槛(库表路径)**:只要本变更读写/依赖任何数据库表(含"零 DDL、只改读写语义"),§4.4 **必须**按下列结构输出,不得用一句话带过、不得省略 ER / DDL / 字段说明表。参考质量标杆:`scenario-job-compile` 类审批文档的「表与数据设计」章(总则结论表 → ER → 表一览 → 逐表 DDL+字段表 → 非表字段与回滚)。
 
+> **大纲 / 标题层级(硬门槛 — 防 TOC 爆炸)**:Markdown 预览大纲**只允许**下列标题进入目录;「DDL」「字段说明」「JSON 形状」等**禁止**写成 `####`/`#####`/`######`,一律用 **加粗标签** + 正文/代码块/表格。
+
+```text
+### 4.4 数据结构 / 数据模型变更
+├── #### 4.4.1 总则与本迭代结构变更结论
+├── #### 4.4.2 ER 图(核心实体关系)
+├── #### 4.4.3 逐表详设
+│   ├── ##### `table_a`(中文名)     ← 每张表仅此一级标题
+│   └── ##### `table_b`(中文名)
+└── #### 4.4.4 非表字段、数据迁移与回滚兼容
+```
+
+表内固定顺序用加粗标签(不是标题):`**本迭代动作**` → `**本迭代变更语句**` → `**DDL(现网/目标)**` → `**字段说明**` →(可选)`**JSON 形状 · <字段名>**`。
+
 #### A. 库表路径(MySQL / PostgreSQL / SQLite 等关系库)——强制结构
 
 按以下小节**顺序**生成。缺任一强制项 → 视为详细设计质量不合格,在确认摘要中报告用户并标记 `[待 refine 澄清]` 或补全后再写入。
@@ -651,23 +665,20 @@ erDiagram
 
 ##### 4.4.3 逐表详设(强制骨架)
 
-对表一览中的**每一张表**输出同构小节 `#### \`table_name\`(中文名)`,顺序固定:
+对表一览中的**每一张表**输出同构小节 `##### \`table_name\`(中文名)`(**仅此一级**进大纲;其下**禁止**再开标题)。顺序固定,标签一律 `**加粗**`:
 
 1. **本迭代动作**:只读 / 写入(既有路径) / 新建 / 改结构(列清单) —— 一句话 + 关键不变量(如幂等键)。
 2. **本迭代变更语句**:`无` 或完整 `ALTER`/`CREATE` 片段(可执行)。
-3. **DDL(完整建表语句)** —— **硬门槛**:
-   - 必须是完整 `CREATE TABLE ...`(即使本迭代零 DDL,也给出**现网/目标**完整表定义,便于实现者对照)。
-   - **必须含存储引擎与字符集**(MySQL 示例:`ENGINE=InnoDB DEFAULT CHARSET=utf8mb4` [`COLLATE=...` 若项目有约定则写出];PostgreSQL 写明 schema / 关键扩展约定;SQLite 可省略 ENGINE,但须完整列定义与约束)。
-   - 含 PRIMARY KEY、UNIQUE、KEY/INDEX、必要时列 `COMMENT` / 表级 `COMMENT`。
-   - 首行注释标明 DDL 来源(迁移文件路径或「本迭代新增」)。
-4. **字段说明表** —— 强制列:
+3. **DDL(现网/目标)**:完整 `CREATE TABLE ...`(即使本迭代零 DDL 也给出对照用完整表定义)。
+   - **必须含存储引擎与字符集**(MySQL:`ENGINE=InnoDB DEFAULT CHARSET=utf8mb4` …;PostgreSQL 写明 schema;SQLite 可省略 ENGINE)。
+   - 含 PRIMARY KEY、UNIQUE、KEY/INDEX、必要时列/表 `COMMENT`;首行注释标明 DDL 来源。
+4. **字段说明**:紧跟一张表(强制列):
 
 | 字段名称 | 字段类型 | 是否有默认值 | 字段说明 | 本迭代用法 |
 |----------|----------|--------------|----------|------------|
 
-   - 「本迭代用法」写清:读 / 写 / 不涉及 / **固定赋值**(`job_type=scenario`)等;本迭代相关列可加粗语义说明。
-   - 索引在 DDL 中已声明即可;若新增索引,在变更语句与字段表或表下短注中说明**支撑的查询**。
-5. 若表含 JSON / 大字段契约:另开子节给出**非表列的 JSON 形状**(字段/类型/必填/说明),与参考文档 `runtime_payload` 写法一致。
+   - 「本迭代用法」写清:读 / 写 / 不涉及 / **固定赋值**等;索引已在 DDL 声明即可。
+5. 若含 JSON / 大字段契约:用 `**JSON 形状 · <列名或逻辑名>**` 加粗标签 + 形状表/代码块,**不要**再开 `##### 字段说明` / `##### runtime_payload…` 标题。
 
 ##### 4.4.4 非表字段、数据迁移与回滚兼容
 
@@ -691,6 +702,7 @@ erDiagram
 - [ ] **G4**:回滚数据兼容有明确方案或显式「无新旧互读问题」
 - [ ] 无「仅文字描述表结构、无 DDL」或「DDL 缺 ENGINE/CHARSET」的偷懒写法
 - [ ] 零 DDL 迭代禁止假装「不涉及数据库」—— 只要读写表,仍走库表路径并展示现网 DDL
+- [ ] **大纲干净**:§4.4 目录仅为 `4.4.1–4.4.4` + 各表 `##### \`name\``;**无**「DDL / 字段说明 / JSON 形状」标题节点
 
 #### C. 非库表路径(CLI / 库 / 配置 / 状态文件)
 
@@ -736,6 +748,19 @@ CREATE TABLE `orders` (
 
 > **质量硬门槛(对外/跨端接口路径)**:只要本变更新增、修改、行为扩展或**新消费**对外接口,§4.5 **必须**按下列结构输出。参考质量标杆:`scenario-job-compile`「接口设计」章(总览与约定 → 接口清单 → 通用错误码 → 逐接口字段表+HTTP 示例 → 调用关系)。禁止只有路径名、无字段表、无错误约定、无请求/响应示例。
 
+> **大纲 / 标题层级(硬门槛 — 防 TOC 爆炸)**:大纲**只允许**下列标题;「请求体字段」「请求示例」「响应示例」「错误」等**禁止**写成标题,一律 `**加粗**`。
+
+```text
+### 4.5 接口设计
+├── #### 4.5.1 总览与约定          ← 通道 / 清单 / 通用错误码 均用加粗小标题,不进更深目录
+├── #### 4.5.2 逐接口详设
+│   ├── ##### I1 · <短名>(变更类型)  ← 每个接口仅此一级标题
+│   └── ##### I2 · …
+└── #### 4.5.3 调用关系
+```
+
+接口内固定顺序用加粗标签:`**元信息**` → `**请求体字段**`(或路径/Query/CLI flags) → `**请求示例**` → `**成功响应字段**` → `**响应示例(成功)**` → `**响应示例(失败)**`(G2) → `**错误**` →(可选)`**处理顺序**`。
+
 #### A. 对外/跨端接口路径——强制结构
 
 ##### 4.5.1 总览与约定
@@ -783,9 +808,9 @@ CREATE TABLE `orders` (
 
 ##### 4.5.2 逐接口详设(强制骨架)
 
-对清单中每个需展开的编号 `In`,输出同构小节 `#### In · <短名>(<变更类型>)`:
+对清单中每个需展开的编号 `In`,输出同构小节 `##### In · <短名>(<变更类型>)`(**仅此一级**进大纲;其下**禁止**再开 `####`/`#####`/`######`)。顺序固定,标签一律 `**加粗**`:
 
-1. **元信息表**(强制):
+1. **元信息**(强制表):
 
 | 项 | 内容 |
 |----|------|
@@ -796,29 +821,25 @@ CREATE TABLE `orders` (
 | 鉴权 | 本接口鉴权要点(可引用通道表) |
 | 本迭代变更 | 一句话(新增字段 / 行为扩展 / 不变仅消费 …) |
 
-2. **参数表**(有则分节:路径参数 / Query / 请求体 / CLI flags):
+2. **请求体字段**(有则写;路径参数 / Query / CLI flags 用同级加粗标签分块,如 `**Query 参数**`,仍**不要**升为标题):
 
 | 字段 | 类型 | 必填 | 默认 | 说明 |
 |------|------|------|------|------|
 
-   - 合法值枚举、别名归一、与表字段差异(如「API 有 `step_uid`,表无此列」)写在「说明」。
-   - 互斥参数(二选一)在说明或表下用引用块写清。
+   - 合法值枚举、别名归一、与表字段差异写在「说明」;互斥参数用引用块。
 
-3. **请求示例**(强制至少 1 个主路径成功请求):
-   - Web:` ```http ` 完整请求行 + 头 + JSON 正文
-   - CLI:` ```text ` 或 shell 调用示例
-   - 库:调用伪代码 / TypeScript 签名调用示例
+3. **请求示例**(强制 ≥1 主路径成功请求):Web 用完整 `http` 块;CLI/库用等价示例。多场景时用加粗副标区分,例:`**请求示例(场景)**` / `**请求示例(接口用例 · 兼容旧客户端)**` —— **不是**标题。
 
-4. **成功响应字段表** + **成功响应示例**(强制)
+4. **成功响应字段** + **响应示例(成功)**(强制)。
 
-5. **失败示例**(质量红线 G2 — 强制):每个「新增/修改/行为扩展」接口**必须**另附 ≥1 组报错示例(完整 HTTP 或等价),覆盖典型失败之一:参数校验失败、鉴权/租约失败、资源不存在、前置条件不满足等。示例正文须与错误表一致。
+5. **响应示例(失败)**(质量红线 G2 — 强制):每个「新增/修改/行为扩展」接口 **≥1** 组报错示例(完整 HTTP 或等价);副标可写失败原因,例:`**响应示例(失败 · 无启用步)**`,仍**不是**标题。
 
-6. **错误表**(强制;条件 → 状态/退出码 → 说明):
+6. **错误**(强制表:条件 → 状态/退出码 → 说明):
 
 | 条件 | 状态 / 退出码 | 说明 |
 |------|---------------|------|
 
-7. **处理顺序 / 合同**(可选但推荐):多步服务端合同用编号列表;与 §4.2/§4.3 流程、§4.4 落库对齐。
+7. **处理顺序**(可选):多步服务端合同用编号列表;与 §4.2/§4.3、§4.4 对齐。
 
 ##### 4.5.3 调用关系(推荐)
 
@@ -837,6 +858,7 @@ CREATE TABLE `orders` (
 - [ ] 「不变·本迭代消费」接口至少有场景+协议+关键消费约定,不假装不存在
 - [ ] 无「只有路径、无字段/无示例/无错误」的偷懒写法;示例与字段表一致
 - [ ] 接口编号可被 §4.2/§4.3 流程、§6 测试引用
+- [ ] **大纲干净**:§4.5 目录仅为 `4.5.1–4.5.3` + 各 `##### In · …`;**无**「请求体字段 / 请求示例 / 响应示例 / 错误」标题节点
 
 #### C. CLI / 库项目路径(无 HTTP 时)
 
@@ -899,6 +921,7 @@ specflow init --artifact-language <language>
 - [ ] 涉及数据/接口的均非留空;不涉及类别显式标注
 - [ ] **§4.4**:ER + DDL + 字段说明;若 JSON/新列变更则有**存量填充策略(G3)**与回滚数据兼容(G4)
 - [ ] **§4.5**:通道/清单/错误码 + 字段/成功示例 + **失败示例(G2)** + 错误表
+- [ ] **§4.4/§4.5 大纲**:目录仅含 `4.4.x`/`4.5.x` + 表名/`In` 小节;字段/示例/DDL/错误均为加粗标签,无标题节点
 - [ ] **§4.8**:回滚兼容结论明确(或显式声明无新旧数据互读问题)
 - [ ] **文风**:无「尽量/大概/一般情况下」等含糊词;生僻缩写首次已注解
 - [ ] 若无法写出实现级细节,标记 `[待 refine 澄清: <元素>]`
@@ -1189,3 +1212,11 @@ specflow init --artifact-language <language>
     LLM-only SpecFlow §4.4 rules. Do not invent MCP tools; do not `npx skills add`.
     Record `skills/database/<stack>` or `LLM-fallback` in the §4.4.1 总则 table.
 
+17. **§4.4 / §4.5 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 · <短名>(类型)`.
+    - Labels such as「请求体字段」「请求示例」「响应示例」「错误」「DDL」「字段说明」
+      「JSON 形状」「通用错误码约定」MUST be `**bold**` body labels — **never**
+      `####` / `#####` / `######` headings. Multiple examples use bold sub-labels
+      (e.g. `**响应示例(失败 · 无启用步)**`), not extra heading nodes.
+

package/skills/specflow-approval/SKILL.md

@@ -285,7 +285,9 @@ Order and hard requirements (from `generate.md` §4.1–4.8):
 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.
 
 **Traceability**: every element → **§5** Requirement/Scenario and **§2** decision.
@@ -358,7 +360,7 @@ Key rules:
 - 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).
+- §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.

package/templates/approval.md

@@ -223,7 +223,8 @@ sequenceDiagram
 ### 4.4 数据结构 / 数据模型变更 (Data Structures)
 
 <!-- 库表硬门槛 + DB 技能路由:命中 skills/database/<stack> 则 Read 补强;
-     未命中 LLM-fallback。总则表填写「DB 技能」列。详见 prompts/approval/database-guidance.md。 -->
+     未命中 LLM-fallback。总则表填写「DB 技能」列。详见 prompts/approval/database-guidance.md。
+     大纲硬门槛:仅 4.4.1–4.4.4 + ##### 表名;DDL/字段说明/JSON 用 **加粗**,禁止再开标题。 -->
 
 #### 4.4.1 总则与本迭代结构变更结论
 
@@ -257,8 +258,11 @@ erDiagram
 ##### `<table_name>`(中文名)
 
 **本迭代动作**: …
+
 **本迭代变更语句**: …
 
+**DDL(现网/目标)**:
+
 ```sql
 CREATE TABLE `table_name` (
   ...
@@ -266,10 +270,14 @@ CREATE TABLE `table_name` (
   COMMENT='...';
 ```
 
+**字段说明**:
+
 | 字段名称 | 字段类型 | 是否有默认值 | 字段说明 | 本迭代用法 |
 |----------|----------|--------------|----------|------------|
 | | | | | |
 
+<!-- 可选:**JSON 形状 · runtime_payload** + 形状表/代码块 — 仍用加粗,不要 ##### -->
+
 #### 4.4.4 非表字段、数据迁移与回滚兼容
 
 | 项 | 说明 |
@@ -282,7 +290,9 @@ CREATE TABLE `table_name` (
 
 ### 4.5 接口设计 (Interface Design)
 
-<!-- 硬门槛:通道 → 清单 → 错误约定 → 逐接口字段/示例/错误表 → 调用关系。详见 generate.md §4.5。 -->
+<!-- 硬门槛:通道 → 清单 → 错误约定 → 逐接口字段/示例/错误表 → 调用关系。
+     大纲硬门槛:仅 4.5.1–4.5.3 + ##### In;请求体字段/示例/错误用 **加粗**,禁止再开标题。
+     详见 generate.md §4.5。 -->
 
 #### 4.5.1 总览与约定
 
@@ -308,17 +318,33 @@ CREATE TABLE `table_name` (
 
 ##### I1 · `<短名>`(`<变更类型>`)
 
+**元信息**:
+
 | 项 | 内容 |
 |----|------|
 | 应用场景 | |
 | 协议 | |
 | 本迭代变更 | |
 
+**请求体字段**:
+
 | 字段 | 类型 | 必填 | 默认 | 说明 |
 |------|------|------|------|------|
 | | | | | |
 
-**请求示例** / **成功响应示例** / **失败示例(G2 强制)** / **错误表** …
+**请求示例**: …
+
+**成功响应字段**: …
+
+**响应示例(成功)**: …
+
+**响应示例(失败)** *(G2 强制)*: …
+
+**错误**:
+
+| 条件 | 状态 / 退出码 | 说明 |
+|------|---------------|------|
+| | | |
 
 #### 4.5.3 调用关系