monoco-toolkit 0.3.10__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
 
 
@@ -952,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?
@@ -1003,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 = """
 ---
@@ -1068,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))
@@ -1079,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"):
@@ -1249,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:
@@ -1436,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)
 
@@ -1449,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 = []
@@ -1469,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,7 +241,7 @@ class StateMachine:
         to_stage: Optional[str],
         solution: Optional[str] = None,
         meta: Optional[IssueMetadata] = None,
-    ) -> Optional[TransitionConfig]:
+    ) -> TransitionConfig:
         """
         Validate if a transition is allowed. Raises ValueError if not.
         If meta is provided, also validates criticality-based policies.
@@ -149,13 +256,16 @@ 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

monoco/features/issue/linter.py

@@ -29,7 +29,7 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
 
     # 1. Collection Phase (Build Index)
     # Helper to collect issues from a project
-    def collect_project_issues(project_issues_root: Path, project_name: str = "local"):
+    def collect_project_issues(project_issues_root: Path, project_name: str = "local", include_archived: bool = False):
         project_issues = []
         project_diagnostics = []
         for subdir in ["Epics", "Features", "Chores", "Fixes", "Domains"]:
@@ -128,10 +128,30 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
                 else:
                     # Standard Issues (Epics/Features/etc)
                     files = []
-                    for status in ["open", "closed", "backlog"]:
-                        status_dir = d / status
-                        if status_dir.exists():
-                            files.extend(status_dir.rglob("*.md"))
+                    # Standard status directories
+                    status_dirs = ["open", "closed", "backlog"]
+                    # Include archived if requested (for full validation)
+                    if include_archived:
+                        status_dirs.append("archived")
+                    
+                    for item in d.iterdir():
+                        if item.is_dir():
+                            status = item.name.lower()
+                            if status in status_dirs:
+                                files.extend(item.rglob("*.md"))
+                            elif status != "archived": # archived is handled separately if include_archived
+                                # Report Illegal Directory immediately
+                                project_diagnostics.append(
+                                    Diagnostic(
+                                        range=Range(
+                                            start=Position(line=0, character=0),
+                                            end=Position(line=0, character=0),
+                                        ),
+                                        message=f"Illegal Directory: Issues should be in 'open/', 'closed/', or 'backlog/' directories, not '{status}/' directory.",
+                                        severity=DiagnosticSeverity.Error,
+                                        source="System",
+                                    )
+                                )
 
                     for f in files:
                         try:
@@ -283,12 +303,45 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
 
     # 2. Validation Phase
     valid_domains = set()
+    # Build list of actual IssueMetadata objects for domain governance checks
+    all_issue_metas = []
+    
     # Now validate
     for path, meta, project_name in all_issues:
         if meta == "DOMAIN":
             valid_domains.add(
                 project_name
             )  # Record the domain name (which was stored in project_name slot)
+        else:
+            all_issue_metas.append(meta)
+
+    # FEAT-0136: Project-Level Domain Governance Check
+    # Calculate scale metrics
+    num_issues = len(all_issue_metas)
+    num_epics = len([i for i in all_issue_metas if i.type == "epic"])
+    is_large_scale = num_issues > 128 or num_epics > 32
+    
+    # Check Domain Coverage for large-scale projects
+    if is_large_scale and num_epics > 0:
+        epics = [i for i in all_issue_metas if i.type == "epic"]
+        untracked_epics = [e for e in epics if not e.domains]
+        untracked_ratio = len(untracked_epics) / len(epics)
+        
+        # Rule: Untracked Epics / Total Epics <= 25%
+        if untracked_ratio > 0.25:
+            # Report this as a project-level diagnostic (attached to first epic or general)
+            diagnostics.append(
+                Diagnostic(
+                    range=Range(
+                        start=Position(line=0, character=0),
+                        end=Position(line=0, character=0),
+                    ),
+                    message=f"Domain Governance: Coverage is too low for a project of this scale ({len(untracked_epics)}/{len(epics)} Epics untracked). "
+                            f"At least 75% of Epics must have domains assigned.",
+                    severity=DiagnosticSeverity.Error,
+                    source="DomainGovernance",
+                )
+            )
 
     for path, meta, project_name in all_issues:
         if meta == "DOMAIN":
@@ -325,6 +378,7 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
 
         # A. Run Core Validator
         # Pass valid_domains kwarg (Validator needs update to accept it)
+        # FEAT-0136: Also pass all_issue_metas for domain governance checks
         file_diagnostics = validator.validate(
             meta,
             content,
@@ -332,6 +386,7 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
             current_project=project_name,
             workspace_root=workspace_root_name,
             valid_domains=valid_domains,
+            all_issues=all_issue_metas,
         )
 
         # Add context to diagnostics (Path)

monoco/features/issue/models.py

@@ -74,6 +74,7 @@ class IssueStatus(str, Enum):
     OPEN = "open"
     CLOSED = "closed"
     BACKLOG = "backlog"
+    ARCHIVED = "archived"
 
 
 class IssueStage(str, Enum):
@@ -223,8 +224,7 @@ class IssueMetadata(BaseModel):
             # Stage normalization
             if "stage" in v and isinstance(v["stage"], str):
                 v["stage"] = v["stage"].lower()
-                if v["stage"] == "todo":
-                    v["stage"] = "draft"
+
                 try:
                     v["stage"] = IssueStage(v["stage"])
                 except ValueError: