# 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](overview.md), [DSL reference](dsl.md), 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.

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

---

## 2 · Roles & Authority Scopes

| Role (suggested) | Required scopes | Responsibilities |
|------------------|-----------------|------------------|
| **Policy Author** | `policy:author`, `policy:simulate`, `findings:read` | Draft DSL, run local/CI simulations, submit for review. |
| **Policy Reviewer** | `policy:review`, `policy:simulate`, `findings:read` | Comment on submissions, demand additional simulations, request changes. |
| **Policy Approver** | `policy:approve`, `policy:audit`, `findings:read` | Grant final approval, ensure sign-off evidence captured. |
| **Policy Operator** | `policy:operate`, `policy:run`, `policy:activate`, `findings:read` | Trigger full/incremental runs, monitor results, roll back to previous version. |
| **Policy Auditor** | `policy:audit`, `findings:read` | 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:author`).
- **Tools:** Console editor, `stella policy edit`, policy DSL files.
- **Actions:**
  - Author DSL leveraging [stella-dsl@1](dsl.md).
  - 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 (`policy:author`).
- **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:operate`, `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).*