monoco-toolkit 0.3.3__py3-none-any.whl → 0.3.6__py3-none-any.whl

monoco/features/issue/commands.py

@@ -267,10 +267,6 @@ def start(
 @app.command("submit")
 def submit(
     issue_id: str = typer.Argument(..., help="Issue ID to submit"),
-    prune: bool = typer.Option(
-        False, "--prune", help="Delete branch/worktree after submit"
-    ),
-    force: bool = typer.Option(False, "--force", help="Force delete branch/worktree"),
     root: Optional[str] = typer.Option(
         None, "--root", help="Override issues root directory"
     ),
@@ -292,22 +288,11 @@ def submit(
         except Exception as e:
             report_status = f"failed: {e}"
 
-        pruned_resources = []
-        if prune:
-            try:
-                pruned_resources = core.prune_issue_resources(
-                    issues_root, issue_id, force, project_root
-                )
-            except Exception as e:
-                OutputManager.error(f"Prune Error: {e}")
-                raise typer.Exit(code=1)
-
         OutputManager.print(
             {
                 "issue": issue,
                 "status": "submitted",
                 "report": report_status,
-                "pruned": pruned_resources,
             }
         )
 

monoco/features/issue/core.py

@@ -221,6 +221,10 @@ def create_issue_file(
         if not find_issue_path(issues_root, rel_id):
             raise ValueError(f"Related issue {rel_id} not found.")
 
+    # Auto-assign default parent for non-epic types if not provided
+    if issue_type != IssueType.EPIC and not parent:
+        parent = "EPIC-0000"
+
     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

monoco/features/issue/engine/machine.py

@@ -169,35 +169,6 @@ class StateMachine:
             if meta.stage is None:
                 meta.stage = "draft"
 
-    def validate_transition(
-        self,
-        from_status: str,
-        from_stage: Optional[str],
-        to_status: str,
-        to_stage: Optional[str],
-        solution: Optional[str] = None,
-    ) -> None:
-        """
-        Validate if a transition is allowed. Raises ValueError if not.
-        """
-        if from_status == to_status and from_stage == to_stage:
-            return  # 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
-        )
-
-        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."
-            )
-
-        if transition.required_solution and solution != transition.required_solution:
-            raise ValueError(
-                f"Lifecycle Policy: Transition '{transition.label}' requires solution '{transition.required_solution}'."
-            )
-
     def enforce_policy(self, meta: IssueMetadata) -> None:
         """
         Apply consistency rules to IssueMetadata.

monoco/features/issue/linter.py

@@ -4,7 +4,7 @@ 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, Range, Position
@@ -12,36 +12,8 @@ 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]:
@@ -77,7 +49,7 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
                             all_issue_ids.add(local_id)
                             all_issue_ids.add(full_id)
 
-                            project_issues.append((f, meta))
+                            project_issues.append((f, meta, project_name))
                     except Exception as e:
                         # Report parsing failure as diagnostic
                         d = Diagnostic(
@@ -93,8 +65,6 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
                         diagnostics.append(d)
         return project_issues
 
-    from monoco.core.config import get_config
-
     conf = get_config(str(issues_root.parent))
 
     # Identify local project name
@@ -110,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))
 
@@ -140,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:
@@ -172,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 = []
 
@@ -215,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:

monoco/features/issue/models.py

@@ -1,6 +1,6 @@
 from enum import Enum
 from typing import List, Optional, Any, Dict
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, Field, model_validator, ConfigDict
 from datetime import datetime
 import hashlib
 import secrets
@@ -105,13 +105,13 @@ class IssueAction(BaseModel):
 
 
 class IssueMetadata(BaseModel):
-    model_config = {"extra": "allow"}
+    model_config = ConfigDict(extra="allow", validate_assignment=True)
 
     id: str
     uid: Optional[str] = None  # Global unique identifier for cross-project identity
-    type: str
-    status: str = "open"
-    stage: Optional[str] = None
+    type: IssueType
+    status: IssueStatus = IssueStatus.OPEN
+    stage: Optional[IssueStage] = None
     title: str
 
     # Time Anchors
@@ -122,7 +122,7 @@ class IssueMetadata(BaseModel):
 
     parent: Optional[str] = None
     sprint: Optional[str] = None
-    solution: Optional[str] = None
+    solution: Optional[IssueSolution] = None
     isolation: Optional[IssueIsolation] = None
     dependencies: List[str] = []
     related: List[str] = []
@@ -161,26 +161,56 @@ class IssueMetadata(BaseModel):
             # Normalize type and status to lowercase for compatibility
             if "type" in v and isinstance(v["type"], str):
                 v["type"] = v["type"].lower()
+                try:
+                    v["type"] = IssueType(v["type"])
+                except ValueError:
+                    pass
+
             if "status" in v and isinstance(v["status"], str):
                 v["status"] = v["status"].lower()
+                try:
+                    v["status"] = IssueStatus(v["status"])
+                except ValueError:
+                    pass
+
             if "solution" in v and isinstance(v["solution"], str):
                 v["solution"] = v["solution"].lower()
+                try:
+                    v["solution"] = IssueSolution(v["solution"])
+                except ValueError:
+                    pass
+
             # 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:
+                    pass
         return v
 
     @model_validator(mode="after")
     def validate_lifecycle(self) -> "IssueMetadata":
-        # Logic Definition:
-        # status: backlog -> stage: freezed
-        # status: closed -> stage: done
-        # status: open -> stage: draft | doing | review | done (default draft)
-
-        # NOTE: We do NOT auto-correct state here anymore to allow Linter to detect inconsistencies.
-        # Auto-correction should be applied explicitly by 'create' or 'update' commands via core logic.
+        # 1. Solution Consistency: Closed issues MUST have a solution
+        if self.status == IssueStatus.CLOSED and not self.solution:
+            raise ValueError(f"Issue '{self.id}' is closed but 'solution' is missing.")
+
+        # 2. Hierarchy Consistency: non-epic types MUST have a parent (except specific root seeds)
+        if self.type != IssueType.EPIC and not self.parent:
+            # We allow exceptions for very specific bootstrap cases if needed, but currently enforce it.
+            if self.id not in ["FEAT-BOOTSTRAP"]:  # Example exception
+                raise ValueError(
+                    f"Issue '{self.id}' of type '{self.type}' must have a 'parent' reference."
+                )
+
+        # 3. State/Stage Consistency (Warnings or Errors)
+        # Note: In Monoco, status: closed is tightly coupled with stage: done
+        if self.status == IssueStatus.CLOSED and self.stage != IssueStage.DONE:
+            # We could auto-fix here, but let's be strict for Validation purposes
+            # raise ValueError(f"Issue '{self.id}' is closed but stage is '{self.stage}' (expected 'done').")
+            pass
 
         return self
 

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,103 @@
+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"],
+        parent="EPIC-0000",
+    )
+
+    # 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