@yasserkhanorg/impact-gate 2.0.0

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

@@ -0,0 +1,112 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * CLI command: cost-report — displays LLM cost breakdown from metrics.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+function parseMetricsFile(filePath) {
+    if (!existsSync(filePath)) {
+        return [];
+    }
+    const lines = readFileSync(filePath, 'utf-8').split('\n');
+    const events = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed.type === 'crew-run') {
+                events.push(parsed);
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return events;
+}
+function filterByDays(events, days) {
+    const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+    return events.filter((e) => new Date(e.timestamp).getTime() >= cutoff);
+}
+export function runCostReportCommand(args) {
+    const reportRoot = args.path || args.testsRoot || process.cwd();
+    const metricsPath = join(reportRoot, '.e2e-ai-agents', 'metrics.jsonl');
+    const days = 30; // Default; could be added as a CLI flag later
+    const allEvents = parseMetricsFile(metricsPath);
+    const events = filterByDays(allEvents, days);
+    if (events.length === 0) {
+        console.log('No crew metrics found.');
+        if (!existsSync(metricsPath)) {
+            console.log(`Metrics file not found at: ${metricsPath}`);
+        }
+        else {
+            console.log('Run `impact-gate crew` to generate cost data.');
+        }
+        return;
+    }
+    // JSON output
+    if (args.jsonOutput) {
+        const report = buildReport(events, days);
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    // Human-readable output
+    const totalCost = events.reduce((sum, e) => sum + e.totalCost, 0);
+    const totalRuns = events.length;
+    console.log(`Impact Gate Cost Report (last ${days} days)`);
+    console.log('='.repeat(45));
+    console.log(`\nTotal: $${totalCost.toFixed(2)} across ${totalRuns} runs\n`);
+    // By workflow
+    const byWorkflow = new Map();
+    for (const e of events) {
+        const entry = byWorkflow.get(e.workflow) || { runs: 0, cost: 0 };
+        entry.runs++;
+        entry.cost += e.totalCost;
+        byWorkflow.set(e.workflow, entry);
+    }
+    console.log('By workflow:');
+    for (const [workflow, data] of [...byWorkflow.entries()].sort((a, b) => b[1].cost - a[1].cost)) {
+        const avg = data.cost / data.runs;
+        console.log(`  ${workflow.padEnd(14)} | ${String(data.runs).padStart(3)} runs | $${data.cost.toFixed(2).padStart(6)} | avg $${avg.toFixed(2)}/run`);
+    }
+    // By agent (top 5)
+    const byAgent = new Map();
+    for (const e of events) {
+        for (const au of e.agentUsage) {
+            byAgent.set(au.agent, (byAgent.get(au.agent) || 0) + au.cost);
+        }
+    }
+    const sortedAgents = [...byAgent.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5);
+    if (sortedAgents.length > 0) {
+        console.log('\nBy agent (top 5):');
+        for (const [agent, cost] of sortedAgents) {
+            const pct = totalCost > 0 ? ((cost / totalCost) * 100).toFixed(0) : '0';
+            console.log(`  ${agent.padEnd(20)} | $${cost.toFixed(2).padStart(6)} | ${pct.padStart(3)}%`);
+        }
+    }
+}
+function buildReport(events, days) {
+    const totalCost = events.reduce((sum, e) => sum + e.totalCost, 0);
+    const byWorkflow = {};
+    const byAgent = {};
+    for (const e of events) {
+        if (!byWorkflow[e.workflow]) {
+            byWorkflow[e.workflow] = { runs: 0, cost: 0 };
+        }
+        byWorkflow[e.workflow].runs++;
+        byWorkflow[e.workflow].cost += e.totalCost;
+        for (const au of e.agentUsage) {
+            byAgent[au.agent] = (byAgent[au.agent] || 0) + au.cost;
+        }
+    }
+    return {
+        days,
+        totalRuns: events.length,
+        totalCost,
+        byWorkflow,
+        byAgent,
+    };
+}

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

@@ -0,0 +1,252 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * CLI command: crew — runs multi-agent QA analysis workflows.
+ */
+import { appendFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { resolveConfig } from '../../agent/config.js';
+import { CrewOrchestrator } from '../../crew/orchestrator.js';
+import { ResponseCache } from '../../cache/response_cache.js';
+import { WORKFLOWS } from '../../crew/workflows.js';
+import { ImpactAnalystAgent } from '../../agents/impact-analyst.js';
+import { GeneratorAgent } from '../../agents/generator.js';
+import { ExecutorAgent } from '../../agents/executor.js';
+import { HealerAgent } from '../../agents/healer.js';
+import { StrategistAgent } from '../../agents/strategist.js';
+import { TestDesignerAgent } from '../../agents/test-designer.js';
+import { CrossImpactAgent } from '../../agents/cross-impact.js';
+import { RegressionAdvisorAgent } from '../../agents/regression-advisor.js';
+const VALID_WORKFLOWS = ['full-qa', 'quick-check', 'design-only'];
+export async function runCrewCommand(args, autoConfig) {
+    if (!args.path && !autoConfig) {
+        console.error('Error: --path is required for crew 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 rawWorkflow = args.crewWorkflow || 'full-qa';
+    if (!VALID_WORKFLOWS.includes(rawWorkflow)) {
+        console.error(`Error: invalid workflow '${rawWorkflow}'. Valid: ${VALID_WORKFLOWS.join(', ')}`);
+        process.exit(1);
+    }
+    const workflowName = rawWorkflow;
+    // Degraded mode: skip all AI features, deterministic analysis only
+    const degraded = args.degradedMode || process.env.E2E_AGENTS_DEGRADED === 'true';
+    if (degraded) {
+        console.log('Running in degraded mode — deterministic analysis only, no LLM calls.');
+    }
+    // Prune expired cache entries to prevent unbounded growth on CI
+    try {
+        const cache = new ResponseCache(testsRoot);
+        const pruned = cache.prune();
+        if (pruned > 0) {
+            console.log(`Cache: pruned ${pruned} expired entries.`);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Cache prune warning: ${msg}`);
+    }
+    const crewConfig = {
+        appPath: config.path,
+        testsRoot,
+        gitSince: args.gitSince || config.git.since,
+        routeFamilies: config.routeFamilies,
+        apiSurface: config.apiSurface,
+        workflow: workflowName,
+        providerOverride: args.llmProvider,
+        budgetUSD: args.budgetUSD,
+        dryRun: degraded || args.dryRun,
+        plugins: args.plugins,
+    };
+    // Create orchestrator and register all agents
+    const orchestrator = new CrewOrchestrator();
+    orchestrator.registerAgent(new ImpactAnalystAgent());
+    orchestrator.registerAgent(new GeneratorAgent());
+    orchestrator.registerAgent(new ExecutorAgent());
+    orchestrator.registerAgent(new HealerAgent());
+    orchestrator.registerAgent(new StrategistAgent());
+    orchestrator.registerAgent(new TestDesignerAgent());
+    orchestrator.registerAgent(new CrossImpactAgent());
+    orchestrator.registerAgent(new RegressionAdvisorAgent());
+    let result;
+    try {
+        result = await orchestrator.run(crewConfig);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Crew workflow failed: ${message}`);
+        process.exit(1);
+    }
+    const ctx = result.context;
+    // Dry-run output
+    if (result.dryRun) {
+        printDryRunOutput(result, workflowName, args.jsonOutput);
+        return;
+    }
+    // Write crew metrics to metrics.jsonl for cost-report
+    if (ctx.usage.requestCount > 0) {
+        try {
+            const baseDir = join(testsRoot, '.e2e-ai-agents');
+            mkdirSync(baseDir, { recursive: true });
+            const metricsPath = join(baseDir, 'metrics.jsonl');
+            const crewMetric = {
+                type: 'crew-run',
+                timestamp: new Date().toISOString(),
+                workflow: workflowName,
+                totalCost: ctx.usage.totalCost,
+                totalTokens: ctx.usage.totalTokens,
+                totalInputTokens: ctx.usage.totalInputTokens,
+                totalOutputTokens: ctx.usage.totalOutputTokens,
+                agentUsage: ctx.agentUsage,
+            };
+            appendFileSync(metricsPath, `${JSON.stringify(crewMetric)}\n`, 'utf-8');
+        }
+        catch {
+            // Non-fatal: metrics writing should not break the workflow
+        }
+    }
+    // JSON output mode
+    if (args.jsonOutput) {
+        const jsonReport = {
+            workflow: workflowName,
+            changedFiles: ctx.changedFiles.length,
+            impactedFlows: ctx.impactedFlows,
+            strategyEntries: ctx.strategyEntries,
+            testDesigns: ctx.testDesigns,
+            crossImpacts: ctx.crossImpacts,
+            regressionRisks: ctx.regressionRisks,
+            findings: ctx.findings,
+            generatedSpecs: ctx.generatedSpecs.map((s) => ({ flowId: s.flowId, specPath: s.specPath, mode: s.mode, written: s.written })),
+            usage: { cost: ctx.usage.totalCost, requests: ctx.usage.requestCount, tokens: ctx.usage.totalTokens },
+            timings: result.timings,
+            warnings: result.warnings,
+        };
+        console.log(JSON.stringify(jsonReport, null, 2));
+        return;
+    }
+    // Human-readable output
+    console.log(`Crew workflow: ${workflowName}`);
+    console.log(`Changed files: ${ctx.changedFiles.length}`);
+    console.log(`Impacted flows: ${ctx.impactedFlows.length}`);
+    console.log(`Strategy entries: ${ctx.strategyEntries.length}`);
+    console.log(`Test designs: ${ctx.testDesigns.length} (${ctx.testDesigns.reduce((sum, td) => sum + td.testCases.length, 0)} test cases)`);
+    console.log(`Cross-impacts: ${ctx.crossImpacts.length}`);
+    console.log(`Regression risks: ${ctx.regressionRisks.length}`);
+    console.log(`Findings: ${ctx.findings.length}`);
+    console.log(`Generated specs: ${ctx.generatedSpecs.length}`);
+    console.log(`Cost: $${ctx.usage.totalCost.toFixed(4)}`);
+    if (ctx.strategyEntries.length > 0) {
+        console.log('\nTest Strategy:');
+        for (const entry of ctx.strategyEntries) {
+            console.log(`  ${entry.priority} ${entry.flowName} → ${entry.approach} [${entry.testCategories.join(', ')}]`);
+        }
+    }
+    if (ctx.testDesigns.length > 0) {
+        console.log('\nTest Designs:');
+        for (const design of ctx.testDesigns) {
+            console.log(`  ${design.flowName}: ${design.testCases.length} test cases`);
+            for (const tc of design.testCases) {
+                console.log(`    [${tc.type}] ${tc.name} (${tc.priority})`);
+            }
+        }
+    }
+    if (ctx.crossImpacts.length > 0) {
+        console.log('\nCross-Family Impacts:');
+        for (const ci of ctx.crossImpacts) {
+            console.log(`  ${ci.sourceFamily} → ${ci.affectedFamily} (${ci.riskLevel}): ${ci.sharedDependency}`);
+        }
+    }
+    if (result.timings && Object.keys(result.timings).length > 0) {
+        console.log('\nPhase timings:');
+        for (const [phase, ms] of Object.entries(result.timings)) {
+            console.log(`  ${phase}: ${ms}ms`);
+        }
+    }
+    if (result.warnings.length > 0) {
+        console.log(`\nWarnings: ${result.warnings.length}`);
+        for (const w of result.warnings.slice(0, 10)) {
+            console.log(`  - ${w}`);
+        }
+        if (result.warnings.length > 10) {
+            console.log(`  ... and ${result.warnings.length - 10} more`);
+        }
+    }
+}
+function printDryRunOutput(result, workflowName, jsonOutput) {
+    const ctx = result.context;
+    const workflow = WORKFLOWS[workflowName];
+    if (jsonOutput) {
+        console.log(JSON.stringify({
+            dryRun: true,
+            workflow: workflowName,
+            changedFiles: ctx.changedFiles,
+            familyGroups: ctx.familyGroups.map((fg) => ({
+                familyId: fg.familyId,
+                featureId: fg.featureId,
+                files: fg.files,
+            })),
+            phases: workflow.phases.map((p) => ({
+                name: p.name,
+                agents: p.parallel || p.sequential || [],
+            })),
+            manifestSource: ctx.manifest?.source || 'none',
+            warnings: result.warnings,
+        }, null, 2));
+        return;
+    }
+    console.log('Dry run — no LLM calls will be made.\n');
+    console.log(`Changed files (${ctx.changedFiles.length}):`);
+    for (const f of ctx.changedFiles.slice(0, 20)) {
+        console.log(`  ${f}`);
+    }
+    if (ctx.changedFiles.length > 20) {
+        console.log(`  ... and ${ctx.changedFiles.length - 20} more`);
+    }
+    console.log(`\nAffected families (${ctx.familyGroups.length}):`);
+    for (const fg of ctx.familyGroups) {
+        const label = fg.featureId ? `${fg.familyId}/${fg.featureId}` : fg.familyId;
+        console.log(`  ${label} (${fg.files.length} files)`);
+    }
+    if (ctx.manifest?.source === 'heuristic') {
+        console.log('\n  Note: Using directory-based heuristics. Run `impact-gate train` for better accuracy.');
+    }
+    console.log(`\nWorkflow: ${workflowName}`);
+    const phaseNames = workflow.phases
+        .map((p) => {
+        const agents = p.parallel || p.sequential || [];
+        return agents.length > 0 ? `${p.name} (${agents.join(', ')})` : p.name;
+    })
+        .join(' → ');
+    console.log(`Phases: ${phaseNames}`);
+    // Cost estimation based on workflow and family count
+    const familyCount = Math.max(ctx.familyGroups.length, 1);
+    const agentCount = workflow.phases.reduce((sum, p) => sum + (p.parallel?.length || 0) + (p.sequential?.length || 0), 0);
+    const costEstimate = estimateCost(workflowName, familyCount, agentCount);
+    console.log(`\nEstimated cost: $${costEstimate.low.toFixed(2)}-$${costEstimate.high.toFixed(2)}`);
+    if (ctx.modelRoutingProviderType) {
+        console.log(`  With model routing: $${(costEstimate.low * 0.5).toFixed(2)}-$${(costEstimate.high * 0.5).toFixed(2)} (Haiku for classification)`);
+    }
+}
+/** Rough cost estimation based on observed averages per workflow type */
+function estimateCost(workflow, families, _agents) {
+    // Per-family cost ranges by workflow (based on typical Sonnet pricing)
+    const ranges = {
+        'quick-check': { low: 0.03, high: 0.10 },
+        'design-only': { low: 0.10, high: 0.40 },
+        'full-qa': { low: 0.30, high: 1.00 },
+    };
+    const range = ranges[workflow] || ranges['full-qa'];
+    return {
+        low: range.low * families,
+        high: range.high * families,
+    };
+}

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

@@ -0,0 +1,36 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { readFileSync } from 'fs';
+import { resolveConfig } from '../../agent/config.js';
+import { appendFeedbackAndRecompute } from '../../agent/feedback.js';
+export function runFeedbackCommand(args, autoConfig) {
+    if (!args.path && !autoConfig) {
+        console.error('Error: --path is required for feedback command');
+        process.exit(1);
+    }
+    if (!args.feedbackInputPath) {
+        console.error('Error: --feedback-input <path> is required for feedback command');
+        process.exit(1);
+    }
+    const { config } = resolveConfig(process.cwd(), autoConfig, {
+        path: args.path,
+        profile: args.profile,
+        testsRoot: args.testsRoot,
+        mode: 'impact',
+        llmProvider: args.llmProvider,
+    });
+    const reportRoot = config.testsRoot || config.path;
+    const raw = JSON.parse(readFileSync(args.feedbackInputPath, 'utf-8'));
+    const payload = {
+        timestamp: raw.timestamp || new Date().toISOString(),
+        runSet: raw.runSet || 'targeted',
+        recommendedTests: raw.recommendedTests || [],
+        executedTests: raw.executedTests || [],
+        failedTests: raw.failedTests || [],
+        escapedFailures: raw.escapedFailures || [],
+    };
+    const output = appendFeedbackAndRecompute(reportRoot, payload);
+    console.log(`Feedback data: ${output.feedbackPath}`);
+    console.log(`Calibration data: ${output.calibrationPath}`);
+    console.log(`Calibration overall: precision=${output.calibration.overall.precision}, recall=${output.calibration.overall.recall}, fnr=${output.calibration.overall.falseNegativeRate}`);
+}

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

@@ -0,0 +1,38 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { resolveConfig } from '../../agent/config.js';
+import { finalizeGeneratedTests } from '../../agent/handoff.js';
+export function runFinalizeCommand(args, autoConfig) {
+    if (!args.path && !autoConfig) {
+        console.error('Error: --path is required for finalize-generated-tests command');
+        process.exit(1);
+    }
+    const { config } = resolveConfig(process.cwd(), autoConfig, {
+        path: args.path,
+        profile: args.profile,
+        testsRoot: args.testsRoot,
+        mode: 'gap',
+        llmProvider: args.llmProvider,
+    });
+    const result = finalizeGeneratedTests({
+        appPath: config.path,
+        testsRoot: config.testsRoot || config.path,
+        branch: args.branch,
+        commitMessage: args.commitMessage,
+        createPr: args.createPr,
+        prTitle: args.prTitle,
+        prBody: args.prBody,
+        baseBranch: args.prBase,
+        dryRun: args.dryRun,
+    });
+    console.log(`Finalize repo root: ${result.repoRoot}`);
+    console.log(`Finalize branch: ${result.branch}`);
+    console.log(`Finalize staged paths: ${result.stagedPaths.join(', ') || 'none'}`);
+    console.log(`Finalize commit: ${result.committed ? 'created' : 'skipped'}`);
+    if (result.commitSha) {
+        console.log(`Finalize commit sha: ${result.commitSha}`);
+    }
+    if (result.prUrl) {
+        console.log(`Finalize PR: ${result.prUrl}`);
+    }
+}

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

@@ -0,0 +1,86 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * CLI command: gate — CI coverage gate that exits 1 if coverage is below threshold.
+ *
+ * Runs deterministic impact analysis (no LLM required) and checks what
+ * percentage of impacted features have test coverage.
+ *
+ * Usage:
+ *   impact-gate gate --threshold 80 --path . --since origin/main
+ */
+import { resolveConfig } from '../../agent/config.js';
+import { getChangedFiles } from '../../agent/git.js';
+import { analyzeImpact } from '../../engine/impact_engine.js';
+export async function runGateCommand(args, autoConfig) {
+    if (!args.path && !autoConfig) {
+        console.error('Error: --path is required for gate command');
+        process.exit(1);
+    }
+    let threshold = args.gateThreshold ?? 80;
+    if (threshold > 0 && threshold < 1) {
+        threshold = threshold * 100;
+    }
+    const { config } = resolveConfig(process.cwd(), autoConfig, {
+        path: args.path,
+        profile: args.profile,
+        testsRoot: args.testsRoot,
+        mode: 'impact',
+        gitSince: args.gitSince,
+    });
+    const testsRoot = config.testsRoot || config.path;
+    const gitSince = args.gitSince || config.git.since;
+    // Get changed files
+    const result = await getChangedFiles(config.path, gitSince);
+    const changedFiles = result.files;
+    if (changedFiles.length === 0) {
+        console.log('No changed files detected. Gate passes.');
+        process.exit(0);
+    }
+    // Run deterministic impact analysis
+    const impact = analyzeImpact(changedFiles, {
+        testsRoot,
+        routeFamilies: config.routeFamilies,
+    });
+    const totalFeatures = impact.impactedFeatures.length;
+    if (totalFeatures === 0) {
+        console.log('No impacted features detected. Gate passes.');
+        process.exit(0);
+    }
+    const coveredFeatures = impact.impactedFeatures.filter((f) => f.coverageStatus === 'covered' || f.coverageStatus === 'partial').length;
+    const coveragePercent = Math.round((coveredFeatures / totalFeatures) * 100);
+    // Output
+    if (args.jsonOutput) {
+        console.log(JSON.stringify({
+            threshold,
+            coveragePercent,
+            totalFeatures,
+            coveredFeatures,
+            passed: coveragePercent >= threshold,
+            uncoveredFeatures: impact.impactedFeatures
+                .filter((f) => f.coverageStatus === 'uncovered')
+                .map((f) => ({ id: f.featureId || f.familyId, priority: f.priority })),
+        }, null, 2));
+    }
+    else {
+        console.log(`Coverage gate: ${coveragePercent}% (${coveredFeatures}/${totalFeatures} features covered)`);
+        console.log(`Threshold: ${threshold}%`);
+        if (coveragePercent < threshold) {
+            console.log(`\nFAILED — coverage ${coveragePercent}% is below ${threshold}% threshold`);
+            const uncovered = impact.impactedFeatures.filter((f) => f.coverageStatus === 'uncovered');
+            if (uncovered.length > 0) {
+                console.log('\nUncovered features:');
+                for (const f of uncovered.slice(0, 10)) {
+                    console.log(`  ${f.priority || 'P2'} ${f.featureId || f.familyId}`);
+                }
+                if (uncovered.length > 10) {
+                    console.log(`  ... and ${uncovered.length - 10} more`);
+                }
+            }
+        }
+        else {
+            console.log('\nPASSED');
+        }
+    }
+    process.exit(coveragePercent >= threshold ? 0 : 1);
+}

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

@@ -0,0 +1,105 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { LLMProviderFactory } from '../../provider_factory.js';
+import { runAgenticGeneration } from '../../agentic/runner.js';
+import { loadOrBuildApiSurface } from '../../knowledge/api_surface.js';
+export async function runGenerateCommand(args, config) {
+    const reportRoot = config.testsRoot || config.path;
+    // Load scenarios from --scenarios flag or plan-report.json
+    let scenarios = [];
+    if (args.generateScenarios) {
+        let raw;
+        if (existsSync(args.generateScenarios)) {
+            raw = JSON.parse(readFileSync(args.generateScenarios, 'utf-8'));
+        }
+        else {
+            raw = JSON.parse(args.generateScenarios);
+        }
+        if (!Array.isArray(raw)) {
+            console.error('--scenarios must be a JSON array of ScenarioInput objects.');
+            process.exit(1);
+        }
+        for (const item of raw) {
+            if (!item.id || !item.name || !Array.isArray(item.scenarios) || !item.routeFamily || !item.priority) {
+                console.error(`Invalid scenario: each must have id, name, scenarios[], routeFamily, priority.`);
+                process.exit(1);
+            }
+        }
+        scenarios = raw;
+    }
+    else {
+        // Try plan.json first (written by plan/suggest command), then plan-report.json (legacy)
+        const planJsonPath = join(reportRoot, '.e2e-ai-agents', 'plan.json');
+        const planReportPath = join(reportRoot, '.e2e-ai-agents', 'plan-report.json');
+        const resolvedPlanPath = existsSync(planJsonPath) ? planJsonPath : existsSync(planReportPath) ? planReportPath : null;
+        if (!resolvedPlanPath) {
+            console.error('No plan report found. Run `plan` first or pass --scenarios.');
+            process.exit(1);
+        }
+        const planReport = JSON.parse(readFileSync(resolvedPlanPath, 'utf-8'));
+        scenarios = (planReport.gapDetails || []).map((gap) => ({
+            id: gap.id,
+            name: gap.id,
+            scenarios: gap.missingScenarios || gap.reasons || ['Verify core user flow'],
+            routeFamily: gap.id.split('.')[0] || gap.id,
+            priority: 'P1',
+        }));
+    }
+    if (scenarios.length === 0) {
+        console.log('No scenarios to generate tests for.');
+        return;
+    }
+    let apiSurface;
+    try {
+        apiSurface = loadOrBuildApiSurface(reportRoot, config.apiSurface);
+    }
+    catch {
+        console.warn('Could not load API surface catalog. Generation will use generic selectors.');
+    }
+    const provider = await LLMProviderFactory.createFromPreference(config.llm.provider);
+    console.log(`Generating tests for ${scenarios.length} scenario(s)...`);
+    const summary = await runAgenticGeneration({
+        scenarios,
+        config: {
+            maxAttempts: args.maxAttempts || 3,
+            project: args.pipelineProject || 'chrome',
+            baseUrl: args.pipelineBaseUrl,
+            testTimeoutMs: 120000,
+            testsRoot: reportRoot,
+            dryRun: args.dryRun,
+        },
+        provider,
+        apiSurface,
+    });
+    console.log(`\nAgentic Generation Summary:`);
+    console.log(`  Generated: ${summary.totalGenerated}`);
+    console.log(`  Passed:    ${summary.totalPassed}`);
+    console.log(`  Failed:    ${summary.totalFailed}`);
+    console.log(`  Attempts:  ${summary.totalAttempts}`);
+    console.log(`  Duration:  ${(summary.durationMs / 1000).toFixed(1)}s`);
+    for (const result of summary.results) {
+        const icon = result.status === 'passed' ? 'PASS' : result.status === 'skipped' ? 'SKIP' : 'FAIL';
+        console.log(`  [${icon}] ${result.scenarioSource} (${result.attempts} attempts)`);
+        if (result.status === 'passed' || result.status === 'skipped') {
+            console.log(`     ${result.specPath}`);
+        }
+    }
+    if (summary.warnings.length > 0) {
+        console.log(`\nWarnings:`);
+        for (const w of summary.warnings) {
+            console.warn(`  - ${w}`);
+        }
+    }
+    const summaryDir = join(reportRoot, '.e2e-ai-agents');
+    if (!existsSync(summaryDir)) {
+        mkdirSync(summaryDir, { recursive: true });
+    }
+    const summaryPath = join(summaryDir, 'agentic-summary.json');
+    writeFileSync(summaryPath, JSON.stringify(summary, null, 2), 'utf-8');
+    console.log(`\nReport: ${summaryPath}`);
+    if (summary.totalFailed > 0) {
+        process.exit(1);
+    }
+}