TenantAtlas/specs/401-high-risk-admin-action-proof-pack/spec.md

Feature Specification: Spec 401 - High-risk Admin Action Proof Pack

Feature Branch: 401-high-risk-admin-action-proof-pack Created: 2026-06-22 Status: Draft / Ready for implementation preparation review Type: Targeted hardening / proof / regression spec Runtime posture: Existing-surface proof and minimal hardening only. No new product surfaces, no new product concepts, no broad restore, backup, or provider redesign. Input: User-provided Spec 401 draft from the Codex attachment, current repo truth, Product Surface Contract, Spec 400 product-contract audit context, roadmap/spec-candidate queue, and related Specs 333, 335, 364, 390, 394, and 395-400.

Candidate Selection Context

• Selected candidate: High-risk Admin Action Proof Pack.
• Source location: Direct user-provided Spec 401 draft attached to this request.
• Why selected: docs/product/spec-candidates.md currently reports no safe automatic next-best-prep target, but the operator supplied a direct manual candidate. The candidate follows the Spec 400 conclusion described in the draft: before broader runtime/browser audits or larger customer-facing claims, TenantPilot needs concrete proof that existing high-risk admin actions behave safely in failure, conflict, stale, partial, blocked, unauthorized, and confirmation/cancel states.
• Roadmap relationship: Supports the current productization and moat priorities by reducing operational and trust risk in restore, backup, and provider setup/detail flows before broader sellability or runtime-audit work proceeds.
• Close alternatives deferred:
  • Management Report PDF staging validation remains manual follow-through for Specs 378-380 and is unrelated to high-risk admin action proof.
  • Governance artifact lifecycle/retention runtime is broader product runtime work and not a proof pack for current admin actions.
  • Provider readiness onboarding productization is optional productization work; this spec proves and minimally hardens existing provider setup/detail behavior first.
  • Cross-domain indicator runtime follow-through is a broader semantic adoption lane, not a targeted confirmation/RBAC/audit proof package.
  • Reopening Specs 333, 335, 364, 390, 394, or 395-400 is forbidden. They are read-only context and dependency evidence.
• Completed-spec guardrail result:
  • No specs/401-high-risk-admin-action-proof-pack/ package or 401-high-risk-admin-action-proof-pack branch existed before this preparation.
  • Specs 333, 335, 364, 390, 394, 395, 396, 397, 398, 399, and 400 are related context only. Any close-out notes, validation results, completed task markers, browser proof, smoke history, and implementation reports in completed or active historical packages must not be rewritten, normalized, unchecked, or removed.
  • Existing restore/provider/backups specs prove important slices, but none replaces this cross-domain proof map for high-impact actions, direct invocation, confirmation cancel/accept, audit/evidence side effects, and focused browser proof across restore, backup, and provider setup/detail.
• Smallest viable implementation slice: Build a proof map for existing restore, backup, and provider flows; add or update focused Pest/Filament/Browser tests for missing proof; apply only minimal runtime hardening where tests reveal an in-scope defect; record states proven, deferred product-decision gaps, browser proof, and no-new-surface/no-completed-spec-rewrite evidence in a Spec 401 implementation report.
• Feature description for Spec Kit: Prove and minimally harden existing high-risk admin actions around restore, backup, and provider setup/detail flows so workspace/environment scoping, authorization, confirmation, cancellation, stale/blocked/partial/failed/conflict/expired states, audit/evidence side effects, and focused browser behavior are evidence-backed without adding new product surfaces or concepts.

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: TenantPilot has high-impact admin actions across restore, backup, and provider setup/detail flows, but current proof is spread across many specs, tests, and UI surfaces. Future agents may assume safety because pages exist, while direct invocation, cancellation, stale proof, partial outcomes, and audit/evidence side effects may not be fully proven for every critical path.
• Today's failure: A restore, backup, or provider setup action can appear safe from UI visibility or preview state alone, while unproven direct execution, missing confirmation, stale provider evidence, partial result handling, forbidden action behavior, or misleading audit/evidence creation remains possible.
• User-visible improvement: Operators and reviewers get evidence-backed confidence that high-risk actions either execute safely with audit/proof, stop honestly with clear state, or are explicitly marked as product-decision debt instead of being treated as implicitly safe.
• Smallest enterprise-capable version: One targeted proof pack over existing restore, backup, and provider setup/detail flows. Inventory current actions, map proof gaps, add focused tests and one bounded browser smoke, and make only minimal hardening fixes required to satisfy existing product contracts.
• Explicit non-goals: No new admin or customer surfaces, no new navigation, no restore architecture, no backup architecture, no provider onboarding redesign, no new status vocabulary, no JSON-to-JSONB work, no management PDF behavior, no governance lifecycle features, no broad UI redesign, no broad browser audit, no completed-spec rewrite.
• Permanent complexity imported: Focused tests, one browser smoke, a spec-local proof map/implementation report, and bounded fixes to existing action gates if confirmed. No new persisted truth, table, framework, enum/status family, provider integration, panel, or product vocabulary is expected.
• Why now: Spec 400 identified restore, backup, and provider setup as the highest-value bounded proof pack before broader runtime/UX audits. False confidence in these flows is higher risk than ordinary UI drift because the flows affect recovery, provider authority, and critical configuration evidence.
• Why not local: A local fix in one resource would not prove cancellation, forbidden direct invocation, stale/blocked state, audit/evidence side effects, and browser behavior across the high-risk action set. The proof must compare the three domains with the same safety criteria.
• Approval class: Core Enterprise.
• Red flags triggered: Multiple surfaces and proof categories. Defense: this is a narrow proof/hardening package, not a new framework; it uses existing surfaces, existing status vocabulary, existing capabilities, existing OperationRun/audit/evidence semantics, and focused tests.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 12/12
• Decision: approve as a bounded high-risk admin action proof pack.

Problem Statement

TenantPilot manages critical Intune configuration. Restore execution, backup scheduling/runs, backup set actions, and provider setup/detail actions can affect recovery posture, provider authority, evidence truth, and auditability.

This spec answers:

Can TenantPilot prove that existing high-risk admin actions behave safely and consistently across success, failure, stale, blocked, partial, expired, unauthorized, confirmation accepted, and confirmation cancelled states?

A flow is considered proven only when repo evidence exists: a focused test, browser proof, policy/action assertion, audit/evidence assertion, or a documented product-decision gap. Code that appears correct is not enough.

Product / Business Value

The proof pack reduces false productization confidence in the highest-risk admin flows. It also gives implementation reviewers a compact evidence set before larger browser/UX/runtime audits, customer-facing claims, or broader productization work proceed.

Primary Users / Operators

• Workspace owners/managers approving or supervising high-impact admin operations.
• Tenant/MSP operators running restore, backup, and provider setup workflows.
• Readonly or lower-capability users who must be blocked from mutation while still receiving safe read-only context where allowed.
• Engineering reviewers and future implementation agents validating high-risk action safety.
• Support/platform operators troubleshooting OperationRun, audit, provider, backup, or restore outcomes without raw-secret exposure.

Spec Scope Fields (mandatory)

• Scope: Existing workspace/managed-environment admin surfaces for restore, backup, provider setup/detail, OperationRun proof, evidence/audit references, and focused browser verification.
• Primary Routes / Surfaces:
  • Restore: existing RestoreRun list/create/view surfaces under App\Filament\Resources\RestoreRunResource.
  • Backup schedules: existing BackupSchedule list/create/edit/action surfaces under App\Filament\Resources\BackupScheduleResource.
  • Backup sets/items: existing BackupSet list/create/view and BackupItems relation surfaces under App\Filament\Resources\BackupSetResource.
  • Provider setup/detail/readiness: existing ProviderConnection list/create/view/edit surfaces under App\Filament\Resources\ProviderConnectionResource, App\Filament\Pages\EnvironmentRequiredPermissions, and existing provider readiness/detail view entries.
  • Operation/audit/evidence support: existing Monitoring Operations, OperationRun detail, Audit Log, Evidence Overview, and related resource links only where already shown by target flows.
• Data Ownership:
  • restore_runs remain restore request/result truth.
  • backup_sets, backup_items, and backup_schedules remain backup truth.
  • provider_connections, provider_credentials, and managed_environment_permissions remain provider/readiness/permission evidence truth.
  • operation_runs remain execution truth.
  • audit_logs remain audit trail truth.
  • evidence_snapshots and existing linked artifacts remain evidence truth when already repo-backed.
  • No new persisted entity/table/artifact is expected by default. A spec-local proof map or implementation report is allowed as review evidence.
• RBAC:
  • Workspace membership and managed-environment entitlement remain mandatory.
  • Non-member or wrong-scope access remains deny-as-not-found.
  • Member missing action capability remains 403 server-side and disabled/hidden per existing UI enforcement.
  • UI visibility is not authorization. Every high-risk action must be proven through direct invocation/action tests where feasible.

For canonical-view or mixed-scope surfaces:

• Default filter behavior when environment-context is active: Existing workspace/environment route context and page filters remain authoritative. Proof must verify target records belong to the active workspace/environment and do not fall back to unsafe session/global context.
• Explicit entitlement checks preventing cross-tenant leakage: Direct action execution, related OperationRun/evidence/audit links, global search posture, and scoped record resolution must not expose or mutate records outside the actor's entitled workspace/environment.

No Legacy / No Backward Compatibility Constraint (mandatory)

TenantPilot is pre-production for this spec. Clean current contract behavior is preferred over compatibility with old labels, legacy fixtures, or hidden fallback behavior.

• Compatibility posture: clean proof and minimal hardening over existing canonical behavior.
• Legacy aliases, fallback readers, hidden routes, duplicate UI, old labels, or historical fixtures kept?: no new compatibility path is allowed by default.
• Why clean replacement is safe now: The spec targets current high-risk action safety before production. If implementation discovers an existing legacy path that remains reachable, the path must be fixed or explicitly reported as out-of-scope product-decision debt; do not preserve it silently.

UI Surface Impact (mandatory - UI-COV-001)

Does this spec add, remove, rename, or materially change any reachable UI surface?

• No UI surface impact
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

This spec does not intentionally add surfaces. Existing pages/actions/status presentations may be changed only where proof gaps require minimal hardening of current behavior.

UI/Productization Coverage

• Route/page/surface:
  • RestoreRun create wizard and view/detail proof surfaces.
  • BackupSchedule list/create/edit/run action surfaces.
  • BackupSet list/create/view and BackupItems relation manager action surfaces.
  • ProviderConnection list/create/view/edit surfaces and EnvironmentRequiredPermissions provider-readiness surfaces.
  • OperationRun, Audit Log, and Evidence links only where the target flows already expose them.
• Current or new page archetype:
  • Restore create: Wizard Page.
  • Restore detail / backup run detail / OperationRun detail: Receipt Page or Technical Annex depending on default-visible proof depth.
  • Backup schedules/sets/provider connections lists: Search/Index Page.
  • Provider setup/create: Settings or Wizard Page depending on current repo implementation.
  • Required permissions/provider readiness: Settings Page / Decision sub-surface.
• Design depth: Domain Pattern Surface / Manual Review Required because the selected flows are high-risk admin action surfaces.
• Repo-truth level: repo-verified existing surfaces.
• Existing pattern reused: Filament resources/actions, UiEnforcement / WorkspaceUiEnforcement, policies/gates, OperationRun Start UX Contract, OperationRun links, BadgeCatalog/BadgeRenderer, Provider readiness resolver/guidance, Restore safety/readiness/resolution contracts, backup quality/health contracts, audit recorder patterns.
• New pattern required: none by default. If implementation needs a new shared pattern, stop and update this spec/plan first.
• Screenshot required: yes for focused browser proof of the highest-risk visible paths, stored or summarized in the implementation report.
• Page audit required: no broad page audit. Update UI coverage artifacts only if implementation materially changes reachable surface classification or discovers registry drift.
• Customer-safe review required: no new customer surface. Proof must still prevent customer-safe or operator-default views from showing raw technical proof as a calm success claim.
• Dangerous-action review required: yes; restore execution, backup run/retry or bulk backup mutations, provider credential/consent/setup changes, and destructive backup/restore/provider actions must be confirmation-, authorization-, and audit-safe.
• Coverage files updated or explicitly not needed:
  • docs/ui-ux-enterprise-audit/route-inventory.md
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md
  • docs/ui-ux-enterprise-audit/page-reports/...
  • docs/ui-ux-enterprise-audit/strategic-surfaces.md
  • docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md
  • docs/ui-ux-enterprise-audit/unresolved-pages.md
  • N/A - no new reachable UI surface by default; existing surface coverage remains valid unless implementation discovers classification drift
• No-impact rationale when applicable: N/A - existing high-risk surfaces may be materially hardened.

Product Surface Impact (mandatory)

Reference: docs/product/standards/product-surface-contract.md.

• Product Surface Contract applies?: yes. The spec affects restore flows, provider state, backup actions, evidence/proof presentation, authorization, and high-impact actions.
• Page archetype: Existing surfaces keep their current archetypes; implementation must document each materially touched surface as Wizard, Receipt, Search/Index, Settings, Decision sub-surface, or Technical Annex.
• Primary user question: "Can I safely run or trust this high-risk admin action now?"
• Primary action: One existing next safe action per affected surface, such as Run readiness checks, Regenerate preview, Confirm restore, Run backup, Review backup, Verify provider, or Resolve provider permissions.
• Surface budget result: expected pass. Exceptions must be documented with page, violated rule, reason, and follow-up.
• Technical Annex / deep-link demotion: OperationRun links, raw evidence, raw provider payloads, source keys, fingerprints, detector/internal reason ownership, and technical logs must not be default product truth unless the surface is clearly technical/audit-facing.
• Canonical status vocabulary: Product-facing states must map to Ready, Needs attention, Blocked, Running, Failed, Expired, Not configured, Unknown, Historical, Superseded, and canonical severity labels. Existing internal/domain states may remain technical detail but must not become new product vocabulary.
• Visible complexity impact: neutral or decreased. Minimal hardening must not make the product louder or more ambiguous.
• Product Surface exceptions: none planned. Any discovered exception must be documented in the implementation report and treated as follow-up if it exceeds scope.

Browser Verification Plan (mandatory)

• Browser proof required?: yes for implementation because existing rendered high-risk flows are in scope.
• No-browser rationale: N/A.
• Focused path when required:
  • Restore preview/readiness path, including a blocked or stale/expired state and confirmation/cancel guard where feasible.
  • Backup schedule or backup set high-impact action path, including blocked/missing provider or failed/partial run state where feasible.
  • Provider setup/detail/readiness path, including stale/missing-permission/failed provider state.
  • One unauthorized or capability-denied path for a high-impact action.
• Primary interaction to execute: open existing pages, inspect visible state, invoke or mount confirmation where safe, cancel/accept via test/browser layer where feasible, and verify no Livewire/Filament runtime errors.
• Console, Livewire, Filament, network, and 500-error checks: required in focused browser proof.
• Full-suite failure triage: unrelated browser-suite failures may be documented only when focused affected proof is green and no touched surface fails.

Human Product Sanity Check (mandatory)

• Required?: yes for implementation close-out.
• No-human-sanity rationale: N/A.
• Reviewer questions: Does each touched flow clearly state purpose, one dominant next action, canonical status, demoted technical detail, and honest proof limits? Does cancellation/forbidden behavior avoid false audit/evidence? Would an operator trust the flow without assuming unproven safety?
• Planned result location: specs/401-high-risk-admin-action-proof-pack/implementation-report.md or final implementation response if no report file is created.

Product Surface Merge Gate Checklist (mandatory)

• No-legacy posture or approved exception recorded.
• Product Surface Impact is completed for existing high-risk surfaces.
• Browser proof is required for rendered high-risk flows during implementation.
• Human Product Sanity is required for implementation close-out.
• Product Surface exceptions are none unless implementation documents a bounded exception.
• Implementation report must state Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, tests/browser result, deployment impact, visible complexity outcome, and no completed-spec rewrite assertion.

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes.
• Interaction class(es): destructive/high-impact actions, confirmation modals, disabled/hidden UI enforcement, status messaging, OperationRun links, audit/evidence links, provider readiness, restore readiness, backup quality/health, notifications, browser proof.
• Systems touched: existing restore, backup, provider, OperationRun, audit, evidence, and Filament action systems.
• Existing pattern(s) to extend: UiEnforcement / WorkspaceUiEnforcement, policies/gates, OperationRunService, OperationRun Start UX Contract, OperationRunLinks, provider readiness/guidance paths, restore safety/readiness paths, backup quality/health paths, AuditRecorder / workspace audit logging, BadgeCatalog/BadgeRenderer.
• Shared contract / presenter / builder / renderer to reuse: exact class selection must follow repo inventory, but implementation must reuse existing shared paths before adding local logic.
• Why the existing shared path is sufficient or insufficient: Existing shared paths are sufficient by default. The proof pack should expose any gaps through tests first; new shared infrastructure is out of scope unless an existing pattern cannot safely enforce action confirmation, authorization, audit, or proof truth.
• Allowed deviation and why: none planned. A bounded exception may be recorded only if a current flow cannot use the shared path and the deviation is smaller than changing the shared contract.
• Consistency impact: restore, backup, provider, OperationRun, audit, evidence, notifications, and visible state labels must not create parallel safety language.
• Review focus: no hidden local authorization, no destructive URL-only actions, no false success proof, no audit/evidence on cancelled/forbidden paths, no completed-spec rewrites.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: yes, where existing restore/backup/provider actions create, queue, block, complete, reconcile, or link OperationRun.
• Shared OperationRun UX contract/layer reused: existing OperationRun Start UX Contract, OperationUxPresenter, OperationRunLinks, OperationRunService, and OperationRunCompleted terminal notification path where relevant.
• Delegated start/completion UX behaviors: queued toast, run link, artifact link, run-enqueued browser event, dedupe/blocked/start-failure messaging, tenant/workspace-safe URL resolution, terminal notifications, and summary count semantics remain delegated to existing shared paths.
• Local surface-owned behavior that remains: input collection, current action mount state, confirmation copy, and domain-specific proof display only.
• Queued DB-notification policy: no new queued DB notification policy. Keep existing explicit opt-in rules.
• Terminal notification path: central lifecycle mechanism only.
• Exception required?: none planned.

Provider Boundary / Platform Core Check (mandatory)

• Shared provider/platform boundary touched?: yes, by proof and minimal hardening over provider setup/detail/readiness and provider-backed restore/backup blockers.
• Boundary classification: mixed.
• Seams affected: provider connection identity/scope, provider verification/freshness, managed-environment required permissions, provider-backed restore/backup prerequisites, provider-specific error/readiness proof, OperationRun context, audit metadata.
• Neutral platform terms preserved or introduced: workspace, managed environment, provider, connection, operation, execution truth, artifact truth, backup truth, evidence truth, audit trail, readiness, blocked, failed, expired.
• Provider-specific semantics retained and why: Microsoft/Intune and Entra terms remain provider-owned where current runtime is explicitly Microsoft-backed. They must not become new platform-core vocabulary in this spec.
• Why this does not deepen provider coupling accidentally: The spec proves existing Microsoft/provider-backed flows and does not add provider families, provider registries, Graph contracts, or platform-wide provider abstractions.
• Follow-up path: follow-up-spec only if proof discovers structural provider-boundary ambiguity that cannot be fixed as minimal hardening.

UI / Surface Guardrail Impact (mandatory)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Restore preview/readiness/create wizard	yes, if proof gap requires hardening	Mixed Filament wizard plus existing custom Blade/presenter paths	restore readiness, dangerous confirmation, OperationRun/evidence links	page, wizard, modal, detail	no planned	Existing high-risk workflow only
Restore run detail/result proof	yes, if result state proof changes	Filament/Infolist plus existing restore detail presenter	receipt/proof/evidence links	detail	no planned	No new route
Backup schedule list/create/edit/run	yes, if action proof changes	Native Filament resource/actions	backup OperationRun start UX, audit, confirmation	table, form, action modal	no planned	Existing resource only
Backup set list/view/items relation	yes, if action proof changes	Native Filament resource/relation manager	backup quality, backup item operations, restore linkage	table, detail, relation manager	no planned	Existing resource only
Provider connection create/view/edit/list	yes, if action proof changes	Native Filament resource plus provider guidance	provider readiness, required permissions, credential/consent audit	form, detail, table, action modal	no planned	Existing resource only
Required permissions / provider readiness	yes, if state proof changes	Filament page/view models	provider readiness/status messaging	page, detail	no planned	Existing page only

Decision-First Surface Role (mandatory)

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Restore preview/readiness	Primary Decision Surface	Decide whether restore can advance safely	readiness status, blocker/reason, next safe action, confirmation requirement	raw preview payload, mapping internals, OperationRun/evidence links where authorized	Primary because restore can mutate provider configuration	follows backup source -> checks -> preview -> confirmation	removes guessing from stale/blocked states
Restore result/detail	Receipt Page / Secondary Context	Decide whether outcome can be trusted	result, partial/failed state, proof/evidence availability, next inspection action	diagnostics, raw item payloads, audit trail	Secondary because it verifies what happened	follows post-execution proof review	separates execution from recovery proof
Backup schedules/sets	Search/Index or Receipt Page	Decide whether backup basis can be created, trusted, retried, or inspected	state, reason, next backup action, provider/environment blocker	raw items, OperationRun detail, audit trail	Primary only for backup management task	follows backup basis and recovery-readiness workflow	makes missing/failed/partial backup states explicit
Provider setup/detail/readiness	Settings / Decision sub-surface	Decide whether provider is configured enough for downstream actions	provider state, permission/freshness blocker, next provider action	raw provider payload, credential internals, technical verification detail	Primary for setup/readiness task, secondary for diagnostics	follows setup -> verify -> resolve permissions	prevents false Ready/Healthy assumptions

Audience-Aware Disclosure (mandatory)

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
Restore preview/readiness	operator-MSP, support-platform	readiness, blocker, impact, confirmation state	preview basis, checks, mapping summary	raw payloads, raw diffs, internal IDs	next safe restore preparation action	raw proof and provider internals	restore readiness owns top status once
Backup schedules/sets	operator-MSP, support-platform	backup state, run state, reason, next action	item counts, run history, failure reason	raw backup payloads, technical OperationRun context	run/review backup action	internal evidence and raw snapshot payload	backup truth separate from recovery proof
Provider setup/detail	operator-MSP, support-platform	connection/readiness/freshness/permission state	required permission rows, verification reports	credentials, raw provider errors, source keys	verify/resolve provider action	credentials and raw provider data	provider readiness resolver/contract owns top status

UI/UX Surface Classification (mandatory)

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
RestoreRun create	Workflow / Wizard / Dangerous Action	Environment-bound restore workflow	run checks, regenerate preview, confirm restore	wizard step progression	N/A	diagnostics/proof panels	final confirmation step only	RestoreRuns list	RestoreRun detail	workspace + environment	Restore run	readiness, proof basis, blockers, confirmation	none
RestoreRun detail	Receipt / Technical Annex	Result/proof detail	inspect proof or resolve failed/partial outcome	detail page	N/A	technical/audit links secondary	none unless existing actions already present	RestoreRuns list	RestoreRun detail	workspace + environment	Restore run	execution outcome and evidence availability	none
BackupSchedule list/edit	List / Table / Settings	Scheduled backup management	run backup or inspect schedule	row click or existing inspect model	current repo pattern	More/action groups	More or confirmed action modal	BackupSchedules list	BackupSchedule edit/detail where present	workspace + environment	Backup schedule	schedule state, next run, last run/proof	none
BackupSet list/view	List / Table / Receipt	Backup basis review	inspect backup or manage items	row click or view page	current repo pattern	More/relation actions	More or confirmed action modal	BackupSets list	BackupSet view	workspace + environment	Backup set	backup quality/state/item proof	none
ProviderConnection list/view/edit	List / Settings / Decision	Provider setup/readiness	verify provider or resolve permissions	row click/view/edit per current repo	current repo pattern	More/detail header	confirmed action modal	ProviderConnections list	ProviderConnection view/edit	workspace + environment/provider	Provider connection	readiness/freshness/permission state	none

Operator Surface Contract (mandatory)

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Restore preview/readiness	Tenant/MSP operator	Decide whether restore can safely advance or execute	Dangerous workflow wizard	Is this restore safe to continue now?	readiness, blocker, impact, proof basis, one next action	raw preview, raw diffs, provider payloads, audit detail	readiness, execution, evidence, lifecycle	TenantPilot preview or Microsoft tenant mutation after confirmation	run checks, regenerate preview, confirm restore	execute restore
Backup schedules/sets	Tenant/MSP operator	Decide whether backup basis exists and can run/retry/inspect	Backup management/list/detail	Can I trust or run this backup path now?	backup state, provider/environment blocker, latest run outcome	raw backup payload, item internals, run logs	backup quality, operation outcome, lifecycle	TenantPilot backup capture and existing provider read paths	run/review backup, manage items	delete/force-delete/restore/archive/bulk actions where existing
Provider setup/detail	Tenant/MSP operator	Decide whether provider is ready enough for downstream operations	Settings/readiness detail	Is this provider configured and current enough?	connection/readiness/freshness/permission state, one next action	credentials, raw provider errors, technical verification	readiness, freshness, permission coverage, connection lifecycle	TenantPilot provider configuration and provider consent/verification	verify/resolve/setup provider	credential/consent/disable/delete/rotate actions where existing

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no runtime source of truth. A proof map or implementation report is review evidence only.
• New persisted entity/table/artifact?: no application table/entity. Spec-local proof artifacts may be created during implementation.
• New abstraction?: no by default.
• New enum/state/reason family?: no. Existing canonical/product/domain states must be reused.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: high-risk admin actions need concrete evidence that safety controls work across domains, not just local UI existence.
• Existing structure is insufficient because: proof is fragmented across specs/tests and not organized by high-risk state/action category.
• Narrowest correct implementation: proof map, focused tests/browser smoke, and minimal in-place hardening of existing action paths.
• Ownership cost: additional focused tests, browser smoke, and implementation-report maintenance for this high-risk package.
• Alternative intentionally rejected: a generic high-risk action framework, broad browser audit, provider onboarding redesign, restore architecture rewrite, or new status taxonomy.
• Release truth: current-release operational safety hardening.

Compatibility posture

This feature assumes a pre-production environment. Backward compatibility, legacy aliases, fallback readers, hidden duplicate UI, and legacy fixtures are out of scope unless explicitly added to this spec after a blocker is discovered.

Data / Truth Source Requirements

• Execution truth remains OperationRun for long-running/queued/high-impact operations.
• Restore request/result truth remains RestoreRun plus existing restore safety/result contracts.
• Backup truth remains BackupSet, BackupItem, BackupSchedule, associated jobs, and existing backup quality/health contracts.
• Provider readiness truth remains ProviderConnection, ManagedEnvironmentPermission, provider verification reports, and existing provider readiness/capability contracts.
• Audit truth remains AuditLog / audit services.
• Evidence truth remains existing evidence snapshots/artifacts where already linked.
• Product truth must distinguish execution truth, artifact truth, backup/snapshot truth, recovery/evidence truth, and operator next action.

Functional Requirements

Cross-domain Proof Requirements

• FR-401-001: Implementation MUST create or update a Spec 401 proof map covering target restore, backup, and provider flows before runtime edits begin.
• FR-401-002: The proof map MUST classify each target flow/state as Fully proven, Proven except explicitly deferred state, Product contract missing, Implementation defect found and fixed, or Implementation defect found but out of scope.
• FR-401-003: The proof map MUST record flow, state, existing proof, missing proof, fix needed, test needed, browser proof needed, and out-of-scope reason.
• FR-401-004: Implementation MUST add or update focused tests before runtime changes wherever feasible.
• FR-401-005: Implementation MUST not introduce new product status vocabulary, persisted truth, provider families, navigation, pages, panels, or broad UI frameworks.
• FR-401-006: Implementation MUST not change completed specs except to read them as context.

Restore Flow Proof

• FR-401-010: Prove authorized users can view restore preview/readiness for scoped workspace/environment records.
• FR-401-011: Prove unauthorized users cannot view or execute restore actions by direct route or action invocation.
• FR-401-012: Prove missing required inputs produce a blocked state and do not allow execution.
• FR-401-013: Prove stale or expired preview/readiness data cannot execute as current.
• FR-401-014: Prove restore execution or equivalent high-impact restore action requires confirmation.
• FR-401-015: Prove cancellation does not execute restore and does not create successful OperationRun, audit, or evidence artifacts.
• FR-401-016: Prove confirmation acceptance executes only the intended scoped action and creates the expected audit/proof artifacts where the existing contract requires them.
• FR-401-017: Prove conflict, partial, and failed restore results are not represented as successful or safe.
• FR-401-018: Prove OperationRun/evidence links shown from restore surfaces are authorized and workspace/environment scoped.
• FR-401-019: If actual restore execution is simulated or preview-only for a state, the UI/tests MUST prove the current product contract says so honestly.

Backup Flow Proof

• FR-401-020: Prove authorized users can view backup schedules, backup sets, backup items, and backup run/status/detail paths for scoped workspace/environment records.
• FR-401-021: Prove unauthorized users cannot view or execute backup actions by direct route or action invocation.
• FR-401-022: Prove backup create/run/retry/bulk actions require appropriate capability.
• FR-401-023: Prove any backup action that triggers a high-impact operation requires confirmation when the existing contract classifies it as high-impact or destructive-like; the proof map MUST list each touched backup action, its classification source, and whether confirmation is required.
• FR-401-024: Prove cancelled backup action does not create misleading OperationRun, audit, evidence, backup item, or success artifact.
• FR-401-025: Prove failed backup state is visible and not represented as successful.
• FR-401-026: Prove partial backup state is visible and not represented as complete.
• FR-401-027: Prove missing provider/environment context blocks backup action safely.
• FR-401-028: Prove stale provider data blocks or warns according to existing contract, and if no contract exists, records a product-decision gap.
• FR-401-029: Prove backup run/detail surfaces do not expose internal-only evidence in inappropriate default product surfaces.

Provider Setup / Detail Proof

• FR-401-030: Prove authorized users can view provider setup/detail/readiness for scoped workspace/environment/provider records.
• FR-401-031: Prove unauthorized users cannot create, edit, verify, disable, inspect, or otherwise mutate provider setup/detail through direct invocation.
• FR-401-032: Prove missing-permission, stale/freshness, failed-connection, partial-permission, and unknown provider states use existing canonical vocabulary and do not imply readiness.
• FR-401-033: Prove provider detail does not expose raw source keys, credentials, raw provider payloads, or technical internals in default product paths.
• FR-401-034: Prove provider readiness/verification actions specifically cannot bypass authorization through direct request/action invocation, even when generic provider create/edit/disable authorization is already covered.
• FR-401-035: Prove provider readiness shown to operators is supported by evidence or clearly marked unavailable/unverified.
• FR-401-036: Prove provider-related OperationRun, audit, and evidence links remain scope-safe and authorized.

Filament / Action / Global Search Requirements

• FR-401-040: Every destructive or high-impact Filament action touched by this spec MUST execute through Action::make(...)->action(...), not URL-only execution.
• FR-401-041: Every destructive or high-impact Filament action touched by this spec MUST include ->requiresConfirmation(), server-side authorization, audit behavior where mutating, and focused tests.
• FR-401-042: URL-only actions MUST remain navigation-only and must not be claimed as confirmation-protected.
• FR-401-043: Every globally searchable resource touched by this spec MUST either have a safe View/Edit page plus $recordTitleAttribute or global search disabled.
• FR-401-044: Table/list surfaces touched by this spec MUST keep meaningful empty states and action hierarchy.

Non-Functional Requirements

• NFR-401-001: Proof and hardening MUST be deterministic and testable without external Microsoft Graph calls.
• NFR-401-002: Browser proof MUST be focused and not expand into a broad browser audit.
• NFR-401-003: Fixture/helper changes MUST stay explicit and cheap by default; no broad hidden provider/workspace/session defaults.
• NFR-401-004: Sensitive data, provider credentials, raw secrets, raw provider payloads, and raw tenant data MUST NOT appear in logs, audit metadata, screenshots, implementation reports, or browser artifacts.
• NFR-401-005: Runtime fixes MUST preserve existing route ownership and workspace/environment scoping.
• NFR-401-006: No new env vars, migrations, queues, scheduler entries, storage disks, assets, packages, or deployment steps are expected by default.
• NFR-401-007: Any implementation defect that requires a broader architecture or product decision MUST be documented as out of scope instead of silently expanded.

Out Of Scope

• New admin surfaces, customer surfaces, navigation groups, routes, pages, panels, or widgets.
• Restore architecture rewrite, new restore execution engine, rollback system, or new restore operation family.
• Backup architecture rewrite, new scheduling product feature, or new backup retention/lifecycle system.
• Provider onboarding redesign, new provider families, provider abstraction framework, or OAuth redesign.
• New customer-facing proof/report output or management PDF behavior.
• Governance artifact lifecycle, resource-policy matrix, JSON-to-JSONB hardening, or full browser/UX/runtime audit.
• Broad copy cleanup, broad UI redesign, broad status-vocabulary cleanup, or unrelated Product Surface Contract migration.
• Completed spec artifact rewrites or removal of validation/browser/close-out history.

User Scenarios & Testing (mandatory)

User Story 1 - Restore high-risk actions are proven safe (Priority: P1)

As an authorized restore operator, I want restore preview/readiness/execution behavior to be proven across blocked, stale, partial, failed, unauthorized, and confirmation/cancel states, so that restore cannot be treated as safe by assumption.

Independent Test: Run focused restore Feature/Filament tests and focused browser path. The tests prove authorization, direct invocation denial, stale/blocked execution prevention, confirmation acceptance/cancellation behavior, and honest partial/failed result semantics.

Acceptance Scenarios:

1. Given a restore preview is stale or expired, When an operator attempts to execute or continue to final execution, Then the action is blocked or redirected to regenerate preview and no successful OperationRun/audit/evidence artifact is created.
2. Given a restore action confirmation is cancelled, When the page returns to the restore flow, Then no restore execution, success audit, success evidence, or misleading OperationRun is created.
3. Given a restore result is partial or failed, When the operator opens restore detail or Operations proof, Then the result is not displayed as completed/safe/recovery-verified.

User Story 2 - Backup high-impact actions are proven safe (Priority: P1)

As an operator responsible for recovery basis, I want backup schedule, backup set, and backup run actions to prove authorization, provider/environment blockers, failed/partial states, and audit/proof side effects, so that backup health is not mistaken for recovery proof.

Independent Test: Run focused backup schedule/set Feature/Filament tests and one browser path that proves a high-impact backup action state, blocked state, or failed/partial state is visible and safe.

Acceptance Scenarios:

1. Given a user lacks backup run capability, When the user invokes a run/retry/create action directly, Then the server denies execution and no OperationRun/audit/success artifact is created.
2. Given provider or environment context is missing/stale, When a backup action is attempted, Then the action blocks or warns according to existing contract and does not create false backup success.
3. Given a backup run is failed or partial, When the operator opens backup run/detail or related OperationRun proof, Then the state is visible and not represented as complete.

User Story 3 - Provider setup/detail actions are proven safe (Priority: P1)

As an operator configuring provider access, I want provider setup/detail/readiness actions to prove authorization, evidence-backed readiness, missing permissions, stale data, failed connection, partial permission, and raw-detail demotion, so downstream restore/backup readiness does not depend on false provider state.

Independent Test: Run focused provider Feature/Filament tests and browser proof that stale/missing-permission/failed provider state is visible, action-gated, and free from raw credentials/provider payloads in default views.

Acceptance Scenarios:

1. Given provider verification evidence is stale or permissions are missing, When the operator opens provider detail or required permissions, Then the surface shows an existing canonical non-ready state and one next safe action.
2. Given a user lacks provider management/run capability, When the user invokes setup/verify/edit/disable directly, Then the server denies execution and does not write misleading audit/evidence.
3. Given provider detail contains technical evidence, When the default product view renders, Then raw credentials, raw provider payloads, source keys, and internal technical details are hidden or gated.

User Story 4 - Cross-flow proof report is complete and bounded (Priority: P2)

As an implementation reviewer, I want one proof map and close-out report that states what was proven, fixed, deferred, and browser-verified, so I can approve or stop the next implementation step without re-reading every related spec.

Independent Test: Inspect the Spec 401 implementation report and proof map. Every P0/P1 residual gap has concrete evidence, status, severity, and next action. No application implementation outside the selected scope is included.

Acceptance Scenarios:

1. Given implementation completes, When the reviewer opens the report, Then restore, backup, and provider domains each list states proven, tests added/updated, browser proof, fixes applied, deferred product decisions, and files changed.
2. Given a state cannot be safely proven because the product contract is missing, When the report is reviewed, Then the state is classified as product-decision debt rather than silently implemented.
3. Given implementation found an out-of-scope defect, When the report is reviewed, Then the defect cites repo evidence and a bounded follow-up recommendation.

Edge Cases

• Confirmation modal is cancelled after state changed on the server or in another tab.
• Preview basis or provider verification becomes stale between mount and action execution.
• User loses capability/session context after opening a page but before action invocation.
• A record belongs to the correct workspace but wrong managed environment.
• OperationRun exists but links to a wrong-scope restore/backup/provider record.
• Backup run creates partial item results but aggregate counters are missing or misleading.
• Provider connection is disabled, failed, or stale while permission rows look granted.
• Browser proof fixture lacks a real execution path; implementation must record the limitation rather than overclaim proof.
• Existing product contract is silent about one required state; classify as product-decision gap.

Success Criteria

• SC-401-001: Every target domain (restore, backup, provider) has a completed proof map row for each applicable high-risk state category or an explicit deferral reason.
• SC-401-002: Focused tests prove direct unauthorized invocation is blocked for at least one high-impact action in each target domain.
• SC-401-003: Focused tests prove confirmation accepted/cancelled behavior for restore and at least one backup or provider high-impact action where confirmation applies.
• SC-401-004: Focused tests prove no misleading success OperationRun/audit/evidence artifact is created for cancelled or forbidden actions where existing contracts define those artifacts.
• SC-401-005: Focused tests prove partial/failed/stale/blocked states are not rendered as Ready, successful, complete, or safe.
• SC-401-006: Focused browser proof covers restore, backup, provider, and one unauthorized/blocked path with no Livewire/Filament/runtime/500 errors on the tested paths.
• SC-401-007: Implementation report states no new surfaces, no new product concepts, no completed-spec rewrites, and all Product Surface close-out fields.

Risks

• Browser fixture cost can grow if the spec attempts to prove every state visually. Mitigation: one focused browser path per domain plus Feature/Filament tests for matrix breadth.
• Restore/backup/provider contracts may be silent about a state. Mitigation: record product-decision debt and avoid inventing behavior.
• Existing tests may already prove parts of the matrix but under names that are hard to discover. Mitigation: inventory before edits and cite existing proof.
• High-risk actions may require minimal hardening across large Filament classes. Mitigation: keep fixes local and tests-first; stop if broad refactor is required.
• Confirmation-cancel behavior can be hard to prove in Livewire/Filament tests. Mitigation: prove "not called before confirmation" and browser modal behavior where feasible, documenting exact limitation.

Assumptions

• Spec 400's attached conclusion is accepted as the direct product trigger for this manual candidate.
• Current route/surface names found in repo inspection are authoritative over the draft wording.
• Existing canonical status vocabulary from the Product Surface Contract governs visible product labels.
• Existing OperationRun, audit, evidence, provider readiness, restore safety, backup quality, and UI enforcement paths should be reused.
• No product owner decision is required before implementation unless proof discovers a missing product contract.

Open Questions

None blocking preparation.

Implementation must stop and update this spec/plan if it discovers that a required proof state needs a new product concept, new persisted truth, new status family, new route/page, or broader architecture than minimal hardening.