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

monoco/core/config.py

@@ -133,6 +133,40 @@ class IssueSchemaConfig(BaseModel):
         return self
 
 
+class DomainItem(BaseModel):
+    name: str = Field(..., description="Canonical domain name (e.g. backend.auth)")
+    description: Optional[str] = Field(None, description="Description of the domain")
+    aliases: List[str] = Field(default_factory=list, description="List of aliases")
+
+
+class DomainConfig(BaseModel):
+    items: List[DomainItem] = Field(
+        default_factory=list, description="List of defined domains"
+    )
+    strict: bool = Field(
+        default=False, description="If True, only allow defined domains"
+    )
+
+    def merge(self, other: "DomainConfig") -> "DomainConfig":
+        if not other:
+            return self
+
+        # Merge items by name
+        if other.items:
+            item_map = {item.name: item for item in self.items}
+            for item in other.items:
+                # Overwrite or merge aliases? Let's overwrite for simplicity/consistency
+                item_map[item.name] = item
+            self.items = list(item_map.values())
+
+        # Strict mode: logic? maybe strict overrides?
+        # Let's say if ANY config asks for strict, it is strict? Or last one wins (project)?
+        # Default merge is usually override.
+        self.strict = other.strict
+
+        return self
+
+
 class StateMachineConfig(BaseModel):
     transitions: List[TransitionConfig]
 
@@ -155,6 +189,7 @@ class MonocoConfig(BaseModel):
     )
 
     issue: IssueSchemaConfig = Field(default_factory=IssueSchemaConfig)
+    domains: DomainConfig = Field(default_factory=DomainConfig)
 
     @staticmethod
     def _deep_merge(base: Dict[str, Any], update: Dict[str, Any]) -> Dict[str, Any]:

monoco/core/integrations.py

@@ -134,12 +134,6 @@ DEFAULT_INTEGRATIONS: Dict[str, AgentIntegration] = {
         bin_name="kimi",
         version_cmd="--version",
     ),
-    "agent": AgentIntegration(
-        key="agent",
-        name="Antigravity",
-        system_prompt_file="GEMINI.md",
-        skill_root_dir=".agent/skills/",
-    ),
 }
 
 

monoco/core/resources/en/AGENTS.md

@@ -6,3 +6,28 @@ Core toolkit commands for project management.
 - **Config**: `monoco config get|set <key> [value]` (Manage configuration)
 - **Sync**: `monoco sync` (Synchronize with agent environments)
 - **Uninstall**: `monoco uninstall` (Clean up agent integrations)
+
+---
+
+## ⚠️ Agent Must-Read: Git Workflow
+
+Before modifying any code, **MUST** follow these steps:
+
+### Standard Process
+
+1. **Create Issue**: `monoco issue create feature -t "Feature Title"`
+2. **🔒 Start Isolation**: `monoco issue start FEAT-XXX --branch`
+   - ⚠️ **Required** `--branch` flag
+   - ❌ Never modify code directly on `main`/`master` branches
+3. **Implement**: Code and test normally
+4. **Sync Files**: `monoco issue sync-files` (must run before commit)
+5. **Submit Review**: `monoco issue submit FEAT-XXX`
+6. **Close Issue**: `monoco issue close FEAT-XXX --solution implemented`
+
+### Quality Gates
+
+- Git Hooks auto-run `monoco issue lint` and tests
+- Don't bypass with `git commit --no-verify`
+- Linter blocks direct modifications on protected branches
+
+> 📖 See `monoco-issue` skill for complete workflow documentation.

monoco/core/resources/en/SKILL.md

@@ -34,7 +34,6 @@ Monoco is a developer productivity toolkit that provides:
 ### Agent Integration
 
 - **`monoco sync`**: Synchronize with agent environments
-
   - Injects system prompts into agent configuration files (GEMINI.md, CLAUDE.md, etc.)
   - Distributes skills to agent framework directories
   - Respects language configuration from `i18n.source_lang`
@@ -43,6 +42,24 @@ Monoco is a developer productivity toolkit that provides:
   - Removes managed blocks from agent configuration files
   - Cleans up distributed skills
 
+### Git Workflow Integration
+
+Monoco enforces a **Feature Branch Workflow** to ensure code isolation and quality:
+
+- **`monoco init`**: Automatically installs Git Hooks
+  - **pre-commit**: Runs Issue Linter and code formatting checks
+  - **pre-push**: Executes test suite and integrity validation
+  - All hooks configurable via `.monoco/config.yaml`
+
+- **Branch Isolation Strategy**:
+  - ⚠️ **Required**: Use `monoco issue start <ID> --branch` to create isolated environment
+  - Auto-generates normalized branch names: `feat/<id>-<slug>`
+  - **Main Protection**: Linter blocks direct code modifications on `main`/`master` branches
+
+- **File Tracking**: `monoco issue sync-files` auto-syncs Git changes to Issue metadata
+
+> 📖 **Detailed Workflow**: See `monoco-issue` skill for complete Issue lifecycle management guide.
+
 ## Configuration Structure
 
 Configuration is stored in YAML format at:
@@ -60,7 +77,21 @@ Key configuration sections:
 
 ## Best Practices
 
+### Basic Operations
+
 1. **Use CLI commands** instead of manual file editing when possible
 2. **Run `monoco sync`** after configuration changes to update agent environments
 3. **Commit `.monoco/config.yaml`** to version control for team consistency
 4. **Keep global config minimal** - most settings should be project-specific
+
+### Git Workflow (⚠️ CRITICAL for Agents)
+
+5. **Strictly follow branch isolation**:
+   - ✅ Always use: `monoco issue start <ID> --branch`
+   - ❌ Never modify code directly on `main`/`master` branches
+   - 📝 Before commit: Run `monoco issue sync-files` to update file tracking
+
+6. **Quality Gates**:
+   - Git Hooks will auto-run checks, don't bypass (`--no-verify`)
+   - Ensure `monoco issue lint` passes before committing
+   - Use `monoco issue submit` to generate delivery reports

monoco/core/resources/zh/AGENTS.md

@@ -6,3 +6,28 @@
 - **配置**: `monoco config get|set <key> [value]` (管理配置)
 - **同步**: `monoco sync` (与 agent 环境同步)
 - **卸载**: `monoco uninstall` (清理 agent 集成)
+
+---
+
+## ⚠️ Agent 必读: Git 工作流
+
+在修改任何代码前,**必须**遵循以下步骤:
+
+### 标准流程
+
+1. **创建 Issue**: `monoco issue create feature -t "功能标题"`
+2. **🔒 启动隔离环境**: `monoco issue start FEAT-XXX --branch`
+   - ⚠️ **强制要求** `--branch` 参数
+   - ❌ 禁止在 `main`/`master` 分支直接修改代码
+3. **实现功能**: 正常编码和测试
+4. **同步文件**: `monoco issue sync-files` (提交前必须运行)
+5. **提交审查**: `monoco issue submit FEAT-XXX`
+6. **关闭 Issue**: `monoco issue close FEAT-XXX --solution implemented`
+
+### 质量门禁
+
+- Git Hooks 会自动运行 `monoco issue lint` 和测试
+- 不要使用 `git commit --no-verify` 绕过检查
+- Linter 会阻止在受保护分支上的直接修改
+
+> 📖 详见 `monoco-issue` skill 获取完整工作流文档。

monoco/core/resources/zh/SKILL.md

@@ -42,6 +42,24 @@ Monoco 是一个开发者生产力工具包，提供:
   - 从 agent 配置文件中移除托管块
   - 清理已分发的 skills
 
+### Git 工作流集成
+
+Monoco 强制执行 **Feature Branch 工作流**以确保代码隔离和质量:
+
+- **`monoco init`**: 自动安装 Git Hooks
+  - **pre-commit**: 运行 Issue Linter 和代码格式检查
+  - **pre-push**: 执行测试套件和完整性验证
+  - 所有 Hooks 可通过 `.monoco/config.yaml` 配置
+
+- **分支隔离策略**:
+  - ⚠️ **强制要求**: 使用 `monoco issue start <ID> --branch` 创建隔离环境
+  - 自动创建规范化分支名: `feat/<id>-<slug>`
+  - **主干保护**: Linter 会阻止在 `main`/`master` 分支上的直接代码修改
+
+- **文件追踪**: `monoco issue sync-files` 自动同步 Git 变更到 Issue 元数据
+
+> 📖 **详细工作流**: 参见 `monoco-issue` skill 获取完整的 Issue 生命周期管理指南。
+
 ## 配置结构
 
 配置以 YAML 格式存储在:
@@ -59,7 +77,21 @@ Monoco 是一个开发者生产力工具包，提供:
 
 ## 最佳实践
 
+### 基础操作
+
 1. **优先使用 CLI 命令**，而不是手动编辑文件
 2. **配置更改后运行 `monoco sync`** 以更新 agent 环境
 3. **将 `.monoco/config.yaml` 提交到版本控制**，保持团队一致性
 4. **保持全局配置最小化** - 大多数设置应该是项目特定的
+
+### Git 工作流 (⚠️ CRITICAL for Agents)
+
+5. **严格遵循分支隔离**:
+   - ✅ 始终使用: `monoco issue start <ID> --branch`
+   - ❌ 禁止在 `main`/`master` 分支直接修改代码
+   - 📝 提交前运行: `monoco issue sync-files` 更新文件追踪
+
+6. **质量门禁**:
+   - Git Hooks 会自动运行检查,不要尝试绕过 (`--no-verify`)
+   - 提交前确保 `monoco issue lint` 通过
+   - 使用 `monoco issue submit` 生成交付报告

monoco/core/sync.py

@@ -20,15 +20,9 @@ def _get_targets(root: Path, config, cli_target: Optional[Path]) -> List[Path]:
         targets.append(cli_target)
         return targets
 
-    # 2. Config Targets
-    if config.agent.targets:
-        for t in config.agent.targets:
-            targets.append(root / t)
-        return targets
-
-    # 3. Registry Defaults (Dynamic Detection)
+    # 2. Registry Defaults (Dynamic Detection)
     integrations = get_active_integrations(
-        root, config_overrides=config.agent.integrations, auto_detect=True
+        root, config_overrides=None, auto_detect=True
     )
 
     if integrations:
@@ -69,16 +63,9 @@ def sync_command(
     # 2. Collect Data
     collected_prompts = {}
 
-    # Filter features based on config if specified
+    # Filter features based on config if specified (Deprecated: agent config removed)
     all_features = registry.get_features()
-    active_features = []
-
-    if config.agent.includes:
-        for f in all_features:
-            if f.name in config.agent.includes:
-                active_features.append(f)
-    else:
-        active_features = all_features
+    active_features = all_features
 
     with console.status("[bold green]Collecting feature integration data...") as status:
         for feature in active_features:
@@ -109,7 +96,7 @@ def sync_command(
 
     # Get active integrations
     integrations = get_active_integrations(
-        root, config_overrides=config.agent.integrations, auto_detect=True
+        root, config_overrides=None, auto_detect=True
     )
 
     if integrations:
@@ -231,7 +218,7 @@ def uninstall_command(
 
     # Get active integrations
     integrations = get_active_integrations(
-        root, config_overrides=config.agent.integrations, auto_detect=True
+        root, config_overrides=None, auto_detect=True
     )
 
     if integrations:

monoco/features/i18n/core.py

@@ -24,6 +24,13 @@ DEFAULT_EXCLUDES = [
     ".vscode",
     ".idea",
     ".fleet",
+    ".vscode-test",
+    ".cache",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".tox",
+    ".nox",
     # System Prompts & Agent Configs
     "AGENTS.md",
     "CLAUDE.md",
@@ -55,17 +62,16 @@ def load_gitignore_patterns(root: Path) -> List[str]:
 
 
 def is_excluded(
-    path: Path, root: Path, patterns: List[str], excludes: Optional[List[str]] = None
+    path: Path, root: Path, patterns: List[str], excludes_set: Optional[set] = None
 ) -> bool:
     """Check if a path should be excluded based on patterns and defaults."""
     rel_path = str(path.relative_to(root))
 
-    final_excludes = excludes if excludes is not None else DEFAULT_EXCLUDES
-
     # 1. Check default excludes (exact match for any path component, case-insensitive)
-    for part in path.parts:
-        if part.lower() in [e.lower() for e in final_excludes]:
-            return True
+    if excludes_set:
+        for part in path.parts:
+            if part.lower() in excludes_set:
+                return True
 
     # 2. Check gitignore patterns
     for pattern in patterns:
@@ -98,11 +104,25 @@ def discover_markdown_files(root: Path, include_issues: bool = False) -> List[Pa
     if not include_issues:
         excludes.append("Issues")
 
-    # We walk to ensure we can skip directories early if needed,
-    # but for now rglob + filter is simpler.
-    for p in root.rglob("*.md"):
-        if p.is_file() and not is_excluded(p, root, patterns, excludes=excludes):
-            all_md_files.append(p)
+    # Pre-calculate lowercase set for performance
+    excludes_set = {e.lower() for e in excludes}
+
+    # Use walk to skip excluded directories early
+    for current_root, dirs, files in root.walk():
+        # Filter directories in-place to skip excluded ones
+        dirs[:] = [
+            d
+            for d in dirs
+            if not is_excluded(
+                current_root / d, root, patterns, excludes_set=excludes_set
+            )
+        ]
+
+        for file in files:
+            if file.endswith(".md"):
+                p = current_root / file
+                if not is_excluded(p, root, patterns, excludes_set=excludes_set):
+                    all_md_files.append(p)
 
     return sorted(all_md_files)
 

monoco/features/issue/commands.py

@@ -17,6 +17,9 @@ backlog_app = typer.Typer(help="Manage backlog operations.")
 lsp_app = typer.Typer(help="LSP Server commands.")
 app.add_typer(backlog_app, name="backlog")
 app.add_typer(lsp_app, name="lsp")
+from . import domain_commands
+
+app.add_typer(domain_commands.app, name="domain")
 console = Console()
 
 
@@ -45,12 +48,12 @@ def create(
     ),
     sprint: Optional[str] = typer.Option(None, "--sprint", help="Sprint ID"),
     tags: List[str] = typer.Option([], "--tag", help="Tags"),
+    domains: List[str] = typer.Option([], "--domain", help="Domains"),
     root: Optional[str] = typer.Option(
         None, "--root", help="Override issues root directory"
     ),
     json: AgentOutput = False,
 ):
-    """Create a new issue."""
     """Create a new issue."""
     config = get_config()
     issues_root = _resolve_issues_root(config, root)
@@ -79,6 +82,7 @@ def create(
             stage=stage,
             dependencies=dependencies,
             related=related,
+            domains=domains,
             subdir=subdir,
             sprint=sprint,
             tags=tags,
@@ -99,6 +103,25 @@ def create(
             )
             console.print(f"Path: {rel_path}")
 
+            # Prompt for Language
+            target_langs = config.i18n.target_langs
+            primary_lang = target_langs[0] if target_langs else "en"
+
+            # Simple mapping for display
+            lang_display = {
+                "zh": "Chinese (Simplified)",
+                "en": "English",
+                "ja": "Japanese",
+            }.get(primary_lang, primary_lang)
+
+            console.print(
+                f"\n[bold yellow]Agent Hint:[/bold yellow] Please fill the ticket content in [bold cyan]{lang_display}[/bold cyan]."
+            )
+
+    except ValueError as e:
+        OutputManager.error(str(e))
+        raise typer.Exit(code=1)
+
     except ValueError as e:
         OutputManager.error(str(e))
         raise typer.Exit(code=1)

monoco/features/issue/core.py

@@ -53,28 +53,108 @@ def _get_slug(title: str) -> str:
     return slug
 
 
-def parse_issue(file_path: Path) -> Optional[IssueMetadata]:
+def parse_issue(file_path: Path, raise_error: bool = False) -> Optional[IssueMetadata]:
     if not file_path.suffix == ".md":
         return None
 
     content = file_path.read_text()
     match = re.search(r"^---(.*?)---", content, re.DOTALL | re.MULTILINE)
     if not match:
+        if raise_error:
+            raise ValueError(f"No frontmatter found in {file_path.name}")
         return None
 
     try:
         data = yaml.safe_load(match.group(1))
         if not isinstance(data, dict):
+            if raise_error:
+                raise ValueError(f"Frontmatter is not a dictionary in {file_path.name}")
             return None
 
         data["path"] = str(file_path.absolute())
         meta = IssueMetadata(**data)
         meta.actions = get_available_actions(meta)
         return meta
-    except Exception:
+    except Exception as e:
+        if raise_error:
+            raise e
         return None
 
 
+def _serialize_metadata(metadata: IssueMetadata) -> str:
+    """
+    Centralized serialization logic to ensure explicit fields and correct ordering.
+    """
+    # Serialize metadata
+    # We want explicit fields even if None/Empty to enforce schema awareness
+    data = metadata.model_dump(
+        exclude_none=True, mode="json", exclude={"actions", "path"}
+    )
+
+    # Force explicit keys if missing (due to exclude_none or defaults)
+    if "parent" not in data:
+        data["parent"] = None
+    if "dependencies" not in data:
+        data["dependencies"] = []
+    if "related" not in data:
+        data["related"] = []
+    if "domains" not in data:
+        data["domains"] = []
+    if "files" not in data:
+        data["files"] = []
+
+    # Custom YAML Dumper to preserve None as 'null' and order
+    # Helper to order keys: id, uid, type, status, stage, title, ... graph ...
+    # Simple sort isn't enough, we rely on insertion order (Python 3.7+)
+    ordered_data = {
+        k: data[k]
+        for k in [
+            "id",
+            "uid",
+            "type",
+            "status",
+            "stage",
+            "title",
+            "created_at",
+            "updated_at",
+        ]
+        if k in data
+    }
+    # Add graph fields
+    for k in [
+        "priority",
+        "parent",
+        "dependencies",
+        "related",
+        "domains",
+        "tags",
+        "files",
+    ]:
+        if k in data:
+            ordered_data[k] = data[k]
+        elif k in ["dependencies", "related", "domains", "tags", "files"]:
+            ordered_data[k] = []
+        elif k == "parent":
+            ordered_data[k] = None
+
+    # Add remaining
+    for k, v in data.items():
+        if k not in ordered_data:
+            ordered_data[k] = v
+
+    yaml_header = yaml.dump(
+        ordered_data, sort_keys=False, allow_unicode=True, default_flow_style=False
+    )
+
+    # Inject Comments for guidance (replace keys with key+comment)
+    if "parent" in ordered_data and ordered_data["parent"] is None:
+        yaml_header = yaml_header.replace(
+            "parent: null", "parent: null # <EPIC-ID> Optional"
+        )
+
+    return yaml_header
+
+
 def parse_issue_detail(file_path: Path) -> Optional[IssueDetail]:
     if not file_path.suffix == ".md":
         return None
@@ -127,6 +207,7 @@ def create_issue_file(
     stage: Optional[IssueStage] = None,
     dependencies: List[str] = [],
     related: List[str] = [],
+    domains: List[str] = [],
     subdir: Optional[str] = None,
     sprint: Optional[str] = None,
     tags: List[str] = [],
@@ -149,8 +230,7 @@ def create_issue_file(
 
     target_dir.mkdir(parents=True, exist_ok=True)
 
-    # Auto-Populate Tags with required IDs (Requirement: Maintain tags field with parent/deps/related/self IDs)
-    # Ensure they are prefixed with '#' for tagging convention if not present (usually tags are just strings, but user asked for #ID)
+    # Auto-Populate Tags with required IDs
     auto_tags = set(tags) if tags else set()
 
     # 1. Add Parent
@@ -165,15 +245,14 @@ def create_issue_file(
     for rel in related:
         auto_tags.add(f"#{rel}")
 
-    # 4. Add Self (as per instruction "auto add this issue... number")
-    # Note: issue_id is generated just above
+    # 4. Add Self
     auto_tags.add(f"#{issue_id}")
 
     final_tags = sorted(list(auto_tags))
 
     metadata = IssueMetadata(
         id=issue_id,
-        uid=generate_uid(),  # Generate global unique identifier
+        uid=generate_uid(),
         type=issue_type,
         status=status,
         stage=stage,
@@ -181,43 +260,23 @@ def create_issue_file(
         parent=parent,
         dependencies=dependencies,
         related=related,
+        domains=domains,
         sprint=sprint,
         tags=final_tags,
         opened_at=current_time() if status == IssueStatus.OPEN else None,
     )
 
-    # Enforce lifecycle policies (defaults, auto-corrections)
+    # Enforce lifecycle policies
     from .engine import get_engine
 
     get_engine().enforce_policy(metadata)
 
     # Serialize metadata
-    # Explicitly exclude actions and path from file persistence
-    yaml_header = yaml.dump(
-        metadata.model_dump(
-            exclude_none=True, mode="json", exclude={"actions", "path"}
-        ),
-        sort_keys=False,
-        allow_unicode=True,
-    )
-
-    # Inject Self-Documenting Hints (Interactive Frontmatter)
-    if "parent:" not in yaml_header:
-        yaml_header += "# parent: <EPIC-ID>   # Optional: Parent Issue ID\n"
-    if "solution:" not in yaml_header:
-        yaml_header += "# solution: null      # Required for Closed state (implemented, cancelled, etc.)\n"
-
-    if "dependencies:" not in yaml_header:
-        yaml_header += "# dependencies: []    # List of dependency IDs\n"
-    if "related:" not in yaml_header:
-        yaml_header += "# related: []         # List of related issue IDs\n"
-    if "files:" not in yaml_header:
-        yaml_header += "# files: []           # List of modified files\n"
+    yaml_header = _serialize_metadata(metadata)
 
     slug = _get_slug(title)
     filename = f"{issue_id}-{slug}.md"
 
-    # Enhanced Template with Instructional Comments
     file_content = f"""---
 {yaml_header}---
 
@@ -249,7 +308,6 @@ def create_issue_file(
     file_path = target_dir / filename
     file_path.write_text(file_content)
 
-    # Inject path into returned metadata
     metadata.path = str(file_path.absolute())
 
     return metadata, file_path
@@ -512,14 +570,7 @@ def update_issue(
         raise ValueError(f"Failed to validate updated metadata: {e}")
 
     # Serialize back
-    # Explicitly exclude actions and path from file persistence
-    new_yaml = yaml.dump(
-        updated_meta.model_dump(
-            exclude_none=True, mode="json", exclude={"actions", "path"}
-        ),
-        sort_keys=False,
-        allow_unicode=True,
-    )
+    new_yaml = _serialize_metadata(updated_meta)
 
     # Reconstruct File
     match_header = re.search(r"^---(.*?)---", content, re.DOTALL | re.MULTILINE)

monoco/features/issue/domain/models.py

@@ -113,6 +113,7 @@ class IssueFrontmatter(BaseModel):
     parent: Optional[str] = None
     dependencies: List[str] = Field(default_factory=list)
     related: List[str] = Field(default_factory=list)
+    domains: List[str] = Field(default_factory=list)
     tags: List[str] = Field(default_factory=list)
     solution: Optional[IssueSolution] = None
     isolation: Optional[IssueIsolation] = None

monoco/features/issue/domain_commands.py

@@ -0,0 +1,47 @@
+import typer
+from rich.table import Table
+from rich.console import Console
+from monoco.features.issue.domain_service import DomainService
+
+app = typer.Typer(help="Manage domain ontology.")
+console = Console()
+
+
+@app.command("list")
+def list_domains():
+    """List defined domains and aliases."""
+    service = DomainService()
+    config = service.config
+
+    table = Table(title=f"Domain Ontology (Strict: {config.strict})")
+    table.add_column("Canonical Name", style="bold cyan")
+    table.add_column("Description", style="white")
+    table.add_column("Aliases", style="yellow")
+
+    for item in config.items:
+        table.add_row(
+            item.name,
+            item.description or "",
+            ", ".join(item.aliases) if item.aliases else "-",
+        )
+
+    console.print(table)
+
+
+@app.command("check")
+def check_domain(domain: str = typer.Argument(..., help="Domain name to check")):
+    """Check if a domain is valid and resolve it."""
+    service = DomainService()
+
+    if service.is_canonical(domain):
+        console.print(f"[green]✔ '{domain}' is a canonical domain.[/green]")
+    elif service.is_alias(domain):
+        canonical = service.get_canonical(domain)
+        console.print(f"[yellow]➜ '{domain}' is an alias for '{canonical}'.[/yellow]")
+    else:
+        if service.config.strict:
+            console.print(f"[red]✘ '{domain}' is NOT a valid domain.[/red]")
+        else:
+            console.print(
+                f"[yellow]⚠ '{domain}' is undefined (Strict Mode: OFF).[/yellow]"
+            )