@gordon.gan/specflow 1.4.1 → 1.4.3-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.3-beta）
 specflow --help
 ```
 

package/dist/integrations/claude/adapter.js

@@ -69,6 +69,7 @@ async function inspectClaude(projectRoot) {
     const promptsDir = join(projectRoot, '.claude', 'specflow', 'prompts');
     const schemasDir = join(projectRoot, '.claude', 'specflow', 'schemas');
     const templatesDir = join(projectRoot, '.claude', 'specflow', 'templates');
+    const guidanceDir = join(projectRoot, '.claude', 'specflow', 'guidance');
     const supported = [];
     const skillContentsByCommand = {};
     for (const command of COMMAND_CATALOG) {
@@ -98,6 +99,7 @@ async function inspectClaude(projectRoot) {
             runtimePromptsDir: { exists: await directoryExists(promptsDir), hash: await hashDirectoryTree(promptsDir) },
             runtimeSchemasDir: { exists: await directoryExists(schemasDir), hash: await hashDirectoryTree(schemasDir) },
             runtimeTemplatesDir: { exists: await directoryExists(templatesDir), hash: await hashDirectoryTree(templatesDir) },
+            runtimeGuidanceDir: { exists: await directoryExists(guidanceDir), hash: await hashDirectoryTree(guidanceDir) },
         },
     };
 }

package/dist/integrations/codex/adapter.js

@@ -40,6 +40,7 @@ function renderCodexAgentsBlock() {
         '- Use artifacts under specflow/changes/<change>/ before coding',
         '- Workflow skills: $specflow-explore, $specflow-propose, $specflow-refine, $specflow-apply, $specflow-review, $specflow-test, $specflow-verify, $specflow-archive, $specflow-fix, $specflow-snap',
         '- Runtime prompts live under .agents/specflow/prompts/',
+        '- Guidance packs (non-IDE skills) live under .agents/specflow/guidance/',
         '',
     ].join('\n');
 }
@@ -96,6 +97,7 @@ async function inspectCodex(projectRoot) {
     const promptsDir = join(projectRoot, '.agents', 'specflow', 'prompts');
     const schemasDir = join(projectRoot, '.agents', 'specflow', 'schemas');
     const templatesDir = join(projectRoot, '.agents', 'specflow', 'templates');
+    const guidanceDir = join(projectRoot, '.agents', 'specflow', 'guidance');
     let agentsFileExists = false;
     try {
         const agentsContent = await fs.readFile(agentsFile, 'utf-8');
@@ -134,6 +136,7 @@ async function inspectCodex(projectRoot) {
             runtimePromptsDir: { exists: await directoryExists(promptsDir), hash: await hashDirectoryTree(promptsDir) },
             runtimeSchemasDir: { exists: await directoryExists(schemasDir), hash: await hashDirectoryTree(schemasDir) },
             runtimeTemplatesDir: { exists: await directoryExists(templatesDir), hash: await hashDirectoryTree(templatesDir) },
+            runtimeGuidanceDir: { exists: await directoryExists(guidanceDir), hash: await hashDirectoryTree(guidanceDir) },
         },
     };
 }

package/dist/integrations/cursor/adapter.js

@@ -89,6 +89,7 @@ async function inspectCursor(projectRoot) {
     const promptsDir = join(projectRoot, '.cursor', 'specflow', 'prompts');
     const schemasDir = join(projectRoot, '.cursor', 'specflow', 'schemas');
     const templatesDir = join(projectRoot, '.cursor', 'specflow', 'templates');
+    const guidanceDir = join(projectRoot, '.cursor', 'specflow', 'guidance');
     const supported = [];
     const skillContentsByCommand = {};
     for (const command of COMMAND_CATALOG) {
@@ -119,6 +120,7 @@ async function inspectCursor(projectRoot) {
             runtimePromptsDir: { exists: await directoryExists(promptsDir), hash: await hashDirectoryTree(promptsDir) },
             runtimeSchemasDir: { exists: await directoryExists(schemasDir), hash: await hashDirectoryTree(schemasDir) },
             runtimeTemplatesDir: { exists: await directoryExists(templatesDir), hash: await hashDirectoryTree(templatesDir) },
+            runtimeGuidanceDir: { exists: await directoryExists(guidanceDir), hash: await hashDirectoryTree(guidanceDir) },
         },
     };
 }

package/dist/integrations/shared/parity-comparator.js

@@ -4,6 +4,7 @@ import { CAPABILITY_MANIFEST, IDE_ASSET_MANIFEST } from './parity-manifest.js';
 const PARITY_COMPARABLE_ASSET_KEYS = [
     'runtimeSchemasDir',
     'runtimeTemplatesDir',
+    'runtimeGuidanceDir',
 ];
 export function validateReportAgainstManifest(report) {
     const deltas = [];

package/dist/integrations/shared/parity-manifest.js

@@ -42,6 +42,7 @@ export const IDE_ASSET_MANIFEST = [
             'runtimePromptsDir',
             'runtimeSchemasDir',
             'runtimeTemplatesDir',
+            'runtimeGuidanceDir',
         ],
     },
     {
@@ -53,6 +54,7 @@ export const IDE_ASSET_MANIFEST = [
             'runtimePromptsDir',
             'runtimeSchemasDir',
             'runtimeTemplatesDir',
+            'runtimeGuidanceDir',
         ],
     },
     {
@@ -63,6 +65,7 @@ export const IDE_ASSET_MANIFEST = [
             'runtimePromptsDir',
             'runtimeSchemasDir',
             'runtimeTemplatesDir',
+            'runtimeGuidanceDir',
         ],
     },
 ];

package/dist/integrations/shared/runtime-assets.d.ts

@@ -1,2 +1,15 @@
 import type { IdeTarget } from './types.js';
+export declare function ideRootDir(ide: IdeTarget): string;
+interface GuidancePackSpec {
+    readonly id: string;
+    readonly source: string;
+    readonly installAs: string;
+    readonly consumers?: readonly string[];
+}
+/**
+ * Loads guidance pack registry from skills/guidance-packs.yaml.
+ * Missing or empty registry → no packs (non-fatal).
+ */
+export declare function loadGuidancePacks(packageRoot: string): Promise<readonly GuidancePackSpec[]>;
 export declare function copyRuntimeAssets(packageRoot: string, projectRoot: string, ide: IdeTarget): Promise<readonly string[]>;
+export {};

package/dist/integrations/shared/runtime-assets.js

@@ -1,7 +1,9 @@
+import { promises as fs } from 'node:fs';
 import { join } from 'node:path';
+import yaml from 'js-yaml';
 import { copyDirRecursive, copyDirRecursiveRendered } from './asset-copy.js';
 import { renderIdeContent } from './skill-renderer.js';
-function ideRootDir(ide) {
+export function ideRootDir(ide) {
     if (ide === 'claude') {
         return '.claude';
     }
@@ -10,12 +12,48 @@ function ideRootDir(ide) {
     }
     return '.agents';
 }
+/**
+ * Loads guidance pack registry from skills/guidance-packs.yaml.
+ * Missing or empty registry → no packs (non-fatal).
+ */
+export async function loadGuidancePacks(packageRoot) {
+    const registryPath = join(packageRoot, 'skills', 'guidance-packs.yaml');
+    let content;
+    try {
+        content = await fs.readFile(registryPath, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const parsed = yaml.load(content);
+    if (!parsed || !Array.isArray(parsed.packs)) {
+        return [];
+    }
+    return parsed.packs.filter((pack) => typeof pack?.id === 'string' &&
+        typeof pack?.source === 'string' &&
+        typeof pack?.installAs === 'string');
+}
+async function copyGuidancePacks(packageRoot, specflowRoot) {
+    const packs = await loadGuidancePacks(packageRoot);
+    for (const pack of packs) {
+        const src = join(packageRoot, ...pack.source.split('/'));
+        const dest = join(specflowRoot, ...pack.installAs.split('/'));
+        await copyDirRecursive(src, dest);
+    }
+}
 export async function copyRuntimeAssets(packageRoot, projectRoot, ide) {
-    const root = join(projectRoot, ideRootDir(ide), 'specflow');
+    const ideRoot = ideRootDir(ide);
+    const root = join(projectRoot, ideRoot, 'specflow');
     const promptsSrc = join(packageRoot, 'prompts');
     const promptsDest = join(root, 'prompts');
     await copyDirRecursiveRendered(promptsSrc, promptsDest, (content) => renderIdeContent(content, ide));
     await copyDirRecursive(join(packageRoot, 'schemas'), join(root, 'schemas'));
     await copyDirRecursive(join(packageRoot, 'templates'), join(root, 'templates'));
-    return [`${ideRootDir(ide)}/specflow/prompts`, `${ideRootDir(ide)}/specflow/schemas`, `${ideRootDir(ide)}/specflow/templates`];
+    await copyGuidancePacks(packageRoot, root);
+    return [
+        `${ideRoot}/specflow/prompts`,
+        `${ideRoot}/specflow/schemas`,
+        `${ideRoot}/specflow/templates`,
+        `${ideRoot}/specflow/guidance`,
+    ];
 }

package/package.json

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

package/prompts/approval/database-guidance.md

@@ -1,9 +1,11 @@
 # Approval · Database Guidance Router
 
 > Used by `/specflow:approval` when generating §4.4 (数据结构 / 数据模型).  
-> **本地技能**: `skills/database/`（本仓库长期维护）。  
+> **Guidance pack**: `database`（见 `skills/guidance-packs.yaml` / `skills/GUIDANCE_PACKS.md`）。  
+> **业务仓落地**: `{ide}/specflow/guidance/database/`（`specflow init` 同步；**不是** IDE skill）。  
 > **禁止**依赖远程 skill 仓库（禁止 `npx skills add` / clone / 运行时 fetch）。  
-> **Not** an MCP tool — on hit, `Read` local matched skill files; on miss, LLM-only §4.4.
+> **Not** an MCP tool — on hit, `Read` local matched skill files; on miss, LLM-only §4.4.  
+> **禁止**写成「invoke `/mysql` skill」——一律 `Read` 路径。
 
 ---
 
@@ -28,18 +30,35 @@ Scan the **project under review** (change's repo root), not SpecFlow itself. Col
 **Multi-hit**: pick primary OLTP store for §4.4 (prefer `mysql` / `postgresql` / `oracle` over
 `redis` / `elasticsearch`). Mention secondary stores in §4.7/架构 if relevant.
 
-**Announce** after detection:
+---
+
+## 2. Resolve guidance root (path priority)
+
+Before reading pack files, resolve `guidanceRoot` for stack `<stack>`:
+
+| Priority | Path | When |
+|----------|------|------|
+| 1 | `.cursor/specflow/guidance/database/<stack>/` | Cursor IDE assets present |
+| 1 | `.claude/specflow/guidance/database/<stack>/` | Claude IDE assets present |
+| 1 | `.agents/specflow/guidance/database/<stack>/` | Codex IDE assets present |
+| 2 | `skills/database/<stack>/` | SpecFlow package / self-repo fallback (relative to SpecFlow package root) |
+| 3 | *(missing)* | `LLM-fallback` |
+
+If multiple IDE roots exist, prefer the IDE the user is running in; otherwise the first existing path among cursor → claude → agents.
+
+**Announce** after detection + resolve:
 
 ```text
 DB stack for approval: <mysql|postgresql|oracle|redis|elasticsearch|none>
-Guidance: skills/database/<stack>/SKILL.md | LLM-fallback
+Guidance: <.cursor|claude|agents>/specflow/guidance/database/<stack>/SKILL.md
+         | skills/database/<stack>/SKILL.md | LLM-fallback
 ```
 
 ---
 
-## 2. On hit — load **local** guidance (Read, do not invent, do not fetch)
+## 3. On hit — load **local** guidance (Read, do not invent, do not fetch)
 
-Base: `skills/database/<stack>/`（相对 SpecFlow 仓库根；离线可读）
+Base = resolved `guidanceRoot` above. From that directory:
 
 | Stack | Must Read | Also Read when §4.4 needs it |
 |-------|-----------|------------------------------|
@@ -49,31 +68,36 @@ Base: `skills/database/<stack>/`（相对 SpecFlow 仓库根；离线可读）
 | `redis` | `SKILL.md` | Only if change is cache/key design — **not** a substitute for relational DDL |
 | `elasticsearch` | `SKILL.md` | Only if change is index/mapping — **not** a substitute for relational DDL |
 
+Point to files **from the router entry** (no reference→reference chains).
+
 Apply guidance to §4.4 output:
 
 1. Prefer engine/charset/collation idioms from the local skill (MySQL: InnoDB + utf8mb4…).
 2. Prefer type/index gotchas from the skill (e.g. DECIMAL for money, no FLOAT amounts).
 3. Keep SpecFlow hard rules (ER, full CREATE TABLE, 本迭代用法, G3/G4) — skill **supplements**, does not replace.
 
-Cite in §4.4 总则, e.g. `DB 技能: skills/database/mysql (本地)`.
+Cite in §4.4 总则 the **actual** path used, e.g.  
+`DB 技能: .cursor/specflow/guidance/database/mysql` 或 `skills/database/mysql (package fallback)`.
 
 ---
 
-## 3. On miss — LLM fallback
+## 4. On miss — LLM fallback
 
-If `DB stack = none` (no durable store signals, or only unknown/custom DB):
+If `DB stack = none`, or stack set but **no** guidance root resolves:
 
 1. **Do not** force-load mysql/postgresql skills.
 2. Generate §4.4 with SpecFlow rules only (`generate.md` §4.4 + Quality Gates G3/G4).
 3. If design/tasks claim a DB but signals are absent → `WARNING` in §8:
    `design 声称落库但未检测到 DB 栈信号 — 已用 LLM 通用 DDL;建议 refine 标明引擎`.
-4. Pure CLI/config changes → keep `不涉及数据库变更(...)`.
+4. If stack detected but guidance files missing → `WARNING` in §8:
+   `dbStack=<stack> 但未找到 guidance/database — 已用 LLM-fallback;建议 specflow init --force-assets`.
+5. Pure CLI/config changes → keep `不涉及数据库变更(...)`.
 
 ---
 
-## 4. Why not remote skills / MCP tools?
+## 5. Why not remote skills / MCP / IDE skills?
 
-- **Remote**: approval must work offline and must not drift with upstream installs; maintain
-  `skills/database/` in this repo.
-- **MCP tools**: these packs are markdown guidance, not APIs; routing chooses which local
-  files to `Read`.
+- **Remote**: approval must work offline; maintain pack in this repo + init sync.
+- **MCP tools**: markdown guidance, not APIs; routing chooses which local files to `Read`.
+- **IDE skills**: packs must **not** appear under `.cursor/skills` / `.claude/skills` / `.agents/skills`
+  (noise + false discoverability). They live only under `{ide}/specflow/guidance/`.

package/prompts/approval/generate.md

@@ -590,14 +590,29 @@ sequenceDiagram
 **适用范围**:涉及持久化、状态存储、数据模型的变更。纯 CLI/库项目若无数据库,覆盖配置结构 / 状态文件 / 缓存结构 / YAML schema 等"数据模型"(走下方「非库表路径」)。
 
 > **DB 技能路由(先于起草)**:执行 `prompts/approval/database-guidance.md`。  
-> - **命中** `mysql` / `postgresql` / `oracle`(及确需时的 redis/es):`Read`  
->   `skills/database/<stack>/SKILL.md` 与路由表中的 DDL/索引/JSON 参考,用其惯例补强类型、引擎、字符集、索引与 Gotchas。  
-> - **未命中**(`dbStack=none`):不硬套某厂商 skill,**交给大模型**按下方 SpecFlow 硬门槛生成。  
-> - 技能是 **Read 知识包**,不是 MCP tool;不得用「调 tool」替代读文件。  
-> - 在总则「DDL 来源」旁注明:`skills/database/<stack>`(本地) 或 `LLM-fallback`。
+> - **命中** `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`。
 
 > **质量硬门槛(库表路径)**:只要本变更读写/依赖任何数据库表(含"零 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 澄清]` 或补全后再写入。
@@ -613,7 +628,7 @@ sequenceDiagram
 | 新增 / 修改 / 删除列 | 列清单 / **无** |
 | 新增索引 | 索引清单 / **无** |
 | DDL 来源 | 仓库基线路径 或 本迭代新增 |
-| DB 技能 | `skills/database/<stack>`(本地) / `LLM-fallback` |
+| DB 技能 | `{ide}/specflow/guidance/database/<stack>` / `skills/database/<stack>`(fallback) / `LLM-fallback` |
 
 紧接一段 **本迭代变更语句** 代码块:
 
@@ -651,23 +666,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 +703,7 @@ erDiagram
 - [ ] **G4**:回滚数据兼容有明确方案或显式「无新旧互读问题」
 - [ ] 无「仅文字描述表结构、无 DDL」或「DDL 缺 ENGINE/CHARSET」的偷懒写法
 - [ ] 零 DDL 迭代禁止假装「不涉及数据库」—— 只要读写表,仍走库表路径并展示现网 DDL
+- [ ] **大纲干净**:§4.4 目录仅为 `4.4.1–4.4.4` + 各表 `##### \`name\``;**无**「DDL / 字段说明 / JSON 形状」标题节点
 
 #### C. 非库表路径(CLI / 库 / 配置 / 状态文件)
 
@@ -736,6 +749,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 +809,9 @@ CREATE TABLE `orders` (
 
 ##### 4.5.2 逐接口详设(强制骨架)
 
-对清单中每个需展开的编号 `In`,输出同构小节 `#### In · <短名>(<变更类型>)`:
+对清单中每个需展开的编号 `In`,输出同构小节 `##### In · <短名>(<变更类型>)`(**仅此一级**进大纲;其下**禁止**再开 `####`/`#####`/`######`)。顺序固定,标签一律 `**加粗**`:
 
-1. **元信息表**(强制):
+1. **元信息**(强制表):
 
 | 项 | 内容 |
 |----|------|
@@ -796,29 +822,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 +859,7 @@ CREATE TABLE `orders` (
 - [ ] 「不变·本迭代消费」接口至少有场景+协议+关键消费约定,不假装不存在
 - [ ] 无「只有路径、无字段/无示例/无错误」的偷懒写法;示例与字段表一致
 - [ ] 接口编号可被 §4.2/§4.3 流程、§6 测试引用
+- [ ] **大纲干净**:§4.5 目录仅为 `4.5.1–4.5.3` + 各 `##### In · …`;**无**「请求体字段 / 请求示例 / 响应示例 / 错误」标题节点
 
 #### C. CLI / 库项目路径(无 HTTP 时)
 
@@ -899,6 +922,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 澄清: <元素>]`
@@ -1184,8 +1208,17 @@ specflow init --artifact-language <language>
     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, Read local
-    `skills/database/<stack>/…` (in-repo, no remote fetch) and apply idioms; on miss,
-    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.
+    `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.
+    - §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/GUIDANCE_PACKS.md

@@ -0,0 +1,49 @@
+# Guidance Packs（两层技能模型）
+
+SpecFlow 区分两类能力包，避免把内部知识暴露成可 `/` 调用的 IDE skill。
+
+## 两层模型
+
+| 层 | 包内位置 | 业务仓落地 | IDE 可发现 |
+|----|----------|------------|------------|
+| **Workflow skill** | `skills/specflow-*` + `COMMAND_CATALOG` | `.cursor/skills/specflow-*`（及 claude/agents） | 是 |
+| **Guidance pack** | `skills/<pack>/` + 本注册表 | `{ide}/specflow/guidance/<pack>/` | **否** |
+
+Workflow skill（如 `/specflow:approval`）通过路由文档指示 Agent **`Read` 文件路径**加载 guidance；禁止写成「invoke `/mysql` skill」。
+
+设计原则对齐 Anthropic Agent Skills 的 progressive disclosure（元数据 → 正文 → 按需 Read `references/`），并复用 SpecFlow 已有的 runtime assets（与 `prompts/` / `templates/` 同级安装）。
+
+## 注册表
+
+[`guidance-packs.yaml`](guidance-packs.yaml) 列出所有需随 `specflow init` / `--force-assets` 同步的 pack：
+
+```yaml
+packs:
+  - id: database
+    source: skills/database      # 相对 SpecFlow 包根
+    installAs: guidance/database # 相对 {ide}/specflow/
+    consumers: [approval]        # 文档用：哪些 workflow 会 Read
+```
+
+## 新增一个 Guidance Pack
+
+1. 在 `skills/<id>/` 放置 `SKILL.md`（及可选 `references/`、`examples/`）。
+2. 在 `guidance-packs.yaml` 增加一行。
+3. 在消费方 workflow 的 prompt/SKILL 中写明解析顺序：
+   - `{ide}/specflow/guidance/<id>/…`（业务仓标准路径）
+   - 回退：包内 `skills/<id>/…`（SpecFlow 自研仓）
+   - 仍缺失：显式 fallback + WARNING
+4. 「调用」语义：`Read …/SKILL.md`（及入口直接点名的 references），禁止链式跳转、禁止 MCP、禁止远程 `npx skills add`。
+
+## 共享 vs 包内 references
+
+| 场景 | 放哪里 |
+|------|--------|
+| 多个 workflow 共用 | Guidance pack（本机制） |
+| 仅单一 skill 使用 | 该 skill 目录下的 `references/`（Anthropic 包内资源） |
+
+## 当前 packs
+
+| id | consumers | 说明 |
+|----|-----------|------|
+| `database` | approval | §4.4 按 `dbStack` Read mysql/postgresql/oracle/redis/elasticsearch |

package/skills/database/README.md

@@ -1,15 +1,26 @@
 # 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 上游 |
+| 运行时依赖 | **无远程仓库依赖**。审批流程只读本地文件，禁止 `npx skills add`、禁止 clone/fetch 上游 |
 | 维护方式 | 在本仓库直接改 `SKILL.md` / `references/` / `examples/`，随 SpecFlow 发版 |
-| 加载方式 | `prompts/approval/database-guidance.md` 路由：命中栈 → Read 本目录；未命中 → LLM-fallback |
-| IDE 全局技能 | **不**自动安装到用户 `.claude/skills`（避免噪音）；仅 approval 按需读取 |
+| 加载方式 | `prompts/approval/database-guidance.md` 路由：命中栈 → Read；未命中 → LLM-fallback |
+| init 安装目标 | `{ide}/specflow/guidance/database/`（与 prompts/templates 同级） |
+| IDE 全局技能 | **不**安装到 `.cursor/skills` / `.claude/skills` / `.agents/skills`（避免噪音与误发现） |
+
+## 路径解析（业务仓）
+
+1. `.cursor/specflow/guidance/database/<stack>/`（或 `.claude` / `.agents`）
+2. 回退：包内 `skills/database/<stack>/`（SpecFlow 自研仓）
+3. 仍缺失：`LLM-fallback` + §8 WARNING（建议 `specflow init --force-assets`）
+
+「调用」语义：`Read …/SKILL.md`（及路由直接点名的 references），**禁止** `invoke /mysql`。
 
 ## 目录
 
@@ -24,6 +35,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

@@ -95,10 +95,11 @@ 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.
+2. `prompts/approval/database-guidance.md` — DB **guidance pack** router for packs under
+   `{ide}/specflow/guidance/database/` (installed by init; **not** an IDE skill) with
+   package fallback `skills/database/`. **Not an MCP tool**: on `dbStack` hit, `Read`
+   matched `SKILL.md` + focused references; on `none` or missing files, LLM-only §4.4.
+   Never "invoke `/mysql` skill" — always `Read` a resolved path.
 
 `generate.md` + `database-guidance.md` together specify:
 
@@ -116,7 +117,9 @@ Read these files and follow them:
   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
+- **DB guidance router** (`database-guidance.md` + guidance pack `database`): match project
+  stack → resolve `{ide}/specflow/guidance/database/<stack>/` (or package `skills/database/`)
+  → `Read`; miss → LLM-fallback. Packs are **not** installed under IDE `skills/` discovery.
   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)
 
@@ -283,9 +286,13 @@ Order and hard requirements (from `generate.md` §4.1–4.8):
 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…).
+   resolve then `Read` `{ide}/specflow/guidance/database/<stack>/SKILL.md` (init-installed
+   guidance pack) or package fallback `skills/database/<stack>/SKILL.md` (+ refs as needed).
+   If `none` or files missing, LLM-only with SpecFlow §4.4 hard bar (ER + full CREATE TABLE…).
+   Cite the actual path in §4.4 总则. **Never** install/invoke database as an IDE skill.
+   **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 +365,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

@@ -222,8 +222,9 @@ sequenceDiagram
 
 ### 4.4 数据结构 / 数据模型变更 (Data Structures)
 
-<!-- 库表硬门槛 + DB 技能路由:命中 skills/database/<stack> 则 Read 补强;
-     未命中 LLM-fallback。总则表填写「DB 技能」列。详见 prompts/approval/database-guidance.md。 -->
+<!-- 库表硬门槛 + DB guidance pack:init 安装到 {ide}/specflow/guidance/database/;
+     路由见 prompts/approval/database-guidance.md。总则表填写实际「DB 技能」路径。
+     大纲硬门槛:仅 4.4.1–4.4.4 + ##### 表名;DDL/字段说明/JSON 用 **加粗**,禁止再开标题。 -->
 
 #### 4.4.1 总则与本迭代结构变更结论
 
@@ -234,7 +235,7 @@ sequenceDiagram
 | 新增/修改/删除列 | <清单 / 无> |
 | 新增索引 | <清单 / 无> |
 | DDL 来源 | <migrations 路径 / 本迭代新增> |
-| DB 技能 | <skills/database/mysql|…(本地) / LLM-fallback> |
+| DB 技能 | <.cursor|…/guidance/database/mysql 或 LLM-fallback> |
 
 ```sql
 -- 本迭代变更语句
@@ -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 调用关系