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

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

@@ -37,6 +37,48 @@ Monoco enforces a **Feature Branch** model.
   - 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.
 
+## Standardized Workflow
+
+### Workflow Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> Plan
+    Plan --> Build: monoco issue start
+    Build --> Submit: monoco issue submit
+    state "Oracle Loop" as Oracle {
+        Submit --> Review: Auto/Manual Review
+        Review --> Fix: Reject
+        Fix --> Submit: Retry
+    }
+    Review --> Merge: Approve
+    Merge --> [*]: monoco issue close
+```
+
+### Action Steps
+
+1.  **Plan Phase**:
+    - Ensure Issue exists and is in `Open` status.
+    - Verify requirements and tasks.
+
+2.  **Build Phase**:
+    - Run `monoco issue start <ID> --branch` (Verification: ensures branch is created).
+    - Implement features/fixes.
+    - Run `monoco issue sync-files` to track changes.
+
+3.  **Submit Phase (Oracle Loop)**:
+    - Run tests to ensure quality.
+    - Run `monoco issue lint`.
+    - Run `monoco issue submit <ID>`.
+    - **IF** errors/feedback received:
+      - Fix issues.
+      - Re-run tests.
+      - Re-submit.
+
+4.  **Merge Phase**:
+    - Once approved:
+    - Run `monoco issue close <ID> --solution completed --prune`.
+
 ### 2. File Tracking
 
 Agents must track modified files to maintain Self-Contained Context.
@@ -113,3 +155,9 @@ The `status` (folder) and `stage` (front matter) must be compatible:
 Linter includes environment-aware guardrails:
 
 - 🛑 **Dirty Main Protection**: Fails if uncommitted changes are detected on protected branches (`main`/`master`).
+
+### 6. ID Format & Hierarchy
+
+- **ID Specification**: Issue IDs must strictly follow the `TYPE-XXXX` format, where `XXXX` are 4 digits (e.g., `FEAT-0001`, `FIX-9999`).
+- **No Suffixes**: IDs with suffixes like `FEAT-0001-1` are strictly prohibited.
+- **Hierarchy Expression**: Sub-features or sub-tasks must be expressed using the `parent` field in the Front Matter. Do NOT use ID naming conventions (like hierarchical suffixes) to express relationships.

monoco/features/issue/resources/skills/issue_lifecycle_workflow/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: issue-lifecycle-workflow
+description: Issue 生命周期工作流 (Flow Skill)。定义从创建到关闭的完整 Issue 管理流程，确保任务追踪和流程合规。
+type: flow
+domain: issue
+version: 1.0.0
+---
+
+# Issue Lifecycle Workflow
+
+Issue 生命周期的标准化工作流，确保 "Open → Start → Develop → Submit → Review → Close" 流程。
+
+## 工作流状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> Open: 创建 Issue
+    
+    Open --> Start: 准备开发
+    Open --> Open: 需求不清<br/>(等待澄清)
+    
+    Start --> Develop: 分支创建
+    Start --> Start: 分支冲突<br/>(解决冲突)
+    
+    Develop --> Submit: 开发完成
+    Develop --> Develop: 测试失败<br/>(修复代码)
+    
+    state "Oracle Loop" as ReviewLoop {
+        Submit --> Review: 提交评审
+        Review --> Fix: 拒绝
+        Fix --> Submit: 重新提交
+    }
+    
+    Review --> Close: 批准合并
+    
+    Close --> [*]: 清理完成
+```
+
+## 执行步骤
+
+### 1. Open (创建)
+
+- **目标**: 创建清晰、可执行的 Issue
+- **输入**: 需求描述、类型、优先级
+- **输出**: Issue Ticket 文件
+- **检查点**:
+  - [ ] 使用 `monoco issue create <type> -t "标题"`
+  - [ ] 选择合适的类型（epic/feature/chore/fix）
+  - [ ] 编写清晰的描述和验收标准
+  - [ ] 设置依赖关系（如需要）
+  - [ ] 确保至少 2 个 Checkbox
+
+### 2. Start (启动)
+
+- **目标**: 准备开发环境，创建功能分支
+- **检查点**:
+  - [ ] 运行 `monoco issue start <ID> --branch`
+  - [ ] 确认分支已创建并切换
+  - [ ] 验证当前不在 main/master 分支
+  - [ ] 检查依赖 Issue 是否已完成
+
+### 3. Develop (开发)
+
+- **目标**: 实现功能或修复缺陷
+- **策略**: 迭代开发，持续测试
+- **检查点**:
+  - [ ] 遵循项目代码规范
+  - [ ] 编写/更新单元测试
+  - [ ] 运行测试套件，确保通过
+  - [ ] 定期提交代码（小步提交）
+  - [ ] 更新文件追踪（`monoco issue sync-files`）
+
+### 4. Submit (提交)
+
+- **目标**: 准备代码评审
+- **检查点**:
+  - [ ] 运行 `monoco issue lint` 检查合规性
+  - [ ] 修复所有 Lint 错误
+  - [ ] 更新任务清单状态
+  - [ ] 运行 `monoco issue submit <ID>`
+  - [ ] 编写变更摘要
+
+### 5. Review (评审)
+
+- **目标**: 代码质量和流程合规检查
+- **检查点**:
+  - [ ] 功能是否正确实现
+  - [ ] 代码是否符合设计规范
+  - [ ] 测试是否充分
+  - [ ] 文档是否同步更新
+  - [ ] 是否遵循项目规范
+
+### 6. Close (关闭)
+
+- **目标**: 完成 Issue，清理环境
+- **检查点**:
+  - [ ] 代码已合并到主分支
+  - [ ] 运行 `monoco issue close <ID> --solution completed --prune`
+  - [ ] 验证分支已清理
+  - [ ] 更新 Review Comments（如需要）
+
+## 决策分支
+
+| 条件 | 动作 |
+|------|------|
+| 需求不清晰 | 返回 Open，请求澄清 |
+| 分支创建失败 | 检查 Git 状态，解决冲突 |
+| 测试失败 | 返回 Develop，修复代码 |
+| Lint 失败 | 修复合规性问题，重新 Submit |
+| 评审拒绝 | 返回 Develop，按反馈修改 |
+| 评审通过 | 进入 Close，合并并清理 |
+
+## 合规要求
+
+- **禁止**: 在 main/master 分支直接修改代码
+- **必须**: 使用 `monoco issue start --branch` 创建功能分支
+- **必须**: 所有单元测试通过后才能 Submit
+- **必须**: 每个 Issue 至少 2 个 Checkbox
+- **必须**: Review/Done 阶段必须包含 Review Comments
+- **建议**: 小步提交，频繁同步文件追踪
+
+## 相关命令
+
+```bash
+# 创建 Issue
+monoco issue create feature -t "标题"
+
+# 启动开发
+monoco issue start FEAT-0001 --branch
+
+# 同步文件追踪
+monoco issue sync-files
+
+# 检查合规性
+monoco issue lint
+
+# 提交评审
+monoco issue submit FEAT-0001
+
+# 关闭 Issue
+monoco issue close FEAT-0001 --solution completed --prune
+```
+
+## Issue 类型指南
+
+| 类型 | 用途 | 前缀 | Mindset |
+|------|------|------|---------|
+| Epic | 宏大目标、愿景容器 | EPIC- | Architect |
+| Feature | 用户价值增量 | FEAT- | Product Owner |
+| Chore | 工程性事务 | CHORE- | Builder |
+| Fix | 缺陷修复 | FIX- | Debugger |
+
+## 与 flow_engineer 的关系
+
+此工作流与 `flow_engineer` 互补：
+- `issue-lifecycle-workflow`: 关注 Issue 管理流程
+- `flow_engineer`: 关注代码实现流程
+
+Engineer 在执行 Develop 阶段时，应遵循 `flow_engineer` 的 Investigate → Code → Test → Report → Submit 流程。

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

@@ -67,6 +67,50 @@ Monoco 强制采用 **Feature Branch** 模式。
 - **禁止主干开发**: **严禁** 直接在 `main`, `master`, `production` 分支上修改代码。Linter 会拦截此类行为。
 - **Submit**: 在提交 PR 前，运行 `monoco issue submit <ID>` 进行清理和预发布检查。
 
+## 标准化工作流 (Standardized Workflow)
+
+本指南引导 Agent 遵循 Monoco 标准 Issue 工作流。
+
+### 工作流图示
+
+```mermaid
+stateDiagram-v2
+    [*] --> Plan
+    Plan --> Build: monoco issue start
+    Build --> Submit: monoco issue submit
+    state "Oracle Loop" as Oracle {
+        Submit --> Review: Auto/Manual Review
+        Review --> Fix: Reject
+        Fix --> Submit: Retry
+    }
+    Review --> Merge: Approve
+    Merge --> [*]: monoco issue close
+```
+
+### 执行步骤
+
+1.  **Plan (计划阶段)**:
+    - 确保 Issue 已创作且处于 `Open` 状态。
+    - 验证需求描述与任务清单 (Acceptance Criteria)。
+
+2.  **Build (构建阶段)**:
+    - 运行 `monoco issue start <ID> --branch` (强制分支隔离)。
+    - 实现功能或修复缺陷。
+    - 运行 `monoco issue sync-files` 更新修改文件追踪。
+
+3.  **Submit (提交阶段 - Oracle 循环)**:
+    - 运行测试确保质量。
+    - 运行 `monoco issue lint` 检查合规性。
+    - 运行 `monoco issue submit <ID>` 触发评审。
+    - **如果** 收到报错或反馈：
+      - 修复问题。
+      - 重新运行测试。
+      - 重新运行提交。
+
+4.  **Merge (合并/关闭阶段)**:
+    - 一旦获得批准 (人工或自动)：
+    - 运行 `monoco issue close <ID> --solution completed --prune` 清理环境并下线。
+
 ### 2. 文件追踪 (File Tracking)
 
 为了保证上下文的自包含性 (Self-Contained Context)，Agent 必须记录修改过的文件。
@@ -136,3 +180,9 @@ Monoco 强制采用 **Feature Branch** 模式。
 Linter 包含环境感知防护：
 
 - 🛑 **Dirty Main Protection**: 当检测到处于受保护分支 (`main`/`master`) 且存在未提交变更时，Lint 将失败并阻止操作。
+
+### 6. ID 格式与层级 (ID Format & Hierarchy)
+
+- **ID 规范**: Issue ID 必须严格遵循 `TYPE-XXXX` 格式，其中 `XXXX` 必须是 4 位数字（示例: `FEAT-0001`, `FIX-9999`）。
+- **禁止后缀**: 禁止使用类似 `FEAT-0001-1` 这样带后缀的 ID。
+- **层级表达**: 子功能或子任务应通过 `parent` 字段（在 Front Matter 中）来关联父级 Issue，严禁通过 ID 命名约定（如加分级后缀）来表达层级关系。

monoco/features/issue/test_priority_integration.py

@@ -16,6 +16,7 @@ def test_validator_namespaced_reference_in_body():
         opened_at=datetime.now(),
         updated_at=datetime.now(),
         domains=["intelligence"],
+        parent="EPIC-0000",
     )
 
     # Context: toolkit project, monoco workspace

monoco/features/issue/validator.py

@@ -27,6 +27,7 @@ class IssueValidator:
         all_issue_ids: Set[str] = set(),
         current_project: Optional[str] = None,
         workspace_root: Optional[str] = None,
+        valid_domains: Set[str] = set(),
     ) -> List[Diagnostic]:
         """
         Validate an issue and return diagnostics.
@@ -77,7 +78,11 @@ class IssueValidator:
         diagnostics.extend(self._validate_references(meta, content, all_issue_ids))
 
         # 5.5 Domain Integrity
-        diagnostics.extend(self._validate_domains(meta, content, all_issue_ids))
+        diagnostics.extend(
+            self._validate_domains(
+                meta, content, all_issue_ids, valid_domains=valid_domains
+            )
+        )
 
         # 6. Time Consistency
         diagnostics.extend(self._validate_time_consistency(meta, content))
@@ -88,6 +93,9 @@ class IssueValidator:
         # 8. Language Consistency
         diagnostics.extend(self._validate_language_consistency(meta, content))
 
+        # 9. Placeholder Detection
+        diagnostics.extend(self._validate_placeholders(meta, content))
+
         return diagnostics
 
     def _validate_language_consistency(
@@ -431,7 +439,7 @@ class IssueValidator:
             )
             resolver = ReferenceResolver(context)
 
-        # Malformed ID Check
+        # 1. Malformed ID Check (Syntax)
         if meta.parent and meta.parent.startswith("#"):
             line = self._get_field_line(content, "parent")
             diagnostics.append(
@@ -466,7 +474,63 @@ class IssueValidator:
                         )
                     )
 
-        if not all_ids or not resolver:
+        # 2. Body Reference Check (Format and Existence)
+        lines = content.split("\n")
+        in_fm = False
+        fm_end = 0
+        for i, line in enumerate(lines):
+            if line.strip() == "---":
+                if not in_fm:
+                    in_fm = True
+                else:
+                    fm_end = i
+                    break
+
+        for i, line in enumerate(lines):
+            if i <= fm_end:
+                continue  # Skip frontmatter
+
+            # Find all matches, including those with invalid suffixes to report them properly
+            matches = re.finditer(r"\b((?:EPIC|FEAT|CHORE|FIX)-\d{4}(?:-\d+)?)\b", line)
+            for match in matches:
+                full_raw_id = match.group(1)
+
+                # Check if it has an invalid suffix (e.g. FEAT-0099-1)
+                if len(full_raw_id.split("-")) > 2:
+                    diagnostics.append(
+                        self._create_diagnostic(
+                            f"Invalid ID Format: '{full_raw_id}' has an invalid suffix. Use 'parent' field for hierarchy.",
+                            DiagnosticSeverity.Warning,
+                            line=i,
+                        )
+                    )
+                    continue
+
+                ref_id = full_raw_id
+
+                # Knowledge Check (Only if resolver is available)
+                if resolver:
+                    # Check for namespaced ID before this match?
+                    full_match = re.search(
+                        r"\b(?:([a-z0-9_-]+)::)?(" + re.escape(ref_id) + r")\b",
+                        line[max(0, match.start() - 50) : match.end()],
+                    )
+
+                    check_id = ref_id
+                    if full_match and full_match.group(1):
+                        check_id = f"{full_match.group(1)}::{ref_id}"
+
+                    if ref_id != meta.id and not resolver.is_valid_reference(check_id):
+                        diagnostics.append(
+                            self._create_diagnostic(
+                                f"Broken Reference: Issue '{check_id}' not found.",
+                                DiagnosticSeverity.Warning,
+                                line=i,
+                            )
+                        )
+
+        # 3. Hierarchy and Graph Integrity (Requires Resolver)
+        if not resolver:
             return diagnostics
 
         # Logic: Epics must have a parent (unless it is the Sink Root EPIC-0000)
@@ -506,49 +570,6 @@ class IssueValidator:
                     )
                 )
 
-        # Body Reference Check
-        # Regex for generic issue ID: (EPIC|FEAT|CHORE|FIX)-\d{4}
-        # We scan line by line to get line numbers
-        lines = content.split("\n")
-        # Skip frontmatter for body check to avoid double counting (handled above)
-        in_fm = False
-        fm_end = 0
-        for i, line in enumerate(lines):
-            if line.strip() == "---":
-                if not in_fm:
-                    in_fm = True
-                else:
-                    fm_end = i
-                    break
-
-        for i, line in enumerate(lines):
-            if i <= fm_end:
-                continue  # Skip frontmatter
-
-            # Find all matches
-            matches = re.finditer(r"\b((?:EPIC|FEAT|CHORE|FIX)-\d{4})\b", line)
-            for match in matches:
-                ref_id = match.group(1)
-                # Check for namespaced ID before this match?
-                # The regex above only catches the ID part.
-                # Let's adjust regex to optionally catch namespace::
-                full_match = re.search(
-                    r"\b(?:([a-z0-9_-]+)::)?(" + re.escape(ref_id) + r")\b",
-                    line[max(0, match.start() - 50) : match.end()],
-                )
-
-                check_id = ref_id
-                if full_match and full_match.group(1):
-                    check_id = f"{full_match.group(1)}::{ref_id}"
-
-                if ref_id != meta.id and not resolver.is_valid_reference(check_id):
-                    diagnostics.append(
-                        self._create_diagnostic(
-                            f"Broken Reference: Issue '{check_id}' not found.",
-                            DiagnosticSeverity.Warning,
-                            line=i,
-                        )
-                    )
         return diagnostics
         return diagnostics
 
@@ -603,7 +624,11 @@ class IssueValidator:
         return diagnostics
 
     def _validate_domains(
-        self, meta: IssueMetadata, content: str, all_ids: Set[str] = set()
+        self,
+        meta: IssueMetadata,
+        content: str,
+        all_ids: Set[str] = set(),
+        valid_domains: Set[str] = set(),
     ) -> List[Diagnostic]:
         diagnostics = []
         # Check if 'domains' field exists in frontmatter text
@@ -650,38 +675,79 @@ class IssueValidator:
                 )
 
         # Domain Content Validation
-        from .domain_service import DomainService
-
-        service = DomainService()
-
+        # If valid_domains is provided (from file scan), use it as strict source of truth
         if hasattr(meta, "domains") and meta.domains:
-            for domain in meta.domains:
-                if service.is_alias(domain):
-                    canonical = service.get_canonical(domain)
-                    diagnostics.append(
-                        self._create_diagnostic(
-                            f"Domain Alias: '{domain}' is an alias for '{canonical}'. Preference: Canonical.",
-                            DiagnosticSeverity.Warning,
-                            line=field_line,
+            if valid_domains:
+                # Use File-based validation
+                for domain in meta.domains:
+                    # 1. Format Check: PascalCase
+                    is_pascal = re.match(r"^[A-Z][a-zA-Z0-9]+$", domain) is not None
+
+                    if not is_pascal:
+                        # Suggest conversion
+                        normalized = "".join(
+                            word.capitalize()
+                            for word in re.findall(r"[a-zA-Z0-9]+", domain)
                         )
-                    )
-                elif not service.is_defined(domain):
-                    if service.config.strict:
+                        if normalized in valid_domains:
+                            diagnostics.append(
+                                self._create_diagnostic(
+                                    f"Domain Format Error: '{domain}' must be PascalCase (e.g., '{normalized}').",
+                                    DiagnosticSeverity.Error,
+                                    line=field_line,
+                                )
+                            )
+                        else:
+                            diagnostics.append(
+                                self._create_diagnostic(
+                                    f"Domain Format Error: '{domain}' must be PascalCase (no spaces/symbols).",
+                                    DiagnosticSeverity.Error,
+                                    line=field_line,
+                                )
+                            )
+                        continue
+
+                    # 2. Existence Check
+                    if domain not in valid_domains:
                         diagnostics.append(
                             self._create_diagnostic(
-                                f"Unknown Domain: '{domain}' is not defined in domain ontology.",
+                                f"Unknown Domain: '{domain}' not found. Available: {', '.join(sorted(valid_domains))}",
                                 DiagnosticSeverity.Error,
                                 line=field_line,
                             )
                         )
-                    else:
+            else:
+                # Fallback to legacy DomainService (hardcoded list)
+                from .domain_service import DomainService
+
+                service = DomainService()
+                for domain in meta.domains:
+                    if service.is_alias(domain):
+                        canonical = service.get_canonical(domain)
                         diagnostics.append(
                             self._create_diagnostic(
-                                f"Unknown Domain: '{domain}' is not defined in domain ontology.",
+                                f"Domain Alias: '{domain}' is an alias for '{canonical}'. Preference: Canonical.",
                                 DiagnosticSeverity.Warning,
                                 line=field_line,
                             )
                         )
+                    elif not service.is_defined(domain):
+                        if service.config.strict:
+                            diagnostics.append(
+                                self._create_diagnostic(
+                                    f"Unknown Domain: '{domain}' is not defined in domain ontology.",
+                                    DiagnosticSeverity.Error,
+                                    line=field_line,
+                                )
+                            )
+                        else:
+                            diagnostics.append(
+                                self._create_diagnostic(
+                                    f"Unknown Domain: '{domain}' is not defined in domain ontology.",
+                                    DiagnosticSeverity.Warning,
+                                    line=field_line,
+                                )
+                            )
 
         return diagnostics
 
@@ -716,3 +782,57 @@ class IssueValidator:
                         )
 
         return diagnostics
+
+    def _validate_placeholders(
+        self, meta: IssueMetadata, content: str
+    ) -> List[Diagnostic]:
+        """
+        Detect uncleared placeholders in issue content.
+        
+        Placeholders are template hints that should be removed before submission.
+        Examples:
+        - <!-- Required for Review/Done stage. Record review feedback here. -->
+        - <!-- TODO: Add implementation details -->
+        - <!-- Placeholder: ... -->
+        
+        Severity depends on stage:
+        - review/done: ERROR (must be cleared before submission)
+        - draft/open/doing: WARNING (should be cleared)
+        """
+        diagnostics = []
+        
+        # Define placeholder patterns
+        placeholder_patterns = [
+            # HTML comments with common placeholder keywords
+            (r"<!--\s*Required for Review/Done stage.*?-->", "Review/Done placeholder"),
+            (r"<!--\s*TODO:.*?-->", "TODO placeholder"),
+            (r"<!--\s*FIXME:.*?-->", "FIXME placeholder"),
+            (r"<!--\s*Placeholder:.*?-->", "Generic placeholder"),
+            (r"<!--\s*Template:.*?-->", "Template placeholder"),
+            (r"<!--\s*Example:.*?-->", "Example placeholder"),
+            # Generic instruction patterns (English and Chinese)
+            (r"<!--\s*Record review feedback here.*?-->", "Review placeholder"),
+            (r"<!--\s*在此记录评审反馈.*?-->", "Review placeholder (Chinese)"),
+        ]
+        
+        lines = content.splitlines()
+        
+        # Determine severity based on stage
+        if meta.stage in ["review", "done"]:
+            severity = DiagnosticSeverity.Error
+        else:
+            severity = DiagnosticSeverity.Warning
+        
+        for line_idx, line in enumerate(lines):
+            for pattern, desc in placeholder_patterns:
+                if re.search(pattern, line, re.IGNORECASE):
+                    diagnostics.append(
+                        self._create_diagnostic(
+                            f"Uncleared Placeholder: {desc} found. Remove template hints before submission.",
+                            severity,
+                            line_idx,
+                        )
+                    )
+                    break  # Only report once per line
+        
+        return diagnostics

monoco/features/memo/__init__.py

@@ -0,0 +1,4 @@
+from .cli import app
+from .adapter import MemoFeature
+
+__all__ = ["app", "MemoFeature"]

monoco/features/memo/adapter.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+from typing import Dict
+from monoco.core.feature import MonocoFeature, IntegrationData
+
+
+class MemoFeature(MonocoFeature):
+    @property
+    def name(self) -> str:
+        return "memo"
+
+    def initialize(self, root: Path, config: Dict) -> None:
+        # Memo feature doesn't require explicit initialization
+        # The inbox is created on first use
+        pass
+
+    def integrate(self, root: Path, config: Dict) -> IntegrationData:
+        # Determine language from config, default to 'en'
+        lang = config.get("i18n", {}).get("source_lang", "en")
+
+        # Resource path: monoco/features/memo/resources/{lang}/AGENTS.md
+        base_dir = Path(__file__).parent / "resources"
+
+        # Try specific language, fallback to 'en'
+        prompt_file = base_dir / lang / "AGENTS.md"
+        if not prompt_file.exists():
+            prompt_file = base_dir / "en" / "AGENTS.md"
+
+        content = ""
+        if prompt_file.exists():
+            content = prompt_file.read_text(encoding="utf-8").strip()
+
+        return IntegrationData(system_prompts={"Memo (Fleeting Notes)": content})