monoco-toolkit 0.3.10__py3-none-any.whl → 0.3.11__py3-none-any.whl

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

@@ -20,3 +20,112 @@ System for managing tasks using `monoco issue`.
      - 🛑 **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).
+
+## Git Merge Strategy
+
+### Core Principles
+
+To ensure safe merging of Feature branches into the mainline and prevent "stale state pollution", the following merge strategy must be followed:
+
+#### 1. No Manual Merge
+
+- **🛑 STRICTLY FORBIDDEN**: Agents must NOT manually execute `git merge` to merge Feature branches
+- **🛑 STRICTLY FORBIDDEN**: Using `git pull origin main` followed by direct commits
+- **✅ ONLY AUTHORITATIVE PATH**: Must use `monoco issue close` for closing the loop
+
+#### 2. Safe Merge Flow
+
+The correct Issue closing workflow is as follows:
+
+```bash
+# 1. Ensure you're on main/master branch and code is merged
+$ git checkout main
+$ git pull origin main
+
+# 2. Confirm Feature branch changes are merged to mainline
+#    (via PR/MR or other code review process)
+
+# 3. Use monoco issue close to close Issue (prune by default)
+$ monoco issue close FEAT-XXXX --solution implemented
+
+# 4. To keep branch, use --no-prune
+$ monoco issue close FEAT-XXXX --solution implemented --no-prune
+```
+
+#### 3. Conflict Resolution Principles
+
+When Feature branch conflicts with mainline:
+
+1. **Auto-merge Stop**: If `touched files` (Issue `files` field) conflict with mainline, automation tools **MUST IMMEDIATELY STOP** merging and throw a clear error.
+
+2. **Manual Cherry-Pick Mode**:
+   - Error message will instruct Agent to switch to manual Cherry-Pick mode
+   - **Core Principle**: Only pick valid changes belonging to this Feature, STRICTLY FORBIDDEN from overwriting updates to unrelated Issues on mainline
+   - Use `git cherry-pick <commit>` to apply valid commits one by one
+
+3. **Fallback Strategy**:
+   ```bash
+   # 1. Create temporary branch for conflict resolution
+   $ git checkout main
+   $ git checkout -b temp/FEAT-XXXX-resolve
+   
+   # 2. Cherry-pick valid commits one by one
+   $ git cherry-pick <commit-hash-1>
+   $ git cherry-pick <commit-hash-2>
+   
+   # 3. If conflicts occur, only keep changes from this Feature
+   #    Discard any modifications that would overwrite other Issue updates on mainline
+   
+   # 4. Merge temporary branch when done
+   $ git checkout main
+   $ git merge temp/FEAT-XXXX-resolve
+   
+   # 5. Close Issue
+   $ monoco issue close FEAT-XXXX --solution implemented
+   ```
+
+#### 4. Smart Atomic Merge Based on files Field
+
+The Issue's `files` field records the Actual Impact Scope of the Feature branch:
+
+- **Generation**: `monoco issue sync-files` uses `git diff --name-only base...target` logic
+- **Purpose**: Serves as a merge whitelist, only merging files in the list, filtering out implicit overwrites caused by "stale baseline"
+- **Limitation**: Cannot defend against explicit accidental modifications (e.g., inadvertently formatting other Issue files)
+
+**Future Enhancement**: Implement selective merge logic based on `files` list:
+```bash
+# Selective merge (planned)
+$ git checkout main
+$ git checkout feature/FEAT-XXXX -- <files...>
+```
+
+#### 5. Cleanup Strategy
+
+- **Default Cleanup**: `monoco issue close` executes `--prune` by default, deleting Feature branch/worktree
+- **Keep Branch**: To preserve branch, explicitly use `--no-prune`
+- **Force Cleanup**: Use `--force` to force delete unmerged branches (use with caution)
+
+```bash
+# Default branch cleanup
+$ monoco issue close FEAT-XXXX --solution implemented
+# ✔ Cleaned up: branch:feat/feat-XXXX-xxx
+
+# Keep branch
+$ monoco issue close FEAT-XXXX --solution implemented --no-prune
+
+# Force cleanup (caution)
+$ monoco issue close FEAT-XXXX --solution implemented --force
+```
+
+### Summary
+
+| Operation | Command | Description |
+|-----------|---------|-------------|
+| Create Issue | `monoco issue create feature -t "Title"` | Create Issue before development |
+| Start Development | `monoco issue start FEAT-XXXX --branch` | Create Feature branch |
+| Sync Files | `monoco issue sync-files` | Update files field |
+| Submit Review | `monoco issue submit FEAT-XXXX` | Enter Review stage |
+| Close Issue | `monoco issue close FEAT-XXXX --solution implemented` | Only merge path |
+| Keep Branch | `monoco issue close ... --no-prune` | Close without deleting branch |
+
+> ⚠️ **WARNING**: Any manual merge operation bypassing `monoco issue close` may cause mainline state pollution and violate workflow compliance requirements.

monoco/features/issue/resources/en/skills/{monoco_issue → monoco_atom_issue}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: monoco-issue
+name: monoco_atom_issue
 description: Official skill for Monoco Issue System. Treats Issues as Universal Atoms, managing the lifecycle of Epic/Feature/Chore/Fix.
-type: standard
+type: atom
 version: 1.0.0
 ---
 

monoco/features/issue/resources/en/skills/{issue_create_workflow → monoco_workflow_issue_creation}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: issue-create-workflow
+name: monoco_workflow_issue_creation
 description: Extract improvement clues from Memo, classify and create Issue Ticket (Copilot Mode)
-type: flow
+type: workflow
 domain: issue
 version: 1.0.0
 ---

monoco/features/issue/resources/en/skills/{issue_develop_workflow → monoco_workflow_issue_development}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: issue-develop-workflow
+name: monoco_workflow_issue_development
 description: Execute complete workflow for Issue development, testing, submission and review (Copilot Mode)
-type: flow
+type: workflow
 domain: issue
 version: 1.0.0
 ---

monoco/features/issue/resources/en/skills/{issue_lifecycle_workflow → monoco_workflow_issue_management}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: issue-lifecycle-workflow
+name: monoco_workflow_issue_management
 description: Issue Lifecycle Workflow (Flow Skill). Defines the complete Issue management process from creation to closure, ensuring task tracking and process compliance.
-type: flow
+type: workflow
 domain: issue
 version: 1.0.0
 ---

monoco/features/issue/resources/en/skills/{issue_refine_workflow → monoco_workflow_issue_refinement}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: issue-refine-workflow
+name: monoco_workflow_issue_refinement
 description: Investigate and refine Issue, supplement technical details and implementation plan (Copilot Mode)
-type: flow
+type: workflow
 domain: issue
 version: 1.0.0
 ---

monoco/features/issue/resources/hooks/post-checkout.sh

@@ -0,0 +1,39 @@
+#!/bin/sh
+# Issue Feature Post-Checkout Hook
+# Automatically syncs issue status when switching branches
+
+echo "[Monoco] Syncing issue status after branch checkout..."
+
+# Get the previous and current HEAD
+PREVIOUS_HEAD="$1"
+NEW_HEAD="$2"
+BRANCH_SWITCH="$3"  # 1 if branch switch, 0 if file checkout
+
+# Only sync on actual branch switches, not file checkouts
+if [ "$BRANCH_SWITCH" != "1" ]; then
+    echo "[Monoco] File checkout detected, skipping issue sync."
+    exit 0
+fi
+
+# Get current branch name
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "HEAD")
+
+echo "[Monoco] Switched to branch: $CURRENT_BRANCH"
+
+# Try to extract issue ID from branch name
+# Common patterns: FEAT-123, feat/FEAT-123, feature/FEAT-123, fix/FEAT-123
+ISSUE_ID=$(echo "$CURRENT_BRANCH" | grep -oE '[A-Z]+-[0-9]+' | head -1)
+
+if [ -n "$ISSUE_ID" ]; then
+    echo "[Monoco] Detected issue ID from branch: $ISSUE_ID"
+
+    # Check if issue exists and update its isolation ref if needed
+    $MONOCO_CMD issue sync-isolation "$ISSUE_ID" --branch "$CURRENT_BRANCH" 2>/dev/null || true
+fi
+
+# Run general sync to ensure files field is up to date
+echo "[Monoco] Running issue file sync..."
+$MONOCO_CMD issue sync-files 2>/dev/null || true
+
+echo "[Monoco] Issue sync complete."
+exit 0

monoco/features/issue/resources/hooks/pre-commit.sh

@@ -0,0 +1,41 @@
+#!/bin/sh
+# Issue Feature Pre-Commit Hook
+# Runs monoco issue lint on staged Issue files
+
+echo "[Monoco] Checking Issue integrity..."
+
+# Get the list of staged Issue files
+STAGED_ISSUES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '^Issues/.*\.md$' || true)
+
+if [ -z "$STAGED_ISSUES" ]; then
+    echo "[Monoco] No Issue files staged. Skipping lint."
+    exit 0
+fi
+
+# Run lint on staged Issue files
+echo "[Monoco] Running lint on staged Issue files..."
+
+# Build file list for monoco command
+FILE_ARGS=""
+for file in $STAGED_ISSUES; do
+    FILE_ARGS="$FILE_ARGS $file"
+done
+
+# Execute lint on each file
+LINT_EXIT=0
+for file in $STAGED_ISSUES; do
+    $MONOCO_CMD issue lint "$file"
+    if [ $? -ne 0 ]; then
+        LINT_EXIT=1
+    fi
+done
+
+if [ $LINT_EXIT -ne 0 ]; then
+    echo ""
+    echo "[Monoco] Issue lint failed. Please fix the errors above."
+    echo "[Monoco] You can run 'monoco issue lint --fix' to attempt automatic fixes."
+    exit $LINT_EXIT
+fi
+
+echo "[Monoco] Issue lint passed."
+exit 0

monoco/features/issue/resources/hooks/pre-push.sh

@@ -0,0 +1,35 @@
+#!/bin/sh
+# Issue Feature Pre-Push Hook
+# Checks for incomplete critical issues before pushing
+
+echo "[Monoco] Checking critical issues before push..."
+
+# Get the list of commits being pushed
+# $1 = remote name, $2 = remote url (if available)
+REMOTE="$1"
+URL="$2"
+
+# Check for high/critical issues that are not closed
+# This uses monoco issue query to find open issues with high/critical criticality
+echo "[Monoco] Scanning for incomplete critical issues..."
+
+# Run the check using monoco command
+$MONOCO_CMD issue check-critical --fail-on-warning
+CHECK_EXIT=$?
+
+if [ $CHECK_EXIT -eq 2 ]; then
+    echo ""
+    echo "[Monoco] ❌ Critical issues found! Push blocked."
+    echo "[Monoco] Please close or resolve the critical issues above before pushing."
+    exit 1
+elif [ $CHECK_EXIT -eq 1 ]; then
+    echo ""
+    echo "[Monoco] ⚠️  High priority issues found."
+    echo "[Monoco] Use --force-push to bypass this warning (not recommended)."
+    # For now, we allow the push but warn
+    # To block, change the exit code to 1
+    exit 0
+fi
+
+echo "[Monoco] ✓ No blocking critical issues found."
+exit 0

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

@@ -20,3 +20,112 @@
      - 🛑 **禁止**直接在 `main`/`master` 分支修改代码 (Linter 会报错)。
      - **清理时机**: 环境清理仅应在 `close` 时执行。**禁止**在 `submit` 阶段清理环境。
      - 修改代码后**必须**更新 `files` 字段（通过 `sync-files` 或手动）。
+
+## Git 合并策略 (Merge Strategy)
+
+### 核心原则
+
+为确保 Feature 分支安全合并到主线，避免"旧状态污染主线"问题，必须遵循以下合并策略：
+
+#### 1. 禁止手动 Merge
+
+- **🛑 严禁** Agent 手动执行 `git merge` 合并 Feature 分支
+- **🛑 严禁** 使用 `git pull origin main` 后直接提交
+- **✅ 唯一权威途径**: 必须使用 `monoco issue close` 进行闭环
+
+#### 2. 安全合并流程 (Safe Merge Flow)
+
+正确的 Issue 关闭流程如下：
+
+```bash
+# 1. 确保当前在 main/master 分支，且代码已合并
+$ git checkout main
+$ git pull origin main
+
+# 2. 确认 Feature 分支的变更已合并到主线
+#    (通过 PR/MR 或其他代码审查流程)
+
+# 3. 使用 monoco issue close 关闭 Issue (默认执行 prune)
+$ monoco issue close FEAT-XXXX --solution implemented
+
+# 4. 如需保留分支，使用 --no-prune
+$ monoco issue close FEAT-XXXX --solution implemented --no-prune
+```
+
+#### 3. 冲突处理原则
+
+当 Feature 分支与主线产生冲突时：
+
+1. **自动合并停止**: 如果 `touched files` (Issue `files` 字段) 与主线产生冲突，自动化工具**必须立即停止合并**，并抛出明确错误。
+
+2. **手动 Cherry-Pick 模式**: 
+   - 错误信息会指示 Agent 转入手动 Cherry-Pick 模式
+   - **核心原则**: 仅挑选属于本 Feature 的有效变更，严禁覆盖主线上无关 Issue 的更新
+   - 使用 `git cherry-pick <commit>` 逐个应用有效提交
+
+3. **Fallback 策略**:
+   ```bash
+   # 1. 创建临时分支用于解决冲突
+   $ git checkout main
+   $ git checkout -b temp/FEAT-XXXX-resolve
+   
+   # 2. 逐个 Cherry-Pick 有效提交
+   $ git cherry-pick <commit-hash-1>
+   $ git cherry-pick <commit-hash-2>
+   
+   # 3. 如有冲突，仅保留本 Feature 的变更
+   #    放弃任何会覆盖主线上其他 Issue 更新的修改
+   
+   # 4. 完成后合并临时分支
+   $ git checkout main
+   $ git merge temp/FEAT-XXXX-resolve
+   
+   # 5. 关闭 Issue
+   $ monoco issue close FEAT-XXXX --solution implemented
+   ```
+
+#### 4. 基于 files 字段的智能合并 (Smart Atomic Merge)
+
+Issue 的 `files` 字段记录了 Feature 分支的真实影响范围 (Actual Impact Scope)：
+
+- **生成方式**: `monoco issue sync-files` 使用 `git diff --name-only base...target` 逻辑
+- **作用**: 作为合并白名单，仅合并列表中的文件，过滤因"旧版本基线"导致的隐性覆盖
+- **限制**: 无法防御显式的误操作修改（如无意中格式化其他 Issue 文件）
+
+**未来增强**: 基于 `files` 列表实现选择性合并逻辑：
+```bash
+# 选择性合并（规划中）
+$ git checkout main
+$ git checkout feature/FEAT-XXXX -- <files...>
+```
+
+#### 5. 清理策略
+
+- **默认清理**: `monoco issue close` 默认执行 `--prune`，删除 Feature 分支/Worktree
+- **保留分支**: 如需保留分支，显式使用 `--no-prune`
+- **强制清理**: 使用 `--force` 强制删除未完全合并的分支（谨慎使用）
+
+```bash
+# 默认清理分支
+$ monoco issue close FEAT-XXXX --solution implemented
+# ✔ Cleaned up: branch:feat/feat-XXXX-xxx
+
+# 保留分支
+$ monoco issue close FEAT-XXXX --solution implemented --no-prune
+
+# 强制清理（谨慎）
+$ monoco issue close FEAT-XXXX --solution implemented --force
+```
+
+### 总结
+
+| 操作 | 命令 | 说明 |
+|------|------|------|
+| 创建 Issue | `monoco issue create feature -t "标题"` | 先创建 Issue 再开发 |
+| 启动开发 | `monoco issue start FEAT-XXXX --branch` | 创建 Feature 分支 |
+| 同步文件 | `monoco issue sync-files` | 更新 files 字段 |
+| 提交评审 | `monoco issue submit FEAT-XXXX` | 进入 Review 阶段 |
+| 关闭 Issue | `monoco issue close FEAT-XXXX --solution implemented` | 唯一合并途径 |
+| 保留分支 | `monoco issue close ... --no-prune` | 关闭但不删除分支 |
+
+> ⚠️ **警告**: 任何绕过 `monoco issue close` 的手动合并操作都可能导致主线状态污染，违反工作流合规要求。

monoco/features/issue/resources/zh/skills/{monoco_issue → monoco_atom_issue_lifecycle}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: monoco-issue
+name: monoco_atom_issue_lifecycle
 description: Monoco Issue System 的官方技能定义。将 Issue 视为通用原子 (Universal Atom)，管理 Epic/Feature/Chore/Fix 的生命周期。
-type: standard
+type: atom
 version: 1.0.0
 ---
 

monoco/features/issue/resources/zh/skills/{issue_create_workflow → monoco_workflow_issue_creation}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: issue-create-workflow
+name: monoco_workflow_issue_creation
 description: 从 Memo 提取改进线索，分类并创建 Issue Ticket (Copilot 模式)
-type: flow
+type: workflow
 domain: issue
 version: 1.0.0
 ---

monoco/features/issue/resources/zh/skills/{issue_develop_workflow → monoco_workflow_issue_development}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: issue-develop-workflow
+name: monoco_workflow_issue_development
 description: 执行 Issue 开发、测试、提交和评审的完整工作流 (Copilot 模式)
-type: flow
+type: workflow
 domain: issue
 version: 1.0.0
 ---

monoco/features/issue/resources/zh/skills/{issue_lifecycle_workflow → monoco_workflow_issue_management}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: issue-lifecycle-workflow
+name: monoco_workflow_issue_management
 description: Issue 生命周期工作流 (Flow Skill)。定义从创建到关闭的完整 Issue 管理流程，确保任务追踪和流程合规。
-type: flow
+type: workflow
 domain: issue
 version: 1.0.0
 ---

monoco/features/issue/resources/zh/skills/{issue_refine_workflow → monoco_workflow_issue_refinement}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: issue-refine-workflow
+name: monoco_workflow_issue_refinement
 description: 调查并细化 Issue，补充技术细节和实现方案 (Copilot 模式)
-type: flow
+type: workflow
 domain: issue
 version: 1.0.0
 ---

monoco/features/issue/validator.py

@@ -28,9 +28,19 @@ class IssueValidator:
         current_project: Optional[str] = None,
         workspace_root: Optional[str] = None,
         valid_domains: Set[str] = set(),
+        all_issues: List[IssueMetadata] = None,
     ) -> List[Diagnostic]:
         """
         Validate an issue and return diagnostics.
+        
+        Args:
+            meta: Issue metadata to validate
+            content: Full content of the issue file
+            all_issue_ids: Set of all issue IDs in the project (for reference validation)
+            current_project: Current project name
+            workspace_root: Workspace root project name
+            valid_domains: Set of valid domain names
+            all_issues: List of all IssueMetadata objects (for domain governance checks, FEAT-0136)
         """
         diagnostics = []
         self._current_project = current_project
@@ -65,6 +75,9 @@ class IssueValidator:
         # 1. State Matrix Validation
         diagnostics.extend(self._validate_state_matrix(meta, content))
 
+        # 1.5 Directory Consistency (FEAT-0144)
+        diagnostics.extend(self._validate_directory_consistency(meta, content))
+
         # 2. State Requirements (Strict Verification)
         diagnostics.extend(self._validate_state_requirements(meta, blocks))
 
@@ -80,7 +93,7 @@ class IssueValidator:
         # 5.5 Domain Integrity
         diagnostics.extend(
             self._validate_domains(
-                meta, content, all_issue_ids, valid_domains=valid_domains
+                meta, content, all_issue_ids, valid_domains=valid_domains, all_issues=all_issues
             )
         )
 
@@ -151,6 +164,62 @@ class IssueValidator:
                     return i
         return 0
 
+    def _validate_directory_consistency(
+        self, meta: IssueMetadata, content: str
+    ) -> List[Diagnostic]:
+        """
+        Check if the issue status matches its physical directory.
+        Checks for illegal directory names (like 'done' or 'freezed').
+        """
+        diagnostics = []
+        if not meta.path:
+            return diagnostics
+
+        path = Path(meta.path)
+        parent_dir_name = path.parent.name.lower()
+
+        # 1. Status/Directory Mismatch
+        if meta.status == "open" and parent_dir_name == "closed":
+            diagnostics.append(
+                self._create_diagnostic(
+                    f"Status/Directory Mismatch: Issue '{meta.id}' has status 'open' but is in 'closed/' directory.",
+                    DiagnosticSeverity.Error,
+                )
+            )
+        elif meta.status == "closed" and parent_dir_name == "open":
+            diagnostics.append(
+                self._create_diagnostic(
+                    f"Status/Directory Mismatch: Issue '{meta.id}' has status 'closed' but is in 'open/' directory.",
+                    DiagnosticSeverity.Error,
+                )
+            )
+
+        # 2. Illegal Directory Names
+        if parent_dir_name == "done":
+            diagnostics.append(
+                self._create_diagnostic(
+                    "Illegal Directory: Issues should be in 'closed/' directory, not 'done/'.",
+                    DiagnosticSeverity.Error,
+                )
+            )
+        elif parent_dir_name == "freezed":
+            diagnostics.append(
+                self._create_diagnostic(
+                    "Illegal Directory: Issues should be in 'backlog/' directory, not 'freezed/'.",
+                    DiagnosticSeverity.Error,
+                )
+            )
+
+        return diagnostics
+
+    def _validate_status_enum(self, meta: IssueMetadata, content: str) -> List[Diagnostic]:
+        """Legacy helper for enum validation (mostly handled by Pydantic now)."""
+        return []
+
+    def _validate_stage_enum(self, meta: IssueMetadata, content: str) -> List[Diagnostic]:
+        """Legacy helper for enum validation (mostly handled by Pydantic now)."""
+        return []
+
     def _validate_state_matrix(
         self, meta: IssueMetadata, content: str
     ) -> List[Diagnostic]:
@@ -629,6 +698,7 @@ class IssueValidator:
         content: str,
         all_ids: Set[str] = set(),
         valid_domains: Set[str] = set(),
+        all_issues: List[IssueMetadata] = None,
     ) -> List[Diagnostic]:
         diagnostics = []
         # Check if 'domains' field exists in frontmatter text
@@ -674,6 +744,36 @@ class IssueValidator:
                     )
                 )
 
+        # FEAT-0136: Scale-Aware Domain Governance
+        # Rule: If Total Issues > 128 or Total Epics > 32, enforce strict Domain coverage
+        is_large_scale = num_issues > 128 or num_epics > 32
+        
+        # FEAT-0136: Domain Auto-Inheritance Logic
+        # If child issue has no domains but parent has, treat as inherited (logical inheritance)
+        if meta.type != "epic" and not meta.domains and meta.parent and all_issues and is_large_scale:
+            parent_issue = None
+            for issue in all_issues:
+                if issue.id == meta.parent:
+                    parent_issue = issue
+                    break
+            
+            if parent_issue and parent_issue.domains:
+                # Parent has domains, child inherits them logically
+                # This is not an error - it's valid inheritance
+                pass
+            elif parent_issue and not parent_issue.domains:
+                # Parent also has no domains in large scale mode - this is an error
+                line = self._get_field_line(content, "domains")
+                diagnostics.append(
+                    self._create_diagnostic(
+                        f"Domain Governance: Issue '{meta.id}' has no domains assigned. "
+                        f"Parent '{meta.parent}' also has no domains. In large-scale projects, "
+                        f"at least 75% of Epics must have domains for children to inherit.",
+                        DiagnosticSeverity.Error,
+                        line=line if line > 0 else field_line,
+                    )
+                )
+
         # Domain Content Validation
         # If valid_domains is provided (from file scan), use it as strict source of truth
         if hasattr(meta, "domains") and meta.domains:

monoco/features/memo/adapter.py

@@ -1,19 +1,32 @@
 from pathlib import Path
 from typing import Dict
-from monoco.core.feature import MonocoFeature, IntegrationData
+from monoco.core.loader import FeatureModule, FeatureMetadata
+from monoco.core.feature import IntegrationData
 
 
-class MemoFeature(MonocoFeature):
-    @property
-    def name(self) -> str:
-        return "memo"
+class MemoFeature(FeatureModule):
+    """Memo (fleeting notes) feature module with unified lifecycle support."""
 
-    def initialize(self, root: Path, config: Dict) -> None:
-        # Memo feature doesn't require explicit initialization
-        # The inbox is created on first use
+    @property
+    def metadata(self) -> FeatureMetadata:
+        return FeatureMetadata(
+            name="memo",
+            version="1.0.0",
+            description="Fleeting notes and quick idea capture",
+            dependencies=["core"],
+            priority=40,
+            lazy=True,  # Can be lazy loaded
+        )
+
+    def _on_mount(self, context: "FeatureContext") -> None:  # type: ignore
+        """Memo feature doesn't require explicit initialization.
+
+        The inbox is created on first use.
+        """
         pass
 
     def integrate(self, root: Path, config: Dict) -> IntegrationData:
+        """Provide integration data for agent environment."""
         # Determine language from config, default to 'en'
         lang = config.get("i18n", {}).get("source_lang", "en")