# Implementation Plan: Spec 401 - High-risk Admin Action Proof Pack **Branch**: `401-high-risk-admin-action-proof-pack` | **Date**: 2026-06-22 | **Spec**: `specs/401-high-risk-admin-action-proof-pack/spec.md` **Input**: Feature specification from `specs/401-high-risk-admin-action-proof-pack/spec.md` ## Summary Prepare a targeted proof and minimal-hardening implementation package over existing restore, backup, and provider setup/detail admin flows. The implementation must first inventory current actions and tests, then build a proof map, add focused tests and browser proof for missing coverage, apply only minimal in-scope hardening defects, and close out with evidence that no new surfaces, concepts, persisted truth, or completed-spec rewrites were introduced. ## Technical Context **Language/Version**: PHP 8.4.15, Laravel 12.52.0, Filament 5.2.1, Livewire 4.1.4. **Primary Dependencies**: Laravel, Filament v5, Livewire v4, Pest 4, PostgreSQL via Sail, existing Spec Kit artifacts, Product Surface Contract, existing OperationRun/audit/evidence/provider/restore/backup support classes. **Storage**: No new database table, migration, persisted product truth, or storage disk expected. Existing tables inspected or touched by tests include `restore_runs`, `backup_sets`, `backup_items`, `backup_schedules`, `provider_connections`, `managed_environment_permissions`, `operation_runs`, `audit_logs`, and `evidence_snapshots`. **Testing**: Pest Feature/Filament/Livewire tests, Unit tests only where derived state helpers need proof, and one focused Pest Browser smoke. **Validation Lanes**: confidence + browser; fast-feedback for pure unit/helper tests; PostgreSQL only if implementation unexpectedly touches PostgreSQL-specific behavior; no heavy-governance lane unless proof map reveals a structural guard need and spec is updated. **Target Platform**: TenantPilot Laravel monolith under `apps/platform`; Spec Kit package under `specs/401-high-risk-admin-action-proof-pack/`. **Project Type**: Laravel web application with Filament admin UI. **Performance Goals**: No material query or browser-suite expansion. Focused tests should prove high-risk behavior without becoming a broad audit. **Constraints**: Existing surfaces only; no new routes/pages/navigation/panels/product concepts/status families/persistence/frameworks; no completed-spec rewrites; no external Graph calls in tests/browser proof. **Scale/Scope**: Three high-risk domains: restore preview/readiness/execution, backup schedules/sets/runs, provider setup/detail/readiness/permissions. ## Candidate Selection And Gate Result - **Candidate source**: direct user-provided Spec 401 draft. - **Auto queue status**: `docs/product/spec-candidates.md` reports no safe automatic next-best-prep target; this is a manually supplied candidate. - **Completed-spec guardrail**: PASS. No `401-*` package existed before preparation. Related Specs 333, 335, 364, 390, 394, and 395-400 are read-only context. - **Smallest slice**: proof map + focused tests + minimal hardening for existing high-risk actions only. - **Close alternatives deferred**: management-report PDF runtime validation, governance artifact lifecycle, provider onboarding redesign, cross-domain indicator follow-through, and reopening recent completed specs. ## Repository Surfaces Likely Affected Restore: ```text apps/platform/app/Filament/Resources/RestoreRunResource.php apps/platform/app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php apps/platform/app/Filament/Resources/RestoreRunResource/Pages/ViewRestoreRun.php apps/platform/app/Filament/Resources/RestoreRunResource/Pages/ListRestoreRuns.php apps/platform/app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunCreatePresenter.php apps/platform/app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunDetailPresenter.php apps/platform/resources/views/filament/forms/components/restore-run-*.blade.php apps/platform/resources/views/filament/infolists/entries/restore-*.blade.php apps/platform/app/Jobs/ExecuteRestoreRunJob.php apps/platform/app/Support/Operations/Reconciliation/RestoreExecuteReconciliationAdapter.php apps/platform/app/Services/Intune/RestoreService.php apps/platform/app/Services/Intune/RestoreRiskChecker.php apps/platform/app/Services/AssignmentRestoreService.php ``` Backup: ```text apps/platform/app/Filament/Resources/BackupScheduleResource.php apps/platform/app/Filament/Resources/BackupScheduleResource/Pages/* apps/platform/app/Filament/Resources/BackupScheduleResource/RelationManagers/BackupScheduleOperationRunsRelationManager.php apps/platform/app/Filament/Resources/BackupSetResource.php apps/platform/app/Filament/Resources/BackupSetResource/Pages/* apps/platform/app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php apps/platform/app/Jobs/RunBackupScheduleJob.php apps/platform/app/Jobs/AddPoliciesToBackupSetJob.php apps/platform/app/Jobs/RemovePoliciesFromBackupSetJob.php apps/platform/app/Services/BackupScheduling/* apps/platform/app/Services/AssignmentBackupService.php apps/platform/app/Support/BackupHealth/* apps/platform/app/Support/BackupQuality/* ``` Provider: ```text apps/platform/app/Filament/Resources/ProviderConnectionResource.php apps/platform/app/Filament/Resources/ProviderConnectionResource/Pages/* apps/platform/app/Filament/Pages/EnvironmentRequiredPermissions.php apps/platform/resources/views/filament/infolists/entries/provider-*.blade.php apps/platform/resources/views/filament/widgets/provider-connections/provider-readiness-guidance.blade.php apps/platform/app/Services/Providers/* apps/platform/app/Support/Providers/* apps/platform/app/Services/Intune/ManagedEnvironmentPermissionService.php apps/platform/app/Services/Intune/ManagedEnvironmentRequiredPermissionsViewModelBuilder.php apps/platform/app/Jobs/ProviderConnectionHealthCheckJob.php ``` Shared proof and safety: ```text apps/platform/app/Filament/Pages/Monitoring/Operations.php apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php apps/platform/app/Filament/Pages/Monitoring/AuditLog.php apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php apps/platform/app/Support/OpsUx/* apps/platform/app/Support/OperationRunLinks.php apps/platform/app/Services/OperationRunService.php apps/platform/app/Services/Audit/* apps/platform/app/Models/OperationRun.php apps/platform/app/Models/AuditLog.php ``` Likely test surfaces: ```text apps/platform/tests/Feature/Filament/Spec401HighRiskAdminActionProofPackTest.php apps/platform/tests/Feature/Operations/Spec401HighRiskAdminActionProofPackTest.php apps/platform/tests/Feature/ProviderConnections/Spec401HighRiskAdminActionProofPackTest.php apps/platform/tests/Feature/BackupScheduling/Spec401HighRiskAdminActionProofPackTest.php apps/platform/tests/Browser/Spec401HighRiskAdminActionProofPackSmokeTest.php specs/401-high-risk-admin-action-proof-pack/implementation-report.md ``` Exact test-file split may be adjusted during implementation to fit existing test organization, but every task must keep the Spec 401 prefix or report mapping. ## Implementation Method ### Phase 1 - Read-only inventory Record current branch, HEAD, dirty state, related routes, Filament resources/pages/actions, Livewire/Blade components, models, policies/gates/capabilities, migrations/schema, existing tests, and recent spec evidence. Do not edit runtime files before the proof map exists. ### Phase 2 - Proof gap mapping Create a Spec 401 proof map in `implementation-report.md` or a spec-local `proof-map.md` if the map is too large. Each row must include: ```text Flow State Existing proof Missing proof Fix needed? Test needed? Browser proof needed? Out of scope? Classification ``` ### Phase 3 - Tests first Add or update tests in this preferred order: 1. Authorization/direct-invocation tests. 2. State semantics tests. 3. Confirmation/cancel tests. 4. Audit/evidence side-effect tests. 5. Browser smoke proof. ### Phase 4 - Minimal hardening Fix only confirmed in-scope defects required by existing product contracts. Acceptable fixes include missing confirmation, missing server-side authorization, stale action execution guard, wrong partial/failed/blocking display, false audit/evidence creation, or raw detail exposure on default product paths. Stop and update spec/plan if a fix requires new surfaces, new persistence, new status vocabulary, broad resource decomposition, or a new architecture layer. ### Phase 5 - Browser proof and close-out Run focused browser proof for restore, backup, provider, and one unauthorized/blocked path. Complete implementation report with files changed, tests, browser proof, states proven/deferred, Product Surface fields, deployment impact, no completed-spec rewrite assertion, and visible complexity outcome. ## UI / Surface Guardrail Plan - **Guardrail scope**: existing high-risk operator-facing surfaces may be minimally hardened. - **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: RestoreRun create/view/list, BackupSchedule list/create/edit/run, BackupSet list/create/view/items, ProviderConnection list/create/view/edit, EnvironmentRequiredPermissions, OperationRun/audit/evidence links where already exposed. - **No-impact class**: N/A. - **Native vs custom classification summary**: mixed. Prefer native Filament actions/resources and shared primitives; existing custom Blade/presenter fragments may be touched only when proof gaps require it. - **Shared-family relevance**: destructive/high-impact actions, OperationRun links/start UX, provider readiness, restore readiness, backup quality, audit/evidence links, status messaging. - **State layers in scope**: page, detail, modal/action, table/relation manager, and route/query context. Shell/navigation/panel state is out of scope unless implementation finds a direct high-risk action leak. - **Audience modes in scope**: operator-MSP and support-platform. No new customer-facing surface. - **Decision/diagnostic/raw hierarchy plan**: decision-first default; diagnostics and raw/support proof hidden, demoted, or capability-gated. - **Raw/support gating plan**: keep raw provider payloads, credentials, source keys, raw evidence, raw backup payloads, and technical logs out of default product surfaces. - **One-primary-action / duplicate-truth control**: each changed surface keeps one dominant next safe action and avoids duplicate readiness/status summaries. - **Handling modes by drift class or surface**: in-scope proof gaps are fixed if safe and bounded; missing product contracts become `document-in-feature` or `follow-up-spec`; broad architecture becomes stop condition. - **Repository-signal treatment**: review-mandatory for high-risk actions; exception-required for any Product Surface budget or action-contract deviation. - **Special surface test profiles**: dangerous-workflow wizard, shared-detail-family, monitoring-state-page, standard-native-filament where applicable. - **Required tests or manual smoke**: Feature/Filament tests plus focused browser smoke. - **Exception path and spread control**: none planned. Exceptions must be named in the implementation report. - **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage. - **UI/Productization coverage decision**: existing coverage remains valid by default; update coverage artifacts only if implementation materially changes surface classification or finds registry drift. - **Coverage artifacts to update**: none planned. - **No-impact rationale**: N/A. - **Screenshot or page-report need**: focused browser proof required; full page reports not required by default. ## Product Surface Contract Plan - **Product Surface Contract reference**: `docs/product/standards/product-surface-contract.md`. - **No-legacy posture**: clean canonical behavior; no compatibility shims or legacy fixtures by default. - **Page archetype and surface budget plan**: keep existing archetypes; document any materially touched surface as Wizard, Receipt, Search/Index, Settings, Decision sub-surface, or Technical Annex; expect pass. - **Technical Annex and deep-link demotion plan**: OperationRun/raw evidence/raw IDs/source keys/fingerprints/payloads/logs remain secondary, internal, or gated. - **Canonical status vocabulary plan**: visible product statuses map to existing Product Surface vocabulary. No new status family. - **Product Surface exceptions**: none planned. - **Browser verification plan**: focused Spec 401 browser smoke over restore, backup, provider, and one unauthorized/blocked path. - **Human Product Sanity plan**: complete in implementation report. - **Visible complexity outcome target**: neutral or decreased. - **Implementation report target**: `specs/401-high-risk-admin-action-proof-pack/implementation-report.md` unless final response carries the full report and the operator accepts no file output. ## Filament / Livewire / Deployment Posture - **Livewire v4 compliance**: Livewire 4.1.4 confirmed by Laravel Boost; no Livewire v3 APIs allowed. - **Panel provider registration location**: `apps/platform/bootstrap/providers.php`; no panel provider change expected. - **Global search posture**: no global search change expected. Any touched globally searchable resource must have View/Edit plus `$recordTitleAttribute`, or global search disabled. - **Destructive/high-impact action posture**: - Touched destructive/high-impact actions must execute through `Action::make(...)->action(...)`. - Touched destructive/high-impact actions must include `->requiresConfirmation()`. - Backup action proof must classify each touched backup action by existing contract source before asserting whether confirmation is required. - URL-only actions remain navigation-only and are not confirmation-protected. - Server-side Gate/Policy authorization and audit/proof side effects must be tested. - **Asset strategy**: no new assets. No `FilamentAsset` registration and no `filament:assets` deployment change expected. - **Testing plan**: Feature/Filament action tests, direct authorization/action execution tests, audit/evidence side-effect tests, state semantics tests, focused browser smoke. - **Deployment impact**: none expected for env vars, migrations, queues, scheduler, storage, assets, provider scopes, or Dokploy. If an existing job/action path is touched, document queue impact but do not add new workers. ## Shared Pattern & System Fit - **Cross-cutting feature marker**: yes. - **Systems touched**: existing Filament action APIs, `UiEnforcement` / `WorkspaceUiEnforcement`, policies/gates, OperationRun UX, provider readiness, restore readiness, backup quality/health, audit/evidence links. - **Shared abstractions reused**: existing helpers/services/presenters should be reused before adding local logic. - **New abstraction introduced? why?**: none planned. A small local test helper is allowed only if it reduces duplicated test setup and stays explicit. - **Why existing abstractions are sufficient or insufficient**: existing action, authorization, OperationRun, provider, restore, backup, and audit paths cover the proof categories. The gap is evidence coverage, not a missing runtime framework. - **Bounded deviation / spread control**: any local deviation must be documented in the implementation report and must not create a parallel operator-facing language. ## OperationRun UX Impact - **Touches OperationRun start/completion/link UX?**: yes where existing restore/backup/provider actions create, queue, block, complete, reconcile, or link runs. - **Central contract reused**: existing OperationRun Start UX Contract, `OperationUxPresenter`, `OperationRunLinks`, `OperationRunService`, `OperationRunCompleted`. - **Delegated UX behaviors**: queued toast, run link, artifact link, browser event, dedupe/blocked/start-failure messaging, tenant/workspace-safe URL resolution, terminal notification. - **Surface-owned behavior kept local**: domain input collection, confirmation copy, and proof display. - **Queued DB-notification policy**: unchanged; no new queued DB notification. - **Terminal notification path**: central lifecycle mechanism. - **Exception path**: none planned. ## Provider Boundary & Portability Fit - **Shared provider/platform boundary touched?**: yes. - **Provider-owned seams**: Microsoft/Intune/Entra connection details, provider verification reports, required Graph permission evidence, provider errors, provider credentials/consent. - **Platform-core seams**: workspace, managed environment, provider connection reference, operation, evidence, audit, readiness, blocked/failed/expired state display, action authorization. - **Neutral platform terms / contracts preserved**: workspace, managed environment, provider, connection, operation, evidence, audit trail, backup, restore, readiness. - **Retained provider-specific semantics and why**: current runtime is Microsoft-backed; provider-specific details stay in technical/provider-owned layers. - **Bounded extraction or follow-up path**: follow-up-spec only if proof uncovers structural provider coupling beyond this minimal hardening slice. ## Domain / Model Implications No new model, migration, enum, table, persisted artifact, provider integration, Graph contract, operation type, queue, scheduler, or customer-output artifact is expected. Existing model relationships and policies must be inspected before tests/hardening. If a required test cannot be written because ownership or scope is ambiguous, record product-decision debt. ## RBAC / Security / Audit Implications - Non-members and wrong-scope actors remain 404. - Members missing capability remain 403 or disabled/hidden per current UI enforcement. - Direct action invocation must be tested; hidden buttons are not proof. - Mutating actions must write audit entries where existing contracts require audit. - Cancelled and forbidden actions must not write successful audit/evidence/OperationRun proof. - Provider credentials, raw tokens, raw provider payloads, raw tenant data, and secrets must never appear in tests, logs, screenshots, or implementation reports. ## OperationRun / Evidence / Result Truth Implications The implementation must distinguish: - **Execution truth**: `OperationRun` status/outcome/summary/failure/audit trail. - **Artifact truth**: evidence snapshots, stored report/review artifacts where already linked. - **Backup/snapshot truth**: backup sets/items/schedules and immutable captured payload truth. - **Recovery/evidence truth**: restore preview/readiness/result, stale/failed/partial proof, provider prerequisites. - **Operator next action**: the single safe action or blocked/deferred state shown to the operator. No product surface may collapse these truths into one false success state. ## Constitution Check - Inventory-first: PASS. Existing inventory/backup/provider/restore truth remains authoritative. - Read/write separation: PASS planned. Restore/backup/provider mutations require preview/dry-run where existing, confirmation, audit, and tests. - Graph contract path: PASS planned. No new Graph calls; existing calls remain behind current abstractions. - Deterministic capabilities: PASS planned. Use existing capability registry/policies; no raw role checks. - RBAC-UX: PASS planned. Direct invocation tests cover 404/403 boundaries and server-side authorization. - Workspace isolation: PASS planned. Tests must prove workspace/environment scope. - Tenant isolation: PASS planned. No cross-tenant leakage or ID shortcuts. - Run observability: PASS planned. Existing long-running/high-impact operations use/reuse OperationRun; no new local run UX. - OperationRun start UX: PASS planned. Existing shared paths reused. - Ops-UX 3-surface feedback: PASS planned. No new queued DB notification or local terminal notification. - Data minimization: PASS planned. No secrets/raw provider payloads in output. - Test governance: PASS planned. Confidence + browser lanes are explicit and bounded. - Proportionality: PASS. Proof map/tests/minimal hardening are narrower than a framework. - No premature abstraction: PASS. No new runtime abstraction planned. - Persisted truth: PASS. No new persistence planned. - Behavioral state: PASS. Existing states/vocabulary only. - UI semantics: PASS. Use Product Surface vocabulary and existing shared badge/status paths. - Shared pattern first: PASS. Existing shared paths are named and preferred. - Provider boundary: PASS. Provider-specific semantics remain provider-owned. - V1 explicitness / few layers: PASS. Direct tests and local hardening only. - Spec discipline / bloat check: PASS. One coherent proof-pack spec instead of many micro-specs. - Filament-native UI: PASS planned. Native Filament/shared primitives first. - UI/Productization coverage: PASS planned. Existing surfaces only; coverage updates only if material classification drift appears. - Product Surface Contract Gate: PASS planned. Spec/plan/tasks name surfaces, browser proof, human sanity, destructive/high-impact actions, deployment impact, and no completed-spec rewrite assertion. ## Test Governance Check - **Test purpose / classification by changed surface**: Feature/Filament for action/authorization/state/audit proof; Browser for focused rendered workflow proof; Unit only for derived state helpers if touched. - **Affected validation lanes**: confidence + browser; fast-feedback for unit-only changes; PostgreSQL only if database-specific behavior changes unexpectedly. - **Why this lane mix is the narrowest sufficient proof**: Direct action behavior and side effects require Feature/Filament tests. Rendered confirmation/status behavior needs focused Browser smoke. Broad heavy-governance is not needed for a bounded proof pack. - **Narrowest proving command(s)**: - `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec401HighRiskAdminActionProofPackTest.php tests/Feature/Operations/Spec401HighRiskAdminActionProofPackTest.php tests/Feature/ProviderConnections/Spec401HighRiskAdminActionProofPackTest.php tests/Feature/BackupScheduling/Spec401HighRiskAdminActionProofPackTest.php --compact` - `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec401HighRiskAdminActionProofPackSmokeTest.php --compact` - `cd apps/platform && ./vendor/bin/sail pint --dirty` - `git diff --check` - **Fixture / helper / factory / seed / context cost risks**: use existing explicit workspace/environment/provider/backup/restore fixtures; do not widen default setup. - **Expensive defaults or shared helper growth introduced?**: no planned; any helper must be opt-in. - **Heavy-family additions, promotions, or visibility changes**: one named focused browser smoke only. - **Surface-class relief / special coverage rule**: dangerous-workflow wizard and shared-detail-family for restore; standard-native-filament for ordinary lists/actions; monitoring-state-page where OperationRun proof is touched. - **Closing validation and reviewer handoff**: reviewers verify proof map completeness, task coverage, test commands/results, browser proof, no secrets/screenshots leak, Product Surface close-out, and no completed-spec rewrites. - **Budget / baseline / trend follow-up**: none expected; document-in-feature if browser fixture cost grows. - **Review-stop questions**: Did implementation add a new surface/status/persistence? Did cancelled/forbidden actions avoid success artifacts? Did direct invocation get tested? Did browser proof stay focused? Did raw detail remain demoted? - **Escalation path**: document-in-feature for contained proof gaps; follow-up-spec for structural missing product contracts; reject-or-split for broad redesign. - **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage. - **Why no dedicated follow-up spec is needed now**: this spec is the bounded proof pack. Follow-ups are created only for confirmed out-of-scope defects or product-decision gaps. ## Project Structure ### Spec Package ```text specs/401-high-risk-admin-action-proof-pack/ ├── spec.md ├── plan.md ├── tasks.md ├── checklists/ │ └── requirements.md └── implementation-report.md # created during implementation close-out if file output is used ``` ### Source Code ```text apps/platform/app/ ├── Filament/ ├── Jobs/ ├── Models/ ├── Policies/ ├── Services/ └── Support/ apps/platform/resources/views/ └── filament/ apps/platform/tests/ ├── Feature/ ├── Unit/ └── Browser/ ``` **Structure Decision**: Use existing Laravel/Filament monolith structure. Do not create new base folders. New tests should live in existing test families with Spec 401 naming. ## Complexity Tracking No constitution violation is planned. | Potential Complexity | Decision | Simpler Alternative | |---|---|---| | Cross-domain proof map | Allowed as spec-local review evidence | One-off local notes would not cover all high-risk domains consistently | | Focused browser smoke | Allowed because rendered high-risk flows are in scope | Feature tests alone cannot prove browser/Livewire/Filament runtime behavior | | Minimal runtime hardening | Allowed only after failing/missing proof confirms an in-scope defect | Broad refactor or framework explicitly rejected | ## Implementation Phases 1. Safety, inventory, and proof map. 2. Restore tests and minimal hardening. 3. Backup tests and minimal hardening. 4. Provider tests and minimal hardening. 5. Cross-domain browser proof. 6. Implementation report and validation. ## Stop Conditions Stop and update spec/plan before continuing if: - implementation requires a new persisted entity/table/artifact; - implementation requires a new enum/status/reason family; - implementation requires a new route/page/navigation group/panel; - implementation requires a broad restore, backup, provider, OperationRun, or Product Surface framework; - a required state lacks a product contract and cannot be safely derived from repo truth; - unrelated dirty state appears; - browser/test fixture work expands into a broad audit; - any completed spec would need to be rewritten to make the proof pass. ## Rollout / Deployment Considerations - **Staging**: run focused tests and browser smoke before staging validation if runtime code changes. - **Production**: no special production rollout expected. If existing high-impact action behavior changes, release notes should call out safer confirmation/authorization/state handling. - **Migrations**: none expected. - **Env vars**: none expected. - **Queues**: existing queue workers only; no new queue class expected unless minimal hardening touches existing jobs. - **Scheduler**: no change expected. - **Storage**: no change expected. - **Assets**: no new assets; `filament:assets` unchanged. ## Risk Controls - Tests before fixes wherever feasible. - Direct invocation tests, not only hidden/disabled UI assertions. - Separate execution truth from backup/artifact/evidence truth. - Treat missing product contract as finding, not implementation invitation. - Keep browser proof focused and evidence-backed. - Preserve historical spec close-out and validation history.