@yasserkhanorg/impact-gate 2.0.0

package/dist/esm/base_provider.js

@@ -0,0 +1,198 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { withRetry } from './resilience/retry.js';
+import { CircuitBreaker } from './resilience/circuit_breaker.js';
+/**
+ * Abstract base class for all LLM providers
+ * Eliminates 240+ lines of duplicate stats management code
+ * Provides common functionality for token tracking, cost calculation, and stats management
+ */
+export class BudgetExceededError extends Error {
+    constructor(currentCost, budgetUSD) {
+        super(`Budget exceeded: $${currentCost.toFixed(4)} >= $${budgetUSD} limit`);
+        this.currentCost = currentCost;
+        this.budgetUSD = budgetUSD;
+        this.name = 'BudgetExceededError';
+    }
+}
+export class BaseProvider {
+    constructor() {
+        /** Tracks the current in-flight budget reservation for this provider instance. */
+        this._activeReservation = 0;
+        this.initializeStats();
+    }
+    /** Lazily get-or-create a circuit breaker shared across all instances of this provider type. */
+    get circuitBreaker() {
+        let cb = BaseProvider._sharedBreakers.get(this.name);
+        if (!cb) {
+            cb = new CircuitBreaker({
+                shouldCount: (error) => {
+                    if (error instanceof BudgetExceededError)
+                        return false;
+                    if (!(error instanceof Error))
+                        return true;
+                    const msg = error.message.toLowerCase();
+                    return msg.includes('429') || msg.includes('rate limit') ||
+                        msg.includes('500') || msg.includes('502') || msg.includes('503') || msg.includes('504') ||
+                        msg.includes('econnreset') || msg.includes('econnrefused') || msg.includes('etimedout') ||
+                        msg.includes('overloaded') || msg.includes('socket hang up') || msg.includes('network error');
+                },
+            });
+            BaseProvider._sharedBreakers.set(this.name, cb);
+        }
+        return cb;
+    }
+    /**
+     * Set a hard budget limit. Once totalCost reaches this value,
+     * subsequent calls will throw BudgetExceededError.
+     */
+    setBudget(usd) {
+        this._budgetUSD = usd;
+    }
+    get budgetUSD() {
+        return this._budgetUSD;
+    }
+    /**
+     * Attach a shared budget ledger so aggregate cost across all providers
+     * in a crew run is checked before each LLM call.
+     */
+    setBudgetLedger(ledger) {
+        this._ledger = ledger;
+    }
+    /**
+     * Check budget and pre-reserve estimated cost for the upcoming LLM call.
+     *
+     * When a shared ledger exists, reserves an estimate derived from the provider's
+     * output token cost × maxTokens (default 4096). This blocks parallel agents from
+     * spending into the same headroom — like a credit card authorization hold.
+     *
+     * Self-healing: if a prior call failed without reaching updateStats(), the stale
+     * reservation is released here before placing the new one.
+     */
+    checkBudget() {
+        if (this._ledger) {
+            // Release stale reservation from a prior failed call that never hit updateStats
+            if (this._activeReservation > 0) {
+                this._ledger.release(this._activeReservation);
+                this._activeReservation = 0;
+            }
+            // Reserve estimated cost for the upcoming call
+            const estimate = this.estimateCallCost();
+            this._ledger.reserve(estimate);
+            this._activeReservation = estimate;
+            try {
+                this._ledger.check();
+            }
+            catch (err) {
+                // Budget exceeded — release reservation immediately so it doesn't leak
+                this._ledger.release(estimate);
+                this._activeReservation = 0;
+                throw err;
+            }
+            return;
+        }
+        if (this._budgetUSD !== undefined && this.stats.totalCost >= this._budgetUSD) {
+            throw new BudgetExceededError(this.stats.totalCost, this._budgetUSD);
+        }
+    }
+    /**
+     * Conservative cost estimate for the upcoming call.
+     * Uses maxTokens (or 4096 default) × output cost rate.
+     * Overestimating is safe — the reservation is replaced with actual cost in updateStats.
+     */
+    estimateCallCost() {
+        const outputTokenEstimate = 4096;
+        const costRate = this.capabilities?.costPer1MOutputTokens ?? 15; // default to ~Sonnet
+        return (outputTokenEstimate / 1000000) * costRate;
+    }
+    /**
+     * Initialize stats object with default values
+     */
+    initializeStats() {
+        this.stats = {
+            requestCount: 0,
+            totalInputTokens: 0,
+            totalOutputTokens: 0,
+            totalTokens: 0,
+            totalCost: 0,
+            averageResponseTimeMs: 0,
+            failedRequests: 0,
+            startTime: new Date(),
+            lastUpdated: new Date(),
+        };
+    }
+    /**
+     * Update stats with new usage data
+     * Maintains rolling average for response time
+     */
+    updateStats(usage, responseTime, cost) {
+        this.stats.requestCount++;
+        this.stats.totalInputTokens += usage.inputTokens;
+        this.stats.totalOutputTokens += usage.outputTokens;
+        this.stats.totalTokens += usage.totalTokens;
+        this.stats.totalCost += cost;
+        if (this._ledger) {
+            // Settle: release the estimate, record actual
+            if (this._activeReservation > 0) {
+                this._ledger.release(this._activeReservation);
+                this._activeReservation = 0;
+            }
+            this._ledger.record(cost);
+        }
+        // Update rolling average response time
+        const totalRequests = this.stats.requestCount;
+        this.stats.averageResponseTimeMs =
+            (this.stats.averageResponseTimeMs * (totalRequests - 1) + responseTime) / totalRequests;
+        this.stats.lastUpdated = new Date();
+    }
+    /**
+     * Get a copy of current usage stats
+     */
+    getUsageStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Reset all usage stats to initial state
+     */
+    resetUsageStats() {
+        this.initializeStats();
+    }
+    /**
+     * Wrap an async call with circuit breaker + retry logic.
+     * Circuit breaker protects against cascading failures from a down provider;
+     * retry handles transient failures within a healthy circuit.
+     *
+     * Non-transient errors (budget, auth, validation) are thrown directly and
+     * bypass the circuit breaker so they don't incorrectly trip it.
+     */
+    retryCall(fn) {
+        return this.circuitBreaker.call(() => withRetry(fn, { maxRetries: 2, baseDelayMs: 1000, maxDelayMs: 10000, jitter: true }), () => { throw new Error(`${this.name} provider circuit open — too many consecutive failures`); });
+    }
+    /**
+     * Calculate cost for token usage, accounting for prompt caching discounts
+     * Cached tokens cost 90% less than regular tokens
+     */
+    calculateCost(usage, costPer1MInputTokens, costPer1MOutputTokens) {
+        // Calculate input token cost
+        let inputCost = 0;
+        // Cached tokens cost 90% less
+        if (usage.cachedTokens) {
+            const cachedCost = (usage.cachedTokens / 1000000) * (costPer1MInputTokens * 0.1);
+            const uncachedInputTokens = usage.inputTokens - usage.cachedTokens;
+            const uncachedCost = (uncachedInputTokens / 1000000) * costPer1MInputTokens;
+            inputCost = cachedCost + uncachedCost;
+        }
+        else {
+            inputCost = (usage.inputTokens / 1000000) * costPer1MInputTokens;
+        }
+        // Calculate output token cost
+        const outputCost = (usage.outputTokens / 1000000) * costPer1MOutputTokens;
+        return inputCost + outputCost;
+    }
+}
+/**
+ * Shared circuit breakers keyed by provider name (e.g., "anthropic", "openai").
+ * All instances of the same provider type share one breaker, so if Anthropic is
+ * down, ALL agents discover it after 3 total failures instead of 3 × N.
+ */
+BaseProvider._sharedBreakers = new Map();

package/dist/esm/budget_ledger.js

@@ -0,0 +1,58 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * Shared budget ledger — tracks aggregate cost across all provider instances
+ * in a single crew run. Prevents parallel agents from each seeing only 1/N
+ * of actual spend and overshooting the budget by N×limit.
+ *
+ * Usage: create one BudgetLedger per crew run, pass it to getCrewProvider(),
+ * which attaches it to each provider via setBudgetLedger().
+ */
+import { BudgetExceededError } from './base_provider.js';
+export class BudgetLedger {
+    constructor(limitUSD) {
+        this._totalCost = 0;
+        this._reserved = 0;
+        this._limitUSD = limitUSD;
+    }
+    get totalCost() {
+        return this._totalCost;
+    }
+    get limitUSD() {
+        return this._limitUSD;
+    }
+    /**
+     * Record actual cost from a completed LLM call.
+     */
+    record(cost) {
+        if (!Number.isFinite(cost) || cost < 0)
+            return;
+        this._totalCost += cost;
+    }
+    /**
+     * Pre-reserve estimated cost before an LLM call begins.
+     * Blocks parallel agents from spending into the same headroom.
+     * Like a credit card authorization hold.
+     */
+    reserve(estimate) {
+        if (!Number.isFinite(estimate) || estimate <= 0)
+            return;
+        this._reserved += estimate;
+    }
+    /**
+     * Release a prior reservation (after API response or on error).
+     */
+    release(estimate) {
+        this._reserved = Math.max(0, this._reserved - estimate);
+    }
+    /**
+     * Throws BudgetExceededError if committed cost + in-flight reservations
+     * have reached the limit.
+     */
+    check() {
+        const effective = this._totalCost + this._reserved;
+        if (effective >= this._limitUSD) {
+            throw new BudgetExceededError(effective, this._limitUSD);
+        }
+    }
+}

package/dist/esm/cache/cached_provider.js

@@ -0,0 +1,85 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { ResponseCache, TTL } from './response_cache.js';
+/**
+ * Decorator that adds transparent response caching to any LLMProvider.
+ *
+ * - `generateText()` checks the cache first and returns a cached response on hit.
+ *   On a miss it delegates to the inner provider, stores the result, and returns it.
+ * - All other methods (analyzeImage, streamText, capabilities, usage stats)
+ *   delegate directly to the wrapped provider.
+ *
+ * The TTL is selected based on the agent role: agents whose name contains
+ * "generat" use the shorter GENERATION TTL; all others use ANALYSIS.
+ */
+export class CachedProvider {
+    constructor(inner, cache, cacheContext) {
+        this.inner = inner;
+        this.cache = cache;
+        this.ctx = cacheContext;
+        this.name = inner.name;
+        this.capabilities = inner.capabilities;
+        // Pick TTL based on agent role
+        this.ttlMs = cacheContext.agent.toLowerCase().includes('generat')
+            ? TTL.GENERATION
+            : TTL.ANALYSIS;
+        // Wire optional methods only when the inner provider supports them
+        if (inner.analyzeImage) {
+            this.analyzeImage = (images, prompt, options) => inner.analyzeImage(images, prompt, options);
+        }
+        if (inner.streamText) {
+            this.streamText = (prompt, options) => inner.streamText(prompt, options);
+        }
+    }
+    /**
+     * Generate text with cache-through semantics.
+     * On a cache hit the inner provider is never called, saving tokens and latency.
+     */
+    async generateText(prompt, options) {
+        const { agent, family, fileHashes } = this.ctx;
+        const model = this.inner.name;
+        // Check cache
+        const cached = this.cache.get(agent, family, fileHashes, model);
+        if (cached) {
+            return {
+                text: cached.response,
+                usage: {
+                    inputTokens: cached.usage.inputTokens,
+                    outputTokens: cached.usage.outputTokens,
+                    totalTokens: cached.usage.inputTokens + cached.usage.outputTokens,
+                    cachedTokens: cached.usage.inputTokens,
+                },
+                cost: 0, // No cost on cache hit
+            };
+        }
+        // Cache miss - call inner provider
+        const response = await this.inner.generateText(prompt, options);
+        // Store in cache
+        const key = ResponseCache.buildKey({ agent, family, fileHashes, model });
+        const entry = {
+            key,
+            family,
+            response: response.text,
+            usage: {
+                inputTokens: response.usage.inputTokens,
+                outputTokens: response.usage.outputTokens,
+                cost: response.cost,
+            },
+            createdAt: new Date().toISOString(),
+            ttlMs: this.ttlMs,
+        };
+        this.cache.set(entry);
+        return response;
+    }
+    getUsageStats() {
+        return this.inner.getUsageStats();
+    }
+    resetUsageStats() {
+        this.inner.resetUsageStats();
+    }
+    async checkHealth() {
+        return this.inner.checkHealth();
+    }
+}
+// Re-export for convenience
+export { ResponseCache, TTL } from './response_cache.js';

package/dist/esm/cache/response_cache.js

@@ -0,0 +1,140 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+/**
+ * TTL presets for different cache entry types.
+ */
+export const TTL = {
+    /** 24 hours - for analysis results that change infrequently */
+    ANALYSIS: 24 * 60 * 60 * 1000,
+    /** 1 hour - for generated content that may need fresher context */
+    GENERATION: 1 * 60 * 60 * 1000,
+};
+/**
+ * Cross-run LLM response cache backed by JSON files.
+ *
+ * Stores entries as `{cacheDir}/{sha256}.json` using a content-addressed key
+ * derived from (agentRole + familyName + sorted file hashes + model).
+ */
+export class ResponseCache {
+    constructor(workspaceRoot) {
+        this.cacheDir = path.join(workspaceRoot, '.e2e-ai-agents', 'cache');
+    }
+    /**
+     * Build a deterministic SHA-256 cache key from the provided parameters.
+     */
+    static buildKey(params) {
+        const sorted = [...params.fileHashes].sort();
+        const payload = params.agent + params.family + JSON.stringify(sorted) + params.model;
+        return crypto.createHash('sha256').update(payload).digest('hex');
+    }
+    /**
+     * Retrieve a cached response if it exists and has not expired.
+     * Returns `null` on cache miss or expiry.
+     */
+    get(agent, family, fileHashes, model) {
+        const key = ResponseCache.buildKey({ agent, family, fileHashes, model });
+        const filePath = path.join(this.cacheDir, `${key}.json`);
+        try {
+            if (!fs.existsSync(filePath)) {
+                return null;
+            }
+            const raw = fs.readFileSync(filePath, 'utf-8');
+            const entry = JSON.parse(raw);
+            const age = Date.now() - new Date(entry.createdAt).getTime();
+            if (age > entry.ttlMs) {
+                // Expired - clean up eagerly
+                fs.unlinkSync(filePath);
+                return null;
+            }
+            return entry;
+        }
+        catch {
+            // Corrupted or unreadable - treat as miss
+            return null;
+        }
+    }
+    /**
+     * Write a cache entry to disk.
+     * Creates the cache directory if it does not yet exist.
+     */
+    set(entry) {
+        this.ensureCacheDir();
+        const filePath = path.join(this.cacheDir, `${entry.key}.json`);
+        fs.writeFileSync(filePath, JSON.stringify(entry, null, 2), 'utf-8');
+    }
+    /**
+     * Remove all cache entries belonging to the given family.
+     *
+     * Because the cache key is a one-way SHA-256 hash, we scan each file and
+     * check its stored `family` field. The directory is scoped to a single
+     * workspace so the scan is bounded.
+     */
+    invalidateFamily(familyName) {
+        if (!fs.existsSync(this.cacheDir)) {
+            return 0;
+        }
+        let deleted = 0;
+        const files = fs.readdirSync(this.cacheDir).filter((f) => f.endsWith('.json'));
+        for (const file of files) {
+            const filePath = path.join(this.cacheDir, file);
+            try {
+                const raw = fs.readFileSync(filePath, 'utf-8');
+                const entry = JSON.parse(raw);
+                if (entry.family === familyName) {
+                    fs.unlinkSync(filePath);
+                    deleted++;
+                }
+            }
+            catch {
+                // Skip unreadable files
+            }
+        }
+        return deleted;
+    }
+    /**
+     * Remove all expired entries from the cache directory.
+     * Returns the number of entries deleted.
+     */
+    prune() {
+        if (!fs.existsSync(this.cacheDir)) {
+            return 0;
+        }
+        let deleted = 0;
+        const now = Date.now();
+        const files = fs.readdirSync(this.cacheDir).filter((f) => f.endsWith('.json'));
+        for (const file of files) {
+            const filePath = path.join(this.cacheDir, file);
+            try {
+                const raw = fs.readFileSync(filePath, 'utf-8');
+                const entry = JSON.parse(raw);
+                const age = now - new Date(entry.createdAt).getTime();
+                if (age > entry.ttlMs) {
+                    fs.unlinkSync(filePath);
+                    deleted++;
+                }
+            }
+            catch {
+                // Corrupted file - remove it
+                try {
+                    fs.unlinkSync(filePath);
+                    deleted++;
+                }
+                catch {
+                    // Ignore if removal also fails
+                }
+            }
+        }
+        return deleted;
+    }
+    /**
+     * Ensure the cache directory exists on disk.
+     */
+    ensureCacheDir() {
+        if (!fs.existsSync(this.cacheDir)) {
+            fs.mkdirSync(this.cacheDir, { recursive: true });
+        }
+    }
+}

package/dist/esm/cli/commands/analyze.js

@@ -0,0 +1,74 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { resolveConfig } from '../../agent/config.js';
+import { runPipeline } from '../../pipeline/orchestrator.js';
+export async function runAnalyzeCommand(args, autoConfig) {
+    if (!args.path && !autoConfig) {
+        console.error('Error: --path is required for analyze command');
+        process.exit(1);
+    }
+    const { config } = resolveConfig(process.cwd(), autoConfig, {
+        path: args.path,
+        profile: args.profile,
+        testsRoot: args.testsRoot,
+        mode: 'impact',
+        gitSince: args.gitSince,
+        llmProvider: args.llmProvider,
+    });
+    const testsRoot = config.testsRoot || config.path;
+    const analyzeStages = [
+        'preprocess', 'impact', 'coverage',
+    ];
+    if (args.analyzeGenerate) {
+        analyzeStages.push('generation');
+    }
+    if (args.analyzeHeal || args.analyzeHealReport) {
+        analyzeStages.push('heal');
+    }
+    const result = await runPipeline({
+        appPath: config.path,
+        testsRoot,
+        gitSince: args.gitSince || config.git.since,
+        routeFamilies: config.routeFamilies,
+        apiSurface: config.apiSurface,
+        stages: analyzeStages,
+        generation: args.analyzeGenerate
+            ? {
+                defaultOutputDir: args.analyzeGenerateOutputDir || 'specs/functional/ai-assisted',
+                dryRun: args.dryRun,
+            }
+            : undefined,
+        heal: (args.analyzeHeal || args.analyzeHealReport)
+            ? {
+                mcp: args.pipelineMcp ?? true,
+                mcpAllowFallback: args.pipelineMcpAllowFallback ?? false,
+                mcpOnly: args.pipelineMcpOnly ?? false,
+                mcpCommandTimeoutMs: args.pipelineMcpTimeoutMs,
+                mcpRetries: args.pipelineMcpRetries ?? 1,
+                dryRun: args.dryRun,
+            }
+            : undefined,
+        playwrightReportPath: args.analyzeHealReport,
+    });
+    console.log(`Analyze report: ${result.reportPath}`);
+    console.log(`Analyze flows identified: ${result.report.summary.flowsIdentified}`);
+    console.log(`Analyze flows covered: ${result.report.summary.flowsCovered}`);
+    console.log(`Analyze flows uncovered: ${result.report.summary.flowsUncovered}`);
+    console.log(`Analyze overall confidence: ${result.report.summary.overallConfidence}`);
+    console.log(`Analyze route families: ${result.report.summary.routeFamiliesImpacted.join(', ') || 'none'}`);
+    if (result.generated && result.generated.length > 0) {
+        const written = result.generated.filter((g) => g.written).length;
+        console.log(`Analyze generated specs: ${result.generated.length} (written=${written})`);
+        for (const g of result.generated) {
+            console.log(`  ${g.mode}: ${g.specPath}`);
+        }
+    }
+    if (result.healResult) {
+        const healed = result.healResult.summary.results.filter((r) => r.healStatus === 'success').length;
+        const healFailed = result.healResult.summary.results.filter((r) => r.healStatus === 'failed').length;
+        console.log(`Analyze heal targets: ${result.healResult.targets.length} (healed=${healed}, failed=${healFailed})`);
+    }
+    if (result.warnings.length > 0) {
+        console.log(`Analyze warnings: ${result.warnings.join(' | ')}`);
+    }
+}

package/dist/esm/cli/commands/bootstrap.js

@@ -0,0 +1,106 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * Bootstrap command — takes a project with an Understand-Anything knowledge graph
+ * and generates route-families.json + initial test stubs.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { logger, LogLevel } from '../../logger.js';
+import { loadKnowledgeGraph, classifyProjectType, transformKGToFamilies } from '../../knowledge/kg_bridge.js';
+import { serializeManifest } from '../../knowledge/route_families.js';
+import { detectFramework, detectTestMode } from '../../adapters/framework_adapter.js';
+import { resolveGenerationProfile } from '../../prompts/generation_profile.js';
+class BootstrapError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BootstrapError';
+    }
+}
+export async function runBootstrapCommand(args) {
+    const projectRoot = resolve(args.path || '.');
+    if (args.verbose)
+        logger.setLevel(LogLevel.DEBUG);
+    if (args.jsonOutput)
+        logger.setJsonMode(true);
+    logger.info('impact-gate bootstrap');
+    logger.info('=======================');
+    // ---------- Step 1: Check for knowledge graph ----------
+    const kgPath = args.bootstrapKgPath
+        ? resolve(args.bootstrapKgPath)
+        : join(projectRoot, '.understand-anything', 'knowledge-graph.json');
+    if (!existsSync(kgPath)) {
+        throw new BootstrapError(`Knowledge graph not found at: ${kgPath}\n\n` +
+            'To bootstrap, first generate a knowledge graph for your project:\n' +
+            '  1. Install Understand-Anything: npm install -g understand-anything\n' +
+            '  2. Run: understand-anything analyze .\n' +
+            '  3. Then run: impact-gate bootstrap\n\n' +
+            'Or provide a path: impact-gate bootstrap --kg-path /path/to/knowledge-graph.json');
+    }
+    // ---------- Step 2: Load KG and classify ----------
+    logger.info('Loading knowledge graph...');
+    const kg = loadKnowledgeGraph(projectRoot, args.bootstrapKgPath ? kgPath : undefined);
+    if (!kg) {
+        throw new BootstrapError('Failed to load knowledge graph. Ensure it is valid JSON with nodes and edges arrays.');
+    }
+    const projectType = classifyProjectType(kg);
+    logger.info(`Project: ${kg.project.name || '(unnamed)'}`);
+    logger.info(`Type: ${projectType}`);
+    logger.info(`Frameworks: ${kg.project.frameworks.join(', ')}`);
+    logger.info(`Languages: ${kg.project.languages.join(', ')}`);
+    logger.info(`Nodes: ${kg.nodes.length}, Edges: ${kg.edges.length}`);
+    // ---------- Step 3: Transform KG to route families ----------
+    logger.info('');
+    logger.info('Generating route families from knowledge graph...');
+    const manifest = transformKGToFamilies(kg);
+    const maxFamilies = args.bootstrapMaxFamilies || 50;
+    if (manifest.families.length > maxFamilies) {
+        logger.info(`Limiting to top ${maxFamilies} families (of ${manifest.families.length} discovered). Use --max-families to adjust.`);
+        manifest.families = manifest.families.slice(0, maxFamilies);
+    }
+    const p0Count = manifest.families.filter((f) => f.priority === 'P0').length;
+    const p1Count = manifest.families.filter((f) => f.priority === 'P1').length;
+    const p2Count = manifest.families.filter((f) => f.priority === 'P2').length;
+    logger.info(`Discovered ${manifest.families.length} families: ${p0Count} P0, ${p1Count} P1, ${p2Count} P2`);
+    // ---------- Step 4: Detect/scaffold test framework ----------
+    const framework = detectFramework(projectRoot);
+    const testMode = args.bootstrapTestMode || detectTestMode(projectRoot, kg);
+    const profile = resolveGenerationProfile({ profile: args.profile, testMode }, kg);
+    logger.info(`Test framework: ${framework.name}`);
+    logger.info(`Test mode: ${testMode}`);
+    logger.info(`Generation profile: ${profile.projectName} (${profile.testFramework})`);
+    // ---------- Step 5: Write route-families.json ----------
+    const outputDir = join(projectRoot, '.e2e-ai-agents');
+    const outputPath = join(outputDir, 'route-families.json');
+    if (args.dryRun) {
+        logger.info('');
+        logger.info('Dry run — proposed manifest:');
+        console.log(serializeManifest(manifest));
+    }
+    else {
+        if (!existsSync(outputDir)) {
+            mkdirSync(outputDir, { recursive: true });
+        }
+        writeFileSync(outputPath, serializeManifest(manifest), 'utf-8');
+        logger.info(`Wrote ${outputPath}`);
+    }
+    // ---------- Step 6: Summary and next steps ----------
+    logger.info('');
+    logger.info('Bootstrap complete!');
+    logger.info('');
+    logger.info('Route families summary:');
+    for (const family of manifest.families.slice(0, 15)) {
+        const endpoints = family.apiEndpoints?.length || 0;
+        const endpointSuffix = endpoints > 0 ? ` (${endpoints} API endpoints)` : '';
+        logger.info(`  ${family.priority || 'P2'} ${family.id}: ${family.routes.join(', ')}${endpointSuffix}`);
+    }
+    if (manifest.families.length > 15) {
+        logger.info(`  ... and ${manifest.families.length - 15} more`);
+    }
+    logger.info('');
+    logger.info('Next steps:');
+    logger.info('  1. Review and refine .e2e-ai-agents/route-families.json');
+    logger.info('  2. Run `impact-gate train --enrich` to add LLM-enriched metadata');
+    logger.info('  3. Run `impact-gate plan` to see what tests are needed');
+    logger.info('  4. Run `impact-gate generate` to create test stubs');
+}