---
name: tenantpilot-operation-run-truth
description: Hard-gate OperationRun lifecycle, execution truth, summary counts, reconciliation, and customer-proof boundaries.
---

## Purpose

Use this skill to keep `OperationRun` as execution truth for queued/remote/long-running work without turning it into customer-safe proof or duplicate domain truth.

## Activate When

- Creating, queuing, deduplicating, resuming, retrying, reconciling, completing, blocking, deep-linking, or displaying `OperationRun` records.
- Adding jobs, provider/Graph work, restore/backup/sync/report/evidence operations, terminal notifications, or run actionability.
- Touching `OperationRunService`, operation summary counts, queued execution gates, run notifications, or operation links.

## Do Not Activate When

- The change is DB-only and not security-relevant, remote, queued, long-running, observable, or user-facing.
- The task only reads OperationRun history as context and does not change behavior or claims.

## Maturity

L4 hard gate.

## Gate Type

hard-gate.

## Source Evidence

- `.specify/memory/constitution.md`
- `docs/architecture-guidelines.md`
- `docs/performance-guidelines.md`
- `docs/testing-guidelines.md`
- `specs/415-generic-content-backed-capture/implementation-report.md`
- `apps/platform/app/Services/OperationRunService.php`
- `apps/platform/app/Support/OpsUx/OperationSummaryKeys.php`
- `apps/platform/app/Notifications/OperationRunCompleted.php`
- `apps/platform/app/Services/Operations/OperationRunOperatorActionService.php`
- `apps/platform/tests/Feature/OperationRunServiceTest.php`
- `apps/platform/tests/Feature/OpsUx/OperationRunSummaryCountsIncrementTest.php`
- `apps/platform/tests/Feature/Operations/Spec367OperationRunActionabilityResolverTest.php`

## External Anchors

Not applicable.

## Required Repo Context

- Operation type and catalog entry.
- Run ownership fields: workspace, managed environment, target scope, initiator.
- Start surface and queued job path.
- `OperationRunService` status/outcome transition methods.
- Summary count key/value handling.
- Notification and audit behavior.
- Customer-facing proof/evidence surface, if any.

## Execution Checklist

- Use `OperationRunService` for status/outcome transitions.
- Keep direct status/outcome writes out of feature code except approved context-only updates.
- Route remote/provider work through jobs/services, not UI render.
- Keep summary counts flat, numeric, and limited to `OperationSummaryKeys::all()`.
- Use central OperationRun start UX/link/notification patterns when UI is involved.
- Keep queued DB notifications explicit opt-in.
- Keep raw payloads, secrets, credentials, and provider error bodies out of OperationRun context/messages.
- Separate OperationRun execution truth from evidence payload truth and customer-safe proof.
- Add tests for lifecycle, idempotency, stale active runs, summary counts, and authorization where runtime behavior changes.

## Stop Conditions

- Direct OperationRun status/outcome writes bypass service-owned lifecycle.
- Remote provider or Graph calls happen during render.
- A feature creates duplicate local run truth or competing status fields.
- OperationRun is presented as default customer proof.
- Stale active runs have no reconciliation or blocked-state path.
- Summary counts include non-numeric values or unregistered keys.
- Raw payloads, secrets, tokens, or sensitive provider details enter run context/messages/notifications.

## Required Evidence After Use

- Operation type and lifecycle path.
- Service-owned transition proof.
- Summary key proof.
- Authorization and scope proof for run access/actionability.
- Customer-proof boundary: evidence/report claims do not rely on OperationRun alone.
- Tests or reasoned N/A for non-runtime/docs-only work.

## Common Failure Modes

- Treating a queued run as proof that evidence is current or customer-safe.
- Local feature code composing its own run notifications and links.
- Writing stale/failed reconciliation as UI-only labels.
- Persisting provider payload snippets in run messages for debugging.
- Creating run records without enough target scope to reauthorize the job.

## Quarantined Rules

Full Spec 416 quarantine list applies. Especially quarantined here: OperationRun as default customer proof; fallback-to-latest evidence; raw provider/evidence payload default display; historical audits as current truth.

## Review / Expiry

Review whenever OperationRun lifecycle, start UX, reconciliation, summary counts, notification policy, or customer proof semantics change. No planned expiry.