@williambeto/ai-workflow 2.8.0 → 2.8.2

package/{chunk-XW747GIG.js → chunk-H7GIKXFO.js}

@@ -112,17 +112,17 @@ var StackDetector = class {
 // src/core/validation/delivery-decision-engine.ts
 import fs2 from "fs/promises";
 import path2 from "path";
-function parseRequest(request = "") {
+function parseDeliveryRequest(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 (/\breact\b|\bnext(?:\.js|js)\b|\bnext\s+js\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)) {
+  else if (/\b(laravel|django|rails|express|nest|fastify|flask)\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";
+  else if (/\b(cli|command[- ]line|executable|bin)\b/.test(req) || /\b(add|create|implement|build|scaffold)\b.{0,40}\bcommand\b/.test(req)) targetStack = "cli";
   let intent = "implementation";
   if (/\b(document|doc|readme)\b/.test(req) || /\b(create|add|write|update|edit)\b.*\b[\w.-]+\.md\b/.test(req)) intent = "docs";
   else if (/\b(audit|security|inspect|dependencies)\b/.test(req)) intent = "audit";
@@ -281,7 +281,7 @@ var DeliveryDecisionEngine = class {
     const isLaravel = ctx.isLaravel || false;
     const isCli = ctx.isCli || false;
     const usesJsFramework = ctx.usesJsFramework || null;
-    const parsed = parseRequest(userRequest);
+    const parsed = parseDeliveryRequest(userRequest);
     const targetStack = parsed.targetStack;
     const intent = parsed.intent;
     let decision = "IMPLEMENT_IN_EXISTING_CONTEXT";
@@ -289,6 +289,7 @@ var DeliveryDecisionEngine = class {
     let forbiddenSubstitutes = ["success-without-validation"];
     let validationRequired = ["build-or-equivalent"];
     let approvalRequired = false;
+    let reason = null;
     if (intent === "audit") {
       decision = "READ_ONLY_AUDIT";
       allowedArtifactShape = "audit-report";
@@ -321,13 +322,22 @@ var DeliveryDecisionEngine = class {
         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;
+      const requestedFrontend = targetStack === "vue" || targetStack === "react" || targetStack === "svelte-or-angular";
+      const detectedFrontend = detectedStacks.find((stack) => ["react", "next", "vue", "nuxt", "svelte", "@angular/core", "quasar"].includes(stack));
+      const frontendMatches = targetStack === "react" && ["react", "next"].includes(detectedFrontend || "") || targetStack === "vue" && ["vue", "nuxt", "quasar"].includes(detectedFrontend || "") || targetStack === "svelte-or-angular" && ["svelte", "@angular/core"].includes(detectedFrontend || "");
+      const hasConflict = requestedFrontend && Boolean(detectedFrontend) && !frontendMatches || targetStack === "laravel" && !detectedStacks.includes("laravel") && detectedStacks.length > 0 || targetStack === "wordpress" && !detectedStacks.includes("wordpress") && detectedStacks.length > 0;
       if (hasConflict) {
         decision = "BLOCK_STACK_CONFLICT";
+        reason = `Requested stack '${targetStack}' conflicts with the active project context (${detectedStacks.join(", ") || "unknown"}).`;
+      } else if (requestedFrontend && !frontendMatches) {
+        decision = "BLOCK_UNSUPPORTED_CONTEXT";
+        reason = `Requested stack '${targetStack}' is not present in the active project context.`;
       } else if (targetStack === "laravel" && !detectedStacks.includes("laravel")) {
         decision = "BLOCK_UNSUPPORTED_CONTEXT";
+        reason = "Laravel was requested, but the active project is not a Laravel project.";
       } else if (targetStack === "wordpress" && !detectedStacks.includes("wordpress")) {
         decision = "BLOCK_UNSUPPORTED_CONTEXT";
+        reason = "WordPress was requested, but the active project is not a WordPress project.";
       } else {
         if (targetStack === "vue" || targetStack === "react") {
           decision = "IMPLEMENT_IN_EXISTING_CONTEXT";
@@ -342,6 +352,7 @@ var DeliveryDecisionEngine = class {
     }
     if (userRequest && userRequest.trim().length < 3) {
       decision = "BLOCK_UNCLEAR_SCOPE";
+      reason = "The request is too short to establish a safe delivery scope.";
     }
     return {
       intent: intent === "implementation" ? "implementation" : intent,
@@ -354,7 +365,9 @@ var DeliveryDecisionEngine = class {
       allowedArtifactShape,
       forbiddenSubstitutes,
       validationRequired,
-      approvalRequired: explicitApprovals.length > 0
+      approvalRequired: explicitApprovals.length > 0,
+      deliveryOutcome: decision.startsWith("BLOCK_") ? "NEEDS_CLARIFICATION" : null,
+      reason
     };
   }
 };
@@ -531,11 +544,12 @@ var ArtifactFidelityGate = class {
         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);
+    const requestedStack = Object.hasOwn(deliveryDecision, "requestedStack") ? deliveryDecision.requestedStack : parseDeliveryRequest(userRequest).targetStack;
+    const reqReact = requestedStack === "react";
+    const reqVue = requestedStack === "vue";
+    const reqBackend = requestedStack === "backend" || requestedStack === "laravel";
+    const reqWp = requestedStack === "wordpress";
+    const reqCli = requestedStack === "cli";
     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.");
     }
@@ -746,10 +760,321 @@ async function hasWpPluginHeader(cwd, file) {
   }
 }
 
+// src/core/request-router.ts
+import path4 from "path";
+import fs4 from "fs";
+var RequestRouter = class {
+  cwd;
+  constructor({ cwd = process.cwd() } = {}) {
+    this.cwd = cwd;
+  }
+  /**
+   * Understands and classifies a natural language request.
+   */
+  understand(request) {
+    const text = String(request).trim();
+    if (!text) {
+      throw new Error("Cannot classify an empty request.");
+    }
+    const { operationType, requestedCapability } = this.extractCapability(text);
+    const mutationIntent = this.determineMutationIntent(text, operationType);
+    const deliveryMode = this.determineDeliveryMode(text, mutationIntent);
+    const capabilityRoles = this.determineCapabilityRoles(text);
+    const riskAssessment = this.determineRiskAssessment(text, mutationIntent);
+    const riskLevel = riskAssessment.riskLevel;
+    const { safetyConstraints, requiredEvidence } = this.determineSafetyAndEvidence(text, mutationIntent);
+    return {
+      rawRequest: text,
+      taskGoal: `Perform ${operationType} operation under ${mutationIntent} intent`,
+      requestedActor: void 0,
+      invalidActor: void 0,
+      requestedCapability,
+      capabilityRoles,
+      operationType,
+      mutationIntent,
+      deliveryMode,
+      riskLevel,
+      requiredEvidence,
+      safetyConstraints,
+      specPolicy: riskAssessment.specPolicy,
+      matchedSignals: riskAssessment.matchedSignals,
+      riskDrivers: riskAssessment.riskDrivers
+    };
+  }
+  extractCapability(text) {
+    let operationType = "explain";
+    let requestedCapability = void 0;
+    const capabilityMappings = [
+      { op: "discover", pattern: /\b(discover|inspect|map|scan|structure|architecture|repo|search|find)\b/i },
+      { op: "validate", pattern: /\b(validate|audit|review|check|verify|test)\b/i },
+      { op: "implement", pattern: /\b(implement|implementa|build|create|crie|cria|add|develop|write|change|modify|atualiza|atualizar|refatora|refatorar)\b/i },
+      { op: "remediate", pattern: /\b(remediate|remedia|heal|healing)\b/i },
+      { op: "fix", pattern: /\b(fix|repair|correct|corrige|corrigir|solve)\b/i },
+      { op: "release", pattern: /\b(release|tag|prepare release|prepara(?:r)?\s+(?:a\s+)?release)\b/i },
+      { op: "deploy", pattern: /\b(deploy|publish|push|produção|producao)\b/i }
+    ];
+    for (const mapping of capabilityMappings) {
+      const match = text.match(mapping.pattern);
+      if (match) {
+        operationType = mapping.op;
+        requestedCapability = match[1];
+        break;
+      }
+    }
+    return { operationType, requestedCapability };
+  }
+  determineMutationIntent(text, operationType) {
+    const writePatterns = /\b(implement|implementa|build|fix|corrige|write|change|modify|create|crie|cria|add|refactor|refatora|refatorar|update|atualiza|atualizar)\b/i;
+    const readOnlyPatterns = /\b(analyze|check|inspect|review|find|search|show|list|read|view|verify|validate|discover|map)\b/i;
+    let mutationIntent = "write";
+    if (/\b(read-only|readonly)\b/i.test(text)) {
+      mutationIntent = "readonly";
+    } else if (writePatterns.test(text)) {
+      mutationIntent = "write";
+    } else if (readOnlyPatterns.test(text) || ["discover", "validate"].includes(operationType)) {
+      mutationIntent = "readonly";
+    }
+    if (/\b(publish|release|deploy|produção|producao|push to npm|push to remote)\b/i.test(text)) {
+      mutationIntent = "publish";
+    }
+    return mutationIntent;
+  }
+  determineDeliveryMode(text, mutationIntent) {
+    if (mutationIntent === "readonly") return "answer-only";
+    const explicitAnswerOnlyMarker = /\b(answer only|preview only|example only|snippet only|apenas (?:responda|mostre|um exemplo|um trecho)|somente (?:resposta|preview|exemplo|trecho))\b/i;
+    const workspaceTarget = "(?:files?|workspace|repository|repo|code(?:base)?|project)";
+    const portugueseWorkspaceTarget = "(?:arquivos?|workspace|reposit[o\xF3]rio|repo|c[o\xF3]digo|codebase|projeto)";
+    const explicitNoWorkspaceEdit = new RegExp(
+      `\\b(?:(?:without\\s+(?:editing|changing|modifying)|(?:do not|don't)\\s+(?:edit|change|modify))\\s+(?:the\\s+)?${workspaceTarget}|no\\s+${workspaceTarget}\\s+changes?|(?:sem\\s+(?:editar|alterar|modificar)|n[a\xE3]o\\s+(?:editar|alterar|modificar|edite|altere|modifique))\\s+(?:(?:os?|as?)\\s+)?${portugueseWorkspaceTarget})\\b`,
+      "i"
+    );
+    const standaloneNoEdit = /(?:\b(?:without\s+(?:editing|changing|modifying)|(?:do not|don't)\s+(?:edit|change|modify)|sem\s+(?:editar|alterar|modificar)|n[aã]o\s+(?:editar|alterar|modificar|edite|altere|modifique)))\s*[.!?]?\s*$/i;
+    return explicitAnswerOnlyMarker.test(text) || explicitNoWorkspaceEdit.test(text) || standaloneNoEdit.test(text) ? "answer-only" : "workspace";
+  }
+  determineCapabilityRoles(text) {
+    const roles = [];
+    const add = (role, pattern) => {
+      if (pattern.test(text)) roles.push(role);
+    };
+    add("frontend-development", /\b(frontend|react|vue|angular|svelte|component|interface|ui|css|html)\b/i);
+    add("backend-development", /\b(backend|api|endpoint|server|database|laravel|django|express|nest|fastify)\b/i);
+    add("documentation", /\b(document|documentation|docs?|readme|markdown)\b/i);
+    add("qa-workflow", /\b(test|tests|validate|audit|review|verify|quality)\b/i);
+    add("release-workflow", /\b(release|publish|deploy|tag)\b/i);
+    return [...new Set(roles)];
+  }
+  determineRiskAssessment(text, mutationIntent) {
+    const matchedSignals = [];
+    const add = (signal, pattern) => {
+      if (pattern.test(text)) {
+        matchedSignals.push(signal);
+        return true;
+      }
+      return false;
+    };
+    const taskTypeSignals = {
+      docsCopy: add("task:docs-copy", /\b(README|docs?|documenta[cç][aã]o|typo|copy|frase|comment|coment[áa]rio)\b/i),
+      refactor: add("task:refactor", /\b(refactor|refatora|refatorar|simplificar|mais simples de manter|manuten[cç][aã]o)\b/i),
+      noBehaviorChange: add("scope:no-behavior-change", /\b(sem alterar (?:o )?comportamento|without changing behavior|without behaviour change|no behavior change|comportamento existente)\b/i),
+      landingPage: add("task:landing-page", /\b(landing page|hotsite|p[áa]gina de venda|p[áa]gina comercial)\b/i),
+      dashboard: add("task:dashboard", /\b(dashboard|painel)\b/i),
+      bugfix: add("task:bugfix", /\b(bug|fix|corrige|corrigir|erro|falha|n[aã]o envia|não envia)\b/i),
+      release: add("task:release", /\b(release|deploy|produ[cç][aã]o|publish|publicar|lan[cç]amento)\b/i)
+    };
+    const domainRiskSignals = {
+      adult: add("domain:adult", /\b(er[óo]tic[oa]s?|adult[oa]s?|sexual|sexo|porn(?:o|ografia)?|18\+)\b/i),
+      auth: add("domain:auth", /\b(login|auth|autentica[cç][aã]o|autoriza[cç][aã]o|permiss(?:ão|oes|ões)|admin|administrador|roles?|rbac)\b/i),
+      payment: add("domain:payment", /\b(pagamento|checkout|billing|cobran[cç]a|fatura[cç][aã]o|assinatura|cart[aã]o|stripe|paypal)\b/i),
+      securityGovernance: add("domain:security-governance", /\b(SECURITY\.md|seguran[cç]a|security policy|pol[ií]tica de seguran[cç]a|governance|governan[cç]a|compliance|branch safety)\b/i)
+    };
+    const impactSignals = {
+      personalData: add("impact:personal-data", /\b(leads?|dados pessoais|personal data|crm|contatos?|contactos?|clientes?|exporta[cç][aã]o|exportar|armazenamento|armazenar|integra[cç][aã]o|integrar)\b/i),
+      productionRelease: mutationIntent === "publish" || add("impact:production-release", /\b(produ[cç][aã]o|release|deploy|publish|publicar|npm)\b/i),
+      adminPermissions: add("impact:admin-permissions", /\b(admin|administrador|permiss(?:ão|oes|ões)|roles?|rbac)\b/i)
+    };
+    if (mutationIntent === "publish" && !matchedSignals.includes("impact:production-release")) {
+      matchedSignals.push("impact:production-release");
+    }
+    const scopeSignals = {
+      localized: add("scope:localized", /\b(localizado|uma frase|typo|pequeno|small|tiny|simples|README)\b/i),
+      broad: add("scope:broad", /\b(plataforma|sistema|completo|premium|end-to-end|amplo|v[aá]rias|m[úu]ltiplas|empresa)\b/i),
+      architectural: add("scope:architectural", /\b(deep|architectural|arquitetural|migration|migra[cç][aã]o|major|full|\[deep\])\b/i),
+      explicitHigh: add("scope:explicit-high", /\b(high-risk|high risk|alto risco)\b/i),
+      explicitRequiredSpec: add("scope:explicit-required-spec", /\b(formal spec|required spec|especifica[cç][aã]o formal)\b/i),
+      explicitRequiredEvidence: add("scope:explicit-required-evidence", /\b(required evidence|evidence required|evid[eê]ncia obrigat[óo]ria)\b/i)
+    };
+    let riskLevel = "medium";
+    const riskDrivers = [];
+    const highDrivers = [
+      ["scope:explicit-high", scopeSignals.explicitHigh],
+      ["scope:architectural", scopeSignals.architectural],
+      ["domain:adult", domainRiskSignals.adult],
+      ["domain:auth", domainRiskSignals.auth],
+      ["domain:payment", domainRiskSignals.payment],
+      ["domain:security-governance", domainRiskSignals.securityGovernance],
+      ["impact:production-release", impactSignals.productionRelease],
+      ["impact:admin-permissions", impactSignals.adminPermissions],
+      ["impact:personal-data", taskTypeSignals.dashboard && impactSignals.personalData]
+    ];
+    for (const [signal, active] of highDrivers) {
+      if (active) {
+        riskDrivers.push(signal);
+      }
+    }
+    if (riskDrivers.length > 0) {
+      riskLevel = "high";
+    } else if (mutationIntent === "readonly") {
+      riskLevel = "low";
+      riskDrivers.push("intent:readonly");
+    } else if (taskTypeSignals.docsCopy && scopeSignals.localized) {
+      riskLevel = "low";
+      riskDrivers.push("task:docs-copy");
+    } else if (taskTypeSignals.refactor || taskTypeSignals.bugfix || taskTypeSignals.landingPage || taskTypeSignals.dashboard) {
+      riskLevel = "medium";
+      if (taskTypeSignals.refactor) riskDrivers.push("task:refactor");
+      if (taskTypeSignals.bugfix) riskDrivers.push("task:bugfix");
+      if (taskTypeSignals.landingPage) riskDrivers.push("task:landing-page");
+      if (taskTypeSignals.dashboard) riskDrivers.push("task:dashboard");
+    }
+    const specPolicy = riskLevel === "high" || scopeSignals.explicitRequiredSpec || taskTypeSignals.landingPage && scopeSignals.broad ? "required" : "none";
+    return {
+      riskLevel,
+      specPolicy,
+      matchedSignals: [...new Set(matchedSignals)],
+      riskDrivers: [...new Set(riskDrivers)]
+    };
+  }
+  determineSafetyAndEvidence(text, mutationIntent) {
+    const safetyConstraints = [];
+    const requiredEvidence = [];
+    if (mutationIntent === "publish") {
+      safetyConstraints.push("Require release gate", "Awaiting user authorization");
+      requiredEvidence.push("release-decision", "tarball-hash");
+    } else if (mutationIntent === "write") {
+      safetyConstraints.push("Require branch gate", "No direct commits to main");
+      requiredEvidence.push("tests", "commit-hash");
+    } else {
+      safetyConstraints.push("No workspace mutations allowed");
+    }
+    if (/\b(bypass|force|direct)\b/i.test(text)) {
+      safetyConstraints.push("Block bypass attempts");
+    }
+    if (/\b(required evidence|evidence required)\b/i.test(text)) {
+      requiredEvidence.push("user-required-evidence");
+    }
+    if (/\b(formal spec|required spec)\b/i.test(text)) {
+      safetyConstraints.push("Require formal specification");
+    }
+    return { safetyConstraints, requiredEvidence };
+  }
+  /**
+   * Decides the routing decision.
+   */
+  route(understanding) {
+    const { operationType, mutationIntent, rawRequest, deliveryMode, capabilityRoles } = understanding;
+    const requestedActor = void 0;
+    if (/\b(bypass safety|bypass validation|force push|directly to main|push to remote without gate)\b/i.test(rawRequest)) {
+      return {
+        requestedActor,
+        selectedActor: "Atlas",
+        mutationOwner: "ControlPlane",
+        capabilityRoles,
+        operationType,
+        mutationIntent,
+        deliveryMode,
+        permissionDecision: "blocked",
+        reason: "Security block: Attempt to bypass safety or push directly is forbidden.",
+        workflowPath: ["Atlas"]
+      };
+    }
+    let { selectedActor, permissionDecision, reason } = this.evaluateActorPermission(operationType, mutationIntent);
+    let workflowPath = ["Atlas"];
+    if (selectedActor === "Phoenix") {
+      const requestPath = path4.join(this.cwd, ".ai-workflow/remediation-request.json");
+      let hasFindings = false;
+      if (fs4.existsSync(requestPath)) {
+        try {
+          const reqData = JSON.parse(fs4.readFileSync(requestPath, "utf8"));
+          if (reqData.affectedChecks && reqData.affectedChecks.length > 0) {
+            hasFindings = true;
+          }
+        } catch {
+        }
+      }
+      if (!hasFindings) {
+        permissionDecision = "blocked";
+        reason = "Blocked: Phoenix acts only with concrete findings and bounded remediation.";
+      }
+    }
+    if (understanding.specPolicy === "required") {
+      workflowPath.push("Nexus", "Orion");
+    }
+    if (selectedActor && !workflowPath.includes(selectedActor)) {
+      workflowPath.push(selectedActor);
+    }
+    const mutationOwner = mutationIntent === "readonly" || deliveryMode === "answer-only" ? null : mutationIntent === "publish" ? "Astra" : selectedActor === "Astra" || selectedActor === "Phoenix" ? selectedActor : "ControlPlane";
+    if (mutationOwner && mutationOwner !== "ControlPlane" && !workflowPath.includes(mutationOwner)) {
+      workflowPath.push(mutationOwner);
+    }
+    if (selectedActor === "Atlas" && ["discover", "validate", "fix", "release", "deploy"].includes(operationType)) {
+      permissionDecision = "blocked";
+      reason = "Atlas self-execution guard: Atlas cannot silently execute specialized actor or capability requests.";
+    }
+    if (mutationOwner === "Astra" && understanding.riskLevel === "high") {
+      workflowPath.push("Sage", "Phoenix", "Sage");
+    }
+    if (understanding.specPolicy === "none") {
+      workflowPath = workflowPath.filter((actor) => {
+        if (actor === "Nexus" && selectedActor !== "Nexus") return false;
+        if (actor === "Orion" && selectedActor !== "Orion") return false;
+        return true;
+      });
+    }
+    return {
+      requestedActor,
+      selectedActor,
+      mutationOwner,
+      capabilityRoles,
+      operationType,
+      mutationIntent,
+      deliveryMode,
+      permissionDecision,
+      reason,
+      workflowPath
+    };
+  }
+  evaluateActorPermission(operationType, mutationIntent) {
+    let selectedActor;
+    let permissionDecision = "allowed";
+    let reason = "Routed successfully.";
+    if (mutationIntent === "publish") {
+      selectedActor = "Orion";
+      reason = "Routed to Orion for release planning and approval gates.";
+    } else if (mutationIntent === "write" && operationType !== "remediate") {
+      selectedActor = "Astra";
+      reason = "Routed to Astra because write intent takes mutation ownership precedence.";
+    } else if (operationType === "discover") {
+      selectedActor = "Nexus";
+    } else if (operationType === "validate") {
+      selectedActor = "Sage";
+    } else if (operationType === "remediate") {
+      selectedActor = "Phoenix";
+    } else if (operationType === "implement" || operationType === "fix") {
+      selectedActor = "Astra";
+    } else if (operationType === "release" || operationType === "deploy") {
+      selectedActor = "Orion";
+    } else {
+      selectedActor = mutationIntent === "write" ? "Astra" : "Atlas";
+    }
+    return { selectedActor, permissionDecision, reason };
+  }
+};
+
 export {
   MergeGate,
   StackDetector,
   DeliveryDecisionEngine,
-  ArtifactFidelityGate
+  ArtifactFidelityGate,
+  RequestRouter
 };
-//# sourceMappingURL=chunk-XW747GIG.js.map
+//# sourceMappingURL=chunk-H7GIKXFO.js.map

package/core/index.d.ts

@@ -1,11 +1,16 @@
+type DeliveryMode = "workspace" | "answer-only";
+
+type MutationOwner = "Astra" | "Phoenix" | "ControlPlane" | null;
 interface RequestUnderstanding {
     rawRequest: string;
     taskGoal: string;
     requestedActor?: string;
     invalidActor?: string;
     requestedCapability?: string;
+    capabilityRoles: string[];
     operationType: string;
     mutationIntent: "readonly" | "write" | "publish";
+    deliveryMode: DeliveryMode;
     riskLevel: "low" | "medium" | "high";
     requiredEvidence: string[];
     safetyConstraints: string[];
@@ -16,8 +21,11 @@ interface RequestUnderstanding {
 interface RoutingDecision {
     requestedActor?: string;
     selectedActor?: string;
+    mutationOwner: MutationOwner;
+    capabilityRoles: string[];
     operationType: string;
     mutationIntent: "readonly" | "write" | "publish";
+    deliveryMode: DeliveryMode;
     permissionDecision: "allowed" | "rerouted" | "blocked";
     reason: string;
     workflowPath: string[];
@@ -176,11 +184,20 @@ interface ExecuteOptions {
     readOnly?: boolean;
     fastTrack?: boolean;
     requireActorConfirmation?: boolean;
+    orchestratedChild?: boolean;
+}
+interface ObservedCommand {
+    command: string;
+    tool: string;
+    status: "PASS" | "FAIL" | "UNKNOWN";
+    exitCode: number | null;
+    source: "sdk" | "json-event" | "text-output";
 }
 interface ExecuteResult {
     success: boolean;
     status?: string;
     commandsRun: string[];
+    commandEvents?: ObservedCommand[];
     eventCount: number;
     error?: string;
     runtimeAgentRequested?: string | null;
@@ -205,7 +222,7 @@ declare class OpenCodeAdapter {
     /**
      * Runs opencode with a prompt and options.
      */
-    execute(message: string, { agent, model, readOnly, fastTrack, requireActorConfirmation }?: ExecuteOptions): Promise<ExecuteResult>;
+    execute(message: string, { agent, model, readOnly, fastTrack, requireActorConfirmation, orchestratedChild }?: ExecuteOptions): Promise<ExecuteResult>;
 }
 
 interface DelegationControllerOptions {
@@ -351,6 +368,8 @@ declare class WorkspaceSnapshot {
     });
     isIgnored(relativePath: string): boolean;
     capture(): Promise<WorkspaceSnapshotData>;
+    listGitVisibleFiles(): string[] | null;
+    scanFiles(relativePaths: string[], filesMap: Record<string, SnapshotFile>): Promise<void>;
     scanDir(dir: string, filesMap: Record<string, SnapshotFile>): Promise<void>;
     calculateHash(snapshot: WorkspaceSnapshotData): string;
 }

package/core/index.js

@@ -9,10 +9,10 @@ import {
   RequestClassifier,
   SpecValidator,
   WorkflowStateMachine
-} from "../chunk-LI76KI7C.js";
+} from "../chunk-4FI5ODAM.js";
 import {
   MergeGate
-} from "../chunk-XW747GIG.js";
+} from "../chunk-H7GIKXFO.js";
 import {
   BranchGate
 } from "../chunk-AINIR25D.js";

package/dist-assets/agents/atlas.md

@@ -23,7 +23,7 @@ Atlas must:
 * Enforce protected-branch safety before writes.
 * Route to specialists only when useful.
 * Require observed validation and prevent false success.
-* Return a concise delivery handoff.
+* Continue from routing through delivery, validation, and a concise handoff.
 
 ## Trusted context
 * Repository files
@@ -40,7 +40,11 @@ Atlas must:
 ## Constraints
 * **High-Risk Sequence Enforcement**: For high-risk tasks (specPolicy: required), Atlas must strictly enforce that the workflow runs sequentially through `discover`, `spec-create`, `spec-review`, and `plan` phases before any implementation or coding starts. Jumping directly to implementation is forbidden.
 * **Authoritative Routing Integrity**: Atlas must routing-delegate requests strictly according to agent capabilities (e.g., never delegate write-mutations to Sage, or discovery/spec-writing to Astra).
-* **Implementation Delegation Constraint**: Atlas must never perform dynamic code writing or logic modification of source files directly. Any code changes (excluding pure documentation, README updates, or spelling typos) must be delegated to Astra.
+* **Implementation Delegation Constraint**: Atlas must never modify user-requested workspace files directly. Every requested mutation, including documentation, README updates, and spelling fixes, must be delegated to Astra. Phoenix may write only during bounded remediation of an observed finding.
+* **Workspace Delivery Constraint**: A natural request to create, fix, change, or implement repository behavior has `deliveryMode: workspace` unless the user explicitly requests an answer-only example or preview. Printed code is never workspace delivery.
+* **Mutation Ownership Constraint**: Astra owns user-requested implementation mutations. Phoenix owns only bounded remediation of observed findings. Skill-backed specialists are capabilities used by those owners and must not receive direct mutation ownership from Atlas.
+* **Non-Terminal Routing Constraint**: `decision: ROUTED` confirms only actor selection. Atlas must continue the workflow and must not present routed output as a completed implementation.
+* **Context Compatibility Constraint**: Before implementation, compare an explicitly requested stack or platform with the active repository. Stop with `NEEDS_CLARIFICATION` when the context conflicts or cannot safely support the requested artifact.
 * **Quality Gate Authoritativeness**: Any non-zero exit code or `BLOCKED` status from a safety gate, validation check, or finalizer command must immediately halt the pipeline.
 * Never write on `main`, `master`, or another protected branch.
 * If the protected branch is clean or has only preservable untracked files, create a scoped branch before editing.
@@ -73,13 +77,16 @@ Atlas must:
 
 ## Operating procedure
 1. classify requests and select the lowest safe proportional policies.
-2. Delegate to specialist actors:
+2. For workspace delivery, run `git branch --show-current` and `git status --short`, then satisfy the branch gate before any edit.
+3. Delegate to workflow owners:
    * Delegation is proportional, not ceremonial.
-   * Use Astra for substantial implementation work.
+   * Use Astra for every user-requested implementation mutation, including small changes.
+   * Astra may use skill-backed specialists as bounded capabilities.
+   * Atlas must not invoke a skill-backed specialist directly for workspace implementation.
    * Use Sage for independent validation when high risk justifies it.
    * Use Phoenix only for concrete findings that need remediation.
    * Do not claim that an agent acted unless that handoff actually occurred.
-3. For low or medium risk tasks:
+4. For low or medium risk tasks:
    * Inspect status.
    * Recover branch if needed.
    * Coordinate and delegate any code-source modifications to Astra (Atlas must never execute code implementation directly).
@@ -92,7 +99,13 @@ Atlas must:
      * exit code `0` with `COMPLETED` or `COMPLETED_WITH_NOTES`: Atlas may report that exact public state;
      * non-zero exit code or `BLOCKED`: remediate within the configured bound or report `BLOCKED`;
      * Atlas must never infer, upgrade, or replace the finalizer result from screenshots, manual checks, build output, or its own judgement.
-4. For high-risk tasks requiring evidence (evidencePolicy: required), use the full workflow/orchestrator so persisted evidence and independent validation remain available.
+5. Resolve the delivery outcome after observed validation:
+   * `CHANGED` requires an actual scoped diff and passing proportional validation.
+   * `ALREADY_SATISFIED` requires explicit verification and must not manufacture a diff.
+   * `READ_ONLY_RESULT` and `PREVIEW_ONLY` must not claim workspace implementation.
+   * `NEEDS_CLARIFICATION` and `NOT_DELIVERED` are blocking outcomes.
+   * Record `testAction: reuse | extend | add | none` with a concrete reason; do not add prompt-specific tests solely to make a request pass.
+6. For high-risk tasks requiring evidence (evidencePolicy: required), use the full workflow/orchestrator so persisted evidence and independent validation remain available.
 
 ## Expected output schema
 Must include:
@@ -107,6 +120,12 @@ workflowPath
 reason
 requiredEvidence
 decision: ROUTED | BLOCKED | NEEDS_CLARIFICATION
+deliveryMode: workspace | answer-only
+mutationOwner: Astra | Phoenix | ControlPlane | null
+capabilityRoles
+deliveryOutcome: CHANGED | ALREADY_SATISFIED | READ_ONLY_RESULT | PREVIEW_ONLY | NEEDS_CLARIFICATION | NOT_DELIVERED
+testAction: reuse | extend | add | none
+testReason
 ```
 
 ## Evidence required

package/dist-assets/commands/atlas.md

@@ -27,6 +27,9 @@ Route user requests safely, proportionately, and securely according to the permi
 - Always route to the correct specialized agent or fail closed.
 - Do not execute code modifications directly.
 - Do not claim routing execution without ledger evidence.
+- Treat `ROUTED` as non-terminal; continue through implementation and validation.
+- Route workspace implementation to Astra, never directly to a skill-backed specialist.
+- Printed code is not a substitute for a requested repository change.
 
 ## Allowed tools
 - classify request
@@ -43,7 +46,8 @@ Route user requests safely, proportionately, and securely according to the permi
 2. Classify intent (write/readonly/publish) and risk level.
 3. Resolve target agent according to the permission matrix.
 4. Log the routing event to the ledger.
-5. Delegate execution to the resolved agent.
+5. Delegate workspace implementation to Astra; pass specialist capabilities as context only.
+6. Continue through proportional validation and resolve the delivery outcome.
 
 ## Safety gates
 - Enforce branch gate constraints.
@@ -58,7 +62,8 @@ Output must include:
 - Classification metrics
 - Target agent resolved
 - Safety constraints
-- Decision: ALLOWED | BLOCKED
+- Decision: ROUTED | BLOCKED | NEEDS_CLARIFICATION
+- Delivery outcome and test action
 
 ## Evidence required
 - routing ledger event log

package/dist-assets/docs/QUICKSTART.md

@@ -1,6 +1,10 @@
 # AI Workflow Kit quickstart
 
-To initialize your project, run `npx ai-workflow init --profile=standard` (default) or `npx ai-workflow init --profile=full` (adds examples). Then, give Atlas a natural software request. Atlas chooses the lowest safe proportional policies and the closest workflow profile.
+To initialize your project, run `npx ai-workflow init --profile=standard` (default) or `npx ai-workflow init --profile=full` (adds examples). For enforced workspace delivery, run `npx aw execute "your natural software request"` or use the OpenCode `/run` command. Atlas chooses the lowest safe proportional policies and the closest workflow profile.
+
+Selecting Atlas directly uses the same ownership contract: Atlas routes product
+mutations to Astra and may use specialists only as capabilities. The CLI path is
+the authoritative control plane for programmatic gates and persisted evidence.
 
 ## Proportional Policies
 
@@ -20,6 +24,11 @@ Write-capable work never runs on `main` or `master`. Existing relevant tests/bui
 - `COMPLETED_WITH_NOTES`
 - `BLOCKED`
 
+The structured delivery outcome distinguishes `CHANGED`,
+`ALREADY_SATISFIED`, `READ_ONLY_RESULT`, `PREVIEW_ONLY`,
+`NEEDS_CLARIFICATION`, and `NOT_DELIVERED`. A routing decision alone is never a
+completed implementation.
+
 Workflow documents are optional unless they provide lasting value or the specification policy requires them.
 
 ## Visual & Accessibility Evidence Requirements