prizmkit 1.1.120 → 1.1.122

package/bundled/skills/prizmkit-test/references/test-generation-steps.md

@@ -1,109 +1,117 @@
-# Test Generation Steps (Phase 5)
+# Test Generation and Infrastructure Steps
+
+Use this reference during `INFRA_READY`, `TEST_BUILD`, and `EXECUTE_PROVE`. The authoritative scope and completeness inputs are `scope.json`, `behavior-risk-matrix.json`, and `test-plan.json`.
 
 ## Scope Guard
 
-Before generating any test, determine whether the run is `scope=this-change`.
+For `scope=this-change`, changed files locate the affected module; they do not restrict tests to changed lines. Fill observable behavior/risk gaps across the whole affected module and execute its Regression Ring. Unrelated modules remain out of scope unless they are direct callers, consumers, shared contracts, or state dependencies.
+
+Do not infer current-change scope from a directory name alone. Unknown scope is `TEST_BLOCKED`.
+
+## Native Infrastructure Discovery
+
+Before writing tests:
+
+1. Inspect manifests, lockfiles, existing test files, runner configuration, scripts, fixtures, and CI commands.
+2. Select the existing adequate runner and naming/import/mock conventions.
+3. Let the target project's semantics determine framework, argv, cwd, timeout, attempts, concurrency, Mock tooling, layers, module roots, inventory patterns, and mutation technology; do not import fixed ecosystem defaults from this skill.
+4. If no adequate infrastructure exists, add only the smallest project-native runner/config/dependencies required for the planned layers.
+5. Verify dependency versions against the package registry before writing manifests.
+6. Record every file/dependency/command change and verification in `infrastructure-changes.json`.
+7. Never delete existing tests or add a second framework when the current one is adequate.
+
+Create fixtures, fakes, contract-backed mock servers, browser harnesses, or isolated services only when required by `test-plan.json`. Every disposable resource needs a unique ID, bounded lifetime, and verified cleanup.
+
+## Matrix-First Test Construction
+
+For every behavior row:
+
+1. Read the public interface, contract source, preconditions, inputs/boundaries, outputs, side effects, transitions, and errors.
+2. Inspect existing test assertions—not names—to find proven cells.
+3. Assess all eight risks: functional, boundary, permission, concurrency, idempotency, time, dependency, and consumer.
+4. For every applicable risk, create a distinct test ID and expected execution layer.
+5. For every non-applicable risk, record a concrete rationale tied to this behavior.
+6. Keep unresolved truth or untestable necessary behavior explicit; it blocks rather than becoming guessed expected behavior.
+
+A module is complete when all observable behaviors and applicable risks have mapped, proven tests and the Regression Ring passes. Line/branch/function coverage may reveal an omission and trigger another matrix review, but a percentage cannot complete a cell.
+
+## Risk-Adaptive Layers
+
+Choose only necessary test types, then assess all ordered layers in `test-plan.json`:
+
+- **Unit/focused:** pure behavior, boundaries, errors, deterministic collaborators, and fast defect localization.
+- **Module/component:** public module behavior with internal collaborators composed as production uses them.
+- **Contract:** producer/consumer or adapter compatibility against a shared/snapshotted machine-readable contract.
+- **Integration:** multiple local modules or isolated infrastructure when mocks cannot establish the relevant property.
+- **Code-level E2E:** CLI/UI/API flow through code-level boundaries when user-visible composition is at risk and a native harness is available.
+- **Affected-module regression:** every required test for the complete affected module.
+- **Regression Ring:** direct callers, consumers, shared contracts, and state dependencies.
+
+Do not require every layer mechanically. An omitted layer needs a specific reason such as “pure library has no UI or process boundary; module tests prove its public composition.” “Not tested” is not a rationale.
 
-For `scope=this-change`, use `generation_policy=in-scope-only` by default. Generate tests only for the in-scope source/test set built from the change artifact and changed files. If a missing test is unrelated to the current change, record it in `Out of Scope Gaps` and do not generate it. A change artifact is any directory with `spec.md` and `plan.md`; it may represent a feature, bug fix, refactor, migration, or other scoped change. Do not infer this-change scope from `.prizmkit/bugfix/` or `.prizmkit/refactor/` by directory name alone; require an explicit artifact directory and changed-files source.
+## Contract-Driven Doubles
 
+Read `${SKILL_DIR}/references/contract-mock-protocol.md` for external databases, queues, filesystems, SaaS, browser backends, and cross-module endpoints.
 
-Generate tests from the Phase 4 Boundary Coverage Matrix in priority order: unit → integration → E2E. After each batch, run immediately.
+Prefer shared OpenAPI/schema/types/generated models. Otherwise snapshot a locally derived contract and record derivation source. Generate success, boundary, malformed, timeout, and failure variants from that contract. Reject independently invented fields or a mock that cannot be traced to a snapshot.
 
-When generated tests fail, distinguish two cases:
-- **Test bug** (syntax error, wrong import, wrong mock, wrong framework API usage) → fix the test and re-run
-- **Assertion failure** (test is valid but code returns unexpected result) → mark as "needs review" in report; do NOT modify production code. This is a potential bug discovered by the generated test.
+Code-level evidence is mock-first and always reports `environment_claim=mocked-code-level-only`. Do not connect production or a user-linked deployed test database.
 
-If a test fails repeatedly after 2 fix attempts, skip it and mark as "unresolved" in the report.
+## Whole-Module Legacy Gap Filling
 
-## 5a. Boundary Matrix First
+When a changed module has incomplete tests:
 
-Before writing any new test, create or update the per-interface Boundary Test Matrix from `references/boundary-coverage-protocol.md`. This step matters because a test suite with broad happy-path coverage can still miss the conditions that cause production failures: invalid input, unauthorized access, ownership mistakes, state transitions, dependency errors, and product-specific invariants.
+- enumerate every observable public behavior, not only changed exports;
+- cover valid/minimal/complex inputs and contract-defined boundaries;
+- cover outputs and response shape;
+- assert side effects and absence of partial effects on failure;
+- cover state transitions and idempotency where applicable;
+- cover permissions, concurrency, clocks, external dependency failures, and consumer assumptions where applicable;
+- avoid tests for unrelated private implementation lines.
 
-For each in-scope interface or endpoint:
-- Identify existing happy-path coverage.
-- Identify existing boundary coverage by reading test assertions, not just test names.
-- Classify applicable categories: request validation, auth/permission/ownership, domain invariants, collection/pagination, date/time, state transitions, dependency failure, and response contract.
-- Mark non-applicable categories as `N/A` with a concrete reason.
-- Mark applicable uncovered categories as `boundary-missing`.
+Use `${SKILL_DIR}/references/service-boundary-test-catalog.md` to discover domain-specific risks, then map only contract-supported expectations.
 
-Do not generate only happy-path tests. If happy path is missing, generate it, then continue with applicable boundary tests in the same batch.
+## Testability Seams
 
-### Existing Test Evaluation
+If production code cannot be controlled:
 
-An existing test counts as boundary coverage only when it:
-- targets the same interface/endpoint,
-- sends the relevant boundary input or creates the relevant state/dependency failure,
-- asserts the expected business code, exception, response shape, state change, or side effect,
-- verifies behavior beyond "HTTP 200" or "non-empty response".
+1. Prefer injecting an existing dependency abstraction.
+2. Otherwise extract a pure function, add an internal adapter, or make state/clock/randomness controllable.
+3. Keep the public contract and observable behavior unchanged.
+4. Record the production patch and behavior-preservation evidence.
 
-A test that only checks the route returns successfully is happy-path coverage, not boundary coverage.
+If a public production contract must change, do not proceed autonomously; return `TEST_BLOCKED`.
 
-### API Endpoint Boundary Discovery
+## Valid Failures
 
-For API endpoints, derive boundary cases from:
-- OpenAPI request schemas and response schemas,
-- handler binding tags and request parsing behavior,
-- service validation logic,
-- repository/service error handling,
-- Prizm L2 TRAPS and DECISIONS,
-- existing tests and source behavior,
-- product rules in project brief/specs.
+Distinguish:
 
-Map each endpoint to business-specific cases. Examples:
-- `POST /auth/refresh`: missing token, malformed token, reused/rotated token, revoked token, token-version race if testable.
-- `POST /meals/update`: missing ID, missing foods, invalid meal type, invalid timestamp, not found, wrong owner, recomputed totals, confirmed state transition.
-- `POST /stats/trends`: invalid type, invalid period, invalid date range, empty data, each supported trend type, inclusive end date behavior.
-- `POST /upload/sign-url`: unsupported content type, file_count 0/default/max/max+1, scene handling, storage provider failure.
+- **Test construction defect:** wrong import, syntax, fixture, mock contract, or runner usage. Fix the test/infrastructure within bounded attempts.
+- **Reliable implementation/contract failure:** valid test against resolved truth repeatedly fails. Preserve the failure and return `TEST_FAIL`; do not repair business behavior here.
+- **Uncertain/flaky/unavailable:** truth unresolved, required test unreliable, infrastructure unavailable, or cleanup fails. Return `TEST_BLOCKED`.
 
-## 5b. Unit Tests (always applicable)
+Never retry until green or silently weaken an assertion/scope.
 
-For each in-scope uncovered interface:
-- Read the source file to understand function signature, branch logic, dependencies, state changes, side effects, and failure paths.
-- Classify the function/class method by service responsibility using names, module path, parameters, dependencies, and related Prizm docs/spec acceptance criteria.
-- Read `references/service-boundary-test-catalog.md` when the unit is service-like or has business-specific inputs — it maps service responsibilities to boundary cases such as auth/session, payment/wallet, repository, pagination, file storage, notification, queue, cache/idempotency, API client, and date/expiration behavior.
-- Build a Unit Test Case Matrix before writing tests. Include generic boundaries plus every applicable service-specific boundary; mark non-applicable categories as `N/A` with a short reason instead of silently skipping them.
-- Generate test file matching project conventions (framework, naming, directory, import style, mock/fixture patterns)
-- Common naming patterns to match:
-  - `src/foo.ts` → `src/__tests__/foo.test.ts` or `src/foo.spec.ts` or `tests/foo_test.py`
-  - Mirror the existing pattern; if no tests exist, use the framework's default convention
-- Cover: happy path, service-specific boundary cases, edge cases (null/undefined/empty), error conditions, branch paths, boundary values, state/side effects, and dependency failures.
-- Verify mocks for dependency method calls, call count/order/arguments when the behavior depends on collaborators.
-- Do NOT test framework internals or third-party library behavior
-- Run tests immediately after generating
+## Execution and Differential Proof
 
-## 5c. Integration Tests
+Run selected tests in order through the bundled evidence builder: focused, module/component, contract/integration, affected-module regression, Regression Ring. The model writes schema-shaped requests; the builder performs the process and appends immutable runner-generated receipts to `executions.json`.
 
-For each in-scope module with dependencies:
-- Generate tests for the module's primary interface exercising its real dependencies.
-- If API endpoints exist, generate request/response tests for every applicable boundary category in the Boundary Matrix, not only valid input. Cover auth, missing params, invalid formats/enums, ownership/not-found, state transitions, and response envelope or schema.
-- If database operations exist, generate CRUD tests using the project's existing test database config when available. Cover transactions, duplicate keys, soft-delete visibility, rollback, and query boundary behavior when applicable.
-- If a dependency failure is not practical at integration level, mark it `N/A` with the reason and cover it in a unit test where mocks are available.
-- Run tests immediately after generating.
+For each new/changed necessary behavior test:
 
-## 5d. E2E Tests (conditional)
+1. In an isolated checkout/equivalent, run it against the actual baseline commit and require failure for the intended recorded signal, then current success.
+2. If baseline proof is genuinely inapplicable, apply one model-selected minimal controlled mutation tied to the risk, require failure, restore it, and verify request/receipt, mutation apply/restore, isolation tree, and original project tree hashes.
+3. Record `PROVEN`, structured `NOT_APPLICABLE`, or `UNPROVEN` with runner receipt IDs.
 
-Preconditions (ALL must be met):
-- Playwright is available (`@playwright/test` or `playwright` in package.json dependencies, or `npx playwright --version` succeeds as fallback)
-- Playwright browsers are installed (check `npx playwright install --dry-run 2>/dev/null` exits cleanly, or `node_modules/.cache/ms-playwright/` directory exists; if missing, warn in report and skip E2E)
-- Project has a UI layer
-- Project can be started (start/dev script in package.json)
-- Acceptance criteria exist in spec.md files
+Necessary `UNPROVEN` evidence blocks. Store complete stdout/stderr in `raw/`; snapshots in `generated-tests/`; do not overwrite previous attempts.
 
-If ALL met:
-- **Before starting dev server**: detect whether it's already running: (1) check `package.json` scripts for port flags (`--port`, `-p`, `PORT=`), (2) fall back to framework defaults (3000 for React/Next/Express, 5173 for Vite, 8000 for Django, 5000 for Flask), (3) if still unknown, ask the user. Use the detected port in `lsof -i :<port>` to check. If running, tell user: "Dev server appears to be already running on port {N}. Use this running instance for E2E tests?" If user confirms, use existing instance. If user declines, skip E2E.
-- Start the project dev server (only if not already running). Wait for it to be ready.
-- For each in-scope uncovered acceptance criterion, generate a Playwright test script.
-- Include boundary user journeys when acceptance criteria mention validation, permissions, empty states, error messages, or lifecycle transitions.
-- Run generated E2E tests, capture screenshots of failure.
-- **Only stop dev server if you started it.** Never stop a server that was already running.
+## Completion Check
 
-If NOT met:
-- Note what was skipped and why in the report
-- If only the server wasn't startable: still generate E2E script files but mark as "not run — manual execution needed"
+Before packaging:
 
-## 5e. Boundary Completion Check
-
-After generating and running tests:
-- Update the Boundary Matrix statuses based on passing tests and `needs-review` findings.
-- If any interface remains `boundary-missing` or happy-path-only, run another targeted generation pass for those categories before final reporting.
-- Stop only when all in-scope interfaces are `boundary-covered`, `generated-needs-review`, or `skipped-with-reason`, or when remaining gaps are explicitly listed as unresolved.
+- no applicable matrix cell lacks test/execution mapping;
+- all required planned layers have reliable selected executions in order;
+- affected-module and Regression Ring regressions are complete;
+- every new/changed necessary behavior has valid differential proof;
+- every isolated resource/mutation is cleaned up;
+- no verdict-capable unresolved edge remains for pass;
+- budgeted/staged work is complete, otherwise `TEST_BLOCKED`.

package/bundled/skills/prizmkit-test/references/test-report-template.md

@@ -1,111 +1,90 @@
-# Test Report Output Template
+# Derived Test Evidence Report Template
 
-Used in Phase 6 of `/prizmkit-test`. Create `.prizmkit/test/{YYYY_MM_DD_HH_MM_SS}_testresult/` directory and write `test-report.md`.
-
-## test-report.md Format
+Generate this report solely from the structured, hashed evidence package. It is not independently editable authority. Any change to this file or another linked artifact without manifest regeneration causes deterministic validation failure.
 
 ```markdown
-# Test Report — {timestamp}
+# Test Evidence Report
 
-## Summary
-- Scope: {full / module: name / feature: ###-name / this-change}
-- Architecture: {frontend / backend / fullstack}
-- Test framework: {name}
-- Mode: {interactive / headless}
+Derived from structured evidence. Authoritative package: `{evidence_dir}`
 
-## Scope
-- Mode: {full-project / module:<name> / feature:<slug> / this-change}
-- Artifact Dir: {none / path to change artifact containing spec.md + plan.md}
-- Diff Base: {ref or none}
-- Changed Files Source: {changed_files / diff_base / plan.md / context-snapshot.md / spec.md / not applicable}
-- Generation Policy: {in-scope-only / full-project}
-- In-Scope Source Files:
-  - {...}
-- In-Scope Test Files:
-  - {...}
-
-
-## Existing Tests Run
-- Total: {N} | Passed: {N} | Failed: {N}
-{failed test details or "All passing"}
-{or "No existing tests found — generated first batch"}
-
-## Coverage Gaps Found
-| Module | Interface | Type | Status |
-|--------|-----------|------|--------|
-| ... | ... | unit/integration/e2e | covered / generated / needs-review / unresolved / skipped / boundary-missing |
-
-## Boundary Matrix
-| Module | Interface | Service Type | Happy Path | Request Validation | Auth / Permission / Ownership | Domain Invariants | Collection / Pagination | Date / Time | State Transitions | Dependency Failure | Response Contract | N/A Reasons | Final Status |
-|--------|-----------|--------------|------------|--------------------|-------------------------------|-------------------|-------------------------|-------------|-------------------|-------------------|-------------------|-------------|--------------|
-| ... | ... | auth/repository/upload/etc. | covered/generated/skipped | covered/generated/needs-review/skipped/boundary-missing | ... | ... | ... | ... | ... | ... | ... | category — reason | boundary-covered / generated-needs-review / skipped-with-reason / boundary-missing |
-
-## Boundary Completion Gate
-- Interfaces total: {N}
-- Boundary-covered: {N}
-- Generated-needs-review: {N}
-- Skipped-with-reason: {N}
-- Boundary-missing: {N}
-- Happy-path-only: {N}
-- Completion gate passed: {yes / no}
-
-If `Boundary-missing > 0` or `Happy-path-only > 0`, write:
-`Tests may pass, but boundary coverage is incomplete.`
-
-## Boundary Coverage Notes
-| Module | Interface | Boundary Categories Covered | Missing Applicable Boundaries | N/A Categories with Reasons |
-|--------|-----------|-----------------------------|-------------------------------|-----------------------------|
-| ... | ... | request validation, ownership, dependency failure | invalid timestamp, repo failure | pagination — endpoint has no list semantics |
-
-## Generated / Updated Tests
-- Unit: {N} generated, {N} needs-review, {N} unresolved
-- Integration: {N} generated, {N} needs-review, {N} unresolved
-- E2E: {N} generated, {N} skipped ({reason})
-
-## Boundary Validation
-- Validator command: `{command or "not run — reason"}`
-- Validator result: {passed / failed / skipped}
-- Validator output: {summary or path to raw output}
-
-## In-Scope Failures
-- {failures caused by this-change scope, or "None"}
-
-## Baseline Failures
-- {pre-existing failures, or "None"}
-
-## Out of Scope Gaps
-- {unrelated historical gaps; informational only for scope=this-change}
+## Evidence
+- Evidence ID: {64-character evidence_id}
+- Protocol Version: {protocol_version}
+- Classification: {behavior / lightweight}
+- Baseline Commit: {baseline_commit}
+- Working Diff SHA-256: {working_diff_sha256}
+- Sensitivity: sensitivity=project-controlled
+- Environment Claim: mocked-code-level-only
 
-## Verdict
-PASS | NEEDS_FIXES | BLOCKED
-
-## Final Status
-- All tests passing: {yes / no}
-- Boundary completion gate passed: {yes / no}
-- Ready for commit: {yes / no — include reason}
-- Needs human review: {list of tests/interfaces marked needs-review}
-{remaining failures if any}
-```
+The evidence package preserves complete command, environment, stdout, stderr, patch, hash, and execution-history values without automatic redaction. The project owns access control, retention, and upload policy. Production credentials, production services, and destructive real-data operations are prohibited.
 
-## Artifacts
+Mocked code-level evidence does not verify a real deployed environment.
 
-Also save alongside `test-report.md`:
-- `existing-test-output.txt` — raw output from Phase 2
-- `generated-tests/` — copies of all generated test files
-- `e2e-output/` — E2E logs and failure screenshots (if applicable)
-- `boundary-validation-output.txt` — output from `scripts/validate_boundary_report.py` when run
+## Scope
+- Affected Module: {name} ({explicit / cohesion-derived})
+- Primary Scope: {count and pointers}
+- Regression Ring: {count and pointers}
+- Verdict-capable Unresolved Edges: {count}
+
+## Behavior-Risk Completeness
+- Observable Behaviors: {count}
+- Applicable Risk Cells: {count}
+- Proven/Mapped Risk Cells: {count}
+- Unresolved Risk Cells: {count}
+- Diagnostic Coverage Signals: {values or not collected; never the completion basis}
+- Matrix: `behavior-risk-matrix.json`
+
+## Risk-Adaptive Test Plan
+| Layer | Required | Rationale | Tests | Selected Execution IDs |
+|-------|----------|-----------|-------|------------------------|
+| focused | {yes/no} | {...} | {...} | {...} |
+| module-component | {yes/no} | {...} | {...} | {...} |
+| contract-integration | {yes/no} | {...} | {...} | {...} |
+| affected-module-regression | {yes/no} | {...} | {...} | {...} |
+| regression-ring | {yes/no} | {...} | {...} | {...} |
+
+## Infrastructure and Contracts
+- Native Runner/Conventions: {...}
+- Infrastructure Changes: `infrastructure-changes.json`
+- Contract Snapshots: `contracts/`
+- Production Resources Used: no
+- Cleanup Succeeded: {yes/no}
+
+## Differential Proof
+- PROVEN: {count}
+- NOT_APPLICABLE: {count with rationale pointers}
+- UNPROVEN: {count}
+- Proof Record: `differential-proof.json`
+
+## Executions
+- Attempts Preserved: {count}
+- Selected Required Executions: {IDs in order}
+- Complete History: `executions.json`
+- Raw Outputs: `raw/`
+
+## Deterministic Validation
+- Command: `python3 ${SKILL_DIR}/scripts/validate_test_evidence.py --evidence-dir {evidence_dir} --project-root {target_project_root}`
+- Result: {passed / failed}
+- Validation Record: `validation.json`
 
-## Final Status Rules
+## Verdict
+Verdict: TEST_PASS | TEST_FAIL | TEST_BLOCKED
 
-Use these rules so the report does not overstate quality:
+## Responsibility Boundary
+- Testing-domain verdict only: yes
+- Overall code-quality or broad Spec verdict: no
+- Business defects repaired by this skill: no
+- Commit/release authorized: no
+- Real deployed environment validated: no
 
-| Tests Passing | Boundary Gate | Needs Review | Ready for Commit |
-|---------------|---------------|--------------|------------------|
-| yes | yes | no | yes |
-| yes | yes | yes | no — human review required |
-| yes | no | any | no — boundary coverage incomplete |
-| no | any | any | no — tests failing |
+## Compatibility
+The legacy test-report interface is not supported. Existing Pipeline or other Skill consumers were not migrated and may be temporarily incompatible after installation.
+```
 
-Do not write "All tests passing. Ready for commit." if any interface is `boundary-missing`, `happy-path-only`, `unresolved`, or `needs-review`.
+## Verdict Rendering Rules
 
-Out-of-scope gaps are informational only. They must not trigger generated tests and must not fail a `scope=this-change` run.
+- Render `TEST_PASS` only after deterministic validation passes and all required evidence is proven.
+- Render `TEST_FAIL` only with reliable reproduced failure execution pointers.
+- Render `TEST_BLOCKED` with explicit blocker pointers.
+- Never render `PASS`, `NEEDS_FIXES`, conditional pass, “ready for commit,” or release authorization.
+- A lightweight `TEST_PASS` must say it proves only the deterministic lightweight claim, not runtime behavior.

package/bundled/skills/prizmkit-test/references/trusted-evidence-execution.md

@@ -0,0 +1,97 @@
+# Trusted Evidence Execution
+
+Load this reference before `SCOPE_DISCOVER`, `EXECUTE_PROVE`, resume, or replay. It defines which choices remain with the model and which evidence mechanics are fixed.
+
+## Two Parameter Classes
+
+### Model-Chosen Project Parameters
+
+Inspect the target project and choose these semantically:
+
+- native test framework, runner, command, flags, and working directory;
+- timeout, attempt/retry policy, concurrency, resource limits, and isolation strategy;
+- unit/module/contract/integration/code-level E2E layers;
+- fixture, fake, Mock, service-double, browser, database, and mutation technology;
+- module roots, public behavior boundary, inventory patterns, exclusions, Regression Ring, and differential method;
+- environment classification and endpoint allow/deny evidence.
+
+The protocol does not prescribe Jest, pytest, a timeout number, a retry count, coverage threshold, runner flag, or mutation package. Record the reason for each choice in request and planning records.
+
+### Protocol-Fixed Locators and Mechanisms
+
+The protocol fixes only what trustworthy, replayable packaging needs:
+
+- locator arguments: project root, evidence directory, request/manifest/inventory/receipt path;
+- schema-shaped request records;
+- project-root and evidence-root path confinement;
+- actual child-process execution without a shell;
+- complete stdout/stderr capture and output hashes;
+- complete effective environment and tool-probe capture;
+- runner-generated UUID receipt, request hash, runner hash, and receipt-chain hash;
+- append-only execution history;
+- differential isolation, cleanup, and tree hashes;
+- deterministic resume invalidation calculation;
+- strict schema and cross-record validation.
+
+## Trust Boundary
+
+A receipt proves that the bundled runner produced a record with the captured inputs and outputs during this invocation. The runner snapshots its own executable bytes inside the evidence package so later validation does not silently depend on whichever PrizmKit version happens to be installed. Hashes bind bytes together and detect later drift. They do not create cryptographic non-repudiation and cannot prove that a same-OS-user, same-permission producer did not replace the runner, requests, repository, or evidence package before validation.
+
+Treat evidence as auditable project-controlled provenance, not a defense against a malicious same-privilege actor. The validator checks consistency, obvious conflicts, and replayability; it cannot mathematically prove that the model found every business behavior.
+
+## Builder Commands
+
+Write requests beneath the evidence directory, then invoke the bundled script:
+
+```bash
+python3 ${SKILL_DIR}/scripts/build_test_evidence.py \
+  --project-root <target-project-root> \
+  --evidence-dir <evidence-dir> \
+  inventory --request requests/inventory.json
+
+python3 ${SKILL_DIR}/scripts/build_test_evidence.py \
+  --project-root <target-project-root> \
+  --evidence-dir <evidence-dir> \
+  execute --request requests/focused.json
+
+python3 ${SKILL_DIR}/scripts/build_test_evidence.py \
+  --project-root <target-project-root> \
+  --evidence-dir <evidence-dir> \
+  differential --request requests/differential.json
+
+python3 ${SKILL_DIR}/scripts/build_test_evidence.py \
+  --project-root <target-project-root> \
+  --evidence-dir <evidence-dir> \
+  resume --manifest manifest.json --inventory target-inventory.json
+```
+
+The subcommands cover fixed mechanics only:
+
+- `inventory`: expand model-selected project-relative patterns, independently enumerate all actual files under each declared module root, reject files that are neither categorized nor structurally excluded, hash actual files, and bind discovery inputs;
+- `execute`: run the declared argv in the declared safe cwd and append a runner-generated receipt;
+- `differential`: execute baseline or controlled-mutation proof in isolated copies and verify cleanup/tree binding;
+- `resume`: compare hashes and stage outputs to compute an invalidation decision while retaining `semantic_review_required=true`.
+
+## Replay
+
+Replay a prior receipt through the runner rather than treating attestation as historical proof:
+
+```bash
+python3 ${SKILL_DIR}/scripts/build_test_evidence.py \
+  --project-root <target-project-root> \
+  --evidence-dir <evidence-dir> \
+  execute --replay-receipt receipts/<receipt>.json
+```
+
+The recorded request hash must still match. Replay emits a new receipt linked with `replay_of`; it never overwrites the historical receipt. A replay can still differ because project state, installed tools, clocks, external test services, or environment values changed. Report those differences instead of claiming historical equivalence.
+
+## External Target Safety
+
+Do not block merely because a string contains `production`; names can be misleading. Classify every external target using endpoint/configuration evidence:
+
+- block `production` and `unknown` external targets;
+- permit only model-classified isolated/test/staging targets with explicit allow evidence and no deny evidence;
+- preserve the complete evidence used for the decision;
+- keep local fakes and in-process contract mocks classified `local` with `external=false`.
+
+The model owns the semantic classification; the runner enforces the declared production/unknown safety invariant and rejects contradictory allow/deny records.