TenantAtlas/specs/187-portfolio-triage-arrival-context/plan.md

Implementation Plan: Portfolio Triage Arrival Context

Branch: 187-portfolio-triage-arrival-context | Date: 2026-04-09 | Spec: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/187-portfolio-triage-arrival-context/spec.md Input: Feature specification from /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/187-portfolio-triage-arrival-context/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/scripts/ for helper scripts.

Summary

Preserve portfolio triage intent when operators move from workspace recovery surfaces or filtered tenant-registry triage into tenant-level destinations by adding one small request-scoped arrival-context contract, propagating it through existing destination URLs, and rendering a compact top-of-page continuity block on the tenant dashboard. The implementation will reuse existing workspace reason_context, existing tenant-registry query-driven triage filters, existing backup/restore list continuity params, and existing capability-aware destination helpers so the feature stays additive, truthful, and free of new persistence or new posture computation.

Technical Context

Language/Version: PHP 8.4.15
Primary Dependencies: Laravel 12, Filament v5, Livewire v4, Pest v4, existing WorkspaceOverviewBuilder, TenantResource, TenantDashboard, CanonicalAdminTenantFilterState, TenantBackupHealthAssessment, RestoreSafetyResolver, and continuity-aware backup or restore list pages
Storage: PostgreSQL unchanged; no new tables, caches, or durable workflow artifacts
Testing: Pest 4 unit and feature tests, shared feature test concerns where reuse is warranted, and Livewire component coverage, run through Laravel Sail
Target Platform: Laravel monolith web application in Sail locally and containerized Linux deployment in staging and production
Project Type: web application
Performance Goals: No additional external calls at render time; keep the feature DB-only; append arrival context to existing URLs without regressing current drilldown routing; decode and resolve continuity once per request; keep workspace overview and tenant-registry changes query-neutral because they only append bounded URL state; avoid new N+1 queries on tenant-dashboard renders
Constraints: Request-scoped only; no persistence; no new recovery-truth model; generic tenant sessions remain unchanged; next-step guidance must stay RBAC-safe; arrival context must be bookmark-safe and fail closed to the generic tenant experience when invalid
Scale/Scope: One lightweight continuity abstraction spanning three operator surfaces: workspace overview triage, tenant-registry triage, and tenant dashboard arrival, while reusing existing backup and restore destinations for deeper follow-up

Constitution Check

GATE: Passed before Phase 0 research. Re-checked after Phase 1 design and still passing.

Principle	Pre-Research	Post-Design	Notes
Inventory-first / snapshots-second	PASS	PASS	The feature only carries existing backup-health and recovery-evidence truth into tenant arrival; no new source-of-truth path is introduced.
Read/write separation	PASS	PASS	The slice is read-only. No new write, restore, or operational start surface is added.
Graph contract path	N/A	N/A	No Microsoft Graph calls, provider contracts, or config/graph_contracts.php changes are required.
Deterministic capabilities	PASS	PASS	Existing capability checks remain authoritative for next-step access and destination degradation.
Workspace + tenant isolation	PASS	PASS	Arrival context is scoped to the active workspace and tenant route, and invalid or out-of-scope context degrades to the generic dashboard.
RBAC-UX authorization semantics	PASS	PASS	Non-members remain 404; members missing deeper capabilities receive degraded guidance rather than false CTAs.
Run observability / Ops-UX	PASS	PASS	No new OperationRun, no change to notification surfaces, and no long-running work.
Data minimization	PASS	PASS	Only bounded reason codes, posture states, return filters, and route-safe context travel in the request; nothing new is persisted.
Proportionality / no premature abstraction	PASS WITH JUSTIFIED ABSTRACTION	PASS WITH JUSTIFIED ABSTRACTION	One small arrival-context value object plus token codec and resolver are justified because multiple existing surfaces already share the same triage vocabulary but lose it at navigation boundaries.
Persisted truth / behavioral state	PASS	PASS	No new table, persisted entity, or new posture state family is introduced.
UI semantics / few layers	PASS	PASS	The continuity block reuses existing domain truth and claim boundaries instead of creating a new presentation framework.
Filament v5 / Livewire v4 compliance	PASS	PASS	The design stays inside the existing Filament v5 + Livewire v4 stack. No legacy API is introduced.
Provider registration location	PASS	PASS	No panel or provider registration changes are required. Laravel 11+ provider registration remains in bootstrap/providers.php.
Global search hard rule	PASS	PASS	No global search behavior changes are proposed. Impacted searchable resources already satisfy the rule: TenantResource has View and Edit pages, BackupSetResource has a View page, and RestoreRunResource has a View page.
Destructive action safety	PASS	PASS	No new destructive action is added. All new CTAs are navigation-only.
Asset strategy	PASS	PASS	No new assets are introduced. Existing deploy behavior remains unchanged, including cd apps/platform && php artisan filament:assets when registered assets are in play elsewhere.
Filament-native UI / Action Surface Contract	PASS	PASS	The tenant dashboard change is an additive read-only widget or section. Workspace overview and tenant registry keep their existing action models.
Filament UX-001	PASS	PASS	No create, edit, or view form layout changes are proposed; only summary and arrival guidance surfaces change.
Testing truth (TEST-TRUTH-001)	PASS	PASS	The plan adds workflow and regression tests that protect operator-visible continuity, truth boundaries, return flow, and RBAC-safe degradation.

Phase 0 Research

Research outcomes are captured in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/187-portfolio-triage-arrival-context/research.md.

Key decisions:

• Reuse existing workspace reason_context and existing destination payloads as the authoritative inputs for portfolio-arrival context instead of inventing a second concern model.
• Carry tenant-dashboard arrival intent in one bounded, versioned base64url token, following the repo's existing token pattern, so the context stays request-scoped, bookmark-safe, and easy to ignore when invalid.
• Preserve the current backup_health_reason and recovery_posture_reason query-param continuity on backup and restore destinations rather than replacing every downstream surface with a new universal token.
• Render the continuity treatment as the first non-lazy tenant dashboard widget or section so the operator sees it before scanning Recovery Readiness, KPIs, or Needs Attention.
• Preserve return-to-portfolio flow by reusing existing tenant-registry filter and sort query params and the canonical workspace overview route instead of creating session-backed triage state.
• Reuse existing capability-aware destination and disabled-helper patterns from WorkspaceOverviewBuilder so the continuity block does not overpromise inaccessible next steps.

Phase 1 Design

Design artifacts are created under /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/187-portfolio-triage-arrival-context/:

• data-model.md: request-scoped continuity entities, source inputs, validation rules, and derived relationships
• contracts/portfolio-triage-arrival-context.logical.openapi.yaml: internal logical contract for source surfaces, arrival token shape, and tenant dashboard continuity rendering
• quickstart.md: focused implementation and verification workflow

Design decisions:

• The new continuity layer is one derived runtime contract, not a persisted triage session or new recovery-confidence engine.
• The arrival token carries only bounded routing and concern metadata. Current tenant truth remains authoritative and is re-derived on arrival.
• WorkspaceOverviewBuilder remains the source of workspace triage reason and destination selection; ListTenants remains the source of filtered tenant-registry return context.
• Existing backup-set and restore-run continuity params remain authoritative for deeper follow-up surfaces.
• The tenant dashboard becomes continuity-aware through an additive top-of-page widget or section, with no redesign of the underlying dashboard architecture.

Project Structure

Documentation (this feature)

specs/187-portfolio-triage-arrival-context/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── portfolio-triage-arrival-context.logical.openapi.yaml
├── checklists/
│   └── requirements.md
└── tasks.md

Source Code (repository root)

apps/platform/
├── app/
│   ├── Filament/
│   │   ├── Pages/
│   │   │   ├── TenantDashboard.php
│   │   │   └── WorkspaceOverview.php
│   │   ├── Resources/
│   │   │   ├── BackupSetResource/
│   │   │   │   └── Pages/ListBackupSets.php
│   │   │   ├── RestoreRunResource/
│   │   │   │   ├── Pages/ListRestoreRuns.php
│   │   │   │   └── Pages/ViewRestoreRun.php
│   │   │   └── TenantResource/
│   │   │       └── Pages/ListTenants.php
│   │   ├── Widgets/
│   │   │   ├── Workspace/
│   │   │   │   ├── WorkspaceNeedsAttention.php
│   │   │   │   └── WorkspaceSummaryStats.php
│   │   │   └── Tenant/
│   │   │       ├── TenantArchivedBanner.php
│   │   │       └── TenantTriageArrivalContinuity.php
│   │   └── Resources/TenantResource.php
│   ├── Support/
│   │   ├── PortfolioTriage/
│   │   │   ├── PortfolioArrivalContext.php
│   │   │   ├── PortfolioArrivalContextToken.php
│   │   │   └── PortfolioArrivalContextResolver.php
│   │   ├── BackupHealth/TenantBackupHealthAssessment.php
│   │   ├── RestoreSafety/RestoreSafetyResolver.php
│   │   └── Workspaces/WorkspaceOverviewBuilder.php
│   └── resources/views/filament/widgets/tenant/
│       └── triage-arrival-continuity.blade.php
└── tests/
    ├── Feature/
    │   ├── Concerns/
    │   │   └── BuildsPortfolioTriageFixtures.php
    │   ├── Filament/
    │   │   ├── WorkspaceOverviewArrivalContextTest.php
    │   │   ├── TenantRegistryArrivalContextTest.php
    │   │   ├── TenantDashboardArrivalContextTest.php
    │   │   ├── TenantDashboardArrivalContextPerformanceTest.php
    │   │   ├── BackupSetListContinuityTest.php
    │   │   ├── RestoreRunListContinuityTest.php
    │   │   ├── WorkspaceOverviewContentTest.php
    │   │   └── TenantRegistryRecoveryTriageTest.php
    │   └── Rbac/
    │       └── TenantDashboardArrivalContextVisibilityTest.php
    └── Unit/
        └── Support/
            └── PortfolioTriage/
                ├── PortfolioArrivalContextTokenTest.php
                └── PortfolioArrivalContextResolverTest.php

Structure Decision: Keep the existing Laravel monolith structure under apps/platform. Add one narrow support namespace for the arrival-context contract and resolver, one additive tenant widget or view for rendering, focused Filament feature tests, narrow unit coverage for the token and resolver seam, and one shared feature-test concern instead of creating a broader navigation framework or new base directories.

Implementation Strategy

Phase A — Introduce the Arrival-Context Runtime Contract

Goal: Add one lightweight, request-scoped continuity contract and a bounded token codec.

Step	File	Change
A.1	apps/platform/app/Support/PortfolioTriage/PortfolioArrivalContext.php	Add the runtime value object that holds source surface, concern family and state, reason, claim boundary, next step, and return target for one tenant-opening action
A.2	apps/platform/app/Support/PortfolioTriage/PortfolioArrivalContextToken.php	Add a versioned base64url codec following the existing resume-token pattern, with strict decode-to-null behavior for malformed or unsupported state
A.3	apps/platform/app/Support/PortfolioTriage/PortfolioArrivalContextResolver.php	Add the resolver that validates decoded payloads, binds them to the current tenant and workspace scope, and derives capability-aware next-step and return targets

Phase B — Emit Arrival Context From Portfolio Sources

Goal: Append the bounded arrival token only where existing portfolio triage already knows why the tenant should open.

Step	File	Change
B.1	apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php	Extend backup-health and recovery-evidence tenant destinations so tenant-dashboard URLs carry the new arrival token while preserving existing destination semantics and disabled-destination fallbacks
B.2	apps/platform/app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php and apps/platform/app/Filament/Widgets/Workspace/WorkspaceSummaryStats.php	Preserve current card and stat CTA behavior while ensuring any tenant-dashboard target emitted from overview data carries arrival context
B.3	apps/platform/app/Filament/Resources/TenantResource.php and apps/platform/app/Filament/Resources/TenantResource/Pages/ListTenants.php	When triage filters are active, append arrival context and return-state data to the existing tenant-open affordance without changing generic list behavior

Phase C — Render The Tenant-Dashboard Continuity Block

Goal: Surface arrival reason, next step, and return path at the top of the tenant dashboard with no dashboard redesign.

Step	File	Change
C.1	apps/platform/app/Filament/Widgets/Tenant/TenantTriageArrivalContinuity.php	Add a non-lazy, full-width widget that resolves optional arrival context from the current request and current tenant scope
C.2	apps/platform/resources/views/filament/widgets/tenant/triage-arrival-continuity.blade.php	Render a compact continuity block with bounded title, reason, current-truth boundary, next-step CTA, and return link
C.3	apps/platform/app/Filament/Pages/TenantDashboard.php	Register the continuity widget first in the dashboard widget stack so it appears before Recovery Readiness and deeper tenant widgets

Phase D — Reuse Existing Deep-Link Continuity And RBAC Degradation

Goal: Keep deeper backup and restore surfaces authoritative while ensuring next-step navigation stays truthful under capability limits.

Step	File	Change
D.1	apps/platform/app/Support/PortfolioTriage/PortfolioArrivalContextResolver.php	Map concern families to existing backup-set or restore-run targets and preserve current backup_health_reason and recovery_posture_reason params for downstream continuity
D.2	apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php patterns reused in new resolver or helper	Reuse existing disabled-target semantics (disabled, helper_text, null url) so unavailable next-step guidance never looks actionable
D.3	apps/platform/app/Filament/Resources/BackupSetResource/Pages/ListBackupSets.php, apps/platform/app/Filament/Resources/RestoreRunResource/Pages/ListRestoreRuns.php, and apps/platform/app/Filament/Resources/RestoreRunResource/Pages/ViewRestoreRun.php	Keep current subheading continuity behavior unchanged and verify the new dashboard continuity flows into these existing destinations without replacing them

Phase E — Preserve Return-To-Portfolio Flow

Goal: Allow operators to resume the originating portfolio triage route without reconstructing filters or context manually.

Step	File	Change
E.1	apps/platform/app/Support/PortfolioTriage/PortfolioArrivalContextResolver.php	Build return targets for workspace overview and tenant-registry triage using bounded route names plus allowlisted filter and sort query params
E.2	apps/platform/app/Filament/Resources/TenantResource/Pages/ListTenants.php	Reuse the existing query-driven triage filter contract on re-entry; no new persistence or session-backed return logic
E.3	apps/platform/app/Filament/Widgets/Tenant/TenantTriageArrivalContinuity.php	Render the return link only when valid arrival context exists; generic tenant sessions remain calm

Phase F — Regression Protection And Verification

Goal: Prove continuity rendering, route preservation, and RBAC-safe degradation without regressing existing drilldowns.

Step	File	Change
F.1	apps/platform/tests/Feature/Filament/WorkspaceOverviewArrivalContextTest.php	Add focused coverage for workspace overview backup-absent and recovery-evidence drilldowns carrying arrival context into tenant-level destinations
F.2	apps/platform/tests/Feature/Filament/TenantRegistryArrivalContextTest.php	Add focused coverage for filtered tenant-registry triage carrying arrival context and preserving return filters and sort
F.3	apps/platform/tests/Feature/Filament/TenantDashboardArrivalContextTest.php	Add dashboard-focused coverage for continuity rendering, generic-session suppression, stale-context honesty, and RBAC-safe next-step degradation
F.4	apps/platform/tests/Feature/Filament/WorkspaceOverviewContentTest.php and apps/platform/tests/Feature/Filament/TenantRegistryRecoveryTriageTest.php	Extend legacy route-preservation regressions so existing non-dashboard destinations remain authoritative when current routing chooses them
F.5	apps/platform/tests/Feature/Filament/TenantDashboardArrivalContextPerformanceTest.php	Add query-shape and request-local resolution coverage that guards against new N+1 behavior and repeated arrival-context resolution on tenant-dashboard renders while overview and registry changes remain URL-only
F.6	apps/platform/tests/Feature/Filament/BackupSetListContinuityTest.php, apps/platform/tests/Feature/Filament/RestoreRunListContinuityTest.php, apps/platform/tests/Feature/Rbac/TenantDashboardArrivalContextVisibilityTest.php, and targeted Sail/Pest/Pint runs	Keep current continuity surfaces green and run the complete arrival-context verification pack across new and existing regressions

Key Design Decisions

D-001 — One bounded token beats scattered dashboard query params

The spec explicitly prefers one small arrival-context abstraction. A single versioned base64url token keeps tenant-dashboard arrival state coherent and removable without proliferating ad hoc query params.

D-002 — Existing downstream continuity params remain authoritative

Backup-set and restore-run destinations already explain why the operator landed there via backup_health_reason and recovery_posture_reason. The new feature should feed those surfaces, not replace them.

D-003 — The tenant dashboard should become continuity-aware through an additive widget, not a page rewrite

The dashboard already uses non-lazy tenant banner widgets. Reusing that pattern satisfies the placement requirement while keeping the change narrow and easy to remove.

D-004 — Current tenant truth must remain separate from arrival reason

Arrival context explains why the operator came, but current posture is still recomputed from existing tenant truth. This separation is the main safeguard against stale or misleading continuity copy.

D-005 — Return context should reuse existing tenant-registry query semantics

ListTenants already knows how to sanitize and reapply backup_posture, recovery_evidence, and triage_sort. Reusing that contract avoids session-backed state or a broader navigation system.

Risk Assessment

Risk	Impact	Likelihood	Mitigation
Arrival token becomes stale or hand-edited and shows misleading copy	High	Medium	Strict allowlist decode, bind the token to current tenant and workspace scope, and degrade to the generic dashboard on invalid or unsupported input
Existing workspace or registry drilldown routes regress	High	Medium	Only append continuity context to existing URLs and preserve existing destination kinds, labels, helper text, and regression tests
Return links drop triage filters and collapse into generic browsing	Medium	Medium	Reuse ListTenants triage query contract exactly and add explicit filtered-registry return tests
Next-step CTA overpromises access	High	Medium	Reuse existing capability-aware disabled-destination semantics and add RBAC-limited dashboard arrival tests
Continuity block adds noise to generic sessions	Medium	Low	Render only when arrival context resolves successfully; no token means no block, no return affordance

Test Strategy

• Add focused unit tests for token encoding, malformed-token handling, allowlisted decode behavior, and resolver scope validation in tests/Unit/Support/PortfolioTriage/PortfolioArrivalContextTokenTest.php and tests/Unit/Support/PortfolioTriage/PortfolioArrivalContextResolverTest.php.
• Add focused Filament feature tests that cover workspace overview backup-absent and recovery-unvalidated drilldowns into the tenant dashboard with the continuity block visible.
• Add focused tenant-registry triage tests that prove triage filters and sort survive a tenant-open and a return-to-registry action.
• Add tenant-dashboard arrival tests that cover backup-absent, backup-stale, backup-degraded, recovery-unvalidated, recovery-weakened, stale-context honesty, multiple-concern wording, generic-session suppression, and RBAC-safe CTA degradation.
• Add query-shape regression coverage in tests/Feature/Filament/TenantDashboardArrivalContextPerformanceTest.php so arrival-context resolution stays request-local and does not introduce new N+1 behavior on tenant-dashboard renders; workspace overview and tenant-registry changes stay URL-only and are protected through their existing functional regressions rather than a separate performance suite.
• Keep existing WorkspaceOverviewContentTest, TenantRegistryRecoveryTriageTest, BackupSetListContinuityTest, and RestoreRunListContinuityTest green so source-route preservation and deeper continuity surfaces remain authoritative.
• No relation managers or destructive actions are added in this slice. Covered Filament surfaces are WorkspaceOverview, ListTenants, TenantDashboard, ListBackupSets, ListRestoreRuns, and ViewRestoreRun.
• Run the minimum focused Sail pack before completion: cd apps/platform && ./vendor/bin/sail artisan test --compact with the unit tests, the new arrival-context feature tests, the existing workspace overview and tenant-registry regressions, the backup or restore continuity regressions, the RBAC arrival-visibility test, the performance regression, then run Pint with cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
New request-scoped arrival-context contract and token codec	Workspace overview and tenant-registry triage already know why a tenant should open, but the dashboard currently loses that intent at the navigation boundary	Referrer-only inference is unreliable, scattered query params would sprawl across surfaces, and persisted triage sessions would add unnecessary storage and lifecycle cost

Proportionality Review

• Current operator problem: Operators arrive on the correct tenant but lose the portfolio triage reason, next step, and return path as soon as the tenant dashboard loads.
• Existing structure is insufficient because: Existing workspace attention items, summary metrics, and tenant-registry filters already compute concern family and destination choice, but none of them preserve that intent into the tenant dashboard render.
• Narrowest correct implementation: Add one small request-scoped arrival-context contract plus a bounded token codec and resolver, then render one additive dashboard continuity block using existing backup or restore destinations for deeper follow-up.
• Ownership cost created: One small support namespace, one additive dashboard widget or view, small URL propagation changes, and focused regression tests across overview, registry, and dashboard surfaces.
• Alternative intentionally rejected: Persisted triage sessions, a new recovery-confidence model, and a broad breadcrumb or navigation framework were rejected because they create new truth or new workflow machinery for a narrow continuity problem.
• Release truth: Current-release truth. The feature hardens an existing operator workflow without adding new posture semantics or persistence.