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

Implementation Plan: OperationRun Phase & Composite Progress v1

Branch: 272-operationrun-phase-composite-progress | Date: 2026-05-05 | Spec: spec.md Input: Feature specification from /specs/272-operationrun-phase-composite-progress/spec.md

Summary

This plan prepares the bounded non-counted follow-up to Spec 270 and the adjacent counted boundary from Spec 271. The implementation path is to reuse OperationRunProgressContract, OperationUxPresenter, and OperationRunService, add canonical operator-safe phase metadata for baseline_capture and baseline_compare, and add one bounded composite summary path for tenant.review.compose from existing aggregate operation truth. The slice must not invent fake percentages, reopen counted rollout work, add a workflow engine, create a child-run graph, or widen into provider health, support diagnostics, or dashboard work.

Inherited Baseline / Explicit Delta

Inherited baseline

• App\Support\OpsUx\OperationRunProgressContract already centralizes none, activity, counted, phased, and composite progress modes.
• The current contract already classifies baseline evidence-capture context as phased and aggregate multi-run truth as composite, but it currently returns only generic placeholder labels.
• App\Jobs\CaptureBaselineSnapshotJob and App\Jobs\CompareBaselineToTenantJob already persist repo-real baseline phase-shaped context, including eligibility and evidence-capture stats.
• App\Services\TenantReviews\TenantReviewService and App\Jobs\ComposeTenantReviewJob already create the canonical tenant.review.compose run type, and current evidence snapshot summaries already contain aggregate operation counts used later in tenant review composition.
• The current tenant shell adopter already renders generic phased/composite fallbacks through the shared contract without inventing a percentage.
• Spec 271 already owns truthful counted rollout for stable-unit families and must remain distinct from this slice.

Explicit delta in this plan

• add canonical operator-safe phase metadata and label derivation for baseline_capture and baseline_compare
• add one bounded composite summary path for tenant.review.compose from current aggregate operation truth
• keep counted, terminal, and generic activity semantics unchanged except for consuming more truthful non-counted detail
• document the narrowed candidate boundary explicitly: review-pack and evidence-snapshot overlap remain with Spec 271, while provider health and support diagnostics remain deferred until repo-real queued progress truth exists

Technical Context

Language/Version: PHP 8.4, Laravel 12, Filament v5, Livewire v4
Primary Dependencies: existing Ops-UX contract/presenter classes, current baseline services/jobs, current tenant-review services/jobs, Pest v4
Storage: PostgreSQL via existing operation_runs, baseline, evidence snapshot, and tenant review tables
Testing: Pest Unit + Feature
Validation Lanes: fast-feedback, confidence
Target Platform: existing Laravel monolith in apps/platform
Project Type: web application (Laravel monolith with Filament)
Performance Goals: no new poller family, no new query family, and no slower-than-current activity feedback disclosure
Constraints: no fake percentages, no new summary_counts keys, no new persistence, no child-run graph, no dashboard redesign, and no provider-health or support-diagnostics rollout
Scale/Scope: one shared contract extension across 3 selected run families plus one UI standards update and focused regression coverage

Likely Affected Repo Surfaces

• apps/platform/app/Support/OpsUx/OperationRunProgressContract.php
• apps/platform/app/Support/OpsUx/OperationUxPresenter.php
• apps/platform/app/Support/OpsUx/OperationStatusNormalizer.php
• apps/platform/app/Services/OperationRunService.php
• apps/platform/app/Services/Baselines/BaselineCaptureService.php
• apps/platform/app/Jobs/CaptureBaselineSnapshotJob.php
• apps/platform/app/Jobs/CompareBaselineToTenantJob.php
• apps/platform/app/Services/TenantReviews/TenantReviewService.php
• apps/platform/app/Jobs/ComposeTenantReviewJob.php
• apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php
• apps/platform/tests/Unit/Support/OpsUx/OperationRunProgressContractTest.php
• apps/platform/tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php
• apps/platform/tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php
• apps/platform/tests/Feature/BaselineDriftEngine/CaptureBaselineContentTest.php
• apps/platform/tests/Feature/Baselines/BaselineCaptureTest.php
• apps/platform/tests/Feature/Baselines/BaselineCompareExecutionGuardTest.php
• apps/platform/tests/Feature/Baselines/BaselineCompareResumeTokenTest.php
• apps/platform/tests/Feature/TenantReview/TenantReviewOperationsUxTest.php
• apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php
• apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php
• apps/platform/tests/Feature/TenantReview/TenantReviewRbacTest.php
• apps/platform/tests/Feature/Baselines/BaselineProfileAuthorizationTest.php
• docs/ui/tenantpilot-enterprise-ui-standards.md

UI / Filament & Livewire Fit

• The visible adopter remains the existing tenant-shell activity feedback surface. No new page, dashboard card, widget family, or top-level monitoring surface is introduced.
• Canonical Operations collection/detail routes remain diagnostics-first drill-through targets. They may inherit safer phase/composite disclosure through the shared presenter path, but they do not gain a second progress framework.
• The shell remains decision-first. This slice only improves whether selected runs can describe truthful non-counted phase/composite state.
• Filament stays v5 on Livewire v4. Provider registration remains unchanged in apps/platform/bootstrap/providers.php.

RBAC / Policy Fit

• Existing capability gates for baseline capture, baseline compare, and tenant review remain unchanged.
• Existing OperationRun policies remain the only progress-visibility gate.
• No new mutation surface is introduced, so current server-side authorization and confirmation behavior stays on the existing launch/detail surfaces.

Audit / Logging Fit

• Existing queued toasts and terminal notifications remain authoritative and unchanged.
• Existing audit ownership remains the only audit trail for the covered runs; no new run-local audit channel is introduced.
• Progress detail remains derived execution truth inside the current OperationRun ownership model, not a second audit or event stream.

Data & Query Fit

• Progress truth remains fully derived from existing operation_runs.context, operation_runs.summary_counts, and current contract logic.
• Selected phase metadata stays inside existing context JSON and does not create a new persisted entity.
• Composite progress for tenant.review.compose stays bounded to currently available aggregate operation truth from evidence snapshot or review summary data.
• No migration, no new JSON table, no cache layer, and no new persisted user preference or progress mode are planned.

UI / Surface Guardrail Plan

• Guardrail scope: changed surfaces
• Native vs custom classification summary: native Filament + existing Livewire/Blade shell surface
• Shared-family relevance: Ops-UX activity feedback and current run summaries
• State layers in scope: shell, detail compatibility
• Audience modes in scope: operator-MSP
• Decision/diagnostic/raw hierarchy plan: decision-first on shell, diagnostics-second on Operations detail
• Raw/support gating plan: unchanged; raw/support detail remains on diagnostics surfaces only
• One-primary-action / duplicate-truth control: keep one dominant View operation action and one shared progress contract that now supplies richer non-counted labels
• Handling modes by drift class or surface: review-mandatory
• Repository-signal treatment: review-mandatory
• Special surface test profiles: global-context-shell
• Required tests or manual smoke: functional-core, state-contract
• Exception path and spread control: none planned
• Active feature PR close-out entry: Guardrail / Smoke Coverage

Shared Pattern & System Fit

• Cross-cutting feature marker: yes
• Systems touched: Ops-UX progress contract, Ops-UX presenter, baseline jobs/services, tenant-review queue/composition path, shell activity feedback
• Shared abstractions reused: OperationRunProgressContract, OperationUxPresenter, OperationStatusNormalizer, OperationRunService
• New abstraction introduced? why?: no new top-level abstraction planned; extend the current contract/presenter path only
• Why the existing abstraction was sufficient or insufficient: classification already exists; what is missing is canonical operator-safe phase/composite detail for selected run families
• Bounded deviation / spread control: selected families only; any additional run family without repo-real truthful phase/composite detail stays on current generic fallback

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes, for active progress meaning only
• Central contract reused: existing OperationRun Start UX Contract plus OperationRunProgressContract
• Delegated UX behaviors: queued toast, canonical run links, run-enqueued event, and terminal-notification lifecycle remain delegated and unchanged
• Surface-owned behavior kept local: current launch inputs, detailed diagnostics, and domain-specific result explanations stay local to their current surfaces
• Queued DB-notification policy: N/A - unchanged
• Terminal notification path: unchanged central lifecycle mechanism
• Exception path: none

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: no
• Provider-owned seams: N/A
• Platform-core seams: OperationRun truth, Ops-UX contract/presenter, baseline and tenant-review execution truth
• Neutral platform terms / contracts preserved: Operation, activity, phase progress, composite progress, terminal outcome
• Retained provider-specific semantics and why: none
• Bounded extraction or follow-up path: provider health and support diagnostics remain an explicit later follow-up if queued progress truth exists later

Constitution Check

GATE: Must pass before implementation begins and again before merge.

• Inventory-first: PASS. The slice only enriches current execution feedback over existing operational truth.
• Read/write separation: PASS. No new external write path is introduced; current domain jobs keep their existing product responsibilities and only persist better progress detail in OperationRun context.
• Graph contract path: PASS. No new Graph or provider contract is introduced.
• Deterministic capabilities: PASS. Authorization and run visibility remain deterministic and testable.
• RBAC-UX: PASS. Visibility remains on existing tenant/admin boundaries and current OperationRun policies.
• Run observability: PASS. Long-running work still flows through current OperationRun ownership and current Ops-UX surfaces.
• Ops-UX lifecycle: PASS. status and outcome ownership remains on OperationRunService; this slice only adds richer non-counted detail.
• Ops-UX summary counts: PASS. No new summary_counts key is planned.
• Test governance: PASS. Proof remains bounded to Unit plus Feature.
• Proportionality / no premature abstraction: PASS. No new workflow engine, child-run graph, or second presenter path is introduced.
• Persisted truth / behavioral state: PASS. No new table, cache, or lifecycle family is added.
• Shared pattern first / UI semantics / Filament-native UI: PASS. Existing Ops-UX path remains central and the visible adopter is unchanged.
• Provider boundary: PASS. No provider/platform seam change.
• Filament/Laravel panel safety: PASS. Filament v5 stays on Livewire v4, provider registration remains in apps/platform/bootstrap/providers.php, and no assets change.

Gate evaluation: PASS.

Test Governance Check

• Test purpose / classification by changed surface: Unit for contract precedence and label derivation; Feature for selected baseline and tenant-review writer seams plus current shell adoption
• Affected validation lanes: fast-feedback, confidence
• Why this lane mix is the narrowest sufficient proof: the shared contract already has a focused unit suite, and the selected run families already have domain feature suites that can prove current context/summary truth without adding new browser or heavy-governance obligations
• Narrowest proving command(s):
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/OpsUx/OperationRunProgressContractTest.php
  • 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
• Fixture / helper / factory / seed / context cost risks: low to moderate; reuse current tenant context helpers, existing baseline helpers, and current tenant-review fixtures instead of adding a new provider-heavy harness
• Expensive defaults or shared helper growth introduced?: no
• Heavy-family additions, promotions, or visibility changes: none
• Surface-class relief / special coverage rule: global-context-shell
• Closing validation and reviewer handoff: rerun the two proving commands above and verify that selected run families now expose truthful non-counted detail, the full precedence chain phased > composite > counted > activity still holds, counted semantics stay counted-only, malformed metadata degrades safely, current 404/403 visibility semantics remain intact, no new polling loop was introduced, and excluded families remain excluded
• Budget / baseline / trend follow-up: none expected beyond a small feature-local increase
• Review-stop questions: did any run family leak raw technical phase labels, did any composite summary masquerade as a percentage, did any excluded family sneak in, and did any new summary_counts key or workflow framework appear?
• Escalation path: reject-or-split for any provider-health/support expansion, dashboard work, child-run graph persistence, or workflow-engine drift
• Active feature PR close-out entry: Guardrail / Smoke Coverage
• Why no dedicated follow-up spec is needed: this package is itself the bounded non-counted progress follow-up to Spec 270; remaining excluded ideas are already named as explicit later follow-ups.

Project Structure

Documentation (this feature)

specs/272-operationrun-phase-composite-progress/
├── spec.md
├── plan.md
├── tasks.md
└── checklists/
    └── requirements.md

Source Code (expected implementation surfaces)

apps/platform/app/Support/OpsUx/
apps/platform/app/Services/OperationRunService.php
apps/platform/app/Services/Baselines/BaselineCaptureService.php
apps/platform/app/Jobs/CaptureBaselineSnapshotJob.php
apps/platform/app/Jobs/CompareBaselineToTenantJob.php
apps/platform/app/Services/TenantReviews/TenantReviewService.php
apps/platform/app/Jobs/ComposeTenantReviewJob.php
apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php
apps/platform/tests/Unit/Support/OpsUx/
apps/platform/tests/Feature/OpsUx/
apps/platform/tests/Feature/Baselines/
apps/platform/tests/Feature/TenantReview/
apps/platform/tests/Feature/Filament/
docs/ui/tenantpilot-enterprise-ui-standards.md

Structure Decision: keep the rollout local to current jobs/services plus the existing Ops-UX support family. Do not introduce a workflow engine, child-run graph, or second progress framework.

Data / Migration Implications

• No migration or schema change is planned.
• No new persisted progress mode or preference is allowed.
• Selected phase/composite detail remains inside existing operation_runs.context JSON only.
• No backfill is planned. Historical runs remain historical truth; the rollout affects future execution and active-run rendering only.

Rollout Considerations

• Filament remains v5 on Livewire v4. Provider registration remains in apps/platform/bootstrap/providers.php.
• No global search or asset change is required because the slice changes only current run-progress truth.
• No destructive action or confirmation model changes are planned.
• No deployment step beyond ordinary code deploy, focused tests, and current formatting validation is expected.

Risk Controls

• Reject any implementation that turns phase/composite labels into fake percentages or a synthetic progress bar.
• Reject any implementation that leaks raw technical step names, exception class names, or transport details into the default operator-facing progress label.
• Reject any implementation that adds a child-run graph or persists child_run_ids as a new framework instead of a bounded current-release need.
• Reject any implementation that widens the rollout to provider health, support diagnostics, review-pack, or evidence-snapshot overlap without an explicit follow-up spec.
• Reject any implementation that changes counted precedence or adds a new summary_counts key to compensate for missing phase/composite truth.

Implementation Phases

Phase 0 - Confirm The Selected Non-Counted Seams

• Verify the current phase and composite fallback behavior in OperationRunProgressContract, the current shell adopter, the current baseline jobs, and the current tenant-review queue/composition path.
• Reconfirm that provider health, support diagnostics, review-pack overlap, and child-run graph persistence remain out of scope.

Phase 1 - Roll Out Baseline Phase Metadata

• Add canonical operator-safe phase metadata for baseline_capture and baseline_compare over the repo-real lifecycle boundaries that already exist today.

Phase 2 - Roll Out Tenant Review Composite Summary

• Seed a bounded composite summary for tenant.review.compose from current evidence-basis operation truth and keep it explicitly non-counted.

Phase 3 - Lock The Guardrail And Proof

• Update the UI standards and focused tests so later non-counted progress work extends one contract rather than inventing new semantics.

Proportionality Review

• Current operator problem: current non-counted runs know more than the product currently says, yet the shell still shows vague generic fallback copy.
• Existing structure is insufficient because: the shared contract can classify phased and composite, but it cannot yet explain them with canonical operator-safe detail for selected run families.
• Narrowest correct implementation: update only selected repo-real phase/composite families and keep all other work on current generic fallback or counted semantics.
• Ownership cost created: selected context writes in existing jobs/services, focused tests, and one standards update.
• Alternative intentionally rejected: a workflow engine, child-run graph, or fake percentage model was rejected because all would be structurally heavier and less truthful than the current-release need.
• Release truth: current-release truth. The repo already contains the contract, the shell adopter, the baseline phase hints, and the tenant-review aggregate truth needed for this rollout.