monoco-toolkit 0.2.7__py3-none-any.whl → 0.3.0__py3-none-any.whl

monoco/features/issue/lsp/definition.py

@@ -2,7 +2,8 @@ from pathlib import Path
 from typing import Optional, List
 from monoco.core.lsp import Location, Position, Range
 from ..domain.parser import MarkdownParser
-from ..domain.workspace import WorkspaceSymbolIndex, IssueLocation
+from ..domain.workspace import WorkspaceSymbolIndex
+
 
 class DefinitionProvider:
     def __init__(self, workspace_root: Path):
@@ -18,25 +19,29 @@ class DefinitionProvider:
             return []
 
         content = file_path.read_text()
-        
+
         # 1. Parse the document to find spans
         # We only need to find the span at the specific line
         issue = MarkdownParser.parse(content, path=str(file_path))
-        
+
         target_span = None
         for block in issue.body.blocks:
             # Check if position is within block
-             # Note: block.line_start is inclusive, line_end is exclusive for content
+            # Note: block.line_start is inclusive, line_end is exclusive for content
             if block.line_start <= position.line < block.line_end:
-                 for span in block.spans:
-                     if span.range.start.line == position.line:
-                         # Check character range
-                         if span.range.start.character <= position.character <= span.range.end.character:
-                             target_span = span
-                             break
+                for span in block.spans:
+                    if span.range.start.line == position.line:
+                        # Check character range
+                        if (
+                            span.range.start.character
+                            <= position.character
+                            <= span.range.end.character
+                        ):
+                            target_span = span
+                            break
             if target_span:
                 break
-        
+
         if not target_span:
             return []
 
@@ -45,28 +50,30 @@ class DefinitionProvider:
             issue_id = target_span.metadata.get("issue_id")
             if issue_id:
                 # Resolve using Workspace Index
-                location = self.index.resolve(issue_id, context_project=self._get_context_project(file_path))
+                location = self.index.resolve(
+                    issue_id, context_project=self._get_context_project(file_path)
+                )
                 if location:
                     return [
                         Location(
                             uri=f"file://{location.file_path}",
                             range=Range(
                                 start=Position(line=0, character=0),
-                                end=Position(line=0, character=0)
-                            )
+                                end=Position(line=0, character=0),
+                            ),
                         )
                     ]
-        
+
         return []
 
     def _get_context_project(self, file_path: Path) -> Optional[str]:
         # Simple heuristic: look for parent directory name if it's a known project structure?
-        # Or rely on configuration. 
+        # Or rely on configuration.
         # For now, let's assume the index handles context if passed, or we pass None.
         # Actually resolving context project from file path is tricky without config loaded for that specific root.
         # Let's try to deduce from path relative to workspace root.
         try:
-             rel = file_path.relative_to(self.workspace_root)
-             return rel.parts[0] # First dir is likely project name in a workspace
+            rel = file_path.relative_to(self.workspace_root)
+            return rel.parts[0]  # First dir is likely project name in a workspace
         except ValueError:
-             return "local"
+            return "local"

monoco/features/issue/migration.py

@@ -1,11 +1,7 @@
 import os
 import re
 import yaml
-import hashlib
-import secrets
 from pathlib import Path
-from typing import List, Dict, Any
-from datetime import datetime
 from .models import generate_uid
 
 # Migration Mappings
@@ -21,20 +17,13 @@ DIR_MAP = {
     "features": "Features",
     "chores": "Chores",
     "fixes": "Fixes",
-    "epics": "Epics"
+    "epics": "Epics",
 }
 
-TYPE_MAP = {
-    "story": "feature",
-    "task": "chore",
-    "bug": "fix"
-}
+TYPE_MAP = {"story": "feature", "task": "chore", "bug": "fix"}
+
+ID_PREFIX_MAP = {"STORY": "FEAT", "TASK": "CHORE", "BUG": "FIX"}
 
-ID_PREFIX_MAP = {
-    "STORY": "FEAT",
-    "TASK": "CHORE",
-    "BUG": "FIX"
-}
 
 def migrate_issues_directory(issues_dir: Path):
     """
@@ -48,7 +37,7 @@ def migrate_issues_directory(issues_dir: Path):
         old_path = issues_dir / old_name
         if old_path.exists():
             new_path = issues_dir / new_name
-            
+
             # Case sensitivity check for some filesystems
             same_inode = False
             try:
@@ -64,6 +53,7 @@ def migrate_issues_directory(issues_dir: Path):
 
             if new_path.exists():
                 import shutil
+
                 for item in old_path.iterdir():
                     dest = new_path / item.name
                     if dest.exists() and item.is_dir():
@@ -81,20 +71,37 @@ def migrate_issues_directory(issues_dir: Path):
         subdir = issues_dir / subdir_name
         if not subdir.exists():
             continue
-            
+
         for file_path in subdir.rglob("*.md"):
             content = file_path.read_text(encoding="utf-8")
             new_content = content
-            
+
             # Replace Type in Frontmatter
             for old_type, new_type in TYPE_MAP.items():
-                new_content = re.sub(rf"^type:\s*{old_type}", f"type: {new_type}", new_content, flags=re.IGNORECASE | re.MULTILINE)
-            
+                new_content = re.sub(
+                    rf"^type:\s*{old_type}",
+                    f"type: {new_type}",
+                    new_content,
+                    flags=re.IGNORECASE | re.MULTILINE,
+                )
+
             # Replace ID Prefixes
             for old_prefix, new_prefix in ID_PREFIX_MAP.items():
-                new_content = new_content.replace(f"[[{old_prefix}-", f"[[{new_prefix}-")
-                new_content = re.sub(rf"^id: {old_prefix}-", f"id: {new_prefix}-", new_content, flags=re.MULTILINE)
-                new_content = re.sub(rf"^parent: {old_prefix}-", f"parent: {new_prefix}-", new_content, flags=re.MULTILINE)
+                new_content = new_content.replace(
+                    f"[[{old_prefix}-", f"[[{new_prefix}-"
+                )
+                new_content = re.sub(
+                    rf"^id: {old_prefix}-",
+                    f"id: {new_prefix}-",
+                    new_content,
+                    flags=re.MULTILINE,
+                )
+                new_content = re.sub(
+                    rf"^parent: {old_prefix}-",
+                    f"parent: {new_prefix}-",
+                    new_content,
+                    flags=re.MULTILINE,
+                )
                 new_content = new_content.replace(f"{old_prefix}-", f"{new_prefix}-")
 
             # Structural Updates (UID, Stage)
@@ -104,18 +111,20 @@ def migrate_issues_directory(issues_dir: Path):
                 try:
                     data = yaml.safe_load(yaml_str) or {}
                     changed = False
-                    
-                    if 'uid' not in data:
-                        data['uid'] = generate_uid()
+
+                    if "uid" not in data:
+                        data["uid"] = generate_uid()
                         changed = True
-                        
-                    if 'stage' in data and data['stage'] == 'todo':
-                        data['stage'] = 'draft'
+
+                    if "stage" in data and data["stage"] == "todo":
+                        data["stage"] = "draft"
                         changed = True
-                            
+
                     if changed:
-                         new_yaml = yaml.dump(data, sort_keys=False, allow_unicode=True)
-                         new_content = new_content.replace(match.group(1), "\n" + new_yaml)
+                        new_yaml = yaml.dump(data, sort_keys=False, allow_unicode=True)
+                        new_content = new_content.replace(
+                            match.group(1), "\n" + new_yaml
+                        )
                 except yaml.YAMLError:
                     pass
 
@@ -127,8 +136,10 @@ def migrate_issues_directory(issues_dir: Path):
             new_filename = filename
             for old_prefix, new_prefix in ID_PREFIX_MAP.items():
                 if filename.startswith(f"{old_prefix}-"):
-                    new_filename = filename.replace(f"{old_prefix}-", f"{new_prefix}-", 1)
+                    new_filename = filename.replace(
+                        f"{old_prefix}-", f"{new_prefix}-", 1
+                    )
                     break
-            
+
             if new_filename != filename:
                 file_path.rename(file_path.parent / new_filename)

monoco/features/issue/models.py

@@ -10,6 +10,7 @@ class IssueID:
     """
     Helper for parsing Issue IDs that might be namespaced (e.g. 'toolkit::FEAT-0001').
     """
+
     def __init__(self, raw: str):
         self.raw = raw
         if "::" in raw:
@@ -22,7 +23,7 @@ class IssueID:
         if self.namespace:
             return f"{self.namespace}::{self.local_id}"
         return self.local_id
-        
+
     def __repr__(self):
         return f"IssueID({self.raw})"
 
@@ -34,9 +35,11 @@ class IssueID:
         """Check if this ID matches another ID string."""
         return str(self) == other_id or (self.is_local and self.local_id == other_id)
 
+
 def current_time() -> datetime:
     return datetime.now().replace(microsecond=0)
 
+
 def generate_uid() -> str:
     """
     Generate a globally unique 6-character short hash for issue identity.
@@ -55,11 +58,13 @@ class IssueType(str, Enum):
     CHORE = "chore"
     FIX = "fix"
 
+
 class IssueStatus(str, Enum):
     OPEN = "open"
     CLOSED = "closed"
     BACKLOG = "backlog"
 
+
 class IssueStage(str, Enum):
     DRAFT = "draft"
     DOING = "doing"
@@ -67,43 +72,48 @@ class IssueStage(str, Enum):
     DONE = "done"
     FREEZED = "freezed"
 
+
 class IssueSolution(str, Enum):
     IMPLEMENTED = "implemented"
     CANCELLED = "cancelled"
     WONTFIX = "wontfix"
     DUPLICATE = "duplicate"
 
+
 class IsolationType(str, Enum):
     BRANCH = "branch"
     WORKTREE = "worktree"
 
+
 class IssueIsolation(BaseModel):
     type: str
     ref: str  # Git branch name
     path: Optional[str] = None  # Worktree path (relative to repo root or absolute)
     created_at: datetime = Field(default_factory=current_time)
 
+
 class IssueAction(BaseModel):
     label: str
     target_status: Optional[str] = None
     target_stage: Optional[str] = None
     target_solution: Optional[str] = None
     icon: Optional[str] = None
-    
+
     # Generic execution extensions
     command: Optional[str] = None
     params: Dict[str, Any] = {}
 
+
 class IssueMetadata(BaseModel):
     model_config = {"extra": "allow"}
-    
+
     id: str
     uid: Optional[str] = None  # Global unique identifier for cross-project identity
     type: str
     status: str = "open"
     stage: Optional[str] = None
     title: str
-    
+
     # Time Anchors
     created_at: datetime = Field(default_factory=current_time)
     opened_at: Optional[datetime] = None
@@ -116,15 +126,16 @@ class IssueMetadata(BaseModel):
     isolation: Optional[IssueIsolation] = None
     dependencies: List[str] = []
     related: List[str] = []
+    domains: List[str] = []
     tags: List[str] = []
+    files: List[str] = []
     path: Optional[str] = None  # Absolute path to the issue file
-    
+
     # Proxy UI Actions (Excluded from file persistence)
     # Modified: Remove exclude=True to allow API/CLI inspection. Must be manually excluded during YAML Dump.
     actions: List[IssueAction] = Field(default=[])
 
-
-    @model_validator(mode='before')
+    @model_validator(mode="before")
     @classmethod
     def normalize_fields(cls, v: Any) -> Any:
         if isinstance(v, dict):
@@ -138,10 +149,13 @@ class IssueMetadata(BaseModel):
                 "Parent": "parent",
                 "Solution": "solution",
                 "Sprint": "sprint",
+                "Domains": "domains",
             }
             for old_k, new_k in field_map.items():
                 if old_k in v and new_k not in v:
-                    v[new_k] = v[old_k] # Don't pop yet to avoid mutation issues if used elsewhere, or pop if safe.
+                    v[new_k] = v[
+                        old_k
+                    ]  # Don't pop yet to avoid mutation issues if used elsewhere, or pop if safe.
                     # Pydantic v2 mode='before' is usually a copy if we want to be safe, but let's just add it.
 
             # Normalize type and status to lowercase for compatibility
@@ -158,18 +172,21 @@ class IssueMetadata(BaseModel):
                     v["stage"] = "draft"
         return v
 
-    @model_validator(mode='after')
-    def validate_lifecycle(self) -> 'IssueMetadata':
+    @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.
-        
+
         return self
 
+
 class IssueDetail(IssueMetadata):
     body: str = ""
-    raw_content: Optional[str] = None # Full file content including frontmatter for editing
+    raw_content: Optional[
+        str
+    ] = None  # Full file content including frontmatter for editing

monoco/features/issue/monitor.py

@@ -2,15 +2,21 @@ import re
 import asyncio
 import logging
 from pathlib import Path
-from typing import Callable, Awaitable, Any, Optional
+from typing import Callable, Awaitable
 
 from watchdog.observers import Observer
 from watchdog.events import FileSystemEventHandler
 
 logger = logging.getLogger("monoco.features.issue.monitor")
 
+
 class IssueEventHandler(FileSystemEventHandler):
-    def __init__(self, loop, on_upsert: Callable[[dict], Awaitable[None]], on_delete: Callable[[dict], Awaitable[None]]):
+    def __init__(
+        self,
+        loop,
+        on_upsert: Callable[[dict], Awaitable[None]],
+        on_delete: Callable[[dict], Awaitable[None]],
+    ):
         self.loop = loop
         self.on_upsert = on_upsert
         self.on_delete = on_delete
@@ -19,16 +25,17 @@ class IssueEventHandler(FileSystemEventHandler):
         if not path_str.endswith(".md"):
             return
         asyncio.run_coroutine_threadsafe(self._handle_upsert(path_str), self.loop)
-    
+
     async def _handle_upsert(self, path_str: str):
         try:
             from monoco.features.issue.core import parse_issue
+
             path = Path(path_str)
             if not path.exists():
                 return
             issue = parse_issue(path)
             if issue:
-                await self.on_upsert(issue.model_dump(mode='json'))
+                await self.on_upsert(issue.model_dump(mode="json"))
         except Exception as e:
             logger.error(f"Error handling upsert for {path_str}: {e}")
 
@@ -54,7 +61,7 @@ class IssueEventHandler(FileSystemEventHandler):
     def on_modified(self, event):
         if not event.is_directory:
             self._process_upsert(event.src_path)
-            
+
     def on_deleted(self, event):
         if not event.is_directory:
             self._process_delete(event.src_path)
@@ -64,11 +71,18 @@ class IssueEventHandler(FileSystemEventHandler):
             self._process_delete(event.src_path)
             self._process_upsert(event.dest_path)
 
+
 class IssueMonitor:
     """
     Monitor the Issues directory for changes using Watchdog and trigger callbacks.
     """
-    def __init__(self, issues_root: Path, on_upsert: Callable[[dict], Awaitable[None]], on_delete: Callable[[dict], Awaitable[None]]):
+
+    def __init__(
+        self,
+        issues_root: Path,
+        on_upsert: Callable[[dict], Awaitable[None]],
+        on_delete: Callable[[dict], Awaitable[None]],
+    ):
         self.issues_root = issues_root
         self.on_upsert = on_upsert
         self.on_delete = on_delete
@@ -78,9 +92,11 @@ class IssueMonitor:
     async def start(self):
         self.loop = asyncio.get_running_loop()
         event_handler = IssueEventHandler(self.loop, self.on_upsert, self.on_delete)
-        
+
         if not self.issues_root.exists():
-            logger.warning(f"Issues root {self.issues_root} does not exist. creating...")
+            logger.warning(
+                f"Issues root {self.issues_root} does not exist. creating..."
+            )
             self.issues_root.mkdir(parents=True, exist_ok=True)
 
         self.observer.schedule(event_handler, str(self.issues_root), recursive=True)

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

@@ -8,8 +8,13 @@ System for managing tasks using `monoco issue`.
 - **Status**: `monoco issue open|close|backlog <id>`
 - **Check**: `monoco issue lint` (Must run after manual edits)
 - **Lifecycle**: `monoco issue start|submit|delete <id>`
+- **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**:
+     - Must use `monoco issue start --branch`.
+     - 🛑 **NO** direct coding on `main`/`master` (Linter will fail).
+     - Must update `files` field after coding (via `sync-files` or manual).

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

@@ -23,6 +23,28 @@ Use this skill to create and manage **Issues** (Universal Atoms) in Monoco proje
 - **🧹 CHORE**: Engineering maintenance, no direct user value. Mindset: Builder.
 - **🐞 FIX**: Correcting deviations. Mindset: Debugger.
 
+## Workflow Policies
+
+### 1. Strict Git Workflow
+
+Monoco enforces a **Feature Branch** model.
+
+- **Start**: Agents **MUST** use `monoco issue start <ID> --branch` to start working.
+  - This creates and switches to a standard `feat/<ID>-<slug>` branch.
+  - **Do NOT** manually create branches using `git checkout -b`.
+- **Protected Main**: **NO** direct modification on `main`, `master`, or `production` branches. Linter will block this.
+- **Submit**: Run `monoco issue submit <ID>` when work is ready for review.
+  - This moves the issue to `Review` stage and generates a Delivery Report.
+  - **Note**: This does **not** merge the code. You (or the user) must handle the Merge/PR process.
+
+### 2. File Tracking
+
+Agents must track modified files to maintain Self-Contained Context.
+
+- **Mechanism**: Issue Ticket Front Matter contains a `files: []` field.
+- **Automated (Recommended)**: Run `monoco issue sync-files` inside the Feature Branch. It diffs against the base branch.
+- **Manual (Fallback)**: If working without branches, Agent MUST **actively** append modified paths to the `files` list.
+
 ## Guidelines
 
 ### Directory Structure & Naming
@@ -45,7 +67,6 @@ Issues are validated via `monoco issue lint`. key constraints:
 Use `monoco issue`:
 
 1. **Create**: `monoco issue create <type> --title "..."`
-
    - Params: `--parent <id>`, `--dependency <id>`, `--related <id>`, `--sprint <id>`, `--tags <tag>`
 
 2. **Transition**: `monoco issue open/close/backlog <id>`
@@ -56,7 +77,8 @@ Use `monoco issue`:
 
 5. **Modification**: `monoco issue start/submit/delete <id>`
 
-6. **Commit**: `monoco issue commit` (Atomic commit for issue files)
+6. **Sync**: `monoco issue sync-files [id]` (Sync code changes to Issue file)
+
 7. **Validation**: `monoco issue lint` (Enforces compliance)
 
 ## Validation Rules (FEAT-0082)
@@ -85,3 +107,9 @@ The `status` (folder) and `stage` (front matter) must be compatible:
 - **open**: Draft, Doing, Review, Done
 - **backlog**: Draft, Doing, Review
 - **closed**: Done
+
+### 5. Environment Policy
+
+Linter includes environment-aware guardrails:
+
+- 🛑 **Dirty Main Protection**: Fails if uncommitted changes are detected on protected branches (`main`/`master`).

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

@@ -8,8 +8,13 @@
 - **状态**: `monoco issue open|close|backlog <id>`
 - **检查**: `monoco issue lint` (手动编辑后必须运行)
 - **生命周期**: `monoco issue start|submit|delete <id>`
+- **上下文同步**: `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. **环境策略**:
+     - 必须使用 `monoco issue start --branch` 创建 Feature 分支。
+     - 🛑 **禁止**直接在 `main`/`master` 分支修改代码 (Linter 会报错)。
+     - 修改代码后**必须**更新 `files` 字段（通过 `sync-files` 或手动）。

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

@@ -57,6 +57,24 @@ Monoco 不仅仅复刻 Jira，而是基于 **"思维模式 (Mindset)"** 重新
 - **次要**: `CHORE` (工程维护/支撑) - 通常独立存在。
 - **原子性原则**: Feature = Design + Dev + Test + Doc + i18n。它们是一体的。
 
+## 工作流策略 (Workflow Policies)
+
+### 1. 严格 Git 工作流 (Strict Git Workflow)
+
+Monoco 强制采用 **Feature Branch** 模式。
+
+- **Start**: 必须使用 `monoco issue start <ID> --branch` 启动任务。这会自动创建 `feat/<ID>-<slug>` 分支。
+- **禁止主干开发**: **严禁** 直接在 `main`, `master`, `production` 分支上修改代码。Linter 会拦截此类行为。
+- **Submit**: 在提交 PR 前，运行 `monoco issue submit <ID>` 进行清理和预发布检查。
+
+### 2. 文件追踪 (File Tracking)
+
+为了保证上下文的自包含性 (Self-Contained Context)，Agent 必须记录修改过的文件。
+
+- **机制**: Issue Ticket 的 Front Matter 包含 `files: []` 字段。
+- **自动化 (推荐)**: 在 Feature Branch 中运行 `monoco issue sync-files`。它会自动对比当前分支与 Base 分支的差异并更新列表。
+- **手动 (备选)**: 如果进行非分支开发，Agent 必须**主动**将修改的文件路径写入 `files` 列表。
+
 ## 准则 (Guidelines)
 
 ### 目录结构
@@ -81,7 +99,8 @@ Monoco 不仅仅复刻 Jira，而是基于 **"思维模式 (Mindset)"** 重新
 
 5. **Modification**: `monoco issue start/submit/delete <id>`
 
-6. **Commit**: `monoco issue commit` (原子化提交 Issue 文件)
+6. **Sync**: `monoco issue sync-files [id]` (同步代码变更到 Issue 文件)
+
 7. **Validation**: `monoco issue lint` (强制执行合规性检查)
 
 ## 合规与结构校验 (Validation Rules)
@@ -111,3 +130,9 @@ Monoco 不仅仅复刻 Jira，而是基于 **"思维模式 (Mindset)"** 重新
 - **open**: Draft, Doing, Review, Done
 - **backlog**: Draft, Doing, Review
 - **closed**: Done
+
+### 5. 环境策略 (Environment Policy)
+
+Linter 包含环境感知防护：
+
+- 🛑 **Dirty Main Protection**: 当检测到处于受保护分支 (`main`/`master`) 且存在未提交变更时，Lint 将失败并阻止操作。