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-tui/examples/memory_benchmark.rs

@@ -13,7 +13,6 @@
 use std::sync::Arc;
 use std::time::Instant;
 
-/// Simulate SubagentInfo with String fields (before optimization)
 #[derive(Clone)]
 struct SubagentInfoString {
     subagent_id: String,
@@ -27,7 +26,6 @@ struct SubagentInfoString {
     tools_used: Vec<String>,
 }
 
-/// Simulate SubagentInfo with Arc<str> fields (after optimization)
 #[derive(Clone)]
 struct SubagentInfoArc {
     subagent_id: Arc<str>,
@@ -85,10 +83,10 @@ fn estimate_string_info_size(info: &SubagentInfoString) -> usize {
 fn estimate_arc_info_size(info: &SubagentInfoArc) -> usize {
     // Arc<str> has 16 bytes overhead (fat pointer) but shares the string data
     std::mem::size_of::<SubagentInfoArc>()
-        + 16 // subagent_id Arc overhead
-        + 16 // child_session_id Arc overhead
-        + 16 // description Arc overhead
-        + 16 // subagent_type Arc overhead
+        + 16
+        + 16
+        + 16
+        + 16
         + info.persona.as_ref().map_or(0, |_| 16)
         + info.role.as_ref().map_or(0, |_| 16)
         + info.model.as_ref().map_or(0, |_| 16)
@@ -99,7 +97,6 @@ fn estimate_arc_info_size(info: &SubagentInfoArc) -> usize {
 fn main() {
     println!("=== SubagentInfo Memory Benchmark ===\n");
 
-    // Test 1: Single instance
     println!("--- Single Instance ---");
     let string_info = create_string_info(1);
     let arc_info = create_arc_info(1);
@@ -114,14 +111,11 @@ fn main() {
     );
     println!();
 
-    // Test 2: Many instances with shared strings
     println!("--- 1000 Instances (with string sharing potential) ---");
     let count = 1000;
 
-    // String-based: each instance has its own copy of shared strings
     let string_infos: Vec<SubagentInfoString> = (0..count).map(create_string_info).collect();
 
-    // Arc-based: shared strings are deduplicated
     let arc_infos: Vec<SubagentInfoArc> = (0..count).map(create_arc_info).collect();
 
     let string_total: usize = string_infos.iter().map(estimate_string_info_size).sum();
@@ -145,7 +139,6 @@ fn main() {
     );
     println!();
 
-    // Test 3: Clone performance
     println!("--- Clone Performance (100,000 clones) ---");
     let iterations = 100_000;
 
@@ -169,7 +162,6 @@ fn main() {
     );
     println!();
 
-    // Test 4: Memory with realistic subagent data
     println!("--- Realistic Scenario (100 subagents with varied data) ---");
     let subagent_types = ["general-purpose", "explore", "plan", "implementer"];
     let personas = ["researcher", "analyst", "reviewer", "implementer"];
@@ -240,7 +232,6 @@ fn main() {
     );
     println!();
 
-    // Summary
     println!("=== Summary ===");
     println!("Arc<str> optimization provides:");
     println!("1. Memory savings through string deduplication (shared strings stored once)");

crates/codegen/kigi-tui/examples/memory_benchmark_accurate.rs

@@ -1,7 +1,5 @@
 //! Accurate memory benchmark for SubagentInfo Arc<str> optimization.
 //!
-//! This benchmark uses dhat for heap profiling to accurately measure memory usage.
-//!
 //! Run with: cargo run --release --example memory_benchmark_accurate
 
 // Illustrative mock structs whose fields exist to model memory layout; not all
@@ -11,7 +9,6 @@
 use std::sync::Arc;
 use std::time::Instant;
 
-/// Simulate SubagentInfo with String fields (before optimization)
 #[derive(Clone)]
 struct SubagentInfoString {
     subagent_id: String,
@@ -25,7 +22,6 @@ struct SubagentInfoString {
     tools_used: Vec<String>,
 }
 
-/// Simulate SubagentInfo with Arc<str> fields (after optimization)
 #[derive(Clone)]
 struct SubagentInfoArc {
     subagent_id: Arc<str>,
@@ -83,7 +79,6 @@ fn create_arc_info(
 fn main() {
     println!("=== SubagentInfo Memory Benchmark (Accurate) ===\n");
 
-    // Test 1: Clone performance - the most impactful optimization
     println!("--- Clone Performance (1,000,000 clones) ---");
     let iterations = 1_000_000;
 
@@ -110,7 +105,6 @@ fn main() {
     );
     println!();
 
-    // Test 2: Memory with shared strings (realistic scenario)
     println!("--- Memory with Shared Strings (1000 subagents) ---");
     println!("Scenario: 1000 subagents sharing subagent_type, model, persona, status");
 
@@ -118,7 +112,6 @@ fn main() {
     let shared_models = ["kigi-3", "kigi-3-mini"];
     let shared_personas = ["researcher", "analyst", "reviewer"];
 
-    // Create string-based infos
     let mut string_infos: Vec<SubagentInfoString> = Vec::with_capacity(1000);
     for i in 0..1000 {
         let st = shared_types[i % shared_types.len()];
@@ -127,7 +120,6 @@ fn main() {
         string_infos.push(create_string_info(i, st, m, p));
     }
 
-    // Create Arc-based infos (with string sharing)
     let mut arc_infos: Vec<SubagentInfoArc> = Vec::with_capacity(1000);
     for i in 0..1000 {
         let st = shared_types[i % shared_types.len()];
@@ -136,8 +128,6 @@ fn main() {
         arc_infos.push(create_arc_info(i, st, m, p));
     }
 
-    // Calculate memory
-    // For String: each instance has its own copy
     let string_mem: usize = string_infos
         .iter()
         .map(|info| {
@@ -154,7 +144,6 @@ fn main() {
         .sum();
 
     // For Arc<str>: shared strings are stored once
-    // Count unique strings
     let mut unique_types = std::collections::HashSet::new();
     let mut unique_models = std::collections::HashSet::new();
     let mut unique_personas = std::collections::HashSet::new();
@@ -177,26 +166,30 @@ fn main() {
         }
     }
 
-    // Arc<str> memory: unique strings + Arc overhead per reference
     let shared_string_mem: usize = unique_types.iter().map(|s| s.len()).sum::<usize>()
         + unique_models.iter().map(|s| s.len()).sum::<usize>()
         + unique_personas.iter().map(|s| s.len()).sum::<usize>()
         + unique_statuses.iter().map(|s| s.len()).sum::<usize>()
         + unique_tools.iter().map(|s| s.len()).sum::<usize>();
 
-    // Per-instance memory for unique fields + Arc overhead
     let per_instance_mem: usize = arc_infos
         .iter()
         .map(|info| {
-            info.subagent_id.len() + 16 + // Arc overhead
-        info.child_session_id.len() + 16 +
-        info.description.len() + 16 +
-        16 + // subagent_type Arc (shared)
-        info.persona.as_ref().map_or(0, |_| 16) + // Arc overhead
-        info.role.as_ref().map_or(0, |_| 16) +
-        info.model.as_ref().map_or(0, |_| 16) +
-        info.status.as_ref().map_or(0, |_| 16) +
-        info.tools_used.len() * 16
+            // Unique fields add their bytes plus a 16-byte Arc pointer; shared
+            // fields contribute only the pointer, their bytes counted once in
+            // shared_string_mem.
+            info.subagent_id.len()
+                + 16
+                + info.child_session_id.len()
+                + 16
+                + info.description.len()
+                + 16
+                + 16
+                + info.persona.as_ref().map_or(0, |_| 16)
+                + info.role.as_ref().map_or(0, |_| 16)
+                + info.model.as_ref().map_or(0, |_| 16)
+                + info.status.as_ref().map_or(0, |_| 16)
+                + info.tools_used.len() * 16
         })
         .sum();
 
@@ -222,7 +215,6 @@ fn main() {
     );
     println!();
 
-    // Test 3: HashMap key performance
     println!("--- HashMap Key Performance (100,000 lookups) ---");
     let iterations = 100_000;
 
@@ -256,7 +248,6 @@ fn main() {
     println!("Arc<str> key lookup time: {:?}", arc_lookup_time);
     println!();
 
-    // Summary
     println!("=== Summary ===");
     println!("Arc<str> optimization provides:");
     println!(

crates/codegen/kigi-tui/examples/real_session_benchmark.rs

@@ -12,7 +12,6 @@
 use std::sync::Arc;
 use std::time::Instant;
 
-/// Simulate SubagentInfo with String fields (before optimization)
 #[derive(Clone, Debug)]
 struct SubagentInfoString {
     subagent_id: String,
@@ -26,7 +25,6 @@ struct SubagentInfoString {
     tools_used: Vec<String>,
 }
 
-/// Simulate SubagentInfo with Arc<str> fields (after optimization)
 #[derive(Clone, Debug)]
 struct SubagentInfoArc {
     subagent_id: Arc<str>,
@@ -40,7 +38,6 @@ struct SubagentInfoArc {
     tools_used: Vec<Arc<str>>,
 }
 
-/// Parsed SubagentSpawned event from updates.jsonl
 #[derive(Debug)]
 struct SubagentSpawnedEvent {
     subagent_id: String,
@@ -53,10 +50,8 @@ struct SubagentSpawnedEvent {
 }
 
 fn parse_subagent_spawned(line: &str) -> Option<SubagentSpawnedEvent> {
-    // Parse JSON line looking for SubagentSpawned events
     let value: serde_json::Value = serde_json::from_str(line).ok()?;
 
-    // Check if this is a SubagentSpawned event
     // Format: {"params": {"update": {"sessionUpdate": "subagent_spawned", ...}}}
     let update = value.get("params")?.get("update")?;
     if update.get("sessionUpdate")?.as_str()? != "subagent_spawned" {
@@ -126,13 +121,13 @@ fn estimate_string_size(info: &SubagentInfoString) -> usize {
 fn estimate_arc_size(info: &SubagentInfoArc) -> usize {
     // Arc<str> overhead is 16 bytes (fat pointer) per field
     // But shared strings are stored once
-    16 * 4 + // subagent_id, child_session_id, description, subagent_type
+    16 * 4 +
     info.persona.as_ref().map_or(0, |_| 16) +
     info.role.as_ref().map_or(0, |_| 16) +
     info.model.as_ref().map_or(0, |_| 16) +
     info.status.as_ref().map_or(0, |_| 16) +
     info.tools_used.len() * 16 +
-    // Add actual string lengths (shared, so counted once per unique string)
+    // Byte lengths for the per-instance unique fields only; shared fields' bytes are not counted per instance.
     info.subagent_id.len() +
     info.child_session_id.len() +
     info.description.len()
@@ -167,7 +162,6 @@ fn main() {
     println!("File size: {:.1} MB", file_size as f64 / 1_000_000.0);
     println!();
 
-    // Parse SubagentSpawned events
     println!("--- Parsing SubagentSpawned events ---");
     let start = Instant::now();
 
@@ -192,11 +186,9 @@ fn main() {
         println!("No SubagentSpawned events found in this session.");
         println!("Trying to find any session with subagents...");
 
-        // Try a different approach - look for any session with subagents
         return;
     }
 
-    // Show sample events
     println!("--- Sample SubagentSpawned events ---");
     for (i, event) in events.iter().take(5).enumerate() {
         println!(
@@ -209,14 +201,12 @@ fn main() {
     }
     println!();
 
-    // Create SubagentInfo instances
     println!("--- Creating SubagentInfo instances ---");
 
     let string_infos: Vec<SubagentInfoString> = events.iter().map(create_string_info).collect();
 
     let arc_infos: Vec<SubagentInfoArc> = events.iter().map(create_arc_info).collect();
 
-    // Calculate memory
     let string_mem: usize = string_infos.iter().map(estimate_string_size).sum();
     let arc_mem: usize = arc_infos.iter().map(estimate_arc_size).sum();
 
@@ -243,7 +233,6 @@ fn main() {
     }
     println!();
 
-    // Analyze string sharing
     println!("--- String Sharing Analysis ---");
     let mut unique_types = std::collections::HashSet::new();
     let mut unique_models = std::collections::HashSet::new();
@@ -271,7 +260,6 @@ fn main() {
     println!("  Personas: {:?}", unique_personas);
     println!();
 
-    // Clone performance
     println!("--- Clone Performance (100,000 clones) ---");
     let iterations = 100_000;
 
@@ -299,7 +287,6 @@ fn main() {
     }
     println!();
 
-    // Summary
     println!("=== Summary ===");
     println!(
         "Session: {:?}",