Repair router frontdoor route boundaries and service prefixes

docs/implplan/SPRINT_20260310_020_Router_frontdoor_route_boundary_and_service_prefix_repair.md

@@ -0,0 +1,77 @@
+# Sprint 20260310-020 - Router Frontdoor Route Boundary And Service Prefix Repair
+
+## Topic & Scope
+- Repair frontdoor route precedence defects that only appear on the real scratch stack after router-gateway reloads and rebuilt web assets.
+- Keep first-party Stella APIs on router transport while correcting the route table so static chunks, platform-owned APIs, and shell compatibility prefixes dispatch to the intended target.
+- Working directory: `src/Router`.
+- Allowed coordination edits: `devops/compose/router-gateway-local.json`, `docs/modules/router/architecture.md`, `devops/compose/README.md`, `src/Router/StellaOps.Gateway.WebService/TASKS.md`, `docs/implplan/SPRINT_20260310_020_Router_frontdoor_route_boundary_and_service_prefix_repair.md`.
+- Expected evidence: focused router tests, live gateway probes on `https://stella-ops.local`, and a Playwright canonical route sweep after gateway restart.
+
+## Dependencies & Concurrency
+- Depends on `SPRINT_20260310_001_Router_frontdoor_required_service_readiness.md` for truthful frontdoor readiness and restart convergence.
+- Safe parallelism: stay in `src/Router` plus the listed compose/docs files; leave frontend route repairs for separate FE iterations once the frontdoor contract is verified.
+
+## Documentation Prerequisites
+- `AGENTS.md`
+- `src/Router/AGENTS.md`
+- `src/Router/StellaOps.Gateway.WebService/AGENTS.md`
+- `src/Router/__Tests/StellaOps.Gateway.WebService.Tests/AGENTS.md`
+- `docs/modules/router/architecture.md`
+
+## Delivery Tracker
+
+### ROUTER-BOUNDARY-001 - Restore route precedence for platform-owned and static-boundary paths
+Status: DONE
+Dependency: none
+Owners: Developer, QA
+Task description:
+- Tighten the root `/policy` regex so it only owns the actual route segment and no longer steals Angular static chunks.
+- Restore explicit platform ownership for `/api/v1/aoc/*` and `/api/v1/administration/*` ahead of the generic `/api/v1/{service}` matcher so those requests do not dispatch to synthetic microservice names.
+
+Completion criteria:
+- [x] `/policy-decisioning.routes-*.js` stays on the static route.
+- [x] `/api/v1/aoc/*` and `/api/v1/administration/*` resolve to `platform`.
+- [x] Focused route-table tests prove precedence against generic catch-alls.
+
+### ROUTER-BOUNDARY-002 - Strip browser compatibility prefixes before microservice dispatch
+Status: DONE
+Dependency: ROUTER-BOUNDARY-001
+Owners: Developer, QA
+Task description:
+- Preserve the shell-facing `/doctor/*` and `/scheduler/*` entrypoints while translating them to the canonical backend paths those services actually expose.
+- Verify the dispatch middleware forwards `/doctor/api/v1/doctor/*` and `/scheduler/api/v1/scheduler/*` as `/api/v1/doctor/*` and `/api/v1/scheduler/*` to the correct microservice.
+
+Completion criteria:
+- [x] Route config translates `/doctor/*` and `/scheduler/*` without duplicating the service-root prefix.
+- [x] Middleware tests assert the translated request path seen by the microservice pipeline.
+- [x] Live frontdoor probes return authenticated backend responses instead of SPA fallback or `404`.
+
+### ROUTER-BOUNDARY-003 - Reverify the live scratch frontdoor with Playwright
+Status: DONE
+Dependency: ROUTER-BOUNDARY-002
+Owners: QA
+Task description:
+- Restart the live `router-gateway`, probe the corrected routes directly, and rerun the Playwright canonical sweep against the local scratch stack.
+- Capture the remaining failures explicitly so the next iteration starts from UI defects only, not route ownership ambiguity.
+
+Completion criteria:
+- [x] `router-gateway` restarted on the local compose stack after config changes.
+- [x] Live probes for `/doctor`, `/scheduler`, `/api/v1/aoc`, and `/api/v1/administration` return backend-authenticated responses.
+- [x] Playwright canonical sweep records the post-fix result set and isolates any remaining failures.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-10 | Sprint created after live scratch verification showed three route-boundary defects: the `/policy` root regex captured Angular chunks, the generic `/api/v1/{service}` matcher stole platform-owned AOC and administration APIs, and shell compatibility prefixes for doctor/scheduler forwarded the wrong backend path. | Developer |
+| 2026-03-10 | Added explicit platform mappings, segment-bound `/policy` matching, and prefix-stripping `/doctor`/`/scheduler` routes in both gateway configs. Focused router tests passed `269/269`. | Developer |
+| 2026-03-10 | Restarted `router-gateway`, re-probed the repaired live frontdoor, and reran the Playwright canonical route sweep. Result: `109/111` passed, with only `/ops/operations/scheduler` and `/ops/operations/doctor` still failing due to frontend routing fallback rather than router dispatch. | QA |
+
+## Decisions & Risks
+- Decision: reverse proxy remains reserved for external/bootstrap surfaces only; first-party Stella API defects must be solved by correcting router route ownership, not by bypassing router transport.
+- Decision: root-prefix regex routes must use segment boundaries whenever SPA/static assets can share the same textual prefix.
+- Decision: browser-facing compatibility prefixes are acceptable when the route table strips them before dispatch so backend services keep their canonical API roots.
+- Risk: the remaining `109/111` Playwright result still includes two frontend route failures under `/ops/operations/*`. Mitigation: treat those as a separate FE iteration and keep this router commit scoped to dispatch correctness.
+
+## Next Checkpoints
+- 2026-03-10: Commit the router/frontdoor boundary repair as a standalone iteration.
+- 2026-03-10: Triage `/ops/operations/scheduler` and `/ops/operations/doctor` in the web route layer using the clean router baseline.