TenantAtlas/.agent/skills/repo-contracts/operation-run-truth/SKILL.md

name	description
tenantpilot-operation-run-truth	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.