@pzy560117/opentest 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 benym
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# OpenTest
+
+OpenTest is a Codex skill bundle for planning, running, verifying, and archiving quality evidence for code changes.
+
+It provides a small lifecycle:
+
+```text
+plan -> author -> run -> accept -> verify -> archive
+```
+
+`heal` is a recovery phase for stale test assets and must not hide product behavior failures.
+
+## Install
+
+Install into the current project:
+
+```bash
+npx @pzy560117/opentest install
+```
+
+Install globally for Codex:
+
+```bash
+npx @pzy560117/opentest install --global
+```
+
+Overwrite an existing OpenTest install:
+
+```bash
+npx @pzy560117/opentest install --force
+```
+
+Restart Codex or open a new session after installation so the new skills are loaded.
+
+## Included Skills
+
+- `opentest`
+- `opentest-plan`
+- `opentest-author`
+- `opentest-run`
+- `opentest-accept`
+- `opentest-verify`
+- `opentest-heal`
+- `opentest-archive`
+
+## Package Contents
+
+- `assets/skills/`: Codex skill files
+- `assets/manifest.json`: published asset manifest
+- `bin/opentest.js`: installer CLI
+

package/assets/manifest.json

@@ -0,0 +1,30 @@
+{
+  "version": "0.1.0",
+  "skills": [
+    "opentest/SKILL.md",
+    "opentest/scripts/opentest-state.sh",
+    "opentest/scripts/opentest-detect.sh",
+    "opentest/scripts/opentest-guard.sh",
+    "opentest/references/lifecycle.md",
+    "opentest/references/matrix-format.md",
+    "opentest/references/quality-gate.md",
+    "opentest/references/acceptance-evidence.md",
+    "opentest/references/command-routing.md",
+    "opentest/references/codex-harness-coverage-heuristics.md",
+    "opentest/templates/plan-template.md",
+    "opentest/templates/matrix-template.md",
+    "opentest/templates/acceptance-template.md",
+    "opentest/templates/report-template.md",
+    "opentest/templates/archive-layout.md",
+    "opentest-plan/SKILL.md",
+    "opentest-author/SKILL.md",
+    "opentest-run/SKILL.md",
+    "opentest-accept/SKILL.md",
+    "opentest-verify/SKILL.md",
+    "opentest-heal/SKILL.md",
+    "opentest-archive/SKILL.md"
+  ],
+  "platforms": [
+    { "id": "codex", "skillsDir": ".codex/skills" }
+  ]
+}

package/assets/skills/opentest/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: opentest
+description: "OpenTest 路由入口。自动检测 .opentest.yaml、初始化测试生命周期状态，并分发到 plan/author/run/accept/verify/heal/archive 阶段。"
+---
+
+# OpenTest 路由入口
+
+## 产出语言契约
+
+- 面向用户输出和生成文档默认使用中文。
+- 命令、路径、frontmatter key、代码标识符和 API 名称保持原文。
+
+## Step 0: 定位脚本
+
+运行：
+
+```bash
+OPENTEST_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+OPENTEST_STATE="${OPENTEST_STATE:-$(find "${OPENTEST_SEARCH_ROOTS[@]}" -path '*/opentest/scripts/opentest-state.sh' -type f -print -quit 2>/dev/null)}"
+OPENTEST_GUARD="${OPENTEST_GUARD:-$(find "${OPENTEST_SEARCH_ROOTS[@]}" -path '*/opentest/scripts/opentest-guard.sh' -type f -print -quit 2>/dev/null)}"
+OPENTEST_DETECT="${OPENTEST_DETECT:-$(find "${OPENTEST_SEARCH_ROOTS[@]}" -path '*/opentest/scripts/opentest-detect.sh' -type f -print -quit 2>/dev/null)}"
+```
+
+若任一脚本缺失，停止并提示安装或复制 OpenTest 分发包。
+
+## Step 1: 状态检测
+
+如果 `.opentest.yaml` 不存在，运行：
+
+```bash
+bash "$OPENTEST_STATE" init
+```
+
+然后运行：
+
+```bash
+bash "$OPENTEST_STATE" check
+bash "$OPENTEST_DETECT" summary
+```
+
+## Step 2: 阶段分发
+
+读取 `phase`：
+
+```bash
+bash "$OPENTEST_STATE" get phase
+```
+
+分发规则：
+
+- `archived: true`：报告 OpenTest 已完成。
+- `phase: plan`：调用 `opentest-plan`。
+- `phase: author`：调用 `opentest-author`。
+- `phase: run`：调用 `opentest-run`。
+- `phase: accept`：调用 `opentest-accept`。
+- `phase: verify`：调用 `opentest-verify`。
+- `phase: heal`：调用 `opentest-heal`。
+- `phase: archive`：调用 `opentest-archive`。
+
+若状态与可验证文件冲突，以文件状态为准，并用 `opentest-state.sh set` 修正。

package/assets/skills/opentest/references/acceptance-evidence.md

@@ -0,0 +1,22 @@
+# Acceptance Evidence
+
+Natural language acceptance cases must include:
+
+- ID
+- intent
+- context
+- actor or role
+- steps
+- expected outcome
+- execution surface
+- evidence status
+
+Allowed evidence status:
+
+- pending
+- pass
+- fail
+- blocked
+- risk-accepted
+
+Blocked evidence must include a reason such as unavailable MCP, unavailable environment, missing seed data, auth requirement, or external service failure.

package/assets/skills/opentest/references/codex-harness-coverage-heuristics.md

@@ -0,0 +1,64 @@
+# Codex Harness 覆盖启发参考
+
+## 用途
+
+本文件随 OpenTest 分发，用于给 `/opentest-plan` 和 `/opentest-accept` 提供轻量覆盖启发。它不是强制 checklist，也不是 Codex Harness 全量内容副本。
+
+OpenTest 应根据变更类型、风险和项目事实选择适用覆盖面。适用但缺少证据的点应记录为 `gap`；不适用的点应在覆盖摘要中说明，不需要展开用例。
+
+## 来源
+
+本参考从本地 Codex Harness 知识库中抽取短规则，主要对应：
+
+- `tdd-workflow`
+- `e2e-runner`
+- `browser-e2e-testing`
+- `verification-loop`
+- `code-reviewer`
+- `speckit-checklist`
+
+## 选择规则
+
+| 变更类型 | 默认考虑的证据 |
+| --- | --- |
+| 纯函数、工具函数、状态计算 | unit evidence |
+| 服务、模块协作、数据库读写 | integration evidence |
+| API、契约、错误处理 | contract、integration、error evidence |
+| 前端渲染或交互 | UI acceptance，必要时 component 或 E2E evidence |
+| 权限、支付、安全、数据写入、跨页面闭环 | high-risk acceptance 或 E2E evidence |
+| 文案、配置、小范围无行为变更 | targeted review 或 light evidence |
+
+## 前端验收维度
+
+前端或真实链路验收可从以下维度中选择适用项，不要求每次全部覆盖：
+
+| 维度 | 含义 |
+| --- | --- |
+| D1 页面渲染 | 标题、文案、结构、主要元素存在 |
+| D2 交互功能 | 点击、输入、选择、弹窗、菜单 |
+| D3 数据展示 | API 数据、格式化、状态展示 |
+| D4 表单验证 | 必填、格式、边界、关联校验 |
+| D5 导航流转 | 菜单、链接、返回、跨页面传参 |
+| D6 状态管理 | loading、empty、error、retry |
+| D7 权限控制 | 角色、路由守卫、越权拦截 |
+| D8 UI 反馈 | toast、modal、loading 指示 |
+| D9 组件联动 | 筛选、tab、数量、级联变化 |
+| D10 边界情况 | 空数据、长文本、特殊输入、前置数据缺失 |
+
+## 输出约束
+
+`/opentest-plan` 应优先输出窄矩阵：
+
+```markdown
+| ID | 意图 | 风险 | 必需证据 | 状态 |
+| --- | --- | --- | --- | --- |
+| ACC-001 | 用户保存后看到成功反馈 | medium | UI 验收 | pending |
+```
+
+只有当风险或变更类型需要时，才增加覆盖维度、命令、证据路径和阻塞原因列。
+
+## 质量门启发
+
+验证建议按 build、type、lint、test、security、diff 的顺序组织。构建、类型、lint、必需测试或必需验收失败时应阻塞通过；非必需证据缺口可以作为可解释风险记录。
+
+工具、环境、前置数据或 MCP 不可用时，记录 `blocked` evidence，不得声称验收通过。

package/assets/skills/opentest/references/command-routing.md

@@ -0,0 +1,9 @@
+# OpenTest Command Routing
+
+`/opentest` is the only automatic router.
+
+If `.opentest.yaml` is missing, initialize it and set `phase: plan`.
+
+The router does not write tests or run product verification directly. It detects state and invokes the next phase skill.
+
+When metadata conflicts with files, prefer verifiable files and repair `.opentest.yaml`.

package/assets/skills/opentest/references/lifecycle.md

@@ -0,0 +1,16 @@
+# OpenTest Lifecycle
+
+## Phases
+
+`plan -> author -> run -> accept -> verify -> archive`
+
+`heal` 是失败恢复阶段，只在测试资产过期或验收执行路径失效时进入。
+
+## Exit Conditions
+
+- plan: `docs/opentest/plans/*.md` and `docs/opentest/matrices/*.md` exist.
+- author: required test assets or acceptance cases exist, or gaps are explicitly recorded.
+- run: run report exists and records commands, exit codes, and summaries.
+- accept: required acceptance evidence is pass or blocked with reason.
+- verify: verification report exists and result is pass, fail, or risk-accepted.
+- archive: verification passed before archive is marked complete.

package/assets/skills/opentest/references/matrix-format.md

@@ -0,0 +1,16 @@
+# Acceptance-to-Test Matrix Format
+
+## Minimal Columns
+
+| ID | 意图 | 风险 | 必需证据 | 状态 |
+| --- | --- | --- | --- | --- |
+
+## Optional Columns
+
+- 覆盖面
+- 命令
+- 证据路径
+- 阻塞原因
+- 风险接受说明
+
+Only add optional columns when risk or change type needs them.

package/assets/skills/opentest/references/quality-gate.md

@@ -0,0 +1,21 @@
+# OpenTest Quality Gate
+
+## Blocking
+
+- build failure
+- type failure
+- lint failure
+- required test failure
+- required acceptance failure
+- required evidence gap for high-risk behavior
+
+## Risk Accepted
+
+- non-critical evidence gap with written reason
+- unavailable optional tool with fallback evidence
+- low-risk behavior covered by review rather than execution
+
+## Non-Blocking Gap
+
+- evidence not applicable to this change
+- optional coverage dimension omitted with reason

package/assets/skills/opentest/scripts/opentest-detect.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  printf 'Usage: opentest-detect.sh summary\n' >&2
+  exit 1
+}
+
+package_script_present() {
+  local name="$1"
+  [ -f package.json ] || return 1
+  grep -Eq "\"$name\"[[:space:]]*:" package.json
+}
+
+summary() {
+  printf '=== OpenTest Project Facts ===\n'
+
+  if [ -f package.json ]; then
+    printf 'package_json: present\n'
+    if package_script_present test; then printf 'npm_test: present\n'; else printf 'npm_test: missing\n'; fi
+    if package_script_present build; then printf 'npm_build: present\n'; else printf 'npm_build: missing\n'; fi
+    if package_script_present lint; then printf 'npm_lint: present\n'; else printf 'npm_lint: missing\n'; fi
+  else
+    printf 'package_json: missing\n'
+  fi
+
+  if [ -f pyproject.toml ] || [ -f pytest.ini ] || [ -f setup.cfg ]; then
+    printf 'python_tests: possible\n'
+  else
+    printf 'python_tests: missing\n'
+  fi
+
+  if [ -f pom.xml ]; then printf 'maven_project: present\n'; else printf 'maven_project: missing\n'; fi
+  if [ -f Cargo.toml ]; then printf 'cargo_project: present\n'; else printf 'cargo_project: missing\n'; fi
+  if [ -d tests ]; then printf 'tests_dir: present\n'; else printf 'tests_dir: missing\n'; fi
+  if [ -d docs/opentest ]; then printf 'opentest_docs: present\n'; else printf 'opentest_docs: missing\n'; fi
+  if [ -d docs/opentest/acceptance ]; then printf 'acceptance_docs: present\n'; else printf 'acceptance_docs: missing\n'; fi
+
+  if git rev-parse --git-dir >/dev/null 2>&1; then
+    printf 'git: present\n'
+    printf 'changed_files: %s\n' "$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')"
+  else
+    printf 'git: missing\n'
+  fi
+}
+
+case "${1:-summary}" in
+  summary)
+    shift
+    [ $# -eq 0 ] || usage
+    summary
+    ;;
+  *)
+    usage
+    ;;
+esac

package/assets/skills/opentest/scripts/opentest-guard.sh

@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PHASE="${1:-}"
+APPLY="${2:-}"
+STATE_FILE="${OPENTEST_STATE_FILE:-.opentest.yaml}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BLOCK=0
+
+red() { printf '\033[31m%s\033[0m\n' "$1" >&2; }
+green() { printf '\033[32m%s\033[0m\n' "$1" >&2; }
+
+usage() {
+  red "Usage: opentest-guard.sh <plan|author|run|accept|verify|heal|archive> [--apply]"
+  exit 1
+}
+
+yaml_field() {
+  local field="$1"
+  awk -v key="$field" '
+    $1 == key ":" {
+      sub(/^[^:]+:[[:space:]]*/, "", $0)
+      print
+      exit
+    }
+  ' "$STATE_FILE" | tr -d '"' | tr -d "'"
+}
+
+file_nonempty() {
+  [ -n "${1:-}" ] && [ "$1" != "null" ] && [ -f "$1" ] && [ -s "$1" ]
+}
+
+check_path() {
+  local description="$1"
+  local path_value="$2"
+  if file_nonempty "$path_value"; then
+    green "  [PASS] $description"
+  else
+    red "  [FAIL] $description"
+    BLOCK=1
+  fi
+}
+
+check_result() {
+  local description="$1"
+  shift
+  if "$@"; then
+    green "  [PASS] $description"
+  else
+    red "  [FAIL] $description"
+    BLOCK=1
+  fi
+}
+
+result_is_archivable() {
+  local result
+  result=$(yaml_field verification_result)
+  [ "$result" = "pass" ] || [ "$result" = "risk-accepted" ]
+}
+
+guard_plan() {
+  check_path "plan exists" "$(yaml_field plan)"
+  check_path "matrix exists" "$(yaml_field matrix)"
+}
+
+guard_author() {
+  local acceptance matrix
+  acceptance=$(yaml_field acceptance)
+  matrix=$(yaml_field matrix)
+
+  if [ -n "$acceptance" ] && [ "$acceptance" != "null" ]; then
+    check_path "acceptance asset exists" "$acceptance"
+  else
+    check_path "matrix exists for recorded gaps" "$matrix"
+  fi
+}
+
+guard_run() {
+  check_path "run report exists" "$(yaml_field run_report)"
+}
+
+guard_accept() {
+  local acceptance run_report
+  acceptance=$(yaml_field acceptance)
+  run_report=$(yaml_field run_report)
+
+  if [ -n "$acceptance" ] && [ "$acceptance" != "null" ]; then
+    check_path "acceptance evidence exists" "$acceptance"
+  else
+    check_path "run report exists for recorded no-acceptance path" "$run_report"
+  fi
+}
+
+guard_verify() {
+  check_path "verification report exists" "$(yaml_field verification_report)"
+  check_result "verification result is archivable" result_is_archivable
+}
+
+guard_heal() {
+  green "  [PASS] heal can return to run after targeted assets are updated"
+}
+
+guard_archive() {
+  check_path "verification report exists" "$(yaml_field verification_report)"
+  check_result "verification result is archivable" result_is_archivable
+}
+
+apply_transition() {
+  case "$PHASE" in
+    plan)
+      bash "$SCRIPT_DIR/opentest-state.sh" transition plan-complete
+      ;;
+    author)
+      bash "$SCRIPT_DIR/opentest-state.sh" transition author-complete
+      ;;
+    run)
+      bash "$SCRIPT_DIR/opentest-state.sh" transition run-complete
+      ;;
+    accept)
+      bash "$SCRIPT_DIR/opentest-state.sh" transition accept-complete
+      ;;
+    verify)
+      local result
+      result=$(yaml_field verification_result)
+      if [ "$result" = "pass" ]; then
+        bash "$SCRIPT_DIR/opentest-state.sh" transition verify-pass
+      elif [ "$result" = "risk-accepted" ]; then
+        bash "$SCRIPT_DIR/opentest-state.sh" transition verify-risk-accepted
+      else
+        bash "$SCRIPT_DIR/opentest-state.sh" transition verify-fail
+      fi
+      ;;
+    heal)
+      bash "$SCRIPT_DIR/opentest-state.sh" transition heal-complete
+      ;;
+    archive)
+      bash "$SCRIPT_DIR/opentest-state.sh" transition archived
+      ;;
+    *)
+      usage
+      ;;
+  esac
+}
+
+if [ -z "$PHASE" ]; then
+  usage
+fi
+
+if [ ! -f "$STATE_FILE" ]; then
+  red "FATAL: $STATE_FILE not found"
+  exit 1
+fi
+
+case "$PHASE" in
+  plan)
+    guard_plan
+    ;;
+  author)
+    guard_author
+    ;;
+  run)
+    guard_run
+    ;;
+  accept)
+    guard_accept
+    ;;
+  verify)
+    guard_verify
+    ;;
+  heal)
+    guard_heal
+    ;;
+  archive)
+    guard_archive
+    ;;
+  *)
+    usage
+    ;;
+esac
+
+if [ "$BLOCK" -ne 0 ]; then
+  red "BLOCKED"
+  exit 1
+fi
+
+green "ALL CHECKS PASSED"
+if [ "$APPLY" = "--apply" ]; then
+  apply_transition
+fi