huskies: merge 858

server/src/service/agents/mod.rs

@@ -7,7 +7,9 @@
 //!
 //! Conventions: `docs/architecture/service-modules.md`
 mod io;
+/// Agent selection heuristics — pick the best agent for a story.
 pub mod selection;
+/// Token usage tracking and budget enforcement.
 pub mod token;
 
 use crate::agents::AgentInfo;

server/src/service/bot_command/mod.rs

@@ -11,6 +11,7 @@
 //! - `io.rs` — all side-effectful calls (transport handlers, stores, agent pool)
 
 pub(super) mod io;
+/// Pure argument parsing for bot slash commands.
 pub mod parse;
 
 use crate::agents::AgentPool;

server/src/service/common/mod.rs

@@ -3,4 +3,5 @@
 //! All sub-modules here are pure (no I/O, no side effects). Any helper that
 //! duplicates logic across two or more service modules belongs here; anything
 //! used by only one service stays in that service.
+/// Story/bug/spike ID extraction and formatting helpers.
 pub mod item_id;

server/src/service/diagnostics/mod.rs

@@ -6,7 +6,9 @@
 //! - `io.rs` — the ONLY place that performs side effects (filesystem reads/writes)
 //! - `permission.rs` — pure permission-rule generation and wildcard checks
 
+/// Side-effectful diagnostics I/O — log reads, CRDT dumps, filesystem writes.
 pub mod io;
+/// Pure permission-rule generation and wildcard matching.
 pub mod permission;
 
 #[allow(unused_imports)]

server/src/service/events/mod.rs

@@ -6,6 +6,7 @@
 //!
 //! Conventions: `docs/architecture/service-modules.md`
 
+/// Bounded in-memory event ring buffer for SSE streaming.
 pub mod buffer;
 pub(super) mod io;
 

server/src/service/gateway/mod.rs

@@ -7,9 +7,12 @@
 //! - `aggregation.rs` — pure cross-project pipeline formatting
 //! - `polling.rs` — pure notification event formatting
 
+/// Cross-project pipeline status aggregation and formatting.
 pub mod aggregation;
+/// Gateway configuration types and TOML parsing.
 pub mod config;
 pub(crate) mod io;
+/// Notification event polling for gateway-level broadcasts.
 pub mod polling;
 
 pub use aggregation::format_aggregate_status_compact;

server/src/service/git_ops/mod.rs

@@ -7,8 +7,11 @@
 //! - `path_guard.rs` — pure path-prefix safety checks
 //! - `porcelain.rs` — pure git porcelain output parsers
 
+/// Side-effectful git command execution (add, commit, diff, log, status).
 pub mod io;
+/// Pure worktree path-prefix safety checks.
 pub mod path_guard;
+/// Pure git porcelain output parsers.
 pub mod porcelain;
 
 #[allow(unused_imports)]

server/src/service/merge/mod.rs

@@ -6,7 +6,9 @@
 //! - `io.rs` — the ONLY place that performs side effects
 //! - `status.rs` — pure merge-status message formatting
 
+/// Side-effectful merge I/O — rebase, cherry-pick, and branch operations.
 pub mod io;
+/// Pure merge-status message formatting.
 pub mod status;
 
 #[allow(unused_imports)]

server/src/service/mod.rs

@@ -5,25 +5,47 @@
 //! - `mod.rs` orchestrates and owns the typed `Error` type
 //! - `io.rs` is the only file that performs side effects
 //! - Topic-named pure files contain branching logic with no I/O
+/// Agent management — start, stop, inspect, and list agents.
 pub mod agents;
+/// Anthropic API key storage and model listing.
 pub mod anthropic;
+/// Bot command dispatch — parses and executes slash commands.
 pub mod bot_command;
+/// Shared pure helpers used across service modules.
 pub mod common;
+/// Diagnostics — server logs, CRDT dump, and permission management.
 pub mod diagnostics;
+/// Pipeline event buffer for SSE streaming.
 pub mod events;
+/// File I/O — path validation, read, write, and listing.
 pub mod file_io;
+/// Gateway — multi-project proxy domain logic.
 pub mod gateway;
+/// Git operations — worktree-scoped git commands.
 pub mod git_ops;
+/// Merge — rebase agent work onto master and validate.
 pub mod merge;
+/// Notifications — fan-out pipeline events to chat transports.
 pub mod notifications;
+/// OAuth 2.0 PKCE flow for Anthropic authentication.
 pub mod oauth;
+/// Pipeline status aggregation helpers.
 pub mod pipeline;
+/// Project open/close/list domain logic.
 pub mod project;
+/// QA — request, approve, and reject code reviews.
 pub mod qa;
+/// Project settings read/write and validation.
 pub mod settings;
+/// Shell command safety, sandboxing, and output helpers.
 pub mod shell;
+/// Status broadcaster — unified event fan-out to all consumers.
 pub mod status;
+/// Story CRUD — create, update, move, and manage work items.
 pub mod story;
+/// Timer — deferred agent start via one-shot timers.
 pub mod timer;
+/// Wizard — multi-step project setup domain logic.
 pub mod wizard;
+/// WebSocket — real-time pipeline updates and permission prompts.
 pub mod ws;

server/src/service/oauth/mod.rs

@@ -7,8 +7,10 @@
 //! - `pkce.rs` — pure PKCE helpers: generation, challenge, encoding
 //! - `flow.rs` — pure flow types and token-expiry decision logic
 
+/// Pure OAuth flow types and token-expiry decision logic.
 pub mod flow;
 pub(super) mod io;
+/// Pure PKCE helpers — code verifier generation, challenge derivation, base64url encoding.
 pub mod pkce;
 
 pub use flow::AccountInfo;

server/src/service/project/mod.rs

@@ -7,6 +7,7 @@
 //! Conventions: `docs/architecture/service-modules.md`
 
 pub(super) mod io;
+/// Pure project selection and path-matching logic.
 pub mod selection;
 
 use crate::state::SessionState;

server/src/service/qa/mod.rs

@@ -6,7 +6,9 @@
 //! - `io.rs` — the ONLY place that performs side effects (git, TCP, process)
 //! - `lifecycle.rs` — pure QA routing decisions (spike vs. normal story)
 
+/// Side-effectful QA I/O — git operations, port scanning, branch merging.
 pub mod io;
+/// Pure QA routing decisions (spike vs. normal story).
 pub mod lifecycle;
 
 pub use io::{find_free_port, merge_spike_branch_to_master};

server/src/service/settings/mod.rs

@@ -9,7 +9,9 @@
 //! - `validate.rs` — pure validation: [`validate_project_settings`]
 
 pub(super) mod io;
+/// Pure types: `ProjectSettings`, TOML serialization, config merging.
 pub mod project;
+/// Pure project-settings validation rules.
 pub mod validate;
 
 pub use project::{ProjectSettings, merge_settings_into_toml, settings_from_config};

server/src/service/shell/mod.rs

@@ -6,7 +6,9 @@
 //! - `io.rs` — the ONLY place that performs side effects (filesystem checks)
 //! - `path_guard.rs` — pure command-safety checks and output utilities
 
+/// Side-effectful shell I/O — filesystem permission checks.
 pub mod io;
+/// Pure command-safety checks, blocked-binary lists, and output truncation.
 pub mod path_guard;
 
 #[allow(unused_imports)]

server/src/service/status/mod.rs

@@ -23,7 +23,9 @@
 //! - Story 643 (Web UI): calls `subscribe()` once at startup.
 //! - Story 644 (chat transports): calls `subscribe()` once per transport.
 
+/// Bounded ring buffer for recent status events.
 pub mod buffer;
+/// Pure status-event to human-readable string formatting.
 pub mod format;
 
 use chrono::{DateTime, Utc};

server/src/service/story/mod.rs

@@ -31,10 +31,15 @@
 //! - `pipeline_items` row — updated on stage transitions and item creation/deletion
 //! - `content_store` entry — updated on story content changes, deleted on purge/delete
 
+/// Pure criterion parsing, checkbox toggling, and validation.
 pub mod criteria;
+/// Pure front-matter field validation (stage names, agent assignments).
 pub mod front_matter;
+/// Side-effectful story file I/O — read, write, move, and delete.
 pub mod io;
+/// Pure story-ID helpers and lifecycle state transitions.
 pub mod lifecycle;
+/// Pure story content validation rules.
 pub mod validation;
 
 pub use criteria::parse_test_cases;

server/src/service/wizard/mod.rs

@@ -7,6 +7,7 @@
 //!   step classification — all unit-testable without tempdirs or an async runtime
 
 pub(crate) mod io;
+/// Pure wizard state-machine helpers — bare-project detection, step classification.
 pub mod state_machine;
 
 use crate::io::wizard::{StepStatus, WizardState, WizardStep, format_wizard_state};

server/src/service/ws/message/mod.rs

@@ -4,8 +4,11 @@
 //! Conversions from domain events to WsResponse live here too.
 //! All logic is pure data transformation; I/O lives in `io.rs`.
 
+/// Conversions from domain events to `WsResponse` frames.
 pub mod convert;
+/// Client-to-server `WsRequest` message definitions.
 pub mod request;
+/// Server-to-client `WsResponse` message definitions.
 pub mod response;
 
 pub use convert::{needs_pipeline_refresh, wizard_steps_to_info};

server/src/service/ws/mod.rs

@@ -9,9 +9,12 @@
 //! - `dispatch.rs` — pure request routing and permission resolution
 //! - `error.rs` — typed error enum
 
+/// Pure request routing and permission resolution.
 pub mod dispatch;
+/// Typed WebSocket error enum.
 pub mod error;
 pub(super) mod io;
+/// Pure WebSocket message types and domain-event conversions.
 pub mod message;
 
 pub use dispatch::{