@bongos/core 1.19.449 → 1.19.451

package/scripts/gds/land-watch.js

@@ -78,14 +78,21 @@ function removeBreadcrumb(fileOrId) {
 }
 
 // PURE decision — exported so the truth table is unit-tested with no fs/network.
-//   'emit' → the task has landed (shipped): render the shipped card, then clear.
-//   'drop' → give up watching: stale, OR it left the land path (grade-failed back to
-//            completed, released, …) so the confirmed→shipped transition won't happen.
+//   'emit' → the task landed inside the watch window: render the shipped card, then clear.
+//   'drop' → give up watching: past the window, OR it left the land path (grade-failed back
+//            to completed, released, …) so the confirmed→shipped transition won't happen.
 //   'keep' → still landing (confirmed), or a transient read failure — retry next turn.
-// emit wins over stale so a just-landed breadcrumb still shows even if old.
+//
+// The window wins over EVERY status, 'shipped' included (task 1003466). It used not to:
+// 'emit' was checked first, so a breadcrumb for a task that landed days ago still rendered a
+// "Shipped" banner. That went unnoticed until a dead publish-reconciler (task 1002419) let a
+// backlog build — eleven tasks flipped to shipped at once and the builder paid a prompt-turn
+// of stale news for each. A land the builder has already moved past is not news; it is spam.
+// An unknown/unparseable age is treated as past the window for the same reason: we cannot
+// prove the crumb is fresh, and the safe direction is always silence.
 function classifyLand(task, ageMs, { staleMs = DEFAULT_STALE_MS } = {}) {
+  if (!Number.isFinite(ageMs) || ageMs > staleMs) return 'drop';
   if (task && task.status === 'shipped') return 'emit';
-  if (typeof ageMs === 'number' && ageMs > staleMs) return 'drop';
   if (!task || typeof task.status !== 'string') return 'keep'; // couldn't read → retry
   if (task.status === 'confirmed') return 'keep';               // still landing
   return 'drop';                                                // no longer on the land path
@@ -126,21 +133,33 @@ function buildShippedEnvelope(crumb, task) {
 
 // Walk the breadcrumbs; emit AT MOST ONE shipped card per run (avoid flooding a turn),
 // dropping the give-ups. Returns the envelope to inject, or null. Deps injected for tests.
+//
+// The backlog drains in THIS pass (task 1003466): the newest land gets the card and every
+// other landed crumb is folded into one "also landed" line and cleared. Holding the extras
+// for later turns is what turned a backlog into a card per prompt — the builder had to ask
+// why the session kept showing cards instead of working.
 async function watch({ nowMs = Date.now(), staleMs = DEFAULT_STALE_MS, getTask = fetchTask, readCrumbs = readBreadcrumbs, removeCrumb = removeBreadcrumb } = {}) {
   const crumbs = readCrumbs().sort((a, b) => String(b.at).localeCompare(String(a.at))); // newest first
   let envelope = null;
+  const alsoLanded = [];
   for (const crumb of crumbs) {
-    const ageMs = nowMs - Date.parse(crumb.at || '') || 0;
+    const at = Date.parse(crumb.at || '');
+    const ageMs = Number.isFinite(at) ? nowMs - at : Infinity; // unparseable → past the window
     const task = await getTask(crumb.taskId);
-    const verdict = classifyLand(task, Number.isFinite(ageMs) ? ageMs : 0, { staleMs });
+    const verdict = classifyLand(task, ageMs, { staleMs });
     if (verdict === 'emit') {
-      if (!envelope) { envelope = buildShippedEnvelope(crumb, task); removeCrumb(crumb._file); }
-      // a 2nd shipped crumb waits for the next turn (one card at a time)
+      if (!envelope) envelope = buildShippedEnvelope(crumb, task);
+      else alsoLanded.push(crumb.taskId);
+      removeCrumb(crumb._file);
     } else if (verdict === 'drop') {
       removeCrumb(crumb._file);
     }
     // 'keep' → leave it
   }
+  // Written as `task N`, never `#N` — a bare #NNN autolinks to a GitHub issue and 404s.
+  if (envelope && alsoLanded.length) {
+    envelope.warnings = [`Also landed: ${alsoLanded.map((id) => `task ${id}`).join(', ')}.`];
+  }
   return envelope;
 }
 

package/scripts/hall-preview/server.js

@@ -232,6 +232,35 @@ app.get(/^\/([a-z-]+)$/, (req, res, next) => {
   if (!sendPage(res, `${req.params[0]}.html`)) next();
 });
 
+// What the READING ROOMS read (task 1003306): the two long-form documents and
+// the generated diagrams. All three live outside modules/hall-ui/public and are
+// served by serve-internal.js from docs/onboarding/ — but the hall's page gate
+// sits in front of them, so in the harness every one of those fetches 302'd to
+// sign-in and the primer could only ever be previewed in its FAILURE state and
+// the diagrams index with five broken images. Same gap task 1003305 closed for
+// the record pages' own routes. Served here, ahead of the gate, from the same
+// canonical files prod reads.
+// NEVER hand-edit a diagram: the .svg/.png pair and assertions.json are written
+// in lockstep by scripts/gds/gen-diagrams.js.
+// Both prefixes, and that is not belt-and-braces. The diagrams page references
+// its figures RELATIVELY (src="diagrams/01-….png"), which prod resolves under
+// /builders/diagrams because the page is served at /builders/diagrams; the
+// harness serves its pages at the root, so the same markup resolves at
+// /diagrams. Mount one and the populated page renders five broken images.
+for (const prefix of ['/builders/diagrams', '/diagrams']) {
+  app.use(prefix, express.static(path.join(ROOT, 'docs/onboarding/diagrams')));
+}
+for (const [route, file] of [
+  ['/builders/primer.md', 'docs/onboarding/primer.md'],
+  ['/builders/drachmae-and-karma.md', 'docs/onboarding/drachmae-and-karma.md'],
+]) {
+  app.get(route, (req, res, next) => {
+    const abs = path.join(ROOT, file);
+    if (!fs.existsSync(abs)) return next();
+    res.type('text/markdown; charset=utf-8').send(fs.readFileSync(abs, 'utf8'));
+  });
+}
+
 // Everything else — /builders/*.css|js assets, /lib/bongos-client.js, diagram
 // PNGs — falls through to the real internal-surface mounting. Our handlers
 // above registered first, so the hall's auth gates in there never fire for

package/src/module-api.js

@@ -33,7 +33,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.449'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.451'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/hall_audit.mjs

@@ -35,10 +35,11 @@ const INLINE_STYLE_BUDGET = {
   // task.html now carries none and passes on the default.)
   // (my-projects + scouting were carried here as standalone surfaces until task
   // 1002868 adopted them into the shell; their exceptions are gone with them.)
-  // Genuinely page-local, and already token-derived. One line over the default;
-  // a whole stylesheet for the legend strip is not worth the extra request, and
-  // diagram-viewer.css is shared with primer.html so it is the wrong home.
-  'diagrams.html': 16,
+  // (diagrams.html's 16-line legend + figure block was the hall's last inline
+  // style. Task 1003306 promoted it: the figure frame became the reading-room
+  // archetype's, shared with the primer, and the legend got diagrams.css — so
+  // the "not worth an extra request" reasoning stopped holding the moment the
+  // page needed a sheet anyway. No page carries an exception now.)
 };
 const DEFAULT_INLINE_BUDGET = 15;
 
@@ -150,18 +151,21 @@ test('the phone-width overflow guards are all still in place', () => {
     // top level, so finding one means the nearest @media is not the enclosing
     // one and the rule is really live everywhere.
     assert.ok(!/\n\}/.test(between), `${re} sits AFTER its nearest @media closed — it is live at every width`);
-    // Pin the EXACT breakpoint, not a band: style.css guards at 640, primer.css
-    // at 760 (its only breakpoint, the one primer.js's matchMedia mirrors).
-    // Narrowing primer's to 640 "for consistency" would silently reopen the
-    // 641–760px band the rule exists to cover, so a tolerant regex would hide
-    // the very drift this test is here to catch.
+    // Pin the EXACT breakpoint, not a band: style.css guards at 640, the
+    // reading room at 760 (its only breakpoint, the one primer.js's matchMedia
+    // mirrors). Narrowing the room's to 640 "for consistency" would silently
+    // reopen the 641–760px band the rule exists to cover, so a tolerant regex
+    // would hide the very drift this test is here to catch.
+    // The room's rule moved sheets in task 1003306 — primer.css → room.css,
+    // when the archetype was factored out for the diagrams index to share. The
+    // ASSERTION is unchanged; only the file it reads moved with the rule.
     assert.match(between, new RegExp(`max-width:\\s*${breakpoint}px`),
       `${re} must sit in the max-width: ${breakpoint}px media query`);
   };
   scoped(css, /:has\(>\s*\.ledger\)\s*\{[^}]*overflow-x:\s*auto/, 640);
   scoped(css, /\.ledger th\s*\{[^}]*position:\s*static/, 640);
   scoped(css, /\.rank-tip\s*\{\s*display:\s*none/, 640);
-  scoped(read('primer.css'), /\.primer-article table\s*\{[^}]*overflow-x:\s*auto/, 760);
+  scoped(read('room.css'), /\.primer-article table\s*\{[^}]*overflow-x:\s*auto/, 760);
 });
 
 // The strip has to hold BOTH invariants, and the second one is the easy one to

package/tests/hall_reading_world.mjs

@@ -0,0 +1,430 @@
+// tests/hall_reading_world.mjs — the READING ROOMS in the chrome world: the
+// primer, the diagrams index, the roadmap deck and the ranks ladder
+// (task 1003306, goal 1000081).
+//
+// tests/hall_tokens.mjs pins the TIER these pages spend, hall_board_world.mjs
+// pins how the board spends it and hall_record_world.mjs the record family;
+// this is the same job for the reading rooms. Everything here is a fact that is
+// SILENT in a browser: the page still renders, it just renders wrong, or it
+// renders right here and fails a floor on the reviewer's machine.
+//
+// What it locks:
+//   * THE PAGE-LOCAL `:root` STAYS GONE. roadmap.css declared one — the only
+//     one in the hall, and forbidden both ways: the branding pack's :root is
+//     spliced at the END of <head> at (0,1,0), so a page-local one is outranked
+//     one way and defeats re-branding the other. Page tokens live on `body`.
+//   * ONE MARKDOWN PARSER. primer.js carried its own copy of md-reader.js's
+//     grammar minus blockquotes, so every `> aside` in the primer silently
+//     collapsed into a paragraph. The copy is gone; the pin is that it stays
+//     gone AND that the room has a blockquote rule to render what now arrives.
+//   * THE SOFT GATE IS aria-disabled. A real `disabled` button leaves the tab
+//     order, so a keyboard reader can never land on the acknowledge control and
+//     never hears the note saying why it is locked.
+//   * THE `ch` TRAP. primer.css capped the article at `72ch` under a comment
+//     claiming 60-72 characters; a `ch` is the font's ZERO glyph and Manrope's
+//     is wide, so it rendered about 90. The measure is --measure, and it is
+//     spent on PROSE only — on a display heading it is the inverse mistake
+//     hall_record_world §8 pins.
+//   * THE DRIFT FALLBACKS. diagram-viewer.css carried eleven
+//     `var(--x, LITERAL)` pairs whose tokens all exist, so the literal never
+//     rendered and only encoded drift (its --ink fallback said #2a2a2a where
+//     the sheet ships #17181a). Plus two raw shadows and a hand-written
+//     z-index: 9999.
+//   * THE SCROLL LOCK IS ON THE ROOT. The diagram's fullscreen locked `body`
+//     where the shell's own drawer locks `html`. Two overlays locking one page
+//     on two different elements is how one of them stops working.
+//   * THE ONE h1, ON EVERY ROOM. All four pages had none — the finding
+//     ranks.states.json had been carrying in the open since task 1003320.
+//   * THE COMPAT ALIASES. Each re-skinned sheet's removal list. The aliases
+//     still EXIST for the pages nobody has re-skinned, so spending one here is
+//     legal CSS that quietly opts the sheet back out of the world.
+//
+// Reproduce the renders these came from. The floors run against the kit's own
+// stub; the POPULATED document needs the fixture harness, because neither the
+// primer markdown nor the generated diagrams are the kit stub's to serve:
+//   node modules/ui-design/kit/render.js --states modules/hall-ui/public/primer.states.json
+//   node scripts/hall-preview/server.js --port 4612 --fixture-me
+//   node modules/ui-design/kit/render.js --states modules/hall-ui/public/primer.states.json \
+//     --base-in http://builders.localhost:4612 --base-out http://builders.localhost:4612
+//   (likewise diagrams.states.json, roadmap.states.json, ranks.states.json)
+//
+// §10 leaves static analysis behind and RUNS md-reader.js in a vm: the parser
+// unification is a behaviour claim, and "primer.js no longer contains a
+// parser" only proves half of it. The other half is that the parser it now
+// calls emits what the primer's markdown needs.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HALL = path.join(ROOT, 'modules', 'hall-ui', 'public');
+const read = (f) => fs.readFileSync(path.join(HALL, f), 'utf8');
+
+const styleCss = read('style.css');
+const roomCss = read('room.css');
+const primerCss = read('primer.css');
+const diagramsCss = read('diagrams.css');
+const roadmapCss = read('roadmap.css');
+const viewerCss = read('diagram-viewer.css');
+const primerJs = read('primer.js');
+const viewerJs = read('diagram-viewer.js');
+const mdReaderJs = read('md-reader.js');
+const primerHtml = read('primer.html');
+const diagramsHtml = read('diagrams.html');
+const roadmapHtml = read('roadmap.html');
+const ranksHtml = read('ranks.html');
+
+const decomment = (css) => css.replace(/\/\*[\s\S]*?\*\//g, '');
+// The body of the first rule matching `selector {`, comments stripped. Naive on
+// purpose: these are flat declaration blocks, not nested at-rules. Takes a PLAIN
+// selector and escapes it here — pass a pre-escaped one and it is escaped twice.
+const rule = (css, selector) => {
+  const esc = selector.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const m = decomment(css).match(new RegExp(`(^|[},])\\s*${esc}\\s*\\{([^}]*)\\}`, 'm'));
+  return m ? m[2] : null;
+};
+
+// The sheets this task re-skinned. A sheet joins this list when its page family
+// lands, and never leaves it.
+const RESKINNED = [
+  ['room.css', roomCss],
+  ['primer.css', primerCss],
+  ['diagrams.css', diagramsCss],
+  ['roadmap.css', roadmapCss],
+  ['diagram-viewer.css', viewerCss],
+];
+
+// ---- 1. no page declares its own :root -------------------------------------
+
+test('no hall page sheet declares a :root of its own', () => {
+  const offenders = [];
+  for (const f of fs.readdirSync(HALL).filter((n) => n.endsWith('.css') && n !== 'style.css')) {
+    if (/(^|[},])\s*:root\s*\{/.test(decomment(read(f)))) offenders.push(f);
+  }
+  assert.deepEqual(offenders, [],
+    'the pack :root is spliced at the end of <head> — a page-local one is outranked one way and defeats re-branding the other. Put page tokens on body.');
+});
+
+test('roadmap.css puts its three helpers on the body, scoped to the page', () => {
+  const body = rule(roadmapCss, 'body[data-page="roadmap"]');
+  assert.ok(body, 'roadmap.css declares its tokens on body[data-page="roadmap"]');
+  for (const t of ['--rm-plan', '--rm-terra-weak']) {
+    assert.match(body, new RegExp(`${t}\\s*:`), `${t} survived the move to body`);
+  }
+  assert.doesNotMatch(decomment(roadmapCss), /--rm-shadow-soft/,
+    'v3 separates by TONE — a panel is never a drawn box and never a shadow');
+  assert.doesNotMatch(decomment(roadmapCss), /box-shadow\s*:\s*(?!inset)[^;]*(?:rgba|0 )/,
+    'no raw shadow came back with it');
+});
+
+test('the :root guard CATCHES a reintroduction and tolerates a lookalike', () => {
+  assert.match(decomment(':root { --x: 1px; }'), /(^|[},])\s*:root\s*\{/);
+  assert.doesNotMatch('html:root-ish { }', /(^|[},])\s*:root\s*\{/);
+});
+
+// ---- 2. the compat aliases are retired from the re-skinned sheets ----------
+
+const ALIASES = ['--surface', '--surface-2', '--border', '--border-strong', '--accent-weak', '--accent-text'];
+
+test('no re-skinned reading-room sheet spends a compat alias', () => {
+  const found = [];
+  for (const [name, css] of RESKINNED) {
+    for (const alias of ALIASES) {
+      // \b would match --surface inside --surface-2, so require the var() close
+      if (new RegExp(`var\\(\\s*${alias}\\s*[,)]`).test(decomment(css))) found.push(`${name}: ${alias}`);
+    }
+  }
+  assert.deepEqual(found, [],
+    'the aliases exist for pages nobody has re-skinned; spending one here quietly opts the sheet back out of the world');
+});
+
+test('the ranks page section of style.css spends the real names too', () => {
+  const card = rule(styleCss, '.rank-card');
+  assert.ok(card, '.rank-card has a rule');
+  for (const alias of ALIASES) {
+    assert.doesNotMatch(card, new RegExp(`var\\(\\s*${alias}\\s*[,)]`), `.rank-card no longer spends ${alias}`);
+  }
+  assert.match(card, /border:\s*var\(--line\)\s+solid\s+transparent/,
+    'the edge is reserved as transparent so a modifier can draw one — collab.css\'s .btn--quiet is the precedent');
+});
+
+test('the alias guard would CATCH --surface without matching --surface-2', () => {
+  const re = new RegExp('var\\(\\s*--surface\\s*[,)]');
+  assert.ok(re.test('background: var(--surface);'));
+  assert.ok(!re.test('background: var(--surface-2);'));
+});
+
+// ---- 3. --measure is the BODY measure, and nothing else --------------------
+
+test('the room measures PROSE, and lets a table, a figure and a code block run wider', () => {
+  const measured = decomment(roomCss).match(/\.primer-article\s*>\s*p,[\s\S]*?\{([^}]*)\}/);
+  assert.ok(measured, 'room.css caps the prose children explicitly, not the card');
+  assert.match(measured[1], /max-width:\s*var\(--measure\)/);
+  const article = rule(roomCss, '.primer-article');
+  assert.ok(article, '.primer-article has a rule');
+  assert.doesNotMatch(article, /max-width/,
+    'the CARD is not capped at the measure — a table and a diagram may take its whole width');
+});
+
+test('no reading sheet does fresh `ch` arithmetic in prose', () => {
+  for (const [name, css] of RESKINNED) {
+    // A `ch` is the ZERO glyph's width, not a character: primer.css's 72ch
+    // rendered ~90. --measure was measured; a fresh number is a guess.
+    const hits = [...decomment(css).matchAll(/max-width:\s*(\d+(?:\.\d+)?)ch/g)].map((m) => m[0]);
+    assert.deepEqual(hits, [], `${name} caps a measure in raw ch — spend var(--measure)`);
+  }
+});
+
+test('the room head takes the display voice, and NOT the body measure', () => {
+  const h = rule(styleCss, '.page-head--room .page-head__h');
+  assert.ok(h, '.page-head--room .page-head__h has a rule');
+  assert.match(h, /font-family:\s*var\(--font-display\)/);
+  assert.doesNotMatch(h, /var\(--measure\)/,
+    '--measure is the BODY measure; on a display line it caps near 950px and the title runs the column');
+  const sub = rule(styleCss, '.page-head--room .page-head__sub');
+  assert.match(sub, /max-width:\s*var\(--measure\)/, 'the sub IS body prose, so it takes the measure');
+});
+
+// ---- 4. the room's one breakpoint is 760, and the script mirrors it --------
+
+test('the room and primer.js agree on 760px, exactly', () => {
+  assert.match(decomment(roomCss), /@media\s*\(max-width:\s*760px\)/,
+    'the room keeps its own breakpoint — narrowing it to the shell\'s 640 reopens the 641-760 band');
+  assert.match(primerJs, /matchMedia\('\(max-width:\s*760px\)'\)/,
+    'primer.js closes the contents at the same width the sheet collapses them');
+  assert.doesNotMatch(decomment(roomCss), /@media\s*\(max-width:\s*640px\)/,
+    'a second, narrower breakpoint in the room is the drift hall_audit exists to catch');
+});
+
+// ---- 5. one markdown parser -----------------------------------------------
+
+test('primer.js carries no parser of its own any more', () => {
+  for (const gone of ['function parseMarkdown', 'function splitTableRow', 'function renderInline', 'function slugify', 'function escapeHtml']) {
+    assert.ok(!primerJs.includes(gone),
+      `primer.js still defines ${gone} — that copy is md-reader.js's, and the copy is what dropped blockquotes`);
+  }
+  assert.match(primerJs, /window\.OTBMdReader/, 'primer.js renders through the shared reader');
+  assert.match(primerJs, /MD\.parseMarkdown\(md,\s*resolveLinkHref\)/, 'and passes its own link resolver into it');
+});
+
+test('primer.html loads the reader BEFORE the page script', () => {
+  // Positions of the SCRIPT TAGS, not of the filenames: the page's own comments
+  // name both files, and an indexOf over the raw HTML finds the prose first.
+  const srcs = [...primerHtml.matchAll(/<script[^>]+src="([^"?]+)/g)].map((m) => m[1]);
+  const reader = srcs.indexOf('/builders/md-reader.js');
+  const page = srcs.indexOf('/builders/primer.js');
+  assert.ok(reader > -1, 'primer.html loads md-reader.js');
+  assert.ok(reader < page, 'both are deferred, so document order is execution order — the reader has to be first');
+});
+
+test('the primer keeps the one rewrite that is its own', () => {
+  assert.match(primerJs, /drachmae-and-karma\.md.*\/builders\/drachmae/s,
+    'the economy doc has an in-hall reader page (task 1472); a link to it must stay in the hall, not bounce to GitHub');
+  assert.match(primerJs, /baseDir:\s*PRIMER_DIR/, 'and resolves its relative links against docs/onboarding/');
+});
+
+test('the room styles what the shared parser emits that the old copy never did', () => {
+  assert.match(mdReaderJs, /<blockquote>/, 'md-reader.js emits blockquotes');
+  const bq = rule(roomCss, '.primer-article blockquote');
+  assert.ok(bq, 'and the room has a rule for them — the pair IS the fix; either half alone is a silent no-op');
+  assert.match(bq, /var\(--glass\)/);
+});
+
+test('primer.js still injects the diagrams — the one parser-adjacent job that is the primer\'s', () => {
+  assert.match(primerJs, /function inlineDiagrams/);
+  assert.match(primerJs, /DIAGRAM_AT_HEADING/);
+  assert.match(primerJs, /fig\.className = 'primer-figure'/,
+    'the injected figure takes the class diagram-viewer.js upgrades and room.css frames');
+});
+
+// ---- 6. the soft gate is reachable ----------------------------------------
+
+test('the acknowledge gate is aria-disabled, never disabled', () => {
+  assert.match(primerHtml, /id="primer-ack-btn"[^>]*aria-disabled="true"/,
+    'a real disabled button leaves the tab order, so a keyboard reader never hears why it is locked');
+  assert.doesNotMatch(primerHtml, /id="primer-ack-btn"[^>]*\sdisabled(?:[=\s>])/, 'and carries no hard disabled attribute');
+  assert.doesNotMatch(primerJs, /btn\.disabled\s*=/, 'nor does the script set one');
+  assert.match(primerJs, /setAttribute\('aria-disabled'/, 'the lock is the aria state');
+  const locked = rule(primerCss, '.primer-ack__btn[aria-disabled="false"]');
+  assert.ok(locked, 'the sheet paints the OPEN state off the same attribute the script writes');
+  assert.match(locked, /background:\s*var\(--accent\)/, 'the accent lights only what is pressable');
+});
+
+test('the locked note is described to the control while it is locked, and dropped when it opens', () => {
+  assert.match(primerHtml, /aria-describedby="primer-ack-note-locked"/);
+  assert.match(primerJs, /removeAttribute\('aria-describedby'\)/,
+    'a note explaining a lock that is gone describes nothing');
+});
+
+// ---- 7. the diagram viewer -------------------------------------------------
+
+test('diagram-viewer.css carries no fallback for a token that cannot be missing', () => {
+  const hits = [...decomment(viewerCss).matchAll(/var\(\s*--[a-z-]+\s*,[^)]+\)/g)].map((m) => m[0]);
+  assert.deepEqual(hits, [],
+    'every one of these tokens ships in style.css, so the literal never rendered — it only encoded drift (the --ink fallback said #2a2a2a where the sheet ships #17181a)');
+});
+
+test('the viewer spends the named z rung, not a hand-written 9999', () => {
+  const full = rule(viewerCss, '.dgv.is-fullscreen');
+  assert.ok(full, '.dgv.is-fullscreen has a rule');
+  assert.match(full, /z-index:\s*var\(--z-diagram-full\)/);
+  assert.doesNotMatch(decomment(viewerCss), /z-index:\s*\d/, 'no bare number is left in the sheet');
+  assert.match(decomment(styleCss), /--z-diagram-full:\s*\d+/, 'and the rung is named in the shell ladder');
+});
+
+test('the fullscreen scroll lock is on the root, where the shell already locks', () => {
+  assert.match(decomment(viewerCss), /html\.dgv-fullscreen-open\s*\{\s*overflow:\s*hidden/);
+  assert.doesNotMatch(decomment(viewerCss), /body\.dgv-fullscreen-open/);
+  assert.match(viewerJs, /document\.documentElement\.classList\.toggle\('dgv-fullscreen-open'/,
+    'the script writes the class where the sheet reads it — the shell\'s own drawer uses html.drawer-open');
+  assert.match(decomment(styleCss), /html\.drawer-open/, 'and that is the convention it is matching');
+});
+
+test('the room frames BOTH figures the viewer upgrades', () => {
+  assert.match(viewerJs, /figure\.diagram img, figure\.primer-figure img/,
+    'one selector, two classes — the viewer has always treated them as one object');
+  const frame = decomment(roomCss).match(/\.primer-figure,\s*figure\.diagram\s*\{([^}]*)\}/);
+  assert.ok(frame, 'and the room frames them in one rule, so they cannot drift apart');
+  assert.match(frame[1], /var\(--glass\)/);
+  // the canvas is inserted INSIDE the figure, so exactly one of the two draws
+  // the frame or the diagram lands in nested boxes
+  const inner = decomment(roomCss).match(/\.primer-figure \.dgv,\s*figure\.diagram \.dgv\s*\{([^}]*)\}/);
+  assert.ok(inner, 'the inserted canvas gives up its own frame');
+  assert.match(inner[1], /border:\s*0/);
+});
+
+// ---- 8. every room has exactly one h1 -------------------------------------
+
+const ROOMS = [['primer.html', primerHtml], ['diagrams.html', diagramsHtml], ['roadmap.html', roadmapHtml], ['ranks.html', ranksHtml]];
+
+// An HTML comment that mentions <h1> is prose, not markup — and these pages each
+// carry one explaining why the heading is there at all.
+const dehtmlcomment = (html) => html.replace(/<!--[\s\S]*?-->/g, '');
+
+test('every reading room renders exactly one h1, and it is the page head\'s', () => {
+  for (const [name, html] of ROOMS.map(([n, h]) => [n, dehtmlcomment(h)])) {
+    const h1s = [...html.matchAll(/<h1\b/g)];
+    assert.equal(h1s.length, 1, `${name} has exactly one <h1> — one-header-main-h1 measures the rendered DOM, not the happy path`);
+    assert.match(html, /<h1 class="page-head__h">/, `${name}'s h1 is the page head's`);
+  }
+});
+
+test('the three DOCS rooms take the room voice; the deck takes the board\'s', () => {
+  for (const [name, html] of [['primer.html', primerHtml], ['diagrams.html', diagramsHtml], ['ranks.html', ranksHtml]]) {
+    assert.match(html, /class="page-head page-head--room"/, `${name} is a reading room`);
+    assert.match(html, /class="page-head__eyebrow"/, `${name} carries the room's eyebrow`);
+  }
+  assert.match(roadmapHtml, /class="page-head page-head--board"/,
+    'the roadmap is a working surface whose figures are the thing to look at, so its own name stays quiet');
+});
+
+test('the document\'s own h1 is suppressed, or the article would render a second one', () => {
+  const h1 = rule(roomCss, '.primer-article h1');
+  assert.ok(h1, 'room.css handles the markdown h1');
+  assert.match(h1, /display:\s*none/);
+});
+
+// ---- 9. the archetype's shape ---------------------------------------------
+
+test('the room opts in from its markup, and the archetype sheet is what carries it', () => {
+  for (const [name, html] of [['primer.html', primerHtml], ['diagrams.html', diagramsHtml]]) {
+    assert.match(html, /<body class="room[^"]*"/, `${name} opts into the room`);
+    assert.match(html, /href="\/builders\/room\.css"/, `${name} loads the archetype`);
+  }
+  const tokens = rule(roomCss, 'body.room');
+  assert.ok(tokens, 'the room\'s composition tokens are on the opt-in body class');
+  assert.doesNotMatch(tokens, /--measure\s*:/,
+    'the measure is NOT redeclared: a ch scales with the font size, so one measured token reads the same at 15px and 17px');
+});
+
+test('the room\'s panels are the shell\'s three card levels, not a fourth', () => {
+  for (const id of ['primer-article', 'primer-skeleton', 'primer-error', 'primer-ack']) {
+    assert.match(primerHtml, new RegExp(`class="[^"]*scroll"[^>]*id="${id}"|id="${id}"[^>]*class="[^"]*scroll"`),
+      `#${id} is the shell's .scroll — v3 has exactly three card levels and a fourth is a design decision, not a local override`);
+  }
+});
+
+test('no page sheet reaches into shell layout', () => {
+  for (const [name, css] of RESKINNED) {
+    assert.doesNotMatch(decomment(css), /\.app-content\s*>\s*main/,
+      `${name} overrides shell layout — the rule tests/hall_record_world.mjs pins`);
+  }
+});
+
+test('no reading room carries an inline <style>, and none needs an audit exception', () => {
+  const withStyle = ROOMS.filter(([, html]) => /<style[^>]*>[\s\S]*?\S[\s\S]*?<\/style>/.test(html)).map(([n]) => n);
+  assert.deepEqual(withStyle, [],
+    'diagrams.html held the hall\'s last SUBSTANTIVE one — 16 lines, one over the default budget, with its own hall_audit exception. The exception retired with it.');
+  const audit = fs.readFileSync(path.join(ROOT, 'tests', 'hall_audit.mjs'), 'utf8');
+  const budgets = audit.match(/const INLINE_STYLE_BUDGET = \{([\s\S]*?)\};/);
+  assert.ok(budgets, 'hall_audit.mjs still declares the ratchet');
+  assert.doesNotMatch(budgets[1].replace(/\/\/[^\n]*/g, ''), /['"][a-z-]+\.html['"]\s*:/,
+    'no page carries an inline-style exception any more');
+  // (scouting.html keeps a one-line block, comfortably inside the DEFAULT
+  // budget — an exception is what this asserts is gone, not every <style>.)
+});
+
+test('roadmap\'s two sub-24px controls clear the floor, on both axes', () => {
+  const t = rule(roadmapCss, '.rm-goal__t');
+  assert.ok(t, '.rm-goal__t has a rule');
+  assert.match(t, /min-height:\s*24px/, 'measured 20px: a 13px line box in a 7px row');
+  const more = rule(roadmapCss, '.rm-gmore');
+  assert.ok(more, '.rm-gmore has a rule');
+  assert.match(more, /min-height:\s*24px/, 'measured 19px');
+  // the WIDTH half is the one that gets missed: at 320 the four fixed items in
+  // the row ate it and `flex: 1; min-width: 0` resolved the title to 0x26
+  assert.match(decomment(roadmapCss), /@media\s*\(max-width:400px\)[\s\S]*?\.rm-goal__t\s*\{[^}]*flex:\s*1 0 100%/,
+    'and the row wraps before the title can resolve to zero width');
+});
+
+// ---- 10. the parser, actually run -----------------------------------------
+
+// md-reader.js is a browser IIFE that only touches `window` and `location`, so
+// a two-property sandbox is the whole DOM it needs.
+function loadReader() {
+  const sandbox = { window: {}, location: { hostname: 'builders.example.com', href: 'https://builders.example.com/primer' } };
+  vm.createContext(sandbox);
+  vm.runInContext(mdReaderJs, sandbox, { filename: 'md-reader.js' });
+  return sandbox.window.OTBMdReader;
+}
+
+test('the shared parser renders the blockquote the primer\'s old copy dropped', () => {
+  const MD = loadReader();
+  const { html } = MD.parseMarkdown('> a note the primer used to lose\n', (h) => h);
+  assert.match(html, /<blockquote><p>a note the primer used to lose<\/p><\/blockquote>/);
+});
+
+test('it slugs h2s the way the table of contents and the in-doc anchors expect', () => {
+  const MD = loadReader();
+  const { html, headings } = MD.parseMarkdown('## The claim → ship lifecycle\n', (h) => h);
+  assert.equal(headings.length, 1);
+  assert.equal(headings[0].level, 2);
+  assert.equal(headings[0].id, MD.slugify('The claim → ship lifecycle'));
+  assert.match(html, new RegExp(`<h2 id="${headings[0].id}">`),
+    'the anchor in the markup and the id the TOC links to come from one call, so they cannot drift');
+});
+
+test('the primer\'s link resolver sends a repo-relative doc to GitHub and leaves the rest alone', () => {
+  const MD = loadReader();
+  const resolve = MD.makeResolveLinkHref({
+    baseDir: 'docs/onboarding/',
+    getBlobBase: () => 'https://github.com/o/r/blob/main',
+    getTreeBase: () => 'https://github.com/o/r/tree/main',
+  });
+  assert.equal(resolve('../../CLAUDE.md'), 'https://github.com/o/r/blob/main/CLAUDE.md');
+  assert.equal(resolve('../recipes/'), 'https://github.com/o/r/tree/main/docs/recipes');
+  assert.equal(resolve('#a-section'), '#a-section', 'an in-page anchor is left alone');
+  assert.equal(resolve('https://example.com/x'), 'https://example.com/x', 'so is an absolute URL');
+  assert.equal(resolve('diagrams'), '/builders/diagrams', 'and the diagrams index stays in the hall');
+});
+
+test('with no repo bases the resolver degrades instead of crashing the page', () => {
+  const MD = loadReader();
+  const resolve = MD.makeResolveLinkHref({ baseDir: 'docs/onboarding/' });
+  assert.equal(resolve('../../CLAUDE.md'), '../../CLAUDE.md',
+    'the bases are fetched at boot; before they land a relative href passes through and 404s harmlessly');
+});