@ginkoai/cli 2.0.6 → 2.1.1

package/dist/commands/start/start-reflection.js

@@ -14,15 +14,25 @@ import fs from 'fs-extra';
 import * as path from 'path';
 import chalk from 'chalk';
 import ora from 'ora';
+import readline from 'readline';
 import { getUserEmail, getGinkoDir, getProjectRoot } from '../../utils/helpers.js';
+import { checkForUpdatesAsync } from '../../utils/version-check.js';
 import { ActiveContextManager } from '../../services/active-context-manager.js';
 import { SessionLogManager } from '../../core/session-log-manager.js';
 import { SessionSynthesizer } from '../../utils/synthesis.js';
 import { loadContextStrategic, formatContextSummary } from '../../utils/context-loader.js';
 import { initializeQueue } from '../../lib/event-queue.js';
 import { loadSprintChecklist, formatSprintChecklist, formatCurrentTaskDetails, detectSprintProgression } from '../../lib/sprint-loader.js';
+import { loadStateCache, saveStateCache, checkCacheStaleness } from '../../lib/state-cache.js';
 import { formatHumanOutput, formatVerboseOutput, formatAIContextJSONL, formatTableOutput, formatEpicComplete, formatSprintProgressionPrompt } from '../../lib/output-formatter.js';
-import { getUserCurrentSprint, setUserCurrentSprint, createAssignmentFromFile, getSprintFileFromAssignment } from '../../lib/user-sprint.js';
+import { getUserCurrentSprint, setUserCurrentSprint, createAssignmentFromFile, getSprintFileFromAssignment, 
+// EPIC-016 Sprint 4: Structure detection (t01)
+checkWorkStructure, incrementAdhocSessionCount, resetAdhocSessionCount } from '../../lib/user-sprint.js';
+// EPIC-016 Sprint 4: Planning menu (t02)
+import { showPlanningMenu, routePlanningChoice } from '../../lib/planning-menu.js';
+// EPIC-016 Sprint 5: Adaptive coaching (t01, t03)
+import { getCoachingContext } from '../../lib/coaching-level.js';
+import { showTargetedCoaching } from '../../lib/targeted-coaching.js';
 import { GraphApiClient } from '../graph/api-client.js';
 import { isGraphInitialized, getGraphId } from '../graph/config.js';
 import { isAuthenticated } from '../../utils/auth-storage.js';
@@ -156,12 +166,231 @@ export class StartReflectionCommand extends ReflectionCommand {
             source: 'graph', // Mark source for debugging
         };
     }
+    /**
+     * Load sprint state from graph API with cache fallback (EPIC-015 Sprint 2 Task 3)
+     *
+     * Data flow:
+     * 1. Try to fetch from graph API first
+     * 2. On success: save to cache for offline use
+     * 3. On failure: load from cache
+     *
+     * @param graphId - The graph namespace ID
+     * @returns Sprint data and source indicator ('graph' | 'cache' | null)
+     */
+    async loadSprintStateFromGraph(graphId) {
+        const client = new GraphApiClient();
+        try {
+            // Try to fetch from graph API first
+            const graphResponse = await client.getActiveSprint(graphId);
+            // Convert API response to cache format
+            const activeSprintData = {
+                sprintId: graphResponse.sprint.id,
+                sprintName: graphResponse.sprint.name,
+                epicId: graphResponse.sprint.id.split('_s')[0] || 'unknown', // Extract epic from e011_s01
+                progress: {
+                    completed: graphResponse.stats.completedTasks,
+                    total: graphResponse.stats.totalTasks,
+                    percentage: graphResponse.stats.progressPercentage,
+                },
+                currentTask: graphResponse.nextTask ? {
+                    taskId: graphResponse.nextTask.id,
+                    taskName: graphResponse.nextTask.title,
+                    status: this.mapGraphStatusToTaskStatus(graphResponse.nextTask.status),
+                } : undefined,
+                nextTask: graphResponse.nextTask ? {
+                    taskId: graphResponse.nextTask.id,
+                    taskName: graphResponse.nextTask.title,
+                } : undefined,
+            };
+            // Save to cache for offline use
+            await saveStateCache(activeSprintData, graphId);
+            return {
+                data: activeSprintData,
+                source: 'graph',
+            };
+        }
+        catch (error) {
+            // Graph unavailable - try to load from cache
+            const cache = await loadStateCache();
+            if (cache && cache.graph_id === graphId) {
+                const staleness = checkCacheStaleness(cache);
+                return {
+                    data: cache.active_sprint,
+                    source: 'cache',
+                    staleness,
+                };
+            }
+            // No cache available
+            return {
+                data: null,
+                source: 'cache',
+            };
+        }
+    }
+    /**
+     * Load sprint data from cache only (for offline fallback)
+     */
+    async loadFromCacheOnly(graphId) {
+        const cache = await loadStateCache();
+        if (cache && cache.graph_id === graphId) {
+            const staleness = checkCacheStaleness(cache);
+            return {
+                data: cache.active_sprint,
+                staleness,
+            };
+        }
+        return { data: null };
+    }
+    /**
+     * Convert cached ActiveSprintData to SprintChecklist format
+     */
+    convertCachedDataToChecklist(cachedData) {
+        // Build minimal checklist from cached data
+        const tasks = [];
+        // If we have a current task, add it
+        if (cachedData.currentTask) {
+            tasks.push({
+                id: cachedData.currentTask.taskId,
+                title: cachedData.currentTask.taskName,
+                state: this.mapStatusToTaskState(cachedData.currentTask.status || 'todo'),
+            });
+        }
+        const completed = cachedData.progress?.completed || 0;
+        const total = cachedData.progress?.total || tasks.length;
+        return {
+            name: cachedData.sprintName || cachedData.sprintId,
+            file: '', // No file when loading from cache
+            tasks,
+            progress: {
+                complete: completed,
+                inProgress: cachedData.currentTask ? 1 : 0,
+                paused: 0,
+                todo: Math.max(0, total - completed - (cachedData.currentTask ? 1 : 0)),
+                total,
+            },
+            currentTask: cachedData.currentTask ? {
+                id: cachedData.currentTask.taskId,
+                title: cachedData.currentTask.taskName,
+                state: this.mapStatusToTaskState(cachedData.currentTask.status || 'todo'),
+            } : undefined,
+            recentCompletions: [],
+        };
+    }
+    /**
+     * Map graph API status string to TaskStatus enum
+     */
+    mapGraphStatusToTaskStatus(status) {
+        switch (status?.toLowerCase()) {
+            case 'complete':
+            case 'completed':
+                return 'completed';
+            case 'in_progress':
+            case 'in-progress':
+                return 'in_progress';
+            default:
+                return 'pending';
+        }
+    }
+    /**
+     * Map graph status to TaskState enum for SprintChecklist
+     */
+    mapStatusToTaskState(status) {
+        switch (status?.toLowerCase()) {
+            case 'complete':
+            case 'completed':
+                return 'complete';
+            case 'in_progress':
+            case 'in-progress':
+                return 'in_progress';
+            case 'paused':
+            case 'sleeping':
+                return 'paused';
+            case 'blocked':
+                return 'in_progress'; // Treat blocked as in_progress for display
+            default:
+                return 'todo';
+        }
+    }
+    /**
+     * Merge graph status with local file content (EPIC-015 Sprint 2 Task 3)
+     *
+     * Graph API is authoritative for STATUS (progress, task states).
+     * Local file provides CONTENT (descriptions, acceptance criteria, ADRs).
+     *
+     * @param graphData - Status data from graph API (or cache)
+     * @param fileContent - Content from local sprint file
+     * @returns Merged SprintChecklist with graph status + file content
+     */
+    mergeGraphStatusWithContent(graphData, fileContent, graphTasks) {
+        // Build task list: merge graph status with file content
+        const tasks = fileContent.tasks.map((fileTask) => {
+            // Find matching task in graph data
+            const graphTask = graphTasks?.find(gt => gt.id === fileTask.id);
+            const status = graphTask?.status || 'not_started';
+            return {
+                id: fileTask.id,
+                title: fileTask.title,
+                state: this.mapStatusToTaskState(status),
+                files: fileTask.files || graphTask?.files || [],
+                effort: fileTask.effort,
+                priority: fileTask.priority || graphTask?.priority,
+                relatedADRs: fileTask.relatedADRs,
+                relatedPatterns: fileTask.relatedPatterns,
+                relatedGotchas: fileTask.relatedGotchas,
+                acceptanceCriteria: fileTask.acceptanceCriteria,
+                dependsOn: fileTask.dependsOn,
+            };
+        });
+        // Calculate progress from graph data
+        const progress = {
+            complete: graphData.progress.completed,
+            inProgress: tasks.filter(t => t.state === 'in_progress').length,
+            paused: tasks.filter(t => t.state === 'paused').length,
+            todo: graphData.progress.total - graphData.progress.completed - tasks.filter(t => t.state === 'in_progress').length,
+            total: graphData.progress.total,
+        };
+        // Determine current task (first in_progress or first todo)
+        const currentTask = tasks.find(t => t.state === 'in_progress') ||
+            tasks.find(t => t.state === 'todo');
+        // Recent completions (completed tasks from the end of list)
+        const recentCompletions = tasks
+            .filter(t => t.state === 'complete')
+            .slice(-3);
+        return {
+            name: graphData.sprintName,
+            file: fileContent.file,
+            progress,
+            tasks,
+            currentTask,
+            recentCompletions,
+            dependencyWarnings: fileContent.dependencyWarnings,
+        };
+    }
     /**
      * Override execute to process handoff and display session info
      */
     async execute(intent, options = {}) {
-        const spinner = ora('Initializing session...').start();
+        // TTY detection with override for Claude Code (e014_s02_t03)
+        // Claude Code's terminal supports box-drawing and colors but reports isTTY=false
+        // Use GINKO_FORCE_TTY=1 to force TTY-like output in Claude Code
+        const forceTTY = process.env.GINKO_FORCE_TTY === '1' || process.env.GINKO_FORCE_TTY === 'true';
+        const isTTY = forceTTY || process.stdout.isTTY === true;
+        // Also force chalk colors when forcing TTY mode (chalk checks FORCE_COLOR env var)
+        if (forceTTY && !process.env.FORCE_COLOR) {
+            process.env.FORCE_COLOR = '1';
+        }
+        const spinner = ora({
+            text: 'Initializing session...',
+            isEnabled: isTTY,
+            isSilent: !isTTY, // Completely silence output in non-TTY mode
+        });
+        // Only start spinner animation in TTY mode
+        if (isTTY) {
+            spinner.start();
+        }
         try {
+            // 0. Start version check in background (non-blocking)
+            const versionCheckPromise = checkForUpdatesAsync();
             // 1. Parse intent
             const parsedIntent = this.parseIntent(intent);
             // 2. Initialize event queue for background sync (ADR-043)
@@ -188,24 +417,27 @@ export class StartReflectionCommand extends ReflectionCommand {
             const userSlug = userEmail.replace('@', '-at-').replace(/\./g, '-');
             const sessionDir = path.join(ginkoDir, 'sessions', userSlug);
             const projectRoot = await getProjectRoot();
-            // Load sprint checklist for session context
-            // Strategy: User sprint first, then local/graph
-            // EPIC-012: Per-user sprint tracking enables multiple users on different sprints
+            // Load sprint checklist for session context (EPIC-015 Sprint 2 Task 3)
+            // NEW DATA FLOW: Graph API is authoritative for STATUS, file provides CONTENT
+            // 1. Fetch status from graph API (with cache fallback)
+            // 2. Load content from local sprint file
+            // 3. Merge: graph status + file content
             let sprintChecklist = null;
             let sprintSource = 'local';
+            let isOffline = false;
+            let cacheAge;
+            let cacheStaleness;
             // First, check if user has a specific sprint assignment
-            const userSprint = await getUserCurrentSprint();
+            // EPIC-012: Per-user sprint tracking enables multiple users on different sprints
+            let userSprint = await getUserCurrentSprint();
             let userSprintLoaded = false;
+            let sprintFilePath;
             if (userSprint) {
                 try {
                     const userSprintFile = await getSprintFileFromAssignment(userSprint);
                     if (await fs.pathExists(userSprintFile)) {
-                        const userSprintChecklist = await loadSprintChecklist(projectRoot, userSprintFile);
-                        if (userSprintChecklist) {
-                            sprintChecklist = userSprintChecklist;
-                            sprintSource = 'user';
-                            userSprintLoaded = true;
-                        }
+                        sprintFilePath = userSprintFile;
+                        userSprintLoaded = true;
                     }
                 }
                 catch {
@@ -213,72 +445,86 @@ export class StartReflectionCommand extends ReflectionCommand {
                     // We'll fall back to global sprint
                 }
             }
-            // If no user sprint, load global sprint (CURRENT-SPRINT.md)
-            let localSprint = null;
-            if (!userSprintLoaded) {
-                localSprint = await loadSprintChecklist(projectRoot);
+            // Load sprint with graph-first status (EPIC-015 Sprint 2 Task 3)
+            const graphId = await isGraphInitialized() ? await getGraphId() : null;
+            const isGraphReady = await isAuthenticated() && graphId;
+            // When user has explicitly set a sprint (via `ginko sprint start`), respect that choice
+            // This ensures continuity - the user knows what they want to work on
+            if (userSprintLoaded && sprintFilePath && sprintFilePath.length > 0) {
+                // User has a local sprint file - load from file
+                spinner.text = 'Loading user-selected sprint...';
+                const localChecklist = await loadSprintChecklist(projectRoot, sprintFilePath);
+                if (localChecklist) {
+                    sprintChecklist = localChecklist;
+                    sprintSource = 'user';
+                }
             }
-            // Only check graph/local if user sprint wasn't already loaded
-            if (!userSprintLoaded) {
-                // Try to load from graph if authenticated
-                let graphSprint = null;
-                if (await isAuthenticated() && await isGraphInitialized()) {
-                    try {
-                        spinner.text = 'Checking graph for sprint updates...';
-                        const graphId = await getGraphId();
-                        if (graphId) {
-                            const client = new GraphApiClient();
-                            const graphResponse = await client.getActiveSprint(graphId);
-                            graphSprint = this.convertGraphSprintToChecklist(graphResponse);
-                        }
-                    }
-                    catch (error) {
-                        // Graph unavailable - use local only
-                        spinner.text = 'Graph unavailable, using local sprint file';
-                    }
+            else if (isGraphReady && graphId) {
+                // Fetch from graph - pass user's sprint preference if set (API will prioritize it)
+                spinner.text = 'Fetching sprint from graph...';
+                const client = new GraphApiClient();
+                try {
+                    // Pass user's sprint preference if set (API will prioritize it for continuity)
+                    const preferredSprintId = userSprint?.sprintId;
+                    const graphResponse = await client.getActiveSprint(graphId, preferredSprintId);
+                    sprintChecklist = this.convertGraphSprintToChecklist(graphResponse);
+                    sprintSource = 'graph';
+                    // Save to cache for offline fallback
+                    const activeSprintData = {
+                        sprintId: graphResponse.sprint.id,
+                        sprintName: graphResponse.sprint.name,
+                        epicId: graphResponse.sprint.id.split('_s')[0] || 'unknown',
+                        progress: {
+                            completed: graphResponse.stats.completedTasks,
+                            total: graphResponse.stats.totalTasks,
+                            percentage: graphResponse.stats.progressPercentage,
+                        },
+                        currentTask: graphResponse.nextTask ? {
+                            taskId: graphResponse.nextTask.id,
+                            taskName: graphResponse.nextTask.title,
+                            status: this.mapGraphStatusToTaskStatus(graphResponse.nextTask.status),
+                        } : undefined,
+                        nextTask: graphResponse.nextTask ? {
+                            taskId: graphResponse.nextTask.id,
+                            taskName: graphResponse.nextTask.title,
+                        } : undefined,
+                    };
+                    await saveStateCache(activeSprintData, graphId);
                 }
-                // Compare and choose the more complete/current sprint
-                // Priority: Local file is source of truth - it represents what the user is actively working on
-                // Graph data may be stale (e.g., still showing Sprint 1 when user moved to Sprint 2)
-                if (localSprint && graphSprint) {
-                    // If the sprints are different (different names), always use local
-                    // This handles the case where graph hasn't been synced with new sprint
-                    const localName = localSprint.name?.toLowerCase() || '';
-                    const graphName = graphSprint.name?.toLowerCase() || '';
-                    const sprintsAreDifferent = localName !== graphName &&
-                        !localName.includes(graphName) &&
-                        !graphName.includes(localName);
-                    if (sprintsAreDifferent) {
-                        // Local file is the source of truth for which sprint we're on
-                        sprintChecklist = localSprint;
-                        sprintSource = 'local';
+                catch (error) {
+                    // Graph unavailable - try cache fallback
+                    const { data: cachedData, staleness } = await this.loadFromCacheOnly(graphId);
+                    if (cachedData) {
+                        // Use cached data
+                        sprintChecklist = this.convertCachedDataToChecklist(cachedData);
+                        sprintSource = 'cache';
+                        isOffline = true;
+                        cacheAge = staleness?.ageHuman;
+                        cacheStaleness = staleness?.level;
+                        if (staleness?.showWarning) {
+                            spinner.text = `Using cached sprint (${staleness.ageHuman})`;
+                        }
                     }
                     else {
-                        // Same sprint - prefer local if it has more tasks OR higher completion count
-                        // This handles case where graph has stale/test data
-                        const localTotal = localSprint.progress?.total || 0;
-                        const graphTotal = graphSprint.progress?.total || 0;
-                        const localProgress = localSprint.progress?.complete || 0;
-                        const graphProgress = graphSprint.progress?.complete || 0;
-                        if (localTotal > graphTotal || localProgress > graphProgress) {
-                            sprintChecklist = localSprint;
+                        // No cache - fall back to local file (offline fallback only)
+                        spinner.text = 'Graph unavailable, using local sprint file';
+                        const localChecklist = await loadSprintChecklist(projectRoot, sprintFilePath);
+                        if (localChecklist) {
+                            sprintChecklist = localChecklist;
                             sprintSource = 'local';
-                        }
-                        else {
-                            sprintChecklist = graphSprint;
-                            sprintSource = 'graph';
+                            isOffline = true;
                         }
                     }
                 }
-                else if (localSprint) {
-                    sprintChecklist = localSprint;
-                    sprintSource = 'local';
-                }
-                else if (graphSprint) {
-                    sprintChecklist = graphSprint;
-                    sprintSource = 'graph';
+            }
+            else {
+                // Graph not initialized - use local file only
+                const localChecklist = await loadSprintChecklist(projectRoot, sprintFilePath);
+                if (localChecklist) {
+                    sprintChecklist = localChecklist;
+                    sprintSource = userSprintLoaded ? 'user' : 'local';
                 }
-            } // end if (!userSprintLoaded)
+            }
             // Load session log content before archiving
             const previousSessionLog = await SessionLogManager.loadSessionLog(sessionDir);
             const hasLog = previousSessionLog.length > 100; // Non-empty log
@@ -398,7 +644,8 @@ export class StartReflectionCommand extends ReflectionCommand {
             // Session logging status shown in table if needed
             // 11. Build AI context for dual output system (TASK-11)
             // Now async due to graph API enrichment (EPIC-002 Sprint 3 completion)
-            const aiContext = await this.buildAIContext(context, activeSynthesis, strategyContext, eventContext, sprintChecklist, isFirstTimeMember);
+            // EPIC-015 Sprint 2: Include offline status for display
+            const aiContext = await this.buildAIContext(context, activeSynthesis, strategyContext, eventContext, sprintChecklist, isFirstTimeMember, { isOffline, cacheAge, cacheStaleness });
             // Store AI context for MCP/external access
             await this.storeAIContext(aiContext, sessionDir);
             // 12. Check sprint progression and epic completion (EPIC-012 Sprint 1)
@@ -425,6 +672,42 @@ export class StartReflectionCommand extends ReflectionCommand {
             }
             // 13. Stop spinner before any output
             spinner.stop();
+            // EPIC-016 Sprint 4: Work Pattern Coaching - Structure Detection (t01) and Planning Menu (t02)
+            // Check if user has structured work (Epic→Sprint→Task). If not, show guided planning menu.
+            const structureStatus = checkWorkStructure(userSprint, sprintChecklist);
+            if (structureStatus.shouldShowPlanningMenu) {
+                // Show planning menu to guide user toward structured work
+                const menuResult = await showPlanningMenu(structureStatus);
+                if (menuResult.cancelled) {
+                    console.log(chalk.dim('Session start cancelled.'));
+                    return;
+                }
+                // Route the selection
+                const routeResult = await routePlanningChoice(menuResult.choice);
+                // Track adoption: ad-hoc vs structured choice
+                if (menuResult.choice === 'adhoc') {
+                    await incrementAdhocSessionCount();
+                }
+                else if (routeResult.success) {
+                    // User chose structured work - reset ad-hoc counter
+                    await resetAdhocSessionCount();
+                }
+                // Epic and sprint creation handle their own flow
+                if (!routeResult.shouldContinueStart) {
+                    return;
+                }
+                // For quick-fix and ad-hoc, update sprint info if a sprint was created
+                if (routeResult.sprintId) {
+                    userSprint = await getUserCurrentSprint();
+                    // Could refresh sprintChecklist from graph here if needed
+                }
+                console.log(''); // Spacing before normal output continues
+            }
+            // EPIC-016 Sprint 4: Check for unassigned tasks and prompt for bulk assignment (ADR-061)
+            // Per ADR-061: Work cannot be anonymous - prompt at sprint start for assignment
+            if (sprintChecklist && graphId) {
+                sprintChecklist = await this.checkAndPromptBulkAssignment(sprintChecklist, graphId, userEmail);
+            }
             // EPIC-008 Sprint 2: Check team context staleness (silent - no output)
             await this.checkTeamStaleness();
             // EPIC-004: Push real-time cursor update on session start
@@ -435,10 +718,32 @@ export class StartReflectionCommand extends ReflectionCommand {
             catch {
                 // Cursor update is non-critical - don't block session start
             }
+            // EPIC-016 Sprint 3: Record session start activity
+            try {
+                const activityGraphId = await getGraphId();
+                if (activityGraphId) {
+                    const activityClient = new GraphApiClient();
+                    await activityClient.recordActivity(activityGraphId, 'session_start');
+                }
+            }
+            catch {
+                // Activity tracking is non-critical - don't block session start
+            }
             // Auto-update insights at scheduled intervals (1-day, 7-day, 30-day)
             this.runScheduledInsights().catch(() => {
                 // Insights update is non-critical - don't block session start
             });
+            // EPIC-016 Sprint 5 t03: Show targeted coaching tips at session start
+            // Only show if we didn't just show the planning menu (which has its own coaching)
+            if (!structureStatus.shouldShowPlanningMenu) {
+                try {
+                    const coachingContext = await getCoachingContext(graphId || undefined);
+                    await showTargetedCoaching(coachingContext, 'start');
+                }
+                catch {
+                    // Coaching tips are non-critical - don't block session start
+                }
+            }
             // 14. Display output LAST (after all async operations complete)
             // Table view is the FINAL output - nothing should print after it
             if (options.verbose) {
@@ -456,6 +761,11 @@ export class StartReflectionCommand extends ReflectionCommand {
                     full: options.full
                 });
             }
+            // 15. Show update notification if available (non-blocking check completed)
+            const updateMessage = await versionCheckPromise;
+            if (updateMessage) {
+                console.log(updateMessage);
+            }
         }
         catch (error) {
             spinner.fail('Session initialization failed');
@@ -1252,7 +1562,7 @@ Example output structure:
      * Creates a rich, structured context object that AI partners can parse.
      * This is the "AI UX" side of the dual output system.
      */
-    async buildAIContext(context, synthesis, strategyContext, eventContext, sprintChecklist, isFirstTimeMember = false) {
+    async buildAIContext(context, synthesis, strategyContext, eventContext, sprintChecklist, isFirstTimeMember = false, offlineStatus) {
         const workMode = context.workMode || 'Think & Build';
         // Build sprint object
         let sprint;
@@ -1335,6 +1645,10 @@ Example output structure:
                 flowState: synthesis?.flowState?.energy || 'neutral',
                 workMode: workMode,
                 isFirstTimeMember,
+                // EPIC-015 Sprint 2: Offline status indicators
+                isOffline: offlineStatus?.isOffline,
+                cacheAge: offlineStatus?.cacheAge,
+                cacheStaleness: offlineStatus?.cacheStaleness,
             },
             charter: eventContext?.strategicContext?.charter,
             teamActivity: eventContext?.strategicContext?.teamActivity ? {
@@ -1459,6 +1773,85 @@ Example output structure:
             // Staleness check is non-critical - don't block session start
         }
     }
+    /**
+     * Check for unassigned tasks in the active sprint and prompt for bulk assignment
+     * Per ADR-061: Work cannot be anonymous - encourage assignment at sprint start
+     *
+     * @param sprintChecklist - Current sprint data with tasks
+     * @param graphId - Graph ID for API calls
+     * @param userEmail - Current user's email
+     * @returns Updated sprintChecklist if tasks were assigned
+     */
+    async checkAndPromptBulkAssignment(sprintChecklist, graphId, userEmail) {
+        // Skip if no sprint or no graph
+        if (!sprintChecklist || !graphId) {
+            return sprintChecklist;
+        }
+        // Count unassigned tasks from graph
+        const client = new GraphApiClient();
+        // Extract sprint ID from file or name, handling both formats:
+        // - e016_s04 (underscore - API format)
+        // - e016-s04 (hyphen - file naming format)
+        const sourceString = sprintChecklist.file || sprintChecklist.name || '';
+        const sprintIdMatch = sourceString.match(/e\d+[-_]s\d+/i);
+        if (!sprintIdMatch) {
+            return sprintChecklist;
+        }
+        // Normalize to underscore format for API calls
+        const sprintId = sprintIdMatch[0].replace('-', '_').toLowerCase();
+        try {
+            // Fetch tasks from graph to check assignee status
+            const tasks = await client.getTasks(graphId, { sprintId });
+            const unassignedTasks = tasks.filter(t => !t.assignee || t.assignee === '' || t.assignee === null);
+            if (unassignedTasks.length === 0) {
+                return sprintChecklist;
+            }
+            // Prompt user for bulk assignment (ADR-061)
+            console.log('');
+            console.log(chalk.yellow(`📋 ${unassignedTasks.length} unassigned ${unassignedTasks.length === 1 ? 'task' : 'tasks'} in sprint ${sprintId}`));
+            const shouldAssign = await this.promptConfirm(`Assign all to you (${userEmail})?`);
+            if (shouldAssign) {
+                // Bulk assign all tasks
+                const assignSpinner = ora({
+                    text: `Assigning ${unassignedTasks.length} tasks...`,
+                    isEnabled: process.stdout.isTTY || process.env.GINKO_FORCE_TTY === '1',
+                }).start();
+                try {
+                    // Update each task's assignee
+                    for (const task of unassignedTasks) {
+                        await client.request('PATCH', `/api/v1/graph/nodes/${encodeURIComponent(task.id)}?graphId=${encodeURIComponent(graphId)}`, { assignee: userEmail });
+                    }
+                    assignSpinner.succeed(chalk.green(`✓ Assigned ${unassignedTasks.length} tasks to ${userEmail}`));
+                }
+                catch (error) {
+                    assignSpinner.fail(chalk.red(`Failed to assign tasks: ${error.message}`));
+                }
+            }
+            else {
+                console.log(chalk.dim('  Skipped - tasks remain unassigned'));
+            }
+            console.log('');
+        }
+        catch {
+            // Non-blocking - if we can't check assignments, continue
+        }
+        return sprintChecklist;
+    }
+    /**
+     * Prompt user for yes/no confirmation
+     */
+    async promptConfirm(message) {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        return new Promise((resolve) => {
+            rl.question(`${message} [Y/n] `, (answer) => {
+                rl.close();
+                resolve(answer.toLowerCase() !== 'n');
+            });
+        });
+    }
     /**
      * Run scheduled insights updates in the background.
      * Checks which periods (1-day, 7-day, 30-day) need updates and runs them.