feat(#27): implement intent classification service

Implement intent classification for natural language queries in the brain module.

Features:
- Hybrid classification approach: rule-based (fast, <100ms) with optional LLM fallback
- 10 intent types: query_tasks, query_events, query_projects, create_task, create_event, update_task, update_event, briefing, search, unknown
- Entity extraction: dates, times, priorities, statuses, people
- Pattern-based matching with priority system (higher priority = checked first)
- Optional LLM classification for ambiguous queries
- POST /api/brain/classify endpoint

Implementation:
- IntentClassificationService with classify(), classifyWithRules(), classifyWithLlm(), extractEntities()
- Comprehensive regex patterns for common query types
- Entity extraction for dates, times, priorities, statuses, mentions
- Type-safe interfaces for IntentType, IntentClassification, ExtractedEntity, IntentPattern
- ClassifyIntentDto and IntentClassificationResultDto for API validation
- Integrated with existing LlmService (optional dependency)

Testing:
- 60 comprehensive tests covering all intent types
- Edge cases: empty queries, special characters, case sensitivity, multiple whitespace
- Entity extraction tests with position tracking
- LLM fallback tests with error handling
- 100% test coverage
- All tests passing (60/60)
- TDD approach: tests written first

Quality:
- No explicit any types
- Explicit return types on all functions
- No TypeScript errors
- Build successful
- Follows existing code patterns
- Quality Rails compliance: All lint checks pass

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

apps/api/src/brain/brain.controller.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, it, vi, beforeEach } from "vitest";
 import { BrainController } from "./brain.controller";
 import { BrainService, BrainQueryResult, BrainContext } from "./brain.service";
+import { IntentClassificationService } from "./intent-classification.service";
+import type { IntentClassification } from "./interfaces";
 import { TaskStatus, TaskPriority, ProjectStatus, EntityType } from "@prisma/client";
 
 describe("BrainController", () => {
@@ -10,6 +12,9 @@ describe("BrainController", () => {
     getContext: ReturnType<typeof vi.fn>;
     search: ReturnType<typeof vi.fn>;
   };
+  let mockIntentService: {
+    classify: ReturnType<typeof vi.fn>;
+  };
 
   const mockWorkspaceId = "123e4567-e89b-12d3-a456-426614174000";
 
@@ -97,6 +102,14 @@ describe("BrainController", () => {
     ],
   };
 
+  const mockIntentResult: IntentClassification = {
+    intent: "query_tasks",
+    confidence: 0.9,
+    entities: [],
+    method: "rule",
+    query: "show my tasks",
+  };
+
   beforeEach(() => {
     mockService = {
       query: vi.fn().mockResolvedValue(mockQueryResult),
@@ -104,7 +117,14 @@ describe("BrainController", () => {
       search: vi.fn().mockResolvedValue(mockQueryResult),
     };
 
-    controller = new BrainController(mockService as unknown as BrainService);
+    mockIntentService = {
+      classify: vi.fn().mockResolvedValue(mockIntentResult),
+    };
+
+    controller = new BrainController(
+      mockService as unknown as BrainService,
+      mockIntentService as unknown as IntentClassificationService
+    );
   });
 
   describe("query", () => {
@@ -155,10 +175,7 @@ describe("BrainController", () => {
     });
 
     it("should return query result structure", async () => {
-      const result = await controller.query(
-        { workspaceId: mockWorkspaceId },
-        mockWorkspaceId
-      );
+      const result = await controller.query({ workspaceId: mockWorkspaceId }, mockWorkspaceId);
 
       expect(result).toHaveProperty("tasks");
       expect(result).toHaveProperty("events");
@@ -204,10 +221,7 @@ describe("BrainController", () => {
     });
 
     it("should return context structure", async () => {
-      const result = await controller.getContext(
-        { workspaceId: mockWorkspaceId },
-        mockWorkspaceId
-      );
+      const result = await controller.getContext({ workspaceId: mockWorkspaceId }, mockWorkspaceId);
 
       expect(result).toHaveProperty("timestamp");
       expect(result).toHaveProperty("workspace");
@@ -276,4 +290,90 @@ describe("BrainController", () => {
       expect(result).toHaveProperty("meta");
     });
   });
+
+  describe("classifyIntent", () => {
+    it("should call intentService.classify with query", async () => {
+      const dto = { query: "show my tasks" };
+
+      const result = await controller.classifyIntent(dto);
+
+      expect(mockIntentService.classify).toHaveBeenCalledWith("show my tasks", undefined);
+      expect(result).toEqual(mockIntentResult);
+    });
+
+    it("should pass useLlm flag when provided", async () => {
+      const dto = { query: "show my tasks", useLlm: true };
+
+      await controller.classifyIntent(dto);
+
+      expect(mockIntentService.classify).toHaveBeenCalledWith("show my tasks", true);
+    });
+
+    it("should return intent classification structure", async () => {
+      const result = await controller.classifyIntent({ query: "show my tasks" });
+
+      expect(result).toHaveProperty("intent");
+      expect(result).toHaveProperty("confidence");
+      expect(result).toHaveProperty("entities");
+      expect(result).toHaveProperty("method");
+      expect(result).toHaveProperty("query");
+    });
+
+    it("should handle different intent types", async () => {
+      const briefingResult: IntentClassification = {
+        intent: "briefing",
+        confidence: 0.95,
+        entities: [],
+        method: "rule",
+        query: "morning briefing",
+      };
+      mockIntentService.classify.mockResolvedValue(briefingResult);
+
+      const result = await controller.classifyIntent({ query: "morning briefing" });
+
+      expect(result.intent).toBe("briefing");
+      expect(result.confidence).toBe(0.95);
+    });
+
+    it("should handle intent with entities", async () => {
+      const resultWithEntities: IntentClassification = {
+        intent: "create_task",
+        confidence: 0.9,
+        entities: [
+          {
+            type: "priority",
+            value: "HIGH",
+            raw: "high priority",
+            start: 12,
+            end: 25,
+          },
+        ],
+        method: "rule",
+        query: "create task high priority",
+      };
+      mockIntentService.classify.mockResolvedValue(resultWithEntities);
+
+      const result = await controller.classifyIntent({ query: "create task high priority" });
+
+      expect(result.entities).toHaveLength(1);
+      expect(result.entities[0].type).toBe("priority");
+      expect(result.entities[0].value).toBe("HIGH");
+    });
+
+    it("should handle LLM classification", async () => {
+      const llmResult: IntentClassification = {
+        intent: "search",
+        confidence: 0.85,
+        entities: [],
+        method: "llm",
+        query: "find something",
+      };
+      mockIntentService.classify.mockResolvedValue(llmResult);
+
+      const result = await controller.classifyIntent({ query: "find something", useLlm: true });
+
+      expect(result.method).toBe("llm");
+      expect(result.intent).toBe("search");
+    });
+  });
 });