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/syntax.rs

@@ -1,7 +1,4 @@
 //! Syntax highlighting support using syntect.
-//!
-//! This module provides the `Syntect` struct which holds the syntax definitions
-//! and theme for code block highlighting.
 
 use std::io::Cursor;
 use std::path::Path;
@@ -14,20 +11,16 @@ use syntect::{
 
 /// Syntax highlighting configuration.
 ///
-/// Holds the theme and syntax definitions for code highlighting.
-/// Create one instance and pass it to the markdown renderer.
+/// Loading the syntax set is expensive; create one instance and pass it to
+/// the markdown renderer.
 pub struct Syntect {
-    /// The color theme for syntax highlighting.
     pub theme: SyntectTheme,
-    /// The syntax definitions (supports 250+ languages via two-face).
     pub syntax_set: SyntaxSet,
 }
 
 impl Syntect {
-    /// Create a new Syntect instance from theme bytes.
-    ///
-    /// The theme bytes should be a TextMate `.tmTheme` file.
-    /// Uses two-face's extended syntax set with 250+ languages.
+    /// `theme_bytes` must be a TextMate `.tmTheme` file. The syntax set is
+    /// two-face's extended one, covering the 250+ languages bat ships.
     ///
     /// # Example
     ///
@@ -37,12 +30,11 @@ impl Syntect {
     pub fn new(theme_bytes: &[u8]) -> Self {
         let mut cursor = Cursor::new(theme_bytes);
         let theme = ThemeSet::load_from_reader(&mut cursor).expect("Failed to load theme");
-        // Use two-face's extended syntax set which includes 250+ languages from bat
         let syntax_set = two_face::syntax::extra_newlines();
         Self { theme, syntax_set }
     }
 
-    /// Find a syntax definition by file path extension.
+    /// Resolves on the extension alone; the rest of the file name is ignored.
     pub fn find_syntax_by_file_path(&self, file_path: &Path) -> Option<&SyntaxReference> {
         let ext = file_path.extension()?.to_str()?;
         self.syntax_set.find_syntax_by_extension(ext)
@@ -53,7 +45,6 @@ impl Syntect {
         self.syntax_set.find_syntax_by_token(token)
     }
 
-    /// Create a highlighter for the given file path.
     pub fn highlight_lines_by_file_path(&self, file_path: &Path) -> Option<HighlightLines<'_>> {
         Some(HighlightLines::new(
             self.find_syntax_by_file_path(file_path)?,
@@ -61,7 +52,6 @@ impl Syntect {
         ))
     }
 
-    /// Create a highlighter for the given language token.
     pub fn highlight_lines_for_token(&self, token: &str) -> Option<HighlightLines<'_>> {
         Some(HighlightLines::new(
             self.find_syntax_by_token(token)?,
@@ -78,7 +68,7 @@ impl Syntect {
     /// If the string matches the citation form but no syntax is found for the
     /// path, this falls back to [`Syntect::find_syntax_by_token`] with the full
     /// `fence_info` string, so plain ` ```lang` blocks keep working and odd
-    /// citations degrade like the pre-citation code path.
+    /// citations degrade to a plain token lookup.
     pub fn highlight_lines_for_fence_info(&self, fence_info: &str) -> Option<HighlightLines<'_>> {
         Some(HighlightLines::new(
             self.find_syntax_for_fence_info(fence_info)?,
@@ -159,10 +149,8 @@ pub(crate) fn syntax_highlight_raw(
     Some(lines)
 }
 
-/// Get a shared Syntect instance for tests.
-///
-/// This loads the tokyo-night theme bundled with the crate.
-/// Uses a static OnceLock for efficiency in test runs.
+/// Shared Syntect instance for tests, using the crate's bundled tokyo-night
+/// theme.
 #[cfg(any(test, fuzzing))]
 #[allow(dead_code)]
 pub fn test_syntect() -> &'static Syntect {