Ahmed Darrazi 53c4543cbd feat: add shared reason translation contract

2026-03-22 21:18:37 +01:00

12 KiB

Raw Blame History

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)

Complete Phase 1: Setup
Complete Phase 2: Foundational contract work
Complete Phase 3: User Story 1
Stop and validate with the blocked-run and provider-guidance tests
Demo the first translated operator-facing slice

Incremental Delivery

Foundation contract and guards
Operations and provider translation slice (US1)
Diagnostic-boundary and fallback hardening (US2)
Tenant-operability and adopted system-console governance adoption (US3)
Polish and validation

Parallel Team Strategy

With multiple developers:

One developer builds the shared translation foundation.
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.
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.

12 KiB Raw Blame History