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/bin/cli.rs

@@ -15,7 +15,6 @@ use tracing::{Level, info};
 
 use kigi_fast_worktree::{BtrfsMode, IgnoredFilesMode, WorkingTreeMode, WorktreeBuilder};
 
-/// CLI enum for BTRFS mode selection
 #[derive(Clone, Debug, Default, ValueEnum)]
 enum CliBtrfsMode {
     /// Auto-detect: use BTRFS snapshot if source is on a BTRFS subvolume
@@ -98,7 +97,6 @@ enum Commands {
 fn main() -> Result<()> {
     let cli = Cli::parse();
 
-    // Initialize tracing
     let level = if cli.verbose {
         Level::DEBUG
     } else {
@@ -167,7 +165,7 @@ fn main() -> Result<()> {
             println!("  Path:   {}", result.worktree_path.display());
             println!("  Commit: {}", &result.commit[..12]);
 
-            // For snapshot methods (btrfs/overlay), files_copied will be 0
+            // Snapshot methods (btrfs/overlay) copy nothing, so files_copied is 0.
             if result.unignored_copy.files_copied > 0 {
                 println!(
                     "  Files:  {} copied, {} dirs",

crates/codegen/kigi-fast-worktree/src/bin/pool_perf_bench.rs

@@ -23,9 +23,7 @@ use clap::Parser;
 
 use kigi_fast_worktree::{CreationMode, WorktreeBuilder, WorktreeSync, remove_worktree};
 
-// ============================================================================
 // CLI
-// ============================================================================
 
 #[derive(Parser)]
 #[command(name = "pool-perf-bench")]
@@ -60,9 +58,7 @@ struct Cli {
     json: bool,
 }
 
-// ============================================================================
 // Timing structs
-// ============================================================================
 
 #[derive(Debug, Clone)]
 struct PhaseTiming {
@@ -97,9 +93,7 @@ struct BenchmarkSummary {
     bottleneck: (String, f64),
 }
 
-// ============================================================================
 // Phase runners
-// ============================================================================
 
 /// Phase 1: Create a linked worktree via GitCheckout mode (what the pool fill task does)
 fn phase_create(source: &Path, dest: &Path, parallelism: usize) -> Result<PhaseTiming> {
@@ -306,9 +300,7 @@ fn phase_cleanup(_source: &Path, worktree: &Path) -> Result<PhaseTiming> {
     })
 }
 
-// ============================================================================
 // A/B mode: two worktrees concurrently
-// ============================================================================
 
 fn run_ab_iteration(
     source: &Path,
@@ -499,9 +491,7 @@ fn run_single_iteration(
     })
 }
 
-// ============================================================================
 // Helpers
-// ============================================================================
 
 fn count_tracked_files(source: &Path) -> Result<usize> {
     kigi_fast_worktree::count_tracked_files(source)
@@ -553,9 +543,7 @@ fn compute_summary(iterations: &[IterationResult]) -> BenchmarkSummary {
     }
 }
 
-// ============================================================================
 // Output
-// ============================================================================
 
 fn print_iteration(result: &IterationResult) {
     println!();
@@ -683,9 +671,7 @@ fn print_json(result: &BenchmarkResult) {
     println!("}}");
 }
 
-// ============================================================================
 // Main
-// ============================================================================
 
 fn main() -> Result<()> {
     let cli = Cli::parse();