@sanity/ailf 3.7.0 → 3.8.0

package/dist/adapters/config-sources/file-config-adapter.js

@@ -1,7 +1,7 @@
 /**
  * FileConfigAdapter — resolves pipeline config from a local config file.
  *
- * Enables `ailf pipeline --config <path>` to load all pipeline options
+ * Enables `ailf run --config <path>` to load all pipeline options
  * from a file instead of CLI flags. Supports multiple formats in
  * priority order:
  *
@@ -91,9 +91,16 @@ function mapEvalConfigToResolvedConfig(config, rootDir) {
     }
     // Normalize legacy mode names (e.g., "full" → literacy + variant)
     const normalized = normalizeMode(config.mode ?? "literacy");
+    // Output directory (W0077 Phase 6c) — resolve `output.dir` relative to the
+    // rootDir (the caller's workspace, set by the FileConfigAdapter caller).
+    // When unset, fall back to <rootDir>/.ailf/results/latest/ to mirror the
+    // CLI's default. This matches `resolveOutputDir` for the auto-load path.
+    const outputDir = config.output?.dir
+        ? resolve(rootDir, config.output.dir)
+        : resolve(rootDir, ".ailf", "results", "latest");
     return {
         rootDir,
-        outputDir: resolve(rootDir, "results", "latest"),
+        outputDir,
         mode: normalized.mode,
         variant: normalized.variant,
         noAutoScope: config.noAutoScope ?? false,
@@ -107,21 +114,40 @@ function mapEvalConfigToResolvedConfig(config, rootDir) {
         compareEnabled: config.compare ?? false,
         compareThreshold: config.compareThreshold,
         compareBaseline: config.compareBaseline,
-        gapAnalysisEnabled: config.gapAnalysis ?? true,
-        readinessEnabled: config.readiness ?? false,
-        discoveryReportEnabled: config.discoveryReport ?? false,
-        publishEnabled: config.publish ?? false,
-        publishTag: config.publishTag,
+        gapAnalysisEnabled: config.execution?.gapAnalysis ?? true,
+        // W0077 Phase 4 — `publish` is now a policy object. Map the auto value
+        // directly to a boolean for the file-config path; the runtime
+        // smart-default logic in pipeline-action.ts isn't relevant here because
+        // the user has explicitly handed us a config file.
+        publishEnabled: config.publish?.auto === "never"
+            ? false
+            : config.publish?.auto !== undefined,
+        publishTag: config.publish?.tag,
         noCache: config.noCache ?? false,
         noRemoteCache: config.noRemoteCache ?? false,
-        graderReplications: config.graderReplications,
+        graderReplications: config.execution?.graderReplications,
         urls: config.urls,
-        headers: config.headers,
-        allowedOrigins: config.allowedOrigins,
+        headers: config.agentic?.headers,
+        allowedOrigins: config.agentic?.allowedOrigins,
         searchMode: config.searchMode ?? "open",
-        concurrency: config.concurrency,
+        concurrency: config.execution?.concurrency,
         remote: false,
-        apiUrl: "https://ailf-api.sanity.build",
+        apiUrl: config.execution?.apiUrl ?? "https://ailf-api.sanity.build",
+        // W0077 Phase 6g — artifact writer settings. `enabled: false` flips
+        // `artifactsDisabled` so composition-root selects the NoOp writer.
+        artifactsDisabled: config.artifacts?.enabled === false ? true : undefined,
+        artifactsDir: config.artifacts?.dir
+            ? resolve(rootDir, config.artifacts.dir)
+            : undefined,
+        artifactsExclude: config.artifacts?.exclude,
+        // W0077 Phase 6h — task-source selection. Default is content-lake
+        // (signaled by `taskSourceType` undefined); when `repo`, the
+        // composition-root resolves `repoTasksPath` (defaulting to
+        // `<rootDir>/.ailf/tasks/` when unset).
+        taskSourceType: config.taskSource?.type === "repo" ? "repo" : undefined,
+        repoTasksPath: config.taskSource?.repoTasksPath
+            ? resolve(rootDir, config.taskSource.repoTasksPath)
+            : undefined,
         presets: config.presets,
     };
 }

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

@@ -1434,11 +1434,49 @@ export declare const RepoConfigSchema: z.ZodObject<{
         projectId: z.ZodOptional<z.ZodString>;
         dataset: z.ZodOptional<z.ZodString>;
         baseUrl: z.ZodOptional<z.ZodString>;
+        studioOrigin: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     reportStore: z.ZodOptional<z.ZodObject<{
         projectId: z.ZodString;
         dataset: z.ZodString;
     }, z.core.$strip>>;
+    publish: z.ZodOptional<z.ZodObject<{
+        auto: z.ZodOptional<z.ZodEnum<{
+            never: "never";
+            always: "always";
+            "full-runs": "full-runs";
+        }>>;
+        tag: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    execution: z.ZodOptional<z.ZodObject<{
+        concurrency: z.ZodOptional<z.ZodNumber>;
+        graderReplications: z.ZodOptional<z.ZodNumber>;
+        gapAnalysis: z.ZodOptional<z.ZodBoolean>;
+        apiUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    output: z.ZodOptional<z.ZodObject<{
+        dir: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    owner: z.ZodOptional<z.ZodObject<{
+        team: z.ZodOptional<z.ZodString>;
+        individual: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    agentic: z.ZodOptional<z.ZodObject<{
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        allowedOrigins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    artifacts: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        dir: z.ZodOptional<z.ZodString>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    taskSource: z.ZodOptional<z.ZodObject<{
+        type: z.ZodOptional<z.ZodEnum<{
+            "content-lake": "content-lake";
+            repo: "repo";
+        }>>;
+        repoTasksPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     triggers: z.ZodOptional<z.ZodObject<{
         pr: z.ZodOptional<z.ZodObject<{
             mode: z.ZodDefault<z.ZodEnum<{

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

@@ -427,12 +427,17 @@ const ScheduleTriggerSchema = TriggerConfigSchema.extend({
 /**
  * Documentation source configuration.
  * Defines which Sanity project holds the documentation being evaluated.
+ *
+ * `studioOrigin` (W0077 Phase 6d) replaces the retired
+ * `--sanity-studio-origin` CLI flag on `ailf run`. The `SANITY_STUDIO_ORIGIN`
+ * env var still wins over this value at resolution time.
  */
 const SourceConfigSchema = z
     .object({
     projectId: z.string().min(1).optional(),
     dataset: z.string().min(1).optional(),
     baseUrl: z.string().url().optional(),
+    studioOrigin: z.string().url().optional(),
 })
     .optional();
 /**
@@ -445,6 +450,121 @@ const ReportStoreConfigSchema = z
     dataset: z.string().min(1),
 })
     .optional();
+/**
+ * Publish policy. Controls when `ailf run` writes a report to the Content
+ * Lake without an explicit `--publish` / `--no-publish` flag.
+ *
+ * - `auto: "always"`    — publish any run with a configured report store
+ * - `auto: "full-runs"` — publish non-debug runs (default)
+ * - `auto: "never"`     — never auto-publish; users must pass --publish
+ *
+ * `tag` is a default value for `--publish-tag` when not passed at the CLI.
+ *
+ * @see docs/design-docs/pipeline-command-surface.md §5.3
+ */
+const PublishConfigSchema = z
+    .object({
+    auto: z.enum(["always", "full-runs", "never"]).optional(),
+    tag: z.string().optional(),
+})
+    .optional();
+/**
+ * Execution-tier configuration. Per-environment values that the four
+ * retired CLI flags used to set: concurrency, grader replications, gap
+ * analysis toggle, and the AILF API URL.
+ *
+ * @see docs/design-docs/pipeline-command-surface.md §5.7 (W0077 Phase 6b)
+ */
+const ExecutionConfigSchema = z
+    .object({
+    concurrency: z.number().int().positive().optional(),
+    graderReplications: z.number().int().positive().optional(),
+    gapAnalysis: z.boolean().optional(),
+    apiUrl: z.string().url().optional(),
+})
+    .optional();
+/**
+ * Task-source configuration (W0077 Phase 6h). Replaces the retired
+ * `--task-source` and `--repo-tasks-path` CLI flags on `ailf run`.
+ *
+ * - `type`           — `content-lake` (default) or `repo`. When `repo`,
+ *                      tasks load from `repoTasksPath` (or
+ *                      `<cwd>/.ailf/tasks/` if unset).
+ * - `repoTasksPath`  — optional explicit path. Resolved relative to the
+ *                      caller's cwd. Required to exist on disk.
+ *
+ * No env-var fallback today; cascade is config-file → built-in default.
+ */
+const TaskSourceConfigSchema = z
+    .object({
+    type: z.enum(["content-lake", "repo"]).optional(),
+    repoTasksPath: z.string().min(1).optional(),
+})
+    .optional();
+/**
+ * Artifact-writer configuration (W0077 Phase 6g). Replaces the retired
+ * `--no-artifacts`, `--artifacts-dir`, and `--artifacts-exclude` CLI flags
+ * on `ailf run`. The `AILF_ARTIFACTS_DIR` env var still wins over
+ * `artifacts.dir` at resolution time. `artifacts.enabled` defaults to
+ * `true` (writers attached); set `false` to disable all writers (mirrors
+ * the legacy `--no-artifacts` semantics).
+ *
+ * Other commands (`ailf runs export`, etc.) keep their `--artifacts-dir`
+ * flag — that's a "read from this directory" override, distinct from the
+ * pipeline's write-side `artifacts.dir`.
+ */
+const ArtifactsConfigSchema = z
+    .object({
+    enabled: z.boolean().optional(),
+    dir: z.string().min(1).optional(),
+    exclude: z.array(z.string().min(1)).optional(),
+})
+    .optional();
+/**
+ * Owner attribution (W0077 Phase 6f). Replaces the retired `--owner-team`
+ * and `--owner-individual` CLI flags. Both feed the D0037 caller envelope
+ * that surfaces in remote-mode runs. Env vars `AILF_OWNER_TEAM` and
+ * `AILF_OWNER_INDIVIDUAL` still win over these values at resolution time.
+ */
+const OwnerConfigSchema = z
+    .object({
+    team: z.string().min(1).optional(),
+    individual: z.string().min(1).optional(),
+})
+    .optional();
+/**
+ * Agentic-mode configuration (W0077 Phase 6f). Replaces the retired
+ * `--header` and `--allowed-origin` CLI flags. `headers` is a key/value
+ * object (mirrors `DOC_HEADERS` env-var JSON shape); `allowedOrigins` is a
+ * list of origin globs. The `DOC_HEADERS` and `DOC_ALLOWED_ORIGIN(S)` env
+ * vars still apply downstream as additive merges.
+ */
+const AgenticConfigSchema = z
+    .object({
+    headers: z.record(z.string(), z.string()).optional(),
+    allowedOrigins: z.array(z.string().min(1)).optional(),
+})
+    .optional();
+/**
+ * Output-directory configuration. Replaces the retired `--output-dir`
+ * CLI flag on `ailf run`. Resolution order:
+ *
+ *   .ailf/config.yaml `output.dir` > built-in default
+ *
+ * Path is resolved relative to the caller's cwd. The built-in default is
+ * `<cwd>/.ailf/results/latest/` (see resolve-output-dir.ts). Other commands
+ * (`ailf publish`, `ailf pr-comment`, etc.) keep their `--output-dir`
+ * flag — that's a "read from this directory" override, distinct from the
+ * pipeline's write-side `output.dir`.
+ *
+ * @see docs/design-docs/pipeline-command-surface.md §5.7 (W0077 Phase 6c)
+ * @see docs/design-docs/output-dir-routing.md
+ */
+const OutputConfigSchema = z
+    .object({
+    dir: z.string().min(1).optional(),
+})
+    .optional();
 /**
  * Zod schema for .ailf/config.yaml — controls documentation source,
  * report destination, and trigger behavior for evaluations from an
@@ -453,6 +573,13 @@ const ReportStoreConfigSchema = z
 export const RepoConfigSchema = z.object({
     source: SourceConfigSchema,
     reportStore: ReportStoreConfigSchema,
+    publish: PublishConfigSchema,
+    execution: ExecutionConfigSchema,
+    output: OutputConfigSchema,
+    owner: OwnerConfigSchema,
+    agentic: AgenticConfigSchema,
+    artifacts: ArtifactsConfigSchema,
+    taskSource: TaskSourceConfigSchema,
     triggers: z
         .object({
         pr: TriggerConfigSchema.optional(),

package/dist/cli.d.ts

@@ -11,7 +11,7 @@
  * appends Quick Start examples.
  *
  * Usage:
- *   ailf pipeline [flags]       # full evaluation pipeline
+ *   ailf run [flags]            # full evaluation run
  *   ailf compare [flags]        # compare evaluation runs
  *   ailf baseline <cmd> [flags] # baseline management
  *   ailf validate [flags]       # config validation
@@ -24,6 +24,6 @@
  *   --dotenv <path>             # override default .env path
  *
  * Dev mode (without building):
- *   tsx src/cli.ts pipeline --debug
+ *   tsx src/cli.ts run --debug
  */
 export {};

package/dist/cli.js

@@ -13,7 +13,7 @@
  * appends Quick Start examples.
  *
  * Usage:
- *   ailf pipeline [flags]       # full evaluation pipeline
+ *   ailf run [flags]            # full evaluation run
  *   ailf compare [flags]        # compare evaluation runs
  *   ailf baseline <cmd> [flags] # baseline management
  *   ailf validate [flags]       # config validation
@@ -26,7 +26,7 @@
  *   --dotenv <path>             # override default .env path
  *
  * Dev mode (without building):
- *   tsx src/cli.ts pipeline --debug
+ *   tsx src/cli.ts run --debug
  */
 import { config as dotenvConfig } from "dotenv";
 import { existsSync, readFileSync } from "fs";
@@ -76,22 +76,75 @@ else if (process.argv.includes("--quiet") || process.argv.includes("-q")) {
     process.env.AILF_LOG_LEVEL = "quiet";
 }
 // ---------------------------------------------------------------------------
-// W0052 — hard-error on retired capture flags and env vars.
-// --------------------------------------------------------------------------
-// The legacy collector has been removed. Callers still using
-// --capture / --capture-dir / --no-capture-compress / --no-capture-extras
-// or AILF_CAPTURE* / AILF_LEGACY_COLLECTOR / AILF_UNIFIED_ARTIFACTS must
-// migrate to --artifacts-dir / --no-artifacts / --artifacts-exclude. We
-// print a clear pointer so failures don't bubble up as opaque "unknown
-// option" errors from Commander.
+// Hard-error on retired flags, env vars, and commands with a migration hint.
 // ---------------------------------------------------------------------------
-const RETIRED_FLAGS = [
-    "--capture",
-    "--capture-dir",
-    "--no-capture-compress",
-    "--no-capture-extras",
-    "--capture-exclude",
-];
+// Each entry maps an old identifier to the message shown when it's seen, so
+// failures don't bubble up as opaque "unknown option" errors from Commander.
+// W0052 retired the legacy artifact collector; W0075 retired the --skip-*
+// negation prefix, the --debug-{n,pattern,sample} filter flags, and several
+// top-level report/validator commands that were consolidated into umbrellas.
+// ---------------------------------------------------------------------------
+const RETIRED_CAPTURE_HINT = "   Use --artifacts-dir / --no-artifacts / --artifacts-exclude instead.\n" +
+    "   See docs/guides/cli-guide.md and docs/decisions/D0033-unified-run-anchored-artifact-capture.md.";
+const RETIRED_FLAG_HINTS = {
+    "--capture": RETIRED_CAPTURE_HINT,
+    "--capture-dir": RETIRED_CAPTURE_HINT,
+    "--no-capture-compress": RETIRED_CAPTURE_HINT,
+    "--no-capture-extras": RETIRED_CAPTURE_HINT,
+    "--capture-exclude": RETIRED_CAPTURE_HINT,
+    "--skip-fetch": "   Use --no-fetch instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "--skip-eval": "   Use --no-eval instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "--debug-n": "   Use --filter-first-n instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "--debug-pattern": "   Use --filter-pattern instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "--debug-sample": "   Use --filter-sample instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "--output-format": "   Use --format instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "--artifacts-dry-run": "   Use --no-artifacts-write instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "--readiness": "   Use `ailf report readiness --from-run <path>` instead. See docs/design-docs/pipeline-command-surface.md (W0077).",
+    "--discovery-report": "   Use `ailf report discovery --from-run <path>` instead. See docs/design-docs/pipeline-command-surface.md (W0077).",
+    "--compare-baseline": "   Use `--compare <path>` instead. `--compare` now takes an optional baseline argument. See docs/design-docs/pipeline-command-surface.md (W0077).",
+    "--before": "   Use --before-source instead. The flag was renamed to disambiguate from baseline comparison. See docs/design-docs/pipeline-command-surface.md (W0077).",
+    "--concurrency": "   Set `execution.concurrency` in .ailf/config.yaml instead. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6b).",
+    "--grader-replications": "   Set `execution.graderReplications` in .ailf/config.yaml instead. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6b).",
+    "--no-gap-analysis": "   Set `execution.gapAnalysis: false` in .ailf/config.yaml instead. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6b).",
+    "--api-url": "   Set `execution.apiUrl` in .ailf/config.yaml or use the AILF_API_URL env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6b).",
+    "--report-dataset": "   Set `reportStore.dataset` in .ailf/config.yaml or use the AILF_REPORT_DATASET env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6e).",
+    "--report-project": "   Set `reportStore.projectId` in .ailf/config.yaml or use the AILF_REPORT_PROJECT_ID env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6e).",
+    "--owner-team": "   Set `owner.team` in .ailf/config.yaml or use the AILF_OWNER_TEAM env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6f).",
+    "--owner-individual": "   Set `owner.individual` in .ailf/config.yaml or use the AILF_OWNER_INDIVIDUAL env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6f).",
+    "--header": "   Set `agentic.headers` (key/value object) in .ailf/config.yaml or use the DOC_HEADERS env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6f).",
+    "--allowed-origin": "   Set `agentic.allowedOrigins` (list of globs) in .ailf/config.yaml or use the DOC_ALLOWED_ORIGINS env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6f).",
+    "--task-source": "   Set `taskSource.type` (content-lake | repo) in .ailf/config.yaml instead. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6h).",
+    "--repo-tasks-path": "   Set `taskSource.repoTasksPath` in .ailf/config.yaml instead. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6h).",
+};
+const RETIRED_COMMAND_HINTS = {
+    pipeline: "   Use `ailf run` instead. See docs/design-docs/pipeline-command-surface.md (W0077).",
+    "validate-tasks": "   Use `ailf validate tasks` instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "readiness-report": "   Use `ailf report readiness` instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "chronic-failures": "   Use `ailf report chronic-failures` instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "coverage-audit": "   Use `ailf report coverage` instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "discovery-report": "   Use `ailf report discovery` instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "agent-report": "   Use `ailf report agent` instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "weekly-digest": "   Use `ailf report digest` instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "check-staleness": "   Use `ailf report staleness` instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+};
+/**
+ * Per-subcommand retired-flag hints. Use this for flags that were retired
+ * from one subcommand but still exist on others (e.g. `--output-dir` is
+ * retired from `ailf run` but still present on `ailf publish`,
+ * `ailf pr-comment`, etc.). Keys are subcommand names; values share the
+ * same shape as `RETIRED_FLAG_HINTS`.
+ */
+const RETIRED_FLAG_HINTS_BY_COMMAND = {
+    run: {
+        "--output-dir": "   Set `output.dir` in .ailf/config.yaml instead. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6c).",
+        "--sanity-dataset": "   Set `source.dataset` in .ailf/config.yaml or use the SANITY_DATASET env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6d).",
+        "--sanity-project": "   Set `source.projectId` in .ailf/config.yaml or use the SANITY_PROJECT_ID env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6d).",
+        "--sanity-studio-origin": "   Set `source.studioOrigin` in .ailf/config.yaml or use the SANITY_STUDIO_ORIGIN env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6d).",
+        "--no-artifacts": "   Set `artifacts.enabled: false` in .ailf/config.yaml instead. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6g).",
+        "--artifacts-dir": "   Set `artifacts.dir` in .ailf/config.yaml or use the AILF_ARTIFACTS_DIR env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6g).",
+        "--artifacts-exclude": "   Set `artifacts.exclude` (list of artifact-type names) in .ailf/config.yaml instead. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6g).",
+    },
+};
 const RETIRED_ENV_VARS = [
     "AILF_CAPTURE",
     "AILF_CAPTURE_DIR",
@@ -102,15 +155,45 @@ const RETIRED_ENV_VARS = [
     "AILF_LEGACY_COLLECTOR",
     "AILF_UNIFIED_ARTIFACTS",
 ];
+/**
+ * Identify the subcommand the user invoked — the first non-flag arg after
+ * `ailf` (argv[0]=node, argv[1]=cli.ts). Returns undefined if none.
+ */
+function findInvokedSubcommand() {
+    for (let i = 2; i < process.argv.length; i++) {
+        const arg = process.argv[i];
+        if (!arg.startsWith("-"))
+            return arg;
+    }
+    return undefined;
+}
 function findRetiredFlag() {
+    const subcommand = findInvokedSubcommand();
+    const subcommandHints = subcommand
+        ? RETIRED_FLAG_HINTS_BY_COMMAND[subcommand]
+        : undefined;
     for (const arg of process.argv) {
         const bare = arg.split("=")[0];
-        if (RETIRED_FLAGS.includes(bare)) {
-            return bare;
+        if (subcommandHints && bare in subcommandHints) {
+            return { flag: bare, hint: subcommandHints[bare] };
+        }
+        if (bare in RETIRED_FLAG_HINTS) {
+            return { flag: bare, hint: RETIRED_FLAG_HINTS[bare] };
         }
     }
     return undefined;
 }
+function findRetiredCommand() {
+    // The first non-flag argument after `ailf` (argv[0]=node, argv[1]=cli.ts).
+    for (let i = 2; i < process.argv.length; i++) {
+        const arg = process.argv[i];
+        if (!arg.startsWith("-") && arg in RETIRED_COMMAND_HINTS)
+            return arg;
+        if (!arg.startsWith("-"))
+            return undefined;
+    }
+    return undefined;
+}
 function findRetiredEnv() {
     for (const name of RETIRED_ENV_VARS) {
         if (process.env[name] !== undefined)
@@ -119,14 +202,21 @@ function findRetiredEnv() {
     return undefined;
 }
 const retiredFlag = findRetiredFlag();
+const retiredCommand = findRetiredCommand();
 const retiredEnv = findRetiredEnv();
-if (retiredFlag || retiredEnv) {
-    const source = retiredFlag
-        ? `flag "${retiredFlag}"`
-        : `environment variable "${retiredEnv}"`;
-    console.error(`❌ ${source} was retired in W0052 along with the legacy artifact collector.`);
-    console.error("   Use --artifacts-dir / --no-artifacts / --artifacts-exclude instead.");
-    console.error("   See docs/cli.md and docs/decisions/D0033-unified-run-anchored-artifact-capture.md.");
+if (retiredFlag || retiredCommand || retiredEnv) {
+    if (retiredFlag) {
+        console.error(`❌ flag "${retiredFlag.flag}" was retired.`);
+        console.error(retiredFlag.hint);
+    }
+    else if (retiredCommand) {
+        console.error(`❌ command "${retiredCommand}" was retired.`);
+        console.error(RETIRED_COMMAND_HINTS[retiredCommand]);
+    }
+    else if (retiredEnv) {
+        console.error(`❌ environment variable "${retiredEnv}" was retired in W0052 along with the legacy artifact collector.`);
+        console.error(RETIRED_CAPTURE_HINT);
+    }
     process.exit(2);
 }
 // ---------------------------------------------------------------------------
@@ -180,8 +270,8 @@ program.hook("preAction", async (thisCommand, actionCommand) => {
 // Within each group, commands appear in the order they are added.
 // ---------------------------------------------------------------------------
 // ── Core Workflow ──────────────────────────────────────────────────────
-import { createPipelineCommand } from "./commands/pipeline.js";
-program.addCommand(createPipelineCommand().helpGroup(CommandGroup.CoreWorkflow));
+import { createRunCommand } from "./commands/run.js";
+program.addCommand(createRunCommand().helpGroup(CommandGroup.CoreWorkflow));
 import { createCompareCommand } from "./commands/compare.js";
 program.addCommand(createCompareCommand().helpGroup(CommandGroup.CoreWorkflow));
 import { createBaselineCommand } from "./commands/baseline.js";
@@ -192,29 +282,35 @@ import { createRunsCommand } from "./commands/runs.js";
 program.addCommand(createRunsCommand().helpGroup(CommandGroup.CoreWorkflow));
 // ── Analysis & Reports ────────────────────────────────────────────────
 import { createReadinessReportCommand } from "./commands/readiness-report.js";
-program.addCommand(createReadinessReportCommand().helpGroup(CommandGroup.AnalysisReports));
 import { createChronicFailuresCommand } from "./commands/chronic-failures.js";
-program.addCommand(createChronicFailuresCommand().helpGroup(CommandGroup.AnalysisReports));
 import { createCoverageAuditCommand } from "./commands/coverage-audit.js";
-program.addCommand(createCoverageAuditCommand().helpGroup(CommandGroup.AnalysisReports));
 import { createDiscoveryReportCommand } from "./commands/discovery-report.js";
-program.addCommand(createDiscoveryReportCommand().helpGroup(CommandGroup.AnalysisReports));
 import { createAgentReportCommand } from "./commands/agent-report.js";
-program.addCommand(createAgentReportCommand().helpGroup(CommandGroup.AnalysisReports));
 import { createWeeklyDigestCommand } from "./commands/weekly-digest.js";
-program.addCommand(createWeeklyDigestCommand().helpGroup(CommandGroup.AnalysisReports));
 import { createCheckStalenessCommand } from "./commands/check-staleness.js";
-program.addCommand(createCheckStalenessCommand().helpGroup(CommandGroup.AnalysisReports));
+const reportCommand = new Command("report")
+    .description("Generate analysis and reporting outputs from evaluation runs")
+    .addCommand(createReadinessReportCommand())
+    .addCommand(createChronicFailuresCommand())
+    .addCommand(createCoverageAuditCommand())
+    .addCommand(createDiscoveryReportCommand())
+    .addCommand(createAgentReportCommand())
+    .addCommand(createWeeklyDigestCommand())
+    .addCommand(createCheckStalenessCommand());
+program.addCommand(reportCommand.helpGroup(CommandGroup.AnalysisReports));
 // ── Grader Reliability ────────────────────────────────────────────────
 import { createGraderCommand } from "./commands/grader/index.js";
 program.addCommand(createGraderCommand().helpGroup(CommandGroup.GraderReliability));
 // ── Setup & Configuration ─────────────────────────────────────────────
 import { createInitCommand } from "./commands/init.js";
 program.addCommand(createInitCommand().helpGroup(CommandGroup.SetupConfig));
-import { createValidateCommand } from "./commands/validate.js";
-program.addCommand(createValidateCommand().helpGroup(CommandGroup.SetupConfig));
+import { createValidateConfigCommand } from "./commands/validate.js";
 import { createValidateTasksCommand } from "./commands/validate-tasks.js";
-program.addCommand(createValidateTasksCommand().helpGroup(CommandGroup.SetupConfig));
+const validateCommand = new Command("validate")
+    .description("Validate AILF configuration and task files")
+    .addCommand(createValidateConfigCommand())
+    .addCommand(createValidateTasksCommand());
+program.addCommand(validateCommand.helpGroup(CommandGroup.SetupConfig));
 import { createFetchDocsCommand } from "./commands/fetch-docs.js";
 program.addCommand(createFetchDocsCommand().helpGroup(CommandGroup.SetupConfig));
 import { createCacheCommand } from "./commands/cache.js";

package/dist/commands/agent-report.js

@@ -6,7 +6,7 @@ import { dirname, join } from "path";
 import { Command } from "commander";
 import { analyzeResults } from "../pipeline/agent-behavior-report.js";
 export function createAgentReportCommand() {
-    return new Command("agent-report")
+    return new Command("agent")
         .description("Generate an agent behavior observation report from eval results")
         .argument("[results-path]", "Path to eval-results.json (default: results/latest/eval-results.json)")
         .action(async (resultsPath) => {

package/dist/commands/calculate-scores.js

@@ -30,8 +30,6 @@ export function createCalculateScoresCommand() {
                 skipEval: true,
                 compareEnabled: false,
                 gapAnalysisEnabled: false,
-                readinessEnabled: false,
-                discoveryReportEnabled: false,
                 publishEnabled: false,
                 noCache: true,
                 noRemoteCache: true,

package/dist/commands/check-staleness.js

@@ -12,7 +12,7 @@
  */
 import { Command } from "commander";
 export function createCheckStalenessCommand() {
-    return new Command("check-staleness")
+    return new Command("staleness")
         .description("Exit 1 if no evaluation report has been produced within the max-age window")
         .option("--max-age <days>", "Max age in days before reports are considered stale", (v) => Number.parseInt(v, 10), 3)
         .action(async (opts) => {

package/dist/commands/chronic-failures.js

@@ -11,15 +11,15 @@ export function createChronicFailuresCommand() {
     return new Command("chronic-failures")
         .description("Identify tasks that error in >50% of recent evaluation runs")
         .option("--lookback <n>", "Number of recent reports to analyze", (v) => parseInt(v, 10), 10)
-        .option("--threshold <n>", "Error rate threshold (0-1) for chronic classification", (v) => parseFloat(v), 0.5)
-        .option("--json", "Output raw JSON", false)
+        .option("--error-rate <n>", "Error rate threshold (0-1) for chronic classification", (v) => parseFloat(v), 0.5)
+        .option("-f, --format <fmt>", "Output format: console or json", "console")
         .action(async (opts) => {
         const reportStore = new ReportStore();
         const report = await detectChronicFailures(reportStore, {
             lookback: opts.lookback,
-            threshold: opts.threshold,
+            threshold: opts.errorRate,
         });
-        if (opts.json) {
+        if (opts.format === "json") {
             console.log(JSON.stringify(report, null, 2));
         }
         else {

package/dist/commands/coverage-audit.js

@@ -13,10 +13,9 @@ import { createSanityLiteracyPreset } from "../pipeline/compiler/presets/index.j
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(__dirname, "..", "..");
 export function createCoverageAuditCommand() {
-    return new Command("coverage-audit")
+    return new Command("coverage")
         .description("Run documentation coverage audit against feature registry")
-        .option("--format <fmt>", "Output format: table, md, markdown")
-        .option("--json", "Output raw JSON", false)
+        .option("-f, --format <fmt>", "Output format: table, md, markdown, json", "table")
         .action(async (opts) => {
         // Build a registry with mode base + preset so coverage audit works
         // even when config/features.ts is empty (preset is source of truth).
@@ -28,17 +27,17 @@ export function createCoverageAuditCommand() {
             console.error("❌ Coverage audit failed. Ensure config/features.yaml exists and is valid.");
             process.exit(1);
         }
-        if (opts.json) {
+        const isMarkdown = opts.format === "md" || opts.format === "markdown";
+        if (opts.format === "json") {
             console.log(JSON.stringify(report, null, 2));
         }
-        else if (opts.format === "md" || opts.format === "markdown") {
+        else if (isMarkdown) {
             console.log(formatCoverageMarkdown(report));
         }
         else {
             console.log(formatCoverageConsole(report));
         }
-        // Print document utilization stats for non-JSON console output
-        if (!opts.json && opts.format !== "md" && opts.format !== "markdown") {
+        if (opts.format !== "json" && !isMarkdown) {
             const docStats = countReferencedDocs(ROOT);
             console.log("DOCUMENT UTILIZATION:");
             console.log(`  ${docStats.total} unique document slugs referenced across evaluation tasks`);