@ginkoai/cli 2.0.6 → 2.1.0

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

@@ -21,6 +21,7 @@ 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 { GraphApiClient } from '../graph/api-client.js';
@@ -156,11 +157,222 @@ 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();
+        // Disable spinner in non-TTY mode (e.g., Claude Code) to prevent output pollution
+        // The table output will be the only visible output
+        const isTTY = process.stdout.isTTY === true;
+        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 {
             // 1. Parse intent
             const parsedIntent = this.parseIntent(intent);
@@ -188,24 +400,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
+            // EPIC-012: Per-user sprint tracking enables multiple users on different sprints
             const 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 +428,74 @@ 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);
-            }
-            // 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';
-                    }
+            // Load sprint with graph-first status (EPIC-015 Sprint 2 Task 3)
+            const graphId = await isGraphInitialized() ? await getGraphId() : null;
+            const isGraphReady = await isAuthenticated() && graphId;
+            if (isGraphReady && graphId) {
+                // Graph-only approach: fetch state directly from graph API (EPIC-015 Sprint 3)
+                // No local file loading - graph is authoritative for STATE
+                spinner.text = 'Fetching sprint from graph...';
+                const client = new GraphApiClient();
+                try {
+                    const graphResponse = await client.getActiveSprint(graphId);
+                    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 +615,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)
@@ -1252,7 +1470,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 +1553,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 ? {