@williambeto/ai-workflow 2.8.2 → 2.9.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 ## [unreleased]
 
+## [2.9.0] - 2026-07-15
+
+### 🚀 Features
+
+- Add a Codex-native project installation with custom agents under
+  `.codex/agents/` and reusable skills, including commands, under
+  `.codex/skills/`
+- Introduce runtime adapters and explicit `--runtime=opencode|codex` selection
+  while preserving OpenCode as the compatibility default
+- Add Codex-aware doctor checks for trusted projects, native agents, skills,
+  policies, and CLI capabilities
+
+### 🐛 Bug Fixes
+
+- Replace legacy Codex prompt and GitHub Copilot paths with documented native
+  Codex assets
+- Preserve consumer-owned `AGENTS.md` files and install a Codex workflow
+  contract only when the root instructions are AIWK-managed or absent
+- Block non-interactive Codex delivery when the runtime cannot prove custom
+  agent ownership instead of reporting unobserved Astra execution
+- Keep runtime selection, delegation evidence, and bounded remediation aligned
+  across the OpenCode and Codex adapters
+
+### 🧪 Testing
+
+- Add unit coverage for Codex agent conversion, command skills, runtime
+  selection, JSON event parsing, trust checks, and fail-closed execution
+- Add a clean-consumer Codex init and doctor smoke test without generating
+  legacy prompt paths
+- Validate the local release tarball in clean repositories with GPT-5.6 Sol
+  Medium and GPT-5.3 Codex Spark; qualify Sol for direct delivery and mark
+  Spark unsupported for workspace-write delivery after repeated code-only
+  responses without observed edits or validation
+
+### 📚 Documentation
+
+- Reclassify Codex as experimental until an app-server E2E can prove native
+  delegation, workspace delivery, and observed validation
+- Document project trust, native Codex asset locations, runtime selection, and
+  model-specific delivery limits
+
 ## [2.8.1] - 2026-07-14
 
 ### 🐛 Bug Fixes

package/bin/ai-workflow.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import {
   COMPLETION_STATUS_TEXT,
+  CodexRuntimeAdapter,
   DelegationController,
   EvidenceLedger,
   ExecutionPlanner,
@@ -11,6 +12,7 @@ import {
   RequestClassifier,
   SpecValidator,
   WorkflowStateMachine,
+  createRuntimeAdapter,
   discoverPackageFiles,
   getFullAgentContent,
   getFullSkillFiles,
@@ -21,7 +23,7 @@ import {
   isTerminalFailure,
   readPackageFile,
   resolveWorkflowProfile
-} from "../chunk-4FI5ODAM.js";
+} from "../chunk-JDSEOEYW.js";
 import {
   EvidenceValidator,
   require_ajv,
@@ -532,6 +534,7 @@ function buildAiWorkflowConfig({ profile, runtimes = ["opencode"] }) {
   const version = getPackageVersion();
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const primaryRuntime = runtimes.join("+");
+  const codexOnly = runtimes.length === 1 && runtimes[0] === "codex";
   return {
     package: "@williambeto/ai-workflow",
     version,
@@ -540,10 +543,10 @@ function buildAiWorkflowConfig({ profile, runtimes = ["opencode"] }) {
     installMode: "project-local",
     generatedAt: now,
     paths: {
-      agents: ".ai-workflow/opencode/agents",
-      commands: ".ai-workflow/opencode/commands",
-      skills: ".ai-workflow/opencode/skills",
-      policies: ".ai-workflow/opencode/docs/policies",
+      agents: codexOnly ? ".codex/agents" : ".ai-workflow/opencode/agents",
+      commands: codexOnly ? ".codex/skills" : ".ai-workflow/opencode/commands",
+      skills: codexOnly ? ".codex/skills" : ".ai-workflow/opencode/skills",
+      policies: codexOnly ? ".codex/docs/policies" : ".ai-workflow/opencode/docs/policies",
       harness: ".ai-workflow/harness",
       schemas: ".ai-workflow/schemas"
     }
@@ -1057,167 +1060,156 @@ Every task completion MUST follow the payload format defined in the individual r
 // src/adapters/platforms/codex.ts
 import fs4 from "fs/promises";
 import path6 from "path";
+function parseMarkdownFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) return { body: content };
+  const metadata = match[1];
+  const name = metadata.match(/^name:\s*["']?([^\n"']+)["']?\s*$/m)?.[1]?.trim();
+  const description = metadata.match(/^description:\s*["']?([^\n"']+)["']?\s*$/m)?.[1]?.trim();
+  return { body: content.slice(match[0].length), name, description };
+}
+function tomlBasicString(value) {
+  return JSON.stringify(value.replace(/\r?\n/g, " "));
+}
+function tomlMultilineString(value) {
+  return value.replace(/\r\n/g, "\n").replace(/"""/g, '\\"\\"\\"');
+}
+function yamlQuoted(value) {
+  return JSON.stringify(value);
+}
+function commandSkillContent(content, commandName) {
+  const parsed = parseMarkdownFrontmatter(content);
+  const description = parsed.description || `Run the AI Workflow Kit ${commandName} command contract.`;
+  return [
+    "---",
+    `name: ${yamlQuoted(`aiwk-command-${commandName}`)}`,
+    `description: ${yamlQuoted(description)}`,
+    "---",
+    "",
+    parsed.body.trim(),
+    ""
+  ].join("\n");
+}
+function codexRootInstructions() {
+  return `# AI Workflow Kit for Codex
+
+## Purpose
+
+Transform a natural request into a proportional, safe, and verifiable software delivery.
+
+## Required flow
+
+Request \u2192 Planning \u2192 Branch Gate \u2192 Delegation when useful \u2192 Implementation \u2192 Validation \u2192 Evidence
+
+## Role ownership
+
+- Atlas routes the request and coordinates the workflow.
+- Astra owns all requested workspace mutations, including work initiated from direct chat. Atlas must delegate write work to the native \`astra\` agent; it must not write on Astra's behalf.
+- Nexus owns discovery and specifications. Orion owns technical planning and release sequencing.
+- Sage performs independent validation only when risk or evidence policy requires it. Phoenix performs bounded remediation from observed findings.
+- Do not delegate simple read-only answers merely for ceremony.
+
+## Safety and completion
+
+- Never implement directly on \`main\` or \`master\`.
+- Before changing files, inspect the branch and preserve unrelated dirty work.
+- Do not create a specification, evidence artifact, test, screenshot, or agent handoff unless the request or proportional policy requires it.
+- Run relevant validation after a workspace change. Do not report \`CHANGED\` or \`COMPLETED\` without observed validation evidence.
+- When \`ai-workflow execute\` is coordinating the task, its parent process owns finalization. A delegated agent must not run a second finalizer in that mode.
+- Report changed files, commands actually run, results, and limitations concisely. Do not print a full implementation in chat when it has been written to the workspace.
+
+## Native Codex resources
+
+- Roles are defined in \`.codex/agents/\`.
+- Reusable skills, including AIWK commands, are defined in \`.codex/skills/\`.
+- Governance policies are available in \`.codex/docs/policies/\`.
+`;
+}
+function toCodexAgentToml(name, source) {
+  const parsed = parseMarkdownFrontmatter(source);
+  const agentName = (parsed.name || name).trim().toLowerCase();
+  const description = parsed.description || `AI Workflow Kit ${agentName} agent.`;
+  const developerInstructions = [
+    parsed.body.trim(),
+    "",
+    "## Codex execution boundary",
+    "- Follow the repository AGENTS.md and this role contract.",
+    "- Report only observed commands, validations, and workspace effects.",
+    "- Do not claim another role's work or finalize the parent AI Workflow execution."
+  ].join("\n");
+  return {
+    name: agentName,
+    description,
+    content: [
+      `name = ${tomlBasicString(agentName)}`,
+      `description = ${tomlBasicString(description)}`,
+      'developer_instructions = """',
+      tomlMultilineString(developerInstructions),
+      '"""',
+      ""
+    ].join("\n")
+  };
+}
 var CodexAdapter = class {
   cwd;
   constructor({ cwd }) {
     this.cwd = cwd;
   }
-  /**
-   * Transforms an OpenCode agent into a Codex prompt with completion contract.
-   */
   async transformAgent(filePath) {
     const content = await fs4.readFile(filePath, "utf8");
-    const fileName = path6.basename(filePath, ".md");
-    const hardenedContent = `${content}
-
-##  System Directives for Codex
-- **No Conversational Filler**: Output only the requested artifact or analysis. Do not apologize or add filler text.
-- **Explicit Paths**: Always specify the exact, absolute or relative file path before making edits.
-- **Read-Only First**: Do not invent or assume file contents. Always read the workspace first.
-
-##  Completion Contract (Mandatory)
-Every task completion MUST provide the following payload:
-1. **Status**: ${COMPLETION_STATUS_TEXT}
-2. **Scope reviewed**: Brief summary of what was analyzed.
-3. **Findings**: Evidence-based discoveries.
-4. **Files affected**: List of all concrete paths modified or created.
-5. **Validation/evidence**: Commands run and their results.
-6. **Risks/notes**: Any caveats or technical debt introduced.
-7. **Required manager action**: Clear next step for the orchestrator.
-8. **Can manager continue**: [yes/no]
-`;
-    return {
-      content: hardenedContent,
-      name: fileName
-    };
+    return toCodexAgentToml(path6.basename(filePath, ".md"), content);
   }
-  /**
-   * Deploys agents, skills, and commands to Codex-native directories.
-   * Mapping:
-   * - Agents -> .github/agents/
-   * - Skills -> .agents/skills/
-   * - Commands -> .codex/prompts/
-   */
-  async deploy(installRoot = ".ai-workflow", force) {
-    const sourceAgentsDir = path6.join(this.cwd, installRoot, "opencode/agents");
-    const sourceSkillsDir = path6.join(this.cwd, installRoot, "opencode/skills");
-    const sourceCommandsDir = path6.join(this.cwd, installRoot, "opencode/commands");
-    const codexAgentsDir = path6.join(this.cwd, ".github/agents");
+  async deploy(installRoot = ".ai-workflow", force = false) {
+    const sourceAgentsDir = path6.join(this.cwd, installRoot, "opencode", "agents");
+    const sourceSkillsDir = path6.join(this.cwd, installRoot, "opencode", "skills");
+    const sourceCommandsDir = path6.join(this.cwd, installRoot, "opencode", "commands");
+    const codexAgentsDir = path6.join(this.cwd, ".codex", "agents");
     await fs4.mkdir(codexAgentsDir, { recursive: true });
-    const agentFiles = await fs4.readdir(sourceAgentsDir).catch(() => []);
-    for (const file of agentFiles) {
+    for (const file of await fs4.readdir(sourceAgentsDir).catch(() => [])) {
       if (!file.endsWith(".md")) continue;
       const transformed = await this.transformAgent(path6.join(sourceAgentsDir, file));
-      await fs4.writeFile(path6.join(codexAgentsDir, `${transformed.name}.md`), transformed.content);
+      await fs4.writeFile(path6.join(codexAgentsDir, `${transformed.name}.toml`), transformed.content);
     }
-    const codexSkillsDir = path6.join(this.cwd, ".codex/skills");
+    const codexSkillsDir = path6.join(this.cwd, ".codex", "skills");
     await fs4.mkdir(codexSkillsDir, { recursive: true });
-    const skillFolders = await fs4.readdir(sourceSkillsDir).catch(() => []);
-    for (const folder of skillFolders) {
+    for (const folder of await fs4.readdir(sourceSkillsDir).catch(() => [])) {
       const skillSource = path6.join(sourceSkillsDir, folder, "SKILL.md");
-      if (await this.exists(skillSource)) {
-        const targetDir = path6.join(codexSkillsDir, folder);
-        await fs4.mkdir(targetDir, { recursive: true });
-        const content = await fs4.readFile(skillSource, "utf8");
-        await fs4.writeFile(path6.join(targetDir, "SKILL.md"), content);
-      }
-    }
-    const codexPromptsDir = path6.join(this.cwd, ".codex/prompts");
-    await fs4.mkdir(codexPromptsDir, { recursive: true });
-    const commandFiles = await fs4.readdir(sourceCommandsDir).catch(() => []);
-    for (const file of commandFiles) {
-      if (!file.endsWith(".md") && !file.endsWith(".toml")) continue;
-      const targetFileName = file.endsWith(".toml") ? `${path6.basename(file, ".toml")}.md` : file;
-      const content = await fs4.readFile(path6.join(sourceCommandsDir, file), "utf8");
-      await fs4.writeFile(path6.join(codexPromptsDir, targetFileName), content);
+      if (!await this.exists(skillSource)) continue;
+      const targetDir = path6.join(codexSkillsDir, folder);
+      await fs4.mkdir(targetDir, { recursive: true });
+      await fs4.writeFile(path6.join(targetDir, "SKILL.md"), await fs4.readFile(skillSource, "utf8"));
+    }
+    for (const file of await fs4.readdir(sourceCommandsDir).catch(() => [])) {
+      if (!file.endsWith(".md") || file.toLowerCase() === "readme.md") continue;
+      const commandName = path6.basename(file, ".md");
+      const targetDir = path6.join(codexSkillsDir, `aiwk-command-${commandName}`);
+      await fs4.mkdir(targetDir, { recursive: true });
+      const source = await fs4.readFile(path6.join(sourceCommandsDir, file), "utf8");
+      await fs4.writeFile(path6.join(targetDir, "SKILL.md"), commandSkillContent(source, commandName));
     }
     const codexPoliciesDir = path6.join(this.cwd, ".codex", "docs", "policies");
     await fs4.mkdir(codexPoliciesDir, { recursive: true });
     const sourcePoliciesDir = path6.join(this.cwd, installRoot, "opencode", "docs", "policies");
-    const policyFiles = await fs4.readdir(sourcePoliciesDir).catch(() => []);
-    for (const file of policyFiles) {
+    for (const file of await fs4.readdir(sourcePoliciesDir).catch(() => [])) {
       if (!file.endsWith(".md")) continue;
-      const policyContent = await fs4.readFile(path6.join(sourcePoliciesDir, file), "utf8");
-      await fs4.writeFile(path6.join(codexPoliciesDir, file), policyContent);
+      await fs4.writeFile(
+        path6.join(codexPoliciesDir, file),
+        await fs4.readFile(path6.join(sourcePoliciesDir, file), "utf8")
+      );
     }
-    await this.deployRootCopilotInstructions();
-    await this.deployRootCodexMd(force);
     await this.deployRootAgentsMd(force);
   }
-  async deployRootCopilotInstructions() {
-    const githubDir = path6.join(this.cwd, ".github");
-    await fs4.mkdir(githubDir, { recursive: true });
-    const targetPath = path6.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/\`.
-
-##  System Boundaries
-- **No Conversational Filler**: Do not apologize or add filler text.
-- **Strict Evidence**: You must provide the Completion Contract payload when finishing a task.
-- **Immutable Core**: Do not modify files inside \`.ai-workflow/\`, \`.agents/\`, \`.claude/\`, or \`.codex/\` unless explicitly requested.
-
-##  Completion Contract
-Every task completion MUST follow the payload format defined in the individual agent files.
-`;
-    await fs4.writeFile(targetPath, instructions);
-  }
-  async deployRootCodexMd(force) {
-    const targetPath = path6.join(this.cwd, "CODEX.md");
-    if (!force && await this.exists(targetPath)) return;
-    const templatePath = path6.join(this.cwd, ".ai-workflow", "templates", "CODEX.md.template");
-    if (await this.exists(templatePath)) {
-      const content = await fs4.readFile(templatePath, "utf8");
-      await fs4.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/\`.
-
-##  System Boundaries
-- **No Conversational Filler**: Do not apologize or add filler text.
-- **Strict Evidence**: You must provide the Completion Contract payload when finishing a task.
-- **Immutable Core**: Do not modify files inside \`.ai-workflow/\`, \`.agents/\`, \`.claude/\`, or \`.codex/\` unless explicitly requested.
-
-##  Completion Contract
-Every task completion MUST follow the payload format defined in the individual agent files.
-`;
-    await fs4.writeFile(targetPath, instructions);
-  }
-  async deployRootAgentsMd(force) {
+  async deployRootAgentsMd(force = false) {
     const targetPath = path6.join(this.cwd, "AGENTS.md");
-    if (!force && await this.exists(targetPath)) return;
-    const templatePath = path6.join(this.cwd, ".ai-workflow", "AGENTS.md");
-    if (await this.exists(templatePath)) {
-      let content = await fs4.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 fs4.writeFile(targetPath, content);
+    if (!force && await this.exists(targetPath)) {
+      const existing = await fs4.readFile(targetPath, "utf8");
+      if (!existing.startsWith("# AI Workflow Kit contributor contract") && !existing.startsWith("# AI Workflow Kit for Codex")) return;
     }
+    await fs4.writeFile(targetPath, codexRootInstructions());
   }
-  async exists(p) {
+  async exists(candidate) {
     try {
-      await fs4.access(p);
+      await fs4.access(candidate);
       return true;
     } catch {
       return false;
@@ -1726,7 +1718,7 @@ async function executePlatformMigrations(cwd, installRoot, platforms, claude, co
   if (codex) {
     const adapter = new CodexAdapter({ cwd });
     await adapter.deploy(installRoot, force);
-    console.log("- codex: deployed AI Workflow Kit agents to .agents/, .codex/, and .github/ (native discovery enabled)");
+    console.log("- codex: deployed native agents to .codex/agents and skills (including commands) to .codex/skills");
   }
   if (antigravity) {
     const adapter = new AntigravityAdapter({ cwd });
@@ -2036,24 +2028,79 @@ async function checkPackageJson(cwd, state) {
   }
 }
 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(path9.join(cwd, check.path));
-    if (ok) {
-      console.log(`PASS ${check.name}`);
+  const rootAgentsPath = path9.join(cwd, "AGENTS.md");
+  const rootAgents = await fs7.readFile(rootAgentsPath, "utf8").catch(() => "");
+  if (!rootAgents) {
+    state.hasFailure = true;
+    console.log("FAIL root AGENTS.md missing");
+  } else if (!rootAgents.includes("Astra owns all requested workspace mutations")) {
+    state.hasFailure = true;
+    console.log("FAIL root AGENTS.md lacks the Codex Astra ownership contract");
+  } else {
+    console.log("PASS root AGENTS.md contains the Codex workflow contract");
+  }
+  const agentsDir = path9.join(cwd, ".codex", "agents");
+  const requiredAgents = ["atlas", "astra", "nexus", "orion", "sage", "phoenix"];
+  for (const agent of requiredAgents) {
+    const agentPath = path9.join(agentsDir, `${agent}.toml`);
+    const content = await fs7.readFile(agentPath, "utf8").catch(() => "");
+    const valid = new RegExp(`^name\\s*=\\s*["']${agent}["']\\s*$`, "m").test(content) && /^description\s*=\s*["']\S/m.test(content) && /^developer_instructions\s*=\s*"""/m.test(content) && /"""\s*$/m.test(content);
+    if (valid) {
+      console.log(`PASS native Codex agent: ${agent}`);
+    } else {
+      state.hasFailure = true;
+      console.log(`FAIL native Codex agent invalid or missing: ${agent}`);
+    }
+  }
+  const skillsDir = path9.join(cwd, ".codex", "skills");
+  const skillFolders = await fs7.readdir(skillsDir).catch(() => []);
+  if (skillFolders.length === 0) {
+    state.hasFailure = true;
+    console.log("FAIL .codex/skills missing or empty");
+  } else {
+    console.log(`PASS .codex/skills detected (${skillFolders.length})`);
+  }
+  const sourceCommandsDir = path9.join(cwd, ".ai-workflow", "opencode", "commands");
+  for (const command of await fs7.readdir(sourceCommandsDir).catch(() => [])) {
+    if (!command.endsWith(".md") || command.toLowerCase() === "readme.md") continue;
+    const name = path9.basename(command, ".md");
+    const commandSkillPath = path9.join(skillsDir, `aiwk-command-${name}`, "SKILL.md");
+    const content = await fs7.readFile(commandSkillPath, "utf8").catch(() => "");
+    if (content.includes(`name: "aiwk-command-${name}"`)) {
+      console.log(`PASS Codex command skill: ${name}`);
     } else {
       state.hasFailure = true;
-      console.log(`FAIL ${check.name}`);
+      console.log(`FAIL Codex command skill invalid or missing: ${name}`);
     }
   }
-  const codexMdOk = await exists(path9.join(cwd, "CODEX.md"));
-  if (codexMdOk) {
-    console.log(`PASS root CODEX.md exists`);
+  if (await exists(path9.join(cwd, ".codex", "docs", "policies"))) {
+    console.log("PASS .codex/docs/policies detected");
+  } else {
+    state.hasFailure = true;
+    console.log("FAIL .codex/docs/policies missing");
+  }
+  if (await exists(path9.join(cwd, ".codex", "prompts"))) {
+    state.hasWarning = true;
+    console.log("WARN legacy .codex/prompts detected; AIWK commands now use .codex/skills");
+  }
+  const adapter = new CodexRuntimeAdapter({ cwd });
+  const inspection = await adapter.inspect();
+  if (!inspection.available) {
+    state.hasFailure = true;
+    console.log("FAIL Codex CLI is not installed or not available in PATH");
+  } else if (!inspection.supports.formatJson) {
+    state.hasFailure = true;
+    console.log("FAIL Codex CLI lacks exec --json required for observed evidence");
+  } else if (inspection.projectTrusted === false) {
+    state.hasFailure = true;
+    console.log("FAIL Codex project is not trusted; native agents are disabled until this repository is trusted in Codex");
+  } else if (!inspection.supports.agent) {
+    state.hasFailure = true;
+    console.log("FAIL Codex native agents are incomplete");
+  } else {
+    state.hasWarning = true;
+    console.log("PASS Codex CLI, JSON events, and native agents are available");
+    console.log("WARN Codex CLI delivery is blocked because `codex exec` cannot prove custom-agent ownership; use interactive Codex");
   }
   if (state.runtimes.includes("codex")) {
     console.log("PASS config runtime includes codex");
@@ -2497,7 +2544,7 @@ async function findCompatibleLedger(cwd, specRelativePath) {
   }
   return matches;
 }
-async function runDeepImplementation(cwd, absoluteSpecPath, specPath, approvalPath, specContent) {
+async function runDeepImplementation(cwd, absoluteSpecPath, specPath, approvalPath, specContent, runtime) {
   if (!approvalPath) throw new Error("[SDD BLOCKED] DEEP resume requires --approval-path.");
   const approvalValidator = new ApprovalReceiptValidator({ cwd });
   const approval = await approvalValidator.validate(approvalPath, absoluteSpecPath);
@@ -2537,7 +2584,9 @@ async function runDeepImplementation(cwd, absoluteSpecPath, specPath, approvalPa
     throw new Error("[SDD BLOCKED] Ledger specification path does not match --spec-path.");
   }
   const draftHash = nexusTerminals[0]?.data?.artifactHash || null;
-  const controller = new DelegationController({ cwd, ledger, adapter: new OpenCodeAdapter({ cwd }) });
+  const runtimeAdapter = await createRuntimeAdapter({ cwd, runtime });
+  console.log(`[RUNTIME] ${runtimeAdapter.runtime}`);
+  const controller = new DelegationController({ cwd, ledger, adapter: runtimeAdapter });
   const absolutePlanPath = path14.join(cwd, "docs/workflows", workflowId, "technical-plan.json");
   const relativePlanPath = repositoryRelative(cwd, absolutePlanPath);
   if (await fs12.access(absolutePlanPath).then(() => true).catch(() => false)) {
@@ -2645,7 +2694,7 @@ async function runDeepImplementation(cwd, absoluteSpecPath, specPath, approvalPa
     controller
   };
 }
-async function runMasterOrchestrator({ cwd, specPath, approvalPath, override, remediationExecutor = null }) {
+async function runMasterOrchestrator({ cwd, specPath, approvalPath, override, remediationExecutor = null, runtime }) {
   if (process.env.AI_WORKFLOW_FINALIZATION_OWNER === "execute") {
     throw new Error("[NESTED EXECUTION BLOCKED] The parent execute process owns orchestration and finalization.");
   }
@@ -2669,7 +2718,7 @@ async function runMasterOrchestrator({ cwd, specPath, approvalPath, override, re
   const profileDefinition = getWorkflowProfile(workflowProfile);
   console.log(`[PASS] Specification: ${specTier.toUpperCase()} spec is APPROVED.`);
   console.log(`[PROFILE] ${workflowProfile} -> ${profileDefinition.owner}; skills: ${profileDefinition.skills.join(", ") || "none"}.`);
-  const deepContext = specTier === "deep" ? await runDeepImplementation(cwd, absoluteSpecPath, specPath, approvalPath, specContent) : null;
+  const deepContext = specTier === "deep" ? await runDeepImplementation(cwd, absoluteSpecPath, specPath, approvalPath, specContent, runtime) : null;
   const validateWorkflow = async () => {
     const evidence = await runCollectEvidence({
       cwd,
@@ -2735,8 +2784,7 @@ async function runMasterOrchestrator({ cwd, specPath, approvalPath, override, re
 import fs13 from "fs/promises";
 import path15 from "path";
 import { execSync as execSync3 } from "child_process";
-function createRuntimeRemediationExecutor(cwd, ledger = null) {
-  const adapter = new OpenCodeAdapter({ cwd });
+function createRuntimeRemediationExecutor(cwd, ledger = null, adapter = new OpenCodeAdapter({ cwd })) {
   function getChangedFiles2() {
     try {
       const output = execSync3("git status --short", { cwd, encoding: "utf8" });
@@ -2761,9 +2809,9 @@ function createRuntimeRemediationExecutor(cwd, ledger = null) {
         actor: "Phoenix",
         actorType: "runtime-agent",
         observed: true,
-        runtime: "opencode",
+        runtime: adapter.runtime,
         eventType: "remediation_start",
-        provenance: "opencode-adapter",
+        provenance: adapter.provenance,
         data: {
           attempt,
           affectedChecks,
@@ -3119,9 +3167,9 @@ async function runImplementation(plan, classification, delegationController, sta
   }
   const runResult = await delegationController.implement(promptMsg, plan.owner, { readOnly: !plan.branchNeeded, fastTrack, orchestratedChild: true });
   if (!runResult.success) {
-    console.error(`[EXECUTE] OpenCode adapter execution reported failure: ${runResult.error || "Unknown error"}`);
+    console.error(`[EXECUTE] Runtime execution reported failure: ${runResult.error || "Unknown error"}`);
     stateMachine.transitionTo("BLOCKED");
-    throw new Error(`[WORKFLOW BLOCKED] OpenCode runtime execution failed: ${runResult.error || "Unknown error"}`);
+    throw new Error(`[WORKFLOW BLOCKED] Runtime execution failed: ${runResult.error || "Unknown error"}`);
   }
   return runResult;
 }
@@ -3170,13 +3218,13 @@ async function runValidation(plan, taskSlug, cwd, gateResult, naturalRequest, cl
   const result = await delegationController.validate(taskSlug, plan.profile, validateWorkflow, plan.evidencePolicy);
   return { result, validateWorkflow };
 }
-async function runBoundedRemediation(plan, taskSlug, cwd, initialResult, validateWorkflow, ledger, delegationController, stateMachine, checkBranchSafety, updateSnapshot) {
+async function runBoundedRemediation(plan, taskSlug, cwd, initialResult, validateWorkflow, ledger, delegationController, runtimeAdapter, stateMachine, checkBranchSafety, updateSnapshot) {
   if (!isRecoverableGateFailure(initialResult.overallStatus)) {
     return initialResult;
   }
   console.log(`
 [REMEDIATION REQUIRED] ${initialResult.overallStatus}. Starting bounded remediation (limit: ${plan.remediationLimit}).`);
-  const executor = createRuntimeRemediationExecutor(cwd, ledger);
+  const executor = createRuntimeRemediationExecutor(cwd, ledger, runtimeAdapter);
   const healer = new HealerEngine({
     cwd,
     remediationLimit: plan.remediationLimit,
@@ -3303,7 +3351,7 @@ async function executeReadOnlyWorkflow(cwd, stateMachine, readOnlyStateBefore, f
     stateHistory: stateMachine.getHistory()
   };
 }
-async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
+async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride, runtime }) {
   if (process.env.AI_WORKFLOW_FINALIZATION_OWNER === "execute") {
     throw new Error("[NESTED EXECUTION BLOCKED] The parent execute process owns orchestration and finalization.");
   }
@@ -3315,7 +3363,9 @@ async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
 [AI WORKFLOW] Executing natural request intake [slug: ${taskSlug}]...
 `);
   const ledger = new EvidenceLedger({ cwd, workflowId: taskSlug });
-  const delegationController = new DelegationController({ cwd, ledger, adapter: new OpenCodeAdapter({ cwd }) });
+  const runtimeAdapter = await createRuntimeAdapter({ cwd, runtime });
+  console.log(`[RUNTIME] ${runtimeAdapter.runtime}`);
+  const delegationController = new DelegationController({ cwd, ledger, adapter: runtimeAdapter });
   let plan = null;
   let branchAuthorized = false;
   try {
@@ -3380,6 +3430,7 @@ async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
       validateWorkflow,
       ledger,
       delegationController,
+      runtimeAdapter,
       stateMachine,
       checkBranchSafety,
       async () => {
@@ -3547,8 +3598,8 @@ function printHelp() {
   console.log(`ai-workflow
 
 Usage:
-  ai-workflow execute "<request>" [--task=<slug>] [--request="<request>"]
-  ai-workflow run --spec-path=<path> [--approval-path=<path>]
+  ai-workflow execute "<request>" [--task=<slug>] [--request="<request>"] [--runtime=<opencode|codex>]
+  ai-workflow run --spec-path=<path> [--approval-path=<path>] [--runtime=<opencode|codex>]
   ai-workflow init [--yes] [--force] [--dry-run] [--no-install] [--no-overwrite] [--claude] [--codex] [--antigravity] [--profile=<profile>]
   ai-workflow validate [--a11y] [--visual-dist=<path>] [--port=<port>]
   ai-workflow collect-evidence [--task=<slug>] [--evidence-policy=<optional|required>] [--mode=<quick|standard|full>] [--dry-run] [--visual-dist=<path>] [--port=<port>]
@@ -3578,6 +3629,7 @@ function parseFlags(args) {
   const requestArg = args.find((arg) => arg.startsWith("--request="));
   const visualDistArg = args.find((arg) => arg.startsWith("--visual-dist="));
   const portArg = args.find((arg) => arg.startsWith("--port="));
+  const runtimeArg = args.find((arg) => arg.startsWith("--runtime="));
   const profileIdx = args.indexOf("--profile");
   const profileVal = profileEqArg ? profileEqArg.replace("--profile=", "") : profileIdx >= 0 && profileIdx + 1 < args.length && !args[profileIdx + 1].startsWith("--") ? args[profileIdx + 1] : void 0;
   return {
@@ -3599,6 +3651,7 @@ function parseFlags(args) {
     request: requestArg ? requestArg.replace("--request=", "") : void 0,
     visualDist: visualDistArg ? visualDistArg.replace("--visual-dist=", "") : void 0,
     port: portArg ? portArg.replace("--port=", "") : void 0,
+    runtime: runtimeArg ? runtimeArg.replace("--runtime=", "") : void 0,
     a11y: args.includes("--a11y"),
     purgeAgents: args.includes("--purge-agents") || args.includes("--purge")
   };
@@ -3610,7 +3663,8 @@ var commandMap = {
     const result = await runExecute({
       cwd: process.cwd(),
       naturalRequest: request,
-      taskSlug: flags.taskSlug
+      taskSlug: flags.taskSlug,
+      runtime: flags.runtime
     });
     if (result && (result.overallStatus === "FAIL_QUALITY_GATE" || result.overallStatus === "BLOCKED" || result.overallStatus === "FAIL")) {
       process.exitCode = result.exitCode === 2 ? 2 : 1;