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-tui/src/scrollback/wrappers/accented.rs

@@ -22,12 +22,10 @@ pub struct Accented<'a, T> {
 }
 
 impl<'a, T> Accented<'a, T> {
-    /// Create a new accented wrapper.
     pub fn new(inner: &'a T, style: Style) -> Self {
         Self { inner, style }
     }
 
-    /// Create with just a foreground color.
     pub fn with_fg(inner: &'a T, color: ratatui::style::Color) -> Self {
         Self {
             inner,
@@ -48,16 +46,13 @@ impl<T: Renderable> Renderable for Accented<'_, T> {
             return;
         }
 
-        // Split horizontally: [accent (1)] [content (rest)]
         let [accent_area, content_area] =
             Layout::horizontal([Constraint::Length(1), Constraint::Min(0)]).areas(area);
 
-        // Draw accent line for all rows
         for y in accent_area.y..accent_area.y + accent_area.height {
             buf.set_string(accent_area.x, y, crate::glyphs::accent_bar(), self.style);
         }
 
-        // Render inner content
         if content_area.width > 0 {
             self.inner.render(content_area, buf);
         }
@@ -112,7 +107,6 @@ mod tests {
         let mut buf = Buffer::empty(area);
         accented.render(area, &mut buf);
 
-        // Check accent line is in column 0
         assert_eq!(
             buf.cell((0, 0)).unwrap().symbol(),
             crate::glyphs::accent_bar()
@@ -122,7 +116,6 @@ mod tests {
             crate::glyphs::accent_bar()
         );
 
-        // Check content starts at column 1
         assert_eq!(buf.cell((1, 0)).unwrap().symbol(), "H");
         assert_eq!(buf.cell((2, 0)).unwrap().symbol(), "i");
     }
@@ -137,6 +130,7 @@ mod tests {
 
         let area = Rect::new(0, 0, 0, 0);
         let mut buf = Buffer::empty(Rect::new(0, 0, 10, 10));
-        accented.render(area, &mut buf); // Should not panic
+        // Should not panic
+        accented.render(area, &mut buf);
     }
 }

crates/codegen/kigi-tui/src/scrollback/wrappers/block_renderer.rs

@@ -105,7 +105,8 @@ impl<B: BlockContent> Renderable for BlockRenderer<'_, B> {
         let has_vpad = self.block.has_vpad(&ctx);
 
         let content_height = output.len() as u16;
-        let vpad = if has_vpad { 2 } else { 0 }; // top + bottom
+        // top + bottom
+        let vpad = if has_vpad { 2 } else { 0 };
 
         content_height + vpad
     }
@@ -120,10 +121,8 @@ impl<B: BlockContent> Renderable for BlockRenderer<'_, B> {
         let has_vpad = self.block.has_vpad(&ctx);
         let block_bg = self.block.background(&ctx);
 
-        // Resolve background color
         let bg_color = self.resolve_background(block_bg);
 
-        // Fill background if specified
         if let Some(bg) = bg_color {
             let bg_style = Style::default().bg(bg);
             for y in area.y..area.y + area.height {
@@ -143,13 +142,11 @@ impl<B: BlockContent> Renderable for BlockRenderer<'_, B> {
             row += 1;
         }
 
-        // Content lines
         for line in &output.lines {
             if row >= max_row {
                 break;
             }
 
-            // Apply line-specific background if set
             // Respects bg_start_col for partial background
             if let Some(line_bg) = line.background {
                 let bg_x = area.x + line.bg_start_col;
@@ -160,13 +157,11 @@ impl<B: BlockContent> Renderable for BlockRenderer<'_, B> {
                 }
             }
 
-            // Render the line content
             buf.set_line_safe(area.x, row, &line.content, area.width);
             row += 1;
         }
 
         // Bottom vpad (empty row) - just skip, background already applied
-        // (no explicit rendering needed)
     }
 }
 
@@ -212,7 +207,6 @@ mod tests {
         let mut buf = Buffer::empty(area);
         renderer.render(area, &mut buf);
 
-        // All cells should have red background
         for y in 0..3 {
             for x in 0..10 {
                 assert_eq!(buf.cell((x, y)).unwrap().bg, Color::Red);

crates/codegen/kigi-tui/src/scrollback/wrappers/entry_renderer.rs

@@ -326,7 +326,8 @@ impl<'a> EntryRenderer<'a> {
 
     /// Legacy fixed chrome-width estimate for callers with no appearance to
     /// borrow (off-screen mermaid sizing); the live value is `chrome_width()`.
-    pub const CHROME_WIDTH: u16 = 1 + 2 + 1; // accent + left_pad + right_pad (legacy)
+    // accent + left_pad + right_pad (legacy)
+    pub const CHROME_WIDTH: u16 = 1 + 2 + 1;
 
     /// Whether this entry should display a timestamp on the first content line.
     ///
@@ -346,7 +347,8 @@ impl<'a> EntryRenderer<'a> {
     /// never collides with the timestamp overlay.
     fn timestamp_reserved(&self) -> u16 {
         if self.appearance.show_timestamps && self.should_show_timestamp() {
-            10 // max short format: "  12:30 PM"
+            // max short format: "  12:30 PM"
+            10
         } else {
             0
         }
@@ -680,10 +682,10 @@ impl Renderable for EntryRenderer<'_> {
         ])
         .areas(area);
 
-        // Build context directly — avoid calling effective_output() here since
-        // we only need the context for background/accent decisions, not the output.
-        // This eliminates a full block.output() call (including syntax highlighting
-        // for edit blocks) that was previously thrown away.
+        // Only background/accent decisions are needed here, so build the
+        // context directly instead of going through effective_output() —
+        // that would run a full block.output() (including syntax
+        // highlighting for edit blocks) just to discard it.
         let mut ctx = self
             .entry
             .context(content_area.width, &self.appearance, self.cwd);
@@ -711,7 +713,6 @@ impl Renderable for EntryRenderer<'_> {
             let full_start_y = area.y;
             let full_end_y = area.y + area.height;
 
-            // Fill accent area if block wants accent background
             if self.entry.block.accent_background(&ctx) {
                 for y in full_start_y..full_end_y {
                     for x in accent_area.x..accent_area.x + accent_area.width {
@@ -722,7 +723,6 @@ impl Renderable for EntryRenderer<'_> {
                 }
             }
 
-            // Fill left padding
             for y in full_start_y..full_end_y {
                 for x in left_pad.x..left_pad.x + left_pad.width {
                     if let Some(cell) = buf.cell_mut((x, y)) {
@@ -731,7 +731,6 @@ impl Renderable for EntryRenderer<'_> {
                 }
             }
 
-            // Fill content area
             for y in full_start_y..full_end_y {
                 for x in content_area.x..content_area.x + content_area.width {
                     if let Some(cell) = buf.cell_mut((x, y)) {
@@ -740,7 +739,6 @@ impl Renderable for EntryRenderer<'_> {
                 }
             }
 
-            // Fill right padding
             for y in full_start_y..full_end_y {
                 for x in right_pad.x..right_pad.x + right_pad.width {
                     if let Some(cell) = buf.cell_mut((x, y)) {
@@ -840,7 +838,6 @@ impl Renderable for EntryRenderer<'_> {
                     );
                 }
             } else {
-                // Static accent: full color
                 let style = Style::default().fg(color);
                 for y in accent_area.y..accent_area.y + accent_area.height {
                     buf.set_string_safe(accent_area.x, y, crate::glyphs::accent_bar(), style);
@@ -886,7 +883,6 @@ impl Renderable for EntryRenderer<'_> {
         // so a wide glyph can't strand a ghost; per-row bg keeps code blocks whole.
         let own_gutter = ts_reserved > 0 && bg_color.is_none() && content_area.width > ts_reserved;
 
-        // Content lines — skip the first `content_skip` lines
         for line in output.lines.iter().skip(content_skip as usize) {
             if row >= max_row {
                 break;
@@ -1092,7 +1088,8 @@ mod tests {
 
     #[test]
     fn test_chrome_width_constant() {
-        assert_eq!(EntryRenderer::CHROME_WIDTH, 4); // 1 + 2 + 1
+        // 1 + 2 + 1
+        assert_eq!(EntryRenderer::CHROME_WIDTH, 4);
     }
 
     #[test]
@@ -1236,7 +1233,8 @@ mod tests {
 
         // AgentMessage has no vpad → first content row at y=0.
         // Hover the rightmost 10 cols of that row to trigger expansion.
-        let hover_x = width - 2 - 5; // inside the timestamp zone
+        // inside the timestamp zone
+        let hover_x = width - 2 - 5;
         let renderer = EntryRenderer::new(&entry, &theme).with_mouse_pos(Some((hover_x, 0)));
 
         let height = renderer.desired_height(width);
@@ -1414,8 +1412,6 @@ mod tests {
         }
     }
 
-    // ── timestamp gutter ownership (ghost-glyph regression) ──
-
     #[test]
     fn gutter_cleared_on_non_first_content_row_without_background() {
         // Regression: nothing writes the timestamp gutter on rows past the
@@ -1573,8 +1569,6 @@ mod tests {
         );
     }
 
-    // ── estimate_height (lazy off-screen sizing) ──
-
     #[test]
     fn estimate_matches_exact_for_plain_single_line() {
         let _theme = pin_theme();
@@ -1760,9 +1754,12 @@ mod tests {
             let entry = ScrollbackEntry::new(RenderBlock::stub(text, Color::Blue));
             EntryRenderer::new(&entry, &theme).estimate_height(14)
         };
-        let wide = height("一二三四五六七八九十"); // display 20, bytes 30
-        let ascii_same_display = height("xxxxxxxxxxxxxxxxxxxx"); // display 20, bytes 20
-        let ascii_same_bytes = height("xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"); // display 30, bytes 30
+        // display 20, bytes 30
+        let wide = height("一二三四五六七八九十");
+        // display 20, bytes 20
+        let ascii_same_display = height("xxxxxxxxxxxxxxxxxxxx");
+        // display 30, bytes 30
+        let ascii_same_bytes = height("xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");
         assert_eq!(
             wide, ascii_same_display,
             "wraps by display width: wide(20 cols) == ascii(20 cols)"
@@ -1773,8 +1770,6 @@ mod tests {
         );
     }
 
-    // ── diagram affordance-row reservation ──
-
     /// A diagram under `auto`/`on` reserves exactly one extra row — the
     /// affordance row — and the off-screen estimate accounts for it so a bulk
     /// load never under-reserves. Rendering is lazy, so the row is always present
@@ -1838,8 +1833,6 @@ mod tests {
         crate::appearance::cache::set_show_thinking_blocks(false);
     }
 
-    // ── flat_background × per-line backgrounds (minimal mode) ──
-
     /// Whether any cell in the buffer carries `bg` as its background.
     fn buf_has_bg(buf: &Buffer, bg: Color) -> bool {
         let area = *buf.area();

crates/codegen/kigi-tui/src/scrollback/wrappers/mod.rs

@@ -43,7 +43,6 @@ mod tests {
     use ratatui::layout::Rect;
     use ratatui::style::Color;
 
-    /// Test that wrappers can be composed together.
     #[test]
     fn test_wrapper_composition() {
         let block = StubBlock::new("Hello", Color::Blue);
@@ -57,7 +56,6 @@ mod tests {
         // Padded: takes 3 columns (2+1), height unchanged
         assert_eq!(padded.desired_height(80), 3);
 
-        // Render and verify structure
         let area = Rect::new(0, 0, 20, 3);
         let mut buf = Buffer::empty(area);
         padded.render(area, &mut buf);

crates/codegen/kigi-tui/src/scrollback/wrappers/padded.rs

@@ -24,7 +24,6 @@ pub struct Padded<'a, T> {
 }
 
 impl<'a, T> Padded<'a, T> {
-    /// Create a new padded wrapper.
     pub fn new(inner: &'a T, left: u16, right: u16) -> Self {
         Self {
             inner,
@@ -48,7 +47,6 @@ impl<'a, T> Padded<'a, T> {
 
 impl<T: Renderable> Renderable for Padded<'_, T> {
     fn desired_height(&self, width: u16) -> u16 {
-        // Padding takes left + right columns
         let content_width = width.saturating_sub(self.left + self.right);
         self.inner.desired_height(content_width)
     }
@@ -58,7 +56,6 @@ impl<T: Renderable> Renderable for Padded<'_, T> {
             return;
         }
 
-        // Fill background if specified
         if let Some(bg) = self.bg {
             let bg_style = Style::default().bg(bg);
             for y in area.y..area.y + area.height {
@@ -70,7 +67,6 @@ impl<T: Renderable> Renderable for Padded<'_, T> {
             }
         }
 
-        // Split horizontally: [left pad] [content] [right pad]
         let [_left_area, content_area, _right_area] = Layout::horizontal([
             Constraint::Length(self.left),
             Constraint::Min(0),
@@ -78,7 +74,6 @@ impl<T: Renderable> Renderable for Padded<'_, T> {
         ])
         .areas(area);
 
-        // Render inner content
         if content_area.width > 0 {
             self.inner.render(content_area, buf);
         }
@@ -91,7 +86,6 @@ mod tests {
     use pretty_assertions::assert_eq;
     use ratatui::style::Color;
 
-    /// Simple test content that renders as fixed height.
     struct TestContent {
         height: u16,
         text: &'static str,
@@ -117,7 +111,6 @@ mod tests {
         };
         let padded = Padded::new(&content, 2, 1);
 
-        // Width 80 -> content gets 77 (80 - 2 - 1)
         assert_eq!(padded.desired_height(80), 3);
     }
 
@@ -129,8 +122,6 @@ mod tests {
         };
         let padded = Padded::standard(&content);
 
-        // Standard is 2 left, 1 right
-        // Width 10 -> content gets 7
         assert_eq!(padded.desired_height(10), 1);
     }
 
@@ -163,7 +154,6 @@ mod tests {
         let mut buf = Buffer::empty(area);
         padded.render(area, &mut buf);
 
-        // All cells should have blue background
         for x in 0..5 {
             let cell = buf.cell((x, 0)).unwrap();
             assert_eq!(cell.bg, Color::Blue);