@link-assistant/hive-mind 0.48.3 → 0.49.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @link-assistant/hive-mind
 
+## 0.49.0
+
+### Minor Changes
+
+- Add --claude-file and --gitkeep-file CLI options for choosing between CLAUDE.md and .gitkeep files
+
+  This feature allows users to choose which file type to use for PR creation:
+  - `--claude-file` (default: true): Use CLAUDE.md file for task details
+  - `--gitkeep-file` (default: false, experimental): Use .gitkeep file instead
+
+  The flags are mutually exclusive:
+  - Using `--gitkeep-file` automatically disables `--claude-file`
+  - Using `--no-claude-file` automatically enables `--gitkeep-file`
+  - Both flags cannot be disabled simultaneously
+
+  This is a step toward making .gitkeep the default behavior in future releases.
+
+## 0.48.4
+
+### Patch Changes
+
+- b010ce6: Increase minimum disk space requirement from 512 MB to 2 GB to provide more room for commands to gracefully finish before running out of disk space and prevent potential OS issues
+
 ## 0.48.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "0.48.3",
+  "version": "0.49.0",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/config.lib.mjs

@@ -64,7 +64,7 @@ export const githubLimits = {
 
 // Memory and disk configurations
 export const systemLimits = {
-  minDiskSpaceMb: parseIntWithDefault('HIVE_MIND_MIN_DISK_SPACE_MB', 500),
+  minDiskSpaceMb: parseIntWithDefault('HIVE_MIND_MIN_DISK_SPACE_MB', 2048),
   defaultPageSizeKb: parseIntWithDefault('HIVE_MIND_DEFAULT_PAGE_SIZE_KB', 16),
 };
 

package/src/hive.config.lib.mjs

@@ -128,8 +128,8 @@ export const createYargsConfig = yargsInstance => {
     })
     .option('min-disk-space', {
       type: 'number',
-      description: 'Minimum required disk space in MB (default: 500)',
-      default: 500,
+      description: 'Minimum required disk space in MB (default: 2048)',
+      default: 2048,
     })
     .option('auto-cleanup', {
       type: 'boolean',

package/src/hive.mjs

@@ -1450,7 +1450,7 @@ if (isDirectExecution) {
     } else {
       const systemCheck = await checkSystem(
         {
-          minDiskSpaceMB: argv.minDiskSpace || 500,
+          minDiskSpaceMB: argv.minDiskSpace || 2048,
           minMemoryMB: 256,
           exitOnFailure: true,
         },

package/src/memory-check.mjs

@@ -27,7 +27,7 @@ const lib = await import('./lib.mjs');
 const { log: libLog, setLogFile } = lib;
 
 // Function to check available disk space
-export const checkDiskSpace = async (minSpaceMB = 500, options = {}) => {
+export const checkDiskSpace = async (minSpaceMB = 2048, options = {}) => {
   const log = options.log || libLog;
 
   try {
@@ -290,7 +290,7 @@ export const getResourceSnapshot = async () => {
 
 // Combined system check function
 export const checkSystem = async (requirements = {}, options = {}) => {
-  const { minMemoryMB = 256, minDiskSpaceMB = 500, exitOnFailure = false } = requirements;
+  const { minMemoryMB = 256, minDiskSpaceMB = 2048, exitOnFailure = false } = requirements;
 
   // Note: log is passed through options to checkDiskSpace and checkRAM
   const results = {
@@ -336,7 +336,7 @@ if (import.meta.url === `file://${process.argv[1]}`) {
       alias: 'd',
       type: 'number',
       description: 'Minimum required disk space in MB',
-      default: 500,
+      default: 2048,
     })
     .option('exit-on-failure', {
       alias: 'e',

package/src/solve.auto-continue.lib.mjs

@@ -181,18 +181,20 @@ export const checkExistingPRsForAutoContinue = async (argv, isIssueUrl, owner, r
                 continue;
               }
 
-              // Check if CLAUDE.md exists in this PR branch
+              // Check if CLAUDE.md or .gitkeep exists in this PR branch
+              // If neither exists, it means work was completed and files were removed
               const claudeMdExists = await checkFileInBranch(owner, repo, 'CLAUDE.md', pr.headRefName);
+              const gitkeepExists = await checkFileInBranch(owner, repo, '.gitkeep', pr.headRefName);
 
-              if (!claudeMdExists) {
-                await log(`✅ Auto-continue: Using PR #${pr.number} (CLAUDE.md missing - work completed, branch: ${pr.headRefName})`);
+              if (!claudeMdExists && !gitkeepExists) {
+                await log(`✅ Auto-continue: Using PR #${pr.number} (CLAUDE.md/.gitkeep missing - work completed, branch: ${pr.headRefName})`);
 
-                // Switch to continue mode immediately (don't wait 24 hours if CLAUDE.md is missing)
+                // Switch to continue mode immediately (don't wait 24 hours if both files are missing)
                 isContinueMode = true;
                 prNumber = pr.number;
                 prBranch = pr.headRefName;
                 if (argv.verbose) {
-                  await log('   Continue mode activated: Auto-continue (CLAUDE.md missing)', { verbose: true });
+                  await log('   Continue mode activated: Auto-continue (initial commit files missing)', { verbose: true });
                   await log(`   PR Number: ${prNumber}`, { verbose: true });
                   await log(`   PR Branch: ${prBranch}`, { verbose: true });
                 }
@@ -454,15 +456,16 @@ export const processAutoContinueForIssue = async (argv, isIssueUrl, urlNumber, o
               continue;
             }
 
-            // Check if CLAUDE.md exists in this PR branch
+            // Check if CLAUDE.md or .gitkeep exists in this PR branch
             const claudeMdExists = await checkFileInBranch(owner, repo, 'CLAUDE.md', pr.headRefName);
+            const gitkeepExists = await checkFileInBranch(owner, repo, '.gitkeep', pr.headRefName);
 
-            if (!claudeMdExists) {
-              await log(`✅ Auto-continue: Using PR #${pr.number} (CLAUDE.md missing - work completed, branch: ${pr.headRefName})`);
+            if (!claudeMdExists && !gitkeepExists) {
+              await log(`✅ Auto-continue: Using PR #${pr.number} (CLAUDE.md/.gitkeep missing - work completed, branch: ${pr.headRefName})`);
 
-              // Switch to continue mode immediately (don't wait 24 hours if CLAUDE.md is missing)
+              // Switch to continue mode immediately (don't wait 24 hours if CLAUDE.md/.gitkeep is missing)
               if (argv.verbose) {
-                await log('   Continue mode activated: Auto-continue (CLAUDE.md missing)', { verbose: true });
+                await log('   Continue mode activated: Auto-continue (CLAUDE.md/.gitkeep missing)', { verbose: true });
                 await log(`   PR Number: ${pr.number}`, { verbose: true });
                 await log(`   PR Branch: ${pr.headRefName}`, { verbose: true });
               }
@@ -490,12 +493,12 @@ export const processAutoContinueForIssue = async (argv, isIssueUrl, urlNumber, o
                 issueNumber,
               };
             } else {
-              await log(`  PR #${pr.number}: CLAUDE.md exists, age ${ageHours}h < 24h - skipping`);
+              await log(`  PR #${pr.number}: CLAUDE.md/.gitkeep exists, age ${ageHours}h < 24h - skipping`);
             }
           }
         }
 
-        await log('⏭️  No suitable PRs found (missing CLAUDE.md or older than 24h) - creating new PR as usual');
+        await log('⏭️  No suitable PRs found (missing CLAUDE.md/.gitkeep or older than 24h) - creating new PR as usual');
       } else {
         await log(`📝 No existing PRs found for issue #${issueNumber} - creating new PR`);
       }

package/src/solve.auto-pr.lib.mjs

@@ -30,20 +30,54 @@ export async function handleAutoPrCreation({ argv, tempDir, branchName, issueNum
   const issueUrl = argv['issue-url'] || argv._[0];
 
   try {
-    // Create CLAUDE.md file with the task details
-    await log(formatAligned('📝', 'Creating:', 'CLAUDE.md with task details'));
+    // Determine which file to create based on CLI flags
+    const useClaudeFile = argv.claudeFile !== false; // Default to true
+    const useGitkeepFile = argv.gitkeepFile === true; // Default to false
 
-    // Check if CLAUDE.md already exists and read its content
-    const claudeMdPath = path.join(tempDir, 'CLAUDE.md');
+    // Log which mode we're using
+    if (argv.verbose) {
+      await log(`   Using ${useClaudeFile ? 'CLAUDE.md' : '.gitkeep'} mode (--claude-file=${useClaudeFile}, --gitkeep-file=${useGitkeepFile})`, { verbose: true });
+    }
+
+    let filePath;
+    let fileName;
     let existingContent = null;
     let fileExisted = false;
-    try {
-      existingContent = await fs.readFile(claudeMdPath, 'utf8');
-      fileExisted = true;
-    } catch (err) {
-      // File doesn't exist, which is fine
-      if (err.code !== 'ENOENT') {
-        throw err;
+
+    if (useClaudeFile) {
+      // Create CLAUDE.md file with the task details
+      await log(formatAligned('📝', 'Creating:', 'CLAUDE.md with task details'));
+
+      filePath = path.join(tempDir, 'CLAUDE.md');
+      fileName = 'CLAUDE.md';
+
+      // Check if CLAUDE.md already exists and read its content
+      try {
+        existingContent = await fs.readFile(filePath, 'utf8');
+        fileExisted = true;
+      } catch (err) {
+        // File doesn't exist, which is fine
+        if (err.code !== 'ENOENT') {
+          throw err;
+        }
+      }
+    } else {
+      // Create .gitkeep file directly (experimental mode)
+      await log(formatAligned('📝', 'Creating:', '.gitkeep (experimental mode)'));
+
+      filePath = path.join(tempDir, '.gitkeep');
+      fileName = '.gitkeep';
+
+      // .gitkeep files are typically small, no need to check for existing content
+      // But we'll check if it exists for proper handling
+      try {
+        existingContent = await fs.readFile(filePath, 'utf8');
+        fileExisted = true;
+      } catch (err) {
+        // File doesn't exist, which is fine
+        if (err.code !== 'ENOENT') {
+          throw err;
+        }
       }
     }
 
@@ -61,44 +95,65 @@ export async function handleAutoPrCreation({ argv, tempDir, branchName, issueNum
     // Without this, appending the same task info produces no git changes,
     // leading to "No commits between branches" error during PR creation
     const timestamp = new Date().toISOString();
-    const taskInfo = `Issue to solve: ${issueUrl}
+
+    let finalContent;
+
+    if (useClaudeFile) {
+      // CLAUDE.md: Use detailed task info
+      const taskInfo = `Issue to solve: ${issueUrl}
 Your prepared branch: ${branchName}
 Your prepared working directory: ${tempDir}${
-      argv.fork && forkedRepo
-        ? `
+        argv.fork && forkedRepo
+          ? `
 Your forked repository: ${forkedRepo}
 Original repository (upstream): ${owner}/${repo}`
-        : ''
-    }
+          : ''
+      }
 
 Proceed.`;
 
-    // If CLAUDE.md already exists, append the task info with separator and timestamp
-    // Otherwise, create new file with just the task info (no timestamp needed for new files)
-    let finalContent;
-    if (fileExisted && existingContent) {
-      await log('   CLAUDE.md already exists, appending task info...', { verbose: true });
-      // Remove any trailing whitespace and add separator
-      const trimmedExisting = existingContent.trimEnd();
-      // Add timestamp to ensure uniqueness when appending
-      finalContent = `${trimmedExisting}\n\n---\n\n${taskInfo}\n\nRun timestamp: ${timestamp}`;
+      // If file already exists, append the task info with separator and timestamp
+      // Otherwise, create new file with just the task info (no timestamp needed for new files)
+      if (fileExisted && existingContent) {
+        await log(`   ${fileName} already exists, appending task info...`, { verbose: true });
+        // Remove any trailing whitespace and add separator
+        const trimmedExisting = existingContent.trimEnd();
+        // Add timestamp to ensure uniqueness when appending
+        finalContent = `${trimmedExisting}\n\n---\n\n${taskInfo}\n\nRun timestamp: ${timestamp}`;
+      } else {
+        finalContent = taskInfo;
+      }
     } else {
-      finalContent = taskInfo;
+      // .gitkeep: Use minimal metadata format
+      const gitkeepContent = `# Auto-generated file for PR creation
+# Issue: ${issueUrl}
+# Branch: ${branchName}
+# Timestamp: ${timestamp}
+# This file was created with --gitkeep-file flag (experimental)
+# It will be removed when the task is complete`;
+
+      if (fileExisted && existingContent) {
+        await log(`   ${fileName} already exists, appending timestamp...`, { verbose: true });
+        // For .gitkeep, just append a new timestamp to ensure uniqueness
+        finalContent = `${existingContent.trimEnd()}\n# Updated: ${timestamp}`;
+      } else {
+        finalContent = gitkeepContent;
+      }
     }
 
-    await fs.writeFile(claudeMdPath, finalContent);
-    await log(formatAligned('✅', 'File created:', 'CLAUDE.md'));
+    await fs.writeFile(filePath, finalContent);
+    await log(formatAligned('✅', 'File created:', fileName));
 
     // Add and commit the file
     await log(formatAligned('📦', 'Adding file:', 'To git staging'));
 
     // Use explicit cwd option for better reliability
-    const addResult = await $({ cwd: tempDir })`git add CLAUDE.md`;
+    const addResult = await $({ cwd: tempDir })`git add ${fileName}`;
 
     if (addResult.code !== 0) {
-      await log('❌ Failed to add CLAUDE.md', { level: 'error' });
+      await log(`❌ Failed to add ${fileName}`, { level: 'error' });
       await log(`   Error: ${addResult.stderr ? addResult.stderr.toString() : 'Unknown error'}`, { level: 'error' });
-      throw new Error('Failed to add CLAUDE.md');
+      throw new Error(`Failed to add ${fileName}`);
     }
 
     // Verify the file was actually staged
@@ -110,112 +165,133 @@ Proceed.`;
     }
 
     // Track which file we're using for the commit
-    let commitFileName = 'CLAUDE.md';
+    let commitFileName = fileName;
 
     // Check if anything was actually staged
     if (!gitStatus || gitStatus.length === 0) {
       await log('');
-      await log(formatAligned('⚠️', 'CLAUDE.md not staged:', 'Checking if file is ignored'), { level: 'warning' });
+      await log(formatAligned('⚠️', `${fileName} not staged:`, 'Checking if file is ignored'), { level: 'warning' });
 
-      // Check if CLAUDE.md is in .gitignore
-      const checkIgnoreResult = await $({ cwd: tempDir })`git check-ignore CLAUDE.md`;
-      const isIgnored = checkIgnoreResult.code === 0;
+      // Only apply fallback logic when using CLAUDE.md mode (not in --gitkeep-file mode)
+      if (useClaudeFile) {
+        // Check if CLAUDE.md is in .gitignore
+        const checkIgnoreResult = await $({ cwd: tempDir })`git check-ignore CLAUDE.md`;
+        const isIgnored = checkIgnoreResult.code === 0;
 
-      if (isIgnored) {
-        await log(formatAligned('ℹ️', 'CLAUDE.md is ignored:', 'Using .gitkeep fallback'));
-        await log('');
-        await log('  📝 Fallback strategy:');
-        await log('     CLAUDE.md is in .gitignore, using .gitkeep instead.');
-        await log('     This allows auto-PR creation to proceed without modifying .gitignore.');
-        await log('');
+        if (isIgnored) {
+          await log(formatAligned('ℹ️', 'CLAUDE.md is ignored:', 'Using .gitkeep fallback'));
+          await log('');
+          await log('  📝 Fallback strategy:');
+          await log('     CLAUDE.md is in .gitignore, using .gitkeep instead.');
+          await log('     This allows auto-PR creation to proceed without modifying .gitignore.');
+          await log('');
 
-        // Create a .gitkeep file as fallback
-        const gitkeepPath = path.join(tempDir, '.gitkeep');
-        const gitkeepContent = `# Auto-generated file for PR creation
+          // Create a .gitkeep file as fallback
+          const gitkeepPath = path.join(tempDir, '.gitkeep');
+          const gitkeepContent = `# Auto-generated file for PR creation
 # Issue: ${issueUrl}
 # Branch: ${branchName}
 # This file was created because CLAUDE.md is in .gitignore
 # It will be removed when the task is complete`;
 
-        await fs.writeFile(gitkeepPath, gitkeepContent);
-        await log(formatAligned('✅', 'Created:', '.gitkeep file'));
+          await fs.writeFile(gitkeepPath, gitkeepContent);
+          await log(formatAligned('✅', 'Created:', '.gitkeep file'));
 
-        // Try to add .gitkeep
-        const gitkeepAddResult = await $({ cwd: tempDir })`git add .gitkeep`;
+          // Try to add .gitkeep
+          const gitkeepAddResult = await $({ cwd: tempDir })`git add .gitkeep`;
 
-        if (gitkeepAddResult.code !== 0) {
-          await log('❌ Failed to add .gitkeep', { level: 'error' });
-          await log(`   Error: ${gitkeepAddResult.stderr ? gitkeepAddResult.stderr.toString() : 'Unknown error'}`, {
-            level: 'error',
-          });
-          throw new Error('Failed to add .gitkeep');
-        }
+          if (gitkeepAddResult.code !== 0) {
+            await log('❌ Failed to add .gitkeep', { level: 'error' });
+            await log(`   Error: ${gitkeepAddResult.stderr ? gitkeepAddResult.stderr.toString() : 'Unknown error'}`, {
+              level: 'error',
+            });
+            throw new Error('Failed to add .gitkeep');
+          }
+
+          // Verify .gitkeep was staged
+          statusResult = await $({ cwd: tempDir })`git status --short`;
+          gitStatus = statusResult.stdout ? statusResult.stdout.toString().trim() : '';
 
-        // Verify .gitkeep was staged
-        statusResult = await $({ cwd: tempDir })`git status --short`;
-        gitStatus = statusResult.stdout ? statusResult.stdout.toString().trim() : '';
+          if (!gitStatus || gitStatus.length === 0) {
+            await log('');
+            await log(formatAligned('❌', 'GIT ADD FAILED:', 'Neither CLAUDE.md nor .gitkeep could be staged'), {
+              level: 'error',
+            });
+            await log('');
+            await log('  🔍 What happened:');
+            await log('     Both CLAUDE.md and .gitkeep failed to stage.');
+            await log('');
+            await log('  🔧 Troubleshooting steps:');
+            await log(`     1. Check git status: cd "${tempDir}" && git status`);
+            await log(`     2. Check .gitignore: cat "${tempDir}/.gitignore"`);
+            await log(`     3. Try force add: cd "${tempDir}" && git add -f .gitkeep`);
+            await log('');
+            throw new Error('Git add staged nothing - both files failed');
+          }
 
-        if (!gitStatus || gitStatus.length === 0) {
+          commitFileName = '.gitkeep';
+          await log(formatAligned('✅', 'File staged:', '.gitkeep'));
+        } else {
           await log('');
-          await log(formatAligned('❌', 'GIT ADD FAILED:', 'Neither CLAUDE.md nor .gitkeep could be staged'), {
-            level: 'error',
-          });
+          await log(formatAligned('❌', 'GIT ADD FAILED:', 'Nothing was staged'), { level: 'error' });
           await log('');
           await log('  🔍 What happened:');
-          await log('     Both CLAUDE.md and .gitkeep failed to stage.');
+          await log('     CLAUDE.md was created but git did not stage any changes.');
+          await log('');
+          await log('  💡 Possible causes:');
+          await log('     • CLAUDE.md already exists with identical content');
+          await log('     • File system sync issue');
           await log('');
           await log('  🔧 Troubleshooting steps:');
-          await log(`     1. Check git status: cd "${tempDir}" && git status`);
-          await log(`     2. Check .gitignore: cat "${tempDir}/.gitignore"`);
-          await log(`     3. Try force add: cd "${tempDir}" && git add -f .gitkeep`);
+          await log(`     1. Check file exists: ls -la "${tempDir}/CLAUDE.md"`);
+          await log(`     2. Check git status: cd "${tempDir}" && git status`);
+          await log(`     3. Force add: cd "${tempDir}" && git add -f CLAUDE.md`);
           await log('');
-          throw new Error('Git add staged nothing - both files failed');
+          await log('  📂 Debug information:');
+          await log(`     Working directory: ${tempDir}`);
+          await log(`     Branch: ${branchName}`);
+          if (existingContent) {
+            await log('     Note: CLAUDE.md already existed (attempted to update with timestamp)');
+          }
+          await log('');
+          throw new Error('Git add staged nothing - CLAUDE.md may be unchanged');
         }
-
-        commitFileName = '.gitkeep';
-        await log(formatAligned('✅', 'File staged:', '.gitkeep'));
       } else {
+        // In --gitkeep-file mode, if .gitkeep couldn't be staged, this is an error
         await log('');
         await log(formatAligned('❌', 'GIT ADD FAILED:', 'Nothing was staged'), { level: 'error' });
         await log('');
         await log('  🔍 What happened:');
-        await log('     CLAUDE.md was created but git did not stage any changes.');
+        await log(`     ${fileName} was created but git did not stage any changes.`);
         await log('');
         await log('  💡 Possible causes:');
-        await log('     • CLAUDE.md already exists with identical content');
+        await log(`     • ${fileName} already exists with identical content`);
         await log('     • File system sync issue');
+        await log(`     • ${fileName} is in .gitignore`);
         await log('');
         await log('  🔧 Troubleshooting steps:');
-        await log(`     1. Check file exists: ls -la "${tempDir}/CLAUDE.md"`);
+        await log(`     1. Check file exists: ls -la "${tempDir}/${fileName}"`);
         await log(`     2. Check git status: cd "${tempDir}" && git status`);
-        await log(`     3. Force add: cd "${tempDir}" && git add -f CLAUDE.md`);
+        await log(`     3. Check if ignored: cd "${tempDir}" && git check-ignore ${fileName}`);
+        await log(`     4. Force add: cd "${tempDir}" && git add -f ${fileName}`);
         await log('');
         await log('  📂 Debug information:');
         await log(`     Working directory: ${tempDir}`);
         await log(`     Branch: ${branchName}`);
+        await log(`     Mode: ${useClaudeFile ? 'CLAUDE.md' : '.gitkeep'}`);
         if (existingContent) {
-          await log('     Note: CLAUDE.md already existed (attempted to update with timestamp)');
+          await log(`     Note: ${fileName} already existed (attempted to update with timestamp)`);
         }
         await log('');
-        throw new Error('Git add staged nothing - CLAUDE.md may be unchanged');
+        throw new Error(`Git add staged nothing - ${fileName} may be unchanged or ignored`);
       }
     }
 
     await log(formatAligned('📝', 'Creating commit:', `With ${commitFileName} file`));
-    const commitMessage =
-      commitFileName === 'CLAUDE.md'
-        ? `Initial commit with task details
-
-Adding CLAUDE.md with task information for AI processing.
-This file will be removed when the task is complete.
-
-Issue: ${issueUrl}`
-        : `Initial commit with task details
-
-Adding .gitkeep for PR creation (CLAUDE.md is in .gitignore).
-This file will be removed when the task is complete.
 
-Issue: ${issueUrl}`;
+    // Determine commit message based on which file is being committed
+    const fileDesc = commitFileName === 'CLAUDE.md' ? 'CLAUDE.md with task information for AI processing' : `.gitkeep for PR creation (${useGitkeepFile ? 'created with --gitkeep-file flag (experimental)' : 'CLAUDE.md is in .gitignore'})`;
+    const commitMessage = `Initial commit with task details\n\nAdding ${fileDesc}.\nThis file will be removed when the task is complete.\n\nIssue: ${issueUrl}`;
 
     // Use explicit cwd option for better reliability
     const commitResult = await $({ cwd: tempDir })`git commit -m ${commitMessage}`;
@@ -228,7 +304,7 @@ Issue: ${issueUrl}`;
       await log(formatAligned('❌', 'COMMIT FAILED:', 'Could not create initial commit'), { level: 'error' });
       await log('');
       await log('  🔍 What happened:');
-      await log('     Git commit command failed after staging CLAUDE.md.');
+      await log(`     Git commit command failed after staging ${commitFileName}.`);
       await log('');
 
       // Check for specific error patterns

package/src/solve.config.lib.mjs

@@ -118,6 +118,16 @@ export const createYargsConfig = yargsInstance => {
         description: 'Automatically fork public repositories without write access (fails for private repos)',
         default: true,
       })
+      .option('claude-file', {
+        type: 'boolean',
+        description: 'Create CLAUDE.md file for task details (default, mutually exclusive with --gitkeep-file)',
+        default: true,
+      })
+      .option('gitkeep-file', {
+        type: 'boolean',
+        description: 'Create .gitkeep file instead of CLAUDE.md (experimental, mutually exclusive with --claude-file)',
+        default: false,
+      })
       .option('attach-logs', {
         type: 'boolean',
         description: 'Upload the solution draft log file to the Pull Request on completion (⚠️ WARNING: May expose sensitive data)',
@@ -181,8 +191,8 @@ export const createYargsConfig = yargsInstance => {
       })
       .option('min-disk-space', {
         type: 'number',
-        description: 'Minimum required disk space in MB (default: 500)',
-        default: 500,
+        description: 'Minimum required disk space in MB (default: 2048)',
+        default: 2048,
       })
       .option('log-dir', {
         type: 'string',
@@ -365,5 +375,44 @@ export const parseArguments = async (yargs, hideBin) => {
     argv.model = 'grok-code';
   }
 
+  // Validate mutual exclusivity of --claude-file and --gitkeep-file
+  // Check if both are explicitly enabled (user passed both --claude-file and --gitkeep-file)
+  if (argv.claudeFile && argv.gitkeepFile) {
+    // Check if they were explicitly set via command line
+    const claudeFileExplicit = rawArgs.includes('--claude-file');
+    const gitkeepFileExplicit = rawArgs.includes('--gitkeep-file');
+
+    if (claudeFileExplicit && gitkeepFileExplicit) {
+      throw new Error('--claude-file and --gitkeep-file are mutually exclusive. Please use only one.');
+    }
+
+    // If only one is explicit, turn off the other
+    if (gitkeepFileExplicit && !claudeFileExplicit) {
+      argv.claudeFile = false;
+    } else if (claudeFileExplicit && !gitkeepFileExplicit) {
+      argv.gitkeepFile = false;
+    }
+  }
+
+  // Check for both being disabled (both --no-claude-file and --no-gitkeep-file)
+  const noClaudeFile = rawArgs.includes('--no-claude-file');
+  const noGitkeepFile = rawArgs.includes('--no-gitkeep-file');
+
+  if (noClaudeFile && noGitkeepFile) {
+    throw new Error('Cannot disable both --claude-file and --gitkeep-file. At least one must be enabled for PR creation.');
+  }
+
+  // If user explicitly set --no-claude-file, enable gitkeep-file
+  if (noClaudeFile && !argv.gitkeepFile) {
+    argv.gitkeepFile = true;
+    argv.claudeFile = false;
+  }
+
+  // If user explicitly set --no-gitkeep-file, enable claude-file (this is the default anyway)
+  if (noGitkeepFile && !argv.claudeFile) {
+    argv.claudeFile = true;
+    argv.gitkeepFile = false;
+  }
+
   return argv;
 };

package/src/solve.mjs

@@ -211,7 +211,7 @@ await validateAndExitOnInvalidModel(argv.model, tool, safeExit);
 // Skip tool CONNECTION validation in dry-run mode or when --skip-tool-connection-check or --no-tool-connection-check is enabled
 // Note: This does NOT skip model validation which is performed above
 const skipToolConnectionCheck = argv.dryRun || argv.skipToolConnectionCheck || argv.toolConnectionCheck === false;
-if (!(await performSystemChecks(argv.minDiskSpace || 500, skipToolConnectionCheck, argv.model, argv))) {
+if (!(await performSystemChecks(argv.minDiskSpace || 2048, skipToolConnectionCheck, argv.model, argv))) {
   await safeExit(1, 'System checks failed');
 }
 // URL validation debug logging
@@ -1045,8 +1045,8 @@ try {
   const autoRestartEnabled = argv['autoRestartOnUncommittedChanges'] !== false;
   const shouldRestart = await checkForUncommittedChanges(tempDir, owner, repo, branchName, $, log, shouldAutoCommit, autoRestartEnabled);
 
-  // Remove CLAUDE.md now that Claude command has finished
-  await cleanupClaudeFile(tempDir, branchName, claudeCommitHash);
+  // Remove initial commit file (CLAUDE.md or .gitkeep) now that Claude command has finished
+  await cleanupClaudeFile(tempDir, branchName, claudeCommitHash, argv);
 
   // Show summary of session and log file
   await showSessionSummary(sessionId, limitReached, argv, issueUrl, tempDir, shouldAttachLogs);

package/src/solve.results.lib.mjs

@@ -42,13 +42,13 @@ const githubLinking = await import('./github-linking.lib.mjs');
 const { hasGitHubLinkingKeyword } = githubLinking;
 
 /**
- * Detect the CLAUDE.md commit hash from branch structure when not available in session
+ * Detect the CLAUDE.md or .gitkeep commit hash from branch structure when not available in session
  * This handles continue mode where the commit hash was lost between sessions
  *
  * Safety checks to prevent Issue #617 (wrong commit revert):
  * 1. Only look at commits on the PR branch (not default branch commits)
  * 2. Verify the commit message matches our expected pattern
- * 3. Verify the commit ONLY adds CLAUDE.md (no other files changed)
+ * 3. Verify the commit ONLY adds CLAUDE.md or .gitkeep (no other files changed)
  * 4. Verify there are additional commits after it (actual work was done)
  *
  * @param {string} tempDir - The temporary directory with the git repo
@@ -57,12 +57,16 @@ const { hasGitHubLinkingKeyword } = githubLinking;
  */
 const detectClaudeMdCommitFromBranch = async (tempDir, branchName) => {
   try {
-    await log('   Attempting to detect CLAUDE.md commit from branch structure...', { verbose: true });
+    await log('   Attempting to detect CLAUDE.md or .gitkeep commit from branch structure...', { verbose: true });
 
-    // First check if CLAUDE.md exists in current branch
+    // First check if CLAUDE.md or .gitkeep exists in current branch
     const claudeMdExistsResult = await $({ cwd: tempDir })`git ls-files CLAUDE.md 2>&1`;
-    if (claudeMdExistsResult.code !== 0 || !claudeMdExistsResult.stdout || !claudeMdExistsResult.stdout.trim()) {
-      await log('   CLAUDE.md does not exist in current branch', { verbose: true });
+    const gitkeepExistsResult = await $({ cwd: tempDir })`git ls-files .gitkeep 2>&1`;
+    const claudeMdExists = claudeMdExistsResult.code === 0 && claudeMdExistsResult.stdout && claudeMdExistsResult.stdout.trim();
+    const gitkeepExists = gitkeepExistsResult.code === 0 && gitkeepExistsResult.stdout && gitkeepExistsResult.stdout.trim();
+
+    if (!claudeMdExists && !gitkeepExists) {
+      await log('   Neither CLAUDE.md nor .gitkeep exists in current branch', { verbose: true });
       return null;
     }
 
@@ -80,7 +84,7 @@ const detectClaudeMdCommitFromBranch = async (tempDir, branchName) => {
     // Find the merge base (fork point) between current branch and default branch
     const mergeBaseResult = await $({ cwd: tempDir })`git merge-base origin/${defaultBranch} HEAD 2>&1`;
     if (mergeBaseResult.code !== 0 || !mergeBaseResult.stdout) {
-      await log('   Could not find merge base, cannot safely detect CLAUDE.md commit', { verbose: true });
+      await log('   Could not find merge base, cannot safely detect initial commit', { verbose: true });
       return null;
     }
     const mergeBase = mergeBaseResult.stdout.toString().trim();
@@ -117,19 +121,19 @@ const detectClaudeMdCommitFromBranch = async (tempDir, branchName) => {
       verbose: true,
     });
 
-    // Safety check: Verify commit message matches expected pattern
-    const expectedMessagePatterns = [/^Initial commit with task details/i, /^Add CLAUDE\.md/i, /^CLAUDE\.md/i];
+    // Safety check: Verify commit message matches expected pattern (CLAUDE.md or .gitkeep)
+    const expectedMessagePatterns = [/^Initial commit with task details/i, /^Add CLAUDE\.md/i, /^CLAUDE\.md/i, /^Add \.gitkeep/i, /\.gitkeep/i];
 
     const messageMatches = expectedMessagePatterns.some(pattern => pattern.test(firstCommitMessage));
     if (!messageMatches) {
-      await log('   First commit message does not match expected CLAUDE.md pattern', { verbose: true });
-      await log('   Expected patterns: "Initial commit with task details...", "Add CLAUDE.md", etc.', {
+      await log('   First commit message does not match expected pattern', { verbose: true });
+      await log('   Expected patterns: "Initial commit with task details...", "Add CLAUDE.md", ".gitkeep", etc.', {
         verbose: true,
       });
       return null;
     }
 
-    // Safety check: Verify the commit ONLY adds CLAUDE.md file (no other files)
+    // Safety check: Verify the commit ONLY adds CLAUDE.md or .gitkeep file (no other files)
     const filesChangedResult = await $({
       cwd: tempDir,
     })`git diff-tree --no-commit-id --name-only -r ${firstCommitHash} 2>&1`;
@@ -141,16 +145,20 @@ const detectClaudeMdCommitFromBranch = async (tempDir, branchName) => {
     const filesChanged = filesChangedResult.stdout.toString().trim().split('\n').filter(Boolean);
     await log(`   Files changed in first commit: ${filesChanged.join(', ')}`, { verbose: true });
 
-    // Check if CLAUDE.md is in the files changed
-    if (!filesChanged.includes('CLAUDE.md')) {
-      await log('   First commit does not include CLAUDE.md', { verbose: true });
+    // Check if CLAUDE.md or .gitkeep is in the files changed
+    const hasClaudeMd = filesChanged.includes('CLAUDE.md');
+    const hasGitkeep = filesChanged.includes('.gitkeep');
+    if (!hasClaudeMd && !hasGitkeep) {
+      await log('   First commit does not include CLAUDE.md or .gitkeep', { verbose: true });
       return null;
     }
 
-    // CRITICAL SAFETY CHECK: Only allow revert if CLAUDE.md is the ONLY file changed
+    const targetFile = hasClaudeMd ? 'CLAUDE.md' : '.gitkeep';
+
+    // CRITICAL SAFETY CHECK: Only allow revert if the target file is the ONLY file changed
     // This prevents Issue #617 where reverting a commit deleted .gitignore, LICENSE, README.md
     if (filesChanged.length > 1) {
-      await log(`   ⚠️  First commit changes more than just CLAUDE.md (${filesChanged.length} files)`, {
+      await log(`   ⚠️  First commit changes more than just ${targetFile} (${filesChanged.length} files)`, {
         verbose: true,
       });
       await log(`   Files: ${filesChanged.join(', ')}`, { verbose: true });
@@ -159,81 +167,86 @@ const detectClaudeMdCommitFromBranch = async (tempDir, branchName) => {
     }
 
     // All safety checks passed!
-    await log(`   ✅ Detected CLAUDE.md commit: ${firstCommitHash.substring(0, 7)}`, { verbose: true });
-    await log('   ✅ Commit only contains CLAUDE.md (safe to revert)', { verbose: true });
+    await log(`   ✅ Detected ${targetFile} commit: ${firstCommitHash.substring(0, 7)}`, { verbose: true });
+    await log(`   ✅ Commit only contains ${targetFile} (safe to revert)`, { verbose: true });
     await log(`   ✅ Branch has ${branchCommits.length - 1} additional commit(s) (work was done)`, { verbose: true });
 
     return firstCommitHash;
   } catch (error) {
     reportError(error, {
-      context: 'detect_claude_md_commit',
+      context: 'detect_initial_commit',
       tempDir,
       branchName,
       operation: 'detect_commit_from_branch_structure',
     });
-    await log(`   Error detecting CLAUDE.md commit: ${error.message}`, { verbose: true });
+    await log(`   Error detecting initial commit: ${error.message}`, { verbose: true });
     return null;
   }
 };
 
-// Revert the CLAUDE.md commit to restore original state
+// Revert the CLAUDE.md or .gitkeep commit to restore original state
 export const cleanupClaudeFile = async (tempDir, branchName, claudeCommitHash = null) => {
   try {
     // If no commit hash provided, try to detect it from branch structure
     // This handles continue mode where the hash was lost between sessions
     if (!claudeCommitHash) {
-      await log('   No CLAUDE.md commit hash from session, attempting to detect from branch...', { verbose: true });
+      await log('   No initial commit hash from session, attempting to detect from branch...', { verbose: true });
       claudeCommitHash = await detectClaudeMdCommitFromBranch(tempDir, branchName);
 
       if (!claudeCommitHash) {
-        await log('   Could not safely detect CLAUDE.md commit to revert', { verbose: true });
+        await log('   Could not safely detect initial commit to revert', { verbose: true });
         return;
       }
-      await log(`   Detected CLAUDE.md commit: ${claudeCommitHash.substring(0, 7)}`, { verbose: true });
+      await log(`   Detected initial commit: ${claudeCommitHash.substring(0, 7)}`, { verbose: true });
     }
 
-    await log(formatAligned('🔄', 'Cleanup:', 'Reverting CLAUDE.md commit'));
+    // Determine which file was used based on the commit message or flags
+    // Check the commit message to determine which file was committed
+    const commitMsgResult = await $({ cwd: tempDir })`git log -1 --format=%s ${claudeCommitHash} 2>&1`;
+    const commitMsg = commitMsgResult.stdout?.trim() || '';
+    const isGitkeepFile = commitMsg.includes('.gitkeep');
+    const fileName = isGitkeepFile ? '.gitkeep' : 'CLAUDE.md';
+
+    await log(formatAligned('🔄', 'Cleanup:', `Reverting ${fileName} commit`));
     await log(`   Using saved commit hash: ${claudeCommitHash.substring(0, 7)}...`, { verbose: true });
 
     const commitToRevert = claudeCommitHash;
 
     // APPROACH 3: Check for modifications before reverting (proactive detection)
-    // This is the main strategy - detect if CLAUDE.md was modified after initial commit
-    await log('   Checking if CLAUDE.md was modified since initial commit...', { verbose: true });
-    const diffResult = await $({ cwd: tempDir })`git diff ${commitToRevert} HEAD -- CLAUDE.md 2>&1`;
+    // This is the main strategy - detect if the file was modified after initial commit
+    await log(`   Checking if ${fileName} was modified since initial commit...`, { verbose: true });
+    const diffResult = await $({ cwd: tempDir })`git diff ${commitToRevert} HEAD -- ${fileName} 2>&1`;
 
     if (diffResult.stdout && diffResult.stdout.trim()) {
-      // CLAUDE.md was modified after initial commit - use manual approach to avoid conflicts
-      await log('   CLAUDE.md was modified after initial commit, using manual cleanup...', { verbose: true });
+      // File was modified after initial commit - use manual approach to avoid conflicts
+      await log(`   ${fileName} was modified after initial commit, using manual cleanup...`, { verbose: true });
 
-      // Get the state of CLAUDE.md from before the initial commit (parent of the commit we're reverting)
+      // Get the state of the file from before the initial commit (parent of the commit we're reverting)
       const parentCommit = `${commitToRevert}~1`;
-      const parentFileExists = await $({ cwd: tempDir })`git cat-file -e ${parentCommit}:CLAUDE.md 2>&1`;
+      const parentFileExists = await $({ cwd: tempDir })`git cat-file -e ${parentCommit}:${fileName} 2>&1`;
 
       if (parentFileExists.code === 0) {
-        // CLAUDE.md existed before the initial commit - restore it to that state
-        await log('   CLAUDE.md existed before session, restoring to previous state...', { verbose: true });
-        await $({ cwd: tempDir })`git checkout ${parentCommit} -- CLAUDE.md`;
+        // File existed before the initial commit - restore it to that state
+        await log(`   ${fileName} existed before session, restoring to previous state...`, { verbose: true });
+        await $({ cwd: tempDir })`git checkout ${parentCommit} -- ${fileName}`;
       } else {
-        // CLAUDE.md didn't exist before the initial commit - delete it
-        await log('   CLAUDE.md was created in session, removing it...', { verbose: true });
-        await $({ cwd: tempDir })`git rm -f CLAUDE.md 2>&1`;
+        // File didn't exist before the initial commit - delete it
+        await log(`   ${fileName} was created in session, removing it...`, { verbose: true });
+        await $({ cwd: tempDir })`git rm -f ${fileName} 2>&1`;
       }
 
       // Create a manual revert commit
-      const commitResult = await $({
-        cwd: tempDir,
-      })`git commit -m "Revert: Remove CLAUDE.md changes from initial commit" 2>&1`;
+      const commitResult = await $({ cwd: tempDir })`git commit -m "Revert: Remove ${fileName} changes from initial commit" 2>&1`;
 
       if (commitResult.code === 0) {
-        await log(formatAligned('📦', 'Committed:', 'CLAUDE.md revert (manual)'));
+        await log(formatAligned('📦', 'Committed:', `${fileName} revert (manual)`));
 
         // Push the revert
         const pushRevertResult = await $({ cwd: tempDir })`git push origin ${branchName} 2>&1`;
         if (pushRevertResult.code === 0) {
-          await log(formatAligned('📤', 'Pushed:', 'CLAUDE.md revert to GitHub'));
+          await log(formatAligned('📤', 'Pushed:', `${fileName} revert to GitHub`));
         } else {
-          await log('   Warning: Could not push CLAUDE.md revert', { verbose: true });
+          await log(`   Warning: Could not push ${fileName} revert`, { verbose: true });
         }
       } else {
         await log('   Warning: Could not create manual revert commit', { verbose: true });
@@ -246,14 +259,14 @@ export const cleanupClaudeFile = async (tempDir, branchName, claudeCommitHash =
       // FALLBACK 1: Standard git revert
       const revertResult = await $({ cwd: tempDir })`git revert ${commitToRevert} --no-edit 2>&1`;
       if (revertResult.code === 0) {
-        await log(formatAligned('📦', 'Committed:', 'CLAUDE.md revert'));
+        await log(formatAligned('📦', 'Committed:', `${fileName} revert`));
 
         // Push the revert
         const pushRevertResult = await $({ cwd: tempDir })`git push origin ${branchName} 2>&1`;
         if (pushRevertResult.code === 0) {
-          await log(formatAligned('📤', 'Pushed:', 'CLAUDE.md revert to GitHub'));
+          await log(formatAligned('📤', 'Pushed:', `${fileName} revert to GitHub`));
         } else {
-          await log('   Warning: Could not push CLAUDE.md revert', { verbose: true });
+          await log(`   Warning: Could not push ${fileName} revert`, { verbose: true });
         }
       } else {
         // FALLBACK 2: Handle unexpected conflicts (three-way merge with automatic resolution)
@@ -267,24 +280,24 @@ export const cleanupClaudeFile = async (tempDir, branchName, claudeCommitHash =
           const statusResult = await $({ cwd: tempDir })`git status --short 2>&1`;
           const statusOutput = statusResult.stdout || '';
 
-          // Check if CLAUDE.md is in the conflict
-          if (statusOutput.includes('CLAUDE.md')) {
-            await log('   Resolving CLAUDE.md conflict by restoring pre-session state...', { verbose: true });
+          // Check if the file is in the conflict
+          if (statusOutput.includes(fileName)) {
+            await log(`   Resolving ${fileName} conflict by restoring pre-session state...`, { verbose: true });
 
-            // Get the state of CLAUDE.md from before the initial commit (parent of the commit we're reverting)
+            // Get the state of the file from before the initial commit (parent of the commit we're reverting)
             const parentCommit = `${commitToRevert}~1`;
-            const parentFileExists = await $({ cwd: tempDir })`git cat-file -e ${parentCommit}:CLAUDE.md 2>&1`;
+            const parentFileExists = await $({ cwd: tempDir })`git cat-file -e ${parentCommit}:${fileName} 2>&1`;
 
             if (parentFileExists.code === 0) {
-              // CLAUDE.md existed before the initial commit - restore it to that state
-              await log('   CLAUDE.md existed before session, restoring to previous state...', { verbose: true });
-              await $({ cwd: tempDir })`git checkout ${parentCommit} -- CLAUDE.md`;
-              // Stage the resolved CLAUDE.md
-              await $({ cwd: tempDir })`git add CLAUDE.md 2>&1`;
+              // File existed before the initial commit - restore it to that state
+              await log(`   ${fileName} existed before session, restoring to previous state...`, { verbose: true });
+              await $({ cwd: tempDir })`git checkout ${parentCommit} -- ${fileName}`;
+              // Stage the resolved file
+              await $({ cwd: tempDir })`git add ${fileName} 2>&1`;
             } else {
-              // CLAUDE.md didn't exist before the initial commit - delete it
-              await log('   CLAUDE.md was created in session, removing it...', { verbose: true });
-              await $({ cwd: tempDir })`git rm -f CLAUDE.md 2>&1`;
+              // File didn't exist before the initial commit - delete it
+              await log(`   ${fileName} was created in session, removing it...`, { verbose: true });
+              await $({ cwd: tempDir })`git rm -f ${fileName} 2>&1`;
               // No need to git add since git rm stages the deletion
             }
 
@@ -292,27 +305,27 @@ export const cleanupClaudeFile = async (tempDir, branchName, claudeCommitHash =
             const continueResult = await $({ cwd: tempDir })`git revert --continue --no-edit 2>&1`;
 
             if (continueResult.code === 0) {
-              await log(formatAligned('📦', 'Committed:', 'CLAUDE.md revert (conflict resolved)'));
+              await log(formatAligned('📦', 'Committed:', `${fileName} revert (conflict resolved)`));
 
               // Push the revert
               const pushRevertResult = await $({ cwd: tempDir })`git push origin ${branchName} 2>&1`;
               if (pushRevertResult.code === 0) {
-                await log(formatAligned('📤', 'Pushed:', 'CLAUDE.md revert to GitHub'));
+                await log(formatAligned('📤', 'Pushed:', `${fileName} revert to GitHub`));
               } else {
-                await log('   Warning: Could not push CLAUDE.md revert', { verbose: true });
+                await log(`   Warning: Could not push ${fileName} revert`, { verbose: true });
               }
             } else {
               await log('   Warning: Could not complete revert after conflict resolution', { verbose: true });
               await log(`   Continue output: ${continueResult.stderr || continueResult.stdout}`, { verbose: true });
             }
           } else {
-            // Conflict in some other file, not CLAUDE.md - this is unexpected
+            // Conflict in some other file, not expected file - this is unexpected
             await log('   Warning: Revert conflict in unexpected file(s), aborting revert', { verbose: true });
             await $({ cwd: tempDir })`git revert --abort 2>&1`;
           }
         } else {
           // Non-conflict error
-          await log('   Warning: Could not revert CLAUDE.md commit', { verbose: true });
+          await log(`   Warning: Could not revert ${fileName} commit`, { verbose: true });
           await log(`   Revert output: ${revertOutput}`, { verbose: true });
         }
       }
@@ -321,10 +334,10 @@ export const cleanupClaudeFile = async (tempDir, branchName, claudeCommitHash =
     reportError(e, {
       context: 'cleanup_claude_file',
       tempDir,
-      operation: 'revert_claude_md_commit',
+      operation: 'revert_initial_commit',
     });
     // If revert fails, that's okay - the task is still complete
-    await log('   CLAUDE.md revert failed or not needed', { verbose: true });
+    await log('   Initial commit revert failed or not needed', { verbose: true });
   }
 };
 

package/src/solve.validation.lib.mjs

@@ -42,7 +42,7 @@ const { reportError } = sentryLib;
 const { validateClaudeConnection } = claudeLib;
 
 // Wrapper function for disk space check using imported module
-const checkDiskSpace = async (minSpaceMB = 500) => {
+const checkDiskSpace = async (minSpaceMB = 2048) => {
   const result = await memoryCheck.checkDiskSpace(minSpaceMB, { log });
   return result.success;
 };
@@ -204,7 +204,7 @@ export const validateContinueOnlyOnFeedback = async (argv, isPrUrl, isIssueUrl)
 // Perform all system checks (disk space, memory, tool connection, GitHub permissions)
 // Note: skipToolConnection only skips the connection check, not model validation
 // Model validation should be done separately before calling this function
-export const performSystemChecks = async (minDiskSpace = 500, skipToolConnection = false, model = 'sonnet', argv = {}) => {
+export const performSystemChecks = async (minDiskSpace = 2048, skipToolConnection = false, model = 'sonnet', argv = {}) => {
   // Check disk space before proceeding
   const hasEnoughSpace = await checkDiskSpace(minDiskSpace);
   if (!hasEnoughSpace) {