@sanity/ailf 0.1.0

package/dist/orchestration/steps/publish-report-step.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Pipeline step: Publish evaluation report to the report store.
+ *
+ * Inlines the logic from the former pipeline/steps/publish-report-step.ts.
+ * Uses ctx.reportStore and ctx.sinks from the composition root instead of
+ * constructing ReportStore and loadSinks() internally.
+ *
+ * Design principles:
+ * - P1: Reports are immutable events (write-once to Sanity)
+ * - P5: Local-first (pipeline never fails because of a store write)
+ * - P6: Sinks are fire-and-forget (failures logged, not thrown)
+ */
+import type { AppContext, PipelineState, PipelineStep, PromptfooUrlEntry, StepResult, ValidationIssue } from "../../_vendor/ailf-core/index.d.ts";
+export declare class PublishReportStep implements PipelineStep {
+    private readonly pipelineStart;
+    private readonly options;
+    readonly name = "publish-report";
+    readonly optional = true;
+    constructor(pipelineStart: number, options?: {
+        evalFingerprint?: string;
+        promptfooUrls?: PromptfooUrlEntry[];
+        publishTag?: string;
+    });
+    check(): ValidationIssue[];
+    execute(ctx: AppContext, state: PipelineState): Promise<StepResult>;
+}

package/dist/orchestration/steps/publish-report-step.js

@@ -0,0 +1,216 @@
+/**
+ * Pipeline step: Publish evaluation report to the report store.
+ *
+ * Inlines the logic from the former pipeline/steps/publish-report-step.ts.
+ * Uses ctx.reportStore and ctx.sinks from the composition root instead of
+ * constructing ReportStore and loadSinks() internally.
+ *
+ * Design principles:
+ * - P1: Reports are immutable events (write-once to Sanity)
+ * - P5: Local-first (pipeline never fails because of a store write)
+ * - P6: Sinks are fire-and-forget (failures logged, not thrown)
+ */
+import { readFileSync } from "fs";
+import { resolve } from "path";
+import { checkScoreSummaryValid } from "../../pipeline/checks.js";
+import { buildProvenance, } from "../../pipeline/provenance.js";
+import { generateReportId } from "../../report-store.js";
+import { withRetry } from "../../sinks/retry.js";
+export class PublishReportStep {
+    pipelineStart;
+    options;
+    name = "publish-report";
+    optional = true;
+    constructor(pipelineStart, options = {}) {
+        this.pipelineStart = pipelineStart;
+        this.options = options;
+    }
+    check() {
+        return [];
+    }
+    async execute(ctx, state) {
+        const start = Date.now();
+        const { rootDir } = ctx.config;
+        // Precondition: score summary exists
+        const summaryIssues = checkScoreSummaryValid(rootDir);
+        const summaryErrors = summaryIssues.filter((i) => i.severity === "error");
+        if (summaryErrors.length > 0) {
+            return {
+                durationMs: Date.now() - start,
+                error: `Score summary missing: ${summaryErrors.map((e) => e.message).join("; ")}`,
+                status: "failed",
+            };
+        }
+        // Read score summary
+        let summary;
+        try {
+            const summaryPath = resolve(rootDir, "results", "latest", "score-summary.json");
+            summary = JSON.parse(readFileSync(summaryPath, "utf-8"));
+        }
+        catch (err) {
+            return {
+                durationMs: Date.now() - start,
+                error: `Failed to read score-summary.json: ${err instanceof Error ? err.message : String(err)}`,
+                status: "failed",
+            };
+        }
+        // Build provenance — prefer state values from upstream steps,
+        // fall back to constructor options for backward compatibility
+        const provenanceOptions = {
+            evalFingerprint: state.evalFingerprint ?? this.options.evalFingerprint,
+            promptfooUrls: state.promptfooUrls ?? this.options.promptfooUrls,
+        };
+        const provenanceInput = buildProvenanceInput(summary, ctx, provenanceOptions);
+        const provenance = buildProvenance(provenanceInput);
+        // Create report
+        const now = new Date().toISOString();
+        const reportId = generateReportId();
+        const durationMs = Date.now() - this.pipelineStart;
+        // Auto-compare against most recent comparable baseline
+        const comparison = ctx.reportStore
+            ? (await ctx.reportStore.autoCompare(summary, provenance, now))
+            : null;
+        const report = {
+            comparison: comparison ?? undefined,
+            completedAt: now,
+            durationMs,
+            id: reportId,
+            provenance,
+            summary,
+            tag: this.options.publishTag ?? ctx.config.publishTag,
+        };
+        // Share reportId with downstream steps (CallbackStep + orchestrator job update)
+        state.reportId = reportId;
+        // Write to store (system of record — best-effort, P5)
+        const sanityResult = ctx.reportStore
+            ? await ctx.reportStore.write(report)
+            : null;
+        // Run sinks (fire-and-forget, P6)
+        const publishResult = await runSinks(report, ctx);
+        // Build result summary
+        const parts = [];
+        if (sanityResult) {
+            parts.push(`report:${sanityResult}`);
+        }
+        else {
+            parts.push("Sanity write skipped (no token or unreachable)");
+        }
+        if (comparison) {
+            const delta = comparison.deltas.overall;
+            const sign = delta >= 0 ? "+" : "";
+            parts.push(`vs baseline: ${sign}${delta.toFixed(1)}`);
+        }
+        if (publishResult.sinkResults.length > 0) {
+            const succeeded = publishResult.sinkResults.filter((r) => r.result.status === "success").length;
+            const total = publishResult.sinkResults.length;
+            parts.push(`sinks: ${succeeded}/${total}`);
+        }
+        return {
+            durationMs: Date.now() - start,
+            status: "success",
+            summary: `Published — ${parts.join(", ")}`,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Assemble provenance input from the score summary and pipeline context.
+ */
+function buildProvenanceInput(summary, ctx, options) {
+    const areas = summary.scores.map((s) => s.feature);
+    const mode = ctx.config.mode;
+    // Read document IDs from config
+    const sanityDocumentIds = ctx.config.sanityDocumentArgs;
+    // Read task filter from config
+    const taskIds = ctx.config.tasks;
+    // Build source from summary metadata or config
+    const source = {
+        baseUrl: summary.source?.baseUrl ?? "https://www.sanity.io/docs",
+        dataset: summary.source?.dataset ?? ctx.config.datasetOverride ?? "next",
+        documentIds: [],
+        llmsTxt: (summary.source?.baseUrl ?? "https://www.sanity.io/docs") + "/llms.txt",
+        name: summary.source?.name ?? "production",
+        perspective: summary.source?.perspective ??
+            ctx.config.perspectiveOverride ??
+            undefined,
+        priorityDomain: "sanity.io",
+        projectId: summary.source?.projectId ?? ctx.config.projectIdOverride ?? "3do82whm",
+        studioOrigin: "https://admin.sanity.io",
+        urls: [],
+    };
+    // Debug runs don't store fingerprints
+    const evalFingerprint = !ctx.config.debug?.enabled
+        ? options.evalFingerprint
+        : undefined;
+    return {
+        areas,
+        evalFingerprint,
+        mode,
+        promptfooUrls: options.promptfooUrls,
+        rootDir: ctx.config.rootDir,
+        sanityDocumentIds,
+        source,
+        taskIds,
+    };
+}
+/**
+ * Fan out a report to all configured sinks.
+ *
+ * Uses ctx.sinks from the composition root instead of loadSinks().
+ * Each sink is run with retry logic (3 attempts, exponential backoff).
+ * Failures are logged but never block the pipeline.
+ */
+async function runSinks(report, ctx) {
+    const sinks = (ctx.sinks ?? []);
+    const sinkResults = [];
+    if (sinks.length === 0) {
+        return { report, sinkResults };
+    }
+    // Health check all sinks first (non-blocking)
+    for (const sink of sinks) {
+        if (sink.healthCheck) {
+            try {
+                const health = await sink.healthCheck();
+                if (!health.healthy) {
+                    console.warn(`  ⚠️  Sink ${sink.name} health check failed: ${health.reason}`);
+                }
+            }
+            catch (err) {
+                console.warn(`  ⚠️  Sink ${sink.name} health check error: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    // Publish to all sinks in parallel (fire-and-forget with retries)
+    const settled = await Promise.allSettled(sinks.map(async (sink) => {
+        const result = await withRetry(() => sink.publish(report));
+        return { name: sink.name, result };
+    }));
+    for (const outcome of settled) {
+        if (outcome.status === "fulfilled") {
+            sinkResults.push(outcome.value);
+            const { name, result } = outcome.value;
+            if (result.status === "failed") {
+                console.warn(`  ⚠️  Sink ${name} failed: ${result.error}`);
+            }
+            else if (result.status === "skipped") {
+                console.log(`  ⏭️  Sink ${name} skipped: ${result.reason}`);
+            }
+            else {
+                console.log(`  ✅ Sink ${name} delivered${result.detail ? ` (${result.detail})` : ""}`);
+            }
+        }
+        else {
+            const error = outcome.reason instanceof Error
+                ? outcome.reason.message
+                : String(outcome.reason);
+            sinkResults.push({
+                name: "unknown",
+                result: { error, status: "failed" },
+            });
+            console.warn(`  ⚠️  Sink delivery error: ${error}`);
+        }
+    }
+    return { report, sinkResults };
+}

package/dist/orchestration/steps/readiness-step.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Pipeline step: Launch readiness report.
+ *
+ * Calls pure functions from pipeline/readiness-report.ts directly.
+ * Optional step — failure doesn't stop the pipeline.
+ */
+import type { AppContext, PipelineStep, StepResult, ValidationIssue } from "../../_vendor/ailf-core/index.d.ts";
+export declare class ReadinessStep implements PipelineStep {
+    readonly name = "readiness";
+    readonly optional = true;
+    check(): ValidationIssue[];
+    execute(ctx: AppContext): Promise<StepResult>;
+}

package/dist/orchestration/steps/readiness-step.js

@@ -0,0 +1,91 @@
+/**
+ * Pipeline step: Launch readiness report.
+ *
+ * Calls pure functions from pipeline/readiness-report.ts directly.
+ * Optional step — failure doesn't stop the pipeline.
+ */
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { resolve } from "path";
+import { load } from "js-yaml";
+import { formatReadinessMarkdown, generateReadinessReport, } from "../../pipeline/readiness-report.js";
+import { ThresholdConfigSchema } from "../../pipeline/schemas.js";
+export class ReadinessStep {
+    name = "readiness";
+    optional = true;
+    check() {
+        return [];
+    }
+    async execute(ctx) {
+        const root = ctx.config.rootDir;
+        const start = Date.now();
+        try {
+            const scoreSummaryPath = resolve(root, "results", "latest", "score-summary.json");
+            const thresholdsPath = resolve(root, "config", "thresholds.yaml");
+            if (!existsSync(scoreSummaryPath)) {
+                return {
+                    durationMs: Date.now() - start,
+                    error: "score-summary.json not found",
+                    status: "failed",
+                };
+            }
+            if (!existsSync(thresholdsPath)) {
+                return {
+                    durationMs: Date.now() - start,
+                    error: "config/thresholds.yaml not found",
+                    status: "failed",
+                };
+            }
+            const scoreSummary = JSON.parse(readFileSync(scoreSummaryPath, "utf-8"));
+            const rawThresholds = load(readFileSync(thresholdsPath, "utf-8"));
+            const thresholdConfig = ThresholdConfigSchema.parse(rawThresholds);
+            const gapPath = resolve(root, "results", "latest", "gap-analysis.json");
+            const gapAnalysis = existsSync(gapPath)
+                ? JSON.parse(readFileSync(gapPath, "utf-8"))
+                : undefined;
+            const readinessAreas = ctx.config.areas ?? scoreSummary.scores.map((s) => s.feature);
+            const readinessLines = [];
+            for (const area of readinessAreas) {
+                const areaScore = scoreSummary.scores.find((s) => s.feature === area);
+                if (!areaScore) {
+                    ctx.logger.warn(`Area "${area}" not found in scores — skipping`);
+                    continue;
+                }
+                const report = generateReadinessReport({
+                    area,
+                    gapAnalysis,
+                    scoreSummary,
+                    thresholdConfig,
+                });
+                const md = formatReadinessMarkdown(report);
+                readinessLines.push(md);
+                console.log(md);
+            }
+            if (readinessLines.length > 0) {
+                writeFileSync(resolve(root, "results", "latest", "readiness-report.md"), readinessLines.join("\n---\n\n"));
+            }
+            const passCount = readinessAreas.filter((area) => {
+                const areaScore = scoreSummary.scores.find((s) => s.feature === area);
+                if (!areaScore)
+                    return false;
+                const report = generateReadinessReport({
+                    area,
+                    scoreSummary,
+                    thresholdConfig,
+                });
+                return report.pass;
+            }).length;
+            return {
+                durationMs: Date.now() - start,
+                status: "success",
+                summary: `${passCount}/${readinessAreas.length} areas ready`,
+            };
+        }
+        catch (err) {
+            return {
+                durationMs: Date.now() - start,
+                error: err instanceof Error ? err.message : String(err),
+                status: "failed",
+            };
+        }
+    }
+}

package/dist/orchestration/steps/report-step.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pipeline step: Generate PR comment / report from scores.
+ *
+ * Calls generatePrComment() from pipeline/pr-comment.ts with typed options.
+ * No env bridge or process.argv manipulation needed.
+ */
+import type { AppContext, PipelineStep, StepResult, ValidationIssue } from "../../_vendor/ailf-core/index.d.ts";
+export declare class ReportStep implements PipelineStep {
+    readonly name = "report";
+    check(): ValidationIssue[];
+    execute(ctx: AppContext): Promise<StepResult>;
+}

package/dist/orchestration/steps/report-step.js

@@ -0,0 +1,49 @@
+/**
+ * Pipeline step: Generate PR comment / report from scores.
+ *
+ * Calls generatePrComment() from pipeline/pr-comment.ts with typed options.
+ * No env bridge or process.argv manipulation needed.
+ */
+import { resolve } from "path";
+import { checkScoreSummaryValid } from "../../pipeline/checks.js";
+import { generatePrComment } from "../../pipeline/pr-comment.js";
+const DEFAULT_REPORT_PATH = "results/latest/pr-comment.md";
+export class ReportStep {
+    name = "report";
+    check() {
+        return [];
+    }
+    async execute(ctx) {
+        const start = Date.now();
+        // Precondition: score summary exists
+        const summaryIssues = checkScoreSummaryValid(ctx.config.rootDir);
+        const summaryErrors = summaryIssues.filter((i) => i.severity === "error");
+        if (summaryErrors.length > 0) {
+            return {
+                durationMs: Date.now() - start,
+                error: `Score summary missing: ${summaryErrors.map((e) => e.message).join("; ")}`,
+                status: "failed",
+            };
+        }
+        const resolvedOutput = ctx.config.outputPath ?? resolve(ctx.config.rootDir, DEFAULT_REPORT_PATH);
+        try {
+            generatePrComment({
+                outputPath: resolvedOutput,
+                promptfooUrl: ctx.config.promptfooUrl,
+                rootDir: ctx.config.rootDir,
+            });
+        }
+        catch (err) {
+            return {
+                durationMs: Date.now() - start,
+                error: `pr-comment failed: ${err instanceof Error ? err.message : String(err)}`,
+                status: "failed",
+            };
+        }
+        return {
+            durationMs: Date.now() - start,
+            status: "success",
+            summary: `Report written to ${resolvedOutput}`,
+        };
+    }
+}

package/dist/orchestration/steps/run-eval-step.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pipeline step: Run Promptfoo evaluation.
+ *
+ * Uses ctx.evalRunner (the EvalRunner port) for the actual Promptfoo
+ * invocation. Builds a clean env object for the subprocess instead of
+ * polluting global process.env.
+ */
+import type { ConcreteEvalMode } from "../../_vendor/ailf-shared/index.d.ts";
+import type { AppContext, PipelineState, PipelineStep, StepResult, ValidationIssue } from "../../_vendor/ailf-core/index.d.ts";
+export declare class RunEvalStep implements PipelineStep {
+    private readonly mode;
+    readonly name: string;
+    constructor(mode: ConcreteEvalMode);
+    check(): ValidationIssue[];
+    execute(ctx: AppContext, state: PipelineState): Promise<StepResult>;
+    cacheInputs(ctx: AppContext): string[];
+}

package/dist/orchestration/steps/run-eval-step.js

@@ -0,0 +1,195 @@
+/**
+ * Pipeline step: Run Promptfoo evaluation.
+ *
+ * Uses ctx.evalRunner (the EvalRunner port) for the actual Promptfoo
+ * invocation. Builds a clean env object for the subprocess instead of
+ * polluting global process.env.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { resolve } from "path";
+import { getStepInputPaths } from "../../pipeline/cache.js";
+import { checkCanonicalContextsExist, checkGeneratedConfigsExist, checkResultsExist, } from "../../pipeline/checks.js";
+import { computeEvalFingerprint } from "../../pipeline/eval-fingerprint.js";
+import { buildFilterFlags, CONFIG_FILES, RESULTS_FILES, scanResultsForErrors, } from "../../pipeline/eval-constants.js";
+export class RunEvalStep {
+    mode;
+    name;
+    constructor(mode) {
+        this.mode = mode;
+        this.name = `eval-${mode}`;
+    }
+    check() {
+        return [];
+    }
+    async execute(ctx, state) {
+        if (ctx.config.skipEval) {
+            return { status: "skipped", reason: "--skip-eval" };
+        }
+        const start = Date.now();
+        const { rootDir, debug, concurrency, noCache } = ctx.config;
+        // Precondition: config file exists
+        const configIssues = checkGeneratedConfigsExist(rootDir);
+        const configErrors = configIssues.filter((i) => i.severity === "error");
+        if (configErrors.length > 0) {
+            return {
+                durationMs: Date.now() - start,
+                error: `Config files missing: ${configErrors.map((e) => e.message).join("; ")}`,
+                status: "failed",
+            };
+        }
+        // Precondition: canonical context files exist for filtered tasks.
+        // Must apply the same area/task filter as fetch-docs so we only
+        // check contexts that were actually fetched.
+        const filter = ctx.config.areas || ctx.config.tasks
+            ? {
+                ...(ctx.config.areas ? { areas: ctx.config.areas } : {}),
+                ...(ctx.config.tasks ? { taskIds: ctx.config.tasks } : {}),
+            }
+            : undefined;
+        const tasks = await ctx.taskSource.loadTasks(filter);
+        const taskIds = tasks.map((t) => t.id);
+        const contextIssues = checkCanonicalContextsExist(rootDir, taskIds);
+        const contextErrors = contextIssues.filter((i) => i.severity === "error");
+        if (contextErrors.length > 0) {
+            return {
+                durationMs: Date.now() - start,
+                error: `Context files missing. Run fetch-docs first. ${contextErrors.map((e) => e.message).join("; ")}`,
+                status: "failed",
+            };
+        }
+        // -----------------------------------------------------------------
+        // Compute eval fingerprint (for remote cache + provenance)
+        // -----------------------------------------------------------------
+        let evalFingerprint;
+        if (!debug?.enabled) {
+            try {
+                evalFingerprint = computeEvalFingerprint({
+                    filter: ctx.config.areas || ctx.config.tasks
+                        ? {
+                            areas: ctx.config.areas,
+                            taskIds: ctx.config.tasks,
+                        }
+                        : undefined,
+                    graderModel: "default",
+                    mode: this.mode,
+                    rootDir,
+                });
+                // Share fingerprint with downstream steps (PublishReportStep)
+                state.evalFingerprint = evalFingerprint;
+            }
+            catch (err) {
+                console.warn(`  ⚠️  Could not compute eval fingerprint: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // -----------------------------------------------------------------
+        // Remote cache check
+        // -----------------------------------------------------------------
+        if (evalFingerprint &&
+            !noCache &&
+            !ctx.config.noRemoteCache &&
+            ctx.reportStore) {
+            const remoteCacheResult = await checkRemoteCache(evalFingerprint, ctx.reportStore, rootDir);
+            if (remoteCacheResult) {
+                return {
+                    durationMs: Date.now() - start,
+                    status: "success",
+                    summary: `Skipped (remote cache hit) — reusing report ${remoteCacheResult.reportId} from ${remoteCacheResult.completedAt}`,
+                };
+            }
+        }
+        // -----------------------------------------------------------------
+        // Build subprocess env explicitly (no global mutation)
+        // -----------------------------------------------------------------
+        const subprocessEnv = {
+            PROMPTFOO_DISABLE_SHARE_EMAIL_REQUEST: "1",
+        };
+        // Only set env vars that differ from defaults — the subprocess inherits
+        // process.env via PromptfooEvalAdapter's { ...process.env, ...config.env }
+        if (ctx.config.mode !== "baseline") {
+            subprocessEnv.EVAL_MODE = ctx.config.mode;
+        }
+        if (ctx.config.searchMode !== "open") {
+            subprocessEnv.EVAL_SEARCH_MODE = ctx.config.searchMode;
+        }
+        if (ctx.config.allowedOrigins?.length) {
+            subprocessEnv.DOC_ALLOWED_ORIGINS = ctx.config.allowedOrigins.join(",");
+        }
+        // -----------------------------------------------------------------
+        // Execute — use the EvalRunner port
+        // -----------------------------------------------------------------
+        const configFile = CONFIG_FILES[this.mode];
+        const filterFlags = buildFilterFlags(debug);
+        const result = await ctx.evalRunner.run({
+            concurrency,
+            configPath: configFile,
+            env: subprocessEnv,
+            filterFlags: filterFlags.trim() || undefined,
+        });
+        // Check if results were written despite non-zero exit
+        if (result.status === "failed") {
+            const resultsExist = checkResultsExist(rootDir, RESULTS_FILES[this.mode]);
+            const hasResults = resultsExist.filter((i) => i.severity === "error").length === 0;
+            if (!hasResults) {
+                return {
+                    durationMs: Date.now() - start,
+                    error: result.error ?? `promptfoo eval failed (mode: ${this.mode})`,
+                    status: "failed",
+                };
+            }
+        }
+        // Postcondition: results file exists
+        const resultsIssues = checkResultsExist(rootDir, RESULTS_FILES[this.mode]);
+        const resultsErrors = resultsIssues.filter((i) => i.severity === "error");
+        if (resultsErrors.length > 0) {
+            return {
+                durationMs: Date.now() - start,
+                error: `Postcondition failed: ${resultsErrors.map((e) => e.message).join("; ")}`,
+                status: "failed",
+            };
+        }
+        // Scan results for errors
+        const errorSummary = scanResultsForErrors(resolve(rootDir, RESULTS_FILES[this.mode]));
+        if (errorSummary) {
+            console.log();
+            console.log(errorSummary);
+        }
+        const durationMs = Date.now() - start;
+        return {
+            durationMs,
+            status: "success",
+            summary: `Evaluation complete (mode: ${this.mode}${debug?.enabled ? ", debug" : ""})`,
+        };
+    }
+    cacheInputs(ctx) {
+        return getStepInputPaths(ctx.config.rootDir, `eval-${this.mode}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Remote cache helpers
+// ---------------------------------------------------------------------------
+async function checkRemoteCache(fingerprint, reportStore, rootDir) {
+    try {
+        const startQuery = Date.now();
+        const cachedReport = (await reportStore.findByFingerprint(fingerprint));
+        const queryMs = Date.now() - startQuery;
+        if (!cachedReport) {
+            console.log(`  ℹ️  Remote cache miss — no report matches fingerprint (${queryMs}ms)`);
+            return null;
+        }
+        const outDir = resolve(rootDir, "results", "latest");
+        if (!existsSync(outDir)) {
+            mkdirSync(outDir, { recursive: true });
+        }
+        writeFileSync(resolve(outDir, "score-summary.json"), JSON.stringify(cachedReport.summary, null, 2));
+        console.log(`  ✅ Remote cache hit — reusing report ${cachedReport.id} from ${cachedReport.completedAt}`);
+        console.log(`  ℹ️  Fingerprint: ${fingerprint.slice(0, 16)}... (${queryMs}ms)`);
+        return {
+            completedAt: cachedReport.completedAt,
+            reportId: cachedReport.id,
+        };
+    }
+    catch (err) {
+        console.warn(`  ⚠️  Remote cache check failed: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}

package/dist/orchestration/steps/validate-step.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pipeline step: Validate configuration.
+ *
+ * Wraps the existing validateConfiguration() + checkEnvironment() logic
+ * behind the PipelineStep interface.
+ */
+import type { AppContext, PipelineStep, StepResult, ValidationIssue } from "../../_vendor/ailf-core/index.d.ts";
+export declare class ValidateStep implements PipelineStep {
+    readonly name = "validate";
+    check(): ValidationIssue[];
+    execute(ctx: AppContext): Promise<StepResult>;
+}

package/dist/orchestration/steps/validate-step.js

@@ -0,0 +1,41 @@
+/**
+ * Pipeline step: Validate configuration.
+ *
+ * Wraps the existing validateConfiguration() + checkEnvironment() logic
+ * behind the PipelineStep interface.
+ */
+import { checkEnvironment } from "../../pipeline/checks.js";
+import { validateConfiguration } from "../../pipeline/validate.js";
+export class ValidateStep {
+    name = "validate";
+    check() {
+        // Validation step has no preconditions — it IS the precondition check.
+        return [];
+    }
+    async execute(ctx) {
+        const start = Date.now();
+        const validation = validateConfiguration(ctx.config.rootDir);
+        const envIssues = checkEnvironment(ctx.config.rootDir);
+        validation.issues.push(...envIssues);
+        const errors = validation.issues.filter((i) => i.severity === "error");
+        const warnings = validation.issues.filter((i) => i.severity === "warning");
+        for (const w of warnings) {
+            ctx.logger.warn(`[${w.source}] ${w.message}`);
+        }
+        if (errors.length > 0) {
+            for (const e of errors) {
+                ctx.logger.error(`[${e.source}] ${e.message}${e.path ? ` at ${e.path}` : ""}`);
+            }
+            return {
+                durationMs: Date.now() - start,
+                error: `Configuration invalid: ${errors.length} error(s)`,
+                status: "failed",
+            };
+        }
+        return {
+            durationMs: Date.now() - start,
+            status: "success",
+            summary: `Configuration valid (${warnings.length} warning(s))`,
+        };
+    }
+}