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

Feature Specification: OperationRun Phase & Composite Progress v1

Feature Branch: 272-operationrun-phase-composite-progress
Created: 2026-05-05
Status: Ready for implementation
Input: Manual promotion from docs/product/spec-candidates.md after the repo-based next-best-prep review confirmed the automatic queue is intentionally empty and the user explicitly chose to promote candidate 272.

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: specs/270-operationrun-progress-contract/ already introduced truthful none, activity, counted, phased, and composite progress capabilities, but the repo still treats phased and composite as generic fallbacks. Baseline capture and baseline compare already persist phase-shaped context, and tenant.review.compose already carries aggregate operation truth, yet operators still only get vague Phase progress pending. or Composite progress pending. copy.
• Today's failure: long-running, non-countable, or aggregate runs can expose meaningful execution truth today, but the shared contract cannot translate that truth into operator-safe phase text or composite summaries. That leaves enterprise operators with either vague indeterminate copy or pressure to invent fake percentages and local explanations.
• User-visible improvement: selected non-countable OperationRun families show truthful operator-safe phase text or composite child summaries while remaining explicitly non-counted. Operators can tell what the system is doing without a fabricated percentage.
• Smallest enterprise-capable version: extend the existing shared Ops-UX progress contract and current shell adopter so baseline_capture, baseline_compare, and tenant.review.compose can surface canonical non-counted phase/composite labels from existing OperationRun.context and existing aggregate summary truth, without adding a workflow engine, a dashboard redesign, or a second presenter layer.
• Explicit non-goals: no full workflow engine, no new top-level monitoring page, no child-run graph persistence, no provider health or support-diagnostics rollout unless repo-real queued progress truth appears first, no review-pack or evidence-snapshot overlap with Spec 271, no fake percentages, no AI-generated progress explanations, no new summary_counts keys, and no new OperationRun lifecycle state.
• Permanent complexity imported: one bounded non-counted progress detail extension inside the existing Ops-UX contract, one derived phase-step vocabulary kept in code and docs only, selected context-shape updates for repo-real run families, focused Pest Unit plus Feature coverage, and one UI standards update.
• Why now: Spec 270 already prepared the shared contract and Spec 271 already claims the counted rollout boundary. The next truthful gap is the current generic phased and composite fallback behavior. Repo truth already contains real baseline phase context and tenant-review aggregate counts, so the product can now make those categories honest and useful without inventing a new framework.
• Why not local: adding baseline-only or tenant-review-only labels would fragment progress semantics across the shell, Operations detail, and future non-counted run families. The truth gap is shared, so the fix must stay on the shared contract.
• Approval class: Core Enterprise
• Red flags triggered: derived phase vocabulary, selected persisted context metadata for non-counted progress, and one shared contract extension. Defense: the vocabulary stays derived only, persistence stays inside the existing operation_runs.context JSON, and the feature reuses the current Ops-UX contract rather than adding a second framework.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 1 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 10/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: tenant + canonical-view
• Primary Routes:
  • /admin/t/{tenant}/... tenant-scoped launch surfaces whose existing shell feedback adopts the shared progress contract
  • /admin/t/{tenant} remains the contextual surface where recent-operation activity hints stay visible; no new tenant dashboard card is introduced
  • /admin/operations and /admin/operations/{run} remain the canonical collection/detail routes that must stay compatible with the resulting phase/composite truth
• Data Ownership: existing operation_runs.context, operation_runs.summary_counts, operation_runs.status, and operation_runs.outcome remain the only persisted execution truth. This feature may standardize new phase/composite context payloads for selected run families inside context, but it must not add a table, cache, mirror projection, or persisted progress-mode flag.
• RBAC: existing capability checks for baseline capture, baseline compare, and tenant review continue to govern launch access. Existing OperationRun policies remain the only visibility gate for phase/composite progress feedback.

For canonical-view behavior:

• Default filter behavior when tenant-context is active: unchanged. The shell continues to show only the current tenant's visible runs, and canonical Operations collection/detail access remains tenant-aware when tenant context is active.
• Explicit entitlement checks preventing cross-tenant leakage: unchanged. Non-members remain 404, member-but-missing-capability remains 403, and no selected run family may emit phase/composite copy for a run the actor cannot already view.

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes
• Interaction class(es): status messaging, activity feedback, execution-truth summaries, and canonical operation guidance
• Systems touched: OperationRunProgressContract, OperationUxPresenter, OperationStatusNormalizer, current shell activity feedback, baseline capture/compare jobs, tenant-review composition start/queue path, and docs/ui/tenantpilot-enterprise-ui-standards.md
• Existing pattern(s) to extend: Spec 270 shared progress contract, current Ops-UX 3-surface lifecycle rules, current shell feedback host, and current baseline/tenant-review execution truth
• Shared contract / presenter / builder / renderer to reuse: App\Support\OpsUx\OperationRunProgressContract, App\Support\OpsUx\OperationUxPresenter, App\Support\OpsUx\OperationStatusNormalizer, App\Services\OperationRunService, and the existing shell activity feedback surface
• Why the existing shared path is sufficient or insufficient: the repo already has one shared progress contract and one shared presenter path, but phased and composite currently stop at generic placeholder labels. The gap is not classification; it is the lack of canonical operator-safe detail for selected non-counted run families.
• Allowed deviation and why: none planned. The slice must extend the shared contract and shared presenter path rather than introducing a baseline-local or tenant-review-local progress helper.
• Consistency impact: preparing, fetching, processing, persisting, and finalizing must remain operator-safe labels rather than raw internals, and composite summaries must never imply a counted percentage unless processed and total separately satisfy the counted contract.
• Review focus: reviewers must block any implementation that leaks raw technical phase names, invents fake percentages, reorders the current progress-contract precedence, or quietly widens the feature to unrelated run families.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: yes
• Shared OperationRun UX contract/layer reused: existing OperationRun Start UX Contract plus App\Support\OpsUx\OperationRunProgressContract and App\Support\OpsUx\OperationUxPresenter
• Delegated start/completion UX behaviors: queued toast wording, canonical View operation links, tenant-safe URL resolution, current run-enqueued browser events, and existing terminal notifications remain delegated to the current shared path and are unchanged in this slice
• Local surface-owned behavior that remains: current baseline and tenant-review launch inputs plus current run-detail diagnostics stay local to their existing surfaces; non-counted progress semantics do not
• Queued DB-notification policy: N/A - unchanged
• Terminal notification path: unchanged central lifecycle mechanism
• Exception required?: none

Provider Boundary / Platform Core Check (mandatory)

• Shared provider/platform boundary touched?: no
• Boundary classification: N/A
• Seams affected: N/A
• Neutral platform terms preserved or introduced: Operation, progress, phase progress, composite progress, activity, terminal outcome
• Provider-specific semantics retained and why: none
• Why this does not deepen provider coupling accidentally: the feature only clarifies shared execution truth over existing platform-owned OperationRun data and existing domain jobs
• Follow-up path: none

UI / Surface Guardrail Impact (mandatory)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Existing OperationRun activity feedback on the tenant shell	yes	Native Filament + existing Livewire/Blade surface	Ops-UX activity feedback and execution-truth summaries	shell	no	No new surface is introduced; selected runs gain truthful phase/composite detail within the existing host

Decision-First Surface Role (mandatory)

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Existing OperationRun activity feedback on the tenant shell	Primary Decision Surface	Decide whether current work simply needs time, is in a meaningful phase, or needs review because aggregate child work is failing	operation label, lifecycle state, one truthful non-counted phase/composite label when available, and canonical View operation action	full run detail, logs, evidence, and diagnostics stay on Operations detail	Primary because it is the current visible progress host and the first place operators check after starting long-running work	Follows the existing start-surface workflow	Replaces vague generic fallback copy without creating another widget family

Audience-Aware Disclosure (mandatory)

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
Existing OperationRun activity feedback on the tenant shell	operator-MSP	operation label, lifecycle state, operator-safe phase/composite label, and canonical open link	one concise guidance line only when it changes the next action	raw payloads, failure internals, evidence details, and unrestricted diagnostics	View operation	raw/support detail stays on Operations detail	the shell shows only one progress meaning derived from the shared contract rather than per-run-family ad hoc labels

UI/UX Surface Classification (mandatory)

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
Existing OperationRun activity feedback on the tenant shell	Monitoring hint	Activity shell hint	Open the most relevant operation if follow-up is needed	explicit View operation link	forbidden	overflow navigation only	none	/admin/operations?tenant_id={currentTenant}	/admin/operations/{run}	current tenant context from the shell	Operation	lifecycle state plus one truthful non-counted progress label	none

Operator Surface Contract (mandatory)

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Existing OperationRun activity feedback on the tenant shell	Tenant operator	Decide whether active work is in a meaningful phase, an aggregate child-review state, or merely generic activity	Start-surface hint	What is this operation doing right now, and do I need to act?	operation label, lifecycle state, operator-safe phase/composite label, canonical open link	detailed run diagnostics and evidence on Operations pages	lifecycle, progress capability	none	View operation, Show all operations	none

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no
• New persisted entity/table/artifact?: no
• New abstraction?: no new top-level abstraction by default; the slice extends the existing progress contract and presenter path only
• New enum/state/reason family?: yes - one derived phase-step vocabulary and one bounded composite-summary shape, both kept in code and docs only
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: selected non-countable or aggregate runs already carry more truthful execution detail than the product surfaces today, but that truth is trapped in raw context or generic placeholders
• Existing structure is insufficient because: the current generic phased/composite fallback tells operators only that some truth exists, not what is actually happening or why a run still deserves patience versus review
• Narrowest correct implementation: extend the existing shared progress contract and selected existing jobs/services so only repo-real phase/composite families gain operator-safe non-counted detail
• Ownership cost: selected context metadata writes in current jobs/services, focused Unit plus Feature coverage, and one UI standards update
• Alternative intentionally rejected: forcing these runs into counted percentages or introducing a workflow engine was rejected because both options would be either dishonest or structurally disproportionate
• Release truth: current-release truth. The repo already contains phase-shaped baseline context and aggregate tenant-review operation truth that justify this bounded extension now.

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement of vague phase/composite fallback copy is preferred over preserving duplicate local semantics.

Testing / Lane / Runtime Impact (mandatory)

• Test purpose / classification: Unit, Feature
• Validation lane(s): fast-feedback, confidence
• Why this classification and these lanes are sufficient: the slice changes shared render semantics plus current job/service metadata writes. One focused Unit suite can prove capability precedence and label derivation cheaply, while focused Feature suites can prove the selected baseline and tenant-review seams persist truthful non-counted detail and the existing shell host renders it without inventing a percentage.
• New or expanded test families: extend tests/Unit/Support/OpsUx/OperationRunProgressContractTest.php, tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php, tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php, tests/Feature/Baselines/BaselineCaptureTest.php, tests/Feature/BaselineDriftEngine/CaptureBaselineContentTest.php, tests/Feature/Baselines/BaselineCompareResumeTokenTest.php, tests/Feature/Baselines/BaselineCompareExecutionGuardTest.php, and tests/Feature/TenantReview/TenantReviewOperationsUxTest.php; extend tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php, tests/Feature/Operations/TenantlessOperationRunViewerTest.php, tests/Feature/TenantReview/TenantReviewRbacTest.php, and tests/Feature/Baselines/BaselineProfileAuthorizationTest.php only as needed when presenter or authorization compatibility proof changes require it
• Fixture / helper cost impact: low to moderate. Reuse existing OperationRun factories, baseline helpers, tenant-review fixtures, and current tenant context helpers; do not add a new browser family or provider-heavy test harness
• Heavy-family visibility / justification: none
• Special surface test profile: global-context-shell
• Standard-native relief or required special coverage: ordinary Unit plus Feature coverage only. Browser proof remains out of scope because layout and clickability are already owned by prior Ops-UX specs.
• Reviewer handoff: reviewers must confirm that phase/composite labels are operator-safe, the full precedence chain phased > composite > counted > activity still holds, counted progress remains gated strictly by processed plus total, malformed or missing metadata degrades safely, current 404/403 visibility semantics remain intact, and excluded run families remain excluded
• Budget / baseline / trend impact: small feature-local increase only
• Escalation needed: reject-or-split if implementation widens into provider health or support-diagnostics rollout, dashboard work, child-run graph persistence, or a new workflow engine
• Active feature PR close-out entry: Guardrail / Smoke Coverage
• Planned validation commands:
  • 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

User Scenarios & Testing (mandatory)

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

As a tenant operator, I need baseline capture to tell me which major phase is active without showing a fake percentage, so I can tell whether the run is still preparing, capturing evidence, persisting a snapshot, or truly stuck.

Why this priority: baseline capture is already a repo-real phase candidate because it persists preflight/runtime eligibility context and full-content evidence-capture stats today.

Independent Test: start a baseline capture through the current service and job path, drive both standard and full-content paths, and verify that active runs expose truthful operator-safe phase labels without rendering a determinate progress bar.

Acceptance Scenarios:

1. Given a baseline capture run is queued and the runtime eligibility recheck begins, When the run becomes active, Then the shared contract exposes an operator-safe preparation or fetch phase instead of generic pending copy.
2. Given full-content evidence capture is underway, When the run reports evidence-capture stats, Then the shell shows a phase label for the current work and does not render a counted progress bar unless processed and total separately satisfy counted semantics.
3. Given the run blocks, fails, or completes, When the run becomes terminal, Then terminal outcome remains authoritative and the progress host no longer behaves like active phase progress.

---

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

As a tenant operator, I need baseline compare to expose which major phase is active, so I can distinguish scope preparation, evidence capture, compare execution, and finalization without guessing from a generic running label.

Why this priority: baseline compare already carries repo-real evidence-capture phase stats and resume-token context, which makes it the second clearest non-counted rollout target.

Independent Test: queue a baseline compare that exercises preparation, optional evidence capture, and completion or partial-completion paths, then verify that the run exposes operator-safe phase labels and still avoids counted rendering when only phase truth exists.

Acceptance Scenarios:

1. Given a baseline compare begins with full-content capture enabled, When evidence capture or resume processing is active, Then the shared contract exposes an operator-safe phase label rather than a generic composite or counted label.
2. Given compare execution moves from preparation to drift evaluation and persistence, When the job updates OperationRun.context, Then the run shows the current phase truthfully and remains explicitly non-counted.
3. Given the compare ends partially succeeded, blocked, or failed, When the run becomes terminal, Then the product drops active phase treatment and keeps terminal outcome plus artifact-truth semantics separate.

---

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

As a tenant operator, I need tenant review composition to summarize the child operation posture without pretending it is percentage-complete, so I can tell whether the review is aggregating healthy or problematic recent operations before I drill into details.

Why this priority: tenant.review.compose already has a canonical run type and repo-real aggregate operation truth through evidence-snapshot sections and review summary data, so it is a bounded composite target without inventing a child-run graph.

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

Acceptance Scenarios:

1. Given tenant review composition is queued from an evidence snapshot with recent operations summary counts, When the run starts, Then the shared contract exposes a composite summary that includes the aggregate operation count without rendering a progress bar.
2. Given the current evidence basis already indicates failed or partial recent operations, When the run is active, Then the composite summary includes an operator-safe child-state or next-step hint rather than generic Composite progress pending. copy.
3. Given the review composition finishes, When the run becomes terminal, Then terminal review outcome remains separate from composite progress and no active composite treatment remains.

---

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

As a maintainer, I need the package and UI standards to say exactly which runs can claim phase or composite progress and which cannot, so later work does not reopen fake percentages or broaden this slice implicitly.

Why this priority: the value of phase/composite v1 depends on keeping the counted, phased, and composite boundaries explicit after Specs 270 and 271.

Independent Test: review the updated package and UI standards together, then confirm that excluded candidate ideas remain named follow-ups instead of hidden implementation obligations.

Acceptance Scenarios:

1. Given a maintainer reads this package after implementation, When they review the standards and requirements, Then they can tell that processed and total remain the only determinate progress source and that phase/composite v1 is explicitly non-counted.
2. Given the original candidate wording mentioned provider health, support diagnostics, review packs, and evidence snapshots, When a maintainer reviews the final package, Then they can see why those areas stayed outside this slice under current repo truth.

Edge Cases

• Missing or malformed phase/composite metadata must degrade safely to the current generic phased, composite, or activity behavior rather than failing the host surface.
• Counted truth must remain subordinate to current precedence: when selected phase or composite metadata is present, the host must not fall back to a percentage just because summary_counts also contains numbers.
• Terminal runs may retain phase/composite context for diagnostics, but active progress treatment must stop as soon as the run is no longer currently active.
• tenant.review.compose with zero or missing operations summary data must degrade to generic activity or minimal composite disclosure rather than inventing a child-state summary.
• Provider health and support diagnostics remain out of scope unless a later feature establishes repo-real queued progress truth for those surfaces.

Requirements (mandatory)

Constitution alignment summary: This feature adds no new Graph contract, no new persisted entity, no new OperationRun lifecycle, and no new notification path. It only extends the existing shared progress contract and selected current job/service writers so non-counted runs can expose truthful phase or composite detail.

Functional Requirements

• FR-001: The implementation MUST reuse App\Support\OpsUx\OperationRunProgressContract, App\Support\OpsUx\OperationUxPresenter, App\Support\OpsUx\OperationStatusNormalizer, and App\Services\OperationRunService as the only non-counted progress contract and shared presentation path.
• FR-002: The in-scope phase run families for v1 are limited to baseline_capture and baseline_compare under current repo truth.
• FR-003: The in-scope composite run family for v1 is limited to tenant.review.compose under current repo truth.
• FR-004: Selected phase run families MUST persist canonical phase metadata inside the existing OperationRun.context payload with a stable machine-friendly phase key and an operator-safe label. Raw implementation internals MUST NOT be surfaced directly to the host surface.
• FR-005: The derived phase vocabulary for v1 is limited to operator-safe step families such as preparing, fetching, processing, persisting, and finalizing. Individual run families may skip phases that do not materially exist in their real workflow, but they MUST NOT invent additional percentage-bearing states.
• FR-006: Baseline capture MUST surface truthful phase progress for its current lifecycle boundaries, including current eligibility or preparation work, current subject or snapshot work, optional evidence capture when enabled, persistence, and finalization.
• FR-007: Baseline compare MUST surface truthful phase progress for its current lifecycle boundaries, including current coverage or preparation work, optional evidence capture or resume work, compare execution, persistence, and finalization.
• FR-008: tenant.review.compose MUST surface composite progress from repo-real aggregate truth already available from the current evidence basis or current review summary, including aggregate child count and any current failed or partial child summary or next-step hint that can be derived honestly.
• FR-009: Composite progress MUST remain explicitly non-counted. Aggregate child counts, failed-child counts, and partial-child counts MUST NOT become a back-door determinate progress bar unless processed and total separately satisfy the counted contract.
• FR-010: When selected phase/composite metadata is missing or malformed, the shared contract MUST degrade safely to the current generic phased, composite, or activity behavior instead of failing closed or inventing a new state.
• FR-011: Current precedence remains unchanged: active phased truth wins over composite, composite wins over counted, counted wins over generic activity, and terminal runs render no active progress treatment.
• FR-012: This slice MUST NOT add new summary_counts keys, new progress capabilities, a new dashboard card, a child-run graph, a workflow engine, or provider health/support-diagnostics progress behavior.
• FR-013: This slice MUST NOT reopen review-pack or evidence-snapshot progress semantics owned by Spec 271 unless current repo truth proves they still need non-counted treatment in a later follow-up spec.
• FR-014: The feature MUST update docs/ui/tenantpilot-enterprise-ui-standards.md so maintainers can see which current run families may claim phase/composite progress and which families remain activity-only, counted, or deferred.

Authorization and Safety Requirements

• AR-001: Existing tenant/admin-plane authorization remains unchanged: non-members and out-of-scope actors stay 404, while member-but-missing-capability actors stay 403.
• AR-002: No in-scope surface may reveal phase/composite progress for a run the current actor cannot already view through existing OperationRun policy checks.
• AR-003: No new destructive or mutating UI action is introduced. Existing baseline and tenant-review start surfaces keep their current authorization and confirmation rules.

Non-Functional Requirements

• NFR-001: Filament remains v5 on Livewire v4. No panel-provider registration change is allowed; apps/platform/bootstrap/providers.php remains authoritative.
• NFR-002: No new panel, globally searchable resource, or asset-registration strategy is allowed.
• NFR-003: No new parallel polling loop is allowed. Existing shell and monitoring pollers remain unchanged.
• NFR-004: Operator-safe phase/composite copy must remain concise, domain-safe, and compatible with the current shell density. It must not become a raw technical trace.
• NFR-005: The rollout must stay bounded enough that all changed behavior can be proved with focused Unit plus Feature commands rather than a new heavy-governance or browser family.

Deferred Follow-Ups / Explicit Non-Goals

• provider health or support-diagnostics progress rollout once those surfaces have repo-real queued phase/composite truth
• review-pack or evidence-snapshot non-counted progress treatment if Spec 271 later proves insufficient
• child-run graph persistence through child_run_ids or operation_run_ids
• 273 - Tenant Dashboard Active Operations Summary Card
• any full workflow engine, tray redesign, or AI-generated progress explanation layer

Key Entities

• Phase Progress Hint: the canonical operator-safe non-counted progress payload derived from OperationRun.context for selected phase-shaped run families.
• Composite Progress Summary: the canonical operator-safe aggregate child summary derived from existing current tenant-review operation truth without implying a percentage.
• Selected Phase Run Family: a currently repo-real run family, such as baseline capture or baseline compare, whose execution truth is best described by current phases rather than determinate counts.
• Selected Composite Run Family: a currently repo-real run family, such as tenant review compose, whose execution truth is best described by aggregate child state rather than determinate counts.

Success Criteria (mandatory)

• SC-001: Focused Unit coverage proves that selected phase and composite metadata produce operator-safe non-counted labels while current counted precedence still works only when truthful processed and total exist.
• SC-002: Focused shell Feature coverage proves that baseline capture and baseline compare show meaningful non-counted phase labels without rendering a progress bar in the covered active scenarios.
• SC-003: Focused Feature coverage proves that tenant.review.compose can expose a truthful composite summary from current aggregate operation truth without rendering a counted percentage.
• SC-004: Missing or malformed metadata degrades safely to current generic fallback behavior in 100% of covered scenarios.
• SC-005: The UI standards and Spec Kit artifacts document one canonical non-counted progress contract and explicitly keep provider health, support diagnostics, review-pack overlap, dashboard work, and workflow-engine ideas out of this slice.

Candidate Selection Rationale

• Selected candidate: OperationRun Phase & Composite Progress v1
• Source locations:
  • docs/product/spec-candidates.md
  • docs/product/roadmap.md
  • specs/270-operationrun-progress-contract/spec.md
  • specs/271-counted-progress-rollout/spec.md
  • apps/platform/app/Support/OpsUx/OperationRunProgressContract.php
  • apps/platform/app/Jobs/CaptureBaselineSnapshotJob.php
  • apps/platform/app/Jobs/CompareBaselineToTenantJob.php
  • apps/platform/app/Jobs/ComposeTenantReviewJob.php
  • apps/platform/app/Services/TenantReviews/TenantReviewService.php
• Why selected: the active automatic prep queue is intentionally empty, the user explicitly chose to promote 272, and the repo already contains the exact truth gap named by the candidate: real phase-shaped baseline context and real tenant-review aggregate operation counts currently terminate in generic fallback labels.
• Why this is the smallest viable implementation slice: v1 stays on the existing shared progress contract, selected current run families, and one standards update. It explicitly avoids a workflow engine, dashboard work, provider health/support rollout, and child-run persistence.
• Why close alternatives were deferred:
  • review-pack and evidence-snapshot progress remain owned by specs/271-counted-progress-rollout/ because those families already have deterministic counted work units under current repo truth
  • provider health and support diagnostics do not currently expose equivalent queued phase/composite progress truth through OperationRun
  • 273 - Tenant Dashboard Active Operations Summary Card remains a separate dashboard concern and should not be reopened here

Related-Spec Guardrail Check

• specs/270-operationrun-progress-contract/: immediate prerequisite. This package extends the shared contract rather than replacing it.
• specs/271-counted-progress-rollout/: adjacent counted-rollout package. This package must not reopen stable-unit counted families or change the existing precedence between counted and non-counted modes.
• specs/268-operationrun-activity-feedback/: existing shell feedback owner. This package may refine the meaning of active progress labels but must not reopen the shell's terminal outcome, dismissal, or browser-surface contract.
• specs/159-baseline-snapshot-truth/ and specs/164-run-detail-hardening/: inherited baseline truth only. This package may not blur artifact truth and execution truth or create a second run-detail semantics layer.

Assumptions

• Spec 270 remains the authoritative shared progress contract and keeps current precedence intact.
• Current baseline capture and compare jobs already own the real lifecycle boundaries that phase v1 should describe; the slice only makes those boundaries operator-safe and canonical.
• Current evidence snapshot operations summary is available early enough in tenant-review queueing to seed a bounded composite summary without inventing a child-run graph.

Risks

• Baseline phase labels can become noisy or technical if the implementation leaks raw internal step names instead of the bounded operator-safe vocabulary.
• tenant.review.compose may not always have enough early aggregate truth to justify a composite summary; that path must degrade safely instead of guessing.
• Touching both baseline jobs and tenant-review composition raises the risk of accidental scope widening into dashboard, report, or provider-specific progress work.

Open Questions

• None blocking safe implementation. If a selected run family cannot produce stable operator-safe non-counted detail without speculative copy, that family must drop back to current generic fallback behavior rather than widening the slice.