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-agent/src/system_reminder.rs

@@ -1,22 +1,14 @@
 //! Reminder policy — wraps kigi-tools reminder config.
 
-/// Default per-prompt fire cap for the runtime turn-end TodoGate. Used
-/// only as the default for `TodoGateConfig`; the runtime consumer reads
-/// the live value from `ReminderPolicy.todo_gate.max_fires_per_prompt`,
-/// so this constant is NOT a hardcoded cap.
+/// Seeds `TodoGateConfig::max_fires_per_prompt`; the gate reads the live value
+/// from `ReminderPolicy.todo_gate`, never this constant.
 pub const DEFAULT_TODO_GATE_MAX_FIRES: u32 = 2;
 
 /// Session-level system reminder policy.
-///
-/// Controls whether system reminders are enabled and configures
-/// the TodoNudge and TodoGate behavior.
 #[derive(Debug, Clone)]
 pub struct ReminderPolicy {
-    /// Whether system reminders are enabled at all.
     pub enabled: bool,
-    /// Configuration for the periodic TodoWrite nudge reminder.
     pub todo_nudge: TodoNudgeConfig,
-    /// Configuration for the runtime turn-end TodoGate.
     pub todo_gate: TodoGateConfig,
 }
 
@@ -30,17 +22,13 @@ impl Default for ReminderPolicy {
     }
 }
 
-/// Configuration for the TodoWrite nudge reminder.
-///
-/// The system will remind the model to use `todo_write` when it
-/// hasn't done so within a configurable number of turns.
+/// Reminds the model to call `todo_write` once it has gone
+/// `turns_since_todo_write` turns without one, then stays quiet for
+/// `turns_between_reminders` turns.
 #[derive(Debug, Clone)]
 pub struct TodoNudgeConfig {
-    /// Whether the TodoNudge reminder is enabled.
     pub enabled: bool,
-    /// Number of turns since last `todo_write` call before nudging.
     pub turns_since_todo_write: u32,
-    /// Minimum turns between nudge reminders.
     pub turns_between_reminders: u32,
 }
 
@@ -54,24 +42,19 @@ impl Default for TodoNudgeConfig {
     }
 }
 
-/// Configuration for the runtime turn-end TodoGate.
-///
-/// The gate inspects `TodoState` after every content-only assistant
-/// message and forces another turn via `<system-reminder>` injection
-/// if pending/unbacked-in-progress todos remain — see
+/// Turn-end gate: inspects `TodoState` after every content-only assistant
+/// message and forces another turn via `<system-reminder>` injection if
+/// pending/unbacked-in-progress todos remain — see
 /// `kigi-shell::session::acp_session::evaluate_todo_gate`.
 ///
-/// **Disabled by default.** Operators opt in via the remote
-/// `todo_gate_enabled = true` remote settings key, or via the
-/// `--todo-gate` CLI flag (session-scoped force-enable, highest
-/// precedence).
+/// **Disabled by default.** Operators opt in via the `todo_gate_enabled`
+/// remote settings key, or via the `--todo-gate` CLI flag (session-scoped
+/// force-enable, highest precedence).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct TodoGateConfig {
-    /// Whether the gate runs at all.
     pub enabled: bool,
-    /// Hard cap on how many times the gate may fire per user prompt
-    /// before the next turn is allowed to end with `TurnOutcome::Completed`.
-    /// Bounds the worst-case extra inference cost.
+    /// Past this many fires per user prompt the next turn is allowed to end
+    /// with `TurnOutcome::Completed`, bounding worst-case extra inference cost.
     pub max_fires_per_prompt: u32,
 }
 
@@ -108,16 +91,11 @@ mod tests {
             "TodoGate ships disabled; remote/local opt-in required"
         );
         assert_eq!(policy.todo_gate.max_fires_per_prompt, 2);
-        // The two reminder mechanisms are independent — flipping one
-        // must not change the other (regression guard).
         assert!(policy.todo_nudge.enabled);
     }
 
     #[test]
     fn todo_gate_enable_does_not_disturb_nudge() {
-        // Remote opt-in (or `[reminder.todo_gate] enabled = true` local
-        // config) flips the gate to on without touching the periodic
-        // TodoNudge as a side-effect.
         let mut policy = ReminderPolicy::default();
         policy.todo_gate.enabled = true;
         assert!(policy.todo_gate.enabled);