patchwork-os 0.2.0-beta.9.canary.93 → 1.1.0-beta.1

package/dist/recipes/validation.js

@@ -5,6 +5,68 @@ import { defaultDeprecationWarn, normalizeRecipeForRuntime, } from "./migrations
 import { RECIPE_NAME_RE, RECIPE_VAR_NAME_RE, RESERVED_VAR_NAMES, } from "./names.js";
 import { generateSchemaSet } from "./schemaGenerator.js";
 import { listToolOutputContextKeys } from "./toolRegistry.js";
+/** Driver ids a `downshift` candidate may name (mirrors the JSON-schema enum). */
+const DOWNSHIFT_KNOWN_DRIVERS = new Set([
+    "claude",
+    "claude-code",
+    "api",
+    "openai",
+    "grok",
+    "gemini",
+    "anthropic",
+    "local",
+]);
+/**
+ * Validate an ordered route-candidate list (`downshift` / `escalate`): an array
+ * of `{driver?, model?}` where each entry sets at least one field and any
+ * `driver` is dispatch-known. Shared by both routing fields so they stay in
+ * lockstep. Codes are field-prefixed (`downshift-type`, `escalate-type`, …).
+ * (quality-aware-escalation)
+ */
+function validateRouteCandidateList(field, value, stepIndex, issues) {
+    if (value === undefined)
+        return;
+    const base = `steps.${stepIndex}.agent.${field}`;
+    if (!Array.isArray(value)) {
+        issues.push({
+            level: "error",
+            message: `Step ${stepIndex + 1}: '${field}' must be an array of {driver?, model?} candidates`,
+            code: `${field}-type`,
+            path: base,
+        });
+        return;
+    }
+    value.forEach((entry, di) => {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            issues.push({
+                level: "error",
+                message: `Step ${stepIndex + 1}: ${field}[${di}] must be an object with 'driver' and/or 'model'`,
+                code: `${field}-entry-type`,
+                path: `${base}.${di}`,
+            });
+            return;
+        }
+        const e = entry;
+        const hasDriver = typeof e.driver === "string";
+        const hasModel = typeof e.model === "string";
+        if (!hasDriver && !hasModel) {
+            issues.push({
+                level: "error",
+                message: `Step ${stepIndex + 1}: ${field}[${di}] must set at least one of 'driver' or 'model'`,
+                code: `${field}-entry-empty`,
+                path: `${base}.${di}`,
+            });
+        }
+        if (hasDriver && !DOWNSHIFT_KNOWN_DRIVERS.has(e.driver)) {
+            issues.push({
+                level: "error",
+                message: `Step ${stepIndex + 1}: ${field}[${di}].driver '${String(e.driver)}' is not a known driver`,
+                code: `${field}-driver-enum`,
+                path: `${base}.${di}.driver`,
+            });
+        }
+    });
+}
 export function validateRecipeDefinition(recipe) {
     const issues = [];
     const normalizedRecipe = normalizeRecipeForValidation(recipe);
@@ -13,6 +75,17 @@ export function validateRecipeDefinition(recipe) {
     }
     else {
         const r = normalizedRecipe;
+        // Root-level `vars:` is silently dropped at runtime — the runner reads
+        // only `trigger.vars` / `trigger.inputs` (PR#259 trap). Warn so the
+        // author moves it under `trigger:` instead of debugging empty {{vars}}.
+        if (r.vars !== undefined) {
+            issues.push({
+                level: "warning",
+                message: "Top-level 'vars' is ignored at runtime — only 'trigger.vars' / 'trigger.inputs' are read. Move declared variables under 'trigger:'.",
+                code: "root-vars-ignored",
+                path: "vars",
+            });
+        }
         if (!r.name || typeof r.name !== "string") {
             issues.push({
                 level: "error",
@@ -69,14 +142,16 @@ export function validateRecipeDefinition(recipe) {
                 // src/recipes/scheduler.ts:parseSchedule.
                 const at = trigger.at.trim();
                 const isInterval = /^@every\s+[1-9]\d*\s*(ms|s|m|h)$/i.test(at);
-                const isCron5 = /^\S+\s+\S+\s+\S+\s+\S+\s+\S+$/.test(at);
-                if (!isInterval && !isCron5) {
+                // Accept 5-field and 6-field cron (M24: node-cron supports 6 fields
+                // with a seconds column; reject only if fewer than 5 fields).
+                const isCronExpr = /^\S+(?:\s+\S+){4,5}$/.test(at);
+                if (!isInterval && !isCronExpr) {
                     issues.push({
                         level: "error",
-                        message: `trigger.at "${at}" is not a valid schedule — expected 5-field cron (e.g. "0 9 * * 1-5") or "@every Ns|Nm|Nh"`,
+                        message: `trigger.at "${at}" is not a valid schedule — expected 5- or 6-field cron (e.g. "0 9 * * 1-5") or "@every Ns|Nm|Nh"`,
                     });
                 }
-                else if (isCron5 && !cron.validate(at)) {
+                else if (isCronExpr && !cron.validate(at)) {
                     // node-cron catches range/step typos a field-count check
                     // misses — e.g. "0 25 * * *", "* / 5 * * *".
                     issues.push({
@@ -88,6 +163,35 @@ export function validateRecipeDefinition(recipe) {
             validateTriggerVarsList(trigger.vars, "vars", issues);
             validateTriggerVarsList(trigger.inputs, "inputs", issues);
         }
+        // M26: parallel:{each} map-reduce is not implemented in chained recipes.
+        // Check raw recipe.steps (before flattening) so the parallel wrapper is visible.
+        const rawRecipe = recipe && typeof recipe === "object" && !Array.isArray(recipe)
+            ? recipe
+            : null;
+        const isChainedRecipe = rawRecipe?.trigger &&
+            typeof rawRecipe.trigger === "object" &&
+            !Array.isArray(rawRecipe.trigger) &&
+            rawRecipe.trigger.type === "chained";
+        if (isChainedRecipe && Array.isArray(rawRecipe?.steps)) {
+            const rawSteps = rawRecipe.steps;
+            for (let i = 0; i < rawSteps.length; i++) {
+                const rawStep = rawSteps[i];
+                if (rawStep && typeof rawStep === "object" && !Array.isArray(rawStep)) {
+                    const rs = rawStep;
+                    if (rs.parallel &&
+                        typeof rs.parallel === "object" &&
+                        !Array.isArray(rs.parallel) &&
+                        "each" in rs.parallel) {
+                        issues.push({
+                            level: "error",
+                            message: `Step ${i + 1}: parallel:{each} map-reduce is not supported in chained recipes. Use the \`fan_out\` tool step for tool-only loops.`,
+                            path: `steps.${i}.parallel`,
+                            code: "chained-parallel-each-unsupported",
+                        });
+                    }
+                }
+            }
+        }
         if (!Array.isArray(r.steps) || r.steps.length === 0) {
             issues.push({
                 level: "error",
@@ -95,8 +199,25 @@ export function validateRecipeDefinition(recipe) {
             });
         }
         else {
+            const seenStepIds = new Set();
             for (let i = 0; i < r.steps.length; i++) {
                 const step = r.steps[i];
+                // Duplicate step ids break dependency wiring (`awaits:`, `into:`
+                // overwrite, output keying) — the runner keys outputs by id and a
+                // second step with the same id silently clobbers the first. Reject.
+                if (typeof step.id === "string") {
+                    if (seenStepIds.has(step.id)) {
+                        issues.push({
+                            level: "error",
+                            message: `Step ${i + 1}: duplicate step id '${step.id}' — step ids must be unique`,
+                            code: "duplicate-step-id",
+                            path: `steps.${i}.id`,
+                        });
+                    }
+                    else {
+                        seenStepIds.add(step.id);
+                    }
+                }
                 const hasTool = typeof step.tool === "string";
                 const hasAgent = !!step.agent;
                 const hasNestedRecipe = typeof step.recipe === "string" || typeof step.chain === "string";
@@ -106,6 +227,20 @@ export function validateRecipeDefinition(recipe) {
                         message: `Step ${i + 1}: Must have 'tool', 'agent', 'recipe', or 'chain' field`,
                     });
                 }
+                // M31: step-level retry: -1 silently skips tool steps (loop body
+                // iterates 0 times when retryCount < 0). Reject at lint time.
+                if (step.retry !== undefined) {
+                    const retryVal = step.retry;
+                    if (typeof retryVal !== "number" ||
+                        !Number.isInteger(retryVal) ||
+                        retryVal < 0) {
+                        issues.push({
+                            level: "error",
+                            message: `Step ${i + 1}: retry must be a non-negative integer (got ${JSON.stringify(retryVal)})`,
+                            path: `steps.${i}.retry`,
+                        });
+                    }
+                }
                 if (step.agent && typeof step.agent === "object") {
                     const agent = step.agent;
                     if (!agent.prompt || typeof agent.prompt !== "string") {
@@ -114,10 +249,121 @@ export function validateRecipeDefinition(recipe) {
                             message: `Step ${i + 1}: Agent step missing 'prompt'`,
                         });
                     }
+                    // Tier-1 #8 (audit 2026-06-22): the judge→refine loop is implemented
+                    // ONLY in the flat runner. A chained recipe (trigger.type:"chained")
+                    // treats a `kind: judge` step as a plain agent step and silently
+                    // ignores `max_revisions` — the refinement never runs. Reject at lint
+                    // time so users aren't misled into thinking it works here.
+                    if (isChainedRecipe) {
+                        const mrChained = agent.max_revisions;
+                        const judgeRequested = agent.kind === "judge" ||
+                            (typeof mrChained === "number" && mrChained > 0);
+                        if (judgeRequested) {
+                            issues.push({
+                                level: "error",
+                                message: `Step ${i + 1}: judge→refine (kind: judge / max_revisions) is not supported in chained recipes (trigger.type: chained) — it only runs in the flat runner and would silently no-op here.`,
+                                code: "chained-judge-unsupported",
+                                path: `steps.${i}.agent`,
+                            });
+                        }
+                    }
+                    // `driver: claude|anthropic` routes to the Anthropic API (needs
+                    // ANTHROPIC_API_KEY), NOT the Claude Code subscription — a common
+                    // trap. Warn at lint time when the key is absent so the step
+                    // doesn't silently no-op ("[agent step skipped: ANTHROPIC_API_KEY
+                    // not set]") at run time. Use `driver: subprocess`/`claude-code`
+                    // for the subscription path.
+                    if ((agent.driver === "claude" || agent.driver === "anthropic") &&
+                        !process.env.ANTHROPIC_API_KEY) {
+                        issues.push({
+                            level: "warning",
+                            message: `Step ${i + 1}: driver '${String(agent.driver)}' uses the Anthropic API but ANTHROPIC_API_KEY is not set — the step will be skipped at run time. Set ANTHROPIC_API_KEY, or use 'driver: subprocess' for the Claude Code subscription.`,
+                            code: "driver-api-key-required",
+                            path: `steps.${i}.agent.driver`,
+                        });
+                    }
+                    // OPT-IN judge→refine loop fields. Both `max_revisions` and
+                    // `on_exhausted` are meaningless without a `kind: "judge"` step
+                    // that points at an upstream step via `reviews:` — a refine loop
+                    // needs an agent output to re-run. Flag misuse as an error so
+                    // `recipe lint` / `doctor` catch it before any run.
+                    const hasRefineField = agent.max_revisions !== undefined ||
+                        agent.on_exhausted !== undefined;
+                    if (hasRefineField) {
+                        if (agent.kind !== "judge") {
+                            issues.push({
+                                level: "error",
+                                message: `Step ${i + 1}: 'max_revisions'/'on_exhausted' require 'kind: judge' (the judge→refine loop only applies to judge steps)`,
+                                code: "refine-requires-judge",
+                                path: `steps.${i}.agent`,
+                            });
+                        }
+                        else if (typeof agent.reviews !== "string" ||
+                            agent.reviews.length === 0) {
+                            issues.push({
+                                level: "error",
+                                message: `Step ${i + 1}: 'max_revisions'/'on_exhausted' require 'reviews' to be set (the loop re-runs the reviewed step)`,
+                                code: "refine-requires-reviews",
+                                path: `steps.${i}.agent`,
+                            });
+                        }
+                    }
+                    if (agent.max_revisions !== undefined) {
+                        const mr = agent.max_revisions;
+                        if (typeof mr !== "number" || !Number.isInteger(mr) || mr < 0) {
+                            issues.push({
+                                level: "error",
+                                message: `Step ${i + 1}: 'max_revisions' must be a non-negative integer (got ${JSON.stringify(mr)})`,
+                                code: "refine-max-revisions-invalid",
+                                path: `steps.${i}.agent.max_revisions`,
+                            });
+                        }
+                    }
+                    if (agent.on_exhausted !== undefined &&
+                        agent.on_exhausted !== "halt" &&
+                        agent.on_exhausted !== "proceed") {
+                        issues.push({
+                            level: "error",
+                            message: `Step ${i + 1}: invalid 'on_exhausted' '${String(agent.on_exhausted)}' — must be 'halt' or 'proceed'`,
+                            code: "refine-on-exhausted-enum",
+                            path: `steps.${i}.agent.on_exhausted`,
+                        });
+                    }
+                    // OPT-IN routing fallbacks, both ordered {driver?, model?} lists:
+                    // `downshift` (cost-aware, Phase 4 — go cheaper as budget depletes)
+                    // and `escalate` (quality-aware — go more capable on judge rejection).
+                    validateRouteCandidateList("downshift", agent.downshift, i, issues);
+                    validateRouteCandidateList("escalate", agent.escalate, i, issues);
+                }
+                // Unconditional risk-enum check. `risk` was previously never
+                // validated here (the parser casts it; the JSON-schema enum is
+                // gated behind FLAG_SCHEMA_LINT, which defaults off). A typo like
+                // `risk: "hgh"` silently fell through the compiler's risk bucketer
+                // to `allow` — fail-open. Flag any out-of-enum value as an error so
+                // `recipe lint` / `doctor` catch it before a run. Reads risk from
+                // the top-level step AND the nested agent object (both forms occur).
+                const stepAgent = step.agent && typeof step.agent === "object"
+                    ? step.agent
+                    : undefined;
+                const riskValue = step.risk ?? stepAgent?.risk;
+                if (riskValue !== undefined &&
+                    riskValue !== "low" &&
+                    riskValue !== "medium" &&
+                    riskValue !== "high") {
+                    issues.push({
+                        level: "error",
+                        message: `Step ${i + 1}: invalid risk '${String(riskValue)}' — must be one of: low, medium, high`,
+                        code: "risk-enum",
+                        path: `steps.${i}.risk`,
+                    });
                 }
             }
+            validateAwaitsTargets(r, recipe, issues);
+            validateJudgeReviewsTargets(r, issues);
             validateTemplateReferences(r, issues, collectParallelEachKeys(recipe));
         }
+        validateRecipeBudget(r, issues);
+        validateRecipeErrorPolicy(r, issues);
     }
     if (isEnabled(FLAG_SCHEMA_LINT)) {
         issues.push(...validateRecipeSchema(normalizedRecipe));
@@ -136,6 +382,251 @@ export function validateRecipeDefinition(recipe) {
         errors,
     };
 }
+/**
+ * Validate the optional recipe `budget` block. Closes a real gap: before
+ * cost-routing Phase 3 there was NO budget validation, so `tokensMax: -5` or
+ * `tokensMax: "lots"` passed lint silently. A present cap must be a positive
+ * number; `onBreach` must be the halt|warn enum.
+ */
+function validateRecipeBudget(r, issues) {
+    const budget = r.budget;
+    if (budget === undefined)
+        return;
+    if (typeof budget !== "object" || budget === null || Array.isArray(budget)) {
+        issues.push({
+            level: "error",
+            message: "'budget' must be an object",
+            path: "budget",
+            code: "budget-type",
+        });
+        return;
+    }
+    const b = budget;
+    for (const key of ["tokensMax", "usdMax"]) {
+        const value = b[key];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "number" || !(value > 0)) {
+            issues.push({
+                level: "error",
+                message: `budget.${key} must be a positive number`,
+                path: `budget.${key}`,
+                code: "budget-positive",
+            });
+        }
+    }
+    if (b.onBreach !== undefined &&
+        b.onBreach !== "halt" &&
+        b.onBreach !== "warn") {
+        issues.push({
+            level: "error",
+            message: "budget.onBreach must be 'halt' or 'warn'",
+            path: "budget.onBreach",
+            code: "budget-onbreach-enum",
+        });
+    }
+    if (b.estimateUnmeasured !== undefined &&
+        typeof b.estimateUnmeasured !== "boolean") {
+        issues.push({
+            level: "error",
+            message: "budget.estimateUnmeasured must be a boolean",
+            path: "budget.estimateUnmeasured",
+            code: "budget-estimate-type",
+        });
+    }
+}
+/**
+ * Validate the optional recipe `on_error` policy block. Audit 2026-06-03
+ * (MEDIUM): the hand-rolled lint never checked it, so a typo'd `fallback`
+ * enum, a non-numeric `retry`, or a negative `retry` (which the runtime
+ * now clamps — see chainedRunner.withRetry, audit HIGH #8) passed lint
+ * silently. Mirrors validateRecipeBudget. `retry` is a non-negative integer;
+ * `retryDelay` a non-negative number (ms); `fallback` the documented enum.
+ */
+function validateRecipeErrorPolicy(r, issues) {
+    const onError = r.on_error;
+    if (onError === undefined)
+        return;
+    if (typeof onError !== "object" ||
+        onError === null ||
+        Array.isArray(onError)) {
+        issues.push({
+            level: "error",
+            message: "'on_error' must be an object",
+            path: "on_error",
+            code: "on-error-type",
+        });
+        return;
+    }
+    const e = onError;
+    if (e.retry !== undefined) {
+        if (typeof e.retry !== "number" ||
+            !Number.isInteger(e.retry) ||
+            e.retry < 0) {
+            issues.push({
+                level: "error",
+                message: "on_error.retry must be a non-negative integer",
+                path: "on_error.retry",
+                code: "on-error-retry",
+            });
+        }
+    }
+    if (e.retryDelay !== undefined) {
+        if (typeof e.retryDelay !== "number" ||
+            !Number.isFinite(e.retryDelay) ||
+            e.retryDelay < 0) {
+            issues.push({
+                level: "error",
+                message: "on_error.retryDelay must be a non-negative number (ms)",
+                path: "on_error.retryDelay",
+                code: "on-error-retrydelay",
+            });
+        }
+    }
+    if (e.fallback !== undefined &&
+        e.fallback !== "log_only" &&
+        e.fallback !== "abort" &&
+        e.fallback !== "deliver_original") {
+        issues.push({
+            level: "error",
+            message: "on_error.fallback must be 'log_only', 'abort', or 'deliver_original'",
+            path: "on_error.fallback",
+            code: "on-error-fallback-enum",
+        });
+    }
+}
+/**
+ * Validate step `awaits:` targets against the set of declared step ids.
+ *
+ * An `awaits:` target that matches no real step is a recipe-authoring bug
+ * that the runtime can't recover from: the cycle-detection DFS skips the
+ * phantom edge (so `hasCycles` stays false), but Kahn's algorithm counts it
+ * in the awaiting step's in-degree and never decrements it — so the
+ * awaiting step AND all its transitive dependents silently drop out of the
+ * topological order, never run, and the run STILL reports success. Flag it
+ * statically so `recipe lint` / `doctor` catch it before any run.
+ *
+ * Known-id collection runs over BOTH:
+ *   - the NORMALIZED recipe (`normalizedRecipe.steps`) — `awaits:` clauses
+ *     live here, and `flattenValidationSteps` has already hoisted parallel
+ *     children to top level (so child ids are present), AND
+ *   - the RAW recipe (`rawRecipe.steps`) — still carries the `parallel:`
+ *     CONTAINER ids that flattening drops.
+ *
+ * The union matters because `awaits: [<parallel-group-id>]` is VALID at
+ * runtime: `chainedRunner.expandParallelSteps` rewrites a group-id await to
+ * the expanded child ids. Collecting from the raw steps keeps those
+ * container ids in `knownIds` so a legitimate group-await isn't flagged,
+ * while a genuine typo (`gather2`) — present in neither list — still errors.
+ */
+/**
+ * Cross-check each judge step's `reviews:` target against the set of resolvable
+ * step keys. The runtime resolves `reviews` against ctx (keyed by `into`) first,
+ * then falls back to step `id` — a reference matching neither silently reviews
+ * nothing. Flag as error when a refine loop is configured (max_revisions set),
+ * warning otherwise (the judge still runs; it just has no prior output to review).
+ */
+function validateJudgeReviewsTargets(r, issues) {
+    const steps = Array.isArray(r.steps)
+        ? r.steps
+        : [];
+    // Collect all resolvable keys: every step's `into` value + every step `id`.
+    const resolvable = new Set();
+    for (const step of steps) {
+        const agent = step.agent && typeof step.agent === "object"
+            ? step.agent
+            : undefined;
+        if (typeof agent?.into === "string")
+            resolvable.add(agent.into);
+        if (typeof step.id === "string")
+            resolvable.add(step.id);
+    }
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        const agent = step.agent && typeof step.agent === "object"
+            ? step.agent
+            : undefined;
+        if (!agent || agent.kind !== "judge")
+            continue;
+        const reviews = agent.reviews;
+        if (typeof reviews !== "string" || reviews.length === 0)
+            continue;
+        if (resolvable.has(reviews))
+            continue;
+        const hasRefineLoop = agent.max_revisions !== undefined || agent.on_exhausted !== undefined;
+        issues.push({
+            level: hasRefineLoop ? "error" : "warning",
+            message: `Step ${i + 1}: 'reviews: ${reviews}' does not match any step into key or step id — the judge would review nothing at run time`,
+            code: "judge-reviews-unresolved",
+            path: `steps.${i}.agent.reviews`,
+        });
+    }
+}
+function validateAwaitsTargets(normalizedRecipe, rawRecipe, issues) {
+    const steps = Array.isArray(normalizedRecipe.steps)
+        ? normalizedRecipe.steps
+        : [];
+    if (steps.length === 0)
+        return;
+    const knownIds = new Set();
+    const collectIds = (list) => {
+        for (const step of list) {
+            if (!step || typeof step !== "object")
+                continue;
+            if (typeof step.id === "string")
+                knownIds.add(step.id);
+            if (Array.isArray(step.parallel)) {
+                collectIds(step.parallel);
+            }
+            else if (step.parallel &&
+                typeof step.parallel === "object" &&
+                Array.isArray(step.parallel.steps)) {
+                collectIds(step.parallel.steps);
+            }
+        }
+    };
+    // Collect from the flattened (normalized) list first — child ids + any
+    // top-level ids.
+    collectIds(steps);
+    // Then collect from the RAW recipe steps so parallel-group CONTAINER ids
+    // (which `flattenValidationSteps` strips) are recognised as valid await
+    // targets. `collectIds` recurses into `parallel:` arrays / map-reduce
+    // `{steps}` blocks, picking up both the container id and its children.
+    if (rawRecipe &&
+        typeof rawRecipe === "object" &&
+        !Array.isArray(rawRecipe) &&
+        Array.isArray(rawRecipe.steps)) {
+        collectIds(rawRecipe.steps);
+    }
+    const checkAwaits = (list, label) => {
+        for (let i = 0; i < list.length; i++) {
+            const step = list[i];
+            if (!step || typeof step !== "object")
+                continue;
+            if (Array.isArray(step.awaits)) {
+                for (const target of step.awaits) {
+                    if (typeof target === "string" && !knownIds.has(target)) {
+                        issues.push({
+                            level: "error",
+                            message: `${label(i)}: awaits unknown step '${target}' — no step with that id exists. The step (and everything depending on it) would silently never run.`,
+                            code: "unknown-awaits-target",
+                            path: `steps.${i}.awaits`,
+                        });
+                    }
+                }
+            }
+            if (Array.isArray(step.parallel)) {
+                checkAwaits(step.parallel, (j) => `${label(i)}.parallel[${j}]`);
+            }
+            else if (step.parallel &&
+                typeof step.parallel === "object" &&
+                Array.isArray(step.parallel.steps)) {
+                checkAwaits(step.parallel.steps, (j) => `${label(i)}.parallel.steps[${j}]`);
+            }
+        }
+    };
+    checkAwaits(steps, (i) => `Step ${i + 1}`);
+}
 /**
  * Validate `trigger.vars` / `trigger.inputs` array entries. Catches names
  * the runtime template engine can't resolve as `{{var}}` (e.g. spaces,
@@ -271,7 +762,17 @@ function flattenValidationStep(step) {
             if (otherwiseStep &&
                 typeof otherwiseStep === "object" &&
                 !Array.isArray(otherwiseStep)) {
+                // Validate the `otherwise` block.
                 branchSteps.push(...flattenValidationStep(otherwiseStep));
+                // Also validate the co-located conditional step fields (if any) — strip
+                // `otherwise` so the validator sees only the branch-step shape.
+                // Only do this when the entry has keys beyond `otherwise`; a standalone
+                // `{ otherwise: {...} }` entry has nothing else to validate and passing
+                // an empty object `{}` to the schema validator produces bogus errors.
+                const { otherwise: _omit, ...branchWithoutOtherwise } = branchRecord;
+                if (Object.keys(branchWithoutOtherwise).length > 0) {
+                    branchSteps.push(...flattenValidationStep(branchWithoutOtherwise));
+                }
                 continue;
             }
             branchSteps.push(...flattenValidationStep(branchRecord));
@@ -395,15 +896,29 @@ function collectParallelEachKeys(recipe) {
     if (!recipe || typeof recipe !== "object" || Array.isArray(recipe))
         return keys;
     const steps = recipe.steps;
+    collectParallelEachKeysFromSteps(steps, keys);
+    return keys;
+}
+/**
+ * Walk a steps array, collecting parallel-each loop variable keys. Recurses
+ * into `parallel: [...]` group arrays so a nested map-reduce step inside a
+ * parallel group still contributes its loop variable (`as`) — otherwise
+ * `{{item}}` references in those child steps were flagged as unknown template
+ * references, blocking valid recipes (audit 2026-06-10 recipe-validation-4).
+ */
+function collectParallelEachKeysFromSteps(steps, keys) {
     if (!Array.isArray(steps))
-        return keys;
+        return;
     for (const step of steps) {
         if (!step || typeof step !== "object" || Array.isArray(step))
             continue;
         const s = step;
-        if (s.parallel &&
-            typeof s.parallel === "object" &&
-            !Array.isArray(s.parallel)) {
+        if (Array.isArray(s.parallel)) {
+            // Parallel GROUP array — recurse into its child steps.
+            collectParallelEachKeysFromSteps(s.parallel, keys);
+        }
+        else if (s.parallel && typeof s.parallel === "object") {
+            // Parallel map-reduce (each/as) object.
             const par = s.parallel;
             if (typeof par.as === "string")
                 keys.add(par.as);
@@ -411,24 +926,33 @@ function collectParallelEachKeys(recipe) {
                 keys.add(s.id);
                 keys.add(`${s.id}.results`);
             }
+            // Recurse into the map-reduce body so deeper nesting is also covered.
+            collectParallelEachKeysFromSteps(par.steps, keys);
         }
         // Step-level each: "{{items}}" as: item — loop variable
         if (typeof s.as === "string")
             keys.add(s.as);
     }
-    return keys;
 }
 function validateTemplateReferences(recipe, issues, extraParallelKeys) {
     const builtinKeys = new Set([
+        // Date/time tokens injected at runtime: `date`/`time` on the flat path and
+        // `DATE`/`TIME` on the chained dispatch path, plus the YYYY / YYYY-MM /
+        // YYYY-MM-DD / ISO_NOW / HH / MM / SS family — now injected on BOTH paths
+        // (yamlRunner.ts ctx + dispatchRecipe env), so {{YYYY-MM-DD}} etc. render
+        // real values AND pass lint. Keep in sync with the yamlRunner.ts injection
+        // sites. (audit 2026-06-10 recipe-validation-1)
         "date",
         "time",
+        "DATE",
+        "TIME",
         "YYYY",
         "YYYY-MM",
         "YYYY-MM-DD",
         "ISO_NOW",
-        "HH", // time component in datetime format strings
-        "MM", // time component in datetime format strings
-        "SS", // time component in datetime format strings
+        "HH",
+        "MM",
+        "SS",
         "this", // Handlebars loop current-item reference
     ]);
     const availableKeys = new Set(builtinKeys);