grimoire-framework 1.0.0

package/.grimoire/development/scripts/greeting-builder.js

@@ -0,0 +1,1406 @@
+/**
+ * Greeting Builder - Context-Aware Agent Greeting System (Core Logic)
+ *
+ * ARCHITECTURE NOTE:
+ * This is the CORE CLASS that contains all greeting logic.
+ * It can be used directly by agents OR via the CLI wrapper (generate-greeting.js).
+ *
+ * - This file: Core GreetingBuilder class
+ * - generate-greeting.js: CLI wrapper that orchestrates context loading
+ *
+ * Builds intelligent greetings based on:
+ * - Session type (new/existing/workflow)
+ * - Git configuration status
+ * - Project status (natural language narrative)
+ * - Command visibility metadata
+ * - Previous agent handoff context
+ * - Current story and branch references
+ *
+ * Story ACT-7: Context-Aware Greeting Sections
+ * - Section builders receive full enriched context from UnifiedActivationPipeline
+ * - Presentation adapts: new=full intro, existing=brief, workflow=focused
+ * - Role description references current story and branch
+ * - Project status uses natural language narrative
+ * - Context section references previous agent handoff intelligently
+ * - Footer varies by session context
+ * - Parallelizable sections executed with Promise.all()
+ * - Fallback to static templates if context loading fails (150ms per section)
+ *
+ * Used by: Most agents (direct invocation in STEP 3)
+ * Also used by: generate-greeting.js (CLI wrapper for @devops, @data-engineer, @ux-design-expert)
+ *
+ * @see docs/architecture/greeting-system.md for full architecture documentation
+ * @see generate-greeting.js for CLI wrapper
+ *
+ * Performance: <200ms total (hard limit with timeout protection)
+ * Fallback: Simple greeting on any error
+ */
+
+const ContextDetector = require('../../core/session/context-detector');
+const GitConfigDetector = require('../../infrastructure/scripts/git-config-detector');
+const WorkflowNavigator = require('./workflow-navigator');
+const GreetingPreferenceManager = require('./greeting-preference-manager');
+const { loadProjectStatus } = require('../../infrastructure/scripts/project-status-loader');
+const { PermissionMode } = require('../../core/permissions');
+const { resolveConfig } = require('../../core/config/config-resolver');
+const { validateUserProfile } = require('../../infrastructure/scripts/validate-user-profile');
+// Story ACT-5: SessionState integration for cross-terminal workflow continuity
+const { SessionState } = require('../../core/orchestration/session-state');
+// Story ACT-5: SurfaceChecker integration for proactive suggestions
+const { SurfaceChecker } = require('../../core/orchestration/surface-checker');
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const GREETING_TIMEOUT = 150; // 150ms hard limit per-section
+const _TOTAL_GREETING_TIMEOUT = 200; // 200ms total pipeline budget (Story ACT-7, documented constant)
+const SECTION_TIMEOUT = 150; // 150ms per section builder (Story ACT-7 AC8)
+
+// Story ACT-2: Validation now delegated to validate-user-profile.js
+const DEFAULT_USER_PROFILE = 'advanced';
+
+const GIT_WARNING_TEMPLATE = `
+⚠️  **Git Configuration Needed**
+   Your project is not connected to a git repository.
+   Run \`git init\` and \`git remote add origin <url>\` to enable version control.
+`;
+
+class GreetingBuilder {
+  constructor() {
+    this.contextDetector = new ContextDetector();
+    this.gitConfigDetector = new GitConfigDetector();
+    this.workflowNavigator = new WorkflowNavigator();
+    this.preferenceManager = new GreetingPreferenceManager();
+    this.config = this._loadConfig();
+  }
+
+  /**
+   * Load resolved config once, shared across greeting build.
+   * Story ACT-9 QA fix: Eliminates duplicate resolveConfig() calls per greeting build.
+   * @returns {Object|null} Resolved config object, or null on failure
+   */
+  _loadResolvedConfig() {
+    try {
+      const result = resolveConfig(process.cwd(), { skipCache: true });
+      return result?.config || null;
+    } catch (error) {
+      console.warn('[GreetingBuilder] Failed to load config:', error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Load user profile via config-resolver (L5 User layer has highest priority).
+   * Story 12.1 - AC3: Uses resolveConfig() to read user_profile from layered hierarchy.
+   * Story ACT-2 - AC3: Runs validate-user-profile during activation (not just installation).
+   * Reads fresh each time (skipCache: true) to reflect toggle changes immediately.
+   * @param {Object} [resolvedConfig] - Pre-loaded config to avoid duplicate resolveConfig() call
+   * @returns {string} User profile ('bob' | 'advanced'), defaults to 'advanced'
+   */
+  loadUserProfile(resolvedConfig) {
+    try {
+      const config = resolvedConfig || this._loadResolvedConfig();
+      const userProfile = config?.user_profile;
+
+      if (!userProfile) {
+        return DEFAULT_USER_PROFILE;
+      }
+
+      // Story ACT-2 - AC3: Run validation during activation pipeline (graceful)
+      const validation = validateUserProfile(userProfile);
+      if (!validation.valid) {
+        console.warn(`[GreetingBuilder] user_profile validation failed: ${validation.error}`);
+        return DEFAULT_USER_PROFILE;
+      }
+      if (validation.warning) {
+        console.warn(`[GreetingBuilder] user_profile warning: ${validation.warning}`);
+      }
+
+      return validation.value;
+    } catch (error) {
+      console.warn('[GreetingBuilder] Failed to load user_profile:', error.message);
+      return DEFAULT_USER_PROFILE;
+    }
+  }
+
+  /**
+   * Build contextual greeting for agent
+   * @param {Object} agent - Agent definition
+   * @param {Object} context - Session context
+   * @returns {Promise<string>} Formatted greeting
+   */
+  async buildGreeting(agent, context = {}) {
+    const fallbackGreeting = this.buildSimpleGreeting(agent);
+
+    try {
+      // ACT-11: Use pre-loaded config from pipeline context to avoid duplicate resolveConfig()
+      const resolvedConfig = context._coreConfig || this._loadResolvedConfig();
+      // Story ACT-2: Load user profile early so preference manager can account for it
+      const userProfile = this.loadUserProfile(resolvedConfig);
+
+      // Check user preference (Story 6.1.4), now profile-aware (Story ACT-2)
+      // Story ACT-2: PM agent bypasses bob mode preference restriction because
+      // PM is the primary interface in bob mode and needs the full contextual greeting.
+      const preference = (userProfile === 'bob' && agent.id === 'pm')
+        ? this.preferenceManager.getPreference('advanced')
+        : this.preferenceManager.getPreference(userProfile);
+
+      if (preference !== 'auto') {
+        // Override with fixed level
+        return this.buildFixedLevelGreeting(agent, preference);
+      }
+
+      // Use session-aware logic (Story 6.1.2.5)
+      // Story ACT-2: Pass pre-loaded userProfile to avoid double loadUserProfile() call
+      const greetingPromise = this._buildContextualGreeting(agent, context, userProfile);
+      const timeoutPromise = new Promise((_, reject) =>
+        setTimeout(() => reject(new Error('Greeting timeout')), GREETING_TIMEOUT),
+      );
+
+      return await Promise.race([greetingPromise, timeoutPromise]);
+    } catch (error) {
+      console.warn('[GreetingBuilder] Fallback to simple greeting:', error.message);
+      return fallbackGreeting;
+    }
+  }
+
+  /**
+   * Build contextual greeting (internal implementation)
+   * Story 10.3: Profile-aware greeting with conditional agent visibility
+   * Story ACT-2: Accepts pre-loaded userProfile to avoid redundant loadUserProfile() calls
+   * Story ACT-7: Context-aware sections with parallelization and enriched context
+   * Story ACT-12: Language removed — delegated to Claude Code native settings.json
+   * @private
+   * @param {Object} agent - Agent definition
+   * @param {Object} context - Session context (may contain pre-loaded values from pipeline)
+   * @param {string} [preloadedUserProfile] - Pre-loaded user profile (avoids double call)
+   * @returns {Promise<string>} Contextual greeting
+   */
+  async _buildContextualGreeting(agent, context, preloadedUserProfile) {
+    // Use pre-loaded values if available, otherwise load
+    const sessionType = context.sessionType || (await this._safeDetectSessionType(context));
+
+    const projectStatus = context.projectStatus || (await this._safeLoadProjectStatus());
+
+    // gitConfig: use from enriched context if available, otherwise load
+    const gitConfig = context.gitConfig || (await this._safeCheckGitConfig());
+
+    // Story 10.3 - AC7, AC8: Load user profile fresh each time
+    // Story ACT-2: Use pre-loaded value if available to avoid double resolveConfig() call
+    const userProfile = preloadedUserProfile || this.loadUserProfile();
+
+    // Story ACT-7 AC1: Build enriched section context for all builders
+    const sectionContext = {
+      sessionType,
+      projectStatus,
+      gitConfig,
+      userProfile,
+      previousAgent: context.previousAgent || null,
+      sessionStory: context.sessionStory || null,
+      lastCommands: context.lastCommands || [],
+      sessionMessage: context.sessionMessage || null,
+      workflowState: context.workflowState || null,
+      workflowActive: context.workflowActive || null,
+      permissions: context.permissions || null,
+    };
+
+    // Permission badge: use from enriched context if available, otherwise load
+    const permissionBadge = context.permissions?.badge || (await this._safeGetPermissionBadge());
+
+    // Build greeting sections based on session type
+    const sections = [];
+
+    // 1. Presentation with permission mode badge (always)
+    // Story ACT-7 AC2: Adapts based on session type (new=full, existing=brief, workflow=focused)
+    sections.push(this.buildPresentation(agent, sessionType, permissionBadge, sectionContext));
+
+    // 2. Role description (new session only, but skip in bob mode for non-PM)
+    // Story ACT-7 AC3: References current story and branch when available
+    if (sessionType === 'new' && !(userProfile === 'bob' && agent.id !== 'pm')) {
+      sections.push(this.buildRoleDescription(agent, sectionContext));
+    }
+
+    // 3. Project status (if git configured, but skip in bob mode for non-PM)
+    // Story ACT-7 AC4: Natural language narrative format
+    if (gitConfig.configured && projectStatus && !(userProfile === 'bob' && agent.id !== 'pm')) {
+      sections.push(this.buildProjectStatus(projectStatus, sessionType, sectionContext));
+    }
+
+    // Story 10.3 - AC1, AC4: Bob mode redirect for non-PM agents
+    if (userProfile === 'bob' && agent.id !== 'pm') {
+      // Show redirect message instead of normal content
+      sections.push(this.buildBobModeRedirect(agent));
+      return sections.filter(Boolean).join('\n\n');
+    }
+
+    // Story ACT-7 AC7: Parallel execution of independent sections
+    // Context section and workflow suggestions use different data sources
+    const [contextSection, workflowSection] = await Promise.all([
+      // 4. Context section (intelligent contextualization + recommendations)
+      // Story ACT-7 AC5: References previous agent handoff intelligently
+      this._safeBuildSection(() =>
+        this.buildContextSection(agent, context, sessionType, projectStatus, sectionContext),
+      ),
+      // 5. Workflow suggestions (Story ACT-5: relaxed trigger + fixed method call)
+      this._safeBuildSection(() => {
+        if (sessionType !== 'new') {
+          return this.buildWorkflowSuggestions(context);
+        }
+        return null;
+      }),
+    ]);
+
+    if (contextSection) {
+      sections.push(contextSection);
+    }
+    if (workflowSection) {
+      sections.push(workflowSection);
+    }
+
+    // 7. Commands (filtered by visibility and user profile)
+    // Story 10.3 - AC2, AC5: Pass userProfile for profile-aware filtering
+    const commands = this.filterCommandsByVisibility(agent, sessionType, userProfile);
+    sections.push(this.buildCommands(commands, sessionType));
+
+    // 8. Footer with signature
+    // Story ACT-7 AC6: Footer varies by session context
+    sections.push(this.buildFooter(agent, sectionContext));
+
+    return sections.filter(Boolean).join('\n\n');
+  }
+
+  /**
+   * Execute a section builder with timeout protection.
+   * Story ACT-7 AC8: Fallback to null if section builder exceeds SECTION_TIMEOUT.
+   * @private
+   * @param {Function} builderFn - Section builder function (sync or async)
+   * @returns {Promise<string|null>} Section result or null on timeout/error
+   */
+  async _safeBuildSection(builderFn) {
+    try {
+      const result = builderFn();
+      // If the builder returns a promise, race it against the timeout
+      if (result && typeof result.then === 'function') {
+        return await Promise.race([
+          result,
+          new Promise((resolve) => setTimeout(() => resolve(null), SECTION_TIMEOUT)),
+        ]);
+      }
+      return result;
+    } catch (error) {
+      console.warn('[GreetingBuilder] Section builder failed:', error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Build fixed-level greeting (Story 6.1.4)
+   * ACT-12: Language removed — Claude Code handles translation natively via settings.json
+   * @param {Object} agent - Agent definition
+   * @param {string} level - Preference level (minimal|named|archetypal)
+   * @returns {string} Fixed-level greeting
+   */
+  buildFixedLevelGreeting(agent, level) {
+    const profile = agent.persona_profile;
+
+    if (!profile || !profile.greeting_levels) {
+      return this.buildSimpleGreeting(agent);
+    }
+
+    // Select greeting based on preference
+    let greetingText;
+    switch (level) {
+      case 'minimal':
+        greetingText = profile.greeting_levels.minimal || `${agent.icon} ${agent.id} Agent ready`;
+        break;
+      case 'named':
+        greetingText = profile.greeting_levels.named || `${agent.icon} ${agent.name} ready`;
+        break;
+      case 'archetypal':
+        greetingText =
+          profile.greeting_levels.archetypal ||
+          `${agent.icon} ${agent.name} the ${profile.archetype} ready`;
+        break;
+      default:
+        greetingText = profile.greeting_levels.named || `${agent.icon} ${agent.name} ready`;
+    }
+
+    return `${greetingText}\n\nType \`*help\` to see available commands.`;
+  }
+
+  /**
+   * Build simple greeting (fallback)
+   * ACT-12: Language removed — Claude Code handles translation natively via settings.json
+   * @param {Object} agent - Agent definition
+   * @returns {string} Simple greeting
+   */
+  buildSimpleGreeting(agent) {
+    const greetingLevels =
+      agent.persona_profile?.communication?.greeting_levels ||
+      agent.persona_profile?.greeting_levels;
+    const greeting = greetingLevels?.named || `${agent.icon} ${agent.name} ready`;
+    return `${greeting}\n\nType \`*help\` to see available commands.`;
+  }
+
+  /**
+   * Build presentation section
+   * Story ACT-7 AC2: Adapts based on session type
+   *   - new session: full archetypal intro
+   *   - existing session: brief "Welcome back" with current focus
+   *   - workflow session: focused on workflow state
+   * @param {Object} agent - Agent definition
+   * @param {string} sessionType - Session type
+   * @param {string} permissionBadge - Permission mode badge (optional)
+   * @param {Object} [sectionContext] - Enriched section context (Story ACT-7)
+   * @returns {string} Presentation text
+   */
+  buildPresentation(agent, sessionType, permissionBadge = '', sectionContext = null) {
+    const profile = agent.persona_profile;
+
+    // Try greeting_levels from communication first, then fall back to top level
+    const greetingLevels = profile?.communication?.greeting_levels || profile?.greeting_levels;
+
+    if (!greetingLevels) {
+      const base = `${agent.icon} ${agent.name} ready`;
+      return permissionBadge ? `${base} ${permissionBadge}` : base;
+    }
+
+    // Story ACT-7 AC2: Presentation adapts based on session type
+    // ACT-12: Language delegated to Claude Code settings.json — hardcoded English phrases
+    let greeting;
+
+    if (sessionType === 'existing' && sectionContext) {
+      // Existing session: brief welcome back
+      const namedGreeting = greetingLevels.named || `${agent.icon} ${agent.name} ready`;
+      const storyRef = sectionContext.sessionStory || sectionContext.projectStatus?.currentStory;
+      if (storyRef) {
+        greeting = `${namedGreeting} -- continuing ${storyRef}`;
+      } else {
+        greeting = `${namedGreeting} -- welcome back`;
+      }
+    } else if (sessionType === 'workflow' && sectionContext) {
+      // Workflow session: focused on current workflow
+      const namedGreeting = greetingLevels.named || `${agent.icon} ${agent.name} ready`;
+      const workflowPhase = sectionContext.workflowState?.currentPhase || sectionContext.workflowActive;
+      if (workflowPhase) {
+        greeting = `${namedGreeting} -- workflow active`;
+      } else {
+        greeting = namedGreeting;
+      }
+    } else {
+      // New session or no context: full archetypal greeting
+      greeting =
+        greetingLevels.archetypal || greetingLevels.named || `${agent.icon} ${agent.name} ready`;
+    }
+
+    // Append permission badge if available
+    return permissionBadge ? `${greeting} ${permissionBadge}` : greeting;
+  }
+
+  /**
+   * Build role description section
+   * Story ACT-7 AC3: References current story and branch when available.
+   * Skipped entirely for returning sessions (too verbose).
+   * @param {Object} agent - Agent definition
+   * @param {Object} [sectionContext] - Enriched section context (Story ACT-7)
+   * @returns {string} Role description
+   */
+  buildRoleDescription(agent, sectionContext = null) {
+    if (!agent.persona || !agent.persona.role) {
+      return '';
+    }
+
+    let roleText = `**Role:** ${agent.persona.role}`;
+
+    // Story ACT-7 AC3: Append story/branch references when available
+    if (sectionContext) {
+      const storyRef = sectionContext.sessionStory || sectionContext.projectStatus?.currentStory;
+      const branchRef = sectionContext.projectStatus?.branch || sectionContext.gitConfig?.branch;
+
+      const refs = [];
+      if (storyRef) {
+        refs.push(`Story: ${storyRef}`);
+      }
+      if (branchRef && branchRef !== 'main' && branchRef !== 'master') {
+        refs.push(`Branch: \`${branchRef}\``);
+      }
+
+      if (refs.length > 0) {
+        roleText += `\n   ${refs.join(' | ')}`;
+      }
+    }
+
+    return roleText;
+  }
+
+  /**
+   * Build project status section
+   * Story ACT-7 AC4: Natural language narrative format alongside bullet points.
+   * @param {Object} projectStatus - Project status data
+   * @param {string} sessionType - Session type
+   * @param {Object} [sectionContext] - Enriched section context (Story ACT-7)
+   * @returns {string} Formatted project status
+   */
+  buildProjectStatus(projectStatus, sessionType = 'full', sectionContext = null) {
+    if (!projectStatus) {
+      return '';
+    }
+
+    // Story ACT-7 AC4: Use narrative format when enriched context is available
+    if (sectionContext) {
+      return this._formatProjectStatusNarrative(projectStatus, sessionType);
+    }
+
+    // Legacy: bullet-point format (backward compatible)
+    const format = sessionType === 'workflow' ? 'condensed' : 'full';
+    return this._formatProjectStatus(projectStatus, format);
+  }
+
+  /**
+   * Format project status as natural language narrative.
+   * Story ACT-7 AC4: Instead of bullet points, produce human-readable sentences.
+   * Example: "You're on branch `feat/act-7` with 3 modified files. Story ACT-7 is in progress."
+   * @private
+   * @param {Object} status - Project status
+   * @param {string} sessionType - Session type
+   * @returns {string} Narrative status
+   */
+  _formatProjectStatusNarrative(status, sessionType) {
+    // Workflow sessions get condensed inline format
+    if (sessionType === 'workflow') {
+      return this._formatProjectStatus(status, 'condensed');
+    }
+
+    const sentences = [];
+
+    // Branch + modified files as natural sentence
+    if (status.branch) {
+      let branchSentence = `You're on branch \`${status.branch}\``;
+      const fileCount = status.modifiedFilesTotalCount || 0;
+      if (fileCount > 0) {
+        branchSentence += ` with ${fileCount} modified file${fileCount !== 1 ? 's' : ''}`;
+      }
+      branchSentence += '.';
+      sentences.push(branchSentence);
+    }
+
+    // Current story as narrative
+    if (status.currentStory) {
+      sentences.push(`Story **${status.currentStory}** is in progress.`);
+    }
+
+    // Recent commits as brief reference
+    if (status.recentCommits && status.recentCommits.length > 0) {
+      const lastCommit = status.recentCommits[0];
+      const commitMsg = typeof lastCommit === 'string' ? lastCommit : lastCommit.message || lastCommit;
+      const shortMsg = String(commitMsg).length > 60
+        ? String(commitMsg).substring(0, 57) + '...'
+        : String(commitMsg);
+      sentences.push(`Last commit: "${shortMsg}"`);
+    }
+
+    if (sentences.length === 0) {
+      return '';
+    }
+
+    return `📊 **Project Status:** ${sentences.join(' ')}`;
+  }
+
+  /**
+   * Format project status (legacy bullet-point format)
+   * @private
+   * @param {Object} status - Project status
+   * @param {string} format - 'full' | 'condensed'
+   * @returns {string} Formatted status
+   */
+  _formatProjectStatus(status, format) {
+    if (format === 'condensed') {
+      const parts = [];
+
+      if (status.branch) {
+        parts.push(`🌿 ${status.branch}`);
+      }
+
+      if (status.modifiedFilesTotalCount > 0) {
+        parts.push(`📝 ${status.modifiedFilesTotalCount} modified`);
+      }
+
+      if (status.currentStory) {
+        parts.push(`📖 ${status.currentStory}`);
+      }
+
+      return parts.length > 0 ? `📊 ${parts.join(' | ')}` : '';
+    }
+
+    // Full format with emojis
+    const lines = [];
+
+    if (status.branch) {
+      lines.push(`🌿 **Branch:** ${status.branch}`);
+    }
+
+    if (status.modifiedFiles && status.modifiedFiles.length > 0) {
+      let filesDisplay = status.modifiedFiles.join(', ');
+      const totalCount = status.modifiedFilesTotalCount || status.modifiedFiles.length;
+      if (totalCount > status.modifiedFiles.length) {
+        const remaining = totalCount - status.modifiedFiles.length;
+        filesDisplay += ` ...and ${remaining} more`;
+      }
+      lines.push(`📝 **Modified:** ${filesDisplay}`);
+    }
+
+    if (status.recentCommits && status.recentCommits.length > 0) {
+      lines.push(`📖 **Recent:** ${status.recentCommits.join(', ')}`);
+    }
+
+    if (status.currentStory) {
+      lines.push(`📌 **Story:** ${status.currentStory}`);
+    }
+
+    if (lines.length === 0) {
+      return '';
+    }
+
+    return `📊 **Project Status:**\n  - ${lines.join('\n  - ')}`;
+  }
+
+  /**
+   * Build intelligent context section with recommendations
+   * Story ACT-7 AC5: References previous agent handoff intelligently.
+   * @param {Object} agent - Agent definition
+   * @param {Object} context - Session context
+   * @param {string} sessionType - Session type
+   * @param {Object} projectStatus - Project status
+   * @param {Object} [sectionContext] - Enriched section context (Story ACT-7)
+   * @returns {string|null} Context section with recommendations
+   */
+  buildContextSection(agent, context, sessionType, projectStatus, sectionContext = null) {
+    // Skip for new sessions
+    if (sessionType === 'new') {
+      return null;
+    }
+
+    const parts = [];
+
+    // Build intelligent context narrative
+    const contextNarrative = this._buildContextNarrative(agent, context, projectStatus);
+
+    if (contextNarrative.description) {
+      parts.push(`💡 **Context:** ${contextNarrative.description}`);
+    }
+
+    // Story ACT-7 AC5: Add handoff context when previous agent is detected
+    if (sectionContext && sectionContext.previousAgent && !contextNarrative.description) {
+      const prevName = this._getPreviousAgentName(context);
+      if (prevName) {
+        parts.push(`💡 **Context:** Picked up from @${prevName}'s session`);
+      }
+    }
+
+    if (contextNarrative.recommendedCommand) {
+      parts.push(`   **Recommended:** Use \`${contextNarrative.recommendedCommand}\` to continue`);
+    }
+
+    return parts.length > 0 ? parts.join('\n') : null;
+  }
+
+  /**
+   * Build intelligent context narrative based on previous work
+   * Analyzes files, story, and previous agent to create rich context
+   * @private
+   */
+  _buildContextNarrative(agent, context, projectStatus) {
+    const prevAgentId = this._getPreviousAgentId(context);
+    const prevAgentName = this._getPreviousAgentName(context);
+
+    // Priority 1: Agent transition + Story + Modified files (richest context)
+    if (prevAgentId && projectStatus?.modifiedFiles) {
+      // Use session story if available (more accurate), otherwise use git story
+      const sessionStory = context.sessionStory || projectStatus.currentStory;
+      const storyContext = this._analyzeStoryContext({
+        ...projectStatus,
+        currentStory: sessionStory,
+      });
+      const fileContext = this._analyzeModifiedFiles(projectStatus.modifiedFiles, sessionStory);
+
+      let description = `Vejo que @${prevAgentName} finalizou os ajustes`;
+
+      if (fileContext.keyFiles.length > 0) {
+        description += ` ${fileContext.summary}`;
+      }
+
+      if (storyContext.storyFile) {
+        description += ` no **\`${storyContext.storyFile}\`**`;
+      }
+
+      description += `. Agora podemos ${this._getAgentAction(agent.id, storyContext)}`;
+
+      const recommendedCommand = this._suggestCommand(agent.id, prevAgentId, storyContext);
+
+      return { description, recommendedCommand };
+    }
+
+    // Priority 2: Agent transition + Story (no file details)
+    if (
+      prevAgentId &&
+      projectStatus?.currentStory &&
+      projectStatus.currentStory !== 'EPIC-SPLIT-IMPLEMENTATION-COMPLETE'
+    ) {
+      const storyContext = this._analyzeStoryContext(projectStatus);
+      const description = `Continuando do trabalho de @${prevAgentName} em ${projectStatus.currentStory}. ${this._getAgentAction(agent.id, storyContext)}`;
+      const recommendedCommand = this._suggestCommand(agent.id, prevAgentId, storyContext);
+
+      return { description, recommendedCommand };
+    }
+
+    // Priority 3: Just agent transition
+    if (prevAgentId) {
+      const description = `Continuing from @${prevAgentName}`;
+      const recommendedCommand = this._suggestCommand(agent.id, prevAgentId, {});
+
+      return { description, recommendedCommand };
+    }
+
+    // Priority 4: Story-based context
+    if (
+      projectStatus?.currentStory &&
+      projectStatus.currentStory !== 'EPIC-SPLIT-IMPLEMENTATION-COMPLETE'
+    ) {
+      const storyContext = this._analyzeStoryContext(projectStatus);
+      const description = `Working on ${projectStatus.currentStory}`;
+      const recommendedCommand = this._suggestCommand(agent.id, null, storyContext);
+
+      return { description, recommendedCommand };
+    }
+
+    // Priority 5: Last command context
+    if (context.lastCommands && context.lastCommands.length > 0) {
+      const lastCmd = context.lastCommands[context.lastCommands.length - 1];
+      const cmdName = typeof lastCmd === 'object' ? lastCmd.command : lastCmd;
+      const description = `Last action: *${cmdName}`;
+
+      return { description, recommendedCommand: null };
+    }
+
+    // Priority 6: Session message
+    if (context.sessionMessage) {
+      return { description: context.sessionMessage, recommendedCommand: null };
+    }
+
+    return { description: null, recommendedCommand: null };
+  }
+
+  _getPreviousAgentId(context) {
+    if (!context.previousAgent) return null;
+    return typeof context.previousAgent === 'string'
+      ? context.previousAgent
+      : context.previousAgent.agentId;
+  }
+
+  _getPreviousAgentName(context) {
+    if (!context.previousAgent) return null;
+    return typeof context.previousAgent === 'string'
+      ? context.previousAgent
+      : context.previousAgent.agentName || context.previousAgent.agentId;
+  }
+
+  _analyzeStoryContext(projectStatus) {
+    const currentStory = projectStatus.currentStory || '';
+    const storyFile = currentStory ? `${currentStory}.md` : null;
+
+    return {
+      storyId: currentStory,
+      storyFile: storyFile,
+      hasStory: !!currentStory && currentStory !== 'EPIC-SPLIT-IMPLEMENTATION-COMPLETE',
+    };
+  }
+
+  _analyzeModifiedFiles(modifiedFiles, _currentStory) {
+    if (!modifiedFiles || modifiedFiles.length === 0) {
+      return { keyFiles: [], summary: '' };
+    }
+
+    const keyFiles = [];
+    const patterns = [
+      {
+        regex: /greeting-builder\.js/,
+        priority: 1,
+        desc: 'do **`.grimoire/scripts/greeting-builder.js`**',
+        category: 'script',
+      },
+      {
+        regex: /agent-config-loader\.js/,
+        priority: 1,
+        desc: 'do **`agent-config-loader.js`**',
+        category: 'script',
+      },
+      {
+        regex: /generate-greeting\.js/,
+        priority: 1,
+        desc: 'do **`generate-greeting.js`**',
+        category: 'script',
+      },
+      {
+        regex: /session-context-loader\.js/,
+        priority: 1,
+        desc: 'do **`session-context-loader.js`**',
+        category: 'script',
+      },
+      {
+        regex: /agents\/.*\.md/,
+        priority: 1,
+        desc: 'das definições de agentes',
+        category: 'agent',
+      },
+      { regex: /\.md$/, priority: 2, desc: 'dos arquivos de documentação', category: 'doc' },
+    ];
+
+    // Find matching key files (avoid duplicates)
+    const seenCategories = new Set();
+    for (const file of modifiedFiles.slice(0, 5)) {
+      // Check first 5 files
+      for (const pattern of patterns) {
+        if (pattern.regex.test(file) && !seenCategories.has(pattern.category)) {
+          keyFiles.push({
+            file,
+            desc: pattern.desc,
+            priority: pattern.priority,
+            category: pattern.category,
+          });
+          seenCategories.add(pattern.category);
+          break;
+        }
+      }
+    }
+
+    // Sort by priority and take top 2
+    keyFiles.sort((a, b) => a.priority - b.priority);
+    const topFiles = keyFiles.slice(0, 2);
+
+    if (topFiles.length === 0) {
+      return { keyFiles: [], summary: 'dos arquivos do projeto' };
+    }
+
+    if (topFiles.length === 1) {
+      return { keyFiles: topFiles, summary: topFiles[0].desc };
+    }
+
+    return {
+      keyFiles: topFiles,
+      summary: `${topFiles[0].desc} e ${topFiles[1].desc}`,
+    };
+  }
+
+  _getAgentAction(agentId, _storyContext) {
+    const actions = {
+      qa: 'revisar a qualidade dessa implementação',
+      dev: 'implementar as funcionalidades',
+      pm: 'sincronizar o progresso',
+      po: 'validar os requisitos',
+      sm: 'coordenar o desenvolvimento',
+    };
+
+    return actions[agentId] || 'continuar o trabalho';
+  }
+
+  _suggestCommand(agentId, prevAgentId, storyContext) {
+    // Agent transition commands
+    if (prevAgentId === 'dev' && agentId === 'qa') {
+      return storyContext.storyFile ? `*review ${storyContext.storyFile}` : '*review';
+    }
+
+    if (prevAgentId === 'qa' && agentId === 'dev') {
+      return '*apply-qa-fixes';
+    }
+
+    if (prevAgentId === 'po' && agentId === 'dev') {
+      return '*develop-yolo';
+    }
+
+    // Role-based commands when no previous agent
+    if (agentId === 'qa' && storyContext.storyFile) {
+      return `*review ${storyContext.storyFile}`;
+    }
+
+    if (agentId === 'dev' && storyContext.hasStory) {
+      return '*develop-yolo docs/stories/[story-path].md';
+    }
+
+    if (agentId === 'pm' && storyContext.storyId) {
+      return `*sync-story ${storyContext.storyId}`;
+    }
+
+    return null;
+  }
+
+  /**
+   * Build current context section (legacy - kept for compatibility)
+   * @param {Object} context - Session context
+   * @param {string} sessionType - Session type
+   * @param {Object} projectStatus - Project status
+   * @returns {string} Context description
+   */
+  buildCurrentContext(context, sessionType, projectStatus) {
+    if (sessionType === 'workflow' && projectStatus?.currentStory) {
+      return `📌 **Context:** Working on ${projectStatus.currentStory}`;
+    }
+
+    if (context.lastCommand) {
+      return `📌 **Last Action:** ${context.lastCommand}`;
+    }
+
+    return '';
+  }
+
+  /**
+   * Build workflow suggestions section
+   * Story ACT-5: Enhanced with SessionState integration for cross-terminal
+   * workflow continuity and SurfaceChecker for proactive suggestions.
+   *
+   * Detection priority:
+   *   1. SessionState (cross-terminal persistence from Epic 11 Story 11.5)
+   *   2. Command history (pattern-based detection from workflow-patterns.yaml)
+   *
+   * @param {Object} context - Session context
+   * @returns {string|null} Workflow suggestions or null
+   */
+  buildWorkflowSuggestions(context) {
+    try {
+      // Story ACT-5 (AC: 3, 6): Check SessionState first for cross-terminal continuity
+      const sessionStateResult = this._detectWorkflowFromSessionState();
+      if (sessionStateResult) {
+        return sessionStateResult;
+      }
+
+      // Fallback: Pattern-based detection from command history
+      const commandHistory = context.commandHistory || context.lastCommands || [];
+      const workflowState = this.workflowNavigator.detectWorkflowState(commandHistory, context);
+
+      if (!workflowState) {
+        return null;
+      }
+
+      const suggestions = this.workflowNavigator.suggestNextCommands(workflowState);
+      if (!suggestions || suggestions.length === 0) {
+        return null;
+      }
+
+      // Story ACT-5 (AC: 4): Enhance suggestions with SurfaceChecker proactive triggers
+      const enhancedSuggestions = this._enhanceSuggestionsWithSurface(suggestions, context);
+
+      const greetingMessage = this.workflowNavigator.getGreetingMessage(workflowState);
+      const header = greetingMessage || 'Next steps:';
+
+      return this.workflowNavigator.formatSuggestions(enhancedSuggestions, header);
+    } catch (error) {
+      console.warn('[GreetingBuilder] Workflow suggestions failed:', error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Detect workflow state from SessionState for cross-terminal continuity.
+   * Story ACT-5 (AC: 3, 6): Reads persisted session state to detect
+   * active workflows that span terminal sessions.
+   * @private
+   * @returns {string|null} Formatted workflow section or null
+   */
+  _detectWorkflowFromSessionState() {
+    try {
+      const projectRoot = process.cwd();
+      const sessionState = new SessionState(projectRoot);
+
+      // Use synchronous existence check to stay within perf budget
+      const stateFilePath = sessionState.getStateFilePath();
+      if (!fs.existsSync(stateFilePath)) {
+        return null;
+      }
+
+      // Read and parse state file synchronously (fast, local file)
+      const content = fs.readFileSync(stateFilePath, 'utf8');
+      const stateData = yaml.load(content);
+
+      if (!stateData?.session_state) {
+        return null;
+      }
+
+      const ss = stateData.session_state;
+
+      // Only show if there is an active workflow with a current story
+      if (!ss.progress?.current_story || !ss.workflow?.current_phase) {
+        return null;
+      }
+
+      // Build suggestions from session state
+      const suggestions = [];
+      const currentStory = ss.progress.current_story;
+      const currentPhase = ss.workflow.current_phase;
+      const storiesDone = ss.progress.stories_done?.length || 0;
+      const totalStories = ss.epic?.total_stories || 0;
+
+      suggestions.push({
+        command: `*develop-yolo ${currentStory}`,
+        description: `Continue ${currentStory} (phase: ${currentPhase})`,
+        raw_command: 'develop-yolo',
+        args: currentStory,
+      });
+
+      if (storiesDone > 0 && totalStories > 0) {
+        suggestions.push({
+          command: `*build-status ${currentStory}`,
+          description: `Check build status (${storiesDone}/${totalStories} stories done)`,
+          raw_command: 'build-status',
+          args: currentStory,
+        });
+      }
+
+      const header = `Workflow in progress: ${ss.epic?.title || 'Active Epic'} (${storiesDone}/${totalStories})`;
+      return this.workflowNavigator.formatSuggestions(suggestions, header);
+    } catch (error) {
+      // Graceful degradation: if SessionState is unavailable, return null
+      console.warn('[GreetingBuilder] SessionState workflow detection failed:', error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Enhance workflow suggestions with SurfaceChecker proactive triggers.
+   * Story ACT-5 (AC: 4): Uses surface conditions to add relevant
+   * proactive suggestions (e.g., cost warnings, risk alerts).
+   * @private
+   * @param {Array} suggestions - Base suggestions from WorkflowNavigator
+   * @param {Object} context - Session context
+   * @returns {Array} Enhanced suggestions array
+   */
+  _enhanceSuggestionsWithSurface(suggestions, context) {
+    try {
+      const checker = new SurfaceChecker();
+      if (!checker.load()) {
+        return suggestions; // Graceful: criteria file not found
+      }
+
+      // Build surface context from session data
+      const surfaceContext = {
+        risk_level: context.riskLevel || 'LOW',
+        errors_in_task: context.errorsInTask || 0,
+        action_type: context.actionType || null,
+      };
+
+      const result = checker.shouldSurface(surfaceContext);
+
+      if (result.should_surface && result.message) {
+        // Prepend a proactive warning suggestion
+        return [
+          {
+            command: '*help',
+            description: `[${result.severity}] ${result.message}`,
+            raw_command: 'help',
+            args: '',
+          },
+          ...suggestions,
+        ];
+      }
+
+      return suggestions;
+    } catch (error) {
+      // Graceful degradation: SurfaceChecker unavailable, return original suggestions
+      console.warn('[GreetingBuilder] SurfaceChecker enhancement failed:', error.message);
+      return suggestions;
+    }
+  }
+
+  /**
+   * Build contextual suggestions based on project state
+   * Analyzes current context and suggests relevant next commands
+   * @param {Object} agent - Agent definition
+   * @param {Object} projectStatus - Project status data
+   * @param {string} sessionType - Session type
+   * @returns {string|null} Contextual suggestions or null
+   */
+  buildContextualSuggestions(agent, projectStatus, _sessionType) {
+    try {
+      const suggestions = [];
+      const agentId = agent.id;
+
+      // Analyze current story status
+      if (projectStatus.currentStory) {
+        const storyMatch = projectStatus.currentStory.match(/(\d+\.\d+\.\d+(\.\d+)?)/);
+        const storyId = storyMatch ? storyMatch[1] : null;
+
+        // QA agent: suggest validation if story is ready
+        if (
+          agentId === 'qa' &&
+          projectStatus.recentCommits &&
+          projectStatus.recentCommits.length > 0
+        ) {
+          const recentCommit = projectStatus.recentCommits[0].message;
+          if (recentCommit.includes('complete') || recentCommit.includes('implement')) {
+            if (storyId) {
+              suggestions.push(`*review ${storyId}`);
+            } else {
+              suggestions.push('*code-review committed');
+            }
+          }
+        }
+
+        // Dev agent: suggest development tasks
+        if (agentId === 'dev' && storyId) {
+          if (projectStatus.modifiedFilesTotalCount > 0) {
+            suggestions.push('*run-tests');
+          }
+          suggestions.push(`*develop-story ${storyId}`);
+        }
+
+        // PM/PO: suggest story/epic management
+        if ((agentId === 'pm' || agentId === 'po') && storyId) {
+          suggestions.push(`*validate-story-draft ${storyId}`);
+        }
+      }
+
+      // Analyze modified files
+      if (projectStatus.modifiedFilesTotalCount > 0) {
+        if (agentId === 'qa') {
+          suggestions.push('*code-review uncommitted');
+        }
+        if (agentId === 'dev' && projectStatus.modifiedFilesTotalCount > 5) {
+          suggestions.push('*commit-changes');
+        }
+      }
+
+      // Analyze recent work
+      if (projectStatus.recentCommits && projectStatus.recentCommits.length > 0) {
+        const lastCommit = projectStatus.recentCommits[0].message;
+
+        // If last commit was a test, suggest review
+        if (lastCommit.includes('test') && agentId === 'qa') {
+          suggestions.push('*run-tests');
+        }
+
+        // If last commit was a feature, suggest QA
+        if ((lastCommit.includes('feat:') || lastCommit.includes('feature')) && agentId === 'qa') {
+          suggestions.push('*code-review committed');
+        }
+      }
+
+      // No suggestions found
+      if (suggestions.length === 0) {
+        return null;
+      }
+
+      // Build suggestion message
+      const contextSummary = this._buildContextSummary(projectStatus);
+      const commandsList = suggestions
+        .slice(0, 2) // Limit to 2 suggestions
+        .map((cmd) => `   - \`${cmd}\``)
+        .join('\n');
+
+      return `💡 **Context:** ${contextSummary}\n\n**Suggested Next Steps:**\n${commandsList}`;
+    } catch (error) {
+      console.warn('[GreetingBuilder] Contextual suggestions failed:', error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Build context summary based on project status
+   * @private
+   * @param {Object} projectStatus - Project status data
+   * @returns {string} Context summary
+   */
+  _buildContextSummary(projectStatus) {
+    const parts = [];
+
+    if (projectStatus.currentStory) {
+      parts.push(`Working on ${projectStatus.currentStory}`);
+    }
+
+    if (projectStatus.modifiedFilesTotalCount > 0) {
+      parts.push(`${projectStatus.modifiedFilesTotalCount} files modified`);
+    }
+
+    if (projectStatus.recentCommits && projectStatus.recentCommits.length > 0) {
+      const lastCommit = projectStatus.recentCommits[0].message;
+      const shortMsg = lastCommit.length > 50 ? lastCommit.substring(0, 47) + '...' : lastCommit;
+      parts.push(`Last: "${shortMsg}"`);
+    }
+
+    return parts.join(', ') || 'Ready to start';
+  }
+
+  /**
+   * Build commands section
+   * @param {Array} commands - Filtered commands
+   * @param {string} sessionType - Session type
+   * @returns {string} Commands list
+   */
+  buildCommands(commands, sessionType) {
+    if (!commands || commands.length === 0) {
+      return '**Commands:** Type `*help` for available commands';
+    }
+
+    const header = this._getCommandsHeader(sessionType);
+    const commandList = commands
+      .slice(0, 12) // Max 12 commands
+      .map((cmd) => {
+        // Handle both object format and string format
+        if (typeof cmd === 'string') {
+          return `   - \`*${cmd}\``;
+        }
+        if (typeof cmd === 'object' && cmd !== null) {
+          const name = cmd.name || cmd.command || String(cmd);
+          const description = cmd.description || '';
+          return description ? `   - \`*${name}\`: ${description}` : `   - \`*${name}\``;
+        }
+        // Fallback for unexpected formats
+        return `   - \`*${String(cmd)}\``;
+      })
+      .filter((cmd) => !cmd.includes('[object Object]')) // Filter out malformed commands
+      .join('\n');
+
+    return `**${header}:**\n${commandList}`;
+  }
+
+  /**
+   * Get commands header based on session type
+   * @private
+   * @param {string} sessionType - Session type
+   * @returns {string} Header text
+   */
+  _getCommandsHeader(sessionType) {
+    switch (sessionType) {
+      case 'new':
+        return 'Available Commands';
+      case 'existing':
+        return 'Quick Commands';
+      case 'workflow':
+        return 'Key Commands';
+      default:
+        return 'Commands';
+    }
+  }
+
+  /**
+   * Build bob mode redirect message for non-PM agents
+   * Story 10.3 - AC4: Show informative message redirecting to Bob
+   * @param {Object} agent - Agent definition (used for personalization)
+   * @returns {string} Redirect message
+   */
+  buildBobModeRedirect(agent) {
+    const agentName = agent?.name || 'Este agente';
+    return `💡 **Você está no Modo Assistido.**
+
+${agentName} não está disponível diretamente no Modo Assistido.
+Use \`@pm\` (Bob) para todas as interações. Bob vai orquestrar os outros agentes internamente para você.
+
+**Para interagir com Bob:**
+   - Digite \`@pm\` ou \`/grimoire:agents:pm\`
+   - Use \`*help\` após ativar Bob para ver comandos disponíveis`;
+  }
+
+  /**
+   * Build footer section
+   * Story ACT-7 AC6: Footer varies by session context.
+   *   - new session: full guide prompt + signature
+   *   - existing session: brief tip + signature
+   *   - workflow session: progress note + signature
+   * @param {Object} agent - Agent definition
+   * @param {Object} [sectionContext] - Enriched section context (Story ACT-7)
+   * @returns {string} Footer text with signature
+   */
+  buildFooter(agent, sectionContext = null) {
+    const parts = [];
+
+    // Story ACT-7 AC6: Vary footer content by session context
+    // ACT-12: Language delegated to Claude Code settings.json — hardcoded English phrases
+    const sessionType = sectionContext?.sessionType || 'new';
+
+    if (sessionType === 'workflow') {
+      // Workflow: progress note
+      const storyRef = sectionContext?.sessionStory || sectionContext?.projectStatus?.currentStory;
+      if (storyRef) {
+        parts.push(`Focused on **${storyRef}**. Type \`*help\` to see available commands.`);
+      } else {
+        parts.push('Workflow active. Type `*help` to see available commands.');
+      }
+    } else if (sessionType === 'existing') {
+      // Existing session: brief tip with session-info reference
+      parts.push('Type `*help` for commands or `*session-info` for session details.');
+    } else {
+      // New session: full guide prompt
+      parts.push('Type `*guide` for comprehensive usage instructions.');
+    }
+
+    // Add agent signature if available
+    if (
+      agent &&
+      agent.persona_profile &&
+      agent.persona_profile.communication &&
+      agent.persona_profile.communication.signature_closing
+    ) {
+      parts.push('');
+      parts.push(agent.persona_profile.communication.signature_closing);
+    }
+
+    return parts.join('\n');
+  }
+
+  /**
+   * Build git warning section
+   * @returns {string} Git warning message
+   */
+  buildGitWarning() {
+    return GIT_WARNING_TEMPLATE.trim();
+  }
+
+  /**
+   * Filter commands by visibility metadata and user profile
+   * Story 10.3 - AC1, AC2, AC3: Profile-aware command filtering
+   * @param {Object} agent - Agent definition
+   * @param {string} sessionType - Session type
+   * @param {string} userProfile - User profile ('bob' | 'advanced')
+   * @returns {Array} Filtered commands
+   */
+  filterCommandsByVisibility(agent, sessionType, userProfile = DEFAULT_USER_PROFILE) {
+    if (!agent.commands || agent.commands.length === 0) {
+      return [];
+    }
+
+    // Story 10.3 - AC1, AC2: Profile-based filtering
+    // If bob mode AND not PM agent: return empty (will show redirect message instead)
+    if (userProfile === 'bob' && agent.id !== 'pm') {
+      return [];
+    }
+
+    // Story 10.3 - AC5: PM agent shows all commands in bob mode
+    // Story 10.3 - AC2: Advanced mode shows commands normally (current behavior)
+    const visibilityFilter = this._getVisibilityFilter(sessionType);
+
+    // Filter commands with visibility metadata
+    const commandsWithMetadata = agent.commands.filter((cmd) => {
+      if (!cmd.visibility || !Array.isArray(cmd.visibility)) {
+        return false; // No metadata, exclude from filtered list
+      }
+
+      return cmd.visibility.includes(visibilityFilter);
+    });
+
+    // If we have metadata-based commands, use them
+    if (commandsWithMetadata.length > 0) {
+      return commandsWithMetadata;
+    }
+
+    // Backwards compatibility: No metadata found, show first 12 commands
+    return agent.commands.slice(0, 12);
+  }
+
+  /**
+   * Get visibility filter for session type
+   * @private
+   * @param {string} sessionType - Session type
+   * @returns {string} Visibility level ('full', 'quick', 'key')
+   */
+  _getVisibilityFilter(sessionType) {
+    switch (sessionType) {
+      case 'new':
+        return 'full';
+      case 'existing':
+        return 'quick';
+      case 'workflow':
+        return 'key';
+      default:
+        return 'full';
+    }
+  }
+
+  /**
+   * Safe session type detection with fallback
+   * @private
+   * @param {Object} context - Session context
+   * @returns {Promise<string>} Session type
+   */
+  async _safeDetectSessionType(context) {
+    try {
+      const conversationHistory = context.conversationHistory || [];
+      return this.contextDetector.detectSessionType(conversationHistory);
+    } catch (error) {
+      console.warn('[GreetingBuilder] Session detection failed:', error.message);
+      return 'new'; // Conservative default
+    }
+  }
+
+  /**
+   * Safe git config check with fallback
+   * @private
+   * @returns {Promise<Object>} Git config result
+   */
+  async _safeCheckGitConfig() {
+    try {
+      return this.gitConfigDetector.get();
+    } catch (error) {
+      console.warn('[GreetingBuilder] Git config check failed:', error.message);
+      return { configured: false, type: null, branch: null };
+    }
+  }
+
+  /**
+   * Safe project status load with fallback
+   * @private
+   * @returns {Promise<Object|null>} Project status or null
+   */
+  async _safeLoadProjectStatus() {
+    try {
+      return await loadProjectStatus();
+    } catch (error) {
+      console.warn('[GreetingBuilder] Project status load failed:', error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Safe permission badge retrieval with fallback
+   * @private
+   * @returns {Promise<string>} Permission mode badge or empty string
+   */
+  async _safeGetPermissionBadge() {
+    try {
+      const mode = new PermissionMode();
+      await mode.load();
+      return mode.getBadge();
+    } catch (error) {
+      console.warn('[GreetingBuilder] Permission mode load failed:', error.message);
+      return '';
+    }
+  }
+
+  /**
+   * Check if git warning should be shown
+   * @private
+   * @returns {boolean} True if should show warning
+   */
+  _shouldShowGitWarning() {
+    if (!this.config || !this.config.git) {
+      return true; // Default: show warning
+    }
+
+    return this.config.git.showConfigWarning !== false;
+  }
+
+  /**
+   * Load core configuration
+   * @private
+   * @returns {Object|null} Configuration or null
+   */
+  _loadConfig() {
+    try {
+      const configPath = path.join(process.cwd(), '.grimoire', 'core-config.yaml');
+      const content = fs.readFileSync(configPath, 'utf8');
+      return yaml.load(content);
+    } catch (_error) {
+      return null;
+    }
+  }
+}
+
+module.exports = GreetingBuilder;
+
+