@farmslot/agent-runtime 0.2.0 → 0.3.1

package/scripts/execution-template-cli.mjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * Standalone execution-template CLI for ADR-049.
+ * Used by `farmslot-agent execution-template` and thin Consensys wrappers.
+ */
+import { existsSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const distEntry = resolve(packageRoot, 'dist', 'index.js');
+
+function usage(exitCode = 0) {
+  const text = [
+    'Usage: execution-template <list|lint|new> [options]',
+    '',
+    'list   --dir <path> --project-worker <path> --package-templates <path>',
+    '       [--project-name name] [--package-id id] [--flow f] [--run-mode m]',
+    '       [--platform p] [--no-include-shadowed] [--json]',
+    'lint   <file-or-dir> [--json]',
+    'new    <path> [--flow f] [--run-mode m] [--platform p] [--title t] [--force] [--json]',
+  ].join('\n');
+  (exitCode === 0 ? console.log : console.error)(text);
+  process.exit(exitCode);
+}
+
+function takeValue(args, i, flag) {
+  const value = args[i + 1];
+  if (value === undefined) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+async function loadRuntime() {
+  if (!existsSync(distEntry)) {
+    throw new Error(
+      `compiled package missing at ${distEntry}; run yarn workspace @farmslot/agent-runtime build`,
+    );
+  }
+  return import(pathToFileURL(distEntry).href);
+}
+
+function parseRunMode(value) {
+  if (value === 'autonomous' || value === 'interactive' || value === 'validation') return value;
+  throw new Error(`--run-mode must be autonomous|interactive|validation (got ${value})`);
+}
+
+async function cmdList(args, runtime) {
+  const opts = {
+    dirs: [],
+    projectWorker: null,
+    projectName: 'project',
+    packageTemplates: null,
+    packageId: 'shared',
+    flow: undefined,
+    runMode: undefined,
+    platform: undefined,
+    includeShadowed: true,
+    json: false,
+  };
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--dir') opts.dirs.push(takeValue(args, i++, arg));
+    else if (arg === '--project-worker') opts.projectWorker = takeValue(args, i++, arg);
+    else if (arg === '--project-name') opts.projectName = takeValue(args, i++, arg);
+    else if (arg === '--package-templates') opts.packageTemplates = takeValue(args, i++, arg);
+    else if (arg === '--package-id') opts.packageId = takeValue(args, i++, arg);
+    else if (arg === '--flow') opts.flow = takeValue(args, i++, arg);
+    else if (arg === '--run-mode') opts.runMode = parseRunMode(takeValue(args, i++, arg));
+    else if (arg === '--platform') opts.platform = takeValue(args, i++, arg);
+    else if (arg === '--include-shadowed') opts.includeShadowed = true;
+    else if (arg === '--no-include-shadowed') opts.includeShadowed = false;
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '-h' || arg === '--help') usage(0);
+    else throw new Error(`unknown option ${arg}`);
+  }
+
+  const sources = [];
+  for (const [index, dir] of opts.dirs.entries()) {
+    const root = resolve(dir);
+    if (!existsSync(root) || !statSync(root).isDirectory()) {
+      throw new Error(`--dir is not a directory: ${root}`);
+    }
+    sources.push(runtime.customTemplateSource(`dir-${index + 1}`, root, 'flow-tree'));
+  }
+  if (opts.projectWorker) {
+    const input = resolve(opts.projectWorker);
+    const projectTemplatesDir =
+      input.endsWith('/worker') || input.endsWith('\\worker') ? resolve(input, '..') : input;
+    // An explicitly named source that does not exist is operator error — a
+    // silent empty catalog hides typos (worker/ is appended by the source).
+    const workerRoot = resolve(projectTemplatesDir, 'worker');
+    if (!existsSync(workerRoot) || !statSync(workerRoot).isDirectory()) {
+      throw new Error(`--project-worker is not a directory: ${workerRoot}`);
+    }
+    sources.push(runtime.projectWorkerTemplateSource(opts.projectName, projectTemplatesDir));
+  }
+  if (opts.packageTemplates) {
+    const root = resolve(opts.packageTemplates);
+    if (!existsSync(root) || !statSync(root).isDirectory()) {
+      throw new Error(`--package-templates is not a directory: ${root}`);
+    }
+    sources.push(runtime.packageFlowTreeTemplateSource(opts.packageId, root));
+  }
+  if (sources.length === 0) {
+    throw new Error('provide --dir, --project-worker, and/or --package-templates');
+  }
+
+  const templates = runtime.listExecutionTemplates({
+    sources,
+    flow: opts.flow,
+    runMode: opts.runMode,
+    platform: opts.platform,
+    includeShadowed: opts.includeShadowed,
+  });
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify({ templates }, null, 2)}\n`);
+    return;
+  }
+  for (const entry of templates) {
+    const shadow = entry.shadowedBy ? ` (shadowed by ${entry.shadowedBy})` : '';
+    process.stdout.write(
+      `${entry.id}\t${entry.flow}\t${entry.runMode ?? '-'}\t${entry.platforms.join(',')}\t${entry.sourceId}\t${entry.path}${shadow}\n`,
+    );
+  }
+}
+
+async function cmdLint(args, runtime) {
+  let target = null;
+  let json = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--json') json = true;
+    else if (arg === '-h' || arg === '--help') usage(0);
+    else if (!arg.startsWith('-') && !target) target = arg;
+    else throw new Error(`unknown option ${arg}`);
+  }
+  if (!target) usage(2);
+  const result = runtime.lintExecutionTemplates(target);
+  if (json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else if (result.ok) {
+    process.stdout.write(`pass ${result.filesChecked} template(s)\n`);
+  } else {
+    for (const issue of result.issues) {
+      process.stderr.write(`${issue.severity} ${issue.path}: ${issue.message}\n`);
+    }
+  }
+  if (!result.ok) process.exitCode = 1;
+}
+
+async function cmdNew(args, runtime) {
+  let pathArg = null;
+  const opts = {
+    flow: undefined,
+    runMode: undefined,
+    platforms: undefined,
+    title: undefined,
+    force: false,
+    json: false,
+  };
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--flow') opts.flow = takeValue(args, i++, arg);
+    else if (arg === '--run-mode') opts.runMode = parseRunMode(takeValue(args, i++, arg));
+    else if (arg === '--platform') {
+      opts.platforms = takeValue(args, i++, arg)
+        .split(',')
+        .map((p) => p.trim())
+        .filter(Boolean);
+    } else if (arg === '--title') opts.title = takeValue(args, i++, arg);
+    else if (arg === '--force') opts.force = true;
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '-h' || arg === '--help') usage(0);
+    else if (!arg.startsWith('-') && !pathArg) pathArg = arg;
+    else throw new Error(`unknown option ${arg}`);
+  }
+  if (!pathArg) usage(2);
+  const created = runtime.createExecutionTemplate({
+    path: pathArg,
+    flow: opts.flow,
+    runMode: opts.runMode,
+    platforms: opts.platforms,
+    title: opts.title,
+    force: opts.force,
+  });
+  if (opts.json) process.stdout.write(`${JSON.stringify(created, null, 2)}\n`);
+  else process.stdout.write(`created ${created.path}\n`);
+}
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (!command || command === '-h' || command === '--help') usage(0);
+  const runtime = await loadRuntime();
+  if (command === 'list') await cmdList(rest, runtime);
+  else if (command === 'lint') await cmdLint(rest, runtime);
+  else if (command === 'new') await cmdNew(rest, runtime);
+  else usage(2);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/scripts/mark-checklist-step.cjs

@@ -19,13 +19,16 @@ const FLOW_REPORT_ARTIFACTS = {
   'review-pr': ['review.md', 'report.md'],
   dev: ['pr-description.md', 'report.md'],
   'pr-complete': ['comments-report.md', 'report.md'],
-  'merge-main': ['report.md', 'merge-report.md'],
+  'update-branch': ['branch-update-report.md', 'report.md'],
+  'ci-fix': ['report.md'],
+  'self-review': ['review-feedback.md', 'report.md'],
+  'self-review-fix': ['report.md'],
 };
 const FALLBACK_REPORT_ARTIFACTS = [
   'report.md',
   'review.md',
   'comments-report.md',
-  'merge-report.md',
+  'branch-update-report.md',
 ];
 
 const usageLine =
@@ -44,8 +47,8 @@ function printHelp() {
       '  ./mark complete [--mark-last] [--no-self-review] [--skip-learnings] [--skip-checklist]',
       '  ./mark no-change --reason "..." [--already-fixed] [--mark-last] [--skip-learnings] [--skip-checklist]',
       '  ./mark blocked --reason "..." [--mark-last]',
-      'Terminal success paths require non-empty artifacts/learnings.md and a flow outcome artifact (complete) or no-change-report (no-change).',
-      'PR flows (dev, fix-bug): write artifacts/pr-description.md. Other flows: review.md, merge-report.md, report.md, etc.',
+      'Terminal success paths require the flow contract artifacts: contribution flows need non-empty artifacts/learnings.md plus a flow outcome artifact (complete) or no-change-report (no-change); reviewer flows (self-review, self-review-fix) need their feedback/report artifact instead of learnings.',
+      'PR flows (dev, fix-bug): write artifacts/pr-description.md. Other flows: review.md, review-feedback.md, branch-update-report.md, report.md, etc.',
       'With --mark-last, every checklist box must be [x] unless --skip-checklist. complete also runs check-task-artifact-contract.mjs.',
       'Do not write SIGNAL.json by hand or with echo.',
     ].join('\n'),
@@ -238,13 +241,20 @@ function inferFlowType(taskPath) {
   } catch {
     return null;
   }
-  const workerMatch = head.match(/^#\s*Worker:\s*([^\n—-]+)/im);
+  const workerMatch = head.match(/^#\s*Worker:\s*([^\n]+)/im);
   if (workerMatch) {
-    const label = workerMatch[1].trim().toLowerCase();
+    const label = workerMatch[1]
+      .split(/\s+[—-]\s+/)[0]
+      .trim()
+      .toLowerCase();
     if (label.includes('fix-bug') || label.includes('fix bug')) return 'fix-bug';
     if (label.includes('review-pr') || label.includes('review pr')) return 'review-pr';
     if (label.includes('pr-complete') || label.includes('pr complete')) return 'pr-complete';
-    if (label.includes('merge-main') || label.includes('merge main')) return 'merge-main';
+    if (label.includes('update-branch') || label.includes('update branch')) return 'update-branch';
+    if (label.includes('ci-fix') || label.includes('ci fix')) return 'ci-fix';
+    if (label.includes('self-review fix') || label.includes('self-review-fix'))
+      return 'self-review-fix';
+    if (label.includes('self-review') || label.includes('self review')) return 'self-review';
     if (label.includes('interactive dev')) return 'dev';
     if (/\bdev\b/.test(label) && !label.includes('review')) return 'dev';
   }
@@ -292,7 +302,15 @@ function assertArtifactContract(taskDir, contract, terminalCommand) {
     if (terminalCommand) args.push('--terminal', terminalCommand);
     if (opts['skip-learnings']) args.push('--skip-learnings');
   } else {
-    if (!opts['skip-learnings']) args.push('--require-learnings');
+    // No persisted contract file — honor the resolved builtin contract instead of
+    // assuming learnings: reviewer flows (self-review, self-review-fix) require their
+    // feedback/report artifact, not artifacts/learnings.md.
+    const contractRequiresLearnings = contract
+      ? (contract.commands?.[terminalCommand ?? 'complete']?.artifacts ?? []).includes(
+          LEARNINGS_ARTIFACT.split(path.sep).join('/'),
+        )
+      : true;
+    if (!opts['skip-learnings'] && contractRequiresLearnings) args.push('--require-learnings');
     if (fs.existsSync(path.join(taskDir, 'artifacts', 'recipe.json'))) {
       args.push('--require-recipe-coverage-if-recipe', '--require-recipe-quality-if-recipe');
     }

package/scripts/worker-terminal-contract.cjs

@@ -36,7 +36,11 @@
  * @property {'builtin' | 'project'} source
  */
 
-const TERMINAL_MARK_RE = /(?:\.\/|\{\{TASK_DIR\}\}\/)mark\s+(complete|no-change|blocked)\b/;
+const TERMINAL_MARK_PATTERN =
+  String.raw`(?:\.\/|\{\{TASK_DIR\}\}\/)mark\b(?:\s+--(?:checklist|signal)\s+\S+)*\s+` +
+  String.raw`(complete|no-change|blocked)\b`;
+const TERMINAL_MARK_RE = new RegExp(TERMINAL_MARK_PATTERN);
+const TERMINAL_MARK_GLOBAL_RE = new RegExp(TERMINAL_MARK_PATTERN, 'g');
 const TERMINAL_COMMANDS = /** @type {const} */ (['complete', 'no-change', 'blocked']);
 
 const LEARNINGS = 'artifacts/learnings.md';
@@ -83,7 +87,7 @@ const BUILTIN_FLOW_COMMANDS = {
     },
     blocked: { artifacts: [] },
   },
-  'merge-main': {
+  'update-branch': {
     complete: {
       report: 'artifacts/report.md',
       artifacts: [LEARNINGS, 'artifacts/report.md'],
@@ -102,19 +106,26 @@ const BUILTIN_FLOW_COMMANDS = {
     },
     blocked: { artifacts: [] },
   },
+  // Reviewer flows produce feedback/report artifacts, not learnings.md — the
+  // reviewer evaluates someone else's work, so the learnings requirement that
+  // applies to contribution flows does not apply here (matches the templates
+  // and the runtime FLOW_REPORT_ARTIFACTS mapping).
   'self-review': {
-    complete: { artifacts: [LEARNINGS] },
+    complete: {
+      report: 'artifacts/review-feedback.md',
+      artifacts: ['artifacts/review-feedback.md'],
+    },
     'no-change': {
-      report: 'artifacts/no-change-report.md',
-      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
+      report: 'artifacts/review-feedback.md',
+      artifacts: ['artifacts/review-feedback.md'],
     },
     blocked: { artifacts: [] },
   },
   'self-review-fix': {
-    complete: { report: 'artifacts/report.md', artifacts: [LEARNINGS, 'artifacts/report.md'] },
+    complete: { report: 'artifacts/report.md', artifacts: ['artifacts/report.md'] },
     'no-change': {
       report: 'artifacts/no-change-report.md',
-      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
+      artifacts: ['artifacts/no-change-report.md'],
     },
     blocked: { artifacts: [] },
   },
@@ -248,9 +259,7 @@ function templateTerminalCommands(content) {
     }
   }
   const commands = new Set();
-  for (const match of scope.matchAll(
-    /(?:\.\/|\{\{TASK_DIR\}\}\/)mark\s+(complete|no-change|blocked)\b/g,
-  )) {
+  for (const match of scope.matchAll(TERMINAL_MARK_GLOBAL_RE)) {
     commands.add(match[1]);
   }
   if (commands.size === 0 && /mark-checklist-step\.cjs[\s\S]{0,400}?\bcomplete\b/.test(scope)) {
@@ -311,21 +320,14 @@ function lintWorkerTemplateAgainstContract(templateContent, contract) {
   /** @type {string[]} */
   const issues = [];
   if (!templateUsesTerminalMark(templateContent)) {
-    issues.push(
-      'terminal worker template must instruct `./mark complete`, `./mark no-change`, or `./mark blocked`',
-    );
-    return issues;
-  }
-
-  if (contract.requireSignal) {
-    if (!templateUsesTerminalMark(templateContent)) {
+    // Omitting `./mark` entirely is only acceptable when the resolved contract
+    // does not require a terminal signal (e.g. pr-complete interactive).
+    if (contract.requireSignal) {
       issues.push(
         'requireSignal is true but template has no terminal `./mark` or mark-checklist-step command',
       );
     }
-    if (/never hand-write `SIGNAL\.json`|Do not write.*SIGNAL\.json/i.test(templateContent)) {
-      // allowed when paired with mark instructions
-    }
+    return issues;
   }
 
   const commands = templateTerminalCommands(templateContent);