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).
This commit is contained in:
ZacharyZhang-NY committed 2026-07-23 16:55:39 -04:00
1 parent ff0fb56c67
commit a02b555e66
1458 files changed
+10729 -21750

No files matched your search

@@ -1,14 +1,9 @@
//! Subagent role and persona configuration types.
//!
//! These are the canonical definitions for `SubagentRole`, `SubagentPersona`,
//! and `PersonaIOField`. The shell re-exports them via
//! `kigi_shell::config::{SubagentRole, SubagentPersona, PersonaIOField}`.
//!
//! Methods that remain in `kigi-shell` (on `SubagentsConfig`):
//! - `discover_personas()` / `discover_roles()` — filesystem discovery
//! coupled to the shell's config resolution pipeline.
//! - `resolve()` — config layering (CLI > env > TOML > remote) is
//! shell-specific. This crate receives already-resolved maps.
//! These are the canonical definitions; the shell re-exports them via
//! `kigi_shell::config`. Filesystem discovery and config layering
//! (CLI > env > TOML > remote) stay in `kigi-shell` on `SubagentsConfig` —
//! this crate only ever sees already-resolved maps.
use kigi_tools::implementations::skills::discovery::extract_first_paragraph;
use std::path::PathBuf;
@@ -17,38 +12,29 @@ use serde::Deserialize;
/// A declarative subagent role definition from config.
///
/// Roles provide named presets that callers can reference via the
/// `subagent_type` field in the task tool. Each role can specify
/// a default capability mode, model override, and custom prompt.
/// Roles are named presets callers reference via the `subagent_type` field in
/// the task tool. Every default here can be overridden per-spawn.
#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
#[serde(default)]
pub struct SubagentRole {
/// Human-readable description of what this role does.
pub description: String,
/// Default capability mode for agents using this role.
/// One of: "read-only", "read-write", "execute", "all".
/// Can be overridden per-spawn via `capability_mode` in the task tool.
#[serde(default)]
pub default_capability_mode: Option<String>,
/// Model override for this role. If set, agents using this role
/// default to this model unless the spawn-time `model` override
/// is provided.
#[serde(default)]
pub model: Option<String>,
/// Default reasoning effort for this role (e.g. "low", "medium", "high").
/// Can be overridden per-spawn via `reasoning_effort` in the task tool.
/// One of: "low", "medium", "high".
#[serde(default)]
pub reasoning_effort: Option<String>,
/// Path to a prompt/instruction file (relative to workspace root).
/// Loaded at spawn time and prepended to the child's prompt as a
/// `<role-instructions>` block.
#[serde(default)]
pub prompt_file: Option<String>,
/// Default isolation mode ("none" or "worktree").
/// One of: "none", "worktree".
#[serde(default)]
pub default_isolation: Option<String>,
/// Base directory for resolving relative `prompt_file` references.
/// Set to the parent dir of the source `.toml` file during discovery.
/// Base directory for resolving a relative `prompt_file`: the parent dir
/// of the source `.toml`, filled in during discovery.
#[serde(skip)]
pub source_dir: Option<PathBuf>,
}
@@ -61,60 +47,49 @@ pub struct SubagentRole {
#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
#[serde(default)]
pub struct SubagentPersona {
/// Inline instruction text applied as a persona layer.
pub instructions: Option<String>,
/// Optional short description shown in persona summaries.
/// Falls back to first-paragraph extraction from `instructions`.
/// When absent, summaries fall back to the first paragraph of
/// `instructions`.
pub description: Option<String>,
/// Path to an instruction file (relative to workspace root).
/// Content is loaded at spawn time and merged with `instructions`.
/// If both are set, `instructions` is prepended before file content.
/// Loaded at spawn time and merged with `instructions`, which is prepended
/// before the file content when both are set.
pub instructions_file: Option<String>,
/// Declared inputs this persona expects. The parent agent reads these
/// to know what file paths or context to provide in the prompt.
#[serde(default)]
pub inputs: Vec<PersonaIOField>,
/// Declared outputs this persona produces. The parent agent reads
/// these to know what artifacts to expect and pass to the next agent.
#[serde(default)]
pub outputs: Vec<PersonaIOField>,
/// Default isolation mode when this persona is used.
/// One of: "none", "worktree".
#[serde(default)]
pub default_isolation: Option<String>,
/// Model override when this persona is used.
#[serde(default)]
pub model: Option<String>,
/// Default reasoning effort for this persona (e.g. "low", "medium", "high").
/// One of: "low", "medium", "high".
#[serde(default)]
pub reasoning_effort: Option<String>,
/// Base directory for resolving relative file references.
/// Set to the parent dir of the source `.toml` file during discovery.
/// When `None`, relative paths resolve against the workspace cwd.
/// Base directory for resolving relative file references: the parent dir
/// of the source `.toml`, filled in during discovery. When `None`,
/// relative paths resolve against the workspace cwd.
#[serde(skip)]
pub source_dir: Option<PathBuf>,
/// Absolute path to the source file this persona was loaded from.
/// Populated during discovery; `None` for inline config personas.
/// Absolute path of the source file, filled in during discovery. `None`
/// for personas declared inline in config.
#[serde(skip)]
pub source_path: Option<String>,
}
/// A declared input or output for a persona.
///
/// Enables the parent agent to discover what a persona needs (inputs)
/// and what it produces (outputs) without hardcoded knowledge of the
/// persona's protocol.
/// Lets the parent agent discover what a persona needs and what it produces
/// without hardcoded knowledge of the persona's protocol.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, serde::Serialize)]
#[serde(deny_unknown_fields)]
pub struct PersonaIOField {
/// Short identifier (e.g. "review_file", "summary_file").
pub name: String,
/// What kind of artifact: "file", "text", etc.
/// Kind of artifact: "file", "text", etc.
#[serde(default = "PersonaIOField::default_io_type")]
pub io_type: String,
/// Whether this input/output is required.
#[serde(default)]
pub required: bool,
/// Human-readable description shown in the task tool help.
pub description: String,
}
@@ -125,8 +100,8 @@ impl PersonaIOField {
}
impl SubagentPersona {
/// Render a human-readable summary of this persona's IO contract
/// for inclusion in the task tool description.
/// Renders this persona's IO contract as Markdown for the task tool
/// description.
pub fn render_io_summary(&self, name: &str) -> String {
let fallback;
let desc = if let Some(d) = self.description.as_deref().filter(|s| !s.trim().is_empty()) {