lighthouse fixes

openspec/specs/lighthouse-quality-gate/spec.md

@@ -0,0 +1,50 @@
+## Purpose
+
+Define a deterministic Lighthouse quality gate that produces repeatable scores and blocks regressions across required categories.
+
+## Requirements
+
+### Requirement: Deterministic Lighthouse configuration
+The project MUST define a deterministic Lighthouse run configuration that specifies:
+
+- a fixed list of URLs to audit
+- mobile and desktop runs
+- theme variants: `light`, `dark`, and `high-contrast`
+- a clean run environment (no browser extensions)
+- throttling / device emulation settings
+
+The configuration MUST be checked into the repository.
+
+#### Scenario: Lighthouse config is version-controlled
+- **WHEN** a developer checks the repository
+- **THEN** a Lighthouse configuration file/script exists and is referenced by a documented command
+
+### Requirement: Lighthouse gate enforces perfect scores
+The project MUST provide a command that runs Lighthouse for the configured URLs and variants and fails if any category score is below 100:
+
+- Performance
+- Accessibility
+- Best Practices
+- SEO
+
+The command MUST output the reports as build artifacts (HTML and/or JSON) to a deterministic output directory.
+
+#### Scenario: Gate fails on a regression
+- **WHEN** Lighthouse runs and any audited variant scores 99 in any category
+- **THEN** the command exits non-zero and reports which URL/variant failed
+
+#### Scenario: Gate produces artifacts
+- **WHEN** Lighthouse runs successfully
+- **THEN** the reports are written to the configured output directory for later inspection
+
+### Requirement: Repeatable scoring rule
+The Lighthouse gate MUST define a repeatable scoring rule to reduce run-to-run noise.
+
+At minimum, it MUST document one of the following:
+
+- single-run with fixed throttling and clean environment, or
+- multiple runs per variant with a deterministic selection rule (e.g., median)
+
+#### Scenario: Run-to-run method is documented
+- **WHEN** a developer runs the gate locally or in CI
+- **THEN** the method for selecting/reporting scores is explicitly documented