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-lifecycle/src/local/contributors/command.rs

@@ -4,8 +4,9 @@ use crate::send::contributors::command::{
     CommandAction, CommandContributor, CommandInvocation, CommandSpec,
 };
 
-/// `?Send` twin of [`CommandContributor`] for single-threaded hosts like kigi build's TUI agent, whose session state is `Rc`/`RefCell`-based and can
-/// never satisfy the `Send` bounds the send flavor bakes into its boxed hook futures.
+/// `?Send` twin of [`CommandContributor`] for single-threaded hosts like kigi build's TUI agent,
+/// whose session state is `Rc`/`RefCell`-based and can never satisfy the `Send` bounds the send
+/// flavor bakes into its boxed hook futures.
 #[async_trait(?Send)]
 pub trait LocalCommandContributor {
     fn advertised_commands(&self) -> Vec<CommandSpec>;
@@ -14,7 +15,8 @@ pub trait LocalCommandContributor {
     -> Result<CommandAction, String>;
 }
 
-/// Send contributors work in single-threaded hosts as-is, so shared logic implements [`CommandContributor`] once and both hosts can register it.
+/// Send contributors work in single-threaded hosts as-is, so shared logic implements
+/// [`CommandContributor`] once and both hosts can register it.
 #[async_trait(?Send)]
 impl<T: CommandContributor> LocalCommandContributor for T {
     fn advertised_commands(&self) -> Vec<CommandSpec> {

crates/codegen/kigi-agent-lifecycle/src/local/contributors/session_lifecycle.rs

@@ -5,7 +5,8 @@ use crate::send::contributors::session_lifecycle::{SessionIdleInput, SessionLife
 /// `?Send` twin of [`SessionLifecycleContributor`].
 #[async_trait(?Send)]
 pub trait LocalSessionLifecycleContributor {
-    /// Fired when the session settles idle (no running turn or queued work); the host owns the check.
+    /// Fired when the session settles idle (no running turn or queued work); the host owns the
+    /// check.
     async fn on_session_idle(&self, _input: &SessionIdleInput) {}
 }
 

crates/codegen/kigi-agent-lifecycle/src/local/contributors/turn_input.rs

@@ -4,8 +4,9 @@ use crate::send::contributors::turn_input::{
     TurnInputContext, TurnInputContributor, TurnInputFragment,
 };
 
-/// `?Send` twin of [`TurnInputContributor`] for single-threaded hosts like kigi build's TUI agent, whose session state is `Rc`/`RefCell`-based
-/// and can never satisfy the `Send` bounds the send flavor bakes into its boxed hook futures.
+/// `?Send` twin of [`TurnInputContributor`] for single-threaded hosts like kigi build's TUI agent,
+/// whose session state is `Rc`/`RefCell`-based and can never satisfy the `Send` bounds the send
+/// flavor bakes into its boxed hook futures.
 #[async_trait(?Send)]
 pub trait LocalTurnInputContributor {
     async fn contribute_turn_input(&self, _input: &TurnInputContext) -> Vec<TurnInputFragment> {
@@ -13,7 +14,8 @@ pub trait LocalTurnInputContributor {
     }
 }
 
-/// Send contributors are usable in single-threaded hosts as-is, so shared logic implements [`TurnInputContributor`] once for both hosts.
+/// Send contributors are usable in single-threaded hosts as-is, so shared logic implements
+/// [`TurnInputContributor`] once for both hosts.
 #[async_trait(?Send)]
 impl<T: TurnInputContributor> LocalTurnInputContributor for T {
     async fn contribute_turn_input(&self, input: &TurnInputContext) -> Vec<TurnInputFragment> {

crates/codegen/kigi-agent-lifecycle/src/local/registry.rs

@@ -6,7 +6,6 @@ use crate::local::contributors::{
     LocalTurnLifecycleContributor,
 };
 
-/// Mutable registry used while hosts register typed runtime contributions.
 #[derive(Default)]
 pub struct LocalExtensionRegistryBuilder {
     turn_lifecycle_contributors: Vec<Rc<dyn LocalTurnLifecycleContributor>>,
@@ -67,7 +66,6 @@ impl LocalExtensionRegistryBuilder {
     }
 }
 
-/// Immutable typed registry produced after extensions are installed.
 #[derive(Default)]
 pub struct LocalExtensionRegistry {
     turn_lifecycle_contributors: Vec<Rc<dyn LocalTurnLifecycleContributor>>,
@@ -94,7 +92,6 @@ impl LocalExtensionRegistry {
         &self.command_contributors
     }
 
-    /// The one contributor owning `name`, or `None` when no extension advertised it.
     pub fn command_handler(&self, name: &str) -> Option<&Rc<dyn LocalCommandContributor>> {
         self.command_handlers.get(name)
     }

crates/codegen/kigi-agent-lifecycle/src/send/contributors/command.rs

@@ -10,7 +10,8 @@ pub struct CommandSpec {
 /// A parsed `/name args` invocation. The host owns parsing and routes it to the command's one owner.
 pub struct CommandInvocation<'a> {
     pub name: &'a str,
-    pub args: &'a str, // Whitespace-trimmed; empty for a bare `/name`.
+    // Whitespace-trimmed; empty for a bare `/name`.
+    pub args: &'a str,
 }
 
 /// What a handled command does to the turn; rejections travel as the `Err` reason.

crates/codegen/kigi-agent-lifecycle/src/send/contributors/session_lifecycle.rs

@@ -1,10 +1,9 @@
 use async_trait::async_trait;
 
-/// Input supplied when the host observes the session settling idle.
 pub struct SessionIdleInput;
 
 #[async_trait]
 pub trait SessionLifecycleContributor: Send + Sync {
-    /// Fired when the session settles idle (no running turn or queued work); the host owns the check.
+    /// Idle means no running turn and no queued work; the host owns that check.
     async fn on_session_idle(&self, _input: &SessionIdleInput) {}
 }

crates/codegen/kigi-agent-lifecycle/src/send/contributors/turn_input.rs

@@ -1,20 +1,17 @@
 use async_trait::async_trait;
 
-/// Turn facts supplied when the host pulls extension input at its sampling chokepoint.
 pub struct TurnInputContext {
-    /// Stable host-owned turn identifier.
     pub turn_id: String,
     /// True when the harness produced the turn (auto-wake, drain, cron, continuation), not the user.
     pub synthetic: bool,
 }
 
-/// A model-visible input fragment contributed into the active turn. The host owns wrapping, origin stamping, and placement.
+/// Raw fragment text: the host owns wrapping, origin stamping, and placement.
 pub struct TurnInputFragment {
     pub text: String,
 }
 
-/// Contributes model-visible input fragments into the active turn when the host pulls at its sampling chokepoint.
-/// Fragments land in the same turn, never a new one.
+/// Fragments land in the turn the host is already sampling, never a new one.
 #[async_trait]
 pub trait TurnInputContributor: Send + Sync {
     async fn contribute_turn_input(&self, _input: &TurnInputContext) -> Vec<TurnInputFragment> {

crates/codegen/kigi-agent-lifecycle/src/send/contributors/turn_lifecycle.rs

@@ -1,6 +1,5 @@
 use async_trait::async_trait;
 
-/// Input supplied when the host starts a turn.
 pub struct TurnStartInput {
     /// True when the harness produced the turn (auto-wake, drain, cron, continuation), not the user.
     pub synthetic: bool,
@@ -12,19 +11,16 @@ impl TurnStartInput {
     }
 }
 
-/// Input supplied when the host completes a turn.
 pub struct TurnDoneInput;
 
-/// Why the host aborted the turn instead of completing it.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum TurnAbortReason {
     /// The client went away mid-turn.
     Disconnected,
-    /// The user interrupted the turn before it completed.
+    /// The user cancelled mid-turn.
     Interrupted,
 }
 
-/// Input supplied when the host aborts a turn.
 pub struct TurnAbortInput {
     pub reason: TurnAbortReason,
 }
@@ -35,7 +31,6 @@ impl TurnAbortInput {
     }
 }
 
-/// Input supplied when the host observes an error for a turn.
 pub struct TurnErrorInput<'a> {
     pub message: &'a str,
 }

crates/codegen/kigi-agent-lifecycle/src/send/registry.rs

@@ -5,7 +5,6 @@ use crate::send::contributors::{
     CommandContributor, SessionLifecycleContributor, TurnInputContributor, TurnLifecycleContributor,
 };
 
-/// Mutable registry used while hosts register typed runtime contributions.
 #[derive(Default)]
 pub struct ExtensionRegistryBuilder {
     turn_lifecycle_contributors: Vec<Arc<dyn TurnLifecycleContributor>>,
@@ -38,8 +37,8 @@ impl ExtensionRegistryBuilder {
         self.command_contributors.push(contributor);
     }
 
-    /// Routes each advertised command to its one owner. Duplicate names are a composition bug:
-    /// first registration wins, panics in debug builds, logs in release.
+    /// Two extensions advertising one command name is a composition bug, so it trips a
+    /// `debug_assert`; release builds keep the first registration and log the loser.
     pub fn build(self) -> ExtensionRegistry {
         let mut command_handlers: HashMap<String, Arc<dyn CommandContributor>> = HashMap::new();
         for contributor in &self.command_contributors {
@@ -63,7 +62,6 @@ impl ExtensionRegistryBuilder {
     }
 }
 
-/// Immutable typed registry produced after extensions are installed.
 #[derive(Default)]
 pub struct ExtensionRegistry {
     turn_lifecycle_contributors: Vec<Arc<dyn TurnLifecycleContributor>>,
@@ -90,7 +88,6 @@ impl ExtensionRegistry {
         &self.command_contributors
     }
 
-    /// The one contributor owning `name`, or `None` when no extension advertised it.
     pub fn command_handler(&self, name: &str) -> Option<&Arc<dyn CommandContributor>> {
         self.command_handlers.get(name)
     }