openspec-sdd-e2e-kit 0.1.0

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

@@ -0,0 +1,160 @@
+name: sdd-e2e
+version: 1
+description: 项目级 OpenSpec SDD + E2E 工作流规范。以 OpenSpec artifact 为主干，在 spec 与 tasks 之间加入 feature 契约，并以 phase acceptance gate 关闭开发切片。
+
+status: project-extension
+owner: front-mindflow-setting
+
+principles:
+  - OpenSpec 管理需求、设计、任务和归档生命周期。
+  - Gherkin feature 是 spec 与 tasks 之间的项目级验证契约。
+  - tasks 必须按 feature 中的 phase 分组。
+  - phase 完成必须依赖 acceptance gate；smoke 不能关闭 phase。
+  - mismatch 必须回到实现或 artifact 修正，不能通过削弱断言绕过。
+  - 本 schema 是项目级扩展，不修改 OpenSpec CLI 本体。
+
+lifecycle:
+  order:
+    - proposal
+    - specs
+    - features
+    - design
+    - tasks
+    - phase-acceptance
+    - final-acceptance
+    - archive
+
+artifacts:
+  proposal:
+    path: openspec/changes/<change>/proposal.md
+    required: true
+    purpose: 说明为什么做、做什么、涉及哪些 capability 和影响面。
+
+  specs:
+    path: openspec/changes/<change>/specs/**/spec.md
+    required: true
+    dependsOn:
+      - proposal
+    purpose: 用 SHALL/MUST/SHOULD 描述需求行为和业务规则。
+
+  features:
+    path: openspec/changes/<change>/specs/**/features/*.feature
+    required: true
+    dependsOn:
+      - specs
+    purpose: 从 specs 扩写可验收 Scenario，并提供 phase/task/e2e 的追溯标签。
+    requiredScenarioTags:
+      - "@phase:<phase-id>"
+      - "@validation:<type>"
+      - "@req:<requirement-id>"
+      - "@p0 | @p1 | @p2"
+    validationTypes:
+      - mock-e2e
+      - real-smoke
+      - component
+      - unit
+      - api
+      - manual
+    boundaryTags:
+      - race-condition
+      - degradation
+      - anti-duplicate
+      - form-validation
+      - conditional-render
+      - cross-view-sync
+      - state-machine
+      - feedback
+      - negative
+
+  testCases:
+    path: openspec/changes/<change>/test-cases.md
+    required: true
+    dependsOn:
+      - features
+    purpose: 汇总 Scenario 覆盖矩阵、优先级、phase 和 validation 类型。
+
+  design:
+    path: openspec/changes/<change>/design.md
+    required: true
+    dependsOn:
+      - specs
+      - features
+      - testCases
+    purpose: 基于需求和 feature 风险面形成实现方案、边界处理和验证策略。
+
+  tasks:
+    path: openspec/changes/<change>/tasks.md
+    required: true
+    dependsOn:
+      - design
+      - features
+    purpose: 按 @phase 分组实现任务，并为每个 phase 声明 smoke 与 acceptance 验证任务。
+    phaseContract:
+      requiredHeading: "## Phase: <phase-id>"
+      requiredCoverageLine: "Covers: `@phase:<phase-id>`"
+      requiredValidationTask: "Acceptance 验证 `@phase:<phase-id>`"
+
+  phaseReports:
+    path: specs/e2e/bdd/<change>/validation-report.<phase-id>.md
+    required: true
+    dependsOn:
+      - tasks
+    purpose: 每个 phase 的 acceptance gate 报告。
+    requiredCoverageFields:
+      - selected
+      - automated
+      - passed
+      - mismatch
+      - blocked
+      - manual
+      - gap-pending
+      - gate
+
+  finalAcceptance:
+    path: openspec/changes/<change>/acceptance-coverage.md
+    required: true
+    dependsOn:
+      - phaseReports
+    purpose: 汇总所有 phase gate，给出 change 级最终验收结论。
+
+gates:
+  featureLint:
+    command: pnpm sdd:lint-features <change>
+    blocks:
+      - Scenario 缺少 @phase、@validation、@req 或优先级标签。
+      - "@validation 不在允许列表。"
+      - "P0 Scenario 使用 @gap-pending。"
+      - 自动化 Scenario 无法追溯到 requirement。
+
+  taskLint:
+    command: pnpm sdd:lint-tasks <change>
+    blocks:
+      - tasks 中存在 feature 未声明的 phase。
+      - feature 中存在 tasks 未覆盖的 phase。
+      - phase 缺少 acceptance 验证任务。
+
+  phaseAcceptance:
+    command: pnpm sdd:phase <change> <phase>
+    blocks:
+      - P0/P1 自动化 Scenario 没有 100% 结果覆盖。
+      - report 中存在未解释的 mismatch、blocked 或 manual。
+      - 只有 smoke 报告，没有 acceptance report。
+
+  finalAcceptance:
+    command: pnpm sdd:acceptance <change>
+    blocks:
+      - 任意必需 phase gate 未通过。
+      - final acceptance summary 缺失。
+
+failureSemantics:
+  passed: 实现符合 feature 描述。
+  mismatch: 实际行为与 feature 不一致，需要修正实现或 artifact。
+  blocked: 环境、登录、权限、数据或依赖阻塞，当前无法可靠验证。
+  manual: 无法稳定自动化，需要记录人工步骤、证据和接受人。
+  gap-pending: spec 明确未决的延期场景，必须记录原因和后续任务。
+
+fallback:
+  openspecCliUnavailable:
+    allowed: true
+    rule: 当 openspec CLI 不可用但 openspec/changes/<change>/ artifact 存在时，skills 和脚本可以直接消费 artifact 继续执行。
+    report: 必须在总结或 validation report 中记录 CLI 不可用和 fallback 行为。

package/kit/openspec/sdd-e2e-flow.md

@@ -0,0 +1,290 @@
+# 项目级 OpenSpec SDD + E2E 工作流规范
+
+本文定义当前项目的第二层 OpenSpec 规范：不修改 OpenSpec CLI 本体，而是在本仓库中约束 change artifact、Codex skills 和 E2E gate 的协作方式。
+
+规范入口：
+
+- OpenSpec 原生 schema：`openspec/schemas/sdd-e2e/schema.yaml`
+- 项目级契约说明：`openspec/schemas/sdd-e2e.yaml`
+- Change 目录：`openspec/changes/<change>/`
+- Feature 目录：`openspec/changes/<change>/specs/**/features/*.feature`
+- Phase E2E 报告：`specs/e2e/bdd/<change>/validation-report.<phase-id>.md`
+- 升级维护说明：`openspec/sdd-e2e-maintenance.md`
+
+## 分层边界
+
+```text
+OpenSpec 本体 / CLI
+  负责基础 artifact 生命周期，不在本项目中修改
+
+项目级 OpenSpec 规范
+  定义 sdd-e2e schema、artifact 契约、phase gate 和失败语义
+
+Codex Skills / Scripts
+  作为执行器，读取项目级规范并落地到具体 change
+```
+
+本规范实现第二层。第三层的 skills 和 scripts 必须服从本规范。
+
+## 标准生命周期
+
+```text
+proposal
+  -> specs
+    -> features
+      -> design
+        -> tasks
+          -> phase acceptance
+            -> final acceptance
+              -> archive
+```
+
+约束：
+
+- `features` 必须在 specs 之后、design/tasks 最终定稿之前生成。
+- `design` 必须参考 features 暴露的边界、降级、竞态、防重复和跨视图同步风险。
+- `tasks` 必须按 features 中的 `@phase:*` 分组。
+- 每个 phase 必须通过 acceptance gate 才能关闭。
+- smoke 只能验证入口和基础链路，不能替代 acceptance。
+
+## Artifact 契约
+
+每个 `schema: sdd-e2e` 的 change 至少包含：
+
+```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
+```
+
+边界类 Scenario 应包含至少一个风险标签：
+
+```text
+@race-condition
+@degradation
+@anti-duplicate
+@form-validation
+@conditional-render
+@cross-view-sync
+@state-machine
+@feedback
+@negative
+```
+
+规则：
+
+- 没有 `@phase:*` 的 Scenario 不能进入 tasks。
+- 没有 `@req:*` 的 Scenario 不能进入实现。
+- P0 Scenario 不能使用 `@gap-pending`。
+- P1 Scenario 使用 `@gap-pending` 时，必须记录原因和后续任务。
+
+## 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。
+
+## Phase Gate
+
+phase completion 的判定以 acceptance report 为准。
+
+phase acceptance 必须覆盖：
+
+- 当前 phase 下所有不含 `@gap-pending` 的 P0/P1 `@validation:mock-e2e` Scenario。
+- 当前 phase 下所有不含 `@gap-pending` 的 P0/P1 `@validation:real-smoke` Scenario。
+- 被声明为自动化的 P0/P1 Scenario。
+
+phase report 至少包含：
+
+```text
+selected
+automated
+passed
+mismatch
+blocked
+manual
+gap-pending
+gate: passed | failed
+```
+
+以下情况 phase 不能关闭：
+
+- 只有 smoke，没有 acceptance report。
+- 自动化范围内 Scenario 没有 100% 结果覆盖。
+- 存在未解释的 `mismatch`。
+- 存在未解除的 `blocked`。
+- 存在未被产品接受的 `manual`。
+
+## 失败语义
+
+```text
+passed
+  实现符合 feature。
+
+mismatch
+  实际行为与 feature 不一致，需要修正实现或 artifact。
+
+blocked
+  环境、登录、权限、数据或依赖阻塞，当前无法可靠验证。
+
+manual
+  无法稳定自动化，需要记录人工步骤、证据和接受人。
+
+gap-pending
+  spec 明确未决的延期场景，必须记录原因和后续任务。
+```
+
+`blocked` 和 `manual` 默认不算通过。只有明确记录接受原因和责任人时，才能在 final acceptance 中作为已知例外处理。
+
+## Spec Impact Review
+
+主 spec SHOULD 在末尾包含非规范性的 `## Code Scope` 区块，记录当前 spec 对应的主要实现范围。该区块用于归档前影响审查，不属于业务规则。
+
+`Code Scope` 推荐记录：
+
+```yaml
+routes:
+  - <route>
+files:
+  - <source-file>
+apis:
+  - <method> <path>
+gitnexus_processes:
+  - <process name>
+```
+
+归档 change 前，执行者 MUST 比较本次改动范围与已有主 spec 的 `Code Scope` 是否重合。比较基线默认使用 `master`；如果 change、PR 或仓库约定明确使用其他目标分支，则使用该目标分支。
+
+在网络和权限允许时，执行者 SHOULD 先执行 `git fetch origin <base_ref>`，保证本地比较基线尽量接近远端最新状态。随后优先使用 GitNexus compare 模式分析完整影响范围；如果 GitNexus 不可用，则使用 `git diff --name-only <base_ref>...HEAD` 降级检查。
+
+存在重合时，归档摘要 MUST 记录处理结论：
+
+- 已同步更新相关主 spec
+- 行为未变化，不需要更新
+- 仅实现细节重合
+- 需要后续补充 spec gap
+
+如果 fetch、GitNexus compare 或 base ref 不可用，执行者 MUST 记录降级原因，并至少使用 changed files 与 `Code Scope.files` 做降级检查。
+
+## 推荐命令
+
+第一版 gate 只做最小检查：
+
+```bash
+pnpm sdd:lint-features <change>
+pnpm sdd:lint-tasks <change>
+pnpm sdd:phase <change> <phase>
+pnpm sdd:acceptance <change>
+```
+
+命令职责：
+
+- `sdd:lint-features`：检查 Scenario 标签完整性和优先级规则。
+- `sdd:lint-tasks`：检查 feature phase 与 tasks phase 双向一致。
+- `sdd:phase`：检查某个 phase 的 acceptance report。
+- `sdd:acceptance`：聚合所有 phase report，生成 final acceptance summary。
+
+## OpenSpec CLI Fallback
+
+如果当前环境没有 `openspec` CLI，但 `openspec/changes/<change>/` 下存在 artifact，skills 和 scripts 可以直接读取 artifact 继续执行。
+
+fallback 要求：
+
+- 必须记录 `openspec CLI unavailable`。
+- 不允许跳过 feature、tasks 或 acceptance gate。
+- 不允许因为 CLI 不可用而降低 phase completion 标准。
+
+## 使用准则
+
+新需求默认优先使用：
+
+```yaml
+schema: sdd-e2e
+```
+
+小型修复可以继续使用 `spec-driven`，但只要变更涉及 UI 行为、交互状态、发布流程、配置表单、异步请求或跨视图同步，就应使用 `sdd-e2e`。
+
+`sdd-e2e` 不是为了生成更多测试，而是为了让每个开发切片都有可追溯的验收边界。
+
+不要在 `.openspec.yaml` 中继续使用 `schemaFile`。OpenSpec CLI 通过 `openspec/schemas/sdd-e2e/schema.yaml` 自动发现 project-local schema。
+
+## 规则强度
+
+### MUST
+
+- `schema: sdd-e2e` 的 change 必须包含 specs、features、test-cases、design 和 tasks。
+- 每个 Scenario 必须有 `@phase:*`、`@validation:*`、`@req:*` 和优先级标签。
+- P0/P1 Scenario 必须有风险/边界类型标签。
+- tasks 必须与 feature phase 双向一致。
+- 每个 phase 必须有 acceptance 验证任务。
+- phase acceptance report 必须通过 `pnpm sdd:phase <change> <phase>`。
+- final acceptance 必须通过 `pnpm sdd:acceptance <change>` 后才能归档。
+- 归档前必须执行 Spec Impact Review，并在存在 Code Scope 重合时记录处理结论。
+- P0 不允许 `@gap-pending`。
+
+### SHOULD
+
+- UI、异步、表单、发布流程、跨视图同步类变更应该默认使用 `sdd-e2e`。
+- 主 spec 应该包含 `Code Scope`，用于归档前影响审查。
+- 每个 phase 应该控制在可独立验收的小切片。
+- feature 应该优先描述用户可观察行为，避免泄露接口字段和实现细节。
+- smoke 可以作为开发中快速反馈，但应该明确标为 smoke，不能替代 acceptance。
+
+### MAY
+
+- 纯文案、样式微调、无状态的轻量修复可以继续使用 `spec-driven`。
+- P2 场景可以只进入 coverage matrix，不一定进入 phase acceptance。
+- `manual` 可以用于无法稳定自动化的外部依赖场景，但必须记录人工步骤和接受人。
+
+### DEFER
+
+- pilot-run 可以在流程规范和 gate 脚本完成后单独执行。
+- 更复杂的 CI 集成、HTML 报告、跨浏览器矩阵不属于第一版规范的必须范围。

package/kit/openspec/sdd-e2e-maintenance.md

@@ -0,0 +1,98 @@
+# SDD-E2E 维护说明
+
+本文说明如何维护当前项目的 OpenSpec SDD + E2E 流程，尤其是 OpenSpec CLI 升级后如何保护本项目的定制 skill。
+
+## 资产分层
+
+```text
+OpenSpec CLI
+  上游依赖，只通过 npm 升级，不修改包源码
+
+Project schema
+  openspec/schemas/sdd-e2e/schema.yaml
+  openspec/schemas/sdd-e2e/templates/*
+
+Project contract
+  openspec/schemas/sdd-e2e.yaml
+  openspec/sdd-e2e-flow.md
+  SDD_E2E_FLOW.md
+
+Project executor
+  .codex/skills/openspec-*
+  .codex/skills/spec-to-gherkin
+  .codex/skills/feature-to-e2e
+  scripts/sdd/*
+```
+
+OpenSpec CLI 负责 artifact 图、instructions、templates 和基础 status。`scripts/sdd/*` 负责本项目的语义 gate。不要把 `openspec status isComplete=true` 当作 phase 或 final acceptance 通过。
+
+## Skill 策略
+
+`.codex/skills/openspec-*` 是本项目的 sdd-e2e overlay，不再视为可被 `openspec update` 直接覆盖的纯官方生成物。
+
+维护规则：
+
+- 可以吸收 OpenSpec 官方 skill 的新命令、新字段和 bug fix。
+- 必须保留 `schema: sdd-e2e` 默认策略、artifact 顺序、phase gate、final acceptance gate。
+- 不允许恢复 `schemaFile` fallback。
+- 不允许在 `sdd-e2e` 适用场景静默 fallback 到 `spec-driven`。
+- 不允许把 smoke、manual、blocked 或 OpenSpec artifact complete 当作 phase complete。
+
+## OpenSpec 升级流程
+
+升级 OpenSpec CLI 后，不要先在当前项目运行 `openspec update`。
+
+推荐步骤：
+
+```bash
+openspec --version
+npm view @fission-ai/openspec version dist-tags --json
+openspec schema validate sdd-e2e --json
+openspec schemas --json
+```
+
+如果要查看新版官方 skill，生成到临时目录，并重定向 `CODEX_HOME`，避免写入真实的 `~/.codex/prompts`：
+
+```bash
+tmp="$(mktemp -d)"
+CODEX_HOME="$tmp/codex-home" openspec init "$tmp/project" --tools codex
+diff -ru "$tmp/project/.codex/skills" ".codex/skills"
+```
+
+只手动合并对本项目有价值的差异。合并后运行：
+
+```bash
+openspec schema validate sdd-e2e --json
+openspec instructions proposal --change codify-sdd-e2e-flow --json
+openspec instructions apply --change codify-sdd-e2e-flow --json
+pnpm sdd:self-test
+pnpm sdd:lint-features codify-sdd-e2e-flow
+pnpm sdd:lint-tasks codify-sdd-e2e-flow
+```
+
+如果确实需要运行 `openspec update`，先确认当前 `.codex/skills/openspec-*` 已有备份或可从 git diff 恢复，并确认是否会写入全局 Codex prompts。
+
+## 新项目迁移清单
+
+最小迁移包：
+
+- `openspec/config.yaml`
+- `openspec/schemas/sdd-e2e/schema.yaml`
+- `openspec/schemas/sdd-e2e/templates/*`
+- `openspec/schemas/sdd-e2e.yaml`
+- `openspec/sdd-e2e-flow.md`
+- `openspec/sdd-e2e-maintenance.md`
+- `SDD_E2E_FLOW.md`
+- `.codex/skills/openspec-*`
+- `.codex/skills/spec-to-gherkin`
+- `.codex/skills/feature-to-e2e`
+- `scripts/sdd/*`
+- `package.json` 中的 `sdd:*` scripts
+
+迁移后先运行：
+
+```bash
+openspec schema validate sdd-e2e --json
+openspec schemas --json
+pnpm sdd:self-test
+```

package/kit/scripts/sdd/check-report.mjs

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getChangeName, reportResult, validatePhaseReport } from './lib.mjs';
+
+const change = getChangeName();
+const phase = process.argv[3];
+const errors = [];
+
+if (!phase) {
+  errors.push('Usage: pnpm sdd:phase <change> <phase>');
+  reportResult(`sdd:phase ${change}`, errors);
+  process.exit();
+}
+
+const reportPath = path.join(
+  process.cwd(),
+  'specs',
+  'e2e',
+  'bdd',
+  change,
+  `validation-report.${phase}.md`,
+);
+
+if (!fs.existsSync(reportPath)) {
+  errors.push(`phase report not found: ${reportPath}`);
+  reportResult(`sdd:phase ${change} ${phase}`, errors);
+  process.exit();
+}
+
+if (fs.existsSync(reportPath)) {
+  errors.push(...validatePhaseReport(change, phase, reportPath).errors);
+}
+
+reportResult(`sdd:phase ${change} ${phase}`, errors);