@williambeto/ai-workflow 2.8.0 → 2.8.2

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 ## [unreleased]
 
+## [2.8.1] - 2026-07-14
+
+### 🐛 Bug Fixes
+
+- Route natural workspace mutations to Astra instead of stopping after a
+  specialist prints code
+- Keep Phoenix limited to bounded remediation of observed findings
+- Require execution-scoped repository changes and proportional validation for
+  successful workspace delivery
+- Preserve explicit read-only, preview, already-satisfied, clarification, and
+  non-delivery outcomes without manufacturing changes
+- Prevent natural phrases such as `next step` from being interpreted as a
+  Next.js stack request
+- Propagate observed OpenCode commands to the evidence ledger and derive test
+  actions from the delivered diff
+- Prevent duplicate finalization and require exactly one observed Astra
+  delegation in the OpenCode fallback path
+- Route mixed inspection-and-change requests to Astra whenever the request has
+  write intent
+- Allow read-only Git, `sed`, and `awk` inspection while continuing to block
+  mutations, and exclude ignored build artifacts from delivery deltas
+- Keep validation proportional for documentation, simple code, backend scripts,
+  and React applications while retaining blocking build requirements for UI
+
+### 🧪 Testing
+
+- Cover routing ownership, delivery outcomes, answer-only confinement, project
+  context compatibility, execution delta attribution, and generated OpenCode
+  permissions through reusable invariants
+- Keep pre-existing dirty work from satisfying delivery or test-action evidence
+- Validate the corrected workflow with a real GPT-5.6 Sol OpenCode delivery and
+  record GPT-5.3 Codex Spark medium as experimental after observed incomplete
+  delivery was correctly blocked
+
+### 📚 Documentation
+
+- Align Atlas, quickstart, ownership, runtime-flow, evidence, and skill
+  governance documentation with the natural-request delivery contract
+- Document the distinction between CLI-enforced gates and model-qualified
+  direct Atlas sessions
+
 ## [2.8.0] - 2026-07-14
 
 ### 🚀 Features

package/bin/ai-workflow.js

@@ -21,7 +21,7 @@ import {
   isTerminalFailure,
   readPackageFile,
   resolveWorkflowProfile
-} from "../chunk-LI76KI7C.js";
+} from "../chunk-4FI5ODAM.js";
 import {
   EvidenceValidator,
   require_ajv,
@@ -30,9 +30,12 @@ import {
 import {
   EvidenceCollector,
   QualityGuard,
-  ValidationPlanner
-} from "../chunk-Y4RLP6ZM.js";
-import "../chunk-XW747GIG.js";
+  ValidationPlanner,
+  parseDeliveryOutcomeClaim
+} from "../chunk-GLYX3HEY.js";
+import {
+  DeliveryDecisionEngine
+} from "../chunk-H7GIKXFO.js";
 import {
   createManagedBackup,
   createManagedPathBackup
@@ -726,34 +729,34 @@ async function readJsonc(filePath) {
 import path3 from "path";
 var LEGACY_MARKER = "_aiWorkflowManaged";
 var 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" }
+  Atlas: { description: "Router and workflow coordinator for AI Workflow Kit", mode: "primary" },
+  Nexus: { description: "Discovery, requirement, scope, and specification owner", mode: "all" },
+  Orion: { description: "Planning, PR sequencing, release, and deployment strategy owner", mode: "all" },
+  Astra: { description: "Implementation owner for incremental, scoped workspace changes", mode: "all" },
+  Sage: { description: "Audit, validation, evidence, and quality gate owner", mode: "all" },
+  Phoenix: { description: "Bounded remediation and regression recovery owner", mode: "all" }
 };
 var 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" }
+  "Architecture-Specialist": { description: "Capability only: advise on the simplest safe architecture for current requirements", skill: "architecture" },
+  "Backend-Engineer": { description: "Capability only: advise on PHP, Node, or Python APIs and persistence", skill: "backend-development" },
+  "Deployment-Specialist": { description: "Capability only: analyze deployment, release, and production readiness", skill: "deployment" },
+  "Design-Specialist": { description: "Capability only: advise on simple and maintainable design principles", skill: "design-principles" },
+  "Docs-Engineer": { description: "Capability only: advise on documentation, READMEs, guides, and prompts", skill: "documentation" },
+  "Frontend-Engineer": { description: "Capability only: advise on UI, state, routing, and accessibility", skill: "frontend-development" },
+  "Frontend-Design-System-Specialist": { description: "Capability only: review CSS and HTML tokens, semantics, typography, and visual quality", skill: "frontend-design-system" },
+  "Full-Stack-Engineer": { description: "Capability only: analyze frontend and backend integration as one testable increment", skill: "full-stack-development" },
+  "Token-Economist": { description: "Capability only: analyze context size while preserving safe execution information", skill: "optimize-tokens" },
+  "PR-Manager": { description: "Capability only: plan or review small pull requests while preserving scope", skill: "pr-workflow" },
+  "Discovery-Analyst": { description: "Capability only: clarify ambiguous requests into actionable outcomes", skill: "product-discovery" },
+  "Product-Planner": { description: "Capability only: shape clarified needs into scoped requirements", skill: "product-planning" },
+  "Memory-Guardian": { description: "Capability only: advise on durable project decisions and recurring corrections", skill: "project-memory" },
+  "Prompt-Engineer": { description: "Capability only: advise on prompts for agents and workflows", skill: "prompt-engineer" },
+  "QA-Engineer": { description: "Capability only: design or review tests, acceptance criteria, and validation evidence", skill: "qa-workflow" },
+  "Refactoring-Specialist": { description: "Capability only: review structure and behavior-preserving simplifications", skill: "refactoring" },
+  "Release-Specialist": { description: "Capability only: analyze release readiness with explicit gates and evidence", skill: "release-workflow" },
+  "SDD-Specialist": { description: "Capability only: shape approved requirements into testable specifications", skill: "spec-driven-development" },
+  "Technical-Leader": { description: "Capability only: analyze technical decisions, architecture, and trade-offs", skill: "technical-leadership" },
+  "UI-UX-Engineer": { description: "Capability only: review usability and interface clarity", skill: "ui-ux-design" }
 };
 var COMMANDS = {
   atlas: { description: "Decide safest next step and delegate to the appropriate workflow or agent", agent: "Atlas" },
@@ -773,18 +776,36 @@ var COMMANDS = {
 };
 function buildManagedConfig() {
   const agent = {};
+  const coreTaskPermissions = Object.fromEntries([
+    ["*", "deny"],
+    ...Object.keys(AGENTS).filter((name) => name !== "Atlas").map((name) => [name, "allow"])
+  ]);
+  const capabilityTaskPermissions = Object.fromEntries([
+    ["*", "deny"],
+    ...Object.keys(SUBAGENTS).map((name) => [name, "allow"])
+  ]);
   for (const [name, def] of Object.entries(AGENTS)) {
     agent[name] = {
-      mode: "primary",
+      mode: def.mode,
       description: def.description,
-      prompt: `{file:./.ai-workflow/opencode/agents/${name.toLowerCase()}.md}`
+      prompt: `{file:./.ai-workflow/opencode/agents/${name.toLowerCase()}.md}`,
+      permission: {
+        ...name === "Atlas" ? { edit: "deny", bash: "ask" } : {},
+        ...name === "Astra" ? { edit: "allow" } : {},
+        task: name === "Atlas" ? coreTaskPermissions : capabilityTaskPermissions
+      }
     };
   }
   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}`
+      prompt: `{file:./.ai-workflow/opencode/skills/${def.skill}/SKILL.md}`,
+      permission: {
+        edit: "deny",
+        bash: "ask",
+        task: { "*": "deny" }
+      }
     };
   }
   const command = {};
@@ -2079,7 +2100,7 @@ function buildDeliverySummary({ evidence }) {
   return {
     Status: evidence?.status || "BLOCKED",
     Branch: evidence?.branch || "unknown",
-    Changes: (evidence?.changedFiles || []).join(", ") || "No changed files recorded",
+    Changes: (evidence?.deliveryChangedFiles || evidence?.changedFiles || []).join(", ") || "No changed files recorded",
     Validation: commands,
     "Known limitations": (evidence?.limitations || []).join("; ") || "None recorded"
   };
@@ -2114,12 +2135,40 @@ async function runCollectEvidence({
   explicitApprovals = [],
   visualDist = null,
   port = null,
-  workflowEvidence = null
+  workflowEvidence = null,
+  claimedOutcome = null,
+  deliveryChangedFiles = null,
+  deliveryAddedFiles = null,
+  deliveryDeletedFiles = null
 }) {
+  if (process.env.AI_WORKFLOW_FINALIZATION_OWNER === "execute") {
+    console.log("[FINALIZATION DEFERRED] Parent ai-workflow execute process owns canonical finalization.");
+    return { status: "DEFERRED_TO_ORCHESTRATOR", internalStatus: "DEFERRED", commands: [] };
+  }
   const policies = resolvePoliciesFromLegacyMode(mode, evidencePolicy);
-  const qualityGuard = new QualityGuard({ cwd, taskSlug, evidencePolicy: policies.evidencePolicy, riskLevel: policies.riskLevel });
+  const workspaceGuard = new QualityGuard({ cwd, taskSlug, evidencePolicy: policies.evidencePolicy, riskLevel: policies.riskLevel });
+  const observedDeliveryFiles = deliveryChangedFiles ?? workspaceGuard.getChangedFiles();
+  const qualityGuard = new QualityGuard({
+    cwd,
+    taskSlug,
+    evidencePolicy: policies.evidencePolicy,
+    riskLevel: policies.riskLevel,
+    scopedChangedFiles: observedDeliveryFiles
+  });
   const planner = new ValidationPlanner({ cwd, qualityGuard });
-  const tasks = await planner.plan(profile);
+  const tasks = await planner.plan(profile, {
+    requireObservedValidation: claimedOutcome === "ALREADY_SATISFIED" && observedDeliveryFiles.length === 0
+  });
+  const docs = observedDeliveryFiles.filter((file) => /(^|\/)(docs?|readme|changelog)|\.md$/i.test(file));
+  if (tasks.length === 0 && docs.length > 0 && docs.length === observedDeliveryFiles.length) {
+    tasks.push({
+      name: "docs-integrity",
+      command: ["aiwk", "internal", "docs-integrity"],
+      kind: "lint",
+      internal: "document-integrity",
+      files: docs
+    });
+  }
   const persist = !dryRun && policies.evidencePolicy === "required";
   const collector = new EvidenceCollector({
     cwd,
@@ -2132,7 +2181,12 @@ async function runCollectEvidence({
     explicitApprovals,
     visualDist,
     port: port || 8080,
-    workflowEvidence
+    workflowEvidence,
+    claimedOutcome,
+    deliveryChangedFiles: observedDeliveryFiles,
+    deliveryAddedFiles,
+    deliveryDeletedFiles,
+    riskLevel: policies.riskLevel
   });
   const evidence = await collector.collect(tasks, { writeArtifact: persist });
   const summary = buildDeliverySummary({ evidence });
@@ -2592,6 +2646,9 @@ async function runDeepImplementation(cwd, absoluteSpecPath, specPath, approvalPa
   };
 }
 async function runMasterOrchestrator({ cwd, specPath, approvalPath, override, remediationExecutor = null }) {
+  if (process.env.AI_WORKFLOW_FINALIZATION_OWNER === "execute") {
+    throw new Error("[NESTED EXECUTION BLOCKED] The parent execute process owns orchestration and finalization.");
+  }
   console.log("\n[AI WORKFLOW] Starting evidence-backed orchestration...\n");
   const branchGate = new BranchGate({ memoryDir: path14.join(cwd, ".ai-workflow"), cwd });
   const taskSlug = specPath ? normalizeTaskSlugFromSpec(specPath) : "implementation";
@@ -2801,6 +2858,19 @@ Please inspect the code, identify the root cause of these failures (e.g. failing
 import fs14 from "fs/promises";
 import path16 from "path";
 import { execSync as execSync4 } from "child_process";
+var INTEGRITY_METADATA_CHANGES = /* @__PURE__ */ new Set(["stagedDiff", "unstagedDiff", "untrackedFiles"]);
+function extractDeliveryChangedFiles(integrity) {
+  const files = /* @__PURE__ */ new Set();
+  for (const file of integrity.changes.added) files.add(file);
+  for (const file of integrity.changes.deleted) files.add(file);
+  for (const change of integrity.changes.modified) {
+    if (change.startsWith("branch:") || change.startsWith("head:")) continue;
+    if (INTEGRITY_METADATA_CHANGES.has(change)) continue;
+    if (change.startsWith("indexTree:")) continue;
+    files.add(change);
+  }
+  return [...files].sort();
+}
 async function captureReadOnlyState(cwd, fastTrack = false) {
   const finalizer = new Finalizer({ cwd, fastTrack });
   const snapshot = await finalizer.snapshotManager.capture();
@@ -2888,6 +2958,13 @@ async function classifyAndPlanExecution(naturalRequest, cwd, taskSlug, delegatio
   const plan = planner.plan(classification, taskSlug);
   console.log(`[PLANNED] Owner: ${plan.owner}, Remediation limit: ${plan.remediationLimit}`);
   stateMachine.transitionTo("PLANNED");
+  if (classification.requestUnderstanding.deliveryMode === "workspace") {
+    const deliveryDecision = await new DeliveryDecisionEngine({ cwd }).determineDecision({ userRequest: naturalRequest });
+    if (deliveryDecision.decision.startsWith("BLOCK_")) {
+      stateMachine.transitionTo("BLOCKED");
+      throw new Error(`[CONTEXT BLOCKED] NEEDS_CLARIFICATION: ${deliveryDecision.reason || deliveryDecision.decision}`);
+    }
+  }
   return { plan, classification };
 }
 function runBranchGate(plan, taskSlug, cwd, stateMachine, branchGate) {
@@ -3026,7 +3103,21 @@ async function runImplementation(plan, classification, delegationController, sta
   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.`;
   }
-  const runResult = await delegationController.implement(promptMsg, plan.owner, { readOnly: !plan.branchNeeded, fastTrack });
+  if (plan.branchNeeded) {
+    promptMsg = [
+      promptMsg,
+      "",
+      "AIWK delivery contract:",
+      "- Work in the active repository; printed code is not a substitute for workspace delivery.",
+      "- Keep the diff scoped and run proportional validation.",
+      "- The parent already satisfied the branch gate. Do not repeat branch/status checks unless a new safety concern makes them necessary.",
+      "- Documentation, screenshots, Sage review, Phoenix remediation, and persisted evidence are conditional; do not create them unless the request, risk policy, or an observed finding requires them.",
+      "- Do not run collect-evidence, create a handoff, or finalize this workflow; the parent execute process is the sole finalization owner.",
+      "- End with exactly one machine-readable line: AIWK_DELIVERY_OUTCOME: CHANGED or AIWK_DELIVERY_OUTCOME: ALREADY_SATISFIED.",
+      "- Use ALREADY_SATISFIED only when inspection and relevant validation prove that no repository change is needed."
+    ].join("\n");
+  }
+  const runResult = await delegationController.implement(promptMsg, plan.owner, { readOnly: !plan.branchNeeded, fastTrack, orchestratedChild: true });
   if (!runResult.success) {
     console.error(`[EXECUTE] OpenCode adapter execution reported failure: ${runResult.error || "Unknown error"}`);
     stateMachine.transitionTo("BLOCKED");
@@ -3047,9 +3138,13 @@ async function runReadOnlyConfinementCheck(readOnlyStateBefore, cwd, stateMachin
 ${violations.join("\n")}`);
   }
 }
-async function runValidation(plan, taskSlug, cwd, gateResult, naturalRequest, delegationController, stateMachine) {
+async function runValidation(plan, taskSlug, cwd, gateResult, naturalRequest, claimedOutcome, deliveryBaseline, deliveryFinalizer, delegationController, stateMachine) {
   stateMachine.transitionTo("VALIDATING");
   const validateWorkflow = async () => {
+    const deliveryIntegrity = await deliveryFinalizer.verifyIntegrity(deliveryBaseline);
+    const deliveryChangedFiles = extractDeliveryChangedFiles(deliveryIntegrity);
+    const deliveryAddedFiles = deliveryIntegrity.changes.added.filter((file) => deliveryChangedFiles.includes(file));
+    const deliveryDeletedFiles = deliveryIntegrity.changes.deleted.filter((file) => deliveryChangedFiles.includes(file));
     const evidence = await runCollectEvidence({
       cwd,
       exitOnError: false,
@@ -3058,7 +3153,11 @@ async function runValidation(plan, taskSlug, cwd, gateResult, naturalRequest, de
       profile: plan.profile,
       branchRecovery: gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : "NOT_REQUIRED",
       userRequest: naturalRequest,
-      explicitApprovals: process.env.AI_WORKFLOW_APPROVALS ? process.env.AI_WORKFLOW_APPROVALS.split(",").map((a) => a.trim()) : []
+      explicitApprovals: process.env.AI_WORKFLOW_APPROVALS ? process.env.AI_WORKFLOW_APPROVALS.split(",").map((a) => a.trim()) : [],
+      claimedOutcome,
+      deliveryChangedFiles,
+      deliveryAddedFiles,
+      deliveryDeletedFiles
     });
     const quality = await new QualityGuard({
       cwd,
@@ -3161,7 +3260,7 @@ async function runFidelityValidation(naturalRequest, result, finalizer) {
     userRequest: naturalRequest,
     projectContext: result.evidence?.deliveryDecision?.projectContext || null,
     deliveryDecision: result.evidence?.deliveryDecision || null,
-    changedFiles: result.evidence?.changedFiles || [],
+    changedFiles: result.evidence?.deliveryChangedFiles || result.evidence?.changedFiles || [],
     evidence: result.evidence || null,
     explicitApprovals: process.env.AI_WORKFLOW_APPROVALS ? process.env.AI_WORKFLOW_APPROVALS.split(",").map((a) => a.trim()) : []
   });
@@ -3178,7 +3277,7 @@ function computeFinalState(finalStatus) {
   if (finalStatus === "PASS_WITH_NOTES") return "COMPLETED_WITH_NOTES";
   return "BLOCKED";
 }
-async function executeReadOnlyWorkflow(cwd, stateMachine, readOnlyStateBefore, fastTrack) {
+async function executeReadOnlyWorkflow(cwd, stateMachine, readOnlyStateBefore, fastTrack, deliveryOutcome) {
   await runReadOnlyConfinementCheck(readOnlyStateBefore, cwd, stateMachine, fastTrack);
   stateMachine.transitionTo("IMPLEMENTED");
   stateMachine.transitionTo("VALIDATING");
@@ -3192,7 +3291,11 @@ async function executeReadOnlyWorkflow(cwd, stateMachine, readOnlyStateBefore, f
     overallStatus: "PASS",
     evidence: {
       internalStatus: "PASS",
-      commandsRun: []
+      commandsRun: [],
+      deliveryMode: "answer-only",
+      deliveryOutcome,
+      testAction: "none",
+      testReason: "Read-only work does not change executable behavior."
     },
     quality: {
       overallStatus: "PASS"
@@ -3201,6 +3304,9 @@ async function executeReadOnlyWorkflow(cwd, stateMachine, readOnlyStateBefore, f
   };
 }
 async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
+  if (process.env.AI_WORKFLOW_FINALIZATION_OWNER === "execute") {
+    throw new Error("[NESTED EXECUTION BLOCKED] The parent execute process owns orchestration and finalization.");
+  }
   if (!naturalRequest || !naturalRequest.trim()) {
     throw new Error("Missing request. Please provide a natural request string via positional arguments or --request flag.");
   }
@@ -3211,6 +3317,7 @@ async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
   const ledger = new EvidenceLedger({ cwd, workflowId: taskSlug });
   const delegationController = new DelegationController({ cwd, ledger, adapter: new OpenCodeAdapter({ cwd }) });
   let plan = null;
+  let branchAuthorized = false;
   try {
     const stateMachine = new WorkflowStateMachine();
     const { plan: planObj, classification } = await classifyAndPlanExecution(naturalRequest, cwd, taskSlug, delegationController, stateMachine);
@@ -3218,6 +3325,7 @@ async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
     const fastTrack = plan.riskLevel === "low" && (!plan.branchNeeded || plan.evidencePolicy === "optional");
     const branchGate = new BranchGate({ memoryDir: path16.join(cwd, ".ai-workflow"), cwd });
     const gateResult = runBranchGate(plan, taskSlug, cwd, stateMachine, branchGate);
+    branchAuthorized = true;
     const checkBranchSafety = () => {
       if (!planObj.branchNeeded) return;
       const currentBranch = branchGate.getCurrentBranch();
@@ -3231,18 +3339,38 @@ async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
     }
     await createSpecIfRequired(plan, classification, taskSlug, cwd);
     let readOnlyStateBefore = null;
+    let deliveryBaseline = null;
+    const deliveryFinalizer = new Finalizer({ cwd, fastTrack: false });
     if (!plan.branchNeeded) {
       readOnlyStateBefore = await captureReadOnlyState(cwd, fastTrack);
+    } else {
+      deliveryBaseline = await deliveryFinalizer.snapshotManager.capture();
     }
-    await runImplementation(plan, classification, delegationController, stateMachine, fastTrack);
+    const implementationResult = await runImplementation(plan, classification, delegationController, stateMachine, fastTrack);
+    const claimedOutcome = parseDeliveryOutcomeClaim(implementationResult.output || "");
     if (!plan.branchNeeded && readOnlyStateBefore) {
-      return await executeReadOnlyWorkflow(cwd, stateMachine, readOnlyStateBefore, fastTrack);
+      const readOnlyOutcome = classification.requestUnderstanding.mutationIntent === "readonly" ? "READ_ONLY_RESULT" : "PREVIEW_ONLY";
+      return await executeReadOnlyWorkflow(cwd, stateMachine, readOnlyStateBefore, fastTrack, readOnlyOutcome);
+    }
+    if (!deliveryBaseline) {
+      throw new Error("[WORKFLOW BLOCKED] Missing delivery baseline for a write workflow.");
     }
     stateMachine.transitionTo("IMPLEMENTED");
     checkBranchSafety();
     const finalizer = new Finalizer({ cwd, fastTrack });
     const snapshotRef = { current: await finalizer.snapshotManager.capture() };
-    const { result: valResult, validateWorkflow } = await runValidation(plan, taskSlug, cwd, gateResult, naturalRequest, delegationController, stateMachine);
+    const { result: valResult, validateWorkflow } = await runValidation(
+      plan,
+      taskSlug,
+      cwd,
+      gateResult,
+      naturalRequest,
+      claimedOutcome,
+      deliveryBaseline,
+      deliveryFinalizer,
+      delegationController,
+      stateMachine
+    );
     let result = valResult;
     result = await runBoundedRemediation(
       plan,
@@ -3292,10 +3420,26 @@ async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
     }
     const finalState = computeFinalState(finalStatus);
     stateMachine.transitionTo(finalState);
+    ledger.logEvent({
+      actor: "Atlas",
+      actorType: "control-plane",
+      observed: true,
+      eventType: "finalization_started",
+      provenance: "execute",
+      data: { owner: "execute", status: finalState }
+    });
     await generateFinalHandoff(plan, taskSlug, cwd, finalState, result.evidence);
+    ledger.logEvent({
+      actor: "Atlas",
+      actorType: "control-plane",
+      observed: true,
+      eventType: "finalization_completed",
+      provenance: "execute",
+      data: { owner: "execute", status: finalState }
+    });
     return { ...result, overallStatus: finalStatus, stateHistory: stateMachine.getHistory() };
   } finally {
-    if (plan && !plan.branchNeeded) {
+    if (!branchAuthorized || plan && !plan.branchNeeded) {
       console.log(`
 [READ-ONLY LEDGER] (In-Memory/Stdout)
 ${JSON.stringify(ledger.getEvents(), null, 2)}
@@ -3499,7 +3643,7 @@ var commandMap = {
     });
   },
   validate: async (_, flags) => {
-    const { runValidate } = await import("../validate-IEHLAVZ6.js");
+    const { runValidate } = await import("../validate-DDKN6ORS.js");
     await runValidate({
       cwd: process.cwd(),
       taskSlug: flags.taskSlug,