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-shell/src/agent/subagent/coordinator_lifecycle.rs

@@ -69,7 +69,6 @@ impl SubagentCoordinator {
                 std::sync::atomic::Ordering::Relaxed,
             );
     }
-    /// Returns a handle to the completion [`Notify`].
     #[cfg_attr(
         not(test),
         expect(
@@ -80,11 +79,9 @@ impl SubagentCoordinator {
     pub fn completion_notify(&self) -> Arc<Notify> {
         Arc::clone(&self.completion_notify)
     }
-    /// Returns a shared handle to the turn-active flag.
     pub fn turn_active_flag(&self) -> Arc<std::sync::atomic::AtomicBool> {
         Arc::clone(&self.is_turn_active)
     }
-    /// Whether the model's turn is currently active.
     #[cfg_attr(
         not(test),
         expect(
@@ -163,7 +160,6 @@ impl SubagentCoordinator {
             subagent_usage_not_applied: self.subagent_usage_not_applied(prompt_id),
         }
     }
-    /// Drain all buffered completion summaries, returning them and clearing the buffer.
     pub fn drain_pending_completions(&mut self) -> Vec<SubagentCompletionSummary> {
         std::mem::take(&mut self.pending_completions)
     }
@@ -235,8 +231,6 @@ impl SubagentCoordinator {
             cancelled: false,
         });
     }
-    /// Insert a synthetic failed entry, push a completion summary, notify waiters.
-    /// Clears any stale pending entry for the same id.
     fn record_failure_completion(&mut self, c: FailureCompletion<'_>) {
         self.pending.remove(&c.subagent_id);
         self.sync_running_gauge();
@@ -303,8 +297,6 @@ impl SubagentCoordinator {
         self.active.insert(tracker.subagent_id.clone(), tracker);
         self.sync_running_gauge();
     }
-    /// Move a finished subagent from `active` to `completed`.
-    /// Returns the tracker if it was active.
     pub fn move_to_completed(
         &mut self,
         id: &str,
@@ -448,7 +440,6 @@ impl SubagentCoordinator {
         }
         SubagentCancelOutcome::NotFound
     }
-    /// Internal: send Cancel + Shutdown to a tracked subagent.
     fn cancel_tracker(tracker: &SubagentTracker) {
         tracker.cancel_token.cancel();
         let _ = tracker

crates/codegen/kigi-shell/src/agent/subagent/coordinator_query.rs

@@ -91,9 +91,6 @@ impl SubagentCoordinator {
         }
         None
     }
-    /// Return `(parent_session_id, child_session_id)` for a given subagent.
-    ///
-    /// Checks active first, then completed. Returns `None` if not found.
     pub(crate) fn session_ids_for(&self, id: &str) -> Option<(String, String)> {
         if let Some(t) = self.active.get(id) {
             return Some((t.parent_session_id.clone(), t.child_session_id.0.to_string()));
@@ -135,7 +132,7 @@ impl SubagentCoordinator {
         self.mark_block_waited(id);
         self.block_wait_slots.entry(id.to_string()).or_default().push(slot);
     }
-    /// Drop a previously registered reply slot (query poll loop exited).
+    /// Drop a registered reply slot (query poll loop exited).
     pub(crate) fn unregister_block_wait(&mut self, id: &str, slot: &BlockWaitSlot) {
         if let Some(slots) = self.block_wait_slots.get_mut(id) {
             slots.retain(|s| !std::rc::Rc::ptr_eq(s, slot));
@@ -181,7 +178,6 @@ impl SubagentCoordinator {
         self.active.get(id).is_some_and(|t| t.explicitly_killed)
             || self.completed.get(id).is_some_and(|c| c.explicitly_killed)
     }
-    /// Return fork provenance for a given subagent.
     pub(crate) fn provenance_for(&self, id: &str) -> SubagentProvenance {
         if let Some(t) = self.active.get(id) {
             return SubagentProvenance {
@@ -254,7 +250,6 @@ impl SubagentCoordinator {
             model_id: meta.effective_model_id,
         })
     }
-    /// Check whether an ID refers to a currently-active (running) subagent.
     pub(crate) fn is_active(&self, id: &str) -> bool {
         self.active.contains_key(id)
     }
@@ -294,7 +289,6 @@ impl SubagentCoordinator {
     }
     /// Snapshot all currently-running subagents for compaction state context.
     ///
-    /// Returns one `ActiveSubagentSummary` per entry in the `active` map.
     /// Completed/failed/cancelled subagents are NOT included — they live in
     /// the `completed` map and are irrelevant for post-compaction reminders
     /// (the model already saw their tool results before compaction).

crates/codegen/kigi-shell/src/agent/subagent/handle_request.rs

@@ -36,11 +36,6 @@ pub(super) fn task_model_override_error(
         is_session_auth,
     )
 }
-/// This is a free async function, NOT a method on MvpAgent. It receives
-/// a `SubagentSpawnContext` with everything it needs, and a mutable
-/// reference to the coordinator for tracking.
-///
-/// Returns when the child session completes (or fails/cancels).
 #[tracing::instrument(
     name = "subagent.handle_request",
     skip_all,

crates/codegen/kigi-shell/src/agent/subagent/mod.rs

@@ -43,7 +43,7 @@ pub(crate) enum InitialContextSource {
     New,
     /// Parent history as `<background_context>` (harness-only chat-prefix fork).
     Forked,
-    /// Resumed from a previously completed peer subagent. The child inherits
+    /// Resumed from a completed peer subagent. The child inherits
     /// the source's raw transcript, tool state, and model. System prompt and
     /// prompt context are freshly rendered from the current agent definition.
     Resumed,
@@ -211,7 +211,6 @@ pub(crate) struct SubagentSpawnContext {
     /// Resolved config for the deploy service.
     pub app_builder_deployer_config:
         kigi_tools::implementations::kigi::deploy_app::AppBuilderDeployerConfig,
-    /// Whether the write_file tool is enabled.
     pub write_file_enabled: bool,
     /// Whether goal mode (`/goal`) is enabled.
     pub goal_enabled: bool,
@@ -423,7 +422,7 @@ impl SubagentSpawnContext {
     /// session-level config, so it is resolved from the same tiers as the
     /// parent (requirements/env/user/managed from disk; remote from the
     /// parent's snapshot) and follows the session into subagents. Bash stays
-    /// on tool defaults, as before that knob existed.
+    /// on tool defaults.
     pub fn resolve_tool_params_json(
         &self,
     ) -> crate::session::agent_rebuild::ResolvedToolParamsJson {
@@ -619,7 +618,6 @@ pub(crate) async fn resolve_snapshot(lookup: Option<SnapshotLookup>) -> Option<S
         }
     }
 }
-/// Check whether a resolved snapshot is still in the `Running` state.
 pub(crate) fn is_running(snap: &SubagentSnapshot) -> bool {
     matches!(
         snap.status,
@@ -2208,7 +2206,6 @@ fn emit_subagent_notification(
         gateway.forward_fire_and_forget(ext_notification);
     }
 }
-/// Progress notification emission interval.
 const PROGRESS_PUBLISH_INTERVAL: std::time::Duration = std::time::Duration::from_secs(2);
 /// Change signature for the progress-publisher dedupe:
 /// `(turn_count, tool_call_count, context_usage_pct, error_count, tokens_used)`.

crates/codegen/kigi-shell/src/agent/subagent/tests/rest.rs

@@ -126,8 +126,6 @@ fn end_to_end_normalized_conversation_shape() {
     assert_eq!(prefix_len, 2);
     assert!(prefix_len < conv.len(), "prefix should not cover the task");
 }
-/// Verify that the task prompt (not background context) would be the
-/// cached prompt text in the session pipeline.
 #[test]
 fn cached_prompt_text_is_task_not_background() {
     use kigi_sampling_types::conversation::ConversationItem;
@@ -162,7 +160,6 @@ fn cached_prompt_text_is_task_not_background() {
         "background should be the inherited context"
     );
 }
-/// Verify extract_last_real_user_query would return the task.
 #[test]
 fn last_user_message_is_task_after_normalization() {
     use kigi_sampling_types::conversation::ConversationItem;
@@ -286,7 +283,6 @@ fn compaction_preserves_inherited_prefix() {
         bg_count, 1, "should have exactly one background_context after compaction"
     );
 }
-/// Verify that compaction with prefix_len=0 (non-forked) passes through unchanged.
 #[test]
 fn compaction_no_prefix_passes_through() {
     use kigi_sampling_types::conversation::ConversationItem;
@@ -623,7 +619,6 @@ fn subagent_worktree_snapshot_gate_defaults_off() {
     let ctx = ctx_with_toggle(std::collections::HashMap::new());
     assert!(! ctx.resolve_subagent_worktree_snapshot_enabled());
 }
-/// Remote remote settings value enables the gate when no local override exists.
 #[test]
 fn subagent_worktree_snapshot_gate_remote_enables() {
     let mut ctx = ctx_with_toggle(std::collections::HashMap::new());
@@ -649,7 +644,6 @@ fn subagent_worktree_snapshot_gate_local_overrides_remote() {
         "local [features] subagent_worktree_snapshot=false must override remote enable"
     );
 }
-/// Local config alone enables the gate (the per-deployment rollout lever).
 #[test]
 fn subagent_worktree_snapshot_gate_local_enables() {
     let mut config = crate::agent::config::Config::default();
@@ -2380,7 +2374,7 @@ async fn resolve_subagent_inherits_parent_model_without_pins() {
 /// An explicit `[subagents.models]` pin routes the subagent to that
 /// model regardless of the parent model — both a light parent
 /// (`kigi-4.5`) and a custom parent (`composer-2-fast`)
-/// honor the pin identically now that the heavy-model gate is gone.
+/// honor the pin identically.
 #[tokio::test]
 async fn resolve_subagent_config_override_pin_applies_for_any_parent() {
     use kigi_agent::config::ModelOverride;
@@ -2541,9 +2535,7 @@ async fn subagent_override_first_party_model_still_gets_primary_token() {
 /// LEAK guard (C1, subagent-override `api_key` channel): an API-key registry
 /// platform override must NOT receive the parent's primary Kimi session token —
 /// `resolve_credentials` would stamp it as the child's `api_key` on
-/// `api.moonshot.cn`. This test previously asserted the opposite
-/// (`subagent_override_non_oauth_model_still_gets_primary_token`), which encoded
-/// the defect.
+/// `api.moonshot.cn`.
 ///
 /// Revert-to-red: make `CredentialAuthority::governing_manager`'s
 /// `Some(platform) => None` arm return `self.primary.clone()` and `api_key`