@farmslot/agent-runtime 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -4,10 +4,23 @@
 
 - Active-development baseline; add user-facing changes here before release or package publication.
 
-## 0.1.0 - 2026-07-06
+## 0.2.0 - 2026-07-12
+
+- fix: use workspace-linked `@farmslot/protocol` during local development so package builds cannot resolve a stale published sibling package.
+- feat: the task-artifact contract check validates `artifacts/recipe.json` (envelope-only) and, when present, `artifacts/resolved-recipe.json` (in full, including flow-call resolution) against the shared Recipe Protocol v1 validator, with a local minimum-envelope fallback when `@farmslot/protocol` dist is not yet built.
+
+## 0.1.1 - 2026-07-06
 
 ### Added
 
-- Add `buildRecipeQualityArtifact()` and `farmslot-agent recipe-quality build` so agents can generate validator-compliant `recipe-quality.json` artifacts from compact verdict/reason/finding inputs.
-- Introduce `@farmslot/agent-runtime` for task-local `mark`, `SIGNAL.json`, worker terminal contract, and task artifact checks.
-- Add `farmslot-agent` CLI with `mark`, `artifact-check`, `install-mark`, and `contract resolve` commands.
+- Add `checklist-target.json` resolution to `mark-checklist-step.cjs` task-dir mode so `./mark` retargets to nested-loop checklists without per-role wrapper scripts.
+- Add `--checklist` / `--signal` overrides on task-dir invocations; signal defaults from checklist basename when omitted.
+- Add centralized nested-loop checklist/signal registry (`DEFAULT_CHECKLIST_TARGET_REGISTRY`, `CHECKLIST_TARGET_BY_AGENT_ROLE`) and path helpers in `checklist-target.cjs`.
+- Add sync test ensuring `checklist-target.cjs` constants stay aligned with `@farmslot/protocol/checklist-target`.
+
+### Changed
+
+- Task-dir `./mark` now requires a valid `checklist-target.json`; missing or invalid manifests fail with a teaching error instead of silently falling back to worker `TASK.md`/`SIGNAL.json`.
+- Remove the legacy explicit-args mark surface (`mark <task.md> <signal.json> <step>`); task-dir mode is the only supported invocation.
+
+## 0.1.0 - 2026-07-06

package/bin/farmslot-agent.mjs

@@ -413,7 +413,7 @@ function installMark(args) {
       '#!/usr/bin/env bash',
       'set -euo pipefail',
       'DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"',
-      `node ${JSON.stringify(binPath)} mark "$DIR/${parsed.task}" "$DIR/${parsed.signal}" "$@"`,
+      `node ${JSON.stringify(binPath)} mark "$DIR" "$@"`,
       '',
     ].join('\n'),
     { mode: 0o755 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farmslot/agent-runtime",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,12 +14,13 @@
       "default": "./dist/index.js"
     },
     "./scripts/mark-checklist-step.cjs": "./scripts/mark-checklist-step.cjs",
+    "./scripts/checklist-target.cjs": "./scripts/checklist-target.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",
+    "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",
     "format": "prettier --write --ignore-path ../../.prettierignore .",
     "format:check": "prettier --check --ignore-path ../../.prettierignore .",
     "lint": "eslint \"src/**/*.ts\"",
@@ -30,7 +31,7 @@
     "prepublishOnly": "node ../../scripts/quality/check-farmslot-package-readiness.mjs --publish --packages @farmslot/agent-runtime"
   },
   "dependencies": {
-    "@farmslot/protocol": "0.7.3"
+    "@farmslot/protocol": "0.8.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

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

@@ -7,6 +7,11 @@ const require = createRequire(import.meta.url);
 const { expandedArtifactsForCommand } = require('./worker-terminal-contract.cjs');
 
 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;
 try {
   ({ isRecipeQualityArtifact: sharedRecipeQualityValidator } =
     await import('@farmslot/protocol/contracts/recipes'));
@@ -17,6 +22,20 @@ try {
     console.warn(`[agent-runtime] using local RecipeQualityArtifact fallback: ${error.message}`);
   }
 }
+try {
+  const recipeProtocol = await import('@farmslot/protocol/recipe');
+  sharedRecipeDocumentValidator = recipeProtocol.validateRecipeDocument;
+  if (typeof recipeProtocol.recipeProtocolSchemaUrlForVersion === 'function') {
+    sharedRecipeSchemaUrlForVersion = recipeProtocol.recipeProtocolSchemaUrlForVersion;
+  }
+} 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 (process.env.FARMSLOT_DEBUG_AGENT_RUNTIME) {
+    console.warn(`[agent-runtime] using local Recipe v1 fallback: ${error.message}`);
+  }
+}
 
 const taskDir = process.argv[2];
 const rawArgs = process.argv.slice(3);
@@ -226,6 +245,83 @@ 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;
+    }
+  }
+  if (runFailed) {
+    validateRecipeDocumentArtifactAt('artifacts/recipe.json', 'recipe.json', {
+      skipFlowCallResolution: true,
+    });
+    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', {});
+}
+
+function validateRecipeDocumentArtifactAt(relPath, label, options) {
+  const text = readText(relPath);
+  if (!text) return;
+  let recipe;
+  try {
+    recipe = JSON.parse(text);
+  } catch (error) {
+    issues.push(`${label}: invalid JSON: ${error.message}`);
+    return;
+  }
+  if (sharedRecipeDocumentValidator) {
+    const result = sharedRecipeDocumentValidator(recipe, options);
+    for (const finding of result.findings) {
+      if (finding.severity === 'error') {
+        issues.push(`${label}: ${finding.code} ${finding.path}: ${finding.message}`);
+      }
+    }
+    return;
+  }
+  if (!isRecord(recipe)) {
+    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`);
+    return;
+  }
+  const workflow = recipe.validate.workflow;
+  if (typeof workflow.entry !== 'string' || !workflow.entry.trim()) {
+    issues.push(`${label}: validate.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`);
+  }
+}
+
 function parseManifest() {
   const text = readText('artifacts/evidence-manifest.json');
   if (!text) return null;
@@ -339,6 +435,7 @@ function parseManifest() {
 }
 
 const hasRecipe = fileExists('artifacts/recipe.json');
+validateRecipeDocumentArtifact();
 if (
   hasRecipe &&
   flags.has('--require-recipe-quality-if-recipe') &&

package/scripts/checklist-target.cjs

@@ -0,0 +1,211 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Canonical filename registry lives in @farmslot/protocol/checklist-target — keep in sync (see test/checklist-target-sync.test.mjs).
+
+const CHECKLIST_TARGET_MANIFEST = 'checklist-target.json';
+const TASK_PROGRESS_MARKDOWN = 'TASK.md';
+const INTERACTIVE_CHECKLIST_MARKDOWN = 'CHECKLIST.md';
+const WORKER_SIGNAL_FILE = 'SIGNAL.json';
+const ROLE_SIGNAL_SUFFIX = '-SIGNAL.json';
+
+const SELF_REVIEW_CHECKLIST = 'SELF-REVIEW.md';
+const SELF_REVIEW_FIX_CHECKLIST = 'SELF-REVIEW-FIX.md';
+const CI_FIX_CHECKLIST = 'CI-FIX.md';
+
+function signalFileForChecklist(checklistBasename) {
+  if (
+    checklistBasename === TASK_PROGRESS_MARKDOWN ||
+    checklistBasename === INTERACTIVE_CHECKLIST_MARKDOWN
+  ) {
+    return WORKER_SIGNAL_FILE;
+  }
+  const base = checklistBasename.replace(/\.md$/i, '');
+  return `${base}${ROLE_SIGNAL_SUFFIX}`;
+}
+
+function taskDirRelPath(taskDir, basename) {
+  const normalized = String(taskDir).replace(/\/+$/, '');
+  return `${normalized}/${basename}`;
+}
+
+function targetForChecklistBasename(checklistBasename) {
+  return {
+    checklist: checklistBasename,
+    signal: signalFileForChecklist(checklistBasename),
+  };
+}
+
+function defaultWorkerTarget(taskDir) {
+  const checklist = fs.existsSync(path.join(taskDir, INTERACTIVE_CHECKLIST_MARKDOWN))
+    ? INTERACTIVE_CHECKLIST_MARKDOWN
+    : TASK_PROGRESS_MARKDOWN;
+  return targetForChecklistBasename(checklist);
+}
+
+const SELF_REVIEW_CHECKLIST_TARGET = targetForChecklistBasename(SELF_REVIEW_CHECKLIST);
+const SELF_REVIEW_FIX_CHECKLIST_TARGET = targetForChecklistBasename(SELF_REVIEW_FIX_CHECKLIST);
+const CI_FIX_CHECKLIST_TARGET = targetForChecklistBasename(CI_FIX_CHECKLIST);
+
+const CHECKLIST_TARGET_BY_AGENT_ROLE = {
+  'self-review': SELF_REVIEW_CHECKLIST_TARGET,
+  'self-review-fix': SELF_REVIEW_FIX_CHECKLIST_TARGET,
+  'ci-fix': CI_FIX_CHECKLIST_TARGET,
+};
+
+const DEFAULT_CHECKLIST_TARGET_REGISTRY = {
+  manifest: CHECKLIST_TARGET_MANIFEST,
+  workerTask: TASK_PROGRESS_MARKDOWN,
+  interactiveChecklist: INTERACTIVE_CHECKLIST_MARKDOWN,
+  workerSignal: WORKER_SIGNAL_FILE,
+  roleSignalSuffix: ROLE_SIGNAL_SUFFIX,
+  roles: CHECKLIST_TARGET_BY_AGENT_ROLE,
+};
+
+function checklistTargetForAgentRole(role, registry = DEFAULT_CHECKLIST_TARGET_REGISTRY) {
+  return registry.roles[role] ?? null;
+}
+
+function readManifest(taskDir) {
+  const manifestPath = path.join(taskDir, CHECKLIST_TARGET_MANIFEST);
+  if (!fs.existsSync(manifestPath)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object') return null;
+  const checklist = typeof parsed.checklist === 'string' ? parsed.checklist.trim() : '';
+  if (!checklist || path.basename(checklist) !== checklist) return null;
+  const signalRaw = typeof parsed.signal === 'string' ? parsed.signal.trim() : '';
+  const signal =
+    signalRaw && path.basename(signalRaw) === signalRaw
+      ? signalRaw
+      : signalFileForChecklist(checklist);
+  return { checklist, signal };
+}
+
+function manifestModeTeachingError(taskDir, reason) {
+  const manifestPath = path.join(path.resolve(taskDir), CHECKLIST_TARGET_MANIFEST);
+  return (
+    `Missing or invalid ${CHECKLIST_TARGET_MANIFEST} at ${manifestPath} (${reason}). ` +
+    'The gateway writes this file at task creation and on every role switch — re-run dispatch/prepare for this run, or write the manifest manually. ' +
+    'Escape hatch: farmslot-agent mark <task-dir> --checklist FILE.md <step> [--signal FILE.json].'
+  );
+}
+
+function taskLocalBasenameOrThrow(value, label, expectedExt) {
+  if (!value || typeof value !== 'string') {
+    throw new Error(`${label} is required`);
+  }
+  const trimmed = value.trim();
+  if (trimmed.includes('/') || trimmed.includes('\\')) {
+    throw new Error(`${label} must be a task-local basename (got ${value})`);
+  }
+  if (!trimmed.endsWith(expectedExt)) {
+    throw new Error(`${label} must end with ${expectedExt} (got ${trimmed})`);
+  }
+  return trimmed;
+}
+
+function resolveChecklistTargetWithOverrides(taskDir, overrides = {}) {
+  const normalizedDir = path.resolve(taskDir);
+  if (overrides.checklist) {
+    const checklist = taskLocalBasenameOrThrow(overrides.checklist, '--checklist', '.md');
+    const signal = overrides.signal
+      ? taskLocalBasenameOrThrow(overrides.signal, '--signal', '.json')
+      : signalFileForChecklist(checklist);
+    return { checklist, signal };
+  }
+  return resolveChecklistTarget(normalizedDir);
+}
+
+function parseTaskDirMarkArgs(taskDir, rawArgs, { isMarkStepToken, usage }) {
+  const overrides = {};
+  const positional = [];
+  for (let i = 0; i < rawArgs.length; i += 1) {
+    const token = rawArgs[i];
+    if (token === '--checklist') {
+      overrides.checklist = rawArgs[++i];
+      if (!overrides.checklist) usage();
+      continue;
+    }
+    if (token === '--signal') {
+      overrides.signal = rawArgs[++i];
+      if (!overrides.signal) usage();
+      continue;
+    }
+    positional.push(token);
+  }
+  if (positional.length === 0) usage();
+  const stepRaw = positional[0];
+  if (stepRaw === '--help' || stepRaw === '-h') {
+    return { help: true };
+  }
+  if (!isMarkStepToken(stepRaw)) usage();
+  let target;
+  try {
+    target = resolveChecklistTargetWithOverrides(taskDir, overrides);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(2);
+  }
+  const normalizedDir = path.resolve(taskDir);
+  return {
+    taskPath: path.join(normalizedDir, target.checklist),
+    signalPath: path.join(normalizedDir, target.signal),
+    stepRaw,
+    rest: positional.slice(1),
+  };
+}
+
+function resolveChecklistTarget(taskDir) {
+  const normalizedDir = path.resolve(taskDir);
+  const manifestPath = path.join(normalizedDir, CHECKLIST_TARGET_MANIFEST);
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(manifestModeTeachingError(taskDir, 'file not found'));
+  }
+  const fromManifest = readManifest(normalizedDir);
+  if (!fromManifest) {
+    throw new Error(manifestModeTeachingError(taskDir, 'invalid JSON or checklist basename'));
+  }
+  return fromManifest;
+}
+
+function resolveChecklistPaths(taskDir) {
+  const target = resolveChecklistTarget(taskDir);
+  const normalizedDir = path.resolve(taskDir);
+  return {
+    taskPath: path.join(normalizedDir, target.checklist),
+    signalPath: path.join(normalizedDir, target.signal),
+    target,
+  };
+}
+
+module.exports = {
+  CHECKLIST_TARGET_MANIFEST,
+  TASK_PROGRESS_MARKDOWN,
+  INTERACTIVE_CHECKLIST_MARKDOWN,
+  WORKER_SIGNAL_FILE,
+  ROLE_SIGNAL_SUFFIX,
+  SELF_REVIEW_CHECKLIST,
+  SELF_REVIEW_FIX_CHECKLIST,
+  CI_FIX_CHECKLIST,
+  SELF_REVIEW_CHECKLIST_TARGET,
+  SELF_REVIEW_FIX_CHECKLIST_TARGET,
+  CI_FIX_CHECKLIST_TARGET,
+  CHECKLIST_TARGET_BY_AGENT_ROLE,
+  DEFAULT_CHECKLIST_TARGET_REGISTRY,
+  checklistTargetForAgentRole,
+  taskDirRelPath,
+  signalFileForChecklist,
+  targetForChecklistBasename,
+  defaultWorkerTarget,
+  manifestModeTeachingError,
+  readManifest,
+  resolveChecklistTarget,
+  resolveChecklistTargetWithOverrides,
+  resolveChecklistPaths,
+  parseTaskDirMarkArgs,
+};

package/scripts/mark-checklist-step.cjs

@@ -6,6 +6,7 @@ const {
   expandedArtifactsForCommand,
   resolveWorkerTerminalContract,
 } = require('./worker-terminal-contract.cjs');
+const { parseTaskDirMarkArgs } = require('./checklist-target.cjs');
 
 const START_COMMANDS = new Set(['start']);
 const TERMINAL_COMMANDS = new Set(['complete', 'no-change', 'blocked']);
@@ -28,14 +29,16 @@ const FALLBACK_REPORT_ARTIFACTS = [
 ];
 
 const usageLine =
-  'usage: mark <step-number|start|complete|no-change|blocked> [--reason text] [--already-fixed] [--mark-last] [--no-self-review] [--skip-learnings] [--skip-checklist]';
+  'usage: mark <task-dir> [--checklist FILE.md] [--signal FILE.json] <step> [options]';
 
 function printHelp() {
   console.log(
     [
       usageLine,
       '',
-      'Bootstrap: ./mark start — worker-owned SIGNAL.json with status running (no checklist box).',
+      'Task-dir mode: farmslot-agent mark <task-dir> <step> — requires checklist-target.json written by the gateway at task creation or role switch.',
+      'Override: farmslot-agent mark <task-dir> --checklist SELF-REVIEW.md <step> — optional --signal; signal defaults from checklist name.',
+      'Bootstrap: ./mark start — role-owned signal with status running (no checklist box).',
       'Progress: ./mark 1, ./mark 2, ... — checks the box and appends checklistTiming.',
       'Terminal:',
       '  ./mark complete [--mark-last] [--no-self-review] [--skip-learnings] [--skip-checklist]',
@@ -55,18 +58,41 @@ function usage() {
   process.exit(2);
 }
 
-const args = process.argv.slice(2);
-if (args.length === 1 && (args[0] === '--help' || args[0] === '-h')) {
-  printHelp();
-  process.exit(0);
+function isMarkStepToken(token) {
+  if (token === '--help' || token === '-h') return true;
+  const lower = String(token).toLowerCase();
+  if (START_COMMANDS.has(lower) || TERMINAL_COMMANDS.has(lower)) return true;
+  const stepNumber = Number(token);
+  return Number.isInteger(stepNumber) && stepNumber >= 1;
 }
 
-const [taskPath, signalPath, stepRaw, ...rest] = args;
-if (stepRaw === '--help' || stepRaw === '-h') {
-  printHelp();
-  process.exit(0);
+function resolveMarkInvocation(rawArgs) {
+  if (rawArgs.length === 0) usage();
+  const first = rawArgs[0];
+  if (first === '--help' || first === '-h') {
+    printHelp();
+    process.exit(0);
+  }
+
+  const firstPath = path.resolve(first);
+  const firstIsDir = fs.existsSync(firstPath) && fs.statSync(firstPath).isDirectory();
+  if (firstIsDir) {
+    const parsed = parseTaskDirMarkArgs(firstPath, rawArgs.slice(1), {
+      isMarkStepToken,
+      usage,
+    });
+    if (parsed.help) {
+      printHelp();
+      process.exit(0);
+    }
+    return parsed;
+  }
+
+  usage();
 }
-if (!taskPath || !signalPath || !stepRaw) usage();
+
+const args = process.argv.slice(2);
+const { taskPath, signalPath, stepRaw, rest } = resolveMarkInvocation(args);
 
 const opts = {};
 for (let i = 0; i < rest.length; i += 1) {