openspec-sdd-e2e-kit 0.1.0

package/kit/.codex/skills/openspec-full-spec-discovery/SKILL.md

@@ -0,0 +1,356 @@
+---
+name: openspec-full-spec-discovery
+description: 全量发现、补齐或审计 OpenSpec 主 spec。用于项目没有维护主 spec、需要从现有代码建立 Product Capability Backlog、入口/API/store/GitNexus 分母归属账本、unknown/exclusion 清单，从 backlog 中选择单个 capability 垂向恢复 main spec，或对全项目 main spec 覆盖/漂移做审计时。
+---
+
+# OpenSpec 全量主 Spec 发现
+
+使用本 skill 从项目全局建立主 spec 恢复地图，并在用户选择单个 capability 后继续恢复主 spec。首次发现阶段只做 capability-level backlog 和分母归属，不写 Requirement、Scenario、`SHALL/MUST`，也不展开 happy path、异常分支或字段级规则。
+
+核心链路：
+
+```text
+Inventory
+-> Entry / Evidence
+-> Capability
+-> Product Capability Backlog
+-> Ownership Ledger
+```
+
+## Scope Boundary
+
+“全量”指在当前可访问仓库、OpenSpec、测试、API 契约、GitNexus 和用户允许的运行时证据范围内尽可能完整发现。
+
+不要声称覆盖不可访问的外部系统、线上配置、远程 feature flag、生产数据、第三方后台、未接入仓库的微服务或未运行路径。
+
+无法确认的行为标记为 `unknown`，实现细节标记为 `impl-detail`，非产品工具链标记为 `out-of-product`。
+
+## 前置工具检查
+
+在进入模式 A/B/C 前，先检查全局 OpenSpec CLI 和全局 GitNexus 是否可用，并向用户说明检查结果。正式 discovery / recovery 要求全局工具可用；如果用户拒绝安装或更新缺失工具，只能停止或做非完成态的文件级预览，不得输出“已完成”的全量覆盖结论。
+
+OpenSpec 检查：
+
+1. 检查全局 `openspec --version`。
+2. 如果全局命令不存在，使用 `npx @fission-ai/openspec --version` 验证 CLI 包并进入安装 / 更新引导。
+3. 全局 CLI 可用后运行：
+   - `openspec list --json`
+   - `openspec list --specs --json`
+4. 不要默认使用裸 `npx openspec`，除非已验证它在当前环境可执行。
+5. 如果 OpenSpec CLI 不可用，只能做非完成态文件级预览：扫描 `openspec/changes/**`、`openspec/changes/archive/**`、`openspec/specs/**`，并记录 `OpenSpec CLI unavailable` 与 fallback 范围。
+
+GitNexus 检查：
+
+1. 检查全局 `gitnexus --version`。
+2. 全局 CLI 可用后运行 `gitnexus status`。
+3. 如果状态提示 stale，先运行 `gitnexus analyze` 再使用 process / context / impact 结果。
+4. 如果 `analyze` 失败或 GitNexus 不可用，记录失败原因、indexed commit、current commit（如可取得），并把 GitNexus process coverage 标为 `stale/unavailable`。
+5. GitNexus stale 或不可用时，只能继续做非完成态 route/API/store/test/archive 预览；不得声称当前 commit 的 GitNexus process 已全量归属。
+
+## 安装 / 更新引导
+
+前置检查不要静默安装或升级。发现全局 OpenSpec 或 GitNexus 缺失、版本异常、索引 stale 且刷新失败时，先向用户报告工具状态、影响和推荐操作，并在用户确认后执行全局安装或更新。
+
+优先级：
+
+1. 全局 CLI：正式 discovery / recovery 前必须能直接运行 `openspec` 和 `gitnexus`。
+2. 临时 `npx`：只用于验证包名、诊断安装问题或一次性引导；不得作为工具已安装的最终状态。
+3. 项目本地依赖：不要为本 skill 自动把 CLI 加入 `package.json` 或 lockfile，除非用户另行明确要求项目固定版本。
+
+OpenSpec 安装 / 更新建议：
+
+- 缺少全局 CLI 时，建议全局安装：`npm install -g @fission-ai/openspec`。
+- 版本异常时，建议全局更新：`npm update -g @fission-ai/openspec` 或重新安装指定版本。
+- 安装 / 更新后必须重新验证 `openspec --version`、`openspec list --json`、`openspec list --specs --json`。
+
+GitNexus 安装 / 更新建议：
+
+- GitNexus CLI 缺失、版本异常或 `analyze` 因运行时依赖失败时，可先运行 `npx gitnexus doctor` 或等价诊断命令定位问题，再询问用户是否安装或更新全局 CLI。
+- 缺少全局 CLI 时，建议全局安装：`npm install -g gitnexus`。
+- 版本异常或全局 `gitnexus analyze` 失败且疑似 CLI 依赖问题时，建议全局更新：`npm update -g gitnexus` 或重新安装指定版本。
+- 安装 / 更新后必须重新运行 `gitnexus --version`、`gitnexus status`；如仍 stale，再运行 `gitnexus analyze` 并记录结果。
+
+所有全局安装、更新或网络访问命令，都必须先获得用户确认。执行后在进入 discovery / recovery 前向用户说明命令、版本、是否修改全局 CLI、失败原因和证据影响；不要把这些工具检查细节写入 capability-level discovery report。
+
+## 三种模式
+
+### 模式 A：首次全量建立 Product Capability Backlog
+
+适用于项目没有主 spec，或主 spec 明显不完整。
+
+输出一份 capability-level discovery report，包含：
+
+1. `Scope Boundary`
+2. `Inventory Summary`
+3. `Evidence Sources`
+4. `Entry / API / Store Assignment Summary`
+5. `GitNexus Process Assignment Ledger`
+6. `Product Capability Backlog`
+7. `Unknown / Inactive Entries`
+8. `Excluded Implementation Details`
+9. `Out-of-product Tooling`
+10. `Open Questions`
+
+不要在模式 A 中生成 flow/rule 细表、Requirement 草稿或 Scenario 草稿。单个 capability 的规则细化使用模式 B。
+
+### 模式 B：单 Capability 主 Spec 恢复
+
+适用于用户接受 backlog 并选择一个 capability 后，或用户直接要求恢复一个明确 capability。
+
+先读取 [references/backlog-row-to-main-spec.md](references/backlog-row-to-main-spec.md)，再进入垂向恢复。
+
+输出可以是：
+
+- readiness / split / block / exclude 判断
+- requirement-level 证据包
+- 候选 Requirement 和 Scenario 草稿
+- 写入前 review 摘要
+- 经用户确认后的 `openspec/specs/<capability>/spec.md`
+- 经用户确认后的 `openspec/specs/<capability>/interaction-flow.md`，作为非规范性交互流程辅助文档
+- recovery 后的 discovery report 状态回写
+
+一次只处理一个 capability。不要把多个 backlog 行合并写入一个主 spec。
+
+### 模式 C：全量主 spec 覆盖审计
+
+适用于已有主 spec 后，检查代码是否被覆盖、spec 是否漂移。
+
+对比：
+
+```text
+Current Inventory
+vs
+Existing main specs + Code Scope
+```
+
+报告：
+
+- 有入口但没有主 spec
+- 有代码 flow 但没有业务归属
+- 主 spec 缺少 `Code Scope`
+- `Code Scope` 指向已删除、改名或迁移的代码
+- GitNexus process 没有 capability 归属
+- Requirement 缺少证据或证据等级过低
+- 不同主 spec 的 Code Scope 重合
+- 建议新增、修改、拆分、合并或废弃的 spec
+
+## Inventory
+
+先盘点项目表面积，不急着命名 capability。
+
+优先收集：
+
+- `openspec list --json`
+- `openspec list --specs --json`
+- 路由、菜单、页面入口和可见用户动作
+- API/service client
+- store、reducer、状态机、form guard
+- 单测、组件测试、BDD feature、Playwright/Cypress
+- `openspec/changes/archive/**`
+- GitNexus `processes`、`query`、`context`
+- 模式 B 中 UI-facing capability 的 Chrome DevTools MCP 运行态验证与遗漏探索
+
+必要时补充：
+
+- 权限策略、RBAC、feature flag、env config
+- OpenAPI、GraphQL schema、protobuf、SDK contract
+- 错误码、i18n 文案、用户可见提示
+- analytics / tracking events
+- third-party integration config
+
+Inventory 不是 spec。它只是发现分母。
+
+## Entry vs Evidence
+
+Entry 是外部 actor、用户动作、外部系统、任务调度或消息系统可以触发业务行为的入口。
+
+不要把内部 service 方法、helper、repository、hook 直接当 Entry。它们通常是 evidence 或 implementation detail。
+
+Frontend API client 可以作为前端能力和后端契约的证据，但不等同于独立业务入口。
+
+GitNexus execution flow 是代码链路证据，不是业务 Requirement。`process assignment coverage` 不等于 `main spec coverage`。
+
+## Product Capability Backlog
+
+按业务能力聚类，不按目录聚类。
+
+好的 capability 边界应满足：
+
+- 对应一个 actor goal 或紧密相关的工作流
+- 有清晰业务对象或用户可见表面
+- 能映射到稳定的主 spec 文件名
+- 范围足够小，能被后续单独审查和验证
+
+Capability 使用 kebab-case spec id；中文业务说明放在 `purpose/boundary`。
+
+Capability granularity gate：
+
+- Backlog 中每一行必须能作为一个独立 `openspec/specs/<capability>/spec.md` 恢复。
+- 如果候选项包含多个独立 actor goal、多个对象生命周期、多个外部系统 owner，或明显需要拆分，不要写成一个宽泛 capability。
+- 优先拆分 list/search/filter 与 create/edit/publish/delete lifecycle；拆分 wrapper/integration 与外部系统内部行为；拆分 notification、onboarding、task 等不同用户目标。
+
+Backlog 字段：
+
+```text
+order | priority | capability | main_spec_status | purpose/boundary | entries/evidence | confidence | vertical_slice_preparation
+```
+
+`main_spec_status`：
+
+- `未完成`：尚未创建 accepted main spec
+- `进行中`：正在单 capability 垂直细化或写入审查
+- `已完成`：已写入 accepted main spec 并完成校验
+- `暂缓`：需要产品确认、运行时证据或外部系统证据后再恢复
+
+不要把 `unknown`、`impl-detail` 或 `out-of-product` 项混入 Product Capability Backlog；它们应单独列出。
+
+## Ownership Ledger
+
+对发现分母建立归属账本。至少覆盖：
+
+- active route / hidden route / layout action
+- service API group
+- store/state domain
+- archived OpenSpec / test evidence
+- GitNexus process
+- inactive/commented entry
+- shared implementation flow
+- out-of-product tooling
+
+建议字段：
+
+```text
+item_type | item | evidence | owner | assignment_status | notes
+```
+
+`assignment_status`：
+
+- `product-capability`
+- `unknown/inactive`
+- `impl-detail`
+- `out-of-product`
+
+每个已发现分母都必须有归属或排除原因。
+
+## Evidence
+
+只在 full discovery 中记录 capability-level 证据摘要和置信度，不做 requirement-level 证据表。
+
+证据等级：
+
+- 高：已接受主 spec、通过的测试、明确 API 契约、用户确认的运行时观察、直接产品文案。
+- 中：route/component/API client/form guard/store/state transition/GitNexus process。
+- 低：单个未测试分支、命名推断、TODO、死代码、注释路由、偶然实现细节。
+
+已归档 OpenSpec 是高置信历史证据，但写入 main spec 前必须和当前代码、入口、测试和 `Code Scope` 做 drift check。
+
+代码只能证明系统当前怎么做，不能自动证明产品本来就应该这么做。
+
+## Chrome DevTools MCP 运行时探索
+
+Chrome DevTools MCP 用于单 capability 的代码推导交互候选图验证、运行态补漏和 drift 检查。默认不用于模式 A 的首次 capability-level backlog；模式 B 中只要 capability 包含页面、弹窗、抽屉、表单、列表、按钮、路由、可见反馈或其它 UI-facing 行为，就必须先从代码和静态证据建立交互候选图，再使用 Chrome DevTools MCP 验证和补漏，最后才能进入 Candidate Requirements。
+
+如果 Chrome DevTools MCP、dev server、登录态、测试数据或目标入口不可用，不得静默跳过。UI-facing capability 不得进入规范性 Candidate Requirements 或 Main Spec Write；只能输出 blocker/gap 或 audit-only 预览，除非用户明确批准其它观察方式。只有纯后端、纯数据契约、离线文档或 out-of-product tooling 等非 UI-facing capability 可以不做 Chrome DevTools MCP，但必须说明排除原因。
+
+使用边界：
+
+- 先完成前置工具检查、Readiness Gate 和静态证据收集，再做 Chrome DevTools MCP 探索。
+- 只观察当前可访问环境，不声称覆盖生产配置、远程 feature flag、真实租户数据或外部系统内部行为。
+- 修改性或破坏性操作（如保存、删除、发布、授权、清空数据、启停配置等）不得默认忽略；必须先纳入交互候选图，并在执行前向用户明确询问目标环境、对象、动作和可能影响。
+- 用户明确批准，或已确认目标是可回滚/可丢弃的测试环境与测试数据时，可以执行该操作并记录运行态结果；用户明确拒绝时，不执行，但将该路径标为 `refused`、`blocked` 或 `not-tested` 并保留为 gap/待验证项。
+- 用户尚未回应或授权边界不清时，不执行修改性或破坏性操作，但不得把路径从候选图中删除或当作不存在。
+- 浏览器观察本身只能证明当前运行时表现；除非已有测试/归档 spec/API 契约支撑或用户确认，不得直接提升为 `SHALL/MUST`。
+
+探索目标：
+
+- 结合代码与静态证据先建立交互候选图：从路由、组件事件处理器、props callback、表单控件、表格列/行操作、菜单项、store 状态迁移、API 调用、测试和归档 spec 推导目标 capability 内所有可能用户动作。tooltip、按钮显隐/禁用、行点击/文字链接、确认弹窗、下拉菜单等只是示例，不是探索上限。
+- 用 Chrome DevTools MCP 验证交互候选动作是否可达、可见结果、网络/状态变化和跨视图同步；对每个候选动作记录 `observed`、`unreachable`、`blocked`、`refused`、`not-tested` 或 `runtime-only` 等处置状态，并记录修改性/破坏性动作的用户授权状态。
+- 验证已有候选 requirement 是否能被当前 UI、网络请求、状态变化或用户可见反馈观察到。
+- 标记 drift：归档 spec 或测试与当前 UI/API 表现不一致时，不直接改写规范；先列为冲突并进入 User Review Gate。
+
+输出只进入 Mode B 的 evidence package / candidate requirement review，不写入 capability-level discovery report。需要保留紧凑的交互候选图与 runtime gap scan：
+
+```text
+candidate_id | candidate action | approval state | static source/evidence | runtime status | observed evidence | requirement/gap disposition | decision needed
+```
+
+## Unknown / Exclusions
+
+单独列出：
+
+- `Unknown / Inactive Entries`：有代码或 flow，但当前入口不可确认。
+- `Excluded Implementation Details`：共享组件、hook、util、helper，不单独写产品 spec。
+- `Out-of-product Tooling`：开发、测试、SDD/E2E 工具链，不进入产品 main spec 分母。
+
+每个 unknown 或 exclusion 必须写明证据、排除原因和需要确认的问题。
+
+## 优先级
+
+Backlog 按风险和恢复价值排序：
+
+1. P0：发布、保存、删除、权限、数据丢失风险、跨视图同步、外部可见状态变化、高置信 archive/test 证据。
+2. P1：常用列表、配置、搜索、筛选、分页、校验、错误处理、空态。
+3. P2：低频入口、窄集成、wrapper contract、小型展示或桥接能力。
+
+## Completion Criteria
+
+满足以下条件时，可以停止模式 A discovery：
+
+- 已扫描当前项目中的主要 entry、API、store/state、测试/archive 和 GitNexus process。
+- 已完成 OpenSpec CLI 和 GitNexus 的前置检查；工具缺失、失败或 stale 时已在进入 discovery 前向用户说明处理口径。
+- 每个已发现分母已归属到 product capability、`unknown/inactive`、`impl-detail` 或 `out-of-product`。
+- Product Capability Backlog 只包含后续应恢复 main spec 的产品 capability。
+- Product Capability Backlog 不包含明显过粗的 product domain；需要拆分的项已在 backlog 中拆开，而不是只写在 preparation notes。
+- 每个 backlog 行都有 priority、main_spec_status、purpose/boundary、entries/evidence、confidence 和 vertical_slice_preparation。
+- unknown、inactive、impl-detail、out-of-product 项已单独列出。
+- 不生成 Requirement、Scenario、`SHALL/MUST` 或 flow/rule 细表。
+
+## Capability Main Spec Recovery
+
+只有用户接受 backlog 并选择 capability 后，或用户直接指定明确 capability 后，才进入单 capability 垂直细化。
+
+当用户要求从 backlog 中选择一个 capability 继续细化、恢复主 spec、准备证据包、写入 `openspec/specs/<capability>/spec.md` 或回写 `main_spec_status` 时，先读取 [references/backlog-row-to-main-spec.md](references/backlog-row-to-main-spec.md)。
+
+以下内容只允许在模式 B 中处理，不属于模式 A 的首次 discovery 产物：
+
+- 单 capability 证据包精查
+- UI-facing capability 的交互候选图、Chrome DevTools MCP Runtime Gap Scan 和 disposition
+- Requirement 名称和规范性 `SHALL/MUST`
+- GIVEN/WHEN/THEN Scenario
+- happy path、异常分支、字段级校验、状态机细节
+- 证据冲突处理和用户确认 gate
+- 最终 `openspec/specs/<capability>/spec.md` 写入
+- 非规范性 `interaction-flow.md` 生成与 spec/flow 对齐检查
+- 精确 `Code Scope`
+
+`Code Scope` 是非规范性证据，不得成为业务要求本身。
+
+## 产物位置
+
+除非用户指定其它位置，模式 A 产出一份简洁 discovery report。可写入：
+
+```text
+openspec/discovery/<YYYY-MM-DD>-<scope>/full-spec-discovery.md
+```
+
+或项目已有的 spec coverage 文档位置。不要把 discovery report 混入最终主 spec。
+
+模式 C 审计可写入：
+
+```text
+openspec/audits/<YYYY-MM-DD>-main-spec-coverage/
+```
+
+最终主 spec 只写入：
+
+```text
+openspec/specs/<capability>/spec.md
+```
+
+模式 B 同步生成或更新的非规范性交互流程辅助文档写入：
+
+```text
+openspec/specs/<capability>/interaction-flow.md
+```
+
+如果同名目录已存在，不要覆盖旧产物；创建 `-v2`、`-v3` 后缀，除非用户明确要求继续更新已有目录。