kenaz 0.0.0-stage → 0.3.2

package/core/.system/githooks/README.md

@@ -0,0 +1,846 @@
+# Git Hooks 自動化系統 (.githooks/)
+
+> **用途**: Git Hooks 自動化工具 — 增量索引、程式碼品質檢查、雙平台支援
+
+---
+
+## 系統概述
+
+`.githooks/` 是 Kenaz AI 的 **Git Hooks 自動化系統**，透過 Git 生命週期鉤子自動執行任務，提升開發效率與代碼品質。
+
+**核心功能**：
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   Git Hooks 系統                             │
+│                                                               │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │ post-commit  │  │ pre-commit   │  │ post-merge   │      │
+│  │   Hook       │  │    Hook      │  │    Hook      │      │
+│  │              │  │              │  │              │      │
+│  │ • RAG 索引   │  │ • 鎖定檢查   │  │ • 索引重建   │      │
+│  │ • 增量同步   │  │ • 衝突防護   │  │ • 任務同步   │      │
+│  │ • 非同步執行 │  │ • Pipeline   │  │ • 自動合併   │      │
+│  └──────────────┘  └──────────────┘  └──────────────┘      │
+│                                                               │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │          雙平台支援（Bash + PowerShell）             │  │
+│  │     Linux/Mac: Bash • Windows: Git Bash/PowerShell    │  │
+│  └──────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 核心組件
+
+### 1. post-commit Hook（Cortex RAG 增量索引）
+
+**觸發時機**：每次 `git commit` 後自動執行
+
+**功能**：
+- ✅ **Cortex RAG 增量索引**：自動同步代碼變更到向量資料庫
+- ✅ **非同步執行**：背景運行，不阻塞 commit 流程
+- ✅ **Lazy Sync 策略**：MCP Server 在下次工具呼叫時自動同步
+- ✅ **CI 環境跳過**：檢測 `CI` 或 `GITHUB_ACTIONS` 環境變數自動跳過
+
+**檔案位置**：
+```
+.githooks/post-commit        # Bash 版本（主力）
+.githooks/post-commit.ps1    # PowerShell 版本（備用）
+```
+
+**關鍵邏輯**（Bash 版本）：
+```bash
+# 檢查 CI 環境
+if [ -n "$CI" ] || [ -n "$GITHUB_ACTIONS" ]; then
+    echo "CI environment detected, skipping Cortex sync"
+    exit 0
+fi
+
+# 檢查配置文件中是否啟用
+check_hooks_enabled() {
+    local config_file="$PROJECT_ROOT/.cortex.yaml"
+    if [ -f "$config_file" ]; then
+        if grep -q "git_hooks:" "$config_file" && grep -q "enabled: true" "$config_file"; then
+            return 0
+        fi
+    fi
+    return 0  # 預設啟用
+}
+
+# MCP Server Lazy Sync 策略
+# 不再直接啟動 Python 進程寫 DB，避免與 MCP Server 的 ChromaDB 連線衝突
+run_sync() {
+    echo -e "${BLUE}Kenaz Cortex:${NC} MCP Server will auto-sync on next tool call"
+}
+```
+
+**配置方式**（`.cortex.yaml`）：
+```yaml
+git_hooks:
+  enabled: true
+  post_commit:
+    incremental_sync: true
+    async_mode: true         # 非同步執行（背景執行）
+    timeout: 30              # 超時秒數（同步模式下使用）
+```
+
+**工作流程**：
+```
+Git Commit
+    ↓
+post-commit Hook 觸發
+    ↓
+檢查 CI 環境 → 跳過（CI 環境）
+    ↓
+檢查 .cortex.yaml → enabled: true?
+    ↓
+輸出提示訊息（MCP Server 將自動同步）
+    ↓
+Hook 完成（非同步，不阻塞）
+    ↓
+下次呼叫 Cortex MCP 工具時
+    ↓
+MCP Server 自動增量同步 ChromaDB
+```
+
+---
+
+### 2. pre-commit Hook（Collaboration 系統鎖定檢查）
+
+**觸發時機**：`git commit` 執行前自動檢查
+
+**功能**：
+- ✅ **任務鎖定衝突檢測**：防止提交被其他用戶鎖定的任務
+- ✅ **自動化衝突防護**：檢查 `.collaboration/tasks/db/all/TASK_*.json` 文件
+- ✅ **友善錯誤提示**：顯示被鎖定的任務及鎖定者資訊
+- ✅ **Fail-Safe 設計**：錯誤時允許提交（避免阻擋正常工作流程）
+
+**檔案位置**：
+```
+.githooks/pre-commit         # Bash wrapper（自動生成）
+.collaboration/hooks/pre-commit.js  # Node.js 實作（核心邏輯）
+```
+
+**關鍵邏輯**（Node.js 版本）：
+```javascript
+// 取得要提交的任務文件
+function getStagedTaskFiles() {
+  const output = execSync('git diff --cached --name-only', {
+    cwd: PROJECT_ROOT,
+    encoding: 'utf8'
+  });
+
+  const stagedFiles = output.split('\n').filter(Boolean);
+
+  // 篩選出任務文件
+  const taskFiles = stagedFiles.filter(file =>
+    file.startsWith('.collaboration/tasks/db/all/TASK_') &&
+    file.endsWith('.json')
+  );
+
+  return taskFiles;
+}
+
+// 檢查任務鎖定衝突
+async function checkLockConflicts(taskFiles, currentUser) {
+  const { LockManager } = require(LOCK_MANAGER_PATH);
+  const lockMgr = new LockManager();
+
+  for (const filePath of taskFiles) {
+    const taskId = extractTaskId(filePath);
+    const locks = await lockMgr.getActiveLocks(taskId);
+    const otherUserLocks = locks.filter(lock => !lock.locked_by.includes(currentUser));
+
+    if (otherUserLocks.length > 0) {
+      conflicts.push({ taskId, filePath, locks: otherUserLocks });
+    }
+  }
+
+  return conflicts;
+}
+```
+
+**配置方式**（`.collaboration/hooks/config.json`）：
+```json
+{
+  "hooks": {
+    "pre-commit": { "enabled": true },
+    "post-merge": { "enabled": true }
+  }
+}
+```
+
+**工作流程**：
+```
+Git Commit 開始
+    ↓
+pre-commit Hook 觸發
+    ↓
+取得 Staged 任務文件（TASK_*.json）
+    ↓
+沒有任務文件 → 允許提交
+    ↓
+檢查任務鎖定狀態（LockManager）
+    ↓
+發現衝突 → 拒絕提交 + 顯示鎖定者資訊
+    ↓
+無衝突 → 允許提交
+```
+
+**錯誤提示範例**：
+```
+========================================
+❌ Commit 被拒絕: 發現任務鎖定衝突
+========================================
+以下任務已被其他用戶鎖定，無法提交:
+
+  TASK_208:
+    - 被 {git_user} 鎖定
+    - 鎖定時間: 2026-02-19T02:30:00.000Z
+    - 過期時間: 2026-02-19T03:30:00.000Z
+
+請先釋放鎖定或等待鎖定過期後再提交。
+```
+
+---
+
+### 3. post-merge Hook（索引重建）
+
+**觸發時機**：`git merge` 或 `git pull` 完成後自動執行
+
+**功能**：
+- ✅ **自動重建 JSONL 索引**：確保合併後的任務索引保持同步
+- ✅ **變更檢測**：只在任務文件變更時重建索引
+- ✅ **日誌記錄**：完整執行日誌存放在 `.collaboration/hooks/logs/post-merge.log`
+
+**檔案位置**：
+```
+.githooks/post-merge         # Bash wrapper（自動生成）
+.collaboration/hooks/post-merge.js  # Node.js 實作（核心邏輯）
+```
+
+**關鍵邏輯**（Node.js 版本）：
+```javascript
+// 取得已變更的任務文件
+function getChangedTaskFiles() {
+  const output = execSync('git diff --name-only HEAD@{1} HEAD', {
+    cwd: CONFIG.projectRoot,
+    encoding: 'utf8'
+  });
+
+  const changedFiles = output.split('\n').filter(Boolean);
+
+  // 篩選出任務文件
+  const taskFiles = changedFiles.filter(file =>
+    file.startsWith('.collaboration/tasks/db/all/TASK_') &&
+    file.endsWith('.json')
+  );
+
+  return taskFiles;
+}
+
+// 重建索引
+function rebuildIndex() {
+  const indexManager = path.join(__dirname, '../core/index-manager.js');
+  execSync(`node "${indexManager}" rebuild`, {
+    cwd: CONFIG.projectRoot,
+    encoding: 'utf8',
+    stdio: 'inherit'
+  });
+}
+```
+
+**配置方式**：
+```javascript
+// 環境變數可以覆蓋配置
+if (process.env.COLLAB_HOOKS_DISABLED === 'true') {
+  return false;
+}
+```
+
+**工作流程**：
+```
+Git Merge/Pull 完成
+    ↓
+post-merge Hook 觸發
+    ↓
+檢查環境變數（COLLAB_HOOKS_DISABLED）
+    ↓
+取得變更的任務文件（TASK_*.json）
+    ↓
+沒有變更 → 跳過索引重建
+    ↓
+有變更 → 調用 index-manager.js rebuild
+    ↓
+索引重建完成 → Hook 完成
+```
+
+---
+
+## 雙平台支援
+
+### Bash 版本（Linux / Mac / Git Bash on Windows）
+
+**適用場景**：
+- ✅ Linux / macOS 原生支援
+- ✅ Windows 使用 Git Bash（推薦）
+- ✅ 功能完整（post-commit, pre-commit, post-merge）
+
+**安裝方式**：
+```bash
+# 方式一：Git 配置（推薦）
+git config core.hooksPath .githooks
+
+# 方式二：符號連結（Linux/Mac）
+ln -sf ../../.githooks/post-commit .git/hooks/post-commit
+ln -sf ../../.githooks/pre-commit .git/hooks/pre-commit
+ln -sf ../../.githooks/post-merge .git/hooks/post-merge
+```
+
+**檔案格式**：
+```bash
+#!/bin/bash
+#
+# Kenaz Cortex - Git Post-Commit Hook
+#
+# 在每次 commit 後自動觸發 RAG 增量索引更新。
+# 支援非同步執行，不阻塞 commit 流程。
+#
+# 安裝方式：
+#   git config core.hooksPath .githooks
+
+# 取得專案根目錄
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# 配置
+CORTEX_SYNC_TIMEOUT=30  # 同步超時秒數
+
+# 顏色輸出
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# ... Hook 邏輯 ...
+```
+
+### PowerShell 版本（Windows）
+
+**適用場景**：
+- ✅ Windows 原生 PowerShell 環境
+- ⚠️ 功能有限（主要支援 post-commit）
+- ⚠️ 需額外配置 Git 使用 PowerShell
+
+**安裝方式**：
+```powershell
+# 執行安裝腳本
+.\dev\scripts\setup_git_hooks.ps1
+```
+
+**檔案格式**：
+```powershell
+# Kenaz Cortex - Git Post-Commit Hook (PowerShell)
+#
+# 在每次 commit 後自動觸發 RAG 增量索引更新。
+# 支援非同步執行，不阻塞 commit 流程。
+#
+# 安裝方式：
+#   .\dev\scripts\hooks\Install-GitHooks.ps1
+#
+# 注意：Windows 上使用此腳本需要將 Git 配置為使用 PowerShell。
+#       建議使用 Bash 版本的 hook（需安裝 Git Bash）。
+
+param(
+    [switch]$Sync,        # 同步模式（等待完成）
+    [int]$Timeout = 30    # 超時秒數
+)
+
+# 配置
+$ErrorActionPreference = "SilentlyContinue"
+$ProjectRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
+
+# ... Hook 邏輯 ...
+```
+
+**平台選擇建議**：
+| 平台 | 推薦方案 | 原因 |
+|------|---------|------|
+| **Linux / macOS** | Bash 版本 | 原生支援 |
+| **Windows** | Git Bash（Bash 版本） | 功能完整、跨平台一致 |
+| **Windows（無 Git Bash）** | PowerShell 版本 | 備用方案 |
+
+---
+
+## 安裝與配置
+
+### 安裝方式
+
+#### 方式一：Git 配置（推薦，所有平台）
+
+**優點**：
+- ✅ 集中管理（`.githooks/` 目錄）
+- ✅ 易於版本控制
+- ✅ 團隊成員共享相同配置
+
+**步驟**：
+```bash
+# 配置 Git 使用 .githooks/ 目錄
+git config core.hooksPath .githooks
+
+# 驗證配置
+git config --get core.hooksPath
+# 輸出：.githooks
+```
+
+#### 方式二：Collaboration Hooks 安裝工具（推薦，Node.js 環境）
+
+**優點**：
+- ✅ 自動化安裝流程
+- ✅ 支援啟用/停用特定 Hooks
+- ✅ 配置管理工具
+- ✅ 狀態檢查功能
+
+**步驟**：
+```bash
+# 安裝所有 hooks
+node .collaboration/hooks/install.js install
+
+# 檢查狀態
+node .collaboration/hooks/install.js status
+
+# 啟用/停用特定 hook
+node .collaboration/hooks/install.js disable pre-commit
+node .collaboration/hooks/install.js enable pre-commit
+
+# 卸載 hooks
+node .collaboration/hooks/install.js uninstall
+```
+
+**輸出範例**：
+```
+開始安裝 Git Hooks...
+
+✅ 安裝 post-merge hook 成功
+   源文件: D:\repo\side\ava\KenazAI\.collaboration\hooks\post-merge.js
+   目標位置: D:\repo\side\ava\KenazAI\.git\hooks\post-merge
+
+✅ 安裝 pre-commit hook 成功
+   源文件: D:\repo\side\ava\KenazAI\.collaboration\hooks\pre-commit.js
+   目標位置: D:\repo\side\ava\KenazAI\.git\hooks\pre-commit
+
+========================================
+安裝完成: 2/2 個 hooks
+========================================
+
+當前配置:
+  post-merge: ✅ 啟用
+  pre-commit: ✅ 啟用
+```
+
+#### 方式三：PowerShell 自動安裝（Windows 限定）
+
+**適用場景**：Windows PowerShell 環境，使用舊 Pipeline 系統
+
+**步驟**：
+```powershell
+# 執行安裝腳本
+.\dev\scripts\setup_git_hooks.ps1
+```
+
+**功能**：
+- 建立 `pre-commit` hook（Pipeline 驗證）
+- 建立 `commit-msg` hook（Commit Message 格式驗證）
+- 自動測試 PowerShell 版本
+
+#### 方式四：手動符號連結（Linux/Mac）
+
+**步驟**：
+```bash
+# 建立符號連結
+ln -sf ../../.githooks/post-commit .git/hooks/post-commit
+ln -sf ../../.githooks/pre-commit .git/hooks/pre-commit
+ln -sf ../../.githooks/post-merge .git/hooks/post-merge
+
+# 驗證連結
+ls -la .git/hooks/
+```
+
+---
+
+### 配置文件
+
+#### `.cortex.yaml`（Cortex RAG Hooks）
+
+**位置**：專案根目錄 `.cortex.yaml`
+
+**配置範例**：
+```yaml
+cortex:
+  enabled: true
+
+  # Git Hooks 設定
+  git_hooks:
+    enabled: true
+    post_commit:
+      incremental_sync: true
+      async_mode: true         # 非同步執行（背景執行）
+      timeout: 30              # 超時秒數（同步模式下使用）
+```
+
+**配置項說明**：
+| 配置項 | 類型 | 預設值 | 說明 |
+|--------|------|--------|------|
+| `enabled` | boolean | `true` | 是否啟用 Git Hooks |
+| `incremental_sync` | boolean | `true` | 是否使用增量同步（只同步變更） |
+| `async_mode` | boolean | `true` | 是否非同步執行（背景運行） |
+| `timeout` | number | `30` | 同步模式下的超時秒數 |
+
+#### `.collaboration/hooks/config.json`（Collaboration Hooks）
+
+**位置**：`.collaboration/hooks/config.json`
+
+**配置範例**：
+```json
+{
+  "hooks": {
+    "post-merge": { "enabled": true },
+    "pre-commit": { "enabled": true }
+  }
+}
+```
+
+**管理方式**：
+```bash
+# 停用 pre-commit hook
+node .collaboration/hooks/install.js disable pre-commit
+
+# 重新啟用
+node .collaboration/hooks/install.js enable pre-commit
+```
+
+---
+
+### 停用 Hooks
+
+#### 臨時跳過 Hooks（單次 Commit）
+
+```bash
+# 使用 --no-verify 標誌跳過所有 hooks
+git commit --no-verify -m "message"
+```
+
+#### 永久停用特定 Hook
+
+**方式一：修改配置文件**
+
+```yaml
+# .cortex.yaml
+git_hooks:
+  enabled: false  # 停用所有 Cortex Hooks
+```
+
+```json
+// .collaboration/hooks/config.json
+{
+  "hooks": {
+    "pre-commit": { "enabled": false }  // 停用 pre-commit hook
+  }
+}
+```
+
+**方式二：使用配置工具**
+
+```bash
+# Collaboration Hooks
+node .collaboration/hooks/install.js disable pre-commit
+
+# 環境變數（post-merge）
+export COLLAB_HOOKS_DISABLED=true
+```
+
+**方式三：刪除 Hook 文件**
+
+```bash
+# 刪除特定 hook
+rm .git/hooks/pre-commit
+
+# 或使用卸載工具
+node .collaboration/hooks/install.js uninstall
+```
+
+---
+
+## 日誌與除錯
+
+### 日誌位置
+
+| Hook | 日誌位置 | 格式 |
+|------|---------|------|
+| **post-commit** | 標準輸出（無持久化） | 彩色終端輸出 |
+| **pre-commit** | `.collaboration/hooks/logs/pre-commit.log` | Timestamped JSON |
+| **post-merge** | `.collaboration/hooks/logs/post-merge.log` | Timestamped JSON |
+
+### 查看日誌
+
+```bash
+# pre-commit 日誌
+tail -f .collaboration/hooks/logs/pre-commit.log
+
+# post-merge 日誌
+tail -f .collaboration/hooks/logs/post-merge.log
+
+# 篩選特定任務
+grep "TASK_208" .collaboration/hooks/logs/pre-commit.log
+```
+
+### 日誌格式範例
+
+```
+[2026-02-19T02:45:30.123Z] [INFO] ========== pre-commit hook 開始執行 ==========
+[2026-02-19T02:45:30.124Z] [INFO] 專案根目錄: D:\repo\side\ava\KenazAI
+[2026-02-19T02:45:30.125Z] [INFO] 當前用戶: {git_user}
+[2026-02-19T02:45:30.130Z] [INFO] 發現 1 個任務文件要提交:
+[2026-02-19T02:45:30.131Z] [INFO]   - .collaboration/tasks/db/all/TASK_208_{git_user}.json
+[2026-02-19T02:45:30.132Z] [INFO] 檢查鎖定衝突...
+[2026-02-19T02:45:30.150Z] [INFO] ✅ 沒有鎖定衝突，允許提交
+[2026-02-19T02:45:30.151Z] [INFO] ========== pre-commit hook 執行完成 (0.03s) ==========
+```
+
+### 除錯模式
+
+```bash
+# 手動執行 hook（除錯用）
+bash .githooks/post-commit
+
+# Node.js hooks
+node .collaboration/hooks/pre-commit.js
+
+# PowerShell hooks
+powershell -ExecutionPolicy Bypass -File .githooks/post-commit.ps1
+```
+
+---
+
+## 常見問題（FAQ）
+
+### Q1: Hooks 為什麼沒有執行？
+
+**A**: 檢查以下項目：
+1. **Git 配置**：`git config --get core.hooksPath` 應輸出 `.githooks`
+2. **執行權限**：`chmod +x .githooks/post-commit`（Linux/Mac）
+3. **配置啟用**：檢查 `.cortex.yaml` 或 `.collaboration/hooks/config.json`
+4. **CI 環境**：CI 環境下 post-commit 會自動跳過
+
+### Q2: pre-commit 錯誤時如何強制提交？
+
+**A**: 使用 `--no-verify` 標誌：
+```bash
+git commit --no-verify -m "message"
+```
+
+**注意**：不建議經常跳過，可能導致鎖定衝突被提交。
+
+### Q3: post-commit 會阻塞 commit 流程嗎？
+
+**A**: 不會。post-commit 使用 Lazy Sync 策略：
+- Hook 只輸出提示訊息，立即返回
+- MCP Server 在下次工具呼叫時自動同步
+- 不啟動額外的 Python 進程
+
+### Q4: Windows 用戶應該使用哪個版本？
+
+**A**: 推薦使用 **Git Bash（Bash 版本）**：
+- 功能完整
+- 跨平台一致
+- 與 Linux/Mac 開發者共享相同配置
+
+PowerShell 版本僅作為備用方案。
+
+### Q5: 如何驗證 Hooks 是否正確安裝？
+
+**A**:
+```bash
+# 方法一：檢查 Git 配置
+git config --get core.hooksPath
+
+# 方法二：使用 Collaboration 工具
+node .collaboration/hooks/install.js status
+
+# 方法三：檢查檔案存在
+ls -la .git/hooks/
+```
+
+### Q6: Hooks 可以在 CI 環境中使用嗎？
+
+**A**: post-commit 會自動跳過 CI 環境（檢測 `CI` 或 `GITHUB_ACTIONS` 環境變數）。其他 hooks 可在 CI 中使用，但需確保環境有 Node.js。
+
+### Q7: 如何更新 Hooks 版本？
+
+**A**:
+```bash
+# Git 配置方式（自動使用最新版本）
+git pull origin main
+
+# Collaboration 安裝方式（重新安裝）
+node .collaboration/hooks/install.js uninstall
+node .collaboration/hooks/install.js install
+```
+
+---
+
+## 相關文檔
+
+### Cortex RAG 系統
+
+| 文檔 | 路徑 | 說明 |
+|------|------|------|
+| **Cortex 配置** | `.cortex.yaml` | RAG 引擎配置（Git Hooks 設定） |
+| **Cortex 整合指南** | `.memory/CORTEX_GUIDE.md` | Cortex 系統整合指南 |
+| **Cortex API 文檔** | `kenaz-cortex/docs/API_REFERENCE.md` | MCP 工具 API 參考 |
+
+### Collaboration 系統
+
+| 文檔 | 路徑 | 說明 |
+|------|------|------|
+| **Collaboration README** | `.collaboration/README.md` | Collaboration 系統完整說明 |
+| **Collaboration Hooks** | `.collaboration/hooks/README.md` | Hooks 安裝與管理工具 |
+| **Task API 文檔** | `.collaboration/core/task-api.js` | 任務 API 參考 |
+| **Lock Manager** | `.collaboration/core/lock-manager.js` | 任務鎖定機制 |
+
+### Pipeline 系統（Legacy）
+
+| 文檔 | 路徑 | 說明 |
+|------|------|------|
+| **Pipeline README** | `.system/pipeline/README.md` | Pipeline 系統說明 |
+| **Setup Git Hooks** | `dev/scripts/setup_git_hooks.ps1` | PowerShell 安裝腳本 |
+
+### 規則系統
+
+| 文檔 | 路徑 | 說明 |
+|------|------|------|
+| **規則索引** | `.rule/INDEX.yaml` | 規則系統索引 |
+| **Agent 工作流程** | `.rule/general/agent-workflow.yaml` | Agent 通用規則 |
+
+---
+
+## 技術架構
+
+### Hook 執行流程（完整）
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Git Operation                            │
+│           (commit / merge / pull)                            │
+└─────────────────┬───────────────────────────────────────────┘
+                  ↓
+      ┌───────────┴───────────┐
+      │   Bash Wrapper        │  (.git/hooks/post-commit)
+      │   or                  │
+      │   Git hooksPath       │  (.githooks/ 目錄)
+      └───────────┬───────────┘
+                  ↓
+      ┌───────────┴───────────┐
+      │   Hook Script         │
+      │   (Bash/PowerShell)   │
+      └───────────┬───────────┘
+                  ↓
+      ┌───────────┴───────────┐
+      │   Environment Check   │
+      │   - CI Detection      │
+      │   - Config Validation │
+      └───────────┬───────────┘
+                  ↓
+      ┌───────────┴───────────┐
+      │   Core Logic          │
+      │   - post-commit       │  → Lazy Sync 提示
+      │   - pre-commit        │  → Node.js Lock Check
+      │   - post-merge        │  → Node.js Index Rebuild
+      └───────────┬───────────┘
+                  ↓
+      ┌───────────┴───────────┐
+      │   Log & Exit          │
+      │   - Success (0)       │
+      │   - Failure (1)       │
+      └───────────────────────┘
+```
+
+### 三種 Hook 架構對比
+
+| Hook | 實作語言 | 核心邏輯位置 | 執行模式 | 阻塞性 |
+|------|---------|-------------|---------|--------|
+| **post-commit** | Bash/PowerShell | `.githooks/post-commit` | 同步提示 → MCP Lazy Sync | 非阻塞 |
+| **pre-commit** | Bash Wrapper → Node.js | `.collaboration/hooks/pre-commit.js` | 同步檢查 | 阻塞（衝突時） |
+| **post-merge** | Bash Wrapper → Node.js | `.collaboration/hooks/post-merge.js` | 同步重建索引 | 阻塞 |
+
+---
+
+## 最佳實踐
+
+### 開發團隊協作
+
+1. **統一使用 Git Bash**：
+   - Windows 用戶安裝 Git for Windows（包含 Git Bash）
+   - 配置使用 `.githooks/` 目錄（`git config core.hooksPath .githooks`）
+   - 避免平台差異
+
+2. **定期檢查 Hooks 狀態**：
+   ```bash
+   node .collaboration/hooks/install.js status
+   ```
+
+3. **Commit 前驗證**：
+   - 確保沒有其他用戶鎖定相同任務
+   - 使用 `.collaboration/core/lock-manager.js` 查詢鎖定狀態
+
+4. **日誌監控**：
+   - 定期查看 `.collaboration/hooks/logs/` 目錄
+   - 發現異常時檢查錯誤日誌
+
+### CI/CD 整合
+
+1. **跳過 post-commit**：
+   - CI 環境自動跳過（檢測 `CI` 環境變數）
+   - 無需額外配置
+
+2. **啟用 pre-commit（可選）**：
+   ```yaml
+   # .github/workflows/ci.yml
+   - name: Install Node.js
+     uses: actions/setup-node@v3
+     with:
+       node-version: '18'
+
+   - name: Run pre-commit checks
+     run: |
+       git config core.hooksPath .githooks
+       # Git commit 會自動觸發 hooks
+   ```
+
+3. **禁用 Hooks**：
+   ```yaml
+   # CI 環境禁用所有 hooks
+   - name: Disable hooks
+     run: git config core.hooksPath /dev/null
+   ```
+
+### 效能優化
+
+1. **Lazy Sync 策略**：
+   - post-commit 不直接同步資料庫
+   - MCP Server 在工具呼叫時自動同步
+   - 避免多進程 ChromaDB 連線衝突
+
+2. **增量索引**：
+   - 只索引變更的檔案
+   - 使用 Git diff 檢測變更範圍
+
+3. **非同步執行**：
+   - post-commit 背景運行
+   - 不阻塞 commit 流程
+
+---
+
+*建立日期: 2026-02-19 | 版本: 1.0.0*