openspec-sdd-e2e-kit 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# OpenSpec SDD-E2E Kit
+
+A portable OpenSpec project-local schema, Codex skill overlay, and SDD/E2E gate scripts for phase-based Spec Driven Development.
+
+## Usage
+
+From a target project root, install the kit assets with one command:
+
+```bash
+npx openspec-sdd-e2e-kit
+```
+
+Preview the writes first:
+
+```bash
+npx openspec-sdd-e2e-kit --dry-run
+```
+
+From this repository:
+
+```bash
+node bin/sdd-e2e-kit.mjs
+node bin/sdd-e2e-kit.mjs check /path/to/project
+node bin/sdd-e2e-kit.mjs diff /path/to/project
+node bin/sdd-e2e-kit.mjs install /path/to/project
+```
+
+After publishing or linking as a package:
+
+```bash
+sdd-e2e-kit
+sdd-e2e-kit check /path/to/project
+sdd-e2e-kit diff /path/to/project
+sdd-e2e-kit install /path/to/project
+```
+
+## Commands
+
+- Running without a command installs the kit into the current working directory.
+- `check`: verify required assets and `package.json` `sdd:*` scripts exist.
+- `diff`: compare a target project against the kit baseline.
+- `install`: copy assets and merge `sdd:*` scripts. Changed target files are not overwritten unless `--force` is used.
+- `update`: alias for `install`; still conservative by default.
+
+## Installed Assets
+
+The installable baseline lives in `kit/` and includes:
+
+- OpenSpec `sdd-e2e` schema and templates
+- SDD-E2E workflow documentation
+- Codex OpenSpec skills and E2E helper skills
+- `scripts/sdd/*` semantic gate scripts
+- `package.json` `sdd:*` script definitions from `kit/manifest.json`
+
+## Target Project Validation
+
+Run these in a target project after install:
+
+```bash
+openspec schema validate sdd-e2e --json
+openspec schemas --json
+pnpm sdd:self-test
+```

package/bin/sdd-e2e-kit.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const argv = process.argv.slice(2);
+const [firstArg, ...remainingArgs] = argv;
+const commands = {
+  check: "src/check.mjs",
+  diff: "src/diff.mjs",
+  install: "src/install.mjs",
+  update: "src/install.mjs",
+};
+
+function help() {
+  console.log([
+    "Usage: sdd-e2e-kit [command] [target] [options]",
+    "",
+    "Running without a command installs the kit into the current working directory.",
+    "",
+    "Commands:",
+    "  check    Check whether a project has the kit assets and scripts",
+    "  diff     Compare a project against the kit baseline",
+    "  install  Install kit assets into a project",
+    "  update   Alias for install; conflicts still require --force",
+    "",
+    "Examples:",
+    "  sdd-e2e-kit",
+    "  sdd-e2e-kit --dry-run",
+    "  sdd-e2e-kit check /path/to/project",
+    "  sdd-e2e-kit diff /path/to/project",
+    "  sdd-e2e-kit install /path/to/project",
+  ].join("\n"));
+}
+
+if (firstArg === "--help" || firstArg === "-h") {
+  help();
+  process.exit(0);
+}
+
+const command = firstArg && commands[firstArg] ? firstArg : "install";
+const args = firstArg && commands[firstArg] ? remainingArgs : argv;
+const script = commands[command];
+
+if (firstArg && !commands[firstArg] && !firstArg.startsWith("-")) {
+  console.error(`Unknown command: ${firstArg}`);
+  help();
+  process.exit(1);
+}
+
+const result = spawnSync(process.execPath, [path.join(root, script), ...args], { stdio: "inherit" });
+process.exit(result.status ?? 1);

package/kit/.codex/skills/feature-to-e2e/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: feature-to-e2e
+description: 在需求开发完成后或某个 OpenSpec phase 完成后，根据 .feature BDD 验收场景直接操作真实页面，支持按 @phase/@validation 标签筛选小范围场景，生成并运行 Playwright 脚本，记录交互步骤、断言、证据和执行结果，用于判断实现逻辑是否符合 feature 描述。适用于实现后的验收或 phase 级 acceptance gate，不用于搭建 Cucumber 基建或长期 CI 回归套件。
+---
+
+# Skill: Feature 到 E2E 验收验证
+
+## 定位
+
+`feature-to-e2e` 用于**开发完成后的功能验收**，也用于 OpenSpec SDD 流程中**单个 phase 完成后的切片验收**。
+
+以 `.feature` 文件为验收真相，用真实浏览器打开页面、点击、输入、观察状态，并把实际操作沉淀为可运行的 Playwright Test。生成脚本默认尽量复用一个浏览器窗口、一个 context、一个 page，按 feature 中的 Scenario 顺序执行。最终输出每个 Scenario 的验证结果：`passed`、`mismatch`、`blocked`、`manual` 或 `gap-pending`。
+
+默认目标是回答一个问题：**当前实现是否符合 feature 描述？**
+
+在 phase 验证模式下，默认目标是回答：**当前 phase 的实现是否满足带有同一 `@phase:<id>` 标签的 Scenario？**
+
+Phase 验证默认是 **acceptance gate**，不是 smoke gate。只验证每个 phase 的代表性主链路不足以判断实施质量；除非用户明确要求 smoke，否则必须覆盖当前 phase 下所有不含 `@gap-pending` 且 `@validation` 可自动化的 P0/P1 Scenario，尤其是输入校验、失败降级、竞态、防重复、条件渲染、跨视图同步等边界场景。
+
+如果 change 使用 `schema: sdd-e2e`，本 skill 是 `openspec/schemas/sdd-e2e.yaml` 中 `phaseAcceptance` gate 的执行器。生成报告后必须能被 `pnpm sdd:phase <change> <phase>` 检查。
+
+## 不做什么
+
+- 不生成 Cucumber runner、step definitions、World 或 hooks。
+- 不把页面当前行为反向改写成规格。
+- 不为了通过测试删除、弱化或跳过 feature 中的业务断言。
+- 不默认建设 CI 回归套件、复杂 fixture 平台或长期测试资产。
+- 不默认做异常注入、网络 mock、性能测试或跨浏览器矩阵，除非 feature 明确要求或用户明确指定。
+- 不猜测登录账号、验证码、token、权限或绕过鉴权方式。
+- 不在用户只要求某个 phase 时全量验证整个 features 目录。
+- 不把 phase smoke 结果当作 phase 完成条件；smoke 只能证明入口和基础链路可用，不能替代边界 Scenario 验收。
+
+## 输入
+
+- 一个 `.feature` 文件或一个 features 目录。
+- 可选的场景筛选条件：`@phase:<id>`、`@validation:<type>`、单个 Scenario 名称或用户指定的 tags。
+- 应用入口 URL、dev server 命令或已有 Playwright `baseURL`。
+- 登录态、测试账号、`storageState`、登录 helper 或其他可执行认证方式。
+- 必要的测试数据、seed 方式或可安全操作的 E2E 测试数据范围。
+- 项目已有 Playwright config、测试目录、脚本和 helper。
+
+缺少入口、鉴权处理方式或关键测试数据时，先暂停并向用户询问具体缺口。
+
+如果 features 中存在 `@phase:*` 标签但用户没有指定验证范围，不要默认全量执行所有 phase；先询问要验证哪个 phase，或在用户明确要求“全量验收”时再执行全量。
+
+## 输出
+
+把产物放在项目 Playwright config 可发现的测试目录下。推荐最小结构：
+
+```text
+<testDir>/bdd/<feature-slug>/
+├── <feature-slug>.validation.spec.ts
+├── validation-report.md
+└── evidence/
+    └── screenshots/      # 仅在需要时生成
+```
+
+Phase 验证模式推荐结构：
+
+```text
+<testDir>/bdd/<feature-slug>/
+├── <phase-id>.validation.spec.ts
+├── validation-report.<phase-id>.md
+└── evidence/
+    └── screenshots/
+```
+
+`schema: sdd-e2e` 的 phase report 默认写入：
+
+```text
+specs/e2e/bdd/<change>/validation-report.<phase-id>.md
+```
+
+必须产出：
+
+- 可运行的 Playwright Test 脚本。
+- 脚本默认在单一窗口上下文中顺序执行；无法这样执行时说明原因。
+- 明确的运行命令。
+- 每个 Scenario 的执行结果。
+- 报告中明确记录验证范围：全量、`@phase:<id>`、`@validation:<type>` 或具体 Scenario。
+- Scenario coverage：列出选中的 Scenario 总数、已自动化数、passed/mismatch/blocked/manual/gap 数；phase acceptance gate 要求自动化范围内 Scenario 100% 有结果。
+- 失败分类：产品 `mismatch`、环境/数据 `blocked`，或测试脚本问题并已修复重跑。
+
+生成粒度约束：
+
+- 默认一次只根据一个 `.feature` 文件生成、运行和报告 Playwright 脚本。
+- 当输入是 features 目录时，先列出待处理 `.feature` 文件并选择下一个文件；不要一次性生成整个目录的所有 Playwright 脚本。
+- 用户明确要求“全量生成/全量验收”时，也必须按 feature 文件顺序逐个生成、逐个检查、逐个记录结果；不要在同一次编辑中批量写出所有 spec。
+- 完成一个 feature 文件后，在报告中记录结果和下一个候选 feature 文件，再继续下一个。
+
+混合 validation 输出策略：
+
+- 当同一 feature 目录同时包含 `@validation:real-smoke` 和 `@validation:mock-e2e`，按 feature 文件继续拆 spec；如果同一 feature 文件内两类 validation 并存，拆成 `<feature>.real-smoke.spec.ts` 和 `<feature>.mock-e2e.spec.ts`。
+- `real-smoke` spec 不得安装目标业务接口 mock，不得导入 mock data fixture；只允许使用真实页面、真实鉴权和真实后端接口。
+- `mock-e2e` spec 可以使用 `page.route` mock 目标业务接口，用于失败、异常、竞态、边界、特定条件渲染等可控状态。
+- 页面操作 helper 可复用；API mock、mock state、mock data builder 必须只被 `mock-e2e` spec 引用。
+- 报告必须分别统计 `real-smoke` 与 `mock-e2e` 的 selected、automated、passed、mismatch、blocked、manual、gap-pending。
+
+## 工作流
+
+0. **执行前鉴权确认**
+
+   - 在生成或运行脚本前，先检查项目是否有登录页、路由守卫、鉴权 store、token/cookie、`storageState`、auth helper 或已有登录测试。
+   - 必须向用户做一次确认：本次 feature 验收入口是否需要登录或特定权限？
+   - 如果需要鉴权，先询问用户采用哪种方式：测试账号登录、已有 `storageState`、登录 helper、seed/session 脚本，或用户指定的其他方式。
+   - 未确认鉴权方式前，不要继续生成不可运行的测试脚本。
+   - 如果用户确认无需鉴权，在报告中记录 `auth: not required`。
+
+1. **预检**
+
+   - 识别包管理器、Playwright config、`testDir`、`baseURL` 和可用测试命令。
+   - 确认应用能启动或目标 URL 可访问。
+   - 确认已按用户指定方式处理鉴权，并确认基础数据足够执行 feature。
+   - 如果缺少 `@playwright/test` 或 config，先报告缺失项；只有用户确认后才创建基建或安装依赖。
+
+2. **解析 feature**
+
+   - 读取 Feature、Rule、Background、Scenario、Scenario Outline、Examples、tags 和原始 steps。
+   - 如果输入是 features 目录，按文件名或用户指定顺序选择一个 `.feature` 文件作为当前处理对象；本轮只解析、生成和运行该文件对应的场景。
+   - 默认验证用户指定的场景；如果用户指定 `@phase:<id>` 或 `@validation:<type>`，只选择同时满足筛选条件且不含 `@gap-pending` 的 Scenario。
+   - 未指定范围时，验证当前 `.feature` 文件内所有不含 `@gap-pending` 且可自动化的 Scenario；不要跨文件扩展范围。
+   - 如果用户要求全量 features 目录，仍然按 feature 文件逐个处理，每完成一个文件再进入下一个文件。
+   - 保留每个 Scenario 到原始 feature step 的追溯关系。
+   - 执行 step coverage review：每个选中 Scenario 的关键 Given/When/Then 必须映射到 Playwright 的前置、动作或断言；不能只因为 Scenario 名称存在就视为覆盖。
+   - 如果 feature 明确区分多个交互入口（按钮、Enter、快捷键、菜单等），每个 P0/P1 入口必须有独立动作或断言；缺失时先补脚本或将其标为 blocked/mismatch，不能静默通过。
+   - `@validation:real-smoke` 必须不 mock 目标业务接口；如果只是真实页面入口 + mocked 业务接口，应在报告中标明 hybrid 性质，并建议 feature 改为 `mock-e2e` 或 schema 允许的更精确标签。
+   - `@validation:real-smoke` 场景如果引用固定业务实体，先验证真实环境是否存在；不存在则标 `blocked`，不能改用 mock 偷跑。
+   - 在报告中按 phase 汇总 Scenario 数、验证类型和未选中原因。
+   - Phase acceptance gate 下，所有 `@p0` / `@p1` 且 `@validation:mock-e2e` 或 `@validation:real-smoke` 的 Scenario 都必须进入执行计划；仅 `@gap-pending`、`@validation:manual` 或明确无法稳定自动化的 Scenario 可以不生成自动化测试，但必须在报告中标 `blocked` 或 `manual` 并说明原因。
+
+3. **操作真实页面**
+
+   - 从干净浏览器上下文开始执行，默认复用同一个 `page`。
+   - 按 feature 文件中的 Scenario 顺序和 Gherkin step 顺序，在同一个页面上点击、输入、选择、等待和断言。
+   - 优先使用稳定 locator：role、label、text、test id；避免随机 class、深层 CSS 和无意义 `nth()`。
+   - 每个关键 step 都记录实际 locator、动作、观察到的页面状态和对应断言。
+
+4. **生成 Playwright 脚本**
+
+   - 使用原生 `@playwright/test`：`test.describe`、`test`、`test.step`、`expect`。
+   - Phase 验证模式下，默认只生成当前 phase 的小型 spec，文件名使用 `<phase-id>.validation.spec.ts`，但该 spec 必须覆盖当前 phase 的全部自动化 Scenario；需要 smoke 时使用 `<phase-id>.smoke.spec.ts`，且报告不得把 smoke 标记为 acceptance gate passed。
+   - 默认生成一个 `test(...)`，在其中用 `test.step` 按顺序表达 Background、Scenario 和关键 step，避免 Playwright 为每个 Scenario 重开独立上下文。
+   - 如果需要更清晰的 Scenario 分段，可以使用 `test.describe.serial` 加共享 `context/page`，但仍应保持一个窗口顺序执行。
+   - 只有当场景互相污染、必须验证刷新后的初始状态、权限/数据要求冲突，或单窗口会掩盖真实问题时，才拆成多个独立 `test(...)`；拆分原因必须写入报告。
+   - 对写操作只使用可识别的 E2E 测试数据，并记录 cleanup 或兜底清理方式。
+   - 对 `real-smoke` 写操作，必须具备用户确认的测试数据范围和 cleanup/rollback 方案；缺少任一条件时标 `blocked`，不要降级成 mock 后继续声称验证真实主链路。
+   - 对 `mock-e2e` 场景，mock fixture 应只覆盖选中 Scenario 所需状态；不要为 real-smoke 主流程安装目标业务接口 mock。
+   - 对 locator action、navigation 和断言设置显式超时，避免缺失元素拖到整条测试超时；长链路全量验证不应使用无限等待。
+   - 对 P0/P1 Scenario 执行断言强度 checklist：请求次数、关键 payload、UI 可见性、消息/行/卡片归属、顺序、负向断言、错误/降级状态至少覆盖适用项；只断言“元素出现”不足以证明归属或竞态安全。
+   - 如果 feature 要求“分别对应”“不覆盖”“不污染”“不阻塞”，脚本必须有对应的负向或顺序断言，例如 `toHaveCount`、payload 检查、区域限定 locator、文本顺序检查或旧响应不展示。
+   - 人类节奏延迟只作为 headed 演示辅助，不应成为默认验收行为。默认脚本应尽量快速稳定；需要演示时通过环境变量（如 `E2E_HUMAN_ACTION_DELAY_MS`）放慢。
+
+5. **执行并修正测试脚本**
+
+   - 运行生成的 spec，例如 `pnpm exec playwright test <target-spec>`。
+   - 如果失败，先判断是否是 locator、等待、断言表达等测试脚本问题；这类问题应修复后重跑。
+   - 不得通过降低业务断言、条件跳过或吞掉失败来制造通过。
+
+6. **判定结果**
+   - `passed`：脚本通过，实际页面行为符合 feature。
+   - `mismatch`：脚本能稳定复现，但产品行为与 feature 描述不一致；保留失败断言并写入报告。
+   - `blocked`：入口、登录、权限、数据、环境或需求歧义导致无法可靠验证；写清缺少什么。
+   - `manual`：无法稳定自动化，需要记录人工步骤、证据和接受人；默认不算 passed。
+   - `gap-pending`：spec 明确未决的延期场景，必须记录原因和后续任务；P0 不允许该状态。
+
+## 报告要求
+
+`validation-report.md` 至少包含：
+
+- feature 文件路径和验证范围。
+- 如果是 phase 验证，记录 phase id、validation 类型筛选、选中 Scenario 数、未选中 Scenario 数。
+- 鉴权判断和处理方式：不需要鉴权、测试账号登录、`storageState`、登录 helper、或 blocked 原因。
+- 运行命令、运行时间和运行结果。
+- Scenario 结果表：名称、tags、状态、证据路径、失败原因。
+- Coverage gate：`selected`、`automated`、`passed`、`mismatch`、`blocked`、`manual`、`gap-pending`，并明确 `gate: passed | failed`。
+- Step coverage 摘要：说明关键 Given/When/Then 是否都有动作或断言；如有未覆盖 step，记录原因和处置结果。
+- 断言强度摘要：列出 P0/P1 场景覆盖了哪些关键断言类型（请求次数、payload、UI 归属、顺序、负向断言、错误/降级状态等），并记录接受的残余风险。
+- mismatch 列表：期望、实际、复现步骤、对应断言。
+- blocker 列表：缺失条件、影响的 Scenario、需要用户提供的信息。
+- 生成或修改的 Playwright 脚本路径。
+- 对 `schema: sdd-e2e`，报告必须显式包含 `gate: passed` 或 `gate: failed`，并在最终回复中说明是否已运行 `pnpm sdd:phase <change> <phase>`。
+
+最终回复用户时，简要说明：
+
+- 验证了哪些 Scenario。
+- 哪些通过、哪些 mismatch、哪些 blocked。
+- Playwright 脚本和报告路径。
+- 没能验证的原因。

package/kit/.codex/skills/feature-to-e2e/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Feature E2E 验收"
+  short_description: "先确认鉴权，再按 .feature 单窗口顺序验收"
+  default_prompt: "使用 $feature-to-e2e 先确认本次验收是否需要鉴权以及处理方式，再根据 .feature 操作真实页面，尽量在一个窗口上下文中顺序生成并运行 Playwright 脚本，报告实现是否符合功能描述。"

package/kit/.codex/skills/openspec-apply-change/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: openspec-apply-change
+description: 实现一个 OpenSpec 变更中的 tasks。适用于用户想开始实现、继续实现，或逐项完成 tasks 时。
+license: MIT
+compatibility: 需要 openspec CLI。
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+  projectOverlay: "sdd-e2e"
+---
+
+实现一个 OpenSpec 变更中的 tasks。
+
+**输入**：可以指定变更名称。如果未指定，先尝试从对话上下文推断；如果含糊或存在歧义，必须让用户从可用变更中选择。
+
+**步骤**
+
+1. **选择变更**
+
+   如果提供了名称，直接使用。否则：
+   - 如果用户在对话中提到过某个变更，尝试从上下文推断
+   - 如果只有一个 active change，可以自动选择
+   - 如果存在歧义，运行 `openspec list --json` 获取可用变更，并使用 **AskUserQuestion tool** 让用户选择
+
+   始终声明："Using change: <name>"，并说明如何覆盖，例如 `/opsx:apply <other>`。
+
+2. **检查状态，理解 schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   解析 JSON，理解：
+   - `schemaName`：当前使用的工作流，例如 `"spec-driven"`
+   - 哪个 artifact 包含 tasks（spec-driven 通常是 `"tasks"`，其他 schema 需要看 status）
+
+   如果 `openspec/changes/<name>/.openspec.yaml` 声明 `schema: sdd-e2e`，读取 `openspec/schemas/sdd-e2e/schema.yaml`、`openspec/schemas/sdd-e2e.yaml` 和 `openspec/sdd-e2e-flow.md`，并把 features、tasks、phaseReports、finalAcceptance 作为项目级必需契约。
+
+3. **获取 apply 指令**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   该命令返回：
+   - 上下文文件路径（随 schema 而变，可能是 proposal/specs/design/tasks，也可能是 spec/tests/implementation/docs）
+   - 进度（总数、已完成、剩余）
+   - task 列表及状态
+   - 基于当前状态的动态指令
+
+   **处理状态：**
+   - 如果 `state: "blocked"`（缺少 artifact）：展示信息，并建议使用 `openspec-continue-change`
+   - 如果 `state: "all_done"`：告知已完成，并建议 archive
+   - 否则：进入实现
+
+4. **读取上下文文件**
+
+   读取 apply instructions 输出中 `contextFiles` 列出的文件。
+   文件取决于当前 schema：
+   - **spec-driven**：proposal、specs、design、tasks
+   - 其他 schema：遵循 CLI 输出中的 contextFiles
+   - 项目验证扩展：如果变更包含 `specs/**/features/*.feature` 或 `test-cases.md`，即使 OpenSpec schema 没有列出，也要作为验证上下文读取。使用其中的 `@phase:*` 和 `@validation:*` 标签理解 phase 边界和预期验证方式。
+   - `schema: sdd-e2e`：必须读取 `openspec/schemas/sdd-e2e/schema.yaml`、`openspec/sdd-e2e-flow.md`、features、`test-cases.md` 和 `tasks.md`；开始实现前先运行 `pnpm sdd:lint-features <change>` 与 `pnpm sdd:lint-tasks <change>`。
+   - 修改源码函数、类或方法前，遵守项目 `AGENTS.md`：先做 GitNexus impact analysis，并在高风险时向用户报告后再继续。
+
+5. **展示当前进度**
+
+   展示：
+   - 当前使用的 schema
+   - 进度：`"N/M tasks complete"`
+   - 剩余 tasks 概览
+   - CLI 返回的动态指令
+
+6. **实现 tasks（循环直到完成或阻塞）**
+
+   对每个待办 task：
+   - 展示当前正在处理的 task
+   - 完成所需代码修改
+   - 保持修改最小、聚焦
+   - 在 tasks 文件中将 task 标记为完成：`- [ ]` -> `- [x]`
+   - 继续下一个 task
+
+   **Phase 验证扩展：**
+   - 如果 `tasks.md` 按 phase 分组，先完成一个 phase 的实现任务，再进入下一个 phase。
+   - 如果某个 phase 有类似 "验证 @phase:<id>" 的验证任务，必须为该 phase 调用项目 `feature-to-e2e` 工作流，而不是生成整目录的大范围 E2E。
+   - 验证命令和报告只能面向同一个 `@phase:<id>` 且兼容 `@validation:*` 类型的 Scenario。
+   - 只有当该 phase 中所有选中的自动化 Scenario 都生成 acceptance report 后，才能把 phase 验证任务标记完成。开发中可以使用 smoke spec，但 smoke 不足以关闭 phase。
+   - acceptance report 必须包含 Scenario 覆盖计数。对于 P0/P1 的 `@validation:mock-e2e` 或 `@validation:real-smoke`，覆盖率必须是 100%，除非 Scenario 明确标注为 `@gap-pending`，或带原因标记为 `manual/blocked`。
+   - 如果报告包含 `mismatch`、`blocked`、未被产品明确接受的 `manual`，或存在未覆盖的自动化 Scenario，记录结果并暂停。不要通过削弱断言或把 acceptance 降级成 smoke 来标记 phase 完成。
+   - 不要仅因为代码 task 完成就把整个 phase 标记完成；phase 完成的条件是实现任务和验证任务都处理完。
+   - 对 `schema: sdd-e2e`，每个 phase 验证前后都运行对应 gate：
+     - 实现前：`pnpm sdd:lint-features <change>`、`pnpm sdd:lint-tasks <change>`
+     - phase 后：`pnpm sdd:phase <change> <phase>`
+     - 全部 phase 后：`pnpm sdd:acceptance <change>`
+   - `pnpm sdd:phase` 未通过时，不要勾选该 phase 的 Acceptance 验证任务。
+   - `pnpm sdd:acceptance` 通过后，才创建或更新 `openspec/changes/<change>/acceptance-coverage.md` 并建议归档。
+
+   **以下情况需要暂停：**
+   - Task 不清楚 -> 询问澄清
+   - 实现暴露设计问题 -> 建议更新 artifact
+   - 遇到错误或阻塞 -> 报告并等待指导
+   - 用户中断
+
+7. **完成或暂停时展示状态**
+
+   展示：
+   - 本轮完成的 tasks
+   - 总进度：`"N/M tasks complete"`
+   - 如果全部完成：建议 archive
+   - 如果暂停：说明原因并等待指导
+
+**实现过程中的输出格式**
+
+```text
+## 正在实现：<change-name>（schema: <schema-name>）
+
+正在处理 task 3/7：<task description>
+[...正在实现...]
+✓ Task 已完成
+
+正在处理 task 4/7：<task description>
+[...正在实现...]
+✓ Task 已完成
+```
+
+**完成时的输出格式**
+
+```text
+## 实现完成
+
+**变更：** <change-name>
+**Schema:** <schema-name>
+**进度：** 7/7 tasks complete ✓
+
+### 本轮完成
+- [x] Task 1
+- [x] Task 2
+...
+
+所有 tasks 已完成，可以归档该变更。
+```
+
+**暂停时的输出格式（遇到问题）**
+
+```text
+## 实现已暂停
+
+**变更：** <change-name>
+**Schema:** <schema-name>
+**进度：** 4/7 tasks complete
+
+### 遇到的问题
+<问题描述>
+
+**选项：**
+1. <选项 1>
+2. <选项 2>
+3. 其他方案
+
+你希望怎么处理？
+```
+
+**约束**
+- 持续推进 tasks，直到完成或被阻塞
+- 开始前必须读取上下文文件（来自 apply instructions 输出）
+- 如果 task 有歧义，实现前暂停并询问
+- 如果实现暴露问题，暂停并建议更新 artifact
+- 代码修改保持最小，并限定在当前 task 范围内
+- 完成每个 task 后立即更新 checkbox
+- 遇到错误、阻塞或需求不清晰时暂停，不要猜测
+- 使用 CLI 输出中的 contextFiles，不要假设固定文件名
+- 对 `schema: sdd-e2e`，不得把 `manual`、`blocked` 或只跑 smoke 的结果当作 phase 完成
+- 对 `schema: sdd-e2e`，不要把 OpenSpec `status.isComplete` 当作实现完成或归档依据；语义完成以 `pnpm sdd:*` gate 为准
+
+**流式工作流集成**
+
+该 skill 支持“围绕 change 执行动作”的模型：
+
+- **可以随时调用**：可以在所有 artifact 完成前（只要存在 tasks）、部分实现后，或与其他动作交错调用
+- **允许更新 artifact**：如果实现暴露设计问题，建议更新 artifact；不要被 phase 锁死，可以流式推进
+- **允许 phase 验证循环**：如果 phase E2E 暴露 spec 缺口或设计 mismatch，在继续前更新相关 spec/feature/design/task artifact，而不是通过削弱断言强行让测试通过

package/kit/.codex/skills/openspec-archive-change/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: openspec-archive-change
+description: 归档一个已经完成的 OpenSpec 变更。适用于用户想在实现完成后最终收口并归档变更时。
+license: MIT
+compatibility: 需要 openspec CLI。
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+  projectOverlay: "sdd-e2e"
+---
+
+归档实验性工作流中的已完成变更。
+
+**输入**：可以指定变更名称。如果未指定，先尝试从对话上下文推断；如果含糊或存在歧义，必须让用户从可用变更中选择。
+
+**步骤**
+
+1. **如果未提供变更名称，让用户选择**
+
+   运行 `openspec list --json` 获取可用变更。使用 **AskUserQuestion tool** 让用户选择。
+
+   只展示 active changes（不包含已归档变更）。
+   如果可用，展示每个变更使用的 schema。
+
+   **重要**：不要猜测或自动选择变更，始终让用户选择。
+
+2. **检查 artifact 完成状态**
+
+   运行 `openspec status --change "<name>" --json` 检查 artifact 完成情况。
+
+   解析 JSON，理解：
+   - `schemaName`：当前使用的工作流
+   - `artifacts`：artifact 列表及其状态（`done` 或其他）
+
+   **如果有任何 artifact 不是 `done`：**
+   - 展示警告，列出未完成 artifact
+   - 使用 **AskUserQuestion tool** 确认用户是否仍要继续
+   - 用户确认后继续
+
+3. **检查 task 完成状态**
+
+   读取 tasks 文件（通常是 `tasks.md`），检查是否存在未完成任务。
+
+   统计 `- [ ]`（未完成）和 `- [x]`（已完成）的 task 数量。
+
+   **如果发现未完成 tasks：**
+   - 展示警告，说明未完成数量
+   - 使用 **AskUserQuestion tool** 确认用户是否仍要继续
+   - 用户确认后继续
+
+   **如果不存在 tasks 文件**：跳过 task 相关警告并继续。
+
+4. **检查 SDD-E2E final acceptance**
+
+   如果 `openspec/changes/<name>/.openspec.yaml` 声明 `schema: sdd-e2e`：
+
+   - 读取 `openspec/schemas/sdd-e2e/schema.yaml`、`openspec/schemas/sdd-e2e.yaml` 和 `openspec/sdd-e2e-flow.md` 作为项目级归档规则。
+   - 先运行：
+     ```bash
+     pnpm sdd:acceptance <name>
+     ```
+   - 检查 `openspec/changes/<name>/acceptance-coverage.md` 是否存在，且 final acceptance 包含 `Final gate: passed` 或等价的 passed 结论。
+   - 如果 final acceptance 未通过，停止归档并展示失败原因。只有当用户明确要求“带例外归档”时，才允许继续，并在摘要中记录该例外。
+
+   **重要**：`schema: sdd-e2e` 的 change 不能因为 tasks 勾选完成就默认可归档；final acceptance 是归档前质量门禁。
+
+5. **执行 Spec Impact Review**
+
+   归档前必须检查本次 change 是否影响已有主 spec 的代码范围：
+
+   - 确定归档比较基线：默认使用 `master`；如果 change、PR 或仓库约定明确使用其他目标分支，则使用该目标分支。
+   - 在网络和权限允许时，先执行 `git fetch origin <base_ref>`，保证本地比较基线尽量接近远端最新状态。
+   - 优先运行 `gitnexus_detect_changes(scope: "compare", base_ref: <base_ref>)`，获取本次 change 相对归档基线影响的 symbols、files、processes 和 APIs。
+   - 如果 GitNexus compare 不可用，降级运行 `gitnexus_detect_changes(scope: "all")`，并在归档摘要中记录降级原因。
+   - 读取所有 `openspec/specs/*/spec.md` 中的 `## Code Scope` 区块。
+   - 比较本次改动范围与已有主 spec 的 `Code Scope` 是否重合。
+
+   **如果存在重合：**
+   - 在继续归档前展示重合项，包括 spec、files、processes 或 APIs。
+   - 必须记录处理结论，且结论必须属于以下之一：
+     - 已同步更新相关主 spec
+     - 行为未变化，不需要更新
+     - 仅实现细节重合
+     - 需要后续补充 spec gap
+   - 不允许在存在重合时静默归档。
+
+   **如果无法运行 GitNexus：**
+   - 优先使用 `git diff --name-only <base_ref>...HEAD` 作为降级检查。
+   - 如果无法确定或读取 `<base_ref>`，合并 `git diff --name-only` 与 `git diff --name-only --cached` 的结果作为工作区降级检查。
+   - 在归档摘要中记录降级原因和检查结论。
+
+6. **评估 delta spec 同步状态**
+
+   检查 `openspec/changes/<name>/specs/` 下是否存在 delta specs。如果不存在，跳过同步提示。
+
+   **如果存在 delta specs：**
+   - 将每个 delta spec 与对应主 spec `openspec/specs/<capability>/spec.md` 比较
+   - 判断会应用哪些变化（新增、修改、删除、重命名）
+   - 在询问用户前，展示合并后的摘要
+
+   **提示选项：**
+   - 如果需要同步："Sync now (recommended)"、"Archive without syncing"
+   - 如果已经同步："Archive now"、"Sync anyway"、"Cancel"
+
+   如果用户选择同步，使用 Task tool（`subagent_type: "general-purpose"`，prompt: `"Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"`）。无论是否同步，随后继续归档。
+
+7. **执行归档**
+
+   如果 archive 目录不存在，先创建：
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   使用当前日期生成目标名称：`YYYY-MM-DD-<change-name>`
+
+   **检查目标是否已存在：**
+   - 如果存在：报错，并建议重命名已有 archive 或使用不同日期
+   - 如果不存在：移动 change 目录到 archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+8. **展示摘要**
+
+   展示归档完成摘要，包括：
+   - 变更名称
+   - 使用的 schema
+   - 归档位置
+   - specs 是否已同步（如适用）
+   - Spec Impact Review 结论
+   - 关于任何警告的说明（artifact/tasks 未完成等）
+
+**成功输出格式**
+
+```text
+## 归档完成
+
+**变更：** <change-name>
+**Schema:** <schema-name>
+**归档到：** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs：** ✓ 已同步到主 specs（或 "No delta specs" / "Sync skipped"）
+
+所有 artifacts 已完成。所有 tasks 已完成。
+```
+
+**约束**
+- 未提供变更名称时，必须让用户选择
+- 使用 artifact graph（`openspec status --json`）检查完成状态
+- 不要因为警告而阻止归档；告知并确认即可
+- 移动归档时保留 `.openspec.yaml`（目录整体移动即可）
+- 清晰展示发生了什么
+- 如果用户请求同步，使用 openspec-sync-specs 的 agent-driven 方式
+- 如果存在 delta specs，始终先做同步评估，并在询问用户前展示合并摘要
+- 归档前必须执行 Spec Impact Review；如果改动范围与已有主 spec 的 Code Scope 重合，必须记录处理结论
+- 对 `schema: sdd-e2e`，OpenSpec artifact 完成状态不是归档放行条件；`pnpm sdd:acceptance` 才是最终 gate