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

package/dist/core/document/schemas.js

@@ -0,0 +1,158 @@
+/**
+ * Document Engine — zod schemas (data model)
+ *
+ * Source of truth for the Generic LongDoc Engine (design doc
+ * docs/GENERIC_LONGDOC_ENGINE_DESIGN.md §6.2, decisions 1–9).
+ *
+ * Layered source of truth:
+ *  - Contract entities (interfaces/tables/decisions) → structured, zod-validated
+ *  - Narrative content → controlled Markdown fragments
+ *  - Outline is the two-pass core IR (replaces ACP index.yaml/parts_order)
+ */
+import { z } from 'zod';
+// ============= Field-level contract primitives =============
+export const FieldSchema = z.object({
+    name: z.string().min(1),
+    type: z.string().min(1),
+    required: z.boolean().default(false),
+    desc: z.string().optional(),
+    default: z.string().optional(),
+});
+export const ErrorSpecSchema = z.object({
+    condition: z.string().min(1),
+    status: z.string().min(1),
+    note: z.string().optional(),
+});
+// ============= Contract entities =============
+export const InterfaceEntitySchema = z.object({
+    id: z.string().min(1), // stable id, e.g. "I1"
+    name: z.string().min(1), // e.g. "SubmitStepResult"
+    method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']),
+    path: z.string().min(1),
+    request_fields: z.array(FieldSchema).optional(),
+    response_fields: z.array(FieldSchema).optional(),
+    errors: z.array(ErrorSpecSchema).min(1), // G2: errors required
+    failure_examples: z.array(z.string()).min(1), // G2 hard gate
+});
+export const TableEntitySchema = z.object({
+    id: z.string().min(1), // stable id, e.g. "T1"
+    name: z.string().min(1),
+    ddl: z.string().min(1),
+    fields: z.array(FieldSchema).optional(),
+    migration: z.string().optional(), // G3: fill strategy
+    rollback: z.string().optional(), // G4: rollback compat
+});
+export const DecisionEntitySchema = z.object({
+    id: z.string().min(1), // e.g. "D1"
+    text: z.string().min(1),
+});
+export const EntitiesSchema = z.object({
+    interfaces: z.array(InterfaceEntitySchema).default([]),
+    tables: z.array(TableEntitySchema).default([]),
+    decisions: z.array(DecisionEntitySchema).default([]),
+});
+// ============= Outline (two-pass core IR, decision 6/8/9) =============
+export const OutlinePointKindSchema = z.enum(['entity', 'narrative', 'mixed']);
+export const OutlinePointSchema = z.object({
+    id: z.string().min(1),
+    text: z.string().min(1),
+    required: z.boolean().default(true),
+    kind: OutlinePointKindSchema.default('mixed'), // decision 9: coverage channel
+    references: z.array(z.string()).default([]), // decision 8: entity ids (full contract injection)
+    source_segments: z.array(z.string()).default([]), // decision 9: original input segment ids
+});
+export const OutlineChapterSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    points: z.array(OutlinePointSchema).min(1),
+    optional: z.boolean().default(false),
+});
+export const OutlineEntitySchema = z.object({
+    id: z.string().min(1),
+    frozen: z.string().min(1), // frozen name, must not drift
+    standalone: z.boolean().default(false), // decision 9: referenced by decisions only, no contract injection
+});
+export const FillOnceSchema = z.object({
+    enabled: z.boolean().default(false),
+    input_budget_tokens: z.number().int().positive().default(8000), // decision 9: exceed → fallback per-chapter
+});
+export const OutlineSchema = z.object({
+    profile: z.string().min(1),
+    chapters: z.array(OutlineChapterSchema).min(1), // order = render order
+    entities: z.array(OutlineEntitySchema).default([]),
+    decisions: z.array(z.string()).default([]),
+    fill_once: FillOnceSchema.optional(),
+});
+// ============= Constraint list (decision 8 · P1-D) =============
+export const ConstraintItemKindSchema = z.enum(['entity', 'decision', 'point']);
+export const ConstraintItemSchema = z.object({
+    kind: ConstraintItemKindSchema,
+    id: z.string().min(1),
+    label: z.string().min(1), // one-line label for digest prompt
+});
+// ============= Chapter component (reusable) =============
+export const ChapterComponentSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    when: z.preprocess((v) => (v === null || v === '' ? undefined : v), z.string().optional()), // condition DSL: input.<feature> && / || / !
+    depends_on: z.array(z.string()).default([]),
+    outline_points: z.array(OutlinePointSchema).default([]), // candidate points (Pass 1 reference)
+    entities: z.record(z.any()).optional(), // chapter entity schema description
+    narratives: z.record(z.any()).optional(),
+    gates: z.array(z.string()).default([]),
+    map_prompt: z.string().optional(),
+    output_budget_tokens: z.number().int().positive().optional(), // per-chapter output cap
+});
+// ============= Scenario profile (three-way classification, decision 8 · P1-J) =============
+export const ScenarioProfileSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    required: z.array(z.string()).min(1), // must be included by outline
+    optional_candidates: z.array(z.string()).default([]), // LLM may choose (subject to when)
+    forbidden: z.array(z.string()).default([]), // never appear in this scenario
+    shared: z.array(z.string()).default([]), // global chapters allowed in dependency closure
+});
+// ============= Review (decision 9 · target + max_rounds) =============
+export const ReviewTargetSchema = z.enum(['entity', 'narrative', 'mixed']);
+export const ReviewFindingSchema = z.object({
+    id: z.string().min(1),
+    severity: z.enum(['critical', 'important', 'minor']),
+    category: z.string().min(1),
+    message: z.string().min(1),
+    target: ReviewTargetSchema.default('narrative'), // decision 9: what to fix
+    chapter: z.string().optional(),
+    status: z.enum(['open', 'fixed', 'waived']).default('open'),
+    waiver_reason: z.string().optional(),
+});
+export const ReviewResultSchema = z.object({
+    schema: z.literal('specflow.document.review/v1'),
+    change: z.string().min(1),
+    reviewed_at: z.string().min(1),
+    reviewer: z.enum(['ai', 'human']).default('ai'),
+    verdict: z.enum(['pass', 'fail', 'pass_with_waivers']),
+    summary: z.string().optional(),
+    findings: z.array(ReviewFindingSchema).default([]),
+    part_hashes: z.array(z.object({ id: z.string(), sha256: z.string().min(64).max(64) })).default([]),
+});
+export function parseReviewResult(raw) {
+    return ReviewResultSchema.parse(raw);
+}
+// ============= Parsers =============
+export function parseInterfaceEntity(raw) {
+    return InterfaceEntitySchema.parse(raw);
+}
+export function parseTableEntity(raw) {
+    return TableEntitySchema.parse(raw);
+}
+export function parseEntities(raw) {
+    return EntitiesSchema.parse(raw);
+}
+export function parseOutline(raw) {
+    return OutlineSchema.parse(raw);
+}
+export function parseChapterComponent(raw) {
+    return ChapterComponentSchema.parse(raw);
+}
+export function parseScenarioProfile(raw) {
+    return ScenarioProfileSchema.parse(raw);
+}

package/dist/integrations/shared/capability-evidence.js

@@ -7,13 +7,10 @@ const MARKER_RULES = [
     { id: 'sub.propose.first_iteration', skill: 'propose', includes: ['first-iteration deep-analysis pass'] },
     { id: 'sub.refine.multi_round', skill: 'refine', includes: ['auto-multi-round loop', '## LOOP (Stages 2-4)'] },
     { id: 'sub.refine.challenge_scope', skill: 'refine', includes: ['Challenge Behaviors #3 and #4', 'question scope'] },
-    { id: 'sub.approval.closed_loop', skill: 'approval', includes: ['Closed-Loop Verification', 'Pass 1'] },
-    { id: 'sub.approval.implementability', skill: 'approval', includes: ['Implementability Assessment', 'Completeness'] },
-    { id: 'sub.approval.no_phase_change', skill: 'approval', includes: ['does NOT advance phase', 'phase stays `refined`'] },
-    { id: 'sub.approval.code_grounding', skill: 'approval', includes: ['Code Grounding', 'Pass 6'] },
-    { id: 'sub.approval.design_quality', skill: 'approval', includes: ['Design Quality Assessment', 'Over-Engineering'] },
-    { id: 'sub.approval.acp_finalize', skill: 'approval', includes: ['specflow approval finalize', 'Stage 12f'] },
-    { id: 'sub.approval.ai_review', skill: 'approval', includes: ['12e AI Review', 'part_hashes'] },
+    { id: 'sub.document.two_pass_outline', skill: 'document', includes: ['outline', 'Pass 1'] },
+    { id: 'sub.document.fill_in_by_points', skill: 'document', includes: ['填空', '要点'] },
+    { id: 'sub.document.contract_injection', skill: 'document', includes: ['契约注入', 'references'] },
+    { id: 'sub.document.coverage_check', skill: 'document', includes: ['覆盖', 'coverage'] },
     { id: 'sub.apply.phase_a', skill: 'apply', includes: ['## Phase A: Task Rewrite'] },
     { id: 'sub.apply.phase_b', skill: 'apply', includes: ['## Phase B: Subagent TDD Execution'] },
     { id: 'sub.apply.gap_detection', skill: 'apply', includes: ['Gap Detection'] },
@@ -26,7 +23,6 @@ const MARKER_RULES = [
     { id: 'failure.explore.proposal_exists_redirect', skill: 'explore', includes: ['explore is too late', 'refine'] },
     { id: 'failure.propose.explore_draft_gate', skill: 'propose', includes: ['Status: draft', 'REFUSE to proceed'] },
     { id: 'failure.apply.phase_gate', skill: 'apply', includes: ['HARD GATE (prerequisite)', 'phase is not `refined`, REFUSE'] },
-    { id: 'failure.approval.phase_gate', skill: 'approval', includes: ['phase must be `refined`', 'REFUSE to proceed'] },
     { id: 'failure.verify.explicit_skip_marker', skill: 'verify', includes: ['Pass 2: skipped (no baseline'] },
 ];
 /**

package/dist/integrations/shared/command-catalog.js

@@ -2,7 +2,7 @@ export const COMMAND_CATALOG = [
     { id: 'explore', description: 'Think-before-propose exploration when requirements are fuzzy' },
     { id: 'propose', description: 'Create proposal and spec artifacts for a change' },
     { id: 'refine', description: 'Refine and iterate on spec artifacts' },
-    { id: 'approval', description: 'Post-refine technical approval document with AI closed-loop check' },
+    { id: 'document', description: 'Generate scenario-based solution documents via the Generic LongDoc Engine' },
     { id: 'apply', description: 'Implement tasks from a change spec' },
     { id: 'review', description: 'Review code changes against spec' },
     { id: 'test', description: 'Run tests and verify coverage' },

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

@@ -13,13 +13,10 @@ export const CAPABILITY_MANIFEST = [
     { id: 'sub.propose.first_iteration', commandId: 'propose', level: 'sub-capability', required: true },
     { id: 'sub.refine.multi_round', commandId: 'refine', level: 'sub-capability', required: true },
     { id: 'sub.refine.challenge_scope', commandId: 'refine', level: 'sub-capability', required: true },
-    { id: 'sub.approval.closed_loop', commandId: 'approval', level: 'sub-capability', required: true },
-    { id: 'sub.approval.implementability', commandId: 'approval', level: 'sub-capability', required: true },
-    { id: 'sub.approval.no_phase_change', commandId: 'approval', level: 'sub-capability', required: true },
-    { id: 'sub.approval.code_grounding', commandId: 'approval', level: 'sub-capability', required: true },
-    { id: 'sub.approval.design_quality', commandId: 'approval', level: 'sub-capability', required: true },
-    { id: 'sub.approval.acp_finalize', commandId: 'approval', level: 'sub-capability', required: true },
-    { id: 'sub.approval.ai_review', commandId: 'approval', level: 'sub-capability', required: true },
+    { id: 'sub.document.two_pass_outline', commandId: 'document', level: 'sub-capability', required: true },
+    { id: 'sub.document.fill_in_by_points', commandId: 'document', level: 'sub-capability', required: true },
+    { id: 'sub.document.contract_injection', commandId: 'document', level: 'sub-capability', required: true },
+    { id: 'sub.document.coverage_check', commandId: 'document', level: 'sub-capability', required: true },
     { id: 'sub.apply.phase_a', commandId: 'apply', level: 'sub-capability', required: true },
     { id: 'sub.apply.phase_b', commandId: 'apply', level: 'sub-capability', required: true },
     { id: 'sub.apply.gap_detection', commandId: 'apply', level: 'sub-capability', required: true },
@@ -32,7 +29,6 @@ export const CAPABILITY_MANIFEST = [
     { id: 'failure.explore.proposal_exists_redirect', commandId: 'explore', level: 'failure-path', required: true },
     { id: 'failure.propose.explore_draft_gate', commandId: 'propose', level: 'failure-path', required: true },
     { id: 'failure.apply.phase_gate', commandId: 'apply', level: 'failure-path', required: true },
-    { id: 'failure.approval.phase_gate', commandId: 'approval', level: 'failure-path', required: true },
     { id: 'failure.verify.explicit_skip_marker', commandId: 'verify', level: 'failure-path', required: true },
 ];
 export const IDE_ASSET_MANIFEST = [

package/package.json

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

package/prompts/apply/phase-a-plan.md

@@ -18,7 +18,7 @@
 
 ## Artifact Language
 
-Before rewriting, resolve `artifacts.language` from the active planning root's `specflow/config.yaml` (see shared `artifact-language.md`). Rewrite **group titles and task description prose** in that language (`zh-CN` → Simplified Chinese; `en` → English). Keep file paths, commands, code blocks, symbols, and Verify command text unchanged. Do not switch business narrative to English when `zh-CN` is configured.
+Before rewriting, resolve `artifacts.language` from the active planning root's `specflow/config.yaml` (see shared `artifact-language.md`). Rewrite **group titles and task description prose** in that language (`zh-CN` → Simplified Chinese; `en` → English). Keep file paths, commands, code blocks, symbols, and Verify command text unchanged. Do not switch business narrative to English when `zh-CN` is configured. zh-CN: 叙述简要;怎么做用 1. 2. 3.。
 
 ## Input Order
 

package/prompts/document/map/acceptance.md

@@ -0,0 +1,8 @@
+# 章节填充：acceptance
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级

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

@@ -0,0 +1,17 @@
+# 章节填充：api-design（接口设计）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+
+## 接口章节硬规则（借鉴 approval api-guidance）
+
+1. **分层契约，禁止混层**：每个契约面对应一个独立 `In`（L2 Worker HTTP / L3 RPC+HTTP / L4 客户端 RPC），禁止「内部经 I7 一行代替 L4 详设」。
+2. **RPC / 服务名冻结**：禁止「暂定 / 如 Xxx / 实现时命名」；给出冻结的 RPC 名 + proto 字段号 + http_path。
+3. **proto 最小集**：新接口尽量给出可生成的 Proto 草案（rpc 名 / message / field 编号 / google.api.http）。
+4. **G2 失败示例（强制）**：清单中每个接口（含「不变」）除成功示例外，必须 ≥1 组失败示例（参数校验失败/租约过期/未认证），附完整 HTTP 或等价示例。只有错误码表不合格。
+5. **固定顺序**：元信息 → 请求体字段（或路径/Query/CLI flags）→ 请求示例 → 成功响应字段 → 响应示例(成功) → 响应示例(失败)(G2) → 错误表 →（可选）处理顺序。
+6. **接口清单稳定编号**：`In` 稳定，供 §4.6 页面引用与跨章交叉引用。
+7. **优先级**：项目约定 + 现网 OpenAPI/proto > SpecFlow 骨架 > LLM。

package/prompts/document/map/architecture.md

@@ -0,0 +1,7 @@
+# 章节填充：architecture
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/closed-loop.md

@@ -0,0 +1,8 @@
+# 章节填充：closed-loop
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级

package/prompts/document/map/compat-migration.md

@@ -0,0 +1,8 @@
+# 章节填充：compat-migration
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级

package/prompts/document/map/config-runtime.md

@@ -0,0 +1,8 @@
+# 章节填充：config-runtime
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级

package/prompts/document/map/core-logic.md

@@ -0,0 +1,8 @@
+# 章节填充：core-logic
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级

package/prompts/document/map/data-model.md

@@ -0,0 +1,17 @@
+# 章节填充：data-model（数据结构/数据模型变更）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+
+## 数据章节硬规则（借鉴 approval database-guidance）
+
+1. **先探测项目 DB 栈**：读项目规约 `conventions.database` + 现网 DDL/迁移文件，判断 MySQL/PostgreSQL/SQLite/Redis/ES 等。命中本地 guidance 则遵循，未命中 LLM fallback。
+2. **总则必须写明**：数据库迁移、新建表、增删列、新增索引、DDL 来源、项目约定（路径或「未发现」）。
+3. **每张表必须**：完整 CREATE TABLE（含 ENGINE/CHARSET/索引）+ 字段说明（类型/本迭代用法）。
+4. **G3 存量填充**：JSON 形状变更或新增列时必须写存量默认值填充策略（回填 SQL/读时默认值/禁止空读/上线顺序）。
+5. **G4 回滚兼容**：回滚后旧版本能否安全跳过/忽略新数据？写明机制（omitempty/忽略未知键/version 分派）。禁止只写「回滚应用」。
+6. **零 DDL 迭代**：仍须展示现网 DDL，禁止假装「不涉及数据库」。
+7. **优先级**：项目约定 > SpecFlow guidance > LLM。项目禁令（如「本迭代禁止迁移」）不得被通用规则覆盖。

package/prompts/document/map/deploy.md

@@ -0,0 +1,8 @@
+# 章节填充：deploy
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级

package/prompts/document/map/fix.md

@@ -0,0 +1,7 @@
+# 章节填充：fix
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/goal.md

@@ -0,0 +1,7 @@
+# 章节填充：goal
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/impact.md

@@ -0,0 +1,7 @@
+# 章节填充：impact
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/implementability.md

@@ -0,0 +1,8 @@
+# 章节填充：implementability
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级

package/prompts/document/map/mvp-boundary.md

@@ -0,0 +1,7 @@
+# 章节填充：mvp-boundary
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/non-goals.md

@@ -0,0 +1,7 @@
+# 章节填充：non-goals
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/regression.md

@@ -0,0 +1,7 @@
+# 章节填充：regression
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/reproduce.md

@@ -0,0 +1,7 @@
+# 章节填充：reproduce
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/requirement.md

@@ -0,0 +1,7 @@
+# 章节填充：requirement
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/root-cause.md

@@ -0,0 +1,7 @@
+# 章节填充：root-cause
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/signoff.md

@@ -0,0 +1,8 @@
+# 章节填充：signoff
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级

package/prompts/document/map/tech-selection.md

@@ -0,0 +1,17 @@
+# 章节填充：tech-selection（技术方案评估）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+
+## 技术评估章节硬规则（借鉴 approval 技术方案评估）
+
+1. **选型五元组表格**：方向/选定方案/备选/选择理由/来源——前端、后端、数据库与缓存、基础设施至少四行。禁止只写「用 React」。
+2. **决策评审表**：每个关键决策给 决策/选定方案/备选方案/理由/影响评估/状态。来源=用户确认优先；绿场缺选型时强制。
+3. **风险与权衡**：列出技术风险（复杂度/依赖/性能/成本），给缓解措施或接受理由。
+4. **目标与非目标**：明确本章方案的 Goals 与 Non-Goals（不做什么）。
+5. **现状与约束**：用可读中文归纳现状与硬约束（含「本迭代禁止…」类红线）；禁止代码腔堆砌。
+6. **设计质量评估**：检查过度设计（YAGNI）——是否合理扩展性 vs 不必要的复杂度。
+7. **优先级**：项目约定 + 用户确认 > SpecFlow guidance > LLM。

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

@@ -0,0 +1,7 @@
+# 章节填充：test-strategy
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

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

@@ -0,0 +1,18 @@
+# 章节填充：ui-design（前端/UI 设计）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+
+## 前端章节硬规则（借鉴 approval frontend-guidance）
+
+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。

package/prompts/document/outline/general.md

@@ -0,0 +1,37 @@
+# Outline 生成（Pass 1）— 通用
+
+你是文档大纲设计专家。基于【全局输入摘要】与【场景 Profile 约束】，生成一份结构化的文档大纲。
+
+## 输入
+- 全局输入摘要（含各段 id 与实体候选）
+- 场景 Profile：必选章 / 候选章（含 when 条件）/ 禁止章
+
+## 输出（JSON，符合 outline schema）
+```json
+{
+  "profile": "<profile-id>",
+  "chapters": [
+    {
+      "id": "<chapter-id>",
+      "title": "<章节标题>",
+      "optional": false,
+      "points": [
+        { "id": "P1", "text": "要点描述", "required": true, "kind": "mixed", "references": ["I1"], "source_segments": ["seg-design-01"] }
+      ]
+    }
+  ],
+  "entities": [
+    { "id": "I1", "frozen": "scheduler.SubmitStepResult", "standalone": false }
+  ],
+  "decisions": ["D1", "D2"]
+}
+```
+
+## 硬规则
+1. **章节约束**：必选章全含；候选章按 when 条件与输入取舍；禁止章绝不出现。
+2. **要点 kind**：引用了实体的要点 → `mixed` 或 `entity`；纯论述 → `narrative`。有 `references` 时 kind 不能是 `narrative`。
+3. **references**：要点引用的实体 id 必须在 `entities` 注册表里。
+4. **实体完整性**：注册表里每个实体必须被至少一个要点 `references` 引用（除非 `standalone: true`，仅供全局决策引用）。
+5. **source_segments**：要点尽量标注来源段 id（来自全局摘要的段 id）。
+6. **每要点引用 ≤3 个实体**。
+7. **要点数量**：每章 2-5 个要点，覆盖该章必须覆盖的维度。

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

@@ -0,0 +1,56 @@
+# AI Review（Pass 3）— 通用长文档审查
+
+你是独立审查者，审查一份**分片生成**的方案文档。你与生成者是分离的——以"挑错"为目标，不替生成者辩护。
+
+## 输入
+- 大纲（outline.yaml）
+- 各章填充（chapters/*.md）
+- 契约实体（entities.json）
+- 依赖摘要与约束清单
+
+## 审查维度（R1–R14）
+- R1 跨章命名：同一实体在 § 各章/大纲/实体区用同一规范名，无「暂定/实现时」
+- R2 决策落地：大纲 decisions 每项在对应章有具体行为
+- R3 实体↔正文：大纲实体注册表每个实体有实质内容；无孤儿实体
+- R4 深度均衡：同批/同依赖链的章节深度可比，无「一章详、一章 stub」
+- R5 交叉引用：引用用稳定 id（P*/I*/T*），目标存在
+- R6 图文一致：时序/流程图与相邻正文一致
+- R7 契约完整：listed 接口/表满足字段/成功/失败示例/错误表
+- R8 枚举闭合：status/enum 集合明确闭合，无「等」
+- R9 分支闭合：提到的重试/取消/超时/回滚路径有结论或 [待 refine 澄清]
+- R10 UI↔API 对齐：uiInScope 时 §UI 字段与接口对齐；空态/加载/错误齐
+- R11 多场景一致：各 Profile 章节覆盖与该场景匹配
+- R12 stub 清除：无 TODO/待补充/仅占位
+- R13 结论一致：可实施性/就绪结论与章节深度匹配
+- R14 大纲要点覆盖：每个 kind=narrative|mixed 要点对应小节存在且有实质内容（非 stub）
+
+## 输出（JSON，符合 review-result schema）
+```json
+{
+  "schema": "specflow.document.review/v1",
+  "change": "<id>",
+  "reviewed_at": "<iso>",
+  "reviewer": "ai",
+  "verdict": "pass | fail | pass_with_waivers",
+  "summary": "发现与修复概况",
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "critical | important | minor",
+      "category": "cross_part_naming",
+      "message": "I3 在 §2 与 04.5 命名不一致",
+      "target": "entity | narrative | mixed",
+      "chapter": "api-design",
+      "status": "open | fixed | waived",
+      "waiver_reason": "仅 minor 可 waived，必须写明理由"
+    }
+  ],
+  "part_hashes": [{ "id": "api-design", "sha256": "<sha256>" }]
+}
+```
+
+## 规则
+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（供防篡改校验）
+4. verdict：全 fixed → pass；仅 minor waived → pass_with_waivers；任一 critical/important open → fail

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