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/common/kigi-interjection-core/src/buffer.rs

@@ -3,30 +3,27 @@ use serde::{Deserialize, Serialize};
 use crate::events::EventQueue;
 use crate::format::format_interjection;
 
-/// A buffered mid-turn interjection awaiting the next safe drain point.
-/// `Attachment` is host-defined (inline images, asset IDs); core never reads it.
+/// Mid-turn interjection waiting for the next safe drain point.
+/// `Attachment` is host-defined; core never inspects it.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct PendingInterjection<Attachment> {
     pub text: String,
     pub attachments: Vec<Attachment>,
 }
 
-/// A drained entry, wrapped and ready to emit as a synthetic user message.
+/// Drained entry, framed as a synthetic user message.
 #[derive(Debug, Clone, PartialEq)]
 pub struct FormattedInterjection<Attachment> {
     pub text: String,
     pub attachments: Vec<Attachment>,
 }
 
-/// A queue of pending interjections — just an [`EventQueue`] of
-/// [`PendingInterjection`]. Use [`drain_formatted`] to drain + frame them as
-/// synthetic user messages.
+/// Queue of [`PendingInterjection`] values. Drain via [`drain_formatted`].
 pub type InterjectionBuffer<Attachment> = EventQueue<PendingInterjection<Attachment>>;
 
-/// Drain `buffer`, framing each entry as a synthetic user message (FIFO, one
-/// message per entry, never merged). `sanitize_text` runs on the raw text first
-/// (hosts strip artifacts like image placeholder paths; pass
-/// `std::convert::identity` if none).
+/// Drain `buffer` FIFO, one synthetic user message per entry (never merged).
+/// `sanitize_text` runs on raw text first (e.g. strip image placeholders);
+/// pass `std::convert::identity` when none is needed.
 pub fn drain_formatted<Attachment>(
     buffer: &InterjectionBuffer<Attachment>,
     sanitize_text: impl Fn(String) -> String,

crates/common/kigi-interjection-core/src/events.rs

@@ -1,7 +1,6 @@
-//! Shared event queue for the push path: producers enqueue out-of-band events;
-//! readers drain the ones relevant to them at hook points. Internally
-//! synchronized and `Arc`-shared (clones share one queue), mirroring
-//! [`crate::buffer::InterjectionBuffer`].
+//! Shared push-path event queue: producers enqueue; readers drain at hook
+//! points. Internally synchronized and `Arc`-shared (clones share one queue),
+//! matching [`crate::buffer::InterjectionBuffer`].
 
 use std::sync::{Arc, Mutex, MutexGuard};
 
@@ -31,12 +30,11 @@ impl<E> EventQueue<E> {
         }
     }
 
-    /// Producer hook: record an event for later draining.
     pub fn push(&self, event: E) {
         self.lock().push(event);
     }
 
-    /// Push, then drop the oldest events so at most `max` remain.
+    /// Push, then drop oldest entries so length stays ≤ `max`.
     pub fn push_capped(&self, event: E, max: usize) {
         let mut q = self.lock();
         q.push(event);
@@ -54,8 +52,7 @@ impl<E> EventQueue<E> {
         self.lock().is_empty()
     }
 
-    /// Remove and return events matching `take`, retaining the rest. FIFO order
-    /// is preserved in both the returned and retained sets.
+    /// Remove matching events; keep the rest. Both sets stay FIFO.
     pub fn drain_matching(&self, take: impl Fn(&E) -> bool) -> Vec<E> {
         let mut q = self.lock();
         let (matched, kept): (Vec<E>, Vec<E>) =
@@ -64,12 +61,10 @@ impl<E> EventQueue<E> {
         matched
     }
 
-    /// Remove and return all events, leaving the queue empty (FIFO order).
     pub fn drain_all(&self) -> Vec<E> {
         std::mem::take(&mut *self.lock())
     }
 
-    /// Discard all events.
     pub fn clear(&self) {
         self.lock().clear();
     }
@@ -80,7 +75,7 @@ impl<E> EventQueue<E> {
 }
 
 impl<E: Clone> EventQueue<E> {
-    /// Clone of the current events, for inspection without draining.
+    /// Snapshot without draining.
     pub fn snapshot(&self) -> Vec<E> {
         self.lock().clone()
     }

crates/common/kigi-interjection-core/src/format.rs

@@ -1,4 +1,4 @@
-/// Truncation threshold, matching the shell's large-prompt limit.
+/// Truncation threshold; matches the shell's large-prompt limit.
 pub const LARGE_PROMPT_THRESHOLD: usize = 25_000;
 
 /// Wrap a user message in the canonical `<user_query>` envelope.
@@ -10,9 +10,9 @@ pub fn user_query(user_message: &str) -> String {
     )
 }
 
-/// Wrap interjection text as a synthetic user message with a mid-turn note.
-/// No deferral instruction: the model decides how to weigh it against
-/// in-flight work. Output is byte-identical to the shell's historical format.
+/// Frame interjection text as a synthetic mid-turn user message.
+/// No deferral instruction — the model weighs it against in-flight work.
+/// Byte-identical to the shell's historical format.
 pub fn format_interjection(text: String) -> String {
     let truncated = if text.len() > LARGE_PROMPT_THRESHOLD {
         let end = text