stageflow 0.2.0 → 0.8.0

package/dist/config/normalizePipelineStageEntry.js

@@ -0,0 +1,210 @@
+import path from "node:path";
+import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { BODY_KEYS, isAllowedPipelineStageEntryKey, } from "./pipelineStageKeys.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function inferIdFromUsesPath(usesPath) {
+    const base = path.basename(usesPath);
+    if (!base)
+        return null;
+    if (base.endsWith(".stage.yaml")) {
+        const id = base.slice(0, -".stage.yaml".length);
+        return id || null;
+    }
+    if (base.endsWith(".yaml")) {
+        const id = base.slice(0, -".yaml".length);
+        return id || null;
+    }
+    return base;
+}
+function extractBodyRaw(raw) {
+    const body = {};
+    for (const key of Object.keys(raw)) {
+        if (BODY_KEYS.has(key)) {
+            body[key] = raw[key];
+        }
+    }
+    return body;
+}
+function hasBodyKey(raw) {
+    return Object.keys(raw).some((key) => BODY_KEYS.has(key) && key !== "skill");
+}
+function readSkill(raw) {
+    if (raw.skill === undefined)
+        return undefined;
+    if (typeof raw.skill !== "string" || raw.skill.trim() === "") {
+        return loadFailure([
+            {
+                code: "stage.invalid_skill",
+                message: "skill must be a non-empty string",
+                category: "stage",
+            },
+        ]);
+    }
+    return loadSuccess(raw.skill.trim());
+}
+function stringStageRefMessage(index, declaringPath, entry) {
+    const hint = entry
+        ? `bare string stage refs are not supported; use { id: "${entry}", uses: "./${entry}.yaml" } or inline body`
+        : `bare string stage refs are not supported; use { id: "…", uses: "./….yaml" } or inline body`;
+    return `Invalid stage entry at index ${index} in ${declaringPath}: ${hint}`;
+}
+export function normalizePipelineStageEntries(rawEntries, ctx) {
+    const normalized = [];
+    for (let index = 0; index < rawEntries.length; index++) {
+        const { raw, declaringPath } = rawEntries[index];
+        if (typeof raw === "string") {
+            return loadFailure([
+                {
+                    code: "pipeline.string_stage_ref",
+                    message: stringStageRefMessage(index, declaringPath, raw),
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
+        }
+        if (!isPlainObject(raw)) {
+            return loadFailure([
+                {
+                    code: "pipeline.invalid_shape",
+                    message: `Invalid stage entry at index ${index} in ${declaringPath}: expected object`,
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
+        }
+        for (const key of Object.keys(raw)) {
+            if (!isAllowedPipelineStageEntryKey(key)) {
+                return loadFailure([
+                    {
+                        code: "pipeline.invalid_shape",
+                        message: `Pipeline ${ctx.pipelineId} (${ctx.path}): invalid stage entry at index ${index}: unknown key "${key}"`,
+                        category: "pipeline",
+                        pipelineId: ctx.pipelineId,
+                    },
+                ]);
+            }
+        }
+        const uses = typeof raw.uses === "string" ? raw.uses : undefined;
+        const hasBody = hasBodyKey(raw);
+        const skillOutcome = readSkill(raw);
+        if (skillOutcome !== undefined && !skillOutcome.ok) {
+            return skillOutcome;
+        }
+        const skill = skillOutcome?.ok ? skillOutcome.value : undefined;
+        if (uses && hasBody) {
+            return loadFailure([
+                {
+                    code: "pipeline.stage_uses_inline_conflict",
+                    message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage entry at index ${index} has both uses and inline body fields`,
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
+        }
+        if (!uses && !hasBody) {
+            const entryLabel = typeof raw.id === "string" ? raw.id : String(index);
+            return loadFailure([
+                {
+                    code: "pipeline.stage_missing_body",
+                    message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${entryLabel}" has no uses: path or inline body`,
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
+        }
+        let id = typeof raw.id === "string" && raw.id ? raw.id : undefined;
+        if (!id && uses) {
+            const inferred = inferIdFromUsesPath(uses);
+            if (inferred)
+                id = inferred;
+        }
+        if (!id) {
+            return loadFailure([
+                {
+                    code: "pipeline.invalid_shape",
+                    message: `Pipeline ${ctx.pipelineId} (${ctx.path}): invalid stage entry at index ${index}: id must be a non-empty string or inferrable from uses path`,
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
+        }
+        if (raw.needs !== undefined) {
+            if (Array.isArray(raw.needs)) {
+                return loadFailure([
+                    {
+                        code: "pipeline.dag_error",
+                        message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": needs must be a string, not an array`,
+                        category: "pipeline",
+                        pipelineId: ctx.pipelineId,
+                    },
+                ]);
+            }
+            if (typeof raw.needs !== "string" || !raw.needs) {
+                return loadFailure([
+                    {
+                        code: "pipeline.dag_error",
+                        message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": needs must be a non-empty string`,
+                        category: "pipeline",
+                        pipelineId: ctx.pipelineId,
+                    },
+                ]);
+            }
+        }
+        let forkValue;
+        if (raw.fork !== undefined) {
+            if (!isPlainObject(raw.fork)) {
+                return loadFailure([
+                    {
+                        code: "pipeline.dag_error",
+                        message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": fork must be an object`,
+                        category: "pipeline",
+                        pipelineId: ctx.pipelineId,
+                    },
+                ]);
+            }
+            forkValue = raw.fork;
+        }
+        let body;
+        if (uses) {
+            const absolutePath = path.resolve(path.dirname(declaringPath), uses);
+            body = { kind: "uses", path: uses, absolutePath };
+        }
+        else {
+            body = { kind: "inline", raw: extractBodyRaw(raw) };
+        }
+        const entry = {
+            id,
+            declaringPath,
+            body,
+            ...(typeof raw.needs === "string" ? { needs: raw.needs } : {}),
+            ...(forkValue !== undefined ? { fork: forkValue } : {}),
+            ...(raw.clonable !== undefined ? { clonable: raw.clonable } : {}),
+            ...(raw.clone_cap !== undefined ? { clone_cap: raw.clone_cap } : {}),
+            ...(skill !== undefined ? { skill } : {}),
+        };
+        const priorPath = normalized.find((e) => e.id === id)?.declaringPath;
+        if (priorPath) {
+            return loadFailure([
+                {
+                    code: "pipeline.include_duplicate_stage",
+                    message: `Duplicate stage id "${id}" in ${declaringPath} (also declared in ${priorPath})`,
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
+        }
+        normalized.push(entry);
+    }
+    return loadSuccess(normalized);
+}
+export function toWiringRefs(entries) {
+    return entries.map((entry) => ({
+        id: entry.id,
+        ...(entry.needs !== undefined ? { needs: entry.needs } : {}),
+        ...(entry.fork !== undefined ? { fork: entry.fork } : {}),
+        ...(entry.clonable !== undefined ? { clonable: entry.clonable } : {}),
+        ...(entry.clone_cap !== undefined ? { clone_cap: entry.clone_cap } : {}),
+    }));
+}

package/dist/config/pipelineStageKeys.d.ts

@@ -0,0 +1,4 @@
+export declare const WIRING_KEYS: Set<string>;
+export declare const BODY_KEYS: Set<string>;
+export declare function isPipelineStageBodyKey(key: string): boolean;
+export declare function isAllowedPipelineStageEntryKey(key: string): boolean;

package/dist/config/pipelineStageKeys.js

@@ -0,0 +1,14 @@
+export const WIRING_KEYS = new Set(["id", "needs", "fork", "uses", "clonable", "clone_cap"]);
+export const BODY_KEYS = new Set([
+    "system_prompt",
+    "model",
+    "payload_schema",
+    "gate_kinds",
+    "skill",
+]);
+export function isPipelineStageBodyKey(key) {
+    return BODY_KEYS.has(key);
+}
+export function isAllowedPipelineStageEntryKey(key) {
+    return WIRING_KEYS.has(key) || BODY_KEYS.has(key);
+}

package/dist/config/resolveCatalogContext.d.ts

@@ -0,0 +1,13 @@
+import type { LoadedManifest } from "../types/stageflowManifest.js";
+import type { LoadIssue } from "./loadOutcome.js";
+import { type CatalogManifestStatus, type StageflowContext } from "../project/resolveStageflowContext.js";
+export type { CatalogManifestStatus };
+export type CatalogContext = {
+    projectRoot: string | null;
+    manifest: LoadedManifest | null;
+    manifestStatus: CatalogManifestStatus;
+    issues: LoadIssue[];
+};
+export declare function catalogContextFromStageflow(ctx: StageflowContext): CatalogContext;
+/** @deprecated Prefer resolveStageflowContext */
+export declare function resolveCatalogContext(invocationCwd: string): Promise<CatalogContext>;

package/dist/config/resolveCatalogContext.js

@@ -0,0 +1,13 @@
+import { resolveStageflowContext, } from "../project/resolveStageflowContext.js";
+export function catalogContextFromStageflow(ctx) {
+    return {
+        projectRoot: ctx.isGitProject ? ctx.projectRoot : null,
+        manifest: ctx.manifest,
+        manifestStatus: ctx.manifestStatus,
+        issues: ctx.manifestIssues,
+    };
+}
+/** @deprecated Prefer resolveStageflowContext */
+export async function resolveCatalogContext(invocationCwd) {
+    return catalogContextFromStageflow(await resolveStageflowContext(invocationCwd));
+}

package/dist/config/resolveForkEmitContext.d.ts

@@ -0,0 +1,4 @@
+import type { CloneEmitContext, ForkEmitContext } from "../types/forkChoice.js";
+import type { ResolvedPipelineDag } from "../types/pipeline.js";
+export declare function resolveCloneEmitContext(dag: ResolvedPipelineDag, stageId: string): CloneEmitContext | undefined;
+export declare function resolveForkEmitContext(dag: ResolvedPipelineDag, stageId: string): ForkEmitContext | undefined;

package/dist/config/resolveForkEmitContext.js

@@ -0,0 +1,34 @@
+export function resolveCloneEmitContext(dag, stageId) {
+    const childIds = dag.childrenOf[stageId] ?? [];
+    const clonableSuccessors = [];
+    for (const childId of childIds) {
+        const node = dag.nodes.find((n) => n.id === childId);
+        if (node?.clonable === true) {
+            clonableSuccessors.push({
+                successorId: childId,
+                cloneCap: node.clone_cap,
+            });
+        }
+    }
+    if (clonableSuccessors.length === 0)
+        return undefined;
+    return { clonableSuccessors };
+}
+export function resolveForkEmitContext(dag, stageId) {
+    const dagNode = dag.nodes.find((n) => n.id === stageId);
+    if (!dagNode?.fork)
+        return undefined;
+    const immediateSuccessorIds = (dag.childrenOf[stageId] ?? []).filter((childId) => {
+        const child = dag.nodes.find((n) => n.id === childId);
+        return child?.clonable !== true;
+    });
+    if (immediateSuccessorIds.length === 0)
+        return undefined;
+    return {
+        immediateSuccessorIds,
+        forkShape: {
+            cardinality: dagNode.fork.select,
+            allowNone: dagNode.fork.allow_none,
+        },
+    };
+}

package/dist/config/resolvePipelineDag.d.ts

@@ -1,9 +1,13 @@
-import type { PipelineStageYamlEntry, ResolvedPipelineDag } from "../types/pipeline.js";
+import type { PipelineStageRef, PipelineStageYamlEntry, ResolvedPipelineDag } from "../types/pipeline.js";
 export type ResolvePipelineDagContext = {
     pipelineId: string;
     path: string;
 };
 export declare function parsePipelineStageEntries(raw: unknown, ctx: ResolvePipelineDagContext): PipelineStageYamlEntry[];
+export declare function resolvePipelineDagFromRefs(refs: PipelineStageRef[], ctx: ResolvePipelineDagContext): {
+    stages: string[];
+    dag: ResolvedPipelineDag;
+};
 export declare function resolvePipelineDag(rawStages: unknown, ctx: ResolvePipelineDagContext): {
     stages: string[];
     dag: ResolvedPipelineDag;

package/dist/config/resolvePipelineDag.js

@@ -1,4 +1,5 @@
-const ALLOWED_STAGE_REF_KEYS = new Set(["id", "needs"]);
+import { isAllowedPipelineStageEntryKey } from "./pipelineStageKeys.js";
+const ALLOWED_FORK_KEYS = new Set(["select", "allow_none"]);
 function pipelineLabel(ctx) {
     return `Pipeline ${ctx.pipelineId} (${ctx.path})`;
 }
@@ -19,26 +20,45 @@ export function parsePipelineStageEntries(raw, ctx) {
     for (let index = 0; index < raw.length; index++) {
         const entry = raw[index];
         if (typeof entry === "string") {
-            if (!entry) {
-                throw new Error(formatError(ctx, `invalid stage entry at index ${index}: stage id must be a non-empty string`));
-            }
-            entries.push(entry);
-            continue;
+            const hint = entry
+                ? `invalid stage entry at index ${index}: bare string stage refs are not supported; use { id: "${entry}", uses: "./${entry}.yaml" } or inline body`
+                : `invalid stage entry at index ${index}: bare string stage refs are not supported; use { id: "…", uses: "./….yaml" } or inline body`;
+            throw new Error(formatError(ctx, hint));
         }
         if (!isPlainObject(entry)) {
             throw new Error(formatError(ctx, `invalid stage entry at index ${index}`));
         }
         const keys = Object.keys(entry);
         for (const key of keys) {
-            if (!ALLOWED_STAGE_REF_KEYS.has(key)) {
+            if (!isAllowedPipelineStageEntryKey(key)) {
                 throw new Error(formatError(ctx, `invalid stage entry "${String(entry.id ?? index)}": unknown key "${key}"`));
             }
         }
         if (typeof entry.id !== "string" || !entry.id) {
             throw new Error(formatError(ctx, `invalid stage entry at index ${index}: id must be a non-empty string`));
         }
+        let forkValue;
+        if (entry.fork !== undefined) {
+            if (!isPlainObject(entry.fork)) {
+                throw new Error(formatError(ctx, `stage "${entry.id}": fork must be an object`));
+            }
+            for (const fk of Object.keys(entry.fork)) {
+                if (!ALLOWED_FORK_KEYS.has(fk)) {
+                    throw new Error(formatError(ctx, `stage "${entry.id}": fork: unknown key "${fk}"`));
+                }
+            }
+            forkValue = entry.fork;
+        }
+        const clonableFields = {
+            ...(entry.clonable !== undefined ? { clonable: entry.clonable } : {}),
+            ...(entry.clone_cap !== undefined ? { clone_cap: entry.clone_cap } : {}),
+        };
         if (entry.needs === undefined) {
-            entries.push({ id: entry.id });
+            entries.push({
+                id: entry.id,
+                ...(forkValue !== undefined ? { fork: forkValue } : {}),
+                ...clonableFields,
+            });
             continue;
         }
         if (Array.isArray(entry.needs)) {
@@ -50,29 +70,24 @@ export function parsePipelineStageEntries(raw, ctx) {
         if (typeof entry.needs !== "string" || !entry.needs) {
             throw new Error(formatError(ctx, `stage "${entry.id}": needs must be a non-empty string`));
         }
-        entries.push({ id: entry.id, needs: entry.needs });
+        entries.push({
+            id: entry.id,
+            needs: entry.needs,
+            ...(forkValue !== undefined ? { fork: forkValue } : {}),
+            ...clonableFields,
+        });
     }
     return entries;
 }
 function normalizeToEdges(entries) {
-    const edges = [];
-    for (let index = 0; index < entries.length; index++) {
-        const entry = entries[index];
-        if (typeof entry === "string") {
-            edges.push({
-                id: entry,
-                needs: index > 0 ? entries[index - 1] : null,
-                stageIndex: index,
-            });
-            continue;
-        }
-        edges.push({
-            id: entry.id,
-            needs: entry.needs ?? null,
-            stageIndex: index,
-        });
-    }
-    return edges;
+    return entries.map((entry, index) => ({
+        id: entry.id,
+        needs: entry.needs ?? null,
+        stageIndex: index,
+        ...(entry.fork !== undefined ? { fork: entry.fork } : {}),
+        ...(entry.clonable !== undefined ? { clonable: entry.clonable } : {}),
+        ...(entry.clone_cap !== undefined ? { clone_cap: entry.clone_cap } : {}),
+    }));
 }
 function detectDuplicateIds(edges, ctx) {
     const seen = new Set();
@@ -160,7 +175,7 @@ function topologicalSort(edges) {
         indegree.set(edge.id, (indegree.get(edge.id) ?? 0) + 1);
         children.get(edge.needs)?.push(edge.id);
     }
-    for (const [parent, childIds] of children) {
+    for (const [, childIds] of children) {
         childIds.sort((a, b) => (byId.get(a)?.stageIndex ?? 0) - (byId.get(b)?.stageIndex ?? 0));
     }
     const roots = edges
@@ -208,12 +223,44 @@ function buildResolvedPipelineDag(edges) {
         needs: edge.needs,
         ancestors: ancestorsById.get(edge.id) ?? [],
         stageIndex: edge.stageIndex,
+        ...(edge.fork !== undefined
+            ? { fork: { select: edge.fork.select, allow_none: edge.fork.allow_none ?? false } }
+            : {}),
+        ...(edge.clonable === true
+            ? { clonable: true, clone_cap: edge.clone_cap ?? 5 }
+            : {}),
     }));
     return { nodes, roots, childrenOf };
 }
-export function resolvePipelineDag(rawStages, ctx) {
-    const entries = parsePipelineStageEntries(rawStages, ctx);
-    const edges = normalizeToEdges(entries);
+function validateForkFields(edges, dag, ctx) {
+    for (const edge of edges) {
+        if (!edge.fork)
+            continue;
+        if (edge.fork.select !== "one" && edge.fork.select !== "subset") {
+            throw new Error(formatError(ctx, `stage "${edge.id}": fork.select must be "one" or "subset"${edge.fork.select === undefined ? " (missing)" : `, got "${String(edge.fork.select)}"`}`));
+        }
+        if ((dag.childrenOf[edge.id] ?? []).length === 0) {
+            throw new Error(formatError(ctx, `fork on stage "${edge.id}": no children in the DAG`));
+        }
+    }
+}
+function validateClonableFields(edges, dag, ctx) {
+    for (const edge of edges) {
+        if (edge.clone_cap !== undefined && edge.clonable !== true) {
+            throw new Error(formatError(ctx, `stage "${edge.id}": clone_cap requires clonable: true`));
+        }
+        if (edge.clonable === true && edge.clone_cap !== undefined) {
+            if (!Number.isInteger(edge.clone_cap) || edge.clone_cap < 2) {
+                throw new Error(formatError(ctx, `stage "${edge.id}": clone_cap must be an integer greater than or equal to 2`));
+            }
+        }
+        if (edge.clonable === true && (dag.childrenOf[edge.id] ?? []).length === 0) {
+            throw new Error(formatError(ctx, `clonable on stage "${edge.id}": no children in the DAG`));
+        }
+    }
+}
+export function resolvePipelineDagFromRefs(refs, ctx) {
+    const edges = normalizeToEdges(refs);
     detectDuplicateIds(edges, ctx);
     validateNeedsTargets(edges, ctx);
     detectCycle(edges, ctx);
@@ -222,8 +269,14 @@ export function resolvePipelineDag(rawStages, ctx) {
         .sort((a, b) => a.stageIndex - b.stageIndex)
         .map((edge) => edge.id);
     const dag = buildResolvedPipelineDag(edges);
+    validateForkFields(edges, dag, ctx);
+    validateClonableFields(edges, dag, ctx);
     return { stages, dag };
 }
+export function resolvePipelineDag(rawStages, ctx) {
+    const entries = parsePipelineStageEntries(rawStages, ctx);
+    return resolvePipelineDagFromRefs(entries, ctx);
+}
 export function areResolvedDagsEquivalent(a, b) {
     const nodeIdsA = new Set(a.nodes.map((node) => node.id));
     const nodeIdsB = new Set(b.nodes.map((node) => node.id));
@@ -256,16 +309,13 @@ export function extractPipelineStageIds(rawStages) {
     const stageIds = [];
     for (const entry of rawStages) {
         if (typeof entry === "string") {
-            if (!entry)
-                return null;
-            stageIds.push(entry);
-            continue;
+            return null;
         }
         if (!isPlainObject(entry))
             return null;
         const keys = Object.keys(entry);
         for (const key of keys) {
-            if (!ALLOWED_STAGE_REF_KEYS.has(key))
+            if (!isAllowedPipelineStageEntryKey(key))
                 return null;
         }
         if (typeof entry.id !== "string" || !entry.id)

package/dist/config/scanCatalogPaths.d.ts

@@ -0,0 +1,4 @@
+import type { LoadedManifest } from "../types/stageflowManifest.js";
+export type CatalogPathKind = "pipeline" | "task";
+export declare function isExcluded(repoRelPath: string, exclude: string[] | undefined): boolean;
+export declare function scanCatalogPaths(manifest: LoadedManifest, kind: CatalogPathKind): Promise<string[]>;

package/dist/config/scanCatalogPaths.js

@@ -0,0 +1,83 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+function normalizeRepoRel(repoRelPath) {
+    return repoRelPath.replace(/\\/g, "/").replace(/^\.\/+/, "");
+}
+export function isExcluded(repoRelPath, exclude) {
+    if (!exclude || exclude.length === 0) {
+        return false;
+    }
+    const normalized = normalizeRepoRel(repoRelPath);
+    for (const entry of exclude) {
+        const prefix = normalizeRepoRel(entry);
+        if (normalized === prefix || normalized.startsWith(`${prefix}/`)) {
+            return true;
+        }
+    }
+    return false;
+}
+function globPatternToRegExp(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}$`);
+}
+function matchesPattern(basename, pattern) {
+    return globPatternToRegExp(pattern).test(basename);
+}
+async function walkDirectory(absDir) {
+    const files = [];
+    let entries;
+    try {
+        entries = await readdir(absDir, { withFileTypes: true, recursive: true });
+    }
+    catch {
+        return files;
+    }
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const parentDir = entry.parentPath ?? absDir;
+        files.push(path.join(parentDir, entry.name));
+    }
+    return files;
+}
+async function expandCatalogEntry(projectRoot, entry, kind, pattern) {
+    const absPath = path.join(projectRoot, entry);
+    let entryStat;
+    try {
+        entryStat = await stat(absPath);
+    }
+    catch {
+        return [];
+    }
+    if (entryStat.isFile()) {
+        return [absPath];
+    }
+    if (!entryStat.isDirectory()) {
+        return [];
+    }
+    const files = await walkDirectory(absPath);
+    return files.filter((filePath) => matchesPattern(path.basename(filePath), pattern));
+}
+export async function scanCatalogPaths(manifest, kind) {
+    const { projectRoot, manifest: doc, patterns } = manifest;
+    const entries = kind === "pipeline" ? doc.catalog.pipelines : doc.catalog.tasks;
+    const pattern = kind === "pipeline" ? patterns.pipeline : patterns.task;
+    const exclude = doc.catalog.exclude;
+    const seen = new Set();
+    const resolved = [];
+    for (const entry of entries) {
+        const absPaths = await expandCatalogEntry(projectRoot, entry, kind, pattern);
+        for (const absPath of absPaths) {
+            const normalized = path.resolve(absPath);
+            if (seen.has(normalized))
+                continue;
+            const repoRel = normalizeRepoRel(path.relative(projectRoot, normalized));
+            if (isExcluded(repoRel, exclude))
+                continue;
+            seen.add(normalized);
+            resolved.push(normalized);
+        }
+    }
+    resolved.sort((a, b) => a.localeCompare(b));
+    return resolved;
+}

package/dist/config/validateCatalog.d.ts

@@ -1,7 +1,8 @@
+import type { LoadedPipeline } from "../types/pipeline.js";
 import type { LoadIssue } from "./loadOutcome.js";
 export type ValidationSeverity = "error" | "warning";
-export type ValidationCategory = "pipeline" | "stage" | "catalog";
-export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "stage.invalid_shape" | "stage.invalid_payload_schema" | "stage.invalid_gate_kinds" | "stage.invalid_skill" | "stage.load_error" | "stage.id_filename_mismatch" | "catalog.duplicate_pipeline_id" | "catalog.orphan_stage";
+export type ValidationCategory = "pipeline" | "stage" | "catalog" | "task";
+export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "pipeline.string_stage_ref" | "pipeline.stage_uses_inline_conflict" | "pipeline.stage_missing_body" | "pipeline.stage_id_mismatch" | "pipeline.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "stage.invalid_shape" | "stage.invalid_payload_schema" | "stage.invalid_gate_kinds" | "stage.invalid_skill" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error";
 export type ValidationFinding = {
     severity: ValidationSeverity;
     code: ValidationFindingCode | string;
@@ -11,12 +12,12 @@ export type ValidationFinding = {
     pipelineId?: string;
     stageId?: string;
 };
-export type ValidationScope = "full" | "pipeline";
+export type ValidationScope = "full" | "pipeline" | "task";
 export type ValidateCatalogOptions = {
     cwd?: string;
-    stagesDir?: string;
     scope: ValidationScope;
     pipeline?: string;
+    task?: string;
     strict?: boolean;
 };
 export type ValidationResult = {
@@ -33,4 +34,21 @@ export declare function effectiveSeverity(finding: ValidationFinding, strict: bo
 export declare function buildValidationResult(scope: ValidationScope, findings: ValidationFinding[], strict: boolean): ValidationResult;
 export declare function findingsFromLoadIssues(cwd: string, absPath: string, issues: LoadIssue[]): ValidationFinding[];
 export declare function findingStageIdFilenameMismatch(cwd: string, absPath: string, fileStem: string, declaredId: string): ValidationFinding;
+export type ValidatePipelineOptions = {
+    cwd?: string;
+    validateStages?: boolean;
+    strict?: boolean;
+};
+export declare function validatePipeline(nameOrPath: string, options?: ValidatePipelineOptions): Promise<ValidationResult>;
+export type LoadPipelineValidatedResult = {
+    ok: true;
+    loaded: LoadedPipeline;
+} | {
+    ok: false;
+    findings: ValidationFinding[];
+};
+export declare function loadPipelineValidated(nameOrPath: string, options?: {
+    cwd?: string;
+    validateStages?: boolean;
+}): Promise<LoadPipelineValidatedResult>;
 export declare function validateCatalog(options: ValidateCatalogOptions): Promise<ValidationResult>;