deploy

name	deploy
position	none
description	Deploy a delivered increment (a validated, merged epic) to a named CLOUD environment the run lens already defined — defaulting to the lowest cloud tier (dev), running exactly what that environment's run.yaml declares, then proving it came up healthy with an independent reachability check and recording the deploy as evidence. Lightweight and on-demand: changes nothing in the product model and stops below production (prod stays with CD from main). The /deploy command in the ProductOS command model. Use when a delivered increment needs to run on a cloud environment /run already defined.
user-invocable	true

deploy

Take a delivered increment — a validated epic already merged to main — and deploy it to a named cloud environment, defaulting to the lowest cloud tier defined in the slice's run lens (dev). Run exactly what that environment's run.yaml declares — provider, region, compute, services, networking, and the deploy command — then prove the increment answers with an independent health check, and record the deploy as evidence. /deploy is on-demand and lightweight: it changes nothing in the product model, and it stops below production — production rollout stays with CD from main.

Pipeline position: none (standalone). /deploy acts on an already-delivered increment on main. It opens no issue, cuts no branch, injects no start-change head and no end sequence — it deploys and records evidence. It reads the slice's run.yaml and the repository; it never writes the product model. (#434)

Compiled From

This play was compiled from the deploy ICE (reference/ice.md) by play-editor (#466 Batch B, Level 3 rollout per ADR 025). Intent defines constraints (C1–C10) and failure conditions (F1–F10); the expectation defines success scenarios (S1–S8), a Done means (D1–D3, baked to stop-condition.yaml), and one recovery entry per failure condition. To modify this play, update reference/ice.md and recompile with play-editor. Do NOT edit this file manually — it is a compiled artifact.

(#467) deploy Confirm checkpoint pinned per Kapil's ruling — deploy needs HITL. Standing up a live cloud environment is outward-facing, so the Confirm Deploy checkpoint (Step 1) is now pinned (C10/F10): it always requires a typed human approval and no config value can turn it off.

Role

You are the orchestrator. You own the workflow and step order. You delegate the domain work — standing the increment up on the cloud environment and proving it reachable — to the env-operator agent via a JSON contract over files on disk, and you run the mechanical checks (config + target resolution, the deploy-record assertions, the model snapshot/diff) through bundled scripts. You never run the deploy yourself, you never target production, you never write the product model, and you never call a deploy "done" on the command's exit code — only on the independent health check.

Forbidden: inventing infrastructure the run lens did not declare (C1); targeting production or an out-of-scope tier (C2); deploying undelivered/unmerged code (C3); writing any product-model file (C4); reporting success without a green independent health check (C5); printing/logging/committing a secret (C6); attempting an automatic rollback-and-redeploy on failure (C8); closing COMPLETED without the stop-condition verdict reading held (C9/F9).

Agent boundaries:

Agent	Domain	Skill it invokes	Phases
env-operator	Operate the cloud environment — deploy the increment per the run lens, prove it reachable, capture the deploy record	deploy-to-cloud-env	Deploy

env-operator is the single domain agent this play uses (1 of the ≤5 budget). It is context-isolated to operations — it reads the run lens and the repository, never evals/verdicts/sign-off, and never edits product code or the product model.

Pre-flight

Check	Constraint	Action on Failure
Resolve config + product_base (scripts/preflight.py)	—	Hard halt
Slice resolves and its lens/run.yaml exists	C1	Hard halt (REC8)
Resolve the target cloud env (scripts/resolve_deploy_target.py) — default lowest, or named; refuse prod	C2, C8/F8	Hard halt: production → REC2; no in-scope cloud env → REC8
The increment is delivered — the epic is validated and merged to main	C3	Hard halt (REC3)

Resolve the deterministic pre-flight facts with the bundled resolver:

python3 scripts/preflight.py --play deploy --config .garura/core/config.yaml

Then resolve the target cloud environment from the slice's run lens (default lowest-defined cloud tier, or an explicit --env; production is refused, and a slice with no cloud env halts):

python3 scripts/resolve_deploy_target.py --run-yaml <product_base>/product-os/<domain>/slices/<slice>/lens/run.yaml [--env <name>]

Exit 0 resolves target_env; exit 3 is production-out-of-scope (halt, REC2); exit 4 is no in-scope cloud environment defined (halt, REC8). Then confirm the increment is delivered — the epic's record shows status: delivered (validated and merged to main); if not, halt (REC3). /deploy deploys what is already delivered — it never validates or merges.

The run's working root (<working> below) is {stm_base}_deploy/ — the deploy record (deploy.json), the captured verify output (deploy-checks.json), the logs, the model snapshots, and the status/ markers all live under it; the stop condition evaluates against it.

Right after the resolver, record the session identity stamp's start marker (#463 — soft-fail, never a halt):

python3 scripts/session_stamp.py --phase start \
    --marker "{stm_base}_deploy/status/session-stamp-deploy.json" \
    --cwd "$(pwd)" --branch "$(git branch --show-current)"

Resume check: if {stm_base}_deploy/status/<slice-id>-<env>.json exists, resume — skip completed steps, reset any in-progress step to pending, continue.

Task DAG

Create ALL tasks immediately after pre-flight resolves — before any domain work.

[T1] Confirm Deploy             blockedBy: []
[T2] Deploy the increment       blockedBy: [T1]
[T3] Verify healthy + surgical  blockedBy: [T2]
[T4] Scenario Validation        blockedBy: [T3]
[T5] Close                      blockedBy: [T4]

Mark each task in-progress before its step and completed right after its eval passes.

Workflow

Phase: Confirm

Step 1 — Confirm Deploy (class: one-way-door, pinned) · Owner: play · Depends on: pre-flight Deploying to a live cloud environment is outward-facing — the increment starts answering on real infrastructure. This checkpoint is pinned per standards/rules/gate-config.md: it always fires and always waits for a typed human approval before anything is deployed — no config value, policy, or ledger can disable it (unpinning is an intent change via play-editor, never a config edit). Present the proposed deploy — the slice, the resolved target environment and tier, the delivered increment (epic + merge ref), and what the environment's run.yaml declares will run — and wait for a typed approval. Approve → continue; cancel → halt with nothing deployed.

Phase: Deploy

Step 2 — Deploy the increment · Owner: env-operator · Depends on: Step 1 First snapshot the product model so Step 3 can prove it untouched (cp -R <product_base>/product-os <working>/model-before). Then the agent invokes deploy-to-cloud-env to deploy the delivered increment to the resolved cloud environment exactly as its run.yaml declares, read secrets from the declared manager binding, and prove reachability — writing a deploy record:

{
  "task":    "deploy the delivered increment to the resolved cloud environment per its run.yaml; prove it reachable; never expose secrets; never touch the product model",
  "inputs":  { "run_lens":    "<product_base>/product-os/<domain>/slices/<slice>/lens/run.yaml",
               "environment": "<resolved target env name>",
               "repo_root":   ".",
               "mode":        "up" },
  "outputs": { "deploy_record": "<working>/deploy.json", "logs": "<working>/deploy.log" }
}

The skill executes only what the environment declares, reads secrets from the declared binding (never prints them), runs an independent health check, and — on failure — leaves the environment in its prior state with prior_state_left: true. It never writes the product model.

Phase: Verify

Step 3 — Verify healthy + surgical · Owner: play · Depends on: Step 2 Snapshot the model after (cp -R <product_base>/product-os <working>/model-after) and assert over the captured deploy record — capture the checker's JSON output; its checks.A1 field is the stop condition's D3 input:

python3 scripts/check_deploy.py --deploy-record <working>/deploy.json --run-yaml <product_base>/product-os/<domain>/slices/<slice>/lens/run.yaml --target-env <resolved env> --model-before <working>/model-before --model-after <working>/model-after --logs <working>/deploy.log > <working>/deploy-checks.json

SE-1 (F2/C2): resolve_deploy_target.py refused production / an out-of-scope tier at pre-flight (exit 3) — production is never deployed (REC2). SE-2 (F8/C8): resolve_deploy_target.py halted when no in-scope cloud environment is defined (exit 4) — /deploy never proceeds without a run-lens cloud env (REC8). SE-3 (F3/C3): the increment is delivered — the epic is validated and merged to main — confirmed at pre-flight before any deploy (REC3). SE-4 (F1/C1): check_deploy.py A1 — the deploy record's environment is the resolved target and it ran the environment's declared deploy_cmd; nothing undeclared ran (REC1). SE-5 (F5/C5): check_deploy.py A2 — a succeeded status carries a green independent health check; a command that exited 0 without answering is failed, not done (REC5). SE-6 (F6/C6): check_deploy.py A3 — no secret literal in the record or logs; secrets_source names a secrets-manager binding (REC6). SE-7 (F4/C4): check_deploy.py A4 — the product model is byte-identical before and after; /deploy wrote no model file (REC4). SE-8 (F7/C8): check_deploy.py A5 — a failed deploy left the environment in its prior state (prior_state_left: true); never a half-deploy, never an auto-rollback-redeploy (REC7). SE-9 (C7): the deploy record is a complete evidence record — the target environment, the steps that ran, the reachable address, and the health proof are all captured (Step 5 writes it to the evidence file per the D1 evidence rule). SE-10 (F9/C9): the close is stop-condition gated — check_stop_condition.py over the baked stop-condition.yaml (D1 the deploy record exists; D2 health.status is green; D3 the captured deploy-checks.json reads checks.A1: true) must read held before any COMPLETED close; a failed deploy that recorded its failure honestly closes HALTED, never COMPLETED (REC9). SE-11 (F10/C10): the deploy proceeded only after a typed human approval at the pinned Confirm Deploy checkpoint (Step 1); no deploy ran without it — the gate is pinned and no config value can disable it (REC10). On any GAP, apply the matching recovery before closing.

Phase: Scenario Validation

Step 4 — Scenario evals · Owner: play · Depends on: Step 3

• SCE-1 (S1 — devops engineer, default deploy): with no target named, the resolver picked dev, the declared deploy ran, health is green with an address, an evidence record exists, the model is byte-identical, and the stop-condition verdict reads held.
• SCE-2 (S2 — devops engineer, named higher tier): with target stage, the deploy record's environment is stage, not dev.
• SCE-3 (S3 — release manager, production refused): targeting production halted before any deploy; no production deploy record was written.
• SCE-4 (S4 — security reviewer, no secret leak): no secret literal in the record or logs; the secrets-manager binding is named.
• SCE-5 (S5 — SRE, false green caught): a deploy command that exited 0 without answering was reported failed, gated on the independent health check.
• SCE-6 (S6 — SRE, failed deploy left clean): a failed deploy left the environment in its prior state and reported the failure; no rollback-redeploy was attempted.
• SCE-7 (S7 — product owner, no model write): the product model is byte-identical before and after.
• SCE-8 (S8 — devops engineer, no cloud environment): a slice with no cloud environment defined halted with nothing deployed.

Phase: Evidence & Close

Step 5 — Close · Owner: play · Depends on: Step 4 Run the Standard Play Close. /deploy is a standalone product-scoped play — record evidence per the D1 rule.

# --- Standard Play Close (canonical; see standards/rules/play-close.md) ---
# Path tokens resolved at pre-flight (resolve here if not already):
#   ltm_project_target  = yq '.ltm.project-target' .garura/core/config.yaml
#   evidence_base, slug:
#     project-scoped play : evidence_base="${stm_base}${issue}/evidence/deploy/" ; slug="#${issue}"
#     product-scoped play : evidence_base="${product_base}_evidence/deploy/"      ; slug="${slice_slug}-${env}"
evidence_template=$(cat "${ltm_project_target}standards/templates/evidence-file.md")
delivery_template=$(cat "${ltm_project_target}standards/templates/delivery-report.md")
ts=$(date -u +%Y%m%d-%H%M%S)
evidence_dest="${evidence_base}${ts}.md"
mkdir -p "$(dirname "$evidence_dest")"

# Session identity stamp (#463) — close phase; start phase ran at pre-flight
session_stamp=$(python3 scripts/session_stamp.py --phase close \
    --marker "${stm_base}_deploy/status/session-stamp-deploy.json")
# Stop-condition gate (#464) — Step C0: this play carries a baked manifest, so the
# gate is LIVE. Evaluate the Done means as the close's authoritative input.
python3 scripts/check_stop_condition.py \
    --manifest "<play-dir>/stop-condition.yaml" \
    --base "${stm_base}_deploy/" \
    --out "${stm_base}_deploy/status/stop-condition-deploy.yaml"
sc_exit=$?   # 0 held · 1 unmet · 2 error

/deploy is standalone (no issue branch), so it is product-scoped: evidence_base="${product_base}_evidence/deploy/" and slug="${slice_slug}-${env}".

Step C0 — bind the verdict. sc_exit == 0 (held) permits status: COMPLETED. Anything else closes HALTED with exit_reason: stop_condition_unmet and the evidence's Stop Condition section names every unmet clause — a failed deploy that recorded its failure honestly is a HALTED run, not a done one; fix the state per REC9 (re-run the verify capture, or record the honest failure) and re-evaluate; the close stays HALTED until the verdict reads held. An unevaluable verdict is never a pass.

Step C1 — Write evidence file. Gated by the resolved evidence.record flag. When false, skip and record evidence skipped (record=false). Otherwise fill the evidence-file.md slots (play deploy, run_id deploy-${ts}, slice+env slug, started/completed, status per C0, exit_reason; artifacts: the deploy record, deploy-checks.json, the scrubbed logs, the stop-condition verdict; the resolved target env; step + scenario evals SE-1…SE-11 / SCE-1…SCE-8; the health proof; the checkpoint decision from the pinned Step 1; the session identity stamp fields from $session_stamp (#463): session_id, ledger_file, ledger_start_offset, ledger_end_offset (null when unresolved — never blocks the close); and stop_condition per C0 with the Stop Condition section filled) and write to $evidence_dest. Do NOT hand-author the body. This persists the deploy evidence record (C7, verified by SE-9) to the evidence file, or explicitly skips on record=false.

Step C2 — Render delivery report. Also render the Next line: resolve this play in standards/rules/pipeline-next.md and emit **Next:** /<command> — <why>. Or run /next to see all recommended actions. (only /next pointer, or omit, when the mapped command is null), per play-close.md. Fill the delivery-report.md slots: ## deploy Delivered — ${slug}, the Run Summary table (target env, address, health), the Pipeline Steps table, the Artifacts Produced table (the deploy record + logs), Next Steps (promote to a higher cloud tier by re-running /deploy --env <tier>; production follows from main via CD), and a pointer to $evidence_dest. Always emitted.

# --- end Standard Play Close ---

Scenario Validation

Scenario	Persona	Eval
S1 — default deploy	devops engineer	SCE-1
S2 — named higher tier	devops engineer	SCE-2
S3 — production refused	release manager	SCE-3
S4 — no secret leak	security reviewer	SCE-4
S5 — false green caught	SRE	SCE-5
S6 — failed deploy left clean	SRE	SCE-6
S7 — no model write	product owner	SCE-7
S8 — no cloud environment	devops engineer	SCE-8

Recovery

For	Trigger	Direction	Handoff
F1	/deploy deployed to, or ran, something the run lens does not declare	stop and undo the out-of-scope action; deploy only what the target env's run.yaml declares	autonomous
F2	production or an out-of-scope tier was targeted	halt; production rollout is out of scope — it stays with CD from main	human
F3	the increment is not delivered, merged, or validated	halt; /deploy deploys only a validated, merged increment — route to /validate or /launch first	human
F4	a product-model file changed	revert the write; /deploy executes only and never writes the model	autonomous
F5	success was reported but the increment is not healthy	mark the deploy failed; "done" requires the independent health check to pass	autonomous
F6	a secret value appeared in the logs, the record, or the repo	strip it, read secrets only from the declared secrets-manager binding, and re-verify none remain	autonomous
F7	a failed deploy left the environment half-deployed	report the partial state for a human to resolve; /deploy does not auto-rollback	human
F8	no run lens, or no cloud environment is defined	halt; run /run to define the cloud environment before /deploy	human
F9	the run is about to close COMPLETED with the Done means unmet	close HALTED (stop_condition_unmet) with the unmet clauses named; fix the state — re-run the verify capture, or record the honest failure — and re-evaluate; the close stays HALTED until the verdict reads held	autonomous
F10	a deploy would proceed without the pinned human approval	halt with nothing deployed; present the proposed deploy and wait for the typed approval	human

Pause and Resume

Steps run top to bottom. On entry, resolve config, resolve the target slice + environment, check the status marker, skip completed steps, reset any in-progress step to pending, and continue.

Compilation Metadata

Field	Value
fingerprint	sha256:495ffe2a4d7fb55d8e4b598a24cba7f6586ef9204ed5b3b6f90cc917635cb431 (of reference/ice.md)
compiled_by	play-editor (#466 Batch B; #467 deploy pinned)
pipeline_position	none (standalone; acts on a delivered increment on main; no start/end injection)
model_writes	no (execution only — never writes the product model)
workflow_structure	C (chained: confirm → deploy → verify → close; one pinned one-way-door checkpoint per gate-config.md; stop-condition gated close)
stop_condition	stop-condition.yaml (D1–D3), gate live at Step C0
domain_agents	1 (env-operator)
utility_agents	0
skills_used	deploy-to-cloud-env
scripts	5 (preflight, resolve_deploy_target, check_deploy, check_stop_condition, session_stamp)
step_evals	11 (SE-1…SE-11)
scenario_evals	8 (SCE-1…SCE-8)
recovery_entries	10 (one per failure condition; 5 autonomous / 5 human)