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/notifications/config.rs

@@ -258,7 +258,6 @@ mod tests {
 
         assert_eq!(parsed.method, NotificationMethod::Bel);
         assert_eq!(parsed.idle_threshold_secs, 60);
-        // Rest should be defaults
         assert_eq!(parsed.condition, NotificationCondition::Unfocused);
         assert!(parsed.sleep_prevention);
         assert!(parsed.progress_bar);

crates/codegen/kigi-tui/src/notifications/focus.rs

@@ -190,8 +190,6 @@ mod tests {
         assert!(!tracker.should_notify());
     }
 
-    // --- Auto session-recap (recap_due) tests ---
-
     #[test]
     fn recap_not_due_while_focused() {
         let tracker = FocusTracker::new(3, 0);

crates/codegen/kigi-tui/src/notifications/hooks.rs

@@ -230,7 +230,8 @@ mod tests {
             command: format!("sleep 100; touch {}", marker.display()),
             events: vec![],
             only_unfocused: false,
-            timeout_secs: 0, // exercises the .max(1) clamp inside run_hook
+            // exercises the .max(1) clamp inside run_hook
+            timeout_secs: 0,
         };
         let start = Instant::now();
         run_hook(&hook, &test_event());

crates/codegen/kigi-tui/src/notifications/mod.rs

@@ -546,8 +546,6 @@ mod tests {
         );
     }
 
-    // --- Progress bar (OSC 9;4) tests ---
-
     fn make_title_state(is_busy: bool) -> title::TitleState<'static> {
         title::TitleState {
             session_name: None,
@@ -705,8 +703,6 @@ mod tests {
         assert!(!svc.is_progress_active());
     }
 
-    // --- Permission notification rate-limiting tests ---
-
     #[test]
     fn permission_suppression_lifecycle() {
         let mut svc = NotificationService::new_for_test(NotificationConfig::default());

crates/codegen/kigi-tui/src/notifications/progress.rs

@@ -100,7 +100,6 @@ mod tests {
     #[test]
     fn emit_noop_for_unsupported_terminal() {
         let ctx = ctx_for(TerminalName::Kitty);
-        // Should not panic or write anything meaningful.
         emit_progress(ProgressState::Indeterminate, &ctx);
         emit_progress(ProgressState::Clear, &ctx);
     }
@@ -130,7 +129,6 @@ mod tests {
             term_program_version: Some("3.6.0".into()),
             ..Default::default()
         };
-        // Should not panic; tmux passthrough wrapping is exercised.
         emit_progress(ProgressState::Indeterminate, &ctx);
         emit_progress(ProgressState::Clear, &ctx);
     }
@@ -155,8 +153,6 @@ mod tests {
         );
     }
 
-    // --- build_progress_escape tests ---
-
     #[test]
     fn build_returns_none_for_unsupported_brand() {
         let ctx = ctx_for(TerminalName::Kitty);

crates/codegen/kigi-tui/src/notifications/protocol.rs

@@ -31,7 +31,6 @@ impl NotificationProtocol {
     }
 }
 
-/// Choose the best notification protocol for the current terminal environment.
 pub fn select_protocol(ctx: &TerminalContext) -> NotificationProtocol {
     if ctx.multiplexer == MultiplexerKind::Zellij {
         return NotificationProtocol::Bel;
@@ -62,8 +61,6 @@ pub fn select_protocol(ctx: &TerminalContext) -> NotificationProtocol {
 
 const BEL_BYTE: &[u8] = b"\x07";
 
-/// Build the escape sequence for a notification, then write it to stderr.
-///
 /// When running under tmux the sequence is wrapped in DCS passthrough so the
 /// outer terminal sees it.
 pub fn emit_notification(
@@ -124,8 +121,6 @@ mod tests {
         }
     }
 
-    // --- select_protocol: every TerminalName variant ---
-
     #[test]
     fn select_iterm2_uses_osc9() {
         assert_eq!(
@@ -214,8 +209,6 @@ mod tests {
         );
     }
 
-    // --- Zellij override ---
-
     #[test]
     fn zellij_overrides_to_bel_for_kitty() {
         assert_eq!(
@@ -260,8 +253,8 @@ mod tests {
         );
     }
 
-    // --- tmux does NOT override protocol selection (passthrough is handled
-    //     at emission time, not selection time) ---
+    // tmux does not override protocol selection: passthrough wrapping
+    // happens at emission time, not selection time.
 
     #[test]
     fn tmux_preserves_osc9_for_iterm2() {
@@ -285,8 +278,6 @@ mod tests {
         );
     }
 
-    // --- screen does not override ---
-
     #[test]
     fn screen_preserves_osc777_for_ghostty() {
         assert_eq!(
@@ -298,12 +289,9 @@ mod tests {
         );
     }
 
-    // --- emit_notification: verifies None is a no-op (does not panic) ---
-
     #[test]
     fn emit_none_is_noop() {
         let ctx = ctx_with_brand(TerminalName::KigiDesktop);
-        // Should return immediately without writing anything.
         emit_notification(NotificationProtocol::None, "title", "body", &ctx);
     }
 
@@ -331,8 +319,6 @@ mod tests {
         emit_notification(NotificationProtocol::Osc777, "title", "body", &ctx);
     }
 
-    // --- exhaustive brand coverage in a table-driven test ---
-
     #[test]
     fn all_brands_have_defined_protocol() {
         let cases: &[(TerminalName, NotificationProtocol)] = &[

crates/codegen/kigi-tui/src/notifications/sleep.rs

@@ -71,7 +71,8 @@ impl SleepInhibitor {
         let result = unsafe {
             IOPMAssertionCreateWithName(
                 assertion_type.as_concrete_TypeRef(),
-                255, // kIOPMAssertionLevelOn
+                // kIOPMAssertionLevelOn
+                255,
                 reason.as_concrete_TypeRef(),
                 &mut assertion_id,
             )
@@ -151,8 +152,6 @@ impl Drop for SleepInhibitor {
     }
 }
 
-// -- macOS IOKit FFI ---------------------------------------------------------
-
 #[cfg(target_os = "macos")]
 use core_foundation::base::TCFType;
 
@@ -264,7 +263,6 @@ mod tests {
         let inhibitor = SleepInhibitor::new(true);
         inhibitor.inhibit();
         if inhibitor.active.get() {
-            // Grab the pid before release.
             let pid = inhibitor.child.borrow().as_ref().map(|c| c.id());
             assert!(pid.is_some());
             inhibitor.release();

crates/codegen/kigi-tui/src/notifications/title.rs

@@ -304,8 +304,6 @@ mod tests {
         }
     }
 
-    // --- Title composition tests ---
-
     #[test]
     fn kigi_only_produces_just_kigi() {
         let cfg = config_with_items(vec![TitleItem::Kigi]);
@@ -572,8 +570,6 @@ mod tests {
         assert_eq!(mgr.last_title, "Thinking - kigi");
     }
 
-    // --- Action Required blinking ---
-
     #[test]
     fn action_required_visible_on_first_tick() {
         let cfg = config_with_items(vec![TitleItem::ActionRequired, TitleItem::Kigi]);
@@ -598,7 +594,8 @@ mod tests {
         let mut mgr = TitleManager::new(&cfg);
         let state = TitleState {
             has_pending_permissions: true,
-            focused: false, // unfocused → should blink
+            // unfocused, so ActionRequired should blink
+            focused: false,
             ..idle_state()
         };
 
@@ -638,8 +635,6 @@ mod tests {
         assert_eq!(mgr.last_title, "kigi");
     }
 
-    // --- Dedup (no-op when unchanged) ---
-
     #[test]
     fn dedup_skips_emission_when_unchanged() {
         let cfg = config_with_items(vec![TitleItem::Kigi]);
@@ -655,8 +650,6 @@ mod tests {
         assert_eq!(mgr.last_title, title_before);
     }
 
-    // --- Empty items list ---
-
     #[test]
     fn empty_items_produces_kigi_fallback() {
         let cfg = config_with_items(vec![]);
@@ -665,8 +658,6 @@ mod tests {
         assert_eq!(mgr.last_title, "kigi");
     }
 
-    // --- Model item ---
-
     #[test]
     fn model_item_shown_when_present() {
         let cfg = config_with_items(vec![TitleItem::Model, TitleItem::Kigi]);
@@ -687,8 +678,6 @@ mod tests {
         assert_eq!(mgr.last_title, "kigi");
     }
 
-    // --- Cwd item ---
-
     #[test]
     fn cwd_shows_last_component() {
         let cfg = config_with_items(vec![TitleItem::Cwd, TitleItem::Kigi]);
@@ -701,8 +690,6 @@ mod tests {
         assert_eq!(mgr.last_title, "my-project - kigi");
     }
 
-    // --- TurnTimer item ---
-
     #[test]
     fn turn_timer_shown_when_above_one_second() {
         let cfg = config_with_items(vec![TitleItem::TurnTimer, TitleItem::Kigi]);
@@ -727,8 +714,6 @@ mod tests {
         assert_eq!(mgr.last_title, "kigi");
     }
 
-    // --- Truncation ---
-
     #[test]
     fn long_session_name_truncated_with_ellipsis() {
         let cfg = config_with_items(vec![TitleItem::SessionName]);
@@ -756,8 +741,6 @@ mod tests {
         assert_eq!(mgr.last_title, "short");
     }
 
-    // --- Reset ---
-
     #[test]
     fn reset_clears_state_and_emits_kigi() {
         let cfg = config_with_items(vec![TitleItem::SessionName, TitleItem::Kigi]);
@@ -777,8 +760,6 @@ mod tests {
         assert_eq!(mgr.tick_count, 0);
     }
 
-    // --- Full default config integration ---
-
     #[test]
     fn default_config_active_turn_with_permissions() {
         let cfg = default_config();
@@ -788,7 +769,8 @@ mod tests {
             session_name: Some("my-session"),
             activity: Some(&activity),
             has_pending_permissions: true,
-            focused: false, // unfocused → should blink per original test
+            // unfocused, so ActionRequired should blink
+            focused: false,
             ..idle_state()
         };
 
@@ -823,8 +805,6 @@ mod tests {
         assert_eq!(mgr.last_title, "kigi");
     }
 
-    // --- Multi-item combinations ---
-
     #[test]
     fn all_items_present_in_order() {
         let cfg = config_with_items(vec![