From 5353ed5b51c468c04ee64eb8496f438d1f1c721a Mon Sep 17 00:00:00 2001 From: doxa-maps Date: Tue, 22 Sep 2026 04:25:25 +0000 Subject: [PATCH] Document every standalone gate, and fix the two that were already failing 26 gates live outside build:unlocked; only nine were listed in reference.md. An inheritor reads that table as the list of what to run before publishing, so seventeen checks were effectively invisible -- including the three that caught the most defects this flight: catalog-currency, smoke:embeds and verify:map-paint. The cost was already being paid. Two unlisted gates were RED, and had been for two sessions: check:quoted-scripts the doc quoted a build chain missing the check:descriptions step added two ticks ago check:capability-exemplars the generated tier table predated golden-path-check Neither is a product defect -- both gates were working exactly as designed, comparing documentation against machine truth. Nobody ran them. That is the failure mode a standalone gate has by construction, and the table is the only mechanism that prevents it. Fixed both (doc updated to match package.json; exemplars regenerated to 27 rows), then filled the table to 25 of 26 -- the one omission is an alias for a script already listed. Each new row states what the gate catches and, for the ones that cannot live in the build, why. Corrected a number mid-edit: I first wrote "nineteen gates" from an earlier tally that had excluded the regenerator helpers. Measured again: 26. --- .../README-SECTION-3-cli-commands.md | 2 +- .../reference-capability-exemplars.md | 3 ++- documentation/reference.md | 26 +++++++++++++++++++ 3 files changed, 29 insertions(+), 2 deletions(-) diff --git a/documentation/README-SECTION-3-cli-commands.md b/documentation/README-SECTION-3-cli-commands.md index 88d18d4d9..89a914514 100644 --- a/documentation/README-SECTION-3-cli-commands.md +++ b/documentation/README-SECTION-3-cli-commands.md @@ -25,7 +25,7 @@ The scripts these commands are grounded in (from this branch's `package.json`): // claiming to be ground truth, and this one had silently stopped being it. "dev": "bun x vite", "build": "bash internal/build-lock.sh", -"build:unlocked": "bun run check:template-literal && bun run clean && bun run token && for d in plugin-designs/*/; do BUNDLE=$(basename \"$d\") bun x vite build || exit 1; done && bun run tree && bun run check:drop && bun run check:parse && bun run verify && bun run check:sri && bun run check:public-hygiene && bun run check:label-joins && bun run gallery", +"build:unlocked": "bun run check:template-literal && bun run clean && bun run token && for d in plugin-designs/*/; do BUNDLE=$(basename \"$d\") bun x vite build || exit 1; done && bun run tree && bun run check:drop && bun run check:parse && bun run verify && bun run check:sri && bun run check:public-hygiene && bun run check:label-joins && bun run check:descriptions && bun run gallery", "preview": "bun x vite preview", "serve": "python3 -m http.server 4173 --bind 0.0.0.0 --directory public", "cap:sync": "./node_modules/.bin/cap sync android", diff --git a/documentation/reference-capability-exemplars.md b/documentation/reference-capability-exemplars.md index 86807cd69..fbd594c5a 100644 --- a/documentation/reference-capability-exemplars.md +++ b/documentation/reference-capability-exemplars.md @@ -13,7 +13,7 @@ > bundle `parameterized` (cap-2) no matter how light it looks, and a `meta.json` `type` > declares tiers 3/4/5. -Generated from 17 bundle(s). +Generated from 18 bundle(s). ## Capability 1 — single-element @@ -25,6 +25,7 @@ Generated from 17 bundle(s). | `cities-internet` | `data-tables` | `single` | | `country-posters` | `countries-map` | `single` | | `country-posters` | `country-poster-wall` | `single` | +| `golden-path-check` | `golden-path-check` | `single` | | `gospel-resources` | `charts` | `single` | | `gospel-resources` | `data-tables` | `single` | | `gospel-resources` | `resources-list` | `single` | diff --git a/documentation/reference.md b/documentation/reference.md index 0c7989029..e9c16fde3 100644 --- a/documentation/reference.md +++ b/documentation/reference.md @@ -228,6 +228,32 @@ so running it inside the build would make it unfalsifiable. Run them before publ | `bun run check:done-evidence` | a backlog card marked `done` with no bluf **and** no fields — a status word the next team cannot reconcile against the code | reads `_qa-cycle/`, which is not in any repo CI clones | | `bun run verify:gate1` | the Gate-1 chain end-to-end against LIVE data: header filter → composite props → real grid re-filter → count back up | needs network; it is an acceptance test, not a build step | | `bun run check:catalog-identity` | the live server serving something **other than** the catalog — a stale CDN copy, a half-finished publish, or the login wall. Hashes each live bundle and compares sha384 against the manifest's own `integrity` | needs network egress, which CI cannot guarantee; it SKIPs when unreachable, and only "reached and wrong" fails | +| `bun run check:catalog-currency` | the live catalog being **an older build** than yours (identity passes on a catalog three publishes behind), **and** a locally-built bundle that is **absent** from the catalog — the "nothing was lost in the merge" guarantee | needs network egress; SKIPs when the catalog cannot be reached at all, because an offline box must not fail a build | +| `bun run smoke:embeds` | an element that **builds, lists in the manifest, and renders nothing** — a thrown `setup()` removes the subtree silently, so every build-time gate still passes. Mounts every profile page and asserts real shadow content | needs a browser; CI has none | +| `bun run verify:map-paint` | a map that **lays out but never paints** — Mapbox creates a full-size `` and only *then* tries for a GL context, so "canvas is 1440×900" is evidence of layout, never of paint. Asserts a live GL context + attribution | needs a browser **launched with the SwiftShader flags** (the MCP/default browser here has no GL at all) | +| `bun run verify:5-caps` | a capability tier that no longer has a working exemplar — the 5×5 product claim going stale | needs a browser + a Mapbox token | +| `bun run check:quoted-scripts` | a **doc that quotes a command which has since changed** — an omitted step in a quoted chain is invisible: there is no wrong character to notice, just a check the reader believes is in the chain | compares docs against `package.json`; cheap, but it guards documentation rather than build output | +| `bun run check:capability-exemplars` | `documentation/reference-capability-exemplars.md` drifting from the manifest's real tiers (regenerate with `bun run capability-exemplars`) | the table is generated *from* the manifest, so running it mid-build would compare a file against the thing that just wrote it | +| `bun run check:settled` | measuring or publishing a tree **mid-build** — a build's `clean` step `rm -rf`s `public/doxa-maps`, so samples taken seconds apart give opposite answers | it exists to be run *around* builds, not inside one | + +The rest, grouped by what they guard — same rule (outside the build, run before publishing): + +| Script | Catches | +|---|---| +| `bun run smoke` · `bun run smoke:gallery` · `bun run smoke:share` | the gallery page, the playground, and share-link round-tripping — each needs a browser | +| `bun run check:a11y-button-names` | an icon-only control with no accessible name (needs a browser to read the computed name) | +| `bun run check:capability-citations` | the README claiming a capability the manifest does not back | +| `bun run check:dxlife` | **any edit to the read-only DX-life clone** — the standing law that tree is never written | +| `bun run check:mobile` · `bun run check:tauri` · `bun run check:wp-embed` | the Capacitor sync, the Tauri config contract, and the WordPress PHP embed — deploy methods 2, 5 and 4 | +| `bun run verify:full` | the research corpus end-to-end | + +> **★ A STANDALONE GATE ONLY FIRES IF SOMEONE REMEMBERS IT — so this table IS the mechanism.** +> Measured 2026-09-22: **26** gates live outside `build:unlocked`; only **nine** were listed here. Two +> of the unlisted ones (`check:quoted-scripts`, `check:capability-exemplars`) were already FAILING, +> and had been for two sessions, because a build step and a bundle were added without their docs +> being regenerated. Nothing was broken in the product — the gates were doing their job — but nobody +> ran them, because an inheritor reads this table as the list of what to run before publishing. +> **An undocumented standalone gate is indistinguishable from one that does not exist.** **Why SRI and not an HTTP status.** `https://nuxtbase.app/app/doxa-maps/manifest.json` returns **200** and is a 2,872-byte HTML **sign-in page** — the app-shell login wall. A status check reads that as