393 lines
27 KiB
Markdown
393 lines
27 KiB
Markdown
# 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.
|