@williambeto/ai-workflow 2.6.4 → 2.7.0

package/bin/ai-workflow.js

@@ -21,13 +21,13 @@ import {
   isTerminalFailure,
   readPackageFile,
   resolveWorkflowProfile
-} from "../chunk-UHLZX2EG.js";
+} from "../chunk-W4RTQWVQ.js";
 import {
   EvidenceCollector,
   QualityGuard,
   ValidationPlanner
-} from "../chunk-6EMG6FAO.js";
-import "../chunk-2AOV2ATY.js";
+} from "../chunk-BDZPUAEX.js";
+import "../chunk-XW747GIG.js";
 import "../chunk-5WRI5ZAA.js";
 
 // src/cli/commands/init.ts
@@ -193,13 +193,14 @@ function isValidProfile(profile) {
 function getTemplateFiles(profile = "standard") {
   return PROFILE_FILES[profile] ?? PROFILE_FILES.standard;
 }
-function buildAiWorkflowConfig({ profile }) {
+function buildAiWorkflowConfig({ profile, runtimes = ["opencode"] }) {
   const version = getPackageVersion();
   const now = (/* @__PURE__ */ new Date()).toISOString();
+  const primaryRuntime = runtimes.join("+");
   return {
     package: "@williambeto/ai-workflow",
     version,
-    runtime: "opencode",
+    runtime: primaryRuntime,
     profile,
     installMode: "project-local",
     generatedAt: now,
@@ -779,7 +780,7 @@ Every task completion MUST provide the following payload:
    * - Skills -> .agents/skills/
    * - Commands -> .codex/prompts/
    */
-  async deploy(installRoot = ".ai-workflow") {
+  async deploy(installRoot = ".ai-workflow", force) {
     const sourceAgentsDir = path7.join(this.cwd, installRoot, "opencode/agents");
     const sourceSkillsDir = path7.join(this.cwd, installRoot, "opencode/skills");
     const sourceCommandsDir = path7.join(this.cwd, installRoot, "opencode/commands");
@@ -791,7 +792,7 @@ Every task completion MUST provide the following payload:
       const transformed = await this.transformAgent(path7.join(sourceAgentsDir, file));
       await fs5.writeFile(path7.join(codexAgentsDir, `${transformed.name}.md`), transformed.content);
     }
-    const codexSkillsDir = path7.join(this.cwd, ".agents/skills");
+    const codexSkillsDir = path7.join(this.cwd, ".codex/skills");
     await fs5.mkdir(codexSkillsDir, { recursive: true });
     const skillFolders = await fs5.readdir(sourceSkillsDir).catch(() => []);
     for (const folder of skillFolders) {
@@ -812,7 +813,7 @@ Every task completion MUST provide the following payload:
       const content = await fs5.readFile(path7.join(sourceCommandsDir, file), "utf8");
       await fs5.writeFile(path7.join(codexPromptsDir, targetFileName), content);
     }
-    const codexPoliciesDir = path7.join(this.cwd, ".agents", "docs", "policies");
+    const codexPoliciesDir = path7.join(this.cwd, ".codex", "docs", "policies");
     await fs5.mkdir(codexPoliciesDir, { recursive: true });
     const sourcePoliciesDir = path7.join(this.cwd, installRoot, "opencode", "docs", "policies");
     const policyFiles = await fs5.readdir(sourcePoliciesDir).catch(() => []);
@@ -821,6 +822,70 @@ Every task completion MUST provide the following payload:
       const policyContent = await fs5.readFile(path7.join(sourcePoliciesDir, file), "utf8");
       await fs5.writeFile(path7.join(codexPoliciesDir, file), policyContent);
     }
+    await this.deployRootCopilotInstructions();
+    await this.deployRootCodexMd(force);
+    await this.deployRootAgentsMd(force);
+  }
+  async deployRootCopilotInstructions() {
+    const githubDir = path7.join(this.cwd, ".github");
+    await fs5.mkdir(githubDir, { recursive: true });
+    const targetPath = path7.join(githubDir, "copilot-instructions.md");
+    const instructions = `# AI Workflow Kit Governance
+
+This repository uses the **AI Workflow Kit** (OpenCode-first) workflow.
+
+##  Mandate: Atlas Authority Protocol
+All architectural changes must align with the specifications issued by the **Specification Authority**.
+
+##  Rules & Personas
+- Always follow the **Branch Gate** policy (never work on \`main\`).
+- Always follow the **SDD Workflow** (Spec -> Plan -> PR -> Evidence).
+- When acting as an agent, consult the instructions in \`.github/agents/\`.
+- When utilizing skills, consult the files in \`.codex/skills/\`.
+
+##  Completion Contract
+Every task completion MUST follow the payload format defined in the individual agent files.
+`;
+    await fs5.writeFile(targetPath, instructions);
+  }
+  async deployRootCodexMd(force) {
+    const targetPath = path7.join(this.cwd, "CODEX.md");
+    if (!force && await this.exists(targetPath)) return;
+    const templatePath = path7.join(this.cwd, ".ai-workflow", "templates", "CODEX.md.template");
+    if (await this.exists(templatePath)) {
+      const content = await fs5.readFile(templatePath, "utf8");
+      await fs5.writeFile(targetPath, content);
+      return;
+    }
+    const instructions = `# AI Workflow Kit Governance
+
+This repository uses the **AI Workflow Kit** (OpenCode-first) workflow.
+
+##  Mandate: Atlas Authority Protocol
+All architectural changes must align with the specifications issued by the **Specification Authority**.
+
+##  Rules & Personas
+- Always follow the **Branch Gate** policy (never work on \`main\`).
+- Always follow the **SDD Workflow** (Spec -> Plan -> PR -> Evidence).
+- When acting as an agent, consult the instructions in \`.github/agents/\`.
+- When utilizing skills, consult the files in \`.codex/skills/\`.
+
+##  Completion Contract
+Every task completion MUST follow the payload format defined in the individual agent files.
+`;
+    await fs5.writeFile(targetPath, instructions);
+  }
+  async deployRootAgentsMd(force) {
+    const targetPath = path7.join(this.cwd, "AGENTS.md");
+    if (!force && await this.exists(targetPath)) return;
+    const templatePath = path7.join(this.cwd, ".ai-workflow", "AGENTS.md");
+    if (await this.exists(templatePath)) {
+      let content = await fs5.readFile(templatePath, "utf8");
+      content = content.replace(/\.agents\/skills/g, ".codex/skills");
+      content = content.replace(/opencode\/commands/g, ".codex/prompts");
+      content = content.replace(/opencode\/docs\/policies/g, ".codex/docs/policies");
+      await fs5.writeFile(targetPath, content);
+    }
   }
   async exists(p) {
     try {
@@ -1256,7 +1321,7 @@ function resolveProfile(profile) {
   }
   return selectedProfile;
 }
-async function writeInstallFiles(cwd, actions, selectedProfile, force, noOverwrite, backupRoot = ".ai-workflow-backups") {
+async function writeInstallFiles(cwd, actions, selectedProfile, platforms, force, noOverwrite, backupRoot = ".ai-workflow-backups") {
   const skipped = [];
   const backups = [];
   for (const action of actions) {
@@ -1272,7 +1337,7 @@ async function writeInstallFiles(cwd, actions, selectedProfile, force, noOverwri
       });
       backups.push(backupPath);
     }
-    const content = action.relativePath === ".ai-workflow/config.json" ? `${JSON.stringify(buildAiWorkflowConfig({ profile: selectedProfile }), null, 2)}
+    const content = action.relativePath === ".ai-workflow/config.json" ? `${JSON.stringify(buildAiWorkflowConfig({ profile: selectedProfile, runtimes: platforms.length > 0 ? platforms : ["opencode"] }), null, 2)}
 ` : action.content;
     await writeFileSafe(action.absolutePath, content || "");
   }
@@ -1319,7 +1384,7 @@ async function writeSymlinks(cwd, linkEntries, force, backupRoot = ".ai-workflow
   }
   return { linkBackups, linkCreated };
 }
-async function executePlatformMigrations(cwd, installRoot, platforms, claude, codex, antigravity) {
+async function executePlatformMigrations(cwd, installRoot, platforms, claude, codex, antigravity, force) {
   if (platforms.length === 0) return;
   console.log("ai-workflow: migrating to native platforms...");
   const agentsDir = path9.join(cwd, installRoot, "opencode/agents");
@@ -1332,7 +1397,7 @@ async function executePlatformMigrations(cwd, installRoot, platforms, claude, co
   }
   if (codex) {
     const adapter = new CodexAdapter({ cwd });
-    await adapter.deploy(installRoot);
+    await adapter.deploy(installRoot, force);
     console.log("- codex: deployed AI Workflow Kit agents to .agents/, .codex/, and .github/ (native discovery enabled)");
   }
   if (antigravity) {
@@ -1433,7 +1498,7 @@ async function runInit({
     }
     return;
   }
-  const { skipped, backups } = await writeInstallFiles(cwd, actions, selectedProfile, force, noOverwrite, backupRoot);
+  const { skipped, backups } = await writeInstallFiles(cwd, actions, selectedProfile, platforms, force, noOverwrite, backupRoot);
   const { linkBackups, linkCreated } = await writeSymlinks(cwd, linkEntries, force, backupRoot);
   await setupInternalSymlinks(cwd, installRoot);
   const opencodeResult = await mergeOpencodeConfig(cwd, { force, backupRoot });
@@ -1457,7 +1522,7 @@ async function runInit({
   }
   const gitignoreResult = await upsertGitignoreBlock(cwd, generatedIgnoreEntries);
   const scriptInjected = await injectScripts(cwd);
-  await executePlatformMigrations(cwd, installRoot, platforms, claude, codex, antigravity);
+  await executePlatformMigrations(cwd, installRoot, platforms, claude, codex, antigravity, force);
   printInstallationSummary({
     selectedProfile,
     opencodeResult,
@@ -1486,11 +1551,7 @@ async function isSymlink(filePath) {
     return false;
   }
 }
-async function runDoctor({ cwd }) {
-  let hasFailure = false;
-  let hasWarning = false;
-  let managedBlocks = [];
-  console.log("Doctor report:");
+async function checkOpenCodeRuntime(cwd, state) {
   const adapter = new OpenCodeAdapter({ cwd });
   const inspection = await adapter.inspect();
   if (inspection.available) {
@@ -1500,22 +1561,26 @@ async function runDoctor({ cwd }) {
     if (inspection.supports.agent) {
       console.log("PASS opencode --agent selection is supported");
     } else {
-      hasWarning = true;
+      state.hasWarning = true;
       console.log("WARN opencode --agent selection is not supported; prompt fallback is available");
     }
   } else {
-    hasFailure = true;
+    state.hasFailure = true;
     console.log("FAIL opencode CLI is not installed or not available in PATH");
   }
+}
+async function checkRequiredFiles(cwd, state) {
   for (const relativePath of REQUIRED_FILES) {
     const ok = await exists(path10.join(cwd, relativePath));
     if (ok) {
       console.log(`PASS ${relativePath}`);
     } else {
-      hasFailure = true;
+      state.hasFailure = true;
       console.log(`FAIL ${relativePath} missing`);
     }
   }
+}
+async function checkAiWorkflowConfig(cwd, state) {
   const configPathV2 = path10.join(cwd, ".ai-workflow/config.json");
   const configPathLegacy = path10.join(cwd, ".ai-workflow.json");
   let configPath = null;
@@ -1524,122 +1589,172 @@ async function runDoctor({ cwd }) {
   } else if (await exists(configPathLegacy)) {
     configPath = configPathLegacy;
   }
-  if (configPath) {
-    try {
-      const config = await readJson(configPath);
-      if (config.installMode === "project-local" || config.mode === "standalone") {
-        console.log("PASS install mode is project-local/standalone");
-      } else {
-        hasWarning = true;
-        console.log(`WARN install mode is not project-local/standalone in ${path10.basename(configPath)}`);
-      }
-      if (config.profile) {
-        console.log(`PASS profile detected: ${config.profile}`);
-      } else {
-        hasWarning = true;
-        console.log(`WARN profile is missing in ${path10.basename(configPath)}`);
-      }
-      if (config.runtime) {
-        console.log(`PASS runtime: ${config.runtime}`);
-      } else {
-        console.log(`NOTE runtime field not present in ${path10.basename(configPath)}`);
-      }
-      if (Array.isArray(config.managedBlocks)) {
-        managedBlocks = config.managedBlocks;
-      } else {
-        console.log(`NOTE managedBlocks not present in ${path10.basename(configPath)} (legacy field)`);
-      }
-      if (Array.isArray(config.managedFiles)) {
-        for (const relativePath of config.managedFiles) {
-          const fileExists = await exists(path10.join(cwd, relativePath));
-          if (!fileExists) {
-            hasWarning = true;
-            console.log(`WARN managed file missing: ${relativePath}`);
-          }
+  if (!configPath) return;
+  try {
+    const config = await readJson(configPath);
+    const basename = path10.basename(configPath);
+    if (config.installMode === "project-local" || config.mode === "standalone") {
+      console.log("PASS install mode is project-local/standalone");
+    } else {
+      state.hasWarning = true;
+      console.log(`WARN install mode is not project-local/standalone in ${basename}`);
+    }
+    if (config.profile) {
+      console.log(`PASS profile detected: ${config.profile}`);
+    } else {
+      state.hasWarning = true;
+      console.log(`WARN profile is missing in ${basename}`);
+    }
+    if (config.runtime) {
+      console.log(`PASS runtime: ${config.runtime}`);
+      state.runtimes = config.runtime.split("+");
+    } else {
+      console.log(`NOTE runtime field not present in ${basename}`);
+      state.runtimes = ["opencode"];
+    }
+    if (Array.isArray(config.managedBlocks)) {
+      state.managedBlocks = config.managedBlocks;
+    } else {
+      console.log(`NOTE managedBlocks not present in ${basename} (legacy field)`);
+    }
+    if (Array.isArray(config.managedFiles)) {
+      for (const relativePath of config.managedFiles) {
+        const fileExists = await exists(path10.join(cwd, relativePath));
+        if (!fileExists) {
+          state.hasWarning = true;
+          console.log(`WARN managed file missing: ${relativePath}`);
         }
       }
-      if (Array.isArray(config.managedLinks)) {
-        for (const relativePath of config.managedLinks) {
-          const absolutePath = path10.join(cwd, relativePath);
-          const linkExists = await exists(absolutePath);
-          if (!linkExists) {
-            hasWarning = true;
-            console.log(`WARN managed link missing: ${relativePath}`);
-            continue;
-          }
-          const isLink = await isSymlink(absolutePath);
-          if (!isLink) {
-            hasWarning = true;
-            console.log(`WARN managed link is not a symlink: ${relativePath}`);
-          }
+    }
+    if (Array.isArray(config.managedLinks)) {
+      for (const relativePath of config.managedLinks) {
+        const absolutePath = path10.join(cwd, relativePath);
+        if (!await exists(absolutePath)) {
+          state.hasWarning = true;
+          console.log(`WARN managed link missing: ${relativePath}`);
+          continue;
+        }
+        if (!await isSymlink(absolutePath)) {
+          state.hasWarning = true;
+          console.log(`WARN managed link is not a symlink: ${relativePath}`);
         }
       }
-    } catch {
-      hasFailure = true;
-      console.log(`FAIL ${path10.basename(configPath)} is not valid JSON`);
     }
+  } catch {
+    state.hasFailure = true;
+    console.log(`FAIL ${path10.basename(configPath)} is not valid JSON`);
   }
+}
+async function checkOpencodeJson(cwd, state) {
   const opencodePath = path10.join(cwd, "opencode.jsonc");
   if (!await exists(opencodePath)) {
-    hasFailure = true;
+    state.hasFailure = true;
     console.log("FAIL opencode.jsonc missing");
-  } else {
-    try {
-      const opencodeConfig = await readJsonc(opencodePath);
-      console.log("PASS opencode.jsonc is valid JSONC");
-      const needsAgentDefault = managedBlocks.includes("opencode.jsonc:agent.default");
-      if (!needsAgentDefault || opencodeConfig.agent?.default) {
-        console.log("PASS opencode agent.default available");
-      } else {
-        hasFailure = true;
-        console.log("FAIL opencode agent.default missing");
-      }
-      const requiredCommands = managedBlocks.filter((block) => block.startsWith("opencode.jsonc:command.")).map((block) => block.replace("opencode.jsonc:command.", ""));
-      if (requiredCommands.length === 0) {
-        console.log("PASS no managed opencode commands required");
+    return;
+  }
+  try {
+    const opencodeConfig = await readJsonc(opencodePath);
+    console.log("PASS opencode.jsonc is valid JSONC");
+    const needsAgentDefault = state.managedBlocks.includes("opencode.jsonc:agent.default");
+    if (!needsAgentDefault || opencodeConfig.agent?.default) {
+      console.log("PASS opencode agent.default available");
+    } else {
+      state.hasFailure = true;
+      console.log("FAIL opencode agent.default missing");
+    }
+    const requiredCommands = state.managedBlocks.filter((block) => block.startsWith("opencode.jsonc:command.")).map((block) => block.replace("opencode.jsonc:command.", ""));
+    if (requiredCommands.length === 0) {
+      console.log("PASS no managed opencode commands required");
+    } else {
+      const missingCommands = requiredCommands.filter((command) => !opencodeConfig.command?.[command]);
+      if (missingCommands.length === 0) {
+        console.log(`PASS opencode managed commands available (${requiredCommands.length})`);
       } else {
-        const missingCommands = requiredCommands.filter((command) => !opencodeConfig.command?.[command]);
-        if (missingCommands.length === 0) {
-          console.log(`PASS opencode managed commands available (${requiredCommands.length})`);
-        } else {
-          hasFailure = true;
-          console.log(`FAIL opencode command entries missing: ${missingCommands.join(", ")}`);
-        }
+        state.hasFailure = true;
+        console.log(`FAIL opencode command entries missing: ${missingCommands.join(", ")}`);
       }
-      const requiredAgents = managedBlocks.filter((block) => block.startsWith("opencode.jsonc:agent.") && !block.endsWith(".default")).map((block) => block.replace("opencode.jsonc:agent.", ""));
-      if (requiredAgents.length === 0) {
-        console.log("PASS no managed opencode agents required");
+    }
+    const requiredAgents = state.managedBlocks.filter((block) => block.startsWith("opencode.jsonc:agent.") && !block.endsWith(".default")).map((block) => block.replace("opencode.jsonc:agent.", ""));
+    if (requiredAgents.length === 0) {
+      console.log("PASS no managed opencode agents required");
+    } else {
+      const missingAgents = requiredAgents.filter((agent) => !opencodeConfig.agent?.[agent]);
+      if (missingAgents.length === 0) {
+        console.log(`PASS opencode managed agents available (${requiredAgents.length})`);
       } else {
-        const missingAgents = requiredAgents.filter((agent) => !opencodeConfig.agent?.[agent]);
-        if (missingAgents.length === 0) {
-          console.log(`PASS opencode managed agents available (${requiredAgents.length})`);
-        } else {
-          hasFailure = true;
-          console.log(`FAIL opencode agent entries missing: ${missingAgents.join(", ")}`);
-        }
+        state.hasFailure = true;
+        console.log(`FAIL opencode agent entries missing: ${missingAgents.join(", ")}`);
       }
-    } catch {
-      hasFailure = true;
-      console.log("FAIL opencode.jsonc is not valid JSONC");
     }
+  } catch {
+    state.hasFailure = true;
+    console.log("FAIL opencode.jsonc is not valid JSONC");
   }
+}
+async function checkPackageJson(cwd, state) {
   const packageJsonPath = path10.join(cwd, "package.json");
   if (await exists(packageJsonPath)) {
     try {
       const packageJson = await readJson(packageJsonPath);
       const scripts = packageJson.scripts ?? {};
       if (!scripts.validate) {
-        hasWarning = true;
+        state.hasWarning = true;
         console.log("WARN package.json has no validate script");
       }
     } catch {
-      hasFailure = true;
+      state.hasFailure = true;
       console.log("FAIL package.json is not valid JSON");
     }
   }
-  const finalStatus = hasFailure ? "FAIL" : hasWarning ? "PASS_WITH_NOTES" : "PASS";
+}
+async function checkCodexRuntime(cwd, state) {
+  const checks = [
+    { name: "root AGENTS.md exists", path: "AGENTS.md" },
+    { name: ".codex/skills exists", path: ".codex/skills" },
+    { name: ".codex prompts detected", path: ".codex/prompts" },
+    { name: ".codex policies detected", path: ".codex/docs/policies" }
+  ];
+  for (const check of checks) {
+    const ok = await exists(path10.join(cwd, check.path));
+    if (ok) {
+      console.log(`PASS ${check.name}`);
+    } else {
+      state.hasFailure = true;
+      console.log(`FAIL ${check.name}`);
+    }
+  }
+  const codexMdOk = await exists(path10.join(cwd, "CODEX.md"));
+  if (codexMdOk) {
+    console.log(`PASS root CODEX.md exists`);
+  }
+  if (state.runtimes.includes("codex")) {
+    console.log("PASS config runtime includes codex");
+  } else {
+    state.hasFailure = true;
+    console.log("FAIL config runtime includes codex");
+  }
+}
+async function runDoctor({ cwd }) {
+  const state = {
+    hasFailure: false,
+    hasWarning: false,
+    managedBlocks: [],
+    runtimes: ["opencode"]
+  };
+  console.log("Doctor report:");
+  await checkRequiredFiles(cwd, state);
+  await checkAiWorkflowConfig(cwd, state);
+  if (state.runtimes.includes("opencode")) {
+    await checkOpenCodeRuntime(cwd, state);
+    await checkOpencodeJson(cwd, state);
+  }
+  if (state.runtimes.includes("codex")) {
+    await checkCodexRuntime(cwd, state);
+  }
+  await checkPackageJson(cwd, state);
+  const finalStatus = state.hasFailure ? "FAIL" : state.hasWarning ? "PASS_WITH_NOTES" : "PASS";
   console.log(`Final status: ${finalStatus}`);
-  if (hasFailure) {
+  if (state.hasFailure) {
     process.exitCode = 1;
   }
 }
@@ -2288,6 +2403,71 @@ async function generateFinalHandoff(plan, taskSlug, cwd, finalState, evidence) {
 `);
   return handoffPath;
 }
+async function runFastTrackValidation(cwd, result, checkBranchSafety) {
+  console.log(`
+--- [FAST-TRACK] Running Lightweight Validation Gates ---`);
+  checkBranchSafety();
+  const changedFiles = result.evidence?.changedFiles || [];
+  console.log(`[FAST-TRACK] Changed files detected:`, changedFiles);
+  const evidencePath = path14.join(cwd, "EVIDENCE.json");
+  const hasEvidence = await fs12.access(evidencePath).then(() => true).catch(() => false);
+  if (hasEvidence) {
+    const { EvidenceValidator } = await import("../evidence-validator-76ZQQYDU.js");
+    const isTest = process.env.NODE_ENV === "test" || process.env.VITEST === "true";
+    const evidenceValidator = new EvidenceValidator({ cwd, skipFileCheck: isTest, skipGitCheck: isTest });
+    const valResult = await evidenceValidator.validate();
+    if (!valResult.valid) {
+      console.error(`
+[FAST-TRACK BLOCKED] EVIDENCE.json validation failed: ${valResult.reason}`);
+      return "FAIL_QUALITY_GATE";
+    }
+  }
+  return result.overallStatus;
+}
+async function runFidelityValidation(naturalRequest, result, finalizer) {
+  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(`
+[FINALIZER BLOCKED] BLOCKED: Artifact fidelity check failed!`);
+    console.log(`Reason: ${fidelityResult.reason}`);
+    return "FAIL_QUALITY_GATE";
+  }
+  return result.overallStatus;
+}
+function computeFinalState(finalStatus) {
+  if (finalStatus === "PASS") return "COMPLETED";
+  if (finalStatus === "PASS_WITH_NOTES") return "COMPLETED_WITH_NOTES";
+  return "BLOCKED";
+}
+async function executeReadOnlyWorkflow(cwd, stateMachine, readOnlyStateBefore, fastTrack) {
+  await runReadOnlyConfinementCheck(readOnlyStateBefore, cwd, stateMachine, fastTrack);
+  stateMachine.transitionTo("IMPLEMENTED");
+  stateMachine.transitionTo("VALIDATING");
+  stateMachine.transitionTo("COMPLETED");
+  console.log("\n--- Final Handoff ---");
+  console.log(`
+[AI WORKFLOW COMPLETE] COMPLETED`);
+  console.log(`Handoff Packet: [IN-MEMORY] (No handoff file written in read-only mode)
+`);
+  return {
+    overallStatus: "PASS",
+    evidence: {
+      internalStatus: "PASS",
+      commandsRun: []
+    },
+    quality: {
+      overallStatus: "PASS"
+    },
+    stateHistory: stateMachine.getHistory()
+  };
+}
 async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
   if (!naturalRequest || !naturalRequest.trim()) {
     throw new Error("Missing request. Please provide a natural request string via positional arguments or --request flag.");
@@ -2303,16 +2483,15 @@ async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
     const stateMachine = new WorkflowStateMachine();
     const { plan: planObj, classification } = await classifyAndPlanExecution(naturalRequest, cwd, taskSlug, delegationController, stateMachine);
     plan = planObj;
-    const fastTrack = plan.riskLevel === "low" && (plan.branchNeeded ? plan.evidencePolicy === "optional" : true);
+    const fastTrack = plan.riskLevel === "low" && (!plan.branchNeeded || plan.evidencePolicy === "optional");
     const branchGate = new BranchGate({ memoryDir: path14.join(cwd, ".ai-workflow"), cwd });
     const gateResult = runBranchGate(plan, taskSlug, cwd, stateMachine, branchGate);
     const checkBranchSafety = () => {
-      if (plan.branchNeeded) {
-        const currentBranch = branchGate.getCurrentBranch();
-        if (branchGate.protectedBranches.includes(currentBranch)) {
-          stateMachine.transitionTo("BLOCKED");
-          throw new Error(`[WORKFLOW BLOCKED] Security violation: current branch is protected '${currentBranch}'!`);
-        }
+      if (!planObj.branchNeeded) return;
+      const currentBranch = branchGate.getCurrentBranch();
+      if (branchGate.protectedBranches.includes(currentBranch)) {
+        stateMachine.transitionTo("BLOCKED");
+        throw new Error(`[WORKFLOW BLOCKED] Security violation: current branch is protected '${currentBranch}'!`);
       }
     };
     await createSpecIfRequired(plan, classification, taskSlug, cwd);
@@ -2321,27 +2500,8 @@ async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
       readOnlyStateBefore = await captureReadOnlyState(cwd, fastTrack);
     }
     await runImplementation(plan, classification, delegationController, stateMachine, fastTrack);
-    if (!plan.branchNeeded) {
-      await runReadOnlyConfinementCheck(readOnlyStateBefore, cwd, stateMachine, fastTrack);
-      stateMachine.transitionTo("IMPLEMENTED");
-      stateMachine.transitionTo("VALIDATING");
-      stateMachine.transitionTo("COMPLETED");
-      console.log("\n--- Final Handoff ---");
-      console.log(`
-[AI WORKFLOW COMPLETE] COMPLETED`);
-      console.log(`Handoff Packet: [IN-MEMORY] (No handoff file written in read-only mode)
-`);
-      return {
-        overallStatus: "PASS",
-        evidence: {
-          internalStatus: "PASS",
-          commandsRun: []
-        },
-        quality: {
-          overallStatus: "PASS"
-        },
-        stateHistory: stateMachine.getHistory()
-      };
+    if (!plan.branchNeeded && readOnlyStateBefore) {
+      return await executeReadOnlyWorkflow(cwd, stateMachine, readOnlyStateBefore, fastTrack);
     }
     stateMachine.transitionTo("IMPLEMENTED");
     checkBranchSafety();
@@ -2369,7 +2529,6 @@ async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
     }
     checkBranchSafety();
     let integrity = { valid: true, changes: { added: [], modified: [], deleted: [] } };
-    let stabResult = result;
     if (!fastTrack) {
       const stab = await runFinalizerStabilization(
         plan,
@@ -2382,54 +2541,23 @@ async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
         snapshotRef,
         checkBranchSafety
       );
-      stabResult = stab.result;
+      result = stab.result;
       integrity = stab.integrity;
     }
-    result = stabResult;
     let finalStatus = result.overallStatus;
     if (fastTrack) {
-      console.log(`
---- [FAST-TRACK] Running Lightweight Validation Gates ---`);
-      checkBranchSafety();
-      const changedFiles = result.evidence?.changedFiles || [];
-      console.log(`[FAST-TRACK] Changed files detected:`, changedFiles);
-      const evidencePath = path14.join(cwd, "EVIDENCE.json");
-      const hasEvidence = await fs12.access(evidencePath).then(() => true).catch(() => false);
-      if (hasEvidence) {
-        const { EvidenceValidator } = await import("../evidence-validator-76ZQQYDU.js");
-        const isTest = process.env.NODE_ENV === "test" || process.env.VITEST === "true";
-        const evidenceValidator = new EvidenceValidator({ cwd, skipFileCheck: isTest, skipGitCheck: isTest });
-        const valResult2 = await evidenceValidator.validate();
-        if (!valResult2.valid) {
-          console.error(`
-[FAST-TRACK BLOCKED] EVIDENCE.json validation failed: ${valResult2.reason}`);
-          finalStatus = "FAIL_QUALITY_GATE";
-        }
-      }
+      finalStatus = await runFastTrackValidation(cwd, result, checkBranchSafety);
     } else if (!integrity.valid) {
       console.log(`
 [FINALIZER BLOCKED] BLOCKED: workspace did not stabilize`);
       console.log(`Final changes detected:`, integrity.changes);
       finalStatus = "FAIL_QUALITY_GATE";
     } else {
-      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(`
-[FINALIZER BLOCKED] BLOCKED: Artifact fidelity check failed!`);
-        console.log(`Reason: ${fidelityResult.reason}`);
-        finalStatus = "FAIL_QUALITY_GATE";
-      }
+      finalStatus = await runFidelityValidation(naturalRequest, result, finalizer);
     }
-    const finalState = finalStatus === "PASS" ? "COMPLETED" : finalStatus === "PASS_WITH_NOTES" ? "COMPLETED_WITH_NOTES" : "BLOCKED";
+    const finalState = computeFinalState(finalStatus);
     stateMachine.transitionTo(finalState);
-    const handoffPath = await generateFinalHandoff(plan, taskSlug, cwd, finalState, result.evidence);
+    await generateFinalHandoff(plan, taskSlug, cwd, finalState, result.evidence);
     return { ...result, overallStatus: finalStatus, stateHistory: stateMachine.getHistory() };
   } finally {
     if (plan && !plan.branchNeeded) {
@@ -2589,19 +2717,9 @@ function parseFlags(args) {
     purgeAgents: args.includes("--purge-agents") || args.includes("--purge")
   };
 }
-async function runCli(args) {
-  const [command] = args;
-  if (command === "--version" || command === "-v") {
-    console.log(getPackageVersion() || "unknown");
-    return;
-  }
-  if (!command || command === "--help" || command === "-h") {
-    printHelp();
-    return;
-  }
-  if (command === "execute") {
-    const flags = parseFlags(args.slice(1));
-    const positionals = args.slice(1).filter((arg) => !arg.startsWith("-"));
+var commandMap = {
+  execute: async (args, flags) => {
+    const positionals = args.filter((arg) => !arg.startsWith("-"));
     const request = flags.request || positionals.join(" ");
     const result = await runExecute({
       cwd: process.cwd(),
@@ -2611,25 +2729,23 @@ async function runCli(args) {
     if (result && (result.overallStatus === "FAIL_QUALITY_GATE" || result.overallStatus === "BLOCKED" || result.overallStatus === "FAIL")) {
       process.exit(1);
     }
-    return;
-  }
-  if (command === "run") {
+  },
+  run: async (_, flags) => {
     await runMasterOrchestrator({
       cwd: process.cwd(),
-      ...parseFlags(args.slice(1))
+      ...flags
     });
-    return;
-  }
-  if (command === "init") {
+  },
+  init: async (_, flags) => {
     await runInit({
       cwd: process.cwd(),
-      ...parseFlags(args.slice(1))
+      ...flags
     });
-    return;
-  }
-  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");
+  },
+  "collect-evidence": async (_, flags) => {
+    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,
@@ -2639,11 +2755,9 @@ async function runCli(args) {
       visualDist: flags.visualDist,
       port: flags.port
     });
-    return;
-  }
-  if (command === "validate") {
-    const flags = parseFlags(args.slice(1));
-    const { runValidate } = await import("../validate-Q2NLLQ5G.js");
+  },
+  validate: async (_, flags) => {
+    const { runValidate } = await import("../validate-A46WUBVZ.js");
     await runValidate({
       cwd: process.cwd(),
       taskSlug: flags.taskSlug,
@@ -2651,17 +2765,32 @@ async function runCli(args) {
       visualDist: flags.visualDist,
       port: flags.port
     });
-    return;
-  }
-  if (command === "doctor") {
+  },
+  doctor: async () => {
     await runDoctor({ cwd: process.cwd() });
-    return;
-  }
-  if (command === "clean") {
+  },
+  clean: async (_, flags) => {
     await runClean({
       cwd: process.cwd(),
-      ...parseFlags(args.slice(1))
+      ...flags
     });
+  }
+};
+async function runCli(args) {
+  const [command] = args;
+  if (command === "--version" || command === "-v") {
+    console.log(getPackageVersion() || "unknown");
+    return;
+  }
+  if (!command || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+  const handler = commandMap[command];
+  if (handler) {
+    const argsSlice = args.slice(1);
+    const flags = parseFlags(argsSlice);
+    await handler(argsSlice, flags);
     return;
   }
   throw new Error(`unknown command: ${command}`);