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

# 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.