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-api/build.rs

@@ -1,7 +1,8 @@
 fn main() {
     kigi_proto_build::configure()
         .type_attribute(
-            ".", // match every message & enum
+            // match every message & enum
+            ".",
             "#[derive(serde::Serialize, serde::Deserialize)]",
         )
         // ToolConfigEntry is embedded in external JSON contracts

crates/codegen/kigi-tools-api/src/config_validation.rs

@@ -1,16 +1,15 @@
-//! Validation of [`ToolConfigEntry`](crate::ToolConfigEntry) fields,
-//! shared so the backend's save-time check cannot drift from what the
-//! tools server enforces at finalize/bind. Errors carry the offending input
-//! so callers can render gRPC violations without re-parsing.
+//! Validation of [`ToolConfigEntry`](crate::ToolConfigEntry) fields, shared so
+//! the backend's save-time check cannot drift from what the tools server
+//! enforces at finalize/bind. Errors carry the offending input so callers can
+//! render gRPC violations without re-parsing.
 
 use kigi_tool_protocol::ToolId;
 use serde_json::{Map, Value};
 
-/// Why a [`ToolConfigEntry`](crate::ToolConfigEntry) is invalid.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum ToolConfigEntryErrorKind {
-    /// Not valid JSON. Includes an explicitly-set empty string: proto3
-    /// `optional` tracks presence, so `Some("")` is rejected, not unset.
+    /// An explicitly-set empty string lands here rather than being treated as
+    /// unset: proto3 `optional` tracks presence, so `Some("")` is a real value.
     ParamsJsonParse { error: String, raw: String },
     /// Valid JSON but not an object.
     ParamsJsonNotObject { value: Value },
@@ -18,7 +17,6 @@ pub enum ToolConfigEntryErrorKind {
     NameOverrideInvalid { name: String, error: String },
 }
 
-/// Validation error for one entry in a tool-config list.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ToolConfigEntryError {
     pub index: usize,
@@ -27,7 +25,7 @@ pub struct ToolConfigEntryError {
 }
 
 impl ToolConfigEntryError {
-    /// Request field path of the failing field, e.g. `tools[3].params_json`.
+    /// gRPC request field path of the failing field, e.g. `tools[3].params_json`.
     pub fn field_path(&self) -> String {
         match self.kind {
             ToolConfigEntryErrorKind::ParamsJsonParse { .. }
@@ -68,8 +66,7 @@ impl std::fmt::Display for ToolConfigEntryError {
 
 impl std::error::Error for ToolConfigEntryError {}
 
-/// Parse and validate a `params_json`, returning the decoded object (or
-/// `None` when unset). `index`/`tool_id` are only used for error reporting.
+/// `index` and `tool_id` are used only for error reporting.
 pub fn parse_params_json(
     index: usize,
     tool_id: &str,
@@ -96,8 +93,7 @@ pub fn parse_params_json(
     }
 }
 
-/// Validates a `name_override` against the `ToolId` charset/length contract,
-/// mirroring [`parse_params_json`] as the shared source of truth.
+/// Enforces the `ToolId` charset/length contract on a `name_override`.
 pub fn validate_name_override(
     index: usize,
     tool_id: &str,
@@ -118,9 +114,7 @@ pub fn validate_name_override(
 }
 
 /// Returns the first entry whose `id` is not in `allowed_ids`, as
-/// `(index, id)`, or `None` when all ids are allowed.
-///
-/// Pure so backend save-time validation and any future consumer share one rule.
+/// `(index, id)`.
 pub fn first_unknown_tool_id<'a>(
     entries: &'a [crate::ToolConfigEntry],
     allowed_ids: &std::collections::HashSet<String>,

crates/codegen/kigi-tools-api/src/lib.rs

@@ -6,7 +6,6 @@
 
 #![allow(clippy::derive_partial_eq_without_eq)]
 
-/// Generated protobuf types.
 pub mod pb {
     include!(concat!(env!("OUT_DIR"), "/kigi.tools.v1.rs"));
 }
@@ -14,84 +13,24 @@ pub mod pb {
 pub mod config_validation;
 pub mod slash_commands;
 
-// Re-export commonly used types at the crate root for convenience
 pub use pb::{
-    // Agent types
-    AgentCompletionRequirement,
-    AgentToolExecConfig,
-    AgentToolRetryConfig,
-    // Request/response types
-    ClearToolOverrideRequest,
-    ClearToolOverrideResponse,
-    DisableToolRequest,
-    DisableToolResponse,
-    EnableToolRequest,
-    EnableToolResponse,
-    // Enums
-    ErrorCode,
-    ExecuteToolRequest,
-    ExecuteToolResponse,
-    ExecutionMetadata,
-    ExecutionOptions,
-    FinalizeAgentRequest,
-    FinalizeAgentResponse,
-    FinalizeConfigValidationDetails,
-    FinalizeConfigViolation,
-    // Tool server config (finalize-time)
-    FinalizeToolServerConfigRequest,
-    FinalizeToolServerConfigResponse,
-    GetAgentInfoRequest,
-    GetAgentInfoResponse,
-    GetCompletionStateRequest,
-    GetCompletionStateResponse,
-    GetSystemPromptRequest,
-    GetSystemPromptResponse,
-    GetSystemRemindersRequest,
-    GetSystemRemindersResponse,
-    GetToolInfoRequest,
-    GetToolOptionsRequest,
-    GetToolOptionsResponse,
-    // Tool state
-    GetToolStateRequest,
-    GetToolStateResponse,
-    // Truncation config
-    GetTruncationConfigRequest,
-    GetTruncationConfigResponse,
-    ListToolsRequest,
-    ListToolsResponse,
-    // Output format specs
-    OutputFieldSpec,
-    OutputFormat,
-    OutputFormatSpec,
-    ResetCompletionStateRequest,
-    ResetCompletionStateResponse,
-    ResetToolOptionsRequest,
-    ResetToolOptionsResponse,
-    SetSystemRemindersRequest,
-    SetSystemRemindersResponse,
-    SetToolOptionsRequest,
-    SetToolOptionsResponse,
-    SetToolOverrideRequest,
-    SetToolOverrideResponse,
-    SetTruncationConfigRequest,
-    SetTruncationConfigResponse,
-    // Streaming types
-    StreamDataChunk,
-    StreamDataKind,
-    StreamFinalResult,
-    // Capability/metadata types
-    ToolCapabilities,
-    ToolCategory,
-    // Per-tool config entry
-    ToolConfigEntry,
-    ToolError,
-    ToolInfo,
-    ToolSource,
-    ToolStreamChunk,
-    ToolSuccess,
-    TruncationConfig,
-    // Version lifecycle warnings
-    VersionWarning,
+    AgentCompletionRequirement, AgentToolExecConfig, AgentToolRetryConfig,
+    ClearToolOverrideRequest, ClearToolOverrideResponse, DisableToolRequest, DisableToolResponse,
+    EnableToolRequest, EnableToolResponse, ErrorCode, ExecuteToolRequest, ExecuteToolResponse,
+    ExecutionMetadata, ExecutionOptions, FinalizeAgentRequest, FinalizeAgentResponse,
+    FinalizeConfigValidationDetails, FinalizeConfigViolation, FinalizeToolServerConfigRequest,
+    FinalizeToolServerConfigResponse, GetAgentInfoRequest, GetAgentInfoResponse,
+    GetCompletionStateRequest, GetCompletionStateResponse, GetSystemPromptRequest,
+    GetSystemPromptResponse, GetSystemRemindersRequest, GetSystemRemindersResponse,
+    GetToolInfoRequest, GetToolOptionsRequest, GetToolOptionsResponse, GetToolStateRequest,
+    GetToolStateResponse, GetTruncationConfigRequest, GetTruncationConfigResponse,
+    ListToolsRequest, ListToolsResponse, OutputFieldSpec, OutputFormat, OutputFormatSpec,
+    ResetCompletionStateRequest, ResetCompletionStateResponse, ResetToolOptionsRequest,
+    ResetToolOptionsResponse, SetSystemRemindersRequest, SetSystemRemindersResponse,
+    SetToolOptionsRequest, SetToolOptionsResponse, SetToolOverrideRequest, SetToolOverrideResponse,
+    SetTruncationConfigRequest, SetTruncationConfigResponse, StreamDataChunk, StreamDataKind,
+    StreamFinalResult, ToolCapabilities, ToolCategory, ToolConfigEntry, ToolError, ToolInfo,
+    ToolSource, ToolStreamChunk, ToolSuccess, TruncationConfig, VersionWarning,
 };
 
 /// Default client-facing tool name derived from a namespaced tool id.
@@ -109,9 +48,7 @@ pub fn default_client_name(id: &str) -> &str {
     id.split(':').nth(1).unwrap_or(id)
 }
 
-/// Convert ToolCategory enum to a string representation.
 impl ToolCategory {
-    /// Get the string representation of the category.
     pub fn as_str(&self) -> &'static str {
         match self {
             Self::Unspecified => "unspecified",

crates/codegen/kigi-tools-api/src/slash_commands.rs

@@ -6,7 +6,6 @@
 /// keys `/loop` availability on this name.
 pub const SCHEDULER_CREATE_TOOL_NAME: &str = "scheduler_create";
 
-/// Usage hint shown when `/loop` is invoked with no arguments.
 pub fn loop_usage_message() -> &'static str {
     "Usage: /loop [interval] <prompt>\n\
      Example: /loop 30m check deploy status\n\
@@ -14,11 +13,9 @@ pub fn loop_usage_message() -> &'static str {
      Tell me how often it should run (e.g. 30m, 1 hour, every 2 days)."
 }
 
-/// Build the model instruction that `/loop` expands into for `args`.
-///
 /// The model, not brittle host parsing, turns the request into the
 /// `scheduler_create` interval, accepting every natural phrasing and erroring
-/// on bad input rather than silently defaulting. See [`loop_usage_message`].
+/// on bad input rather than silently defaulting.
 pub fn loop_schedule_instruction(args: &str) -> String {
     format!(
         "# /loop -- schedule a recurring prompt\n\n\

crates/codegen/kigi-tools-api/tests/wire_shape.rs

@@ -47,7 +47,6 @@ fn tool_config_entry_round_trips() {
 
 #[test]
 fn minimal_entry_deserializes_from_id_only() {
-    // Consumers must accept sparse payloads: optional fields absent, map empty.
     let back: ToolConfigEntry = serde_json::from_value(serde_json::json!({"id": "Kigi:read_file"}))
         .expect("deserialize minimal");
     assert_eq!(back.id, "Kigi:read_file");
@@ -60,8 +59,6 @@ fn minimal_entry_deserializes_from_id_only() {
 
 #[test]
 fn missing_id_fails_to_deserialize() {
-    // `id` is the only required field: a payload without it must be rejected
-    // instead of silently deserializing with an empty id.
     let result: Result<ToolConfigEntry, _> =
         serde_json::from_value(serde_json::json!({"name_override": "search"}));
     assert!(result.is_err(), "payload without `id` must be rejected");
@@ -69,8 +66,8 @@ fn missing_id_fails_to_deserialize() {
 
 #[test]
 fn explicit_null_optional_fields_deserialize_as_none() {
-    // `#[serde(default)]` covers *absent* keys; explicit `null` is handled by
-    // the `Option` fields themselves. Pin that both shapes are accepted.
+    // `#[serde(default)]` only covers *absent* keys; explicit `null` is
+    // accepted by the `Option` fields themselves.
     let back: ToolConfigEntry = serde_json::from_value(serde_json::json!({
         "id": "Kigi:read_file",
         "params_json": null,
@@ -87,9 +84,8 @@ fn explicit_null_optional_fields_deserialize_as_none() {
 
 #[test]
 fn explicit_null_map_is_rejected() {
-    // The map field is not `Option`-typed: `null` is not coerced to an empty
-    // map. Producers must omit the key or emit `{}`. Pin the rejection so a
-    // codegen change that silently starts accepting `null` is caught.
+    // The map field is not `Option`-typed, so `null` is not coerced to an
+    // empty map: producers must omit the key or emit `{}`.
     let result: Result<ToolConfigEntry, _> = serde_json::from_value(serde_json::json!({
         "id": "Kigi:read_file",
         "params_name_overrides": null,