save checkpoint

docs/modules/release-orchestrator/appendices/promotion-capsule-optional.md

@@ -0,0 +1,56 @@
+# 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.
+
+## Related References
+
+- `src/Policy/StellaOps.Policy.Gateway/Endpoints/ExceptionApprovalEndpoints.cs`
+- `src/Policy/StellaOps.Policy.Gateway/Services/ApprovalWorkflowService.cs`
+- `docs/product/decision-capsules.md`
+- `docs/modules/release-orchestrator/workflow/promotion.md`