feat: add LLM enrichment to commit-msg hook (GIT-87)

src/application/handlers/CommitMsgHandler.ts

@@ -4,6 +4,10 @@
  * Handles the commit-msg git hook event.
  * Analyzes the commit message, infers memory metadata,
  * and appends AI-* trailers to the commit message file.
+ *
+ * When LLM enrichment is enabled and available, uses Claude to generate
+ * richer trailer content based on the staged diff. Falls back to heuristic
+ * analysis if enrichment fails or is unavailable.
  */
 
 import { readFileSync } from 'fs';
@@ -23,14 +27,19 @@ import {
 import type { IAgentResolver } from '../../domain/interfaces/IAgentResolver';
 import type { IHookConfigLoader } from '../../domain/interfaces/IHookConfigLoader';
 import type { ICommitMsgConfig } from '../../domain/interfaces/IHookConfig';
+import type { ILLMClient, ILLMExtractedFact } from '../../domain/interfaces/ILLMClient';
+
+/** Maximum diff size to send to LLM (10KB). */
+const MAX_DIFF_LENGTH = 10_000;
 
 export class CommitMsgHandler implements IEventHandler<ICommitMsgEvent> {
   constructor(
     private readonly commitAnalyzer: ICommitAnalyzer,
     private readonly gitClient: IGitClient,
     private readonly logger: ILogger,
     private readonly agentResolver: IAgentResolver,
-    private readonly configLoader: IHookConfigLoader
+    private readonly configLoader: IHookConfigLoader,
+    private readonly llmClient?: ILLMClient | null,
   ) {}
 
   async handle(event: ICommitMsgEvent): Promise<IEventResult> {
@@ -63,30 +72,48 @@ export class CommitMsgHandler implements IEventHandler<ICommitMsgEvent> {
         return { handler: 'CommitMsgHandler', success: true };
       }
 
-      // 5. Get staged files (only if inferTags is enabled)
-      const stagedFiles = config.inferTags
-        ? this.gitClient.diffStagedNames(event.cwd)
-        : [];
+      // 5. Get staged files (for tags and enrichment)
+      const stagedFiles = this.gitClient.diffStagedNames(event.cwd);
 
-      // 6. Analyze the commit message
-      const analysis = this.commitAnalyzer.analyze(message, stagedFiles);
+      // 6. Attempt LLM enrichment if enabled and available
+      const shouldEnrich = config.enrich && this.llmClient != null;
+      let enrichedFacts: ILLMExtractedFact[] | null = null;
 
-      // 7. Check requireType config - skip if no type detected and requireType is true
-      if (config.requireType && !analysis.type) {
-        this.logger.debug('No memory type detected and requireType is true, skipping');
-        return { handler: 'CommitMsgHandler', success: true };
+      if (shouldEnrich) {
+        enrichedFacts = await this.attemptEnrichment(
+          message,
+          stagedFiles,
+          config.enrichTimeout,
+          event.cwd,
+        );
       }
 
-      // 8. Build trailers (skip Agent/Model if already present from prepare-commit-msg)
-      const trailers = this.buildTrailers(analysis, config, message);
+      // 7. Build trailers - use enrichment if available, else heuristic
+      let trailers: ITrailer[];
+      let source: 'llm-enrichment' | 'heuristic';
+
+      if (enrichedFacts && enrichedFacts.length > 0) {
+        trailers = this.buildEnrichedTrailers(enrichedFacts, config, message);
+        source = 'llm-enrichment';
+      } else {
+        // Fallback to heuristic analysis
+        const analysis = this.commitAnalyzer.analyze(message, stagedFiles);
+
+        // Check requireType config - skip if no type detected and requireType is true
+        if (config.requireType && !analysis.type) {
+          this.logger.debug('No memory type detected and requireType is true, skipping');
+          return { handler: 'CommitMsgHandler', success: true };
+        }
+
+        trailers = this.buildTrailers(analysis, config, message);
+        source = 'heuristic';
+      }
 
-      // 9. Append trailers to the commit message using git interpret-trailers
+      // 8. Append trailers to the commit message using git interpret-trailers
       await this.appendTrailers(event.commitMsgPath, trailers, event.cwd);
 
       this.logger.info('Commit message analyzed and trailers added', {
-        type: analysis.type,
-        tags: analysis.tags,
-        confidence: analysis.confidence,
+        source,
         trailerCount: trailers.length,
       });
 
@@ -104,6 +131,79 @@ export class CommitMsgHandler implements IEventHandler<ICommitMsgEvent> {
     }
   }
 
+  /**
+   * Attempt LLM enrichment with timeout.
+   * Returns extracted facts on success, null on failure or timeout.
+   */
+  private async attemptEnrichment(
+    message: string,
+    stagedFiles: string[],
+    timeoutMs: number,
+    cwd: string,
+  ): Promise<ILLMExtractedFact[] | null> {
+    if (!this.llmClient) return null;
+
+    try {
+      // Get staged diff for LLM context
+      const diff = this.gitClient.diffStaged(cwd);
+      const truncatedDiff = this.truncateDiff(diff, MAX_DIFF_LENGTH);
+
+      // Parse commit message for LLM input
+      const lines = message.split('\n');
+      const subject = lines[0] || '';
+      const body = lines.slice(2).join('\n').trim(); // Skip blank line after subject
+
+      // Race enrichment against timeout
+      const enrichmentPromise = this.llmClient.enrichCommit({
+        sha: 'staged', // No SHA yet - use placeholder
+        subject,
+        body,
+        diff: truncatedDiff,
+        filesChanged: stagedFiles,
+      });
+
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+      const timeoutPromise = new Promise<null>((resolve) => {
+        timeoutId = setTimeout(() => resolve(null), timeoutMs);
+      });
+
+      const result = await Promise.race([enrichmentPromise, timeoutPromise]);
+
+      // Clear timeout if enrichment completed first
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+
+      if (result === null) {
+        this.logger.warn('LLM enrichment timed out', { timeoutMs });
+        return null;
+      }
+
+      this.logger.debug('LLM enrichment successful', {
+        factsExtracted: result.facts.length,
+        inputTokens: result.usage.inputTokens,
+        outputTokens: result.usage.outputTokens,
+      });
+
+      return [...result.facts];
+    } catch (error) {
+      this.logger.warn('LLM enrichment failed, falling back to heuristic', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return null;
+    }
+  }
+
+  /**
+   * Truncate diff to max length, preserving line boundaries.
+   */
+  private truncateDiff(diff: string, maxLength: number): string {
+    if (diff.length <= maxLength) return diff;
+    const truncated = diff.slice(0, maxLength);
+    const lastNewline = truncated.lastIndexOf('\n');
+    return lastNewline > 0 ? truncated.slice(0, lastNewline) : truncated;
+  }
+
   /**
    * Check if analysis should be skipped for special commit types.
    * Returns the skip reason, or null if analysis should proceed.
@@ -155,7 +255,99 @@ export class CommitMsgHandler implements IEventHandler<ICommitMsgEvent> {
   }
 
   /**
-   * Build all AI-* trailers from the analysis result.
+   * Build trailers from LLM enrichment results.
+   */
+  private buildEnrichedTrailers(
+    facts: ILLMExtractedFact[],
+    config: ICommitMsgConfig,
+    existingMessage: string,
+  ): ITrailer[] {
+    const trailers: ITrailer[] = [];
+
+    // Agent and Model trailers (skip if already present)
+    const hasAgent = existingMessage.includes('AI-Agent:');
+    const hasModel = existingMessage.includes('AI-Model:');
+
+    if (!hasAgent) {
+      const agent = this.agentResolver.resolveAgent();
+      if (agent) trailers.push({ key: AI_TRAILER_KEYS.AGENT, value: agent });
+    }
+    if (!hasModel) {
+      const model = this.agentResolver.resolveModel();
+      if (model) trailers.push({ key: AI_TRAILER_KEYS.MODEL, value: model });
+    }
+
+    // Select best fact for primary trailer (highest priority type/confidence)
+    const bestFact = this.selectBestFact(facts);
+
+    if (bestFact) {
+      const trailerKey = MEMORY_TYPE_TO_TRAILER_KEY[bestFact.type];
+      if (trailerKey) {
+        const truncatedContent = bestFact.content.slice(0, 200);
+        trailers.push({ key: trailerKey, value: truncatedContent });
+      }
+
+      // Use confidence from LLM
+      trailers.push({ key: AI_TRAILER_KEYS.CONFIDENCE, value: bestFact.confidence });
+
+      // Merge tags from all facts (respect inferTags setting)
+      if (config.inferTags) {
+        const allTags = new Set<string>();
+        for (const fact of facts) {
+          for (const tag of fact.tags) {
+            allTags.add(tag);
+          }
+        }
+        if (allTags.size > 0) {
+          trailers.push({ key: AI_TRAILER_KEYS.TAGS, value: [...allTags].join(', ') });
+        }
+      }
+    }
+
+    // Lifecycle from config
+    trailers.push({ key: AI_TRAILER_KEYS.LIFECYCLE, value: config.defaultLifecycle });
+
+    // Memory ID
+    trailers.push({ key: AI_TRAILER_KEYS.MEMORY_ID, value: this.generateMemoryId() });
+
+    // Source indicator
+    trailers.push({ key: AI_TRAILER_KEYS.SOURCE, value: 'llm-enrichment' });
+
+    return trailers;
+  }
+
+  /**
+   * Select the best fact from LLM results.
+   * Priority: decision > gotcha > convention > fact
+   * Within same type: verified > high > medium > low
+   */
+  private selectBestFact(facts: ILLMExtractedFact[]): ILLMExtractedFact | null {
+    if (facts.length === 0) return null;
+
+    const typePriority: Record<string, number> = {
+      decision: 4,
+      gotcha: 3,
+      convention: 2,
+      fact: 1,
+    };
+
+    const confidencePriority: Record<string, number> = {
+      verified: 4,
+      high: 3,
+      medium: 2,
+      low: 1,
+      uncertain: 0,
+    };
+
+    return [...facts].sort((a, b) => {
+      const typeDiff = (typePriority[b.type] || 0) - (typePriority[a.type] || 0);
+      if (typeDiff !== 0) return typeDiff;
+      return (confidencePriority[b.confidence] || 0) - (confidencePriority[a.confidence] || 0);
+    })[0];
+  }
+
+  /**
+   * Build all AI-* trailers from the heuristic analysis result.
    * Skips Agent/Model if they already exist (from prepare-commit-msg).
    */
   private buildTrailers(
@@ -206,6 +398,9 @@ export class CommitMsgHandler implements IEventHandler<ICommitMsgEvent> {
     // Add memory ID for tracking
     trailers.push({ key: AI_TRAILER_KEYS.MEMORY_ID, value: this.generateMemoryId() });
 
+    // Source indicator for heuristic analysis
+    trailers.push({ key: AI_TRAILER_KEYS.SOURCE, value: 'heuristic' });
+
     return trailers;
   }
 

src/domain/entities/ITrailer.ts

@@ -34,6 +34,7 @@ export const AI_TRAILER_KEYS = {
   MEMORY_ID: 'AI-Memory-Id',
   AGENT: 'AI-Agent',
   MODEL: 'AI-Model',
+  SOURCE: 'AI-Source',
 } as const;
 
 /**

src/domain/interfaces/IHookConfig.ts

@@ -45,6 +45,10 @@ export interface ICommitMsgConfig {
   readonly requireType: boolean;
   /** Default memory lifecycle. */
   readonly defaultLifecycle: 'permanent' | 'project' | 'session';
+  /** Enable LLM enrichment for richer trailer content. Requires ANTHROPIC_API_KEY. */
+  readonly enrich: boolean;
+  /** Timeout in ms for LLM enrichment call. Default: 5000. */
+  readonly enrichTimeout: number;
 }
 
 export interface IHooksConfig {

src/hooks/utils/config.ts

@@ -23,6 +23,8 @@ const DEFAULTS: IHookConfig = {
       inferTags: true,
       requireType: false,
       defaultLifecycle: 'project',
+      enrich: true,
+      enrichTimeout: 5000,
     },
   },
 };

src/infrastructure/di/container.ts

@@ -93,13 +93,21 @@ export function createContainer(options?: IContainerOptions): AwilixContainer<IC
         container.cradle.logger,
         container.cradle.agentResolver,
         container.cradle.hookConfigLoader,
+        container.cradle.llmClient,
       ));
 
       return bus;
     }).singleton(),
 
     llmClient: asFunction(() => {
-      return options?.enrich ? (createLLMClient() ?? null) : null;
+      // When enrich is explicitly false, do not create LLM client.
+      // When enrich is true or not specified, attempt to create it.
+      // This allows hooks to use LLM enrichment without explicit opt-in,
+      // while still respecting explicit enrich:false from CLI commands.
+      if (options?.enrich === false) {
+        return null;
+      }
+      return createLLMClient() ?? null;
     }).singleton(),
 
     // ── Application services ─────────────────────────────────────