@ginkoai/cli 2.4.4 → 2.5.0

package/dist/lib/resumption-brief.js

@@ -0,0 +1,344 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2026-02-05
+ * @tags: [resumption-brief, context-synthesis, session-start, epic-018]
+ * @related: [context-loader-events.ts, ../commands/start/start-reflection.ts]
+ * @priority: critical
+ * @complexity: medium
+ * @dependencies: [context-loader-events.ts]
+ */
+/**
+ * Synthesize a resumption brief from loaded context (EPIC-018 Sprint 1 t01)
+ *
+ * Takes the raw events from LoadedContext and produces a structured
+ * ResumptionBrief that AI assistants can use to understand session state.
+ *
+ * @param context - Loaded context from event stream
+ * @param options - Synthesis options
+ * @returns Synthesized resumption brief
+ */
+export function synthesizeResumptionBrief(context, options = {}) {
+    const { maxEvents = 50, maxFiles = 10, includeTeam = false } = options;
+    // Combine events (my events + optionally team events)
+    const allEvents = includeTeam && context.teamEvents
+        ? [...context.myEvents, ...context.teamEvents]
+        : context.myEvents;
+    // Sort by timestamp descending (most recent first)
+    const sortedEvents = [...allEvents]
+        .sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime())
+        .slice(0, maxEvents);
+    // Extract components
+    const summary = generateSessionSummary(sortedEvents);
+    const stoppingPoint = findStoppingPoint(sortedEvents);
+    const openQuestions = extractOpenQuestions(sortedEvents);
+    const filesModified = extractFilesTouched(sortedEvents, maxFiles);
+    const duration = calculateSessionDuration(sortedEvents);
+    const decisions = extractDecisions(sortedEvents);
+    const insights = extractInsights(sortedEvents);
+    return {
+        lastSession: {
+            summary,
+            stoppingPoint,
+            openQuestions,
+            filesModified,
+            duration
+        },
+        decisions,
+        insights,
+        synthesizedAt: new Date(),
+        eventCount: sortedEvents.length
+    };
+}
+/**
+ * Generate a summary of the session work (t01)
+ *
+ * Analyzes events to produce a concise summary like:
+ * "Renamed settings panel, investigating API"
+ */
+function generateSessionSummary(events) {
+    if (events.length === 0) {
+        return 'No recent session activity';
+    }
+    // Group events by category
+    const features = events.filter(e => e.category === 'feature');
+    const fixes = events.filter(e => e.category === 'fix');
+    const achievements = events.filter(e => e.category === 'achievement');
+    const summaryParts = [];
+    // Prioritize achievements (completed work)
+    if (achievements.length > 0) {
+        const recentAchievement = achievements[0];
+        summaryParts.push(truncateDescription(recentAchievement.description, 50));
+    }
+    // Add feature work
+    if (features.length > 0 && summaryParts.length < 2) {
+        const recentFeature = features[0];
+        const prefix = summaryParts.length > 0 ? 'working on' : '';
+        const desc = truncateDescription(recentFeature.description, 40);
+        summaryParts.push(prefix ? `${prefix} ${desc}` : desc);
+    }
+    // Add fix work
+    if (fixes.length > 0 && summaryParts.length < 2) {
+        const recentFix = fixes[0];
+        const prefix = summaryParts.length > 0 ? 'fixing' : '';
+        const desc = truncateDescription(recentFix.description, 40);
+        summaryParts.push(prefix ? `${prefix} ${desc}` : desc);
+    }
+    // Fallback to most recent event
+    if (summaryParts.length === 0) {
+        summaryParts.push(truncateDescription(events[0].description, 60));
+    }
+    return summaryParts.join(', ');
+}
+/**
+ * Find where work stopped (t01)
+ *
+ * Looks at the most recent events to determine the stopping point.
+ * Returns something like: "Checking if 'team' appears in API responses"
+ */
+function findStoppingPoint(events) {
+    if (events.length === 0) {
+        return 'No stopping point identified';
+    }
+    // Most recent non-git event is typically where work stopped
+    const workEvents = events.filter(e => e.category !== 'git' &&
+        e.category !== 'achievement' // Achievements are completed, not stopping points
+    );
+    if (workEvents.length === 0) {
+        // If only git/achievements, last event was probably a commit
+        const lastEvent = events[0];
+        if (lastEvent.category === 'git') {
+            return `Last commit: ${truncateDescription(lastEvent.description, 60)}`;
+        }
+        if (lastEvent.category === 'achievement') {
+            return `Completed: ${truncateDescription(lastEvent.description, 60)}`;
+        }
+        return truncateDescription(lastEvent.description, 60);
+    }
+    const stoppingEvent = workEvents[0];
+    // Add file context if available
+    if (stoppingEvent.files && stoppingEvent.files.length > 0) {
+        const mainFile = stoppingEvent.files[0];
+        const fileName = mainFile.split('/').pop() || mainFile;
+        return `${truncateDescription(stoppingEvent.description, 50)} (in ${fileName})`;
+    }
+    return truncateDescription(stoppingEvent.description, 60);
+}
+/**
+ * Extract open questions from events (EPIC-018 Sprint 1 t03)
+ *
+ * Looks for decision/insight events with high impact that might indicate
+ * unresolved questions. Also parses descriptions for question patterns.
+ */
+function extractOpenQuestions(events) {
+    const questions = [];
+    const seenQuestions = new Set();
+    for (const event of events) {
+        // Look for explicit questions in descriptions
+        const questionPatterns = [
+            /\?$/, // Ends with question mark
+            /should we/i,
+            /need to decide/i,
+            /unclear/i,
+            /not sure/i,
+            /question:/i,
+            /todo:/i,
+            /tbd/i,
+            /investigate/i,
+            /figure out/i
+        ];
+        const hasQuestionIndicator = questionPatterns.some(pattern => pattern.test(event.description));
+        // High-impact decisions might indicate open questions
+        const isHighImpactDecision = event.category === 'decision' &&
+            event.impact === 'high';
+        // Insights with uncertainty might be open questions
+        const isUncertainInsight = event.category === 'insight' &&
+            (event.description.toLowerCase().includes('maybe') ||
+                event.description.toLowerCase().includes('might') ||
+                event.description.toLowerCase().includes('could'));
+        if (hasQuestionIndicator || isHighImpactDecision || isUncertainInsight) {
+            // Extract the question or create one from the description
+            let question = event.description;
+            // Clean up the question
+            if (!question.endsWith('?')) {
+                // Convert statement to question if needed
+                if (question.toLowerCase().startsWith('should we')) {
+                    question = question + '?';
+                }
+                else if (question.toLowerCase().includes('need to decide')) {
+                    question = question.replace(/need to decide/i, 'Decision needed:');
+                }
+            }
+            // Deduplicate
+            const normalizedQuestion = question.toLowerCase().trim();
+            if (!seenQuestions.has(normalizedQuestion)) {
+                seenQuestions.add(normalizedQuestion);
+                questions.push(truncateDescription(question, 100));
+            }
+        }
+    }
+    return questions.slice(0, 5); // Limit to 5 questions
+}
+/**
+ * Extract files touched from events (EPIC-018 Sprint 1 t02)
+ *
+ * Collects unique files from event.files arrays and returns them
+ * sorted by frequency (most touched first).
+ */
+function extractFilesTouched(events, maxFiles) {
+    const fileCount = new Map();
+    for (const event of events) {
+        if (event.files && Array.isArray(event.files)) {
+            for (const file of event.files) {
+                if (file && typeof file === 'string') {
+                    const count = fileCount.get(file) || 0;
+                    fileCount.set(file, count + 1);
+                }
+            }
+        }
+    }
+    // Sort by frequency (most touched first)
+    const sortedFiles = Array.from(fileCount.entries())
+        .sort((a, b) => b[1] - a[1])
+        .map(([file]) => file);
+    return sortedFiles.slice(0, maxFiles);
+}
+/**
+ * Calculate session duration from events (t01)
+ *
+ * Returns human-readable duration like "2h 15m"
+ */
+function calculateSessionDuration(events) {
+    if (events.length < 2) {
+        return 'Unknown';
+    }
+    // Events are sorted descending (most recent first)
+    const mostRecent = new Date(events[0].timestamp);
+    const oldest = new Date(events[events.length - 1].timestamp);
+    const durationMs = mostRecent.getTime() - oldest.getTime();
+    const durationMinutes = Math.round(durationMs / (1000 * 60));
+    if (durationMinutes < 1) {
+        return 'Less than 1 minute';
+    }
+    else if (durationMinutes < 60) {
+        return `${durationMinutes}m`;
+    }
+    else {
+        const hours = Math.floor(durationMinutes / 60);
+        const minutes = durationMinutes % 60;
+        return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+    }
+}
+/**
+ * Extract decisions from events (t01)
+ */
+function extractDecisions(events) {
+    return events
+        .filter(e => e.category === 'decision')
+        .map(e => ({
+        description: e.description,
+        timestamp: new Date(e.timestamp)
+    }))
+        .slice(0, 5); // Limit to 5 most recent
+}
+/**
+ * Extract insights from events (t01)
+ */
+function extractInsights(events) {
+    return events
+        .filter(e => e.category === 'insight')
+        .map(e => ({
+        description: e.description,
+        timestamp: new Date(e.timestamp)
+    }))
+        .slice(0, 5); // Limit to 5 most recent
+}
+/**
+ * Helper: Truncate description to max length with ellipsis
+ */
+function truncateDescription(description, maxLength) {
+    if (description.length <= maxLength) {
+        return description;
+    }
+    return description.substring(0, maxLength - 3) + '...';
+}
+/**
+ * Format resumption brief for human display
+ *
+ * Converts the structured brief into a readable format.
+ */
+export function formatResumptionBrief(brief) {
+    const lines = [];
+    lines.push('=== Resumption Brief ===');
+    lines.push('');
+    // Last session summary
+    lines.push(`Summary: ${brief.lastSession.summary}`);
+    lines.push(`Stopping point: ${brief.lastSession.stoppingPoint}`);
+    lines.push(`Duration: ${brief.lastSession.duration}`);
+    lines.push('');
+    // Files modified
+    if (brief.lastSession.filesModified.length > 0) {
+        lines.push('Files touched:');
+        for (const file of brief.lastSession.filesModified.slice(0, 5)) {
+            lines.push(`  - ${file}`);
+        }
+        if (brief.lastSession.filesModified.length > 5) {
+            lines.push(`  ... and ${brief.lastSession.filesModified.length - 5} more`);
+        }
+        lines.push('');
+    }
+    // Open questions
+    if (brief.lastSession.openQuestions.length > 0) {
+        lines.push('Open questions:');
+        for (const question of brief.lastSession.openQuestions) {
+            lines.push(`  ? ${question}`);
+        }
+        lines.push('');
+    }
+    // Decisions
+    if (brief.decisions.length > 0) {
+        lines.push('Recent decisions:');
+        for (const decision of brief.decisions.slice(0, 3)) {
+            lines.push(`  - ${decision.description}`);
+        }
+        lines.push('');
+    }
+    // Insights
+    if (brief.insights.length > 0) {
+        lines.push('Insights:');
+        for (const insight of brief.insights.slice(0, 3)) {
+            lines.push(`  - ${insight.description}`);
+        }
+        lines.push('');
+    }
+    lines.push(`Analyzed ${brief.eventCount} events`);
+    return lines.join('\n');
+}
+/**
+ * Format resumption brief for AI context (JSONL entry)
+ *
+ * Returns a structured object suitable for AI consumption.
+ */
+export function formatResumptionBriefForAI(brief) {
+    return {
+        type: 'resumption_brief',
+        timestamp: brief.synthesizedAt.toISOString(),
+        lastSession: {
+            summary: brief.lastSession.summary,
+            stoppingPoint: brief.lastSession.stoppingPoint,
+            openQuestions: brief.lastSession.openQuestions,
+            filesModified: brief.lastSession.filesModified,
+            duration: brief.lastSession.duration
+        },
+        decisions: brief.decisions.map(d => ({
+            description: d.description,
+            timestamp: d.timestamp.toISOString()
+        })),
+        insights: brief.insights.map(i => ({
+            description: i.description,
+            timestamp: i.timestamp.toISOString()
+        })),
+        eventCount: brief.eventCount
+    };
+}
+//# sourceMappingURL=resumption-brief.js.map

package/dist/lib/resumption-brief.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resumption-brief.js","sourceRoot":"","sources":["../../src/lib/resumption-brief.ts"],"names":[],"mappings":"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"}

package/dist/lib/staleness-detector.js

@@ -166,7 +166,7 @@ export function displayStalenessWarning(result) {
         }
     }
     console.log('');
-    console.log(chalk.dim('   Run `ginko sync` to pull team updates.'));
+    console.log(chalk.dim('   Run `ginko pull` to pull team updates.'));
     console.log('');
 }
 // =============================================================================

package/dist/lib/state-cache.d.ts

@@ -123,6 +123,49 @@ export declare function checkCacheStaleness(cache: StateCache): CacheStalenessRe
  * ```
  */
 export declare function formatCacheAge(fetchedAt: string): string;
+/**
+ * Load cached state only if it's fresh (< 5 minutes old)
+ * Returns null if cache is stale or doesn't exist
+ *
+ * This enables cache-first loading for faster startup:
+ * 1. Check cache - if fresh, return immediately (0ms network)
+ * 2. If stale/missing, fetch from API and update cache
+ *
+ * @param graphId - Graph ID to match against cached data
+ * @returns Fresh cache data or null if stale/missing
+ *
+ * @example
+ * ```typescript
+ * // Cache-first pattern in start-reflection.ts:
+ * const cached = await loadFreshCache(graphId);
+ * if (cached) {
+ *   return cached; // Skip API call, use cache
+ * }
+ * // Cache miss/stale - fetch from API
+ * const fresh = await fetchFromApi();
+ * await saveStateCache(fresh, graphId);
+ * ```
+ */
+export declare function loadFreshCache(graphId: string): Promise<ActiveSprintData | null>;
+/**
+ * Try to load from cache first, falling back to API call
+ * Automatically updates cache on successful API fetch
+ *
+ * @param graphId - Graph namespace identifier
+ * @param fetchFn - Function to call if cache is stale/missing
+ * @returns Sprint data from cache or fresh API call
+ *
+ * @example
+ * ```typescript
+ * const data = await loadWithCacheFallback(graphId, async () => {
+ *   return await client.getActiveSprint(graphId);
+ * });
+ * ```
+ */
+export declare function loadWithCacheFallback(graphId: string, fetchFn: () => Promise<ActiveSprintData>): Promise<{
+    data: ActiveSprintData;
+    source: 'cache' | 'api';
+}>;
 /**
  * Get the full path to the cache file
  */

package/dist/lib/state-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-cache.d.ts","sourceRoot":"","sources":["../../src/lib/state-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAsBH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE;QACR,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,WAAW,CAAC,EAAE;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC;KACjD,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,gBAAgB,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;CACtB;AAiBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAoBjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAUrD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,oBAAoB,CAsB3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAwBxD;AAMD;;GAEG;AACH,iBAAe,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAG7C;AAED;;GAEG;AACH,iBAAS,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,UAAU,CAsCvD;AAMD,eAAO,MAAM,SAAS;;;;;;CAMrB,CAAC"}
+{"version":3,"file":"state-cache.d.ts","sourceRoot":"","sources":["../../src/lib/state-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAsBH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE;QACR,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,WAAW,CAAC,EAAE;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC;KACjD,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,gBAAgB,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;CACtB;AAiBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAoBjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAUrD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,oBAAoB,CAsB3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAwBxD;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAoBtF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,GACvC,OAAO,CAAC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,OAAO,GAAG,KAAK,CAAA;CAAE,CAAC,CAgB9D;AAMD;;GAEG;AACH,iBAAe,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAG7C;AAED;;GAEG;AACH,iBAAS,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,UAAU,CAsCvD;AAMD,eAAO,MAAM,SAAS;;;;;;CAMrB,CAAC"}

package/dist/lib/state-cache.js

@@ -203,6 +203,78 @@ export function formatCacheAge(fetchedAt) {
     return date.toLocaleDateString();
 }
 // =============================================================================
+// EPIC-018 Sprint 1 TASK-04: Cache-First Optimization
+// =============================================================================
+/**
+ * Load cached state only if it's fresh (< 5 minutes old)
+ * Returns null if cache is stale or doesn't exist
+ *
+ * This enables cache-first loading for faster startup:
+ * 1. Check cache - if fresh, return immediately (0ms network)
+ * 2. If stale/missing, fetch from API and update cache
+ *
+ * @param graphId - Graph ID to match against cached data
+ * @returns Fresh cache data or null if stale/missing
+ *
+ * @example
+ * ```typescript
+ * // Cache-first pattern in start-reflection.ts:
+ * const cached = await loadFreshCache(graphId);
+ * if (cached) {
+ *   return cached; // Skip API call, use cache
+ * }
+ * // Cache miss/stale - fetch from API
+ * const fresh = await fetchFromApi();
+ * await saveStateCache(fresh, graphId);
+ * ```
+ */
+export async function loadFreshCache(graphId) {
+    const cache = await loadStateCache();
+    // No cache exists
+    if (!cache) {
+        return null;
+    }
+    // Cache is for a different graph
+    if (cache.graph_id !== graphId) {
+        return null;
+    }
+    // Check if cache is fresh
+    const staleness = checkCacheStaleness(cache);
+    if (!staleness.isFresh) {
+        return null;
+    }
+    return cache.active_sprint;
+}
+/**
+ * Try to load from cache first, falling back to API call
+ * Automatically updates cache on successful API fetch
+ *
+ * @param graphId - Graph namespace identifier
+ * @param fetchFn - Function to call if cache is stale/missing
+ * @returns Sprint data from cache or fresh API call
+ *
+ * @example
+ * ```typescript
+ * const data = await loadWithCacheFallback(graphId, async () => {
+ *   return await client.getActiveSprint(graphId);
+ * });
+ * ```
+ */
+export async function loadWithCacheFallback(graphId, fetchFn) {
+    // Try cache first
+    const cached = await loadFreshCache(graphId);
+    if (cached) {
+        return { data: cached, source: 'cache' };
+    }
+    // Cache miss - fetch from API
+    const fresh = await fetchFn();
+    // Update cache in background (don't await)
+    saveStateCache(fresh, graphId).catch(() => {
+        // Ignore cache save errors - non-critical
+    });
+    return { data: fresh, source: 'api' };
+}
+// =============================================================================
 // Helper Functions
 // =============================================================================
 /**

package/dist/lib/state-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"state-cache.js","sourceRoot":"","sources":["../../src/lib/state-cache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"state-cache.js","sourceRoot":"","sources":["../../src/lib/state-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,MAAM,UAAU,CAAC;AAC1B,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAmDlD,gFAAgF;AAChF,YAAY;AACZ,gFAAgF;AAEhF,MAAM,UAAU,GAAG,kBAAkB,CAAC;AACtC,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,uCAAuC;AACvC,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAM,YAAY;AAC3D,MAAM,oBAAoB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,WAAW;AAE7D,gFAAgF;AAChF,WAAW;AACX,gFAAgF;AAEhF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,YAAY,EAAE,CAAC;QAEvC,IAAI,CAAC,MAAM,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACpC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAE1C,6CAA6C;QAC7C,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,IAAkB,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,2DAA2D;QAC3D,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAsB,EACtB,OAAe;IAEf,MAAM,SAAS,GAAG,MAAM,YAAY,EAAE,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,GAAG,SAAS,QAAQ,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IAElD,iCAAiC;IACjC,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAE7B,MAAM,KAAK,GAAe;QACxB,OAAO,EAAE,aAAa;QACtB,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,QAAQ,EAAE,OAAO;QACjB,aAAa,EAAE,IAAI;KACpB,CAAC;IAEF,gDAAgD;IAChD,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;QACnD,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,sCAAsC;QACtC,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,wBAAwB;QAC1B,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,YAAY,EAAE,CAAC;QAEvC,IAAI,MAAM,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACnC,MAAM,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,oCAAoC;IACtC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAiB;IACnD,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC;IAElD,IAAI,KAAoC,CAAC;IAEzC,IAAI,KAAK,GAAG,kBAAkB,EAAE,CAAC;QAC/B,KAAK,GAAG,OAAO,CAAC;IAClB,CAAC;SAAM,IAAI,KAAK,GAAG,oBAAoB,EAAE,CAAC;QACxC,KAAK,GAAG,OAAO,CAAC;IAClB,CAAC;SAAM,CAAC;QACN,KAAK,GAAG,SAAS,CAAC;IACpB,CAAC;IAED,OAAO;QACL,KAAK;QACL,GAAG,EAAE,KAAK;QACV,QAAQ,EAAE,cAAc,CAAC,KAAK,CAAC,UAAU,CAAC;QAC1C,OAAO,EAAE,KAAK,KAAK,OAAO;QAC1B,WAAW,EAAE,KAAK,KAAK,OAAO;KAC/B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC;IACjC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;IAE9C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAE5D,IAAI,QAAQ,GAAG,EAAE,EAAE,CAAC;QAClB,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,IAAI,QAAQ,GAAG,EAAE,EAAE,CAAC;QAClB,OAAO,GAAG,QAAQ,UAAU,CAAC;IAC/B,CAAC;IACD,IAAI,SAAS,GAAG,EAAE,EAAE,CAAC;QACnB,OAAO,GAAG,SAAS,QAAQ,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;IAC9D,CAAC;IACD,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,OAAO,GAAG,QAAQ,OAAO,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;IAC3D,CAAC;IAED,OAAO,IAAI,CAAC,kBAAkB,EAAE,CAAC;AACnC,CAAC;AAED,gFAAgF;AAChF,sDAAsD;AACtD,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAe;IAClD,MAAM,KAAK,GAAG,MAAM,cAAc,EAAE,CAAC;IAErC,kBAAkB;IAClB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED,iCAAiC;IACjC,IAAI,KAAK,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,0BAA0B;IAC1B,MAAM,SAAS,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC7C,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC,aAAa,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,OAAe,EACf,OAAwC;IAExC,kBAAkB;IAClB,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAC3C,CAAC;IAED,8BAA8B;IAC9B,MAAM,KAAK,GAAG,MAAM,OAAO,EAAE,CAAC;IAE9B,2CAA2C;IAC3C,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;QACxC,0CAA0C;IAC5C,CAAC,CAAC,CAAC;IAEH,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AACxC,CAAC;AAED,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;GAEG;AACH,KAAK,UAAU,YAAY;IACzB,MAAM,QAAQ,GAAG,MAAM,WAAW,EAAE,CAAC;IACrC,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;AACzC,CAAC;AAED;;GAEG;AACH,SAAS,YAAY,CAAC,IAAa;IACjC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,KAAK,GAAG,IAA2B,CAAC;IAE1C,gBAAgB;IAChB,IAAI,KAAK,CAAC,OAAO,KAAK,aAAa,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,wBAAwB;IACxB,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC9D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,aAAa,IAAI,OAAO,KAAK,CAAC,aAAa,KAAK,QAAQ,EAAE,CAAC;QACpE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,mCAAmC;IACnC,MAAM,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC;IACnC,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QAC7D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,OAAO,MAAM,CAAC,QAAQ,CAAC,SAAS,KAAK,QAAQ;QACjE,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,KAAK,QAAQ;QACzC,OAAO,MAAM,CAAC,QAAQ,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;QACnD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,gFAAgF;AAChF,sBAAsB;AACtB,gFAAgF;AAEhF,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,YAAY;IACZ,YAAY;IACZ,kBAAkB;IAClB,oBAAoB;IACpB,aAAa;CACd,CAAC"}

package/dist/lib/targeted-coaching.js

@@ -109,8 +109,8 @@ export const COACHING_TIPS = [
         id: 'quality-team-sync',
         metric: 'collaborationQuality',
         context: ['start'],
-        message: 'Run `ginko sync` periodically to stay aligned with team updates',
-        action: 'ginko sync',
+        message: 'Run `ginko pull` periodically to stay aligned with team updates',
+        action: 'ginko pull',
         priority: 6,
     },
     // Anti-Patterns Tips

package/dist/lib/task-parser.d.ts

@@ -12,8 +12,19 @@
  * Task status values (aligned with Status API)
  */
 export type TaskStatus = 'not_started' | 'in_progress' | 'blocked' | 'complete' | 'paused';
+/**
+ * Task content quality assessment (EPIC-018)
+ */
+export type TaskContentQuality = 'thin' | 'adequate' | 'rich';
 /**
  * Parsed task from sprint markdown
+ *
+ * EPIC-018: Rich task content follows WHY-WHAT-HOW structure:
+ * - problem: WHY this task exists (motivation)
+ * - solution: WHAT we're achieving (outcome)
+ * - approach: HOW we'll implement it (strategy)
+ * - scope: boundaries (in/out of scope)
+ * - acceptance_criteria: done when (definition of done)
  */
 export interface ParsedTask {
     /** Task ID (e.g., e015_s00a_t01, TASK-1, adhoc_260119_s01_t01) */
@@ -32,16 +43,26 @@ export interface ParsedTask {
     assignee: string | null;
     /** Initial status from checkbox (used only on CREATE) */
     initial_status: TaskStatus;
-    /** Task goal/description */
-    goal: string | null;
-    /** Approach/implementation notes (e014_s02_t04) */
+    /** WHY: Problem/motivation - why this task exists */
+    problem: string | null;
+    /** WHAT: Solution/outcome - what we're achieving */
+    solution: string | null;
+    /** HOW: Approach/strategy - implementation notes */
     approach: string | null;
-    /** Acceptance criteria list */
+    /** Boundaries: What's in/out of scope */
+    scope: string | null;
+    /** @deprecated Use 'solution' instead. Kept for backward compatibility. */
+    goal: string | null;
+    /** Acceptance criteria list (definition of done) */
     acceptance_criteria: string[];
     /** Referenced files */
     files: string[];
     /** Related ADR references */
     related_adrs: string[];
+    /** AI confidence score (0-100) when task was created */
+    confidence: number | null;
+    /** Assessed content quality */
+    content_quality: TaskContentQuality;
 }
 /**
  * Sprint metadata extracted alongside tasks
@@ -73,6 +94,15 @@ export declare function parseTaskHierarchy(taskId: string): {
     sprint_id: string;
     epic_id: string;
 } | null;
+/**
+ * Assess task content quality (EPIC-018)
+ *
+ * Evaluates whether a task has enough content to work autonomously.
+ * - thin: Missing critical fields (problem, acceptance criteria)
+ * - adequate: Has basics but missing approach or scope
+ * - rich: Complete WHY-WHAT-HOW structure
+ */
+export declare function assessTaskContentQuality(task: ParsedTask): TaskContentQuality;
 /**
  * Parse a single task block
  *

package/dist/lib/task-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-parser.d.ts","sourceRoot":"","sources":["../../src/lib/task-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAmBH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE3F;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qBAAqB;IACrB,QAAQ,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACjD,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yDAAyD;IACzD,cAAc,EAAE,UAAU,CAAC;IAC3B,4BAA4B;IAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,+BAA+B;IAC/B,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,uBAAuB;IACvB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6BAA6B;IAC7B,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,cAAc;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA8BhG;AAqID;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrD,UAAU,GAAG,IAAI,CA6GnB;AA4GD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAwBrF;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAazF;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAyBtF"}
+{"version":3,"file":"task-parser.d.ts","sourceRoot":"","sources":["../../src/lib/task-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAmBH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE3F;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;AAE9D;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qBAAqB;IACrB,QAAQ,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACjD,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yDAAyD;IACzD,cAAc,EAAE,UAAU,CAAC;IAG3B,qDAAqD;IACrD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yCAAyC;IACzC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAErB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAEpB,oDAAoD;IACpD,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,uBAAuB;IACvB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6BAA6B;IAC7B,YAAY,EAAE,MAAM,EAAE,CAAC;IAGvB,wDAAwD;IACxD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,+BAA+B;IAC/B,eAAe,EAAE,kBAAkB,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,cAAc;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA8BhG;AAkJD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,UAAU,GAAG,kBAAkB,CAa7E;AAwED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrD,UAAU,GAAG,IAAI,CAgInB;AA4GD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAwBrF;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAazF;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAyBtF"}