@pzy560117/opentest 0.1.6 → 0.1.8

package/assets/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.6",
+  "version": "0.1.8",
   "languages": [
     {
       "id": "en",
@@ -62,12 +62,14 @@
       "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",
       "opentest/references/quality-gate.md",
       "opentest/templates/acceptance-template.md",
       "opentest/templates/archive-layout.md",
+      "opentest/templates/fixtures-template.md",
       "opentest/templates/matrix-template.md",
       "opentest/templates/plan-template.md",
       "opentest/templates/report-template.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/complete-testing-workflow.md

@@ -0,0 +1,51 @@
+# 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`.
+
+## 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/scripts/opentest-detect.sh

@@ -39,6 +39,8 @@ summary() {
   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/fixtures ]; then printf 'fixtures_dir: present\n'; else printf 'fixtures_dir: missing\n'; fi
+  if [ -f docs/opentest/fixtures/seed.md ] || [ -f docs/opentest/fixtures/seed.json ]; then printf 'seed_data: present\n'; else printf 'seed_data: 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
 

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

@@ -69,7 +69,7 @@ require_state_file() {
 
 validate_known_field() {
   case "$1" in
-    workflow|phase|plan|matrix|acceptance|run_mode|run_report|test_framework|coverage_report|verification_result|verification_report|archived|created_at|updated_at)
+    workflow|phase|plan|matrix|fixtures|acceptance|run_mode|run_report|smoke_report|pre_push_report|test_framework|coverage_report|verification_result|verification_report|archived|created_at|updated_at)
       return 0
       ;;
     *)
@@ -110,9 +110,12 @@ workflow: standard
 phase: plan
 plan: null
 matrix: null
+fixtures: null
 acceptance: null
 run_mode: targeted
 run_report: null
+smoke_report: null
+pre_push_report: null
 test_framework: pytest
 coverage_report: null
 verification_result: pending
@@ -144,7 +147,7 @@ cmd_set() {
       validate_enum "$value" plan author run accept verify heal archive
       ;;
     run_mode)
-      validate_enum "$value" targeted fast full ci-like
+      validate_enum "$value" targeted fast full ci-like pre-push
       ;;
     verification_result)
       validate_enum "$value" pending pass fail risk-accepted
@@ -246,7 +249,7 @@ cmd_check() {
 
   validate_enum "$workflow" standard
   validate_enum "$phase" plan author run accept verify heal archive
-  validate_enum "$run_mode" targeted fast full ci-like
+  validate_enum "$run_mode" targeted fast full ci-like pre-push
   validate_enum "$verification_result" pending pass fail risk-accepted
   validate_enum "$archived" true false
 

package/assets/skills/opentest/templates/acceptance-template.md

@@ -30,3 +30,22 @@
 - status:
 - notes:
 - artifacts:
+
+## Full CRUD Flow
+
+Use this default full-chain case when the change touches create, read, update, delete, data writes, files, permissions, or cross-page flows.
+
+```text
+create -> list -> detail -> update -> read back -> delete -> confirm absence -> teardown
+```
+
+- fixture:
+- actor/role:
+- create assertion:
+- list assertion:
+- detail assertion:
+- update assertion:
+- read-back assertion:
+- delete/cancel assertion:
+- post-delete assertion:
+- cleanup assertion:

package/assets/skills/opentest/templates/fixtures-template.md

@@ -0,0 +1,52 @@
+# OpenTest Test Data Fixtures
+
+## Purpose
+
+Record the exact test data needed to prove every matrix item. Keep fixtures deterministic, isolated, and safe to rerun.
+
+## users
+
+| id | role | permissions | purpose |
+| --- | --- | --- | --- |
+| user-admin | admin | create/read/update/delete | CRUD happy path |
+| user-readonly | viewer | read only | permission denial |
+
+## roles
+
+- admin:
+- viewer:
+- unauthorized:
+
+## Entities
+
+| id | state | fields | used by ACC IDs |
+| --- | --- | --- | --- |
+| entity-create-valid | valid new record |  | ACC-001 |
+| entity-existing | persisted record |  | ACC-002, ACC-003, ACC-004 |
+| entity-invalid | invalid/boundary data |  | ACC-005 |
+
+## files/images
+
+| path | type | purpose | cleanup |
+| --- | --- | --- | --- |
+| docs/opentest/fixtures/files/sample-image.png | image | upload / preview / file validation | remove after test |
+
+## Seed
+
+- command:
+- data source:
+- idempotency rule:
+
+## teardown
+
+- command:
+- cleanup scope:
+- rollback notes:
+
+## Assertions
+
+- UI:
+- API:
+- DB/storage:
+- files:
+- logs:

package/assets/skills/opentest/templates/matrix-template.md

@@ -2,5 +2,12 @@
 
 | ID | Intent | Coverage dimension | Trigger/Input | Expected behavior | Risk | Evidence layer | Framework/command | Required evidence | Gap/blocker | Status |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| ACC-001 | Happy path succeeds | main path |  |  | low | smoke | project command or `python -m pytest` | targeted review | none | pending |
-| ACC-002 | Failure or boundary path | failure/boundary |  |  | medium | acceptance | natural-language acceptance or `python -m pytest` | UI/API acceptance | none | pending |
+| ACC-001 | create succeeds | create | valid fixture entity | entity is created and visible in list/detail | high | integration + acceptance | `python -m pytest` + real workflow | create evidence, UI/API/DB assertion, fixture used | none | pending |
+| ACC-002 | read/list/detail succeeds | read/list/detail | seeded entity | list, search/filter, and detail show correct data | high | integration + acceptance | `python -m pytest` + real workflow | read/list/detail evidence and data consistency check | none | pending |
+| ACC-003 | update succeeds | update | edited fixture entity | updated values persist after read back | high | integration + acceptance | `python -m pytest` + real workflow | update evidence and read-back assertion | none | pending |
+| ACC-004 | delete succeeds safely | delete | existing fixture entity | confirm/cancel behavior works; deleted item disappears after confirmation | high | integration + acceptance | `python -m pytest` + real workflow | delete evidence, cancel evidence, post-delete read check | none | pending |
+| ACC-005 | failure and boundary paths are handled | failure/boundary | invalid, empty, duplicate, unauthorized, or stale fixture data | clear feedback without corrupting data | high | unit/integration/acceptance | `python -m pytest` + acceptance | validation, permission, duplicate, stale-state evidence | none | pending |
+| ACC-006 | data consistency holds | data consistency | create/update/delete flow | UI, API, database/storage, files, and logs agree | high | integration | project command or `python -m pytest` | consistency evidence across surfaces | none | pending |
+| ACC-007 | end-to-end CRUD flow works | end-to-end CRUD | create -> list -> detail -> update -> read back -> delete | full user workflow completes and leaves clean state | high | E2E/acceptance | browser/API workflow | full-chain steps, screenshots/logs, cleanup evidence | none | pending |
+| ACC-008 | smoke gate passes | smoke | app starts and core entry points open | core route/API/CRUD happy path does not crash | high | smoke | project smoke command or targeted workflow | smoke_report path | none | pending |
+| ACC-009 | pre-push gate passes | pre-push | staged change before push | format/lint/type/unit/integration/smoke/diff checks pass or block push | high | pre-push | project command sequence | pre_push_report path | none | pending |

package/assets/skills/opentest/templates/report-template.md

@@ -21,6 +21,24 @@
 | ID | evidence layer | required evidence | result | gap/risk |
 | --- | --- | --- | --- | --- |
 
+## Test Data
+
+- fixtures:
+- seed:
+- teardown:
+- data cleanup result:
+
+## Smoke
+
+- smoke_report:
+- result:
+
+## Pre-Push
+
+- pre_push_report:
+- command sequence:
+- result:
+
 ## Quality Gate
 
 - blocking:

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,28 +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. For E2E, smoke, browser acceptance, real APIs, or cross-page flows, write natural language acceptance cases under `docs/opentest/acceptance/`.
-5. 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.
-6. Record reasons and risk for evidence that is not applicable or cannot currently be created.
-7. Write the `.opentest.yaml` `acceptance` field.
-8. If the project uses Loop Handoff, update `docs/loop-handoff/latest.md` with test assets, natural language acceptance cases, gaps/risks, and next step.
-9. 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,32 +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. 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.
-5. 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`.
-6. Mark applicable but uncovered evidence as `gap`, and record a concrete blocker or recovery path instead of leaving coverage unknown.
-7. Write the `.opentest.yaml` `plan` and `matrix` fields.
-8. If the project uses Loop Handoff, update `docs/loop-handoff/latest.md` with the plan path, matrix path, current phase, and next step.
-9. 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.
+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,31 +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.
+- `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.
+## Modes
 
-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.
+- `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, and log path under `docs/opentest/runs/`.
-5. Write the `.opentest.yaml` `run_report` field, and write `coverage_report` when coverage 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,22 +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.
-- 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/complete-testing-workflow.md

@@ -0,0 +1,51 @@
+# 完整测试工作流
+
+只有当阶段 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：新增 -> 列表 -> 详情 -> 修改 -> 回读 -> 删除 -> 确认消失 -> 清理
+
+不适用的环节必须在 `缺口/阻塞` 中写明原因。
+
+## 运行质量门
+
+- 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/templates/acceptance-template.md

@@ -30,3 +30,22 @@
 - status:
 - 备注:
 - 产物:
+
+## 完整 CRUD 链路
+
+当变更涉及新增、查询、修改、删除、数据写入、文件、权限或跨页面流程时，默认补这个全链路用例。
+
+```text
+新增 -> 列表 -> 详情 -> 修改 -> 回读 -> 删除 -> 确认消失 -> 清理
+```
+
+- fixture:
+- 执行角色:
+- 新增断言:
+- 列表断言:
+- 详情断言:
+- 修改断言:
+- 回读断言:
+- 删除/取消断言:
+- 删除后断言:
+- 清理断言:

package/assets/skills-zh/opentest/templates/fixtures-template.md

@@ -0,0 +1,52 @@
+# OpenTest 测试数据 Fixtures
+
+## 目的
+
+记录每个矩阵项需要的测试数据。测试数据必须确定、隔离、可重复执行。
+
+## 用户
+
+| id | 角色 | 权限 | 用途 |
+| --- | --- | --- | --- |
+| user-admin | admin | 新增/查询/修改/删除 | CRUD 主路径 |
+| user-readonly | viewer | 只读 | 权限拒绝 |
+
+## 角色
+
+- admin:
+- viewer:
+- unauthorized:
+
+## 实体
+
+| id | 状态 | 字段 | 对应 ACC |
+| --- | --- | --- | --- |
+| entity-create-valid | 有效新记录 |  | ACC-001 |
+| entity-existing | 已存在记录 |  | ACC-002, ACC-003, ACC-004 |
+| entity-invalid | 非法/边界数据 |  | ACC-005 |
+
+## 文件/图片
+
+| 路径 | 类型 | 用途 | 清理 |
+| --- | --- | --- | --- |
+| docs/opentest/fixtures/files/sample-image.png | 图片 | 上传/预览/文件校验 | 测试后删除 |
+
+## Seed
+
+- 命令:
+- 数据来源:
+- 幂等规则:
+
+## Teardown
+
+- 命令:
+- 清理范围:
+- 回滚说明:
+
+## 断言
+
+- UI:
+- API:
+- DB/存储:
+- 文件:
+- 日志:

package/assets/skills-zh/opentest/templates/matrix-template.md

@@ -2,5 +2,12 @@
 
 | ID | 意图 | 覆盖维度 | 触发/输入 | 期望行为 | 风险 | 证据层级 | 框架/命令 | 必需证据 | 缺口/阻塞 | 状态 |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| ACC-001 | 主路径成功 | 主路径 |  |  | low | smoke | 项目命令或 `python -m pytest` | targeted review | 无 | pending |
-| ACC-002 | 失败/边界路径 | 失败/边界 |  |  | medium | acceptance | 自然语言验收或 `python -m pytest` | UI/API 验收 | 无 | pending |
+| ACC-001 | 新增成功 | 新增 | 有效 fixture 实体 | 创建成功，并能在列表/详情中看到 | high | integration + acceptance | `python -m pytest` + 真实工作流 | 新增证据、UI/API/DB 断言、使用的测试数据 | 无 | pending |
+| ACC-002 | 查询/列表/详情成功 | 查询/列表/详情 | 已 seed 的实体 | 列表、搜索/筛选、详情显示正确数据 | high | integration + acceptance | `python -m pytest` + 真实工作流 | 查询/列表/详情证据和数据一致性检查 | 无 | pending |
+| ACC-003 | 修改成功 | 修改 | 编辑 fixture 实体 | 保存后回读仍是新值 | high | integration + acceptance | `python -m pytest` + 真实工作流 | 修改证据和回读断言 | 无 | pending |
+| ACC-004 | 删除安全成功 | 删除 | 已存在 fixture 实体 | 删除确认/取消正确；确认删除后不可见 | high | integration + acceptance | `python -m pytest` + 真实工作流 | 删除证据、取消证据、删除后回读检查 | 无 | pending |
+| ACC-005 | 失败/边界路径可控 | 失败/边界 | 非法、空、重复、无权限或过期 fixture 数据 | 给出清晰反馈且不污染数据 | high | unit/integration/acceptance | `python -m pytest` + 验收 | 校验、权限、重复提交、过期状态证据 | 无 | pending |
+| ACC-006 | 数据一致性成立 | 数据一致性 | 新增/修改/删除闭环 | UI、API、数据库/存储、文件和日志一致 | high | integration | 项目命令或 `python -m pytest` | 跨界面一致性证据 | 无 | pending |
+| ACC-007 | 端到端 CRUD 链路可用 | 端到端 CRUD | 新增 -> 列表 -> 详情 -> 修改 -> 回读 -> 删除 | 完整用户链路通过并留下干净状态 | high | E2E/acceptance | 浏览器/API 工作流 | 全链路步骤、截图/日志、清理证据 | 无 | pending |
+| ACC-008 | 冒烟质量门通过 | 冒烟 | 应用启动且核心入口可访问 | 核心路由/API/CRUD 主路径不崩 | high | smoke | 项目冒烟命令或 targeted workflow | smoke_report 路径 | 无 | pending |
+| ACC-009 | pre-push 质量门通过 | pre-push | push 前 staged change | format/lint/type/unit/integration/smoke/diff 检查通过，否则阻止 push | high | pre-push | 项目命令序列 | pre_push_report 路径 | 无 | pending |

package/assets/skills-zh/opentest/templates/report-template.md

@@ -21,6 +21,24 @@
 | ID | 证据层级 | 必需证据 | result | 缺口/风险 |
 | --- | --- | --- | --- | --- |
 
+## 测试数据
+
+- fixtures:
+- seed:
+- teardown:
+- 数据清理结果:
+
+## 冒烟
+
+- smoke_report:
+- result:
+
+## Pre-Push
+
+- pre_push_report:
+- 命令序列:
+- result:
+
 ## 质量门
 
 - 阻塞项:

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,28 +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. 对 E2E、smoke、browser acceptance、真实 API 或跨页面流程，写入 `docs/opentest/acceptance/` 自然语言验收用例。
-5. 对前端反馈类用例，写清反馈位置和形态，例如字段下方错误、表单顶部错误、轻提示、模态框、行内状态或页面错误态。
-6. 对不适用或当前无法补齐的证据，记录原因和风险。
-7. 写入 `.opentest.yaml` 的 `acceptance` 字段。
-8. 更新 `docs/loop-handoff/latest.md`（如果项目使用 Loop Handoff），记录测试资产、自然语言验收用例、gap/risk 和下一步。
-9. 运行 `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,28 +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. 做隐性场景挖掘：空输入、非法输入、网络失败、权限不足、重复提交、长内容、空数据、错误映射、移动端、可访问性、跨页面返回和状态恢复。
-5. 生成窄矩阵，至少包含 `ID`、`意图`、`覆盖维度`、`触发/输入`、`期望行为`、`风险`、`证据层级`、`框架/命令`、`必需证据`、`缺口/阻塞`、`状态`。
-6. 对适用但未覆盖的证据面标记 `gap`，并写清具体阻塞或恢复路径，不把覆盖状态留成 unknown。
-7. 写入 `.opentest.yaml` 的 `plan` 和 `matrix` 字段。
-8. 更新 `docs/loop-handoff/latest.md`（如果项目使用 Loop Handoff），记录 plan、matrix 路径、当前阶段和下一步。
-9. 运行 `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；不是要求每次任务都跑所有测试类型。
+每个适用行为、失败路径、边界和风险面都要有证据或明确 gap/blocker。CRUD 基线和测试数据默认必需；不适用时必须在矩阵写明原因。

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

@@ -1,31 +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 验证顺序。
+- `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` 和安装/恢复步骤，不允许直接通过质量门。
+- `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. 记录命令、退出码、摘要、覆盖率输出和日志路径到 `docs/opentest/runs/`。
-5. 写入 `.opentest.yaml` 的 `run_report` 字段；当要求或产生覆盖率证据时，也写入 `coverage_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,22 +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。
-- 高风险行为不能因为没有工具、没有测试框架或没有 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.6",
+  "version": "0.1.8",
   "description": "OpenTest quality evidence lifecycle skills for Codex",
   "keywords": [
     "opentest",

package/scripts/smoke-test.js

@@ -32,6 +32,15 @@ function assert(condition, message) {
   }
 }
 
+function readRequiredText(filePath, message) {
+  try {
+    return readFileSync(filePath, 'utf8');
+  } catch {
+    assert(false, message);
+    return '';
+  }
+}
+
 function pathSegments(file) {
   return file.split(/[\\/]+/).filter(Boolean);
 }
@@ -183,6 +192,85 @@ function assertDefaultPytestContracts() {
   assert(chineseMatrix.includes('覆盖维度') && chineseMatrix.includes('框架/命令') && chineseMatrix.includes('缺口/阻塞'), '[COVERAGE] Chinese matrix template must include coverage, command, and gap columns');
 }
 
+function assertCompleteTestingWorkflowContracts() {
+  const stateScript = readFileSync('assets/skills/opentest/scripts/opentest-state.sh', 'utf8');
+  const detectScript = readFileSync('assets/skills/opentest/scripts/opentest-detect.sh', 'utf8');
+  const manifestText = readFileSync('assets/manifest.json', 'utf8');
+  const englishPlan = readFileSync('assets/skills/opentest-plan/SKILL.md', 'utf8');
+  const chinesePlan = readFileSync('assets/skills-zh/opentest-plan/SKILL.md', 'utf8');
+  const englishAuthor = readFileSync('assets/skills/opentest-author/SKILL.md', 'utf8');
+  const chineseAuthor = readFileSync('assets/skills-zh/opentest-author/SKILL.md', 'utf8');
+  const englishRun = readFileSync('assets/skills/opentest-run/SKILL.md', 'utf8');
+  const chineseRun = readFileSync('assets/skills-zh/opentest-run/SKILL.md', 'utf8');
+  const englishVerify = readFileSync('assets/skills/opentest-verify/SKILL.md', 'utf8');
+  const chineseVerify = readFileSync('assets/skills-zh/opentest-verify/SKILL.md', 'utf8');
+  const englishMatrix = readFileSync('assets/skills/opentest/templates/matrix-template.md', 'utf8');
+  const chineseMatrix = readFileSync('assets/skills-zh/opentest/templates/matrix-template.md', 'utf8');
+  const englishFixture = readRequiredText('assets/skills/opentest/templates/fixtures-template.md', '[FIXTURES] missing English fixture template');
+  const chineseFixture = readRequiredText('assets/skills-zh/opentest/templates/fixtures-template.md', '[FIXTURES] missing Chinese fixture template');
+  const englishAcceptance = readFileSync('assets/skills/opentest/templates/acceptance-template.md', 'utf8');
+  const chineseAcceptance = readFileSync('assets/skills-zh/opentest/templates/acceptance-template.md', 'utf8');
+
+  assert(manifestText.includes('opentest/templates/fixtures-template.md'), '[FIXTURES] manifest must ship fixture templates');
+  assert(stateScript.includes('fixtures: null'), '[FIXTURES] state init must track fixtures');
+  assert(stateScript.includes('smoke_report: null'), '[SMOKE] state init must track smoke_report');
+  assert(stateScript.includes('pre_push_report: null'), '[PREPUSH] state init must track pre_push_report');
+  assert(stateScript.includes('fixtures|'), '[FIXTURES] state script must allow fixtures field updates');
+  assert(stateScript.includes('targeted fast full ci-like pre-push'), '[PREPUSH] state script must allow pre-push run mode');
+  assert(detectScript.includes('fixtures_dir:'), '[FIXTURES] detect summary must report fixtures_dir');
+  assert(detectScript.includes('seed_data:'), '[FIXTURES] detect summary must report seed_data');
+
+  for (const keyword of ['create', 'read/list/detail', 'update', 'delete', 'data consistency', 'smoke', 'pre-push', 'end-to-end CRUD']) {
+    assert(englishMatrix.includes(keyword), `[MATRIX] English matrix missing ${keyword}`);
+  }
+  for (const keyword of ['新增', '查询/列表/详情', '修改', '删除', '数据一致性', '冒烟', 'pre-push', '端到端 CRUD']) {
+    assert(chineseMatrix.includes(keyword), `[MATRIX] Chinese matrix missing ${keyword}`);
+  }
+
+  assert(englishFixture.includes('users') && englishFixture.includes('roles') && englishFixture.includes('files/images') && englishFixture.includes('teardown'), '[FIXTURES] English fixture template must cover users, roles, files/images, and teardown');
+  assert(chineseFixture.includes('用户') && chineseFixture.includes('角色') && chineseFixture.includes('文件/图片') && chineseFixture.includes('清理'), '[FIXTURES] Chinese fixture template must cover users, roles, files/images, and teardown');
+  assert(englishAcceptance.includes('create -> list -> detail -> update -> read back -> delete'), '[ACCEPTANCE] English acceptance template must include full CRUD flow');
+  assert(chineseAcceptance.includes('新增 -> 列表 -> 详情 -> 修改 -> 回读 -> 删除'), '[ACCEPTANCE] Chinese acceptance template must include full CRUD flow');
+
+  assert(englishPlan.includes('CRUD baseline') && englishPlan.includes('test data'), '[PLAN] English plan skill must require CRUD baseline and test data planning');
+  assert(chinesePlan.includes('CRUD 基线') && chinesePlan.includes('测试数据'), '[PLAN] Chinese plan skill must require CRUD baseline and test data planning');
+  assert(englishAuthor.includes('fixtures') && englishAuthor.includes('seed') && englishAuthor.includes('teardown'), '[AUTHOR] English author skill must require fixtures, seed, and teardown assets');
+  assert(chineseAuthor.includes('fixtures') && chineseAuthor.includes('seed') && chineseAuthor.includes('teardown'), '[AUTHOR] Chinese author skill must require fixtures, seed, and teardown assets');
+  assert(englishRun.includes('pre-push') && englishRun.includes('smoke_report') && englishRun.includes('pre_push_report'), '[RUN] English run skill must cover pre-push, smoke_report, and pre_push_report');
+  assert(chineseRun.includes('pre-push') && chineseRun.includes('smoke_report') && chineseRun.includes('pre_push_report'), '[RUN] Chinese run skill must cover pre-push, smoke_report, and pre_push_report');
+  assert(englishVerify.includes('Smoke evidence is required') && englishVerify.includes('pre-push evidence is required') && englishVerify.includes('fixture'), '[VERIFY] English verify skill must gate smoke, pre-push, and fixtures');
+  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 = [
@@ -487,6 +575,8 @@ runManifestPathRelativitySelfCheck();
 assertManifestStructure();
 assertPrepublishGateCoversManifestAssets();
 assertDefaultPytestContracts();
+assertCompleteTestingWorkflowContracts();
+assertProgressiveDisclosureContracts();
 assertOpenTestSearchRootsCoverPlatforms();
 assertLanguageAssetContracts();
 await assertPrepublishRejectsPublishSecretTextFiles();