@claude-flow/shared 3.0.0-alpha.1 → 3.0.0-alpha.8

package/.claude-flow/logs/headless/audit_1777379816437_w0eaul_prompt.log

@@ -0,0 +1,3210 @@
+[2026-04-28T12:36:56.443Z] PROMPT
+============================================================
+Analyze this codebase for security vulnerabilities:
+- Check for hardcoded secrets (API keys, passwords)
+- Identify SQL injection risks
+- Find XSS vulnerabilities
+- Check for insecure dependencies
+- Identify authentication/authorization issues
+
+Provide a JSON report with:
+{
+  "vulnerabilities": [{ "severity": "high|medium|low", "file": "...", "line": N, "description": "..." }],
+  "riskScore": 0-100,
+  "recommendations": ["..."]
+}
+
+## Codebase Context
+
+--- src/utils/secure-logger.js (truncated) ---
+/**
+ * Secure Logger Utility
+ *
+ * Provides sanitized error logging that strips sensitive information
+ * before logging to prevent information disclosure.
+ *
+ * Security features:
+ * - Removes stack traces in production
+ * - Sanitizes file paths to prevent internal structure disclosure
+ * - Filters sensitive keys from error objects
+ * - Truncates long messages to prevent log injection
+ *
+ * @module @claude-flow/shared/utils/secure-logger
+ */
+const DEFAULT_CONFIG = {
+    environment: process.env.NODE_ENV || 'development',
+    maxMessageLength: 1000,
+    includeStackTrace: process.env.NODE_ENV === 'development',
+    sensitiveKeys: [
+        'password', 'passwd', 'secret', 'token', 'apikey', 'api_key',
+        'authorization', 'auth', 'credential', 'private', 'key',
+        'session', 'cookie', 'jwt', 'bearer', 'access_token', 'refresh_token',
+    ],
+    pathPatterns: [
+        /\/home\/[^/]+/g, // Unix home directories
+        /\/Users\/[^/]+/g, // macOS home directories
+        /C:\\Users\\[^\\]+/gi, // Windows user directories
+        /\/var\/[^/]+/g, // Var directories
+        /\/tmp\/[^/]+/g, // Temp directories
+    ],
+};
+// ============================================================================
+// Sanitization Functions
+// ============================================================================
+/**
+ * Sanitize a string message
+ */
+function sanitizeMessage(message, config) {
+    let sanitized = message;
+    // Truncate long messages
+    if (sanitized.length > config.maxMessageLength) {
+        sanitized = sanitized.substring(0, config.maxMessageLength) + '... [truncated]';
+    }
+    // Sanitize paths
+    for (const pattern of config.pathPatterns) {
+        sanitized = sanitized.replace(pattern, '[PATH]');
+    }
+    // Remove potential sensitive data patterns
+    sanitized = sanitized.replace(/[a-zA-Z0-9+/]{40,}={0,2}/g, '[REDACTED_KEY]');
+    sanitized = sanitized.replace(/Bearer\s+[^\s]+/gi, 'Bearer [REDACTED]');
+    sanitized = sanitized.replace(/token[=:]\s*[^\s&]+/gi, 'token=[REDACTED]');
+    return sanitized;
+}
+/**
+ * Sanitize an error object
+ */
+function sanitizeError(error, config) {
+    if (error === null || error === undefined) {
+        return { message: 'Unknown error' };
+    }
+    if (typeof error === 'string') {
+        return { message: sanitizeMessage(error, config) };
+    }
+    if (error instanceof Error) {
+        const sanitized = {
+            name: error.name,
+            message: sanitizeMessage(error.message, config),
+        };
+        // Only include stack in development
+        if (config.includeStackTrace && error.stack) {
+            sanitized.stack = sanitizeMessage(error.stack, config);
+        }
+        // Include code if present (common in Node.js errors)
+        if ('code' in error) {
+            sanitized.code = error.code;
+        }
+        return sanitized;
+    }
+    if (typeof error === 'object') {
+        return sanitizeObject(error, config);
+    }
+    return { message: String(error) };
+}
+/**
+ * Sanitize a plain object
+ */
+function sanitizeObject(obj, config) {
+    const sanitized = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const lowerKey = key.toLowerCase();
+        // Skip sensitive keys
+        if (config.sensitiveKeys.some(sk => lowerKey.includes(sk))) {
+            sanitized[key] = '[REDACTED]';
+            continue;
+        }
+        // Recursively sanitize nested objects
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            sanitized[key] = sanitizeObject(value, config);
+        }
+        else if (typeof value === 'string') {
+            sanitized[key] = sanitizeMessage(value, config);
+        }
+        else {
+            sanitized[key] = value;
+        }
+    }
+    return sanitized;
+}
+// ============================================================================
+// Logger Class
+// ============================================================================
+export class SecureLogger {
+    config;
+    prefix;
+    constructor(prefix = '', config = {}) {
+        this.prefix = prefix;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Log an info message
+     */
+    info(message, data) {
+        const sanitizedMessage = sanitizeMessage(message, this.config);
+        const sanitizedData = data ? sanitizeObject(data, this.config) : undefined;
+        if (sanitizedData) {
+            console.info(`[INFO]${this.prefix ? ` [${this.prefix}]` : ''} ${sanitizedMessage}`, sanitizedData);
+        }
+        else {
+            console.info(`[INFO]${this.prefix ? ` [${this.prefix}]` : ''} ${sanitizedMessage}`);
+        }
+    }
+    /**
+     * Log a warning message
+     */
+    warn(message, data) {
+        const sanitizedMessage = sanitizeMessage(message, this.config);
+        const sanitizedData = data ? sanitizeObject(data, this.config) : undefined;
+        if (sanitizedData) {
+            console.warn(`[WARN]${this.prefix ? ` [${this.prefix}]` : ''} ${sanitizedMessage}`, sanitiz
+
+--- __tests__/hooks/bash-safety.test.ts (truncated) ---
+/**
+ * V3 Bash Safety Hook Tests
+ *
+ * Tests for command safety analysis and dangerous command detection.
+ *
+ * @module v3/shared/hooks/__tests__/bash-safety.test
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  createHookRegistry,
+  createBashSafetyHook,
+  BashSafetyHook,
+  HookRegistry,
+} from '../../src/hooks/index.js';
+
+describe('BashSafetyHook', () => {
+  let registry: HookRegistry;
+  let bashSafety: BashSafetyHook;
+
+  beforeEach(() => {
+    registry = createHookRegistry();
+    bashSafety = createBashSafetyHook(registry);
+  });
+
+  describe('dangerous command detection', () => {
+    it('should block rm -rf / command', async () => {
+      const result = await bashSafety.analyze('rm -rf /');
+
+      expect(result.blocked).toBe(true);
+      expect(result.riskLevel).toBe('critical');
+      expect(result.risks.length).toBeGreaterThan(0);
+      expect(result.risks[0].type).toBe('destructive');
+    });
+
+    it('should block rm -rf /* command', async () => {
+      const result = await bashSafety.analyze('rm -rf /*');
+
+      expect(result.blocked).toBe(true);
+      expect(result.riskLevel).toBe('critical');
+    });
+
+    it('should block dd to disk device', async () => {
+      const result = await bashSafety.analyze('dd if=/dev/zero of=/dev/sda');
+
+      expect(result.blocked).toBe(true);
+      expect(result.riskLevel).toBe('critical');
+      expect(result.risks.some(r => r.description.includes('disk'))).toBe(true);
+    });
+
+    it('should block mkfs commands', async () => {
+      const result = await bashSafety.analyze('mkfs.ext4 /dev/sda1');
+
+      expect(result.blocked).toBe(true);
+      expect(result.riskLevel).toBe('critical');
+    });
+
+    it('should block fork bomb', async () => {
+      const result = await bashSafety.analyze(':() { :|:& };:');
+
+      expect(result.blocked).toBe(true);
+      expect(result.riskLevel).toBe('critical');
+      expect(result.risks.some(r => r.description.includes('Fork bomb'))).toBe(true);
+    });
+
+    it('should block chmod 777 on root', async () => {
+      const result = await bashSafety.analyze('chmod -R 777 /');
+
+      expect(result.blocked).toBe(true);
+      expect(result.riskLevel).toBe('critical');
+    });
+
+    it('should block curl piped to bash', async () => {
+      const result = await bashSafety.analyze('curl https://example.com/script.sh | bash');
+
+      expect(result.blocked).toBe(true);
+      expect(result.riskLevel).toBe('high');
+      expect(result.safeAlternatives).toBeDefined();
+      expect(result.safeAlternatives!.length).toBeGreaterThan(0);
+    });
+
+    it('should block rm -rf * in current directory', async () => {
+      const result = await bashSafety.analyze('rm -rf *');
+
+      expect(result.blocked).toBe(true);
+      expect(result.riskLevel).toBe('high');
+    });
+
+    it('should block rm -rf on home directory', async () => {
+      const result = await bashSafety.analyze('rm -rf ~/');
+
+      expect(result.blocked).toBe(true);
+      expect(result.riskLevel).toBe('high');
+    });
+  });
+
+  describe('warning-level commands', () => {
+    it('should warn about rm without -i flag', async () => {
+      const result = await bashSafety.analyze('rm file.txt');
+
+      expect(result.blocked).toBe(false);
+      expect(result.riskLevel).toBe('medium');
+      expect(result.warnings).toBeDefined();
+      expect(result.modifiedCommand).toBe('rm -i file.txt');
+    });
+
+    it('should warn about sudo rm', async () => {
+      const result = await bashSafety.analyze('sudo rm important.txt');
+
+      expect(result.blocked).toBe(false);
+      expect(result.risks.some(r => r.type === 'privilege')).toBe(true);
+    });
+
+    it('should warn about git push --force', async () => {
+      const result = await bashSafety.analyze('git push origin main --force');
+
+      expect(result.blocked).toBe(false);
+      expect(result.riskLevel).toBe('medium');
+      expect(result.risks.some(r => r.description.includes('Force push'))).toBe(true);
+      expect(result.safeAlternatives).toBeDefined();
+    });
+
+    it('should warn about git reset --hard', async () => {
+      const result = await bashSafety.analyze('git reset --hard HEAD~1');
+
+      expect(result.blocked).toBe(false);
+      expect(result.riskLevel).toBe('medium');
+      expect(result.risks.some(r => r.description.includes('Hard reset'))).toBe(true);
+    });
+
+    it('should warn about DROP DATABASE', async () => {
+      const result = await bashSafety.analyze('mysql -e "DROP DATABASE production"');
+
+      expect(result.blocked).toBe(false);
+      expect(result.riskLevel).toBe('high');
+    });
+
+    it('should warn about kill -9', async () => {
+      const result = await bashSafety.analyze('kill -9 12345');
+
+      expect(result.blocked).toBe(false);
+      expect(result.riskLevel).toBe('low');
+    });
+  });
+
+  describe('secret detection', () => {
+    it('should detect password in command', async () => {
+      const result = await bashSafety.analyze('mysql -p password=secret123');
+
+      expect(result.risks.some(r => r
+
+--- __tests__/hooks/file-organization.test.ts (truncated) ---
+/**
+ * V3 File Organization Hook Tests
+ *
+ * Tests for file organization enforcement and formatter recommendations.
+ *
+ * @module v3/shared/hooks/__tests__/file-organization.test
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  createHookRegistry,
+  createFileOrganizationHook,
+  FileOrganizationHook,
+  HookRegistry,
+} from '../../src/hooks/index.js';
+
+describe('FileOrganizationHook', () => {
+  let registry: HookRegistry;
+  let fileOrg: FileOrganizationHook;
+
+  beforeEach(() => {
+    registry = createHookRegistry();
+    fileOrg = createFileOrganizationHook(registry);
+  });
+
+  describe('root folder blocking', () => {
+    it('should block TypeScript source files in root', async () => {
+      const result = await fileOrg.analyze('utils.ts');
+
+      expect(result.blocked).toBe(true);
+      expect(result.blockReason).toBeDefined();
+      expect(result.suggestedDirectory).toBe('src/');
+      expect(result.suggestedPath).toBe('src/utils.ts');
+    });
+
+    it('should block JavaScript source files in root', async () => {
+      const result = await fileOrg.analyze('index.js');
+
+      expect(result.blocked).toBe(true);
+      expect(result.suggestedDirectory).toBe('src/');
+    });
+
+    it('should block TypeScript test files in root', async () => {
+      const result = await fileOrg.analyze('utils.test.ts');
+
+      expect(result.blocked).toBe(true);
+      expect(result.suggestedDirectory).toBe('tests/');
+      expect(result.suggestedPath).toBe('tests/utils.test.ts');
+    });
+
+    it('should block spec files in root', async () => {
+      const result = await fileOrg.analyze('api.spec.ts');
+
+      expect(result.blocked).toBe(true);
+      expect(result.suggestedDirectory).toBe('tests/');
+    });
+
+    it('should block Python files in root', async () => {
+      const result = await fileOrg.analyze('main.py');
+
+      expect(result.blocked).toBe(true);
+      expect(result.suggestedDirectory).toBe('src/');
+    });
+
+    it('should block Go files in root', async () => {
+      const result = await fileOrg.analyze('main.go');
+
+      expect(result.blocked).toBe(true);
+      expect(result.suggestedDirectory).toBe('cmd/');
+    });
+
+    it('should block shell scripts in root', async () => {
+      const result = await fileOrg.analyze('deploy.sh');
+
+      expect(result.blocked).toBe(true);
+      expect(result.suggestedDirectory).toBe('scripts/');
+    });
+
+    it('should block CSS files in root', async () => {
+      const result = await fileOrg.analyze('styles.css');
+
+      expect(result.blocked).toBe(true);
+      expect(result.suggestedDirectory).toBe('styles/');
+    });
+  });
+
+  describe('allowed root files', () => {
+    it('should allow JSON config files in root', async () => {
+      const result = await fileOrg.analyze('package.json');
+
+      expect(result.blocked).toBe(false);
+    });
+
+    it('should allow YAML config files in root', async () => {
+      const result = await fileOrg.analyze('config.yaml');
+
+      expect(result.blocked).toBe(false);
+    });
+
+    it('should allow Markdown files in root', async () => {
+      const result = await fileOrg.analyze('README.md');
+
+      expect(result.blocked).toBe(false);
+    });
+
+    it('should allow environment files in root', async () => {
+      const result = await fileOrg.analyze('.env');
+
+      expect(result.blocked).toBe(false);
+    });
+
+    it('should allow .env.local files in root', async () => {
+      const result = await fileOrg.analyze('.env.local');
+
+      expect(result.blocked).toBe(false);
+    });
+  });
+
+  describe('files in correct directories', () => {
+    it('should allow TypeScript files in src/', async () => {
+      const result = await fileOrg.analyze('src/utils.ts');
+
+      expect(result.blocked).toBe(false);
+      expect(result.issues?.some(i => i.type === 'wrong-directory')).toBeFalsy();
+    });
+
+    it('should allow test files in tests/', async () => {
+      const result = await fileOrg.analyze('tests/utils.test.ts');
+
+      expect(result.blocked).toBe(false);
+    });
+
+    it('should allow test files in __tests__/', async () => {
+      const result = await fileOrg.analyze('__tests__/utils.test.ts');
+
+      expect(result.blocked).toBe(false);
+    });
+
+    it('should allow scripts in scripts/', async () => {
+      const result = await fileOrg.analyze('scripts/deploy.sh');
+
+      expect(result.blocked).toBe(false);
+    });
+
+    it('should allow Go files in cmd/', async () => {
+      const result = await fileOrg.analyze('cmd/main.go');
+
+      expect(result.blocked).toBe(false);
+    });
+  });
+
+  describe('files in wrong directories', () => {
+    it('should warn about test files in src/', async () => {
+      const result = await fileOrg.analyze('src/utils.test.ts');
+
+      expect(result.blocked).toBe(false);
+      expect(result.issues?.some(i => i.type === 'wrong-directory')).toBe(true);
+      expect(result.warnings?.length).toBeGreaterThan(0);
+    });
+
+    it('should warn about source files in tests/', async () => {
+      const result = await fileO
+
+--- __tests__/hooks/git-commit.test.ts (truncated) ---
+/**
+ * V3 Git Commit Hook Tests
+ *
+ * Tests for git commit message formatting and validation.
+ *
+ * @module v3/shared/hooks/__tests__/git-commit.test
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  createHookRegistry,
+  createGitCommitHook,
+  GitCommitHook,
+  HookRegistry,
+} from '../../src/hooks/index.js';
+
+describe('GitCommitHook', () => {
+  let registry: HookRegistry;
+  let gitCommit: GitCommitHook;
+
+  beforeEach(() => {
+    registry = createHookRegistry();
+    gitCommit = createGitCommitHook(registry);
+  });
+
+  describe('commit type detection', () => {
+    it('should detect feat type from message', async () => {
+      const result = await gitCommit.process('Add user authentication');
+
+      expect(result.commitType).toBe('feat');
+      expect(result.modifiedMessage).toMatch(/^feat:/);
+    });
+
+    it('should detect fix type from message', async () => {
+      const result = await gitCommit.process('Fix login validation bug');
+
+      expect(result.commitType).toBe('fix');
+      expect(result.modifiedMessage).toMatch(/^fix:/);
+    });
+
+    it('should detect docs type from message', async () => {
+      const result = await gitCommit.process('Update README documentation');
+
+      expect(result.commitType).toBe('docs');
+      expect(result.modifiedMessage).toMatch(/^docs:/);
+    });
+
+    it('should detect refactor type from message', async () => {
+      const result = await gitCommit.process('Refactor authentication module');
+
+      expect(result.commitType).toBe('refactor');
+      expect(result.modifiedMessage).toMatch(/^refactor:/);
+    });
+
+    it('should detect test type from message', async () => {
+      const result = await gitCommit.process('Add unit tests for user service');
+
+      expect(result.commitType).toBe('test');
+      expect(result.modifiedMessage).toMatch(/^test:/);
+    });
+
+    it('should detect perf type from message', async () => {
+      const result = await gitCommit.process('Optimize database queries');
+
+      expect(result.commitType).toBe('perf');
+      expect(result.modifiedMessage).toMatch(/^perf:/);
+    });
+
+    it('should detect build type from message', async () => {
+      const result = await gitCommit.process('Update webpack configuration');
+
+      expect(result.commitType).toBe('build');
+      expect(result.modifiedMessage).toMatch(/^build:/);
+    });
+
+    it('should detect ci type from message', async () => {
+      const result = await gitCommit.process('Update GitHub Actions workflow');
+
+      expect(result.commitType).toBe('ci');
+      expect(result.modifiedMessage).toMatch(/^ci:/);
+    });
+
+    it('should detect chore type from message', async () => {
+      const result = await gitCommit.process('Update dependencies');
+
+      expect(result.commitType).toBe('chore');
+      expect(result.modifiedMessage).toMatch(/^chore:/);
+    });
+
+    it('should detect revert type from message', async () => {
+      const result = await gitCommit.process('Revert previous commit');
+
+      expect(result.commitType).toBe('revert');
+      expect(result.modifiedMessage).toMatch(/^revert:/);
+    });
+  });
+
+  describe('preserving existing prefixes', () => {
+    it('should not add duplicate prefix if already present', async () => {
+      const result = await gitCommit.process('feat: add user authentication');
+
+      expect(result.commitType).toBe('feat');
+      // Should not have double prefix
+      expect(result.modifiedMessage).not.toMatch(/^feat:.*feat:/);
+    });
+
+    it('should detect type from existing prefix', async () => {
+      const result = await gitCommit.process('fix(auth): resolve login issue');
+
+      expect(result.commitType).toBe('fix');
+    });
+
+    it('should handle scoped commits', async () => {
+      const result = await gitCommit.process('feat(api): add new endpoint');
+
+      expect(result.commitType).toBe('feat');
+    });
+  });
+
+  describe('ticket extraction', () => {
+    it('should extract JIRA ticket from branch name', async () => {
+      const result = await gitCommit.process('Add feature', 'feature/ABC-123-new-feature');
+
+      expect(result.ticketReference).toBe('ABC-123');
+      expect(result.modifiedMessage).toContain('Refs: ABC-123');
+    });
+
+    it('should extract GitHub issue from branch name', async () => {
+      const result = await gitCommit.process('Fix bug', 'fix/#456-login-bug');
+
+      expect(result.ticketReference).toBe('#456');
+      expect(result.modifiedMessage).toContain('Refs: #456');
+    });
+
+    it('should not duplicate ticket if already in message', async () => {
+      const result = await gitCommit.process('Fix ABC-123 bug', 'feature/ABC-123-test');
+
+      // Should only appear once
+      const matches = result.modifiedMessage.match(/ABC-123/g);
+      expect(matches).toBeDefined();
+      expect(matches!.length).toBeLessThanOrEqual(2);
+    });
+  });
+
+  describe('co-author addition', () => {
+    it('should add co-author by default', async () => {
+      const result = await gitCommit.process('Add feature');
+
+      expect(res
+
+--- __tests__/hooks/index.ts ---
+/**
+ * V3 Hooks Tests Index
+ *
+ * Exports all hook tests for the V3 hooks system.
+ *
+ * @module v3/shared/hooks/__tests__
+ */
+
+// Test files are automatically discovered by vitest
+// This file serves as documentation of available tests
+
+export const testFiles = [
+  './task-hooks.test.ts',
+  './session-hooks.test.ts',
+  './bash-safety.test.ts',
+  './file-organization.test.ts',
+  './git-commit.test.ts',
+];
+
+export const testCategories = {
+  'Core Hooks': ['task-hooks.test.ts', 'session-hooks.test.ts'],
+  'Safety Hooks': ['bash-safety.test.ts', 'file-organization.test.ts', 'git-commit.test.ts'],
+};
+
+
+--- __tests__/hooks/session-hooks.test.ts (truncated) ---
+/**
+ * V3 Session Hooks Tests
+ *
+ * Tests for session-end and session-restore hook functionality.
+ *
+ * @module v3/shared/hooks/__tests__/session-hooks.test
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  createHookRegistry,
+  createSessionHooksManager,
+  SessionHooksManager,
+  HookRegistry,
+  HookEvent,
+  InMemorySessionStorage,
+} from '../../src/hooks/index.js';
+
+describe('SessionHooksManager', () => {
+  let registry: HookRegistry;
+  let sessionManager: SessionHooksManager;
+  let storage: InMemorySessionStorage;
+
+  beforeEach(() => {
+    registry = createHookRegistry();
+    storage = new InMemorySessionStorage();
+    sessionManager = createSessionHooksManager(registry, storage);
+  });
+
+  describe('session lifecycle hooks', () => {
+    it('should register session hooks on creation', () => {
+      const startHooks = registry.getHandlers(HookEvent.SessionStart);
+      const endHooks = registry.getHandlers(HookEvent.SessionEnd);
+      const resumeHooks = registry.getHandlers(HookEvent.SessionResume);
+
+      expect(startHooks.some(h => h.name === 'session-hooks:start')).toBe(true);
+      expect(endHooks.some(h => h.name === 'session-hooks:end')).toBe(true);
+      expect(resumeHooks.some(h => h.name === 'session-hooks:resume')).toBe(true);
+    });
+  });
+
+  describe('session-end hook', () => {
+    it('should end session and return summary', async () => {
+      // Simulate session start by triggering tracking
+      const context = {
+        event: HookEvent.SessionStart,
+        timestamp: new Date(),
+        session: { id: 'test-session', startTime: new Date() },
+      };
+      await sessionManager['handleSessionStart'](context);
+
+      // Wait a moment to ensure duration > 0
+      await new Promise(resolve => setTimeout(resolve, 10));
+
+      const result = await sessionManager.executeSessionEnd();
+
+      expect(result.success).toBe(true);
+      expect(result.duration).toBeGreaterThanOrEqual(0);
+      expect(result.summary).toBeDefined();
+      expect(result.summary!.tasksExecuted).toBe(0);
+      expect(result.summary!.commandsExecuted).toBe(0);
+    });
+
+    it('should persist session state', async () => {
+      // Start session
+      const startContext = {
+        event: HookEvent.SessionStart,
+        timestamp: new Date(),
+        session: { id: 'persist-session', startTime: new Date() },
+      };
+      await sessionManager['handleSessionStart'](startContext);
+
+      const result = await sessionManager.executeSessionEnd();
+
+      expect(result.persistedState).toBeDefined();
+      expect(result.statePath).toBeDefined();
+
+      // Verify state was saved
+      const sessions = await storage.list();
+      expect(sessions.length).toBeGreaterThan(0);
+    });
+
+    it('should handle ending session without active session', async () => {
+      const result = await sessionManager.executeSessionEnd();
+      expect(result.success).toBe(true);
+    });
+
+    it('should reset activity tracking after session end', async () => {
+      // Start session
+      const context = {
+        event: HookEvent.SessionStart,
+        timestamp: new Date(),
+        session: { id: 'reset-session', startTime: new Date() },
+      };
+      await sessionManager['handleSessionStart'](context);
+
+      await sessionManager.executeSessionEnd();
+
+      expect(sessionManager.getCurrentSessionId()).toBeNull();
+    });
+  });
+
+  describe('session-restore hook', () => {
+    it('should restore a previous session', async () => {
+      // Create and end a session first
+      const startContext = {
+        event: HookEvent.SessionStart,
+        timestamp: new Date(),
+        session: { id: 'restore-test', startTime: new Date() },
+      };
+      await sessionManager['handleSessionStart'](startContext);
+      await sessionManager.executeSessionEnd();
+
+      // Restore the session
+      const result = await sessionManager.executeSessionRestore('restore-test');
+
+      expect(result.success).toBe(true);
+      expect(result.restoredState).toBeDefined();
+      expect(result.restoredState!.sessionId).toBe('restore-test');
+    });
+
+    it('should restore latest session when no ID specified', async () => {
+      // Create and end multiple sessions
+      for (const id of ['session-1', 'session-2', 'session-3']) {
+        const context = {
+          event: HookEvent.SessionStart,
+          timestamp: new Date(),
+          session: { id, startTime: new Date() },
+        };
+        await sessionManager['handleSessionStart'](context);
+        await sessionManager.executeSessionEnd();
+        await new Promise(resolve => setTimeout(resolve, 5));
+      }
+
+      const result = await sessionManager.executeSessionRestore();
+
+      expect(result.success).toBe(true);
+      expect(result.restoredState).toBeDefined();
+    });
+
+    it('should fail gracefully when session not found', async () => {
+      const result = await sessionManager.executeSessionRestore('non-existent');
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBeDefin
+
+--- __tests__/hooks/task-hooks.test.ts (truncated) ---
+/**
+ * V3 Task Hooks Tests
+ *
+ * Tests for pre-task and post-task hook functionality.
+ *
+ * @module v3/shared/hooks/__tests__/task-hooks.test
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  createHookRegistry,
+  createTaskHooksManager,
+  TaskHooksManager,
+  HookRegistry,
+  HookEvent,
+} from '../../src/hooks/index.js';
+
+describe('TaskHooksManager', () => {
+  let registry: HookRegistry;
+  let taskManager: TaskHooksManager;
+
+  beforeEach(() => {
+    registry = createHookRegistry();
+    taskManager = createTaskHooksManager(registry);
+  });
+
+  describe('pre-task hook', () => {
+    it('should register pre-task hook on creation', () => {
+      const hooks = registry.getHandlers(HookEvent.PreTaskExecute);
+      expect(hooks.length).toBeGreaterThan(0);
+      expect(hooks.some(h => h.name === 'task-hooks:pre-task')).toBe(true);
+    });
+
+    it('should analyze task and suggest agents for coding task', async () => {
+      const result = await taskManager.executePreTask(
+        'task-123',
+        'Implement user authentication feature'
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.suggestedAgents).toBeDefined();
+      expect(result.suggestedAgents!.length).toBeGreaterThan(0);
+      expect(result.suggestedAgents![0].type).toBe('coder');
+      expect(result.suggestedAgents![0].confidence).toBeGreaterThan(0);
+    });
+
+    it('should suggest security-architect for security tasks', async () => {
+      const result = await taskManager.executePreTask(
+        'task-456',
+        'Fix security vulnerability in authentication'
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.suggestedAgents).toBeDefined();
+      const securityAgent = result.suggestedAgents!.find(a => a.type === 'security-architect');
+      expect(securityAgent).toBeDefined();
+    });
+
+    it('should suggest tester for test-related tasks', async () => {
+      const result = await taskManager.executePreTask(
+        'task-789',
+        'Write unit tests for user service'
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.suggestedAgents).toBeDefined();
+      const testerAgent = result.suggestedAgents!.find(a => a.type === 'tester');
+      expect(testerAgent).toBeDefined();
+    });
+
+    it('should estimate complexity based on task description', async () => {
+      // Simple task
+      const simpleResult = await taskManager.executePreTask(
+        'task-simple',
+        'Fix typo in readme'
+      );
+      expect(simpleResult.complexity).toBe('low');
+
+      // Complex task
+      const complexResult = await taskManager.executePreTask(
+        'task-complex',
+        'Refactor and redesign the entire authentication system with multiple OAuth providers'
+      );
+      expect(complexResult.complexity).toBe('high');
+    });
+
+    it('should detect risks in task description', async () => {
+      const result = await taskManager.executePreTask(
+        'task-risky',
+        'Delete old data from production database'
+      );
+
+      expect(result.risks).toBeDefined();
+      expect(result.risks!.length).toBeGreaterThan(0);
+      expect(result.risks!.some(r => r.includes('production'))).toBe(true);
+    });
+
+    it('should track active tasks', async () => {
+      await taskManager.executePreTask('task-1', 'Task 1');
+      await taskManager.executePreTask('task-2', 'Task 2');
+
+      const activeTasks = taskManager.getActiveTasks();
+      expect(activeTasks.size).toBe(2);
+      expect(activeTasks.has('task-1')).toBe(true);
+      expect(activeTasks.has('task-2')).toBe(true);
+    });
+
+    it('should provide recommendations for high complexity tasks', async () => {
+      const result = await taskManager.executePreTask(
+        'task-high-complexity',
+        'Implement complex distributed system with multiple services'
+      );
+
+      expect(result.recommendations).toBeDefined();
+      expect(result.recommendations!.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('post-task hook', () => {
+    it('should register post-task hook on creation', () => {
+      const hooks = registry.getHandlers(HookEvent.PostTaskExecute);
+      expect(hooks.length).toBeGreaterThan(0);
+      expect(hooks.some(h => h.name === 'task-hooks:post-task')).toBe(true);
+    });
+
+    it('should record successful task outcome', async () => {
+      // First start the task
+      await taskManager.executePreTask('task-success', 'Test task');
+
+      // Then complete it
+      const result = await taskManager.executePostTask('task-success', true);
+
+      expect(result.success).toBe(true);
+      expect(result.outcome).toBeDefined();
+      expect(result.outcome!.success).toBe(true);
+      expect(result.outcome!.duration).toBeGreaterThanOrEqual(0);
+    });
+
+    it('should record failed task outcome', async () => {
+      await taskManager.executePreTask('task-failed', 'Test task');
+
+      const result = await taskManager.executePostTask('task-failed', false, {
+        error: 'Test failed due to timeout',
+      });
+
+      ex
+
+--- src/core/config/defaults.ts ---
+/**
+ * V3 Default Configuration Values
+ */
+
+import type {
+  AgentConfig,
+  TaskConfig,
+  SwarmConfig,
+  MemoryConfig,
+  MCPServerConfig,
+  OrchestratorConfig,
+  SystemConfig,
+} from './schema.js';
+
+/**
+ * Default agent configuration
+ */
+export const defaultAgentConfig: Partial<AgentConfig> = {
+  capabilities: [],
+  maxConcurrentTasks: 5,
+  priority: 50,
+  retryPolicy: {
+    maxRetries: 3,
+    backoffMs: 1000,
+    backoffMultiplier: 2,
+  },
+};
+
+/**
+ * Default task configuration
+ */
+export const defaultTaskConfig: Partial<TaskConfig> = {
+  priority: 50,
+  metadata: {
+    maxRetries: 3,
+  },
+};
+
+/**
+ * Default swarm configuration (core version)
+ */
+export const defaultSwarmConfigCore: SwarmConfig = {
+  topology: 'hierarchical-mesh',
+  maxAgents: 20,
+  autoScale: {
+    enabled: false,
+    minAgents: 1,
+    maxAgents: 20,
+    scaleUpThreshold: 0.8,
+    scaleDownThreshold: 0.3,
+  },
+  coordination: {
+    consensusRequired: false,
+    timeoutMs: 10000,
+    retryPolicy: {
+      maxRetries: 3,
+      backoffMs: 500,
+    },
+  },
+  communication: {
+    protocol: 'events',
+    batchSize: 10,
+    flushIntervalMs: 100,
+  },
+};
+
+/**
+ * Default memory configuration (hybrid backend - ADR-009)
+ */
+export const defaultMemoryConfig: MemoryConfig = {
+  type: 'hybrid',
+  path: './data/memory',
+  sqlite: {
+    inMemory: false,
+    wal: true,
+  },
+  agentdb: {
+    dimensions: 1536,
+    indexType: 'hnsw',
+    efConstruction: 200,
+    m: 16,
+    quantization: 'none',
+  },
+  hybrid: {
+    vectorThreshold: 100,
+  },
+};
+
+/**
+ * Default MCP server configuration
+ */
+export const defaultMCPServerConfig: MCPServerConfig = {
+  name: 'claude-flow',
+  version: '3.0.0',
+  transport: {
+    type: 'stdio',
+  },
+  capabilities: {
+    tools: true,
+    resources: true,
+    prompts: true,
+    logging: true,
+  },
+};
+
+/**
+ * Default orchestrator configuration
+ */
+export const defaultOrchestratorConfig: OrchestratorConfig = {
+  session: {
+    persistSessions: true,
+    dataDir: './data',
+    sessionRetentionMs: 3600000, // 1 hour
+  },
+  health: {
+    checkInterval: 30000, // 30 seconds
+    historyLimit: 100,
+    degradedThreshold: 1,
+    unhealthyThreshold: 2,
+  },
+  lifecycle: {
+    maxConcurrentAgents: 20,
+    spawnTimeout: 30000, // 30 seconds
+    terminateTimeout: 10000, // 10 seconds
+    maxSpawnRetries: 3,
+  },
+};
+
+/**
+ * Default full system configuration
+ */
+export const defaultSystemConfig: SystemConfig = {
+  orchestrator: defaultOrchestratorConfig,
+  memory: defaultMemoryConfig,
+  mcp: defaultMCPServerConfig,
+  swarm: defaultSwarmConfigCore,
+};
+
+/**
+ * Agent type presets
+ */
+export const agentTypePresets: Record<string, Partial<AgentConfig>> = {
+  coder: {
+    type: 'coder',
+    capabilities: ['code', 'debug', 'refactor', 'test'],
+    maxConcurrentTasks: 3,
+    priority: 70,
+  },
+  reviewer: {
+    type: 'reviewer',
+    capabilities: ['review', 'analyze', 'suggest'],
+    maxConcurrentTasks: 5,
+    priority: 60,
+  },
+  tester: {
+    type: 'tester',
+    capabilities: ['test', 'validate', 'benchmark'],
+    maxConcurrentTasks: 4,
+    priority: 65,
+  },
+  researcher: {
+    type: 'researcher',
+    capabilities: ['research', 'analyze', 'summarize'],
+    maxConcurrentTasks: 3,
+    priority: 50,
+  },
+  planner: {
+    type: 'planner',
+    capabilities: ['plan', 'organize', 'decompose'],
+    maxConcurrentTasks: 2,
+    priority: 80,
+  },
+  architect: {
+    type: 'architect',
+    capabilities: ['design', 'architecture', 'patterns'],
+    maxConcurrentTasks: 2,
+    priority: 85,
+  },
+  coordinator: {
+    type: 'coordinator',
+    capabilities: ['coordinate', 'delegate', 'monitor'],
+    maxConcurrentTasks: 10,
+    priority: 90,
+  },
+  security: {
+    type: 'security',
+    capabilities: ['audit', 'scan', 'validate', 'secure'],
+    maxConcurrentTasks: 3,
+    priority: 95,
+  },
+  performance: {
+    type: 'performance',
+    capabilities: ['benchmark', 'optimize', 'profile'],
+    maxConcurrentTasks: 2,
+    priority: 70,
+  },
+};
+
+/**
+ * Get merged configuration with defaults
+ */
+export function mergeWithDefaults<T extends Record<string, unknown>>(
+  config: Partial<T>,
+  defaults: T,
+): T {
+  return { ...defaults, ...config } as T;
+}
+
+
+--- src/core/config/index.ts ---
+/**
+ * V3 Configuration - Public API
+ */
+
+// Schemas
+export * from './schema.js';
+
+// Validation
+export * from './validator.js';
+
+// Defaults
+export * from './defaults.js';
+
+// Loader
+export * from './loader.js';
+
+
+--- src/core/config/loader.ts (truncated) ---
+/**
+ * V3 Configuration Loader
+ * Load configuration from various sources
+ */
+
+import { readFile } from 'fs/promises';
+import { join, resolve } from 'path';
+import { existsSync } from 'fs';
+import type { SystemConfig } from './schema.js';
+import { validateSystemConfig, type ValidationResult } from './validator.js';
+import { defaultSystemConfig, mergeWithDefaults } from './defaults.js';
+
+/**
+ * Configuration source type
+ */
+export type ConfigSource = 'file' | 'env' | 'default' | 'merged';
+
+/**
+ * Loaded configuration with metadata
+ */
+export interface LoadedConfig {
+  config: SystemConfig;
+  source: ConfigSource;
+  path?: string;
+  warnings?: string[];
+}
+
+/**
+ * Configuration file names to search for
+ */
+const CONFIG_FILE_NAMES = [
+  'claude-flow.config.json',
+  'claude-flow.config.js',
+  'claude-flow.json',
+  '.claude-flow.json',
+];
+
+/**
+ * Find configuration file in directory
+ */
+async function findConfigFile(directory: string): Promise<string | null> {
+  for (const name of CONFIG_FILE_NAMES) {
+    const path = join(directory, name);
+    if (existsSync(path)) {
+      return path;
+    }
+  }
+  return null;
+}
+
+/**
+ * Load configuration from JSON file
+ */
+async function loadJsonConfig(path: string): Promise<unknown> {
+  const content = await readFile(path, 'utf8');
+  return JSON.parse(content);
+}
+
+/**
+ * Load configuration from environment variables
+ */
+function loadEnvConfig(): Partial<SystemConfig> {
+  const config: Partial<SystemConfig> = {};
+
+  // Orchestrator settings
+  if (process.env.CLAUDE_FLOW_MAX_AGENTS) {
+    config.orchestrator = {
+      ...defaultSystemConfig.orchestrator,
+      lifecycle: {
+        ...defaultSystemConfig.orchestrator.lifecycle,
+        maxConcurrentAgents: parseInt(process.env.CLAUDE_FLOW_MAX_AGENTS, 10),
+      },
+    };
+  }
+
+  // Data directory
+  if (process.env.CLAUDE_FLOW_DATA_DIR) {
+    config.orchestrator = {
+      ...config.orchestrator,
+      ...defaultSystemConfig.orchestrator,
+      session: {
+        ...defaultSystemConfig.orchestrator.session,
+        dataDir: process.env.CLAUDE_FLOW_DATA_DIR,
+      },
+    };
+  }
+
+  // Memory type
+  if (process.env.CLAUDE_FLOW_MEMORY_TYPE) {
+    const memoryType = process.env.CLAUDE_FLOW_MEMORY_TYPE as NonNullable<SystemConfig['memory']>['type'];
+    if (['sqlite', 'agentdb', 'hybrid', 'redis', 'memory'].includes(memoryType)) {
+      config.memory = {
+        ...(defaultSystemConfig.memory ?? { type: 'hybrid' }),
+        type: memoryType,
+      };
+    }
+  }
+
+  // MCP transport
+  const defaultMcp = defaultSystemConfig.mcp ?? { name: 'claude-flow', version: '3.0.0', transport: { type: 'stdio' as const } };
+  if (process.env.CLAUDE_FLOW_MCP_TRANSPORT) {
+    const transport = process.env.CLAUDE_FLOW_MCP_TRANSPORT as 'stdio' | 'http' | 'websocket';
+    if (['stdio', 'http', 'websocket'].includes(transport)) {
+      config.mcp = {
+        ...defaultMcp,
+        transport: {
+          ...defaultMcp.transport,
+          type: transport,
+        },
+      };
+    }
+  }
+
+  if (process.env.CLAUDE_FLOW_MCP_PORT) {
+    config.mcp = {
+      ...config.mcp,
+      ...defaultMcp,
+      transport: {
+        ...config.mcp?.transport,
+        ...defaultMcp.transport,
+        port: parseInt(process.env.CLAUDE_FLOW_MCP_PORT, 10),
+      },
+    };
+  }
+
+  // Swarm topology
+  const defaultSwarm = defaultSystemConfig.swarm ?? { topology: 'hierarchical-mesh' as const, maxAgents: 20 };
+  if (process.env.CLAUDE_FLOW_SWARM_TOPOLOGY) {
+    const topology = process.env.CLAUDE_FLOW_SWARM_TOPOLOGY as NonNullable<SystemConfig['swarm']>['topology'];
+    if (['hierarchical', 'mesh', 'ring', 'star', 'adaptive', 'hierarchical-mesh'].includes(topology)) {
+      config.swarm = {
+        ...defaultSwarm,
+        topology,
+      };
+    }
+  }
+
+  return config;
+}
+
+/**
+ * Configuration loader class
+ */
+export class ConfigLoader {
+  private searchPaths: string[] = [];
+
+  constructor(additionalPaths?: string[]) {
+    // Default search paths
+    this.searchPaths = [
+      process.cwd(),
+      resolve(process.cwd(), '..'),
+      resolve(process.env.HOME ?? '', '.claude-flow'),
+    ];
+
+    if (additionalPaths) {
+      this.searchPaths.push(...additionalPaths);
+    }
+  }
+
+  /**
+   * Load configuration from all sources
+   */
+  async load(): Promise<LoadedConfig> {
+    const warnings: string[] = [];
+
+    // Start with defaults
+    let config: SystemConfig = { ...defaultSystemConfig };
+    let source: ConfigSource = 'default';
+    let path: string | undefined;
+
+    // Try to load from file
+    for (const searchPath of this.searchPaths) {
+      const configPath = await findConfigFile(searchPath);
+      if (configPath) {
+        try {
+          const fileConfig = await loadJsonConfig(configPath);
+          const validation = validateSystemConfig(fileConfig);
+
+          if (validation.success) {
+            config = mergeWithDefaults(validation.data!, defaultSystemConfig) as SystemConfig;
+            source = 'file';
+            path = configPath;
+            break;
+          } else {
+           
+
+--- src/core/config/schema.ts (truncated) ---
+/**
+ * V3 Configuration Schemas
+ * Zod schemas for all configuration types
+ */
+
+import { z } from 'zod';
+
+/**
+ * Agent configuration schema
+ */
+export const AgentConfigSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  type: z.string().min(1),
+  capabilities: z.array(z.string()).default([]),
+  maxConcurrentTasks: z.number().int().min(1).default(5),
+  priority: z.number().int().min(0).max(100).default(50),
+  timeout: z.number().int().positive().optional(),
+  retryPolicy: z.object({
+    maxRetries: z.number().int().min(0).default(3),
+    backoffMs: z.number().int().positive().default(1000),
+    backoffMultiplier: z.number().positive().default(2),
+  }).optional(),
+  resources: z.object({
+    maxMemoryMb: z.number().int().positive().optional(),
+    maxCpuPercent: z.number().min(0).max(100).optional(),
+  }).optional(),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+/**
+ * Task configuration schema
+ */
+export const TaskConfigSchema = z.object({
+  type: z.string().min(1),
+  description: z.string().min(1),
+  priority: z.number().int().min(0).max(100).default(50),
+  timeout: z.number().int().positive().optional(),
+  assignedAgent: z.string().optional(),
+  input: z.record(z.unknown()).optional(),
+  metadata: z.object({
+    requiredCapabilities: z.array(z.string()).optional(),
+    retryCount: z.number().int().min(0).optional(),
+    maxRetries: z.number().int().min(0).optional(),
+    critical: z.boolean().optional(),
+    parentTaskId: z.string().optional(),
+    childTaskIds: z.array(z.string()).optional(),
+    tags: z.array(z.string()).optional(),
+  }).optional(),
+});
+
+/**
+ * Swarm configuration schema
+ */
+export const SwarmConfigSchema = z.object({
+  topology: z.enum(['hierarchical', 'mesh', 'ring', 'star', 'adaptive', 'hierarchical-mesh']),
+  maxAgents: z.number().int().positive().default(20),
+  autoScale: z.object({
+    enabled: z.boolean().default(false),
+    minAgents: z.number().int().min(0).default(1),
+    maxAgents: z.number().int().positive().default(20),
+    scaleUpThreshold: z.number().min(0).max(1).default(0.8),
+    scaleDownThreshold: z.number().min(0).max(1).default(0.3),
+  }).optional(),
+  coordination: z.object({
+    consensusRequired: z.boolean().default(false),
+    timeoutMs: z.number().int().positive().default(10000),
+    retryPolicy: z.object({
+      maxRetries: z.number().int().min(0).default(3),
+      backoffMs: z.number().int().positive().default(500),
+    }),
+  }).optional(),
+  communication: z.object({
+    protocol: z.enum(['events', 'messages', 'shared-memory']).default('events'),
+    batchSize: z.number().int().positive().default(10),
+    flushIntervalMs: z.number().int().positive().default(100),
+  }).optional(),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+/**
+ * Memory configuration schema
+ */
+export const MemoryConfigSchema = z.object({
+  type: z.enum(['sqlite', 'agentdb', 'hybrid', 'redis', 'memory']).default('hybrid'),
+  path: z.string().optional(),
+  maxSize: z.number().int().positive().optional(),
+  ttlMs: z.number().int().positive().optional(),
+  sqlite: z.object({
+    filename: z.string().optional(),
+    inMemory: z.boolean().default(false),
+    wal: z.boolean().default(true),
+  }).optional(),
+  agentdb: z.object({
+    dimensions: z.number().int().positive().default(1536),
+    indexType: z.enum(['hnsw', 'flat', 'ivf']).default('hnsw'),
+    efConstruction: z.number().int().positive().default(200),
+    m: z.number().int().positive().default(16),
+    quantization: z.enum(['none', 'scalar', 'product']).default('none'),
+  }).optional(),
+  redis: z.object({
+    host: z.string().default('localhost'),
+    port: z.number().int().positive().default(6379),
+    password: z.string().optional(),
+    db: z.number().int().min(0).default(0),
+    keyPrefix: z.string().default('claude-flow:'),
+  }).optional(),
+  hybrid: z.object({
+    vectorThreshold: z.number().int().positive().default(100),
+  }).optional(),
+});
+
+/**
+ * MCP server configuration schema
+ */
+export const MCPServerConfigSchema = z.object({
+  name: z.string().min(1).default('claude-flow'),
+  version: z.string().min(1).default('3.0.0'),
+  transport: z.object({
+    type: z.enum(['stdio', 'http', 'websocket']).default('stdio'),
+    port: z.number().int().positive().optional(),
+    host: z.string().optional(),
+    path: z.string().optional(),
+  }),
+  capabilities: z.object({
+    tools: z.boolean().default(true),
+    resources: z.boolean().default(true),
+    prompts: z.boolean().default(true),
+    logging: z.boolean().default(true),
+    experimental: z.record(z.boolean()).optional(),
+  }).optional(),
+});
+
+/**
+ * Orchestrator configuration schema
+ */
+export const OrchestratorConfigSchema = z.object({
+  session: z.object({
+    persistSessions: z.boolean().default(true),
+    dataDir: z.string().default('./data'),
+    sessionRetentionMs: z.number().int().positive().default(3600000),
+  }),
+  health: z.object({
+    checkInterval: z.number().int().positive().default(30000),
+    historyLimit: z.number().int().positive()
+
+--- src/core/config/validator.ts ---
+/**
+ * V3 Configuration Validator
+ * Validation logic using Zod schemas
+ */
+
+import { z, type ZodError } from 'zod';
+import {
+  AgentConfigSchema,
+  TaskConfigSchema,
+  SwarmConfigSchema,
+  MemoryConfigSchema,
+  MCPServerConfigSchema,
+  OrchestratorConfigSchema,
+  SystemConfigSchema,
+  type AgentConfig,
+  type TaskConfig,
+  type SwarmConfig,
+  type MemoryConfig,
+  type MCPServerConfig,
+  type OrchestratorConfig,
+  type SystemConfig,
+} from './schema.js';
+
+/**
+ * Validation result
+ */
+export interface ValidationResult<T> {
+  success: boolean;
+  data?: T;
+  errors?: ValidationError[];
+}
+
+/**
+ * Validation error
+ */
+export interface ValidationError {
+  path: string;
+  message: string;
+  code: string;
+}
+
+/**
+ * Convert Zod error to validation errors
+ */
+function zodErrorToValidationErrors(error: ZodError): ValidationError[] {
+  return error.errors.map((e) => ({
+    path: e.path.join('.'),
+    message: e.message,
+    code: e.code,
+  }));
+}
+
+/**
+ * Generic validation function
+ * Uses parse + try/catch to get output types with defaults applied
+ */
+function validate<TInput, TOutput>(
+  schema: z.ZodType<TOutput, z.ZodTypeDef, TInput>,
+  data: unknown
+): ValidationResult<TOutput> {
+  try {
+    const parsed = schema.parse(data);
+    return {
+      success: true,
+      data: parsed,
+    };
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return {
+        success: false,
+        errors: zodErrorToValidationErrors(error),
+      };
+    }
+    throw error;
+  }
+}
+
+/**
+ * Validate agent configuration
+ */
+export function validateAgentConfig(data: unknown): ValidationResult<AgentConfig> {
+  return validate(AgentConfigSchema, data);
+}
+
+/**
+ * Validate task configuration
+ */
+export function validateTaskConfig(data: unknown): ValidationResult<TaskConfig> {
+  return validate(TaskConfigSchema, data);
+}
+
+/**
+ * Validate swarm configuration
+ */
+export function validateSwarmConfig(data: unknown): ValidationResult<SwarmConfig> {
+  return validate(SwarmConfigSchema, data);
+}
+
+/**
+ * Validate memory configuration
+ */
+export function validateMemoryConfig(data: unknown): ValidationResult<MemoryConfig> {
+  return validate(MemoryConfigSchema, data);
+}
+
+/**
+ * Validate MCP server configuration
+ */
+export function validateMCPServerConfig(data: unknown): ValidationResult<MCPServerConfig> {
+  return validate(MCPServerConfigSchema, data);
+}
+
+/**
+ * Validate orchestrator configuration
+ */
+export function validateOrchestratorConfig(data: unknown): ValidationResult<OrchestratorConfig> {
+  return validate(OrchestratorConfigSchema, data);
+}
+
+/**
+ * Validate full system configuration
+ */
+export function validateSystemConfig(data: unknown): ValidationResult<SystemConfig> {
+  return validate(SystemConfigSchema, data);
+}
+
+/**
+ * Configuration validator class
+ */
+export class ConfigValidator {
+  /**
+   * Validate and throw on error
+   */
+  static validateOrThrow<TInput, TOutput>(
+    schema: z.ZodType<TOutput, z.ZodTypeDef, TInput>,
+    data: unknown,
+    configName: string
+  ): TOutput {
+    const result = validate(schema, data);
+
+    if (!result.success) {
+      const errorMessages = result.errors
+        ?.map((e) => `  - ${e.path}: ${e.message}`)
+        .join('\n');
+      throw new Error(`Invalid ${configName} configuration:\n${errorMessages}`);
+    }
+
+    return result.data!;
+  }
+
+  /**
+   * Validate agent config or throw
+   */
+  static validateAgentOrThrow(data: unknown): AgentConfig {
+    return this.validateOrThrow(AgentConfigSchema, data, 'agent');
+  }
+
+  /**
+   * Validate task config or throw
+   */
+  static validateTaskOrThrow(data: unknown): TaskConfig {
+    return this.validateOrThrow(TaskConfigSchema, data, 'task');
+  }
+
+  /**
+   * Validate swarm config or throw
+   */
+  static validateSwarmOrThrow(data: unknown): SwarmConfig {
+    return this.validateOrThrow(SwarmConfigSchema, data, 'swarm');
+  }
+
+  /**
+   * Validate memory config or throw
+   */
+  static validateMemoryOrThrow(data: unknown): MemoryConfig {
+    return this.validateOrThrow(MemoryConfigSchema, data, 'memory');
+  }
+
+  /**
+   * Validate MCP server config or throw
+   */
+  static validateMCPServerOrThrow(data: unknown): MCPServerConfig {
+    return this.validateOrThrow(MCPServerConfigSchema, data, 'MCP server');
+  }
+
+  /**
+   * Validate orchestrator config or throw
+   */
+  static validateOrchestratorOrThrow(data: unknown): OrchestratorConfig {
+    return this.validateOrThrow(OrchestratorConfigSchema, data, 'orchestrator');
+  }
+
+  /**
+   * Validate system config or throw
+   */
+  static validateSystemOrThrow(data: unknown): SystemConfig {
+    return this.validateOrThrow(SystemConfigSchema, data, 'system');
+  }
+
+  /**
+   * Check if data matches schema
+   */
+  static isValid<TInput, TOutput>(
+    schema: z.ZodType<TOutput, z.ZodTypeDef, TInput>,
+    data: unknown
+  ): boolean {
+    return validate(schema, data).success;
+  }
+}
+
+
+--- src/core/event-bus.ts (truncated) ---
+/**
+ * V3 Event Bus
+ * Core event pub/sub implementation
+ */
+
+import type {
+  IEvent,
+  IEventBus,
+  IEventCreate,
+  IEventHandler,
+  IEventSubscription,
+  IEventFilter,
+} from './interfaces/event.interface.js';
+import { randomBytes } from 'crypto';
+
+// Secure event ID generation
+function generateSecureEventId(): string {
+  const timestamp = Date.now().toString(36);
+  const random = randomBytes(12).toString('hex');
+  return `evt_${timestamp}_${random}`;
+}
+
+/**
+ * Event subscription implementation
+ */
+class EventSubscription implements IEventSubscription {
+  private active = true;
+  private paused = false;
+
+  constructor(
+    readonly id: string,
+    readonly filter: IEventFilter,
+    private removeCallback: () => void,
+  ) {}
+
+  unsubscribe(): void {
+    this.active = false;
+    this.removeCallback();
+  }
+
+  pause(): void {
+    this.paused = true;
+  }
+
+  resume(): void {
+    this.paused = false;
+  }
+
+  isActive(): boolean {
+    return this.active && !this.paused;
+  }
+}
+
+/**
+ * Event bus implementation
+ */
+export class EventBus implements IEventBus {
+  private handlers = new Map<string, Set<IEventHandler>>();
+  private subscriptions = new Map<string, { filter: IEventFilter; handler: IEventHandler; subscription: EventSubscription }>();
+  private subscriptionId = 0;
+
+  emit<T = unknown>(type: string, payload: T, options?: Partial<IEventCreate<T>>): void {
+    const event = this.createEvent(type, payload, options);
+    this.dispatchEvent(event);
+  }
+
+  async emitAsync<T = unknown>(type: string, payload: T, options?: Partial<IEventCreate<T>>): Promise<void> {
+    const event = this.createEvent(type, payload, options);
+    await this.dispatchEventAsync(event);
+  }
+
+  on<T = unknown>(type: string, handler: IEventHandler<T>): IEventSubscription {
+    return this.subscribe({ types: [type] }, handler);
+  }
+
+  subscribe<T = unknown>(filter: IEventFilter, handler: IEventHandler<T>): IEventSubscription {
+    const id = `sub_${++this.subscriptionId}`;
+
+    // Register for all matching types
+    const types = filter.types ?? ['*'];
+    for (const type of types) {
+      let handlers = this.handlers.get(type);
+      if (!handlers) {
+        handlers = new Set();
+        this.handlers.set(type, handlers);
+      }
+      handlers.add(handler as IEventHandler);
+    }
+
+    const subscription = new EventSubscription(id, filter, () => {
+      this.removeSubscription(id);
+    });
+
+    this.subscriptions.set(id, { filter, handler: handler as IEventHandler, subscription });
+
+    return subscription;
+  }
+
+  once<T = unknown>(type: string, handler: IEventHandler<T>): IEventSubscription {
+    const wrappedHandler: IEventHandler<T> = async (event) => {
+      subscription.unsubscribe();
+      await handler(event);
+    };
+
+    const subscription = this.on(type, wrappedHandler);
+    return subscription;
+  }
+
+  off(type: string, handler: IEventHandler): void {
+    const handlers = this.handlers.get(type);
+    if (handlers) {
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        this.handlers.delete(type);
+      }
+    }
+  }
+
+  removeAllListeners(type?: string): void {
+    if (type) {
+      this.handlers.delete(type);
+    } else {
+      this.handlers.clear();
+    }
+  }
+
+  listenerCount(type: string): number {
+    return this.handlers.get(type)?.size ?? 0;
+  }
+
+  eventNames(): string[] {
+    return Array.from(this.handlers.keys());
+  }
+
+  private createEvent<T>(type: string, payload: T, options?: Partial<IEventCreate<T>>): IEvent<T> {
+    return {
+      id: generateSecureEventId(),
+      type,
+      timestamp: new Date(),
+      source: options?.source ?? 'event-bus',
+      payload,
+      priority: options?.priority,
+      correlationId: options?.correlationId,
+      causationId: options?.causationId,
+      metadata: options?.metadata,
+    };
+  }
+
+  private dispatchEvent<T>(event: IEvent<T>): void {
+    // Get handlers for specific type
+    const typeHandlers = this.handlers.get(event.type);
+
+    // Get wildcard handlers
+    const wildcardHandlers = this.handlers.get('*');
+
+    const allHandlers = new Set<IEventHandler>();
+
+    if (typeHandlers) {
+      for (const handler of typeHandlers) {
+        allHandlers.add(handler);
+      }
+    }
+
+    if (wildcardHandlers) {
+      for (const handler of wildcardHandlers) {
+        allHandlers.add(handler);
+      }
+    }
+
+    for (const handler of allHandlers) {
+      try {
+        const result = handler(event);
+        if (result instanceof Promise) {
+          result.catch((error) => {
+            console.error(`Error in async event handler for ${event.type}:`, error);
+          });
+        }
+      } catch (error) {
+        console.error(`Error in event handler for ${event.type}:`, error);
+      }
+    }
+  }
+
+  private async dispatchEventAsync<T>(event: IEvent<T>): Promise<void> {
+    const typeHandlers = this.handlers.get(event.type);
+    const wildcardHandlers = this.handlers.get('*');
+
+    const allHandlers = new Set<IEventHandler>();
+
+    if (typeHandlers) {
+      for (const handler
+
+--- src/core/index.ts ---
+/**
+ * V3 Core Module - Public API
+ * Domain-Driven Design with Clean Architecture
+ *
+ * This module provides the core architecture for claude-flow v3:
+ * - Decomposed orchestrator (task, session, health, lifecycle management)
+ * - Event-driven architecture with event bus and coordinator
+ * - Type-safe configuration with Zod validation
+ * - Clean interfaces following DDD principles
+ */
+
+// Interfaces (Domain contracts)
+export * from './interfaces/index.js';
+
+// Event system
+export { EventBus, createEventBus } from './event-bus.js';
+
+// Orchestrator components (decomposed)
+export * from './orchestrator/index.js';
+
+// Configuration
+export * from './config/index.js';
+
+
+--- src/core/interfaces/agent.interface.ts ---
+/**
+ * V3 Agent Interfaces
+ * Domain-Driven Design - Agent Lifecycle Bounded Context
+ */
+
+/**
+ * Agent status in the system
+ */
+export type AgentStatus = 'spawning' | 'active' | 'idle' | 'busy' | 'error' | 'terminated';
+
+/**
+ * Agent type classification
+ */
+export type AgentType =
+  | 'coder'
+  | 'reviewer'
+  | 'tester'
+  | 'researcher'
+  | 'planner'
+  | 'architect'
+  | 'coordinator'
+  | 'security'
+  | 'performance'
+  | 'custom';
+
+/**
+ * Agent capability declaration
+ */
+export interface IAgentCapability {
+  name: string;
+  level: 'basic' | 'intermediate' | 'advanced' | 'expert';
+  description?: string;
+}
+
+/**
+ * Agent configuration for spawning
+ */
+export interface IAgentConfig {
+  readonly id: string;
+  readonly name: string;
+  readonly type: AgentType | string;
+
+  capabilities: string[];
+  maxConcurrentTasks: number;
+  priority: number;
+
+  timeout?: number;
+  retryPolicy?: {
+    maxRetries: number;
+    backoffMs: number;
+    backoffMultiplier: number;
+  };
+
+  resources?: {
+    maxMemoryMb?: number;
+    maxCpuPercent?: number;
+  };
+
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Core agent entity
+ */
+export interface IAgent {
+  readonly id: string;
+  readonly name: string;
+  readonly type: AgentType | string;
+  readonly config: IAgentConfig;
+  readonly createdAt: Date;
+
+  status: AgentStatus;
+  currentTaskCount: number;
+  lastActivity: Date;
+
+  sessionId?: string;
+  terminalId?: string;
+  memoryBankId?: string;
+
+  metrics?: {
+    tasksCompleted: number;
+    tasksFailed: number;
+    avgTaskDuration: number;
+    errorCount: number;
+    uptime: number;
+  };
+
+  health?: {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    lastCheck: Date;
+    issues?: string[];
+  };
+}
+
+/**
+ * Agent session for tracking active work
+ */
+export interface IAgentSession {
+  readonly id: string;
+  readonly agentId: string;
+  readonly startTime: Date;
+
+  status: 'active' | 'idle' | 'terminated';
+  terminalId: string;
+  memoryBankId: string;
+
+  lastActivity: Date;
+  endTime?: Date;
+
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Agent pool for managing multiple agents
+ */
+export interface IAgentPool {
+  /**
+   * Add an agent to the pool
+   */
+  add(agent: IAgent): void;
+
+  /**
+   * Remove an agent from the pool
+   */
+  remove(agentId: string): boolean;
+
+  /**
+   * Get an agent by ID
+   */
+  get(agentId: string): IAgent | undefined;
+
+  /**
+   * Get all agents in the pool
+   */
+  getAll(): IAgent[];
+
+  /**
+   * Get agents by status
+   */
+  getByStatus(status: AgentStatus): IAgent[];
+
+  /**
+   * Get agents by type
+   */
+  getByType(type: AgentType | string): IAgent[];
+
+  /**
+   * Get available agents (can accept more tasks)
+   */
+  getAvailable(): IAgent[];
+
+  /**
+   * Get pool size
+   */
+  size(): number;
+
+  /**
+   * Check if pool has capacity
+   */
+  hasCapacity(maxSize: number): boolean;
+
+  /**
+   * Clear all agents
+   */
+  clear(): void;
+}
+
+/**
+ * Agent lifecycle manager interface
+ */
+export interface IAgentLifecycleManager {
+  /**
+   * Spawn a new agent
+   */
+  spawn(config: IAgentConfig): Promise<IAgent>;
+
+  /**
+   * Spawn multiple agents in parallel
+   */
+  spawnBatch(configs: IAgentConfig[]): Promise<Map<string, IAgent>>;
+
+  /**
+   * Terminate an agent
+   */
+  terminate(agentId: string, reason?: string): Promise<void>;
+
+  /**
+   * Terminate all agents
+   */
+  terminateAll(reason?: string): Promise<void>;
+
+  /**
+   * Restart an agent
+   */
+  restart(agentId: string): Promise<IAgent>;
+
+  /**
+   * Update agent configuration
+   */
+  updateConfig(agentId: string, config: Partial<IAgentConfig>): Promise<void>;
+
+  /**
+   * Get agent by ID
+   */
+  getAgent(agentId: string): IAgent | undefined;
+
+  /**
+   * Get all agents
+   */
+  getAllAgents(): IAgent[];
+
+  /**
+   * Get active agents count
+   */
+  getActiveCount(): number;
+
+  /**
+   * Check agent health
+   */
+  checkHealth(agentId: string): Promise<IAgent['health']>;
+}
+
+/**
+ * Agent registry for type definitions
+ */
+export interface IAgentRegistry {
+  /**
+   * Register an agent type with default config
+   */
+  register(type: string, defaultConfig: Partial<IAgentConfig>): void;
+
+  /**
+   * Unregister an agent type
+   */
+  unregister(type: string): boolean;
+
+  /**
+   * Get default config for a type
+   */
+  getDefaultConfig(type: string): Partial<IAgentConfig> | undefined;
+
+  /**
+   * Get all registered types
+   */
+  getRegisteredTypes(): string[];
+
+  /**
+   * Check if a type is registered
+   */
+  isRegistered(type: string): boolean;
+}
+
+
+--- src/core/interfaces/coordinator.interface.ts (truncated) ---
+/**
+ * V3 Coordinator Interfaces
+ * Domain-Driven Design - Coordination Bounded Context
+ * Aligned with ADR-003 (Single Coordination Engine)
+ */
+
+import type { ITask, ITaskResult } from './task.interface.js';
+import type { IAgent, IAgentConfig } from './agent.interface.js';
+
+/**
+ * Swarm topology types
+ */
+export type SwarmTopology =
+  | 'hierarchical'
+  | 'mesh'
+  | 'ring'
+  | 'star'
+  | 'adaptive'
+  | 'hierarchical-mesh';
+
+/**
+ * Coordination status
+ */
+export type CoordinationStatus =
+  | 'initializing'
+  | 'ready'
+  | 'coordinating'
+  | 'degraded'
+  | 'error'
+  | 'shutdown';
+
+/**
+ * Swarm configuration
+ */
+export interface ISwarmConfig {
+  topology: SwarmTopology;
+  maxAgents: number;
+
+  autoScale?: {
+    enabled: boolean;
+    minAgents: number;
+    maxAgents: number;
+    scaleUpThreshold: number;
+    scaleDownThreshold: number;
+  };
+
+  coordination?: {
+    consensusRequired: boolean;
+    timeoutMs: number;
+    retryPolicy: {
+      maxRetries: number;
+      backoffMs: number;
+    };
+  };
+
+  communication?: {
+    protocol: 'events' | 'messages' | 'shared-memory';
+    batchSize: number;
+    flushIntervalMs: number;
+  };
+
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Swarm state
+ */
+export interface ISwarmState {
+  readonly id: string;
+  readonly topology: SwarmTopology;
+  readonly createdAt: Date;
+
+  status: CoordinationStatus;
+  agentCount: number;
+  taskCount: number;
+
+  metrics?: {
+    throughput: number;
+    latencyMs: number;
+    successRate: number;
+    resourceUtilization: number;
+  };
+}
+
+/**
+ * Coordinator interface - unified coordination engine
+ */
+export interface ICoordinator {
+  /**
+   * Initialize the coordinator
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Shutdown the coordinator
+   */
+  shutdown(): Promise<void>;
+
+  /**
+   * Initialize a swarm with configuration
+   */
+  initializeSwarm(config: ISwarmConfig): Promise<ISwarmState>;
+
+  /**
+   * Get swarm state
+   */
+  getSwarmState(): ISwarmState | undefined;
+
+  /**
+   * Assign a task to an agent
+   */
+  assignTask(task: ITask, agentId: string): Promise<void>;
+
+  /**
+   * Get tasks assigned to an agent
+   */
+  getAgentTasks(agentId: string): Promise<ITask[]>;
+
+  /**
+   * Get task count for an agent
+   */
+  getAgentTaskCount(agentId: string): Promise<number>;
+
+  /**
+   * Cancel a task
+   */
+  cancelTask(taskId: string): Promise<void>;
+
+  /**
+   * Report task completion
+   */
+  reportTaskComplete(taskId: string, result: ITaskResult): Promise<void>;
+
+  /**
+   * Get coordination health status
+   */
+  getHealthStatus(): Promise<{ healthy: boolean; error?: string; metrics?: Record<string, number> }>;
+
+  /**
+   * Perform maintenance tasks
+   */
+  performMaintenance(): Promise<void>;
+}
+
+/**
+ * Coordination manager interface - higher-level orchestration
+ */
+export interface ICoordinationManager extends ICoordinator {
+  /**
+   * Register an agent with the coordinator
+   */
+  registerAgent(agent: IAgent): Promise<void>;
+
+  /**
+   * Unregister an agent
+   */
+  unregisterAgent(agentId: string): Promise<void>;
+
+  /**
+   * Get all registered agents
+   */
+  getRegisteredAgents(): IAgent[];
+
+  /**
+   * Request agent consensus on a decision
+   */
+  requestConsensus(topic: string, options: unknown[], timeout?: number): Promise<unknown>;
+
+  /**
+   * Broadcast message to all agents
+   */
+  broadcast(message: unknown): Promise<void>;
+
+  /**
+   * Send message to specific agent
+   */
+  sendToAgent(agentId: string, message: unknown): Promise<void>;
+
+  /**
+   * Acquire a distributed lock
+   */
+  acquireLock(resourceId: string, agentId: string, timeout?: number): Promise<boolean>;
+
+  /**
+   * Release a distributed lock
+   */
+  releaseLock(resourceId: string, agentId: string): Promise<void>;
+
+  /**
+   * Check for deadlocks
+   */
+  detectDeadlocks(): Promise<{ detected: boolean; agents?: string[]; resources?: string[] }>;
+}
+
+/**
+ * Health status for components
+ */
+export interface IHealthStatus {
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  components: Record<string, IComponentHealth>;
+  timestamp: Date;
+}
+
+/**
+ * Component health details
+ */
+export interface IComponentHealth {
+  name: string;
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  lastCheck: Date;
+  error?: string;
+  metrics?: Record<string, number>;
+}
+
+/**
+ * Health monitor interface
+ */
+export interface IHealthMonitor {
+  /**
+   * Start health monitoring
+   */
+  start(): void;
+
+  /**
+   * Stop health monitoring
+   */
+  stop(): void;
+
+  /**
+   * Get current health status
+   */
+  getStatus(): Promise<IHealthStatus>;
+
+  /**
+   * Register a health check
+   */
+  registerCheck(
+    name: string,
+    check: () => Promise<{ healthy: boolean; error?: string; metrics?: Record<string, number> }>
+  ): void;
+
+  /**
+   * Unregister a health check
+   */
+  unregisterCheck(name: string): void;
+
+  /**
+   * Get health history
+   */
+  getHistory(limit?: number): IHealthStatus[];
+
+  /**
+   * Subscribe to health changes
+   */
+  onHealthChange(callback: (status: IHealthStatus) => void): () => void;
+}
+
+/**
+ * Metrics co
+
+--- src/core/interfaces/event.interface.ts (truncated) ---
+/**
+ * V3 Event Interfaces
+ * Domain-Driven Design - Event Sourcing Pattern (ADR-007)
+ */
+
+/**
+ * Event priority levels
+ */
+export type EventPriority = 'critical' | 'high' | 'normal' | 'low';
+
+/**
+ * Core event structure
+ */
+export interface IEvent<T = unknown> {
+  readonly id: string;
+  readonly type: string;
+  readonly timestamp: Date;
+  readonly source: string;
+
+  payload: T;
+  priority?: EventPriority;
+  correlationId?: string;
+  causationId?: string;
+
+  metadata?: {
+    version?: number;
+    userId?: string;
+    sessionId?: string;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Event creation parameters
+ */
+export interface IEventCreate<T = unknown> {
+  type: string;
+  payload: T;
+  source?: string;
+  priority?: EventPriority;
+  correlationId?: string;
+  causationId?: string;
+  metadata?: IEvent['metadata'];
+}
+
+/**
+ * Event handler function type
+ */
+export type IEventHandler<T = unknown> = (event: IEvent<T>) => void | Promise<void>;
+
+/**
+ * Event filter for subscriptions
+ */
+export interface IEventFilter {
+  types?: string[];
+  sources?: string[];
+  priority?: EventPriority[];
+  correlationId?: string;
+}
+
+/**
+ * Event subscription handle
+ */
+export interface IEventSubscription {
+  readonly id: string;
+  readonly filter: IEventFilter;
+
+  /**
+   * Unsubscribe from events
+   */
+  unsubscribe(): void;
+
+  /**
+   * Pause subscription
+   */
+  pause(): void;
+
+  /**
+   * Resume subscription
+   */
+  resume(): void;
+
+  /**
+   * Check if subscription is active
+   */
+  isActive(): boolean;
+}
+
+/**
+ * Event bus interface for pub/sub communication
+ */
+export interface IEventBus {
+  /**
+   * Emit an event to all subscribers
+   */
+  emit<T = unknown>(type: string, payload: T, options?: Partial<IEventCreate<T>>): void;
+
+  /**
+   * Emit an event and wait for all handlers
+   */
+  emitAsync<T = unknown>(type: string, payload: T, options?: Partial<IEventCreate<T>>): Promise<void>;
+
+  /**
+   * Subscribe to events matching a type pattern
+   */
+  on<T = unknown>(type: string, handler: IEventHandler<T>): IEventSubscription;
+
+  /**
+   * Subscribe to events with filter
+   */
+  subscribe<T = unknown>(filter: IEventFilter, handler: IEventHandler<T>): IEventSubscription;
+
+  /**
+   * Subscribe to a single event occurrence
+   */
+  once<T = unknown>(type: string, handler: IEventHandler<T>): IEventSubscription;
+
+  /**
+   * Remove a specific handler
+   */
+  off(type: string, handler: IEventHandler): void;
+
+  /**
+   * Remove all handlers for a type
+   */
+  removeAllListeners(type?: string): void;
+
+  /**
+   * Get count of listeners for a type
+   */
+  listenerCount(type: string): number;
+
+  /**
+   * Get all event types with active listeners
+   */
+  eventNames(): string[];
+}
+
+/**
+ * System event types enumeration
+ */
+export const SystemEventTypes = {
+  // System lifecycle
+  SYSTEM_READY: 'system:ready',
+  SYSTEM_SHUTDOWN: 'system:shutdown',
+  SYSTEM_ERROR: 'system:error',
+  SYSTEM_HEALTHCHECK: 'system:healthcheck',
+
+  // Agent lifecycle
+  AGENT_SPAWNED: 'agent:spawned',
+  AGENT_TERMINATED: 'agent:terminated',
+  AGENT_ERROR: 'agent:error',
+  AGENT_IDLE: 'agent:idle',
+  AGENT_BUSY: 'agent:busy',
+  AGENT_HEALTH_CHANGED: 'agent:health:changed',
+
+  // Task lifecycle
+  TASK_CREATED: 'task:created',
+  TASK_ASSIGNED: 'task:assigned',
+  TASK_STARTED: 'task:started',
+  TASK_COMPLETED: 'task:completed',
+  TASK_FAILED: 'task:failed',
+  TASK_CANCELLED: 'task:cancelled',
+  TASK_TIMEOUT: 'task:timeout',
+  TASK_RETRY: 'task:retry',
+
+  // Session lifecycle
+  SESSION_CREATED: 'session:created',
+  SESSION_RESTORED: 'session:restored',
+  SESSION_TERMINATED: 'session:terminated',
+  SESSION_PERSISTED: 'session:persisted',
+
+  // Memory events
+  MEMORY_STORED: 'memory:stored',
+  MEMORY_RETRIEVED: 'memory:retrieved',
+  MEMORY_CLEARED: 'memory:cleared',
+
+  // Coordination events
+  COORDINATION_STARTED: 'coordination:started',
+  COORDINATION_COMPLETED: 'coordination:completed',
+  DEADLOCK_DETECTED: 'coordination:deadlock',
+
+  // Metrics events
+  METRICS_COLLECTED: 'metrics:collected',
+} as const;
+
+export type SystemEventType = typeof SystemEventTypes[keyof typeof SystemEventTypes];
+
+/**
+ * Event store interface for event sourcing
+ */
+export interface IEventStore {
+  /**
+   * Append an event to the store
+   */
+  append(event: IEvent): Promise<void>;
+
+  /**
+   * Get events by aggregate ID
+   */
+  getByAggregateId(aggregateId: string, fromVersion?: number): Promise<IEvent[]>;
+
+  /**
+   * Get events by type
+   */
+  getByType(type: string, options?: { limit?: number; offset?: number }): Promise<IEvent[]>;
+
+  /**
+   * Get events in time range
+   */
+  getByTimeRange(start: Date, end: Date): Promise<IEvent[]>;
+
+  /**
+   * Get events by correlation ID
+   */
+  getByCorrelationId(correlationId: string): Promise<IEvent[]>;
+
+  /**
+   * Get all events (paginated)
+   */
+  getAll(options?: { limit?: number; offset?: number }): Promise<IEvent[]>;
+
+  /**
+   * Get event count
+   */
+  count(filter?: IEventFilter): Promise<number>;
+
+  /**
+   * Clear old events
+   */
+  prune(olderThan: Date): P
+
+--- src/core/interfaces/index.ts ---
+/**
+ * V3 Core Interfaces - Public API
+ * Domain-Driven Design with Clean Architecture
+ */
+
+// Task interfaces
+export * from './task.interface.js';
+
+// Agent interfaces
+export * from './agent.interface.js';
+
+// Event interfaces
+export * from './event.interface.js';
+
+// Memory interfaces
+export * from './memory.interface.js';
+
+// Coordinator interfaces
+export * from './coordinator.interface.js';
+
+
+--- src/core/interfaces/memory.interface.ts (truncated) ---
+/**
+ * V3 Memory Interfaces
+ * Domain-Driven Design - Memory Management Bounded Context
+ * Aligned with ADR-006 (Unified Memory Service) and ADR-009 (Hybrid Memory Backend)
+ */
+
+/**
+ * Memory entry types
+ */
+export type MemoryType = 'session' | 'persistent' | 'vector' | 'cache' | 'pattern';
+
+/**
+ * Memory entry structure
+ */
+export interface IMemoryEntry {
+  readonly id: string;
+  readonly key: string;
+  readonly type: MemoryType;
+  readonly createdAt: Date;
+
+  value: unknown;
+  updatedAt: Date;
+  expiresAt?: Date;
+
+  metadata?: {
+    source?: string;
+    agentId?: string;
+    sessionId?: string;
+    version?: number;
+    tags?: string[];
+    embedding?: number[];
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Memory entry creation parameters
+ */
+export interface IMemoryEntryCreate {
+  key: string;
+  value: unknown;
+  type?: MemoryType;
+  expiresAt?: Date;
+  ttlMs?: number;
+  metadata?: IMemoryEntry['metadata'];
+}
+
+/**
+ * Vector search parameters
+ */
+export interface IVectorSearchParams {
+  embedding: number[];
+  k?: number;
+  threshold?: number;
+  filter?: {
+    type?: MemoryType;
+    tags?: string[];
+    agentId?: string;
+  };
+}
+
+/**
+ * Vector search result
+ */
+export interface IVectorSearchResult {
+  entry: IMemoryEntry;
+  score: number;
+  distance: number;
+}
+
+/**
+ * Memory backend interface for storage operations
+ */
+export interface IMemoryBackend {
+  /**
+   * Initialize the backend
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Shutdown the backend
+   */
+  shutdown(): Promise<void>;
+
+  /**
+   * Store a memory entry
+   */
+  store(entry: IMemoryEntryCreate): Promise<IMemoryEntry>;
+
+  /**
+   * Retrieve a memory entry by key
+   */
+  retrieve(key: string): Promise<IMemoryEntry | undefined>;
+
+  /**
+   * Retrieve by ID
+   */
+  retrieveById(id: string): Promise<IMemoryEntry | undefined>;
+
+  /**
+   * Update a memory entry
+   */
+  update(key: string, value: unknown, metadata?: Partial<IMemoryEntry['metadata']>): Promise<IMemoryEntry | undefined>;
+
+  /**
+   * Delete a memory entry
+   */
+  delete(key: string): Promise<boolean>;
+
+  /**
+   * Check if a key exists
+   */
+  exists(key: string): Promise<boolean>;
+
+  /**
+   * List all keys matching a pattern
+   */
+  keys(pattern?: string): Promise<string[]>;
+
+  /**
+   * Get all entries matching filter
+   */
+  list(filter?: { type?: MemoryType; tags?: string[] }): Promise<IMemoryEntry[]>;
+
+  /**
+   * Clear all entries
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Get entry count
+   */
+  count(): Promise<number>;
+
+  /**
+   * Prune expired entries
+   */
+  prune(): Promise<number>;
+
+  /**
+   * Get health status
+   */
+  getHealthStatus(): Promise<{ healthy: boolean; error?: string; metrics?: Record<string, number> }>;
+}
+
+/**
+ * Vector memory backend for similarity search
+ */
+export interface IVectorMemoryBackend extends IMemoryBackend {
+  /**
+   * Store with embedding
+   */
+  storeVector(entry: IMemoryEntryCreate & { embedding: number[] }): Promise<IMemoryEntry>;
+
+  /**
+   * Search by vector similarity
+   */
+  search(params: IVectorSearchParams): Promise<IVectorSearchResult[]>;
+
+  /**
+   * Update embedding for an entry
+   */
+  updateEmbedding(key: string, embedding: number[]): Promise<boolean>;
+
+  /**
+   * Build or rebuild index
+   */
+  buildIndex(): Promise<void>;
+
+  /**
+   * Get index statistics
+   */
+  getIndexStats(): Promise<{
+    vectorCount: number;
+    dimensions: number;
+    indexType: string;
+    memoryUsageMb: number;
+  }>;
+}
+
+/**
+ * Memory bank for agent-specific storage
+ */
+export interface IMemoryBank {
+  readonly id: string;
+  readonly agentId: string;
+  readonly createdAt: Date;
+
+  /**
+   * Store in bank
+   */
+  store(key: string, value: unknown, options?: Partial<IMemoryEntryCreate>): Promise<IMemoryEntry>;
+
+  /**
+   * Retrieve from bank
+   */
+  retrieve(key: string): Promise<IMemoryEntry | undefined>;
+
+  /**
+   * Delete from bank
+   */
+  delete(key: string): Promise<boolean>;
+
+  /**
+   * List all entries in bank
+   */
+  list(): Promise<IMemoryEntry[]>;
+
+  /**
+   * Clear all entries in bank
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Get bank size
+   */
+  size(): Promise<number>;
+
+  /**
+   * Close the bank
+   */
+  close(): Promise<void>;
+}
+
+/**
+ * Memory manager interface
+ */
+export interface IMemoryManager {
+  /**
+   * Initialize the manager
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Shutdown the manager
+   */
+  shutdown(): Promise<void>;
+
+  /**
+   * Create a memory bank for an agent
+   */
+  createBank(agentId: string): Promise<string>;
+
+  /**
+   * Get a memory bank
+   */
+  getBank(bankId: string): IMemoryBank | undefined;
+
+  /**
+   * Close a memory bank
+   */
+  closeBank(bankId: string): Promise<void>;
+
+  /**
+   * Store in global memory
+   */
+  store(entry: IMemoryEntryCreate): Promise<IMemoryEntry>;
+
+  /**
+   * Retrieve from global memory
+   */
+  retrieve(key: string): Promise<IMemoryEntry | undefined>;
+
+  /**
+   * Search vectors (if vector backend available)
+   */
+  searchVectors?(params: IVectorSearchParams): Promise<IVectorSearchResult[]>;
+
+  /**
+   
+
+--- src/core/interfaces/task.interface.ts ---
+/**
+ * V3 Task Interfaces
+ * Domain-Driven Design - Task Bounded Context
+ */
+
+/**
+ * Task priority levels
+ */
+export type TaskPriority = 'critical' | 'high' | 'medium' | 'low';
+
+/**
+ * Task status throughout its lifecycle
+ */
+export type TaskStatus =
+  | 'pending'
+  | 'queued'
+  | 'assigned'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+  | 'timeout';
+
+/**
+ * Core task entity
+ */
+export interface ITask {
+  readonly id: string;
+  readonly type: string;
+  readonly description: string;
+  readonly priority: number;
+  readonly createdAt: Date;
+
+  status: TaskStatus;
+  assignedAgent?: string;
+  startedAt?: Date;
+  completedAt?: Date;
+  timeout?: number;
+
+  input?: Record<string, unknown>;
+  output?: Record<string, unknown>;
+  error?: Error;
+
+  metadata?: {
+    requiredCapabilities?: string[];
+    retryCount?: number;
+    maxRetries?: number;
+    critical?: boolean;
+    parentTaskId?: string;
+    childTaskIds?: string[];
+    tags?: string[];
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Task creation parameters
+ */
+export interface ITaskCreate {
+  type: string;
+  description: string;
+  priority?: number;
+  timeout?: number;
+  assignedAgent?: string;
+  input?: Record<string, unknown>;
+  metadata?: ITask['metadata'];
+}
+
+/**
+ * Task result after completion
+ */
+export interface ITaskResult {
+  taskId: string;
+  success: boolean;
+  output?: Record<string, unknown>;
+  error?: Error;
+  duration: number;
+  agentId?: string;
+  metrics?: {
+    tokensUsed?: number;
+    memoryPeakMb?: number;
+    retryCount?: number;
+  };
+}
+
+/**
+ * Task queue interface for managing task ordering and processing
+ */
+export interface ITaskQueue {
+  /**
+   * Add a task to the queue
+   */
+  enqueue(task: ITask): Promise<void>;
+
+  /**
+   * Remove and return the highest priority task
+   */
+  dequeue(): Promise<ITask | undefined>;
+
+  /**
+   * Peek at the next task without removing it
+   */
+  peek(): Promise<ITask | undefined>;
+
+  /**
+   * Get the current queue size
+   */
+  size(): number;
+
+  /**
+   * Check if the queue is empty
+   */
+  isEmpty(): boolean;
+
+  /**
+   * Clear all tasks from the queue
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Get all queued tasks (for inspection)
+   */
+  getAll(): Promise<ITask[]>;
+
+  /**
+   * Remove a specific task by ID
+   */
+  remove(taskId: string): Promise<boolean>;
+
+  /**
+   * Update task priority
+   */
+  updatePriority(taskId: string, priority: number): Promise<boolean>;
+}
+
+/**
+ * Task manager interface for lifecycle management
+ */
+export interface ITaskManager {
+  /**
+   * Create a new task
+   */
+  createTask(params: ITaskCreate): Promise<ITask>;
+
+  /**
+   * Get a task by ID
+   */
+  getTask(taskId: string): ITask | undefined;
+
+  /**
+   * Get all tasks matching optional filter
+   */
+  getTasks(filter?: Partial<Pick<ITask, 'status' | 'type' | 'assignedAgent'>>): ITask[];
+
+  /**
+   * Assign a task to an agent
+   */
+  assignTask(taskId: string, agentId: string): Promise<void>;
+
+  /**
+   * Start task execution
+   */
+  startTask(taskId: string): Promise<void>;
+
+  /**
+   * Complete a task with result
+   */
+  completeTask(taskId: string, result: ITaskResult): Promise<void>;
+
+  /**
+   * Fail a task with error
+   */
+  failTask(taskId: string, error: Error): Promise<void>;
+
+  /**
+   * Cancel a task
+   */
+  cancelTask(taskId: string, reason?: string): Promise<void>;
+
+  /**
+   * Retry a failed task
+   */
+  retryTask(taskId: string): Promise<void>;
+
+  /**
+   * Get task metrics
+   */
+  getMetrics(): TaskManagerMetrics;
+
+  /**
+   * Clean up old completed/failed tasks
+   */
+  cleanup(olderThan: Date): Promise<number>;
+}
+
+/**
+ * Task manager metrics
+ */
+export interface TaskManagerMetrics {
+  totalTasks: number;
+  pendingTasks: number;
+  runningTasks: number;
+  completedTasks: number;
+  failedTasks: number;
+  cancelledTasks: number;
+  avgDuration: number;
+  avgWaitTime: number;
+}
+
+/**
+ * Task assignment strategy interface
+ */
+export interface ITaskAssignmentStrategy {
+  /**
+   * Select the best agent for a task
+   */
+  selectAgent(task: ITask, availableAgents: string[]): Promise<string | undefined>;
+
+  /**
+   * Score an agent for a task (higher is better)
+   */
+  scoreAgent(task: ITask, agentId: string): Promise<number>;
+}
+
+
+## Instructions
+
+Analyze the above codebase context and provide your response following the format specified in the task.