TenantAtlas/specs/192-record-header-discipline/spec.md

# Feature Specification: Record Page Header Discipline & Contextual Navigation

**Feature Branch**: `192-record-header-discipline`  
**Created**: 2026-04-11  
**Status**: Proposed  
**Input**: User description: "Spec 192 - Record Page Header Discipline & Contextual Navigation"

## Spec Candidate Check *(mandatory — SPEC-GATE-001)*

- **Problem**: Several classic admin record/detail/edit pages still expose flat header button rows where navigation, routine mutation, infrequent administration, and danger all compete at the same visual weight.
- **Today's failure**: Operators reach the right pages, but the header often does not signal the next best step. Navigation occupies prime action space, multiple mutations compete visibly, and rare or destructive actions appear too close to routine actions.
- **User-visible improvement**: Standard record pages become calmer and easier to scan. One next step becomes obvious, contextual navigation moves closer to the content it belongs to, and risky or rare actions stop cluttering the primary header lane.
- **Smallest enterprise-capable version**: Classify all in-scope record/detail/edit surfaces, remediate the clearly problematic standard pages with one shared header discipline, explicitly catalog the one workflow-heavy exception, and add lightweight regression protection.
- **Explicit non-goals**: No new global action framework for every surface class, no monitoring or workbench action cleanup, no new confirmation-depth policy, no provider-dispatch redesign, and no forced Spec 133 body-layout rollout onto simple pages.
- **Permanent complexity imported**: A narrow cross-page header-discipline contract, an explicit surface-classification matrix, a documented special-type exception, and focused regression coverage for record-page header sprawl.
- **Why now**: The constitution now contains HDR-001, and the repo already has both good and bad examples. Without a concrete inventory and rule rollout, drift will continue page by page.
- **Why not local**: Isolated page-by-page cleanup would reduce noise on one page at a time but would not create a stable repo-wide rule for when navigation belongs in context, when secondary actions must be grouped, or when a page deserves a special-type exception.
- **Approval class**: Cleanup
- **Red flags triggered**: Cross-domain UI rule risk if this grows into a generalized action framework. Defense: the spec stays limited to classic record/detail/edit surfaces, forbids a new engine, and explicitly excludes other surface classes.
- **Score**: Nutzen: 2 | Dringlichkeit: 1 | Scope: 2 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 2 | **Gesamt: 10/12**
- **Decision**: approve

## Spec Scope Fields *(mandatory)*

- **Scope**: canonical-view
- **Primary Routes**:
  - Existing BaselineProfile resource view route
  - Existing EvidenceSnapshot, FindingException, and TenantReview resource view routes
  - Existing Tenant resource view and edit routes in the tenant admin plane
  - Existing ProviderConnection and Finding resource view routes
  - Existing ReviewPack, AlertDestination, PolicyVersion, Workspace resource view routes
  - Existing BaselineSnapshot and BackupSet resource view routes
- **Data Ownership**:
  - Workspace-owned records touched by this spec remain workspace-owned: BaselineProfile, BaselineSnapshot, AlertDestination, PolicyVersion, and Workspace views.
  - Tenant-owned records touched by this spec remain tenant-owned: EvidenceSnapshot, Finding, FindingException, TenantReview, Tenant, ProviderConnection, ReviewPack, and BackupSet views.
  - This spec introduces no new tables, persisted entities, route semantics, or record truth. It changes only action hierarchy, placement, and classification on existing pages.
- **RBAC**:
  - Existing workspace membership plus capability checks continue to govern workspace-owned pages.
  - Existing tenant membership plus capability checks continue to govern tenant-owned pages.
  - Header regrouping does not change authorization semantics: non-members remain `404`, members lacking a capability remain `403`, and destructive actions retain confirmation plus server-side authorization.

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: This feature adds no new filter behavior. Tenant-scoped record pages remain bound to the active tenant context, while workspace-owned record pages remain workspace-scoped even if a tenant was previously active. Moving navigation out of the primary header must not broaden scope or imply cross-tenant search.
- **Explicit entitlement checks preventing cross-tenant leakage**: Any contextual link that survives the header cleanup must still be built through existing related-navigation and capability-aware helpers. Inaccessible related records remain suppressed, non-members remain deny-as-not-found, and moving an action from primary header placement to contextual or grouped placement must not reveal a destination that was previously inaccessible.

## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)*

| Surface | Surface Type | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Baseline profile detail | Workspace record detail | Existing BaselineProfile inspect flow into the view page | allowed | Summary context and grouped secondary header actions after remediation | none | Existing BaselineProfile collection route | Existing BaselineProfile view route | Workspace, active snapshot state, visible assigned-tenant count | Baseline profile | Whether a consumable snapshot exists and whether capture or compare is the next step | remediation required |
| Evidence snapshot detail | Tenant record detail | Existing EvidenceSnapshot inspect flow into the view page | allowed | Related-context links and grouped secondary header actions | Separated lifecycle danger action | Existing EvidenceSnapshot collection route | Existing EvidenceSnapshot view route | Tenant, freshness, expiry, latest review-pack relationship | Evidence snapshot | Whether the snapshot is current, reusable, or needs refresh/expiry handling | remediation required |
| Finding exception detail | Tenant governance detail | Existing FindingException inspect flow into the view page | allowed | Related finding and approval-queue links move to contextual placement outside the header | Revocation remains isolated danger | Existing FindingException collection or approval-queue route | Existing FindingException view route | Tenant, validity state, owner, review due state | Finding exception | Whether the exception remains valid and what governance step is next | remediation required |
| Tenant review detail | Tenant record detail | Existing TenantReview inspect flow into the view page | allowed | Related export/evidence/run links move to contextual placement outside the header, while infrequent lifecycle actions stay grouped secondary | Archive remains separated inside secondary danger placement | Existing TenantReview collection route | Existing TenantReview view route | Tenant, review status, evidence/export linkage, operation context | Tenant review | Which lifecycle step is next and whether the review is ready to refresh, publish, or export | remediation required |
| Tenant edit surface | Tenant edit record | Existing Tenant edit entry from tenant list or tenant detail | allowed | Related view/context links move to contextual placement outside the header | Archive or restore stays separate from ordinary edit context | Existing Tenant collection route | Existing Tenant edit route | Tenant lifecycle, workspace context, related onboarding status | Tenant | That this surface is for editing and not for multi-purpose workflow dispatch | remediation required |
| Tenant detail (tenant admin resource view) | Workflow-heavy tenant detail hub | Existing Tenant inspect flow into the resource view page | allowed | Contextual navigation remains outside the header, while internal grouped header actions remain mandatory for external links, verification, setup, and lifecycle work | Lifecycle actions remain isolated inside grouped danger placement | Existing Tenant collection route | Existing Tenant resource view route | Tenant lifecycle, verification state, RBAC health, recent operations, onboarding context | Tenant | What setup, verification, or lifecycle step currently deserves attention | workflow-heavy special-type exception |
| Provider connection detail | Tenant configuration detail | Existing ProviderConnection inspect flow into the view page | allowed | Secondary admin actions stay in a deliberate grouped override-management structure | Dangerous credential actions stay inside separated danger slot within the group | Existing ProviderConnection collection route | Existing ProviderConnection view route | Tenant, provider, connection type, consent and verification state | Provider connection | Whether the connection is usable and which override or consent step is relevant | minor alignment only |
| Finding detail | Tenant record detail | Existing Finding inspect flow into the view page | allowed | Back-link, related-context link, and approval-queue navigation stay secondary or grouped | Workflow danger stays inside the workflow group | Existing Finding collection route | Existing Finding view route | Tenant, severity or health context, related approval state | Finding | What the finding means and where the next governance or remediation path lives | minor alignment only |
| Review pack detail | Tenant export detail | Existing ReviewPack inspect flow into the view page | allowed | Regenerate remains secondary to the pack outcome | none | Existing ReviewPack collection route | Existing ReviewPack view route | Tenant, pack status, export options, readiness | Review pack | Whether the pack is ready for download | compliant / no-op reference |
| Alert destination detail | Workspace configuration detail | Existing AlertDestination inspect flow into the view page | allowed | Deep-link navigation stays secondary | none | Existing AlertDestination collection route | Existing AlertDestination view route | Workspace, destination type, enabled state, last-test state | Alert destination | Whether delivery is enabled and whether the last test succeeded | compliant / no-op reference |
| Policy version detail | Workspace detail | Existing PolicyVersion inspect flow into the view page | allowed | Single related-record navigation remains contextual | none | Existing PolicyVersion collection route | Existing PolicyVersion view route | Workspace, version identity, policy relationship | Policy version | What version is being inspected and what record it belongs to | compliant / no-op reference |
| Workspace resource detail | Workspace detail | Existing Workspace inspect flow into the resource view page | allowed | No secondary header cluster required | none | Existing Workspace collection route | Existing Workspace resource view route | Workspace identity and manage capability state | Workspace | Which workspace is being viewed and whether it can be edited | compliant / no-op reference |
| Baseline snapshot detail | Workspace detail | Existing BaselineSnapshot inspect flow into the view page | allowed | Single related-record navigation remains contextual | none | Existing BaselineSnapshot collection route | Existing BaselineSnapshot view route | Workspace, source profile, snapshot recency | Baseline snapshot | What snapshot is current and what related record it belongs to | compliant / no-op reference |
| Backup set detail | Tenant recovery detail | Existing BackupSet inspect flow into the view page | allowed | Related-record navigation plus grouped secondary mutations | Grouped restore/archive/force-delete danger structure already exists | Existing BackupSet collection route | Existing BackupSet view route | Tenant, archive state, restore relevance | Backup set | Whether the backup set is active, archived, or eligible for restore | compliant / no-op reference |

## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*

| Surface | Primary Persona | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|
| Baseline profile detail | Workspace operator | Standard record detail | Is this baseline ready to capture or compare, and what is the next step? | Snapshot readiness, capture mode, visible assignment scope | Run IDs, rollout reason details | readiness, snapshot freshness | `simulation only` for compare; existing workspace capture path for capture | `Capture baseline` or `Compare now` | none |
| Evidence snapshot detail | Tenant operator | Standard record detail | Is this evidence current enough, and do I need to refresh or inspect related outputs? | Snapshot status, expiry, related pack/run availability | Internal run identifiers | freshness, lifecycle | Existing evidence refresh scope only | `Refresh evidence` when applicable | `Expire snapshot` |
| Finding exception detail | Tenant manager | Governance record detail | Is this exception still valid, and do I need to renew or revoke it? | Current validity, owner, review due, linked finding context | Detailed evidence references | validity, governance lifecycle | `TenantPilot only` | `Renew exception` when applicable | `Revoke exception` |
| Tenant review detail | Tenant manager | Standard record detail | What is the next lifecycle step for this review? | Review status, evidence/export linkage, current operation context | Low-level run metadata | lifecycle, readiness, freshness | `TenantPilot only` for publish/archive; existing export path for pack generation | One of `Refresh review`, `Publish review`, or `Export executive pack` depending on state | `Archive review` |
| Tenant edit surface | Tenant manager or owner | Edit surface | Can I update this tenant safely without losing context? | Editable tenant identity, lifecycle state, related onboarding context | Technical provider details remain outside the primary edit task | lifecycle | `TenantPilot only` | Save the edit form | `Archive` or `Restore` when available |
| Tenant detail (tenant admin resource view) | Tenant operator or manager | Workflow-heavy detail hub | What tenant setup, verification, or lifecycle step needs attention right now? | Verification report, recent operations, RBAC health, onboarding state | Raw run detail and lower-level provider metadata | lifecycle, verification readiness, RBAC health | Mixed existing tenant-operation scopes | `Verify configuration` only if it is the clearly dominant next step; otherwise grouped actions only | `Archive` or `Restore` |
| Provider connection detail | Tenant manager | Configuration detail | Is this connection healthy, and what provider-management step is next? | Consent, connection type, override state | Credential-specific technical detail | consent, verification, lifecycle | Existing provider-management scopes | `Edit` or `Grant admin consent` only if one clearly dominates | Credential delete and override reversion remain grouped danger |
| Finding detail | Tenant operator | Standard record detail | What does this finding mean, and where should I go next? | Finding summary, related record context, governance path | Low-level payload detail | governance state, health or severity | Existing finding workflow scope only | Existing workflow primary, if any, stays inside governed group | Existing workflow danger only |
| Review pack detail | Tenant operator | Export detail | Is this pack ready to use? | Status, download readiness, pack options summary | Raw generation metadata | readiness, lifecycle | Existing export scope only | `Download` | none |
| Alert destination detail | Workspace operator | Configuration detail | Is this destination working? | Destination type, enabled state, last-test result | Delivery log drilldown context | enablement, delivery health | Existing alert-test scope only | `Send test message` | none |
| Policy version detail | Workspace operator | Reference detail | Which version am I looking at, and what record should I open next? | Version identity and parent policy context | Raw payload footer content | version lifecycle | read-only | Related-record open action only | none |
| Workspace resource detail | Workspace owner or manager | Standard record detail | What workspace is this, and can I manage it? | Workspace identity and top-level manage affordance | Low-level metadata | none beyond manage eligibility | `TenantPilot only` | `Edit` | none |
| Baseline snapshot detail | Workspace operator | Reference detail | What snapshot is this and what should I open next? | Snapshot identity, related profile context | Detailed snapshot payload content | recency, completeness | read-only | Related-record open action only | none |
| Backup set detail | Tenant manager | Recovery detail | Is this backup set active, archived, or ready to restore? | Archive state, related record context, restore relevance | Deep backup item detail | lifecycle, restore readiness | Existing backup mutation scope only | Related-record open action stays secondary; restore remains grouped | `Archive` and `Force delete` remain grouped danger |

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: no
- **New persisted entity/table/artifact?**: no
- **New abstraction?**: no
- **New enum/state/reason family?**: no
- **New cross-domain UI framework/taxonomy?**: yes
- **Current operator problem**: Classic record pages are inconsistent about what belongs in the primary header lane, so operators see avoidable noise and weak hierarchy on pages that should be fast to scan.
- **Existing structure is insufficient because**: HDR-001 exists at the constitutional level, but the repo still lacks a concrete inventory, a bounded standard-record rule set, and an explicit way to justify a workflow-heavy exception without page-local improvisation.
- **Narrowest correct implementation**: Apply the rule only to the explicitly named record/detail/edit surfaces, remediate only the pages that need it, preserve already clean pages, and document a single special-type exception instead of inventing a framework.
- **Ownership cost**: Ongoing review discipline for header-action placement, a small regression-test burden, browser smoke maintenance for remediated pages, and explicit exception tracking.
- **Alternative intentionally rejected**: Purely local cleanup on the five obvious problem pages was rejected because it would reduce immediate noise but would not stop future drift or explain why some pages are compliant while one page is an allowed exception.
- **Release truth**: current-release operator clarity and action-surface discipline

## User Scenarios & Testing *(mandatory)*

### User Story 1 - See one next step on standard record pages (Priority: P1)

As an operator opening a standard record/detail/edit page, I want the header to show one clear next step instead of a horizontal row of competing buttons.

**Why this priority**: This is the core workflow benefit. If the next step still competes with several peer actions, the feature has not solved the problem it targets.

**Independent Test**: Open each remediation-required standard page and verify that no more than one visible emphasized header action remains while routine navigation and rare actions move out of the flat primary lane.

**Acceptance Scenarios**:

1. **Given** a remediation-required standard record page, **When** the page renders after cleanup, **Then** it shows at most one visible primary header action.
2. **Given** a standard page whose next step depends on state, **When** the record state changes, **Then** the page promotes only the state-appropriate next action and keeps others secondary.

---

### User Story 2 - Follow contextual navigation near the relevant content (Priority: P1)

As an operator, I want related navigation to live near the summary or context it belongs to, instead of taking the same visual weight as a mutation.

**Why this priority**: Contextual navigation is still important, but it should support the reading flow instead of dominating the header.

**Independent Test**: Open remediated pages that currently mix navigation and mutation in the header and confirm that pure navigation moves to related-context or other inline contextual placement outside the header.

**Acceptance Scenarios**:

1. **Given** a remediated standard page with related-record navigation, **When** the page renders, **Then** the navigation no longer appears as a peer to the main mutation and instead lives in contextual placement outside the header.
2. **Given** a page offers both navigation and a next-step mutation, **When** the operator scans the header, **Then** the mutation reads as the next step and the navigation reads as supporting context.

---

### User Story 3 - Keep rare and dangerous actions available without clutter (Priority: P2)

As an operator, I want infrequent administrative actions and destructive actions to remain available without visually competing with routine work.

**Why this priority**: The pages still need power-user actions, but those actions should not make every visit look risky or overloaded.

**Independent Test**: Open pages with lifecycle or dangerous actions and confirm that rare actions are grouped and danger remains visibly separated with existing confirmation behavior intact.

**Acceptance Scenarios**:

1. **Given** a remediated page includes rare administrative actions, **When** the page renders, **Then** those actions live in a deliberate secondary group instead of as peer buttons.
2. **Given** a remediated page includes destructive or governance-sensitive actions, **When** the page renders, **Then** those actions remain separated from safe routine actions and still require confirmation.

---

### User Story 4 - Treat workflow-heavy pages as explicit exceptions (Priority: P3)

As a product reviewer, I want workflow-heavy record pages to be explicitly identified as exceptions so they stay disciplined without being forced into the wrong pattern.

**Why this priority**: The cleanup should not flatten important operational hubs into misleadingly simple pages.

**Independent Test**: Review the special-type page and verify that it is explicitly classified, internally structured, and not silently exempted.

**Acceptance Scenarios**:

1. **Given** the tenant admin resource view is a workflow-heavy hub, **When** the spec and implementation are reviewed, **Then** it is marked as a special-type exception with a documented internal action order.
2. **Given** a special-type page does not have one obvious next step, **When** it renders, **Then** it does not reintroduce a flat multi-button header row in the name of consistency.

### Edge Cases

- If a baseline profile has no consumable snapshot, `Capture baseline` remains the sole visible primary action and compare actions stay secondary or disabled.
- If a standard page has no related destination currently available, the cleanup must not insert a dead contextual-navigation placeholder just to satisfy consistency.
- If the current actor can view a record but cannot execute its mutation, the action may remain visible-but-disabled per existing RBAC rules, but it still must not become a competing primary if it is not executable.
- If a workflow-heavy page has no clearly dominant next step, it should keep grouped actions only rather than manufacturing a fake primary.
- If a compliant reference page already has one clean related action or one clean grouped danger structure, the spec must not force cosmetic churn.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature introduces no new Microsoft Graph contract, no new persisted truth, and no new queue model. It only reorganizes existing operator-facing action surfaces on existing record/detail/edit pages. Existing mutations keep their current preview, confirmation, audit, and run-observability behavior.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** The spec adds only a narrow cross-page UI discipline plus an explicit exception vocabulary. It introduces no new persistence, no new state family, and no generalized action engine. The proportionality review above documents why a bounded cross-page rule is justified and why a broader framework is rejected.

**Constitution alignment (OPS-UX):** Existing operations such as baseline capture, baseline compare, evidence refresh, tenant review refresh, verification, and provider-management actions continue to use their current `OperationRun`, toast, and audit contracts. This spec does not create a new run type or alter existing run summary semantics.

**Constitution alignment (RBAC-UX):** The feature spans workspace/admin and tenant-context surfaces but does not change authorization logic. Non-members remain `404`, members lacking required capabilities remain `403`, grouped or relocated actions still enforce server-side authorization, and destructive actions continue to require confirmation. At least one positive and one negative regression test must confirm that regrouping actions does not loosen access.

**Constitution alignment (OPS-EX-AUTH-001):** Not applicable. No authentication-handshake behavior changes.

**Constitution alignment (BADGE-001):** The cleanup does not introduce new badge semantics. Existing status and health badges remain centralized and unchanged.

**Constitution alignment (UI-FIL-001):** The feature must use native Filament header actions, `ActionGroup`, and existing shared UI primitives. It must avoid a page-local button framework or ad-hoc badge language. The only approved exception is keeping the tenant admin resource view as a workflow-heavy surface with explicit grouped action ordering.

**Constitution alignment (UI-NAMING-001):** Action labels must stay domain-first and consistent as actions move between primary, contextual, and grouped placement. Target verbs include `Capture baseline`, `Compare now`, `Refresh review`, `Publish review`, `Verify configuration`, `Open …`, `Archive`, and `Restore`. Implementation-first labels must not become primary operator labels.

**Constitution alignment (UI-CONST-001 / UI-SURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001):** This spec classifies each affected surface, defines the one inspect/open model already in use, preserves existing list inspect affordances, and reassigns secondary and destructive actions according to surface type. Standard record pages must expose one clear next step; explicit exceptions must be catalogued and justified.

**Constitution alignment (OPSURF-001):** Default-visible header content must stay operator-first. Pure navigation becomes contextual content outside the header, diagnostics remain secondary, and dangerous actions keep existing confirmation and mutation-scope language. Workspace and tenant context must remain explicit through the same routes, related links, and action copy already in use.

**Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001):** The feature introduces no new presenter or semantic layer. It uses direct action placement and classification rather than a new interpretation framework. Tests should prove business consequences of header discipline, not a thin abstraction.

**Constitution alignment (Filament Action Surfaces):** The Action Surface Contract is satisfied for all remediated standard record/detail/edit pages after cleanup: one visible primary header action, no redundant flat navigation buttons, no empty action groups, and destructive actions in the correct secondary or danger placement. The tenant admin resource view is the only explicit exception and must document why grouped workflow actions remain appropriate.

**Constitution alignment (UX-001 — Layout & Information Architecture):** This feature changes header-action hierarchy only. View pages continue to rely on their existing infolists or structured sections, and the tenant edit page keeps its edit-form save/cancel affordances as the primary edit path. The spec does not justify any regression toward disabled edit forms or naked-field layouts.

### Functional Requirements

- **FR-192-001 Surface inventory**: The spec and implementation MUST maintain an explicit inventory of every in-scope record/detail/edit surface covered by this feature.
- **FR-192-002 Explicit classification**: Every in-scope surface MUST be assigned exactly one classification: `compliant / no-op reference`, `remediation required`, `minor alignment only`, or `workflow-heavy special-type exception`.
- **FR-192-003 Standard-page primary rule**: Every remediated standard record/detail/edit surface MUST expose at most one visible emphasized primary header action.
- **FR-192-004 Contextual navigation rule**: Pure related-record navigation MUST leave the flat primary header lane on remediated standard pages and move into contextual placement outside the header.
- **FR-192-005 Secondary grouping rule**: Infrequent, administrative, or secondary actions MUST move into deliberate grouped secondary placement rather than remaining as peer buttons.
- **FR-192-006 Group-order rule**: Secondary grouped actions MUST remain internally ordered so navigation, routine mutation, external links, and danger do not become an undifferentiated junk drawer.
- **FR-192-007 Danger separation rule**: Destructive, irreversible, or governance-sensitive actions MUST remain visibly separated from safe routine actions and keep their existing confirmation behavior.
- **FR-192-008 Baseline profile hierarchy**: On BaselineProfile detail, `Capture baseline` MUST be the only visible primary action when no consumable snapshot exists, and `Compare now` MUST be the only visible primary action when a consumable snapshot exists. `View snapshot` and `Open compare matrix` MUST move to contextual placement outside the header, while `Compare assigned tenants` and `Edit` become secondary.
- **FR-192-009 Evidence snapshot hierarchy**: On EvidenceSnapshot detail, only one central next action MAY remain visible. `Open operation` and `View review pack` MUST move to contextual placement outside the header, and `Expire snapshot` MUST remain a separated lifecycle danger action.
- **FR-192-010 Finding exception hierarchy**: On FindingException detail, related navigation MUST move to contextual placement outside the header, `Renew exception` MAY be primary when renewal is valid, and `Revoke exception` MUST remain separated as a danger-governance action.
- **FR-192-011 Tenant review hierarchy**: On TenantReview detail, only one dominant lifecycle action MAY remain primary based on review state. Refresh, publish, export, and related navigation MUST no longer appear as a flat row of peer buttons; pure navigation moves to contextual placement outside the header, and archive remains secondary danger.
- **FR-192-012 Tenant edit discipline**: EditTenant MUST remain edit-first. Save/cancel remain the primary edit affordance, while `View` and related onboarding move to contextual placement outside the header and lifecycle actions stay secondary and structurally separated.
- **FR-192-013 Workflow-heavy exception contract**: The tenant admin resource view MUST be explicitly marked as a workflow-heavy special type. It MAY expose one visible primary action only when a clear next step dominates; otherwise its actions remain grouped with deliberate internal order.
- **FR-192-014 Minor-alignment review**: ViewProviderConnection and ViewFinding MUST be reviewed against the same discipline but changed only when a real header-noise issue exists.
- **FR-192-015 Reference preservation**: ViewBaselineSnapshot, ViewBackupSet, ViewReviewPack, ViewAlertDestination, ViewPolicyVersion, and the Workspace resource view MUST stay unchanged or receive only minimal alignment if they already satisfy the discipline.
- **FR-192-016 No body-layout expansion**: This feature MUST NOT force Spec 133 body-layout rollout onto simple view pages that are already structurally acceptable.
- **FR-192-017 No governance-friction expansion**: This feature MUST NOT widen confirmation depth, reason-capture rules, or provider-dispatch semantics beyond the behavior already owned by the underlying actions.
- **FR-192-018 Authorization continuity**: Moving, grouping, or relabeling actions MUST NOT change route scope, capability enforcement, deny-as-not-found behavior, or audit obligations.
- **FR-192-019 Vocabulary continuity**: Header labels, modal titles, notifications, and related helper copy MUST keep the same domain vocabulary when actions move between primary, contextual, and grouped placement.
- **FR-192-020 Regression guard**: The repo MUST add a lightweight project-wide guard that prevents new standard record pages from reintroducing multiple competing primary header actions, flat navigation-mutation mixes, or silent special-type exceptions.
- **FR-192-021 Browser verification**: Browser or UI smoke checks MUST cover all remediation-required pages, the explicit workflow-heavy exception, and a no-regression baseline over the compliant or no-op reference pages.

## Surface Decision Matrix

- **Remediation required**:
  - BaselineProfile detail
  - EvidenceSnapshot detail
  - FindingException detail
  - TenantReview detail
  - EditTenant
- **Workflow-heavy special-type exception**:
  - Tenant detail (tenant admin resource view)
- **Minor alignment only**:
  - ProviderConnection detail
  - Finding detail
- **Compliant / no-op reference**:
  - BaselineSnapshot detail
  - BackupSet detail
  - ReviewPack detail
  - AlertDestination detail
  - PolicyVersion detail
  - Workspace resource detail

## Target Outcomes by Key Surface

- **BaselineProfile detail**: The header presents one obvious next step. Snapshot and matrix navigation stop competing with compare or capture. Secondary compare variants and edit move into grouped secondary placement.
- **EvidenceSnapshot detail**: One next action stays visible. Run and review-pack navigation move to contextual placement outside the header. `Expire snapshot` remains clearly separated as lifecycle danger.
- **FindingException detail**: Governance lifecycle stops competing with related navigation. `Renew exception` and `Revoke exception` are no longer presented as flat equals.
- **TenantReview detail**: Review lifecycle becomes easier to scan. The page distinguishes viewing related outputs from refreshing, publishing, exporting, or archiving.
- **EditTenant**: The page reads as an edit surface first. View/context links move to contextual placement outside the header, and archive or restore stops competing with the edit task.
- **Tenant detail (tenant admin resource view)**: The page remains a workflow hub, but grouped header actions gain an explicit internal order separating external links, verification, setup, and lifecycle, while pure navigation moves into contextual placement outside the header.

## Non-Goals

- Creating a new global action framework for every surface class
- Cleaning up monitoring, queue, or workbench surfaces
- Hardening confirmation-depth, reason-capture, or danger-vocabulary policy
- Changing dispatch, preflight, provider-start, or other backend operation semantics
- Extending Spec 133 body composition to every view page by default
- Cosmetic flattening of already-clean pages for the sake of uniformity alone

## Assumptions

- Spec 133 remains a body-composition reference only and is not the rollout vehicle for this feature.
- Existing pages such as BaselineSnapshot detail and BackupSet detail remain valid internal reference patterns for calm record-page headers.
- Existing server-side authorization, audit, and run-observability behavior is already correct for the underlying actions and will be preserved as actions move.
- The tenant admin resource view is the only currently known page in this scope that deserves an explicit workflow-heavy exception rather than a standard-record cleanup.

## Dependencies

- HDR-001 in the constitution as the source rule for header action discipline
- Existing related-navigation and contextual-link helpers already used by several detail pages
- Existing Filament header action surfaces and `ActionGroup` patterns
- Existing browser and regression testing infrastructure for Filament surfaces

## Risks

- The cleanup could drift into a broader action-framework project if it is not kept strictly to classic record/detail/edit surfaces.
- A grouped secondary menu could become a junk drawer if internal order is not treated as part of the contract.
- Workflow-heavy pages could be flattened incorrectly if the exception rule is not explicit and narrow.
- Cosmetic overreach could create churn on already-compliant pages and dilute the value of the cleanup.

## Review Questions

- Does every remediated standard page now make the next likely step obvious?
- Has pure navigation moved closer to the content it belongs to instead of living in the primary header lane?
- Are rare and dangerous actions calmer without becoming hard to find?
- Is the tenant admin resource view clearly documented as a special type rather than a silent inconsistency?
- Have compliant reference pages been preserved instead of cosmetically rebuilt?

## 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 |
|---|---|---|---|---|---|---|---|---|---|---|
| BaselineProfile detail | `apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php` | `Capture baseline` or `Compare now` becomes the sole visible primary; `View snapshot` and `Open compare matrix` move to contextual placement outside the header, while `Compare assigned tenants` and `Edit` become grouped secondary actions | Existing resource inspect flow unchanged | Unchanged by this spec | none | unchanged | Flat multi-button header is removed; contextual navigation leaves the primary lane | n/a | Existing compare and capture run/audit behavior unchanged | Remediation-required standard record page |
| EvidenceSnapshot detail | `apps/platform/app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php` | One visible primary action only; `Open operation` and `View review pack` move to contextual placement outside the header; `Expire snapshot` remains separated danger | Existing resource inspect flow unchanged | Unchanged by this spec | none | unchanged | Header becomes `one next step + contextual links + separated danger` | n/a | Existing evidence refresh and expire behavior unchanged | Remediation-required standard record page |
| FindingException detail | `apps/platform/app/Filament/Resources/FindingExceptionResource/Pages/ViewFindingException.php` | `Renew exception` may be primary; `Open finding` and `Open approval queue` move to contextual placement outside the header; `Revoke exception` remains separated danger | Existing resource inspect flow unchanged | Unchanged by this spec | none | unchanged | Navigation and lifecycle actions are no longer flat peers | n/a | Existing exception-service audit behavior unchanged | Remediation-required standard record page |
| TenantReview detail | `apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php` | One of `Refresh review`, `Publish review`, or `Export executive pack` may be primary depending on state; `Open operation`, `View executive pack`, and `View evidence snapshot` move to contextual placement outside the header; `More` retains infrequent actions with `Archive review` separated as danger | Existing resource inspect flow unchanged | Unchanged by this spec | none | unchanged | Flat peer row of navigation plus lifecycle actions is removed | n/a | Existing review lifecycle and export behavior unchanged | Remediation-required standard record page |
| EditTenant | `apps/platform/app/Filament/Resources/TenantResource/Pages/EditTenant.php` | Header no longer carries `View` or related onboarding navigation; those move into contextual tenant-meta placement outside the header, while lifecycle actions remain grouped or separated and do not compete with the edit task | Existing resource edit entry unchanged | Unchanged by this spec | none | unchanged | Header no longer competes with form submission | Save and cancel remain the primary edit affordance | Existing tenant lifecycle audit behavior unchanged | Remediation-required edit surface |
| Tenant detail (tenant admin resource view) | `apps/platform/app/Filament/Resources/TenantResource/Pages/ViewTenant.php` | Existing grouped `Actions` menu stays for external links, verification, setup, and lifecycle work, while pure navigation moves to contextual placement outside the header; `Verify configuration` may be lifted only as a sole visible primary if clearly justified | Existing resource inspect flow unchanged | Unchanged by this spec | none | unchanged | No flat multi-button row is introduced to fake standardization | n/a | Existing tenant verification, RBAC refresh, and lifecycle audit behavior unchanged | Explicit workflow-heavy special-type exception |
| ProviderConnection detail | `apps/platform/app/Filament/Resources/ProviderConnectionResource/Pages/ViewProviderConnection.php` | Audit whether `Grant admin consent` and `Edit` should remain peers; dedicated override actions stay grouped under one managed secondary structure | Existing resource inspect flow unchanged | Unchanged by this spec | none | unchanged | Only minor cleanup if the header still reads as two competing primaries | n/a | Existing dedicated-override audit behavior unchanged | Minor alignment only |
| Finding detail | `apps/platform/app/Filament/Resources/FindingResource/Pages/ViewFinding.php` | `Back to origin`, `Open related record`, and `Open approval queue` remain contextual outside the header; workflow actions stay inside the existing governed group | Existing resource inspect flow unchanged | Unchanged by this spec | Existing list behavior unchanged | unchanged | Only adjust if flat navigation still competes with the workflow group | n/a | Existing workflow audit behavior unchanged | Minor alignment only |
| ReviewPack detail | `apps/platform/app/Filament/Resources/ReviewPackResource/Pages/ViewReviewPack.php` | `Download` remains the clear primary and `Regenerate` remains secondary | Existing resource inspect flow unchanged | Unchanged by this spec | none | unchanged | No structural header change expected | n/a | Existing review-pack generation behavior unchanged | Compliant / no-op reference |
| AlertDestination detail | `apps/platform/app/Filament/Resources/AlertDestinationResource/Pages/ViewAlertDestination.php` | `Send test message` stays primary and `View last delivery` stays secondary | Existing resource inspect flow unchanged | Unchanged by this spec | none | unchanged | No structural header change expected | n/a | Existing alert-test behavior unchanged | Compliant / no-op reference |
| PolicyVersion detail | `apps/platform/app/Filament/Resources/PolicyVersionResource/Pages/ViewPolicyVersion.php` | Existing calm related-record access remains contextual and needs no expansion in this feature | Existing resource inspect flow unchanged | Unchanged by this spec | none | unchanged | No structural header change expected | n/a | Read-only surface; no new audit behavior | Compliant / no-op reference |
| Workspace resource detail | `apps/platform/app/Filament/Resources/Workspaces/Pages/ViewWorkspace.php` | Single `Edit` action remains acceptable | Existing resource inspect flow unchanged | Unchanged by this spec | none | unchanged | No structural header change expected | n/a | Existing workspace-manage behavior unchanged | Compliant / no-op reference |
| BaselineSnapshot detail | `apps/platform/app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php` | Existing calm related-record access remains contextual and needs no expansion in this feature | Existing resource inspect flow unchanged | Unchanged by this spec | none | unchanged | No structural header change expected | n/a | Read-only surface; no new audit behavior | Compliant / no-op reference |
| BackupSet detail | `apps/platform/app/Filament/Resources/BackupSetResource/Pages/ViewBackupSet.php` | Existing `More` structure with grouped restore and delete lifecycle actions remains acceptable | Existing resource inspect flow unchanged | Unchanged by this spec | Existing list behavior unchanged | unchanged | No structural header change expected unless grouped ordering needs small tightening | n/a | Existing restore/delete audit behavior unchanged | Compliant / no-op reference |

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

- **Record Header Discipline**: The cross-page contract for standard record/detail/edit pages: one visible primary action, contextual navigation near content, grouped secondary actions, and separated danger.
- **Surface Classification Matrix**: The explicit catalog assigning each in-scope surface to remediation required, minor alignment only, compliant/no-op reference, or workflow-heavy special-type exception.
- **Special-Type Exception**: The explicit allowance for a workflow-heavy record page to stay grouped and internally ordered without pretending to be a standard single-next-step detail page.
- **Contextual Navigation Slot**: The related-context placement that keeps navigation near the summary or section it belongs to instead of in a flat primary header row.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-192-001**: In acceptance review and smoke coverage, 100% of remediation-required standard record/detail/edit pages show no more than one visible primary header action.
- **SC-192-002**: 100% of in-scope surfaces are explicitly classified in the spec and implementation notes, and no affected page remains an undocumented exception.
- **SC-192-003**: Every remediated standard page relocates at least one pure navigation action out of the flat primary header lane into contextual placement outside the header.
- **SC-192-004**: During acceptance walkthroughs, reviewers can identify the next likely step on each remediated standard page within 5 seconds without scanning more than one header action cluster.
- **SC-192-005**: No compliant or no-op reference page receives a structural header rebuild unless a documented minor-alignment finding exists, and smoke coverage confirms no regression on that reference set.
- **SC-192-006**: The tenant admin resource view remains explicitly marked as a workflow-heavy special type and passes review without reverting to a flat peer-button header row.

## Definition of Done

This feature is complete when:

- every in-scope record/detail/edit surface is classified explicitly,
- every remediated standard page shows at most one visible primary header action,
- contextual navigation has left the flat primary header lane on remediated standard pages,
- rare and administrative actions are grouped deliberately rather than left as peer buttons,
- destructive or governance-sensitive actions remain structurally separated,
- the tenant admin resource view is explicitly documented and treated as a workflow-heavy special type,
- compliant and no-op reference pages are preserved rather than cosmetically rebuilt,
- a lightweight regression guard exists for future record-page header changes,
- and browser smoke checks confirm the visible hierarchy on the remediated pages.

## Recommended Sequencing

- Spec 193 should handle monitoring and workbench action hierarchy, where different surface rules are needed.
- Spec 194 should handle governance-friction hardening, including confirmation depth, reason capture, and danger-language policy.