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-sampler/src/stream/chat_completions.rs

@@ -96,7 +96,8 @@ pub fn stream_chat_completions<'a>(
         loop {
             let next = match tokio::time::timeout(idle_timeout, stream.next()).await {
                 Ok(Some(next)) => next,
-                Ok(None) => break, // stream ended normally
+                // stream ended normally
+                Ok(None) => break,
                 Err(_elapsed) => {
                     let err = SamplingError::IdleTimeout {
                         elapsed_secs: idle_timeout.as_secs(),
@@ -253,7 +254,7 @@ pub fn stream_chat_completions<'a>(
             }
         }
 
-        // ── Build the final response ─────────────────────────────────
+        // Build the final response
         let tool_calls: Vec<ToolCall> = tool_call_acc
             .into_values()
             .map(|(id, name, arguments)| {

crates/codegen/kigi-sampler/src/stream/collect.rs

@@ -38,7 +38,6 @@ pub async fn collect_response(
                 response, metrics, ..
             } => return Ok((*response, metrics)),
             SamplingEvent::Failed { error, .. } => return Err(error),
-            // Drop intermediate events; this is a buffered collector.
             _ => {}
         }
     }

crates/codegen/kigi-sampler/src/stream/messages.rs

@@ -241,7 +241,8 @@ pub fn stream_messages<'a>(
                             arguments_delta: None,
                         };
                     }
-                    _ => {} // Image / ToolResult are not expected in assistant streams.
+                    // Image / ToolResult are not expected in assistant streams.
+                    _ => {}
                 },
 
                 MessageStreamEvent::ContentBlockDelta { index, delta } => {
@@ -460,7 +461,7 @@ pub fn stream_messages<'a>(
             return;
         }
 
-        // ── Build the final response ─────────────────────────────────
+        // Build the final response
         let model_id = final_model.unwrap_or_default();
         // Match the OAI Responses convention: prompt_tokens = full prompt, cached_prompt_tokens = cache hits only.
         let total_prompt_tokens = final_input_tokens

crates/codegen/kigi-sampler/src/stream/messages_tests.rs

@@ -537,7 +537,7 @@ fn meaningful_content_classifier_treats_ping_as_keepalive() {
     ));
 }
 
-// ── Token usage: Anthropic Messages API cache-bucket accounting ────────────
+// Token usage: Anthropic Messages API cache-bucket accounting
 
 fn message_start_with_cache(
     input: u32,

crates/codegen/kigi-sampler/src/stream/mod.rs

@@ -1,12 +1,11 @@
 //! Layer-2 stream transforms: turn raw HTTP chunk streams into
 //! [`SamplingEvent`](crate::events::SamplingEvent) streams.
 //!
-//! Each backend has its own transform because the raw chunk types
-//! differ; backend dispatch happens in M4's
-//! [`actor::request_task`](crate::actor::request_task), which knows
-//! the API backend from `SamplerConfig.api_backend` and calls the
-//! matching `SamplingClient::conversation_stream*` method before
-//! handing the result to the corresponding transform here.
+//! Each backend needs its own transform because the raw chunk types differ.
+//! Dispatch lives in [`actor::request_task`](crate::actor::request_task),
+//! which reads the backend from `SamplerConfig.api_backend`, calls the
+//! matching `SamplingClient::conversation_stream*` method, and hands the
+//! result to the transform here.
 
 pub mod chat_completions;
 pub mod collect;

crates/codegen/kigi-sampler/src/stream/responses.rs

@@ -261,7 +261,7 @@ pub fn stream_responses<'a>(
                 }
 
                 // Continuation chunk for a streaming FunctionCall's args.
-                // Drop silently if no preceding OutputItemAdded mapped.
+                // Drop silently if no preceding `OutputItemAdded` mapped.
                 ResponseStreamEvent::ResponseFunctionCallArgumentsDelta(args_event) => {
                     let delta = args_event.delta;
                     if !delta.is_empty()
@@ -323,7 +323,7 @@ pub fn stream_responses<'a>(
                     return;
                 }
 
-                // ── Backend-hosted tool lifecycle events ────────────
+                // Backend-hosted tool lifecycle events
                 // These tools are executed server-side by the agentic
                 // sampler. We emit progress events so the shell/pager
                 // can show status to the user.
@@ -406,7 +406,7 @@ pub fn stream_responses<'a>(
             }
         }
 
-        // ── Build the final response ─────────────────────────────────
+        // Build the final response
         let mut response = match final_response {
             Some(r) => r,
             None => {
@@ -437,7 +437,7 @@ pub fn stream_responses<'a>(
         // (`deserialize_response_event`) has already rewritten
         // `u.total_tokens` to `context_details.input + output` when
         // the backend emits it; on older deployments the wire
-        // value passes through unchanged.
+        // value passes through `unchanged`.
         let usage = response.usage.as_ref().map(|u| TokenUsage {
             prompt_tokens: u.input_tokens,
             completion_tokens: u.output_tokens,
@@ -501,7 +501,8 @@ pub fn stream_responses<'a>(
             cost_usd_ticks,
             message_chunks_emitted: message_chunk_count,
             doom_loop_signals,
-            stop_message: None, // not reported on the Responses API
+            // not reported on the Responses API
+            stop_message: None,
         };
 
         yield SamplingEvent::Completed {
@@ -848,7 +849,7 @@ mod tests {
 
     #[tokio::test]
     async fn function_call_args_delta_without_added_event_is_dropped() {
-        // ArgumentsDelta with no preceding OutputItemAdded has no
+        // ArgumentsDelta with no preceding `OutputItemAdded` has no
         // output_index → tool_index mapping; drop silently.
         let events: Vec<Result<rs::ResponseStreamEvent, SamplingError>> = vec![
             Ok(function_call_args_delta_event(7, "{\"oops\":1}")),