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-tty-utils/src/lib.rs

@@ -42,9 +42,7 @@ use std::io;
 mod process_scope;
 pub use process_scope::{ProcessScope, global_process_scope};
 
-// ---------------------------------------------------------------------------
 // TTY detach — pre_exec building block
-// ---------------------------------------------------------------------------
 
 /// Detach from the controlling TTY by starting a new session.
 ///
@@ -83,9 +81,7 @@ pub fn detach_from_tty() -> io::Result<()> {
     Ok(())
 }
 
-// ---------------------------------------------------------------------------
 // tokio::process::Command wrapper
-// ---------------------------------------------------------------------------
 
 /// Detach a `tokio::process::Command` from the parent's controlling TTY/console.
 ///
@@ -108,9 +104,7 @@ pub fn detach_command(cmd: &mut tokio::process::Command) {
     }
 }
 
-// ---------------------------------------------------------------------------
 // std::process::Command wrapper
-// ---------------------------------------------------------------------------
 
 /// Detach a `std::process::Command` from the parent's controlling TTY/console.
 ///
@@ -138,9 +132,7 @@ pub fn detach_std_command(cmd: &mut std::process::Command) {
     }
 }
 
-// ---------------------------------------------------------------------------
 // Process group lifecycle
-// ---------------------------------------------------------------------------
 
 /// Configure a command so the spawned child becomes the leader of a new
 /// process group.
@@ -367,9 +359,7 @@ impl Drop for ProcessGroup {
     }
 }
 
-// ---------------------------------------------------------------------------
 // Environment variable helpers
-// ---------------------------------------------------------------------------
 
 /// Returns environment variables that prevent CLI tools from launching any
 /// interactive program that would block waiting for user input — pagers,
@@ -450,9 +440,7 @@ fn noop_cmd() -> &'static str {
     }
 }
 
-// ---------------------------------------------------------------------------
 // Stderr redirection — shield TUI output from C-library noise
-// ---------------------------------------------------------------------------
 
 /// The dup'd stderr fd that writes to the real terminal. Set once by
 /// [`redirect_native_stderr`]. Stored as [`OwnedFd`](std::os::unix::io::OwnedFd)
@@ -492,7 +480,8 @@ pub fn redirect_native_stderr() {
         // at process start.
         let duped = unsafe { libc::dup(2) };
         if duped < 0 {
-            return; // best-effort; don't crash
+            // best-effort; don't crash
+            return;
         }
 
         // Store the duped fd (as OwnedFd) before redirecting.
@@ -718,7 +707,7 @@ mod tests {
         assert_eq!(env.get("GPG_TTY"), Some(&String::new()));
     }
 
-    // ── stderr redirect integration tests ────────────────────────
+    // stderr redirect integration tests
     //
     // The redirect/dup/restore cycle mutates process-global state
     // (fd 2 and a `OnceLock`), so the full flow runs in a subprocess
@@ -770,7 +759,8 @@ mod tests {
     #[test]
     fn stderr_redirect_roundtrip_body() {
         if std::env::var("__XAI_STDERR_REDIRECT_SUBPROCESS").is_err() {
-            return; // skip when not invoked as subprocess
+            // skip when not invoked as subprocess
+            return;
         }
 
         use std::io::Write;
@@ -832,7 +822,8 @@ mod tests {
         new_process_group(&mut cmd);
 
         let mut group = ProcessGroup::new().expect("create ProcessGroup");
-        #[allow(clippy::disallowed_methods)] // test: exercises ProcessGroup directly
+        // test: exercises ProcessGroup directly
+        #[allow(clippy::disallowed_methods)]
         let mut child = cmd.spawn().expect("spawn child");
         group.attach(&child).expect("attach child to group");
 
@@ -866,7 +857,8 @@ mod tests {
         new_process_group(&mut cmd);
 
         let mut group = ProcessGroup::new().expect("create ProcessGroup");
-        #[allow(clippy::disallowed_methods)] // test: exercises ProcessGroup + grandchild kill
+        // test: exercises ProcessGroup + grandchild kill
+        #[allow(clippy::disallowed_methods)]
         let mut child = cmd.spawn().expect("spawn leader");
         group.attach(&child).expect("attach leader to group");
 

crates/codegen/kigi-tty-utils/src/process_scope.rs

@@ -241,7 +241,8 @@ mod tests {
         let scope = ProcessScope::new();
         let (mut c, _g) = scope.spawn(sleeper()).unwrap();
         scope.kill_all();
-        scope.kill_all(); // second call must not panic / error
+        // second call must not panic / error
+        scope.kill_all();
         assert!(died(&mut c).await);
     }
 
@@ -262,7 +263,8 @@ mod tests {
             "dropping the owner's Arc must make the scope's weak dead"
         );
 
-        scope.kill_all(); // must be a no-op for the now-unowned group
+        // must be a no-op for the now-unowned group
+        scope.kill_all();
         // The child was never killed by the scope; clean it up so the test
         // doesn't leak a real `sleep` process.
         let _ = c.start_kill();
@@ -287,13 +289,16 @@ mod tests {
     #[tokio::test]
     async fn register_after_kill_all_reaps_immediately() {
         let scope = ProcessScope::new();
-        scope.kill_all(); // close the scope
+        // close the scope
+        scope.kill_all();
 
         let mut cmd = sleeper();
         scope.prepare(&mut cmd);
-        #[allow(clippy::disallowed_methods)] // test: exercises enroll() after close
+        // test: exercises enroll() after close
+        #[allow(clippy::disallowed_methods)]
         let mut child = cmd.spawn().unwrap();
-        let _group = scope.enroll(&child).unwrap(); // register() runs post-close
+        // register() runs post-close
+        let _group = scope.enroll(&child).unwrap();
         assert_eq!(
             scope.live_count(),
             0,