ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/365-operations-ui-operator-actions-regression-gate/tasks.md
ahmido 6ac0913ff8 feat: implement operations UI operator actions regression gate (#436) 
Implemented operations UI operator actions regression gate.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #436
2026-06-08 01:21:14 +00:00

20 KiB
Raw Permalink Blame History

Tasks: Operations UI Operator Actions & Regression Gate

Input: Design documents from /specs/365-operations-ui-operator-actions-regression-gate/
Prerequisites: plan.md, spec.md, artifacts/spec365-action-eligibility-matrix.md, artifacts/spec365-regression-gate-matrix.md

Tests: Required. Runtime changes must use Pest 4 unit/feature/browser coverage.

Repository State Captured During Prep

  • Branch: 365-operations-ui-operator-actions-regression-gate
  • HEAD: 3ce1cae7 feat: implement restore high risk operation reconciliation (#435)
  • git status at prep start: clean on platform-dev before branch creation; after Spec Kit branch creation only specs/365-operations-ui-operator-actions-regression-gate/ was untracked.
  • Spec 364 baseline status: treated as completed immediate predecessor; implementation must keep Spec364 restore/high-risk tests green.
  • Relevant Operations UI / action files:
    • apps/platform/app/Filament/Pages/Monitoring/Operations.php
    • apps/platform/app/Filament/Resources/OperationRunResource.php
    • apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
    • apps/platform/app/Support/OpsUx/OperationUxPresenter.php
    • apps/platform/app/Support/OpsUx/OperationRunProgressContract.php
    • apps/platform/app/Support/OperationRunLinks.php
    • apps/platform/app/Support/Navigation/RelatedNavigationResolver.php
    • apps/platform/app/Support/Navigation/RelatedActionLabelCatalog.php
    • apps/platform/app/Policies/OperationRunPolicy.php
    • apps/platform/app/Support/OperationRunCapabilityResolver.php
    • apps/platform/app/Support/Auth/Capabilities.php
    • apps/platform/app/Services/AdapterRunReconciler.php
    • apps/platform/app/Support/Operations/Reconciliation/OperationRunReconciliationRegistry.php
    • apps/platform/app/Services/OperationRunService.php

Implementation Decisions to Record During Close-Out

  • Implemented actions: Reconcile for eligible stale adapter-backed OperationRuns; safe related navigation for review, evidence snapshot, review pack/report, inventory affected-family/details, backup details, and restore details; support diagnostics remains secondary/capability-gated.
  • Deferred actions: generic Retry for all families because no repo-verified generic safe retry/start seam was found; OperationRun Acknowledge because no clean existing acknowledge/note seam exists.
  • Unsupported/forbidden actions: Force Complete, Mark Succeeded, Retry Restore, Re-execute Restore, Delete, Purge.
  • Coverage artifact decision: updated docs/ui-ux-enterprise-audit/page-reports/ui-003-operations.md because the existing Operations strategic surface gained visible safe-next-action hierarchy.
  • Spec 358-364 regression result: targeted Spec359/Spec360 browser/Spec364 plus OperationRun viewer/link/monitoring/resource presentation regressions passed locally; final filter sweep recorded under Phase 13.
  • Mutation scope disclosure result: Reconcile confirmation discloses TenantPilot-only OperationRun/action metadata and explicitly states no Microsoft tenant retry/change. Retry was not implemented.

Test Governance Checklist

  • Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
  • New or changed tests stay in the smallest honest family, and any browser addition is explicit.
  • Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
  • Planned validation commands cover the change without pulling in unrelated lane cost.
  • The declared surface test profile (monitoring-state-page, shared-detail-family) is explicit.
  • Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR.

Format: [ID] [P?] [Story] Description

  • [P]: Can run in parallel after prerequisites.
  • [Story]: US1, US2, US3, US4, US5, US6.

Phase 1: Setup and Audit (Shared)

Purpose: Confirm repo seams, docs, capabilities, and existing UI before implementation.

  • T001 [P] Re-read specs/365-operations-ui-operator-actions-regression-gate/spec.md, plan.md, both matrix artifacts, and .specify/memory/constitution.md before code changes.
  • T002 [P] Audit current OperationRun UI/action code in apps/platform/app/Filament/Pages/Monitoring/Operations.php, apps/platform/app/Filament/Resources/OperationRunResource.php, and apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php.
  • T003 [P] Audit current shared OperationRun UX/link seams in OperationUxPresenter, OperationRunProgressContract, OperationRunLinks, RelatedNavigationResolver, and RelatedActionLabelCatalog.
  • T004 [P] Audit action authorization seams in OperationRunPolicy, OperationRunCapabilityResolver, and Capabilities to decide whether existing capabilities cover reconcile/retry/diagnostics.
  • T005 [P] Audit existing audit/action metadata seams in AuditRecorder, WorkspaceAuditLogger, and OperationRun context writes to decide whether context.operator_actions is needed.
  • T006 [P] Audit safe retry/resume/start seams, including TenantlessOperationRunViewer::resumeCaptureAction() and any operation-family start services; record unsupported families in the close-out section above.

Phase 2: Foundational Resolver and Contracts (Blocking)

Purpose: Add the single action decision path before UI wiring.

  • T007 [US1] Add a narrow resolver such as apps/platform/app/Support/Operations/OperationRunActionEligibility.php that derives primary/secondary/disabled actions from canonical OperationRun truth, user, workspace, and environment scope.
  • T008 [US1] Add a small derived result object or array contract for primary_action, secondary_actions, disabled_actions, disabled_reasons, and attention_reason; keep it non-persisted and avoid new status/outcome enums.
  • T009 [US1] Ensure resolver reads canonical context.dispatch, context.reconciliation, context.results, context.coverage, and context.restore only; do not add new legacy fallback paths.
  • T010 [US3] Encode high-risk classification for restore/tenant mutation/destructive/unknown operations so retry/re-execute/force-success always fail closed.
  • T011 [US2] Encode reconcile eligibility through OperationRunReconciliationRegistry support and current run state/freshness/proof rules.
  • T012 [US4] Encode retry eligibility as unavailable by default unless a repo-verified safe non-high-risk retry/start seam exists for the operation family.
  • T013 [US5] Encode related action eligibility using canonical related metadata and existing link/navigation resolvers.
  • T014 [US6] Encode diagnostics visibility through existing support/operator capability checks.

Phase 3: Unit Tests First (Resolver, Presenter, Guard)

Purpose: Lock action decisions before Filament UI changes.

  • T015 [P] [US1] Add apps/platform/tests/Unit/Support/Operations/Spec365OperationRunActionEligibilityTest.php covering fresh queued, stale queued, stale running, unsupported, missing capability, and cross-workspace inputs.
  • T016 [P] [US1] Add apps/platform/tests/Unit/Support/Operations/Spec365OperationRunPrimaryActionTest.php covering one primary action for review, evidence, review-pack/report, sync partial, backup blocked, restore verification-required, and restore failed.
  • T017 [P] [US3] Cover high-risk action guard assertions in the Spec365 unit tests, proving restore/high-risk has no retry, re-execute, force complete, mark succeeded, delete, or purge action.
  • T018 [P] [US1] Update OperationRun detail/presentation/browser coverage for outcome-specific decision summaries and raw-leakage sanitization.
  • T019 [P] [US4] Add unit coverage proving safe retry returns unavailable/deferred for operation families without a repo-verified retry seam.

Phase 4: Existing Operations UI Integration

Purpose: Make the existing surfaces decision-first without creating new pages.

  • T020 [US1] Update Operations.php table/list presentation to surface status/outcome, freshness, scope, primary reason, and one resolver-provided primary action or action label.
  • T021 [US1] Update OperationRunResource.php detail sections to place decision summary, evidence, and next action before technical diagnostics.
  • T022 [US1] Update TenantlessOperationRunViewer.php header/action groups to consume resolver output for primary and secondary actions.
  • T023 [US1] Ensure technical/raw context sections are collapsed and capability-gated by default.
  • T024 [US1] Remove or demote any redundant "View" action when row click/detail link already provides the primary inspect model.
  • T025 [US3] Ensure high-risk restore detail uses "View restore details" or equivalent safe navigation and never presents retry/re-execute/force-success copy.

Phase 5: Safe Reconcile Action

Purpose: Integrate reconciliation only through existing canonical seams.

  • T026 [US2] Add a Filament reconcile action on the appropriate OperationRun detail/header surface using Action::make(...)->action(...) and confirmation/description copy where appropriate.
  • T078 [US2] Ensure Reconcile action helper text, modal description, preview, or confirmation communicates mutation scope before execution, normally TenantPilot-only OperationRun/action metadata.
  • T027 [US2] Enforce server-side authorization and scope in OperationRunPolicy or a central action policy/helper; preserve non-member 404 and missing-capability 403 semantics.
  • T028 [US2] Execute reconcile through AdapterRunReconciler and OperationRunService; do not mutate OperationRun state directly in the UI action.
  • T029 [US2] Make reconcile idempotent for already reconciled or no-op adapter outcomes.
  • T030 [US2] Write audit/action metadata for reconcile with action, run id, workspace, environment, actor, previous/new status/outcome, reason code, timestamp, and no secrets.
  • T031 [US2] Add disabled/unavailable reason copy for unsupported, missing capability, cross-scope, insufficient proof, and already terminal/succeeded states.

Phase 6: Safe Retry Action or Explicit Deferral

Purpose: Offer retry only where safe and repo-real.

  • T032 [US4] For each candidate non-high-risk operation family, verify whether a safe idempotent retry/start seam exists; document results in the close-out section.
  • T033 [US4] No safe generic seam exists; retry action not implemented.
  • T079 [US4] No Retry implemented; mutation-scope disclosure not applicable.
  • T034 [US4] If no safe seam exists for a family, keep retry unavailable and show a localized disabled/deferred reason.
  • T035 [US4] No Retry implemented; no new run-creation flood path added.
  • T036 [US4] No Retry implemented; no retry audit metadata required.
  • T037 [US4] Ensure completed/succeeded, unknown, restore, tenant mutation, destructive, and high-risk runs never become retryable.

Phase 7: Related Domain Actions

Purpose: Let operators open proof without raw context inspection.

  • T038 [US5] Wire related actions through existing OperationRunLinks / RelatedNavigationResolver where canonical metadata and policy checks pass.
  • T039 [US5] Support canonical related actions for review, evidence snapshot, review-pack/report artifact, backup set, sync/details if existing route exists, and restore details.
  • T040 [US5] Hide or disable related actions when metadata is absent, capability is missing, or the target is cross-workspace/cross-environment.
  • T041 [US5] Ensure no action reads signed URLs, raw payloads, or legacy fallback context from OperationRun context.

Phase 8: Localization and Copy

Purpose: Keep labels and summaries customer-safe in EN/DE.

  • T042 [P] [US6] Add EN localization keys in apps/platform/lang/en/localization.php for reconcile, retry, related actions, disabled reasons, high-risk guard, and summary states.
  • T043 [P] [US6] Add DE localization keys in apps/platform/lang/de/localization.php for the same key families.
  • T044 [US6] Ensure primary action labels use Verb + Object and avoid implementation-first terms.
  • T045 [US6] Ensure customer-readable copy does not expose SQL, Guzzle, stack trace, access token, client secret, queue payload, serialized job, or internal constraint names.

Phase 9: Feature Tests

Purpose: Prove direct action behavior, RBAC, scope, audit, and related links.

  • T046 [P] [US2] Add apps/platform/tests/Feature/Operations/Spec365OperationRunOperatorActionsTest.php for reconcile success, unsupported reconcile denial, and idempotency.
  • T047 [P] [US4] Add retry-unavailable tests in focused Spec365 unit/feature coverage; no Retry implemented.
  • T048 [P] [US2,US4] Add apps/platform/tests/Feature/Operations/Spec365OperationRunOperatorActionsTest.php for missing capability and direct action denial.
  • T049 [P] [US2,US5] Add cross-workspace and cross-environment denial tests.
  • T050 [P] [US6] Add apps/platform/tests/Feature/Operations/Spec365OperationRunOperatorActionsTest.php for reconcile metadata and no-secret assertions.
  • T080 [P] [US6] Extend denied-action coverage to assert failed/denied Reconcile attempts are audit-visible or safely logged without secrets; Retry not implemented.
  • T051 [P] [US5] Cover same-scope related links and cross-scope denial in Spec365 unit/feature tests plus existing OperationRun link contract tests.
  • T052 [P] [US1] Cover regression matrix states that do not require browser coverage in Spec365 unit tests and existing OperationRun presentation regressions.

Phase 10: Browser Smoke

Purpose: Prove the actual Operations UI is decision-first and safe.

  • T053 [US1] Add apps/platform/tests/Browser/Spec365OperationsUiOperatorActionsSmokeTest.php for Operations list decision-first fields and no raw JSON by default.
  • T054 [US2] Cover review reconcile state, confirmation modal, and absence of SQL/constraint leakage.
  • T055 [US5] Cover review-pack/report and evidence snapshot available states with safe related actions.
  • T056 [US1] Cover sync partial and backup blocked summary states.
  • T057 [US3] Cover restore verification-required/high-risk state with safe restore details action and absence of Retry Restore, Force Complete, and Mark Succeeded.
  • T058 [US6] Cover RBAC-denied user where reconcile/retry actions are unavailable in feature coverage; Retry not implemented.
  • T059 [US6] Cover raw leakage guard for SQLSTATE, Guzzle, stack trace, access token, client secret, environment_reviews_fingerprint_mutable_unique, and serialized job.
  • T060 [US1] Screenshots were not saved because the automated browser assertions were sufficient and no visual defect remained after smoke.

Phase 11: Optional Acknowledge Decision

Purpose: Avoid a local "reviewed" substitute unless the repo already supports it cleanly.

  • T061 [US6] Verify whether a clean existing OperationRun acknowledge/note/audit seam exists.
  • T062 [US6] No clean seam exists; Acknowledge not implemented.
  • T063 [US6] Document Acknowledge as deferred in the close-out section and do not implement local context-only success-like state.

Phase 12: Coverage Artifacts and Documentation Close-Out

Purpose: Keep Spec Kit and UI coverage aligned.

  • T064 [P] Update artifacts/spec365-action-eligibility-matrix.md if implementation changes eligible actions or disabled reasons.
  • T065 [P] Update artifacts/spec365-regression-gate-matrix.md with actual test file names/statuses after implementation.
  • T066 Update docs/ui-ux-enterprise-audit/page-reports/ui-003-operations.md and related design coverage files if implementation changes layout, action hierarchy, state hierarchy, or screenshots materially; record a no-update rationale only for pattern-compatible action/copy wiring.
  • T067 Update this tasks.md close-out section with implemented/deferred/unsupported actions and validation outcomes.

Phase 13: Validation

Purpose: Run the final Spec365 and regression gate.

  • T068 Run cd apps/platform && php artisan test --compact --filter=Spec365 or targeted direct Spec365 lanes.
  • T069 Run cd apps/platform && php artisan test --compact --filter=Spec364.
  • T070 Run cd apps/platform && php artisan test --compact --filter=Spec363.
  • T071 Run cd apps/platform && php artisan test --compact --filter=Spec362.
  • T072 Run cd apps/platform && php artisan test --compact --filter=Spec361.
  • T073 Run cd apps/platform && php artisan test --compact --filter=Spec360.
  • T074 Run cd apps/platform && php artisan test --compact --filter=Spec359.
  • T075 Run cd apps/platform && php artisan test --compact --filter=Spec358.
  • T076 Run cd apps/platform && php vendor/bin/pint --dirty.
  • T077 Run git diff --check.
  • T081 Run a static scan over changed application files for Livewire v3 APIs: emit, emitTo, and dispatchBrowserEvent.
  • T082 Review the final diff for Filament/Tailwind/build asset changes; if any are required, update spec.md and plan.md before merge.
  • T083 If browser lane was not included in the Spec365 filter, run cd apps/platform && php artisan test --compact tests/Browser/Spec365OperationsUiOperatorActionsSmokeTest.php.

Validation Close-Out

  • php artisan test --compact --filter=Spec365: 23 passed, 160 assertions.
  • php artisan test --compact --filter=Spec364: 10 passed, 59 assertions.
  • php artisan test --compact --filter=Spec363: no tests found.
  • php artisan test --compact --filter=Spec362: 27 passed, 238 assertions.
  • php artisan test --compact --filter=Spec361: 16 passed, 123 assertions.
  • php artisan test --compact --filter=Spec360: 9 passed, 79 assertions.
  • php artisan test --compact --filter=Spec359: 25 passed, 150 assertions.
  • php artisan test --compact --filter=Spec358: no tests found.
  • php vendor/bin/pest tests/Feature/Operations/Spec359OperationRunAdapterReconciliationTest.php tests/Feature/EnvironmentReview/Spec359ReviewComposeReconciliationTest.php tests/Feature/Operations/Spec364RestoreExecuteReconciliationTest.php tests/Feature/Operations/TenantlessOperationRunViewerTest.php tests/Feature/Guards/OperationRunLinkContractGuardTest.php: 42 passed, 194 assertions.
  • php vendor/bin/pest tests/Feature/Monitoring/MonitoringOperationsTest.php tests/Feature/Monitoring/OperationRunResolvedReferencePresentationTest.php tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php tests/Feature/Filament/OperationRunListFiltersTest.php tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php: 37 passed, 271 assertions.
  • php artisan test --compact tests/Browser/Spec365OperationsUiOperatorActionsSmokeTest.php: 3 passed, 42 assertions.
  • php artisan test --compact tests/Browser/Spec360OperationRunCanonicalCutoverSmokeTest.php: 2 passed, 21 assertions.
  • php vendor/bin/pint --dirty: passed after formatting dirty PHP files.
  • Livewire v3 API scan over changed app files for emit, emitTo, and dispatchBrowserEvent: no matches.
  • git diff --check: passed.
  • Final diff review: no Filament panel/provider registration changes, no Tailwind/build asset changes, no new migrations, no env var changes, no queue/cron/storage changes.

Dependencies and Ordering

  • Phase 1 must complete before runtime implementation.
  • Phase 2 must complete before Phases 4-7.
  • Phase 3 should be written before or alongside Phase 2.
  • Reconcile and retry feature tests depend on resolver and authorization decisions.
  • Browser smoke depends on visible UI wiring and localization.
  • Validation runs last.

Parallel Execution Examples

  • T002-T006 can run in parallel during audit.
  • T015-T019 can run in parallel after resolver contract is sketched.
  • T042-T043 can run in parallel with feature test implementation.
  • T046-T052 can be split by action family after shared factories/fixtures exist.

Notes

  • Do not add a new generic retry framework in this spec.
  • Do not add any restore retry/re-execute path.
  • Do not add Force Complete, Mark Succeeded, Delete, Purge, or equivalent copy.
  • Do not add new top-level Operations navigation.
  • Do not expose raw technical diagnostics by default.
  • Do not add new Filament/Tailwind assets unless implementation proves they are required and the spec/plan are updated first.