@gordon.gan/specflow 1.3.3-beta → 1.4.1

package/prompts/approval/generate.md

@@ -0,0 +1,1191 @@
+<!-- SOURCE: SpecFlow original — integrates OpenSpec structural aggregation, arc42 design-review framework, ADR status fields, Superpowers challenge-behavior injection, and SpecFlow verify/review grounding patterns -->
+
+# Approval Document Generation
+
+> This prompt drives the `/specflow:approval` skill. It defines the 7-Pass closed-loop
+> verification, design quality assessment, detailed design generation, implementability
+> assessment, and the exact structure of `approval.md`. The calling SKILL.md owns phase
+> gating, anchor-file extraction, and user confirmation; this prompt owns the analysis
+> and document generation.
+
+## Entry Context
+
+Before running this flow, the SKILL.md has confirmed:
+
+- `phase: refined` in `.specflow.yaml`
+- All four artifacts exist: `proposal.md`, `specs/**/*.md`, `design.md`, `tasks.md`
+- `artifacts.language` resolved (default `en`)
+- Tech stack detected (Node/Go/Python/Rust/unknown)
+- Anchor files extracted from `design.md` + `tasks.md`
+- Optional: `specflow/specs/` baseline exists (for Pass 7)
+
+You MUST read, in this order, before any analysis:
+
+1. `specflow/changes/<name>/proposal.md` — the WHY and WHAT
+2. `specflow/changes/<name>/specs/**/*.md` — the behavioral contract (all delta specs)
+3. `specflow/changes/<name>/design.md` — the HOW (decisions, risks)
+4. `specflow/changes/<name>/tasks.md` — the implementation breakdown
+5. `specflow/changes/<name>/.specflow.yaml` — metadata (phase, created date)
+6. Optional: `specflow/changes/<name>/explore.md` — exploration context
+7. Optional: `specflow/specs/` baseline — for Pass 7 cross-check
+8. Anchor files (read in Pass 6, not here)
+
+Do not skip any of the four required artifacts. If any is missing, stop and tell the
+SKILL.md caller which are missing.
+
+---
+
+## Part A: Closed-Loop Verification (7 Passes)
+
+Each Pass examines cross-artifact or artifact-to-reality coherence from one angle.
+Every Pass MUST produce (for analysis / conversation):
+
+1. A **Verdict**: `PASS` | `WARNING` | `FAIL` | `SKIPPED`
+2. **Evidence**: concrete citations (keep brief; full matrices only when WARNING/FAIL)
+3. A brief **rationale** linking evidence to verdict
+
+**Document output (§8)**: collapse all 7 Passes into **one table** — see Part E §8.
+Do not paste per-Pass essays into `approval.md`.
+
+Verdict calibration:
+
+- `PASS` — no gaps found in this dimension.
+- `WARNING` — gaps exist but are recoverable. The plan is still implementable but the approver should note the risk.
+- `FAIL` — a structural break exists. The plan is not coherent or not grounded as-is.
+- `SKIPPED` — the check does not apply (e.g., greenfield project for Pass 6/7). A `SKIPPED` Pass does not affect the overall verdict.
+
+### Pass 1 — Requirement Closure (proposal ↔ specs)
+
+**AI self-prompt**: "Does every item in proposal's `## What Changes` have a corresponding
+delta spec? Does every capability listed in `## Capabilities` have a `specs/<name>/spec.md`?
+Does every impact area in `## Impact` have spec coverage? Is there a delta spec that the
+proposal never mentioned (orphan spec)?"
+
+**Check**:
+
+1. For each bullet in `## What Changes`, identify which capability/spec addresses it. If a change bullet has no corresponding spec, that is a `FAIL`.
+2. For each capability in `## Capabilities → New/Modified`, confirm `specs/<name>/spec.md` exists. Missing spec file is a `FAIL`.
+3. For each impact area in `## Impact`, assess whether the specs cover the behavioral consequences. Uncovered impact is a `WARNING`.
+4. For each delta spec file, confirm the proposal mentions its capability. Orphan spec is a `WARNING`.
+
+**Evidence format**: a table mapping proposal items → spec files, with coverage status.
+
+### Pass 2 — Design Closure (design ↔ specs)
+
+**AI self-prompt**: "Does every `### Decision N` in design.md point to at least one spec
+Requirement it enables? Is there a spec Requirement that has no design decision supporting
+it (orphan requirement)? Does any design decision contradict a spec scenario?"
+
+**Check**:
+
+1. For each decision in `design.md` under `## Design Decisions` (or equivalent), identify which spec Requirements it enables. A decision with no traceable requirement is a `WARNING`.
+2. For each spec Requirement, identify which design decision(s) support its implementation. A requirement with no supporting decision is a `WARNING`.
+3. Scan for contradictions: does any design decision specify behavior that conflicts with a `WHEN/THEN` scenario? Contradiction is a `FAIL`.
+
+**Evidence format**: a bidirectional table — decisions → requirements, and requirements → decisions.
+
+### Pass 3 — Spec Closure (scenario completeness + testability + delta integrity)
+
+**AI self-prompt**: "Does every Requirement have at least one Scenario? Are WHEN/THEN clauses
+testable? Are delta operations structurally complete?"
+
+**Check**:
+
+1. Every `### Requirement:` has ≥1 `#### Scenario:`. Missing scenario is a `FAIL`.
+2. Every Scenario has at least one `- **WHEN**` and one `- **THEN**`. Missing clause is a `FAIL`.
+3. **3-level testability grading** for each Scenario:
+   - **Functional-testable** (✅): WHEN condition is reproducible (specific input/config/state), THEN is verifiable (specific output/behavior). Example: "config contains `artifacts.language: zh-CN`" → reproducible.
+   - **Document-testable** (⚠️): Tests existence/completeness but not behavior. Example: "a user reads the initialization documentation" → can only verify doc exists, not that a user "reads" it.
+   - **Untestable** (❌): WHEN or THEN uses vague terms ("appropriate", "reasonable", "fast", "适当", "合理", "快速") or describes an unverifiable state.
+   - Document-testable and Untestable are both `WARNING`.
+4. REMOVED Requirements have `**Reason**:` and `**Migration**:`. Missing is a `FAIL`.
+5. RENAMED Requirements have `FROM:` and `TO:`. Missing is a `FAIL`.
+6. MODIFIED Requirements reference names that exist in the main specs baseline (if baseline exists). Mismatched name is a `FAIL`.
+7. Run `specflow validate` on each delta spec file. Any validation error is a `FAIL`.
+8. **Detailed-design coverage** (cross-check with §4 方案详细设计): every spec Requirement
+   that involves data/interface/flow changes must have a corresponding detailed-design
+   element. A Requirement whose implementation needs a data structure, interface, or state
+   flow but has NO detailed-design element (or an element marked "待 refine 澄清") is a
+   `WARNING` — the plan describes WHAT but not HOW to build it.
+
+**Evidence format**: per-spec-file, a Scenario table with columns: Scenario | WHEN | THEN | Testability (✅/⚠️/❌) | Notes.
+
+### Pass 4 — Implementation Closure (tasks ↔ specs)
+
+**AI self-prompt**: "Does every spec Requirement have at least one task implementing it? Is
+there a task that implements behavior not in any spec (scope creep)? Are tasks atomic enough?"
+
+**Check**:
+
+1. For each spec Requirement, identify which task(s) implement it. A requirement with no covering task is a `FAIL`.
+2. For each task, identify which spec Requirement it implements. A task with no traceable requirement is a `WARNING` (scope creep).
+3. Scan tasks for placeholders: 'TBD', 'TODO', 'implement feature', '待定'. Each is a `WARNING`.
+4. Assess task granularity: tasks that bundle multiple unrelated changes, or are so vague an engineer cannot estimate them, are `WARNING`.
+
+**Evidence format**: coverage matrix — requirements (rows) × tasks (columns), plus "scope creep" section.
+
+### Pass 5 — Risk Closure (risks ↔ mitigations + BREAKING migration + unidentified risks)
+
+**AI self-prompt**: "Does every risk in design.md have a mitigation? Are there BREAKING
+changes with no migration plan? Based on the change's nature, are there risks the design
+did not identify?"
+
+**Check**:
+
+1. For each risk in `design.md` under `## Risks / Trade-offs`, confirm a mitigation exists. Risk with no mitigation is a `WARNING`.
+2. For each `**BREAKING**` item in proposal's `## What Changes`, confirm a migration path. BREAKING with no migration is a `FAIL`.
+3. Reason about unidentified risks based on the change's nature: auth/security, data schema/migration, concurrency/race, external dependency supply-chain. Each unidentified risk is a `WARNING` with reasoning.
+
+**Evidence format**: risk table with columns: Risk | Severity | Mitigation | Status (identified+mitigated / identified+unmitigated / AI-identified-new).
+
+### Pass 6 — Code Grounding (design/tasks ↔ existing project code)
+
+> This Pass reads actual project code. It is the key difference between "self-consistency
+> check" and "landing feasibility check".
+
+**AI self-prompt**: "Do the files the plan says it will modify/extend actually exist? Is the
+plan's extension approach compatible with the existing code structure? Does the plan's
+tech choices match the project's actual tech stack?"
+
+**Anchor files**: the SKILL.md has already extracted the set of file paths referenced in
+`design.md` and `tasks.md`. Read each anchor file (the file itself only — do NOT follow
+imports, do NOT recurse into dependencies).
+
+**Greenfield handling**: If the project has no source code directory (e.g., no `src/`,
+no `lib/`, no `cmd/`), emit `SKIPPED (greenfield — no existing code to ground against)`
+and do not grade.
+
+**Check** (for non-greenfield projects):
+
+1. **File existence**: For each anchor file path, check if the file exists in the project.
+   - All exist → this sub-check passes.
+   - Some missing → `FAIL` with the list of missing files. The plan references files that don't exist — either it's wrong about the codebase, or it's a greenfield file to be created (if the plan clearly says "create new file X", that's fine; if it says "extend existing file X" and X doesn't exist, that's a FAIL).
+   - Plan says "create new file" and file doesn't exist → OK (not a failure).
+
+2. **Structure compatibility**: For each existing anchor file, read it and assess:
+   - If the plan says "extend function X" — does function X exist? Is it structured to be extensible (e.g., has a clear signature, not a monolithic 500-line function)?
+   - If the plan says "add module Y" — does the parent directory's pattern support adding modules (e.g., are there sibling modules following a consistent pattern)?
+   - If the plan says "modify config schema" — does the current schema structure support the modification without breaking existing consumers?
+   - Incompatibility is a `WARNING` (not a `FAIL` — the plan might still work with adjustments, but the approver should know).
+
+3. **Tech-stack consistency**: Does the plan's technology approach match the detected tech stack?
+   - Plan uses patterns/libraries consistent with the project's `package.json`/`go.mod`/etc. → OK.
+   - Plan introduces a new library/ pattern not in the project → `WARNING` with reasoning (may be justified, but the approver should confirm).
+   - Plan contradicts the tech stack (e.g., plan says "use jest" but project uses vitest) → `WARNING` unless design.md explicitly justifies the switch.
+
+**Evidence format**:
+- Table: Anchor File | Exists? | Plan Action (extend/create/modify) | Compatibility Assessment
+- Tech-stack consistency: one-line verdict with reasoning.
+- For greenfield: the single `SKIPPED (greenfield)` line, verbatim.
+
+### Pass 7 — Baseline Cross-Check (delta specs ↔ `specflow/specs/` main baseline)
+
+> This Pass checks whether the change's delta specs conflict with or duplicate existing
+> main specs. It is the "plan-time regression check" — verify owns the "implementation-time
+> regression check".
+
+**AI self-prompt**: "Do the delta specs' ADDED requirements duplicate anything already in the
+main specs? Do the MODIFIED requirements' names match existing main spec requirement names
+(so delta merge will work at archive time)? Does the change claim to modify a capability that
+doesn't exist in the baseline?"
+
+**Baseline handling**: If `specflow/specs/` does not exist or contains no spec files, emit
+`SKIPPED (no baseline — greenfield or no archived changes yet)` and do not grade. This is
+the same pattern as verify Pass 2.
+
+**Check** (when baseline exists):
+
+1. **Duplicate detection**: For each ADDED Requirement in the delta specs, check if a Requirement with the same name already exists in the main spec for the same capability. Duplicate is a `WARNING` (the archive merge would produce a duplicate header).
+2. **MODIFIED name matching**: For each MODIFIED Requirement, confirm a Requirement with the exact same name exists in the corresponding main spec. Mismatch is a `FAIL` (delta merge at archive time would fail with "Requirement not found").
+3. **REMOVED name matching**: For each REMOVED Requirement, confirm it exists in the main spec. Mismatch is a `FAIL`.
+4. **RENAMED FROM matching**: For each RENAMED Requirement's `FROM:` name, confirm it exists in the main spec. Mismatch is a `FAIL`.
+5. **Cross-capability conflict**: If the change modifies capability A's spec, does the change introduce behavior that conflicts with capability B's existing spec (if B exists in baseline)? Conflict is a `WARNING`.
+
+**Evidence format**:
+- For each delta operation (ADDED/MODIFIED/REMOVED/RENAMED), a row: Capability | Requirement Name | Operation | Baseline Status (exists/duplicate/not-found) | Verdict.
+- For greenfield: the single `SKIPPED (no baseline)` line, verbatim.
+
+### Closed-Loop Overall Verdict
+
+- `FAIL` if any non-SKIPPED Pass is `FAIL`
+- `PASS WITH WARNINGS` if no `FAIL` but ≥1 non-SKIPPED Pass is `WARNING`
+- `PASS` if all non-SKIPPED Passes are `PASS` (SKIPPED Passes do not affect the verdict)
+
+---
+
+## Part B: Design Quality Assessment
+
+### Over-Engineering Check
+
+Scan `design.md` and `tasks.md` for 5 over-engineering signals. Each signal detected must
+cite the specific design section or task.
+
+| # | Signal | How to detect | Example |
+|---|--------|--------------|---------|
+| 1 | Interface for unrequested requirements | design defines interfaces/capabilities not in spec's Requirements | spec only requires `en`/`zh-CN`, design builds a `LocaleRegistry` |
+| 2 | Unnecessary abstraction layer | single implementation gets an interface + factory + strategy | one reviewer type → `ReviewerFactory` + `ReviewerStrategy` |
+| 3 | Pre-built unused infrastructure | tasks include infrastructure not required by any spec scenario | CLI option change → builds a plugin system |
+| 4 | Config fields beyond current needs | YAML schema defines fields with no current consumer | `artifacts.language` + pre-built `artifacts.format`/`artifacts.tone` |
+| 5 | Complexity exceeding problem scale | simple problem uses heavy pattern (state machine, event bus, middleware chain) for a boolean config |
+
+**Verdict rule**:
+- 0 signals → `PASS`
+- 1-2 signals → `WARNING` (each must cite design section)
+- 3+ signals → `FAIL` (the plan is over-engineered)
+
+### Extensibility Assessment
+
+Scan `design.md` for 5 extensibility signals. Each signal detected must cite the specific
+decision or section.
+
+| # | Signal | How to detect | Example (from SpecFlow's own design D1) |
+|---|--------|--------------|----------------------------------------|
+| 1 | Namespace reservation | config uses nested key to leave room for siblings | `artifacts.language` not `artifactLanguage` |
+| 2 | Stable interface, replaceable implementation | type/interface defined clearly but no pre-built multi-impl | `ArtifactLanguage` type with `en`/`zh-CN` only |
+| 3 | Explicit Non-Goals | design has a Non-Goals section listing what's NOT done | "本变更不支持任意 BCP 47 语言" |
+| 4 | Backward-compatibility path | design describes how existing behavior stays compatible | "缺省 `artifacts.language` 解析为 `en`" |
+| 5 | Decision rationale mentions extensibility trade-off | a Decision block's rationale explicitly weighs extensibility | D1 rationale: "为未来 artifact 设置留命名空间" |
+
+**Verdict rule**:
+- 4-5 signals → `PASS`
+- 2-3 signals → `WARNING`
+- 0-1 signals → `WARNING` (the plan may be too rigid — approver should confirm extensibility was considered)
+
+### Combined Design Quality Verdict
+
+- `FAIL` if over-engineering is `FAIL`
+- `FAIL` (escalated) if over-engineering is `WARNING`/`FAIL` AND extensibility is `WARNING` — the plan is both bloated AND not extensible
+- `WARNING` if either check is `WARNING` (without the escalation condition)
+- `PASS` if both checks are `PASS`
+
+---
+
+## Part C: Implementability Assessment (7 Dimensions)
+
+Each dimension produces a verdict: `READY` | `NEEDS REFINEMENT` | `BLOCKED`.
+
+### Dimension 1: Completeness
+Scan all four artifacts for TODOs/placeholders/vague sections.
+- `READY` if no placeholders. `NEEDS REFINEMENT` if non-critical. `BLOCKED` if in spec requirements or critical decisions.
+
+### Dimension 2: Spec Alignment
+Tasks cover all spec requirements? Scope creep?
+- `READY` if full coverage, no scope creep. `NEEDS REFINEMENT` if minor gaps/creep. `BLOCKED` if a core requirement has zero tasks.
+
+### Dimension 3: Task Actionability
+Each task concrete and executable? Paths, commands, expected outputs defined?
+- `READY` if all actionable. `NEEDS REFINEMENT` if some vague. `BLOCKED` if tasks are too coarse to start.
+
+### Dimension 4: Technical Feasibility
+Design decisions achievable in the detected tech stack?
+- `READY` if all feasible. `NEEDS REFINEMENT` if a new dependency/infra is plausible but unconfirmed. `BLOCKED` if a decision is technically infeasible.
+
+### Dimension 5: Dependency Clarity
+Task dependencies and external dependencies explicit? Execution order derivable?
+- `READY` if explicit and clear. `NEEDS REFINEMENT` if implicit but inferrable. `BLOCKED` if ambiguous and unsequenceable.
+
+### Dimension 6: Architecture Consistency
+> Grounded in code reading from Pass 6. Reuse Pass 6's anchor-file findings.
+
+Design choices match the project's existing patterns:
+- **Tech stack**: plan's libraries/patterns match `package.json`/`go.mod`/etc.
+- **Directory structure**: new modules placed where siblings live (e.g., `src/core/` not `src/utils/` if existing core modules are in `src/core/`)
+- **Error handling**: plan uses the project's error pattern (e.g., `StoreError` with diagnostics, not bare `throw new Error`)
+- **Test framework**: plan's test approach matches project's framework (vitest not jest, if vitest is in use)
+- `READY` if all consistent. `NEEDS REFINEMENT` if 1-2 inconsistencies with justification. `BLOCKED` if fundamental mismatch (e.g., plan requires a framework the project doesn't use and can't easily add).
+
+### Dimension 7: Implementation Risk
+Assess risk factors that could derail implementation:
+- **Core module change**: does the plan modify high-risk modules (delta merge engine, parser, archive, validator)?
+- **Data migration**: does the change require migrating existing data formats?
+- **Concurrency**: does the change touch concurrent/transactional code?
+- **External API break**: does the change break interfaces other consumers depend on?
+- **Team tech-stack unfamiliarity**: does the plan use technologies the project doesn't already use (inferring from `package.json`/`go.mod`)?
+- `READY` if no high-risk items. `NEEDS REFINEMENT` if high-risk items exist with mitigations. `BLOCKED` if high-risk items exist with no mitigation.
+
+### Implementability Overall Verdict
+
+- `BLOCKED` if any dimension is `BLOCKED`
+- `NEEDS REFINEMENT` if no `BLOCKED` but any dimension is `NEEDS REFINEMENT`
+- `READY` if all 7 are `READY`
+
+---
+
+## Part D: AI Pre-Approval Recommendation
+
+Based on all three verdicts:
+
+| Closed-Loop | Design Quality | Implementability | Recommendation |
+|-------------|---------------|-----------------|----------------|
+| PASS | PASS | READY | **建议批准** (Recommend approval) |
+| PASS | PASS | NEEDS REFINEMENT | **有条件批准** (Conditional — fix during apply) |
+| PASS WITH WARNINGS | any non-FAIL | READY/NEEDS REFINEMENT | **有条件批准** (Conditional — acknowledge warnings) |
+| any | WARNING | any non-BLOCKED | **有条件批准** (Conditional — design quality concerns) |
+| FAIL | any | any | **退回 refine** (Return to refine) |
+| any | FAIL | any | **退回 refine** (Return to refine — over-engineered or rigid) |
+| any | any | BLOCKED | **退回 refine** (Return to refine — remove blockers) |
+
+The recommendation must include a 1-2 sentence rationale citing the specific verdicts that drove it.
+
+---
+
+## Part E: approval.md Document Structure
+
+Generate `approval.md` following this exact structure. Adapt narrative language to
+`artifacts.language`; keep protocol markers, IDs, paths, commands, and code in English.
+
+**Chapter order (implementer-first, aligned with scenario-job-compile readability)**:
+
+1. 绪论与边界 — proposal + optional explore + AI; absorbs What/Impact; **no 变更摘要 chapter**
+2. 技术方案评估 — decisions / risks / design quality
+3. 架构整体设计 — diagrams + **图要点说明** + components (before acceptance)
+4. 方案详细设计 — 设计要点 + Happy Path + 业务场景(+说明) + data/API/…
+5. 验收标准 — **after** architecture & detailed design
+6. 测试策略 → 7. 部署 → 8. 闭环 → 9. 可实施性 → 10. 审批
+
+### ⚠️ 质量红线 (Quality Gates) — 必须严格执行
+
+生成 `approval.md` 全文时下列红线**缺一不可**;违反则详细设计/接口/数据章节视为不合格,确认前必须补全。
+
+| # | 红线 | 要求 |
+|---|------|------|
+| G1 | 一图胜千言 | 任何超过 **5 行**的文字流程描述,**必须**改为 Mermaid 代码块(`sequenceDiagram` / `flowchart` / `stateDiagram-v2`),禁止长段落散文流程 |
+| G2 | 必须有「失败」示例 | §4.5 每个「新增/修改/行为扩展」接口:除成功请求/响应示例外,**必须**另附 ≥1 组**报错**请求或响应示例(如参数校验失败、租约过期、未认证);仅有错误码表、无 HTTP/正文示例 → 不合格 |
+| G3 | 必须有「数据迁移方案」 | 凡涉及 **JSON 字段形状变更**或**新增列**:必须写明**存量数据的默认值填充策略**(回填脚本 / 读时默认 / 禁止空读等);零 DDL 但改 JSON 语义同样适用 |
+| G4 | 必须有「回滚兼容」说明 | 若发布失败回滚:新代码已写入的数据,旧版代码是否能**安全跳过/忽略**?必须给出明确方案(如 `omitempty`、忽略未知字段、`schema_version` 分派、双写兼容窗口);禁止只写「回滚镜像」而无数据兼容结论 |
+
+### Style & Tone (文风要求) — 全文适用
+
+1. **通俗易懂**:面向要动手的开发同学;避免生僻英文缩写,**首次出现必须注解**(例:`DDL`(数据定义语言)、`RPC`(远程过程调用));协议字段名/路径/代码标识符保持原文。
+2. **逻辑严密**:拒绝模棱两可词 —— **禁止**使用「尽量」「大概」「一般情况下」「可能需要」「酌情」「视情况」等;应使用「**必须**」「**禁止**」「**采用 XX 方案**」「固定为…」。若确有分支,写成显式条件表(若 A → 做 X;若 B → 做 Y),不得用含糊副词搪塞。
+
+```markdown
+# 技术方案审批文档: <change-name>
+
+> 本文档由 `/specflow:approval` 基于 refine 收敛后的四件套 + 现有代码与 spec 基线生成,
+> 经 AI 7 维闭环检查、架构整体设计、方案详细设计、测试策略、部署/发布/回滚、设计质量评估与可实施性评估,供人工审批使用。
+> 生成时间: YYYY-MM-DD HH:MM | phase: refined | 产物语言: <lang> | 技术栈: <stack>
+
+---
+
+## 1. 绪论与边界 (Introduction & Boundaries)
+
+> 本章以**业务叙事**说明"为什么做、做什么、影响面、做完后如何闭环、坚决不做什么"。
+> **数据来源**:`proposal.md`(必选)+ `explore.md`(若存在且可用则吸收)+ **AI 提炼**。
+> **不再单列「变更摘要」章**:原 Why / What Changes / Impact 并入本章 1.1–1.2。
+
+### 1.1 背景与痛点 (Background & Pain Points)
+
+用一段话说明当前现状,并用 **Mermaid 现状流程图** 直观呈现,痛点节点**用红色标注**。
+
+**要求**:
+
+1. 描述当前业务/系统的实际流程(用户如何完成目标、经过了哪些步骤)
+2. 用 Mermaid `flowchart` 绘制现状流程
+3. **痛点节点用红色标注**:`classDef pain fill:#ffcccc,stroke:#cc0000,color:#000` + `:::pain` 或 `class X pain`
+4. 每个痛点一句话说明**它造成的代价**(返工/延迟/错误/成本)
+5. 痛点应可追溯到 proposal.md 的 `## Why`;若有 `explore.md`,吸收其中已确认的痛点/约束洞察(勿编造)
+
+**痛点清单**(对应图中红色节点):
+
+| 痛点 | 代价 |
+|------|------|
+| <痛点> | <代价> |
+
+### 1.2 做什么与影响面 (What & Impact)
+
+AI 从 proposal `## What Changes` / `## Impact`(及 explore 相关结论)提炼,替代原「变更摘要」章。
+
+**做什么**(按 新增/修改/移除/重命名;BREAKING 显式标注):
+
+| 类别 | 内容 | BREAKING? |
+|------|------|-----------|
+| 新增 | | |
+| 修改 | | |
+| 移除 / 重命名 | | |
+
+**影响面**:
+
+| 影响区域 | 影响等级 | 说明 |
+|---------|---------|------|
+| | 高/中/低 | |
+
+### 1.3 业务闭环与目标 (Business Loop & Goals)
+
+说明"本次变更完成后,业务如何形成闭环",并给出 **用户操作路径(User Journey)**。
+
+**要求**:
+
+1. 描述完成本次变更后,用户完成目标的完整路径
+2. 用 Mermaid `sequenceDiagram` 或 `flowchart` 绘制 User Journey
+3. 标注每一步的价值/产出
+4. Goals 应可验证,引用 **§5 验收标准**
+
+**业务目标**(可验证):
+
+| 目标 | 可验证方式(引用 §5) |
+|------|---------------------|
+| <目标> | §5 <Scenario 名> |
+
+### 1.4 非目标 (Non-Goals)
+
+**必须明确列出本次迭代坚决不做的事项,并说明不做理由**(防止需求蔓延)。
+
+1. 从 proposal.md / design.md / explore.md 的 Non-Goals 提炼,必须补充"不做理由"
+2. 若确实没有,写明 `proposal/design 未声明 Non-Goals,建议在 refine 补充边界`
+
+| 非目标 | 不做理由 |
+|--------|---------|
+| <非目标> | <理由> |
+
+---
+
+## 2. 技术方案评估 (Technical Design Review)
+
+### 2.1 现状与约束 (Context & Constraints)
+[整合 design.md Context + AI 补充的隐含约束]
+
+### 2.2 目标与非目标 (Goals & Non-Goals)
+[整合 design.md Goals/Non-Goals]
+
+### 2.3 决策评审表 (Decision Review)
+
+| 决策 | 选定方案 | 备选方案 | 理由 | 影响评估 | 状态 |
+|------|---------|---------|------|---------|------|
+| D1: <name> | <方案> | <A/B> | <理由> | <评估> | Proposed |
+
+### 2.4 风险与权衡 (Risks & Trade-offs)
+
+| 风险 | 严重等级 | 缓解措施 | 就绪度 |
+|------|---------|---------|--------|
+| <name> | 高/中/低 | <措施> | ✅/⚠️/❌ |
+
+### 2.5 设计质量评估 (Design Quality)
+
+#### 过度设计检查
+| # | 信号 | 检测到? | 证据(design/tasks 位置) |
+|---|------|--------|----------------------|
+| 1 | 为未提出的需求设计接口 | ✅是/❌否 | |
+| 2 | 不必要的抽象层 | | |
+| 3 | 预建未使用的基础设施 | | |
+| 4 | 配置项超出当前需求 | | |
+| 5 | 复杂度超出问题规模 | | |
+**过度设计结论:** PASS (0 signals) / WARNING (1-2) / FAIL (3+)
+
+#### 扩展性评估
+| # | 信号 | 检测到? | 证据(design 位置) |
+|---|------|--------|----------------|
+| 1 | 命名空间预留 | | |
+| 2 | 接口稳定,实现可替换 | | |
+| 3 | 显式 Non-Goals | | |
+| 4 | 向后兼容路径 | | |
+| 5 | 决策理由提及扩展性权衡 | | |
+**扩展性结论:** PASS (4-5) / WARNING (0-3)
+
+**设计质量总评:** PASS / WARNING / FAIL
+
+---
+
+
+## 3. 架构整体设计 (Architecture Design)
+
+> 本章回答"系统由哪些模块组成、模块间如何依赖与交互、每个模块的职责与边界是什么"。
+> 聚焦**宏观结构**;与 §4 方案详细设计(模块内部实现 / 时序)互补。
+> 质量标杆:`scenario-job-compile` §3 —— **图 + 图要点说明 + 核心组件表**。
+
+### 3.1 总体架构 (Architecture Overview)
+
+用 Mermaid 绘制 **模块依赖/分层图**(推荐),并可附加 **系统交互总览**。
+
+**绘制要求**:
+
+1. 标注变更模块(`[新增]` / `[修改]`),影响面一眼可见
+2. 边标注依赖方向或交互消息
+3. CLI/库 → `src/core/*`、`src/cli/*`;Web → 服务/组件;多仓 → 仓库/服务
+4. 图与 **§2 决策**一致
+
+**设计说明 / 图要点**(强制,紧跟每张架构图之后):
+
+用编号列表解释图中**读图关键点**(不是复述节点名),对齐标杆「设计说明(总体架构)」:
+
+1. 分层/边界怎么划、谁不直连谁
+2. 本迭代不变式(如零 DDL、双通道、一场景一作业)
+3. 复用 vs 新增的落点
+4. 与 §2 决策的对应关系
+
+若有第二张交互图,另写 **交互要点**(一段或短列表):谁感知、谁禁止直连 DB/绕过网关等。
+
+### 3.2 核心组件说明 (Core Components)
+
+| 组件 | 职责 | 边界(做什么 / 不做什么) | 依赖 | 变更类型 |
+|------|------|-------------------------|------|---------|
+| `<组件名>` | 一句话职责 | 做什么;不做什么 | 依赖的组件 | 新增/修改/不变 |
+
+**填写要求**:列出新增+修改组件;边界写「不做什么」;与 §3.1 图一一对应;边界可追溯到 §2 决策。
+
+可附 **组件边界总原则**(短列表:平台/Worker/控制台各做什么、禁止什么)。
+
+**不涉及架构变更时写**:`不涉及架构变更(单模块/单文件调整,模块边界无变化)`。
+
+### 3.3 架构一致性自检(生成后检查)
+
+- [ ] §3.1 图标注了新增/修改模块
+- [ ] **每张架构图后有「设计说明 / 图要点」**(非空编号列表)
+- [ ] §3.2 每个组件有「不做什么」边界
+- [ ] 图与表一一对应
+- [ ] 组件边界可追溯到 §2 决策
+- [ ] 未涉及时显式标注「不涉及架构变更」
+
+---
+
+## 4. 方案详细设计 (Detailed Design)
+
+> 将方案从宏观决策落到实现者可照写的细节。
+> **只呈现本变更涉及的部分**;不涉及显式写「不涉及 X」。
+> 每个元素可追溯到 **§5 验收标准**与 **§2 决策**。
+> 质量标杆:`scenario-job-compile` §4 —— **设计要点一览 → 业务时序(含设计要点说明) → 表/接口**。
+
+### 4.1 设计要点一览(强制)
+
+从 design 决策提炼实现**不可随便推翻**的要点(P1…Pn):
+
+| 编号 | 要点 | 说明 |
+|------|------|------|
+| P1 | <短名> | <一句话不变量/策略> |
+
+### 4.2 核心业务时序 · Happy Path(强制)
+
+**必须**给出主成功路径的**完整** Mermaid `sequenceDiagram`(建议 `autonumber`),覆盖主角色从发起到成功终态的端到端调用;不得用一句话替代。
+
+**结构**:
+
+1. **目的**:一句话
+2. **时序图**:Happy Path 全链路
+3. **设计要点**:图后强制说明(不变式、与 P1…Pn 对应、本图不展开的失败边界)
+
+```mermaid
+sequenceDiagram
+  autonumber
+  %% Happy Path — 成功路径完整时序
+```
+
+**设计要点**:
+
+- …
+
+### 4.3 业务场景时序(强制有说明)
+
+对每个关键业务场景输出同构小节(对齐标杆「业务流程 A/B/C…」):
+
+#### 场景 X · `<名称>`
+
+1. **目的**
+2. **时序/状态/流程开**(Mermaid `sequenceDiagram` / `flowchart` / `stateDiagram-v2`)
+3. **设计要点**(强制 — 禁止有图无说明;可用列表或小表)
+
+至少覆盖本变更的核心分支(如失败策略、幂等、兼容缺省、计划 vs 调试等)。纯单步无分支时可写:`不涉及多业务场景(主路径已由 §4.2 Happy Path 覆盖)`——但仍须保留 §4.2。
+
+### 4.4 数据结构 / 数据模型变更 (Data Structures)
+
+**适用范围**:涉及持久化、状态存储、数据模型的变更。纯 CLI/库项目若无数据库,覆盖配置结构 / 状态文件 / 缓存结构 / YAML schema 等"数据模型"(走下方「非库表路径」)。
+
+> **DB 技能路由(先于起草)**:执行 `prompts/approval/database-guidance.md`。  
+> - **命中** `mysql` / `postgresql` / `oracle`(及确需时的 redis/es):`Read`  
+>   `skills/database/<stack>/SKILL.md` 与路由表中的 DDL/索引/JSON 参考,用其惯例补强类型、引擎、字符集、索引与 Gotchas。  
+> - **未命中**(`dbStack=none`):不硬套某厂商 skill,**交给大模型**按下方 SpecFlow 硬门槛生成。  
+> - 技能是 **Read 知识包**,不是 MCP tool;不得用「调 tool」替代读文件。  
+> - 在总则「DDL 来源」旁注明:`skills/database/<stack>`(本地) 或 `LLM-fallback`。
+
+> **质量硬门槛(库表路径)**:只要本变更读写/依赖任何数据库表(含"零 DDL、只改读写语义"),§4.4 **必须**按下列结构输出,不得用一句话带过、不得省略 ER / DDL / 字段说明表。参考质量标杆:`scenario-job-compile` 类审批文档的「表与数据设计」章(总则结论表 → ER → 表一览 → 逐表 DDL+字段表 → 非表字段与回滚)。
+
+#### A. 库表路径(MySQL / PostgreSQL / SQLite 等关系库)——强制结构
+
+按以下小节**顺序**生成。缺任一强制项 → 视为详细设计质量不合格,在确认摘要中报告用户并标记 `[待 refine 澄清]` 或补全后再写入。
+
+##### 4.4.1 总则与本迭代结构变更结论
+
+用结论表一眼说清本迭代对库结构做什么(即使结论是「零迁移」也要写明):
+
+| 项 | 结论 |
+|----|------|
+| 数据库迁移(脚本/工具名) | 有 / **本迭代零迁移** |
+| 新建表 | 表名列表 / **无** |
+| 新增 / 修改 / 删除列 | 列清单 / **无** |
+| 新增索引 | 索引清单 / **无** |
+| DDL 来源 | 仓库基线路径 或 本迭代新增 |
+| DB 技能 | `skills/database/<stack>`(本地) / `LLM-fallback` |
+
+紧接一段 **本迭代变更语句** 代码块:
+
+- 有变更:给出可执行的 `CREATE` / `ALTER` / `DROP`(与下方逐表 DDL 一致)。
+- **零变更**:显式写「无(明确不执行)」,并可用注释列出**禁止合入**的反例 `ALTER`/`CREATE`(防止实现时偷偷加列)。
+
+##### 4.4.2 ER 图(核心实体关系)——强制
+
+用 Mermaid `erDiagram` 画出**本变更涉及的核心实体**(新增 + 修改 + 本迭代强依赖的既有表),标注:
+
+1. 实体名(= 表名)与**中文表意**(可用实体注释或紧随其后的说明)。
+2. 关系基数(`||--o{` / `}o--||` 等)与关联键语义(如「作业 1 — N 逐步结果」)。
+3. 每个实体列出 **3–8 个关键属性**(主键、业务主键、外键、本迭代读写的关键列);勿堆砌全量字段(全量在字段说明表)。
+4. 与 §2 决策、§3 组件一致:图中实体必须在表一览与逐表章节出现。
+
+```mermaid
+erDiagram
+  PARENT_TABLE ||--o{ CHILD_TABLE : "1:N 业务关系说明"
+  PARENT_TABLE {
+    char uid PK "业务主键"
+    varchar name "名称"
+  }
+  CHILD_TABLE {
+    char uid PK
+    char parent_uid FK
+    int step_order "本迭代幂等键之一"
+  }
+```
+
+**图说明(强制,紧跟 ER 图)**:用表格描述图中每张表,提升可读性 —— 不是重复 ER 属性列表,而是回答「这张表是干什么的、本迭代怎么动」:
+
+| 表名 | 中文名 | 职责(一句话) | 结构 | 本迭代动作 |
+|------|--------|--------------|------|------------|
+| `parent_table` | … | … | 不变 / 新增 / 改列 | 只读 / 写入 / 新建 |
+
+##### 4.4.3 逐表详设(强制骨架)
+
+对表一览中的**每一张表**输出同构小节 `#### \`table_name\`(中文名)`,顺序固定:
+
+1. **本迭代动作**:只读 / 写入(既有路径) / 新建 / 改结构(列清单) —— 一句话 + 关键不变量(如幂等键)。
+2. **本迭代变更语句**:`无` 或完整 `ALTER`/`CREATE` 片段(可执行)。
+3. **DDL(完整建表语句)** —— **硬门槛**:
+   - 必须是完整 `CREATE TABLE ...`(即使本迭代零 DDL,也给出**现网/目标**完整表定义,便于实现者对照)。
+   - **必须含存储引擎与字符集**(MySQL 示例:`ENGINE=InnoDB DEFAULT CHARSET=utf8mb4` [`COLLATE=...` 若项目有约定则写出];PostgreSQL 写明 schema / 关键扩展约定;SQLite 可省略 ENGINE,但须完整列定义与约束)。
+   - 含 PRIMARY KEY、UNIQUE、KEY/INDEX、必要时列 `COMMENT` / 表级 `COMMENT`。
+   - 首行注释标明 DDL 来源(迁移文件路径或「本迭代新增」)。
+4. **字段说明表** —— 强制列:
+
+| 字段名称 | 字段类型 | 是否有默认值 | 字段说明 | 本迭代用法 |
+|----------|----------|--------------|----------|------------|
+
+   - 「本迭代用法」写清:读 / 写 / 不涉及 / **固定赋值**(`job_type=scenario`)等;本迭代相关列可加粗语义说明。
+   - 索引在 DDL 中已声明即可;若新增索引,在变更语句与字段表或表下短注中说明**支撑的查询**。
+5. 若表含 JSON / 大字段契约:另开子节给出**非表列的 JSON 形状**(字段/类型/必填/说明),与参考文档 `runtime_payload` 写法一致。
+
+##### 4.4.4 非表字段、数据迁移与回滚兼容
+
+| 项 | 说明 |
+|----|------|
+| 协议/计算字段(不落库) | 如列表聚合计数;说明计算方式 |
+| **存量数据默认值填充策略**(G3) | JSON 形状变更或新增列时**必须**填写:回填 SQL/脚本、读路径默认值、是否允许空、上线顺序(先兼容读再写新形状等) |
+| 结构回滚 | 有 DDL → 回滚脚本要点;无 DDL →「无结构可回滚,回滚应用即可」 |
+| **回滚数据兼容**(G4) | 新版本已写入行/JSON,旧版本代码能否安全忽略未知字段或旧 `schema_version`?写明机制(`omitempty` / 忽略未知键 / version 分派等) |
+| 数据保留 | 已写入行是否保留、是否需清洗 |
+
+**零结构变更且不改 JSON 语义时**:在上表写明「无存量填充;无新形状回滚兼容问题」,不得整节留空。
+
+#### B. 库表路径 —— 质量自检(生成后必过)
+
+- [ ] 有总则结论表 + 本迭代变更语句(零变更也显式写「无」)
+- [ ] 有 Mermaid `erDiagram`,且图后有「表名/中文名/职责/结构/本迭代动作」说明表
+- [ ] 每张涉及表均有:动作、变更语句、**完整 CREATE TABLE(含引擎与字符集)**、字段说明表
+- [ ] 字段说明表含「本迭代用法」列;幂等键 / 外键 / 枚举合法值写清
+- [ ] **G3**:JSON 变更或新增列时有存量默认值填充策略;否则显式写「无存量填充」
+- [ ] **G4**:回滚数据兼容有明确方案或显式「无新旧互读问题」
+- [ ] 无「仅文字描述表结构、无 DDL」或「DDL 缺 ENGINE/CHARSET」的偷懒写法
+- [ ] 零 DDL 迭代禁止假装「不涉及数据库」—— 只要读写表,仍走库表路径并展示现网 DDL
+
+#### C. 非库表路径(CLI / 库 / 配置 / 状态文件)
+
+无关系库表时,覆盖配置结构 / 状态文件 / YAML schema / 缓存键:
+
+| 元素 | 内容 |
+|------|------|
+| 配置或状态结构 | 键路径、类型、默认值、生效时机 |
+| 约束 | 合法值、校验失败行为 |
+| 迁移 | 缺省兼容、是否改写存量文件 |
+
+示例:
+```yaml
+# specflow/config.yaml 新增
+artifacts:
+  language: zh-CN   # en | zh-CN,缺省 en
+```
+
+**完全不涉及任何持久化/配置结构时写**:`不涉及数据库变更(纯逻辑/CLI 变更,无持久化数据模型)`。
+
+#### D. 库表 DDL 示例(完整度标杆)
+
+```sql
+-- 来源:migrations/example/ddl/orders.sql(或:本迭代新增)
+CREATE TABLE `orders` (
+  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部自增主键',
+  `uid` CHAR(36) NOT NULL COMMENT '业务主键',
+  `project_id` VARCHAR(64) NOT NULL,
+  `status` VARCHAR(32) NOT NULL DEFAULT 'pending',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_uid` (`uid`),
+  KEY `idx_project_status` (`project_id`, `status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  COMMENT='订单';
+```
+
+### 4.5 接口设计 (Interface Design)
+
+**适用范围**:暴露 API / RPC / CLI 命令 / 跨模块函数接口的变更(含「协议不变但本迭代新消费」)。
+**项目类型适配**:Web/服务 → HTTP(+RPC);CLI → commander 等命令参数;库 → 导出函数签名。
+
+> **质量硬门槛(对外/跨端接口路径)**:只要本变更新增、修改、行为扩展或**新消费**对外接口,§4.5 **必须**按下列结构输出。参考质量标杆:`scenario-job-compile`「接口设计」章(总览与约定 → 接口清单 → 通用错误码 → 逐接口字段表+HTTP 示例 → 调用关系)。禁止只有路径名、无字段表、无错误约定、无请求/响应示例。
+
+#### A. 对外/跨端接口路径——强制结构
+
+##### 4.5.1 总览与约定
+
+**1) 调用方与通道**(多通道时必填;单通道也建议写明鉴权):
+
+| 通道 | 路径前缀 / 入口 | 调用方 | 鉴权 |
+|------|-----------------|--------|------|
+| 例:控制台 API | `/api/v1/...` | 前端经网关 | 用户/项目身份 |
+| 例:内部 API | `/internal/v1/...` | Worker/服务 | 租约/服务身份 |
+
+**2) 本迭代接口清单**(强制总表,编号稳定便于交叉引用):
+
+| 编号 | 接口 | 变更类型 | 应用场景 |
+|------|------|----------|----------|
+| I1 | <短名> | **新增** / **修改** / **行为扩展**(请求体不变) / **不变**(本迭代消费) | 谁在什么时候用 |
+
+变更类型约定(优化自标杆文档,强制统一用语):
+
+| 类型 | 含义 | §4.5 展开深度 |
+|------|------|---------------|
+| 新增 | 新路径或新 RPC | 完整展开(字段+示例+错误) |
+| 修改 | 请求/响应形状变化(加字段、改语义) | 完整展开,并标明**本迭代变更点** |
+| 行为扩展 | 消息形状不变,服务端认新取值/新分支 | 完整展开侧重点:行为差异与错误;可注明「请求/响应消息不变」 |
+| 不变(本迭代消费) | 协议不动,本迭代开始依赖 | 可精简:场景+协议+关键字段/查询约定+为何本迭代需要;仍建议有成功响应要点 |
+| 不变(不展开) | 已落地且本迭代不改、不新消费 | **清单可一句带过或不列入**,勿重复粘贴既有文档 |
+
+**3) 通用错误码约定**(强制;按项目现网风格映射):
+
+| 错误类别 / 状态 | 典型 HTTP 或退出码 | 含义(本迭代) |
+|-----------------|-------------------|--------------|
+| 参数非法 | 400 / 退出码 1 | … |
+| 未找到 | 404 | … |
+| 无权限 / 未认证 | 403 / 401 | … |
+| 冲突 / 前置失败 | 409 / 412 | … |
+| 内部错误 | 500 | … |
+
+**约定**(按项目裁剪,至少覆盖命名与错误风格):
+
+1. **字段命名**:与现网一致(如 JSON 蛇形 `project_id`;proto `json_name`;CLI kebab-case 等)。
+2. **错误风格**:业务错误进 `message` / 状态详情;**禁止**「HTTP 200 + 业务错误码」混用(除非项目现网已是该风格且 design 显式沿用)。
+3. **幂等 / 终态语义**:若存在上报类接口,写清「成功 ≠ 资源终态」等不变量(对齐 §2 决策)。
+4. **兼容缺省**:可选字段缺省时的兼容行为写进字段表「默认」列。
+5. **与流程对齐**:接口编号可被 §4.2/§4.3 时序与 §6 测试引用。
+
+##### 4.5.2 逐接口详设(强制骨架)
+
+对清单中每个需展开的编号 `In`,输出同构小节 `#### In · <短名>(<变更类型>)`:
+
+1. **元信息表**(强制):
+
+| 项 | 内容 |
+|----|------|
+| 应用场景 | 谁、在什么用户动作/系统时机下调用 |
+| 协议 | 方法 + 路径(或 CLI 命令 / 导出函数签名) |
+| Content-Type / 编码 | 如 `application/json`(若适用) |
+| 对应 RPC / 内部名 | 若有(可写暂定名 +「实现时与 OpenAPI/proto 对齐」) |
+| 鉴权 | 本接口鉴权要点(可引用通道表) |
+| 本迭代变更 | 一句话(新增字段 / 行为扩展 / 不变仅消费 …) |
+
+2. **参数表**(有则分节:路径参数 / Query / 请求体 / CLI flags):
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+
+   - 合法值枚举、别名归一、与表字段差异(如「API 有 `step_uid`,表无此列」)写在「说明」。
+   - 互斥参数(二选一)在说明或表下用引用块写清。
+
+3. **请求示例**(强制至少 1 个主路径成功请求):
+   - Web:` ```http ` 完整请求行 + 头 + JSON 正文
+   - CLI:` ```text ` 或 shell 调用示例
+   - 库:调用伪代码 / TypeScript 签名调用示例
+
+4. **成功响应字段表** + **成功响应示例**(强制)
+
+5. **失败示例**(质量红线 G2 — 强制):每个「新增/修改/行为扩展」接口**必须**另附 ≥1 组报错示例(完整 HTTP 或等价),覆盖典型失败之一:参数校验失败、鉴权/租约失败、资源不存在、前置条件不满足等。示例正文须与错误表一致。
+
+6. **错误表**(强制;条件 → 状态/退出码 → 说明):
+
+| 条件 | 状态 / 退出码 | 说明 |
+|------|---------------|------|
+
+7. **处理顺序 / 合同**(可选但推荐):多步服务端合同用编号列表;与 §4.2/§4.3 流程、§4.4 落库对齐。
+
+##### 4.5.3 调用关系(推荐)
+
+用短文本或 Mermaid 概括调用方如何串起 `I1…In`(主路径一条线即可),便于实现与联调对照。
+
+```text
+调用方A: I3 → I1 → I4 → I7
+调用方B: … → I5 → I6
+```
+
+#### B. 接口路径 —— 质量自检(生成后必过)
+
+- [ ] 有通道/鉴权表(或多通道说明)+ 本迭代接口清单(编号+变更类型+场景)
+- [ ] 有通用错误码约定 + 命名/错误风格约定
+- [ ] 每个「新增/修改/行为扩展」接口具备:元信息、字段表、成功请求/响应示例、**失败示例(G2)**、错误表
+- [ ] 「不变·本迭代消费」接口至少有场景+协议+关键消费约定,不假装不存在
+- [ ] 无「只有路径、无字段/无示例/无错误」的偷懒写法;示例与字段表一致
+- [ ] 接口编号可被 §4.2/§4.3 流程、§6 测试引用
+
+#### C. CLI / 库项目路径(无 HTTP 时)
+
+无 HTTP 时仍用「清单 + 逐接口」骨架,将「协议」换为命令/导出签名;错误码换为退出码或抛错类型。示例:
+
+```text
+specflow init --artifact-language <language>
+  入参: language?: string   可选,默认 'en';合法值 en | zh-CN | zh(zh 别名→zh-CN)
+  出参: { status: 'initialized' | 'already_initialized' | 'updated_assets', message: string }
+  错误码:
+    E_INVALID_LANGUAGE   退出码 1 — 不支持的 language 值
+    E_PARITY_STRICT      退出码 1 — 资产生成后 parity 校验失败
+```
+
+**完全不涉及接口变更时写**:`不涉及接口变更(内部实现调整,无对外/跨模块接口变化)`。
+
+### 4.6 核心算法 / 逻辑说明 (Core Logic)
+
+**适用范围**:有非平凡算法或数据处理逻辑的变更。
+| 元素 | 内容 |
+|------|------|
+| 输入输出 | 输入数据结构、输出数据结构 |
+| 处理步骤 | 逐步逻辑(编号列表) |
+| 复杂度 | 时间/空间复杂度,边界条件 |
+
+**不涉及非平凡算法时写**:`不涉及非平凡算法(逻辑简单,无复杂数据处理)`。
+
+### 4.7 配置与运行环境 (Configuration & Runtime)
+
+**适用范围**:新增配置项、环境变量、运行时依赖的变更。
+| 元素 | 内容 |
+|------|------|
+| 配置项 | 名称、类型、默认值、生效时机 |
+| 环境变量 | 新增变量、语义 |
+| 运行时依赖 | 新增依赖、版本、用途 |
+
+**不涉及配置变更时写**:`不涉及配置或运行环境变更`。
+
+### 4.8 兼容性与迁移 (Compatibility & Migration)
+
+**适用范围**:破坏性变更、JSON/列变更、或任何「新版本写入、旧版本仍可能读」的发布窗口。
+
+| 元素 | 内容 |
+|------|------|
+| 旧行为 → 新行为 | 映射表(禁止含糊「基本兼容」) |
+| 迁移路径 | 存量用户如何升级、步骤顺序 |
+| **存量默认值填充**(G3) | 与 §4.4.4 一致;JSON/新列必须写明填充策略 |
+| **回滚数据兼容**(G4) | 发布失败回滚后:新代码已写数据,旧代码是否安全忽略/跳过?必须给出方案(`omitempty` / 忽略未知字段 / `schema_version` 等) |
+| 应用回滚 | 镜像/包回退步骤 |
+
+**完全无兼容风险时写**:`不涉及破坏性变更(向后兼容);无新形状写入,回滚仅回退应用即可` —— 仍须一句话点明「无新旧数据互读问题」。
+
+### 详细设计质量自检(生成后检查)
+
+- [ ] 有 §4.1 设计要点一览(P1…Pn)
+- [ ] 有 §4.2 Happy Path **完整**时序图 + 设计要点说明
+- [ ] 每个 §4.3 业务场景均有图 + **设计要点说明**(无裸图)
+- [ ] **G1**:超过 5 行的文字流程已改为 Mermaid,无长散文流程
+- [ ] 每个详细设计元素可追溯到 §5 Requirement/Scenario 与 §2 决策
+- [ ] 涉及数据/接口的均非留空;不涉及类别显式标注
+- [ ] **§4.4**:ER + DDL + 字段说明;若 JSON/新列变更则有**存量填充策略(G3)**与回滚数据兼容(G4)
+- [ ] **§4.5**:通道/清单/错误码 + 字段/成功示例 + **失败示例(G2)** + 错误表
+- [ ] **§4.8**:回滚兼容结论明确(或显式声明无新旧数据互读问题)
+- [ ] **文风**:无「尽量/大概/一般情况下」等含糊词;生僻缩写首次已注解
+- [ ] 若无法写出实现级细节,标记 `[待 refine 澄清: <元素>]`
+
+---
+
+## 5. 验收标准 (Acceptance Criteria)
+
+[按 capability 分组,完整列出所有 Requirement + Scenario,每个 Scenario 3 级可测试性标注]
+
+### 5.1 Capability: <name>
+[Delta 操作类型: ADDED / MODIFIED / REMOVED / RENAMED]
+
+#### Requirement: <name>
+<描述>
+
+| Scenario | WHEN | THEN | 可测试性 | 说明 |
+|----------|------|------|---------|------|
+| <name> | <条件> | <期望> | ✅ 功能可测试 / ⚠️ 文档可测试 / ❌ 不可测试 | <原因 if ⚠️/❌> |
+
+---
+
+## 6. 测试策略 (Test Strategy)
+
+> 本章从"§5 验收标准可不可测"升级为"**用分层测试证明方案正确**"。它回答:
+> 每个验收标准(WHEN/THEN)由哪一层测试覆盖、用什么工具、目标是证明什么。
+> **选择性呈现**:只列出本变更实际需要的测试层级;不涉及的层级显式标注"不涉及"。
+
+### 6.1 分层测试矩阵
+
+| 测试层级 | 覆盖对象 | 工具/框架 | 目标(证明什么) | 覆盖的验收标准 |
+|---------|---------|----------|---------------|---------------|
+| 单元测试 | 核心函数/类/模块内部逻辑 | <框架,如 vitest/jest/pytest> | 逻辑正确、边界处理 | 引用 §5 的 Scenario |
+| 集成测试 | 模块间交互、接口契约、外部依赖 | <框架> | 模块协作正确、契约一致 | 引用 §5 的 Scenario |
+| 验收测试 | spec 的 WHEN/THEN 行为 | <E2E/CLI 测试> | 逐 Scenario 验证用户可见行为 | §5 全部核心 Scenario |
+| 回归测试 | 主 specs 基线 + 既有行为 | <框架> | 不破坏已有功能 | 主 specs(§5 基线对照) |
+| 性能测试 | 关键路径/高并发 | <如 k6/jmeter/bench> | NFR 性能目标达成 | NFR 章节 |
+| 安全测试 | 认证/授权/输入边界 | <SAST/渗透> | 无已知漏洞 | NFR 安全目标 |
+| 兼容性测试 | 多平台/多版本/多浏览器 | <如 playwright> | 跨环境一致 | 兼容性 Requirement |
+
+**填写要求**:
+
+1. 每个测试层级**映射到 §5 验收标准**(引用具体 Scenario 名)—— 这是"测试策略与验收标准闭环"的关键
+2. 每个层级标注**工具/框架**(呼应 full-stack-skills 的"阶段→技能映射":测试阶段→test-writer/playwright/pytest)
+3. **目标要可验证**("证明 P95 < 200ms" 而非 "测性能")
+4. 新增测试 vs 修改既有测试要区分
+
+**示例**:
+
+| 测试层级 | 覆盖对象 | 工具/框架 | 目标(证明什么) | 覆盖的验收标准 |
+|---------|---------|----------|---------------|---------------|
+| 单元测试 | `artifact-language.ts` 的 normalize/require/validate | vitest | `zh`→`zh-CN` 别名、非法值拒绝 | "Normalize the Chinese CLI alias" |
+| 集成测试 | `init` 命令 + config 写入 + 资产生成 | vitest + tmpdir | init 后 config.yaml 含 `artifacts.language` | "Initialize a Simplified Chinese project" |
+| 验收测试 | `specflow init --artifact-language zh-CN` 全流程 | CLI 测试 | 端到端产物符合预期 | "Reject an unsupported language" 等 |
+| 回归测试 | 既有 init 行为(无语言参数) | vitest | 缺省仍为 en,不破坏既有 | "Initialize without an explicit language" |
+
+### 6.2 测试环境与数据
+
+| 项 | 说明 |
+|----|------|
+| 测试环境 | 单元/集成用本地 tmpdir;验收用隔离环境(如 CI) |
+| 测试数据 | 需要的 fixture/seed 数据、中文/英文样本 |
+| 并行/隔离 | 测试间是否可并行、是否需要隔离(文件锁/独立目录) |
+| 覆盖率目标 | 核心模块目标覆盖率(如 ≥80%) |
+
+### 6.3 测试策略自检
+
+- [ ] 每个 §5 验收标准至少被一个测试层级覆盖(闭环)
+- [ ] 每个测试层级有工具、有可验证目标
+- [ ] 既有行为有回归测试保护(对应 Pass 7 基线)
+- [ ] 新增测试与修改既有测试已区分
+
+**不涉及测试变更时写**:`不涉及测试变更(纯文档/配置变更,无行为逻辑需要测试)`。
+
+---
+
+## 7. 部署/发布/回滚方案 (Deployment & Release)
+
+> 本章回答"方案实现后如何上线、如何发布、出问题如何回滚、上线后如何监控"。
+> **选择性呈现**:对有运行系统的项目必须;对纯库/CLI/文档项目可显式标注"不涉及运行时部署"。
+
+### 7.1 部署方案 (Deployment)
+
+| 项 | 方案 |
+|----|------|
+| 部署目标 | 部署到哪里(生产/预发/多环境)、依赖的基础设施 |
+| 部署方式 | 镜像/包发布/代码部署/配置下发;CI 流水线步骤 |
+| 部署顺序 | 依赖部署的先后(如先迁移 DB 再部署应用) |
+| 配置管理 | 新配置项如何在各环境生效、密钥管理 |
+| 环境差异 | dev/staging/prod 的环境差异与处理 |
+
+### 7.2 发布策略 (Release Strategy)
+
+| 项 | 方案 |
+|----|------|
+| 发布方式 | 蓝绿/金丝雀/滚动/直接替换;理由 |
+| 发布窗口 | 是否需停机窗口、灰度比例 |
+| 兼容性 | 新旧版本共存期间的兼容(如 API 版本化、DB 兼容) |
+
+### 7.3 回滚方案 (Rollback)
+
+| 项 | 方案 |
+|----|------|
+| 回滚触发条件 | 什么情况下回滚(错误率/指标阈值) |
+| 回滚方式 | 镜像回退/代码回退/数据回滚;自动或手动 |
+| 回滚的数据一致性 | 数据迁移的回滚(若有)、缓存/队列的清理 |
+| 回滚验证 | 回滚后如何确认恢复正常 |
+
+### 7.4 监控与可观测性 (Monitoring & Observability)
+
+| 项 | 方案 |
+|----|------|
+| 关键指标 | 上线后需监控的指标(错误率/延迟/资源) |
+| 日志/追踪 | 日志规范、链路追踪 |
+| 告警 | 告警阈值与负责人 |
+
+### 7.5 部署方案自检
+
+- [ ] 部署目标/方式/顺序明确
+- [ ] 发布策略与兼容性说明
+- [ ] 回滚触发条件、方式、数据一致性、验证明确
+- [ ] 上线后监控指标与告警明确
+
+**不涉及运行时部署时写**:`不涉及运行时部署(纯库/CLI/文档项目,无服务上线,变更通过包发布/版本发布交付)`。
+
+---
+
+## 8. 闭环性检查 (Closed-Loop Verification)
+
+> **写法要简练**:内部仍跑完 Pass 1–7,但写入本文只保留下表。  
+> - `PASS` / `SKIPPED`:「关键证据」一句话即可(不必贴大表)。  
+> - `WARNING` / `FAIL`:「关键证据」写清缺口(文件/Requirement/Scenario/任务 ID),最多 2–3 条要点。  
+> - **禁止**为每个 Pass 再开长小节、禁止重复贴总评表。
+
+| Pass | 检查项 | 结论 | 关键证据(一句话;⚠️/❌ 可列 2–3 条要点) |
+|------|--------|------|--------------------------------------|
+| 1 | 需求闭环 proposal↔specs | ✅/⚠️/❌ | |
+| 2 | 方案闭环 design↔specs | ✅/⚠️/❌ | |
+| 3 | 规格闭环 场景/可测试性/delta | ✅/⚠️/❌ | |
+| 4 | 实施闭环 tasks↔specs | ✅/⚠️/❌ | |
+| 5 | 风险闭环 缓解/BREAKING | ✅/⚠️/❌ | |
+| 6 | 代码落地性 锚点/结构/栈 | ✅/⚠️/❌/⊘ | |
+| 7 | 基线对照 主 specs | ✅/⚠️/❌/⊘ | |
+
+**整体闭环性:** PASS / PASS WITH WARNINGS / FAIL
+
+判定:任一 ❌ → FAIL;无 ❌ 但有 ⚠️ → PASS WITH WARNINGS;全 ✅(⊘ 不计)→ PASS。
+
+---
+
+## 9. 可实施性评估 (Implementability Assessment)
+
+| 评估维度 | 结论 | 说明 |
+|---------|------|------|
+| 完整性 | READY / NEEDS REFINEMENT / BLOCKED | |
+| 规格对齐 | | |
+| 任务可执行性 | | |
+| 技术可行性 | | |
+| 依赖明确性 | | |
+| 架构一致性 | | <基于 Pass 6 代码读取> |
+| 实施风险 | | <核心模块/数据迁移/并发/外部接口> |
+
+**可实施性总评:** READY / NEEDS REFINEMENT / BLOCKED
+
+---
+
+## 10. 审批意见 (Approval Decision)
+
+### 10.1 AI 预审建议
+
+**建议:** 建议批准 / 有条件批准 / 退回 refine / 拒绝
+**理由:** <1-2 句话,引用具体 verdict>
+
+### 10.2 人工审批签字栏
+
+| 角色 | 姓名 | 审批结论 | 日期 | 意见 |
+|------|------|---------|------|------|
+| 技术负责人 | | □ 批准 □ 退回 □ 拒绝 | | |
+| 产品负责人 | | □ 批准 □ 退回 □ 拒绝 | | |
+| 架构师 | | □ 批准 □ 退回 □ 拒绝 | | |
+
+> 审批结论填写说明:批准 → 可执行 `/specflow:apply`;退回 → 执行 `/specflow:refine` 修复后重新审批;拒绝 → 废弃本次 change。
+
+---
+
+## 附录 A: 产物溯源
+
+| 章节 | 数据来源 | 处理方式 |
+|------|---------|---------|
+| 绪论与边界 | proposal.md + explore.md(可选) + design Non-Goals | AI 提炼;痛点图 + What/Impact + User Journey + 非目标;**无变更摘要章** |
+| 技术方案评估 | design.md | 决策表 + 风险表 + 设计质量 |
+| 架构整体设计 | design + 锚点代码 + specs | Mermaid 图 + **图要点说明** + 组件边界表;追溯 §2 |
+| 方案详细设计 | design + specs + 锚点 + 现网 DDL/API | 设计要点 + Happy Path + 业务场景(+说明) + 数据/接口等;追溯 §5+§2 |
+| 验收标准 | specs/**/*.md | **置于设计之后**;3 级可测试性 |
+| 测试策略 | §5 验收标准 + 项目测试栈 | 分层矩阵映射验收标准 |
+| 部署/发布/回滚 | §2 决策 + 运行环境 | 部署/发布/回滚/监控 |
+| 闭环性检查 | 四件套 + 锚点 + 主 specs | 内部跑 Pass 1–7;**正文只输出一张结论表**(PASS 一句话;⚠️/❌ 要点化) |
+| 可实施性评估 | tasks + design + specs + 代码 | AI 推理 |
+| 审批意见 | 三重 verdict | AI 预审 + 人工签字栏 |
+```
+
+### Generation Rules
+
+1. **§1 绪论 must be truthful and precise**: every pain point in the current-flow diagram
+   must be grounded in proposal.md `## Why` / design.md Context / confirmed explore.md
+   (do not invent pains). Absorb What Changes + Impact into §1.2 (no separate 变更摘要
+   chapter). Every User Journey step must trace to a §5 acceptance criterion. Every
+   Non-Goal must state its "不做理由".
+
+2. **Acceptance Criteria (§5) is exhaustive and placed after design**: include every
+   Requirement and Scenario from every delta spec. Do not summarize or omit. Do NOT place
+   acceptance before architecture/detailed design.
+
+3. **Pass 6 evidence must cite real code**: when Pass 6 is ⚠️/❌, §8「关键证据」must cite
+   actual anchor paths and concrete findings. PASS may be one line
+   (e.g. `锚点 N 个均存在,结构可扩展`). Greenfield → `⊘` with the SKIPPED reason.
+
+4. **Pass 7 evidence must cite baseline specs**: when ⚠️/❌, cite capability/requirement
+   names compared. PASS → one line; no baseline → `⊘`.
+
+5. **Over-engineering evidence must cite design/tasks location**: "Signal 2 detected in
+   `design.md` § D3, which defines a `ReviewerFactory` for a single reviewer type" — not
+   just "over-engineered".
+
+6. **Language policy + Style & Tone**: narrative follows `artifacts.language`; protocol
+   markers, IDs, paths, commands, code stay in original form. Apply Style & Tone hard
+   rule (通俗 + 首次注解缩写 + 禁止含糊词) to all human-readable narrative.
+
+7. **No file modification**: this prompt only generates `approval.md`. Do not modify the
+   four artifacts, project code, or main specs.
+
+8. **Sign-off table is empty**: human sign-off fields must be blank.
+
+9. **§4.4 database section quality (hard rule)**: if the change reads/writes any
+   relational table (including zero-DDL semantic-only changes), §4.4 MUST include:
+   (a) structure-change conclusion table + explicit change SQL (or explicit「无」),
+   (b) Mermaid `erDiagram` of core entities + a table-description legend
+   (表名/中文名/职责/结构/本迭代动作),
+   (c) per-table complete `CREATE TABLE` with storage engine + charset (MySQL:
+   `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4` …), and
+   (d) per-table field description table with「本迭代用法」.
+   Do NOT substitute prose-only schema descriptions. Do NOT omit ENGINE/CHARSET on
+   MySQL DDL. Zero-DDL iterations still show current-baseline DDL — never claim
+   「不涉及数据库」when tables are in the read/write path.
+
+10. **§4.5 interface section quality (hard rule)**: if the change adds, modifies,
+    behavior-extends, or newly consumes external/cross-service interfaces, §4.5 MUST
+    include: (a) caller/channel + auth overview, (b) numbered interface inventory with
+    change type (新增/修改/行为扩展/不变·本迭代消费), (c) common error-code mapping and
+    naming/error-style conventions, (d) per-interface meta table, field tables
+    (name/type/required/default/description), at least one success request example and
+    success response example, **(e) ≥1 failure request/response example (G2)**, and an
+    error-condition table. Do NOT ship path-only stubs without fields/examples/errors.
+    Unchanged APIs that this iteration does not consume need not be fully re-documented.
+
+11. **§3 architecture diagram key points (hard rule)**: every architecture Mermaid diagram
+    MUST be followed by a numbered「设计说明 / 图要点」list (boundary/invariants/reuse) —
+    not a mere restatement of node names. Component table alone is not enough.
+
+12. **§4 Happy Path + scenario design notes (hard rule)**: §4.1 design-points table, §4.2
+    complete Happy Path `sequenceDiagram`, and each §4.3 business scenario MUST include
+    post-diagram「设计要点」explanations. Bare diagrams without notes are a quality failure.
+
+13. **Quality Gates G1–G4 (hard rule)**:
+    - **G1**: any process description longer than 5 prose lines MUST be a Mermaid
+      `sequenceDiagram` / `flowchart` / `stateDiagram-v2` (no long prose flows).
+    - **G2**: every added/modified/behavior-extended interface in §4.5 MUST include ≥1
+      failure request/response example (validation failure, lease expiry, etc.), not only
+      an error-code table.
+    - **G3**: JSON shape changes or new columns MUST document存量数据默认值填充策略 in
+      §4.4.4 / §4.8.
+    - **G4**: MUST state rollback data compatibility — whether old code can safely
+      ignore/skip data written by new code (`omitempty`, unknown-field ignore,
+      `schema_version`, etc.). "Rollback the image" alone is insufficient.
+
+14. **Style & Tone (hard rule)**: plain language for implementers; obscure English
+    abbreviations MUST be glossed on first use. Ban weasel words「尽量」「大概」
+    「一般情况下」「可能需要」「酌情」「视情况」; use「必须」「禁止」「采用 XX 方案」
+    or explicit if/then tables instead.
+
+15. **§8 closed-loop must be concise (hard rule)**: write exactly one summary table
+    (Pass | 检查项 | 结论 | 关键证据). Do NOT open seven Pass subsections or a second
+    summary table. PASS/SKIPPED → one short phrase; WARNING/FAIL → ≤3 concrete bullets.
+
+16. **§4.4 database skill routing**: before drafting relational DDL, run
+    `prompts/approval/database-guidance.md`. On stack hit, Read local
+    `skills/database/<stack>/…` (in-repo, no remote fetch) and apply idioms; on miss,
+    LLM-only SpecFlow §4.4 rules. Do not invent MCP tools; do not `npx skills add`.
+    Record `skills/database/<stack>` or `LLM-fallback` in the §4.4.1 总则 table.
+