Throttle sidebar pending approvals badge refresh

docs/implplan/SPRINT_20260311_004_FE_sidebar_pending_approvals_badge_refresh_throttle.md

@@ -0,0 +1,51 @@
+# Sprint 20260311_004 - FE Sidebar Pending Approvals Badge Refresh Throttle
+
+## Topic & Scope
+- Eliminate transient live route failures caused by the shared sidebar polling pending approvals on every navigation.
+- Keep the approvals badge current where operators actually need freshness, without making unrelated pages fail under full-route Playwright sweeps.
+- Preserve stale badge state on transient backend failures instead of zeroing the shell and creating false-negative QA noise.
+- Working directory: `src/Web/StellaOps.Web/src/app/layout/app-sidebar`.
+- Allowed coordination edits: `src/Web/StellaOps.Web/src/app/layout/app-sidebar/app-sidebar.component.spec.ts`, `docs/implplan/SPRINT_20260311_004_FE_sidebar_pending_approvals_badge_refresh_throttle.md`.
+- Expected evidence: focused Angular sidebar coverage, rebuilt web bundle synced into `compose_console-dist`, and a live Playwright canonical route sweep returning `111/111`.
+
+## Dependencies & Concurrency
+- Depends on the live compose stack at `https://stella-ops.local`.
+- Safe parallelism: stay inside the shared shell badge behavior; do not broaden this slice into approval queue data contracts or unrelated integrations screens.
+
+## Documentation Prerequisites
+- `AGENTS.md`
+- `docs/qa/feature-checks/FLOW.md`
+- `docs/implplan/SPRINT_20260306_003_FE_playwright_setup_reset_iteration_loop.md`
+
+## Delivery Tracker
+
+### FE-SIDEBAR-APPROVALS-001 - Stop shared-shell badge churn from poisoning unrelated route verification
+Status: DONE
+Dependency: none
+Owners: QA, 3rd Line Support, Product Manager, Architect, Developer
+Task description:
+- A full authenticated Playwright canonical sweep regressed from `111/111` to `110/111`, but the reported failing page (`/ops/integrations/scm`) rendered correctly in isolation. Root-cause triage showed the shared sidebar was refetching pending approvals on every `NavigationEnd`, which turned the sweep into 100+ background calls to `/api/v2/releases/approvals?status=pending`.
+- The clean fix is to treat the pending approvals badge as a stale-while-revalidate shell affordance: load it on startup, throttle ordinary navigation refreshes, force refresh when the operator enters approvals surfaces, and preserve the last known badge count on transient errors.
+
+Completion criteria:
+- [x] The sidebar no longer refetches pending approvals on every unrelated navigation.
+- [x] Approvals surfaces still force a badge refresh.
+- [x] Transient approvals failures do not zero the badge after a successful load.
+- [x] Focused sidebar tests pass.
+- [x] The rebuilt live web returns `111/111` on `live-frontdoor-canonical-route-sweep.mjs`.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-11 | Sprint created after the live canonical route sweep dropped to `110/111` with `/ops/integrations/scm` falsely failing under a background `503` from `/api/v2/releases/approvals?status=pending`. Direct Playwright repro proved the SCM page itself was healthy and isolated the issue to shared-shell badge churn. | Developer |
+| 2026-03-11 | Added stale-while-revalidate throttling to the pending approvals badge, forced refreshes only for approvals surfaces, and preserved stale badge state on transient failures. Added focused router-backed sidebar coverage for unrelated vs approvals navigation. | Developer |
+| 2026-03-11 | `npx ng test --watch=false --progress=false --include=src/app/layout/app-sidebar/app-sidebar.component.spec.ts` passed `13/13`; `npm run build` passed; the rebuilt bundle was synced into `compose_console-dist`, `stellaops-router-gateway` was restarted, and `node ./scripts/live-frontdoor-canonical-route-sweep.mjs` returned `111/111` against `https://stella-ops.local`. | QA |
+
+## Decisions & Risks
+- Decision: the pending approvals badge is a shell hint, not a hard-real-time signal. It should be refreshed aggressively only when the operator is on approvals surfaces.
+- Decision: preserve the previous badge count after transient failures once a successful load has happened; zeroing the badge on a background hiccup misleads operators and creates false route failures.
+- Risk: the current deployment sync still uses a direct copy into `compose_console-dist`; keep that operational detail outside this sprint’s code scope.
+
+## Next Checkpoints
+- Commit the shared-shell badge repair.
+- Start the next deep page-action sweep now that the canonical route matrix is back to green.