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.

Imposed rule: New or significantly changed policies must run in shadow mode with coverage fixtures before activation. Promotions are blocked until shadow + coverage gates pass.

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 System Overview, the DSL reference, and the Policy Runs guide 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.
• Shadow mode runs capture findings without enforcement; shadow exit requires coverage + twin-run determinism checks.

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

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.
  • Run stella policy lint and stella policy simulate --sbom <fixtures> locally.
  • Add/refresh coverage fixtures under tests/policy/<policyId>/cases/*.json; run stella policy test.
  • Keep settings.shadow = true until coverage + shadow gates pass.
  • 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).
  • Attach coverage results (shadow mode + stella policy test).
  • 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.
  • Verify shadow gate + coverage suite passed in CI.
  • 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 Signing & Publication

• Who: Operators with fresh-auth (policy:publish, policy:promote) and approval backing.
• Tools: Console “Publish & Sign” wizard, CLI stella policy publish, stella policy promote.
• Actions:
  • Execute stella policy publish <id> --version n --reason "<why>" --ticket SEC-123 --sign to produce a DSSE attestation capturing IR digest + approval metadata.
  • Provide required metadata headers (policy_reason, policy_ticket, policy_digest), enforced by Authority; CLI flags map to headers automatically.
  • Promote the signed version to targeted environments (stella policy promote <id> --version n --environment stage).
• Artefacts:
  • DSSE payload stored in policy_attestations, containing SHA-256 digest, signer, reason, ticket, promoted environment.
  • Audit events policy.published, policy.promoted including metadata snapshot and attestation reference.
• Guards:
  • Publish requires a fresh-auth window (<5 minutes) and interactive identity (client-credentials tokens are rejected).
  • Metadata headers must be present; missing values return policy_attestation_metadata_missing.
  • Signing key rotation enforced via Authority JWKS; CLI refuses to publish if attestation verification fails.

3.6 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.7 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

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

4.1 · CLI Command Reference

stella policy edit <file>

Open a policy DSL file in your configured editor ($EDITOR or $VISUAL), validate after editing, and optionally commit with SemVer metadata.

Options:

• -c, --commit - Commit changes after successful validation
• -V, --version <semver> - SemVer version for commit metadata (e.g., 1.2.0)
• -m, --message <msg> - Custom commit message (auto-generated if not provided)
• --no-validate - Skip validation after editing (not recommended)

Example:

# Edit and commit with version metadata
stella policy edit policies/my-policy.dsl --commit --version 1.2.0

stella policy test <file>

Run coverage test fixtures against a policy DSL file to validate rule behavior.

Options:

• -d, --fixtures <dir> - Path to fixtures directory (defaults to tests/policy/<policy-name>/cases)
• --filter <pattern> - Run only fixtures matching this pattern
• -f, --format <fmt> - Output format: table (default) or json
• -o, --output <file> - Write test results to a file
• --fail-fast - Stop on first test failure

Example:

stella policy test policies/vuln-policy.dsl --filter critical

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 the Policy telemetry guide) highlight pending approvals, run SLA, and VEX overrides.
• Reproducibility:
  • Each state transition stores IR checksum and simulation diff digests, enabling offline audit replay.

6 · Compliance Gates

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.
• [ ] Publish attestation signed: stella policy publish executed by interactive operator, metadata (policy_reason, policy_ticket, policy_digest) present, DSSE attestation stored.
• [ ] Promotion recorded: Target environment promoted via CLI/Console with audit event linking to attestation.
• [ ] 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-11-27 (Sprint 401).