whitehat-security/docs/test-plane.md

# Governed test plane

This is the missing control from the 2026-08-22 cutoff. It is a fail-closed
admission path, not a standing authorization to probe.

## What the plane is

A live E2 run is admitted only when every item below is true:

1. The target is registered in `targets/` with `applicability: applicable`.
2. Known-bad calibration for that target has already failed in-process.
3. The engagement is complete, in window, owner-acknowledged, and not a
   retired ID.
4. `approval_class` matches the registration (`fixture-e2` / `live-e2` /
   `fixture-e3` / `e3` / `fixture-capacity` / `capacity`).
5. The runner namespace is `whitehat`, the image digest is pinned, and
   engagement labels are present. Live E3 also names a `database`. Live
   capacity also names an `aggressor_ceiling`.
6. A value-safe custody **receipt** is supplied to `admit-plane --receipt`.
   The receipt names handles, mount keys, expiry and `secret_values_observed:
   false`. It must not contain token values. Without a receipt, live admission
   fails closed and requests no credential.
7. The kill switch is clear.
8. The rate watcher is attached. Cleanup revokes the lease.

If any item is false, `whitehat admit-plane` exits 2 and no identity is
requested.

## What the plane is not

- Not authorization. Rules of engagement §1 still apply.
- Not a packet. Manifests in `plane/` are a contract for `ops-mason`.
- Not a secret broker. `UnconnectedCustodyBroker` is the default for every
  non-fixture environment and raises before any custody call.
- Not a way to finish tenant-engine E2. That target is `not_applicable`.

## Operator commands

```sh
PYTHONPATH=src python3 -m whitehat_security.cli validate-targets targets
PYTHONPATH=src python3 -m whitehat_security.cli admit-plane engagements/<record>.json targets/<target>.json --receipt <custody-receipt.json>
PYTHONPATH=src python3 -m whitehat_security.cli kill-switch
PYTHONPATH=src python3 -m whitehat_security.cli deliver evidence/<run>.json --outbox outbox
```

Create `plane/KILL` to abort independently of the runner process.

## Retired identifiers

`WH-ENG-20260821-AUDIT-E2`, `WH-ENG-20260821-TENANT-E2`,
`WH-ENG-20260822-AUDIT-E2-01`, `WH-ENG-20260822-AUDIT-E2-02`, and
`WH-ENG-20260822-AUDIT-E2-03` are terminal. `-02` projected and then aborted
with zero packets. `-03` completed as a bounded target pass. A later live E2
run needs a new ID, a new window, WP-0025 receipts, and `admit-plane`
`--receipt --contract --broker-receipt`.