openspec-playwright 0.3.52 → 0.3.54

package/README.md

@@ -50,7 +50,7 @@ openspec-pw audit         # Audit tests for orphaned specs and issues
 openspec-pw coverage      # Analyze spec–test coverage for changes
 openspec-pw flake         # Detect static flake patterns in test files
 openspec-pw migrate       # Migrate old test files to new structure
-openspec-pw explore       # Explore routes in parallel with Playwright
+openspec-pw explore       # Explore app routes with Playwright
 openspec-pw run <name>    # Execute E2E tests for a change
 openspec-pw uninstall     # Remove integration from the project
 ```
@@ -87,7 +87,7 @@ openspec-pw uninstall     # Remove integration from the project
   │
   ├── 10. Healer (if needed) → auto-heals failures via MCP
   │
-  └── 11. Report → openspec/reports/playwright-e2e-<name>.md
+  └── 11. Report → openspec/reports/playwright-e2e-<name>-<timestamp>.md
 ```
 
 ## Prerequisites
@@ -115,7 +115,7 @@ Browser exploration is provided out of the box by Playwright MCP and `openspec-p
 
 1. Detects supported editors in the project (Claude Code and/or OpenCode)
 2. Installs the E2E command for each detected editor (`/opsx:e2e` for Claude Code, `/opsx-e2e` for OpenCode)
-3. Generates `tests/playwright/seed.spec.ts`, `auth.setup.ts`, `credentials.yaml`, `app-knowledge.md`
+3. Generates `tests/playwright/seed.spec.ts`, `auth.setup.ts`, `credentials.yaml`, `app-knowledge.md`, `pages/BasePage.ts`
 4. Generates `playwright.config.ts` with automatic dev script and port detection (Vite/Next/Nuxt/Astro, `.env`, and `--port`)
 
 > **Note**: After running `openspec-pw init`, manually install Playwright browsers: `npx playwright install --with-deps`
@@ -144,14 +144,16 @@ Run through these steps in order when using the E2E workflow for the first time:
 
 ## App Server Detection
 
-Generated `playwright.config.ts` automatically detects the app URL in this order:
+Generated `playwright.config.ts` automatically detects the app URL in this priority order:
 
 1. `BASE_URL` environment variable
-2. port flags in `package.json` scripts, e.g. `vite --port 5125`
-3. `vite.config.*` `server.port`
-4. `.env.local`, `.env.development`, `.env` (`PLAYWRIGHT_PORT`, `E2E_PORT`, `VITE_PORT`, `PORT`)
-5. framework defaults: Vite `5173`, Astro `4321`, Next/Nuxt `3000`
-6. fallback: `http://localhost:3000`
+2. environment variables: `PLAYWRIGHT_PORT`, `E2E_PORT`, `VITE_PORT`, `PORT`
+3. port flags in `package.json` scripts, e.g. `vite --port 5125`
+4. `vite.config.*` `server.port`
+5. `.env.local`, `.env.development`, `.env` (same env var names)
+6. framework defaults: Vite `5173`, Astro `4321`, Next/Nuxt `3000`
+7. `seed.spec.ts` `BASE_URL` constant
+8. fallback: `http://localhost:3000`
 
 Run `openspec-pw doctor` to see the detected dev script and base URL:
 
@@ -215,27 +217,33 @@ CLI (openspec-pw)
   ├── run        → Executes E2E tests with server lifecycle
   ├── migrate    → Migrates old test files to new structure
   ├── audit      → Audits tests for orphaned specs and issues
+  ├── coverage   → Analyzes spec–test coverage for changes
   ├── flake      → Detects static flake patterns in test files
   ├── doctor     → Checks prerequisites
-  ├── explore    → Explores routes in parallel with Playwright
+  ├── explore    → Explores app routes with Playwright
   └── uninstall  → Removes integration from the project
 
 Editors (auto-detected by openspec-pw init)
   ├── Claude Code (/opsx:e2e)
   │   ├── .claude/commands/opsx/e2e.md   → Command file
   │   ├── @playwright/mcp                → Healer Agent tools (via `claude mcp add playwright …`)
-  │   └── CLAUDE.md                      → Employee-grade standards
+  │   └── CLAUDE.md                      → Imports AGENTS.md via `@AGENTS.md`
   └── OpenCode (/opsx-e2e)
       ├── .opencode/commands/opsx-e2e.md → Command file (body rewritten from /opsx: → /opsx-)
       ├── opencode.jsonc                 → Playwright MCP (mcp.playwright) + instructions routing
-      └── CLAUDE.md or AGENTS.md         → Employee-grade standards (routed by detected editors)
+      └── AGENTS.md                      → Employee-grade standards (SSOT)
+
+Employee-grade standards live in **AGENTS.md** as the single source of truth. Claude Code
+loads them via a thin CLAUDE.md with `@AGENTS.md` import. OpenCode registers AGENTS.md in
+`opencode.jsonc` under `instructions`.
 
 Test Assets (tests/playwright/)
   ├── seed.spec.ts         → Env validation
   ├── auth.setup.ts        → Session recording
   ├── global.teardown.ts   → Post-test cleanup (optional)
   ├── credentials.yaml     → Test users
-  └── app-knowledge.md     → Project-level selector patterns (cross-change)
+  ├── app-knowledge.md     → Project-level selector patterns (cross-change)
+  └── pages/BasePage.ts    → Shared page object class
 
 Exploration (openspec/changes/<name>/specs/playwright/)
   ├── app-exploration.md → This change's routes + verified selectors

package/README.zh-CN.md

@@ -68,10 +68,12 @@ openspec-pw init          # 安装 Playwright E2E 集成
 ```bash
 openspec-pw init          # 初始化集成（一次性设置；加 --seed 覆盖已有 seed.spec.ts）
 openspec-pw update        # 更新 CLI 和命令到最新版本
-openspec-pw doctor        # 检查前置条件
+openspec-pw doctor        # 检查前置条件 + 应用服务器诊断
 openspec-pw audit         # 检查测试文件是否有孤儿文件和配置问题
+openspec-pw coverage      # 分析 spec 与测试之间的覆盖率
+openspec-pw flake         # 检测测试文件中的静态不稳定模式
 openspec-pw migrate       # 迁移旧测试文件到新目录结构
-openspec-pw explore       # 并行探索路由
+openspec-pw explore       # 探索应用路由
 openspec-pw run <name>    # 执行指定 change 的 E2E 测试
 openspec-pw uninstall     # 移除项目中的集成
 ```
@@ -108,14 +110,14 @@ openspec-pw uninstall     # 移除项目中的集成
   │
   ├── 10. Healer（如需要）→ 通过 MCP 自动修复失败
   │
-  └── 11. 报告 → openspec/reports/playwright-e2e-<name>.md
+  └── 11. 报告 → openspec/reports/playwright-e2e-<name>-<timestamp>.md
 ```
 
 ## `openspec-pw init` 做了什么
 
 1. 检测项目中的受支持编辑器（Claude Code 和/或 OpenCode）
 2. 为每个检测到的编辑器安装 E2E 命令（Claude Code 用 `/opsx:e2e`，OpenCode 用 `/opsx-e2e`）
-3. 生成 `tests/playwright/seed.spec.ts`、`auth.setup.ts`、`credentials.yaml`、`app-knowledge.md`
+3. 生成 `tests/playwright/seed.spec.ts`、`auth.setup.ts`、`credentials.yaml`、`app-knowledge.md`、`pages/BasePage.ts`
 
 ## 首次配置清单
 
@@ -188,23 +190,32 @@ CLI (openspec-pw)
   ├── run        → 执行 E2E 测试并管理服务器生命周期
   ├── migrate    → 迁移旧测试文件到新目录结构
   ├── audit      → 检查测试文件是否有孤儿文件和配置问题
+  ├── coverage   → 分析 spec 与测试之间的覆盖率
+  ├── flake      → 检测测试文件中的静态不稳定模式
   ├── doctor     → 检查前置条件
-  ├── explore    → 并行探索路由
+  ├── explore    → 探索应用路由
   └── uninstall  → 移除项目中的集成
 
 编辑器（由 openspec-pw init 自动检测）
   ├── Claude Code (/opsx:e2e)
   │   ├── .claude/commands/opsx/e2e.md    → 命令文件（从 templates/e2e-command.md 安装）
-  │   └── @playwright/mcp                 → Healer Agent 工具（通过 `claude mcp add playwright …`）
+  │   ├── @playwright/mcp                 → Healer Agent 工具（通过 `claude mcp add playwright …`）
+  │   └── CLAUDE.md                       → 通过 `@AGENTS.md` 引入 AGENTS.md
   └── OpenCode (/opsx-e2e)
       ├── .opencode/commands/opsx-e2e.md  → 命令文件（正文由 /opsx: 改写为 /opsx-）
-      └── opencode.jsonc                  → Playwright MCP (mcp.playwright) + 指令路由
+      ├── opencode.jsonc                  → Playwright MCP (mcp.playwright) + 指令路由
+      └── AGENTS.md                       → 员工级规范（单一数据源）
+
+员工级规范统一存放在 **AGENTS.md** 中。Claude Code 通过薄层 CLAUDE.md
+（包含 `@AGENTS.md` 导入）加载；OpenCode 在 `opencode.jsonc` 的 `instructions` 中注册 AGENTS.md。
 
 测试资产 (tests/playwright/)
-  ├── seed.spec.ts       → 环境验证
-  ├── auth.setup.ts      → 会话录制
-  ├── credentials.yaml   → 测试用户
-  └── app-knowledge.md   → 项目级选择器模式（跨 change 复用）
+  ├── seed.spec.ts        → 环境验证
+  ├── auth.setup.ts       → 会话录制
+  ├── global.teardown.ts  → 测试后清理（可选）
+  ├── credentials.yaml    → 测试用户
+  ├── app-knowledge.md    → 项目级选择器模式（跨 change 复用）
+  └── pages/BasePage.ts   → 共享页面对象基类
 
 探索结果 (openspec/changes/<name>/specs/playwright/)
   ├── app-exploration.md → 本次 change 的路由 + 已验证选择器

package/employee-standards.md

@@ -1,98 +1,140 @@
 # AI Coding Assistant Employee-Grade Standards
 
-> 员工级行为规范。
-
 ---
 
 ## 0. 适用范围
 
-本规范适用于 OpenSpec + openspec-playwright 项目（使用 AI 编码助手，如 Claude Code 或 OpenCode）。
+**约定**：动手前先读 `openspec/config.yaml`（技术栈、结构、约定、约束等），无内容则忽略。
 
-**项目规范**：动手前读 `openspec/config.yaml`（技术栈、结构、约定、约束等），无内容则忽略。
+**语言**：用中文回复用户。
 
-## 1. 代码质量（强制执行）
+**优先级决策规则**：🔴 CRITICAL（违反→静默 bug / 安全漏洞，必须修正）→ **停下确认后再执行**｜🟡 IMPORTANT（偏离需说明理由）→ **谨慎执行，偏离说明原因**｜⚪ STANDARD（标准实践，可调整）→ 按标准执行
 
-**动手前先思考**：列出假设，逐条验证。复杂任务如有多种解释则都列出来，如有更简单的方案则提出来，必要时坚持己见。有不清楚的地方则停下来，说出困惑，再提问。
+---
 
-**每步有可验证的退出条件**：多步骤任务先列计划（`1. [Step] → verify: [check]`），动手后循环验证直到成功。lint + typecheck 自动执行，任一失败则停止。lint 失败时优先运行 `npm run lint:fix`。
+## 1. 代码质量
+
+> WHY：AI 默认倾向多写、快写、猜写。本节约束将这些倾向转化为可验证的生产代码。
+
+**DO**
+- 🔴 **lint + typecheck 每次编辑后自动执行，通过才算成功**。扫源码扩展名判断主语言：.ts/.tsx→ESLint+tsc、.py→ruff+mypy、.go→gofmt+vet。工具不存在时告知用户，不假装跑过
+- 🟡 动手前列假设 → 逐条验证。有不清→停下来，说出困惑，再提问
+- 🟡 多解释则全列，更简单方案则提出并坚持
+- 🟡 多步任务先列计划（`1. [Step] → verify: [check]`），循环验证直到成功
+- 🟡 lint 失败时优先运行 `npm run lint:fix`
+- 🟡 只写被要求的：不加"灵活"、"可配置"、单次使用抽象、未要求功能。200行能50行则重写
+- 🟡 精准改动：只改必要的，改完清理自己造成的垃圾。匹配现有风格
+- 🟡 代码文件行数上限 1500：超过即违例，必须按职责拆分，不得继续堆叠
+- ⚪ 重构前清理未使用的 import/export/prop/console.log，单独提交再做重构
+
+**DO NOT**
+- 不写只适配特定输入值的逻辑 → 上游格式变化即失效
+- 不假设外部数据有效 → 必须校验类型/范围/null，处理空/异常/边界值，防 NPE 和注入
+- 不假设异步/外部操作一定成功 → 网络、磁盘、下游随时可能失败
+- 不假设响应结构一定如预期 → 先校验再访问深层属性，API 升级增减字段不通知你
+- 不假设精度/范围安全 → 计算前确认安全范围，数值溢出和精度损失是隐蔽 bug
+- 不假设资源自动释放 → 文件/连接/cursor 用后必须释放
+- 不写魔法数字 → 用常量或枚举并注释原因
+- 不断言具体值（除非明确要求）→ 脆性断言，换环境即碎
+
+**REQUIRE**
+- linter/typechecker 不存在 → 告知用户并建议安装
+- mock 数据 / fixture → 参见 §6 数据编撰禁令
+- 涉及 API 定义 → 查阅真实 OpenAPI/MCP 定义并标注来源
 
-**只写被要求的东西**：不要加"灵活"、"可配置"、单次使用的抽象、没被要求的功能。200行能50行完成则重写。
+---
 
-**精准改动**：只改必要的，改完清理自己造成的垃圾。匹配现有风格，不改进无关代码。
+## 2. 上下文管理
 
-**lint + typecheck 通过（项目标准工具链）才算成功**。动手前扫描项目根目录源码文件扩展名检测主语言——`.py`→Python（ruff + mypy）、`.ts`/`.tsx`→TypeScript（ESLint + tsc）、`.go`→Go（gofmt + vet），工具不存在时告知用户。
+> WHY：AI 上下文窗口有限，压缩恢复时刻丢失状态。本节建立恢复协议。
 
-**禁止非通用性改动**：
-- 不写只适配特定输入值的逻辑
-- 禁止假设外部数据有效 → 必须校验类型/范围/null
-- 处理数据时考虑边界情况（空值、异常值、边界值）
-- 断言用通用规则，不用具体值（除非明确要求）
-- 禁止魔法数字 → 用常量或枚举，注释说明原因（例如：`const MAX_RETRIES = 3; // 网络请求最大重试次数`）
-- 禁止隐式成功假设 → 异步/外部操作必须处理失败情况
-- 禁止响应结构假设 → 先校验返回结构再访问深层属性
-- 禁止精度/范围假设 → 计算前确认数值在安全范围内
-- 禁止资源泄漏假设 → 文件/连接/cursor 等使用后必须释放
+**DO**
+- 🟡 超过 500 行文件：分次读取或编辑前重新读取完整文件
+- 🟡 上下文压缩恢复后：`git status` → 重读 proposal/design/tasks → 对照 design 检查实现 → lint + typecheck → 继续
+- ⚪ 超过 10 条消息后，编辑任何文件前强制重新读取
 
-## 2. 上下文管理
+**DO NOT**
+- 禁止跨阶段跳步（explore→apply→verify→e2e 各阶段由用户触发）
+- 禁止跨 change 改动：`/opsx:apply <X>` 期间不改 `changes/<Y>/`
+- 禁止"顺手清理"其他 open change 文件 → 告知用户，由用户决定
 
-**文件读取完整**：超过 500 行的文件，不要假设单次读取覆盖完整内容——根据需要分次读取或编辑前重新读取完整文件。超过 10 条消息后，编辑任何文件前强制重新读取。
+---
 
-**上下文压缩恢复后（Apply 阶段）**：
-1. `git status` — 确认已改动的内容
-2. 重读 `changes/<name>/proposal.md` + `design.md` + `tasks.md` — 确认范围、设计决策、任务状态
-3. 对照 design.md 检查关键实现（路径、命名、目录结构）
-4. 运行对应语言的 lint + typecheck 验证
-5. 然后继续实施
+## 3. 架构 Invariants
 
-**OpenSpec 阶段隔离**：每个阶段由用户手动触发，禁止跨阶段跳步（explore 阶段不能调 apply，verify 阶段不能调 e2e）。
+> **[项目特定]** 以下仅适用于 openspec-playwright 项目结构。WHY：这些约束一违反即产生 review 难发现的 bug。Anthropic 称其为最高杠杆的 agent 代码质量措施。
 
-**禁止跨 change 改动**：执行 `/opsx:apply <X>` 期间，不得修改 `changes/<Y>/`（X≠Y）下任何文件。看到其它 open change 的"顺手清理"诱惑一律拒绝。
+- 🔴 CLI 命令向 `src/index.ts` 注册，`src/commands/` 下按职责分文件
+- 🔴 模板文件放 `templates/`，不与其他源码混放
+- 🟡 OpenSpec change artifacts 放 `changes/<name>/`，遵循命名规范
+- 🟡 E2E 测试生成代码放 `e2e/`（如 `e2e/auth.setup.ts`）
+- 🔴 文档同步规则：改 `src/commands/*.ts`/`src/index.ts` 时必须同步更新 README + CHANGELOG
 
-**重构前清死代码**：未使用的 import/export/prop/console.log 先删掉，单独提交，再做重构。
+---
 
-## 3. 大规模任务处理
+## 4. 工具使用
 
-**200 行以上修改或显著架构变更必须走 OpenSpec**：代码改动超过 200 行、或涉及新增服务/API 契约/数据模型重构时，禁止直接修改，必须通过 OpenSpec 工作流（/opsx:propose）。
+> WHY：工具使用方式直接影响搜索覆盖面和结果准确性。
 
-## 4. 工具限制与编辑安全
+**DO**
+- 🟡 搜索要全：Grep 搜内容 + Glob 搜文件名，两者缺一不可。跳过 node_modules/vendor/__pycache__（调试依赖时除外），搜子目录时按需缩小
+- 🟡 重命名覆盖：调用、类型、字符串、import、barrel file、测试 mock，不得假设一次覆盖
+- ⚪ 联网调研优先 agent-reach skill
+- 🟡 编辑 → 重新读取确认 → lint+typecheck → 任一失败则回退
+- 🟡 变更完成告知用户可能遗漏区域，提示人工复查
 
-**搜索要全**：用 Grep 搜内容，用 Glob 搜文件名。两者缺一不可。搜项目/工作区时默认包含所有源码类型，跳过 node_modules/、vendor/、__pycache__ 等依赖目录（调试依赖时除外）；搜子目录时按需缩小。重命名时覆盖调用、类型、字符串、`import`、barrel file、测试 mock，不得假设一次覆盖所有情况。
+**DO NOT**
+- 禁止用 sed/awk/node -e/python -c 等管道命令改源码文件（跳过编辑工具验证层）
+- 不主动推送，除非用户明确要求
+- 不假设单次 grep 覆盖所有情况（glob 可能漏嵌套文件或非标准扩展名）
 
-**联网调研优先 agent-reach**：需要查询/调研/搜索等联网操作时，优先使用 agent-reach skill，避免 WebFetch/WebSearch 直接抓页面导致反爬失败。
+**REQUIRE**
+- 使用格式化工具（ruff fmt / prettier 除外——不改语义）
+- 密钥与 .env 不入版本控制。示例用占位符（如 `YOUR_API_KEY`）。调试日志不打印凭据
 
-**编辑要求**：编辑后重新读取文件确认变更正确应用。变更完成后，明确告知用户可能遗漏的区域（动态引用、测试 mock 等），提示人工复查。
+---
 
-**禁止脚本改文件**：修改源码文件只能使用内置编辑工具（Read/Edit/Write），禁止用 sed/awk/node -e/python -c 等管道命令改文件。格式化工具（ruff fmt、prettier）除外。
+## 5. 大规模任务
 
-**不主动推送**：除非用户明确要求，否则不推送代码。
+> WHY：200+ 行直接修改缺乏评审，OpenSpec 工作流强制提案→设计→评审→实现。
 
-**中文回复**：用中文回复用户。
+- 🔴 200+ 行修改或架构变更（新增服务/API 契约/数据模型重构）必须走 OpenSpec（`/opsx:propose`），禁止直接修改
 
-**安全规范**：密钥与 `.env` 文件不入版本控制。示例代码用占位符（如 `YOUR_API_KEY`）不用真实凭据。调试日志不打印凭据/密钥/token。
+### 工作流参考
 
-## 5. 完整生产工作流
+| 阶段 | 命令 | 退出条件 |
+|------|------|---------|
+| 提案 | `/opsx:propose` | proposal + scenarios 生成 |
+| 实现 | `/opsx:apply` | lint + typecheck 通过 |
+| 自审 | `/opsx:verify` | 实现匹配 design，无遗漏 |
+| E2E | `/opsx:e2e` / `/opsx-e2e` | 测试生成 + Healer 验证通过 |
+| 归档 | `/opsx:archive` | specs 更新，归档完成 |
 
-**Superpowers（可选增强）**：安装 `/plugin install superpowers@claude-plugins-official` 后，Superpowers 在 propose → apply → verify 阶段提供更严谨的 AI 方法论（对话式 spec 探索、TDD、subagent 并行实现）。Superpowers **不改变 OpenSpec 主流程**，所有阶段仍由用户手动触发。
+所有阶段由用户手动触发，**AI 不自动进入下一阶段**。Superpowers（可选）：`/plugin install superpowers@claude-plugins-official`，提供对话式 spec 探索、TDD、subagent 并行实现，不改变主流程。
 
-阶段命令即触发器：`/opsx:propose` → `/opsx:apply` → `/opsx:verify` → e2e 命令（Claude Code 用 `/opsx:e2e`，OpenCode 用 `/opsx-e2e`）→ `/opsx:archive`。**所有阶段由用户手动触发，AI 不自动进入下一阶段**（详见 §2 阶段隔离）。
+---
 
-## 6. 禁止编撰数据
+## 6. 数据编撰禁令
 
-无论前后端一体还是纯前端项目，AI 助手**严禁**主动编撰任何数据填充代码，除非用户明确同意。
+> WHY：AI 有"填空"倾向——缺乏数据时编造看似合理的值，引入静默 bug。
 
-**适用范围**：mock 用户 / 邮箱 / 手机号；编造的测试期望值（"期望返回 `{ success: true }`" 等）；凭空出现的配置默认值（API URL、feature flag、密钥）；假装存在的接口 / 字段 / 枚举值。
+**DO NOT**
+- 严禁主动编撰任何数据填充代码，除非用户明确同意
+- 编撰示例：mock 用户/邮箱/手机号、编造测试期望值、凭空出现配置默认值、假装存在的接口/字段/枚举值
+- 不编造 URL/路径 → 引用真实来源，勿凭印象编造 endpoint/path/字段名
+- 遇需数据的代码位必须显式询问用户
+- 用户拒绝时，用 stub / `throw` / `return null` 显式失败，禁止静默编造
 
-**强制流程**：
-1. 遇需数据的代码位 → **必须**显式询问用户
-2. 用户同意占位 → 用 `TODO(user)` 标注并附问询上下文
-3. 用户提供数据 → 使用真实数据
-4. 用户拒绝提供 → 用 stub / `throw` / `return null` 让代码显式失败，**禁止**静默编造值
+**REQUIRE**
+- 用户同意占位 → `TODO(user)` 标注并附问询上下文
+- 用户提供数据 → 使用真实数据
+- 无论前后端一体还是纯前端，存在 OpenAPI/接口文档 → 查阅真实定义并标注来源（如 `// 来源: docs/api/openapi.yaml#/paths/...`）
 
-**纯前端项目**：若存在 OpenAPI / 接口文档 / MCP 暴露的接口，必须查阅真实定义后引用，并标注来源（例如 `// 来源: docs/api/openapi.yaml#/paths/...`），禁止凭印象编造 endpoint / path / 字段名。
+---
 
 ## 7. 临时文件管理
 
-所有工具（Chrome DevTools MCP、截图、日志、heapdump 等）产生的非源码临时文件必须放项目根目录 `tmp/` 下：
+- 非源码临时文件（截图、日志、heapdump 等）放项目根 `tmp/` 下
 - 平铺，不分子目录
-- 文件名含时间戳（避免覆盖）
-- `tmp/` 中超过 24 小时的文件可以在 commit 前删除
+- 文件名含时间戳
+- 超 24 小时的文件可在 commit 前删除

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openspec-playwright",
-  "version": "0.3.52",
+  "version": "0.3.54",
   "description": "OpenSpec + Playwright E2E verification setup tool for Claude Code",
   "type": "module",
   "bin": {