--- 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. - [x] 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. - [x] 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`. - [x] 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`. - [x] 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. - [x] 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. - [x] 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. - [x] 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. - [x] 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 - [x] 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 - [x] 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. - [x] 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 - [x] 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. - [x] 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 - [x] 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. - [x] 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 - [x] 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 - [x] 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. - [x] 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 - [x] 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. - [x] 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. - [x] 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`. - [x] 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`. - [x] 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. - [x] 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