@pzy560117/opentest 0.1.7 → 0.1.9

package/assets/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.7",
+  "version": "0.1.9",
   "languages": [
     {
       "id": "en",
@@ -62,6 +62,7 @@
       "opentest/references/acceptance-evidence.md",
       "opentest/references/codex-harness-coverage-heuristics.md",
       "opentest/references/command-routing.md",
+      "opentest/references/complete-testing-workflow.md",
       "opentest/references/lifecycle.md",
       "opentest/references/matrix-format.md",
       "opentest/references/opentest-driven-development.md",

package/assets/skills/opentest/SKILL.md

@@ -1,20 +1,19 @@
 ---
 name: opentest
-description: "OpenTest router. Detects .opentest.yaml, initializes test lifecycle state, and dispatches to plan/author/run/accept/verify/heal/archive phases."
+description: "OpenTest router entry: detect .opentest.yaml, initialize lifecycle state, and route to plan/author/run/accept/verify/heal/archive."
 ---
 
-# OpenTest Router
+# OpenTest
 
-OpenTest is a test decision and quality evidence lifecycle for AI coding changes. It is not just a TDD wrapper, and it is not just a command runner at the end of implementation. Before implementation, it turns explicit requirements, implicit boundaries, failure paths, interaction feedback, and risk scenarios into a test matrix, then uses that matrix to drive code, acceptance, and quality gates.
+OpenTest turns change requirements into a test-evidence lifecycle before implementation work proceeds.
 
-## Output Language Contract
+## Required references
 
-- User-facing output and generated documents default to English.
-- Commands, paths, frontmatter keys, code identifiers, and API names stay as written.
+- `opentest/references/command-routing.md`
+- `opentest/references/lifecycle.md`
+- `opentest/references/complete-testing-workflow.md`
 
-## Step 0: Locate Scripts
-
-Run:
+## Bootstrap
 
 ```bash
 OPENTEST_SEARCH_ROOTS=("." ".codex/skills" ".claude/skills" ".cursor/skills" ".opencode/skills" ".gemini/skills" ".qwen/skills" ".qoder/skills" "$HOME/.codex/skills" "$HOME/.claude/skills" "$HOME/.cursor/skills" "$HOME/.config/opencode/skills" "$HOME/.gemini/skills" "$HOME/.qwen/skills" "$HOME/.qoder/skills")
@@ -23,71 +22,12 @@ OPENTEST_GUARD="${OPENTEST_GUARD:-$(find "${OPENTEST_SEARCH_ROOTS[@]}" -path '*/
 OPENTEST_DETECT="${OPENTEST_DETECT:-$(find "${OPENTEST_SEARCH_ROOTS[@]}" -path '*/opentest/scripts/opentest-detect.sh' -type f -print -quit 2>/dev/null)}"
 ```
 
-If any script is missing, stop and ask the user to install or copy the OpenTest distribution.
-
-## Step 1: Detect State
-
-If `docs/loop-handoff/latest.md` exists, read it first to recover the previous OpenTest phase, matrix/acceptance/report paths, blockers, and next step. The handoff is only a recovery hint; it does not replace `.opentest.yaml`.
-
-If `.opentest.yaml` does not exist, run:
-
-```bash
-bash "$OPENTEST_STATE" init
-```
-
-Then run:
-
-```bash
-bash "$OPENTEST_STATE" check
-bash "$OPENTEST_DETECT" summary
-```
-
-## Step 2: Dispatch Phase
-
-Read `phase`:
-
-```bash
-bash "$OPENTEST_STATE" get phase
-```
-
-Dispatch rules:
-
-- `archived: true`: report that OpenTest is complete.
-- `phase: plan`: invoke `opentest-plan`.
-- `phase: author`: invoke `opentest-author`.
-- `phase: run`: invoke `opentest-run`.
-- `phase: accept`: invoke `opentest-accept`.
-- `phase: verify`: invoke `opentest-verify`.
-- `phase: heal`: invoke `opentest-heal`.
-- `phase: archive`: invoke `opentest-archive`.
-
-If state conflicts with verifiable files, trust the files and repair state with `opentest-state.sh set`. If a handoff exists, also update its current phase, next step, failures, and blockers.
-
-## OpenTest-Driven Development Usage
-
-When the user wants test-driven development, or when the requirement includes frontend interactions, login, forms, permissions, APIs, data writes, cross-page flows, or high-risk behavior, OpenTest must run before build work:
-
-```text
-Requirement / OpenSuper design
-  -> opentest plan    # implicit scenario mining + acceptance-to-test matrix
-  -> opentest author  # test assets / natural language acceptance cases
-  -> build            # implement against the matrix
-  -> opentest run     # unit / integration / smoke / e2e commands
-  -> opentest accept  # real page, API, or workflow acceptance
-  -> opentest verify  # quality gate report
-```
-
-The `plan` phase must not merely restate requirements. It must actively inspect:
-
-- Happy paths, failure paths, boundary inputs, empty data, permissions, network failures, duplicate submissions, concurrency, and stale state.
-- Frontend feedback location: field-level message, form-level alert, toast, modal, inline status, or page error state.
-- Evidence layers: unit, component, integration, contract, E2E, smoke, visual/browser acceptance, and security/review.
-- Which evidence is required, which is not applicable, and which is a gap or risk-accepted candidate.
-
-After implementation, `OpenSuper verify` may reference the OpenTest verification report, but it does not replace the OpenTest matrix, run records, or acceptance evidence.
-
-## Loop Handoff Integration
+If any script is missing, stop and ask the user to install OpenTest.
 
-After OpenTest completes any `plan`, `author`, `run`, `accept`, or `verify` phase, update `docs/loop-handoff/latest.md` when the project uses Loop Handoff. At minimum, record the `.opentest.yaml` path, current phase, test asset paths, verification already run, verification not run, failures/blockers, and next step.
+## Route
 
-The verification report path produced by `opentest-verify` must be written to the handoff so OpenSuper verify or a resumed session can reference it directly.
+1. If `.opentest.yaml` is missing, run `bash "$OPENTEST_STATE" init`.
+2. Run `bash "$OPENTEST_STATE" check` and `bash "$OPENTEST_DETECT" summary`.
+3. Read `phase` with `bash "$OPENTEST_STATE" get phase`.
+4. Dispatch to `opentest-plan`, `opentest-author`, `opentest-run`, `opentest-accept`, `opentest-verify`, `opentest-heal`, or `opentest-archive`.
+5. Keep generated user-facing artifacts in the installed skill language.

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

@@ -25,3 +25,17 @@ Allowed evidence status:
 Blocked evidence must include a reason such as unavailable MCP, unavailable environment, missing seed data, auth requirement, or external service failure.
 
 UI feedback evidence should record the actual location and shape of feedback, for example field-level inline error, form-level alert, toast, modal, page-level error panel, disabled control, loading indicator, or retry action.
+
+## Case Granularity Rules
+
+Acceptance matrices must distinguish render validation, functional validation, and side-effect validation. Do not treat "the screen can open" as complete acceptance.
+
+- Render validation: confirm that the entry point, dialog, form, list, or key control renders in the real page.
+- Functional validation: confirm that the business result actually takes effect after the user completes the key action.
+- Side-effect validation: confirm that dialogs, overlays, loading states, disabled states, toasts, or error states do not remain and mislead the next action.
+
+Any case with form submission, create, edit, delete, upload, authorization, state transition, or another write operation must include the full "fill/input -> submit/confirm -> verify result took effect" chain. Examples:
+
+- Address form can open (render validation).
+- User can fill and submit the form, and the new address appears in the list or detail view (functional validation).
+- After submission, the dialog closes, no overlay or stale loading state remains, and the next action is still usable (side-effect validation).

package/assets/skills/opentest/references/complete-testing-workflow.md

@@ -0,0 +1,66 @@
+# Complete Testing Workflow
+
+Use this reference only when the phase skill asks for detailed coverage rules.
+
+## Default Evidence Chain
+
+```text
+plan -> matrix -> fixtures -> tests -> run -> accept -> smoke -> pre-push -> verify -> archive
+```
+
+## Test Data
+
+Create `docs/opentest/fixtures/` for changes that touch data, files, roles, permissions, APIs, or stateful workflows.
+
+Required sections:
+
+- users and roles
+- permissions
+- entities for valid, existing, invalid, duplicate, unauthorized, and stale states
+- files/images when uploads, previews, or media validation exist
+- seed command and idempotency rule
+- teardown command and cleanup scope
+- assertions for UI, API, DB/storage, files, and logs
+
+## CRUD Baseline
+
+For persisted data, APIs, forms, files, or stateful flows, include these matrix dimensions:
+
+- create: validation, success, visibility in list/detail
+- read/list/detail: list, search, filter, pagination, empty state, detail
+- update: initial values, validation failure, save, read back
+- delete: confirmation, cancel, success, post-delete absence
+- failure/boundary: invalid, empty, duplicate, unauthorized, stale, network/API error
+- data consistency: UI, API, DB/storage, files, logs
+- end-to-end CRUD: create -> list -> detail -> update -> read back -> delete -> confirm absence -> teardown
+
+If a leg is not applicable, record why in `gap/blocker`.
+
+## Interaction Acceptance Hard Rules
+
+When Playwright CLI, browser MCP, or manual real-page acceptance executes CRUD, form submission, file upload, authorization, state transition, or another write operation, it must include post-submit assertions. Screenshots or "the page did not crash" are not enough.
+
+Recommended execution chain:
+
+```text
+open -> snapshot -> fill/input -> click(submit/confirm) -> snapshot -> read/assert changed result -> screenshot -> PASS/FAIL
+```
+
+- Read-after-write validation: after submission, re-read at least one trustworthy result surface such as the page, list, detail view, API response, storage record, or logs, and confirm the value changed.
+- Dialog/overlay validation: after a successful write, assert that the dialog closes, overlay is removed, loading stops, button state recovers, and the next action is usable.
+- Failure-path validation: for validation failure, permission failure, or network/API errors, assert the feedback location, input retention strategy, and recovery path.
+- Evidence recording: PASS must state the changed result that was asserted. If no result surface can be read, mark the evidence as `blocked` or `risk-accepted` and record why.
+
+## Run Gates
+
+- targeted: evidence linked to changed matrix rows
+- fast: type, lint, unit
+- full: project full test set
+- ci-like: CI order
+- pre-push: format/check, lint, type, unit, targeted integration, smoke, `git diff --check`
+
+Default code test command is `python -m pytest`. Coverage command is `python -m pytest --cov=. --cov-report=term-missing`.
+
+## Verify Gates
+
+Block pass when required fixtures, seed/teardown, smoke, pre-push, coverage, CRUD, or full-chain acceptance evidence is missing for an applicable high-risk change.

package/assets/skills/opentest-accept/SKILL.md

@@ -5,21 +5,19 @@ description: "OpenTest phase 4: execute natural language, MCP, or real workflow
 
 # OpenTest Accept
 
-## Goal
+Execute required acceptance items and write PASS, FAIL, or blocked evidence back to cases and the matrix.
 
-Execute required acceptance items and write PASS, FAIL, or blocked evidence back to acceptance cases and the matrix.
+## Required references
 
-## Steps
-
-1. Read the matrix and `docs/opentest/acceptance/`.
-2. For frontend interactions, prefer Chrome DevTools MCP to execute real page acceptance.
-3. For APIs or backend workflows, use existing project commands or direct API checks.
-4. For feedback scenarios, observe the actual rendered location and shape. For example, field errors must not be recorded only as "failed"; record whether they appear below the field, at the top of the form, in a toast, in a modal, or in a page error region.
-5. When tools, environment, or seed data are unavailable, record blocked evidence.
-6. Update acceptance records.
-7. If the project uses Loop Handoff, update `docs/loop-handoff/latest.md` with acceptance result, screenshot/step evidence paths, blocked evidence, and next step.
-8. Run `bash "$OPENTEST_GUARD" accept --apply`.
+- `opentest/references/acceptance-evidence.md`
+- `opentest/references/complete-testing-workflow.md`
+- `opentest/templates/acceptance-template.md`
 
-## Existing Skill Routing
+## Steps
 
-For frontend interaction acceptance, prefer natural language cases plus Chrome DevTools MCP. Before execution, confirm that the case covers a dimension applicable to this change. After execution, write PASS, FAIL, or blocked back to the matching ACC ID.
+1. Read the matrix, fixtures, and `docs/opentest/acceptance/`.
+2. For frontend interactions, prefer Chrome DevTools MCP and observe the real rendered UI.
+3. For API/backend workflows, use project commands or direct API checks.
+4. For CRUD/data changes, execute the full chain from the workflow reference.
+5. Record feedback location/shape, artifacts, blocked evidence, and matching ACC IDs.
+6. Update acceptance records and run `bash "$OPENTEST_GUARD" accept --apply`.

package/assets/skills/opentest-author/SKILL.md

@@ -1,30 +1,24 @@
 ---
 name: opentest-author
-description: "OpenTest phase 2: create test assets and natural language acceptance cases from the matrix."
+description: "OpenTest phase 2: create test assets, fixtures, and natural language acceptance cases from the matrix."
 ---
 
 # OpenTest Author
 
-## Goal
+Turn the matrix into executable tests, fixtures, seed/teardown notes, and acceptance cases.
 
-Create or update test assets from the acceptance-to-test matrix.
+## Required references
 
-This phase turns the matrix into executable evidence. Write tests for behavior that the project's test framework can prove. Write natural language acceptance cases for real workflows, browser checks, APIs, or manually reproducible steps. Do not force all interaction feedback into unit tests just to imitate TDD.
+- `opentest/references/opentest-driven-development.md`
+- `opentest/references/complete-testing-workflow.md`
+- `opentest/templates/fixtures-template.md`
+- `opentest/templates/acceptance-template.md`
 
 ## Steps
 
-1. Read `matrix` from `.opentest.yaml`.
-2. For unit/component/integration/contract evidence, create or update test files using the project's existing test framework.
-3. Default to pytest when code-level tests are required and the project has no explicit framework rule or existing framework. Prefer `tests/` and a command that can run with `python -m pytest`.
-4. Create or update `docs/opentest/fixtures/` from the fixtures template, including users, roles, entities, files/images, seed, teardown, and assertion surfaces.
-5. For E2E, smoke, browser acceptance, real APIs, or cross-page flows, write natural language acceptance cases under `docs/opentest/acceptance/`.
-6. For CRUD or data-writing changes, include a full workflow case: create -> list -> detail -> update -> read back -> delete -> confirm absence -> teardown.
-7. For frontend feedback cases, specify the feedback location and shape, such as field-level errors, form-level errors, toast, modal, inline status, or page error state.
-8. Record reasons and risk for evidence that is not applicable or cannot currently be created.
-9. Write the `.opentest.yaml` `fixtures` and `acceptance` fields.
-10. If the project uses Loop Handoff, update `docs/loop-handoff/latest.md` with fixtures, seed/teardown, test assets, natural language acceptance cases, gaps/risks, and next step.
-11. Run `bash "$OPENTEST_GUARD" author --apply`.
-
-## Existing Skill Routing
-
-When the matrix requires code-level test evidence, load the existing TDD guidance first. If project rules require a specific test framework, follow those rules. If no project framework is present, use pytest as the default instead of inventing a custom harness. If the current task is better proven by real acceptance than by adding test framework code, record the reason and hand it to `opentest-accept`.
+1. Read `matrix` and `fixtures` from `.opentest.yaml`.
+2. For code evidence, use the project framework; if none exists, Default to pytest with tests under `tests/` runnable by `python -m pytest`.
+3. Create/update fixtures, seed, teardown, users, roles, entities, files/images, and assertion surfaces.
+4. For CRUD/data changes, author the full acceptance flow: create -> list -> detail -> update -> read back -> delete -> confirm absence -> teardown.
+5. Record any gap/blocker with reason and risk.
+6. Write `.opentest.yaml` fields: `fixtures`, `acceptance`, then run `bash "$OPENTEST_GUARD" author --apply`.

package/assets/skills/opentest-plan/SKILL.md

@@ -1,36 +1,27 @@
 ---
 name: opentest-plan
-description: "OpenTest phase 1: analyze the change, risks, and project facts, then produce a test strategy and acceptance-to-test matrix."
+description: "OpenTest phase 1: analyze the change, risks, project facts, and create a test strategy plus acceptance-to-test matrix."
 ---
 
 # OpenTest Plan
 
-## Goal
+Create `docs/opentest/plans/`, `docs/opentest/matrices/`, and a fixtures plan before implementation.
 
-Create a test strategy under `docs/opentest/plans/` and a matrix under `docs/opentest/matrices/`.
+## Required references
 
-This phase is the entry point for OpenTest-driven development. Before implementation, it must make scenarios explicit even when the requirement did not spell them out but a mature product should handle them. Do not produce only a few happy-path tests from the literal requirement.
+- `opentest/references/codex-harness-coverage-heuristics.md`
+- `opentest/references/matrix-format.md`
+- `opentest/references/complete-testing-workflow.md`
 
 ## Steps
 
-1. Read project rules, requirements, design, diff, existing test commands, and `opentest/references/codex-harness-coverage-heuristics.md`.
-2. If the change involves frontend UI, forms, navigation, CRUD, status feedback, or motion, first read the project's `docs/frontend/DESIGN.md` and any available `harness-frontend-design` / `product-ui-defaults` rules.
-3. Classify the change type, risk level, applicable coverage dimensions, and whether code-level evidence should use an existing project framework or the default `pytest` framework.
-4. Define the test data plan: users, roles, permissions, entities, files/images, seed command, teardown command, and UI/API/DB/file/log assertions.
-5. Mine implicit scenarios: empty input, invalid input, network failure, missing permissions, duplicate submission, long content, empty data, error mapping, mobile behavior, accessibility, cross-page return paths, and state restoration.
-6. Apply the CRUD baseline for create, read/list/detail/search/filter, update/read-back, delete/cancel/post-delete, data consistency, and end-to-end CRUD flow whenever the change touches persisted data, APIs, forms, files, or stateful workflows.
-7. Produce a narrow matrix with at least `ID`, `intent`, `coverage dimension`, `trigger/input`, `expected behavior`, `risk`, `evidence layer`, `framework/command`, `required evidence`, `gap/blocker`, and `status`.
-8. Mark applicable but uncovered evidence as `gap`, and record a concrete blocker or recovery path instead of leaving coverage unknown.
-9. Write the `.opentest.yaml` `plan`, `matrix`, and `fixtures` fields.
-10. If the project uses Loop Handoff, update `docs/loop-handoff/latest.md` with the plan path, matrix path, fixtures path, current phase, and next step.
-11. Run `bash "$OPENTEST_GUARD" plan --apply`.
+1. Read project rules, requirements/design/diff, existing commands, and detection output.
+2. Classify risk, applicable coverage, test data, and whether code tests use an existing framework or default `pytest`.
+3. Apply the CRUD baseline and test data requirements from the workflow reference for data-writing/API/form/file/stateful changes.
+4. Produce a matrix with coverage dimension, framework/command, required evidence, gap/blocker, and status.
+5. Write `.opentest.yaml` fields: `plan`, `matrix`, `fixtures`.
+6. Update handoff if present, then run `bash "$OPENTEST_GUARD" plan --apply`.
 
-## Constraints
+## Gate
 
-Do not expand the full Codex Harness checklist into fixed required items. Keep a lightweight coverage summary for low-risk changes, and expand detailed acceptance dimensions only for high-risk loops.
-
-Do not force all evidence into unit tests. The matrix must state which behavior is proven by unit, component, integration, contract, E2E, smoke, browser acceptance, or security review evidence.
-
-Coverage completeness means every applicable product behavior, failure path, boundary, and risk surface has either required evidence or an explicit gap/blocker. It does not mean every task must run every possible test type.
-
-CRUD baseline and test data are default requirements for data-writing changes. If any CRUD leg is not applicable, the matrix must state why.
+Every applicable behavior, failure path, boundary, and risk surface needs evidence or a written gap/blocker. CRUD baseline and test data are default requirements unless the matrix says why they are not applicable.

package/assets/skills/opentest-run/SKILL.md

@@ -1,34 +1,31 @@
 ---
 name: opentest-run
-description: "OpenTest phase 3: run project test commands in targeted, fast, full, or ci-like mode."
+description: "OpenTest phase 3: run project verification commands in targeted, fast, full, ci-like, or pre-push mode."
 ---
 
 # OpenTest Run
 
-## Goal
+Run matrix-driven commands and write evidence reports under `docs/opentest/runs/`.
 
-Run existing project verification commands and write a run report.
+## Required references
 
-## Modes
-
-- `targeted`: run only test commands related to the matrix.
-- `fast`: run fast feedback commands, such as type, lint, and unit.
-- `full`: run the project's full test command set.
-- `ci-like`: reproduce CI verification order as closely as practical.
-- `pre-push`: run the push gate sequence before publishing or pushing.
+- `opentest/references/command-routing.md`
+- `opentest/references/complete-testing-workflow.md`
 
-Evidence layers are decided by the matrix. Do not run only unit tests just because `npm test` exists. If the matrix requires integration, contract, E2E, smoke, or security checks, run the matching project command or record missing command / blocked.
-
-If `.opentest.yaml` has `test_framework: pytest`, or code-level test evidence is required and no project framework is declared, use `python -m pytest` as the default test command. When the matrix requires coverage evidence, prefer `python -m pytest --cov=. --cov-report=term-missing` and write the coverage output path to `.opentest.yaml` `coverage_report`. If pytest or pytest-cov is unavailable, record `missing command` with the install/remediation step instead of passing the gate.
+## Modes
 
-Smoke evidence is required for ordinary feature changes unless explicitly not applicable in the matrix. A pre-push run should include the project equivalent of format/check, lint, type, unit, integration-targeted, smoke, and `git diff --check`. Missing commands must be recorded as missing or not applicable.
+- `targeted`: matrix-related commands only.
+- `fast`: type/lint/unit feedback.
+- `full`: full project command set.
+- `ci-like`: reproduce CI order.
+- `pre-push`: push gate sequence.
 
 ## Steps
 
-1. Read `run_mode` and the matrix from `.opentest.yaml`.
-2. Prefer explicit project commands, and select targeted, fast, full, or ci-like mode based on matrix evidence layers.
-3. If no explicit command exists for code-level tests, run or document the default pytest command.
-4. Record command, exit code, summary, coverage output, smoke output, pre-push output, and log path under `docs/opentest/runs/`.
-5. Write the `.opentest.yaml` `run_report` field, and write `coverage_report`, `smoke_report`, or `pre_push_report` when the matching evidence was required or produced.
-6. If the project uses Loop Handoff, update `docs/loop-handoff/latest.md` with verification already run, verification not run, failures/blockers, run report path, and next step.
+1. Read `run_mode`, matrix, fixtures, and required evidence.
+2. Prefer explicit project commands; otherwise use `python -m pytest` for code-level tests.
+3. For coverage, prefer `python -m pytest --cov=. --cov-report=term-missing`.
+4. Smoke evidence is required unless the matrix says not applicable.
+5. For `pre-push`, run or record format/check, lint, type, unit, targeted integration, smoke, and `git diff --check`.
+6. Write `run_report`, plus `coverage_report`, `smoke_report`, or `pre_push_report` when produced/required.
 7. Run `bash "$OPENTEST_GUARD" run --apply`.

package/assets/skills/opentest-verify/SKILL.md

@@ -5,25 +5,20 @@ description: "OpenTest phase 5: apply quality gates and generate a verification
 
 # OpenTest Verify
 
-## Goal
+Apply quality gates and write `verification_report` plus `verification_result`.
 
-Apply quality gates, produce a structured verification report, and write the result back to the state file.
+## Required references
 
-## Verification Order
+- `opentest/references/quality-gate.md`
+- `opentest/references/complete-testing-workflow.md`
+- `opentest/templates/report-template.md`
 
-Organize the verification report by build, type, lint, test, security, and diff. If the project has no command for a category, record missing command or not applicable instead of treating unknown status as pass.
+## Steps
 
-Organize evidence in build, type, lint, test, security, diff order. Mark `fail` when required tests, required acceptance, build, type, or lint fail. Non-required gaps may be recorded as `risk-accepted`. Write to `docs/opentest/reports/` and to the `.opentest.yaml` `verification_report` and `verification_result` fields.
-If the project uses Loop Handoff, also write the OpenTest verification report path, verification result, verification already run, verification not run, failures/blockers, and next step to `docs/loop-handoff/latest.md`.
-
-The verification report must also review the matrix and confirm:
-
-- Every required evidence item has a pass, fail, blocked, or risk-accepted conclusion.
-- Coverage completeness is checked: every applicable coverage dimension in the matrix has required evidence, a run/acceptance result, or an explicit gap/blocker with recovery path.
-- Test data is traceable: fixture, seed, teardown, and cleanup evidence exist for data-writing or CRUD changes.
-- Smoke evidence is required unless the matrix explicitly marks smoke as not applicable.
-- pre-push evidence is required before push/publish unless the user explicitly skips it and the report records the risk.
-- High-risk behavior does not pass merely because tooling, a test framework, or seed data is missing.
-- If code-level coverage was required and `test_framework: pytest` is active, the report must include the `python -m pytest` command result and the `coverage_report` path, or fail/block with a reason.
-- Blocked evidence includes a blocker reason and recovery path.
-- If product behavior fails, do not enter `heal` to patch test assets; return to implementation or requirement correction.
+1. Organize evidence in build, type, lint, test, security, diff order.
+2. Check every required evidence item has pass, fail, blocked, or risk-accepted.
+3. Confirm Coverage completeness: every applicable coverage dimension has evidence or a gap/blocker with recovery path.
+4. Smoke evidence is required unless the matrix marks smoke not applicable.
+5. pre-push evidence is required before push/publish unless the user explicitly skips it and risk is recorded.
+6. For CRUD/data changes, fixture, seed, teardown, cleanup, and `coverage_report` evidence are required when applicable.
+7. High-risk behavior must not pass because tooling, fixture, seed data, or framework is missing.

package/assets/skills-zh/opentest/SKILL.md

@@ -1,20 +1,19 @@
 ---
 name: opentest
-description: "OpenTest 路由入口。自动检测 .opentest.yaml、初始化测试生命周期状态，并分发到 plan/author/run/accept/verify/heal/archive 阶段。"
+description: "OpenTest 路由入口。自动检测 .opentest.yaml、初始化生命周期状态，并分发到 plan/author/run/accept/verify/heal/archive。"
 ---
 
-# OpenTest 路由入口
+# OpenTest
 
-OpenTest 是面向 AI 编程变更的测试决策与质量证据生命周期。它不是单纯的 TDD 包装，也不是只在实现结束后跑命令；它应在实现前先把显性需求、隐性边界、失败路径、交互反馈和风险场景整理成测试矩阵，再用矩阵驱动代码、验收和质量门。
+OpenTest 在实现前把需求转成测试证据生命周期。
 
-## 产出语言契约
+## 必读引用
 
-- 面向用户输出和生成文档默认使用中文。
-- 命令、路径、frontmatter key、代码标识符和 API 名称保持原文。
+- `opentest/references/command-routing.md`
+- `opentest/references/lifecycle.md`
+- `opentest/references/complete-testing-workflow.md`
 
-## 第 0 步：定位脚本
-
-运行：
+## 启动
 
 ```bash
 OPENTEST_SEARCH_ROOTS=("." ".codex/skills" ".claude/skills" ".cursor/skills" ".opencode/skills" ".gemini/skills" ".qwen/skills" ".qoder/skills" "$HOME/.codex/skills" "$HOME/.claude/skills" "$HOME/.cursor/skills" "$HOME/.config/opencode/skills" "$HOME/.gemini/skills" "$HOME/.qwen/skills" "$HOME/.qoder/skills")
@@ -23,71 +22,12 @@ OPENTEST_GUARD="${OPENTEST_GUARD:-$(find "${OPENTEST_SEARCH_ROOTS[@]}" -path '*/
 OPENTEST_DETECT="${OPENTEST_DETECT:-$(find "${OPENTEST_SEARCH_ROOTS[@]}" -path '*/opentest/scripts/opentest-detect.sh' -type f -print -quit 2>/dev/null)}"
 ```
 
-若任一脚本缺失，停止并提示安装或复制 OpenTest 分发包。
-
-## 第 1 步：状态检测
-
-如果存在 `docs/loop-handoff/latest.md`，先读取 handoff，确认上次 OpenTest 阶段、矩阵/验收/报告路径、阻塞项和下一步。handoff 只作为恢复线索，不替代 `.opentest.yaml`。
-
-如果 `.opentest.yaml` 不存在，运行：
-
-```bash
-bash "$OPENTEST_STATE" init
-```
-
-然后运行：
-
-```bash
-bash "$OPENTEST_STATE" check
-bash "$OPENTEST_DETECT" summary
-```
-
-## 第 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` 修正；如存在 handoff，也同步更新 handoff 的“当前阶段/下一步/失败阻塞”。
-
-## OpenTest-Driven Development 用法
-
-当用户想“以测试驱动开发”，或需求包含前端交互、登录、表单、权限、API、数据写入、跨页面流程或高风险行为时，OpenTest 必须前置到 build 之前：
-
-```text
-需求 / OpenSuper design
-  -> opentest plan    # 隐性场景挖掘 + acceptance-to-test matrix
-  -> opentest author  # 测试资产 / 自然语言验收用例
-  -> build            # 按矩阵实现
-  -> opentest run     # unit / integration / smoke / e2e 命令
-  -> opentest accept  # 真实页面、API 或链路验收
-  -> opentest verify  # 质量门报告
-```
-
-`plan` 阶段不能只复述需求。它必须主动检查：
-
-- 主路径、失败路径、边界输入、空数据、权限、网络、重复提交、并发或过期状态。
-- 前端反馈位置：字段下方、表单顶部、轻提示、模态框、行内状态、页面错误态。
-- 证据分层：unit、component、integration、contract、E2E、smoke、visual/browser acceptance、security/review。
-- 哪些证据是必需，哪些是不适用，哪些是 gap 或 risk-accepted 候选。
-
-实现完成后，`OpenSuper verify` 可以引用 OpenTest 的 verification report，但不能替代 OpenTest 的矩阵、运行记录和验收证据。
-
-## Loop Handoff 衔接
+任一脚本缺失时停止，并提示安装 OpenTest。
 
-OpenTest 每完成 `plan`、`author`、`run`、`accept`、`verify` 任一阶段后，应更新 `docs/loop-handoff/latest.md`，至少记录 `.opentest.yaml` 路径、当前阶段、测试资产路径、已运行验证、未运行验证、失败/阻塞和下一步。
+## 分发
 
-`opentest-verify` 生成的 verification report 路径必须写入 handoff，方便 OpenSuper verify 或新会话恢复时直接引用。
+1. 若 `.opentest.yaml` 不存在，运行 `bash "$OPENTEST_STATE" init`。
+2. 运行 `bash "$OPENTEST_STATE" check` 和 `bash "$OPENTEST_DETECT" summary`。
+3. 用 `bash "$OPENTEST_STATE" get phase` 读取阶段。
+4. 分发到 `opentest-plan`、`opentest-author`、`opentest-run`、`opentest-accept`、`opentest-verify`、`opentest-heal` 或 `opentest-archive`。
+5. 面向人的产物使用已安装的 skill 语言。

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

@@ -25,3 +25,17 @@
 `blocked` 证据必须包含原因，例如 MCP 不可用、环境不可用、缺少 seed data、需要认证，或外部服务失败。
 
 UI 反馈证据应记录反馈实际出现的位置和形态，例如字段级行内错误、表单级警告、轻提示、模态框、页面级错误面板、禁用控件、加载指示或重试操作。
+
+## 用例粒度规则
+
+验收矩阵必须区分渲染验证、功能验证和副作用验证，不能把“界面能打开”当成完整验收。
+
+- 渲染验证：确认入口、弹窗、表单、列表或关键控件能被真实页面渲染出来。
+- 功能验证：确认用户完成关键操作后，业务结果真实生效。
+- 副作用验证：确认操作完成后的弹窗、遮罩、loading、禁用态、toast 或错误态不会残留或误导下一步操作。
+
+凡是有表单提交、创建、编辑、删除、上传、授权、状态流转或其他写操作的用例，必须包含“填写/输入 -> 提交/确认 -> 验证结果生效”的完整链路。示例：
+
+- 地址表单能打开（渲染验证）。
+- 能填写表单并提交，新地址出现在列表或详情中（功能验证）。
+- 提交后弹窗关闭，页面无遮罩、无残留 loading，后续操作仍可继续（副作用验证）。

package/assets/skills-zh/opentest/references/complete-testing-workflow.md

@@ -0,0 +1,66 @@
+# 完整测试工作流
+
+只有当阶段 skill 要求读取详细覆盖规则时，才加载本引用。
+
+## 默认证据链
+
+```text
+plan -> matrix -> fixtures -> tests -> run -> accept -> smoke -> pre-push -> verify -> archive
+```
+
+## 测试数据
+
+变更涉及数据、文件、角色、权限、API 或有状态流程时，创建 `docs/opentest/fixtures/`。
+
+必需内容：
+
+- 用户和角色
+- 权限
+- 有效、已存在、非法、重复、无权限、过期状态的实体
+- 涉及上传、预览或媒体校验时的文件/图片
+- seed 命令和幂等规则
+- teardown 命令和清理范围
+- UI、API、DB/存储、文件、日志断言
+
+## CRUD 基线
+
+涉及持久化数据、API、表单、文件或有状态流程时，矩阵包含：
+
+- 新增：校验、成功、列表/详情可见
+- 查询/列表/详情：列表、搜索、筛选、分页、空态、详情
+- 修改：初始回显、校验失败、保存、回读
+- 删除：确认、取消、成功、删除后不可见
+- 失败/边界：非法、空、重复、无权限、过期、网络/API 错误
+- 数据一致性：UI、API、DB/存储、文件、日志
+- 端到端 CRUD：新增 -> 列表 -> 详情 -> 修改 -> 回读 -> 删除 -> 确认消失 -> 清理
+
+不适用的环节必须在 `缺口/阻塞` 中写明原因。
+
+## 交互验收硬规则
+
+Playwright CLI、浏览器 MCP 或人工真实页面验收执行 CRUD、表单提交、文件上传、授权、状态流转等写操作时，必须包含提交后断言，不能只截图或只确认页面未崩溃。
+
+推荐执行链路：
+
+```text
+open -> snapshot -> fill/input -> click(submit/confirm) -> snapshot -> read/assert changed result -> screenshot -> PASS/FAIL
+```
+
+- 写后读验证：提交后必须重新读取页面、列表、详情、API 响应、存储记录或日志中的至少一个可信结果面，确认值已变更。
+- 弹窗/遮罩验证：写操作成功后必须断言弹窗关闭、遮罩移除、loading 停止、按钮状态恢复，且下一步可操作。
+- 失败路径验证：校验失败、权限失败、网络/API 错误时，必须断言错误反馈位置、输入保留策略和可恢复路径。
+- 证据记录：PASS 必须说明断言到的变更结果；若无法读取结果面，状态应为 `blocked` 或 `risk-accepted`，并写明原因。
+
+## 运行质量门
+
+- targeted：与变更矩阵行相关的证据
+- fast：type、lint、unit
+- full：项目完整测试集
+- ci-like：CI 顺序
+- pre-push：format/check、lint、type、unit、targeted integration、smoke、`git diff --check`
+
+默认代码测试命令是 `python -m pytest`。覆盖率命令是 `python -m pytest --cov=. --cov-report=term-missing`。
+
+## Verify 质量门
+
+适用的高风险变更缺少必需 fixtures、seed/teardown、冒烟、pre-push、覆盖率、CRUD 或全链路验收证据时，不允许通过。

package/assets/skills-zh/opentest-accept/SKILL.md

@@ -5,21 +5,19 @@ description: "OpenTest 阶段 4：执行自然语言验收、MCP 验收或真实
 
 # OpenTest Accept
 
-## 目标
+执行必需验收项，并把 PASS、FAIL 或 blocked evidence 回写到用例和矩阵。
 
-执行必需验收项，并把 PASS、FAIL 或 blocked evidence 回写到验收用例和矩阵。
+## 必读引用
 
-## 步骤
-
-1. 读取矩阵和 `docs/opentest/acceptance/`。
-2. 对前端交互，优先用 Chrome DevTools MCP 执行真实页面验收。
-3. 对 API 或后台链路，使用项目已有命令或直接 API 检查。
-4. 对反馈类场景，必须观察实际呈现位置和形态；例如字段错误不能只记录“失败”，要记录是否在字段下方、表单顶部、轻提示、模态框或页面错误区显示。
-5. 工具、环境或前置数据不可用时，记录 blocked evidence。
-6. 更新验收记录。
-7. 更新 `docs/loop-handoff/latest.md`（如果项目使用 Loop Handoff），记录验收结果、截图/步骤证据路径、blocked evidence 和下一步。
-8. 运行 `bash "$OPENTEST_GUARD" accept --apply`。
+- `opentest/references/acceptance-evidence.md`
+- `opentest/references/complete-testing-workflow.md`
+- `opentest/templates/acceptance-template.md`
 
-## 现有技能路由
+## 步骤
 
-前端交互验收优先使用自然语言用例加 Chrome DevTools MCP。执行前先确认用例覆盖的是本次适用维度；执行后把 PASS、FAIL 或 blocked 写回对应 ACC ID。
+1. 读取矩阵、fixtures 和 `docs/opentest/acceptance/`。
+2. 前端交互优先用 Chrome DevTools MCP 执行真实页面验收。
+3. API/后台链路使用项目命令或直接 API 检查。
+4. CRUD/数据变更执行 workflow 引用中的完整链路。
+5. 记录反馈位置/形态、产物、blocked evidence 和对应 ACC ID。
+6. 更新验收记录并运行 `bash "$OPENTEST_GUARD" accept --apply`。

package/assets/skills-zh/opentest-author/SKILL.md

@@ -1,30 +1,24 @@
 ---
 name: opentest-author
-description: "OpenTest 阶段 2：根据矩阵补齐测试资产和自然语言验收用例。"
+description: "OpenTest 阶段 2：根据矩阵补齐测试资产、fixtures 和自然语言验收用例。"
 ---
 
 # OpenTest Author
 
-## 目标
+把矩阵转成可执行测试、fixtures、seed/teardown 说明和验收用例。
 
-根据 acceptance-to-test matrix 创建或更新测试资产。
+## 必读引用
 
-本阶段把矩阵变成可执行证据：能用项目测试框架证明的写测试；更适合真实链路、浏览器、API 或人工可复验步骤证明的，写自然语言验收用例。不要为了“像 TDD”而把所有交互反馈硬塞进 unit test。
+- `opentest/references/opentest-driven-development.md`
+- `opentest/references/complete-testing-workflow.md`
+- `opentest/templates/fixtures-template.md`
+- `opentest/templates/acceptance-template.md`
 
 ## 步骤
 
-1. 读取 `.opentest.yaml` 中的 `matrix`。
-2. 对 unit/component/integration/contract 证据，按项目已有测试框架创建或更新测试文件。
-3. 当矩阵要求代码级测试、且项目没有明确框架规则或既有框架时，默认使用 pytest；优先放在 `tests/`，并确保可用 `python -m pytest` 运行。
-4. 根据 fixtures 模板创建或更新 `docs/opentest/fixtures/`，包括用户、角色、实体、文件/图片、seed、teardown 和断言界面。
-5. 对 E2E、smoke、browser acceptance、真实 API 或跨页面流程，写入 `docs/opentest/acceptance/` 自然语言验收用例。
-6. 对 CRUD 或数据写入类变更，补完整工作流用例：新增 -> 列表 -> 详情 -> 修改 -> 回读 -> 删除 -> 确认消失 -> 清理。
-7. 对前端反馈类用例，写清反馈位置和形态，例如字段下方错误、表单顶部错误、轻提示、模态框、行内状态或页面错误态。
-8. 对不适用或当前无法补齐的证据，记录原因和风险。
-9. 写入 `.opentest.yaml` 的 `fixtures` 和 `acceptance` 字段。
-10. 更新 `docs/loop-handoff/latest.md`（如果项目使用 Loop Handoff），记录 fixtures、seed/teardown、测试资产、自然语言验收用例、gap/risk 和下一步。
-11. 运行 `bash "$OPENTEST_GUARD" author --apply`。
-
-## 现有技能路由
-
-当矩阵要求代码级测试证据时，优先加载现有 TDD guidance。若项目规则要求特定测试框架，遵循项目规则。若项目没有测试框架，默认使用 pytest，不临时发明自定义测试壳。若当前任务更适合真实验收而不是新增测试框架代码，记录原因并交给 `opentest-accept`。
+1. 读取 `.opentest.yaml` 的 `matrix` 和 `fixtures`。
+2. 代码级证据优先用项目框架；没有框架时默认使用 pytest，测试放入 `tests/` 并可用 `python -m pytest` 运行。
+3. 创建/更新 fixtures、seed、teardown、用户、角色、实体、文件/图片和断言界面。
+4. CRUD/数据变更必须补全链路：新增 -> 列表 -> 详情 -> 修改 -> 回读 -> 删除 -> 确认消失 -> 清理。
+5. 记录 gap/blocker 的原因和风险。
+6. 写入 `.opentest.yaml` 的 `fixtures`、`acceptance`，再运行 `bash "$OPENTEST_GUARD" author --apply`。

package/assets/skills-zh/opentest-plan/SKILL.md

@@ -5,32 +5,23 @@ description: "OpenTest 阶段 1：分析变更、风险和项目事实，生成
 
 # OpenTest Plan
 
-## 目标
+在实现前生成 `docs/opentest/plans/`、`docs/opentest/matrices/` 和测试数据计划。
 
-生成 `docs/opentest/plans/` 下的测试策略和 `docs/opentest/matrices/` 下的矩阵。
+## 必读引用
 
-本阶段是 OpenTest-driven development 的入口。它必须在实现前把“需求没写但成熟产品默认应该处理”的场景显性化，避免只根据字面需求写少量 happy path 测试。
+- `opentest/references/codex-harness-coverage-heuristics.md`
+- `opentest/references/matrix-format.md`
+- `opentest/references/complete-testing-workflow.md`
 
 ## 步骤
 
-1. 读取项目规则、需求、设计、diff、现有测试命令和 `opentest/references/codex-harness-coverage-heuristics.md`。
-2. 如果存在前端、表单、导航、CRUD、状态反馈或动效，优先读取项目内 `docs/frontend/DESIGN.md` 和可用的 `harness-frontend-design` / `product-ui-defaults` 规则。
-3. 判断变更类型、风险等级、适用覆盖维度，以及代码级证据应使用项目已有框架还是默认 `pytest` 框架。
-4. 定义测试数据计划：用户、角色、权限、实体、文件/图片、seed 命令、teardown 命令，以及 UI/API/DB/文件/日志断言。
-5. 做隐性场景挖掘：空输入、非法输入、网络失败、权限不足、重复提交、长内容、空数据、错误映射、移动端、可访问性、跨页面返回和状态恢复。
-6. 对涉及持久化数据、API、表单、文件或有状态工作流的变更，默认套用 CRUD 基线：新增、查询/列表/详情/搜索/筛选、修改/回读、删除/取消/删除后检查、数据一致性、端到端 CRUD。
-7. 生成窄矩阵，至少包含 `ID`、`意图`、`覆盖维度`、`触发/输入`、`期望行为`、`风险`、`证据层级`、`框架/命令`、`必需证据`、`缺口/阻塞`、`状态`。
-8. 对适用但未覆盖的证据面标记 `gap`，并写清具体阻塞或恢复路径，不把覆盖状态留成 unknown。
-9. 写入 `.opentest.yaml` 的 `plan`、`matrix` 和 `fixtures` 字段。
-10. 更新 `docs/loop-handoff/latest.md`（如果项目使用 Loop Handoff），记录 plan、matrix、fixtures 路径、当前阶段和下一步。
-11. 运行 `bash "$OPENTEST_GUARD" plan --apply`。
+1. 读取项目规则、需求/设计/diff、现有命令和 detect 输出。
+2. 判断风险、适用覆盖面、测试数据，以及代码测试使用项目框架还是默认 `pytest`。
+3. 数据写入、API、表单、文件或有状态流程默认套用 CRUD 基线和测试数据要求。
+4. 生成矩阵，包含覆盖维度、框架/命令、必需证据、缺口/阻塞和状态。
+5. 写入 `.opentest.yaml` 的 `plan`、`matrix`、`fixtures`。
+6. 如存在 handoff，同步 plan/matrix/fixtures 路径，然后运行 `bash "$OPENTEST_GUARD" plan --apply`。
 
-## 约束
+## 质量门
 
-不要把 Codex Harness 全量 checklist 展开成固定必需项。低风险变更保留轻量覆盖摘要，高风险闭环再展开详细验收维度。
-
-不要把所有证据都写成 unit test。矩阵要明确哪些用 unit/component/integration/contract/E2E/smoke/browser acceptance/security review 证明。
-
-覆盖完整性指每个适用的产品行为、失败路径、边界和风险面都有必需证据，或有明确的 gap/blocker；不是要求每次任务都跑所有测试类型。
-
-CRUD 基线和测试数据是数据写入类变更的默认要求。若某个 CRUD 环节不适用，必须在矩阵中写明原因。
+每个适用行为、失败路径、边界和风险面都要有证据或明确 gap/blocker。CRUD 基线和测试数据默认必需；不适用时必须在矩阵写明原因。

package/assets/skills-zh/opentest-run/SKILL.md

@@ -1,34 +1,31 @@
 ---
 name: opentest-run
-description: "OpenTest 阶段 3：按 targeted、fast、full 或 ci-like 模式运行项目测试命令。"
+description: "OpenTest 阶段 3：按 targeted、fast、full、ci-like 或 pre-push 模式运行项目测试命令。"
 ---
 
 # OpenTest Run
 
-## 目标
+运行矩阵驱动的命令，并把证据写到 `docs/opentest/runs/`。
 
-执行项目已有验证命令并写入运行报告。
+## 必读引用
 
-## 模式
-
-- `targeted`：只运行与矩阵相关的测试命令。
-- `fast`：运行快速反馈命令，例如 type、lint、unit。
-- `full`：运行项目完整测试命令。
-- `ci-like`：尽量复现 CI 验证顺序。
-- `pre-push`：push 或发布前运行推送质量门序列。
+- `opentest/references/command-routing.md`
+- `opentest/references/complete-testing-workflow.md`
 
-证据层级由矩阵决定。不要因为存在 `npm test` 就只跑 unit test；如果矩阵要求 integration、contract、E2E、smoke 或安全检查，必须运行对应项目命令，或记录 missing command / blocked。
-
-如果 `.opentest.yaml` 中 `test_framework: pytest`，或矩阵要求代码级测试但项目没有声明测试框架，默认测试命令使用 `python -m pytest`。当矩阵要求覆盖率证据时，优先使用 `python -m pytest --cov=. --cov-report=term-missing`，并把覆盖率输出路径写入 `.opentest.yaml` 的 `coverage_report`。如果缺少 pytest 或 pytest-cov，记录 `missing command` 和安装/恢复步骤，不允许直接通过质量门。
+## 模式
 
-普通功能变更默认必须有冒烟证据，除非矩阵明确写明不适用。pre-push 运行应包含项目等价的 format/check、lint、type、unit、targeted integration、smoke 和 `git diff --check`；缺少命令时必须记录 missing 或 not applicable。
+- `targeted`：只跑矩阵相关命令。
+- `fast`：type/lint/unit 快速反馈。
+- `full`：项目完整命令集。
+- `ci-like`：尽量复现 CI 顺序。
+- `pre-push`：push 质量门。
 
 ## 步骤
 
-1. 读取 `.opentest.yaml` 的 `run_mode` 和矩阵。
-2. 优先使用项目显式命令，按矩阵中的证据层级选择 targeted、fast、full 或 ci-like。
-3. 如果代码级测试没有显式命令，运行或记录默认 pytest 命令。
-4. 记录命令、退出码、摘要、覆盖率输出、冒烟输出、pre-push 输出和日志路径到 `docs/opentest/runs/`。
-5. 写入 `.opentest.yaml` 的 `run_report` 字段；当要求或产生对应证据时，也写入 `coverage_report`、`smoke_report` 或 `pre_push_report`。
-6. 更新 `docs/loop-handoff/latest.md`（如果项目使用 Loop Handoff），记录已运行验证、未运行验证、失败/阻塞、run report 路径和下一步。
+1. 读取 `run_mode`、矩阵、fixtures 和必需证据。
+2. 优先使用项目命令；没有代码级命令时用 `python -m pytest`。
+3. 覆盖率优先用 `python -m pytest --cov=. --cov-report=term-missing`。
+4. 除非矩阵写明不适用，否则必须有冒烟证据。
+5. `pre-push` 运行或记录 format/check、lint、type、unit、targeted integration、smoke、`git diff --check`。
+6. 写入 `run_report`，必要时写入 `coverage_report`、`smoke_report`、`pre_push_report`。
 7. 运行 `bash "$OPENTEST_GUARD" run --apply`。

package/assets/skills-zh/opentest-verify/SKILL.md

@@ -5,25 +5,20 @@ description: "OpenTest 阶段 5：应用质量门并生成验证报告。"
 
 # OpenTest Verify
 
-## 目标
+应用质量门，并写入 `verification_report` 与 `verification_result`。
 
-应用质量门，输出结构化验证报告，并把结果写回状态文件。
+## 必读引用
 
-## 验证顺序
+- `opentest/references/quality-gate.md`
+- `opentest/references/complete-testing-workflow.md`
+- `opentest/templates/report-template.md`
 
-验证报告按 build、type、lint、test、security、diff 组织。若项目没有某类命令，记录为 missing command 或 not applicable，不把未知状态写成 pass。
+## 步骤
 
-按 build、type、lint、test、security、diff 的顺序组织证据。必需测试、必需验收、构建、类型或 lint 失败时标记 `fail`。非必需缺口可记录为 `risk-accepted`。写入 `docs/opentest/reports/` 和 `.opentest.yaml` 的 `verification_report`、`verification_result`。
-如果项目使用 Loop Handoff，同时把 OpenTest verification report 路径、verification result、已运行验证、未运行验证、失败/阻塞和下一步写入 `docs/loop-handoff/latest.md`。
-
-验证报告还必须回看矩阵，确认：
-
-- 每个 required evidence 都有 pass、fail、blocked 或 risk-accepted 结论。
-- 覆盖完整性已检查：矩阵中的每个适用覆盖维度都有必需证据、运行/验收结果，或带恢复路径的明确 gap/blocker。
-- 测试数据可追踪：数据写入或 CRUD 变更必须有 fixture、seed、teardown 和清理证据。
-- 必须有冒烟证据，除非矩阵明确标记 smoke 不适用。
-- push/publish 前必须有 pre-push 证据；除非用户明确跳过，并在报告里记录风险。
-- 高风险行为不能因为没有工具、没有测试框架或没有 seed data 就直接通过。
-- 如果要求代码级覆盖率且 `test_framework: pytest` 生效，报告必须包含 `python -m pytest` 命令结果和 `coverage_report` 路径；否则必须 fail/block 并写明原因。
-- blocked evidence 必须包含阻塞原因和后续恢复路径。
-- 若产品行为失败，不进入 `heal` 修测试资产；应返回实现或需求修正。
+1. 按 build、type、lint、test、security、diff 组织证据。
+2. 每个 required evidence 必须有 pass、fail、blocked 或 risk-accepted。
+3. 检查覆盖完整性：每个适用覆盖维度都有证据，或有带恢复路径的 gap/blocker。
+4. 除非矩阵标记不适用，否则必须有冒烟证据。
+5. push/publish 前必须有 pre-push 证据；用户明确跳过时要记录风险。
+6. CRUD/数据变更按适用性要求测试数据、fixture、seed、teardown、清理和 `coverage_report` 证据。
+7. 不能因为缺工具、fixture、seed data 或测试框架就让高风险行为通过。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pzy560117/opentest",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "OpenTest quality evidence lifecycle skills for Codex",
   "keywords": [
     "opentest",

package/scripts/smoke-test.js

@@ -242,6 +242,35 @@ function assertCompleteTestingWorkflowContracts() {
   assert(chineseVerify.includes('必须有冒烟证据') && chineseVerify.includes('必须有 pre-push 证据') && chineseVerify.includes('测试数据'), '[VERIFY] Chinese verify skill must gate smoke, pre-push, and test data');
 }
 
+function assertProgressiveDisclosureContracts() {
+  const stageSkillPaths = [
+    'assets/skills/opentest/SKILL.md',
+    'assets/skills/opentest-plan/SKILL.md',
+    'assets/skills/opentest-author/SKILL.md',
+    'assets/skills/opentest-run/SKILL.md',
+    'assets/skills/opentest-accept/SKILL.md',
+    'assets/skills/opentest-verify/SKILL.md',
+    'assets/skills-zh/opentest/SKILL.md',
+    'assets/skills-zh/opentest-plan/SKILL.md',
+    'assets/skills-zh/opentest-author/SKILL.md',
+    'assets/skills-zh/opentest-run/SKILL.md',
+    'assets/skills-zh/opentest-accept/SKILL.md',
+    'assets/skills-zh/opentest-verify/SKILL.md',
+  ];
+
+  for (const skillPath of stageSkillPaths) {
+    const content = readFileSync(skillPath, 'utf8');
+    assert(content.length <= 1800, `[DISCLOSURE] ${skillPath} must stay concise and move detail into references`);
+    assert(
+      content.includes('Required references') || content.includes('必读引用'),
+      `[DISCLOSURE] ${skillPath} must declare required references near the top`,
+    );
+  }
+
+  const manifestText = readFileSync('assets/manifest.json', 'utf8');
+  assert(manifestText.includes('opentest/references/complete-testing-workflow.md'), '[DISCLOSURE] manifest must ship complete testing workflow reference');
+}
+
 async function assertPrepublishRejectsPublishSecretTextFiles() {
   const fixtureDir = path.join('assets', 'opentest-smoke-secret-fixtures');
   const fixtures = [
@@ -547,6 +576,7 @@ assertManifestStructure();
 assertPrepublishGateCoversManifestAssets();
 assertDefaultPytestContracts();
 assertCompleteTestingWorkflowContracts();
+assertProgressiveDisclosureContracts();
 assertOpenTestSearchRootsCoverPlatforms();
 assertLanguageAssetContracts();
 await assertPrepublishRejectsPublishSecretTextFiles();