@soleri/core 9.3.0 → 9.4.0

package/src/brain/extraction-quality.test.ts

@@ -0,0 +1,323 @@
+/**
+ * TDD tests for brain extraction quality (issue #359).
+ *
+ * These tests define the DESIRED behavior of extractKnowledge().
+ * They are expected to FAIL against the current implementation.
+ * Implementation fixes come in issues #360-#366.
+ *
+ * What's wrong today:
+ * - plan_completed rule produces generic "Successful plan: {id}" titles
+ * - Extraction rules never read session.context (objective, scope, decisions)
+ * - No dedup: same rule + sessionId can produce duplicate proposals
+ * - long_session rule fires with low-value noise (to be removed in #360)
+ * - No drift_detected rule exists yet (to be added in #366)
+ * - Confidence is not adjusted based on context richness
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createAgentRuntime } from '../runtime/runtime.js';
+import type { AgentRuntime } from '../runtime/types.js';
+
+describe('Extraction Quality', () => {
+  let runtime: AgentRuntime;
+  let plannerDir: string;
+
+  beforeEach(() => {
+    plannerDir = join(tmpdir(), 'extraction-quality-test-' + Date.now());
+    mkdirSync(plannerDir, { recursive: true });
+    runtime = createAgentRuntime({
+      agentId: 'test-extraction-quality',
+      vaultPath: ':memory:',
+      plansPath: join(plannerDir, 'plans.json'),
+    });
+  });
+
+  afterEach(() => {
+    runtime.close();
+    rmSync(plannerDir, { recursive: true, force: true });
+  });
+
+  // ─── Helper ────────────────────────────────────────────────────────
+
+  function createSessionWithContext(
+    sessionId: string,
+    context: string,
+    overrides: {
+      planId?: string;
+      planOutcome?: string;
+      toolsUsed?: string[];
+      filesModified?: string[];
+      domain?: string;
+    } = {},
+  ) {
+    runtime.brainIntelligence.lifecycle({
+      action: 'start',
+      sessionId,
+      domain: overrides.domain ?? 'testing',
+      context,
+      toolsUsed: overrides.toolsUsed ?? [],
+      filesModified: overrides.filesModified ?? [],
+      planId: overrides.planId,
+    });
+    runtime.brainIntelligence.lifecycle({
+      action: 'end',
+      sessionId,
+      planOutcome: overrides.planOutcome,
+      toolsUsed: overrides.toolsUsed,
+      filesModified: overrides.filesModified,
+    });
+  }
+
+  // ─── 1. Actionable titles from rich context ───────────────────────
+
+  describe('actionable proposals from session context', () => {
+    it('should use session context objective in plan_completed proposal title', () => {
+      const richContext = JSON.stringify({
+        objective: 'Add OAuth2 authentication to the API gateway',
+        scope: { included: ['auth module', 'gateway routes'], excluded: ['frontend'] },
+        decisions: ['Use passport.js for OAuth2 strategy'],
+      });
+
+      createSessionWithContext('rich-ctx-1', richContext, {
+        planId: 'plan-oauth',
+        planOutcome: 'completed',
+      });
+
+      const result = runtime.brainIntelligence.extractKnowledge('rich-ctx-1');
+      const planProposal = result.proposals.find((p) => p.rule === 'plan_completed');
+
+      expect(planProposal).toBeDefined();
+      // The title should reference the objective, not just the plan ID
+      expect(planProposal!.title).not.toContain('Successful plan:');
+      expect(planProposal!.title.toLowerCase()).toContain('oauth');
+    });
+
+    it('should use session context objective in plan_abandoned proposal title', () => {
+      const richContext = JSON.stringify({
+        objective: 'Migrate database from Postgres to CockroachDB',
+        scope: { included: ['migration scripts', 'connection pool'] },
+      });
+
+      createSessionWithContext('rich-ctx-2', richContext, {
+        planId: 'plan-migrate',
+        planOutcome: 'abandoned',
+      });
+
+      const result = runtime.brainIntelligence.extractKnowledge('rich-ctx-2');
+      const abandonedProposal = result.proposals.find((p) => p.rule === 'plan_abandoned');
+
+      expect(abandonedProposal).toBeDefined();
+      // The title should reference what was abandoned, not just the plan ID
+      expect(abandonedProposal!.title).not.toContain('Abandoned plan:');
+      expect(abandonedProposal!.title.toLowerCase()).toContain('migrate');
+    });
+
+    it('should include scope details in proposal description when context has scope', () => {
+      const richContext = JSON.stringify({
+        objective: 'Refactor the billing reconciliation module',
+        scope: {
+          included: ['stripe-adapter', 'webhook-handler', 'ledger-service'],
+          excluded: ['billing-ui', 'invoice-generator'],
+        },
+      });
+
+      createSessionWithContext('rich-ctx-3', richContext, {
+        planId: 'plan-abc',
+        planOutcome: 'completed',
+      });
+
+      const result = runtime.brainIntelligence.extractKnowledge('rich-ctx-3');
+      const planProposal = result.proposals.find((p) => p.rule === 'plan_completed');
+
+      expect(planProposal).toBeDefined();
+      // Description should mention scope components, not just "can be reused for similar tasks"
+      expect(planProposal!.description.toLowerCase()).toMatch(/stripe|webhook|ledger/);
+    });
+  });
+
+  // ─── 2. Dedup: same rule + sessionId = 1 proposal ────────────────
+
+  describe('proposal deduplication', () => {
+    it('should produce exactly 1 proposal per rule per session', () => {
+      createSessionWithContext('dedup-1', 'some context', {
+        planId: 'plan-dedup',
+        planOutcome: 'completed',
+      });
+
+      // Extract twice on same session (reset extractedAt in between)
+      runtime.brainIntelligence.extractKnowledge('dedup-1');
+      runtime.brainIntelligence.resetExtracted({ sessionId: 'dedup-1' });
+      runtime.brainIntelligence.extractKnowledge('dedup-1');
+
+      // Query all proposals for this session
+      const proposals = runtime.brainIntelligence.getProposals({
+        sessionId: 'dedup-1',
+      });
+
+      // Count proposals per rule
+      const ruleCounts = new Map<string, number>();
+      for (const p of proposals) {
+        ruleCounts.set(p.rule, (ruleCounts.get(p.rule) ?? 0) + 1);
+      }
+
+      // Each rule should appear at most once per session
+      for (const [rule, count] of ruleCounts) {
+        expect(count, `rule "${rule}" should appear exactly once`).toBe(1);
+      }
+    });
+  });
+
+  // ─── 3. long_session rule should not fire ─────────────────────────
+
+  describe('long_session rule removal', () => {
+    it('should NOT produce a long_session proposal', () => {
+      // Create session manually with backdated start time to simulate >30 min duration.
+      // SQLite datetime('now') uses 'YYYY-MM-DD HH:MM:SS' format (no T/Z), so match that.
+      const d = new Date(Date.now() - 35 * 60 * 1000);
+      const thirtyFiveMinAgo = d
+        .toISOString()
+        .replace('T', ' ')
+        .replace(/\.\d{3}Z$/, '');
+      const provider = runtime.vault.getProvider();
+
+      // Insert session directly with backdated started_at so auto-extract sees the long duration
+      provider.run(
+        `INSERT INTO brain_sessions (id, started_at, domain, context, tools_used, files_modified)
+         VALUES (?, ?, ?, ?, ?, ?)`,
+        ['long-sess-1', thirtyFiveMinAgo, 'testing', null, '[]', '[]'],
+      );
+
+      // End the session — this sets ended_at to now(), creating a >30 min gap
+      runtime.brainIntelligence.lifecycle({
+        action: 'end',
+        sessionId: 'long-sess-1',
+        toolsUsed: ['search'], // need at least 1 tool for auto-extract gate
+      });
+
+      // Reset extracted_at so we can manually extract and inspect
+      runtime.brainIntelligence.resetExtracted({ sessionId: 'long-sess-1' });
+
+      const result = runtime.brainIntelligence.extractKnowledge('long-sess-1');
+
+      // long_session rule should no longer exist (removal in #360)
+      expect(result.rulesApplied).not.toContain('long_session');
+      expect(result.proposals.find((p) => p.rule === 'long_session')).toBeUndefined();
+    });
+  });
+
+  // ─── 4. drift_detected rule ───────────────────────────────────────
+
+  describe('drift_detected rule', () => {
+    it('should fire when session context contains drift indicators', () => {
+      const contextWithDrift = JSON.stringify({
+        objective: 'Implement caching layer for API responses',
+        drift: {
+          items: [
+            {
+              type: 'added',
+              description: 'Added Redis fallback to in-memory cache',
+              impact: 'medium',
+            },
+            {
+              type: 'skipped',
+              description: 'Skipped cache invalidation webhooks',
+              impact: 'high',
+            },
+          ],
+          accuracyScore: 65,
+        },
+      });
+
+      createSessionWithContext('drift-1', contextWithDrift, {
+        planId: 'plan-cache',
+        planOutcome: 'completed',
+      });
+
+      const result = runtime.brainIntelligence.extractKnowledge('drift-1');
+
+      // A drift_detected rule should fire (to be added in #366)
+      expect(result.rulesApplied).toContain('drift_detected');
+      const driftProposal = result.proposals.find((p) => p.rule === 'drift_detected');
+      expect(driftProposal).toBeDefined();
+      expect(driftProposal!.type).toBe('anti-pattern');
+      expect(driftProposal!.description.toLowerCase()).toMatch(/drift|skipped|deviation/);
+    });
+
+    it('should NOT fire drift_detected when context has no drift', () => {
+      const cleanContext = JSON.stringify({
+        objective: 'Add unit tests for auth module',
+        scope: { included: ['auth'] },
+      });
+
+      createSessionWithContext('no-drift-1', cleanContext, {
+        planId: 'plan-tests',
+        planOutcome: 'completed',
+      });
+
+      const result = runtime.brainIntelligence.extractKnowledge('no-drift-1');
+      expect(result.rulesApplied).not.toContain('drift_detected');
+    });
+  });
+
+  // ─── 5. Context richness affects confidence ───────────────────────
+
+  describe('confidence based on context richness', () => {
+    it('should assign higher confidence to proposals with rich session context', () => {
+      // Session with rich context
+      const richContext = JSON.stringify({
+        objective: 'Build notification service',
+        scope: { included: ['notifications', 'email-adapter', 'push-adapter'] },
+        decisions: ['Use event-driven architecture', 'SNS for push notifications'],
+      });
+
+      createSessionWithContext('conf-rich', richContext, {
+        planId: 'plan-notify-rich',
+        planOutcome: 'completed',
+      });
+
+      // Session with no context
+      createSessionWithContext('conf-empty', '', {
+        planId: 'plan-notify-empty',
+        planOutcome: 'completed',
+      });
+
+      const richResult = runtime.brainIntelligence.extractKnowledge('conf-rich');
+      runtime.brainIntelligence.resetExtracted({ sessionId: 'conf-empty' });
+      const emptyResult = runtime.brainIntelligence.extractKnowledge('conf-empty');
+
+      const richPlanProposal = richResult.proposals.find((p) => p.rule === 'plan_completed');
+      const emptyPlanProposal = emptyResult.proposals.find((p) => p.rule === 'plan_completed');
+
+      expect(richPlanProposal).toBeDefined();
+      expect(emptyPlanProposal).toBeDefined();
+
+      // Rich context should produce higher confidence than empty context
+      expect(richPlanProposal!.confidence).toBeGreaterThan(emptyPlanProposal!.confidence);
+    });
+
+    it('should assign lower confidence when session context is null', () => {
+      // Session with null context (no context field at all)
+      runtime.brainIntelligence.lifecycle({
+        action: 'start',
+        sessionId: 'conf-null',
+        planId: 'plan-null-ctx',
+      });
+      runtime.brainIntelligence.lifecycle({
+        action: 'end',
+        sessionId: 'conf-null',
+        planOutcome: 'completed',
+      });
+
+      runtime.brainIntelligence.resetExtracted({ sessionId: 'conf-null' });
+      const result = runtime.brainIntelligence.extractKnowledge('conf-null');
+      const planProposal = result.proposals.find((p) => p.rule === 'plan_completed');
+
+      expect(planProposal).toBeDefined();
+      // Without context, confidence should be below the current hardcoded 0.65
+      expect(planProposal!.confidence).toBeLessThan(0.65);
+    });
+  });
+});

package/src/brain/intelligence.ts

@@ -38,7 +38,6 @@ const SPREAD_MAX = 5;
 const RECENCY_DECAY_DAYS = 30;
 const EXTRACTION_TOOL_THRESHOLD = 3;
 const EXTRACTION_FILE_THRESHOLD = 3;
-const EXTRACTION_LONG_SESSION_MINUTES = 30;
 const EXTRACTION_HIGH_FEEDBACK_RATIO = 0.8;
 const AUTO_PROMOTE_THRESHOLD = 0.8;
 const AUTO_PROMOTE_PENDING_MIN = 0.4;
@@ -739,10 +738,18 @@ export class BrainIntelligence {
     for (const [tool, count] of toolCounts) {
       if (count >= EXTRACTION_TOOL_THRESHOLD) {
         rulesApplied.push('repeated_tool_usage');
+        const ctx = session.context ?? '';
+        const objective = this.extractObjective(ctx);
+        const toolTitle = objective
+          ? `Tool pattern: ${tool} (${count}x) during ${objective.slice(0, 60)}`
+          : `Frequent use of ${tool} (${count}x)`;
+        const toolDescription = objective
+          ? `Tool ${tool} used ${count} times while working on: ${objective}. This tool-task pairing may indicate a reusable workflow.`
+          : `Tool ${tool} was used ${count} times in session. Consider automating or abstracting this workflow.`;
         proposals.push(
           this.createProposal(sessionId, 'repeated_tool_usage', 'pattern', {
-            title: `Frequent use of ${tool}`,
-            description: `Tool ${tool} was used ${count} times in session. Consider automating or abstracting this workflow.`,
+            title: toolTitle,
+            description: toolDescription,
             confidence: Math.min(0.9, 0.5 + count * 0.1),
           }),
         );
@@ -766,57 +773,107 @@ export class BrainIntelligence {
       if (significantDirs.length > 0) {
         const [topDir, topFiles] = significantDirs.sort((a, b) => b[1].length - a[1].length)[0];
         rulesApplied.push('multi_file_edit');
+        const ctx = session.context ?? '';
+        const objective = this.extractObjective(ctx);
+        const isRefactor = /refactor|rename|move|extract|consolidat/i.test(ctx);
+        const isFeature = /feat|add|implement|create|new/i.test(ctx);
+        const inferredPattern = isRefactor
+          ? 'Refactoring'
+          : isFeature
+            ? 'Feature'
+            : 'Cross-cutting change';
+        const mfeTitle = objective
+          ? `${inferredPattern}: ${objective.slice(0, 70)}`
+          : `${inferredPattern} in ${topDir} (${topFiles.length} files)`;
+        const mfeDescription = objective
+          ? `${inferredPattern} across ${topFiles.length} files in ${topDir}: ${objective}`
+          : `Session modified ${topFiles.length} files in ${topDir}: ${topFiles.slice(0, 5).join(', ')}${topFiles.length > 5 ? '...' : ''}.`;
         proposals.push(
           this.createProposal(sessionId, 'multi_file_edit', 'pattern', {
-            title: `Multi-file change pattern in ${topDir} (${topFiles.length} files)`,
-            description: `Session modified ${topFiles.length} files in ${topDir}: ${topFiles.slice(0, 5).join(', ')}${topFiles.length > 5 ? '...' : ''}. This may indicate an architectural pattern.`,
+            title: mfeTitle,
+            description: mfeDescription,
             confidence: Math.min(0.8, 0.4 + topFiles.length * 0.05),
           }),
         );
       }
     }
 
-    // Rule 3: Long session (>30min) — neutral observation, not anti-pattern
-    if (session.endedAt && session.startedAt) {
-      const durationMs =
-        new Date(session.endedAt).getTime() - new Date(session.startedAt).getTime();
-      const durationMin = durationMs / 60000;
-      if (durationMin > EXTRACTION_LONG_SESSION_MINUTES) {
-        rulesApplied.push('long_session');
-        proposals.push(
-          this.createProposal(sessionId, 'long_session', 'pattern', {
-            title: `Long session (${Math.round(durationMin)} minutes)`,
-            description: `Session lasted ${Math.round(durationMin)} minutes. Deep work session — review if this duration was productive or indicates a need for better tooling.`,
-            confidence: 0.3,
-          }),
-        );
-      }
-    }
-
-    // Rule 4: Plan completed — moderate confidence to avoid auto-promoting generic entries
+    // Rule 3: Plan completed — parse session.context for actionable title + dynamic confidence
     if (session.planId && session.planOutcome === 'completed') {
       rulesApplied.push('plan_completed');
+      const ctx = session.context ?? '';
+      const objective = this.extractObjective(ctx);
+      const hasScope = /scope|included|excluded/i.test(ctx);
+      const hasCriteria = /criteria|acceptance|verification/i.test(ctx);
+      const confidence =
+        ctx.length > 0
+          ? hasScope && hasCriteria
+            ? 0.85
+            : hasScope || hasCriteria
+              ? 0.8
+              : 0.75
+          : 0.5;
+      const title = objective
+        ? `Workflow: ${objective.slice(0, 80)}`
+        : `Successful plan: ${session.planId}`;
+      const description = objective
+        ? `Completed: ${objective}${hasScope ? '. Scope and constraints documented in session context.' : ''}`
+        : `Plan ${session.planId} completed successfully. This workflow can be reused for similar tasks.`;
       proposals.push(
         this.createProposal(sessionId, 'plan_completed', 'workflow', {
-          title: `Successful plan: ${session.planId}`,
-          description: `Plan ${session.planId} completed successfully. This workflow can be reused for similar tasks.`,
-          confidence: 0.65,
+          title,
+          description,
+          confidence,
         }),
       );
     }
 
-    // Rule 5: Plan abandoned
+    // Rule 4: Plan abandoned — parse context for failure reason
     if (session.planId && session.planOutcome === 'abandoned') {
       rulesApplied.push('plan_abandoned');
+      const ctx = session.context ?? '';
+      const objective = this.extractObjective(ctx);
+      const hasFailureReason = /blocked|failed|wrong|mistake|abandoned|reverted|conflict/i.test(
+        ctx,
+      );
+      const confidence = ctx.length > 0 ? (hasFailureReason ? 0.85 : 0.75) : 0.5;
+      const title = objective
+        ? `Anti-pattern: ${objective.slice(0, 80)}`
+        : `Abandoned plan: ${session.planId}`;
+      const description = objective
+        ? `Abandoned: ${objective}${hasFailureReason ? '. Failure indicators found in session context — review for root cause.' : '. Review what went wrong to avoid repeating.'}`
+        : `Plan ${session.planId} was abandoned. Review what went wrong to avoid repeating in future sessions.`;
       proposals.push(
         this.createProposal(sessionId, 'plan_abandoned', 'anti-pattern', {
-          title: `Abandoned plan: ${session.planId}`,
-          description: `Plan ${session.planId} was abandoned. Review what went wrong to avoid repeating in future sessions.`,
-          confidence: 0.7,
+          title,
+          description,
+          confidence,
         }),
       );
     }
 
+    // Rule 5: Drift detected — fires when plan completed but context contains drift indicators
+    if (session.planId && session.planOutcome === 'completed' && session.context) {
+      const driftPattern =
+        /drift|skipped|added.*unplanned|changed scope|out of scope|deviat|unplanned/i;
+      if (driftPattern.test(session.context)) {
+        rulesApplied.push('drift_detected');
+        const objective = this.extractObjective(session.context);
+        const driftMatch =
+          session.context.match(/drift[:\s]+(.{1,120})/i) ??
+          session.context.match(/skipped[:\s]+(.{1,120})/i) ??
+          session.context.match(/unplanned[:\s]+(.{1,120})/i);
+        const driftDetail = driftMatch ? driftMatch[1].trim() : 'scope changed during execution';
+        proposals.push(
+          this.createProposal(sessionId, 'drift_detected', 'anti-pattern', {
+            title: `Plan drift: ${objective ? objective.slice(0, 60) : session.planId} — ${driftDetail.slice(0, 40)}`,
+            description: `Plan ${objective ?? session.planId} completed with drift: ${driftDetail}. Review scope controls for future planning.`,
+            confidence: 0.8,
+          }),
+        );
+      }
+    }
+
     // Rule 6: High feedback ratio (>80% accept or dismiss)
     const feedbackRow = this.provider.get<{
       total: number;
@@ -1369,12 +1426,58 @@ export class BrainIntelligence {
     };
   }
 
+  /**
+   * Extract the objective from session context — first meaningful sentence or line.
+   * Returns empty string if context is empty or unparseable.
+   */
+  private extractObjective(context: string): string {
+    if (!context || context.trim().length === 0) return '';
+    // Try to find an "Objective:" line
+    const objMatch = context.match(/objective[:\s]+(.+)/i);
+    if (objMatch) return objMatch[1].trim().replace(/\s+/g, ' ');
+    // Fall back to first non-empty line
+    const firstLine = context
+      .split('\n')
+      .map((l) => l.trim())
+      .find((l) => l.length > 0);
+    return firstLine ? firstLine.replace(/\s+/g, ' ') : '';
+  }
+
   private createProposal(
     sessionId: string,
     rule: string,
     type: 'pattern' | 'anti-pattern' | 'workflow',
     data: { title: string; description: string; confidence: number },
   ): KnowledgeProposal {
+    // Dedup guard: skip if a proposal with the same rule + sessionId already exists
+    const existing = this.provider.get<{
+      id: string;
+      session_id: string;
+      rule: string;
+      type: string;
+      title: string;
+      description: string;
+      confidence: number;
+      promoted: number;
+      created_at: string;
+    }>('SELECT * FROM brain_proposals WHERE session_id = ? AND rule = ? LIMIT 1', [
+      sessionId,
+      rule,
+    ]);
+    if (existing) {
+      return {
+        id: existing.id,
+        sessionId: existing.session_id,
+        rule: existing.rule,
+        type: existing.type as 'pattern' | 'anti-pattern' | 'workflow',
+        title: existing.title,
+        description: existing.description,
+        confidence: existing.confidence,
+        promoted: existing.promoted === 1,
+        createdAt: existing.created_at,
+      };
+    }
+
     const id = randomUUID();
     this.provider.run(
       `INSERT INTO brain_proposals (id, session_id, rule, type, title, description, confidence)

package/src/brain/learning-radar.ts

@@ -229,14 +229,17 @@ export class LearningRadar {
   }
 
   /**
-   * Dismiss a pending candidate — mark it as not worth capturing.
+   * Dismiss one or more pending candidates — mark them as not worth capturing.
    */
-  dismiss(candidateId: number): { dismissed: boolean } {
+  dismiss(candidateIds: number | number[]): { dismissed: number } {
+    const ids = Array.isArray(candidateIds) ? candidateIds : [candidateIds];
+    if (ids.length === 0) return { dismissed: 0 };
+    const placeholders = ids.map(() => '?').join(',');
     const result = this.provider.run(
-      "UPDATE radar_candidates SET status = 'dismissed' WHERE id = ? AND status = 'pending'",
-      [candidateId],
+      `UPDATE radar_candidates SET status = 'dismissed' WHERE id IN (${placeholders}) AND status = 'pending'`,
+      ids,
     );
-    return { dismissed: result.changes > 0 };
+    return { dismissed: result.changes };
   }
 
   /**

package/src/brain/second-brain-features.test.ts

@@ -335,7 +335,7 @@ describe('Ambient learning radar (#208)', () => {
     const pending = candidates.find((c) => c.title.includes('stale cache'));
     expect(pending).toBeDefined();
     const result = learningRadar.dismiss(pending!.id);
-    expect(result.dismissed).toBe(true);
+    expect(result.dismissed).toBe(1);
   });
 
   it('getStats returns radar statistics', () => {

package/src/control/intent-router.test.ts

@@ -35,7 +35,7 @@ describe('IntentRouter', () => {
   describe('construction', () => {
     it('seeds 10 default modes on first creation', () => {
       const modes = router.getModes();
-      expect(modes.length).toBe(10);
+      expect(modes.length).toBe(11);
     });
 
     it('starts in GENERAL-MODE', () => {
@@ -44,7 +44,7 @@ describe('IntentRouter', () => {
 
     it('is idempotent — second instance does not duplicate modes', () => {
       const router2 = new IntentRouter(vault);
-      expect(router2.getModes().length).toBe(10);
+      expect(router2.getModes().length).toBe(11);
     });
   });
 
@@ -199,7 +199,7 @@ describe('IntentRouter', () => {
     it('adds a new mode to the database', () => {
       router.registerMode(customMode);
       const modes = router.getModes();
-      expect(modes.length).toBe(11);
+      expect(modes.length).toBe(12);
       const found = modes.find((m) => m.mode === 'CUSTOM-MODE');
       expect(found).toBeDefined();
       expect(found!.keywords).toEqual(['custom', 'special']);
@@ -338,6 +338,76 @@ describe('IntentRouter', () => {
     });
   });
 
+  // ─── YOLO-MODE ───────────────────────────────────────────────
+
+  describe('YOLO-MODE', () => {
+    it('route_intent with "yolo" returns YOLO-MODE', () => {
+      const result = router.routeIntent('go yolo on this task');
+      expect(result.intent).toBe('yolo');
+      expect(result.mode).toBe('YOLO-MODE');
+      expect(result.matchedKeywords).toContain('yolo');
+    });
+
+    it('morph to YOLO-MODE succeeds when hook pack is installed', () => {
+      const result = router.morph('YOLO-MODE', { hookPackInstalled: true });
+      expect(result.previousMode).toBe('GENERAL-MODE');
+      expect(result.currentMode).toBe('YOLO-MODE');
+      expect(result.behaviorRules.length).toBe(5);
+      expect(result.blocked).toBeUndefined();
+      expect(result.error).toBeUndefined();
+    });
+
+    it('morph to YOLO-MODE fails when hook pack is missing', () => {
+      const result = router.morph('YOLO-MODE');
+      expect(result.blocked).toBe(true);
+      expect(result.error).toContain('yolo-safety hook pack');
+      expect(result.error).toContain('soleri hooks add-pack yolo-safety');
+      expect(result.currentMode).toBe('GENERAL-MODE'); // unchanged
+      expect(router.getCurrentMode()).toBe('GENERAL-MODE'); // not switched
+    });
+
+    it('morph to YOLO-MODE fails when hookPackInstalled is explicitly false', () => {
+      const result = router.morph('YOLO-MODE', { hookPackInstalled: false });
+      expect(result.blocked).toBe(true);
+      expect(result.error).toContain('yolo-safety hook pack');
+      expect(router.getCurrentMode()).toBe('GENERAL-MODE');
+    });
+
+    it('morph to other modes is unaffected by the gate', () => {
+      const result = router.morph('BUILD-MODE');
+      expect(result.currentMode).toBe('BUILD-MODE');
+      expect(result.blocked).toBeUndefined();
+      expect(result.error).toBeUndefined();
+      expect(router.getCurrentMode()).toBe('BUILD-MODE');
+    });
+
+    it('get_behavior_rules returns 5 rules', () => {
+      const rules = router.getBehaviorRules('YOLO-MODE');
+      expect(rules).toHaveLength(5);
+      expect(rules[0]).toContain('Skip plan approval gates');
+      expect(rules[1]).toContain('orchestrate_complete');
+      expect(rules[2]).toContain('vault gather-before-execute');
+      expect(rules[3]).toContain('Hook pack must be installed');
+      expect(rules[4]).toContain('exit YOLO');
+    });
+
+    it('all keywords route to YOLO-MODE', () => {
+      const keywords = [
+        'yolo',
+        'autonomous',
+        'fire-and-forget',
+        'hands-off',
+        'no-approval',
+        'skip-gates',
+        'full-auto',
+      ];
+      for (const kw of keywords) {
+        const result = router.routeIntent(kw);
+        expect(result.mode).toBe('YOLO-MODE');
+      }
+    });
+  });
+
   // ─── getModes ─────────────────────────────────────────────────
 
   describe('getModes', () => {