git.stella-ops.org/docs/modules/ui/v2-rewire/source-of-truth.md

UI v2 Rewire Source of Truth

Status: Active Date: 2026-02-20 Working directory: docs/modules/ui/v2-rewire

1) Hard rules

1. For overlapping guidance, higher pack number wins.
2. If a higher pack is partial, keep the latest lower-pack detail for uncovered screens.
3. Inside one pack, interpret in this order:
   • Now/New location statements,
   • menu/screen graphs,
   • ASCII/rationale text.
4. Canonical planning references must come from this file plus authority-matrix.md, not raw packs alone.
5. pack-23.md is the active Platform IA override for all conflicts with pack-22.md and lower packs.
6. pack-22.md remains authority for non-Platform areas unless pack-23.md explicitly overrides them.

2) Canonical IA (v3)

2.1 Root modules

Canonical top-level modules are:

• Dashboard
• Releases
• Security
• Evidence
• Topology
• Platform
• Administration

2.2 Global context

Region and Environment are global context selectors in the top bar, not deep menu nodes.

Required global context controls:

• Search
• Region multi-select
• Environment multi-select scoped to Region selection
• Time window selector
• Status indicators (offline/feed/policy/evidence)

2.3 Ownership decisions resolved by precedence

These are authoritative for planning and replace older conflicting placements:

• Release Control root is decomposed:
  • release lifecycle surfaces move to Releases,
  • inventory/setup surfaces move to Topology.
• Bundle is deprecated in operator IA and renamed to Release.
• Runs, Deployments, Promotions, and Hotfixes are lifecycle views inside Releases and not top-level modules.
• VEX and Exceptions are exposed as one UX concept:
  • Security -> Triage disposition rail + detail tabs,
  • Security -> Advisories & VEX for provider/library/conflict/trust operations,
  • backend data models remain distinct.
• SBOM, reachability, and unknowns are unified under Security -> Supply-Chain Data tabs.
• Advisory feed and VEX source configuration belongs to Integrations, not Security.
• Policy Governance remains under Administration.
• Trust posture must be reachable from Evidence, while admin-owner trust mutations remain governed by administration scopes.

3) Canonical screen authorities

Use the following packs as the latest valid source per domain.

3.1 IA and naming consolidation

Authoritative pack:

• pack-22.md
• pack-23.md (highest precedence for Platform ownership and menu placement)
• pack-22.md

Superseded for overlapping decisions:

• pack-21.md and lower packs for root module grouping and naming.

3.2 Dashboard

Authoritative packs:

• pack-22.md for mission control framing and quick actions.
• pack-16.md for detailed dashboard signal widgets where not overridden.

3.3 Releases

Authoritative packs:

• pack-22.md for consolidation model (list, detail tabs, activity, approvals queue).
• pack-12.md for release composition/builder details.
• pack-13.md for promotion flow semantics.
• pack-14.md for timeline/checkpoint/rollback/replay semantics.
• pack-17.md for approvals detail depth.

Superseded:

• Standalone menu treatment from earlier packs where runs/deployments/promotions/hotfixes were separate roots.

3.4 Topology

Authoritative packs:

• pack-22.md for module ownership and taxonomy.
• pack-18.md for environment detail shell standards reused inside topology-aware views.

3.5 Security

Authoritative packs:

• pack-22.md for consolidation into Overview, Triage, Advisories & VEX, Supply-Chain Data, and optional Reports.
• pack-19.md for decision-first security detail behavior where not overridden.

Superseded:

• Earlier split explorer layouts that force separate VEX/Exceptions and separate SBOM roots.

3.6 Evidence

Authoritative packs:

• pack-22.md for evidence navigation framing and release linkage expectations.
• pack-20.md for evidence chain structure (packs/export/proof/replay/audit).

3.7 Operations

Authoritative packs:

• pack-23.md for Platform Ops placement and workflow prioritization.
• pack-15.md for data integrity operating model.
• pack-10.md for feeds/airgap operational detail where still valid.

3.8 Integrations

Authoritative packs:

• pack-23.md for Platform Integrations placement and topology ownership split.
• pack-10.md and pack-21.md for connector detail flows where not overridden.

3.9 Administration

Authoritative packs:

• pack-22.md for top-level scope.
• pack-21.md for detailed A0-A7 screen structure where not overridden.

4) Normalized terminology (canonical names)

Use these terms in sprint tickets/specs:

• Bundle -> Release
• Create Bundle -> Create Release
• Current Release -> Deploy Release
• Run Timeline -> Activity (cross-release) or Timeline (release detail tab)
• Security & Risk -> Security
• Evidence & Audit -> Evidence
• Platform Ops -> Platform -> Ops
• Integrations root -> Platform -> Integrations
• Setup root -> Platform -> Setup
• Regions & Environments menu -> Topology module + global context switchers

5) Planning gaps to schedule first

Create first-wave dependency sprints for:

• backend global context contracts and persistence (Region/Environment top-bar model),
• releases read-model contracts for list/detail/activity/approvals queue,
• topology inventory contracts and synchronization,
• security disposition aggregation contracts (VEX + Exceptions UX join),
• route deprecation map from /release-control/*, /security-risk/*, /evidence-audit/*, /platform-ops/* to canonical paths.