First deployment

openspec/changes/archive/2026-02-13-p15-complete-test-suite/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-13

openspec/changes/archive/2026-02-13-p15-complete-test-suite/design.md

@@ -0,0 +1,55 @@
+## Context
+
+The codebase has grown across frontend UX, backend ingestion, translations, analytics, and admin tooling. Quality checks are currently ad hoc and mostly manual, creating regression risk. A single cross-layer test and observability program is needed to enforce predictable release quality.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Establish CI quality gates covering unit, integration, E2E, accessibility, security, and performance.
+- Provide deterministic test fixtures for UI/API/DB workflows.
+- Define explicit coverage targets for critical paths and edge cases.
+- Add production monitoring and alerting for latency, failures, and freshness.
+
+**Non-Goals:**
+- Migrating the app to a different framework.
+- Building a full SRE platform from scratch.
+- Replacing existing business logic outside remediation findings.
+
+## Decisions
+
+### Decision 1: Layered test pyramid with release gates
+Adopt unit + integration + E2E layering; block release when any gate fails.
+
+### Decision 2: Deterministic test data contracts
+Use seeded fixtures and mockable provider boundaries for repeatable results.
+
+### Decision 3: Accessibility and speed as first-class CI checks
+Treat WCAG and page-speed regressions as gate failures with explicit thresholds.
+
+### Decision 4: Security checks split by class
+Run dependency audit, static security lint, and API abuse smoke tests separately for clearer ownership.
+
+### Decision 5: Monitoring linked to user-impacting SLOs
+Alert on API error rate, response latency, scheduler freshness, and failed fetch cycles.
+
+## Risks / Trade-offs
+
+- **[Risk] Longer CI times** -> Mitigation: split fast/slow suites, parallelize jobs.
+- **[Risk] Flaky E2E tests** -> Mitigation: stable fixtures, retry policy only for known transient failures.
+- **[Risk] Alert fatigue** -> Mitigation: tune thresholds with burn-in period and severity levels.
+
+## Migration Plan
+
+1. Baseline current test/tooling and add missing framework dependencies.
+2. Implement layered suites and CI workflow stages.
+3. Add WCAG, speed, and security checks with thresholds.
+4. Add monitoring dashboards and alert routes.
+5. Run remediation sprint for failing gates.
+
+Rollback:
+- Keep non-blocking mode for new gates until stability criteria are met.
+
+## Open Questions
+
+- Which minimum coverage threshold should be required for merge (line/branch)?
+- Which environments should execute full E2E and speed checks (PR vs nightly)?

openspec/changes/archive/2026-02-13-p15-complete-test-suite/proposal.md

@@ -0,0 +1,36 @@
+## Why
+
+The platform needs stronger quality gates to ensure stable, predictable behavior across releases. A complete testing and review program will reduce regressions, improve confidence in deployments, and surface performance, accessibility, and security risks earlier.
+
+## What Changes
+
+- Introduce a unified automated test suite strategy covering unit, integration, and end-to-end paths.
+- Add end-to-end test coverage for core UI flows, API contracts, and database state transitions.
+- Add WCAG-focused accessibility checks and include them in quality gates.
+- Add page speed and runtime performance checks with repeatable thresholds.
+- Add baseline security testing (dependency, config, and common web vulnerability checks).
+- Add user-experience validation scenarios for key journeys and failure states.
+- Define comprehensive coverage expectations for critical features and edge cases.
+- Add a structured code-review/remediation/optimization pass to resolve quality debt.
+- Add performance monitoring and alerting requirements for production health visibility.
+
+## Capabilities
+
+### New Capabilities
+- `platform-quality-gates`: Defines required CI quality gates and pass/fail criteria for release readiness.
+- `end-to-end-system-testing`: Defines end-to-end testing coverage across UI, API, and database workflows.
+- `security-and-performance-test-harness`: Defines security checks and page/runtime performance testing strategy.
+- `observability-monitoring-and-alerting`: Defines performance monitoring signals, dashboards, and alerting thresholds.
+- `code-review-remediation-workflow`: Defines structured remediation and optimization workflow after comprehensive review.
+
+### Modified Capabilities
+- `wcag-2-2-aa-accessibility`: Expand verification requirements to include automated accessibility testing in release gates.
+- `delivery-and-rendering-performance`: Add enforceable page speed benchmarks and regression thresholds.
+- `site-admin-safety-and-ergonomics`: Add operational verification requirements tied to maintenance command behaviors.
+
+## Impact
+
+- **Testing/Tooling:** New test suites, fixtures, and CI workflows for UI/API/DB/accessibility/security/performance.
+- **Frontend/Backend:** Potential bug fixes and optimizations discovered during comprehensive test and review passes.
+- **Operations:** Monitoring/alerting setup and documentation for performance and reliability signals.
+- **Release Process:** Stronger quality gates before archive/release actions.

openspec/changes/archive/2026-02-13-p15-complete-test-suite/specs/code-review-remediation-workflow/spec.md

@@ -0,0 +1,17 @@
+## ADDED Requirements
+
+### Requirement: Comprehensive review findings are tracked and remediated
+The system SHALL track review findings and remediation outcomes in a structured workflow.
+
+#### Scenario: Review finding lifecycle
+- **WHEN** a code review identifies defect, risk, or optimization opportunity
+- **THEN** finding is recorded with severity/owner/status
+- **AND** remediation is linked to a verifiable change
+
+### Requirement: Optimization work is bounded and measurable
+Optimization actions SHALL include measurable before/after evidence.
+
+#### Scenario: Optimization evidence recorded
+- **WHEN** performance or code quality optimization is implemented
+- **THEN** benchmark or metric delta is documented
+- **AND** no functional regression is introduced

openspec/changes/archive/2026-02-13-p15-complete-test-suite/specs/delivery-and-rendering-performance/spec.md

@@ -0,0 +1,43 @@
+## MODIFIED Requirements
+
+### Requirement: HTTP delivery applies compression and cache policy
+The system SHALL apply transport-level compression and explicit cache directives for static assets, API responses, and public HTML routes.
+
+#### Scenario: Compressed responses are available for eligible payloads
+- **WHEN** a client requests compressible content that exceeds the compression threshold
+- **THEN** the response is served with gzip compression
+- **AND** response headers advertise the selected content encoding
+
+#### Scenario: Route classes receive deterministic cache-control directives
+- **WHEN** clients request static assets, API responses, or HTML page routes
+- **THEN** each route class returns a cache policy aligned to its freshness requirements
+- **AND** cache directives are explicit and testable from response headers
+
+### Requirement: Media rendering optimizes perceived loading performance
+The system SHALL lazy-load non-critical images and render shimmer placeholders until image load completion or fallback resolution.
+
+#### Scenario: Feed and modal images lazy-load with placeholders
+- **WHEN** feed or modal images have not completed loading
+- **THEN** a shimmer placeholder is visible for the pending image region
+- **AND** the placeholder is removed after load or fallback error handling completes
+
+#### Scenario: Image rendering reduces layout shift risk
+- **WHEN** article images are rendered in hero, feed, or modal contexts
+- **THEN** image elements include explicit dimensions and async decoding hints
+- **AND** layout remains stable while content loads
+
+### Requirement: Smooth scrolling behavior is consistently enabled
+The system SHALL provide smooth scrolling behavior for in-page navigation and user-initiated scroll interactions.
+
+#### Scenario: In-page navigation uses smooth scrolling
+- **WHEN** users navigate to in-page anchors or equivalent interactions
+- **THEN** scrolling transitions occur smoothly rather than jumping abruptly
+- **AND** behavior is consistent across supported breakpoints
+
+### Requirement: Performance thresholds are continuously validated
+The system SHALL enforce page-speed and rendering performance thresholds in automated checks.
+
+#### Scenario: Performance budget gate
+- **WHEN** performance checks exceed configured budget thresholds
+- **THEN** CI performance gate fails
+- **AND** reports identify the regressed metrics and impacted pages

openspec/changes/archive/2026-02-13-p15-complete-test-suite/specs/end-to-end-system-testing/spec.md

@@ -0,0 +1,16 @@
+## ADDED Requirements
+
+### Requirement: End-to-end coverage spans UI, API, and DB effects
+The system SHALL provide end-to-end tests that validate full workflows across UI, API, and persisted database outcomes.
+
+#### Scenario: Core user flow E2E
+- **WHEN** a core browsing flow is executed in E2E tests
+- **THEN** UI behavior, API responses, and DB side effects match expected outcomes
+
+### Requirement: Edge-case workflows are covered
+The system SHALL include edge-case E2E tests for critical failure and boundary conditions.
+
+#### Scenario: Failure-state E2E
+- **WHEN** an edge case is triggered (empty data, unavailable upstream, invalid permalink, etc.)
+- **THEN** system response remains stable and user-safe
+- **AND** no unhandled runtime errors occur

openspec/changes/archive/2026-02-13-p15-complete-test-suite/specs/observability-monitoring-and-alerting/spec.md

@@ -0,0 +1,16 @@
+## ADDED Requirements
+
+### Requirement: Production monitoring covers key reliability signals
+The system SHALL capture and expose reliability/performance metrics for core services.
+
+#### Scenario: Metrics available for operations
+- **WHEN** production system is running
+- **THEN** dashboards expose API latency/error rate, scheduler freshness, and ingestion health signals
+
+### Requirement: Alerting is actionable and threshold-based
+The system SHALL send alerts on defined thresholds with clear operator guidance.
+
+#### Scenario: Threshold breach alert
+- **WHEN** a monitored metric breaches configured threshold
+- **THEN** alert is emitted to configured channel
+- **AND** alert includes service, metric, threshold, and suggested next action

openspec/changes/archive/2026-02-13-p15-complete-test-suite/specs/platform-quality-gates/spec.md

@@ -0,0 +1,17 @@
+## ADDED Requirements
+
+### Requirement: Release quality gates are mandatory
+The system SHALL enforce mandatory CI quality gates before release.
+
+#### Scenario: Gate failure blocks release
+- **WHEN** any required gate fails
+- **THEN** release pipeline status is failed
+- **AND** deployment/archive promotion is blocked
+
+### Requirement: Required gates are explicit and versioned
+The system SHALL define an explicit set of required gates and versions for tooling.
+
+#### Scenario: Gate manifest exists
+- **WHEN** pipeline configuration is evaluated
+- **THEN** required gates include tests, accessibility, security, and performance checks
+- **AND** tool versions are pinned or documented for reproducibility

openspec/changes/archive/2026-02-13-p15-complete-test-suite/specs/security-and-performance-test-harness/spec.md

@@ -0,0 +1,17 @@
+## ADDED Requirements
+
+### Requirement: Security test harness runs in CI
+The system SHALL run baseline automated security checks in CI.
+
+#### Scenario: Security checks execute
+- **WHEN** CI pipeline runs on protected branches
+- **THEN** dependency vulnerability and static security checks execute
+- **AND** high-severity findings fail the gate
+
+### Requirement: Performance test harness enforces thresholds
+The system SHALL run page-speed and API-performance checks against defined thresholds.
+
+#### Scenario: Performance regression detection
+- **WHEN** measured performance exceeds regression threshold
+- **THEN** performance gate fails
+- **AND** reports include metric deltas and failing surfaces

openspec/changes/archive/2026-02-13-p15-complete-test-suite/specs/site-admin-safety-and-ergonomics/spec.md

@@ -0,0 +1,33 @@
+## MODIFIED Requirements
+
+### Requirement: Confirmation guard for destructive commands
+Destructive admin commands SHALL require explicit confirmation before execution.
+
+#### Scenario: Missing confirmation flag
+- **WHEN** an operator runs clear-news or clean-archive without required confirmation
+- **THEN** the command exits without applying destructive changes
+- **AND** prints guidance for explicit confirmation usage
+
+### Requirement: Dry-run support where applicable
+Maintenance commands SHALL provide dry-run mode for previewing effects where feasible.
+
+#### Scenario: Dry-run preview
+- **WHEN** an operator invokes a command with dry-run mode
+- **THEN** the command reports intended actions and affected counts
+- **AND** persists no data changes
+
+### Requirement: Actionable failure summaries
+Admin commands SHALL output actionable errors and final status summaries.
+
+#### Scenario: Partial failure reporting
+- **WHEN** a maintenance command partially fails
+- **THEN** output includes succeeded/failed counts
+- **AND** includes actionable next-step guidance
+
+### Requirement: Admin workflows have automated verification coverage
+Admin safety-critical workflows SHALL be covered by automated tests.
+
+#### Scenario: Safety command regression test
+- **WHEN** admin command tests run in CI
+- **THEN** confirmation and dry-run behavior are validated by tests
+- **AND** regressions in safety guards fail the gate

openspec/changes/archive/2026-02-13-p15-complete-test-suite/specs/wcag-2-2-aa-accessibility/spec.md

@@ -0,0 +1,19 @@
+## MODIFIED Requirements
+
+### Requirement: Core user flows comply with WCAG 2.2 AA baseline
+The system SHALL meet WCAG 2.2 AA accessibility requirements for primary interactions and content presentation, and SHALL verify compliance through automated accessibility checks in CI.
+
+#### Scenario: Keyboard-only interaction flow
+- **WHEN** a keyboard-only user navigates the page
+- **THEN** all primary interactive elements are reachable and operable
+- **AND** visible focus indication is present at each step
+
+#### Scenario: Contrast and non-text alternatives
+- **WHEN** users consume text and non-text UI content
+- **THEN** color contrast meets AA thresholds for relevant text and controls
+- **AND** meaningful images and controls include accessible labels/alternatives
+
+#### Scenario: Accessibility CI gate
+- **WHEN** pull request validation runs
+- **THEN** automated accessibility checks execute against key pages and flows
+- **AND** violations above configured severity fail the gate

openspec/changes/archive/2026-02-13-p15-complete-test-suite/tasks.md

@@ -0,0 +1,43 @@
+## 1. Test Framework Baseline
+
+- [x] 1.1 Inventory current test/tooling gaps across frontend, backend, and DB layers.
+- [x] 1.2 Add or standardize test runners, fixtures, and deterministic seed data.
+- [x] 1.3 Define CI quality-gate stages and failure policies.
+
+## 2. UI/API/DB End-to-End Coverage
+
+- [x] 2.1 Implement E2E tests for critical UI journeys (hero/feed/modal/permalink/share).
+- [x] 2.2 Implement API contract integration tests for news, config, and admin flows.
+- [x] 2.3 Add DB state verification for ingestion, archiving, and translation workflows.
+- [x] 2.4 Add edge-case E2E scenarios for invalid input, empty data, and failure paths.
+
+## 3. Accessibility and UX Testing
+
+- [x] 3.1 Integrate automated WCAG checks into CI for core pages.
+- [x] 3.2 Add keyboard-focus and contrast regression checks.
+- [x] 3.3 Add user-experience validation checklist for readability and interaction clarity.
+
+## 4. Security and Performance Testing
+
+- [x] 4.1 Add dependency and static security scanning to CI.
+- [x] 4.2 Add abuse/safety smoke tests for API endpoints.
+- [x] 4.3 Add page-speed and runtime performance checks with threshold budgets.
+- [x] 4.4 Fail pipeline when security/performance thresholds are breached.
+
+## 5. Review, Remediation, and Optimization
+
+- [x] 5.1 Run comprehensive code review pass and log findings with severity/owner.
+- [x] 5.2 Remediate defects uncovered by automated and manual testing.
+- [x] 5.3 Implement optimization tasks with before/after evidence.
+
+## 6. Monitoring and Alerting
+
+- [x] 6.1 Define production metrics for reliability and latency.
+- [x] 6.2 Configure dashboards and alert thresholds for key services.
+- [x] 6.3 Add alert runbook guidance for common incidents.
+
+## 7. Final Validation
+
+- [x] 7.1 Verify all quality gates pass in CI.
+- [x] 7.2 Verify coverage targets and edge-case suites meet defined thresholds.
+- [x] 7.3 Verify monitoring alerts trigger correctly in test conditions.