@gordon.gan/specflow 1.8.0-beta → 1.8.2-beta

package/prompts/explore/explore-session.md

@@ -84,7 +84,7 @@ If exploration reveals the idea is not worth building, say so — that is a vali
 
 ### Step 5 — Draft explore.md
 
-Load the scaffold from `.claude/specflow/templates/explore.md` and write `specflow/changes/<name>/explore.md` using the exact sections below.
+Load the scaffold from `.claude/specflow/templates/explore.md` and write `specflow/changes/<name>/explore.md` using the exact sections below. Follow `prompts/shared/artifact-language.md`. zh-CN: 叙述简要;怎么做用 1. 2. 3.。
 
 ### Step 6 — Gate: Direction confirmation (HARD GATE)
 

package/prompts/propose/design-draft.md

@@ -6,7 +6,7 @@
 
 Generate a substantive `design.md` representing your **first round of deep thinking** on this change. This is v1 of the design — refine will produce v2 by challenging assumptions, proposing alternative options, probing edge cases, and questioning scope. Your job here is to give refine something real to work with.
 
-**Narrative language:** Follow the resolved `artifacts.language` for Context, Goals / Non-Goals, Decisions, Risks, and Open Questions. Keep paths, commands, code, symbols, and technical identifiers unchanged.
+**Narrative language:** Follow the resolved `artifacts.language` for Context, Goals / Non-Goals, Decisions, Risks, and Open Questions. Keep paths, commands, code, symbols, and technical identifiers unchanged. zh-CN: 叙述简要;怎么做用 1. 2. 3.(见 `artifact-language.md`)。
 
 ## Inputs You Must Read
 

package/prompts/propose/proposal.md

@@ -4,7 +4,7 @@
 
 Generate a proposal document following the SpecFlow format. The proposal establishes WHY a change is needed and WHAT it affects.
 
-**Narrative language:** Follow the resolved `artifacts.language` for Why, What Changes, Impact, Capabilities prose, and success criteria. Keep change IDs, capability IDs, paths, commands, and code symbols unchanged.
+**Narrative language:** Follow the resolved `artifacts.language` for Why, What Changes, Impact, Capabilities prose, and success criteria. Keep change IDs, capability IDs, paths, commands, and code symbols unchanged. zh-CN: 叙述简要;怎么做用 1. 2. 3.(见 `artifact-language.md`)。
 
 ## Process
 

package/prompts/propose/specs.md

@@ -27,7 +27,7 @@ Create one spec file per capability at `specflow/changes/<change-name>/specs/<ca
 
 **CRITICAL FORMAT — the specflow CLI parses this exact structure. Deviations will cause validation and archive failures.**
 
-**Narrative language:** Follow the resolved `artifacts.language` for all business content — requirement descriptions, scenario titles, and the text after `WHEN` / `THEN`. Protocol markers below stay exactly English. Do not emit English narrative when `zh-CN` is configured.
+**Narrative language:** Follow the resolved `artifacts.language` for all business content — requirement descriptions, scenario titles, and the text after `WHEN` / `THEN`. Protocol markers below stay exactly English. Do not emit English narrative when `zh-CN` is configured. zh-CN: 叙述简要;怎么做用 1. 2. 3.(见 `artifact-language.md`)。
 
 Use `##` headers for delta operation sections. Use `###` for requirements. Use `####` for scenarios. Use `- **WHEN**` and `- **THEN**` bullet format for scenario steps.
 

package/prompts/propose/tasks-draft.md

@@ -31,7 +31,7 @@ This marker tells future readers (and the Apply Phase A prompt) that this docume
 
 2. **Each group contains 2 to 6 concrete checkbox items**
    - Format: `- [ ] N.M <action phrase>` where N is the group number and M is the item index within the group
-   - Group titles and task descriptions MUST follow the resolved `artifacts.language` from Artifact Language Setup (zh-CN → Simplified Chinese; en → English). Keep paths, commands, code, and symbols unchanged. Do not default to English when `zh-CN` is configured, and do not mix narrative languages inside the same tasks.md.
+   - Group titles and task descriptions MUST follow the resolved `artifacts.language` from Artifact Language Setup (zh-CN → Simplified Chinese; en → English). Keep paths, commands, code, and symbols unchanged. Do not default to English when `zh-CN` is configured, and do not mix narrative languages inside the same tasks.md. zh-CN: 叙述简要;怎么做用 1. 2. 3.。
 
 3. **Items are concrete actions, not topics**
    - zh-CN good: "实现 searchNotes 纯函数"

package/prompts/refine/design-output.md

@@ -4,7 +4,7 @@ Orchestration prompt for generating `design.md` from an approved proposal and de
 
 ## Overview
 
-The design document captures architectural decisions, technical approach, and risk assessment for a change. It bridges the gap between "what" (specs) and "how" (implementation plan).
+The design document captures architectural decisions, technical approach, and risk assessment for a change. It bridges the gap between "what" (specs) and "how" (implementation plan). Follow `prompts/shared/artifact-language.md`. zh-CN: 叙述简要;怎么做用 1. 2. 3.。
 
 ## Prerequisites
 

package/prompts/refine/update-artifacts.md

@@ -75,6 +75,8 @@ Never proceed to writing without an explicit A/B/C choice from the user.
 
 ## Format Preservation Rules
 
+zh-CN 叙述: 简要;怎么做用 1. 2. 3.(见 `prompts/shared/artifact-language.md`)。表格与协议标记不改结构。
+
 Each artifact type has format contracts that `specflow validate` and `specflow change
 archive` rely on. Violating them breaks downstream automation.
 

package/prompts/shared/artifact-language.md

@@ -14,6 +14,7 @@ Before creating or rewriting any SpecFlow artifact:
    - text after protected `WHEN` / `THEN` markers
    - design Context, Goals, Decisions, Risks, Open Questions
    - task group titles and task descriptions (including Apply Phase A rewrites)
+   - explore.md and approval.md narrative
 4. Do **not** mix languages for that business content. Protocol markers and technical identifiers stay as written below; everything else follows the resolved language.
 
 ## Protected Protocol
@@ -34,3 +35,15 @@ Language selection never changes SpecFlow's machine-readable protocol. Keep thes
 Also preserve capability IDs, change names, file paths, commands, code, symbols, and established technical identifiers.
 
 When modifying an existing requirement, preserve its exact requirement name if delta matching depends on that name. Do not translate historical artifacts automatically; the configured language applies prospectively to content created or intentionally rewritten in the current workflow.
+
+## Narrative style (all artifacts)
+
+Applies to **every** human-readable artifact: proposal, specs (after WHEN/THEN), design, tasks, explore, approval, apply Phase A rewrites.
+
+When `artifacts.language` is `zh-CN`:
+
+1. **简要** — 一句一事;禁止套话与大段散文。
+2. **有条理** — 「怎么做 / 怎么走 / 怎么处理」写成 **1. 2. 3.**,每步一句。
+3. **不改结构** — 表格、Mermaid、DDL、HTTP 示例、协议标记保持原样。
+
+`en`: keep prose brief; numbered steps for how-to. Same table/diagram exception.

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,115 @@
+---
+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> | --workset <name>] [--changes "repo1:ch1,repo2:ch2" | "repo1,repo2"] [--text "..."] [--profile <id>] [--work-root <path>] [--signoff]
+```
+
+Cursor: `specflow:techdoc-synth run ...`; Codex: `$specflow-techdoc-synth run ...`。
+
+**收到 `run` 命令后，你必须自动完成全流程，不得中途停下要求分步确认**（除非产物校验失败需要修正）。
+
+## 低成本调用（推荐，三种写法）
+
+命令长是常见痛点，`synthesize` 已内置三档简化：
+
+| 写法 | 命令 | 适用 |
+|---|---|---|
+| **A. `--workset`（最简，推荐）** | `/specflow:techdoc-synth run --workset talos-platform` | 已用 `specflow workset create` 存过三仓路径（成员指向各仓根目录），一次创建、后续零成本 |
+| **B. 只写仓名** | `/specflow:techdoc-synth run --workspace-root <root> --changes "talos,talos-web,talos-worker"` | 仓名短、change 名长时；自动选每仓最新 change |
+| **C. 省略 `--profile`** | 上两式均可省略 `--profile`，从 `--text`（优先）或四件套自动识别场景 | 场景关键词明确时；识别不出且有 `--text` → 向你确认 |
+
+- **workset 语义**：`--workset <name>` 自动推导 workspace-root（成员公共父目录）+ 每仓**最新非 archive change**；`--changes` 可覆盖（支持成员 label 或仓目录名，如 `--changes "api,web:ch2"`）。
+- **`--text` 自动识别涉及哪些功能**：省略 `--changes` 且提供 `--text` 时，按描述**自动匹配每仓最相关的 change**（对 proposal/design 摘要做 token 频率打分，change 名命中加分，并列取较新者；无关联才回退「最新」）。例：`--text "案例场景"` 自动选中三仓的 scenario-job-compile / web-scenario-cases / scenario-execution。
+- **描述模糊不打断（workset 模式）**：`--text` 识别场景不确定时，workset 模式默认取分数最高候选（如 feature）继续，directive 标注「场景识别较弱，默认采用 …」；`--workspace-root` 模式保持确认。
+- **零参数全自动**：`--workset <name>` + `--text "..."` 即可——workspace-root、各仓 change、场景 profile 全部自动解析。
+- **创建 workset**：`specflow workset create <name> --member "api:/path/repo1" --member "web:/path/repo2"`（或编辑 `~/.local/share/specflow/worksets/worksets.yaml`）。
+
+## 场景自动识别（省略 --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/acceptance.yaml

@@ -0,0 +1,16 @@
+# 验收标准（可选；按 capability 列出 Scenario + 可测试性）
+id: acceptance
+title: 验收标准
+when: null
+depends_on: [goal]
+outline_points:
+  - { id: AC1, text: Capability + Requirement 清单, required: true, kind: narrative }
+  - { id: AC2, text: 每个 Scenario 的可测试性标注, required: true, kind: narrative }
+entities: {}
+narratives:
+  acceptance: required
+gates:
+  - 每个验收标准必须映射到可测试性（✅ 功能 / ⚠️ 文档 / ❌ 不可测试）
+  - 禁止空泛（无 WHEN/THEN）
+map_prompt: prompts/document/map/acceptance.md
+output_budget_tokens: 3000

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

@@ -0,0 +1,29 @@
+# 接口设计（候选；依赖架构；0→1 全栈/功能场景合并「契约+前端对接」）
+id: api-design
+title: 接口设计
+when: input.containsApiChange
+depends_on: [architecture]
+outline_points:
+  - { id: O1, text: 接口总览与调用方/鉴权, required: true, kind: narrative }
+  - { 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]
+    each:
+      failure_example: required
+      errors_table: required
+narratives:
+  design_notes: required
+gates:
+  - 禁止「暂定/如/实现时」接口名
+  - 每个接口必须 ≥1 失败示例
+  - 接口编号稳定可交叉引用
+  - 涉及前端对接时，请求封装与错误码统一方案必须与契约对齐（R5，字段名/错误码禁各写各的）
+  - 前端接口 Mock 必须与契约一致（禁 Mock 一套、真实接口另一套）
+map_prompt: prompts/document/map/api-design.md
+output_budget_tokens: 8000

package/templates/document/chapters/architecture.yaml

@@ -0,0 +1,21 @@
+# 架构设计（0→1 候选；依赖技术选型；扩展：C4 分层 + ADR 决策记录）
+id: architecture
+title: 架构设计
+when: input.hasLogic && input.hasBackend
+depends_on: [tech-selection]
+outline_points:
+  - { 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
+gates:
+  - 架构图必须附「设计要点」说明（禁止只复述节点名）
+  - 每个组件须有「不做什么」边界
+  - 超 5 行流程必须 Mermaid（G1）
+  - C4 分层给到 Component 层时，与 core-flow 的组件层交互时序对接（R5）
+map_prompt: prompts/document/map/architecture.md
+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/closed-loop.yaml

@@ -0,0 +1,22 @@
+# 闭环性检查（审批模式必选；需求↔方案↔规格↔实施↔风险↔代码↔基线）
+id: closed-loop
+title: 闭环性检查
+when: null
+depends_on: [goal, tech-selection, architecture, api-design, data-model]
+outline_points:
+  - { id: CL1, text: 需求闭环（proposal↔specs）, required: true, kind: narrative }
+  - { id: CL2, text: 方案闭环（design↔specs）, required: true, kind: narrative }
+  - { id: CL3, text: 规格闭环（场景/可测试性/delta）, required: true, kind: narrative }
+  - { id: CL4, text: 实施闭环（tasks↔specs）, required: true, kind: narrative }
+  - { id: CL5, text: 风险闭环（缓解/BREAKING）, required: true, kind: narrative }
+  - { id: CL6, text: 代码落地性（锚点/结构/栈）, required: true, kind: narrative }
+  - { id: CL7, text: 基线对照（主 specs）, required: true, kind: narrative }
+entities: {}
+narratives:
+  closed_loop: required
+gates:
+  - 每个 Pass 必须给 ✅/⚠️/❌ 结论 + 一句话证据
+  - 必须给出整体闭环性结论（PASS / PASS WITH WARNINGS / FAIL）
+  - 禁止空泛（无证据的通过）
+map_prompt: prompts/document/map/closed-loop.md
+output_budget_tokens: 3000

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

@@ -0,0 +1,21 @@
+# 兼容性与迁移（扩展：新旧 API 对照 / 浏览器兼容 / 渐进式迁移，F4 用）
+id: compat-migration
+title: 兼容性与迁移
+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: 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/config-runtime.yaml

@@ -0,0 +1,16 @@
+# 配置与运行环境
+id: config-runtime
+title: 配置与运行环境
+when: null
+depends_on: [architecture]
+outline_points:
+  - { id: CFG1, text: 配置项（键路径/类型/默认值/生效时机）, required: true, kind: narrative }
+  - { id: CFG2, text: 约束与校验失败行为, required: true, kind: narrative }
+entities: {}
+narratives:
+  config_runtime: required
+gates:
+  - 配置变更须写明兼容（缺省兼容/是否改写存量）
+  - 完全不涉及写「不涉及」
+map_prompt: prompts/document/map/config-runtime.md
+output_budget_tokens: 2000

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

@@ -0,0 +1,16 @@
+# 核心算法 / 逻辑说明
+id: core-logic
+title: 核心算法/逻辑
+when: input.hasLogic
+depends_on: [architecture]
+outline_points:
+  - { id: LOG1, text: 核心算法/流程说明, required: true, kind: narrative }
+  - { id: LOG2, text: 边界与异常处理, required: true, kind: narrative }
+entities: {}
+narratives:
+  core_logic: required
+gates:
+  - 超 5 行流程必须 Mermaid（G1）
+  - 复杂交互页状态机用 stateDiagram-v2
+map_prompt: prompts/document/map/core-logic.md
+output_budget_tokens: 3000

package/templates/document/chapters/data-model.yaml

@@ -0,0 +1,25 @@
+# 数据模型（候选；依赖接口设计）
+id: data-model
+title: 数据模型
+when: input.hasPersistence
+depends_on: [api-design]
+outline_points:
+  - { id: DM1, text: 表结构与 DDL, required: true, kind: entity }
+  - { id: DM2, text: 字段说明 + 本迭代用法, required: true, kind: entity }
+  - { id: DM3, text: 存量填充策略（G3）, required: true, kind: narrative }
+  - { id: DM4, text: 回滚数据兼容（G4）, required: true, kind: narrative }
+entities:
+  tables:
+    required: [id, name, ddl]
+    each:
+      migration: required
+      rollback: required
+narratives:
+  data_notes: required
+gates:
+  - 每张表必须有完整 CREATE TABLE（含 ENGINE/CHARSET）
+  - JSON/新列必须有存量填充策略（G3）
+  - 必须有回滚数据兼容说明（G4）
+  - 零 DDL 迭代仍须展示现网 DDL（禁止假装不涉及数据库）
+map_prompt: prompts/document/map/data-model.md
+output_budget_tokens: 8000