# Tasks: Operator Reason Code Translation and Humanization Contract **Input**: Design documents from `/specs/157-reason-code-translation/` **Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/ **Tests**: Runtime behavior changes in this repo require Pest coverage. This feature changes operator-facing behavior on existing runtime surfaces, so tests are required for each implemented story. **Operations**: This feature does not introduce a new `OperationRun` type or change lifecycle ownership, but it does change adopted `OperationRun` notifications and run-detail explanation paths. Tasks must preserve the existing Ops-UX contract, keep `OperationRun.status` and `OperationRun.outcome` service-owned, and avoid adding new queued or running DB notifications. **RBAC**: This feature changes operator-facing explanation text on tenant/admin and platform/system surfaces. Tasks must preserve 404 versus 403 semantics, keep next-step guidance entitlement-safe, and include positive and negative authorization coverage. **Organization**: Tasks are grouped by user story so each story remains independently implementable and testable after the foundational phase. ## Phase 1: Setup (Shared Infrastructure) **Purpose**: Create the documentation-first implementation skeleton for the new shared reason-translation slice. - [X] T001 Create the shared implementation namespace under `app/Support/ReasonTranslation/` - [X] T002 [P] Create the shared unit-test namespace under `tests/Unit/Support/ReasonTranslation/` - [X] T003 [P] Create the feature-test namespace for translation safety under `tests/Feature/Authorization/` --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Build the common contract that every adopted reason family and surface will consume. **⚠️ CRITICAL**: No user story work can begin until this phase is complete. - [X] T004 Implement the shared next-step value object in `app/Support/ReasonTranslation/NextStepOption.php` - [X] T005 Implement the shared resolution envelope in `app/Support/ReasonTranslation/ReasonResolutionEnvelope.php` - [X] T006 [P] Implement the shared translation contract interface in `app/Support/ReasonTranslation/Contracts/TranslatesReasonCode.php` - [X] T007 Implement the central reason translator registry in `app/Support/ReasonTranslation/ReasonTranslator.php` - [X] T008 Implement bounded fallback translation behavior in `app/Support/ReasonTranslation/FallbackReasonTranslator.php` - [X] T009 [P] Add unit coverage for the shared envelope and fallback contract in `tests/Unit/Support/ReasonTranslation/ReasonResolutionEnvelopeTest.php` - [X] T010 [P] Add guard coverage for raw-code primary-message and canonical vocabulary regressions in `tests/Architecture/ReasonTranslationPrimarySurfaceGuardTest.php` **Checkpoint**: Shared reason-translation foundation is ready. User story implementation can now begin. --- ## Phase 3: User Story 1 - Understand Why Work Was Blocked Or Failed (Priority: P1) 🎯 MVP **Goal**: Operators see human-readable labels, explanations, and next steps instead of raw internal reason codes on the highest-leverage adopted surfaces. **Independent Test**: A blocked or failed run and a blocked provider flow can be opened independently, and both show translated labels plus actionable guidance without exposing raw internal codes as the primary message. ### Tests for User Story 1 - [X] T011 [P] [US1] Extend blocked run behavior coverage in `tests/Feature/Monitoring/OperationRunBlockedSpec081Test.php` - [X] T012 [P] [US1] Extend provider blocked guidance coverage in `tests/Feature/ProviderConnections/ProviderOperationBlockedGuidanceSpec081Test.php` - [X] T013 [P] [US1] Add notification translation coverage in `tests/Feature/Notifications/OperationRunNotificationTest.php` ### Implementation for User Story 1 - [X] T014 [US1] Implement execution-denial translation behavior in `app/Support/Operations/ExecutionDenialReasonCode.php` - [X] T015 [US1] Add provider reason translation support in `app/Support/Providers/ProviderReasonTranslator.php` - [X] T016 [US1] Refactor provider next-step resolution to consume the shared contract in `app/Support/Providers/ProviderNextStepsRegistry.php` - [X] T017 [US1] Update terminal notification rendering to use translated reason envelopes in `app/Support/OpsUx/OperationUxPresenter.php` - [X] T018 [US1] Update persisted operation notification payloads to use translated reason wording in `app/Notifications/OperationRunCompleted.php` - [X] T019 [US1] Update adopted run-detail reason presentation in `app/Filament/Resources/OperationRunResource.php` **Checkpoint**: User Story 1 is independently functional when operations and provider-blocked flows show translated labels and next-step guidance. --- ## Phase 4: User Story 2 - Preserve Backend Precision Without Polluting The Primary Surface (Priority: P1) **Goal**: Raw internal reason codes remain stable and available in diagnostics while primary adopted surfaces stay operator-first. **Independent Test**: Adopted operation and provider surfaces show translated messages by default, while the original internal reason code remains available in diagnostics and stored payloads. ### Tests for User Story 2 - [X] T020 [P] [US2] Add raw-code diagnostic-retention coverage in `tests/Unit/Support/ReasonTranslation/ExecutionDenialReasonTranslationTest.php` - [X] T021 [P] [US2] Add provider translation and fallback coverage in `tests/Unit/Support/ReasonTranslation/ProviderReasonTranslationTest.php` - [X] T022 [P] [US2] Add positive and negative authorization coverage for translated guidance, summaries, and next-step hints in `tests/Feature/Authorization/ReasonTranslationScopeSafetyTest.php` ### Implementation for User Story 2 - [X] T023 [US2] Add translator-backed diagnostic presentation helpers in `app/Support/ReasonTranslation/ReasonPresenter.php` - [X] T024 [US2] Reduce heuristic reason explanation usage in `app/Support/OpsUx/RunFailureSanitizer.php` - [X] T025 [US2] Update summary-line reason humanization for adopted operation surfaces in `app/Support/OpsUx/SummaryCountsNormalizer.php` - [X] T026 [US2] Preserve internal-code storage while adding translated envelopes in `app/Services/OperationRunService.php` **Checkpoint**: User Story 2 is independently functional when diagnostics still expose stable internal codes while primary adopted surfaces no longer rely on them as the headline message. --- ## Phase 5: User Story 3 - Reuse One Translation Contract Across Domains (Priority: P2) **Goal**: The same shared contract works beyond operations and providers by adopting tenant-operability governance and adopted system-console RBAC or onboarding surfaces with consistent actionability semantics. **Independent Test**: A tenant-operability surface and an adopted system-console RBAC or onboarding surface can be opened independently and both show the same label, explanation, and actionability shape as the operations and provider slices. ### Tests for User Story 3 - [X] T027 [P] [US3] Add tenant-operability translation coverage in `tests/Unit/Support/ReasonTranslation/TenantOperabilityReasonTranslationTest.php` - [X] T028 [P] [US3] Add RBAC translation coverage in `tests/Unit/Support/ReasonTranslation/RbacReasonTranslationTest.php` - [X] T029 [P] [US3] Add governance-surface feature coverage for tenant-operability and adopted system-console reason labels in `tests/Feature/ReasonTranslation/GovernanceReasonPresentationTest.php` ### Implementation for User Story 3 - [X] T030 [US3] Implement tenant-operability translation behavior in `app/Support/Tenants/TenantOperabilityReasonCode.php` - [X] T031 [US3] Implement RBAC reason translation behavior in `app/Support/RbacReason.php` - [X] T032 [US3] Update tenant-operability result rendering to consume the shared contract in `app/Services/Tenants/TenantOperabilityService.php` - [X] T033 [US3] Update adopted system-console RBAC health and onboarding surfaces to consume translated reasons in `app/Services/Intune/RbacHealthService.php` **Checkpoint**: All three user stories are independently functional once operations, providers, tenant-operability governance, and adopted system-console RBAC or onboarding surfaces share the same translation contract. --- ## Phase 6: Polish & Cross-Cutting Concerns **Purpose**: Complete consistency, documentation, and final validation across the first slice. - [X] T034 [P] Update the internal rollout and validation notes in `specs/157-reason-code-translation/quickstart.md` - [X] T035 Add implementation notes for future adopters in `specs/157-reason-code-translation/research.md` - [X] T036 Run focused first-slice validation from `specs/157-reason-code-translation/quickstart.md` - [X] T037 Run formatting for changed files with `vendor/bin/sail bin pint --dirty --format agent` --- ## Dependencies & Execution Order ### Phase Dependencies - **Setup (Phase 1)**: No dependencies; can start immediately. - **Foundational (Phase 2)**: Depends on Setup completion; blocks all user stories. - **User Story 1 (Phase 3)**: Depends on Foundational completion. - **User Story 2 (Phase 4)**: Depends on Foundational completion and should follow after enough of US1 exists to validate the operator-facing contract on real surfaces. - **User Story 3 (Phase 5)**: Depends on Foundational completion and should follow after the contract is proven on operations and provider flows. - **Polish (Phase 6)**: Depends on all implemented stories. ### User Story Dependencies - **US1 (P1)**: Can start immediately after the foundational contract is ready; it is the MVP slice. - **US2 (P1)**: Depends on the foundational contract and benefits from US1's adopted operation and provider surfaces. - **US3 (P2)**: Depends on the foundational contract and reuses the patterns proven in US1 and US2. ### Within Each User Story - Tests should be added or extended before implementation changes are finalized. - Translation artifacts before surface wiring. - Surface wiring before feature-level validation. - Story-specific regression coverage before moving to the next story. ### Parallel Opportunities - `T002` and `T003` can run in parallel. - `T004`, `T005`, and `T006` can partially overlap after the namespace exists. - `T009` and `T010` can run in parallel once the foundational classes exist. - Within US1, `T011`, `T012`, and `T013` can run in parallel. - Within US2, `T020`, `T021`, and `T022` can run in parallel. - Within US3, `T027`, `T028`, and `T029` can run in parallel. --- ## Parallel Example: User Story 1 ```bash # Parallelize the story-specific regression coverage: Task: "Extend blocked run behavior coverage in tests/Feature/Monitoring/OperationRunBlockedSpec081Test.php" Task: "Extend provider blocked guidance coverage in tests/Feature/ProviderConnections/ProviderOperationBlockedGuidanceSpec081Test.php" Task: "Add notification translation coverage in tests/Feature/Notifications/OperationRunNotificationTest.php" # After the tests exist, parallelize translation seams where they do not touch the same file: Task: "Implement execution-denial translation behavior in app/Support/Operations/ExecutionDenialReasonCode.php" Task: "Add provider reason translation support in app/Support/Providers/ProviderReasonTranslator.php" ``` --- ## Implementation Strategy ### MVP First (User Story 1 Only) 1. Complete Phase 1: Setup 2. Complete Phase 2: Foundational contract work 3. Complete Phase 3: User Story 1 4. **Stop and validate** with the blocked-run and provider-guidance tests 5. Demo the first translated operator-facing slice ### Incremental Delivery 1. Foundation contract and guards 2. Operations and provider translation slice (US1) 3. Diagnostic-boundary and fallback hardening (US2) 4. Tenant-operability and adopted system-console governance adoption (US3) 5. Polish and validation ### Parallel Team Strategy With multiple developers: 1. One developer builds the shared translation foundation. 2. Once the foundation is complete: - Developer A implements operations and notifications. - Developer B implements provider guidance and fallback coverage. - Developer C prepares tenant-operability and RBAC adoption tests. 3. Merge only after the guard and authorization-safe translation tests are green. --- ## Notes - `[P]` tasks touch different files and can be parallelized safely. - User story labels map directly to the stories in `spec.md`. - Keep the first slice bounded to operations, providers, tenant-operability governance, and adopted system-console RBAC or onboarding surfaces. - Do not expand the adoption set opportunistically into baseline, restore, onboarding raw-string reasons, or verification payload reasons during this tasks pass. - All PHP, Artisan, Composer, and test commands must run through Sail.