Monorepo Deep Review — 2026-06-25

Five-specialist deep review of the monorepo ongoing project, focused on the 61-commit delta since the 2026-05-14 review. Raw per-dimension reports: ./2026-06-25_review-reports/{security,architecture,design,testing,perf-a11y}.md.

Verdict

The 61-commit delta is healthy and the codebase is materially better than the 2026-05-14 baseline. Security is clean (0 critical/high; all 4 prior issues fixed). Architecture’s biggest prior finding — the phantom components package — is fully resolved; it’s now a real @monorepo/components workspace dep with clean one-way dependency flow and an honored Astro-first split. The brand-animation SSOT refactor is verified genuine. The mBR OKLCH token pipeline is now real.

But two issues need action now, both on the live, active-focus MBR site, both cheap:

1. WCAG-AA contrast regression on the new rates dashboard — one token breaks 63 elements (~0.25h fix).
2. test:py is red — an sd-api packaging bug masks 31 passing tests and breaks the test chain (~0.5h fix); lint + sd-app typecheck are also red.

Everything else is incomplete-migration debt and SSOT drift — real, but 0.25–3h cleanups, none release-blocking.

Severity rollup (across all 5 dimensions)

Dimension	Crit	High	Med	Low	Headline
Security	0	0	1	4	Clean; all prior findings fixed; bump deps
Architecture	0	3	5	4	Phantom-package fixed; naming + SSOT-drift debt
Design+brand	0	1	5	4	Token pipeline + brand SSOT real; focus pages outside the system
Testing+DX	1	—	—	—	test:py red (packaging); lint+typecheck red; rates.ts untested
Perf+a11y	1	4	—	3	Rates dashboard AA contrast (63 nodes); tooltips not kbd/touch

Prioritized action queue (severity × effort × leverage)

Do now — cheap, high-impact, on the live MBR site:

1. [crit, 0.25h] Fix rates dashboard contrast — bump --muted-foreground (sites/mbr/src/styles/themes/light.css:23, 28 6% 44% → ~38% L). Clears 60+ AA violations on the flagship page in one line. (perf-a11y C1)
2. [crit, 0.5h] Unbreak test:py — add [tool.uv.sources] sd-math = { path = "../sd-math", editable = true } to packages/sd-api/pyproject.toml, uv lock, commit. Reveals 31 already-passing sd-api tests and restores the test chain. (testing)
3. [high, 0.25h] Lint auto-fix — pnpm lint:fix clears 9/10 errors (no-var + dead var GAP=6) in sites/mbr/focus.astro + sites/sdc/focus.astro. (testing)

Next — accessibility + correctness: 4. [high, 1h] Tooltips keyboard/touch/ARIA — add Esc-to-dismiss (WCAG 1.4.13), aria-describedby trigger→bubble, and touch support to Tooltip.astro + the .ft injector; today definitions are unreachable on the phones the Focus PWAs install on. (perf-a11y I1, design low) 5. [high, 1h] SDC focus page latent bug — sites/sdc/.../load-focus-content.ts injects .ft spans but sites/sdc/src/pages/focus.astro has no .ft CSS/JS; the first SDC Glossary() term will render an unstyled, permanently-visible definition. (design high) 6. [high, 0.5h] Self-host fonts on Focus PWAs — both focus pages still load Inter from Google Fonts CDN render-blocking (mbr/sdc focus.astro:11-13); the main mBR site fix never propagated. (perf-a11y I2) 7. [important, 0.5h] Add scope to rates <th> — 56 headers across 8 tables + RateTable.astro:24-28 (WCAG 1.3.1). (perf-a11y I3) 8. [high, 0.5h] sd-app typecheck red — 61 pnpm check errors (missing paraglide message keys); CI has the step commented out, so sd-app type regressions are invisible. (testing)

Then — SSOT / architecture debt (prevents future silent breakage): 9. [high, 2h] Extract focus-content engine to the canonical library — ~250 lines (glossary parser, tooltip injector, frontmatter parser, FocusContent types) are copy-pasted between mbr/sdc load-focus-content.ts; drift already begun (sdc has FocusProminent, mbr doesn’t). Move generic engine to packages/components/src/lib/focus-content.ts. (architecture high) 10. [high, 1.5h] Finish the package-scope migration — @monorepo/* (components) vs @smart-debt/* (design-tokens, i18n, sd-app); pick one (recommend @monorepo/*), rename, fix stale CLAUDE.md:29 ref. (architecture high) 11. [high, 1h] Resolve orphaned @smart-debt/i18n — zero consumers; delete or wire sd-app’s Paraglide to consume it. (architecture high) 12. [med] Consolidate the 3 tooltip implementations (.tt canonical vs .ft duplicated + injector) → .tt; RateTable generalization for the 9 inline rates tables; gitignore committed rates.generated.json + document the cross-project rate-scanner SSOT; @components alias cleanup in ts. (architecture + design med)

Lower / latent: 13. mBR dark-mode tokens fail AA but dark mode is unreachable (no toggle) — fix anchors or remove until a toggle exists. Raw-HSL rates accents → token scale. archive/brand-assets-* + .obsidian/ tracked in repo → gitignore + git rm --cached. Dependency bump (Astro 5→6 line; high audit hits are dev-only/SSR-inapplicable since all sites are static). sd-app↔sd-api boundary still unwired (document before prod). rates.ts financial math has zero TS unit tests.

Per-dimension digest

• Security (security.md) — 0 crit/0 high/1 med/4 low. All 4 prior findings fixed (CORS allow-list, sd-app CSP, untracked .wrangler, mbr .env ignore). New set:html sinks (Tooltip, focus) safe — build-time KB content only; add trust-boundary comments. sd-api has no auth/rate-limit (fine while internal; add before public). PWA cache hardening verified correct. Package rename clean.
• Architecture (architecture.md) — 0/3/5/4. Phantom-package RESOLVED; clean dep direction; Astro/Alpine/Svelte split honored; brand SSOT real. Debt: half-finished @monorepo rename, orphaned i18n, focus-engine duplication, residual @components alias, committed artifacts. apps/CLAUDE.md confirmed correct (layer context, not stray).
• Design+brand (design.md) — 0/1/5/4. mBR token pipeline + animation SSOT verified real (prior #1 fixed). Focus pages live outside the design system (hardcoded #004425, 3 tooltip impls). SDC .ft latent bug (high). Dark-mode tokens fail AA but unreachable.
• Testing+DX (testing.md) — green: design-tokens 26/26, sd-app 3/3, sd-math 218/218; red: test:py (sd-api packaging — 31 tests pass when path supplied), lint (10 err), pnpm check (61 sd-app type err). test:all + pre-push fail at HEAD. Gap: sites/mbr/src/lib/rates.ts (14 fns incl. financial math) untested; new rates sections + Tooltip + bfcache handlers untested. (E2E not run this pass — time-boxed.)
• Perf+a11y (perf-a11y.md) — 1 crit/4 imp/3 min. Rates contrast (C1, one token, 63 nodes). Tooltips not kbd/touch (I1). Focus PWA Google Fonts (I2). 56 <th> missing scope (I3). Well-handled: viewport clamp (0 overflow @390px verified), reduced-motion gating, Cache-Control correctness, heading order.

Prior-review (2026-05-14) reconciliation

Most prior findings resolved. Security 4/4 fixed. Architecture: #1,#2,#4,#6,#10 resolved; #3 (sd-app↔sd-api) and #9 (archive/) still open; #7 (.obsidian/ tracked) partial. Design: mBR token bypass (top prior finding) fixed. Testing: CI case-mismatch fixed, Python wired into pipeline + pre-push. Deferred items added to repo UPGRADES.md this session.

Notes

• Review was read-only. The fixes below were applied in a same-day follow-up (Talbot: “proceed with fixes”).
• Raw specialist reports preserved as siblings in ./2026-06-25_review-reports/.

---

Fixes applied — 2026-06-25 (follow-up, committed monorepo@8b3ba22 + 128a52e)

The fast-follow tier (criticals + cheap mechanical wins). Each verified, not assumed.

• sd-api packaging (crit) — [tool.uv.sources] sd-math = {path, editable} + uv.lock. test:py green: sd-math 218 + sd-api 31 (was 0/broken).
• rates dashboard contrast (crit) — axe-verified to 0 color-contrast violations on /rates (was 63+; iterated 83→30→0). The specialist’s “one-line token” estimate undercounted: the failing text sits on warm-gray surfaces (not white), so it needed --muted-foreground 44%→32%, debt accent text/banner darkening, and the amber stat-chip — all in sites/mbr.
• lint 10→0 errors — lint:fix (no-var) + removed a dead const GAP in focus.astro:298. 7 pre-existing no-explicit-any warnings remain.
• a11y scope="col" on all rate-table headers (rates.astro + RateTable.astro).
• Verified green: lint 0 err, test:py 249, design-tokens 26/26, mbr astro check 0/0/0.

Surfaced during verification (pre-existing, NOT from these fixes): running the mbr axe E2E (the review pass skipped E2E) revealed 2 homepage issues — a button-name violation + one color-contrast node #a84859 @ 4.49. Logged in repo UPGRADES.md for a follow-up.

Deferred backlog (tooltip kbd/touch a11y, SDC .ft latent bug, self-host fonts, focus-engine extraction, package-scope migration, orphaned i18n, sd-app typecheck) → repo UPGRADES.md.

Lessons (candidates — surfaced for approval)

• Verify a11y contrast fixes with axe against the rendered background, not foreground-on-white math. The “one-line” token tweak cleared only ⅓ of nodes; real surfaces were warm-gray. [→ monorepo LESSONS.md]
• Run axe/E2E during review, not just unit+lint. The prior pass skipped E2E and missed homepage a11y violations that one axe run surfaced. [→ monorepo review process]
• Resume a dropped background agent via SendMessage (context intact) rather than restarting cold. One of 5 parallel specialists hit a mid-stream connection error; resuming recovered its 28 tool-uses of investigation. [→ global agent workflow]