TenantAtlas/specs/043-cross-tenant-compare-and-promotion/plan.md

Implementation Plan: Cross-Tenant Compare Preview and Promotion Preflight

Branch: 043-cross-tenant-compare-and-promotion | Date: 2026-04-27 | Spec: spec.md Input: Feature specification from spec.md

Summary

Refresh Spec 043 into a narrow, implementation-ready workflow that adds one canonical workspace-context compare page under /admin, one reusable compare preview builder, and one read-only promotion preflight action. The slice reuses existing baseline compare subject identity, portfolio-triage context continuity, capability resolvers, and workspace audit logging. It deliberately stops before actual promotion execution, queueing, or persisted promotion drafts.

Filament remains on Livewire v4, no panel-provider registration changes are required (bootstrap/providers.php remains the authoritative provider registration location), no globally searchable compare resource is added, and no new panel asset bundle is expected.

Technical Context

Language/Version: PHP 8.4, Laravel 12
Primary Dependencies: Filament v5, Livewire v4, Pest v4, existing baseline compare services, portfolio-triage seams, audit services, and capability resolvers
Storage: PostgreSQL via existing inventory, policy-version, and audit tables; no new compare or promotion table
Testing: Pest v4 Unit and Feature coverage only
Validation Lanes: fast-feedback, confidence
Target Platform: Laravel monolith in apps/platform, admin panel only (/admin)
Project Type: Web application (Laravel monolith with Filament pages)
Performance Goals: compare preview and promotion preflight stay synchronous and derived from existing persisted truth; no background execution path in v1
Constraints: no target mutation, no OperationRun, no queue, no new persisted draft, no cross-workspace compare, no raw payload view by default
Scale/Scope: 2 tenant selectors, 1 canonical compare page, 1 preflight action, 1 launch/return continuity path, focused reuse of existing compare builders

UI / Surface Guardrail Plan

• Guardrail scope: one new canonical compare page plus one launch action from existing tenant-registry/portfolio context
• Native vs custom classification summary: native Filament page with shared compare/audit/navigation primitives
• Shared-family relevance: canonical admin pages, compare drill-down patterns, launch actions, audit-backed modal/action copy
• State layers in scope: page, query state
• Audience modes in scope: operator-MSP only
• Decision/diagnostic/raw hierarchy plan: decision-first compare summary, diagnostics second, raw evidence stays on existing tenant/baseline surfaces
• Raw/support gating plan: no new raw/support surface; keep payload proof behind existing pages
• One-primary-action / duplicate-truth control: the compare page keeps one dominant next action, Generate promotion preflight; drill-down and return actions stay secondary
• Launch default: the tenant-registry launch action prefills the launched tenant as target tenant; the operator chooses the source tenant explicitly
• Handling modes by drift class or surface: review-mandatory; any actual promotion execution or queue path is exception-required and out of scope
• Repository-signal treatment: review-mandatory
• Special surface test profiles: standard-native-filament
• Required tests or manual smoke: functional-core, state-contract
• Exception path and spread control: none
• Active feature PR close-out entry: Guardrail

Shared Pattern & System Fit

• Cross-cutting feature marker: yes
• Systems touched:
  • App\Filament\Pages\BaselineCompareLanding
  • App\Filament\Pages\BaselineCompareMatrix
  • App\Filament\Resources\TenantResource
  • App\Filament\Resources\TenantResource\Pages\ListTenants
  • App\Services\Baselines\BaselineCompareService
  • App\Support\Baselines\BaselineCompareMatrixBuilder
  • App\Support\Baselines\Compare\CompareStrategyRegistry
  • App\Services\PortfolioTriage\TenantTriageReviewService
  • App\Services\Audit\WorkspaceAuditLogger
  • App\Support\Audit\AuditActionId
  • App\Support\Navigation\CanonicalNavigationContext
• Shared abstractions reused: capability resolvers, baseline compare strategy selection, canonical navigation context, existing audit recorder/logger path, and tenant-registry return-state conventions
• New abstraction introduced? why?: one narrow compare preview builder and one narrow promotion preflight service, because no existing service accepts source+target tenant scope and computes promotion readiness without execution
• Why the existing abstraction was sufficient or insufficient: tenant-level baseline compare is sufficient for subject identity, evidence posture, and drill-down semantics, but insufficient for dual-tenant scope and promotion-readiness reasoning
• Bounded deviation / spread control: no local compare sidecars on tenant pages; future callers must route through the canonical compare page and its services

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: no
• Central contract reused: N/A
• Delegated UX behaviors: N/A
• Surface-owned behavior kept local: compare preview and preflight remain synchronous and read-only
• Queued DB-notification policy: N/A
• Terminal notification path: N/A
• Exception path: none

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: yes
• Provider-owned seams: Microsoft-first inventory subject identity and policy-type mapping remain inside existing baseline compare strategy selection and inventory data
• Platform-core seams: source/target tenant scope, compare preview contract, promotion preflight contract, operator-facing readiness vocabulary
• Neutral platform terms / contracts preserved: source tenant, target tenant, governed subject, compare preview, promotion preflight, and blocked reason
• Retained provider-specific semantics and why: existing policy-type and inventory semantics remain Microsoft-first because this repo still has one real provider domain; the compare page should not invent fake provider-neutral mapping logic above that seam
• Bounded extraction or follow-up path: follow-up-spec only if later provider domains become current-release truth

Constitution Check

GATE: Must pass before implementation preparation continues.

• Inventory-first: PASS. Compare preview and preflight derive from existing inventory and policy-version truth rather than a new compare snapshot.
• Read/write separation: PASS. This slice stays read-only; no write execution is introduced.
• Graph contract path: PASS. No new Graph endpoint or direct provider call is added.
• Deterministic capabilities: PASS. Reuse existing capability registries such as Capabilities::TENANT_VIEW, Capabilities::WORKSPACE_BASELINES_VIEW, Capabilities::WORKSPACE_BASELINES_MANAGE, and existing tenant sync/manage seams.
• Workspace and tenant isolation: PASS. The compare page must resolve workspace membership first and source/target entitlement second, with 404 for inaccessible tenants.
• RBAC-UX plane separation: PASS. This slice lives only in /admin; no /system or cross-plane route is introduced.
• Destructive action discipline: PASS by non-use. The slice contains no destructive action.
• Global search: PASS. No new Resource or Global Search result is introduced.
• OperationRun / Ops-UX: PASS by non-use. Actual promotion execution is deferred.
• Data minimization: PASS. The compare page summarizes derived readiness and blocks; raw payloads stay on existing tenant/baseline pages.
• Test governance: PASS. Proof stays in Unit plus Feature; no browser or heavy-governance expansion is planned.
• Proportionality / no premature abstraction: PASS. One preview builder and one preflight service are justified by the dual-tenant workflow; no new persistence or framework layer is added.
• Persisted truth: PASS. No new compare or promotion table.
• Behavioral state: PASS. Readiness and blocked reasons remain derived, not persisted.
• Shared pattern first / UI semantics / Filament-native UI: PASS. Existing compare, navigation, and audit paths are extended rather than replaced.
• Provider boundary: PASS. Microsoft-shaped subject matching stays in existing strategy seams; the page contract stays platform-neutral.
• Filament/Laravel panel safety: PASS. Filament v5 remains on Livewire v4, no provider registration change beyond bootstrap/providers.php, and no new assets are planned.

Gate evaluation: PASS.

Test Governance Check

• Test purpose / classification by changed surface: Feature for the compare page, launch context, auth, and audit; Unit for compare preview matching and promotion-preflight classification
• Affected validation lanes: fast-feedback, confidence
• Why this lane mix is the narrowest sufficient proof: feature tests prove the Filament page and launch path while unit tests keep preview/preflight rules cheap and isolated. Browser or heavy-governance coverage is not required for the first read-only slice.
• Narrowest proving command(s):
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/PortfolioCompare/CrossTenantComparePreviewBuilderTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/PortfolioCompare/CrossTenantPromotionPreflightTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/PortfolioCompare/CrossTenantComparePageTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/PortfolioCompare/CrossTenantCompareAuthorizationTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/PortfolioCompare/CrossTenantPromotionPreflightAuditTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/PortfolioCompare/CrossTenantCompareLaunchContextTest.php
• Fixture / helper / factory / seed / context cost risks: reuse existing inventory, baseline compare, tenant registry, and portfolio-triage fixtures; avoid browser setup, queue fixtures, or seeded promotion history
• Expensive defaults or shared helper growth introduced?: no
• Heavy-family additions, promotions, or visibility changes: none
• Surface-class relief / special coverage rule: standard-native-filament
• Closing validation and reviewer handoff: rerun the six focused commands above and confirm the slice remains read-only, deny-as-not-found-safe, and grounded on existing compare + portfolio seams
• Budget / baseline / trend follow-up: none expected
• Review-stop questions: lane fit, hidden fixture growth, accidental write execution, accidental queue/runtime scope
• Escalation path: document-in-feature for contained lane drift, reject-or-split for any attempt to add execution scope
• Active feature PR close-out entry: Guardrail
• Why no dedicated follow-up spec is needed: test upkeep remains feature-local; only actual promotion execution or multi-provider compare would warrant a separate follow-up spec

Project Structure

Documentation (this feature)

specs/043-cross-tenant-compare-and-promotion/
├── checklists/
│   └── requirements.md
├── spec.md
├── plan.md
└── tasks.md

This refresh intentionally limits itself to the core preparation package plus checklists/requirements.md. No additional research/data-model/contracts artifact is required to make the narrowed slice implementation-ready.

Source Code (repository root)

apps/platform/
├── app/
│   ├── Filament/Pages/
│   │   ├── BaselineCompareLanding.php
│   │   ├── BaselineCompareMatrix.php
│   │   └── [new canonical compare page]
│   ├── Filament/Resources/TenantResource.php
│   ├── Filament/Resources/TenantResource/Pages/ListTenants.php
│   ├── Models/
│   │   ├── InventoryItem.php
│   │   └── PolicyVersion.php
│   ├── Services/Audit/
│   │   └── WorkspaceAuditLogger.php
│   ├── Services/Baselines/
│   │   └── BaselineCompareService.php
│   ├── Services/PortfolioTriage/
│   │   └── TenantTriageReviewService.php
│   ├── Support/Audit/AuditActionId.php
│   ├── Support/Baselines/
│   │   ├── BaselineCompareMatrixBuilder.php
│   │   └── Compare/CompareStrategyRegistry.php
│   └── Support/PortfolioCompare/ or Services/PortfolioCompare/
└── tests/
		├── Feature/PortfolioCompare/
		└── Unit/Support/PortfolioCompare/

Structure Decision: keep implementation inside apps/platform, reuse existing compare and portfolio seams, and introduce at most one small PortfolioCompare support/service namespace for the new dual-tenant preview/preflight logic.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
New compare preview builder	dual-tenant compare needs one place to translate existing inventory/baseline truth into a canonical preview contract	page-local mapping would duplicate compare logic and drift from existing baseline compare seams
New promotion preflight service	readiness reasoning must stay read-only and auditable before any execution path exists	bolting readiness rules into the page would make later reuse and testing brittle

Proportionality Review

• Current operator problem: portfolio operators still lack one bounded surface that answers whether a target tenant can follow a source tenant.
• Existing structure is insufficient because: existing baseline compare is tenant-vs-reference, not tenant-vs-tenant, and portfolio triage does not compute promotion readiness.
• Narrowest correct implementation: one canonical page plus one preview builder and one preflight service, no new table, no execution path.
• Ownership cost created: maintain a small preview/preflight contract and a focused test family.
• Alternative intentionally rejected: actual promotion execution, persisted promotion drafts, and local compare sidecars were rejected as premature.
• Release truth: current-release gap, not speculative platform work.

Implementation Strategy

Suggested MVP Scope

MVP = US1 + US2 together. A compare page without a promotion preflight leaves the core decision incomplete, and a preflight without a canonical compare page has no trustworthy operator context.

Incremental Delivery

1. Reuse current compare, navigation, capability, and audit seams.
2. Deliver the canonical compare preview.
3. Add the read-only promotion preflight on top of the same page and services.
4. Add launch/return continuity from portfolio-triage and tenant-registry context.
5. Finish with narrow validation and formatting.

Team Strategy

1. Settle the preview/preflight contracts first.
2. Parallelize unit tests for preview/preflight rules and feature tests for page/auth behavior.
3. Serialize merges around the canonical compare page and the shared PortfolioCompare service namespace so the page contract does not drift.