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-file-utils/src/events/log.rs

@@ -54,7 +54,8 @@ impl EventWriter {
         Self {
             inner: Arc::new(EventWriterInner {
                 file: Mutex::new(None),
-                error_logged: AtomicBool::new(true), // suppress error logging
+                // suppress error logging
+                error_logged: AtomicBool::new(true),
             }),
         }
     }

crates/codegen/kigi-file-utils/src/events/tracker.rs

@@ -169,7 +169,7 @@ impl EventTracker {
         self.pending_interrupt_reminder.replace(false)
     }
 
-    /// Emit PhaseChanged(PermissionPrompt) → PermissionRequested.
+    /// Emit `PhaseChanged`(PermissionPrompt) → PermissionRequested.
     /// Returns the Instant for `permission_resolved()` to compute wait_ms.
     pub fn permission_requested(&self, tool_name: &str) -> Instant {
         self.emit(Event::PhaseChanged {

crates/codegen/kigi-file-utils/src/events/types.rs

@@ -339,7 +339,7 @@ pub enum Event {
         pattern: &'static str,
     },
 
-    // ── MCP Diagnostics ──────────────────────────────────────────
+    // MCP Diagnostics
     McpConfigResolved {
         servers: Vec<McpConfigServer>,
         disabled: Vec<String>,

crates/codegen/kigi-file-utils/src/lib.rs

@@ -41,7 +41,6 @@ pub const SKIP_DIR_NAMES: &[&str] = &[
     ".ruff_cache",
 ];
 
-/// [`SKIP_DIR_NAMES`] as a set for O(1) membership checks.
 pub fn skip_dir_set() -> &'static std::collections::HashSet<&'static str> {
     use std::collections::HashSet;
     use std::sync::LazyLock;
@@ -50,15 +49,14 @@ pub fn skip_dir_set() -> &'static std::collections::HashSet<&'static str> {
     &SET
 }
 
-/// Compute SHA256 hash of content as a hex string.
 pub fn sha256_hex(content: &[u8]) -> String {
     use sha2::{Digest, Sha256};
     let mut hasher = Sha256::new();
     hasher.update(content);
     format!("{:x}", hasher.finalize())
 }
-/// Compute SHA256 hash of a file by streaming, without loading entire file into memory.
-/// If `max_bytes` is set (> 0), only hash up to that many bytes.
+/// Streams the file instead of loading it into memory; `max_bytes` caps how
+/// much of it is hashed.
 pub fn sha256_hex_from_file(
     path: &std::path::Path,
     max_bytes: Option<u64>,

crates/codegen/kigi-file-utils/src/s3.rs

@@ -124,7 +124,7 @@ pub(crate) async fn build_s3_client(
 
 /// Static access-key credentials for presigning S3 URLs.
 ///
-/// `Debug` is intentionally redacted — the struct holds plaintext secrets.
+/// `Debug` is deliberately redacted — the struct holds plaintext secrets.
 #[derive(Clone)]
 pub struct S3StaticCredentials {
     pub access_key_id: String,

crates/codegen/kigi-file-utils/src/trace_context.rs

@@ -247,7 +247,8 @@ mod tests {
             trace_id,
             span_id,
             TraceFlags::SAMPLED,
-            true, // is_remote
+            // is_remote
+            true,
             TraceState::default(),
         );
 

crates/codegen/kigi-file-utils/src/workspace_classifier.rs

@@ -25,6 +25,8 @@ pub fn is_project_dir(cwd: &Path) -> bool {
         return false;
     }
 
+    // A repo checked out anywhere counts as a project, even under a system or
+    // excluded directory, so this check deliberately precedes the exclusions.
     if cwd.ancestors().any(|p| p.join(".git").exists()) {
         return true;
     }