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/scroll_matrix/cells.rs

@@ -120,7 +120,7 @@ const AUTO_MUX_NODROP: &[InvariantId] = &[
 ];
 const AUTO_SCREEN: &[InvariantId] = &[Ord, Cap, DropEq, Cadence, ConsA, Accel, Carry, Cfg, Screen];
 /// The jerk suite: core + the two smoothness invariants the finalize-decel
-/// fix made hold (formerly this cell's xfail set).
+/// fix made hold (once this cell's xfail set).
 const JERK: &[InvariantId] = &[
     Ord,
     Cap,
@@ -158,7 +158,7 @@ const fn cell(
 /// The matrix. Ids are `<class>_<config>_<gesture>[_qualifier]`.
 #[rustfmt::skip]
 pub const CELLS: &[MatrixCell] = &[
-    // ── Curated (CI tier, 8 cells) ─────────────────────────────────────
+    // Curated (CI tier, 8 cells)
     cell("c1_auto_g3_flood_speed100", Tier::Curated, &[SPEED100],
         ExpectedProfile { speed: 6.0, ..C1 }, GestureId::G3Flood, SessionKind::Settled, AUTO_QUIET),
     cell("c2_auto_g3_flood_speed100", Tier::Curated, &[ITERM, SPEED100],
@@ -179,7 +179,7 @@ pub const CELLS: &[MatrixCell] = &[
     // (I-SMOOTH-COAST, I-NO-DROP) are ordinary pass rows now.
     cell("c1_auto_g4_jerk_xfail", Tier::Curated, &[],
         C1, GestureId::G4Jerk, SessionKind::Settled, JERK),
-    // ── Full tier (local sweep; representative subset — see trim note) ─
+    // Full tier (local sweep; representative subset — see trim note)
     cell("c1_auto_g1", Tier::Full, &[], C1,
         GestureId::G1Notch, SessionKind::Settled, AUTO_NODROP),
     cell("c1_auto_g2", Tier::Full, &[], C1,
@@ -250,7 +250,8 @@ mod tests {
         if let Some(lines) = get("KIGI_SCROLL_LINES") {
             let lines: u16 = lines.parse().unwrap();
             wheel_lpt = lines;
-            trackpad_lpt = lines; // one knob overrides both paths
+            // one knob overrides both paths
+            trackpad_lpt = lines;
         }
         // speed_to_multiplier re-derivation for the settings used in rows.
         let speed = match get("KIGI_SCROLL_SPEED") {

crates/codegen/kigi-pager-pty-harness/src/scroll_matrix/gestures.rs

@@ -35,9 +35,8 @@ pub const MIN_LINES_PER_WHEEL_STREAM: i64 = 1;
 
 /// One SGR wheel report: sleep `pre_delay_ms`, then emit `button`.
 ///
-/// `button` is [`SGR_SCROLL_UP`]/[`SGR_SCROLL_DOWN`] — `u16` because those
-/// harness consts are `u16` (the design sketch said `u8`; deviating keeps
-/// one shared definition instead of a cast at every emission site).
+/// `button` is `u16` because the [`SGR_SCROLL_UP`]/[`SGR_SCROLL_DOWN`]
+/// harness consts are, sparing a cast at every emission site.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct WheelStep {
     /// Host-side sleep before emitting this report (0 for the first step).
@@ -190,7 +189,6 @@ pub enum GestureId {
 }
 
 impl GestureId {
-    /// Every gesture, for exhaustive table sweeps (tests, the A13 runner).
     pub const ALL: [GestureId; 12] = [
         GestureId::G1Notch,
         GestureId::G2NotchTrain,
@@ -256,7 +254,7 @@ impl GestureId {
     }
 }
 
-/// `(up, down)` report counts — direction-sum test primitive.
+/// `(up, down)` report counts.
 pub fn direction_counts(steps: &[WheelStep]) -> (usize, usize) {
     let up = steps.iter().filter(|s| s.button == SGR_SCROLL_UP).count();
     (up, steps.len() - up)
@@ -266,8 +264,6 @@ pub fn direction_counts(steps: &[WheelStep]) -> (usize, usize) {
 mod tests {
     use super::*;
 
-    /// Streams split on gaps > STREAM_GAP_MS or direction flips — recompute
-    /// from the table and compare to the declared `expected_streams`.
     fn streams_in(steps: &[WheelStep]) -> usize {
         let mut streams = 1;
         for pair in steps.windows(2) {
@@ -298,18 +294,15 @@ mod tests {
 
     #[test]
     fn notch_structure_and_gaps() {
-        // G2/ept3: notch starts every 3 events carry the 50ms gap, intra-notch 0.
         for (i, step) in G2_NOTCH_TRAIN_EPT3.iter().enumerate() {
             let expected = if i > 0 && i % 3 == 0 { 50 } else { 0 };
             assert_eq!(step.pre_delay_ms, expected, "G2 ept3 step {i}");
         }
-        // G9b: same shape at 55ms — under the 80ms gap, one stream.
         let notch_gaps = G9B_MUX_BATCH
             .iter()
             .filter(|s| s.pre_delay_ms == 55)
             .count();
         assert_eq!(notch_gaps, 7, "8 notches → 7 inter-notch gaps");
-        // G5: dup 4ms after each notch head, notch heads 60ms apart.
         for (i, step) in G5_GHOSTTY_DUP.iter().enumerate() {
             let expected = if i == 0 {
                 0
@@ -345,8 +338,6 @@ mod tests {
 
     #[test]
     fn delays_agree_with_stream_gap_thresholds() {
-        // Single-stream gestures never pause past the 80ms finalize gap and
-        // never flip; multi-stream ones split exactly as declared.
         for gesture in GestureId::ALL {
             for ept in [1u16, 3] {
                 let steps = gesture.steps(ept);
@@ -359,13 +350,10 @@ mod tests {
                 );
             }
         }
-        // The G11 pause is what splits it: strictly past the finalize gap.
         assert!(G11_CARRY_EPT3[3].pre_delay_ms > STREAM_GAP_MS);
         assert!(G11_CARRY_EPT1[1].pre_delay_ms > STREAM_GAP_MS);
-        // G1/ept3 is a first tick inside the wheel-promotion window.
         let g1_span: u64 = G1_NOTCH_EPT3.iter().map(|s| s.pre_delay_ms).sum();
         assert!(g1_span <= WHEEL_TICK_DETECT_MAX_MS);
-        // G5's dup spacing must sit under the interval-window floor.
         assert!((G5_GHOSTTY_DUP[1].pre_delay_ms as f64) < ACCEL_MIN_INTERVAL_MS);
     }
 }

crates/codegen/kigi-pager-pty-harness/src/scroll_matrix/invariants.rs

@@ -463,7 +463,7 @@ mod tests {
     use super::super::log::{group_streams, parse_jsonl_str};
     use super::*;
 
-    // ── JSONL fixture builders ─────────────────────────────────────────
+    // JSONL fixture builders
     // Raw strings through parse_jsonl_str so every fixture also exercises
     // the wire schema (same stance as log.rs's producer-shaped constants).
 
@@ -498,7 +498,8 @@ mod tests {
         kind: &str,
         events: (u64, u64),
         accel_avg: (f32, Option<f64>),
-        lines: (f32, i64, i64, i64), // desired, applied_total, flushed, backlog_after
+        // desired, applied_total, flushed, backlog_after
+        lines: (f32, i64, i64, i64),
         msf: Option<f64>,
         dropped: Option<i64>,
     ) -> String {
@@ -710,7 +711,8 @@ mod tests {
     fn cfg_rejects_echo_profile_mismatch() {
         assert!(check(InvariantId::Cfg, &C1, &canonical()).is_pass());
         let mut fixture = canonical();
-        fixture[0] = start(0.0, 0.0, "auto", 6.0); // speed echo ≠ expected 1.0
+        // speed echo ≠ expected 1.0
+        fixture[0] = start(0.0, 0.0, "auto", 6.0);
         assert_violated(check(InvariantId::Cfg, &C1, &fixture), "speed");
         let expected_wheel = ExpectedProfile {
             mode: "wheel",

crates/codegen/kigi-pager-pty-harness/src/scroll_matrix/log.rs

@@ -292,7 +292,8 @@ mod tests {
 
     fn jsonl(lines: &[&str]) -> String {
         let mut out = lines.join("\n");
-        out.push('\n'); // producer's writeln! always terminates lines
+        // producer's writeln! always terminates lines
+        out.push('\n');
         out
     }
 

crates/codegen/kigi-pager-pty-harness/src/scroll_matrix/report.rs

@@ -35,7 +35,6 @@ pub enum CellStatus {
 }
 
 impl CellStatus {
-    /// Fixed-width table label.
     pub fn as_str(self) -> &'static str {
         match self {
             CellStatus::Pass => "PASS",
@@ -46,7 +45,6 @@ impl CellStatus {
     }
 }
 
-/// One invariant row of a [`CellReport`].
 #[derive(Clone, Debug, Serialize)]
 pub struct InvariantReport {
     /// Design vocabulary id (`I-ORD`, …).
@@ -57,7 +55,6 @@ pub struct InvariantReport {
     pub detail: Option<String>,
 }
 
-/// Verdict of one matrix cell run.
 #[derive(Clone, Debug, Serialize)]
 pub struct CellReport {
     pub cell_id: String,
@@ -88,8 +85,7 @@ pub fn exit_code(reports: &[CellReport]) -> u8 {
     u8::from(failed)
 }
 
-/// Write `report.json` (pretty, array of [`CellReport`]) into `dir`,
-/// creating it as needed; returns the file path.
+/// Write the reports as `dir/report.json`, creating `dir` as needed.
 pub fn write_report_json(reports: &[CellReport], dir: &Path) -> Result<PathBuf> {
     std::fs::create_dir_all(dir)
         .with_context(|| format!("create artifacts dir {}", dir.display()))?;
@@ -208,7 +204,6 @@ mod tests {
             "XFail is green"
         );
         assert_eq!(exit_code(&[pass.clone(), fail]), 1);
-        // The fixed-bug tripwire: an xfail cell that PASSES must break the run.
         assert_eq!(exit_code(&[pass, xfail, xpass]), 1, "XPass must be nonzero");
     }
 
@@ -267,12 +262,10 @@ mod tests {
         let lines: Vec<&str> = table.lines().collect();
         assert_eq!(lines.len(), 3, "header + one row per cell:\n{table}");
 
-        // Every row's STATUS column starts where the header's does.
         let status_col = lines[0].find("STATUS").expect("header STATUS");
         assert_eq!(&lines[1][status_col..status_col + 4], "PASS");
         assert_eq!(&lines[2][status_col..status_col + 4], "FAIL");
 
-        // Failure detail is carried (truncated, newlines flattened).
         assert!(lines[2].contains("I-CAP: flushed 40"), "table:\n{table}");
         assert!(lines[2].contains("..."), "long detail truncated:\n{table}");
         assert!(

crates/codegen/kigi-pager-pty-harness/src/scroll_matrix/runner.rs

@@ -68,7 +68,6 @@ const COMPLETION_TIMEOUT: Duration = Duration::from_secs(30);
 /// streaming preamble plus its post-gesture tail drain — finishes in ~20s.
 const CELL_HARD_CAP: Duration = Duration::from_secs(60);
 
-/// `tier` label for [`CellReport`].
 fn tier_label(tier: Tier) -> &'static str {
     match tier {
         Tier::Curated => "curated",
@@ -145,7 +144,6 @@ fn panic_message(err: tokio::task::JoinError) -> String {
     }
 }
 
-/// Everything [`run_cell`] needs from a completed (non-aborted) cell body.
 struct CellRun {
     outcomes: Vec<(InvariantId, InvariantResult)>,
     streams: usize,
@@ -311,11 +309,9 @@ fn check_screen(
     InvariantResult::Pass
 }
 
-/// XPASS row detail: the actionable half of the xfail contract.
 const XPASS_DETAIL: &str = "expected to violate (xfail) but PASSED — the pinned bug got fixed \
                             or the cell rotted; promote the invariant out of the xfail set";
 
-/// Classify evaluated invariants into per-row statuses and the cell verdict.
 /// Precedence: any `Fail` (non-xfail violation) fails the cell; else any
 /// `XPass` fails it (fixed/rotted xfail must be promoted, not absorbed);
 /// else any `XFail` marks the expected failure; else `Pass`.
@@ -370,8 +366,8 @@ mod tests {
         }
     }
 
-    /// The wire bytes of the shared wheel position, pinned to the
-    /// `40;12` encoding documented on `WHEEL_ROW`/`WHEEL_COL`.
+    /// Pins the wire bytes to the `40;12` encoding documented on
+    /// `WHEEL_ROW`/`WHEEL_COL`.
     #[test]
     fn sgr_report_encodes_one_based_wire_coords() {
         assert_eq!(sgr_wheel_report(64), "\x1b[<64;40;12M");
@@ -382,9 +378,7 @@ mod tests {
     fn clamped_travel_models_bottom_pin_and_top_clamp() {
         // G7's shape: down-deliveries at the pin don't move, the up tail does.
         assert_eq!(simulate_clamped_travel(300, [10, -7]), -7);
-        // Up then partially back down: net movement, no clamp involved.
         assert_eq!(simulate_clamped_travel(300, [-5, 3]), -2);
-        // Pure down at the pin stays put.
         assert_eq!(simulate_clamped_travel(300, [10]), 0);
         // Down past the pin then up: the overshoot must not bank as credit.
         assert_eq!(simulate_clamped_travel(300, [25, -4]), -4);
@@ -422,13 +416,11 @@ mod tests {
     fn classify_precedence_fail_over_xpass_over_xfail_over_pass() {
         use InvariantId::{Cap, NoDrop, Ord, SmoothCoast};
 
-        // All pass, nothing xfailed → Pass.
         let (status, rows) = classify(&[(Ord, InvariantResult::Pass)], &[]);
         assert_eq!(status, CellStatus::Pass);
         assert_eq!(rows[0].status, InvariantStatus::Pass);
         assert_eq!(rows[0].id, "I-ORD");
 
-        // The declared bug violates, everything else passes → XFail.
         let jerk = [
             (Ord, InvariantResult::Pass),
             (SmoothCoast, violated("coast")),
@@ -439,7 +431,7 @@ mod tests {
         assert_eq!(rows[1].status, InvariantStatus::XFail);
         assert_eq!(rows[1].detail.as_deref(), Some("coast"));
 
-        // One xfail row passing flips the cell to XPass (fixed-bug tripwire)…
+        // One xfail row passing flips the cell to XPass: the fixed-bug tripwire.
         let half_fixed = [
             (SmoothCoast, InvariantResult::Pass),
             (NoDrop, violated("dropped 74")),
@@ -448,7 +440,7 @@ mod tests {
         assert_eq!(status, CellStatus::XPass);
         assert!(rows[0].detail.as_deref().unwrap().contains("promote"));
 
-        // …but any non-xfail violation dominates everything.
+        // A non-xfail violation dominates everything.
         let broken = [
             (Cap, violated("flushed 40 exceeds cap 25")),
             (SmoothCoast, InvariantResult::Pass),

crates/codegen/kigi-pager-pty-harness/src/scroll_matrix/session.rs

@@ -67,7 +67,7 @@ const MARKER_PREFIX: &str = "MARKER-";
 /// off-screen while the tail is in flight (witness for "still streaming").
 pub const STREAM_END_SENTINEL: &str = "STREAMDONE";
 
-/// Unique numbered marker line (`MARKER-0042`), zero-padded so no marker is
+/// Unique numbered marker line (`MARKER-0042`), zero-`padded` so no marker is
 /// a substring of another within a [`marker_response`] transcript.
 pub fn marker_line(n: usize) -> String {
     format!("{MARKER_PREFIX}{n:04}")