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-codebase-graph/src/scope_graph/edges.rs

@@ -2,21 +2,21 @@
 
 use serde::{Deserialize, Serialize};
 
-/// Describes the relation between two nodes in the ScopeGraph.
+/// Edge weight in the ScopeGraph. Every variant is directed source-to-target,
+/// in the order its name reads.
 #[derive(Serialize, Deserialize, PartialEq, Eq, Copy, Clone, Debug)]
 pub enum EdgeKind {
-    /// The edge weight from a nested scope to its parent scope.
+    /// Nested scope to its parent scope.
     ScopeToScope,
 
-    /// The edge weight from a definition to its definition scope.
+    /// Definition to the scope that owns it, which for a hoisted def is the
+    /// parent of the scope it was written in.
     DefToScope,
 
-    /// The edge weight from an import to its definition scope.
+    /// Import to its defining scope.
     ImportToScope,
 
-    /// The edge weight from a reference to its definition.
     RefToDef,
 
-    /// The edge weight from a reference to its import.
     RefToImport,
 }

crates/codegen/kigi-codebase-graph/src/scope_graph/graph.rs

@@ -44,7 +44,7 @@ pub type ExtractedSymbols = (
 /// even if file contents haven't changed.
 #[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
 pub enum QueryVersion {
-    /// Legacy format - index was built before query versioning was added.
+    /// Legacy format - index was built without query versioning.
     /// This triggers a rebuild since we don't know what queries were used.
     /// Default for backwards compatibility with old cached indexes.
     #[default]
@@ -394,7 +394,6 @@ impl ScopeGraph {
         })
     }
 
-    /// Find all references to a given name
     pub fn find_references(&self, name: &str, src: &[u8]) -> Vec<Range> {
         self.graph
             .node_indices()
@@ -703,9 +702,7 @@ impl ScopeGraphIndex {
         }
     }
 
-    // ========================================================================
     // String interning helpers
-    // ========================================================================
 
     /// Intern a string and return its ID.
     #[inline]
@@ -725,9 +722,7 @@ impl ScopeGraphIndex {
         self.interner.get_id(s)
     }
 
-    // ========================================================================
     // File metadata operations
-    // ========================================================================
 
     /// Update file metadata (size and mtime) for staleness tracking.
     pub fn update_file_meta(&mut self, path: &Path) {
@@ -751,9 +746,7 @@ impl ScopeGraphIndex {
         }
     }
 
-    // ========================================================================
     // Alias operations
-    // ========================================================================
 
     /// Register an alias relationship: alias_name is an alias for original_name
     pub fn add_alias(&mut self, alias_name: &str, original_name: &str) {
@@ -771,9 +764,7 @@ impl ScopeGraphIndex {
         self.add_alias(&alias_name, &original_name);
     }
 
-    // ========================================================================
     // Symbol insertion (for builder/manager use)
-    // ========================================================================
 
     /// Add a definition occurrence for a symbol.
     pub fn add_definition(&mut self, symbol: &str, path: &str, line: usize) {
@@ -847,9 +838,7 @@ impl ScopeGraphIndex {
             .filter_map(|(&id, meta)| self.get_str(id).map(|path| (path, meta)))
     }
 
-    // ========================================================================
     // File operations
-    // ========================================================================
 
     /// Add a file's scope graph to the index
     pub fn add_file(&mut self, file_path: PathBuf, graph: ScopeGraph, src: &[u8]) {
@@ -996,9 +985,7 @@ impl ScopeGraphIndex {
         self.file_meta.len()
     }
 
-    // ========================================================================
     // Query operations
-    // ========================================================================
 
     /// Find where a symbol is defined (includes resolving aliases)
     pub fn find_definitions(&self, symbol: &str) -> Vec<(&str, usize)> {
@@ -1284,9 +1271,7 @@ impl ScopeGraphIndex {
             .collect()
     }
 
-    // ========================================================================
     // Statistics and metadata
-    // ========================================================================
 
     /// Get statistics: (files_count, total_definitions, total_references).
     ///
@@ -1301,7 +1286,6 @@ impl ScopeGraphIndex {
         )
     }
 
-    /// Get alias count
     pub fn alias_count(&self) -> usize {
         self.aliases.len()
     }
@@ -1356,9 +1340,7 @@ impl ScopeGraphIndex {
         self.interner.shrink_to_fit();
     }
 
-    // ========================================================================
     // Binary serialization (custom format with magic bytes)
-    // ========================================================================
 
     /// Save the index to a file in binary format.
     pub fn save(&self, path: &Path) -> io::Result<()> {
@@ -1617,7 +1599,8 @@ impl ScopeGraphIndex {
 
         Ok(Self {
             interner,
-            graphs: HashMap::new(), // Not serialized
+            // Not serialized
+            graphs: HashMap::new(),
             definitions,
             references,
             aliases,
@@ -1716,7 +1699,8 @@ mod tests {
         index.compact();
         let (f1, d1, r1) = index.stats();
 
-        index.compact(); // second call must be a no-op
+        // second call must be a no-op
+        index.compact();
         let (f2, d2, r2) = index.stats();
 
         assert_eq!(f1, f2);

crates/codegen/kigi-codebase-graph/src/scope_graph/mod.rs

@@ -16,17 +16,12 @@ pub use nodes::{LocalDef, LocalImport, LocalScope, NodeKind, Reference, Symbol,
 
 use crate::languages::TSLanguageConfig;
 
-/// Result of building a scope graph, including alias pairs.
 pub struct ScopeGraphResult {
-    /// The scope graph for the file.
     pub graph: ScopeGraph,
-    /// Alias pairs: (alias_name, original_name).
+    /// Each pair is `(alias_name, original_name)`.
     pub aliases: Vec<(String, String)>,
 }
 
-/// Build a ScopeGraph from tree-sitter query and source.
-///
-/// This is a convenience wrapper around `scope_graph_from_definitions_query`.
 pub fn build_scope_graph(
     query: &tree_sitter::Query,
     root_node: tree_sitter::Node<'_>,

crates/codegen/kigi-codebase-graph/src/scope_graph/nodes.rs

@@ -89,7 +89,6 @@ impl LocalDef {
         &src[self.range.start_byte()..self.range.end_byte()]
     }
 
-    /// Get the scope range.
     pub fn scope_range(&self) -> &Range {
         &self.scope.range
     }