TenantAtlas/specs/412-pilot-readiness-remediation-pack/plan.md

Implementation Plan: Spec 412 - Pilot Readiness Remediation Pack

Branch: 412-pilot-readiness-remediation-pack | Date: 2026-06-24 | Spec: specs/412-pilot-readiness-remediation-pack/spec.md Input: Feature specification from specs/412-pilot-readiness-remediation-pack/spec.md

Summary

Prepare a bounded remediation implementation over four Spec 407 pilot-readiness findings. The future implementation must fix ready management PDF surfacing, prove operations routes complete browser navigation, demote raw finding hashes from default detail content, and clarify readonly provider-connection no-access outcomes. It must reuse existing Laravel/Filament/Livewire/report/OperationRun/RBAC surfaces, add focused Pest and browser proof, produce an implementation report with the required matrices, and avoid new surfaces, new product concepts, broad architecture, or completed-spec rewrites.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12.52.0 Primary Dependencies: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, Laravel Sail Storage: PostgreSQL; no new schema expected Testing: Pest feature/Filament/Livewire tests plus focused browser smoke Validation Lanes: fast-feedback, confidence, browser; PostgreSQL only if implementation unexpectedly changes PostgreSQL-specific database behavior Target Platform: Laravel monolith under apps/platform Project Type: web application with Filament admin/system panels Performance Goals: operations pages render with bounded DB-only work and no browser navigation timeout under focused local audit conditions Constraints: no new product surface, no full browser audit, no staging/Dokploy validation, no completed-spec rewrite, no Graph/external calls during render Scale/Scope: existing review/report, operations, finding, and provider-connection surfaces only

Repository Surfaces Likely Affected

Implementation must verify exact file ownership before editing, but current repo inventory identifies these likely surfaces:

• apps/platform/app/Filament/Resources/ReviewPackResource.php
• apps/platform/app/Filament/Resources/ReviewPackResource/Pages/ViewReviewPack.php
• apps/platform/app/Services/ReviewPacks/ManagementReportPdfService.php
• apps/platform/app/Http/Controllers/ManagementReportPdfDownloadController.php
• apps/platform/app/Http/Controllers/ReviewPackDownloadController.php
• apps/platform/app/Http/Controllers/ReviewPackRenderedReportController.php
• apps/platform/app/Filament/Pages/Monitoring/Operations.php
• apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
• apps/platform/resources/views/filament/pages/monitoring/operations.blade.php
• apps/platform/resources/views/filament/pages/operations/tenantless-operation-run-viewer.blade.php
• apps/platform/app/Filament/Resources/FindingResource.php
• apps/platform/app/Filament/Resources/ProviderConnectionResource.php
• route and middleware behavior in apps/platform/routes/web.php and related workspace/provider auth middleware only if inventory proves the no-access issue lives there
• existing tests under apps/platform/tests/Feature/ReviewPack/, apps/platform/tests/Feature/Monitoring/, apps/platform/tests/Feature/Operations/, apps/platform/tests/Feature/Filament/, apps/platform/tests/Feature/ProviderConnections/, and finding-focused tests

No runtime file outside these related surfaces should be changed without updating this plan first.

UI / Surface Guardrail Plan

• Guardrail scope: changed existing surfaces only.
• Affected routes/pages/actions/states/navigation/panel/provider surfaces: review pack detail management PDF action state, signed report/PDF downloads, operations index/detail, finding detail default body, provider connection no-access outcome.
• No-impact class, if applicable: N/A.
• Native vs custom classification summary: native Filament plus existing shared primitives; avoid custom UI framework/styling.
• Shared-family relevance: reports/downloads, status messaging, technical detail disclosure, OperationRun links, authorization/no-access messaging.
• State layers in scope: detail action state, signed route state, page load/readiness, default-vs-technical detail disclosure, route/authorization outcome.
• Audience modes in scope: operator-MSP, readonly/customer-safe where exposed, support-platform for technical detail.
• Decision/diagnostic/raw hierarchy plan: product decision first; diagnostics second; support/raw evidence collapsed or gated.
• Raw/support gating plan: demote hashes and raw identifiers into collapsed/support/operator-only technical detail if retained.
• One-primary-action / duplicate-truth control: ready PDF produces one ready/download/open action; generate is not primary when a valid ready PDF exists.
• UI Action Matrix handling: use the spec's UI Action Matrix as the action-placement source for header, row, bulk, empty-state, primary, secondary, destructive, and technical/audit actions across the four affected surfaces.
• Handling modes by drift class or surface: review-mandatory for all four included surfaces; exception-required for any Product Surface budget violation.
• Repository-signal treatment: report-only unless implementation discovers broad architecture mismatch, in which case stop and update spec/plan.
• Special surface test profiles: shared-detail-family, monitoring-state-page, exception-coded-surface.
• Required tests or manual smoke: feature/Filament/Livewire tests plus focused browser proof.
• Exception path and spread control: none approved.
• Active feature PR close-out entry: Product Surface / Focused Browser Proof / Pilot Readiness Remediation.
• UI/Productization coverage decision: no new reachable surface; existing surface behavior changed and proof captured in implementation report.
• Coverage artifacts to update: none expected because no new surface is introduced; update docs/ui-ux-enterprise-audit only if implementation materially changes route inventory, page archetype, navigation, or page structure beyond the approved remediation.
• No-impact rationale: N/A.
• Navigation / Filament provider-panel handling: no panel provider or navigation change expected.
• Screenshot or page-report need: focused screenshots/browser records required; full page reports are not required.

Product Surface Contract Plan

• Product Surface Contract reference: docs/product/standards/product-surface-contract.md.
• No-legacy posture: canonical correction; no compatibility aliases, fallback readers, duplicate UI, or old labels unless the spec is updated with an explicit exception.
• Page archetype and surface budget plan:
  • Review pack detail: Report/Receipt; one primary report/PDF action based on truth.
  • Operations index/detail: Technical Annex/Receipt; browser readiness and no raw diagnostics by default.
  • Finding detail: Decision/Secondary Context; raw hashes demoted.
  • Provider no-access: Settings denial outcome; clear and non-leaky.
• Technical Annex and deep-link demotion plan: OperationRun proof links, evidence IDs, fingerprints, source hashes, payloads, logs, and raw provider fields must not become default product content.
• Canonical status vocabulary plan: map report/readiness/status labels to allowed vocabulary (Ready, Needs attention, Blocked, Running, Failed, Expired, Not configured, Unknown, Historical, Superseded) or existing badge domains that already map to it.
• Product Surface exceptions: none approved.
• Browser verification plan: focused browser paths listed in spec.md.
• Human Product Sanity plan: record result in implementation-report.md.
• Visible complexity outcome target: decreased for review/finding/provider; neutral for operations.
• Implementation report target: specs/412-pilot-readiness-remediation-pack/implementation-report.md.

Filament / Livewire / Deployment Posture

• Livewire v4 compliance: Livewire 4.1.4 confirmed through Laravel Boost.
• Panel provider registration location: existing providers are registered in apps/platform/bootstrap/providers.php; no panel provider change expected.
• Global search posture: no resource should be newly globally searchable. Existing sensitive resources such as ReviewPackResource and ProviderConnectionResource keep global search disabled where applicable. If FindingResource global search is touched, it must have safe View/Edit coverage and tenant scoping or remain disabled according to repo rules.
• Destructive/high-impact action posture: no new destructive action. Existing management PDF generation is high-impact/queued and must keep ->action(...), confirmation, authorization, audit/OperationRun behavior, and tests.
• Asset strategy: no new assets expected; filament:assets is not required unless implementation registers new Filament assets, which is out of scope.
• Testing plan: Pest feature/Filament/Livewire tests for report/PDF state, signed download authorization, operations render/readiness, finding default body hash demotion, provider no-access semantics, plus focused browser smoke.
• Deployment impact: no env vars, migrations, scheduler, storage volumes, or queue topology changes expected. Existing queue/storage for management PDF remains relevant.

Shared Pattern & System Fit

• Cross-cutting feature marker: yes.
• Systems touched: report state/action links, signed downloads, OperationRun links/readiness, finding technical disclosure, provider authorization copy.
• Shared abstractions reused: ManagementReportPdfService, OperationUxPresenter, OperationRunLinks, BadgeRenderer, UiEnforcement / WorkspaceUiEnforcement, existing policies/middleware/controllers.
• New abstraction introduced? why?: none planned. A small local helper is acceptable only if it replaces repeated state checks in an existing surface and does not become a new framework.
• Why the existing abstraction was sufficient or insufficient: the repo already has report/PDF services, OperationRun helpers, badge domains, and RBAC helpers; defects are state selection/proof issues.
• Bounded deviation / spread control: none approved.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes, only existing management PDF generation run links/toasts and operations route readiness.
• Central contract reused: shared OperationRun UX layer, OperationUxPresenter, OperationRunLinks, OperationRunService.
• Delegated UX behaviors: queued toast, open/view run link, artifact link, browser event, dedupe/blocked messaging, tenant/workspace-safe URL resolution remain delegated.
• Surface-owned behavior kept local: local action visibility and initiation input only.
• Queued DB-notification policy: no new opt-in.
• Terminal notification path: central lifecycle mechanism.
• Exception path: none.

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: yes, bounded.
• Provider-owned seams: provider-connection detail and provider-specific readiness/diagnostics.
• Platform-core seams: workspace/environment membership, capability denial, no-access route outcome.
• Neutral platform terms / contracts preserved: workspace, managed environment, provider connection, access, permission, membership.
• Retained provider-specific semantics and why: Microsoft/provider labels remain only where existing provider connection UI already owns them.
• Bounded extraction or follow-up path: none expected; broader provider readiness remains a separate manual promotion item.

Constitution Check

GATE: Must pass before implementation. Re-check after any scope change.

• Inventory-first: no inventory truth changes expected.
• Read/write separation: report generation remains explicit/queued/confirmed; no new write action.
• Graph contract path: no Graph call during render; any existing Graph work stays behind services/jobs.
• Deterministic capabilities: no new capability registry entry expected; if one becomes necessary, update spec/plan first.
• RBAC-UX: non-member workspace/environment access remains 404/deny-as-not-found; member missing capability remains 403; UI visibility is not security.
• Workspace isolation: report, operation, finding, and provider records remain workspace/environment scoped.
• Tenant isolation: managed-environment-scoped reads/downloads remain entitled and non-leaky.
• Run observability: existing management PDF generation run remains observable through OperationRun; no new operation type planned.
• OperationRun start UX: no local queued toast/link/event composition.
• Ops-UX 3-surface feedback: no new DB notification policy.
• Ops-UX lifecycle: no direct status/outcome transition outside OperationRunService.
• Summary counts contract: no new summary count keys expected.
• Data minimization: no secrets, tokens, raw provider payloads, file paths, stack traces, fingerprints, or source hashes in customer/default content.
• Test governance: lane classification and focused browser proof are explicit.
• Proportionality: no new source of truth, entity, status family, taxonomy, or framework.
• Product Surface Contract: no raw technical identifiers in default product views; one dominant next action per affected decision context.
• Completed-spec guardrail: Specs 400-407 remain read-only context.

Implementation Phases

Phase 1 - Focused Inventory And Reproduction

Confirm dirty state, route list, relevant files, existing tests, and whether each Spec 407 finding reproduces locally. Document non-reproducible findings without expanding scope.

Phase 2 - Report/PDF State Remediation

Add focused tests first for ready, missing, failed, inconsistent, unauthorized, cross-workspace, signed, and unsigned report/PDF states. Fix only existing report/PDF state selection and action presentation so ready stored management PDFs surface as ready/downloadable.

Phase 3 - Operations Route Load Completion

Add/adjust tests around operations index/detail render, DB-only behavior, query bounds, and route readiness. Investigate browser/network behavior and fix only page behavior causing timeout, 500, Livewire fatal error, blocking request, heavy payload, or broken readiness signal.

Phase 4 - Finding Hash Demotion

Add default-body tests proving raw hashes are not prominent. Move fingerprints/scope/source hashes into existing technical/collapsed/support/operator detail if support workflows still need them.

Phase 5 - Readonly Provider No-Access Clarity

Add/adjust authorization tests for readonly, unauthorized, and cross-workspace actors. Improve copy/outcome without granting access or leaking record existence.

Phase 6 - Focused Browser Proof And Close-Out

Run focused browser paths, inspect console/network/runtime logs, complete required matrices, run targeted tests, and produce implementation report. Do not run or claim a full browser audit.

Data / Migration Plan

• No migration is expected.
• No new persisted entity, enum, state, or report artifact is approved.
• Existing StoredReport, ReviewPack, OperationRun, Finding, and ProviderConnection truth must be reused.
• If implementation discovers missing persisted truth is required, stop and update spec/plan before coding.

RBAC / Authorization Plan

• Preserve signed route authorization for report/PDF downloads.
• Preserve workspace and managed-environment entitlement checks for review packs, operation runs, findings, and provider connections.
• Prove unauthorized and cross-workspace direct URLs remain blocked.
• Prove readonly provider access remains denied while the outcome is clearer.
• Do not replace server-side authorization with UI hiding.

Audit / Observability Plan

• No new audit family expected.
• Existing management PDF generation/download audit behavior must remain intact.
• If a remediation changes high-impact action behavior, update existing audit tests or add targeted ones.
• Operations pages remain DB-only at render time and continue to use OperationRun as execution truth.

Test Strategy

• Review/PDF: add/update tests under apps/platform/tests/Feature/ReviewPack/, likely building on Spec379ManagementReportPdfTest, Spec404ManagementReportPdfRuntimeValidationTest, ReviewPackDownloadTest, and customer output route gate tests.
• Operations: add/update tests under apps/platform/tests/Feature/Monitoring/, apps/platform/tests/Feature/Operations/, and apps/platform/tests/Feature/Filament/ for render, DB-only, and route readiness.
• Finding detail: add/update finding resource/render tests under the existing finding/Filament test families.
• Provider no-access: add/update tests under apps/platform/tests/Feature/ProviderConnections/ for readonly/unauthorized/cross-workspace behavior.
• Browser: focused smoke only for the eight paths named in the spec.
• Final command set: targeted filters first, then the smallest broader relevant suite. Full suite is useful but not a substitute for focused proof.

Rollout Considerations

• No environment variable change expected.
• No migration expected.
• No queue topology change expected.
• Existing management PDF generation queue/storage behavior remains relevant.
• No filament:assets deployment step is introduced unless the implementation unexpectedly registers assets, which is out of scope.
• Staging/Dokploy runtime validation remains outside this pack.

Risk Controls

• Reproduce or validate each finding before fixing.
• Keep fixes local to existing surfaces and services.
• Add negative authorization tests before changing report/provider behavior.
• Treat non-member and cross-workspace cases as leakage risks.
• Browser proof must record route, actor, state, expected result, actual result, console/runtime/network outcome, and screenshots/log references where available.
• If any P0 is discovered, stop broadening and report it; do not hide it inside local remediation.

Candidate Selection Gate

PASS WITH NUMBERING DEVIATION. User directly supplied the candidate; it is bounded, roadmap-aligned, and not covered by an existing spec in this branch. Existing branch/spec numbering from other branches reserves 408 through 411, so this package uses 412.

Preparation Analyze Result

Manual preparation analysis is required because this repo exposes prompt/agent stubs for speckit.analyze but no local executable analyze command. The analysis must check:

• spec/plan/tasks/checklist consistency;
• completion guardrail for Specs 400-407;
• no application implementation;
• four-finding scope only;
• Product Surface Contract coverage;
• RBAC, workspace/environment isolation, OperationRun, evidence/result truth, and browser proof coverage;
• no new surface, concept, persisted truth, status family, or broad abstraction.

Spec Readiness Gate

PASS when spec.md, plan.md, tasks.md, and checklists/requirements.md remain aligned after manual preparation analysis. No product question blocks later implementation.