7d6a23be53
The search box was never tested this flight, so it was checked: it finds groups by
people-group name, by language name and by ISO code, and shows its empty state for a
query that matches nothing. "Pashtun" returns 8 of 13 matches, "deu" 8 of 27, "Uab Meto"
2, and a nonsense string gives "Nothing matches that name, language or code." No defect,
so nothing in the product changed.
Finding it healthy took two attempts, and the first attempt is the point. It queried
invented selectors — .gm-sug, .gm-hit — got 0 results for every query including valid
ones, and would have reported a working search as broken. The real class is .gm-qrow,
and it is in the component.
That is the third time in this flight one probe produced a confident wrong verdict from
a guessed selector or a guessed denominator, and it has gone wrong in both directions:
- a table probe read the page's own "234 rows" caption and PASSED an entirely empty
body, because the document was missing its columns block;
- a charts probe FAILED a correct chart by counting all 5,563 catalogue codes when the
chart counts the 5,067 languages spoken by a pin;
- this one.
The existing selector row in the pitfalls table is about Shadow DOM not piercing, which
is a different failure. This one is added beside it: read the selector and the
denominator out of the source, assert on rendered content rather than on a number the
page prints about itself, and grep the component for the real class names first.
7.8 KiB
AGENT BRIEF — read this once, then build
If you were dispatched to this repo, read this file first. It replaces the wall of environment rules that used to be pasted into every spawn prompt. Your prompt should now be short: what to build, which files you own, and the one assertion that would prove it.
Why this file exists: measured 2026-09-23 — agents produced 21 report docs totalling 2,079 lines and 27 scratch probes against a handful of product commits, because each spawn prompt made proving the job and building the side effect. Every agent also re-derived the same environment from scratch. That discovery tax is now paid once, here.
The rule that matters most
Ship a commit, then write two sentences. Not the reverse. The artifact is the diff. A long, honest report attached to no commit is the failure mode this file exists to end.
Push it. A local commit is invisible — the Driver runs a laptop watcher against the Forgejo repo
and sees changes in his browser from that repo. Work that stops at git commit is not delivered.
TOKEN="$(pass show vivarium/forgejo-certified-sandbox | head -1)"
git -c http.postBuffer=524288000 \
push "https://oauth2:${TOKEN}@git.nuxtbase.app/doxa-life/doxa-maps.git" HEAD:doxa-maps-plugin-studio \
2>&1 | sed "s/${TOKEN}/[REDACTED]/g"
unset TOKEN
Never echo the token; always filter output through sed; never let it reach .git/config.
★ PUSH TO main TOO, once your change is verified. The Driver's laptop dev-server watches
main, not the working branch — so work pushed only to doxa-maps-plugin-studio is invisible
to him no matter how well it was tested. That is how 287 commits accumulated without him seeing a
single one.
git -c http.postBuffer=524288000 \
push "https://oauth2:${TOKEN}@git.nuxtbase.app/doxa-life/doxa-maps.git" HEAD:main \
2>&1 | sed "s/${TOKEN}/[REDACTED]/g"
Only push to main what you have actually verified — it is the branch a human is looking at.
Do not run the full build
bun run build takes minutes, and its first step deletes public/doxa-maps/ — which wipes the
output every other agent is using. Use the dev server; it hot-reloads.
This is now ENFORCED, not just asked. bun run build refuses with exit 75 unless you set
BUILD_ALLOW=1. If you hit that refusal it is telling you the truth — take one of the cheaper
paths it prints rather than reaching for the flag. Only the coordinator, running the single
authoritative build for a wave, should set it. This rule was documented here before it was
enforced and got violated anyway, by a dispatch prompt that said bun run build while telling the
agent to read this file first. An explicit instruction beats a standing rule at the point of work,
so the build now refuses instead of asking.
bun x vite --port <YOUR OWN PORT> --strictPort # e.g. 5299, 5399, 5499 …
BUNDLE=<name> bun x vite build # one bundle's compiled output; does NOT clean
--strictPort is mandatory. Vite silently moves to the next free port otherwise, and five gates
have 5173 hardcoded (check-facet-changes-map, plugin-gallery-smoke, smoke-studio,
generate-gallery, check-scrim-covers-viewport) — so a drifted server makes a gate talk to
somebody else's page and report a confident wrong answer with no error.
Before you believe a measurement
| Symptom | Check this first |
|---|---|
| "it didn't mount" / "0 elements" | bun run check:sri — a single-bundle build leaves stale SRI in leaf pages and the browser then refuses to execute the script. Looks identical to a mount failure. |
| bundles missing, files deleted, counts wrong | bun run check:settled — graded by exit code. It reads the build lock, which knows the queue; pgrep samples an instant and will tell you 0 builders while one is queued. |
| a gate "failed" | Re-run it un-suppressed. A command killed by a short timeout is not a failure, and these gates print teaching prose after the verdict, so ` |
| a selector finds nothing in a composite | Shadow DOM does not pierce. Use a recursive shadowRoot walker, not document.querySelector. |
| a probe's verdict, in EITHER direction | Read the selector and the denominator out of the source; never invent them. An invented selector fails a working feature, and a count the page prints about itself passes a broken one. Measured three times in one flight: .gm-sug returned 0 for every search query while search worked fine; a chart was "wrong" only because the probe counted all 5,563 catalogue codes when the chart counts the 5,067 spoken by a pin; and a table probe read its own "234 rows" caption and passed an entirely empty body. Assert on rendered content — rows and cells — and grep the component for the real class names first. |
Facts that are easy to get wrong
- This box HAS working WebGL via SwiftShader —
verify:map-paintpasses 11/11 with live GL at 1280×800. Any instruction saying "this VPS has NO WebGL" is stale; you may assert painted canvases and real zoom. Launch flags are ininternal/verify-map-paint.mjs. - Playwright must run from inside this repo —
node_modulesis here; a script in/tmpcannot resolve it. serve-stricttakes--directory, not--root, and returns 404 for a directory URL by design (production parity). Ask for/index.htmlexplicitly.pray.doxa.lifeneeds a browser User-Agent from scripts; a default script UA gets 403.root-dx-lifeis a READ-ONLY clone and not even a git repo — zero edits, ever, no safety net.- Scratch files go in
_qa-cycle/, never in this repo.
House style
- Material LIGHT only:
#f3f3f1surface ·#fff·#3b463dtext ·#92b195accent ·#d1d4cdborder ·#6d766emuted. No dark mode, noprefers-color-scheme: dark. - No backticks inside shadow-CSS template literals — this broke the build twice. Use string
concatenation:
'.x{display:block}' + '.y{…}'. - Keep both synced CSS copies byte-identical (
check:synced-css). - Every visible button needs an accessible name (
check:a11y-button-names). - Imitate before innovate. Where DX-life's designer already made a decision — radii, spacing, type scale, colours — port it faithfully rather than substituting our tokens.
- Commit messages are product-only: no AI or authorship trailers.
How much verification is enough
Size it to the blast radius. This is a judgement, and over-verifying is a real cost, not a virtue:
| Change | Prove it with |
|---|---|
| one bundle's own CSS / copy | the dev server + a screenshot you actually read |
| one bundle's logic | a unit-style assertion on the function, or one browser check |
anything in library/ |
name every consumer (grep) and re-check at least two of them — a change here reaches every bundle |
| layout / scroll / wheel behaviour | the three-clause conjunction, via bun run check:fits-screen |
State the one assertion that would falsify your change, run it, and report the number. You do not owe a complete audit.
★ Read the image when the deliverable is visual. Numbers have certified visually broken output in this repo more than once — a green generator is not a look-at-it.
Where the hard-won knowledge lives
Read these only when they bear on your task; do not read them all:
_qa-cycle/02-builder-cycle/lessons-learned.json— stories with costs attached_qa-cycle/02-builder-cycle/anti-patterns.json— smells to avoid_qa-cycle/02-builder-cycle/best-practices.json— practices that proved themselves_qa-cycle/01-ideation-research/VISION-the-seven-plugins-are-one-argument.md— what the product is for, and why the dashboard is deliberately shorter than a viewport