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-subagent-resolution/src/lib.rs

@@ -1,8 +1,8 @@
 //! Subagent configuration resolution crate.
 //!
-//! Extracts the pure-logic "resolution" phase of subagent spawning from
-//! `kigi-shell` into a reusable library. Given a spawn request and a
-//! resolution context (roles, personas, parent state), this crate resolves:
+//! The pure-logic "resolution" phase of subagent spawning. Given a spawn
+//! request and a resolution context (roles, personas, parent state), this
+//! crate resolves:
 //!
 //! - Effective runtime config (model, persona, capability mode, isolation)
 //!   via precedence: explicit override > role > persona > parent.
@@ -10,20 +10,16 @@
 //! - Role prompt file loading.
 //! - Resume identity validation (type/persona match checks; model is soft-ignored).
 //!
-//! This crate has no dependency on session, coordinator, or transport types.
-//! Designed to be consumed by local hosts (e.g. `kigi-shell`) and any
-//! future remote spawn path that only needs pure resolution logic.
+//! Nothing here may depend on session, coordinator, or transport types: local
+//! hosts (e.g. `kigi-shell`) and any remote spawn path must both be able to
+//! consume it.
 //!
-//! ## Planned composition API
-//!
-//! Future work may add a higher-level composition helper once shell call sites
-//! are refactored onto this crate:
-//!
-//! - `resolve_subagent_spec()` composition function
-//! - `SubagentSpec`, `ResolveSubagentRequest`, `ResolutionContext` boundary types
-//! - Optional deps for `AgentDefinition` lookup and worktree creation
-//! - Model override resolution chain (global > per-type > role > parent)
-//! - Capability mode filtering (delegates to `SubagentCapabilityMode::filter_tool_config()`)
+//! TODO: add a `resolve_subagent_spec()` composition entry point once shell
+//! call sites move onto this crate. It needs `SubagentSpec` /
+//! `ResolveSubagentRequest` / `ResolutionContext` boundary types, optional deps
+//! for `AgentDefinition` lookup and worktree creation, the global > per-type >
+//! role > parent model override chain, and capability mode filtering via
+//! `SubagentCapabilityMode::filter_tool_config()`.
 
 pub mod config;
 pub mod context;