7cb0985b12
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>
4.9 KiB
4.9 KiB
1. Program Governance Baseline
- 1.1 Publish a frozen in-scope/out-of-scope route matrix for this phase (include
/admin/pages,/admin/performance; exclude/tables,/excel-query,/query-tool,/mid-section-defect) - 1.2 Add modernization governance documentation for phase completion criteria and legacy deprecation milestones
- 1.3 Create an exception registry format for temporary route/style exceptions (owner + milestone)
2. Shell Route Contract Expansion (In Scope)
- 2.1 Extend shell route contract metadata to cover all in-scope routes for this phase
- 2.2 Add governed navigation target definitions for
/admin/pagesand/admin/performance - 2.3 Ensure route visibility/access policy metadata is validated for in-scope routes
- 2.4 Add CI contract checks that fail on missing in-scope route metadata
3. Canonical Routing and Compatibility Policy
- 3.1 Define canonical shell entry behavior for in-scope report routes
- 3.2 Implement explicit compatibility policy for direct non-canonical route entry
- 3.3 Verify query-semantics compatibility for in-scope routes under canonical/compatibility paths
4. Admin Surface Modernization Integration
- 4.1 Integrate
/admin/pagesand/admin/performanceinto shell-governed navigation flow - 4.2 Preserve backend auth/session authority while modernizing shell navigation governance
- 4.3 Add admin visibility/access behavior tests for shell-governed admin targets
5. Style Isolation and Token Enforcement
- 5.1 Inventory in-scope route styles for page-global selector usage (
:root,body) and classify required refactors - 5.2 Refactor in-scope route-local styles to scoped/container-based ownership
- 5.3 Move shared visual semantics to token-backed Tailwind/shared layers
- 5.4 Add style-governance lint/check rules for in-scope routes and exception handling
6. Page-Content Modernization Safety (Charts/Filters/Interactions)
- 6.1 Define route-level content contracts for in-scope pages (filter input semantics, query payload structure, chart data shape, state transitions)
- 6.2 Build golden fixtures and parity assertions for chart/filter critical states before cutover
- 6.3 Add interaction parity checks for critical flows (filter apply/reset, chart drill/selection, empty/error states)
- 6.4 Add route-scoped feature flags and immediate rollback controls for content cutover
- 6.5 Define a per-route manual acceptance checklist for chart/filter/page-content migration
- 6.6 Require manual acceptance sign-off for each route before moving to the next route
- 6.7 Require parity pass + manual acceptance sign-off before legacy content path retirement
- 6.8 Create route-level known-bug baselines for migrated scope before implementation begins
- 6.9 Add mandatory "BUG revalidation during migration" checklist items to manual acceptance for each route
- 6.10 Block route sign-off and legacy retirement if known legacy bugs are reproduced in the modernized route
7. Asset Readiness and Fallback Retirement (In Scope)
- 7.1 Define required in-scope asset readiness checks for build/release pipeline
- 7.2 Enforce fail-fast release behavior when required in-scope assets are missing
- 7.3 Retire runtime fallback posture for in-scope routes per governance milestones
- 7.4 Keep deferred route fallback posture unchanged in this phase and document follow-up linkage
8. Frontend Quality Gate Modernization
- 8.1 Define mandatory functional parity checks for in-scope modernization routes
- 8.2 Define visual regression checkpoints for critical states in in-scope routes
- 8.3 Define accessibility checks (keyboard flows, aria semantics, reduced-motion behavior)
- 8.4 Define performance budgets and measurement points for shell/route behavior
- 8.5 Configure gate severity policy (warn mode rollout -> blocking mode promotion)
9. Test and CI Wiring
- 9.1 Extend frontend test suite for new route governance/admin scenarios
- 9.2 Extend backend/integration tests for canonical routing and compatibility behavior
- 9.3 Add CI jobs for route-governance completeness, quality-gate execution, and asset readiness checks
- 9.4 Ensure deferred routes are excluded from this phase blocking criteria
10. Migration and Rollback Runbook
- 10.1 Update runbook with phased rollout steps and hold points for modernization gates
- 10.2 Document rollback controls for gate false positives and route-level reversion
- 10.3 Add operational observability checkpoints for route governance and gate outcomes
11. Follow-up Change Preparation (Deferred Routes)
- 11.1 Create a linked follow-up modernization change for
/tables,/excel-query,/query-tool,/mid-section-defect - 11.2 Transfer deferred-route requirements and acceptance criteria into the follow-up change
- 11.3 Record explicit handoff from this phase to the deferred-route phase