feat(ui): ship release promotions cutover

docs-archived/implplan/SPRINT_20260308_010_FE_release_promotions_cutover.md

@@ -0,0 +1,96 @@
+# Sprint 20260308_010_FE - Release Promotions Cutover
+
+## Topic & Scope
+- Restore the dormant promotions workflow as a first-class `Releases` capability instead of leaving it split between orphaned components, queue aliases, and approval-only entry points.
+- Make `/releases/promotions` the canonical owner route for promotion list, creation, and detail flows, with legacy `/release-control/promotions*` and `/releases/promotion-queue*` bookmarks preserved.
+- Wire a real release-context handoff from the active release workbench into the promotion wizard so operators can start a usable promotion request from a release they are reviewing.
+- Working directory: `src/Web/StellaOps.Web`.
+- Expected evidence: focused Angular route/component tests, Playwright route and workflow verification, updated UI docs, archived sprint.
+
+## Dependencies & Concurrency
+- Builds on the shipped IA and canonical route work already completed for `Releases`, Decisioning Studio, and contextual return-to flows.
+- Safe to implement in parallel with unrelated Router or live-search work as long as edits stay within `src/Web/StellaOps.Web` and scoped UI docs.
+
+## Documentation Prerequisites
+- `docs/modules/ui/README.md`
+- `docs/modules/ui/implementation_plan.md`
+- `docs/modules/ui/component-preservation-map/RESTORATION_PRIORITIES.md`
+- `docs/modules/ui/policy-decisioning-studio/README.md`
+
+## Delivery Tracker
+
+### FE-RP-001 - Canonical promotions owner route and alias cutover
+Status: DONE
+Dependency: none
+Owners: Developer / Implementer
+Task description:
+- Mount the existing promotions list, create, and detail workflow under the live `Releases` route tree as `/releases/promotions`.
+- Repair stale legacy redirects so `/release-control/promotions*` and `/releases/promotion-queue*` land on the canonical promotions subtree without dropping query state.
+- Surface the canonical path from live release navigation so the workflow is discoverable from the active shell.
+
+Completion criteria:
+- [x] `routes/releases.routes.ts` mounts a canonical promotions subtree.
+- [x] Legacy aliases redirect to the canonical subtree while preserving query params and fragments.
+- [x] Live shell navigation points at `/releases/promotions`, not the stale queue alias.
+
+### FE-RP-002 - Release-context promotion request handoff
+Status: DONE
+Dependency: FE-RP-001
+Owners: Developer / Implementer
+Task description:
+- Complete the promotion request handoff from the active release workbench so the operator can leave a release or run context and enter the promotion wizard with prefilled identity and a deterministic return path.
+- Merge the worthwhile behavior from the dropped promotion-request surface, especially decisioning preview handoff and contextual return-to routing, into the canonical promotion wizard instead of reviving a second product page.
+
+Completion criteria:
+- [x] Active release workbench actions navigate into the canonical promotion wizard with release context.
+- [x] The promotion wizard preloads release context and offers a Decisioning Studio deep link with a valid return-to contract.
+- [x] Operator back-navigation and post-submit behavior remain usable and deterministic.
+
+### FE-RP-003 - Verification coverage for route cutover and usable workflow
+Status: DONE
+Dependency: FE-RP-002
+Owners: Developer / Implementer, Test Automation, QA
+Task description:
+- Add focused Angular tests for the canonical route tree, release-context handoff, and promotion wizard state hydration.
+- Add Playwright coverage that proves legacy promotion aliases cut over correctly and that a real operator can reach the promotion wizard from the live Releases area.
+
+Completion criteria:
+- [x] Targeted Angular tests cover the canonical promotions route contract and release-context handoff.
+- [x] Playwright covers at least one live shell entry point plus one legacy alias.
+- [x] The scoped test suite passes deterministically.
+
+### FE-RP-004 - Docs sync, archive, and shipped-feature note
+Status: DONE
+Dependency: FE-RP-003
+Owners: Developer / Implementer, Documentation author
+Task description:
+- Document the canonical promotions owner route, alias policy, and release-context handoff in the UI module docs.
+- Record the tested behavior in a checked feature note, update the task board and implementation plan, then archive the sprint only after all delivery tasks are actually complete.
+
+Completion criteria:
+- [x] Module docs describe the canonical promotions workflow and alias contract.
+- [x] Checked-feature verification note records the actual commands and outcomes.
+- [x] Sprint is archived with all tasks marked `DONE`.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-08 | Sprint created and moved to DOING for canonical release promotions cutover. | Implementer |
+| 2026-03-08 | Mounted canonical `/releases/promotions` routes, repaired `/release-control/promotions*` and `/releases/promotion-queue*` aliases, and split shell surfacing into distinct `Approvals` and `Promotions` entries. | Implementer |
+| 2026-03-08 | Wired release-context handoff from the active release workbench into the canonical promotion wizard and merged decisioning-preview behavior from the dropped promotion-request surface. | Implementer |
+| 2026-03-08 | Verification passed: Angular targeted tests `2` files / `8` tests, Playwright `2` scenarios, and `npm run build` with existing bundle-budget warnings only. | Implementer |
+
+## Decisions & Risks
+- The sprint restores one operator workflow, not the full legacy release-orchestrator shell. If deeper release dashboards or environment editors prove valuable later, they need their own bounded sprint.
+- Promotion creation stays under `Releases`, while approval adjudication remains under `Releases > Approvals`; the UI must avoid collapsing those two surfaces back into one ambiguous queue.
+- Route alias handling must preserve query params and fragments so release-context and bookmark flows remain deterministic.
+- Browser verification initially exposed a live-shell compile blocker in `src/Web/StellaOps.Web/src/app/layout/app-sidebar/sidebar-preference.service.ts`; the sidebar preference contract was repaired as part of this sprint because the releases shell could not boot otherwise.
+- Verification commands:
+  - `npm run test -- --watch=false --include src/tests/releases/release-promotions-cutover.spec.ts --include src/tests/releases/release-detail.live-refresh.spec.ts`
+  - `npx playwright test --config playwright.config.ts tests/e2e/release-promotions-cutover.spec.ts --workers=1`
+  - `npm run build`
+
+## Next Checkpoints
+- Route and navigation cutover complete with local tests.
+- Release-context promotion handoff verified in browser.
+- Sprint archived and committed locally without unrelated files.