@sanity/ailf 1.0.0 → 2.0.1

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[];
 }

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

@@ -10,11 +10,13 @@
  * and stores a `releaseAutoScope` entry in PipelineState. Downstream
  * steps (GenerateConfigsStep, RunEvalStep) use this to narrow scope.
  */
-import { mkdirSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
 import { isIdRef, isPathRef, isSlugRef, } from "../../_vendor/ailf-core/index.js";
 import { getStepInputPaths } from "../../pipeline/cache.js";
+import { buildCacheContext } from "../cache-context.js";
 import { checkCanonicalContextsExist } from "../../pipeline/checks.js";
+import { loadPipelineTasks } from "../load-pipeline-tasks.js";
 import { loadSource } from "../../sources.js";
 import { configToSourceOverrides } from "../config-to-source-overrides.js";
 export class FetchDocsStep {
@@ -27,16 +29,22 @@ export class FetchDocsStep {
             return { status: "skipped", reason: "--skip-fetch" };
         }
         const start = Date.now();
-        // Precondition: at least one task has canonical doc mappings
-        const allTasks = await ctx.taskSource.loadTasks(buildFilter(ctx));
+        // Load tasks from the filesystem — the same source GenerateConfigsStep
+        // uses. This replaces ctx.taskSource (ContentLakeTaskSource) which may
+        // have no ailf.task documents, causing a mismatch where generated
+        // configs reference context files that were never fetched.
+        const allTasks = await loadPipelineTasks({
+            rootDir: ctx.config.rootDir,
+            mode: ctx.config.mode,
+            repoTasksPath: ctx.config.repoTasksPath,
+        });
         // Bridge: narrow to literacy tasks for canonical doc access
         const literacyTasks = allTasks.filter((t) => t.mode === "literacy");
         const tasksWithDocs = literacyTasks.filter((t) => (t.context?.docs?.length ?? 0) > 0);
         if (tasksWithDocs.length === 0) {
             return {
-                durationMs: Date.now() - start,
-                error: "No tasks with canonical_docs found. Add canonical_docs to your task definitions.",
-                status: "failed",
+                status: "skipped",
+                reason: "No literacy tasks with canonical_docs — nothing to fetch",
             };
         }
         // Resolve source once with typed overrides
@@ -72,6 +80,21 @@ export class FetchDocsStep {
             if (result.metadata) {
                 writeMetadataFiles(ctx.config.rootDir, result.metadata);
             }
+            // Capture metadata files (mode-specific extras)
+            if (ctx.collector.extrasEnabled) {
+                const contextsDir = join(ctx.config.rootDir, "contexts");
+                for (const [type, filename] of [
+                    ["document-manifest", "document-manifest.json"],
+                    ["release-impact", "release-impact.json"],
+                    ["document-overlay", "document-overlay.json"],
+                    ["url-fetch", "url-fetch.json"],
+                ]) {
+                    const filePath = join(contextsDir, filename);
+                    if (existsSync(filePath)) {
+                        ctx.collector.captureFile("fetch-docs", type, filePath);
+                    }
+                }
+            }
         }
         catch (err) {
             return {
@@ -118,19 +141,9 @@ export class FetchDocsStep {
     cacheInputs(ctx) {
         return getStepInputPaths(ctx.config.rootDir, "fetch-docs");
     }
-}
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-function buildFilter(ctx) {
-    const { areas, tasks, tags } = ctx.config;
-    if (!areas && !tasks && !tags)
-        return undefined;
-    return {
-        ...(areas ? { areas } : {}),
-        ...(tasks ? { taskIds: tasks } : {}),
-        ...(tags ? { tags } : {}),
-    };
+    cacheContext(ctx) {
+        return buildCacheContext(ctx.config);
+    }
 }
 /**
  * Write metadata files returned by DocFetcher to the contexts/ directory.

package/dist/orchestration/steps/gap-analysis-step.js

@@ -14,7 +14,7 @@
  *
  * This is an optional step — failure doesn't stop the pipeline.
  */
-import { existsSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { join, resolve } from "path";
 import { isSlugRef } from "../../_vendor/ailf-core/index.js";
 export class GapAnalysisStep {
@@ -56,7 +56,9 @@ export class GapAnalysisStep {
             console.log(formatFailureModesConsole(failureModeReport));
             const gapReport = buildGapAnalysisReport(failureModeReport, scoreSummary.scores);
             console.log(formatGapAnalysisConsole(gapReport));
-            const outDir = resolve(root, "results", "latest");
+            // Write user-facing artifacts to outputDir (respects --output-dir)
+            const outDir = ctx.config.outputDir;
+            mkdirSync(outDir, { recursive: true });
             writeFileSync(join(outDir, "failure-modes.json"), JSON.stringify(failureModeReport, null, 2));
             writeFileSync(join(outDir, "gap-analysis.json"), JSON.stringify(gapReport, null, 2));
             const manifestPath = resolve(root, "contexts", "document-manifest.json");
@@ -166,6 +168,15 @@ export class GapAnalysisStep {
                 scores: enrichedScores,
             };
             writeFileSync(scoreSummaryPath, JSON.stringify(enrichedSummary, null, 2));
+            // Capture gap analysis artifacts
+            const failureModesPath = join(outDir, "failure-modes.json");
+            if (existsSync(failureModesPath)) {
+                ctx.collector.captureFile("gap-analysis", "failure-modes", failureModesPath);
+            }
+            const gapReportPath = join(outDir, "gap-analysis.json");
+            if (existsSync(gapReportPath)) {
+                ctx.collector.captureFile("gap-analysis", "gap-report", gapReportPath);
+            }
             const gapCount = gapReport.gaps.length;
             const classRate = failureModeReport.classificationRate.toFixed(0);
             return {

package/dist/orchestration/steps/generate-configs-step.d.ts

@@ -24,4 +24,5 @@ export declare class GenerateConfigsStep implements PipelineStep {
     private compileAll;
     private checkLiteracyPostconditions;
     cacheInputs(ctx: AppContext): string[];
+    cacheContext(ctx: AppContext): string[];
 }