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-tools/src/reminders/lsp_diagnostics.rs

@@ -26,8 +26,8 @@ impl Reminder for LspDiagnosticsReminder {
 
         lsp.ensure_started_background();
 
-        // After SearchReplace edits, notify LSP so diagnostics refresh.
-        // The adapter routes immediately when ready and buffers pre-ready edits otherwise.
+        // Notify LSP of the edit so diagnostics refresh; when the adapter is not
+        // yet ready the notification is buffered rather than dropped.
         if let ToolOutput::SearchReplace(SearchReplaceOutput::EditsApplied(edits)) = tool_output
             && let Ok(content) = std::fs::read_to_string(&edits.absolute_path)
         {
@@ -35,7 +35,7 @@ impl Reminder for LspDiagnosticsReminder {
                 .await;
         }
 
-        // Drain any pending diagnostics (from this or previous edits).
+        // Drain diagnostics queued by this or earlier edits.
         if let Some(summary) = lsp
             .drain_diagnostics(std::time::Duration::from_millis(500))
             .await

crates/codegen/kigi-tools/src/reminders/mod.rs

@@ -22,31 +22,24 @@ pub use lsp_diagnostics::LspDiagnosticsReminder;
 pub use skill_discovery::SkillDiscoveryReminder;
 pub use task_completion::TaskCompletionReminder;
 
-/// The default system-reminder tag name (hyphen).
 pub const DEFAULT_REMINDER_TAG: &str = "system-reminder";
 
-/// Wrap plain text in `<system-reminder>` tags (default hyphen variant).
-///
-/// Input:  `"Some reminder text"`
-/// Output: `"<system-reminder>\nSome reminder text\n</system-reminder>"`
+/// Wrap `text` in the default hyphen tag, [`DEFAULT_REMINDER_TAG`].
 pub fn wrap_reminder(text: &str) -> String {
     wrap_reminder_with_tag(text, DEFAULT_REMINDER_TAG)
 }
 
-/// Wrap plain text in a configurable reminder wrapper.
-///
-/// Use [`DEFAULT_REMINDER_TAG`] unless the harness requires a different
-/// tag name (harness-specific tags live with the harness crate).
+/// Prefer [`DEFAULT_REMINDER_TAG`] unless the harness needs a different tag
+/// name; harness-specific tags live with the harness crate.
 pub fn wrap_reminder_with_tag(text: &str, tag: &str) -> String {
     format!("<{tag}>\n{text}\n</{tag}>")
 }
 
-/// Frame a scheduled task prompt with `<system-reminder>` context for the model.
+/// Frame a scheduled-task prompt with `<system-reminder>` context.
 ///
-/// The raw `prompt` is what the user wrote in `/loop`; this wrapping tells
-/// the model the message is a recurring task execution so it executes
-/// rather than questioning the prompt. The UI shows the raw prompt text;
-/// only the model receives this framed version.
+/// The raw `prompt` is what the user wrote in `/loop`; the framing tells the
+/// model this is a recurring task to execute, not to question. The UI shows
+/// the raw prompt; only the model receives this framed version.
 pub fn format_scheduled_task_prompt(prompt: &str, task_id: &str, human_schedule: &str) -> String {
     format!(
         "<system-reminder>\n\
@@ -61,15 +54,8 @@ pub fn format_scheduled_task_prompt(prompt: &str, task_id: &str, human_schedule:
     )
 }
 
-/// Append wrapped reminders to a tool output string.
-/// Returns output unchanged if reminders is empty.
-///
-/// Each reminder is individually wrapped via
-/// [`wrap_reminder_with_tag`] using the given `tag`, then all are joined
-/// with `"\n\n"` and appended to the output with a `"\n\n"` separator.
-///
-/// Use [`DEFAULT_REMINDER_TAG`] unless the harness requires a different
-/// tag name.
+/// Wrap each reminder and append the block to `output`, separated by blank
+/// lines. Returns `output` unchanged when there are no reminders.
 pub fn format_with_reminders(output: String, reminders: Vec<String>, tag: &str) -> String {
     if reminders.is_empty() {
         return output;

crates/codegen/kigi-tools/src/reminders/skill_discovery.rs

@@ -1,17 +1,12 @@
 //! Skill discovery reminder — discovers new skills near accessed paths.
 //!
-//! Contains `SkillDiscoveryReminder`, a cross-cutting `Reminder` that fires
-//! after every tool call to check for SKILL.md files in `.kigi/skills/`,
-//! `.agents/skills/`, or `.claude/skills/` directories near the accessed path.
-//!
-//! The actual tracking logic lives in
+//! The tracking logic lives in
 //! `types::skill_discovery_tracker::SkillDiscoveryTracker`.
 
 use std::path::{Path, PathBuf};
 
-/// Directories that contain skill definitions (`.kigi/skills/`, `.agents/skills/`,
-/// `.claude/skills/`, `.cursor/skills/`). Shared between startup skill discovery
-/// and runtime `SkillDiscoveryReminder`.
+/// Config directories whose `skills/` subdirectory holds skill definitions.
+/// Shared between startup discovery and the runtime `SkillDiscoveryReminder`.
 pub const SKILL_CONFIG_DIRS: &[&str] = &[".kigi", ".agents", ".claude", ".cursor"];
 
 use crate::implementations::skills::discovery;
@@ -24,31 +19,21 @@ use crate::types::resources::SharedResources;
 use crate::types::skill_discovery_tracker::SkillManager;
 use crate::types::tool::{Reminder, ToolKind};
 
-/// Cross-cutting reminder that discovers skills in subdirectories
-/// near filesystem paths accessed by tools.
+/// Cross-cutting reminder that discovers skills in directories near the
+/// filesystem paths tools access. Register it alongside tools so it runs after
+/// every tool call.
 ///
-/// **Concise mode limitation (V1):** This reminder is globally disabled when
-/// `SystemRemindersEnabled(false)` is set (concise mode). This means dynamic
-/// skill discovery will NOT fire in concise mode. This is an intentional V1
-/// layering compromise — discovery is coupled to the Reminder delivery
-/// mechanism for expediency. If concise-mode support is later needed, migrate
-/// to a dedicated post-tool-call hook that is NOT gated by
-/// `SystemRemindersEnabled`.
-///
-/// Reacts to `ReadFile`, `ListDir`, and `SearchReplace` outputs by
-/// extracting the filesystem path the tool accessed, walking up toward
-/// cwd checking for skill directories, and emitting a reminder for any
-/// newly discovered skills.
-///
-/// This is a standalone struct — not attached to any specific tool.
-/// Register it alongside tools so it runs after every tool call.
+/// **Concise mode limitation (V1):** this reminder is globally disabled when
+/// `SystemRemindersEnabled(false)` is set (concise mode), so dynamic skill
+/// discovery does NOT fire in concise mode. This is an intentional V1 layering
+/// compromise — discovery is coupled to the Reminder delivery mechanism for
+/// expediency. If concise-mode support is later needed, migrate to a dedicated
+/// post-tool-call hook that is NOT gated by `SystemRemindersEnabled`.
 pub struct SkillDiscoveryReminder;
 
 impl SkillDiscoveryReminder {
-    /// Extract the filesystem path the tool accessed from the output.
-    ///
-    /// Returns `None` for tools that don't operate on filesystem paths,
-    /// or for error variants (no reliable path to extract).
+    /// The filesystem path the tool accessed, or `None` for non-filesystem
+    /// tools and error variants (no reliable path to extract).
     fn extract_target_path(tool_output: &ToolOutput) -> Option<&Path> {
         match tool_output {
             ToolOutput::ReadFile(ReadFileOutput::FileContent(fc)) => Some(&fc.absolute_path),
@@ -78,8 +63,6 @@ impl SkillDiscoveryReminder {
         }
     }
 
-    /// Check whether a SKILL.md path is inside a supported skills directory
-    /// (`.kigi/skills/`, `.agents/skills/`, or `.claude/skills/`).
     fn is_in_supported_skills_dir(path: &Path) -> bool {
         for ancestor in path.ancestors().skip(1) {
             if ancestor.file_name().is_some_and(|n| n == "skills") {
@@ -111,8 +94,7 @@ impl Reminder for SkillDiscoveryReminder {
         resources: SharedResources,
         tool_output: &ToolOutput,
     ) -> Vec<String> {
-        // 1. Activate `paths:`-gated skills matching any file the tool touched
-        //    (includes multi-file `apply_patch` edits).
+        // Activate `paths:`-gated skills for every file the tool touched.
         let activation_paths = Self::extract_activation_paths(tool_output);
         if !activation_paths.is_empty() {
             let path_refs: Vec<&Path> = activation_paths.iter().map(PathBuf::as_path).collect();
@@ -122,7 +104,7 @@ impl Reminder for SkillDiscoveryReminder {
             }
         }
 
-        // 2. Discovery walks from a single representative path (read/list/edit).
+        // Discovery itself walks from a single representative path.
         let Some(target_path) = Self::extract_target_path(tool_output) else {
             return vec![];
         };
@@ -156,7 +138,7 @@ impl Reminder for SkillDiscoveryReminder {
             return vec![];
         }
 
-        // 2. Snapshot context under lock, then RELEASE the lock before I/O.
+        // Snapshot context under the lock, then release it before doing I/O.
         let (cwd, git_root, mut checked_dirs_snapshot, compat) = {
             let res = resources.lock().await;
             let Some(tracker) = res.get::<SkillManager>() else {
@@ -173,10 +155,8 @@ impl Reminder for SkillDiscoveryReminder {
                 tracker.compat,
             )
         };
-        // Lock is released here.
 
-        // 3. Run filesystem discovery OUTSIDE the lock.
-        // Calls directly into the discovery module -- no callback indirection.
+        // Filesystem discovery runs outside the lock.
         let discovered = discovery::discover_skills_for_paths(
             &[target_path],
             &cwd,
@@ -195,9 +175,8 @@ impl Reminder for SkillDiscoveryReminder {
             return vec![];
         }
 
-        // 4. Re-acquire lock and merge results into tracker.
-        // The reminder does NOT produce announcement text. It just updates
-        // the tracker state. The session drains announcements from the
+        // Merge results into the tracker. This reminder never returns
+        // announcement text itself; the session drains announcements from the
         // tracker via take_pending_reconciliation() after each tool call.
         {
             let mut res = resources.lock().await;
@@ -206,15 +185,12 @@ impl Reminder for SkillDiscoveryReminder {
                 None => return vec![],
             };
 
-            // Merge checked_dirs from the snapshot back into the tracker.
             tracker.checked_dirs.extend(checked_dirs_snapshot);
 
-            // Add discovered skills (dedup by canonical path, sets pending flag).
+            // add_discovered sets the pending flag the session later drains.
             tracker.add_discovered(discovered);
         }
 
-        // Return empty -- announcement delivery is handled by the session
-        // via take_pending_reconciliation(), NOT by this reminder.
         vec![]
     }
 }

crates/codegen/kigi-tools/src/reminders/task_completion.rs

@@ -40,7 +40,6 @@ const MAX_INLINE_COMPLETION_BYTES: usize = 4_000;
 #[derive(Clone, Debug, Default)]
 pub struct AutoWakeDeliveredIds(pub Arc<std::sync::Mutex<HashSet<String>>>);
 impl AutoWakeDeliveredIds {
-    /// Insert an ID into the delivered set.
     pub fn insert(&self, id: String) {
         self.0.lock().unwrap_or_else(|e| e.into_inner()).insert(id);
     }
@@ -59,7 +58,6 @@ impl AutoWakeDeliveredIds {
             .unwrap_or_else(|e| e.into_inner())
             .contains(id)
     }
-    /// Drain all IDs from the set, returning them.
     pub fn drain(&self) -> Vec<String> {
         let mut guard = self.0.lock().unwrap_or_else(|e| e.into_inner());
         guard.drain().collect()
@@ -186,7 +184,6 @@ pub fn format_monitor_completion(task: &TaskSnapshot, task_output_name: Option<&
         dur = task.duration_secs(),
     )
 }
-/// Warn the model about other background tasks that are still running.
 fn format_running_tasks_warning(running: &[&TaskSnapshot], kill_task_name: Option<&str>) -> String {
     use std::fmt::Write as _;
     let n = running.len();
@@ -498,22 +495,6 @@ pub fn format_between_turn_bash_completions(
     }
     buf
 }
-/// Extract task / subagent IDs whose completion the model already
-/// learned about from this tool result. Used by:
-/// - `TaskCompletionReminder::collect_reminders` to suppress the
-///   per-tool-call `<system-reminder>` for the same ID.
-/// - `kigi-shell`'s `SessionActor` to sweep matching synthetic
-///   auto-wake prompts and notifications out of `pending_inputs` /
-///   `pending_notifications` (closes the TOCTOU race that produces
-///   trailing `<system-reminder>` items in `chat_history.jsonl`).
-///
-/// Centralising this here means the two consumer surfaces cannot drift:
-/// both call the same function, and the exhaustive `match` below
-/// forces every new `ToolOutput` variant to opt in or out at compile
-/// time.
-///
-/// Returns borrowed `&str` slices (no allocation) — the strings live in
-/// `output` for the duration of the call.
 /// Extract the subagent UUID from the body of a Task-tool-formatted
 /// text output. The shape is exactly:
 ///
@@ -538,6 +519,22 @@ fn task_text_agent_id(text: &str) -> Option<&str> {
         .unwrap_or(after.len());
     if end == 0 { None } else { Some(&after[..end]) }
 }
+/// Extract task / subagent IDs whose completion the model already
+/// learned about from this tool result. Used by:
+/// - `TaskCompletionReminder::collect_reminders` to suppress the
+///   per-tool-call `<system-reminder>` for the same ID.
+/// - `kigi-shell`'s `SessionActor` to sweep matching synthetic
+///   auto-wake prompts and notifications out of `pending_inputs` /
+///   `pending_notifications` (closes the TOCTOU race that produces
+///   trailing `<system-reminder>` items in `chat_history.jsonl`).
+///
+/// Centralising this here means the two consumer surfaces cannot drift:
+/// both call the same function, and the exhaustive `match` below
+/// forces every new `ToolOutput` variant to opt in or out at compile
+/// time.
+///
+/// Returns borrowed `&str` slices (no allocation) — the strings live in
+/// `output` for the duration of the call.
 pub fn consumed_completion_ids(output: &ToolOutput) -> Vec<&str> {
     let mut ids = Vec::new();
     if let ToolOutput::Text(t) = output