monoco-toolkit 0.2.4__py3-none-any.whl → 0.2.6__py3-none-any.whl

monoco/features/issue/core.py

@@ -10,35 +10,21 @@ from monoco.core.config import get_config, MonocoConfig
 from monoco.core.lsp import DiagnosticSeverity
 from .validator import IssueValidator
 
-PREFIX_MAP = {
-    IssueType.EPIC: "EPIC",
-    IssueType.FEATURE: "FEAT",
-    IssueType.CHORE: "CHORE",
-    IssueType.FIX: "FIX"
-}
+from .engine import get_engine
 
-REVERSE_PREFIX_MAP = {v: k for k, v in PREFIX_MAP.items()}
+def get_prefix_map(issues_root: Path) -> Dict[str, str]:
+    engine = get_engine(str(issues_root.parent))
+    return engine.get_prefix_map()
 
-def enforce_lifecycle_policy(meta: IssueMetadata) -> None:
-    """
-    Apply business rules to ensure IssueMetadata consistency.
-    Should be called during Create or Update (but NOT during Read/Lint).
-    """
-    if meta.status == IssueStatus.BACKLOG:
-        meta.stage = IssueStage.FREEZED
-    
-    elif meta.status == IssueStatus.CLOSED:
-        # Enforce stage=done for closed issues
-        if meta.stage != IssueStage.DONE:
-            meta.stage = IssueStage.DONE
-        # Auto-fill closed_at if missing
-        if not meta.closed_at:
-            meta.closed_at = current_time()
-    
-    elif meta.status == IssueStatus.OPEN:
-        # Ensure valid stage for open status
-        if meta.stage is None:
-            meta.stage = IssueStage.DRAFT
+def get_reverse_prefix_map(issues_root: Path) -> Dict[str, str]:
+    prefix_map = get_prefix_map(issues_root)
+    return {v: k for k, v in prefix_map.items()}
+
+def get_issue_dir(issue_type: str, issues_root: Path) -> Path:
+    engine = get_engine(str(issues_root.parent))
+    folder_map = engine.get_folder_map()
+    folder = folder_map.get(issue_type, issue_type.capitalize() + "s")
+    return issues_root / folder
 
 def _get_slug(title: str) -> str:
     slug = title.lower()
@@ -52,15 +38,6 @@ def _get_slug(title: str) -> str:
         
     return slug
 
-def get_issue_dir(issue_type: IssueType, issues_root: Path) -> Path:
-    mapping = {
-        IssueType.EPIC: "Epics",
-        IssueType.FEATURE: "Features",
-        IssueType.CHORE: "Chores",
-        IssueType.FIX: "Fixes",
-    }
-    return issues_root / mapping[issue_type]
-
 def parse_issue(file_path: Path) -> Optional[IssueMetadata]:
     if not file_path.suffix == ".md":
         return None
@@ -105,8 +82,9 @@ def parse_issue_detail(file_path: Path) -> Optional[IssueDetail]:
     except Exception:
         return None
 
-def find_next_id(issue_type: IssueType, issues_root: Path) -> str:
-    prefix = PREFIX_MAP[issue_type]
+def find_next_id(issue_type: str, issues_root: Path) -> str:
+    prefix_map = get_prefix_map(issues_root)
+    prefix = prefix_map.get(issue_type, "ISSUE")
     pattern = re.compile(rf"{prefix}-(\d+)")
     max_id = 0
     
@@ -147,7 +125,7 @@ def create_issue_file(
 
     issue_id = find_next_id(issue_type, issues_root)
     base_type_dir = get_issue_dir(issue_type, issues_root)
-    target_dir = base_type_dir / status.value
+    target_dir = base_type_dir / status
     
     if subdir:
         target_dir = target_dir / subdir
@@ -170,24 +148,49 @@ def create_issue_file(
     )
     
     # Enforce lifecycle policies (defaults, auto-corrections)
-    enforce_lifecycle_policy(metadata)
+    from .engine import get_engine
+    get_engine().enforce_policy(metadata)
 
+    # Serialize metadata
     yaml_header = yaml.dump(metadata.model_dump(exclude_none=True, mode='json'), sort_keys=False, allow_unicode=True)
+    
+    # Inject Self-Documenting Hints (Interactive Frontmatter)
+    if "parent:" not in yaml_header:
+        yaml_header += "# parent: <EPIC-ID>   # Optional: Parent Issue ID\n"
+    if "solution:" not in yaml_header:
+        yaml_header += "# solution: null      # Required for Closed state (implemented, cancelled, etc.)\n"
+
     slug = _get_slug(title)
     filename = f"{issue_id}-{slug}.md"
     
+    # Enhanced Template with Instructional Comments
     file_content = f"""---
 {yaml_header}---
 
 ## {issue_id}: {title}
 
 ## Objective
+<!-- Describe the "Why" and "What" clearly. Focus on value. -->
 
 ## Acceptance Criteria
+<!-- Define binary conditions for success. -->
+- [ ] Criteria 1
 
 ## Technical Tasks
+<!-- Breakdown into atomic steps. Use nested lists for sub-tasks. -->
 
-- [ ] 
+<!-- Status Syntax: -->
+<!-- [ ] To Do -->
+<!-- [/] Doing -->
+<!-- [x] Done -->
+<!-- [~] Cancelled -->
+<!-- - [ ] Parent Task -->
+<!--   - [ ] Sub Task -->
+
+- [ ] Task 1
+
+## Review Comments
+<!-- Required for Review/Done stage. Record review feedback here. -->
 """
     file_path = target_dir / filename
     file_path.write_text(file_content)
@@ -198,32 +201,29 @@ def create_issue_file(
     return metadata, file_path
 def get_available_actions(meta: IssueMetadata) -> List[Any]:
     from .models import IssueAction
+    from .engine import get_engine
+    
+    engine = get_engine()
+    transitions = engine.get_available_transitions(meta)
+    
     actions = []
-
-    if meta.status == IssueStatus.OPEN:
-        # Stage-based movements
-        if meta.stage == IssueStage.DRAFT:
-            actions.append(IssueAction(label="Start", target_status=IssueStatus.OPEN, target_stage=IssueStage.DOING))
-            actions.append(IssueAction(label="Freeze", target_status=IssueStatus.BACKLOG))
-        elif meta.stage == IssueStage.DOING:
-            actions.append(IssueAction(label="Stop", target_status=IssueStatus.OPEN, target_stage=IssueStage.DRAFT))
-            actions.append(IssueAction(label="Submit", target_status=IssueStatus.OPEN, target_stage=IssueStage.REVIEW))
-        elif meta.stage == IssueStage.REVIEW:
-            actions.append(IssueAction(label="Approve", target_status=IssueStatus.CLOSED, target_stage=IssueStage.DONE, target_solution=IssueSolution.IMPLEMENTED))
-            actions.append(IssueAction(label="Reject", target_status=IssueStatus.OPEN, target_stage=IssueStage.DOING))
-        elif meta.stage == IssueStage.DONE:
-            actions.append(IssueAction(label="Reopen", target_status=IssueStatus.OPEN, target_stage=IssueStage.DRAFT))
-            actions.append(IssueAction(label="Close", target_status=IssueStatus.CLOSED, target_stage=IssueStage.DONE, target_solution=IssueSolution.IMPLEMENTED))
+    for t in transitions:
+        command = t.command_template.format(id=meta.id) if t.command_template else ""
         
-        # Generic cancel
-        actions.append(IssueAction(label="Cancel", target_status=IssueStatus.CLOSED, target_stage=IssueStage.DONE, target_solution=IssueSolution.CANCELLED))
-
-    elif meta.status == IssueStatus.BACKLOG:
-        actions.append(IssueAction(label="Pull", target_status=IssueStatus.OPEN, target_stage=IssueStage.DRAFT))
-        actions.append(IssueAction(label="Cancel", target_status=IssueStatus.CLOSED, target_stage=IssueStage.DONE, target_solution=IssueSolution.CANCELLED))
-
-    elif meta.status == IssueStatus.CLOSED:
-        actions.append(IssueAction(label="Reopen", target_status=IssueStatus.OPEN, target_stage=IssueStage.DRAFT))
+        # Determine task if it's an agent action
+        task = None
+        if t.name == "develop":
+            task = "develop"
+        
+        actions.append(IssueAction(
+            label=t.label,
+            icon=t.icon,
+            target_status=t.to_status if t.to_status != meta.status or t.to_stage != meta.stage else None,
+            target_stage=t.to_stage if t.to_stage != meta.stage else None,
+            target_solution=t.required_solution,
+            command=command,
+            task=task
+        ))
 
     return actions
 
@@ -261,7 +261,8 @@ def find_issue_path(issues_root: Path, issue_id: str) -> Optional[Path]:
     except IndexError:
         return None
         
-    issue_type = REVERSE_PREFIX_MAP.get(prefix)
+    reverse_prefix_map = get_reverse_prefix_map(issues_root)
+    issue_type = reverse_prefix_map.get(prefix)
     if not issue_type:
         return None
         
@@ -316,30 +317,43 @@ def update_issue(
         current_status = IssueStatus(current_status_str.lower())
     except ValueError:
         current_status = IssueStatus.OPEN
+    
+    current_stage_str = data.get("stage")
+    current_stage = IssueStage(current_stage_str.lower()) if current_stage_str else None
 
     # Logic: Status Update
     target_status = status if status else current_status
     
-    # Validation: For closing
-    effective_solution = solution.value if solution else data.get("solution")
+    # If status is changing, we don't default target_stage to current_stage
+    # because the new status might have different allowed stages.
+    # enforce_policy will handle setting the correct default stage for the new status.
+    if status and status != current_status:
+        target_stage = stage
+    else:
+        target_stage = stage if stage else current_stage
     
-    # Policy: Prevent Backlog -> Review
-    if stage == IssueStage.REVIEW and current_status == IssueStatus.BACKLOG:
-         raise ValueError(f"Lifecycle Policy: Cannot submit Backlog issue directly. Run `monoco issue pull {issue_id}` first.")
+    # Engine Validation
+    from .engine import get_engine
+    engine = get_engine()
+    
+    # Map solution string to enum if present
+    effective_solution = solution
+    if not effective_solution and data.get("solution"):
+        try:
+            effective_solution = IssueSolution(data.get("solution").lower())
+        except ValueError:
+            pass
 
-    if target_status == IssueStatus.CLOSED:
-        # Validator will check solution presence
-        current_data_stage = data.get('stage')
-        
-        # Policy: IMPLEMENTED requires REVIEW stage
-        if effective_solution == IssueSolution.IMPLEMENTED.value:
-            if current_data_stage != IssueStage.REVIEW.value:
-                raise ValueError(f"Lifecycle Policy: 'Implemented' issues must be submitted for review first.\nCurrent stage: {current_data_stage}\nAction: Run `monoco issue submit {issue_id}`.")
-
-     # Policy: No closing from DOING (General Safety)
-        if current_data_stage == IssueStage.DOING.value:
-             raise ValueError("Cannot close issue in progress (Doing). Please review (`monoco issue submit`) or stop (`monoco issue open`) first.")
-             
+    # Use engine to validate the transition
+    engine.validate_transition(
+        from_status=current_status,
+        from_stage=current_stage,
+        to_status=target_status,
+        to_stage=target_stage,
+        solution=effective_solution
+    )
+
+    if target_status == "closed":
         # Policy: Dependencies must be closed
         dependencies_to_check = dependencies if dependencies is not None else data.get('dependencies', [])
         if dependencies_to_check:
@@ -347,8 +361,8 @@ def update_issue(
                 dep_path = find_issue_path(issues_root, dep_id)
                 if dep_path:
                     dep_meta = parse_issue(dep_path)
-                    if dep_meta and dep_meta.status != IssueStatus.CLOSED:
-                        raise ValueError(f"Dependency Block: Cannot close {issue_id} because dependency {dep_id} is [Status: {dep_meta.status.value}].")
+                    if dep_meta and dep_meta.status != "closed":
+                        raise ValueError(f"Dependency Block: Cannot close {issue_id} because dependency {dep_id} is [Status: {dep_meta.status}].")
     
     # Validate new parent/dependencies/related exist
     if parent is not None and parent != "":
@@ -367,12 +381,12 @@ def update_issue(
             
     # Update Data
     if status:
-        data['status'] = status.value
+        data['status'] = status
 
     if stage:
-        data['stage'] = stage.value
+        data['stage'] = stage
     if solution:
-        data['solution'] = solution.value
+        data['solution'] = solution
     
     if title:
         data['title'] = title
@@ -415,7 +429,8 @@ def update_issue(
         
         # Enforce lifecycle policies (defaults, auto-corrections)
         # This ensures that when we update, we also fix invalid states (like Closed but not Done)
-        enforce_lifecycle_policy(updated_meta)
+        from .engine import get_engine
+        get_engine().enforce_policy(updated_meta)
 
         # Delegate to IssueValidator for static state validation
         # We need to construct the full content to validate body-dependent rules (like checkboxes)
@@ -451,7 +466,8 @@ def update_issue(
     if status and status != current_status:
         # Move file
         prefix = issue_id.split("-")[0].upper()
-        base_type_dir = get_issue_dir(REVERSE_PREFIX_MAP[prefix], issues_root)
+        reverse_prefix_map = get_reverse_prefix_map(issues_root)
+        base_type_dir = get_issue_dir(reverse_prefix_map[prefix], issues_root)
         
         try:
             rel_path = path.relative_to(base_type_dir)
@@ -459,7 +475,7 @@ def update_issue(
         except ValueError:
             structure_path = Path(path.name)
 
-        target_path = base_type_dir / target_status.value / structure_path
+        target_path = base_type_dir / target_status / structure_path
             
         if path != target_path:
             target_path.parent.mkdir(parents=True, exist_ok=True)
@@ -475,7 +491,7 @@ def update_issue(
     updated_meta.actions = get_available_actions(updated_meta)
     return updated_meta
 
-def start_issue_isolation(issues_root: Path, issue_id: str, mode: IsolationType, project_root: Path) -> IssueMetadata:
+def start_issue_isolation(issues_root: Path, issue_id: str, mode: str, project_root: Path) -> IssueMetadata:
     """
     Start physical isolation for an issue (Branch or Worktree).
     """
@@ -503,7 +519,7 @@ def start_issue_isolation(issues_root: Path, issue_id: str, mode: IsolationType,
     
     isolation_meta = None
 
-    if mode == IsolationType.BRANCH:
+    if mode == "branch":
         if not git.branch_exists(project_root, branch_name):
             git.create_branch(project_root, branch_name, checkout=True)
         else:
@@ -513,9 +529,9 @@ def start_issue_isolation(issues_root: Path, issue_id: str, mode: IsolationType,
             if current != branch_name:
                 git.checkout_branch(project_root, branch_name)
         
-        isolation_meta = IssueIsolation(type=IsolationType.BRANCH, ref=branch_name)
+        isolation_meta = IssueIsolation(type="branch", ref=branch_name)
 
-    elif mode == IsolationType.WORKTREE:
+    elif mode == "worktree":
         wt_path = project_root / ".monoco" / "worktrees" / f"{issue_id.lower()}-{slug}"
         
         # Check if worktree exists physically
@@ -526,7 +542,7 @@ def start_issue_isolation(issues_root: Path, issue_id: str, mode: IsolationType,
              wt_path.parent.mkdir(parents=True, exist_ok=True)
              git.worktree_add(project_root, branch_name, wt_path)
              
-        isolation_meta = IssueIsolation(type=IsolationType.WORKTREE, ref=branch_name, path=str(wt_path))
+        isolation_meta = IssueIsolation(type="worktree", ref=branch_name, path=str(wt_path))
     
     # Persist Metadata
     # We load raw, update isolation field, save.
@@ -538,7 +554,7 @@ def start_issue_isolation(issues_root: Path, issue_id: str, mode: IsolationType,
         
         data['isolation'] = isolation_meta.model_dump(mode='json')
         # Also ensure stage is DOING (logic link)
-        data['stage'] = IssueStage.DOING.value
+        data['stage'] = "doing"
         data['updated_at'] = current_time()
 
         new_yaml = yaml.dump(data, sort_keys=False, allow_unicode=True)
@@ -700,7 +716,10 @@ def list_issues(issues_root: Path, recursive_workspace: bool = False) -> List[Is
     List all issues in the project.
     """
     issues = []
-    for issue_type in IssueType:
+    engine = get_engine(str(issues_root.parent))
+    all_types = engine.get_all_types()
+    
+    for issue_type in all_types:
         base_dir = get_issue_dir(issue_type, issues_root)
         for status_dir in ["open", "backlog", "closed"]:
             d = base_dir / status_dir
@@ -739,21 +758,21 @@ def get_board_data(issues_root: Path) -> Dict[str, List[IssueMetadata]]:
     Get open issues grouped by their stage for Kanban view.
     """
     board = {
-        IssueStage.DRAFT.value: [],
-        IssueStage.DOING.value: [],
-        IssueStage.REVIEW.value: [],
-        IssueStage.DONE.value: []
+        "draft": [],
+        "doing": [],
+        "review": [],
+        "done": []
     }
     
     issues = list_issues(issues_root)
     for issue in issues:
-        if issue.status == IssueStatus.OPEN and issue.stage:
-            stage_val = issue.stage.value
+        if issue.status == "open" and issue.stage:
+            stage_val = issue.stage
             if stage_val in board:
                 board[stage_val].append(issue)
-        elif issue.status == IssueStatus.CLOSED:
+        elif issue.status == "closed":
             # Optionally show recently closed items in DONE column
-            board[IssueStage.DONE.value].append(issue)
+            board["done"].append(issue)
             
     return board
 
@@ -763,14 +782,14 @@ def validate_issue_integrity(meta: IssueMetadata, all_issue_ids: Set[str] = set(
     UI-agnostic.
     """
     errors = []
-    if meta.status == IssueStatus.CLOSED and not meta.solution:
+    if meta.status == "closed" and not meta.solution:
         errors.append(f"Solution Missing: {meta.id} is closed but has no solution field.")
             
     if meta.parent:
         if all_issue_ids and meta.parent not in all_issue_ids:
              errors.append(f"Broken Link: {meta.id} refers to non-existent parent {meta.parent}.")
 
-    if meta.status == IssueStatus.BACKLOG and meta.stage != IssueStage.FREEZED:
+    if meta.status == "backlog" and meta.stage != "freezed":
         errors.append(f"Lifecycle Error: {meta.id} is backlog but stage is not freezed (found: {meta.stage}).")
         
     return errors
@@ -815,7 +834,8 @@ def update_issue_content(issues_root: Path, issue_id: str, new_content: str) ->
         # Reuse logic from update_issue (simplified)
         
         prefix = issue_id.split("-")[0].upper()
-        base_type_dir = get_issue_dir(REVERSE_PREFIX_MAP[prefix], issues_root)
+        reverse_prefix_map = get_reverse_prefix_map(issues_root)
+        base_type_dir = get_issue_dir(reverse_prefix_map[prefix], issues_root)
         
         # Calculate structure path (preserve subdir)
         try:
@@ -828,7 +848,7 @@ def update_issue_content(issues_root: Path, issue_id: str, new_content: str) ->
             # Fallback if path is weird
             structure_path = Path(path.name)
 
-        target_path = base_type_dir / meta.status.value / structure_path
+        target_path = base_type_dir / meta.status / structure_path
             
         if path != target_path:
             target_path.parent.mkdir(parents=True, exist_ok=True)
@@ -980,9 +1000,9 @@ def check_issue_match(issue: IssueMetadata, explicit_positives: List[str], terms
     searchable_parts = [
         issue.id,
         issue.title,
-        issue.status.value,
-        issue.type.value,
-        str(issue.stage.value) if issue.stage else "",
+        issue.status,
+        issue.type,
+        str(issue.stage) if issue.stage else "",
         *(issue.tags or []),
         *(issue.dependencies or []),
         *(issue.related or []),
@@ -1041,7 +1061,10 @@ def search_issues(issues_root: Path, query: str) -> List[IssueMetadata]:
     # To support deep search (Body), we need to read files.
     # Let's iterate files directly.
     
-    for issue_type in IssueType:
+    engine = get_engine(str(issues_root.parent))
+    all_types = engine.get_all_types()
+    
+    for issue_type in all_types:
         base_dir = get_issue_dir(issue_type, issues_root)
         for status_dir in ["open", "backlog", "closed"]:
             d = base_dir / status_dir
@@ -1089,7 +1112,7 @@ def recalculate_parent(issues_root: Path, parent_id: str):
         return
 
     total = len(children)
-    closed = len([c for c in children if c.status == IssueStatus.CLOSED])
+    closed = len([c for c in children if c.status == "closed"])
     # Progress string: "3/5"
     progress_str = f"{closed}/{total}"
     
@@ -1129,8 +1152,8 @@ def recalculate_parent(issues_root: Path, parent_id: str):
         
         if current_status == "open" and current_stage == "draft":
             # Check if any child is active
-            active_children = [c for c in children if c.status == IssueStatus.OPEN and c.stage != IssueStage.DRAFT]
-            closed_children = [c for c in children if c.status == IssueStatus.CLOSED]
+            active_children = [c for c in children if c.status == "open" and c.stage != "draft"]
+            closed_children = [c for c in children if c.status == "closed"]
             
             if active_children or closed_children:
                 data["stage"] = "doing"
@@ -1212,7 +1235,7 @@ def move_issue(
     
     # 4. Construct target path
     target_type_dir = get_issue_dir(issue.type, target_issues_root)
-    target_status_dir = target_type_dir / issue.status.value
+    target_status_dir = target_type_dir / issue.status
     
     # Preserve subdirectory structure if any
     try:

monoco/features/issue/domain/lifecycle.py

@@ -0,0 +1,126 @@
+from typing import List, Optional, Callable
+from pydantic import BaseModel
+from ..models import IssueStatus, IssueStage, IssueSolution, current_time
+from .models import Issue
+
+class Transition(BaseModel):
+    name: str
+    from_status: Optional[IssueStatus] = None # None means any
+    from_stage: Optional[IssueStage] = None   # None means any
+    to_status: IssueStatus
+    to_stage: Optional[IssueStage] = None
+    required_solution: Optional[IssueSolution] = None
+    description: str = ""
+
+    def is_allowed(self, issue: Issue) -> bool:
+        if self.from_status and issue.status != self.from_status:
+            return False
+        if self.from_stage and issue.frontmatter.stage != self.from_stage:
+            return False
+        return True
+
+class TransitionService:
+    def __init__(self):
+        self.transitions: List[Transition] = [
+            # Open -> Backlog
+            Transition(
+                name="freeze",
+                from_status=IssueStatus.OPEN,
+                to_status=IssueStatus.BACKLOG,
+                to_stage=IssueStage.FREEZED,
+                description="Move open issue to backlog"
+            ),
+            # Backlog -> Open
+            Transition(
+                name="activate",
+                from_status=IssueStatus.BACKLOG,
+                to_status=IssueStatus.OPEN,
+                to_stage=IssueStage.DRAFT, # Reset to draft?
+                description="Restore issue from backlog"
+            ),
+            # Open (Draft) -> Open (Doing)
+            Transition(
+                name="start",
+                from_status=IssueStatus.OPEN,
+                from_stage=IssueStage.DRAFT,
+                to_status=IssueStatus.OPEN,
+                to_stage=IssueStage.DOING,
+                description="Start working on the issue"
+            ),
+            # Open (Doing) -> Open (Review)
+            Transition(
+                name="submit",
+                from_status=IssueStatus.OPEN,
+                from_stage=IssueStage.DOING,
+                to_status=IssueStatus.OPEN,
+                to_stage=IssueStage.REVIEW,
+                description="Submit for review"
+            ),
+             # Open (Review) -> Open (Doing) - reject
+            Transition(
+                name="reject",
+                from_status=IssueStatus.OPEN,
+                from_stage=IssueStage.REVIEW,
+                to_status=IssueStatus.OPEN,
+                to_stage=IssueStage.DOING,
+                description="Reject review and return to doing"
+            ),
+            # Open (Review) -> Closed (Implemented)
+            Transition(
+                name="accept",
+                from_status=IssueStatus.OPEN,
+                from_stage=IssueStage.REVIEW,
+                to_status=IssueStatus.CLOSED,
+                to_stage=IssueStage.DONE,
+                required_solution=IssueSolution.IMPLEMENTED,
+                description="Accept and close issue"
+            ),
+            # Direct Close (Cancel, Wontfix, Duplicate)
+            Transition(
+                name="cancel",
+                to_status=IssueStatus.CLOSED,
+                to_stage=IssueStage.DONE,
+                required_solution=IssueSolution.CANCELLED,
+                description="Cancel the issue"
+            ),
+             Transition(
+                name="wontfix",
+                to_status=IssueStatus.CLOSED,
+                to_stage=IssueStage.DONE,
+                required_solution=IssueSolution.WONTFIX,
+                description="Mark as wontfix"
+            ),
+        ]
+
+    def get_available_transitions(self, issue: Issue) -> List[Transition]:
+        return [t for t in self.transitions if t.is_allowed(issue)]
+
+    def apply_transition(self, issue: Issue, transition_name: str) -> Issue:
+        # Find transition
+        candidates = [t for t in self.transitions if t.name == transition_name]
+        valid_transition = None
+        for t in candidates:
+            if t.is_allowed(issue):
+                valid_transition = t
+                break
+        
+        if not valid_transition:
+            raise ValueError(f"Transition '{transition_name}' is not allowed for current state.")
+
+        # Apply changes
+        issue.frontmatter.status = valid_transition.to_status
+        if valid_transition.to_stage:
+            issue.frontmatter.stage = valid_transition.to_stage
+        if valid_transition.required_solution:
+            issue.frontmatter.solution = valid_transition.required_solution
+            
+        issue.frontmatter.updated_at = current_time()
+        
+        # Logic for closed_at, opened_at etc.
+        if valid_transition.to_status == IssueStatus.CLOSED and issue.frontmatter.closed_at is None:
+            issue.frontmatter.closed_at = current_time()
+            
+        if valid_transition.to_status == IssueStatus.OPEN and issue.frontmatter.opened_at is None:
+             issue.frontmatter.opened_at = current_time()
+            
+        return issue