@miller-tech/uap 2.36.1 → 2.39.0

package/dist/workflow/types.d.ts

@@ -0,0 +1,400 @@
+/**
+ * Declarative workflow types — the static layer over the blackboard
+ * orchestrator.
+ *
+ * WHY THIS EXISTS. The orchestrator (src/delivery/task-orchestrator.ts)
+ * executes a task DAG with fresh minimal contexts, bounded repair, and
+ * resume-at-the-boundary — but the DAG it runs is MODEL-AUTHORED at runtime
+ * (decompose.ts), so every mission re-plans itself and nothing is a durable,
+ * inspectable, reusable asset. The measured alternative (Memdoor's
+ * team-solve, GVS5H's method: five Qwen3.8-27B roles beating a frontier
+ * single-call on LiveCodeBench Hard at 9.8 vs 8.0) is a workflow authored
+ * ONCE as data — fixed role prompts, `requires:` edges, deterministic
+ * command steps — pointed at whatever model is serving.
+ *
+ * This module is the file format: a `workflow.yaml` plus role-prompt files.
+ * The runner (runner.ts) maps these steps onto `orchestrate()` unchanged, so
+ * the graph semantics (dependency-triggered dispatch, skip cascade, minimal
+ * repair, resume) are the validated delivery semantics, not a reimplementation.
+ */
+import { z } from 'zod';
+/** Step kinds. Each maps to one execution seam in the runner. */
+export declare const STEP_KINDS: readonly ["agent", "command", "gate", "loop"];
+export type StepKind = (typeof STEP_KINDS)[number];
+declare const WorkflowStepSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<["agent", "command", "gate", "loop"]>;
+    /** Human label for logs; defaults to the id. */
+    title: z.ZodOptional<z.ZodString>;
+    /**
+     * Per-step model pin — a ModelPresets id (e.g. `qwen38-27b`, the local
+     * strata arm through the proxy). Absent = the workflow default, then the
+     * CLI pin, then the local fleet default. Mirrors the decompose C2 per-leaf
+     * model dial: the plan (here: the author) decides which rung each step pays.
+     */
+    model: z.ZodOptional<z.ZodString>;
+    /**
+     * Path to the role-prompt file, relative to the workflow directory.
+     * Agent steps take `prompt` XOR `goal` — a file keeps the workflow.yaml
+     * reviewable while the role prompt stays a first-class artifact (the
+     * Memdoor layout: one file per step). Loop steps take the same pair:
+     * the role instruction the convergence loop executes against.
+     */
+    prompt: z.ZodOptional<z.ZodString>;
+    /** Inline role prompt (alternative to `prompt:`). */
+    goal: z.ZodOptional<z.ZodString>;
+    /** Run-directory files whose CONTENTS are inlined into the agent prompt. */
+    reads: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Run-directory files this step produces. The first entry receives the
+     * agent reply (or the command's captured output); the rest are declared
+     * for the graph's write-collision check. Overwrite semantics — the file
+     * ledger is authoritative, chat is not. NOT for loop steps: a loop works
+     * the project tree (its DeliveryResult is the blackboard entry), not the
+     * run directory.
+     */
+    writes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** DAG edges: step ids that must SUCCEED before this one runs. */
+    requires: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Acceptance criteria lines — assembled into the agent prompt. */
+    criteria: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** command kind: shell line, run with cwd = the run directory. */
+    command: z.ZodOptional<z.ZodString>;
+    /**
+     * command kind: capture the output but never fail the run — Memdoor's
+     * `test` step ("test-output.log (never fails the run)"). The verdict step
+     * is simply a command WITHOUT this flag: a nonzero exit fails the run.
+     */
+    neverFails: z.ZodOptional<z.ZodBoolean>;
+    /** command kind: kill the command after this many ms (default 120000). */
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    /** gate kind: prompt shown when the run pauses for approval. */
+    approvalPrompt: z.ZodOptional<z.ZodString>;
+    /**
+     * gate kind: maximum ms to WAIT for `uap workflow approve` before
+     * reporting the run as blocked (exit 2, resumable). 0 = never wait:
+     * pause immediately. Default 0 — approval is an operator act, not
+     * something a headless run should block a terminal on.
+     */
+    waitMs: z.ZodOptional<z.ZodNumber>;
+    /**
+     * loop kind: max executor turns for the convergence loop this step runs
+     * (the caller's default applies when absent). The loop's exit condition
+     * is the project's real completion gates — this bounds the attempt
+     * budget, it does not replace verification.
+     */
+    turns: z.ZodOptional<z.ZodNumber>;
+    /**
+     * loop kind: run the gates ONLY — no executor turns. The independent
+     * final verdict after repair steps: a green repair is not "delivered"
+     * until a verify-only pass says so.
+     */
+    verifyOnly: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    kind: "command" | "agent" | "loop" | "gate";
+    model?: string | undefined;
+    goal?: string | undefined;
+    command?: string | undefined;
+    title?: string | undefined;
+    turns?: number | undefined;
+    prompt?: string | undefined;
+    timeoutMs?: number | undefined;
+    criteria?: string[] | undefined;
+    writes?: string[] | undefined;
+    reads?: string[] | undefined;
+    requires?: string[] | undefined;
+    neverFails?: boolean | undefined;
+    approvalPrompt?: string | undefined;
+    waitMs?: number | undefined;
+    verifyOnly?: boolean | undefined;
+}, {
+    id: string;
+    kind: "command" | "agent" | "loop" | "gate";
+    model?: string | undefined;
+    goal?: string | undefined;
+    command?: string | undefined;
+    title?: string | undefined;
+    turns?: number | undefined;
+    prompt?: string | undefined;
+    timeoutMs?: number | undefined;
+    criteria?: string[] | undefined;
+    writes?: string[] | undefined;
+    reads?: string[] | undefined;
+    requires?: string[] | undefined;
+    neverFails?: boolean | undefined;
+    approvalPrompt?: string | undefined;
+    waitMs?: number | undefined;
+    verifyOnly?: boolean | undefined;
+}>;
+declare const WorkflowDefSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    /**
+     * Default model pin for steps that do not name one. The full resolution
+     * order is step.model → defaultModel → CLI --model → the local fleet
+     * default (see cli/workflow.ts) — the workflow names no model and stays
+     * portable across whatever arm is serving.
+     */
+    defaultModel: z.ZodOptional<z.ZodString>;
+    /**
+     * Max concurrent INDEPENDENT steps (clamped to [1,16] by the
+     * orchestrator). Agent steps are stateless completions writing distinct
+     * files, so >1 is safe for the steps that declare disjoint `writes`; the
+     * loader rejects shared write targets across PARALLEL siblings.
+     * Default 1 — one local rail serves one completion at a time.
+     */
+    parallel: z.ZodOptional<z.ZodNumber>;
+    /**
+     * Bounded fresh re-execution of a failed step before its dependents are
+     * blocked (orchestrator maxRepairsPerTask). Env hard-ceiling 5 applies.
+     * Default: the orchestrator's (1).
+     */
+    maxRepairsPerStep: z.ZodOptional<z.ZodNumber>;
+    /** Assembled-prompt budget in chars (orchestrator contextBudgetChars). */
+    contextBudgetChars: z.ZodOptional<z.ZodNumber>;
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<["agent", "command", "gate", "loop"]>;
+        /** Human label for logs; defaults to the id. */
+        title: z.ZodOptional<z.ZodString>;
+        /**
+         * Per-step model pin — a ModelPresets id (e.g. `qwen38-27b`, the local
+         * strata arm through the proxy). Absent = the workflow default, then the
+         * CLI pin, then the local fleet default. Mirrors the decompose C2 per-leaf
+         * model dial: the plan (here: the author) decides which rung each step pays.
+         */
+        model: z.ZodOptional<z.ZodString>;
+        /**
+         * Path to the role-prompt file, relative to the workflow directory.
+         * Agent steps take `prompt` XOR `goal` — a file keeps the workflow.yaml
+         * reviewable while the role prompt stays a first-class artifact (the
+         * Memdoor layout: one file per step). Loop steps take the same pair:
+         * the role instruction the convergence loop executes against.
+         */
+        prompt: z.ZodOptional<z.ZodString>;
+        /** Inline role prompt (alternative to `prompt:`). */
+        goal: z.ZodOptional<z.ZodString>;
+        /** Run-directory files whose CONTENTS are inlined into the agent prompt. */
+        reads: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * Run-directory files this step produces. The first entry receives the
+         * agent reply (or the command's captured output); the rest are declared
+         * for the graph's write-collision check. Overwrite semantics — the file
+         * ledger is authoritative, chat is not. NOT for loop steps: a loop works
+         * the project tree (its DeliveryResult is the blackboard entry), not the
+         * run directory.
+         */
+        writes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** DAG edges: step ids that must SUCCEED before this one runs. */
+        requires: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** Acceptance criteria lines — assembled into the agent prompt. */
+        criteria: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** command kind: shell line, run with cwd = the run directory. */
+        command: z.ZodOptional<z.ZodString>;
+        /**
+         * command kind: capture the output but never fail the run — Memdoor's
+         * `test` step ("test-output.log (never fails the run)"). The verdict step
+         * is simply a command WITHOUT this flag: a nonzero exit fails the run.
+         */
+        neverFails: z.ZodOptional<z.ZodBoolean>;
+        /** command kind: kill the command after this many ms (default 120000). */
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        /** gate kind: prompt shown when the run pauses for approval. */
+        approvalPrompt: z.ZodOptional<z.ZodString>;
+        /**
+         * gate kind: maximum ms to WAIT for `uap workflow approve` before
+         * reporting the run as blocked (exit 2, resumable). 0 = never wait:
+         * pause immediately. Default 0 — approval is an operator act, not
+         * something a headless run should block a terminal on.
+         */
+        waitMs: z.ZodOptional<z.ZodNumber>;
+        /**
+         * loop kind: max executor turns for the convergence loop this step runs
+         * (the caller's default applies when absent). The loop's exit condition
+         * is the project's real completion gates — this bounds the attempt
+         * budget, it does not replace verification.
+         */
+        turns: z.ZodOptional<z.ZodNumber>;
+        /**
+         * loop kind: run the gates ONLY — no executor turns. The independent
+         * final verdict after repair steps: a green repair is not "delivered"
+         * until a verify-only pass says so.
+         */
+        verifyOnly: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        kind: "command" | "agent" | "loop" | "gate";
+        model?: string | undefined;
+        goal?: string | undefined;
+        command?: string | undefined;
+        title?: string | undefined;
+        turns?: number | undefined;
+        prompt?: string | undefined;
+        timeoutMs?: number | undefined;
+        criteria?: string[] | undefined;
+        writes?: string[] | undefined;
+        reads?: string[] | undefined;
+        requires?: string[] | undefined;
+        neverFails?: boolean | undefined;
+        approvalPrompt?: string | undefined;
+        waitMs?: number | undefined;
+        verifyOnly?: boolean | undefined;
+    }, {
+        id: string;
+        kind: "command" | "agent" | "loop" | "gate";
+        model?: string | undefined;
+        goal?: string | undefined;
+        command?: string | undefined;
+        title?: string | undefined;
+        turns?: number | undefined;
+        prompt?: string | undefined;
+        timeoutMs?: number | undefined;
+        criteria?: string[] | undefined;
+        writes?: string[] | undefined;
+        reads?: string[] | undefined;
+        requires?: string[] | undefined;
+        neverFails?: boolean | undefined;
+        approvalPrompt?: string | undefined;
+        waitMs?: number | undefined;
+        verifyOnly?: boolean | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    steps: {
+        id: string;
+        kind: "command" | "agent" | "loop" | "gate";
+        model?: string | undefined;
+        goal?: string | undefined;
+        command?: string | undefined;
+        title?: string | undefined;
+        turns?: number | undefined;
+        prompt?: string | undefined;
+        timeoutMs?: number | undefined;
+        criteria?: string[] | undefined;
+        writes?: string[] | undefined;
+        reads?: string[] | undefined;
+        requires?: string[] | undefined;
+        neverFails?: boolean | undefined;
+        approvalPrompt?: string | undefined;
+        waitMs?: number | undefined;
+        verifyOnly?: boolean | undefined;
+    }[];
+    description?: string | undefined;
+    parallel?: number | undefined;
+    defaultModel?: string | undefined;
+    maxRepairsPerStep?: number | undefined;
+    contextBudgetChars?: number | undefined;
+}, {
+    name: string;
+    steps: {
+        id: string;
+        kind: "command" | "agent" | "loop" | "gate";
+        model?: string | undefined;
+        goal?: string | undefined;
+        command?: string | undefined;
+        title?: string | undefined;
+        turns?: number | undefined;
+        prompt?: string | undefined;
+        timeoutMs?: number | undefined;
+        criteria?: string[] | undefined;
+        writes?: string[] | undefined;
+        reads?: string[] | undefined;
+        requires?: string[] | undefined;
+        neverFails?: boolean | undefined;
+        approvalPrompt?: string | undefined;
+        waitMs?: number | undefined;
+        verifyOnly?: boolean | undefined;
+    }[];
+    description?: string | undefined;
+    parallel?: number | undefined;
+    defaultModel?: string | undefined;
+    maxRepairsPerStep?: number | undefined;
+    contextBudgetChars?: number | undefined;
+}>;
+export type WorkflowStep = z.infer<typeof WorkflowStepSchema>;
+export type WorkflowDef = z.infer<typeof WorkflowDefSchema>;
+/** The parsed + validated workflow, ready for the runner. */
+export interface LoadedWorkflow {
+    /** Absolute path of the workflow directory (workflow.yaml's dir). */
+    dir: string;
+    def: WorkflowDef;
+    /**
+     * Role-prompt text per agent step id, resolved from `prompt:` files at
+     * load time — fail-closed: a missing prompt file is a load error, never a
+     * silent empty role.
+     */
+    rolePrompts: Map<string, string>;
+}
+export declare const WORKFLOW_FILE = "workflow.yaml";
+/** Run lifecycle status, persisted to run-state.json after every change. */
+export type WorkflowRunStatus = 'running' | 'succeeded' | 'failed' | 'blocked';
+/**
+ * The persisted run state. `done` carries exactly what the orchestrator's
+ * onProgress emits — id + summary (+ contract) — so a resume seeds
+ * orchestrate.initialDone and finished work is never redone.
+ */
+export interface WorkflowRunState {
+    runId: string;
+    workflow: string;
+    status: WorkflowRunStatus;
+    startedAt: string;
+    updatedAt: string;
+    endedAt?: string;
+    /** One-line mission text (orientation for every step context). */
+    mission: string;
+    /** Cumulative accepted steps (orchestrator onProgress payload). */
+    done: Array<{
+        id: string;
+        summary: string;
+        contract?: string;
+    }>;
+    /** Failed step ids from the last attempt (informational on resume). */
+    failed: string[];
+}
+/** Exit-code contract — CI/cron can branch without parsing output. */
+export declare const WORKFLOW_EXIT: {
+    readonly ok: 0;
+    /** A step failed (and its repairs); dependents were skipped. */
+    readonly stepFailed: 1;
+    /** The run paused at a gate awaiting approval — resumable. */
+    readonly blocked: 2;
+    /** The workflow file itself is invalid — never retriable as-is. */
+    readonly invalid: 3;
+};
+/**
+ * The convergence-loop seam for `kind: loop` steps — the composition point
+ * where a workflow DIRECTS delivery machinery. The caller owns loop
+ * construction (deliver wires its ConvergenceLoop / mission dispatch);
+ * the engine owns assembly (role instruction + dependency outputs + reads)
+ * and the graph semantics around it. `stepId` lets one seam serve several
+ * roles (solve vs repair vs a verify-only verdict).
+ */
+export type LoopStepExecutor = (args: {
+    stepId: string;
+    /** Assembled instruction: role prompt + direct-dependency outputs + reads. */
+    prompt: string;
+    /** The step's model pin, when the workflow names one. */
+    model?: string;
+    /** A verify-only step: gates, no executor turns. */
+    verifyOnly?: boolean;
+    /** The step's turns bound, when the workflow names one. */
+    turns?: number;
+}) => Promise<{
+    success: boolean;
+    summary: string;
+    turns?: number;
+}>;
+/**
+ * Per-step role-call seam for agent steps — lets a caller with its own
+ * executor rails (deliver's generator/judge plan) drive role steps through
+ * them instead of a raw model client, preserving its discipline.
+ */
+export type StepCallExecutor = (step: {
+    id: string;
+    kind: StepKind;
+}, prompt: string) => Promise<string>;
+/** Narrow the raw parsed YAML into the typed def, with a flat error list. */
+export declare function parseWorkflowDef(raw: unknown): WorkflowDef;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/workflow/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/workflow/types.ts"],"names":[],"mappings":"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"}

package/dist/workflow/types.js

@@ -0,0 +1,147 @@
+/**
+ * Declarative workflow types — the static layer over the blackboard
+ * orchestrator.
+ *
+ * WHY THIS EXISTS. The orchestrator (src/delivery/task-orchestrator.ts)
+ * executes a task DAG with fresh minimal contexts, bounded repair, and
+ * resume-at-the-boundary — but the DAG it runs is MODEL-AUTHORED at runtime
+ * (decompose.ts), so every mission re-plans itself and nothing is a durable,
+ * inspectable, reusable asset. The measured alternative (Memdoor's
+ * team-solve, GVS5H's method: five Qwen3.8-27B roles beating a frontier
+ * single-call on LiveCodeBench Hard at 9.8 vs 8.0) is a workflow authored
+ * ONCE as data — fixed role prompts, `requires:` edges, deterministic
+ * command steps — pointed at whatever model is serving.
+ *
+ * This module is the file format: a `workflow.yaml` plus role-prompt files.
+ * The runner (runner.ts) maps these steps onto `orchestrate()` unchanged, so
+ * the graph semantics (dependency-triggered dispatch, skip cascade, minimal
+ * repair, resume) are the validated delivery semantics, not a reimplementation.
+ */
+import { z } from 'zod';
+/** Step kinds. Each maps to one execution seam in the runner. */
+export const STEP_KINDS = ['agent', 'command', 'gate', 'loop'];
+/**
+ * File-system discipline for step ids: lowercase slug, no dots — a repair
+ * chain namespaces links as `<id>.r0-…` (task-orchestrator.ts) and a dot in
+ * the base id would blur that boundary in run-state.json.
+ */
+const STEP_ID_RE = /^[a-z0-9][a-z0-9-]*$/;
+const WorkflowStepSchema = z.object({
+    id: z.string().regex(STEP_ID_RE, 'step id must be a lowercase slug (a-z, 0-9, -)'),
+    kind: z.enum(STEP_KINDS),
+    /** Human label for logs; defaults to the id. */
+    title: z.string().min(1).optional(),
+    /**
+     * Per-step model pin — a ModelPresets id (e.g. `qwen38-27b`, the local
+     * strata arm through the proxy). Absent = the workflow default, then the
+     * CLI pin, then the local fleet default. Mirrors the decompose C2 per-leaf
+     * model dial: the plan (here: the author) decides which rung each step pays.
+     */
+    model: z.string().min(1).optional(),
+    /**
+     * Path to the role-prompt file, relative to the workflow directory.
+     * Agent steps take `prompt` XOR `goal` — a file keeps the workflow.yaml
+     * reviewable while the role prompt stays a first-class artifact (the
+     * Memdoor layout: one file per step). Loop steps take the same pair:
+     * the role instruction the convergence loop executes against.
+     */
+    prompt: z.string().min(1).optional(),
+    /** Inline role prompt (alternative to `prompt:`). */
+    goal: z.string().min(1).optional(),
+    /** Run-directory files whose CONTENTS are inlined into the agent prompt. */
+    reads: z.array(z.string().min(1)).optional(),
+    /**
+     * Run-directory files this step produces. The first entry receives the
+     * agent reply (or the command's captured output); the rest are declared
+     * for the graph's write-collision check. Overwrite semantics — the file
+     * ledger is authoritative, chat is not. NOT for loop steps: a loop works
+     * the project tree (its DeliveryResult is the blackboard entry), not the
+     * run directory.
+     */
+    writes: z.array(z.string().min(1)).optional(),
+    /** DAG edges: step ids that must SUCCEED before this one runs. */
+    requires: z.array(z.string().min(1)).optional(),
+    /** Acceptance criteria lines — assembled into the agent prompt. */
+    criteria: z.array(z.string().min(1)).optional(),
+    /** command kind: shell line, run with cwd = the run directory. */
+    command: z.string().min(1).optional(),
+    /**
+     * command kind: capture the output but never fail the run — Memdoor's
+     * `test` step ("test-output.log (never fails the run)"). The verdict step
+     * is simply a command WITHOUT this flag: a nonzero exit fails the run.
+     */
+    neverFails: z.boolean().optional(),
+    /** command kind: kill the command after this many ms (default 120000). */
+    timeoutMs: z.number().int().positive().optional(),
+    /** gate kind: prompt shown when the run pauses for approval. */
+    approvalPrompt: z.string().min(1).optional(),
+    /**
+     * gate kind: maximum ms to WAIT for `uap workflow approve` before
+     * reporting the run as blocked (exit 2, resumable). 0 = never wait:
+     * pause immediately. Default 0 — approval is an operator act, not
+     * something a headless run should block a terminal on.
+     */
+    waitMs: z.number().int().nonnegative().optional(),
+    /**
+     * loop kind: max executor turns for the convergence loop this step runs
+     * (the caller's default applies when absent). The loop's exit condition
+     * is the project's real completion gates — this bounds the attempt
+     * budget, it does not replace verification.
+     */
+    turns: z.number().int().positive().optional(),
+    /**
+     * loop kind: run the gates ONLY — no executor turns. The independent
+     * final verdict after repair steps: a green repair is not "delivered"
+     * until a verify-only pass says so.
+     */
+    verifyOnly: z.boolean().optional(),
+});
+const WorkflowDefSchema = z.object({
+    name: z.string().regex(STEP_ID_RE, 'workflow name must be a lowercase slug'),
+    description: z.string().min(1).optional(),
+    /**
+     * Default model pin for steps that do not name one. The full resolution
+     * order is step.model → defaultModel → CLI --model → the local fleet
+     * default (see cli/workflow.ts) — the workflow names no model and stays
+     * portable across whatever arm is serving.
+     */
+    defaultModel: z.string().min(1).optional(),
+    /**
+     * Max concurrent INDEPENDENT steps (clamped to [1,16] by the
+     * orchestrator). Agent steps are stateless completions writing distinct
+     * files, so >1 is safe for the steps that declare disjoint `writes`; the
+     * loader rejects shared write targets across PARALLEL siblings.
+     * Default 1 — one local rail serves one completion at a time.
+     */
+    parallel: z.number().int().min(1).max(16).optional(),
+    /**
+     * Bounded fresh re-execution of a failed step before its dependents are
+     * blocked (orchestrator maxRepairsPerTask). Env hard-ceiling 5 applies.
+     * Default: the orchestrator's (1).
+     */
+    maxRepairsPerStep: z.number().int().min(0).max(5).optional(),
+    /** Assembled-prompt budget in chars (orchestrator contextBudgetChars). */
+    contextBudgetChars: z.number().int().positive().optional(),
+    steps: z.array(WorkflowStepSchema).min(1, 'a workflow needs at least one step'),
+});
+export const WORKFLOW_FILE = 'workflow.yaml';
+/** Exit-code contract — CI/cron can branch without parsing output. */
+export const WORKFLOW_EXIT = {
+    ok: 0,
+    /** A step failed (and its repairs); dependents were skipped. */
+    stepFailed: 1,
+    /** The run paused at a gate awaiting approval — resumable. */
+    blocked: 2,
+    /** The workflow file itself is invalid — never retriable as-is. */
+    invalid: 3,
+};
+/** Narrow the raw parsed YAML into the typed def, with a flat error list. */
+export function parseWorkflowDef(raw) {
+    const parsed = WorkflowDefSchema.safeParse(raw);
+    if (!parsed.success) {
+        const lines = parsed.error.issues.map((i) => `  - ${i.path.join('.')}: ${i.message}`);
+        throw new Error(`invalid workflow definition:\n${lines.join('\n')}`);
+    }
+    return parsed.data;
+}
+//# sourceMappingURL=types.js.map

package/dist/workflow/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/workflow/types.ts"],"names":[],"mappings":"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"}

package/docs/INDEX.md

@@ -50,6 +50,7 @@ Full map: **[The UAP Delivery Pipeline](guides/DELIVERY_PIPELINE.md)**.
 | [What UAP Does Automatically (compact)](guides/AUTOMATIC.md) | A shorter, trigger-by-trigger telling of the same ground as AUTOMATIC_FEATURES |
 | [**`uap deliver`**](guides/DELIVER.md) | The Build+QC harness — convergence loop to verified completion, tiered gates, CI/deploy feedback loop ⭐ |
 | [**Orchestrator & Hands-Free**](guides/ORCHESTRATOR.md) | The long-task autonomy layer — blackboard orchestrator, epic controller, completion ledger, auto-seed/resume; any model runs a huge build to 100% hands-free ⭐ |
+| [Workflows](guides/WORKFLOWS.md) | Static `workflow.yaml` step DAGs (agent/command/gate/loop) over the orchestrator — role relays with cross-correction, deterministic verdicts, resumable runs; bundled team-solve + the deliver-driven team-solve-deliver (`uap deliver --team-solve`, auto on high/critical) |
 | [**UAP Across Two Agents & Uplift**](guides/TWO_AGENTS_AND_UPLIFT.md) | The whole line applied seam-by-seam to opencode+Qwen3.6 (local) and Claude Code+Opus 4.8 (cloud), plus the benchmark that measures UAP uplift — diagrams + `benchmarks/suites/swe-bench-pro/` config |
 | [Memory](guides/MEMORY.md) | The 4-tier memory system, write-gates, semantic recall |
 | [MCP Router](guides/MCP_ROUTER.md) | Token-optimizing tool proxy + FTS5 output compression |

package/docs/architecture/adr/0013-declarative-workflow-layer.md

@@ -0,0 +1,99 @@
+# ADR 0013: Declarative workflow layer — static step DAGs over the orchestrator
+
+- Status: Accepted (amended by ADR 0014: a fourth step kind `loop`, the
+  caller-injected convergence-loop seam, and the team-solve-deliver
+  posture that `uap deliver` auto-engages on high/critical missions)
+- Date: 2026-11-03
+- Spec: `uap workflow` (src/workflow/, src/cli/workflow.ts,
+  examples/workflows/team-solve/, docs/guides/WORKFLOWS.md).
+- Supersedes: none — additive layer; `orchestrate()` and every existing
+  delivery surface are untouched.
+
+## Context
+
+UAP's task DAG machinery (ADR 0009's blackboard orchestrator) executes a
+graph of fresh-context tasks with bounded repair and resume — but the DAG it
+runs is model-authored at runtime (decompose.ts). Every mission re-plans
+itself; nothing about the plan is a durable, reviewable, reusable asset.
+
+The measured external counterpoint is GVS5H (Lee, 2026; reproduced by
+Memdoor's team-solve): five Qwen3.8-27B roles on a STATIC graph — planner,
+two parallel ideators from different algorithm families, solver, reviewer,
+repairer — talking only through files, judged only by a deterministic
+harness, matched the authors' own harness on LiveCodeBench Hard (9.8/10 vs
+9.6; a frontier single-call at 8.0). The claim is structure, not model
+class: the graph and the ledger discipline carried the result.
+
+UAP had the engine but not the declarative layer: no way to author the graph
+as data, pin models per step, run deterministic command steps as first-class
+nodes, or resume a blocked run — nothing a CI or a cron could execute as a
+file.
+
+## Decision
+
+1. **A workflow is data.** `.uap/workflows/<name>/workflow.yaml` (zod-
+   validated) + role-prompt files; search roots project → home → bundled
+   `examples/` (first hit wins). The loader is fail-closed: unique ids, known
+   `requires:`, cycle rejection (Kahn — topoOrder's fail-soft is right for
+   model-authored plans, wrong for a static file), kind/field confusion,
+   parallel write collision (graph-safety FALSE INDEPENDENCE, checked at
+   authoring time), run-dir path escapes, load-time model-pin validation,
+   reserved-path rejection.
+2. **`orchestrate()` is the engine, unchanged.** The runner maps three step
+   kinds onto its existing seams: `agent` (fresh single completion; role
+   prompt + direct-dependency summaries + inlined `reads:` files; the reply
+   IS `writes[0]`), `command` (spawnSync exit-code verdict; `neverFails`
+   evidence mode), `gate` (approval file → BLOCKED exit 2, resumable). No
+   graph logic is reimplemented; dependency-triggered dispatch, skip
+   cascade, bounded repair, and resume-at-the-boundary are inherited and
+   already tested by the orchestrator suite.
+3. **Files, not chat.** Steps communicate only through the run directory
+   (`.uap/workflow-runs/<runId>/`); each agent step starts from a fresh
+   context assembled from the file ledger. One deliberate divergence from
+   Memdoor: one reply → one file (overwrite semantics), not append-to-notes;
+   per-step files keep the ledger unambiguous.
+4. **Steps name no model.** Pin ladder: step → workflow `defaultModel` →
+   `--model` → the local fleet default (`qwen38-27b`, the strata arm through
+   the proxy). A workflow is portable across arms and endpoints without
+   edits; `--endpoint` covers non-local OpenAI-compatible servers.
+5. **Exit contract for CI/cron:** 0 ok · 1 step failed · 2 gate blocked
+   (resumable) · 3 invalid workflow. A real step defect never hides behind a
+   blocked gate (failed > blocked precedence).
+6. **Trust boundary is the npm-scripts class.** `command:` lines run a shell
+   as the invoking user; `--input` bundles are dereferenced on copy (no
+   symlink escapes) and cannot plant run-state.json; model replies are data
+   (prompts and files, never a shell); model-written code executes only via
+   authored commands, exactly like `deliver` gate scripts. Untrusted input
+   composes with `uap sandbox --net off` externally — no sandbox stub inside
+   the layer.
+7. **Validation is a gated option, not a claim.** O7 in
+   docs/plans/model-performance-proof-options.md: paired three-arm (single-
+   shot / deliver gate loop / team-solve workflow) on the same local model;
+   starts only on an explicit go, with the house rules (paired rates,
+   bootstrap CI, McNemar, discrimination status).
+
+## Alternatives considered
+
+- **Extend decompose.ts with static plan files** — rejected: couples the
+  declarative format to the model-planning path; a static workflow needs
+  different validation (fail-closed, not fail-soft) and different authoring
+  ergonomics than a runtime plan.
+- **Byte-port Memdoor's mario engine** — rejected: UAP already owns a
+  validated orchestrator with repair/resume semantics; a second engine would
+  duplicate them. The port keeps the METHOD (roles, ledger discipline,
+  deterministic verdict), not the bytes.
+- **Build workflows on droids/Task** — rejected: droid delegation is runtime
+  ad-hoc (the orchestrating model decides); a workflow must be executable
+  headless from a file, by CI, without any model in the driver's seat.
+
+## Consequences
+
+- `uap workflow list|show|run|status|resume|approve` joins the command
+  surface (additive; registration is one lazy-map entry + one block).
+- team-solve ships as the bundled flagship example and the O7 subject; its
+  published numbers belong to the authors (their harness, their host).
+- Known follow-ups (tracked, deliberate): a shared preset resolver for
+  deliver + workflow (the pin ladder's resolution discipline is currently
+  expressed twice); dashboard integration over run-state.json's stable JSON
+  seam; gate repair-attempt accounting (an unapproved gate consumes its
+  step's repair budget while waiting).