# Promotion Runtime Gap Closure Plan

## Scope

Close the gap between documented Release Orchestrator promotion/environment APIs
and currently implemented runtime controllers.

## Current Runtime Reality

Implemented HTTP controllers:

| Runtime surface | Implemented controller |
| --- | --- |
| Compliance APIs | `src/ReleaseOrchestrator/StellaOps.ReleaseOrchestrator.Api/Controllers/ComplianceController.cs` |
| Rollback intelligence APIs | `src/ReleaseOrchestrator/__Apps/StellaOps.ReleaseOrchestrator.WebApi/Controllers/RollbackIntelligenceController.cs` |

Promotion libraries are implemented and test-covered, but promotion/environment
HTTP controllers are not yet present in these API hosts.

## Gap Inventory (Docs vs Runtime)

| API group | Doc status | Runtime status | Priority |
| --- | --- | --- | --- |
| `/api/v1/environments` | Documented | Missing controller | P0 |
| `/api/v1/promotions` | Documented | Missing controller | P0 |
| `/api/v1/promotions/{id}/decision` | Documented | Missing controller | P0 |
| `/api/v1/promotions/{id}/evidence` | Documented | Missing controller | P1 |
| `/api/v1/approval-policies` | Documented | Missing controller | P1 |

## Delivery Sequence

1. Add Environment API controller surface backed by `IEnvironmentService`.
2. Add Promotion API controller surface backed by `IPromotionManager` and
   decision services.
3. Add decision/evidence endpoints with deterministic response models.
4. Add approval-policy endpoints and SoD enforcement bindings.
5. Add integration tests for end-to-end promotion request -> decision retrieval.

## Acceptance Criteria

- Endpoint group implementation is tracked by API group with owning project path.
- Promotion state transitions match `docs/modules/release-jobengine/workflow/promotion.md`.
- Decision records include policy digest and evidence references.
- Fail-closed behavior is enforced when gate providers error.
- Replay-oriented deterministic assertions are present in tests.

## 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`

## Related Contracts

- 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`