@farmslot/agent-runtime 0.11.0 → 0.13.0

package/scripts/acceptance-ledger.cjs

@@ -0,0 +1,412 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { atomicWrite, readJson } = require('./mark-io.cjs');
+
+// Acceptance-criteria ledger (ADR-060 / plans/sub-task-observability-v1.md).
+//
+// `farmslot-agent ac` is the only writer of artifacts/acceptance-status.json, the
+// way `mark` is the only writer of SIGNAL.json. The ids come from task init, which
+// records the criteria in inputs/handoff.json; this module never invents one.
+//
+// The constants and the validate/summarize/render helpers are a behavioral mirror
+// of @farmslot/protocol/contracts/acceptance (see test/acceptance-ledger-sync.test.mjs).
+// The mirror exists because the mark engine and this CLI are CJS and must run on a
+// slot without a built protocol package.
+
+const HANDOFF_INPUT = path.join('inputs', 'handoff.json');
+const ACCEPTANCE_STATUS_ARTIFACT = 'artifacts/acceptance-status.json';
+const ACCEPTANCE_VERDICTS = ['proven', 'weak', 'missing', 'untestable'];
+const ACCEPTANCE_PROOF_MODES = ['state', 'visual', 'mixed'];
+const ACCEPTANCE_CRITERION_ID_PATTERN = /^AC-[1-9][0-9]*$/;
+
+/** A refused command: the message is worker-facing, the code is the exit code. */
+class AcceptanceRefusal extends Error {
+  constructor(message, code = 1) {
+    super(message);
+    this.name = 'AcceptanceRefusal';
+    this.code = code;
+  }
+}
+
+/**
+ * `AC-<N>` for a criterion's position in the handoff array.
+ * @param {number} index 0-based position in inputs/handoff.json task.acceptanceCriteria.
+ */
+function acceptanceCriterionId(index) {
+  return `AC-${index + 1}`;
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function validateAcceptanceStatusLedger(value) {
+  const issues = [];
+  if (!isRecord(value)) return ['acceptance ledger: expected object'];
+  if (value.schemaVersion !== 1) issues.push('acceptance ledger schemaVersion: expected 1');
+  if (!Array.isArray(value.criteria)) {
+    issues.push('acceptance ledger criteria: expected array');
+    return issues;
+  }
+  const seen = new Set();
+  value.criteria.forEach((entry, index) => {
+    const prefix = `acceptance ledger criteria[${index}]`;
+    if (!isRecord(entry)) {
+      issues.push(`${prefix}: expected object`);
+      return;
+    }
+    if (!isNonEmptyString(entry.id) || !ACCEPTANCE_CRITERION_ID_PATTERN.test(entry.id)) {
+      issues.push(`${prefix}.id: expected AC-<N>`);
+    } else if (seen.has(entry.id)) {
+      issues.push(`${prefix}.id: duplicate ${entry.id}`);
+    } else {
+      seen.add(entry.id);
+    }
+    if (typeof entry.text !== 'string') issues.push(`${prefix}.text: expected string`);
+    if (!ACCEPTANCE_VERDICTS.includes(entry.verdict)) {
+      issues.push(`${prefix}.verdict: expected one of ${ACCEPTANCE_VERDICTS.join(', ')}`);
+    }
+    if (entry.proofMode !== undefined && !ACCEPTANCE_PROOF_MODES.includes(entry.proofMode)) {
+      issues.push(`${prefix}.proofMode: expected one of ${ACCEPTANCE_PROOF_MODES.join(', ')}`);
+    }
+    for (const key of ['evidence', 'recipeNodes']) {
+      const list = entry[key];
+      if (!Array.isArray(list) || list.some((item) => !isNonEmptyString(item))) {
+        issues.push(`${prefix}.${key}: expected an array of non-empty strings`);
+      }
+    }
+    if (entry.note !== undefined && typeof entry.note !== 'string') {
+      issues.push(`${prefix}.note: expected string`);
+    }
+    if (!isNonEmptyString(entry.updatedAt)) {
+      issues.push(`${prefix}.updatedAt: expected non-empty string`);
+    }
+  });
+  return issues;
+}
+
+function acceptanceCriteriaView(criteria, ledger) {
+  const byId = new Map((ledger?.criteria ?? []).map((entry) => [entry.id, entry]));
+  const rows = criteria.map((criterion) => ({
+    ...criterion,
+    status: byId.get(criterion.id) ?? null,
+  }));
+  for (const entry of ledger?.criteria ?? []) {
+    if (!criteria.some((criterion) => criterion.id === entry.id)) {
+      rows.push({ id: entry.id, text: entry.text, status: entry });
+    }
+  }
+  return rows;
+}
+
+function summarizeAcceptanceStatus(ledger, criteria) {
+  const total = criteria
+    ? Math.max(criteria.length, ledger.criteria.length)
+    : ledger.criteria.length;
+  const summary = {
+    proven: 0,
+    weak: 0,
+    missing: 0,
+    untestable: 0,
+    unrecorded: 0,
+    total,
+  };
+  for (const criterion of ledger.criteria) summary[criterion.verdict] += 1;
+  summary.unrecorded =
+    total - (summary.proven + summary.weak + summary.missing + summary.untestable);
+  return summary;
+}
+
+function cell(value) {
+  return (
+    value
+      .replace(/\|/g, '\\|')
+      .replace(/\s*\n\s*/g, ' ')
+      .trim() || '-'
+  );
+}
+
+function list(values) {
+  return values.length > 0 ? cell(values.join(', ')) : '-';
+}
+
+function renderAcceptanceCoverage(ledger, criteria = ledger.criteria) {
+  const summary = summarizeAcceptanceStatus(ledger, criteria);
+  const rows = acceptanceCriteriaView(criteria, ledger);
+  const untestable = ledger.criteria
+    .filter((criterion) => criterion.verdict === 'untestable')
+    .map((criterion) => criterion.id);
+  const lines = [
+    '## Recipe coverage',
+    '',
+    '| AC | Criterion | Verdict | Proof mode | Recipe nodes | Evidence | Note |',
+    '| --- | --- | --- | --- | --- | --- | --- |',
+  ];
+  for (const row of rows) {
+    const status = row.status;
+    lines.push(
+      `| ${row.id} | ${cell(row.text)} | ${status ? status.verdict.toUpperCase() : 'NO VERDICT'} | ` +
+        `${status?.proofMode ?? '-'} | ${list(status?.recipeNodes ?? [])} | ` +
+        `${list(status?.evidence ?? [])} | ${cell(status?.note ?? '')} |`,
+    );
+  }
+  lines.push(
+    '',
+    `Overall recipe coverage: ${summary.proven}/${summary.total} ACs PROVEN ` +
+      `(untestable: ${untestable.length > 0 ? untestable.join(', ') : 'none'}, ` +
+      `weak: ${summary.weak}, missing: ${summary.missing}` +
+      `${summary.unrecorded > 0 ? `, no verdict: ${summary.unrecorded}` : ''})`,
+    '',
+  );
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// task-dir IO
+
+function ledgerPath(taskDir) {
+  return path.join(taskDir, ACCEPTANCE_STATUS_ARTIFACT);
+}
+
+/**
+ * The criteria task init recorded, as `{ id, text }` in handoff order. An empty
+ * array means this run has no acceptance criteria, so the ledger does not apply.
+ */
+function handoffAcceptanceCriteria(taskDir) {
+  return criteriaFromHandoff(readJson(path.join(taskDir, HANDOFF_INPUT)));
+}
+
+/** The `AC-<N>` list a parsed handoff carries; positions are the ids. */
+function criteriaFromHandoff(handoff) {
+  const task = isRecord(handoff.task) ? handoff.task : {};
+  const criteria = Array.isArray(task.acceptanceCriteria) ? task.acceptanceCriteria : [];
+  return criteria
+    .map((text, index) => ({ id: acceptanceCriterionId(index), text: String(text) }))
+    .filter((criterion) => criterion.text.trim().length > 0);
+}
+
+/**
+ * Same read, for the path that enforces the ledger. A missing handoff means no
+ * criteria, as ENOENT does everywhere; anything else — unreadable file, invalid
+ * JSON, a non-array `acceptanceCriteria` — refuses, because a task whose criteria
+ * cannot be read has not proven them. The permissive reader above still serves
+ * `ac list` / `ac render`, where a broken handoff is the CLI's own refusal.
+ *
+ * The gateway's terminal check applies the identical rule from the slot, so a
+ * signal written around this engine cannot pass what `mark` refuses.
+ */
+function requireHandoffAcceptanceCriteria(taskDir) {
+  let handoff;
+  try {
+    handoff = readJson(path.join(taskDir, HANDOFF_INPUT));
+  } catch (err) {
+    throw new AcceptanceRefusal(handoffReadRefusal(`invalid ${HANDOFF_INPUT}: ${err.message}`));
+  }
+  const task = isRecord(handoff.task) ? handoff.task : {};
+  if (task.acceptanceCriteria !== undefined && !Array.isArray(task.acceptanceCriteria)) {
+    throw new AcceptanceRefusal(
+      handoffReadRefusal(`invalid ${HANDOFF_INPUT}: task.acceptanceCriteria must be an array`),
+    );
+  }
+  // One parse: the handoff read above is the only one this path makes.
+  return criteriaFromHandoff(handoff);
+}
+
+/** One message shape for a handoff the acceptance rule cannot read. */
+function handoffReadRefusal(detail) {
+  return (
+    `cannot complete: ${detail}. The acceptance criteria (ADR-060) come from that file, so ` +
+    `nothing can tell whether every criterion has a verdict. Restore ${HANDOFF_INPUT} from the ` +
+    `orchestrator copy, then run ./mark complete again.`
+  );
+}
+
+/** The stored ledger, or null when the run has not written one yet. */
+function readAcceptanceLedger(taskDir) {
+  const file = ledgerPath(taskDir);
+  if (!fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, 'utf8');
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw new AcceptanceRefusal(`${ACCEPTANCE_STATUS_ARTIFACT}: invalid JSON (${err.message})`);
+  }
+}
+
+function writeAcceptanceLedger(taskDir, ledger) {
+  const issues = validateAcceptanceStatusLedger(ledger);
+  if (issues.length > 0) {
+    throw new AcceptanceRefusal(
+      `refusing to write an invalid ${ACCEPTANCE_STATUS_ARTIFACT}:\n- ${issues.join('\n- ')}`,
+    );
+  }
+  atomicWrite(ledgerPath(taskDir), `${JSON.stringify(ledger, null, 2)}\n`, 0o644);
+}
+
+/** Task-dir relative evidence path, refused when it escapes the dir or is missing. */
+function assertEvidencePath(taskDir, rawPath) {
+  const normalized = rawPath.replace(/\\/g, '/').replace(/^\.\/+/, '');
+  if (!normalized || path.posix.isAbsolute(normalized) || path.isAbsolute(rawPath)) {
+    throw new AcceptanceRefusal(`evidence path must be relative to the task dir: ${rawPath}`);
+  }
+  if (normalized.split('/').some((segment) => segment === '..')) {
+    throw new AcceptanceRefusal(`evidence path must stay inside the task dir: ${rawPath}`);
+  }
+  if (!fs.existsSync(path.join(taskDir, normalized))) {
+    throw new AcceptanceRefusal(`evidence path does not exist: ${normalized}`);
+  }
+  return normalized;
+}
+
+/**
+ * Record one verdict. The criterion must be one task init registered: the ledger
+ * carries exactly the handoff ids, never an id the worker made up.
+ */
+function setAcceptanceVerdict(taskDir, input) {
+  const criteria = handoffAcceptanceCriteria(taskDir);
+  if (criteria.length === 0) {
+    throw new AcceptanceRefusal(
+      `${HANDOFF_INPUT} lists no acceptance criteria; there is no ledger to write`,
+    );
+  }
+  const criterion = criteria.find((entry) => entry.id === input.id);
+  if (!criterion) {
+    throw new AcceptanceRefusal(
+      `unknown acceptance criterion ${input.id}; ${HANDOFF_INPUT} lists ${criteria
+        .map((entry) => entry.id)
+        .join(', ')}`,
+    );
+  }
+  if (!ACCEPTANCE_VERDICTS.includes(input.verdict)) {
+    throw new AcceptanceRefusal(
+      `unknown verdict ${input.verdict}; expected one of ${ACCEPTANCE_VERDICTS.join(', ')}`,
+    );
+  }
+  if (input.proofMode !== undefined && !ACCEPTANCE_PROOF_MODES.includes(input.proofMode)) {
+    throw new AcceptanceRefusal(
+      `unknown proof mode ${input.proofMode}; expected one of ${ACCEPTANCE_PROOF_MODES.join(', ')}`,
+    );
+  }
+  const evidence = (input.evidence ?? []).map((entry) => assertEvidencePath(taskDir, entry));
+  const stored = readAcceptanceLedger(taskDir);
+  if (stored) {
+    const issues = validateAcceptanceStatusLedger(stored);
+    if (issues.length > 0) {
+      throw new AcceptanceRefusal(
+        `${ACCEPTANCE_STATUS_ARTIFACT} does not match the ledger contract:\n- ${issues.join('\n- ')}`,
+      );
+    }
+  }
+  const byId = new Map((stored?.criteria ?? []).map((entry) => [entry.id, entry]));
+  byId.set(criterion.id, {
+    id: criterion.id,
+    text: criterion.text,
+    verdict: input.verdict,
+    ...(input.proofMode ? { proofMode: input.proofMode } : {}),
+    evidence,
+    recipeNodes: [...(input.recipeNodes ?? [])],
+    ...(input.note ? { note: input.note } : {}),
+    updatedAt: input.now ?? new Date().toISOString(),
+  });
+  // Handoff order, so the ledger and the rendered table always read like TASK.md.
+  const ledger = {
+    schemaVersion: 1,
+    criteria: criteria.map((entry) => byId.get(entry.id)).filter(Boolean),
+  };
+  writeAcceptanceLedger(taskDir, ledger);
+  return ledger;
+}
+
+/** Every handoff criterion with its current verdict, or null when unrecorded. */
+function acceptanceStatusList(taskDir) {
+  const stored = readAcceptanceLedger(taskDir);
+  const byId = new Map((stored?.criteria ?? []).map((entry) => [entry.id, entry]));
+  return handoffAcceptanceCriteria(taskDir).map((criterion) => {
+    const entry = byId.get(criterion.id);
+    return {
+      id: criterion.id,
+      text: criterion.text,
+      verdict: entry ? entry.verdict : null,
+      ...(entry?.proofMode ? { proofMode: entry.proofMode } : {}),
+      evidence: entry?.evidence ?? [],
+      recipeNodes: entry?.recipeNodes ?? [],
+      ...(entry?.note ? { note: entry.note } : {}),
+      updatedAt: entry?.updatedAt ?? null,
+    };
+  });
+}
+
+/**
+ * Terminal-contract issues for the ledger: every registered criterion needs a
+ * verdict, and `weak` or `missing` fails unless the flow's contract waives it
+ * (`acceptance.allowWeak`). Returns an empty array when the run has no criteria.
+ */
+function acceptanceContractIssues(taskDir, options = {}) {
+  const criteria = handoffAcceptanceCriteria(taskDir);
+  if (criteria.length === 0) return [];
+  let stored;
+  try {
+    stored = readAcceptanceLedger(taskDir);
+  } catch (err) {
+    if (!(err instanceof AcceptanceRefusal)) throw err;
+    return [err.message];
+  }
+  if (!stored) {
+    return [
+      `${ACCEPTANCE_STATUS_ARTIFACT} is missing but ${HANDOFF_INPUT} lists ${criteria.length} ` +
+        'acceptance criteria — record a verdict for each with `farmslot-agent ac set <id> <verdict>`',
+    ];
+  }
+  const issues = validateAcceptanceStatusLedger(stored);
+  if (issues.length > 0) return issues;
+  const known = new Set(criteria.map((criterion) => criterion.id));
+  for (const entry of stored.criteria) {
+    if (!known.has(entry.id)) {
+      issues.push(
+        `${ACCEPTANCE_STATUS_ARTIFACT}: ${entry.id} is not an acceptance criterion of this task`,
+      );
+    }
+  }
+  const byId = new Map(stored.criteria.map((entry) => [entry.id, entry]));
+  for (const criterion of criteria) {
+    const entry = byId.get(criterion.id);
+    if (!entry) {
+      issues.push(
+        `${criterion.id} has no verdict — run \`farmslot-agent ac set ${criterion.id} <verdict>\``,
+      );
+      continue;
+    }
+    if (!options.allowWeak && (entry.verdict === 'missing' || entry.verdict === 'weak')) {
+      issues.push(
+        `${criterion.id} is ${entry.verdict}: prove it, or record \`untestable\` with a note ` +
+          '(a flow may waive this with worker_terminal.acceptance.allowWeak)',
+      );
+    }
+  }
+  return issues;
+}
+
+module.exports = {
+  ACCEPTANCE_CRITERION_ID_PATTERN,
+  acceptanceCriteriaView,
+  ACCEPTANCE_PROOF_MODES,
+  ACCEPTANCE_STATUS_ARTIFACT,
+  ACCEPTANCE_VERDICTS,
+  AcceptanceRefusal,
+  acceptanceContractIssues,
+  acceptanceCriterionId,
+  acceptanceStatusList,
+  handoffAcceptanceCriteria,
+  requireHandoffAcceptanceCriteria,
+  readAcceptanceLedger,
+  renderAcceptanceCoverage,
+  setAcceptanceVerdict,
+  summarizeAcceptanceStatus,
+  validateAcceptanceStatusLedger,
+  writeAcceptanceLedger,
+};

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

@@ -6,6 +6,8 @@ import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
 const { expandedArtifactsForCommand } = require('./worker-terminal-contract.cjs');
+const { SUBTASK_INDEX_REL, openSubtaskUnits } = require('./subtask-unit.cjs');
+const { acceptanceContractIssues } = require('./acceptance-ledger.cjs');
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const workspaceProtocolRoot = path.resolve(packageRoot, '../protocol');
 
@@ -102,7 +104,7 @@ for (let i = 0; i < rawArgs.length; i += 1) {
 
 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]',
+    '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-acceptance-status] [--require-learnings] [--skip-learnings]',
   );
   process.exit(2);
 }
@@ -673,6 +675,28 @@ if (!isSelfReviewTerminal) {
   }
 }
 
+// A registered child unit is part of the parent's proof: the parent cannot
+// report success while a child checklist is still running or blocked.
+if (fileExists(SUBTASK_INDEX_REL)) {
+  for (const { unit, status } of openSubtaskUnits(taskDir)) {
+    issues.push(
+      `${unit.checklist}: subtask ${unit.id} is not settled (status ${status ?? 'no signal'}) — ` +
+        `finish it with ./mark sub ${unit.id} complete`,
+    );
+  }
+}
+
+// The acceptance ledger is the run's proof record (ADR-060): every criterion task
+// init registered in inputs/handoff.json needs a verdict, and `weak` / `missing`
+// fails unless the flow's terminal contract waives it.
+if (flags.has('--require-acceptance-status')) {
+  for (const issue of acceptanceContractIssues(taskDir, {
+    allowWeak: terminalContract?.acceptance?.allowWeak === true,
+  })) {
+    issues.push(issue);
+  }
+}
+
 if (flags.has('--require-learnings')) {
   const learnings = readText('artifacts/learnings.md');
   if (!learnings?.trim()) {

package/scripts/checklist-target.cjs

@@ -9,6 +9,11 @@ const INTERACTIVE_CHECKLIST_MARKDOWN = 'CHECKLIST.md';
 const WORKER_SIGNAL_FILE = 'SIGNAL.json';
 const ROLE_SIGNAL_SUFFIX = '-SIGNAL.json';
 
+// Child checklist units (ADR-060): one directory, one index, slug ids.
+const SUBTASKS_DIR = 'subtasks';
+const SUBTASK_INDEX_FILE = 'index.json';
+const SUBTASK_ID_PATTERN = /^[a-z0-9-]+$/;
+
 const SELF_REVIEW_CHECKLIST = 'SELF-REVIEW.md';
 const SELF_REVIEW_FIX_CHECKLIST = 'SELF-REVIEW-FIX.md';
 const CI_FIX_CHECKLIST = 'CI-FIX.md';
@@ -81,8 +86,29 @@ function enumerateChecklistCheckboxes(markdown) {
   }
   return items;
 }
+// Mirror of @farmslot/protocol/checklist-target checklistNumberingMismatches:
+// a label carrying explicit numbering must match its enumerated position, or an
+// inserted row silently shifts every later step onto the wrong box.
+function checklistNumberingMismatches(markdown) {
+  const mismatches = [];
+  for (const item of enumerateChecklistCheckboxes(markdown)) {
+    const labeled = item.rawLabel.match(/^\*{0,2}(\d+[a-z]?)[.)]/i);
+    if (labeled && labeled[1] !== String(item.stepNumber)) {
+      mismatches.push(`position ${item.stepNumber} is labeled "${labeled[1]}"`);
+    }
+  }
+  return mismatches;
+}
+
 const WORKER_TERMINAL_CONTRACT_INPUT = path.join('inputs', 'worker-terminal-contract.json');
 
+// checklistStepName — mirror of the protocol rule for the name a step is shown
+// under: the bold lead, numbering kept, instructions dropped. `mark` records it
+// in SIGNAL.json so events and every step view name a row the same way.
+function checklistStepName(rawLabel) {
+  return rawLabel.replace(/^\*\*(.+?)\*\*.*$/, '$1').trim();
+}
+
 function signalFileForChecklist(checklistBasename) {
   if (
     checklistBasename === TASK_PROGRESS_MARKDOWN ||
@@ -94,6 +120,37 @@ function signalFileForChecklist(checklistBasename) {
   return `${base}${ROLE_SIGNAL_SUFFIX}`;
 }
 
+// Mirror of @farmslot/protocol/transport/signal isSettledSubtaskStatus. NOT the
+// terminal predicate: a `blocked` child keeps ownership of its parent step.
+const WORKER_SIGNAL_STATUS_IS_SETTLED = {
+  running: false,
+  blocked: false,
+  complete: true,
+  failed: false,
+  done: true,
+};
+
+function isSettledSubtaskStatus(status) {
+  return (
+    status !== null &&
+    status !== undefined &&
+    Object.hasOwn(WORKER_SIGNAL_STATUS_IS_SETTLED, status) &&
+    WORKER_SIGNAL_STATUS_IS_SETTLED[status]
+  );
+}
+
+/**
+ * Task-dir relative paths of a child unit pair. Mirror of the protocol
+ * `subtaskPaths`: the signal basename comes from signalFileForChecklist, only
+ * the `subtasks/` prefix is new.
+ */
+function subtaskPaths(id) {
+  return {
+    checklist: `${SUBTASKS_DIR}/${id}.md`,
+    signal: `${SUBTASKS_DIR}/${signalFileForChecklist(`${id}.md`)}`,
+  };
+}
+
 function taskDirRelPath(taskDir, basename) {
   const normalized = String(taskDir).replace(/\/+$/, '');
   return `${normalized}/${basename}`;
@@ -268,7 +325,14 @@ function resolveChecklistPaths(taskDir) {
 
 module.exports = {
   CHECKLIST_SKIP_SECTIONS,
+  checklistStepName,
+  checklistNumberingMismatches,
   enumerateChecklistCheckboxes,
+  SUBTASKS_DIR,
+  SUBTASK_INDEX_FILE,
+  SUBTASK_ID_PATTERN,
+  isSettledSubtaskStatus,
+  subtaskPaths,
   CHECKLIST_TARGET_MANIFEST,
   TASK_PROGRESS_MARKDOWN,
   INTERACTIVE_CHECKLIST_MARKDOWN,