@vibe-x/agent-better-checkpoint 0.3.3 → 0.3.4

package/bin/cli.mjs

@@ -38,7 +38,7 @@ const CONFIG_TEMPLATE = join(PLATFORM_DIR, 'config.template.yml');
 // ============================================================
 
 function parseArgs(argv) {
-  const args = { platform: null, uninstall: false, target: null };
+  const args = { platform: null, uninstall: false, target: null, activate: false };
   for (let i = 2; i < argv.length; i++) {
     switch (argv[i]) {
       case '--platform':
@@ -58,6 +58,9 @@ function parseArgs(argv) {
       case '--uninstall':
         args.uninstall = true;
         break;
+      case '--activate':
+        args.activate = true;
+        break;
       case '--help':
       case '-h':
         printHelp();
@@ -82,6 +85,7 @@ Usage:
 Options:
   --platform <cursor|claude>  Target AI platform (auto-detected if omitted)
   --target <path>             Project-only install (no global). Use . for cwd
+  --activate                  Activate checkpoint rules in current project (AGENTS.md only)
   --uninstall                 Remove installed files and hook registrations
   -h, --help                  Show this help message
 `);
@@ -229,11 +233,14 @@ function installScripts(osType) {
 
   // 双端脚本都安装，方便跨平台使用
   copyFileSafe(join(PLATFORM_DIR, 'unix', 'checkpoint.sh'), join(scriptsDir, 'checkpoint.sh'));
+  copyFileSafe(join(PLATFORM_DIR, 'unix', 'alloc_patch.sh'), join(scriptsDir, 'alloc_patch.sh'));
   copyFileSafe(join(PLATFORM_DIR, 'unix', 'check_uncommitted.sh'), join(hooksDir, 'check_uncommitted.sh'));
   setExecutable(join(scriptsDir, 'checkpoint.sh'));
+  setExecutable(join(scriptsDir, 'alloc_patch.sh'));
   setExecutable(join(hooksDir, 'check_uncommitted.sh'));
 
   copyFileSafe(join(PLATFORM_DIR, 'win', 'checkpoint.ps1'), join(scriptsDir, 'checkpoint.ps1'));
+  copyFileSafe(join(PLATFORM_DIR, 'win', 'alloc_patch.ps1'), join(scriptsDir, 'alloc_patch.ps1'));
   copyFileSafe(join(PLATFORM_DIR, 'win', 'check_uncommitted.ps1'), join(hooksDir, 'check_uncommitted.ps1'));
 
   console.log(`  Scripts → ${scriptsDir}/`);
@@ -301,12 +308,18 @@ function registerCursorHook(osType) {
 function installProjectOnly(targetDir, aiPlatform, osType) {
   const root = resolve(targetDir);
 
-  // .vibe-x/agent-better-checkpoint: checkpoint 脚本 + config
+  // .vibe-x/agent-better-checkpoint: checkpoint 脚本 + helper + config
   const vibeXBase = join(root, '.vibe-x', 'agent-better-checkpoint');
   ensureDir(vibeXBase);
   copyFileSafe(join(PLATFORM_DIR, 'unix', 'checkpoint.sh'), join(vibeXBase, 'checkpoint.sh'));
+  copyFileSafe(join(PLATFORM_DIR, 'unix', 'alloc_patch.sh'), join(vibeXBase, 'alloc_patch.sh'));
+  copyFileSafe(join(PLATFORM_DIR, 'unix', 'check_uncommitted.sh'), join(vibeXBase, 'check_uncommitted.sh'));
   copyFileSafe(join(PLATFORM_DIR, 'win', 'checkpoint.ps1'), join(vibeXBase, 'checkpoint.ps1'));
+  copyFileSafe(join(PLATFORM_DIR, 'win', 'alloc_patch.ps1'), join(vibeXBase, 'alloc_patch.ps1'));
+  copyFileSafe(join(PLATFORM_DIR, 'win', 'check_uncommitted.ps1'), join(vibeXBase, 'check_uncommitted.ps1'));
   setExecutable(join(vibeXBase, 'checkpoint.sh'));
+  setExecutable(join(vibeXBase, 'alloc_patch.sh'));
+  setExecutable(join(vibeXBase, 'check_uncommitted.sh'));
   const configDest = join(vibeXBase, 'config.yml');
   if (!existsSync(configDest) && existsSync(CONFIG_TEMPLATE)) {
     copyFileSafe(CONFIG_TEMPLATE, configDest);
@@ -356,9 +369,22 @@ function uninstallProjectOnly(targetDir, aiPlatform) {
   const vibeXBase = join(root, '.vibe-x', 'agent-better-checkpoint');
   const skillRoot = aiPlatform === 'cursor' ? '.cursor' : '.claude';
   const skillDir = join(root, skillRoot, 'skills', SKILL_NAME);
-  if (existsSync(vibeXBase)) {
-    rmSync(vibeXBase, { recursive: true, force: true });
-    console.log(`  Removed ${vibeXBase}`);
+  const checkpointShPath = join(vibeXBase, 'checkpoint.sh');
+  const checkpointPs1Path = join(vibeXBase, 'checkpoint.ps1');
+  const allocPatchShPath = join(vibeXBase, 'alloc_patch.sh');
+  const allocPatchPs1Path = join(vibeXBase, 'alloc_patch.ps1');
+  const checkUncommittedShPath = join(vibeXBase, 'check_uncommitted.sh');
+  const checkUncommittedPs1Path = join(vibeXBase, 'check_uncommitted.ps1');
+  for (const filePath of [
+    checkpointShPath,
+    checkpointPs1Path,
+    allocPatchShPath,
+    allocPatchPs1Path,
+    checkUncommittedShPath,
+    checkUncommittedPs1Path,
+    join(vibeXBase, 'config.yml'),
+  ]) {
+    if (existsSync(filePath)) rmSync(filePath, { force: true });
   }
 
   if (existsSync(skillDir)) {
@@ -503,6 +529,123 @@ function unregisterClaudeHook() {
   console.log(`  Cleaned config: ${settingsPath}`);
 }
 
+// ============================================================
+// Activate logic (AGENTS.md only, with installation check)
+// ============================================================
+
+const SUPPORTED_PLATFORMS = ['cursor', 'claude'];
+
+function checkGlobalInstallation() {
+  const home = homedir();
+  const results = {
+    hasScripts: existsSync(join(INSTALL_BASE, 'scripts', 'checkpoint.sh')) ||
+                existsSync(join(INSTALL_BASE, 'scripts', 'checkpoint.ps1')),
+    platforms: {}
+  };
+  
+  for (const p of SUPPORTED_PLATFORMS) {
+    const skillDir = p === 'cursor' ? '.cursor' : '.claude';
+    results.platforms[p] = {
+      hasSkill: existsSync(join(home, skillDir, 'skills', SKILL_NAME, 'SKILL.md'))
+    };
+  }
+  
+  results.hasAnySkill = SUPPORTED_PLATFORMS.some(p => results.platforms[p].hasSkill);
+  results.isFullyInstalled = results.hasScripts && results.hasAnySkill;
+  return results;
+}
+
+function checkProjectInstallation(targetDir) {
+  const root = resolve(targetDir);
+  const results = {
+    hasScripts: existsSync(join(root, '.vibe-x', 'agent-better-checkpoint', 'checkpoint.sh')) ||
+                existsSync(join(root, '.vibe-x', 'agent-better-checkpoint', 'checkpoint.ps1')),
+    platforms: {}
+  };
+  
+  for (const p of SUPPORTED_PLATFORMS) {
+    const skillDir = p === 'cursor' ? '.cursor' : '.claude';
+    results.platforms[p] = {
+      hasSkill: existsSync(join(root, skillDir, 'skills', SKILL_NAME, 'SKILL.md'))
+    };
+  }
+  
+  results.hasAnySkill = SUPPORTED_PLATFORMS.some(p => results.platforms[p].hasSkill);
+  results.isFullyInstalled = results.hasScripts && results.hasAnySkill;
+  return results;
+}
+
+function activateProject(targetDir) {
+  const root = resolve(targetDir);
+  
+  // Check if already has AGENTS.md block
+  const agentsMdPath = join(root, 'AGENTS.md');
+  if (existsSync(agentsMdPath)) {
+    const content = readFileSync(agentsMdPath, 'utf-8');
+    if (content.includes(AGENTS_BLOCK_START)) {
+      console.log(`\n⚠️  AGENTS.md already contains checkpoint rules. Nothing to do.`);
+      return;
+    }
+  }
+
+  // Step 1: Check project-level installation (all platforms)
+  const projectStatus = checkProjectInstallation(root);
+  if (projectStatus.isFullyInstalled) {
+    // Project has both scripts and skill for at least one platform
+    console.log(`\n[Activate] Adding checkpoint rules to ${root}...`);
+    injectAgentsMdBlock(root);
+    console.log(`\n✅ Activation complete!`);
+    console.log(`\nThe AI agent will now follow checkpoint commit rules in this project.`);
+    return;
+  }
+
+  // Step 2: Check global installation (all platforms)
+  const globalStatus = checkGlobalInstallation();
+  if (globalStatus.isFullyInstalled) {
+    // Global has both scripts and skill for at least one platform
+    console.log(`\n[Activate] Adding checkpoint rules to ${root}...`);
+    injectAgentsMdBlock(root);
+    console.log(`\n✅ Activation complete!`);
+    console.log(`\nThe AI agent will now follow checkpoint commit rules in this project.`);
+    return;
+  }
+
+  // Step 3: Neither project nor global is fully installed - provide detailed diagnosis
+  const hasAnyProjectSkill = projectStatus.hasAnySkill;
+  const hasAnyGlobalSkill = globalStatus.hasAnySkill;
+  const hasAnyProjectScripts = projectStatus.hasScripts;
+  const hasAnyGlobalScripts = globalStatus.hasScripts;
+
+  const hasAnySkill = hasAnyProjectSkill || hasAnyGlobalSkill;
+  const hasAnyScripts = hasAnyProjectScripts || hasAnyGlobalScripts;
+
+  if (!hasAnySkill && !hasAnyScripts) {
+    console.log(`\n⚠️  No agent-better-checkpoint installation detected.`);
+    console.log(`\nChecked locations:`);
+    console.log(`  Project: ${root}`);
+    console.log(`  Global:  ${INSTALL_BASE}`);
+    console.log(`\nPlease install first:`);
+    console.log(`  Global:        npx @vibe-x/agent-better-checkpoint`);
+    console.log(`  Project-only:  npx @vibe-x/agent-better-checkpoint --target . --platform cursor|claude`);
+    console.log(`\nThen run --activate again.`);
+    process.exit(1);
+  }
+
+  if (!hasAnySkill) {
+    console.log(`\n⚠️  Checkpoint scripts found, but skill (SKILL.md) is missing.`);
+    console.log(`\nThe AI agent needs the skill to know how to commit. Please run:`);
+    console.log(`  npx @vibe-x/agent-better-checkpoint --platform cursor|claude`);
+    process.exit(1);
+  }
+
+  if (!hasAnyScripts) {
+    console.log(`\n⚠️  Skill found, but checkpoint scripts are missing.`);
+    console.log(`\nPlease reinstall to get the scripts:`);
+    console.log(`  npx @vibe-x/agent-better-checkpoint`);
+    process.exit(1);
+  }
+}
+
 // ============================================================
 // Main entry
 // ============================================================
@@ -513,7 +656,7 @@ function main() {
   const aiPlatform = args.platform || detectAIPlatform();
   const projectTargetDir = args.target ? resolve(args.target) : null;
 
-  if (!aiPlatform && !projectTargetDir && !args.uninstall) {
+  if (!aiPlatform && !projectTargetDir && !args.uninstall && !args.activate) {
     console.error(
       'Error: could not detect AI platform.\n' +
       'Please specify: npx @vibe-x/agent-better-checkpoint --platform cursor|claude'
@@ -556,6 +699,10 @@ function main() {
       if (platforms.length === 0) console.log('\nNo global installation found.');
     }
     console.log('\n✅ Uninstallation complete!');
+  } else if (args.activate) {
+    // Activate: only inject AGENTS.md, check installation first
+    const targetDir = projectTargetDir || process.cwd();
+    activateProject(targetDir);
   } else {
     if (projectTargetDir) {
       if (!aiPlatform) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-x/agent-better-checkpoint",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Semantic Git checkpoint commits for AI coding sessions",
   "type": "module",
   "bin": {
@@ -10,8 +10,14 @@
     "bin/",
     "platform/",
     "skill/",
-    "LICENSE"
+    "LICENSE",
+    "scripts/"
   ],
+  "scripts": {
+    "release:check": "node ./scripts/release-check.mjs",
+    "preversion": "npm run release:check",
+    "prepublishOnly": "npm run release:check"
+  },
   "keywords": [
     "ai",
     "agent",

package/platform/unix/alloc_patch.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+#
+# alloc_patch.sh — Allocate a temporary patch file for hunk-level checkpoint commits
+#
+# Creates a writable patch path under ~/.vibe-x/agent-better-checkpoint/tmp/
+# and returns a one-line JSON payload with id, createdAt, path, and ttlHours.
+#
+# Usage:
+#   alloc_patch.sh --workspace /path/to/repo
+#   alloc_patch.sh --help
+
+set -euo pipefail
+
+TTL_HOURS=48
+TMP_ROOT="${HOME}/.vibe-x/agent-better-checkpoint/tmp"
+WORKSPACE=""
+
+usage() {
+    cat <<'EOF'
+alloc_patch.sh — Allocate a temporary patch file for checkpoint hunks
+
+Usage:
+  alloc_patch.sh --workspace <path>
+  alloc_patch.sh --help
+
+Options:
+  --workspace <path>   Workspace root used to derive a stable temp namespace
+  --help               Show this help message
+EOF
+}
+
+error() {
+    local code="$1"
+    shift
+    echo "${code}: $*" >&2
+    exit 1
+}
+
+json_escape() {
+    local str="$1"
+    str="${str//\\/\\\\}"
+    str="${str//\"/\\\"}"
+    str="${str//$'\n'/\\n}"
+    str="${str//$'\r'/\\r}"
+    str="${str//$'\t'/\\t}"
+    printf '%s' "$str"
+}
+
+workspace_hash() {
+    local input="$1"
+    if command -v shasum >/dev/null 2>&1; then
+        printf '%s' "$input" | shasum -a 256 | awk '{print substr($1,1,8)}'
+    elif command -v sha256sum >/dev/null 2>&1; then
+        printf '%s' "$input" | sha256sum | awk '{print substr($1,1,8)}'
+    else
+        printf '%s' "$input" | cksum | awk '{print $1}'
+    fi
+}
+
+random_id() {
+    local id
+    id=$(LC_ALL=C tr -dc 'A-Z0-9' < /dev/urandom | head -c 10 || true)
+    if [[ -z "$id" ]]; then
+        id="$(date -u +%s)"
+    fi
+    printf '%s' "$id"
+}
+
+cleanup_expired() {
+    local root="$1"
+    [[ -d "$root" ]] || return 0
+
+    find "$root" -type f -name 'patch-*.patch' -mtime +1 -exec rm -f {} + 2>/dev/null || true
+    find "$root" -type d -empty -mindepth 1 -exec rmdir {} + 2>/dev/null || true
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --workspace)
+            WORKSPACE="${2:-}"
+            shift 2
+            ;;
+        --help|-h)
+            usage
+            exit 0
+            ;;
+        *)
+            error "ABC_TEMP_ALLOC_FAILED" "Unknown option: $1"
+            ;;
+    esac
+done
+
+if [[ -z "$WORKSPACE" ]]; then
+    error "ABC_TEMP_ALLOC_FAILED" "Missing required --workspace argument. Please provide the workspace root path."
+fi
+
+if ! mkdir -p "$TMP_ROOT" 2>/dev/null; then
+    error "ABC_TEMP_ALLOC_FAILED" "Failed to create the temp root at ${TMP_ROOT}. Please check directory permissions."
+fi
+
+cleanup_expired "$TMP_ROOT"
+
+WORKSPACE_HASH=$(workspace_hash "$WORKSPACE")
+WORKSPACE_DIR="${TMP_ROOT}/${WORKSPACE_HASH}"
+if ! mkdir -p "$WORKSPACE_DIR" 2>/dev/null; then
+    error "ABC_TEMP_ALLOC_FAILED" "Failed to create the workspace temp directory at ${WORKSPACE_DIR}. Please check directory permissions."
+fi
+
+STAMP=$(date -u +%Y%m%dT%H%M%SZ)
+CREATED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+ID=$(random_id)
+PATCH_PATH="${WORKSPACE_DIR}/patch-${STAMP}-${ID}.patch"
+
+if ! : > "$PATCH_PATH" 2>/dev/null; then
+    error "ABC_TEMP_ALLOC_FAILED" "Failed to create a temporary patch file at ${PATCH_PATH}. Please check directory permissions and available disk space."
+fi
+
+printf '{"ok":true,"id":"%s","createdAt":"%s","path":"%s","ttlHours":%s}\n' \
+    "$(json_escape "$ID")" \
+    "$(json_escape "$CREATED_AT")" \
+    "$(json_escape "$PATCH_PATH")" \
+    "$TTL_HOURS"

package/platform/unix/check_uncommitted.sh

@@ -427,7 +427,7 @@ build_and_output_reminder() {
     changes_indented=$(echo "$changes" | sed 's/^/  /')
 
     # Project-local script; fallback to global
-    local checkpoint_cmd_sh checkpoint_cmd_ps1
+    local checkpoint_cmd_sh checkpoint_cmd_ps1 alloc_patch_cmd_sh alloc_patch_cmd_ps1
     if [[ -f "${workspace}/.vibe-x/agent-better-checkpoint/checkpoint.sh" ]]; then
         checkpoint_cmd_sh=".vibe-x/agent-better-checkpoint/checkpoint.sh"
     else
@@ -438,6 +438,16 @@ build_and_output_reminder() {
     else
         checkpoint_cmd_ps1='\$env:USERPROFILE/.vibe-x/agent-better-checkpoint/scripts/checkpoint.ps1'
     fi
+    if [[ -f "${workspace}/.vibe-x/agent-better-checkpoint/alloc_patch.sh" ]]; then
+        alloc_patch_cmd_sh=".vibe-x/agent-better-checkpoint/alloc_patch.sh"
+    else
+        alloc_patch_cmd_sh="~/.vibe-x/agent-better-checkpoint/scripts/alloc_patch.sh"
+    fi
+    if [[ -f "${workspace}/.vibe-x/agent-better-checkpoint/alloc_patch.ps1" ]]; then
+        alloc_patch_cmd_ps1='.\\.vibe-x\\agent-better-checkpoint\\alloc_patch.ps1'
+    else
+        alloc_patch_cmd_ps1='\$env:USERPROFILE/.vibe-x/agent-better-checkpoint/scripts/alloc_patch.ps1'
+    fi
 
     local reminder
     reminder="## ⚠️ Uncommitted Changes Detected
@@ -449,17 +459,24 @@ There are uncommitted changes in the workspace. Please create a checkpoint commi
 ${changes_indented}
 \`\`\`
 
-**Action Required**: Run the checkpoint script to commit these changes:
+**Action Required**: Allocate a patch file, write only the selected hunks for this conversation, then run the checkpoint script.
 
 **macOS/Linux:**
 \`\`\`bash
-${checkpoint_cmd_sh} \"checkpoint(<scope>): <description>\" \"<user-prompt>\" --type fallback
+PATCH_JSON=\$(${alloc_patch_cmd_sh} --workspace \"${workspace}\")
+PATCH_PATH=\$(printf '%s' \"\$PATCH_JSON\" | python3 -c 'import sys,json; print(json.load(sys.stdin)["path"])')
+# Write only the selected hunks for this conversation to \"\$PATCH_PATH\" as a unified diff patch.
+${checkpoint_cmd_sh} \"checkpoint(<scope>): <description>\" \"<user-prompt>\" --type fallback --patch-file \"\$PATCH_PATH\"
 \`\`\`
 
 **Windows (PowerShell):**
 \`\`\`powershell
-powershell -File \"${checkpoint_cmd_ps1}\" \"checkpoint(<scope>): <description>\" \"<user-prompt>\" -Type fallback
-\`\`\`"
+\$patch = powershell -File \"${alloc_patch_cmd_ps1}\" -Workspace \"${workspace}\" | ConvertFrom-Json
+# Write only the selected hunks for this conversation to \$patch.path as a unified diff patch.
+powershell -File \"${checkpoint_cmd_ps1}\" \"checkpoint(<scope>): <description>\" \"<user-prompt>\" -Type fallback -PatchFile \$patch.path
+\`\`\`
+
+If the checkpoint script returns an \`ABC_PATCH_*\` error, do not fall back to a full commit automatically. Explain the conflict and ask the user how to proceed."
 
     output_block "$reminder" "$platform"
 }

package/platform/unix/checkpoint.sh

@@ -5,10 +5,10 @@
 # AI provides descriptive content (subject + body). This script:
 # 1. Truncates user-prompt (≤60 chars, head+tail)
 # 2. Appends metadata via git interpret-trailers
-# 3. Runs git add -A && git commit
+# 3. Runs git add -A && git commit, or applies a selected patch to the index first
 #
 # Usage:
-#   checkpoint.sh <message> [user-prompt] [--type auto|fallback]
+#   checkpoint.sh <message> [user-prompt] [--type auto|fallback] [--patch-file <path>]
 
 set -euo pipefail
 
@@ -18,6 +18,7 @@ set -euo pipefail
 MESSAGE="${1:-}"
 USER_PROMPT="${2:-}"
 CHECKPOINT_TYPE="auto"
+PATCH_FILE=""
 
 shift 2 2>/dev/null || true
 while [[ $# -gt 0 ]]; do
@@ -26,18 +27,44 @@ while [[ $# -gt 0 ]]; do
             CHECKPOINT_TYPE="${2:-auto}"
             shift 2
             ;;
+        --patch-file)
+            PATCH_FILE="${2:-}"
+            shift 2
+            ;;
+        --help|-h)
+            cat <<'EOF'
+checkpoint.sh — Create semantic Git checkpoint commits
+
+Usage:
+  checkpoint.sh <message> [user-prompt] [--type auto|fallback] [--patch-file <path>]
+
+Options:
+  --type <auto|fallback>  Checkpoint type metadata
+  --patch-file <path>     Apply only the selected patch hunks to the index before commit
+  --help                  Show this help message
+EOF
+            exit 0
+            ;;
         *)
-            shift
+            echo "Unknown option: $1" >&2
+            exit 1
             ;;
     esac
 done
 
 if [[ -z "$MESSAGE" ]]; then
     echo "Error: commit message is required" >&2
-    echo "Usage: checkpoint.sh <message> [user-prompt] [--type auto|fallback]" >&2
+    echo "Usage: checkpoint.sh <message> [user-prompt] [--type auto|fallback] [--patch-file <path>]" >&2
     exit 1
 fi
 
+fail_checkpoint() {
+    local code="$1"
+    shift
+    echo "${code}: $*" >&2
+    exit 1
+}
+
 # ============================================================
 # Platform detection
 # ============================================================
@@ -60,10 +87,23 @@ AGENT_PLATFORM=$(detect_platform)
 truncate_prompt() {
     local prompt="$1"
     local max_len=60
+
+    # Ensure UTF-8 character-based (not byte-based) string operations.
+    # Without this, ${#prompt} and ${prompt:0:n} count bytes in C locale,
+    # which breaks multi-byte characters (e.g., Chinese) mid-character.
+    local old_lc_all="${LC_ALL:-}"
+    export LC_ALL=en_US.UTF-8
+
     local len=${#prompt}
 
     if [[ $len -le $max_len ]]; then
         echo "$prompt"
+        # Restore LC_ALL
+        if [[ -n "$old_lc_all" ]]; then
+            export LC_ALL="$old_lc_all"
+        else
+            unset LC_ALL
+        fi
         return
     fi
 
@@ -71,6 +111,14 @@ truncate_prompt() {
     local tail_len=$(( max_len - 3 - head_len ))
     local head="${prompt:0:$head_len}"
     local tail="${prompt:$((len - tail_len)):$tail_len}"
+
+    # Restore LC_ALL
+    if [[ -n "$old_lc_all" ]]; then
+        export LC_ALL="$old_lc_all"
+    else
+        unset LC_ALL
+    fi
+
     echo "${head}...${tail}"
 }
 
@@ -98,15 +146,44 @@ has_changes() {
     return 1
 }
 
-if ! has_changes; then
-    echo "No changes to commit."
-    exit 0
-fi
+has_staged_changes() {
+    if ! git diff --cached --quiet 2>/dev/null; then
+        return 0
+    fi
+    return 1
+}
 
-# ============================================================
-# git add -A
-# ============================================================
-git add -A
+if [[ -z "$PATCH_FILE" ]]; then
+    if ! has_changes; then
+        echo "No changes to commit."
+        exit 0
+    fi
+
+    # ============================================================
+    # git add -A
+    # ============================================================
+    git add -A
+else
+    if [[ ! -f "$PATCH_FILE" ]]; then
+        fail_checkpoint "ABC_PATCH_FILE_MISSING" "Patch file not found at ${PATCH_FILE}. Please allocate and write the patch file before running checkpoint."
+    fi
+
+    if [[ ! -s "$PATCH_FILE" ]]; then
+        fail_checkpoint "ABC_PATCH_FILE_EMPTY" "Patch file at ${PATCH_FILE} is empty. Please write at least one selected hunk before running checkpoint."
+    fi
+
+    if ! git apply --cached --check "$PATCH_FILE" >/dev/null 2>&1; then
+        fail_checkpoint "ABC_PATCH_APPLY_FAILED" "Failed to apply the selected patch cleanly to the Git index. The target hunks may have drifted or overlap with other uncommitted edits."
+    fi
+
+    if ! git apply --cached "$PATCH_FILE" >/dev/null 2>&1; then
+        fail_checkpoint "ABC_PATCH_APPLY_FAILED" "Failed to apply the selected patch to the Git index after the dry run succeeded. Please verify the patch file and retry."
+    fi
+
+    if ! has_staged_changes; then
+        fail_checkpoint "ABC_PATCH_NO_STAGED_CHANGES" "The selected patch did not produce any staged changes. The target hunks may already be staged or no longer match the current repository state."
+    fi
+fi
 
 # ============================================================
 # Build trailers and commit
@@ -120,6 +197,15 @@ if [[ -n "$TRUNCATED_PROMPT" ]]; then
     TRAILER_ARGS+=(--trailer "User-Prompt: ${TRUNCATED_PROMPT}")
 fi
 
-echo "$MESSAGE" | git interpret-trailers "${TRAILER_ARGS[@]}" | git commit -F -
+if ! echo "$MESSAGE" | git interpret-trailers "${TRAILER_ARGS[@]}" | git commit -F -; then
+    if [[ -n "$PATCH_FILE" ]]; then
+        fail_checkpoint "ABC_PATCH_COMMIT_FAILED" "Git commit failed after staging the selected patch. Review the repository state and retry when ready."
+    fi
+    exit 1
+fi
+
+if [[ -n "$PATCH_FILE" ]]; then
+    rm -f "$PATCH_FILE"
+fi
 
 echo "Checkpoint committed successfully."

package/platform/win/alloc_patch.ps1

@@ -0,0 +1,142 @@
+<#
+.SYNOPSIS
+    alloc_patch.ps1 — Allocate a temporary patch file for hunk-level checkpoint commits
+
+.DESCRIPTION
+    Creates a writable patch path under ~/.vibe-x/agent-better-checkpoint/tmp/
+    and returns a one-line JSON payload with id, createdAt, path, and ttlHours.
+
+.PARAMETER Workspace
+    Workspace root used to derive a stable temp namespace. Required.
+
+.EXAMPLE
+    .\alloc_patch.ps1 -Workspace C:\repo
+#>
+
+param(
+    [string]$Workspace = "",
+    [switch]$Help
+)
+
+$ErrorActionPreference = "Stop"
+$TTL_HOURS = 48
+$TMP_ROOT = Join-Path $HOME ".vibe-x/agent-better-checkpoint/tmp"
+
+function Show-Usage {
+    @"
+alloc_patch.ps1 — Allocate a temporary patch file for checkpoint hunks
+
+Usage:
+  alloc_patch.ps1 -Workspace <path>
+  alloc_patch.ps1 -Help
+
+Options:
+  -Workspace <path>   Workspace root used to derive a stable temp namespace
+  -Help               Show this help message
+"@ | Write-Output
+}
+
+function Fail-Alloc {
+    param(
+        [string]$Code,
+        [string]$Message
+    )
+
+    [Console]::Error.WriteLine("${Code}: ${Message}")
+    exit 1
+}
+
+function Get-WorkspaceHash {
+    param([string]$InputText)
+
+    $sha = [System.Security.Cryptography.SHA256]::Create()
+    try {
+        $bytes = [System.Text.Encoding]::UTF8.GetBytes($InputText)
+        $hashBytes = $sha.ComputeHash($bytes)
+        $hex = -join ($hashBytes | ForEach-Object { $_.ToString("x2") })
+        return $hex.Substring(0, 8)
+    }
+    finally {
+        $sha.Dispose()
+    }
+}
+
+function Get-RandomId {
+    $bytes = New-Object byte[] 6
+    [System.Security.Cryptography.RandomNumberGenerator]::Fill($bytes)
+    $hex = -join ($bytes | ForEach-Object { $_.ToString("X2") })
+    return $hex.Substring(0, 10)
+}
+
+function Cleanup-Expired {
+    param([string]$Root)
+
+    if (-not (Test-Path $Root -PathType Container)) {
+        return
+    }
+
+    $cutoff = (Get-Date).ToUniversalTime().AddHours(-$TTL_HOURS)
+    Get-ChildItem -Path $Root -Recurse -File -Filter 'patch-*.patch' -ErrorAction SilentlyContinue |
+        Where-Object { $_.LastWriteTimeUtc -lt $cutoff } |
+        ForEach-Object {
+            Remove-Item $_.FullName -Force -ErrorAction SilentlyContinue
+        }
+
+    Get-ChildItem -Path $Root -Recurse -Directory -ErrorAction SilentlyContinue |
+        Sort-Object FullName -Descending |
+        ForEach-Object {
+            if (-not (Get-ChildItem -Path $_.FullName -Force -ErrorAction SilentlyContinue)) {
+                Remove-Item $_.FullName -Force -ErrorAction SilentlyContinue
+            }
+        }
+}
+
+if ($Help) {
+    Show-Usage
+    exit 0
+}
+
+if (-not $Workspace) {
+    Fail-Alloc -Code "ABC_TEMP_ALLOC_FAILED" -Message "Missing required -Workspace argument. Please provide the workspace root path."
+}
+
+try {
+    New-Item -ItemType Directory -Path $TMP_ROOT -Force | Out-Null
+}
+catch {
+    Fail-Alloc -Code "ABC_TEMP_ALLOC_FAILED" -Message "Failed to create the temp root at $TMP_ROOT. Please check directory permissions."
+}
+
+Cleanup-Expired -Root $TMP_ROOT
+
+$workspaceHash = Get-WorkspaceHash -InputText $Workspace
+$workspaceDir = Join-Path $TMP_ROOT $workspaceHash
+
+try {
+    New-Item -ItemType Directory -Path $workspaceDir -Force | Out-Null
+}
+catch {
+    Fail-Alloc -Code "ABC_TEMP_ALLOC_FAILED" -Message "Failed to create the workspace temp directory at $workspaceDir. Please check directory permissions."
+}
+
+$stamp = (Get-Date).ToUniversalTime().ToString("yyyyMMddTHHmmssZ")
+$createdAt = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
+$id = Get-RandomId
+$patchPath = Join-Path $workspaceDir "patch-$stamp-$id.patch"
+
+try {
+    New-Item -ItemType File -Path $patchPath -Force | Out-Null
+}
+catch {
+    Fail-Alloc -Code "ABC_TEMP_ALLOC_FAILED" -Message "Failed to create a temporary patch file at $patchPath. Please check directory permissions and available disk space."
+}
+
+$result = [ordered]@{
+    ok = $true
+    id = $id
+    createdAt = $createdAt
+    path = $patchPath
+    ttlHours = $TTL_HOURS
+}
+
+$result | ConvertTo-Json -Compress | Write-Output

package/platform/win/check_uncommitted.ps1

@@ -288,12 +288,20 @@ function Build-Reminder {
     # Project-local script; fallback to global
     $checkpointSh = "~/.vibe-x/agent-better-checkpoint/scripts/checkpoint.sh"
     $checkpointPs1 = "`$env:USERPROFILE/.vibe-x/agent-better-checkpoint/scripts/checkpoint.ps1"
+    $allocPatchSh = "~/.vibe-x/agent-better-checkpoint/scripts/alloc_patch.sh"
+    $allocPatchPs1 = "`$env:USERPROFILE/.vibe-x/agent-better-checkpoint/scripts/alloc_patch.ps1"
     if (Test-Path (Join-Path $Workspace ".vibe-x/agent-better-checkpoint/checkpoint.sh")) {
         $checkpointSh = ".vibe-x/agent-better-checkpoint/checkpoint.sh"
     }
     if (Test-Path (Join-Path $Workspace ".vibe-x/agent-better-checkpoint/checkpoint.ps1")) {
         $checkpointPs1 = ".\.vibe-x\agent-better-checkpoint\checkpoint.ps1"
     }
+    if (Test-Path (Join-Path $Workspace ".vibe-x/agent-better-checkpoint/alloc_patch.sh")) {
+        $allocPatchSh = ".vibe-x/agent-better-checkpoint/alloc_patch.sh"
+    }
+    if (Test-Path (Join-Path $Workspace ".vibe-x/agent-better-checkpoint/alloc_patch.ps1")) {
+        $allocPatchPs1 = ".\.vibe-x\agent-better-checkpoint\alloc_patch.ps1"
+    }
 
     return @"
 ## ⚠️ Uncommitted Changes Detected
@@ -305,17 +313,24 @@ There are uncommitted changes in the workspace. Please create a checkpoint commi
 $ChangesIndented
 ``````
 
-**Action Required**: Run the checkpoint script to commit these changes:
+**Action Required**: Allocate a patch file, write only the selected hunks for this conversation, then run the checkpoint script.
 
 **macOS/Linux:**
 ``````bash
-$checkpointSh "checkpoint(<scope>): <description>" "<user-prompt>" --type fallback
+PATCH_JSON=$($allocPatchSh --workspace "$Workspace")
+PATCH_PATH=$(printf '%s' "$PATCH_JSON" | python3 -c 'import sys,json; print(json.load(sys.stdin)["path"])')
+# Write only the selected hunks for this conversation to "$PATCH_PATH" as a unified diff patch.
+$checkpointSh "checkpoint(<scope>): <description>" "<user-prompt>" --type fallback --patch-file "$PATCH_PATH"
 ``````
 
 **Windows (PowerShell):**
 ``````powershell
-powershell -File "$checkpointPs1" "checkpoint(<scope>): <description>" "<user-prompt>" -Type fallback
+$patch = powershell -File "$allocPatchPs1" -Workspace "$Workspace" | ConvertFrom-Json
+# Write only the selected hunks for this conversation to $patch.path as a unified diff patch.
+powershell -File "$checkpointPs1" "checkpoint(<scope>): <description>" "<user-prompt>" -Type fallback -PatchFile $patch.path
 ``````
+
+If the checkpoint script returns an `ABC_PATCH_*` error, do not fall back to a full commit automatically. Explain the conflict and ask the user how to proceed.
 "@
 }
 

package/platform/win/checkpoint.ps1

@@ -6,7 +6,7 @@
     AI provides descriptive content (subject + body). This script:
     1. Truncates user-prompt (≤60 chars, head+tail)
     2. Appends metadata via git interpret-trailers
-    3. Runs git add -A && git commit
+    3. Runs git add -A && git commit, or applies a selected patch to the index first
 
 .PARAMETER Message
     Full commit message (subject + blank line + body). Required.
@@ -17,22 +17,65 @@
 .PARAMETER Type
     Checkpoint type: "auto" (default) or "fallback".
 
+.PARAMETER PatchFile
+    Optional patch file path. When provided, only the selected hunks are staged before commit.
+
 .EXAMPLE
     .\checkpoint.ps1 "checkpoint(auth): add JWT refresh" "implement token refresh"
 #>
 
 param(
-    [Parameter(Mandatory = $true, Position = 0)]
-    [string]$Message,
+    [Parameter(Position = 0)]
+    [string]$Message = "",
 
     [Parameter(Position = 1)]
     [string]$UserPrompt = "",
 
-    [string]$Type = "auto"
+    [string]$Type = "auto",
+
+    [string]$PatchFile = "",
+
+    [switch]$Help
 )
 
 $ErrorActionPreference = "Stop"
 
+function Show-Usage {
+    @"
+checkpoint.ps1 — Create semantic Git checkpoint commits
+
+Usage:
+  checkpoint.ps1 <message> [user-prompt] [-Type auto|fallback] [-PatchFile <path>]
+  checkpoint.ps1 -Help
+
+Options:
+  -Type <auto|fallback>  Checkpoint type metadata
+  -PatchFile <path>      Apply only the selected patch hunks to the index before commit
+  -Help                  Show this help message
+"@ | Write-Output
+}
+
+function Fail-Checkpoint {
+    param(
+        [string]$Code,
+        [string]$MessageText
+    )
+
+    [Console]::Error.WriteLine("${Code}: ${MessageText}")
+    exit 1
+}
+
+if ($Help) {
+    Show-Usage
+    exit 0
+}
+
+if (-not $Message) {
+    [Console]::Error.WriteLine("Error: commit message is required")
+    [Console]::Error.WriteLine("Usage: checkpoint.ps1 <message> [user-prompt] [-Type auto|fallback] [-PatchFile <path>]")
+    exit 1
+}
+
 # ============================================================
 # Platform detection
 # ============================================================
@@ -80,11 +123,11 @@ if ($UserPrompt) {
 
 function Test-HasChanges {
     # Staged changes
-    $diffCached = git diff --cached --quiet 2>$null
+    git diff --cached --quiet 2>$null
     if ($LASTEXITCODE -ne 0) { return $true }
 
     # Unstaged changes
-    $diffWorking = git diff --quiet 2>$null
+    git diff --quiet 2>$null
     if ($LASTEXITCODE -ne 0) { return $true }
 
     # Untracked files
@@ -94,16 +137,46 @@ function Test-HasChanges {
     return $false
 }
 
-if (-not (Test-HasChanges)) {
-    Write-Host "No changes to commit."
-    exit 0
+function Test-HasStagedChanges {
+    git diff --cached --quiet 2>$null
+    return $LASTEXITCODE -ne 0
 }
 
-# ============================================================
-# git add -A
-# ============================================================
+if (-not $PatchFile) {
+    if (-not (Test-HasChanges)) {
+        Write-Host "No changes to commit."
+        exit 0
+    }
 
-git add -A
+    # ============================================================
+    # git add -A
+    # ============================================================
+    git add -A
+}
+else {
+    if (-not (Test-Path $PatchFile -PathType Leaf)) {
+        Fail-Checkpoint -Code "ABC_PATCH_FILE_MISSING" -MessageText "Patch file not found at $PatchFile. Please allocate and write the patch file before running checkpoint."
+    }
+
+    $patchInfo = Get-Item $PatchFile
+    if ($patchInfo.Length -le 0) {
+        Fail-Checkpoint -Code "ABC_PATCH_FILE_EMPTY" -MessageText "Patch file at $PatchFile is empty. Please write at least one selected hunk before running checkpoint."
+    }
+
+    git apply --cached --check -- $PatchFile 2>$null
+    if ($LASTEXITCODE -ne 0) {
+        Fail-Checkpoint -Code "ABC_PATCH_APPLY_FAILED" -MessageText "Failed to apply the selected patch cleanly to the Git index. The target hunks may have drifted or overlap with other uncommitted edits."
+    }
+
+    git apply --cached -- $PatchFile 2>$null
+    if ($LASTEXITCODE -ne 0) {
+        Fail-Checkpoint -Code "ABC_PATCH_APPLY_FAILED" -MessageText "Failed to apply the selected patch to the Git index after the dry run succeeded. Please verify the patch file and retry."
+    }
+
+    if (-not (Test-HasStagedChanges)) {
+        Fail-Checkpoint -Code "ABC_PATCH_NO_STAGED_CHANGES" -MessageText "The selected patch did not produce any staged changes. The target hunks may already be staged or no longer match the current repository state."
+    }
+}
 
 # ============================================================
 # Build trailers and commit
@@ -118,7 +191,16 @@ if ($TruncatedPrompt) {
     $TrailerArgs += @("--trailer", "User-Prompt: $TruncatedPrompt")
 }
 
-# Pipe message → git interpret-trailers → git commit
 $Message | git interpret-trailers @TrailerArgs | git commit -F -
+if ($LASTEXITCODE -ne 0) {
+    if ($PatchFile) {
+        Fail-Checkpoint -Code "ABC_PATCH_COMMIT_FAILED" -MessageText "Git commit failed after staging the selected patch. Review the repository state and retry when ready."
+    }
+    exit $LASTEXITCODE
+}
+
+if ($PatchFile -and (Test-Path $PatchFile -PathType Leaf)) {
+    Remove-Item $PatchFile -Force -ErrorAction SilentlyContinue
+}
 
 Write-Host "Checkpoint committed successfully."

package/scripts/release-check.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * Release Gate for agent-better-checkpoint.
+ * Fails fast when common release omissions are detected.
+ */
+
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+
+function fail(msg) {
+  console.error(`\n[release:check] ${msg}`);
+  process.exit(1);
+}
+
+function ok(msg) {
+  console.log(`[release:check] OK: ${msg}`);
+}
+
+function fileExists(path) {
+  try {
+    readFileSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function sha256(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+function readText(path) {
+  return readFileSync(path, 'utf8');
+}
+
+function git(args) {
+  return execFileSync('git', args, { encoding: 'utf8' }).trim();
+}
+
+function ensureCleanWorktree() {
+  const out = git(['status', '--porcelain']);
+  if (out.length !== 0) fail('Working tree is not clean. Commit or stash changes before release.');
+  ok('working tree clean');
+}
+
+function ensureChangelogHasVersion(version) {
+  const changelog = readText('CHANGELOG.md');
+  if (!changelog.includes(`## [${version}]`)) {
+    fail(`CHANGELOG.md does not contain an entry for version ${version}.`);
+  }
+  ok(`CHANGELOG contains ${version}`);
+}
+
+function ensureFilesInSync(sourcePath, mirrorPath, label) {
+  if (!fileExists(mirrorPath)) {
+    console.warn(`[release:check] WARN: ${mirrorPath} not found; skipping sync check for ${label}.`);
+    return;
+  }
+
+  const sourceText = readText(sourcePath).replace(/\r\n/g, '\n');
+  const mirrorText = readText(mirrorPath).replace(/\r\n/g, '\n');
+
+  if (sha256(sourceText) !== sha256(mirrorText)) {
+    fail(`${label} out of sync:\n- ${sourcePath}\n- ${mirrorPath}\nPlease update both or regenerate project-local copy.`);
+  }
+
+  ok(`${label} copies are in sync`);
+}
+
+function ensureProjectLocalScriptsInSync() {
+  const pairs = [
+    {
+      sourcePath: 'platform/unix/checkpoint.sh',
+      mirrorPath: '.vibe-x/agent-better-checkpoint/checkpoint.sh',
+      label: 'unix checkpoint.sh',
+    },
+    {
+      sourcePath: 'platform/unix/check_uncommitted.sh',
+      mirrorPath: '.vibe-x/agent-better-checkpoint/check_uncommitted.sh',
+      label: 'unix check_uncommitted.sh',
+    },
+    {
+      sourcePath: 'platform/win/checkpoint.ps1',
+      mirrorPath: '.vibe-x/agent-better-checkpoint/checkpoint.ps1',
+      label: 'windows checkpoint.ps1',
+    },
+    {
+      sourcePath: 'platform/win/check_uncommitted.ps1',
+      mirrorPath: '.vibe-x/agent-better-checkpoint/check_uncommitted.ps1',
+      label: 'windows check_uncommitted.ps1',
+    },
+    {
+      sourcePath: 'platform/unix/alloc_patch.sh',
+      mirrorPath: '.vibe-x/agent-better-checkpoint/alloc_patch.sh',
+      label: 'unix alloc_patch.sh',
+    },
+    {
+      sourcePath: 'platform/win/alloc_patch.ps1',
+      mirrorPath: '.vibe-x/agent-better-checkpoint/alloc_patch.ps1',
+      label: 'windows alloc_patch.ps1',
+    },
+  ];
+
+  for (const pair of pairs) {
+    ensureFilesInSync(pair.sourcePath, pair.mirrorPath, pair.label);
+  }
+}
+
+function ensureSkillVersionMatches(version) {
+  const skill = readText('skill/SKILL.md');
+  const requiredSnippets = [
+    `version: "${version}"`,
+    `@vibe-x/agent-better-checkpoint@${version}`,
+    `**Version**: ${version}`,
+  ];
+
+  const missing = requiredSnippets.filter((snippet) => !skill.includes(snippet));
+  if (missing.length > 0) {
+    fail(`skill/SKILL.md is missing current version references for ${version}:\n- ${missing.join('\n- ')}`);
+  }
+
+  ok(`skill/SKILL.md references ${version}`);
+}
+
+function main() {
+  if (!fileExists('package.json')) fail('package.json not found (run from repo root).');
+  if (!fileExists('CHANGELOG.md')) fail('CHANGELOG.md not found.');
+  if (!fileExists('platform/unix/checkpoint.sh')) fail('platform/unix/checkpoint.sh not found.');
+
+  const pkg = JSON.parse(readText('package.json'));
+  const version = pkg.version;
+  if (!version) fail('package.json missing version field.');
+
+  ensureCleanWorktree();
+  ensureProjectLocalScriptsInSync();
+  ensureChangelogHasVersion(version);
+  ensureSkillVersionMatches(version);
+
+  ok(`release checks passed for ${pkg.name}@${version}`);
+}
+
+main();

package/skill/SKILL.md

@@ -3,7 +3,7 @@ name: agent-better-checkpoint
 description: "Creates semantic Git checkpoint commits during AI coding sessions with Conventional Commits format and Git Trailers. Use after completing code edits, or when user says 'commit changes', 'create checkpoint', or 'save my progress'."
 license: MIT
 metadata:
-  version: "0.3.3"
+  version: "0.3.4"
   author: "alienzhou"
   category: "version-control"
 ---
@@ -31,7 +31,7 @@ Both `.sh` and `.ps1` are always installed regardless of current OS.
 If neither exists, run:
 
 ```bash
-npx @vibe-x/agent-better-checkpoint@0.3.3
+npx @vibe-x/agent-better-checkpoint@0.3.4
 ```
 
 Without `--target`: installs globally. With `--target .`: project-only (skill + hooks in `.cursor/`, scripts in `.vibe-x/`), no global changes.
@@ -99,14 +99,16 @@ Switch to flex-column layout with collapsible sidebar.
 
 ## 🛠️ How to Commit
 
-Call the checkpoint script after composing your message. Both `.sh` and `.ps1` are always available — pick the one matching the current OS.
+Default to the patch-based flow when you can clearly identify the hunks from the current logical unit of work. Fall back to the full-workspace commit flow only when the user explicitly wants everything committed together.
 
 **Prefer project-local when present**, fall back to global:
 
-| OS | Project-local | Global fallback |
-|----|--------------|-----------------|
-| macOS/Linux | `.vibe-x/agent-better-checkpoint/checkpoint.sh` | `~/.vibe-x/agent-better-checkpoint/scripts/checkpoint.sh` |
-| Windows | `powershell -File ".vibe-x\agent-better-checkpoint\checkpoint.ps1"` | `powershell -File "$env:USERPROFILE\.vibe-x\agent-better-checkpoint\scripts\checkpoint.ps1"` |
+| Script | macOS/Linux | Windows |
+|--------|-------------|---------|
+| checkpoint | `.vibe-x/agent-better-checkpoint/checkpoint.sh` | `powershell -File ".vibe-x\agent-better-checkpoint\checkpoint.ps1"` |
+| alloc_patch | `.vibe-x/agent-better-checkpoint/alloc_patch.sh` | `powershell -File ".vibe-x\agent-better-checkpoint\alloc_patch.ps1"` |
+| global checkpoint | `~/.vibe-x/agent-better-checkpoint/scripts/checkpoint.sh` | `powershell -File "$env:USERPROFILE\.vibe-x\agent-better-checkpoint\scripts\checkpoint.ps1"` |
+| global alloc_patch | `~/.vibe-x/agent-better-checkpoint/scripts/alloc_patch.sh` | `powershell -File "$env:USERPROFILE\.vibe-x\agent-better-checkpoint\scripts\alloc_patch.ps1"` |
 
 ### Parameters:
 
@@ -115,31 +117,51 @@ Call the checkpoint script after composing your message. Both `.sh` and `.ps1` a
 | message (1st arg) | Yes | Full commit message (subject + blank line + body) |
 | user-prompt (2nd arg) | No | The user's original prompt/request |
 | `--type` / `-Type` | No | `auto` (default) or `fallback` |
+| `--patch-file` / `-PatchFile` | No | Apply only the selected hunks from a unified diff patch before commit |
 
-### Example (macOS/Linux):
+### Recommended patch flow (macOS/Linux):
 
 ```bash
+PATCH_JSON=$(.vibe-x/agent-better-checkpoint/alloc_patch.sh --workspace "$PWD")
+PATCH_PATH=$(printf '%s' "$PATCH_JSON" | python3 -c 'import sys,json; print(json.load(sys.stdin)["path"])')
+# Write only the selected hunks for this logical unit to "$PATCH_PATH" as a unified diff patch.
 .vibe-x/agent-better-checkpoint/checkpoint.sh \
   "checkpoint(auth): add JWT token refresh logic
 
 Implement automatic token refresh when access token expires.
 Uses refresh token rotation for security." \
-  "帮我实现 token 刷新机制"
+  "帮我实现 token 刷新机制" \
+  --patch-file "$PATCH_PATH"
 ```
 
-### Example (Windows):
+### Recommended patch flow (Windows):
 
 ```powershell
+$patch = powershell -File ".vibe-x\agent-better-checkpoint\alloc_patch.ps1" -Workspace (Get-Location).Path | ConvertFrom-Json
+# Write only the selected hunks for this logical unit to $patch.path as a unified diff patch.
 powershell -File ".vibe-x\agent-better-checkpoint\checkpoint.ps1" `
   "checkpoint(auth): add JWT token refresh logic`n`nImplement automatic token refresh when access token expires.`nUses refresh token rotation for security." `
+  "帮我实现 token 刷新机制" `
+  -PatchFile $patch.path
+```
+
+### Full-workspace fallback example (macOS/Linux):
+
+```bash
+.vibe-x/agent-better-checkpoint/checkpoint.sh \
+  "checkpoint(auth): add JWT token refresh logic
+
+Implement automatic token refresh when access token expires.
+Uses refresh token rotation for security." \
   "帮我实现 token 刷新机制"
 ```
 
 ### What the script does:
 1. Truncates user prompt to ≤60 characters (head...tail)
 2. Appends Git Trailers: `Agent`, `Checkpoint-Type`, `User-Prompt`
-3. Runs `git add -A && git commit`
-4. Exits gracefully if there are no changes
+3. Either runs `git add -A && git commit` or applies the selected patch hunks and then commits
+4. Returns `ABC_PATCH_*` errors when the selected patch cannot be committed safely
+5. Exits gracefully if there are no changes
 
 ---
 
@@ -167,4 +189,4 @@ This should feel natural — commit as you go, like any good developer.
 
 ---
 
-**Version**: 0.3.3
+**Version**: 0.3.4