fix: add instruction size safeguard to prevent Copilot context overflow

Author: mohamedsedkiyouzbechi

CHANGELOG.md

@@ -8,6 +8,11 @@ All notable changes to the "promptitude" extension will be documented in this fi
 
 - Sync failure messages now distinguish **invalid repository URLs** (e.g. sub-paths like `/tree/main/...`) from **incompatible repository structures** (repo is reachable but has no supported prompt folders). The summary toast shows a categorised count, and "Show Details" lists the specific reason per repository.
 
+### Added
+
+- Instructions size safeguard: warns when active instructions (`.instructions.md`) may overwhelm GitHub Copilot's context window. Checks total instructions file size (>500 KB), active instructions count (>50), and repository count (>10) after each sync. Only instructions are counted since they are auto-loaded into context, unlike `.prompt.md` files which are invoked on-demand.
+- Disabled (inactive) prompts are now cleaned up from the active prompts directory during sync, preventing them from being loaded by Copilot.
+
 ## [1.5.4] - 2026-01-12
 
 ### Fixed

src/constant.ts

@@ -4,3 +4,9 @@ export const REPO_SYNC_CHAT_MODE_LEGACY_PATH = `chatmodes/`;
 export const REPO_SYNC_CHAT_MODE_LEGACY_SINGULAR_PATH = `chatmode/`;
 export const REPO_SYNC_INSTRUCTIONS_PATH = `instructions/`;
 export const REPO_SYNC_PROMPT_PATH = `prompts/`;
+
+// Instructions size safeguard thresholds
+/** Maximum total size (in bytes) of all active instructions before warning the user */
+export const INSTRUCTION_SIZE_WARNING_THRESHOLD_BYTES = 500 * 1024; // 500 KB
+/** Maximum number of active instructions before warning the user */
+export const INSTRUCTION_COUNT_WARNING_THRESHOLD = 50;

src/syncManager.ts

@@ -10,7 +10,7 @@ import { GitProviderFactory } from './utils/gitProviderFactory';
 import { FileSystemManager } from './utils/fileSystem';
 import { AzureDevOpsApiManager } from './utils/azureDevOps';
 import { PromptTreeDataProvider } from './ui/promptTreeProvider';
-import { REPO_SYNC_CHAT_MODE_PATH, REPO_SYNC_CHAT_MODE_LEGACY_PATH, REPO_SYNC_CHAT_MODE_LEGACY_SINGULAR_PATH, REPO_SYNC_INSTRUCTIONS_PATH, REPO_SYNC_PROMPT_PATH, } from './constant';
+import { REPO_SYNC_CHAT_MODE_PATH, REPO_SYNC_CHAT_MODE_LEGACY_PATH, REPO_SYNC_CHAT_MODE_LEGACY_SINGULAR_PATH, REPO_SYNC_INSTRUCTIONS_PATH, REPO_SYNC_PROMPT_PATH, INSTRUCTION_SIZE_WARNING_THRESHOLD_BYTES, INSTRUCTION_COUNT_WARNING_THRESHOLD, } from './constant';
 export interface SyncResult {
     success: boolean;
     itemsUpdated: number;
@@ -102,12 +102,18 @@ export class SyncManager {
             // Recreate symlinks for active prompts (in case they were manually deleted)
             await this.recreateActivePromptSymlinks();
 
+            // Remove disabled prompts from the active prompts directory
+            await this.cleanupInactivePrompts();
+
             // Clean up orphaned regular files in prompts directory
             const cleanup = await this.cleanupOrphanedPrompts();
             if (cleanup.removed > 0) {
                 this.logger.info(`Cleaned up ${cleanup.removed} orphaned prompt files`);
             }
 
+            // Validate total instruction size to prevent Copilot context overflow
+            await this.validateInstructionSize();
+
             // Update status based on overall result
             if (result.overallSuccess) {
                 this.statusBar.setStatus(SyncStatus.Success);
@@ -289,7 +295,8 @@ export class SyncManager {
                 }
 
                 const filePath = this.fileSystem.joinPath(promptsDir, fileName);
-                const matchingPrompt = allPrompts.find(prompt => prompt.name === fileName);
+                // Match on both prompt.name and prompt.workspaceName to handle disambiguated files (e.g., prompt@org-repo.md)
+                const matchingPrompt = allPrompts.find(prompt => prompt.name === fileName || prompt.workspaceName === fileName);
 
                 // Remove file if prompt exists but is not active
                 if (matchingPrompt && !matchingPrompt.active) {
@@ -1290,6 +1297,60 @@ export class SyncManager {
         }
     }
 
+    /**
+     * Validate total instructions size and count, warning the user if thresholds are exceeded.
+     * Instructions (.instructions.md) are automatically loaded into Copilot's context window,
+     * unlike .prompt.md files which are invoked on-demand.
+     */
+    private async validateInstructionSize(): Promise<void> {
+        try {
+            const promptsDir = this.config.getPromptsDirectory();
+
+            // Ensure the prompts directory exists
+            await this.fileSystem.ensureDirectoryExists(promptsDir);
+
+            const entries = await this.fileSystem.readDirectory(promptsDir);
+            // Only count instructions files — they are auto-loaded into Copilot's context
+            const instructionFiles = entries.filter(f => f.endsWith('.instructions.md'));
+            const activeCount = instructionFiles.length;
+
+            // Calculate total size of active instruction files
+            let totalSize = 0;
+
+            for (const file of instructionFiles) {
+                try {
+                    const filePath = this.fileSystem.joinPath(promptsDir, file);
+                    totalSize += await this.fileSystem.getFileSize(filePath);
+                } catch {
+                    this.logger.debug(`Skipped unreadable instruction file: ${file}`);
+                }
+            }
+
+            const totalSizeKB = totalSize / 1024;
+            const reasons: string[] = [];
+
+            if (totalSize > INSTRUCTION_SIZE_WARNING_THRESHOLD_BYTES) {
+                reasons.push(`total size (${totalSizeKB.toFixed(0)} KB) exceeds ${(INSTRUCTION_SIZE_WARNING_THRESHOLD_BYTES / 1024).toFixed(0)} KB`);
+            }
+            if (activeCount > INSTRUCTION_COUNT_WARNING_THRESHOLD) {
+                reasons.push(`${activeCount} active instructions exceeds limit of ${INSTRUCTION_COUNT_WARNING_THRESHOLD}`);
+            }
+
+            if (reasons.length > 0) {
+                this.logger.warn(`Instructions size safeguard triggered: ${reasons.join('; ')}`);
+                await this.notifications.showPromptSizeWarning({
+                    totalSizeKB,
+                    activeCount,
+                    reasons
+                });
+            } else {
+                this.logger.debug(`Instructions size check passed: ${activeCount} instructions, ${totalSizeKB.toFixed(1)} KB`);
+            }
+        } catch (error) {
+            this.logger.error('Failed to validate prompt size', error instanceof Error ? error : undefined);
+        }
+    }
+
     dispose(): void {
         this.logger.info('Disposing SyncManager...');
 

src/utils/fileSystem.ts

@@ -58,6 +58,10 @@ export class FileSystemManager {
         }
     }
 
+    async getFileSize(filePath: string): Promise<number> {
+        const stats = await stat(filePath);
+        return stats.size;
+    }
 
     joinPath(...paths: string[]): string {
         return path.join(...paths);

src/utils/notifications.ts

@@ -182,4 +182,27 @@ export class NotificationManager {
             await this.showError(`Failed to setup Azure DevOps authentication: ${errorMessage}`);
         }
     }
+
+    /**
+     * Show a warning when the total instructions size or count exceeds safe thresholds.
+     * Instructions are auto-loaded into Copilot's context, unlike prompts which are on-demand.
+     */
+    async showPromptSizeWarning(details: { totalSizeKB: number; activeCount: number; reasons: string[] }): Promise<void> {
+        const reasonText = details.reasons.join('; ');
+        const message = `⚠️ Promptitude: Your active instructions may be too large for GitHub Copilot's context window (${details.totalSizeKB.toFixed(0)} KB across ${details.activeCount} instructions). ${reasonText}. Consider disabling unused instructions.`;
+
+        // Always show this warning regardless of notification settings — it's a safeguard
+        const result = await vscode.window.showWarningMessage(
+            message,
+            'Manage Prompts',
+            'Open Settings',
+            'Dismiss'
+        );
+
+        if (result === 'Manage Prompts') {
+            vscode.commands.executeCommand('promptitude.cards.focus');
+        } else if (result === 'Open Settings') {
+            vscode.commands.executeCommand('workbench.action.openSettings', 'promptitude');
+        }
+    }
 }