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

package/prompts/approval/generate.md

@@ -1,1596 +0,0 @@
-<!-- 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)
-- `projectMode` (`greenfield` | `brownfield`) and `stackCoverage` (`complete` | `partial` | `missing`)
-- Tech Stack Intake gate completed when greenfield or stack dimensions are missing
-  (user confirmed 前端 / 后端 / 数据库与缓存 / 基础设施, or marked「不涉及」)
-- `uiInScope` resolved; when yes, FE 五元组 confirmed (or marked pending refine)
-- Anchor files extracted from **each in-scope repo** when `multi_repo.enabled` (Stage 1b)
-- Optional: `specflow/specs/` baseline exists (for Pass 7)
-- When multi-repo: `multi_repo.document_mode` + (`primary_repo` if unified) confirmed by user
-
-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.
-
-When **`multi_repo.enabled=true`**, read **`prompts/approval/multi-repo-guidance.md`** first.
-Load four artifacts **from every repo** in `multi_repo.repos[]` before analysis. Unified mode
-merges cross-repo content into **one** document stored under **`primary_repo`**; per_repo mode
-writes **separate** `approval.md` per repo (see §G).
-
----
-
-## 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. 架构整体设计 — 架构图 + **图要点说明** + 组件(置于验收之前)
-4. 方案详细设计 — 设计要点 + Happy Path + 业务场景(+说明) + 数据/接口/**前端(若有 UI)**…
-5. 验收标准 — **可选**(须先询问用户;选「要」则放在设计之后;选「不要」则整章省略)
-6. 测试策略 — 默认输出(若无 §5,矩阵改为映射 delta specs 的 Requirement/Scenario)
-7. 部署/发布/回滚 — **可选**(须先询问用户)
-8. 闭环性检查 — **可选**(须先询问用户;内部仍跑 Pass 1–7,仅「要」时写入正文表)
-9. 可实施性评估 → 10. 审批意见(**仅人工签字栏**;AI 预审只在对话中反馈,不写入文档)
-
-### 可选章节门禁(写入前必须询问)
-
-在写入 `approval.md` 之前,向用户明确询问(可合并进确认摘要):
-
-```text
-以下章节是否写入审批文档?(默认均可选「不要」以保持精简)
-- [ ] §5 验收标准(从 specs 展开全部 Requirement/Scenario)
-- [ ] §7 部署/发布/回滚方案
-- [ ] §8 闭环性检查表(Pass 1–7 结论表)
-```
-
-- 用户选「要」→ 按下方骨架生成该章。
-- 用户选「不要」→ **整章省略**(不要写「不涉及…」占位段)。
-- 未得到明确答复前,**不要**写入文件。
-
-### ⚠️ 质量红线 — 必须严格执行
-
-生成 `approval.md` 时,下列红线**缺一不可**;违反则详细设计/接口/数据相关章节视为不合格,确认写入前必须补全。
-
-| 编号 | 红线名称 | 要求 |
-|------|----------|------|
-| G1 | 一图胜千言 | 任何超过 **5 行**的文字流程描述,**必须**改为 Mermaid 图(`sequenceDiagram` / `flowchart` / `stateDiagram-v2`),禁止用长段落散文写流程 |
-| G2 | 必须有失败示例 | §4.5 清单中**每个**接口(含**不变**):除成功请求与成功响应示例外,**还必须**附 ≥1 组**失败**请求或响应示例(如参数校验失败、租约过期、未认证)。只有错误码表、没有具体 HTTP/正文示例 → 不合格 |
-| G3 | 必须有数据迁移/填充方案 | 凡涉及 **JSON 字段形状变更**或**新增列**:必须写明**存量数据的默认值填充策略**(回填脚本 / 读时默认值 / 禁止空读等)。即使本迭代不做表结构变更、只改 JSON 语义,同样适用 |
-| G4 | 必须有回滚数据兼容说明 | 若发布失败需要回滚:新版本已经写入的数据,旧版本代码能否**安全跳过或忽略**?必须给出明确方案(例如忽略未知字段、按数据版本分派、兼容窗口双写等)。禁止只写「回滚镜像/回滚应用」却不说明数据兼容结论 |
-| G5 | 前端须有页面/路由清单 | 当 `uiInScope=yes`:§4.6 **必须**给出本迭代页面/路由清单与栈五元组(Framework/Styling/State/UI kit/FE testing)。禁止只写「用 React」 |
-| G6 | 关键页须有空/加载/错态 | 当 `uiInScope=yes`:每个关键 `Page · …` **至少**覆盖空态 / 加载 / 错误之一,并标明依赖的 §4.5 接口编号 |
-
-### 文风要求 — 全文适用
-
-1. **通俗易懂**:面向要动手实现的开发同学;避免生僻英文缩写,**首次出现必须中文注解**(例:DDL(数据定义语言)、RPC(远程过程调用))。
-2. **叙述用可读中文,禁止「代码腔」堆砌**:
-   - §2.1 现状与约束、§3 架构说明、§4 设计要点等**正文/列表**,用业务与模块语言书写(例:「调度侧编译目前只认接口用例类型,运行时打成扁平的 HTTP 请求规格」)。
-   - **禁止**把路径、函数名、类型名、结构体字段当作句子主干连写(反例:`compileOne` in `internal/scheduler/...` only accepts `ref_type=api_case`…)。
-   - 若确需锚定实现位置:同一条约束最多用括号**点名一次**可读定位(模块中文名 + 必要时一个路径或符号),或把路径/符号放到表格「证据」列;细节接口形状仍放在 §4.5 的字段表与示例中。
-   - Mermaid、DDL、HTTP 示例、字段表中的协议名/列名保持技术原文(不受本条限制)。
-3. **逻辑严密**:拒绝模棱两可 —— **禁止**「尽量」「大概」「一般情况下」「可能需要」「酌情」「视情况」;应使用「**必须**」「**禁止**」「**采用 XX 方案**」「固定为…」。若有分支,写成显式条件表(若 A → 做 X;若 B → 做 Y)。
-
-```markdown
-# 技术方案审批文档: <change-name>
-
-> 本文档由 `/specflow:approval` 基于 refine 收敛后的四件套 + 现有代码与 spec 基线生成,
-> 经 AI 闭环检查与设计质量/可实施性评估(结论在对话中反馈),并含架构与详细设计等章节,供人工审批使用。
-> 生成时间: 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)
-
-> 用**可读中文**归纳现状与硬约束(含「本迭代禁止…」类红线)。禁止代码腔堆砌;需要锚点时见上文「文风要求」第 2 条。  
-> **0→1 绿场**:可写「尚无存量业务代码;约束来自用户确认的技术选型与组织规范」。
-
-[整合 design.md Context + AI 从锚点代码提炼的隐含约束 — 写成中文要点列表]
-
-### 2.2 技术选型 (Tech Stack Selection)
-
-> **何时必须有本章节**:  
-> - `projectMode=greenfield`(从 0 到 1),或  
-> - 四件套未写清且本变更需要的维度缺失(前端 / 后端 / 数据库与缓存 / 基础设施)。  
-> **来源优先级**:用户在 Tech Stack Intake 门禁中的确认 **>** design 决策表 **>** 仓库信号。  
-> **禁止**在未提问、未确认时由模型臆造全栈。  
-> 若本变更为棕地小改且选型沿用现网 → 可写一行「沿用现网栈:<摘要>」并跳过详表。
-
-**选型总表**(绿场或补选型时强制):
-
-| 方向 | 选定方案 | 备选(若有) | 选择理由 | 来源 |
-|------|----------|------------|----------|------|
-| 前端 | Framework / Styling / State / UI kit / FE testing | | | 用户确认 / design / 沿用现网 / 不涉及 |
-| 后端 | | | | |
-| 数据库与缓存 | | | | |
-| 基础设施 | | | | |
-| 其它(消息/搜索/… ) | | | | |
-
-> 前端行在 `uiInScope=yes` 时**必须**写成五元组(见 `frontend-guidance.md`);禁止只填「React」。
-
-将关键选型同步写入下方 **§2.4 决策评审表**(如 D-FE / D-BE / D-DB / D-Infra)。
-
-### 2.3 目标与非目标 (Goals & Non-Goals)
-[整合 design.md Goals/Non-Goals]
-
-### 2.4 决策评审表 (Decision Review)
-
-| 决策 | 选定方案 | 备选方案 | 理由 | 影响评估 | 状态 |
-|------|---------|---------|------|---------|------|
-| D1: <name> | <方案> | <A/B> | <理由> | <评估> | Proposed |
-
-### 2.5 风险与权衡 (Risks & Trade-offs)
-
-| 风险 | 严重等级 | 缓解措施 | 就绪度 |
-|------|---------|---------|--------|
-| <name> | 高/中/低 | <措施> | ✅/⚠️/❌ |
-
-### 2.6 设计质量评估 (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 —— **图 + 图要点说明 + 核心组件表**。
-
-> **项目约定(先于起草)**:执行 `prompts/approval/project-conventions-guidance.md`,`topic=architecture`。  
-> 懒加载 Read 项目 architecture skill/rule/docs(跨 IDE 路径见该路由)。  
-> **优先级**:项目约定 + 锚点代码 **>** 通用架构常识。将硬边界/禁令写入图要点(可读中文)。  
-> 总则式标注:在图要点第 1 条或组件表注记「项目约定: <path|未发现>」。
-
-### 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 技能(先于起草,固定顺序)**:  
-> 1. 执行 `prompts/approval/project-conventions-guidance.md`,`topic=database` — Read 项目 DB 约定(若有)。  
-> 2. 执行 `prompts/approval/database-guidance.md` — 探测 `dbStack` 并 Read SpecFlow `{ide}/specflow/guidance/database/<stack>/`(或包内回退)。  
-> 3. Read 现网 DDL/迁移/锚点(Pass 6)。  
-> **优先级**:项目约定 + 现网 DDL **>** SpecFlow DB guidance **>** LLM。  
-> 不得「invoke `/mysql`」;总则须同时填写「项目约定」「DB 技能」「DDL 来源」。
-
-> **质量硬门槛(库表路径)**:只要本变更读写/依赖任何数据库表(含"零 DDL、只改读写语义"),§4.4 **必须**按下列结构输出,不得用一句话带过、不得省略 ER / DDL / 字段说明表。参考质量标杆:`scenario-job-compile` 类审批文档的「表与数据设计」章(总则结论表 → ER → 表一览 → 逐表 DDL+字段表 → 非表字段与回滚)。
-
-> **大纲 / 标题层级(硬门槛 — 防 TOC 爆炸)**:Markdown 预览大纲**只允许**下列标题进入目录;「DDL」「字段说明」「JSON 形状」等**禁止**写成 `####`/`#####`/`######`,一律用 **加粗标签** + 正文/代码块/表格。
-
-```text
-### 4.4 数据结构 / 数据模型变更
-├── #### 4.4.1 总则与本迭代结构变更结论
-├── #### 4.4.2 ER 图(核心实体关系)
-├── #### 4.4.3 逐表详设
-│   ├── ##### `table_a`(中文名)     ← 每张表仅此一级标题
-│   └── ##### `table_b`(中文名)
-└── #### 4.4.4 非表字段、数据迁移与回滚兼容
-```
-
-表内固定顺序用加粗标签(不是标题):`**本迭代动作**` → `**本迭代变更语句**` → `**DDL(现网/目标)**` → `**字段说明**` →(可选)`**JSON 形状 · <字段名>**`。
-
-#### A. 库表路径(MySQL / PostgreSQL / SQLite 等关系库)——强制结构
-
-按以下小节**顺序**生成。缺任一强制项 → 视为详细设计质量不合格,在确认摘要中报告用户并标记 `[待 refine 澄清]` 或补全后再写入。
-
-##### 4.4.1 总则与本迭代结构变更结论
-
-用结论表一眼说清本迭代对库结构做什么(即使结论是「零迁移」也要写明):
-
-| 项 | 结论 |
-|----|------|
-| 数据库迁移(脚本/工具名) | 有 / **本迭代零迁移** |
-| 新建表 | 表名列表 / **无** |
-| 新增 / 修改 / 删除列 | 列清单 / **无** |
-| 新增索引 | 索引清单 / **无** |
-| DDL 来源 | 仓库基线路径 或 本迭代新增 |
-| 项目约定 | 实际 Read 路径(可多个用 `; `) / **未发现** |
-| DB 技能 | `{ide}/specflow/guidance/database/<stack>` / `skills/database/<stack>`(fallback) / `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` …;PostgreSQL 写明 schema;SQLite 可省略 ENGINE)。
-   - 含 PRIMARY KEY、UNIQUE、KEY/INDEX、必要时列/表 `COMMENT`;首行注释标明 DDL 来源。
-4. **字段说明**:紧跟一张表(强制列):
-
-| 字段名称 | 字段类型 | 是否有默认值 | 字段说明 | 本迭代用法 |
-|----------|----------|--------------|----------|------------|
-
-   - 「本迭代用法」写清:读 / 写 / 不涉及 / **固定赋值**等;索引已在 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
-- [ ] 总则含「项目约定」列(路径或「未发现」)+「DB 技能」列+「DDL 来源」
-- [ ] 若探测到项目 DB 约定,正文已体现其硬禁令;否则确认摘要 WARNING
-
-#### 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 等命令参数;库 → 导出函数签名。
-
-> **项目约定(先于起草)**:执行 `prompts/approval/project-conventions-guidance.md`,`topic=api`;再执行 **`prompts/approval/api-guidance.md`**(分层、RPC 锁名、proto/OpenAPI 可生成包)。  
-> 懒加载项目 API/错误码/鉴权/契约约定。有 UI 时 **§4.6** 另跑 `topic=frontend` + `frontend-guidance.md`
-> (勿把页面树塞进 §4.5)。  
-> **优先级**:项目约定 + 现网 OpenAPI/proto **>** SpecFlow §4.5 骨架 **>** LLM。  
-> 在 §4.5.1 总览用一行注明「项目约定: <path|未发现>」。
-
-> **质量硬门槛(对外/跨端接口路径)**:本迭代**列入 §4.5 清单**的每个接口(含**协议不变**、**本迭代消费**、**行为扩展**等),§4.5 **必须**按下列完整结构输出,**禁止**因「无协议变更」而精简、省略字段表/示例/错误约定。参考质量标杆:`scenario-job-compile`「接口设计」章(总览与约定 → 接口清单 → 通用错误码 → 逐接口字段表+HTTP 示例 → 调用关系)。禁止只有路径名、无字段表、无错误约定、无请求/响应示例。
-
-> **大纲 / 标题层级(硬门槛 — 防 TOC 爆炸)**:大纲**只允许**下列标题;「请求体字段」「请求示例」「响应示例」「错误」等**禁止**写成标题,一律 `**加粗**`。
-
-```text
-### 4.5 接口设计
-├── #### 4.5.1 总览与约定          ← 通道 / 清单 / 通用错误码 均用加粗小标题,不进更深目录
-├── #### 4.5.2 逐接口详设
-│   ├── ##### I1 · <短名>(变更类型)  ← 每个接口仅此一级标题
-│   └── ##### I2 · …
-└── #### 4.5.3 调用关系
-```
-
-接口内固定顺序用加粗标签:`**元信息**` → `**请求体字段**`(或路径/Query/CLI flags) → `**请求示例**` → `**成功响应字段**` → `**响应示例(成功)**` → `**响应示例(失败)**`(G2) → `**错误**` →(可选)`**处理顺序**`。
-
-#### A. 对外/跨端接口路径——强制结构
-
-##### 4.5.1 总览与约定
-
-**1) 调用方与通道**(多通道时必填;单通道也建议写明鉴权):
-
-| 通道 | 路径前缀 / 入口 | 调用方 | 鉴权 |
-|------|-----------------|--------|------|
-| 例:控制台 API | `/api/v1/...` | 前端经网关 | 用户/项目身份 |
-| 例:内部 API | `/internal/v1/...` | Worker/服务 | 租约/服务身份 |
-
-**2) 本迭代接口清单**(强制总表,编号稳定便于交叉引用):
-
-| 编号 | 接口 | 变更类型 | 应用场景 |
-|------|------|----------|----------|
-| I1 | <短名> | **新增** / **修改** / **行为扩展**(请求体不变) / **不变**(本迭代消费) | 谁在什么时候用 |
-
-变更类型约定(优化自标杆文档,强制统一用语):
-
-| 类型 | 含义 | §4.5 展开深度 |
-|------|------|---------------|
-| 新增 | 新路径或新 RPC | 完整展开(字段+示例+错误) |
-| 修改 | 请求/响应形状变化(加字段、改语义) | 完整展开,并标明**本迭代变更点** |
-| 行为扩展 | 消息形状不变,服务端认新取值/新分支 | 完整展开;在「本迭代变更」写明行为差异;可注明「请求/响应消息不变」 |
-| 不变(本迭代消费) | 协议/消息形状不动,本迭代开始依赖或调用 | **完整展开**(与新增/修改同骨架);「本迭代变更」写「协议不变,本迭代消费」;禁止「详见 OpenAPI/既有文档」代替字段表与示例 |
-| 不变(协议不变) | 本迭代仍调用,协议与现网一致 | **完整展开**(同上);字段/示例须与现网 OpenAPI/proto/锚点对齐,可标注「与现网一致」 |
-
-> **清单规则(硬)**:本迭代**不调用、不消费**的接口 **不列入** §4.5 清单。**一旦列入清单,无论变更类型是否为「不变」,均须按 §4.5.2 完整骨架输出**,不得精简、不得只写路径、不得跳过示例。
-
-> **分层规则(硬 — 防 B2 类混写)**:同一业务链上的 **Worker HTTP(L2)**、**平台 gRPC+HTTP 绑定(L3)**、**东向 client RPC(L4)** 必须是 **独立 `In`**,各自完整展开。禁止在 L2 写满 HTTP 后,用「内部经 I6/I7 调用」一行代替 L4 详设。见 `api-guidance.md` §1。
-
-**2b) 契约面分层(合订/三端推荐)**:
-
-| 层 | 面 | 清单要求 |
-|----|-----|----------|
-| L1 | 控制台 HTTP | 字段表 + 示例 + 错误 |
-| L2 | Worker→Gateway HTTP | OpenAPI schema 草案 + **完整** work 鉴权头示例 |
-| L3 | Gateway 转码 RPC | **冻结** RPC 名 + proto 字段号 + `google.api.http` + **Gateway 注册点** |
-| L4 | 平台 `client/<svc>/` RPC | 完整骨架;不变亦须字段表+示例,禁止 stub |
-
-**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 测试引用。
-6. **RPC 锁名(硬)**:新增/修改 gRPC **禁止**「暂定」「如 XxxRpc」「实现时命名/对齐」。须写死 `package.ServiceMethod`,并在决策表或 §4.5 元信息一致。见 `api-guidance.md` §2。
-7. **错误映射唯一(硬)**:条件 → **唯一** gRPC code → **唯一** HTTP;禁止「403/409(与 progress 同类)」「或现网」。
-
-##### 4.5.2 逐接口详设(强制骨架)
-
-对清单中**每个**编号 `In`(含**不变**类型),输出同构小节 `##### In · <短名>(<变更类型>)`(**仅此一级**进大纲;其下**禁止**再开 `####`/`#####`/`######`)。顺序固定,标签一律 `**加粗**`:
-
-1. **元信息**(强制表):
-
-| 项 | 内容 |
-|----|------|
-| 应用场景 | 谁、在什么用户动作/系统时机下调用 |
-| 协议 | 方法 + 路径(或 CLI 命令 / 导出函数签名) |
-| Content-Type / 编码 | 如 `application/json`(若适用) |
-| 对应 RPC / 内部名 | **冻结**全名(例 `scheduler.SubmitStepResult`);proto 路径;**禁止**暂定/如/实现时 |
-| 鉴权 | 本接口鉴权要点(可引用通道表) |
-| Gateway 注册 | 新增 HTTP 绑定时:**文件+函数名**或 ProtoSets 路径(禁止只写「含新绑定」) |
-| 本迭代变更 | 一句话(新增字段 / 行为扩展 / 不变仅消费 …) |
-
-2. **请求体字段**(有则写;路径参数 / Query / CLI flags 用同级加粗标签分块,如 `**Query 参数**`,仍**不要**升为标题):
-
-| 字段 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-
-   - 合法值枚举、别名归一、与表字段差异写在「说明」;互斥参数用引用块。
-
-3. **请求示例**(强制 ≥1 主路径成功请求):Web 用完整 `http` 块;CLI/库用等价示例。多场景时用加粗副标区分,例:`**请求示例(场景)**` / `**请求示例(接口用例 · 兼容旧客户端)**` —— **不是**标题。
-
-4. **成功响应字段** + **响应示例(成功)**(强制)。
-
-5. **响应示例(失败)**(质量红线 G2 — 强制):清单中**每个**接口 **≥1** 组报错示例(完整 HTTP 或等价);「不变」接口亦须给出典型失败场景(如参数非法、未认证、资源不存在);副标可写失败原因,例:`**响应示例(失败 · 无启用步)**`,仍**不是**标题。
-
-6. **错误**(强制表:条件 → 状态/退出码 → 说明):
-
-| 条件 | 状态 / 退出码 | 说明 |
-|------|---------------|------|
-
-7. **处理顺序**(可选):多步服务端合同用编号列表;与 §4.2/§4.3、§4.4 对齐。
-
-8. **Proto / OpenAPI 契约包**( **新增** 或 **修改 HTTP 绑定** 的 RPC — 硬):在接口小节末尾用加粗标签 `**Proto 草案**` / `**OpenAPI 指针**` 输出:
-   - proto:`rpc` 全名 + `message` 字段号表 + `google.api.http` 原文
-   - Gateway:与现网同类 RPC **同一注册点**的文件/函数,或 ProtoSets 条目
-   - Worker:OpenAPI 路径 + schema 字段与 L3 一致;HTTP 示例含 **全部** 必填头
-   - status/enum **闭合**,与现网 ingest 校验一致(禁止「等」、禁止逐步 ingest 写 `running` 除非同步改白名单)
-   详见 `api-guidance.md` §3。
-
-##### 4.5.3 调用关系(推荐)
-
-用短文本或 Mermaid 概括调用方如何串起 `I1…In`(主路径一条线即可),便于实现与联调对照。
-
-```text
-调用方A: I3 → I1 → I4 → I7
-调用方B: … → I5 → I6
-```
-
-#### B. 接口路径 —— 质量自检(生成后必过)
-
-- [ ] 有通道/鉴权表(或多通道说明)+ 本迭代接口清单(编号+变更类型+场景)
-- [ ] 有通用错误码约定 + 命名/错误风格约定
-- [ ] **分层**:L2 Worker HTTP / L3 RPC / L4 东向 RPC 各有独立 `In`,无「内部调用」stub
-- [ ] **RPC 已冻结**:无暂定/如/实现时;新增 RPC 含 proto 字段号 + http option + Gateway 注册点
-- [ ] 清单中**每个**接口(含**不变**)具备:元信息、字段表、成功请求/响应示例、**失败示例(G2)**、错误表
-- [ ] **不变**接口未因「无协议变更」而省略字段表/示例;内容与现网契约或锚点一致
-- [ ] 无「只有路径、无字段/无示例/无错误」的偷懒写法;示例与字段表一致
-- [ ] 接口编号可被 §4.2/§4.3 流程、§6 测试引用
-- [ ] **大纲干净**:§4.5 目录仅为 `4.5.1–4.5.3` + 各 `##### In · …`;**无**「请求体字段 / 请求示例 / 响应示例 / 错误」标题节点
-
-#### 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 前端 / UI 设计 (Frontend / UI Design)
-
-**适用范围**:本变更含控制台 / Web / App UI / 页面 / 路由 / 组件(见 `frontend-guidance.md` → `uiInScope`)。  
-**不涉及时**:整章省略,或在详细设计自检处写一行 `不涉及前端/UI 变更` —— **禁止**臆造页面树。
-
-> **项目约定 + IDE 落地规约 + FE 路由(先于起草)**:  
-> 1. 执行 `project-conventions-guidance.md`,`topic=frontend`。  
-> 2. 执行 `prompts/approval/frontend-guidance.md` §3 — **强制**扫描 IDE skills/rules
->    (`.cursor` / `.claude` / `.agents`)与落地文档(组件/路由/状态/表单/样式/a11y/测试/lint);
->    合计 ≤5 文件;`Read` 路径,禁止 `invoke`。  
-> 3. Read 现网路由/布局/API client 锚点(Pass 6 深度:仅文件)。  
-> **优先级**:项目约定 + IDE skills/rules + 现网 UI **>** §4.6 骨架 **>** LLM。
-
-> **质量硬门槛**:`uiInScope=yes` 时必须输出下列结构。禁止只有「用 React/Vue」一句话;禁止把完整目录树堆进 §2.1。  
-> **大纲 / 标题层级**:只允许 `#### 4.6.1–4.6.5` + `##### Page · <短名>`;「空态/加载/错误/依赖接口」等用 `**加粗**`。
-
-```text
-### 4.6 前端 / UI 设计
-├── #### 4.6.1 总则与本迭代结论
-├── #### 4.6.2 信息架构与路由
-├── #### 4.6.3 关键页面 / 组件详设
-│   └── ##### Page · <短名>
-├── #### 4.6.4 状态与数据获取
-└── #### 4.6.5 视觉与验证回路
-```
-
-#### 4.6.1 总则与本迭代结论
-
-| 项 | 结论 |
-|----|------|
-| Surface | Web / Mobile / Desktop / 混合 |
-| Framework | |
-| Styling / 设计系统 | |
-| State | |
-| UI kit | |
-| FE testing | |
-| 本迭代页面 | 列表 / **无新增页(仅改组件)** |
-| 项目约定 | config + 中立 docs 路径 / **未发现** |
-| IDE skills/rules | `.cursor`/`.claude`/`.agents` 下实际 Read 路径 / **未发现** |
-| 本迭代不涉及 | 例:无设计系统重建 / 无 RN |
-
-栈五元组须与 §2.2 前端行、Intake 确认一致。  
-落地禁令(组件库、禁止全局 CSS、表单校验库等)用可读中文写入本节与 §2.1;路径放本表。
-
-#### 4.6.2 信息架构与路由
-
-| 路由 / 入口 | 页面短名 | 对应 Journey / Scenario | 本迭代动作 |
-|-------------|----------|-------------------------|------------|
-| | | | 新增 / 修改 / 不动 |
-
-可用简短 Mermaid `flowchart` 画页面关系(G1:超 5 行散文改图)。
-
-#### 4.6.3 关键页面 / 组件详设
-
-对清单中每个需展开的页面输出 `##### Page · <短名>`(**仅此一级**进大纲):
-
-1. **目的**:一句话用户目标  
-2. **关键组件**:布局 / 列表 / 表单 / 抽屉…(中文名;边界「不做什么」)  
-3. **依赖接口**:§4.5 `In` 编号(无接口则写「无」并说明纯本地态)  
-4. **状态要点**:进入页需要的数据;提交后的成功态  
-5. **空态 / 加载 / 错误**(G6 — 至少一项写清文案或行为;推荐三项都写)  
-6. **权限 / 可见性**(若有)
-
-#### 4.6.4 状态与数据获取
-
-| 类别 | 方案 | 说明 |
-|------|------|------|
-| Server state | 例:React Query / SWR / 仅页面内 fetch | |
-| Client state | 例:Zustand / 组件本地 | |
-| 表单与校验 | 例:Zod + RHF / 现网表单库 | |
-| 错误呈现 | Toast / 页内 Alert / 错误边界 | 须用户可理解 |
-
-#### 4.6.5 视觉与验证回路
-
-- **响应式 / a11y**:本迭代必须覆盖的断点与可达性抽查(有则写;无则「沿用现网,本迭代不改视觉体系」)。  
-- **Visual Loop**:Generate → Render → Inspect → Refine(写清本项目的 preview / 截图 / 浏览器检查方式)。  
-- **命令**:`dev` / `test` / `e2e` / `browser check`(来自约定或 Intake;未知则 `[待 refine 澄清: FE 验证命令]`)。  
-- **AI builder**(若用):导出、本地可构建、密钥、退出计划 — 一小节即可。
-
-#### 前端路径 —— 质量自检
-
-- [ ] `uiInScope=yes` 时有 §4.6.1 五元组 + 页面清单(**G5**) + **项目约定/IDE skills/rules** 列  
-- [ ] 每个关键 Page 有依赖接口与空/加载/错态(**G6**)  
-- [ ] 页面可被 §4.2/§1.3 引用;接口编号对齐 §4.5  
-- [ ] 状态/表单/测试命令与已 Read 的 IDE/仓规约一致(有则引用路径)  
-- [ ] 大纲仅为 `4.6.1–4.6.5` + `Page · …`;无「空态」等标题节点  
-- [ ] 正文可读中文,无代码腔目录树堆砌,无整段粘贴 skill 原文
-
-### 4.7 核心算法 / 逻辑说明 (Core Logic)
-
-**适用范围**:有非平凡算法或数据处理逻辑的变更。
-| 元素 | 内容 |
-|------|------|
-| 输入输出 | 输入数据结构、输出数据结构 |
-| 处理步骤 | 逐步逻辑(编号列表) |
-| 复杂度 | 时间/空间复杂度,边界条件 |
-
-**不涉及非平凡算法时写**:`不涉及非平凡算法(逻辑简单,无复杂数据处理)`。
-
-### 4.8 配置与运行环境 (Configuration & Runtime)
-
-**适用范围**:新增配置项、环境变量、运行时依赖的变更。
-| 元素 | 内容 |
-|------|------|
-| 配置项 | 名称、类型、默认值、生效时机 |
-| 环境变量 | 新增变量、语义 |
-| 运行时依赖 | 新增依赖、版本、用途 |
-
-**不涉及配置变更时写**:`不涉及配置或运行环境变更`。
-
-### 4.9 兼容性与迁移 (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(若有 §5)或 delta specs 中的同名条目,以及 §2 决策
-- [ ] 涉及数据/接口的均非留空;不涉及类别显式标注
-- [ ] **§4.4**:ER + DDL + 字段说明;若 JSON/新列变更则有**存量填充策略(G3)**与回滚数据兼容(G4)
-- [ ] **§4.5**:通道/清单/错误码 + 字段/成功示例 + **失败示例(G2)** + 错误表
-- [ ] **§4.6**(若 `uiInScope`):五元组 + 页面清单(**G5**) + 空/加载/错态(**G6**) + Visual Loop
-- [ ] **§4.4/§4.5/§4.6 大纲**:目录仅含规定小节 + 表名/`In`/`Page`;字段/示例/DDL/空态等均为加粗标签
-- [ ] **§4.9**:回滚兼容结论明确(或显式声明无新旧数据互读问题)
-- [ ] **文风**:无「尽量/大概/一般情况下」等含糊词;生僻缩写首次已注解
-- [ ] 若无法写出实现级细节,标记 `[待 refine 澄清: <元素>]`
-
----
-
-## 5. 验收标准 (Acceptance Criteria)
-
-> **可选章**:仅当用户在写入前确认「要 §5」时输出;否则整章省略。  
-> 若输出:放在架构与详细设计之后;按 capability 完整列出 Requirement + Scenario,并做 3 级可测试性标注。
-
-[仅在用户确认需要时展开]
-
-### 5.1 Capability: <name>
-[Delta 操作类型: ADDED / MODIFIED / REMOVED / RENAMED]
-
-#### Requirement: <name>
-<描述>
-
-| Scenario | WHEN | THEN | 可测试性 | 说明 |
-|----------|------|------|---------|------|
-| <name> | <条件> | <期望> | ✅ 功能可测试 / ⚠️ 文档可测试 / ❌ 不可测试 | <原因 if ⚠️/❌> |
-
----
-
-## 6. 测试策略 (Test Strategy)
-
-> 本章回答:用分层测试证明方案正确。  
-> **与 §5 的关系**:若文档含 §5,矩阵必须映射到具体 Scenario;若用户未要 §5,则映射到 delta specs 中的 Requirement/Scenario **名称**(仍须可追溯,不得空泛)。
-> **选择性呈现**:只列出本变更实际需要的测试层级;不涉及的层级显式标注"不涉及"。
-
-### 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 修改既有测试要区分
-5. 若 `uiInScope=yes`:矩阵须覆盖组件/E2E 或 browser 检查,并与 §4.6.5 Visual Loop
-   (Generate→Render→Inspect→Refine)命令一致
-
-**示例**:
-
-| 测试层级 | 覆盖对象 | 工具/框架 | 目标(证明什么) | 覆盖的验收标准 |
-|---------|---------|----------|---------------|---------------|
-| 单元测试 | `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)
-
-> **可选章**:仅当用户确认「要 §7」时输出;否则整章省略。  
-> 若输出:回答如何上线、如何发布、出问题如何回滚、上线后如何监控。纯库/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)
-
-> **可选章**:仅当用户确认「要 §8」时输出;否则整章省略。  
-> 无论是否写入文档,**内部分析仍必须跑完 Pass 1–7**,并在对话确认摘要中给出整体闭环结论。  
-> 若写入本文:只保留下表 —— `PASS`/`SKIPPED` 一句话;`WARNING`/`FAIL` 最多 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)
-
-> **禁止**在本文写入「AI 预审建议」小节。AI 预审结论(建议批准 / 有条件批准 / 退回 refine / 拒绝 + 理由)只在**对话中**向用户反馈。  
-> 本文仅保留人工签字栏。
-
-### 10.1 人工审批签字栏
-
-| 角色 | 姓名 | 审批结论 | 日期 | 意见 |
-|------|------|---------|------|------|
-| 技术负责人 | | □ 批准 □ 退回 □ 拒绝 | | |
-| 产品负责人 | | □ 批准 □ 退回 □ 拒绝 | | |
-| 架构师 | | □ 批准 □ 退回 □ 拒绝 | | |
-
-> 审批结论填写说明:批准 → 可执行 `/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(若有)或 delta specs + 项目测试栈 | 分层矩阵可追溯 |
-| 部署/发布/回滚 | §2 决策 + 运行环境 | **可选**;用户确认后输出 |
-| 闭环性检查 | 四件套 + 锚点 + 主 specs | 内部必跑 Pass 1–7;正文表**可选** |
-| 可实施性评估 | tasks + design + specs + 代码 | AI 推理写入文档 |
-| 审批意见 | 人工签字 | **仅签字栏**;AI 预审只在对话反馈 |
-```
-
-### 生成规则 (Generation Rules)
-
-1. **§1 绪论须真实准确**:现状流程图中的每个痛点必须有据于 `proposal.md` 的 `## Why`、`design.md` Context 或已确认的 `explore.md`(禁止臆造痛点)。将 What Changes + Impact 吸收进 §1.2(不设单独的「变更摘要」章)。每条 User Journey 步骤须能追溯到 §5 验收标准(**当 §5 纳入时**),否则追溯到具名 delta-spec 的 Requirement/Scenario。每条 Non-Goal 须写明「不做理由」。
-
-2. **§5 / §7 / §8 为可选章节(硬规则)**:写入 `approval.md` 前,须询问用户是否纳入验收标准、部署/发布/回滚、闭环性检查表。仅当用户明确选择「要」时才写入对应章节;选择「不要/省略」时整章删除(禁止用「不涉及」占位填充)。§5 纳入时须穷尽(覆盖每个 Requirement/Scenario),且放在 §3/§4 之后。
-
-3. **Pass 6 证据须引用真实代码**:当 Pass 6 为 ⚠️/❌ 时,若 §8 纳入,其「关键证据」须引用实际锚点路径与具体发现;**对话**确认摘要中亦须呈现相同证据。PASS 可一行带过(例:`锚点 N 个均存在,结构可扩展`)。绿场 → `⊘` 并注明 SKIPPED 原因。
-
-4. **Pass 7 证据须引用基线 specs**:当 ⚠️/❌ 时,须引用所比对的能力/requirement 名称(§8 纳入时写入正文,**对话中始终呈现**)。PASS → 一行带过;无基线 → `⊘`。
-
-5. **过度设计证据须引用 design/tasks 位置**:例:「Signal 2 见于 `design.md` § D3,为单一 reviewer 类型定义了 `ReviewerFactory`」——禁止只写「过度设计」。叙述优先可读中文;路径/符号放证据列。
-
-6. **语言策略与文风**:叙述遵循 `artifacts.language`。须遵守文风硬规则:通俗、缩写首次注解、禁止含糊词、**禁止正文代码腔**(路径/函数名堆砌 → 可读中文;协议字段/DDL/HTTP 示例除外)。协议标记(`Requirement:` / `WHEN` / `THEN`)保持原文形式。
-
-7. **禁止修改其他文件**:本 prompt 仅生成 `approval.md`。不得修改四件套、项目代码或主 specs。
-
-8. **签字栏须留空**:人工签字字段必须空白。
-
-8b. **AI 预审不入库(硬规则)**:禁止将「AI 预审建议」/§10.1 建议写入 `approval.md`。建议批准/有条件批准/退回 refine/拒绝 + 理由**仅在对话**确认摘要中交付。文档 §10 **仅**含人工签字表。
-
-9. **§4.4 数据库章节质量(硬规则)**:若变更读/写任何关系表(含零 DDL、仅语义变更),§4.4 **必须**包含:
-   (a) 结构变更结论表 + 明确变更 SQL(或明确写「无」),
-   (b) 核心实体的 Mermaid `erDiagram` + 表说明图例(表名/中文名/职责/结构/本迭代动作),
-   (c) 每张表完整 `CREATE TABLE`(含存储引擎与字符集;MySQL 须 `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4` …),
-   (d) 每张表字段说明表(含「本迭代用法」)。
-   禁止仅用散文描述 schema。MySQL DDL 禁止省略 ENGINE/CHARSET。零 DDL 迭代仍须展示当前基线 DDL —— 当表处于读/写路径时,禁止声称「不涉及数据库」。
-
-10. **§4.5 接口章节质量(硬规则)**:起草前执行 `project-conventions-guidance.md` `topic=api` + **`api-guidance.md`**.若变更涉及对外/跨服务/跨模块接口(含新增、修改、行为扩展、**协议不变但本迭代消费或调用**),§4.5 **必须**包含:
-    (a) 调用方/通道 + 鉴权总览,
-    (b) 编号稳定的接口清单(变更类型含 新增/修改/行为扩展/不变·本迭代消费/不变·协议不变),
-    (c) **契约面分层**:Worker HTTP / 平台 RPC+HTTP 绑定 / 东向 RPC **各自独立 `In`**,禁止 L2 详写、L4 一句 stub,
-    (d) 通用错误码映射(**唯一** gRPC code → **唯一** HTTP;禁止「或」「同类映射」),
-    (e) 清单中**每个**接口的元信息表、字段表、≥1 组成功请求/响应示例,
-    **(f) 每个接口 ≥1 组失败示例(G2)**,
-    (g) 错误条件表,
-    **(h) 新增/改 HTTP 绑定的 RPC**:冻结 RPC 全名 + proto 字段号 + `google.api.http` + Gateway 注册点 + Worker OpenAPI schema(禁止「暂定」「如」「实现时对齐」)。
-    禁止 stub。**一旦列入清单,无论是否不变,均须完整骨架**;可标注「与现网一致」但仍须贴字段表与示例。
-
-11. **§3 架构图须附设计要点(硬规则)**:每个架构 Mermaid 图后**必须**跟编号「设计说明 / 图要点」列表(边界/不变式/复用) —— 禁止仅复述节点名。仅有组件表不够。
-
-12. **§4 Happy Path 与场景设计要点(硬规则)**:§4.1 设计要点表、§4.2 完整 Happy Path `sequenceDiagram`、§4.3 每个业务场景**必须**在图后附「设计要点」说明。仅有图无说明视为质量不合格。
-
-13. **质量红线 G1–G6(硬规则)**:
-    - **G1**:超过 5 行散文的流程描述**必须**改为 Mermaid `sequenceDiagram` / `flowchart` / `stateDiagram-v2`(禁止长散文流程)。
-    - **G2**:§4.5 清单中**每个**接口(含**不变**)**必须**含 ≥1 组失败请求/响应示例(参数校验失败、租约过期等),禁止仅有错误码表。
-    - **G3**:JSON 形状变更或新增列**必须**在 §4.4.4 / §4.9 记录存量数据默认值填充策略。
-    - **G4**:**必须**说明回滚数据兼容性 —— 旧代码能否安全忽略/跳过新代码写入的数据(`omitempty`、未知字段忽略、`schema_version` 等)。仅写「回滚镜像」不够。
-    - **G5**:当 `uiInScope=yes` 时,§4.6 **必须**含页面/路由清单 + 前端栈五元组(Framework / Styling / State / UI kit / FE testing)。仅写「用 React」不合格。
-    - **G6**:当 `uiInScope=yes` 时,每个关键 `Page · …` **必须**覆盖空态/加载/错误至少一项,调用 API 时引用 §4.5 `In` 编号。
-
-14. **文风(硬规则)**:面向实现者的通俗语言;生僻英文缩写首次使用须注解。禁止含糊词「尽量」「大概」「一般情况下」「可能需要」「酌情」「视情况」;改用「必须」「禁止」「采用 XX 方案」或显式 if/then 表。**禁止** §2.1/§3/§4 正文代码腔:改写为可读中文;每条 bullet 括号内定位至多一次;协议名仅出现在表/DDL/HTTP 示例中。
-
-15. **§8 闭环正文可选但分析不可省(硬规则)**:对话摘要**始终**跑 Pass 1–7。用户选择纳入 §8 时,正文**仅**写一张汇总表(Pass | 检查项 | 结论 | 关键证据)。禁止展开七个 Pass 子节。用户选择省略时,`approval.md` 中**完全**不含 §8。
-
-16. **§4.4 数据库取证(硬规则)**:起草关系型 DDL 前:
-    (a) 执行 `project-conventions-guidance.md`,`topic=database`,Read 最多 3 份项目约定;
-    (b) 执行 `database-guidance.md` 取 SpecFlow pack / `dbStack`;
-    (c) Read 现网 DDL/迁移/锚点。优先级:**项目约定 + 现网 DDL > SpecFlow guidance > LLM**。§4.4.1 须记录 `项目约定` 与 `DB 技能`(或 未发现 / LLM-fallback)。禁止臆造 MCP 工具;禁止 `npx skills add`。
-
-17. **§4.4 / §4.5 / §4.6 大纲层级(硬规则)**:Markdown 目录须保持浅层。
-    - §4.4 标题仅:`#### 4.4.1–4.4.4` + 每表 `##### \`table\`(中文名)`。
-    - §4.5 标题仅:`#### 4.5.1–4.5.3` + 每接口 `##### In · <短名>(类型)`。
-    - §4.6 标题仅:`#### 4.6.1–4.6.5` + 每页 `##### Page · <短名>`。
-    - 「请求体字段」「请求示例」「响应示例」「错误」「DDL」「字段说明」「JSON 形状」「通用错误码约定」「空态」「加载」「错误」「依赖接口」等**必须**为 `**加粗**` 正文标签 —— **禁止** `####` / `#####` / `######` 标题。多组示例用加粗副标,禁止额外标题节点。
-
-18. **项目约定懒加载(硬规则)**:写 §3 / §4.4 / §4.5 / §4.6 前,执行 `project-conventions-guidance.md` 对应主题(`architecture` / `database` / `api` / `frontend`)。优先 `specflow/config.yaml` 的 `conventions.<topic>`;否则 activeIde → 其他 IDE → 仓根中立文档。每主题最多 3 文件。若约定文件存在但草稿违反硬禁令,在对话摘要(及 §8 若纳入)中发出 WARNING。
-
-19. **绿场/缺选型 Tech Stack Intake(硬规则)**:若 `projectMode=greenfield` 或四件套缺少所需栈维度(前端/后端/数据库与缓存/基础设施),**须在对话中询问用户**后再写架构或 DDL。答案写入 §2.2 技术选型与 §2.4 决策。禁止臆造全栈。标「不涉及」的维度可跳过。必选维度用户拒绝选择 → `[待 refine 澄清: 技术选型]` 并阻止猜测栈。`uiInScope=yes` 时前端答案须覆盖五元组(见 `frontend-guidance.md`);不接受仅「React」。
-
-20. **§4.6 前端章节质量(硬规则)**:若 `uiInScope=yes`,起草 §4.6 前:
-    (a) 执行 `topic=frontend` 约定;
-    (b) 执行 `frontend-guidance.md` §3 并 **Read** 匹配的 IDE skills/rules + 实现文档(组件/路由/状态/表单/API client/样式/a11y/测试命令/lint 禁令) —— 最多 5 文件,禁止 `invoke`;
-    (c) Read 现网 UI 锚点。§4.6.1 **必须**引用 `项目约定` 与 `IDE skills/rules`(或 未发现)。§4.6 **必须**含 4.6.1–4.6.5(页面/状态明确后,未知命令方可标 `[待 refine 澄清]`)。页面交叉引用 §4.5 `In` 与 §4.2 旅程。UI 不在范围时整章省略 —— 禁止臆造页面树。禁止将 skill 正文原文粘贴进 `approval.md`。
-
----
-
-## Part F: Segmented Generation (Map → CLI Reduce)
-
-> Router detail: `prompts/approval/segmented-generation.md`  
-> Index template: `templates/approval-index.yaml` · Part fragment: `templates/approval-part.md`
-
-When `approval/index.yaml` has `mode: segmented` (default for non-trivial §4), follow
-**12a → Gate → 12b → 12c → 12d**. The external artifact remains `approval.md`; the
-`approval/` directory is agent workspace only.
-
-### F.1 When to segment
-
-| Condition | Mode |
-|-----------|------|
-| `tables > 2` OR `interfaces > 3` OR `pages > 2` OR `optional.s5=true` | **segmented** (mandatory) |
-| Else | ask user: segmented (recommended) or monolithic |
-
-### F.2 Pipeline (hard order)
-
-1. **12a Index + Skeleton** — write `index.yaml` + `analysis.json` + parts 01–03, 04-detail-core, 06/09/10
-2. **Gate** — user confirms index inventory + optional chapters + mode
-3. **12b Map Append** — batched `04.4*` / `04.5*` / `04.6*` / `04.7–04.9`
-4. **12c Optional** — `05*` / `07` / `08` only when opted in
-5. **12e AI Review** — fix parts; write `review-result.json` with `part_hashes` (see `ai-review.md`)
-6. **12f Finalize** — `specflow approval finalize <change>` (lint → review-check → check → assemble → bundle)
-
-**Reduce 禁止 LLM** — never stitch parts in chat or paste from memory.
-
-### F.3 Anti-lazy rules (Map — hard)
-
-| # | Forbidden | Required |
-|---|-----------|----------|
-| L1 | One-shot full `approval.md` when `mode=segmented` | Write parts; `specflow approval finalize` |
-| L2 | Empty part, `< 20` chars, placeholder-only | Full section per Part E |
-| L3 | `TODO` / `待补充` / `此处省略` / bare `TBD` | Concrete text or `[待 refine 澄清: <元素>]` |
-| L4 | `详见 design/tasks` without §/In/Page id | Cross-ref `§4.5 I2` / `Page·列表` / `P1` |
-| L5 | New table/interface/page ids not in index | Update `index.yaml` first |
-| L6 | Skip DDL/字段表/失败示例 because "same as design" or "unchanged API" | G2–G6 minimum; **不变**仍须完整 §4.5 骨架 |
-| L6b | Collapse L4 RPC into「内部调用 I7」; L2-only HTTP without proto | **分层**: L2/L3/L4 各独立 `In`;见 `api-guidance.md` §1 |
-| L6c | RPC「暂定/如/实现时命名」 | **冻结** `Service.Method` + proto 字段号;见 `api-guidance.md` §2–§3 |
-| L7 | Skip IDE skills/rules scan for §4.6 | `frontend-guidance.md` §3 before Map |
-| L8 | Paste skill/rule bodies verbatim | Readable Chinese + path in §4.6.1 |
-| L9 | Foreign `## N.` headings in parts | `###`/`####` only; CLI injects chapter headers |
-| L10 | Mark done without finalize passing | Fix diagnostics; run `specflow approval finalize` |
-
-CLI lazy validation mirrors L2–L3 (`lazy_part_content` on assemble/check).
-
-### F.4 Map context budget
-
-Per batch Read only:
-
-- `approval/index.yaml` + `approval/analysis.json` (verdicts, not full Pass essays)
-- design/tasks/spec **snippets** for batch ids
-- conventions (≤3 files/topic; frontend ≤5 total per frontend-guidance)
-- anchor files for batch entities
-
-Do not reload entire four artifacts each batch.
-
-### F.5 index.yaml contract
-
-- `parts_order` is source of truth for assemble order
-- `tables[]` / `interfaces[]` / `pages[]` entries MUST include `part` matching `approval/parts/<part>.md`
-- `optional.s5/s7/s8` gates §5/§7/§8 parts even if files exist on disk
-
-### F.6 Retry
-
-| CLI diagnostic | Action |
-|----------------|--------|
-| `lazy_part_content` | Rewrite that part only; re-check |
-| `missing_part` | Write part or fix index |
-| `id_part_mismatch` | Align index `part` with filename |
-| `orphan_part` | Add to index or delete file |
-
-Do not rerun Pass 1–7 unless analysis is stale.
-
----
-
-## Part G: Multi-Repo Approval (多仓)
-
-> Router: `prompts/approval/multi-repo-guidance.md`
-
-### G.1 Trigger
-
-User natural language, workset, or cross-repo design → `multi_repo.enabled=true`.
-
-### G.2 User gates (hard, before Stage 12a)
-
-1. **Document mode**: **A** bundle (per_repo + CLI bundle, recommended) **or** **B** per_repo only **or** **C** legacy unified LLM merge (discourage).
-2. If **A or C**: **主仓** `primary_repo` — playbook/bundle or unified workspace path.
-3. Record in `index.yaml`; set `acp.pipeline: acp/v2`; do not assemble until answered.
-
-### G.3 Bundle 合订视图 (recommended)
-
-- Each repo: own `approval/` + `specflow approval assemble <repo.change>`.
-- Primary repo: `approval-playbook.yaml` + `specflow approval bundle <primary.change>`.
-- Output: `approval-unified.md` (readonly concatenation, no LLM merge).
-
-### G.4 Legacy unified LLM 合订 (discouraged)
-
-- Read **every** repo's four artifacts + anchors.
-- `index.change` **should equal** primary repo's change name.
-- Header lists all repos; §2.3 / 附录 B per-repo tables.
-- CLI: `specflow approval assemble <primary.change>` from **primary** planning root.
-
-### G.5 Per-repo 分仓
-
-- Separate `approval/` (or monolithic `approval.md`) **in each repo**.
-- Each document scoped to that repo only; cross-ref sibling paths.
-- Separate assemble per repo.
-
-### G.6 Inventory
-
-Recommend `repo` on `tables[]` / `interfaces[]` / `pages[]` entries for unified mode traceability.
-
-### G.7 主仓一键 · Subagent 并行 (mode A)
-
-> Router: `prompts/approval/multi-repo-spoke-subagent.md` · Orchestrator: `skills/specflow-approval/SKILL.md` **Stage 1c**
-
-When user starts `/specflow:approval` from **primary** repo and chose **A (bundle)**:
-
-1. Primary writes `approval-playbook.yaml`; spoke indexes set `bundle.enabled: false`.
-2. **Parallel** Task subagents per non-primary repo → full spoke Map + 12e + `finalize` (no `--bundle`).
-3. Primary **wait gate** — all spokes `finalize_ok`.
-4. Primary Map + finalize + `finalize --bundle --workspace-root <primary.planning_root>`.
-
-**Anti-lazy (multi-repo)**: no unified LLM merge when mode A chosen; no stub spoke parts (`见 design.md` rows without decision text); each spoke needs `analysis.json` + `review-result.json` when `acp.review.enabled`.
-
----
-
-## Part H: ACP Pipeline (Approval Compiler Pipeline)
-
-> Router: `prompts/approval/acp-pipeline.md` · AI review: `prompts/approval/ai-review.md`
-
-### H.1 When to use
-
-| Signal | Action |
-|--------|--------|
-| Segmented mode (`approval/parts/`) | **Always** run ACP Verify before assemble |
-| Multi-repo bundle | per_repo assemble → `approval bundle` |
-| Long doc / cross-part inconsistency risk | Enable `acp.review` (Stage 12e) |
-
-### H.2 Pipeline stages
-
-```text
-Analyze (Pass 1–7) → IR Freeze (index.yaml + interfaces[].frozen)
-→ Map (batched parts) → lint → review-pack → AI Review (12e) → review-check
-→ check → assemble → bundle (optional)
-```
-
-### H.3 index.yaml `acp` block
-
-```yaml
-acp:
-  pipeline: acp/v2
-  review:
-    enabled: true
-    required_pass: true   # assemble --require-review gates on this
-```
-
-Also freeze RPC names in `interfaces[].frozen` before Map batches.
-
-### H.4 CLI
-
-**Preferred (skill default)**:
-
-```bash
-specflow approval finalize <change> [--bundle] [--workspace-root <root>]
-```
-
-| Command | Purpose |
-|---------|---------|
-| `specflow approval review-hashes <change> [--json]` | Emit `part_hashes[]` for `review-result.json` |
-| `specflow approval finalize <change>` | One-shot: lint → review-check → check → assemble → bundle |
-| `specflow approval lint <change> [--strict]` | Debug / CI: cross-part consistency |
-| `specflow approval review-pack <change>` | Debug: generate review packet |
-| `specflow approval review-check <change>` | Debug: validate review-result |
-| `specflow approval check <change>` | Debug: parts/index validation |
-| `specflow approval assemble <change> [--require-review]` | Debug: merge parts only |
-| `specflow approval bundle <change>` | Debug: multi-repo readonly merge |
-
-### H.5 Stage 12e AI Review (mandatory when `acp.review.enabled`)
-
-Runs **inside `/specflow-approval`** — not as separate user steps:
-
-1. `specflow approval finalize <change>` — pauses with `review-packet.json` if needed
-2. Agent reads `prompts/approval/ai-review.md` + parts; fixes parts; writes `review-result.json`
-3. Re-run `specflow approval finalize <change>`
-
-AI review targets **long-document failure modes**: cross-part naming drift, inventory/body mismatch, depth imbalance across batches, unclosed branches, diagram/prose divergence, §4.6/§4.5 misalignment — not product-specific case rules.
-
-Optional domain packs (`runtime-guidance.md`, `api-guidance.md`) apply **only when** design/analysis mentions those topics.
-
-### H.6 Render (MD → HTML)
-
-```bash
-specflow approval render <change> [--input approval.md] [--output approval.html]
-specflow approval finalize <change> --render   # optional: render after finalize
-```
-
-Standalone HTML with embedded CSS; Mermaid diagrams load from CDN when present.
-
-### H.7 Playbook bundle (multi-repo)
-
-Template: `templates/approval-playbook.yaml`. Lists per-repo `approval.md` paths; `bundle` concatenates with repo headers — **no LLM merge**.
-