TenantAtlas/specs/131-cross-resource-navigation/spec.md

# Feature Specification: Cross-Resource Navigation & Drill-Down Cohesion

**Feature Branch**: `131-cross-resource-navigation`  
**Created**: 2026-03-10  
**Status**: Draft  
**Input**: User description: "Establish consistent cross-resource navigation and drill-down flows across related enterprise resources"

## Spec Scope Fields *(mandatory)*

- **Scope**: canonical-view
- **Primary Routes**:
  - Workspace admin governance and inventory detail pages under `/admin/...`
  - Canonical workspace operations and monitoring surfaces under `/admin/operations...`
  - Tenant-context entry points under `/admin/t/{tenant}/...` only where they launch canonical related views with preserved context
- **Data Ownership**:
  - Existing workspace-owned governance, monitoring, backup, and inventory records remain the source of truth
  - Existing tenant-scoped records remain unchanged; this feature standardizes how their relationships are presented and traversed
  - No new persisted domain model is introduced; only navigation, presentation, and relation mapping behavior change
- **RBAC**:
  - Workspace membership remains the primary boundary for visibility across admin resources
  - Target-resource capability checks remain required before rendering actionable navigation to related records
  - Cross-resource navigation must preserve deny-as-not-found behavior for non-members and under-entitled tenant scope

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: When a user launches a canonical operations or monitoring destination from a tenant-context screen, the destination opens on the authoritative workspace-level route with the originating tenant applied as visible filter or context badge when relevant.
- **Explicit entitlement checks preventing cross-tenant leakage**: Canonical destinations must enforce existing workspace membership and tenant-scope entitlements before rendering related records; users outside the permitted workspace or tenant scope must not receive target details, related labels, or actionable deep links.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Trace a finding to its source (Priority: P1)

As a governance operator, I want to move from a finding to its related snapshot, policy context, and source run without copying identifiers so I can investigate drift and evidence quickly.

**Why this priority**: Findings are a high-pressure triage surface. If operators hit dead ends there, the broader governance workflow breaks.

**Independent Test**: Can be fully tested by opening a finding with related records and verifying that the finding detail and list surfaces expose clear links to the most important upstream evidence and downstream operational context.

**Acceptance Scenarios**:

1. **Given** a finding with an accessible related baseline snapshot and source run, **When** an authorized operator opens the finding, **Then** the page exposes clear related-context entries and drill-down actions to those records using human-readable labels.
2. **Given** a findings list with rows that each have different related records available, **When** the operator reviews the list, **Then** each row exposes only the most relevant available drill-down actions and does not force the operator to open the record just to continue the workflow.

---

### User Story 2 - Move between policy history and snapshot evidence (Priority: P1)

As a policy operator, I want to move coherently between a policy, its versions, and related baseline snapshots so I can understand how captured evidence maps back to governance history.

**Why this priority**: Policy, version, and snapshot relationships are central to the platform’s governance model and should not require manual reconstruction.

**Independent Test**: Can be fully tested by opening a policy version and a baseline snapshot and verifying that each surface exposes the expected related parent, child, or filtered-list destinations.

**Acceptance Scenarios**:

1. **Given** a policy version that belongs to a parent policy and is referenced by accessible snapshots, **When** an authorized operator opens the policy version, **Then** the page offers a direct path back to the parent policy and to relevant snapshot evidence.
2. **Given** a baseline snapshot tied to a baseline profile, source run, and policy-version evidence, **When** an authorized operator opens the snapshot, **Then** the page exposes those related records in a structured context section rather than raw identifiers or scattered text fields.

---

### User Story 3 - Preserve context when leaving tenant-scoped entry points (Priority: P2)

As an operator working from a tenant-context screen, I want canonical operations and monitoring pages to preserve my current tenant meaning so I can continue my investigation without losing scope.

**Why this priority**: Canonical routes reduce route sprawl, but they must not force the operator to mentally reconstruct which tenant the workflow came from.

**Independent Test**: Can be fully tested by navigating from a tenant-context page into a canonical operations destination and verifying that the resulting screen preserves tenant context through filters, badges, or visible metadata.

**Acceptance Scenarios**:

1. **Given** an operator launches a canonical operations view from a tenant-context resource, **When** the canonical page opens, **Then** the route remains the authoritative workspace-level destination and the originating tenant context is visibly preserved.
2. **Given** an operator uses breadcrumbs or back links after drilling into a canonical operations destination, **When** they navigate back, **Then** the path reflects resource lineage or filtered-list origin rather than arbitrary browser-history behavior.

### Edge Cases

- A related record may be missing, deleted, or unresolved even though a stored reference exists.
- A user may be allowed to view the current record but not the related destination.
- A one-to-many relation may be more useful as a filtered canonical list than as a single-record deep link.
- A record may have several technically available relations, but only a subset should be surfaced to avoid link sprawl.
- A canonical operations destination may be reachable from both workspace-level and tenant-context entry points without changing the authoritative route.
- Some screens may show technical identifiers as secondary context, but those identifiers must not be the only navigation affordance for high-value relationships.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature is a presentation and navigation cohesion improvement over existing governance, monitoring, inventory, and backup records. It introduces no new Microsoft Graph calls, no new write workflows, no new queue or scheduled jobs, and no new mutable domain records. Existing `OperationRun` and related evidence records remain authoritative; this feature only standardizes how users move between them.

**Constitution alignment (OPS-UX):** This feature reuses existing operational records as destinations only. It does not create or mutate `OperationRun` state, does not alter toast/progress/terminal notification behavior, and must not introduce operational side effects into read-only navigation surfaces.

**Constitution alignment (RBAC-UX):** This feature affects workspace-admin `/admin` surfaces and tenant-context `/admin/t/{tenant}/...` entry points that launch related canonical views. Cross-plane access remains deny-as-not-found. Non-members or users outside entitled workspace or tenant scope must receive 404 semantics. In-scope members lacking target-resource capability must receive 403 semantics where protected resource access is attempted. Server-side gates or policies must continue to govern every related-resource destination. No raw capability strings or role-string checks may be introduced. At least one positive and one negative authorization test must cover related-resource visibility and navigation behavior.

**Constitution alignment (OPS-EX-AUTH-001):** Not applicable. This feature introduces no authentication handshake behavior and must not add synchronous outbound work to monitoring pages.

**Constitution alignment (BADGE-001):** If tenant or resource context badges are introduced or standardized as part of context-preserving navigation, they must use existing centralized badge semantics rather than ad hoc per-page mappings.

**Constitution alignment (Filament Action Surfaces):** This feature modifies multiple Filament resource list and detail surfaces. The Action Surface Contract must remain satisfied by using consistent inspect affordances, capped visible row actions, and structured view-page related actions. No destructive actions are introduced by this feature.

**Constitution alignment (UX-001 — Layout & Information Architecture):** Modified detail pages must expose related context through sectioned view layouts rather than ad hoc field dumps. View pages remain infolist-first or equivalent read-only presentations. List pages continue to provide search, sort, and filter behavior for core dimensions while adding predictable related drill-down actions without overloading each row.

### Functional Requirements

- **FR-131-01 Related navigation availability**: Whenever a related record is surfaced in a related-context section or as a drill-down action, the interface must provide either an actionable navigation path or a clear unavailable state for that specific displayed relation.
- **FR-131-02 Human-readable relation labels**: Related records must be presented with human-readable labels whenever possible, with technical identifiers shown only as secondary context.
- **FR-131-03 Canonical operations destinations**: All run-oriented or monitoring-oriented drill-down actions must resolve to the canonical workspace-level operations destination pattern.
- **FR-131-04 Tenant-context preservation**: When a canonical destination is opened from a tenant-context source, the destination must preserve the originating tenant meaning through filters, badges, or visible context metadata without changing the authoritative route.
- **FR-131-05 Structured related-context section**: Key detail pages must expose a structured related-context section that groups the most important connected records for the current object.
- **FR-131-06 Detail-surface consistency**: Related-context sections must follow a stable pattern across key detail pages so operators can predict where to find upstream and downstream links.
- **FR-131-07 List-level drill-down actions**: High-value list surfaces must expose direct row-level drill-down actions to the most relevant related records when those actions support common operator workflows.
- **FR-131-08 Limited action noise**: Pages with multiple possible related links must prioritize the few most useful operator journeys and avoid surfacing every technical relation at once. Default priority order is: direct upstream evidence for the current record first, canonical run or operations context second when it explains provenance, and filtered list destinations for one-to-many follow-up third.
- **FR-131-09 Shared action vocabulary**: Cross-resource navigation labels must converge on a small, consistent vocabulary such as “View policy,” “View policy version,” “View snapshot,” “View run,” and “Open operations.”
- **FR-131-10 Dead-end reduction**: Key enterprise records including findings, baseline snapshots, policy versions, operation runs, and backup sets must not present as dead-end pages when meaningful related destinations exist.
- **FR-131-11 Missing relation handling**: Missing, deleted, unresolved, or inaccessible related references must render as clear unavailable states without broken links or misleading affordances.
- **FR-131-12 Role-aware action rendering**: Related-resource links and actions must only render as actionable when the user is permitted to open the target resource.
- **FR-131-13 Non-leaking unavailable states**: Where policy allows awareness of a relation but not access to the target, the interface may show a non-clickable unavailable state without disclosing protected target detail.
- **FR-131-14 Breadcrumb semantics**: Breadcrumbs and back links must support resource lineage and filtered-list origin semantics rather than relying only on browser history.
- **FR-131-15 Explicit navigation matrix**: The implementation must define and follow an explicit cross-resource navigation matrix for the major policy, snapshot, finding, backup, and operations relationships in scope.
- **FR-131-16 Policy and version navigation**: Users must be able to move coherently between policies and policy versions, including access to parent policy context from version surfaces.
- **FR-131-17 Snapshot and profile navigation**: Users must be able to move between baseline snapshots and their owning baseline profiles, with source run context shown where available.
- **FR-131-18 Snapshot and findings navigation**: Users must be able to move between snapshots and related findings where that relationship exists and is meaningful.
- **FR-131-19 Finding evidence navigation**: Findings must expose direct paths to their most important related evidence or source artifacts where available.
- **FR-131-20 Backup and run navigation**: Backup sets and related operation runs must expose coherent navigation in both directions where applicable.
- **FR-131-21 Operations to domain navigation**: Canonical operations detail or filtered-list surfaces must provide drill-down paths back to the primary affected domain record when one exists.
- **FR-131-22 Reusable relation presentation model**: Related links must be generated from a reusable presentation pattern so labels, availability, and context hints stay consistent across screens.
- **FR-131-23 Centralized relation mapping**: Non-trivial cross-resource mapping rules must be centralized so future resources can plug into the same navigation pattern without page-by-page duplication.
- **FR-131-24 Extensible future coverage**: The navigation pattern must remain extensible enough to support future related artifacts such as reports, evidence items, exceptions, review packs, and audit entries by allowing a new relation type to be added through the centralized matrix, label catalog, and shared related-context renderer without requiring page-specific label or availability logic changes on existing resources.

### Non-Goals

- Full information architecture or sidebar redesign
- Global search redesign
- New data models or relationship persistence changes
- Audit log redesign
- Baseline snapshot renderer redesign
- Bulk workflow redesign
- Notification redesign
- Customer read-only portal behavior
- Universal link exposure for every possible relation on every page

### Assumptions

- The current product already stores enough relationship metadata to support materially better drill-down behavior on the highest-value enterprise resources.
- Canonical operations and monitoring destinations already exist or are being converged elsewhere and should be reused here rather than duplicated.
- Operators benefit more from a predictable small set of high-value actions than from exhaustive exposure of every related record.
- Some one-to-many relationships are best represented as filtered canonical lists rather than direct links to a single target record.

### Dependencies

- Existing workspace and tenant authorization rules
- Existing canonical operations and monitoring destination patterns
- Existing governance, backup, inventory, and monitoring resource relationships
- Existing related-record labels or display names where available

## UI Action Matrix *(mandatory when Filament is changed)*

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Findings | Workspace admin list and detail surfaces | None new beyond related view actions | Primary finding inspection remains the row or title link | View snapshot, View run | None | Existing empty state remains; no new CTA required | View snapshot, View policy or View run where most relevant | N/A | No | Related-context section added on detail view; no destructive actions |
| Baseline snapshots | Workspace admin list and detail surfaces | None new beyond related view actions | Snapshot title or row remains primary inspect affordance | View profile, Open findings | None | Existing immutable empty state remains | View baseline profile, View run | N/A | No | Detail page gains structured related context |
| Policy versions | Workspace admin list and detail surfaces | None new beyond related view actions | Version title or row remains primary inspect affordance | View policy, View snapshot | None | Existing empty state remains | View policy, Open snapshots | N/A | No | Focus is lineage and evidence navigation |
| Backup sets | Workspace admin list and detail surfaces | None new beyond related view actions | Backup set row remains primary inspect affordance | View run, View artifact | None | Existing empty state remains | View run, Open operations | N/A | No | No backup mutation changes in this spec |
| Operation runs and canonical operations pages | Canonical workspace operations list and detail surfaces | Filter and related navigation only | Canonical run inspection remains the primary row or detail action | View target record, View backup set when relevant | None | Existing empty state may include one canonical filter reset CTA if already standard | View related record, Back to related list context | N/A | No | Canonical route authority is the primary requirement |

### Navigation Matrix

- **NM-131-01 Policy ↔ Policy Version**: Policy surfaces expose versions or latest relevant version; policy version surfaces expose parent policy and may expose filtered sibling-version context where useful.
- **NM-131-02 Policy Version ↔ Baseline Snapshot**: Policy version surfaces expose related snapshot evidence where supported; snapshot surfaces expose referenced policy version when resolvable and permitted.
- **NM-131-03 Baseline Snapshot ↔ Baseline Profile**: Snapshot surfaces expose owning baseline profile; baseline profile surfaces expose snapshots or latest relevant snapshot where meaningful.
- **NM-131-04 Baseline Snapshot ↔ Findings**: Snapshot surfaces expose related findings via filtered list or direct drill-down; finding surfaces expose the source snapshot where available.
- **NM-131-05 Finding ↔ Source Artifact**: Finding surfaces expose the most relevant source artifact among snapshot, baseline profile, policy, policy version, or run depending on available context.
- **NM-131-06 Backup Set ↔ Operation Run**: Backup set surfaces expose originating or recent related runs; run surfaces expose the related backup set or resulting artifact when applicable.
- **NM-131-07 Operation Run ↔ Domain Resource**: Canonical run surfaces expose the primary affected or target domain record where meaningful; domain-resource surfaces expose the related run or canonical operations view.
- **NM-131-08 Operations ↔ Tenant Context**: Tenant-scoped entry points open the canonical operations destination with tenant context visibly preserved rather than branching to alternate route families.

### Key Entities *(include if feature involves data)*

- **Related Context Entry**: A normalized presentation of one important related record, including user-facing label, destination availability, relation type, and context hint.
- **Drill-Down Action**: A standardized action that opens a directly related upstream, downstream, or canonical list destination from a list or detail surface.
- **Navigation Matrix Rule**: The explicit definition of which related destination should be offered for a given resource relationship and in which UI surface.
- **Canonical Destination Context**: The preserved workspace and tenant meaning applied when a user opens an authoritative operations or monitoring page from another screen.
- **Unavailable Relation State**: The representation used when a related record exists conceptually but cannot be opened because it is missing, unresolved, or unauthorized.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-131-01 Reduced dead ends**: In acceptance testing of the in-scope high-value resources, operators can move to at least one meaningful related destination from every eligible detail page without copying identifiers manually.
- **SC-131-02 Canonical operations consistency**: In navigation tests for run-related actions, 100% of in-scope “View run” and similar operational links resolve to the canonical workspace-level operations destination pattern.
- **SC-131-03 Evidence traceability**: In finding and snapshot test scenarios, operators can reach the most important related evidence or source record in one direct action from the current screen.
- **SC-131-04 Context preservation**: In tenant-context-to-canonical navigation tests, 100% of in-scope flows preserve visible tenant meaning on the canonical destination.
- **SC-131-05 Graceful degradation**: In missing, unresolved, or unauthorized relation scenarios, 100% of tested screens render a clear unavailable state without broken links.
- **SC-131-06 Label consistency**: In regression review of the in-scope surfaces, the shared action vocabulary is used consistently for equivalent drill-down tasks.