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

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.

monoco/features/issue/resources/hooks/agent/before-tool.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# JIT Hook: before-tool for Issue workflow compliance
+# Triggers: Bash, WriteFile tool calls
+# Purpose: Check branch compliance before code modifications
+
+---
+type: agent
+provider: claude-code
+event: before-tool
+matcher: ["Bash", "WriteFile"]
+priority: 10
+description: "Check code modification compliance (branch, sync-files)"
+---
+
+# Get current branch
+CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+
+# Check if we're on a protected branch
+if [[ "$CURRENT_BRANCH" == "main" || "$CURRENT_BRANCH" == "master" ]]; then
+    cat << 'EOF'
+{
+  "decision": "ask",
+  "reason": "Protected branch detected",
+  "message": "🛑 You are currently on the main/master branch. Direct modifications are prohibited.",
+  "metadata": {
+    "additionalContext": {
+      "current_branch": "main",
+      "reminders": [
+        "Use 'monoco issue start <ID> --branch' to create a feature branch",
+        "Never modify code directly on main/master branch"
+      ]
+    }
+  }
+}
+EOF
+    exit 0
+fi
+
+# Check if branch name follows feature branch pattern (contains FEAT-, FIX-, CHORE-)
+if [[ "$CURRENT_BRANCH" =~ (FEAT|FIX|CHORE)-[0-9]+ ]]; then
+    ISSUE_ID="${BASH_REMATCH[0]}"
+    
+    # Check for uncommitted changes that might need sync-files
+    if git diff --quiet HEAD 2>/dev/null; then
+        # No uncommitted changes
+        cat << EOF
+{
+  "decision": "allow",
+  "reason": "Branch check passed",
+  "message": "✅ Current in feature branch: $CURRENT_BRANCH",
+  "metadata": {
+    "additionalContext": {
+      "current_issue": "$ISSUE_ID",
+      "current_branch": "$CURRENT_BRANCH",
+      "reminders": [
+        "Run 'monoco issue sync-files' after modifying files",
+        "Run 'monoco issue submit $ISSUE_ID' when ready for review"
+      ]
+    }
+  }
+}
+EOF
+    else
+        # Has uncommitted changes
+        cat << EOF
+{
+  "decision": "allow",
+  "reason": "Branch check passed with pending changes",
+  "message": "⚠️ You have uncommitted changes. Remember to run sync-files before submit.",
+  "metadata": {
+    "additionalContext": {
+      "current_issue": "$ISSUE_ID",
+      "current_branch": "$CURRENT_BRANCH",
+      "uncommitted_changes": true,
+      "reminders": [
+        "Run 'monoco issue sync-files' to update files field",
+        "Run 'monoco issue submit $ISSUE_ID' when ready for review"
+      ]
+    }
+  }
+}
+EOF
+    fi
+else
+    # Not on a feature branch
+    cat << EOF
+{
+  "decision": "ask",
+  "reason": "Not on feature branch",
+  "message": "⚠️ You are on '$CURRENT_BRANCH' which does not appear to be a feature branch.",
+  "metadata": {
+    "additionalContext": {
+      "current_branch": "$CURRENT_BRANCH",
+      "reminders": [
+        "Use 'monoco issue start <ID> --branch' to work on an Issue",
+        "Or ensure your branch name contains the Issue ID (e.g., FEAT-0123-xxx)"
+      ]
+    }
+  }
+}
+EOF
+fi

monoco/features/issue/resources/hooks/agent/session-start.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+# JIT Hook: session-start for Issue context injection
+# Triggers: At the beginning of agent session
+# Purpose: Inject current Issue context into agent session
+
+---
+type: agent
+provider: claude-code
+event: session-start
+priority: 5
+description: "Inject current Issue context into session"
+---
+
+# Get current branch
+CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+
+# Try to extract Issue ID from branch name
+if [[ "$CURRENT_BRANCH" =~ (FEAT|FIX|CHORE|EPIC)-[0-9]+ ]]; then
+    ISSUE_ID="${BASH_REMATCH[0]}"
+    
+    # Try to find the Issue file
+    ISSUE_FILE=$(find /Users/indenscale/Documents/Projects/Monoco/Toolkit/Issues -name "${ISSUE_ID}*.md" 2>/dev/null | head -1)
+    
+    if [[ -n "$ISSUE_FILE" && -f "$ISSUE_FILE" ]]; then
+        # Extract issue metadata from front matter
+        ISSUE_STATUS=$(grep -E "^status:" "$ISSUE_FILE" | head -1 | cut -d: -f2 | tr -d ' ' || echo "unknown")
+        ISSUE_STAGE=$(grep -E "^stage:" "$ISSUE_FILE" | head -1 | cut -d: -f2 | tr -d ' ' || echo "unknown")
+        ISSUE_TITLE=$(grep -E "^title:" "$ISSUE_FILE" | head -1 | cut -d: -f2- | sed 's/^ *//' || echo "unknown")
+        
+        cat << EOF
+{
+  "decision": "allow",
+  "reason": "Issue context loaded",
+  "message": "📋 Active Issue: $ISSUE_ID - $ISSUE_TITLE",
+  "metadata": {
+    "additionalContext": {
+      "current_issue": "$ISSUE_ID",
+      "issue_title": "$ISSUE_TITLE",
+      "issue_status": "$ISSUE_STATUS",
+      "issue_stage": "$ISSUE_STAGE",
+      "current_branch": "$CURRENT_BRANCH",
+      "reminders": [
+        "Issue: $ISSUE_ID ($ISSUE_STATUS / $ISSUE_STAGE)",
+        "Run 'monoco issue sync-files' after file modifications",
+        "Run 'monoco issue submit $ISSUE_ID' when ready for review"
+      ]
+    }
+  }
+}
+EOF
+    else
+        # Issue file not found
+        cat << EOF
+{
+  "decision": "allow",
+  "reason": "Partial context loaded",
+  "message": "📋 Detected Issue ID: $ISSUE_ID from branch",
+  "metadata": {
+    "additionalContext": {
+      "current_issue": "$ISSUE_ID",
+      "current_branch": "$CURRENT_BRANCH",
+      "reminders": [
+        "Working on: $ISSUE_ID",
+        "Run 'monoco issue sync-files' after file modifications"
+      ]
+    }
+  }
+}
+EOF
+    fi
+else
+    # Not on a feature branch
+    cat << EOF
+{
+  "decision": "allow",
+  "reason": "No active Issue detected",
+  "message": "ℹ️ No active Issue detected from branch name",
+  "metadata": {
+    "additionalContext": {
+      "current_branch": "$CURRENT_BRANCH",
+      "reminders": [
+        "To start working: monoco issue start <ID> --branch"
+      ]
+    }
+  }
+}
+EOF
+fi

monoco/features/issue/resources/hooks/{post-checkout.sh → git/git-post-checkout.sh}

@@ -1,8 +1,10 @@
 #!/bin/sh
-# Issue Feature Post-Checkout Hook
-# Automatically syncs issue status when switching branches
-
-echo "[Monoco] Syncing issue status after branch checkout..."
+# ---
+# type: git
+# event: post-checkout
+# description: "Sync issue status and files after branch checkout"
+# priority: 100
+# ---
 
 # Get the previous and current HEAD
 PREVIOUS_HEAD="$1"
@@ -11,29 +13,28 @@ 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
 
+echo "[Monoco] Syncing issue status after branch checkout..."
+
 # 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
+    monoco 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
+monoco issue sync-files 2>/dev/null || true
 
 echo "[Monoco] Issue sync complete."
 exit 0

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

@@ -0,0 +1,31 @@
+#!/bin/sh
+# ---
+# type: git
+# event: pre-commit
+# matcher:
+#   - "Issues/**/*.md"
+# description: "Lint staged Issue files for integrity"
+# priority: 100
+# ---
+
+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
+    exit 0
+fi
+
+# Run lint on staged Issue files
+echo "[Monoco] Running lint on staged Issue files..."
+
+for file in $STAGED_ISSUES; do
+    monoco issue lint "$file"
+    if [ $? -ne 0 ]; then
+        exit 1
+    fi
+done
+
+echo "[Monoco] Issue lint passed."
+exit 0

monoco/features/issue/resources/hooks/{pre-push.sh → git/git-pre-push.sh}

@@ -1,20 +1,15 @@
 #!/bin/sh
-# Issue Feature Pre-Push Hook
-# Checks for incomplete critical issues before pushing
+# ---
+# type: git
+# event: pre-push
+# description: "Check for incomplete critical issues before pushing"
+# priority: 100
+# ---
 
 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
+monoco issue check-critical --fail-on-warning
 CHECK_EXIT=$?
 
 if [ $CHECK_EXIT -eq 2 ]; then
@@ -27,7 +22,6 @@ elif [ $CHECK_EXIT -eq 1 ]; then
     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
 

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

@@ -1,131 +1,26 @@
-# Issue 管理 (Agent 指引)
+# Issue 管理
 
-## Issue 管理
+使用 `monoco issue` 管理任务。
 
-使用 `monoco issue` 管理任务的系统。
-
-- **创建**: `monoco issue create <type> -t "标题"` (类型: epic, feature, chore, fix)
+- **创建**: `monoco issue create <type> -t "标题"`
 - **状态**: `monoco issue open|close|backlog <id>`
-- **检查**: `monoco issue lint` (手动编辑后必须运行)
+- **检查**: `monoco issue lint`
 - **生命周期**: `monoco issue start|submit|delete <id>`
-- **上下文同步**: `monoco issue sync-files [id]` (更新文件追踪)
-- **结构**: `Issues/{CapitalizedPluralType}/{lowercase_status}/` (如 `Issues/Features/open/`)。
-- **强制规则**:
-  1. **先有 Issue**: 在进行任何调研、设计或 Draft 之前，必须先使用 `monoco issue create` 创建 Issue。
-  2. **标题**: 必须包含 `## {ID}: {Title}` 标题（与 Front Matter 一致）。
-  3. **内容**: 至少 2 个 Checkbox，使用 `- [ ]`, `- [x]`, `- [-]`, `- [/]`。
-  4. **评审**: `review`/`done` 阶段必须包含 `## Review Comments` 章节且内容不为空。
-  5. **环境策略**:
-     - 必须使用 `monoco issue start --branch` 创建 Feature 分支。
-     - 🛑 **禁止**直接在 `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 sync-files [id]`
+- **结构**: `Issues/{CapitalizedPluralType}/{lowercase_status}/` (如 `Issues/Features/open/`)
 
-# 强制清理（谨慎）
-$ monoco issue close FEAT-XXXX --solution implemented --force
-```
+## 标准工作流
 
-### 总结
+1. **创建**: `monoco issue create feature -t "标题"`
+2. **启动**: `monoco issue start FEAT-XXX --branch`
+3. **实现**: 正常编码与测试。
+4. **同步**: `monoco issue sync-files` (更新 `files` 字段)。
+5. **提交**: `monoco issue submit FEAT-XXX`。
+6. **合规合并**: `monoco issue close FEAT-XXX --solution implemented` (合并到主线的唯一途径)。
 
-| 操作 | 命令 | 说明 |
-|------|------|------|
-| 创建 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` | 关闭但不删除分支 |
+## Git 合并策略
 
-> ⚠️ **警告**: 任何绕过 `monoco issue close` 的手动合并操作都可能导致主线状态污染，违反工作流合规要求。
+- **禁止手动合并**: 严禁在 `main`/`master` 分支执行 `git merge` 或直接 `git pull`。
+- **原子合并**: `monoco issue close` 仅根据 Issue 的 `files` 列表合并变更。
+- **冲突处理**: 若产生冲突，请遵循 `close` 命令产生的指引进行手动 Cherry-Pick。
+- **清理策略**: `monoco issue close` 默认执行清理（删除分支/Worktree）。需保留请指定 `--no-prune`。