TenantAtlas/specs/199-global-context-shell-contract/spec.md

Feature Specification: Global Context Shell Contract

Feature Branch: 199-global-context-shell-contract
Created: 2026-04-18
Status: Proposed
Input: User description: "Spec 199 — Global Context Shell Contract"

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

• Problem: The admin and tenant shell currently derive active workspace and tenant scope from a mix of route input, query hints, panel tenant state, session-backed workspace context, remembered tenant values, and shell-local rendering logic instead of one explicit product contract.
• Today's failure: Operators and developers cannot reliably answer the same basic question across the shell: what scope is actually active, what a switch or clear flow will do, whether a deeplink is authoritative, and which fallback wins when context inputs disagree or become invalid.
• User-visible improvement: Operators see one clear workspace-first shell truth, one predictable tenant truth inside that workspace, explicit tenantless states, and consistent switch, clear, restore, and fallback behavior across shared shell surfaces.
• Smallest enterprise-capable version: Map the current context sources and shell entry points, define one resolved context contract for workspace and tenant, align the context bar and switch/clear flows to that contract, add focused regression coverage for resolution and fallback, and document what remains page-state or constitution work.
• Explicit non-goals: No page-level tab/filter/inspect-state contract, no generic Filament nativity cleanup, no global navigation or IA rewrite, no detail micro-UI redesign, no new generic context platform engine, and no product-wide authorization redesign beyond shell context visibility and enforcement boundaries.
• Permanent complexity imported: A bounded shell-context taxonomy, an explicit source-of-truth hierarchy, documented switch/select/clear/fallback rules, a shared shell vocabulary for workspace and tenant state, and focused regression tests around those rules.
• Why now: The repo already has multiple context sources and shared shell surfaces across /admin and /admin/t/{external_id}. Adjacent specs intentionally leave this global shell context layer unresolved, so additional work will keep reintroducing drift unless the contract is cut now.
• Why not local: Local fixes inside one partial, one controller, or one panel would reduce a symptom, but would keep competing truths alive and would not give operators or reviewers a single product contract for scope resolution.
• Approval class: Core Enterprise
• Red flags triggered: Cross-panel contract breadth and source-of-truth consolidation. Defense: the scope is tightly bounded to workspace and tenant shell truth, introduces no new persistence, and explicitly excludes broader navigation, page-state, and micro-UI cleanup work.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes:
  • /admin
  • /admin/choose-workspace
  • /admin/choose-tenant
  • /admin/switch-workspace
  • /admin/select-tenant
  • /admin/clear-tenant-context
  • /admin/t/{external_id}/...
  • Shared shell surfaces rendered on the admin and tenant panels
• Data Ownership:
  • This feature introduces no new tables, persisted entities, or storage truth.
  • It standardizes the shell contract that governs how workspace-owned context and tenant-owned scope visibility are resolved on existing surfaces.
  • Remembered workspace and tenant values remain convenience state only; they do not become independent product records.
• RBAC:
  • Workspace membership is required before a workspace can become the active shell context.
  • Tenant membership is required before a tenant can become the active tenant context.
  • Non-membership remains deny-as-not-found and capability checks inside an established scope remain server-side authorization concerns.

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: Workspace-level pages may opt into an explicit tenant prefilter, but the shell contract itself must never inject hidden page-local filters. Tenant-bound routes remain explicitly tenant-scoped.
• Explicit entitlement checks preventing cross-tenant leakage: Route, query, remembered, and switch requests must pass workspace and tenant entitlement checks before they become active shell context. Invalid or inaccessible context requests must be discarded without leaking unavailable tenant truth.

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Global context bar / shell header	Secondary Context Surface	Confirm or change current scope before navigating, reviewing, or mutating anything else	Active workspace, active tenant or explicit tenantless state, current shell scope, available switch affordance	Available workspaces, available tenants, and any intentionally surfaced recovery hint	Not primary because it frames decisions across the product rather than owning a domain-specific decision queue	Aligns /admin and /admin/t/{external_id} entry points around one scope model	Removes repeated “where am I?” reconstruction and hidden scope drift between pages
Context recovery shell state	Secondary Context Surface	Recover from missing, invalid, inaccessible, or incompatible context before work continues	Missing or invalid scope state, actual fallback scope, and the next required action	Optional explanation of why a requested or remembered context was discarded	Not primary because it is a recovery state of the shell contract, not a business workbench	Aligns missing-context behavior instead of letting each page improvise its own fallback	Prevents confusing half-active scope states and reduces retry-based navigation

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

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	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 / Justification
Global context bar / shell header	Navigation / Context / Shell	Global scope switcher	Confirm current scope or intentionally switch workspace or tenant	One inline shell context strip with one menu-driven switch model	forbidden	Inside the context controls only	none; tenant clear is a scope-reset action, not a data-destructive action	/admin and /admin/t/{external_id} shared shell	none	Active workspace, active tenant or No tenant selected, current panel scope	Context / workspace / tenant	The single resolved workspace and tenant truth governing the shell right now	none
Context recovery shell state	Navigation / Context / Recovery	Missing or invalid scope recovery	Choose a valid workspace, return to a workspace-level route, or clear invalid tenant context	One inline recovery state in the same shell contract	forbidden	Recovery controls inside the shell state only	none	/admin and /admin/t/{external_id} shared shell	none	Missing workspace, missing tenant, invalid request, incompatible tenant, inaccessible tenant	Context recovery	Why the requested scope cannot be honored and what valid scope remains	none

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

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Global context bar / shell header	Workspace operator, tenant operator	Confirm current scope and intentionally switch workspace or tenant	Shell context strip	Where am I operating right now, and can I safely change scope?	Active workspace, active tenant or explicit tenantless state, current panel scope, switch affordances	Why a requested context was ignored, which remembered value was eligible, and any compatibility note that must stay secondary	workspace presence, tenant presence, validity, source resolution	context only	Switch workspace, Select tenant, Clear tenant context	none
Context recovery shell state	Workspace operator, tenant operator	Recover from missing, invalid, inaccessible, or incompatible context	Shell recovery prompt	Why is this scope unavailable, and what is the valid next step?	Missing or invalid state, current fallback scope, next valid action	Discarded request reason and any intentionally surfaced restore candidate	missing, invalid, inaccessible, incompatible, tenantless	context only	Choose workspace, Return to workspace-level page, Clear tenant request	none

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: yes
• New persisted entity/table/artifact?: no
• New abstraction?: no
• New enum/state/reason family?: yes
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: Operators and reviewers face multiple competing answers for current scope, fallback, and restore behavior, so shell context cannot be trusted as a single product truth.
• Existing structure is insufficient because: The current shell can derive active context from route input, query hints, session state, panel state, and remembered values. Local cleanup in one place cannot define one shared switch, clear, restore, and fallback contract across panels.
• Narrowest correct implementation: Define one resolved shell-context contract over existing workspace and tenant context behavior, explicitly classify requested, remembered, resolved, tenantless, and invalid states, and align current shell surfaces and entry flows to it without new persistence or a generic engine.
• Ownership cost: The repo gains one source hierarchy to maintain, one shared shell vocabulary to preserve, and focused feature tests for context resolution, switch, clear, restore, and invalid-state handling.
• Alternative intentionally rejected: Local partial-only cleanup was rejected because it would preserve competing truths. A broader generic multi-panel context framework was rejected because it would import unnecessary abstraction for a bounded shell problem.
• Release truth: current-release operator truth and shell reliability

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Unit + Feature
• Validation lane(s): fast-feedback, confidence
• Why this classification and these lanes are sufficient: The change spans two proving purposes: unit tests for canonical source precedence, remembered-context invalidation, and page-category decisions in the support layer, plus feature tests for controller flows, middleware behavior, route recovery, and shared shell rendering. Together they prove runtime behavior without escalating to browser or heavy-governance lanes by default.
• New or expanded test families: Focused unit shell-context resolution tests, workspace-switch and tenant-selection controller tests, explicit workspace-chooser exception tests, and shared-shell display tests for admin and tenant panel entry paths.
• Fixture / helper cost impact: Minimal workspace, tenant, membership, entitlement, session, and remembered-context setup. No new providers, seeds, heavy browser harness, or long-running runtime fixtures are required.
• Heavy-family visibility / justification: none
• Reviewer handoff: Reviewers must confirm that coverage remains feature-level, that shell rendering is not accidentally pushed into a broad browser family, that invalid-context fallbacks are proven, and that the minimal commands below are enough to verify the contract.
• Budget / baseline / trend impact: Minor increase in focused feature-test runtime only.
• Escalation needed: none
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=GlobalContext
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=WorkspaceSwitch
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=TenantContext

User Scenarios & Testing (mandatory)

User Story 1 - See The True Current Scope (Priority: P1)

As an operator, I want every shared shell surface to show the real active workspace and tenant state so I can trust where my next action will apply.

Why this priority: If the shell cannot answer the active scope question clearly, every downstream page remains harder to trust.

Independent Test: Open workspace-level and tenant-bound entry paths with valid and tenantless scenarios, then verify that the shell always shows the same resolved scope truth the target page is using.

Acceptance Scenarios:

1. Given a valid workspace and tenant context are active, When the shell renders on a shared admin or tenant panel surface, Then it shows that resolved workspace and tenant consistently.
2. Given a workspace-level page is active with no tenant selected, When the shell renders, Then it shows an explicit tenantless state instead of implying that a hidden tenant is still active.

---

User Story 2 - Switch Workspace Without Stale Tenant Truth (Priority: P1)

As an operator, I want workspace switching to deterministically resolve what happens to tenant context so I do not carry a stale tenant into the wrong workspace or page.

Why this priority: Workspace is the primary scope. If workspace switching is ambiguous, the entire workspace-first model breaks down.

Independent Test: Start from a valid workspace and tenant, switch to a different workspace with compatible and incompatible tenant conditions, and verify the resulting scope, fallback, and destination page.

Acceptance Scenarios:

1. Given an operator switches to a different workspace and the prior tenant is not valid in that workspace, When the switch resolves, Then the shell clears tenant context and lands in a valid workspace-scoped state.
2. Given an operator switches to a workspace where a requested or remembered tenant is valid and allowed for the target surface, When the switch resolves, Then that tenant becomes active only after validation within the new workspace.

---

User Story 3 - Select Or Clear Tenant Intentionally (Priority: P1)

As an operator, I want tenant selection and tenant clearing to behave like explicit scope decisions so I always understand whether I am entering tenant scope or returning to workspace-only scope.

Why this priority: Tenant is secondary but operationally critical. The select and clear flows are the most visible scope-changing actions in the shell.

Independent Test: Select a tenant from the shell, clear it from a workspace-level page, and clear it from a tenant-bound route to verify that the resulting shell truth and destination are deterministic.

Acceptance Scenarios:

1. Given an operator selects a valid tenant inside the active workspace, When the shell resolves the selection, Then the active tenant becomes that tenant and the shell shows the same tenant on the target page.
2. Given an operator clears tenant context while on a tenant-required route, When the clear flow resolves, Then the system redirects to the documented workspace-level fallback and the shell shows no active tenant.

---

User Story 4 - Reject Invalid Or Stale Context Cleanly (Priority: P1)

As an operator, I want invalid, inaccessible, or stale requested and remembered context to fail cleanly so I do not operate under a false scope illusion.

Why this priority: Invalid context handling is where competing truths most often become visible and dangerous.

Independent Test: Enter the shell with invalid route, query, and remembered context combinations, then verify that the shell discards invalid inputs, lands in a valid fallback state, and never leaves stale scope indicators behind.

Acceptance Scenarios:

1. Given a route or query requests a tenant that does not belong to the resolved workspace, When the shell resolves context, Then that tenant request is rejected and the shell falls back to a valid workspace-scoped state.
2. Given a remembered tenant is no longer accessible or compatible, When the shell restores context, Then the remembered tenant is ignored and the operator sees an explicit valid fallback state.

---

User Story 5 - Keep Shared Shell Logic Consistent Across Panels (Priority: P2)

As a reviewer, I want admin and tenant panel entry paths that share the shell contract to resolve context by the same rules so extensions do not create panel-specific truths.

Why this priority: The main risk is drift between shared shell surfaces and panel-specific context assumptions.

Independent Test: Resolve the same entitled workspace and tenant scenario through the workspace-level shell and tenant-bound shell entry paths, then verify that both surfaces display the same active truth and compatible fallback behavior.

Acceptance Scenarios:

1. Given the same workspace and tenant are active through different valid entry paths, When the shared shell renders, Then both panels show the same resolved scope truth.
2. Given a panel-specific context source disagrees with the resolved shell contract, When the shell renders, Then the panel-specific source is treated as supporting data only and does not become a competing visible truth.

Edge Cases

• A route or query requests a tenant that belongs to a different workspace than the resolved workspace.
• Session-backed workspace state and requested workspace state disagree on first load.
• A remembered tenant exists for the prior workspace but not for the newly selected workspace.
• A tenant is cleared while the current page requires tenant scope.
• The explicit workspace chooser route is entered without workspace context and must not be mistaken for a generic missing-workspace error.
• A tenant becomes inaccessible between selection and the next request.
• A shell recovery state must distinguish between missing workspace, missing tenant, invalid tenant, and inaccessible tenant.
• Shared shell display and underlying page behavior disagree unless one explicit contract prevents the drift.

Requirements (mandatory)

Constitution alignment (required): This feature introduces no new Microsoft Graph calls, no new persistent storage, and no new queued or scheduled operational workflow. It standardizes shell context resolution, display, and context-changing flows on existing surfaces.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): This feature introduces one bounded source-of-truth hierarchy and one bounded state taxonomy for global shell context. It does not introduce new persistence or a generic context framework. The proportionality review above explains why local cleanup is insufficient and why broader abstraction is rejected.

Constitution alignment (TEST-GOV-001): This feature changes runtime behavior and targeted tests. The proving purpose is feature-level validation of shell resolution, switch, clear, restore, and fallback behavior. The narrowest sufficient lanes are fast-feedback and confidence. No new browser or heavy-governance family is justified, fixture cost remains limited to workspace, tenant, membership, and session state, and reviewers must treat accidental escalation beyond those bounds as a merge blocker.

Constitution alignment (OPS-UX): Existing OperationRun behavior remains unchanged. The feature does not create or rename run types, change service-owned run transitions, or alter progress or notification contracts.

Constitution alignment (RBAC-UX): The feature affects workspace-context routes on /admin, tenant-context routes on /admin/t/{external_id}, and shared shell context display. Non-members remain deny-as-not-found. Members without required capability remain authorization failures only after workspace and tenant entitlement are established. Context resolution must never surface inaccessible workspace or tenant truth, and global search must remain tenant-safe under the resolved shell contract. Positive and negative authorization regression coverage must prove that shell cleanup does not relax these rules.

Constitution alignment (OPS-EX-AUTH-001): Not applicable. The feature does not add synchronous authentication-handshake behavior.

Constitution alignment (BADGE-001): The feature does not introduce a new badge language. Existing status and severity badges remain centrally defined and must not be remapped ad hoc as part of the shell-context work.

Constitution alignment (UI-FIL-001): The feature must rely on existing panel shell surfaces, native Filament controls, and shared shell primitives already used by the repo. It must not introduce a new local status language or a second context widget family beside the shared shell contract.

Constitution alignment (UI-NAMING-001): Operator vocabulary must stay domain-first and consistent across shell labels, action labels, notifications, and recovery copy. Canonical terms include Workspace, Tenant, No tenant selected, Switch workspace, Select tenant, Clear tenant context, and Context unavailable.

Constitution alignment (DECIDE-001): The affected shell surfaces are secondary context surfaces. They exist to make the next operator decision trustworthy by showing current scope and offering explicit scope changes, not by becoming a separate workbench.

Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001): The shared shell must expose one primary context display and switch model, one recovery model, explicit placement of scope-reset actions, and one canonical vocabulary for workspace and tenant truth. It must avoid competing header, modal, or partial-owned context truths.

Constitution alignment (ACTSURF-001 - action hierarchy): Context display, scope selection, and scope recovery must remain separated from destructive data actions and from unrelated page-local actions. Tenant clear remains a context-reset action grouped with tenant controls, not a destructive record action.

Constitution alignment (OPSURF-001): Default-visible shell content must stay operator-first: active workspace, tenant state, validity, and the next valid context action. Any diagnostic explanation of discarded requests or remembered candidates must stay secondary and only appear where necessary.

Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001): The feature replaces competing shell truth with one resolved context model and a bounded state vocabulary. It must not add redundant presenter or explanation layers, and tests must focus on visible outcomes such as displayed scope, redirects, clears, and invalid-state fallback.

Constitution alignment (Filament Action Surfaces): The Action Surface Contract is satisfied when the shared shell uses exactly one resolved context source for display, uses the same contract for switch, select, and clear flows, and avoids redundant alternate context widgets or empty grouped action placeholders. The UI Action Matrix below documents the shell surfaces.

Constitution alignment (UX-001 — Layout & Information Architecture): This feature changes shell context behavior, not page form architecture. Shared shell surfaces must remain calm, concise, and explicit, and missing-context recovery must not overload the header with unrelated information.

Global Context Taxonomy

• Requested Context: Workspace or tenant input requested by route, query, explicit switch/select action, or other documented entry path before validation.
• Resolved Workspace Context: The one validated workspace scope that the shell and workspace-bound pages consume.
• Resolved Tenant Context: The one validated tenant scope inside the resolved workspace, or the explicit tenantless state when no tenant is active.
• Remembered Context: Non-leading convenience state used only as a restore candidate after validation.
• Invalid / Unavailable Context: Requested or remembered workspace or tenant input that cannot be honored because it is missing, inaccessible, incompatible, or no longer valid.
• Tenantless Workspace State: A valid workspace-scoped state where no tenant is active and the shell must say so explicitly.

Context Source Hierarchy

Context facet	Leading source	Supporting sources	Never-leading sources
Active workspace	Valid requested workspace for the current entry flow, otherwise the validated current workspace state	Remembered last workspace only when there is no active session workspace and the restore rule explicitly allows it	View-local fallbacks, raw query hints outside documented flows, raw tenant-panel state
Active tenant	Valid tenant required by the current route or explicitly selected by the operator inside the resolved workspace	Query-backed tenant hints only on explicitly allowed workspace-scoped routes after validation, then remembered tenant for the resolved workspace only when no higher-priority tenant is active and the target surface allows restore	Tenant from a different workspace, stale remembered tenant, partial-local shell state, raw panel tenant state treated as an independent truth
Shell display	The resolved context model only	none	Any partial-owned inference, convenience hint, or stale page-local context that is not part of the resolved context

Context Source Inventory Ownership

• The canonical inventory of in-scope workspace and tenant context sources is maintained in data-model.md under Context Source Inventory.
• Any new source that can influence shell context must be added there with its source role, owning seam, and validation note before implementation or cleanup work lands.

Context Flow Summary

Flow	Trigger	Required validation	Allowed outcome	Forbidden outcome
Workspace switch	Explicit shell action	Workspace entitlement, route compatibility, tenant compatibility re-evaluation	Resolved target workspace with valid tenant or explicit tenantless state	Carrying an incompatible tenant silently into the new workspace
Tenant select	Explicit shell action or required tenant entry route	Tenant entitlement, membership in resolved workspace, route compatibility	Resolved tenant inside the active workspace	Tenant becoming active without a valid workspace or despite incompatibility
Tenant clear	Explicit shell action	Current route compatibility with tenantless state	Valid tenantless workspace state or redirect to workspace-level fallback	Remaining on a tenant-required route with no valid tenant
Restore	First load or eligible return flow	Restore rule, workspace compatibility, tenant compatibility, entitlement	Valid restored workspace or tenant context	Remembered context overriding an explicit current truth or reviving invalid scope
Invalid-context recovery	Any invalid request or stale remembered state	Missing, inaccessible, incompatible, or unauthorized determination	Clear fallback state and explicit recovery path	Hidden failure or stale shell scope display

Documented Workspace-Safe Fallbacks

Situation	Required fallback
External previous URL, missing referrer, or clear-flow sentinel path	/admin/operations via admin.operations.index
Missing or unrecoverable workspace truth at shell entry or restore time	/admin/choose-workspace
Tenant-bound route under /admin/t/{external_id}/... or /admin/tenants/... with a valid current workspace	admin.workspace.managed-tenants.index for the current workspace
Tenant-bound route cleanup after workspace truth is no longer available	/admin via admin.home
Tenant-scoped evidence path under /admin/evidence/... except /admin/evidence/overview	/admin/evidence/overview via admin.evidence.overview
Workspace-scoped route that is tenantless-capable	Remain on the same route in explicit tenantless state
Canonical workspace record viewer under /admin/operations/{run} with valid entitlement	Remain on the same viewer route in explicit tenantless or tenant-scoped state, whichever the resolved contract allows

Explicit Page-Category Exceptions

• /admin/choose-workspace is the explicit workspace_chooser_exception route. It remains reachable without an established workspace and must not be inferred from generic missing-workspace behavior.
• Tenant-scoped evidence paths under /admin/evidence/... except /admin/evidence/overview are explicit tenant_scoped_evidence routes for recovery purposes and must fall back to admin.evidence.overview.

Documented Workspace Switch Destinations

Switch outcome	Destination
Safe intended return inside /admin...	Intended URL wins when still valid for the resolved workspace
Resolved workspace with zero selectable tenants	admin.workspace.managed-tenants.index
Resolved workspace with multiple selectable tenants	/admin/choose-tenant
Resolved workspace with exactly one selectable tenant	Tenant dashboard route under /admin/t/{external_id}

Assumptions and Dependencies

• The product remains workspace-first: workspace context is the primary shell scope and tenant context stays subordinate to it.
• Existing admin and tenant panels continue to share shell-level context surfaces rather than splitting into unrelated context systems.
• Existing entitlement checks for workspace membership and tenant membership remain the security boundary the shell contract must respect.
• Current-release workspace-independent exception coverage is limited to the workspace chooser flow; it must stay explicit and must not be inferred from a generic missing-workspace failure path.
• Page-level tab, filter, inspect, and draft/apply semantics remain governed by the separate monitoring page-state contract unless this spec explicitly takes ownership.

Functional Requirements

• FR-199-001 Source inventory: The product MUST maintain one explicit inventory of all workspace and tenant context sources that can affect the shared shell contract, and that inventory MUST remain the canonical feature artifact for source roles and ownership.
• FR-199-002 Single resolved truth: The shell MUST expose exactly one resolved workspace truth and exactly one resolved tenant truth for each request.
• FR-199-003 Workspace primacy: Workspace MUST remain the primary shell scope for the product.
• FR-199-004 Tenant dependency: Tenant context MUST never remain active without a valid resolved workspace.
• FR-199-005 Source-role declaration: Every context source in scope MUST be classified as leading, supporting, or never-leading.
• FR-199-006 Requested-context validation: Requested context from route, query, or explicit switch/select flows MUST be validated before it becomes active shell context.
• FR-199-007 Query-role discipline: Query-based context hints MUST only participate when their role is explicitly defined by the contract.
• FR-199-008 Remembered-context role: Remembered or last-used values MUST remain supporting restore candidates only.
• FR-199-009 Remembered-context precedence: Remembered context MUST NEVER outrank a valid route request, explicit operator selection, or already resolved current-request truth.
• FR-199-010 Workspace switch contract: Workspace switching MUST define the resulting tenant outcome, route compatibility outcome, and fallback behavior.
• FR-199-011 Tenant re-evaluation on workspace switch: When workspace changes, existing tenant context MUST be re-evaluated against the target workspace before it may remain active.
• FR-199-012 Tenant select contract: Tenant selection MUST only activate a tenant inside the currently resolved workspace and only after the route's selector-operability check succeeds.
• FR-199-013 Tenant clear contract: Tenant clear MUST be an explicit operator flow with deterministic resulting scope and redirect behavior.
• FR-199-014 Tenant-required fallback: Clearing or losing tenant context on a tenant-required route MUST redirect to a documented workspace-level fallback.
• FR-199-015 Tenantless validity: Workspace-level pages may operate without an active tenant only when they are explicitly defined as tenantless-capable.
• FR-199-016 Workspace-required validity: Workspace-bound pages MUST NOT behave as valid without a resolved workspace.
• FR-199-017 Workspace-independent exception discipline: If a route is workspace-independent, that exception MUST be explicit and MUST NOT be inferred from missing context.
• FR-199-018 Distinct invalid-state handling: Missing workspace, missing tenant, invalid tenant, inaccessible tenant, and incompatible tenant MUST be distinguishable in contract behavior where they imply different operator recovery paths.
• FR-199-019 Visible scope parity: Any workspace or tenant scope shown in the shell MUST match the scope actually governing the current request.
• FR-199-020 Context-bar derivation: The context bar MUST derive its display and affordances only from resolved shell context and MUST NOT keep a second implicit context model.
• FR-199-021 Shared entry-rule consistency: Shell entry through direct navigation, route-bound tenant context, query-backed request context, switch flows, and restore flows MUST use the same resolution rules.
• FR-199-022 Page-state separation: Global shell context MUST remain distinct from local page-state such as tabs, filters, inspect state, and draft/apply behavior.
• FR-199-023 Redirect consistency: Redirect and return behavior after switch, clear, or invalid-context recovery MUST be deterministic and documented.
• FR-199-024 Restore entry discipline: Restore behavior MUST explicitly define which entry flows may consult remembered workspace and tenant values and when restore is skipped.
• FR-199-025 Invalid remembered-state cleanup: Invalid remembered workspace or tenant context MUST be discarded from support state cleanly and MUST NOT revive stale shell truth.
• FR-199-026 Panel consistency: Relevant admin and tenant panel shell surfaces that share the contract MUST resolve and display context by the same rules.
• FR-199-027 Supporting-state boundaries: Raw panel tenant state, session convenience data, and view-local shell logic MAY support resolution but MUST NOT become independent active truth.
• FR-199-028 Workspace and tenant compatibility: Tenant context MUST always remain compatible with the resolved workspace and the current route type.
• FR-199-029 Explicit tenantless display: When no tenant is active, the shell MUST show an explicit tenantless state rather than implying remembered or hidden tenant scope.
• FR-199-030 Recovery visibility: Invalid or missing context recovery MUST provide a clear next action and MUST not strand operators in an ambiguous half-context state.
• FR-199-031 Global search safety: Shell-context resolution MUST preserve tenant-safe and workspace-safe search behavior so inaccessible tenant-owned results never become visible through context drift.
• FR-199-032 No partial-owned authority: Partial-local rendering logic MAY format resolved context, but it MUST NOT own precedence, validation, or recovery decisions.
• FR-199-033 Regression coverage: Automated tests MUST cover context resolution, workspace switch, tenant select, tenant clear, restore behavior, invalid-context handling, and shell display consistency.
• FR-199-034 Manual shell smoke checks: Manual smoke checks MUST confirm that operators can understand scope, switch scope, clear tenant context, and recover from invalid context without hidden state.
• FR-199-035 Closure documentation: Final documentation MUST record the source hierarchy, allowed switch/select/clear/restore rules, fallback behavior, and what remains out of scope for page-state or constitution specs.
• FR-199-036 No navigation rewrite: The implementation MUST standardize shell context truth without turning this feature into a general navigation or information-architecture rewrite.

Non-Goals

• Standardizing page-level tabs, filters, inspect state, or draft/apply semantics that belong to the page-state contract.
• Redesigning shared detail micro-UI families or generic header action patterns outside shell-context needs.
• Rewriting product information architecture beyond what is required to make shell context truthful.
• Creating a generic shell platform, universal context engine, or speculative cross-product abstraction.
• Treating tenant as a globally independent truth outside the workspace-first model.

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
Global context bar / shell hook	Shared topbar shell surface on admin and tenant panels	Switch workspace, Select tenant, Clear tenant context	none	none	none	Choose workspace or Select tenant only when the contract requires recovery	none	n/a	no	Context actions change shell scope only. They must use one resolved context contract and must not introduce a second widget-owned truth.
Context recovery shell state	Shared shell recovery state	Choose workspace, Return to workspace scope, Clear invalid tenant request	none	none	none	Same recovery actions only	none	n/a	no	Recovery is a shell-state correction, not a record workflow. No destructive record action is introduced.

Key Entities (include if feature involves data)

• Requested Context: A requested workspace or tenant scope supplied by route, query, explicit switch/select action, or another documented entry path before validation.
• Resolved Context: The one validated shell truth consumed by the shared shell and the current page, composed of a resolved workspace and a resolved tenant or explicit tenantless state.
• Remembered Context: A non-leading convenience candidate representing last-used workspace or tenant values that may be considered for restore under documented rules.
• Invalid / Unavailable Context: Requested or remembered context that cannot be honored because it is missing, inaccessible, incompatible, or no longer valid.
• Tenantless Workspace State: A valid shell state in which a workspace is active but no tenant is active.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: In validation scenarios, operators can identify the active workspace and tenant or tenantless state from the shared shell within 3 seconds on all in-scope entry paths.
• SC-002: 100% of documented workspace-switch, tenant-select, tenant-clear, and invalid-context scenarios land in one valid resolved scope that matches what the shell displays.
• SC-003: 100% of tested invalid, inaccessible, or incompatible requested and remembered context scenarios fall back without leaving stale workspace or tenant indicators behind.
• SC-004: Shared admin-panel and tenant-panel shell entry paths show the same resolved scope truth for the same entitled scenario during validation.
• SC-005: Manual smoke validation confirms that operators never need trial-and-error navigation to understand whether they are in workspace-only or tenant scope on the covered shell flows.