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/src/plugins/discovery.rs

@@ -21,7 +21,7 @@ use sha2::{Digest, Sha256};
 use super::manifest::{ManifestLoadResult, PluginManifest, load_manifest, name_from_dirname};
 use super::trust::TrustStore;
 
-// ── Public types ──────────────────────────────────────────────────────
+// Public types
 
 /// Where a plugin was discovered from.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
@@ -204,12 +204,12 @@ impl DiscoveryConfig {
     }
 }
 
-// ── Discovery entry point ─────────────────────────────────────────────
+// Discovery entry point
 
 /// User plugin directories in priority order: `$KIGI_SHARE_DIR/plugins` then
 /// `~/.claude/plugins`.
 ///
-/// Unlike agent discovery, plugins are intentionally NOT discovered from a
+/// Unlike agent discovery, plugins are deliberately NOT discovered from a
 /// legacy `~/.kigi/plugins`: plugin trust, persisted plugin-data, and install
 /// paths all resolve under `kigi_home()`, so a plugin scanned from the legacy
 /// tree would appear untrusted and lose its persisted state. Keeping plugins on
@@ -483,7 +483,7 @@ pub fn discover_plugins(
     candidates
 }
 
-// ── Internal helpers ──────────────────────────────────────────────────
+// Internal helpers
 
 /// Scan a plugins parent directory (e.g. `~/.kigi/plugins/`) and collect
 /// each subdirectory as a plugin candidate.
@@ -510,7 +510,8 @@ fn scan_plugin_dir(
 
     let mut subdirs: Vec<PathBuf> = entries
         .filter_map(|e| e.ok())
-        .filter(|e| e.path().is_dir()) // follows symlinks
+        // follows symlinks
+        .filter(|e| e.path().is_dir())
         .map(|e| e.path())
         .collect();
 
@@ -787,7 +788,7 @@ fn resolve_name_conflicts(candidates: &mut Vec<DiscoveredPlugin>) {
     }
 }
 
-// ── Compat installed_plugins.json types ───────────────────────────────
+// Compat installed_plugins.json types
 
 /// Compat `installed_plugins.json` format.
 #[derive(serde::Deserialize)]
@@ -1351,7 +1352,7 @@ mod tests {
         let parts: Vec<&str> = id.0.split('/').collect();
         assert_eq!(parts.len(), 3);
         assert_eq!(parts[0], "user");
-        assert_eq!(parts[1].len(), 8); // 8 hex chars
+        assert_eq!(parts[1].len(), 8);
         assert_eq!(parts[2], "my-plugin");
     }
 

crates/codegen/kigi-agent/src/plugins/git_install.rs

@@ -561,7 +561,7 @@ pub struct UpdateResult {
 
 /// Status of an update attempt.
 pub enum UpdateStatus {
-    /// Repo was updated successfully.
+    /// Repo updated successfully.
     Updated(UpdateResult),
     /// Repo is pinned to a tag or commit — no automatic update.
     Pinned { ref_name: String },
@@ -633,7 +633,7 @@ pub fn update_repo(repo_key: &str, repo: &InstalledRepo) -> Result<UpdateStatus,
             let new_commit = read_head_commit(repo_path);
             let changed = old_commit.as_deref() != new_commit.as_deref();
 
-            // Re-discover plugins (new ones may have been added)
+            // Re-discover plugins: the pull may bring new ones
             let plugins = discover_plugins_in_dir(repo_path, subdir.as_deref())?;
 
             Ok(UpdateStatus::Updated(UpdateResult {

crates/codegen/kigi-agent/src/plugins/hooks_adapter.rs

@@ -296,7 +296,8 @@ mod tests {
     fn prefilter_handles_invalid_json() {
         let json = "not valid json{";
         let (filtered, skipped) = prefilter_unsupported_events(json);
-        assert_eq!(filtered, json); // returned as-is
+        // returned as-is
+        assert_eq!(filtered, json);
         assert!(skipped.is_empty());
     }
 
@@ -500,7 +501,7 @@ mod tests {
     /// reference resolves to the plugin root exactly once, and the result
     /// contains no leftover `$` placeholders. This is the contract the
     /// hooks_adapter has long held, and it must continue to hold
-    /// now that `parse_hook_file` itself does an env-expansion pass with
+    /// because `parse_hook_file` itself does an env-expansion pass with
     /// the per-hook `extra_env`. The first pass (in `parse_hook_file`)
     /// runs against an EMPTY `extra_env` for plugin hooks (the adapter
     /// only fills it in afterwards), so the placeholder survives that

crates/codegen/kigi-agent/src/plugins/install_registry.rs

@@ -297,7 +297,7 @@ impl InstallRegistry {
     }
 }
 
-// ── Errors ────────────────────────────────────────────────────────────
+// Errors
 
 #[derive(Debug, thiserror::Error)]
 pub enum InstallError {
@@ -323,7 +323,7 @@ pub enum InstallError {
     InstallFailed { detail: String },
 }
 
-// ── Tests ─────────────────────────────────────────────────────────────
+// Tests
 
 #[cfg(test)]
 mod tests {

crates/codegen/kigi-agent/src/plugins/manifest.rs

@@ -154,7 +154,7 @@ pub struct PluginManifest {
     #[serde(default)]
     pub keywords: Vec<String>,
 
-    // ── Component path overrides (supplement convention dirs) ──────
+    // Component path overrides (supplement convention dirs)
     #[serde(default)]
     pub skills: Option<PathOrPaths>,
     #[serde(default)]
@@ -247,7 +247,7 @@ impl PluginManifest {
 
     /// Log informational messages about manifest features.
     ///
-    /// Called during discovery. Inline hooks and MCP servers are now
+    /// Called during discovery. Inline hooks and MCP servers are
     /// fully supported; this method logs when they are detected.
     pub fn warn_unsupported_features(&self, plugin_name: &str) {
         if self.inline_hooks().is_some() {
@@ -287,7 +287,7 @@ fn resolve_dirs(
     }
 }
 
-// ── Manifest loading ──────────────────────────────────────────────────
+// Manifest loading
 
 /// Manifest search order within a plugin directory.
 const MANIFEST_PATHS: &[&str] = &[
@@ -375,7 +375,7 @@ pub fn normalize_inline_mcp_servers(value: &serde_json::Value) -> serde_json::Va
     serde_json::json!({ "mcpServers": inner })
 }
 
-// ── Errors ────────────────────────────────────────────────────────────
+// Errors
 
 #[derive(Debug, thiserror::Error)]
 pub enum ManifestError {
@@ -530,7 +530,8 @@ mod tests {
         );
         assert_eq!(
             name_from_dirname(Path::new("/path/to/---")),
-            None // all hyphens after trim
+            // all hyphens after trim
+            None
         );
     }
 

crates/codegen/kigi-agent/src/plugins/marketplace.rs

@@ -147,7 +147,7 @@ pub fn load_enabled_disabled_plugins(path: &Path) -> (Vec<String>, Vec<String>)
     parse_enabled_disabled_plugins(&json)
 }
 
-// ── Compat known_marketplaces.json ────────────────────────────────────
+// Compat known_marketplaces.json
 
 /// Entry in `~/.claude/plugins/known_marketplaces.json`.
 #[derive(serde::Deserialize)]

crates/codegen/kigi-agent/src/plugins/mod.rs

@@ -1,15 +1,9 @@
-//! Plugin system — discover, load, and manage plugins (including compat layouts).
+//! Plugin discovery, loading, and registry.
 //!
 //! A plugin is a self-contained directory that bundles skills, agents,
-//! MCP server configs, and hooks into a namespaced unit.  Plugins can
+//! MCP server configs, and hooks into a namespaced unit. Plugins can
 //! live under `~/.kigi/plugins/`, `.kigi/plugins/` (project-level),
 //! or be passed via `--plugin-dir` on the CLI.
-//!
-//! This module handles:
-//! - `manifest` — parsing `plugin.json` manifests
-//! - `discovery` — scanning the filesystem for plugin directories
-//! - `trust` — project-plugin trust management
-//! - `registry` — in-memory registry of active plugins
 
 pub mod discovery;
 pub mod git_install;

crates/codegen/kigi-agent/src/plugins/registry.rs

@@ -301,7 +301,7 @@ impl PluginRegistry {
     }
 }
 
-// ── Shared handle for cross-thread reload ─────────────────────────────
+// Shared handle for cross-thread reload
 
 /// Thread-safe handle for plugin registry lifecycle.
 ///
@@ -456,7 +456,7 @@ impl SharedPluginRegistryHandle {
     }
 }
 
-// ── Component counting helpers ────────────────────────────────────────
+// Component counting helpers
 
 /// Collect the SKILL.md paths that load from the given skill dirs.
 ///
@@ -793,9 +793,11 @@ mod tests {
             &["enabled-plugin".to_string()],
         );
 
-        assert_eq!(reg.len(), 2); // Both in registry
+        // Both in registry
+        assert_eq!(reg.len(), 2);
         let active = reg.active_plugins();
-        assert_eq!(active.len(), 1); // Only enabled one is active
+        // Only enabled one is active
+        assert_eq!(active.len(), 1);
         assert_eq!(active[0].name, "enabled-plugin");
 
         // Disabled one is in list but marked disabled
@@ -876,9 +878,12 @@ mod tests {
 
         let reg = PluginRegistry::from_discovered(plugins, &[], &[]);
         let list = reg.list();
-        assert_eq!(list[0].name, "alpha"); // CliOverride = 0
-        assert_eq!(list[1].name, "beta"); // Project = 1
-        assert_eq!(list[2].name, "zebra"); // User = 2
+        // CliOverride = 0
+        assert_eq!(list[0].name, "alpha");
+        // Project = 1
+        assert_eq!(list[1].name, "beta");
+        // User = 2
+        assert_eq!(list[2].name, "zebra");
     }
 
     #[test]
@@ -935,7 +940,7 @@ mod tests {
         assert_eq!(reg.mcp_server_owner("my-server"), Some("mcp-plugin"));
     }
 
-    // ── Combined disabled + untrusted scenarios ─────────────────
+    // Combined disabled + untrusted scenarios
 
     #[test]
     fn disabled_project_plugin_excluded_from_active_and_enabled() {
@@ -961,7 +966,7 @@ mod tests {
 
         let bad = reg.get("bad-plugin").unwrap();
         assert!(!bad.enabled);
-        // trusted is now propagated from discovery (was false for Project scope)
+        // trusted is propagated from discovery (was false for Project scope)
         assert!(!bad.trusted);
     }
 
@@ -1166,7 +1171,7 @@ mod tests {
         assert_eq!(config.disabled.len(), 2);
     }
 
-    // ── Security: trust propagation from discovery ──────────────
+    // Security: trust propagation from discovery
 
     #[test]
     fn untrusted_project_plugin_excluded_from_active_even_when_enabled() {
@@ -1174,12 +1179,14 @@ mod tests {
         // pre-populated enabledPlugins) but NOT trusted. It must NOT
         // appear in active_plugins() so its hooks never fire.
         let plugins = vec![
-            make_discovered("malicious", PluginScope::Project, false), // untrusted
+            // untrusted
+            make_discovered("malicious", PluginScope::Project, false),
         ];
         let reg = PluginRegistry::from_discovered(
             plugins,
             &[],
-            &["malicious".to_string()], // attacker got it into enabled list
+            // attacker got it into enabled list
+            &["malicious".to_string()],
         );
 
         // Plugin is enabled but not trusted

crates/codegen/kigi-agent/src/plugins/trust.rs

@@ -129,7 +129,8 @@ impl TrustStore {
             })?;
 
         if !self.trusted.remove(&canonical) {
-            return Ok(()); // wasn't trusted
+            // wasn't trusted
+            return Ok(());
         }
 
         // Rewrite the entire file without the revoked path
@@ -176,7 +177,7 @@ impl TrustStore {
         }
     }
 
-    // ── Internal ──────────────────────────────────────────────────────
+    // Internal
 
     fn read_trust_file(path: &Path) -> HashSet<PathBuf> {
         let file = match std::fs::File::open(path) {
@@ -208,7 +209,7 @@ impl TrustStore {
     }
 }
 
-// ── Errors ────────────────────────────────────────────────────────────
+// Errors
 
 #[derive(Debug, thiserror::Error)]
 pub enum TrustError {
@@ -320,7 +321,8 @@ mod tests {
         // This test checks the logic but can't easily mock $HOME.
         // We verify the function exists and returns a boolean.
         let result = TrustStore::is_config_path_auto_trusted(Path::new("/nonexistent/path"));
-        assert!(!result); // nonexistent path can't be canonicalized
+        // nonexistent path can't be canonicalized
+        assert!(!result);
     }
 
     #[test]