monoco-toolkit 0.3.2__py3-none-any.whl → 0.3.5__py3-none-any.whl

monoco/features/issue/linter.py

@@ -4,44 +4,16 @@ from rich.console import Console
 from rich.table import Table
 import typer
 import re
-from monoco.core import git
+from monoco.core.config import get_config
 from . import core
 from .validator import IssueValidator
-from monoco.core.lsp import Diagnostic, DiagnosticSeverity
+from monoco.core.lsp import Diagnostic, DiagnosticSeverity, Range, Position
 
 console = Console()
 
 
-def check_environment_policy(project_root: Path):
-    """
-    Guardrail: Prevent direct modifications on protected branches (main/master).
-    """
-    # Only enforce if it is a git repo
-    try:
-        if not git.is_git_repo(project_root):
-            return
-
-        current_branch = git.get_current_branch(project_root)
-        # Standard protected branches
-        if current_branch in ["main", "master", "production"]:
-            # Check if dirty (uncommitted changes)
-            changed_files = git.get_git_status(project_root)
-            if changed_files:
-                console.print("\n[bold red]🛑 Environment Policy Violation[/bold red]")
-                console.print(
-                    f"You are modifying code directly on protected branch: [bold cyan]{current_branch}[/bold cyan]"
-                )
-                console.print(f"Found {len(changed_files)} uncommitted changes.")
-                console.print(
-                    "[yellow]Action Required:[/yellow] Please stash your changes and switch to a feature branch."
-                )
-                console.print("  > git stash")
-                console.print("  > monoco issue start <ID> --branch")
-                console.print("  > git stash pop")
-                raise typer.Exit(code=1)
-    except Exception:
-        # Fail safe: Do not block linting if git check fails unexpectedly
-        pass
+# Removed check_environment_policy as per project philosophy:
+# Toolkit should not interfere with Git operations.
 
 
 def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnostic]:
@@ -68,19 +40,31 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
                         files.extend(status_dir.rglob("*.md"))
 
                 for f in files:
-                    meta = core.parse_issue(f)
-                    if meta:
-                        local_id = meta.id
-                        full_id = f"{project_name}::{local_id}"
-
-                        all_issue_ids.add(local_id)
-                        all_issue_ids.add(full_id)
-
-                        project_issues.append((f, meta))
+                    try:
+                        meta = core.parse_issue(f, raise_error=True)
+                        if meta:
+                            local_id = meta.id
+                            full_id = f"{project_name}::{local_id}"
+
+                            all_issue_ids.add(local_id)
+                            all_issue_ids.add(full_id)
+
+                            project_issues.append((f, meta, project_name))
+                    except Exception as e:
+                        # Report parsing failure as diagnostic
+                        d = Diagnostic(
+                            range=Range(
+                                start=Position(line=0, character=0),
+                                end=Position(line=0, character=0),
+                            ),
+                            message=f"Schema Error: {str(e)}",
+                            severity=DiagnosticSeverity.Error,
+                            source="System",
+                        )
+                        d.data = {"path": f}
+                        diagnostics.append(d)
         return project_issues
 
-    from monoco.core.config import get_config
-
     conf = get_config(str(issues_root.parent))
 
     # Identify local project name
@@ -96,6 +80,17 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
         ).exists():
             workspace_root = parent
 
+    # Identify local project name
+    local_project_name = "local"
+    if conf and conf.project and conf.project.name:
+        local_project_name = conf.project.name.lower()
+
+    workspace_root_name = local_project_name
+    if workspace_root != issues_root.parent:
+        root_conf = get_config(str(workspace_root))
+        if root_conf and root_conf.project and root_conf.project.name:
+            workspace_root_name = root_conf.project.name.lower()
+
     # Collect from local issues_root
     all_issues.extend(collect_project_issues(issues_root, local_project_name))
 
@@ -126,11 +121,17 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
             pass
 
     # 2. Validation Phase
-    for path, meta in all_issues:
+    for path, meta, project_name in all_issues:
         content = path.read_text()  # Re-read content for validation
 
         # A. Run Core Validator
-        file_diagnostics = validator.validate(meta, content, all_issue_ids)
+        file_diagnostics = validator.validate(
+            meta,
+            content,
+            all_issue_ids,
+            current_project=project_name,
+            workspace_root=workspace_root_name,
+        )
 
         # Add context to diagnostics (Path)
         for d in file_diagnostics:
@@ -158,9 +159,8 @@ def run_lint(
         format: Output format (table, json)
         file_paths: Optional list of paths to files to validate (LSP/Pre-commit mode)
     """
-    # 0. Environment Policy Check (Guardrail)
-    # We assume issues_root.parent is the project root or close enough for git context
-    check_environment_policy(issues_root.parent)
+    # No environment policy check here.
+    # Toolkit should remain focused on Issue integrity.
 
     diagnostics = []
 
@@ -193,7 +193,7 @@ def run_lint(
 
             # Parse and validate file
             try:
-                meta = core.parse_issue(file)
+                meta = core.parse_issue(file, raise_error=True)
                 if not meta:
                     console.print(
                         f"[yellow]Warning:[/yellow] Failed to parse issue metadata from {file_path}. Skipping."
@@ -201,7 +201,16 @@ def run_lint(
                     continue
 
                 content = file.read_text()
-                file_diagnostics = validator.validate(meta, content, all_issue_ids)
+
+                # Try to resolve current project name for context
+                current_project_name = "local"
+                conf = get_config(str(issues_root.parent))
+                if conf and conf.project and conf.project.name:
+                    current_project_name = conf.project.name.lower()
+
+                file_diagnostics = validator.validate(
+                    meta, content, all_issue_ids, current_project=current_project_name
+                )
 
                 # Add context
                 for d in file_diagnostics:
@@ -315,6 +324,36 @@ def run_lint(
                                 new_content = "\n".join(lines) + "\n"
                                 has_changes = True
 
+                    if (
+                        "Hierarchy Violation" in d.message
+                        and "Epics must have a parent" in d.message
+                    ):
+                        try:
+                            fm_match = re.search(
+                                r"^---(.*?)---", new_content, re.DOTALL | re.MULTILINE
+                            )
+                            if fm_match:
+                                import yaml
+
+                                fm_text = fm_match.group(1)
+                                data = yaml.safe_load(fm_text) or {}
+
+                                # Default to EPIC-0000
+                                data["parent"] = "EPIC-0000"
+
+                                new_fm_text = yaml.dump(
+                                    data, sort_keys=False, allow_unicode=True
+                                )
+                                # Replace FM block
+                                new_content = new_content.replace(
+                                    fm_match.group(1), "\n" + new_fm_text
+                                )
+                                has_changes = True
+                        except Exception as ex:
+                            console.print(
+                                f"[red]Failed to fix parent hierarchy: {ex}[/red]"
+                            )
+
                     if "Tag Check: Missing required context tags" in d.message:
                         # Extract missing tags from message
                         # Message format: "Tag Check: Missing required context tags: #TAG1, #TAG2"
@@ -426,6 +465,70 @@ def run_lint(
             except Exception as e:
                 console.print(f"[red]Failed to fix domains for {path.name}: {e}[/red]")
 
+            # Domain Alias Fix
+            try:
+                alias_fixes = [
+                    d for d in current_file_diags if "Domain Alias:" in d.message
+                ]
+                if alias_fixes:
+                    fm_match = re.search(
+                        r"^---(.*?)---", new_content, re.DOTALL | re.MULTILINE
+                    )
+                    if fm_match:
+                        import yaml
+
+                        fm_text = fm_match.group(1)
+                        data = yaml.safe_load(fm_text) or {}
+
+                        domain_changed = False
+                        if "domains" in data and isinstance(data["domains"], list):
+                            domains = data["domains"]
+                            for d in alias_fixes:
+                                # Parse message: Domain Alias: 'alias' is an alias for 'canonical'.
+                                m = re.search(
+                                    r"Domain Alias: '([^']+)' is an alias for '([^']+)'",
+                                    d.message,
+                                )
+                                if m:
+                                    old_d = m.group(1)
+                                    new_d = m.group(2)
+
+                                    if old_d in domains:
+                                        domains = [
+                                            new_d if x == old_d else x for x in domains
+                                        ]
+                                        domain_changed = True
+
+                            if domain_changed:
+                                data["domains"] = domains
+                                new_fm_text = yaml.dump(
+                                    data, sort_keys=False, allow_unicode=True
+                                )
+                                new_content = new_content.replace(
+                                    fm_match.group(1), "\n" + new_fm_text
+                                )
+                                has_changes = True
+
+                                # Write immediately if not handled by previous block?
+                                # We are in standard flow where has_changes flag handles write at end of loop?
+                                # Wait, the previous block (Missing domains) logic wrote internally ONLY if has_changes.
+                                # AND it reset has_changes=False at start of try?
+                                # Actually the previous block structure was separate try-except blocks.
+                                # But here I am inserting AFTER the Missing Domains try-except (which was lines 390-442).
+                                # But I need to write if I changed it.
+                                path.write_text(new_content)
+                                if not any(path == p for p in processed_paths):
+                                    fixed_count += 1
+                                    processed_paths.add(path)
+                                console.print(
+                                    f"[dim]Fixed (Domain Alias): {path.name}[/dim]"
+                                )
+
+            except Exception as e:
+                console.print(
+                    f"[red]Failed to fix domain aliases for {path.name}: {e}[/red]"
+                )
+
         console.print(f"[green]Applied auto-fixes to {fixed_count} files.[/green]")
 
         # Re-run validation to verify

monoco/features/issue/resolver.py

@@ -0,0 +1,177 @@
+"""
+Reference Resolution Engine for Multi-Project Environments.
+
+This module implements a priority-based resolution strategy for Issue ID references
+in multi-project/workspace environments.
+
+Resolution Priority:
+1. Explicit Namespace (namespace::ID) - Highest priority
+2. Proximity Rule (Current Project Context)
+3. Root Fallback (Workspace Root)
+"""
+
+from typing import Optional, Set, Dict
+from dataclasses import dataclass
+
+
+@dataclass
+class ResolutionContext:
+    """Context information for reference resolution."""
+
+    current_project: str
+    """Name of the current project (e.g., 'toolkit', 'typedown')."""
+
+    workspace_root: Optional[str] = None
+    """Name of the workspace root project (e.g., 'monoco')."""
+
+    available_ids: Set[str] = None
+    """Set of all available Issue IDs (both local and namespaced)."""
+
+    def __post_init__(self):
+        if self.available_ids is None:
+            self.available_ids = set()
+
+
+class ReferenceResolver:
+    """
+    Resolves Issue ID references with multi-project awareness.
+
+    Supports:
+    - Explicit namespace syntax: `namespace::ID`
+    - Proximity-based resolution
+    - Root fallback for global issues
+    """
+
+    def __init__(self, context: ResolutionContext):
+        self.context = context
+
+        # Build index for fast lookup
+        self._local_ids: Set[str] = set()
+        self._namespaced_ids: Dict[str, Set[str]] = {}
+
+        for issue_id in context.available_ids:
+            if "::" in issue_id:
+                # Namespaced ID
+                namespace, local_id = issue_id.split("::", 1)
+                if namespace not in self._namespaced_ids:
+                    self._namespaced_ids[namespace] = set()
+                self._namespaced_ids[namespace].add(local_id)
+            else:
+                # Local ID
+                self._local_ids.add(issue_id)
+
+    def resolve(self, reference: str) -> Optional[str]:
+        """
+        Resolve an Issue ID reference to its canonical form.
+
+        Args:
+            reference: The reference to resolve (e.g., "FEAT-0001" or "toolkit::FEAT-0001")
+
+        Returns:
+            The canonical ID if found, None otherwise.
+            For namespaced IDs, returns the full form (e.g., "toolkit::FEAT-0001").
+            For local IDs, returns the short form (e.g., "FEAT-0001").
+
+        Resolution Strategy:
+        1. If reference contains "::", treat as explicit namespace
+        2. Otherwise, apply proximity rule:
+           a. Check current project context
+           b. Check workspace root (if different from current)
+           c. Check if exists as local ID
+        """
+        # Strategy 1: Explicit Namespace
+        if "::" in reference:
+            return self._resolve_explicit(reference)
+
+        # Strategy 2: Proximity Rule
+        return self._resolve_proximity(reference)
+
+    def _resolve_explicit(self, reference: str) -> Optional[str]:
+        """Resolve explicitly namespaced reference."""
+        if reference in self.context.available_ids:
+            return reference
+        return None
+
+    def _resolve_proximity(self, reference: str) -> Optional[str]:
+        """
+        Resolve reference using proximity rule.
+
+        Priority:
+        1. Current project namespace
+        2. Workspace root namespace
+        3. Local (unnamespaced) ID
+        """
+        # Priority 1: Current project
+        current_namespaced = f"{self.context.current_project}::{reference}"
+        if current_namespaced in self.context.available_ids:
+            return current_namespaced
+
+        # Priority 2: Workspace root (if different from current)
+        if (
+            self.context.workspace_root
+            and self.context.workspace_root != self.context.current_project
+        ):
+            root_namespaced = f"{self.context.workspace_root}::{reference}"
+            if root_namespaced in self.context.available_ids:
+                return root_namespaced
+
+        # Priority 3: Local ID
+        if reference in self._local_ids:
+            return reference
+
+        return None
+
+    def is_valid_reference(self, reference: str) -> bool:
+        """Check if a reference can be resolved."""
+        return self.resolve(reference) is not None
+
+    def get_resolution_chain(self, reference: str) -> list[str]:
+        """
+        Get the resolution chain for debugging purposes.
+
+        Returns a list of candidate IDs that were checked in order.
+        """
+        chain = []
+
+        if "::" in reference:
+            chain.append(reference)
+        else:
+            # Proximity chain
+            chain.append(f"{self.context.current_project}::{reference}")
+
+            if (
+                self.context.workspace_root
+                and self.context.workspace_root != self.context.current_project
+            ):
+                chain.append(f"{self.context.workspace_root}::{reference}")
+
+            chain.append(reference)
+
+        return chain
+
+
+def resolve_reference(
+    reference: str,
+    context_project: str,
+    available_ids: Set[str],
+    workspace_root: Optional[str] = None,
+) -> Optional[str]:
+    """
+    Convenience function for resolving a single reference.
+
+    Args:
+        reference: The Issue ID to resolve
+        context_project: Current project name
+        available_ids: Set of all available Issue IDs
+        workspace_root: Optional workspace root project name
+
+    Returns:
+        Resolved canonical ID or None if not found
+    """
+    context = ResolutionContext(
+        current_project=context_project,
+        workspace_root=workspace_root,
+        available_ids=available_ids,
+    )
+    resolver = ReferenceResolver(context)
+    return resolver.resolve(reference)

monoco/features/issue/resources/en/AGENTS.md

@@ -11,10 +11,12 @@ System for managing tasks using `monoco issue`.
 - **Sync Context**: `monoco issue sync-files [id]` (Update file tracking)
 - **Structure**: `Issues/{CapitalizedPluralType}/{lowercase_status}/` (e.g. `Issues/Features/open/`). Do not deviate.
 - **Rules**:
-  1. **Heading**: Must have `## {ID}: {Title}` (matches metadata).
-  2. **Checkboxes**: Min 2 using `- [ ]`, `- [x]`, `- [-]`, `- [/]`.
-  3. **Review**: `## Review Comments` section required for Review/Done stages.
-  4. **Environment Policies**:
+  1. **Issue First**: You MUST create an Issue (`monoco issue create`) before starting any work (research, design, or drafting).
+  2. **Heading**: Must have `## {ID}: {Title}` (matches metadata).
+  3. **Checkboxes**: Min 2 using `- [ ]`, `- [x]`, `- [-]`, `- [/]`.
+  4. **Review**: `## Review Comments` section required for Review/Done stages.
+  5. **Environment Policies**:
      - Must use `monoco issue start --branch`.
      - 🛑 **NO** direct coding on `main`/`master` (Linter will fail).
+     - **Prune Timing**: ONLY prune environment (branch/worktree) during `monoco issue close --prune`. NEVER prune at `submit` stage.
      - Must update `files` field after coding (via `sync-files` or manual).

monoco/features/issue/resources/zh/AGENTS.md

@@ -11,10 +11,12 @@
 - **上下文同步**: `monoco issue sync-files [id]` (更新文件追踪)
 - **结构**: `Issues/{CapitalizedPluralType}/{lowercase_status}/` (如 `Issues/Features/open/`)。
 - **强制规则**:
-  1. **标题**: 必须包含 `## {ID}: {Title}` 标题（与 Front Matter 一致）。
-  2. **内容**: 至少 2 个 Checkbox，使用 `- [ ]`, `- [x]`, `- [-]`, `- [/]`。
-  3. **评审**: `review`/`done` 阶段必须包含 `## Review Comments` 章节且内容不为空。
-  4. **环境策略**:
+  1. **先有 Issue**: 在进行任何调研、设计或 Draft 之前，必须先使用 `monoco issue create` 创建 Issue。
+  2. **标题**: 必须包含 `## {ID}: {Title}` 标题（与 Front Matter 一致）。
+  3. **内容**: 至少 2 个 Checkbox，使用 `- [ ]`, `- [x]`, `- [-]`, `- [/]`。
+  4. **评审**: `review`/`done` 阶段必须包含 `## Review Comments` 章节且内容不为空。
+  5. **环境策略**:
      - 必须使用 `monoco issue start --branch` 创建 Feature 分支。
      - 🛑 **禁止**直接在 `main`/`master` 分支修改代码 (Linter 会报错)。
+     - **清理时机**: 环境清理仅应在 `close` 时执行。**禁止**在 `submit` 阶段清理环境。
      - 修改代码后**必须**更新 `files` 字段（通过 `sync-files` 或手动）。

monoco/features/issue/test_priority_integration.py

@@ -0,0 +1,102 @@
+from monoco.features.issue.validator import IssueValidator
+from monoco.features.issue.models import IssueMetadata
+from datetime import datetime
+
+
+def test_validator_namespaced_reference_in_body():
+    validator = IssueValidator()
+    meta = IssueMetadata(
+        id="FEAT-0001",
+        uid="123456",
+        type="feature",
+        status="open",
+        stage="draft",
+        title="Test Issue",
+        created_at=datetime.now(),
+        opened_at=datetime.now(),
+        updated_at=datetime.now(),
+        domains=["intelligence"],
+    )
+
+    # Context: toolkit project, monoco workspace
+    # Available IDs include namespaced versions
+    all_ids = {"monoco::EPIC-0001", "toolkit::FEAT-0002"}
+
+    # 1. Test namespaced reference in body
+    content = """---
+id: FEAT-0001
+title: Test Issue
+---
+
+## FEAT-0001: Test Issue
+
+This depends on monoco::EPIC-0001 and toolkit::FEAT-0002.
+Broken one: other::FIX-9999.
+"""
+
+    diagnostics = validator.validate(
+        meta, content, all_ids, current_project="toolkit", workspace_root="monoco"
+    )
+
+    # Should have 1 warning for other::FIX-9999
+    warnings = [d for d in diagnostics if "Broken Reference" in d.message]
+    assert len(warnings) == 1
+    assert "other::FIX-9999" in warnings[0].message
+
+    # 2. Test proximity resolution in body
+    content_proximity = """---
+id: FEAT-0001
+title: Test Issue
+---
+
+## FEAT-0001: Test Issue
+
+Referencing EPIC-0001 (should resolve to monoco::EPIC-0001 via root fallback).
+Referencing FEAT-0002 (should resolve to toolkit::FEAT-0002 via proximity).
+"""
+
+    diagnostics = validator.validate(
+        meta,
+        content_proximity,
+        all_ids,
+        current_project="toolkit",
+        workspace_root="monoco",
+    )
+
+    warnings = [d for d in diagnostics if "Broken Reference" in d.message]
+    assert len(warnings) == 0  # Both should be resolved
+
+
+def test_validator_parent_resolution():
+    validator = IssueValidator()
+    # Epic in toolkit
+    meta = IssueMetadata(
+        id="EPIC-0100",
+        uid="111",
+        type="epic",
+        status="open",
+        stage="draft",
+        title="Sub Epic",
+        parent="EPIC-0000",  # Root Epic in workspace root
+        created_at=datetime.now(),
+        opened_at=datetime.now(),
+        updated_at=datetime.now(),
+        domains=["intelligence"],
+    )
+
+    all_ids = {"monoco::EPIC-0000", "toolkit::EPIC-0100"}
+
+    content = """---
+id: EPIC-0100
+parent: EPIC-0000
+---
+"""
+
+    # Context: current=toolkit, root=monoco
+    diagnostics = validator.validate(
+        meta, content, all_ids, current_project="toolkit", workspace_root="monoco"
+    )
+
+    # Should be valid via root fallback
+    errors = [d for d in diagnostics if d.severity == 1]  # DiagnosticSeverity.Error
+    assert len(errors) == 0

monoco/features/issue/test_resolver.py

@@ -0,0 +1,83 @@
+from monoco.features.issue.resolver import ReferenceResolver, ResolutionContext
+
+
+def test_resolve_explicit_namespace():
+    context = ResolutionContext(
+        current_project="toolkit",
+        workspace_root="monoco",
+        available_ids={"toolkit::FEAT-0001", "monoco::FEAT-0001", "EPIC-0001"},
+    )
+    resolver = ReferenceResolver(context)
+
+    # Explicitly project reference
+    assert resolver.resolve("toolkit::FEAT-0001") == "toolkit::FEAT-0001"
+    assert resolver.resolve("monoco::FEAT-0001") == "monoco::FEAT-0001"
+
+    # Non-existent namespace
+    assert resolver.resolve("other::FEAT-0001") is None
+
+
+def test_resolve_proximity_current_project():
+    context = ResolutionContext(
+        current_project="toolkit",
+        workspace_root="monoco",
+        available_ids={
+            "toolkit::FEAT-0001",
+            "monoco::FEAT-0001",
+        },
+    )
+    resolver = ReferenceResolver(context)
+
+    # Should prefer current project
+    assert resolver.resolve("FEAT-0001") == "toolkit::FEAT-0001"
+
+
+def test_resolve_root_fallback():
+    context = ResolutionContext(
+        current_project="toolkit",
+        workspace_root="monoco",
+        available_ids={
+            "monoco::EPIC-0000",
+            "toolkit::FEAT-0001",
+        },
+    )
+    resolver = ReferenceResolver(context)
+
+    # Should fallback to root if not in current
+    assert resolver.resolve("EPIC-0000") == "monoco::EPIC-0000"
+
+
+def test_resolve_local_ids():
+    context = ResolutionContext(
+        current_project="toolkit",
+        workspace_root="monoco",
+        available_ids={
+            "EPIC-9999",
+        },
+    )
+    resolver = ReferenceResolver(context)
+
+    # Should resolve plain local IDs
+    assert resolver.resolve("EPIC-9999") == "EPIC-9999"
+
+
+def test_priority_order():
+    context = ResolutionContext(
+        current_project="toolkit",
+        workspace_root="monoco",
+        available_ids={"toolkit::FEAT-0001", "monoco::FEAT-0001", "FEAT-0001"},
+    )
+    resolver = ReferenceResolver(context)
+
+    # Order: toolkit::FEAT-0001 > monoco::FEAT-0001 > FEAT-0001
+    assert resolver.resolve("FEAT-0001") == "toolkit::FEAT-0001"
+
+    # If removed from toolkit context
+    context.available_ids.remove("toolkit::FEAT-0001")
+    resolver = ReferenceResolver(context)
+    assert resolver.resolve("FEAT-0001") == "monoco::FEAT-0001"
+
+    # If removed from root context
+    context.available_ids.remove("monoco::FEAT-0001")
+    resolver = ReferenceResolver(context)
+    assert resolver.resolve("FEAT-0001") == "FEAT-0001"