TenantAtlas/specs/272-operationrun-phase-composite-progress/tasks.md

---
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