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>
2.8 KiB
2.8 KiB
Context
This follow-up change consumes the explicit handoff from full-modernization-architecture-blueprint phase 1. Deferred routes were intentionally excluded to control blast radius, but they now represent the remaining architecture gap.
Current deferred-route risks:
- Shell contract incompleteness and mixed navigation behavior.
- Legacy runtime fallback dependency.
- Content modernization parity not yet formalized.
- Potential legacy bug carry-over if migration is done implementation-first.
Goals / Non-Goals
Goals
- Complete shell-governed route coverage for deferred routes.
- Adopt canonical shell routing and explicit compatibility policy.
- Execute contract-first content modernization with parity and rollback controls.
- Enforce mandatory manual acceptance and BUG revalidation before sign-off.
Non-Goals
- Reworking already in-scope phase-1 routes again.
- Changing backend business data semantics beyond compatibility safeguards.
- Bundling unrelated admin/report features into this follow-up.
Decisions
D1. Deferred routes are promoted to in-scope as a single governed wave
/tables,/excel-query,/query-tool,/mid-section-defectare all in-scope for this change.
D2. Canonical policy matches phase 1
- Canonical shell path is
/portal-shell/<route>. - Direct entry behavior remains explicit compatibility (redirect or compatibility render) with preserved query semantics.
D3. Content migration remains route-by-route, not big-bang
- Only one deferred route can be in cutover state at a time.
- Next route is blocked until current route has parity pass + manual sign-off + bug replay pass.
D4. Legacy bug carry-over prevention is a hard gate
- Known bug baseline must be recorded before implementation.
- Reproduced known bugs on modernized path block sign-off and legacy retirement.
Risks / Trade-offs
- Deferred routes may have heavier legacy coupling than phase-1 routes.
- Route-by-route cutover increases total elapsed time but reduces rollback blast radius.
- Asset-readiness enforcement can block releases earlier; rollout plan must phase warn->block.
Migration Plan
- Freeze deferred-route scope matrix for this follow-up change.
- Extend shell route contracts and metadata coverage to full completeness.
- Define route content contracts + golden fixtures + interaction parity checks.
- Execute per-route migration with feature-flagged cutover and manual acceptance.
- Retire deferred-route runtime fallback posture after acceptance and readiness gates pass.
- Update runbook/rollback docs and close handoff linkage.
Rollback Strategy
- Keep route-scoped cutover flags for immediate per-route rollback.
- Allow temporary gate downgrade (
block->warn) only with explicit waiver and expiry. - Preserve route-level evidence (parity, manual sign-off, bug replay) to support rollback decisions.