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

package/dist/core/document/schemas.js

@@ -0,0 +1,191 @@
+/**
+ * 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';
+// ============= 通用归一化（P2） =============
+/** 把显式 null 归一为 undefined，使 `.default([])` 对 null 与缺键行为一致（zod v3 默认不处理 null）。 */
+const nullish = (schema) => z.preprocess((v) => (v === null ? undefined : v), schema);
+// ============= 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().trim().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().trim().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().trim().min(1), // e.g. "D1"
+    text: z.string().min(1),
+});
+export const EntitiesSchema = z.object({
+    interfaces: nullish(z.array(InterfaceEntitySchema).default([])),
+    tables: nullish(z.array(TableEntitySchema).default([])),
+    decisions: nullish(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().trim().min(1),
+    text: z.string().min(1),
+    required: z.boolean().default(true),
+    kind: OutlinePointKindSchema.default('mixed'), // decision 9: coverage channel
+    references: nullish(z.array(z.string()).default([])), // decision 8: entity ids (full contract injection)
+    source_segments: nullish(z.array(z.string()).default([])), // decision 9: original input segment ids
+});
+export const OutlineChapterSchema = z.object({
+    // 白名单字符集与 paths.ts CHAPTER_ID_RE 一致：拒绝路径分隔符/`..`/空串（防路径穿越）
+    id: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/, 'chapter id must be a safe identifier'),
+    title: z.string().min(1),
+    points: z.array(OutlinePointSchema).min(1),
+    optional: z.boolean().default(false),
+});
+export const OutlineEntitySchema = z.object({
+    id: z.string().trim().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: nullish(z.array(OutlineEntitySchema).default([])),
+    decisions: nullish(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().trim().min(1),
+    label: z.string().min(1), // one-line label for digest prompt
+});
+// ============= Chapter component (reusable) =============
+export const ChapterComponentSchema = z.object({
+    id: z.string().trim().min(1),
+    title: z.string().min(1),
+    when: z.preprocess((v) => (typeof v === 'string' ? (v.trim() === '' ? undefined : v.trim()) : v === null ? undefined : v), z.string().optional()), // condition DSL: input.<feature> && / || / !
+    depends_on: nullish(z.array(z.string()).default([])),
+    outline_points: nullish(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: nullish(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().trim().min(1),
+    name: z.string().min(1),
+    required: z.array(z.string()).min(1), // must be included by outline
+    optional_candidates: nullish(z.array(z.string()).default([])), // LLM may choose (subject to when)
+    forbidden: nullish(z.array(z.string()).default([])), // never appear in this scenario
+    shared: nullish(z.array(z.string()).default([])), // global chapters allowed in dependency closure
+    appendices: nullish(z.array(z.enum(['anti-ai', 'handoff'])).default([])), // §7.2: rendered 附录 B/C
+});
+// ============= Review (decision 9 · target + max_rounds) =============
+export const ReviewTargetSchema = z.enum(['entity', 'narrative', 'mixed']);
+export const ReviewFindingSchema = z.object({
+    id: z.string().trim().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: nullish(z.array(ReviewFindingSchema).default([])),
+    part_hashes: nullish(z.array(z.object({ id: z.string().trim().min(1), sha256: z.string().regex(/^[a-f0-9]{64}$/i, 'sha256 must be 64 hex chars') })).default([])),
+    /** decision 9 · tamper semantics: chapters the ENGINE legitimately changed after the review
+     *  snapshot (entity refill / narrative fix notes). The tamper check exempts these from the
+     *  post-review "stale" verdict — every other chapter must still match the reviewer-time
+     *  `part_hashes` snapshot. */
+    post_review_repairs: nullish(z.array(z.object({ chapter: z.string().min(1), at: z.string().min(1) })).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 parseDecisionEntity(raw) {
+    return DecisionEntitySchema.parse(raw);
+}
+export function parseEntities(raw) {
+    return EntitiesSchema.parse(raw);
+}
+/**
+ * 兼容两种章节 JSON 块格式的实体解析：
+ *   - 未包装：`{"interfaces": [...], "tables": [...], "decisions": [...]}`（引擎推荐，validate 期望）
+ *   - 包装：`{"entities": {"interfaces": [...]}}`（部分 map 提示词曾要求，Agent 可能照此写）
+ * zod 默认 strip 未知 key，若顶层只有 `entities` 会被剥成空实体——这里显式解包后再解析，
+ * 避免「提示词包装格式 → 实体被剥空 → validate 报缺失 → Agent 反复返工」。
+ */
+export function parseEntitiesLenient(raw) {
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        const obj = raw;
+        if (obj.entities && typeof obj.entities === 'object' && !Array.isArray(obj.entities)) {
+            const inner = obj.entities;
+            // 仅当解包后含实体字段才解包；否则保持原样（可能是非实体叙述块）。
+            if ('interfaces' in inner || 'tables' in inner || 'decisions' in inner) {
+                return parseEntities(inner);
+            }
+        }
+    }
+    return parseEntities(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,14 +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.approval.multi_repo_subagent', skill: 'approval', includes: ['Stage 1c', 'multi-repo-spoke-subagent'] },
+    { id: 'sub.techdoc.two_pass_outline', skill: 'techdoc', includes: ['outline', 'Pass 1'] },
+    { id: 'sub.techdoc.fill_in_by_points', skill: 'techdoc', includes: ['填空', '要点'] },
+    { id: 'sub.techdoc.contract_injection', skill: 'techdoc', includes: ['契约注入', 'references'] },
+    { id: 'sub.techdoc.coverage_check', skill: 'techdoc', 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'] },
@@ -27,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,8 @@ 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: 'techdoc', description: 'Generate scenario-based solution documents via the Generic LongDoc Engine' },
+    { id: 'techdoc-synth', description: 'Synthesize multi-repo four artifacts into ONE cross-repo document (document + synthesize; scene auto-detect when --profile omitted)' },
     { 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,14 +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.approval.multi_repo_subagent', commandId: 'approval', level: 'sub-capability', required: true },
+    { id: 'sub.techdoc.two_pass_outline', commandId: 'techdoc', level: 'sub-capability', required: true },
+    { id: 'sub.techdoc.fill_in_by_points', commandId: 'techdoc', level: 'sub-capability', required: true },
+    { id: 'sub.techdoc.contract_injection', commandId: 'techdoc', level: 'sub-capability', required: true },
+    { id: 'sub.techdoc.coverage_check', commandId: 'techdoc', 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 },
@@ -33,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.8.0-beta",
+  "version": "1.8.2-beta",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [
@@ -55,6 +55,7 @@
     "release:major": "npm version major && git push && git push --tags"
   },
   "dependencies": {
+    "@gordon.gan/specflow": "^1.8.0-alpha",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "js-yaml": "^4.1.0",

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,9 @@
+# 章节填充：acceptance
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+- 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级

package/prompts/document/map/anti-ai.md

@@ -0,0 +1,29 @@
+# 附录填充：anti-ai（去AI味自检 · 附录 B）
+
+你是方案文档撰写员。为整份方案写「去AI味自检」条目，写入 `appendices/anti-ai.md`。
+
+## 硬规则（frontend-dev-guide §十一 → README §1.6）
+
+1. **至少 3 条**：每条自检对应五维中的一维，格式 `- 维度名：自检陈述`（如 `- 不做决策：明确写了本期不做什么（…），不是只列功能清单`）。
+2. **对着五维写**：
+   | 维度 | 自检问题 | AI 味反例 |
+   |------|---------|----------|
+   | 不做决策 | 明确说了「不做什么」？ | 只列功能清单 |
+   | 数字具体 | 指标/约束具体到数字？ | 「提升体验」 |
+   | 竞品立场 | 与竞品差异有一句话立场？ | 「借鉴头部最佳实践」 |
+   | 此刻合理性 | 为什么现在做？不做会怎样？ | 不解释时机 |
+   | 优先级倾斜 | P0/P1 有倾斜逻辑？ | 全功能同等权重 |
+3. **必须引用本文档的实际内容**：每条自检要能指到正文里的具体段落/数字（如「正文 §Benchmark 给了原始测量值 82ms/320ms，不是只说『更快』」）。禁止写与本文档无关的通用自检。
+4. **诚实**：自检条目是「我确实做到了」的声明，不是愿望清单。没做到的维度不要硬凑，写「本迭代不适用」并说明理由。
+5. **禁止 stub**（TODO/待补充/此处省略）；每条不少于 15 字。
+
+## 输出示例
+
+```markdown
+- 不做决策：明确写了预研不做架构/接口/UI 实现设计（§6.3 分界），不是只列候选功能。
+- 数字具体：benchmark 给出同条件同设备原始测量值（冷启动 82ms vs 320ms），不是「性能大幅提升」。
+- 竞品立场：一句话立场写明「本项目不选 Bun」及原因，不是「借鉴头部最佳实践」。
+- 此刻合理性：说明了本次预研触发点（生态缺口风险），不做会怎样已写（§research）。
+```
+
+> 优先级：项目约定 > SpecFlow guidance > LLM。

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

@@ -0,0 +1,26 @@
+# 章节填充：api-design（接口设计 · 契约 + 前端对接）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## 接口章节硬规则（借鉴 approval api-guidance + F1/F2 前端对接合并）
+
+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` 稳定，供页面引用与跨章交叉引用。
+
+## 前端对接维度（O5–O7，F1 §2.2 合并「契约+对接」）
+
+7. **前端请求封装**：统一请求层（拦截器：token 注入/统一错误处理/超时/重试策略/缓存），DTO → VO 映射层。禁止「每个页面自己 fetch + 自己处理错误」。
+8. **前端错误处理统一**：后端错误码 → 前端统一错误态映射（Loading-Empty-Error），禁止前后端各写一套错误码约定。
+9. **接口 Mock 与契约先行**：前端并行开发用 Mock，Mock 的数据结构必须与冻结契约一致（R5）；联调时切换真实接口不改变前端代码结构。
+10. **优先级**：项目约定 + 现网 OpenAPI/proto > SpecFlow 骨架 > LLM。
+
+> 前后端契约一致性是本章最高门禁：字段名、错误码、DTO 结构前后端必须对齐，禁止各写各的。

package/prompts/document/map/architecture.md

@@ -0,0 +1,27 @@
+# 章节填充：architecture（架构设计 · C4 分层 + ADR）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## 架构章节硬规则（G1 + README §1.7 + C4/ADR，见 f1-0to1.md §2.7.4）
+
+1. **架构图必须有图 + 文字（README §1.7 门禁）**：
+   - Mermaid 组件图/容器图（```mermaid block）。
+   - 图后逐节点说明职责/边界/「不放什么」，禁止只复述节点名，也禁止只有图无文字。
+   - 超 5 行流程必须 Mermaid（G1）。
+
+2. **每个组件必须写「不做什么」边界**（反AI决策 #1 在架构层）：组件职责一句话 + 明确不放什么（如「网关不做业务逻辑」「缓存层不做持久化」）。
+
+3. **C4 分层（AR4）**：按需给 Context（系统上下文，外部系统/用户）/ Container（可部署单元：Web/API/DB/消息）/ Component（模块组件）分层；每层给依赖方向。与 core-flow 的组件层交互时序对接（R5，交叉引用冻结 id）。
+
+4. **ADR 决策记录（AR5）**：把 tech-selection 的关键决策沉淀为 ADR——背景 / 决策 / 后果 / 备选（为什么不用备选）。引用 tech-selection 的 decisions 实体 id，不另起名。
+
+5. **架构一致性自检（AR3）**：对照目标（可扩展/可维护/性能），检查架构是否满足，给出自检结论。
+
+6. **功能场景（F2）特殊**：architecture = 功能架构（不是项目架构）——只画本次功能涉及的模块/组件边界/与现有系统的集成点，不重画整个项目架构。
+
+> 优先级：项目约定 > SpecFlow guidance > LLM。项目禁令不得被通用规则覆盖。

package/prompts/document/map/benchmark.md

@@ -0,0 +1,26 @@
+# 章节填充：benchmark（Benchmark 数据）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown（含测量数据表）
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## Benchmark 章节硬规则（F5 预研/选型 · 数据说话的严谨性）
+
+1. **同条件同设备（铁律）**：所有候选必须在**同一台设备/同一环境/同一数据规模**下测量，并写明条件（硬件型号 / OS / 版本 / 数据集 / 压测工具 / 次数）。**禁止**拿别人文档里的数字和自己实测比，也禁止不同环境互相硬比。
+
+2. **必须给原始测量值**：每个指标给**原始数据**（如 `P95 延迟 = 23ms`、`冷启动 = 1.8s`、`bundle gzip = 186KB`、`QPS = 1200`），再谈相对提升。**禁止**只写「提升 50%」「性能大幅提升」这类无原始数据的结论（反AI决策 #2 数字门禁）。
+
+3. **双维度覆盖（全栈）**：按预研对象取舍——
+   - **前端维度**：渲染速度（首屏/交互）、内存占用、bundle 体积（raw/gzip）、加载时间、Lighthouse。
+   - **后端维度**：吞吐（QPS/RPS）、延迟（P50/P95/P99）、内存/CPU 占用、连接数、DB 查询耗时。
+   - 只评估前端的预研可以只测前端维度，但**要说清为什么后端维度不适用**（如「纯前端库，无服务端运行时」）。
+
+4. **DX 对比也量化**：HMR 速度、调试工具链（DevTools 集成/断点）、类型体验（TS 支持等级）、文档质量、迁移成本。DX 可以主观，但要有「为什么」；能数字化的给数字。
+
+5. **注明数据可信度**：每个结论标注「可复现（附复现步骤）/ 单次测量（未复现）/ 样本数 N」。数据可信度决定选型结论的权重——不可复现的数据不能支撑硬结论。
+
+6. **结论承接选型**：benchmark 结论（哪个候选在哪些维度占优）要能被 tech-selection 评估矩阵引用，作为「得分」的事实依据。
+
+> 优先级：项目约定 > SpecFlow guidance > LLM。项目红线（如「性能目标是 LCP<2.5s」）优先于通用规则。

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

@@ -0,0 +1,9 @@
+# 章节填充：closed-loop
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+- 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级

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

@@ -0,0 +1,31 @@
+# 章节填充：compat-migration（兼容性与迁移 · 新旧 API 对照）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+- 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级
+
+## 兼容迁移章节硬规则（G3/G4 + F4 迁移扩展）
+
+1. **接口/数据兼容结论（CM1）**：本次变更是否破坏兼容——接口签名、数据结构、字段增减、行为变化。给明确结论（兼容/不兼容 + 影响面）。
+
+2. **存量填充策略（CM2 · G3）**：新数据/新字段对存量数据的填充策略（回填默认值/延迟填充/首次访问计算），写明触发时机与可回滚性。
+
+3. **回滚数据兼容（CM3 · G4）**：回滚后旧版本能否安全跳过/忽略新数据，必须写明。禁止「回滚就完事」。
+
+4. **新旧 API 变化对照（CM4）**：有 Breaking Change 时逐项对照：
+   ```
+   | 旧 API/字段 | 新 API/字段 | 变更类型（重命名/删除/改类型/新增必填） | 迁移动作 |
+   ```
+   禁止只写「不兼容」。
+
+5. **浏览器/依赖兼容（CM5）**：目标版本 + 降级手段（README §1.4），禁「支持最新浏览器」空话。
+
+6. **渐进式迁移（CM6）**：分阶段迁移计划、新旧代码共存（双构建/双运行/特性开关）、每阶段结束可运行。
+
+7. **零变更**：显式「无新旧互读问题」。
+
+> 优先级：项目约定 > SpecFlow guidance > LLM。项目禁令不得被通用规则覆盖。

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

@@ -0,0 +1,30 @@
+# 章节填充：component-design（组件设计）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown（含组件树）
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## 组件设计章节硬规则（frontend-dev-guide 组件方法论 + README §1.1/§1.2）
+
+1. **组件树必须标注流向（禁只列组件名）**：
+   ```
+   页面 PageX
+     └─ 容器 ContainerX（数据获取 + 状态）──Props 向下──
+           └─ 展示组件 PresenterX（只渲染）──Events 向上──
+                 └─ 基础组件 BaseX（default/loading/empty/error 四态）
+   ```
+   每条连线标注「props 流向」或「event 名 + 参数」。
+
+2. **单一职责 + 组合优先**：一个组件只做一件事；优先组合而非继承。给出每个组件的「职责一句话」和「不做什么」。
+
+3. **四态必须逐组件覆盖（README §1.2 结构模板）**：default / loading / empty / error（含重试），禁止只写成功态。每态给出 UI 表现（骨架屏/空文案+引导/错误重试）。
+
+4. **容器/展示分离**：容器组件负责数据获取与状态管理，展示组件只负责渲染。必须写明每个组件属于哪一类，数据从哪来。
+
+5. **复用与拆分边界（反AI决策 #1）**：至少给 1 条「本迭代不拆/不复用」的边界（如「两个页面暂共享此组件，但差异超过 30% 时拆开」）。禁止为抽象而抽象。
+
+6. **禁臆造组件树（README §1.1）**：组件树必须能追溯到页面/路由清单与设计输入；不存在于输入或推断来源的页面树禁止臆造。
+
+> 优先级：项目约定 > SpecFlow guidance > LLM。项目禁令不得被通用规则覆盖。

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

@@ -0,0 +1,9 @@
+# 章节填充：config-runtime
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+- 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级

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

@@ -0,0 +1,62 @@
+# 章节填充：core-flow（主业务流程时序）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown（含 Mermaid 时序图）
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## 时序图硬规则（README §1.7 架构图规范 + seqdiagram 精神）
+
+1. **必须有图**：主链路时序图用 Mermaid `sequenceDiagram` 源码块（diagram as code，可进 git/diff）。禁止用文字描述代替图，也禁止贴图片。
+
+2. **必须有文字说明图（图 + 文成对）**：
+   - 图前写一段「本图说明」：这条链路在讲什么、参与者（lifeline）分别是谁。
+   - 图后逐条解释关键消息/分支：每条消息为什么这么走、谁负责什么、失败时怎么办。
+   - **禁止只有图没有文字**，也禁止只有文字没有图。
+
+3. **覆盖关键分支**（禁止只画 happy path）：
+   - 成功路径：正常完成整条链路。
+   - 异常/失败路径：错误码 → 降级 → 重试 → 回滚（`alt`/`opt` 块）。
+   - 写操作链路：幂等（重复请求/重复提交如何保证只生效一次）+ 并发（并发写/乐观锁）。
+   - 异步/消息链路：回调/补偿/死信/超时（`par`/`Note` 标注）。
+   - 第三方交互：webhook/回调/超时降级/隔离（防雪崩）。
+
+4. **标注易错决策点**（seqdiagram-examples 精神）：每条主链路至少标 1 处「第一次容易做错的决策」——如幂等键怎么生成、超时设多少、回调如何防重、降级策略是什么。用 `Note right of` 或紧随图的文字说明。
+
+5. **交叉引用一致（R5）**：时序图里用到的接口/表，引用上游冻结契约 id（如 `I1`/`T1`），不要另起新名；与 api-design/data-model 保持一致。
+
+6. **粒度**：一图一事——一条主链路一张图，不要把所有流程塞进一张巨型图；图多时按业务主链路拆开，每图配文字。
+
+## Mermaid sequenceDiagram 模板（可填空）
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant U as 用户
+    participant FE as 前端
+    participant BE as 后端
+    participant DB as 数据库
+    participant TP as 第三方
+    participant WK as 异步任务
+    U->>FE: 触发主操作（{页面/按钮}）
+    FE->>BE: {API 调用 + 参数}
+    BE->>BE: 校验/幂等键（{幂等方案}）
+    BE->>DB: {读写 + 事务/锁}
+    alt 成功
+        BE-->>FE: 200 + {返回结构}
+        FE-->>U: 成功态（{UI 表现}）
+    else 失败
+        BE-->>FE: {错误码 + 降级}
+        FE-->>U: 错误态（{重试/回退}）
+    end
+    opt 异步
+        BE->>WK: 投递任务（{队列/补偿}）
+    end
+    opt 第三方
+        BE->>TP: {调用 + 超时/重试}
+        TP-->>BE: {回调/webhook}
+    end
+```
+
+> 优先级：项目约定 > SpecFlow guidance > LLM。项目禁令（如「禁止引入消息队列」）不得被通用规则覆盖。

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

@@ -0,0 +1,9 @@
+# 章节填充：core-logic
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+- 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级

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

@@ -0,0 +1,18 @@
+# 章节填充：data-model（数据结构/数据模型变更）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## 数据章节硬规则（借鉴 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,26 @@
+# 章节填充：deploy（部署交付方案 · 12-Factor）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+- 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级
+
+## 部署交付章节硬规则（F1 §2.6.2 + Twelve-Factor App）
+
+1. **环境拆分（DP1）**：dev/staging/prod 各自用途、谁访问、数据隔离。禁止「部署到服务器」这种空话。
+
+2. **CI/CD 流水线（DP2）**：代码检查 → 测试 → 构建 → 部署 各环节的工具与触发方式。**构建产物与运行分离（不可变制品）**：一次构建的镜像/产物用于所有环境，禁止「环境不同产物不同」。
+
+3. **部署拓扑（DP3）**：后端（容器/K8s/Serverless/虚拟机）+ 前端（静态托管/CDN/**SPA 路由回退**——history 模式必须配 fallback 到 index.html，否则刷新 404）。写明部署方式与理由。
+
+4. **发布策略（DP4）**：蓝绿 / 金丝雀 / 滚动 选择并给理由（按风险与回滚速度取舍）。
+
+5. **回滚（DP5）**：触发条件（什么指标/谁决策）、方式（切流量/重部署旧版本）、**数据一致性结论（G4 语义）**——回滚后新数据如何处理、旧版本能否安全读取，必须写明。禁止「出问题就回滚」一句话。
+
+6. **配置管理（DP6 · 12-Factor）**：配置来自环境变量；密钥（DB 密码/API key）不进代码仓库、不进制品；写明密钥管理方式（Secrets Manager/.env 注入）与生效时机（重启/热更新）。
+
+7. **纯库/CLI 项目**：可写「不涉及运行时部署」，并说明交付形态（npm 包/二进制/构建产物）。
+
+> 优先级：项目约定 > SpecFlow guidance > LLM。项目禁令不得被通用规则覆盖。