@gordon.gan/specflow 1.8.0-alpha → 1.8.1-beta

package/prompts/document/map/test-strategy.md

@@ -1,7 +1,24 @@
-# 章节填充：test-strategy
+# 章节填充：test-strategy（测试策略 · 前端金字塔）
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
 - kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## 测试策略章节硬规则（F1 §2.2 + 前端金字塔）
+
+1. **分层测试矩阵（T1）**：逐层（单元/集成/E2E/契约）写清——测什么、用什么工具/框架、可验证目标（覆盖率或用例数）、与哪个验收标准/场景对应。禁止「写单元测试」空话。
+
+2. **测试环境与数据（T2）**：测试环境地址、测试数据准备（fixture/seed/工厂）、Mock 说明（接口 Mock/第三方 Mock）。
+
+3. **与验收标准映射（T3）**：每条验收标准（GWT）对应到至少一个测试层级，形成可追踪矩阵。
+
+4. **前端测试金字塔（T4）**：单元 60% / 组件 30% / E2E 10% 的投入比例；组件测试方式写明——Snapshot + 交互（render + fireEvent/userEvent 断言行为），关键组件/页面覆盖率目标。
+
+5. **回归测试范围（T5）**：明确回归清单覆盖受影响面（对应 impact 章节），列出受影响功能与对应回归用例。
+
+6. **工具版本具体**：框架 + 断言库 + 运行器给具体版本（如 Vitest + Testing Library），禁止「用 Jest」。
+
+> 优先级：项目约定 > SpecFlow guidance > LLM。项目禁令不得被通用规则覆盖。

package/prompts/document/map/ui-design.md

@@ -1,18 +1,21 @@
-# 章节填充：ui-design（前端/UI 设计）
+# 章节填充：ui-design（前端/UI 设计 · 扩展状态机/路由守卫/埋点/浏览器兼容）
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
 - kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
 
-## 前端章节硬规则（借鉴 approval frontend-guidance）
+## 前端章节硬规则（借鉴 approval frontend-guidance + README §1.2/§1.4）
 
 1. **总则必须写明**：Surface、Framework、Styling/设计系统、State、UI kit、FE testing、本迭代页面、项目约定（路径或「未发现」）、IDE skills/rules（路径或「未发现」）、**本迭代不选/不适用（至少 1 条）**、本迭代不涉及。
 2. **G5 页面/路由清单**：必须给出本迭代页面/路由清单 + 栈五元组。禁止只写「用 React」。
 3. **G6 空态/加载/错误**：每个关键 `Page · <短名>` 必须写清空态、加载、错误三项（文案或行为），并标明依赖的接口编号。成功态/无权限按需。
-4. **每页填空表**：目的/路由/组件树/依赖接口/字段级状态/请求时机/五态/边界。
-5. **交互状态机**：仅复杂交互页（多步表单/向导/可逆流程）用 stateDiagram-v2；简单页写「不涉及」。
-6. **IDE skills/rules 扫描**：读 `.cursor` / `.claude` / `.agents` 下与组件/状态/表单/测试/a11y/样式相关的 rules 与 skills，落地到页面设计（解析路径后 Read，禁止 invoke skill）。
-7. **性能/XSS/埋点**：仅 design 或项目约定点名时才写，否则省略。
-8. **优先级**：项目约定 + IDE 落地文档 > SpecFlow 骨架 > LLM。
+4. **每页填空表**：目的/路由/组件树/依赖接口/字段级状态/请求时机/五态/边界（README §1.2 结构模板）。
+5. **交互状态机（UI5）**：仅复杂交互页（多步表单/向导/可逆流程）用 `stateDiagram-v2`；每状态写明 UI 表现与迁移条件（含异常分支）；简单页写「不涉及」。禁止把简单页面硬画成状态机。
+6. **路由守卫/懒加载（UI6）**：有权限/登录态要求的路由必须给守卫方案（守卫逻辑/重定向/动态 import 分块）。禁止只说「加守卫」。
+7. **埋点（UI7）**：仅 design 或项目约定点名时写——页面曝光事件 + 参数、关键点击事件 + 参数。否则省略。
+8. **浏览器兼容策略（UI8）**：兼容结论必须具体到版本 + 降级手段（如「Safari 16.4 以下无 :has()，用 JS 降级」），禁止「支持最新浏览器」式空话（README §1.4 门禁）。内部系统=最新 2 版；对外 C 端=iOS Safari 14+ / Android Chrome 90+；政务金融=IE11（如必需）全量 polyfill。
+9. **IDE skills/rules 扫描**：读 `.cursor` / `.claude` / `.agents` 下与组件/状态/表单/测试/a11y/样式相关的 rules 与 skills，落地到页面设计（解析路径后 Read，禁止 invoke skill）。
+10. **优先级**：项目约定 + IDE 落地文档 > SpecFlow 骨架 > LLM。

package/prompts/document/outline/general.md

@@ -2,9 +2,18 @@
 
 你是文档大纲设计专家。基于【全局输入摘要】与【场景 Profile 约束】，生成一份结构化的文档大纲。
 
+## 前置：工程数据源扫描 + 信息缺口询问（必须先做）
+
+生成大纲前，先按 `prompts/document/shared/grounding.md` 执行：
+1. **扫描工程数据源**：只读与场景相关的数据源（OpenAPI/proto、DDL/ORM、路由/组件树、package.json、git diff 等），提取事实（接口字段/表列/依赖版本/组件名）。
+2. **汇总信息缺口并一次性询问**：提取不到的关键信息（验收标准/非目标/权衡偏好/灰度策略等）→ 形成编号清单一次性问用户；拿到答案或"按默认判断"后再生成大纲。
+3. **事实进大纲**：能确定的契约实体（接口/表/决策）进入大纲 `entities` 注册表并冻结名称；推断内容标注来源。
+
 ## 输入
 - 全局输入摘要（含各段 id 与实体候选）
 - 场景 Profile：必选章 / 候选章（含 when 条件）/ 禁止章
+- 工程数据源提取的事实摘要（接口/表/组件/依赖）
+- 用户对信息缺口的确认结果
 
 ## 输出（JSON，符合 outline schema）
 ```json

package/prompts/document/review/ai-review.md

@@ -52,5 +52,6 @@
 ## 规则
 1. critical/important 必须 fixed 或升级人工；只有 minor 可 waived（须 waiver_reason）
 2. findings 每条带 target（decision 9）：entity → 改 entities.json；narrative → 改 chapters/<id>.md；mixed → 两者
-3. part_hashes 为修复后各章 sha256（供防篡改校验）
+3. part_hashes 为**审查时刻**各章 sha256（由引擎在审查后计算，作为防篡改基线；引擎自身修复记入 `post_review_repairs`，不算篡改）
 4. verdict：全 fixed → pass；仅 minor waived → pass_with_waivers；任一 critical/important open → fail
+5. **闭环核对（重要）**：对 packet 中「上一轮 findings」逐条核实——若对应章节已含 `<!-- review-fix -->` 注记且问题已解决，标 `status=fixed`，**不要重复报告同一问题**；仅报告仍未解决或修复不完整的项

package/prompts/document/shared/grounding.md

@@ -0,0 +1,84 @@
+# 工程数据源提取 + 信息缺口询问（grounding 通用指引）
+
+> 本文件是**所有章节生成前**的强制前置步骤，也是"数据源提取 → 缺口询问"的质量链核心。
+> 原则：**事实从工程数据源提取，意图向用户询问，推理由你完成**。禁止用 LLM 编造工程事实。
+
+## 一、为什么必须做（质量链）
+
+```
+工程数据源（事实）→ 信息缺口询问（意图）→ 大纲（结构）→ 逐章填充（推理）→ lint/review（校验）
+```
+
+- lint/review 只能保证**格式正确**；只有"数据源提取 + 缺口询问"才能保证**内容正确**。
+- 接口字段少一个、表结构差一列、路由写错——方案文档就失去"可直接交给后端/测试执行"的价值。
+
+## 二、双层提取：引擎确定性提取 + Agent 按需补取
+
+**第一层（引擎确定性，无需 Agent 操作）**：`specflow techdoc run` 会自动扫描工程中的
+OpenAPI（`openapi.yaml`/`swagger.json` 等）、proto3（`*.proto`）、SQL DDL（`schema.sql`/`migration` 等），
+**确定性**解析出契约实体（接口 method/path/字段/错误码、表名/字段/DDL 原文），并作为
+「工程契约候选」注入大纲生成——LLM 只能原样引用这些 frozen 名，禁止改名/编造。
+
+**第二层（Agent 按需补取）**：引擎未覆盖的数据源，由你在生成前主动扫描补取（见下表），
+并按「事实 vs 推理」分级使用。
+
+## 三、工程数据源清单（第二层 · 按场景按需取用，禁止一次性全读）
+
+| 数据源 | 提取什么 | 优先场景/章节 |
+|---|---|---|
+| OpenAPI / Swagger / proto / 现有路由文件 | 接口签名、DTO 字段、错误码、http_path | api-design / compat-migration |
+| DDL / ORM schema / migration 文件 | 表结构、字段、索引、外键 | data-model / migration |
+| 组件树 / 路由表 / 状态管理 store / 样式文件 | 页面清单、组件结构、状态流 | ui-design / component-design / state-management |
+| package.json / 依赖清单 / 构建配置 | 技术栈、依赖版本、框架 | tech-selection / migration / 0to1 |
+| 现有 docs / README / conventions | 团队约定、既有术语、命名规范 | 所有章节（约定优先） |
+| 配置文件（环境/部署/CI） | 环境拆分、部署拓扑、密钥策略 | deploy / ops |
+| 测试文件 / 覆盖率报告 | 已有测试面、回归范围 | test-strategy / regression |
+| git diff / 变更文件列表 | **本次改动的真实影响面** | impact / root-cause / bugfix |
+
+> **按需加载**：只读当前章节涉及的数据源，禁止一次性读全部（token 暴涨 + 注意力稀释）。
+
+## 三、事实 vs 推理 分级（必须遵守）
+
+| 类型 | 定义 | 处理方式 |
+|---|---|---|
+| **事实（fact）** | 工程里已有的：接口字段、表列、路由、依赖版本、组件名 | **必须从工程数据源提取**，禁止 LLM 编造 |
+| **意图（intent）** | 用户/业务的目标、验收标准、非目标、权衡偏好、灰度策略 | **向用户询问**，禁止猜测 |
+| **推理（reasoning）** | 方案权衡、架构分析、迁移步骤、测试设计 | **由你基于事实+意图推导**，可自由发挥但须可溯源 |
+
+## 四、信息缺口清单（一次性询问，禁止逐章打断）
+
+**流程**：
+1. 扫描工程数据源 + 读用户输入，提取能确定的事实。
+2. 汇总**仍然缺失的关键信息** → 形成"信息缺口清单"。
+3. **一次性**向用户询问（列成编号清单），拿到答案后再生成；不要每章都问。
+
+**常见缺口（按场景）**：
+
+| 场景 | 典型必须询问的缺口 |
+|---|---|
+| 0to1 / feature | 验收标准、MVP 边界、非目标、技术栈约束、部署目标环境 |
+| bugfix | 复现环境/频率、影响用户范围、修复优先级、是否有回归基线 |
+| poc | 决策判据、候选范围、时间盒、成功标准 |
+| migration | 升级目标版本、灰度策略、回滚要求、兼容期限 |
+| approve | 审批人/签字要求、风险容忍度 |
+
+**询问格式**：
+```text
+已从工程中提取：<已确定的事实摘要，一两行>
+以下关键信息缺失，请确认（可逐条回答或直接说"按你的默认判断"）：
+1. <缺口 1>
+2. <缺口 2>
+```
+
+## 五、与现有机制的衔接
+
+- **反偷懒 lint 不替代缺口询问**：lint 只禁 TODO/含糊词；被 lint 拦住后"硬编一个"是错误路径——应先问用户。
+- **detect 场景确认复用同一模式**：场景不确定时已经会向用户确认；本节把确认范围扩展到**章节级信息缺口**。
+- **产物标记**：若用户明确表示"按默认判断"，在对应章节标注「此处为用户默认判断，非工程确认」，保证可审计。
+
+## 六、前端场景补充（资深前端视角）
+
+- 接口契约：**字段名、类型、错误码必须与后端/OpenAPI 对齐**，禁止"前后端各写一套"。
+- 组件/页面：组件名、路由路径、状态 store 名应来自工程；页面清单可与用户核对。
+- 性能：基准数值必须来自实测（或标注"待实测"），禁止编造 LCP/包体数字。
+- 依赖升级：当前版本/目标版本来自 package.json；升级理由与收益向用户确认。

package/skills/specflow-techdoc/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: specflow-techdoc
+description: "One-command scenario-based technical document generation (0→1 / bugfix / feature / poc) using the IDE's model — run → Agent auto-generates → validate"
+---
+
+# SpecFlow: Document
+
+> **一键生成技术文档**：输入 `/specflow:techdoc run <profile> --text "..."`，你用当前 IDE 模型自动完成全部生成，用户拿到 `document.md`。
+> 引擎不调用第三方 LLM API——由你（Agent，运行在 IDE 模型上）完成需要 LLM 的步骤，`specflow techdoc` 只做确定性校验与渲染。
+
+## Invocation（一键入口）
+
+```text
+/specflow:techdoc run [<0to1|bugfix|feature|poc>] [--text "..."] [--design <file>] [--specs <file>] [--work-root <path>]
+```
+
+Cursor: `specflow:techdoc run <profile>`; Codex: `$specflow-techdoc run <profile>`.
+
+**收到 `run` 命令后，你必须自动完成全流程，不得中途停下来要求用户分步确认**（除非产物校验失败需要修正）。
+
+## 双模式
+
+document 同时支持两种用法：
+
+1. **通用模式（现状）**：`run <0to1|bugfix|feature|poc>` 从自然语言/素材生成方案文档。
+2. **审批模式（approval 能力）**：`document approve` 从**四件套**（proposal / specs / design / tasks）生成审批文档——含闭环性检查（7 Pass）、可实施性评估（7 维）、质量红线（G1-G6）、可选签字栏（`--signoff`）。多仓：`--workspace-root <root>` 扫描各仓四件套，每仓生成后主仓合订。
+
+```text
+# 审批模式（单仓）
+specflow techdoc approve --change <name> --signoff
+# 审批模式（多仓：各仓四件套 → 各自生成 → 主仓合订）
+specflow techdoc approve --workspace-root <root> --changes "platform:ch1,web:ch2"
+```
+
+## 场景自动识别（省略 profile 时）
+
+当用户 **未指定** `<profile>` 时：
+
+1. 先用你的模型理解自然语言，判断场景（确定性关键词见 `specflow techdoc detect`）：
+   - **0to1**：从零做一个产品/项目（"想做/做一个/新产品"）；纯前端（无后端信号）自动走 `frontend-0to1`
+   - **frontend-0to1**：纯前端从零（"纯前端/静态站点/官网/无后端"）
+   - **bugfix**：排查修复问题（"报错/500/崩溃/挂了/异常"，含前端/多端维度）
+   - **feature**：给已有系统加功能（"新增/加个/扩展"，含全栈/接口/前端维度）
+   - **poc**：技术预研/选型（"预研/PoC/方案对比/技术调研"）
+   - **migration**：技术升级（"迁移/大版本/框架升级/构建工具升级/Vue2→Vue3"）
+2. 若判断明确 → 直接使用该场景。
+3. 若**不确定**或信号冲突 → **向用户确认**（列出上述场景选项及含义），等待用户选择后再继续。
+4. 可选：`specflow techdoc detect --text "..."` 查看确定性关键词识别的结果作为参考。
+
+> 确定性规则（`detect`）是初判参考；你的模型理解更准。以模型判断 + 用户确认为准。
+> 识别优先级参考 README §0.3：F1 0to1 > F4 migration > F5 poc > F2 feature > F3 bugfix。
+> **场景轴 × 技术栈轴正交**：场景管「做什么」，涉及哪几层（前端/后端/API/数据）由输入特征自动判定，章节按需伸缩——不需要用户选「全栈版」。
+
+## 一键执行流程（Agent 自动完成）
+
+```text
+run [<profile>]
+  ├─ ① 规划    specflow techdoc plan <profile> ...   → 得到步骤清单 + workRoot
+  ├─ ② 生成    你（Agent）用当前模型按步骤逐项执行：
+  │     ├─ 0. 工程数据源扫描 + 信息缺口询问（见下 §②.0，先做！）
+  │     ├─ input-summary（多输入时）→ digests/input-summary.md
+  │     ├─ outline → outline.yaml（参考 prompts/document/outline/general.md）
+  │     ├─ 逐章填空 → chapters/<id>.md + entities.json（参考 prompts/document/map/<id>.md）
+  │     └─ review（可选）→ review-result.json（参考 prompts/document/review/ai-review.md）
+  └─ ③ 校验    specflow techdoc validate --work-root <path>
+                 └─ 通过 → 输出 document.md；失败 → 修正产物后重跑 validate
+```
+
+## ① 规划（plan）
+
+```text
+specflow techdoc plan <profile> [--text "..."] [--design <file>] [--specs <file>] [--work-root <path>]
+```
+
+引擎输出每个 Agent 步骤（id / 做什么 / 参考提示词 / 输入 / 输出 / 必做）。你按此清单执行即可。
+
+## ② 生成（你，用 IDE 模型执行）
+
+0. **工程数据源提取 + 信息缺口询问（必须先做，质量链根基）**：按 `prompts/document/shared/grounding.md` 执行——
+   - **引擎已自动提取（无需你操作）**：`run` 会确定性扫描 OpenAPI（`openapi.yaml`/`swagger.json`）、proto3（`*.proto`）、SQL DDL（`schema.sql`/`migration`），解析出契约实体（接口 method/path/字段/错误码、表名/DDL）并注入大纲——LLM 只能原样引用 frozen 名，禁止编造。引擎未覆盖的数据源由你按需补取（组件树/路由/store/package.json/git diff 等）。
+   - **事实 vs 推理分级**：接口字段/表列/组件名/依赖版本 = **事实，必须来自工程**；目标/验收/权衡偏好 = **意图，向用户询问**；方案分析/迁移步骤 = **推理，基于事实+意图推导**。禁止编造工程事实。
+   - **信息缺口清单一次性询问**：扫描后汇总仍缺失的关键信息（验收标准/非目标/灰度策略/修复优先级等），列成编号清单**一次性**问用户；用户答"按默认判断"时在章节标注「此处为用户默认判断，非工程确认」。不要逐章打断。
+   - **优先级：引擎提取的工程事实 > 项目约定 > 用户确认 > SpecFlow guidance > LLM 推理**。
+1. **读取项目规约（与 0 并行）**：扫描 `specflow/config.yaml` 的 `conventions.<topic>`、中立文档 `docs/db/conventions.md`、`docs/api/guidelines.md`、IDE 规则、guidance packs（`skills/guidance-packs.yaml`）。未发现时显式标注「未发现项目规约」。将数据库 DDL 约定、API 规范、前端规约、架构禁令落实到后续章节。
+2. **input-summary**（多输入或长输入时）：读全部输入，产出紧凑摘要 → `digests/input-summary.md`。
+3. **outline**：按场景 Profile 生成 `outline.yaml`——章节序 + 每章要点（kind / references / source_segments）+ 实体注册表 + 决策。**能确定的契约实体（接口/表/决策）在 Pass 1 就冻结进注册表**。参考 `.claude/specflow/prompts/document/outline/general.md`。
+4. **逐章填空**：每章一个步骤 → `chapters/<id>.md`（叙述）+ 契约实体进 `entities.json`。**本章涉及的工程事实按 grounding 提取，缺口已在 §②.0 一次性确认过，不再逐章问**。参考 `.claude/specflow/prompts/document/map/goal.md` 等（如 `map/api-design.md`、`map/root-cause.md`）。
+5. **review**（可选）：独立审查全部章节 → `review-result.json`（findings + part_hashes）。参考 `.claude/specflow/prompts/document/review/ai-review.md`。
+
+## ③ 校验（validate，引擎确定性执行）
+
+```text
+specflow techdoc validate --work-root <path>
+```
+
+引擎校验：
+- outline 必选章 / references / kind 一致性
+- 每章叙述过反偷懒 lint（禁 TODO/待补充/同上/含糊词）
+- 契约实体 zod + 结构化覆盖（引用的实体必须被填充）
+- 通过后渲染 `document.md`（+ `document.html`）
+
+**若 validate 失败**：读取 diagnostics，修正对应产物，重跑 validate，直到通过。
+
+## 内置场景 Profile
+
+**业务场景（6 个，管「做什么」）**——章节按输入特征伸缩（hasBackend / uiInScope / containsApiChange / hasPersistence / hasLogic）：
+
+| Profile | 必选章 | 特征驱动的候选章 |
+|---------|--------|--------|
+| `0to1`（从零全栈） | goal / mvp-boundary / non-goals / tech-selection / architecture / frontend-architecture / api-design / core-flow / component-design / state-management / ui-design / performance / test-strategy / deploy / ops | research / data-model（hasPersistence）/ core-logic（hasLogic）/ signoff |
+| `frontend-0to1`（纯前端从零） | 全栈 0to1 去掉 architecture / data-model | research / signoff |
+| `bugfix`（修 bug） | reproduce / root-cause / fix | impact / ui-design（uiInScope）/ regression / compat-migration（containsApiChange）/ signoff |
+| `feature`（加功能） | requirement / test-strategy | impact / tech-selection（hasBackend\|containsApiChange）/ architecture（hasBackend）/ api-design（containsApiChange）/ core-flow（hasBackend\|uiInScope）/ component-design / state-management / ui-design（uiInScope）/ data-model（hasPersistence）/ core-logic（hasLogic）/ performance（uiInScope\|hasBackend）/ compat-migration（containsApiChange）/ signoff |
+| `poc`（预研选型） | research / poc-demo / benchmark / tech-selection | goal / impact / signoff |
+| `migration`（技术升级） | goal / impact / compat-migration / migration-guide / test-strategy / deploy | performance / api-design（containsApiChange）/ data-model（hasPersistence）/ architecture（hasBackend）/ ui-design（uiInScope）/ ops / signoff |
+
+**审批模式（非业务场景）**——`approve` 回答「用什么形态呈现」（四件套 → 审批评审文档），与业务场景正交，由 `techdoc approve` 入口调用：
+
+| 模式 | 必选章 | 候选章 |
+|------|--------|--------|
+| `approve`（审批） | goal / tech-selection / architecture / api-design / data-model / test-strategy / closed-loop / implementability | ui-design / core-logic / config-runtime / compat-migration / acceptance / deploy / signoff |
+
+> 全栈场景方法论见 `docs/scenario-templates/README.md`（F1–F5）。`poc`（F5）证据链 `research → poc-demo → benchmark → tech-selection`；`migration`（F4）核心 `compat-migration → migration-guide`；`bugfix`（F3）零新增章节，纯复用现有组件。原 `fullstack-feature`/`fullstack-bugfix` 已并入 `feature`/`bugfix`（由特征伸缩），原 `fullstack-poc`/`fullstack-migration` 更名 `poc`/`migration`。
+
+## 质量红线（生成时必须满足）
+
+- 契约实体：接口须含 ≥1 失败示例（G2）；表须含完整 DDL。
+- 覆盖：每个大纲要点必须有填充落点。
+- 反偷懒：禁止 TODO/待补充/同上/含糊词。
+- 一致性：跨章实体名/路径与 outline.yaml 冻结名一致，不靠记忆。
+- **事实可溯源（grounding）**：接口字段/表列/组件名/依赖版本等工程事实必须来自工程数据源或用户确认，禁止 LLM 编造；用户默认判断的项标注「此处为用户默认判断」。
+
+## 说明
+
+- `run` 是一键入口（Agent 自动执行）。`plan` / `validate` 是分步/高级用法。
+- 本命令不改 phase，不阻塞 apply。
+
+## 实现能力标记（parity 校验用）
+
+- **两遍扫描（two-pass outline）**：Pass 1 生成 outline（大纲），Pass 2 逐章填空。
+- **按要点填空（fill-in by points）**：每章对着要点清单填空。
+- **契约注入（contract injection）**：上游契约实体按 references 确定性注入。
+- **覆盖校验（coverage check）**：结构化通道 + 语义通道校验覆盖。

package/skills/specflow-techdoc-synth/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: specflow-techdoc-synth
+description: "One-command multi-repo technical solution document synthesis — merge multiple repos' four-artifact sets (proposal/specs/design/tasks) into ONE cross-repo document (techdoc + synthesize): unified outline, namespaced contract entities, per-repo sections, global overview/conclusion"
+---
+
+# SpecFlow: Document Synth（多仓合成文档）
+
+> **一键多仓合成**：输入 `/specflow:techdoc-synth run --workspace-root <root>`，你把多仓四件套合成**一份完整文档**（不是拼接）。引擎只做确定性校验（`synthesize` 质量门禁），需要 LLM 的步骤由你（Agent）用当前 IDE 模型完成。
+
+## Invocation（一键入口）
+
+```text
+/specflow:techdoc-synth run [--workspace-root <root>] [--changes "repo1:ch1,repo2:ch2"] [--text "..."] [--profile <id>] [--work-root <path>] [--signoff]
+```
+
+Cursor: `specflow:techdoc-synth run ...`; Codex: `$specflow-techdoc-synth run ...`。
+
+**收到 `run` 命令后，你必须自动完成全流程，不得中途停下要求分步确认**（除非产物校验失败需要修正）。
+
+## 场景自动识别（省略 --profile 时）
+
+与 `techdoc` 相同，`techdoc-synth` 支持场景识别：
+
+1. **显式指定** `--profile <id>` → 直接使用该 profile（如 `approve` / `0to1` / `frontend-0to1` / `bugfix` / `feature` / `poc` / `migration`）。
+2. **省略 `--profile`** 时自动识别（确定性关键词见 `specflow techdoc detect`）：
+   - 提供 `--text "..."` → 以该自然语言描述为准识别场景（跨仓任务描述）；
+   - 未提供 `--text` → 从各仓四件套内容拼接识别。
+3. **识别明确**（置信度 ≥ 0.5）→ 直接采用识别出的 profile。
+4. **识别不确定**：
+   - 有 `--text` → **向用户确认**（列出候选场景），等待选择后带 `--profile` 重跑；
+   - 无 `--text` → **回退 `approve`**（原合成默认，不打断流程，保持向后兼容）。
+5. 可选：`specflow techdoc detect --text "..."` 查看确定性关键词识别的结果作为参考。
+
+> 场景识别决定合成文档的**章节结构**（如 bugfix → reproduce/root-cause/fix；feature → requirement/test-strategy；poc → research/poc-demo/benchmark/tech-selection；migration → compat-migration/migration-guide）。跨仓合成规则（统一大纲/命名空间/分仓小节/全局视角/跨仓依赖）对任何 profile 都适用。
+
+## 与 `techdoc approve --bundle` 的区别（为什么用 synth）
+
+| 维度 | `approve --bundle`（拼接） | `techdoc-synth`（合成） |
+|---|---|---|
+| 大纲 | 每仓独立 | **一次统一大纲**，章节覆盖所有仓 |
+| 契约实体 | 每仓独立 I1/T1，跨仓冲突 | **命名空间隔离**（`<repo>_<id>`） |
+| 章节内容 | 各仓各写各的 | **每章按仓分节**（`### <repo>`），细节不互相稀释 |
+| 全局视角 | 无 | goal 写多仓总目标；closed-loop/implementability 跨仓统一结论 |
+| 跨仓依赖 | 不识别 | 显式标注「跨仓依赖」（接口调用/数据共享/发布顺序） |
+| 质量门禁 | 无 | **分仓小节门禁**（validate 强制：每必选章含所有仓的 `### <repo>` 小节） |
+
+> 原有多仓多产物（`techdoc approve --workspace-root ... --bundle` 各仓独立文档 + 主仓合订）**保持不变**；`techdoc-synth` 是新增的"真正合成"路径，两者并存。
+
+## 使用前提
+
+- **≥2 个仓**（单仓请用 `/specflow:techdoc`）。
+- 每个仓在 `<workspaceRoot>/<repo>/specflow/changes/<change>/` 下有四件套（proposal / spec / design / tasks，缺件可自动跳过）。
+- 跨仓协作场景（一个业务的前后端仓 / 一个平台的多服务仓 / 同构协作仓）。
+
+## 一键执行流程（Agent 自动完成）
+
+```text
+run [--workspace-root <root>]
+  ├─ ① 发现   扫描各仓四件套（--changes 精确指定或自动扫描）
+  ├─ ② 输入   每仓四件套加「来源仓」标记 → 统一输入集（+ 可选 --text 描述）
+  ├─ ②.5 场景 省略 --profile 时自动识别（--text 优先，其次四件套内容）；不确定且有 --text → 向用户确认；无 --text → 回退 approve
+  ├─ ③ 规划   specflow techdoc synthesize --workspace-root <root> [--json]
+  ├─ ④ 生成   你（Agent）用当前模型按跨仓合成规则逐项执行：
+  │     ├─ 0. 按仓工程数据源扫描 + 跨仓缺口询问（见下「跨仓 grounding」）
+  │     ├─ outline（统一大纲，章节覆盖所有仓）
+  │     ├─ 逐章填空（每章按仓分节 `### <repo>` + 契约实体 `<repo>_<id>` 命名空间）
+  │     └─ review（可选）
+  └─ ⑤ 校验   specflow techdoc validate --work-root <path>
+                 └─ 通过 → 输出 document.md；失败 → 修正产物后重跑
+```
+
+## 跨仓 grounding（生成前必须先做，与单仓同源）
+
+按 `prompts/document/shared/grounding.md` 执行，但**按仓组织**：
+- **按仓扫描工程数据源**：写某仓小节前只扫描**该仓**的数据源（OpenAPI/proto、DDL、路由/组件、package.json、git diff），禁止一次性读全部仓（token 暴涨 + 注意力稀释）。
+- **事实 vs 推理分级**：接口字段/表列/组件名/依赖版本 = 事实，来自对应仓工程；目标/验收/跨仓权衡偏好 = 意图，向用户询问；跨仓分析 = 推理。
+- **跨仓缺口一次性询问**：汇总各仓仍缺失的关键信息（跨仓接口契约、数据共享范围、发布顺序、验收标准）→ 编号清单一次性问用户；答"按默认判断"时在对应仓小节标注「此处为用户默认判断」。
+- 跨仓接口契约字段**必须与各仓真实接口定义对齐**（`<repo>_I1` 命名空间下的事实），禁止合成时编造。
+
+## 跨仓合成规则（必须遵守，validate 强制）
+
+1. **统一大纲**：一次生成一份 outline，章节覆盖所有仓，**不按仓分章**（跨仓对比/汇总放进对应章节）。
+2. **契约实体命名空间**：跨仓实体 id 用 `<repo>_<id>` 前缀（如 `repo1_I1`、`repo2_T1`），**禁止不同仓共用裸 id**。
+3. **每章必须分仓小节（质量门禁）**：每个必选章节的叙述按仓分节，用 `### <repo>` 小节标题（可带后缀如 `### repo1 · 目标`），且**每个仓都必须出现**。禁止把多仓内容混写成一段（会导致细节互相稀释）。
+4. **全局视角**（若所选 profile 包含对应章节）：goal 写多仓总目标与边界；tech-selection 对比各仓技术方案；api-design/data-model 分仓列契约；closed-loop 跨仓统一闭环检查；implementability 跨仓统一可实施性评估。其他场景章节（如 reproduce/root-cause/fix、requirement/test-strategy、research/poc-demo/benchmark）同样按仓分节并给出跨仓结论。
+5. **跨仓依赖/风险**：涉及仓间依赖（接口调用/数据共享/发布顺序）时显式标注「跨仓依赖」。
+
+> 门禁是确定性的：`synthesize` 在 workRoot 写入 `repos.json`，`document validate` 读取后对每个必选章节检查 `### <repo>` 小节，缺失 → error（`repo_section_missing`）。非 synthesize 工作目录（`document run` / `approve --bundle`）不写 repos.json，门禁不触发。
+
+## 产物
+
+- `<workspaceRoot>/.specflow/document-synthesized/document.md`（可用 `--work-root` 指定输出目录）
+- `repos.json`：参与合成的仓清单（门禁依据，自动写入）
+
+## 说明
+
+- 本命令不改 phase，不阻塞 apply。
+- 质量目标：**合成 ≠ 拼接**。若某仓内容异构过大、合成会导致过度概括，可退回到 `techdoc approve --workspace-root ... --bundle`（各仓独立真源 + 只读合订）。
+- 提示词模板（Agent 逐章填充时参考）：`.claude/specflow/prompts/document/outline/general.md`（大纲）、`.claude/specflow/prompts/document/map/api-design.md` 等（逐章，按章节 id 取对应 map 提示词）、`.claude/specflow/prompts/document/review/ai-review.md`（审查）、`.claude/specflow/prompts/document/shared/grounding.md`（跨仓工程数据源扫描 + 缺口询问）。

package/templates/document/chapters/api-design.yaml

@@ -1,4 +1,4 @@
-# 接口设计（候选；依赖架构）
+# 接口设计（候选；依赖架构；0→1 全栈/功能场景合并「契约+前端对接」）
 id: api-design
 title: 接口设计
 when: input.containsApiChange
@@ -8,6 +8,9 @@ outline_points:
   - { id: O2, text: 逐接口字段表 + 成功示例, required: true, kind: mixed }
   - { id: O3, text: 每个接口 ≥1 失败示例（G2）, required: true, kind: entity }
   - { id: O4, text: 错误码映射, required: true, kind: entity }
+  - { id: O5, text: 前端请求封装（拦截器/重试/缓存/DTO→VO）, required: false, kind: narrative }
+  - { id: O6, text: 前端错误处理（错误码统一/Loading-Empty-Error 状态）, required: false, kind: narrative }
+  - { id: O7, text: 接口 Mock 与联调（Mock 策略/契约先行，前端可并行开发）, required: false, kind: narrative }
 entities:
   interfaces:
     required: [id, name, method, path, errors]
@@ -20,5 +23,7 @@ gates:
   - 禁止「暂定/如/实现时」接口名
   - 每个接口必须 ≥1 失败示例
   - 接口编号稳定可交叉引用
+  - 涉及前端对接时，请求封装与错误码统一方案必须与契约对齐（R5，字段名/错误码禁各写各的）
+  - 前端接口 Mock 必须与契约一致（禁 Mock 一套、真实接口另一套）
 map_prompt: prompts/document/map/api-design.md
 output_budget_tokens: 8000

package/templates/document/chapters/architecture.yaml

@@ -1,12 +1,14 @@
-# 架构设计（0→1 候选；依赖技术选型）
+# 架构设计（0→1 候选；依赖技术选型；扩展：C4 分层 + ADR 决策记录）
 id: architecture
 title: 架构设计
-when: input.hasLogic
+when: input.hasLogic && input.hasBackend
 depends_on: [tech-selection]
 outline_points:
-  - { id: AR1, text: 总体架构（模块关系）, required: true, kind: mixed }
+  - { id: AR1, text: 总体架构（模块关系，C4 Context/Container 分层）, required: true, kind: mixed }
   - { id: AR2, text: 核心组件与职责边界, required: true, kind: narrative }
   - { id: AR3, text: 架构一致性自检, required: false, kind: narrative }
+  - { id: AR4, text: C4 分层（Context 系统上下文 / Container 容器 / Component 组件），标注层级与依赖方向, required: false, kind: narrative }
+  - { id: AR5, text: 关键架构决策记录（ADR：背景/决策/后果/备选，沉淀 tech-selection 的 decisions）, required: false, kind: narrative }
 entities: {}
 narratives:
   architecture_notes: required
@@ -14,5 +16,6 @@ gates:
   - 架构图必须附「设计要点」说明（禁止只复述节点名）
   - 每个组件须有「不做什么」边界
   - 超 5 行流程必须 Mermaid（G1）
+  - C4 分层给到 Component 层时，与 core-flow 的组件层交互时序对接（R5）
 map_prompt: prompts/document/map/architecture.md
-output_budget_tokens: 4000
+output_budget_tokens: 4500

package/templates/document/chapters/benchmark.yaml

@@ -0,0 +1,20 @@
+# Benchmark 数据（benchmark · fullstack-poc 预研/选型场景）
+# 高质量 Benchmark 要点：同条件同设备 + 原始测量值 + 前后端双维度 + DX 对比 + 可复现
+id: benchmark
+title: Benchmark 数据
+when: null
+depends_on: [research]
+outline_points:
+  - { id: BM1, text: 基准场景与条件（硬件/版本/数据集；同条件同设备）, required: true, kind: narrative }
+  - { id: BM2, text: 性能对比（原始测量值：前端渲染/加载/bundle；后端吞吐/延迟/内存）, required: true, kind: mixed }
+  - { id: BM3, text: DX 对比（HMR/调试工具/类型体验/文档）, required: true, kind: narrative }
+  - { id: BM4, text: 对比结论与数据可信度（可复现/样本数/单次）, required: true, kind: narrative }
+entities: {}
+narratives:
+  benchmark_notes: required
+gates:
+  - 必须同条件同设备对比（禁不同环境硬比）
+  - 必须给原始测量值（禁只写「提升 50%」无原始数据）
+  - 结论必须注明数据可信度（可复现/单次/样本数）
+map_prompt: prompts/document/map/benchmark.md
+output_budget_tokens: 5000

package/templates/document/chapters/compat-migration.yaml

@@ -1,17 +1,21 @@
-# 兼容性与迁移
+# 兼容性与迁移（扩展：新旧 API 对照 / 浏览器兼容 / 渐进式迁移，F4 用）
 id: compat-migration
 title: 兼容性与迁移
-when: null
+when: input.containsApiChange
 depends_on: [api-design, data-model]
 outline_points:
   - { id: CM1, text: 接口/数据兼容结论, required: true, kind: narrative }
   - { id: CM2, text: 存量填充策略（G3）, required: true, kind: narrative }
   - { id: CM3, text: 回滚数据兼容（G4）, required: true, kind: narrative }
+  - { id: CM4, text: 新旧 API 变化对照表（旧 → 新，含 Breaking Change 标注）, required: false, kind: narrative }
+  - { id: CM5, text: 浏览器/依赖兼容（目标版本 + 降级手段，README §1.4）, required: false, kind: narrative }
+  - { id: CM6, text: 渐进式迁移方案（分阶段/新旧代码共存/双构建双运行）, required: false, kind: narrative }
 entities: {}
 narratives:
   compat_migration: required
 gates:
   - 回滚后旧版本能否安全跳过/忽略新数据（G4）必须写明
   - 零变更时显式「无新旧互读问题」
+  - 有 Breaking Change 时，新旧 API 对照必须逐项（禁只写「不兼容」）
 map_prompt: prompts/document/map/compat-migration.md
-output_budget_tokens: 2500
+output_budget_tokens: 3500

package/templates/document/chapters/component-design.yaml

@@ -0,0 +1,22 @@
+# 组件设计（component-design · 0→1 全栈/全栈功能场景）
+# 高质量组件设计要点：组件树 + 通信方式 + 四态(default/loading/empty/error) + 容器/展示分离 + 复用拆分
+id: component-design
+title: 组件设计
+when: input.uiInScope
+depends_on: [frontend-architecture]
+outline_points:
+  - { id: CD1, text: 组件树（页面→区块→基础组件，标注父子与 Props 流向，禁臆造）, required: true, kind: mixed }
+  - { id: CD2, text: 组件通信方式（Props 向下 / Events 向上 / Context / Store，逐一说明取舍）, required: true, kind: narrative }
+  - { id: CD3, text: 每个组件的四态（default/loading/empty/error）与 UI 表现, required: true, kind: narrative }
+  - { id: CD4, text: 容器/展示组件分离（数据获取与状态在容器层，渲染在展示层）, required: true, kind: narrative }
+  - { id: CD5, text: 组件复用与拆分原则（单一职责/组合优先，至少 1 条「不拆分」边界）, required: false, kind: narrative }
+entities: {}
+narratives:
+  component_design: required
+gates:
+  - 组件树必须标注 Props/Events 流向（禁只列组件名）
+  - 每个关键组件必须覆盖 default/loading/empty/error 四态（禁只写成功态）
+  - 必须写明容器/展示分离结论
+  - 至少 1 条「本迭代不拆/不复用」边界（禁过度设计）
+map_prompt: prompts/document/map/component-design.md
+output_budget_tokens: 4000

package/templates/document/chapters/core-flow.yaml

@@ -0,0 +1,27 @@
+# 主业务流程时序（core-flow · 0→1 全栈/全栈功能场景）
+# 高质量时序图要点：主链路 + 图文并茂 + 异常/幂等并发/异步/第三方 + 易错决策点 + 交叉引用
+id: core-flow
+title: 主业务流程时序
+when: input.hasBackend || input.uiInScope
+depends_on: [architecture, api-design]
+outline_points:
+  - { id: CF1, text: 主业务链路时序图（用户→前端→后端→DB→第三方→异步 lifeline，Mermaid sequenceDiagram）, required: true, kind: narrative }
+  - { id: CF2, text: 时序图必须有文字说明（逐消息/逐分支解释职责与理由，禁只有图无文字）, required: true, kind: narrative }
+  - { id: CF3, text: 异常/失败分支（alt/opt：错误码→降级→重试→回滚）, required: true, kind: narrative }
+  - { id: CF4, text: 幂等与并发控制（重复请求/重复提交/并发写/乐观锁）, required: true, kind: narrative }
+  - { id: CF5, text: 异步/消息/队列交互（回调/补偿/死信/超时）, required: false, kind: narrative }
+  - { id: CF6, text: 第三方系统交互（webhook/回调/超时降级/隔离）, required: false, kind: narrative }
+  - { id: CF7, text: 每个时序图的「易错决策点」标注（seqdiagram 精神：第一次容易做错的决定）, required: true, kind: narrative }
+  - { id: CF8, text: 时序图与接口契约/数据模型的交叉引用（用冻结契约 id，R5）, required: false, kind: narrative }
+entities: {}
+narratives:
+  core_flow: required
+gates:
+  - 主链路时序图必须 Mermaid 源码（```mermaid sequenceDiagram）+ 可渲染（diagram as code）
+  - 时序图必须有文字说明（逐消息/逐分支），禁止只有图无文字
+  - 每条主链路必须画异常/失败分支（禁只画 happy path）
+  - 有写操作的链路必须给幂等/并发结论（禁「前端按钮防抖」当幂等方案）
+  - 有异步/第三方的链路必须标超时/降级/补偿
+  - 至少标注 1 处「易错决策点」
+map_prompt: prompts/document/map/core-flow.md
+output_budget_tokens: 4000

package/templates/document/chapters/core-logic.yaml

@@ -1,7 +1,7 @@
 # 核心算法 / 逻辑说明
 id: core-logic
 title: 核心算法/逻辑
-when: null
+when: input.hasLogic
 depends_on: [architecture]
 outline_points:
   - { id: LOG1, text: 核心算法/流程说明, required: true, kind: narrative }

package/templates/document/chapters/deploy.yaml

@@ -1,18 +1,22 @@
-# 部署/发布/回滚方案（可选）
+# 部署交付方案（deploy · 0→1 扩展为「部署交付」：环境/CI-CD/拓扑/发布/回滚/配置管理 12-Factor）
 id: deploy
-title: 部署/发布/回滚
+title: 部署交付方案
 when: null
 depends_on: [test-strategy]
 outline_points:
-  - { id: DP1, text: 部署方案（目标/方式/顺序/配置）, required: true, kind: narrative }
-  - { id: DP2, text: 发布策略（蓝绿/金丝雀/滚动）, required: true, kind: narrative }
-  - { id: DP3, text: 回滚方案（触发条件/方式/数据一致/验证）, required: true, kind: narrative }
-  - { id: DP4, text: 监控与可观测性（指标/日志/告警）, required: true, kind: narrative }
+  - { id: DP1, text: 环境拆分（dev/staging/prod 及用途/访问控制）, required: true, kind: narrative }
+  - { id: DP2, text: CI/CD 流水线（代码检查→测试→构建→部署）+ 制品/不可变版本, required: true, kind: narrative }
+  - { id: DP3, text: 部署拓扑与方式（容器/K8s/Serverless/虚拟机 + 前端静态托管/CDN/SPA 回退）, required: true, kind: narrative }
+  - { id: DP4, text: 发布策略（蓝绿/金丝雀/滚动）, required: true, kind: narrative }
+  - { id: DP5, text: 回滚（触发条件/方式/数据一致/验证）, required: true, kind: narrative }
+  - { id: DP6, text: 配置管理（环境变量/密钥/生效时机；12-Factor）, required: true, kind: narrative }
 entities: {}
 narratives:
   deploy: required
 gates:
   - 回滚必须有数据一致性结论（G4 语义）
+  - 配置必须来自环境变量（12-Factor）；硬编码密钥/地址 → error
+  - 构建产物与运行分离（不可变制品）
   - 纯库/CLI 项目可写「不涉及运行时部署」
 map_prompt: prompts/document/map/deploy.md
-output_budget_tokens: 2500
+output_budget_tokens: 3500