# Target Maturity Evidence Runbook

This runbook turns retained target-environment results into a sanitized,
signed GovOPlaN capability-fit proof. It does not make a deployment suitable,
certified, supported, or production-approved by itself. The proof records what
independent authorities assessed against one exact installed release.

## Roles and custody

Use separate trust domains for release signing, installation receipts,
boundary assessment, and production approval. A private proof key must be
provisioned outside the assessed application and its matching public key must
already exist in a separately managed
`capability-fit-proof-authority-keyring.schema.json` document. Do not store
private keys, raw reports, credentials, personal data, backup material, or
target endpoints in Git.

Each authority key lists only the scopes that role may attest. At least one
supplied signing key must cover every claim, and the issuer rejects a key that:

- is absent, inactive, expired, or revoked in the authority keyring;
- expires before the proof;
- does not match its independently provisioned public key;
- reuses release-catalog or installer-authority key material.

## Target run

Install one pinned catalog release and issue its installed-composition receipt
with `tools/assessments/installer-receipt.py`. Exercise the actual target
topology, including:

- PostgreSQL and Redis as shared state services;
- shared S3-compatible object storage;
- at least two stateless API replicas and the intended worker topology;
- fenced singleton work, ingress, certificates, proxy headers, and the real
  network/trust boundary;
- provider health and freshness for every provider required by the product;
- monitoring, alerting, failure response, accessibility, privacy, and security
  controls;
- backup, isolated restore, failed-deployment rollback, and forward recovery.

For the recovery claim, retain the observed recovery point, measured RPO and
RTO, database/object-store consistency result, and semantic reconstruction of
the institutional and Service/Form reference journeys. Measure RPO from the
last acknowledged durable effect that survives recovery and RTO until service
health plus semantic reconstruction pass. Failed runs are evidence too and
must use a negative result.

The private reports stay in the approved evidence store. Give each report an
opaque artifact ID and each evaluated control a versioned opaque control ID.

## Private claim manifest

Create a private manifest conforming to
`capability-fit-boundary-run.schema.json`. Relative artifact paths resolve from
the manifest directory. Paths are read and hashed by the issuer and are never
copied into the signed output.

```json
{
  "$schema": "./capability-fit-boundary-run.schema.json",
  "schema_version": "0.1.0",
  "evidence_kind": "govoplan.capability-fit-boundary-run",
  "proof_id": "target:production:20260802",
  "expires_at": "2026-09-01T00:00:00Z",
  "claims": [
    {
      "scope": "target_environment",
      "result": "passed",
      "control_ids": ["topology:shared-state-v1"],
      "artifacts": [
        {"artifact_id": "target:run-20260802", "path": "private/target.json"}
      ]
    },
    {
      "scope": "recovery",
      "result": "passed",
      "control_ids": ["recovery:restore-rollback-v1"],
      "artifacts": [
        {"artifact_id": "recovery:run-20260802", "path": "private/recovery.json"}
      ]
    }
  ]
}
```

Reference readiness needs positive `target_environment`, `accessibility`,
`privacy`, `security`, `operations`, and `recovery` claims. Provider acceptance
and production approval are separate scopes. A production-approval authority
must not approve its own unreviewed target run.

## Issue and verify

Issue only while the signed installer observation is current. Repeat
`--signing-key` when multiple independent roles are needed. The command first
verifies the catalog, independent catalog trust root, exact installed payload,
installer receipt, and installer authority. It then hashes artifacts, signs the
sanitized proof, verifies it immediately, and writes both proof and review with
atomic private-file permissions.

```bash
./.venv/bin/python tools/assessments/boundary-evidence.py \
  --assessment /srv/govoplan/assessment.json \
  --catalog /srv/govoplan/catalogs/stable.json \
  --keyring /srv/govoplan/catalogs/keyring.json \
  --trusted-keyring /srv/govoplan/trust/catalog-keyring.json \
  --installed-evidence /srv/govoplan/evidence/installed.json \
  --installer-receipt /srv/govoplan/evidence/installer-receipt.json \
  --installer-authority-keyring /srv/govoplan/trust/installer-authorities.json \
  --claims /srv/govoplan/evidence/private/target-run.json \
  --authority-keyring /srv/govoplan/trust/proof-authorities.json \
  --signing-key authority-target=/run/secrets/target-proof-ed25519.pem \
  --output /srv/govoplan/evidence/target-proof.json \
  --review-output /srv/govoplan/evidence/target-proof-review.json
```

Add `--expected-external-provider-subject provider-production` when the claim
manifest contains `external_providers`. This value is an opaque deployment ID,
not a URL or credential.

## Promotion gate

The general verifier can now be made admission-enforcing. These switches return
a blocking exit status when a required claim is absent, expired, negative,
revoked, or bound to another assessment, release, installation, or subject:

```bash
./.venv/bin/python tools/assessments/capability-fit.py \
  --catalog /srv/govoplan/catalogs/stable.json \
  --keyring /srv/govoplan/catalogs/keyring.json \
  --trusted-keyring /srv/govoplan/trust/catalog-keyring.json \
  --installed-evidence /srv/govoplan/evidence/installed.json \
  --installer-receipt /srv/govoplan/evidence/installer-receipt.json \
  --installer-authority-keyring /srv/govoplan/trust/installer-authorities.json \
  --boundary-evidence /srv/govoplan/evidence/target-proof.json \
  --boundary-authority-keyring /srv/govoplan/trust/proof-authorities.json \
  --require-reference-readiness \
  --require-production-approval \
  --output /srv/govoplan/evidence/admission-review.json
```

Use `--require-external-provider-proof` as well when the promoted product
requires an external provider. Live admission must not use
`--verification-time`; that switch is only for clearly labelled historical
review.

## Renewal and failure

Renew evidence after release, installed composition, deployment, control, or
provider changes and before expiry. Revoke an authority key immediately after
custody loss and rerun the affected assessment with a new independent key.
Never copy a previous positive claim to a new release. Preserve negative and
superseded receipts according to the approved evidence-retention policy.