stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

Update module architecture docs and workflow tutorials

Browse Source 
- Module dossiers: attestor, authority, cli, graph, scanner
- Policy assistant parameters guide
- UI v2-rewire navigation rendering policy
- Test suite overview update
- Workflow engine requirements and tutorial series (01-08)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
master
2026-03-30 17:25:37 +03:00
parent 5722d36c0e
commit a6ffb38ecf
17 changed files with 4442 additions and 4380 deletions
Download Patch File Download Diff File Expand all files Collapse all files

176
docs/modules/ui/v2-rewire/S00_nav_rendering_policy.md
View File

@@ -1,81 +1,143 @@
# S00 Nav Rendering Policy
Status: Frozen
Date: 2026-02-18
Date: 2026-03-29
Working directory: `docs/modules/ui/v2-rewire`
Sprint: `20260218_005`, task `R0-03`
Sprint: `20260218_005`, task `R0-03` (updated 2026-03-29 for 6-group restructure)
## Policy statement
Release Control-owned capabilities may be rendered as direct shortcuts in the sidebar if and only if:
1. Ownership is labeled as **Release Control** in breadcrumbs and page headers.
2. The canonical routes for those capabilities live under `/release-control/*`.
Capabilities may be rendered as direct shortcuts in the sidebar if and only if:
1. Ownership is labeled with the correct **group name** in breadcrumbs and page headers.
2. The canonical routes for those capabilities live under the group's route prefix.
3. The sidebar shortcut links to the canonical route, not an alias.
This policy prevents mixed rendering where the same screen appears to be owned by two domains.
## Canonical sidebar groups (6 groups)
The sidebar is organized into exactly 6 menu groups identified by `menuGroupId`:
| # | menuGroupId | Rendered label | Purpose |
|---|-------------|----------------|---------|
| 1 | `home` | *(none)* | Dashboard entry point |
| 2 | `release-control` | Release Control | Deployments, Releases, Environments, Readiness |
| 3 | `security` | Security | Vulnerabilities, Posture, Scan, VEX & Exceptions, Risk & Governance (incl. Simulation, Audit) |
| 4 | `evidence` | Evidence | Evidence Overview, Decision Capsules, Audit Log, Export Center |
| 5 | `operations` | Operations | Operations Hub, Policy Packs, Scheduled Jobs, Feeds & Airgap, Agent Fleet, Signals, Scripts, Diagnostics |
| 6 | `setup-admin` | Settings | Integrations, Identity & Access, Certificates & Trust, Theme & Branding, User Preferences |
### Policy dissolution
The former `policy` group was dissolved in the 7-to-6 restructure. Policy is a toolset, not a persona -- its items were distributed by audience:
- **Security** absorbed: VEX & Exceptions, Risk & Governance (including Simulation and Policy Audit). These are consumed by security practitioners during triage and risk assessment.
- **Operations** absorbed: Policy Packs. Pack authoring and management is an operational/admin workflow.
There is no standalone "Policy" group in the sidebar. The `/ops/policy/*` route prefix is retained for backward compatibility but items are surfaced under their new parent groups.
### New items surfaced (2026-03-29)
- **Readiness** (`/releases/readiness`) -- added to Release Control. Surfaces gate status and release readiness checks before promotion.
- **Findings Explorer** (`/security/findings`) -- added as a child of Security Posture. Provides a filterable view of all security findings across the fleet.
### Items removed from direct navigation
The following items are no longer direct sidebar entries but remain routable for deep links and contextual navigation:
- Runtime Drift, Notifications, Watchlist -- accessible from Operations Hub landing page
- Replay & Verify, Bundles, Trust -- accessible from Evidence Overview and Decision Capsules detail
## Allowed rendering model
### Desktop (expanded sidebar)
```
Dashboard
[Home]
Dashboard
Release Control
├── Releases [shortcut direct nav allowed]
├── Approvals [shortcut direct nav allowed]
├── Bundles [nested only — no direct shortcut]
├── Deployments [nested only — no direct shortcut]
└── Regions & Environments [nested only — no direct shortcut]
Security & Risk
Evidence & Audit
Integrations
Platform Ops
Administration
Deployments [badge: failed runs + pending approvals]
Releases [badge: blocked gates]
Environments
Readiness
Security
Vulnerabilities [badge: critical findings]
Security Posture [sparkline: security trend]
Supply-Chain Data
Findings Explorer
Reachability
Unknowns
Scan Image
VEX & Exceptions
Risk & Governance
Simulation
Policy Audit
Evidence
Evidence Overview
Decision Capsules
Audit Log
Export Center
Operations
Operations Hub [sparkline: platform trend]
Policy Packs
Scheduled Jobs
Feeds & Airgap
Agent Fleet
Signals
Scripts
Diagnostics
Settings
Integrations
Identity & Access
Certificates & Trust
Theme & Branding
User Preferences
```
`Releases` and `Approvals` may appear as direct children under `Release Control` in the sidebar
(rather than requiring expand → click).
`Bundles`, `Deployments`, and `Regions & Environments` remain nested and require expand.
### Desktop (collapsed sidebar -- icons only)
### Desktop (collapsed sidebar — icons only)
- Show icon for Release Control root only.
- Tooltip on hover shows "Release Control".
- Click navigates to Release Control overview or last active child.
- No separate Releases / Approvals icons in collapsed mode.
- Show icon for each group root only.
- Tooltip on hover shows the group label.
- Click navigates to the first item in the group or last active child.
- No separate child icons in collapsed mode.
### Mobile (navigation drawer)
- All root domains appear as top-level items in the drawer.
- Release Control expands in-place to show child nav items.
- `Releases` and `Approvals` may appear as drawer children with Release Control as visible parent.
- No Release Control capabilities may appear as top-level drawer items separate from the Release Control group.
- All 6 groups appear as top-level items in the drawer.
- Groups expand in-place to show child nav items.
- No capabilities may appear as top-level drawer items separate from their group.
## Breadcrumb rules
Canonical format: `Root Domain > Capability > [Sub-page]`
Canonical format: `Group > Capability > [Sub-page]`
| Scenario | Breadcrumb | Notes |
| --- | --- | --- |
| Releases list | `Release Control > Releases` | No shortcut bypasses ownership label |
| Deployments list | `Release Control > Deployments` | |
| Release detail | `Release Control > Releases > RCB-1234` | ID or name appended |
| Approvals queue | `Release Control > Approvals` | |
| Approval detail | `Release Control > Approvals > APR-5678` | |
| Bundle catalog | `Release Control > Bundles` | |
| Bundle detail | `Release Control > Bundles > my-bundle` | |
| Bundle version detail | `Release Control > Bundles > my-bundle > v1.3.0` | |
| Deployments | `Release Control > Deployments` | |
| Environments list | `Release Control > Regions & Environments` | |
| Environment detail | `Release Control > Regions & Environments > staging-eu` | |
| Readiness | `Release Control > Readiness` | New item |
| Vulnerabilities | `Security > Vulnerabilities` | |
| Findings Explorer | `Security > Security Posture > Findings Explorer` | Nested under posture |
| VEX & Exceptions | `Security > VEX & Exceptions` | Absorbed from Policy |
| Risk & Governance | `Security > Risk & Governance` | Absorbed from Policy |
| Policy Simulation | `Security > Risk & Governance > Simulation` | Nested child |
| Evidence Overview | `Evidence > Evidence Overview` | |
| Decision Capsules | `Evidence > Decision Capsules` | |
| Audit Log | `Evidence > Audit Log` | |
| Operations Hub | `Operations > Operations Hub` | |
| Policy Packs | `Operations > Policy Packs` | Absorbed from Policy |
| Integrations | `Settings > Integrations` | |
| Certificates & Trust | `Settings > Certificates & Trust` | Renamed from "Certificates" |
### Concrete counter-examples (forbidden)
| Forbidden breadcrumb | Reason |
| --- | --- |
| `Approvals > APR-5678` | Missing Release Control ownership prefix |
| `Releases` (no parent) | Same — no domain context |
| `Settings > Policy Governance` | Policy Governance owner is Administration, not Settings |
| `Evidence & Audit > Trust & Signing` | Trust & Signing owner is Administration; Evidence may only show a consumer link |
| `Policy > VEX & Exceptions` | Policy group no longer exists; VEX is under Security |
| `Policy > Packs` | Policy group dissolved; Packs is under Operations |
| `Approvals > APR-5678` | Missing group ownership prefix |
| `Releases` (no parent) | No domain context |
| `Evidence > Trust` | Trust item removed from Evidence nav |
## Legacy label transition behavior
@@ -83,7 +145,7 @@ Where users know a surface by an old label, show a compact transition label duri
Rules:
- Transition labels appear only in page headers and sidebar items, not in breadcrumbs.
- Format: canonical label is primary; old label appears parenthetically — e.g., `Policy Governance (formerly Policy Studio)`.
- Format: canonical label is primary; old label appears parenthetically -- e.g., `Certificates & Trust (formerly Certificates)`.
- Transition labels are removed at sprint 016 cutover unless traffic evidence requires extension.
- Canonical labels are always primary; old labels never replace canonical ones.
@@ -91,26 +153,26 @@ Planned transition labels:
| Canonical label | Transition label (migration window only) | Remove at |
| --- | --- | --- |
| `Security & Risk` | `Security & Risk (formerly Security)` | Sprint 016 |
| `Platform Ops` | `Platform Ops (formerly Operations)` | Sprint 016 |
| `Evidence & Audit` | `Evidence & Audit (formerly Evidence)` | Sprint 016 |
| `Policy Governance` | `Policy Governance (formerly Policy Studio / Policy)` | Sprint 016 |
| `Security` | `Security (formerly Security & Risk)` | Sprint 016 |
| `Operations` | `Operations (formerly Platform Ops)` | Sprint 016 |
| `Evidence` | `Evidence (formerly Evidence & Audit)` | Sprint 016 |
| `Certificates & Trust` | `Certificates & Trust (formerly Certificates)` | Sprint 016 |
## Explicit do-not list
The following rendering patterns are forbidden in any sprint implementation:
1. **Do not** place Release Control capability screens (`Releases`, `Approvals`, `Bundles`, `Deployments`, `Environments`) as root-level sidebar items independent from the `Release Control` group.
2. **Do not** display a breadcrumb that omits the canonical root domain prefix.
1. **Do not** place any capability as a root-level sidebar item independent from its canonical group.
2. **Do not** display a breadcrumb that omits the canonical group prefix.
3. **Do not** show different ownership labels on desktop vs. mobile for the same screen.
4. **Do not** use legacy root-level nav paths (e.g., `/approvals`, `/releases`) as the canonical nav target — they must redirect to `/release-control/*` canonical targets.
5. **Do not** label `Trust & Signing` as owned by Evidence & Audit or Security in any nav or header.
6. **Do not** label `Policy Governance` as owned by Release Control in any nav or header.
7. **Do not** introduce a new root domain that is not in the canonical 7: Dashboard, Release Control, Security & Risk, Evidence & Audit, Integrations, Platform Ops, Administration.
4. **Do not** use legacy root-level nav paths (e.g., `/approvals`, `/releases` at root) as the canonical nav target -- they must redirect to canonical targets.
5. **Do not** reintroduce a `policy` group -- Policy items live under Security and Operations.
6. **Do not** label Policy Packs as owned by Security -- Packs authoring is an Operations concern.
7. **Do not** introduce a new root domain that is not in the canonical 6: Home, Release Control, Security, Evidence, Operations, Settings.
## Route alias requirements for migration
During the alias window, current root-level paths (`/releases`, `/approvals`) must:
- Resolve to the canonical `/release-control/releases` and `/release-control/approvals` routes.
- Render the canonical breadcrumb (e.g., `Release Control > Releases`) — not an alias-derived breadcrumb.
During the alias window, legacy paths must:
- Resolve to the canonical routes under the new group structure.
- Render the canonical breadcrumb (e.g., `Security > VEX & Exceptions`) -- not an alias-derived breadcrumb.
- Not appear as primary nav items in the sidebar; the sidebar must link to canonical paths only.