@williambeto/ai-workflow 2.4.8 → 2.6.3

package/src/core/healing/healer-engine.js

@@ -1,212 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import crypto from "node:crypto";
-import { isRecoverableGateFailure } from "../statuses.js";
-
-const MODE_ATTEMPTS = Object.freeze({ quick: 1, standard: 2, full: 3 });
-
-function stableJson(value) {
-  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
-  if (value && typeof value === "object") {
-    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
-  }
-  return JSON.stringify(value);
-}
-
-function collectBlockingFindings(result = {}) {
-  const findings = [];
-  const add = (source, value) => {
-    if (!value || typeof value !== "object") return;
-    const status = value.status || value.overallStatus;
-    if (!["FAIL", "FAIL_QUALITY_GATE", "FAIL_DELEGATION_GATE", "BLOCKED"].includes(status)) return;
-    findings.push({
-      source,
-      status,
-      missing: Array.isArray(value.missing) ? [...value.missing].sort() : [],
-      reason: value.reason || value.summary || ""
-    });
-  };
-
-  add("result", result);
-  add("evidence", result.evidence);
-  add("quality", result.quality);
-  const checks = result.quality?.checks || result.policyValidation?.checks || result.checks || {};
-  for (const [name, check] of Object.entries(checks)) add(`check:${name}`, check);
-  return findings.sort((a, b) => a.source.localeCompare(b.source));
-}
-
-export class HealerEngine {
-  constructor({ cwd, mode = "standard", taskSlug = "implementation", maxAttempts = null, ledger = null } = {}) {
-    this.cwd = cwd;
-    this.mode = MODE_ATTEMPTS[mode] ? mode : "standard";
-    this.taskSlug = taskSlug;
-    this.maxAttempts = maxAttempts ?? MODE_ATTEMPTS[this.mode];
-    this.ledger = ledger;
-  }
-
-  get statePath() {
-    return path.join(this.cwd, ".ai-workflow", `healing-state-${this.taskSlug}.json`);
-  }
-
-  fingerprint(result) {
-    return crypto.createHash("sha256").update(stableJson(collectBlockingFindings(result))).digest("hex");
-  }
-
-  blockingCount(result) {
-    return collectBlockingFindings(result).length;
-  }
-
-  affectedChecks(result) {
-    return collectBlockingFindings(result).map((finding) => finding.source);
-  }
-
-  hasProgress(before, after, remediation = {}) {
-    if (!isRecoverableGateFailure(after.overallStatus)) return true;
-    const beforeCount = this.blockingCount(before);
-    const afterCount = this.blockingCount(after);
-    if (afterCount < beforeCount) return true;
-    if (this.fingerprint(before) !== this.fingerprint(after) && (remediation.changedFiles?.length || remediation.evidenceAdded?.length)) return true;
-    return false;
-  }
-
-  async writeState(state) {
-    await fs.mkdir(path.dirname(this.statePath), { recursive: true });
-    await fs.writeFile(this.statePath, JSON.stringify(state, null, 2));
-  }
-
-  async resetState() {
-    try { await fs.unlink(this.statePath); } catch {}
-  }
-
-  async writeRemediationRequest({ attempt, result }) {
-    const requestPath = path.join(this.cwd, ".ai-workflow", "remediation-request.json");
-    await fs.mkdir(path.dirname(requestPath), { recursive: true });
-    const request = {
-      taskSlug: this.taskSlug,
-      executionMode: this.mode,
-      attempt,
-      maxAttempts: this.maxAttempts,
-      status: result.overallStatus,
-      affectedChecks: this.affectedChecks(result),
-      findingsFingerprint: this.fingerprint(result),
-      instruction: "Apply the smallest safe correction for the listed gates, then rerun validation. Do not broaden scope."
-    };
-    await fs.writeFile(requestPath, JSON.stringify(request, null, 2));
-    return requestPath;
-  }
-
-  async run({ initialResult, validate, remediate }) {
-    let current = initialResult;
-    const history = [];
-    const seen = new Set();
-
-    if (!isRecoverableGateFailure(current.overallStatus)) {
-      await this.resetState();
-      return { ...current, remediation: { status: "NOT_REQUIRED", attempts: 0, history } };
-    }
-
-    for (let attempt = 1; attempt <= this.maxAttempts; attempt += 1) {
-      const fingerprint = this.fingerprint(current);
-      if (seen.has(fingerprint)) {
-        const blocked = { overallStatus: "BLOCKED", reason: "Repeated unresolved finding", previousResult: current };
-        await this.writeState({ status: "BLOCKED", reason: blocked.reason, attempts: attempt - 1, history });
-        return { ...blocked, remediation: { status: "BLOCKED", attempts: attempt - 1, history } };
-      }
-      seen.add(fingerprint);
-
-      const requestPath = await this.writeRemediationRequest({ attempt, result: current });
-      if (typeof remediate !== "function") {
-        const blocked = { overallStatus: "BLOCKED", reason: "No remediation executor available", previousResult: current, requestPath };
-        await this.writeState({ status: "BLOCKED", reason: blocked.reason, attempts: attempt - 1, history, requestPath });
-        return { ...blocked, remediation: { status: "BLOCKED", attempts: attempt - 1, history, requestPath } };
-      }
-
-      const remediation = await remediate({
-        attempt,
-        maxAttempts: this.maxAttempts,
-        mode: this.mode,
-        taskSlug: this.taskSlug,
-        result: current,
-        affectedChecks: this.affectedChecks(current),
-        requestPath
-      });
-
-      if (!remediation?.applied) {
-        const blocked = { overallStatus: "BLOCKED", reason: remediation?.reason || "Remediation was not applied", previousResult: current, requestPath };
-        history.push({ attempt, before: current.overallStatus, remediation, after: "NOT_RUN", progress: false });
-        await this.writeState({ status: "BLOCKED", reason: blocked.reason, attempts: attempt, history });
-        return { ...blocked, remediation: { status: "BLOCKED", attempts: attempt, history } };
-      }
-
-      const next = await validate({ affectedChecks: this.affectedChecks(current), attempt });
-      const progress = this.hasProgress(current, next, remediation);
-
-      // Verify strict conditions to declare Phoenix remediation applied/completed
-      const findingsConcrete = this.affectedChecks(current).length > 0;
-      const hashAltered = remediation.changedFiles && remediation.changedFiles.length > 0;
-      const inScope = hashAltered && remediation.changedFiles.every(file => {
-        const norm = file.replaceAll("\\", "/");
-        if (norm.startsWith(".ai-workflow/")) return false;
-        if (norm === "package.json" || norm === "package-lock.json" || norm === "tsconfig.json" || norm === ".gitignore" || norm === "opencode.jsonc" || norm === "EVIDENCE.json") {
-          return false;
-        }
-        return true;
-      });
-      const validationPassed = next.overallStatus === "PASS" || next.overallStatus === "PASS_WITH_NOTES";
-
-      const phoenixSuccessful = findingsConcrete && hashAltered && inScope && validationPassed;
-
-      if (this.ledger && phoenixSuccessful) {
-        this.ledger.logEvent({
-          actor: "Phoenix",
-          actorType: "runtime-agent",
-          observed: true,
-          runtime: "opencode",
-          eventType: "remediation_complete",
-          provenance: "opencode-adapter",
-          data: {
-            success: true,
-            changedFiles: remediation.changedFiles,
-            event: "remediation.completed"
-          }
-        });
-      }
-
-      history.push({
-        attempt,
-        before: current.overallStatus,
-        after: next.overallStatus,
-        progress,
-        changedFiles: remediation.changedFiles || [],
-        evidenceAdded: remediation.evidenceAdded || [],
-        affectedChecks: this.affectedChecks(current)
-      });
-      await this.writeState({ status: next.overallStatus, attempts: attempt, history });
-
-      if (!isRecoverableGateFailure(next.overallStatus)) {
-        await this.resetState();
-        return { ...next, remediation: { status: "RESOLVED", attempts: attempt, history } };
-      }
-
-      if (!progress) {
-        return {
-          overallStatus: "BLOCKED",
-          reason: "Remediation made no measurable progress",
-          previousResult: next,
-          remediation: { status: "BLOCKED", attempts: attempt, history }
-        };
-      }
-
-      current = next;
-    }
-
-    return {
-      overallStatus: "BLOCKED",
-      reason: `Quality remediation attempts exhausted for ${this.mode} mode`,
-      previousResult: current,
-      remediation: { status: "BLOCKED", attempts: this.maxAttempts, history }
-    };
-  }
-}
-
-export { MODE_ATTEMPTS, collectBlockingFindings };

package/src/core/healing/runtime-remediation-executor.js

@@ -1,136 +0,0 @@
-import { OpenCodeAdapter } from "../runtime/opencode-adapter.js";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { execSync } from "node:child_process";
-
-export function createRuntimeRemediationExecutor(cwd, ledger = null) {
-  const adapter = new OpenCodeAdapter({ cwd });
-
-  function getChangedFiles() {
-    try {
-      const output = execSync("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(`\n[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 fs.readFile(requestPath, "utf8"));
-    } catch {
-      // ignore/fallback
-    }
-
-    const filesBefore = getChangedFiles();
-    const fileContentsBefore = {};
-    for (const file of filesBefore) {
-      try {
-        fileContentsBefore[file] = await fs.readFile(path.join(cwd, file), "utf8");
-      } catch {
-        fileContentsBefore[file] = null;
-      }
-    }
-    
-    // Extract concrete command outputs for failing checks
-    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 = getChangedFiles();
-    const changedFiles = [];
-    for (const file of filesAfter) {
-      if (!filesBefore.includes(file)) {
-        changedFiles.push(file);
-      } else {
-        try {
-          const contentAfter = await fs.readFile(path.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"]
-    };
-  };
-}

package/src/core/identity.js

@@ -1,43 +0,0 @@
-export const AGENT_MAP = {
-  "atlas": "Atlas",
-  "nexus": "Nexus",
-  "orion": "Orion",
-  "astra": "Astra",
-  "sage": "Sage",
-  "phoenix": "Phoenix",
-  "architecture": "Architecture-Specialist",
-  "backend-development": "Backend-Engineer",
-  "deployment": "Deployment-Specialist",
-  "design-principles": "Design-Specialist",
-  "documentation": "Docs-Engineer",
-  "frontend-development": "Frontend-Engineer",
-  "full-stack-development": "Full-Stack-Engineer",
-  "optimize-tokens": "Token-Economist",
-  "pr-workflow": "PR-Manager",
-  "product-discovery": "Discovery-Analyst",
-  "product-planning": "Product-Planner",
-  "project-memory": "Memory-Guardian",
-  "prompt-engineer": "Prompt-Engineer",
-  "qa-workflow": "QA-Engineer",
-  "refactoring": "Refactoring-Specialist",
-  "release-workflow": "Release-Specialist",
-  "spec-driven-development": "SDD-Specialist",
-  "technical-leadership": "Technical-Leader",
-  "ui-ux-design": "UI-UX-Engineer"
-};
-
-/**
- * Returns the canonical (commercial) name for an agent given its internal slug.
- * Falls back to PascalCase translation if no mapping exists.
- * @param {string} slug
- * @returns {string}
- */
-export function getCanonicalAgentName(slug) {
-  if (AGENT_MAP[slug]) return AGENT_MAP[slug];
-  
-  // Fallback: convert slug-case to PascalCase
-  return slug
-    .split("-")
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join("");
-}

package/src/core/install-plan.js

@@ -1,34 +0,0 @@
-import path from "node:path";
-import { getTemplateFiles } from "./templates.js";
-
-export async function createInstallPlan({ cwd, exists, 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 exists(absolutePath)) ? "conflict" : "create";
-    actions.push({
-      type: action,
-      relativePath: installedRelativePath,
-      absolutePath,
-      content
-    });
-  }
-
-  const configPath = path.join(cwd, ".ai-workflow/config.json");
-  actions.push({
-    type: (await exists(configPath)) ? "conflict" : "create",
-    relativePath: ".ai-workflow/config.json",
-    absolutePath: configPath,
-    content: null
-  });
-
-  return actions;
-}

package/src/core/opencode-merge.js

@@ -1,150 +0,0 @@
-import path from "node:path";
-import { exists, readJsonc, writeFileSafe } from "./filesystem.js";
-import { createManagedBackup } from "./backup.js";
-import { getTemplateFiles } from "./templates.js";
-
-const LEGACY_MARKER = "_aiWorkflowManaged";
-
-const 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" }
-};
-
-const 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" }
-};
-
-const 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
-  };
-}
-
-export async function mergeOpencodeConfig(cwd, { force = false, backupRoot = ".ai-workflow-backups" } = {}) {
-  const targetPath = path.join(cwd, "opencode.jsonc");
-  const managed = buildManagedConfig();
-
-  if (!(await exists(targetPath))) {
-    await writeFileSafe(targetPath, `${JSON.stringify(managed, null, 2)}\n`);
-    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)}\n`);
-    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)}\n`);
-  return { changed: true, reason: "merged-managed-sections" };
-}