chore: reinitialize project with vite architecture

openspec/specs/cache-observability-hardening/spec.md

@@ -0,0 +1,38 @@
+## Purpose
+Define stable requirements for cache-observability-hardening.
+## Requirements
+### Requirement: Layered Cache SHALL Expose Operational State
+The route cache implementation SHALL expose layered cache operational state, including mode, freshness, and degradation status.
+
+#### Scenario: Redis unavailable degradation state
+- **WHEN** Redis is unavailable
+- **THEN** health endpoints MUST indicate degraded cache mode while keeping L1 memory cache active
+
+### Requirement: Cache Telemetry MUST be Queryable for Operations
+The system MUST provide cache telemetry suitable for operations diagnostics.
+
+#### Scenario: Telemetry inspection
+- **WHEN** operators request deep health status
+- **THEN** cache-related metrics/state SHALL be present and interpretable for troubleshooting
+
+### Requirement: Health Endpoints SHALL Expose Pool Saturation and Degradation Reason Codes
+Operational health endpoints MUST report connection pool saturation indicators and explicit degradation reason codes.
+
+#### Scenario: Pool saturation observed
+- **WHEN** checked-out connections and overflow approach configured limits
+- **THEN** deep health output MUST expose saturation metrics and degraded reason classification
+
+### Requirement: Degraded Responses MUST Be Correlatable Across API and Health Telemetry
+Error responses for degraded states SHALL include stable codes that can be mapped to health telemetry and operational dashboards.
+
+#### Scenario: Degraded API response correlation
+- **WHEN** an API request fails due to circuit-open or pool-exhausted conditions
+- **THEN** operators MUST be able to match the response code to current health telemetry state
+
+### Requirement: Operational Alert Thresholds SHALL Be Explicitly Defined
+The system MUST define alert thresholds for sustained degraded state, repeated worker recovery, and abnormal retry pressure.
+
+#### Scenario: Sustained degradation threshold exceeded
+- **WHEN** degraded status persists beyond configured duration
+- **THEN** the monitoring contract MUST classify the service as alert-worthy with actionable context
+

openspec/specs/conda-systemd-runtime-alignment/spec.md

@@ -0,0 +1,26 @@
+# conda-systemd-runtime-alignment Specification
+
+## Purpose
+TBD - created by archiving change stability-and-frontend-compute-shift. Update Purpose after archive.
+## Requirements
+### Requirement: Production Service Runtime SHALL Use Conda-Aligned Execution Paths
+Service units and operational scripts MUST run with a consistent conda-managed Python runtime.
+
+#### Scenario: Service unit starts application
+- **WHEN** systemd starts the dashboard service and watchdog
+- **THEN** both processes MUST execute using the configured conda environment binaries and paths
+
+### Requirement: Watchdog and Runtime Paths MUST Be Operationally Consistent
+PID files, restart flag paths, state files, and worker control interfaces SHALL be consistent across scripts, environment variables, and systemd units.
+
+#### Scenario: Watchdog handles restart flag
+- **WHEN** a restart flag is written by admin control endpoints
+- **THEN** watchdog MUST read the same configured path set and signal the correct Gunicorn master process
+
+### Requirement: Deployment Documentation MUST Match Runtime Contract
+Runbooks and deployment documentation MUST describe the same conda/systemd/watchdog contract used by the deployed system.
+
+#### Scenario: Operator follows deployment runbook
+- **WHEN** an operator performs deploy, health check, and rollback from documentation
+- **THEN** documented commands and paths MUST work without requiring venv-specific assumptions
+

openspec/specs/field-contract-governance/spec.md

@@ -0,0 +1,42 @@
+## Purpose
+Define stable requirements for field-contract-governance.
+## Requirements
+### Requirement: Field Contract Registry SHALL Define UI/API/Export Mapping
+The system SHALL maintain a field contract registry mapping UI labels, API keys, export headers, and semantic types.
+
+#### Scenario: Contract lookup for page rendering
+- **WHEN** a page renders table headers and values
+- **THEN** it MUST resolve display labels and keys through the shared field contract definitions
+
+#### Scenario: Contract lookup for export
+- **WHEN** export headers are generated
+- **THEN** header names MUST follow the same semantic mapping used by the page contract
+
+### Requirement: Consistency Checks MUST Detect Contract Drift
+The system MUST provide automated checks that detect mismatches between UI, API response keys, and export field definitions.
+
+#### Scenario: Drift detection failure
+- **WHEN** a page or export changes a field name without updating the contract
+- **THEN** consistency checks MUST report a failing result before release
+
+### Requirement: Dynamic Report Rendering MUST Sanitize Untrusted Values
+Dynamic table/list rendering in report and query pages SHALL sanitize untrusted text before injecting HTML.
+
+#### Scenario: HTML-like payload in query result
+- **WHEN** an API result field contains HTML-like text payload
+- **THEN** the rendered page MUST display escaped text and MUST NOT execute embedded script content
+
+### Requirement: UI Table and Download Headers SHALL Follow the Same Field Contract
+Page table headers and exported file headers SHALL map to the same field contract definition for the same dataset.
+
+#### Scenario: Header consistency check
+- **WHEN** users view a report table and then export the corresponding data
+- **THEN** header labels MUST remain semantically aligned and avoid conflicting naming for identical fields
+
+### Requirement: Hold Detail Dynamic Rendering MUST Sanitize Untrusted Values
+Dynamic table and distribution rendering in hold-detail SHALL sanitize untrusted text before injecting into HTML attributes or content.
+
+#### Scenario: Hold reason distribution contains HTML-like payload
+- **WHEN** workcenter/package/lot fields include HTML-like text from upstream data
+- **THEN** the hold-detail page MUST render escaped text and MUST NOT execute embedded markup or scripts
+

openspec/specs/field-name-consistency/spec.md

@@ -0,0 +1,16 @@
+## Purpose
+Define stable requirements for field-name-consistency.
+
+## Requirements
+
+
+### Requirement: UI and Export Fields SHALL Have a Consistent Contract
+The system SHALL define and apply a consistent contract among UI column labels, API keys, and export headers for report/query pages.
+
+#### Scenario: Job query export naming consistency
+- **WHEN** job query exports include cause/repair/symptom values
+- **THEN** exported field names SHALL reflect semantic value type consistently (e.g., code name vs status name)
+
+#### Scenario: Resource history field alignment
+- **WHEN** resource history detail table shows KPI columns
+- **THEN** columns required by export semantics (including Availability%) SHALL be present or explicitly mapped

openspec/specs/frontend-compute-shift/spec.md

@@ -0,0 +1,52 @@
+## Purpose
+Define stable requirements for frontend-compute-shift.
+## Requirements
+### Requirement: Display-Layer Computation SHALL be Shifted to Frontend Safely
+The system SHALL move eligible display-layer computations from backend to frontend while preserving existing business behavior.
+
+#### Scenario: Equivalent metric output
+- **WHEN** frontend-computed metrics are produced for a supported page
+- **THEN** output values MUST match baseline backend results within defined rounding rules
+
+### Requirement: Compute Shift MUST be Verifiable by Parity Fixtures
+Each migrated computation MUST have parity fixtures comparing baseline and migrated outputs.
+
+#### Scenario: Parity test gating
+- **WHEN** a compute-shifted module is changed
+- **THEN** parity checks MUST run and fail the migration gate if output differs beyond tolerance
+
+### Requirement: Compute-Shifted Logic SHALL Be Exposed as Reusable Frontend Core Modules
+Frontend-computed metrics and transformations MUST be implemented as reusable, testable modules instead of page-local inline logic.
+
+#### Scenario: Multiple pages consume shared compute logic
+- **WHEN** two or more pages require the same metric transformation or aggregation
+- **THEN** they MUST import a shared frontend core module and produce consistent outputs
+
+### Requirement: Frontend Compute Parity MUST Include Tolerance Contracts Per Metric
+Parity verification SHALL define explicit tolerance and rounding contracts per migrated metric.
+
+#### Scenario: Parity check for migrated metric
+- **WHEN** migrated frontend computation is validated against baseline output
+- **THEN** parity tests MUST evaluate the metric against its declared tolerance and fail when outside bounds
+
+### Requirement: Compute Shift MUST Preserve Existing User-Facing Logic
+Frontend compute migration MUST preserve existing filter semantics, drill-down behavior, and displayed totals.
+
+#### Scenario: Existing dashboard interactions after compute shift
+- **WHEN** users apply filters and navigate drill-down flows on migrated pages
+- **THEN** interaction results MUST remain behaviorally equivalent to the pre-shift baseline
+
+### Requirement: Frontend Compute Paths MUST Handle Zero and Boundary Values Correctly
+Frontend-computed report metrics SHALL preserve valid zero values and boundary conditions in user-visible KPI and summary components.
+
+#### Scenario: Zero-value KPI rendering
+- **WHEN** OU% or availability metrics are computed as `0`
+- **THEN** the page MUST render `0%` (or configured numeric format) instead of placeholder values
+
+### Requirement: Hierarchical Filter Compute Logic SHALL Be Deterministic Across Levels
+Frontend matrix/filter computations SHALL produce deterministic selection and filtering outcomes for group, family, and resource levels.
+
+#### Scenario: Matrix selection at multiple hierarchy levels
+- **WHEN** users toggle matrix cells across group, family, and resource rows
+- **THEN** selected-state rendering and filtered equipment result sets MUST remain level-correct and reversible
+

openspec/specs/full-vite-page-modularization/spec.md

@@ -0,0 +1,81 @@
+## Purpose
+Define stable requirements for full-vite-page-modularization.
+## Requirements
+### Requirement: Major Pages SHALL be Managed by Vite Modules
+The system SHALL provide Vite-managed module entries for major portal pages, replacing inline scripts in a phased manner.
+
+#### Scenario: Portal module loading
+- **WHEN** the portal page is rendered
+- **THEN** it MUST load its behavior from a Vite-built module asset when available
+
+#### Scenario: Page module fallback
+- **WHEN** a required Vite asset is unavailable
+- **THEN** the system MUST keep page behavior functional through explicit fallback logic
+
+### Requirement: Build Pipeline SHALL Produce Backend-Served Assets
+Vite build output MUST be emitted into backend static paths and served by Flask/Gunicorn on the same origin.
+
+#### Scenario: Build artifact placement
+- **WHEN** frontend build is executed
+- **THEN** generated JS/CSS files SHALL be written to the configured backend static dist directory
+
+### Requirement: Vite Page Modules SHALL Reuse Shared Chart and Query Building Blocks
+Page entry modules MUST consume shared chart/query/drawer utilities for common behaviors.
+
+#### Scenario: Common chart behavior across pages
+- **WHEN** multiple report pages render equivalent chart interactions
+- **THEN** the behavior MUST be provided by shared Vite modules rather than duplicated page-local implementations
+
+### Requirement: Modularization MUST Preserve Established Navigation and Drill-Down Semantics
+Refactoring into Vite modules SHALL not alter existing page transitions, independent tabs, and drill-down entry points.
+
+#### Scenario: User follows existing drill-down path
+- **WHEN** the user navigates from summary page to detail views
+- **THEN** the resulting flow and parameter semantics MUST match the established baseline behavior
+
+### Requirement: Module Boundaries SHALL Support Frontend Compute Expansion
+Vite module structure MUST keep compute logic decoupled from DOM wiring so additional backend-to-frontend computation shifts can be added safely.
+
+#### Scenario: Adding a new frontend-computed metric
+- **WHEN** a new metric is migrated from backend to frontend
+- **THEN** the metric logic MUST be integrated through shared compute modules without rewriting page routing structure
+
+### Requirement: WIP Report Pages SHALL Be Served by Vite Modules
+The system SHALL provide Vite entry bundles for WIP overview and WIP detail pages, with template-level asset resolution.
+
+#### Scenario: WIP module asset available
+- **WHEN** the built asset exists in backend static dist
+- **THEN** the page MUST load behavior from the corresponding Vite module entry
+
+#### Scenario: WIP module asset unavailable
+- **WHEN** the built asset is not present
+- **THEN** the page MUST retain equivalent behavior through explicit inline fallback logic
+
+### Requirement: Vite Modules MUST Preserve Legacy Handler Compatibility
+Vite report modules SHALL expose required global handlers for existing inline entry points until event wiring is fully migrated.
+
+#### Scenario: Inline-triggered handler compatibility
+- **WHEN** a template control invokes existing global handler names
+- **THEN** the migrated module MUST provide compatible callable handlers without runtime scope errors
+
+### Requirement: Hold Detail Page SHALL Be Served by a Vite Module
+The system SHALL provide a dedicated Vite entry bundle for the hold-detail report page.
+
+#### Scenario: Hold-detail module asset exists
+- **WHEN** `/hold-detail` is rendered and `hold-detail.js` exists in static dist
+- **THEN** the page MUST load behavior from the Vite module entry
+
+#### Scenario: Hold-detail module asset missing
+- **WHEN** `/hold-detail` is rendered and the module asset is unavailable
+- **THEN** the page MUST remain operational through explicit inline fallback logic
+
+### Requirement: WIP Modules SHALL Reuse Shared Autocomplete and Filter Query Utilities
+WIP overview and WIP detail Vite entry modules SHALL use shared frontend core utilities for autocomplete request construction and cross-filter behavior.
+
+#### Scenario: Cross-filter autocomplete parity across WIP pages
+- **WHEN** users type in workorder/lot/package/type filters on either WIP overview or WIP detail pages
+- **THEN** both pages MUST generate equivalent autocomplete request parameters and return behaviorally consistent dropdown results
+
+#### Scenario: Shared utility change propagates across both pages
+- **WHEN** autocomplete mapping rules are updated in the shared core module
+- **THEN** both WIP overview and WIP detail modules MUST consume the updated behavior without duplicated page-local logic edits

openspec/specs/layered-route-cache/spec.md

@@ -0,0 +1,42 @@
+## Purpose
+Define stable requirements for layered-route-cache.
+## Requirements
+### Requirement: Route Cache SHALL Use Layered Storage
+The route cache SHALL use L1 in-memory TTL cache and L2 Redis JSON cache when Redis is available.
+
+#### Scenario: L1 cache hit
+- **WHEN** a cached key exists in L1 and is unexpired
+- **THEN** the API response SHALL be returned from memory without querying Redis
+
+#### Scenario: L2 fallback
+- **WHEN** a cached key is missing in L1 but exists in Redis
+- **THEN** the value SHALL be returned and warmed into L1
+
+### Requirement: Cache SHALL Degrade Gracefully Without Redis
+The route cache SHALL remain functional with L1 cache when Redis is unavailable.
+
+#### Scenario: Redis unavailable at startup
+- **WHEN** Redis health check fails during app initialization
+- **THEN** route cache operations SHALL continue using L1 cache without application failure
+
+### Requirement: Resource and WIP Full-Table Cache SHALL Remain the Authoritative Cached Dataset
+The system MUST keep `resource` and `wip` full-table cache datasets as the canonical cached source for downstream route queries.
+
+#### Scenario: Route query reads cached baseline
+- **WHEN** an endpoint requires resource or wip data
+- **THEN** it MUST read from the corresponding full-table cache baseline before applying derived filters or aggregations
+
+### Requirement: Cache Access Paths SHALL Support Index-Based Lookup and Derived Views
+The caching layer SHALL support index and derived-view access paths to reduce per-request full-table merge and transformation overhead.
+
+#### Scenario: Lookup by key under concurrent load
+- **WHEN** requests query by high-cardinality keys such as RESOURCEID
+- **THEN** the system MUST serve lookups via indexed cache access instead of repeated full-array scans
+
+### Requirement: Full-Table Cache Refresh MUST Support Incremental Derivation Updates
+Derived cache indices and aggregates MUST be refreshed consistently when the underlying full-table cache version changes.
+
+#### Scenario: Cache version update
+- **WHEN** full-table cache is refreshed to a new version
+- **THEN** dependent indices and derived views MUST be rebuilt or updated before being exposed for reads
+

openspec/specs/migration-gates-and-rollout/spec.md

@@ -0,0 +1,48 @@
+## Purpose
+Define stable requirements for migration-gates-and-rollout.
+## Requirements
+### Requirement: Migration Gates SHALL Define Cutover Readiness
+The system SHALL define explicit migration gates for functional parity, build integrity, and operational health before final cutover.
+
+#### Scenario: Gate evaluation before cutover
+- **WHEN** release is prepared for final cutover
+- **THEN** all required migration gates MUST pass or cutover SHALL be blocked
+
+### Requirement: Rollout and Rollback Procedures MUST be Actionable
+The system SHALL document actionable rollout and rollback procedures for root migration.
+
+#### Scenario: Rollback execution
+- **WHEN** post-cutover validation fails critical checks
+- **THEN** operators MUST be able to execute documented rollback steps to restore previous stable behavior
+
+### Requirement: Migration Gates SHALL Include Runtime Resilience Validation
+Cutover readiness gates MUST include resilience checks for pool exhaustion handling, circuit-breaker fail-fast behavior, and recovery flow.
+
+#### Scenario: Resilience gate evaluation
+- **WHEN** migration gates are executed before release
+- **THEN** resilience tests MUST pass for degraded-response semantics and recovery path validation
+
+### Requirement: Migration Gates SHALL Include Frontend Compute Parity Validation
+Cutover readiness MUST include parity validation for metrics shifted from backend to frontend computation.
+
+#### Scenario: Compute parity gate
+- **WHEN** a release includes additional frontend-computed metrics
+- **THEN** gate execution MUST verify parity fixtures and fail if tolerance contracts are violated
+
+### Requirement: Rollout Procedure MUST Include Conda-Systemd-Watchdog Rehearsal
+Rollout and rollback runbooks SHALL include an operational rehearsal for service start, watchdog-triggered reload, and post-restart health checks under the conda/systemd runtime contract.
+
+#### Scenario: Pre-cutover rehearsal
+- **WHEN** operators execute pre-cutover rehearsal
+- **THEN** they MUST successfully complete conda-based start, worker reload, and health verification steps documented in the runbook
+
+### Requirement: Migration Gates SHALL Enforce Architecture Documentation Consistency
+Cutover governance MUST include verification that runtime architecture contracts documented for operators match implemented deployment and resilience behavior.
+
+#### Scenario: Documentation gate before release
+- **WHEN** release gates are executed for a migration or hardening change
+- **THEN** project README artifacts MUST be updated to reflect current single-port runtime contract, resilience diagnostics, and frontend modularization strategy
+
+#### Scenario: Gate fails on stale architecture contract
+- **WHEN** implementation introduces resilience or module-governance changes but README architecture section remains outdated
+- **THEN** release governance MUST treat the gate as failed until documentation is aligned

openspec/specs/portal-drawer-navigation/spec.md

@@ -0,0 +1,19 @@
+## Purpose
+Define stable requirements for portal-drawer-navigation.
+
+## Requirements
+
+
+### Requirement: Portal Navigation SHALL Group Entries by Functional Drawers
+The portal SHALL group navigation entries into functional drawers: reports, queries, and development tools.
+
+#### Scenario: Drawer grouping visibility
+- **WHEN** users open the portal
+- **THEN** report pages and query pages SHALL appear in separate drawer groups
+
+### Requirement: Existing Page Behavior SHALL Remain Compatible
+The portal navigation refactor SHALL preserve existing target routes and lazy-load behavior for content frames.
+
+#### Scenario: Route continuity
+- **WHEN** a user selects an existing page entry from the new drawer
+- **THEN** the corresponding original route SHALL be loaded without changing page business logic behavior

openspec/specs/report-effects-parity/spec.md

@@ -0,0 +1,30 @@
+# report-effects-parity Specification
+
+## Purpose
+TBD - created by archiving change vite-jinja-report-parity-hardening. Update Purpose after archive.
+## Requirements
+### Requirement: Report Effect Parity SHALL Be Preserved During Vite Migration
+The system SHALL preserve existing Jinja-era report interactions when report pages are served by Vite modules.
+
+#### Scenario: WIP overview interactions remain equivalent
+- **WHEN** users operate WIP overview filters, KPI cards, chart refresh, and drill-down entry
+- **THEN** the resulting state transitions and navigation parameters MUST remain behaviorally equivalent to the baseline page logic
+
+#### Scenario: WIP detail interactions remain equivalent
+- **WHEN** users operate WIP detail filters, pagination, lot detail popup, and back-to-overview transitions
+- **THEN** the resulting data scope and interaction behavior MUST match baseline semantics
+
+### Requirement: Report Visual Semantics MUST Remain Consistent
+Report pages SHALL keep established status color semantics, KPI display rules, and table/chart synchronization behavior after migration.
+
+#### Scenario: KPI and matrix state consistency
+- **WHEN** metric values are zero or filters target specific matrix levels
+- **THEN** KPI values and selected-state highlights MUST render correctly without collapsing valid zero values or losing selection state
+
+### Requirement: Hold Detail Interaction Semantics SHALL Remain Equivalent After Modularization
+Migrating hold-detail to a Vite module SHALL preserve existing filter, pagination, and refresh behavior.
+
+#### Scenario: User applies filters and paginates on hold-detail
+- **WHEN** users toggle age/workcenter/package filters and navigate pages
+- **THEN** returned lots, distribution highlights, and pagination state MUST remain behaviorally equivalent to baseline inline behavior
+

openspec/specs/root-cutover-finalization/spec.md

@@ -0,0 +1,23 @@
+## Purpose
+Define stable requirements for root-cutover-finalization.
+
+## Requirements
+
+
+### Requirement: Root Project SHALL be the Single Execution Target
+The system SHALL run all application startup, test, and deployment workflows from `DashBoard_vite` root without requiring nested `DashBoard/` paths.
+
+#### Scenario: Root startup script execution
+- **WHEN** an operator runs start/deploy scripts from `DashBoard_vite` root
+- **THEN** all referenced source/config/script paths MUST resolve inside root project structure
+
+#### Scenario: Root test execution
+- **WHEN** CI or local developer runs test commands from root
+- **THEN** tests SHALL execute against root source tree and root config files
+
+### Requirement: Reference Directory MUST Remain Non-Authoritative
+`DashBoard/` SHALL be treated as reference-only and MUST NOT be required for production runtime.
+
+#### Scenario: Runtime independence
+- **WHEN** root application is started in an environment without `DashBoard/`
+- **THEN** the application MUST remain functional for the defined migration scope

openspec/specs/root-project-restructure/spec.md

@@ -0,0 +1,16 @@
+## Purpose
+Define stable requirements for root-project-restructure.
+
+## Requirements
+
+
+### Requirement: Root Directory SHALL be the Primary Executable Project
+The system SHALL treat `DashBoard_vite` root directory as the primary executable project, while `DashBoard/` remains reference-only during migration.
+
+#### Scenario: Running app from root
+- **WHEN** a developer runs project scripts from `DashBoard_vite` root
+- **THEN** the application startup flow SHALL resolve code and config from root project files
+
+#### Scenario: Reference directory preserved
+- **WHEN** migration is in progress
+- **THEN** `DashBoard/` SHALL remain available for structure comparison and behavior verification

openspec/specs/runtime-resilience-recovery/spec.md

@@ -0,0 +1,50 @@
+# runtime-resilience-recovery Specification
+
+## Purpose
+TBD - created by archiving change stability-and-frontend-compute-shift. Update Purpose after archive.
+## Requirements
+### Requirement: Database Pool Runtime Configuration SHALL Be Enforced
+The system SHALL apply database pool and timeout parameters from runtime configuration to the active SQLAlchemy engine used by request handling.
+
+#### Scenario: Runtime pool configuration takes effect
+- **WHEN** operators set pool and timeout values via environment configuration and start the service
+- **THEN** the active engine MUST use those values for pool size, overflow, wait timeout, and query call timeout
+
+### Requirement: Pool Exhaustion MUST Return Retry-Aware Degraded Responses
+The system MUST return explicit degraded responses for connection pool exhaustion and include machine-readable metadata for retry/backoff behavior.
+
+#### Scenario: Pool exhausted under load
+- **WHEN** concurrent requests exceed available database connections and pool wait timeout is reached
+- **THEN** the API MUST return a dedicated error code and retry guidance instead of a generic 500 failure
+
+### Requirement: Runtime Degradation MUST Integrate Circuit Breaker State
+Database-facing API behavior SHALL distinguish circuit-breaker-open degradation from transient query failures.
+
+#### Scenario: Circuit breaker is open
+- **WHEN** the circuit breaker transitions to OPEN state
+- **THEN** database-backed endpoints MUST fail fast with a stable degradation response contract
+
+### Requirement: Worker Recovery SHALL Support Hot Reload and Watchdog-Assisted Recovery
+The runtime MUST support graceful worker hot reload and watchdog-triggered recovery without requiring a port change or full system reboot.
+
+#### Scenario: Worker restart requested
+- **WHEN** an authorized operator requests worker restart during degraded operation
+- **THEN** the service MUST trigger graceful reload and preserve single-port availability
+
+### Requirement: Report Frontend API Access SHALL Honor Degraded Retry Contracts
+Report pages SHALL use retry-aware API access paths for JSON endpoints so degraded backend responses propagate retry metadata to UI behavior.
+
+#### Scenario: Pool exhaustion or circuit-open response
+- **WHEN** report API endpoints return degraded error codes with retry hints
+- **THEN** frontend calls MUST flow through MesApi-compatible behavior and avoid aggressive uncontrolled retry loops
+
+### Requirement: Runtime Resilience Diagnostics MUST Expose Actionable Signals
+The system MUST expose machine-readable resilience thresholds, restart-churn indicators, and operator action recommendations so degraded states can be triaged consistently.
+
+#### Scenario: Health payload includes resilience diagnostics
+- **WHEN** clients call `/health` or `/health/deep`
+- **THEN** responses MUST include resilience thresholds and a recommendation field describing whether to observe, throttle, or trigger controlled worker recovery
+
+#### Scenario: Admin status includes restart churn summary
+- **WHEN** operators call `/admin/api/system-status` or `/admin/api/worker/status`
+- **THEN** responses MUST include bounded restart history summary within a configured time window and indicate whether churn threshold is exceeded

openspec/specs/vite-single-port-integration/spec.md

@@ -0,0 +1,19 @@
+## Purpose
+Define stable requirements for vite-single-port-integration.
+
+## Requirements
+
+
+### Requirement: Frontend Build SHALL Use Vite With Flask Static Output
+The system SHALL use Vite to build frontend assets and output artifacts into Flask static directories served by the backend.
+
+#### Scenario: Build asset generation
+- **WHEN** frontend build is executed
+- **THEN** Vite SHALL generate portal-related JS/CSS artifacts into the backend static output path
+
+### Requirement: Deployment SHALL Preserve Single External Port
+The system SHALL preserve single-port external serving through Flask/Gunicorn.
+
+#### Scenario: Production serving mode
+- **WHEN** the system runs in deployment mode
+- **THEN** frontend assets SHALL be served through Flask on the same external port as API/page routes