@williambeto/ai-workflow 2.2.7 → 2.3.0

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
+      }
+    }
+  }
 }

package/src/core/delegation-controller.js

@@ -0,0 +1,134 @@
+import { OpenCodeAdapter } from "./runtime/opencode-adapter.js";
+
+/**
+ * DelegationController - Manages and logs coordination between Atlas, Astra, Sage, and Phoenix.
+ */
+export class DelegationController {
+  constructor({ cwd = process.cwd(), ledger, adapter } = {}) {
+    this.cwd = cwd;
+    this.ledger = ledger;
+    this.adapter = adapter || new OpenCodeAdapter({ cwd });
+  }
+
+  /**
+   * Logs routing decision by Atlas.
+   */
+  async route(naturalRequest, classification) {
+    if (this.ledger) {
+      this.ledger.logEvent({
+        actor: "Atlas",
+        actorType: "control-plane",
+        observed: true,
+        eventType: "routing",
+        provenance: "request-classifier",
+        data: {
+          request: naturalRequest,
+          classification,
+          event: "routing.completed"
+        }
+      });
+    }
+  }
+
+  /**
+   * Logs and executes the implementation process by Astra.
+   */
+  async implement(promptMsg, owner, options = {}) {
+    if (this.ledger) {
+      this.ledger.logEvent({
+        actor: owner,
+        actorType: "runtime-agent",
+        observed: true,
+        runtime: "opencode",
+        eventType: "implementation_start",
+        provenance: "opencode-adapter",
+        data: {
+          agent: owner,
+          prompt: promptMsg,
+          event: "implementation.started"
+        }
+      });
+    }
+
+    const runResult = await this.adapter.execute(promptMsg, { agent: owner, ...options });
+
+    if (this.ledger) {
+      this.ledger.logEvent({
+        actor: owner,
+        actorType: "runtime-agent",
+        observed: true,
+        runtime: "opencode",
+        eventType: "implementation_complete",
+        provenance: "opencode-adapter",
+        data: {
+          success: runResult.success,
+          commandsRun: runResult.commandsRun || [],
+          eventCount: runResult.eventCount || 0,
+          error: runResult.error,
+          event: "implementation.completed"
+        }
+      });
+    }
+
+    return runResult;
+  }
+
+  /**
+   * Runs validation locally without logging Sage since no validation agent runtime was executed.
+   */
+  async validate(taskSlug, mode, profile, verifyFn) {
+    const result = await verifyFn();
+
+    if (mode === "full") {
+      if (this.ledger) {
+        this.ledger.logEvent({
+          actor: "Sage",
+          actorType: "auditor",
+          observed: true,
+          runtime: "opencode",
+          eventType: "validation_start",
+          provenance: "opencode-adapter",
+          data: {
+            agent: "Sage",
+            event: "validation.started"
+          }
+        });
+      }
+
+      let gitDiff = "";
+      try {
+        const { execSync } = await import("node:child_process");
+        gitDiff = execSync("git diff HEAD", { cwd: this.cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+      } catch {
+        // ignore
+      }
+
+      const prompt = `Please validate the implementation. Diff:\n${gitDiff}\nLocal Evidence:\n${JSON.stringify(result, null, 2)}`;
+      const runResult = await this.adapter.execute(prompt, { agent: "Sage" });
+
+      if (this.ledger) {
+        this.ledger.logEvent({
+          actor: "Sage",
+          actorType: "auditor",
+          observed: true,
+          runtime: "opencode",
+          eventType: "validation_complete",
+          provenance: "opencode-adapter",
+          data: {
+            success: runResult.success,
+            commandsRun: runResult.commandsRun || [],
+            eventCount: runResult.eventCount || 0,
+            error: runResult.error,
+            event: "validation.completed"
+          }
+        });
+      }
+
+      if (!runResult.success) {
+        result.overallStatus = "FAIL_QUALITY_GATE";
+      }
+    }
+
+    return result;
+  }
+}

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,10 @@ export class ExecutionPlanner {
       ? path.join("docs/workflows", taskSlug, "spec.md")
       : null;
 
+    const owner = classification.intent === "write"
+      ? "Astra"
+      : classification.owner;
+
     // Build default expected validations based on the resolved profile
     const validationsExpected = [];
     if (classification.validationNeeded) {
@@ -45,7 +49,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,