@sanity/ailf 4.1.0 → 4.2.0

package/dist/_vendor/ailf-core/types/generalized-task.d.ts

@@ -97,6 +97,19 @@ export interface TaskOptions {
     /** Arbitrary Promptfoo overrides (escape hatch) */
     promptfooOverrides?: Record<string, unknown>;
 }
+/**
+ * Variable keys reserved by the AILF compilers. Populated automatically
+ * from canonical task fields; forbidden in `prompt.vars` to prevent silent
+ * override of canonical values.
+ */
+export type ReservedPromptVarKey = "task" | "docs" | "__featureArea";
+/**
+ * Variables for prompt-template interpolation. Freeform extras are
+ * allowed; reserved keys (see {@link ReservedPromptVarKey}) are forbidden.
+ */
+export type PromptVars = Record<string, unknown> & {
+    [K in ReservedPromptVarKey]?: never;
+};
 /** Fields shared by all task modes */
 export interface TaskCommonFields {
     /** Unique task identifier */
@@ -121,7 +134,11 @@ export interface TaskCommonFields {
     providers?: TaskProviderConfig[];
     /** Task-level execution options */
     options?: TaskOptions;
-    /** Prompt configuration */
+    /**
+     * Prompt configuration. Reserved `vars` keys (see
+     * {@link ReservedPromptVarKey}) are forbidden — use `prompt.text` for
+     * the prompt body and `context.docs` for documentation references.
+     */
     prompt?: {
         /** Named prompt template */
         template?: string;
@@ -129,8 +146,8 @@ export interface TaskCommonFields {
         text?: string;
         /** System message override */
         systemMessage?: string;
-        /** Variables for template interpolation */
-        vars?: Record<string, unknown>;
+        /** Variables for template interpolation (reserved keys forbidden) */
+        vars?: PromptVars;
     };
     /** Arbitrary metadata */
     metadata?: Record<string, unknown>;

package/dist/_vendor/ailf-core/types/index.d.ts

@@ -28,7 +28,7 @@ export type { AilfEvalWorkflow, AilfEvalWorkflowJob, AilfEvalWorkflowStep, RepoA
 export type { PipelineRequest, PipelineRequestCallback, PipelineRequestCallerExecutor, PipelineRequestCallerGit, PipelineRequestCallerOwner, PipelineRequestDebug, PipelineRequestTaskSource, } from "./pipeline-request.js";
 export type { ArtifactId, AssociationAxis, AssociationValues, Brand, EntryKey, Err, FixtureId, IdValidationError, NewReportId, Ok, ProviderId, PromptId, Result, ResultId, RubricId, RunFingerprint, RunId, SuiteId, TaskId, TaskSlug, TraceId, } from "./branded-ids.js";
 export { err, fixtureId, generateRunId, ok, providerId, resultId, runId, suiteId, taskId, traceId, } from "./branded-ids.js";
-export type { AgentHarnessTaskDefinition, ContentLakeAuthorableMode, ContentLakeAuthorableTask, CustomTaskDefinition, GeneralizedAssertionDefinition, GeneralizedDocRef, GeneralizedTaskDefinition, GeneralizedTemplatedAssertion, GeneralizedValueAssertion, IdDocRef, KnowledgeProbeTaskDefinition, LiteracyTaskDefinition, MCPServerTaskDefinition, PathDocRef, PerspectiveDocRef, RubricRef, SlugDocRef, TaskCommonFields, TaskDifficulty, TaskOptions, TaskProviderConfig, TaskStatus, } from "./generalized-task.js";
+export type { AgentHarnessTaskDefinition, ContentLakeAuthorableMode, ContentLakeAuthorableTask, CustomTaskDefinition, GeneralizedAssertionDefinition, GeneralizedDocRef, GeneralizedTaskDefinition, GeneralizedTemplatedAssertion, GeneralizedValueAssertion, IdDocRef, KnowledgeProbeTaskDefinition, LiteracyTaskDefinition, MCPServerTaskDefinition, PromptVars, PathDocRef, PerspectiveDocRef, ReservedPromptVarKey, RubricRef, SlugDocRef, TaskCommonFields, TaskDifficulty, TaskOptions, TaskProviderConfig, TaskStatus, } from "./generalized-task.js";
 type DocumentRef = _DocumentRef;
 /** Aggregated retrieval metrics for a feature area */
 export interface AreaRetrievalMetrics {

package/dist/adapters/doc-fetchers/sanity-doc-fetcher.d.ts

@@ -21,13 +21,29 @@ export declare class SanityDocFetcher implements DocFetcher {
     private fetchInternal;
     private fetchManifest;
     /**
-     * Batch-resolve document ID refs to their article slugs.
+     * Batch-resolve document ID refs without filtering on `_type`.
      *
-     * This bridges IdDocRef entries into the slug-based fetch pipeline.
-     * Articles are queried by _id and their slugs are returned for use
-     * in the existing slug-based content map.
+     * Articles are routed back into the slug-flow (so manifest, perspective
+     * diffing, and overlay handling continue to work unchanged). Non-articles
+     * are rendered eagerly via the renderer registry — `typesReference` gets
+     * a high-fidelity formatter; anything else falls through to the default
+     * walker so authors can pin marketing pages, glossary entries, etc.
+     * without an AILF code change.
+     *
+     * Three log shapes:
+     *   - `info` — doc rendered with the default formatter (suggests a
+     *     dedicated renderer would improve fidelity)
+     *   - `warn` — registered renderer produced empty content (W0195 AC#3)
+     *   - `warn` — id had no matching document (existed/wrong tenant/typo)
+     */
+    private resolveIdRefs;
+    /**
+     * Fetch the raw body of a Sanity file asset URL, used by the
+     * `typesReference` renderer to inline typedoc JSON. Returns `null`
+     * on any HTTP/network failure rather than throwing — the renderer
+     * surfaces a placeholder so the rest of the context still renders.
      */
-    private resolveIdRefsToSlugs;
+    private fetchAttachmentBody;
     /**
      * Resolve path-based canonical doc references to their article slugs.
      *

package/dist/adapters/doc-fetchers/sanity-doc-fetcher.js

@@ -18,8 +18,9 @@ import { join } from "path";
 import { canonicalDocRefLabel, isIdRef, isPathRef, isPerspectiveRef, isSlugRef, } from "../../_vendor/ailf-core/index.js";
 import { fetchUrlContent, } from "../../pipeline/fetch-url-content.js";
 import { createPerspectiveClient, createPublishedClient, getSanityClient, } from "../../sanity/client.js";
+import { renderDocument, } from "../../sanity/document-renderers.js";
 import { toMarkdown } from "../../sanity/portable-text.js";
-import { ALL_ARTICLES_QUERY, ALL_FEATURE_AREAS, ARTICLE_BY_ID_QUERY, ARTICLE_BY_SLUG_QUERY, ARTICLE_BY_SLUG_WITH_PERSPECTIVE_QUERY, ARTICLE_SLUG_BY_PATH_QUERY, ARTICLE_SLUG_BY_SECTION_PATH_QUERY, ARTICLES_IN_RELEASE_QUERY, ARTICLES_METADATA_BY_SLUGS_QUERY, FEATURE_AREA_QUERIES, } from "../../sanity/queries.js";
+import { ALL_ARTICLES_QUERY, ALL_FEATURE_AREAS, ARTICLE_BY_ID_QUERY, ARTICLE_BY_SLUG_QUERY, ARTICLE_BY_SLUG_WITH_PERSPECTIVE_QUERY, ARTICLE_SLUG_BY_PATH_QUERY, ARTICLE_SLUG_BY_SECTION_PATH_QUERY, ARTICLES_IN_RELEASE_QUERY, ARTICLES_METADATA_BY_SLUGS_QUERY, DOCS_BY_IDS_QUERY, FEATURE_AREA_QUERIES, } from "../../sanity/queries.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -99,9 +100,11 @@ export class SanityDocFetcher {
                 }
             }
         }
-        // Resolve ID refs → slugs via batch query
-        const idToSlug = await this.resolveIdRefsToSlugs(idRefs, source);
-        for (const slug of idToSlug.values()) {
+        // Resolve ID refs. Articles get added to allSlugs (legacy slug-flow takes
+        // over for fetch + render). Non-articles render directly via the renderer
+        // registry and bypass the slug-keyed content map.
+        const idResolution = await this.resolveIdRefs(idRefs, source);
+        for (const slug of idResolution.idToSlug.values()) {
             allSlugs.add(slug);
         }
         // Resolve path refs → slugs
@@ -118,8 +121,14 @@ export class SanityDocFetcher {
             }
         }
         const metadata = {};
-        // 2. Fetch document manifest (traceability metadata)
+        // 2. Fetch document manifest (traceability metadata). Articles flow
+        // through fetchManifest; non-article id-refs contribute their own
+        // entries from the resolution we already did above.
         const manifest = await this.fetchManifest(allSlugs, source);
+        for (const extra of idResolution.extraManifest) {
+            manifest.push(extra);
+        }
+        manifest.sort((a, b) => a.slug.localeCompare(b.slug));
         if (manifest.length > 0) {
             metadata.manifest = manifest;
         }
@@ -232,12 +241,22 @@ export class SanityDocFetcher {
                     }
                     continue;
                 }
+                // Non-article id-refs bypass the slug-keyed content map: their
+                // rendered Markdown was produced by `resolveIdRefs` and is cached
+                // by document `_id`. Article id-refs continue to go through the
+                // slug-flow below (consistent with overlay/perspective handling).
+                if (isIdRef(ref) && idResolution.contentById.has(ref.id)) {
+                    const entry = idResolution.contentById.get(ref.id);
+                    parts.push(entry.content);
+                    slugs.push(entry.slug);
+                    continue;
+                }
                 let slug;
                 if (isSlugRef(ref)) {
                     slug = ref.slug;
                 }
                 else if (isIdRef(ref)) {
-                    slug = idToSlug.get(ref.id);
+                    slug = idResolution.idToSlug.get(ref.id);
                 }
                 else if (isPathRef(ref)) {
                     slug = pathToSlug.get(ref.path);
@@ -289,40 +308,125 @@ export class SanityDocFetcher {
             .sort((a, b) => a.slug.localeCompare(b.slug));
     }
     // -----------------------------------------------------------------------
-    // Private: Resolve ID refs to slugs
+    // Private: Resolve ID refs (type-agnostic)
     // -----------------------------------------------------------------------
     /**
-     * Batch-resolve document ID refs to their article slugs.
+     * Batch-resolve document ID refs without filtering on `_type`.
+     *
+     * Articles are routed back into the slug-flow (so manifest, perspective
+     * diffing, and overlay handling continue to work unchanged). Non-articles
+     * are rendered eagerly via the renderer registry — `typesReference` gets
+     * a high-fidelity formatter; anything else falls through to the default
+     * walker so authors can pin marketing pages, glossary entries, etc.
+     * without an AILF code change.
      *
-     * This bridges IdDocRef entries into the slug-based fetch pipeline.
-     * Articles are queried by _id and their slugs are returned for use
-     * in the existing slug-based content map.
+     * Three log shapes:
+     *   - `info` — doc rendered with the default formatter (suggests a
+     *     dedicated renderer would improve fidelity)
+     *   - `warn` — registered renderer produced empty content (W0195 AC#3)
+     *   - `warn` — id had no matching document (existed/wrong tenant/typo)
      */
-    async resolveIdRefsToSlugs(idRefs, source) {
-        const result = new Map();
+    async resolveIdRefs(idRefs, source) {
+        const idToSlug = new Map();
+        const contentById = new Map();
+        const extraManifest = [];
         if (idRefs.length === 0)
-            return result;
+            return { idToSlug, contentById, extraManifest };
         const uniqueIds = [...new Set(idRefs.map((r) => r.id))];
+        const taskByRef = new Map();
+        for (const { id, taskId } of idRefs) {
+            const existing = taskByRef.get(id) ?? [];
+            existing.push(taskId);
+            taskByRef.set(id, existing);
+        }
         const client = source?.perspective
             ? createPerspectiveClient(source.perspective, source)
             : getSanityClient(toSanityOverrides(source));
-        // Batch query: fetch slug for each document ID
-        const articles = await client.fetch(`*[_type == "article" && _id in $ids] { _id, "slug": slug.current }`, { ids: uniqueIds });
-        const idToSlugMap = new Map(articles.map((a) => [a._id, a.slug]));
-        for (const { id, taskId } of idRefs) {
-            const slug = idToSlugMap.get(id);
-            if (slug) {
-                result.set(id, slug);
+        const docs = await client.fetch(DOCS_BY_IDS_QUERY, {
+            ids: uniqueIds,
+        });
+        const docsById = new Map(docs.map((d) => [d._id, d]));
+        let articleCount = 0;
+        let highFidelity = 0;
+        let defaultFidelity = 0;
+        for (const id of uniqueIds) {
+            const taskIds = taskByRef.get(id) ?? [];
+            const doc = docsById.get(id);
+            if (!doc) {
+                console.warn(`    [warn] doc "${id}" not found (referenced by task(s): ${taskIds.join(", ")})`);
+                continue;
+            }
+            // Article id-refs flow back into the slug-keyed pipeline so manifest,
+            // perspective diff, and document overlay continue to work. The slug
+            // projection in DOCS_BY_IDS_QUERY mirrors ARTICLE_PROJECTION.
+            if (doc._type === "article") {
+                const slug = doc.slug;
+                if (typeof slug === "string" && slug.length > 0) {
+                    idToSlug.set(id, slug);
+                    articleCount += 1;
+                }
+                else {
+                    console.warn(`    [warn] article "${id}" has no slug (referenced by task(s): ${taskIds.join(", ")})`);
+                }
+                continue;
+            }
+            const rendered = await renderDocument(doc, {
+                fetchUrl: this.fetchAttachmentBody,
+            });
+            if (!rendered.content) {
+                console.warn(`    [warn] doc "${id}" resolved as "${doc._type}" but produced empty context (referenced by task(s): ${taskIds.join(", ")})`);
+                continue;
+            }
+            contentById.set(id, {
+                content: rendered.content,
+                slug: rendered.slug,
+                type: doc._type,
+            });
+            const _rev = doc._rev;
+            const title = doc.title;
+            extraManifest.push({
+                _id: doc._id,
+                _rev: typeof _rev === "string" ? _rev : "",
+                slug: rendered.slug,
+                title: typeof title === "string" ? title : `(${doc._type})`,
+            });
+            if (rendered.fidelity === "default") {
+                console.log(`    [info] doc "${id}" rendered with default formatter — a dedicated renderer for "${doc._type}" would likely improve grader fidelity`);
+                defaultFidelity += 1;
             }
             else {
-                console.warn(`    [warn] No article found for document ID "${id}" (referenced by task "${taskId}")`);
+                highFidelity += 1;
             }
         }
-        if (result.size > 0) {
-            console.log(`  Resolved ${result.size} document ID ref(s) to slugs`);
+        if (articleCount > 0) {
+            console.log(`  Resolved ${articleCount} article id ref(s) to slugs`);
         }
-        return result;
+        if (highFidelity + defaultFidelity > 0) {
+            console.log(`  Resolved ${highFidelity + defaultFidelity} non-article id ref(s) (${highFidelity} high-fidelity, ${defaultFidelity} default)`);
+        }
+        return { idToSlug, contentById, extraManifest };
     }
+    /**
+     * Fetch the raw body of a Sanity file asset URL, used by the
+     * `typesReference` renderer to inline typedoc JSON. Returns `null`
+     * on any HTTP/network failure rather than throwing — the renderer
+     * surfaces a placeholder so the rest of the context still renders.
+     */
+    fetchAttachmentBody = async (url) => {
+        try {
+            const response = await fetch(url);
+            if (!response.ok) {
+                console.warn(`    [warn] attachment fetch failed for ${url}: HTTP ${response.status}`);
+                return null;
+            }
+            return await response.text();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`    [warn] attachment fetch failed for ${url}: ${msg}`);
+            return null;
+        }
+    };
     // -----------------------------------------------------------------------
     // Private: Resolve path refs to slugs
     // -----------------------------------------------------------------------

package/dist/adapters/task-sources/repo-schemas.d.ts

@@ -1425,6 +1425,22 @@ export declare function parseCanonicalTaskFile(raw: unknown, filename: string):
  * GeneralizedTaskDefinition shape.
  */
 export declare function detectLegacyFieldNames(raw: unknown, filename: string): string[];
+interface MigrationResult {
+    migrated: unknown;
+    warnings: string[];
+}
+/**
+ * Pre-process legacy `prompt.vars.{task,docs,__featureArea}` into the
+ * canonical shape. Backwards-compatible: legacy-shape tasks continue to
+ * load, but a deprecation warning is emitted per affected task.
+ *
+ *   Legacy:    prompt: { vars: { task: "...", docs: "file://..." } }
+ *   Canonical: prompt: { text: "..." }
+ *
+ * Applies to every task regardless of mode. Per-task dedup: at most one
+ * warning per task per call, listing every reserved key that was present.
+ */
+export declare function migratePromptShape(raw: unknown, filename: string): MigrationResult;
 /**
  * Zod schema for .ailf/config.yaml — controls documentation source,
  * report destination, and trigger behavior for evaluations from an

package/dist/adapters/task-sources/repo-schemas.js

@@ -141,11 +141,30 @@ const AssertionSchema = z.union([
 // ---------------------------------------------------------------------------
 // Shared field schemas — building blocks reused across mode variants
 // ---------------------------------------------------------------------------
+/**
+ * Variable keys reserved by the AILF compilers — populated automatically
+ * from canonical task fields (`prompt.text`, `context.docs`, `area`).
+ * Mirrors `ReservedPromptVarKey` in `@sanity/ailf-core`; the `satisfies`
+ * clause makes drift a build error.
+ */
+const RESERVED_PROMPT_VAR_KEYS = [
+    "task",
+    "docs",
+    "__featureArea",
+];
 const TaskPromptSchema = z.object({
     template: z.string().optional(),
     text: z.string().optional(),
     systemMessage: z.string().optional(),
-    vars: z.record(z.string(), z.unknown()).optional(),
+    vars: z
+        .record(z.string(), z.unknown())
+        .refine((vars) => !RESERVED_PROMPT_VAR_KEYS.some((key) => key in vars), {
+        message: `prompt.vars contains a reserved key. Reserved keys: ` +
+            RESERVED_PROMPT_VAR_KEYS.join(", ") +
+            `. Use prompt.text for the prompt body and context.docs for ` +
+            `documentation references.`,
+    })
+        .optional(),
 });
 const RubricRefSchema = z.union([
     z.object({ ref: z.string().min(1) }),
@@ -416,6 +435,64 @@ export function detectLegacyFieldNames(raw, filename) {
     }
     return warnings;
 }
+/**
+ * Pre-process legacy `prompt.vars.{task,docs,__featureArea}` into the
+ * canonical shape. Backwards-compatible: legacy-shape tasks continue to
+ * load, but a deprecation warning is emitted per affected task.
+ *
+ *   Legacy:    prompt: { vars: { task: "...", docs: "file://..." } }
+ *   Canonical: prompt: { text: "..." }
+ *
+ * Applies to every task regardless of mode. Per-task dedup: at most one
+ * warning per task per call, listing every reserved key that was present.
+ */
+export function migratePromptShape(raw, filename) {
+    if (!Array.isArray(raw))
+        return { migrated: raw, warnings: [] };
+    const warnings = [];
+    const migrated = raw.map((entry, i) => {
+        if (typeof entry !== "object" || entry === null)
+            return entry;
+        const obj = entry;
+        const prompt = obj.prompt;
+        if (typeof prompt !== "object" || prompt === null)
+            return entry;
+        const promptObj = prompt;
+        const vars = promptObj.vars;
+        if (typeof vars !== "object" || vars === null)
+            return entry;
+        const varsObj = vars;
+        // Detect which reserved keys are present
+        const presentReserved = RESERVED_PROMPT_VAR_KEYS.filter((key) => key in varsObj);
+        if (presentReserved.length === 0)
+            return entry;
+        const taskId = typeof obj.id === "string" ? obj.id : `task[${i}]`;
+        // Build migrated prompt + vars
+        const newPrompt = { ...promptObj };
+        const newVars = { ...varsObj };
+        for (const key of presentReserved) {
+            if (key === "task" && newPrompt.text === undefined) {
+                // Move the prompt body to prompt.text only if the canonical slot
+                // is unset; an explicit prompt.text always wins.
+                newPrompt.text = newVars.task;
+            }
+            delete newVars[key];
+        }
+        // Drop empty vars to keep the migrated shape minimal
+        if (Object.keys(newVars).length === 0) {
+            delete newPrompt.vars;
+        }
+        else {
+            newPrompt.vars = newVars;
+        }
+        warnings.push(`[${filename}] ${taskId}: deprecated prompt.vars keys ` +
+            `(${presentReserved.join(", ")}) — migrated to canonical shape ` +
+            `(prompt.text + context.docs). Update the task source to silence ` +
+            `this warning.`);
+        return { ...obj, prompt: newPrompt };
+    });
+    return { migrated, warnings };
+}
 // ---------------------------------------------------------------------------
 // Config schemas — specific to the eval pipeline
 // ---------------------------------------------------------------------------

package/dist/adapters/task-sources/repo-task-source.js

@@ -22,7 +22,7 @@ import { existsSync, readdirSync, readFileSync } from "fs";
 import { resolve } from "path";
 import { load } from "js-yaml";
 import { CANONICAL_EVAL_MODES } from "../../_vendor/ailf-shared/index.js";
-import { detectLegacyFieldNames, parseCanonicalTaskFile, } from "./repo-schemas.js";
+import { detectLegacyFieldNames, migratePromptShape, parseCanonicalTaskFile, } from "./repo-schemas.js";
 import { discoverTsTaskFiles, loadTsTaskFile } from "./task-file-loader.js";
 /** Set of canonical mode names for O(1) lookup */
 const KNOWN_MODES = new Set(CANONICAL_EVAL_MODES);
@@ -69,10 +69,19 @@ export class RepoTaskSource {
                     legacyWarnings.join("\n") +
                     "\n\nSee contributing-tasks.md for the canonical task format.");
             }
+            // W0193: pre-migrate legacy prompt.vars.{task,docs,__featureArea}
+            // to the canonical prompt.text + context.docs shape. Mode-agnostic —
+            // every mode's TaskPromptSchema rejects reserved keys, so the shim
+            // unblocks legacy tasks regardless of mode. Per-task deprecation
+            // warning fires on stderr.
+            const { migrated, warnings: deprecationWarnings } = migratePromptShape(parsed, file);
+            for (const warning of deprecationWarnings) {
+                console.warn(warning);
+            }
             // Validate through canonical Zod schema
             let validated;
             try {
-                validated = parseCanonicalTaskFile(parsed, file);
+                validated = parseCanonicalTaskFile(migrated, file);
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);

package/dist/commands/validate-tasks.js

@@ -17,7 +17,7 @@ import { existsSync, readdirSync, readFileSync } from "fs";
 import { resolve, relative, basename } from "path";
 import { Command } from "commander";
 import { load } from "js-yaml";
-import { detectLegacyFieldNames, parseCanonicalTaskFile, } from "../adapters/task-sources/repo-schemas.js";
+import { detectLegacyFieldNames, migratePromptShape, parseCanonicalTaskFile, } from "../adapters/task-sources/repo-schemas.js";
 import { validateCanonicalTasks, formatRepoValidationResult, } from "../adapters/task-sources/repo-validation.js";
 import { discoverTsTaskFiles, loadTsTaskFile, } from "../adapters/task-sources/task-file-loader.js";
 export function createValidateTasksCommand() {
@@ -133,8 +133,14 @@ function validateTaskArray(entries, file, accumulator) {
         console.error();
         return false;
     }
+    // W0193: pre-migrate legacy prompt.vars.{task,docs,__featureArea} shape
+    // and surface deprecation warnings (non-fatal — the file still validates).
+    const { migrated, warnings: deprecationWarnings } = migratePromptShape(entries, file);
+    for (const warning of deprecationWarnings) {
+        console.warn(`  ${warning}`);
+    }
     try {
-        const tasks = parseCanonicalTaskFile(entries, file);
+        const tasks = parseCanonicalTaskFile(migrated, file);
         console.log(`  ${file}: ${tasks.length} task${tasks.length === 1 ? "" : "s"} valid`);
         accumulator.push(...tasks);
         return true;

package/dist/pipeline/compiler/mode-handlers/__fixtures__/agent-harness-example-tasks.js

@@ -30,10 +30,6 @@ export const scaffoldProjectTask = {
             "2. Configure sanity.config.ts with project ID 'test-project' and dataset 'production'\n" +
             "3. Create a 'post' schema type with title, slug, body, and author fields\n" +
             "4. Ensure the project builds without errors",
-        vars: {
-            task: "Scaffold a Sanity Studio project with a post schema type. " +
-                "The project should build cleanly.",
-        },
     },
     assertions: [
         { type: "file-exists", value: "sanity.config.ts" },
@@ -70,10 +66,6 @@ export const modifyCodeTask = {
         text: "In the existing Sanity Studio project, add a custom document action " +
             "that logs a message before publishing. Follow the Sanity docs for " +
             "custom document actions.",
-        vars: {
-            task: "Add a custom document action that wraps the default publish action " +
-                "and logs 'Publishing document: <title>' before executing.",
-        },
     },
     assertions: [
         { type: "file-exists", value: "actions/logPublishAction.ts" },
@@ -127,10 +119,6 @@ export const multiFileRefactorTask = {
             "3. Query method calls (fetch → client.fetch with new signature)\n" +
             "4. Mutation helpers (create/patch/delete API changes)\n" +
             "Ensure the project compiles after migration.",
-        vars: {
-            task: "Migrate the codebase from @sanity/client v5 to v6, " +
-                "updating all files. Project must compile cleanly after migration.",
-        },
     },
     assertions: [
         {

package/dist/pipeline/compiler/mode-handlers/__fixtures__/knowledge-probe-example-tasks.js

@@ -38,10 +38,6 @@ export const groqProjectionTask = {
             "5. Array slicing with `[0..5]` and `[0...5]`\n" +
             "6. Conditional projections using `select()`\n\n" +
             "Provide working code examples for each.",
-        vars: {
-            task: "Explain GROQ projection syntax with working code examples " +
-                "covering projections, spread, dereference, slicing, and select().",
-        },
     },
     assertions: [
         { type: "contains", value: "->" },
@@ -89,10 +85,6 @@ export const defineTypeApiTask = {
             "3. Why were these typed helpers introduced? What did they replace?\n" +
             "4. Show a complete example of a document schema with various field types\n" +
             "5. How do you add validation rules using the typed API?",
-        vars: {
-            task: "Explain Sanity's defineType/defineField schema API with examples, " +
-                "motivation, and validation rules.",
-        },
     },
     assertions: [
         { type: "contains", value: "defineType" },
@@ -142,10 +134,6 @@ export const ecosystemComparisonTask = {
             "4. Developer experience and customization\n" +
             "5. Pricing models\n" +
             "6. When would you choose one over the other?",
-        vars: {
-            task: "Compare Sanity and Contentful across architecture, content modeling, " +
-                "querying, DX, pricing, and use case fit.",
-        },
     },
     assertions: [
         { type: "contains-any", value: ["GROQ", "groq"] },

package/dist/pipeline/compiler/mode-handlers/literacy/compiler.js

@@ -10,6 +10,18 @@ import { LiteracyVariant, } from "../../../normalize-mode.js";
 import { buildBaselineAssertions, resolveAssertions } from "./assertions.js";
 import { LITERACY_PROMPT_TEMPLATES } from "./prompts.js";
 import { validateLiteracyTask } from "./validation.js";
+/**
+ * Variable keys reserved by the AILF compilers. Authoring these via
+ * `prompt.vars` is rejected by `PromptVars` at compile time and by
+ * `TaskPromptSchema` at parse time; this constant exists to defend
+ * the literacy compiler at runtime against legacy-shape `*.task.ts`
+ * files that bypass both gates.
+ */
+const RESERVED_PROMPT_VAR_KEYS = [
+    "task",
+    "docs",
+    "__featureArea",
+];
 /**
  * Compile a literacy task into Promptfoo configuration.
  */
@@ -58,20 +70,47 @@ function buildPrompts(evalMode) {
 // ---------------------------------------------------------------------------
 function buildTestCases(task, evalMode, options, warnings) {
     const tests = [];
-    const promptText = task.prompt?.text ?? task.prompt?.template ?? "";
+    // W0193: type-erased read of prompt.vars so we can defensively detect
+    // reserved keys on legacy-shape `*.task.ts` files (the type narrow makes
+    // `task.prompt.vars.task` `never`, but TS task files bypass both the
+    // type and the parse-time schema). YAML/inline-task paths have already
+    // been migrated by `migratePromptShape` upstream.
+    const rawVars = (task.prompt?.vars ?? {});
+    const legacyTaskBody = typeof rawVars.task === "string" ? rawVars.task : undefined;
+    const promptText = task.prompt?.text ?? legacyTaskBody ?? task.prompt?.template ?? "";
     const contextDocs = task.context?.docs ?? [];
     const taskArea = task.area ?? "";
     const taskTitle = task.title;
-    const promptVars = task.prompt?.vars ?? {};
+    // Strip reserved keys from the vars spread so they cannot override the
+    // canonical assignments below. `safePromptVars` carries only freeform
+    // template extras.
+    const safePromptVars = {};
+    const presentReserved = [];
+    for (const [key, value] of Object.entries(rawVars)) {
+        if (RESERVED_PROMPT_VAR_KEYS.includes(key)) {
+            presentReserved.push(key);
+            continue;
+        }
+        safePromptVars[key] = value;
+    }
+    // Single deduplicated deprecation warning per task — even when several
+    // reserved keys are present.
+    if (presentReserved.length > 0) {
+        warnings.push(`Literacy task "${task.id}": deprecated prompt.vars keys ` +
+            `(${presentReserved.join(", ")}) — use prompt.text for the prompt ` +
+            `body and context.docs for documentation references. The compiler ` +
+            `migrated them in-memory, but the task source should be updated.`);
+    }
     const hasDocs = contextDocs.length > 0;
     const docsVar = hasDocs ? `file://contexts/canonical/${task.id}.md` : "";
     const assertions = resolveAssertions(task, options, warnings);
-    // Gold entry — canonical docs injected
+    // Gold entry — canonical docs injected. Spread freeform extras first so
+    // canonical keys (task / docs / __featureArea) cannot be overridden.
     const goldVars = {
+        ...safePromptVars,
         task: promptText,
         docs: docsVar,
         __featureArea: taskArea,
-        ...promptVars,
     };
     tests.push({
         description: `${taskTitle} (gold)`,
@@ -89,10 +128,10 @@ function buildTestCases(task, evalMode, options, warnings) {
             tests.push({
                 description: `${taskTitle} (baseline)`,
                 vars: {
+                    ...safePromptVars,
                     task: promptText,
                     docs: "",
                     __featureArea: taskArea,
-                    ...promptVars,
                 },
                 prompts: ["without-docs"],
                 ...(baselineAssertions.length > 0