refactor: consolidate phase transition logic and update docs

Phase Transition Consolidation (METIS-T-0056):
- Add single source of truth methods to DocumentType in types.rs:
  valid_transitions_from(), can_transition(), next_phase(), phase_sequence()
- Update PhaseTransitionService to delegate to DocumentType
- Update all document can_transition_to() implementations to delegate
- Update MCP transition_phase tool to use DocumentType::phase_sequence()

Documentation Fixes:
- Fix instructions.md: forward-only transitions, add Strategy, fix prefix
  length (2-8 chars), add risk_level critical option
- Fix phase-transitions/SKILL.md: remove bidirectional arrows
- Fix phase-flow.md: clarify forward-only with blocked exception

Plugin Restructure:
- Move skill/ to plugins/metis/ with improved organization
- Update marketplace.json source path

Version: 1.0.10

Author: Dylan Storey

.claude-plugin/marketplace.json

@@ -7,9 +7,9 @@
   "plugins": [
     {
       "name": "metis",
-      "source": "./skill",
+      "source": "./plugins/metis",
       "description": "Flight Levels methodology for project and work management. Teaches when and why to use Metis tools for project planning, work decomposition, and phase management.",
-      "version": "1.0.0"
+      "version": "1.0.10"
     }
   ]
 }

.metis/backlog/tech-debt/METIS-T-0056.md

@@ -0,0 +1,83 @@
+---
+id: consolidate-phase-transition
+level: task
+title: "Consolidate phase transition validation logic"
+short_code: "METIS-T-0056"
+created_at: 2026-01-12T13:13:49.387803+00:00
+updated_at: 2026-01-12T17:33:38.770114+00:00
+parent: 
+blocked_by: []
+archived: false
+
+tags:
+  - "#task"
+  - "#tech-debt"
+  - "#phase/completed"
+
+
+exit_criteria_met: false
+strategy_id: NULL
+initiative_id: NULL
+---
+
+# Consolidate phase transition validation logic
+
+## Objective
+
+Eliminate duplicate phase transition validation logic by having a single source of truth for valid transitions.
+
+## Problem
+
+Phase transition rules are currently defined in two places:
+
+1. **`PhaseTransitionService::get_valid_transitions()`** - `crates/metis-docs-core/src/application/services/workspace/transition.rs`
+2. **Each document's `can_transition_to()` trait impl** - e.g., `crates/metis-docs-core/src/domain/documents/vision/mod.rs`
+
+This caused a bug where the service claimed backward transitions were valid, but the document-level validation rejected them. We fixed this by aligning both to forward-only, but the duplication remains.
+
+## Proposed Solutions
+
+### Option A: Service delegates to documents
+Have `get_valid_transitions()` call the document's `can_transition_to()` for each possible phase instead of maintaining its own list.
+
+### Option B: Documents delegate to service
+Remove validation from document's `transition_phase()` and have it trust the service's validation.
+
+### Option C: Shared transition rules
+Extract transition rules to a single location (e.g., constants or a dedicated module) that both service and documents reference.
+
+## Files Involved
+
+- `crates/metis-docs-core/src/application/services/workspace/transition.rs`
+- `crates/metis-docs-core/src/domain/documents/vision/mod.rs`
+- `crates/metis-docs-core/src/domain/documents/strategy/mod.rs`
+- `crates/metis-docs-core/src/domain/documents/initiative/mod.rs`
+- `crates/metis-docs-core/src/domain/documents/task/mod.rs`
+- `crates/metis-docs-core/src/domain/documents/adr/mod.rs`
+
+## Acceptance Criteria
+
+## Acceptance Criteria
+
+## Acceptance Criteria
+
+## Acceptance Criteria
+
+- [x] Single source of truth for phase transition rules
+- [x] No duplicate transition validation logic
+- [x] All existing tests pass
+- [x] Documentation updated if API changes
+
+## Resolution
+
+Implemented Option C (shared transition rules) by adding methods to `DocumentType`:
+- `valid_transitions_from(phase)` - returns valid target phases
+- `can_transition(from, to)` - checks if transition is valid
+- `next_phase(current)` - gets next phase in sequence
+- `phase_sequence()` - returns ordered phases for display
+
+Updated all consumers to use these methods:
+- `PhaseTransitionService::get_valid_transitions()` now delegates to `DocumentType`
+- `PhaseTransitionService::get_next_phase()` now delegates to `DocumentType`
+- All document `can_transition_to()` implementations now delegate to `DocumentType`
+- MCP `transition_phase.rs` now uses `DocumentType::phase_sequence()`

Cargo.toml

@@ -8,7 +8,7 @@ members = [
 resolver = "2"
 
 [workspace.package]
-version = "1.0.9"
+version = "1.0.10"
 edition = "2021"
 license = "Apache-2.0"
 authors = ["Dylan Storey <contact@colliery.io>"]

crates/metis-docs-core/src/application/services/workspace/transition.rs

@@ -245,134 +245,22 @@ impl PhaseTransitionService {
         Ok(())
     }
 
-    /// Get valid transitions from a given phase for a document type
+    /// Get valid transitions from a given phase for a document type.
+    /// Delegates to DocumentType::valid_transitions_from() - the single source of truth.
     fn get_valid_transitions(&self, doc_type: DocumentType, from_phase: Phase) -> Vec<Phase> {
-        match doc_type {
-            DocumentType::Vision => match from_phase {
-                Phase::Draft => vec![Phase::Review],
-                Phase::Review => vec![Phase::Draft, Phase::Published],
-                Phase::Published => vec![Phase::Review],
-                _ => vec![],
-            },
-            DocumentType::Strategy => match from_phase {
-                Phase::Shaping => vec![Phase::Design],
-                Phase::Design => vec![Phase::Shaping, Phase::Ready],
-                Phase::Ready => vec![Phase::Design, Phase::Active],
-                Phase::Active => vec![Phase::Ready, Phase::Completed],
-                Phase::Completed => vec![],
-                _ => vec![],
-            },
-            DocumentType::Initiative => match from_phase {
-                Phase::Discovery => vec![Phase::Design],
-                Phase::Design => vec![Phase::Discovery, Phase::Ready],
-                Phase::Ready => vec![Phase::Design, Phase::Decompose],
-                Phase::Decompose => vec![Phase::Ready, Phase::Active],
-                Phase::Active => vec![Phase::Decompose, Phase::Completed],
-                Phase::Completed => vec![],
-                _ => vec![],
-            },
-            DocumentType::Task => match from_phase {
-                Phase::Backlog => vec![Phase::Todo],
-                Phase::Todo => vec![Phase::Active, Phase::Blocked],
-                Phase::Active => vec![Phase::Todo, Phase::Completed, Phase::Blocked],
-                Phase::Blocked => vec![Phase::Todo, Phase::Active],
-                Phase::Completed => vec![],
-                _ => vec![],
-            },
-            DocumentType::Adr => match from_phase {
-                Phase::Draft => vec![Phase::Discussion],
-                Phase::Discussion => vec![Phase::Draft, Phase::Decided],
-                Phase::Decided => vec![Phase::Superseded],
-                Phase::Superseded => vec![],
-                _ => vec![],
-            },
-        }
+        doc_type.valid_transitions_from(from_phase)
     }
 
-    /// Get the next phase in the natural sequence for a document type
+    /// Get the next phase in the natural sequence for a document type.
+    /// Delegates to DocumentType::next_phase() - the single source of truth.
     fn get_next_phase(&self, doc_type: DocumentType, current_phase: Phase) -> Result<Phase> {
-        match doc_type {
-            DocumentType::Vision => match current_phase {
-                Phase::Draft => Ok(Phase::Review),
-                Phase::Review => Ok(Phase::Published),
-                Phase::Published => Err(MetisError::InvalidPhaseTransition {
-                    from: current_phase.to_string(),
-                    to: "none".to_string(),
-                    doc_type: "vision".to_string(),
-                }),
-                _ => Err(MetisError::InvalidPhaseTransition {
-                    from: current_phase.to_string(),
-                    to: "unknown".to_string(),
-                    doc_type: "vision".to_string(),
-                }),
-            },
-            DocumentType::Strategy => match current_phase {
-                Phase::Shaping => Ok(Phase::Design),
-                Phase::Design => Ok(Phase::Ready),
-                Phase::Ready => Ok(Phase::Active),
-                Phase::Active => Ok(Phase::Completed),
-                Phase::Completed => Err(MetisError::InvalidPhaseTransition {
-                    from: current_phase.to_string(),
-                    to: "none".to_string(),
-                    doc_type: "strategy".to_string(),
-                }),
-                _ => Err(MetisError::InvalidPhaseTransition {
-                    from: current_phase.to_string(),
-                    to: "unknown".to_string(),
-                    doc_type: "strategy".to_string(),
-                }),
-            },
-            DocumentType::Initiative => match current_phase {
-                Phase::Discovery => Ok(Phase::Design),
-                Phase::Design => Ok(Phase::Ready),
-                Phase::Ready => Ok(Phase::Decompose),
-                Phase::Decompose => Ok(Phase::Active),
-                Phase::Active => Ok(Phase::Completed),
-                Phase::Completed => Err(MetisError::InvalidPhaseTransition {
-                    from: current_phase.to_string(),
-                    to: "none".to_string(),
-                    doc_type: "initiative".to_string(),
-                }),
-                _ => Err(MetisError::InvalidPhaseTransition {
-                    from: current_phase.to_string(),
-                    to: "unknown".to_string(),
-                    doc_type: "initiative".to_string(),
-                }),
-            },
-            DocumentType::Task => {
-                match current_phase {
-                    Phase::Backlog => Ok(Phase::Todo), // Transition from backlog to todo
-                    Phase::Todo => Ok(Phase::Active),
-                    Phase::Active => Ok(Phase::Completed),
-                    Phase::Blocked => Ok(Phase::Active), // Unblock by default
-                    Phase::Completed => Err(MetisError::InvalidPhaseTransition {
-                        from: current_phase.to_string(),
-                        to: "none".to_string(),
-                        doc_type: "task".to_string(),
-                    }),
-                    _ => Err(MetisError::InvalidPhaseTransition {
-                        from: current_phase.to_string(),
-                        to: "unknown".to_string(),
-                        doc_type: "task".to_string(),
-                    }),
-                }
+        doc_type.next_phase(current_phase).ok_or_else(|| {
+            MetisError::InvalidPhaseTransition {
+                from: current_phase.to_string(),
+                to: "none".to_string(),
+                doc_type: doc_type.to_string(),
             }
-            DocumentType::Adr => match current_phase {
-                Phase::Draft => Ok(Phase::Discussion),
-                Phase::Discussion => Ok(Phase::Decided),
-                Phase::Decided => Ok(Phase::Superseded),
-                Phase::Superseded => Err(MetisError::InvalidPhaseTransition {
-                    from: current_phase.to_string(),
-                    to: "none".to_string(),
-                    doc_type: "adr".to_string(),
-                }),
-                _ => Err(MetisError::InvalidPhaseTransition {
-                    from: current_phase.to_string(),
-                    to: "unknown".to_string(),
-                    doc_type: "adr".to_string(),
-                }),
-            },
-        }
+        })
     }
 
     /// Check if a phase transition is valid without performing it
@@ -568,27 +456,32 @@ mod tests {
 
         let transition_service = PhaseTransitionService::new(&workspace_dir);
 
-        // Test vision transitions
+        // Test vision transitions (forward-only)
         let vision_draft_transitions =
             transition_service.get_valid_transitions_for(DocumentType::Vision, Phase::Draft);
         assert_eq!(vision_draft_transitions, vec![Phase::Review]);
 
         let vision_review_transitions =
             transition_service.get_valid_transitions_for(DocumentType::Vision, Phase::Review);
-        assert_eq!(
-            vision_review_transitions,
-            vec![Phase::Draft, Phase::Published]
-        );
+        assert_eq!(vision_review_transitions, vec![Phase::Published]);
 
-        // Test strategy transitions
+        // Test strategy transitions (forward-only)
         let strategy_shaping_transitions =
             transition_service.get_valid_transitions_for(DocumentType::Strategy, Phase::Shaping);
         assert_eq!(strategy_shaping_transitions, vec![Phase::Design]);
 
-        // Test task transitions - specifically backlog to todo
+        // Test task transitions - backlog to todo
         let task_backlog_transitions =
             transition_service.get_valid_transitions_for(DocumentType::Task, Phase::Backlog);
         assert_eq!(task_backlog_transitions, vec![Phase::Todo]);
+
+        // Test task transitions - blocked can return to todo or active
+        let task_blocked_transitions =
+            transition_service.get_valid_transitions_for(DocumentType::Task, Phase::Blocked);
+        assert_eq!(
+            task_blocked_transitions,
+            vec![Phase::Todo, Phase::Active]
+        );
     }
 
     #[tokio::test]
@@ -598,7 +491,7 @@ mod tests {
 
         let transition_service = PhaseTransitionService::new(&workspace_dir);
 
-        // Valid transitions
+        // Valid forward transitions
         assert!(transition_service.is_valid_transition(
             DocumentType::Vision,
             Phase::Draft,
@@ -610,7 +503,7 @@ mod tests {
             Phase::Design
         ));
 
-        // Invalid transitions
+        // Invalid transitions - skipping phases
         assert!(!transition_service.is_valid_transition(
             DocumentType::Vision,
             Phase::Draft,
@@ -621,5 +514,17 @@ mod tests {
             Phase::Shaping,
             Phase::Active
         ));
+
+        // Invalid transitions - backward (not supported)
+        assert!(!transition_service.is_valid_transition(
+            DocumentType::Vision,
+            Phase::Review,
+            Phase::Draft
+        ));
+        assert!(!transition_service.is_valid_transition(
+            DocumentType::Strategy,
+            Phase::Design,
+            Phase::Shaping
+        ));
     }
 }

crates/metis-docs-core/src/domain/documents/adr/mod.rs

@@ -354,11 +354,8 @@ impl Document for Adr {
 
     fn can_transition_to(&self, phase: Phase) -> bool {
         if let Ok(current_phase) = self.phase() {
-            use Phase::*;
-            matches!(
-                (current_phase, phase),
-                (Draft, Discussion) | (Discussion, Decided) | (Decided, Superseded)
-            )
+            // Delegate to DocumentType - the single source of truth
+            DocumentType::Adr.can_transition(current_phase, phase)
         } else {
             false // Can't transition if we can't determine current phase
         }

crates/metis-docs-core/src/domain/documents/initiative/mod.rs

@@ -405,15 +405,8 @@ impl Document for Initiative {
 
     fn can_transition_to(&self, phase: Phase) -> bool {
         if let Ok(current_phase) = self.phase() {
-            use Phase::*;
-            matches!(
-                (current_phase, phase),
-                (Discovery, Design)
-                    | (Design, Ready)
-                    | (Ready, Decompose)
-                    | (Decompose, Active)
-                    | (Active, Completed)
-            )
+            // Delegate to DocumentType - the single source of truth
+            DocumentType::Initiative.can_transition(current_phase, phase)
         } else {
             false // Can't transition if we can't determine current phase
         }

crates/metis-docs-core/src/domain/documents/strategy/mod.rs

@@ -407,11 +407,8 @@ impl Document for Strategy {
 
     fn can_transition_to(&self, phase: Phase) -> bool {
         if let Ok(current_phase) = self.phase() {
-            use Phase::*;
-            matches!(
-                (current_phase, phase),
-                (Shaping, Design) | (Design, Ready) | (Ready, Active) | (Active, Completed)
-            )
+            // Delegate to DocumentType - the single source of truth
+            DocumentType::Strategy.can_transition(current_phase, phase)
         } else {
             false // Can't transition if we can't determine current phase
         }

crates/metis-docs-core/src/domain/documents/task/mod.rs

@@ -352,17 +352,8 @@ impl Document for Task {
 
     fn can_transition_to(&self, phase: Phase) -> bool {
         if let Ok(current_phase) = self.phase() {
-            use Phase::*;
-            match (current_phase, phase) {
-                (Backlog, Todo) => true, // Move from backlog to todo when assigned to initiative
-                (Todo, Active) => true,
-                (Active, Completed) => true,
-                (Active, Blocked) => true,
-                (Todo, Blocked) => true, // Can pre emptively be blocked while in backlog
-                (Blocked, Active) => true,
-                (Blocked, Todo) => true, // Can go back to todo if unblocked
-                _ => false,
-            }
+            // Delegate to DocumentType - the single source of truth
+            DocumentType::Task.can_transition(current_phase, phase)
         } else {
             false // Can't transition if we can't determine current phase
         }