feat: brain defaults, active-work hooks, test coverage, #83 fix

Defaults (breaking: now opt-in by default):
- brain.embedding.enabled: false → true (vector search out of the box)
- brain.memoryBridge.contextAware: false → true (scope-aware bridge)
- brain.summarization.enabled: false → true (session summaries)

Active-work capture hooks:
- New work-capture-hooks.ts: onPromptSubmit/onResponseComplete handlers
- Smart filtering: only mutations, skip lifecycle-covered ops
- Gated behind brain.captureWork config (default: false, opt-in)
- Wired into CLI dispatch (cli.ts) for provider-agnostic capture
- Replaced env var gates in file-hooks.ts and mcp-hooks.ts with
  config-first + env var override pattern

Issue #83 fix:
- Added REQUIRED_SESSION_COLUMNS (provider_id, stats_json, resume_count,
  grade_mode) with ensureColumns() before migrateWithRetry()
- Follows existing REQUIRED_TASK_COLUMNS pattern

Test coverage:
- New brain-automation.test.ts: 55 tests across 9 feature groups
- Covers config, summarization, transcript, maintenance, embedding,
  queue, bridge refresh, context-aware generation

4912 tests passing, 0 failures.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kryptobaseddev

packages/cleo/src/dispatch/adapters/cli.ts

@@ -10,7 +10,7 @@
  */
 
 import { randomUUID } from 'node:crypto';
-import { autoRecordDispatchTokenUsage, getProjectRoot } from '@cleocode/core/internal';
+import { autoRecordDispatchTokenUsage, getProjectRoot, hooks } from '@cleocode/core/internal';
 import { type CliOutputOptions, cliError, cliOutput } from '../../cli/renderers/index.js';
 import { Dispatcher } from '../dispatcher.js';
 import { createDomainHandlers } from '../domains/index.js';
@@ -141,6 +141,22 @@ export async function dispatchFromCli(
   outputOpts?: CliOutputOptions,
 ): Promise<void> {
   const dispatcher = getCliDispatcher();
+  const projectRoot = getProjectRoot();
+  const dispatchStart = Date.now();
+
+  // Dispatch onPromptSubmit hook (best-effort, fire-and-forget)
+  hooks
+    .dispatch('onPromptSubmit', projectRoot, {
+      timestamp: new Date().toISOString(),
+      gateway,
+      domain,
+      operation,
+      source: 'cli',
+    })
+    .catch(() => {
+      /* hook errors are non-fatal */
+    });
+
   const response = await dispatcher.dispatch({
     gateway,
     domain,
@@ -150,6 +166,21 @@ export async function dispatchFromCli(
     requestId: randomUUID(),
   });
 
+  // Dispatch onResponseComplete hook (best-effort, fire-and-forget)
+  hooks
+    .dispatch('onResponseComplete', projectRoot, {
+      timestamp: new Date().toISOString(),
+      gateway,
+      domain,
+      operation,
+      success: response.success,
+      durationMs: Date.now() - dispatchStart,
+      errorCode: response.error?.code,
+    })
+    .catch(() => {
+      /* hook errors are non-fatal */
+    });
+
   if (response.success) {
     await autoRecordDispatchTokenUsage({
       requestPayload: params,
@@ -219,12 +250,45 @@ export async function dispatchRaw(
   params?: Record<string, unknown>,
 ): Promise<DispatchResponse> {
   const dispatcher = getCliDispatcher();
-  return dispatcher.dispatch({
+  const projectRoot = getProjectRoot();
+  const dispatchStart = Date.now();
+
+  // Dispatch onPromptSubmit hook (best-effort, fire-and-forget)
+  hooks
+    .dispatch('onPromptSubmit', projectRoot, {
+      timestamp: new Date().toISOString(),
+      gateway,
+      domain,
+      operation,
+      source: 'cli',
+    })
+    .catch(() => {
+      /* hook errors are non-fatal */
+    });
+
+  const response = await dispatcher.dispatch({
     gateway,
     domain,
     operation,
     params,
     source: 'cli',
     requestId: randomUUID(),
   });
+
+  // Dispatch onResponseComplete hook (best-effort, fire-and-forget)
+  hooks
+    .dispatch('onResponseComplete', projectRoot, {
+      timestamp: new Date().toISOString(),
+      gateway,
+      domain,
+      operation,
+      success: response.success,
+      durationMs: Date.now() - dispatchStart,
+      errorCode: response.error?.code,
+    })
+    .catch(() => {
+      /* hook errors are non-fatal */
+    });
+
+  return response;
 }

packages/contracts/src/config.ts

@@ -186,6 +186,8 @@ export interface BrainConfig {
   captureFiles: boolean;
   /** Whether to capture MCP tool events (default: false). */
   captureMcp: boolean;
+  /** Whether to capture active-work dispatch mutations (tasks.add, tasks.update) (default: false). */
+  captureWork: boolean;
   /** Embedding provider settings. */
   embedding: BrainEmbeddingConfig;
   /** Memory bridge auto-refresh settings. */

packages/core/src/config.ts

@@ -83,17 +83,18 @@ const DEFAULTS: CleoConfig = {
     autoCapture: true,
     captureFiles: false,
     captureMcp: false,
+    captureWork: false,
     embedding: {
-      enabled: false,
+      enabled: true,
       provider: 'local' as const,
     },
     memoryBridge: {
       autoRefresh: true,
-      contextAware: false,
+      contextAware: true,
       maxTokens: 2000,
     },
     summarization: {
-      enabled: false,
+      enabled: true,
     },
   },
 };

packages/core/src/hooks/handlers/file-hooks.ts

@@ -5,7 +5,9 @@
  * Includes 5-second dedup and path-based filtering to avoid noisy writes.
  * Auto-registers on module load.
  *
- * Disabled by default. Set CLEO_BRAIN_CAPTURE_FILES=true to enable.
+ * Disabled by default. Enable via:
+ *   - Config: brain.captureFiles = true  (checked first)
+ *   - Env:    CLEO_BRAIN_CAPTURE_FILES=true  (overrides config)
  */
 
 import { isAbsolute, relative } from 'node:path';
@@ -39,10 +41,34 @@ function shouldSkipPath(relativePath: string): boolean {
   return SKIP_PATTERNS.some((pattern) => pattern.test(relativePath));
 }
 
+/**
+ * Check whether file-change capture is enabled.
+ *
+ * Resolution order (first truthy wins):
+ *   1. CLEO_BRAIN_CAPTURE_FILES env var (explicit override)
+ *   2. brain.captureFiles project config value
+ *
+ * Defaults to false when neither is set.
+ */
+async function isFileCaptureEnabled(projectRoot: string): Promise<boolean> {
+  const envOverride = process.env['CLEO_BRAIN_CAPTURE_FILES'];
+  if (envOverride !== undefined) {
+    return envOverride === 'true';
+  }
+  try {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(projectRoot);
+    return config.brain?.captureFiles ?? false;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Handle onFileChange - capture file changes to BRAIN
  *
- * Gated behind CLEO_BRAIN_CAPTURE_FILES=true env var.
+ * Gated behind brain.captureFiles config or CLEO_BRAIN_CAPTURE_FILES env var.
+ * Env var takes precedence over config for backward compatibility.
  * Deduplicates rapid writes to the same file within a 5-second window.
  * Filters out .cleo/ internal files and test temp directories.
  * Converts absolute paths to project-relative paths.
@@ -52,7 +78,7 @@ export async function handleFileChange(
   payload: OnFileChangePayload,
 ): Promise<void> {
   // Opt-in gate: disabled by default to prevent observation noise
-  if (process.env['CLEO_BRAIN_CAPTURE_FILES'] !== 'true') return;
+  if (!(await isFileCaptureEnabled(projectRoot))) return;
 
   // 5-second dedup
   const now = Date.now();

packages/core/src/hooks/handlers/index.ts

@@ -11,10 +11,12 @@ import './task-hooks.js';
 import './error-hooks.js';
 import './file-hooks.js';
 import './mcp-hooks.js';
+import './work-capture-hooks.js';
 
 export { handleError } from './error-hooks.js';
 export { handleFileChange } from './file-hooks.js';
 export { handlePromptSubmit, handleResponseComplete } from './mcp-hooks.js';
 // Re-export handler functions for explicit use
 export { handleSessionEnd, handleSessionStart } from './session-hooks.js';
 export { handleToolComplete, handleToolStart } from './task-hooks.js';
+export { handleWorkPromptSubmit, handleWorkResponseComplete } from './work-capture-hooks.js';

packages/core/src/hooks/handlers/mcp-hooks.ts

@@ -1,9 +1,11 @@
 /**
  * MCP Prompt/Response Hook Handlers - Wave 2 of T5237
  *
- * Handlers for onPromptSubmit and onResponseComplete events.
- * By default, NO brain capture (too noisy). Brain observation is
- * opt-in via CLEO_BRAIN_CAPTURE_MCP=true environment variable.
+ * Handlers for onPromptSubmit and onResponseComplete events that capture
+ * ALL gateway operations (read and write) to BRAIN.
+ * By default, NO brain capture (too noisy). Enable via:
+ *   - Config: brain.captureMcp = true  (checked first)
+ *   - Env:    CLEO_BRAIN_CAPTURE_MCP=true  (overrides config)
  * Auto-registers on module load.
  */
 
@@ -17,23 +19,39 @@ function isMissingBrainSchemaError(err: unknown): boolean {
 }
 
 /**
- * Check if brain capture is enabled for MCP events.
- * Defaults to false (too noisy for normal operation).
+ * Check whether MCP-level brain capture is enabled.
+ *
+ * Resolution order (first truthy wins):
+ *   1. CLEO_BRAIN_CAPTURE_MCP env var (explicit override)
+ *   2. brain.captureMcp project config value
+ *
+ * Defaults to false when neither is set (too noisy for normal operation).
  */
-function isBrainCaptureEnabled(): boolean {
-  return process.env['CLEO_BRAIN_CAPTURE_MCP'] === 'true';
+async function isBrainCaptureEnabled(projectRoot: string): Promise<boolean> {
+  const envOverride = process.env['CLEO_BRAIN_CAPTURE_MCP'];
+  if (envOverride !== undefined) {
+    return envOverride === 'true';
+  }
+  try {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(projectRoot);
+    return config.brain?.captureMcp ?? false;
+  } catch {
+    return false;
+  }
 }
 
 /**
- * Handle onPromptSubmit - optionally capture prompt events to BRAIN
+ * Handle onPromptSubmit - optionally capture ALL gateway prompt events to BRAIN.
  *
- * No-op by default. Set CLEO_BRAIN_CAPTURE_MCP=true to enable.
+ * No-op by default. Enable via brain.captureMcp config or CLEO_BRAIN_CAPTURE_MCP env.
+ * For selective mutation-only capture, use work-capture-hooks.ts instead.
  */
 export async function handlePromptSubmit(
   projectRoot: string,
   payload: OnPromptSubmitPayload,
 ): Promise<void> {
-  if (!isBrainCaptureEnabled()) return;
+  if (!(await isBrainCaptureEnabled(projectRoot))) return;
 
   const { observeBrain } = await import('../../memory/brain-retrieval.js');
 
@@ -50,15 +68,16 @@ export async function handlePromptSubmit(
 }
 
 /**
- * Handle onResponseComplete - optionally capture response events to BRAIN
+ * Handle onResponseComplete - optionally capture ALL gateway response events to BRAIN.
  *
- * No-op by default. Set CLEO_BRAIN_CAPTURE_MCP=true to enable.
+ * No-op by default. Enable via brain.captureMcp config or CLEO_BRAIN_CAPTURE_MCP env.
+ * For selective mutation-only capture, use work-capture-hooks.ts instead.
  */
 export async function handleResponseComplete(
   projectRoot: string,
   payload: OnResponseCompletePayload,
 ): Promise<void> {
-  if (!isBrainCaptureEnabled()) return;
+  if (!(await isBrainCaptureEnabled(projectRoot))) return;
 
   const { observeBrain } = await import('../../memory/brain-retrieval.js');