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-system-power/src/lib.rs

@@ -7,7 +7,7 @@
 //! token and the user is forced to re-login. See
 //! `kigi-shell`'s `AuthManager` sleep gate, which consumes these events to
 //! avoid *starting* a refresh just before sleep. An in-flight refresh is
-//! deliberately left to finish, never aborted (dropping it could discard a
+//! Deliberately left to finish, never aborted (dropping it could discard a
 //! rotated-token response and cause the very revocation this guards against);
 //! instead, its [`PowerEvent::WillSleep`] handler may block briefly (bounded)
 //! to hold off the suspend until that in-flight refresh completes — see the
@@ -49,7 +49,7 @@ pub enum PowerEvent {
     /// Handlers must therefore be idempotent and safe to "cancel" via
     /// `DidWake`.
     WillSleep,
-    /// The system resumed from sleep, or a previously announced sleep was
+    /// The system resumed from sleep, or a earlier announced sleep was
     /// cancelled (macOS `kIOMessageSystemWillNotSleep` after a vetoed
     /// idle-sleep query). Both mean "not sleeping (anymore)".
     DidWake,
@@ -161,7 +161,7 @@ mod tests {
     #[test]
     fn power_event_is_copy_eq() {
         let e = PowerEvent::WillSleep;
-        let copied = e; // Copy
+        let copied = e;
         assert_eq!(e, copied);
         assert_ne!(PowerEvent::WillSleep, PowerEvent::DidWake);
     }

crates/codegen/kigi-system-power/src/linux.rs

@@ -17,7 +17,7 @@ const IFACE: &str = "org.freedesktop.login1.Manager";
 
 /// Linux listener handle.
 ///
-/// There is intentionally no clean stop: the worker thread parks on a blocking
+/// There is deliberately no clean stop: the worker thread parks on a blocking
 /// logind signal iterator, which cannot be interrupted without a signal
 /// arriving, so dropping this neither joins nor cancels it. The thread (and its
 /// D-Bus connection + sleep-delay inhibitor fd) live until process exit. That

crates/codegen/kigi-system-power/src/macos.rs

@@ -46,8 +46,10 @@ type IoServiceInterestCallback = extern "C" fn(
 
 #[link(name = "CoreFoundation", kind = "framework")]
 unsafe extern "C" {
-    static kCFRunLoopCommonModes: *const c_void; // CFRunLoopMode (CFStringRef)
-    static kCFRunLoopDefaultMode: *const c_void; // CFRunLoopMode (CFStringRef)
+    // CFRunLoopMode (CFStringRef)
+    static kCFRunLoopCommonModes: *const c_void;
+    // CFRunLoopMode (CFStringRef)
+    static kCFRunLoopDefaultMode: *const c_void;
     fn CFRunLoopGetCurrent() -> *mut c_void;
     fn CFRunLoopRunInMode(
         mode: *const c_void,
@@ -274,7 +276,7 @@ extern "C" fn power_callback(
     if let Some(event) = event {
         // For sleep-bound messages the ack is sent only *after* the callback
         // returns: a `WillSleep` handler may block (bounded) waiting for an
-        // in-flight token refresh to finish, which intentionally delays the
+        // in-flight token refresh to finish, which deliberately delays the
         // `IOAllowPowerChange` and holds off the suspend. IOKit allows ~30 s
         // per phase before forcing sleep, so a bounded wait is safe. See the
         // `kigi_system_power` crate-level callback contract.

crates/codegen/kigi-system-power/src/windows.rs

@@ -1,8 +1,6 @@
 //! Windows system sleep/wake via `PowerRegisterSuspendResumeNotification`
 //! with a `DEVICE_NOTIFY_CALLBACK` recipient — no hidden window or message
 //! loop required (Windows 8+).
-//!
-//! NOTE: this module only compiles when targeting Windows.
 
 use std::os::raw::c_void;
 
@@ -29,8 +27,6 @@ struct Context {
 }
 
 pub(crate) struct Listener {
-    // Registration handle from `PowerRegisterSuspendResumeNotification`
-    // (a `*mut c_void`; cast to `HPOWERNOTIFY` for unregister).
     handle: *mut c_void,
     // Kept alive (and freed in `Drop`) because the OS holds a raw pointer to it.
     ctx: *mut Context,
@@ -70,6 +66,8 @@ impl Listener {
 
 impl Drop for Listener {
     fn drop(&mut self) {
+        // SAFETY: unregistering first guarantees the OS can no longer invoke
+        // the callback, so freeing `ctx` afterwards cannot race a live call.
         unsafe {
             PowerUnregisterSuspendResumeNotification(self.handle as HPOWERNOTIFY);
             drop(Box::from_raw(self.ctx));
@@ -82,14 +80,14 @@ unsafe extern "system" fn power_callback(
     event_type: u32,
     _setting: *const c_void,
 ) -> u32 {
-    // Safe: `context` is the live `Context` we registered with.
+    // SAFETY: `context` is the `Context` pointer we registered with, and the
+    // registration is unregistered before that box is freed.
     let ctx = unsafe { &*(context as *const Context) };
     match event_type {
         PBT_APMSUSPEND => (ctx.callback)(PowerEvent::WillSleep),
         // A single resume can deliver both PBT_APMRESUMEAUTOMATIC and
-        // PBT_APMRESUMESUSPEND, so `DidWake` may fire twice per wake. That is
-        // fine and intentional: lowering the sleep gate is idempotent, so a
-        // duplicate wake is harmless — do not try to "dedupe" this later.
+        // PBT_APMRESUMESUSPEND, so `DidWake` fires twice per wake. Intentional:
+        // lowering the sleep gate is idempotent, so do not "dedupe" this.
         PBT_APMRESUMEAUTOMATIC | PBT_APMRESUMESUSPEND => (ctx.callback)(PowerEvent::DidWake),
         _ => {}
     }