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

monoco/features/issue/core.py

@@ -46,6 +46,32 @@ def get_issue_dir(issue_type: str, issues_root: Path) -> Path:
     return issues_root / folder
 
 
+def _extract_issue_id_from_branch(branch: str) -> Optional[str]:
+    """
+    Extract issue ID from a branch name.
+
+    Supported patterns:
+    - <ID>-slug (e.g., FEAT-0123-login-page)
+    - <ID> (e.g., FEAT-0123)
+
+    Args:
+        branch: Branch name to parse
+
+    Returns:
+        The extracted issue ID (uppercase) or None if no match
+    """
+    # Pattern: <prefix>-<number> at start of branch name
+    # Examples:
+    #   FEAT-0123-login-page -> FEAT-0123
+    #   FEAT-0123 -> FEAT-0123
+    #   FIX-0001-critical -> FIX-0001
+    pattern = r'^([a-z]+-\d+)'
+    match = re.match(pattern, branch, re.IGNORECASE)
+    if match:
+        return match.group(1).upper()
+    return None
+
+
 def _parse_isolation_ref(ref: str) -> str:
     """
     Parse isolation ref and strip any 'branch:' or 'worktree:' prefix.
@@ -83,6 +109,55 @@ def _get_slug(title: str) -> str:
     return slug
 
 
+def _unquote_git_path(path: str) -> str:
+    """
+    Decode Git C-quoting format paths to native strings.
+
+    Git uses C-quoting for paths containing non-ASCII characters or special characters:
+    - Wraps the path in double quotes: "path"
+    - Escapes bytes as octal: \351\207\215 represents UTF-8 bytes
+
+    Args:
+        path: Path string, potentially in Git C-quoting format
+
+    Returns:
+        Decoded native path string
+
+    Examples:
+        >>> _unquote_git_path('"path-\\351\\207\\215.md"')
+        'path-重.md'
+        >>> _unquote_git_path('"path\\ with\\ space.md"')
+        'path with space.md'
+        >>> _unquote_git_path('normal/path.md')
+        'normal/path.md'
+    """
+    path = path.strip()
+
+    # Check if the path is wrapped in double quotes (C-quoting format)
+    if not (path.startswith('"') and path.endswith('"')):
+        return path
+
+    # Remove outer quotes
+    path = path[1:-1]
+
+    # Collect all bytes (octal escapes -> bytes, ASCII chars -> their byte values)
+    bytes_list = []
+    i = 0
+    while i < len(path):
+        if path[i] == '\\' and i + 3 < len(path) and path[i+1:i+4].isdigit():
+            # This is an octal escape sequence (e.g., \351)
+            byte_val = int(path[i+1:i+4], 8)
+            bytes_list.append(byte_val)
+            i += 4
+        else:
+            # Regular ASCII character
+            bytes_list.append(ord(path[i]))
+            i += 1
+
+    # Decode the entire byte sequence as UTF-8
+    return bytes(bytes_list).decode('utf-8')
+
+
 def parse_issue(file_path: Path, raise_error: bool = False) -> Optional[IssueMetadata]:
     if not file_path.suffix == ".md":
         return None
@@ -494,14 +569,15 @@ def find_issue_path_across_branches(
     issues_root: Path, 
     issue_id: str, 
     project_root: Optional[Path] = None,
-    include_archived: bool = True
-) -> Tuple[Optional[Path], Optional[str]]:
+    include_archived: bool = True,
+    allow_multi_branch: bool = False
+) -> Tuple[Optional[Path], Optional[str], Optional[List[str]]]:
     """
     Find issue path across all local git branches.
     
     Implements the "Golden Path" logic:
     - If issue found in exactly one branch -> return it silently
-    - If issue found in multiple branches -> raise error (conflict)
+    - If issue found in multiple branches -> handle based on allow_multi_branch flag
     - If issue not found in any branch -> return None
     
     Args:
@@ -509,12 +585,14 @@ def find_issue_path_across_branches(
         issue_id: Issue ID to find
         project_root: Project root (defaults to issues_root.parent)
         include_archived: Whether to search in archived directory
+        allow_multi_branch: If True, return all conflicting branches instead of raising error
         
     Returns:
-        Tuple of (file_path, branch_name) or (None, None) if not found
+        Tuple of (file_path, branch_name, conflicting_branches) or (None, None, None) if not found
+        conflicting_branches is None if no conflict, or a list of branch names if conflict detected
         
     Raises:
-        RuntimeError: If issue found in multiple branches (conflict)
+        RuntimeError: If issue found in multiple branches and allow_multi_branch is False (conflict)
     """
     # First, try to find in current working tree
     local_path = find_issue_path(issues_root, issue_id, include_archived)
@@ -525,54 +603,16 @@ def find_issue_path_across_branches(
     
     # If not a git repo, just return local result
     if not git.is_git_repo(project_root):
-        return (local_path, None) if local_path else (None, None)
+        return (local_path, None, None) if local_path else (None, None, None)
     
     # Get current branch
     current_branch = git.get_current_branch(project_root)
     
-    # Search in all branches to detect conflicts (FIX-0006)
-    # If found locally, we still check other branches to detect potential duplicate files (conflict)
+    # Issue files existing in multiple branches is NORMAL - not a conflict
+    # Just return the local path without any conflict checking
     if local_path:
-        # Get relative path for git checking
-        try:
-            rel_path = local_path.relative_to(project_root)
-        except ValueError:
-            # If path is outside project root, we can't search other branches anyway
-            return local_path, current_branch
-            
-        conflicting_branches = _find_branches_with_file(project_root, str(rel_path), current_branch)
-        
-        # SPECIAL CASE (FIX-0006): During 'issue close' or similar operations,
-        # it is expected that the file exists in the feature branch (isolation branch)
-        # and now in the target branch (e.g. main). This is NOT a conflict.
-        if conflicting_branches:
-            # Try to parse metadata to see if these "conflicts" are actually the isolation branch
-            try:
-                meta = parse_issue(local_path)
-                if meta and meta.isolation:
-                    iso_type = getattr(meta.isolation, "type", None)
-                    iso_ref = getattr(meta.isolation, "ref", None)
-                    
-                    source_branch = None
-                    if iso_type == "branch":
-                        source_branch = iso_ref
-                    elif iso_ref and iso_ref.startswith("branch:"):
-                        source_branch = iso_ref[7:]
-                    
-                    if source_branch:
-                        # Filter out the source branch from conflicts
-                        conflicting_branches = [b for b in conflicting_branches if b != source_branch]
-            except Exception:
-                # If parsing fails, stick with raw conflicts to be safe
-                pass
-
-        if conflicting_branches:
-             raise RuntimeError(
-                f"Issue {issue_id} found in multiple branches: {current_branch}, {', '.join(conflicting_branches)}. "
-                f"Please resolve the conflict by merging branches or deleting duplicate issue files."
-            )
-        return local_path, current_branch
-        
+        return local_path, current_branch, None
+
     # Not found locally, search in all branches
     return _search_issue_in_branches(issues_root, issue_id, project_root, include_archived)
 
@@ -615,33 +655,34 @@ def _search_issue_in_branches(
     issue_id: str,
     project_root: Path,
     include_archived: bool = True
-) -> Tuple[Optional[Path], Optional[str]]:
+) -> Tuple[Optional[Path], Optional[str], Optional[List[str]]]:
     """
     Search for an issue file across all branches.
     
     Returns:
-        Tuple of (file_path, branch_name) or (None, None)
+        Tuple of (file_path, branch_name, conflicting_branches) or (None, None, None)
+        conflicting_branches is None if no conflict, or a list of branch names if conflict detected
         
     Raises:
-        RuntimeError: If issue found in multiple branches
+        RuntimeError: If issue found in multiple branches and allow_multi_branch is False
     """
     parsed = IssueID(issue_id)
     
     if not parsed.is_local:
         # For workspace issues, just use standard find
         path = find_issue_path(issues_root, issue_id, include_archived)
-        return (path, None) if path else (None, None)
+        return (path, None, None) if path else (None, None, None)
     
     # Get issue type from prefix
     try:
         prefix = parsed.local_id.split("-")[0].upper()
     except IndexError:
-        return None, None
+        return None, None, None
     
     reverse_prefix_map = get_reverse_prefix_map(issues_root)
     issue_type = reverse_prefix_map.get(prefix)
     if not issue_type:
-        return None, None
+        return None, None, None
     
     # Build possible paths to search
     base_dir = get_issue_dir(issue_type, issues_root)
@@ -657,7 +698,7 @@ def _search_issue_in_branches(
     # Get all local branches
     code, stdout, _ = git._run_git(["branch", "--format=%(refname:short)"], project_root)
     if code != 0:
-        return None, None
+        return None, None, None
     
     all_branches = [b.strip() for b in stdout.splitlines() if b.strip()]
     
@@ -687,15 +728,14 @@ def _search_issue_in_branches(
                     found_in_branches.append((branch, line))
     
     if not found_in_branches:
-        return None, None
+        return None, None, None
     
     if len(found_in_branches) > 1:
-        # Found in multiple branches - conflict
+        # Found in multiple branches - return all branches for caller to handle
         branches = [b for b, _ in found_in_branches]
-        raise RuntimeError(
-            f"Issue {issue_id} found in multiple branches: {', '.join(branches)}. "
-            f"Please resolve the conflict by merging branches or deleting duplicate issue files."
-        )
+        branch, file_path = found_in_branches[0]
+        full_path = project_root / file_path
+        return full_path, branch, branches
     
     # Golden path: exactly one match
     branch, file_path = found_in_branches[0]
@@ -704,11 +744,11 @@ def _search_issue_in_branches(
     try:
         git.git_checkout_files(project_root, branch, [file_path])
         full_path = project_root / file_path
-        return full_path, branch
+        return full_path, branch, None
     except Exception:
         # If checkout fails, return the path anyway - caller can handle
         full_path = project_root / file_path
-        return full_path, branch
+        return full_path, branch, None
 
 
 def update_issue(
@@ -1068,7 +1108,7 @@ def start_issue_isolation(
             )
 
     slug = _get_slug(issue.title)
-    branch_name = f"feat/{issue_id.lower()}-{slug}"
+    branch_name = f"{issue_id}-{slug}"
 
     isolation_meta = None
 
@@ -1206,9 +1246,41 @@ def delete_issue_file(issues_root: Path, issue_id: str):
     path.unlink()
 
 
+def _has_uncommitted_changes(project_root: Path) -> Tuple[bool, List[str]]:
+    """
+    Check if there are uncommitted changes in the working directory.
+    
+    Returns:
+        Tuple of (has_changes, list_of_changed_files)
+    """
+    # Check for staged changes
+    cmd_staged = ["diff", "--cached", "--name-only"]
+    code, stdout, _ = git._run_git(cmd_staged, project_root)
+    staged_files = [f.strip() for f in stdout.splitlines() if f.strip()] if code == 0 else []
+    
+    # Check for unstaged changes
+    cmd_unstaged = ["diff", "--name-only"]
+    code, stdout, _ = git._run_git(cmd_unstaged, project_root)
+    unstaged_files = [f.strip() for f in stdout.splitlines() if f.strip()] if code == 0 else []
+    
+    # Check for untracked files
+    cmd_untracked = ["ls-files", "--others", "--exclude-standard"]
+    code, stdout, _ = git._run_git(cmd_untracked, project_root)
+    untracked_files = [f.strip() for f in stdout.splitlines() if f.strip()] if code == 0 else []
+    
+    all_changes = list(set(staged_files + unstaged_files + untracked_files))
+    all_changes.sort()
+    
+    return len(all_changes) > 0, all_changes
+
+
 def sync_issue_files(issues_root: Path, issue_id: str, project_root: Path) -> List[str]:
     """
     Sync 'files' field in issue metadata with actual changed files in git.
+    
+    Pre-condition: All changes must be committed. If there are uncommitted changes,
+    this function will raise an error with instructions on how to proceed.
+    
     Strategies:
     1. Isolation Ref: If issue has isolation (branch/worktree), use that ref.
     2. Convention: If no isolation, look for branch `*/<id>-*`.
@@ -1224,6 +1296,20 @@ def sync_issue_files(issues_root: Path, issue_id: str, project_root: Path) -> Li
     if not issue:
         raise ValueError(f"Could not parse issue {issue_id}")
 
+    # CHORE-0036: Check for uncommitted changes
+    has_uncommitted, uncommitted_files = _has_uncommitted_changes(project_root)
+    if has_uncommitted:
+        files_list = "\n  - ".join([""] + uncommitted_files)
+        raise RuntimeError(
+            f"Uncommitted changes detected in working directory:{files_list}\n\n"
+            f"You must explicitly handle these files before syncing:\n"
+            f"  1. git add <files> && git commit -m '...'  (to commit)\n"
+            f"  2. git checkout -- <files>                   (to discard)\n"
+            f"  3. echo '<pattern>' >> .gitignore            (to ignore)\n"
+            f"  4. git rm <files>                            (to remove)\n\n"
+            f"After handling, run: monoco issue sync-files {issue_id}"
+        )
+
     # Determine Target Branch
     target_ref = None
 
@@ -1232,15 +1318,15 @@ def sync_issue_files(issues_root: Path, issue_id: str, project_root: Path) -> Li
         if target_ref == "current":
              target_ref = git.get_current_branch(project_root)
     else:
-        # Heuristic Search
-        # 1. Is current branch related?
+        # Heuristic Search - STRICT ID MATCHING ONLY
+        # 1. Is current branch's extracted ID exactly matching the issue ID?
         current = git.get_current_branch(project_root)
-        if issue_id.lower() in current.lower():
+        branch_issue_id = _extract_issue_id_from_branch(current)
+        if branch_issue_id and branch_issue_id.upper() == issue_id.upper():
             target_ref = current
         else:
-            # 2. Search for branch
-            # Limitation: core.git doesn't list all branches yet.
-            # We skip this for now to avoid complexity, relying on isolation or current context.
+            # 2. Search for branch - not implemented yet
+            # To avoid ambiguity, we only match current branch if it exactly matches
             pass
 
     if not target_ref:
@@ -1270,6 +1356,14 @@ def sync_issue_files(issues_root: Path, issue_id: str, project_root: Path) -> Li
 
     changed_files = [f.strip() for f in stdout.splitlines() if f.strip()]
 
+    # Decode Git C-quoting format paths to native paths
+    changed_files = [_unquote_git_path(f) for f in changed_files]
+
+    # FEAT-0172: Exclude issue file itself from files list
+    # Issue file is handled separately by update_issue (directory move + status update)
+    relative_issue_path = str(path.relative_to(project_root))
+    changed_files = [f for f in changed_files if f != relative_issue_path]
+
     # Sort for consistency
     changed_files.sort()
 
@@ -1308,28 +1402,21 @@ def merge_issue_changes(
     if issue.isolation and issue.isolation.ref:
         source_ref = _parse_isolation_ref(issue.isolation.ref)
     else:
-        # Heuristic: Search for branch by convention
-        # We can't use 'current' here safely if we are on main,
-        # but let's assume we might be calling this from elsewhere?
-        # Actually, for 'close', we are likely on main.
-        # So we search for a branch named 'feat/{id}-*' or similar?
-        pass
+        # Heuristic: Search for branch by convention {id}-*
+        import re
+        code, stdout, _ = git._run_git(["branch", "--format=%(refname:short)"], project_root)
+        if code == 0:
+            for branch in stdout.splitlines():
+                branch = branch.strip()
+                if re.match(rf"{re.escape(issue_id)}-", branch, re.IGNORECASE):
+                    source_ref = branch
+                    break
 
-    # If local metadata doesn't have isolation ref, we might be stuck.
-    # But let's assume valid workflow.
     if not source_ref:
-          # Try to find a branch starting with feat/{id} or {id}
-          # This is a bit weak, needs better implementation in 'git' or 'issue' module
-          # For now, if we can't find it, we error.
-          pass
-
-    if not source_ref or not git.branch_exists(project_root, source_ref):
-        # Fallback: maybe we are currently ON the feature branch?
-        # If so, source_ref should be current. But we expect to call this from MAIN.
-        pass
-        
-    if not source_ref:
-         raise RuntimeError(f"Could not determine source branch for Issue {issue_id}. Ensure isolation ref is set.")
+        # No branch found - files should already be in current branch
+        # This is valid for direct workflow (no feature branch created)
+        # Nothing to merge, files are already in place
+        return issue.files
 
     if not git.branch_exists(project_root, source_ref):
          raise RuntimeError(f"Source branch {source_ref} does not exist.")
@@ -1360,10 +1447,20 @@ def merge_issue_changes(
     if not issue.files:
          return []
 
-    # 1. Conflict Check
-    # A conflict occurs if a file in 'files' has changed on HEAD (main)
-    # since the common ancestor of HEAD and source_ref.
+    # Compatibility: Decode any legacy escaped paths in files field
+    # This handles files stored before the _unquote_git_path fix was applied
+    decoded_files = [_unquote_git_path(f) for f in issue.files]
 
+    if not decoded_files:
+        return []
+
+    # Identify the issue file path
+    relative_issue_path = str(path.relative_to(project_root))
+
+    # Separate files: issue file vs code files
+    code_files = [f for f in decoded_files if f != relative_issue_path]
+
+    # 1. Conflict Check (only for code files, issue file skips conflict check)
     current_head = git.get_current_branch(project_root)
     try:
         base = git.get_merge_base(project_root, current_head, source_ref)
@@ -1371,7 +1468,7 @@ def merge_issue_changes(
         raise RuntimeError(f"Failed to determine merge base: {e}")
 
     conflicts = []
-    for f in issue.files:
+    for f in code_files:
         # Has main changed this file?
         if git.has_diff(project_root, base, current_head, [f]):
             # Has feature also changed this file?
@@ -1386,12 +1483,15 @@ def merge_issue_changes(
         )
 
     # 2. Perform Atomic Merge (Selective Checkout)
-    try:
-        git.git_checkout_files(project_root, source_ref, issue.files)
-    except Exception as e:
-        raise RuntimeError(f"Selective checkout failed: {e}")
+    # FEAT-0172: Only merge code files, issue file is handled separately
+    files_to_merge = code_files
+    if files_to_merge:
+        try:
+            git.git_checkout_files(project_root, source_ref, files_to_merge)
+        except Exception as e:
+            raise RuntimeError(f"Selective checkout failed: {e}")
 
-    return issue.files
+    return files_to_merge
 
 
 # Resources

monoco/features/issue/domain_commands.py

@@ -26,22 +26,3 @@ def list_domains():
         )
 
     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]"
-            )

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

@@ -1,131 +1,26 @@
-# Issue Management (Agent Guidance)
-
-## Issue Management
+# Issue Management
 
 System for managing tasks using `monoco issue`.
 
-- **Create**: `monoco issue create <type> -t "Title"` (types: epic, feature, chore, fix)
+- **Create**: `monoco issue create <type> -t "Title"`
 - **Status**: `monoco issue open|close|backlog <id>`
-- **Check**: `monoco issue lint` (Must run after manual edits)
+- **Check**: `monoco issue lint`
 - **Lifecycle**: `monoco issue start|submit|delete <id>`
-- **Sync Context**: `monoco issue sync-files [id]` (Update file tracking)
-- **Structure**: `Issues/{CapitalizedPluralType}/{lowercase_status}/` (e.g. `Issues/Features/open/`). Do not deviate.
-- **Rules**:
-  1. **Issue First**: You MUST create an Issue (`monoco issue create`) before starting any work (research, design, or drafting).
-  2. **Heading**: Must have `## {ID}: {Title}` (matches metadata).
-  3. **Checkboxes**: Min 2 using `- [ ]`, `- [x]`, `- [-]`, `- [/]`.
-  4. **Review**: `## Review Comments` section required for Review/Done stages.
-  5. **Environment Policies**:
-     - Must use `monoco issue start --branch`.
-     - 🛑 **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
+- **Sync Context**: `monoco issue sync-files [id]`
+- **Structure**: `Issues/{CapitalizedPluralType}/{lowercase_status}/` (e.g. `Issues/Features/open/`)
 
-When Feature branch conflicts with mainline:
+## Standard Workflow
 
-1. **Auto-merge Stop**: If `touched files` (Issue `files` field) conflict with mainline, automation tools **MUST IMMEDIATELY STOP** merging and throw a clear error.
+1. **Create Issue**: `monoco issue create feature -t "Title"`
+2. **Start Branch**: `monoco issue start FEAT-XXX --branch`
+3. **Implement**: Normal coding and testing.
+4. **Sync Files**: `monoco issue sync-files` (Update `files` field).
+5. **Submit**: `monoco issue submit FEAT-XXX`.
+6. **Close & Merge**: `monoco issue close FEAT-XXX --solution implemented` (The only way to merge).
 
-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 |
+## Git Merge Strategy
 
-> ⚠️ **WARNING**: Any manual merge operation bypassing `monoco issue close` may cause mainline state pollution and violate workflow compliance requirements.
+- **NO Manual Merge**: Strictly forbidden from using `git merge` or `git pull` into main.
+- **Atomic Merge**: `monoco issue close` merges only the files listed in the `files` field.
+- **Conflicts**: If conflicts occur, follow the instructions provided by the `close` command (usually manual cherry-pick).
+- **Cleanup**: `monoco issue close` prunes the branch/worktree by default. Use `--no-prune` to keep it.