# Quality and Monitoring Baseline

## CI Quality Gates

Pipeline file: `.github/workflows/quality-gates.yml`

Stages:
- `lint-and-test`: Ruff + pytest (coverage threshold enforced).
- `security-scan`: `pip-audit` dependency vulnerability scan.

Failure policy:
- Any failed stage blocks merge.
- Coverage floor below threshold blocks merge.

## Coverage and Test Scope

Current baseline suites:
- API contracts: `tests/test_api_contracts.py`
- DB lifecycle workflows: `tests/test_db_workflows.py`
- Accessibility contracts: `tests/test_accessibility_contract.py`
- Security/performance smoke checks: `tests/test_security_and_performance.py`

## UX Validation Checklist

Run manually on desktop + mobile viewport:
1. Hero loads with image and CTA visible.
2. Feed cards render with source and TL;DR CTA.
3. Modal opens/closes with Escape and backdrop click.
4. Share controls are visible in light and dark themes.
5. Floating back-to-top appears after scrolling and returns to top.

## Production Metrics and Alert Thresholds

| Metric | Target | Alert Threshold |
|---|---|---|
| API p95 latency (`/api/news`) | < 350 ms | > 750 ms for 10 min |
| API error rate (`5xx`) | < 1% | > 3% for 5 min |
| Scheduler success rate | 100% hourly runs | 2 consecutive failures |
| Feed freshness lag | < 75 min | > 120 min |

## Alert Runbook

### Incident: Elevated API latency
1. Confirm DB file I/O and host CPU saturation.
2. Inspect recent release diff for expensive queries.
3. Roll back latest deploy if regression is confirmed.

### Incident: Scheduler failures
1. Check API key and upstream provider status.
2. Run `python -m backend.cli force-fetch` for repro.
3. Review logs for provider fallback exhaustion.

### Incident: Error-rate spike
1. Check `/api/health` response and DB availability.
2. Identify top failing routes and common status codes.
3. Mitigate with rollback or feature flag disablement.

## Review/Remediation Log Template

Use this structure for each cycle:

```text
severity=<high|medium|low> owner=<name> area=<frontend|backend|infra> finding=<summary> status=<open|fixed>
```