@farmslot/agent-runtime 0.2.0 → 0.3.0

package/dist/execution-template/types.d.ts

@@ -0,0 +1,66 @@
+/** Shared Markdown execution-template catalog (ADR-049). */
+export type ExecutionTemplateSourceKind = 'custom' | 'project' | 'workspace' | 'user' | 'package' | 'fallback';
+export type ExecutionTemplateLayout = 'flow-tree' | 'worker-flat';
+export type ExecutionRunMode = 'autonomous' | 'interactive' | 'validation';
+export interface ExecutionTemplateSource {
+    /** Stable source label for catalogs / shadowing (e.g. project:farmslot-farm). */
+    id: string;
+    kind: ExecutionTemplateSourceKind;
+    /** Absolute directory to scan. */
+    root: string;
+    layout: ExecutionTemplateLayout;
+}
+export interface ExecutionTemplateFrontmatter {
+    id?: string;
+    title?: string;
+    flow?: string;
+    version?: string | number;
+    runMode?: ExecutionRunMode;
+    platforms?: string[];
+    labels?: string[];
+    [key: string]: unknown;
+}
+export interface ExecutionTemplateEntry {
+    id: string;
+    title: string;
+    flow: string;
+    version: string;
+    runMode: ExecutionRunMode | null;
+    platforms: string[];
+    labels: string[];
+    path: string;
+    relativePath: string;
+    sourceId: string;
+    sourceKind: ExecutionTemplateSourceKind;
+    /** Present when a higher-precedence source already claimed this id. */
+    shadowedBy?: string;
+    frontmatter: ExecutionTemplateFrontmatter | null;
+    heading: string | null;
+}
+export interface ListExecutionTemplatesOptions {
+    sources: ExecutionTemplateSource[];
+    flow?: string;
+    runMode?: ExecutionRunMode;
+    platform?: string;
+    /** Include shadowed duplicates (default true for list diagnostics). */
+    includeShadowed?: boolean;
+}
+export interface LintIssue {
+    path: string;
+    severity: 'error' | 'warning';
+    message: string;
+}
+export interface LintExecutionTemplatesResult {
+    ok: boolean;
+    issues: LintIssue[];
+    filesChecked: number;
+}
+export interface CreateExecutionTemplateOptions {
+    path: string;
+    flow?: string;
+    runMode?: ExecutionRunMode;
+    platforms?: string[];
+    title?: string;
+    force?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/execution-template/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/execution-template/types.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D,MAAM,MAAM,2BAA2B,GACnC,QAAQ,GACR,SAAS,GACT,WAAW,GACX,MAAM,GACN,SAAS,GACT,UAAU,CAAC;AAEf,MAAM,MAAM,uBAAuB,GAAG,WAAW,GAAG,aAAa,CAAC;AAElE,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,aAAa,GAAG,YAAY,CAAC;AAE3E,MAAM,WAAW,uBAAuB;IACtC,iFAAiF;IACjF,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,2BAA2B,CAAC;IAClC,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,uBAAuB,CAAC;CACjC;AAED,MAAM,WAAW,4BAA4B;IAC3C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACjC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,2BAA2B,CAAC;IACxC,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,4BAA4B,GAAG,IAAI,CAAC;IACjD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB"}

package/dist/execution-template/types.js

@@ -0,0 +1,3 @@
+/** Shared Markdown execution-template catalog (ADR-049). */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/execution-template/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/execution-template/types.ts"],"names":[],"mappings":"AAAA,4DAA4D"}

package/dist/index.d.ts

@@ -4,5 +4,6 @@ export declare const AGENT_RUNTIME_SCRIPT_EXPORTS: {
     readonly workerTerminalContract: "@farmslot/agent-runtime/scripts/worker-terminal-contract.cjs";
     readonly checkTaskArtifactContract: "@farmslot/agent-runtime/scripts/check-task-artifact-contract.mjs";
 };
+export * from './execution-template/index.js';
 export * from './recipe-quality.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAE/D,eAAO,MAAM,4BAA4B;;;;CAI/B,CAAC;AAEX,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAE/D,eAAO,MAAM,4BAA4B;;;;CAI/B,CAAC;AAEX,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -4,5 +4,6 @@ export const AGENT_RUNTIME_SCRIPT_EXPORTS = {
     workerTerminalContract: '@farmslot/agent-runtime/scripts/worker-terminal-contract.cjs',
     checkTaskArtifactContract: '@farmslot/agent-runtime/scripts/check-task-artifact-contract.mjs',
 };
+export * from './execution-template/index.js';
 export * from './recipe-quality.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,qBAAqB,GAAG,yBAAyB,CAAC;AAE/D,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,iBAAiB,EAAE,yDAAyD;IAC5E,sBAAsB,EAAE,8DAA8D;IACtF,yBAAyB,EAAE,kEAAkE;CACrF,CAAC;AAEX,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,qBAAqB,GAAG,yBAAyB,CAAC;AAE/D,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,iBAAiB,EAAE,yDAAyD;IAC5E,sBAAsB,EAAE,8DAA8D;IACtF,yBAAyB,EAAE,kEAAkE;CACrF,CAAC;AAEX,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farmslot/agent-runtime",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,7 +20,7 @@
   },
   "scripts": {
     "typecheck": "yarn workspace @farmslot/protocol build && tsc --noEmit --project tsconfig.json",
-    "test": "node test/mark-checklist-step.test.cjs && node test/checklist-target-sync.test.mjs && node test/package-exports.test.cjs && node test/check-task-artifact-contract.test.cjs && node test/recipe-quality-builder.test.cjs",
+    "test": "node test/mark-checklist-step.test.cjs && node test/checklist-target-sync.test.mjs && node test/package-exports.test.cjs && node test/check-task-artifact-contract.test.cjs && node test/recipe-quality-builder.test.cjs && node ../../scripts/quality/run-tsx-tests.mjs --cwd . --tsconfig tsconfig.json src/execution-template",
     "format": "prettier --write --ignore-path ../../.prettierignore .",
     "format:check": "prettier --check --ignore-path ../../.prettierignore .",
     "lint": "eslint \"src/**/*.ts\"",
@@ -31,12 +31,13 @@
     "prepublishOnly": "node ../../scripts/quality/check-farmslot-package-readiness.mjs --publish --packages @farmslot/agent-runtime"
   },
   "dependencies": {
-    "@farmslot/protocol": "0.8.0"
+    "@farmslot/protocol": "0.11.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "eslint": "^10.3.0",
     "prettier": "^3.8.3",
+    "tsx": "^4.19.0",
     "typescript": "^5.6.0"
   },
   "repository": {
@@ -66,7 +67,8 @@
     "dist/**/*.d.ts.map",
     "dist/**/*.js.map",
     "scripts/**/*.cjs",
-    "scripts/**/*.mjs"
+    "scripts/**/*.mjs",
+    "scripts/execution-template-cli.mjs"
   ],
   "publishConfig": {
     "access": "public"

package/scripts/check-task-artifact-contract.mjs

@@ -1,41 +1,84 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
 const { expandedArtifactsForCommand } = require('./worker-terminal-contract.cjs');
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const workspaceProtocolRoot = path.resolve(packageRoot, '../protocol');
+
+function isMissingWorkspaceProtocolBuild(error, output) {
+  return (
+    error?.code === 'ERR_MODULE_NOT_FOUND' &&
+    path.basename(path.dirname(packageRoot)) === 'packages' &&
+    existsSync(path.join(workspaceProtocolRoot, 'package.json')) &&
+    !existsSync(path.join(workspaceProtocolRoot, output))
+  );
+}
 
 let sharedRecipeQualityValidator = null;
 let sharedRecipeDocumentValidator = null;
-// Mirror @farmslot/protocol recipeProtocolSchemaUrlForVersion: only v1 is a
-// supported schema_version, so do not synthesize URLs for other versions.
-let sharedRecipeSchemaUrlForVersion = (version) =>
-  version === 1 ? 'https://farmslot.io/schemas/recipe-v1.schema.json' : null;
+let sharedRecipeArtifactPackageValidator = null;
+let sharedResolvedRecipeArtifactPath = null;
+// Keep the source-checkout fallback pinned to the canonical Recipe v1 schema.
+const RECIPE_SCHEMA_URL = 'https://farmslot.io/schemas/recipe-v1.schema.json';
 try {
-  ({ isRecipeQualityArtifact: sharedRecipeQualityValidator } =
-    await import('@farmslot/protocol/contracts/recipes'));
+  const qualityProtocol = await import('@farmslot/protocol/contracts/recipes');
+  if (typeof qualityProtocol.isRecipeQualityArtifact !== 'function') {
+    throw new Error('installed @farmslot/protocol does not export isRecipeQualityArtifact');
+  }
+  sharedRecipeQualityValidator = qualityProtocol.isRecipeQualityArtifact;
 } catch (error) {
+  if (!isMissingWorkspaceProtocolBuild(error, 'dist/contracts/recipes.js')) throw error;
   // Source checkouts run this script before @farmslot/protocol has emitted dist/.
   // Keep strict local validation instead of downgrading to the historical loose gate.
   if (process.env.FARMSLOT_DEBUG_AGENT_RUNTIME) {
     console.warn(`[agent-runtime] using local RecipeQualityArtifact fallback: ${error.message}`);
   }
 }
+let recipeProtocol = null;
 try {
-  const recipeProtocol = await import('@farmslot/protocol/recipe');
-  sharedRecipeDocumentValidator = recipeProtocol.validateRecipeDocument;
-  if (typeof recipeProtocol.recipeProtocolSchemaUrlForVersion === 'function') {
-    sharedRecipeSchemaUrlForVersion = recipeProtocol.recipeProtocolSchemaUrlForVersion;
-  }
+  recipeProtocol = await import('@farmslot/protocol/recipe');
 } catch (error) {
-  // Compatibility fail-safe: source checkouts can run before @farmslot/protocol
-  // has emitted dist/. In that degraded state, do not bypass recipe checks;
-  // enforce the minimum executable envelope locally until the shared validator loads.
+  if (!isMissingWorkspaceProtocolBuild(error, 'dist/recipe/index.js')) throw error;
+  // Source checkouts can run before @farmslot/protocol has emitted dist/.
+  // Keep strict local validation until the shared validator is available.
   if (process.env.FARMSLOT_DEBUG_AGENT_RUNTIME) {
     console.warn(`[agent-runtime] using local Recipe v1 fallback: ${error.message}`);
   }
 }
+if (recipeProtocol) {
+  for (const api of [
+    'validateRecipeDocument',
+    'validateRecipeArtifactPackage',
+    'resolvedRecipeArtifactPath',
+  ]) {
+    if (typeof recipeProtocol[api] !== 'function') {
+      throw new Error(`installed @farmslot/protocol does not export ${api}`);
+    }
+  }
+  const compatibilityProbe = recipeProtocol.validateRecipeDocument({
+    $schema: RECIPE_SCHEMA_URL,
+    description: 'Validate the canonical Recipe v1 envelope.',
+    workflow: {
+      entry: 'done',
+      nodes: { done: { action: 'end', status: 'pass' } },
+    },
+  });
+  const incompatibleFinding = compatibilityProbe?.findings?.find(
+    (finding) => finding?.severity === 'error',
+  );
+  if (incompatibleFinding) {
+    throw new Error(
+      `installed @farmslot/protocol rejects canonical Recipe v1 (${incompatibleFinding.code})`,
+    );
+  }
+  sharedRecipeDocumentValidator = recipeProtocol.validateRecipeDocument;
+  sharedRecipeArtifactPackageValidator = recipeProtocol.validateRecipeArtifactPackage;
+  sharedResolvedRecipeArtifactPath = recipeProtocol.resolvedRecipeArtifactPath;
+}
 
 const taskDir = process.argv[2];
 const rawArgs = process.argv.slice(3);
@@ -85,15 +128,34 @@ const allowedOmitKeys = new Set(['file', 'reason']);
 
 function fileExists(rel) {
   try {
-    return statSync(path.join(taskDir, rel)).isFile();
-  } catch {
+    return statSync(resolveTaskArtifactPath(rel)).isFile();
+  } catch (error) {
+    if (!isMissingPathError(error)) throw error;
     return false;
   }
 }
 
 function readText(rel) {
-  const p = path.join(taskDir, rel);
-  return existsSync(p) ? readFileSync(p, 'utf8') : null;
+  try {
+    return readFileSync(resolveTaskArtifactPath(rel), 'utf8');
+  } catch (error) {
+    if (!isMissingPathError(error)) throw error;
+    return null;
+  }
+}
+
+function isMissingPathError(error) {
+  return error && typeof error === 'object' && error.code === 'ENOENT';
+}
+
+function resolveTaskArtifactPath(rel) {
+  const root = realpathSync(taskDir);
+  const candidate = realpathSync(path.resolve(taskDir, rel));
+  const relative = path.relative(root, candidate);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`${rel} resolves outside the task directory`);
+  }
+  return candidate;
 }
 
 function isRecord(value) {
@@ -135,7 +197,7 @@ function isRecipeQualityArtifactFallback(value) {
   if (fields.project != null && typeof fields.project !== 'string') return false;
   if (
     fields.flow_type != null &&
-    !['fix-bug', 'review-pr', 'dev', 'pr-complete', 'merge-main'].includes(fields.flow_type)
+    !['fix-bug', 'review-pr', 'dev', 'pr-complete', 'update-branch'].includes(fields.flow_type)
   )
     return false;
   if (fields.task_type != null && typeof fields.task_type !== 'string') return false;
@@ -246,47 +308,97 @@ function validateRecipeQualityArtifact() {
 }
 
 function validateRecipeDocumentArtifact() {
-  // Mirror the artifact-package contract (protocol/recipe/artifact.ts): a failed run
-  // keeps recipe.json envelope-only and does not re-validate the composition, so a
-  // graceful failure (e.g. a flow cycle) is not rejected here.
-  const summaryText = readText('artifacts/summary.json');
-  let runFailed = false;
-  if (summaryText) {
-    try {
-      runFailed = JSON.parse(summaryText)?.status === 'fail';
-    } catch {
-      // A malformed summary is another check's concern; without a confirmed failure
-      // status, enforce the stricter (passing-run) validation as the safe default.
-      runFailed = false;
+  const authoredRecipe = readJsonArtifact('artifacts/recipe.json', 'recipe.json');
+  if (authoredRecipe === undefined) return;
+  validateRecipeDocumentValue(authoredRecipe, 'recipe.json', { skipRecipeCallResolution: true });
+
+  const packageRoot = 'artifacts/recipe-run';
+  const recipe = readJsonArtifact(`${packageRoot}/recipe.json`, 'recipe-run/recipe.json');
+  if (recipe === undefined) {
+    issues.push('artifacts/recipe-run/recipe.json is missing');
+    return;
+  }
+  if (canonicalJson(authoredRecipe) !== canonicalJson(recipe)) {
+    issues.push('artifacts/recipe-run/recipe.json does not match artifacts/recipe.json');
+  }
+  const manifest = readJsonArtifact(
+    `${packageRoot}/artifact-manifest.json`,
+    'recipe-run/artifact-manifest.json',
+  );
+  const recipeResolution = readJsonArtifact(
+    `${packageRoot}/recipe-resolution.json`,
+    'recipe-run/recipe-resolution.json',
+  );
+  const resolvedRecipes = {};
+  if (isRecord(recipeResolution) && Array.isArray(recipeResolution.dependencies)) {
+    for (const dependency of recipeResolution.dependencies) {
+      if (!isRecord(dependency)) continue;
+      const artifact = resolvedRecipeArtifactPath(dependency.digest);
+      if (!artifact) continue;
+      const document = readJsonArtifact(`${packageRoot}/${artifact}`, `recipe-run/${artifact}`);
+      if (document !== undefined) resolvedRecipes[String(dependency.digest)] = document;
     }
   }
-  if (runFailed) {
-    validateRecipeDocumentArtifactAt('artifacts/recipe.json', 'recipe.json', {
-      skipFlowCallResolution: true,
+  if (sharedRecipeArtifactPackageValidator) {
+    const result = sharedRecipeArtifactPackageValidator({
+      recipe,
+      manifest,
+      recipeResolution,
+      resolvedRecipes,
+      artifactPaths: listArtifactPaths(path.join(taskDir, packageRoot)),
     });
+    for (const finding of result.findings) {
+      if (finding.severity === 'error') {
+        issues.push(`${finding.code} ${finding.path}: ${finding.message}`);
+      }
+    }
     return;
   }
-  // Passing/unknown run: the composition must be proven — recipe.json's call.refs are
-  // proven either by resolved-recipe.json (validated in full, so recipe.json is
-  // envelope-only) or by recipe.json being self-contained (validated in full).
-  const hasResolvedRecipe = fileExists('artifacts/resolved-recipe.json');
-  validateRecipeDocumentArtifactAt('artifacts/recipe.json', 'recipe.json', {
-    skipFlowCallResolution: hasResolvedRecipe,
-    externalCatalogsResolvable: false,
-  });
-  validateRecipeDocumentArtifactAt('artifacts/resolved-recipe.json', 'resolved-recipe.json', {});
+  if (manifest === undefined) issues.push('artifact-manifest.json is missing');
+  if (recipeResolution === undefined) issues.push('recipe-resolution.json is missing');
+  const externalRecipeIds = new Set(
+    isRecord(recipeResolution) && Array.isArray(recipeResolution.dependencies)
+      ? recipeResolution.dependencies
+          .filter(isRecord)
+          .map((dependency) => dependency.ref)
+          .filter((ref) => typeof ref === 'string')
+      : [],
+  );
+  validateRecipeDocumentValue(recipe, 'recipe.json', { externalRecipeIds });
+  for (const [digest, document] of Object.entries(resolvedRecipes)) {
+    validateRecipeDocumentValue(document, `resolved recipe ${digest}`, { externalRecipeIds });
+  }
+}
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (isRecord(value)) {
+    return `{${Object.entries(value)
+      .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+      .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value);
 }
 
-function validateRecipeDocumentArtifactAt(relPath, label, options) {
+function resolvedRecipeArtifactPath(digest) {
+  if (sharedResolvedRecipeArtifactPath) return sharedResolvedRecipeArtifactPath(digest);
+  if (typeof digest !== 'string' || !/^sha256:[a-f0-9]{64}$/u.test(digest)) return undefined;
+  return `resolved-recipes/${digest.slice('sha256:'.length)}.recipe.json`;
+}
+
+function readJsonArtifact(relPath, label) {
   const text = readText(relPath);
-  if (!text) return;
-  let recipe;
+  if (!text) return undefined;
   try {
-    recipe = JSON.parse(text);
+    return JSON.parse(text);
   } catch (error) {
     issues.push(`${label}: invalid JSON: ${error.message}`);
-    return;
+    return undefined;
   }
+}
+
+function validateRecipeDocumentValue(recipe, label, options) {
   if (sharedRecipeDocumentValidator) {
     const result = sharedRecipeDocumentValidator(recipe, options);
     for (const finding of result.findings) {
@@ -300,26 +412,59 @@ function validateRecipeDocumentArtifactAt(relPath, label, options) {
     issues.push(`${label}: expected object`);
     return;
   }
-  if (recipe.schema_version !== 1) {
-    issues.push(`${label}: schema_version must equal 1`);
-  }
-  const expectedSchemaUrl = sharedRecipeSchemaUrlForVersion(recipe.schema_version);
-  if (recipe.$schema != null && recipe.$schema !== expectedSchemaUrl) {
-    issues.push(
-      `${label}: $schema must match schema_version (${expectedSchemaUrl ?? 'unknown schema_version'})`,
-    );
-  }
-  if (!isRecord(recipe.validate) || !isRecord(recipe.validate.workflow)) {
-    issues.push(`${label}: validate.workflow is required`);
+  const allowedRootFields = new Set([
+    '$schema',
+    'title',
+    'description',
+    'paramsSchema',
+    'proofTargets',
+    'workflow',
+  ]);
+  for (const field of Object.keys(recipe)) {
+    if (!allowedRootFields.has(field))
+      issues.push(`${label}: unsupported top-level field ${field}`);
+  }
+  if (recipe.$schema !== RECIPE_SCHEMA_URL) {
+    issues.push(`${label}: $schema must equal ${RECIPE_SCHEMA_URL}`);
+  }
+  if (typeof recipe.description !== 'string' || !recipe.description.trim()) {
+    issues.push(`${label}: description must be a non-empty string`);
+  }
+  if (!isRecord(recipe.workflow)) {
+    issues.push(`${label}: workflow is required`);
     return;
   }
-  const workflow = recipe.validate.workflow;
+  const workflow = recipe.workflow;
   if (typeof workflow.entry !== 'string' || !workflow.entry.trim()) {
-    issues.push(`${label}: validate.workflow.entry must be a non-empty string`);
+    issues.push(`${label}: workflow.entry must be a non-empty string`);
   }
   if (!isRecord(workflow.nodes) || Object.keys(workflow.nodes).length === 0) {
-    issues.push(`${label}: validate.workflow.nodes must be a non-empty object`);
+    issues.push(`${label}: workflow.nodes must be a non-empty object`);
+    return;
   }
+  for (const [nodeId, node] of Object.entries(workflow.nodes)) {
+    if (!isRecord(node) || typeof node.action !== 'string' || !node.action.trim()) {
+      issues.push(`${label}: workflow.nodes.${nodeId}.action must be a non-empty string`);
+      continue;
+    }
+    if (node.action !== 'end' && (typeof node.intent !== 'string' || !node.intent.trim())) {
+      issues.push(`${label}: workflow.nodes.${nodeId}.intent must be a non-empty string`);
+    }
+  }
+}
+
+function listArtifactPaths(root) {
+  if (!existsSync(root)) return [];
+  const paths = [];
+  const visit = (dir, prefix) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) visit(path.join(dir, entry.name), relative);
+      else if (entry.isFile()) paths.push(relative);
+    }
+  };
+  visit(root, '');
+  return paths.sort();
 }
 
 function parseManifest() {