@williambeto/ai-workflow 2.4.9 → 2.6.3

package/bin/ai-workflow.js

@@ -1,8 +1,2676 @@
 #!/usr/bin/env node
+import {
+  BranchGate,
+  COMPLETION_STATUS_TEXT,
+  DelegationController,
+  EvidenceLedger,
+  ExecutionPlanner,
+  Finalizer,
+  HandoffEngine,
+  HealerEngine,
+  OpenCodeAdapter,
+  RequestClassifier,
+  SpecValidator,
+  WorkflowStateMachine,
+  discoverPackageFiles,
+  getFullAgentContent,
+  getFullSkillFiles,
+  getPackageVersion,
+  getWorkflowProfile,
+  isRecoverableGateFailure,
+  isTerminalFailure,
+  readPackageFile,
+  resolveWorkflowProfile
+} from "../chunk-UHLZX2EG.js";
+import {
+  EvidenceCollector,
+  QualityGuard,
+  ValidationPlanner
+} from "../chunk-6EMG6FAO.js";
+import "../chunk-2AOV2ATY.js";
+import "../chunk-5WRI5ZAA.js";
 
-import { runCli } from "../src/cli.js";
+// src/cli/commands/init.ts
+import fs7 from "fs/promises";
+import path9 from "path";
 
+// src/core/install-plan.ts
+import path from "path";
+
+// src/core/templates.ts
+var COMMON_FILES = {
+  "opencode/README.md": `# OpenCode Setup
+
+This directory is managed by \`ai-workflow\` init.
+Add agent and command files required by your project workflow.
+`
+};
+var FULL_PRIMARY_AGENTS = [
+  "atlas",
+  "nexus",
+  "orion",
+  "astra",
+  "sage",
+  "phoenix"
+];
+var FULL_SKILLS = [
+  "project-memory",
+  "optimize-tokens",
+  "documentation",
+  "architecture",
+  "technical-leadership",
+  "product-discovery",
+  "product-planning",
+  "spec-driven-development",
+  "pr-workflow",
+  "qa-workflow",
+  "release-workflow",
+  "deployment",
+  "ui-ux-design",
+  "design-principles",
+  "frontend-development",
+  "backend-development",
+  "full-stack-development",
+  "refactoring",
+  "prompt-engineer"
+];
+function buildRuntimeFiles({ includeFormalEvidence = false } = {}) {
+  const files = {};
+  for (const agent of FULL_PRIMARY_AGENTS) {
+    const content = getFullAgentContent(agent);
+    if (content === null) {
+      throw new Error(`CRITICAL FAILURE: Missing required agent asset: dist-assets/agents/${agent}.md`);
+    }
+    files[`opencode/agents/${agent}.md`] = content;
+  }
+  for (const skill of FULL_SKILLS) {
+    const skillFiles = getFullSkillFiles(skill);
+    if (Object.keys(skillFiles).length === 0) {
+      continue;
+    }
+    for (const [relPath, content] of Object.entries(skillFiles)) {
+      const targetPath = relPath.replace(/^dist-assets\//, "opencode/");
+      if (!files[targetPath]) {
+        files[targetPath] = content;
+      }
+    }
+  }
+  const opencodeGovernancePolicy = readPackageFile("dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md");
+  if (opencodeGovernancePolicy !== null) {
+    files["opencode/docs/policies/SKILLS_COMMON_GOVERNANCE.md"] = opencodeGovernancePolicy;
+  }
+  const commandFiles = discoverPackageFiles("dist-assets/commands");
+  for (const [relPath, content] of Object.entries(commandFiles)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "opencode/");
+    if (!files[targetPath]) {
+      files[targetPath] = content;
+    }
+  }
+  const opencodeSkillFiles = discoverPackageFiles("dist-assets/skills");
+  for (const [relPath, content] of Object.entries(opencodeSkillFiles)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "opencode/");
+    if (!files[targetPath]) {
+      files[targetPath] = content;
+    }
+  }
+  const harnessWorkflowFiles = discoverPackageFiles("dist-assets/harness/workflows");
+  for (const [relPath, content] of Object.entries(harnessWorkflowFiles)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "");
+    files[targetPath] = content;
+  }
+  const harnessHandoffFiles = discoverPackageFiles("dist-assets/harness/handoffs");
+  for (const [relPath, content] of Object.entries(harnessHandoffFiles)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "");
+    files[targetPath] = content;
+  }
+  const agentsContent = readPackageFile("dist-assets/AGENTS.md");
+  if (agentsContent !== null) files["AGENTS.md"] = agentsContent;
+  const consumerQuickstart = readPackageFile("dist-assets/docs/QUICKSTART.md");
+  if (consumerQuickstart !== null) files["QUICKSTART.md"] = consumerQuickstart;
+  const policyContent = readPackageFile("dist-assets/docs/architecture-policy.md");
+  if (policyContent !== null) files["opencode/docs/architecture-policy.md"] = policyContent;
+  const dpContent = readPackageFile("dist-assets/docs/design-patterns-policy.md");
+  if (dpContent !== null) files["opencode/docs/design-patterns-policy.md"] = dpContent;
+  const visualValidationGuide = readPackageFile("dist-assets/docs/visual-validation-guide.md");
+  if (visualValidationGuide !== null) files["opencode/docs/visual-validation-guide.md"] = visualValidationGuide;
+  const governancePolicies = discoverPackageFiles("dist-assets/docs/policies");
+  for (const [relPath, content] of Object.entries(governancePolicies)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "opencode/");
+    files[targetPath] = content;
+  }
+  const compatibilityDocs = discoverPackageFiles("dist-assets/docs/compatibility");
+  for (const [relPath, content] of Object.entries(compatibilityDocs)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "opencode/");
+    files[targetPath] = content;
+  }
+  const qualityReferenceFiles = discoverPackageFiles("dist-assets/docs/references");
+  for (const [relPath, content] of Object.entries(qualityReferenceFiles)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "opencode/");
+    files[targetPath] = content;
+  }
+  const workflowProfileFiles = discoverPackageFiles("dist-assets/docs/profiles");
+  for (const [relPath, content] of Object.entries(workflowProfileFiles)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "opencode/");
+    files[targetPath] = content;
+  }
+  const templateFiles = discoverPackageFiles("dist-assets/templates");
+  for (const [relPath, content] of Object.entries(templateFiles)) {
+    if (!includeFormalEvidence && relPath.includes("/owner-evidence/")) continue;
+    const targetPath = relPath.replace(/^dist-assets\//, "");
+    files[targetPath] = content;
+  }
+  const schemaFiles = discoverPackageFiles("dist-assets/schemas");
+  for (const [relPath, content] of Object.entries(schemaFiles)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "");
+    files[targetPath] = content;
+  }
+  return files;
+}
+function buildExtraFiles() {
+  const files = {};
+  const exampleFiles = discoverPackageFiles("dist-assets/examples");
+  for (const [relPath, content] of Object.entries(exampleFiles)) {
+    const targetPath = relPath.replace(/^dist-assets\//, "");
+    files[targetPath] = content;
+  }
+  return files;
+}
+var STANDARD_FILES = buildRuntimeFiles();
+var FULL_FILES = { ...buildRuntimeFiles({ includeFormalEvidence: true }), ...buildExtraFiles() };
+var PROFILE_FILES = {
+  standard: {
+    ...COMMON_FILES,
+    ...STANDARD_FILES
+  },
+  full: {
+    ...COMMON_FILES,
+    ...FULL_FILES
+  }
+};
+function isValidProfile(profile) {
+  return profile === "standard" || profile === "full";
+}
+function getTemplateFiles(profile = "standard") {
+  return PROFILE_FILES[profile] ?? PROFILE_FILES.standard;
+}
+function buildAiWorkflowConfig({ profile }) {
+  const version = getPackageVersion();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    package: "@williambeto/ai-workflow",
+    version,
+    runtime: "opencode",
+    profile,
+    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",
+      harness: ".ai-workflow/harness",
+      schemas: ".ai-workflow/schemas"
+    }
+  };
+}
+
+// src/core/install-plan.ts
+async function createInstallPlan({
+  cwd,
+  exists: exists3,
+  profile = "standard"
+}) {
+  const actions = [];
+  const templateFiles = getTemplateFiles(profile);
+  const installRoot = ".ai-workflow";
+  for (const [relativePath, content] of Object.entries(templateFiles)) {
+    if (relativePath === "opencode.jsonc") {
+      continue;
+    }
+    const installedRelativePath = path.join(installRoot, relativePath);
+    const absolutePath = path.join(cwd, installedRelativePath);
+    const action = await exists3(absolutePath) ? "conflict" : "create";
+    actions.push({
+      type: action,
+      relativePath: installedRelativePath,
+      absolutePath,
+      content
+    });
+  }
+  const configPath = path.join(cwd, ".ai-workflow/config.json");
+  actions.push({
+    type: await exists3(configPath) ? "conflict" : "create",
+    relativePath: ".ai-workflow/config.json",
+    absolutePath: configPath,
+    content: null
+  });
+  return actions;
+}
+
+// src/core/filesystem.ts
+import fs from "fs/promises";
+import path2 from "path";
+import { execSync } from "child_process";
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function writeFileSafe(filePath, content) {
+  const absolutePath = path2.resolve(filePath);
+  const repoCwd = path2.resolve(process.cwd());
+  const relativeToRepo = path2.relative(repoCwd, absolutePath).replaceAll("\\", "/");
+  const isOperational = relativeToRepo === "EVIDENCE.json" || relativeToRepo.startsWith(".ai-workflow/") || relativeToRepo.startsWith(".ai-workflow\\");
+  if (!isOperational) {
+    let currentBranch = "";
+    const fileCwd = path2.dirname(absolutePath);
+    try {
+      currentBranch = execSync("git branch --show-current", { cwd: fileCwd, encoding: "utf8", stdio: "pipe" }).trim();
+    } catch {
+    }
+    const protectedBranches = ["main", "master"];
+    const isInitCommand = process.argv.includes("init");
+    if (protectedBranches.includes(currentBranch) && !isInitCommand) {
+      if (process.env.AI_WORKFLOW_BYPASS_PROTECTED_BRANCH !== "true") {
+        throw new Error("FAIL_PROTECTED_BRANCH: Direct writes to protected branch are prohibited.");
+      }
+    }
+  }
+  await fs.mkdir(path2.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, content, "utf8");
+}
+async function readJson(filePath) {
+  const content = await fs.readFile(filePath, "utf8");
+  return JSON.parse(content);
+}
+function stripJsonComments(content) {
+  let output = "";
+  let inString = false;
+  let quote = "";
+  let escaped = false;
+  let inLineComment = false;
+  let inBlockComment = false;
+  for (let index = 0; index < content.length; index += 1) {
+    const char = content[index];
+    const next = content[index + 1];
+    if (inLineComment) {
+      if (char === "\n" || char === "\r") {
+        inLineComment = false;
+        output += char;
+      }
+      continue;
+    }
+    if (inBlockComment) {
+      if (char === "*" && next === "/") {
+        inBlockComment = false;
+        index += 1;
+        continue;
+      }
+      if (char === "\n" || char === "\r") {
+        output += char;
+      }
+      continue;
+    }
+    if (inString) {
+      output += char;
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === quote) {
+        inString = false;
+        quote = "";
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      inString = true;
+      quote = char;
+      output += char;
+      continue;
+    }
+    if (char === "/" && next === "/") {
+      inLineComment = true;
+      index += 1;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      inBlockComment = true;
+      index += 1;
+      continue;
+    }
+    output += char;
+  }
+  return output;
+}
+function stripTrailingCommas(content) {
+  let output = "";
+  let inString = false;
+  let quote = "";
+  let escaped = false;
+  for (let index = 0; index < content.length; index += 1) {
+    const char = content[index];
+    if (inString) {
+      output += char;
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === quote) {
+        inString = false;
+        quote = "";
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      inString = true;
+      quote = char;
+      output += char;
+      continue;
+    }
+    if (char === ",") {
+      let nextIndex = index + 1;
+      while (/\s/.test(content[nextIndex] ?? "")) {
+        nextIndex += 1;
+      }
+      if (content[nextIndex] === "}" || content[nextIndex] === "]") {
+        continue;
+      }
+    }
+    output += char;
+  }
+  return output;
+}
+async function readJsonc(filePath) {
+  const content = await fs.readFile(filePath, "utf8");
+  return JSON.parse(stripTrailingCommas(stripJsonComments(content)));
+}
+
+// src/core/backup.ts
+import fs2 from "fs/promises";
+import path3 from "path";
+function escapeRelativePath(relativePath) {
+  return relativePath.replace(/[\\/]/g, "__");
+}
+async function createManagedBackup(filePath, { cwd, backupRoot, maxPerFile = 20 }) {
+  const relativePath = path3.relative(cwd, filePath);
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const backupName = `${escapeRelativePath(relativePath)}.${stamp}.bak`;
+  const absoluteBackupRoot = path3.join(cwd, backupRoot);
+  const backupPath = path3.join(absoluteBackupRoot, backupName);
+  await fs2.mkdir(absoluteBackupRoot, { recursive: true });
+  await fs2.copyFile(filePath, backupPath);
+  const prefix = `${escapeRelativePath(relativePath)}.`;
+  const entries = await fs2.readdir(absoluteBackupRoot);
+  const matching = entries.filter((entry) => entry.startsWith(prefix) && entry.endsWith(".bak")).sort();
+  if (matching.length > maxPerFile) {
+    const excess = matching.slice(0, matching.length - maxPerFile);
+    await Promise.all(excess.map((entry) => fs2.unlink(path3.join(absoluteBackupRoot, entry))));
+  }
+  return backupPath;
+}
+async function createManagedPathBackup(targetPath, { cwd, backupRoot, maxPerFile = 20 }) {
+  const relativePath = path3.relative(cwd, targetPath);
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const backupName = `${escapeRelativePath(relativePath)}.${stamp}.bak`;
+  const absoluteBackupRoot = path3.join(cwd, backupRoot);
+  const backupPath = path3.join(absoluteBackupRoot, backupName);
+  await fs2.mkdir(absoluteBackupRoot, { recursive: true });
+  await fs2.rename(targetPath, backupPath);
+  const prefix = `${escapeRelativePath(relativePath)}.`;
+  const entries = await fs2.readdir(absoluteBackupRoot);
+  const matching = entries.filter((entry) => entry.startsWith(prefix) && entry.endsWith(".bak")).sort();
+  if (matching.length > maxPerFile) {
+    const excess = matching.slice(0, matching.length - maxPerFile);
+    await Promise.all(excess.map((entry) => fs2.rm(path3.join(absoluteBackupRoot, entry), { recursive: true, force: true })));
+  }
+  return backupPath;
+}
+
+// src/core/opencode-merge.ts
+import path4 from "path";
+var LEGACY_MARKER = "_aiWorkflowManaged";
+var AGENTS = {
+  Atlas: { description: "Router and workflow coordinator for AI Workflow Kit" },
+  Nexus: { description: "Discovery, requirement, scope, and specification owner" },
+  Orion: { description: "Planning, PR sequencing, release, and deployment strategy owner" },
+  Astra: { description: "Implementation owner for incremental, scoped changes" },
+  Sage: { description: "Audit, validation, evidence, and quality gate owner" },
+  Phoenix: { description: "Remediation and regression recovery owner" }
+};
+var SUBAGENTS = {
+  "Architecture-Specialist": { description: "Select the simplest architecture that safely satisfies current requirements", skill: "architecture" },
+  "Backend-Engineer": { description: "Support safe PHP/Node/Python backend changes for APIs and persistence", skill: "backend-development" },
+  "Deployment-Specialist": { description: "Plan, review, or validate deployment, release, and production-readiness", skill: "deployment" },
+  "Design-Specialist": { description: "Apply practical design principles to keep solutions simple and maintainable", skill: "design-principles" },
+  "Docs-Engineer": { description: "Write or improve project documentation, READMEs, guides, and prompts", skill: "documentation" },
+  "Frontend-Engineer": { description: "Implement or review frontend changes involving UI, state, routing, and accessibility", skill: "frontend-development" },
+  "Frontend-Design-System-Specialist": { description: "Enforce CSS/HTML tokens, semantic elements, typography, and premium atmosphere constraints for frontend quality", skill: "frontend-design-system" },
+  "Full-Stack-Engineer": { description: "Coordinate frontend and backend changes as one coherent, testable increment", skill: "full-stack-development" },
+  "Token-Economist": { description: "Reduce context size while preserving information required for safe execution", skill: "optimize-tokens" },
+  "PR-Manager": { description: "Plan, implement, review, or validate small pull requests while preserving scope", skill: "pr-workflow" },
+  "Discovery-Analyst": { description: "Clarify ambiguous requests into actionable problem statements and success outcomes", skill: "product-discovery" },
+  "Product-Planner": { description: "Turn clarified needs into scoped requirements with acceptance-ready outcomes", skill: "product-planning" },
+  "Memory-Guardian": { description: "Manage discoverable project memory for durable decisions and recurring corrections", skill: "project-memory" },
+  "Prompt-Engineer": { description: "Expert in creating and refining prompts for AI agents and workflows", skill: "prompt-engineer" },
+  "QA-Engineer": { description: "Design, review, or improve tests, acceptance criteria, and validation evidence", skill: "qa-workflow" },
+  "Refactoring-Specialist": { description: "Improve code/document structure safely while preserving behavior", skill: "refactoring" },
+  "Release-Specialist": { description: "Prepare release readiness decisions with explicit gates and evidence", skill: "release-workflow" },
+  "SDD-Specialist": { description: "Convert approved requirements into explicit, testable specification artifacts", skill: "spec-driven-development" },
+  "Technical-Leader": { description: "Make technical decisions, review architecture, and identify trade-offs", skill: "technical-leadership" },
+  "UI-UX-Engineer": { description: "Improve usability and interface clarity without introducing unnecessary complexity", skill: "ui-ux-design" }
+};
+var COMMANDS = {
+  atlas: { description: "Decide safest next step and delegate to the appropriate workflow or agent", agent: "Atlas" },
+  run: { description: "Execute the master orchestration pipeline (Gates, SDD, Implementation, Validation, Healing)", agent: "Atlas" },
+  discover: { description: "Understand the project, gather context, and create initial documentation", agent: "Nexus" },
+  "spec-create": { description: "Create a clear specification before implementation", agent: "Nexus" },
+  "spec-review": { description: "Review a specification and validate scope, risks, criteria, and gaps", agent: "Nexus" },
+  "spec-implement": { description: "Implement an approved specification incrementally", agent: "Astra" },
+  plan: { description: "Plan a task or change, defining steps, risks, and validation", agent: "Orion" },
+  implement: { description: "Implement a small task with defined scope", agent: "Astra" },
+  validate: { description: "Run project validations and collect evidence", agent: "Sage" },
+  audit: { description: "Audit the project, identify issues, and suggest prioritized improvements", agent: "Sage" },
+  "optimize-tokens": { description: "Analyze workflow and context usage; suggest reductions without losing quality or evidence", agent: "Sage" },
+  "update-memory": { description: "Update durable project memory with relevant decisions, constraints, and reusable context", agent: "Nexus" },
+  release: { description: "Prepare delivery with commit, push, PR/merge readiness, changelog, and evidence", agent: "Orion" },
+  deploy: { description: "Publish the project to the defined environment after validation and release readiness", agent: "Orion" }
+};
+function buildManagedConfig() {
+  const agent = {};
+  for (const [name, def] of Object.entries(AGENTS)) {
+    agent[name] = {
+      mode: "primary",
+      description: def.description,
+      prompt: `{file:./.ai-workflow/opencode/agents/${name.toLowerCase()}.md}`
+    };
+  }
+  for (const [name, def] of Object.entries(SUBAGENTS)) {
+    agent[name] = {
+      mode: "subagent",
+      description: def.description,
+      prompt: `{file:./.ai-workflow/opencode/skills/${def.skill}/SKILL.md}`
+    };
+  }
+  const command = {};
+  for (const [name, def] of Object.entries(COMMANDS)) {
+    command[name] = {
+      description: def.description,
+      agent: def.agent,
+      template: `{file:./.ai-workflow/opencode/commands/${name}.md}`
+    };
+  }
+  return {
+    $schema: "https://opencode.ai/config.json",
+    default_agent: "Atlas",
+    agent,
+    skills: {
+      paths: ["./.ai-workflow/opencode/skills"]
+    },
+    command
+  };
+}
+async function mergeOpencodeConfig(cwd, { force = false, backupRoot = ".ai-workflow-backups" } = {}) {
+  const targetPath = path4.join(cwd, "opencode.jsonc");
+  const managed = buildManagedConfig();
+  if (!await exists(targetPath)) {
+    await writeFileSafe(targetPath, `${JSON.stringify(managed, null, 2)}
+`);
+    return { changed: true, reason: "created" };
+  }
+  let current;
+  try {
+    current = await readJsonc(targetPath);
+  } catch {
+    if (!force) {
+      return { changed: false, reason: "invalid-json (skipped)" };
+    }
+    await createManagedBackup(targetPath, {
+      cwd,
+      backupRoot,
+      maxPerFile: 20
+    });
+    await writeFileSafe(targetPath, `${JSON.stringify(managed, null, 2)}
+`);
+    return { changed: true, reason: "invalid-json (replaced with --force)" };
+  }
+  const { [LEGACY_MARKER]: _legacyManaged, ...currentWithoutLegacy } = current;
+  const next = {
+    ...currentWithoutLegacy,
+    $schema: current.$schema ?? managed.$schema,
+    ...managed.mcp ? {
+      mcp: {
+        ...current.mcp ?? {},
+        ...managed.mcp
+      }
+    } : {},
+    agent: {
+      ...current.agent ?? {},
+      ...managed.agent
+    },
+    command: {
+      ...current.command ?? {},
+      ...managed.command
+    }
+  };
+  const changed = JSON.stringify(current) !== JSON.stringify(next);
+  if (!changed) {
+    return { changed: false, reason: "already-up-to-date" };
+  }
+  await writeFileSafe(targetPath, `${JSON.stringify(next, null, 2)}
+`);
+  return { changed: true, reason: "merged-managed-sections" };
+}
+
+// src/core/symlink-layout.ts
+import fs3 from "fs/promises";
+import path5 from "path";
+function normalize(p) {
+  return p.split(path5.sep).join("/");
+}
+var LINKABLE_ROOTS = /* @__PURE__ */ new Set([
+  "opencode",
+  ".agents"
+]);
+var LINKABLE_FILES = /* @__PURE__ */ new Set([]);
+function buildSymlinkEntries({ templateFiles, installRoot = ".ai-workflow" }) {
+  const entries = /* @__PURE__ */ new Map();
+  for (const relativePath of Object.keys(templateFiles)) {
+    if (relativePath === "opencode.jsonc") continue;
+    const normalized = normalize(relativePath);
+    if (LINKABLE_FILES.has(normalized)) {
+      entries.set(normalized, `${installRoot}/${normalized}`);
+      continue;
+    }
+    for (const rootPath of LINKABLE_ROOTS) {
+      if (normalized === rootPath || normalized.startsWith(`${rootPath}/`)) {
+        entries.set(rootPath, `${installRoot}/${rootPath}`);
+        break;
+      }
+    }
+  }
+  return Array.from(entries.entries()).map(([linkPath, targetPath]) => ({ linkPath, targetPath }));
+}
+async function isSymlinkTo(absoluteLinkPath, absoluteTargetPath) {
+  try {
+    const stat = await fs3.lstat(absoluteLinkPath);
+    if (!stat.isSymbolicLink()) return false;
+    const currentTarget = await fs3.readlink(absoluteLinkPath);
+    const resolved = path5.resolve(path5.dirname(absoluteLinkPath), currentTarget);
+    return resolved === absoluteTargetPath;
+  } catch {
+    return false;
+  }
+}
+async function setupInternalSymlinks(cwd, installRoot = ".ai-workflow") {
+  const skillsLink = path5.join(cwd, installRoot, "opencode/skills");
+  const skillsTarget = path5.join(cwd, installRoot, ".agents/skills");
+  if (!await exists2(skillsTarget)) return;
+  try {
+    const stat = await fs3.lstat(skillsLink).catch(() => null);
+    if (stat) {
+      if (stat.isSymbolicLink()) {
+        const current = await fs3.readlink(skillsLink);
+        if (current === "../.agents/skills") return;
+        await fs3.unlink(skillsLink);
+      } else {
+        return;
+      }
+    }
+    const type = process.platform === "win32" ? "junction" : "dir";
+    await fs3.symlink("../.agents/skills", skillsLink, type);
+  } catch {
+  }
+}
+async function exists2(p) {
+  try {
+    await fs3.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/adapters/platforms/claude.ts
+import fs4 from "fs/promises";
+import path6 from "path";
+var ClaudeAdapter = class {
+  cwd;
+  constructor({ cwd }) {
+    this.cwd = cwd;
+  }
+  /**
+   * Transforms an OpenCode agent or skill into a Claude rule with completion contract.
+   */
+  async transformToRule(filePath, type = "agent") {
+    const content = await fs4.readFile(filePath, "utf8");
+    const fileName = path6.basename(filePath, ".md") === "SKILL" ? path6.basename(path6.dirname(filePath)) : path6.basename(filePath, ".md");
+    const ruleName = `${type}-${fileName.toLowerCase()}`;
+    const hardenedContent = `---
+name: ${ruleName}
+description: ${type === "agent" ? "Persona" : "Skill"} rule for ${fileName}
+---
+# ${fileName} ${type === "agent" ? "Persona" : "Skill"}
+
+${content}
+
+##  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: ruleName
+    };
+  }
+  /**
+   * Deploys agents, skills, and root CLAUDE.md.
+   */
+  async deploy(installRoot = ".ai-workflow") {
+    const rulesDir = path6.join(this.cwd, ".claude/rules");
+    await fs4.mkdir(rulesDir, { recursive: true });
+    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 agentFiles = await fs4.readdir(sourceAgentsDir).catch(() => []);
+    for (const file of agentFiles) {
+      if (!file.endsWith(".md")) continue;
+      const transformed = await this.transformToRule(path6.join(sourceAgentsDir, file), "agent");
+      await fs4.writeFile(path6.join(rulesDir, `${transformed.name}.md`), transformed.content);
+    }
+    const skillFolders = await fs4.readdir(sourceSkillsDir).catch(() => []);
+    for (const folder of skillFolders) {
+      const skillSource = path6.join(sourceSkillsDir, folder, "SKILL.md");
+      if (await this.exists(skillSource)) {
+        const transformed = await this.transformToRule(skillSource, "skill");
+        await fs4.writeFile(path6.join(rulesDir, `${transformed.name}.md`), transformed.content);
+      }
+    }
+    await this.deployRootClaudeMd(sourceCommandsDir);
+  }
+  async deployRootClaudeMd(sourceCommandsDir) {
+    const targetPath = path6.join(this.cwd, "CLAUDE.md");
+    const commandFiles = await fs4.readdir(sourceCommandsDir).catch(() => []);
+    let commandsDoc = "";
+    for (const file of commandFiles) {
+      if (!file.endsWith(".md")) continue;
+      const name = path6.basename(file, ".md");
+      commandsDoc += `- \`ai-workflow run --spec-path=...\` (Target: ${name})
+`;
+    }
+    const instructions = `# CLAUDE.md - AI Workflow Kit Governance
+
+This project 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** (./specs).
+
+##  Common Commands
+${commandsDoc}
+- \`ai-workflow doctor\`: Verify installation.
+- \`ai-workflow collect-evidence\`: Generate EVIDENCE.json.
+
+##  Rules & Personas
+Adhere to the specific rules and personas defined in \`.claude/rules/\`. 
+- Always follow the **Branch Gate** policy (never work on \`main\`).
+- Always follow the **SDD Workflow** (Spec -> Plan -> PR -> Evidence).
+
+##  Completion Contract
+Every task completion MUST follow the payload format defined in the individual rule files.
+`;
+    await fs4.writeFile(targetPath, instructions);
+  }
+  async exists(p) {
+    try {
+      await fs4.access(p);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+
+// src/adapters/platforms/codex.ts
+import fs5 from "fs/promises";
+import path7 from "path";
+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 fs5.readFile(filePath, "utf8");
+    const fileName = path7.basename(filePath, ".md");
+    const hardenedContent = `${content}
+
+##  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
+    };
+  }
+  /**
+   * Deploys agents, skills, and commands to Codex-native directories.
+   * Mapping:
+   * - Agents -> .github/agents/
+   * - Skills -> .agents/skills/
+   * - Commands -> .codex/prompts/
+   */
+  async deploy(installRoot = ".ai-workflow") {
+    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");
+    const codexAgentsDir = path7.join(this.cwd, ".github/agents");
+    await fs5.mkdir(codexAgentsDir, { recursive: true });
+    const agentFiles = await fs5.readdir(sourceAgentsDir).catch(() => []);
+    for (const file of agentFiles) {
+      if (!file.endsWith(".md")) continue;
+      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");
+    await fs5.mkdir(codexSkillsDir, { recursive: true });
+    const skillFolders = await fs5.readdir(sourceSkillsDir).catch(() => []);
+    for (const folder of skillFolders) {
+      const skillSource = path7.join(sourceSkillsDir, folder, "SKILL.md");
+      if (await this.exists(skillSource)) {
+        const targetDir = path7.join(codexSkillsDir, folder);
+        await fs5.mkdir(targetDir, { recursive: true });
+        const content = await fs5.readFile(skillSource, "utf8");
+        await fs5.writeFile(path7.join(targetDir, "SKILL.md"), content);
+      }
+    }
+    const codexPromptsDir = path7.join(this.cwd, ".codex/prompts");
+    await fs5.mkdir(codexPromptsDir, { recursive: true });
+    const commandFiles = await fs5.readdir(sourceCommandsDir).catch(() => []);
+    for (const file of commandFiles) {
+      if (!file.endsWith(".md") && !file.endsWith(".toml")) continue;
+      const targetFileName = file.endsWith(".toml") ? `${path7.basename(file, ".toml")}.md` : file;
+      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");
+    await fs5.mkdir(codexPoliciesDir, { recursive: true });
+    const sourcePoliciesDir = path7.join(this.cwd, installRoot, "opencode", "docs", "policies");
+    const policyFiles = await fs5.readdir(sourcePoliciesDir).catch(() => []);
+    for (const file of policyFiles) {
+      if (!file.endsWith(".md")) continue;
+      const policyContent = await fs5.readFile(path7.join(sourcePoliciesDir, file), "utf8");
+      await fs5.writeFile(path7.join(codexPoliciesDir, file), policyContent);
+    }
+  }
+  async exists(p) {
+    try {
+      await fs5.access(p);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+
+// src/adapters/platforms/antigravity.ts
+import fs6 from "fs/promises";
+import path8 from "path";
+import { pathToFileURL } from "url";
+var PERSONA_MAPPING = {
+  "atlas": "Atlas",
+  "orion": "Orion",
+  "sage": "Sage",
+  "nexus": "Nexus",
+  "astra": "Astra",
+  "sage-validation": "Sage",
+  "orion-release": "Orion",
+  "orion-deploy": "Orion",
+  "nexus-discovery": "Nexus",
+  "phoenix": "Phoenix"
+};
+var AntigravityAdapter = class {
+  cwd;
+  constructor({ cwd }) {
+    this.cwd = cwd;
+  }
+  /**
+   * Transforms an OpenCode agent or specialized skill file to an Antigravity Skill.
+   */
+  async transform(filePath) {
+    const content = await fs6.readFile(filePath, "utf8");
+    const fileName = path8.basename(filePath, ".md") === "SKILL" ? path8.basename(path8.dirname(filePath)) : path8.basename(filePath, ".md");
+    const persona = PERSONA_MAPPING[fileName.toLowerCase()] || "Astra";
+    if (content.trim().startsWith("---")) {
+      return { content, name: fileName };
+    }
+    const descriptionMatch = content.match(/^# .*\n\n(.*)/m);
+    const description = descriptionMatch ? descriptionMatch[1].trim() : `Specialized agent for ${fileName}.`;
+    const skillContent = `---
+name: ${fileName}
+description: ${description}
+---
+# ${persona} Persona
+
+${content}
+
+##  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: skillContent,
+      name: fileName
+    };
+  }
+  /**
+   * Deploys transformed skills and agents to their respective directories.
+   * Also orchestrates the .antigravity/ native integration.
+   */
+  async deploy(transformedItems, installRoot = ".ai-workflow") {
+    const agentsDir = path8.join(this.cwd, installRoot, "opencode/agents");
+    const skillsDir = path8.join(this.cwd, installRoot, "opencode/skills");
+    await fs6.mkdir(agentsDir, { recursive: true });
+    await fs6.mkdir(skillsDir, { recursive: true });
+    for (const item of transformedItems) {
+      const isAgent = PERSONA_MAPPING[item.name.toLowerCase()];
+      const targetDir = isAgent ? agentsDir : path8.join(skillsDir, item.name);
+      const fileName = isAgent ? `${item.name}.md` : "SKILL.md";
+      const absoluteTargetDir = isAgent ? agentsDir : targetDir;
+      await fs6.mkdir(absoluteTargetDir, { recursive: true });
+      await fs6.writeFile(path8.join(absoluteTargetDir, fileName), item.content);
+    }
+    await this.deployNativeExtensions(installRoot);
+    await this.deployInstructions();
+  }
+  /**
+   * Orchestrates the .agents/ directory with copies of .ai-workflow/ assets.
+   * Using hard copies instead of symlinks ensures native discovery across all platforms.
+   */
+  async deployNativeExtensions(installRoot = ".ai-workflow") {
+    const antigravityDir = path8.join(this.cwd, ".agents");
+    const antigravityAgents = path8.join(antigravityDir, "agents");
+    const antigravitySkills = path8.join(antigravityDir, "skills");
+    const antigravityCommands = path8.join(antigravityDir, "commands");
+    await fs6.mkdir(antigravityAgents, { recursive: true });
+    await fs6.mkdir(antigravitySkills, { recursive: true });
+    await fs6.mkdir(antigravityCommands, { recursive: true });
+    const getUrls = (targetPath) => {
+      const linuxUrl = pathToFileURL(targetPath).href;
+      const urls = [linuxUrl];
+      if (process.platform === "linux" && process.env.WSL_DISTRO_NAME) {
+        const distro = process.env.WSL_DISTRO_NAME;
+        const normalizedPath = targetPath.replaceAll("\\", "/");
+        urls.push(`file://wsl.localhost/${distro}${normalizedPath}`);
+        urls.push(`file:///wsl.localhost/${distro}${normalizedPath}`);
+      }
+      return urls.join("\n");
+    };
+    const toolNames = [
+      "send_message",
+      "find_by_name",
+      "grep_search",
+      "view_file",
+      "list_dir",
+      "read_url_content",
+      "search_web",
+      "schedule",
+      "multi_replace_file_content",
+      "replace_file_content",
+      "write_to_file",
+      "run_command",
+      "manage_task",
+      "define_subagent",
+      "invoke_subagent",
+      "manage_subagents",
+      "call_mcp_tool"
+    ];
+    const systemPromptConfig = {
+      "includeSections": [
+        "user_information",
+        "mcp_servers",
+        "skills",
+        "subagent_reminder",
+        "messaging",
+        "artifacts",
+        "user_rules"
+      ]
+    };
+    const sourceAgentsDir = path8.join(this.cwd, installRoot, "opencode/agents");
+    const agentFiles = await fs6.readdir(sourceAgentsDir).catch(() => []);
+    const AGENTS_INFO = {
+      "atlas": { name: "Atlas", description: "Router and workflow coordinator for AI Workflow Kit" },
+      "nexus": { name: "Nexus", description: "Discovery, requirement, scope, and specification owner" },
+      "orion": { name: "Orion", description: "Planning, PR sequencing, release, and deployment strategy owner" },
+      "astra": { name: "Astra", description: "Implementation owner for incremental, scoped changes" },
+      "sage": { name: "Sage", description: "Audit, validation, evidence, and quality gate owner" },
+      "phoenix": { name: "Phoenix", description: "Remediation and regression recovery owner" }
+    };
+    for (const file of agentFiles) {
+      if (!file.endsWith(".md")) continue;
+      const lowercaseName = path8.basename(file, ".md").toLowerCase();
+      const info = AGENTS_INFO[lowercaseName];
+      if (!info) continue;
+      const agentFolder = path8.join(antigravityAgents, lowercaseName);
+      await fs6.mkdir(agentFolder, { recursive: true });
+      const content = await fs6.readFile(path8.join(sourceAgentsDir, file), "utf8");
+      const mdTarget = path8.join(agentFolder, `${lowercaseName}.md`);
+      await fs6.writeFile(mdTarget, content);
+      const agentJson = {
+        name: lowercaseName,
+        description: info.description,
+        hidden: false,
+        config: {
+          customAgent: {
+            systemPromptSections: [
+              {
+                title: "Agent System Instructions",
+                content: `You are ${info.name}, the ${lowercaseName === "astra" ? "implementation" : lowercaseName} owner.
+
+Follow the contract instructions in:
+${getUrls(mdTarget)}`
+              }
+            ],
+            toolNames,
+            systemPromptConfig
+          }
+        }
+      };
+      await fs6.writeFile(path8.join(agentFolder, "agent.json"), JSON.stringify(agentJson, null, 2));
+    }
+    const SUBAGENTS_INFO = {
+      "Architecture-Specialist": { description: "Select the simplest architecture that safely satisfies current requirements", skill: "architecture" },
+      "Backend-Engineer": { description: "Support safe PHP/Node/Python backend changes for APIs and persistence", skill: "backend-development" },
+      "Deployment-Specialist": { description: "Plan, review, or validate deployment, release, and production-readiness", skill: "deployment" },
+      "Design-Specialist": { description: "Apply practical design principles to keep solutions simple and maintainable", skill: "design-principles" },
+      "Docs-Engineer": { description: "Write or improve project documentation, READMEs, guides, and prompts", skill: "documentation" },
+      "Frontend-Engineer": { description: "Implement or review frontend changes involving UI, state, routing, and accessibility", skill: "frontend-development" },
+      "Full-Stack-Engineer": { description: "Coordinate frontend and backend changes as one coherent, testable increment", skill: "full-stack-development" },
+      "Token-Economist": { description: "Reduce context size while preserving information required for safe execution", skill: "optimize-tokens" },
+      "PR-Manager": { description: "Plan, implement, review, or validate small pull requests while preserving scope", skill: "pr-workflow" },
+      "Discovery-Analyst": { description: "Clarify ambiguous requests into actionable problem statements and success outcomes", skill: "product-discovery" },
+      "Product-Planner": { description: "Turn clarified needs into scoped requirements with acceptance-ready outcomes", skill: "product-planning" },
+      "Memory-Guardian": { description: "Manage discoverable project memory for durable decisions and recurring corrections", skill: "project-memory" },
+      "Prompt-Engineer": { description: "Expert in creating and refining prompts for AI agents and workflows", skill: "prompt-engineer" },
+      "QA-Engineer": { description: "Design, review, or improve tests, acceptance criteria, and validation evidence", skill: "qa-workflow" },
+      "Refactoring-Specialist": { description: "Improve code/document structure safely while preserving behavior", skill: "refactoring" },
+      "Release-Specialist": { description: "Prepare release readiness decisions with explicit gates and evidence", skill: "release-workflow" },
+      "SDD-Specialist": { description: "Convert approved requirements into explicit, testable specification artifacts", skill: "spec-driven-development" },
+      "Technical-Leader": { description: "Make technical decisions, review architecture, and identify trade-offs", skill: "technical-leadership" },
+      "UI-UX-Engineer": { description: "Improve usability and interface clarity without introducing unnecessary complexity", skill: "ui-ux-design" }
+    };
+    for (const [name, subInfo] of Object.entries(SUBAGENTS_INFO)) {
+      const lowercaseSubagentName = name.toLowerCase();
+      const subagentFolder = path8.join(antigravityAgents, lowercaseSubagentName);
+      await fs6.mkdir(subagentFolder, { recursive: true });
+      const skillPath = path8.join(antigravitySkills, subInfo.skill, "SKILL.md");
+      const subagentJson = {
+        name: lowercaseSubagentName,
+        description: subInfo.description,
+        hidden: false,
+        config: {
+          customAgent: {
+            systemPromptSections: [
+              {
+                title: "Agent System Instructions",
+                content: `You are ${name}.
+
+Follow the contract instructions in:
+${getUrls(skillPath)}`
+              }
+            ],
+            toolNames,
+            systemPromptConfig
+          }
+        }
+      };
+      await fs6.writeFile(path8.join(subagentFolder, "agent.json"), JSON.stringify(subagentJson, null, 2));
+    }
+    const sourceSkillsDir = path8.join(this.cwd, installRoot, "opencode/skills");
+    const skillFolders = await fs6.readdir(sourceSkillsDir).catch(() => []);
+    for (const folder of skillFolders) {
+      const skillSource = path8.join(sourceSkillsDir, folder, "SKILL.md");
+      if (await this.exists(skillSource)) {
+        await fs6.mkdir(path8.join(antigravitySkills, folder), { recursive: true });
+        const content = await fs6.readFile(skillSource, "utf8");
+        await fs6.writeFile(path8.join(antigravitySkills, folder, "SKILL.md"), content);
+      }
+    }
+    const sourceCommandsDir = path8.join(this.cwd, installRoot, "opencode/commands");
+    if (await this.exists(sourceCommandsDir)) {
+      const commandFiles = await fs6.readdir(sourceCommandsDir).catch(() => []);
+      for (const file of commandFiles) {
+        if (!file.endsWith(".md") && !file.endsWith(".toml")) continue;
+        const content = await fs6.readFile(path8.join(sourceCommandsDir, file), "utf8");
+        await fs6.writeFile(path8.join(antigravityCommands, file), content);
+      }
+    }
+    const sourcePoliciesDir = path8.join(this.cwd, installRoot, "opencode", "docs", "policies");
+    const antigravityPolicies = path8.join(antigravityDir, "docs", "policies");
+    if (await this.exists(sourcePoliciesDir)) {
+      await fs6.mkdir(antigravityPolicies, { recursive: true });
+      const policyFiles = await fs6.readdir(sourcePoliciesDir).catch(() => []);
+      for (const file of policyFiles) {
+        if (!file.endsWith(".md")) continue;
+        const content = await fs6.readFile(path8.join(sourcePoliciesDir, file), "utf8");
+        await fs6.writeFile(path8.join(antigravityPolicies, file), content);
+      }
+    }
+    const settingsPath = path8.join(antigravityDir, "settings.json");
+    if (!await this.exists(settingsPath)) {
+      const settings = {
+        model: { name: "auto" },
+        ui: { theme: "Ayu" }
+      };
+      await fs6.writeFile(settingsPath, JSON.stringify(settings, null, 2));
+    }
+  }
+  async exists(p) {
+    try {
+      await fs6.access(p);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Deploys the main ANTIGRAVITY.md and .antigravityignore instructions to the project root.
+   */
+  async deployInstructions() {
+    const targetPath = path8.join(this.cwd, "ANTIGRAVITY.md");
+    const ignorePath = path8.join(this.cwd, ".antigravityignore");
+    try {
+      await fs6.access(targetPath);
+    } catch {
+      const instructions = `# AI Workflow Kit - Engineering Governance
+
+## Mandate: Atlas Authority Protocol
+All architectural changes must align with the specifications issued by the **Specification Authority** (./specs).
+
+## Ternary Architecture
+- **Root:** Orchestration and config.
+- **.ai-workflow/:** Implementation (The Muscle).
+- **./specs:** Specifications (The Brain).
+
+## Branch Gates
+- **main Branch:** READ-ONLY.
+- **Validation:** Merges require successful observed validation; full/release workflows may persist EVIDENCE.json.
+
+## Primary Agents
+- **Atlas (Orchestrator)**
+- **Orion (Strategist)**
+- **Sage (Auditor)**
+- **Nexus (Spec Architect)**
+- **Astra (Developer)**
+- **Phoenix (Healer)**
+
+## Operational Preferences
+- Use \`token-economy\` and \`minimal-context\` skills.
+- **Native Discovery**: This project uses workspace-specific extensions in \`.agents/\`.
+- **Workflow Entry**: Use \`/atlas\` to begin any task.
+`;
+      await fs6.writeFile(targetPath, instructions);
+    }
+    try {
+      await fs6.access(ignorePath);
+    } catch {
+      const ignoreContent = `.ai-workflow/
+.ai-workflow-backups/
+node_modules/
+.git/
+EVIDENCE.json
+*.tgz
+*.zip
+*.tar
+.agents/tmp/
+.agents/history/
+`;
+      await fs6.writeFile(ignorePath, ignoreContent);
+    }
+  }
+};
+
+// src/cli/commands/init.ts
+function summarize(actions) {
+  const createCount = actions.filter((a) => a.type === "create").length;
+  const conflictCount = actions.filter((a) => a.type === "conflict").length;
+  return { createCount, conflictCount };
+}
+function printPlan(actions) {
+  for (const action of actions) {
+    console.log(`- ${action.type.padEnd(8)} ${action.relativePath}`);
+  }
+}
+function toIgnoreEntries(linkPath) {
+  if (linkPath === "README.workflow.md") {
+    return [linkPath];
+  }
+  const normalized = linkPath.endsWith("/") ? linkPath.slice(0, -1) : linkPath;
+  return [normalized, `${normalized}/`];
+}
+function buildGitignoreBlock(entries) {
+  const unique = Array.from(new Set(entries));
+  const sorted = unique.sort((a, b) => a.localeCompare(b));
+  return [
+    "# BEGIN AI WORKFLOW KIT",
+    "# AI Workflow Kit generated files",
+    ...sorted,
+    "# END AI WORKFLOW KIT"
+  ].join("\n");
+}
+async function upsertGitignoreBlock(cwd, entries) {
+  const gitignorePath = path9.join(cwd, ".gitignore");
+  const block = buildGitignoreBlock(entries);
+  const beginMarker = "# BEGIN AI WORKFLOW KIT";
+  const endMarker = "# END AI WORKFLOW KIT";
+  const hasGitignore = await exists(gitignorePath);
+  if (!hasGitignore) {
+    await writeFileSafe(gitignorePath, `${block}
+`);
+    return "created";
+  }
+  const current = await fs7.readFile(gitignorePath, "utf8");
+  const beginIndex = current.indexOf(beginMarker);
+  const endIndex = current.indexOf(endMarker);
+  if (beginIndex >= 0 && endIndex > beginIndex) {
+    const before = current.slice(0, beginIndex).replace(/\n?# AI Workflow Kit generated files\n?$/, "\n").replace(/[ \t]+$/gm, "").replace(/\n*$/, "\n");
+    const afterStart = endIndex + endMarker.length;
+    const after = current.slice(afterStart).replace(/^\n*/, "\n");
+    const next2 = `${before}${block}${after}`;
+    if (next2 !== current) {
+      await writeFileSafe(gitignorePath, next2);
+      return "updated";
+    }
+    return "unchanged";
+  }
+  const separator = current.endsWith("\n") ? "\n" : "\n\n";
+  const next = `${current}${separator}${block}
+`;
+  await writeFileSafe(gitignorePath, next);
+  return "updated";
+}
+async function injectScripts(cwd) {
+  const pkgPath = path9.join(cwd, "package.json");
+  if (!await exists(pkgPath)) return false;
+  try {
+    const pkg = await readJson(pkgPath);
+    if (!pkg.scripts) pkg.scripts = {};
+    if (!pkg.scripts.validate) {
+      pkg.scripts.validate = "ai-workflow collect-evidence";
+      await writeFileSafe(pkgPath, `${JSON.stringify(pkg, null, 2)}
+`);
+      return true;
+    }
+  } catch {
+  }
+  return false;
+}
+async function verifySelfExecutionGuard(cwd, devMode) {
+  if (!devMode) {
+    try {
+      const pkgPath = path9.join(cwd, "package.json");
+      if (await exists(pkgPath)) {
+        const pkg = await readJson(pkgPath);
+        if (pkg.name === "@williambeto/ai-workflow") {
+          console.error("\nFATAL: Cannot run 'ai-workflow init' inside its own development repository.");
+          console.error("This would corrupt the development environment. Aborting.");
+          console.error("Use the --dev-mode flag if you are developing the kit itself and need to test the init command.\n");
+          process.exit(1);
+        }
+      }
+    } catch {
+    }
+  }
+}
+function resolveProfile(profile) {
+  const selectedProfile = profile || "standard";
+  if (!isValidProfile(selectedProfile)) {
+    console.error(`Invalid profile: "${selectedProfile}". Valid profiles: standard, full`);
+    process.exit(1);
+  }
+  return selectedProfile;
+}
+async function writeInstallFiles(cwd, actions, selectedProfile, force, noOverwrite, backupRoot = ".ai-workflow-backups") {
+  const skipped = [];
+  const backups = [];
+  for (const action of actions) {
+    if (action.type === "conflict" && (noOverwrite || !force)) {
+      skipped.push(action.relativePath);
+      continue;
+    }
+    if (action.type === "conflict" && force) {
+      const backupPath = await createManagedBackup(action.absolutePath, {
+        cwd,
+        backupRoot,
+        maxPerFile: 20
+      });
+      backups.push(backupPath);
+    }
+    const content = action.relativePath === ".ai-workflow/config.json" ? `${JSON.stringify(buildAiWorkflowConfig({ profile: selectedProfile }), null, 2)}
+` : action.content;
+    await writeFileSafe(action.absolutePath, content || "");
+  }
+  return { skipped, backups };
+}
+async function writeSymlinks(cwd, linkEntries, force, backupRoot = ".ai-workflow-backups") {
+  const linkBackups = [];
+  const linkCreated = [];
+  for (const { linkPath, targetPath } of linkEntries) {
+    const absoluteLinkPath = path9.join(cwd, linkPath);
+    const absoluteTargetPath = path9.join(cwd, targetPath);
+    if (!await exists(absoluteTargetPath)) {
+      throw new Error(`missing link target: ${targetPath}`);
+    }
+    if (await isSymlinkTo(absoluteLinkPath, absoluteTargetPath)) {
+      continue;
+    }
+    if (await exists(absoluteLinkPath)) {
+      if (!force) {
+        throw new Error(
+          `cannot create symlink '${linkPath}' because path already exists. Re-run with --force to backup and replace. If symlink creation fails, see troubleshooting in docs/npm-consumer-quickstart.md.`
+        );
+      }
+      const backupPath = await createManagedPathBackup(absoluteLinkPath, {
+        cwd,
+        backupRoot,
+        maxPerFile: 20
+      });
+      linkBackups.push(backupPath);
+      await fs7.rm(absoluteLinkPath, { recursive: true, force: true });
+    }
+    const stat = await fs7.lstat(absoluteTargetPath);
+    const type = process.platform === "win32" ? stat.isDirectory() ? "junction" : "file" : stat.isDirectory() ? "dir" : "file";
+    const linkTarget = process.platform === "win32" ? absoluteTargetPath : path9.relative(path9.dirname(absoluteLinkPath), absoluteTargetPath);
+    try {
+      await fs7.mkdir(path9.dirname(absoluteLinkPath), { recursive: true });
+      await fs7.symlink(linkTarget, absoluteLinkPath, type);
+    } catch (error) {
+      throw new Error(
+        `failed to create symlink '${linkPath}' -> '${targetPath}' (${error.message}). For Windows, enable Developer Mode or run terminal as Administrator. For Linux/macOS, verify write permissions in project root.`
+      );
+    }
+    linkCreated.push(linkPath);
+  }
+  return { linkBackups, linkCreated };
+}
+async function executePlatformMigrations(cwd, installRoot, platforms, claude, codex, antigravity) {
+  if (platforms.length === 0) return;
+  console.log("ai-workflow: migrating to native platforms...");
+  const agentsDir = path9.join(cwd, installRoot, "opencode/agents");
+  const skillsDir = path9.join(cwd, installRoot, "opencode/skills");
+  const agentFiles = (await fs7.readdir(agentsDir).catch(() => [])).filter((f) => f.endsWith(".md")).map((f) => path9.join(agentsDir, f));
+  if (claude) {
+    const adapter = new ClaudeAdapter({ cwd });
+    await adapter.deploy(installRoot);
+    console.log("- claude: deployed AI Workflow Kit agents to CLAUDE.md and .claude/rules/ (native discovery enabled)");
+  }
+  if (codex) {
+    const adapter = new CodexAdapter({ cwd });
+    await adapter.deploy(installRoot);
+    console.log("- codex: deployed AI Workflow Kit agents to .agents/, .codex/, and .github/ (native discovery enabled)");
+  }
+  if (antigravity) {
+    const adapter = new AntigravityAdapter({ cwd });
+    const skillFolders = await fs7.readdir(skillsDir).catch(() => []);
+    const skillFiles = [];
+    for (const folder of skillFolders) {
+      const skillPath = path9.join(skillsDir, folder, "SKILL.md");
+      if (await exists(skillPath)) {
+        skillFiles.push(skillPath);
+      }
+    }
+    const allFiles = [...agentFiles, ...skillFiles];
+    const transformed = await Promise.all(allFiles.map((f) => adapter.transform(f)));
+    await adapter.deploy(transformed, installRoot);
+    console.log(`- antigravity: deployed AI Workflow Kit agents to .agents/ (native discovery enabled)`);
+  }
+}
+function printInstallationSummary({
+  selectedProfile,
+  opencodeResult,
+  gitignoreResult,
+  scriptInjected,
+  linkCreated,
+  backups,
+  linkBackups,
+  skipped,
+  noInstall
+}) {
+  console.log("Installation complete.");
+  console.log(`- profile: ${selectedProfile}`);
+  console.log(`- opencode.jsonc: ${opencodeResult.reason}`);
+  console.log(`- .gitignore: ${gitignoreResult}`);
+  console.log(`- scripts: ${scriptInjected ? "injected 'validate'" : "already-up-to-date"}`);
+  console.log(`- symlink layout: ${linkCreated.length > 0 ? `created ${linkCreated.length}` : "already-up-to-date"}`);
+  if (backups.length > 0) {
+    console.log(`- backups created: ${backups.length}`);
+    for (const filePath of backups) {
+      console.log(`  ${filePath}`);
+    }
+  }
+  if (linkBackups.length > 0) {
+    console.log(`- symlink backups created: ${linkBackups.length}`);
+    for (const filePath of linkBackups) {
+      console.log(`  ${filePath}`);
+    }
+  }
+  if (skipped.length > 0) {
+    console.log(`- conflicts skipped: ${skipped.length}`);
+    for (const relativePath of skipped) {
+      console.log(`  ${relativePath}`);
+    }
+  }
+  console.log(`- dependency install: ${noInstall ? "skipped (--no-install)" : "not managed in this step"}`);
+  console.log("Next steps:");
+  console.log("  npx @williambeto/ai-workflow doctor");
+}
+async function runInit({
+  cwd,
+  yes,
+  force,
+  dryRun,
+  noInstall,
+  noOverwrite,
+  claude,
+  codex,
+  antigravity,
+  "dev-mode": devMode,
+  profile
+}) {
+  await verifySelfExecutionGuard(cwd, devMode);
+  const selectedProfile = resolveProfile(profile);
+  const installRoot = ".ai-workflow";
+  const backupRoot = ".ai-workflow-backups";
+  const platforms = [];
+  if (claude) platforms.push("claude");
+  if (codex) platforms.push("codex");
+  if (antigravity) platforms.push("antigravity");
+  console.log(`ai-workflow: initializing in ${cwd}`);
+  console.log(`Profile: ${selectedProfile}`);
+  if (platforms.length > 0) {
+    console.log(`Platforms: ${platforms.join(", ")}`);
+  }
+  const actions = await createInstallPlan({ cwd, exists, profile: selectedProfile });
+  const linkEntries = buildSymlinkEntries({ templateFiles: getTemplateFiles(selectedProfile), installRoot });
+  const { createCount, conflictCount } = summarize(actions);
+  console.log(`Plan: ${createCount} create, ${conflictCount} conflict`);
+  printPlan(actions);
+  if (!yes && conflictCount > 0 && !force && !noOverwrite) {
+    throw new Error(
+      "conflicts detected. Re-run with --force to replace managed files or resolve conflicts manually"
+    );
+  }
+  if (dryRun) {
+    console.log("Dry-run enabled. No files were written.");
+    if (platforms.length > 0) {
+      console.log("ai-workflow: (dry-run) platform migration would be executed after file writing.");
+    }
+    return;
+  }
+  const { skipped, backups } = await writeInstallFiles(cwd, actions, selectedProfile, force, noOverwrite, backupRoot);
+  const { linkBackups, linkCreated } = await writeSymlinks(cwd, linkEntries, force, backupRoot);
+  await setupInternalSymlinks(cwd, installRoot);
+  const opencodeResult = await mergeOpencodeConfig(cwd, { force, backupRoot });
+  const generatedIgnoreEntries = [
+    "node_modules/",
+    ".ai-workflow/",
+    ".ai-workflow-backups/",
+    "opencode.jsonc.backup.*",
+    "EVIDENCE.json",
+    "*.tgz",
+    ...linkEntries.flatMap((entry) => toIgnoreEntries(entry.linkPath))
+  ];
+  if (codex) {
+    generatedIgnoreEntries.push(".agents/", ".codex/");
+  }
+  if (claude) {
+    generatedIgnoreEntries.push(".claude/");
+  }
+  if (antigravity) {
+    generatedIgnoreEntries.push(".agents/");
+  }
+  const gitignoreResult = await upsertGitignoreBlock(cwd, generatedIgnoreEntries);
+  const scriptInjected = await injectScripts(cwd);
+  await executePlatformMigrations(cwd, installRoot, platforms, claude, codex, antigravity);
+  printInstallationSummary({
+    selectedProfile,
+    opencodeResult,
+    gitignoreResult,
+    scriptInjected,
+    linkCreated,
+    backups,
+    linkBackups,
+    skipped,
+    noInstall
+  });
+}
+
+// src/cli/commands/doctor.ts
+import fs8 from "fs/promises";
+import path10 from "path";
+var REQUIRED_FILES = [
+  ".ai-workflow",
+  "opencode/README.md"
+];
+async function isSymlink(filePath) {
+  try {
+    const stat = await fs8.lstat(filePath);
+    return stat.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+async function runDoctor({ cwd }) {
+  let hasFailure = false;
+  let hasWarning = false;
+  let managedBlocks = [];
+  console.log("Doctor report:");
+  const adapter = new OpenCodeAdapter({ cwd });
+  const inspection = await adapter.inspect();
+  if (inspection.available) {
+    console.log("PASS opencode CLI is available");
+    const supportedStr = Object.entries(inspection.supports).filter(([_, v]) => v).map(([k, _]) => k).join(", ");
+    console.log(`PASS opencode capabilities detected: ${supportedStr || "none"}`);
+    if (inspection.supports.agent) {
+      console.log("PASS opencode --agent selection is supported");
+    } else {
+      hasWarning = true;
+      console.log("WARN opencode --agent selection is not supported; prompt fallback is available");
+    }
+  } else {
+    hasFailure = true;
+    console.log("FAIL opencode CLI is not installed or not available in PATH");
+  }
+  for (const relativePath of REQUIRED_FILES) {
+    const ok = await exists(path10.join(cwd, relativePath));
+    if (ok) {
+      console.log(`PASS ${relativePath}`);
+    } else {
+      hasFailure = true;
+      console.log(`FAIL ${relativePath} missing`);
+    }
+  }
+  const configPathV2 = path10.join(cwd, ".ai-workflow/config.json");
+  const configPathLegacy = path10.join(cwd, ".ai-workflow.json");
+  let configPath = null;
+  if (await exists(configPathV2)) {
+    configPath = configPathV2;
+  } 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 (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}`);
+          }
+        }
+      }
+    } catch {
+      hasFailure = true;
+      console.log(`FAIL ${path10.basename(configPath)} is not valid JSON`);
+    }
+  }
+  const opencodePath = path10.join(cwd, "opencode.jsonc");
+  if (!await exists(opencodePath)) {
+    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");
+      } 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(", ")}`);
+        }
+      }
+      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");
+      } 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(", ")}`);
+        }
+      }
+    } catch {
+      hasFailure = true;
+      console.log("FAIL opencode.jsonc is not valid JSONC");
+    }
+  }
+  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;
+        console.log("WARN package.json has no validate script");
+      }
+    } catch {
+      hasFailure = true;
+      console.log("FAIL package.json is not valid JSON");
+    }
+  }
+  const finalStatus = hasFailure ? "FAIL" : hasWarning ? "PASS_WITH_NOTES" : "PASS";
+  console.log(`Final status: ${finalStatus}`);
+  if (hasFailure) {
+    process.exitCode = 1;
+  }
+}
+
+// src/core/validation/canonical-finalization.ts
+var DELIVERY_SUMMARY_FIELDS = Object.freeze([
+  "Status",
+  "Branch",
+  "Changes",
+  "Validation",
+  "Known limitations"
+]);
+function buildDeliverySummary({ evidence }) {
+  const commands = (evidence?.commands || []).map((item) => `${item.command || item.name}: ${item.status}`).join("; ") || "No validation commands recorded";
+  return {
+    Status: evidence?.status || "BLOCKED",
+    Branch: evidence?.branch || "unknown",
+    Changes: (evidence?.changedFiles || []).join(", ") || "No changed files recorded",
+    Validation: commands,
+    "Known limitations": (evidence?.limitations || []).join("; ") || "None recorded"
+  };
+}
+function formatDeliverySummary(summary) {
+  return DELIVERY_SUMMARY_FIELDS.map((field) => `${field}: ${summary?.[field] || "NOT_RECORDED"}`).join("\n");
+}
+
+// src/cli/commands/collect-evidence.ts
+function resolvePoliciesFromLegacyMode(mode, evidencePolicy) {
+  const activePolicy = evidencePolicy || (mode === "full" ? "required" : "optional");
+  let risk = "medium";
+  if (mode === "full") {
+    risk = "high";
+  } else if (mode === "quick") {
+    risk = activePolicy === "required" ? "medium" : "low";
+  } else if (activePolicy === "required") {
+    risk = "high";
+  }
+  return { evidencePolicy: activePolicy, riskLevel: risk };
+}
+async function runCollectEvidence({
+  cwd,
+  exitOnError = true,
+  taskSlug = null,
+  mode = null,
+  evidencePolicy = null,
+  dryRun = false,
+  profile = "generic",
+  branchRecovery = "NOT_RECORDED",
+  userRequest = null,
+  explicitApprovals = [],
+  visualDist = null,
+  port = null
+}) {
+  const policies = resolvePoliciesFromLegacyMode(mode, evidencePolicy);
+  const qualityGuard = new QualityGuard({ cwd, taskSlug, evidencePolicy: policies.evidencePolicy, riskLevel: policies.riskLevel });
+  const planner = new ValidationPlanner({ cwd, qualityGuard });
+  const tasks = await planner.plan(profile);
+  const persist = !dryRun && policies.evidencePolicy === "required";
+  const collector = new EvidenceCollector({
+    cwd,
+    timeout: 6e4,
+    taskSlug,
+    evidencePolicy: policies.evidencePolicy,
+    profile,
+    branchRecovery,
+    userRequest,
+    explicitApprovals,
+    visualDist,
+    port: port || 8080
+  });
+  const evidence = await collector.collect(tasks, { writeArtifact: persist });
+  const summary = buildDeliverySummary({ evidence });
+  console.log("\n--- Delivery Summary ---");
+  console.log(formatDeliverySummary(summary));
+  console.log(persist ? "\nArtifact: EVIDENCE.json" : "\nArtifact: NOT_REQUIRED for optional evidence policy");
+  console.log(`Commands processed: ${evidence.commands.length}
+`);
+  if (evidence.status === "BLOCKED" && exitOnError) process.exit(1);
+  return evidence;
+}
+
+// src/core/healing/cli-remediation-executor.ts
+import { spawnSync, execSync as execSync2 } from "child_process";
+import fs9 from "fs/promises";
+import path11 from "path";
+async function readScripts(cwd) {
+  try {
+    const pkg = JSON.parse(await fs9.readFile(path11.join(cwd, "package.json"), "utf8"));
+    return pkg.scripts || {};
+  } catch {
+    return {};
+  }
+}
+function getChangedFiles(cwd) {
+  try {
+    const output = execSync2("git status --short", { cwd, encoding: "utf8" });
+    return output.split("\n").filter(Boolean).map((line) => line.slice(3).trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+function resolveRetryScripts(affectedChecks, scripts) {
+  const retry = /* @__PURE__ */ new Set();
+  for (const check of affectedChecks) {
+    if (check === "evidence" || check === "result") {
+      if (scripts.test) retry.add("test");
+      if (scripts.lint) retry.add("lint");
+      if (scripts.build) retry.add("build");
+      if (scripts.typecheck) retry.add("typecheck");
+    }
+    if (check.includes("test")) retry.add("test");
+    if (check.includes("lint")) retry.add("lint");
+    if (check.includes("build")) retry.add("build");
+    if (check.includes("typecheck")) retry.add("typecheck");
+  }
+  return [...retry].filter((name) => !!scripts[name]);
+}
+function createCliRemediationExecutor(cwd) {
+  return async function remediationExecutor({
+    attempt,
+    maxAttempts,
+    mode,
+    affectedChecks,
+    requestPath
+  }) {
+    console.log(`
+[HEALER] Attempt ${attempt}/${maxAttempts} \u2014 mode: ${mode}`);
+    console.log(`[HEALER] Affected: ${affectedChecks.join(", ")}`);
+    const scripts = await readScripts(cwd);
+    const filesBefore = getChangedFiles(cwd);
+    const toRetry = resolveRetryScripts(affectedChecks, scripts);
+    if (toRetry.length === 0) {
+      console.log("[HEALER] No retryable scripts found for the affected checks.");
+      console.log(`[HEALER] Review ${requestPath} for details.`);
+      return {
+        applied: false,
+        reason: `No npm scripts available to address: ${affectedChecks.join(", ")}. Manual remediation required.`
+      };
+    }
+    console.log(`[HEALER] Re-running: ${toRetry.map((s) => `npm run ${s}`).join(", ")}`);
+    const results = [];
+    let anyPassed = false;
+    for (const scriptName of toRetry) {
+      process.stdout.write(`  \u2192 npm run ${scriptName} ... `);
+      const isWin32 = process.platform === "win32";
+      const cmd = isWin32 ? "npm.cmd" : "npm";
+      const result = spawnSync(cmd, ["run", scriptName], {
+        cwd,
+        shell: false,
+        encoding: "utf8",
+        timeout: 12e4
+      });
+      const passed = result.status === 0;
+      if (passed) anyPassed = true;
+      console.log(passed ? "PASS" : "FAIL");
+      results.push({ script: scriptName, passed, exitCode: result.status });
+    }
+    const filesAfter = getChangedFiles(cwd);
+    const changedFiles = filesAfter.filter((f) => !filesBefore.includes(f));
+    if (!anyPassed && changedFiles.length === 0) {
+      console.log("[HEALER] No scripts passed and no files changed \u2014 remediation had no effect.");
+      return {
+        applied: false,
+        reason: `Re-ran ${toRetry.join(", ")} \u2014 all failed. Structural fix required by the implementing agent.`
+      };
+    }
+    console.log(`[HEALER] Applied: ${results.filter((r) => r.passed).map((r) => r.script).join(", ") || "none passed"}`);
+    if (changedFiles.length) console.log(`[HEALER] Changed files: ${changedFiles.join(", ")}`);
+    return {
+      applied: true,
+      changedFiles,
+      evidenceAdded: anyPassed ? ["validation-output"] : []
+    };
+  };
+}
+
+// src/cli/commands/run.ts
+import path12 from "path";
+import fs10 from "fs/promises";
+function normalizeTaskSlugFromSpec(specPath) {
+  const normalized = String(specPath).replaceAll("\\", "/");
+  const marker = "/docs/workflows/";
+  const index = normalized.includes(marker) ? normalized.indexOf(marker) + marker.length : normalized.startsWith("docs/workflows/") ? "docs/workflows/".length : -1;
+  if (index >= 0) {
+    const slug = normalized.slice(index).split("/")[0];
+    if (slug) return slug;
+  }
+  return path12.basename(specPath, path12.extname(specPath));
+}
+function combineValidation(evidence, quality) {
+  const statuses = [evidence.internalStatus, quality.overallStatus];
+  let overallStatus = "PASS";
+  if (statuses.includes("BLOCKED")) overallStatus = "BLOCKED";
+  else if (statuses.includes("FAIL")) overallStatus = "FAIL";
+  else if (statuses.includes("FAIL_DELEGATION_GATE")) overallStatus = "FAIL_DELEGATION_GATE";
+  else if (statuses.includes("FAIL_QUALITY_GATE")) overallStatus = "FAIL_QUALITY_GATE";
+  else if (statuses.includes("PASS_WITH_NOTES")) overallStatus = "PASS_WITH_NOTES";
+  return { overallStatus, evidence, quality };
+}
+async function runMasterOrchestrator({ cwd, specPath, override, remediationExecutor = null }) {
+  console.log("\n[AI WORKFLOW] Starting evidence-backed orchestration...\n");
+  const branchGate = new BranchGate({ memoryDir: path12.join(cwd, ".ai-workflow"), cwd });
+  const taskSlug = specPath ? normalizeTaskSlugFromSpec(specPath) : "implementation";
+  const gateResult = branchGate.check(override, { taskSlug });
+  if (gateResult.blocked) throw new Error(`[GATE BLOCKED] ${gateResult.reason}`);
+  console.log(`[PASS] Branch Gate: ${gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : `${gateResult.branch} is authorized`}.`);
+  if (!specPath) throw new Error("[SDD BLOCKED] Missing --spec-path. An approved specification is required.");
+  const validator = new SpecValidator();
+  const absoluteSpecPath = path12.isAbsolute(specPath) ? specPath : path12.join(cwd, specPath);
+  const validation = await validator.validate(absoluteSpecPath);
+  if (!validation.valid) throw new Error(`[SDD BLOCKED] Specification is not ready: ${validation.reason}`);
+  const specTier = validation.tier || "standard";
+  const riskLevel = specTier === "deep" ? "high" : specTier === "tiny" ? "low" : "medium";
+  const evidencePolicy = specTier === "deep" ? "required" : "optional";
+  const remediationLimit = specTier === "deep" ? 3 : specTier === "tiny" ? 1 : 2;
+  const specContent = await fs10.readFile(absoluteSpecPath, "utf8");
+  const workflowProfile = resolveWorkflowProfile({ request: specContent });
+  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 validateWorkflow = async () => {
+    const evidence = await runCollectEvidence({
+      cwd,
+      exitOnError: false,
+      taskSlug,
+      evidencePolicy,
+      profile: workflowProfile,
+      branchRecovery: gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : "NOT_REQUIRED"
+    });
+    const quality = await new QualityGuard({ cwd, taskSlug, evidencePolicy, riskLevel }).verify();
+    return combineValidation(evidence, quality);
+  };
+  let result = await validateWorkflow();
+  if (isRecoverableGateFailure(result.overallStatus)) {
+    console.log(`
+[REMEDIATION REQUIRED] ${result.overallStatus}. Starting bounded remediation (limit: ${remediationLimit}).`);
+    const executor = typeof remediationExecutor === "function" ? remediationExecutor : createCliRemediationExecutor(cwd);
+    const healer = new HealerEngine({ cwd, remediationLimit, taskSlug });
+    result = await healer.run({ initialResult: result, validate: validateWorkflow, remediate: executor });
+  }
+  if (isTerminalFailure(result.overallStatus)) {
+    throw new Error(`[WORKFLOW BLOCKED] ${result.overallStatus}: ${result.reason || "Validation could not be resolved safely."}`);
+  }
+  if (isRecoverableGateFailure(result.overallStatus)) {
+    throw new Error(`[WORKFLOW BLOCKED] Unresolved gate status after remediation: ${result.overallStatus}`);
+  }
+  console.log("\n--- Final Handoff ---");
+  const handoffEngine = new HandoffEngine({ cwd });
+  const handoffPath = await handoffEngine.generate({
+    taskId: path12.basename(specPath, ".md"),
+    status: result.overallStatus,
+    specPaths: [specPath],
+    evidence: result.evidence,
+    nextActions: `Profile ${workflowProfile}. Observed validation completed. Ready for review or explicitly approved release actions.`
+  });
+  console.log(`
+[AI WORKFLOW COMPLETE] ${result.overallStatus}`);
+  if (result.remediation?.attempts) console.log(`Remediation attempts: ${result.remediation.attempts}`);
+  console.log(`Handoff Packet: ${path12.relative(cwd, handoffPath)}
+`);
+  return { ...result, workflowProfile };
+}
+
+// src/core/healing/runtime-remediation-executor.ts
+import fs11 from "fs/promises";
+import path13 from "path";
+import { execSync as execSync3 } from "child_process";
+function createRuntimeRemediationExecutor(cwd, ledger = null) {
+  const adapter = new OpenCodeAdapter({ cwd });
+  function getChangedFiles2() {
+    try {
+      const output = execSync3("git status --short", { cwd, encoding: "utf8" });
+      return output.split("\n").filter(Boolean).map((line) => line.slice(3).trim()).filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+  return async function runtimeRemediationExecutor({
+    attempt,
+    maxAttempts,
+    mode,
+    affectedChecks,
+    requestPath,
+    result
+  }) {
+    console.log(`
+[HEALER] Running Runtime/Phoenix Structural Remediation [Attempt ${attempt}/${maxAttempts}]`);
+    console.log(`[HEALER] Affected checks: ${affectedChecks.join(", ")}`);
+    if (ledger) {
+      ledger.logEvent({
+        actor: "Phoenix",
+        actorType: "runtime-agent",
+        observed: true,
+        runtime: "opencode",
+        eventType: "remediation_start",
+        provenance: "opencode-adapter",
+        data: {
+          attempt,
+          affectedChecks,
+          event: "remediation.started"
+        }
+      });
+    }
+    let requestContent = {};
+    try {
+      requestContent = JSON.parse(await fs11.readFile(requestPath, "utf8"));
+    } catch {
+    }
+    const filesBefore = getChangedFiles2();
+    const fileContentsBefore = {};
+    for (const file of filesBefore) {
+      try {
+        fileContentsBefore[file] = await fs11.readFile(path13.join(cwd, file), "utf8");
+      } catch {
+        fileContentsBefore[file] = null;
+      }
+    }
+    const failedCommands = (result?.evidence?.commands || []).filter((cmd) => ["FAIL", "BLOCKED"].includes(cmd.status));
+    let concreteOutput = "";
+    if (failedCommands.length > 0) {
+      concreteOutput = failedCommands.map((cmd) => {
+        return `Command: ${cmd.name} (${Array.isArray(cmd.command) ? cmd.command.join(" ") : cmd.command})
+Exit Code: ${cmd.exitCode}
+Output:
+${cmd.output}`;
+      }).join("\n\n");
+    } else {
+      concreteOutput = JSON.stringify(result?.quality || result || {}, null, 2);
+    }
+    const promptMsg = `We are in remediation mode (attempt ${attempt}/${maxAttempts}).
+The following validation checks have failed:
+${affectedChecks.join(", ")}
+
+Details of the failure:
+\`\`\`
+${concreteOutput}
+\`\`\`
+
+Please inspect the code, identify the root cause of these failures (e.g. failing tests, syntax issues, build errors), and write a correction to the relevant files in the workspace to make the tests/validations pass.`;
+    console.log(`[HEALER] Sending structural healing request to Phoenix agent...`);
+    const runResult = await adapter.execute(promptMsg, {
+      agent: "Phoenix"
+    });
+    const filesAfter = getChangedFiles2();
+    const changedFiles = [];
+    for (const file of filesAfter) {
+      if (!filesBefore.includes(file)) {
+        changedFiles.push(file);
+      } else {
+        try {
+          const contentAfter = await fs11.readFile(path13.join(cwd, file), "utf8");
+          if (contentAfter !== fileContentsBefore[file]) {
+            changedFiles.push(file);
+          }
+        } catch {
+          if (fileContentsBefore[file] !== null) {
+            changedFiles.push(file);
+          }
+        }
+      }
+    }
+    const success = runResult.success && changedFiles.length > 0;
+    if (!runResult.success) {
+      console.log(`[HEALER] Phoenix remediation failed: ${runResult.error || "Unknown error"}`);
+      return {
+        applied: false,
+        reason: `Phoenix runtime execution failed: ${runResult.error || "Unknown error"}`
+      };
+    }
+    if (changedFiles.length === 0) {
+      console.log(`[HEALER] Phoenix execution succeeded but no files were modified.`);
+      return {
+        applied: false,
+        reason: "Phoenix runtime executed but did not modify any files in the workspace."
+      };
+    }
+    console.log(`[HEALER] Phoenix successfully executed remediation commands.`);
+    console.log(`[HEALER] Files modified: ${changedFiles.join(", ")}`);
+    return {
+      applied: true,
+      changedFiles,
+      evidenceAdded: ["phoenix-healing-run"]
+    };
+  };
+}
+
+// src/cli/commands/execute.ts
+import fs12 from "fs/promises";
+import path14 from "path";
+import { execSync as execSync4 } from "child_process";
+async function captureReadOnlyState(cwd, fastTrack = false) {
+  const finalizer = new Finalizer({ cwd, fastTrack });
+  const snapshot = await finalizer.snapshotManager.capture();
+  const execGit = (args) => {
+    try {
+      return execSync4(`git ${args}`, { cwd, encoding: "utf8", stdio: "pipe" }).trim();
+    } catch {
+      return "";
+    }
+  };
+  const head = execGit("rev-parse HEAD");
+  const branch = execGit("rev-parse --abbrev-ref HEAD");
+  const indexTree = execGit("write-tree");
+  const porcelainStatus = execGit("status --porcelain");
+  return {
+    snapshot,
+    head,
+    branch,
+    indexTree,
+    porcelainStatus
+  };
+}
+function compareReadOnlyState(before, after) {
+  const violations = [];
+  if (before.branch !== after.branch) {
+    violations.push(`Branch changed from '${before.branch}' to '${after.branch}'`);
+  }
+  if (before.head !== after.head) {
+    violations.push(`Git HEAD changed from '${before.head}' to '${after.head}' (commit or reset made inside read-only task)`);
+  }
+  if (before.indexTree !== after.indexTree) {
+    violations.push(`Git index tree changed from '${before.indexTree}' to '${after.indexTree}'`);
+  }
+  if (before.porcelainStatus !== after.porcelainStatus) {
+    violations.push(`Git status changed. Before:
+${before.porcelainStatus}
+After:
+${after.porcelainStatus}`);
+  }
+  const beforeFiles = before.snapshot.files || {};
+  const afterFiles = after.snapshot.files || {};
+  for (const [file, info] of Object.entries(afterFiles)) {
+    const prevInfo = beforeFiles[file];
+    if (!prevInfo) {
+      violations.push(`File added: ${file}`);
+    } else if (prevInfo.sha256 !== info.sha256) {
+      violations.push(`File content modified: ${file}`);
+    }
+  }
+  for (const file of Object.keys(beforeFiles)) {
+    if (!afterFiles[file]) {
+      violations.push(`File deleted: ${file}`);
+    }
+  }
+  return violations;
+}
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32) || "task";
+}
+function combineValidation2(evidence, quality) {
+  const statuses = [evidence.internalStatus, quality.overallStatus];
+  let overallStatus = "PASS";
+  if (statuses.includes("BLOCKED")) overallStatus = "BLOCKED";
+  else if (statuses.includes("FAIL")) overallStatus = "FAIL";
+  else if (statuses.includes("FAIL_DELEGATION_GATE")) overallStatus = "FAIL_DELEGATION_GATE";
+  else if (statuses.includes("FAIL_QUALITY_GATE")) overallStatus = "FAIL_QUALITY_GATE";
+  else if (statuses.includes("PASS_WITH_NOTES")) overallStatus = "PASS_WITH_NOTES";
+  return { overallStatus, evidence, quality };
+}
+async function classifyAndPlanExecution(naturalRequest, cwd, taskSlug, delegationController, stateMachine) {
+  const classifier = new RequestClassifier();
+  const classification = classifier.classify(naturalRequest, { cwd });
+  console.log(`[CLASSIFIED] Intent: ${classification.intent}, Mode: ${classification.mode}, Profile: ${classification.profile}`);
+  stateMachine.transitionTo("CLASSIFIED");
+  await delegationController.route(naturalRequest, classification);
+  const routingDecision = classification.routingDecision || {};
+  if (routingDecision.permissionDecision === "blocked") {
+    stateMachine.transitionTo("BLOCKED");
+    throw new Error(`[ROUTE BLOCKED] ${routingDecision.reason}`);
+  }
+  if (routingDecision.permissionDecision === "rerouted") {
+    console.log(`[REROUTED] ${routingDecision.reason}`);
+  }
+  const planner = new ExecutionPlanner({ cwd });
+  const plan = planner.plan(classification, taskSlug);
+  console.log(`[PLANNED] Owner: ${plan.owner}, Remediation limit: ${plan.remediationLimit}`);
+  stateMachine.transitionTo("PLANNED");
+  return { plan, classification };
+}
+function runBranchGate(plan, taskSlug, cwd, stateMachine, branchGate) {
+  const gateResult = branchGate.check("", {
+    taskSlug,
+    readOnly: !plan.branchNeeded
+  });
+  if (gateResult.blocked) {
+    stateMachine.transitionTo("BLOCKED");
+    throw new Error(`[GATE BLOCKED] ${gateResult.reason}`);
+  }
+  console.log(`[PASS] Branch Gate: ${gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : `${gateResult.branch} is authorized`}.`);
+  stateMachine.transitionTo("BRANCH_READY");
+  return gateResult;
+}
+async function createSpecIfRequired(plan, classification, taskSlug, cwd) {
+  if (plan.specPath) {
+    const fullSpecPath = path14.join(cwd, plan.specPath);
+    const specExists = await fs12.access(fullSpecPath).then(() => true).catch(() => false);
+    if (!specExists) {
+      await fs12.mkdir(path14.dirname(fullSpecPath), { recursive: true });
+      const specTemplatePath = path14.join(cwd, ".ai-workflow/templates/specs/standard.md");
+      const templateContent = await fs12.readFile(specTemplatePath, "utf8").catch(() => {
+        return `# [STANDARD] Specification: ${classification.request}
+
+## Metadata
+
+- ID: SPEC-${taskSlug}
+- Author: Spec-Engineer
+- Status: DRAFT
+- Date: ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}
+
+## Functional Requirements
+
+- ${classification.request}
+
+## Technical Implementation Plan
+
+### Files to Create/Modify
+
+- \`src/index.js\`
+
+## Acceptance Criteria
+
+- [ ] Implemented successfully
+
+## Testing Strategy
+
+- [ ] Behavior tests pass`;
+      });
+      await fs12.writeFile(fullSpecPath, templateContent);
+      console.log(`[EXECUTE] Created DRAFT specification template at: ${plan.specPath}`);
+    }
+  }
+}
+async function runImplementation(plan, classification, delegationController, stateMachine, fastTrack = false) {
+  stateMachine.transitionTo("DELEGATED");
+  stateMachine.transitionTo("IMPLEMENTING");
+  let promptMsg = classification.request;
+  if (plan.specPath) {
+    promptMsg = `Please review and fill in the specification file at: ${plan.specPath}. Make sure to change the Status field to 'APPROVED' in the Metadata section, and then implement the behavior described.`;
+  }
+  const runResult = await delegationController.implement(promptMsg, plan.owner, { readOnly: !plan.branchNeeded, fastTrack });
+  if (!runResult.success) {
+    console.error(`[EXECUTE] OpenCode adapter execution reported failure: ${runResult.error || "Unknown error"}`);
+    stateMachine.transitionTo("BLOCKED");
+    throw new Error(`[WORKFLOW BLOCKED] OpenCode runtime execution failed: ${runResult.error || "Unknown error"}`);
+  }
+  return runResult;
+}
+async function runReadOnlyConfinementCheck(readOnlyStateBefore, cwd, stateMachine, fastTrack = false) {
+  const readOnlyStateAfter = await captureReadOnlyState(cwd, fastTrack);
+  const violations = compareReadOnlyState(readOnlyStateBefore, readOnlyStateAfter);
+  if (violations.length > 0) {
+    console.error(`[EXECUTE] Read-only confinement violation detected:`);
+    for (const v of violations) {
+      console.error(`  - ${v}`);
+    }
+    stateMachine.transitionTo("BLOCKED");
+    throw new Error(`[WORKFLOW BLOCKED] Read-only confinement violation: files were written/modified, index or commits modified: 
+${violations.join("\n")}`);
+  }
+}
+async function runValidation(plan, taskSlug, cwd, gateResult, naturalRequest, delegationController, stateMachine) {
+  stateMachine.transitionTo("VALIDATING");
+  const validateWorkflow = async () => {
+    const evidence = await runCollectEvidence({
+      cwd,
+      exitOnError: false,
+      taskSlug,
+      evidencePolicy: plan.evidencePolicy,
+      profile: plan.profile,
+      branchRecovery: gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : "NOT_REQUIRED",
+      userRequest: naturalRequest,
+      explicitApprovals: process.env.AI_WORKFLOW_APPROVALS ? process.env.AI_WORKFLOW_APPROVALS.split(",").map((a) => a.trim()) : []
+    });
+    const quality = await new QualityGuard({
+      cwd,
+      taskSlug,
+      evidencePolicy: plan.evidencePolicy,
+      riskLevel: plan.riskLevel
+    }).verify();
+    return combineValidation2(evidence, quality);
+  };
+  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) {
+  if (!isRecoverableGateFailure(initialResult.overallStatus)) {
+    return initialResult;
+  }
+  console.log(`
+[REMEDIATION REQUIRED] ${initialResult.overallStatus}. Starting bounded remediation (limit: ${plan.remediationLimit}).`);
+  const executor = createRuntimeRemediationExecutor(cwd, ledger);
+  const healer = new HealerEngine({
+    cwd,
+    remediationLimit: plan.remediationLimit,
+    taskSlug,
+    ledger
+  });
+  return await healer.run({
+    initialResult,
+    validate: async () => {
+      stateMachine.transitionTo("REVALIDATING");
+      return await delegationController.validate(taskSlug, plan.profile, validateWorkflow, plan.evidencePolicy);
+    },
+    remediate: async (remedCtx) => {
+      stateMachine.transitionTo("REMEDIATING");
+      const remRes = await executor(remedCtx);
+      if (remRes.applied) {
+        checkBranchSafety();
+        await updateSnapshot();
+      }
+      return remRes;
+    }
+  });
+}
+async function runFinalizerStabilization(plan, taskSlug, cwd, initialResult, validateWorkflow, delegationController, finalizer, lastWriteSnapshotRef, checkBranchSafety) {
+  let integrity = await finalizer.verifyIntegrity(lastWriteSnapshotRef.current);
+  let revalidationCount = 0;
+  const maxRevalidations = 2;
+  let result = initialResult;
+  while (!integrity.valid && revalidationCount < maxRevalidations) {
+    console.log(`
+[FINALIZER WARNING] Workspace mutated during validation! Re-running validation to stabilize.`);
+    console.log(`Changes detected:`, integrity.changes);
+    checkBranchSafety();
+    lastWriteSnapshotRef.current = await finalizer.snapshotManager.capture();
+    revalidationCount++;
+    result = await delegationController.validate(taskSlug, plan.profile, validateWorkflow, plan.evidencePolicy);
+    checkBranchSafety();
+    integrity = await finalizer.verifyIntegrity(lastWriteSnapshotRef.current);
+  }
+  return { result, integrity };
+}
+async function generateFinalHandoff(plan, taskSlug, cwd, finalState, evidence) {
+  console.log("\n--- Final Handoff ---");
+  const handoffEngine = new HandoffEngine({ cwd });
+  const handoffPath = await handoffEngine.generate({
+    taskId: taskSlug,
+    status: finalState,
+    specPaths: plan.specPath ? [plan.specPath] : [],
+    evidence,
+    nextActions: `Profile ${plan.profile}. Observed execution completed with status ${finalState}.`
+  });
+  console.log(`
+[AI WORKFLOW COMPLETE] ${finalState}`);
+  console.log(`Handoff Packet: ${path14.relative(cwd, handoffPath)}
+`);
+  return handoffPath;
+}
+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.");
+  }
+  const taskSlug = taskSlugOverride || slugify(naturalRequest);
+  console.log(`
+[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 }) });
+  let plan = null;
+  try {
+    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 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}'!`);
+        }
+      }
+    };
+    await createSpecIfRequired(plan, classification, taskSlug, cwd);
+    let readOnlyStateBefore = null;
+    if (!plan.branchNeeded) {
+      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()
+      };
+    }
+    stateMachine.transitionTo("IMPLEMENTED");
+    checkBranchSafety();
+    const finalizer = new Finalizer({ cwd, fastTrack });
+    const snapshotRef = { current: await finalizer.snapshotManager.capture() };
+    const { result: valResult, validateWorkflow } = await runValidation(plan, taskSlug, cwd, gateResult, naturalRequest, delegationController, stateMachine);
+    let result = valResult;
+    result = await runBoundedRemediation(
+      plan,
+      taskSlug,
+      cwd,
+      result,
+      validateWorkflow,
+      ledger,
+      delegationController,
+      stateMachine,
+      checkBranchSafety,
+      async () => {
+        snapshotRef.current = await finalizer.snapshotManager.capture();
+      }
+    );
+    if (isTerminalFailure(result.overallStatus)) {
+      stateMachine.transitionTo("BLOCKED");
+      throw new Error(`[WORKFLOW BLOCKED] ${result.overallStatus}: Validation could not be resolved safely.`);
+    }
+    checkBranchSafety();
+    let integrity = { valid: true, changes: { added: [], modified: [], deleted: [] } };
+    let stabResult = result;
+    if (!fastTrack) {
+      const stab = await runFinalizerStabilization(
+        plan,
+        taskSlug,
+        cwd,
+        result,
+        validateWorkflow,
+        delegationController,
+        finalizer,
+        snapshotRef,
+        checkBranchSafety
+      );
+      stabResult = 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";
+        }
+      }
+    } 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";
+      }
+    }
+    const finalState = finalStatus === "PASS" ? "COMPLETED" : finalStatus === "PASS_WITH_NOTES" ? "COMPLETED_WITH_NOTES" : "BLOCKED";
+    stateMachine.transitionTo(finalState);
+    const handoffPath = await generateFinalHandoff(plan, taskSlug, cwd, finalState, result.evidence);
+    return { ...result, overallStatus: finalStatus, stateHistory: stateMachine.getHistory() };
+  } finally {
+    if (plan && !plan.branchNeeded) {
+      console.log(`
+[READ-ONLY LEDGER] (In-Memory/Stdout)
+${JSON.stringify(ledger.getEvents(), null, 2)}
+`);
+    } else {
+      try {
+        await ledger.save(`.ai-workflow/history/${taskSlug}-ledger.json`);
+      } catch (err) {
+      }
+    }
+  }
+}
+
+// src/cli/commands/clean.ts
+import { existsSync, rmSync, lstatSync, unlinkSync } from "fs";
+import { join } from "path";
+import readline from "readline";
+function askConfirmation(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+function isSymlink2(filePath) {
+  try {
+    return lstatSync(filePath).isSymbolicLink();
+  } catch (_) {
+    return false;
+  }
+}
+async function runClean({ cwd, yes = false, dryRun = false, purgeAgents = false }) {
+  const targets = [
+    ".ai-workflow",
+    "opencode.jsonc",
+    ".workflow-state.json",
+    "opencode"
+  ];
+  const hasAgents = existsSync(join(cwd, ".agents"));
+  const existingTargets = targets.map((name) => join(cwd, name)).filter((path15) => existsSync(path15) || isSymlink2(path15));
+  if (existingTargets.length === 0 && (!hasAgents || !purgeAgents)) {
+    console.log("No AI Workflow configuration or files found in the current project.");
+    return;
+  }
+  console.log("\n[AI WORKFLOW] De-initialization");
+  console.log("===============================");
+  if (dryRun) {
+    console.log("[DRY RUN] The following items would be deleted:");
+    existingTargets.forEach((path15) => console.log(`  - ${path15}`));
+    if (hasAgents && purgeAgents) {
+      console.log(`  - ${join(cwd, ".agents")} (customizations folder)`);
+    } else if (hasAgents) {
+      console.log(`  - NOTE: ${join(cwd, ".agents")} exists but will NOT be deleted (run with --purge-agents to delete)`);
+    }
+    return;
+  }
+  if (!yes) {
+    if (!process.stdin.isTTY) {
+      console.log("Error: Non-interactive terminal detected. Run with --yes to bypass confirmation.");
+      if (process.env.NODE_ENV === "test") {
+      } else {
+        process.exit(1);
+      }
+    }
+    const confirmDeinit = await askConfirmation("Are you sure you want to de-initialize AI Workflow from the project? [y/N] ");
+    if (confirmDeinit !== "y" && confirmDeinit !== "yes") {
+      console.log("Aborted.");
+      return;
+    }
+    if (hasAgents && !purgeAgents) {
+      const confirmPurge = await askConfirmation("A custom '.agents' folder was detected. Do you want to purge it (this deletes custom prompts/rules/skills)? [y/N] ");
+      if (confirmPurge === "y" || confirmPurge === "yes") {
+        purgeAgents = true;
+      }
+    }
+  }
+  if (purgeAgents && hasAgents) {
+    existingTargets.push(join(cwd, ".agents"));
+  }
+  console.log("\nRemoving files...");
+  for (const target of existingTargets) {
+    try {
+      if (isSymlink2(target)) {
+        unlinkSync(target);
+        console.log(`Deleted symlink: ${target}`);
+      } else {
+        rmSync(target, { recursive: true, force: true });
+        console.log(`Deleted directory/file: ${target}`);
+      }
+    } catch (error) {
+      console.error(`Failed to delete ${target}: ${error.message}`);
+    }
+  }
+  console.log("\nAI Workflow has been successfully removed from this project.");
+}
+
+// src/cli/index.ts
+function printHelp() {
+  console.log(`ai-workflow
+
+Usage:
+  ai-workflow execute "<request>" [--task=<slug>] [--request="<request>"]
+  ai-workflow run --spec-path=<path>
+  ai-workflow init [--yes] [--force] [--dry-run] [--no-install] [--no-overwrite] [--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>]
+  ai-workflow doctor
+  ai-workflow clean [--yes] [--dry-run] [--purge-agents]
+
+Commands:
+  execute           Orchestrate execution of a natural request through the state machine
+  run               Proportionate orchestrator with branch safety, validation, and bounded remediation
+  init              Install AI workflow defaults (OpenCode). --profile=standard (default) or --profile=full (adds examples)
+  collect-evidence  Run observed project validation; persists EVIDENCE.json under required evidence policy
+  doctor            Verify local ai-workflow installation
+  clean             De-initialize and remove AI Workflow files and symlinks from the project
+`);
+}
+function parseFlags(args) {
+  const specPathArg = args.find((arg) => arg.startsWith("--spec-path="));
+  const profileEqArg = args.find((arg) => arg.startsWith("--profile="));
+  const taskArg = args.find((arg) => arg.startsWith("--task="));
+  const modeArg = args.find((arg) => arg.startsWith("--mode="));
+  const evidencePolicyArg = args.find((arg) => arg.startsWith("--evidence-policy="));
+  const requestArg = args.find((arg) => arg.startsWith("--request="));
+  const visualDistArg = args.find((arg) => arg.startsWith("--visual-dist="));
+  const portArg = args.find((arg) => arg.startsWith("--port="));
+  const profileIdx = args.indexOf("--profile");
+  const profileVal = profileEqArg ? profileEqArg.replace("--profile=", "") : profileIdx >= 0 && profileIdx + 1 < args.length && !args[profileIdx + 1].startsWith("--") ? args[profileIdx + 1] : void 0;
+  return {
+    yes: args.includes("--yes"),
+    force: args.includes("--force"),
+    dryRun: args.includes("--dry-run"),
+    noInstall: args.includes("--no-install"),
+    noOverwrite: args.includes("--no-overwrite"),
+    claude: args.includes("--claude"),
+    codex: args.includes("--codex"),
+    antigravity: args.includes("--antigravity"),
+    "dev-mode": args.includes("--dev-mode"),
+    specPath: specPathArg ? specPathArg.replace("--spec-path=", "") : void 0,
+    profile: profileVal || void 0,
+    taskSlug: taskArg ? taskArg.replace("--task=", "") : void 0,
+    mode: modeArg ? modeArg.replace("--mode=", "") : void 0,
+    evidencePolicy: evidencePolicyArg ? evidencePolicyArg.replace("--evidence-policy=", "") : void 0,
+    request: requestArg ? requestArg.replace("--request=", "") : void 0,
+    visualDist: visualDistArg ? visualDistArg.replace("--visual-dist=", "") : void 0,
+    port: portArg ? portArg.replace("--port=", "") : void 0,
+    a11y: args.includes("--a11y"),
+    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("-"));
+    const request = flags.request || positionals.join(" ");
+    const result = await runExecute({
+      cwd: process.cwd(),
+      naturalRequest: request,
+      taskSlug: flags.taskSlug
+    });
+    if (result && (result.overallStatus === "FAIL_QUALITY_GATE" || result.overallStatus === "BLOCKED" || result.overallStatus === "FAIL")) {
+      process.exit(1);
+    }
+    return;
+  }
+  if (command === "run") {
+    await runMasterOrchestrator({
+      cwd: process.cwd(),
+      ...parseFlags(args.slice(1))
+    });
+    return;
+  }
+  if (command === "init") {
+    await runInit({
+      cwd: process.cwd(),
+      ...parseFlags(args.slice(1))
+    });
+    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");
+    await runCollectEvidence({
+      cwd: process.cwd(),
+      taskSlug: flags.taskSlug,
+      mode: flags.mode,
+      evidencePolicy: flags.evidencePolicy,
+      dryRun: flags.dryRun,
+      visualDist: flags.visualDist,
+      port: flags.port
+    });
+    return;
+  }
+  if (command === "validate") {
+    const flags = parseFlags(args.slice(1));
+    const { runValidate } = await import("../validate-Q2NLLQ5G.js");
+    await runValidate({
+      cwd: process.cwd(),
+      taskSlug: flags.taskSlug,
+      a11y: flags.a11y,
+      visualDist: flags.visualDist,
+      port: flags.port
+    });
+    return;
+  }
+  if (command === "doctor") {
+    await runDoctor({ cwd: process.cwd() });
+    return;
+  }
+  if (command === "clean") {
+    await runClean({
+      cwd: process.cwd(),
+      ...parseFlags(args.slice(1))
+    });
+    return;
+  }
+  throw new Error(`unknown command: ${command}`);
+}
 runCli(process.argv.slice(2)).catch((error) => {
   console.error(`ai-workflow error: ${error.message}`);
   process.exit(1);
 });
+export {
+  runCli
+};
+//# sourceMappingURL=ai-workflow.js.map