Promotion Runtime Gap Closure Plan

Scope

Close the gap between documented Release Orchestrator promotion/environment APIs and current runtime surfaces.

The runtime is no longer limited to compliance and rollback-intelligence controllers. The standalone WebApi owns persisted Release Orchestrator runtime surfaces for environments, targets, agents, releases, approvals, deployment jobs, agent-runtime polling, scripts, and release dashboard snapshots.

The /api/v1/release-orchestrator/releases/{id}/promote and /deploy paths fail closed when release truth is incomplete. Promotion requires ready release state, target environment, verified release evidence, and verified policy-decision evidence. Deploy requires approval quorum, persisted gate result details with all gates passed, and verified release evidence. Deploy creates a pending persisted deployment record and only target execution may advance it to success. The latest VM deployment gate passed 20/20 on 2026-05-09; see docs/qa/agent-targets/e2e-test-runbook.md.

Gap Inventory (Docs vs Runtime)

Capability / API group	Current status	Owner for remaining work
`/api/v1/release-orchestrator/environments` and `/targets`	DONE. Persisted environment/target CRUD, validation, health, freeze windows, and agent assignment exist.	Maintenance only.
`/api/v1/environments/{id}` compatibility reads	DONE for dashboard/detail compatibility through `ReleaseControlV2Endpoints`.	Maintenance only.
Release truth list/detail/create/update/delete/ready/promote/deploy	DONE for the current WebApi adapter path. Release/component/approval/gate/evidence rows are persisted and fail closed when truth is missing.	Library engine full-ctor replacement remains in `SPRINT_20260506_005_ReleaseOrchestrator_library_engine_full_wireup.md`.
`/api/v1/release-orchestrator/approvals` and `/api/v1/approvals/{id}/decision`	DONE. Approval rows persist and decision application is idempotent per actor.	DB-backed approval-policy management remains in Sprint 20260506_006.
Agent registration and runtime polling	PARTIAL. Registration tokens, agent registration/list/read/revoke, mTLS polling endpoints, internal CA-signed client certificates, app-layer client certificate chain validation, Postgres-backed agent/task state, topology-catalog visibility for registered agents, and native target-agent ComposeHost/DockerHost live proof exist.	Compose service bootstrap and no-in-process E2E remain in Sprint 20260506_002.
`/api/v1/promotions` controller consolidation	STILL PLANNED. Current release promote path works through `/api/v1/release-orchestrator/releases/{id}/promote`; the separate promotions controller remains deferred.	Future promotions API consolidation sprint.
`/api/v1/promotions/{id}/evidence`	PARTIAL. Approval/evidence compatibility surfaces exist under `/api/v1/approvals/{id}/evidence` and release evidence endpoints. Dedicated promotions evidence route remains deferred.	Future promotions API consolidation sprint.
`/api/v1/release-orchestrator/approval-policies`	DONE. DB-backed approval-policy CRUD exists with read/manage scopes, audit-emitted mutations, soft-disable deletes, UI editor at `/releases/policies`, and evaluator defaulting to `release_orchestrator.approval_policies`.	Maintenance only; config fallback removal is a future cleanup.
Progressive strategy execution	PARTIAL/DONE for current VM scope. All-at-once, rolling, canary, A/B alias, missing-adapter fail-closed, and rollback evidence are covered by tests and live VM proof; real router/load-balancer data-plane proof is not claimed.	Traffic adapter data-plane sprint after router/load-balancer integration is selected.

Delivery Sequence

DONE: Add environment/target API controller surface backed by persisted release-orchestrator environment stores.
DONE: Add release promote/deploy compatibility runtime backed by release truth, approval rows, gate decisions, and deployment pipeline execution.
DONE: Add decision/evidence compatibility endpoints with deterministic response models for approvals and release evidence.
DONE: Add DB-backed approval-policy endpoints and UI management surface (Sprint 20260506_006).
NEXT: Consolidate dedicated /api/v1/promotions controller surfaces once the library DeployOrchestrator full-ctor path replaces the WebApi adapter.

Acceptance Criteria

DONE: Endpoint group implementation is tracked by API group with owning project path in this document and active sprint files.
PARTIAL: Promotion state transitions match the compatibility release promote path; dedicated /api/v1/promotions consolidation is still deferred.
DONE for current policy evaluator: decision records include policy mode, policy id, reason, required-approval override, and gate/evidence references where available; the default evaluator reads from the DB-backed approval-policy store.
DONE: fail-closed behavior is enforced when gate providers, approval quorum, gate decisions, release evidence, runtime preflight, pull, health, digest, labels, stickers, or traffic adapters fail.
DONE: replay-oriented deterministic assertions exist in Release Orchestrator integration/unit tests and the repeatable live VM Playwright suite.

Test Targets

src/ReleaseOrchestrator/__Tests/StellaOps.ReleaseOrchestrator.Promotion.Tests/
src/ReleaseOrchestrator/__Tests/StellaOps.ReleaseOrchestrator.Environment.Tests/
src/ReleaseOrchestrator/__Tests/StellaOps.ReleaseOrchestrator.Integration.Tests/

Minimum acceptance test mapping:

Policy gate and decision flow: Gate/PolicyGateTests.cs, Decision/DecisionEngineTests.cs
Deterministic gate evaluation ordering: Gate/GateEvaluatorTests.cs
Environment promotion sequencing: Environment.Tests/Services/EnvironmentServiceTests.cs

Policy ownership: docs/modules/policy/promotion-gate-ownership-contract.md
Evidence contract: docs/modules/evidence-locker/promotion-evidence-contract.md
Optional capsule profile: docs/modules/release-jobengine/appendices/promotion-capsule-optional.md