From b6a3b0722b6430f6999457556e2c3c3593293b3f Mon Sep 17 00:00:00 2001 From: CLU Date: Thu, 29 Oct 2026 13:17:21 -0500 Subject: [PATCH] docs: document the living-database workflow and its enforced rules --- README.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/README.md b/README.md index fb0c2ec..19ff2fd 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,49 @@ V0.1 scaffold per master spec. A retro frontier game that scopes Big Tech exposu ``` packages/ core/ Render-agnostic game logic, seed data, scoring + core/db/ The living database: schema, seeds, build + verify web/ React + Vite SPA (V1 funnel) server/ Minimal waitlist API (email + channel only) ``` +## The living database + +The database is the source of truth. The site is a view over it. Nothing in the UI may +hardcode a number that lives in `bigtech.db`. + +```bash +npm run db:build # rebuild the db, apply seeds, verify, regenerate the catalog +npm run db:verify # run the instrument's own checks against the existing db +``` + +`packages/core/db/bigtech.db` is **built, not committed**. What is committed is the part that +matters: `db/schema.sql`, `db/seed/*.sql`, and `db/build.mjs`. + +The build refuses to pass if a score breaks the instrument's own rules: + +- dimension weights must sum to 100 +- every stored `weighted_total` must recompute from its scores +- every grade must match its band +- every score must carry a written rationale +- no tier-4 claim may attach to a scored dimension +- the reproducible-build caps are enforced, not documented: no reproducible build caps + verifiability at 3, an experimental one at 6 + +A product with no assessment surfaces as `unassessed`. It is never given a guessed number. +That is why the 43 legacy roster entries sit in the database as placeholders and exactly one +product carries a real score. + +### Adding an assessment + +1. Write `packages/core/db/seed/000N-.sql` using the shape in `0001-signal.sql`. +2. Every score needs a `rationale` and at least three tier-1 or tier-2 `evidence` rows. +3. `npm run db:build`. If it fails, the report is not ready to publish. + +### What the numbers mean + +See the instrument spec. Scores are 0 to 100, and a weighted average is not the headline: the +weakest dimension is, because a 90 with a 5 on local data exposure is a 90 that will leak. + ## Quick start ```bash