@williambeto/ai-workflow 2.3.5 → 2.3.7

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/dist-assets/docs/full-documentation.md

@@ -49,7 +49,7 @@ In an initialized consumer, use:
 - `.ai-workflow/opencode/agents/*.md`
 - `.ai-workflow/opencode/commands/*.md`
 - `.ai-workflow/opencode/skills/*/SKILL.md`
-- `.ai-workflow/docs/policies/*.md`
+- `.ai-workflow/opencode/docs/policies/*.md`
 - `.ai-workflow/QUICKSTART.md`
 
 Repository maintainers edit the packaged sources under `dist-assets/**`.

package/dist-assets/prompts/03-create-tech-plan.md

@@ -94,8 +94,8 @@ Follow these rules:
 2. Preserve the agreed scope.
 3. Inspect or reason from the current project structure.
 4. Follow existing project patterns first.
-5. Apply `docs/architecture-policy.md` before proposing structure (classify as `simple-site`, `feature-app`, `domain-app`, `package-tooling`, or `wordpress`).
-6. Apply `docs/design-patterns-policy.md` before proposing formal design patterns.
+5. Apply `opencode/docs/architecture-policy.md` before proposing structure (classify as `simple-site`, `feature-app`, `domain-app`, `package-tooling`, or `wordpress`).
+6. Apply `opencode/docs/design-patterns-policy.md` before proposing formal design patterns.
 7. Do not invent new architecture unless justified.
 8. Identify files likely to change.
 9. Identify files that should not change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williambeto/ai-workflow",
-  "version": "2.3.5",
+  "version": "2.3.7",
   "description": "AI Workflow Kit — OpenCode-first software delivery workflow with agents, commands, skills, validation, and evidence",
   "license": "MIT",
   "author": "José Willams",

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 = [] }) {
   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 });
   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/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
     };
   }
 

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

@@ -2,9 +2,11 @@ import fs from "node:fs/promises";
 import path from "node:path";
 
 export class ArtifactFidelityGate {
-  constructor({ cwd = process.cwd(), deliveryClass } = {}) {
+  constructor({ cwd = process.cwd(), deliveryClass, userRequest, explicitApprovals } = {}) {
     this.cwd = cwd;
     this.deliveryClass = deliveryClass;
+    this.userRequest = userRequest;
+    this.explicitApprovals = explicitApprovals;
   }
 
   async verify(changedFiles = []) {
@@ -16,7 +18,6 @@ export class ArtifactFidelityGate {
       for (const file of changedFiles) {
         const ext = path.extname(file).toLowerCase();
         
-        // 1. Forbid adding/modifying HTML files that are not SPA entry points
         if (ext === ".html" || ext === ".htm") {
           const basename = path.basename(file).toLowerCase();
           const isSpaEntry = basename === "index.html" && 
@@ -28,7 +29,6 @@ export class ArtifactFidelityGate {
             };
           }
 
-          // Check if SPA entry imports framework libraries via CDN script tags
           try {
             const content = await fs.readFile(path.join(this.cwd, file), "utf8");
             if (content.includes("unpkg.com") || content.includes("cdnjs.cloudflare.com") || content.includes("cdn.jsdelivr.net")) {
@@ -60,4 +60,279 @@ export class ArtifactFidelityGate {
 
     return { passed: true };
   }
+
+  async verifyRequestFidelity(arg) {
+    let userRequest = this.userRequest || "";
+    let deliveryDecision = this.deliveryDecision || {};
+    let projectContext = this.projectContext || {};
+    let changedFiles = [];
+    let explicitApprovals = this.explicitApprovals || [];
+
+    if (Array.isArray(arg)) {
+      changedFiles = arg;
+    } else if (arg && typeof arg === "object") {
+      userRequest = arg.userRequest || userRequest;
+      deliveryDecision = arg.deliveryDecision || deliveryDecision;
+      projectContext = arg.projectContext || projectContext;
+      changedFiles = arg.changedFiles || changedFiles;
+      explicitApprovals = arg.explicitApprovals || explicitApprovals;
+    }
+
+    const blockingDecisions = new Set([
+      "BLOCK_STACK_CONFLICT",
+      "BLOCK_UNCLEAR_SCOPE",
+      "BLOCK_UNSUPPORTED_CONTEXT",
+      "REQUIRE_EXPLICIT_AUTHORIZATION",
+      "RELEASE_OR_DEPLOY_REQUIRES_APPROVAL"
+    ]);
+
+    if (blockingDecisions.has(deliveryDecision?.decision)) {
+      const filtered = changedFiles.filter(file => 
+        !file.startsWith(".ai-workflow/") && 
+        !file.startsWith(".git/") && 
+        file !== "EVIDENCE.json" &&
+        file !== "EVIDENCE.temp.json"
+      );
+      return {
+        status: "BLOCKED",
+        passed: false,
+        reason: `Delivery decision is blocking: ${deliveryDecision.decision}`,
+        decision: deliveryDecision.decision,
+        checkedFiles: filtered,
+        violations: [`Blocking delivery decision: ${deliveryDecision.decision}`]
+      };
+    }
+
+    const filteredFiles = changedFiles.filter(file => 
+      !file.startsWith(".ai-workflow/") && 
+      !file.startsWith(".git/") && 
+      file !== "EVIDENCE.json" &&
+      file !== "EVIDENCE.temp.json"
+    );
+
+    const req = userRequest.toLowerCase();
+    const isReadOnly = /(inspect|audit|read-only|dependencies)/.test(req);
+    const isDocsOnly = /(document|doc|readme)/.test(req) && !req.includes("code");
+    const isRelease = /(release|publish|deploy)/.test(req);
+
+    const violations = [];
+
+    if (isReadOnly && filteredFiles.length > 0) {
+      violations.push("Read-only audit task mutated repository files mismatch.");
+    }
+
+    if (isDocsOnly) {
+      const codeChanged = filteredFiles.some(file => 
+        !file.endsWith(".md") && !file.endsWith(".txt") && !file.startsWith("docs/")
+      );
+      if (codeChanged) {
+        violations.push("Documentation-only task mutated codebase files without justification mismatch.");
+      }
+    }
+
+    if (isRelease) {
+      const approved = explicitApprovals.includes("npm-publish") || explicitApprovals.includes("deploy-production");
+      if (!approved) {
+        violations.push("Release/deploy task proceeds without explicit approval token mismatch.");
+      }
+    }
+
+    const reqReact = /(react|next)/.test(req);
+    const reqVue = /(vue|nuxt)/.test(req);
+    const reqBackend = /(laravel|django|rails|express|nest|fastify|flask)/.test(req);
+    const reqWp = /(wordpress|wp)/.test(req);
+    const reqCli = /(cli|command)/.test(req);
+
+    if (reqReact && this.deliveryClass === "standalone-web" && !/prototype/.test(req)) {
+      violations.push("React framework page requested, but a standalone HTML/CSS substitute mismatch was delivered instead.");
+    }
+    if (reqVue && this.deliveryClass === "standalone-web" && !/prototype/.test(req)) {
+      violations.push("Vue framework page requested, but a standalone HTML/CSS substitute mismatch was delivered instead.");
+    }
+
+    if (reqBackend && filteredFiles.length > 0) {
+      const isLaravel = /\blaravel\b/i.test(req);
+      const isDjango = /\bdjango\b/i.test(req);
+      const isExpressNestFastify = /\b(express|nest|fastify)\b/i.test(req);
+      const isRails = /\brails\b/i.test(req);
+
+      if (isLaravel) {
+        const isLaravelArtifact = filteredFiles.some(file => 
+          file === "composer.json" ||
+          file === "artisan" ||
+          file.startsWith("routes/") ||
+          file.startsWith("app/Http/Controllers/") ||
+          file.startsWith("app/Models/") ||
+          file.startsWith("app/Services/") ||
+          file.startsWith("tests/Feature/") ||
+          file.startsWith("tests/Unit/") ||
+          /(^|\/)(routes\/.*\.php|app\/Http\/Controllers\/.*\.php|app\/Models\/.*\.php|app\/Services\/.*\.php|tests\/Feature\/.*\.php|tests\/Unit\/.*\.php|artisan|composer\.json)$/.test(file)
+        );
+        if (!isLaravelArtifact) {
+          violations.push("Laravel endpoint/scaffold requested, but no valid Laravel files/structure mismatch was delivered.");
+        }
+      } else if (isDjango) {
+        const isDjangoArtifact = filteredFiles.some(file => 
+          file === "manage.py" ||
+          file === "requirements.txt" ||
+          file === "pyproject.toml" ||
+          file.endsWith("settings.py") ||
+          file.endsWith("urls.py") ||
+          file.endsWith("views.py") ||
+          file.endsWith("models.py") ||
+          file.endsWith("tests.py") ||
+          /(^|\/)(manage\.py|settings\.py|urls\.py|views\.py|models\.py|tests\.py|requirements\.txt|pyproject\.toml)$/.test(file)
+        );
+        if (!isDjangoArtifact) {
+          violations.push("Django backend requested, but no valid Django files/structure mismatch was delivered.");
+        }
+      } else if (isExpressNestFastify) {
+        const isExpressNestFastifyArtifact = filteredFiles.some(file => 
+          file === "package.json" ||
+          file.startsWith("src/routes/") ||
+          file.startsWith("src/controllers/") ||
+          file.startsWith("src/services/") ||
+          file.startsWith("tests/") ||
+          /(^|\/)(package\.json|src\/routes\/.*|src\/controllers\/.*|src\/services\/.*|tests\/.*|server\.[a-z]+|app\.[a-z]+|main\.[a-z]+)$/.test(file)
+        );
+        if (!isExpressNestFastifyArtifact) {
+          violations.push("Express/Fastify/Nest backend requested, but no valid Node.js server files/structure mismatch was delivered.");
+        }
+      } else if (isRails) {
+        const isRailsArtifact = filteredFiles.some(file => 
+          file === "Gemfile" ||
+          file === "config/routes.rb" ||
+          file.startsWith("app/controllers/") ||
+          file.startsWith("app/models/") ||
+          file.startsWith("app/services/") ||
+          file.startsWith("test/") ||
+          file.startsWith("spec/") ||
+          /(^|\/)(Gemfile|config\/routes\.rb|app\/controllers\/.*|app\/models\/.*|app\/services\/.*|test\/.*|spec\/.*)$/.test(file)
+        );
+        if (!isRailsArtifact) {
+          violations.push("Ruby on Rails backend requested, but no valid Rails files/structure mismatch was delivered.");
+        }
+      } else {
+        const isGenericBackendArtifact = filteredFiles.some(file => 
+          !file.includes("plain_script.py") &&
+          (
+            file.startsWith("app/") ||
+            file.startsWith("routes/") ||
+            file.startsWith("config/") ||
+            file.startsWith("src/controllers/") ||
+            file.startsWith("src/routes/") ||
+            file.startsWith("src/services/") ||
+            file.startsWith("backend/") ||
+            file.startsWith("server/") ||
+            file.startsWith("api/") ||
+            file.endsWith(".py") ||
+            file.endsWith(".php") ||
+            file.endsWith(".rb") ||
+            file.endsWith(".go")
+          )
+        );
+        if (!isGenericBackendArtifact) {
+          violations.push("Backend endpoint requested, but wrong backend artifact structure mismatch was delivered.");
+        }
+      }
+    }
+
+    if (reqCli && filteredFiles.length > 0) {
+      const isCliArtifact = filteredFiles.some(file => 
+        file.startsWith("bin/") || file.startsWith("src/commands/")
+      );
+      if (!isCliArtifact) {
+        violations.push("CLI command requested, but a loose script outside the executable bin/commands configuration mismatch was delivered.");
+      }
+    }
+
+    if (reqWp && filteredFiles.length > 0) {
+      let isWpArtifact = false;
+      for (const file of filteredFiles) {
+        const basename = path.basename(file);
+        const ext = path.extname(file).toLowerCase();
+
+        if (file.startsWith("wp-content/") || file === "wp-config.php") {
+          isWpArtifact = true;
+          break;
+        }
+
+        if (basename === "functions.php" ||
+            basename === "front-page.php" ||
+            basename === "single.php" ||
+            basename === "page.php" ||
+            basename === "archive.php" ||
+            basename === "theme.json" ||
+            file.startsWith("template-parts/") ||
+            file.includes("/template-parts/")) {
+          isWpArtifact = true;
+          break;
+        }
+        if (basename === "style.css") {
+          const hasHeader = await hasWpThemeHeader(this.cwd, file);
+          if (hasHeader) {
+            isWpArtifact = true;
+            break;
+          }
+        }
+        if (basename === "index.php") {
+          isWpArtifact = true; 
+          break;
+        }
+
+        if (basename === "uninstall.php" ||
+            basename === "composer.json" ||
+            file.startsWith("includes/") || file.includes("/includes/") ||
+            file.startsWith("admin/") || file.includes("/admin/") ||
+            file.startsWith("public/") || file.includes("/public/") ||
+            file.startsWith("src/") || file.includes("/src/")) {
+          isWpArtifact = true;
+          break;
+        }
+        if (ext === ".php") {
+          const hasHeader = await hasWpPluginHeader(this.cwd, file);
+          if (hasHeader) {
+            isWpArtifact = true;
+            break;
+          }
+        }
+      }
+
+      const hasHtml = filteredFiles.some(file => path.extname(file).toLowerCase() === ".html" || path.extname(file).toLowerCase() === ".htm");
+
+      if (!isWpArtifact || hasHtml) {
+        violations.push("WordPress plugin or theme requested, but files were delivered outside the WordPress structure or contained standalone HTML.");
+      }
+    }
+
+    const status = violations.length > 0 ? "BLOCKED" : "PASS";
+    return {
+      status,
+      passed: status === "PASS",
+      reason: violations.length > 0 ? `Fidelity violations: ${violations.join("; ")}` : "Verification passed",
+      decision: deliveryDecision.decision || this.deliveryClass,
+      checkedFiles: filteredFiles,
+      violations
+    };
+  }
+}
+
+async function hasWpThemeHeader(cwd, file) {
+  try {
+    const fullPath = path.join(cwd, file);
+    const content = await fs.readFile(fullPath, "utf8");
+    return /\bTheme Name\s*:/i.test(content) || /\bTheme URI\s*:/i.test(content);
+  } catch {
+    return false;
+  }
+}
+
+async function hasWpPluginHeader(cwd, file) {
+  try {
+    const fullPath = path.join(cwd, file);
+    const content = await fs.readFile(fullPath, "utf8");
+    return /\bPlugin Name\s*:/i.test(content) || /\bDescription\s*:/i.test(content);
+  } catch {
+    return false;
+  }
 }

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,8 @@ 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";
 
 const VALIDATION_KINDS = new Set(["test", "build", "typecheck", "lint", "security", "smoke", "validate", "other"]);
 
@@ -27,7 +29,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 = [] } = {}) {
     this.cwd = cwd;
     this.maxLogLength = maxLogLength;
     this.timeout = timeout;
@@ -35,6 +37,53 @@ export class EvidenceCollector {
     this.mode = mode;
     this.profile = profile;
     this.branchRecovery = branchRecovery;
+    this.userRequest = userRequest;
+    this.explicitApprovals = explicitApprovals;
+  }
+
+  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 +144,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 +175,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) {
@@ -118,12 +201,14 @@ 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
     };
 
     if (writeArtifact) {