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-log/src/appender.rs

@@ -41,6 +41,7 @@ pub(crate) fn flush_file_log_guards() {
     if let Some(m) = FILE_LOG_GUARDS.get() {
         // Recover from a poisoned mutex so exit-flush still drains the guards.
         let mut guards = m.lock().unwrap_or_else(|poisoned| poisoned.into_inner());
-        guards.clear(); // dropping each WorkerGuard flushes + joins its writer thread
+        // dropping each WorkerGuard flushes + joins its writer thread
+        guards.clear();
     }
 }

crates/codegen/kigi-log/src/debug_log.rs

@@ -105,7 +105,7 @@ where
     Ok(fmt_layer)
 }
 
-// ── Per-session routing layer ───────────────────────────────────────────────
+// Per-session routing layer
 
 /// Filesystem-safe session key. Sanitized once at capture (`on_new_span`) and
 /// stashed in the span's tracing extensions, so events fired anywhere under the
@@ -148,7 +148,7 @@ impl Visit for EventVisitor {
     }
 }
 
-// Format one compact, ANSI-free firehose line. Intentionally NOT byte-identical
+// Format one compact, ANSI-free firehose line. Deliberately NOT byte-identical
 // to `fmt::Layer`: its `FormatEvent` can't be reused from another layer and a
 // `MakeWriter` can't see span context, so we render here. Span context is
 // omitted on purpose — the file name already carries the session id.
@@ -355,7 +355,7 @@ where
     }
 }
 
-// ── Install + lifecycle ──────────────────────────────────────────────────────
+// Install + lifecycle
 
 /// Resolve the requested debug target and install the matching firehose layer on
 /// `registry`, then init the subscriber.

crates/codegen/kigi-log/src/hooks_log.rs

@@ -112,7 +112,8 @@ fn resolve_log_path() -> Option<PathBuf> {
     let default_path = || kigi_home().join("logs").join("hooks.log");
     let raw = match std::env::var(ENV_HOOKS_LOG) {
         Ok(val) => val,
-        Err(_) => return None, // opt-in only
+        // opt-in only
+        Err(_) => return None,
     };
     let raw = raw.trim();
     match raw {

crates/codegen/kigi-log/src/instrumentation.rs

@@ -251,7 +251,8 @@ where
     // registration issue when the layer is boxed as Box<dyn Layer<S>>.
     let fmt_layer = tracing_subscriber::fmt::layer()
         .json()
-        .with_current_span(false) // `spans` array already carries the full ancestor list
+        // `spans` array already carries the full ancestor list
+        .with_current_span(false)
         .with_ansi(false)
         .with_timer(tracing_subscriber::fmt::time::UtcTime::rfc_3339())
         .with_thread_ids(true)

crates/codegen/kigi-log/src/lib.rs

@@ -1,10 +1,7 @@
 //! Local, zero-egress observability for Kigi sessions.
 //!
-//! Every sink in this crate writes to the local filesystem (under the Kigi
-//! home directory) and nothing else: the unified session log, the `--debug`
-//! firehose, subsystem file logs (memory, hooks, sampling), and the
-//! env-gated performance instrumentation. No module here opens a network
-//! connection — that property is the crate's contract.
+//! Every sink writes under the Kigi home directory and nowhere else. No module
+//! here may open a network connection — that is the crate's contract.
 
 mod appender;
 pub mod debug_log;

crates/codegen/kigi-log/src/memory_log.rs

@@ -1,15 +1,8 @@
 //! Memory system tracing target and optional file-based logging layer.
 //!
-//! Provides a dedicated tracing target (`xai_memory`) with an optional
-//! file logger that writes to `~/.kigi/logs/memory.log`.
-//!
-//! ## When to use
-//!
-//! Use `tracing::info!(target: memory_log::TARGET, ...)` at memory system
-//! lifecycle points — config resolution, storage init, flush, search, etc.
-//! These events are always emitted (zero cost when the layer is absent).
-//!
-//! ## Enabling (debug builds)
+//! Emit events with `tracing::info!(target: memory_log::TARGET, ...)` at memory
+//! system lifecycle points — config resolution, storage init, flush, search.
+//! They are always emitted, at zero cost when the layer is absent.
 //!
 //! ```bash
 //! # build with memory logging enabled, then:
@@ -63,9 +56,7 @@ mod inner {
         }
     }
 
-    /// Build the memory log layer.
-    ///
-    /// Writes to `~/.kigi/logs/memory.log`. Filters to `xai_memory=trace`.
+    /// Writes to `~/.kigi/logs/memory.log`, filtered to `xai_memory=trace`.
     /// Set `KIGI_MEMORY_LOG=0` to disable, `KIGI_MEMORY_LOG=/path` to redirect.
     pub fn layer<S>() -> Option<impl Layer<S>>
     where

crates/codegen/kigi-log/src/sampling_log.rs

@@ -60,7 +60,8 @@ where
 
     let fmt_layer = tracing_subscriber::fmt::layer()
         .json()
-        .with_current_span(false) // `spans` array already carries the full ancestor list
+        // `spans` array already carries the full ancestor list
+        .with_current_span(false)
         .with_ansi(false)
         .with_timer(tracing_subscriber::fmt::time::UtcTime::rfc_3339())
         .with_target(false)

crates/codegen/kigi-log/src/session_ctx.rs

@@ -5,16 +5,13 @@
 //! `session_id` field. [`with_session_ctx`] installs that span for the
 //! duration of a session's work.
 
-/// The `session_id` field name the debug-log firehose router keys on:
-/// `debug_log::SessionIdVisitor` stashes a `SessionId` extension on any span
-/// carrying this field — the span *name* is not load-bearing for routing. Shared
-/// so the `info_span!` here and the router in `debug_log` can't silently drift; a
-/// rename trips `session_span_exposes_router_field` below.
+/// The field name the firehose router keys on: `debug_log::SessionIdVisitor`
+/// stashes a `SessionId` extension on any span carrying this field — the span
+/// *name* is not load-bearing for routing.
 pub(crate) const SESSION_ID_FIELD: &str = "session_id";
 
-/// Build the per-session tracing span the firehose router routes by. The field
-/// name MUST be the literal `session_id` (tracing field names can't come from a
-/// const); the test below pins it against [`SESSION_ID_FIELD`].
+/// The field name MUST be the literal `session_id` (tracing field names can't
+/// come from a const); the test below pins it against [`SESSION_ID_FIELD`].
 fn session_span(session_id: &str) -> tracing::Span {
     tracing::info_span!("session", session_id = %session_id)
 }
@@ -30,11 +27,8 @@ pub async fn with_session_ctx<F: std::future::Future>(session_id: &str, fut: F)
 mod tests {
     use super::*;
 
-    /// The debug-log firehose router (`debug_log`) finds the session span by its
-    /// `session_id` field (not by name). That field name is a literal in
-    /// `session_span` (tracing field names can't be a const), so pin it against the
-    /// shared const here — a rename of either breaks this test instead of silently
-    /// degrading routing to the per-pid fallback.
+    /// Without this pin, a diverging field name silently degrades routing to the
+    /// per-pid fallback instead of failing.
     #[test]
     fn session_span_exposes_router_field() {
         // A bare registry enables every callsite, so the span has live metadata.

crates/codegen/kigi-log/src/unified_log.rs

@@ -26,14 +26,12 @@ pub fn set_version(ver: &str) {
 
 pub const LOG_DIR: &str = "logs";
 const LOG_FILE: &str = "unified.jsonl";
-pub const MAX_SIZE: u64 = 5 * 1024 * 1024; // 5 MB
+pub const MAX_SIZE: u64 = 5 * 1024 * 1024;
 
 /// ACP method name for unified log notifications.
 pub const LOG_METHOD: &str = "kigi/log";
 
-// ---------------------------------------------------------------------------
 // Log entry types
-// ---------------------------------------------------------------------------
 
 /// Log level for a unified log entry.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, strum::Display, Serialize, Deserialize)]
@@ -126,9 +124,7 @@ pub struct ClientLogEntry {
     pub ctx: Option<serde_json::Value>,
 }
 
-// ---------------------------------------------------------------------------
 // Writer
-// ---------------------------------------------------------------------------
 
 struct LogWriter {
     file: File,
@@ -228,9 +224,7 @@ pub fn trim_file(path: &std::path::Path) {
     }
 }
 
-// ---------------------------------------------------------------------------
 // Public API
-// ---------------------------------------------------------------------------
 
 /// Return a new timestamp string in the unified log format.
 fn now_ts() -> String {
@@ -315,7 +309,7 @@ pub fn snapshot_log() -> Option<Vec<u8>> {
     {
         let _ = w.file.flush();
     }
-    // Lock released intentionally — snapshot is approximate.
+    // Lock released deliberately — snapshot is approximate.
     match fs::read(&path) {
         Ok(data) if !data.is_empty() => Some(data),
         _ => None,