docs(comments): rewrite comments across all crates to the guidelines

Sweep every first-party crate source (1956 .rs files) to the project comment
guidelines: delete redundant restatements, decorative banners, change
narration, and end-of-line comments; keep and tighten the crucial ones
(invariants, bug rationale, SAFETY blocks, ported-source attribution).

No functional code changed. Every edit is proven comment-only against the
prior tree by a comment-stripping lexer (string/char/raw-string aware) plus a
separate doctest-fence check. Where removing a comment made rustfmt or clippy
want to re-lay-out adjacent code, the minimal triggering comment is restored so
code tokens stay byte-identical.

Gates green: cargo fmt --all --check (0 diffs), cargo check and cargo clippy
--workspace --all-targets (0 warnings).

Adds scripts/check_codegen_comment_guidelines.py — the enforcement gate for
these guidelines (flags banners, end-of-line comments, change narration, and
commented-out code).

crates/codegen/kigi-markdown/src/latex/commands.rs

@@ -205,7 +205,7 @@ fn script_atom_is_wordlike(atom: &str, rendered: &str) -> bool {
 fn render_command(cursor: &mut Cursor<'_>, out: &mut MathBox, depth: usize, mode: Mode) {
     let name = cursor.read_command_name();
     match name {
-        // ── Structure ────────────────────────────────────────────────────
+        // Structure
         "" => out.push('\\'),
         "\\" => out.push('\n'),
         "begin" => render_environment(cursor, out, depth, mode),
@@ -232,7 +232,7 @@ fn render_command(cursor: &mut Cursor<'_>, out: &mut MathBox, depth: usize, mode
             }
         }
 
-        // ── Fractions / binomials / roots ────────────────────────────────
+        // Fractions / binomials / roots
         "frac" | "dfrac" | "tfrac" | "cfrac" => {
             let num = take_brace_arg(cursor).map(|a| render_atom(a, depth, mode));
             let den = take_brace_arg(cursor).map(|a| render_atom(a, depth, mode));
@@ -261,7 +261,8 @@ fn render_command(cursor: &mut Cursor<'_>, out: &mut MathBox, depth: usize, mode
                     cursor.bump();
                 }
                 let idx = &cursor.src[start..cursor.pos];
-                cursor.bump(); // consume `]`
+                // consume `]`
+                cursor.bump();
                 Some(render_atom(idx, depth, mode))
             } else {
                 None
@@ -290,7 +291,7 @@ fn render_command(cursor: &mut Cursor<'_>, out: &mut MathBox, depth: usize, mode
             }
         }
 
-        // ── Boxes (frame dropped; content preserved) ─────────────────────
+        // Boxes (frame dropped; content preserved)
         "boxed" => {
             if let Some(arg) = take_brace_arg(cursor) {
                 out.push_str(&render_atom(arg, depth, mode));
@@ -302,7 +303,7 @@ fn render_command(cursor: &mut Cursor<'_>, out: &mut MathBox, depth: usize, mode
             }
         }
 
-        // ── Text / alphabets ─────────────────────────────────────────────
+        // Text / alphabets
         "text" | "textrm" | "textit" | "textbf" | "textsf" | "texttt" | "textnormal" | "mbox"
         | "hbox" => {
             if let Some(arg) = take_brace_arg(cursor) {
@@ -321,7 +322,7 @@ fn render_command(cursor: &mut Cursor<'_>, out: &mut MathBox, depth: usize, mode
             render_mapped_alphabet(cursor, out, depth, mode, map_mathbf)
         }
 
-        // ── Accents (combining marks) ────────────────────────────────────
+        // Accents (combining marks)
         "hat" | "widehat" => render_accent(cursor, out, depth, mode, '\u{0302}'),
         "bar" | "overline" => render_accent(cursor, out, depth, mode, '\u{0304}'),
         "tilde" | "widetilde" => render_accent(cursor, out, depth, mode, '\u{0303}'),
@@ -335,7 +336,7 @@ fn render_command(cursor: &mut Cursor<'_>, out: &mut MathBox, depth: usize, mode
         "mathring" => render_accent(cursor, out, depth, mode, '\u{030A}'),
         "underline" => render_accent(cursor, out, depth, mode, '\u{0332}'),
 
-        // ── Negation ─────────────────────────────────────────────────────
+        // Negation
         "not" => {
             if let Some(atom) = cursor.read_atom() {
                 let rendered = render_atom(atom, depth, mode);
@@ -359,7 +360,7 @@ fn render_command(cursor: &mut Cursor<'_>, out: &mut MathBox, depth: usize, mode
             }
         }
 
-        // ── Decorations rendered as base + script ────────────────────────
+        // Decorations rendered as base + script
         "overset" | "stackrel" => {
             let over = take_brace_arg(cursor).map(|a| render_atom(a, depth, mode));
             let base = take_brace_arg(cursor).map(|a| render_atom(a, depth, mode));
@@ -385,7 +386,7 @@ fn render_command(cursor: &mut Cursor<'_>, out: &mut MathBox, depth: usize, mode
             }
         }
 
-        // ── Modular arithmetic ───────────────────────────────────────────
+        // Modular arithmetic
         "pmod" => {
             if let Some(arg) = take_brace_arg(cursor) {
                 if !out.at_line_start() && !out.ends_with_space() {
@@ -401,7 +402,7 @@ fn render_command(cursor: &mut Cursor<'_>, out: &mut MathBox, depth: usize, mode
             out.push_str("mod ");
         }
 
-        // ── Spacing ──────────────────────────────────────────────────────
+        // Spacing
         "," | ";" | ":" | ">" | " " | "space" | "thinspace" | "medspace" | "thickspace"
         | "enspace" => {
             if !out.at_line_start() && !out.ends_with_space() {
@@ -412,7 +413,7 @@ fn render_command(cursor: &mut Cursor<'_>, out: &mut MathBox, depth: usize, mode
         "qquad" => out.push_str("    "),
         "!" | "negthinspace" | "negmedspace" | "negthickspace" => {}
 
-        // ── No-ops (sizing/styling/structure hints) ──────────────────────
+        // No-ops (sizing/styling/structure hints)
         "limits" | "nolimits" | "displaystyle" | "textstyle" | "scriptstyle"
         | "scriptscriptstyle" | "big" | "Big" | "bigg" | "Bigg" | "bigl" | "Bigl" | "biggl"
         | "Biggl" | "bigr" | "Bigr" | "biggr" | "Biggr" | "bigm" | "Bigm" | "biggm" | "Biggm"
@@ -425,7 +426,7 @@ fn render_command(cursor: &mut Cursor<'_>, out: &mut MathBox, depth: usize, mode
             }
         }
 
-        // ── Symbol table ─────────────────────────────────────────────────
+        // Symbol table
         _ => {
             if let Some(sym) = symbol(name) {
                 out.push_str(sym);

crates/codegen/kigi-markdown/src/latex/cursor.rs

@@ -1,6 +1,5 @@
 //! Byte cursor over TeX source.
 
-/// Byte cursor over the TeX source.
 pub(super) struct Cursor<'a> {
     pub(super) src: &'a str,
     pub(super) pos: usize,
@@ -24,7 +23,7 @@ impl<'a> Cursor<'a> {
     /// Consume `\command` (alphabetic name) or `\<single char>`; the leading
     /// backslash must already be consumed. Returns the command name.
     ///
-    /// Unlike TeX we do NOT consume trailing whitespace: the caller's
+    /// Unlike TeX, trailing whitespace is NOT consumed: the caller's
     /// whitespace collapsing keeps `\to 0` rendering as `→ 0`.
     pub(super) fn read_command_name(&mut self) -> &'a str {
         let start = self.pos;
@@ -43,7 +42,6 @@ impl<'a> Cursor<'a> {
         }
     }
 
-    /// Skip whitespace (TeX collapses it; meaning comes from commands).
     pub(super) fn skip_ws(&mut self) {
         while matches!(self.peek(), Some(c) if c.is_whitespace()) {
             self.bump();
@@ -59,7 +57,7 @@ impl<'a> Cursor<'a> {
         while let Some(ch) = self.bump() {
             match ch {
                 '\\' => {
-                    // Skip escaped char so `\{`/`\}` don't affect depth.
+                    // Skip the escaped char so `\{`/`\}` don't affect depth.
                     self.bump();
                 }
                 '{' => depth += 1,

crates/codegen/kigi-markdown/src/latex/environments.rs

@@ -19,8 +19,8 @@ pub(super) fn render_environment(
     };
     let env_name = env_name.trim().trim_end_matches('*');
 
-    // Capture body source until the matching `\end{name}`, tracking nesting
-    // of same-named environments. Scans raw source from the cursor.
+    // Scan raw source for the matching `\end{name}`, tracking nesting of
+    // same-named environments.
     let body_start = cursor.pos;
     let mut body_end = cursor.src.len();
     let mut resume = cursor.src.len();
@@ -38,8 +38,8 @@ pub(super) fn render_environment(
         } else if command_at(after_bs, "end") {
             "end".len()
         } else {
-            // Not begin/end: skip the backslash and the char after it (so
-            // `\\` and `\{` never confuse the scan).
+            // Skip the backslash and the char after it so that `\\` and `\{`
+            // never confuse the scan.
             let skip = after_bs.chars().next().map_or(0, char::len_utf8);
             search = bs_pos + 1 + skip.max(1);
             continue;
@@ -66,7 +66,7 @@ pub(super) fn render_environment(
     cursor.pos = resume;
     let mut body = &cursor.src[body_start..body_end.min(cursor.src.len())];
 
-    // Optional column spec for array environments: `\begin{array}{ll}`.
+    // Discard the optional column spec: `\begin{array}{ll}`.
     if env_name == "array" || env_name == "alignat" {
         let mut probe = Cursor::new(body);
         probe.skip_ws();
@@ -92,9 +92,9 @@ fn command_at(rest: &str, word: &str) -> bool {
 
 /// Split an environment body into rows (`\\`) and cells (`&`) at brace and
 /// environment depth 0, render each cell, then lay the rows out according to
-/// the environment. Returns one string per visual row; the caller attaches
-/// them as a box. In `flat` mode, matrix/cases environments render as a
-/// single row with `; ` between matrix rows.
+/// the environment. Returns one string per visual row. In `flat` mode,
+/// matrix/cases environments collapse to a single row with `; ` between
+/// matrix rows.
 fn env_rows_to_strings(
     body: &str,
     env_name: &str,
@@ -130,7 +130,7 @@ fn env_rows_to_strings(
                     env_depth = env_depth.saturating_sub(1);
                 }
                 // Skip the backslash plus the char after it so escaped
-                // delimiters (`\&`, `\{`, `\}`) never affect depth/splits.
+                // delimiters (`\&`, `\{`, `\}`) never affect depth or splits.
                 let skip = rest.chars().next().map_or(0, char::len_utf8);
                 i += 1 + skip.max(1);
                 continue;
@@ -148,7 +148,6 @@ fn env_rows_to_strings(
     row.push(body[cell_start.min(bytes.len())..].to_string());
     rows.push(row);
 
-    // Render each cell, drop fully-empty rows.
     let mut rendered_rows: Vec<Vec<String>> = rows
         .into_iter()
         .map(|cells| {
@@ -177,15 +176,14 @@ fn env_rows_to_strings(
     let n_rows = rendered_rows.len();
 
     if is_matrix {
-        // Flat (inline) mode: one row, single delimiter pair, rows joined
-        // with `; ` — `(1  2; 3  4)`.
         if flat {
             let inner = rendered_rows
                 .iter()
                 .map(|cells| cells.join("  "))
                 .collect::<Vec<_>>()
                 .join("; ");
-            // Single-row delimiter pair; plain `matrix` has none (' ').
+            // Ask for the single-row form; plain `matrix` has no delimiter
+            // and reports ' '.
             let (l, r) = matrix_delims(env_name, 0, 1);
             let mut s = String::new();
             if l != ' ' {
@@ -197,7 +195,6 @@ fn env_rows_to_strings(
             }
             return vec![s];
         }
-        // Pad columns to equal width so rows align.
         let n_cols = rendered_rows.iter().map(Vec::len).max().unwrap_or(0);
         let mut widths = vec![0usize; n_cols];
         for cells in &rendered_rows {
@@ -243,9 +240,7 @@ fn env_rows_to_strings(
             .collect()
     } else {
         // aligned/align/gather/split/equation/…: `&` is an invisible
-        // alignment marker; rejoin cells with a single space. One string per
-        // row; the caller's box attachment (or flat `; ` join) handles the
-        // rest.
+        // alignment marker, so cells rejoin with a single space.
         rendered_rows
             .iter()
             .map(|cells| {
@@ -255,7 +250,7 @@ fn env_rows_to_strings(
                     .cloned()
                     .collect::<Vec<_>>()
                     .join(" ");
-                // Collapse any double spaces introduced around markers.
+                // Empty alignment cells leave runs of spaces behind.
                 while s.contains("  ") {
                     s = s.replace("  ", " ");
                 }

crates/codegen/kigi-markdown/src/latex/math_box.rs

@@ -124,7 +124,7 @@ impl MathBox {
                 self.lines.push(String::new());
             }
         }
-        // Place the box rows, left-padded to the attach column.
+        // Place the box rows, left-`padded` to the attach column.
         for (i, row) in rows.iter().enumerate() {
             let target = self.anchor - box_anchor + i;
             let line = &mut self.lines[target];

crates/codegen/kigi-markdown/src/latex/mod.rs

@@ -79,7 +79,6 @@ pub(crate) fn latex_to_unicode_display(src: &str) -> Option<Vec<String>> {
     Some(lines)
 }
 
-/// Run the converter and return the output lines.
 fn convert(src: &str, flat: bool) -> Vec<String> {
     let mut cursor = Cursor::new(src);
     let mut out = MathBox::new(flat);

crates/codegen/kigi-markdown/src/latex/symbols.rs

@@ -1,4 +1,10 @@
 //! Character and symbol mapping tables.
+//!
+//! In the `map_math*` alphabets the explicit letter arms come first on
+//! purpose: those letters were encoded as Letterlike Symbols before the
+//! contiguous Mathematical Alphanumeric blocks existed, so their block slots
+//! are unassigned and the arithmetic arms below would yield a reserved
+//! codepoint.
 
 pub(super) fn to_superscript(c: char) -> Option<char> {
     Some(match c {

crates/codegen/kigi-markdown/src/latex/tests.rs

@@ -29,10 +29,10 @@ fn subscripts_map_to_unicode() {
 
 #[test]
 fn script_fallback_uses_parens() {
-    // φ has no superscript form → fall back to ^(...)
+    // Greek letters have no superscript forms; a multi-char run falls back to
+    // ^(...) while a lone char keeps the bare marker.
     assert_eq!(inline("x^{\\alpha\\beta}"), "x^(αβ)");
     assert_eq!(inline("x^\\alpha"), "x^α");
-    // Single unmappable subscript char.
     assert_eq!(inline("a_q"), "a_q");
 }