playwright-intelligence-engine 2.0.0 → 2.0.2

package/src/cli/index.ts

@@ -1,1172 +1,1238 @@
-import * as path from 'node:path';
-import * as fs from 'node:fs';
-import { spawn, execSync } from 'node:child_process';
-import { ArchiveReader } from '../trace/archive-reader.js';
-import { TraceParser } from '../trace/trace-parser.js';
-import { EvidenceCorrelator } from '../diagnostics/evidence-correlator.js';
-import { DiagnosticReportGenerator } from '../diagnostics/diagnostic-report.js';
-import { McpServer } from '../mcp/server.js';
-import { TestGenerator } from '../generator/test-generator.js';
-import { DiagnosticRerunner } from '../reproduce/diagnostic-rerunner.js';
-import { ApprovalService } from '../repair/approval-service.js';
-import { WorkspacePromoter } from '../repair/workspace-promoter.js';
-import { getRuntimeProvenance, PACKAGE_VERSION } from '../core/version.js';
-import { inspectTestbed } from '../evaluation/repository-inspector.js';
-import { RepositoryRunner } from '../evaluation/repository-runner.js';
-import { initProjectConfig } from '../config/project-config.js';
-import { buildRepositoryProfile, writeRepositoryProfile } from '../intelligence/repository-profile.js';
-import { bootstrapProjectIntelligence, recordProjectFailure, recordProjectRepairAccepted, recordProjectRepairFeedback } from '../intelligence/project-intelligence.js';
-import { clusterFailures, FailureObservation } from '../intelligence/failure-clustering.js';
-import { analyzeTestStability, analyzeRepositoryImpact, TestRunObservation } from '../intelligence/suite-intelligence.js';
-import { planArchitecture, writeArchitecturePlan, ArchitectureMode, ArchitectureGenerationInput } from '../generator/architecture-generator.js';
-import { AppCrawler } from '../perception/crawler.js';
-import type { AppModel } from '../perception/app-model.js';
-import { ExecutionRunner } from '../sandbox/execution-runner.js';
-import { buildCiEvidenceReport } from '../integrations/playwright-report-adapter.js';
-import { buildSarifReport } from '../integrations/sarif-report.js';
-import { recordArchitectureWorkflow, recordCiWorkflow } from '../governance/workflow-audit.js';
-import { buildTeamDashboard, TeamEvidenceRun } from '../governance/team-dashboard.js';
-import { parseExternalFailureEvidence, supplementDiagnosticContext } from '../diagnostics/external-failure-evidence.js';
-import { runRepairWorkflow } from '../repair/repair-workflow.js';
-import { runAutonomousRepairWorkflow } from '../intelligence/autonomous-repair-workflow.js';
-import { normalizeFailureCategory } from '../diagnostics/failure-category.js';
-import { buildEvaluationScorecard, EvaluationObservation } from '../evaluation/evaluation-scorecard.js';
-import { buildTestIntelligencePlan, ExistingTestInput, RequirementInput } from '../intelligence/test-intelligence.js';
-import { runGenerationAgent } from '../intelligence/generation-agent.js';
-import { runEvidenceDrivenGeneration } from '../intelligence/generation-verifier.js';
-import { GitDiffCollector } from '../collectors/git-diff-collector.js';
-import type { AuthorKind } from '../authoring/index.js';
-
-export async function runCli(argv: string[]): Promise<void> {
-  const command = argv[2];
-
-  if (!command || command === '--help' || command === '-h') {
-    printHelp();
-    return;
-  }
-
-  if (command === '--version' || command === '-v') {
-    console.log(PACKAGE_VERSION);
-    return;
-  }
-
-  if (command === 'mcp') {
-    const server = new McpServer();
-    server.start();
-    return;
-  }
-
-  if (command === 'inspect-testbed') {
-    const testbedPath = argv[3];
-    if (!testbedPath) {
-      console.error('Error: testbed directory required. Usage: pw-intel inspect-testbed <directory> [--json] [--out <manifest.json>]');
-      process.exit(1);
-    }
-
-    try {
-      const manifests = await inspectTestbed(testbedPath);
-      const outputPathIndex = argv.indexOf('--out');
-      const outputPath = outputPathIndex >= 0 ? argv[outputPathIndex + 1] : undefined;
-      const serialized = JSON.stringify({ generatedAt: new Date().toISOString(), testbedPath, repositories: manifests }, null, 2);
-
-      if (outputPath) {
-        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
-        await fs.promises.writeFile(path.resolve(outputPath), serialized, 'utf8');
-      }
-
-      if (argv.includes('--json') || outputPath) {
-        console.log(serialized);
-      } else {
-        console.log(`Testbed: ${testbedPath}`);
-        for (const manifest of manifests) {
-          console.log(`- ${manifest.name}: ${manifest.status}; ${manifest.testFiles} test files; ${manifest.pageObjectFiles} Page Object files; ${manifest.packageManager}`);
-        }
-      }
-      return;
-    } catch (err: any) {
-      console.error(`Testbed inspection failed: ${err?.message ?? String(err)}`);
-      process.exit(1);
-    }
-  }
-
-  if (command === 'run-testbed') {
-    const testbedPath = argv[3];
-    if (!testbedPath) {
-      console.error('Error: testbed directory required. Usage: pw-intel run-testbed <directory> [--script <name>]');
-      process.exit(1);
-    }
-
-    try {
-      const manifests = await inspectTestbed(testbedPath);
-      const scriptIndex = argv.indexOf('--script');
-      const script = scriptIndex >= 0 ? argv[scriptIndex + 1] : undefined;
-      const repositoryIndex = argv.indexOf('--repository');
-      const repository = repositoryIndex >= 0 ? argv[repositoryIndex + 1] : undefined;
-      const timeoutIndex = argv.indexOf('--timeout');
-      const timeoutValue = timeoutIndex >= 0 ? Number(argv[timeoutIndex + 1]) : undefined;
-      if (timeoutValue !== undefined && (!Number.isFinite(timeoutValue) || timeoutValue <= 0)) {
-        throw new Error('--timeout must be a positive number of milliseconds');
-      }
-      const outputPathIndex = argv.indexOf('--out');
-      const outputPath = outputPathIndex >= 0 ? argv[outputPathIndex + 1] : undefined;
-      const selectedManifests = repository ? manifests.filter((manifest) => manifest.name === repository) : manifests;
-      if (repository && selectedManifests.length === 0) {
-        throw new Error(`Repository '${repository}' was not found in the testbed manifest`);
-      }
-      const results = [];
-      for (const manifest of selectedManifests) {
-        results.push(await RepositoryRunner.runBaseline(manifest, { script, timeoutMs: timeoutValue }));
-      }
-      const serialized = JSON.stringify({ generatedAt: new Date().toISOString(), testbedPath, results }, null, 2);
-      if (outputPath) {
-        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
-        await fs.promises.writeFile(path.resolve(outputPath), serialized, 'utf8');
-      }
-      console.log(serialized);
-      return;
-    } catch (err: any) {
-      console.error(`Testbed execution failed: ${err?.message ?? String(err)}`);
-      process.exit(1);
-    }
-  }
-
-  if (command === 'diagnose') {
-    const tracePath = argv[3];
-    if (!tracePath) {
-      console.error('Error: trace.zip path required. Usage: pw-intel diagnose <path-to-trace.zip> [--error-context <error-context.md>]');
-      process.exit(1);
-    }
-
-    try {
-        const { traceEntryName, networkEntryName, traceEntryNames, networkEntryNames } = ArchiveReader.findTraceFileEntries(tracePath);
-      if (!traceEntryName) {
-        throw new Error(`No .trace event stream found in archive '${tracePath}'`);
-      }
-
-        const traceText = await ArchiveReader.readEntriesAsText(tracePath, traceEntryNames ?? [traceEntryName]);
-        const networkText = (networkEntryNames ?? (networkEntryName ? [networkEntryName] : [])).length > 0
-          ? await ArchiveReader.readEntriesAsText(tracePath, networkEntryNames ?? [networkEntryName!])
-        : '';
-
-      const traceLines = traceText.split('\n');
-      const networkLines = networkText.split('\n');
-      let context = TraceParser.assembleDiagnosticContext(traceLines, networkLines);
-      const errorContextIndex = argv.indexOf('--error-context');
-      const errorContextPath = errorContextIndex >= 0 ? argv[errorContextIndex + 1] : undefined;
-      if (errorContextPath) {
-        const errorContext = await fs.promises.readFile(path.resolve(errorContextPath), 'utf8');
-        context = supplementDiagnosticContext(context, parseExternalFailureEvidence(errorContext));
-      }
-      const correlated = EvidenceCorrelator.correlate(context);
-      const intelligence = await bootstrapProjectIntelligence(process.cwd());
-      await recordProjectFailure(process.cwd(), context.failedAction.selector, correlated.classification.category);
-
-      if (argv.includes('--json')) {
-        const proposedLocator = DiagnosticReportGenerator.extractProposedLocator(correlated, intelligence);
-        const shouldAbstain = correlated.classification.shouldAbstain || !proposedLocator;
-        const actionOutcome = shouldAbstain ? 'ABSTAIN' : 'REPAIR';
-        const canonicalCategory = normalizeFailureCategory(correlated.classification.category);
-        const abstentionReason =
-          correlated.classification.abstentionReason ??
-          (!proposedLocator ? 'No safe, unique replacement locator candidate discovered in DOM snapshot.' : undefined);
-
-        console.log(JSON.stringify({
-          provenance: getRuntimeProvenance(process.cwd()),
-          classification: canonicalCategory,
-          rawClassification: correlated.classification.category,
-          confidence: correlated.classification.confidence,
-          shouldAbstain,
-          actionOutcome,
-          reason: correlated.classification.reason,
-          abstentionReason,
-          failedAction: correlated.context.failedAction,
-          failureFingerprint: correlated.failureFingerprint,
-          proposedLocator,
-        }, null, 2));
-        return;
-      }
-
-      const report = DiagnosticReportGenerator.generateTerminalReport(correlated, undefined, intelligence);
-
-      console.log(report);
-    } catch (err: any) {
-      console.error(`Diagnostic execution failed: ${err.message}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'repair') {
-    const tracePath = argv[3];
-    if (!tracePath) {
-      console.error('Error: trace.zip path required. Usage: pw-intel repair <trace.zip> --test <spec> --pom <page-object> --class <Class> --member <member> [--execute]');
-      process.exit(1);
-    }
-    try {
-      const option = (name: string): string | undefined => {
-        const index = argv.indexOf(name);
-        return index >= 0 ? argv[index + 1] : undefined;
-      };
-      const operationText = option('--operation');
-      const operation = operationText ? JSON.parse(operationText) as unknown : undefined;
-      const result = await runRepairWorkflow({
-        tracePath,
-        workspaceRoot: option('--workspace') ?? process.cwd(),
-        errorContextPath: option('--error-context'),
-        testFilePath: option('--test'),
-        pomFilePath: option('--pom'),
-        className: option('--class'),
-        memberName: option('--member'),
-        configPath: option('--config'),
-        project: option('--project'),
-        execute: argv.includes('--execute'),
-        worktreeId: option('--worktree-id'),
-        operation,
-      });
-      const canonicalClassification = {
-        ...result.correlated.classification,
-        category: normalizeFailureCategory(result.correlated.classification.category),
-      };
-      console.log(JSON.stringify({
-        provenance: getRuntimeProvenance(process.cwd()),
-        status: result.status,
-        classification: canonicalClassification,
-        failureFingerprint: result.correlated.failureFingerprint,
-        proposedLocator: result.proposedLocator,
-        candidate: result.candidate,
-        proposalId: result.stagedProposal?.proposalId,
-        worktree: result.worktree,
-        verification: result.verification,
-        reason: result.reason,
-      }, null, 2));
-      if (result.status === 'REJECTED') process.exitCode = 1;
-    } catch (err: any) {
-      console.error(`Repair workflow failed: ${err?.message ?? String(err)}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'autonomous-repair') {
-    const tracePath = argv[3];
-    if (!tracePath) {
-      console.error('Error: trace.zip path required. Usage: pw-intel autonomous-repair <trace.zip> [--execute] [--test <spec>] [--pom <page-object>] [--class <Class>] [--member <member>]');
-      process.exit(1);
-    }
-    try {
-      const option = (name: string): string | undefined => {
-        const index = argv.indexOf(name);
-        return index >= 0 ? argv[index + 1] : undefined;
-      };
-      const result = await runAutonomousRepairWorkflow({
-        tracePath,
-        workspaceRoot: option('--workspace') ?? process.cwd(),
-        errorContextPath: option('--error-context'),
-        testFilePath: option('--test'),
-        pomFilePath: option('--pom'),
-        className: option('--class'),
-        memberName: option('--member'),
-        configPath: option('--config'),
-        worktreeId: option('--worktree-id'),
-        enableBrowserInvestigation: argv.includes('--browser'),
-        browserUrl: option('--browser-url'),
-        browserAllowedHosts: (option('--allow-host') ?? '').split(',').map((host) => host.trim()).filter(Boolean),
-        enableTestExecution: argv.includes('--run-tests'),
-        autoPromote: argv.includes('--promote'),
-        execute: argv.includes('--execute'),
-      });
-      console.log(JSON.stringify({
-        provenance: getRuntimeProvenance(process.cwd()),
-        status: result.status,
-        reason: result.reason,
-        agent: {
-          state: result.proposalRun.agent.state,
-          modelInvoked: result.proposalRun.agent.modelInvoked,
-          classification: result.proposalRun.agent.classification,
-          proposal: result.proposal,
-          errors: result.proposalRun.agent.errors,
-          steps: result.proposalRun.agent.steps,
-        },
-        verification: result.verification,
-        promotion: result.promotion,
-      }, null, 2));
-      if (result.status === 'PROPOSAL_REJECTED' || result.status === 'VERIFICATION_FAILED') process.exitCode = 1;
-    } catch (err: any) {
-      console.error(`Autonomous repair failed: ${err?.message ?? String(err)}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'reproduce') {
-    const specFile = argv[3];
-    if (!specFile) {
-      console.error('Error: spec file path required. Usage: pw-intel reproduce <specFilePath>');
-      process.exit(1);
-    }
-
-    try {
-      const option = (name: string): string | undefined => {
-        const index = argv.indexOf(name);
-        return index >= 0 ? argv[index + 1] : undefined;
-      };
-      console.log(`Running diagnostic reproduction for '${specFile}'...`);
-      const result = await DiagnosticRerunner.rerunAndDiagnose({
-        specFilePath: specFile,
-        workspaceRoot: option('--workspace') ?? process.cwd(),
-      });
-
-      console.log(result.report);
-      if (!result.passed) {
-        process.exit(1);
-      }
-    } catch (err: any) {
-      console.error(`Reproduction execution failed: ${err.message}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'benchmark') {
-    // Resolve benchmark script from package directory first, falling back to process.cwd()
-    const cliDir = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1'));
-    const packageRootDir = path.resolve(cliDir, '..');
-    const packageBenchmarkScript = path.resolve(packageRootDir, 'benchmarks', 'runner', 'master-benchmark-runner.ts');
-    const localBenchmarkScript = path.resolve(process.cwd(), 'benchmarks', 'runner', 'master-benchmark-runner.ts');
-    const benchmarkScript = fs.existsSync(packageBenchmarkScript)
-      ? packageBenchmarkScript
-      : (fs.existsSync(localBenchmarkScript) ? localBenchmarkScript : undefined);
-
-    if (!benchmarkScript) {
-      console.log('Empirical benchmark harness is maintained in the research testbed repository.');
-      console.log('See docs/BENCHMARK.md for methodology, metrics, and empirical validation results.');
-      return;
-    }
-
-    // Locate tsx CLI entry point
-    const tsxCandidatePaths = [
-      path.resolve(packageRootDir, 'node_modules', 'tsx', 'dist', 'cli.mjs'),
-      path.resolve(process.cwd(), 'node_modules', 'tsx', 'dist', 'cli.mjs'),
-    ];
-    const tsxCli = tsxCandidatePaths.find((p) => fs.existsSync(p));
-
-    let executable: string;
-    let finalArgs: string[];
-
-    if (tsxCli) {
-      executable = process.execPath;
-      finalArgs = [tsxCli, benchmarkScript, ...argv.slice(3)];
-    } else {
-      executable = process.platform === 'win32' ? 'cmd.exe' : 'npx';
-      finalArgs = process.platform === 'win32'
-        ? ['/d', '/s', '/c', 'npx', 'tsx', benchmarkScript, ...argv.slice(3)]
-        : ['tsx', benchmarkScript, ...argv.slice(3)];
-    }
-
-    const child = spawn(executable, finalArgs, {
-      cwd: process.cwd(),
-      stdio: 'inherit',
-    });
-
-    child.on('close', (code) => {
-      process.exit(code ?? 0);
-    });
-    return;
-  }
-
-  if (command === 'doctor') {
-    await runDoctor();
-    return;
-  }
-
-  if (command === 'init') {
-    const workspaceRoot = argv[3] && !argv[3].startsWith('--') ? argv[3] : process.cwd();
-    try {
-      const option = (name: string): string | undefined => {
-        const index = argv.indexOf(name);
-        return index >= 0 ? argv[index + 1] : undefined;
-      };
-      const apiKeyArg = option('--api-key');
-      const modelArg = option('--model') ?? (apiKeyArg?.startsWith('sk-') ? 'gpt-4o' : 'deepseek-chat');
-      const endpointArg = option('--endpoint');
-
-      const result = await initProjectConfig(workspaceRoot, { force: argv.includes('--force') });
-
-      // Handle optional LLM configuration
-      if (apiKeyArg) {
-        const envPath = path.join(workspaceRoot, '.env');
-        const envLines = [
-          '# Playwright Intelligence Engine (PIE) Configuration',
-          `PIE_LLM_API_KEY=${apiKeyArg}`,
-          `PIE_LLM_MODEL=${modelArg}`,
-        ];
-        if (endpointArg) {
-          envLines.push(`PIE_LLM_ENDPOINT=${endpointArg}`);
-        } else if (apiKeyArg.startsWith('sk-proj-') || apiKeyArg.startsWith('sk-')) {
-          envLines.push('PIE_LLM_ENDPOINT=https://api.openai.com/v1/chat/completions');
-        }
-        await fs.promises.writeFile(envPath, `${envLines.join('\n')}\n`, 'utf8');
-
-        // Ensure .env is in .gitignore
-        const gitignorePath = path.join(workspaceRoot, '.gitignore');
-        try {
-          const gitignoreContent = await fs.promises.readFile(gitignorePath, 'utf8').catch(() => '');
-          if (!gitignoreContent.includes('.env')) {
-            await fs.promises.appendFile(gitignorePath, '\n.env\n', 'utf8');
-          }
-        } catch {}
-      }
-
-      const activeApiKey = apiKeyArg ?? process.env.PIE_LLM_API_KEY ?? process.env.OPENAI_API_KEY ?? process.env.DEEPSEEK_API_KEY;
-
-      if (argv.includes('--json')) {
-        console.log(JSON.stringify({ ...result, llmConfigured: Boolean(activeApiKey) }, null, 2));
-      } else {
-        console.log(`${result.created ? 'Created' : 'Found'} PIE project configuration: ${result.configPath}`);
-        console.log(`  Package manager : ${result.config.test.packageManager}`);
-        console.log(`  Test command    : ${result.config.test.command ?? 'not detected'}`);
-        console.log(`  Fail-closed     : ${result.config.diagnostics.failClosed ? 'enabled' : 'disabled'}`);
-        console.log(`  LLM Provider    : ${activeApiKey ? `configured (${apiKeyArg ? 'written to .env' : 'detected in environment'})` : 'not configured (100% offline deterministic mode)'}`);
-        if (!activeApiKey) {
-          console.log(`  Note            : Core diagnosis and repair are 100% offline. To enable AI test generation, run: pw-intel init --api-key <key>`);
-        }
-        console.log('\nQuickstart Commands:');
-        console.log('  Diagnose a trace   : pw-intel diagnose ./test-results/trace.zip');
-        console.log('  Repair a failure   : pw-intel autonomous-repair ./test-results/trace.zip --execute');
-        console.log('  Generate tests     : pw-intel generate-agent ./requirements.json --mode brownfield --write');
-      }
-    } catch (err: any) {
-      console.error(`PIE initialization failed: ${err?.message ?? String(err)}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'profile') {
-    const workspaceRoot = argv[3] && !argv[3].startsWith('--') ? argv[3] : process.cwd();
-    try {
-      const profile = await buildRepositoryProfile(workspaceRoot);
-      const outputIndex = argv.indexOf('--out');
-      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
-      if (outputPath) {
-        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
-        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(profile, null, 2)}\n`, 'utf8');
-      } else {
-        await writeRepositoryProfile(workspaceRoot, profile);
-      }
-      if (argv.includes('--json') || outputPath) console.log(JSON.stringify(profile, null, 2));
-      else {
-        console.log(`Repository profile generated for ${profile.repository.name}`);
-        console.log(`  Tests           : ${profile.structure.testFiles}`);
-        console.log(`  Page Objects    : ${profile.structure.pageObjectFiles}`);
-        console.log(`  Fixtures        : ${profile.structure.fixtureFiles}`);
-        console.log(`  Preferred loc.  : ${profile.locatorConventions.preferred}`);
-        console.log(`  Domain terms    : ${profile.domainTerms.slice(0, 10).join(', ') || 'none detected'}`);
-      }
-    } catch (err: any) {
-      console.error(`Repository profiling failed: ${err?.message ?? String(err)}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'cluster-failures') {
-    const inputPath = argv[3];
-    if (!inputPath) {
-      console.error('Error: input JSON path required. Usage: pw-intel cluster-failures <observations.json> [--out <report.json>]');
-      process.exit(1);
-    }
-    try {
-      const parsed = JSON.parse(await fs.promises.readFile(path.resolve(inputPath), 'utf8')) as { observations?: FailureObservation[] } | FailureObservation[];
-      const observations = Array.isArray(parsed) ? parsed : parsed.observations ?? [];
-      const clusters = clusterFailures(observations);
-      const report = {
-        generatedAt: new Date().toISOString(),
-        observationCount: observations.length,
-        clusterCount: clusters.length,
-        clusters,
-      };
-      const outputIndex = argv.indexOf('--out');
-      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
-      if (outputPath) {
-        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
-        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
-      }
-      console.log(JSON.stringify(report, null, 2));
-    } catch (err: any) {
-      console.error(`Failure clustering failed: ${err?.message ?? String(err)}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'evaluation-scorecard') {
-    const inputPath = argv[3];
-    if (!inputPath) {
-      console.error('Error: evaluation JSON path required. Usage: pw-intel evaluation-scorecard <results.json> [--out <scorecard.json>]');
-      process.exit(1);
-    }
-    try {
-      const parsed = JSON.parse(await fs.promises.readFile(path.resolve(inputPath), 'utf8')) as EvaluationObservation[] | { observations?: EvaluationObservation[]; diagnosisResults?: EvaluationObservation[] };
-      const observations = Array.isArray(parsed) ? parsed : parsed.observations ?? parsed.diagnosisResults ?? [];
-      const scorecard = buildEvaluationScorecard(observations);
-      const report = { generatedAt: new Date().toISOString(), inputPath: path.resolve(inputPath), ...scorecard };
-      const outputIndex = argv.indexOf('--out');
-      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
-      if (outputPath) {
-        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
-        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
-      }
-      console.log(JSON.stringify(report, null, 2));
-    } catch (err: any) {
-      console.error(`Evaluation scorecard failed: ${err?.message ?? String(err)}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'plan-test-intelligence') {
-    const requirementsPath = argv[3];
-    if (!requirementsPath) {
-      console.error('Error: requirements JSON path required. Usage: pw-intel plan-test-intelligence <requirements.json> [--tests <tests.json>] [--out <plan.json>]');
-      process.exit(1);
-    }
-    try {
-      const requirementsRaw = JSON.parse(await fs.promises.readFile(path.resolve(requirementsPath), 'utf8')) as RequirementInput[] | { requirements?: RequirementInput[] | string; title?: string; steps?: ArchitectureGenerationInput['steps']; baseUrl?: string; includeCi?: boolean };
-      const requirements = Array.isArray(requirementsRaw)
-        ? requirementsRaw
-        : Array.isArray(requirementsRaw.requirements)
-          ? requirementsRaw.requirements
-          : typeof requirementsRaw.requirements === 'string'
-            ? [{ id: 'requirement-1', title: requirementsRaw.title ?? requirementsRaw.requirements.slice(0, 100), description: requirementsRaw.requirements }]
-            : [];
-      if (requirements.length === 0) throw new Error('The requirements document contains no requirements');
-      const testsIndex = argv.indexOf('--tests');
-      const testsPath = testsIndex >= 0 ? argv[testsIndex + 1] : undefined;
-      let existingTests: ExistingTestInput[] = [];
-      if (testsPath) {
-        const testsRaw = JSON.parse(await fs.promises.readFile(path.resolve(testsPath), 'utf8')) as ExistingTestInput[] | { tests?: ExistingTestInput[] };
-        existingTests = Array.isArray(testsRaw) ? testsRaw : testsRaw.tests ?? [];
-      }
-      const plan = buildTestIntelligencePlan(requirements, existingTests);
-      const report = { generatedAt: new Date().toISOString(), requirementsPath: path.resolve(requirementsPath), testsPath: testsPath ? path.resolve(testsPath) : undefined, ...plan };
-      const outputIndex = argv.indexOf('--out');
-      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
-      if (outputPath) {
-        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
-        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
-      }
-      console.log(JSON.stringify(report, null, 2));
-    } catch (err: any) {
-      console.error(`Test intelligence planning failed: ${err?.message ?? String(err)}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'generate-agent') {
-    const requirementsPath = argv[3];
-    if (!requirementsPath) {
-      console.error('Error: requirements JSON path required. Usage: pw-intel generate-agent <requirements.json> [--mode greenfield|brownfield] [--tests <tests.json>] [--write]');
-      process.exit(1);
-    }
-    try {
-      const requirementsRaw = JSON.parse(await fs.promises.readFile(path.resolve(requirementsPath), 'utf8')) as RequirementInput[] | { requirements?: RequirementInput[] | string; title?: string; steps?: ArchitectureGenerationInput['steps']; baseUrl?: string; includeCi?: boolean };
-      const requirementsDocument = Array.isArray(requirementsRaw) ? undefined : requirementsRaw;
-      const requirements = Array.isArray(requirementsRaw)
-        ? requirementsRaw
-        : Array.isArray(requirementsRaw.requirements)
-          ? requirementsRaw.requirements
-          : typeof requirementsRaw.requirements === 'string'
-            ? [{ id: 'requirement-1', title: requirementsRaw.title ?? requirementsRaw.requirements.slice(0, 100), description: requirementsRaw.requirements }]
-            : [];
-      if (requirements.length === 0) throw new Error('The requirements document contains no requirements');
-      const testsIndex = argv.indexOf('--tests');
-      const testsPath = testsIndex >= 0 ? argv[testsIndex + 1] : undefined;
-      let existingTests: ExistingTestInput[] = [];
-      if (testsPath) {
-        const testsRaw = JSON.parse(await fs.promises.readFile(path.resolve(testsPath), 'utf8')) as ExistingTestInput[] | { tests?: ExistingTestInput[] };
-        existingTests = Array.isArray(testsRaw) ? testsRaw : testsRaw.tests ?? [];
-      }
-      const modeIndex = argv.indexOf('--mode');
-      const mode = (modeIndex >= 0 ? argv[modeIndex + 1] : 'brownfield') as 'greenfield' | 'brownfield';
-      if (mode !== 'greenfield' && mode !== 'brownfield') throw new Error("--mode must be 'greenfield' or 'brownfield'");
-      const baseUrlIndex = argv.indexOf('--base-url');
-      const baseUrl = baseUrlIndex >= 0 ? argv[baseUrlIndex + 1] : requirementsDocument?.baseUrl;
-      const authorArg = argv.find((arg) => arg.startsWith('--author='));
-      const authorIndex = argv.indexOf('--author');
-      const author = authorArg
-        ? (authorArg.slice('--author='.length) as 'template' | 'hybrid' | 'llm')
-        : authorIndex >= 0
-          ? (argv[authorIndex + 1] as 'template' | 'hybrid' | 'llm')
-          : 'hybrid';
-      const result = await runGenerationAgent({
-        requirements,
-        existingTests,
-        mode,
-        author,
-        workspaceRoot: (argv.indexOf('--workspace') >= 0 ? argv[argv.indexOf('--workspace') + 1] : undefined) ?? process.cwd(),
-        ...(baseUrl ? { baseUrl } : {}),
-        ...(requirementsDocument?.steps ? { suggestedSteps: requirementsDocument.steps } : {}),
-        ...(requirementsDocument?.includeCi !== undefined ? { includeCi: requirementsDocument.includeCi } : {}),
-        write: argv.includes('--write'),
-        verify: argv.includes('--verify'),
-      });
-      console.log(JSON.stringify({ generatedAt: new Date().toISOString(), requirementsPath: path.resolve(requirementsPath), ...result }, null, 2));
-      if (result.status === 'ABSTAINED' || result.status === 'MODEL_NOT_CONFIGURED' || result.status === 'NEEDS_INPUT' || result.status === 'VERIFICATION_FAILED' || result.status === 'AGENT_NO_PROGRESS') process.exitCode = 1;
-    } catch (err: any) {
-      console.error(`Generation agent failed: ${err?.message ?? String(err)}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'stability-feedback') {
-    const selector = argv[3];
-    const outcomeIndex = argv.indexOf('--outcome');
-    const outcome = outcomeIndex >= 0 ? argv[outcomeIndex + 1] : undefined;
-    if (!selector || (outcome !== 'accepted' && outcome !== 'rejected')) {
-      console.error('Error: selector and outcome are required. Usage: pw-intel stability-feedback <selector> --outcome accepted|rejected');
-      process.exit(1);
-    }
-    try {
-      await recordProjectRepairFeedback(process.cwd(), selector, outcome);
-      console.log(JSON.stringify({ selector, outcome, recorded: true }));
-    } catch (err: any) {
-      console.error(`Stability feedback failed: ${err?.message ?? String(err)}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'suite-health') {
-    const inputPath = argv[3];
-    if (!inputPath) {
-      console.error('Error: run-record JSON path required. Usage: pw-intel suite-health <runs.json> [--out <report.json>]');
-      process.exit(1);
-    }
-    try {
-      const parsed = JSON.parse(await fs.promises.readFile(path.resolve(inputPath), 'utf8')) as { runs?: TestRunObservation[] } | TestRunObservation[];
-      const runs = Array.isArray(parsed) ? parsed : parsed.runs ?? [];
-      const summaries = analyzeTestStability(runs);
-      const report = { generatedAt: new Date().toISOString(), runCount: runs.length, testCount: summaries.length, flakyTestCount: summaries.filter((summary) => summary.flaky).length, tests: summaries };
-      const outputIndex = argv.indexOf('--out');
-      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
-      if (outputPath) {
-        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
-        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
-      }
-      console.log(JSON.stringify(report, null, 2));
-    } catch (err: any) {
-      console.error(`Suite health analysis failed: ${err?.message ?? String(err)}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'team-dashboard') {
-    const inputPath = argv[3];
-    if (!inputPath) {
-      console.error('Error: team evidence JSON path required. Usage: pw-intel team-dashboard <evidence.json> [--out <report.json>]');
-      process.exit(1);
-    }
-    try {
-      const parsed = JSON.parse(await fs.promises.readFile(path.resolve(inputPath), 'utf8')) as { runs?: TeamEvidenceRun[] } | TeamEvidenceRun[];
-      const runs = Array.isArray(parsed) ? parsed : parsed.runs ?? [];
-      const report = buildTeamDashboard(runs);
-      const outputIndex = argv.indexOf('--out');
-      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
-      if (outputPath) {
-        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
-        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
-      }
-      console.log(JSON.stringify(report, null, 2));
-    } catch (err: any) {
-      console.error(`Team dashboard generation failed: ${err?.message ?? String(err)}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'impact') {
-    const changedPath = argv[3];
-    if (!changedPath) {
-      console.error('Error: changed-files JSON path required. Usage: pw-intel impact <changed-files.json> [--root <directory>] [--out <report.json>]');
-      process.exit(1);
-    }
-    try {
-      const parsed = JSON.parse(await fs.promises.readFile(path.resolve(changedPath), 'utf8')) as { changedFiles?: string[] } | string[];
-      const changedFiles = Array.isArray(parsed) ? parsed : parsed.changedFiles ?? [];
-      const rootIndex = argv.indexOf('--root');
-      const root = (rootIndex >= 0 ? argv[rootIndex + 1] : undefined) ?? process.cwd();
-      const report = await analyzeRepositoryImpact(root, changedFiles);
-      const outputIndex = argv.indexOf('--out');
-      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
-      if (outputPath) {
-        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
-        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
-      }
-      console.log(JSON.stringify(report, null, 2));
-    } catch (err: any) {
-      console.error(`Impact analysis failed: ${err?.message ?? String(err)}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'architect') {
-    const featureName = argv[3];
-    if (!featureName || featureName.startsWith('--')) {
-      console.error('Error: feature name required. Usage: pw-intel architect <featureName> [--mode greenfield|brownfield] [--baseUrl <url>] [--crawl] [--app-model <path>] [--requirements <json>] [--write] [--verify]');
-      process.exit(1);
-    }
-    try {
-      const modeIndex = argv.indexOf('--mode');
-      const mode = (modeIndex >= 0 ? argv[modeIndex + 1] : 'greenfield') as ArchitectureMode;
-      if (mode !== 'greenfield' && mode !== 'brownfield') throw new Error("--mode must be 'greenfield' or 'brownfield'");
-      const requirementsIndex = argv.indexOf('--requirements');
-      const requirementsPath = requirementsIndex >= 0 ? argv[requirementsIndex + 1] : undefined;
-      const requirements = requirementsPath
-        ? JSON.parse(await fs.promises.readFile(path.resolve(requirementsPath), 'utf8')) as Partial<ArchitectureGenerationInput>
-        : {};
-      const baseUrlIndex = argv.indexOf('--baseUrl');
-      const baseUrlFromArg = baseUrlIndex >= 0 ? argv[baseUrlIndex + 1] : undefined;
-      const baseUrl = baseUrlFromArg ?? requirements.baseUrl;
-
-      let appModel = requirements.appModel;
-      const appModelIndex = argv.indexOf('--app-model');
-      if (appModelIndex >= 0 && argv[appModelIndex + 1]) {
-        const modelPath = path.resolve(argv[appModelIndex + 1]!);
-        appModel = JSON.parse(await fs.promises.readFile(modelPath, 'utf8')) as AppModel;
-      } else if (baseUrl && (argv.includes('--crawl') || (!requirements.steps || requirements.steps.length === 0))) {
-        try {
-          appModel = await AppCrawler.crawl({ baseUrl });
-        } catch {
-          // Graceful fallback if live crawl cannot connect
-        }
-      }
-
-      const profile = mode === 'brownfield' ? await buildRepositoryProfile(process.cwd()) : undefined;
-      const plan = planArchitecture({
-        featureName,
-        mode,
-        profile,
-        baseUrl,
-        requirements: requirements.requirements,
-        steps: requirements.steps,
-        includeCi: requirements.includeCi,
-        appModel,
-      });
-      let writeResult;
-      if (argv.includes('--write')) writeResult = await writeArchitecturePlan(process.cwd(), plan);
-      let verification;
-      if (argv.includes('--verify') && writeResult && writeResult.written.length > 0) {
-        const spec = plan.files.find((file) => file.relativePath.endsWith('.spec.ts'));
-        if (spec) {
-          verification = await ExecutionRunner.run('npx', {
-            cwd: process.cwd(),
-            args: ['playwright', 'test', spec.relativePath, '--reporter=line'],
-            timeoutMs: 60_000,
-          });
-
-          // Falsifiability Prover (Mutation Verification)
-          if (verification.exitCode === 0) {
-            try {
-              const specFullPath = path.resolve(process.cwd(), spec.relativePath);
-              const originalContent = await fs.promises.readFile(specFullPath, 'utf8');
-              const mutatedContent = originalContent.replace(
-                /expect\(page\.getByText\(['"][^'"]+['"]\)\)/,
-                `expect(page.getByText('__UNMATCHED_FALSIFICATION_TARGET__'))`
-              );
-              if (mutatedContent !== originalContent) {
-                await fs.promises.writeFile(specFullPath, mutatedContent, 'utf8');
-                const mutatedRun = await ExecutionRunner.run('npx', {
-                  cwd: process.cwd(),
-                  args: ['playwright', 'test', spec.relativePath, '--reporter=line'],
-                  timeoutMs: 60_000,
-                });
-                await fs.promises.writeFile(specFullPath, originalContent, 'utf8');
-                (verification as any).falsifiable = mutatedRun.exitCode !== 0;
-              }
-            } catch {
-              // Non-fatal if mutation check cannot run
-            }
-          }
-        }
-      }
-      await recordArchitectureWorkflow(process.cwd(), plan, writeResult);
-      const report = { generatedAt: new Date().toISOString(), plan, writeResult, ...(verification ? { verification } : {}) };
-      const outputIndex = argv.indexOf('--out');
-      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
-      if (outputPath) {
-        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
-        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
-      }
-      console.log(JSON.stringify(report, null, 2));
-    } catch (err: any) {
-      console.error(`Architecture generation failed: ${err?.message ?? String(err)}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'qa') {
-    const featureName = argv[3] && !argv[3].startsWith('--') ? argv[3] : undefined;
-    const readFlag = (flag: string): string | undefined => {
-      const idx = argv.indexOf(flag);
-      return idx >= 0 && argv[idx + 1] && !argv[idx + 1]!.startsWith('--') ? argv[idx + 1] : undefined;
-    };
-    const workspaceRoot = path.resolve(readFlag('--workspace') ?? process.cwd());
-    const baseUrl = readFlag('--url') ?? readFlag('--base-url');
-    const requirementsPath = readFlag('--requirements');
-    const markdownPath = readFlag('--markdown');
-    const gherkinPath = readFlag('--gherkin');
-    const promptFlag = readFlag('--prompt');
-    const outArtifactDir = readFlag('--out-dir');
-    const storageStatePath = readFlag('--storage-state');
-    const authorFlag = readFlag('--author') as AuthorKind | undefined;
-    const author: AuthorKind | undefined = authorFlag === 'template' || authorFlag === 'hybrid' || authorFlag === 'llm' ? authorFlag : undefined;
-    const useDiff = argv.includes('--diff');
-    const write = !argv.includes('--no-write');
-    const verify = !argv.includes('--no-verify');
-    const runMutations = !argv.includes('--no-mutate');
-    const allowMutatingActions = argv.includes('--allow-mutating');
-
-    try {
-      let markdown = markdownPath ? await fs.promises.readFile(path.resolve(markdownPath), 'utf8') : undefined;
-      let jsonRequirements: unknown;
-      let prompt = promptFlag;
-      let featureText = gherkinPath ? await fs.promises.readFile(path.resolve(gherkinPath), 'utf8') : undefined;
-
-      if (requirementsPath) {
-        const resolvedReqPath = path.resolve(requirementsPath);
-        const rawReq = await fs.promises.readFile(resolvedReqPath, 'utf8');
-        if (resolvedReqPath.toLowerCase().endsWith('.json')) {
-          jsonRequirements = JSON.parse(rawReq);
-        } else if (resolvedReqPath.toLowerCase().endsWith('.feature')) {
-          featureText = featureText ?? rawReq;
-        } else {
-          markdown = markdown ?? rawReq;
-        }
-      }
-
-      if (!featureName && !markdown && !jsonRequirements && !featureText && !prompt && !useDiff) {
-        console.error(
-          'Usage: pw-intel qa <featureName> [--workspace <dir>] [--url <baseUrl>] [--requirements <path>] [--markdown <path>] [--gherkin <path>] [--prompt <text>] [--diff] [--author template|hybrid|llm] [--out-dir <dir>] [--storage-state <path>] [--allow-mutating] [--no-write] [--no-verify] [--no-mutate]',
-        );
-        process.exit(1);
-      }
-
-      let gitDiff: { changedFiles?: string[]; changedRoutes?: string[]; changedSymbols?: string[]; apiEndpoints?: string[]; validationHints?: string[] } | undefined;
-      if (useDiff) {
-        const collected = await new GitDiffCollector().collect({ workspaceRoot });
-        const payload = collected[0]?.payload as { changedFiles?: string[]; diffHints?: { changedRoutes?: string[]; changedSymbols?: string[]; apiEndpoints?: string[]; validationHints?: string[] } } | undefined;
-        if (payload?.changedFiles?.length) {
-          gitDiff = {
-            changedFiles: payload.changedFiles,
-            ...(payload.diffHints ?? {}),
-          };
-        }
-      }
-
-      const result = await runEvidenceDrivenGeneration({
-        workspaceRoot,
-        featureName,
-        baseUrl,
-        prompt,
-        markdown,
-        jsonRequirements,
-        featureText,
-        gitDiff,
-        author,
-        outArtifactDir,
-        storageStatePath,
-        allowMutatingActions,
-        write,
-        verify,
-        runMutations,
-      });
-
-      const outFlag = readFlag('--out');
-      if (outFlag) {
-        await fs.promises.mkdir(path.dirname(path.resolve(outFlag)), { recursive: true });
-        await fs.promises.writeFile(path.resolve(outFlag), `${JSON.stringify(result.qaReport, null, 2)}\n`, 'utf8');
-      }
-      console.log(JSON.stringify(result.qaReport, null, 2));
-    } catch (err: any) {
-      console.error(`QA pipeline failed: ${err?.message ?? String(err)}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'ci-report') {
-    const reportPath = argv[3];
-    if (!reportPath) {
-      console.error('Error: Playwright JSON report path required. Usage: pw-intel ci-report <playwright-report.json> [--repository <name>] [--out <report.json>]');
-      process.exit(1);
-    }
-    try {
-      const report = JSON.parse(await fs.promises.readFile(path.resolve(reportPath), 'utf8')) as unknown;
-      const repositoryIndex = argv.indexOf('--repository');
-      const repository = repositoryIndex >= 0 ? argv[repositoryIndex + 1] : undefined;
-      const evidence = buildCiEvidenceReport(report, { repository, runId: process.env.GITHUB_RUN_ID ?? process.env.CI_PIPELINE_ID });
-      await recordCiWorkflow(process.cwd(), evidence);
-      const outputIndex = argv.indexOf('--out');
-      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
-      if (outputPath) {
-        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
-        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(evidence, null, 2)}\n`, 'utf8');
-      }
-      const sarifIndex = argv.indexOf('--sarif-out');
-      const sarifPath = sarifIndex >= 0 ? argv[sarifIndex + 1] : undefined;
-      if (sarifPath) {
-        const sarif = buildSarifReport(evidence, PACKAGE_VERSION);
-        await fs.promises.mkdir(path.dirname(path.resolve(sarifPath)), { recursive: true });
-        await fs.promises.writeFile(path.resolve(sarifPath), `${JSON.stringify(sarif, null, 2)}\n`, 'utf8');
-      }
-      console.log(evidence.markdown);
-      for (const annotation of evidence.annotations) console.log(annotation);
-      if (evidence.qualityGate.status === 'FAIL') process.exitCode = 1;
-    } catch (err: any) {
-      console.error(`CI report ingestion failed: ${err?.message ?? String(err)}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'approve') {
-    const proposalId = argv[3];
-    if (!proposalId) {
-      console.error('Error: proposalId required. Usage: pw-intel approve <proposalId>');
-      process.exit(1);
-    }
-
-    const proposal = ApprovalService.getInstance().getProposal(proposalId);
-    if (!proposal) {
-      console.error(`Error: Proposal '${proposalId}' not found or expired.`);
-      process.exit(1);
-    }
-
-    console.log('========================================================================');
-    console.log(' PLAYWRIGHT INTELLIGENCE ENGINE — OPERATOR REPAIR APPROVAL');
-    console.log('========================================================================\n');
-    console.log(`Proposal ID      : ${proposal.proposalId}`);
-    console.log(`Target File      : ${proposal.targetFilePath}`);
-    console.log(`Target Class     : ${proposal.targetClassName}`);
-    console.log(`Target Member    : ${proposal.targetMemberName}`);
-    console.log(`Original Hash    : ${proposal.originalSourceHash.slice(0, 16)}...`);
-    console.log(`Patched Hash     : ${proposal.patchedSourceHash.slice(0, 16)}...`);
-    console.log(`Worktree Status  : ${proposal.worktreeExecutionVerified ? 'VERIFIED (Target test passed in isolated worktree)' : 'UNVERIFIED'}`);
-    console.log('\n--- Proposed Unified Diff ---');
-    console.log(proposal.fullDiff || '(No diff recorded)');
-    console.log('-----------------------------\n');
-
-    if (!proposal.worktreeExecutionVerified) {
-      console.error('Security Violation: Cannot authorize proposal. Worktree test execution was not verified.');
-      process.exit(1);
-    }
-
-    try {
-      const tokenPayload = ApprovalService.getInstance().authorizeProposal({ proposalId });
-      console.log('PROPOSAL AUTHORIZED.');
-      console.log(`Single-Use Approval Token: ${tokenPayload.tokenId}\n`);
-      console.log(`To atomically apply this patch to your workspace, run:`);
-      console.log(`  pw-intel promote --token ${tokenPayload.tokenId}\n`);
-    } catch (err: any) {
-      console.error(`Authorization failed: ${err.message}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (command === 'promote') {
-    const tokenIndex = argv.indexOf('--token');
-    const token = tokenIndex !== -1 ? argv[tokenIndex + 1] : undefined;
-    if (!token) {
-      console.error('Error: --token argument required. Usage: pw-intel promote --token <approvalToken>');
-      process.exit(1);
-    }
-
-    const tokenPayload = ApprovalService.getInstance().getTokenPayload(token);
-    if (!tokenPayload) {
-      console.error(`Error: Invalid or expired approval token '${token}'.`);
-      process.exit(1);
-    }
-
-    const proposal = ApprovalService.getInstance().getProposal(tokenPayload.proposalId);
-    if (!proposal) {
-      console.error(`Error: Staged proposal '${tokenPayload.proposalId}' no longer available.`);
-      process.exit(1);
-    }
-
-    console.log(`Applying authorized repair to '${tokenPayload.targetFilePath}'...`);
-    const promoResult = await WorkspacePromoter.promote({
-      targetFilePath: tokenPayload.targetFilePath,
-      workspaceRoot: process.cwd(),
-      patchedContent: proposal.patchedSource,
-      approvalTokenPayload: tokenPayload,
-    });
-
-    if (!promoResult.success) {
-      console.error(`Promotion failed: ${promoResult.error}`);
-      process.exit(1);
-    }
-
-    await recordProjectRepairAccepted(process.cwd(), proposal.replacementSelector).catch(() => {});
-
-    console.log(`Successfully promoted verified repair!`);
-    console.log(`Target File   : ${promoResult.targetFilePath}`);
-    console.log(`Bytes Written : ${promoResult.bytesWritten}`);
-    console.log(`Final Hash    : ${promoResult.finalHash.slice(0, 16)}...`);
-    return;
-  }
-
-  if (command === 'generate') {
-    const featureName = argv[3] ?? 'Dashboard';
-    const suite = TestGenerator.generateSuite(featureName, [
-      { action: 'fill', name: 'Search', value: 'query' },
-      { action: 'click', role: 'button', name: 'Submit' },
-      { action: 'assert-visible', role: 'heading', name: 'Results' },
-    ]);
-
-    console.log(`Generated Page Object (${suite.pageObjectName}.ts):`);
-    console.log(suite.pageObjectCode);
-    console.log('─────────────────────────────────────────────────────────────────');
-    console.log(`Generated Spec:`);
-    console.log(suite.specCode);
-    return;
-  }
-
-  console.error(`Unknown command: ${command}`);
-  printHelp();
-  process.exit(1);
-}
-
-async function runDoctor(): Promise<void> {
-  console.log('Running Playwright Intelligence Engine Diagnostic Healthcheck (pw-intel doctor)...\n');
-  let healthy = true;
-
-  // 1. Node.js version
-  const nodeVer = process.versions.node;
-  const major = parseInt(nodeVer.split('.')[0] || '0', 10);
-  if (major >= 20) {
-    console.log(`  ✓ Node.js Runtime     : v${nodeVer} (Supported >= 20.0.0)`);
-  } else {
-    console.log(`  ✗ Node.js Runtime     : v${nodeVer} (Unsupported, requires Node >= 20.0.0)`);
-    healthy = false;
-  }
-
-  // 2. Git CLI availability
-  try {
-    const gitVer = execSync('git --version', { encoding: 'utf-8' }).trim();
-    console.log(`  ✓ Git Version Control : ${gitVer}`);
-  } catch {
-    console.log(`  ✗ Git Version Control : Not found in PATH (Required for isolated worktrees)`);
-    healthy = false;
-  }
-
-  // 3. Playwright availability
-  let pwFound = false;
-  try {
-    const cwdPkg = path.resolve(process.cwd(), 'package.json');
-    if (fs.existsSync(cwdPkg)) {
-      const pkg = JSON.parse(fs.readFileSync(cwdPkg, 'utf-8'));
-      const pwVer = pkg.devDependencies?.['@playwright/test'] || pkg.dependencies?.['@playwright/test'];
-      if (pwVer) {
-        console.log(`  ✓ Playwright Test     : ${pwVer} (Found in package.json)`);
-        pwFound = true;
-      }
-    }
-  } catch {}
-  if (!pwFound) {
-    try {
-      const pwCliVer = execSync('npx --no-install playwright --version', {
-        encoding: 'utf-8',
-        timeout: 4000,
-        stdio: ['ignore', 'pipe', 'ignore'],
-      }).trim();
-      console.log(`  ✓ Playwright CLI      : ${pwCliVer}`);
-      pwFound = true;
-    } catch {
-      console.log(`  ! Playwright Test     : Not detected in current working directory (Optional for offline trace analysis)`);
-    }
-  }
-
-  // 4. Workspace write access
-  try {
-    fs.accessSync(process.cwd(), fs.constants.W_OK);
-    console.log(`  ✓ Workspace Access    : Read/Write verified for '${process.cwd()}'`);
-  } catch {
-    console.log(`  ✗ Workspace Access    : Permission denied writing to '${process.cwd()}'`);
-    healthy = false;
-  }
-
-  // 5. Host platform info
-  console.log(`  ✓ Host Platform       : ${process.platform} (${process.arch})`);
-
-  // 6. Optional LLM status
-  const apiKey = process.env.PIE_LLM_API_KEY ?? process.env.OPENAI_API_KEY ?? process.env.DEEPSEEK_API_KEY;
-  if (apiKey) {
-    console.log(`  ✓ LLM Provider        : Configured (AI test generation enabled)`);
-  } else {
-    console.log(`  ℹ LLM Provider        : None configured (100% offline deterministic mode active; run 'pw-intel init --api-key <key>' to enable AI generation)`);
-  }
-
-  console.log('\nHealthcheck Verdict: ' + (healthy ? 'HEALTHY (Ready for diagnostic and repair workflows)' : 'DEGRADED (Check failed items above)'));
-  if (!healthy) {
-    process.exit(1);
-  }
-}
-
-function printHelp(): void {
-  console.log(`
-Playwright Intelligence Engine CLI (pw-intel)
-
-Usage:
-  pw-intel init [dir] [--api-key <k>] [--model <m>] Initializes PIE config & optional LLM credentials
-  pw-intel profile [directory]   Builds the project repository convention profile
-  pw-intel cluster-failures <json> Groups failure observations by deterministic fingerprints
-  pw-intel evaluation-scorecard <json> Reconciles expected/predicted categories, repairs, abstentions, and latency
-  pw-intel plan-test-intelligence <requirements.json> Plans coverage, missing scenarios, and duplicate tests
-  pw-intel generate-agent <requirements.json> Uses structured LLM planning, then deterministic Playwright generation
-                                   --mode greenfield|brownfield --tests <tests.json> --base-url <url> --write --verify
-  pw-intel stability-feedback <selector> --outcome accepted|rejected Records operator repair feedback
-  pw-intel suite-health <json>    Calculates flaky-test and duration summaries
-  pw-intel team-dashboard <json> Aggregates repository CI evidence into a team dashboard
-  pw-intel impact <json>         Selects impacted tests from changed files and repository imports
-  pw-intel architect <featureName> Plans greenfield/brownfield Playwright architecture; add --write to create missing files
-  pw-intel qa <featureName>         Runs 4-phase evidence-driven QA workflow (plan, explore, generate, verify & falsify)
-                                   --workspace <dir> --url <baseUrl> --requirements <path> --gherkin <path> --diff --author template|hybrid|llm --out-dir <dir>
-  pw-intel ci-report <playwright-report.json> Ingests Playwright JSON and emits clusters, stability, gate, and CI annotations
-                                   --sarif-out <file> writes GitHub/code-scanning SARIF output
-  pw-intel doctor                   Inspects host environment, Node, Git, Playwright & workspace readiness
-  pw-intel diagnose <trace.zip>     Diagnoses a Playwright trace archive and outputs root cause
-                                   --error-context <file> supplements traces with Playwright error-context.md
-  pw-intel repair <trace.zip>       Creates a proposal; add --execute for isolated verification
-                                   --test <spec> --pom <page-object> --class <Class> --member <member>
-                                   --config <playwright.config> --error-context <file> --worktree-id <id>
-                                   --operation <JSON> for an allowlisted frame/shadow/locator operation
-  pw-intel autonomous-repair <trace.zip> Runs the bounded LLM agent and deterministic isolated verifier
-                                   --execute applies the proposal only in a disposable worktree
-                                   --browser --browser-url <url> --allow-host <hostname[,hostname]>
-                                   --run-tests allows the agent to run an explicitly requested target test
-                                   --promote promotes only an independently verified repair; implies execution
-  pw-intel reproduce <spec.ts>      Reruns a failing test with live multi-source diagnostic instrumentation
-  pw-intel inspect-testbed <dir>    Inspects external Playwright repositories and emits a reproducible manifest
-  pw-intel run-testbed <dir>       Runs bounded baseline commands for discovered repositories
-                                   --repository <name> --script <name> --timeout <ms> --out <file>
-  pw-intel approve <proposalId>     Human review and cryptographic authorization of staged repair proposal
-  pw-intel promote --token <token>  Atomically applies authorized repair proposal to active workspace
-  pw-intel benchmark [options]      Executes empirical real browser benchmark suite against Controlled App Server
-  pw-intel mcp                      Starts the Model Context Protocol (MCP) JSON-RPC server on stdio
-  pw-intel generate <featureName>   Generates verified Page Object and Spec scaffolding
-  pw-intel --help                   Shows this help message
-
-Benchmark Options:
-  --family <name>                   Filter mutation scenarios by family name (e.g. "Dynamic IDs")
-  --scenario <id>                   Filter negative control scenarios by category or name
-  --browser <browser>               Target browser (default: chromium)
-`);
-}
-
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { spawn, execSync } from 'node:child_process';
+import { ArchiveReader } from '../trace/archive-reader.js';
+import { TraceParser } from '../trace/trace-parser.js';
+import { EvidenceCorrelator } from '../diagnostics/evidence-correlator.js';
+import { DiagnosticReportGenerator } from '../diagnostics/diagnostic-report.js';
+import { McpServer } from '../mcp/server.js';
+import { TestGenerator } from '../generator/test-generator.js';
+import { DiagnosticRerunner } from '../reproduce/diagnostic-rerunner.js';
+import { ApprovalService } from '../repair/approval-service.js';
+import { WorkspacePromoter } from '../repair/workspace-promoter.js';
+import { getRuntimeProvenance, PACKAGE_VERSION } from '../core/version.js';
+import { inspectTestbed } from '../evaluation/repository-inspector.js';
+import { RepositoryRunner } from '../evaluation/repository-runner.js';
+import { initProjectConfig } from '../config/project-config.js';
+import { buildRepositoryProfile, writeRepositoryProfile } from '../intelligence/repository-profile.js';
+import { bootstrapProjectIntelligence, recordProjectFailure, recordProjectRepairAccepted, recordProjectRepairFeedback } from '../intelligence/project-intelligence.js';
+import { clusterFailures, FailureObservation } from '../intelligence/failure-clustering.js';
+import { analyzeTestStability, analyzeRepositoryImpact, TestRunObservation } from '../intelligence/suite-intelligence.js';
+import { planArchitecture, writeArchitecturePlan, ArchitectureMode, ArchitectureGenerationInput } from '../generator/architecture-generator.js';
+import { AppCrawler } from '../perception/crawler.js';
+import type { AppModel } from '../perception/app-model.js';
+import { ExecutionRunner } from '../sandbox/execution-runner.js';
+import { buildCiEvidenceReport } from '../integrations/playwright-report-adapter.js';
+import { buildSarifReport } from '../integrations/sarif-report.js';
+import { recordArchitectureWorkflow, recordCiWorkflow } from '../governance/workflow-audit.js';
+import { buildTeamDashboard, TeamEvidenceRun } from '../governance/team-dashboard.js';
+import { parseExternalFailureEvidence, supplementDiagnosticContext } from '../diagnostics/external-failure-evidence.js';
+import { runRepairWorkflow } from '../repair/repair-workflow.js';
+import { runAutonomousRepairWorkflow } from '../intelligence/autonomous-repair-workflow.js';
+import { normalizeFailureCategory } from '../diagnostics/failure-category.js';
+import { buildEvaluationScorecard, EvaluationObservation } from '../evaluation/evaluation-scorecard.js';
+import { buildTestIntelligencePlan, ExistingTestInput, RequirementInput } from '../intelligence/test-intelligence.js';
+import { runGenerationAgent } from '../intelligence/generation-agent.js';
+import { runEvidenceDrivenGeneration } from '../intelligence/generation-verifier.js';
+import { GitDiffCollector } from '../collectors/git-diff-collector.js';
+import type { AuthorKind } from '../authoring/index.js';
+
+function findTraceArchives(targetPath?: string): string[] {
+  if (targetPath && !targetPath.startsWith('--')) {
+    const resolved = path.resolve(targetPath);
+    if (fs.existsSync(resolved)) {
+      if (fs.statSync(resolved).isFile() && resolved.endsWith('.zip')) {
+        return [resolved];
+      }
+    }
+  }
+
+  const candidateDirs = [
+    targetPath && !targetPath.startsWith('--') && fs.existsSync(targetPath) && fs.statSync(targetPath).isDirectory()
+      ? path.resolve(targetPath)
+      : null,
+    path.resolve('test-results'),
+    path.resolve('playwright-report'),
+    process.cwd(),
+  ].filter(Boolean) as string[];
+
+  const found: { filePath: string; mtime: number }[] = [];
+  const seen = new Set<string>();
+
+  for (const dir of candidateDirs) {
+    if (!fs.existsSync(dir)) continue;
+    try {
+      const entries = fs.readdirSync(dir, { recursive: true });
+      for (const entry of entries) {
+        const fullPath = path.join(dir, String(entry));
+        if (fullPath.endsWith('.zip') && !seen.has(fullPath)) {
+          try {
+            const stat = fs.statSync(fullPath);
+            if (stat.isFile()) {
+              seen.add(fullPath);
+              found.push({ filePath: fullPath, mtime: stat.mtimeMs });
+            }
+          } catch {}
+        }
+      }
+    } catch {}
+  }
+
+  return found.sort((a, b) => b.mtime - a.mtime).map((f) => f.filePath);
+}
+
+export async function runCli(argv: string[]): Promise<void> {
+  const command = argv[2];
+
+  if (!command || command === '--help' || command === '-h') {
+    printHelp();
+    return;
+  }
+
+  if (command === '--version' || command === '-v') {
+    console.log(PACKAGE_VERSION);
+    return;
+  }
+
+  if (command === 'mcp') {
+    const server = new McpServer();
+    server.start();
+    return;
+  }
+
+  if (command === 'inspect-testbed') {
+    const testbedPath = argv[3];
+    if (!testbedPath) {
+      console.error('Error: testbed directory required. Usage: pw-intel inspect-testbed <directory> [--json] [--out <manifest.json>]');
+      process.exit(1);
+    }
+
+    try {
+      const manifests = await inspectTestbed(testbedPath);
+      const outputPathIndex = argv.indexOf('--out');
+      const outputPath = outputPathIndex >= 0 ? argv[outputPathIndex + 1] : undefined;
+      const serialized = JSON.stringify({ generatedAt: new Date().toISOString(), testbedPath, repositories: manifests }, null, 2);
+
+      if (outputPath) {
+        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+        await fs.promises.writeFile(path.resolve(outputPath), serialized, 'utf8');
+      }
+
+      if (argv.includes('--json') || outputPath) {
+        console.log(serialized);
+      } else {
+        console.log(`Testbed: ${testbedPath}`);
+        for (const manifest of manifests) {
+          console.log(`- ${manifest.name}: ${manifest.status}; ${manifest.testFiles} test files; ${manifest.pageObjectFiles} Page Object files; ${manifest.packageManager}`);
+        }
+      }
+      return;
+    } catch (err: any) {
+      console.error(`Testbed inspection failed: ${err?.message ?? String(err)}`);
+      process.exit(1);
+    }
+  }
+
+  if (command === 'run-testbed') {
+    const testbedPath = argv[3];
+    if (!testbedPath) {
+      console.error('Error: testbed directory required. Usage: pw-intel run-testbed <directory> [--script <name>]');
+      process.exit(1);
+    }
+
+    try {
+      const manifests = await inspectTestbed(testbedPath);
+      const scriptIndex = argv.indexOf('--script');
+      const script = scriptIndex >= 0 ? argv[scriptIndex + 1] : undefined;
+      const repositoryIndex = argv.indexOf('--repository');
+      const repository = repositoryIndex >= 0 ? argv[repositoryIndex + 1] : undefined;
+      const timeoutIndex = argv.indexOf('--timeout');
+      const timeoutValue = timeoutIndex >= 0 ? Number(argv[timeoutIndex + 1]) : undefined;
+      if (timeoutValue !== undefined && (!Number.isFinite(timeoutValue) || timeoutValue <= 0)) {
+        throw new Error('--timeout must be a positive number of milliseconds');
+      }
+      const outputPathIndex = argv.indexOf('--out');
+      const outputPath = outputPathIndex >= 0 ? argv[outputPathIndex + 1] : undefined;
+      const selectedManifests = repository ? manifests.filter((manifest) => manifest.name === repository) : manifests;
+      if (repository && selectedManifests.length === 0) {
+        throw new Error(`Repository '${repository}' was not found in the testbed manifest`);
+      }
+      const results = [];
+      for (const manifest of selectedManifests) {
+        results.push(await RepositoryRunner.runBaseline(manifest, { script, timeoutMs: timeoutValue }));
+      }
+      const serialized = JSON.stringify({ generatedAt: new Date().toISOString(), testbedPath, results }, null, 2);
+      if (outputPath) {
+        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+        await fs.promises.writeFile(path.resolve(outputPath), serialized, 'utf8');
+      }
+      console.log(serialized);
+      return;
+    } catch (err: any) {
+      console.error(`Testbed execution failed: ${err?.message ?? String(err)}`);
+      process.exit(1);
+    }
+  }
+
+  if (command === 'diagnose') {
+    const candidateArg = argv[3];
+    const traces = findTraceArchives(candidateArg);
+    if (traces.length === 0) {
+      console.error(
+        'Error: No trace.zip files found in test-results/ or current directory.\n' +
+        'Please run your Playwright tests with tracing enabled: npx playwright test --trace on\n' +
+        'Or pass the path directly: pw-intel diagnose <path-to-trace.zip>'
+      );
+      process.exit(1);
+    }
+    const tracePath = traces[0]!;
+    if (traces.length > 1) {
+      console.log(`[pw-intel] Auto-discovered ${traces.length} trace files. Diagnosing most recent: ${path.relative(process.cwd(), tracePath)}`);
+    } else if (!candidateArg || candidateArg.startsWith('--') || (fs.existsSync(candidateArg) && fs.statSync(candidateArg).isDirectory())) {
+      console.log(`[pw-intel] Auto-discovered trace: ${path.relative(process.cwd(), tracePath)}`);
+    }
+
+    try {
+        const { traceEntryName, networkEntryName, traceEntryNames, networkEntryNames } = ArchiveReader.findTraceFileEntries(tracePath);
+      if (!traceEntryName) {
+        throw new Error(`No .trace event stream found in archive '${tracePath}'`);
+      }
+
+        const traceText = await ArchiveReader.readEntriesAsText(tracePath, traceEntryNames ?? [traceEntryName]);
+        const networkText = (networkEntryNames ?? (networkEntryName ? [networkEntryName] : [])).length > 0
+          ? await ArchiveReader.readEntriesAsText(tracePath, networkEntryNames ?? [networkEntryName!])
+        : '';
+
+      const traceLines = traceText.split('\n');
+      const networkLines = networkText.split('\n');
+      let context = TraceParser.assembleDiagnosticContext(traceLines, networkLines);
+      const errorContextIndex = argv.indexOf('--error-context');
+      const errorContextPath = errorContextIndex >= 0 ? argv[errorContextIndex + 1] : undefined;
+      if (errorContextPath) {
+        const errorContext = await fs.promises.readFile(path.resolve(errorContextPath), 'utf8');
+        context = supplementDiagnosticContext(context, parseExternalFailureEvidence(errorContext));
+      }
+      const correlated = EvidenceCorrelator.correlate(context);
+      const intelligence = await bootstrapProjectIntelligence(process.cwd());
+      await recordProjectFailure(process.cwd(), context.failedAction.selector, correlated.classification.category);
+
+      if (argv.includes('--json')) {
+        const proposedLocator = DiagnosticReportGenerator.extractProposedLocator(correlated, intelligence);
+        const shouldAbstain = correlated.classification.shouldAbstain || !proposedLocator;
+        const actionOutcome = shouldAbstain ? 'ABSTAIN' : 'REPAIR';
+        const canonicalCategory = normalizeFailureCategory(correlated.classification.category);
+        const abstentionReason =
+          correlated.classification.abstentionReason ??
+          (!proposedLocator ? 'No safe, unique replacement locator candidate discovered in DOM snapshot.' : undefined);
+
+        console.log(JSON.stringify({
+          provenance: getRuntimeProvenance(process.cwd()),
+          classification: canonicalCategory,
+          rawClassification: correlated.classification.category,
+          confidence: correlated.classification.confidence,
+          shouldAbstain,
+          actionOutcome,
+          reason: correlated.classification.reason,
+          abstentionReason,
+          failedAction: correlated.context.failedAction,
+          failureFingerprint: correlated.failureFingerprint,
+          proposedLocator,
+        }, null, 2));
+        return;
+      }
+
+      const report = DiagnosticReportGenerator.generateTerminalReport(correlated, undefined, intelligence);
+
+      console.log(report);
+    } catch (err: any) {
+      console.error(`Diagnostic execution failed: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'repair') {
+    const tracePath = argv[3];
+    if (!tracePath) {
+      console.error('Error: trace.zip path required. Usage: pw-intel repair <trace.zip> --test <spec> --pom <page-object> --class <Class> --member <member> [--execute]');
+      process.exit(1);
+    }
+    try {
+      const option = (name: string): string | undefined => {
+        const index = argv.indexOf(name);
+        return index >= 0 ? argv[index + 1] : undefined;
+      };
+      const operationText = option('--operation');
+      const operation = operationText ? JSON.parse(operationText) as unknown : undefined;
+      const result = await runRepairWorkflow({
+        tracePath,
+        workspaceRoot: option('--workspace') ?? process.cwd(),
+        errorContextPath: option('--error-context'),
+        testFilePath: option('--test'),
+        pomFilePath: option('--pom'),
+        className: option('--class'),
+        memberName: option('--member'),
+        configPath: option('--config'),
+        project: option('--project'),
+        execute: argv.includes('--execute'),
+        worktreeId: option('--worktree-id'),
+        operation,
+      });
+      const canonicalClassification = {
+        ...result.correlated.classification,
+        category: normalizeFailureCategory(result.correlated.classification.category),
+      };
+      console.log(JSON.stringify({
+        provenance: getRuntimeProvenance(process.cwd()),
+        status: result.status,
+        classification: canonicalClassification,
+        failureFingerprint: result.correlated.failureFingerprint,
+        proposedLocator: result.proposedLocator,
+        candidate: result.candidate,
+        proposalId: result.stagedProposal?.proposalId,
+        worktree: result.worktree,
+        verification: result.verification,
+        reason: result.reason,
+      }, null, 2));
+      if (result.status === 'REJECTED') process.exitCode = 1;
+    } catch (err: any) {
+      console.error(`Repair workflow failed: ${err?.message ?? String(err)}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'autonomous-repair') {
+    const candidateArg = argv[3];
+    const traces = findTraceArchives(candidateArg);
+    if (traces.length === 0) {
+      console.error(
+        'Error: No trace.zip files found in test-results/ or current directory.\n' +
+        'Please run your Playwright tests with tracing enabled: npx playwright test --trace on\n' +
+        'Or pass the path directly: pw-intel autonomous-repair <trace.zip> [--execute]'
+      );
+      process.exit(1);
+    }
+    const tracePath = traces[0]!;
+    if (traces.length > 1) {
+      console.log(`[pw-intel] Auto-discovered ${traces.length} trace files. Repairing most recent: ${path.relative(process.cwd(), tracePath)}`);
+    } else if (!candidateArg || candidateArg.startsWith('--') || (fs.existsSync(candidateArg) && fs.statSync(candidateArg).isDirectory())) {
+      console.log(`[pw-intel] Auto-discovered trace: ${path.relative(process.cwd(), tracePath)}`);
+    }
+    try {
+      const option = (name: string): string | undefined => {
+        const index = argv.indexOf(name);
+        return index >= 0 ? argv[index + 1] : undefined;
+      };
+      const result = await runAutonomousRepairWorkflow({
+        tracePath,
+        workspaceRoot: option('--workspace') ?? process.cwd(),
+        errorContextPath: option('--error-context'),
+        testFilePath: option('--test'),
+        pomFilePath: option('--pom'),
+        className: option('--class'),
+        memberName: option('--member'),
+        configPath: option('--config'),
+        worktreeId: option('--worktree-id'),
+        enableBrowserInvestigation: argv.includes('--browser'),
+        browserUrl: option('--browser-url'),
+        browserAllowedHosts: (option('--allow-host') ?? '').split(',').map((host) => host.trim()).filter(Boolean),
+        enableTestExecution: argv.includes('--run-tests'),
+        autoPromote: argv.includes('--promote'),
+        execute: argv.includes('--execute'),
+      });
+      console.log(JSON.stringify({
+        provenance: getRuntimeProvenance(process.cwd()),
+        status: result.status,
+        reason: result.reason,
+        agent: {
+          state: result.proposalRun.agent.state,
+          modelInvoked: result.proposalRun.agent.modelInvoked,
+          classification: result.proposalRun.agent.classification,
+          proposal: result.proposal,
+          errors: result.proposalRun.agent.errors,
+          steps: result.proposalRun.agent.steps,
+        },
+        verification: result.verification,
+        promotion: result.promotion,
+      }, null, 2));
+      if (result.status === 'PROPOSAL_REJECTED' || result.status === 'VERIFICATION_FAILED') process.exitCode = 1;
+    } catch (err: any) {
+      console.error(`Autonomous repair failed: ${err?.message ?? String(err)}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'reproduce') {
+    const specFile = argv[3];
+    if (!specFile) {
+      console.error('Error: spec file path required. Usage: pw-intel reproduce <specFilePath>');
+      process.exit(1);
+    }
+
+    try {
+      const option = (name: string): string | undefined => {
+        const index = argv.indexOf(name);
+        return index >= 0 ? argv[index + 1] : undefined;
+      };
+      console.log(`Running diagnostic reproduction for '${specFile}'...`);
+      const result = await DiagnosticRerunner.rerunAndDiagnose({
+        specFilePath: specFile,
+        workspaceRoot: option('--workspace') ?? process.cwd(),
+      });
+
+      console.log(result.report);
+      if (!result.passed) {
+        process.exit(1);
+      }
+    } catch (err: any) {
+      console.error(`Reproduction execution failed: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'benchmark') {
+    // Resolve benchmark script from package directory first, falling back to process.cwd()
+    const cliDir = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1'));
+    const packageRootDir = path.resolve(cliDir, '..');
+    const packageBenchmarkScript = path.resolve(packageRootDir, 'benchmarks', 'runner', 'master-benchmark-runner.ts');
+    const localBenchmarkScript = path.resolve(process.cwd(), 'benchmarks', 'runner', 'master-benchmark-runner.ts');
+    const benchmarkScript = fs.existsSync(packageBenchmarkScript)
+      ? packageBenchmarkScript
+      : (fs.existsSync(localBenchmarkScript) ? localBenchmarkScript : undefined);
+
+    if (!benchmarkScript) {
+      console.log('Empirical benchmark harness is maintained in the research testbed repository.');
+      console.log('See docs/BENCHMARK.md for methodology, metrics, and empirical validation results.');
+      return;
+    }
+
+    // Locate tsx CLI entry point
+    const tsxCandidatePaths = [
+      path.resolve(packageRootDir, 'node_modules', 'tsx', 'dist', 'cli.mjs'),
+      path.resolve(process.cwd(), 'node_modules', 'tsx', 'dist', 'cli.mjs'),
+    ];
+    const tsxCli = tsxCandidatePaths.find((p) => fs.existsSync(p));
+
+    let executable: string;
+    let finalArgs: string[];
+
+    if (tsxCli) {
+      executable = process.execPath;
+      finalArgs = [tsxCli, benchmarkScript, ...argv.slice(3)];
+    } else {
+      executable = process.platform === 'win32' ? 'cmd.exe' : 'npx';
+      finalArgs = process.platform === 'win32'
+        ? ['/d', '/s', '/c', 'npx', 'tsx', benchmarkScript, ...argv.slice(3)]
+        : ['tsx', benchmarkScript, ...argv.slice(3)];
+    }
+
+    const child = spawn(executable, finalArgs, {
+      cwd: process.cwd(),
+      stdio: 'inherit',
+    });
+
+    child.on('close', (code) => {
+      process.exit(code ?? 0);
+    });
+    return;
+  }
+
+  if (command === 'doctor') {
+    await runDoctor();
+    return;
+  }
+
+  if (command === 'init') {
+    const workspaceRoot = argv[3] && !argv[3].startsWith('--') ? argv[3] : process.cwd();
+    try {
+      const option = (name: string): string | undefined => {
+        const index = argv.indexOf(name);
+        return index >= 0 ? argv[index + 1] : undefined;
+      };
+      const apiKeyArg = option('--api-key');
+      const modelArg = option('--model') ?? (apiKeyArg?.startsWith('sk-') ? 'gpt-4o' : 'deepseek-chat');
+      const endpointArg = option('--endpoint');
+
+      const result = await initProjectConfig(workspaceRoot, { force: argv.includes('--force') });
+
+      // Handle optional LLM configuration
+      if (apiKeyArg) {
+        const envPath = path.join(workspaceRoot, '.env');
+        const envLines = [
+          '# Playwright Intelligence Engine (PIE) Configuration',
+          `PIE_LLM_API_KEY=${apiKeyArg}`,
+          `PIE_LLM_MODEL=${modelArg}`,
+        ];
+        if (endpointArg) {
+          envLines.push(`PIE_LLM_ENDPOINT=${endpointArg}`);
+        } else if (apiKeyArg.startsWith('sk-proj-') || apiKeyArg.startsWith('sk-')) {
+          envLines.push('PIE_LLM_ENDPOINT=https://api.openai.com/v1/chat/completions');
+        }
+        await fs.promises.writeFile(envPath, `${envLines.join('\n')}\n`, 'utf8');
+
+        // Ensure .env is in .gitignore
+        const gitignorePath = path.join(workspaceRoot, '.gitignore');
+        try {
+          const gitignoreContent = await fs.promises.readFile(gitignorePath, 'utf8').catch(() => '');
+          if (!gitignoreContent.includes('.env')) {
+            await fs.promises.appendFile(gitignorePath, '\n.env\n', 'utf8');
+          }
+        } catch {}
+      }
+
+      const activeApiKey = apiKeyArg ?? process.env.PIE_LLM_API_KEY ?? process.env.OPENAI_API_KEY ?? process.env.DEEPSEEK_API_KEY;
+
+      if (argv.includes('--json')) {
+        console.log(JSON.stringify({ ...result, llmConfigured: Boolean(activeApiKey) }, null, 2));
+      } else {
+        console.log(`${result.created ? 'Created' : 'Found'} PIE project configuration: ${result.configPath}`);
+        console.log(`  Package manager : ${result.config.test.packageManager}`);
+        console.log(`  Test command    : ${result.config.test.command ?? 'not detected'}`);
+        console.log(`  Fail-closed     : ${result.config.diagnostics.failClosed ? 'enabled' : 'disabled'}`);
+        console.log(`  LLM Provider    : ${activeApiKey ? `configured (${apiKeyArg ? 'written to .env' : 'detected in environment'})` : 'not configured (100% offline deterministic mode)'}`);
+        if (!activeApiKey) {
+          console.log(`  Note            : Core diagnosis and repair are 100% offline. To enable AI test generation, run: pw-intel init --api-key <key>`);
+        }
+        console.log('\nQuickstart Commands:');
+        console.log('  Diagnose a trace   : pw-intel diagnose ./test-results/trace.zip');
+        console.log('  Repair a failure   : pw-intel autonomous-repair ./test-results/trace.zip --execute');
+        console.log('  Generate tests     : pw-intel generate-agent ./requirements.json --mode brownfield --write');
+      }
+    } catch (err: any) {
+      console.error(`PIE initialization failed: ${err?.message ?? String(err)}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'profile') {
+    const workspaceRoot = argv[3] && !argv[3].startsWith('--') ? argv[3] : process.cwd();
+    try {
+      const profile = await buildRepositoryProfile(workspaceRoot);
+      const outputIndex = argv.indexOf('--out');
+      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
+      if (outputPath) {
+        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(profile, null, 2)}\n`, 'utf8');
+      } else {
+        await writeRepositoryProfile(workspaceRoot, profile);
+      }
+      if (argv.includes('--json') || outputPath) console.log(JSON.stringify(profile, null, 2));
+      else {
+        console.log(`Repository profile generated for ${profile.repository.name}`);
+        console.log(`  Tests           : ${profile.structure.testFiles}`);
+        console.log(`  Page Objects    : ${profile.structure.pageObjectFiles}`);
+        console.log(`  Fixtures        : ${profile.structure.fixtureFiles}`);
+        console.log(`  Preferred loc.  : ${profile.locatorConventions.preferred}`);
+        console.log(`  Domain terms    : ${profile.domainTerms.slice(0, 10).join(', ') || 'none detected'}`);
+      }
+    } catch (err: any) {
+      console.error(`Repository profiling failed: ${err?.message ?? String(err)}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'cluster-failures') {
+    const inputPath = argv[3];
+    if (!inputPath) {
+      console.error('Error: input JSON path required. Usage: pw-intel cluster-failures <observations.json> [--out <report.json>]');
+      process.exit(1);
+    }
+    try {
+      const parsed = JSON.parse(await fs.promises.readFile(path.resolve(inputPath), 'utf8')) as { observations?: FailureObservation[] } | FailureObservation[];
+      const observations = Array.isArray(parsed) ? parsed : parsed.observations ?? [];
+      const clusters = clusterFailures(observations);
+      const report = {
+        generatedAt: new Date().toISOString(),
+        observationCount: observations.length,
+        clusterCount: clusters.length,
+        clusters,
+      };
+      const outputIndex = argv.indexOf('--out');
+      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
+      if (outputPath) {
+        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+      }
+      console.log(JSON.stringify(report, null, 2));
+    } catch (err: any) {
+      console.error(`Failure clustering failed: ${err?.message ?? String(err)}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'evaluation-scorecard') {
+    const inputPath = argv[3];
+    if (!inputPath) {
+      console.error('Error: evaluation JSON path required. Usage: pw-intel evaluation-scorecard <results.json> [--out <scorecard.json>]');
+      process.exit(1);
+    }
+    try {
+      const parsed = JSON.parse(await fs.promises.readFile(path.resolve(inputPath), 'utf8')) as EvaluationObservation[] | { observations?: EvaluationObservation[]; diagnosisResults?: EvaluationObservation[] };
+      const observations = Array.isArray(parsed) ? parsed : parsed.observations ?? parsed.diagnosisResults ?? [];
+      const scorecard = buildEvaluationScorecard(observations);
+      const report = { generatedAt: new Date().toISOString(), inputPath: path.resolve(inputPath), ...scorecard };
+      const outputIndex = argv.indexOf('--out');
+      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
+      if (outputPath) {
+        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+      }
+      console.log(JSON.stringify(report, null, 2));
+    } catch (err: any) {
+      console.error(`Evaluation scorecard failed: ${err?.message ?? String(err)}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'plan-test-intelligence') {
+    const requirementsPath = argv[3];
+    if (!requirementsPath) {
+      console.error('Error: requirements JSON path required. Usage: pw-intel plan-test-intelligence <requirements.json> [--tests <tests.json>] [--out <plan.json>]');
+      process.exit(1);
+    }
+    try {
+      const requirementsRaw = JSON.parse(await fs.promises.readFile(path.resolve(requirementsPath), 'utf8')) as RequirementInput[] | { requirements?: RequirementInput[] | string; title?: string; steps?: ArchitectureGenerationInput['steps']; baseUrl?: string; includeCi?: boolean };
+      const requirements = Array.isArray(requirementsRaw)
+        ? requirementsRaw
+        : Array.isArray(requirementsRaw.requirements)
+          ? requirementsRaw.requirements
+          : typeof requirementsRaw.requirements === 'string'
+            ? [{ id: 'requirement-1', title: requirementsRaw.title ?? requirementsRaw.requirements.slice(0, 100), description: requirementsRaw.requirements }]
+            : [];
+      if (requirements.length === 0) throw new Error('The requirements document contains no requirements');
+      const testsIndex = argv.indexOf('--tests');
+      const testsPath = testsIndex >= 0 ? argv[testsIndex + 1] : undefined;
+      let existingTests: ExistingTestInput[] = [];
+      if (testsPath) {
+        const testsRaw = JSON.parse(await fs.promises.readFile(path.resolve(testsPath), 'utf8')) as ExistingTestInput[] | { tests?: ExistingTestInput[] };
+        existingTests = Array.isArray(testsRaw) ? testsRaw : testsRaw.tests ?? [];
+      }
+      const plan = buildTestIntelligencePlan(requirements, existingTests);
+      const report = { generatedAt: new Date().toISOString(), requirementsPath: path.resolve(requirementsPath), testsPath: testsPath ? path.resolve(testsPath) : undefined, ...plan };
+      const outputIndex = argv.indexOf('--out');
+      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
+      if (outputPath) {
+        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+      }
+      console.log(JSON.stringify(report, null, 2));
+    } catch (err: any) {
+      console.error(`Test intelligence planning failed: ${err?.message ?? String(err)}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'generate-agent') {
+    const requirementsPath = argv[3];
+    if (!requirementsPath) {
+      console.error('Error: requirements JSON path required. Usage: pw-intel generate-agent <requirements.json> [--mode greenfield|brownfield] [--tests <tests.json>] [--write]');
+      process.exit(1);
+    }
+    try {
+      const requirementsRaw = JSON.parse(await fs.promises.readFile(path.resolve(requirementsPath), 'utf8')) as RequirementInput[] | { requirements?: RequirementInput[] | string; title?: string; steps?: ArchitectureGenerationInput['steps']; baseUrl?: string; includeCi?: boolean };
+      const requirementsDocument = Array.isArray(requirementsRaw) ? undefined : requirementsRaw;
+      const requirements = Array.isArray(requirementsRaw)
+        ? requirementsRaw
+        : Array.isArray(requirementsRaw.requirements)
+          ? requirementsRaw.requirements
+          : typeof requirementsRaw.requirements === 'string'
+            ? [{ id: 'requirement-1', title: requirementsRaw.title ?? requirementsRaw.requirements.slice(0, 100), description: requirementsRaw.requirements }]
+            : [];
+      if (requirements.length === 0) throw new Error('The requirements document contains no requirements');
+      const testsIndex = argv.indexOf('--tests');
+      const testsPath = testsIndex >= 0 ? argv[testsIndex + 1] : undefined;
+      let existingTests: ExistingTestInput[] = [];
+      if (testsPath) {
+        const testsRaw = JSON.parse(await fs.promises.readFile(path.resolve(testsPath), 'utf8')) as ExistingTestInput[] | { tests?: ExistingTestInput[] };
+        existingTests = Array.isArray(testsRaw) ? testsRaw : testsRaw.tests ?? [];
+      }
+      const modeIndex = argv.indexOf('--mode');
+      const mode = (modeIndex >= 0 ? argv[modeIndex + 1] : 'brownfield') as 'greenfield' | 'brownfield';
+      if (mode !== 'greenfield' && mode !== 'brownfield') throw new Error("--mode must be 'greenfield' or 'brownfield'");
+      const baseUrlIndex = argv.indexOf('--base-url');
+      const baseUrl = baseUrlIndex >= 0 ? argv[baseUrlIndex + 1] : requirementsDocument?.baseUrl;
+      const authorArg = argv.find((arg) => arg.startsWith('--author='));
+      const authorIndex = argv.indexOf('--author');
+      const author = authorArg
+        ? (authorArg.slice('--author='.length) as 'template' | 'hybrid' | 'llm')
+        : authorIndex >= 0
+          ? (argv[authorIndex + 1] as 'template' | 'hybrid' | 'llm')
+          : 'hybrid';
+      const result = await runGenerationAgent({
+        requirements,
+        existingTests,
+        mode,
+        author,
+        workspaceRoot: (argv.indexOf('--workspace') >= 0 ? argv[argv.indexOf('--workspace') + 1] : undefined) ?? process.cwd(),
+        ...(baseUrl ? { baseUrl } : {}),
+        ...(requirementsDocument?.steps ? { suggestedSteps: requirementsDocument.steps } : {}),
+        ...(requirementsDocument?.includeCi !== undefined ? { includeCi: requirementsDocument.includeCi } : {}),
+        write: argv.includes('--write'),
+        verify: argv.includes('--verify'),
+      });
+      console.log(JSON.stringify({ generatedAt: new Date().toISOString(), requirementsPath: path.resolve(requirementsPath), ...result }, null, 2));
+      if (result.status === 'ABSTAINED' || result.status === 'MODEL_NOT_CONFIGURED' || result.status === 'NEEDS_INPUT' || result.status === 'VERIFICATION_FAILED' || result.status === 'AGENT_NO_PROGRESS') process.exitCode = 1;
+    } catch (err: any) {
+      console.error(`Generation agent failed: ${err?.message ?? String(err)}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'stability-feedback') {
+    const selector = argv[3];
+    const outcomeIndex = argv.indexOf('--outcome');
+    const outcome = outcomeIndex >= 0 ? argv[outcomeIndex + 1] : undefined;
+    if (!selector || (outcome !== 'accepted' && outcome !== 'rejected')) {
+      console.error('Error: selector and outcome are required. Usage: pw-intel stability-feedback <selector> --outcome accepted|rejected');
+      process.exit(1);
+    }
+    try {
+      await recordProjectRepairFeedback(process.cwd(), selector, outcome);
+      console.log(JSON.stringify({ selector, outcome, recorded: true }));
+    } catch (err: any) {
+      console.error(`Stability feedback failed: ${err?.message ?? String(err)}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'suite-health') {
+    const inputPath = argv[3];
+    if (!inputPath) {
+      console.error('Error: run-record JSON path required. Usage: pw-intel suite-health <runs.json> [--out <report.json>]');
+      process.exit(1);
+    }
+    try {
+      const parsed = JSON.parse(await fs.promises.readFile(path.resolve(inputPath), 'utf8')) as { runs?: TestRunObservation[] } | TestRunObservation[];
+      const runs = Array.isArray(parsed) ? parsed : parsed.runs ?? [];
+      const summaries = analyzeTestStability(runs);
+      const report = { generatedAt: new Date().toISOString(), runCount: runs.length, testCount: summaries.length, flakyTestCount: summaries.filter((summary) => summary.flaky).length, tests: summaries };
+      const outputIndex = argv.indexOf('--out');
+      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
+      if (outputPath) {
+        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+      }
+      console.log(JSON.stringify(report, null, 2));
+    } catch (err: any) {
+      console.error(`Suite health analysis failed: ${err?.message ?? String(err)}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'team-dashboard') {
+    const inputPath = argv[3];
+    if (!inputPath) {
+      console.error('Error: team evidence JSON path required. Usage: pw-intel team-dashboard <evidence.json> [--out <report.json>]');
+      process.exit(1);
+    }
+    try {
+      const parsed = JSON.parse(await fs.promises.readFile(path.resolve(inputPath), 'utf8')) as { runs?: TeamEvidenceRun[] } | TeamEvidenceRun[];
+      const runs = Array.isArray(parsed) ? parsed : parsed.runs ?? [];
+      const report = buildTeamDashboard(runs);
+      const outputIndex = argv.indexOf('--out');
+      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
+      if (outputPath) {
+        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+      }
+      console.log(JSON.stringify(report, null, 2));
+    } catch (err: any) {
+      console.error(`Team dashboard generation failed: ${err?.message ?? String(err)}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'impact') {
+    const changedPath = argv[3];
+    if (!changedPath) {
+      console.error('Error: changed-files JSON path required. Usage: pw-intel impact <changed-files.json> [--root <directory>] [--out <report.json>]');
+      process.exit(1);
+    }
+    try {
+      const parsed = JSON.parse(await fs.promises.readFile(path.resolve(changedPath), 'utf8')) as { changedFiles?: string[] } | string[];
+      const changedFiles = Array.isArray(parsed) ? parsed : parsed.changedFiles ?? [];
+      const rootIndex = argv.indexOf('--root');
+      const root = (rootIndex >= 0 ? argv[rootIndex + 1] : undefined) ?? process.cwd();
+      const report = await analyzeRepositoryImpact(root, changedFiles);
+      const outputIndex = argv.indexOf('--out');
+      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
+      if (outputPath) {
+        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+      }
+      console.log(JSON.stringify(report, null, 2));
+    } catch (err: any) {
+      console.error(`Impact analysis failed: ${err?.message ?? String(err)}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'architect') {
+    const featureName = argv[3];
+    if (!featureName || featureName.startsWith('--')) {
+      console.error('Error: feature name required. Usage: pw-intel architect <featureName> [--mode greenfield|brownfield] [--baseUrl <url>] [--crawl] [--app-model <path>] [--requirements <json>] [--write] [--verify]');
+      process.exit(1);
+    }
+    try {
+      const modeIndex = argv.indexOf('--mode');
+      const mode = (modeIndex >= 0 ? argv[modeIndex + 1] : 'greenfield') as ArchitectureMode;
+      if (mode !== 'greenfield' && mode !== 'brownfield') throw new Error("--mode must be 'greenfield' or 'brownfield'");
+      const requirementsIndex = argv.indexOf('--requirements');
+      const requirementsPath = requirementsIndex >= 0 ? argv[requirementsIndex + 1] : undefined;
+      const requirements = requirementsPath
+        ? JSON.parse(await fs.promises.readFile(path.resolve(requirementsPath), 'utf8')) as Partial<ArchitectureGenerationInput>
+        : {};
+      const baseUrlIndex = argv.indexOf('--baseUrl');
+      const baseUrlFromArg = baseUrlIndex >= 0 ? argv[baseUrlIndex + 1] : undefined;
+      const baseUrl = baseUrlFromArg ?? requirements.baseUrl;
+
+      let appModel = requirements.appModel;
+      const appModelIndex = argv.indexOf('--app-model');
+      if (appModelIndex >= 0 && argv[appModelIndex + 1]) {
+        const modelPath = path.resolve(argv[appModelIndex + 1]!);
+        appModel = JSON.parse(await fs.promises.readFile(modelPath, 'utf8')) as AppModel;
+      } else if (baseUrl && (argv.includes('--crawl') || (!requirements.steps || requirements.steps.length === 0))) {
+        try {
+          appModel = await AppCrawler.crawl({ baseUrl });
+        } catch {
+          // Graceful fallback if live crawl cannot connect
+        }
+      }
+
+      const profile = mode === 'brownfield' ? await buildRepositoryProfile(process.cwd()) : undefined;
+      const plan = planArchitecture({
+        featureName,
+        mode,
+        profile,
+        baseUrl,
+        requirements: requirements.requirements,
+        steps: requirements.steps,
+        includeCi: requirements.includeCi,
+        appModel,
+      });
+      let writeResult;
+      if (argv.includes('--write')) writeResult = await writeArchitecturePlan(process.cwd(), plan);
+      let verification;
+      if (argv.includes('--verify') && writeResult && writeResult.written.length > 0) {
+        const spec = plan.files.find((file) => file.relativePath.endsWith('.spec.ts'));
+        if (spec) {
+          verification = await ExecutionRunner.run('npx', {
+            cwd: process.cwd(),
+            args: ['playwright', 'test', spec.relativePath, '--reporter=line'],
+            timeoutMs: 60_000,
+          });
+
+          // Falsifiability Prover (Mutation Verification)
+          if (verification.exitCode === 0) {
+            try {
+              const specFullPath = path.resolve(process.cwd(), spec.relativePath);
+              const originalContent = await fs.promises.readFile(specFullPath, 'utf8');
+              const mutatedContent = originalContent.replace(
+                /expect\(page\.getByText\(['"][^'"]+['"]\)\)/,
+                `expect(page.getByText('__UNMATCHED_FALSIFICATION_TARGET__'))`
+              );
+              if (mutatedContent !== originalContent) {
+                await fs.promises.writeFile(specFullPath, mutatedContent, 'utf8');
+                const mutatedRun = await ExecutionRunner.run('npx', {
+                  cwd: process.cwd(),
+                  args: ['playwright', 'test', spec.relativePath, '--reporter=line'],
+                  timeoutMs: 60_000,
+                });
+                await fs.promises.writeFile(specFullPath, originalContent, 'utf8');
+                (verification as any).falsifiable = mutatedRun.exitCode !== 0;
+              }
+            } catch {
+              // Non-fatal if mutation check cannot run
+            }
+          }
+        }
+      }
+      await recordArchitectureWorkflow(process.cwd(), plan, writeResult);
+      const report = { generatedAt: new Date().toISOString(), plan, writeResult, ...(verification ? { verification } : {}) };
+      const outputIndex = argv.indexOf('--out');
+      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
+      if (outputPath) {
+        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+      }
+      console.log(JSON.stringify(report, null, 2));
+    } catch (err: any) {
+      console.error(`Architecture generation failed: ${err?.message ?? String(err)}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'qa') {
+    const featureName = argv[3] && !argv[3].startsWith('--') ? argv[3] : undefined;
+    const readFlag = (flag: string): string | undefined => {
+      const idx = argv.indexOf(flag);
+      return idx >= 0 && argv[idx + 1] && !argv[idx + 1]!.startsWith('--') ? argv[idx + 1] : undefined;
+    };
+    const workspaceRoot = path.resolve(readFlag('--workspace') ?? process.cwd());
+    const baseUrl = readFlag('--url') ?? readFlag('--base-url');
+    const requirementsPath = readFlag('--requirements');
+    const markdownPath = readFlag('--markdown');
+    const gherkinPath = readFlag('--gherkin');
+    const promptFlag = readFlag('--prompt');
+    const outArtifactDir = readFlag('--out-dir');
+    const storageStatePath = readFlag('--storage-state');
+    const authorFlag = readFlag('--author') as AuthorKind | undefined;
+    const author: AuthorKind | undefined = authorFlag === 'template' || authorFlag === 'hybrid' || authorFlag === 'llm' ? authorFlag : undefined;
+    const useDiff = argv.includes('--diff');
+    const write = !argv.includes('--no-write');
+    const verify = !argv.includes('--no-verify');
+    const runMutations = !argv.includes('--no-mutate');
+    const allowMutatingActions = argv.includes('--allow-mutating');
+
+    try {
+      let markdown = markdownPath ? await fs.promises.readFile(path.resolve(markdownPath), 'utf8') : undefined;
+      let jsonRequirements: unknown;
+      let prompt = promptFlag;
+      let featureText = gherkinPath ? await fs.promises.readFile(path.resolve(gherkinPath), 'utf8') : undefined;
+
+      if (requirementsPath) {
+        const resolvedReqPath = path.resolve(requirementsPath);
+        const rawReq = await fs.promises.readFile(resolvedReqPath, 'utf8');
+        if (resolvedReqPath.toLowerCase().endsWith('.json')) {
+          jsonRequirements = JSON.parse(rawReq);
+        } else if (resolvedReqPath.toLowerCase().endsWith('.feature')) {
+          featureText = featureText ?? rawReq;
+        } else {
+          markdown = markdown ?? rawReq;
+        }
+      }
+
+      if (!featureName && !markdown && !jsonRequirements && !featureText && !prompt && !useDiff) {
+        console.error(
+          'Usage: pw-intel qa <featureName> [--workspace <dir>] [--url <baseUrl>] [--requirements <path>] [--markdown <path>] [--gherkin <path>] [--prompt <text>] [--diff] [--author template|hybrid|llm] [--out-dir <dir>] [--storage-state <path>] [--allow-mutating] [--no-write] [--no-verify] [--no-mutate]',
+        );
+        process.exit(1);
+      }
+
+      let gitDiff: { changedFiles?: string[]; changedRoutes?: string[]; changedSymbols?: string[]; apiEndpoints?: string[]; validationHints?: string[] } | undefined;
+      if (useDiff) {
+        const collected = await new GitDiffCollector().collect({ workspaceRoot });
+        const payload = collected[0]?.payload as { changedFiles?: string[]; diffHints?: { changedRoutes?: string[]; changedSymbols?: string[]; apiEndpoints?: string[]; validationHints?: string[] } } | undefined;
+        if (payload?.changedFiles?.length) {
+          gitDiff = {
+            changedFiles: payload.changedFiles,
+            ...(payload.diffHints ?? {}),
+          };
+        }
+      }
+
+      const result = await runEvidenceDrivenGeneration({
+        workspaceRoot,
+        featureName,
+        baseUrl,
+        prompt,
+        markdown,
+        jsonRequirements,
+        featureText,
+        gitDiff,
+        author,
+        outArtifactDir,
+        storageStatePath,
+        allowMutatingActions,
+        write,
+        verify,
+        runMutations,
+      });
+
+      const outFlag = readFlag('--out');
+      if (outFlag) {
+        await fs.promises.mkdir(path.dirname(path.resolve(outFlag)), { recursive: true });
+        await fs.promises.writeFile(path.resolve(outFlag), `${JSON.stringify(result.qaReport, null, 2)}\n`, 'utf8');
+      }
+      console.log(JSON.stringify(result.qaReport, null, 2));
+    } catch (err: any) {
+      console.error(`QA pipeline failed: ${err?.message ?? String(err)}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'ci-report') {
+    const reportPath = argv[3];
+    if (!reportPath) {
+      console.error('Error: Playwright JSON report path required. Usage: pw-intel ci-report <playwright-report.json> [--repository <name>] [--out <report.json>]');
+      process.exit(1);
+    }
+    try {
+      const report = JSON.parse(await fs.promises.readFile(path.resolve(reportPath), 'utf8')) as unknown;
+      const repositoryIndex = argv.indexOf('--repository');
+      const repository = repositoryIndex >= 0 ? argv[repositoryIndex + 1] : undefined;
+      const evidence = buildCiEvidenceReport(report, { repository, runId: process.env.GITHUB_RUN_ID ?? process.env.CI_PIPELINE_ID });
+      await recordCiWorkflow(process.cwd(), evidence);
+      const outputIndex = argv.indexOf('--out');
+      const outputPath = outputIndex >= 0 ? argv[outputIndex + 1] : undefined;
+      if (outputPath) {
+        await fs.promises.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+        await fs.promises.writeFile(path.resolve(outputPath), `${JSON.stringify(evidence, null, 2)}\n`, 'utf8');
+      }
+      const sarifIndex = argv.indexOf('--sarif-out');
+      const sarifPath = sarifIndex >= 0 ? argv[sarifIndex + 1] : undefined;
+      if (sarifPath) {
+        const sarif = buildSarifReport(evidence, PACKAGE_VERSION);
+        await fs.promises.mkdir(path.dirname(path.resolve(sarifPath)), { recursive: true });
+        await fs.promises.writeFile(path.resolve(sarifPath), `${JSON.stringify(sarif, null, 2)}\n`, 'utf8');
+      }
+      console.log(evidence.markdown);
+      for (const annotation of evidence.annotations) console.log(annotation);
+      if (evidence.qualityGate.status === 'FAIL') process.exitCode = 1;
+    } catch (err: any) {
+      console.error(`CI report ingestion failed: ${err?.message ?? String(err)}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'approve') {
+    const proposalId = argv[3];
+    if (!proposalId) {
+      console.error('Error: proposalId required. Usage: pw-intel approve <proposalId>');
+      process.exit(1);
+    }
+
+    const proposal = ApprovalService.getInstance().getProposal(proposalId);
+    if (!proposal) {
+      console.error(`Error: Proposal '${proposalId}' not found or expired.`);
+      process.exit(1);
+    }
+
+    console.log('========================================================================');
+    console.log(' PLAYWRIGHT INTELLIGENCE ENGINE — OPERATOR REPAIR APPROVAL');
+    console.log('========================================================================\n');
+    console.log(`Proposal ID      : ${proposal.proposalId}`);
+    console.log(`Target File      : ${proposal.targetFilePath}`);
+    console.log(`Target Class     : ${proposal.targetClassName}`);
+    console.log(`Target Member    : ${proposal.targetMemberName}`);
+    console.log(`Original Hash    : ${proposal.originalSourceHash.slice(0, 16)}...`);
+    console.log(`Patched Hash     : ${proposal.patchedSourceHash.slice(0, 16)}...`);
+    console.log(`Worktree Status  : ${proposal.worktreeExecutionVerified ? 'VERIFIED (Target test passed in isolated worktree)' : 'UNVERIFIED'}`);
+    console.log('\n--- Proposed Unified Diff ---');
+    console.log(proposal.fullDiff || '(No diff recorded)');
+    console.log('-----------------------------\n');
+
+    if (!proposal.worktreeExecutionVerified) {
+      console.error('Security Violation: Cannot authorize proposal. Worktree test execution was not verified.');
+      process.exit(1);
+    }
+
+    try {
+      const tokenPayload = ApprovalService.getInstance().authorizeProposal({ proposalId });
+      console.log('PROPOSAL AUTHORIZED.');
+      console.log(`Single-Use Approval Token: ${tokenPayload.tokenId}\n`);
+      console.log(`To atomically apply this patch to your workspace, run:`);
+      console.log(`  pw-intel promote --token ${tokenPayload.tokenId}\n`);
+    } catch (err: any) {
+      console.error(`Authorization failed: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (command === 'promote') {
+    const tokenIndex = argv.indexOf('--token');
+    const token = tokenIndex !== -1 ? argv[tokenIndex + 1] : undefined;
+    if (!token) {
+      console.error('Error: --token argument required. Usage: pw-intel promote --token <approvalToken>');
+      process.exit(1);
+    }
+
+    const tokenPayload = ApprovalService.getInstance().getTokenPayload(token);
+    if (!tokenPayload) {
+      console.error(`Error: Invalid or expired approval token '${token}'.`);
+      process.exit(1);
+    }
+
+    const proposal = ApprovalService.getInstance().getProposal(tokenPayload.proposalId);
+    if (!proposal) {
+      console.error(`Error: Staged proposal '${tokenPayload.proposalId}' no longer available.`);
+      process.exit(1);
+    }
+
+    console.log(`Applying authorized repair to '${tokenPayload.targetFilePath}'...`);
+    const promoResult = await WorkspacePromoter.promote({
+      targetFilePath: tokenPayload.targetFilePath,
+      workspaceRoot: process.cwd(),
+      patchedContent: proposal.patchedSource,
+      approvalTokenPayload: tokenPayload,
+    });
+
+    if (!promoResult.success) {
+      console.error(`Promotion failed: ${promoResult.error}`);
+      process.exit(1);
+    }
+
+    await recordProjectRepairAccepted(process.cwd(), proposal.replacementSelector).catch(() => {});
+
+    console.log(`Successfully promoted verified repair!`);
+    console.log(`Target File   : ${promoResult.targetFilePath}`);
+    console.log(`Bytes Written : ${promoResult.bytesWritten}`);
+    console.log(`Final Hash    : ${promoResult.finalHash.slice(0, 16)}...`);
+    return;
+  }
+
+  if (command === 'generate') {
+    const featureName = argv[3] ?? 'Dashboard';
+    const suite = TestGenerator.generateSuite(featureName, [
+      { action: 'fill', name: 'Search', value: 'query' },
+      { action: 'click', role: 'button', name: 'Submit' },
+      { action: 'assert-visible', role: 'heading', name: 'Results' },
+    ]);
+
+    console.log(`Generated Page Object (${suite.pageObjectName}.ts):`);
+    console.log(suite.pageObjectCode);
+    console.log('─────────────────────────────────────────────────────────────────');
+    console.log(`Generated Spec:`);
+    console.log(suite.specCode);
+    return;
+  }
+
+  console.error(`Unknown command: ${command}`);
+  printHelp();
+  process.exit(1);
+}
+
+async function runDoctor(): Promise<void> {
+  console.log('Running Playwright Intelligence Engine Diagnostic Healthcheck (pw-intel doctor)...\n');
+  let healthy = true;
+
+  // 1. Node.js version
+  const nodeVer = process.versions.node;
+  const major = parseInt(nodeVer.split('.')[0] || '0', 10);
+  if (major >= 20) {
+    console.log(`  ✓ Node.js Runtime     : v${nodeVer} (Supported >= 20.0.0)`);
+  } else {
+    console.log(`  ✗ Node.js Runtime     : v${nodeVer} (Unsupported, requires Node >= 20.0.0)`);
+    healthy = false;
+  }
+
+  // 2. Git CLI availability
+  try {
+    const gitVer = execSync('git --version', { encoding: 'utf-8' }).trim();
+    console.log(`  ✓ Git Version Control : ${gitVer}`);
+  } catch {
+    console.log(`  ✗ Git Version Control : Not found in PATH (Required for isolated worktrees)`);
+    healthy = false;
+  }
+
+  // 3. Playwright availability
+  let pwFound = false;
+  try {
+    const cwdPkg = path.resolve(process.cwd(), 'package.json');
+    if (fs.existsSync(cwdPkg)) {
+      const pkg = JSON.parse(fs.readFileSync(cwdPkg, 'utf-8'));
+      const pwVer = pkg.devDependencies?.['@playwright/test'] || pkg.dependencies?.['@playwright/test'];
+      if (pwVer) {
+        console.log(`  ✓ Playwright Test     : ${pwVer} (Found in package.json)`);
+        pwFound = true;
+      }
+    }
+  } catch {}
+  if (!pwFound) {
+    try {
+      const pwCliVer = execSync('npx --no-install playwright --version', {
+        encoding: 'utf-8',
+        timeout: 4000,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+      console.log(`  ✓ Playwright CLI      : ${pwCliVer}`);
+      pwFound = true;
+    } catch {
+      console.log(`  ! Playwright Test     : Not detected in current working directory (Optional for offline trace analysis)`);
+    }
+  }
+
+  // 4. Workspace write access
+  try {
+    fs.accessSync(process.cwd(), fs.constants.W_OK);
+    console.log(`  ✓ Workspace Access    : Read/Write verified for '${process.cwd()}'`);
+  } catch {
+    console.log(`  ✗ Workspace Access    : Permission denied writing to '${process.cwd()}'`);
+    healthy = false;
+  }
+
+  // 5. Host platform info
+  console.log(`  ✓ Host Platform       : ${process.platform} (${process.arch})`);
+
+  // 6. Optional LLM status
+  const apiKey = process.env.PIE_LLM_API_KEY ?? process.env.OPENAI_API_KEY ?? process.env.DEEPSEEK_API_KEY;
+  if (apiKey) {
+    console.log(`  ✓ LLM Provider        : Configured (AI test generation enabled)`);
+  } else {
+    console.log(`  ℹ LLM Provider        : None configured (100% offline deterministic mode active; run 'pw-intel init --api-key <key>' to enable AI generation)`);
+  }
+
+  console.log('\nHealthcheck Verdict: ' + (healthy ? 'HEALTHY (Ready for diagnostic and repair workflows)' : 'DEGRADED (Check failed items above)'));
+  if (!healthy) {
+    process.exit(1);
+  }
+}
+
+function printHelp(): void {
+  console.log(`
+Playwright Intelligence Engine CLI (pw-intel)
+
+Usage:
+  pw-intel init [dir] [--api-key <k>] [--model <m>] Initializes PIE config & optional LLM credentials
+  pw-intel profile [directory]   Builds the project repository convention profile
+  pw-intel cluster-failures <json> Groups failure observations by deterministic fingerprints
+  pw-intel evaluation-scorecard <json> Reconciles expected/predicted categories, repairs, abstentions, and latency
+  pw-intel plan-test-intelligence <requirements.json> Plans coverage, missing scenarios, and duplicate tests
+  pw-intel generate-agent <requirements.json> Uses structured LLM planning, then deterministic Playwright generation
+                                   --mode greenfield|brownfield --tests <tests.json> --base-url <url> --write --verify
+  pw-intel stability-feedback <selector> --outcome accepted|rejected Records operator repair feedback
+  pw-intel suite-health <json>    Calculates flaky-test and duration summaries
+  pw-intel team-dashboard <json> Aggregates repository CI evidence into a team dashboard
+  pw-intel impact <json>         Selects impacted tests from changed files and repository imports
+  pw-intel architect <featureName> Plans greenfield/brownfield Playwright architecture; add --write to create missing files
+  pw-intel qa <featureName>         Runs 4-phase evidence-driven QA workflow (plan, explore, generate, verify & falsify)
+                                   --workspace <dir> --url <baseUrl> --requirements <path> --gherkin <path> --diff --author template|hybrid|llm --out-dir <dir>
+  pw-intel ci-report <playwright-report.json> Ingests Playwright JSON and emits clusters, stability, gate, and CI annotations
+                                   --sarif-out <file> writes GitHub/code-scanning SARIF output
+  pw-intel doctor                   Inspects host environment, Node, Git, Playwright & workspace readiness
+  pw-intel diagnose <trace.zip>     Diagnoses a Playwright trace archive and outputs root cause
+                                   --error-context <file> supplements traces with Playwright error-context.md
+  pw-intel repair <trace.zip>       Creates a proposal; add --execute for isolated verification
+                                   --test <spec> --pom <page-object> --class <Class> --member <member>
+                                   --config <playwright.config> --error-context <file> --worktree-id <id>
+                                   --operation <JSON> for an allowlisted frame/shadow/locator operation
+  pw-intel autonomous-repair <trace.zip> Runs the bounded LLM agent and deterministic isolated verifier
+                                   --execute applies the proposal only in a disposable worktree
+                                   --browser --browser-url <url> --allow-host <hostname[,hostname]>
+                                   --run-tests allows the agent to run an explicitly requested target test
+                                   --promote promotes only an independently verified repair; implies execution
+  pw-intel reproduce <spec.ts>      Reruns a failing test with live multi-source diagnostic instrumentation
+  pw-intel inspect-testbed <dir>    Inspects external Playwright repositories and emits a reproducible manifest
+  pw-intel run-testbed <dir>       Runs bounded baseline commands for discovered repositories
+                                   --repository <name> --script <name> --timeout <ms> --out <file>
+  pw-intel approve <proposalId>     Human review and cryptographic authorization of staged repair proposal
+  pw-intel promote --token <token>  Atomically applies authorized repair proposal to active workspace
+  pw-intel benchmark [options]      Executes empirical real browser benchmark suite against Controlled App Server
+  pw-intel mcp                      Starts the Model Context Protocol (MCP) JSON-RPC server on stdio
+  pw-intel generate <featureName>   Generates verified Page Object and Spec scaffolding
+  pw-intel --help                   Shows this help message
+
+Benchmark Options:
+  --family <name>                   Filter mutation scenarios by family name (e.g. "Dynamic IDs")
+  --scenario <id>                   Filter negative control scenarios by category or name
+  --browser <browser>               Target browser (default: chromium)
+`);
+}
+