agentic-qe 3.8.6 → 3.8.8

package/dist/cli/handlers/hypergraph-handler.js

@@ -0,0 +1,248 @@
+/**
+ * Agentic QE v3 - Hypergraph Command Handler
+ *
+ * Exposes hypergraph queries to users via CLI:
+ *   aqe hypergraph stats       - Show node/edge counts by type
+ *   aqe hypergraph untested    - Find functions with no test coverage
+ *   aqe hypergraph impacted    - Find tests impacted by changed files
+ *   aqe hypergraph gaps        - Find functions with low coverage
+ */
+import chalk from 'chalk';
+import { join, resolve } from 'path';
+import { existsSync } from 'fs';
+import { findProjectRoot } from '../../kernel/unified-memory.js';
+import { openDatabase } from '../../shared/safe-db.js';
+import { createHypergraphEngine } from '../../integrations/ruvector/hypergraph-engine.js';
+// ============================================================================
+// Hypergraph Handler
+// ============================================================================
+export class HypergraphHandler {
+    name = 'hypergraph';
+    description = 'Query the code knowledge hypergraph';
+    cleanupAndExit;
+    ensureInitialized;
+    constructor(cleanupAndExit, ensureInitialized) {
+        this.cleanupAndExit = cleanupAndExit;
+        this.ensureInitialized = ensureInitialized;
+    }
+    register(program, _context) {
+        const hg = program
+            .command('hypergraph')
+            .alias('hg')
+            .description(this.description);
+        hg
+            .command('stats')
+            .description('Show hypergraph statistics (node/edge counts by type)')
+            .option('--db <path>', 'Database path')
+            .action(async (options) => {
+            await this.executeStats(options);
+        });
+        hg
+            .command('untested')
+            .description('Find functions with no test coverage')
+            .option('--db <path>', 'Database path')
+            .option('--limit <number>', 'Max results', '20')
+            .action(async (options) => {
+            await this.executeUntested(options);
+        });
+        hg
+            .command('impacted <files...>')
+            .description('Find tests impacted by changed files')
+            .option('--db <path>', 'Database path')
+            .action(async (files, options) => {
+            await this.executeImpacted(files, options);
+        });
+        hg
+            .command('gaps')
+            .description('Find functions with low coverage')
+            .option('--db <path>', 'Database path')
+            .option('--max-coverage <number>', 'Coverage threshold (%)', '50')
+            .option('--limit <number>', 'Max results', '20')
+            .action(async (options) => {
+            await this.executeGaps(options);
+        });
+    }
+    // --------------------------------------------------------------------------
+    // Subcommands
+    // --------------------------------------------------------------------------
+    async executeStats(options) {
+        if (!await this.ensureInitialized())
+            return;
+        const { engine, close } = await this.openEngine(options.db);
+        try {
+            const stats = await engine.getStats();
+            console.log(chalk.blue('\n  Hypergraph Statistics\n'));
+            console.log(chalk.white(`  Total nodes: ${stats.totalNodes}`));
+            console.log(chalk.white(`  Total edges: ${stats.totalEdges}`));
+            if (stats.totalNodes > 0) {
+                console.log(chalk.gray('\n  Nodes by type:'));
+                for (const [type, count] of Object.entries(stats.nodesByType)) {
+                    if (count > 0) {
+                        console.log(chalk.gray(`    ${type}: ${count}`));
+                    }
+                }
+                console.log(chalk.gray('\n  Edges by type:'));
+                for (const [type, count] of Object.entries(stats.edgesByType)) {
+                    if (count > 0) {
+                        console.log(chalk.gray(`    ${type}: ${count}`));
+                    }
+                }
+                console.log(chalk.gray(`\n  Avg complexity: ${stats.avgComplexity.toFixed(1)}`));
+                console.log(chalk.gray(`  Avg coverage: ${stats.avgCoverage.toFixed(1)}%`));
+                console.log(chalk.gray(`  Nodes with embeddings: ${stats.nodesWithEmbeddings}`));
+            }
+            else {
+                console.log(chalk.yellow('\n  Hypergraph is empty. Run "aqe init --auto" to populate it.'));
+            }
+            console.log('');
+        }
+        finally {
+            close();
+        }
+        await this.cleanupAndExit(0);
+    }
+    async executeUntested(options) {
+        if (!await this.ensureInitialized())
+            return;
+        const { engine, close } = await this.openEngine(options.db);
+        try {
+            const limit = parseInt(options.limit, 10) || 20;
+            const untested = await engine.findUntestedFunctions();
+            const results = untested.slice(0, limit);
+            console.log(chalk.blue(`\n  Untested Functions (${untested.length} total)\n`));
+            if (results.length === 0) {
+                console.log(chalk.green('  All functions have test coverage!'));
+            }
+            else {
+                for (const fn of results) {
+                    const complexity = fn.complexity ? chalk.yellow(` complexity=${fn.complexity}`) : '';
+                    console.log(chalk.white(`  ${fn.name}`) + chalk.gray(` ${fn.filePath || ''}:${fn.lineStart || '?'}`) + complexity);
+                }
+                if (untested.length > limit) {
+                    console.log(chalk.gray(`\n  ... and ${untested.length - limit} more (use --limit to show more)`));
+                }
+            }
+            console.log('');
+        }
+        finally {
+            close();
+        }
+        await this.cleanupAndExit(0);
+    }
+    async executeImpacted(files, options) {
+        if (!await this.ensureInitialized())
+            return;
+        // Resolve relative paths to absolute so they match hypergraph entries
+        const absoluteFiles = files.map(f => resolve(f));
+        const { engine, close } = await this.openEngine(options.db);
+        try {
+            const tests = await engine.findImpactedTests(absoluteFiles);
+            console.log(chalk.blue(`\n  Impacted Tests for ${files.length} file(s)\n`));
+            if (tests.length === 0) {
+                console.log(chalk.gray('  No impacted tests found. The hypergraph may need rebuilding.'));
+            }
+            else {
+                for (const test of tests) {
+                    console.log(chalk.white(`  ${test.name}`) + chalk.gray(` ${test.filePath || ''}`));
+                }
+            }
+            console.log(chalk.gray(`\n  Total: ${tests.length} test(s)\n`));
+        }
+        finally {
+            close();
+        }
+        await this.cleanupAndExit(0);
+    }
+    async executeGaps(options) {
+        if (!await this.ensureInitialized())
+            return;
+        const { engine, close } = await this.openEngine(options.db);
+        try {
+            const maxCoverage = parseInt(options.maxCoverage, 10) || 50;
+            const limit = parseInt(options.limit, 10) || 20;
+            const gaps = await engine.findCoverageGaps(maxCoverage);
+            const results = gaps.slice(0, limit);
+            console.log(chalk.blue(`\n  Coverage Gaps (<= ${maxCoverage}%) — ${gaps.length} total\n`));
+            if (results.length === 0) {
+                console.log(chalk.green('  No coverage gaps found!'));
+            }
+            else {
+                for (const fn of results) {
+                    const cov = fn.coverage !== undefined ? chalk.red(` ${fn.coverage}%`) : '';
+                    const complexity = fn.complexity ? chalk.yellow(` complexity=${fn.complexity}`) : '';
+                    console.log(chalk.white(`  ${fn.name}`) + cov + chalk.gray(` ${fn.filePath || ''}`) + complexity);
+                }
+                if (gaps.length > limit) {
+                    console.log(chalk.gray(`\n  ... and ${gaps.length - limit} more (use --limit to show more)`));
+                }
+            }
+            console.log('');
+        }
+        finally {
+            close();
+        }
+        await this.cleanupAndExit(0);
+    }
+    // --------------------------------------------------------------------------
+    // Helpers
+    // --------------------------------------------------------------------------
+    async openEngine(dbPathOverride) {
+        const projectRoot = findProjectRoot();
+        const dbPath = dbPathOverride || join(projectRoot, '.agentic-qe', 'memory.db');
+        if (!existsSync(dbPath)) {
+            throw new Error(`Database not found: ${dbPath}\nRun "aqe init --auto" first.`);
+        }
+        const db = openDatabase(dbPath);
+        try {
+            const engine = await createHypergraphEngine({
+                db,
+                maxTraversalDepth: 10,
+                maxQueryResults: 1000,
+                enableVectorSearch: false,
+            });
+            return {
+                engine,
+                close: () => {
+                    try {
+                        db.close();
+                    }
+                    catch { /* ignore */ }
+                },
+            };
+        }
+        catch (error) {
+            // Close db if engine creation fails to prevent connection leak
+            try {
+                db.close();
+            }
+            catch { /* ignore */ }
+            throw error;
+        }
+    }
+    getHelp() {
+        return `
+Query the code knowledge hypergraph for untested functions,
+impacted tests, and coverage gaps.
+
+Usage:
+  aqe hypergraph stats                    Show node/edge counts by type
+  aqe hypergraph untested [--limit N]     Find functions with no test coverage
+  aqe hypergraph impacted <files...>      Find tests impacted by changed files
+  aqe hypergraph gaps [--max-coverage N]  Find functions with low coverage
+
+Options:
+  --db <path>          Override database path (default: .agentic-qe/memory.db)
+  --limit <number>     Max results (default: 20)
+  --max-coverage <n>   Coverage threshold for gaps (default: 50)
+
+Alias: aqe hg stats
+`;
+    }
+}
+// ============================================================================
+// Factory
+// ============================================================================
+export function createHypergraphHandler(cleanupAndExit, ensureInitialized) {
+    return new HypergraphHandler(cleanupAndExit, ensureInitialized);
+}
+//# sourceMappingURL=hypergraph-handler.js.map

package/dist/cli/handlers/index.d.ts

@@ -11,4 +11,5 @@ export { AgentHandler, createAgentHandler } from './agent-handler.js';
 export { DomainHandler, createDomainHandler } from './domain-handler.js';
 export { ProtocolHandler, createProtocolHandler } from './protocol-handler.js';
 export { BrainHandler, createBrainHandler } from './brain-handler.js';
+export { HypergraphHandler, createHypergraphHandler } from './hypergraph-handler.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/handlers/index.js

@@ -13,4 +13,5 @@ export { AgentHandler, createAgentHandler } from './agent-handler.js';
 export { DomainHandler, createDomainHandler } from './domain-handler.js';
 export { ProtocolHandler, createProtocolHandler } from './protocol-handler.js';
 export { BrainHandler, createBrainHandler } from './brain-handler.js';
+export { HypergraphHandler, createHypergraphHandler } from './hypergraph-handler.js';
 //# sourceMappingURL=index.js.map

package/dist/cli/handlers/init-handler.d.ts

@@ -40,6 +40,7 @@ interface InitOptions {
     withWindsurf?: boolean;
     withContinuedev?: boolean;
     withAllPlatforms?: boolean;
+    withMcp?: boolean;
     withClaudeFlow?: boolean;
     skipClaudeFlow?: boolean;
     noGovernance?: boolean;

package/dist/cli/handlers/init-handler.js

@@ -49,6 +49,7 @@ export class InitHandler {
             .option('--with-codex', 'Include OpenAI Codex CLI MCP config and AGENTS.md')
             .option('--with-windsurf', 'Include Windsurf MCP config and rules')
             .option('--with-continuedev', 'Include Continue.dev MCP config and rules')
+            .option('--with-mcp', 'Include MCP server config in .mcp.json (opt-in — CLI works without MCP)')
             .option('--with-all-platforms', 'Include all coding agent platform configurations')
             .option('--auto-migrate', 'Automatically migrate from v2 if detected')
             .option('--with-claude-flow', 'Force Claude Flow integration setup')
@@ -114,6 +115,7 @@ export class InitHandler {
             withCodex: options.withCodex,
             withWindsurf: options.withWindsurf,
             withContinueDev: options.withContinuedev,
+            withMcp: options.withMcp,
             noGovernance: options.noGovernance,
         });
         console.log(chalk.white('  Analyzing project...\n'));
@@ -170,9 +172,14 @@ export class InitHandler {
             console.log(chalk.gray(`    - Claude Flow: ${cfResult?.available ? 'Enabled' : 'Standalone mode'}`));
             console.log(chalk.gray(`    - Total time: ${result.totalDurationMs}ms\n`));
             console.log(chalk.white('Next steps:'));
-            console.log(chalk.gray('  1. Add MCP: claude mcp add aqe -- aqe-mcp'));
-            console.log(chalk.gray('  2. Run tests: aqe test <path>'));
-            console.log(chalk.gray('  3. Check status: aqe status\n'));
+            console.log(chalk.gray('  1. Run tests: aqe test <path>'));
+            console.log(chalk.gray('  2. Check coverage: aqe coverage <path>'));
+            console.log(chalk.gray('  3. Check status: aqe status'));
+            if (!result.summary.mcpConfigured) {
+                console.log(chalk.gray('\n  Optional — enable MCP server for richer agent integration:'));
+                console.log(chalk.gray('    aqe init --with-mcp'));
+                console.log(chalk.gray('    # or manually: claude mcp add aqe -- aqe-mcp\n'));
+            }
         }
         else {
             console.log(chalk.red('  Initialization failed. Check errors above.\n'));
@@ -220,9 +227,14 @@ export class InitHandler {
             }
             console.log(chalk.gray(`    - Total time: ${result.totalDurationMs}ms\n`));
             console.log(chalk.white('Next steps:'));
-            console.log(chalk.gray('  1. Add MCP: claude mcp add aqe -- aqe-mcp'));
-            console.log(chalk.gray('  2. Run tests: aqe test <path>'));
-            console.log(chalk.gray('  3. Check status: aqe status\n'));
+            console.log(chalk.gray('  1. Run tests: aqe test <path>'));
+            console.log(chalk.gray('  2. Check coverage: aqe coverage <path>'));
+            console.log(chalk.gray('  3. Check status: aqe status'));
+            if (!result.summary.mcpConfigured) {
+                console.log(chalk.gray('\n  Optional — enable MCP server for richer agent integration:'));
+                console.log(chalk.gray('    aqe init --with-mcp'));
+                console.log(chalk.gray('    # or manually: claude mcp add aqe -- aqe-mcp\n'));
+            }
         }
         else {
             console.log(chalk.red('  Initialization failed. Check errors above.\n'));

package/dist/cli/index.js

@@ -816,6 +816,7 @@ import { createLLMRouterCommand } from './commands/llm-router.js';
 import { createSyncCommands } from './commands/sync.js';
 import { createHooksCommand } from './commands/hooks.js';
 import { createLearningCommand } from './commands/learning.js';
+import { createMemoryCommand } from './commands/memory.js';
 import { createMcpCommand } from './commands/mcp.js';
 import { createPlatformCommand } from './commands/platform.js';
 import { createProveCommand } from './commands/prove.js';
@@ -826,6 +827,7 @@ program.addCommand(createLLMRouterCommand());
 program.addCommand(createSyncCommands());
 program.addCommand(createHooksCommand());
 program.addCommand(createLearningCommand());
+program.addCommand(createMemoryCommand(context, cleanupAndExit, ensureInitialized));
 program.addCommand(createMcpCommand());
 program.addCommand(createPlatformCommand());
 program.addCommand(createProveCommand(context, cleanupAndExit, ensureInitialized));

package/dist/coordination/protocols/code-intelligence-index.js

@@ -128,17 +128,8 @@ export class CodeIntelligenceIndexProtocol {
                 filesIndexed: indexResult.value.filesIndexed,
                 duration: indexResult.value.duration,
             });
-            // Step 1b: Build Hypergraph from index result (if code intelligence supports it)
-            const codeIntelForHypergraph = this.kernel.getDomainAPI('code-intelligence');
-            if (codeIntelForHypergraph?.buildHypergraphFromIndex) {
-                try {
-                    await codeIntelForHypergraph.buildHypergraphFromIndex(indexResult.value);
-                }
-                catch (hypergraphError) {
-                    // Non-fatal: hypergraph is supplementary to the core indexing pipeline
-                    console.warn('[CodeIndexProtocol] Hypergraph build failed (continuing):', hypergraphError);
-                }
-            }
+            // Note: Hypergraph is now rebuilt automatically inside coordinator.index()
+            // (no separate buildHypergraphFromIndex call needed here)
             // Step 2: Analyze Impact (if enabled and relevant trigger)
             let impactAnalysis;
             if (this.config.analyzeImpact && this.shouldAnalyzeImpact(trigger)) {

package/dist/domains/code-intelligence/coordinator-hypergraph.js

@@ -20,7 +20,7 @@ export async function initializeHypergraph(hypergraphDbPath, enableGNN) {
     const path = await import('path');
     const { findProjectRoot } = await import('../../kernel/unified-memory.js');
     const projectRoot = findProjectRoot();
-    const dbPath = hypergraphDbPath || path.join(projectRoot, '.agentic-qe', 'hypergraph.db');
+    const dbPath = hypergraphDbPath || path.join(projectRoot, '.agentic-qe', 'memory.db');
     const dir = path.dirname(dbPath);
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });

package/dist/domains/code-intelligence/coordinator.d.ts

@@ -318,6 +318,11 @@ export declare class CodeIntelligenceCoordinator extends BaseDomainCoordinator<C
      * test discovery with the existing impact analysis.
      */
     private enhanceImpactWithHypergraph;
+    /**
+     * Build a CodeIndexResult from file paths using shared lightweight regex extraction.
+     * Used to keep hypergraph in sync when index() is called.
+     */
+    private buildCodeIndexResultFromPaths;
     /**
      * Verify a code pattern detection using multi-model consensus
      * Per MM-001: High-stakes code intelligence decisions require verification

package/dist/domains/code-intelligence/coordinator.js

@@ -133,7 +133,7 @@ export class CodeIntelligenceCoordinator extends BaseDomainCoordinator {
             const path = await import('path');
             const { findProjectRoot } = await import('../../kernel/unified-memory.js');
             const projectRoot = findProjectRoot();
-            const dbPath = this.config.hypergraphDbPath || path.join(projectRoot, '.agentic-qe', 'hypergraph.db');
+            const dbPath = this.config.hypergraphDbPath || path.join(projectRoot, '.agentic-qe', 'memory.db');
             // Ensure directory exists
             const dir = path.dirname(dbPath);
             if (!fs.existsSync(dir)) {
@@ -151,10 +151,16 @@ export class CodeIntelligenceCoordinator extends BaseDomainCoordinator {
             logger.info(`Hypergraph Engine initialized at ${dbPath}`);
         }
         catch (error) {
-            logger.error('Failed to initialize Hypergraph Engine:', error instanceof Error ? error : undefined);
+            const msg = error instanceof Error ? error.message : String(error);
+            logger.warn(`Hypergraph Engine initialization failed (feature degraded): ${msg}`);
             // Don't throw - hypergraph is optional, coordinator should still work
             this.hypergraph = undefined;
             this.hypergraphDb = undefined;
+            // Publish degradation event so health checks can surface it
+            if (this.config.publishEvents) {
+                const event = createEvent('code-intelligence.HypergraphDegraded', 'code-intelligence', { reason: msg });
+                this.eventBus.publish(event).catch(() => { });
+            }
         }
     }
     /**
@@ -289,11 +295,26 @@ export class CodeIntelligenceCoordinator extends BaseDomainCoordinator {
                         await this.collectProjectMetrics(projectPath);
                     }
                 }
-                this.updateWorkflowProgress(workflowId, 80);
+                this.updateWorkflowProgress(workflowId, 70);
                 // Index content for semantic search
                 if (request.paths.length > 0) {
                     await this.indexForSemanticSearch(request.paths);
                 }
+                this.updateWorkflowProgress(workflowId, 85);
+                // V3: Rebuild hypergraph from indexed files (keeps hypergraph in sync with KG)
+                if (this.config.enableHypergraph && this.hypergraph && request.paths.length > 0) {
+                    try {
+                        const codeIndexResult = await this.buildCodeIndexResultFromPaths(request.paths);
+                        if (codeIndexResult.files.length > 0) {
+                            await this.hypergraph.buildFromIndexResult(codeIndexResult);
+                            logger.info(`Hypergraph rebuilt from ${codeIndexResult.files.length} indexed files`);
+                        }
+                    }
+                    catch (hgError) {
+                        // Non-fatal: hypergraph is supplementary to the core indexing pipeline
+                        logger.warn(`Hypergraph rebuild skipped: ${hgError instanceof Error ? hgError.message : hgError}`);
+                    }
+                }
                 this.updateWorkflowProgress(workflowId, 100);
                 this.completeWorkflow(workflowId);
                 // Publish events
@@ -1005,6 +1026,17 @@ export class CodeIntelligenceCoordinator extends BaseDomainCoordinator {
         return HypergraphHelpers.enhanceImpactWithHypergraph(this.hypergraph, request, baseAnalysis);
     }
     // ============================================================================
+    // Hypergraph Helpers
+    // ============================================================================
+    /**
+     * Build a CodeIndexResult from file paths using shared lightweight regex extraction.
+     * Used to keep hypergraph in sync when index() is called.
+     */
+    async buildCodeIndexResultFromPaths(paths) {
+        const { extractCodeIndex } = await import('../../shared/code-index-extractor.js');
+        return extractCodeIndex(paths);
+    }
+    // ============================================================================
     // Domain-Specific Consensus Methods (MM-001)
     // ============================================================================
     /**

package/dist/init/phases/06-code-intelligence.d.ts

@@ -22,11 +22,11 @@ export declare class CodeIntelligencePhase extends BasePhase<CodeIntelligenceRes
     readonly requiresPhases: readonly ["database"];
     protected run(context: InitContext): Promise<CodeIntelligenceResult>;
     /**
-     * Check if code intelligence index exists
+     * Check if code intelligence index exists (uses provided db connection)
      */
     private checkCodeIntelligenceIndex;
     /**
-     * Get count of KG entries
+     * Get count of KG entries (uses provided db connection)
      */
     private getKGEntryCount;
     /**
@@ -41,7 +41,12 @@ export declare class CodeIntelligencePhase extends BasePhase<CodeIntelligenceRes
      */
     private runCodeIntelligenceScan;
     /**
-     * Read the indexedAt timestamp from KG metadata
+     * Build hypergraph from indexed files.
+     * Uses shared extractor to populate hypergraph_nodes/hypergraph_edges in memory.db.
+     */
+    private buildHypergraph;
+    /**
+     * Read the indexedAt timestamp from KG metadata (uses provided db connection)
      */
     private getLastIndexedAt;
     /**

package/dist/init/phases/06-code-intelligence.js

@@ -54,42 +54,55 @@ export class CodeIntelligencePhase extends BasePhase {
     requiresPhases = ['database'];
     async run(context) {
         const { projectRoot } = context;
-        const hasIndex = await this.checkCodeIntelligenceIndex(projectRoot);
-        if (!hasIndex) {
+        const dbPath = join(projectRoot, '.agentic-qe', 'memory.db');
+        if (!existsSync(dbPath)) {
             context.services.log('  Building knowledge graph...');
             return await this.runCodeIntelligenceScan(projectRoot, context, false);
         }
-        // Delta scan: check for files modified since last index
-        const lastIndexedAt = await this.getLastIndexedAt(projectRoot);
-        if (!lastIndexedAt) {
-            const entryCount = await this.getKGEntryCount(projectRoot);
-            context.services.log(`  Using existing index (${entryCount} entries)`);
-            return { status: 'existing', entries: entryCount };
+        // Open a single DB connection for all pre-scan queries
+        const db = openDatabase(dbPath);
+        try {
+            const hasIndex = this.checkCodeIntelligenceIndex(db);
+            if (!hasIndex) {
+                db.close();
+                context.services.log('  Building knowledge graph...');
+                return await this.runCodeIntelligenceScan(projectRoot, context, false);
+            }
+            // Delta scan: check for files modified since last index
+            const lastIndexedAt = this.getLastIndexedAt(db);
+            if (!lastIndexedAt) {
+                const entryCount = this.getKGEntryCount(db);
+                db.close();
+                context.services.log(`  Using existing index (${entryCount} entries)`);
+                return { status: 'existing', entries: entryCount };
+            }
+            const entryCount = this.getKGEntryCount(db);
+            db.close();
+            const changedFiles = await this.findChangedFiles(projectRoot, lastIndexedAt);
+            if (changedFiles.length === 0) {
+                context.services.log(`  Index up to date (${entryCount} entries)`);
+                return { status: 'existing', entries: entryCount };
+            }
+            context.services.log(`  Delta scan: ${changedFiles.length} files changed since last index...`);
+            return await this.runCodeIntelligenceScan(projectRoot, context, true, changedFiles);
         }
-        const changedFiles = await this.findChangedFiles(projectRoot, lastIndexedAt);
-        if (changedFiles.length === 0) {
-            const entryCount = await this.getKGEntryCount(projectRoot);
-            context.services.log(`  Index up to date (${entryCount} entries)`);
-            return { status: 'existing', entries: entryCount };
+        catch (error) {
+            try {
+                db.close();
+            }
+            catch { /* ignore */ }
+            throw error;
         }
-        context.services.log(`  Delta scan: ${changedFiles.length} files changed since last index...`);
-        return await this.runCodeIntelligenceScan(projectRoot, context, true, changedFiles);
     }
     /**
-     * Check if code intelligence index exists
+     * Check if code intelligence index exists (uses provided db connection)
      */
-    async checkCodeIntelligenceIndex(projectRoot) {
-        const dbPath = join(projectRoot, '.agentic-qe', 'memory.db');
-        if (!existsSync(dbPath)) {
-            return false;
-        }
+    checkCodeIntelligenceIndex(db) {
         try {
-            const db = openDatabase(dbPath);
             const result = db.prepare(`
         SELECT COUNT(*) as count FROM kv_store
         WHERE namespace = 'code-intelligence:kg'
       `).get();
-            db.close();
             return result.count > 0;
         }
         catch {
@@ -97,17 +110,14 @@ export class CodeIntelligencePhase extends BasePhase {
         }
     }
     /**
-     * Get count of KG entries
+     * Get count of KG entries (uses provided db connection)
      */
-    async getKGEntryCount(projectRoot) {
-        const dbPath = join(projectRoot, '.agentic-qe', 'memory.db');
+    getKGEntryCount(db) {
         try {
-            const db = openDatabase(dbPath);
             const result = db.prepare(`
         SELECT COUNT(*) as count FROM kv_store
         WHERE namespace LIKE 'code-intelligence:kg%'
       `).get();
-            db.close();
             return result.count;
         }
         catch {
@@ -165,6 +175,9 @@ export class CodeIntelligencePhase extends BasePhase {
                 const entries = result.value.nodesCreated + result.value.edgesCreated;
                 const label = incremental ? 'Delta indexed' : 'Indexed';
                 context.services.log(`  ${label} ${entries} entries to ${dbPath}`);
+                // Also populate the hypergraph tables (hypergraph_nodes/hypergraph_edges)
+                // so CLI/MCP hypergraph queries work immediately after init
+                await this.buildHypergraph(dbPath, filesToIndex, context);
                 return { status: 'indexed', entries };
             }
             return { status: 'error', entries: 0 };
@@ -175,18 +188,43 @@ export class CodeIntelligencePhase extends BasePhase {
         }
     }
     /**
-     * Read the indexedAt timestamp from KG metadata
+     * Build hypergraph from indexed files.
+     * Uses shared extractor to populate hypergraph_nodes/hypergraph_edges in memory.db.
      */
-    async getLastIndexedAt(projectRoot) {
-        const dbPath = join(projectRoot, '.agentic-qe', 'memory.db');
+    async buildHypergraph(dbPath, filesToIndex, context) {
         try {
+            const { extractCodeIndex } = await import('../../shared/code-index-extractor.js');
+            const { createHypergraphEngine } = await import('../../integrations/ruvector/hypergraph-engine.js');
             const db = openDatabase(dbPath);
+            const engine = await createHypergraphEngine({
+                db,
+                maxTraversalDepth: 10,
+                maxQueryResults: 1000,
+                enableVectorSearch: false,
+            });
+            const codeIndexResult = await extractCodeIndex(filesToIndex);
+            const buildResult = await engine.buildFromIndexResult(codeIndexResult);
+            db.close();
+            const total = buildResult.nodesCreated + buildResult.edgesCreated;
+            if (total > 0) {
+                context.services.log(`  Hypergraph: ${buildResult.nodesCreated} nodes, ${buildResult.edgesCreated} edges`);
+            }
+        }
+        catch (error) {
+            // Non-fatal: hypergraph is supplementary
+            context.services.warn?.(`  Hypergraph build skipped: ${error}`);
+        }
+    }
+    /**
+     * Read the indexedAt timestamp from KG metadata (uses provided db connection)
+     */
+    getLastIndexedAt(db) {
+        try {
             const row = db.prepare(`
         SELECT value FROM kv_store
         WHERE namespace = 'code-intelligence:kg'
           AND key = 'metadata:index'
       `).get();
-            db.close();
             if (!row)
                 return null;
             const metadata = safeJsonParse(row.value);

package/dist/init/phases/08-mcp.js

@@ -26,6 +26,16 @@ export class MCPPhase extends BasePhase {
     requiresPhases = ['configuration', 'database'];
     async run(context) {
         const { projectRoot } = context;
+        // MCP is opt-in: skip unless --with-mcp is passed
+        if (!context.options.withMcp) {
+            context.services.log('  MCP: skipped (opt-in — use --with-mcp to enable)');
+            context.services.log('  All QE commands available via CLI: aqe memory, aqe test, aqe coverage, etc.');
+            return {
+                configured: false,
+                mcpPath: '',
+                serverName: '',
+            };
+        }
         // AQE MCP server configuration
         // AQE_PROJECT_ROOT omitted — runtime discovery via findProjectRoot() is
         // portable across machines, devcontainers, and CI (#321)