explico 0.8.0 → 0.11.0

package/dist/rules/catalog.js

@@ -0,0 +1,983 @@
+const ELEMENTS = [
+  "prose",
+  "math",
+  "equation",
+  "notation",
+  "heading",
+  "part-page",
+  "plot",
+  "diagram",
+  "table",
+  "assessment",
+  "source",
+  "changelog"
+];
+const COURSE_RULE_ID = /^X[1-9][0-9]?$/;
+function isCourseRuleId(id) {
+  return COURSE_RULE_ID.test(id);
+}
+const GATE_MATH = { module: "src/reference/gate-math.ts", fn: "resolveInto" };
+const GLYPHS = { module: "src/reference/math-glyphs.mjs", fn: "resolveMathGlyphs" };
+const REGISTRY = { module: "src/reference/registry.ts", fn: "buildNotationRegistry" };
+const KEYED_FLOATS = { module: "src/reference/keyed-float-validate.ts", fn: "validateKeyedFloats" };
+function consistency(fn) {
+  return { module: "src/reference/consistency.ts", fn };
+}
+function check(code, severity, located, ...emitters) {
+  return { code, severity, emitters, located };
+}
+function keyedFloatChecks() {
+  const out = [];
+  for (const prefix of ["eq", "tab", "fig", "dia", "ex", "check"]) {
+    const emitter = prefix === "eq" ? { module: "src/reference/equations-validate.ts", fn: "validateEquations" } : prefix === "check" ? { module: "src/reference/knowledge-checks-validate.ts", fn: "validateKnowledgeChecks" } : KEYED_FLOATS;
+    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));
+      out.push(check(`${prefix}-removed-prop`, "error", false, emitter));
+    }
+  }
+  out.push(
+    check("ex-missing-prop", "error", false, {
+      module: "src/reference/examples-validate.ts",
+      fn: "validateExamples"
+    })
+  );
+  out.push(
+    check("sec-ref-resolves", "error", true, {
+      module: "src/reference/sections-validate.ts",
+      fn: "validateSectionRefs"
+    })
+  );
+  out.push(
+    check("fold-unnamed", "error", false, {
+      module: "src/reference/folds-validate.ts",
+      fn: "validateFolds"
+    })
+  );
+  return out;
+}
+function baselineEdits(what) {
+  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: [] }
+    }
+  ];
+}
+const RULES = [
+  // ---- 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\u2019s table of spellings that are fixed to one meaning \u2014 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> \u2014 <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 \u2014 which spelling was chosen is caught in review; rule N4\u2019s 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} \u2014 the natural numbers",
+            "\\mathbb{Z} \u2014 the integers",
+            "\\mathbb{R} \u2014 the reals",
+            "\\mathbb{C} \u2014 the complex numbers",
+            "\\mathbb{P} \u2014 probability",
+            "\\mathcal{N}(\\mu, \\sigma^2) \u2014 the normal distribution (mean, variance)",
+            "\\mathrm{d} \u2014 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 `$\u2026$`, 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 \u2014 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 \u2014 and only when \u2014 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\u2019s `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 `$\u2026$`, never as plain text",
+    title: "A physical quantity, unit, or math operator is typeset in `$\u2026$`, never as plain text \u2014 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="\u2026"`) 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 `$\u2026$`.",
+        schema: { type: "array", items: "string", default: [] }
+      }
+    ]
+  },
+  {
+    kind: "rule",
+    id: "N10",
+    short: "A multi-letter label is `\\mathrm{\u2026}`, and universal or explained",
+    title: "A multi-letter roman label is written `\\mathrm{\u2026}`, 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}}` \u2014 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{\u2026}` at all \u2014 rule N4\u2019s 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\u2019s 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\u2019s own trailing punctuation.",
+    elements: ["math", "prose", "assessment"],
+    doc: "notation.md#n12",
+    summary: "Math, and each row before a `\\\\`, never ends in `.`, `,`, `;` or `:` \u2014 the sentence\u2019s 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)` \u2014 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 \u2014 `(`, `[`, `\\{`, or `|` inside another one of them \u2014 must use the scalable `\\left`/`\\right` form, not the bare character.",
+    elements: ["math"],
+    doc: "notation.md#n15",
+    summary: "Inside another delimiter pair, write `\\left( \u2026 \\right)`, `\\left| \u2026 \\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\u2019s shape is semantic; a nest is engine-sized, not hand-sized",
+    title: "A delimiter\u2019s shape carries its meaning and never changes to show nesting: a nest is sized by the engine \u2014 `\\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 \u2014 an interval `[a, b)`, a norm `\\|\xB7\\|`, a set `\\{\u2026\\}`, a parenthesis for grouping \u2014 and never swap shapes (`( [ \\{ \u2026 \\} ] )`) to mark depth. Depth is size: write `\\left`/`\\right` at every level and let the engine size them, never `\\bigl\u2026\\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 \u2014 `delimiter-manual-size` parses sizing syntax only, and never decides whether a bracket is semantic. A bare nested delimiter is rule N15\u2019s 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 \u2014 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`, \u2026) 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\u2019s source citation carries a locator.",
+    elements: ["notation", "source"],
+    doc: "notation.md#n20",
+    summary: 'Each item in a notation entry\u2019s `sources` names the place in the source (`locator: "\xA73.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 (\u201Claunch angle\u201D); 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\u2019s own entry.",
+    elements: ["math", "notation"],
+    doc: "notation.md#n22",
+    summary: "A decoration (`\\hat`, `\\bar`, `\\overline`, `'`, `^*`, `^\\dagger`, \u2026) is on the course\u2019s `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 \u2014 a dependency graph, a flowchart \u2014 is a `<Diagram id="\u2026">` with its nodes and formulas declared, never a hand-drawn SVG or an image.',
+    checks: []
+  },
+  {
+    kind: "rule",
+    id: "V2",
+    short: "Static charts: SVG \u2192 D3 \u2192 Observable Plot, chosen per figure",
+    title: "Static charts: hand-rolled SVG first, then D3, then Observable Plot \u2014 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\u2019s 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\u2019s 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\u2026`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` \u2014 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 \u2014 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\u2019s `\\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\u2019s `\\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\u2019s `frontmatter.title` \u2014 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 \u2192 this one) and a `<PartScope>` paragraph",
+    title: "A part\u2019s 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 \u2014 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="\u2026">`, never a raw Markdown/HTML table',
+    title: 'A table is a `<Table id="\u2026">`, never a raw Markdown or HTML table.',
+    elements: ["table"],
+    doc: "structure-rules.md#s3",
+    summary: 'Wrap every pipe table or `<table>` in `<Table id="\u2026" caption="\u2026">` so it gets a number and `[[tab-\u2026]]` 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>` \u2014 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 \u2014 the `conventions.signConventionKey` notation entry (`[[key]]`) or the `conventions.cashFlowPerspectiveCompetency` competency \u2014 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\u2019s only `#`, so the body\u2019s first heading is `##`, and each heading is at most one level deeper than the one before it (`##` \u2192 `###`, never `##` \u2192 `####`); going back up any number of levels is fine. A knowledge check\u2019s and a worked-example set\u2019s 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 \u2014 at least a sentence on what the section is about \u2014 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="\u2026">`.',
+    checks: []
+  },
+  {
+    kind: "rule",
+    id: "S9",
+    short: "A float\u2019s short caption names it; the long caption goes on from that name",
+    title: "A float\u2019s 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\u2019s 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 \u2014 its subject, its marks and symbols, the case shown \u2014 and at most the one thing to notice. The argument drawn from a figure is lesson text after it, and a lab\u2019s 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: "\u201CThe residual, or error, is \u2026\u201D introduces a synonym; pick one name and use it. \u201Cor\u201D joins alternatives, not names.",
+    checks: []
+  },
+  {
+    kind: "rule",
+    id: "P2",
+    short: "One term for each concept, repeated \u2014 no synonyms for variety",
+    title: "Use one term for each concept, and repeat it.",
+    elements: ["prose"],
+    doc: "prose.md#p2",
+    summary: "Say \u201Cresidual\u201D 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 (\u201Csignificant\u201D, \u201Cnormal\u201D).",
+    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\u2019s standard term over a coined one, and define it at first use \u2014 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 \u201Clet\u2019s dive in\u201D, 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\u2019s words for it in an \u201CIndustry jargon\u201D 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; \u201Cbecause\u201D, \u201Cso\u201D, \u201Ctherefore\u201D 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: "\u201CProportional to\u201D means `y = kx`; \u201Cgrows with\u201D means monotone; \u201Cdepends on\u201D 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 \u2014 not \u201Cwe have:\u201D.",
+    checks: []
+  }
+];
+const RETIRED = [
+  {
+    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\u2019s `reserved` table, which a course can edit."
+  },
+  {
+    id: "N3",
+    title: "Multi-letter roman labels use `\\mathrm{\u2026}`.",
+    date: "2026-09-26",
+    into: "N10",
+    why: "Writing a label as `\\mathrm{\u2026}` and explaining it are two halves of one rule, and N10 is where both are checked."
+  },
+  {
+    id: "N6",
+    title: "Probability is `\\mathbb{P}` \u2014 double-struck `P`.",
+    date: "2026-09-26",
+    into: "N2",
+    why: "`\\mathbb{P}` is a line in N2\u2019s `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\u2019s `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\u2019s shape carries its meaning, so depth is shown by size \u2014 which this engine handles automatically \u2014 not by alternating shapes. The rule also scoped itself to \u201CAI-generated\u201D 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 = [
+  {
+    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}{\u2026}` 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\u2019s `id` is well-formed and unique, it is named by its caption pair, and every `[[\u2026]]` 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\u2019s id are kebab-case and unique on the page; `[[eq-\u2026]]`, `[[tab-\u2026]]`, `[[fig-\u2026]]`, `[[dia-\u2026]]`, `[[ex-\u2026]]`, `[[check-\u2026]]` point at one that exists, and `[[sec-\u2026]]` 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()
+  },
+  {
+    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"
+      ].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"
+      ].map(
+        (code) => check(code, "error", false, {
+          module: "src/reference/curriculum-alignment.ts",
+          fn: "validateNotationAlignment"
+        })
+      )
+    ]
+  }
+];
+const CATALOG = [...RULES, ...INVARIANTS];
+const BY_ID = new Map(CATALOG.map((entry) => [entry.id, entry]));
+const OWNER_BY_CODE = (() => {
+  const map = /* @__PURE__ */ new Map();
+  for (const entry of CATALOG) {
+    for (const { code } of entry.checks) {
+      const previous = map.get(code);
+      if (previous !== void 0) {
+        throw new Error(
+          `rule catalog: code "${code}" is owned by both ${previous.id} and ${entry.id}`
+        );
+      }
+      map.set(code, entry);
+    }
+  }
+  return map;
+})();
+function ownerOf(code) {
+  return OWNER_BY_CODE.get(code);
+}
+function ruleIdOf(code) {
+  const owner = OWNER_BY_CODE.get(code);
+  if (owner !== void 0) return owner.kind === "rule" ? owner.id : void 0;
+  return isCourseRuleId(code) ? code : void 0;
+}
+function entryById(id) {
+  return BY_ID.get(id);
+}
+function ruleById(id) {
+  const entry = BY_ID.get(id);
+  return entry?.kind === "rule" ? entry : void 0;
+}
+function rules() {
+  return RULES;
+}
+function retiredRules() {
+  return RETIRED;
+}
+function retiredRule(id) {
+  return RETIRED.find((rule) => rule.id === id);
+}
+function invariants() {
+  return INVARIANTS;
+}
+function enforcementOf(entry) {
+  if (entry.checks.length === 0) return "guide";
+  return entry.kind === "rule" && entry.unchecked !== void 0 ? "partial" : "script";
+}
+function ownedCodes() {
+  return [...OWNER_BY_CODE.keys()].sort();
+}
+export {
+  CATALOG,
+  ELEMENTS,
+  enforcementOf,
+  entryById,
+  invariants,
+  isCourseRuleId,
+  ownedCodes,
+  ownerOf,
+  retiredRule,
+  retiredRules,
+  ruleById,
+  ruleIdOf,
+  rules
+};