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-pager-pty-harness/src/screen.rs

@@ -1,4 +1,4 @@
-//! Layer 2a: Screen state tracking via `alacritty_terminal` (ptyctl).
+//! Layer 2a: screen state tracking via `alacritty_terminal` (ptyctl).
 //!
 //! Parses raw PTY output through a headless terminal emulator and provides
 //! queries for what the user would see on screen.
@@ -6,8 +6,6 @@
 use ptyctl::styled::StyledLine;
 use ptyctl::term::{ScreenOpts, ScreenOutput, SessionListener, Terminal};
 
-/// Tracks the virtual terminal screen state by feeding raw PTY output
-/// through an `alacritty_terminal`-based headless terminal (via ptyctl).
 pub struct ScreenTracker {
     terminal: Terminal,
     /// Receives terminal-generated replies (cursor-position reports, device
@@ -18,7 +16,6 @@ pub struct ScreenTracker {
 }
 
 impl ScreenTracker {
-    /// Create a new tracker for a terminal with the given dimensions.
     pub fn new(rows: u16, cols: u16) -> Self {
         let (tx, rx) = tokio::sync::mpsc::unbounded_channel();
         let listener = SessionListener::new(tx);
@@ -28,14 +25,11 @@ impl ScreenTracker {
         }
     }
 
-    /// Feed raw PTY output bytes into the terminal emulator.
     pub fn feed(&mut self, bytes: &[u8]) {
         self.terminal.feed(bytes);
     }
 
-    /// Drain any terminal-generated replies queued while parsing fed input
-    /// (cursor-position reports answering `ESC[6n`, device attributes, color
-    /// queries, …), concatenated in order. Empty when nothing was queued.
+    /// Replies queued while parsing fed input, concatenated in order.
     ///
     /// These MUST be written back to the PTY or programs that probe the
     /// terminal will hang or time out — most relevant here, the inline
@@ -51,23 +45,22 @@ impl ScreenTracker {
         out
     }
 
-    /// Return structured screen contents (no escape codes).
+    /// Structured screen contents, with escape codes stripped.
     pub fn output(&self) -> ScreenOutput {
         self.terminal.screen_content(&ScreenOpts::default())
     }
 
-    /// Return the full text contents of the screen (no escape codes).
+    /// Full screen text, with escape codes stripped.
     pub fn contents(&self) -> String {
         self.output().lines.join("\n")
     }
 
-    /// Check whether the screen contains the given text substring.
     pub fn contains(&self, text: &str) -> bool {
         self.contents().contains(text)
     }
 
-    /// Return the current cursor position as `(row, col)` (0-indexed, matching
-    /// the original vt100 convention used by existing tests).
+    /// Cursor position as `(row, col)`, 0-indexed to match the vt100
+    /// convention the tests are written against.
     pub fn cursor_position(&self) -> (u16, u16) {
         let pos = self.terminal.cursor_position();
         // ptyctl cursor is 1-indexed; the harness API is 0-indexed.
@@ -77,35 +70,32 @@ impl ScreenTracker {
         )
     }
 
-    /// Resize the virtual terminal to new dimensions.
     pub fn resize(&mut self, rows: u16, cols: u16) {
         self.terminal.resize(cols, rows);
     }
 
-    /// Return the full screen with style information for visual artifacts.
     pub fn styled(&self) -> Vec<StyledLine> {
         self.terminal.screen_styled(&ScreenOpts::default())
     }
 
-    /// Render the current screen as an HTML document.
     pub fn html(&self) -> String {
         self.terminal.screen_html(&ScreenOpts::default())
     }
 
-    /// Access the underlying ptyctl `Terminal` for advanced queries
-    /// (styled output, scrollback, terminal modes, etc.).
+    /// Escape hatch for queries this wrapper does not expose (scrollback
+    /// details, terminal modes, …).
     pub fn terminal(&self) -> &Terminal {
         &self.terminal
     }
 
-    /// Number of lines in the terminal's scrollback history — content that has
-    /// scrolled *above* the visible screen. This is where minimal mode's
-    /// committed conversation blocks land (printed via `insert_before`).
+    /// Number of history lines that have scrolled *above* the visible screen.
+    /// This is where minimal mode's committed conversation blocks land
+    /// (printed via `insert_before`).
     pub fn scrollback_count(&self) -> usize {
         self.terminal.scrollback_count()
     }
 
-    /// The full scrollback history as text, oldest line first.
+    /// Scrollback history as text, oldest line first.
     pub fn scrollback_text(&self) -> String {
         let n = self.terminal.scrollback_count();
         self.terminal
@@ -116,8 +106,7 @@ impl ScreenTracker {
             .join("\n")
     }
 
-    /// Scrollback history plus the visible screen, joined oldest→newest:
-    /// everything a user could see by scrolling up. Minimal-mode committed
+    /// Scrollback plus visible screen, oldest→newest. Minimal-mode committed
     /// content may be in either region depending on how much has accumulated,
     /// so assertions on committed output should use this.
     pub fn full_text(&self) -> String {
@@ -130,7 +119,6 @@ impl ScreenTracker {
         }
     }
 
-    /// Whether scrollback + visible screen contains `text`.
     pub fn full_contains(&self, text: &str) -> bool {
         self.full_text().contains(text)
     }
@@ -140,36 +128,28 @@ impl ScreenTracker {
 mod tests {
     use super::*;
 
-    /// Lines pushed above a small screen must be readable via the scrollback
-    /// helpers — the property minimal-mode e2e tests rely on to assert that a
-    /// committed block reached native scrollback.
     #[test]
     fn scrolled_off_lines_are_captured_by_scrollback_helpers() {
-        // 3-row screen; print 8 numbered lines so the first ones scroll off.
         let mut s = ScreenTracker::new(3, 20);
         for i in 1..=8 {
             s.feed(format!("line{i}\r\n").as_bytes());
         }
-        // The earliest lines are no longer on the visible screen…
         assert!(
             !s.contains("line1"),
             "line1 should have scrolled off-screen"
         );
-        // …but they are in scrollback, and full_text sees everything.
         assert!(s.scrollback_count() >= 5, "expected scrolled-off history");
         assert!(s.scrollback_text().contains("line1"));
         assert!(s.full_contains("line1"));
         assert!(s.full_contains("line8"));
     }
 
-    /// A DSR cursor-position query (`ESC[6n`) must produce a forwardable reply
-    /// (a CPR `ESC[<row>;<col>R`) — the mechanism minimal-mode tests rely on so
-    /// the inline viewport's startup cursor query completes. Without forwarding,
-    /// `--minimal` silently downgrades to full-screen inline.
+    /// Without a forwardable CPR reply the inline viewport's startup cursor
+    /// query never completes and `--minimal` silently downgrades to
+    /// full-screen inline.
     #[test]
     fn drain_responses_answers_cursor_position_query() {
         let mut s = ScreenTracker::new(24, 80);
-        // Nothing queued before any query is fed.
         assert!(s.drain_responses().is_empty());
 
         s.feed(b"\x1b[6n");