# Platform Release Profile Gates v1

Status: active release contract
Owner: Release Engineering / Platform Ops
Last updated: 2026-06-03
Fairway task: `PSSM-PROD-C9-RELEASE-PROFILE-GATES-001`

## Purpose

Define the environment and release-profile gates required before a
production-impacting shared-service claim or platform-control promotion.

This contract uses the existing release profile resolver, platform evidence
bundle, remote validation phases, and L2 promotion gate. It defines what those
gates must prove per profile.

## Profile Gate Principle

A release profile is not only a pipeline shortcut. It is a contract for:

1. target environment;
2. allowed change classes;
3. required artifacts and digests;
4. required config, DNS, TLS, secrets, registry, schema, and seed posture;
5. required validation phases;
6. rollback or forward-fix posture;
7. evidence required to make a readiness claim.

Fast profiles are allowed only when they ship artifacts that were already
validated against the source SHA by the required global gates.

## Gate Families

| Gate family | Required proof |
|---|---|
| Source and promotion | Source SHA is integrated on `master` or an explicit dev-test divergence is recorded. |
| Contract and codegen | OpenAPI/AsyncAPI bundles, generated Go/TS artifacts, and SDK assets match source. |
| Schema and seed | Migration baseline, seed version, and profile-specific required values are compatible. |
| Artifact and image | Release manifest pins immutable artifacts and runtime images by digest. |
| Registry | Product, scope, usage-unit, evidence-type, artifact-type, policy, and release registry entries required by the change are active or explicitly not applicable. |
| Secrets and PKI | Required secrets, certs, service identity, OIDC clients, and rotation posture are present for the profile. |
| DNS/TLS/edge | Public/internal hosts, ingress, tunnels, cert-manager/edge posture, and redirect/HSTS expectations match the profile. |
| Runtime health | API, web, workers, node-agent, terminal/app routes, queues, and observability are healthy enough for rollout. |
| UAT and security | Required smoke, UAT, security, and residual-risk evidence exists for the change class. |
| Reconciliation | Provider/runtime/billing drift posture is acceptable for the profile. |
| Rollback | Rollback command, manifest, migration posture, and residual-risk owner are explicit. |

## Profile Matrix

| Profile | Use when | Required gates |
|---|---|---|
| `standard` | Normal platform-control deploy from promoted source SHA | all gate families; smoke validation required; lifecycle validation when runtime/app/provisioning/storage changes |
| `web-fast` | Low-risk web-only changes | source, contract/codegen if API assets changed, web artifact digest, runtime config, DNS/TLS, web smoke; must reference prior backend/global validation SHA |
| `api-fast` | Low-risk API/backend-only patch with no schema/runtime infra change | source, contract/codegen, backend tests, API image digest, schema compatibility, API health/authz smoke |
| `runtime-fast` | Bounded runtime/service image change | source, relevant tests, image digest, runtime health, targeted remote validation, rollback |
| `node-agent-fast` | Node-agent/bootstrap-only change | source, node-agent artifact digest, bootstrap metadata, node-agent conformance, rollback |
| `config-only` | Environment config, manifests, edge, Keycloak redirect, deploy/preflight change | existing manifest, profile resolver output, preflight, config diff, smoke; no source/runtime image change |
| `validation-only` | Validation script/assertion change against already deployed manifest | deployed manifest reference, validation phase evidence, no deploy or artifact rebuild |
| `dev-test` | Disposable validation of platform-control-only hardware/runtime behavior | explicit divergence marker, source SHA, bounded owner, follow-up path to merge/promote normally |

## Required Evidence Payload

Every production-impacting release profile must produce or reference:

```yaml
release_profile_evidence:
  source_commit: string
  release_profile: string
  environment_profile: string
  release_manifest_digest: string
  change_class: web | api | runtime | node_agent | config | validation | broad
  validated_against_source_sha: string
  gates:
    - gate_id: string
      result: pass | fail | partial | blocked | missing | not_applicable
      owner: string
      evidence_types:
        - string
      artifact: string
      missing_reason: string
  rollback:
    command: string
    manifest_or_revision: string
    migration_posture: forward_only | reversible | manual_review
    owner: string
```

Missing, failing, or blocked gates cannot be described as a clean promotion.
Partial gates require an approval and residual-risk path.

## Failure Handling

| Failure type | Required operator result |
|---|---|
| Missing profile value | Preflight fails before deploy; profile resolver artifact identifies field. |
| Missing secret/cert | Deploy blocks unless profile explicitly marks it not applicable. |
| Stale registry/seed value | Release gate fails and points to registry/seed owner. |
| Remote validation failure | Evidence identifies phase, principal/project, correlation id, owner, and forward-fix or rollback path. |
| Reconciliation drift | Gate fails or becomes partial based on severity and profile policy. |
| Fast-profile skipped gate | Gate must reference the source SHA and artifact that already passed the skipped global validation. |

## Relationship To Existing Scripts

| Existing script | Role in this contract |
|---|---|
| `platform_control_resolve_release_profile_contract.sh` | Produces redacted profile contract and catches stale profile values. |
| `platform_control_remote_preflight.sh` | Validates target environment before deploy. |
| `platform_control_release_manifest.sh` | Produces immutable release manifest. |
| `platform_control_deploy_from_manifest.sh` | Deploys without rebuilding artifacts. |
| `platform_evidence_payload.sh` | Builds release evidence payload. |
| `platform_evidence_gate.sh` | Evaluates release gates in report or enforce mode. |
| `platform_foundation_l2_promotion_gate.sh` | Blocks PSSM L2 claims unless guards, degradation, and evidence pass. |

## Graduation Rule

Profile gates should graduate in this order:

1. report-only for new gate families while evidence quality is checked;
2. warning for repeated missing evidence or profile drift;
3. blocking for production-impacting shared-service claims and PSSM L2 claims;
4. blocking for normal production promotion once false positives have explicit
   owner/debt records.

Do not allow report-only gates to remain the permanent default for profile
values, secrets, DNS/TLS, migrations, artifact digests, UAT, security, rollback,
or reconciliation evidence.

## Related Docs

- `doc/operations/Platform_Control_CI_CD_Target_Model_v1.md`
- `doc/governance/Platform_Control_Release_Promotion_Policy.md`
- `Platform_Evidence_Status_Slice_v1.md`
- `Platform_Runtime_Reconciliation_Evidence_Model_v1.md`
- `Secrets_PKI_Runtime_Trust_Model_v1.md`