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-shell/src/sampling/conversation.rs

@@ -1,9 +1,6 @@
 //! API-agnostic conversation representation.
 //!
-//! The canonical types now live in `kigi_sampling_types::conversation`.
-//! This module re-exports them.
+//! The canonical types live in `kigi_sampling_types::conversation`; this module
+//! re-exports them.
 
-// Re-export everything from the standalone crate.
 pub use kigi_sampling_types::conversation::*;
-
-// Tests for conversation types now live in kigi-sampling-types crate.

crates/codegen/kigi-shell/src/sampling/error.rs

@@ -1,10 +1,9 @@
 //! Sampling error types.
 //!
-//! The canonical error types now live in `kigi_sampling_types::error`.
-//! This module re-exports them and adds `map_sampling_err_to_acp` which
-//! depends on `agent_client_protocol::Error` (a kigi-shell dependency).
+//! The canonical error types live in `kigi_sampling_types::error`. This module
+//! re-exports them and adds `map_sampling_err_to_acp`, which depends on
+//! `agent_client_protocol::Error` (a kigi-shell dependency).
 
-// Re-export everything from the standalone crate.
 pub use kigi_sampling_types::error::*;
 
 use agent_client_protocol as acp;
@@ -51,7 +50,6 @@ pub fn rate_limited_user_message(is_api_key_auth: bool) -> &'static str {
 }
 
 /// Map a `SamplingError` to an ACP `Error` for client-facing responses.
-/// This stays in kigi-shell because it depends on `agent_client_protocol::Error`.
 pub fn map_sampling_err_to_acp(err: SamplingError) -> acp::Error {
     use reqwest::StatusCode;
     match err {
@@ -339,7 +337,6 @@ mod tests {
         assert!(RATE_LIMITED_USER_MESSAGE_OAUTH.contains("official Kimi CLI"));
         assert!(RATE_LIMITED_USER_MESSAGE_OAUTH.contains("same subscription quota"));
         assert!(RATE_LIMITED_USER_MESSAGE_OAUTH.contains(kigi_env::upgrade_page_url()));
-        // API-key copy points at the Moonshot platform, not the subscription.
         assert!(RATE_LIMITED_USER_MESSAGE_API_KEY.contains("Moonshot"));
         assert!(!RATE_LIMITED_USER_MESSAGE_API_KEY.contains("subscription quota"));
     }
@@ -459,7 +456,6 @@ mod tests {
             }
         }
         let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(f));
-        // Restore original state.
         unsafe {
             std::env::remove_var("KIGI_API_KEY");
             std::env::remove_var("XAI_API_KEY");

crates/codegen/kigi-shell/src/sampling/mod.rs

@@ -2,30 +2,17 @@ pub mod conversation;
 pub mod error;
 pub mod types;
 
-// `Client` is the legacy alias used throughout the shell. A later refactor
-// retired the bespoke shell HTTP client and points `Client` at the sampler crate's
-// `SamplingClient` -- the two have identical method sets, so call-sites
-// compile unchanged.
 pub use self::conversation::*;
 pub use self::error::{ResponseModelMetadata, Result, SamplingError};
 pub use self::types::*;
 pub use kigi_sampler::ApiBackend;
 pub use kigi_sampler::SamplingClient as Client;
 
-// Re-export async-openai Responses API types under `rs` namespace
 pub use async_openai::types::responses as rs;
 
-// ---------------------------------------------------------------------------
-// kigi-sampler re-exports
-// ---------------------------------------------------------------------------
-//
-// The actual streaming / retry / HTTP-client logic lives in the
-// `kigi-sampler` crate. We re-export the public surface here so
-// `crate::sampling::{SamplerHandle, SamplerConfig, ...}` paths keep working
-// for callers that haven't been ported to spell these directly via
-// `kigi_sampler::*`. The shell-side `sampling::client::Config`
-// composite was removed when its only remaining role -- session-snapshot
-// state for `MvpAgent` -- was migrated to `RefCell<SamplerConfig>` directly.
+// The streaming / retry / HTTP-client logic lives in `kigi-sampler`; these
+// re-exports keep `crate::sampling::{SamplerHandle, SamplerConfig, ...}` paths
+// working for callers not yet ported to `kigi_sampler::*` directly.
 pub use kigi_sampler::{
     InferenceLatencyStats, OriginClientInfo, RequestId, SamplerActor, SamplerConfig, SamplerHandle,
     SamplingChannel, SamplingClient, SamplingErrorInfo, SamplingErrorKind, SamplingEvent,

crates/codegen/kigi-shell/src/sampling/types.rs

@@ -1,15 +1,5 @@
-// Re-export all types from the standalone kigi-sampling-types crate.
-// This keeps all existing `crate::sampling::types::*` imports working.
 pub use kigi_sampling_types::types::*;
 
-// `CreateResponseWrapper` and `MessagesRequestWrapper` previously lived
-// here. They were moved into `kigi-sampling-types::types` (and
-// are re-exported above via the wildcard) so the new
-// `kigi-sampler` crate can reference them without a circular
-// dep on `kigi-shell`.
-
-// Tests for the types now live in kigi-sampling-types crate.
-
 use kigi_tools::types::output::ImageContent as ToolsImageContent;
 
 /// Render an `ImageContent` produced by the read-file tool as a URL