@yasserkhanorg/impact-gate 2.0.0

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

@@ -0,0 +1,57 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { resolveConfig } from '../../agent/config.js';
+import { runTargetedSpecHeal } from '../../agent/pipeline.js';
+import { extractPlaywrightUnstableSpecs } from '../../agent/playwright_report.js';
+export function runHealCommand(args, autoConfig) {
+    if (!args.path && !autoConfig) {
+        console.error('Error: --path is required for heal command');
+        process.exit(1);
+    }
+    if (!args.traceabilityReportPath) {
+        console.error('Error: --traceability-report <path> is required for heal command');
+        process.exit(1);
+    }
+    const { config } = resolveConfig(process.cwd(), autoConfig, {
+        path: args.path,
+        profile: args.profile,
+        testsRoot: args.testsRoot,
+        mode: 'gap',
+        framework: args.framework,
+        pipeline: {
+            enabled: true,
+            scenarios: args.pipelineScenarios,
+            outputDir: args.pipelineOutput,
+            baseUrl: args.pipelineBaseUrl,
+            browser: args.pipelineBrowser,
+            headless: args.pipelineHeadless,
+            project: args.pipelineProject,
+            parallel: args.pipelineParallel,
+            dryRun: args.pipelineDryRun,
+            mcp: args.pipelineMcp,
+            mcpAllowFallback: args.pipelineMcpAllowFallback,
+            mcpOnly: args.pipelineMcpOnly,
+        },
+        llmProvider: args.llmProvider,
+    });
+    const reportRoot = config.testsRoot || config.path;
+    const unstableSpecs = extractPlaywrightUnstableSpecs(args.traceabilityReportPath, [reportRoot, config.path]);
+    if (unstableSpecs.length === 0) {
+        console.log('Heal targeted unstable specs: 0');
+        return;
+    }
+    const targetedSummary = runTargetedSpecHeal(reportRoot, unstableSpecs.map((spec) => ({
+        specPath: spec.specPath,
+        status: spec.status,
+        reason: `Playwright report: failingTests=${spec.failingTests}, flakyTests=${spec.flakyTests}`,
+    })), {
+        ...config.pipeline,
+        enabled: true,
+        heal: true,
+    });
+    const healedCount = targetedSummary.results.filter((result) => result.healStatus === 'success').length;
+    console.log(`Heal targeted unstable specs: ${unstableSpecs.length} (healed=${healedCount})`);
+    if (targetedSummary.warnings.length > 0) {
+        console.log(`Heal warnings: ${targetedSummary.warnings.join(' | ')}`);
+    }
+}

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

@@ -0,0 +1,30 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { getChangedFiles } from '../../agent/git.js';
+import { analyzeImpact as analyzeImpactV2 } from '../../engine/impact_engine.js';
+export function runImpactCommand(args, config) {
+    const reportRoot = config.testsRoot || config.path;
+    const gitResult = getChangedFiles(config.path, config.git.since, { includeUncommitted: config.git.includeUncommitted });
+    const impactResult = analyzeImpactV2(gitResult.files, {
+        testsRoot: reportRoot,
+        routeFamilies: config.routeFamilies,
+    });
+    console.log(`Impact: ${impactResult.changedFiles.length} changed files → ${impactResult.impactedFeatures.length} features impacted`);
+    console.log(`Unbound files: ${impactResult.unboundFiles.length}`);
+    for (const f of impactResult.impactedFeatures) {
+        const label = f.featureId || f.familyId;
+        console.log(`  [${f.priority}] ${label}: ${f.coverageStatus} (PW=${f.playwrightSpecs.length}, Cy=${f.cypressSpecs.length})`);
+    }
+    if (impactResult.warnings.length > 0) {
+        for (const w of impactResult.warnings) {
+            console.warn(`  Warning: ${w}`);
+        }
+    }
+    const outputDir = join(reportRoot, '.e2e-ai-agents');
+    mkdirSync(outputDir, { recursive: true });
+    const planPath = join(outputDir, 'plan.json');
+    writeFileSync(planPath, JSON.stringify(impactResult, null, 2));
+    console.log(`Wrote ${planPath}`);
+}

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

@@ -0,0 +1,133 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { existsSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import * as readline from 'readline';
+import { detectFramework, detectTestsRoot, detectGitDefaultBranch } from '../defaults.js';
+const CONFIG_FILENAME = 'impact-gate.config.json';
+const LEGACY_CONFIG_FILENAMES = ['e2e-ai-agents.config.json', '.e2e-ai-agents.config.json'];
+function createInterface() {
+    return readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+}
+function ask(rl, question, defaultValue) {
+    const suffix = defaultValue ? ` (${defaultValue})` : '';
+    return new Promise((resolve) => {
+        rl.question(`${question}${suffix}: `, (answer) => {
+            resolve(answer.trim() || defaultValue || '');
+        });
+    });
+}
+function buildConfig(answers) {
+    const config = {
+        path: answers.path,
+        framework: answers.framework,
+        git: { since: answers.gitSince },
+        impact: {
+            dependencyGraph: { enabled: true, maxDepth: 3 },
+            traceability: { enabled: true },
+            aiFlow: {
+                enabled: answers.enableAi,
+                provider: answers.enableAi ? answers.provider : undefined,
+            },
+        },
+        policy: {
+            enforcementMode: answers.enforcementMode,
+            blockOnActions: ['must-add-tests'],
+        },
+    };
+    if (answers.testsRoot && answers.testsRoot !== '.' && answers.testsRoot !== answers.path) {
+        config.testsRoot = answers.testsRoot;
+    }
+    return config;
+}
+function printNextSteps() {
+    console.log('');
+    console.log('  Next steps:');
+    console.log('    1. Start with impact analysis:  npx impact-gate impact --path .');
+    console.log('    2. Build a coverage plan:      npx impact-gate plan --path .');
+    console.log('    3. Optional AI setup:          export ANTHROPIC_API_KEY=sk-ant-...');
+    console.log('    4. Verify provider health:     npx impact-gate llm-health');
+    console.log('');
+}
+export async function runInitCommand(yes = false) {
+    const targetDir = process.cwd();
+    const configPath = join(targetDir, CONFIG_FILENAME);
+    const existingLegacyConfig = LEGACY_CONFIG_FILENAMES.find((filename) => existsSync(join(targetDir, filename)));
+    if (existsSync(configPath) || existingLegacyConfig) {
+        const existingName = existsSync(configPath) ? CONFIG_FILENAME : existingLegacyConfig;
+        console.error(`${existingName} already exists in this directory.`);
+        console.error('Remove it first if you want to re-initialize.');
+        process.exit(1);
+    }
+    // Non-interactive mode: auto-detect everything and write immediately
+    if (yes) {
+        const appPath = '.';
+        const answers = {
+            path: appPath,
+            testsRoot: detectTestsRoot(appPath) || '.',
+            framework: detectFramework(appPath),
+            gitSince: detectGitDefaultBranch(appPath),
+            provider: 'auto',
+            enableAi: true,
+            enforcementMode: 'advisory',
+        };
+        const config = buildConfig(answers);
+        const json = JSON.stringify(config, null, 2) + '\n';
+        writeFileSync(configPath, json, 'utf-8');
+        console.log(`Created ${CONFIG_FILENAME}`);
+        printNextSteps();
+        return;
+    }
+    console.log('');
+    console.log('  impact-gate init');
+    console.log('  ==================');
+    console.log('');
+    console.log('  This will create an impact-gate.config.json in the current directory.');
+    console.log('  Legacy e2e-ai-agents config filenames are still supported during migration.');
+    console.log('');
+    const rl = createInterface();
+    try {
+        const appPath = await ask(rl, '  Path to your web app root', '.');
+        const detectedFramework = detectFramework(appPath);
+        const framework = await ask(rl, '  Test framework (auto | playwright | cypress | pytest | supertest | selenium)', detectedFramework);
+        const detectedTestsRoot = detectTestsRoot(appPath);
+        const testsRoot = await ask(rl, '  Path to tests root (relative to app root, "." if same)', detectedTestsRoot || '.');
+        const detectedBranch = detectGitDefaultBranch(appPath);
+        const gitSince = await ask(rl, '  Git ref to diff against', detectedBranch);
+        const providerAnswer = await ask(rl, '  LLM provider for AI features (anthropic | openai | ollama | auto)', 'auto');
+        const enableAi = providerAnswer !== 'none';
+        const enforcementMode = await ask(rl, '  Policy enforcement mode (advisory | warn | block)', 'advisory');
+        const answers = {
+            path: appPath,
+            testsRoot,
+            framework,
+            gitSince,
+            provider: providerAnswer,
+            enableAi,
+            enforcementMode,
+        };
+        const config = buildConfig(answers);
+        const json = JSON.stringify(config, null, 2) + '\n';
+        console.log('');
+        console.log('  Generated config:');
+        console.log('');
+        for (const line of json.split('\n')) {
+            console.log(`    ${line}`);
+        }
+        const confirm = await ask(rl, '  Write this config? (Y/n)', 'Y');
+        if (confirm.toLowerCase() !== 'y' && confirm !== '') {
+            console.log('  Aborted.');
+            process.exit(0);
+        }
+        writeFileSync(configPath, json, 'utf-8');
+        console.log('');
+        console.log(`  Created ${CONFIG_FILENAME}`);
+        printNextSteps();
+    }
+    finally {
+        rl.close();
+    }
+}

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

@@ -0,0 +1,19 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { LLMProviderFactory } from '../../provider_factory.js';
+export async function runLlmHealth() {
+    try {
+        const provider = await LLMProviderFactory.createFromEnv();
+        const health = await provider.checkHealth();
+        if (!health.healthy) {
+            console.error(`${provider.name} failed: ${health.message}`);
+            process.exit(1);
+        }
+        console.log(`${provider.name} OK -> ${health.message}`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`LLM health check failed: ${message}`);
+        process.exit(1);
+    }
+}

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

@@ -0,0 +1,117 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { appendFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { writeCiSummary } from '../../engine/plan_builder.js';
+import { recommendTestsAI, recommendTestsDeterministic } from '../../api.js';
+import { appendCrewToSummary, runPlanCrewAnalysis, writeCrewArtifacts } from './plan_crew.js';
+export async function runPlanCommand(args, autoConfig, config) {
+    const reportRoot = config.testsRoot || config.path;
+    const apiOptions = {
+        cwd: process.cwd(),
+        configPath: autoConfig,
+        path: args.path,
+        profile: args.profile,
+        testsRoot: args.testsRoot,
+        gitSince: args.gitSince,
+        llmProvider: args.llmProvider,
+        policy: args.policyMinConfidence !== undefined ||
+            args.policySafeMergeConfidence !== undefined ||
+            args.policyWarningsThreshold !== undefined ||
+            (args.policyRiskyPatterns && args.policyRiskyPatterns.length > 0) ||
+            args.policyEnforcementMode !== undefined ||
+            (args.policyBlockActions && args.policyBlockActions.length > 0)
+            ? {
+                minConfidenceForTargeted: args.policyMinConfidence,
+                safeMergeMinConfidence: args.policySafeMergeConfidence,
+                forceFullOnWarningsAtOrAbove: args.policyWarningsThreshold,
+                riskyFilePatterns: args.policyRiskyPatterns,
+                enforcementMode: args.policyEnforcementMode,
+                blockOnActions: args.policyBlockActions,
+            }
+            : undefined,
+    };
+    let result;
+    if (args.noAi) {
+        result = recommendTestsDeterministic(apiOptions);
+    }
+    else {
+        result = await recommendTestsAI(apiOptions);
+        if (result.aiEnrichment) {
+            const { aiEnrichment } = result;
+            console.log(`AI enrichment: ${aiEnrichment.enrichedFeatures.length} features enriched (${aiEnrichment.tokenUsage.input + aiEnrichment.tokenUsage.output} tokens)`);
+        }
+        else if (!process.env.ANTHROPIC_API_KEY && !process.env.OPENAI_API_KEY && !process.env.LLM_PROVIDER) {
+            console.log('Tip: configure ANTHROPIC_API_KEY, OPENAI_API_KEY, or LLM_PROVIDER to enable AI-powered enrichment');
+        }
+    }
+    const { plan, planPath, ciSummaryMarkdown, ciSummaryPath } = result;
+    let planReport = plan;
+    let combinedSummaryMarkdown = ciSummaryMarkdown;
+    let crewSummaryPath = '';
+    let crewMarkdownPath = '';
+    let crewTestPlanPath = '';
+    if (args.crew) {
+        try {
+            const crew = await runPlanCrewAnalysis(plan, config, args);
+            planReport = {
+                ...plan,
+                crew,
+            };
+            combinedSummaryMarkdown = appendCrewToSummary(ciSummaryMarkdown, crew, plan);
+            const artifacts = writeCrewArtifacts(reportRoot, crew, plan);
+            crewSummaryPath = artifacts.crewSummaryPath;
+            crewMarkdownPath = artifacts.crewMarkdownPath;
+            crewTestPlanPath = artifacts.crewTestPlanPath;
+            writeFileSync(planPath, JSON.stringify(planReport, null, 2), 'utf-8');
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`Crew analysis unavailable: ${message}`);
+        }
+    }
+    writeCiSummary(reportRoot, combinedSummaryMarkdown);
+    const summaryPath = args.ciCommentPath
+        ? writeCiSummary(reportRoot, combinedSummaryMarkdown, args.ciCommentPath)
+        : ciSummaryPath;
+    // Compute metrics paths (api already wrote metrics; derive paths for GHA output)
+    const metricsEventsPath = join(reportRoot, '.e2e-ai-agents/metrics.jsonl');
+    const metricsSummaryPath = join(reportRoot, '.e2e-ai-agents/metrics-summary.json');
+    const ghaOutput = args.githubOutputPath || process.env.GITHUB_OUTPUT;
+    if (ghaOutput) {
+        appendFileSync(ghaOutput, `run_set=${planReport.runSet}\n`);
+        appendFileSync(ghaOutput, `action=${planReport.decision.action}\n`);
+        appendFileSync(ghaOutput, `confidence=${planReport.confidence}\n`);
+        appendFileSync(ghaOutput, `enforcement_mode=${planReport.enforcement.mode}\n`);
+        appendFileSync(ghaOutput, `enforcement_should_fail=${planReport.enforcement.shouldFail}\n`);
+        appendFileSync(ghaOutput, `recommended_tests_count=${planReport.recommendedTests.length}\n`);
+        appendFileSync(ghaOutput, `required_new_tests_count=${planReport.requiredNewTests.length}\n`);
+        appendFileSync(ghaOutput, `plan_path=${planPath}\n`);
+        appendFileSync(ghaOutput, `summary_path=${summaryPath}\n`);
+        appendFileSync(ghaOutput, `metrics_events_path=${metricsEventsPath}\n`);
+        appendFileSync(ghaOutput, `metrics_summary_path=${metricsSummaryPath}\n`);
+        appendFileSync(ghaOutput, `crew_enabled=${planReport.crew ? 'true' : 'false'}\n`);
+        appendFileSync(ghaOutput, `crew_workflow=${planReport.crew?.workflow || ''}\n`);
+        appendFileSync(ghaOutput, `crew_summary_path=${crewSummaryPath}\n`);
+        appendFileSync(ghaOutput, `crew_markdown_path=${crewMarkdownPath}\n`);
+        appendFileSync(ghaOutput, `crew_test_plan_path=${crewTestPlanPath}\n`);
+        appendFileSync(ghaOutput, `crew_impacted_flows=${planReport.crew?.summary.impactedFlows || 0}\n`);
+        appendFileSync(ghaOutput, `crew_strategy_entries=${planReport.crew?.summary.strategyEntries || 0}\n`);
+        appendFileSync(ghaOutput, `crew_test_designs=${planReport.crew?.summary.testDesigns || 0}\n`);
+    }
+    console.log(`Suggested run set: ${planReport.runSet} (confidence ${planReport.confidence})`);
+    console.log(`Decision: ${planReport.decision.action} - ${planReport.decision.summary}`);
+    console.log(`Enforcement: ${planReport.enforcement.mode} (shouldFail=${planReport.enforcement.shouldFail})`);
+    console.log(`Plan data: ${planPath}`);
+    console.log(`CI summary: ${summaryPath}`);
+    if (planReport.crew) {
+        console.log(`Crew workflow: ${planReport.crew.workflow} (impactedFlows=${planReport.crew.summary.impactedFlows}, strategyEntries=${planReport.crew.summary.strategyEntries}, testDesigns=${planReport.crew.summary.testDesigns})`);
+        console.log(`Crew summary: ${crewSummaryPath}`);
+        console.log(`Crew test plan: ${crewTestPlanPath}`);
+    }
+    console.log(`Plan metrics: ${metricsSummaryPath}`);
+    const failOnLegacyFlag = args.failOnMustAddTests && planReport.decision.action === 'must-add-tests';
+    if (failOnLegacyFlag || planReport.enforcement.shouldFail) {
+        process.exit(2);
+    }
+}

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

@@ -0,0 +1,309 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { CrossImpactAgent } from '../../agents/cross-impact.js';
+import { ImpactAnalystAgent } from '../../agents/impact-analyst.js';
+import { RegressionAdvisorAgent } from '../../agents/regression-advisor.js';
+import { StrategistAgent } from '../../agents/strategist.js';
+import { TestDesignerAgent } from '../../agents/test-designer.js';
+import { CrewOrchestrator } from '../../crew/orchestrator.js';
+const VALID_WORKFLOWS = new Set(['full-qa', 'quick-check', 'design-only']);
+function uniqueStrings(values) {
+    return Array.from(new Set(values.filter(Boolean)));
+}
+function singleLine(value) {
+    return value.replace(/\s+/g, ' ').trim();
+}
+function chooseCrewWorkflow(explicitWorkflow, plan) {
+    if (explicitWorkflow && VALID_WORKFLOWS.has(explicitWorkflow)) {
+        return explicitWorkflow;
+    }
+    if (plan.decision.action === 'must-add-tests' || plan.metrics.uncoveredP0P1Flows > 0) {
+        return 'design-only';
+    }
+    return 'quick-check';
+}
+function registerCrewAgents(orchestrator) {
+    orchestrator.registerAgent(new ImpactAnalystAgent());
+    orchestrator.registerAgent(new StrategistAgent());
+    orchestrator.registerAgent(new TestDesignerAgent());
+    orchestrator.registerAgent(new CrossImpactAgent());
+    orchestrator.registerAgent(new RegressionAdvisorAgent());
+}
+export async function runPlanCrewAnalysis(plan, config, args) {
+    const reportRoot = config.testsRoot || config.path;
+    const workflow = chooseCrewWorkflow(args.crewWorkflow, plan);
+    const normalizedProvider = config.llm.provider?.trim().toLowerCase();
+    const providerOverride = normalizedProvider && normalizedProvider !== 'auto' ? normalizedProvider : 'auto';
+    const orchestrator = new CrewOrchestrator();
+    registerCrewAgents(orchestrator);
+    const result = await orchestrator.run({
+        appPath: config.path,
+        testsRoot: reportRoot,
+        gitSince: args.gitSince || config.git.since,
+        routeFamilies: config.routeFamilies,
+        apiSurface: config.apiSurface,
+        workflow,
+        providerOverride: providerOverride === 'auto' ? undefined : providerOverride,
+        budgetUSD: args.budgetUSD,
+        dryRun: args.dryRun,
+    });
+    const ctx = result.context;
+    const highRiskCrossImpacts = ctx.crossImpacts.filter((entry) => entry.riskLevel === 'high');
+    const manualReviewEntries = ctx.strategyEntries.filter((entry) => entry.approach === 'manual-review');
+    return {
+        workflow,
+        providerOverride,
+        summary: {
+            impactedFlows: ctx.impactedFlows.length,
+            strategyEntries: ctx.strategyEntries.length,
+            testDesigns: ctx.testDesigns.length,
+            crossImpacts: ctx.crossImpacts.length,
+            highRiskCrossImpacts: highRiskCrossImpacts.length,
+            regressionRisks: ctx.regressionRisks.length,
+            findings: ctx.findings.length,
+            generatedSpecs: ctx.generatedSpecs.length,
+            manualReviewEntries: manualReviewEntries.length,
+            totalCostUSD: Number(ctx.usage.totalCost.toFixed(4)),
+            totalTokens: ctx.usage.totalTokens,
+        },
+        impactedFlows: ctx.impactedFlows,
+        strategyEntries: ctx.strategyEntries,
+        testDesigns: ctx.testDesigns,
+        crossImpacts: ctx.crossImpacts,
+        regressionRisks: ctx.regressionRisks,
+        findings: ctx.findings,
+        warnings: uniqueStrings([...ctx.warnings, ...result.warnings]),
+        timings: result.timings,
+    };
+}
+/**
+ * Match a strategy/design entry against a set of gap family IDs.
+ */
+function matchesGapFamily(flowId, flowName, gapFamilies) {
+    return Array.from(gapFamilies).some((fam) => flowId.startsWith(fam) || flowName.toLowerCase().includes(fam.replace(/_/g, ' ')));
+}
+export function buildCrewMarkdown(crew, plan) {
+    const totalCases = crew.testDesigns.reduce((n, td) => n + td.testCases.length, 0);
+    const gapFamilies = new Set((plan?.gapDetails ?? []).map((g) => g.id));
+    const lines = [
+        '### Crew Analysis — What to Test',
+        '',
+        `Crew analyzed the diff and recommends what to verify before merging.`,
+        '',
+        `Impacted flows: **${crew.summary.impactedFlows}** | Strategy entries: **${crew.summary.strategyEntries}**`,
+    ];
+    if (totalCases > 0) {
+        const gapDesigns = gapFamilies.size > 0
+            ? crew.testDesigns.filter((td) => matchesGapFamily(td.flowId, td.flowName, gapFamilies))
+            : [];
+        const gapCases = gapDesigns.reduce((n, td) => n + td.testCases.length, 0);
+        const gapP0Cases = gapDesigns.reduce((n, td) => n + td.testCases.filter((tc) => tc.priority === 'P0').length, 0);
+        lines.push(`Structured test designs: **${crew.summary.testDesigns}** flows, **${totalCases}** test cases`);
+        if (gapDesigns.length > 0) {
+            lines.push(`Gap-focused: **${gapDesigns.length}** flows, **${gapCases}** test cases (**${gapP0Cases}** P0)`);
+        }
+    }
+    if (crew.summary.crossImpacts > 0) {
+        lines.push(`Cross-impacts: **${crew.summary.crossImpacts}** (${crew.summary.highRiskCrossImpacts} high risk)`);
+    }
+    lines.push(`Estimated AI cost: **$${crew.summary.totalCostUSD.toFixed(4)}**`);
+    if (crew.strategyEntries.length > 0) {
+        lines.push('');
+        lines.push('Top Strategy Recommendations:');
+        for (const entry of crew.strategyEntries.slice(0, 5)) {
+            lines.push(`- ${entry.priority} ${entry.flowName} -> ${entry.approach} (${entry.crossImpactRisk} cross-impact risk)`);
+        }
+    }
+    if (crew.testDesigns.length > 0) {
+        lines.push('');
+        lines.push('Structured Test Designs:');
+        for (const design of crew.testDesigns.slice(0, 3)) {
+            lines.push(`- ${design.flowName}: ${design.testCases.length} designed test case(s)`);
+        }
+    }
+    const riskyCrossImpacts = crew.crossImpacts.filter((entry) => entry.riskLevel === 'high');
+    if (riskyCrossImpacts.length > 0) {
+        lines.push('');
+        lines.push('High-Risk Cross-Impacts:');
+        for (const entry of riskyCrossImpacts.slice(0, 5)) {
+            lines.push(`- ${entry.sourceFamily} -> ${entry.affectedFamily}: ${entry.sharedDependency}`);
+        }
+    }
+    if (crew.findings.length > 0) {
+        lines.push('');
+        lines.push('Crew Findings:');
+        for (const finding of crew.findings.slice(0, 5)) {
+            lines.push(`- ${finding.severity} ${finding.type}: ${finding.summary}`);
+        }
+    }
+    if (crew.warnings.length > 0) {
+        lines.push('');
+        lines.push('Crew Warnings:');
+        for (const warning of crew.warnings.slice(0, 5)) {
+            lines.push(`- ${singleLine(warning)}`);
+        }
+    }
+    return lines.join('\n');
+}
+export function appendCrewToSummary(baseMarkdown, crew, plan) {
+    return `${baseMarkdown}\n\n---\n\n${buildCrewMarkdown(crew, plan)}`;
+}
+/**
+ * Build a full structured test plan as a Markdown document.
+ * Sections: gap flows first (P0 cases expanded), then covered-flow smoke tests.
+ */
+export function buildCrewTestPlan(crew, plan) {
+    const gapFamilies = new Set((plan?.gapDetails ?? []).map((g) => g.id));
+    const hasTestDesigns = crew.testDesigns.length > 0;
+    const totalCases = crew.testDesigns.reduce((n, td) => n + td.testCases.length, 0);
+    // Split strategy entries into gap-related and covered
+    const gapStrategies = gapFamilies.size > 0
+        ? crew.strategyEntries.filter((s) => matchesGapFamily(s.flowId, s.flowName, gapFamilies))
+        : [];
+    const coveredStrategies = crew.strategyEntries.filter((s) => !gapStrategies.includes(s));
+    // Split test designs (if present) into gap-related and covered
+    const gapDesigns = [];
+    const coveredDesigns = [];
+    for (const td of crew.testDesigns) {
+        if (matchesGapFamily(td.flowId, td.flowName, gapFamilies)) {
+            gapDesigns.push(td);
+        }
+        else {
+            coveredDesigns.push(td);
+        }
+    }
+    const gapCases = gapDesigns.reduce((n, td) => n + td.testCases.length, 0);
+    const coveredCases = coveredDesigns.reduce((n, td) => n + td.testCases.length, 0);
+    const lines = [
+        '# Crew Test Plan — What to Verify',
+        '',
+        '> **This is a test recommendation, not a test execution report.**',
+        '> Crew analyzed the code diff and identified what needs to be tested.',
+        '> Use this plan to guide manual QA or write automated E2E tests.',
+        '',
+        `_Auto-generated by impact-gate crew (\`${crew.workflow}\` workflow)_`,
+        '',
+        '## Summary',
+        '',
+        `| Metric | Count |`,
+        `|--------|-------|`,
+        `| Gap flows — **no existing tests, must verify** | ${gapStrategies.length} flows${hasTestDesigns ? `, **${gapCases} test cases**` : ''} |`,
+        `| Covered flows — **has tests, verify no regressions** | ${coveredStrategies.length} flows${hasTestDesigns ? `, ${coveredCases} test cases` : ''} |`,
+        `| Total | ${crew.strategyEntries.length} flows${hasTestDesigns ? `, ${totalCases} test cases` : ''} |`,
+        `| High-risk cross-impacts | ${crew.summary.highRiskCrossImpacts} |`,
+        `| AI cost | $${crew.summary.totalCostUSD.toFixed(4)} |`,
+        '',
+    ];
+    // ── Gap flows ──
+    if (gapStrategies.length > 0) {
+        lines.push('## Action Required: Gap Flows (No Existing Tests)');
+        lines.push('');
+        lines.push('These flows have **no automated E2E coverage**. Before merging, either:');
+        lines.push('1. **Write E2E tests** for the critical scenarios below, or');
+        lines.push('2. **Manually verify** each flow works as expected');
+        lines.push('');
+        for (const strategy of gapStrategies) {
+            const td = crew.testDesigns.find((d) => d.flowId === strategy.flowId);
+            lines.push(`### ${strategy.flowName}`);
+            lines.push('');
+            const actionVerb = strategy.approach === 'full-test' ? 'Write full E2E test or verify manually'
+                : strategy.approach === 'smoke-test' ? 'Smoke-test manually or add basic E2E coverage'
+                    : strategy.approach === 'manual-review' ? 'Manual review required'
+                        : 'Can skip — low risk';
+            lines.push(`**${strategy.priority}** | Recommended: **${strategy.approach}** | Cross-impact risk: **${strategy.crossImpactRisk}**`);
+            lines.push(`> ${actionVerb}`);
+            if (strategy.rationale && !strategy.rationale.includes('Default strategy')) {
+                lines.push(`> Rationale: ${strategy.rationale}`);
+            }
+            if (strategy.testCategories.length > 0) {
+                lines.push(`> Test types to cover: ${strategy.testCategories.join(', ')}`);
+            }
+            lines.push('');
+            // If test designs exist, show P0/P1 cases
+            if (td && td.testCases.length > 0) {
+                const p0Cases = td.testCases.filter((tc) => tc.priority === 'P0');
+                const p1Cases = td.testCases.filter((tc) => tc.priority === 'P1');
+                if (p0Cases.length > 0) {
+                    lines.push('**P0 — Must test:**');
+                    lines.push('');
+                    for (const tc of p0Cases) {
+                        lines.push(`- [ ] **${tc.name}** (${tc.type})`);
+                        if (tc.preconditions.length > 0) {
+                            lines.push(`  - Preconditions: ${tc.preconditions.join('; ')}`);
+                        }
+                        lines.push(`  - Steps: ${tc.steps.join(' → ')}`);
+                        lines.push(`  - Expected: ${tc.expectedOutcome}`);
+                    }
+                    lines.push('');
+                }
+                if (p1Cases.length > 0) {
+                    lines.push(`<details><summary>P1 — Should test (${p1Cases.length})</summary>`);
+                    lines.push('');
+                    for (const tc of p1Cases) {
+                        lines.push(`- [ ] **${tc.name}** (${tc.type}) — ${tc.expectedOutcome}`);
+                    }
+                    lines.push('');
+                    lines.push('</details>');
+                    lines.push('');
+                }
+            }
+        }
+    }
+    // ── Covered flows ──
+    if (coveredStrategies.length > 0) {
+        lines.push('## Regression Check: Covered Flows (Already Have Tests)');
+        lines.push('');
+        lines.push('These flows have existing E2E specs. The existing tests should catch regressions automatically.');
+        lines.push('**No manual action required** unless CI tests fail on these flows.');
+        lines.push('');
+        for (const strategy of coveredStrategies) {
+            const td = crew.testDesigns.find((d) => d.flowId === strategy.flowId);
+            const caseCount = td ? td.testCases.length : 0;
+            const detail = caseCount > 0 ? ` | ${caseCount} cases` : '';
+            lines.push(`<details><summary><strong>${strategy.flowName}</strong> — ${strategy.approach}${detail} (${strategy.priority})</summary>`);
+            lines.push('');
+            lines.push(`Existing tests should cover this. Cross-impact risk: ${strategy.crossImpactRisk}`);
+            if (strategy.rationale && !strategy.rationale.includes('Default strategy')) {
+                lines.push(`> ${strategy.rationale}`);
+            }
+            if (strategy.testCategories.length > 0) {
+                lines.push(`Test categories: ${strategy.testCategories.join(', ')}`);
+            }
+            if (td && td.testCases.length > 0) {
+                lines.push('');
+                for (const tc of td.testCases) {
+                    lines.push(`- [ ] **${tc.name}** (${tc.priority}, ${tc.type}) — ${tc.expectedOutcome}`);
+                }
+            }
+            lines.push('');
+            lines.push('</details>');
+            lines.push('');
+        }
+    }
+    // ── Cross-impacts ──
+    const highRisk = crew.crossImpacts.filter((ci) => ci.riskLevel === 'high');
+    if (highRisk.length > 0) {
+        lines.push('## High-Risk Cross-Impacts — Verify Before Release');
+        lines.push('');
+        lines.push('Changes in one area may break these related areas. Manually verify or ensure E2E tests cover both sides:');
+        lines.push('');
+        for (const ci of highRisk) {
+            lines.push(`- **${ci.sourceFamily}** → **${ci.affectedFamily}**: ${ci.sharedDependency}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+export function writeCrewArtifacts(reportRoot, crew, plan) {
+    const outputDir = join(reportRoot, '.e2e-ai-agents');
+    mkdirSync(outputDir, { recursive: true });
+    const crewSummaryPath = join(outputDir, 'crew-summary.json');
+    const crewMarkdownPath = join(outputDir, 'crew-summary.md');
+    const crewTestPlanPath = join(outputDir, 'crew-test-plan.md');
+    writeFileSync(crewSummaryPath, JSON.stringify(crew, null, 2), 'utf-8');
+    writeFileSync(crewMarkdownPath, buildCrewMarkdown(crew, plan), 'utf-8');
+    writeFileSync(crewTestPlanPath, buildCrewTestPlan(crew, plan), 'utf-8');
+    return { crewSummaryPath, crewMarkdownPath, crewTestPlanPath };
+}