@sanity/ailf 2.0.0 → 2.0.2

package/dist/orchestration/build-app-context.js

@@ -8,7 +8,9 @@
  * Once all commands construct ResolvedConfig directly (or use --config),
  * this bridge can be deleted.
  */
+import { join } from "node:path";
 import { createAppContext } from "../composition-root.js";
+import { tryLoadConfigFile } from "../pipeline/compiler/config-loader.js";
 /**
  * Map legacy ResolvedOptions to ResolvedConfig.
  *
@@ -50,6 +52,7 @@ export function mapToResolvedConfig(opts, rootDir) {
         noCache: opts.noCache,
         noRemoteCache: opts.noRemoteCache,
         graderReplications: opts.graderReplications,
+        outputDir: opts.outputDir,
         outputPath: opts.outputPath,
         urls: opts.urlArgs.length > 0 ? opts.urlArgs : undefined,
         headers: opts.headerArgs.length > 0
@@ -75,6 +78,10 @@ export function mapToResolvedConfig(opts, rootDir) {
         remote: opts.remote ?? false,
         apiUrl: opts.apiUrl ?? "https://ailf-api.sanity.build",
         apiKey: opts.apiKey,
+        captureEnabled: opts.captureEnabled ?? false,
+        captureDir: opts.captureDir ?? join(rootDir, "results", "captures"),
+        captureCompress: opts.captureCompress ?? true,
+        captureExtras: opts.captureExtras ?? true,
     };
 }
 /**
@@ -85,5 +92,11 @@ export function mapToResolvedConfig(opts, rootDir) {
  */
 export function buildAppContext(opts, rootDir) {
     const config = mapToResolvedConfig(opts, rootDir);
+    // Inject config-file-only values that don't come from CLI options.
+    // evalBudgetMs lives on ModelsConfig, not CLI flags.
+    const models = tryLoadConfigFile("models", rootDir);
+    if (models?.data?.evalBudgetMs) {
+        config.evalBudgetMs = models.data.evalBudgetMs;
+    }
     return createAppContext(config);
 }

package/dist/orchestration/cache-context.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Build cache context strings from the resolved pipeline configuration.
+ *
+ * These non-file strings participate in cache key computation so that
+ * different CLI filters (mode, variant, area, task, tag) produce
+ * distinct cache entries. Without them, running `--mode knowledge-probe`
+ * after `--mode literacy` would return cached literacy results.
+ *
+ * @see packages/core/src/ports/pipeline-step.ts — cacheContext() method
+ * @see packages/eval/src/pipeline/cache.ts — hashFiles() context parameter
+ */
+import type { ResolvedConfig } from "../_vendor/ailf-core/index.d.ts";
+/**
+ * Derive deterministic context strings from the resolved pipeline config.
+ *
+ * Included in every cacheable step's key so that:
+ * - `--mode literacy` and `--mode knowledge-probe` never share cache
+ * - `--variant agentic` and `--variant baseline` never share cache
+ * - `--area studio` and `--area groq` never share cache
+ * - `--task T001` and `--task T002` never share cache
+ * - `--tag critical` and `--tag smoke` never share cache
+ */
+export declare function buildCacheContext(config: ResolvedConfig): string[];

package/dist/orchestration/cache-context.js

@@ -0,0 +1,43 @@
+/**
+ * Build cache context strings from the resolved pipeline configuration.
+ *
+ * These non-file strings participate in cache key computation so that
+ * different CLI filters (mode, variant, area, task, tag) produce
+ * distinct cache entries. Without them, running `--mode knowledge-probe`
+ * after `--mode literacy` would return cached literacy results.
+ *
+ * @see packages/core/src/ports/pipeline-step.ts — cacheContext() method
+ * @see packages/eval/src/pipeline/cache.ts — hashFiles() context parameter
+ */
+/**
+ * Derive deterministic context strings from the resolved pipeline config.
+ *
+ * Included in every cacheable step's key so that:
+ * - `--mode literacy` and `--mode knowledge-probe` never share cache
+ * - `--variant agentic` and `--variant baseline` never share cache
+ * - `--area studio` and `--area groq` never share cache
+ * - `--task T001` and `--task T002` never share cache
+ * - `--tag critical` and `--tag smoke` never share cache
+ */
+export function buildCacheContext(config) {
+    const context = [];
+    // Mode is always present — it's required in ResolvedConfig
+    context.push(`mode:${config.mode}`);
+    // Variant (literacy sub-mode: baseline, agentic, observed, full)
+    if (config.variant) {
+        context.push(`variant:${config.variant}`);
+    }
+    // Area filter — sorted for deterministic hashing
+    if (config.areas && config.areas.length > 0) {
+        context.push(`areas:${[...config.areas].sort().join(",")}`);
+    }
+    // Task filter — sorted for deterministic hashing
+    if (config.tasks && config.tasks.length > 0) {
+        context.push(`tasks:${[...config.tasks].sort().join(",")}`);
+    }
+    // Tag filter — sorted for deterministic hashing
+    if (config.tags && config.tags.length > 0) {
+        context.push(`tags:${[...config.tags].sort().join(",")}`);
+    }
+    return context;
+}

package/dist/orchestration/env-bridge.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Environment variable bridge — writes ResolvedConfig values to process.env
+ * so that lib/*.ts modules (which still read process.env) work correctly.
+ *
+ * This replaces the former global applyEnvironment() with an explicit
+ * per-step bridge. Each orchestration step calls this before invoking
+ * its lib/*.ts main() function.
+ *
+ * Phase 9 will eliminate this file entirely by giving lib/*.ts main()
+ * functions typed option parameters.
+ *
+ * @see docs/exec-plans/active/ports-and-adapters/phase-8-delete-legacy-step-layer.md
+ */
+import type { ResolvedConfig } from "../_vendor/ailf-core/index.d.ts";
+/**
+ * Bridge ResolvedConfig values to process.env.
+ *
+ * Idempotent — safe to call multiple times. Only sets env vars for
+ * config values that are defined (never deletes or resets).
+ */
+export declare function bridgeConfigToEnv(config: ResolvedConfig): void;

package/dist/orchestration/env-bridge.js

@@ -0,0 +1,66 @@
+/**
+ * Environment variable bridge — writes ResolvedConfig values to process.env
+ * so that lib/*.ts modules (which still read process.env) work correctly.
+ *
+ * This replaces the former global applyEnvironment() with an explicit
+ * per-step bridge. Each orchestration step calls this before invoking
+ * its lib/*.ts main() function.
+ *
+ * Phase 9 will eliminate this file entirely by giving lib/*.ts main()
+ * functions typed option parameters.
+ *
+ * @see docs/exec-plans/active/ports-and-adapters/phase-8-delete-legacy-step-layer.md
+ */
+/**
+ * Bridge ResolvedConfig values to process.env.
+ *
+ * Idempotent — safe to call multiple times. Only sets env vars for
+ * config values that are defined (never deletes or resets).
+ */
+export function bridgeConfigToEnv(config) {
+    // Mode
+    process.env.EVAL_MODE = config.mode;
+    // Search mode
+    if (config.searchMode !== "open") {
+        process.env.EVAL_SEARCH_MODE = config.searchMode;
+    }
+    // Source
+    if (config.source) {
+        process.env.DOC_SOURCE = config.source;
+    }
+    // URL-derived overrides
+    if (config.urls?.[0]) {
+        process.env.DOC_BASE_URL = config.urls[0];
+    }
+    // Sanity overrides
+    if (config.datasetOverride) {
+        process.env.SANITY_DATASET = config.datasetOverride;
+    }
+    if (config.projectIdOverride) {
+        process.env.SANITY_PROJECT_ID = config.projectIdOverride;
+    }
+    if (config.perspectiveOverride) {
+        process.env.SANITY_PERSPECTIVE = config.perspectiveOverride;
+    }
+    if (config.studioOriginOverride) {
+        process.env.SANITY_STUDIO_ORIGIN = config.studioOriginOverride;
+    }
+    if (config.sanityDocumentArgs?.length) {
+        process.env.SANITY_DOCUMENT_IDS = config.sanityDocumentArgs.join(",");
+    }
+    // Custom headers
+    if (config.headers) {
+        process.env.DOC_HEADERS = JSON.stringify(config.headers);
+    }
+    // Allowed origins
+    if (config.allowedOrigins?.length) {
+        process.env.DOC_ALLOWED_ORIGINS = config.allowedOrigins.join(",");
+    }
+    // Scoping filters
+    if (config.areas) {
+        process.env.EVAL_FILTER_AREAS = config.areas.join(",");
+    }
+    if (config.tasks) {
+        process.env.EVAL_FILTER_TASKS = config.tasks.join(",");
+    }
+}

package/dist/orchestration/load-pipeline-tasks.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared task loading for pipeline orchestration steps.
+ *
+ * Both FetchDocsStep and GenerateConfigsStep need to see the same set of
+ * tasks. This function loads from filesystem .task.ts files — the
+ * authoritative source for the current pipeline architecture.
+ *
+ * Background: The composition root wires ctx.taskSource to
+ * ContentLakeTaskSource by default, but GenerateConfigsStep bypasses it
+ * and loads directly from the filesystem. FetchDocsStep must use the
+ * same source to avoid a mismatch where configs reference context files
+ * that were never fetched.
+ *
+ * @see packages/eval/src/orchestration/steps/generate-configs-step.ts
+ * @see packages/eval/src/orchestration/steps/fetch-docs-step.ts
+ */
+import type { GeneralizedTaskDefinition } from "../_vendor/ailf-core/index.d.ts";
+export interface LoadPipelineTasksOptions {
+    /** Absolute path to the eval package root (packages/eval) */
+    rootDir: string;
+    /** Evaluation mode — determines the tasks/{mode}/ subdirectory */
+    mode: string;
+    /** Optional extra directory for repo-based tasks (--repo-tasks-path) */
+    repoTasksPath?: string;
+}
+/**
+ * Load task definitions from the filesystem, matching the pipeline's
+ * authoritative task source.
+ *
+ * Discovers and loads `*.task.ts` files from `tasks/{mode}/` and
+ * optionally `--repo-tasks-path`. Tasks whose `mode` field doesn't
+ * match the requested mode are excluded.
+ */
+export declare function loadPipelineTasks(opts: LoadPipelineTasksOptions): Promise<GeneralizedTaskDefinition[]>;

package/dist/orchestration/load-pipeline-tasks.js

@@ -0,0 +1,52 @@
+/**
+ * Shared task loading for pipeline orchestration steps.
+ *
+ * Both FetchDocsStep and GenerateConfigsStep need to see the same set of
+ * tasks. This function loads from filesystem .task.ts files — the
+ * authoritative source for the current pipeline architecture.
+ *
+ * Background: The composition root wires ctx.taskSource to
+ * ContentLakeTaskSource by default, but GenerateConfigsStep bypasses it
+ * and loads directly from the filesystem. FetchDocsStep must use the
+ * same source to avoid a mismatch where configs reference context files
+ * that were never fetched.
+ *
+ * @see packages/eval/src/orchestration/steps/generate-configs-step.ts
+ * @see packages/eval/src/orchestration/steps/fetch-docs-step.ts
+ */
+import { resolve } from "path";
+import { discoverTsTaskFiles, loadTsTaskFile, } from "../adapters/task-sources/task-file-loader.js";
+import { resolveVendoredSubdir } from "../pipeline/compiler/config-loader.js";
+/**
+ * Load task definitions from the filesystem, matching the pipeline's
+ * authoritative task source.
+ *
+ * Discovers and loads `*.task.ts` files from `tasks/{mode}/` and
+ * optionally `--repo-tasks-path`. Tasks whose `mode` field doesn't
+ * match the requested mode are excluded.
+ */
+export async function loadPipelineTasks(opts) {
+    const tasksDir = resolveVendoredSubdir(opts.rootDir, `tasks/${opts.mode}`);
+    const dirs = [tasksDir];
+    if (opts.repoTasksPath) {
+        const repoDir = resolve(opts.repoTasksPath);
+        if (!dirs.includes(repoDir)) {
+            dirs.push(repoDir);
+        }
+    }
+    const tasks = [];
+    for (const dir of dirs) {
+        const files = discoverTsTaskFiles(dir);
+        for (const file of files) {
+            const raw = await loadTsTaskFile(file);
+            for (const t of raw.tasks) {
+                const task = t;
+                // Filter to matching mode (skip tasks from other modes in same dir)
+                if (!("mode" in task) || task.mode === opts.mode) {
+                    tasks.push(task);
+                }
+            }
+        }
+    }
+    return tasks;
+}

package/dist/orchestration/pipeline-orchestrator.js

@@ -20,10 +20,20 @@ import { runStep } from "./step-runner.js";
  * underlying Sanity client. Best-effort — failures are logged and
  * never block the pipeline.
  */
-async function reportJobProgress(ctx, stepName, completedSteps, totalSteps, status, errorInfo) {
+async function reportJobProgress(ctx, stepName, completedSteps, totalSteps, status, errorInfo, jobUpdates) {
     const jobId = ctx.config.jobId;
     if (!jobId)
         return;
+    // Accumulate update for artifact capture
+    jobUpdates?.push({
+        jobId,
+        stepName,
+        completedSteps,
+        totalSteps,
+        status,
+        errorInfo,
+        timestamp: new Date().toISOString(),
+    });
     // Use the report store's write capability to patch the job document.
     // The report store exposes a Sanity client — we access it through
     // a best-effort PATCH via the same client infrastructure.
@@ -59,6 +69,51 @@ async function reportJobProgress(ctx, stepName, completedSteps, totalSteps, stat
     }
 }
 // ---------------------------------------------------------------------------
+// Artifact capture
+// ---------------------------------------------------------------------------
+/**
+ * Capture a snapshot of the pipeline config, final state, and step results.
+ * Strips secrets (API keys, tokens) from the config.
+ */
+function capturePipelineContext(ctx, state, results) {
+    if (!ctx.collector.enabled)
+        return;
+    const sanitized = Object.fromEntries(Object.entries(ctx.config).filter(([k]) => !/token|secret|key/i.test(k)));
+    ctx.collector.capture("pipeline", "pipeline-context", {
+        config: sanitized,
+        state: {
+            reportId: state.reportId,
+            evalFingerprint: state.evalFingerprint,
+            belowCritical: state.belowCritical,
+            remoteCacheHits: state.remoteCacheHits
+                ? [...state.remoteCacheHits]
+                : undefined,
+            releaseAutoScope: state.releaseAutoScope,
+            testSummary: state.testSummary,
+        },
+        steps: Object.entries(results).map(([name, result]) => ({
+            name,
+            status: result.status,
+            durationMs: result.status !== "skipped" ? result.durationMs : undefined,
+        })),
+    });
+}
+/**
+ * Flush captured artifacts to disk. Non-blocking — failures are logged
+ * but never affect the pipeline result.
+ */
+async function flushArtifacts(ctx) {
+    if (!ctx.collector.enabled)
+        return;
+    try {
+        const result = await ctx.collector.flush();
+        ctx.logger.info(`Captured ${result.artifactCount} artifacts → ${result.destination}`);
+    }
+    catch (err) {
+        ctx.logger.warn(`Artifact capture flush failed: ${err instanceof Error ? err.message : err}`);
+    }
+}
+// ---------------------------------------------------------------------------
 // Orchestrator
 // ---------------------------------------------------------------------------
 /**
@@ -76,6 +131,7 @@ export async function orchestratePipeline(ctx, steps) {
     const validation = { issues: [], valid: true };
     const pipelineStart = Date.now();
     const hasJob = !!ctx.config.jobId;
+    const jobUpdates = [];
     ctx.logger.section("ai-literacy-framework — Evaluation Pipeline");
     ctx.logger.debug(`Pipeline starting with ${steps.length} steps`, {
         steps: steps.map((s) => s.name),
@@ -86,7 +142,7 @@ export async function orchestratePipeline(ctx, steps) {
     });
     // Report initial running status
     if (hasJob) {
-        await reportJobProgress(ctx, steps[0]?.name ?? "init", 0, steps.length, "running");
+        await reportJobProgress(ctx, steps[0]?.name ?? "init", 0, steps.length, "running", undefined, jobUpdates);
     }
     for (let i = 0; i < steps.length; i++) {
         const step = steps[i];
@@ -94,7 +150,7 @@ export async function orchestratePipeline(ctx, steps) {
         ctx.logger.section(step.name);
         // Report current step progress
         if (hasJob) {
-            await reportJobProgress(ctx, step.name, i, steps.length, "running");
+            await reportJobProgress(ctx, step.name, i, steps.length, "running", undefined, jobUpdates);
         }
         const result = await runStep(step, ctx, state);
         results[step.name] = result;
@@ -111,8 +167,15 @@ export async function orchestratePipeline(ctx, steps) {
                 await reportJobProgress(ctx, step.name, i + 1, steps.length, "failed", {
                     message: failedError,
                     step: step.name,
-                });
+                }, jobUpdates);
             }
+            // Capture pipeline context and job updates before flushing
+            capturePipelineContext(ctx, state, results);
+            if (jobUpdates.length > 0) {
+                ctx.collector.capture("job-store", "job-updates", jobUpdates);
+            }
+            // Flush captured artifacts even on failure (partial capture is useful)
+            await flushArtifacts(ctx);
             return {
                 belowCritical: state.belowCritical,
                 durationMs: Date.now() - pipelineStart,
@@ -129,7 +192,7 @@ export async function orchestratePipeline(ctx, steps) {
         }
         // Report step completion
         if (hasJob) {
-            await reportJobProgress(ctx, step.name, i + 1, steps.length, "running");
+            await reportJobProgress(ctx, step.name, i + 1, steps.length, "running", undefined, jobUpdates);
         }
     }
     const durationMs = Date.now() - pipelineStart;
@@ -166,6 +229,13 @@ export async function orchestratePipeline(ctx, steps) {
             ctx.logger.warn("Failed to report job completion — continuing");
         }
     }
+    // Capture pipeline context and job updates before flushing
+    capturePipelineContext(ctx, state, results);
+    if (jobUpdates.length > 0) {
+        ctx.collector.capture("job-store", "job-updates", jobUpdates);
+    }
+    // Flush captured artifacts (non-blocking — failures never affect pipeline result)
+    await flushArtifacts(ctx);
     return {
         belowCritical: state.belowCritical,
         durationMs,

package/dist/orchestration/step-runner.js

@@ -36,8 +36,12 @@ export async function runStep(step, ctx, state = {}) {
     if (canCache) {
         try {
             const inputs = step.cacheInputs(ctx);
+            const context = step.cacheContext?.(ctx);
             ctx.logger.debug(`[${step.name}] Cache inputs: ${inputs.length} files`);
-            const key = await ctx.cache.computeKey(inputs);
+            if (context?.length) {
+                ctx.logger.debug(`[${step.name}] Cache context: ${context.join(", ")}`);
+            }
+            const key = await ctx.cache.computeKey(inputs, context);
             cacheKey = key;
             ctx.logger.debug(`[${step.name}] Cache key: ${key}`);
             const cached = await ctx.cache.lookup(step.name, key);

package/dist/orchestration/steps/calculate-scores-step.d.ts

@@ -10,4 +10,5 @@ export declare class CalculateScoresStep implements PipelineStep {
     check(): ValidationIssue[];
     execute(ctx: AppContext, state: PipelineState): Promise<StepResult>;
     cacheInputs(ctx: AppContext): string[];
+    cacheContext(ctx: AppContext): string[];
 }

package/dist/orchestration/steps/calculate-scores-step.js

@@ -4,9 +4,11 @@
  * Calls calculateAndWriteScores() from pipeline/calculate-scores.ts with
  * typed options derived from AppContext. No env bridge needed.
  */
+import { existsSync } from "node:fs";
 import { join } from "path";
 import { LiteracyVariant } from "../../pipeline/normalize-mode.js";
 import { getStepInputPaths } from "../../pipeline/cache.js";
+import { buildCacheContext } from "../cache-context.js";
 import { calculateAndWriteScores } from "../../pipeline/calculate-scores.js";
 import { checkResultsExist, checkScoreSummaryValid, } from "../../pipeline/checks.js";
 import { resultsFileForMode } from "../../pipeline/eval-constants.js";
@@ -118,6 +120,14 @@ export class CalculateScoresStep {
         if (belowCritical.length > 0) {
             state.belowCritical = belowCritical;
         }
+        // Capture score artifacts
+        const resultsDir = join(ctx.config.rootDir, "results", "latest");
+        for (const file of ["score-summary.json", "grader-judgments.json"]) {
+            const filePath = join(resultsDir, file);
+            if (existsSync(filePath)) {
+                ctx.collector.captureFile("calculate-scores", file.replace(".json", ""), filePath);
+            }
+        }
         const criticalSuffix = belowCritical.length > 0
             ? ` (${belowCritical.length} area(s) below critical threshold: ${belowCritical.join(", ")})`
             : "";
@@ -130,4 +140,7 @@ export class CalculateScoresStep {
     cacheInputs(ctx) {
         return getStepInputPaths(ctx.config.rootDir, "calculate-scores");
     }
+    cacheContext(ctx) {
+        return buildCacheContext(ctx.config);
+    }
 }

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

@@ -52,11 +52,20 @@ export class CallbackStep {
         }
         // Deliver callback — read reportId from pipeline state (set by PublishReportStep)
         ctx.logger.info(`Delivering results to ${this.callback.url}`);
-        const result = await deliverCallback(this.callback, {
+        const callbackPayload = {
             deliveredAt: new Date().toISOString(),
             jobId: this.jobId,
             reportId: state.reportId,
             summary,
+        };
+        // Capture callback payload (Tier 2 — no secrets: headers are NOT captured)
+        ctx.collector.capture("callback", "callback-payload", callbackPayload);
+        const result = await deliverCallback(this.callback, callbackPayload);
+        // Capture callback response status (not the body — that's the user's system)
+        ctx.collector.capture("callback", "callback-response", {
+            ok: result.ok,
+            attempts: result.attempts,
+            error: result.error,
         });
         if (result.ok) {
             return {

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

@@ -5,7 +5,7 @@
  * inlined directly from the former pipeline/steps/compare-step.ts.
  * This is an optional step — failure doesn't stop the pipeline.
  */
-import { existsSync, readFileSync, readdirSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from "fs";
 import { join, resolve } from "path";
 import { compare } from "../../pipeline/compare.js";
 export class CompareStep {
@@ -65,9 +65,12 @@ export class CompareStep {
             ? { noiseThreshold: ctx.config.compareThreshold }
             : undefined;
         const report = compare(baseline, experiment, options);
-        // Write report
-        const reportPath = resolve(rootDir, "results", "latest", "comparison-report.json");
+        // Write report to outputDir (respects --output-dir)
+        mkdirSync(ctx.config.outputDir, { recursive: true });
+        const reportPath = resolve(ctx.config.outputDir, "comparison-report.json");
         writeFileSync(reportPath, JSON.stringify(report, null, 2));
+        // Capture comparison report
+        ctx.collector.captureFile("compare", "comparison-report", reportPath);
         // Build summary
         const improved = report.improved.length;
         const regressed = report.regressed.length;

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

@@ -4,7 +4,7 @@
  * Calls pure functions from pipeline/discovery-report.ts directly.
  * Optional step — failure doesn't stop the pipeline.
  */
-import { existsSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { resolve } from "path";
 import { formatDiscoveryMarkdown, generateDiscoveryReport, } from "../../pipeline/discovery-report.js";
 export class DiscoveryReportStep {
@@ -34,7 +34,11 @@ export class DiscoveryReportStep {
             }
             const report = generateDiscoveryReport(scoreSummary, ctx.config.areas);
             const md = formatDiscoveryMarkdown(report);
-            writeFileSync(resolve(root, "results", "latest", "discovery-report.md"), md);
+            // Write to outputDir (respects --output-dir)
+            mkdirSync(ctx.config.outputDir, { recursive: true });
+            const discoveryPath = resolve(ctx.config.outputDir, "discovery-report.md");
+            writeFileSync(discoveryPath, md);
+            ctx.collector.captureFile("discovery-report", "discovery-report", discoveryPath);
             console.log(md);
             const invisible = report.invisibleDocs.length;
             const f1 = report.overall.avgF1.toFixed(2);

package/dist/orchestration/steps/fetch-docs-shell.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shell delegation for the fetch-docs step.
+ *
+ * Isolates the execSync call so it can be replaced when the pipeline
+ * fully migrates to the DocFetcher port.
+ */
+export interface ShellResult {
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Run `pnpm fetch-docs` via shell.
+ *
+ * Returns a result object instead of throwing so the step can
+ * handle the failure uniformly.
+ */
+export declare function runFetchDocsShell(rootDir: string, source?: string): ShellResult;

package/dist/orchestration/steps/fetch-docs-shell.js

@@ -0,0 +1,30 @@
+/**
+ * Shell delegation for the fetch-docs step.
+ *
+ * Isolates the execSync call so it can be replaced when the pipeline
+ * fully migrates to the DocFetcher port.
+ */
+import { execSync } from "child_process";
+/**
+ * Run `pnpm fetch-docs` via shell.
+ *
+ * Returns a result object instead of throwing so the step can
+ * handle the failure uniformly.
+ */
+export function runFetchDocsShell(rootDir, source) {
+    try {
+        const sourceArg = source ? ` --source ${source}` : "";
+        execSync(`pnpm fetch-docs${sourceArg}`, {
+            cwd: rootDir,
+            env: process.env,
+            stdio: "inherit",
+        });
+        return { ok: true };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}

package/dist/orchestration/steps/fetch-docs-step.d.ts

@@ -16,4 +16,5 @@ export declare class FetchDocsStep implements PipelineStep {
     check(): ValidationIssue[];
     execute(ctx: AppContext, state: PipelineState): Promise<StepResult>;
     cacheInputs(ctx: AppContext): string[];
+    cacheContext(ctx: AppContext): string[];
 }