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/common/kigi-test-utils/src/env.rs

@@ -1,8 +1,7 @@
 //! Environment-variable test knobs.
 
-/// Parse a `usize` env knob, falling back to `default` when unset or
-/// unparseable. The perf-repro convention for sizing `#[ignore]` benches
-/// (e.g. `KIGI_PERF_GIT_FILES`).
+/// Parse a `usize` env knob; use `default` when unset or unparseable.
+/// Perf-repro convention for sizing `#[ignore]` benches (e.g. `KIGI_PERF_GIT_FILES`).
 pub fn env_usize(key: &str, default: usize) -> usize {
     std::env::var(key)
         .ok()

crates/common/kigi-test-utils/src/git.rs

@@ -1,21 +1,16 @@
 //! Hermetic git helpers for tests.
 //!
-//! When running under `bazel test`, the `GIT_BIN_PATH` environment variable
-//! points to a statically-linked git binary provided by Bazel.  The helpers
-//! in this module prepend that binary's directory to `PATH` so that
-//! `Command::new("git")` resolves to it instead of relying on a
-//! system-installed git.
+//! Under `bazel test`, `GIT_BIN_PATH` points at a Bazel-provided static git.
+//! Helpers prepend that binary's directory to `PATH` so `Command::new("git")`
+//! resolves to it instead of a system install.
 
 use std::path::{Path, PathBuf};
 use std::sync::Once;
 
 static HERMETIC_GIT_INIT: Once = Once::new();
 
-/// Prepend the hermetic git binary directory to `PATH` so that
-/// `Command::new("git")` resolves to the Bazel-provided static binary
-/// instead of relying on a system-installed git.
-///
-/// Safe to call multiple times — only the first call mutates `PATH`.
+/// Prepend the hermetic git binary directory to `PATH`.
+/// Idempotent — only the first call mutates `PATH`.
 pub fn ensure_hermetic_git_on_path() {
     HERMETIC_GIT_INIT.call_once(|| {
         if let Ok(git_bin) = std::env::var("GIT_BIN_PATH") {
@@ -27,7 +22,7 @@ pub fn ensure_hermetic_git_on_path() {
             };
             if let Some(bin_dir) = git_path.parent() {
                 let current_path = std::env::var("PATH").unwrap_or_default();
-                // SAFETY: called once via `Once` before any child processes are spawned.
+                // SAFETY: once via `Once`, before any child processes spawn.
                 unsafe {
                     std::env::set_var("PATH", format!("{}:{}", bin_dir.display(), current_path));
                 }
@@ -36,8 +31,7 @@ pub fn ensure_hermetic_git_on_path() {
     });
 }
 
-/// Ensure the hermetic git binary is on `PATH` before running tests that
-/// need git.  Call at the top of any `#[test]` that spawns `git` commands.
+/// Put hermetic git on `PATH` at the top of tests that spawn `git`.
 ///
 /// ```ignore
 /// #[test]
@@ -53,9 +47,7 @@ macro_rules! require_git {
     };
 }
 
-/// Initialise a fresh git repository at `path` with a dummy user config.
-///
-/// Calls [`ensure_hermetic_git_on_path`] first so the hermetic binary is used.
+/// Init a fresh repo at `path` with dummy user config (hermetic git).
 pub fn init_git_repo(path: &Path) {
     ensure_hermetic_git_on_path();
     std::process::Command::new("git")
@@ -77,9 +69,7 @@ pub fn init_git_repo(path: &Path) {
         .unwrap();
 }
 
-/// Stage all files and create a commit.
-///
-/// Calls [`ensure_hermetic_git_on_path`] first so the hermetic binary is used.
+/// Stage all files and create a commit (hermetic git).
 pub fn git_commit_all(path: &Path, message: &str) {
     ensure_hermetic_git_on_path();
     std::process::Command::new("git")
@@ -94,20 +84,16 @@ pub fn git_commit_all(path: &Path, message: &str) {
         .unwrap();
 }
 
-/// Run a git command in `dir` with a deterministic author/committer, assert
-/// success, and return trimmed stdout.
-///
-/// Calls [`ensure_hermetic_git_on_path`] first so the hermetic binary is used.
+/// Run git in `dir` with a fixed author/committer; assert success; return
+/// trimmed stdout (hermetic git).
 pub fn run_git(dir: &Path, args: &[&str]) -> String {
     run_git_with_env(dir, args, &[])
 }
 
-/// Like [`run_git`], with extra environment variables (e.g.
-/// `GIT_SEQUENCE_EDITOR`). Hermetic beyond the binary and author identity:
-/// the developer's global/system git config is masked (a local
-/// `commit.gpgsign`/`core.hooksPath`/`rebase.autoSquash` must not change
-/// test behavior) and credential prompts are disabled. `envs` is applied
-/// last, so callers can override any of this.
+/// Like [`run_git`], with extra env vars (e.g. `GIT_SEQUENCE_EDITOR`).
+/// Masks global/system git config and disables credential prompts so local
+/// `commit.gpgsign` / `core.hooksPath` / `rebase.autoSquash` cannot skew
+/// tests. `envs` is applied last and may override any of this.
 pub fn run_git_with_env(dir: &Path, args: &[&str], envs: &[(&str, &str)]) -> String {
     ensure_hermetic_git_on_path();
     let mut cmd = std::process::Command::new("git");
@@ -138,9 +124,8 @@ pub fn run_git_with_env(dir: &Path, args: &[&str], envs: &[(&str, &str)]) -> Str
     String::from_utf8_lossy(&output.stdout).trim().to_string()
 }
 
-/// Write a grouped fan-out tree of ~`files` files (`files_per_dir` per
-/// directory, directories bucketed 100 per group) under `dir`. No git
-/// operations — callers stage/commit as needed.
+/// Write a grouped fan-out of ~`files` files under `dir` (`files_per_dir`
+/// per directory, directories bucketed 100 per group). No git ops.
 pub fn write_fanout_tree(dir: &Path, files: usize, files_per_dir: usize) {
     for d in 0..files.div_ceil(files_per_dir) {
         let sub = dir.join(format!("g{}", d / 100)).join(format!("d{d}"));
@@ -155,9 +140,9 @@ pub fn write_fanout_tree(dir: &Path, files: usize, files_per_dir: usize) {
     }
 }
 
-/// Create a `feature` branch with `picks` one-file commits off the current
-/// HEAD, advance the base branch by one commit (so a rebase has work), and
-/// leave `feature` checked out. Returns the base branch name.
+/// Create `feature` with `picks` one-file commits off HEAD, advance the base
+/// by one commit (so rebase has work), leave `feature` checked out.
+/// Returns the base branch name.
 pub fn make_feature_branch(dir: &Path, picks: usize) -> String {
     let base = run_git(dir, &["rev-parse", "--abbrev-ref", "HEAD"]);
     run_git(dir, &["checkout", "-b", "feature"]);

crates/common/kigi-test-utils/src/image.rs

@@ -1,13 +1,14 @@
 //! Synthetic image fixtures shared across crates' test suites.
 
-/// Wrap a PNG into a minimal single-frame ICO. `width`/`height` are the
-/// ICONDIRENTRY bytes (`0` means 256); the PNG carries the real dimensions.
+/// Wrap a PNG into a minimal single-frame ICO.
+/// `width`/`height` are ICONDIRENTRY bytes (`0` means 256); the PNG holds
+/// the real dimensions.
 pub fn ico_with_png_frame(png: &[u8], width: u8, height: u8) -> Vec<u8> {
     let mut buf = Vec::with_capacity(22 + png.len());
-    buf.extend_from_slice(&[0, 0, 1, 0, 1, 0]); // ICONDIR
-    buf.extend_from_slice(&[width, height, 0, 0, 1, 0, 32, 0]); // ICONDIRENTRY
-    buf.extend_from_slice(&(png.len() as u32).to_le_bytes()); // bytes in resource
-    buf.extend_from_slice(&22u32.to_le_bytes()); // offset to the PNG payload
+    buf.extend_from_slice(&[0, 0, 1, 0, 1, 0]);
+    buf.extend_from_slice(&[width, height, 0, 0, 1, 0, 32, 0]);
+    buf.extend_from_slice(&(png.len() as u32).to_le_bytes());
+    buf.extend_from_slice(&22u32.to_le_bytes());
     buf.extend_from_slice(png);
     buf
 }

crates/common/kigi-test-utils/src/lib.rs

@@ -1,22 +1,10 @@
-//! Shared test utilities for xAI crates.
+//! Shared test utilities for Kigi crates.
 //!
-//! Provides common helpers that are needed by many crates' test suites:
-//!
-//! - **Hermetic git**: [`git::ensure_hermetic_git_on_path`] prepends the Bazel-provided
-//!   static `git` binary to `PATH` so that tests don't depend on a system-installed git.
-//!   The [`require_git!`] macro is a convenient shorthand.
-//!
-//! - **Git repo helpers**: [`git::init_git_repo`] and [`git::git_commit_all`] for
-//!   setting up throwaway git repos in tests.
-//!
-//! - **Bazel runfiles**: [`crate_root!`] resolves the crate root directory via
-//!   Bazel runfiles (for `bazel test`) or `CARGO_MANIFEST_DIR` (for `cargo test`).
-//!
-//! - **Tracing capture**: [`tracing_capture::MessagePrefixCounter`] counts
-//!   log lines by message prefix (thread-scoped or global install) for tests
-//!   that assert on how often an instrumented code path ran.
-//!
-//! - **Env knobs**: [`env::env_usize`] for perf-repro test sizing.
+//! - **Hermetic git**: [`git::ensure_hermetic_git_on_path`] / [`require_git!`]
+//! - **Repo helpers**: [`git::init_git_repo`], [`git::git_commit_all`]
+//! - **Bazel runfiles**: [`crate_root!`]
+//! - **Tracing capture**: [`tracing_capture::MessagePrefixCounter`]
+//! - **Env knobs**: [`env::env_usize`]
 
 pub mod env;
 pub mod git;

crates/common/kigi-test-utils/src/runfiles_util.rs

@@ -1,15 +1,12 @@
-//! Bazel runfiles helpers for locating test data.
+//! Bazel runfiles helpers for test data.
 //!
-//! Under `bazel test`, source files and test data are accessed via the
-//! *runfiles* tree.  Under `cargo test`, `CARGO_MANIFEST_DIR` provides
-//! the crate root.  The [`crate_root!`] macro abstracts over both.
+//! Under `bazel test`, data lives in the runfiles tree; under `cargo test`,
+//! `CARGO_MANIFEST_DIR` is the crate root. [`crate_root!`] covers both.
 
 use std::path::PathBuf;
 
-/// Try to resolve a runfiles path to an absolute directory.
-///
-/// Returns `Some(path)` when running under Bazel (with the `bazel` feature
-/// enabled) and the runfiles entry exists, `None` otherwise.
+/// Resolve a runfiles path to an absolute directory when the `bazel` feature
+/// is on and the entry exists; otherwise `None`.
 pub fn try_resolve_runfiles(_path: &str) -> Option<PathBuf> {
     #[cfg(feature = "bazel")]
     {
@@ -22,11 +19,8 @@ pub fn try_resolve_runfiles(_path: &str) -> Option<PathBuf> {
     }
 }
 
-/// Resolve the crate root directory, working under both `bazel test` and
-/// `cargo test`.
-///
-/// Under Bazel the path is resolved via runfiles; under Cargo it falls back
-/// to `CARGO_MANIFEST_DIR`.
+/// Crate root under both `bazel test` (runfiles) and `cargo test`
+/// (`CARGO_MANIFEST_DIR`).
 ///
 /// # Example
 ///

crates/common/kigi-test-utils/src/tracing_capture.rs

@@ -1,14 +1,13 @@
-//! Test-only tracing capture: count events whose `message` starts with a
-//! known prefix.
+//! Count tracing events whose `message` starts with a known prefix.
 //!
-//! Producers should export the exact log-line prefixes as `pub const`s next
-//! to the `tracing::debug!` call sites (e.g. `kigi_hunk_tracker`'s
-//! `REFRESH_SCAN_LOG_PREFIX`) so tests never duplicate the strings.
+//! Producers should export exact prefixes as `pub const`s next to the
+//! `tracing::debug!` site (e.g. `REFRESH_SCAN_LOG_PREFIX`) so tests never
+//! duplicate the strings.
 
 use std::sync::Arc;
 use std::sync::atomic::{AtomicUsize, Ordering};
 
-/// Extracts the formatted `message` field of one event.
+/// Pulls the formatted `message` field off one event.
 #[derive(Default)]
 struct MessageVisitor(String);
 
@@ -20,8 +19,8 @@ impl tracing::field::Visit for MessageVisitor {
     }
 }
 
-/// A `tracing_subscriber::Layer` counting, per registered prefix, the events
-/// whose `message` starts with it. Clones share the counts.
+/// Layer that counts, per registered prefix, events whose `message` starts
+/// with it. Clones share the same counters.
 #[derive(Clone)]
 pub struct MessagePrefixCounter {
     counters: Arc<Vec<(&'static str, AtomicUsize)>>,
@@ -34,8 +33,7 @@ impl MessagePrefixCounter {
         }
     }
 
-    /// Events counted so far for `prefix`. Panics on a prefix that was never
-    /// registered — that is a bug in the test, not a zero count.
+    /// Count for `prefix`. Panics if `prefix` was never registered.
     pub fn count(&self, prefix: &str) -> usize {
         self.counters
             .iter()
@@ -62,9 +60,9 @@ impl<S: tracing::Subscriber> tracing_subscriber::Layer<S> for MessagePrefixCount
     }
 }
 
-/// Install a **thread-scoped** default subscriber counting `prefixes`; hold
-/// the guard for the test's lifetime. Only observes events emitted on the
-/// current thread — tasks under test must run on a current-thread runtime.
+/// Thread-scoped default subscriber counting `prefixes`. Hold the guard for
+/// the test lifetime. Only sees events on the current thread — use a
+/// current-thread runtime for the subject under test.
 pub fn install_prefix_counter_thread(
     prefixes: &[&'static str],
 ) -> (tracing::subscriber::DefaultGuard, MessagePrefixCounter) {
@@ -74,12 +72,10 @@ pub fn install_prefix_counter_thread(
     (tracing::subscriber::set_default(subscriber), counter)
 }
 
-/// Install the **process-global** subscriber counting `prefixes` — for tests
-/// whose subject spawns its own threads/runtimes. Panics if a global
-/// subscriber already exists: the test binary must own it.
+/// Process-global subscriber counting `prefixes` — for subjects that spawn
+/// their own threads/runtimes. Panics if a global subscriber already exists.
 ///
-/// `stderr_env_filter` additionally tees formatted logs matching the given
-/// `EnvFilter` directive to stderr (local debugging).
+/// `stderr_env_filter` optionally tees matching formatted logs to stderr.
 pub fn install_prefix_counter_global(
     prefixes: &[&'static str],
     stderr_env_filter: Option<&str>,