explico 0.7.0 → 0.11.0

package/src/rules/catalog.ts

@@ -0,0 +1,1298 @@
+/**
+ * The rule catalog — every authoring rule and every always-on invariant the
+ * engine enforces, as data.
+ *
+ * The prose of a rule (rationale, how to apply, examples) lives in
+ * `docs/authoring/<area>.md`; this module holds only what a machine needs:
+ * the permanent ID, the element(s) a rule affects, the diagnostic codes it
+ * owns and where they are emitted, its settings, and whether a course may
+ * turn it off. `scripts/agent/gen-rules.mjs` renders the README index from
+ * it and checks the `.md` files against it; `tests/rules/catalog.test.ts`
+ * fails when a code is emitted that no entry owns, or when two entries claim
+ * one code. See `docs/plans/rule-catalog.md` for the design.
+ *
+ * Two kinds of entry share the catalog:
+ *
+ * - A **rule** is a choice — a house style that could have gone another way.
+ *   It has a lettered ID and, unless `locked`, a checkbox in the course
+ *   settings (`rules.<ID>.enabled`). A rule that is retired leaves this list
+ *   for the compact {@link RetiredRule} one, which costs a reader four lines
+ *   instead of a whole entry.
+ * - An **invariant** is what the syntax means — a `[[key]]` must resolve, a
+ *   `\label{eq:…}` key is unique. One entry per feature, always on,
+ *   documented next to the syntax rather than as a rule page.
+ *
+ * Enforcement is never typed by hand: it is derived from `checks` and
+ * `unchecked` by {@link enforcementOf}.
+ */
+
+/** The part of a page a rule is about. The first tag on an entry is primary. */
+export type Element =
+  | 'prose'
+  | 'math'
+  | 'equation'
+  | 'notation'
+  | 'heading'
+  | 'part-page'
+  | 'plot'
+  | 'diagram'
+  | 'table'
+  | 'assessment'
+  | 'source'
+  | 'changelog';
+
+/** Every element, in the order the rules-in-effect page lists them. */
+export const ELEMENTS: readonly Element[] = [
+  'prose',
+  'math',
+  'equation',
+  'notation',
+  'heading',
+  'part-page',
+  'plot',
+  'diagram',
+  'table',
+  'assessment',
+  'source',
+  'changelog',
+];
+
+/**
+ * The five areas the engine ships, plus `X` — reserved for a course's own rules
+ * and never used by an engine rule (see {@link CourseRuleId}).
+ */
+export type RuleArea = 'N' | 'V' | 'C' | 'S' | 'P' | 'X';
+export type RuleId = `${RuleArea}${number}`;
+
+/**
+ * A course's own rule, defined in `courseRules` in the course settings rather
+ * than here (`src/rules/course-rules.ts`). `X` is permanently reserved for
+ * them: the engine never ships an `X` rule, so a course can number its own
+ * `X1`, `X2`, … without a future engine release colliding with them. The form
+ * is the same as an engine rule's, so one ID works everywhere — a commit
+ * message, a diagnostic, a waiver, the rules-in-effect page.
+ */
+export type CourseRuleId = `X${number}`;
+
+const COURSE_RULE_ID = /^X[1-9][0-9]?$/;
+
+/** True for a well-formed course-rule ID (`X1`…`X99`). */
+export function isCourseRuleId(id: string): id is CourseRuleId {
+  return COURSE_RULE_ID.test(id);
+}
+
+export type Severity = 'error' | 'warning' | 'info';
+
+/** Where a code is emitted: engine source module + the function that pushes it. */
+export interface Emitter {
+  /** Repo-relative engine source path, e.g. `src/reference/gate-heading-length.ts`. */
+  readonly module: string;
+  /** A `function`/`const` name in that module; existence-checked by the tests. */
+  readonly fn: string;
+}
+
+export interface RuleCheck {
+  /** The `code` the diagnostic carries. Unique across the whole catalog. */
+  readonly code: string;
+  readonly severity: Severity;
+  readonly emitters: readonly [Emitter, ...Emitter[]];
+  /**
+   * True when a lesson-body emission carries `file` + `line`, so a per-place
+   * waiver can target it. Corpus-level and per-file checks are `false`.
+   */
+  readonly located: boolean;
+}
+
+/** A course-settable parameter of a rule — a tiny JSON-Schema subset. */
+export type SettingSchema =
+  | { readonly type: 'integer'; readonly minimum?: number; readonly default: number }
+  | { readonly type: 'boolean'; readonly default: boolean }
+  | { readonly type: 'array'; readonly items: 'string'; readonly default: readonly string[] };
+
+export interface SettingSpec {
+  readonly key: string;
+  readonly title: string;
+  readonly description: string;
+  readonly schema: SettingSchema;
+}
+
+export interface RuleEntry {
+  readonly kind: 'rule';
+  /** Permanent. A rule that is retired keeps its ID in {@link RetiredRule}. */
+  readonly id: RuleId;
+  /** The bold first sentence of the rule page, verbatim. */
+  readonly title: string;
+  /** Index-table phrasing, one line; the README row uses it over `title`. */
+  readonly short?: string;
+  readonly elements: readonly [Element, ...Element[]];
+  /**
+   * Path + anchor under `docs/authoring/`, e.g. `notation.md#n9`. On a course
+   * rule (`source: 'course'`) it is instead a link the course owns, used as
+   * given.
+   */
+  readonly doc: string;
+  /** What an agent needs in order to comply — at most three sentences, no rationale. */
+  readonly summary: string;
+  readonly checks: readonly RuleCheck[];
+  /** What no script sees. Present → enforcement is `partial`. */
+  readonly unchecked?: string;
+  /** Why the rule has no checkbox. */
+  readonly locked?: string;
+  readonly settings?: readonly SettingSpec[];
+  /**
+   * Set only on the synthetic entry built from a course's own `courseRules`
+   * block (`courseRuleEntry`). The static catalog never sets it, so `source`
+   * absent means "shipped with the engine".
+   */
+  readonly source?: 'course';
+}
+
+export interface InvariantEntry {
+  readonly kind: 'invariant';
+  /** A feature slug, e.g. `notation-references`. */
+  readonly id: string;
+  readonly title: string;
+  readonly elements: readonly [Element, ...Element[]];
+  readonly doc: string;
+  readonly summary: string;
+  readonly checks: readonly [RuleCheck, ...RuleCheck[]];
+}
+
+export type CatalogEntry = RuleEntry | InvariantEntry;
+
+export type Enforcement = 'script' | 'partial' | 'guide';
+
+// --- emitters ------------------------------------------------------------
+
+const GATE_MATH: Emitter = { module: 'src/reference/gate-math.ts', fn: 'resolveInto' };
+const GLYPHS: Emitter = { module: 'src/reference/math-glyphs.mjs', fn: 'resolveMathGlyphs' };
+const REGISTRY: Emitter = { module: 'src/reference/registry.ts', fn: 'buildNotationRegistry' };
+const KEYED_FLOATS: Emitter = { module: 'src/reference/keyed-float-validate.ts', fn: 'validateKeyedFloats' };
+
+function consistency(fn: string): Emitter {
+  return { module: 'src/reference/consistency.ts', fn };
+}
+
+function check(
+  code: string,
+  severity: Severity,
+  located: boolean,
+  ...emitters: [Emitter, ...Emitter[]]
+): RuleCheck {
+  return { code, severity, emitters, located };
+}
+
+/**
+ * `{eq,tab,fig,dia,check}-<suffix>` — the keyed-float family shares one
+ * validator — plus `sec-ref-resolves` for a `[[sec-…]]` to a heading, and
+ * `fold-unnamed` for a `<Fold>` with nothing to name its bar by.
+ */
+function keyedFloatChecks(): RuleCheck[] {
+  const out: RuleCheck[] = [];
+  for (const prefix of ['eq', 'tab', 'fig', 'dia', 'ex', 'check'] as const) {
+    const emitter: Emitter =
+      prefix === 'eq'
+        ? { module: 'src/reference/equations-validate.ts', fn: 'validateEquations' }
+        : prefix === 'check'
+          ? { module: 'src/reference/knowledge-checks-validate.ts', fn: 'validateKnowledgeChecks' }
+          : KEYED_FLOATS;
+    // An equation's key is validated by the `\label{eq:…}` pattern itself, so
+    // there is no `eq-invalid-key`; the JSX floats and checks report one.
+    if (prefix !== 'eq') out.push(check(`${prefix}-invalid-key`, 'error', false, emitter));
+    out.push(
+      check(`${prefix}-duplicate-key`, 'error', false, emitter),
+      check(`${prefix}-ref-resolves`, 'error', false, emitter),
+    );
+    if (prefix === 'tab' || prefix === 'fig' || prefix === 'dia' || prefix === 'ex') {
+      out.push(check(`${prefix}-key-unused`, 'info', false, emitter));
+      // A prop that is gone: a name prop the caption pair (`caption` +
+      // `short`) replaced — a figure's `title`, a diagram's `label`, an
+      // example set's `summary` — or a diagram's compaction props
+      // (`defaultOpen`, `rememberState`). The shared validator checks every
+      // JSX float; a table never had one to remove.
+      out.push(check(`${prefix}-removed-prop`, 'error', false, emitter));
+    }
+  }
+  // A worked-example set cannot do without its `id` (its anchor and
+  // `[[ex-…]]`) or its `short` title (its heading after the "Example" badge).
+  out.push(
+    check('ex-missing-prop', 'error', false, {
+      module: 'src/reference/examples-validate.ts',
+      fn: 'validateExamples',
+    }),
+  );
+  // A section's key is its heading's anchor, which the slugger makes unique,
+  // so only the reference can go wrong.
+  out.push(
+    check('sec-ref-resolves', 'error', true, {
+      module: 'src/reference/sections-validate.ts',
+      fn: 'validateSectionRefs',
+    }),
+  );
+  // A `<Fold>` is named by its `label`, or by the numbered floats it holds;
+  // one with neither has an empty bar.
+  out.push(
+    check('fold-unnamed', 'error', false, {
+      module: 'src/reference/folds-validate.ts',
+      fn: 'validateFolds',
+    }),
+  );
+  return out;
+}
+
+// --- settings shared by several rules ----------------------------------------
+
+function baselineEdits(what: string): readonly SettingSpec[] {
+  return [
+    {
+      key: 'allow',
+      title: 'Also allow',
+      description: `${what} this course treats as universal, in addition to the shipped list.`,
+      schema: { type: 'array', items: 'string', default: [] },
+    },
+    {
+      key: 'deny',
+      title: 'Always explain',
+      description: `Shipped ${what.toLowerCase()} this course still wants explained.`,
+      schema: { type: 'array', items: 'string', default: [] },
+    },
+  ];
+}
+
+// --- the catalog ---------------------------------------------------------
+
+const RULES: readonly RuleEntry[] = [
+  // ---- N — notation ------------------------------------------------------
+  {
+    kind: 'rule',
+    id: 'N2',
+    short: 'A reserved spelling is used only for its reserved meaning',
+    title:
+      'A reserved spelling means only what it is reserved for, and every other styled letter is a symbol of its own.',
+    elements: ['math'],
+    doc: 'notation.md#n2',
+    summary:
+      'The `reserved` setting is this course’s table of spellings that are fixed to one meaning — nothing else may use them, and they need no notation key. Every *other* styled letter (`\\mathbb{E}`, `\\mathcal{L}`, an italic `d` used as a variable) is an ordinary symbol that needs a notation entry of its own, even when the plain letter has one (N4).',
+    checks: [],
+    settings: [
+      {
+        key: 'reserved',
+        title: 'Reserved spellings',
+        description:
+          'One `<latex> — <meaning>` line per spelling this course fixes to a single meaning, printed on the rules-in-effect page so an author or an agent reads the table without opening the rule page. Nothing checks it — which spelling was chosen is caught in review; rule N4’s gate only asks that a glyph resolve. Replace the shipped list to change the conventions: drop the probability lines in a course with no probability, or write `\\mathcal{N}(\\mu, \\sigma)` for a course that parameterises the normal by standard deviation.',
+        schema: {
+          type: 'array',
+          items: 'string',
+          default: [
+            '\\mathbb{N} — the natural numbers',
+            '\\mathbb{Z} — the integers',
+            '\\mathbb{R} — the reals',
+            '\\mathbb{C} — the complex numbers',
+            '\\mathbb{P} — probability',
+            '\\mathcal{N}(\\mu, \\sigma^2) — the normal distribution (mean, variance)',
+            '\\mathrm{d} — the differential',
+          ],
+        },
+      },
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'N4',
+    short: 'One meaning per glyph; define once; `[[key]]` before first math',
+    title:
+      'One meaning per glyph per page; define once; introduce with `[[key]]` before the first math use.',
+    elements: ['math', 'notation'],
+    doc: 'notation.md#n4',
+    summary:
+      'Every glyph in rendered math resolves to exactly one notation entry on the page: introduce it with `[[key]]` in prose before its first `$…$`, define a page-local one in `notation.local`, or bind a compound with `\\explain{key}{latex}`. Do not reuse a glyph for a second meaning on the same page.',
+    checks: [
+      check('unresolved-glyph', 'error', true, GATE_MATH),
+      check('glyph-unique-in-corpus', 'warning', false, consistency('checkGlyphUniqueness')),
+      check('weak-local', 'info', false, consistency('checkWeakLocal')),
+      check('gloss-wants-promoting', 'info', false, consistency('checkGlossWantsPromoting')),
+      check('card-wants-demoting', 'info', false, consistency('checkCardWantsDemoting')),
+    ],
+    locked:
+      'the notation layer is this rule — an unresolved glyph has no hover card and the render path needs every glyph bound.',
+  },
+  {
+    kind: 'rule',
+    id: 'N5',
+    short: 'Referenced display equations carry `\\label{eq:key}`',
+    title: 'A display equation referenced later carries `\\label{eq:key}`.',
+    elements: ['equation'],
+    doc: 'notation.md#n5',
+    summary:
+      'Label a display equation with `\\label{eq:key}` when — and only when — prose refers back to it with `[[eq-key]]`. A label nothing references is noise.',
+    checks: [
+      check('eq-key-unused', 'info', false, {
+        module: 'src/reference/equations-validate.ts',
+        fn: 'validateEquations',
+      }),
+    ],
+    unchecked: 'that a referenced-in-prose equation actually carries a label.',
+  },
+  {
+    kind: 'rule',
+    id: 'N8',
+    short: 'A named operator is universal (shipped/course list) or explained',
+    title: 'A named operator is universal, or it is explained.',
+    elements: ['math', 'notation'],
+    doc: 'notation.md#n8',
+    summary:
+      'An operator such as `\\sin` or `\\operatorname{Var}` is either on the shipped universal list (plus the course’s `allow` list) or has a notation entry. The `deny` list forces an entry for a shipped one.',
+    checks: [
+      check('operator-explained', 'warning', false, consistency('checkOperatorExplained')),
+    ],
+    settings: baselineEdits('Operators'),
+  },
+  {
+    kind: 'rule',
+    id: 'N9',
+    short: 'A quantity/unit/operator is typeset in `$…$`, never as plain text',
+    title:
+      'A physical quantity, unit, or math operator is typeset in `$…$`, never as plain text — in prose, a table cell, an assessment `prompt` / `explanation`, or a caption that itself lives outside math.',
+    elements: ['prose', 'assessment', 'table'],
+    doc: 'notation.md#n9',
+    summary:
+      'Never write `45 m/s`, `t (s)`, `vx` or `KE/m` as plain text, and never spell a stated quantity\'s unit out: "4 seconds", "2 meters per second squared", "30 degrees", "$x = 3$ meters" are `$4\\ \\text{s}$`, `$2\\ \\text{m/s}^2$`, `$30^{\\circ}$`, `$x = 3\\ \\text{m}$`. A unit inside math is `\\text{}`-wrapped, short form, in the same span as its number or symbol. A unit named on its own ("measured in meters") stays a word; a sentence that defines a unit is waived. JSX prop strings (`caption="…"`) and assessment choice labels render no math, so N9 does not apply there.',
+    checks: [
+      check(
+        'prose-notation',
+        'error',
+        true,
+        { module: 'src/reference/gate-prose-notation.ts', fn: 'gateProseNotation' },
+        { module: 'src/reference/gate-prose-notation.ts', fn: 'gateProseNotationInAssessments' },
+      ),
+      check(
+        'spelled-unit',
+        'error',
+        true,
+        { module: 'src/reference/gate-prose-notation.ts', fn: 'gateProseNotation' },
+        { module: 'src/reference/gate-prose-notation.ts', fn: 'gateProseNotationInAssessments' },
+      ),
+    ],
+    settings: [
+      {
+        key: 'allow',
+        title: 'Unit words prose may spell out',
+        description:
+          'Unit words (`hour`, `minute`) this course lets prose write out next to a number or `per`, singular or plural. Every other unit in `unit-words.ts` must be a symbol in `$…$`.',
+        schema: { type: 'array', items: 'string', default: [] },
+      },
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'N10',
+    short: 'A multi-letter label is `\\mathrm{…}`, and universal or explained',
+    title:
+      'A multi-letter roman label is written `\\mathrm{…}`, and it is universal or it is explained.',
+    elements: ['math', 'notation'],
+    doc: 'notation.md#n10',
+    summary:
+      'Write a word-like label inside math as `\\mathrm{KE}`, `v_{\\mathrm{max}}` — never a bare run of italic letters, which reads as a product. The label itself is on the shipped list (plus `allow`) or has a notation entry: the glyph resolver skips a `\\mathrm{}` body, so nothing else gives it a hover card.',
+    checks: [
+      check('roman-label-explained', 'warning', false, consistency('checkRomanLabelExplained')),
+    ],
+    unchecked:
+      'that a bare multi-letter run was wrapped in `\\mathrm{…}` at all — rule N4’s gate reports it as unresolved one-letter symbols, which is a different message for the same mistake.',
+    settings: baselineEdits('Roman labels'),
+  },
+  {
+    kind: 'rule',
+    id: 'N11',
+    short: 'A worked example never drops a unit from a substituted value',
+    title:
+      'A worked example never drops a unit from a substituted value, and its result is dimensionally consistent.',
+    elements: ['math', 'prose'],
+    doc: 'notation.md#n11',
+    summary:
+      'When numbers replace symbols, every value keeps its unit (`$v = 3\\ \\text{m/s} \\cdot 4\\ \\text{s}$`), and the result’s unit follows from them.',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'N12',
+    short: 'Math syntax never carries the sentence\'s own trailing punctuation',
+    title: 'Math syntax never carries the sentence’s own trailing punctuation.',
+    elements: ['math', 'prose', 'assessment'],
+    doc: 'notation.md#n12',
+    summary:
+      'Math, and each row before a `\\\\`, never ends in `.`, `,`, `;` or `:` — the sentence’s own punctuation goes after the closing `$`, or is dropped after a display block. A trailing decimal point (`5.`) and a typed `...` count too. The only exception is an upright dotted abbreviation that is notation (`\\text{h.c.}`): the shipped list plus `allow`.',
+    checks: [
+      check(
+        'math-trailing-punctuation',
+        'error',
+        true,
+        { module: 'src/reference/gate-math-punctuation.ts', fn: 'gateMathPunctuation' },
+        { module: 'src/reference/gate-math-punctuation.ts', fn: 'gateMathPunctuationInAssessments' },
+      ),
+    ],
+    settings: [
+      {
+        key: 'allow',
+        title: 'Also allow',
+        description:
+          'Dotted abbreviations this course sets as notation at the end of math (`\\text{w.p.}`), in addition to the shipped `a.e.`, `a.s.`, `c.c.`, `const.`, `h.c.`, `i.i.d.`.',
+        schema: { type: 'array', items: 'string', default: [] },
+      },
+      {
+        key: 'deny',
+        title: 'Never allow',
+        description: 'Shipped abbreviations this course does not accept at the end of math.',
+        schema: { type: 'array', items: 'string', default: [] },
+      },
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'N13',
+    short: 'A nonlinear function always takes a parenthesized argument',
+    title:
+      'A nonlinear function always takes a parenthesized argument, even a single symbol.',
+    elements: ['math'],
+    doc: 'notation.md#n13',
+    summary: 'Write `\\sin(x)`, `\\ln(t)`, `f(x)` — never `\\sin x`.',
+    checks: [check('unparenthesized-function', 'error', true, GLYPHS)],
+    locked:
+      'the glyph resolver cannot tell where an unparenthesized argument ends, so it cannot bind the symbols inside it.',
+  },
+  {
+    kind: 'rule',
+    id: 'N14',
+    short: 'An abbreviation-shaped word in prose is universal, or explained',
+    title: 'An abbreviation-shaped word in prose is universal, or it is explained.',
+    elements: ['prose'],
+    doc: 'notation.md#n14',
+    summary:
+      'An all-caps or dotted token in prose (`OLS`, `w.r.t.`) is on the shipped list (plus `allow`) or has an entry in `content/abbreviations/`.',
+    checks: [
+      check('abbreviation-unexplained', 'error', true, {
+        module: 'src/reference/gate-abbreviations.ts',
+        fn: 'gateAbbreviations',
+      }),
+    ],
+    settings: baselineEdits('Abbreviations'),
+  },
+  {
+    kind: 'rule',
+    id: 'N15',
+    short: 'A nested `(`, `[`, `{`, or `|` must use scalable sizing',
+    title:
+      'A nested visible delimiter — `(`, `[`, `\\{`, or `|` inside another one of them — must use the scalable `\\left`/`\\right` form, not the bare character.',
+    elements: ['math'],
+    doc: 'notation.md#n15',
+    summary:
+      'Inside another delimiter pair, write `\\left( … \\right)`, `\\left| … \\right|`; a bare nested `|` or `(` fails the build.',
+    checks: [check('nested-bare-delimiter', 'error', true, GLYPHS)],
+    locked:
+      'a bare `|` is both an opener and a closer; nested, the resolver cannot pair it, so the rule is a parsing precondition.',
+  },
+  {
+    kind: 'rule',
+    id: 'N17',
+    short: 'A delimiter’s shape is semantic; a nest is engine-sized, not hand-sized',
+    title:
+      'A delimiter’s shape carries its meaning and never changes to show nesting: a nest is sized by the engine — `\\left ... \\right` at every level, never `\\bigl`, `\\Bigl`, `\\biggl`, or `\\Biggl` inside it.',
+    elements: ['math'],
+    doc: 'notation.md#n17',
+    summary:
+      'Keep the shape each delimiter has for its meaning — an interval `[a, b)`, a norm `\\|·\\|`, a set `\\{…\\}`, a parenthesis for grouping — and never swap shapes (`( [ \\{ … \\} ] )`) to mark depth. Depth is size: write `\\left`/`\\right` at every level and let the engine size them, never `\\bigl…\\bigr` and friends inside a nest.',
+    checks: [
+      check('delimiter-manual-size', 'warning', true, {
+        module: 'src/reference/delimiter-size.ts',
+        fn: 'lintDelimiterSizes',
+      }),
+    ],
+    unchecked:
+      'the shape half — `delimiter-manual-size` parses sizing syntax only, and never decides whether a bracket is semantic. A bare nested delimiter is rule N15’s error instead.',
+  },
+  {
+    kind: 'rule',
+    id: 'N18',
+    short: 'A multi-step derivation is one aligned chain; reasons follow `\\qquad`',
+    title:
+      'Write a multi-step derivation as one chain: one step per line, aligned at the relation sign, with any justification on the same line after `\\qquad`.',
+    elements: ['equation'],
+    doc: 'notation.md#n18',
+    summary:
+      'A derivation is one `aligned` block: each step on its own line, `&=` at the relation, the reason after `\\qquad` on the same line — not a run of separate display equations.',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'N19',
+    short: 'A notation entry states `units` from the vocabulary, or `dimensionless`',
+    title:
+      'A notation entry states its `units`, or declares itself `dimensionless`, using the units vocabulary.',
+    elements: ['notation'],
+    doc: 'notation.md#n19',
+    summary:
+      'Every notation entry has `units:` from `units-vocab.ts` (`m/s`, `s`, `kg`, …) or `dimensionless: true`. A token outside the vocabulary is a warning.',
+    checks: [
+      check('notation-units', 'warning', false, consistency('checkNotationUnits')),
+      check('units-vocab', 'warning', false, consistency('checkNotationUnits')),
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'N20',
+    short: 'A notation entry\'s source citation carries a locator',
+    title: 'A notation entry’s source citation carries a locator.',
+    elements: ['notation', 'source'],
+    doc: 'notation.md#n20',
+    summary:
+      'Each item in a notation entry’s `sources` names the place in the source (`locator: "§3.2"`, `"p. 41"`), not just the source id.',
+    checks: [
+      check('notation-source-locator', 'warning', false, consistency('checkNotationSourceLocator')),
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'N21',
+    short: 'A gloss is named by a short noun phrase, not a sentence',
+    title: 'A gloss is named by a short noun phrase, not described by a sentence.',
+    elements: ['notation'],
+    doc: 'notation.md#n21',
+    summary:
+      'A gloss `label` names the symbol in a few words (“launch angle”); a clause, sentence punctuation, or a definition belongs in a full notation entry instead.',
+    checks: [check('gloss-name-shape', 'warning', false, consistency('checkGlossNameShape'))],
+  },
+  {
+    kind: 'rule',
+    id: 'N22',
+    short: 'An accent or mark is an operator: universal, explained, or a whole form',
+    title:
+      'An accent or mark on a symbol is an operator: universal, explained, or part of the symbol’s own entry.',
+    elements: ['math', 'notation'],
+    doc: 'notation.md#n22',
+    summary:
+      'A decoration (`\\hat`, `\\bar`, `\\overline`, `\'`, `^*`, `^\\dagger`, …) is on the course’s `allow` list (shipped empty), explained by an operator entry (`latex: \\hat{}`), or the decorated form has its own entry (`latex: \\hat{\\beta}`), which wins for that form. A page may suspend a decoration in `notation.suspend`, with a `reason`; every decorated form of it there then needs its own entry.',
+    checks: [
+      check('accent-explained', 'warning', false, consistency('checkAccentExplained')),
+      check('suspended-operator-unresolved', 'error', true, GATE_MATH),
+      check('operator-suspension-reason', 'warning', false, consistency('checkOperatorSuspension')),
+      check('operator-suspended', 'info', false, consistency('checkOperatorSuspension')),
+      check('operator-shadowed', 'info', false, consistency('checkOperatorSuspension')),
+    ],
+    settings: baselineEdits('Decorations'),
+  },
+
+  // ---- V — visualizations -----------------------------------------------------
+  {
+    kind: 'rule',
+    id: 'V1',
+    short: 'Graphs and flowcharts use the `Diagram` component',
+    title: 'Graphs and flowcharts use the `Diagram` component.',
+    elements: ['diagram'],
+    doc: 'visualizations.md#v1',
+    summary:
+      'A node-and-edge picture — a dependency graph, a flowchart — is a `<Diagram id="…">` with its nodes and formulas declared, never a hand-drawn SVG or an image.',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'V2',
+    short: 'Static charts: SVG → D3 → Observable Plot, chosen per figure',
+    title:
+      'Static charts: hand-rolled SVG first, then D3, then Observable Plot — chosen per figure.',
+    elements: ['plot'],
+    doc: 'visualizations.md#v2',
+    summary:
+      'For a static chart pick the lightest tool that draws it: inline SVG, then D3, then Observable Plot. State the choice in the figure’s source comment.',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'V3',
+    short: 'Interactive figures: a hydrated island + the `renderLabMath` seam',
+    title:
+      'Interactive figures: a hydrated island and the `renderLabMath` seam for equations.',
+    elements: ['plot'],
+    doc: 'visualizations.md#v3',
+    summary:
+      'An interactive figure is an island under `content/labs/` inside a `<Figure>`, renders its equations through `renderLabMath`, and labels its controls; the figure’s caption is its name, so the lab writes no accessible name or text alternative of its own.',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'V4',
+    short: 'Randomised figures expose an adjustable, deterministic seed',
+    title: 'A randomised figure exposes an adjustable, deterministic seed.',
+    elements: ['plot'],
+    doc: 'visualizations.md#v4',
+    summary:
+      'Randomness in a figure comes from a seed the reader can see and change; the same seed always draws the same picture.',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'V5',
+    short: 'Axis ranges span the first 10 seeds at the current control values',
+    title:
+      'Axis ranges span the first 10 seeds, evaluated at the current values of every other control.',
+    elements: ['plot'],
+    doc: 'visualizations.md#v5',
+    summary:
+      'Fix each axis range so the drawings for seeds 1…`seeds` all fit at the current control values; the axes do not jump when the seed changes.',
+    checks: [],
+    settings: [
+      {
+        key: 'seeds',
+        title: 'Seeds spanned',
+        description: 'How many leading seeds an axis range must accommodate.',
+        schema: { type: 'integer', minimum: 1, default: 10 },
+      },
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'V6',
+    short: 'Every quantitative axis shows at least three labelled values',
+    title: 'Every quantitative axis of a chart shows at least three labelled values.',
+    elements: ['plot'],
+    doc: 'visualizations.md#v6',
+    summary:
+      'Each numeric axis carries at least `minLabels` tick labels, so a reader can read a value off the chart.',
+    checks: [],
+    settings: [
+      {
+        key: 'minLabels',
+        title: 'Minimum axis labels',
+        description: 'Labelled tick values a quantitative axis must show.',
+        schema: { type: 'integer', minimum: 2, default: 3 },
+      },
+    ],
+  },
+
+  // ---- C — versioning ---------------------------------------------------------
+  {
+    kind: 'rule',
+    id: 'C1',
+    short: 'Every content change lands with a `content/CHANGELOG.md` entry',
+    title:
+      'Every content change lands with a `content/CHANGELOG.md` entry under `## [Unreleased]`.',
+    elements: ['changelog'],
+    doc: 'versioning.md#c1',
+    summary:
+      'Any edit under `content/` adds a bullet to `content/CHANGELOG.md` under `## [Unreleased]` in the same commit.',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'C2',
+    short: 'The knowledge version is semver over learning-facing content',
+    title: 'The knowledge version is semver over learning-facing content.',
+    elements: ['changelog'],
+    doc: 'versioning.md#c2',
+    summary:
+      'Bump `about.version` MAJOR when a lesson, competency, notation key or stated outcome is removed or changed; MINOR for something new; PATCH for a fix or clarification.',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'C3',
+    short: '`about.version` equals the newest changelog heading; a release moves both',
+    title:
+      '`about.version` equals the newest `## [x.y.z]` heading in `content/CHANGELOG.md`, and a release moves `## [Unreleased]` and bumps `about.version` in one commit.',
+    elements: ['changelog'],
+    doc: 'versioning.md#c3',
+    summary:
+      'The version in `course.config.ts` and the newest dated heading in `content/CHANGELOG.md` are the same string. On a release, rename `## [Unreleased]` to `## [x.y.z] - <date>`, open a fresh empty `## [Unreleased]` above it, and set `about.version` to that `x.y.z` — in one commit. Between releases `about.version` stays at the last released value.',
+    checks: [
+      check('knowledge-version-mismatch', 'warning', false, {
+        module: 'src/compiler/knowledge-version.ts',
+        fn: 'resolveKnowledgeVersion',
+      }),
+      check('knowledge-version-invalid', 'warning', false, {
+        module: 'src/compiler/knowledge-version.ts',
+        fn: 'resolveKnowledgeVersion',
+      }),
+      check('knowledge-changelog-missing', 'warning', false, {
+        module: 'src/compiler/knowledge-version.ts',
+        fn: 'resolveKnowledgeVersion',
+      }),
+    ],
+    unchecked:
+      'that the two edits landed in one commit — the build only ever sees the end state, so a release split across commits warns until the second half lands.',
+  },
+
+  // ---- S — structure ----------------------------------------------------------
+  {
+    kind: 'rule',
+    id: 'S1',
+    short: 'No heading, short caption or short-note title over 65 characters',
+    title:
+      'No heading, no short caption (`short`, an equation’s `\\caption{}`) and no short-note title runs past 65 characters.',
+    elements: ['heading'],
+    doc: 'structure-rules.md#s1',
+    summary:
+      'A Markdown heading, the `short` caption of a `Figure`, `Diagram`, `Table`, `Memo` or `CompactExamples`, an equation’s `\\caption{}` and a `ShortNote` `title` are short noun phrases of at most `maxLength` characters; the claim goes in the prose or the long `caption`, which is never measured.',
+    checks: [
+      check('title-length', 'error', true, {
+        module: 'src/reference/gate-heading-length.ts',
+        fn: 'gateHeadingLength',
+      }),
+    ],
+    unchecked: 'a lesson’s `frontmatter.title` — the gate scans the body only.',
+    settings: [
+      {
+        key: 'maxLength',
+        title: 'Maximum length',
+        description: 'Characters a heading or short caption may run to.',
+        schema: { type: 'integer', minimum: 20, default: 65 },
+      },
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'S2',
+    short: 'A part page carries a `<PartBridge>` (earlier parts → this one) and a `<PartScope>` paragraph',
+    title:
+      'A part’s overview page carries two authored paragraphs: a `<PartBridge>` on how the earlier parts lead into this one, then a `<PartScope>` on what this part covers.',
+    elements: ['part-page'],
+    doc: 'structure-rules.md#s2',
+    summary:
+      'A `content/docs/<dir>/index.mdx` has one `<PartBridge>` paragraph (optional on the first part) then one `<PartScope>` paragraph, each inside the word range, before `<PartOverview />`. Keep a blank line inside each tag.',
+    checks: [
+      check('part-page-paragraph', 'error', false, {
+        module: 'src/reference/gate-part-pages.ts',
+        fn: 'gatePartPages',
+      }),
+    ],
+    unchecked:
+      'what each paragraph says — the gate cannot tell a bridge that links the parts from one that does not.',
+    settings: [
+      {
+        key: 'bridgeMinWords',
+        title: 'Bridge: minimum words',
+        description: 'Fewest words the `<PartBridge>` paragraph may have.',
+        schema: { type: 'integer', minimum: 1, default: 30 },
+      },
+      {
+        key: 'bridgeMaxWords',
+        title: 'Bridge: maximum words',
+        description: 'Most words the `<PartBridge>` paragraph may have.',
+        schema: { type: 'integer', minimum: 1, default: 150 },
+      },
+      {
+        key: 'scopeMinWords',
+        title: 'Scope: minimum words',
+        description: 'Fewest words the `<PartScope>` paragraph may have.',
+        schema: { type: 'integer', minimum: 1, default: 30 },
+      },
+      {
+        key: 'scopeMaxWords',
+        title: 'Scope: maximum words',
+        description: 'Most words the `<PartScope>` paragraph may have.',
+        schema: { type: 'integer', minimum: 1, default: 150 },
+      },
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'S3',
+    short: 'A table is a `<Table id="…">`, never a raw Markdown/HTML table',
+    title: 'A table is a `<Table id="…">`, never a raw Markdown or HTML table.',
+    elements: ['table'],
+    doc: 'structure-rules.md#s3',
+    summary:
+      'Wrap every pipe table or `<table>` in `<Table id="…" caption="…">` so it gets a number and `[[tab-…]]` can reach it.',
+    checks: [
+      check('raw-table-markdown', 'warning', false, {
+        module: 'src/reference/raw-floats-validate.ts',
+        fn: 'validateRawFloats',
+      }),
+      check('raw-table-html', 'warning', false, {
+        module: 'src/reference/raw-floats-validate.ts',
+        fn: 'validateRawFloats',
+      }),
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'S4',
+    short: 'A `<Diagram>` carries an `id` and sits where numbering can see it',
+    title: 'A `<Diagram>` carries an `id` and sits where diagram numbering can see it.',
+    elements: ['diagram'],
+    doc: 'structure-rules.md#s4',
+    summary:
+      'Give every `<Diagram>` an `id`, and place it at the top level or inside `<Memo>`/`<ShortNote>`/`<Table>`/`<Figure>` — a diagram nested elsewhere (e.g. in `<CompactExample>`) is never numbered.',
+    checks: [
+      check('diagram-unkeyed', 'warning', false, {
+        module: 'src/reference/raw-floats-validate.ts',
+        fn: 'validateRawFloats',
+      }),
+      check('diagram-nested', 'warning', false, {
+        module: 'src/reference/raw-floats-validate.ts',
+        fn: 'validateRawFloats',
+      }),
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'S5',
+    short: 'A sign / perspective convention is declared once and cited elsewhere',
+    title: 'A sign or perspective convention is declared once and cited everywhere else.',
+    elements: ['prose'],
+    doc: 'structure-rules.md#s5',
+    summary:
+      'Prose that states a sign / cash-flow-perspective convention resolves it to the single declaration — the `conventions.signConventionKey` notation entry (`[[key]]`) or the `conventions.cashFlowPerspectiveCompetency` competency — rather than restating it.',
+    checks: [
+      check(
+        'convention-single-definition',
+        'warning',
+        false,
+        consistency('checkConventionSingleDefinition'),
+      ),
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'S6',
+    short: 'Headings descend one level at a time, from `##`',
+    title:
+      'Headings descend one level at a time: a lesson body starts at `##` and never skips a level on the way down.',
+    elements: ['heading'],
+    doc: 'structure-rules.md#s6',
+    summary:
+      'The page title is the lesson’s only `#`, so the body’s first heading is `##`, and each heading is at most one level deeper than the one before it (`##` → `###`, never `##` → `####`); going back up any number of levels is fine. A knowledge check’s and a worked-example set’s heading count as a `##`.',
+    checks: [
+      check('heading-skip', 'error', true, {
+        module: 'src/reference/gate-heading-structure.ts',
+        fn: 'gateHeadingStructure',
+      }),
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'S7',
+    short: 'A heading is followed by body content, never by another heading',
+    title: 'A heading is followed by body content, never directly by another heading.',
+    elements: ['heading'],
+    doc: 'structure-rules.md#s7',
+    summary:
+      'Write body content — at least a sentence on what the section is about — between a heading and the next one, whatever their levels. `<AssessmentSet />` and `<CompactExamples>` draw an `<h2>` of their own, so no heading goes directly above either.',
+    checks: [
+      check('heading-adjacent', 'error', true, {
+        module: 'src/reference/gate-heading-structure.ts',
+        fn: 'gateHeadingStructure',
+      }),
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'S8',
+    short: 'Prefer `<Memo>` over a Starlight aside when the content needs an anchor, a caption or collapsing',
+    title:
+      'Use a `<Memo>`, not a Starlight aside, for content that deserves an anchor, a caption, or collapsing.',
+    elements: ['prose'],
+    doc: 'structure-rules.md#s8',
+    summary:
+      'A `:::note`/`:::tip`/`:::caution`/`:::danger` (or `<Aside>`) is a short callout read in passing: no number, no link, never folded. Anything a reader may want to cite, skip or come back to is a `<Memo id="…">`.',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'S9',
+    short: 'A float’s short caption names it; the long caption goes on from that name',
+    title:
+      'A float’s short caption names it, and its long caption goes on from that name instead of restating it; a figure holds no running text, and a lab’s instructions go in its tools.',
+    elements: ['plot', 'table', 'diagram'],
+    doc: 'structure-rules.md#s9',
+    summary:
+      'Give each figure, table and diagram a `short` caption that names it: it opens the caption line in bold, and names the float in "Hidden here", a copied link and the "Figures and tables" page. The long `caption` goes on from that name to say what the float shows — its subject, its marks and symbols, the case shown — and at most the one thing to notice. The argument drawn from a figure is lesson text after it, and a lab’s instructions are the first line of its `tools`.',
+    checks: [],
+  },
+
+  // ---- P — prose --------------------------------------------------------------
+  {
+    kind: 'rule',
+    id: 'P1',
+    short: '"or" never introduces a second name for the same thing',
+    title: 'Never use "or" to give a thing a second name.',
+    elements: ['prose'],
+    doc: 'prose.md#p1',
+    summary:
+      '“The residual, or error, is …” introduces a synonym; pick one name and use it. “or” joins alternatives, not names.',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'P2',
+    short: 'One term for each concept, repeated — no synonyms for variety',
+    title: 'Use one term for each concept, and repeat it.',
+    elements: ['prose'],
+    doc: 'prose.md#p2',
+    summary: 'Say “residual” every time; never rotate synonyms for variety.',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'P3',
+    short: 'One meaning for each term; no technical term in its everyday sense',
+    title: 'Give each term one meaning, and keep it.',
+    elements: ['prose'],
+    doc: 'prose.md#p3',
+    summary:
+      'A technical term keeps its technical meaning on the page; do not also use it in its everyday sense (“significant”, “normal”).',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'P4',
+    short: 'Use the established term; define it where the argument first needs it',
+    title: 'Use the established term, and define it where the argument first needs it.',
+    elements: ['prose'],
+    doc: 'prose.md#p4',
+    summary:
+      'Prefer the field’s standard term over a coined one, and define it at first use — not earlier in a glossary paragraph, not later.',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'P5',
+    short: 'Main text is literal: no idioms, metaphors, buzzwords, entertainment',
+    title:
+      'Write the main text literally: no idioms, metaphors, colloquialisms, buzzwords, or entertainment.',
+    elements: ['prose'],
+    doc: 'prose.md#p5',
+    summary:
+      'Main text states facts and steps plainly; no “let’s dive in”, no metaphor, no joke. An aside may be lighter.',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'P6',
+    short: 'Industry jargon only in an optional "Industry jargon" aside',
+    title:
+      'Keep industry jargon out of the main text. Put jargon that the reader must recognize in an optional "Industry jargon" aside.',
+    elements: ['prose'],
+    doc: 'prose.md#p6',
+    summary:
+      'Use the textbook term in the argument; list the trade’s words for it in an “Industry jargon” aside if the reader will meet them.',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'P7',
+    short: 'One claim per sentence; every logical link stated',
+    title: 'Write one claim per sentence, and state every logical link.',
+    elements: ['prose'],
+    doc: 'prose.md#p7',
+    summary:
+      'One assertion per sentence; “because”, “so”, “therefore” are written out, never left for the reader to infer.',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'P8',
+    short: 'Words for a relation match the math exactly ("proportional to")',
+    title: 'Words that state a relation say exactly what the mathematics says.',
+    elements: ['prose', 'math'],
+    doc: 'prose.md#p8',
+    summary:
+      '“Proportional to” means `y = kx`; “grows with” means monotone; “depends on” means a function of. Match the words to the formula.',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'P9',
+    short: 'A display equation\'s lead-in says what it gives and where it comes from',
+    title:
+      'Introduce a display equation with a sentence that says what it gives and where it comes from.',
+    elements: ['prose', 'equation'],
+    doc: 'prose.md#p9',
+    summary:
+      'The sentence before a display equation names the quantity it yields and the step or law it follows from — not “we have:”.',
+    checks: [],
+  },
+];
+
+/**
+ * A rule that is no longer in force. It keeps its ID forever — an old commit
+ * message, review comment or waiver naming `N3` must stay unambiguous — but it
+ * is deliberately *not* a {@link RuleEntry}: nothing iterates it as a rule, it
+ * has no page in `docs/authoring/`, it is absent from the settings schema and
+ * from `build/rules-in-effect.md`, and an agent never reads it while drafting.
+ * The one place it is written out is the generated table in
+ * `docs/authoring/retired.md`, which is where a migration guide links.
+ */
+export interface RetiredRule {
+  readonly id: RuleId;
+  /** The sentence the rule had, so an old reference to it still resolves. */
+  readonly title: string;
+  /** `YYYY-MM-DD`. */
+  readonly date: string;
+  /** The rule it was folded into, when it was folded into one. */
+  readonly into?: RuleId;
+  /** Why, and what changed for an author — one or two sentences. */
+  readonly why: string;
+}
+
+const RETIRED: readonly RetiredRule[] = [
+  {
+    id: 'N1',
+    title: 'The normal distribution is `\\mathcal{N}`.',
+    date: '2026-09-26',
+    into: 'N2',
+    why: 'One spelling fixed to one meaning is one rule; `\\mathcal{N}(\\mu, \\sigma^2)` is a line in N2’s `reserved` table, which a course can edit.',
+  },
+  {
+    id: 'N3',
+    title: 'Multi-letter roman labels use `\\mathrm{…}`.',
+    date: '2026-09-26',
+    into: 'N10',
+    why: 'Writing a label as `\\mathrm{…}` and explaining it are two halves of one rule, and N10 is where both are checked.',
+  },
+  {
+    id: 'N6',
+    title: 'Probability is `\\mathbb{P}` — double-struck `P`.',
+    date: '2026-09-26',
+    into: 'N2',
+    why: '`\\mathbb{P}` is a line in N2’s `reserved` table.',
+  },
+  {
+    id: 'N7',
+    title: 'The differential `d` is upright `\\mathrm{d}`.',
+    date: '2026-09-26',
+    into: 'N2',
+    why: '`\\mathrm{d}` is a line in N2’s `reserved` table.',
+  },
+  {
+    id: 'N16',
+    title:
+      'In AI-generated mathematical content, alternate delimiter types for nested grouping when their shape is stylistic; preserve every conventional or semantic delimiter shape.',
+    date: '2026-09-26',
+    into: 'N17',
+    why: 'Folded into N17 with the preference dropped: a delimiter’s shape carries its meaning, so depth is shown by size — which this engine handles automatically — not by alternating shapes. The rule also scoped itself to “AI-generated” content, which is not a property of the page.',
+  },
+  {
+    id: 'C4',
+    title:
+      'On a release, move `## [Unreleased]` to `## [x.y.z] - YYYY-MM-DD` and bump `about.version` in the same commit.',
+    date: '2026-09-26',
+    into: 'C3',
+    why: 'The release procedure and the invariant it keeps are one rule, and `knowledge-changelog-missing` (owned by C3) was already the check that fired on a half-finished release.',
+  },
+];
+
+const INVARIANTS: readonly InvariantEntry[] = [
+  {
+    kind: 'invariant',
+    id: 'notation-references',
+    title: 'Notation keys are well-formed, unique, defined, and acyclic.',
+    elements: ['notation', 'math'],
+    doc: 'components.md#reference-systems',
+    summary:
+      'A `[[key]]` or `\\explain{key}{…}` names an existing entry; a key is kebab-case; a shared entry is defined once; formula references never form a cycle.',
+    checks: [
+      check('undefined-reference', 'error', false, REGISTRY),
+      check('invalid-key', 'error', false, REGISTRY, GLYPHS),
+      check('duplicate-key', 'error', false, GLYPHS),
+      check('duplicate-page', 'error', false, REGISTRY),
+      check('duplicate-definition', 'error', false, REGISTRY),
+      check('conflicting-definition', 'error', false, REGISTRY),
+      check('reference-cycle', 'error', false, REGISTRY),
+      check('gloss-collides-with-card', 'error', false, REGISTRY),
+      check('unknown-explicit-key', 'error', true, GLYPHS, {
+        module: 'src/reference/gate-math.ts',
+        fn: 'reportUnknownScopeKeys',
+      }),
+      check('malformed-explicit-binding', 'error', true, GLYPHS),
+      check('unused-definition', 'info', false, REGISTRY),
+    ],
+  },
+  {
+    kind: 'invariant',
+    id: 'math-syntax',
+    title: 'Every math span parses and resolves unambiguously.',
+    elements: ['math'],
+    doc: 'notation.md',
+    summary:
+      'KaTeX must parse the span, the glyph table must be well-formed, and a span must not resolve to two entries at once.',
+    checks: [
+      check('invalid-latex', 'error', true, GLYPHS),
+      check('invalid-latex-input', 'error', true, GLYPHS),
+      check('invalid-notation', 'error', false, GLYPHS),
+      check('invalid-definitions', 'error', false, GLYPHS),
+      check('unsupported-katex-version', 'error', false, GLYPHS),
+      check('ambiguous-span', 'error', true, GLYPHS),
+      check('ambiguous-base-fallback', 'error', true, GLYPHS),
+      check('ambiguous-canonical-notation', 'error', false, GLYPHS),
+      check('math-compile-error', 'error', true, GATE_MATH),
+    ],
+  },
+  {
+    kind: 'invariant',
+    id: 'keyed-floats',
+    title: 'A keyed float’s `id` is well-formed and unique, it is named by its caption pair, and every `[[…]]` to it or to a section resolves.',
+    elements: ['equation', 'table', 'plot', 'diagram', 'assessment', 'heading'],
+    doc: 'structure.md#the-invariant-and-why-it-is-build-enforced',
+    summary:
+      '`\\label{eq:key}`, `<Table id>`, `<Figure id>`, `<Diagram id>`, `<CompactExamples id>` and a knowledge check’s id are kebab-case and unique on the page; `[[eq-…]]`, `[[tab-…]]`, `[[fig-…]]`, `[[dia-…]]`, `[[ex-…]]`, `[[check-…]]` point at one that exists, and `[[sec-…]]` at a top-level heading by its anchor. A float is named by `caption` and an optional `short`: `<Figure title>` and `<Diagram label>` no longer exist. A `<CompactExamples>` needs both an `id` and a `short` title. A `<Fold>` is named by its `label` or by a numbered float inside it.',
+    checks: keyedFloatChecks() as [RuleCheck, ...RuleCheck[]],
+  },
+  {
+    kind: 'invariant',
+    id: 'course-settings',
+    title: 'The course settings name real rules and current keys.',
+    elements: ['changelog'],
+    doc: 'README.md#amending',
+    summary:
+      'A `rules.<ID>` block names a live rule; a deprecated top-level key (`operators`, `romanLabels`, `abbreviations`) still works but warns until it is moved under `rules`.',
+    checks: [
+      check('config-deprecated-key', 'warning', false, {
+        module: 'src/rules/settings.ts',
+        fn: 'resolveRules',
+      }),
+      check('config-retired-rule', 'warning', false, {
+        module: 'src/rules/settings.ts',
+        fn: 'resolveRules',
+      }),
+    ],
+  },
+  {
+    kind: 'invariant',
+    id: 'waivers',
+    title: 'A per-place waiver names a waivable rule, gives a reason, and covers something.',
+    elements: ['prose'],
+    doc: 'README.md#waiving-a-rule-at-one-place',
+    summary:
+      '`{/* explico-allow <ID>[, <ID>]: <reason> */}` on its own line waives the named rules for the next block. The rule must be non-locked and waivable inline; a script-rule waiver that silences nothing is reported so it gets removed.',
+    checks: [
+      check('waiver-malformed', 'error', true, { module: 'src/rules/waivers.ts', fn: 'collectWaivers' }),
+      check('waiver-invalid', 'error', true, { module: 'src/rules/waivers.ts', fn: 'collectWaivers' }),
+      check('waiver-unused', 'warning', true, { module: 'src/rules/waivers.ts', fn: 'applyWaivers' }),
+    ],
+  },
+  {
+    kind: 'invariant',
+    id: 'curriculum',
+    title: 'The curriculum graph is well-formed.',
+    elements: ['changelog'],
+    doc: 'structure.md#the-names',
+    summary:
+      'Competency, lesson, track and assessment ids are valid and unique; prerequisites and `teaches`/`requires` name real entries with no cycles; tracks order lessons after their prerequisites; notation alignment names real competencies and lessons.',
+    checks: [
+      ...(
+        [
+          'invalid-id',
+          'duplicate-id',
+          'unknown-reference',
+          'duplicate-reference',
+          'self-prerequisite',
+          'cycle',
+          'lesson-order',
+          'track-order',
+          'assessment-coverage',
+          'invalid-assessment',
+          'review-state',
+          'teaches-support',
+        ] as const
+      ).map((code) =>
+        check(code, 'error', false, {
+          module: 'src/curriculum/validation.ts',
+          fn: 'validateCurriculum',
+        }),
+      ),
+      ...(
+        [
+          'alignment-unknown-competency',
+          'alignment-unknown-lesson',
+          'alignment-introduction',
+          'alignment-unavailable',
+          'alignment-review-state',
+        ] as const
+      ).map((code) =>
+        check(code, 'error', false, {
+          module: 'src/reference/curriculum-alignment.ts',
+          fn: 'validateNotationAlignment',
+        }),
+      ),
+    ] as [RuleCheck, ...RuleCheck[]],
+  },
+];
+
+export const CATALOG: readonly CatalogEntry[] = [...RULES, ...INVARIANTS];
+
+// --- lookups -------------------------------------------------------------
+
+const BY_ID = new Map<string, CatalogEntry>(CATALOG.map((entry) => [entry.id, entry]));
+
+const OWNER_BY_CODE = (() => {
+  const map = new Map<string, CatalogEntry>();
+  for (const entry of CATALOG) {
+    for (const { code } of entry.checks) {
+      const previous = map.get(code);
+      if (previous !== undefined) {
+        throw new Error(
+          `rule catalog: code "${code}" is owned by both ${previous.id} and ${entry.id}`,
+        );
+      }
+      map.set(code, entry);
+    }
+  }
+  return map;
+})();
+
+/** The rule or invariant that owns a diagnostic code, if any. */
+export function ownerOf(code: string): CatalogEntry | undefined {
+  return OWNER_BY_CODE.get(code);
+}
+
+/**
+ * The **rule** ID a diagnostic code belongs to — a lettered engine rule, or a
+ * course rule, whose single check carries the rule's own ID as its code.
+ * `undefined` for a code owned by an invariant (there is no rule page to read)
+ * and for a code nothing owns.
+ */
+export function ruleIdOf(code: string): RuleId | undefined {
+  const owner = OWNER_BY_CODE.get(code);
+  if (owner !== undefined) return owner.kind === 'rule' ? owner.id : undefined;
+  return isCourseRuleId(code) ? code : undefined;
+}
+
+export function entryById(id: string): CatalogEntry | undefined {
+  return BY_ID.get(id);
+}
+
+export function ruleById(id: string): RuleEntry | undefined {
+  const entry = BY_ID.get(id);
+  return entry?.kind === 'rule' ? entry : undefined;
+}
+
+export function rules(): readonly RuleEntry[] {
+  return RULES;
+}
+
+/** Every retired rule, oldest ID first. Read by the generated table and nothing else. */
+export function retiredRules(): readonly RetiredRule[] {
+  return RETIRED;
+}
+
+/** The retired rule with this ID, if the ID belonged to one. */
+export function retiredRule(id: string): RetiredRule | undefined {
+  return RETIRED.find((rule) => rule.id === id);
+}
+
+export function invariants(): readonly InvariantEntry[] {
+  return INVARIANTS;
+}
+
+/**
+ * `script` — every violation a check can see is reported; `partial` — checks
+ * exist but the rule says what they miss; `guide` — nothing runs, a reviewer
+ * (or the agent's own reading) is the enforcement.
+ */
+export function enforcementOf(entry: CatalogEntry): Enforcement {
+  if (entry.checks.length === 0) return 'guide';
+  return entry.kind === 'rule' && entry.unchecked !== undefined ? 'partial' : 'script';
+}
+
+/** Every code the catalog owns, sorted. */
+export function ownedCodes(): readonly string[] {
+  return [...OWNER_BY_CODE.keys()].sort();
+}