@williambeto/ai-workflow 2.3.7 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
+## [2.4.0] - 2026-06-20
+
+### Added
+- Native Visual Evidence capture in `collect-evidence` via `--visual-dist` and `--port` parameters, launching a static loopback server and capturing Chromium screenshots using Playwright.
+- CSS/HTML Design System Gate validation in `ArtifactFidelityGate` that automatically runs when the `frontend-design-system` skill is loaded in the repository, checking for CSS custom properties, inline style density, CDN scripts, and semantic HTML layout tags.
+- Native accessibility auditing command `npx aw validate --a11y` via Axe-core running inside Playwright, blocking critical violations and persisting reports in `.evidence/a11y/report.json`.
+- Standard `frontend-design-system` skill (`.agents/skills/frontend-design-system/SKILL.md`) to guide Astra and other agents through visual hierarchy, spacing grids, theme palettes, accessible contrast, and output rules.
+- Automated tests covering static loopback servers, Playwright screenshots, Axe-core checks, inline style gates, CSS tokens, and HTML semantics.
+
+## [2.3.7] - 2026-06-20
+
+### Changed
+- Bumped version to 2.3.7.
+
+## [2.3.6] - 2026-06-20
+
+### Added
+- Request-aware delivery decision and artifact fidelity gates (GREEN phase) to prevent false-positive completions in frontend/backend stack tasks.
+- Hardened check for blocking delivery decisions in `ArtifactFidelityGate` and `Finalizer`.
+- False-positive regression tests and release readiness audit documentation.
+
+### Fixed
+- Aligned WordPress root detection logic between `DeliveryDecisionEngine` and `ArtifactFidelityGate`.
+- Corrected architecture and design patterns policy relative paths in the technical plan prompt.
+- Normalized approved release decision string to `RELEASE_OR_DEPLOY_APPROVED`.
+
+## [2.3.5] - 2026-06-20
+
+### Fixed
+- Corrected the governance policy relative path header in all standard skill Markdown files.
+
+## [2.3.4] - 2026-06-20
+
+### Fixed
+- Corrected the mapping and resolution path of policies under `opencode/docs`.
+
+## [2.3.3] - 2026-06-20
+
+### Added
+- First phase implementation of the Delivery Decision Engine and Artifact Fidelity Gate checking for correct technology stacks.
+- Hardened PromptContracts and validation scripts for stack-aware quality checking.
+
 ## [2.3.2] - 2026-06-19
 
+
 ### Documentation
 - Clarified first-time usage with `npx @williambeto/ai-workflow init`.
 - Clarified local installed-package alias usage with `npx aw init`, `npx aw doctor`, and `npx aw run`.

package/dist-assets/skills/frontend-design-system/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: frontend-design-system
+description: Design system guidelines and rules for creating premium, consistent, and accessible interfaces.
+governance: ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md
+---
+
+# Frontend Design System PromptContract
+
+## Role
+Guides Astra and other agents in styling UI, hierarchy, and responsive layout states to build premium interfaces.
+
+## Objective
+Evolve technical governance to guarantee real visual and frontend quality by enforcing visual thesis, design tokens, responsive states, semantic HTML, and accessibility validations.
+
+## Trusted context
+- Project design system tokens (CSS custom properties)
+- HTML semantic markup standards
+- Accessible color ratios (WCAG 2.1 AA/AAA)
+- Visual asset registries (images, local SVGs)
+- Client styling guidelines
+
+## User input
+- Feature requirements and wireframes
+- Active UI components and styles
+- Target viewport dimensions (mobile, desktop)
+- Feedback on visual quality or layout defects
+
+## Constraints
+- **Visual Thesis & Deliberate Composition**: Layouts must be cohesive. Avoid generic grids, pill soup, or unorganized structures.
+- **Copy Specificity**: Never use placeholders ("Lorem Ipsum"). Write domain-specific, realistic copy.
+- **Strict Design System / CSS Gate**:
+  - CSS tokens must define a primary palette, background, surface, text styles, and spacing scale.
+  - Exposing excessive inline styles (`style="..."`) is prohibited.
+  - CDN dependencies for visual libraries (Tailwind, Bootstrap) are blocked unless explicitly authorized.
+- **Typography Scale**: Maintain a single `<h1>` per page. Line heights must be balanced: 1.1-1.25 for headings, 1.5-1.7 for readable body text.
+- **Acessibilidade (A11y)**: Must achieve WCAG compliance. Contrast ratio must be at least 4.5:1 for body text (3:1 for headings/large text). Semantic HTML elements (`<header>`, `<main>`, `<footer>`, `<nav>`, `<section>`) must structure the layout.
+- **Tokens de Cor & Spacing**: Spacing must adhere to an 8px-grid scale (e.g. 4px, 8px, 16px, 24px, 32px, 48px). Colors must use CSS custom properties: `--color-primary`, `--color-background`, `--color-surface`, `--color-text`.
+- **Regras Anti-Output Fraco**: Prevent empty blocks, broken states, and plain gradient fills with no concrete content.
+
+## Allowed tools
+- `view_file` to inspect existing design tokens, components, and templates.
+- `write_to_file` and `replace_file_content` to edit CSS variables and structured HTML markup.
+- `run_command` to execute validate command line checks (`npx aw validate --a11y` and `collect-evidence`).
+
+## Forbidden actions
+- Deploying raw HTML without CSS custom properties/tokens.
+- Injecting raw CDN CSS/JS libraries into page headers without authorization.
+- Committing unstyled layout states or missing loading/empty/error/success conditions.
+
+## Procedure
+1. **Analyze existing Design Tokens**: Check if the project already has CSS variables or custom properties. Adapt to the project's tokens if found, otherwise define a default safe set (primary, background, surface, text, space-*, font-*).
+2. **Draft Semantic Structure**: Build the UI skeleton using HTML5 semantic elements (`<header>`, `<main>`, etc.) with unique IDs for testing.
+3. **Apply Spacing and Typography Scales**: Implement the 8px grid system and a tight heading line-height / relaxed body line-height scale.
+4. **Implement UI States**: Ensure loading, empty, error, and success states are styled, fully functional, and visually robust.
+5. **A11y Verification**: Verify WCAG contrast levels. Run validation commands with `npm run validate` or `npx aw validate --a11y` to check for accessibility violations.
+6. **Collect Visual Evidence**: Capture desktop and mobile screenshots using `collect-evidence --visual-dist` to verify design fidelity.
+
+## Expected output schema
+The output must report:
+- CSS variables/tokens detected or introduced
+- Accessibility audit summary (Axe-core run results)
+- UI states implemented (loading, empty, error, success)
+- Semantic HTML tags list
+- Visual evidence location (`.evidence/visual/`)
+- Compliance decision: PASS | FAIL (with detailed reasons)
+
+## Evidence required
+- Screenshot artifacts in `.evidence/visual/` (mobile and desktop)
+- Axe-core accessibility report in `.evidence/a11y/`
+- Verified HTML/CSS files conforming to the design gates
+
+## Stop conditions
+- Absence of CSS variables/tokens defining colors or spacing
+- Axe-core report containing critical a11y violations
+- Exceeding inline style limits or using unauthorized CDNs
+
+## Failure modes
+- **White screenshots or rendering failures**: Local server path or assets not loaded.
+- **Unstyled outputs**: Styles not applied or missing CSS files.
+- **Broken layout states**: Misaligned responsive viewports or broken container grids.
+
+## Escalation rules
+- Report critical design system deviations to the frontend lead or escalate to the primary owner.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williambeto/ai-workflow",
-  "version": "2.3.7",
+  "version": "2.4.0",
   "description": "AI Workflow Kit — OpenCode-first software delivery workflow with agents, commands, skills, validation, and evidence",
   "license": "MIT",
   "author": "José Willams",
@@ -92,6 +92,7 @@
     "@semantic-release/npm": "^13.1.5",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
+    "axe-core": "^4.10.0",
     "markdownlint-cli": "^0.48.0",
     "playwright": "^1.60.0",
     "semantic-release": "^25.0.3",

package/src/cli.js

@@ -12,7 +12,8 @@ Usage:
   ai-workflow execute "<request>" [--task=<slug>] [--request="<request>"]
   ai-workflow run --spec-path=<path>
   ai-workflow init [--yes] [--force] [--dry-run] [--no-install] [--no-overwrite] [--gemini] [--claude] [--codex] [--antigravity] [--profile=<profile>]
-  ai-workflow collect-evidence [--task=<slug>] [--mode=<quick|standard|full>] [--dry-run]
+  ai-workflow validate [--a11y] [--visual-dist=<path>] [--port=<port>]
+  ai-workflow collect-evidence [--task=<slug>] [--mode=<quick|standard|full>] [--dry-run] [--visual-dist=<path>] [--port=<port>]
   ai-workflow doctor
 
 Commands:
@@ -30,6 +31,8 @@ function parseFlags(args) {
   const taskArg = args.find((arg) => arg.startsWith("--task="));
   const modeArg = args.find((arg) => arg.startsWith("--mode="));
   const requestArg = args.find((arg) => arg.startsWith("--request="));
+  const visualDistArg = args.find((arg) => arg.startsWith("--visual-dist="));
+  const portArg = args.find((arg) => arg.startsWith("--port="));
   const profileIdx = args.indexOf("--profile");
   const profileVal = profileEqArg
     ? profileEqArg.replace("--profile=", "")
@@ -52,7 +55,10 @@ function parseFlags(args) {
     profile: profileVal || undefined,
     taskSlug: taskArg ? taskArg.replace("--task=", "") : undefined,
     mode: modeArg ? modeArg.replace("--mode=", "") : undefined,
-    request: requestArg ? requestArg.replace("--request=", "") : undefined
+    request: requestArg ? requestArg.replace("--request=", "") : undefined,
+    visualDist: visualDistArg ? visualDistArg.replace("--visual-dist=", "") : undefined,
+    port: portArg ? portArg.replace("--port=", "") : undefined,
+    a11y: args.includes("--a11y")
   };
 }
 
@@ -104,7 +110,27 @@ export async function runCli(args) {
   if (command === "collect-evidence") {
     const flags = parseFlags(args.slice(1));
     if (flags.mode && !["quick", "standard", "full"].includes(flags.mode)) throw new Error("--mode must be quick, standard, or full");
-    await runCollectEvidence({ cwd: process.cwd(), taskSlug: flags.taskSlug, mode: flags.mode, dryRun: flags.dryRun });
+    await runCollectEvidence({ 
+      cwd: process.cwd(), 
+      taskSlug: flags.taskSlug, 
+      mode: flags.mode, 
+      dryRun: flags.dryRun,
+      visualDist: flags.visualDist,
+      port: flags.port
+    });
+    return;
+  }
+
+  if (command === "validate") {
+    const flags = parseFlags(args.slice(1));
+    const { runValidate } = await import("./commands/validate.js");
+    await runValidate({
+      cwd: process.cwd(),
+      taskSlug: flags.taskSlug,
+      a11y: flags.a11y,
+      visualDist: flags.visualDist,
+      port: flags.port
+    });
     return;
   }
 

package/src/commands/collect-evidence.js

@@ -5,13 +5,13 @@ import { buildDeliverySummary, formatDeliverySummary } from "../core/validation/
 import fs from "node:fs/promises";
 import path from "node:path";
 
-export async function runCollectEvidence({ cwd, exitOnError = true, taskSlug = null, mode = null, dryRun = false, profile = "generic", branchRecovery = "NOT_RECORDED", userRequest = null, explicitApprovals = [] }) {
+export async function runCollectEvidence({ cwd, exitOnError = true, taskSlug = null, mode = null, dryRun = false, profile = "generic", branchRecovery = "NOT_RECORDED", userRequest = null, explicitApprovals = [], visualDist = null, port = null }) {
   const qualityGuard = new QualityGuard({ cwd, taskSlug, mode });
   const planner = new ValidationPlanner({ cwd, qualityGuard });
   const tasks = await planner.plan(profile);
 
   const persist = !dryRun && mode === "full";
-  const collector = new EvidenceCollector({ cwd, timeout: 60000, taskSlug, mode, profile, branchRecovery, userRequest, explicitApprovals });
+  const collector = new EvidenceCollector({ cwd, timeout: 60000, taskSlug, mode, profile, branchRecovery, userRequest, explicitApprovals, visualDist, port });
   const evidence = await collector.collect(tasks, { writeArtifact: persist });
   const summary = buildDeliverySummary({ evidence });
 

package/src/commands/validate.js

@@ -0,0 +1,81 @@
+import { EvidenceCollector } from "../core/validation/evidence-collector.js";
+import { QualityGuard } from "../core/validation/quality-guard.js";
+import { ValidationPlanner } from "../core/validation/validation-planner.js";
+import { VisualVerifier } from "../core/validation/visual-verifier.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function runValidate({ cwd = process.cwd(), exitOnError = true, taskSlug = null, a11y = false, visualDist = null, port = 8080 }) {
+  console.log("--- Running Validation ---");
+  const qualityGuard = new QualityGuard({ cwd, taskSlug, mode: "standard" });
+  const planner = new ValidationPlanner({ cwd, qualityGuard });
+  const tasks = await planner.plan("standard");
+
+  const collector = new EvidenceCollector({ cwd, timeout: 60000, taskSlug, mode: "standard" });
+  const results = [];
+  
+  for (const task of tasks) {
+    console.log(`Running validation task: ${task.name}...`);
+    const res = collector.runTask(task);
+    results.push(res);
+    console.log(`- Status: ${res.status} (${res.summary})`);
+  }
+
+  let a11yResult = null;
+  if (a11y) {
+    if (!visualDist) {
+      throw new Error("Accessibility audit (--a11y) requires a target build directory specified via --visual-dist=<path>.");
+    }
+    console.log(`\n--- Running Accessibility Audit ---`);
+    console.log(`Serving ${visualDist} on port ${port}...`);
+    try {
+      const verifier = new VisualVerifier({ cwd, visualDist, port });
+      a11yResult = await verifier.runAccessibilityCheck();
+      console.log(`Accessibility audit complete.`);
+      console.log(`- Critical violations: ${a11yResult.critical.length}`);
+      console.log(`- Serious violations: ${a11yResult.serious.length}`);
+      console.log(`- Report saved to: ${path.relative(cwd, a11yResult.reportPath)}`);
+    } catch (err) {
+      console.error(`Accessibility audit failed: ${err.message}`);
+      if (exitOnError) process.exit(1);
+      throw err;
+    }
+  }
+
+  // Load future configuration if present
+  let config = {};
+  try {
+    const configContent = await fs.readFile(path.join(cwd, "ai-workflow.config.json"), "utf8");
+    config = JSON.parse(configContent);
+  } catch {}
+
+  const hasFailure = results.some((r) => ["FAIL", "BLOCKED", "FAIL_QUALITY_GATE"].includes(r.status));
+  
+  let hasA11yFailure = false;
+  if (a11yResult) {
+    const criticalIsBlocker = true; // Critical violations are always blockers
+    const seriousIsBlocker = config.a11y?.seriousAsBlocker === true;
+    
+    if (criticalIsBlocker && a11yResult.critical.length > 0) {
+      hasA11yFailure = true;
+      console.error(`Accessibility FAILED: ${a11yResult.critical.length} critical accessibility violations detected.`);
+    }
+    if (a11yResult.serious.length > 0) {
+      if (seriousIsBlocker) {
+        hasA11yFailure = true;
+        console.error(`Accessibility FAILED: ${a11yResult.serious.length} serious accessibility violations detected (blocked by configuration).`);
+      } else {
+        console.warn(`Accessibility WARNING: ${a11yResult.serious.length} serious accessibility violations detected.`);
+      }
+    }
+  }
+
+  if (hasFailure || hasA11yFailure) {
+    console.log("\nValidation FAILED.");
+    if (exitOnError) process.exit(1);
+    return { passed: false, results, a11yResult };
+  }
+
+  console.log("\nValidation PASSED.");
+  return { passed: true, results, a11yResult };
+}

package/src/core/validation/artifact-fidelity-gate.js

@@ -58,6 +58,14 @@ export class ArtifactFidelityGate {
       }
     }
 
+    const frontendViolations = await this.verifyFrontendFidelity(changedFiles);
+    if (frontendViolations && frontendViolations.length > 0) {
+      return {
+        passed: false,
+        reason: frontendViolations.join("; ")
+      };
+    }
+
     return { passed: true };
   }
 
@@ -305,6 +313,11 @@ export class ArtifactFidelityGate {
       }
     }
 
+    const frontendViolations = await this.verifyFrontendFidelity(filteredFiles);
+    if (frontendViolations && frontendViolations.length > 0) {
+      violations.push(...frontendViolations);
+    }
+
     const status = violations.length > 0 ? "BLOCKED" : "PASS";
     return {
       status,
@@ -315,6 +328,79 @@ export class ArtifactFidelityGate {
       violations
     };
   }
+
+  async verifyFrontendFidelity(changedFiles) {
+    const dsSkillPath1 = path.join(this.cwd, ".agents/skills/frontend-design-system/SKILL.md");
+    const dsSkillPath2 = path.join(this.cwd, ".agents/skills/frontend_design_system/SKILL.md");
+    const hasDesignSystemSkill = await fs.access(dsSkillPath1).then(() => true).catch(() => false) ||
+                                 await fs.access(dsSkillPath2).then(() => true).catch(() => false);
+    if (!hasDesignSystemSkill) {
+      return null;
+    }
+
+    const uiFiles = changedFiles.filter((file) =>
+      /\.(tsx|jsx|vue|html|css|scss|less|blade\.php)$/.test(file)
+    );
+    if (uiFiles.length === 0) return null;
+
+    const violations = [];
+    let cssContentCombined = "";
+    let htmlContentCombined = "";
+    let styleAttrsCount = 0;
+
+    for (const file of uiFiles) {
+      try {
+        const fullPath = path.join(this.cwd, file);
+        const content = await fs.readFile(fullPath, "utf8");
+
+        if (/\.(css|scss|less|vue|tsx|jsx)$/.test(file)) {
+          cssContentCombined += content;
+        }
+        if (/\.(html|vue|tsx|jsx|blade\.php)$/.test(file)) {
+          htmlContentCombined += content;
+          
+          // Match inline style attributes
+          const inlineStyles = content.match(/style\s*=\s*["']/g) || [];
+          styleAttrsCount += inlineStyles.length;
+
+          // CDN Checks
+          if (/(unpkg\.com|cdnjs\.cloudflare\.com|cdn\.jsdelivr\.net|tailwindcss|bootstrap)/i.test(content)) {
+            const isApproved = (this.explicitApprovals || []).some(app => 
+              /cdn-styles|tailwind|bootstrap/i.test(app)
+            );
+            if (!isApproved) {
+              violations.push(`Fidelity Violation: standalone external CDN style/library dependency detected in '${file}' without explicit authorization.`);
+            }
+          }
+        }
+      } catch {
+        // ignore
+      }
+    }
+
+    // 1. Tokens CSS mínimos Check
+    const hasRules = cssContentCombined.includes("{");
+    const hasCssVars = /--[a-zA-Z0-9_-]+\s*:/g.test(cssContentCombined);
+    if (hasRules && !hasCssVars) {
+      violations.push("Fidelity Violation: Design System token mismatch. No CSS custom properties (variables) detected in changed UI stylesheets.");
+    }
+
+    // 2. Excesso de style="..."
+    if (styleAttrsCount > 5) {
+      violations.push(`Fidelity Violation: excessive inline styles detected (${styleAttrsCount} style="..." declarations). Use CSS classes or utility classes instead.`);
+    }
+
+    // 3. HTML principal tags semânticas básicas Check
+    if (htmlContentCombined.length > 0) {
+      const hasSemanticTags = /<(header|main|footer|nav|section)\b/i.test(htmlContentCombined);
+      const hasH1 = /<h1\b/i.test(htmlContentCombined);
+      if (!hasSemanticTags && !hasH1) {
+        violations.push("Fidelity Violation: HTML layout structure lacks basic semantic elements (<header>, <main>, <footer>, <nav>, <section>) or <h1> tag.");
+      }
+    }
+
+    return violations;
+  }
 }
 
 async function hasWpThemeHeader(cwd, file) {

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

@@ -4,6 +4,7 @@ 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"]);
 
@@ -29,7 +30,7 @@ function inferTaskKind(task = {}) {
 }
 
 export class EvidenceCollector {
-  constructor({ cwd, maxLogLength = 2000, timeout = 60000, taskSlug = null, mode = null, profile = "generic", branchRecovery = "NOT_RECORDED", userRequest = null, explicitApprovals = [] } = {}) {
+  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;
@@ -39,6 +40,8 @@ export class EvidenceCollector {
     this.branchRecovery = branchRecovery;
     this.userRequest = userRequest;
     this.explicitApprovals = explicitApprovals;
+    this.visualDist = visualDist;
+    this.port = Number(port || 8080);
   }
 
   async findUserRequest() {
@@ -194,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,
@@ -208,7 +231,8 @@ export class EvidenceCollector {
       checks: policyValidation.checks,
       limitations,
       deliveryDecision,
-      artifactFidelityCheck
+      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();
+    }
+  }
+}