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-fast-worktree/src/copy/cow.rs

@@ -104,7 +104,7 @@ mod tests {
         let dst = temp.path().join("link");
 
         std::fs::write(&dst, "stale").unwrap();
-        // Target is intentionally dangling; it must still be created.
+        // Target is deliberately dangling; it must still be created.
         replace_symlink(Path::new("does-not-exist"), &dst).unwrap();
 
         let meta = std::fs::symlink_metadata(&dst).unwrap();

crates/codegen/kigi-fast-worktree/src/copy/engine.rs

@@ -98,16 +98,20 @@ pub(crate) fn copy_parallel(
     // Deep directory trees (15+ levels) amplify this significantly.
     let mut builder = WalkBuilder::new(source);
     builder
-        .hidden(false) // Include hidden files.
+        // Include hidden files.
+        .hidden(false)
         .git_ignore(config.respect_gitignore)
-        .git_global(false) // Never use global gitignore (~/.config/git/ignore) —
+        // Never use global gitignore (~/.config/git/ignore) —
+        .git_global(false)
         // it contains personal preferences irrelevant to worktree creation.
-        .git_exclude(false) // Never use .git/info/exclude — external tooling
+        // Never use .git/info/exclude — external tooling
+        .git_exclude(false)
         // can append broad patterns (*.min.js, *.zip) that
         // incorrectly skip git-tracked files. The `ignore` crate doesn't
         // check tracking status, so tracked files matching these patterns
         // get silently dropped during the copy.
-        .threads(num_workers) // Limit walker parallelism to avoid FD exhaustion
+        // Limit walker parallelism to avoid FD exhaustion
+        .threads(num_workers)
         .filter_entry(|entry| {
             // Always skip .git directory.
             entry.file_name() != ".git"
@@ -274,7 +278,8 @@ mod tests {
         assert!(dest.path().join("file1.txt").exists());
         assert!(dest.path().join("file2.txt").exists());
         assert!(dest.path().join("subdir/file3.txt").exists());
-        assert_eq!(result.copied_paths.len(), 4); // 3 files + 1 dir
+        // 3 files + 1 dir
+        assert_eq!(result.copied_paths.len(), 4);
     }
 
     #[test]

crates/codegen/kigi-fast-worktree/src/copy/gitdir.rs

@@ -3,8 +3,8 @@
 //! Copies essential git internal files using reflink (CoW) when supported,
 //! skipping transient state, lock files, and stale worktree registrations.
 //!
-//! The `objects/` directory (often the largest subtree) is copied in parallel
-//! using a thread pool for better throughput on SSDs.
+//! The tree is walked once to enumerate entries, then the copies are sharded
+//! across scoped threads for throughput on SSDs.
 
 use std::path::{Path, PathBuf};
 use std::sync::atomic::{AtomicU64, Ordering};
@@ -13,7 +13,6 @@ use anyhow::{Context, Result};
 
 use crate::copy::cow::clone_file;
 
-/// Statistics from copying the `.git/` directory.
 #[derive(Clone, Debug, Default)]
 pub(crate) struct GitDirCopyStats {
     pub files_copied: u64,
@@ -27,9 +26,7 @@ pub(crate) struct GitDirCopyStats {
 /// These are either transient state (merge/rebase in-progress markers) or
 /// linked-worktree metadata that would be stale in the copy.
 const SKIP_TOP_LEVEL: &[&str] = &[
-    // Linked worktree registrations — stale in a standalone copy
     "worktrees",
-    // Transient HEAD-like state files
     "FETCH_HEAD",
     "ORIG_HEAD",
     "MERGE_HEAD",
@@ -38,11 +35,9 @@ const SKIP_TOP_LEVEL: &[&str] = &[
     "REBASE_HEAD",
     "AUTO_MERGE",
     "BISECT_LOG",
-    // In-progress multi-step operation state
     "sequencer",
     "rebase-merge",
     "rebase-apply",
-    // GC state
     "gc.log",
     // fsmonitor daemon state — a host-local Unix-domain IPC socket
     // (`fsmonitor--daemon.ipc`, which cannot be reflinked/copied) plus its
@@ -52,27 +47,16 @@ const SKIP_TOP_LEVEL: &[&str] = &[
     "fsmonitor--daemon.ipc",
 ];
 
-/// A work item for the parallel copy pool.
 struct CopyWork {
     source: PathBuf,
     dest: PathBuf,
 }
 
-/// Copy `.git/` directory contents using CoW, skipping unnecessary entries.
+/// Build a standalone git repository's `.git/` at `dest_git` by selectively
+/// copying from `source_git`, using reflink (CoW) where the filesystem
+/// supports it and falling back to a regular copy otherwise.
 ///
-/// Creates a standalone git repository's `.git/` at `dest_git` by selectively
-/// copying from `source_git`. Files are copied using reflink (CoW) when the
-/// filesystem supports it, falling back to regular copy otherwise.
-///
-/// The `objects/` subtree is copied in parallel (it's typically the largest
-/// part and has no ordering dependencies). Other top-level entries are copied
-/// sequentially.
-///
-/// Skips:
-/// - Lock files (`*.lock`) at any depth
-/// - Stale worktree registrations (`worktrees/`)
-/// - Transient state files (`MERGE_HEAD`, `CHERRY_PICK_HEAD`, etc.)
-/// - In-progress rebase/cherry-pick state (`sequencer/`, `rebase-merge/`)
+/// Lock files at any depth and the [`SKIP_TOP_LEVEL`] entries are left behind.
 pub(crate) fn copy_git_dir(source_git: &Path, dest_git: &Path) -> Result<GitDirCopyStats> {
     copy_git_dir_with_workers(source_git, dest_git, num_cpus::get())
 }
@@ -95,8 +79,6 @@ fn copy_git_dir_with_workers(
     let symlinks_copied = AtomicU64::new(0);
     let entries_skipped = AtomicU64::new(0);
 
-    // First pass: collect work items for parallel copy.
-    // We collect all (source, dest) pairs, then process them in parallel.
     let mut work_items: Vec<CopyWork> = Vec::new();
     collect_work_recursive(
         source_git,
@@ -107,7 +89,6 @@ fn copy_git_dir_with_workers(
         &entries_skipped,
     )?;
 
-    // Process file copies in parallel using scoped threads.
     let num_workers = max_workers.min(work_items.len().max(1));
 
     if num_workers <= 1 || work_items.len() < 64 {
@@ -182,10 +163,9 @@ fn copy_git_dir_with_workers(
     Ok(stats)
 }
 
-/// Recursively collect work items (files/symlinks to copy), creating directories eagerly.
-///
-/// Directories are created immediately (they must exist before files are written),
-/// but file copies are deferred to the work list for parallel processing.
+/// Walk `source`, creating every directory eagerly (they must exist before the
+/// copy workers write into them) while deferring files and symlinks to
+/// `work_items` for parallel copying.
 fn collect_work_recursive(
     source: &Path,
     dest: &Path,
@@ -230,7 +210,6 @@ fn collect_work_recursive(
                 entries_skipped,
             )?;
         } else if file_type.is_file() || file_type.is_symlink() {
-            // Regular file or symlink — add to work list.
             work_items.push(CopyWork {
                 source: source_path,
                 dest: dest_path,
@@ -249,14 +228,12 @@ fn collect_work_recursive(
     Ok(())
 }
 
-/// Copy a single file or symlink entry.
 fn copy_single_entry(
     source_path: &Path,
     dest_path: &Path,
     files_copied: &AtomicU64,
     symlinks_copied: &AtomicU64,
 ) -> Result<()> {
-    // Check if it's a symlink by querying symlink metadata.
     let metadata = std::fs::symlink_metadata(source_path)
         .with_context(|| format!("failed to stat {}", source_path.display()))?;
 
@@ -301,13 +278,10 @@ fn copy_single_entry(
     Ok(())
 }
 
-/// Decide whether to skip a `.git/` entry based on its name and depth.
 fn should_skip(name: &str, depth: usize) -> bool {
-    // Skip lock files at any depth
     if name.ends_with(".lock") {
         return true;
     }
-    // Skip known top-level entries
     if depth == 0 && SKIP_TOP_LEVEL.contains(&name) {
         return true;
     }
@@ -325,7 +299,6 @@ mod tests {
         let source_git = temp.path().join("source/.git");
         let dest_git = temp.path().join("dest/.git");
 
-        // Create a minimal .git structure
         std::fs::create_dir_all(source_git.join("objects/pack")).unwrap();
         std::fs::create_dir_all(source_git.join("refs/heads")).unwrap();
         std::fs::write(source_git.join("HEAD"), "ref: refs/heads/main\n").unwrap();
@@ -539,7 +512,6 @@ mod tests {
 
         let err = copy_git_dir_with_workers(&source_git, &dest_git, 4)
             .expect_err("a failed .git/ entry copy must propagate as an error");
-        // The error names the failing entry, not some unrelated setup failure.
         let chain = format!("{err:#}");
         assert!(
             chain.contains("obj0"),

crates/codegen/kigi-fast-worktree/src/copy/shard.rs

@@ -17,17 +17,13 @@ fn rapidhash_path(path: &Path) -> u64 {
     rapidhash_v3(bytes)
 }
 
-/// Compute the shard index for a path based on its parent directory.
-///
-/// Files in the same directory will always be assigned to the same shard,
-/// which avoids lock contention when creating parent directories.
+/// Sharded on the parent directory, so files in the same directory always land
+/// in the same shard and never contend on creating their parent.
 pub(crate) fn shard_for_path(path: &Path, num_shards: usize) -> usize {
     let parent = path.parent().unwrap_or(path);
     (rapidhash_path(parent) as usize) % num_shards
 }
 
-/// Deterministic 16-hex-char (full 64-bit) hash of a path's full bytes.
-///
 /// Disambiguates same-basename worktrees that share a basename-derived key (btrfs
 /// snapshot name, worktree DB id). Full 64 bits keep a collision astronomically
 /// unlikely.
@@ -53,7 +49,6 @@ mod tests {
         let shard2 = shard_for_path(&file2, num_shards);
         let shard3 = shard_for_path(&file3, num_shards);
 
-        // All files in src/ should go to the same shard
         assert_eq!(shard1, shard2);
         assert_eq!(shard2, shard3);
     }
@@ -65,10 +60,10 @@ mod tests {
 
         let num_shards = 8;
 
-        // Different directories may (but don't have to) produce different shards
+        // Different directories may collide onto one shard, so there is nothing
+        // to assert beyond "does not panic".
         let _shard1 = shard_for_path(&file1, num_shards);
         let _shard2 = shard_for_path(&file2, num_shards);
-        // Just verify it doesn't panic
     }
 
     #[test]

crates/codegen/kigi-fast-worktree/src/copy/skip.rs

@@ -7,7 +7,6 @@ use anyhow::Result;
 use dashmap::DashSet;
 use ignore::{WalkBuilder, WalkState};
 
-/// Build a globset matcher for skip patterns.
 pub(crate) fn build_skip_matcher(patterns: &[String]) -> Result<globset::GlobSet> {
     let mut builder = globset::GlobSetBuilder::new();
     for pattern in patterns {
@@ -16,10 +15,10 @@ pub(crate) fn build_skip_matcher(patterns: &[String]) -> Result<globset::GlobSet
     Ok(builder.build()?)
 }
 
-/// Collect all *unignored* paths in `source` (relative).
+/// Collect all *unignored* paths in `source`, relative to it.
 ///
-/// This is used to implement an "ignored-only" copy: by collecting unignored paths
-/// and then skipping them during a second pass with `respect_gitignore=false`.
+/// Backs the "ignored-only" copy: a second pass runs with
+/// `respect_gitignore=false` and skips everything in this set.
 pub(crate) fn collect_unignored_paths(
     source: &Path,
     parallelism: usize,
@@ -93,7 +92,6 @@ mod tests {
         std::fs::create_dir_all(&info_dir).unwrap();
         std::fs::write(info_dir.join("exclude"), "*.zip\n").unwrap();
 
-        // A truly-ignored (gitignored, untracked) artifact.
         std::fs::create_dir(repo.join("build")).unwrap();
         std::fs::write(repo.join("build/out.o"), "obj").unwrap();
 

crates/codegen/kigi-fast-worktree/src/copy/types.rs

@@ -6,7 +6,7 @@ use std::sync::Arc;
 
 use dashmap::{DashMap, DashSet};
 
-/// A structured report about dirty (modified/untracked/deleted) files in the source worktree.
+/// Counts of dirty files in the *source* worktree.
 #[derive(Clone, Debug, Default)]
 pub struct DirtyFilesReport {
     pub modified_files: u64,
@@ -14,7 +14,6 @@ pub struct DirtyFilesReport {
     pub deleted_files: u64,
 }
 
-/// Statistics from a copy operation.
 #[derive(Clone, Debug, Default)]
 pub struct CopyStats {
     pub files_copied: u64,
@@ -26,7 +25,6 @@ pub struct CopyStats {
 }
 
 impl CopyStats {
-    /// Merge another stats into this one.
     pub fn merge(&mut self, other: CopyStats) {
         self.files_copied += other.files_copied;
         self.dirs_created += other.dirs_created;
@@ -36,7 +34,6 @@ impl CopyStats {
     }
 }
 
-/// Kind of filesystem entry to replicate.
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub(crate) enum CopyEntryKind {
     File,
@@ -44,25 +41,22 @@ pub(crate) enum CopyEntryKind {
     Symlink,
 }
 
-/// Entry to be processed by a worker.
 #[derive(Debug)]
 pub(crate) struct CopyEntry {
     pub(crate) rel_path: PathBuf,
     pub(crate) kind: CopyEntryKind,
 }
 
-/// Configuration for the parallel copy operation.
 #[derive(Clone, Debug, Default)]
 pub(crate) struct ParallelCopyConfig {
-    /// Number of parallel workers (0 = num_cpus)
+    /// 0 means "one per CPU".
     pub num_workers: usize,
-    /// Channel buffer size per shard
+    /// Channel buffer size, per shard.
     pub channel_buffer: usize,
-    /// Files to skip (relative paths)
+    /// Paths relative to the source root.
     pub skip_files: Option<Arc<DashSet<PathBuf>>>,
-    /// Whether to respect `.gitignore` rules
     pub respect_gitignore: bool,
-    /// Additional patterns to skip (glob patterns)
+    /// Globs, applied on top of `skip_files`.
     pub skip_patterns: Vec<String>,
 }
 

crates/codegen/kigi-fast-worktree/src/copy/worker.rs

@@ -23,7 +23,6 @@ pub(crate) struct WorkerCtx {
 }
 
 pub(crate) fn run_worker(rx: crossbeam::channel::Receiver<CopyEntry>, ctx: WorkerCtx) {
-    // Track created directories to avoid redundant mkdir calls.
     let mut created_dirs: HashSet<PathBuf> = HashSet::new();
 
     for entry in rx {
@@ -59,7 +58,8 @@ fn process_entry(
     issues: &std::sync::Mutex<Vec<String>>,
     file_metadata: &DashMap<PathBuf, Metadata>,
 ) -> bool {
-    // Ensure parent directory exists.
+    // `created_dirs.insert` yields false for a parent this worker already made,
+    // short-circuiting the chain so the mkdir syscall is skipped.
     if let Some(parent) = dst.parent()
         && !parent.as_os_str().is_empty()
         && created_dirs.insert(parent.to_path_buf())
@@ -116,7 +116,6 @@ fn process_entry(
             Ok(()) => {
                 files_copied.fetch_add(1, Ordering::Relaxed);
 
-                // Collect file metadata for index updates
                 if let Ok(metadata) = std::fs::metadata(dst) {
                     file_metadata.insert(entry.rel_path.clone(), metadata);
                 }