@williambeto/ai-workflow 2.2.7 → 2.3.1

package/src/core/evidence/evidence-ledger.js

@@ -0,0 +1,53 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * EvidenceLedger - Traces structural workflow events to make delegation observable.
+ */
+export class EvidenceLedger {
+  constructor({ cwd = process.cwd(), workflowId = "unknown" } = {}) {
+    this.cwd = cwd;
+    this.workflowId = workflowId;
+    this.events = [];
+  }
+
+  /**
+   * Logs a workflow event to the ledger.
+   * @param {Object} eventParam
+   * @param {string} eventParam.actor - The agent name (Atlas, Astra, Sage, Phoenix).
+   * @param {string} eventParam.eventType - Type of event.
+   * @param {string} eventParam.provenance - Originating component.
+   * @param {Object} [eventParam.data] - Additional metadata.
+   * @returns {Object} The logged event.
+   */
+  logEvent({ actor, eventType, provenance, data = {}, actorType, observed, runtime }) {
+    const event = {
+      workflowId: this.workflowId,
+      timestamp: new Date().toISOString(),
+      actor,
+      actorType: actorType !== undefined ? actorType : undefined,
+      observed: observed !== undefined ? observed : undefined,
+      runtime: runtime !== undefined ? runtime : undefined,
+      eventType,
+      provenance,
+      data
+    };
+    this.events.push(event);
+    console.log(`[LEDGER] [${actor}] ${eventType}: ${JSON.stringify(data)}`);
+    return event;
+  }
+
+  getEvents() {
+    return this.events;
+  }
+
+  /**
+   * Saves the ledger events to a JSON file.
+   * @param {string} filePath - Absolute or relative path.
+   */
+  async save(filePath) {
+    const targetPath = path.isAbsolute(filePath) ? filePath : path.join(this.cwd, filePath);
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.writeFile(targetPath, JSON.stringify(this.events, null, 2), "utf8");
+  }
+}

package/src/core/execution-planner.js

@@ -21,6 +21,9 @@ export class ExecutionPlanner {
       ? path.join("docs/workflows", taskSlug, "spec.md")
       : null;
 
+    const owner = classification.routingDecision?.selectedActor ||
+      (classification.intent === "write" ? "Astra" : classification.owner);
+
     // Build default expected validations based on the resolved profile
     const validationsExpected = [];
     if (classification.validationNeeded) {
@@ -45,7 +48,7 @@ export class ExecutionPlanner {
       objective: classification.request,
       scope: classification.intent === "read-only" ? "Analysis and verification" : "Implementation of requested behavior",
       restrictions,
-      owner: classification.owner,
+      owner,
       skills: [...classification.skills],
       branchNeeded,
       branchName: branchNeeded ? `feat/${taskSlug}` : null,

package/src/core/finalization/finalizer.js

@@ -0,0 +1,77 @@
+import { WorkspaceSnapshot } from "./workspace-snapshot.js";
+
+export class Finalizer {
+  constructor({ cwd = process.cwd() } = {}) {
+    this.cwd = cwd;
+    this.snapshotManager = new WorkspaceSnapshot({ cwd });
+  }
+
+  /**
+   * Compares the current workspace state with a previously captured snapshot.
+   * @param {Object} previousSnapshot - The snapshot object captured earlier.
+   * @returns {Object} { valid: boolean, changes: { added: string[], modified: string[], deleted: string[] } }
+   */
+  async verifyIntegrity(previousSnapshot) {
+    const currentSnapshot = await this.snapshotManager.capture();
+    const added = [];
+    const modified = [];
+    const deleted = [];
+
+    let valid = true;
+
+    // Compare metadata and git trees
+    if (previousSnapshot.branch !== currentSnapshot.branch) {
+      modified.push(`branch:${previousSnapshot.branch}->${currentSnapshot.branch}`);
+      valid = false;
+    }
+    if (previousSnapshot.head !== currentSnapshot.head) {
+      modified.push(`head:${previousSnapshot.head}->${currentSnapshot.head}`);
+      valid = false;
+    }
+    if (previousSnapshot.indexTree !== currentSnapshot.indexTree) {
+      modified.push(`indexTree:${previousSnapshot.indexTree}->${currentSnapshot.indexTree}`);
+      valid = false;
+    }
+    if (previousSnapshot.stagedDiffHash !== currentSnapshot.stagedDiffHash) {
+      modified.push("stagedDiff");
+      valid = false;
+    }
+    if (previousSnapshot.unstagedDiffHash !== currentSnapshot.unstagedDiffHash) {
+      modified.push("unstagedDiff");
+      valid = false;
+    }
+    if (previousSnapshot.untrackedFilesHash !== currentSnapshot.untrackedFilesHash) {
+      modified.push("untrackedFiles");
+      valid = false;
+    }
+
+    // Check for additions and modifications in files
+    const prevFiles = previousSnapshot.files || {};
+    const currFiles = currentSnapshot.files || {};
+
+    for (const [file, info] of Object.entries(currFiles)) {
+      const prevInfo = prevFiles[file];
+      if (!prevInfo) {
+        added.push(file);
+      } else if (prevInfo.sha256 !== info.sha256 || prevInfo.mode !== info.mode) {
+        modified.push(file);
+      }
+    }
+
+    // Check for deletions in files
+    for (const file of Object.keys(prevFiles)) {
+      if (!currFiles[file]) {
+        deleted.push(file);
+      }
+    }
+
+    if (added.length > 0 || modified.length > 0 || deleted.length > 0) {
+      valid = false;
+    }
+
+    return {
+      valid,
+      changes: { added, modified, deleted }
+    };
+  }
+}

package/src/core/finalization/workspace-snapshot.js

@@ -0,0 +1,110 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { execSync } from "node:child_process";
+
+export class WorkspaceSnapshot {
+  constructor({ cwd = process.cwd() } = {}) {
+    this.cwd = cwd;
+  }
+
+  isIgnored(relativePath) {
+    const norm = relativePath.replaceAll("\\", "/");
+    if (norm === "node_modules" || norm.startsWith("node_modules/")) return true;
+    if (norm === "vendor" || norm.startsWith("vendor/")) return true;
+    if (norm === ".git" || norm.startsWith(".git/")) return true;
+    if (norm === "EVIDENCE.json") return true;
+    if (norm === ".ai-workflow/EVIDENCE.json") return true;
+    if (norm.startsWith(".ai-workflow/history/")) return true;
+    if (norm.startsWith(".ai-workflow/handoffs/")) return true;
+    return false;
+  }
+
+  async capture() {
+    const files = {};
+    await this.scanDir(this.cwd, files);
+
+    const execGit = (args) => {
+      try {
+        return execSync(`git ${args}`, { cwd: this.cwd, encoding: "utf8", stdio: "pipe" }).trim();
+      } catch {
+        return "";
+      }
+    };
+
+    const branch = execGit("rev-parse --abbrev-ref HEAD");
+    const head = execGit("rev-parse HEAD");
+    const indexTree = execGit("write-tree");
+
+    const stagedDiff = execGit("diff --cached");
+    const unstagedDiff = execGit("diff");
+    const untrackedFiles = execGit("status --porcelain");
+
+    const hashString = (str) => {
+      return crypto.createHash("sha256").update(str).digest("hex");
+    };
+
+    return {
+      branch,
+      head,
+      indexTree,
+      files,
+      stagedDiffHash: hashString(stagedDiff),
+      unstagedDiffHash: hashString(unstagedDiff),
+      untrackedFilesHash: hashString(untrackedFiles)
+    };
+  }
+
+  async scanDir(dir, filesMap) {
+    try {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        const relativePath = path.relative(this.cwd, fullPath);
+
+        if (this.isIgnored(relativePath)) {
+          continue;
+        }
+
+        if (entry.isDirectory()) {
+          await this.scanDir(fullPath, filesMap);
+        } else if (entry.isFile()) {
+          try {
+            const stat = await fs.stat(fullPath);
+            const content = await fs.readFile(fullPath);
+            const sha256 = crypto.createHash("sha256").update(content).digest("hex");
+            const isExecutable = (stat.mode & 0o111) !== 0;
+            const mode = isExecutable ? "100755" : "100644";
+
+            filesMap[relativePath] = {
+              sha256,
+              mode
+            };
+          } catch {
+            // ignore unreadable/locked files
+          }
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  calculateHash(snapshot) {
+    const hash = crypto.createHash("sha256");
+    hash.update(snapshot.branch || "");
+    hash.update(snapshot.head || "");
+    hash.update(snapshot.indexTree || "");
+    hash.update(snapshot.stagedDiffHash || "");
+    hash.update(snapshot.unstagedDiffHash || "");
+    hash.update(snapshot.untrackedFilesHash || "");
+
+    const sortedFiles = Object.keys(snapshot.files || {}).sort();
+    for (const file of sortedFiles) {
+      hash.update(file);
+      hash.update(snapshot.files[file].sha256);
+      hash.update(snapshot.files[file].mode);
+    }
+    return hash.digest("hex");
+  }
+}

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

@@ -76,66 +76,54 @@ export class BranchGate {
   }
 
   /**
-   * @param {string} override
-   * @param {{autoRecover?: boolean, taskSlug?: string, readOnly?: boolean}} options
+   * Strictly verifies branch safety without any override bypasses.
    */
-  check(override = "", { autoRecover = false, taskSlug = "implementation", readOnly = false } = {}) {
+  check(overrideIgnored = "", { taskSlug = "implementation", readOnly = false } = {}) {
     if (readOnly) {
       const currentBranch = this.getCurrentBranch();
       return { blocked: false, branch: currentBranch, recovered: false, readOnly: true };
     }
 
     try {
-      // Enforce fail-closed: verify inside worktree first
+      // 1. Verify inside worktree (Git availability)
       try {
         this.run("git rev-parse --is-inside-work-tree");
       } catch (e) {
-        const reason = "Not inside a Git repository or Git is unavailable. Implementation work is blocked.";
+        const reason = "Git is unavailable or not inside a Git repository. Implementation work is blocked.";
         this.log(`BLOCKED: ${reason}`);
         return { blocked: true, branch: "unknown", reason };
       }
 
+      // 2. Get current branch
       const currentBranch = this.getCurrentBranch();
-      if (currentBranch === "unknown") {
+      if (!currentBranch || currentBranch === "unknown" || currentBranch.trim() === "") {
         const reason = "Could not determine current Git branch name. Implementation work is blocked.";
         this.log(`BLOCKED: ${reason}`);
         return { blocked: true, branch: "unknown", reason };
       }
-      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 };
+      const isProtected = this.protectedBranches.includes(currentBranch);
+      if (!isProtected) {
+        return { blocked: false, branch: currentBranch, 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
-        };
+      // 3. Protected branch checks - any dirty file blocks
+      const dirty = this.getDirtyState();
+      if (!dirty.clean) {
+        const reason = `Direct writes to protected branch '${currentBranch}' are prohibited and the branch is dirty (has changes).`;
+        this.log(`BLOCKED: ${reason}`);
+        return { blocked: true, branch: currentBranch, reason, 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}`);
+      // 4. Create scoped branch (Auto-recover)
+      const recoveredBranch = this.createScopedBranch(taskSlug);
+      this.log(`AUTO-RECOVERED '${currentBranch}' -> '${recoveredBranch}'`);
       return {
-        blocked: true,
-        branch: currentBranch,
-        reason: `${reason} Enable safe auto-recovery or use AI_OVERRIDE with a concrete justification.`
+        blocked: false,
+        branch: recoveredBranch,
+        branchBefore: currentBranch,
+        recovered: true,
+        dirtyState: dirty
       };
     } catch (error) {
       const reason = `Git command failure on branch gate check: ${error.message}`;

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

@@ -36,11 +36,12 @@ function collectBlockingFindings(result = {}) {
 }
 
 export class HealerEngine {
-  constructor({ cwd, mode = "standard", taskSlug = "implementation", maxAttempts = null } = {}) {
+  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() {
@@ -139,6 +140,38 @@ export class HealerEngine {
 
       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,

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

@@ -0,0 +1,136 @@
+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/request-classifier.js

@@ -1,4 +1,5 @@
 import { resolveWorkflowProfile, getWorkflowProfile } from "./workflow-profiles.js";
+import { RequestRouter } from "./request-router.js";
 
 /**
  * RequestClassifier - Classifies natural requests into structured, testable contracts.
@@ -9,12 +10,14 @@ export class RequestClassifier {
    * @param {string} request - The natural language request string.
    * @returns {Object} Structured classification contract.
    */
-  classify(request = "") {
+  classify(request = "", options = {}) {
     const text = String(request).trim();
     if (!text) {
       throw new Error("Cannot classify an empty request.");
     }
 
+    const cwd = options.cwd || process.cwd();
+
     // 1. Resolve Profile
     const profile = resolveWorkflowProfile({ request: text });
     const profileDef = getWorkflowProfile(profile);
@@ -43,16 +46,23 @@ export class RequestClassifier {
     const specNeeded = mode === "full" && intent === "write";
     const validationNeeded = intent === "write";
 
+    // Integrate central RequestRouter
+    const router = new RequestRouter({ cwd });
+    const requestUnderstanding = router.understand(text);
+    const routingDecision = router.route(requestUnderstanding);
+
     return {
       request: text,
       profile,
-      owner: profileDef.owner,
-      intent,
+      owner: routingDecision.selectedActor || profileDef.owner,
+      intent: requestUnderstanding.mutationIntent === "readonly" ? "read-only" : "write",
       mode,
-      risk,
+      risk: requestUnderstanding.riskLevel,
       specNeeded,
       validationNeeded,
-      skills: [...profileDef.skills]
+      skills: [...profileDef.skills],
+      requestUnderstanding,
+      routingDecision
     };
   }
 }