git.stella-ops.org/docs/ui/policy-editor.md

Policy Editor Workspace

Audience: Product/UX, UI engineers, policy authors/reviewers using the Console.
Scope: Layout, features, RBAC, a11y, simulation workflow, approvals, run dashboards, and offline considerations for the Policy Engine v2 editor (“Policy Studio”).

The Policy Editor is the primary Console workspace for composing, simulating, and approving stella-dsl@1 policies. It combines Monaco-based editing, diff visualisations, and governance tools so authors and reviewers can collaborate without leaving the browser.

---

1 · Access & Prerequisites

• Routes: /console/policy (list) → /console/policy/:policyId/:version?.
• Scopes / roles:
  • policy:author (role policy-author) to edit drafts, run lint/compile, and execute quick simulations.
  • policy:review (role policy-reviewer) to review drafts, leave comments, and request changes.
  • policy:approve (role policy-approver) to approve or reject submissions.
  • policy:operate (role policy-operator) to trigger batch simulations, promotions, and canary runs.
  • policy:audit (role policy-auditor) to access immutable history and audit exports.
  • policy:simulate to run simulations from Console; findings:read to open explain drawers.
• Feature flags: policyStudio.enabled (defaults true once Policy Engine v2 API available).
• Browser support: Evergreen Chrome, Edge, Firefox, Safari (last two versions). Uses WASM OPA sandbox; ensure COOP/COEP enabled per UI architecture.

---

2 · Workspace Layout

┌────────────────────────────────────────────────────────────────────────────┐
│ Header: Policy selector • tenant switch • last activation banner           │
├────────────────────────────────────────────────────────────────────────────┤
│ Sidebar (left)      │ Main content (right)                                 │
│ - Revision list      │ ┌───────────── Editor tabs ───────────────┐         │
│ - Checklist status   │ │  DSL  │  Simulation  │  Approvals  │ ... │         │
│ - Pending reviews    │ └─────────────────────────────────────────┘         │
│ - Run backlog        │                                                     │
│                      │ Editor pane / Simulation diff / Run viewer          │
└────────────────────────────────────────────────────────────────────────────┘

• Sidebar: Revision timeline (draft, submitted, approved), compliance checklist cards, outstanding review requests, run backlog (incremental queue depth and SLA).
• Editor tabs:
  • DSL (primary Monaco editor)
  • Simulation (pre/post diff charts)
  • Approvals (comments, audit log)
  • Runs (heatmap dashboards)
  • Explain Explorer (optional drawer for findings)
• Right rail: context cards for VEX providers, policy metadata, quick links to CLI/API docs.

Placeholder screenshot: ![Policy editor workspace](../assets/policy-editor/workspace.png) (add after UI team captures latest build).

---

3 · Editing Experience

• Monaco editor configured for stella-dsl@1:
  • Syntax highlighting, IntelliSense for rule/action names, snippets for common patterns.
  • Inline diagnostics sourced from /policies/{id}/lint and /compile.
  • Code actions (“Fix indentation”, “Insert requireVex block”).
  • Mini-map disabled by default to reduce contrast noise; toggle available.
• Keyboard shortcuts (accessible via ?):
  • Ctrl/Cmd + S – Save draft (uploads to API if changed).
  • Ctrl/Cmd + Shift + Enter – Run lint + compile.
  • Ctrl/Cmd + Shift + D – Open diff view vs baseline.
  • Alt + Shift + F – Format document (canonical ordering).
• Schema tooltips: Hover on profile, rule, action to view documentation (sourced from DSL doc).
• Offline warnings: When sealed mode detected, banner reminds authors to validate with offline bundle.

---

4 · Simulation & Diff Panel

• Triggered via “Run simulation” (toolbar) or automatically after compile.
• Displays:
  • Summary cards: total findings added/removed/unchanged; severity up/down counts.
  • Rule hit table: top rules contributing to diffs with percentage change.
  • Component list: virtualised table linking to explain drawer; supports filters (severity, status, VEX outcome).
  • Visualisations: stacked bar chart (severity deltas), sparkline for incremental backlog impact.
• Supports run presets:
  • Golden SBOM set (default)
  • Custom SBOM selection (via multi-select and search)
  • Import sample JSON from CLI (Upload diff).
• Diff export options:
  • Download JSON (same schema as CLI output)
  • Copy as Markdown for review comments
• Simulation results persist per draft version; history accessible via timeline.

---

5 · Review & Approval Workflow

• Commenting: Line-level comments anchored to DSL lines; global comments supported. Uses rich text (Markdown subset) with mention support (@group/sec-reviewers).
• Resolution: Approvers/reviewers can mark comment resolved; history preserved in timeline.
• Approval pane:
  • Checklist (lint, simulation, determinism CI) with status indicators; links to evidence.
  • Reviewer checklist (quorum, blocking comments).
  • Approval button only enabled when checklist satisfied.
• Audit log: Chronological view of submit/review/approve/archive events with actor, timestamp, note, attachments.
• RBAC feedback: When user lacks permission, actions are disabled with tooltip referencing required scope(s).
• Notifications: Integration with Notifier—subscribe/unsubscribe from review reminders within panel.

---

6 · Runs & Observability

• Run tab consumes /policy/runs data:
  • Heatmap of rule hits per run (rows = runs, columns = top rules).
  • VEX override counter, suppressions, quieted findings metrics.
  • Incremental backlog widget (queue depth vs SLA).
  • Export CSV/JSON button.
• Replay/Download: For each run, actions to download sealed replay bundle or open CLI command snippet.
• Alert banners:
  • Determinism mismatch (red)
  • SLA breach (amber)
  • Pending replay (info)

---

7 · Explain & Findings Integration

• Inline “Open in Findings” button for any diff entry; opens side drawer with explain trace (same schema as /findings/*/explain).
• Drawer includes:
  • Rule sequence with badges (block/warn/quiet).
  • VEX evidence and justification codes.
  • Links to advisories (Concelier) and SBOM components.
• Copy-to-clipboard (JSON) and “Share permalink” features (permalinks encode tenant, policy version, component).

---

8 · Accessibility & i18n

• WCAG 2.2 AA:
  • Focus order follows logical workflow; skip link available.
  • All actionable icons paired with text or aria-label.
  • Simulation charts include table equivalents for screen readers.
• Keyboard support:
  • Alt+1/2/3/4 to switch tabs.
  • Shift+? toggles help overlay (with key map).
• Internationalisation:
  • Translations sourced from /locales/{lang}.json.
  • Date/time displayed using user locale via Intl.DateTimeFormat.
• Theming:
  • Light/dark CSS tokens; Monaco theme syncs with overall theme.
  • High-contrast mode toggled via user preferences.

---

9 · Offline & Air-Gap Behaviour

• When console operates in sealed enclave:
  • Editor displays “Sealed mode” banner with import timestamp.
  • Simulation uses cached SBOM/advisory/VEX data only; results flagged accordingly.
  • “Export bundle” button packages draft + simulations for transfer.
• Approvals require local Authority; UI blocks actions if policy:approve scope absent due to offline token limitations.
• Run tab surfaces bundle staleness warnings (policy_runs.inputs.env.sealed=true).

---

10 · Telemetry & Testing Hooks

• User actions (simulate, submit, approve, activate) emit telemetry (ui.policy.action spans) with anonymised metadata.
• Console surfaces correlation IDs for lint/compile errors to ease support triage.
• Cypress/Playwright fixtures available under ui/policy-editor/examples/; docs should note to re-record after significant UI changes.

---

11 · Compliance Checklist

• Lint integration: Editor surfaces diagnostics from API compile endpoint; errors link to DSL documentation.
• Simulation parity: Diff panel mirrors CLI schema; export button tested.
• Workflow RBAC: Buttons enable/disable correctly per scope (policy:write/submit/review/approve).
• A11y verified: Keyboard navigation, focus management, colour contrast (light/dark) pass automated Axe checks.
• Offline safeguards: Sealed-mode banner and bundle export flows present; no network calls trigger in sealed mode.
• Telemetry wired: Action spans and error logs include policyId, version, traceId.
• Docs cross-links: Links to DSL, lifecycle, runs, API, CLI guides validated.
• Screenshot placeholders updated: Replace TODO images with latest UI captures before GA.

---

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