@bastani/atomic 0.8.17 → 0.8.18

package/dist/builtin/workflows/builtin/shared-prompts.ts

@@ -0,0 +1,11 @@
+export const WORKER_PREFLIGHT_CONTRACT = [
+  "Before normal implementation delegation, determine whether this checkout appears initialized for its actual language, framework, and build system.",
+  "Do not rely on hard-coded assumptions about JavaScript, TypeScript, Python, Rust, Go, Java, mobile, or any other ecosystem. Infer the project type and setup requirements from repository evidence.",
+  "Inspect source layout, setup docs, package/build manifests, lockfiles, toolchain files, generated-artifact conventions, CI workflows, workflow configuration, and package scripts or equivalent task definitions.",
+  "Look for evidence that dependencies, generated files, local toolchains, submodules, codegen outputs, or other project-specific initialization artifacts are missing for this checkout.",
+  "When repository evidence shows missing initialization, run or delegate the appropriate documented setup command before implementation work.",
+  "You are responsible for initializing the checkout when setup commands are documented; missing dependencies, generated files, or local toolchains are setup work, not user handoff work.",
+  "Once setup succeeds, continue normal implementation orchestration. Do not treat missing dependencies or generated setup artifacts in a fresh worktree as implementation failures.",
+  "If setup requirements cannot be determined confidently, delegate a focused discovery task before implementation instead of guessing.",
+  "If setup remains blocked after evidence-based discovery and setup attempts, report the blocker with commands tried and the exact evidence needed to continue.",
+].join("\n");

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.8.17",
+  "version": "0.8.18",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [

package/dist/builtin/workflows/src/extension/discovery.ts

@@ -149,19 +149,17 @@ export interface DiscoveryResult {
 // ---------------------------------------------------------------------------
 
 /**
- * Validate a candidate value as a WorkflowDefinition.
+ * Validate a candidate value as a WorkflowDefinition by shape only.
+ *
+ * Discovery intentionally does not invoke workflow run functions: user-authored
+ * run bodies may perform filesystem, network, or other side effects before the
+ * first ctx.stage()/ctx.task()/ctx.chain()/ctx.parallel() call. Runtime empty
+ * graph validation remains the authoritative guard that a workflow creates at
+ * least one stage when it is actually invoked.
+ *
  * Returns null when valid, or a human-readable rejection reason string.
  */
-function workflowRunCreatesStage(run: WorkflowDefinition["run"]): boolean {
-  // Discovery must not execute workflow bodies: run functions are arbitrary
-  // user code and may perform I/O before the first stage. Use a conservative
-  // static guard instead so obvious no-stage definitions are rejected before
-  // they can register and render an empty graph.
-  const source = Function.prototype.toString.call(run);
-  return /\.\s*(?:stage|task|chain|parallel)\s*\(/.test(source);
-}
-
-function validateDefinition(value: unknown): string | null {
+function validateDefinitionShape(value: unknown): string | null {
   if (value === null || typeof value !== "object") {
     return "export is not an object";
   }
@@ -179,9 +177,6 @@ function validateDefinition(value: unknown): string | null {
   if (typeof d["run"] !== "function") {
     return "run must be a function";
   }
-  if (!workflowRunCreatesStage(d["run"] as WorkflowDefinition["run"])) {
-    return "run must create at least one workflow stage via ctx.stage(), ctx.task(), ctx.chain(), or ctx.parallel(); otherwise the workflow graph is empty (cachedLayout.length === 0)";
-  }
   return null;
 }
 
@@ -215,14 +210,58 @@ function validateConfig(config: unknown): string | null {
 }
 
 /** Merge a batch of candidates into registry state, first-seen wins. */
-function applyBatch(
+async function applyBatch(
+  candidates: Array<{ value: unknown; exportKey: string; kind: DiscoveryKind; filePath?: string; configuredName?: string }>,
+  registry: WorkflowRegistry,
+  sources: DiscoverySource[],
+  diagnostics: DiscoveryDiagnostic[],
+): Promise<WorkflowRegistry> {
+  for (const { value, exportKey, kind, filePath, configuredName } of candidates) {
+    const reason = validateDefinitionShape(value);
+    if (reason !== null) {
+      diagnostics.push({
+        level: "error",
+        code: "INVALID_DEFINITION",
+        message: `${kind} export "${exportKey}" rejected: ${reason}`,
+        source: filePath ?? exportKey,
+      });
+      continue;
+    }
+
+    const def = value as WorkflowDefinition;
+    const key = def.normalizedName;
+
+    if (registry.has(key)) {
+      diagnostics.push({
+        level: "warn",
+        code: "DUPLICATE_NAME",
+        message: `${kind} export "${exportKey}" skipped: normalizedName "${key}" already registered`,
+        source: filePath ?? exportKey,
+      });
+      continue;
+    }
+
+    registry = registry.register(def);
+    sources.push({
+      id: key,
+      kind,
+      name: def.name,
+      ...(filePath !== undefined ? { filePath } : {}),
+      ...(configuredName !== undefined ? { configuredName } : {}),
+    });
+  }
+  return registry;
+}
+
+/** Merge bundled startup candidates with shape-only validation to keep startup seeding synchronous. */
+function applyBatchShapeOnly(
   candidates: Array<{ value: unknown; exportKey: string; kind: DiscoveryKind; filePath?: string; configuredName?: string }>,
   registry: WorkflowRegistry,
   sources: DiscoverySource[],
   diagnostics: DiscoveryDiagnostic[],
 ): WorkflowRegistry {
   for (const { value, exportKey, kind, filePath, configuredName } of candidates) {
-    const reason = validateDefinition(value);
+    const reason = validateDefinitionShape(value);
     if (reason !== null) {
       diagnostics.push({
         level: "error",
@@ -508,14 +547,14 @@ export async function discoverWorkflows(
     const hasEntries = Array.isArray(pw) ? pw.length > 0 : Object.keys(pw).length > 0;
     if (hasEntries) {
       const candidates = await loadFromPaths(pw, "settings-project", cwd, diagnostics);
-      registry = applyBatch(candidates, registry, sources, diagnostics);
+      registry = await applyBatch(candidates, registry, sources, diagnostics);
     }
   }
 
   // 2. project-local
   for (const dir of getProjectConfigPaths(cwd, "workflows").reverse()) {
     const candidates = await loadFromDir(dir, "project-local", diagnostics);
-    registry = applyBatch(candidates, registry, sources, diagnostics);
+    registry = await applyBatch(candidates, registry, sources, diagnostics);
   }
 
   // 3. settings-global
@@ -524,14 +563,14 @@ export async function discoverWorkflows(
     const hasEntries = Array.isArray(gw) ? gw.length > 0 : Object.keys(gw).length > 0;
     if (hasEntries) {
       const candidates = await loadFromPaths(gw, "settings-global", homeDir, diagnostics);
-      registry = applyBatch(candidates, registry, sources, diagnostics);
+      registry = await applyBatch(candidates, registry, sources, diagnostics);
     }
   }
 
   // 4. user-global — canonical Atomic path plus legacy pi path
   for (const dir of CONFIG_DIR_NAMES.map((name) => join(homeDir, name, "agent", "workflows")).reverse()) {
     const candidates = await loadFromDir(dir, "user-global", diagnostics);
-    registry = applyBatch(candidates, registry, sources, diagnostics);
+    registry = await applyBatch(candidates, registry, sources, diagnostics);
   }
 
   // 5. package workflows
@@ -539,7 +578,7 @@ export async function discoverWorkflows(
     const hasEntries = Array.isArray(packageWorkflowPaths) ? packageWorkflowPaths.length > 0 : Object.keys(packageWorkflowPaths).length > 0;
     if (hasEntries) {
       const candidates = await loadFromPaths(packageWorkflowPaths, "package", cwd, diagnostics);
-      registry = applyBatch(candidates, registry, sources, diagnostics);
+      registry = await applyBatch(candidates, registry, sources, diagnostics);
     }
   }
 
@@ -602,7 +641,7 @@ function discoverBundledManifest(): DiscoveryResult {
     kind: "bundled" as DiscoveryKind,
   }));
 
-  registry = applyBatch(candidates, registry, sources, diagnostics);
+  registry = applyBatchShapeOnly(candidates, registry, sources, diagnostics);
 
   return { registry, sources, errors: diagnostics };
 }

package/dist/builtin/workflows/src/extension/index.ts

@@ -456,6 +456,8 @@ export interface WorkflowToolArgs extends StageOptions {
   maxOutput?: WorkflowMaxOutput;
   artifacts?: boolean;
   worktree?: boolean;
+  gitWorktreeDir?: string;
+  baseBranch?: string;
 }
 
 // ---------------------------------------------------------------------------

package/dist/builtin/workflows/src/extension/runtime.ts

@@ -190,6 +190,8 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
       maxOutput,
       artifacts,
       worktree,
+      gitWorktreeDir,
+      baseBranch,
       ...stageOptions
     } = args;
 
@@ -206,6 +208,8 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
       ...(maxOutput !== undefined ? { maxOutput } : {}),
       ...(typeof artifacts === "boolean" ? { artifacts } : {}),
       ...(typeof worktree === "boolean" ? { worktree } : {}),
+      ...(typeof gitWorktreeDir === "string" ? { gitWorktreeDir } : {}),
+      ...(typeof baseBranch === "string" ? { baseBranch } : {}),
     };
   }
 

package/dist/builtin/workflows/src/extension/workflow-schema.ts

@@ -66,6 +66,8 @@ const WorkflowTaskOptionProperties = {
   outputMode: Type.Optional(Type.Union([Type.Literal("inline"), Type.Literal("file-only")])),
   reads: Type.Optional(Type.Union([Type.Array(Type.String()), Type.Literal(false)])),
   worktree: Type.Optional(Type.Boolean()),
+  gitWorktreeDir: Type.Optional(Type.String()),
+  baseBranch: Type.Optional(Type.String()),
   maxOutput: Type.Optional(MaxOutputSchema),
   artifacts: Type.Optional(Type.Boolean()),
 };
@@ -83,6 +85,8 @@ const ParallelChainStepSchema = Type.Object({
   concurrency: Type.Optional(Type.Number()),
   failFast: Type.Optional(Type.Boolean()),
   worktree: Type.Optional(Type.Boolean()),
+  gitWorktreeDir: Type.Optional(Type.String()),
+  baseBranch: Type.Optional(Type.String()),
 });
 
 export const WorkflowParametersSchema = Type.Object({

package/dist/builtin/workflows/src/runs/foreground/executor.ts

@@ -56,6 +56,7 @@ import {
   createWorktrees,
   diffWorktrees,
   findWorktreeTaskCwdConflict,
+  setupGitWorktree,
   formatWorktreeDiffSummary,
   formatWorktreeTaskCwdConflict,
   type WorktreeSetup,
@@ -82,6 +83,8 @@ export interface RunContinuationOpts {
 
 export interface RunOpts {
   adapters?: StageAdapters;
+  /** Invocation working directory exposed to workflow definitions as ctx.cwd. */
+  cwd?: string;
   /** HIL adapter injected by the pi runtime or test harness. */
   ui?: WorkflowUIAdapter;
   /** Internal detached-run mode: surface ctx.ui.* as node-local workflow prompt stages. */
@@ -186,6 +189,23 @@ function resolveInputConcurrency(
   return Math.floor(value);
 }
 
+function resolveInputRuntimeDefaults(
+  def: Pick<WorkflowDefinition, "inputBindings">,
+  resolvedInputs: ResolvedInputs,
+): Partial<StageOptions> {
+  const defaults: Partial<StageOptions> = {};
+  const worktree = def.inputBindings?.worktree;
+  if (worktree !== undefined) {
+    const gitWorktreeDir = resolvedInputs[worktree.gitWorktreeDir];
+    if (typeof gitWorktreeDir === "string" && gitWorktreeDir.trim().length > 0) {
+      defaults.gitWorktreeDir = gitWorktreeDir;
+      const baseBranch = worktree.baseBranch === undefined ? undefined : resolvedInputs[worktree.baseBranch];
+      if (typeof baseBranch === "string") defaults.baseBranch = baseBranch;
+    }
+  }
+  return defaults;
+}
+
 // ---------------------------------------------------------------------------
 // HIL unavailable fallback — rejects with precise per-primitive error
 // ---------------------------------------------------------------------------
@@ -397,6 +417,8 @@ function taskStageOptions(options: WorkflowTaskExecutionOptions): StageOptions {
     outputMode: _outputMode,
     reads: _reads,
     worktree: _worktree,
+    gitWorktreeDir: _gitWorktreeDir,
+    baseBranch: _baseBranch,
     maxOutput: _maxOutput,
     artifacts: _artifacts,
     ...stageOptions
@@ -550,6 +572,8 @@ function directTaskWithDefaults(
     output,
     outputMode,
     worktree,
+    gitWorktreeDir,
+    baseBranch,
     maxOutput,
     artifacts,
     ...stageDefaults
@@ -567,6 +591,8 @@ function directTaskWithDefaults(
     ...(item.output === undefined && output !== undefined ? { output } : {}),
     ...(item.outputMode === undefined && outputMode !== undefined ? { outputMode } : {}),
     ...(item.worktree === undefined && worktree !== undefined ? { worktree } : {}),
+    ...(item.gitWorktreeDir === undefined && gitWorktreeDir !== undefined ? { gitWorktreeDir } : {}),
+    ...(item.baseBranch === undefined && baseBranch !== undefined ? { baseBranch } : {}),
     ...(item.maxOutput === undefined && maxOutput !== undefined ? { maxOutput } : {}),
     ...(item.artifacts === undefined && artifacts !== undefined ? { artifacts } : {}),
   };
@@ -714,6 +740,42 @@ function normalizeDirectTaskCwd(cwd: string | undefined): string | undefined {
   return isAbsolute(cwd) ? cwd : resolve(process.cwd(), cwd);
 }
 
+function resolveWorktreeCwdOverride(cwd: string | undefined, worktreeCwd: string): string | undefined {
+  if (cwd === undefined || cwd.length === 0) return undefined;
+  return isAbsolute(cwd) ? cwd : resolve(worktreeCwd, cwd);
+}
+
+function stageOptionsWithInputDefaults<T extends StageOptions>(options: T | undefined, inputDefaults: Partial<StageOptions>): T | undefined {
+  const defaults = withoutUndefinedProperties(inputDefaults);
+  if (Object.keys(defaults).length === 0) return options;
+  return { ...defaults, ...withoutUndefinedProperties(options ?? {}) } as T;
+}
+
+function stageOptionsWithGitWorktree<T extends StageOptions>(options: T | undefined, workflowInvocationCwd: string): T | undefined {
+  if (options === undefined) return undefined;
+  if (typeof options.gitWorktreeDir !== "string" || options.gitWorktreeDir.trim().length === 0) {
+    return options;
+  }
+  const setup = setupGitWorktree({
+    gitWorktreeDir: options.gitWorktreeDir,
+    baseBranch: options.baseBranch,
+    cwd: workflowInvocationCwd,
+  });
+  const explicitCwd = resolveWorktreeCwdOverride(options.cwd, setup.cwd);
+  return { ...options, gitWorktreeDir: undefined, baseBranch: undefined, cwd: explicitCwd ?? setup.cwd };
+}
+
+function workflowCwdWithInputWorktree(inputDefaults: Partial<StageOptions>, workflowInvocationCwd: string): string {
+  if (typeof inputDefaults.gitWorktreeDir !== "string" || inputDefaults.gitWorktreeDir.trim().length === 0) {
+    return workflowInvocationCwd;
+  }
+  return setupGitWorktree({
+    gitWorktreeDir: inputDefaults.gitWorktreeDir,
+    baseBranch: inputDefaults.baseBranch,
+    cwd: workflowInvocationCwd,
+  }).cwd;
+}
+
 function directWorktreeDiffsDir(options: WorkflowDirectOptions, setup: WorktreeSetup, runId: string, scope: string): string {
   const baseDir = options.chainDir ?? join(setup.cwd, CONFIG_DIR_NAME, "workflows");
   return join(baseDir, "worktree-diffs", runId, scope);
@@ -732,6 +794,10 @@ function prepareDirectWorktrees(
     };
   }
 
+  if (typeof options.gitWorktreeDir === "string" || tasks.some((task) => typeof task.gitWorktreeDir === "string")) {
+    throw new Error("pi-workflows: worktree and gitWorktreeDir are mutually exclusive; use gitWorktreeDir for a reusable worktree or worktree:true for temporary isolated worktrees.");
+  }
+
   const sharedCwd = resolveSharedDirectWorktreeCwd(tasks);
   const conflict = findWorktreeTaskCwdConflict(
     tasks.map((task) => ({ agent: task.name, cwd: normalizeDirectTaskCwd(task.cwd) })),
@@ -884,6 +950,13 @@ function workflowDetailsFromRun(
   };
 }
 
+const EMPTY_WORKFLOW_GRAPH_ERROR_MESSAGE = "Workflow run completed without creating any workflow stages. Create at least one stage with ctx.stage(), ctx.task(), ctx.chain(), or ctx.parallel().";
+
+function assertWorkflowCreatedStage(runSnapshot: RunSnapshot): void {
+  if (runSnapshot.stages.length > 0) return;
+  throw new Error(EMPTY_WORKFLOW_GRAPH_ERROR_MESSAGE);
+}
+
 function defineDirectWorkflow(
   name: string,
   runFn: WorkflowDefinition["run"],
@@ -1010,8 +1083,13 @@ async function runDirectChainStep(
   runId: string,
 ): Promise<{ results: WorkflowTaskResult[]; artifacts: WorkflowArtifact[] }> {
   if ("parallel" in step) {
-    const expanded = expandedParallelTasks(step.parallel.map((item) => directTaskWithDefaults(item, options)));
-    const stepOptions = { ...options, worktree: options.worktree === true || step.worktree === true };
+    const stepOptions = {
+      ...options,
+      worktree: options.worktree === true || step.worktree === true,
+      ...(step.gitWorktreeDir !== undefined ? { gitWorktreeDir: step.gitWorktreeDir } : {}),
+      ...(step.baseBranch !== undefined ? { baseBranch: step.baseBranch } : {}),
+    };
+    const expanded = expandedParallelTasks(step.parallel.map((item) => directTaskWithDefaults(item, stepOptions)));
     const prepared = prepareDirectWorktrees(expanded, stepOptions, `${runId}-s${index}`, `step-${index}`);
     try {
       const steps = prepared.tasks.map((item) =>
@@ -1485,6 +1563,13 @@ export async function run<TInputs extends Record<string, unknown>>(
   // 4. Create GraphFrontierTracker and per-run ConcurrencyLimiter
   const tracker = new GraphFrontierTracker();
   const inputConcurrency = resolveInputConcurrency(def.inputs, resolvedInputs);
+  const inputRuntimeDefaults = resolveInputRuntimeDefaults(def, resolvedInputs);
+  const workflowInvocationCwd = opts.cwd ?? process.cwd();
+  let workflowCwd: string | undefined;
+  const resolveWorkflowCwd = (): string => {
+    workflowCwd ??= workflowCwdWithInputWorktree(inputRuntimeDefaults, workflowInvocationCwd);
+    return workflowCwd;
+  };
   const limiter = createRunLimiter(inputConcurrency ?? opts.config?.defaultConcurrency);
   interface ReleaseBarrier {
     readonly promise: Promise<void>;
@@ -1819,11 +1904,13 @@ export async function run<TInputs extends Record<string, unknown>>(
   // 5. Build WorkflowRunContext
   const ctx: WorkflowRunContext<TInputs> = {
     inputs: resolvedInputs as TInputs,
+    get cwd() { return resolveWorkflowCwd(); },
     // Prompt nodes and caller-provided UI adapters are mutually exclusive;
     // executor-owned prompt nodes intentionally take precedence when enabled.
     ui: opts.usePromptNodesForUi === true ? buildPromptNodeUiAdapter() : opts.ui ?? makeUnavailableUIContext(),
 
     stage(name: string, options?: StageOptions, stageFailFastScope?: ParallelFailFastScope) {
+      options = stageOptionsWithGitWorktree(stageOptionsWithInputDefaults(options, inputRuntimeDefaults), workflowInvocationCwd);
       // a. Generate stageId
       const stageId = crypto.randomUUID();
 
@@ -2369,16 +2456,17 @@ export async function run<TInputs extends Record<string, unknown>>(
 
     async task(name: string, options: WorkflowTaskOptions, stageFailFastScope?: ParallelFailFastScope): Promise<WorkflowTaskResult> {
       const runTaskOnce = async (taskOptions: WorkflowTaskOptions): Promise<WorkflowTaskResult> => {
+        const resolvedTaskOptions = stageOptionsWithGitWorktree(stageOptionsWithInputDefaults(taskOptions, inputRuntimeDefaults), workflowInvocationCwd) ?? taskOptions;
         const stage = (ctx.stage as typeof ctx.stage & ((stageName: string, stageOptions?: StageOptions, scope?: ParallelFailFastScope) => StageContext))(
           name,
-          taskStageOptions(taskOptions),
+          taskStageOptions(resolvedTaskOptions),
           stageFailFastScope,
         );
         const rawText = await stage.prompt(
-          applyTaskContext(`${taskReadInstruction(taskOptions)}${taskPrompt(taskOptions)}`, taskPrevious(taskOptions)),
-          taskPromptOptions(taskOptions),
+          applyTaskContext(`${taskReadInstruction(resolvedTaskOptions)}${taskPrompt(resolvedTaskOptions)}`, taskPrevious(resolvedTaskOptions)),
+          taskPromptOptions(resolvedTaskOptions),
         );
-        const text = truncateTaskOutput(rawText, taskOptions.maxOutput);
+        const text = truncateTaskOutput(rawText, resolvedTaskOptions.maxOutput);
         const sessionId = (() => {
           try {
             return stage.sessionId;
@@ -2475,6 +2563,8 @@ export async function run<TInputs extends Record<string, unknown>>(
       return finalizeKilled(runId, runSnapshot, activeStore, opts.persistence, opts.onRunEnd);
     }
 
+    assertWorkflowCreatedStage(runSnapshot);
+
     const recorded = activeStore.recordRunEnd(runId, "completed", result);
     opts.onRunEnd?.(runId, "completed", result);
 

package/dist/builtin/workflows/src/runs/foreground/stage-runner.ts

@@ -144,6 +144,8 @@ function stripWorkflowOnlyOptions(options: StageOptions | undefined): CreateAgen
     context,
     forkFromSessionFile,
     sessionDir,
+    gitWorktreeDir: _gitWorktreeDir,
+    baseBranch: _baseBranch,
     ...sessionOptions
   } = options;
   if (sessionOptions.sessionManager === undefined) {

package/dist/builtin/workflows/src/runs/shared/workflow-runner.ts

@@ -45,6 +45,8 @@ export interface WorkflowDefinition extends StageOptions {
   output?: string | false;
   outputMode?: WorkflowOutputMode;
   worktree?: boolean;
+  gitWorktreeDir?: string;
+  baseBranch?: string;
   maxOutput?: WorkflowMaxOutput;
   artifacts?: boolean;
 }
@@ -91,6 +93,7 @@ function runOptionsWithAdapters(
 
   return {
     ...options.runOptions,
+    cwd: options.cwd ?? options.runOptions?.cwd,
     ...(config !== undefined ? { config } : {}),
     adapters: buildRuntimeAdapters(options.pi ?? {}, adapterOptions),
     store: createStore(),
@@ -164,6 +167,8 @@ function directOptions(definition: WorkflowDefinition): WorkflowDirectOptions {
     output,
     outputMode,
     worktree,
+    gitWorktreeDir,
+    baseBranch,
     maxOutput,
     artifacts,
     ...stageOptions
@@ -180,6 +185,8 @@ function directOptions(definition: WorkflowDefinition): WorkflowDirectOptions {
     ...(output !== undefined ? { output } : {}),
     ...(outputMode !== undefined ? { outputMode } : {}),
     ...(typeof worktree === "boolean" ? { worktree } : {}),
+    ...(typeof gitWorktreeDir === "string" ? { gitWorktreeDir } : {}),
+    ...(typeof baseBranch === "string" ? { baseBranch } : {}),
     ...(maxOutput !== undefined ? { maxOutput } : {}),
     ...(typeof artifacts === "boolean" ? { artifacts } : {}),
   };