# StellaOps Console - Policies Workspace > **Audience:** Policy Guild, Console UX, product ops, review leads. > **Scope:** Policy workspace navigation, editor surfaces, simulation, approvals, RBAC, observability, offline behaviour, and CLI parity for Sprint 23. The Policies workspace centralises authoring, simulation, review, and promotion for `stella-dsl@1` packs. It builds on the Policy Editor (`docs/ui/policy-editor.md`) and adds list views, governance workflows, and integrations with runs and findings. --- ## 1. Access and prerequisites - **Routes:** - `/console/policies` (list) - `/console/policies/:policyId` (details) - `/console/policies/:policyId/:revision` (editor, approvals, runs) - **Scopes / roles:** - `policy:read` (list and details) - `policy:author` (edit drafts, run lint/compile) - `policy:review`, `policy:approve` (workflow actions) - `policy:operate` (promotions, run orchestration) - `policy:simulate` (run simulations) - `policy:audit` (download audit bundles) - `effective:write` (promotion visibility only; actual write remains server-side) - **Feature flags:** `policy.studio.enabled`, `policy.simulation.diff`, `policy.runCharts.enabled`, `policy.offline.bundleUpload`. - **Dependencies:** Policy Engine v2 APIs (`/policies`, `/policy/runs`, `/policy/simulations`), Policy Studio Monaco assets, Authority fresh-auth flows for critical operations. --- ## 2. List and detail views ### 2.1 Policy list | Column | Description | |--------|-------------| | **Policy** | Human-readable name plus policy ID (e.g., `P-7`). | | **State** | `Active`, `Draft`, `Staged`, `Simulation`, `Archived`. Badge colours align with Policy Engine status. | | **Revision** | Latest revision digest (short SHA). | | **Owner** | Primary maintainer or owning team tag. | | **Last change** | Timestamp and actor of last update (edit, submit, approve). | | **Pending approvals** | Count of outstanding approval requests (with tooltip listing reviewers). | Row actions: `Open`, `Duplicate`, `Export pack`, `Run simulation`, `Compare revisions`. Filters: owning team, state, tag, pending approvals, contains staged changes, last change window, simulation warnings (determinism, failed run). ### 2.2 Policy detail header - Summary cards: current state, digest, active revision, staged revision (if any), simulation status, last production run (timestamp, duration, determinism hash). - Action bar: `Edit draft`, `Run simulation`, `Submit for review`, `Promote`, `Export pack`, `View findings`. --- ## 3. Editor shell The editor view reuses the structure documented in `/docs/ui/policy-editor.md` and adds: - **Context banner** showing tenant, policy ID, revision digest, and simulation badge if editing sandbox copy. - **Lint and compile status** displayed inline with time since last run. - **Checklist sidebar** summarising required steps (lint pass, simulation run, deterministic CI, security review). Each item links to evidence (e.g., latest simulation diff). - **Monaco integration** with policy-specific snippets, schema hover, code actions (`Insert allowlist`, `Add justification`). - **Draft autosave** every 30 seconds with conflict detection (merges disabled; last write wins with warning). --- ## 4. Simulation workflows - Simulation modal accepts SBOM filter (golden set, specific SBOM IDs, tenant-wide) and options for VEX weighting overrides. - Simulations run asynchronously; progress shown in run ticker with status updates. - Diff view summarises totals: affected findings added/removed, severity up/down counts, quieted changes. - Side-by-side diff (Active vs Simulation) accessible directly from policy detail. - Export options: JSON diff, Markdown summary, CLI snippet `stella policy simulate --policy --sbom `. - Simulation results cached per draft revision. Cache invalidates when draft changes or SBOM snapshot updates. - Simulation compliance card requires at least one up-to-date simulation before submission. --- ## 5. Review and approval - **Review requests:** Authors tag reviewers; review sidebar lists pending reviewers, due dates, and escalation contact. - **Comments:** Threaded comments support markdown, mentions, and attachments (redacted before persistence). Comment resolution required before approval. - **Approval checklist:** - Lint/compile success - Simulation fresh (within configured SLA) - Determinism verification passed - Security review (if flagged) - Offline bundle prepared (optional) - **Fresh-auth:** Approve/promote buttons require fresh authentication; modal prompts for credentials and enforces short-lived token (<5 minutes). - **Approval audit:** Approval events recorded with correlation ID, digests, reviewer note, effective date, and optional ticket link. --- ## 6. Promotion and rollout - Promotion dialog summarises staged changes, target tenants, release windows, and run plan (full vs incremental). - Operators can schedule promotion or apply immediately. - Promotion triggers Policy Engine to materialise new revision; console reflects status and shows run progress. - CLI parity: `stella policy promote --policy --revision --run-mode full`. - Rollback guidance accessible from action bar (`Open rollback instructions`) linking to CLI command and documentation. --- ## 7. Runs and observability - Runs tab displays table of recent runs with columns: run ID, type (`full`, `incremental`, `simulation`), duration, determinism hash, findings delta counts, triggered by. - Charts: findings trend, quieted findings trend, rule hit heatmap (top rules vs recent runs). - Clicking a run opens run detail drawer showing inputs (policy digest, SBOM batch hash, advisory snapshot hash), output summary, and explain bundle download. - Error runs display red badge; detail drawer includes correlation ID and link to Policy Engine logs. - SSE updates stream run status changes to keep UI real-time. --- ## 8. RBAC and governance | Role | Scopes | Capabilities | |------|--------|--------------| | **Author** | `policy:read`, `policy:author`, `policy:simulate` | Create drafts, run lint/simulations, comment. | | **Reviewer** | `policy:read`, `policy:review`, `policy:simulate` | Leave review comments, request changes. | | **Approver** | `policy:read`, `policy:approve`, `policy:operate`, `policy:simulate` | Approve/promote, trigger runs, view run history. | | **Operator** | `policy:read`, `policy:operate`, `policy:simulate`, `effective:write` | Schedule promotions, monitor runs (no editing). | | **Auditor** | `policy:read`, `policy:audit`, `policy:simulate` | View immutable history, export audit bundles. | | **Admin** | Above plus Authority admin scopes | Manage roles, configure escalation chains. | UI disables controls not allowed by current scope and surfaces tooltip with required scope names. Audit log captures denied attempts (`policy.ui.action_denied`). --- ## 9. Exports and offline bundles - `Export pack` button downloads policy pack (zip) with metadata, digest manifest, and README. - Offline bundle uploader allows importing reviewed packs; UI verifies signatures and digests before applying. - Explain bundle export collects latest run explain traces for audit. - CLI parity: - `stella policy export --policy --revision ` - `stella policy bundle import --file ` - `stella policy bundle export --policy --revision ` - Offline mode displays banner and disables direct promotion; provides script instructions for offline runner. --- ## 10. Observability and alerts - Metrics cards show `policy_run_seconds`, `policy_rules_fired_total`, `policy_determinism_failures_total`. - Alert banners surfaced for determinism failures, simulation stale warnings, approval SLA breaches. - Links to dashboards (Grafana) pre-filtered with policy ID. - Telemetry panel lists last emitted events (policy.promoted, policy.simulation.completed). --- ## 11. Offline and air-gap considerations - In sealed mode, editor warns about cached enrichment data; simulation run button adds tooltip explaining degraded evidence. - Promotions queue and require manual CLI execution on authorised host; UI provides downloadable job manifest. - Run charts switch to snapshot data; SSE streams disabled, replaced by manual refresh button. - Export/download buttons label file paths for removable media transfer. --- ## 12. Screenshot coordination - Placeholders: - `![Policy list placeholder](../assets/ui/policies/list-placeholder.png)` - `![Policy approval placeholder](../assets/ui/policies/approval-placeholder.png)` - `![Simulation diff placeholder](../assets/ui/policies/simulation-placeholder.png)` - Coordinate with Console Guild via `#console-screenshots` (entry 2025-10-26) to replace placeholders once UI captures are ready (light and dark themes). --- ## 13. References - `/docs/ui/policy-editor.md` - detailed editor mechanics. - `/docs/ui/findings.md` - downstream findings view and explain drawer. - `/docs/policy/overview.md` and `/docs/policy/runs.md` - Policy Engine contracts. - `/docs/security/authority-scopes.md` - scope definitions. - `/docs/cli/policy.md` - CLI commands for policy management. - `/docs/ui/console-overview.md` - navigation shell and filters. --- ## 14. Compliance checklist - [ ] Policy list and detail workflow documented (columns, filters, actions). - [ ] Editor shell extends Policy Studio guidance with checklists and lint/simulation integration. - [ ] Simulation flow, diff presentation, and CLI parity captured. - [ ] Review, approval, and promotion workflows detailed with scope gating. - [ ] Runs dashboard, metrics, and SSE behaviour described. - [ ] Exports and offline bundle handling included. - [ ] Offline/air-gap behaviour and screenshot coordination recorded. - [ ] References validated. --- *Last updated: 2025-10-26 (Sprint 23).*