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-update/tests/common/artifact_server.rs

@@ -277,7 +277,7 @@ fn handle_connection(
     let range = parse_range(&request);
     let addr = stream.local_addr().unwrap();
 
-    // ── Metadata routes ─────────────────────────────────────────────────────
+    // Metadata routes
     if path == "/releases/latest" {
         let latest = state.lock().unwrap().latest.clone();
         let body = release_json(&addr, &latest);
@@ -290,7 +290,7 @@ fn handle_connection(
         return;
     }
 
-    // ── Asset routes: /dl/{version}/{name} ──────────────────────────────────
+    // Asset routes: /dl/{version}/{name}
     let Some(rest) = path.strip_prefix("/dl/") else {
         write_simple_response(&mut stream, "404 Not Found", b"not found", is_head);
         return;
@@ -330,7 +330,7 @@ fn handle_connection(
         return;
     }
 
-    // ── Archive body with corruption modes ──────────────────────────────────
+    // Archive body with corruption modes
     // Count only body-serving GETs; the parallel path's HEAD probe is excluded.
     if !is_head {
         gets.fetch_add(1, Ordering::Relaxed);

crates/codegen/kigi-update/tests/common/mod.rs

@@ -22,7 +22,8 @@
 //! }
 //! ```
 
-#![allow(dead_code)] // each test binary uses a different subset
+// each test binary uses a different subset
+#![allow(dead_code)]
 
 #[cfg(unix)]
 pub mod artifact_server;
@@ -31,9 +32,7 @@ use std::ffi::OsString;
 use std::path::{Path, PathBuf};
 use std::sync::OnceLock;
 
-// ─────────────────────────────────────────────────────────────────────────────
 // KIGI_SHARE_DIR isolation
-// ─────────────────────────────────────────────────────────────────────────────
 
 /// Returns a process-wide test `KIGI_SHARE_DIR`, initialized exactly once per test
 /// binary. Once initialized, `kigi_config::kigi_home()` will resolve to
@@ -92,9 +91,7 @@ pub fn set_update_base(base: &str) {
     unsafe { std::env::set_var(kigi_env::UPDATE_BASE_URL_ENV, base) };
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // Install-test fixtures
-// ─────────────────────────────────────────────────────────────────────────────
 
 /// Host `{os}-{arch}` string matching the versioned binary naming scheme
 /// (`kigi-{version}-{platform}`).
@@ -193,7 +190,6 @@ pub fn backdate_downloads() {
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // GitHub Releases fixtures
 //
 // Wire shapes mirror the real GitHub REST API
@@ -203,7 +199,6 @@ pub fn backdate_downloads() {
 //   GET /repos/{o}/{r}/releases             → array of release objects
 // Release object: {"tag_name":"v0.1.0","assets":[{"name":"...",
 // "browser_download_url":"..."}]}
-// ─────────────────────────────────────────────────────────────────────────────
 
 /// Build a tar.gz archive from `(name, bytes)` entries.
 #[cfg(unix)]
@@ -299,9 +294,7 @@ pub async fn mount_latest(server: &wiremock::MockServer, version: &str) {
         .await;
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // PATH-override fake binary (used by the install.sh harness)
-// ─────────────────────────────────────────────────────────────────────────────
 
 /// RAII guard that places a sh-script with name `name` at the head of `PATH`.
 /// Restores `PATH` on drop.

crates/codegen/kigi-update/tests/test_blitz_cancel.rs

@@ -33,9 +33,7 @@ use common::{
 };
 use kigi_update::auto_update::install_internal_from_base;
 
-// ─────────────────────────────────────────────────────────────────────────────
 // Artifacts + fixtures
-// ─────────────────────────────────────────────────────────────────────────────
 
 /// A real executable whose ARCHIVE clears the 16 MiB parallel threshold (at
 /// least 2 chunks), so the parallel byte-range path is exercised. The shell
@@ -174,9 +172,7 @@ async fn run_one(
     assert_invariant(home, &prev_good, &new_binary, expect);
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // Deterministic matrix — single-connection path (small archive)
-// ─────────────────────────────────────────────────────────────────────────────
 
 #[tokio::test(flavor = "multi_thread")]
 #[serial]
@@ -224,9 +220,7 @@ async fn blitz_single_connection_matrix() {
     run_one(&server, Mode::Full, "0.1.182", None).await;
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // Deterministic matrix — parallel byte-range path (>= 16 MiB archive)
-// ─────────────────────────────────────────────────────────────────────────────
 
 #[tokio::test(flavor = "multi_thread")]
 #[serial]
@@ -269,10 +263,8 @@ async fn blitz_parallel_path_matrix() {
     run_one(&server, Mode::Full, "0.1.182", None).await;
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // Checksum + smoke-test rejections keep previous-good, then recover WITHOUT
 // a reset in between.
-// ─────────────────────────────────────────────────────────────────────────────
 
 #[tokio::test(flavor = "multi_thread")]
 #[serial]
@@ -312,9 +304,7 @@ async fn smoke_and_checksum_failures_keep_previous_good_then_recover() {
     assert_invariant(home, &prev_good, &new_binary, Expect::NewBinary);
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // Bounded randomized fuzz (CI) + ignored stress (1e5+ iterations).
-// ─────────────────────────────────────────────────────────────────────────────
 
 /// Cheap deterministic PRNG so the fuzz needs no extra dependency.
 struct Rng(u64);

crates/codegen/kigi-update/tests/test_install_internal.rs

@@ -31,9 +31,7 @@ fn base(server: &MockServer) -> String {
     format!("{}/releases", server.uri())
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // Happy-path
-// ─────────────────────────────────────────────────────────────────────────────
 
 #[tokio::test]
 #[serial]
@@ -207,9 +205,7 @@ async fn install_removes_legacy_links() {
     assert!(bin_dir.join("kigi").is_symlink(), "kigi link installed");
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // Failure paths
-// ─────────────────────────────────────────────────────────────────────────────
 
 #[tokio::test]
 #[serial]
@@ -447,10 +443,8 @@ async fn install_swap_failure_leaves_prior_install_active() {
     );
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // Rollback semantics: pinned installs move DOWN as well as up (the release
 // channel is authoritative for the internal installer).
-// ─────────────────────────────────────────────────────────────────────────────
 
 #[tokio::test]
 #[serial]
@@ -479,9 +473,7 @@ async fn install_rollback_then_upgrade_sequence() {
     }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // Cleanup integration: install v1..v3, verify N-1 retention.
-// ─────────────────────────────────────────────────────────────────────────────
 
 #[tokio::test]
 #[serial]

crates/codegen/kigi-update/tests/test_install_sh.rs

@@ -168,11 +168,9 @@ fn install_sh_happy_path_installs_versioned_binary_and_symlink() {
         "symlink must be relative (survives bind-mounted homes)"
     );
 
-    // The active link runs.
     let status = Command::new(&link).arg("--version").status().unwrap();
     assert!(status.success(), "installed kigi must run");
 
-    // Resolved the latest endpoint (no pinned version).
     assert!(
         fx.curl_log().contains("/latest"),
         "must resolve via /latest: {}",
@@ -255,7 +253,6 @@ fn install_sh_fails_when_release_lacks_platform_asset() {
         return;
     }
     let fx = Fixture::new("0.1.5", &small_good_artifact(), None);
-    // Rewrite release.json without the platform archive asset.
     let json = serde_json::json!({
         "tag_name": "v0.1.5",
         "assets": [
@@ -282,9 +279,8 @@ fn install_sh_fails_when_archive_lacks_kigi_binary() {
         return;
     }
     let fx = Fixture::new("0.1.5", &small_good_artifact(), None);
-    // Replace the archive with one that has no `kigi` entry; keep the
-    // manifest consistent so the checksum gate passes and the extraction
-    // check is what trips.
+    // The manifest hash is kept consistent so the checksum gate passes and the
+    // extraction check is what trips.
     let archive = common::make_tar_gz(&[("LICENSE", b"license only")]);
     std::fs::write(
         fx.dir.path().join("SHA256SUMS"),

crates/codegen/kigi-update/tests/test_io.rs

@@ -29,9 +29,7 @@ fn reset() {
     reset_home();
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // write_version_cache
-// ─────────────────────────────────────────────────────────────────────────────
 
 #[tokio::test]
 #[serial]
@@ -130,10 +128,8 @@ async fn write_version_cache_records_recent_timestamp() {
     );
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // is_version_cache_fresh — exercised via the public re-export. Each scenario
 // writes the file directly so we can control the timestamp.
-// ─────────────────────────────────────────────────────────────────────────────
 
 /// Write a `KigiVersion`-shaped JSON file with an arbitrary timestamp.
 fn write_cache_with_timestamp(version: &str, ts: time::OffsetDateTime) {
@@ -217,9 +213,7 @@ async fn version_cache_missing_file_is_not_fresh() {
     );
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // version.json wire format — the on-disk file is read by every kigi launch.
-// ─────────────────────────────────────────────────────────────────────────────
 
 #[tokio::test]
 #[serial]
@@ -276,12 +270,10 @@ async fn write_version_cache_idempotent_for_same_version() {
     assert_eq!(v1["version"], "0.1.180");
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // get_installed_kigi_version env override
 //
 // The function honors `KIGI_TEST_VERSION` for testing. We exercise it
 // via the public re-export only — no private items leaked.
-// ─────────────────────────────────────────────────────────────────────────────
 //
 // Note: `get_installed_kigi_version` is not re-exported from `lib.rs`, but
 // it's `pub` from `version` module and accessible via `version::`.

crates/codegen/kigi-update/tests/test_network.rs

@@ -26,9 +26,7 @@ fn tag_json(tag: &str) -> serde_json::Value {
     serde_json::json!({ "tag_name": tag, "draft": false, "prerelease": false, "assets": [] })
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // Happy-path tests (fast, no retries triggered).
-// ─────────────────────────────────────────────────────────────────────────────
 
 #[tokio::test]
 async fn latest_release_returns_version_on_success() {
@@ -217,10 +215,8 @@ async fn base_url_trailing_slash_is_tolerated() {
     assert_eq!(release.version().unwrap(), "0.1.181");
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Retry behavior — these tests intentionally exercise the 1s+2s+4s backoff,
+// Retry behavior — these tests deliberately exercise the 1s+2s+4s backoff,
 // so each takes up to ~7 seconds. They run in parallel.
-// ─────────────────────────────────────────────────────────────────────────────
 
 #[tokio::test]
 async fn latest_release_retries_on_5xx_then_succeeds() {
@@ -320,10 +316,8 @@ async fn latest_release_connection_refused_is_retried_and_returns_error() {
     );
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // download_silent — same body shape as download_with_progress but no
 // progress bar to capture.
-// ─────────────────────────────────────────────────────────────────────────────
 
 #[tokio::test]
 async fn download_silent_writes_body_to_dest() {
@@ -540,10 +534,8 @@ async fn download_silent_to_nonexistent_parent_dir_fails() {
     );
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // download_with_progress — same contract; covers the spinner path
 // (no Content-Length) and the progress-bar path (with Content-Length).
-// ─────────────────────────────────────────────────────────────────────────────
 
 #[tokio::test]
 async fn download_with_progress_writes_body_with_content_length() {
@@ -604,10 +596,8 @@ async fn download_with_progress_atomic_rename() {
     assert!(!dest.with_extension("tmp").exists());
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // Parallel byte-range path — exercises the HEAD + 206 Partial Content code path
 // in download_silent / download_with_progress for files >= 16 MiB.
-// ─────────────────────────────────────────────────────────────────────────────
 
 /// Wiremock responder for `GET` that honors `Range: bytes=A-B` with `206`.
 /// Without a Range header it returns the full body with `200`.

crates/codegen/kigi-update/tests/test_update_flows.rs

@@ -95,10 +95,8 @@ fn setup(server: &ArtifactServer, latest: &str, running: &str) {
     set_test_version(running);
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // Convergence: ensure_latest_on_disk downloads once, then every subsequent
 // pass (the leader's hourly re-entry) converges without re-downloading.
-// ─────────────────────────────────────────────────────────────────────────────
 
 #[tokio::test]
 #[serial]
@@ -207,9 +205,7 @@ async fn run_update_rolls_back_when_latest_moved_backwards() {
     assert_eq!(server.request_count(), 1);
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // Disk-version probe
-// ─────────────────────────────────────────────────────────────────────────────
 
 #[tokio::test]
 #[serial]
@@ -288,9 +284,7 @@ async fn ensure_latest_repairs_dangling_symlink_by_downloading() {
     );
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // check_update_status (`kigi update --check`)
-// ─────────────────────────────────────────────────────────────────────────────
 
 #[tokio::test]
 #[serial]
@@ -369,9 +363,7 @@ async fn check_status_unsupported_channel_reports_error() {
     );
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // run_update_if_available — the auto-update opt-out gate.
-// ─────────────────────────────────────────────────────────────────────────────
 
 #[tokio::test]
 #[serial]
@@ -399,11 +391,9 @@ async fn run_update_if_available_respects_auto_update_false() {
     assert!(!ran, "auto_update=false must suppress the update entirely");
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
 // Race integrity: the accepted same-instant race must stay harmless. Two (or
 // three) installers running concurrently — even for DIFFERENT versions —
 // must never leave a corrupt active binary.
-// ─────────────────────────────────────────────────────────────────────────────
 
 async fn run_concurrent_installs(
     server: &ArtifactServer,