openspec-sdd-e2e-kit 0.1.0

package/kit/SDD_E2E_FLOW.md

@@ -0,0 +1,268 @@
+# OpenSpec SDD + E2E 流程总览
+
+本文是当前项目根目录层级的流程入口文档，用于说明已经落地的项目级 OpenSpec SDD + E2E 工作流。
+
+完整规范见：
+
+- `openspec/sdd-e2e-flow.md`
+- `openspec/schemas/sdd-e2e/schema.yaml`
+- `openspec/schemas/sdd-e2e.yaml`
+- `openspec/sdd-e2e-maintenance.md`
+- `openspec/changes/codify-sdd-e2e-flow/`
+
+## 目标
+
+这套流程的目标是把 E2E 验收能力融入 OpenSpec SDD 开发链路，避免在完整 spec 完成后一次性生成过重的 E2E。
+
+核心思想：
+
+```text
+spec 先定义业务规则
+feature 扩写验收场景
+tasks 按 phase 组织实现
+每个 phase 完成后跑对应 acceptance gate
+最后再跑 change 级 final acceptance
+```
+
+## 分层边界
+
+```text
+OpenSpec 本体 / CLI
+  不在本项目中修改
+
+项目级 OpenSpec 规范
+  由 openspec/schemas/sdd-e2e/schema.yaml、openspec/schemas/sdd-e2e.yaml 和 openspec/sdd-e2e-flow.md 定义
+
+Codex Skills / Scripts
+  作为执行器，读取项目级规范并落地到具体 change
+```
+
+本项目当前实现的是第二层和第三层：
+
+- 第二层：`schema: sdd-e2e`
+- 第三层：`.codex/skills/*` 和 `scripts/sdd/*`
+
+## 标准流程
+
+```text
+proposal
+  -> specs
+    -> features
+      -> test-cases
+        -> design
+          -> tasks
+            -> phase implementation
+              -> phase acceptance
+                -> final acceptance
+                  -> archive
+```
+
+关键约束：
+
+- `features` 必须在 specs 之后、design/tasks 最终定稿之前生成。
+- `tasks.md` 必须按 feature 中的 `@phase:*` 分组。
+- 每个 phase 必须通过 acceptance gate 才能关闭。
+- smoke 只能证明入口和基础链路可用，不能替代 acceptance。
+- final acceptance 通过前不能归档 `schema: sdd-e2e` 的 change。
+
+## 新 Change 如何使用
+
+适用于 UI 行为、交互状态、配置表单、异步请求、发布流程、跨视图同步或需要 E2E 验收的变更。
+
+`.openspec.yaml` 应声明：
+
+```yaml
+schema: sdd-e2e
+```
+
+不再使用 `schemaFile`。OpenSpec CLI 会从 `openspec/schemas/sdd-e2e/schema.yaml` 自动发现项目级 schema。
+
+最小 artifact 结构：
+
+```text
+openspec/changes/<change>/.openspec.yaml
+openspec/changes/<change>/proposal.md
+openspec/changes/<change>/specs/**/spec.md
+openspec/changes/<change>/specs/**/features/*.feature
+openspec/changes/<change>/test-cases.md
+openspec/changes/<change>/design.md
+openspec/changes/<change>/tasks.md
+```
+
+验收产物：
+
+```text
+specs/e2e/bdd/<change>/validation-report.<phase-id>.md
+openspec/changes/<change>/acceptance-coverage.md
+```
+
+## Feature 标签契约
+
+每个 Scenario 必须包含：
+
+```text
+@phase:<phase-id>
+@validation:<type>
+@req:<requirement-id>
+@p0 | @p1 | @p2
+```
+
+允许的 `@validation`：
+
+```text
+mock-e2e
+real-smoke
+component
+unit
+api
+manual
+```
+
+P0/P1 Scenario 还必须包含风险或边界类型标签，例如：
+
+```text
+@race-condition
+@degradation
+@anti-duplicate
+@form-validation
+@conditional-render
+@cross-view-sync
+@state-machine
+@feedback
+@negative
+```
+
+## Tasks 与 Phase
+
+`tasks.md` 必须按 phase 组织：
+
+```md
+## Phase: <phase-id>
+
+Covers: `@phase:<phase-id>`
+
+- [ ] 实现任务
+- [ ] Smoke 验证 `@phase:<phase-id>`
+- [ ] Acceptance 验证 `@phase:<phase-id>` 全部自动化 Scenario
+```
+
+规则：
+
+- tasks 不能发明 feature 中不存在的 phase id。
+- feature 中出现的 phase 必须在 tasks 中出现。
+- 每个 phase 必须有 acceptance 验证任务。
+- 调整 phase 时，必须同步修改 feature 和 tasks。
+
+## Gate 命令
+
+```bash
+pnpm sdd:lint-features <change>
+pnpm sdd:lint-tasks <change>
+pnpm sdd:phase <change> <phase>
+pnpm sdd:acceptance <change>
+pnpm sdd:self-test
+```
+
+命令职责：
+
+- `sdd:lint-features`：检查 Scenario 标签完整性、validation 类型、P0 gap-pending 禁止规则、P0/P1 风险标签。
+- `sdd:lint-tasks`：检查 feature phase 与 tasks phase 双向一致，并确认每个 phase 有 acceptance 任务。
+- `sdd:phase`：检查 phase report 是否存在、字段是否完整、是否覆盖当前 phase 下所有必需 P0/P1 Scenario。
+- `sdd:acceptance`：聚合所有 phase report，生成 final acceptance summary。
+- `sdd:self-test`：用临时 fixture 验证 gate 脚本能拦截坏标签、坏 phase、覆盖不足、failed/blocked report。
+
+## Phase Report 要求
+
+每个 phase acceptance report 至少包含：
+
+```text
+selected
+automated
+passed
+mismatch
+blocked
+manual
+gap-pending
+gate: passed | failed
+```
+
+`sdd:phase` 会回读 feature，计算当前 phase 应覆盖的 P0/P1 Scenario 数。只在报告里写 `gate: passed` 不足以通过。
+
+## 失败语义
+
+```text
+passed
+  实现符合 feature。
+
+mismatch
+  实际行为与 feature 不一致，需要修正实现或 artifact。
+
+blocked
+  环境、登录、权限、数据或依赖阻塞，当前无法可靠验证。
+
+manual
+  无法稳定自动化，需要记录人工步骤、证据和接受人。
+
+gap-pending
+  spec 明确未决的延期场景，必须记录原因和后续任务。
+```
+
+`blocked` 和 `manual` 默认不算通过。只有明确记录接受原因和责任人时，才能作为已知例外处理。
+
+## 规则强度
+
+MUST：
+
+- `schema: sdd-e2e` 的 change 必须包含 specs、features、test-cases、design 和 tasks。
+- 每个 Scenario 必须有 `@phase`、`@validation`、`@req` 和优先级标签。
+- P0/P1 Scenario 必须有风险或边界标签。
+- tasks 必须与 feature phase 双向一致。
+- phase acceptance 必须通过 `pnpm sdd:phase <change> <phase>`。
+- final acceptance 必须通过 `pnpm sdd:acceptance <change>` 后才能归档。
+- P0 不允许 `@gap-pending`。
+
+SHOULD：
+
+- UI、异步、表单、发布流程、跨视图同步类变更默认使用 `sdd-e2e`。
+- 每个 phase 控制在可独立验收的小切片。
+- feature 描述用户可观察行为，避免泄露接口字段和实现细节。
+
+MAY：
+
+- 纯文案、样式微调、无状态轻量修复可以继续使用 `spec-driven`。
+- P2 场景可以只进入 coverage matrix，不一定进入 phase acceptance。
+- `manual` 可用于无法稳定自动化的外部依赖场景，但必须记录人工步骤和接受人。
+
+## 当前落地状态
+
+流程改造 change：
+
+```text
+openspec/changes/codify-sdd-e2e-flow
+```
+
+已通过：
+
+```bash
+pnpm sdd:self-test
+pnpm sdd:lint-features codify-sdd-e2e-flow
+pnpm sdd:lint-tasks codify-sdd-e2e-flow
+pnpm sdd:phase codify-sdd-e2e-flow artifact-contract
+pnpm sdd:phase codify-sdd-e2e-flow feature-contract
+pnpm sdd:phase codify-sdd-e2e-flow phase-gate
+pnpm sdd:phase codify-sdd-e2e-flow reporting
+```
+
+当前 final acceptance 预期失败：
+
+```bash
+pnpm sdd:acceptance codify-sdd-e2e-flow
+```
+
+原因：
+
+```text
+pilot-run phase 尚未执行，缺少 validation-report.pilot-run.md
+```
+
+也就是说，流程规范和 gate 脚本已经落地，但还需要选择一个小型真实业务 change 跑 pilot，才能关闭最终验收。

package/kit/manifest.json

@@ -0,0 +1,78 @@
+{
+  "name": "openspec-sdd-e2e-kit",
+  "version": "0.1.0",
+  "description": "Project-local OpenSpec SDD + E2E workflow kit",
+  "assets": [
+    {
+      "path": "openspec/config.yaml",
+      "type": "file"
+    },
+    {
+      "path": "openspec/schemas/sdd-e2e",
+      "type": "directory"
+    },
+    {
+      "path": "openspec/schemas/sdd-e2e.yaml",
+      "type": "file"
+    },
+    {
+      "path": "openspec/sdd-e2e-flow.md",
+      "type": "file"
+    },
+    {
+      "path": "openspec/sdd-e2e-maintenance.md",
+      "type": "file"
+    },
+    {
+      "path": "SDD_E2E_FLOW.md",
+      "type": "file"
+    },
+    {
+      "path": ".codex/skills/openspec-apply-change",
+      "type": "directory"
+    },
+    {
+      "path": ".codex/skills/openspec-archive-change",
+      "type": "directory"
+    },
+    {
+      "path": ".codex/skills/openspec-continue-change",
+      "type": "directory"
+    },
+    {
+      "path": ".codex/skills/openspec-explore",
+      "type": "directory"
+    },
+    {
+      "path": ".codex/skills/openspec-full-spec-discovery",
+      "type": "directory"
+    },
+    {
+      "path": ".codex/skills/openspec-new-change",
+      "type": "directory"
+    },
+    {
+      "path": ".codex/skills/openspec-propose",
+      "type": "directory"
+    },
+    {
+      "path": ".codex/skills/spec-to-gherkin",
+      "type": "directory"
+    },
+    {
+      "path": ".codex/skills/feature-to-e2e",
+      "type": "directory"
+    },
+    {
+      "path": "scripts/sdd",
+      "type": "directory"
+    }
+  ],
+  "packageScripts": {
+    "sdd:acceptance": "node scripts/sdd/summarize-acceptance.mjs",
+    "sdd:lint-features": "node scripts/sdd/lint-features.mjs",
+    "sdd:lint-tasks": "node scripts/sdd/lint-tasks.mjs",
+    "sdd:phase": "node scripts/sdd/check-report.mjs",
+    "sdd:self-test": "node scripts/sdd/self-test.mjs"
+  }
+}

package/kit/openspec/config.yaml

@@ -0,0 +1,18 @@
+schema: sdd-e2e
+context: |
+  This project uses a project-local OpenSpec schema named sdd-e2e.
+  The workflow inserts Gherkin feature contracts between specs and design/tasks, then uses phase-scoped acceptance gates during implementation.
+  Feature files must be generated before design and tasks are finalized.
+  Phase completion is determined by acceptance reports and pnpm sdd:phase, not by smoke checks alone.
+rules:
+  features:
+    - "Generate Cucumber-compatible .feature files under specs/**/features/."
+    - "Every Scenario must include @phase, @validation, @req, and @p0/@p1/@p2 tags."
+    - "P0 and P1 scenarios must include risk or boundary tags."
+  tasks:
+    - "Organize tasks by feature @phase tags using ## Phase: <phase-id> headings."
+    - "Every phase must include a matching Covers line and an Acceptance validation task."
+    - "Do not invent phases that do not exist in feature tags."
+  final-acceptance:
+    - "Run pnpm sdd:acceptance <change> and use the generated acceptance-coverage.md."
+    - "Do not archive schema: sdd-e2e changes before final acceptance passes unless an exception is explicitly accepted."

package/kit/openspec/schemas/sdd-e2e/schema.yaml

@@ -0,0 +1,128 @@
+name: sdd-e2e
+version: 1
+description: Project workflow for OpenSpec SDD with Gherkin feature contracts and phase E2E acceptance gates
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Explain why the change is needed, what will change, and which capabilities are affected
+    template: proposal.md
+    instruction: |
+      Create the proposal artifact for a project-level SDD-E2E change.
+
+      The proposal must establish the problem, the intended user-visible behavior, the affected capabilities, and the expected impact. Keep implementation detail out unless it is necessary to clarify scope.
+
+      For UI behavior, interaction state, async requests, configuration forms, publishing flows, or cross-view synchronization, prefer this sdd-e2e workflow over the lightweight spec-driven workflow.
+    requires: []
+
+  - id: specs
+    generates: "specs/**/spec.md"
+    description: Define normative behavior and business rules using OpenSpec requirements and scenarios
+    template: spec.md
+    instruction: |
+      Create one spec file per capability listed in proposal.md.
+
+      Specs define what the system SHALL do. Use ADDED/MODIFIED/REMOVED/RENAMED sections and OpenSpec requirement syntax. Every requirement must have at least one scenario with exactly four heading hashes.
+
+      Do not encode implementation details as requirements unless they are externally observable behavior or a required contract.
+    requires:
+      - proposal
+
+  - id: features
+    generates: "specs/**/features/*.feature"
+    description: Expand specs into Gherkin feature files that define phase-scoped acceptance contracts
+    template: feature.feature
+    instruction: |
+      Generate Gherkin feature files from completed specs before finalizing design or tasks.
+
+      This artifact is an acceptance contract, not an optional test attachment. Expand beyond the happy path and cover frontend risk dimensions when applicable: state-machine behavior, validation, feedback, degradation, anti-duplicate actions, race conditions, conditional rendering, data echo, and cross-view sync.
+
+      Every Scenario must include scenario-level tags:
+      - @phase:<phase-id>
+      - @validation:<mock-e2e|real-smoke|component|unit|api|manual>
+      - @req:<requirement-id>
+      - @p0, @p1, or @p2
+
+      P0 and P1 scenarios must include at least one risk or boundary tag. P0 scenarios must not use @gap-pending.
+    requires:
+      - specs
+
+  - id: test-cases
+    generates: test-cases.md
+    description: Summarize rules, spec gaps, coverage matrix, and phase validation plan derived from features
+    template: test-cases.md
+    instruction: |
+      Create the coverage matrix for the generated feature files.
+
+      Include input sources, business rules, confirmed and pending spec gaps, scenario coverage by requirement, phase summary, validation type distribution, and feature file index.
+
+      If spec gaps affect E2E executability, record them explicitly and do not pretend they are covered.
+    requires:
+      - features
+
+  - id: design
+    generates: design.md
+    description: Explain the implementation approach, decisions, risks, and validation strategy
+    template: design.md
+    instruction: |
+      Create design.md after specs, features, and test-cases exist.
+
+      The design must use feature scenarios as input. Pay special attention to @phase boundaries, @validation types, P0/P1 scenarios, and risk tags. Record how implementation will handle mismatch, blocked validation, and known spec gaps.
+
+      Keep design focused on decisions and trade-offs, not line-by-line implementation.
+    requires:
+      - specs
+      - features
+      - test-cases
+
+  - id: tasks
+    generates: tasks.md
+    description: Break implementation into phase-scoped tasks tied to feature tags and acceptance gates
+    template: tasks.md
+    instruction: |
+      Create tasks.md using phase groups from feature Scenario tags.
+
+      Each phase must use:
+      ## Phase: <phase-id>
+      Covers: `@phase:<phase-id>`
+
+      Each phase must include implementation tasks and an Acceptance validation task for the same phase. A smoke task can exist, but smoke cannot close a phase.
+
+      Do not invent phase IDs that do not exist in feature tags. If a phase changes, update both feature tags and tasks.
+    requires:
+      - design
+      - features
+      - test-cases
+
+  - id: final-acceptance
+    generates: acceptance-coverage.md
+    description: Aggregate all phase acceptance reports and record the change-level final gate result
+    template: acceptance-coverage.md
+    instruction: |
+      Generate final acceptance after phase implementation and phase reports are complete.
+
+      Run:
+      pnpm sdd:acceptance <change>
+
+      The generated acceptance-coverage.md must show every phase gate and a final passed or failed result. A schema: sdd-e2e change should not be archived until final acceptance passes or the exception is explicitly accepted.
+    requires:
+      - tasks
+
+apply:
+  requires:
+    - tasks
+  tracks: tasks.md
+  instruction: |
+    Read proposal, specs, features, test-cases, design, and tasks before implementation.
+
+    Before implementation, run:
+    pnpm sdd:lint-features <change>
+    pnpm sdd:lint-tasks <change>
+
+    Implement one phase at a time. For each phase:
+    - complete the phase implementation tasks
+    - validate the selected @phase:<phase-id> scenarios
+    - write specs/e2e/bdd/<change>/validation-report.<phase-id>.md
+    - run pnpm sdd:phase <change> <phase-id>
+    - only mark the phase Acceptance task done if the phase gate passes
+
+    After all phases, run pnpm sdd:acceptance <change>. Do not treat smoke-only, blocked, manual, or mismatch results as phase completion unless the report records an accepted exception.

package/kit/openspec/schemas/sdd-e2e/templates/acceptance-coverage.md

@@ -0,0 +1,9 @@
+# Acceptance Coverage
+
+Change: `<change>`
+
+| Phase | Gate | Report |
+|---|---|---|
+| `<phase>` | pending | `specs/e2e/bdd/<change>/validation-report.<phase>.md` |
+
+Final gate: failed

package/kit/openspec/schemas/sdd-e2e/templates/design.md

@@ -0,0 +1,29 @@
+## Context
+
+<!-- Current behavior, relevant code areas, constraints, and dependencies. -->
+
+## Goals / Non-Goals
+
+**Goals:**
+- <goal>
+
+**Non-Goals:**
+- <non-goal>
+
+## Decisions
+
+### 1. <Decision>
+
+<Decision and rationale. Include alternatives considered where useful.>
+
+## Phase Strategy
+
+<!-- Explain how implementation maps to @phase tags and how each phase will be validated. -->
+
+## Risks / Trade-offs
+
+<!-- Include mismatch, blocked validation, concurrency, data, auth, and rollout risks. -->
+
+## Validation Plan
+
+<!-- List lint, unit/component/API/E2E/phase gates. Include pnpm sdd:* commands when applicable. -->

package/kit/openspec/schemas/sdd-e2e/templates/feature.feature

@@ -0,0 +1,13 @@
+@<capability>
+Feature: <capability title>
+
+  Background:
+    Given <stable shared precondition>
+
+  Rule: <business rule>
+
+    @phase:<phase-id> @validation:<type> @req:<requirement-id> @p0 @state-machine
+    Scenario: <observable scenario>
+      Given <precondition>
+      When <user action>
+      Then <observable result>

package/kit/openspec/schemas/sdd-e2e/templates/proposal.md

@@ -0,0 +1,23 @@
+## Why
+
+<!-- Explain the problem or opportunity. What user-visible limitation does this change address? Why now? -->
+
+## What Changes
+
+<!-- Describe the intended behavior changes. Be specific about new capabilities, modified behavior, and removals. -->
+
+## Capabilities
+
+### New Capabilities
+
+<!-- List new capability specs to create. Use kebab-case. -->
+- `<name>`: <brief description>
+
+### Modified Capabilities
+
+<!-- List existing capability specs whose requirements change. Leave empty if none. -->
+- `<existing-name>`: <what requirement changes>
+
+## Impact
+
+<!-- Affected pages, components, stores, services, APIs, data, E2E coverage, or operational risks. -->

package/kit/openspec/schemas/sdd-e2e/templates/spec.md

@@ -0,0 +1,21 @@
+## ADDED Requirements
+
+### Requirement: <requirement name>
+
+<Normative requirement text. Use SHALL/MUST for required behavior.>
+
+#### Scenario: <scenario name>
+- **WHEN** <condition or user action>
+- **THEN** <observable expected outcome>
+
+## MODIFIED Requirements
+
+<!-- For modified requirements, copy the full existing requirement block and edit it. -->
+
+## REMOVED Requirements
+
+<!-- Include Reason and Migration for removed behavior. -->
+
+## RENAMED Requirements
+
+<!-- Use FROM:/TO: for renamed requirements. -->

package/kit/openspec/schemas/sdd-e2e/templates/tasks.md

@@ -0,0 +1,16 @@
+# Phase-Driven Tasks
+
+## Phase: <phase-id>
+
+Covers: `@phase:<phase-id>`
+
+- [ ] Implement <behavior>
+- [ ] Run focused verification for `@phase:<phase-id>`
+- [ ] Acceptance 验证 `@phase:<phase-id>` 全部自动化 Scenario
+
+## Final Validation
+
+- [ ] Run `pnpm sdd:lint-features <change>`
+- [ ] Run `pnpm sdd:lint-tasks <change>`
+- [ ] Run all required implementation checks
+- [ ] Run `pnpm sdd:acceptance <change>`

package/kit/openspec/schemas/sdd-e2e/templates/test-cases.md

@@ -0,0 +1,35 @@
+# Test Cases
+
+## Input Sources
+
+<!-- List spec files, design notes, product constraints, and relevant implementation context. -->
+
+## Business Rules
+
+<!-- Extract rules from specs before listing scenarios. -->
+
+## Spec Gaps
+
+<!-- Record confirmed gaps and pending gaps. Mark whether each affects automation. -->
+
+## Coverage Matrix
+
+| Rule | Dimension | Priority | Phase | Validation | Scenario |
+|---|---|---:|---|---|---|
+| <rule> | <dimension> | P0 | <phase> | <validation> | <scenario> |
+
+## Phase Validation Summary
+
+| Phase | Scenarios | Automated | Manual | Notes |
+|---|---:|---:|---:|---|
+| <phase> | 0 | 0 | 0 | <notes> |
+
+## Feature File Index
+
+| File | Requirement | Scenario Count |
+|---|---|---:|
+| `specs/<capability>/features/<file>.feature` | <requirement> | 0 |
+
+## Quality Summary
+
+<!-- Include scenario count, unique step pattern count if available, gap-pending count, validation distribution, and lint status. -->