git.stella-ops.org/docs/policy/lifecycle.md

Policy Lifecycle & Approvals

Audience: Policy authors, reviewers, security approvers, release engineers.
Scope: End-to-end flow for stella-dsl@1 policies from draft through archival, including CLI/Console touch-points, Authority scopes, audit artefacts, and offline considerations.

This guide explains how a policy progresses through Stella Ops, which roles are involved, and the artefacts produced at every step. Pair it with the Policy Engine Overview, DSL reference, and upcoming run documentation to ensure consistent authoring and rollout.

---

1 · Protocol Summary

• Policies are immutable versions attached to a stable policy_id.
• Lifecycle states: draft → submitted → approved → active → archived.
• Every transition requires explicit Authority scopes and produces structured events + storage artefacts (policies, policy_runs, audit log collections).
• Simulation and CI gating happen before approvals can be granted.
• Activation triggers (runs, bundle exports, CLI promote) operate on the latest approved version per tenant.

stateDiagram-v2
    [*] --> Draft
    Draft --> Draft: edit/save (policy:write)
    Draft --> Submitted: submit(reviewers) (policy:submit)
    Submitted --> Draft: requestChanges (policy:write)
    Submitted --> Approved: approve (policy:approve)
    Approved --> Active: activate/run (policy:run)
    Active --> Archived: archive (policy:archive)
    Approved --> Archived: superseded/explicit archive
    Archived --> [*]

---

2 · Roles & Authority Scopes

Role (suggested)	Required scopes	Responsibilities
Policy Author	policy:write, policy:submit, policy:simulate	Draft DSL, run local/CI simulations, submit for review.
Policy Reviewer	policy:review, policy:simulate, policy:runs	Comment on submissions, demand additional simulations, request changes.
Policy Approver	policy:approve, policy:runs, policy:audit	Grant final approval, ensure sign-off evidence captured.
Policy Operator	policy:run, policy:activate, findings:read	Trigger full/incremental runs, monitor results, roll back to previous version.
Policy Auditor	policy:audit, findings:read, policy:history	Review past versions, verify attestations, respond to compliance requests.
Policy Engine Service	effective:write, findings:read	Materialise effective findings during runs; no approval capabilities.

Scopes are issued by Authority (AUTH-POLICY-20-001). Tenants may map organisational roles (e.g., secops.approver) to these scopes via issuer policy.

---

3 · Lifecycle Stages in Detail

3.1 Draft

• Who: Authors (policy:write).
• Tools: Console editor, stella policy edit, policy DSL files.
• Actions:
  • Author DSL leveraging stella-dsl@1.
  • Run stella policy lint and stella policy simulate --sbom <fixtures> locally.
  • Attach rationale metadata (metadata.description, tags).
• Artefacts:
  • policies document with status=draft, version=n, provenance.created_by.
  • Local IR cache (.stella.ir.json) generated by CLI compile.
• Guards:
  • Draft versions never run in production.
  • CI must lint drafts before allowing submission PRs (see DEVOPS-POLICY-20-001).

3.2 Submission

• Who: Authors with policy:submit.
• Tools: Console “Submit for review” button, stella policy submit <policyId> --reviewers ....
• Actions:
  • Provide review notes and required simulations (CLI uploads attachments).
  • Choose reviewer groups; Authority records them in submission metadata.
• Artefacts:
  • Policy document transitions to status=submitted, capturing submitted_by, submitted_at, reviewer list, simulation digest references.
  • Audit event policy.submitted (Authority timeline / Notifier integration).
• Guards:
  • Submission blocked unless latest lint + compile succeed (<24 h freshness).
  • Must reference at least one simulation artefact (CLI enforces via --attach).

3.3 Review (Submitted)

• Who: Reviewers (policy:review), optionally authors responding.
• Tools: Console review pane (line comments, overall verdict), stella policy review.
• Actions:
  • Inspect DSL diff vs previous approved version.
  • Run additional simulate jobs (UI button or CLI).
  • Request changes → policy returns to draft with comment log.
• Artefacts:
  • Comments stored in policy_reviews collection with timestamps, resolved flag.
  • Additional simulation run records appended to submission metadata.
• Guards:
  • Approval cannot proceed until all blocking comments resolved.
  • Required reviewers (Authority rule) must vote before approver sees “Approve” button.

3.4 Approval

• Who: Approvers (policy:approve).
• Tools: Console “Approve”, CLI stella policy approve <id> --version n --note "rationale".
• Actions:
  • Confirm compliance checks (see §6) all green.
  • Provide approval note (mandatory string captured in audit trail).
• Artefacts:
  • Policy status=approved, approved_by, approved_at, approval_note.
  • Audit event policy.approved plus optional Notifier broadcast.
  • Immutable approval record stored in policy_history.
• Guards:
  • Approver cannot be same identity as author (enforced by Authority config).
  • Approver must attest to successful simulation diff review (--attach diff.json).

3.5 Activation & Runs

• Who: Operators (policy:run, policy:activate).
• Tools: Console “Promote to active”, CLI stella policy activate <id> --version n, stella policy run.
• Actions:
  • Mark approved version as tenant’s active policy.
  • Trigger full run or rely on orchestrator for incremental runs.
  • Monitor results via Console dashboards or CLI run logs.
• Artefacts:
  • policy_runs entries with mode=full|incremental, policy_version=n.
  • Effective findings collections updated; explain traces stored.
  • Activation event policy.activated with runId.
• Guards:
  • Activation blocked if previous full run <24 h old failed or is pending.
  • Selection of SBOM/advisory snapshots uses consistent cursors recorded for reproducibility.

3.6 Archival / Rollback

• Who: Approvers or Operators with policy:archive.
• Tools: Console menu, CLI stella policy archive <id> --version n --reason.
• Actions:
  • Retire policies superseded by newer versions or revert to older approved version (stella policy activate <id> --version n-1).
  • Export archived version for audit bundles (Offline Kit integration).
• Artefacts:
  • Policy status=archived, archived_by, archived_at, reason.
  • Audit event policy.archived.
  • Exported DSSE-signed policy pack stored if requested.
• Guards:
  • Archival cannot proceed while runs using that version are in-flight.
  • Rollback requires documented incident reference.

---

4 · Tooling Touchpoints

Stage	Console	CLI	API
Draft	Inline linting, simulation panel	stella policy lint, edit, simulate	POST /policies, PUT /policies/{id}/versions/{v}
Submit	Submit modal (attach simulations)	stella policy submit	POST /policies/{id}/submit
Review	Comment threads, diff viewer	stella policy review --approve/--request-changes	POST /policies/{id}/reviews
Approve	Approve dialog	stella policy approve	POST /policies/{id}/approve
Activate	Promote button, run scheduler	stella policy activate, run, simulate	POST /policies/{id}/run, POST /policies/{id}/activate
Archive	Archive / rollback menu	stella policy archive	POST /policies/{id}/archive

All CLI commands emit structured JSON by default; use --format table for human review.

---

5 · Audit & Observability

• Storage:
  • policies retains all versions with provenance metadata.
  • policy_reviews stores reviewer comments, timestamps, attachments.
  • policy_history summarises transitions (state, actor, note, diff digest).
  • policy_runs retains input cursors and determinism hash per run.
• Events:
  • policy.submitted, policy.review.requested, policy.approved, policy.activated, policy.archived, policy.rollback.
  • Routed to Notifier + Timeline Indexer; offline deployments log to local event store.
• Logs & metrics:
  • Policy Engine logs include policyId, policyVersion, runId, approvalNote.
  • Observability dashboards (see forthcoming /docs/observability/policy.md) highlight pending approvals, run SLA, VEX overrides.
• Reproducibility:
  • Each state transition stores IR checksum and simulation diff digests, enabling offline audit replay.

---

6 · Compliance Gates

Gate	Stage	Enforced by	Requirement
DSL lint	Draft → Submit	CLI/CI	stella policy lint successful within 24 h.
Simulation evidence	Submit	CLI/Console	Attach diff from stella policy simulate covering baseline SBOM set.
Reviewer quorum	Submit → Approve	Authority	Minimum approver/reviewer count configurable per tenant.
Determinism CI	Approve	DevOps job	Twin run diff passes (DEVOPS-POLICY-20-003).
Activation health	Approve → Activate	Policy Engine	Last run status succeeded; orchestrator queue healthy.
Export validation	Archive	Offline Kit	DSSE-signed policy pack generated for long-term retention.

Failure of any gate emits a policy.lifecycle.violation event and blocks transition until resolved.

---

7 · Offline / Air-Gap Considerations

• Offline Kit bundles include:
  • Approved policy packs (.policy.bundle + DSSE signatures).
  • Submission/approval audit logs.
  • Simulation diff JSON for reproducibility.
• Air-gapped sites operate with the same lifecycle:
  • Approvals happen locally; Authority runs in enclave.
  • Rollout requires manual import of policy packs from connected environment via signed bundles.
  • stella policy simulate --sealed ensures no outbound calls; required before approval in sealed mode.

---

8 · Incident Response & Rollback

• Incident mode (triggered via policy incident activate) forces:
  • Immediate incremental run to evaluate mitigation policies.
  • Expanded trace retention for affected runs.
  • Automatic snapshot of currently active policies for evidence locker.
• Rollback path:
  1. stella policy activate <id> --version <previous> with incident note.
  2. Orchestrator schedules full run to ensure findings align.
  3. Archive problematic version with reason referencing incident ticket.
• Post-incident review must confirm new version passes gates before re-activation.

---

9 · CI/CD Integration (Reference)

• Pre-merge: run lint + simulation jobs against golden SBOM fixtures.
• Post-merge (main): compile, compute IR checksum, stage for Offline Kit.
• Nightly: determinism replay, policy simulate diff drift alerts, backlog of pending approvals.
• Notifications: Slack/Email via Notifier when submissions await review > SLA or approvals succeed.

---

10 · Compliance Checklist

• Role mapping validated: Authority issuer config maps organisational roles to required policy:* scopes (per tenant).
• Submission evidence attached: Latest simulation diff and lint artefacts linked to submission.
• Reviewer quorum met: All required reviewers approved or acknowledged; no unresolved blocking comments.
• Approval note logged: Approver justification recorded in audit trail alongside IR checksum.
• Activation guard passed: Latest run status success, orchestrator queue healthy, determinism job green.
• Archive bundles produced: When archiving, DSSE-signed policy pack exported and stored for offline retention.
• Offline parity proven: For sealed deployments, --sealed simulations executed and logged before approval.

---

Last updated: 2025-10-26 (Sprint 20).