stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
c568e09a1db4649976d14ce8e18998dc44bebe02
git.stella-ops.org/docs/modules/ui/policy-decisioning-studio/README.md

7.5 KiB
Raw Blame History

Policy Decisioning Studio

Recommendation

Create one dynamic sub-product shell, not one giant page and not three separate sibling products.

  • Canonical mount: /ops/policy
  • Suggested user-facing title: Decisioning Studio
  • Suggested nav label for now: keep Policy to avoid unnecessary IA churn during rollout

This shell should unify the current policy workspace, policy governance, policy simulation, and the actionable parts of VEX conflict resolution into one product surface with deep-linkable tabs and a shared context model.

Why This Is The Right Shape

  • Policy authoring, governance, simulation, VEX overrides, exceptions, and release gates are all parts of one decisioning workflow.
  • Release Orchestrator is a consumer of policy/VEX decisions, not a second owner of those UIs.
  • The current split creates duplicated mental models: packs live in one branch, governance in another, simulation in another, and VEX conflicts off to the side.
  • A single shell allows one shared context header for tenant, pack, environment, artifact digest, and release.
  • Deep-linkable child routes preserve auditability and operator workflows better than a modal-heavy or single-scroll design.

Product Modes

The shell should support three modes without forking the UI into separate apps.

1. Global Mode

  • Used by policy admins and security operators.
  • Focus: pack inventory, governance controls, simulations, trust/VEX posture, gate policy defaults.

2. Pack Mode

  • Used when the user is working on a specific policy pack.
  • Focus: editing, YAML, rule builder, approvals, explain traces, simulation for one pack.

3. Release Context Mode

  • Entered from Release Orchestrator deep links.
  • Context is pinned in the shell header: releaseId, environment, artifactDigest, approvalId, and effective policy bundle.
  • Focus: "why is this promotion blocked / allowed?" rather than general administration.

Recommended IA

Primary tabs

  • Overview
    • decision board for active packs, pending approvals, open conflicts, shadow-mode readiness, and gate health
  • Packs
    • policy pack inventory and pack-scoped workspace
  • Governance
    • risk budgets, trust weights, staleness, sealed mode, profiles, validator, governance audit
  • Simulation
    • shadow mode, console, coverage, effective policy, diff, merge preview, history, batch evaluation
  • VEX & Exceptions
    • VEX conflicts, consensus review, overrides, exception queue, exception detail, rationale capture
  • Release Gates
    • gate catalog, environment-specific gate policy, release-context gate evaluation, promotion readiness
  • Audit
    • immutable policy/VEX decision history, evidence pointers, exports, explain traces

Secondary navigation

  • Use child tabs inside the active primary tab.
  • Use a contextual right rail for evidence, explain traces, or release summary.
  • Never hide critical release-decision screens behind modal-only flows.

Route Contract

Keep /ops/policy as the canonical root and move the product to a single route tree.

Canonical routes

  • /ops/policy
  • /ops/policy/packs
  • /ops/policy/packs/:packId
  • /ops/policy/packs/:packId/edit
  • /ops/policy/packs/:packId/rules
  • /ops/policy/packs/:packId/yaml
  • /ops/policy/packs/:packId/approvals
  • /ops/policy/packs/:packId/explain/:runId
  • /ops/policy/governance/...
  • /ops/policy/simulation/...
  • /ops/policy/vex
  • /ops/policy/vex/conflicts
  • /ops/policy/vex/conflicts/:conflictId
  • /ops/policy/exceptions
  • /ops/policy/exceptions/:exceptionId
  • /ops/policy/gates
  • /ops/policy/gates/environments/:environment
  • /ops/policy/gates/releases/:releaseId
  • /ops/policy/audit

Alias and migration rules

  • Legacy /policy-studio/* routes redirect into /ops/policy/packs/*
  • /admin/policy/governance and /admin/policy/simulation redirect into /ops/policy/governance/* and /ops/policy/simulation/*
  • /admin/vex-hub/* should redirect into /ops/policy/vex/* for mutating and conflict-resolution flows
  • If Analyze keeps a VEX entry point, it should deep-link into the same shell in read-only context instead of owning a separate VEX product

What To Merge

Merge into Packs

  • PolicyWorkspaceComponent
  • PolicyEditorComponent
  • PolicyYamlEditorComponent
  • PolicyRuleBuilderComponent
  • PolicyApprovalsComponent
  • PolicyExplainComponent
  • PolicyDashboardComponent

Merge into Governance

  • PolicyGovernanceComponent shell
  • risk budget, trust weighting, staleness, sealed mode, profiles, validator, audit, conflicts, schema tools

Merge into Simulation

  • SimulationDashboardComponent shell
  • shadow mode, console, lint, coverage, effective policy, audit, diff, promotion, merge preview, history, batch

Merge into VEX & Exceptions

  • VexConflictResolutionComponent
  • preserved ideas from VexConflictStudioComponent
  • exception queue and exception detail flows
  • VEX consensus and trust-weighted decision support

Merge into Release Gates

  • promotion gate surfaces from policy simulation
  • environment gate policy editors
  • release-context verdict page used by Release Orchestrator

Release Orchestrator Integration

Release Orchestrator should link into this shell instead of growing a parallel policy UI.

Entry points from releases

  • approval detail -> open gate verdict in release context mode
  • promotion request -> open readiness checklist in release context mode
  • release detail -> open effective policy + VEX posture for this artifact
  • workflow editor -> deep link to gate catalog / policy pack used by the workflow
  • evidence detail -> deep link to policy and VEX rationale bound to the promotion

Required release-context panel

  • active release / approval identifier
  • environment lane
  • artifact digest / subject digest
  • effective policy pack and version
  • gate verdict summary
  • open conflicts or missing evidence
  • CTA back to release flow

Ownership rule

  • Release Orchestrator owns promotion state and workflow execution
  • Decisioning Studio owns policy authoring, governance, VEX resolution, exceptions, and gate explanation

UI Standards For Implementation

  • One shell component with child router outlets, not duplicated top-level pages
  • Page-owned context and self-serve guidance
  • Stable deep links for every tab and subview
  • Scope-aware tabs that hide or disable only what the operator cannot act on
  • Shared evidence and explain cards reused across policy, VEX, and release contexts
  • Deterministic loading order and route aliases so legacy bookmarks remain functional during rollout

Non-Goals

  • Do not move all security exploration into this shell; read-only security analytics can remain elsewhere if they deep-link into the same canonical decisioning routes when action is required.
  • Do not let Release Orchestrator fork its own policy editor or VEX conflict UI.
  • Do not collapse everything into one scroll page; operators need stable, bookmarkable subviews.

Source Inputs

  • docs/contracts/policy-studio.md
  • docs/security/policy-governance.md
  • docs/modules/release-orchestrator/ui/overview.md
  • docs/modules/release-orchestrator/workflow/evidence-based-release-gates.md
  • docs/modules/ui/component-preservation-map/README.md
  • src/Web/StellaOps.Web/src/app/features/policy-governance/policy-governance.routes.ts
  • src/Web/StellaOps.Web/src/app/features/policy-simulation/policy-simulation.routes.ts
  • src/Web/StellaOps.Web/src/app/features/vex-hub/vex-hub.routes.ts
  • src/Web/StellaOps.Web/src/app/routes/ops.routes.ts
  • src/Web/StellaOps.Web/src/app/routes/administration.routes.ts