TenantAtlas/specs/285-workspace-rbac-environment-access/spec.md

Feature Specification: Workspace-first RBAC & Environment Access Scoping

Feature Branch: 285-workspace-rbac-environment-access
Created: 2026-05-09
Status: Blocked by external prerequisites
Input: User description: "Follow instructions in #prompt:SKILL.md with these arguments: mit 285 weitermachen"

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

• Problem: Repo truth already has workspace memberships, managed-environment memberships, a workspace capability resolver, and a tenant capability resolver, but authorization still depends on two parallel role-bearing truths. Operators can be valid workspace members while environment visibility, Filament tenant selection, provider-connection access, run drilldowns, and governance surfaces still hinge on separate ManagedEnvironmentMembership rows and a second capability map.
• Today's failure: access semantics are not consistently workspace-first. WorkspaceContext, User::getTenants(), ProviderConnectionPolicy, OperationRunPolicy, FindingPolicy, EvidenceSnapshotPolicy, ReviewPackPolicy, and TenantReviewPolicy all mix workspace membership, environment membership, and capability checks differently. That makes deny-as-not-found behavior harder to reason about, duplicates role administration, and blocks a calm future role model such as Workspace Admin versus Customer Viewer because role truth is split before customer-safe roles even exist.
• User-visible improvement: operators manage role-bearing access once at workspace level, environment visibility becomes an explicit secondary scope instead of a second hidden RBAC core, and tenant-owned pages, provider connections, run drilldowns, evidence, findings, and governance review surfaces all follow the same 404 versus 403 rules.
• Smallest enterprise-capable version: keep workspace_memberships as the only role-bearing access truth, replace role-bearing ManagedEnvironmentMembership semantics with a narrow optional managed-environment access-scope overlay, retarget CapabilityResolver, User::canAccessTenant(), WorkspaceContext, and the key environment-owned policies to evaluate workspace role first and environment scope second, and migrate the current tenant-membership management surface so it no longer edits a second role family.
• Explicit non-goals: no /system plane RBAC redesign, no full customer-portal RBAC migration, no mandatory environment-level ACL product, no per-environment role matrix, no new role-productization surface, no provider-capability registry work from Spec 283, no source-taxonomy work from Spec 284, no copy/localization neutralization from Spec 286, no no-legacy guardrail pack from Spec 287, and no compatibility shim or dual-write path.
• Permanent complexity imported: one unified workspace-first access-resolution path, one narrow optional managed-environment scope overlay contract, targeted policy rewiring, a migration of the current tenant-membership UI into workspace-role management plus environment-scope management, and focused unit, feature, and browser proof. No new role family and no new independent persisted source of truth are added.
• Why now: Specs 279 through 283 reserve the workspace-first cutover pack specifically so workspace context, provider-neutral identity, and provider capability truth do not sit on top of tenant-first authorization. Without 285, the route shell and provider boundary work still rest on a dual RBAC core that keeps the product Microsoft- and tenant-shaped in its access semantics.
• Why not local: a local policy patch or one-off page helper would leave User, WorkspaceContext, CapabilityResolver, OperationRunPolicy, relation managers, and onboarding or provider surfaces inconsistent. The drift is structural and already spans models, policies, Filament navigation, and tests.
• Approval class: Core Enterprise
• Red flags triggered: authorization source-of-truth change, cross-cutting policy retargeting, and semantic replacement of an existing role-bearing model. Defense: the repo already carries both workspace and managed-environment role truths. Canonical replacement is safer and narrower than keeping them synchronized through more compatibility logic.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 1 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 2 | Gesamt: 10/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes:
  • /admin/workspaces
  • /admin/workspaces/{record}
  • /admin/provider-connections
  • named onboarding routes admin.onboarding and admin.onboarding.draft
  • current admin-panel managed-environment selection and tenant-owned routes used by Finding, EvidenceSnapshot, ReviewPack, TenantReview, and OperationRun drilldowns, regardless of whether the shell is still the current tenant-context route family or the prepared workspace-first route family from Spec 280
  • TenantResource membership and related-access surfaces that currently expose managed-environment membership CRUD
• Data Ownership:
  • workspace_memberships remain the workspace-owned, role-bearing source of truth
  • the current managed_environment_memberships persistence becomes a narrow managed-environment access-scope overlay or is replaced in-place by its workspace-first successor; it must not remain a second role-bearing truth
  • ManagedEnvironment, ProviderConnection, Finding, EvidenceSnapshot, ReviewPack, and TenantReview remain managed-environment-owned records anchored by workspace_id plus managed_environment_id
  • OperationRun continues to support both workspace-bound records anchored by workspace_id alone and managed-environment-bound records anchored by workspace_id plus optional managed_environment_id
• RBAC:
  • workspace membership is the first entitlement boundary
  • managed-environment access scope is an optional narrowing boundary, not a second independent role authority
  • capability checks for managed-environment-owned resources continue to use the existing capability registry, but role resolution must come from workspace membership rather than environment membership
  • non-members or out-of-scope actors stay 404; in-scope members missing a required capability stay 403

Cross-Cutting / Shared Pattern Reuse

• Cross-cutting feature?: yes
• Interaction class(es): navigation entry points, context selection, relation-manager membership management, cross-resource authorization, run drilldowns, and shared policy enforcement
• Systems touched: WorkspaceContext, User::managedEnvironments(), User::getTenants(), User::canAccessTenant(), WorkspaceCapabilityResolver, CapabilityResolver, TenantMembershipManager, WorkspaceMembershipManager, OperationRunCapabilityResolver, key environment-owned policies, ManageTenantMemberships, TenantMembershipsRelationManager, workspace membership relation managers, and shared UiEnforcement paths that depend on capability outcomes
• Existing pattern(s) to extend: workspace membership resolution, current capability resolver caching, shared deny-as-not-found policy pattern, existing workspace membership management, and existing action-surface enforcement for membership CRUD
• Shared contract / presenter / builder / renderer to reuse: WorkspaceCapabilityResolver, CapabilityResolver as the current managed-environment capability entry point, WorkspaceContext, OperationRunCapabilityResolver, UiEnforcement, WorkspaceMembershipManager, and the existing Filament relation-manager contract family
• Why the existing shared path is sufficient or insufficient: the repo already has the right core seams, but they currently stop at workspace-only or environment-only access decisions. The feature should converge them into one shared workspace-first access contract instead of introducing a third resolver stack.
• Allowed deviation and why: none. Any temporary compatibility alias, duplicate manager, or page-local access resolver would extend the drift this slice is meant to remove.
• Consistency impact: workspace chooser, managed-environment selection, provider-connections access, environment-owned resource policies, and membership-management surfaces must all derive access from the same workspace-first contract before provider capability or operability checks add deeper gating.
• Review focus: reviewers must verify that no role-bearing ManagedEnvironmentMembership path survives in policies or Filament gates, that workspace membership becomes the only role authority, and that environment scope is modeled as narrowing rather than as a second full RBAC system.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes
• Shared OperationRun UX contract/layer reused: OperationRunCapabilityResolver, OperationRunPolicy, ProviderOperationStartGate, and the existing OperationRunService lifecycle path
• Delegated start/completion UX behaviors: run viewability, required capability lookups, workspace-versus-environment entitlement resolution, and provider-capability follow-through stay delegated to the shared run authorization seams
• Local surface-owned behavior that remains: start surfaces keep only initiation inputs and the existing Open operation or drilldown affordances; this slice changes the access contract they rely on
• Queued DB-notification policy: N/A
• Terminal notification path: existing central lifecycle mechanism
• Exception required?: none

Provider Boundary / Platform Core Check

N/A - no shared provider/platform boundary is redefined in this slice. The feature consumes provider-neutral capability outcomes from Spec 283 as downstream inputs only.

UI / Surface Guardrail Impact

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Workspace membership management	yes	Native Filament resource relation manager	role-bearing membership CRUD, audit-safe owner guards	page, relation manager, modal	no	becomes the only role-management surface
Managed-environment access-scope management (retargeted from current tenant membership surface)	yes	Native Filament relation manager plus existing page shell	optional environment narrowing, selection visibility, drilldown continuity	page, relation manager, modal	no	must stop acting like a second role editor
Shared managed-environment selection and tenant-owned page access	yes	Mixed shared shell plus existing native pages	context selection, 404/403 semantics, route continuity, run drilldowns	shell, page, remembered context, URL-query	no	workflow guardrail change more than layout change

Decision-First Surface Role

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
Workspace membership management	Primary Decision Surface	Decide which workspace role a user should hold	member, role, and last-owner guard status	audit trail and historical change detail	Primary because this is the canonical role-bearing authority after the cutover	Matches workspace-first SaaS administration	removes duplicate role assignment across workspace and environment surfaces
Managed-environment access-scope management	Secondary Context Surface	Decide whether a workspace member should be narrowed to a subset of environments	whether access inherits workspace-wide or is explicitly narrowed	exact scoped environments and audit history	Secondary because it narrows visibility after the main workspace role decision	Keeps environment scope subordinate to workspace role truth	avoids forcing operators to reason about two different role systems
Shared managed-environment selection and tenant-owned page access	Primary Decision Surface	Decide whether the current environment is accessible and what next page can be opened safely	current workspace, selected environment, access-denied routing, one next valid destination	deeper diagnostics, provider capability blockers, and operability detail	Primary because operators feel the cutover first through context selection and page access	Follows the existing admin shell and drilldown workflow	reduces surprise 404/403 drift between pages and runs

Audience-Aware Disclosure

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
Workspace membership management	operator-MSP, support-platform	member, role, allowed management actions, owner-guard status	audit detail, membership source, history	raw model identifiers	Change role or Add member	raw IDs and low-level audit context stay secondary	workspace role is shown once as the canonical authority
Managed-environment access-scope management	operator-MSP, support-platform	whether access inherits workspace-wide or is explicitly scoped, plus the scoped environments	who is scoped where, why, and audit history	raw pivot identifiers and debug metadata	Manage access scope	raw pivot data stays hidden	the page explains environment narrowing once and does not repeat workspace role meaning
Shared managed-environment selection and tenant-owned page access	operator-MSP, support-platform	selected workspace, selected environment, and whether access is allowed	scoped-access reasons, provider capability or operability follow-up	raw policy internals and debug payloads	Open environment or Return to workspace	debug semantics stay out of default-visible UI	access denial is explained through one shared contract before deeper diagnostics appear

UI/UX Surface Classification

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
Workspace membership management	List / Detail / Settings	CRUD / Relation-first Resource	add member or change role	inline relation-manager management	forbidden	grouped relation actions only	grouped destructive actions with confirmation	workspace detail memberships relation	same workspace detail page	workspace context	Workspace member	canonical role-bearing access	none
Managed-environment access-scope management	List / Detail / Settings	CRUD / Relation-first Resource	add or remove allowed environments for a workspace member	inline relation-manager or dedicated scoped page	forbidden	grouped relation actions only	grouped destructive actions with confirmation	managed-environment access scope page under current workspace or environment	same access-scope page	workspace and managed-environment context	Environment access scope	whether access is inherited or narrowed	none
Shared managed-environment selection and tenant-owned page access	Navigation / Drilldown / Context	Global-context Shell	open the current environment safely	explicit environment selection and deep-link entry points	required where the shell already uses row or identifier click	secondary navigation or diagnostics in helper placements	none introduced by this slice	existing admin shell and context chooser	existing tenant-owned page routes and run drilldowns	workspace, managed environment, lifecycle	Managed environment	access allowed or deny-as-not-found boundary	none

Operator Surface Contract

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
Workspace membership management	Workspace owner or manager	decide which workspace role a member should hold	relation-manager settings surface	What should this member be allowed to do across the workspace?	member, workspace role, owner-guard state	audit history and membership source	role authority, owner-guard	TenantPilot only	Add member, Change role	Remove member
Managed-environment access-scope management	Workspace owner or manager	decide whether a member should be limited to specific environments	relation-manager or dedicated scoped page	Should this member inherit workspace-wide access or be narrowed to specific environments?	inheritance mode, selected environments	audit history, scope source	inherited versus narrowed	TenantPilot only	Add allowed environment, Remove allowed environment	Clear or narrow access scope
Shared managed-environment selection and tenant-owned page access	Workspace operator	decide whether the current environment or run can be opened safely	global-context shell and page access	Can I open this environment, run, or resource from the current workspace?	current workspace, selected environment, and access result	deeper operability or provider blockers	workspace entitlement, environment scope, capability, operability	none	Open environment, Return to workspace	none

Proportionality Review

• New source of truth?: yes, but it is a canonical replacement of the existing role-bearing source-of-truth split rather than a new persisted truth
• New persisted entity/table/artifact?: no
• New abstraction?: yes
• New enum/state/reason family?: no
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: access control is duplicated across workspace roles and managed-environment memberships, which creates inconsistent page access, duplicated administration, and future-role drift.
• Existing structure is insufficient because: the current structure requires two role-bearing membership tables plus two resolver stacks to answer one authorization question. That contradicts the workspace-first cutover and makes deny-as-not-found rules inconsistent.
• Narrowest correct implementation: keep workspace memberships as the only role-bearing truth, reinterpret or replace the existing managed-environment membership model as a narrow access-scope overlay, and retarget the existing shared resolvers, policies, and relation managers instead of adding a new RBAC framework.
• Ownership cost: capability resolution, model semantics, membership management surfaces, policy tests, and browser smoke all need synchronized updates; that cost is bounded because the feature removes a duplicate model instead of adding a third one.
• Alternative intentionally rejected: keeping both role-bearing tables and adding synchronization or fallback logic. That would preserve the split truth and add more compatibility complexity in a pre-production codebase.
• Release truth: current-release truth

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, dual-write logic, historical-fixture preservation, and compatibility-specific tests are out of scope unless an adjacent prerequisite spec explicitly requires them.

Canonical replacement is preferred over preservation.

External implementation prerequisites

• Spec 280 must already provide the workspace-first route and panel-shell baseline on the implementation branch before 285 runtime work begins.
• Spec 281 must already provide the provider-neutral target-scope and provider-identity baseline so access scope does not hardcode Microsoft-specific scope contracts.
• Spec 283 must already provide the provider capability context consumed by provider-backed actions once workspace-first access passes.
• Spec 284 remains adjacent but is not a hard blocker for the RBAC cutover as long as 285 does not absorb source-taxonomy work.

Testing / Lane / Runtime Impact

• Test purpose / classification: Unit, Feature, Browser
• Validation lane(s): fast-feedback, confidence, browser
• Why this classification and these lanes are sufficient: the resolver and scope-overlay logic need unit proof; policy, Filament access, and environment-selection behavior need feature proof; one browser smoke is required to confirm that workspace role management plus environment-scope management drive real shell access consistently.
• New or expanded test families: one unit family for workspace-first access resolution and scoped-environment inheritance, one feature family for environment-owned policy retargeting, one feature family for membership-surface migration, one feature family for OperationRun access continuity, and one narrow browser smoke for workspace role plus environment-scope behavior
• Fixture / helper cost impact: moderate because proof needs workspace membership, optional environment-scope records, managed-environment context, and representative provider/run resources without widening global test defaults
• Heavy-family visibility / justification: one browser smoke only; no heavy-governance family is justified
• Special surface test profile: standard-native-filament, global-context-shell, shared-detail-family
• Standard-native relief or required special coverage: standard Filament feature coverage is sufficient for membership management surfaces; one global-context-shell smoke is required for environment selection and page access continuity
• Reviewer handoff: reviewers must verify that workspace_memberships become the sole role-bearing truth, that any surviving managed-environment overlay no longer carries capability authority, that ProviderConnectionResource stays non-globally-searchable with View and Edit pages intact, that touched destructive membership actions still use ->action(...) plus ->requiresConfirmation(), that Filament remains v5 on Livewire v4, that provider registration stays in apps/platform/bootstrap/providers.php, and that the planned tests cover both positive and negative access paths
• Budget / baseline / trend impact: moderate feature-local increase only
• Escalation needed: document-in-feature if implementation must stage a temporary scope-overlay alias; reject-or-split if it keeps dual role authority
• Active feature PR close-out entry: Guardrail
• Planned validation commands:
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Unit/Auth/WorkspaceFirstCapabilityResolverTest.php tests/Unit/Auth/ManagedEnvironmentAccessScopeResolverTest.php)
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Feature/Auth/WorkspaceFirstManagedEnvironmentAccessTest.php tests/Feature/Rbac/ProviderConnectionWorkspaceFirstPolicyTest.php tests/Feature/Rbac/OperationRunWorkspaceFirstAuthorizationTest.php tests/Feature/Rbac/GovernanceArtifactsWorkspaceFirstAuthorizationTest.php tests/Feature/Filament/WorkspaceMembershipRoleManagementTest.php tests/Feature/Filament/ManagedEnvironmentAccessScopeManagementTest.php)
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Browser/Spec285WorkspaceRbacEnvironmentAccessSmokeTest.php)
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail bin pint --dirty --format agent)

Candidate Selection Gate Summary

• Selected candidate: 285 - Workspace-first RBAC & Environment Access Scoping
• Source locations:
  • docs/product/spec-candidates.md under the reserved workspace-first cutover pack
  • docs/product/roadmap.md under the same cutover ordering
• Why selected now: the user explicitly requested the reserved slot 285, and repo truth shows this is the next unspecced cutover gap after workspace context, provider-neutral target scope, and provider capability preparation. The remaining blocker is no longer route or provider vocabulary alone, but the dual authorization core.
• Why close alternatives were deferred:
  • 284 remains source-taxonomy work and should not be folded into RBAC replacement
  • 286 should follow once the canonical access model and environment-scope semantics are stable
  • 287 should harden the cutover after 285 finishes replacing the dual access core instead of before
• Smallest viable implementation slice: replace role-bearing managed-environment membership truth with workspace-first role resolution plus an optional environment-scope overlay, then retarget the key policies and membership surfaces around that contract
• Documented deviations from raw candidate wording:
  • the raw candidate says TenantMembership should be removed or replaced, but current repo truth uses ManagedEnvironmentMembership rather than TenantMembership
  • repo truth already has WorkspaceMembership, WorkspaceCapabilityResolver, and workspace-level role management, so 285 is not greenfield RBAC; it is a consolidation cutover
  • the optional environment-scope layer should be modeled as a narrow visibility overlay, not as another full role-bearing ACL system

Completed-Spec Guardrail Result

• specs/279-workspace-managed-environment-core/ already exists with implementation-close-out history and remains historical prerequisite context only
• specs/280-workspace-tenancy-environment-routing/ already exists with Status: Ready and remains adjacent prepared context only
• specs/281-provider-connection-scope/ already exists with Status: Ready and remains adjacent prepared context only
• specs/282-governance-artifact-retargeting/ already exists with implementation-close-out history and remains historical adjacent context only
• specs/283-provider-capability-registry/ already exists with Status: Ready and remains adjacent prepared context only
• specs/062-tenant-rbac-v1/ and specs/065-tenant-rbac-v1/ remain historical tenant-first RBAC context and are not modified by this package
• the target package specs/285-workspace-rbac-environment-access/ did not exist before this prep run and is the sole new package created here

Deferred Adjacent Candidates

• 284 - Provider-neutral Artifact Source Taxonomy v1
• 286 - UI Copy, IA & Localization Neutralization
• 287 - Cutover Quality Gates & No-Legacy Enforcement

User Scenarios & Testing

User Story 1 - Workspace membership becomes the only role authority (Priority: P1)

As a workspace owner or manager, I want one canonical role-bearing membership record so every managed-environment page and run drilldown inside my workspace follows the same role decision.

Why this priority: this is the core cutover value. Without it, environment-owned pages still depend on a second RBAC truth.

Independent Test: create one workspace member without any explicit managed-environment scope rows, open an entitled managed environment, and confirm provider connections, findings, evidence, review packs, and run drilldowns all use the workspace role consistently.

Acceptance Scenarios:

1. Given a user has a workspace membership with the required role and no environment-scope narrowing, When they open a managed-environment-owned resource inside that workspace, Then access is decided from workspace membership plus capability and does not require a second role-bearing environment membership.
2. Given a user is not a workspace member, When they open any managed-environment-owned route or run drilldown for that workspace, Then the system responds as deny-as-not-found.

---

User Story 2 - Environment scope can narrow visibility without becoming a second RBAC system (Priority: P1)

As a workspace owner or manager, I want to optionally narrow a member to specific managed environments without creating a second role matrix per environment.

Why this priority: the roadmap explicitly wants environment access scopes to stay feasible, but not at the cost of reintroducing another full ACL core.

Independent Test: grant one workspace member access to only one environment, confirm that environment is selectable and a sibling environment in the same workspace stays hidden or 404, while the same workspace role capabilities apply inside the allowed environment.

Acceptance Scenarios:

1. Given a workspace member has an explicit allowlist for one managed environment, When they try to open another managed environment in the same workspace, Then the system responds as deny-as-not-found.
2. Given a workspace member has an explicit allowlist for one managed environment, When they open an allowed environment, Then their role capabilities are derived from workspace membership and only visibility is narrowed by environment scope.

---

User Story 3 - Membership management surfaces stop editing duplicate role truth (Priority: P2)

As a workspace owner or manager, I want workspace roles and environment scopes managed on purpose-built surfaces so I do not assign contradictory roles in two places.

Why this priority: the current tenant-membership UI encodes the drift directly; until it is retargeted, operators can keep rebuilding the dual model.

Independent Test: open the workspace membership surface and the retargeted environment-scope surface, confirm roles are managed only at workspace level, confirm environment surfaces only manage visibility scope, and confirm both mutation paths audit their changes.

Acceptance Scenarios:

1. Given a workspace owner opens membership management, When they change a member role, Then the role change is stored and audited at workspace scope only.
2. Given a workspace owner opens the managed-environment access-scope surface, When they add or remove one environment from scope, Then the mutation changes environment visibility only and does not expose a second role selector.

Edge Cases

• What happens when a workspace member has no explicit environment-scope rows and the workspace contains archived or removed managed environments?
• How does the system handle a remembered managed-environment context after a scope row is removed or a workspace membership is deleted?
• What happens when an OperationRun belongs to a workspace with no managed_environment_id versus one that is environment-bound?
• How does the system handle last-owner protection when workspace role management replaces the current managed-environment owner semantics?
• What happens when local RBAC passes but provider capability from Spec 283 blocks the action afterward?

Requirements

Functional Requirements

• FR-001 Workspace membership is the only role-bearing authorization truth. Managed-environment-owned resource capabilities MUST resolve from workspace membership, not from a second environment role record.
• FR-002 Workspace membership is the first entitlement boundary. Non-members of the current workspace MUST receive deny-as-not-found for workspace-owned and managed-environment-owned routes, actions, and run drilldowns.
• FR-003 Managed-environment scope is an optional narrowing layer. The managed-environment overlay MUST only answer whether the current workspace member may access a specific managed environment; it MUST NOT become a second role or capability registry.
• FR-004 Full workspace inheritance is the default. If no explicit managed-environment scope narrowing exists for a workspace member, that member inherits environment visibility across the selectable managed environments in the workspace.
• FR-005 Scoped access is explicit. If explicit managed-environment scope rows exist for a workspace member, only those environments are visible or openable for that member.
• FR-006 Capability resolution stays capability-first. The existing capability registry remains the only capability vocabulary, and environment-owned policies MUST continue to check capabilities rather than raw role strings.
• FR-007 User::canAccessTenant(), Filament tenant selection, remembered tenant context, and related-context navigation MUST use the same workspace-first access contract.
• FR-008 Environment-owned policies MUST be retargeted. ManagedEnvironment, ProviderConnection, OperationRun, Finding, EvidenceSnapshot, ReviewPack, TenantReview, and other governance-review or evidence surfaces in scope MUST evaluate workspace membership first, managed-environment scope second, and capability third.
• FR-009 OperationRun authorization MUST preserve mixed workspace and managed-environment behavior. Workspace-wide runs continue to authorize against workspace membership; environment-bound runs additionally respect managed-environment scope before capability evaluation.
• FR-010 Membership-management surfaces MUST split concerns. Workspace membership management remains the only role-editing surface. The current tenant-membership surface MUST either be removed or transformed into environment access-scope management with no second role selector.
• FR-011 Membership and scope mutations remain audited. Workspace role changes, environment-scope changes, and last-owner blocks MUST write canonical audit records with no secrets.
• FR-012 404 versus 403 semantics stay explicit. Non-membership or out-of-scope access returns 404; in-scope members missing the capability return 403.
• FR-013 Global search and shell context stay safe. Non-members or out-of-scope actors MUST not receive managed-environment hints through global search or remembered tenant context.
• FR-014 No compatibility path is introduced. The runtime MUST not keep dual-write, fallback-role reads, or legacy role-based ManagedEnvironmentMembership checks once the cutover lands.

Non-Functional Requirements

• NFR-001 Resolver performance remains request-local and cacheable. The new access-resolution path MUST avoid N+1 membership or scope queries in page tables, run lists, and bulk authorization preflight.
• NFR-002 Test breadth stays bounded. Proof focuses on unit resolver behavior, feature authorization behavior, and one browser smoke; no broad browser matrix is justified.
• NFR-003 Workspace and managed-environment isolation remain explicit and diagnosable. Audit logs and denied-access logs MUST make the failed boundary diagnosable without leaking raw provider detail.
• NFR-004 Filament v5 and Livewire v4 remain unchanged. The feature MUST not introduce view publishing, custom action surfaces outside existing patterns, or asset strategy changes.

Scope Boundaries (required for this slice)

In Scope

• replacing environment role authority with workspace-first role authority
• modeling explicit managed-environment scope as narrowing only
• retargeting CapabilityResolver, User::canAccessTenant(), WorkspaceContext, and the key environment-owned policies to that contract
• migrating the current tenant-membership management surface so it no longer edits a second role family
• preserving canonical 404 versus 403 semantics across workspace-owned and environment-owned surfaces
• preserving provider-capability follow-through as a downstream gate rather than re-encoding provider rules here

Non-Goals

• designing a new customer-facing role catalog
• shipping per-environment role overrides or a full environment ACL matrix
• redefining /system platform RBAC
• absorbing provider capability, source taxonomy, copy/localization, or no-legacy guardrail work from Specs 283, 284, 286, or 287
• shipping compatibility aliases or legacy dual-write logic

Assumptions

• Specs 280, 281, and 283 will land or already be available on the eventual implementation branch before runtime work on 285 starts.
• WorkspaceMembership and WorkspaceCapabilityResolver remain the correct extension points for canonical role-bearing access.
• The current managed_environment_memberships persistence can be repurposed or replaced in place because the product is still pre-production.
• The existing capability vocabulary in App\Support\Auth\Capabilities remains valid; 285 changes who resolves roles, not the capability names themselves.
• ProviderConnectionResource remains non-globally-searchable, while resources already carrying valid search destinations retain those destinations.

Risks

• dual-role checks may survive in one or more policies or Filament helpers and silently preserve the old model
• environment-scope management could accidentally keep role selectors or owner semantics and reintroduce a second RBAC core under a new label
• OperationRun access and remembered tenant context may drift if they do not adopt the same workspace-first access contract as page policies
• enum or capability-map convergence could widen unexpectedly if implementation tries to solve adjacent role-productization concerns in the same slice

UI Action Matrix (mandatory when Filament is changed)

Action Surface Contract satisfied?: yes
UI-FIL-001 satisfied?: yes. The slice keeps native Filament relation managers, native confirmation modals, and existing shared enforcement helpers. No local Blade replacement or asset exception is planned.
UX-001 satisfied?: yes for the touched surfaces in scope. The feature reuses existing resource and relation-manager shells rather than introducing custom Create/Edit/View layouts.

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
Workspace membership management	apps/platform/app/Filament/Resources/Workspaces/RelationManagers/WorkspaceMembershipsRelationManager.php	Add member	Inline relation-manager row focus inside the workspace detail page; no redundant View action	Change role, Remove member	none	Add member	none	native modal submit and cancel	yes	Remove member stays destructive, confirmation-protected, server-authorized, and last-owner-safe
Managed-environment access-scope management	apps/platform/app/Filament/Resources/TenantResource/Pages/ManageTenantMemberships.php plus TenantMembershipsRelationManager.php	Add allowed environment	Inline relation-manager or page-local scoped list; no separate inspect route	Edit scope, Remove access	none	Add allowed environment	none	native modal submit and cancel	yes	The surface may not expose a role selector, owner semantics, or a second role-bearing mutation path

Key Entities

• WorkspaceMembership: existing workspace-owned, role-bearing membership pivot that remains the only source for role and capability derivation.
• ManagedEnvironmentAccessScope: logical successor to the current managed-environment membership semantics; stores optional visibility narrowing only and never grants capabilities by itself.
• ManagedEnvironment authorization decision: derived, non-persisted access payload used by User, WorkspaceContext, policies, and run drilldowns to evaluate membership, scope, capability, and denial outcome consistently.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: In the bounded proof suite, a workspace member with the required workspace role and no explicit scope rows can open at least one provider-connection surface and one governance-artifact surface in the workspace without any role-bearing managed-environment membership row.
• SC-002: In the bounded proof suite, a workspace member narrowed to one managed environment receives 404 for a sibling environment in the same workspace while still receiving the expected capability outcome inside the allowed environment.
• SC-003: The retargeted membership surfaces expose exactly one role-editing plane at workspace scope and zero role selectors on the managed-environment scope surface, while every destructive membership or scope mutation remains confirmation-protected.
• SC-004: The named unit, feature, browser, and dirty-file formatting commands in this package pass without widening the proof family beyond the files listed in spec.md, plan.md, quickstart.md, and tasks.md.