@gordon.gan/specflow 1.3.2-beta → 1.4.0-beta

package/prompts/approval/generate.md

@@ -0,0 +1,912 @@
+<!-- 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:
+
+1. A **Verdict**: `PASS` | `WARNING` | `FAIL` | `SKIPPED`
+2. **Evidence**: concrete citations (file path, section heading, requirement/scenario name, task ID, or for Pass 6/7: actual code file + function/section)
+3. A brief **rationale** linking evidence to verdict
+
+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 §6 方案详细设计): 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.
+
+```markdown
+# 技术方案审批文档: <change-name>
+
+> 本文档由 `/specflow:approval` 基于 refine 收敛后的四件套 + 现有代码与 spec 基线生成,
+> 经 AI 7 维闭环检查、架构整体设计、方案详细设计、测试策略、部署/发布/回滚、设计质量评估与可实施性评估,供人工审批使用。
+> 生成时间: YYYY-MM-DD HH:MM | phase: refined | 产物语言: <lang> | 技术栈: <stack>
+
+---
+
+## 1. 变更概览 (Dashboard)
+
+| 维度 | 值 |
+|------|-----|
+| Change 名称 | <change-name> |
+| 创建日期 | <from .specflow.yaml created> |
+| 当前 phase | refined |
+| 技术栈 | <Node/TypeScript / Go / Python / Rust / unknown> |
+| Capability 数 | N (新增 X / 修改 Y) |
+| Requirement 数 | N |
+| Scenario 数 | N (功能可测试 A / 文档可测试 B / 不可测试 C) |
+| 任务总数 | N (已完成 X / 待实施 Y) |
+| Design 决策数 | N |
+| 识别风险数 | N |
+| 代码锚点文件数 | N (存在 M / 不存在 K / 新建 L) |
+| 基线 spec 数 | N (或 "无基线 — greenfield") |
+| 过度设计信号数 | N (0 = PASS / 1-2 = WARNING / 3+ = FAIL) |
+| 扩展性信号数 | N (4-5 = PASS / 0-3 = WARNING) |
+
+> 上述计数基于四件套文件 + 项目代码 + 主 specs 精确统计,非 AI 估算。
+
+---
+
+## 2. 变更摘要 (Executive Summary)
+
+### 2.1 为什么做 (Why)
+[2-3 句话提炼 proposal.md 的 Why]
+
+### 2.2 做什么 (What Changes)
+[按 新增/修改/移除/重命名 分类,标注 BREAKING]
+
+### 2.3 影响面 (Impact)
+[整合 proposal.md Impact,AI 评估影响等级]
+
+---
+
+## 3. 验收标准 (Acceptance Criteria)
+
+[按 capability 分组,完整列出所有 Requirement + Scenario,每个 Scenario 3 级可测试性标注]
+
+### 3.1 Capability: <name>
+[Delta 操作类型: ADDED / MODIFIED / REMOVED / RENAMED]
+
+#### Requirement: <name>
+<描述>
+
+| Scenario | WHEN | THEN | 可测试性 | 说明 |
+|----------|------|------|---------|------|
+| <name> | <条件> | <期望> | ✅ 功能可测试 / ⚠️ 文档可测试 / ❌ 不可测试 | <原因 if ⚠️/❌> |
+
+---
+
+## 4. 技术方案评估 (Technical Design Review)
+
+### 4.1 现状与约束 (Context & Constraints)
+[整合 design.md Context + AI 补充的隐含约束]
+
+### 4.2 目标与非目标 (Goals & Non-Goals)
+[整合 design.md Goals/Non-Goals]
+
+### 4.3 决策评审表 (Decision Review)
+
+| 决策 | 选定方案 | 备选方案 | 理由 | 影响评估 | 状态 |
+|------|---------|---------|------|---------|------|
+| D1: <name> | <方案> | <A/B> | <理由> | <评估> | Proposed |
+
+### 4.4 风险与权衡 (Risks & Trade-offs)
+
+| 风险 | 严重等级 | 缓解措施 | 就绪度 |
+|------|---------|---------|--------|
+| <name> | 高/中/低 | <措施> | ✅/⚠️/❌ |
+
+### 4.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
+
+---
+
+## 5. 架构整体设计 (Architecture Design)
+
+> 本章回答"系统由哪些模块组成、模块间如何依赖与交互、每个模块的职责与边界是什么"。
+> 它聚焦**宏观结构**(模块图 + 交互图),与 §6 方案详细设计(模块内部实现)互补:
+> 架构讲"模块之间的关系",详细设计讲"模块内部怎么做"。
+
+### 5.1 总体架构 (Architecture Overview)
+
+用 Mermaid 图绘制 **系统交互图 或 模块依赖图**,直观呈现变更后的系统结构。
+
+**图型选择**:
+
+- **模块依赖图 / 分层架构图** — `mermaid flowchart LR`(模块为节点,依赖为边),展示新增/修改模块在整体中的位置
+- **系统交互图** — `mermaid sequenceDiagram`(参与者为模块/角色),展示变更涉及的模块间调用时序
+
+**绘制要求**:
+
+1. 标注**变更涉及的模块**(用颜色/形状/标注 `[新增]` `[修改]` 区分),让评审者一眼看出本次变更影响面
+2. 边标注**依赖方向**(谁依赖谁)或**交互消息**(谁调用谁,传递什么)
+3. 对纯 CLI/库项目,模块 = 源码模块(`src/core/*`、`src/cli/*`);对 Web 项目,模块 = 服务/组件;对多仓,模块 = 仓库/服务
+4. 图应**与 §4 决策一致** —— 图上体现的结构必须能追溯到某个决策
+
+**示例(模块依赖图)**:
+```mermaid
+flowchart LR
+    subgraph CLI["CLI 层 (src/cli/)"]
+        INIT["init 命令 [修改]"]
+        CHANGE["change 命令"]
+        STORE["store 命令 [新增]"]
+    end
+    subgraph CORE["核心层 (src/core/)"]
+        CONFIG["project-config [修改]"]
+        ART["artifact-language [新增]"]
+        STORECORE["store/ [新增]"]
+        ROOT["root-selection [新增]"]
+    end
+    INIT --> CONFIG
+    INIT --> ART
+    STORE --> STORECORE
+    CHANGE --> ROOT
+    CONFIG --> ART
+```
+
+**示例(系统交互图)**:
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant C as CLI (init)
+    participant F as Filesystem
+    participant P as Parity check
+    U->>C: specflow init --artifact-language zh-CN
+    C->>F: 创建 specflow/{changes,specs}
+    C->>F: 写入 config.yaml (artifacts.language)
+    C->>F: 复制 IDE 资产
+    C->>P: parity 严格校验
+    P-->>C: ok / fail
+    C-->>U: status + message
+```
+
+### 5.2 核心组件说明 (Core Components)
+
+用表格定义**每个模块/组件的职责与边界**。这是实现者判断"某逻辑该放哪个模块"的依据,也是评审者验证"模块边界是否清晰"的依据。
+
+| 组件 | 职责 | 边界(做什么 / 不做什么) | 依赖 | 变更类型 |
+|------|------|-------------------------|------|---------|
+| `<组件名>` | 一句话职责 | 做什么;不做什么(明确边界) | 依赖的组件 | 新增/修改/不变 |
+
+**填写要求**:
+
+1. **列出变更涉及的所有组件**(新增 + 修改),并为每个标注职责、边界、依赖
+2. 边界要写"不做什么" —— 明确职责归属,防止实现时逻辑放错模块(如:CLI 不解析斜杠参数、核心层不做 AI 推理)
+3. 依赖方向要明确(谁依赖谁),避免循环依赖
+4. **与 §5.1 图一致**:每个表格组件应在图中出现
+5. 每个组件边界可追溯到 §4 决策(如 D1 选择"在 skill 层解释 --yes" → 边界"CLI 不解析斜杠参数")
+
+**示例**:
+
+| 组件 | 职责 | 边界 | 依赖 | 变更 |
+|------|------|------|------|------|
+| `src/core/artifact-language.ts` | 定义语言类型、别名规范化、指导渲染 | 只定义策略,不写文件;不做自然语言检测 | 无 | 新增 |
+| `src/cli/commands/init.ts` | 初始化项目、写入 config、调用资产生成 | 只写新配置;不覆盖已有 config;不做 AI 推理 | project-config, artifact-language | 修改 |
+| `src/core/project-config.ts` | 解析 config.yaml,产出诊断 | 只解析,不校验 IDE 资产;错误恢复为默认值 | artifact-language | 修改 |
+
+**不涉及架构变更时写**:`不涉及架构变更(单模块/单文件调整,模块边界无变化)`。
+
+### 5.3 架构一致性自检(生成后检查)
+
+- [ ] §5.1 图标注了新增/修改模块,评审者一眼看出影响面
+- [ ] §5.2 每个组件有"不做什么"的边界,避免逻辑放错模块
+- [ ] §5.1 与 §5.2 一一对应(图中有,表中有;表中依赖与图边一致)
+- [ ] 组件边界可追溯到 §4 决策
+- [ ] 未涉及架构变更时显式标注"不涉及架构变更"
+
+---
+
+## 6. 方案详细设计 (Detailed Design)
+
+> 本章节将方案从"宏观决策"落到"实现者可直接照写的细节"。它回答:具体怎么实现每个部分?
+> **只呈现本变更涉及的部分**,不涉及的类型显式标注 "本变更不涉及 X" 而非留空。
+> 每个详细设计元素必须**可追溯到 §3 验收标准**(Requirement/Scenario)和 §4 决策(design.md 的 D1-Dn)。
+
+### 6.1 数据结构 / 数据模型变更 (Data Structures)
+
+**适用范围**:涉及持久化、状态存储、数据模型的变更。纯 CLI/库项目若无数据库,覆盖配置结构 / 状态文件 / 缓存结构 / YAML schema 等"数据模型"。
+
+| 元素 | 内容 |
+|------|------|
+| 新增/修改的表结构或数据模型 | 名称、字段、类型、长度、约束(主键/外键/唯一/非空/默认值) |
+| 索引建议 | 由查询模式驱动的索引(覆盖查询/联合/唯一),不盲目加索引;说明每条索引支撑的查询 |
+| 数据迁移 | 存量数据转换方式、迁移脚本、回滚方案 |
+| 配置结构 | 新增/修改的配置键、类型、默认值、生效时机 |
+
+示例(数据库):
+```sql
+CREATE TABLE artifact_language (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  project_id INTEGER NOT NULL REFERENCES project(id),
+  language   TEXT NOT NULL DEFAULT 'en' CHECK (language IN ('en','zh-CN')),
+  updated_at TEXT NOT NULL,
+  UNIQUE (project_id)
+);
+-- 索引 idx_project_language:支撑 "按 project_id 查语言" 高频查询
+CREATE INDEX idx_artifact_language_project ON artifact_language(project_id);
+```
+
+示例(CLI/库项目的配置结构):
+```yaml
+# specflow/config.yaml 新增
+artifacts:
+  language: zh-CN   # en | zh-CN,缺省 en
+```
+
+**不涉及数据库变更时写**:`不涉及数据库变更(纯逻辑/CLI 变更,无持久化数据模型)`。
+
+### 6.2 接口设计 (Interface Design)
+
+**适用范围**:暴露 API/RPC/CLI 命令/函数间接口的变更。
+**项目类型适配**:CLI 项目 → commander 命令参数;库项目 → 导出函数签名;Web 项目 → HTTP API。
+
+| 元素 | 内容 |
+|------|------|
+| 接口签名 | 方法名/路径/CLI 命令;参数名、类型、必选/可选、校验规则 |
+| 入参说明 | 每个参数的语义、合法值、默认值 |
+| 出参说明 | 返回类型、成功/失败结构 |
+| 错误码定义 | 错误码枚举、含义、HTTP 状态码 / CLI 退出码映射 |
+
+示例(CLI):
+```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 校验失败
+```
+
+**不涉及接口变更时写**:`不涉及接口变更(内部实现调整,无对外/跨模块接口变化)`。
+
+### 6.3 业务流程 (Business Flow)
+
+**适用范围**:有状态流转、多步骤逻辑、并发时序的变更。即使无显式状态机,任何多步骤流程都应画时序图。
+
+| 元素 | 内容 |
+|------|------|
+| 时序说明 | 谁调用谁、顺序、分支、异常路径(可用 Mermaid `sequenceDiagram`) |
+| 状态机流转 | 状态集合、迁移事件、迁移条件、终态(可用 Mermaid `stateDiagram-v2`) |
+
+示例(时序):
+```mermaid
+sequenceDiagram
+  participant U as User
+  participant I as init CLI
+  participant FS as Filesystem
+  participant P as Parity check
+  U->>I: specflow init --artifact-language zh-CN
+  I->>FS: 创建 specflow/{changes,specs}
+  I->>FS: 写入 config.yaml (artifacts.language: zh-CN)
+  I->>FS: 复制 IDE 资产 (skills/commands/prompts)
+  I->>P: parity 严格校验
+  P-->>I: ok / fail
+  I-->>U: status + message
+```
+
+**不涉及业务流程变更时写**:`不涉及复杂业务流程(单步/线性实现,无状态流转)`。
+
+### 6.4 核心算法 / 逻辑说明 (Core Logic)
+
+**适用范围**:有非平凡算法或数据处理逻辑的变更。
+| 元素 | 内容 |
+|------|------|
+| 输入输出 | 输入数据结构、输出数据结构 |
+| 处理步骤 | 逐步逻辑(编号列表) |
+| 复杂度 | 时间/空间复杂度,边界条件 |
+
+**不涉及非平凡算法时写**:`不涉及非平凡算法(逻辑简单,无复杂数据处理)`。
+
+### 6.5 配置与运行环境 (Configuration & Runtime)
+
+**适用范围**:新增配置项、环境变量、运行时依赖的变更。
+| 元素 | 内容 |
+|------|------|
+| 配置项 | 名称、类型、默认值、生效时机 |
+| 环境变量 | 新增变量、语义 |
+| 运行时依赖 | 新增依赖、版本、用途 |
+
+**不涉及配置变更时写**:`不涉及配置或运行环境变更`。
+
+### 6.6 兼容性与迁移 (Compatibility & Migration)
+
+**适用范围**:有破坏性变更。
+| 元素 | 内容 |
+|------|------|
+| 旧行为 → 新行为 | 映射表 |
+| 迁移路径 | 存量用户如何升级、迁移步骤 |
+| 回滚方案 | 失败时如何回滚 |
+
+**不涉及破坏性变更时写**:`不涉及破坏性变更(向后兼容)`。
+
+### 详细设计质量自检(生成后检查)
+
+- [ ] 每个详细设计元素可追溯到 §3 验收标准的某个 Requirement/Scenario
+- [ ] 每个详细设计选择引用了 §4 的某个决策(不另起炉灶)
+- [ ] 涉及数据/接口/流程的,均非留空(写了真实签名/字段/状态)
+- [ ] 不涉及的类别显式标注 "不涉及",而非留空
+- [ ] 若某个元素无法写出实现级细节,标记 `[待 refine 澄清: <元素>]` — 这是方案未想透的质量信号,应报告给用户
+
+---
+
+## 7. 测试策略 (Test Strategy)
+
+> 本章从"§3 验收标准可不可测"升级为"**用分层测试证明方案正确**"。它回答:
+> 每个验收标准(WHEN/THEN)由哪一层测试覆盖、用什么工具、目标是证明什么。
+> **选择性呈现**:只列出本变更实际需要的测试层级;不涉及的层级显式标注"不涉及"。
+
+### 7.1 分层测试矩阵
+
+| 测试层级 | 覆盖对象 | 工具/框架 | 目标(证明什么) | 覆盖的验收标准 |
+|---------|---------|----------|---------------|---------------|
+| 单元测试 | 核心函数/类/模块内部逻辑 | <框架,如 vitest/jest/pytest> | 逻辑正确、边界处理 | 引用 §3 的 Scenario |
+| 集成测试 | 模块间交互、接口契约、外部依赖 | <框架> | 模块协作正确、契约一致 | 引用 §3 的 Scenario |
+| 验收测试 | spec 的 WHEN/THEN 行为 | <E2E/CLI 测试> | 逐 Scenario 验证用户可见行为 | §3 全部核心 Scenario |
+| 回归测试 | 主 specs 基线 + 既有行为 | <框架> | 不破坏已有功能 | 主 specs(§3 基线对照) |
+| 性能测试 | 关键路径/高并发 | <如 k6/jmeter/bench> | NFR 性能目标达成 | NFR 章节 |
+| 安全测试 | 认证/授权/输入边界 | <SAST/渗透> | 无已知漏洞 | NFR 安全目标 |
+| 兼容性测试 | 多平台/多版本/多浏览器 | <如 playwright> | 跨环境一致 | 兼容性 Requirement |
+
+**填写要求**:
+
+1. 每个测试层级**映射到 §3 验收标准**(引用具体 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" |
+
+### 7.2 测试环境与数据
+
+| 项 | 说明 |
+|----|------|
+| 测试环境 | 单元/集成用本地 tmpdir;验收用隔离环境(如 CI) |
+| 测试数据 | 需要的 fixture/seed 数据、中文/英文样本 |
+| 并行/隔离 | 测试间是否可并行、是否需要隔离(文件锁/独立目录) |
+| 覆盖率目标 | 核心模块目标覆盖率(如 ≥80%) |
+
+### 7.3 测试策略自检
+
+- [ ] 每个 §3 验收标准至少被一个测试层级覆盖(闭环)
+- [ ] 每个测试层级有工具、有可验证目标
+- [ ] 既有行为有回归测试保护(对应 Pass 7 基线)
+- [ ] 新增测试与修改既有测试已区分
+
+**不涉及测试变更时写**:`不涉及测试变更(纯文档/配置变更,无行为逻辑需要测试)`。
+
+---
+
+## 8. 部署/发布/回滚方案 (Deployment & Release)
+
+> 本章回答"方案实现后如何上线、如何发布、出问题如何回滚、上线后如何监控"。
+> **选择性呈现**:对有运行系统的项目必须;对纯库/CLI/文档项目可显式标注"不涉及运行时部署"。
+
+### 8.1 部署方案 (Deployment)
+
+| 项 | 方案 |
+|----|------|
+| 部署目标 | 部署到哪里(生产/预发/多环境)、依赖的基础设施 |
+| 部署方式 | 镜像/包发布/代码部署/配置下发;CI 流水线步骤 |
+| 部署顺序 | 依赖部署的先后(如先迁移 DB 再部署应用) |
+| 配置管理 | 新配置项如何在各环境生效、密钥管理 |
+| 环境差异 | dev/staging/prod 的环境差异与处理 |
+
+### 8.2 发布策略 (Release Strategy)
+
+| 项 | 方案 |
+|----|------|
+| 发布方式 | 蓝绿/金丝雀/滚动/直接替换;理由 |
+| 发布窗口 | 是否需停机窗口、灰度比例 |
+| 兼容性 | 新旧版本共存期间的兼容(如 API 版本化、DB 兼容) |
+
+### 8.3 回滚方案 (Rollback)
+
+| 项 | 方案 |
+|----|------|
+| 回滚触发条件 | 什么情况下回滚(错误率/指标阈值) |
+| 回滚方式 | 镜像回退/代码回退/数据回滚;自动或手动 |
+| 回滚的数据一致性 | 数据迁移的回滚(若有)、缓存/队列的清理 |
+| 回滚验证 | 回滚后如何确认恢复正常 |
+
+### 8.4 监控与可观测性 (Monitoring & Observability)
+
+| 项 | 方案 |
+|----|------|
+| 关键指标 | 上线后需监控的指标(错误率/延迟/资源) |
+| 日志/追踪 | 日志规范、链路追踪 |
+| 告警 | 告警阈值与负责人 |
+
+### 8.5 部署方案自检
+
+- [ ] 部署目标/方式/顺序明确
+- [ ] 发布策略与兼容性说明
+- [ ] 回滚触发条件、方式、数据一致性、验证明确
+- [ ] 上线后监控指标与告警明确
+
+**不涉及运行时部署时写**:`不涉及运行时部署(纯库/CLI/文档项目,无服务上线,变更通过包发布/版本发布交付)`。
+
+---
+
+## 9. 闭环性检查 (Closed-Loop Verification)
+
+### Pass 1: 需求闭环 (Requirement Closure)
+**Verdict:** PASS / WARNING / FAIL
+**证据:** <proposal→spec 覆盖表>
+
+### Pass 2: 方案闭环 (Design Closure)
+**Verdict:** PASS / WARNING / FAIL
+**证据:** <decision↔requirement 双向表>
+
+### Pass 3: 规格闭环 (Spec Closure)
+**Verdict:** PASS / WARNING / FAIL
+**证据:** <Scenario 可测试性表 + delta 结构检查>
+
+### Pass 4: 实施闭环 (Implementation Closure)
+**Verdict:** PASS / WARNING / FAIL
+**证据:** <requirement×task 覆盖矩阵 + 范围蔓延检查>
+
+### Pass 5: 风险闭环 (Risk Closure)
+**Verdict:** PASS / WARNING / FAIL
+**证据:** <风险表 + 未识别风险>
+
+### Pass 6: 代码落地性 (Code Grounding)
+**Verdict:** PASS / WARNING / FAIL / SKIPPED (greenfield)
+**证据:**
+
+| 锚点文件 | 存在? | 计划动作 | 结构兼容性 |
+|---------|------|---------|-----------|
+| <path> | ✅/❌ | extend/create/modify | <评估> |
+
+**技术栈一致性:** <一行结论 + 理由>
+
+### Pass 7: 基线对照 (Baseline Cross-Check)
+**Verdict:** PASS / WARNING / FAIL / SKIPPED (no baseline)
+**证据:**
+
+| Capability | Requirement | 操作 | 基线状态 | 结论 |
+|-----------|-------------|------|---------|------|
+| <name> | <name> | ADDED/MODIFIED/... | exists/duplicate/not-found | ✅/⚠️/❌ |
+
+### 闭环性总评
+
+| 维度 | 结论 |
+|------|------|
+| Pass 1 需求闭环 | ✅/⚠️/❌/⊘(skipped) |
+| Pass 2 方案闭环 | |
+| Pass 3 规格闭环 | |
+| Pass 4 实施闭环 | |
+| Pass 5 风险闭环 | |
+| Pass 6 代码落地性 | |
+| Pass 7 基线对照 | |
+
+**整体闭环性:** PASS / PASS WITH WARNINGS / FAIL
+
+---
+
+## 10. 可实施性评估 (Implementability Assessment)
+
+| 评估维度 | 结论 | 说明 |
+|---------|------|------|
+| 完整性 | READY / NEEDS REFINEMENT / BLOCKED | |
+| 规格对齐 | | |
+| 任务可执行性 | | |
+| 技术可行性 | | |
+| 依赖明确性 | | |
+| 架构一致性 | | <基于 Pass 6 代码读取> |
+| 实施风险 | | <核心模块/数据迁移/并发/外部接口> |
+
+**可实施性总评:** READY / NEEDS REFINEMENT / BLOCKED
+
+---
+
+## 11. 审批意见 (Approval Decision)
+
+### 7.1 AI 预审建议
+
+**建议:** 建议批准 / 有条件批准 / 退回 refine / 拒绝
+**理由:** <1-2 句话,引用具体 verdict>
+
+### 7.2 人工审批签字栏
+
+| 角色 | 姓名 | 审批结论 | 日期 | 意见 |
+|------|------|---------|------|------|
+| 技术负责人 | | □ 批准 □ 退回 □ 拒绝 | | |
+| 产品负责人 | | □ 批准 □ 退回 □ 拒绝 | | |
+| 架构师 | | □ 批准 □ 退回 □ 拒绝 | | |
+
+> 审批结论填写说明:批准 → 可执行 `/specflow:apply`;退回 → 执行 `/specflow:refine` 修复后重新审批;拒绝 → 废弃本次 change。
+
+---
+
+## 附录 A: 产物溯源
+
+| 章节 | 数据来源 | 处理方式 |
+|------|---------|---------|
+| 变更概览 | .specflow.yaml + specs/ + tasks.md + design.md + 项目代码 + 主 specs | 精确统计 |
+| 变更摘要 | proposal.md (+ explore.md) | AI 提炼 |
+| 验收标准 | specs/**/*.md | AI 整合 + 3 级可测试性评估 |
+| 技术方案评估 | design.md | AI 用 arc42 重组 + 决策表 + 风险表 + 设计质量评估 |
+| 架构整体设计 | design.md 决策 + 项目代码(锚点)+ specs 契约 | AI 绘制 Mermaid 模块依赖/系统交互图 + 组件职责边界表;每组件追溯到 §4 |
+| 方案详细设计 | design.md 决策 + specs 契约 + 项目代码(锚点) | AI 落地为数据/接口/流程/算法/配置/兼容性;每元素追溯到 §3+§4 |
+| 测试策略 | §3 验收标准 + 项目测试栈 | AI 分层测试矩阵(单元/集成/验收/回归/性能/安全),每层映射到验收标准 |
+| 部署/发布/回滚 | §4 决策 + 项目运行环境 | AI 部署方式/发布策略/回滚/监控方案;纯库项目标注"不涉及运行时部署" |
+| 闭环性检查 Pass 1-5 | 四件套交叉验证 | AI 推理 |
+| 闭环性检查 Pass 6 | 项目锚点文件(只读文件本身) | AI 代码结构分析 |
+| 闭环性检查 Pass 7 | specflow/specs/ 主基线 | AI 交叉对照 |
+| 可实施性评估 | tasks + design + specs + 项目代码 | AI 推理 |
+| 审批意见 | 闭环性 + 设计质量 + 可实施性三重 verdict | AI 预审 + 人工签字栏 |
+```
+
+### Generation Rules
+
+1. **Dashboard counts are precise**: read every delta spec file, count headers. Read anchor
+   files, count exists/missing/new. Read `specflow/specs/`, count baseline specs. If a count
+   cannot be determined, state "无法精确统计" rather than guess.
+
+2. **Acceptance Criteria is exhaustive**: include every Requirement and Scenario from every
+   delta spec. Do not summarize or omit.
+
+3. **Pass 6 evidence must cite real code**: every anchor file in the evidence table must be
+   a file you actually read. "Structure compatibility" must reference concrete findings
+   (function name, module pattern, export shape). "I didn't read the file" is not acceptable —
+   either read it or mark it `SKIPPED (greenfield)`.
+
+4. **Pass 7 evidence must cite baseline specs**: every row must reference the actual main
+   spec file and requirement name you compared against. If baseline is absent, use the
+   verbatim `SKIPPED (no baseline — greenfield or no archived changes yet)` line.
+
+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**: narrative follows `artifacts.language`; protocol markers, IDs,
+   paths, commands, code stay in original form.
+
+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.