feat(modernization): full architecture blueprint with hardening follow-up

Implement phased modernization infrastructure for transitioning from
multi-page legacy routing to SPA portal-shell architecture, plus
post-delivery hardening fixes for policy loading, fallback consistency,
and governance drift detection.

Key changes:
- Add route contract enrichment with scope/visibility/compatibility policies
- Canonical 302 redirects from legacy direct-entry to /portal-shell/ routes
- Asset readiness enforcement and runtime fallback retirement for in-scope routes
- Shared feature-flag helpers (env > config > default) replacing duplicated _to_bool
- Defensive copy for lru_cached policy payloads preventing mutation corruption
- Unified retired-fallback response helper across app and blueprint routes
- Frontend/backend route-contract cross-validation in governance gates
- Shell CSS token fallback values for routes rendered outside shell scope
- Local-safe .env.example defaults with production recommendation comments
- Legacy contract fallback warning logging and single-hop redirect optimization

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.env.example

@@ -181,9 +181,41 @@ WORKER_RESTART_COOLDOWN=60
 # Watchdog loop check interval in seconds
 WATCHDOG_CHECK_INTERVAL=5
 
+# ============================================================
+# Portal Shell / Full Modernization Flags
+# ============================================================
+# Frontend build mode: auto | always | never
+# - auto: build only when dist is missing/stale
+# - always: force build on every start/restart
+# - never: skip build entirely
+FRONTEND_BUILD_MODE=always
+
+# Fail startup when frontend build fails (recommended in production)
+FRONTEND_BUILD_FAIL_ON_ERROR=true
+
+# Shell-first SPA navigation
+# Local default: false (avoid coupling first boot to shell-first cutover behavior)
+# Production recommendation: set true after shell cutover verification is complete
+PORTAL_SPA_ENABLED=false
+
+# Fail-fast readiness gate for in-scope dist assets
+# Local default: false (allow startup when dist artifacts are intentionally absent)
+# Production recommendation: set true to enforce release readiness at boot
+MODERNIZATION_ENFORCE_ASSET_READINESS=false
+
+# Retire in-scope runtime fallback behavior
+# Local default: false (retain compatibility fallback while developing)
+# Production recommendation: set true only after all in-scope dist assets are verified
+MODERNIZATION_RETIRE_IN_SCOPE_RUNTIME_FALLBACK=false
+
 # Runtime contract strict validation toggle
+# Local default: false (avoid strict conda/runtime checks on onboarding machines)
+# Production recommendation: set true to fail fast on contract drift
 RUNTIME_CONTRACT_ENFORCE=false
 
+# Health endpoint memo cache TTL in seconds
+HEALTH_MEMO_TTL_SECONDS=5
+
 # ============================================================
 # Runtime Resilience Diagnostics Thresholds
 # ============================================================
@@ -205,6 +237,3 @@ RESILIENCE_RESTART_CHURN_THRESHOLD=3
 # Example: https://example.com,https://app.example.com
 # Set to * for development (not recommended for production)
 CORS_ALLOWED_ORIGINS=
-
-# Health endpoint memo cache TTL in seconds
-HEALTH_MEMO_TTL_SECONDS=5