feat(934): typed Stage enum replaces directory-string state model

The state machine's `Stage` enum becomes the source of truth for pipeline
state. Six stages of work land together:

  1. Clean wire vocabulary (`coding`, `merge`, `merge_failure`, ...) replaces
     legacy directory-style strings (`2_current`, `4_merge`, ...) on the wire.
     `Stage::from_dir` accepted both during deployment; new writes always
     emit the clean form via `stage_dir_name`. Lexicographic `dir >= "5_done"`
     checks in lifecycle.rs become typed `matches!` checks since the new
     vocabulary doesn't sort in pipeline order.
  2. `crdt_state::write_item` takes typed `&Stage`, serialising via
     `stage_dir_name` at the CRDT boundary. `#[cfg(test)] write_item_str`
     parses legacy strings for test fixtures.
  3. `WorkItem::stage()` returns typed `crdt_state::Stage`; `stage_str()`
     is gone from the public API. Projection dispatches on the typed enum.
  4. `frozen` becomes an orthogonal CRDT register. `Stage::Frozen` and
     `PipelineEvent::Freeze`/`Unfreeze` are removed; `transition_to_frozen`/
     `unfrozen` set the flag directly without touching the stage register.
  5. Watcher sweep and `tool_update_story`'s `blocked` setter route through
     `apply_transition` so the typed transition table validates every
     stage change. `update_story` gains a `frozen` field for symmetry.
  6. One-shot startup migration rewrites pre-934 directory-style stage
     registers (and sets `frozen=true` on items previously at `7_frozen`).
     `Stage::from_dir` drops legacy aliases. The db boundary keeps a small
     normaliser so callers with legacy strings (MCP, tests) still work.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

server/src/service/agents/mod.rs

@@ -208,17 +208,23 @@ pub fn get_work_item_content(
             .map_err(|e| Error::Io(format!("Pipeline read error: {e}")))?;
         let stage = item
             .as_ref()
-            .map(|i| match &i.stage {
-                crate::pipeline_state::Stage::Upcoming => "upcoming",
-                crate::pipeline_state::Stage::Backlog => "backlog",
-                crate::pipeline_state::Stage::Coding => "current",
-                crate::pipeline_state::Stage::Blocked { .. } => "blocked",
-                crate::pipeline_state::Stage::Qa => "qa",
-                crate::pipeline_state::Stage::Merge { .. } => "merge",
-                crate::pipeline_state::Stage::MergeFailure { .. } => "merge_failure",
-                crate::pipeline_state::Stage::Done { .. } => "done",
-                crate::pipeline_state::Stage::Archived { .. } => "archived",
-                crate::pipeline_state::Stage::Frozen { .. } => "frozen",
+            .map(|i| {
+                // Frozen is now an orthogonal CRDT flag (story 934, stage 4).
+                if i.is_frozen() {
+                    "frozen"
+                } else {
+                    match &i.stage {
+                        crate::pipeline_state::Stage::Upcoming => "upcoming",
+                        crate::pipeline_state::Stage::Backlog => "backlog",
+                        crate::pipeline_state::Stage::Coding => "current",
+                        crate::pipeline_state::Stage::Blocked { .. } => "blocked",
+                        crate::pipeline_state::Stage::Qa => "qa",
+                        crate::pipeline_state::Stage::Merge { .. } => "merge",
+                        crate::pipeline_state::Stage::MergeFailure { .. } => "merge_failure",
+                        crate::pipeline_state::Stage::Done { .. } => "done",
+                        crate::pipeline_state::Stage::Archived { .. } => "archived",
+                    }
+                }
             })
             .unwrap_or("unknown")
             .to_string();
@@ -344,7 +350,7 @@ max_budget_usd = 5.0
             "---\nname: \"Foo Story\"\n---\n\nSome content.",
         );
         // Story 929: name lives in the CRDT register.
-        crate::crdt_state::write_item(
+        crate::crdt_state::write_item_str(
             "42_story_foo",
             "1_backlog",
             Some("Foo Story"),

server/src/service/gateway/polling.rs

@@ -54,8 +54,8 @@ mod tests {
     fn stage_transition_prefixes_project_name() {
         let event = StoredEvent::StageTransition {
             story_id: "42_story_my_feature".to_string(),
-            from_stage: "2_current".to_string(),
-            to_stage: "3_qa".to_string(),
+            from_stage: "coding".to_string(),
+            to_stage: "qa".to_string(),
             timestamp_ms: 1000,
         };
         let (plain, html) = format_gateway_event("huskies", &event);

server/src/service/notifications/format.rs

@@ -19,7 +19,6 @@ pub fn stage_display_name(stage: &str) -> &'static str {
         Some(Stage::Done { .. }) => "Done",
         Some(Stage::Archived { .. }) => "Archived",
         Some(Stage::MergeFailure { .. }) => "MergeFailure",
-        Some(Stage::Frozen { .. }) => "Frozen",
         None => "Unknown",
     }
 }
@@ -185,12 +184,12 @@ mod tests {
 
     #[test]
     fn stage_display_name_maps_all_known_stages() {
-        assert_eq!(stage_display_name("1_backlog"), "Backlog");
-        assert_eq!(stage_display_name("2_current"), "Current");
-        assert_eq!(stage_display_name("3_qa"), "QA");
-        assert_eq!(stage_display_name("4_merge"), "Merge");
-        assert_eq!(stage_display_name("5_done"), "Done");
-        assert_eq!(stage_display_name("6_archived"), "Archived");
+        assert_eq!(stage_display_name("backlog"), "Backlog");
+        assert_eq!(stage_display_name("coding"), "Current");
+        assert_eq!(stage_display_name("qa"), "QA");
+        assert_eq!(stage_display_name("merge"), "Merge");
+        assert_eq!(stage_display_name("done"), "Done");
+        assert_eq!(stage_display_name("archived"), "Archived");
         assert_eq!(stage_display_name("unknown"), "Unknown");
     }
 

server/src/service/notifications/io/tests_stage.rs

@@ -46,11 +46,11 @@ async fn stage_notification_uses_dynamic_room_ids() {
 
     watcher_tx
         .send(WatcherEvent::WorkItem {
-            stage: "3_qa".to_string(),
+            stage: "qa".to_string(),
             item_id: "10_story_foo".to_string(),
             action: "qa".to_string(),
             commit_msg: "huskies: qa 10_story_foo".to_string(),
-            from_stage: Some("2_current".to_string()),
+            from_stage: Some("coding".to_string()),
         })
         .unwrap();
 
@@ -88,11 +88,11 @@ async fn stage_notification_with_no_rooms_is_silent() {
 
     watcher_tx
         .send(WatcherEvent::WorkItem {
-            stage: "3_qa".to_string(),
+            stage: "qa".to_string(),
             item_id: "10_story_foo".to_string(),
             action: "qa".to_string(),
             commit_msg: "huskies: qa 10_story_foo".to_string(),
-            from_stage: Some("2_current".to_string()),
+            from_stage: Some("coding".to_string()),
         })
         .unwrap();
 
@@ -165,7 +165,7 @@ async fn synthetic_event_without_from_stage_does_not_notify() {
     // Synthetic reassign event within 4_merge — no actual stage change.
     watcher_tx
         .send(WatcherEvent::WorkItem {
-            stage: "4_merge".to_string(),
+            stage: "merge".to_string(),
             item_id: "549_story_skip_qa".to_string(),
             action: "reassign".to_string(),
             commit_msg: String::new(),
@@ -209,11 +209,11 @@ async fn skip_qa_shows_current_to_merge_not_qa_to_merge() {
     // Story skips QA: from_stage is 2_current, not 3_qa.
     watcher_tx
         .send(WatcherEvent::WorkItem {
-            stage: "4_merge".to_string(),
+            stage: "merge".to_string(),
             item_id: "549_story_skip_qa".to_string(),
             action: "merge".to_string(),
             commit_msg: "huskies: merge 549_story_skip_qa".to_string(),
-            from_stage: Some("2_current".to_string()),
+            from_stage: Some("coding".to_string()),
         })
         .unwrap();
 

server/src/service/status/format.rs

@@ -83,8 +83,8 @@ mod tests {
         let event = StatusEvent::StageTransition {
             story_id: "42_story_foo".to_string(),
             story_name: Some("Foo Story".to_string()),
-            from_stage: "4_merge".to_string(),
-            to_stage: "5_done".to_string(),
+            from_stage: "merge".to_string(),
+            to_stage: "done".to_string(),
         };
         let s = format_status_event(&event);
         assert!(
@@ -101,8 +101,8 @@ mod tests {
         let event = StatusEvent::StageTransition {
             story_id: "10_story_bar".to_string(),
             story_name: Some("Bar".to_string()),
-            from_stage: "1_backlog".to_string(),
-            to_stage: "2_current".to_string(),
+            from_stage: "backlog".to_string(),
+            to_stage: "coding".to_string(),
         };
         let s = format_status_event(&event);
         assert!(!s.contains("\u{1f389}"));
@@ -114,8 +114,8 @@ mod tests {
         let event = StatusEvent::StageTransition {
             story_id: "5_story_x".to_string(),
             story_name: None,
-            from_stage: "2_current".to_string(),
-            to_stage: "3_qa".to_string(),
+            from_stage: "coding".to_string(),
+            to_stage: "qa".to_string(),
         };
         let s = format_status_event(&event);
         assert!(s.contains("5_story_x"));
@@ -182,8 +182,8 @@ mod tests {
             StatusEvent::StageTransition {
                 story_id: "1_story_a".to_string(),
                 story_name: None,
-                from_stage: "1_backlog".to_string(),
-                to_stage: "2_current".to_string(),
+                from_stage: "backlog".to_string(),
+                to_stage: "coding".to_string(),
             },
             StatusEvent::MergeFailure {
                 story_id: "2_story_b".to_string(),

server/src/service/story/front_matter.rs

@@ -4,32 +4,19 @@
 //! without performing any I/O. Parsing is delegated to `crate::io::story_metadata`.
 
 #[allow(dead_code)]
-/// Return `true` if `stage` is a recognised pipeline stage directory name.
+/// Return `true` if `stage` is a recognised pipeline stage name.
 ///
-/// Valid stage names match the `.huskies/work/N_name/` directory scheme.
+/// Accepts both the clean post-934 wire form (e.g. `"backlog"`) and the
+/// legacy directory-style form (e.g. `"1_backlog"`).
 pub fn is_valid_stage(stage: &str) -> bool {
     crate::pipeline_state::Stage::from_dir(stage).is_some()
 }
 
 #[allow(dead_code)]
-/// Map a human-readable stage alias (e.g. `"backlog"`) to its directory name
-/// (e.g. `"1_backlog"`). Returns `None` for unrecognised aliases.
+/// Map any recognised stage alias (clean wire form or legacy directory form)
+/// to the canonical clean wire form. Returns `None` for unrecognised aliases.
 pub fn stage_alias_to_dir(alias: &str) -> Option<&'static str> {
-    use crate::pipeline_state::Stage;
-    // Canonical directory names (e.g. "1_backlog") round-trip through the typed enum.
-    if let Some(stage) = Stage::from_dir(alias) {
-        return Some(stage.dir_name());
-    }
-    // Short human-readable aliases (user-facing input normalization).
-    match alias {
-        "backlog" => Some("1_backlog"),
-        "current" => Some("2_current"),
-        "qa" => Some("3_qa"),
-        "merge" => Some("4_merge"),
-        "done" => Some("5_done"),
-        "archived" => Some("6_archived"),
-        _ => None,
-    }
+    crate::pipeline_state::Stage::from_dir(alias).map(|s| s.dir_name())
 }
 
 // ── Tests ─────────────────────────────────────────────────────────────────────
@@ -40,36 +27,42 @@ mod tests {
 
     #[test]
     fn is_valid_stage_accepts_all_known_stages() {
-        assert!(is_valid_stage("1_backlog"));
-        assert!(is_valid_stage("2_current"));
-        assert!(is_valid_stage("3_qa"));
-        assert!(is_valid_stage("4_merge"));
-        assert!(is_valid_stage("5_done"));
-        assert!(is_valid_stage("6_archived"));
+        // Clean post-934 vocabulary.
+        assert!(is_valid_stage("backlog"));
+        assert!(is_valid_stage("coding"));
+        assert!(is_valid_stage("qa"));
+        assert!(is_valid_stage("merge"));
+        assert!(is_valid_stage("done"));
+        assert!(is_valid_stage("archived"));
     }
 
     #[test]
     fn is_valid_stage_rejects_unknown() {
-        assert!(!is_valid_stage("current"));
-        assert!(!is_valid_stage("backlog"));
+        // Story 934 stage 6 dropped legacy directory-style aliases.
+        assert!(!is_valid_stage("current")); // pre-934 short alias, no longer mapped
+        assert!(!is_valid_stage("1_backlog"));
+        assert!(!is_valid_stage("2_current"));
         assert!(!is_valid_stage("7_future"));
         assert!(!is_valid_stage(""));
     }
 
     #[test]
     fn stage_alias_maps_short_names() {
-        assert_eq!(stage_alias_to_dir("backlog"), Some("1_backlog"));
-        assert_eq!(stage_alias_to_dir("current"), Some("2_current"));
-        assert_eq!(stage_alias_to_dir("qa"), Some("3_qa"));
-        assert_eq!(stage_alias_to_dir("merge"), Some("4_merge"));
-        assert_eq!(stage_alias_to_dir("done"), Some("5_done"));
-        assert_eq!(stage_alias_to_dir("archived"), Some("6_archived"));
+        assert_eq!(stage_alias_to_dir("backlog"), Some("backlog"));
+        assert_eq!(stage_alias_to_dir("coding"), Some("coding"));
+        assert_eq!(stage_alias_to_dir("qa"), Some("qa"));
+        assert_eq!(stage_alias_to_dir("merge"), Some("merge"));
+        assert_eq!(stage_alias_to_dir("done"), Some("done"));
+        assert_eq!(stage_alias_to_dir("archived"), Some("archived"));
     }
 
     #[test]
-    fn stage_alias_maps_full_dir_names() {
-        assert_eq!(stage_alias_to_dir("1_backlog"), Some("1_backlog"));
-        assert_eq!(stage_alias_to_dir("6_archived"), Some("6_archived"));
+    fn stage_alias_returns_none_for_legacy_dir_names() {
+        // Story 934 stage 6: legacy directory-style aliases are no longer
+        // recognised — startup migration rewrites stored CRDT values, and
+        // user-facing aliases now use only the clean wire vocabulary.
+        assert_eq!(stage_alias_to_dir("1_backlog"), None);
+        assert_eq!(stage_alias_to_dir("6_archived"), None);
     }
 
     #[test]

server/src/service/work_item/assign.rs

@@ -56,7 +56,7 @@ mod tests {
         let story_id = "8770_story_assign_regression_crdt";
 
         // Seed the CRDT so set_agent can find the item.
-        crate::crdt_state::write_item(
+        crate::crdt_state::write_item_str(
             story_id,
             "2_current",
             Some("Assign Regression"),
@@ -98,7 +98,7 @@ mod tests {
         let story_id_b = "8772_story_assign_path_b";
 
         for sid in &[story_id_a, story_id_b] {
-            crate::crdt_state::write_item(
+            crate::crdt_state::write_item_str(
                 sid,
                 "2_current",
                 Some("Path Test"),

server/src/service/work_item/delete.rs

@@ -195,7 +195,7 @@ mod tests {
         let story_id = "8750_story_service_delete_regression";
 
         // Seed CRDT.
-        crate::crdt_state::write_item(
+        crate::crdt_state::write_item_str(
             story_id,
             "1_backlog",
             Some("Service Delete Regression"),

server/src/service/work_item/freeze.rs

@@ -28,10 +28,8 @@ pub enum UnfreezeStatus {
 /// stage without making any CRDT writes.  Returns `Err` if the state transition
 /// fails (e.g. the item is not found or is in a terminal stage).
 pub fn freeze(story_id: &str) -> Result<FreezeStatus, String> {
-    let already_frozen = crate::pipeline_state::read_typed(story_id)
-        .ok()
-        .flatten()
-        .map(|i| i.stage.is_frozen())
+    let already_frozen = crate::crdt_state::read_item(story_id)
+        .map(|view| view.frozen())
         .unwrap_or(false);
 
     if already_frozen {
@@ -45,13 +43,11 @@ pub fn freeze(story_id: &str) -> Result<FreezeStatus, String> {
 
 /// Unfreeze a work item, resuming normal pipeline behaviour.
 ///
-/// Returns [`UnfreezeStatus::NotFrozen`] if the item is not currently in the
-/// frozen stage.  Returns `Err` if the state transition fails.
+/// Returns [`UnfreezeStatus::NotFrozen`] if the item is not currently frozen.
+/// Returns `Err` if the state transition fails.
 pub fn unfreeze(story_id: &str) -> Result<UnfreezeStatus, String> {
-    let is_frozen = crate::pipeline_state::read_typed(story_id)
-        .ok()
-        .flatten()
-        .map(|i| i.stage.is_frozen())
+    let is_frozen = crate::crdt_state::read_item(story_id)
+        .map(|view| view.frozen())
         .unwrap_or(false);
 
     if !is_frozen {
@@ -92,7 +88,7 @@ mod tests {
             .expect("read_typed should succeed")
             .expect("item should be present");
         assert!(
-            item.stage.is_frozen(),
+            item.is_frozen(),
             "stage should be Frozen after freeze: {:?}",
             item.stage
         );
@@ -141,7 +137,7 @@ mod tests {
             .expect("read_typed should succeed")
             .expect("item should be present");
         assert!(
-            !item.stage.is_frozen(),
+            !item.is_frozen(),
             "stage should not be Frozen after unfreeze: {:?}",
             item.stage
         );
@@ -212,12 +208,12 @@ mod tests {
             .expect("MCP-path item should be in CRDT");
 
         assert!(
-            state_a.stage.is_frozen(),
+            state_a.is_frozen(),
             "chat-path CRDT stage must be frozen: {:?}",
             state_a.stage
         );
         assert!(
-            state_b.stage.is_frozen(),
+            state_b.is_frozen(),
             "MCP-path CRDT stage must be frozen: {:?}",
             state_b.stage
         );