@williambeto/ai-workflow 1.19.0 → 2.1.0

package/{packages/ai-workflow/src → src}/commands/init.js

@@ -2,10 +2,11 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { createInstallPlan } from "../core/install-plan.js";
 import { buildAiWorkflowConfig, getTemplateFiles, isValidProfile } from "../core/templates.js";
-import { exists, writeFileSafe } from "../core/filesystem.js";
+import { exists, writeFileSafe, readJson } from "../core/filesystem.js";
 import { createManagedBackup, createManagedPathBackup } from "../core/backup.js";
 import { mergeOpencodeConfig } from "../core/opencode-merge.js";
-import { buildSymlinkEntries, isSymlinkTo } from "../core/symlink-layout.js";
+import { buildSymlinkEntries, isSymlinkTo, setupInternalSymlinks } from "../core/symlink-layout.js";
+import { GeminiAdapter, ClaudeAdapter, CodexAdapter } from "../adapters/index.js";
 
 function summarize(actions) {
   const createCount = actions.filter((a) => a.type === "create").length;
@@ -79,16 +80,63 @@ async function upsertGitignoreBlock(cwd, entries) {
   return "updated";
 }
 
-export async function runInit({ cwd, yes, force, dryRun, noInstall, noOverwrite, profile }) {
-  const selectedProfile = profile ?? "full";
-  const installRoot = ".ai-workflow";
+async function injectScripts(cwd) {
+  const pkgPath = path.join(cwd, "package.json");
+  if (!(await exists(pkgPath))) return;
+
+  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)}\n`);
+      return true;
+    }
+  } catch {
+    // Ignore invalid package.json
+  }
+  return false;
+}
+
+export async function runInit({
+ cwd, yes, force, dryRun, noInstall, noOverwrite, gemini, claude, codex, "dev-mode": devMode, profile }) {
+  // Self-execution guard
+  if (!devMode) {
+    try {
+      const pkgPath = path.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 {
+      // Ignore if package.json is unreadable. The guard is a safety net.
+    }
+  }
+
+  const selectedProfile = profile || "standard";
 
   if (!isValidProfile(selectedProfile)) {
-    throw new Error(`invalid profile: ${selectedProfile}. Use minimal, operational, or full.`);
+    console.error(`Invalid profile: "${selectedProfile}". Valid profiles: standard, full`);
+    process.exit(1);
   }
+  const installRoot = ".ai-workflow";
+
+  const platforms = [];
+  if (gemini) platforms.push("gemini");
+  if (claude) platforms.push("claude");
+  if (codex) platforms.push("codex");
 
   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 });
@@ -105,6 +153,9 @@ export async function runInit({ cwd, yes, force, dryRun, noInstall, noOverwrite,
 
   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;
   }
 
@@ -128,17 +179,10 @@ export async function runInit({ cwd, yes, force, dryRun, noInstall, noOverwrite,
     }
 
     const content =
-      action.relativePath === ".ai-workflow.json"
+      action.relativePath === ".ai-workflow/config.json"
         ? `${JSON.stringify(
             buildAiWorkflowConfig({
-              profile: selectedProfile,
-              managedFiles: Array.from(
-                new Set([
-                  ...Object.keys(getTemplateFiles(selectedProfile)).map((p) => path.join(installRoot, p)),
-                  ".ai-workflow.json"
-                ])
-              ),
-              managedLinks: linkEntries.map((entry) => entry.linkPath)
+              profile: selectedProfile
             }),
             null,
             2
@@ -175,6 +219,8 @@ export async function runInit({ cwd, yes, force, dryRun, noInstall, noOverwrite,
         maxPerFile: 20
       });
       linkBackups.push(backupPath);
+      // Ensure we remove the old path before symlinking if it's not already handled by backup
+      await fs.rm(absoluteLinkPath, { recursive: true, force: true });
     }
 
     const stat = await fs.lstat(absoluteTargetPath);
@@ -182,6 +228,7 @@ export async function runInit({ cwd, yes, force, dryRun, noInstall, noOverwrite,
     const linkTarget = process.platform === "win32" ? absoluteTargetPath : path.relative(path.dirname(absoluteLinkPath), absoluteTargetPath);
 
     try {
+      await fs.mkdir(path.dirname(absoluteLinkPath), { recursive: true });
       await fs.symlink(linkTarget, absoluteLinkPath, type);
     } catch (error) {
       throw new Error(
@@ -193,25 +240,77 @@ export async function runInit({ cwd, yes, force, dryRun, noInstall, noOverwrite,
     linkCreated.push(linkPath);
   }
 
-  const opencodeResult =
-    selectedProfile === "minimal"
-      ? { reason: "skipped (minimal profile)" }
-      : await mergeOpencodeConfig(cwd, { force, backupRoot, profile: selectedProfile });
+  await setupInternalSymlinks(cwd, installRoot);
+
+  const opencodeResult = await mergeOpencodeConfig(cwd, { force, backupRoot });
 
   const generatedIgnoreEntries = [
     ".ai-workflow/",
-    ".ai-workflow.json",
     ".ai-workflow-backups/",
+    "opencode.jsonc.backup.*",
     ...linkEntries.flatMap((entry) => toIgnoreEntries(entry.linkPath))
   ];
 
+  if (gemini) {
+    generatedIgnoreEntries.push(".gemini/");
+  }
+  if (codex) {
+    generatedIgnoreEntries.push(".agents/", ".codex/");
+  }
+  if (claude) {
+    generatedIgnoreEntries.push(".claude/");
+  }
+
   const gitignoreResult = await upsertGitignoreBlock(cwd, generatedIgnoreEntries);
+  const scriptInjected = await injectScripts(cwd);
+
+  if (platforms.length > 0) {
+    console.log("ai-workflow: migrating to native platforms...");
+    const agentsDir = path.join(cwd, installRoot, "opencode/agents");
+    const skillsDir = path.join(cwd, installRoot, "opencode/skills");
+
+    const agentFiles = (await fs.readdir(agentsDir).catch(() => []))
+      .filter((f) => f.endsWith(".md"))
+      .map((f) => path.join(agentsDir, f));
+
+    if (gemini) {
+      const adapter = new GeminiAdapter({ cwd });
+      
+      // Collect specialized skills from the new opencode/skills path
+      const skillFolders = await fs.readdir(skillsDir).catch(() => []);
+      const skillFiles = [];
+      for (const folder of skillFolders) {
+        const skillPath = path.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(`- gemini: deployed AI Workflow Kit agents to .gemini/ (native discovery enabled)`);
+    }
+
+    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)");
+    }
+  }
 
   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}`);

package/src/commands/run.js

@@ -0,0 +1,111 @@
+import { BranchGate } from "../core/gates/branch-gate.js";
+import { SpecValidator } from "../core/sdd/validator.js";
+import { HandoffEngine } from "../core/handoff/handoff-engine.js";
+import { runCollectEvidence } from "./collect-evidence.js";
+import { QualityGuard } from "../core/validation/quality-guard.js";
+import { HealerEngine } from "../core/healing/healer-engine.js";
+import { createCliRemediationExecutor } from "../core/healing/cli-remediation-executor.js";
+import { isRecoverableGateFailure, isTerminalFailure } from "../core/statuses.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { getWorkflowProfile, resolveWorkflowProfile } from "../core/workflow-profiles.js";
+
+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 path.basename(specPath, path.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 };
+}
+
+/**
+ * Coordinates branch safety, specification validation, observed validation, bounded remediation, and handoff.
+ * Failed required validation can never be promoted to success.
+ */
+export async function runMasterOrchestrator({ cwd, specPath, override, remediationExecutor = null }) {
+  console.log("\n[AI WORKFLOW] Starting evidence-backed orchestration...\n");
+
+  const branchGate = new BranchGate({ memoryDir: path.join(cwd, ".ai-workflow"), cwd });
+  const taskSlug = specPath ? normalizeTaskSlugFromSpec(specPath) : "implementation";
+  const gateResult = branchGate.check(override, { autoRecover: true, 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 = path.isAbsolute(specPath) ? specPath : path.join(cwd, specPath);
+  const validation = await validator.validate(absoluteSpecPath);
+  if (!validation.valid) throw new Error(`[SDD BLOCKED] Specification is not ready: ${validation.reason}`);
+
+  const executionMode = validation.tier === "deep" ? "full" : validation.tier === "tiny" ? "quick" : "standard";
+  const specContent = await fs.readFile(absoluteSpecPath, "utf8");
+  const workflowProfile = resolveWorkflowProfile({ request: specContent });
+  const profileDefinition = getWorkflowProfile(workflowProfile);
+  console.log(`[PASS] Specification: ${validation.tier.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,
+      mode: executionMode,
+      profile: workflowProfile,
+      branchRecovery: gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : "NOT_REQUIRED"
+    });
+    const quality = await new QualityGuard({ cwd, taskSlug, mode: executionMode }).verify();
+    return combineValidation(evidence, quality);
+  };
+
+  let result = await validateWorkflow();
+  if (isRecoverableGateFailure(result.overallStatus)) {
+    console.log(`\n[REMEDIATION REQUIRED] ${result.overallStatus}. Starting bounded ${executionMode} remediation.`);
+    // Use the provided executor (programmatic API) or fall back to the default CLI executor.
+    // The CLI executor re-runs failed npm scripts; it does not modify source code.
+    const executor = typeof remediationExecutor === "function"
+      ? remediationExecutor
+      : createCliRemediationExecutor(cwd);
+    const healer = new HealerEngine({ cwd, mode: executionMode, 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: path.basename(specPath, ".md"),
+    status: result.overallStatus,
+    specPaths: [specPath],
+    nextActions: `Profile ${workflowProfile}. Observed validation completed. Ready for review or explicitly approved release actions.`
+  });
+
+  console.log(`\n[AI WORKFLOW COMPLETE] ${result.overallStatus}`);
+  if (result.remediation?.attempts) console.log(`Remediation attempts: ${result.remediation.attempts}`);
+  console.log(`Handoff Packet: ${path.relative(cwd, handoffPath)}\n`);
+  return { ...result, workflowProfile };
+}
+
+export { combineValidation };

package/src/core/completion-contract.js

@@ -0,0 +1,35 @@
+/**
+ * Evaluates objective owner-output completeness. It does not judge visual taste.
+ * A caller may resume the same owner once; a second incomplete result must block.
+ */
+export function evaluateOwnerCompletion({
+  expectedFiles = [],
+  existingFiles = [],
+  validation = {},
+  ownerReportComplete = false,
+  resumeCount = 0
+} = {}) {
+  const existing = new Set(existingFiles);
+  const missingFiles = expectedFiles.filter((file) => !existing.has(file));
+  const missingValidation = Object.entries(validation)
+    .filter(([, value]) => value === "REQUIRED" || value === false)
+    .map(([key]) => key);
+  const missing = [
+    ...missingFiles.map((file) => `file:${file}`),
+    ...missingValidation.map((check) => `validation:${check}`),
+    ...(!ownerReportComplete ? ["owner-report"] : [])
+  ];
+
+  if (missing.length === 0) {
+    return { status: "PASS", action: "continue", missing: [] };
+  }
+  if (resumeCount < 1) {
+    return { status: "INCOMPLETE", action: "resume-same-owner", missing };
+  }
+  return {
+    status: "BLOCKED",
+    action: "stop",
+    reason: "Owner output remained incomplete after one resume",
+    missing
+  };
+}

package/src/core/gates/branch-gate.js

@@ -0,0 +1,113 @@
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+function slugify(value = "task") {
+  return String(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48) || "task";
+}
+
+/**
+ * BranchGate - Protects main/master and can recover safely onto a scoped branch.
+ */
+export class BranchGate {
+  constructor({ protectedBranches = ["main", "master"], memoryDir, cwd = process.cwd() } = {}) {
+    this.protectedBranches = protectedBranches;
+    this.logPath = memoryDir ? path.join(memoryDir, "GATE_ALERTS.log") : null;
+    this.cwd = cwd;
+  }
+
+  run(command) {
+    return execSync(command, {
+      cwd: this.cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    }).trim();
+  }
+
+  log(event) {
+    if (!this.logPath) return;
+    const timestamp = new Date().toISOString();
+    const logEntry = `[${timestamp}] ${event}\n`;
+    try {
+      if (!fs.existsSync(path.dirname(this.logPath))) fs.mkdirSync(path.dirname(this.logPath), { recursive: true });
+      fs.appendFileSync(this.logPath, logEntry);
+    } catch (error) {
+      console.error(`Failed to write to gate log: ${error.message}`);
+    }
+  }
+
+  getDirtyState() {
+    const lines = this.run("git status --short").split("\n").filter(Boolean);
+    const tracked = lines.filter((line) => !line.startsWith("??"));
+    const untracked = lines.filter((line) => line.startsWith("??"));
+    return { clean: lines.length === 0, tracked, untracked, lines };
+  }
+
+  createScopedBranch(taskSlug) {
+    const base = `feat/${slugify(taskSlug)}`;
+    let candidate = base;
+    let suffix = 2;
+    while (true) {
+      try {
+        this.run(`git show-ref --verify --quiet refs/heads/${candidate}`);
+        candidate = `${base}-${suffix++}`;
+      } catch {
+        break;
+      }
+    }
+    this.run(`git switch -c ${candidate}`);
+    return candidate;
+  }
+
+  /**
+   * @param {string} override
+   * @param {{autoRecover?: boolean, taskSlug?: string}} options
+   */
+  check(override = "", { autoRecover = false, taskSlug = "implementation" } = {}) {
+    try {
+      const currentBranch = this.run("git rev-parse --abbrev-ref HEAD");
+      const isProtected = this.protectedBranches.includes(currentBranch);
+      if (!isProtected) return { blocked: false, branch: currentBranch, recovered: false };
+
+      if (override && override.trim().length >= 20) {
+        this.log(`AUTHORIZED BYPASS on '${currentBranch}': ${override.trim()}`);
+        return { blocked: false, branch: currentBranch, authorized: true, recovered: false };
+      }
+
+      if (autoRecover) {
+        const dirty = this.getDirtyState();
+        if (dirty.tracked.length > 0) {
+          const reason = `Unsafe tracked changes prevent Branch Gate Auto-Recovery: ${dirty.tracked.join(", ")}`;
+          this.log(`BLOCKED AUTO-RECOVERY on '${currentBranch}': ${reason}`);
+          return { blocked: true, branch: currentBranch, reason, dirtyState: dirty };
+        }
+
+        const recoveredBranch = this.createScopedBranch(taskSlug);
+        this.log(`AUTO-RECOVERED '${currentBranch}' -> '${recoveredBranch}'`);
+        return {
+          blocked: false,
+          branch: recoveredBranch,
+          branchBefore: currentBranch,
+          recovered: true,
+          dirtyState: dirty
+        };
+      }
+
+      const reason = override && override.trim().length < 20
+        ? "Override justification too short (min 20 chars)."
+        : `Direct commits to '${currentBranch}' are prohibited.`;
+      this.log(`BLOCKED ATTEMPT on '${currentBranch}': ${reason}`);
+      return {
+        blocked: true,
+        branch: currentBranch,
+        reason: `${reason} Enable safe auto-recovery or use AI_OVERRIDE with a concrete justification.`
+      };
+    } catch (error) {
+      return { blocked: false, branch: "unknown", error: error.message, recovered: false };
+    }
+  }
+}

package/src/core/handoff/handoff-engine.js

@@ -0,0 +1,78 @@
+import { execSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * HandoffEngine - Bundles project context into a single Markdown packet.
+ */
+export class HandoffEngine {
+  constructor({ cwd }) {
+    this.cwd = cwd;
+  }
+
+  /**
+   * Generates a handoff packet.
+   * @param {Object} data - Context data.
+   * @returns {Promise<string>} The generated packet content.
+   */
+  async generate({ taskId, author, status, specPaths = [], nextActions }) {
+    const timestamp = new Date().toISOString();
+    
+    // 1. Collect Specs content
+    let specsContent = "";
+    for (const specPath of specPaths) {
+      const absolutePath = path.isAbsolute(specPath) ? specPath : path.join(this.cwd, specPath);
+      try {
+        const content = await fs.readFile(absolutePath, "utf8");
+        specsContent += `### File: ${specPath}\n\n${content}\n\n`;
+      } catch (err) {
+        specsContent += `### File: ${specPath}\n\n[Error reading file: ${err.message}]\n\n`;
+      }
+    }
+
+    // 2. Capture Git Diff
+    let gitDiff = "No changes detected.";
+    try {
+      gitDiff = execSync("git diff HEAD", { cwd: this.cwd, encoding: "utf8" }).trim() || "No changes detected.";
+    } catch (err) {
+      gitDiff = `[Error capturing diff: ${err.message}]`;
+    }
+
+    // 3. Read EVIDENCE.json
+    let evidenceJson = "{}";
+    let evidenceSummary = "No evidence found.";
+    const evidencePath = path.join(this.cwd, "EVIDENCE.json");
+    try {
+      const content = await fs.readFile(evidencePath, "utf8");
+      const data = JSON.parse(content);
+      evidenceJson = JSON.stringify(data, null, 2);
+      evidenceSummary = `Status: ${data.status}, Commands: ${data.commands?.length || 0}`;
+    } catch (err) {
+      // Optional: don't fail if evidence is missing
+    }
+
+    // 4. Populate Template
+    const templatePath = path.join(import.meta.dirname, "../../../dist-assets/templates/HANDOFF.template.md");
+    let template = await fs.readFile(templatePath, "utf8");
+
+    const packet = template
+      .replace("${TASK_ID}", taskId || "unknown")
+      .replace("${TIMESTAMP}", timestamp)
+      .replace("${AUTHOR}", author || "AI Workflow Kit")
+      .replace("${STATUS}", status || "IN_PROGRESS")
+      .replace("${SPECS_CONTENT}", specsContent || "No specs provided.")
+      .replace("${EVIDENCE_SUMMARY}", evidenceSummary)
+      .replace("${EVIDENCE_JSON}", evidenceJson)
+      .replace("${GIT_DIFF}", gitDiff)
+      .replace("${NEXT_ACTIONS}", nextActions || "Awaiting manager assignment.");
+
+    const handoffDir = path.join(this.cwd, ".ai-workflow/handoffs");
+    await fs.mkdir(handoffDir, { recursive: true });
+    
+    const packetName = `HANDOFF-${taskId || "TMP"}-${Date.now()}.md`;
+    const packetPath = path.join(handoffDir, packetName);
+    await fs.writeFile(packetPath, packet);
+
+    return packetPath;
+  }
+}