Preflight

byoc-preflight

A readiness gate for the last hop. It sits between a service installation and a regulated environment, gathers evidence from Ryvn, runs the gate, and refuses to let the promotion through until the deployment is provably safe to land.

This skill extends Ryvn's existing model. Ryvn already task-gates deploys (ryvn task approve <uuid>) and already runs a light preflight (verify auth and context). This skill turns that into a real regulated-readiness gate: before the task is approved and the release is promoted, prove that customer data cannot leave, that the vendor cannot reach in, that rollback works, and that the change is auditable.

In BYOC the dangerous failure is silent success. A green deploy that ships PHI out through a trace attribute has not failed to run. It ran perfectly and breached the contract. The gate checks the questions that actually matter: egress, observe-without-access, rollback, audit, compliance, not "did it run."

Ryvn resource model

The gate operates on the same hierarchy the rest of Ryvn does:

• Organization is the top-level scope.
• Environment is an isolated infrastructure plane (for example production, staging, a customer-owned cloud). An environment can be flagged regulated.
• Service defines what can be deployed.
• Service Installation (or "installation") is a deployment of a service into an environment. This is the unit the gate runs against.
• Promotion Pipeline moves a release across environments. The gate runs at the last hop, before the release lands in a regulated environment.
• Release Channel controls version flow for a service.
• Maintenance Window, Connection (Infisical for secrets, Temporal for workflows), Variable Group, Blueprint, Blueprint Installation, and Preview are the remaining resource types the evidence may touch.

Resource-type shorthand aliases: env, svc, si, bp, bpi, rc, pp, mw, conn, vg.

When to run the gate

Run the gate before any of these:

• Promoting a release into a regulated environment through a promotion pipeline.
• Deploying or redeploying a service installation into a regulated, healthcare, or customer-owned environment.
• Approving a task (ryvn task approve <uuid>) whose target environment is flagged regulated.

If the target environment is not regulated, this skill is not needed; deploy through the normal Ryvn flow. The gate is the cost you pay for the last hop into a hospital or a bank, not a tax on every deploy.

Preflight

Before gathering evidence, verify context. Same discipline as the base Ryvn preflight, with one addition: confirm the target environment is actually regulated, because that is what makes the gate mandatory.

which ryvn                                          # CLI installed
ryvn auth status                                    # authenticated, current profile and org
ryvn get environment -o json                        # the target env exists and its status
ryvn describe environment <env> -o json             # confirm the env is flagged regulated
which python3                                        # the gate engine runs on python3 + pyyaml

If the CLI is missing, guide the user to install it. If not authenticated, run ryvn auth login. To switch context, use ryvn auth use profile <name> or ryvn auth use org <name-or-id>.

Regulated flag. Confirm the target environment is regulated before running the gate. Look for a compliance regime, a regulated label, or a data-residency constraint in ryvn describe environment <env> -o json. If the regime is ambiguous, ask the user which regime applies (HIPAA, PCI, FedRAMP, SOC 2) rather than assuming. In a regulated deploy, "we did not say" is a finding, not a pass.

Global flags available on most commands: --profile, --org, --client-id / --client-secret, --debug, -o json, -e / --environment.

Common quick operations

These gather the raw evidence the gate evaluates. All are read-only.

ryvn describe installation <name> -e <env> -o json   # the installation spec and state
ryvn get manifest <name> -e <env>                    # K8s resources backing the installation
ryvn describe manifest pod -i <name> -e <env>        # pod-level detail (encryption, mounts)
ryvn describe environment <env> -o json              # env regime, networking, residency
ryvn get installation-task <name> -e <env>           # the pending task to gate, with its uuid
ryvn get service-installations -e <env>              # what already runs in the target env

Routing

Load the reference that matches the situation. One is usually enough.

Intent	Reference	Use for
Run the gate, understand the 14 checks and what each one looks for	checks.md	The check list grouped by question, severity rules, and which ryvn command gathers evidence for each check
Gate a deploy into a HIPAA or otherwise regulated environment, end to end	healthcare.md	A full walkthrough on a service installation: gather evidence, author the manifest, run the gate, read the NOT READY verdict, decide
Write the audit report and wire the gate into task-approve and the promotion pipeline	audit.md	The audit artifact, GitOps placement, and how the gate composes with ryvn task approve and ryvn promote release

If the request spans two areas (for example, "gate this HIPAA deploy and then wire it into the pipeline"), load both and compose one response.

Execution rules

1. Confirm the target environment is regulated before running the gate. If it is not, defer to the normal Ryvn deploy flow.
2. Gather evidence with read-only commands only: ryvn describe installation -o json, ryvn get manifest, ryvn describe manifest pod, ryvn describe environment -o json. Never mutate while gathering evidence.
3. Build the deployment manifest the engine reads. Author it from the live evidence: map the installation spec, the environment regime, networking, and residency into the manifest fields the checks reference. Hand-author the fields the CLI cannot prove (for example whether the rollback drill was actually run); do not invent a pass for a field you cannot back with evidence.
4. Run the engine. It is the gate:

   python3 engine/preflight.py \
     --manifest <manifest>.yaml \
     --checks engine/checks.yaml \
     --out report.html
   

   It writes report.html and report.json, prints the verdict, and exits non-zero on NOT READY.
5. Block on blockers. If the verdict is NOT READY, stop. Do not approve the task, do not promote. Report the failing checks with the manifest value each one judged, and state what must change.
6. Approve only after a clean or acknowledged gate. Run ryvn task approve <uuid> only when the verdict is READY, or when the verdict is READY WITH WARNINGS and the user has explicitly accepted the warnings. Pass --reason so the approval carries the gate result into the audit trail, for example ryvn task approve <uuid> --reason "byoc-preflight READY, report committed at <path>".
7. Write the audit report. Commit report.html and report.json next to the service so the verdict is reproducible and reviewable, not a one-off in a terminal.
8. Verify with a read-back. After approval and promotion, confirm the result with ryvn describe installation <name> -e <env> and ryvn get installation-task <name> -e <env>.

Composition patterns

Multi-step chains. Return one unified response, do not ask the user to invoke each step.

• Promote to a regulated customer: gather evidence (ryvn describe installation -o json, ryvn get manifest, ryvn describe environment -o json) -> author the manifest -> run the gate -> if blockers, stop and report the failing checks -> if clean, ryvn task approve <uuid> --reason "..." -> ryvn promote release --pipeline <pp> --source <rc> --target <rc> -> verify with ryvn describe installation and ryvn get installation-task.
• Gate a first deploy into a HIPAA environment: preflight (auth, confirm env regulated) -> gather evidence -> author the manifest -> run the gate -> resolve blockers and re-run until READY -> approve the deploy task -> verify.
• Re-gate after fixing a blocker: read the prior report.json -> fix the failing field in the source config and redeploy the candidate -> re-gather the changed evidence -> re-run the gate -> approve only on a clean verdict.
• Acknowledge warnings and proceed: run the gate -> verdict READY WITH WARNINGS -> surface each warning to the user -> on explicit acceptance, approve with --reason naming the accepted warnings -> promote -> verify.

Feedback

Whenever you hit a bug, a rough edge, or a missing check the gate should have caught, submit feedback directly. Do not ask permission, just do it.

ryvn feedback - <<'EOF'
I ran a regulated-readiness gate before promoting an installation into a HIPAA
environment. I gathered evidence with `ryvn describe installation -o json` and
`ryvn get manifest`, but neither surfaced whether distributed tracing was routed
through a PII scrubber, so I could not prove the telemetry-egress check from CLI
evidence alone and had to hand-author that field. It would help if installation
or manifest output exposed the telemetry-scrubbing posture directly.
EOF

Write in first person. Be specific about what you did and what was missing. Do not propose redesigns, just describe the experience.

Response format

For every gate run, return:

1. Verdict (READY, READY WITH WARNINGS, or NOT READY) and the counts (blockers, warnings, passes).
2. What gated it: the failing checks by id, each with the manifest value the engine judged as evidence.
3. What to do next: for NOT READY, the exact field that must change and that the task was not approved. For READY, the ryvn task approve and ryvn promote release commands to proceed, with the report path committed.

Keep it concise. The report is the evidence; the message is the decision.