Recommendation accuracy validation

The repeatable buyer-scenario check for #261: a documented set of representative inputs whose expected shortlists are derived from the comparison matrix, executed against a live instance's /api/recommendation. If the catalog, rules, or engine drift, this fails.

Running it

npm run validate:scenarios                        # against the dev server (localhost:6650)
BASE_URL=https://<host> npm run validate:scenarios  # against preview/production

The script is scripts/validate-scenarios.mjs; it exits non-zero on any mismatch, so it can gate CI or a deploy. It needs a seeded database (the catalog seed plus seed/catalog-fragments.txt — what seed:local and seed:remote both apply; dev-up does not seed).

Scenarios and their matrix derivations

Scenario (inputs as factor options)	Expected lead	Why (matrix grounding)
Coastal + residential	sl73	SL73 is the only system with Miami-Dade hurricane compliance = Yes
Interior acoustic control + commercial	nw-acoustical-645	Highest STC range (32–45); the acoustic rule gates on STC ≥ 40
Wood frames + residential	nw-wood-540	The wood-framed folding flagship; materials includes Wood
Urban + exterior acoustic control	nw-multislide-630	Best OITC (up to 36); the OITC rule gates at ≥ 30
Mountain + cold climate	nw-aluminum-640	Energy Star-qualifiable and high-altitude suitable; cold-climate rule (priority 45) leads
Commercial + ADA required	nw-multislide-630	Unconditional ADA yes; budget SL45/SL60 appear as alternatives (ADA yes with insert)
Open corner + aluminum	nw-aluminum-640	Open-corner available = Yes; SL45/SL60 are the cheaper qualifying corners
Clad frames	nw-clad-740	The only Aluminum/Wood (clad) system
Segmented / curved opening	hsw60	Segmented curves available = Yes on the HSW stacking family; SL45 is the budget qualifier
No answers	nw-aluminum-640	The versatile-default global rule — no buyer leaves empty-handed

Alternatives asserted in the script are systems that must appear among the right-sized (strictly cheaper, still qualifying) alternatives.

Reading a failure: the lead is wrong → a rule, threshold, or attribute value changed (check seed/sql/075-selection-rules.sql and the value the rule gates on); an expected alternative is missing → its qualifying value or its budget tier changed. The matrix derivations above say which cell to check — sources and precedence are in data-provenance.md.