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/src/campaigns.rs

@@ -59,7 +59,6 @@ pub fn build_campaign_entries(
             tracing::warn!(layer, "campaigns: entry missing id; skipped");
             continue;
         };
-        // Skip no-op entries (id only, no fields to overlay).
         if entry.patch.is_empty() {
             continue;
         }
@@ -180,8 +179,8 @@ mod tests {
 
     #[test]
     fn apply_highest_priority_wins_on_leaf_conflict() {
-        // Two *distinct* ids both set models.default; the higher-priority source
-        // (earlier in the merged list) must win the leaf.
+        // Two *distinct* ids both set models.default, so dedup by id does not
+        // apply and the leaf conflict is settled by apply order alone.
         let req = [CampaignEntry {
             id: "req".into(),
             patch: models_default_patch("from-req"),
@@ -200,8 +199,6 @@ mod tests {
 
     #[test]
     fn build_campaign_entries_skips_missing_id() {
-        // A `None` id and a whitespace-only id are both dropped (with a warn);
-        // only the entry carrying a real id survives.
         let taken = vec![
             ConfigOverrideEntry {
                 meta: CampaignMeta { id: None },
@@ -236,9 +233,8 @@ mod tests {
             let entries = take_campaign_entries(&mut layer, "user");
             assert_eq!(entries.len(), 1);
             assert_eq!(entries[0].id, "c1");
-            // The id key (either spelling) must be consumed by the meta, never
-            // land in the patch — a leaked key would deep-merge a junk top-level
-            // `id` into every effective config.
+            // A leaked id key would deep-merge a junk top-level `id` into every
+            // effective config.
             assert!(
                 entries[0].patch.get("id").is_none()
                     && entries[0].patch.get("campaign_id").is_none(),
@@ -273,7 +269,6 @@ mod tests {
     #[test]
     fn effective_config_honors_dismiss() {
         use crate::loader::ConfigLayers;
-        // A dismissed campaign id stops overriding; the user's stored value returns.
         let mut layers = ConfigLayers {
             user: parse("[models]\ndefault = \"user-old\"\n"),
             ..Default::default()

crates/codegen/kigi-config/src/lib.rs

@@ -25,8 +25,6 @@ pub mod signed_policy;
 mod validation;
 pub mod version_overrides;
 
-// Only the cross-crate campaign surface is re-exported at the root; the rest stays
-// reachable via the `pub mod` paths for in-crate use without widening the API.
 pub use campaigns::{
     CampaignEntry, CampaignOverrides, filter_active_campaigns, ids_touching_paths,
 };

crates/codegen/kigi-config/src/loader.rs

@@ -84,7 +84,6 @@ pub fn load_from_disk() -> std::io::Result<toml::Value> {
     load_user_config_layer(user_kigi_home().as_deref(), "config.toml")
 }
 
-/// Managed config filename, shared by the loaders in this module.
 pub const MANAGED_CONFIG_FILENAME: &str = "managed_config.toml";
 
 pub fn load_managed_config() -> std::io::Result<toml::Value> {
@@ -111,7 +110,6 @@ pub fn load_system_managed_config() -> std::io::Result<toml::Value> {
     Ok(v)
 }
 
-/// One managed-config layer: the parsed TOML and the file it came from.
 #[derive(Debug, Clone)]
 pub struct ManagedConfigLayer {
     pub value: toml::Value,
@@ -377,7 +375,6 @@ pub struct CampaignsState {
     pub dismissed_ids: Vec<String>,
 }
 
-/// Path to `$KIGI_SHARE_DIR/campaigns_state.json` under `home`.
 pub fn campaigns_state_path(home: &std::path::Path) -> std::path::PathBuf {
     home.join(CAMPAIGNS_STATE_FILE)
 }

crates/codegen/kigi-config/src/macos_managed.rs

@@ -1,6 +1,6 @@
 //! macOS MDM managed-preferences layer.
 //!
-//! Admins push a device profile with standard-base64 (padded) TOML under
+//! Admins push a device profile with standard-base64 (`padded`) TOML under
 //! preference domain `ai.x.kigi` (`requirements_toml_base64`). Only admin-*forced*
 //! values are read, so a local user can't forge it via their own preference
 //! domain; trusted on every launch, independent of network/cache. `None` off macOS.

crates/codegen/kigi-config/src/managed_cache.rs

@@ -425,7 +425,8 @@ fn managed_config_stale_at(home: Option<&Path>, identity: &ServingIdentity) -> b
         return false;
     };
     let Some(cache) = read_managed_config_cache(home) else {
-        return true; // no marker → never synced → stale
+        // no marker → never synced → stale
+        return true;
     };
     if cache_unusable_for(&cache, home, identity) {
         return true;

crates/codegen/kigi-config/src/managed_cache/tests.rs

@@ -65,7 +65,8 @@ fn signed_verdict_does_not_skip_deploy_key_fingerprint() {
     // opted-in cache.
     assert!(managed_policy_compromised_decision(
         SignedVerdict::Trusted,
-        true, // deploy-key fingerprint mismatch
+        // deploy-key fingerprint mismatch
+        true,
         Some(&opted_in),
         home,
         &dkey("fp-local")

crates/codegen/kigi-config/src/paths.rs

@@ -146,9 +146,6 @@ pub fn decode_cwd_from_dirname(dir: &std::path::Path) -> Option<String> {
         .map(|s| s.trim().to_string())
 }
 
-/// Build the CWD-level session directory path:
-/// `kigi_home()/sessions/{encode_cwd_dirname(cwd)}`.
-///
 /// Does **not** create the directory on disk — use [`ensure_sessions_cwd_dir`]
 /// when the directory must exist.
 pub fn sessions_cwd_dir(cwd: &str) -> PathBuf {
@@ -181,10 +178,8 @@ pub fn ensure_sessions_cwd_dir(cwd: &str) -> std::io::Result<PathBuf> {
     Ok(dir)
 }
 
-/// Generate a URL-safe slug from a string.
-///
-/// Lowercases, replaces non-alphanumeric chars with `-`, collapses
-/// consecutive dashes, and truncates to `max_len` characters.
+/// Output is ASCII-only, so `max_len` bounds the result in bytes as well as
+/// chars — [`encode_cwd_dirname`] relies on that for its length guarantee.
 fn slugify(input: &str, max_len: usize) -> String {
     let mut result = String::with_capacity(input.len());
     let mut prev_dash = false;

crates/codegen/kigi-config/src/shell.rs

@@ -342,9 +342,7 @@ fn invocation_for(shell: &WindowsShell, command: &str) -> ShellInvocation {
     }
 }
 
-// =============================================================================
 // Unix shell resolution
-// =============================================================================
 //
 // Locates an absolute path to a bash/zsh binary on Unix:
 //

crates/codegen/kigi-config/src/signed_policy/tests.rs

@@ -650,7 +650,8 @@ fn signed_cache_compromised_respects_signed_opt_out() {
     let dir = tempfile::tempdir().unwrap();
     let home = dir.path();
     let (kp, pubkey) = test_keypair();
-    let p = payload(); // fail_closed = false
+    // fail_closed = false
+    let p = payload();
     write_policy(home, &p);
     write_sidecar(home, &sign(&kp, &p)).unwrap();
 

crates/codegen/kigi-config/src/validation.rs

@@ -58,7 +58,6 @@ impl RequirementsSource {
     }
 }
 
-/// One requirements layer: the parsed TOML and where it came from.
 #[derive(Debug, Clone)]
 pub struct RequirementsLayer {
     pub value: toml::Value,
@@ -171,7 +170,6 @@ pub(crate) fn mdm_requirements_value() -> Option<toml::Value> {
     )
 }
 
-/// Errors from validating requirements layers at startup.
 #[derive(Debug, thiserror::Error)]
 pub enum RequirementsError {
     #[error(

crates/codegen/kigi-config/src/version_overrides.rs

@@ -143,14 +143,20 @@ mod tests {
             );
             cfg["x"].as_integer() == Some(1)
         }
-        assert!(applies(Some("1.7.0"), None, "1.7.0")); // min inclusive
-        assert!(applies(Some("1.0.0"), Some("1.7.0"), "1.7.0")); // max inclusive
-        assert!(!applies(Some("1.7.0"), None, "1.6.0")); // below min
-        assert!(!applies(Some("1.0.0"), Some("1.5.0"), "2.0.0")); // above max
-        assert!(applies(Some("1.7.0"), None, "99.0.0")); // unbounded above
-        assert!(applies(None, Some("2.0.0"), "1.5.0")); // max-only, within
-        assert!(!applies(None, Some("2.0.0"), "2.0.1")); // max-only, above
-        assert!(applies(None, None, "1.0.0")); // unbounded both = always
+        // min inclusive
+        assert!(applies(Some("1.7.0"), None, "1.7.0"));
+        // max inclusive
+        assert!(applies(Some("1.0.0"), Some("1.7.0"), "1.7.0"));
+        assert!(!applies(Some("1.7.0"), None, "1.6.0"));
+        assert!(!applies(Some("1.0.0"), Some("1.5.0"), "2.0.0"));
+        // unbounded above
+        assert!(applies(Some("1.7.0"), None, "99.0.0"));
+        // max-only, within
+        assert!(applies(None, Some("2.0.0"), "1.5.0"));
+        // max-only, above
+        assert!(!applies(None, Some("2.0.0"), "2.0.1"));
+        // unbounded both = always
+        assert!(applies(None, None, "1.0.0"));
     }
 
     #[test]