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/benches/edit_highlight.rs

@@ -48,8 +48,6 @@ const MEASURE_TIME: Duration = Duration::from_secs(3);
 const MEASURE_TIME_HEAVY: Duration = Duration::from_secs(5);
 const RENDER_WIDTH: u16 = 120;
 
-// ── Fixtures ────────────────────────────────────────────────────────────────
-
 struct Fixture {
     _dir: TempDir,
     path: PathBuf,
@@ -170,8 +168,6 @@ fn make_hunk_at(file_lines: &[&str], close_i: usize) -> Option<DiffHunk> {
     }
 }
 
-// ── Non-product prefix baseline ─────────────────────────────────────────────
-
 fn own_ranges(ranges: Vec<(SyntectStyle, &str)>) -> Vec<(SyntectStyle, String)> {
     ranges.into_iter().map(|(s, t)| (s, t.to_owned())).collect()
 }
@@ -233,8 +229,6 @@ fn estimate_style_map_bytes(map: &HashMap<usize, Vec<(ratatui::style::Style, Str
     bytes
 }
 
-// ── Bench groups ────────────────────────────────────────────────────────────
-
 fn configure_fast(group: &mut criterion::BenchmarkGroup<'_, criterion::measurement::WallTime>) {
     group
         .sample_size(SAMPLE_SIZE)
@@ -287,7 +281,6 @@ fn bench_matrix(c: &mut Criterion) {
     let config = DiffRenderConfig::default();
     let syntect = get_syntect();
 
-    // ── 500L + prefix (own heavy config) ────────────────────────────────────
     {
         let fx = gen_python_fixture(500, 8);
         let file_lines: Vec<&str> = fx.file_text.lines().collect();
@@ -308,7 +301,6 @@ fn bench_matrix(c: &mut Criterion) {
         group.finish();
     }
 
-    // ── 10kL session (no prefix) ────────────────────────────────────────────
     {
         let fx = gen_python_fixture(10_000, 40);
         let styles = compute_file_scoped_styles(fx.path(), &fx.file_text, &fx.hunks)

crates/codegen/kigi-tui/benches/render.rs

@@ -23,11 +23,9 @@ use kigi_tui::theme::Theme;
 
 static BENCH_MD: &str = include_str!("bench.md");
 
-/// Viewport dimensions for the benchmark.
 const VIEWPORT_WIDTH: u16 = 120;
 const VIEWPORT_HEIGHT: u16 = 50;
 
-/// How many lines to advance per step in full_scroll.
 const SCROLL_STEP: u16 = 10;
 
 /// Entry count for the reveal benchmarks. Approximates the ~3,200-entry
@@ -76,8 +74,6 @@ fn compute_layouts(
         .collect()
 }
 
-// ─── Benchmarks ────────────────────────────────────────────────────
-
 /// Render a single frame at scroll offset 0 (top of document).
 ///
 /// The per-frame baseline with no top clipping — only bottom-clipped.
@@ -152,11 +148,10 @@ fn bench_full_scroll(c: &mut Criterion) {
     let appearance = AppearanceConfig::default();
     let layouts = compute_layouts(&entries, &appearance);
 
-    // usize: scroll offset is usize in the render path.
     let total: usize = layouts
         .iter()
         .map(|l| l.height as usize + l.gap_after as usize)
-        .sum(); // heights + gaps
+        .sum();
     let max_scroll = total.saturating_sub(VIEWPORT_HEIGHT as usize);
 
     // Prime the wrap cache
@@ -271,8 +266,6 @@ fn bench_windowed_scroll(c: &mut Criterion) {
     g.finish();
 }
 
-// ─── Reveal (scrollback-search n/N navigation) ─────────────────────
-
 /// One paragraph of lorem-style body per entry (~1.7 KB), so the
 /// `REVEAL_ENTRIES`-entry corpus is on the order of the motivating session's
 /// searchable text (a few MB; the exact size is logged).

crates/codegen/kigi-tui/benches/search.rs

@@ -1,12 +1,11 @@
 //! Criterion benchmarks for scrollback search.
 //!
-//! - `scan` measures the raw regex scan over a large corpus — the work that ran
-//!   synchronously on the input thread on every keystroke before the background
-//!   daemon, and now runs off-thread.
-//! - `query_steady` / `query_cold` measure the UI-thread cost of `update_query`
-//!   after the daemon change: a steady keystroke only compiles the matcher and
-//!   enqueues the query (the scan is off-thread), while the cold path also
-//!   rebuilds and ships the corpus on a content change.
+//! - `scan` measures the raw regex scan over a large corpus — the work the
+//!   daemon runs off the input thread, sparing the UI a per-keystroke scan.
+//! - `query_steady` / `query_cold` measure the UI-thread cost of `update_query`:
+//!   a steady keystroke only compiles the matcher and enqueues the query (the
+//!   scan is off-thread), while the cold path also rebuilds and ships the corpus
+//!   on a content change.
 
 use std::hint::black_box;
 use std::time::Duration;
@@ -53,9 +52,8 @@ fn build_large_scrollback(entries: usize) -> ScrollbackState {
     state
 }
 
-/// The regex scan itself — the work the daemon now runs off the input thread
-/// (previously this ran synchronously per keystroke). `fox` appears in every
-/// entry, the worst case for match collection.
+/// The regex scan itself — the corpus work the daemon runs off the input
+/// thread. `fox` appears in every entry, the worst case for match collection.
 fn bench_scan(c: &mut Criterion) {
     let state = build_large_scrollback(CORPUS_ENTRIES);
     let mut index = ScrollbackSearchIndex::new();
@@ -71,9 +69,9 @@ fn bench_scan(c: &mut Criterion) {
     g.finish();
 }
 
-/// Steady keystroke after the daemon: the corpus is already shipped, so
-/// `update_query` just compiles the matcher and enqueues the query, and `poll`
-/// picks up the async result — no scan on the UI thread.
+/// Steady keystroke: the corpus is already shipped, so `update_query` just
+/// compiles the matcher and enqueues the query, and `poll` picks up the async
+/// result — no scan on the UI thread.
 fn bench_query_steady(c: &mut Criterion) {
     let state = build_large_scrollback(CORPUS_ENTRIES);
     let mut search = ScrollbackSearchState::open();