TenantAtlas/specs/157-reason-code-translation/quickstart.md

Quickstart: Operator Reason Code Translation and Humanization Contract

Goal

Validate the shared reason translation contract on a bounded first slice without breaking RBAC, existing Ops-UX lifecycle rules, or diagnostic precision.

First-Slice Scope

The recommended first slice covers:

1. Operations run detail and terminal notifications
2. Provider blocked-state guidance and next-step rendering
3. Tenant-operability governance reason presentation
4. Adopted system-console RBAC or onboarding health reason presentation
5. Shared fallback behavior for untranslated adopted reasons

Implementation Order

1. Define the shared resolution envelope and domain-facing translation contract
2. Adopt enum-backed reason families first
3. Extend provider next-step and provider blocking flows to the same contract shape
4. Wire OperationUxPresenter and OperationRunCompleted to translated envelopes
5. Add fallback, vocabulary, and non-leakage guard coverage before expanding beyond the first slice

Focused Validation Commands

Run all commands through Sail.

vendor/bin/sail artisan test --compact \
    tests/Unit/OpsUx/RunFailureSanitizerTest.php \
    tests/Feature/Monitoring/OperationRunBlockedSpec081Test.php \
    tests/Feature/ProviderConnections/ProviderOperationBlockedGuidanceSpec081Test.php

Expected additions or extensions during the slice:

vendor/bin/sail artisan test --compact \
    tests/Architecture/ReasonTranslationPrimarySurfaceGuardTest.php \
    tests/Unit/Support/ReasonTranslation/ReasonResolutionEnvelopeTest.php \
    tests/Unit/Support/ReasonTranslation/ExecutionDenialReasonTranslationTest.php \
    tests/Unit/Support/ReasonTranslation/TenantOperabilityReasonTranslationTest.php \
    tests/Unit/Support/ReasonTranslation/RbacReasonTranslationTest.php \
    tests/Unit/Support/ReasonTranslation/ProviderReasonTranslationTest.php \
    tests/Feature/Notifications/OperationRunNotificationTest.php \
    tests/Feature/Operations/OperationRunBlockedExecutionPresentationTest.php \
    tests/Feature/Operations/TenantlessOperationRunViewerTest.php \
    tests/Feature/ReasonTranslation/GovernanceReasonPresentationTest.php \
    tests/Feature/Authorization/ReasonTranslationScopeSafetyTest.php

vendor/bin/sail bin pint --dirty --format agent

First-Slice Implementation Notes

• Operations notifications and the canonical run-detail surface now resolve reason codes through a shared envelope before rendering the primary message.
• Provider blocked-start notifications now render translated labels, explanations, and next-step guidance instead of raw provider codes.
• RBAC governance details now render a translated reason label and explanation while keeping the diagnostic reason code visible in secondary detail.
• OperationRun.context.reason_translation stores the translated envelope for adopted run surfaces, while reason_code remains unchanged for diagnostics and audit use cases.

Manual Smoke Checklist

/admin/operations and run detail

• Blocked runs show a translated label and concise explanation.
• The primary surface does not show the raw internal reason code as the headline message.
• If action is required, the surface shows a next step or explicit remediation guidance.
• Raw reason codes remain available only in diagnostics or secondary detail.

Provider connection and provider-blocked flows

• Provider blocking states show translated labels instead of bare provider reason codes.
• The first next-step hint remains actionable and entitlement-safe.
• Unknown provider failures still render an understandable fallback label.

Tenant or RBAC governance slice

• Raw enum values such as missing_capability or manual_assignment_required do not appear as the primary operator label.
• The operator can tell whether the state is transient, prerequisite-bound, or requires manual intervention.

Manual Review Protocol For SC-157-004

Review exactly 12 curated examples after the first slice is implemented:

1. 4 operations examples covering blocked, denied, retryable, and non-actionable outcomes
2. 4 provider guidance examples covering prerequisite missing, permission required, connectivity, and fallback behavior
3. 2 tenant-operability examples covering readiness degradation and manual intervention
4. 2 adopted system-console examples covering RBAC health or onboarding prerequisite reasons

For each example, record pass or fail for these two checks:

1. Cause clarity: the default-visible label and explanation make the underlying issue understandable without exposing the raw internal code as the headline.
2. Next-step clarity: the default-visible message either provides an explicit next step or clearly states that no operator action is required.

SC-157-004 passes when at least 11 of the 12 curated examples pass both checks.

Validation Checklist

• Adopted primary surfaces never use a raw internal reason code as the default-visible message.
• Diagnostics still preserve the original internal reason code.
• Actionable reasons include guidance or an explicit next step.
• Non-actionable reasons explicitly communicate that no action is required.
• Fallback labels are sentence-case, are not identical to the raw internal code, and include either an explicit next step or an explicit no-action-needed signal.
• Canonical and tenant-context surfaces do not reveal unauthorized remediation paths or protected state.
• RunFailureSanitizer remains bounded to sanitization and fallback behavior on adopted surfaces.

Rollout Note

Do not migrate every reason-bearing family opportunistically. Keep the slice bounded to operations, provider guidance, tenant-operability governance, and adopted system-console RBAC or onboarding surfaces so that translation regressions remain attributable and reversible.