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

monoco/features/issue/engine/machine.py

@@ -79,6 +79,113 @@ class StateMachine:
             allowed.append(t)
         return allowed
 
+    def get_available_solutions(self, from_status: str, from_stage: Optional[str]) -> List[str]:
+        """Get all valid solutions for transitions from the current state."""
+        solutions = set()
+        for t in self.transitions:
+            # Skip non-transitions (agent actions with same status/stage)
+            if t.from_status is None and t.from_stage is None:
+                continue
+
+            if t.from_status and t.from_status != from_status:
+                continue
+            if t.from_stage and t.from_stage != from_stage:
+                continue
+
+            if t.required_solution:
+                solutions.add(t.required_solution)
+        return sorted(list(solutions))
+
+    def get_valid_transitions_from_state(
+        self, from_status: str, from_stage: Optional[str]
+    ) -> List[TransitionConfig]:
+        """Get all valid transitions from a given state."""
+        valid = []
+        for t in self.transitions:
+            # Skip non-transitions (agent actions with same status/stage)
+            if t.from_status is None and t.from_stage is None:
+                continue
+
+            if t.from_status and t.from_status != from_status:
+                continue
+            if t.from_stage and t.from_stage != from_stage:
+                continue
+
+            valid.append(t)
+        return valid
+
+    def _format_state(self, status: str, stage: Optional[str]) -> str:
+        """Format a state for display in error messages."""
+        # Handle Enum values
+        if hasattr(status, 'value'):
+            status = status.value
+        if stage and hasattr(stage, 'value'):
+            stage = stage.value
+        
+        if stage:
+            return f"{status}({stage})"
+        return status
+
+    def _build_transition_not_found_error(
+        self,
+        from_status: str,
+        from_stage: Optional[str],
+        to_status: str,
+        to_stage: Optional[str],
+    ) -> str:
+        """Build a descriptive error message when no transition is found."""
+        current_state = self._format_state(from_status, from_stage)
+        target_state = self._format_state(to_status, to_stage)
+
+        error_msg = (
+            f"Lifecycle Policy: Transition from '{current_state}' "
+            f"to '{target_state}' is not defined."
+        )
+
+        # Add available transitions hint
+        valid_transitions = self.get_valid_transitions_from_state(from_status, from_stage)
+        if valid_transitions:
+            error_msg += " Available transitions from this state:"
+            for t in valid_transitions:
+                target = self._format_state(t.to_status, t.to_stage)
+                if t.required_solution:
+                    error_msg += f"\n  - {t.name}: '{current_state}' -> '{target}' (requires --solution {t.required_solution})"
+                else:
+                    error_msg += f"\n  - {t.name}: '{current_state}' -> '{target}'"
+        else:
+            error_msg += " No transitions are available from this state."
+
+        return error_msg
+
+    def _build_invalid_solution_error(
+        self,
+        transition: TransitionConfig,
+        provided_solution: Optional[str],
+        from_status: str,
+        from_stage: Optional[str],
+    ) -> str:
+        """Build a descriptive error message when solution is invalid or missing."""
+        current_state = self._format_state(from_status, from_stage)
+        target_state = self._format_state(transition.to_status, transition.to_stage)
+
+        if provided_solution:
+            error_msg = (
+                f"Lifecycle Policy: Transition '{transition.label}' from '{current_state}' "
+                f"to '{target_state}' does not accept solution '{provided_solution}'."
+            )
+        else:
+            error_msg = (
+                f"Lifecycle Policy: Transition '{transition.label}' from '{current_state}' "
+                f"to '{target_state}' requires a solution."
+            )
+
+        # Get valid solutions for this transition
+        valid_solutions = self.get_available_solutions(from_status, from_stage)
+        if valid_solutions:
+            error_msg += f" Valid solutions are: {', '.join(valid_solutions)}."
+
+        return error_msg
+
     def find_transition(
         self,
         from_status: str,
@@ -134,7 +241,7 @@ class StateMachine:
         to_stage: Optional[str],
         solution: Optional[str] = None,
         meta: Optional[IssueMetadata] = None,
-    ) -> Optional[TransitionConfig]:
+    ) -> TransitionConfig:
         """
         Validate if a transition is allowed. Raises ValueError if not.
         If meta is provided, also validates criticality-based policies.
@@ -149,13 +256,16 @@ class StateMachine:
 
         if not transition:
             raise ValueError(
-                f"Lifecycle Policy: Transition from {from_status}({from_stage if from_stage else 'None'}) "
-                f"to {to_status}({to_stage if to_stage else 'None'}) is not defined."
+                self._build_transition_not_found_error(
+                    from_status, from_stage, to_status, to_stage
+                )
             )
 
         if transition.required_solution and solution != transition.required_solution:
             raise ValueError(
-                f"Lifecycle Policy: Transition '{transition.label}' requires solution '{transition.required_solution}'."
+                self._build_invalid_solution_error(
+                    transition, solution, from_status, from_stage
+                )
             )
 
         # Criticality-based policy checks

monoco/features/issue/linter.py

@@ -29,7 +29,7 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
 
     # 1. Collection Phase (Build Index)
     # Helper to collect issues from a project
-    def collect_project_issues(project_issues_root: Path, project_name: str = "local"):
+    def collect_project_issues(project_issues_root: Path, project_name: str = "local", include_archived: bool = False):
         project_issues = []
         project_diagnostics = []
         for subdir in ["Epics", "Features", "Chores", "Fixes", "Domains"]:
@@ -128,10 +128,30 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
                 else:
                     # Standard Issues (Epics/Features/etc)
                     files = []
-                    for status in ["open", "closed", "backlog"]:
-                        status_dir = d / status
-                        if status_dir.exists():
-                            files.extend(status_dir.rglob("*.md"))
+                    # Standard status directories
+                    status_dirs = ["open", "closed", "backlog"]
+                    # Include archived if requested (for full validation)
+                    if include_archived:
+                        status_dirs.append("archived")
+                    
+                    for item in d.iterdir():
+                        if item.is_dir():
+                            status = item.name.lower()
+                            if status in status_dirs:
+                                files.extend(item.rglob("*.md"))
+                            elif status != "archived": # archived is handled separately if include_archived
+                                # Report Illegal Directory immediately
+                                project_diagnostics.append(
+                                    Diagnostic(
+                                        range=Range(
+                                            start=Position(line=0, character=0),
+                                            end=Position(line=0, character=0),
+                                        ),
+                                        message=f"Illegal Directory: Issues should be in 'open/', 'closed/', or 'backlog/' directories, not '{status}/' directory.",
+                                        severity=DiagnosticSeverity.Error,
+                                        source="System",
+                                    )
+                                )
 
                     for f in files:
                         try:
@@ -283,12 +303,45 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
 
     # 2. Validation Phase
     valid_domains = set()
+    # Build list of actual IssueMetadata objects for domain governance checks
+    all_issue_metas = []
+    
     # Now validate
     for path, meta, project_name in all_issues:
         if meta == "DOMAIN":
             valid_domains.add(
                 project_name
             )  # Record the domain name (which was stored in project_name slot)
+        else:
+            all_issue_metas.append(meta)
+
+    # FEAT-0136: Project-Level Domain Governance Check
+    # Calculate scale metrics
+    num_issues = len(all_issue_metas)
+    num_epics = len([i for i in all_issue_metas if i.type == "epic"])
+    is_large_scale = num_issues > 128 or num_epics > 32
+    
+    # Check Domain Coverage for large-scale projects
+    if is_large_scale and num_epics > 0:
+        epics = [i for i in all_issue_metas if i.type == "epic"]
+        untracked_epics = [e for e in epics if not e.domains]
+        untracked_ratio = len(untracked_epics) / len(epics)
+        
+        # Rule: Untracked Epics / Total Epics <= 25%
+        if untracked_ratio > 0.25:
+            # Report this as a project-level diagnostic (attached to first epic or general)
+            diagnostics.append(
+                Diagnostic(
+                    range=Range(
+                        start=Position(line=0, character=0),
+                        end=Position(line=0, character=0),
+                    ),
+                    message=f"Domain Governance: Coverage is too low for a project of this scale ({len(untracked_epics)}/{len(epics)} Epics untracked). "
+                            f"At least 75% of Epics must have domains assigned.",
+                    severity=DiagnosticSeverity.Error,
+                    source="DomainGovernance",
+                )
+            )
 
     for path, meta, project_name in all_issues:
         if meta == "DOMAIN":
@@ -325,6 +378,7 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
 
         # A. Run Core Validator
         # Pass valid_domains kwarg (Validator needs update to accept it)
+        # FEAT-0136: Also pass all_issue_metas for domain governance checks
         file_diagnostics = validator.validate(
             meta,
             content,
@@ -332,6 +386,7 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
             current_project=project_name,
             workspace_root=workspace_root_name,
             valid_domains=valid_domains,
+            all_issues=all_issue_metas,
         )
 
         # Add context to diagnostics (Path)

monoco/features/issue/models.py

@@ -74,6 +74,7 @@ class IssueStatus(str, Enum):
     OPEN = "open"
     CLOSED = "closed"
     BACKLOG = "backlog"
+    ARCHIVED = "archived"
 
 
 class IssueStage(str, Enum):
@@ -223,8 +224,7 @@ class IssueMetadata(BaseModel):
             # Stage normalization
             if "stage" in v and isinstance(v["stage"], str):
                 v["stage"] = v["stage"].lower()
-                if v["stage"] == "todo":
-                    v["stage"] = "draft"
+
                 try:
                     v["stage"] = IssueStage(v["stage"])
                 except ValueError:

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
 ---