playwright-intelligence-engine 0.0.0-stage → 2.0.0

package/src/governance/team-dashboard.ts

@@ -0,0 +1,189 @@
+import type { CiEvidenceReport } from '../integrations/playwright-report-adapter.js';
+import { evaluateQualityGate, QualityGatePolicy, QualityGateReport } from '../integrations/quality-gate.js';
+import { FailureCluster } from '../intelligence/failure-clustering.js';
+import { TestStabilitySummary } from '../intelligence/suite-intelligence.js';
+
+export interface TeamEvidenceRun {
+  runId: string;
+  repository: string;
+  branch?: string | undefined;
+  commit?: string | undefined;
+  timestamp?: number | undefined;
+  evidence: CiEvidenceReport;
+}
+
+export interface RepositoryDashboardSummary {
+  repository: string;
+  runs: number;
+  testRuns: number;
+  failures: number;
+  flakyTests: number;
+  failureClusters: number;
+  passRate: number;
+  latestStatus: QualityGateReport['status'];
+  latestRunId: string;
+}
+
+export interface DashboardFlakyTest {
+  key: string;
+  repository?: string | undefined;
+  testId: string;
+  title?: string | undefined;
+  sourceFile?: string | undefined;
+  flakeRate: number;
+  runs: number;
+  failures: number;
+}
+
+export interface TeamDashboardReport {
+  generatedAt: string;
+  policy: QualityGatePolicy;
+  runCount: number;
+  repositoryCount: number;
+  repositories: RepositoryDashboardSummary[];
+  totals: {
+    testRuns: number;
+    failures: number;
+    flakyTests: number;
+    failureClusters: number;
+  };
+  failureClusters: FailureCluster[];
+  flakyTests: DashboardFlakyTest[];
+  qualityGate: QualityGateReport;
+  markdown: string;
+}
+
+function round(value: number): number {
+  return Number(value.toFixed(3));
+}
+
+function severityRank(severity: FailureCluster['severity']): number {
+  return { critical: 4, high: 3, medium: 2, low: 1, unknown: 0 }[severity];
+}
+
+function aggregateClusters(runs: TeamEvidenceRun[]): FailureCluster[] {
+  const grouped = new Map<string, FailureCluster>();
+  for (const run of runs) {
+    for (const cluster of run.evidence.clusters) {
+      const existing = grouped.get(cluster.clusterId);
+      if (!existing) {
+        grouped.set(cluster.clusterId, {
+          ...cluster,
+          affectedRepositories: [...new Set([run.repository, ...cluster.affectedRepositories])].sort(),
+          affectedTests: [...cluster.affectedTests].sort(),
+          observationIds: cluster.observationIds.map((id) => `${run.runId}:${id}`).sort(),
+        });
+        continue;
+      }
+      existing.count += cluster.count;
+      existing.observationIds.push(...cluster.observationIds.map((id) => `${run.runId}:${id}`));
+      existing.observationIds = [...new Set(existing.observationIds)].sort();
+      existing.affectedRepositories = [...new Set([...existing.affectedRepositories, run.repository, ...cluster.affectedRepositories])].sort();
+      existing.affectedTests = [...new Set([...existing.affectedTests, ...cluster.affectedTests])].sort();
+      existing.severity = severityRank(cluster.severity) > severityRank(existing.severity) ? cluster.severity : existing.severity;
+      existing.evidenceConsistency = round((existing.evidenceConsistency + cluster.evidenceConsistency) / 2);
+      if (cluster.firstSeen !== undefined) existing.firstSeen = existing.firstSeen === undefined ? cluster.firstSeen : Math.min(existing.firstSeen, cluster.firstSeen);
+      if (cluster.lastSeen !== undefined) existing.lastSeen = existing.lastSeen === undefined ? cluster.lastSeen : Math.max(existing.lastSeen, cluster.lastSeen);
+    }
+  }
+  return [...grouped.values()].sort((left, right) => severityRank(right.severity) - severityRank(left.severity) || right.count - left.count || left.clusterId.localeCompare(right.clusterId));
+}
+
+function aggregateStability(runs: TeamEvidenceRun[]): TestStabilitySummary[] {
+  const groups = new Map<string, TestStabilitySummary[]>();
+  for (const run of runs) {
+    for (const summary of run.evidence.stability) {
+      const key = `${run.repository}::${summary.testId}`;
+      const group = groups.get(key);
+      if (group) group.push({ ...summary, repository: run.repository });
+      else groups.set(key, [{ ...summary, repository: run.repository }]);
+    }
+  }
+  return [...groups.entries()].map(([key, summaries]) => {
+    const first = summaries[0]!;
+    const totalRuns = summaries.reduce((sum, item) => sum + item.runs, 0);
+    const passes = summaries.reduce((sum, item) => sum + item.passes, 0);
+    const failures = summaries.reduce((sum, item) => sum + item.failures, 0);
+    const skips = summaries.reduce((sum, item) => sum + item.skips, 0);
+    const blocked = summaries.reduce((sum, item) => sum + item.blocked, 0);
+    return {
+      ...first,
+      testId: first.testId,
+      repository: first.repository,
+      runs: totalRuns,
+      passes,
+      failures,
+      skips,
+      blocked,
+      passRate: totalRuns > 0 ? round(passes / totalRuns) : 0,
+      flakeRate: totalRuns > 0 ? round(Math.min(passes, failures) / totalRuns) : 0,
+      flaky: passes > 0 && failures > 0,
+      failureClusters: [...new Set(summaries.flatMap((item) => item.failureClusters))].sort(),
+      lastStatus: summaries[summaries.length - 1]!.lastStatus,
+      ...(key ? {} : {}),
+    };
+  });
+}
+
+function renderMarkdown(report: Omit<TeamDashboardReport, 'markdown'>): string {
+  const lines = [
+    `# PIE Team Quality Dashboard — ${report.qualityGate.status}`,
+    '',
+    `Policy: **${report.policy.name ?? 'default'}**`,
+    `Runs: **${report.runCount}** | Repositories: **${report.repositoryCount}** | Test executions: **${report.totals.testRuns}**`,
+    `Failures: **${report.totals.failures}** | Flaky tests: **${report.totals.flakyTests}** | Failure clusters: **${report.totals.failureClusters}**`,
+  ];
+  if (report.qualityGate.reasons.length > 0) lines.push('', '## Gate reasons', ...report.qualityGate.reasons.map((reason) => `- ${reason}`));
+  lines.push('', '## Repositories', '| Repository | Runs | Tests | Failures | Flaky | Gate |', '|---|---:|---:|---:|---:|---|');
+  for (const repository of report.repositories) lines.push(`| ${repository.repository} | ${repository.runs} | ${repository.testRuns} | ${repository.failures} | ${repository.flakyTests} | ${repository.latestStatus} |`);
+  if (report.failureClusters.length > 0) {
+    lines.push('', '## Top failure clusters', '| Severity | Count | Category | Repositories |', '|---|---:|---|---|');
+    for (const cluster of report.failureClusters.slice(0, 20)) lines.push(`| ${cluster.severity} | ${cluster.count} | ${cluster.fingerprint.category} | ${cluster.affectedRepositories.join(', ') || 'unknown'} |`);
+  }
+  return lines.join('\n');
+}
+
+export function buildTeamDashboard(runs: TeamEvidenceRun[], policy: QualityGatePolicy = {}): TeamDashboardReport {
+  const clusters = aggregateClusters(runs);
+  const stability = aggregateStability(runs);
+  const blockedCount = runs.reduce((sum, run) => sum + run.evidence.qualityGate.blockedCount, 0);
+  const requiredOracleUnavailable = runs.reduce((sum, run) => sum + run.evidence.qualityGate.requiredOracleUnavailable, 0);
+  const verifiedRepairs = runs.reduce((sum, run) => sum + run.evidence.qualityGate.verifiedRepairs, 0);
+  const failedRepairs = runs.reduce((sum, run) => sum + run.evidence.qualityGate.failedRepairs, 0);
+  const qualityGate = evaluateQualityGate({ clusters, stability, blockedCount, requiredOracleUnavailable, verifiedRepairs, failedRepairs }, policy);
+  const repositoryNames = [...new Set(runs.map((run) => run.repository))].sort();
+  const repositories = repositoryNames.map((repository) => {
+    const repositoryRuns = runs.filter((run) => run.repository === repository);
+    const testRuns = repositoryRuns.reduce((sum, run) => sum + run.evidence.runs.length, 0);
+    const failures = repositoryRuns.reduce((sum, run) => sum + run.evidence.failures.length, 0);
+    const flakyTests = new Set(repositoryRuns.flatMap((run) => run.evidence.stability.filter((test) => test.flaky).map((test) => test.testId))).size;
+    const latest = [...repositoryRuns].sort((left, right) => (right.timestamp ?? 0) - (left.timestamp ?? 0))[0]!;
+    return {
+      repository,
+      runs: repositoryRuns.length,
+      testRuns,
+      failures,
+      flakyTests,
+      failureClusters: new Set(repositoryRuns.flatMap((run) => run.evidence.clusters.map((cluster) => cluster.clusterId))).size,
+      passRate: testRuns > 0 ? round(repositoryRuns.reduce((sum, run) => sum + run.evidence.runs.filter((test) => test.status === 'PASS').length, 0) / testRuns) : 0,
+      latestStatus: latest.evidence.qualityGate.status,
+      latestRunId: latest.runId,
+    } satisfies RepositoryDashboardSummary;
+  });
+  const flakyTests = [...new Map(stability.filter((test) => test.flaky).map((test) => {
+    const key = `${test.repository ?? 'unknown'}::${test.testId}`;
+    return [key, { key, repository: test.repository, testId: test.testId, title: test.title, sourceFile: test.sourceFile, flakeRate: test.flakeRate, runs: test.runs, failures: test.failures } satisfies DashboardFlakyTest];
+  })).values()].sort((left, right) => right.flakeRate - left.flakeRate || left.key.localeCompare(right.key));
+  const reportBase = {
+    generatedAt: new Date().toISOString(),
+    policy,
+    runCount: runs.length,
+    repositoryCount: repositoryNames.length,
+    repositories,
+    totals: { testRuns: runs.reduce((sum, run) => sum + run.evidence.runs.length, 0), failures: runs.reduce((sum, run) => sum + run.evidence.failures.length, 0), flakyTests: flakyTests.length, failureClusters: clusters.length },
+    failureClusters: clusters,
+    flakyTests,
+    qualityGate,
+  };
+  return { ...reportBase, markdown: renderMarkdown(reportBase) };
+}

package/src/governance/workflow-audit.ts

@@ -0,0 +1,72 @@
+import { AuditLog } from './audit-log.js';
+import type { ArchitecturePlan, ArchitectureWriteResult } from '../generator/architecture-generator.js';
+import type { CiEvidenceReport } from '../integrations/playwright-report-adapter.js';
+
+export interface RepairWorkflowAuditInput {
+  status: 'ABSTAINED' | 'INPUT_REQUIRED' | 'OPERATION_PROPOSAL_ONLY' | 'PROPOSAL_READY' | 'VERIFIED_READY_FOR_APPROVAL' | 'REJECTED';
+  category: string;
+  proposalId?: string | undefined;
+  worktreeId?: string | undefined;
+  executionPassed?: boolean | undefined;
+}
+
+export async function recordArchitectureWorkflow(
+  root: string,
+  plan: ArchitecturePlan,
+  writeResult?: ArchitectureWriteResult,
+): Promise<void> {
+  await new AuditLog(root).append({
+    actor: 'system',
+    action: 'architecture_plan',
+    outcome: plan.status === 'ABSTAIN' ? 'abstained' : 'allowed',
+    target: plan.featureName,
+    metadata: {
+      mode: plan.mode,
+      status: plan.status,
+      plannedFiles: plan.files.length,
+      createdFiles: writeResult?.written.length ?? 0,
+      skippedFiles: writeResult?.skipped.length ?? 0,
+      warnings: plan.warnings.length,
+    },
+  });
+}
+
+export async function recordCiWorkflow(root: string, report: CiEvidenceReport): Promise<void> {
+  await new AuditLog(root).append({
+    actor: 'system',
+    action: 'ci_evidence_ingested',
+    outcome: report.qualityGate.status === 'PASS' ? 'allowed' : report.qualityGate.status === 'ABSTAIN' ? 'abstained' : 'failed',
+    target: report.clusters[0]?.representative.repository ?? 'playwright-report',
+    metadata: {
+      status: report.qualityGate.status,
+      tests: report.runs.length,
+      failures: report.failures.length,
+      clusters: report.clusters.length,
+      flakyTests: report.stability.filter((test) => test.flaky).length,
+      criticalClusters: report.qualityGate.criticalClusters,
+    },
+  });
+}
+
+export async function recordRepairWorkflow(root: string, input: RepairWorkflowAuditInput): Promise<void> {
+  const outcome = input.status === 'ABSTAINED'
+    ? 'abstained'
+    : input.status === 'REJECTED'
+      ? 'failed'
+    : input.status === 'INPUT_REQUIRED'
+        ? 'denied'
+        : 'allowed';
+  await new AuditLog(root).append({
+    actor: 'system',
+    action: 'repair_workflow',
+    outcome,
+    target: input.category,
+    metadata: {
+      status: input.status,
+      category: input.category,
+      ...(input.proposalId ? { proposalId: input.proposalId } : {}),
+      ...(input.worktreeId ? { worktreeId: input.worktreeId } : {}),
+      ...(input.executionPassed !== undefined ? { executionPassed: input.executionPassed } : {}),
+    },
+  });
+}

package/src/index.ts

@@ -0,0 +1,107 @@
+// Core Types & Schemas
+export * from './core/version.js';
+export * from './core/types/diagnostic-context.js';
+export * from './core/types/repair-evidence.js';
+export * from './core/errors/engine-errors.js';
+
+// Trace Ingestion
+export * from './trace/archive-reader.js';
+export * from './trace/version-detector.js';
+export * from './trace/trace-parser.js';
+export * from './trace/snapshot-resolver.js';
+export * from './trace/adapters/trace-adapter.js';
+export * from './trace/adapters/adapter-registry.js';
+export * from './trace/adapters/v8-adapter.js';
+export * from './trace/adapters/v9-adapter.js';
+export * from './trace/adapters/v10-adapter.js';
+export * from './trace/adapters/unknown-adapter.js';
+
+// Diagnostics
+export * from './diagnostics/failure-classifier.js';
+export * from './diagnostics/evidence-correlator.js';
+export * from './diagnostics/diagnostic-report.js';
+export * from './diagnostics/diagnostic-contract.js';
+export * from './diagnostics/failure-category.js';
+export * from './diagnostics/external-failure-evidence.js';
+
+// Selector Intelligence & Abstention
+export * from './selector/candidate-extractor.js';
+export * from './selector/selector-scorer.js';
+export * from './selector/abstention-policy.js';
+export * from './selector/repair-candidate-ranker.js';
+export * from './intelligence/locator-disambiguation-engine.js';
+
+// AST Repair & Verification
+export * from './repair/ast-patcher.js';
+export * from './repair/statement-patcher.js';
+export * from './repair/assertion-hasher.js';
+export * from './repair/diff-allowlist.js';
+export * from './repair/intent-validator.js';
+export * from './repair/repair-planner.js';
+export * from './repair/repair-workflow.js';
+export * from './repair/approval-service.js';
+export * from './repair/workspace-promoter.js';
+export * from './repair/repair-operations.js';
+export * from './repair/verification-gates.js';
+export * from './repair/safe-operation-compiler.js';
+export * from './collectors/git-diff-collector.js';
+export * from './collectors/network-collector.js';
+export * from './collectors/static-ast-collector.js';
+export * from './repair/browser-operation-executor.js';
+export * from './repair/source-mapper.js';
+
+// Selector Verification & Live Reproduction
+export * from './selector/live-locator-verifier.js';
+export * from './reproduce/direct-browser-investigator.js';
+export * from './reproduce/diagnostic-rerunner.js';
+export * from './reproduce/interactive-workflow-runner.js';
+
+// Sandbox & Worktree Management
+export * from './sandbox/dependency-strategy.js';
+export * from './sandbox/worktree-manager.js';
+export * from './sandbox/execution-runner.js';
+
+// Memory & Generation
+export * from './memory/stability-ledger.js';
+export * from './generator/test-generator.js';
+export * from './generator/architecture-generator.js';
+export * from './generator/assertion-quality-gate.js';
+export * from './generator/candidate-writer.js';
+export * from './authoring/index.js';
+export * from './gate/index.js';
+export * from './perception/index.js';
+export * from './config/project-config.js';
+export * from './intelligence/llm-proposal.js';
+export * from './intelligence/model-provider.js';
+export * from './intelligence/model-contract.js';
+export * from './intelligence/evidence-bundle.js';
+export * from './intelligence/repair-agent.js';
+export * from './intelligence/trace-proposal-workflow.js';
+export * from './intelligence/verified-llm-repair-workflow.js';
+export * from './intelligence/autonomous-repair-workflow.js';
+export * from './intelligence/generation-agent.js';
+export * from './intelligence/generation-verifier.js';
+export * from './intelligence/repository-profile.js';
+export * from './intelligence/project-intelligence.js';
+export * from './intelligence/failure-clustering.js';
+export * from './intelligence/suite-intelligence.js';
+export * from './intelligence/business-intent.js';
+export * from './intelligence/test-intelligence.js';
+export * from './intelligence/workflow-planner.js';
+export * from './integrations/ci-summary.js';
+export * from './integrations/quality-gate.js';
+export * from './integrations/playwright-report-adapter.js';
+export * from './integrations/sarif-report.js';
+export * from './governance/audit-log.js';
+export * from './governance/workflow-audit.js';
+export * from './governance/team-dashboard.js';
+export * from './repair/workflow-plan.js';
+export * from './evaluation/repository-inspector.js';
+export * from './evaluation/repository-runner.js';
+export * from './evaluation/evaluation-scorecard.js';
+
+// Framework & MCP
+export * from './framework/config-adapter.js';
+export * from './mcp/server.js';
+export * from './cli/index.js';
+

package/src/integrations/ci-summary.ts

@@ -0,0 +1,37 @@
+export interface CiFailureSummary {
+  status: 'PASS' | 'FAIL' | 'ABSTAIN' | 'BLOCKED';
+  repository?: string;
+  testIdentity?: string;
+  category?: string;
+  confidence?: number;
+  reason: string;
+  artifacts: string[];
+  repairProposalAvailable: boolean;
+  verifiedRepair: boolean;
+}
+
+export function renderCiSummary(summary: CiFailureSummary): string {
+  const lines = [
+    `## PIE result: ${summary.status}`,
+    '',
+    summary.repository ? `- Repository: \`${summary.repository}\`` : undefined,
+    summary.testIdentity ? `- Test: \`${summary.testIdentity}\`` : undefined,
+    summary.category ? `- Classification: \`${summary.category}\`` : undefined,
+    summary.confidence === undefined ? undefined : `- Confidence: ${(summary.confidence * 100).toFixed(1)}%`,
+    `- Repair proposal: ${summary.repairProposalAvailable ? 'available' : 'not available'}`,
+    `- Browser verification: ${summary.verifiedRepair ? 'passed' : 'not verified'}`,
+    `- Reason: ${summary.reason}`,
+  ].filter((line): line is string => line !== undefined);
+
+  if (summary.artifacts.length > 0) {
+    lines.push('', '### Artifacts', ...summary.artifacts.map((artifact) => `- ${artifact}`));
+  }
+
+  return lines.join('\n');
+}
+
+export function renderGitHubAnnotation(summary: CiFailureSummary): string {
+  const level = summary.status === 'FAIL' ? 'error' : summary.status === 'ABSTAIN' ? 'warning' : 'notice';
+  return `::${level} title=PIE ${summary.status}::${summary.reason}`;
+}
+

package/src/integrations/playwright-report-adapter.ts

@@ -0,0 +1,173 @@
+import { clusterFailures, FailureObservation } from '../intelligence/failure-clustering.js';
+import { analyzeTestStability, TestRunObservation } from '../intelligence/suite-intelligence.js';
+import { evaluateQualityGate, QualityGateReport } from './quality-gate.js';
+
+export interface PlaywrightReportAdapterOptions {
+  repository?: string | undefined;
+  runId?: string | undefined;
+  timestamp?: number | undefined;
+}
+
+export interface ParsedPlaywrightReport {
+  runs: TestRunObservation[];
+  failures: FailureObservation[];
+}
+
+export interface CiEvidenceReport extends ParsedPlaywrightReport {
+  clusters: ReturnType<typeof clusterFailures>;
+  stability: ReturnType<typeof analyzeTestStability>;
+  qualityGate: QualityGateReport;
+  markdown: string;
+  annotations: string[];
+}
+
+interface PlaywrightResult {
+  status?: string | undefined;
+  duration?: number | undefined;
+  retry?: number | undefined;
+  error?: { message?: string; stack?: string } | undefined;
+  errors?: Array<{ message?: string; stack?: string }> | undefined;
+}
+
+interface PlaywrightTest {
+  title?: string | undefined;
+  titlePath?: string[] | undefined;
+  file?: string | undefined;
+  projectName?: string | undefined;
+  results?: PlaywrightResult[] | undefined;
+  status?: string | undefined;
+}
+
+function asObject(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : {};
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function mapStatus(status: string | undefined): TestRunObservation['status'] {
+  switch ((status ?? '').toLowerCase()) {
+    case 'passed': return 'PASS';
+    case 'skipped': return 'SKIP';
+    case 'timedout':
+    case 'timeout': return 'TIMEOUT';
+    case 'interrupted': return 'BLOCKED';
+    case 'failed': return 'FAIL';
+    default: return 'BLOCKED';
+  }
+}
+
+function collectTests(node: unknown, inheritedFile: string | undefined, inheritedTitles: string[], output: PlaywrightTest[]): void {
+  const object = asObject(node);
+  const file = asString(object.file) ?? inheritedFile;
+  const title = asString(object.title);
+  const titles = title ? [...inheritedTitles, title] : inheritedTitles;
+  const specs = Array.isArray(object.specs) ? object.specs : [];
+  for (const spec of specs) {
+    const specObject = asObject(spec);
+    const specTitle = asString(specObject.title);
+    const specTitles = specTitle ? [...titles, specTitle] : titles;
+    const tests = Array.isArray(specObject.tests) ? specObject.tests : [];
+    for (const test of tests) {
+      const testObject = asObject(test);
+      output.push({
+        title: specTitles.join(' › '),
+        titlePath: specTitles,
+        file: asString(testObject.location) ?? file,
+        projectName: asString(testObject.projectName),
+        results: Array.isArray(testObject.results) ? testObject.results.map((result) => asObject(result) as PlaywrightResult) : [],
+        status: asString(testObject.status),
+      });
+    }
+  }
+  const suites = Array.isArray(object.suites) ? object.suites : [];
+  for (const suite of suites) collectTests(suite, file, titles, output);
+}
+
+function failureMessage(result: PlaywrightResult): { message?: string; stack?: string } {
+  const first = result.error ?? result.errors?.[0];
+  return {
+    ...(first?.message !== undefined ? { message: first.message } : {}),
+    ...(first?.stack !== undefined ? { stack: first.stack } : {}),
+  };
+}
+
+export function parsePlaywrightJsonReport(report: unknown, options: PlaywrightReportAdapterOptions = {}): ParsedPlaywrightReport {
+  const root = asObject(report);
+  const tests: PlaywrightTest[] = [];
+  if (Array.isArray(root.suites)) {
+    for (const suite of root.suites) collectTests(suite, undefined, [], tests);
+  } else if (Array.isArray(root.tests)) {
+    collectTests(root, undefined, [], tests);
+  }
+
+  const runId = options.runId ?? `playwright-${options.timestamp ?? Date.now()}`;
+  const timestamp = options.timestamp;
+  const runs: TestRunObservation[] = [];
+  const failures: FailureObservation[] = [];
+  tests.forEach((test, testIndex) => {
+    const results: PlaywrightResult[] = test.results && test.results.length > 0 ? test.results : [{ status: test.status }];
+    results.forEach((result, resultIndex) => {
+      const status = mapStatus(result.status);
+      const testId = `${test.file ?? 'unknown'}::${test.title ?? `test-${testIndex + 1}`}`;
+      const retryIndex = typeof result.retry === 'number' ? result.retry : resultIndex;
+      runs.push({
+        runId,
+        testId,
+        repository: options.repository,
+        title: test.title,
+        sourceFile: test.file,
+        status,
+        durationMs: typeof result.duration === 'number' ? result.duration : undefined,
+        timestamp,
+        retryIndex,
+      });
+      if (status === 'FAIL' || status === 'TIMEOUT') {
+        const error = failureMessage(result);
+        failures.push({
+          id: `${runId}:${testIndex}:${resultIndex}`,
+          repository: options.repository,
+          testTitle: test.title,
+          sourceFile: test.file,
+          category: 'TEST_FAILURE',
+          errorMessage: error.message,
+          errorStack: error.stack,
+          timestamp,
+          durationMs: typeof result.duration === 'number' ? result.duration : undefined,
+        });
+      }
+    });
+  });
+  return { runs, failures };
+}
+
+function renderMarkdown(report: Omit<CiEvidenceReport, 'markdown' | 'annotations'>): string {
+  const lines = [
+    `## PIE CI result: ${report.qualityGate.status}`,
+    '',
+    `- Tests observed: ${report.runs.length}`,
+    `- Failure observations: ${report.failures.length}`,
+    `- Failure clusters: ${report.clusters.length}`,
+    `- Flaky tests: ${report.stability.filter((test) => test.flaky).length}`,
+  ];
+  if (report.qualityGate.reasons.length > 0) lines.push('', '### Gate reasons', ...report.qualityGate.reasons.map((reason) => `- ${reason}`));
+  if (report.clusters.length > 0) {
+    lines.push('', '### Failure clusters', '| Severity | Count | Category | Cluster |', '|---|---:|---|---|');
+    for (const cluster of report.clusters.slice(0, 20)) lines.push(`| ${cluster.severity} | ${cluster.count} | ${cluster.fingerprint.category} | ${cluster.clusterId} |`);
+  }
+  return lines.join('\n');
+}
+
+export function buildCiEvidenceReport(report: unknown, options: PlaywrightReportAdapterOptions = {}): CiEvidenceReport {
+  const parsed = parsePlaywrightJsonReport(report, options);
+  const clusters = clusterFailures(parsed.failures);
+  const stability = analyzeTestStability(parsed.runs.map((run) => ({
+    ...run,
+    failureClusterId: clusters.find((cluster) => run.title && cluster.affectedTests.includes(run.title))?.clusterId,
+  })));
+  const qualityGate = evaluateQualityGate({ clusters, stability });
+  const base = { ...parsed, clusters, stability, qualityGate };
+  const annotations = qualityGate.reasons.map((reason) => `::${qualityGate.status === 'FAIL' ? 'error' : qualityGate.status === 'ABSTAIN' ? 'warning' : 'notice'} title=PIE ${qualityGate.status}::${reason}`);
+  return { ...base, markdown: renderMarkdown(base), annotations };
+}

package/src/integrations/quality-gate.ts

@@ -0,0 +1,95 @@
+import { FailureCluster } from '../intelligence/failure-clustering.js';
+import { TestStabilitySummary } from '../intelligence/suite-intelligence.js';
+
+export interface QualityGateInput {
+  clusters?: FailureCluster[] | undefined;
+  stability?: TestStabilitySummary[] | undefined;
+  blockedCount?: number | undefined;
+  requiredOracleUnavailable?: number | undefined;
+  verifiedRepairs?: number | undefined;
+  failedRepairs?: number | undefined;
+}
+
+/**
+ * Optional team policy. When omitted, evaluateQualityGate preserves the
+ * original evidence-driven behavior used by local diagnosis and CI reports.
+ */
+export interface QualityGatePolicy {
+  name?: string | undefined;
+  maxFlakyTests?: number | undefined;
+  maxHighSeverityClusters?: number | undefined;
+  maxBlockedResults?: number | undefined;
+  failOnAbstain?: boolean | undefined;
+}
+
+export interface QualityGateReport {
+  status: 'PASS' | 'FAIL' | 'ABSTAIN' | 'BLOCKED';
+  reasons: string[];
+  criticalClusters: number;
+  highSeverityClusters: number;
+  flakyTests: number;
+  blockedCount: number;
+  requiredOracleUnavailable: number;
+  verifiedRepairs: number;
+  failedRepairs: number;
+  policyViolations: string[];
+}
+
+export function evaluateQualityGate(input: QualityGateInput, policy: QualityGatePolicy = {}): QualityGateReport {
+  const clusters = input.clusters ?? [];
+  const stability = input.stability ?? [];
+  const blockedCount = input.blockedCount ?? 0;
+  const requiredOracleUnavailable = input.requiredOracleUnavailable ?? 0;
+  const verifiedRepairs = input.verifiedRepairs ?? 0;
+  const failedRepairs = input.failedRepairs ?? 0;
+  const criticalClusters = clusters.filter((cluster) => cluster.severity === 'critical').length;
+  const highSeverityClusters = clusters.filter((cluster) => cluster.severity === 'high').length;
+  const flakyTests = stability.filter((summary) => summary.flaky).length;
+  const reasons: string[] = [];
+
+  if (criticalClusters > 0) reasons.push(`${criticalClusters} critical failure cluster(s) detected`);
+  if (failedRepairs > 0) reasons.push(`${failedRepairs} repair verification(s) failed`);
+  if (blockedCount > 0) reasons.push(`${blockedCount} test or repository result(s) are blocked`);
+  if (requiredOracleUnavailable > 0) reasons.push(`${requiredOracleUnavailable} required business oracle result(s) are unavailable`);
+  if (highSeverityClusters > 0) reasons.push(`${highSeverityClusters} high-severity failure cluster(s) detected`);
+  if (flakyTests > 0) reasons.push(`${flakyTests} flaky test(s) detected`);
+
+  const policyViolations: string[] = [];
+  if (policy.maxFlakyTests !== undefined && flakyTests > policy.maxFlakyTests) {
+    policyViolations.push(`Policy '${policy.name ?? 'default'}' allows at most ${policy.maxFlakyTests} flaky test(s), found ${flakyTests}`);
+  }
+  if (policy.maxHighSeverityClusters !== undefined && highSeverityClusters > policy.maxHighSeverityClusters) {
+    policyViolations.push(`Policy '${policy.name ?? 'default'}' allows at most ${policy.maxHighSeverityClusters} high-severity cluster(s), found ${highSeverityClusters}`);
+  }
+  if (policy.maxBlockedResults !== undefined && blockedCount > policy.maxBlockedResults) {
+    policyViolations.push(`Policy '${policy.name ?? 'default'}' allows at most ${policy.maxBlockedResults} blocked result(s), found ${blockedCount}`);
+  }
+  reasons.push(...policyViolations);
+
+  const evidenceStatus: QualityGateReport['status'] = criticalClusters > 0 || failedRepairs > 0
+    ? 'FAIL'
+    : blockedCount > 0
+      ? 'BLOCKED'
+      : requiredOracleUnavailable > 0 || highSeverityClusters > 0 || flakyTests > 0
+        ? 'ABSTAIN'
+        : 'PASS';
+  const status: QualityGateReport['status'] = policyViolations.length > 0 || (policy.failOnAbstain === true && evidenceStatus === 'ABSTAIN')
+    ? 'FAIL'
+    : evidenceStatus;
+  if (policy.failOnAbstain === true && evidenceStatus === 'ABSTAIN' && policyViolations.length === 0) {
+    reasons.push(`Policy '${policy.name ?? 'default'}' rejects ABSTAIN outcomes`);
+  }
+
+  return {
+    status,
+    reasons,
+    criticalClusters,
+    highSeverityClusters,
+    flakyTests,
+    blockedCount,
+    requiredOracleUnavailable,
+    verifiedRepairs,
+    failedRepairs,
+    policyViolations,
+  };
+}