ahmido
332f6325cb
Automated PR provided by Codex via Gitea API. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #483
104 lines
4.5 KiB
Markdown
104 lines
4.5 KiB
Markdown
---
|
|
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.
|