openspec-sdd-e2e-kit 0.1.0

package/kit/.codex/skills/openspec-full-spec-discovery/references/backlog-row-to-main-spec.md

@@ -0,0 +1,447 @@
+# Backlog Row 到 Main Spec 恢复
+
+只在用户已经选择一个明确 capability 后使用本参考。输入可以来自 `full-spec-discovery.md` 的 Product Capability Backlog，也可以来自用户直接指定的 capability、页面、路由或已有主 spec。
+
+本参考负责把一个 capability 垂向恢复为 `openspec/specs/<capability>/spec.md`。首次全量 discovery 阶段不要使用本参考生成 Requirement、Scenario 或 `SHALL/MUST`。
+
+## 流程
+
+```text
+Backlog Row /明确 capability
+-> Readiness Gate
+-> Evidence Package
+-> Chrome DevTools MCP Runtime Gap Scan
+-> Candidate Requirements
+-> User Review Gate
+-> Pre-write Checks
+-> Main Spec Write
+-> Interaction Flow Write
+-> Spec / Flow Alignment Review
+-> Discovery Writeback
+```
+
+一次只处理一个 capability。不要把多个 backlog 行合并写入一个主 spec。
+
+## 输入契约
+
+从 Product Capability Backlog 读取：
+
+```text
+order | priority | capability | main_spec_status | purpose/boundary | entries/evidence | confidence | vertical_slice_preparation
+```
+
+同时读取与该 capability 相关的：
+
+- Entry / API / Store assignment summary
+- GitNexus process assignment ledger
+- Unknown / Inactive Entries
+- Excluded Implementation Details
+- Out-of-product Tooling
+- Open Questions
+- 已有 `openspec/specs/<capability>/spec.md`
+- 已有 `openspec/specs/<capability>/interaction-flow.md`
+- 已归档 `openspec/changes/archive/**/specs/**/spec.md`
+- 测试、API 契约、UI 文案、route、store、form guard、mock 或 fixture
+
+只带入会影响当前 capability 边界、规则、证据、阻塞项或目标 spec 路径的材料。
+
+## Readiness Gate
+
+只有满足以下条件时，才继续恢复：
+
+- `capability` 是 kebab-case，并能映射到 `openspec/specs/<capability>/spec.md`。
+- 该 capability 描述一个 actor goal，或一个边界紧密的产品工作流。
+- 该 capability 有稳定业务对象、用户可见表面或外部契约。
+- 该 capability 不是内部 component、hook、helper、state action、utility 或 execution flow。
+- 证据足以启动 requirement-level 恢复，即使细节仍需确认。
+
+如果一行混合多个 actor goal、多个对象生命周期、多个外部 owner、多个独立页面或互不相关的用户任务，不要恢复成一个主 spec。
+
+使用以下决策之一：
+
+- `ready`：继续构建证据包。
+- `split`：先拆成更小 capability，每个子项 `main_spec_status = 未完成`。
+- `block`：标记 `main_spec_status = 暂缓`，写明 blocker 和下一步证据来源。
+- `exclude`：移出 Product Capability Backlog，放入 `unknown/inactive`、`impl-detail` 或 `out-of-product`。
+
+GitNexus process 可以作为证据或归属线索，但不能单独证明 capability 已完成。
+
+## Evidence Package
+
+先收集证据，再起草 requirement。使用紧凑表格：
+
+```text
+候选行为 | 证据 | 置信度 | 待确认问题
+```
+
+对 UI-facing capability，Evidence Package 还必须先列出静态交互候选图，作为 Chrome DevTools MCP Runtime Gap Scan 的输入：
+
+```text
+候选动作 | 静态来源 | 用户可见表面 | 预期可见结果/状态变化 | 预期 network/storage | 是否修改性/破坏性 | 用户授权状态 | 后续处理
+```
+
+静态来源应尽量覆盖 route、页面组合、组件事件处理器、props callback、表单控件、表格列/行操作、菜单项、store 状态迁移、API 调用、测试、归档 spec 和直接 UI 文案。不要只按当前可见页面截图枚举控件；先用代码和证据推导目标 capability 内可能存在的用户动作，再进入运行态验证。
+
+证据等级：
+
+- 高：已有主 spec、已接受归档 delta spec、断言可观察行为且通过的测试、明确 API/后端契约、用户确认的运行时观察、直接产品文案。
+- 中：route/page composition、API client 形态、form schema/submit guard、store/reducer/state-machine、mock/fixture/Storybook、错误或空态分支。
+- 低：未测试条件分支、死代码、TODO、注释代码、未使用 props、偶然实现细节、只靠命名推断、无 UI/测试支撑的生成类型。
+
+冲突处理：
+
+1. 优先采用已接受 OpenSpec，而不是代码现状。
+2. 优先采用断言用户可见行为的测试，而不是实现分支。
+3. 优先采用当前可观察 UI，而不是过期文档。
+4. 将未测试代码视为候选行为，不视为产品意图。
+5. 选择某个来源作为规范依据前，先让用户确认。
+
+只有高置信或用户确认的行为才能写成 `SHALL`、`MUST` 或 `SHOULD`。中低置信行为先写成候选、gap 或待验证问题。
+
+浏览器观察只证明当前可见行为，不自动证明产品意图。对 UI-facing capability，必须在 Candidate Requirements 之前使用 Chrome DevTools MCP 做运行态验证与遗漏探索；只有纯后端、纯数据契约、离线文档或 out-of-product tooling 等非 UI-facing capability 可以跳过，并必须说明排除原因。
+
+## Chrome DevTools MCP Runtime Gap Scan
+
+对 UI-facing capability，在 Candidate Requirements 之前必须执行一轮 Chrome DevTools MCP 运行态验证与遗漏探索。该步骤既验证已有候选 requirement，也要先结合代码和静态证据推导目标 capability 内所有可能用户动作，再通过运行态观察验证可达性、可见结果、网络/状态变化和遗漏交互。
+
+如果 Chrome DevTools MCP、dev server、登录态、测试数据或目标入口不可用，记录 runtime blocker / gap，不得臆造运行时行为，不得静默跳过。UI-facing capability 不得进入规范性 Candidate Requirements 或 Main Spec Write；只能输出 blocker/gap 或 audit-only 预览，除非用户明确批准其它观察方式。
+
+准备：
+
+- 确认 dev server URL、登录态/token/cookies、测试数据、目标 capability 入口和允许操作边界。
+- 明确哪些动作只观察、哪些动作可执行、哪些动作执行前需要用户确认；修改性或破坏性动作默认纳入交互候选图，不得因需要确认而忽略。
+- 执行修改性或破坏性动作前，向用户说明目标环境、目标对象、具体动作和可能影响；用户批准或确认可回滚/可丢弃测试数据后执行；用户明确拒绝时不执行，并标为 `refused`、`blocked` 或 `not-tested`；用户未回应或授权边界不清时，保留为待授权 gap。
+- 若登录、数据或环境不可用，记录 blocker，不臆造运行时行为。
+
+执行：
+
+1. 从路由、组件事件处理器、props callback、表单控件、表格列/行操作、菜单项、store 状态迁移、API 调用、测试和归档 spec 推导交互候选图，覆盖目标 capability 内所有可能用户动作。示例类型不得被视为探索上限。
+2. 为每个候选动作分配稳定的本次审查 ID，并记录静态来源、预期可见结果、预期 network/storage、是否修改性/破坏性、用户授权状态。
+3. 打开目标 capability 的真实入口，确认页面/抽屉/弹窗是否可达，并将当前可见控件、菜单、按钮、输入、切换、空态、加载态、错误态和禁用态与交互候选图对齐。
+4. 用 DevTools 对交互候选图做运行态验证，优先验证归档 spec、测试和代码之间可能 drift 的行为。等价动作组可以选代表执行，但未执行项必须显式标为 `not-tested`、`blocked`、`refused` 或待确认。
+5. 对每个候选动作记录 `observed`、`unreachable`、`blocked`、`refused`、`not-tested` 或 `runtime-only` 状态，并观察 DOM 可见变化、network request/response、console error、storage/session 变化、URL/路由变化、可见反馈和跨视图同步。
+6. 对代码推导到但运行态不可达的动作、运行态发现但静态证据没有覆盖的行为，分别列为 gap 或“挖掘候选”，不要直接写成规范。
+7. 如果观察到归档 spec/test 与当前运行时冲突，列为冲突并进入 User Review Gate。
+
+输出 runtime gap scan：
+
+```text
+candidate_id | candidate action | approval state | static source/evidence | runtime status | observed evidence | requirement/gap disposition | decision needed
+```
+
+同时保留紧凑的交互候选图摘要，说明每个候选动作来自代码、测试、归档 spec、API/store 还是运行态探索，以及它最终被归入 requirement、gap、排除项或待确认问题。
+
+证据定级：
+
+- 运行时观察 + 用户确认，或运行时观察 + 通过测试/归档 spec/API 契约支撑，可以作为高置信证据。
+- 仅 Chrome DevTools MCP 观察到、未被测试或用户确认的行为，默认中置信。
+- 只来自瞬时 UI、异常数据、偶发网络状态或无法复现的观察，默认低置信或 gap。
+
+不要把 raw screenshot、完整 network payload、console dump 写进最终 main spec。最终 spec 只保留被接受的可观察业务规则；DevTools 证据可进入写入前摘要和非规范性 `Code Scope`。
+
+## Candidate Requirements
+
+按业务规则分组证据，不按文件、组件或函数分组。
+
+每个候选 requirement 包含：
+
+- Requirement 名称
+- Requirement ID，格式为 `REQ-<SPEC_SHORT_CODE>-NN`
+- 候选规则描述
+- 代表性 Scenario 摘要
+- 证据引用
+- 关联交互候选动作或 runtime gap
+- 置信度：高 / 中 / 低
+- 待确认问题或冲突
+
+候选表：
+
+```text
+Requirement 候选名 | 规则摘要 | Scenario 摘要 | 证据 | 关联交互/Runtime Gap | 置信度 | 决策
+```
+
+Requirement 应描述稳定业务规则或用户可见工作流。不要把组件名、API 函数名、hook、reducer action 或文件名写成 requirement。
+
+规范性语言使用：
+
+- `WHEN <触发条件>, 系统 SHALL <可观察行为>.`
+- `IF <条件>, 系统 SHALL/MUST <可观察行为>.`
+- `WHILE <状态>, 系统 SHALL/MUST <可观察行为>.`
+- `<实体> MUST NOT <被禁止的行为>.`
+
+避免“正确地”“通常”“简单”“快速”“合理”“友好”等不可验证词。
+
+## Scenario 规则
+
+每个 requirement 至少一个 `#### Scenario`。
+
+Scenario 必须描述可观察行为：
+
+```md
+#### Scenario: <代表性例子>
+- **GIVEN** <初始状态>
+- **WHEN** <用户动作或系统事件>
+- **THEN** <可观察结果>
+```
+
+不要写实现断言，例如 `handleSubmit 被调用`、React state 为某值、某 hook 返回某内部字段。只有当实现细节本身是外部契约时，才改写成契约描述。
+
+主 spec 不写 `.feature` 的 `@phase`、`@validation`、`@req`、优先级或风险标签。
+
+## Requirement / Flow ID 规则
+
+写入主 spec 时，每个 Requirement 必须有稳定 ID：
+
+```text
+REQ-<SPEC_SHORT_CODE>-NN
+```
+
+`SPEC_SHORT_CODE` 使用 capability 的可读短码，优先取主要词首字母并大写，例如 `chat-test-affix -> CTA`。`NN` 使用两位递增编号。ID 一旦被 `interaction-flow.md`、测试、审计或其它文档引用，应尽量保持稳定；标题微调不应导致 ID 变化。
+
+在 `spec.md` 中保留 OpenSpec 标题格式，并把 ID 放在 Requirement 规范正文之后、Scenario 之前：
+
+```md
+### Requirement: <业务规则名称>
+
+<系统 SHALL/MUST ...>
+
+Requirement ID: `REQ-XXX-01`
+
+#### Scenario: <代表性例子>
+```
+
+不要把 `Requirement ID` 放在 Requirement 标题后的第一段。OpenSpec strict 校验会把第一段当作 Requirement 正文；如果第一段没有 `SHALL` 或 `MUST`，会校验失败。
+
+`interaction-flow.md` 中的流程 ID 使用：
+
+```text
+FLOW-<SPEC_SHORT_CODE>-NN
+```
+
+流程 ID 只用于辅助文档引用，不替代主 spec 的 Requirement ID。
+
+## User Review Gate
+
+编辑文件前先展示候选规则、交互候选图摘要、runtime gap scan 和写入摘要。让用户对不确定规则分类：
+
+- `接受`：写入主 spec。
+- `编辑`：调整措辞或 scenario。
+- `Gap`：记录为未决，不写成 `SHALL`。
+- `拒绝`：本次 spec 省略。
+- `验证`：先运行或检查更多证据。
+
+未经用户确认，绝不能把以下内容提升为 `SHALL`：
+
+- 只有低置信代码路径支持的行为。
+- 像 workaround、bug、历史妥协或偶然 UI 状态的行为。
+- 被测试、UI、API 契约或已归档 spec 反驳的规则。
+- 无法从可观察行为推断出的产品决策。
+- 私有实现细节。
+
+对 UI-facing capability，User Review Gate 必须明确说明：
+
+- 哪些静态推导动作已被运行态验证并归入候选 requirement。
+- 哪些静态推导动作在运行态不可达，暂列 gap、排除项或待确认问题。
+- 哪些运行态探索发现的动作缺少静态证据或规范来源，暂列“挖掘候选”。
+- 哪些修改性或破坏性动作已获批准执行、哪些被用户明确拒绝、哪些仍待授权；被拒绝或待授权的路径不得从候选图和 gap 中消失。
+
+写入前摘要至少列出：
+
+```text
+Target spec:
+Target interaction flow:
+Mode: create | update | audit-only
+Interaction candidate graph summary:
+Runtime gap scan:
+Unverified or unreachable candidates:
+Runtime-only discovered candidates:
+Chrome DevTools MCP blockers or exclusions:
+Mutation/destructive action approvals:
+Add requirements:
+Modify requirements:
+Keep unchanged:
+Not writing as normative:
+Interaction flows:
+Code Scope evidence:
+```
+
+## Pre-write Checks
+
+写入或更新前确认：
+
+- 每个 requirement 至少有一个 scenario。
+- 每个 requirement 都有 `REQ-<SPEC_SHORT_CODE>-NN` ID，且 ID 放在规范正文之后、Scenario 之前。
+- 如果写入或更新主 spec，也必须同步创建或更新 `interaction-flow.md`。
+- 每个 scenario 包含 `GIVEN`、`WHEN` 和 `THEN`，除非有明确理由省略 `GIVEN`。
+- 每个规范性声明都能被用户、API consumer 或 integration 观察到。
+- 没有私有实现细节被提升为业务规则。
+- 没有低置信行为被写成 `SHALL`。
+- 修改性或破坏性候选动作没有因需要授权而被忽略；每个此类动作都有 `approved`、`refused`、`pending`、`not-needed` 或等价处置说明。
+- UI-facing capability 已完成 Chrome DevTools MCP Runtime Gap Scan，或已记录不可用 blocker 并停止规范性写入。
+- 代码推导出的每个交互候选动作都有 disposition：requirement、gap、exclude、blocked、not-tested 或 decision needed。
+- 没有未经用户明确批准就弱化已有 requirement。
+- 术语与项目已有语言、UI 文案和 OpenSpec 风格一致。
+- 主 spec 包含非规范性的 `## Code Scope`。
+
+如果验证需要当前不可用的登录、数据、凭据或运行环境，停止并把 capability 标记为 `暂缓` 或留下明确 gap。
+
+## Main Spec Write
+
+只有用户接受写入摘要后，才创建或更新：
+
+```text
+openspec/specs/<capability>/spec.md
+```
+
+最终主 spec 保持干净，并为每个 Requirement 标记稳定 ID：
+
+```md
+# <capability> Specification
+
+## Purpose
+<业务边界>
+
+## Requirements
+
+### Requirement: <业务规则名称>
+
+<系统 SHALL/MUST ...>
+
+Rules:
+- <可选的补充业务规则>
+
+Requirement ID: `REQ-XXX-01`
+
+#### Scenario: <代表性例子>
+- **GIVEN** <初始状态>
+- **WHEN** <用户动作或系统事件>
+- **THEN** <可观察结果>
+
+## Code Scope
+<非规范性实现范围>
+```
+
+`Code Scope` 不是业务规则，不使用 `SHALL/MUST`。至少记录可确认的 `routes`、`files`、`apis` 或 `gitnexus_processes` 中一类；证据不足的项不要臆造。
+
+除非用户要求，不要把证据置信度表格写进最终 spec。只有用户希望在 spec 中保留未决项时，才添加简短 `## 待确认问题`。
+
+更新已有 spec 时，保留无关 requirement，只编辑已接受的范围。
+
+## Interaction Flow Write
+
+写入或更新主 spec 时，同时创建或更新：
+
+```text
+openspec/specs/<capability>/interaction-flow.md
+```
+
+`interaction-flow.md` 是面向研发和测试的辅助阅读材料，只表达交互流程，不新增规范性要求。若它与 `spec.md` 冲突，以 `spec.md` 的 Requirement 和 Scenario 为准。
+
+推荐结构：
+
+````md
+# <capability> Interaction Flow
+
+本文档是 `<capability>` 主 spec 的辅助阅读材料，面向研发和测试人员。
+
+它只整理交互流程，不新增规范性要求。若本文档与 `spec.md` 存在冲突，以 `spec.md` 中的 Requirement 和 Scenario 为准。
+
+## 阅读范围
+
+<In scope / Out of scope Mermaid 或列表>
+
+## Requirement ID 对照
+
+| Requirement ID | `spec.md` Requirement | 关联流程 |
+| --- | --- | --- |
+| `REQ-XXX-01` | `<Requirement 名称>` | `FLOW-XXX-01` |
+
+## FLOW-XXX-01：<中文流程名>
+
+<一句话说明该流程表达什么。>
+
+```mermaid
+flowchart TD
+  A["用户动作"]
+  B["系统可见反馈"]
+  A --> B
+```
+
+阅读要点：
+- <研发/测试需要关注的边界>
+
+关联 Requirements：
+- `REQ-XXX-01`：`<Requirement 名称>`
+
+## 流程与 Requirement 索引
+
+| 流程 ID | 核心关注点 | Requirement IDs |
+| --- | --- | --- |
+| `FLOW-XXX-01` | `<流程摘要>` | `REQ-XXX-01` |
+````
+
+图表规则：
+
+- 普通用户交互主线用 Mermaid `flowchart`。
+- 并发、乱序返回、回调、超时、reset 后旧响应隔离等时序逻辑用 `sequenceDiagram`。
+- 节点、分支和注释使用中文；保留项目既有技术术语，例如 `pending`、`answer`、`pre_session`、`Agent`。
+- 交互流程图表达“用户动作与可见结果”；payload 构建、状态派生等实现细节只在它们帮助研发/测试理解验收边界时保留。
+- 每个流程块必须列出关联的 Requirement ID。
+- 文档必须同时提供 `Requirement -> Flow` 和 `Flow -> Requirement` 两种索引。
+
+## Spec / Flow Alignment Review
+
+写入 `spec.md` 和 `interaction-flow.md` 后执行对齐检查：
+
+1. 每个 `REQ-...` 在 `spec.md` 中真实存在。
+2. `interaction-flow.md` 引用的每个 `REQ-...` 都能在 `spec.md` 找到。
+3. 每个主 spec Requirement 至少能在 `interaction-flow.md` 的对照表或流程索引中找到对应项；若某 Requirement 没有交互流程，必须说明它是范围边界、排除项、后台契约或其它非交互规则。
+4. 每个 `FLOW-...` 至少关联一个 Requirement ID。
+5. 每个被引用的 `FLOW-...` 都有对应的 `## FLOW-...` 章节。
+6. 每个 `## FLOW-...` 章节都出现在 `流程与 Requirement 索引` 中。
+7. `Requirement -> Flow` 对照表、每个 flow 章节的“关联 Requirements”、`Flow -> Requirement` 索引三处映射必须一致。
+8. 每个 flow 的用户动作、触发条件、系统可见反馈、异常分支和边界处理必须与对应 Requirement 及其 Scenario 的 GIVEN/WHEN/THEN 逻辑一致。
+9. `interaction-flow.md` 不新增 `spec.md` 没有承认的规范性 `SHALL/MUST`、业务规则、可见结果或异常处理。
+10. 运行：
+
+```bash
+git diff --check
+openspec validate --specs --strict --json
+```
+
+如果当前 CLI / 工具环境支持 multi-agent 或 subagent 能力，在完成本地对齐检查后派生一个独立子 agent 做二次审查。先检查当前会话是否暴露 multi-agent/subagent 工具；例如可通过可用工具列表、`tool_search` 查询 `multi-agent`，或当前 CLI 的 agent/subagent 帮助命令确认。若不可用，记录“multi-agent unavailable”并继续人工检查。
+
+子 agent 审查要求：
+
+- 只给子 agent 原始产物路径：`openspec/specs/<capability>/spec.md` 和 `openspec/specs/<capability>/interaction-flow.md`。
+- 不泄露你的结论、预期答案或已知问题。
+- 让子 agent 检查 Requirement ID 是否存在、Flow ID 是否完整、双向索引是否一致。
+- 让子 agent 逐项对比流程图与对应 Requirement / Scenario 的 BDD 逻辑，确认 GIVEN 初始状态、WHEN 用户动作或系统事件、THEN 可见结果、异常分支和边界处理没有偏离。
+- 让子 agent 检查流程图是否新增未被主 spec 承认的规范性规则、可见结果或异常处理。
+- 子 agent 不应修改文件；它只返回发现的问题和建议。
+- 如果子 agent 发现真实不一致，修正后重新运行本地对齐检查和 OpenSpec strict 校验。
+
+## Discovery Report 回写
+
+处理 capability 后，回写 Product Capability Backlog：
+
+- `未完成 -> 进行中`：用户选择该行并开始恢复。
+- `进行中 -> 已完成`：主 spec 和 `interaction-flow.md` 已创建或更新，用户已接受，通过 review checks，包含 `Purpose`、`Requirements`、代表性 Scenario、非规范性 `Code Scope`、Requirement ID、Flow ID 和双向索引。
+- `未完成/进行中 -> 暂缓`：产品意图、运行时访问、外部系统证据、凭据或证据冲突阻塞规范性恢复。
+- `暂缓 -> 进行中`：blocker 已解除并重新开始恢复。
+
+不要因为 GitNexus process、route、API group 或代码 owner 已归属，就标记为 `已完成`。完成必须有已接受主 spec。
+
+当 capability 被拆分时，更新 ledger，使每个 route/API/store/process owner 指向新的子 capability 或明确 exclusion。
+
+当 capability 被排除时，从 Product Capability Backlog 移除，并在对应 unknown、implementation detail 或 tooling 章节记录证据和原因。
+
+## 停止条件
+
+遇到以下情况时，停止并询问用户：
+
+- 请求范围过大，无法安全审查。
+- 证据冲突，并且影响产品行为判断。
+- 写入会删除或重写已接受范围之外的现有主 spec 内容。
+- 验证需要当前不可用的登录、数据、凭据或运行环境。
+- 用户要求修改应用代码；此时切换到合适的 OpenSpec change 工作流。

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

@@ -0,0 +1,92 @@
+---
+name: openspec-new-change
+description: 使用实验性的 artifact 工作流创建一个新的 OpenSpec 变更。适用于用户想用结构化步骤创建新功能、修复或修改时。
+license: MIT
+compatibility: 需要 openspec CLI。
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+  projectOverlay: "sdd-e2e"
+---
+
+使用 artifact 驱动方式创建一个新的 OpenSpec 变更。
+
+本项目已经集成 project-local schema：`sdd-e2e`。原生 schema 入口是 `openspec/schemas/sdd-e2e/schema.yaml`；流程规范入口是 `openspec/sdd-e2e-flow.md`。不要再使用 `schemaFile` fallback 来模拟 schema。
+
+**输入**：用户请求中应该包含一个变更名称（kebab-case），或者包含他们想构建内容的描述。
+
+**步骤**
+
+1. **如果没有清晰输入，先询问用户想构建什么**
+
+   使用 **AskUserQuestion tool**（开放式问题，不提供预设选项）询问：
+   > "你想处理哪个变更？请描述你想构建或修复的内容。"
+
+   根据用户描述推导 kebab-case 名称，例如 `"add user authentication"` -> `add-user-auth`。
+
+   **重要**：在理解用户想构建什么之前，不要继续执行。
+
+2. **确定工作流 schema**
+
+   先运行：
+   ```bash
+   openspec schemas --json
+   ```
+
+   如果结果中包含 source 为 `project` 的 `sdd-e2e`，则说明项目级流程已接入 OpenSpec CLI。
+
+   **默认选择 `sdd-e2e` 的情况**：变更涉及 UI 行为、交互状态、异步请求、配置表单、发布流程、跨视图同步，或需要 phase E2E 验收。
+
+   **只有在用户提到以下内容时，才使用不同 schema：**
+   - 指定了具体 schema 名称 -> 使用 `--schema <name>`
+   - 提到 "show workflows" 或 "what workflows" -> 运行 `openspec schemas --json` 并让用户选择
+   - 明确要求轻量流程、纯文案、样式微调或无状态小修 -> 可以使用默认 `spec-driven`
+
+   如果需求应使用 `sdd-e2e`，但 `openspec schemas --json` 未列出该 schema，停止并提示先修复项目 schema 集成；不要静默 fallback 到 `spec-driven`。
+
+3. **创建变更目录**
+   ```bash
+   openspec new change "<name>" --schema sdd-e2e
+   ```
+   如果已经明确选择其他 schema，改用对应的 `--schema <name>`；如果使用默认 `spec-driven`，可省略 `--schema`。
+
+   命令会在 `openspec/changes/<name>/` 下创建 `.openspec.yaml`。对于 `sdd-e2e`，文件应至少包含：
+   ```yaml
+   schema: sdd-e2e
+   ```
+
+4. **展示 artifact 状态**
+   ```bash
+   openspec status --change "<name>"
+   ```
+   该命令会显示哪些 artifact 需要创建、哪些已就绪（依赖已满足）。
+
+5. **获取第一个 artifact 的创建说明**
+
+   第一个 artifact 取决于 schema，例如 spec-driven 工作流通常是 `proposal`。
+   查看 status 输出，找到第一个状态为 `"ready"` 的 artifact。
+   ```bash
+   openspec instructions <first-artifact-id> --change "<name>"
+   ```
+   该命令会输出创建第一个 artifact 所需的模板和上下文。
+
+6. **停止并等待用户指示**
+
+**输出**
+
+完成上述步骤后，汇总：
+- 变更名称和位置
+- 当前使用的 schema / 工作流，以及 artifact 顺序
+- 当前状态（0/N 个 artifact 已完成）
+- 第一个 artifact 的模板
+- 提示语："已准备好创建第一个 artifact。你可以描述这个变更的背景，我来起草；也可以直接让我继续。"
+
+**约束**
+- 此时不要创建任何 artifact，只展示说明
+- 不要越过第一个 artifact 模板继续推进
+- 如果名称不合法（不是 kebab-case），要求用户提供合法名称
+- 如果同名变更已经存在，建议继续该变更
+- 如果使用非默认工作流，必须传 `--schema`
+- 使用 `sdd-e2e` 时，后续 artifact 顺序以 `openspec/schemas/sdd-e2e/schema.yaml` 为准：proposal -> specs -> features -> test-cases -> design -> tasks -> phase acceptance -> final acceptance -> archive
+- OpenSpec `status` 只表示 artifact 文件是否存在；phase gate 和 final acceptance 以 `pnpm sdd:*` 命令为准

package/kit/.codex/skills/openspec-propose/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: openspec-propose
+description: 一次性提出一个新的 OpenSpec 变更并生成所有必要 artifact。适用于用户想快速描述需求，并得到可进入实现阶段的 proposal、design、specs 和 tasks。
+license: MIT
+compatibility: 需要 openspec CLI。
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+  projectOverlay: "sdd-e2e"
+---
+
+提出一个新变更：创建 change，并一次性生成实现前所需的所有 artifact。
+
+我会创建包含以下 artifact 的变更：
+- `proposal.md`：做什么、为什么做
+- `specs/**/spec.md`：需求行为和业务规则
+- `specs/**/features/*.feature`：由 specs 扩写的验收契约
+- `test-cases.md`：覆盖矩阵和 phase 摘要
+- `design.md`：如何实现
+- `tasks.md`：实现步骤
+
+准备开始实现时，运行 `/opsx:apply`。
+
+项目验证扩展：
+- 当前项目支持原生 project-local schema：`openspec/schemas/sdd-e2e/schema.yaml`。
+- 对于 `schema: sdd-e2e` 的变更，features 和 test-cases 是必需 artifact，不是可选测试附件。
+- 对于默认 `spec-driven` 变更，不要自动加塞 sdd-e2e artifact；只有用户明确要求补充 phase 验证时才生成项目验证 artifact。
+- 生成的 Scenario 标签（`@phase:*`、`@validation:*`、`@req:*`）应当影响 design 中的风险分析，以及 tasks 中的 phase 分组。
+
+---
+
+**输入**：用户请求中应该包含一个变更名称（kebab-case），或者包含他们想构建内容的描述。
+
+**步骤**
+
+1. **如果没有清晰输入，先询问用户想构建什么**
+
+   使用 **AskUserQuestion tool**（开放式问题，不提供预设选项）询问：
+   > "你想处理哪个变更？请描述你想构建或修复的内容。"
+
+   根据用户描述推导 kebab-case 名称，例如 `"add user authentication"` -> `add-user-auth`。
+
+   **重要**：在理解用户想构建什么之前，不要继续执行。
+
+2. **创建变更目录**
+   ```bash
+   openspec new change "<name>" --schema sdd-e2e
+   ```
+   对 UI 行为、交互状态、异步请求、配置表单、发布流程、跨视图同步或需要 phase E2E 的需求，默认使用 `--schema sdd-e2e`。
+
+   创建前先确认 schema 可用：
+   ```bash
+   openspec schemas --json
+   ```
+   如果 `sdd-e2e` 未出现在 schema 列表中，停止并提示先修复 OpenSpec 集成；不要创建 `spec-driven` 后手动伪装成 sdd-e2e。
+
+3. **获取 artifact 构建顺序**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   解析 JSON，得到：
+   - `applyRequires`：进入实现前必须完成的 artifact ID 数组，例如 `["tasks"]`
+   - `artifacts`：所有 artifact 的列表，包含状态和依赖关系
+
+4. **按顺序创建 artifact，直到满足 apply-ready 条件**
+
+   使用 **TodoWrite tool** 跟踪 artifact 创建进度。
+
+   按依赖顺序遍历 artifact（优先处理没有未完成依赖的 artifact）：
+
+   a. **对于每个状态为 `ready`（依赖已满足）的 artifact**：
+      - 获取创建说明：
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - instructions JSON 包含：
+        - `context`：项目背景（给你的约束，不要写入输出文件）
+        - `rules`：artifact 级规则（给你的约束，不要写入输出文件）
+        - `template`：输出文件应使用的结构
+        - `instruction`：该 artifact 类型的 schema 指南
+        - `outputPath`：应写入的位置
+        - `dependencies`：需要读取的已完成依赖 artifact
+      - 读取所有已完成依赖文件作为上下文
+      - 使用 `template` 作为结构创建 artifact 文件
+      - 写作时遵守 `context` 和 `rules`，但不要把它们复制进文件
+      - 简短展示进度："已创建 <artifact-id>"
+
+   b. **持续创建，直到所有 `applyRequires` artifact 都完成**
+      - 每创建一个 artifact 后，重新运行 `openspec status --change "<name>" --json`
+      - 检查 `applyRequires` 中的每个 artifact ID 是否都在 `artifacts` 数组中显示 `status: "done"`
+      - 全部完成后停止
+      - 对 `schema: sdd-e2e`，按 schema artifact 顺序创建：proposal -> specs -> features -> test-cases -> design -> tasks。不得在 features/test-cases 缺失时创建 design 或 tasks。
+      - 对 `schema: sdd-e2e`，创建 tasks 后停止；final-acceptance 是实现和 phase report 完成后的收口 artifact，不在 propose 阶段提前生成。
+
+   c. **如果某个 artifact 需要用户补充输入**（上下文不清晰）：
+      - 使用 **AskUserQuestion tool** 澄清
+      - 然后继续创建
+
+5. **展示最终状态**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**输出**
+
+完成所有 artifact 后，汇总：
+- 变更名称和位置
+- 已创建 artifact 列表及简短说明
+- 已创建的项目验证 artifact，例如 `specs/**/features/*.feature` 和 `test-cases.md`
+- 当前就绪状态："所有 artifact 已创建，可以开始实现。"
+- 提示语："运行 `/opsx:apply`，或直接让我开始实现 tasks。"
+
+**Artifact 创建准则**
+
+- 遵循 `openspec instructions` 中每种 artifact 的 `instruction` 字段
+- schema 决定每个 artifact 应包含的内容，必须按 schema 执行
+- 创建新 artifact 前，先读取依赖 artifact
+- 使用 `template` 作为输出文件结构，并填充各节
+- **重要**：`context` 和 `rules` 是给你的约束，不是文件内容
+  - 不要把 `<context>`、`<rules>`、`<project_context>` 块复制到 artifact 文件中
+  - 它们只指导你如何写，绝不能出现在最终输出中
+
+**约束**
+- 创建进入实现所需的全部 artifact（由 schema 的 `apply.requires` 定义）
+- 创建新 artifact 前必须读取依赖 artifact
+- 如果上下文严重不清楚，询问用户；但优先做合理决策，保持推进
+- 如果同名变更已存在，询问用户是继续该变更还是创建新变更
+- 每创建一个 artifact 后，先确认文件确实存在，再继续下一个
+- 如果生成了 `.feature` 文件，必须确认每个 Scenario 都有 `@phase:*`、`@validation:*` 和 `@req:*` 标签，然后才能用它们塑造 tasks
+- 如果 `.openspec.yaml` 声明 `schema: sdd-e2e`，还必须确认每个 Scenario 都有 `@p0|@p1|@p2` 优先级标签，并运行 `pnpm sdd:lint-features <change>` 与 `pnpm sdd:lint-tasks <change>`
+- OpenSpec `status.isComplete` 只代表 artifact 文件存在；不要把它当成 SDD final acceptance 结论