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-config-types/src/flags.rs

@@ -1,5 +1,8 @@
-//! Config-value resolution leaf types and per-model laziness config,
-//! extracted from kigi-shell for dependency inversion.
+//! Config-value resolution leaf types and per-model laziness config.
+//!
+//! They live outside kigi-shell so crates below it (kigi-memory,
+//! kigi-shared, kigi-workspace) can share them without depending on the
+//! shell.
 
 use kigi_config::env_bool;
 
@@ -18,7 +21,6 @@ pub enum ConfigSource {
     Default,
 }
 
-/// A resolved config value with its source for diagnostics.
 #[derive(Debug, Clone)]
 pub struct Resolved<T> {
     pub value: T,
@@ -156,9 +158,8 @@ pub struct LazinessDetectorPerModelConfig {
     pub min_confidence: Option<f32>,
     /// When `Some(true)` (or `None` — the default), the classifier sees
     /// the assistant's plain-text reasoning as `[assistant reasoning]`
-    /// lines. `Some(false)` drops them (the pre-2026-05 behavior).
-    /// `None` defers to the harness default (`LAZINESS_INCLUDE_REASONING`,
-    /// currently `true`).
+    /// lines; `Some(false)` drops them. `None` defers to the harness
+    /// default (`LAZINESS_INCLUDE_REASONING`, currently `true`).
     #[serde(default)]
     pub include_reasoning: Option<bool>,
 }

crates/codegen/kigi-config-types/src/mcp.rs

@@ -1,5 +1,4 @@
-//! MCP server configuration value types, extracted from kigi-shell
-//! (config dependency inversion).
+//! MCP server configuration value types.
 
 use agent_client_protocol as acp;
 use indexmap::IndexMap;
@@ -8,14 +7,10 @@ use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::path::PathBuf;
 
-/// serde default helper. Kept module-local rather than shared — the `pool`
-/// module keeps its own copy for `PoolConfig`.
 fn default_true() -> bool {
     true
 }
 
-/// Read an MCP OAuth client secret from the named env var. Moved here with
-/// `McpServerConfig` (its only caller).
 fn resolve_oauth_client_secret(env_var: Option<&String>) -> Option<String> {
     let env_var = env_var?;
     match std::env::var(env_var) {
@@ -56,10 +51,8 @@ pub enum McpServerTransportConfig {
         /// OAuth client ID for providers that don't support Dynamic Client Registration.
         #[serde(default, skip_serializing_if = "Option::is_none")]
         oauth_client_id: Option<String>,
-        /// Name of the env var holding the OAuth client secret (for BYO credentials).
         #[serde(default, skip_serializing_if = "Option::is_none")]
         oauth_client_secret_env_var: Option<String>,
-        /// OAuth scopes to request during authorization.
         #[serde(default, skip_serializing_if = "Option::is_none")]
         oauth_scopes: Option<Vec<String>>,
     },
@@ -176,7 +169,6 @@ impl McpServerConfig {
                     })
                     .unwrap_or_default();
 
-                // Add bearer token from environment variable if specified
                 if let Some(env_var) = bearer_token_env_var {
                     match std::env::var(env_var) {
                         Ok(token) => {
@@ -213,7 +205,7 @@ impl McpServerConfig {
         }
     }
 
-    /// Extract OAuth configuration for this server, if any OAuth fields are set.
+    /// Inline `oauth_*` transport fields take precedence over the `oauth` block.
     pub fn oauth_config(&self) -> Option<McpOAuthConfig> {
         if let McpServerTransportConfig::StreamableHttp {
             oauth_client_id,
@@ -260,7 +252,7 @@ pub struct RelaySyncConfig {
 }
 
 impl RelaySyncConfig {
-    /// Check if relay sync is enabled. Env var takes precedence over config.
+    /// `KIGI_RELAY_SYNC_ENABLED` overrides the configured value.
     pub fn is_enabled(&self) -> bool {
         if let Ok(env_val) = std::env::var("KIGI_RELAY_SYNC_ENABLED") {
             return env_val.eq_ignore_ascii_case("true") || env_val == "1";

crates/codegen/kigi-config-types/src/memory.rs

@@ -450,7 +450,8 @@ mod tests {
     fn effective_half_life_converts_legacy_recency_decay() {
         let mut s = MemorySearchConfig::default();
         s.temporal_decay.enabled = false;
-        s.recency_decay = 0.5; // non-default → converted
+        // non-default → converted
+        s.recency_decay = 0.5;
         let hl = s.effective_half_life_days().unwrap();
         assert!(
             (hl - 1.0).abs() < 1e-9,

crates/codegen/kigi-config-types/src/permission.rs

@@ -32,7 +32,7 @@ pub enum PatternMode {
 
 /// Action to take when rule matches.
 ///
-/// CWE-1188: Default changed from Allow to Deny so that omitting the
+/// CWE-1188: the default is Deny rather than Allow, so that omitting the
 /// `action` field in a TOML permission rule does not silently create a
 /// catch-all allow rule.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]

crates/codegen/kigi-config-types/src/pool.rs

@@ -1,5 +1,4 @@
-//! Worktree-pool configuration value type, extracted from kigi-shell
-//! (config dependency inversion).
+//! Worktree-pool configuration value type.
 
 use serde::{Deserialize, Serialize};
 
@@ -18,27 +17,23 @@ use serde::{Deserialize, Serialize};
 /// ```
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct PoolConfig {
-    /// Whether the pool is enabled at all.
-    /// Can be set to false to disable pooling regardless of repo size.
-    /// Default: true (auto-detect based on file_count_threshold)
+    /// When false, pooling is off regardless of repo size; otherwise
+    /// `file_count_threshold` decides.
     #[serde(default = "default_true")]
     pub enabled: bool,
 
-    /// Number of worktrees to keep ready in the pool.
-    /// 2 is the minimum useful value when forks need parallel worktrees.
-    /// Default: 2
+    /// Number of worktrees to keep ready. 2 is the minimum useful value when
+    /// forks need parallel worktrees.
     #[serde(default = "default_pool_size")]
     pub pool_size: usize,
 
-    /// Minimum number of tracked files for the pool to activate.
-    /// Below this threshold, on-demand creation is fast enough.
-    /// Default: 50_000
+    /// Minimum number of tracked files for the pool to activate. Below this,
+    /// on-demand creation is fast enough.
     #[serde(default = "default_file_count_threshold")]
     pub file_count_threshold: usize,
 
-    /// Number of threads to use for worktree creation when populating the pool.
-    /// This can speed up pool population on large repos, but also increases resource usage.
-    /// Default: 3.
+    /// Threads used to populate the pool. Higher values speed up population on
+    /// large repos at the cost of more concurrent resource use.
     #[serde(default = "default_pool_parallelism")]
     pub parallelism: usize,
 }