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

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-document/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: specflow-document
+description: "One-command scenario-based technical document generation (0→1 / bugfix / feature) using the IDE's model — run → Agent auto-generates → validate"
+---
+
+# SpecFlow: Document
+
+> **一键生成技术文档**：输入 `/specflow:document run <profile> --text "..."`，你用当前 IDE 模型自动完成全部生成，用户拿到 `document.md`。
+> 引擎不调用第三方 LLM API——由你（Agent，运行在 IDE 模型上）完成需要 LLM 的步骤，`specflow document` 只做确定性校验与渲染。
+
+## Invocation（一键入口）
+
+```text
+/specflow:document run [<0to1|bugfix|feature>] [--text "..."] [--design <file>] [--specs <file>] [--work-root <path>]
+```
+
+Cursor: `specflow:document run <profile>`; Codex: `$specflow-document run <profile>`.
+
+**收到 `run` 命令后，你必须自动完成全流程，不得中途停下来要求用户分步确认**（除非产物校验失败需要修正）。
+
+## 双模式
+
+document 同时支持两种用法：
+
+1. **通用模式（现状）**：`run <0to1|bugfix|feature>` 从自然语言/素材生成方案文档。
+2. **审批模式（approval 能力）**：`document approve` 从**四件套**（proposal / specs / design / tasks）生成审批文档——含闭环性检查（7 Pass）、可实施性评估（7 维）、质量红线（G1-G6）、可选签字栏（`--signoff`）。多仓：`--workspace-root <root>` 扫描各仓四件套，每仓生成后主仓合订。
+
+```text
+# 审批模式（单仓）
+specflow document approve --change <name> --signoff
+# 审批模式（多仓：各仓四件套 → 各自生成 → 主仓合订）
+specflow document approve --workspace-root <root> --changes "platform:ch1,web:ch2"
+```
+
+## 场景自动识别（省略 profile 时）
+
+当用户 **未指定** `<profile>` 时：
+
+1. 先用你的模型理解自然语言，判断场景：
+   - **0to1**：从零做一个产品/项目（"想做/做一个/新产品"）
+   - **bugfix**：排查修复问题（"报错/500/崩溃/挂了/异常"）
+   - **feature**：给已有系统加功能（"新增/加个/扩展"）
+2. 若判断明确 → 直接使用该场景。
+3. 若**不确定**或信号冲突 → **向用户确认**（列出 0to1 / bugfix / feature 三个选项及含义），等待用户选择后再继续。
+4. 可选：`specflow document detect --text "..."` 查看确定性关键词识别的结果作为参考。
+
+> 确定性规则（`detect`）是初判参考；你的模型理解更准。以模型判断 + 用户确认为准。
+
+## 一键执行流程（Agent 自动完成）
+
+```text
+run [<profile>]
+  ├─ ① 规划    specflow document plan <profile> ...   → 得到步骤清单 + workRoot
+  ├─ ② 生成    你（Agent）用当前模型按步骤逐项执行：
+  │     ├─ 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 document validate --work-root <path>
+                 └─ 通过 → 输出 document.md；失败 → 修正产物后重跑 validate
+```
+
+## ① 规划（plan）
+
+```text
+specflow document plan <profile> [--text "..."] [--design <file>] [--specs <file>] [--work-root <path>]
+```
+
+引擎输出每个 Agent 步骤（id / 做什么 / 参考提示词 / 输入 / 输出 / 必做）。你按此清单执行即可。
+
+## ② 生成（你，用 IDE 模型执行）
+
+0. **读取项目规约（必须先做）**：生成任何章节前，先扫描项目规约与 IDE 规则——
+   - 配置：`specflow/config.yaml` 的 `conventions.<topic>`（architecture / database / api / frontend）
+   - 中立文档：`docs/db/conventions.md`、`docs/api/guidelines.md`、`docs/engineering/*` 等
+   - IDE 规则：`.cursor` / `.claude` / `.agents` 下的 skills 与 rules
+   - guidance packs：`skills/guidance-packs.yaml` 声明的私有知识包（如 database）
+   - **优先级：项目约定 > SpecFlow guidance > LLM**。未发现时显式标注「未发现项目规约」。
+   - 将数据库 DDL 约定、API 规范、前端规约、架构禁令落实到后续章节。
+1. **input-summary**（多输入或长输入时）：读全部输入，产出紧凑摘要 → `digests/input-summary.md`。
+2. **outline**：按场景 Profile 生成 `outline.yaml`——章节序 + 每章要点（kind / references / source_segments）+ 实体注册表 + 决策。参考 `.claude/specflow/prompts/document/outline/general.md`。
+3. **逐章填空**：每章一个步骤 → `chapters/<id>.md`（叙述）+ 契约实体进 `entities.json`。参考 `.claude/specflow/prompts/document/map/goal.md` 等（如 `map/api-design.md`、`map/root-cause.md`）。
+4. **review**（可选）：独立审查全部章节 → `review-result.json`（findings + part_hashes）。参考 `.claude/specflow/prompts/document/review/ai-review.md`。
+
+## ③ 校验（validate，引擎确定性执行）
+
+```text
+specflow document validate --work-root <path>
+```
+
+引擎校验：
+- outline 必选章 / references / kind 一致性
+- 每章叙述过反偷懒 lint（禁 TODO/待补充/同上/含糊词）
+- 契约实体 zod + 结构化覆盖（引用的实体必须被填充）
+- 通过后渲染 `document.md`（+ `document.html`）
+
+**若 validate 失败**：读取 diagnostics，修正对应产物，重跑 validate，直到通过。
+
+## 内置场景 Profile
+
+| Profile | 必选章 | 候选章 |
+|---------|--------|--------|
+| `0to1` | goal / tech-selection / mvp-boundary / non-goals | architecture / api-design / data-model / test-strategy |
+| `bugfix` | reproduce / root-cause / fix | impact / regression |
+| `feature` | requirement / test-strategy | api-design / data-model / ui-design |
+
+## 质量红线（生成时必须满足）
+
+- 契约实体：接口须含 ≥1 失败示例（G2）；表须含完整 DDL。
+- 覆盖：每个大纲要点必须有填充落点。
+- 反偷懒：禁止 TODO/待补充/同上/含糊词。
+- 一致性：跨章实体名/路径与 outline.yaml 冻结名一致，不靠记忆。
+
+## 说明
+
+- `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/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,24 @@
+# 接口设计（候选；依赖架构）
+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 }
+entities:
+  interfaces:
+    required: [id, name, method, path, errors]
+    each:
+      failure_example: required
+      errors_table: required
+narratives:
+  design_notes: required
+gates:
+  - 禁止「暂定/如/实现时」接口名
+  - 每个接口必须 ≥1 失败示例
+  - 接口编号稳定可交叉引用
+map_prompt: prompts/document/map/api-design.md
+output_budget_tokens: 8000

package/templates/document/chapters/architecture.yaml

@@ -0,0 +1,18 @@
+# 架构设计（0→1 候选；依赖技术选型）
+id: architecture
+title: 架构设计
+when: input.hasLogic
+depends_on: [tech-selection]
+outline_points:
+  - { id: AR1, text: 总体架构（模块关系）, required: true, kind: mixed }
+  - { id: AR2, text: 核心组件与职责边界, required: true, kind: narrative }
+  - { id: AR3, text: 架构一致性自检, required: false, kind: narrative }
+entities: {}
+narratives:
+  architecture_notes: required
+gates:
+  - 架构图必须附「设计要点」说明（禁止只复述节点名）
+  - 每个组件须有「不做什么」边界
+  - 超 5 行流程必须 Mermaid（G1）
+map_prompt: prompts/document/map/architecture.md
+output_budget_tokens: 4000

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,17 @@
+# 兼容性与迁移
+id: compat-migration
+title: 兼容性与迁移
+when: null
+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 }
+entities: {}
+narratives:
+  compat_migration: required
+gates:
+  - 回滚后旧版本能否安全跳过/忽略新数据（G4）必须写明
+  - 零变更时显式「无新旧互读问题」
+map_prompt: prompts/document/map/compat-migration.md
+output_budget_tokens: 2500

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-logic.yaml

@@ -0,0 +1,16 @@
+# 核心算法 / 逻辑说明
+id: core-logic
+title: 核心算法/逻辑
+when: null
+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

package/templates/document/chapters/deploy.yaml

@@ -0,0 +1,18 @@
+# 部署/发布/回滚方案（可选）
+id: deploy
+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 }
+entities: {}
+narratives:
+  deploy: required
+gates:
+  - 回滚必须有数据一致性结论（G4 语义）
+  - 纯库/CLI 项目可写「不涉及运行时部署」
+map_prompt: prompts/document/map/deploy.md
+output_budget_tokens: 2500

package/templates/document/chapters/fix.yaml

@@ -0,0 +1,18 @@
+# 修复方案（bugfix 必选；依赖根因）
+id: fix
+title: 修复方案
+when: null
+depends_on: [root-cause]
+outline_points:
+  - { id: F1, text: 修复思路（对应根因）, required: true, kind: narrative }
+  - { id: F2, text: 具体改动点, required: true, kind: mixed }
+  - { id: F3, text: 修复验证方式, required: true, kind: narrative }
+entities: {}
+narratives:
+  fix_notes: required
+gates:
+  - 修复必须对应根因（禁止治标不治本）
+  - 改动点必须具体可执行
+  - 必须给出验证方式
+map_prompt: prompts/document/map/fix.md
+output_budget_tokens: 2500

package/templates/document/chapters/goal.yaml

@@ -0,0 +1,17 @@
+# 目标与问题（0→1 必选）
+id: goal
+title: 目标与问题
+when: null
+depends_on: []
+outline_points:
+  - { id: G1, text: 要解决什么问题（一句话痛点）, required: true, kind: narrative }
+  - { id: G2, text: 产品目标（解决…实现…）, required: true, kind: narrative }
+  - { id: G3, text: 目标用户与核心场景, required: true, kind: narrative }
+entities: {}
+narratives:
+  goal: required
+gates:
+  - 目标必须用「解决…实现…」句式
+  - 禁止含糊目标（如「做一个好用的工具」）
+map_prompt: prompts/document/map/goal.md
+output_budget_tokens: 2000

package/templates/document/chapters/impact.yaml

@@ -0,0 +1,16 @@
+# 影响面（bugfix 候选；依赖根因）
+id: impact
+title: 影响面
+when: null
+depends_on: [root-cause]
+outline_points:
+  - { id: IM1, text: 受影响功能/用户/数据, required: true, kind: narrative }
+  - { id: IM2, text: 影响严重度评估, required: true, kind: narrative }
+entities: {}
+narratives:
+  impact_notes: required
+gates:
+  - 必须覆盖功能/用户/数据三维度
+  - 严重度必须有依据
+map_prompt: prompts/document/map/impact.md
+output_budget_tokens: 1500

package/templates/document/chapters/implementability.yaml

@@ -0,0 +1,22 @@
+# 可实施性评估（审批模式必选；7 维）
+id: implementability
+title: 可实施性评估
+when: null
+depends_on: [closed-loop, test-strategy]
+outline_points:
+  - { id: IM1, text: 完整性（READY/NEEDS REFINEMENT/BLOCKED）, required: true, kind: narrative }
+  - { id: IM2, text: 规格对齐, required: true, kind: narrative }
+  - { id: IM3, text: 任务可执行性, required: true, kind: narrative }
+  - { id: IM4, text: 技术可行性, required: true, kind: narrative }
+  - { id: IM5, text: 依赖明确性, required: true, kind: narrative }
+  - { id: IM6, text: 架构一致性, required: true, kind: narrative }
+  - { id: IM7, text: 实施风险, required: true, kind: narrative }
+entities: {}
+narratives:
+  implementability: required
+gates:
+  - 每维必须给结论（READY/NEEDS REFINEMENT/BLOCKED）+ 说明
+  - 必须给可实施性总评
+  - 禁止与 §4 深度矛盾（如「READY」但 §4 缺细节）
+map_prompt: prompts/document/map/implementability.md
+output_budget_tokens: 2500

package/templates/document/chapters/mvp-boundary.yaml

@@ -0,0 +1,20 @@
+# MVP 边界（0→1 必选；依赖目标）
+id: mvp-boundary
+title: MVP 边界
+when: null
+depends_on: [goal]
+outline_points:
+  - { id: MVP1, text: MVP 核心功能清单, required: true, kind: entity }
+  - { id: MVP2, text: 后续版本功能, required: true, kind: narrative }
+  - { id: MVP3, text: 预估复杂度与开发阶段, required: true, kind: narrative }
+entities:
+  decisions:
+    required: [id, text]
+narratives:
+  mvp_notes: required
+gates:
+  - MVP 核心功能 ≤5 条
+  - 必须区分「MVP 核心 / 后续版本」
+  - 禁止范围蔓延（把非核心塞进 MVP）
+map_prompt: prompts/document/map/mvp-boundary.md
+output_budget_tokens: 2500

package/templates/document/chapters/non-goals.yaml

@@ -0,0 +1,17 @@
+# 非目标（0→1 必选；依赖 MVP 边界）
+id: non-goals
+title: 非目标（本期不做）
+when: null
+depends_on: [mvp-boundary]
+outline_points:
+  - { id: NG1, text: 明确排除的功能/优化点, required: true, kind: narrative }
+  - { id: NG2, text: 每个非目标的排除理由, required: true, kind: narrative }
+entities: {}
+narratives:
+  non_goals: required
+gates:
+  - 至少列 1 条非目标
+  - 每个非目标必须写明「不做理由」
+  - 禁止把「做不到」写成「不做」
+map_prompt: prompts/document/map/non-goals.md
+output_budget_tokens: 1500

package/templates/document/chapters/regression.yaml

@@ -0,0 +1,16 @@
+# 回归验证（bugfix 候选；依赖修复）
+id: regression
+title: 回归验证
+when: null
+depends_on: [fix]
+outline_points:
+  - { id: RG1, text: 回归测试范围, required: true, kind: narrative }
+  - { id: RG2, text: 防复发策略, required: true, kind: narrative }
+entities: {}
+narratives:
+  regression_notes: required
+gates:
+  - 回归范围必须覆盖受影响面
+  - 必须有防复发策略（测试/监控）
+map_prompt: prompts/document/map/regression.md
+output_budget_tokens: 1500

package/templates/document/chapters/reproduce.yaml

@@ -0,0 +1,16 @@
+# 复现路径（bugfix 必选）
+id: reproduce
+title: 复现路径
+when: null
+depends_on: []
+outline_points:
+  - { id: R1, text: 复现步骤与环境, required: true, kind: narrative }
+  - { id: R2, text: 预期 vs 实际行为, required: true, kind: narrative }
+entities: {}
+narratives:
+  reproduce_notes: required
+gates:
+  - 复现步骤必须可执行（编号步骤）
+  - 必须写明预期 vs 实际
+map_prompt: prompts/document/map/reproduce.md
+output_budget_tokens: 1500

package/templates/document/chapters/requirement.yaml

@@ -0,0 +1,18 @@
+# 需求（feature 必选）
+id: requirement
+title: 需求
+when: null
+depends_on: []
+outline_points:
+  - { id: REQ1, text: 功能需求描述, required: true, kind: narrative }
+  - { id: REQ2, text: 验收标准（Given-When-Then）, required: true, kind: mixed }
+entities:
+  decisions:
+    required: [id, text]
+narratives:
+  requirement_notes: required
+gates:
+  - 需求必须可验证（有明确验收标准）
+  - 禁止含糊需求（如「更好的体验」）
+map_prompt: prompts/document/map/requirement.md
+output_budget_tokens: 3000

package/templates/document/chapters/root-cause.yaml

@@ -0,0 +1,18 @@
+# 根因分析（bugfix 必选；依赖复现）
+id: root-cause
+title: 根因分析
+when: null
+depends_on: [reproduce]
+outline_points:
+  - { id: C1, text: 直接原因, required: true, kind: narrative }
+  - { id: C2, text: 触发条件, required: true, kind: narrative }
+  - { id: C3, text: 影响链路, required: true, kind: narrative }
+entities: {}
+narratives:
+  root_cause: required
+gates:
+  - 禁止「可能是…」含糊根因
+  - 必须区分直接原因 vs 触发条件
+  - 根因必须可验证（与复现步骤对应）
+map_prompt: prompts/document/map/root-cause.md
+output_budget_tokens: 2000

package/templates/document/chapters/signoff.yaml

@@ -0,0 +1,15 @@
+# 审批意见（可选；仅人工签字栏，用户 --signoff 时启用）
+id: signoff
+title: 审批意见
+when: input.includeSignoff
+depends_on: []
+outline_points:
+  - { id: SG1, text: 人工审批签字栏（角色/姓名/结论/日期/意见）, required: true, kind: narrative }
+entities: {}
+narratives:
+  signoff: required
+gates:
+  - 禁止写入 AI 预审建议（仅人工签字栏）
+  - 每个角色有结论选项（批准/退回/拒绝）
+map_prompt: prompts/document/map/signoff.md
+output_budget_tokens: 1000

package/templates/document/chapters/tech-selection.yaml

@@ -0,0 +1,20 @@
+# 技术选型（0→1 必选；五元组门禁）
+id: tech-selection
+title: 技术选型
+when: null
+depends_on: []
+outline_points:
+  - { id: TS1, text: 前端五元组（Framework/Styling/State/UI kit/FE testing）, required: true, kind: entity }
+  - { id: TS2, text: 后端/数据库/基础设施选型与理由, required: true, kind: mixed }
+  - { id: TS3, text: 选型理由（为何不用备选）, required: true, kind: narrative }
+entities:
+  decisions:
+    required: [id, text]
+narratives:
+  selection_reason: required
+gates:
+  - 前端必须给出五元组，禁止只写「用 React」
+  - 每项选型必须附理由
+  - 禁止臆造全栈（绿场需用户确认选型）
+map_prompt: prompts/document/map/tech-selection.md
+output_budget_tokens: 3000

package/templates/document/chapters/test-strategy.yaml

@@ -0,0 +1,20 @@
+# 测试策略（候选；依赖接口 + 数据）
+id: test-strategy
+title: 测试策略
+when: input.hasLogic
+depends_on: [api-design, data-model]
+outline_points:
+  - { id: T1, text: 分层测试矩阵, required: true, kind: entity }
+  - { id: T2, text: 测试环境与数据, required: true, kind: narrative }
+  - { id: T3, text: 与验收标准的映射, required: true, kind: narrative }
+entities:
+  decisions:
+    required: [id, text]
+narratives:
+  test_notes: required
+gates:
+  - 每个测试层级必须映射到具体验收标准/场景
+  - 每个层级有工具/框架 + 可验证目标
+  - 不涉及测试变更时显式标注
+map_prompt: prompts/document/map/test-strategy.md
+output_budget_tokens: 3000