ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
b82c56f1f3
TenantAtlas/specs/272-operationrun-phase-composite-progress/tasks.md
Ahmed Darrazi 4256e642ed
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 1m39s
Details
chore: commit all changes (automated)
2026-05-05 12:38:55 +02:00

17 KiB
Raw Blame History

description
Task list for OperationRun Phase & Composite Progress v1

Tasks: OperationRun Phase & Composite Progress v1

Input: Design documents from specs/272-operationrun-phase-composite-progress/
Prerequisites: specs/272-operationrun-phase-composite-progress/spec.md, specs/272-operationrun-phase-composite-progress/plan.md, specs/272-operationrun-phase-composite-progress/checklists/requirements.md

Review Artifact: specs/272-operationrun-phase-composite-progress/checklists/requirements.md is the outcome-of-record for the review outcome class, workflow outcome, and test-governance outcome. If implementation widens into provider health or support-diagnostics rollout, review-pack overlap, dashboard work, child-run graph persistence, or a workflow engine, update that artifact before continuing.

Tests: REQUIRED (Pest). Keep proof bounded to existing Unit plus Feature suites for Ops-UX, Baselines, TenantReview, and current run-detail compatibility. Browser coverage remains owned by prior Ops-UX specs and must not become a hidden requirement here. Operations: No new OperationRun type, no new lifecycle family, no fake percentages, no workflow engine, no new summary_counts keys, no dashboard card, no provider health or support-diagnostics rollout, and no child-run graph persistence. RBAC: Reuse current OperationRun policies, baseline capabilities, and tenant-review capabilities. No tenantless leakage from tenant surfaces; non-counted progress must remain invisible for inaccessible runs. Shared Pattern Reuse: Reuse OperationRunProgressContract, OperationUxPresenter, OperationStatusNormalizer, OperationRunService, and docs/ui/tenantpilot-enterprise-ui-standards.md. Do not create a second local progress translator in Blade, Livewire, or domain jobs. Filament / Panel Guardrails: Filament remains v5 on Livewire v4. Provider registration remains unchanged in apps/platform/bootstrap/providers.php. No new panel, resource, global-search behavior, or asset strategy is allowed. This slice changes current progress truth only. Organization: Tasks are grouped by user story so baseline capture, baseline compare, tenant-review composite progress, and the future-boundary documentation remain independently reviewable.

Test Governance Notes

  • Lane mix stays Unit plus Feature.
  • Prefer extending current Ops-UX, Baselines, and TenantReview suites before creating a new family.
  • Browser proof stays with prior Ops-UX specs and must not become a hidden requirement here.
  • Validation commands must stay file-scoped and run through Sail.

Phase 1: Setup (Shared Context)

Purpose: confirm the bounded manual-promotion slice, the inherited progress-contract rules, and the repo-real phase/composite seams before runtime edits begin.

  • T001 Review specs/272-operationrun-phase-composite-progress/spec.md, specs/272-operationrun-phase-composite-progress/plan.md, specs/272-operationrun-phase-composite-progress/checklists/requirements.md, docs/product/spec-candidates.md, docs/product/roadmap.md, specs/270-operationrun-progress-contract/spec.md, specs/271-counted-progress-rollout/spec.md, specs/268-operationrun-activity-feedback/spec.md, docs/ui/tenantpilot-enterprise-ui-standards.md, and .specify/memory/constitution.md together so the slice stays on repo-real non-counted progress and keeps counted overlap plus dashboard work explicitly out of scope.
  • T002 [P] Confirm the current shared contract and host seams in apps/platform/app/Support/OpsUx/OperationRunProgressContract.php, apps/platform/app/Support/OpsUx/OperationUxPresenter.php, apps/platform/app/Support/OpsUx/OperationStatusNormalizer.php, and the current shell progress host proofs in apps/platform/tests/Unit/Support/OpsUx/OperationRunProgressContractTest.php and apps/platform/tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php.
  • T003 [P] Confirm the current baseline phase-writer seams in apps/platform/app/Services/Baselines/BaselineCaptureService.php, apps/platform/app/Jobs/CaptureBaselineSnapshotJob.php, apps/platform/app/Jobs/CompareBaselineToTenantJob.php, and apps/platform/app/Services/Baselines/BaselineContentCapturePhase.php.
  • T004 [P] Confirm the current tenant-review composite seams and explicit exclusions in apps/platform/app/Services/TenantReviews/TenantReviewService.php, apps/platform/app/Jobs/ComposeTenantReviewJob.php, apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php, and the related proof owner apps/platform/tests/Feature/TenantReview/TenantReviewOperationsUxTest.php.

Phase 2: Foundational (Blocking Prerequisites)

Purpose: settle the shared contract boundary, the selected non-counted vocabulary, and the focused proof owners before user-story runtime work begins.

Critical: no user-story runtime work should begin until this phase is complete.

  • T005 [P] Create or extend failing coverage in apps/platform/tests/Unit/Support/OpsUx/OperationRunProgressContractTest.php for operator-safe phase/composite label derivation, malformed-metadata fallback, and the rule that current counted progress remains subordinate to truthful phase/composite precedence.
  • T006 [P] Extend apps/platform/tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php and apps/platform/tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php only as needed so the shell proves selected phase/composite labels render without a progress bar and the full precedence chain phased > composite > counted > activity still holds, with counted mode available only when truthful processed and total exist.
  • T007 [P] Extend apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php only if presenter or run-detail disclosure changes require proof that operator-safe phase/composite copy stays separate from terminal artifact truth and detailed diagnostics.
  • T008 [P] Review or extend apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php, apps/platform/tests/Feature/TenantReview/TenantReviewRbacTest.php, and apps/platform/tests/Feature/Baselines/BaselineProfileAuthorizationTest.php so current 404/403 semantics, inaccessible-run invisibility, and unchanged confirmation behavior remain explicit proof owners for this slice.

Checkpoint: the shared contract boundary and focused proof owners are settled before implementation begins.

Phase 3: User Story 1 - See truthful phase progress for baseline capture (Priority: P1)

Goal: baseline capture exposes operator-safe phase truth for current lifecycle boundaries without inventing a percentage.

Independent Test: start baseline capture through the current service/job path, exercise current standard and full-content branches, and verify the active run exposes truthful phase labels while remaining explicitly non-counted.

Tests for User Story 1

  • T009 [P] [US1] Extend apps/platform/tests/Feature/Baselines/BaselineCaptureTest.php and apps/platform/tests/Feature/BaselineDriftEngine/CaptureBaselineContentTest.php for phase metadata seeding at preflight or runtime-recheck, current subject or snapshot work, optional evidence capture, persistence, and finalization.

Implementation for User Story 1

  • T010 [US1] Update apps/platform/app/Services/Baselines/BaselineCaptureService.php and apps/platform/app/Jobs/CaptureBaselineSnapshotJob.php only as needed so baseline_capture writes canonical phase key and operator-safe label details into existing OperationRun.context as work moves through current lifecycle boundaries.
  • T011 [US1] Review blocked, resumed, failed, and completed capture paths so terminal runs retain diagnostic context without leaving stale active-phase truth and so missing phase metadata degrades safely to the current generic fallback.

Checkpoint: User Story 1 is independently functional when baseline capture can describe its current phase truthfully without ever rendering fake counted progress.

Phase 4: User Story 2 - See truthful phase progress for baseline compare (Priority: P1)

Goal: baseline compare exposes operator-safe phase truth for current preparation, evidence-capture, compare, persistence, and finalization boundaries without inventing a percentage.

Independent Test: queue a baseline compare that exercises current preparation and optional evidence-capture branches, then verify the run exposes truthful phase labels and remains explicitly non-counted.

Tests for User Story 2

  • T012 [P] [US2] Extend apps/platform/tests/Feature/Baselines/BaselineCompareResumeTokenTest.php and apps/platform/tests/Feature/Baselines/BaselineCompareExecutionGuardTest.php only as needed for phase metadata around current preparation, evidence capture or resume, compare execution, persistence, and finalization.
  • T013 [P] [US2] Extend apps/platform/tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php or apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php only as needed so baseline compare phase labels remain operator-safe and explicitly non-counted on visible surfaces.

Implementation for User Story 2

  • T014 [US2] Update apps/platform/app/Jobs/CompareBaselineToTenantJob.php and any immediately adjacent baseline helper only as needed so baseline_compare publishes canonical phase key and operator-safe label detail for current preparation, evidence capture or resume, compare execution, persistence, and finalization.
  • T015 [US2] Review partial, blocked, failed, and malformed-context compare paths so phase detail degrades safely when metadata is absent and never overrides terminal outcome or artifact-truth semantics.

Checkpoint: User Story 2 is independently functional when baseline compare can describe its current phase truthfully without falling back to fake counted progress.

Phase 5: User Story 3 - See truthful composite progress for tenant review compose (Priority: P2)

Goal: tenant.review.compose exposes a bounded composite summary from current aggregate operation truth without pretending it is percentage progress.

Independent Test: create or refresh a tenant review from an evidence snapshot with known operations summary counts, then verify the active run exposes a truthful composite label with aggregate child hints while remaining non-counted.

Tests for User Story 3

  • T016 [P] [US3] Extend apps/platform/tests/Feature/TenantReview/TenantReviewOperationsUxTest.php and current shell proof owners only as needed for composite summary labels derived from evidence-basis operation counts plus current failed or partial child hints, including safe fallback when aggregate truth is zero, missing, or too weak for composite disclosure.

Implementation for User Story 3

  • T017 [US3] Update apps/platform/app/Services/TenantReviews/TenantReviewService.php, apps/platform/app/Jobs/ComposeTenantReviewJob.php, and apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php only as needed so tenant.review.compose seeds bounded composite summary metadata from the current evidence snapshot operations summary before running work and finalizes it after composition completes, while degrading safely to generic activity/composite fallback when that aggregate truth is absent.
  • T018 [US3] Keep composite v1 bounded to tenant.review.compose and current aggregate summary fields; record provider health/support diagnostics, review-pack or evidence-snapshot overlap, and child-run link expansion as follow-up explicitly instead of widening the implementation slice.

Checkpoint: User Story 3 is independently functional when tenant.review.compose can summarize current aggregate operation posture truthfully without rendering counted progress.

Phase 6: User Story 4 - Preserve non-counted progress boundaries in docs and review artifacts (Priority: P2)

Goal: future contributors can extend non-counted progress without silently reopening fake percentages, workflow-engine drift, or excluded run families.

Independent Test: review the standards update and the completed proof list together, then confirm that counted overlap, provider health/support diagnostics, dashboard work, and child-run graph persistence remain named follow-ups rather than hidden scope here.

Implementation for User Story 4

  • T019 [US4] Update docs/ui/tenantpilot-enterprise-ui-standards.md with the current phase/composite rules: selected families only, operator-safe non-technical labels, counted precedence unchanged, composite summaries explicitly non-counted, and excluded candidate ideas named as later follow-ups.
  • T020 [US4] Review the resulting package and touched code to confirm there is still no workflow engine, no dashboard card, no provider health/support-diagnostics rollout, no review-pack or evidence-snapshot overlap, no child-run graph persistence, and no new summary_counts key.

Checkpoint: User Story 4 is independently functional when future-extension boundaries are explicit in both docs and the feature package.

Phase 7: Polish & Cross-Cutting Validation

Purpose: validate the bounded slice, stop drift, and hand off a clean implementation path.

  • T021 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/OpsUx/OperationRunProgressContractTest.php.
  • T022 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php tests/Feature/BaselineDriftEngine/CaptureBaselineContentTest.php tests/Feature/Baselines/BaselineCaptureTest.php tests/Feature/Baselines/BaselineCompareResumeTokenTest.php tests/Feature/Baselines/BaselineCompareExecutionGuardTest.php tests/Feature/TenantReview/TenantReviewOperationsUxTest.php tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php tests/Feature/Operations/TenantlessOperationRunViewerTest.php tests/Feature/TenantReview/TenantReviewRbacTest.php tests/Feature/Baselines/BaselineProfileAuthorizationTest.php.
  • T023 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent for touched platform files.
  • T024 [P] Review touched code to confirm Filament stays on Livewire v4, provider registration remains unchanged in apps/platform/bootstrap/providers.php, no new assets were registered, no new globally searchable resource behavior was introduced, no new parallel polling loop was added, and the full precedence chain phased > composite > counted > activity still holds with counted mode requiring truthful processed plus total.

Dependencies & Execution Order

Phase Dependencies

  • Phase 1 (Setup): no dependencies; start immediately.
  • Phase 2 (Foundational): depends on Phase 1 and blocks user-story work.
  • Phase 3 (US1): depends on Phase 2 and establishes the clearest repo-real phase rollout target.
  • Phase 4 (US2): depends on Phase 2 and should land after or alongside US1 so both baseline phase families share one operator-safe vocabulary.
  • Phase 5 (US3): depends on Phase 2 and should land after the baseline phase path so composite v1 reuses the same non-counted contract discipline.
  • Phase 6 (US4): depends on Phases 3 through 5 so the documented boundary matches the implemented slice.
  • Phase 7 (Polish): depends on all desired user stories being complete.

User Story Dependencies

  • US1 (P1): independently testable after Phase 2 and delivers the clearest immediate value because baseline capture already persists repo-real phase truth.
  • US2 (P1): independently testable after Phase 2 and completes the baseline non-counted execution pair.
  • US3 (P2): independently testable after Phase 2 and completes the approved composite v1 slice for current aggregate tenant-review work.
  • US4 (P2): independently testable after Phases 3 through 5 and is required for package completion because the narrowed 271/272 boundary is part of the approved scope.

Within Each User Story

  • Write or extend the listed Pest coverage first and make it fail for the intended gap.
  • Land the writer-side metadata changes before adjusting any shared host assertion that depends on that new truth.
  • Re-run the narrowest affected validation command after each story checkpoint before moving on.

Implementation Strategy

Suggested MVP Scope

  • MVP = US1 + US2, because the first enterprise-visible value arrives once the current baseline capture and compare families can show truthful non-counted phase progress through the shared contract.

Incremental Delivery

  1. Complete Phase 1 and Phase 2.
  2. Deliver US1.
  3. Deliver US2.
  4. Deliver US3.
  5. Land US4 documentation and boundary hardening.
  6. Finish with focused validation and formatting.

Team Strategy

  1. Settle the shared contract boundary and proof owners first.
  2. Keep baseline capture, baseline compare, and tenant-review composite edits serialized per family.
  3. Do not widen into provider health/support progress, review-pack overlap, dashboard work, or a workflow engine while implementing this package.

Deferred Follow-Ups / Non-Goals

  • provider health or support-diagnostics progress rollout
  • review-pack or evidence-snapshot non-counted progress overlap with Spec 271
  • child-run graph persistence through child_run_ids or operation_run_ids
  • 273 - Tenant Dashboard Active Operations Summary Card
  • any workflow-engine or AI-generated progress explanation layer