intentdna 1.8.6 → 1.8.7

package/dist/runtime/workflow-runner.d.ts

@@ -1,17 +1,21 @@
 /**
  * Intent DNA -- Workflow Shell Script Runner
  *
- * Compiles a WorkflowPlan into an executable bash script.
+ * Compiles a WorkflowPlan into a legacy executable bash script.
  * Each step invokes `claude -p --agent <role-name>`.
  * Parallel groups use background jobs + wait.
  * Retry loops wrap the execution with round tracking.
  *
+ * This module is a compatibility exporter only. Canonical execution uses the
+ * typed RunController through `dna run`; generated scripts do not own durable
+ * run state, handoff resolution, resume, cancellation, or workspace lifecycle.
+ *
  * Output: a self-contained shell script with set -euo pipefail,
  * run_agent helper, parallel group execution, retry logic, and
  * transition-based flow control.
  */
 import type { WorkflowPlan } from "../schema/types.js";
-/** Options for workflow shell script generation */
+/** @deprecated Compatibility exporter options; use the canonical `dna run` runtime. */
 export interface WorkflowShellOptions {
     /** Agent name prefix (default "dna-") */
     agentPrefix?: string;
@@ -26,7 +30,7 @@ export interface WorkflowShellOptions {
     /** Include pause/resume support (default false) */
     pauseSupport?: boolean;
 }
-/** Result of workflow shell script generation */
+/** @deprecated Compatibility exporter result; use the canonical `dna run` runtime. */
 export interface WorkflowShellResult {
     /** The generated script content */
     script: string;
@@ -36,17 +40,25 @@ export interface WorkflowShellResult {
 /**
  * Compile a WorkflowPlan into an executable shell script.
  * Pure function, no side effects.
+ *
+ * @deprecated Generated shell has legacy execution semantics. Use the typed
+ * RunController through `dna run` for canonical execution.
  */
 export declare function compileWorkflowToShell(plan: WorkflowPlan, options?: WorkflowShellOptions): WorkflowShellResult;
 /**
  * Write workflow shell script to the file system.
  * Creates the directory if it doesn't exist.
  * Returns the path of the written file.
+ *
+ * @deprecated Writes a legacy compatibility export; it is not an execution
+ * entrypoint for the Foundation Runtime.
  */
 export declare function writeWorkflowScript(result: WorkflowShellResult, outputDir: string): Promise<string>;
 /**
  * Remove Intent DNA generated workflow scripts from a directory.
  * Only removes files that contain the sentinel comment.
  * Returns number of files removed.
+ *
+ * @deprecated Manages only legacy compatibility exports.
  */
 export declare function removeWorkflowScripts(outputDir: string): Promise<number>;

package/dist/runtime/workflow-runner.js

@@ -1,11 +1,15 @@
 /**
  * Intent DNA -- Workflow Shell Script Runner
  *
- * Compiles a WorkflowPlan into an executable bash script.
+ * Compiles a WorkflowPlan into a legacy executable bash script.
  * Each step invokes `claude -p --agent <role-name>`.
  * Parallel groups use background jobs + wait.
  * Retry loops wrap the execution with round tracking.
  *
+ * This module is a compatibility exporter only. Canonical execution uses the
+ * typed RunController through `dna run`; generated scripts do not own durable
+ * run state, handoff resolution, resume, cancellation, or workspace lifecycle.
+ *
  * Output: a self-contained shell script with set -euo pipefail,
  * run_agent helper, parallel group execution, retry logic, and
  * transition-based flow control.
@@ -460,6 +464,9 @@ function generateFailureChecks(plan) {
 /**
  * Compile a WorkflowPlan into an executable shell script.
  * Pure function, no side effects.
+ *
+ * @deprecated Generated shell has legacy execution semantics. Use the typed
+ * RunController through `dna run` for canonical execution.
  */
 export function compileWorkflowToShell(plan, options) {
     const opts = {
@@ -544,6 +551,9 @@ export function compileWorkflowToShell(plan, options) {
  * Write workflow shell script to the file system.
  * Creates the directory if it doesn't exist.
  * Returns the path of the written file.
+ *
+ * @deprecated Writes a legacy compatibility export; it is not an execution
+ * entrypoint for the Foundation Runtime.
  */
 export async function writeWorkflowScript(result, outputDir) {
     await mkdir(outputDir, { recursive: true });
@@ -555,6 +565,8 @@ export async function writeWorkflowScript(result, outputDir) {
  * Remove Intent DNA generated workflow scripts from a directory.
  * Only removes files that contain the sentinel comment.
  * Returns number of files removed.
+ *
+ * @deprecated Manages only legacy compatibility exports.
  */
 export async function removeWorkflowScripts(outputDir) {
     let entries;

package/dist/runtime/workspace-isolation.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Typed adaptation of oh-my-codex v0.20.3 worktree allocation.
+ *
+ * IntentDNA keys workspaces by durable attempt identity, records an exact base
+ * commit, and leaves preservation or cleanup to an explicit Controller decision.
+ * Team naming, CLI parsing, generated shell, and automatic rollback are excluded.
+ */
+import type { AttemptId, RunId, StepId } from "./run-contracts.js";
+export type WorkspaceIsolation = "none" | "worktree";
+export type WorkspaceIsolationErrorCode = "invalid_request" | "not_git_repository" | "git_command_failed" | "path_conflict" | "branch_conflict" | "workspace_mismatch" | "unsafe_cleanup_target";
+export declare class WorkspaceIsolationError extends Error {
+    readonly code: WorkspaceIsolationErrorCode;
+    constructor(code: WorkspaceIsolationErrorCode, message: string);
+}
+export interface AttemptWorkspaceRequest {
+    readonly isolation: WorkspaceIsolation;
+    readonly repository_directory: string;
+    readonly run_id: RunId;
+    readonly step_id: StepId;
+    readonly attempt_id: AttemptId;
+    /**
+     * Git revision to resolve once and record as the immutable worktree base.
+     * Defaults to HEAD. It is ignored for isolation=none.
+     */
+    readonly base_ref?: string;
+    /**
+     * Parent directory owned by this service. Defaults to
+     * <repository>/.dna/worktrees/runtime.
+     */
+    readonly worktree_root?: string;
+}
+export interface SharedWorkspacePlan {
+    readonly isolation: "none";
+    readonly run_id: RunId;
+    readonly step_id: StepId;
+    readonly attempt_id: AttemptId;
+    readonly working_directory: string;
+}
+export interface IsolatedWorkspacePlan {
+    readonly isolation: "worktree";
+    readonly run_id: RunId;
+    readonly step_id: StepId;
+    readonly attempt_id: AttemptId;
+    readonly repository_root: string;
+    readonly worktree_root: string;
+    readonly working_directory: string;
+    readonly branch_name: string;
+    readonly base_ref: string;
+    readonly base_commit: string;
+    readonly ownership_key: string;
+}
+export type AttemptWorkspacePlan = SharedWorkspacePlan | IsolatedWorkspacePlan;
+export interface SharedWorkspaceAllocation extends SharedWorkspacePlan {
+    readonly created: false;
+    readonly reused: true;
+}
+export interface IsolatedWorkspaceAllocation extends IsolatedWorkspacePlan {
+    readonly created: boolean;
+    readonly reused: boolean;
+    readonly dirty_at_allocation: boolean;
+    readonly conflicted_at_allocation: boolean;
+}
+export type AttemptWorkspaceAllocation = SharedWorkspaceAllocation | IsolatedWorkspaceAllocation;
+export interface WorkspaceInspection {
+    readonly exists: boolean;
+    readonly registered: boolean;
+    readonly owned_by_attempt: boolean;
+    readonly dirty: boolean;
+    readonly conflicted: boolean;
+    readonly head: string | null;
+    readonly branch_ref: string | null;
+}
+export type WorkspacePreservationReason = "attempt_failed" | "attempt_cancelled" | "integration_conflicted" | "integration_pending" | "controller_policy";
+export type WorkspaceLifecycleDecision = {
+    readonly action: "preserve";
+    readonly reason: WorkspacePreservationReason;
+    readonly detail?: string;
+} | {
+    readonly action: "cleanup";
+    readonly attempt_outcome: "succeeded";
+    readonly integration: "integrated";
+    /** Delete the attempt branch after removing the worktree. Default: true. */
+    readonly delete_branch?: boolean;
+};
+export type WorkspaceLifecycleResult = {
+    readonly status: "not_applicable";
+    readonly working_directory: string;
+} | {
+    readonly status: "preserved";
+    readonly working_directory: string;
+    readonly reason: WorkspacePreservationReason | "dirty" | "conflicted";
+    readonly detail: string | null;
+} | {
+    readonly status: "cleaned";
+    readonly working_directory: string;
+    readonly branch_deleted: boolean;
+};
+export declare function planAttemptWorkspace(request: AttemptWorkspaceRequest): AttemptWorkspacePlan;
+export declare function allocateAttemptWorkspace(plan: AttemptWorkspacePlan): AttemptWorkspaceAllocation;
+export declare function inspectAttemptWorkspace(workspace: AttemptWorkspaceAllocation): WorkspaceInspection;
+export declare function applyWorkspaceLifecycleDecision(workspace: AttemptWorkspaceAllocation, decision: WorkspaceLifecycleDecision): WorkspaceLifecycleResult;
+export declare function defaultWorktreeRoot(repositoryRoot: string): string;
+export declare function describeWorkspace(workspace: AttemptWorkspacePlan): string;

package/dist/runtime/workspace-isolation.js

@@ -0,0 +1,373 @@
+/**
+ * Typed adaptation of oh-my-codex v0.20.3 worktree allocation.
+ *
+ * IntentDNA keys workspaces by durable attempt identity, records an exact base
+ * commit, and leaves preservation or cleanup to an explicit Controller decision.
+ * Team naming, CLI parsing, generated shell, and automatic rollback are excluded.
+ */
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, realpathSync, } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, } from "node:path";
+export class WorkspaceIsolationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "WorkspaceIsolationError";
+        this.code = code;
+    }
+}
+function git(cwd, args, allowFailure = false) {
+    const result = spawnSync("git", [...args], {
+        cwd,
+        encoding: "utf8",
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    const output = {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    };
+    if (!allowFailure && output.status !== 0) {
+        const detail = output.stderr.trim() || output.stdout.trim();
+        throw new WorkspaceIsolationError("git_command_failed", detail || `git ${args.join(" ")} failed`);
+    }
+    return output;
+}
+function requireText(value, label) {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.includes("\0")) {
+        throw new WorkspaceIsolationError("invalid_request", `${label} must be non-empty and contain no NUL byte`);
+    }
+    return trimmed;
+}
+function canonicalExistingDirectory(path, label) {
+    const requested = resolve(requireText(path, label));
+    if (!existsSync(requested)) {
+        throw new WorkspaceIsolationError("invalid_request", `${label} does not exist: ${requested}`);
+    }
+    const status = lstatSync(requested);
+    if (status.isSymbolicLink() || !status.isDirectory()) {
+        throw new WorkspaceIsolationError("invalid_request", `${label} must be a real directory: ${requested}`);
+    }
+    return realpathSync(requested);
+}
+function repositoryRoot(cwd) {
+    const result = git(cwd, ["rev-parse", "--show-toplevel"], true);
+    if (result.status !== 0 || !result.stdout.trim()) {
+        throw new WorkspaceIsolationError("not_git_repository", `not a Git repository: ${cwd}`);
+    }
+    return realpathSync(resolve(result.stdout.trim()));
+}
+function resolveCommit(repoRoot, ref) {
+    const value = requireText(ref, "base_ref");
+    const result = git(repoRoot, ["rev-parse", "--verify", `${value}^{commit}`], true);
+    if (result.status !== 0 || !result.stdout.trim()) {
+        throw new WorkspaceIsolationError("invalid_request", `base_ref does not resolve to a commit: ${value}`);
+    }
+    return result.stdout.trim();
+}
+function pathToken(value) {
+    const normalized = value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 32);
+    return normalized || "step";
+}
+function ownershipKey(runId, stepId, attemptId) {
+    return createHash("sha256")
+        .update(JSON.stringify([runId, stepId, attemptId]))
+        .digest("hex")
+        .slice(0, 16);
+}
+function isInside(parent, child) {
+    const rel = relative(parent, child);
+    return rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel);
+}
+function assertSafeWorktreeRoot(repository, worktreeRoot) {
+    if (!isInside(repository, worktreeRoot)) {
+        throw new WorkspaceIsolationError("invalid_request", `worktree_root must be a child of the repository: ${worktreeRoot}`);
+    }
+    const components = relative(repository, worktreeRoot).split(/[\\/]+/);
+    let cursor = repository;
+    for (const component of components) {
+        cursor = join(cursor, component);
+        if (!existsSync(cursor))
+            continue;
+        const status = lstatSync(cursor);
+        if (status.isSymbolicLink() || !status.isDirectory()) {
+            throw new WorkspaceIsolationError("path_conflict", `worktree_root contains a non-directory or symlink component: ${cursor}`);
+        }
+    }
+    if (existsSync(worktreeRoot)) {
+        const canonical = realpathSync(worktreeRoot);
+        if (!isInside(repository, canonical)) {
+            throw new WorkspaceIsolationError("path_conflict", `worktree_root resolves outside the repository: ${canonical}`);
+        }
+    }
+}
+function assertOwnedPath(worktreeRoot, worktreePath, repository, requireExisting) {
+    const root = existsSync(worktreeRoot)
+        ? realpathSync(worktreeRoot)
+        : resolve(worktreeRoot);
+    if (!isInside(repository, root)) {
+        throw new WorkspaceIsolationError("unsafe_cleanup_target", `owned worktree root resolves outside the repository: ${root}`);
+    }
+    const target = resolve(worktreePath);
+    if (!isInside(root, target) || target === repository) {
+        throw new WorkspaceIsolationError("unsafe_cleanup_target", `workspace is outside its owned root: ${target}`);
+    }
+    if (!existsSync(target)) {
+        if (requireExisting) {
+            throw new WorkspaceIsolationError("unsafe_cleanup_target", `workspace does not exist: ${target}`);
+        }
+        return;
+    }
+    const status = lstatSync(target);
+    if (status.isSymbolicLink() || !status.isDirectory()) {
+        throw new WorkspaceIsolationError("unsafe_cleanup_target", `workspace is not a real directory: ${target}`);
+    }
+    const canonical = realpathSync(target);
+    if (!isInside(root, canonical) || canonical === repository) {
+        throw new WorkspaceIsolationError("unsafe_cleanup_target", `workspace resolves outside its owned root: ${canonical}`);
+    }
+    const dotGit = join(canonical, ".git");
+    if (existsSync(dotGit) && lstatSync(dotGit).isDirectory()) {
+        throw new WorkspaceIsolationError("unsafe_cleanup_target", `workspace points at a main repository: ${canonical}`);
+    }
+}
+function listWorktrees(repoRoot) {
+    const raw = git(repoRoot, ["worktree", "list", "--porcelain"]).stdout.trim();
+    if (!raw)
+        return [];
+    return raw.split(/\n\n+/).flatMap((block) => {
+        const lines = block.split(/\r?\n/).filter(Boolean);
+        const pathLine = lines.find((line) => line.startsWith("worktree "));
+        const headLine = lines.find((line) => line.startsWith("HEAD "));
+        if (!pathLine || !headLine)
+            return [];
+        const branchLine = lines.find((line) => line.startsWith("branch "));
+        return [{
+                path: resolve(pathLine.slice("worktree ".length)),
+                head: headLine.slice("HEAD ".length).trim(),
+                branch_ref: branchLine
+                    ? branchLine.slice("branch ".length).trim()
+                    : null,
+                prunable: lines.some((line) => line.startsWith("prunable")),
+            }];
+    });
+}
+function worktreeAt(entries, path) {
+    const target = resolve(path);
+    return entries.find((entry) => resolve(entry.path) === target) ?? null;
+}
+function branchWorktree(entries, branchName) {
+    const branchRef = `refs/heads/${branchName}`;
+    return entries.find((entry) => entry.branch_ref === branchRef) ?? null;
+}
+function sameGitRepository(repoRoot, worktreePath) {
+    const repo = git(repoRoot, ["rev-parse", "--git-common-dir"], true);
+    const workspace = git(worktreePath, ["rev-parse", "--git-common-dir"], true);
+    if (repo.status !== 0 || workspace.status !== 0)
+        return false;
+    const repoCommon = resolve(repoRoot, repo.stdout.trim());
+    const workspaceCommon = resolve(worktreePath, workspace.stdout.trim());
+    return repoCommon === workspaceCommon;
+}
+function workspaceState(worktreePath) {
+    const dirty = git(worktreePath, ["status", "--porcelain", "--untracked-files=all"]).stdout.trim().length > 0;
+    const conflicted = git(worktreePath, ["diff", "--name-only", "--diff-filter=U"]).stdout.trim().length > 0;
+    return { dirty, conflicted };
+}
+function expectedBranchRef(plan) {
+    return `refs/heads/${plan.branch_name}`;
+}
+function assertMatchingWorktree(plan, entry) {
+    if (entry.branch_ref !== expectedBranchRef(plan)
+        || !sameGitRepository(plan.repository_root, plan.working_directory)) {
+        throw new WorkspaceIsolationError("workspace_mismatch", `existing worktree is not owned by attempt ${plan.attempt_id}: ${plan.working_directory}`);
+    }
+}
+export function planAttemptWorkspace(request) {
+    const cwd = canonicalExistingDirectory(request.repository_directory, "repository_directory");
+    if (request.isolation === "none") {
+        return {
+            isolation: "none",
+            run_id: request.run_id,
+            step_id: request.step_id,
+            attempt_id: request.attempt_id,
+            working_directory: cwd,
+        };
+    }
+    const repoRoot = repositoryRoot(cwd);
+    const root = resolve(request.worktree_root
+        ? requireText(request.worktree_root, "worktree_root")
+        : join(repoRoot, ".dna", "worktrees", "runtime"));
+    assertSafeWorktreeRoot(repoRoot, root);
+    const key = ownershipKey(request.run_id, request.step_id, request.attempt_id);
+    const step = pathToken(request.step_id);
+    const baseRef = request.base_ref?.trim() || "HEAD";
+    const baseCommit = resolveCommit(repoRoot, baseRef);
+    return {
+        isolation: "worktree",
+        run_id: request.run_id,
+        step_id: request.step_id,
+        attempt_id: request.attempt_id,
+        repository_root: repoRoot,
+        worktree_root: root,
+        working_directory: join(root, `${step}-${key}`),
+        branch_name: `dna/attempt/${step}-${key}`,
+        base_ref: baseRef,
+        base_commit: baseCommit,
+        ownership_key: key,
+    };
+}
+export function allocateAttemptWorkspace(plan) {
+    if (plan.isolation === "none") {
+        return { ...plan, created: false, reused: true };
+    }
+    mkdirSync(plan.worktree_root, { recursive: true });
+    assertSafeWorktreeRoot(plan.repository_root, plan.worktree_root);
+    assertOwnedPath(plan.worktree_root, plan.working_directory, plan.repository_root, false);
+    let entries = listWorktrees(plan.repository_root);
+    const stale = worktreeAt(entries, plan.working_directory);
+    if (stale
+        && stale.prunable
+        && !existsSync(plan.working_directory)) {
+        git(plan.repository_root, ["worktree", "prune", "--expire", "now"]);
+        entries = listWorktrees(plan.repository_root);
+    }
+    const existing = worktreeAt(entries, plan.working_directory);
+    if (existing) {
+        assertMatchingWorktree(plan, existing);
+        const state = workspaceState(plan.working_directory);
+        return {
+            ...plan,
+            created: false,
+            reused: true,
+            dirty_at_allocation: state.dirty,
+            conflicted_at_allocation: state.conflicted,
+        };
+    }
+    if (existsSync(plan.working_directory)) {
+        throw new WorkspaceIsolationError("path_conflict", `worktree path is occupied by an unowned entry: ${plan.working_directory}`);
+    }
+    const inUse = branchWorktree(entries, plan.branch_name);
+    if (inUse) {
+        throw new WorkspaceIsolationError("branch_conflict", `attempt branch is already checked out at ${inUse.path}`);
+    }
+    const branchExists = git(plan.repository_root, ["show-ref", "--verify", "--quiet", expectedBranchRef(plan)], true).status === 0;
+    if (branchExists) {
+        throw new WorkspaceIsolationError("branch_conflict", `attempt branch already exists without its owned worktree: ${plan.branch_name}`);
+    }
+    git(plan.repository_root, [
+        "worktree",
+        "add",
+        "-b",
+        plan.branch_name,
+        plan.working_directory,
+        plan.base_commit,
+    ]);
+    return {
+        ...plan,
+        created: true,
+        reused: false,
+        dirty_at_allocation: false,
+        conflicted_at_allocation: false,
+    };
+}
+export function inspectAttemptWorkspace(workspace) {
+    if (workspace.isolation === "none") {
+        return {
+            exists: existsSync(workspace.working_directory),
+            registered: false,
+            owned_by_attempt: true,
+            dirty: false,
+            conflicted: false,
+            head: null,
+            branch_ref: null,
+        };
+    }
+    const exists = existsSync(workspace.working_directory);
+    const entry = worktreeAt(listWorktrees(workspace.repository_root), workspace.working_directory);
+    const owned = Boolean(exists
+        && entry
+        && entry.branch_ref === expectedBranchRef(workspace)
+        && sameGitRepository(workspace.repository_root, workspace.working_directory));
+    const state = owned
+        ? workspaceState(workspace.working_directory)
+        : { dirty: false, conflicted: false };
+    return {
+        exists,
+        registered: entry !== null,
+        owned_by_attempt: owned,
+        dirty: state.dirty,
+        conflicted: state.conflicted,
+        head: entry?.head ?? null,
+        branch_ref: entry?.branch_ref ?? null,
+    };
+}
+export function applyWorkspaceLifecycleDecision(workspace, decision) {
+    if (workspace.isolation === "none") {
+        return {
+            status: "not_applicable",
+            working_directory: workspace.working_directory,
+        };
+    }
+    if (decision.action === "preserve") {
+        return {
+            status: "preserved",
+            working_directory: workspace.working_directory,
+            reason: decision.reason,
+            detail: decision.detail ?? null,
+        };
+    }
+    assertOwnedPath(workspace.worktree_root, workspace.working_directory, workspace.repository_root, true);
+    const inspection = inspectAttemptWorkspace(workspace);
+    if (!inspection.owned_by_attempt) {
+        throw new WorkspaceIsolationError("workspace_mismatch", `cleanup target is not owned by attempt ${workspace.attempt_id}`);
+    }
+    if (inspection.conflicted) {
+        return {
+            status: "preserved",
+            working_directory: workspace.working_directory,
+            reason: "conflicted",
+            detail: "cleanup refused because the worktree contains unresolved conflicts",
+        };
+    }
+    if (inspection.dirty) {
+        return {
+            status: "preserved",
+            working_directory: workspace.working_directory,
+            reason: "dirty",
+            detail: "cleanup refused because the worktree contains uncommitted changes",
+        };
+    }
+    git(workspace.repository_root, [
+        "worktree",
+        "remove",
+        workspace.working_directory,
+    ]);
+    let branchDeleted = false;
+    if (decision.delete_branch !== false) {
+        const removed = git(workspace.repository_root, ["branch", "-d", workspace.branch_name], true);
+        branchDeleted = removed.status === 0;
+    }
+    return {
+        status: "cleaned",
+        working_directory: workspace.working_directory,
+        branch_deleted: branchDeleted,
+    };
+}
+export function defaultWorktreeRoot(repositoryRoot) {
+    return join(resolve(repositoryRoot), ".dna", "worktrees", "runtime");
+}
+export function describeWorkspace(workspace) {
+    if (workspace.isolation === "none") {
+        return `shared workspace ${workspace.working_directory}`;
+    }
+    return `${basename(dirname(workspace.working_directory))}/${basename(workspace.working_directory)} at ${workspace.base_commit}`;
+}

package/dist/schema/types.d.ts

@@ -564,6 +564,7 @@ export interface WorkflowStep {
     completion: CompletionCheck[] | null;
     checkpoints: StepCheckpoint[] | null;
     handoff: StepHandoff | null;
+    enforce: NonNullable<WorkflowStepDef["enforce"]> | null;
     max_attempts?: number;
     on_fail?: "retry_with_feedback" | "handoff" | "skip";
     handoff_to?: string;

package/dist/schema/validate.js

@@ -444,6 +444,65 @@ function validateCompletionCheck(check, path) {
     }
     return errors;
 }
+function workflowStepsForValidation(workflow, path, errors) {
+    const entries = [];
+    const rawSteps = workflow.steps;
+    for (let i = 0; i < rawSteps.length; i++) {
+        const raw = rawSteps[i];
+        const stepPath = `${path}.steps[${i}]`;
+        if (typeof raw !== "object"
+            || raw === null
+            || !("parallel" in raw)) {
+            entries.push({
+                step: (typeof raw === "object" && raw !== null ? raw : {}),
+                path: stepPath,
+            });
+            continue;
+        }
+        const parallel = raw.parallel;
+        if (typeof parallel !== "object" || parallel === null) {
+            errors.push({
+                path: `${stepPath}.parallel`,
+                message: "parallel block must be an object",
+            });
+            continue;
+        }
+        const block = parallel;
+        const isolation = block.isolation;
+        if (isolation !== undefined
+            && (typeof isolation !== "string"
+                || !WORKFLOW_ISOLATION_VALUES.includes(isolation))) {
+            errors.push({
+                path: `${stepPath}.parallel.isolation`,
+                message: `must be one of: ${WORKFLOW_ISOLATION_VALUES.join(", ")}`,
+            });
+        }
+        const mergeStrategy = block.merge_strategy;
+        if (mergeStrategy !== undefined
+            && (typeof mergeStrategy !== "string"
+                || !WORKFLOW_MERGE_STRATEGY_VALUES.includes(mergeStrategy))) {
+            errors.push({
+                path: `${stepPath}.parallel.merge_strategy`,
+                message: `must be one of: ${WORKFLOW_MERGE_STRATEGY_VALUES.join(", ")}`,
+            });
+        }
+        if (!Array.isArray(block.steps) || block.steps.length === 0) {
+            errors.push({
+                path: `${stepPath}.parallel.steps`,
+                message: "parallel block requires at least one step",
+            });
+            continue;
+        }
+        for (let j = 0; j < block.steps.length; j++) {
+            const inner = block.steps[j];
+            entries.push({
+                step: (typeof inner === "object" && inner !== null ? inner : {}),
+                path: `${stepPath}.parallel.steps[${j}]`,
+            });
+        }
+    }
+    return entries;
+}
 function validateWorkflow(workflow, roleNames, pathPrefix) {
     const errors = [];
     const path = pathPrefix ?? "workflow";
@@ -459,12 +518,12 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
         errors.push({ path: `${path}.steps`, message: "workflow requires at least one step" });
         return errors; // early return, downstream checks need steps
     }
+    const workflowSteps = workflowStepsForValidation(workflow, path, errors);
     // Collect step ids for reference checking
     const stepIds = new Set();
     const seenStepIds = new Set();
-    for (let i = 0; i < workflow.steps.length; i++) {
-        const step = workflow.steps[i];
-        const stepPath = `${path}.steps[${i}]`;
+    for (const entry of workflowSteps) {
+        const { step, path: stepPath } = entry;
         // step.id required and unique
         if (!step.id) {
             errors.push({ path: `${stepPath}.id`, message: "step requires 'id'" });
@@ -579,9 +638,8 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
         }
     }
     // Second pass: validate depends_on references against all step ids
-    for (let i = 0; i < workflow.steps.length; i++) {
-        const step = workflow.steps[i];
-        const stepPath = `${path}.steps[${i}]`;
+    for (const entry of workflowSteps) {
+        const { step, path: stepPath } = entry;
         for (const dep of step.depends_on ?? []) {
             if (dep && !stepIds.has(dep)) {
                 errors.push({