Optional Promotion Capsule and `human_decision` Envelope

Status

Optional profile. This appendix must not block baseline promotion delivery.

Promotion Capsule (Optional)

The optional promotion capsule is a DSSE-wrapped bundle containing:

Promotion identity (promotionId, source/target environment, artifact digests)
Policy inputs (policy digest/version, gate input digest)
Evidence references (evidence bundle id, attestation digests, Rekor refs)
Decision output (allow/deny/pending + reason codes)
Signatures and verification metadata

Suggested Envelope Type

Media type: application/vnd.stellaops.promotion-capsule+json
Predicate type: stella.ops/promotionCapsule@v1

Optional `human_decision` DSSE Envelope

For exception paths, the optional envelope captures accountable human override decisions and links them to the promotion record.

Required fields:

decisionId (stable id)
promotionId
requestId (Policy exception approval request id)
actorId
decision (approve|reject|cancel)
reason
ticket
expiresAtUtc (if temporary override)
recordedAtUtc

Binding to Existing Approval Workflows

Policy exception workflow APIs remain source of truth for request lifecycle.
Optional DSSE human_decision envelope references Policy request/audit ids.
Promotion decision records may include humanDecisionEnvelopeId when present.

SLA and Governance Notes

human_decision should be time-bounded and non-default.
Override paths should require explicit scope and reason metadata.
Expired override envelopes must not authorize future promotions.

src/Policy/StellaOps.Policy.Gateway/Endpoints/ExceptionApprovalEndpoints.cs
src/Policy/StellaOps.Policy.Gateway/Services/ApprovalWorkflowService.cs
docs/product/decision-capsules.md
docs/modules/release-jobengine/workflow/promotion.md