@williambeto/ai-workflow 2.3.6 → 2.4.0

package/AGENTS.md

@@ -25,3 +25,8 @@ Atlas routes. Nexus owns discovery, requirements, and spec authoring. Orion owns
 ## Evidence
 
 Quick and standard work require only branch, changed areas, commands/results, and limitations in the handoff. Full/release/audit/security work may persist machine-generated evidence.
+
+## Core Concept
+
+AI Workflow is an npm CLI that installs agents, commands, skills, policies and templates into your repository.
+It guides coding agents from request to implementation, validation and evidence. AI Workflow Kit preserves workflow integrity so coding agents cannot skip from request to code to success without an explicit implementation path, proportional validation, and final evidence.

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.6",
+  "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" }) {
+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 });
+  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/execute.js

@@ -257,7 +257,9 @@ export async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverri
         taskSlug,
         mode: plan.mode,
         profile: plan.profile,
-        branchRecovery: gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : "NOT_REQUIRED"
+        branchRecovery: gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : "NOT_REQUIRED",
+        userRequest: naturalRequest,
+        explicitApprovals: process.env.AI_WORKFLOW_APPROVALS ? process.env.AI_WORKFLOW_APPROVALS.split(",").map(a => a.trim()) : []
       });
       const quality = await new QualityGuard({ cwd, taskSlug, mode: plan.mode }).verify();
       return combineValidation(evidence, quality);
@@ -329,7 +331,14 @@ export async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverri
       finalStatus = "FAIL_QUALITY_GATE";
     } else {
       // Workspace stabilized, now run Artifact Fidelity Gate
-      const fidelityResult = await finalizer.verifyFidelity(result.evidence?.changedFiles);
+      const fidelityResult = await finalizer.verifyFidelity({
+        userRequest: naturalRequest,
+        projectContext: result.evidence?.deliveryDecision?.projectContext || null,
+        deliveryDecision: result.evidence?.deliveryDecision || null,
+        changedFiles: result.evidence?.changedFiles || [],
+        evidence: result.evidence || null,
+        explicitApprovals: process.env.AI_WORKFLOW_APPROVALS ? process.env.AI_WORKFLOW_APPROVALS.split(",").map(a => a.trim()) : []
+      });
       if (!fidelityResult.passed) {
         console.log(`\n[FINALIZER BLOCKED] BLOCKED: Artifact fidelity check failed!`);
         console.log(`Reason: ${fidelityResult.reason}`);

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/evidence/evidence-ledger.js

@@ -50,4 +50,49 @@ export class EvidenceLedger {
     await fs.mkdir(path.dirname(targetPath), { recursive: true });
     await fs.writeFile(targetPath, JSON.stringify(this.events, null, 2), "utf8");
   }
+
+  async verifyRoleConfinement() {
+    const violations = [];
+    const events = this.events;
+    
+    const atlasImplements = events.some(e => e.actor === "Atlas" && (e.eventType === "implementation_start" || e.eventType === "implementation_complete"));
+    if (atlasImplements) {
+      violations.push("Atlas cannot implement directly");
+    }
+
+    const nexusMutates = events.some(e => e.actor === "Nexus" && e.eventType === "file_mutate");
+    if (nexusMutates) {
+      violations.push("Nexus cannot mutate files during discovery");
+    }
+
+    const sageValidates = events.some(e => e.actor === "Sage" && (e.eventType === "validation_start" || e.eventType === "validation_complete"));
+    const hasFidelity = events.some(e => e.eventType === "fidelity_check" || e.eventType === "fidelity_verification");
+    if (sageValidates && !hasFidelity) {
+      violations.push("Sage cannot validate without fidelity evidence");
+    }
+
+    const phoenixRemediates = events.find(e => e.actor === "Phoenix" && e.eventType === "remediation_start");
+    if (phoenixRemediates) {
+      const findings = phoenixRemediates.data?.findings;
+      if (!findings || findings.length === 0) {
+        violations.push("Phoenix cannot perform remediation without findings");
+      }
+    }
+
+    const orionReleases = events.find(e => e.actor === "Orion" && e.eventType === "release_start");
+    if (orionReleases) {
+      const approvals = orionReleases.data?.approvals;
+      if (!approvals || approvals.length === 0) {
+        violations.push("Orion cannot release without explicit approval");
+      }
+    }
+
+    const passed = violations.length === 0;
+    return {
+      passed,
+      status: passed ? "PASS" : "BLOCKED",
+      reason: violations.length > 0 ? `Role violations: ${violations.join("; ")}` : "Verification passed",
+      violations
+    };
+  }
 }

package/src/core/finalization/finalizer.js

@@ -32,16 +32,65 @@ export class Finalizer {
     }
   }
 
-  async verifyFidelity(changedFiles = null) {
+  async verifyFidelity(arg) {
+    let userRequest = null;
+    let projectContext = null;
+    let deliveryDecision = null;
+    let changedFiles = null;
+    let evidence = null;
+    let explicitApprovals = [];
+
+    if (Array.isArray(arg)) {
+      changedFiles = arg;
+    } else if (arg && typeof arg === "object") {
+      userRequest = arg.userRequest;
+      projectContext = arg.projectContext;
+      deliveryDecision = arg.deliveryDecision;
+      changedFiles = arg.changedFiles;
+      evidence = arg.evidence;
+      explicitApprovals = arg.explicitApprovals || [];
+    }
+
     const filesToCheck = changedFiles || this.getChangedFilesFromGit();
     const decisionEngine = new DeliveryDecisionEngine({ cwd: this.cwd });
-    const deliveryClass = await decisionEngine.determineClass(filesToCheck);
-    const fidelityGate = new ArtifactFidelityGate({ cwd: this.cwd, deliveryClass });
-    const result = await fidelityGate.verify(filesToCheck);
+    const actualProjectContext = projectContext || await decisionEngine.detectContext();
+    const actualUserRequest = userRequest || "";
+
+    const actualDeliveryDecision = deliveryDecision || await decisionEngine.determineDecision({
+      userRequest: actualUserRequest,
+      projectContext: actualProjectContext,
+      explicitApprovals
+    });
+
+    const actualDeliveryClass = await decisionEngine.determineClass(filesToCheck);
+
+    const fidelityGate = new ArtifactFidelityGate({
+      cwd: this.cwd,
+      deliveryClass: actualDeliveryClass,
+      userRequest: actualUserRequest,
+      explicitApprovals
+    });
+
+    const requestFidelity = await fidelityGate.verifyRequestFidelity({
+      userRequest: actualUserRequest,
+      deliveryDecision: actualDeliveryDecision,
+      projectContext: actualProjectContext,
+      changedFiles: filesToCheck,
+      evidence,
+      explicitApprovals
+    });
+
+    const verifyResult = await fidelityGate.verify(filesToCheck);
+
+    const passed = requestFidelity.passed && verifyResult.passed;
+    const reason = !requestFidelity.passed ? requestFidelity.reason : verifyResult.reason;
+
     return {
-      passed: result.passed,
-      reason: result.reason,
-      deliveryClass
+      passed,
+      status: requestFidelity.status || (passed ? "PASS" : "BLOCKED"),
+      reason,
+      deliveryClass: actualDeliveryClass,
+      requestFidelity
     };
   }