explico 0.3.0 → 0.5.0

package/src/reference/consistency.ts

@@ -22,6 +22,10 @@
  *   (h) operator-explained           a named operator a lesson uses is on the
  *                                     shipped/course operator allowlist or
  *                                     carries a notation entry (rule N8)
+ *   (i) roman-label-explained        a `\mathrm{…}` multi-letter label a lesson
+ *                                     uses is on the shipped/course roman-label
+ *                                     allowlist or carries a notation entry
+ *                                     (rule N10)
  *
  * Check (d) — the committed per-lesson resolution report — lives in
  * `src/content/resolution-report.ts`.
@@ -30,12 +34,14 @@
 import type {
   CourseConventions,
   CourseOperators,
+  CourseRomanLabels,
 } from '../compiler/course-config';
 import type { CurriculumCatalog } from '../curriculum/validation';
 import type { NotationSpec } from '../compiler/collections';
 import type { LintIgnore } from './lint-ignore';
 import { effectiveOperatorAllowlist } from './base-operators.mjs';
-import { collectOperators } from './math-glyphs.mjs';
+import { effectiveRomanLabelAllowlist } from './base-roman-labels.mjs';
+import { collectOperators, collectRomanLabels } from './math-glyphs.mjs';
 import { offVocabularyTokens } from './units-vocab';
 import type {
   NotationDefinitionRecord,
@@ -54,7 +60,8 @@ export type ConsistencyCode =
   | 'gloss-wants-promoting'
   | 'card-wants-demoting'
   | 'gloss-name-shape'
-  | 'operator-explained';
+  | 'operator-explained'
+  | 'roman-label-explained';
 
 export interface ConsistencyDiagnostic {
   readonly code: ConsistencyCode;
@@ -79,6 +86,8 @@ export interface ConsistencyInput {
   readonly conventions: CourseConventions;
   /** This course's edits to the named-operator baseline (rule N8). */
   readonly operators?: CourseOperators;
+  /** This course's edits to the roman-label baseline (rule N10). */
+  readonly romanLabels?: CourseRomanLabels;
 }
 
 const CONVENTION_RE =
@@ -551,6 +560,66 @@ function checkOperatorExplained(
   }
 }
 
+/**
+ * (i) roman-label-explained (rule N10) — the `\mathrm{…}` twin of (h)
+ * above: N3 requires the *format* (`\mathrm{KE}`, never bare `KE`) but has
+ * no opinion on whether the label is ever explained, because the glyph
+ * resolver skips a `\mathrm{…}` body whole. This is the check that looks at
+ * them; it reads `collectRomanLabels`, which parses with the same pinned
+ * KaTeX as the completeness gate.
+ */
+function checkRomanLabelExplained(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const allowlist = effectiveRomanLabelAllowlist(input.romanLabels);
+  const byId = new Map<string, NotationDefinitionRecord>(
+    input.registry.definitions.map((definition) => [definition.id, definition]),
+  );
+  const bindingsByLesson = new Map(
+    input.registry.bundles.map((bundle) => [bundle.lessonId, bundle.bindings]),
+  );
+
+  for (const lesson of input.notationInput.lessons) {
+    // Labels the reader is shown on this page: the lesson's own
+    // `notation.local` entries, plus every shared card it binds with `[[key]]`.
+    const explained = new Set<string>();
+    const noteEntryLabels = (latex: string): void => {
+      for (const label of collectRomanLabels(latex)) {
+        explained.add(label.name);
+      }
+    };
+    for (const definition of lesson.localDefinitions) {
+      noteEntryLabels(definition.notation);
+    }
+    for (const binding of bindingsByLesson.get(lesson.lessonId) ?? []) {
+      const definition = byId.get(binding.definitionId);
+      if (definition) noteEntryLabels(definition.notation);
+    }
+
+    const reported = new Set<string>();
+    for (const span of mathSpans(lesson.body)) {
+      for (const label of collectRomanLabels(span.latex)) {
+        if (allowlist.has(label.name)) continue;
+        if (explained.has(label.name)) continue;
+        if (reported.has(label.name)) continue;
+        reported.add(label.name);
+        if (input.lintIgnore.matches('roman-label-explained', label.name)) {
+          continue;
+        }
+        out.push({
+          code: 'roman-label-explained',
+          severity: 'warning',
+          lessonId: lesson.lessonId,
+          file: lesson.source.file,
+          glyph: label.name,
+          message: `${lesson.lessonId}: roman label ${JSON.stringify(`\\mathrm{${label.name}}`)} is neither on the course roman-label allowlist nor explained by a notation entry; give it a card or notation.local entry (latex ${JSON.stringify(`\\mathrm{${label.name}}`)}) introduced with [[key]], or add ${JSON.stringify(label.name)} to romanLabels.allow in course.config.ts`,
+        });
+      }
+    }
+  }
+}
+
 const CHECKS: ((
   input: ConsistencyInput,
   out: ConsistencyDiagnostic[],
@@ -565,6 +634,7 @@ const CHECKS: ((
   checkCardWantsDemoting,
   checkGlossNameShape,
   checkOperatorExplained,
+  checkRomanLabelExplained,
 ];
 
 /**
@@ -603,6 +673,7 @@ export function consistencyCounts(
     'card-wants-demoting': 0,
     'gloss-name-shape': 0,
     'operator-explained': 0,
+    'roman-label-explained': 0,
   } satisfies Record<ConsistencyCode, number>;
   for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
   return counts;

package/src/reference/diagrams-validate.ts

@@ -0,0 +1,40 @@
+/** `validateKeyedFloats` for `<Diagram>` — see `keyed-float-validate.ts`. */
+
+import {
+  validateKeyedFloats,
+  type KeyedFloatLabelRecord,
+  type KeyedFloatLessonInput,
+  type KeyedFloatValidation,
+} from './keyed-float-validate';
+
+export type DiagramDiagnosticCode =
+  | 'dia-invalid-key'
+  | 'dia-duplicate-key'
+  | 'dia-ref-resolves'
+  | 'dia-key-unused';
+
+export interface DiagramDiagnostic {
+  readonly code: DiagramDiagnosticCode;
+  readonly severity: 'error' | 'warning';
+  readonly message: string;
+  readonly file?: string;
+  readonly lessonId?: string;
+  readonly key?: string;
+}
+
+export type DiagramLabelRecord = KeyedFloatLabelRecord;
+export type DiagramLessonInput = KeyedFloatLessonInput;
+
+export interface DiagramValidation extends KeyedFloatValidation {
+  readonly diagnostics: readonly DiagramDiagnostic[];
+}
+
+export function validateDiagrams(
+  lessons: readonly DiagramLessonInput[],
+): DiagramValidation {
+  return validateKeyedFloats(lessons, {
+    tagName: 'Diagram',
+    prefix: 'dia',
+    noun: 'diagram',
+  }) as DiagramValidation;
+}

package/src/reference/equations-validate.ts

@@ -54,10 +54,12 @@ export interface EquationLessonInput {
   readonly file: string;
   readonly body: string;
   /**
-   * The lesson's 1-based ordinal in the course. When set, equations are
-   * numbered `‹chapter›.‹n›`; when omitted, the legacy `##`-section scheme.
+   * `{ prefix, offset }` — the part's 1-based ordinal among the sidebar groups,
+   * and how many display equations earlier lessons of that part already used.
+   * When set, equations are numbered `‹part›.‹offset + n›`; when omitted, the
+   * legacy `##`-section scheme. See `docs/authoring/structure.md`.
    */
-  readonly chapter?: number;
+  readonly numbering?: { readonly prefix: number; readonly offset: number };
 }
 
 const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
@@ -95,7 +97,7 @@ export function validateEquations(
   )) {
     const seen = new Set<string>();
     const table: Record<string, string> = {};
-    for (const raw of scanEquationLabels(lesson.body, lesson.chapter) as {
+    for (const raw of scanEquationLabels(lesson.body, lesson.numbering) as {
       key: string;
       number: string;
       section: number;

package/src/reference/equations.mjs

@@ -2,12 +2,17 @@
  * Equation identity (Step D7, extended F3) — shared, framework-free helpers.
  *
  * Every display equation (`$$…$$`) in a lesson is numbered and given an `id`
- * from appearance order. When the caller supplies a `chapter` (the lesson's
- * ordinal position in the course), the number is `‹chapter›.‹n›` — `n` counts
- * every display equation in the lesson and `##` headings do not affect it
- * (`(2.4)` = fourth display equation of the second lesson). With no `chapter`
- * the number falls back to the `##`-section scheme `‹section›.‹indexInSection›`
- * (used by hand-built test trees and non-lesson pages). An author additionally
+ * from appearance order. When the caller supplies `numbering`
+ * (`{ prefix, offset }` — see `resolveNumbering`), the number is
+ * `‹part›.‹offset + n›`: the prefix is the **part**'s ordinal among the sidebar
+ * groups, `n` counts every display equation in the lesson, and `offset` carries
+ * the count from earlier lessons of the same part so the sequence runs
+ * continuously across a part rather than restarting on every page. `##` and
+ * `###` headings never affect it — `(2.4)` is the fourth display equation of
+ * part 2, wherever in that part it sits. See `docs/authoring/structure.md` for
+ * the level names. With no `numbering` the number falls back to the
+ * `##`-section scheme `‹section›.‹indexInSection›` (used by hand-built test
+ * trees and non-lesson pages). An author additionally
  * marks an equation with a trailing `\label{eq:<key>}` inside its `$$…$$`
  * block (inside math, so the `:` is safe and the form matches amsmath) when
  * they want a *stable* anchor that survives edits and cross-page references:
@@ -63,19 +68,42 @@ function equationNumber(section, index) {
 }
 
 /**
- * The visible number for one display equation. With `chapter` (the lesson's
- * course ordinal) the scheme is `‹chapter›.‹indexInLesson›` and `##` headings
+ * Normalise the numbering input to `{ prefix, offset }`.
+ *
+ * `prefix` is the number before the dot — the **part**'s ordinal (its position
+ * among the sidebar groups). `offset` is how many display equations already
+ * appeared in earlier lessons of that same part, so `n` runs continuously
+ * across a part instead of restarting on every page. A bare number is the
+ * legacy per-lesson form (`prefix = n`, `offset = 0`) and is still accepted so
+ * hand-built trees and unit tests keep working. `undefined`/`null`/`0` ⇒ the
+ * `##`-section fallback for non-lesson pages.
+ */
+export function resolveNumbering(input) {
+  if (input == null) return { prefix: undefined, offset: 0 };
+  if (typeof input === 'number') {
+    return { prefix: input || undefined, offset: 0 };
+  }
+  return {
+    prefix: input.prefix || undefined,
+    offset: Number(input.offset) || 0,
+  };
+}
+
+/**
+ * The visible number for one display equation. With a `prefix` (the part's
+ * ordinal) the scheme is `‹part›.‹offset + indexInLesson›` and `##` headings
  * are ignored; without it, the legacy `##`-section scheme.
  */
 export function displayEquationNumber({
-  chapter,
+  prefix,
+  offset = 0,
   section,
   indexInSection,
   indexInLesson,
 }) {
-  return chapter == null
+  return prefix == null
     ? equationNumber(section, indexInSection)
-    : `${chapter}.${indexInLesson}`;
+    : `${prefix}.${offset + indexInLesson}`;
 }
 
 /** The positional anchor id for an unkeyed equation, e.g. `2.4` → `eq-2-4`. */
@@ -100,25 +128,58 @@ export function stripFencedCode(markdown) {
  * `keep`, when given, leaves a component of that name untouched instead of
  * blanking it — `keyed-jsx-floats.mjs` uses this to blank every *other*
  * component while still finding `<Table>`/`<Figure>` tags at the top level.
+ *
+ * `transparent`, when given, removes only those components' opening/closing
+ * tags and exposes their body to the later blanking pass. `<Memo>` and
+ * `<ShortNote>` are intentional uses: unlike a worked-example/presentation
+ * wrapper, their bodies are details in the lesson's reading order, so numbered
+ * equations/floats in them stay in the official sequence. Section headings in
+ * a transparent body do not change the surrounding page's section counter.
  */
-export function stripJsxComponents(markdown, keep) {
-  return String(markdown).replace(
+export function stripJsxComponents(markdown, keep, transparent = []) {
+  let source = String(markdown);
+  const attributes = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'])*`;
+  for (const name of transparent) {
+    const component = new RegExp(
+      `<${name}\\b${attributes}>([\\s\\S]*?)<\\/${name}\\s*>`,
+      'g',
+    );
+    source = source.replace(component, (block, body) => {
+      const bodyStart = block.indexOf(body);
+      const visibleBody = body.replace(
+        /(^|\n)([ \t]{0,3})##(?=[ \t]+\S)/g,
+        (match) => match.replace(/#/g, ' '),
+      );
+      return (
+        block.slice(0, bodyStart).replace(/[^\n]/g, ' ') +
+        visibleBody +
+        block.slice(bodyStart + body.length).replace(/[^\n]/g, ' ')
+      );
+    });
+  }
+  return source.replace(
     /<([A-Z][A-Za-z0-9]*)(?:\s[^>]*)?>[\s\S]*?<\/\1>/g,
     (block, name) => (name === keep ? block : block.replace(/[^\n]/g, ' ')),
   );
 }
 
 /**
- * Every keyed display equation in a Markdown body, in appearance order, with
- * its assigned number. `$$…$$` blocks only. With `chapter` (the lesson's
- * course ordinal) the number is `‹chapter›.‹n›`, `n` sequential over every
- * display block in the lesson; without it, `##` headings advance a section
- * counter and the number is `‹section›.‹indexInSection›`. Either way every
- * display block advances the index, so a keyed equation's number reflects its
- * position among *all* display equations, not only the keyed ones.
+ * Every display equation in a Markdown body, keyed or not, in appearance order
+ * with its assigned number. `$$…$$` blocks only. With `numbering`
+ * (`{ prefix, offset }`, the part's ordinal and the count of display equations
+ * in earlier lessons of that part) the number is `‹part›.‹offset + n›`, `n`
+ * sequential over every display block in the lesson; without it, `##` headings
+ * advance a section counter and the number is `‹section›.‹indexInSection›`.
+ * Either way every display block advances the index, so a keyed equation's
+ * number reflects its position among *all* display equations, not only the
+ * keyed ones.
  */
-export function scanEquationLabels(markdown, chapter) {
-  const text = stripJsxComponents(stripFencedCode(markdown));
+export function scanDisplayEquations(markdown, numbering) {
+  const { prefix, offset } = resolveNumbering(numbering);
+  const text = stripJsxComponents(stripFencedCode(markdown), undefined, [
+    'Memo',
+    'ShortNote',
+  ]);
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
   const display = /\$\$([\s\S]+?)\$\$/g;
@@ -148,11 +209,11 @@ export function scanEquationLabels(markdown, chapter) {
     }
     indexInSection += 1;
     indexInLesson += 1;
-    if (token.key == null) continue;
     labels.push({
       key: token.key,
       number: displayEquationNumber({
-        chapter,
+        prefix,
+        offset,
         section,
         indexInSection,
         indexInLesson,
@@ -164,30 +225,43 @@ export function scanEquationLabels(markdown, chapter) {
   return labels;
 }
 
+/** The keyed subset of `scanDisplayEquations` — the manifest builder's view. */
+export function scanEquationLabels(markdown, numbering) {
+  return scanDisplayEquations(markdown, numbering).filter(
+    (equation) => equation.key != null,
+  );
+}
+
+/**
+ * How many display equations a lesson body holds. This is what makes `n` run
+ * continuously across a part: a lesson's `offset` is the sum of this over every
+ * earlier lesson in the same part.
+ */
+export function countDisplayEquations(markdown) {
+  return scanDisplayEquations(markdown).length;
+}
+
 /**
  * The mdast equivalent of `scanEquationLabels` for *every* display equation:
  * walk the tree in document order, advancing the section counter on every
  * depth-2 heading and emitting a record for every `math` node. `key` is the
- * `\label{eq:…}` payload when present, else `null`. `chapter` is threaded the
+ * `\label{eq:…}` payload when present, else `null`. `numbering` is threaded the
  * same way as in `scanEquationLabels`.
  */
-export function collectDisplayEquations(tree, chapter) {
+export function collectDisplayEquations(tree, numbering) {
+  const { prefix, offset } = resolveNumbering(numbering);
   const equations = [];
   let section = 0;
   let indexInSection = 0;
   let indexInLesson = 0;
 
-  // Only top-level blocks: a `$$…$$` nested in an MDX component (a
-  // `<CompactExample>` worked example, an `<Aside>`) is illustrative, not part
-  // of the lesson's equation sequence, and its container may be collapsed.
-  const children = Array.isArray(tree?.children) ? tree.children : [];
-  for (const node of children) {
-    if (!node || typeof node !== 'object') continue;
-    if (node.type === 'heading' && node.depth === 2) {
-      section += 1;
-      indexInSection = 0;
-      continue;
-    }
+  // Top-level blocks plus the bodies of `<Memo>` and `<ShortNote>`: other MDX
+  // components (a `<CompactExample>` worked example, an `<Aside>`) remain
+  // illustrative and outside the lesson's official equation sequence. These
+  // two detail components are deliberately transparent because they occupy an
+  // exact point in the reading order, even while visually collapsed.
+  const collectFromDetail = (node) => {
+    if (!node || typeof node !== 'object') return;
     if (node.type === 'math') {
       indexInSection += 1;
       indexInLesson += 1;
@@ -196,7 +270,8 @@ export function collectDisplayEquations(tree, chapter) {
       equations.push({
         key: label ? label[1] : null,
         number: displayEquationNumber({
-          chapter,
+          prefix,
+          offset,
           section,
           indexInSection,
           indexInLesson,
@@ -205,6 +280,33 @@ export function collectDisplayEquations(tree, chapter) {
         indexInSection,
         node,
       });
+      return;
+    }
+    if (
+      node.type === 'mdxJsxFlowElement' &&
+      node.name !== 'Memo' &&
+      node.name !== 'ShortNote'
+    ) {
+      return;
+    }
+    if (!Array.isArray(node.children)) return;
+    for (const child of node.children) collectFromDetail(child);
+  };
+
+  const children = Array.isArray(tree?.children) ? tree.children : [];
+  for (const node of children) {
+    if (!node || typeof node !== 'object') continue;
+    if (node.type === 'heading' && node.depth === 2) {
+      section += 1;
+      indexInSection = 0;
+      continue;
+    }
+    if (node.type === 'math') collectFromDetail(node);
+    else if (
+      node.type === 'mdxJsxFlowElement' &&
+      (node.name === 'Memo' || node.name === 'ShortNote')
+    ) {
+      collectFromDetail(node);
     }
   }
   return equations;
@@ -214,8 +316,8 @@ export function collectDisplayEquations(tree, chapter) {
  * The keyed subset of `collectDisplayEquations` — the tree-walk counterpart of
  * `scanEquationLabels`. Numbers reflect position among all display equations.
  */
-export function collectEquationLabels(tree, chapter) {
-  return collectDisplayEquations(tree, chapter).filter(
+export function collectEquationLabels(tree, numbering) {
+  return collectDisplayEquations(tree, numbering).filter(
     (equation) => equation.key != null,
   );
 }

package/src/reference/gate-abbreviations.ts

@@ -0,0 +1,128 @@
+/**
+ * The abbreviation-notation gate (rule N14): every acronym-shaped or
+ * dotted-abbreviation-shaped token sitting in plain lesson prose is either
+ * universal, explained by the abbreviations table, or already explained as a
+ * math quantity elsewhere on the same page.
+ *
+ * This is the prose-shaped twin of [N8](#n8)/[N10](#n10)
+ * (`checkOperatorExplained` / `checkRomanLabelExplained` in `consistency.ts`)
+ * rather than a rewrite of them: those two already require every
+ * `\operatorname{…}` / `\mathrm{…}` used *inside* `$…$` to be universal or
+ * explained, so an abbreviation that is also a math quantity — `MSE` written
+ * `\mathrm{MSE}` in an equation and bound to a notation entry — is already
+ * covered there. What N8/N10 cannot see is the same word sitting in ordinary
+ * prose ("the OLS estimator…") with no `$…$` around it at all; that is this
+ * gate's whole job, so it reuses `pageScope` plus `collectRomanLabels` /
+ * `collectOperators` (the exact functions N8/N10 already call) to recognize
+ * when a prose token is covered by that other mechanism instead of asking the
+ * author to explain the same term twice.
+ *
+ * Ships straight as an error, same as N9 (`gate-prose-notation.ts`): the
+ * corpus has no prior instances to absorb, so there is no Tier-3 warm-up
+ * period and no `lint-ignore.yml` entry.
+ */
+import { collectOperators, collectRomanLabels } from './math-glyphs.mjs';
+import { isBaseAbbreviation } from './base-abbreviations.mjs';
+import { pageScope } from './gate-math';
+import type { MathGateDiagnostic, ScopeEntry } from './gate-math';
+import { lineOf, proseOnly } from './gate-prose-notation';
+import type {
+  AbbreviationDefinitionInput,
+  NotationRegistryInput,
+} from './types';
+import type { CourseAbbreviations } from '../compiler/course-config';
+
+// An all-caps run of 2+ letters, an optional trailing plural/possessive `s`
+// or `'s` (`OLSs`, `SSR's`) stripped from the reported token so it matches
+// the table/baseline entry for the singular form.
+const CAPS_RUN = /\b([A-Z]{2,})(?:'s|s)?\b/g;
+// A run of 2+ single-letter-then-period groups: `w.r.t.`, `i.i.d.`, `e.g.`.
+const DOTTED_ABBR = /\b(?:[A-Za-z]\.){2,}/g;
+
+interface AbbreviationMatch {
+  readonly token: string;
+  readonly index: number;
+}
+
+/** Every abbreviation-shaped token in an already-prose-only string, in source order. */
+function findAbbreviationLikeTokens(text: string): AbbreviationMatch[] {
+  const out: AbbreviationMatch[] = [];
+  for (const match of text.matchAll(CAPS_RUN)) {
+    out.push({ token: match[1] ?? match[0], index: match.index ?? 0 });
+  }
+  for (const match of text.matchAll(DOTTED_ABBR)) {
+    out.push({ token: match[0], index: match.index ?? 0 });
+  }
+  return out.sort((a, b) => a.index - b.index);
+}
+
+const FIX =
+  'Add it to an abbreviations-table entry (content/abbreviations/*.md), ' +
+  'allowlist it in abbreviations.allow in course.config.ts if it is common, ' +
+  'non-technical usage, or — if it names a math quantity — introduce it as ' +
+  '\\mathrm{…} (or \\operatorname{…}) bound to a notation entry the reader ' +
+  'can hover. See docs/authoring/notation.md#n14.';
+
+/**
+ * Scan every lesson body for an abbreviation-shaped token outside `$…$` that
+ * is neither universal nor explained. Returns one `MathGateDiagnostic`
+ * (context `'abbreviation'`, always an error) per unresolved token, deduped
+ * per lesson so a term used many times on one page is reported once.
+ */
+export function gateAbbreviations(input: {
+  readonly notationInput: NotationRegistryInput;
+  readonly abbreviations: readonly AbbreviationDefinitionInput[];
+  readonly courseAbbreviations?: CourseAbbreviations;
+}): MathGateDiagnostic[] {
+  const { notationInput, abbreviations, courseAbbreviations } = input;
+
+  const tableTokens = new Set<string>();
+  for (const entry of abbreviations) {
+    tableTokens.add(entry.abbr);
+    for (const alias of entry.aliases) tableTokens.add(alias);
+  }
+
+  const sharedByKey = new Map<string, ScopeEntry>(
+    notationInput.sharedDefinitions.map((definition) => [
+      definition.key,
+      { key: definition.key, notation: definition.notation },
+    ]),
+  );
+
+  const diagnostics: MathGateDiagnostic[] = [];
+
+  for (const lesson of notationInput.lessons) {
+    // Terms already explained as a math quantity on this page (N8/N10): every
+    // roman label / named operator carried by a bound local or `[[key]]`
+    // /`\explain`-referenced shared definition.
+    const mathQuantityNames = new Set<string>();
+    for (const entry of pageScope(lesson, sharedByKey)) {
+      for (const label of collectRomanLabels(entry.notation)) {
+        mathQuantityNames.add(label.name);
+      }
+      for (const operator of collectOperators(entry.notation)) {
+        mathQuantityNames.add(operator.name);
+      }
+    }
+
+    const text = proseOnly(lesson.body);
+    const reported = new Set<string>();
+    for (const { token, index } of findAbbreviationLikeTokens(text)) {
+      if (reported.has(token)) continue;
+      if (isBaseAbbreviation(token, courseAbbreviations)) continue;
+      if (tableTokens.has(token)) continue;
+      if (mathQuantityNames.has(token)) continue;
+      reported.add(token);
+      diagnostics.push({
+        context: 'abbreviation',
+        severity: 'error',
+        file: lesson.source.file,
+        line: lineOf(lesson.body, index),
+        token,
+        message: `Unexplained abbreviation ${JSON.stringify(token)} outside math. ${FIX}`,
+      });
+    }
+  }
+
+  return diagnostics;
+}

package/src/reference/gate-math.ts

@@ -20,14 +20,25 @@ import type {
 } from './types';
 
 export interface MathGateDiagnostic {
-  readonly context: 'body' | 'formula' | 'assessment';
+  readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation';
   /**
    * Body / component-slot math blocks the build (the render path needs every
    * glyph resolved for the KaTeX trust callback). `formula` joined it at D15:
    * a formula's glyphs are now rendered live and explorable, so an unresolved
    * one is a hole the reader can see, and the corpus was brought to zero when
-   * the tier was promoted. `assessment` math stays a Tier-3 warning until its
-   * own reviewed content pass (D6/D13/D14).
+   * the tier was promoted. `assessment` joined the same way when
+   * `AssessmentRunner` started rendering `prompt` / `explanation` through
+   * KaTeX (`mixed-content.ts`) instead of showing them as raw text: an
+   * unresolved glyph is now a visible hole in the assessment UI, not an
+   * invisible warning, so the corpus was brought to zero and the tier
+   * promoted in the same change — see `CHANGELOG.md`. `prose` (N9,
+   * `gate-prose-notation.ts`) is the complementary direction — plain-text
+   * notation sitting *outside* `$…$` — and ships straight as an error: it has
+   * no partial corpus to absorb, since every prior instance was fixed in the
+   * same change that introduced the check. `abbreviation` (N14,
+   * `gate-abbreviations.ts`) is the same "ships straight as an error" story
+   * for a different shape of plain-text token — an unexplained acronym or
+   * dotted abbreviation, rather than a mis-typed quantity/unit.
    */
   readonly severity: 'error' | 'warning';
   readonly file: string;
@@ -39,7 +50,9 @@ export interface MathGateDiagnostic {
 const SEVERITY: Record<MathGateDiagnostic['context'], 'error' | 'warning'> = {
   body: 'error',
   formula: 'error',
-  assessment: 'warning',
+  assessment: 'error',
+  prose: 'error',
+  abbreviation: 'error',
 };
 
 interface AssessmentItemLike {
@@ -93,11 +106,18 @@ function mathSpans(body: string): MathSpan[] {
   return spans;
 }
 
-type ScopeEntry = { key: string; notation: string };
+export type ScopeEntry = { key: string; notation: string };
 
-function pageScope(
+/**
+ * A lesson's flat glyph table: its own `notation.local` entries plus every
+ * shared card it introduces with `[[key]]` / `\explain{key}`. Exported so a
+ * caller that needs the *same* scope for a different purpose — rendering an
+ * assessment's math (`mixed-content.ts`), say — doesn't reconstruct it by
+ * hand and risk drifting from what the completeness gate actually checks.
+ */
+export function pageScope(
   lesson: NotationLessonInput,
-  sharedByKey: ReadonlyMap<string, SharedNotationDefinitionInput>,
+  sharedByKey: ReadonlyMap<string, ScopeEntry>,
 ): ScopeEntry[] {
   const local = lesson.localDefinitions.map((definition) => ({
     key: definition.key,