up

docs/policy/lifecycle.md

@@ -3,17 +3,19 @@
 > **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.
+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.
+> **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.
 
 ---
 
 ## 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.
+- 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.
 
 ```mermaid
 stateDiagram-v2
@@ -53,7 +55,9 @@ stateDiagram-v2
 - **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.
+  - 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`.
@@ -67,7 +71,8 @@ stateDiagram-v2
 - **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).
+  - 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.
@@ -96,7 +101,8 @@ stateDiagram-v2
 - **Who:** Approvers (`policy:approve`).
 - **Tools:** Console “Approve”, CLI `stella policy approve <id> --version n --note "rationale"`.
 - **Actions:**
-  - Confirm compliance checks (see §6) all green.
+  - 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`.
@@ -190,12 +196,14 @@ All CLI commands emit structured JSON by default; use `--format table` for human
 
 ## 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`). |
+| 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. |
+| **Shadow run** | Submit → Approve | Policy Engine / CI | Shadow mode enabled (`settings.shadow=true`) with findings recorded; must execute once per change. |
+| **Coverage suite** | Submit → Approve | CI (`stella policy test`) | Coverage fixtures present and passing; artefact attached to submission. |
+| **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`). |
 | **Attestation metadata** | Approve → Publish | Authority / CLI | `policy:publish` executed with reason & ticket metadata; DSSE attestation verified. |
 | **Activation health** | Publish/Promote → Activate | Policy Engine | Last run status succeeded; orchestrator queue healthy. |
 | **Export validation** | Archive | Offline Kit | DSSE-signed policy pack generated for long-term retention. |