@williambeto/ai-workflow 2.2.6 → 2.3.0

package/src/adapters/platforms/codex.js

@@ -87,6 +87,19 @@ Every task completion MUST provide the following payload:
       const content = await fs.readFile(path.join(sourceCommandsDir, file), "utf8");
       await fs.writeFile(path.join(codexPromptsDir, targetFileName), content);
     }
+
+    // 4. Copy governance policy into .agents/docs/policies/ so the relative
+    //    link ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md in each
+    //    .agents/skills/{skill}/SKILL.md resolves correctly.
+    const codexPoliciesDir = path.join(this.cwd, ".agents", "docs", "policies");
+    await fs.mkdir(codexPoliciesDir, { recursive: true });
+    const sourcePoliciesDir = path.join(this.cwd, installRoot, "opencode", "docs", "policies");
+    const policyFiles = await fs.readdir(sourcePoliciesDir).catch(() => []);
+    for (const file of policyFiles) {
+      if (!file.endsWith(".md")) continue;
+      const policyContent = await fs.readFile(path.join(sourcePoliciesDir, file), "utf8");
+      await fs.writeFile(path.join(codexPoliciesDir, file), policyContent);
+    }
   }
 
   async exists(p) {

package/src/adapters/platforms/gemini.js

@@ -150,7 +150,20 @@ Every task completion MUST provide the following payload:
       }
     }
 
-    // 4. Inject project settings.json
+    // 4. Copy governance policy into .gemini/docs/policies/ so the relative
+    //    link ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md in each
+    //    .gemini/skills/{skill}/SKILL.md resolves correctly.
+    const geminiPoliciesDir = path.join(geminiDir, "docs", "policies");
+    await fs.mkdir(geminiPoliciesDir, { recursive: true });
+    const sourcePoliciesDir = path.join(this.cwd, installRoot, "opencode", "docs", "policies");
+    const policyFiles = await fs.readdir(sourcePoliciesDir).catch(() => []);
+    for (const file of policyFiles) {
+      if (!file.endsWith(".md")) continue;
+      const content = await fs.readFile(path.join(sourcePoliciesDir, file), "utf8");
+      await fs.writeFile(path.join(geminiPoliciesDir, file), content);
+    }
+
+    // 5. Inject project settings.json
     const settingsPath = path.join(geminiDir, "settings.json");
     if (!(await this.exists(settingsPath))) {
       const settings = {

package/src/cli.js

@@ -11,7 +11,7 @@ function printHelp() {
 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] [--gemini] [--claude] [--codex] [--profile=<profile>]
+  ai-workflow init [--yes] [--force] [--dry-run] [--no-install] [--no-overwrite] [--gemini] [--claude] [--codex] [--antigravity] [--profile=<profile>]
   ai-workflow collect-evidence [--task=<slug>] [--mode=<quick|standard|full>] [--dry-run]
   ai-workflow doctor
 
@@ -46,6 +46,7 @@ function parseFlags(args) {
     gemini: args.includes("--gemini"),
     claude: args.includes("--claude"),
     codex: args.includes("--codex"),
+    antigravity: args.includes("--antigravity"),
     "dev-mode": args.includes("--dev-mode"),
     specPath: specPathArg ? specPathArg.replace("--spec-path=", "") : undefined,
     profile: profileVal || undefined,
@@ -73,12 +74,14 @@ export async function runCli(args) {
     const flags = parseFlags(args.slice(1));
     const positionals = args.slice(1).filter((arg) => !arg.startsWith("-"));
     const request = flags.request || positionals.join(" ");
-    await runExecute({
+    const result = await runExecute({
       cwd: process.cwd(),
       naturalRequest: request,
-      override: args.includes("--override") ? "authorized-override-token" : undefined,
       taskSlug: flags.taskSlug
     });
+    if (result && (result.overallStatus === "FAIL_QUALITY_GATE" || result.overallStatus === "BLOCKED" || result.overallStatus === "FAIL")) {
+      process.exit(1);
+    }
     return;
   }
 

package/src/commands/collect-evidence.js

@@ -1,50 +1,14 @@
 import { EvidenceCollector } from "../core/validation/evidence-collector.js";
 import { QualityGuard } from "../core/validation/quality-guard.js";
+import { ValidationPlanner } from "../core/validation/validation-planner.js";
 import { buildDeliverySummary, formatDeliverySummary } from "../core/validation/canonical-finalization.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 
-function isNoOpScript(script = "") {
-  const value = String(script).trim().toLowerCase();
-  return /^(echo\b|true$|exit\s+0$|node\s+-e\s+["']?console\.log)/.test(value) || value.includes("tests-pass");
-}
-
-function addScriptTask(tasks, scripts, name, command, { rejectNoOp = false } = {}) {
-  const script = scripts[name];
-  if (!script) return;
-  if (!rejectNoOp && name === "test" && isNoOpScript(script)) return;
-  if (rejectNoOp && isNoOpScript(script)) {
-    tasks.push({ name, command, kind: name === "test" ? "test" : name, presetStatus: "FAIL_QUALITY_GATE", summary: `Configured ${name} script is a no-op: ${script}` });
-    return;
-  }
-  tasks.push({ name, command, kind: name === "test" ? "test" : name });
-}
-
-function isManagedValidationPath(file = "") {
-  return /(^|\/)(node_modules|vendor|dist|coverage|\.cache)(\/|$)/.test(String(file).replaceAll("\\", "/"));
-}
-
 export async function runCollectEvidence({ cwd, exitOnError = true, taskSlug = null, mode = null, dryRun = false, profile = "generic", branchRecovery = "NOT_RECORDED" }) {
-  const tasks = [];
   const qualityGuard = new QualityGuard({ cwd, taskSlug, mode });
-  try {
-    const pkg = JSON.parse(await fs.readFile(path.join(cwd, "package.json"), "utf8"));
-    const scripts = pkg.scripts || {};
-    const executableBehavior = await qualityGuard.hasExecutableBehaviorChanges();
-    addScriptTask(tasks, scripts, "lint", "npm run lint");
-    addScriptTask(tasks, scripts, "test", "npm test", { rejectNoOp: executableBehavior });
-    addScriptTask(tasks, scripts, "build", "npm run build");
-    addScriptTask(tasks, scripts, "typecheck", "npm run typecheck");
-    if (scripts.validate && !String(scripts.validate).includes("ai-workflow collect-evidence")) addScriptTask(tasks, scripts, "validate", "npm run validate");
-
-    const changed = qualityGuard.getChangedFiles().filter((file) => !isManagedValidationPath(file));
-    const hasTs = changed.some((file) => /\.(ts|tsx)$/.test(file)) || await fs.access(path.join(cwd, "tsconfig.json")).then(() => true).catch(() => false);
-    if (hasTs && !scripts.typecheck) {
-      tasks.push({ name: "typecheck", command: "npm run typecheck", kind: "typecheck", presetStatus: "FAIL_QUALITY_GATE", summary: "TypeScript detected but no typecheck script is configured." });
-    }
-  } catch {
-    // Non-Node projects can still supply validation through project-specific commands.
-  }
+  const planner = new ValidationPlanner({ cwd, qualityGuard });
+  const tasks = await planner.plan(profile);
 
   const persist = !dryRun && mode === "full";
   const collector = new EvidenceCollector({ cwd, timeout: 60000, taskSlug, mode, profile, branchRecovery });

package/src/commands/doctor.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { exists, readJson, readJsonc } from "../core/filesystem.js";
+import { OpenCodeAdapter } from "../core/runtime/opencode-adapter.js";
 
 const REQUIRED_FILES = [
   ".ai-workflow",
@@ -23,6 +24,21 @@ export async function runDoctor({ cwd }) {
 
   console.log("Doctor report:");
 
+  // Check OpenCode runtime
+  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"}`);
+  } 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(path.join(cwd, relativePath));
 

package/src/commands/execute.js

@@ -2,15 +2,89 @@ import { RequestClassifier } from "../core/request-classifier.js";
 import { ExecutionPlanner } from "../core/execution-planner.js";
 import { WorkflowStateMachine } from "../core/workflow-state-machine.js";
 import { BranchGate } from "../core/gates/branch-gate.js";
+import { EvidenceLedger } from "../core/evidence/evidence-ledger.js";
+import { DelegationController } from "../core/delegation-controller.js";
 import { OpenCodeAdapter } from "../core/runtime/opencode-adapter.js";
 import { runCollectEvidence } from "./collect-evidence.js";
 import { QualityGuard } from "../core/validation/quality-guard.js";
 import { HandoffEngine } from "../core/handoff/handoff-engine.js";
 import { HealerEngine } from "../core/healing/healer-engine.js";
-import { createCliRemediationExecutor } from "../core/healing/cli-remediation-executor.js";
+import { createRuntimeRemediationExecutor } from "../core/healing/runtime-remediation-executor.js";
 import { isRecoverableGateFailure, isTerminalFailure } from "../core/statuses.js";
+import { Finalizer } from "../core/finalization/finalizer.js";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { execSync } from "node:child_process";
+
+async function captureReadOnlyState(cwd) {
+  const finalizer = new Finalizer({ cwd });
+  const snapshot = await finalizer.snapshotManager.capture();
+  
+  const execGit = (args) => {
+    try {
+      return execSync(`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 = [];
+
+  // 1. Compare branch
+  if (before.branch !== after.branch) {
+    violations.push(`Branch changed from '${before.branch}' to '${after.branch}'`);
+  }
+
+  // 2. Compare HEAD
+  if (before.head !== after.head) {
+    violations.push(`Git HEAD changed from '${before.head}' to '${after.head}' (commit or reset made inside read-only task)`);
+  }
+
+  // 3. Compare index tree
+  if (before.indexTree !== after.indexTree) {
+    violations.push(`Git index tree changed from '${before.indexTree}' to '${after.indexTree}'`);
+  }
+
+  // 4. Compare porcelain status
+  if (before.porcelainStatus !== after.porcelainStatus) {
+    violations.push(`Git status changed. Before:\n${before.porcelainStatus}\nAfter:\n${after.porcelainStatus}`);
+  }
+
+  // 5. Compare workspace files (SHA-256 hashes)
+  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
@@ -34,7 +108,7 @@ function combineValidation(evidence, quality) {
 /**
  * runExecute - Coordinators natural request execution.
  */
-export async function runExecute({ cwd, naturalRequest, override, taskSlug: taskSlugOverride }) {
+export 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.");
   }
@@ -42,131 +116,241 @@ export async function runExecute({ cwd, naturalRequest, override, taskSlug: task
   const taskSlug = taskSlugOverride || slugify(naturalRequest);
   console.log(`\n[AI WORKFLOW] Executing natural request intake [slug: ${taskSlug}]...\n`);
 
-  const stateMachine = new WorkflowStateMachine();
-
-  // 1. Classification
-  const classifier = new RequestClassifier();
-  const classification = classifier.classify(naturalRequest);
-  console.log(`[CLASSIFIED] Intent: ${classification.intent}, Mode: ${classification.mode}, Profile: ${classification.profile}`);
-  stateMachine.transitionTo("CLASSIFIED");
-
-  // 2. Planning
-  const planner = new ExecutionPlanner({ cwd });
-  const plan = planner.plan(classification, taskSlug);
-  console.log(`[PLANNED] Owner: ${plan.owner}, Remediation limit: ${plan.remediationLimit}`);
-  stateMachine.transitionTo("PLANNED");
-
-  // 3. Branch Gate
-  const branchGate = new BranchGate({ memoryDir: path.join(cwd, ".ai-workflow"), cwd });
-  const gateResult = branchGate.check(override, {
-    autoRecover: true,
-    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");
-
-  // 4. Spec template creation (for full/deep mode)
-  if (plan.specPath) {
-    const fullSpecPath = path.join(cwd, plan.specPath);
-    const specExists = await fs.access(fullSpecPath).then(() => true).catch(() => false);
-    if (!specExists) {
-      await fs.mkdir(path.dirname(fullSpecPath), { recursive: true });
-      const specTemplatePath = path.join(cwd, ".ai-workflow/templates/specs/standard.md");
-      const templateContent = await fs.readFile(specTemplatePath, "utf8").catch(() => {
-        return `# [STANDARD] Specification: ${classification.request}\n\n## Metadata\n\n- ID: SPEC-${taskSlug}\n- Author: Spec-Engineer\n- Status: DRAFT\n- Date: ${new Date().toISOString().split("T")[0]}\n\n## Functional Requirements\n\n- ${classification.request}\n\n## Technical Implementation Plan\n\n### Files to Create/Modify\n\n- \`src/index.js\`\n\n## Acceptance Criteria\n\n- [ ] Implemented successfully\n\n## Testing Strategy\n\n- [ ] Behavior tests pass`;
-      });
-      await fs.writeFile(fullSpecPath, templateContent);
-      console.log(`[EXECUTE] Created DRAFT specification template at: ${plan.specPath}`);
-    }
-  }
+  const ledger = new EvidenceLedger({ cwd, workflowId: taskSlug });
+  const delegationController = new DelegationController({ cwd, ledger, adapter: new OpenCodeAdapter({ cwd }) });
 
-  // 5. Delegation
-  stateMachine.transitionTo("DELEGATED");
-  stateMachine.transitionTo("IMPLEMENTING");
+  let plan = null;
+  try {
+    const stateMachine = new WorkflowStateMachine();
 
-  const adapter = new OpenCodeAdapter({ cwd });
-  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.`;
-  }
+    // 1. Classification
+    const classifier = new RequestClassifier();
+    const classification = classifier.classify(naturalRequest);
+    console.log(`[CLASSIFIED] Intent: ${classification.intent}, Mode: ${classification.mode}, Profile: ${classification.profile}`);
+    stateMachine.transitionTo("CLASSIFIED");
 
-  const runResult = await adapter.execute(promptMsg, {
-    agent: plan.owner,
-    dangerouslySkipPermissions: true
-  });
+    await delegationController.route(naturalRequest, classification);
 
-  if (!runResult.success) {
-    console.error(`[EXECUTE] OpenCode adapter execution reported failure.`);
-  }
-  stateMachine.transitionTo("IMPLEMENTED");
-
-  // 6. Validation
-  stateMachine.transitionTo("VALIDATING");
-  const validateWorkflow = async () => {
-    const evidence = await runCollectEvidence({
-      cwd,
-      exitOnError: false,
+    // 2. Planning
+    const planner = new ExecutionPlanner({ cwd });
+    plan = planner.plan(classification, taskSlug);
+    console.log(`[PLANNED] Owner: ${plan.owner}, Remediation limit: ${plan.remediationLimit}`);
+    stateMachine.transitionTo("PLANNED");
+
+    // 3. Branch Gate
+    const branchGate = new BranchGate({ memoryDir: path.join(cwd, ".ai-workflow"), cwd });
+    const gateResult = branchGate.check(undefined, {
+      autoRecover: true,
       taskSlug,
-      mode: plan.mode,
-      profile: plan.profile,
-      branchRecovery: gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : "NOT_REQUIRED"
+      readOnly: !plan.branchNeeded
     });
-    const quality = await new QualityGuard({ cwd, taskSlug, mode: plan.mode }).verify();
-    return combineValidation(evidence, quality);
-  };
 
-  let result = await validateWorkflow();
-
-  // 7. Bounded Remediation
-  if (isRecoverableGateFailure(result.overallStatus)) {
-    stateMachine.transitionTo("REMEDIATING");
-    console.log(`\n[REMEDIATION REQUIRED] ${result.overallStatus}. Starting bounded ${plan.mode} remediation.`);
-    const executor = createCliRemediationExecutor(cwd);
-    const healer = new HealerEngine({ cwd, mode: plan.mode, taskSlug });
-    
-    result = await healer.run({
-      initialResult: result,
-      validate: async () => {
-        stateMachine.transitionTo("REVALIDATING");
-        const res = await validateWorkflow();
-        return res;
-      },
-      remediate: executor
+    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");
+
+    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}'!`);
+        }
+      }
+    };
+
+    // 4. Spec template creation (for full/deep mode)
+    if (plan.specPath) {
+      const fullSpecPath = path.join(cwd, plan.specPath);
+      const specExists = await fs.access(fullSpecPath).then(() => true).catch(() => false);
+      if (!specExists) {
+        await fs.mkdir(path.dirname(fullSpecPath), { recursive: true });
+        const specTemplatePath = path.join(cwd, ".ai-workflow/templates/specs/standard.md");
+        const templateContent = await fs.readFile(specTemplatePath, "utf8").catch(() => {
+          return `# [STANDARD] Specification: ${classification.request}\n\n## Metadata\n\n- ID: SPEC-${taskSlug}\n- Author: Spec-Engineer\n- Status: DRAFT\n- Date: ${new Date().toISOString().split("T")[0]}\n\n## Functional Requirements\n\n- ${classification.request}\n\n## Technical Implementation Plan\n\n### Files to Create/Modify\n\n- \`src/index.js\`\n\n## Acceptance Criteria\n\n- [ ] Implemented successfully\n\n## Testing Strategy\n\n- [ ] Behavior tests pass`;
+        });
+        await fs.writeFile(fullSpecPath, templateContent);
+        console.log(`[EXECUTE] Created DRAFT specification template at: ${plan.specPath}`);
+      }
+    }
+
+    // 5. Delegation
+    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.`;
+    }
+
+    let readOnlyStateBefore = null;
+    if (!plan.branchNeeded) {
+      readOnlyStateBefore = await captureReadOnlyState(cwd);
+    }
+
+    const runResult = await delegationController.implement(promptMsg, plan.owner, { readOnly: !plan.branchNeeded });
+
+    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"}`);
+    }
+
+    if (!plan.branchNeeded) {
+      const readOnlyStateAfter = await captureReadOnlyState(cwd);
+      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: \n${violations.join("\n")}`);
+      }
+
+      stateMachine.transitionTo("IMPLEMENTED");
+      stateMachine.transitionTo("VALIDATING");
+      stateMachine.transitionTo("COMPLETED");
+
+      console.log("\n--- Final Handoff ---");
+      console.log(`\n[AI WORKFLOW COMPLETE] COMPLETED`);
+      console.log(`Handoff Packet: [IN-MEMORY] (No handoff file written in read-only mode)\n`);
+
+      return {
+        overallStatus: "PASS",
+        evidence: {
+          internalStatus: "PASS",
+          commandsRun: []
+        },
+        quality: {
+          overallStatus: "PASS"
+        },
+        stateHistory: stateMachine.getHistory()
+      };
+    }
+
+    stateMachine.transitionTo("IMPLEMENTED");
+    checkBranchSafety();
+
+    // Capture snapshot immediately after last implementation write
+    const finalizer = new Finalizer({ cwd });
+    let lastWriteSnapshot = await finalizer.snapshotManager.capture();
+
+    // 6. Validation
+    stateMachine.transitionTo("VALIDATING");
+    const validateWorkflow = async () => {
+      const evidence = await runCollectEvidence({
+        cwd,
+        exitOnError: false,
+        taskSlug,
+        mode: plan.mode,
+        profile: plan.profile,
+        branchRecovery: gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : "NOT_REQUIRED"
+      });
+      const quality = await new QualityGuard({ cwd, taskSlug, mode: plan.mode }).verify();
+      return combineValidation(evidence, quality);
+    };
+
+    let result = await delegationController.validate(taskSlug, plan.mode, plan.profile, validateWorkflow);
+
+    // 7. Bounded Remediation
+    if (isRecoverableGateFailure(result.overallStatus)) {
+      console.log(`\n[REMEDIATION REQUIRED] ${result.overallStatus}. Starting bounded ${plan.mode} remediation.`);
+      const executor = createRuntimeRemediationExecutor(cwd, ledger);
+      const healer = new HealerEngine({ cwd, mode: plan.mode, taskSlug, ledger });
+      
+      result = await healer.run({
+        initialResult: result,
+        validate: async () => {
+          stateMachine.transitionTo("REVALIDATING");
+          const res = await delegationController.validate(taskSlug, plan.mode, plan.profile, validateWorkflow);
+          return res;
+        },
+        remediate: async (remedCtx) => {
+          stateMachine.transitionTo("REMEDIATING");
+          const remRes = await executor(remedCtx);
+          if (remRes.applied) {
+            checkBranchSafety();
+            // Update snapshot because remediation wrote new changes
+            lastWriteSnapshot = await finalizer.snapshotManager.capture();
+          }
+          return remRes;
+        }
+      });
+    }
+
+    if (isTerminalFailure(result.overallStatus)) {
+      stateMachine.transitionTo("BLOCKED");
+      throw new Error(`[WORKFLOW BLOCKED] ${result.overallStatus}: Validation could not be resolved safely.`);
+    }
+
+    checkBranchSafety();
+
+    // 8. Finalizer / Stabilization Loop
+    let integrity = await finalizer.verifyIntegrity(lastWriteSnapshot);
+    let revalidationCount = 0;
+    const maxRevalidations = 2;
+
+    while (!integrity.valid && revalidationCount < maxRevalidations) {
+      console.log(`\n[FINALIZER WARNING] Workspace mutated during validation! Re-running validation to stabilize.`);
+      console.log(`Changes detected:`, integrity.changes);
+
+      checkBranchSafety();
+
+      // Update snapshot to current workspace state before validation runs
+      lastWriteSnapshot = await finalizer.snapshotManager.capture();
+      revalidationCount++;
+
+      // Re-run validation
+      result = await delegationController.validate(taskSlug, plan.mode, plan.profile, validateWorkflow);
+
+      checkBranchSafety();
+
+      // Verify integrity against the snapshot taken before this validation iteration
+      integrity = await finalizer.verifyIntegrity(lastWriteSnapshot);
+    }
+
+    let finalStatus = result.overallStatus;
+    if (!integrity.valid) {
+      console.log(`\n[FINALIZER BLOCKED] BLOCKED: workspace did not stabilize`);
+      console.log(`Final changes detected:`, integrity.changes);
+      finalStatus = "FAIL_QUALITY_GATE";
+    }
+
+    const finalState = finalStatus === "PASS"
+      ? "COMPLETED"
+      : finalStatus === "PASS_WITH_NOTES"
+        ? "COMPLETED_WITH_NOTES"
+        : "BLOCKED";
+
+    stateMachine.transitionTo(finalState);
+
+    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: result.evidence,
+      nextActions: `Profile ${plan.profile}. Observed execution completed with status ${finalState}.`
     });
-  }
 
-  if (isTerminalFailure(result.overallStatus)) {
-    stateMachine.transitionTo("BLOCKED");
-    throw new Error(`[WORKFLOW BLOCKED] ${result.overallStatus}: Validation could not be resolved safely.`);
-  }
+    console.log(`\n[AI WORKFLOW COMPLETE] ${finalState}`);
+    console.log(`Handoff Packet: ${path.relative(cwd, handoffPath)}\n`);
 
-  // 8. Finalizer
-  const finalState = result.overallStatus === "PASS"
-    ? "COMPLETED"
-    : result.overallStatus === "PASS_WITH_NOTES"
-      ? "COMPLETED_WITH_NOTES"
-      : "BLOCKED";
-
-  stateMachine.transitionTo(finalState);
-
-  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: result.evidence,
-    nextActions: `Profile ${plan.profile}. Observed execution completed with status ${finalState}.`
-  });
-
-  console.log(`\n[AI WORKFLOW COMPLETE] ${finalState}`);
-  console.log(`Handoff Packet: ${path.relative(cwd, handoffPath)}\n`);
-
-  return { ...result, stateHistory: stateMachine.getHistory() };
+    return { ...result, overallStatus: finalStatus, stateHistory: stateMachine.getHistory() };
+  } finally {
+    if (typeof plan !== "undefined" && plan && !plan.branchNeeded) {
+      console.log(`\n[READ-ONLY LEDGER] (In-Memory/Stdout)\n${JSON.stringify(ledger.getEvents(), null, 2)}\n`);
+    } else {
+      try {
+        await ledger.save(`.ai-workflow/history/${taskSlug}-ledger.json`);
+      } catch (err) {
+        // ignore or log
+      }
+    }
+  }
 }