huskies: merge 858

server/src/pipeline_state/events.rs

@@ -21,21 +21,25 @@ pub trait TransitionSubscriber: Send + Sync {
     fn on_transition(&self, fired: &TransitionFired);
 }
 
+/// Collects [`TransitionSubscriber`]s and dispatches [`TransitionFired`] events to each.
 pub struct EventBus {
     subscribers: Vec<Box<dyn TransitionSubscriber>>,
 }
 
 impl EventBus {
+    /// Create an empty event bus with no subscribers.
     pub fn new() -> Self {
         Self {
             subscribers: Vec::new(),
         }
     }
 
+    /// Register a subscriber to receive all future transition events.
     pub fn subscribe<S: TransitionSubscriber + 'static>(&mut self, subscriber: S) {
         self.subscribers.push(Box::new(subscriber));
     }
 
+    /// Fire a transition event, calling every registered subscriber in order.
     pub fn fire(&self, event: TransitionFired) {
         for sub in &self.subscribers {
             sub.on_transition(&event);

server/src/pipeline_state/subscribers.rs

@@ -10,6 +10,7 @@ use super::{event_label, stage_dir_name, stage_label};
 // These are ready to wire into the event bus but not yet connected to the
 // actual subsystems. Suppress dead_code until consumers are migrated.
 
+/// Subscriber that logs pipeline transitions to the Matrix bot channel.
 #[allow(dead_code)]
 pub struct MatrixBotSubscriber;
 #[allow(dead_code)]
@@ -27,6 +28,7 @@ impl TransitionSubscriber for MatrixBotSubscriber {
     }
 }
 
+/// Subscriber that re-renders the filesystem `work/` directory on stage transitions.
 #[allow(dead_code)]
 pub struct FileRendererSubscriber;
 #[allow(dead_code)]
@@ -43,6 +45,7 @@ impl TransitionSubscriber for FileRendererSubscriber {
     }
 }
 
+/// Subscriber that writes stage updates to the pipeline-items data store.
 #[allow(dead_code)]
 pub struct PipelineItemsSubscriber;
 #[allow(dead_code)]
@@ -59,6 +62,7 @@ impl TransitionSubscriber for PipelineItemsSubscriber {
     }
 }
 
+/// Subscriber that promotes eligible backlog items when a story completes or is archived.
 #[allow(dead_code)]
 pub struct AutoAssignSubscriber;
 #[allow(dead_code)]
@@ -77,6 +81,7 @@ impl TransitionSubscriber for AutoAssignSubscriber {
     }
 }
 
+/// Subscriber that broadcasts stage transitions to all connected WebSocket clients.
 #[allow(dead_code)]
 pub struct WebUiBroadcastSubscriber;
 #[allow(dead_code)]

server/src/pipeline_state/transition.rs

@@ -51,6 +51,7 @@ pub enum PipelineEvent {
 
 // ── Per-node execution events ───────────────────────────────────────────────
 
+/// Events that drive per-node [`ExecutionState`] transitions (agent lifecycle).
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum ExecutionEvent {
     SpawnRequested { agent: AgentName },

server/src/pipeline_state/types.rs

@@ -7,18 +7,23 @@ use std::num::NonZeroU32;
 
 // ── Newtypes ────────────────────────────────────────────────────────────────
 
+/// Unique identifier for a pipeline work item (story, bug, spike, or refactor).
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct StoryId(pub String);
 
+/// Git branch name associated with a work item.
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct BranchName(pub String);
 
+/// A Git commit SHA (typically the merge commit written when a story lands on master).
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct GitSha(pub String);
 
+/// The name of the agent process handling a work item on a given node.
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct AgentName(pub String);
 
+/// Ed25519 public key (32 bytes) that uniquely identifies a huskies node in the mesh.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct NodePubkey(pub [u8; 32]);
 
@@ -191,6 +196,7 @@ pub struct PipelineItem {
 
 // ── Transition errors ───────────────────────────────────────────────────────
 
+/// Error returned when a pipeline event is not valid for the current stage.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub enum TransitionError {
     InvalidTransition { from_stage: String, event: String },