TenantAtlas/specs/282-governance-artifact-retargeting/plan.md

Implementation Plan: Governance Artifact Retargeting to ManagedEnvironment

Branch: 282-governance-artifact-retargeting | Date: 2026-05-07 | Spec: spec.md Input: Feature specification from specs/282-governance-artifact-retargeting/spec.md

Summary

Prepare the third reserved managed-environment cutover slice by moving the existing governance artifact surface families onto the workspace-first admin runtime. The narrow implementation path reuses the existing artifact models, Filament resources, artifact presenters, ResolvesPanelTenantContext, InteractsWithTenantOwnedRecords, OperateHubShell, RelatedNavigationResolver, CanonicalNavigationContext, OperationRunLinks, and the workspace-first route shell prepared by Spec 280, while explicitly deferring lifecycle, stored-report productization, provider-capability, taxonomy, RBAC, copy, and quality-gate follow-through to Specs 267, 277, and 283 through 287.

This plan is intentionally bounded. Filament remains v5 on Livewire v4, provider registration remains in apps/platform/bootstrap/providers.php, no schema or persistence change is introduced, no artifact naming or lifecycle rewrite is introduced, and no compatibility panel or route fallback is allowed.

This package is not independently executable on current repo truth. Implementation is blocked until the workspace-first environment route shell from Spec 280 is already merged or otherwise present on the implementation branch.

Inherited Baseline / Explicit Delta

Inherited baseline

• Spec 279 already moved the core governance artifact models onto managed_environment_id plus workspace_id, and many models now derive workspace_id through DerivesWorkspaceIdFromTenant or equivalent seams.
• Spec 280 already defines the workspace-first environment route shell and surviving admin-panel ownership as the adjacent cutover baseline, and 282 is only executable once that shell is already present on the implementation branch.
• Spec 281 already prepares the provider-boundary extraction so 282 can treat provider seams as adjacent context, not new scope.
• Current repo truth still shows tenant-panel registration or admin-hidden behavior on several governance artifact resources through shouldRegisterNavigation() checks against Filament::getCurrentPanel()?->getId() === 'admin'.
• Current repo truth also shows environment resolution and authorization on read-only artifact resources such as ReviewPackResource, EvidenceSnapshotResource, and StoredReportResource still relying on ManagedEnvironment::current() or mixed fallback chains that assume the tenant panel remains active.
• OperationRunLinks already owns the canonical operations link language; 282 only needs artifact surfaces to reuse that contract.
• Existing prepared packages already cover adjacent lifecycle and artifact productization gaps: Spec 267 for artifact lifecycle and Spec 277 for stored reports.

Explicit delta in this plan

• Register the touched governance artifact resource families on the workspace-first admin runtime instead of hiding them from the admin panel or depending on the tenant panel.
• Align collection and detail route ownership for those resource families to /admin/workspaces/{workspace}/environments/{environment}/....
• Align environment-context resolution for those resources and their related pages so the admin panel can resolve the current managed environment without the tenant panel.
• Retarget related navigation, record URLs, and operation drillthroughs emitted by the touched artifact surfaces to the workspace-first environment and operations contracts.
• Preserve each resource's existing action hierarchy, read-only or mutation semantics, capability model, and artifact presenters.
• Explicitly defer lifecycle semantics, stored-report surface expansion, provider-capability or taxonomy work, RBAC redesign, copy-neutralization, and broader no-legacy enforcement.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12.52
Primary Dependencies: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, existing Filament resources and shared navigation/context helpers
Storage: PostgreSQL, no new persistence or schema change
Testing: Pest feature tests, one Pest browser smoke, focused legacy-panel guard coverage
Validation Lanes: fast-feedback, confidence, browser
Target Platform: Laravel monolith in apps/platform
Project Type: web application
Performance Goals: preserve current resource responsiveness and viewer behavior while changing only panel registration, route ownership, environment resolution, and deep links
Constraints: no schema migration, no compatibility routes, no dual-panel ownership, no naming or lifecycle rewrite, no RBAC redesign, provider registration remains in apps/platform/bootstrap/providers.php, and Filament remains v5 on Livewire v4
Scale/Scope: one route and registration contract over the existing environment-owned governance artifact resource families plus their related drillthrough links

Likely Affected Repo Surfaces

• apps/platform/app/Filament/Concerns/ResolvesPanelTenantContext.php
• apps/platform/app/Filament/Concerns/InteractsWithTenantOwnedRecords.php
• apps/platform/app/Filament/Resources/InventoryItemResource.php
• apps/platform/app/Filament/Resources/PolicyResource.php
• apps/platform/app/Filament/Resources/PolicyVersionResource.php
• apps/platform/app/Filament/Resources/BackupScheduleResource.php
• apps/platform/app/Filament/Resources/BackupSetResource.php
• apps/platform/app/Filament/Resources/RestoreRunResource.php
• apps/platform/app/Filament/Resources/FindingResource.php
• apps/platform/app/Filament/Resources/FindingExceptionResource.php
• apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php
• apps/platform/app/Filament/Resources/TenantReviewResource.php
• apps/platform/app/Filament/Resources/ReviewPackResource.php
• apps/platform/app/Filament/Resources/StoredReportResource.php
• apps/platform/app/Support/Navigation/RelatedNavigationResolver.php
• apps/platform/app/Support/Navigation/CanonicalNavigationContext.php
• apps/platform/app/Support/OperationRunLinks.php
• apps/platform/app/Support/OperateHub/OperateHubShell.php
• representative feature and browser coverage under apps/platform/tests/Feature/Filament/GovernanceArtifacts/ and apps/platform/tests/Browser/

Filament v5 / Panel Notes

• Livewire v4.0+ compliance: this slice keeps Filament v5 on Livewire v4 and changes only resource registration, route ownership, context resolution, and related links.
• Provider registration location: any provider registration context remains in apps/platform/bootstrap/providers.php; nothing moves to bootstrap/app.php.
• Global search rule: 282 does not enable global search on new artifact resources. Any touched resource that is already searchable must keep a valid View or Edit destination or be disabled in the same slice.
• Destructive actions: no new destructive actions are introduced. Existing destructive or high-impact actions touched by the route retarget must preserve ->requiresConfirmation() plus current server authorization.
• Asset strategy: no new asset registration or deployment step is planned.

Governance Artifact Route Ownership Fit

• Treat the current environment-owned governance artifact resources as the primary unit of change, not the underlying models or lifecycle semantics.
• Reuse the workspace-first environment route shell from Spec 280 instead of inventing a parallel artifact route family.
• Reuse ResolvesPanelTenantContext as the shared environment-resolution seam, but make the admin-panel route contract its authoritative source for the touched artifact families.
• Reuse each resource's current action-surface declaration and local UI semantics; only route ownership, admin registration, and related URLs move.
• Reuse OperationRunLinks and RelatedNavigationResolver for artifact-origin operation or related-resource drillthroughs rather than per-resource URL composition.
• Do not preserve ManagedEnvironment::current() as a surviving runtime fallback for touched surfaces. The final shipped contract must resolve the current environment from the workspace-first admin route or operate-hub context only.

UI / Surface Guardrail Plan

• Guardrail scope: changed surfaces
• Native vs custom classification summary: native Filament
• Shared-family relevance: environment-scoped resources, related navigation, artifact presenters, operation links
• State layers in scope: shell, page, detail, URL-query
• Audience modes in scope: operator-MSP, support-platform, customer-safe read-only where already supported by current surfaces
• Decision/diagnostic/raw hierarchy plan: keep environment scope and primary inspect action visible first; keep diagnostics or raw/support detail secondary on the destination surface
• Raw/support gating plan: unchanged existing gating; this slice does not widen raw evidence disclosure
• One-primary-action / duplicate-truth control: preserve each resource's current inspect model and existing primary action; add no new redundant inspect or navigation affordance
• Handling modes by drift class or surface: review-mandatory
• Repository-signal treatment: review-mandatory until guard coverage proves the touched artifact families no longer depend on the tenant panel
• Special surface test profiles: standard-native-filament, global-context-shell
• Required tests or manual smoke: functional-core, state-contract, manual-smoke
• Exception path and spread control: none; the goal is convergence on the admin-panel route contract
• Active feature PR close-out entry: Guardrail

Shared Pattern & System Fit

• Cross-cutting feature marker: yes
• Systems touched: environment-owned resources, shared environment-context helpers, related navigation, operation links, artifact presenters, admin-panel route shell
• Shared abstractions reused: ResolvesPanelTenantContext, InteractsWithTenantOwnedRecords, RelatedNavigationResolver, CanonicalNavigationContext, OperationRunLinks, ArtifactTruthPresenter, existing ActionSurfaceDeclarations
• New abstraction introduced? why?: none planned; the existing shared seams are sufficient
• Why the existing abstraction was sufficient or insufficient: the abstractions already express the right ownership and presentation model; they are insufficient only because the tenant panel still leaks into registration and route-generation behavior
• Bounded deviation / spread control: none; if a local escape hatch appears, the work is out of scope and should split

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes, link semantics only
• Central contract reused: OperationRunLinks, RelatedNavigationResolver, and the workspace-first operations routes from Spec 280
• Delegated UX behaviors: artifact-origin operation links, explicit environment-filter continuity, and destination-safe route ownership
• Surface-owned behavior kept local: source resources decide whether a related operation link exists; they do not own the operations URL contract
• Queued DB-notification policy: N/A
• Terminal notification path: N/A
• Exception path: none

Provider Boundary & Portability Fit

N/A - 282 does not alter shared provider identity or capability seams directly. Those remain with Specs 281, 283, and 284.

Constitution Check

GATE: Must pass before implementation begins and again after design artifacts are complete.

• Inventory-first / snapshot truth: PASS. Artifact persistence truth stays unchanged.
• Read/write separation: PASS. No new remote-write or lifecycle workflow is introduced.
• Graph contract path: PASS. No Graph contract change is introduced.
• Deterministic capabilities: PASS. Existing capability checks stay unchanged.
• RBAC-UX plane separation: PASS. /admin and /system remain separate.
• Workspace isolation: PASS. Workspace membership remains the first route boundary.
• Managed-environment isolation: PASS. Managed-environment access remains the second route boundary.
• Destructive action discipline: PASS by non-expansion. Existing confirmation and server authorization remain intact.
• Global search safety: PASS with implementation condition. Touched searchable surfaces must keep valid destinations or be disabled.
• OperationRun / Ops-UX: PASS. Only existing operation link semantics move.
• Data minimization: PASS. No new data or raw disclosure is introduced.
• Test governance: PASS. Proof stays bounded to focused feature and browser coverage.
• Proportionality / no premature abstraction: PASS. The plan changes route ownership only.
• Persisted truth / behavioral state: PASS. No new persistence, state family, or taxonomy is introduced.
• UI semantics / shared pattern first / Filament-native UI: PASS. Existing native resources and presenters remain the first path.
• Provider boundary: PASS by non-expansion.

Gate evaluation: PASS.

Post-design re-check: PASS while research.md, data-model.md, quickstart.md, contracts/governance-artifact-retargeting.logical.openapi.yaml, and checklists/requirements.md remain aligned and keep Specs 267, 277, and 283 through 287 deferred.

Test Governance Check

• Test purpose / classification by changed surface: Feature, Browser
• Affected validation lanes: fast-feedback, confidence, browser
• Why this lane mix is the narrowest sufficient proof: the cutover changes resource registration, route ownership, context resolution, and deep-link behavior on existing surfaces. Feature tests prove those contracts; one browser smoke proves the real shell and one representative artifact path.
• Narrowest proving command(s):
  • 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/Filament/GovernanceArtifacts/GovernanceArtifactAdminPanelRegistrationTest.php tests/Feature/Filament/GovernanceArtifacts/GovernanceArtifactEnvironmentContextTest.php tests/Feature/Filament/GovernanceArtifacts/GovernanceArtifactDeepLinkContractTest.php tests/Feature/Filament/GovernanceArtifacts/GovernanceArtifactLegacyTenantPanelGuardTest.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/Spec282GovernanceArtifactRetargetingSmokeTest.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)
• Fixture / helper / factory / seed / context cost risks: moderate because proof needs workspace membership, managed-environment membership, and representative artifact fixtures across more than one family
• Expensive defaults or shared helper growth introduced?: no; keep new fixtures opt-in and bounded to the governance-artifact family
• Heavy-family additions, promotions, or visibility changes: none
• Surface-class relief / special coverage rule: standard-native-filament relief for most resources; one browser smoke still required for the real shell and route contract
• Closing validation and reviewer handoff: rerun the exact commands above, confirm the touched governance artifact families register on the admin panel, confirm resource URLs and related links no longer emit tenant-panel destinations, confirm environment resolution on the admin panel no longer depends on tenant-panel-only state, confirm touched searchable resources keep truthful destinations or stay disabled, confirm destructive actions still require confirmation, and confirm no new asset or deployment step appears
• Budget / baseline / trend follow-up: contained feature-local increase only
• Review-stop questions: did the implementation leave any touched artifact family admin-hidden, did any touched resource still rely on panel: 'tenant' or tenant: URLs, did any read-only artifact surface still require ManagedEnvironment::current() as the only source of truth, did the slice absorb lifecycle or copy work from adjacent specs
• Escalation path: reject-or-split if the implementation introduces schema work, compatibility fallbacks, or adjacent lifecycle or RBAC scope
• Active feature PR close-out entry: Guardrail
• Why no dedicated follow-up spec is needed: the remaining adjacent work already exists as Specs 267, 277, and 283 through 287; route and registration proof stays inside this feature

Review Checklist Status

• Review checklist artifact: checklists/requirements.md
• Review outcome class: blocked-by-prerequisite
• Workflow outcome: keep
• Test-governance outcome: keep
• Escalation rule: if implementation starts without Spec 280 present, leaves touched artifact families tenant-panel-bound, introduces schema or lifecycle work, or widens into adjacent specs, flip the workflow outcome to split or reject-or-split

Rollout Considerations

• Land the touched governance artifact resource families and the shared environment-context helper changes as one bounded slice so admin registration, route ownership, and authorization move together.
• Do not begin runtime implementation until Spec 280 is merged or otherwise available on the implementation branch.
• Update shared route and context seams before polishing individual resources so each resource can inherit the same final contract.
• Keep read-only artifact surfaces in the same slice because they are the most likely place for hidden tenant-panel fallbacks to survive.
• Keep operation drillthrough retargeting inside the same slice so artifact truth and execution truth stay aligned.

Risk Controls

• Reject any implementation that reopens schema, lifecycle, or naming work instead of limiting itself to route ownership and context resolution.
• Reject any implementation that leaves a touched artifact family hidden from the admin panel or still emitting tenant-panel URLs.
• Reject any implementation that adds a second local route helper pattern instead of reusing the shared navigation and context seams.
• Reject any implementation that widens searchable exposure without keeping a truthful destination.

Research & Design Outputs

• research.md records the candidate deviations, route-ownership decision, touched resource inventory, and deferrals.
• data-model.md captures the route-context and authorization contracts for the environment-owned artifact families.
• quickstart.md gives reviewers the bounded proof flow and exact commands.
• contracts/governance-artifact-retargeting.logical.openapi.yaml records the logical route contract for the touched artifact families and their operation drillthroughs.
• checklists/requirements.md records package readiness, boundedness, and outcome state.

Project Structure

Documentation (this feature)

specs/282-governance-artifact-retargeting/
├── checklists/
│   └── requirements.md
├── contracts/
│   └── governance-artifact-retargeting.logical.openapi.yaml
├── data-model.md
├── plan.md
├── quickstart.md
├── research.md
├── spec.md
└── tasks.md

Source Code (expected implementation surfaces)

apps/platform/
├── app/
│   ├── Filament/
│   │   ├── Concerns/
│   │   │   ├── InteractsWithTenantOwnedRecords.php
│   │   │   └── ResolvesPanelTenantContext.php
│   │   └── Resources/
│   │       ├── BackupScheduleResource.php
│   │       ├── BackupSetResource.php
│   │       ├── EvidenceSnapshotResource.php
│   │       ├── FindingExceptionResource.php
│   │       ├── FindingResource.php
│   │       ├── InventoryItemResource.php
│   │       ├── PolicyResource.php
│   │       ├── PolicyVersionResource.php
│   │       ├── RestoreRunResource.php
│   │       ├── ReviewPackResource.php
│   │       ├── StoredReportResource.php
│   │       └── TenantReviewResource.php
│   └── Support/
│       ├── Navigation/
│       │   ├── CanonicalNavigationContext.php
│       │   └── RelatedNavigationResolver.php
│       ├── OperateHub/
│       │   └── OperateHubShell.php
│       └── OperationRunLinks.php
└── tests/
    ├── Browser/
    │   └── Spec282GovernanceArtifactRetargetingSmokeTest.php
    └── Feature/
        └── Filament/
            └── GovernanceArtifacts/
                ├── GovernanceArtifactAdminPanelRegistrationTest.php
                ├── GovernanceArtifactDeepLinkContractTest.php
                ├── GovernanceArtifactEnvironmentContextTest.php
                └── GovernanceArtifactLegacyTenantPanelGuardTest.php

Structure Decision: Laravel monolith under apps/platform with one bounded documentation package under specs/282-governance-artifact-retargeting/, no new runtime top-level folders, and no adjacent-page retargeting in this slice.

Deferred Follow-Ups / Non-Goals

• Spec 267 artifact lifecycle and retention contract work
• Spec 277 stored-reports browse and detail productization beyond route ownership
• Spec 283 provider capability registry
• Spec 284 provider-neutral artifact taxonomy
• Spec 285 workspace-first RBAC and environment access scoping redesign
• Spec 286 UI copy and localization neutralization
• Spec 287 cutover-wide no-legacy enforcement