@williambeto/ai-workflow 2.3.6 → 2.4.0

package/src/core/validation/delivery-decision-engine.js

@@ -2,6 +2,29 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { StackDetector } from "./stack-detector.js";
 
+function parseRequest(request = "") {
+  const req = request.toLowerCase();
+  
+  let targetStack = null;
+  if (/\b(vue|nuxt|quasar)\b/.test(req)) targetStack = "vue";
+  else if (/\b(react|next)\b/.test(req)) targetStack = "react";
+  else if (/\b(angular|svelte)\b/.test(req)) targetStack = "svelte-or-angular";
+  else if (/\b(laravel|django|rails|express|nest|fastify)\b/.test(req)) {
+    if (/\blaravel\b/.test(req)) targetStack = "laravel";
+    else targetStack = "backend";
+  }
+  else if (/\b(wordpress|wp)\b/.test(req)) targetStack = "wordpress";
+  else if (/\b(cli|command|bin)\b/.test(req)) targetStack = "cli";
+
+  let intent = "implementation";
+  if (/\b(document|doc|readme)\b/.test(req)) intent = "docs";
+  else if (/\b(audit|security|inspect|dependencies)\b/.test(req)) intent = "audit";
+  else if (/\b(release|publish|deploy)\b/.test(req)) intent = "release";
+  else if (/\b(prototype|standalone html)\b/.test(req)) intent = "prototype";
+
+  return { targetStack, intent };
+}
+
 export class DeliveryDecisionEngine {
   constructor({ cwd = process.cwd() } = {}) {
     this.cwd = cwd;
@@ -13,7 +36,6 @@ export class DeliveryDecisionEngine {
       return "empty";
     }
 
-    // 1. Docs check
     const isDocs = changedFiles.every(file => 
       file.endsWith(".md") || file.endsWith(".txt") || file.startsWith("docs/")
     );
@@ -21,10 +43,8 @@ export class DeliveryDecisionEngine {
       return "docs-only";
     }
 
-    // 2. Detect project stacks
     const stacks = await this.stackDetector.detect();
     
-    // Check package.json for frontend frameworks
     let usesJsFramework = false;
     try {
       const pkgPath = path.join(this.cwd, "package.json");
@@ -35,14 +55,11 @@ export class DeliveryDecisionEngine {
       const frameworks = ["react", "next", "vue", "nuxt", "svelte", "solid-js", "preact", "quasar", "@angular/core"];
       usesJsFramework = frameworks.some(fw => deps[fw] !== undefined);
     } catch {
-      // package.json doesn't exist or is invalid
+      // ignore
     }
 
-    // Check for WordPress
-    const isWordPress = await fs.access(path.join(this.cwd, "wp-config.php")).then(() => true).catch(() => false) ||
-                        await fs.access(path.join(this.cwd, "wp-content")).then(() => true).catch(() => false);
+    const isWordPress = await checkWordPressDirectRoot(this.cwd);
 
-    // Analyze changed files for UI/frontend assets
     const hasFrontendFiles = changedFiles.some(file => 
       /\.(html?|css|scss|sass|less|jsx|tsx|vue|svelte)$/i.test(file) ||
       (/\.js$/i.test(file) && !file.includes("config") && !file.includes("test"))
@@ -66,4 +83,262 @@ export class DeliveryDecisionEngine {
 
     return "generic-code";
   }
+
+  async detectContext() {
+    const stacks = await this.stackDetector.detect();
+    
+    let usesJsFramework = null;
+    let hasPackageJson = false;
+    let isCli = false;
+    try {
+      const pkgPath = path.join(this.cwd, "package.json");
+      const pkgContent = await fs.readFile(pkgPath, "utf8");
+      hasPackageJson = true;
+      const pkg = JSON.parse(pkgContent);
+      const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      if (pkg.bin || pkg.name === "@williambeto/ai-workflow") {
+        isCli = true;
+      }
+      
+      const frameworks = ["react", "next", "vue", "nuxt", "svelte", "solid-js", "preact", "quasar", "@angular/core"];
+      for (const fw of frameworks) {
+        if (deps[fw] !== undefined) {
+          usesJsFramework = fw;
+          break;
+        }
+      }
+    } catch {}
+
+    let isLaravel = false;
+    let hasComposerJson = false;
+    try {
+      const composerPath = path.join(this.cwd, "composer.json");
+      const composerContent = await fs.readFile(composerPath, "utf8");
+      hasComposerJson = true;
+      const composer = JSON.parse(composerContent);
+      const reqs = { ...(composer.require || {}), ...(composer.requireDev || {}) };
+      if (reqs["laravel/framework"]) {
+        isLaravel = true;
+      }
+    } catch {}
+
+    const isWordPress = await checkWordPressDirectRoot(this.cwd);
+
+    let isEmpty = true;
+    try {
+      const entries = await fs.readdir(this.cwd);
+      const meaningful = entries.filter(e => !e.startsWith(".") && !["node_modules", "EVIDENCE.json"].includes(e));
+      if (meaningful.length > 0) {
+        if (meaningful.length === 1 && meaningful[0] === "package.json") {
+          try {
+            const content = await fs.readFile(path.join(this.cwd, "package.json"), "utf8");
+            const pkg = JSON.parse(content);
+            if (!pkg.dependencies && !pkg.devDependencies) {
+              isEmpty = true;
+            } else {
+              isEmpty = false;
+            }
+          } catch {
+            isEmpty = true;
+          }
+        } else {
+          isEmpty = false;
+        }
+      }
+    } catch {
+      isEmpty = true;
+    }
+
+    let projectState = isEmpty ? "empty" : "active";
+    let detectedStackType = "unknown";
+    let detectedStacks = [];
+
+    if (isWordPress) {
+      detectedStackType = "WordPress context";
+      detectedStacks.push("wordpress");
+    } else if (isLaravel) {
+      detectedStackType = "backend context";
+      detectedStacks.push("laravel");
+    } else if (usesJsFramework) {
+      detectedStackType = "existing matching stack";
+      detectedStacks.push(usesJsFramework);
+    } else if (isCli) {
+      detectedStackType = "CLI package context";
+      detectedStacks.push("node");
+    } else if (stacks.includes("node")) {
+      detectedStackType = "existing matching stack";
+      detectedStacks.push("node");
+    } else if (stacks.includes("python") || stacks.includes("php")) {
+      detectedStackType = "backend context";
+      detectedStacks.push(...stacks);
+    } else if (projectState === "empty") {
+      detectedStackType = "empty project";
+    }
+
+    return {
+      projectState,
+      detectedStackType,
+      detectedStacks,
+      isWordPress,
+      isLaravel,
+      usesJsFramework,
+      isCli
+    };
+  }
+
+  async determineDecision(input = {}) {
+    const userRequest = input.userRequest || "";
+    const explicitApprovals = input.explicitApprovals || [];
+    
+    const ctx = input.projectContext || await this.detectContext();
+    const projectState = ctx.projectState || "active";
+    const detectedStacks = ctx.detectedStacks || [];
+    const isWordPress = ctx.isWordPress || false;
+    const isLaravel = ctx.isLaravel || false;
+    const isCli = ctx.isCli || false;
+    const usesJsFramework = ctx.usesJsFramework || null;
+
+    const parsed = parseRequest(userRequest);
+    const targetStack = parsed.targetStack;
+    const intent = parsed.intent;
+
+    let decision = "IMPLEMENT_IN_EXISTING_CONTEXT";
+    let allowedArtifactShape = "generic-code";
+    let forbiddenSubstitutes = ["success-without-validation"];
+    let validationRequired = ["build-or-equivalent"];
+    let approvalRequired = false;
+
+    if (intent === "audit") {
+      decision = "READ_ONLY_AUDIT";
+      allowedArtifactShape = "audit-report";
+      forbiddenSubstitutes.push("any-code-mutation");
+      validationRequired = [];
+    }
+    else if (intent === "docs") {
+      decision = "DOCS_ONLY";
+      allowedArtifactShape = "markdown";
+      forbiddenSubstitutes.push("unjustified-code-mutation");
+      validationRequired = [];
+    }
+    else if (intent === "release") {
+      decision = "RELEASE_OR_DEPLOY_REQUIRES_APPROVAL";
+      allowedArtifactShape = "package-tarball";
+      forbiddenSubstitutes.push("publish-without-approval");
+      validationRequired = ["release-readiness-or-equivalent"];
+      
+      const hasApproval = explicitApprovals.includes("npm-publish") || explicitApprovals.includes("deploy-production");
+      if (hasApproval) {
+        decision = "RELEASE_OR_DEPLOY_APPROVED";
+        approvalRequired = true;
+      }
+    }
+    else if (intent === "prototype") {
+      decision = "CREATE_STANDALONE_PROTOTYPE";
+      allowedArtifactShape = "standalone-html";
+      validationRequired = [];
+    }
+    else if (projectState === "empty") {
+      decision = "SCAFFOLD_AND_IMPLEMENT";
+      if (targetStack === "vue" || targetStack === "react") {
+        allowedArtifactShape = "runnable-framework-app";
+        forbiddenSubstitutes.push("standalone-html-as-framework-delivery", "loose-framework-files-without-runtime");
+        validationRequired.push("dependency-install-or-verification", "runtime-smoke-or-equivalent");
+      }
+    } else {
+      const hasConflict = (targetStack === "vue" && detectedStacks.includes("react")) ||
+                          (targetStack === "react" && detectedStacks.includes("vue")) ||
+                          (targetStack === "laravel" && !detectedStacks.includes("laravel") && detectedStacks.length > 0) ||
+                          (targetStack === "wordpress" && !detectedStacks.includes("wordpress") && detectedStacks.length > 0);
+      
+      if (hasConflict) {
+        decision = "BLOCK_STACK_CONFLICT";
+      } else if (targetStack === "laravel" && !detectedStacks.includes("laravel")) {
+        decision = "BLOCK_UNSUPPORTED_CONTEXT";
+      } else if (targetStack === "wordpress" && !detectedStacks.includes("wordpress")) {
+        decision = "BLOCK_UNSUPPORTED_CONTEXT";
+      } else {
+        if (targetStack === "vue" || targetStack === "react") {
+          decision = "IMPLEMENT_IN_EXISTING_CONTEXT";
+          allowedArtifactShape = "runnable-framework-app";
+          forbiddenSubstitutes.push("standalone-html-as-framework-delivery", "loose-framework-files-without-runtime");
+          validationRequired.push("dependency-install-or-verification", "runtime-smoke-or-equivalent");
+        } else if (targetStack === "cli" || isCli) {
+          decision = "CLI_COMMAND_INTEGRATION";
+          allowedArtifactShape = "bin-entry";
+        }
+      }
+    }
+
+    if (userRequest && userRequest.trim().length < 3) {
+      decision = "BLOCK_UNCLEAR_SCOPE";
+    }
+
+    return {
+      intent: intent === "implementation" ? "implementation" : intent,
+      requestedOutcome: targetStack === "vue" || targetStack === "react" ? "page" : (targetStack === "wordpress" ? "plugin-or-theme" : null),
+      requestedStack: targetStack,
+      requestedPlatform: targetStack === "wordpress" ? "wordpress" : null,
+      projectState,
+      detectedStacks,
+      decision,
+      allowedArtifactShape,
+      forbiddenSubstitutes,
+      validationRequired,
+      approvalRequired: explicitApprovals.length > 0
+    };
+  }
+}
+
+async function checkWordPressDirectRoot(cwd) {
+  // Check standard paths
+  const hasWpConfig = await fs.access(path.join(cwd, "wp-config.php")).then(() => true).catch(() => false);
+  const hasWpContent = await fs.access(path.join(cwd, "wp-content")).then(() => true).catch(() => false);
+  if (hasWpConfig || hasWpContent) {
+    return true;
+  }
+
+  // Check direct Theme root
+  const hasStyleCss = await fs.access(path.join(cwd, "style.css")).then(() => true).catch(() => false);
+  if (hasStyleCss) {
+    try {
+      const content = await fs.readFile(path.join(cwd, "style.css"), "utf8");
+      if (/\bTheme Name\s*:/i.test(content) || /\bTheme URI\s*:/i.test(content)) {
+        const otherIndicators = [
+          "functions.php",
+          "theme.json",
+          "index.php",
+          "front-page.php",
+          "single.php",
+          "page.php",
+          "archive.php",
+          "template-parts"
+        ];
+        for (const ind of otherIndicators) {
+          const exists = await fs.access(path.join(cwd, ind)).then(() => true).catch(() => false);
+          if (exists) {
+            return true;
+          }
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  // Check direct Plugin root
+  try {
+    const files = await fs.readdir(cwd);
+    for (const file of files) {
+      if (file.endsWith(".php")) {
+        const content = await fs.readFile(path.join(cwd, file), "utf8");
+        if (/\bPlugin Name\s*:/i.test(content)) {
+          return true;
+        }
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  return false;
 }

package/src/core/validation/evidence-collector.js

@@ -2,6 +2,9 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { QualityGuard } from "./quality-guard.js";
+import { DeliveryDecisionEngine } from "./delivery-decision-engine.js";
+import { ArtifactFidelityGate } from "./artifact-fidelity-gate.js";
+import { VisualVerifier } from "./visual-verifier.js";
 
 const VALIDATION_KINDS = new Set(["test", "build", "typecheck", "lint", "security", "smoke", "validate", "other"]);
 
@@ -27,7 +30,7 @@ function inferTaskKind(task = {}) {
 }
 
 export class EvidenceCollector {
-  constructor({ cwd, maxLogLength = 2000, timeout = 60000, taskSlug = null, mode = null, profile = "generic", branchRecovery = "NOT_RECORDED" } = {}) {
+  constructor({ cwd, maxLogLength = 2000, timeout = 60000, taskSlug = null, mode = null, profile = "generic", branchRecovery = "NOT_RECORDED", userRequest = null, explicitApprovals = [], visualDist = null, port = 8080 } = {}) {
     this.cwd = cwd;
     this.maxLogLength = maxLogLength;
     this.timeout = timeout;
@@ -35,6 +38,55 @@ export class EvidenceCollector {
     this.mode = mode;
     this.profile = profile;
     this.branchRecovery = branchRecovery;
+    this.userRequest = userRequest;
+    this.explicitApprovals = explicitApprovals;
+    this.visualDist = visualDist;
+    this.port = Number(port || 8080);
+  }
+
+  async findUserRequest() {
+    if (this.userRequest) return this.userRequest;
+
+    if (this.taskSlug) {
+      const ledgerPath = path.join(this.cwd, `.ai-workflow/history/${this.taskSlug}-ledger.json`);
+      try {
+        const content = await fs.readFile(ledgerPath, "utf8");
+        const events = JSON.parse(content);
+        const routeEvent = events.find(e => e.eventType === "routing");
+        if (routeEvent && routeEvent.data?.request) {
+          return routeEvent.data.request;
+        }
+        const startEvent = events.find(e => e.eventType === "implementation_start");
+        if (startEvent && startEvent.data?.prompt) {
+          return startEvent.data.prompt;
+        }
+      } catch {}
+    }
+
+    try {
+      const dir = path.join(this.cwd, ".ai-workflow/history");
+      const files = await fs.readdir(dir);
+      for (const file of files) {
+        if (file.endsWith("-ledger.json")) {
+          const content = await fs.readFile(path.join(dir, file), "utf8");
+          const events = JSON.parse(content);
+          const routeEvent = events.find(e => e.eventType === "routing");
+          if (routeEvent && routeEvent.data?.request) {
+            return routeEvent.data.request;
+          }
+        }
+      }
+    } catch {}
+
+    try {
+      const { execSync } = await import("node:child_process");
+      const branch = execSync("git branch --show-current", { cwd: this.cwd, encoding: "utf8" }).trim();
+      if (branch && branch !== "main" && branch !== "master" && branch.startsWith("feat/")) {
+        return branch.replace("feat/", "").replaceAll("-", " ");
+      }
+    } catch {}
+
+    return "";
   }
 
   runTask(task) {
@@ -95,6 +147,30 @@ export class EvidenceCollector {
     const behaviorTests = results.filter((result) => result.kind === "test");
     const passingBehaviorTest = behaviorTests.some((result) => result.status === "PASS");
 
+    const userRequest = await this.findUserRequest();
+    const engine = new DeliveryDecisionEngine({ cwd: this.cwd });
+    const projectContext = await engine.detectContext();
+    const deliveryDecision = await engine.determineDecision({
+      userRequest,
+      projectContext,
+      explicitApprovals: this.explicitApprovals || []
+    });
+
+    const fidelityGate = new ArtifactFidelityGate({
+      cwd: this.cwd,
+      deliveryClass: deliveryDecision.allowedArtifactShape === "runnable-framework-app" ? "framework-native-frontend" : (deliveryDecision.allowedArtifactShape === "wordpress" ? "wordpress-php" : "generic-code"),
+      userRequest,
+      explicitApprovals: this.explicitApprovals || []
+    });
+
+    const changedFiles = policyValidation.git?.changedFiles || [];
+    const artifactFidelityCheck = await fidelityGate.verifyRequestFidelity({
+      userRequest,
+      deliveryDecision,
+      projectContext,
+      changedFiles
+    });
+
     let overallStatus = "PASS";
     if (implementation && executableBehavior && tasks.length === 0) overallStatus = "BLOCKED";
     else if (results.some((result) => ["FAIL", "BLOCKED", "FAIL_QUALITY_GATE"].includes(result.status))) overallStatus = "FAIL_QUALITY_GATE";
@@ -102,6 +178,16 @@ export class EvidenceCollector {
     else if (["FAIL", "BLOCKED", "FAIL_QUALITY_GATE"].includes(policyValidation.overallStatus)) overallStatus = "FAIL_QUALITY_GATE";
     else if (results.some((result) => result.status === "PASS_WITH_NOTES") || policyValidation.overallStatus === "PASS_WITH_NOTES") overallStatus = "PASS_WITH_NOTES";
 
+    if (!artifactFidelityCheck || !artifactFidelityCheck.passed) {
+      overallStatus = "BLOCKED";
+    } else if (implementation) {
+      if (!deliveryDecision || !deliveryDecision.decision || deliveryDecision.decision.startsWith("BLOCK") || deliveryDecision.decision.includes("BLOCKED") || deliveryDecision.decision === "REQUIRE_EXPLICIT_AUTHORIZATION" || deliveryDecision.decision === "RELEASE_OR_DEPLOY_REQUIRES_APPROVAL") {
+        overallStatus = "BLOCKED";
+      } else if (results.length === 0 && executableBehavior && deliveryDecision.decision !== "DOCUMENTATION_ONLY" && deliveryDecision.decision !== "DOCS_ONLY" && deliveryDecision.decision !== "READ_ONLY_AUDIT") {
+        overallStatus = "BLOCKED";
+      }
+    }
+
     const limitations = [];
     if (implementation && executableBehavior && tasks.length === 0) limitations.push("No meaningful validation command was available for executable implementation work.");
     if (executableBehavior && behaviorTests.length === 0) {
@@ -111,6 +197,26 @@ export class EvidenceCollector {
       if (check.status === "PASS_WITH_NOTES" && check.reason) limitations.push(`${name}: ${check.reason}`);
     }
 
+    let visualEvidence = null;
+    if (this.visualDist) {
+      console.log(`\n--- Capturing Visual Evidence ---`);
+      console.log(`Serving ${this.visualDist} on port ${this.port}...`);
+      try {
+        const verifier = new VisualVerifier({ cwd: this.cwd, visualDist: this.visualDist, port: this.port });
+        const screenshots = await verifier.captureScreenshots();
+        visualEvidence = {
+          desktop: path.relative(this.cwd, screenshots[0]),
+          mobile: path.relative(this.cwd, screenshots[1])
+        };
+        console.log(`Visual evidence captured successfully:`);
+        console.log(`- Desktop: ${visualEvidence.desktop}`);
+        console.log(`- Mobile: ${visualEvidence.mobile}`);
+      } catch (err) {
+        console.error(`Error capturing visual evidence: ${err.message}`);
+        throw err;
+      }
+    }
+
     const evidence = {
       timestamp: new Date().toISOString(),
       taskSlug: this.taskSlug,
@@ -118,12 +224,15 @@ export class EvidenceCollector {
       workflowProfile: this.profile,
       branchRecovery: this.branchRecovery,
       branch: policyValidation.git?.branch || "unknown",
-      changedFiles: policyValidation.git?.changedFiles || [],
+      changedFiles,
       status: publicStatus(overallStatus),
       internalStatus: overallStatus,
       commands: results,
       checks: policyValidation.checks,
-      limitations
+      limitations,
+      deliveryDecision,
+      artifactFidelityCheck,
+      visualEvidence
     };
 
     if (writeArtifact) {

package/src/core/validation/visual-verifier.js

@@ -0,0 +1,159 @@
+import http from "node:http";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export class VisualVerifier {
+  constructor({ cwd = process.cwd(), visualDist = null, port = 8080 } = {}) {
+    this.cwd = cwd;
+    this.visualDist = visualDist;
+    this.port = Number(port || 8080);
+    this.server = null;
+  }
+
+  async startServer() {
+    if (!this.visualDist) {
+      throw new Error("No --visual-dist directory specified. Cannot start visual server.");
+    }
+    const distPath = path.resolve(this.cwd, this.visualDist);
+    this.server = http.createServer(async (req, res) => {
+      try {
+        const urlPath = req.url.split("?")[0];
+        const filePath = path.join(distPath, urlPath === "/" ? "index.html" : urlPath);
+        const content = await fs.readFile(filePath);
+        
+        const ext = path.extname(filePath).toLowerCase();
+        let contentType = "text/html";
+        if (ext === ".js" || ext === ".mjs") contentType = "application/javascript";
+        else if (ext === ".css") contentType = "text/css";
+        else if (ext === ".png") contentType = "image/png";
+        else if (ext === ".jpg" || ext === ".jpeg") contentType = "image/jpeg";
+        else if (ext === ".svg") contentType = "image/svg+xml";
+        
+        res.writeHead(200, { "Content-Type": contentType });
+        res.end(content);
+      } catch (err) {
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not Found");
+      }
+    });
+
+    await new Promise((resolve, reject) => {
+      this.server.listen(this.port, "127.0.0.1", (err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+
+  async closeServer() {
+    if (this.server) {
+      await new Promise((resolve) => this.server.close(resolve));
+      this.server = null;
+    }
+  }
+
+  async captureScreenshots() {
+    if (!this.visualDist) return [];
+
+    let playwright;
+    try {
+      playwright = await import("playwright");
+    } catch {
+      throw new Error(
+        "Playwright is required to capture visual evidence. Please install it using 'npm install -D playwright' and initialize browsers using 'npx playwright install'."
+      );
+    }
+
+    await this.startServer();
+    const browser = await playwright.chromium.launch();
+    const page = await browser.newPage();
+
+    const outputDir = path.join(this.cwd, ".evidence/visual");
+    await fs.mkdir(outputDir, { recursive: true });
+
+    const desktopPath = path.join(outputDir, "desktop.png");
+    const mobilePath = path.join(outputDir, "mobile.png");
+
+    try {
+      await page.goto(`http://127.0.0.1:${this.port}`);
+
+      // Desktop
+      await page.setViewportSize({ width: 1440, height: 900 });
+      await page.screenshot({ path: desktopPath, fullPage: true });
+
+      // Mobile
+      await page.setViewportSize({ width: 390, height: 844 });
+      await page.screenshot({ path: mobilePath, fullPage: true });
+    } finally {
+      await browser.close();
+      await this.closeServer();
+    }
+
+    return [desktopPath, mobilePath];
+  }
+
+  async runAccessibilityCheck() {
+    if (!this.visualDist) {
+      throw new Error("Accessibility check requires a target build directory specified via --visual-dist.");
+    }
+
+    let playwright;
+    try {
+      playwright = await import("playwright");
+    } catch {
+      throw new Error(
+        "Playwright is required to run accessibility checks. Please install it using 'npm install -D playwright' and initialize browsers using 'npx playwright install'."
+      );
+    }
+
+    await this.startServer();
+    const browser = await playwright.chromium.launch();
+    const page = await browser.newPage();
+
+    const outputDir = path.join(this.cwd, ".evidence/a11y");
+    await fs.mkdir(outputDir, { recursive: true });
+
+    try {
+      await page.goto(`http://127.0.0.1:${this.port}`);
+
+      // Read axe-core bundle
+      let axeScript = "";
+      try {
+        const axePath = path.join(this.cwd, "node_modules/axe-core/axe.min.js");
+        axeScript = await fs.readFile(axePath, "utf8");
+      } catch {
+        // Fallback: look in dev-kit node_modules
+        try {
+          // Resolve relative to current module path
+          const mainAxePath = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../../../node_modules/axe-core/axe.min.js");
+          axeScript = await fs.readFile(mainAxePath, "utf8");
+        } catch {
+          throw new Error("axe-core package is not installed. Please install axe-core using 'npm install -D axe-core'.");
+        }
+      }
+
+      await page.evaluate(axeScript);
+
+      const axeResults = await page.evaluate(() => {
+        return window.axe.run();
+      });
+
+      const reportPath = path.join(outputDir, "report.json");
+      await fs.writeFile(reportPath, JSON.stringify(axeResults, null, 2));
+
+      const criticalViolations = axeResults.violations.filter(v => v.impact === "critical");
+      const seriousViolations = axeResults.violations.filter(v => v.impact === "serious");
+
+      return {
+        passed: criticalViolations.length === 0,
+        reportPath,
+        violations: axeResults.violations,
+        critical: criticalViolations,
+        serious: seriousViolations
+      };
+    } finally {
+      await browser.close();
+      await this.closeServer();
+    }
+  }
+}