docs: codify enforcement-strength test authoring standard

Author: Sdvegas21

CONTRIBUTING.md

@@ -8,6 +8,7 @@ Thanks for contributing.
 - Keep ClawZero positioned as an in-path enforcement substrate.
 - Do not reframe the project as attack-simulation-first.
 - Maintain witness schema compatibility.
+- Follow the enforcement-strength test standard in `docs/test-authoring-guide.md`.
 
 ## Development
 
@@ -16,6 +17,8 @@ pytest tests/test_claims.py -v
 python demo/openclaw_attack_demo.py --mode compare --scenario shell
 ```
 
+For test changes, run targeted suites locally and include output in the PR.
+
 ## Pull Requests
 
 Please include:
@@ -24,3 +27,12 @@ Please include:
 - design approach
 - tests and verification output
 - contract/schema impact (if any)
+
+## Test Quality Gate
+
+PRs that add or modify tests must satisfy:
+
+- no weak assertions (existence-only / no-op assertions)
+- explicit enforcement-path assertions (`decision`, `reason_code`, `sink_type`)
+- witness/session assertions where the feature depends on them
+- behavior grounded in actual runtime contracts (not aspirational assumptions)

docs/index.md

@@ -30,4 +30,5 @@ Use the attack demo as **proof of enforcement**, not as the product center.
 ## Operator Docs
 
 - [Integration Quickstarts](integration-quickstarts.md)
+- [Test Authoring Guide](test-authoring-guide.md)
 - [Claims Registry](claims-registry.md)

docs/test-authoring-guide.md

@@ -0,0 +1,72 @@
+# Test Authoring Guide
+
+This is the enforcement-strength standard for all new ClawZero tests.
+
+## Non-Negotiable Standard
+
+Every test must enforce behavior, not just execution.
+
+- No weak assertions like only `is not None`, existence-only checks, or broad `in` checks when exact behavior is known.
+- No tolerance paths that silently accept both `allow` and `block` unless the contract explicitly allows both and each branch has strict assertions.
+- No assumptions about engine behavior. Assertions must match documented runtime contracts and current policy semantics.
+
+## Required Assertions by Path
+
+### Block Path
+
+Use `pytest.raises(ExecutionBlocked)` and assert:
+
+- `decision.decision == "block"`
+- `decision.sink_type == expected_sink`
+- `decision.reason_code == expected_reason` (or documented bounded set only where contract requires)
+
+### Allow / Annotate Path
+
+Assert all of:
+
+- Returned result semantics (exact expected payload/shape when deterministic)
+- Witness sink, decision, and reason code
+- Provenance contract fields when applicable (`taint_level`, markers, source chain)
+
+## Session / Chain Tests
+
+For multi-step/session tests, assert:
+
+- Chain detections include expected pattern(s)
+- Detection evidence references real request IDs from the executed chain
+- Threshold-sensitive behavior is validated against profile thresholds
+- Session report counts and persisted log contents match executed calls
+
+## Witness Assertions
+
+When a test depends on witness artifacts, assert:
+
+- witness exists and is a dict
+- witness request linkage (`request_id`)
+- decision/sink/reason match expected enforcement outcome
+- provenance fields are validated against engine normalization rules
+
+## Generated Test Files
+
+Generated suites are held to the same bar as handwritten suites.
+
+- No exception-assertion no-ops
+- No count-inflation-only assertions
+- Same strict enforcement/result/witness/session checks as non-generated tests
+
+## Review Checklist (PR Gate)
+
+Before merge, reviewers should verify:
+
+- Weak assertion patterns are absent
+- Enforcement path(s) are explicitly required by assertions
+- Reason codes and sinks are validated, not implied
+- Tests are grounded in current contracts, not aspirational behavior
+- Local targeted run and CI are both green
+
+## Useful Contract Anchors
+
+- `tests/policy_matrix_data.py`
+- `tests/test_policy_matrix_generated.py`
+- `tests/runtime/test_engine_parity_contract.py`
+- `tests/test_witness_integrity_matrix.py`

mkdocs.yml

@@ -17,6 +17,7 @@ nav:
   - Policies: policies.md
   - OpenClaw Integration: openclaw-integration.md
   - Integration Quickstarts: integration-quickstarts.md
+  - Test Authoring Guide: test-authoring-guide.md
   - Claims Registry: claims-registry.md
   - Release Checklist: release-checklist.md
   - GitHub Launch Copy: github-profile-copy.md