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>
3.6 KiB
3.6 KiB
ADDED Requirements
Requirement: In-scope page-content modernization SHALL be contract-first
Before chart/filter/page interaction refactors are cut over, each in-scope route SHALL define a contract baseline that captures data and interaction semantics.
Scenario: Route contract baseline defined
- WHEN an in-scope route is selected for chart/filter modernization
- THEN the route SHALL define filter input semantics, query payload expectations, and chart data-shape contracts
- THEN the route SHALL define critical state expectations for loading, empty, error, and success interactions
Requirement: Cutover SHALL require parity evidence against baseline behavior
In-scope chart/filter modernization cutover SHALL require parity evidence against baseline fixtures and critical interaction flows.
Scenario: Parity gate before default switch
- WHEN a route is proposed for defaulting to a modernized chart/filter implementation
- THEN golden fixture parity checks SHALL pass for defined critical states
- THEN interaction parity checks SHALL pass for filter apply/reset and chart selection/drill behaviors
Requirement: Route-level content cutover SHALL be reversible
Modernized chart/filter content rollouts SHALL use reversible controls that allow immediate rollback without reverting unrelated shell architecture work.
Scenario: Controlled rollout and rollback
- WHEN a modernized route is enabled for users
- THEN the route SHALL be controlled by route-scoped feature flag or equivalent switch
- THEN rollback procedure SHALL be documented and executable within one release cycle
Requirement: Page-content modernization progression SHALL require manual route acceptance
In-scope chart/filter/page-content migration SHALL progress one route at a time with explicit manual acceptance records.
Scenario: Route-by-route manual acceptance gate
- WHEN an in-scope route completes modernization implementation and parity checks
- THEN that route SHALL be manually accepted using a defined checklist covering filter flows, chart interactions, empty/error behavior, and visual correctness
- THEN the next route SHALL NOT begin cutover until manual acceptance for the current route is signed off
Requirement: Known legacy bugs in migrated scope SHALL NOT be carried into modernized routes
Modernized route acceptance SHALL include explicit revalidation of known legacy defects in migrated scope, and reproduced defects SHALL block sign-off.
Scenario: Route-level legacy bug baseline and replay
- WHEN an in-scope route enters chart/filter/page-content modernization
- THEN a route-level known-bug baseline (within migrated scope) SHALL be recorded before implementation
- THEN manual acceptance SHALL replay those known-bug checks on the modernized route
Scenario: Legacy bug carry-over is blocked
- WHEN manual acceptance finds that a known legacy bug is still reproducible in the modernized route
- THEN route sign-off SHALL fail
- THEN route cutover completion and legacy code retirement SHALL be blocked until the bug is fixed
Requirement: Legacy content path retirement SHALL require parity and manual acceptance
Legacy chart/filter implementations SHALL be removed only after parity checks and manual acceptance criteria are satisfied.
Scenario: Legacy removal approval
- WHEN legacy chart/filter code is planned for removal on an in-scope route
- THEN the route SHALL provide parity pass evidence and manual acceptance sign-off records
- THEN unresolved parity failures or manual acceptance defects SHALL block legacy removal