d63af51f84
Some checks failed
api-governance / spectral-lint (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
oas-ci / oas-validate (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
52 lines
2.6 KiB
Markdown
52 lines
2.6 KiB
Markdown
# Policy Governance
|
|
|
|
> **Imposed rule:** Publish/Promote actions require reason + ticket metadata and DSSE attestation; two-person approval is recommended and enforced where configured by Authority.
|
|
|
|
This guide defines roles, scopes, approvals, signing, and exception handling for Stella policies.
|
|
|
|
## 1. Roles & scopes
|
|
- Author: `policy:author`, `policy:simulate`
|
|
- Reviewer: `policy:review`, `policy:simulate`
|
|
- Approver: `policy:approve`, `policy:audit`
|
|
- Operator: `policy:operate`, `policy:activate`, `policy:run`
|
|
- Publisher: `policy:publish`, `policy:promote`
|
|
- Auditor: `policy:audit`
|
|
|
|
Authority policy can map org roles to scopes; two-person rule can be enabled per tenant for publish/promote.
|
|
|
|
## 2. Approval workflow
|
|
1) Author drafts with shadow + coverage fixtures; runs lint/simulate/test.
|
|
2) Submit with attachments (lint, simulate, coverage, reason/ticket optional at this stage).
|
|
3) Reviewers comment/resolve; approver checks gates (shadow, coverage, determinism).
|
|
4) Publisher runs `stella policy publish --reason --ticket --sign`; attestation stored and optionally mirrored to Rekor.
|
|
5) Operator activates version; audit events recorded.
|
|
|
|
## 3. Signing & attestation
|
|
- DSSE payload includes IR hash, policyId/version, reason, ticket, approvals, shadow/coverage evidence refs.
|
|
- Rekor mirror when online; offline deployments store bundle + checkpoint for later replay.
|
|
- Evidence Locker stores DSSE + run inputs/outputs for audit.
|
|
|
|
## 4. Exceptions & waivers
|
|
- Use SPL rules with explicit scope and `because` rationale; no perpetual suppressions.
|
|
- Waivers must include expiration and owner; DSSE attested if exported.
|
|
- AOC: Aggregation-Only Contract requires waiver scope to avoid cross-tenant data; UI/CLI enforce tenant scoping.
|
|
|
|
## 5. Compliance checklist
|
|
- [ ] Two-person rule enforced (Authority config) for publish/promote.
|
|
- [ ] Reason and ticket captured on publish; stored in attestation metadata.
|
|
- [ ] Shadow + coverage gates passed and attached.
|
|
- [ ] IR hash recorded; attestation verified before activation.
|
|
- [ ] Waivers have expiry, owner, `because`, and scope.
|
|
- [ ] Offline replay path documented for the policy pack.
|
|
|
|
## 6. Audit & observability
|
|
- Timeline events: `policy.submitted`, `policy.approved`, `policy.published`, `policy.promoted`, `policy.activated`, `policy.archived`.
|
|
- Metrics: `policy_publish_total`, `policy_promote_total`, `policy_attestation_verify_failures`, `policy_shadow_runs_total`.
|
|
- Logs: include `policyId`, `version`, `attestation_ref`, `reason`, `ticket`, `shadow`.
|
|
|
|
## References
|
|
- `docs/policy/overview.md`
|
|
- `docs/policy/lifecycle.md`
|
|
- `docs/policy/spl-v1.md`
|
|
- `docs/policy/runtime.md`
|