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.

```bash
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:

```bash
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.