Files

egg 7cb0985b12 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>

2026-02-12 11:26:02 +08:00

2.5 KiB

Raw Blame History

asset-readiness-and-fallback-retirement Specification

Purpose

TBD - created by archiving change full-modernization-architecture-blueprint. Update Purpose after archive.

Requirements

Requirement: In-scope frontend assets SHALL be release-ready before deployment

In-scope routes SHALL rely on build/deploy readiness guarantees instead of runtime fallback behavior as the primary resilience mechanism.

Scenario: Build-readiness enforcement

WHEN release artifacts are prepared for deployment
THEN in-scope route assets SHALL be validated for presence and loadability
THEN missing required in-scope assets SHALL fail the release gate

Requirement: Runtime fallback retirement SHALL follow a governed phase policy

Runtime fallback behavior for in-scope modernization routes SHALL be retired under explicit governance milestones.

Scenario: Fallback retirement in phase scope

WHEN a route is marked in-scope for fallback retirement
THEN runtime fallback behavior for that route SHALL be removed or disabled by policy
THEN reliability for that route SHALL be guaranteed by release-time readiness gates

Requirement: Deferred routes SHALL keep existing fallback posture in this phase

Routes deferred from this modernization phase SHALL retain their existing fallback posture until handled by a follow-up change.

Scenario: Deferred fallback continuity

WHEN /tables, /excel-query, /query-tool, or /mid-section-defect is evaluated in this phase
THEN fallback retirement SHALL NOT be required for phase completion
THEN fallback retirement decisions for those routes SHALL be addressed in a follow-up modernization change

Requirement: Fallback-retirement failure response SHALL be consistent across route hosts

When in-scope runtime fallback retirement is enabled and route assets are unavailable, app-level and blueprint-level route handlers SHALL return a consistent retired-fallback response surface.

Scenario: App-level in-scope route enters retired fallback state

WHEN an in-scope app-level route cannot serve required dist assets and fallback retirement is enabled
THEN the route SHALL return the standardized retired-fallback response contract

Scenario: Blueprint-level in-scope route enters retired fallback state

WHEN an in-scope blueprint-level route cannot serve required dist assets and fallback retirement is enabled
THEN the route SHALL return the same standardized retired-fallback response contract used by app-level routes

2.5 KiB Raw Blame History