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/session/helpers/memory_context.rs

@@ -186,10 +186,6 @@ mod tests {
         assert!(output.contains("score: 0.70"));
     }
 
-    // -----------------------------------------------------------------------
-    // conversation_has_memory_context (idempotency guard) tests
-    // -----------------------------------------------------------------------
-
     fn sample_result() -> MemorySearchResult {
         MemorySearchResult {
             chunk_id: "test:0".into(),
@@ -237,10 +233,6 @@ mod tests {
         assert!(!conversation_has_memory_context(&[]));
     }
 
-    // -----------------------------------------------------------------------
-    // staleness annotation tests
-    // -----------------------------------------------------------------------
-
     #[test]
     fn test_staleness_shown_for_old_session_result() {
         let now = std::time::SystemTime::now()
@@ -287,10 +279,6 @@ mod tests {
         );
     }
 
-    // -----------------------------------------------------------------------
-    // is_greeting tests
-    // -----------------------------------------------------------------------
-
     #[test]
     fn test_greeting_detection() {
         assert!(is_greeting("hi"));
@@ -309,10 +297,6 @@ mod tests {
         assert!(!is_greeting("hi there, can you help me with something"));
     }
 
-    // -----------------------------------------------------------------------
-    // Injection counter semantics tests
-    // -----------------------------------------------------------------------
-
     /// `format_memory_reminder` returns `None` for an empty result list.
     ///
     /// This is the key invariant for the `memory_injection_count` contract:

crates/codegen/kigi-shell/src/session/helpers/memory_flush.rs

@@ -76,10 +76,6 @@ pub fn should_flush(
     should
 }
 
-// ---------------------------------------------------------------------------
-// Flush prompt and response processing
-// ---------------------------------------------------------------------------
-
 /// System prompt injected for the flush model call.
 pub const FLUSH_SYSTEM_PROMPT: &str = "\
 You are a memory assistant. Extract ALL useful information from this conversation \
@@ -154,21 +150,19 @@ pub fn process_flush_response(response: &str, config: &MemoryFlushConfig) -> Flu
     tracing::info!(target: LOG,
         "MEMORY_FLUSH_RESPONSE: len={len} preview=\"{preview}\"");
 
-    // Check for empty
     if trimmed.is_empty() {
         tracing::info!(target: LOG,
             "MEMORY_FLUSH_RESPONSE: empty → NothingToStore");
         return FlushResult::NothingToStore;
     }
 
-    // Check for NO_REPLY
     if is_no_reply(trimmed) {
         tracing::info!(target: LOG,
             "MEMORY_FLUSH_RESPONSE: matches NO_REPLY pattern → NothingToStore");
         return FlushResult::NothingToStore;
     }
 
-    // Truncate if too long (use char count for consistency with .chars().take())
+    // Char count keeps this consistent with the `.chars().take()` below.
     let content = if trimmed.chars().count() > config.max_flush_write_chars {
         tracing::warn!(target: LOG,
             "MEMORY_FLUSH_RESPONSE: truncated from {len} to {} chars",
@@ -181,7 +175,6 @@ pub fn process_flush_response(response: &str, config: &MemoryFlushConfig) -> Flu
         trimmed.to_string()
     };
 
-    // Must contain at least one markdown header for structure
     if !has_markdown_headers(&content) {
         tracing::info!(target: LOG,
             "MEMORY_FLUSH_RESPONSE: no markdown headers → Rejected");
@@ -442,10 +435,6 @@ mod tests {
         assert!(!should_flush(82_000, 100_000, 85, &config, 5, 5));
     }
 
-    // -----------------------------------------------------------------------
-    // process_flush_response tests
-    // -----------------------------------------------------------------------
-
     #[test]
     fn test_flush_response_empty() {
         let config = default_flush_config();
@@ -604,10 +593,6 @@ mod tests {
         assert_eq!(window[0].role, Role::User);
     }
 
-    // -----------------------------------------------------------------------
-    // is_semantically_duplicate tests
-    // -----------------------------------------------------------------------
-
     #[tokio::test]
     async fn test_semantic_dedup_no_provider_allows_write() {
         use crate::session::memory::{MemoryIndex, MemoryStorage, index::init_sqlite_vec};

crates/codegen/kigi-shell/src/session/helpers/prompt_suggest.rs

@@ -317,8 +317,6 @@ mod tests {
     use super::*;
     use crate::config::PromptSuggestModelPin as Pin;
 
-    // -- effective_suggest_model ---------------------------------------------
-
     #[test]
     fn effective_model_default_requires_catalog() {
         // No pin, no hint: the built-in default fires only when this shell's
@@ -385,8 +383,6 @@ mod tests {
         );
     }
 
-    // -- sanitize_suggestion ------------------------------------------------
-
     #[test]
     fn sanitize_accepts_short_imperative() {
         assert_eq!(
@@ -474,8 +470,6 @@ mod tests {
         );
     }
 
-    // -- build_transcript ---------------------------------------------------
-
     fn user(text: &str) -> ConversationItem {
         ConversationItem::user(text.to_owned())
     }
@@ -484,8 +478,6 @@ mod tests {
         ConversationItem::assistant(text.to_owned())
     }
 
-    // -- is_repeat_of_user_message -------------------------------------------
-
     #[test]
     fn repeat_filter_rejects_verbatim_past_prompt() {
         let conv = vec![user("fix the flaky auth test"), assistant("Fixed it")];

crates/codegen/kigi-shell/src/session/helpers/replay.rs

@@ -181,7 +181,6 @@ struct ReplayState {
     /// The prompt index we're trying to reach.
     target: usize,
 
-    /// Accumulated conversation items.
     conversation: Vec<ConversationItem>,
 
     /// Current prompt counter (how many user turns we've seen).
@@ -203,7 +202,6 @@ struct ReplayState {
     /// Partial text accumulator for the current agent message.
     current_agent_text: String,
 
-    /// Whether there's a pending agent message to flush.
     has_pending_agent: bool,
 
     /// When set, the replay is operating "after" a loaded checkpoint.
@@ -403,7 +401,6 @@ impl ReplayState {
                 self.original_user_info = file.original_user_info.clone();
             }
 
-            // Replace accumulated conversation with the compacted history.
             self.conversation = file.compacted_history;
             // Checkpoints predate this binary's validation (or the API's
             // current validators), so heal them like the jsonl loader does
@@ -434,7 +431,6 @@ impl ReplayState {
                 "Replay: loaded compaction checkpoint"
             );
 
-            // If the auto-continue prompt was recorded, add it as a user turn.
             if let Some(ref ac) = info.auto_continue {
                 self.conversation
                     .push(ConversationItem::user(ac.prompt_text.clone()));
@@ -831,7 +827,8 @@ mod tests {
             make_agent_update("s1", "R1"),
             make_user_update("s1", "P2"),
             make_agent_update("s1", "R2"),
-            make_rewind_marker(1), // keep P0 only
+            // keep P0 only
+            make_rewind_marker(1),
             make_user_update("s1", "P1_prime"),
             make_agent_update("s1", "R1_prime"),
         ];

crates/codegen/kigi-shell/src/session/helpers/session_recap.rs

@@ -272,7 +272,7 @@ pub(crate) fn clean_recap_text(raw: &str) -> String {
         let cut = floor_char_boundary(&out, RECAP_MAX_CHARS);
         out.truncate(cut);
         out = out.trim_end().to_string();
-        out.push('\u{2026}'); // …
+        out.push('\u{2026}');
     }
 
     out
@@ -522,8 +522,6 @@ mod tests {
         );
     }
 
-    // ---- budget_recap_items ------------------------------------------------
-
     /// Recompute the prompt budget the helper uses, for end-state assertions.
     fn recap_prompt_budget(context_window: u64) -> u64 {
         (context_window.min(RECAP_CONTEXT_WINDOW_CAP) * RECAP_BUDGET_THRESHOLD_PERCENT / 100)
@@ -588,7 +586,8 @@ mod tests {
             ConversationItem::system("sys"),
             ConversationItem::user("q1"),
             ConversationItem::assistant("a1"),
-            ConversationItem::user("d".repeat(40_000)), // ~10k est tokens
+            // ~10k est tokens
+            ConversationItem::user("d".repeat(40_000)),
             ConversationItem::assistant("a2"),
             ConversationItem::user("recent q"),
         ];
@@ -637,10 +636,13 @@ mod tests {
         // the recent user turn is what survives the front-trim.
         let conv = vec![
             ConversationItem::system("sys"),
-            ConversationItem::user("c".repeat(40_000)), // oldest real user, dropped
-            ConversationItem::user("what changed in the parser?"), // most-recent real user
+            // oldest real user, dropped
+            ConversationItem::user("c".repeat(40_000)),
+            // most-recent real user turn
+            ConversationItem::user("what changed in the parser?"),
             ConversationItem::assistant_tool_calls(vec![mk_tool_call("c9", "{}")]),
-            ConversationItem::tool_result("c9", "t".repeat(40_000)), // trailing run, > budget
+            // trailing run, > budget
+            ConversationItem::tool_result("c9", "t".repeat(40_000)),
         ];
         let out = budget_recap_items(conv, "system-reminder", false, 8_000);
 

crates/codegen/kigi-shell/src/session/helpers/session_summary.rs

@@ -66,10 +66,8 @@ pub(crate) fn title_fallback_from_user_text(user_message: &str) -> String {
     }
 }
 
-/// Generates a title for the session by looking at the first user message
-/// We do not generate more of it on next user message unless its very important
-///
-/// Ideally we should be updating it as the session continues, but ... skipping that for now
+/// Generates a title for the session from the first user message only; the
+/// title is not regenerated as the session continues.
 pub async fn generate_session_summary(
     user_message: String,
     client: OaiCompatClient,

crates/codegen/kigi-shell/src/session/helpers/tool_input_parsing.rs

@@ -1,7 +1,6 @@
 pub fn try_extract_concatenated_json_objects(arguments: &str) -> Option<Vec<serde_json::Value>> {
     let trimmed = arguments.trim();
 
-    // Quick check: must start with '{'.
     if !trimmed.starts_with('{') {
         return None;
     }