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/bin/question_view_playground.rs

@@ -17,7 +17,6 @@ use ratatui::style::{Modifier, Style};
 use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Borders, Paragraph, Wrap};
 
-/// Hardcoded example question sets for UI playground scenarios.
 fn example_scenarios() -> Vec<(&'static str, Vec<Question>)> {
     vec![
         (
@@ -366,7 +365,6 @@ fn main() -> io::Result<()> {
 fn draw(f: &mut ratatui::Frame, app: &mut App) {
     let area = f.area();
 
-    // Layout: header(3) + question view (dynamic) + status(3)
     let content_w = area.width.saturating_sub(QUESTION_VIEW_HPAD) as usize;
     let qv_height = question_view_height(&mut app.state, area.height.saturating_sub(6), content_w);
 
@@ -378,7 +376,6 @@ fn draw(f: &mut ratatui::Frame, app: &mut App) {
     ])
     .split(area);
 
-    // Header
     let scenario_label = format!(
         "question-view-playground [{}/{}] {}",
         app.active_scenario + 1,
@@ -395,13 +392,11 @@ fn draw(f: &mut ratatui::Frame, app: &mut App) {
     .block(Block::default().borders(Borders::ALL).title("info"));
     f.render_widget(header, chunks[0]);
 
-    // Question view
     let qv_area = chunks[1];
     if qv_area.height > 0 && qv_area.width > 0 {
         render_question_view(f.buffer_mut(), qv_area, &app.state, None, &app.theme, true);
     }
 
-    // Status bar
     let status = Paragraph::new(app.status.clone())
         .wrap(Wrap { trim: false })
         .block(Block::default().borders(Borders::ALL).title("status"));

crates/codegen/kigi-tui/src/bin/scrollback_search_playground.rs

@@ -70,7 +70,6 @@ impl App {
         }
     }
 
-    /// Re-run the search for the current query buffer.
     fn refresh_query(&mut self) {
         self.search.update_query(&self.query, &self.scrollback);
         self.reveal_current();
@@ -81,7 +80,6 @@ impl App {
         ));
     }
 
-    /// Scroll the current match into view (exercises the reveal path).
     fn reveal_current(&mut self) {
         if let Some(m) = self.search.current()
             && let Some(idx) = self.scrollback.index_of_id(m.entry_id)
@@ -177,13 +175,15 @@ fn draw(f: &mut ratatui::Frame, app: &mut App) {
     let theme = Theme::current();
     let area = f.area();
     let chunks = Layout::vertical([
-        Constraint::Length(4),  // info / help
-        Constraint::Length(14), // scrollback + search bar
-        Constraint::Min(1),     // event log
+        // info / help
+        Constraint::Length(4),
+        // scrollback + search bar
+        Constraint::Length(14),
+        // event log
+        Constraint::Min(1),
     ])
     .split(area);
 
-    // -- Info / help panel --
     let info = Paragraph::new(vec![
         Line::from(Span::styled(
             "scrollback-search-playground",
@@ -196,7 +196,6 @@ fn draw(f: &mut ratatui::Frame, app: &mut App) {
     .block(Block::default().borders(Borders::ALL).title("info"));
     f.render_widget(info, chunks[0]);
 
-    // -- Scrollback + search bar --
     // Reserve the bottom row of the block for the search bar, exactly as the
     // production draw path will when `scrollback_search.is_some()`.
     let block_area = chunks[1];
@@ -227,7 +226,6 @@ fn draw(f: &mut ratatui::Frame, app: &mut App) {
         }
     }
 
-    // -- Search bar --
     render_search_bar(
         f.buffer_mut(),
         block_area.x,
@@ -259,7 +257,6 @@ fn draw(f: &mut ratatui::Frame, app: &mut App) {
         }
     }
 
-    // -- Event log --
     let lines: Vec<Line<'static>> = app.events.iter().map(|e| Line::from(e.clone())).collect();
     let log = Paragraph::new(lines)
         .wrap(Wrap { trim: false })

crates/codegen/kigi-tui/src/bin/scrollback_selection_playground.rs

@@ -23,10 +23,8 @@ use ratatui::style::{Modifier, Style};
 use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Borders, Paragraph, Wrap};
 
-/// Maximum time (ms) between consecutive clicks to count as a multi-click.
 const MULTI_CLICK_TIMEOUT_MS: u128 = 300;
 
-/// Maximum selected text length shown in event log before truncating.
 const MAX_DISPLAY_TEXT_LEN: usize = 60;
 
 /// Playground highlight TTL (`hold`/`word_select` → 0; flash → 500ms for visibility).
@@ -305,16 +303,21 @@ fn main() -> io::Result<()> {
 fn draw(f: &mut ratatui::Frame, app: &mut App) {
     let area = f.area();
     let chunks = Layout::vertical([
-        Constraint::Length(5),  // info + help
-        Constraint::Length(3),  // last mouse event
-        Constraint::Length(3),  // selection hit test
-        Constraint::Length(3),  // persistent selection state
-        Constraint::Length(14), // scrollback
-        Constraint::Min(1),     // event log
+        // info + help
+        Constraint::Length(5),
+        // last mouse event
+        Constraint::Length(3),
+        // selection hit test
+        Constraint::Length(3),
+        // persistent selection state
+        Constraint::Length(3),
+        // scrollback
+        Constraint::Length(14),
+        // event log
+        Constraint::Min(1),
     ])
     .split(area);
 
-    // -- Info / help panel --
     let dbl_click = double_click_action_label();
     let info = Paragraph::new(vec![
         Line::from(Span::styled(
@@ -329,7 +332,6 @@ fn draw(f: &mut ratatui::Frame, app: &mut App) {
     .block(Block::default().borders(Borders::ALL).title("info"));
     f.render_widget(info, chunks[0]);
 
-    // -- Scrollback render --
     let scrollback_area = chunks[4];
     app.scrollback
         .prepare_layout(scrollback_area.width, scrollback_area.height);
@@ -357,7 +359,6 @@ fn draw(f: &mut ratatui::Frame, app: &mut App) {
         }
     }
 
-    // Render selection overlays.
     if let Some(sel) = &sb_output.selection_box {
         sel.render(f.buffer_mut());
     }
@@ -365,7 +366,6 @@ fn draw(f: &mut ratatui::Frame, app: &mut App) {
         render_persistent_selection_overlay(&app.last_selection_model, ps, None, f.buffer_mut());
     }
 
-    // -- Last mouse event panel --
     let last_mouse = app.last_mouse.as_deref().unwrap_or("(no mouse event yet)");
     let last_mouse_para = Paragraph::new(last_mouse).wrap(Wrap { trim: false }).block(
         Block::default()
@@ -374,7 +374,6 @@ fn draw(f: &mut ratatui::Frame, app: &mut App) {
     );
     f.render_widget(last_mouse_para, chunks[1]);
 
-    // -- Hit test panel --
     let hit = app.last_mouse.as_ref().and_then(|mouse| {
         let parts: Vec<&str> = mouse.split_whitespace().collect();
         let col = parts
@@ -420,7 +419,6 @@ fn draw(f: &mut ratatui::Frame, app: &mut App) {
     );
     f.render_widget(hit_para, chunks[2]);
 
-    // -- Persistent selection state panel --
     let sel_text = match &app.persistent_selection {
         Some(ps) => {
             let origin = match ps.origin {
@@ -448,7 +446,6 @@ fn draw(f: &mut ratatui::Frame, app: &mut App) {
     );
     f.render_widget(sel_para, chunks[3]);
 
-    // -- Event log --
     let lines: Vec<Line<'static>> = app.events.iter().map(|e| Line::from(e.clone())).collect();
     let log = Paragraph::new(lines)
         .wrap(Wrap { trim: false })