@farmslot/agent-runtime 0.1.0

package/dist/recipe-quality.js

@@ -0,0 +1,178 @@
+import { isRecipeQualityArtifact, RECIPE_QUALITY_ARTIFACT_SOURCES, RECIPE_QUALITY_ARTIFACT_VERSION, RECIPE_QUALITY_DIMENSION_STATUSES, RECIPE_QUALITY_FALLBACK_SOURCES, RECIPE_QUALITY_PROOF_MODES, RECIPE_QUALITY_VERDICTS, } from '@farmslot/protocol';
+const COMPACT_VERDICT_BY_VERDICT = {
+    pass: 'PASS',
+    warn: 'WARN',
+    fail: 'FAIL',
+};
+const CORE_ARTIFACT_KEYS = new Set([
+    'version',
+    'verdict',
+    'compact',
+    'dimensions',
+    'structural_findings',
+    'contextual_findings',
+    'suggested_recipe_delta',
+    'training_fields',
+    'meta',
+]);
+function assertRecipeQualityVerdict(value) {
+    if (!RECIPE_QUALITY_VERDICTS.includes(value)) {
+        throw new TypeError(`verdict must be one of: ${RECIPE_QUALITY_VERDICTS.join(', ')}.`);
+    }
+}
+function assertRecipeQualityProducer(value) {
+    if (!RECIPE_QUALITY_ARTIFACT_SOURCES.includes(value)) {
+        throw new TypeError(`producer must be one of: ${RECIPE_QUALITY_ARTIFACT_SOURCES.join(', ')}.`);
+    }
+}
+function assertStringArray(name, value) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+        throw new TypeError(`${name} must be an array of strings.`);
+    }
+}
+function defaultFallbackUsed(producer, fallbackSource) {
+    return fallbackSource != null || producer.startsWith('fallback:');
+}
+function isPlainRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function assertOptionalPlainRecord(name, value) {
+    if (value != null && !isPlainRecord(value)) {
+        throw new TypeError(`${name} must be a JSON object when provided.`);
+    }
+}
+function assertOptionalBoolean(name, value) {
+    if (value != null && typeof value !== 'boolean') {
+        throw new TypeError(`${name} must be a boolean when provided.`);
+    }
+}
+function assertOptionalArray(name, value) {
+    if (value != null && !Array.isArray(value)) {
+        throw new TypeError(`${name} must be an array when provided.`);
+    }
+}
+function validateTrainingFields(value) {
+    assertOptionalPlainRecord('trainingFields', value);
+    const proofMode = value?.proof_mode;
+    if (proofMode != null && !RECIPE_QUALITY_PROOF_MODES.includes(proofMode)) {
+        throw new TypeError(`trainingFields.proof_mode must be one of: ${RECIPE_QUALITY_PROOF_MODES.join(', ')}.`);
+    }
+}
+function validateDimensions(value) {
+    assertOptionalPlainRecord('dimensions', value);
+    if (!value)
+        return;
+    for (const [name, dimension] of Object.entries(value)) {
+        if (!isPlainRecord(dimension)) {
+            throw new TypeError(`dimensions.${name} must be a JSON object.`);
+        }
+        if (!RECIPE_QUALITY_DIMENSION_STATUSES.includes(dimension.status)) {
+            throw new TypeError(`dimensions.${name}.status must be one of: ${RECIPE_QUALITY_DIMENSION_STATUSES.join(', ')}.`);
+        }
+        if (typeof dimension.reason !== 'string') {
+            throw new TypeError(`dimensions.${name}.reason must be a string.`);
+        }
+        assertStringArray(`dimensions.${name}.evidence`, dimension.evidence);
+    }
+}
+function validateFindings(name, value) {
+    assertOptionalArray(name, value);
+    if (!value)
+        return;
+    for (const [index, finding] of value.entries()) {
+        if (!isPlainRecord(finding)) {
+            throw new TypeError(`${name}.${index} must be a JSON object.`);
+        }
+        if (typeof finding.code !== 'string')
+            throw new TypeError(`${name}.${index}.code must be a string.`);
+        if (typeof finding.message !== 'string')
+            throw new TypeError(`${name}.${index}.message must be a string.`);
+        if (finding.dimension != null && typeof finding.dimension !== 'string') {
+            throw new TypeError(`${name}.${index}.dimension must be a string when provided.`);
+        }
+        if (finding.evidence != null)
+            assertStringArray(`${name}.${index}.evidence`, finding.evidence);
+    }
+}
+function validateExtraKeys(extra) {
+    assertOptionalPlainRecord('extra', extra);
+    if (!extra)
+        return;
+    for (const key of Object.keys(extra)) {
+        if (CORE_ARTIFACT_KEYS.has(key)) {
+            throw new TypeError(`extra.${key} cannot override a RecipeQualityArtifact core field.`);
+        }
+    }
+}
+/**
+ * Builds the canonical `artifacts/recipe-quality.json` payload from the compact
+ * fields agents are expected to know after a recipe-quality pass.
+ */
+export function buildRecipeQualityArtifact(input) {
+    assertRecipeQualityVerdict(input.verdict);
+    assertStringArray('reasons', input.reasons);
+    if (input.reasons.length === 0) {
+        throw new TypeError('reasons must include at least one reason.');
+    }
+    assertStringArray('betterVersionGuidance', input.betterVersionGuidance ?? []);
+    assertStringArray('suggestedRecipeDelta', input.suggestedRecipeDelta ?? []);
+    assertStringArray('sourceSignals', input.sourceSignals ?? ['recipe-quality.json']);
+    validateDimensions(input.dimensions);
+    validateFindings('structuralFindings', input.structuralFindings);
+    validateFindings('contextualFindings', input.contextualFindings);
+    assertOptionalBoolean('fallbackUsed', input.fallbackUsed);
+    assertOptionalBoolean('legacyTask', input.legacyTask);
+    assertOptionalBoolean('artifactRequired', input.artifactRequired);
+    validateTrainingFields(input.trainingFields);
+    validateExtraKeys(input.extra);
+    const producer = input.producer ?? 'worker';
+    assertRecipeQualityProducer(producer);
+    const fallbackSource = input.fallbackSource;
+    if (fallbackSource != null && !RECIPE_QUALITY_FALLBACK_SOURCES.includes(fallbackSource)) {
+        throw new TypeError(`fallbackSource must be one of: ${RECIPE_QUALITY_FALLBACK_SOURCES.join(', ')}.`);
+    }
+    const fallbackUsed = input.fallbackUsed ?? defaultFallbackUsed(producer, fallbackSource);
+    if (fallbackSource != null && !producer.startsWith('fallback:')) {
+        throw new TypeError('fallbackSource requires a fallback producer.');
+    }
+    if (fallbackSource != null && fallbackUsed === false) {
+        throw new TypeError('fallbackUsed cannot be false when fallbackSource is set.');
+    }
+    if (producer.startsWith('fallback:') && fallbackUsed === false) {
+        throw new TypeError('fallbackUsed cannot be false for fallback producers.');
+    }
+    if (!producer.startsWith('fallback:') && fallbackUsed === true) {
+        throw new TypeError('fallbackUsed cannot be true for non-fallback producers.');
+    }
+    const artifact = {
+        ...(input.extra ?? {}),
+        version: RECIPE_QUALITY_ARTIFACT_VERSION,
+        verdict: input.verdict,
+        compact: {
+            verdict: COMPACT_VERDICT_BY_VERDICT[input.verdict],
+            reasons: input.reasons,
+            better_version_guidance: input.betterVersionGuidance ?? [],
+        },
+        dimensions: input.dimensions ?? {},
+        structural_findings: input.structuralFindings ?? [],
+        contextual_findings: input.contextualFindings ?? [],
+        suggested_recipe_delta: input.suggestedRecipeDelta ?? [],
+        training_fields: {
+            proof_mode: 'unknown',
+            ...(input.trainingFields ?? {}),
+        },
+        meta: {
+            producer,
+            fallback_used: fallbackUsed,
+            ...(fallbackSource ? { fallback_source: fallbackSource } : {}),
+            legacy_task: input.legacyTask ?? false,
+            artifact_required: input.artifactRequired ?? true,
+            source_signals: input.sourceSignals ?? ['recipe-quality.json'],
+        },
+    };
+    if (!isRecipeQualityArtifact(artifact)) {
+        throw new TypeError('Built recipe-quality artifact does not satisfy RecipeQualityArtifact.');
+    }
+    return artifact;
+}
+//# sourceMappingURL=recipe-quality.js.map

package/dist/recipe-quality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipe-quality.js","sourceRoot":"","sources":["../src/recipe-quality.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@farmslot/agent-runtime",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "farmslot-agent": "./bin/farmslot-agent.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./scripts/mark-checklist-step.cjs": "./scripts/mark-checklist-step.cjs",
+    "./scripts/worker-terminal-contract.cjs": "./scripts/worker-terminal-contract.cjs",
+    "./scripts/check-task-artifact-contract.mjs": "./scripts/check-task-artifact-contract.mjs"
+  },
+  "scripts": {
+    "typecheck": "yarn workspace @farmslot/protocol build && tsc --noEmit --project tsconfig.json",
+    "test": "node test/mark-checklist-step.test.cjs && node test/package-exports.test.cjs && node test/check-task-artifact-contract.test.cjs && node test/recipe-quality-builder.test.cjs",
+    "format": "prettier --write --ignore-path ../../.prettierignore .",
+    "format:check": "prettier --check --ignore-path ../../.prettierignore .",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "quality": "prettier --check --ignore-path ../../.prettierignore . && eslint \"src/**/*.ts\" && yarn typecheck && yarn build && yarn test",
+    "build": "yarn workspace @farmslot/protocol build && rm -rf dist && tsc --project tsconfig.build.json",
+    "prepack": "cd ../.. && node scripts/quality/check-farmslot-package-readiness.mjs --require-changelog --packages @farmslot/agent-runtime && yarn workspace @farmslot/agent-runtime build",
+    "prepublishOnly": "node ../../scripts/quality/check-farmslot-package-readiness.mjs --publish --packages @farmslot/agent-runtime"
+  },
+  "dependencies": {
+    "@farmslot/protocol": "0.7.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "eslint": "^10.3.0",
+    "prettier": "^3.8.3",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deeeed/farmslot.git",
+    "directory": "packages/agent-runtime"
+  },
+  "bugs": {
+    "url": "https://github.com/deeeed/farmslot/issues"
+  },
+  "license": "MIT",
+  "homepage": "https://farmslot.io/docs/reference/agent-runtime",
+  "keywords": [
+    "farmslot",
+    "agent-runtime",
+    "task-lifecycle",
+    "validation",
+    "agentic-engineering"
+  ],
+  "files": [
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "bin/**/*.mjs",
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/**/*.js.map",
+    "scripts/**/*.cjs",
+    "scripts/**/*.mjs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

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

@@ -0,0 +1,400 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const { expandedArtifactsForCommand } = require('./worker-terminal-contract.cjs');
+
+let sharedRecipeQualityValidator = null;
+try {
+  ({ isRecipeQualityArtifact: sharedRecipeQualityValidator } =
+    await import('@farmslot/protocol/contracts/recipes'));
+} catch (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}`);
+  }
+}
+
+const taskDir = process.argv[2];
+const rawArgs = process.argv.slice(3);
+const flags = new Set();
+let contractPath;
+let terminalCommand;
+for (let i = 0; i < rawArgs.length; i += 1) {
+  const arg = rawArgs[i];
+  if (arg === '--contract') {
+    contractPath = rawArgs[i + 1];
+    i += 1;
+    continue;
+  }
+  if (arg === '--terminal') {
+    terminalCommand = rawArgs[i + 1];
+    i += 1;
+    continue;
+  }
+  flags.add(arg);
+}
+
+if (!taskDir) {
+  console.error(
+    'usage: check-task-artifact-contract.mjs <task-dir> [--contract path] [--terminal complete|no-change|blocked] [--require-recipe-quality-if-recipe] [--require-recipe-coverage-if-recipe] [--require-learnings] [--skip-learnings]',
+  );
+  process.exit(2);
+}
+
+const issues = [];
+const mediaExt = /\.(png|jpe?g|gif|mp4|mov|webm)$/i;
+const internalArtifactPath =
+  /^artifacts\/(?:harness-launch|harness-relaunch|harness-relaunch-node20|runtime-launch|runtime-relaunch|runner-blockers)\//;
+const allowedManifestKeys = new Set([
+  'version',
+  'preferred_mode',
+  'summary',
+  'before_after_pairs',
+  'standalone',
+  'omit',
+  'videos',
+  'before_state_capture',
+]);
+const allowedPairKeys = new Set(['label', 'covers', 'before', 'after', 'note']);
+const allowedStandaloneKeys = new Set(['label', 'covers', 'file', 'note']);
+const allowedVideoKeys = new Set(['before', 'after', 'preferred', 'note']);
+const allowedOmitKeys = new Set(['file', 'reason']);
+
+function fileExists(rel) {
+  try {
+    return statSync(path.join(taskDir, rel)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function readText(rel) {
+  const p = path.join(taskDir, rel);
+  return existsSync(p) ? readFileSync(p, 'utf8') : null;
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+
+function isRecipeQualityArtifactFallback(value) {
+  if (!isRecord(value)) return false;
+  if (value.version !== 1) return false;
+  if (!['pass', 'warn', 'fail'].includes(value.verdict)) return false;
+  if (!isRecord(value.compact)) return false;
+  if (!['PASS', 'WARN', 'FAIL'].includes(value.compact.verdict)) return false;
+  if (!isStringArray(value.compact.reasons)) return false;
+  if (!isStringArray(value.compact.better_version_guidance)) return false;
+  if (!isRecord(value.dimensions)) return false;
+  for (const dimension of Object.values(value.dimensions)) {
+    if (!isRecord(dimension)) return false;
+    if (!['pass', 'warn', 'fail', 'not_applicable'].includes(dimension.status)) return false;
+    if (typeof dimension.reason !== 'string') return false;
+    if (!isStringArray(dimension.evidence)) return false;
+  }
+  for (const key of ['structural_findings', 'contextual_findings']) {
+    if (!Array.isArray(value[key])) return false;
+    for (const finding of value[key]) {
+      if (!isRecord(finding)) return false;
+      if (typeof finding.code !== 'string' || typeof finding.message !== 'string') return false;
+      if (finding.dimension != null && typeof finding.dimension !== 'string') return false;
+      if (finding.evidence != null && !isStringArray(finding.evidence)) return false;
+    }
+  }
+  if (!isStringArray(value.suggested_recipe_delta)) return false;
+  if (!isRecord(value.training_fields)) return false;
+  const fields = value.training_fields;
+  if (fields.farm != null && typeof fields.farm !== 'string') return false;
+  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)
+  )
+    return false;
+  if (fields.task_type != null && typeof fields.task_type !== 'string') return false;
+  if (fields.claim_is_visual != null && typeof fields.claim_is_visual !== 'boolean') return false;
+  if (
+    fields.proof_mode != null &&
+    !['logs', 'state', 'trace', 'screenshot', 'mixed', 'unknown'].includes(fields.proof_mode)
+  )
+    return false;
+  if (fields.anti_patterns != null && !isStringArray(fields.anti_patterns)) return false;
+  if (fields.good_patterns != null && !isStringArray(fields.good_patterns)) return false;
+  if (!isRecord(value.meta)) return false;
+  const meta = value.meta;
+  if (
+    ![
+      'worker',
+      'gateway',
+      'fallback:recipe-coverage',
+      'fallback:recipe-json',
+      'fallback:report',
+      'fallback:missing',
+    ].includes(meta.producer)
+  )
+    return false;
+  if (typeof meta.fallback_used !== 'boolean') return false;
+  if (typeof meta.legacy_task !== 'boolean') return false;
+  if (typeof meta.artifact_required !== 'boolean') return false;
+  if (!isStringArray(meta.source_signals)) return false;
+  if (
+    meta.fallback_source != null &&
+    ![
+      'fallback:recipe-coverage',
+      'fallback:recipe-json',
+      'fallback:report',
+      'fallback:missing',
+    ].includes(meta.fallback_source)
+  )
+    return false;
+  return true;
+}
+
+function isRecipeQualityArtifactStrict(value) {
+  const validator = sharedRecipeQualityValidator ?? isRecipeQualityArtifactFallback;
+  return validator(value);
+}
+
+function unknownKeys(record, allowed, prefix) {
+  for (const key of Object.keys(record)) {
+    if (!allowed.has(key)) issues.push(`${prefix}.${key}: unknown key`);
+  }
+}
+
+function optionalString(record, key, prefix) {
+  if (record[key] !== undefined && typeof record[key] !== 'string') {
+    issues.push(`${prefix}.${key}: expected string`);
+  }
+}
+
+function optionalStringArray(record, key, prefix) {
+  if (record[key] === undefined) return;
+  if (!Array.isArray(record[key]) || record[key].some((entry) => typeof entry !== 'string')) {
+    issues.push(`${prefix}.${key}: expected string[]`);
+  }
+}
+
+function normalizeArtifactPath(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (!trimmed || /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i.test(trimmed)) return null;
+  const pathPart = trimmed.split(/[?#]/, 1)[0];
+  const normalized = pathPart.replace(/\\/g, '/').replace(/^\.\/+/g, '');
+  if (!normalized || path.posix.isAbsolute(normalized) || normalized.includes('\0')) return null;
+  const segments = normalized.split('/').filter(Boolean);
+  if (segments.some((segment) => segment === '.' || segment === '..')) return null;
+  const withoutArtifacts =
+    segments[0] === 'artifacts' ? segments.slice(1).join('/') : segments.join('/');
+  if (!withoutArtifacts || !mediaExt.test(withoutArtifacts)) return null;
+  return `artifacts/${withoutArtifacts}`;
+}
+
+function addRef(refs, value) {
+  const normalized = normalizeArtifactPath(value);
+  if (!normalized) return;
+  if (internalArtifactPath.test(normalized)) {
+    issues.push(`evidence-manifest references internal artifact: ${normalized}`);
+    return;
+  }
+  refs.add(normalized);
+}
+
+function validateRecipeQualityArtifact() {
+  const text = readText('artifacts/recipe-quality.json');
+  if (!text) return;
+  let artifact;
+  try {
+    artifact = JSON.parse(text);
+  } catch (error) {
+    issues.push(`recipe-quality.json: invalid JSON: ${error.message}`);
+    return;
+  }
+  if (!isRecord(artifact)) {
+    issues.push('recipe-quality.json: expected object');
+    return;
+  }
+  if (!isRecipeQualityArtifactStrict(artifact)) {
+    issues.push('recipe-quality.json: does not match RecipeQualityArtifact contract');
+  }
+}
+
+function parseManifest() {
+  const text = readText('artifacts/evidence-manifest.json');
+  if (!text) return null;
+  let manifest;
+  try {
+    manifest = JSON.parse(text);
+  } catch (error) {
+    issues.push(`evidence-manifest.json: invalid JSON: ${error.message}`);
+    return null;
+  }
+  if (!isRecord(manifest)) {
+    issues.push('evidence-manifest.json: expected object');
+    return null;
+  }
+  unknownKeys(manifest, allowedManifestKeys, 'manifest');
+  if (manifest.version !== undefined && typeof manifest.version !== 'number') {
+    issues.push('manifest.version: expected number');
+  }
+  if (
+    manifest.preferred_mode !== undefined &&
+    !['screenshots', 'video'].includes(manifest.preferred_mode)
+  ) {
+    issues.push('manifest.preferred_mode: expected screenshots or video');
+  }
+  optionalString(manifest, 'summary', 'manifest');
+
+  if (manifest.before_after_pairs !== undefined) {
+    if (!Array.isArray(manifest.before_after_pairs)) {
+      issues.push('manifest.before_after_pairs: expected array');
+    } else {
+      manifest.before_after_pairs.forEach((entry, index) => {
+        const prefix = `manifest.before_after_pairs[${index}]`;
+        if (!isRecord(entry)) return issues.push(`${prefix}: expected object`);
+        unknownKeys(entry, allowedPairKeys, prefix);
+        if (typeof entry.label !== 'string' || !entry.label.trim())
+          issues.push(`${prefix}.label: expected non-empty string`);
+        optionalStringArray(entry, 'covers', prefix);
+        optionalString(entry, 'before', prefix);
+        optionalString(entry, 'after', prefix);
+        optionalString(entry, 'note', prefix);
+        if (entry.before === undefined && entry.after === undefined)
+          issues.push(`${prefix}: expected before or after`);
+      });
+    }
+  }
+
+  if (manifest.standalone !== undefined) {
+    if (!Array.isArray(manifest.standalone)) {
+      issues.push('manifest.standalone: expected array');
+    } else {
+      manifest.standalone.forEach((entry, index) => {
+        const prefix = `manifest.standalone[${index}]`;
+        if (!isRecord(entry)) return issues.push(`${prefix}: expected object`);
+        unknownKeys(entry, allowedStandaloneKeys, prefix);
+        if (typeof entry.label !== 'string' || !entry.label.trim())
+          issues.push(`${prefix}.label: expected non-empty string`);
+        optionalStringArray(entry, 'covers', prefix);
+        if (typeof entry.file !== 'string' || !entry.file.trim())
+          issues.push(`${prefix}.file: expected non-empty string`);
+        optionalString(entry, 'note', prefix);
+      });
+    }
+  }
+
+  if (manifest.videos !== undefined) {
+    if (!isRecord(manifest.videos)) {
+      issues.push('manifest.videos: expected object');
+    } else {
+      unknownKeys(manifest.videos, allowedVideoKeys, 'manifest.videos');
+      optionalString(manifest.videos, 'before', 'manifest.videos');
+      optionalString(manifest.videos, 'after', 'manifest.videos');
+      optionalString(manifest.videos, 'note', 'manifest.videos');
+      if (
+        manifest.videos.preferred !== undefined &&
+        typeof manifest.videos.preferred !== 'boolean'
+      ) {
+        issues.push('manifest.videos.preferred: expected boolean');
+      }
+    }
+  }
+
+  if (manifest.omit !== undefined) {
+    if (!Array.isArray(manifest.omit)) {
+      issues.push('manifest.omit: expected array');
+    } else {
+      manifest.omit.forEach((entry, index) => {
+        const prefix = `manifest.omit[${index}]`;
+        if (typeof entry === 'string') return;
+        if (!isRecord(entry)) return issues.push(`${prefix}: expected string or object`);
+        unknownKeys(entry, allowedOmitKeys, prefix);
+        if (typeof entry.file !== 'string' || !entry.file.trim())
+          issues.push(`${prefix}.file: expected non-empty string`);
+        optionalString(entry, 'reason', prefix);
+      });
+    }
+  }
+
+  const refs = new Set();
+  for (const pair of manifest.before_after_pairs ?? []) {
+    addRef(refs, pair?.before);
+    addRef(refs, pair?.after);
+  }
+  for (const entry of manifest.standalone ?? []) addRef(refs, entry?.file);
+  addRef(refs, manifest.videos?.before);
+  addRef(refs, manifest.videos?.after);
+
+  for (const ref of [...refs].sort()) {
+    if (!fileExists(ref)) issues.push(`evidence-manifest references missing artifact: ${ref}`);
+  }
+  return { manifest, refs };
+}
+
+const hasRecipe = fileExists('artifacts/recipe.json');
+if (
+  hasRecipe &&
+  flags.has('--require-recipe-quality-if-recipe') &&
+  !fileExists('artifacts/recipe-quality.json')
+) {
+  issues.push('recipe.json exists but artifacts/recipe-quality.json is missing');
+}
+if (
+  hasRecipe &&
+  flags.has('--require-recipe-coverage-if-recipe') &&
+  !fileExists('artifacts/recipe-coverage.md')
+) {
+  issues.push('recipe.json exists but artifacts/recipe-coverage.md is missing');
+}
+validateRecipeQualityArtifact();
+
+const parsed = parseManifest();
+const coverage = readText('artifacts/recipe-coverage.md');
+if (coverage && /\|\s*(visual|mixed)\s*\|/i.test(coverage)) {
+  const refCount = parsed?.refs?.size ?? 0;
+  if (refCount === 0)
+    issues.push(
+      'recipe-coverage.md declares visual/mixed proof but evidence-manifest has no media references',
+    );
+}
+
+if (flags.has('--require-learnings')) {
+  const learnings = readText('artifacts/learnings.md');
+  if (!learnings?.trim()) {
+    issues.push('artifacts/learnings.md: required non-empty learnings artifact');
+  }
+}
+
+if (contractPath && existsSync(contractPath) && terminalCommand) {
+  const contract = JSON.parse(readFileSync(contractPath, 'utf8'));
+  const expanded = expandedArtifactsForCommand(contract, terminalCommand, fileExists);
+  for (const artifactPath of expanded.artifacts) {
+    if (flags.has('--skip-learnings') && artifactPath === 'artifacts/learnings.md') continue;
+    if (artifactPath.endsWith('.md') && !readText(artifactPath)?.trim()) {
+      issues.push(`${artifactPath}: required non-empty artifact (worker terminal contract)`);
+    }
+    if (!fileExists(artifactPath)) {
+      issues.push(`${artifactPath}: required artifact missing (worker terminal contract)`);
+    }
+  }
+  if (expanded.requireRecipeQuality && hasRecipe && !fileExists('artifacts/recipe-quality.json')) {
+    issues.push('recipe.json exists but artifacts/recipe-quality.json is missing');
+  }
+  if (expanded.requireRecipeCoverage && hasRecipe && !fileExists('artifacts/recipe-coverage.md')) {
+    issues.push('recipe.json exists but artifacts/recipe-coverage.md is missing');
+  }
+}
+
+if (issues.length > 0) {
+  console.error('TASK_ARTIFACT_CONTRACT_FAIL');
+  for (const issue of issues) console.error(`- ${issue}`);
+  process.exit(1);
+}
+console.log('TASK_ARTIFACT_CONTRACT_PASS');