monoco-toolkit 0.3.9__py3-none-any.whl → 0.3.11__py3-none-any.whl

monoco/features/issue/core.py

@@ -108,6 +108,8 @@ def _serialize_metadata(metadata: IssueMetadata) -> str:
         data["domains"] = []
     if "files" not in data:
         data["files"] = []
+    if "solution" not in data:
+        data["solution"] = None
 
     # Custom YAML Dumper to preserve None as 'null' and order
     # Helper to order keys: id, uid, type, status, stage, title, ... graph ...
@@ -147,6 +149,10 @@ def _serialize_metadata(metadata: IssueMetadata) -> str:
     if "criticality" in data:
         ordered_data["criticality"] = data["criticality"]
 
+    # Add solution if present (for template generation)
+    if "solution" in data:
+        ordered_data["solution"] = data["solution"]
+
     # Add remaining
     for k, v in data.items():
         if k not in ordered_data:
@@ -161,6 +167,10 @@ def _serialize_metadata(metadata: IssueMetadata) -> str:
         yaml_header = yaml_header.replace(
             "parent: null", "parent: null # <EPIC-ID> Optional"
         )
+    if "solution" in ordered_data and ordered_data["solution"] is None:
+        yaml_header = yaml_header.replace(
+            "solution: null", "solution: null # implemented, cancelled, wontfix, duplicate"
+        )
 
     return yaml_header
 
@@ -189,15 +199,19 @@ def parse_issue_detail(file_path: Path) -> Optional[IssueDetail]:
         return None
 
 
-def find_next_id(issue_type: str, issues_root: Path) -> str:
+def find_next_id(issue_type: str, issues_root: Path, include_archived: bool = False) -> str:
     prefix_map = get_prefix_map(issues_root)
     prefix = prefix_map.get(issue_type, "ISSUE")
     pattern = re.compile(rf"{prefix}-(\d+)")
     max_id = 0
 
     base_dir = get_issue_dir(issue_type, issues_root)
-    # Scan all subdirs: open, backlog, closed
-    for status_dir in ["open", "backlog", "closed"]:
+    # Scan all subdirs: open, backlog, closed, archived (optional)
+    status_dirs = ["open", "backlog", "closed"]
+    if include_archived:
+        status_dirs.append("archived")
+    
+    for status_dir in status_dirs:
         d = base_dir / status_dir
         if d.exists():
             for f in d.rglob("*.md"):
@@ -388,7 +402,15 @@ def get_available_actions(meta: IssueMetadata) -> List[Any]:
     return actions
 
 
-def find_issue_path(issues_root: Path, issue_id: str) -> Optional[Path]:
+def find_issue_path(issues_root: Path, issue_id: str, include_archived: bool = True) -> Optional[Path]:
+    """
+    Find the path of an issue file.
+    
+    Args:
+        issues_root: Root directory of issues
+        issue_id: Issue ID to find
+        include_archived: Whether to search in archived directory (default: True for find operations)
+    """
     parsed = IssueID(issue_id)
 
     if not parsed.is_local:
@@ -414,7 +436,7 @@ def find_issue_path(issues_root: Path, issue_id: str) -> Optional[Path]:
             return None
 
         # Recursively search in member project
-        return find_issue_path(member_issues, parsed.local_id)
+        return find_issue_path(member_issues, parsed.local_id, include_archived)
 
     # Local Search
     try:
@@ -428,9 +450,19 @@ def find_issue_path(issues_root: Path, issue_id: str) -> Optional[Path]:
         return None
 
     base_dir = get_issue_dir(issue_type, issues_root)
-    # Search in all status subdirs recursively
-    for f in base_dir.rglob(f"{parsed.local_id}-*.md"):
-        return f
+    # Search in standard status subdirs first
+    for status_dir in ["open", "backlog", "closed"]:
+        d = base_dir / status_dir
+        if d.exists():
+            for f in d.rglob(f"{parsed.local_id}-*.md"):
+                return f
+    
+    # Search in archived if enabled
+    if include_archived:
+        archived_dir = base_dir / "archived"
+        if archived_dir.exists():
+            for f in archived_dir.rglob(f"{parsed.local_id}-*.md"):
+                return f
     return None
 
 
@@ -515,7 +547,7 @@ def update_issue(
     temp_meta = IssueMetadata(**data)
 
     # Use engine to validate the transition
-    engine.validate_transition(
+    transition = engine.validate_transition(
         from_status=current_status,
         from_stage=current_stage,
         to_status=target_status,
@@ -659,6 +691,8 @@ def update_issue(
     path.write_text(new_content)
 
     # 3. Handle physical move if status changed
+    # Save old path before move for git tracking
+    old_path_before_move = path
     if status and status != current_status:
         # Move file
         prefix = issue_id.split("-")[0].upper()
@@ -702,17 +736,16 @@ def update_issue(
         # Only auto-commit if we're in a git repo
         git_service = IssueGitService(project_root)
         if git_service.is_git_repository():
-            # Determine old path if status changed (file was moved)
+            # Use the saved old path before file move for git tracking
             old_path_for_git = None
-            if status and status != current_status:
-                # The original path before move
-                old_path_for_git = find_issue_path(issues_root, issue_id)
+            if status and status != current_status and old_path_before_move != path:
+                old_path_for_git = old_path_before_move
 
             commit_result = git_service.commit_issue_change(
                 issue_id=issue_id,
                 action=action,
                 issue_file_path=path,
-                old_file_path=old_path_for_git if old_path_for_git != path else None,
+                old_file_path=old_path_for_git,
                 no_commit=no_commit,
             )
             # Attach commit result to metadata for optional inspection
@@ -721,9 +754,47 @@ def update_issue(
     # Update returned metadata with final absolute path
     updated_meta.path = str(path.absolute())
     updated_meta.actions = get_available_actions(updated_meta)
+
+    # Execute Post Actions (Trigger)
+    if transition and hasattr(transition, "post_actions") and transition.post_actions:
+        _execute_post_actions(transition.post_actions, updated_meta)
+
     return updated_meta
 
 
+def _execute_post_actions(actions: List[str], meta: IssueMetadata):
+    """
+    Execute a list of shell commands as post-actions.
+    Supports template substitution with issue metadata.
+    """
+    import shlex
+    import subprocess
+    from rich.console import Console
+    
+    console = Console()
+    data = meta.model_dump(mode="json")
+    
+    for action in actions:
+        try:
+            # Safe template substitution
+            cmd = action.format(**data)
+        except KeyError as e:
+            console.print(f"[yellow]Trigger Warning:[/yellow] Missing key for template '{action}': {e}")
+            continue
+            
+        console.print(f"[bold cyan]Triggering:[/bold cyan] {cmd}")
+        
+        args = shlex.split(cmd)
+        
+        try:
+            # Run in foreground to allow interaction if needed (e.g. agent output)
+            subprocess.run(args, check=True)
+        except subprocess.CalledProcessError as e:
+            console.print(f"[red]Trigger Failed:[/red] Command '{cmd}' exited with code {e.returncode}")
+        except Exception as e:
+            console.print(f"[red]Trigger Error:[/red] {e}")
+
+
 def start_issue_isolation(
     issues_root: Path, issue_id: str, mode: str, project_root: Path
 ) -> IssueMetadata:
@@ -913,6 +984,8 @@ def sync_issue_files(issues_root: Path, issue_id: str, project_root: Path) -> Li
 
     if issue.isolation and issue.isolation.ref:
         target_ref = issue.isolation.ref
+        if target_ref == "current":
+             target_ref = git.get_current_branch(project_root)
     else:
         # Heuristic Search
         # 1. Is current branch related?
@@ -964,6 +1037,118 @@ def sync_issue_files(issues_root: Path, issue_id: str, project_root: Path) -> Li
     return []
 
 
+def merge_issue_changes(
+    issues_root: Path, issue_id: str, project_root: Path
+) -> List[str]:
+    """
+    Perform Smart Atomic Merge or selection checkout of touched files.
+    Ensures safe mainline synchronization by only merging files tracked in 'files' field.
+    """
+    path = find_issue_path(issues_root, issue_id)
+    if not path:
+        raise FileNotFoundError(f"Issue {issue_id} not found.")
+
+    issue = parse_issue(path)
+    if not issue:
+        raise ValueError(f"Could not parse issue {issue_id}")
+
+    if not issue.files:
+        # If no files tracked, nothing to merge.
+        return []
+
+    # Determine Source (Feature Branch)
+    # We prioritize what's in the issue metadata on LOCAL (main).
+    # If not there, we try heuristic.
+    source_ref = None
+    if issue.isolation and issue.isolation.ref:
+        source_ref = issue.isolation.ref
+    else:
+        # Heuristic: Search for branch by convention
+        # We can't use 'current' here safely if we are on main,
+        # but let's assume we might be calling this from elsewhere?
+        # Actually, for 'close', we are likely on main.
+        # So we search for a branch named 'feat/{id}-*' or similar?
+        pass
+
+    # If local metadata doesn't have isolation ref, we might be stuck.
+    # But let's assume valid workflow.
+    if not source_ref:
+          # Try to find a branch starting with feat/{id} or {id}
+          # This is a bit weak, needs better implementation in 'git' or 'issue' module
+          # For now, if we can't find it, we error.
+          pass
+
+    if not source_ref or not git.branch_exists(project_root, source_ref):
+        # Fallback: maybe we are currently ON the feature branch?
+        # If so, source_ref should be current. But we expect to call this from MAIN.
+        pass
+        
+    if not source_ref:
+         raise RuntimeError(f"Could not determine source branch for Issue {issue_id}. Ensure isolation ref is set.")
+
+    if not git.branch_exists(project_root, source_ref):
+         raise RuntimeError(f"Source branch {source_ref} does not exist.")
+
+    # RE-READ Issue from Source Branch
+    # The 'files' list on main might be outdated. We need the list from the feature branch.
+    relative_path = path.relative_to(project_root)
+    
+    try:
+        # Read file content from git
+        code, access_content, _ = git._run_git(["show", f"{source_ref}:{relative_path}"], project_root)
+        if code == 0:
+            # Parse it
+            # We need to extract yaml frontmatter manually or use existing parser if it supported text input
+            import re
+            import yaml
+            match = re.search(r"^---(.*?)---", access_content, re.DOTALL | re.MULTILINE)
+            if match:
+                data = yaml.safe_load(match.group(1)) or {}
+                source_files = data.get("files", [])
+                if source_files:
+                    # Update issue object with latest files for this operation
+                    issue.files = source_files
+    except Exception as e:
+        # If reading fails (maybe path changed?), we fall back to local 'files'
+        pass
+
+    if not issue.files:
+         return []
+
+    # 1. Conflict Check
+    # A conflict occurs if a file in 'files' has changed on HEAD (main)
+    # since the common ancestor of HEAD and source_ref.
+
+    current_head = git.get_current_branch(project_root)
+    try:
+        base = git.get_merge_base(project_root, current_head, source_ref)
+    except Exception as e:
+        raise RuntimeError(f"Failed to determine merge base: {e}")
+
+    conflicts = []
+    for f in issue.files:
+        # Has main changed this file?
+        if git.has_diff(project_root, base, current_head, [f]):
+            # Has feature also changed this file?
+            if git.has_diff(project_root, base, source_ref, [f]):
+                conflicts.append(f)
+
+    if conflicts:
+        raise RuntimeError(
+            f"Atomic Merge Conflict: The following files changed on both mainline and {issue_id}:\n"
+            + "\n".join([f"  - {f}" for f in conflicts])
+            + "\n\nPlease resolve manually using Cherry-Pick as per AGENTS.md policy."
+        )
+
+    # 2. Perform Atomic Merge (Selective Checkout)
+    try:
+        git.git_checkout_files(project_root, source_ref, issue.files)
+    except Exception as e:
+        raise RuntimeError(f"Selective checkout failed: {e}")
+
+    return issue.files
+
+
 # Resources
 SKILL_CONTENT = """
 ---
@@ -1029,10 +1214,15 @@ def get_resources() -> Dict[str, Any]:
 
 
 def list_issues(
-    issues_root: Path, recursive_workspace: bool = False
+    issues_root: Path, recursive_workspace: bool = False, include_archived: bool = False
 ) -> List[IssueMetadata]:
     """
     List all issues in the project.
+    
+    Args:
+        issues_root: Root directory of issues
+        recursive_workspace: Include issues from workspace members
+        include_archived: Include archived issues (default: False)
     """
     issues = []
     engine = get_engine(str(issues_root.parent))
@@ -1040,7 +1230,11 @@ def list_issues(
 
     for issue_type in all_types:
         base_dir = get_issue_dir(issue_type, issues_root)
-        for status_dir in ["open", "backlog", "closed"]:
+        status_dirs = ["open", "backlog", "closed"]
+        if include_archived:
+            status_dirs.append("archived")
+        
+        for status_dir in status_dirs:
             d = base_dir / status_dir
             if d.exists():
                 for f in d.rglob("*.md"):
@@ -1210,6 +1404,56 @@ def update_issue_content(
             os.unlink(tmp_path)
 
 
+def update_issue_field(
+    issue_path: Path,
+    field: str,
+    value: Any,
+) -> IssueMetadata:
+    """
+    Update a specific field in an issue's frontmatter.
+
+    Args:
+        issue_path: Path to the issue file
+        field: Field name to update
+        value: New value for the field
+
+    Returns:
+        Updated IssueMetadata
+    """
+    # Read full content
+    content = issue_path.read_text()
+
+    # Split Frontmatter and Body
+    match = re.search(r"^---(.*?)---\n(.*)", content, re.DOTALL | re.MULTILINE)
+    if not match:
+        raise ValueError(f"Could not parse frontmatter for {issue_path}")
+
+    yaml_str = match.group(1)
+    body = match.group(2)
+
+    try:
+        data = yaml.safe_load(yaml_str) or {}
+    except yaml.YAMLError as e:
+        raise ValueError(f"Invalid YAML metadata: {e}")
+
+    # Update the field
+    data[field] = value
+    data["updated_at"] = current_time()
+
+    # Serialize back directly (not through model) to preserve all fields
+    yaml_header = yaml.dump(
+        data, sort_keys=False, allow_unicode=True, default_flow_style=False
+    )
+
+    # Reconstruct File
+    new_content = f"---\n{yaml_header}---\n{body}"
+    issue_path.write_text(new_content)
+
+    # Re-hydrate through Model to validate and return
+    updated_meta = IssueMetadata(**data)
+    return updated_meta
+
+
 def generate_delivery_report(
     issues_root: Path, issue_id: str, project_root: Path
 ) -> IssueMetadata:
@@ -1397,10 +1641,15 @@ def check_issue_match(
     return True
 
 
-def search_issues(issues_root: Path, query: str) -> List[IssueMetadata]:
+def search_issues(issues_root: Path, query: str, include_archived: bool = False) -> List[IssueMetadata]:
     """
     Search issues using advanced query syntax.
     Returns list of matching IssueMetadata.
+    
+    Args:
+        issues_root: Root directory of issues
+        query: Search query string
+        include_archived: Include archived issues in search (default: False)
     """
     explicit_positives, terms, negatives = parse_search_query(query)
 
@@ -1410,7 +1659,7 @@ def search_issues(issues_root: Path, query: str) -> List[IssueMetadata]:
     # Let's align with "grep": empty pattern matches everything?
     # Or strict: empty query -> all.
     if not explicit_positives and not terms and not negatives:
-        return list_issues(issues_root)
+        return list_issues(issues_root, include_archived=include_archived)
 
     matches = []
     all_files = []
@@ -1430,7 +1679,11 @@ def search_issues(issues_root: Path, query: str) -> List[IssueMetadata]:
 
     for issue_type in all_types:
         base_dir = get_issue_dir(issue_type, issues_root)
-        for status_dir in ["open", "backlog", "closed"]:
+        status_dirs = ["open", "backlog", "closed"]
+        if include_archived:
+            status_dirs.append("archived")
+        
+        for status_dir in status_dirs:
             d = base_dir / status_dir
             if d.exists():
                 for f in d.rglob("*.md"):

monoco/features/issue/engine/machine.py

@@ -79,6 +79,113 @@ class StateMachine:
             allowed.append(t)
         return allowed
 
+    def get_available_solutions(self, from_status: str, from_stage: Optional[str]) -> List[str]:
+        """Get all valid solutions for transitions from the current state."""
+        solutions = set()
+        for t in self.transitions:
+            # Skip non-transitions (agent actions with same status/stage)
+            if t.from_status is None and t.from_stage is None:
+                continue
+
+            if t.from_status and t.from_status != from_status:
+                continue
+            if t.from_stage and t.from_stage != from_stage:
+                continue
+
+            if t.required_solution:
+                solutions.add(t.required_solution)
+        return sorted(list(solutions))
+
+    def get_valid_transitions_from_state(
+        self, from_status: str, from_stage: Optional[str]
+    ) -> List[TransitionConfig]:
+        """Get all valid transitions from a given state."""
+        valid = []
+        for t in self.transitions:
+            # Skip non-transitions (agent actions with same status/stage)
+            if t.from_status is None and t.from_stage is None:
+                continue
+
+            if t.from_status and t.from_status != from_status:
+                continue
+            if t.from_stage and t.from_stage != from_stage:
+                continue
+
+            valid.append(t)
+        return valid
+
+    def _format_state(self, status: str, stage: Optional[str]) -> str:
+        """Format a state for display in error messages."""
+        # Handle Enum values
+        if hasattr(status, 'value'):
+            status = status.value
+        if stage and hasattr(stage, 'value'):
+            stage = stage.value
+        
+        if stage:
+            return f"{status}({stage})"
+        return status
+
+    def _build_transition_not_found_error(
+        self,
+        from_status: str,
+        from_stage: Optional[str],
+        to_status: str,
+        to_stage: Optional[str],
+    ) -> str:
+        """Build a descriptive error message when no transition is found."""
+        current_state = self._format_state(from_status, from_stage)
+        target_state = self._format_state(to_status, to_stage)
+
+        error_msg = (
+            f"Lifecycle Policy: Transition from '{current_state}' "
+            f"to '{target_state}' is not defined."
+        )
+
+        # Add available transitions hint
+        valid_transitions = self.get_valid_transitions_from_state(from_status, from_stage)
+        if valid_transitions:
+            error_msg += " Available transitions from this state:"
+            for t in valid_transitions:
+                target = self._format_state(t.to_status, t.to_stage)
+                if t.required_solution:
+                    error_msg += f"\n  - {t.name}: '{current_state}' -> '{target}' (requires --solution {t.required_solution})"
+                else:
+                    error_msg += f"\n  - {t.name}: '{current_state}' -> '{target}'"
+        else:
+            error_msg += " No transitions are available from this state."
+
+        return error_msg
+
+    def _build_invalid_solution_error(
+        self,
+        transition: TransitionConfig,
+        provided_solution: Optional[str],
+        from_status: str,
+        from_stage: Optional[str],
+    ) -> str:
+        """Build a descriptive error message when solution is invalid or missing."""
+        current_state = self._format_state(from_status, from_stage)
+        target_state = self._format_state(transition.to_status, transition.to_stage)
+
+        if provided_solution:
+            error_msg = (
+                f"Lifecycle Policy: Transition '{transition.label}' from '{current_state}' "
+                f"to '{target_state}' does not accept solution '{provided_solution}'."
+            )
+        else:
+            error_msg = (
+                f"Lifecycle Policy: Transition '{transition.label}' from '{current_state}' "
+                f"to '{target_state}' requires a solution."
+            )
+
+        # Get valid solutions for this transition
+        valid_solutions = self.get_available_solutions(from_status, from_stage)
+        if valid_solutions:
+            error_msg += f" Valid solutions are: {', '.join(valid_solutions)}."
+
+        return error_msg
+
     def find_transition(
         self,
         from_status: str,
@@ -134,13 +241,14 @@ class StateMachine:
         to_stage: Optional[str],
         solution: Optional[str] = None,
         meta: Optional[IssueMetadata] = None,
-    ) -> None:
+    ) -> TransitionConfig:
         """
         Validate if a transition is allowed. Raises ValueError if not.
         If meta is provided, also validates criticality-based policies.
+        Returns the TransitionConfig if a transition occurred, None if no change.
         """
         if from_status == to_status and from_stage == to_stage:
-            return  # No change is always allowed (unless we want to enforce specific updates)
+            return None  # No change is always allowed (unless we want to enforce specific updates)
 
         transition = self.find_transition(
             from_status, from_stage, to_status, to_stage, solution
@@ -148,18 +256,23 @@ class StateMachine:
 
         if not transition:
             raise ValueError(
-                f"Lifecycle Policy: Transition from {from_status}({from_stage if from_stage else 'None'}) "
-                f"to {to_status}({to_stage if to_stage else 'None'}) is not defined."
+                self._build_transition_not_found_error(
+                    from_status, from_stage, to_status, to_stage
+                )
             )
 
         if transition.required_solution and solution != transition.required_solution:
             raise ValueError(
-                f"Lifecycle Policy: Transition '{transition.label}' requires solution '{transition.required_solution}'."
+                self._build_invalid_solution_error(
+                    transition, solution, from_status, from_stage
+                )
             )
 
         # Criticality-based policy checks
         if meta and meta.criticality:
             self._validate_criticality_policy(meta, from_stage, to_stage)
+            
+        return transition
 
     def _validate_criticality_policy(
         self,