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-workspace/src/session/checkpoint.rs

@@ -20,12 +20,10 @@ use std::collections::{HashMap, HashSet};
 /// - `None` — a turn hook (`on_before_turn`/`on_after_turn`).
 /// - `Some(idx)` — a rewind RPC arm (`begin_prompt`/`end_prompt`).
 pub(crate) enum TurnBoundary {
-    /// Turn start.
     Start {
         prompt_index: Option<usize>,
         turn_number: u64,
     },
-    /// Turn end.
     End {
         prompt_index: Option<usize>,
         turn_number: u64,
@@ -82,7 +80,6 @@ impl TurnBoundary {
 /// a blob written before a later field existed still deserializes (field `None`).
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct RewindCheckpoint {
-    /// The prompt this checkpoint belongs to.
     pub prompt_index: usize,
     /// Filesystem before/after snapshots for the prompt.
     pub fs: RewindPoint,
@@ -225,7 +222,7 @@ impl WorkspaceHandle {
     /// Keyed on `prompt_index`: turn hooks (`None`) drive activity; rewind RPC
     /// arms (`Some`) drive rewind capture (FS, plus git/hunks when their flags
     /// are on). `workspace_rewind_all_outcomes` also finalizes the open FS
-    /// checkpoint on non-`Completed` turn-ends (gap #2).
+    /// checkpoint on non-`Completed` turn-ends.
     pub(crate) async fn on_turn_boundary(&self, session_id: &str, boundary: TurnBoundary) {
         match boundary {
             TurnBoundary::Start {

crates/codegen/kigi-workspace/src/session/checkpoint_store.rs

@@ -362,7 +362,7 @@ fn load_capped_from_disk(dir: &Path, cap: usize) -> BTreeMap<usize, RewindCheckp
         let Some(idx) = parse_checkpoint_index(&file_name) else {
             // Sweep orphaned temp files from a crashed `write_checkpoint_file`:
             // rehydrate runs once at construction before this instance writes, so
-            // removing them is safe and bounds clutter. Best-effort.
+            // dropping them is safe and bounds clutter. Best-effort.
             if is_orphan_checkpoint_tmp(&file_name) {
                 let _ = std::fs::remove_file(entry.path());
             }
@@ -691,7 +691,7 @@ mod tests {
                 "no separators for {raw:?}: {s:?}"
             );
             assert!(s != "." && s != "..", "not a traversal component: {s:?}");
-            // Joining must stay within the store root and add exactly one path
+            // Joining must stay within the store root and join exactly one path
             // component (no `..` escape).
             let joined = root.join(&s);
             assert!(joined.starts_with(root), "stays in root: {joined:?}");

crates/codegen/kigi-workspace/src/session/file_state.rs

@@ -572,7 +572,8 @@ impl FileStateTracker {
         let mut source = self.lazy_source.lock().await;
         // Clone the path so we can clear `source` after a successful read.
         let Some(path) = source.clone() else {
-            return; // already loaded, or never lazy
+            // already loaded, or never lazy
+            return;
         };
         let loaded = match read_rewind_points_file(&path) {
             Ok(points) => points,
@@ -659,7 +660,7 @@ impl FileStateTracker {
     ///
     /// NOTE: This method is similar to `capture_file_state_with_fs`. They are kept
     /// separate due to type system constraints (`AsyncFileSystem` trait vs `AsyncFsWrapper`
-    /// concrete type). Keep them in sync when making changes.
+    /// concrete type). Keep them in sync when editing either side.
     pub async fn capture_file_state<F: AsyncFileSystem + ?Sized>(
         &self,
         fs: &F,
@@ -677,7 +678,8 @@ impl FileStateTracker {
             // Not currently processing a prompt, skip capture
             return Ok(());
         };
-        drop(current); // Release lock before async operations
+        // Release lock before async operations
+        drop(current);
 
         // Read current file content (or None if it doesn't exist)
         let content = fs
@@ -704,7 +706,7 @@ impl FileStateTracker {
     ///
     /// NOTE: This method is similar to `capture_file_state`. They are kept separate
     /// due to type system constraints (`AsyncFsWrapper` concrete type vs generic
-    /// `AsyncFileSystem` trait). Keep them in sync when making changes.
+    /// `AsyncFileSystem` trait). Keep them in sync when editing either side.
     pub async fn capture_file_state_with_fs(
         &self,
         fs: &AsyncFsWrapper,
@@ -722,7 +724,8 @@ impl FileStateTracker {
             // Not currently processing a prompt, skip capture
             return Ok(());
         };
-        drop(current); // Release lock before async operations
+        // Release lock before async operations
+        drop(current);
 
         // Read current file content (or None if it doesn't exist)
         let content = fs
@@ -826,7 +829,7 @@ impl FileStateTracker {
         result
     }
 
-    /// Get a specific rewind point by prompt index. Intentionally does NOT trigger
+    /// Get a specific rewind point by prompt index. Deliberately does NOT trigger
     /// the historical load: this is the live persistence path (a just-completed
     /// prompt's point is always in memory), so resume-then-work stays fast.
     pub async fn get_rewind_point(&self, prompt_index: usize) -> Option<RewindPoint> {
@@ -1067,7 +1070,8 @@ impl FileStateHandle {
 
 #[cfg(test)]
 mod tests {
-    use super::ToolContext; // from stub above
+    // from stub above
+    use super::ToolContext;
     use super::*;
     use crate::file_system::MockFs;
     use kigi_paths::AbsPathBuf;
@@ -1392,7 +1396,7 @@ mod tests {
         assert!(abs_json.contains("\"path\":\"/abs/path/file.txt\""));
     }
 
-    // ── Lazy historical rewind-point loading ──────────────────────────────────
+    // Lazy historical rewind-point loading
 
     /// Build a rewind point at `idx` with the given (relative path, content) files.
     fn point_with_files(idx: usize, files: &[(&str, &str)]) -> RewindPoint {
@@ -1444,7 +1448,6 @@ mod tests {
         assert_eq!(points.len(), 2);
         assert_eq!(points[0].prompt_index, 0);
         assert_eq!(points[1].prompt_index, 1);
-        // Now singular lookups see the loaded points.
         assert!(tracker.get_rewind_point(0).await.is_some());
     }
 
@@ -1555,9 +1558,9 @@ mod tests {
 
         let metas = tracker.get_rewind_point_metas().await;
         assert_eq!(metas.len(), 2);
-        assert_eq!(metas[0].prompt_index, 0); // from disk
+        assert_eq!(metas[0].prompt_index, 0);
         assert_eq!(metas[0].num_file_snapshots, 1);
-        assert_eq!(metas[1].prompt_index, 1); // from memory
+        assert_eq!(metas[1].prompt_index, 1);
         assert_eq!(metas[1].num_file_snapshots, 1);
     }
 
@@ -1666,7 +1669,7 @@ mod tests {
         assert_eq!(metas[1].num_file_snapshots, 1);
     }
 
-    // ── pure merge_rewind_points_from branch coverage ────────────────────────
+    // pure merge_rewind_points_from branch coverage
 
     #[test]
     fn merge_pure_target_zero_clears_all() {

crates/codegen/kigi-workspace/src/session/git.rs

@@ -940,7 +940,7 @@ fn change_type_from_porcelain(ch: char, staged: bool) -> ChangeType {
 }
 /// Parse `git diff --numstat` output into a map of path → (additions, deletions).
 ///
-/// We intentionally omit `-M` from our `git diff --numstat` invocations, so rename
+/// We deliberately omit `-M` from our `git diff --numstat` invocations, so rename
 /// entries won't appear in practice. The format is simply `ADDS\tDELS\tPATH`
 /// (or `-\t-\tPATH` for binary files).
 fn parse_numstat(output: &str) -> HashMap<String, (u64, u64)> {

crates/codegen/kigi-workspace/src/session/mod.rs

@@ -370,7 +370,7 @@ impl WorkspaceSession {
     ///
     /// TOOL-STATE CAVEAT: the outgoing toolset is not flushed here, so an
     /// in-process rebuild can drop up to one debounce window (≤500 ms) of
-    /// unpersisted state. Intentionally not "fixed" with a flush-before-rebuild:
+    /// unpersisted state. Deliberately not "fixed" with a flush-before-rebuild:
     /// tool `call()` does not hold `update_lock`, so a concurrent call would
     /// still race. Restart/snapshot scenarios are unaffected.
     pub(crate) fn replace(
@@ -486,7 +486,7 @@ pub struct WorkspaceShared {
     pub(crate) session_event_writers:
         Arc<dashmap::DashMap<String, kigi_file_utils::events::EventWriter>>,
     /// `(path, size, mtime_ms) → sha256` memo for the client-facing
-    /// `workspace.client_fs_*` ops, so unchanged files hash once per
+    /// `workspace.client_fs_*` ops, so `unchanged` files hash once per
     /// workspace instead of per stat/read.
     /// Test-only seam: runs after the toolset re-resolve returns and before
     /// the post-resolve turn re-check / install in

crates/codegen/kigi-workspace/src/session/tool_config.rs

@@ -315,8 +315,7 @@ impl SessionContextFactory for WorkspaceSessionContextFactory {
         IDS.clone()
     }
 }
-/// Build web fetch config. Enabled with default params unless
-/// `KIGI_DISABLE_WEB_FETCH=1` is set.
+/// Enabled with default params unless `KIGI_DISABLE_WEB_FETCH=1` is set.
 fn build_web_fetch_config() -> kigi_tools::implementations::kigi::web_fetch::WebFetchConfig {
     use kigi_tools::implementations::kigi::web_fetch::{WebFetchConfig, WebFetchParams};
     if std::env::var("KIGI_DISABLE_WEB_FETCH").is_ok_and(|v| v == "1" || v == "true") {