111 lines
5.7 KiB
Markdown
111 lines
5.7 KiB
Markdown
# 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.
|