explico 0.1.1 → 0.2.0

package/dist/compiler/cli.d.ts

@@ -7,6 +7,7 @@ import '../reference/types.js';
 import '../reference/lint-ignore.js';
 import '../reference/equations-validate.js';
 import '../reference/gate-math.js';
+import '../reference/gloss.js';
 import './lesson-derivation.js';
 
 /**

package/dist/compiler/collections.js

@@ -4,6 +4,7 @@ import { parseFrontmatter } from "@astrojs/markdown-remark";
 import { isSubstantiveMeaning } from "../reference/prose.js";
 import { parseEquationRef } from "../reference/equations.mjs";
 import { resolveLabel } from "../reference/label.js";
+import { resolveGlosses } from "../reference/gloss.js";
 import {
   deriveRequires,
   deriveSources,
@@ -206,6 +207,30 @@ async function loadCurriculumCatalog() {
     tracks: jsonEntries(join(CONTENT_ROOT, "tracks"))
   };
 }
+function glossEntries(raw, ownerKey, at) {
+  if (raw === void 0) return [];
+  if (!Array.isArray(raw)) throw new Error(`${at} must be an array`);
+  const authored = raw.map((value, index) => {
+    const data = record(value, `${at}[${index}]`);
+    const units = optionalString(data.units, `${at}[${index}].units`);
+    return {
+      latex: string(data.latex, `${at}[${index}].latex`),
+      name: string(data.name, `${at}[${index}].name`),
+      ...units === void 0 ? {} : { units }
+    };
+  });
+  const glosses = resolveGlosses(ownerKey, authored);
+  const seen = /* @__PURE__ */ new Set();
+  for (const gloss of glosses) {
+    if (seen.has(gloss.key)) {
+      throw new Error(
+        `${at} declares two glosses named ${JSON.stringify(gloss.label)}`
+      );
+    }
+    seen.add(gloss.key);
+  }
+  return glosses;
+}
 function localDefinition(raw, file, index) {
   const at = `${file} notation.local[${index}]`;
   const data = record(raw, at);
@@ -224,6 +249,7 @@ function localDefinition(raw, file, index) {
     seeAlso: strings(data.seeAlso, `${at}.seeAlso`),
     alignment: data.alignment === void 0 ? { kind: "general", rationale: "Lesson-local symbol." } : alignment(data.alignment, `${at}.alignment`),
     references: extractNotationReferences(definitionText, file, "definition"),
+    glosses: glossEntries(data.glosses, key, `${at}.glosses`),
     source: { file },
     ...formula === void 0 ? {} : { formula },
     ...units === void 0 ? {} : { units }
@@ -255,6 +281,7 @@ function sharedNotationEntries() {
       aiAssisted: boolean(data.aiAssisted, `${file} aiAssisted`),
       body,
       references: extractNotationReferences(body, file, void 0),
+      glosses: glossEntries(data.glosses, key, `${file} glosses`),
       source: { file },
       ...formula === void 0 ? {} : { formula },
       ...units === void 0 ? {} : { units }

package/dist/compiler/manifest.d.ts

@@ -2,7 +2,8 @@ import { CurriculumIssue } from '../curriculum/validation.js';
 import { ConsistencyDiagnostic } from '../reference/consistency.js';
 import { EquationLabelRecord, EquationDiagnostic } from '../reference/equations-validate.js';
 import { MathGateDiagnostic } from '../reference/gate-math.js';
-import { NotationDefinitionRecord, NotationPageBundle, NotationBacklink, NotationDiagnostic, EditorialStatus } from '../reference/types.js';
+import { GlyphScopeEntry } from '../reference/gloss.js';
+import { NotationDefinitionRecord, NotationPageBundle, NotationBacklink, NotationDiagnostic, EditorialStatus, NotationGlossEntry } from '../reference/types.js';
 import { CourseConfig } from './course-config.js';
 import { SidebarGroup } from './lesson-derivation.js';
 import './collections.js';
@@ -81,6 +82,14 @@ interface ManifestLessonNotation {
     readonly seeAlso: readonly string[];
     readonly units?: string;
     readonly formula?: string;
+    /** Symbols the formula names that have no card of their own (D15). */
+    readonly glosses: readonly NotationGlossEntry[];
+    /**
+     * Entry-scoped glyph table for `formula` — the entry, its glosses, and any
+     * card the formula names. Precomputed here because the whole card set lives
+     * in the compiler, not in the page component.
+     */
+    readonly formulaScope: readonly GlyphScopeEntry[];
 }
 interface ManifestLesson {
     readonly id: string;

package/dist/compiler/manifest.js

@@ -23,6 +23,7 @@ import {
 } from "../reference/gate-math.js";
 import { loadLintIgnore } from "../reference/lint-ignore.js";
 import { buildNotationRegistry } from "../reference/registry.js";
+import { formulaGlyphScope } from "../reference/gloss.js";
 import { resolveReferenceId } from "../reference/references.js";
 import {
   loadCurriculumCatalog,
@@ -97,7 +98,7 @@ function lessonNotationResolution(lesson, definitionsById, availableDefinitionId
     };
   });
 }
-function lessonNotationBundle(bundle, definitionsById, resolution) {
+function lessonNotationBundle(bundle, definitionsById, resolution, cardsByKey) {
   const definitions = [];
   for (const definitionId of bundle?.definitionIds ?? []) {
     const definition = definitionsById.get(definitionId);
@@ -111,6 +112,14 @@ function lessonNotationBundle(bundle, definitionsById, resolution) {
       summary: definition.summary,
       editorialStatus: definition.status,
       seeAlso: [...definition.seeAlso],
+      glosses: [...definition.glosses],
+      formulaScope: formulaGlyphScope({
+        key: definition.key,
+        notation: definition.notation,
+        glosses: definition.glosses,
+        cardsByKey,
+        ...definition.formula === void 0 ? {} : { formula: definition.formula }
+      }),
       ...definition.units === void 0 ? {} : { units: definition.units },
       ...definition.formula === void 0 ? {} : { formula: definition.formula }
     });
@@ -152,6 +161,12 @@ async function compileManifest(courseConfig) {
     loadNotationRegistryInput()
   ]);
   const registry = buildNotationRegistry(notationInput);
+  const cardsByKey = new Map(
+    notationInput.sharedDefinitions.map((definition) => [
+      definition.key,
+      { key: definition.key, notation: definition.notation }
+    ])
+  );
   const definitionsById = new Map(
     registry.definitions.map((definition) => [definition.id, definition])
   );
@@ -237,7 +252,8 @@ async function compileManifest(courseConfig) {
           notationLesson,
           definitionsById,
           availableDefinitionIds
-        )
+        ),
+        cardsByKey
       )
     });
   }

package/dist/compiler/resolution-report.d.ts

@@ -7,6 +7,7 @@ import '../reference/types.js';
 import '../reference/lint-ignore.js';
 import '../reference/equations-validate.js';
 import '../reference/gate-math.js';
+import '../reference/gloss.js';
 import './lesson-derivation.js';
 
 /**

package/dist/reference/consistency.d.ts

@@ -30,7 +30,7 @@ import { NotationRegistry, NotationRegistryInput } from './types.js';
  * `src/content/resolution-report.ts`.
  */
 
-type ConsistencyCode = 'glyph-unique-in-corpus' | 'notation-units' | 'units-vocab' | 'convention-single-definition' | 'numerals-tagged' | 'weak-local' | 'notation-source-locator';
+type ConsistencyCode = 'glyph-unique-in-corpus' | 'notation-units' | 'units-vocab' | 'convention-single-definition' | 'numerals-tagged' | 'weak-local' | 'notation-source-locator' | 'gloss-wants-promoting' | 'card-wants-demoting' | 'gloss-name-shape';
 interface ConsistencyDiagnostic {
     readonly code: ConsistencyCode;
     /** Tier 3 — every finding here is a warning until content is brought clean. */

package/dist/reference/consistency.js

@@ -200,13 +200,101 @@ function checkNotationSourceLocator(input, out) {
     }
   }
 }
+const GLOSS_PROMOTION_LIMIT = 3;
+function checkGlossWantsPromoting(input, out) {
+  const owners = /* @__PURE__ */ new Map();
+  const record = (ownerKey, gloss) => {
+    const id = `${gloss.notation}\0${gloss.label.toLowerCase()}`;
+    const current = owners.get(id) ?? { label: gloss.label, keys: /* @__PURE__ */ new Set() };
+    current.keys.add(ownerKey);
+    owners.set(id, current);
+  };
+  for (const definition of input.notationInput.sharedDefinitions) {
+    for (const gloss of definition.glosses) record(definition.key, gloss);
+  }
+  for (const lesson of input.notationInput.lessons) {
+    for (const definition of lesson.localDefinitions) {
+      for (const gloss of definition.glosses) record(definition.key, gloss);
+    }
+  }
+  for (const [id, { label, keys }] of [...owners].sort(
+    ([a], [b]) => a.localeCompare(b)
+  )) {
+    if (keys.size < GLOSS_PROMOTION_LIMIT) continue;
+    const glyph = id.split("\0")[0] ?? "";
+    if (input.lintIgnore.matches("gloss-wants-promoting", glyph)) continue;
+    out.push({
+      code: "gloss-wants-promoting",
+      severity: "warning",
+      glyph,
+      message: `gloss ${JSON.stringify(glyph)} (${label}) is declared on ${keys.size} entries (${[...keys].sort().join(", ")}); a meaning reused this widely wants promoting to a card`
+    });
+  }
+}
+const CARD_BODY_MINIMUM_WORDS = 25;
+function checkCardWantsDemoting(input, out) {
+  const used = new Set(
+    input.registry.backlinks.map((backlink) => backlink.key)
+  );
+  for (const definition of input.notationInput.sharedDefinitions) {
+    if (definition.formula !== void 0) continue;
+    if (definition.sources.length > 0) continue;
+    if (used.has(definition.key)) continue;
+    const words = stripCode(definition.body).split(/\s+/).filter((word) => word.length > 0).length;
+    if (words >= CARD_BODY_MINIMUM_WORDS) continue;
+    if (input.lintIgnore.matches("card-wants-demoting", definition.key)) {
+      continue;
+    }
+    out.push({
+      code: "card-wants-demoting",
+      severity: "warning",
+      key: definition.key,
+      file: definition.source.file,
+      count: words,
+      message: `notation card ${definition.key} has no formula, no sources, a ${words}-word body, and no lesson uses it; it carries no more than a name \u2014 a gloss on the entry that needs it may be the right home`
+    });
+  }
+}
+const GLOSS_NAME_WORD_LIMIT = 6;
+const GLOSS_NAME_PROSE = /[.;]|\b(?:which|whose|that is|such that)\b/i;
+function checkGlossNameShape(input, out) {
+  const check = (gloss, file, lessonId) => {
+    const words = gloss.label.trim().split(/\s+/).filter(Boolean);
+    const reason = words.length > GLOSS_NAME_WORD_LIMIT ? `${words.length} words` : GLOSS_NAME_PROSE.test(gloss.label) ? "sentence punctuation or a relative clause" : void 0;
+    if (reason === void 0) return;
+    if (input.lintIgnore.matches("gloss-name-shape", gloss.key)) return;
+    out.push({
+      code: "gloss-name-shape",
+      severity: "warning",
+      key: gloss.key,
+      file,
+      ...lessonId ? { lessonId } : {},
+      message: `gloss ${gloss.key} is named ${JSON.stringify(gloss.label)} (${reason}); a gloss name is a short noun phrase naming the symbol, not a description of it`
+    });
+  };
+  for (const definition of input.notationInput.sharedDefinitions) {
+    for (const gloss of definition.glosses) {
+      check(gloss, definition.source.file);
+    }
+  }
+  for (const lesson of input.notationInput.lessons) {
+    for (const definition of lesson.localDefinitions) {
+      for (const gloss of definition.glosses) {
+        check(gloss, definition.source.file, lesson.lessonId);
+      }
+    }
+  }
+}
 const CHECKS = [
   checkGlyphUniqueness,
   checkNotationUnits,
   checkConventionSingleDefinition,
   checkNumeralsTagged,
   checkWeakLocal,
-  checkNotationSourceLocator
+  checkNotationSourceLocator,
+  checkGlossWantsPromoting,
+  checkCardWantsDemoting,
+  checkGlossNameShape
 ];
 function runConsistencyChecks(input) {
   const diagnostics = [];
@@ -223,7 +311,10 @@ function consistencyCounts(diagnostics) {
     "convention-single-definition": 0,
     "numerals-tagged": 0,
     "weak-local": 0,
-    "notation-source-locator": 0
+    "notation-source-locator": 0,
+    "gloss-wants-promoting": 0,
+    "card-wants-demoting": 0,
+    "gloss-name-shape": 0
   };
   for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
   return counts;

package/dist/reference/equations.d.mts

@@ -8,42 +8,69 @@ export function parseEquationRef(raw: any): {
 } | undefined;
 /** Remove every `\label{eq:…}` (and the whitespace it leaves) from a math source. */
 export function stripEquationLabels(latex: any): string;
+/** The positional anchor id for an unkeyed equation, e.g. `2.4` → `eq-2-4`. */
+export function equationAnchorId({ key, number }: {
+    key: any;
+    number: any;
+}): string;
 /**
  * Every keyed display equation in a Markdown body, in appearance order, with
  * its assigned number. `$$…$$` blocks only; `##` headings between them advance
- * the section counter.
+ * the section counter. Every display block advances the in-section index, so a
+ * keyed equation's number reflects its position among *all* display equations,
+ * not only the keyed ones.
  */
 export function scanEquationLabels(markdown: any): {
-    key: string | undefined;
+    key: string;
+    number: string;
+    section: number;
+    indexInSection: number;
+}[];
+/**
+ * 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`.
+ */
+export function collectDisplayEquations(tree: any): {
+    key: string | null;
     number: string;
     section: number;
     indexInSection: number;
+    node: any;
 }[];
 /**
- * The mdast equivalent of `scanEquationLabels`: walk the tree in document
- * order, advancing the section counter on every depth-2 heading and emitting a
- * label for every `math` node whose source carries `\label{eq:…}`.
+ * The keyed subset of `collectDisplayEquations` — the tree-walk counterpart of
+ * `scanEquationLabels`. Numbers reflect position among all display equations.
  */
-export function collectEquationLabels(tree: any): any[];
+export function collectEquationLabels(tree: any): {
+    key: string | null;
+    number: string;
+    section: number;
+    indexInSection: number;
+    node: any;
+}[];
 /**
- * Equation identity (Step D7) — shared, framework-free helpers.
+ * Equation identity (Step D7, extended F3) — shared, framework-free helpers.
  *
- * An author marks a display equation by putting a trailing `\label{eq:<key>}`
- * inside its `$$…$$` block (inside math, so the `:` is safe and the form
- * matches amsmath). The compiler assigns the *visible* number from appearance
- * order, scoped to the enclosing `##` section (`(2.4)` = fourth keyed equation
- * under the second section). The number is never authored; unkeyed display
- * equations render clean and stay un-referenceable. Prose refers to an
- * equation with the reserved `eq-` prefix (a bare `:` in `[[…]]` prose would
- * be eaten by `remark-directive`):
+ * Every display equation (`$$…$$`) in a lesson is numbered and given an
+ * `id`, from appearance order scoped to the enclosing `##` section (`(2.4)` =
+ * fourth display equation under the second section). 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:
  *
  *   [[eq-discount-factor-def]]           same page  → "(2.4)" linked to #eq-…
  *   [[foundations/present-value#eq-pv]]  cross page → number from the manifest
  *
+ * An unkeyed equation still gets a positional anchor (`#eq-2-4`) so it can be
+ * deep-linked, but only a keyed equation is referenceable by name.
+ *
  * `scanEquationLabels` (raw Markdown) and `collectEquationLabels` (mdast tree)
  * MUST agree — `tests/notation/equations.test.ts` checks that on the real
  * corpus. Both are here so `manifest.ts` and `remark-notation.mjs` share one
- * numbering algorithm.
+ * numbering algorithm. `collectDisplayEquations` is the superset the render
+ * path uses to number and anchor every display equation, keyed or not.
  */
 /** `eq:` key grammar — the notation-key shape without the dotted namespaces. */
 export const EQ_KEY_PATTERN: RegExp;

package/dist/reference/equations.mjs

@@ -1,22 +1,24 @@
 /**
- * Equation identity (Step D7) — shared, framework-free helpers.
+ * Equation identity (Step D7, extended F3) — shared, framework-free helpers.
  *
- * An author marks a display equation by putting a trailing `\label{eq:<key>}`
- * inside its `$$…$$` block (inside math, so the `:` is safe and the form
- * matches amsmath). The compiler assigns the *visible* number from appearance
- * order, scoped to the enclosing `##` section (`(2.4)` = fourth keyed equation
- * under the second section). The number is never authored; unkeyed display
- * equations render clean and stay un-referenceable. Prose refers to an
- * equation with the reserved `eq-` prefix (a bare `:` in `[[…]]` prose would
- * be eaten by `remark-directive`):
+ * Every display equation (`$$…$$`) in a lesson is numbered and given an
+ * `id`, from appearance order scoped to the enclosing `##` section (`(2.4)` =
+ * fourth display equation under the second section). 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:
  *
  *   [[eq-discount-factor-def]]           same page  → "(2.4)" linked to #eq-…
  *   [[foundations/present-value#eq-pv]]  cross page → number from the manifest
  *
+ * An unkeyed equation still gets a positional anchor (`#eq-2-4`) so it can be
+ * deep-linked, but only a keyed equation is referenceable by name.
+ *
  * `scanEquationLabels` (raw Markdown) and `collectEquationLabels` (mdast tree)
  * MUST agree — `tests/notation/equations.test.ts` checks that on the real
  * corpus. Both are here so `manifest.ts` and `remark-notation.mjs` share one
- * numbering algorithm.
+ * numbering algorithm. `collectDisplayEquations` is the superset the render
+ * path uses to number and anchor every display equation, keyed or not.
  */
 
 /** `eq:` key grammar — the notation-key shape without the dotted namespaces. */
@@ -51,11 +53,16 @@ export function stripEquationLabels(latex) {
     .trim();
 }
 
-/** The visible number for the `index`-th keyed equation under `section`. */
+/** The visible number for the `index`-th display equation under `section`. */
 function equationNumber(section, index) {
   return section > 0 ? `${section}.${index}` : String(index);
 }
 
+/** The positional anchor id for an unkeyed equation, e.g. `2.4` → `eq-2-4`. */
+export function equationAnchorId({ key, number }) {
+  return key ? `eq-${key}` : `eq-${String(number).replace(/\./g, '-')}`;
+}
+
 function stripFencedCode(markdown) {
   return String(markdown)
     .replace(/```[\s\S]*?```/g, (block) => block.replace(/[^\n]/g, ' '))
@@ -63,13 +70,29 @@ function stripFencedCode(markdown) {
     .replace(/(^|[^`])`[^`\n]*`/g, (match) => match.replace(/[^\n]/g, ' '));
 }
 
+/**
+ * Blank the body of every block-level MDX component (`<Capitalised …> … </…>`)
+ * so a `$$…$$` used to illustrate a worked example inside `<CompactExample>`
+ * (or an `<Aside>`, etc.) is not counted as a lesson-body equation. The
+ * outermost match wins, so nested components are blanked in one pass;
+ * newlines are kept so line/section structure is unchanged.
+ */
+function stripJsxComponents(markdown) {
+  return String(markdown).replace(
+    /<([A-Z][A-Za-z0-9]*)(?:\s[^>]*)?>[\s\S]*?<\/\1>/g,
+    (block) => block.replace(/[^\n]/g, ' '),
+  );
+}
+
 /**
  * Every keyed display equation in a Markdown body, in appearance order, with
  * its assigned number. `$$…$$` blocks only; `##` headings between them advance
- * the section counter.
+ * the section counter. Every display block advances the in-section index, so a
+ * keyed equation's number reflects its position among *all* display equations,
+ * not only the keyed ones.
  */
 export function scanEquationLabels(markdown) {
-  const text = stripFencedCode(markdown);
+  const text = stripJsxComponents(stripFencedCode(markdown));
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
   const display = /\$\$([\s\S]+?)\$\$/g;
@@ -79,9 +102,11 @@ export function scanEquationLabels(markdown) {
   for (const match of text.matchAll(display)) {
     EQ_LABEL_PATTERN.lastIndex = 0;
     const label = EQ_LABEL_PATTERN.exec(match[1]);
-    if (label) {
-      tokens.push({ kind: 'equation', index: match.index, key: label[1] });
-    }
+    tokens.push({
+      kind: 'equation',
+      index: match.index,
+      key: label ? label[1] : null,
+    });
   }
   tokens.sort((a, b) => a.index - b.index);
 
@@ -95,6 +120,7 @@ export function scanEquationLabels(markdown) {
       continue;
     }
     indexInSection += 1;
+    if (token.key == null) continue;
     labels.push({
       key: token.key,
       number: equationNumber(section, indexInSection),
@@ -106,39 +132,49 @@ export function scanEquationLabels(markdown) {
 }
 
 /**
- * The mdast equivalent of `scanEquationLabels`: walk the tree in document
- * order, advancing the section counter on every depth-2 heading and emitting a
- * label for every `math` node whose source carries `\label{eq:…}`.
+ * 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`.
  */
-export function collectEquationLabels(tree) {
-  const labels = [];
+export function collectDisplayEquations(tree) {
+  const equations = [];
   let section = 0;
   let indexInSection = 0;
 
-  const walk = (node) => {
-    if (!node || typeof node !== 'object') return;
+  // 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;
-      return;
+      continue;
     }
     if (node.type === 'math') {
+      indexInSection += 1;
       EQ_LABEL_PATTERN.lastIndex = 0;
       const label = EQ_LABEL_PATTERN.exec(String(node.value ?? ''));
-      if (label) {
-        indexInSection += 1;
-        labels.push({
-          key: label[1],
-          number: equationNumber(section, indexInSection),
-          section,
-          indexInSection,
-          node,
-        });
-      }
-      return;
+      equations.push({
+        key: label ? label[1] : null,
+        number: equationNumber(section, indexInSection),
+        section,
+        indexInSection,
+        node,
+      });
     }
-    if (Array.isArray(node.children)) node.children.forEach(walk);
-  };
-  walk(tree);
-  return labels;
+  }
+  return equations;
+}
+
+/**
+ * The keyed subset of `collectDisplayEquations` — the tree-walk counterpart of
+ * `scanEquationLabels`. Numbers reflect position among all display equations.
+ */
+export function collectEquationLabels(tree) {
+  return collectDisplayEquations(tree).filter(
+    (equation) => equation.key != null,
+  );
 }

package/dist/reference/gate-math.d.ts

@@ -4,10 +4,11 @@ interface MathGateDiagnostic {
     readonly context: 'body' | 'formula' | 'assessment';
     /**
      * Body / component-slot math blocks the build (the render path needs every
-     * glyph resolved for the KaTeX trust callback). `formula` and `assessment`
-     * math enter as warnings (Tier 3) and are promoted once existing content is
-     * brought into line — they surface pre-existing ambiguities that are a
-     * separate reviewed content pass (D6/D13/D14), not a D3 codemod.
+     * 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).
      */
     readonly severity: 'error' | 'warning';
     readonly file: string;