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.

• T001 Create the shared implementation namespace under app/Support/ReasonTranslation/
• T002 [P] Create the shared unit-test namespace under tests/Unit/Support/ReasonTranslation/
• 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.

• T004 Implement the shared next-step value object in app/Support/ReasonTranslation/NextStepOption.php
• T005 Implement the shared resolution envelope in app/Support/ReasonTranslation/ReasonResolutionEnvelope.php
• T006 [P] Implement the shared translation contract interface in app/Support/ReasonTranslation/Contracts/TranslatesReasonCode.php
• T007 Implement the central reason translator registry in app/Support/ReasonTranslation/ReasonTranslator.php
• T008 Implement bounded fallback translation behavior in app/Support/ReasonTranslation/FallbackReasonTranslator.php
• T009 [P] Add unit coverage for the shared envelope and fallback contract in tests/Unit/Support/ReasonTranslation/ReasonResolutionEnvelopeTest.php
• 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

• T011 [P] [US1] Extend blocked run behavior coverage in tests/Feature/Monitoring/OperationRunBlockedSpec081Test.php
• T012 [P] [US1] Extend provider blocked guidance coverage in tests/Feature/ProviderConnections/ProviderOperationBlockedGuidanceSpec081Test.php
• T013 [P] [US1] Add notification translation coverage in tests/Feature/Notifications/OperationRunNotificationTest.php

Implementation for User Story 1

• T014 [US1] Implement execution-denial translation behavior in app/Support/Operations/ExecutionDenialReasonCode.php
• T015 [US1] Add provider reason translation support in app/Support/Providers/ProviderReasonTranslator.php
• T016 [US1] Refactor provider next-step resolution to consume the shared contract in app/Support/Providers/ProviderNextStepsRegistry.php
• T017 [US1] Update terminal notification rendering to use translated reason envelopes in app/Support/OpsUx/OperationUxPresenter.php
• T018 [US1] Update persisted operation notification payloads to use translated reason wording in app/Notifications/OperationRunCompleted.php
• 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

• T020 [P] [US2] Add raw-code diagnostic-retention coverage in tests/Unit/Support/ReasonTranslation/ExecutionDenialReasonTranslationTest.php
• T021 [P] [US2] Add provider translation and fallback coverage in tests/Unit/Support/ReasonTranslation/ProviderReasonTranslationTest.php
• 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

• T023 [US2] Add translator-backed diagnostic presentation helpers in app/Support/ReasonTranslation/ReasonPresenter.php
• T024 [US2] Reduce heuristic reason explanation usage in app/Support/OpsUx/RunFailureSanitizer.php
• T025 [US2] Update summary-line reason humanization for adopted operation surfaces in app/Support/OpsUx/SummaryCountsNormalizer.php
• 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

• T027 [P] [US3] Add tenant-operability translation coverage in tests/Unit/Support/ReasonTranslation/TenantOperabilityReasonTranslationTest.php
• T028 [P] [US3] Add RBAC translation coverage in tests/Unit/Support/ReasonTranslation/RbacReasonTranslationTest.php
• 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

• T030 [US3] Implement tenant-operability translation behavior in app/Support/Tenants/TenantOperabilityReasonCode.php
• T031 [US3] Implement RBAC reason translation behavior in app/Support/RbacReason.php
• T032 [US3] Update tenant-operability result rendering to consume the shared contract in app/Services/Tenants/TenantOperabilityService.php
• 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.

• T034 [P] Update the internal rollout and validation notes in specs/157-reason-code-translation/quickstart.md
• T035 Add implementation notes for future adopters in specs/157-reason-code-translation/research.md
• T036 Run focused first-slice validation from specs/157-reason-code-translation/quickstart.md
• 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

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