@farmslot/skills 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -4,4 +4,19 @@ All notable changes to `@farmslot/skills` are tracked here.
 
 ## Unreleased
 
+- Active-development baseline; add user-facing changes here before release or package publication.
+
+## 0.1.2 - 2026-07-03
+
+- Colocate finish-contract scripts in `packages/skills/scripts/` (`mark-checklist-step.cjs`, `worker-terminal-contract.cjs`, `check-task-artifact-contract.mjs`) as the canonical source for `@farmslot/skills` and consensys-skills delegation
+- **dev / fix-bug:** terminal `./mark complete` requires `artifacts/learnings.md` + `artifacts/pr-description.md` (not `report.md`)
+- `./mark` infers dev/fix-bug flow from embedded checklist `Skill:` header (standalone recipe skills)
+- Export `./scripts/worker-terminal-contract.cjs` and `./scripts/check-task-artifact-contract.mjs` from the package
+
+## 0.1.1 - 2026-06-30
+
+- Single-path mark CLI for worker terminal signals.
+
+## 0.1.0 - 2026-06-28
+
 - Add the generic recipe-first skills package and migrate the former top-level recipe cooking kit into `skills/recipe-cook`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arthur Breton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -6,7 +6,7 @@ Public guide: https://farmslot.io/docs/guides/recipe-skills-adoption
 
 ## What This Package Is
 
-`@farmslot/skills` is the recipe-first adoption kit. It teaches an agent how to write, review, diagnose, and adopt validation recipes before a team installs the full Farmslot OS.
+`@farmslot/skills` is the recipe-first adoption kit. It teaches an agent how to write, review, diagnose, and adopt validation recipes before a team installs the full Farmslot framework.
 
 It does not require Gateway, Command Center, a pool file, slots, or Companion for first use.
 
@@ -49,7 +49,7 @@ Supported layouts:
 2. Recipe runner: add a local command that can execute one recipe and emit artifacts.
 3. Project recipe layer: add recipes, runner manifests, project actions, and artifact conventions.
 4. Farmslot project integration: add `project.json` hooks for Command Center and slots.
-5. Full OS: adopt multi-slot dispatch, live steering, Companion supervision, and retrospectives.
+5. Full framework: adopt multi-slot dispatch, live steering, Companion supervision, and retrospectives.
 
 ## Source layout
 
@@ -61,6 +61,7 @@ Supported layouts:
 
 ## Maintenance rules
 
+- `scripts/mark-checklist-step.cjs` mirrors consensys-skills `recipe-harness/scripts/mark-checklist-step.cjs`. Edit the recipe-harness copy first; sync the mirror before shipping Farmslot gateway or npm changes.
 - Keep package payloads self-contained; consumers should not need the Farmslot monorepo.
 - Update `CHANGELOG.md` before packaging or publishing.
 - Run the package readiness guard when files move, bins change, or exports are added.
@@ -72,3 +73,7 @@ yarn workspace @farmslot/skills build
 yarn workspace @farmslot/skills test
 node scripts/quality/check-farmslot-package-readiness.mjs --packages @farmslot/skills
 ```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/bin/farmslot-checklist.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../scripts/mark-checklist-step.cjs';

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@farmslot/skills",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
+    "farmslot-checklist": "./bin/farmslot-checklist.mjs",
     "farmslot-skills": "./bin/farmslot-skills.mjs"
   },
   "exports": {
@@ -14,11 +15,14 @@
       "default": "./dist/index.js"
     },
     "./skills/*": "./skills/*/SKILL.md",
-    "./schemas/*": "./schemas/*"
+    "./schemas/*": "./schemas/*",
+    "./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": "tsc --noEmit --project tsconfig.json",
-    "test": "node test/prepare-cooking-run.test.cjs && node test/run-cooking-lane.test.cjs && node test/validator-loop.test.cjs && node test/package-exports.test.cjs",
+    "test": "node test/mark-checklist-step.test.cjs && node test/prepare-cooking-run.test.cjs && node test/run-cooking-lane.test.cjs && node test/validator-loop.test.cjs && node test/package-exports.test.cjs",
     "format": "prettier --write --ignore-path ../../.prettierignore .",
     "format:check": "prettier --check --ignore-path ../../.prettierignore .",
     "lint": "eslint \"src/**/*.ts\"",
@@ -53,6 +57,7 @@
   ],
   "files": [
     "README.md",
+    "LICENSE",
     "CHANGELOG.md",
     "bin/**/*.mjs",
     "dist/**/*.js",
@@ -61,6 +66,7 @@
     "dist/**/*.js.map",
     "schemas/**/*.json",
     "scripts/**/*.cjs",
+    "scripts/**/*.mjs",
     "skills/**/*.md",
     "templates/**/*.json"
   ],

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

@@ -0,0 +1,310 @@
+#!/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');
+
+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 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 (artifact.version !== 1) issues.push('recipe-quality.json: version must be 1');
+  if (!['pass', 'warn', 'fail'].includes(artifact.verdict)) {
+    issues.push('recipe-quality.json: verdict must be pass, warn, or fail');
+  }
+  if (!isRecord(artifact.compact) || !['PASS', 'WARN', 'FAIL'].includes(artifact.compact.verdict)) {
+    issues.push('recipe-quality.json: compact.verdict must be PASS, WARN, or FAIL');
+  }
+}
+
+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');

package/scripts/mark-checklist-step.cjs

@@ -0,0 +1,488 @@
+#!/usr/bin/env node
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const {
+  expandedArtifactsForCommand,
+  resolveWorkerTerminalContract,
+} = require('./worker-terminal-contract.cjs');
+
+const START_COMMANDS = new Set(['start']);
+const TERMINAL_COMMANDS = new Set(['complete', 'no-change', 'blocked']);
+const NO_CHANGE_REPORT = path.join('artifacts', 'no-change-report.md');
+const LEARNINGS_ARTIFACT = path.join('artifacts', 'learnings.md');
+const ARTIFACT_CONTRACT_SCRIPT = path.resolve(__dirname, 'check-task-artifact-contract.mjs');
+
+const FLOW_REPORT_ARTIFACTS = {
+  'fix-bug': ['pr-description.md', 'report.md'],
+  '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'],
+};
+const FALLBACK_REPORT_ARTIFACTS = [
+  'report.md',
+  'review.md',
+  'comments-report.md',
+  'merge-report.md',
+];
+
+const usageLine =
+  'usage: mark <step-number|start|complete|no-change|blocked> [--reason text] [--already-fixed] [--mark-last] [--no-self-review] [--skip-learnings] [--skip-checklist]';
+
+function printHelp() {
+  console.log(
+    [
+      usageLine,
+      '',
+      'Bootstrap: ./mark start — worker-owned SIGNAL.json 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]',
+      '  ./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.',
+      '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'),
+  );
+}
+
+function usage() {
+  console.error(usageLine);
+  console.error('run ./mark --help for details');
+  process.exit(2);
+}
+
+const args = process.argv.slice(2);
+if (args.length === 1 && (args[0] === '--help' || args[0] === '-h')) {
+  printHelp();
+  process.exit(0);
+}
+
+const [taskPath, signalPath, stepRaw, ...rest] = args;
+if (stepRaw === '--help' || stepRaw === '-h') {
+  printHelp();
+  process.exit(0);
+}
+if (!taskPath || !signalPath || !stepRaw) usage();
+
+const opts = {};
+for (let i = 0; i < rest.length; i += 1) {
+  const key = rest[i];
+  if (
+    key === '--mark-last' ||
+    key === '--already-fixed' ||
+    key === '--no-self-review' ||
+    key === '--skip-learnings' ||
+    key === '--skip-checklist'
+  ) {
+    opts[key.slice(2)] = true;
+    continue;
+  }
+  const value = rest[i + 1];
+  if (!key?.startsWith('--') || value === undefined) usage();
+  opts[key.slice(2)] = value;
+  i += 1;
+}
+
+const stepToken = String(stepRaw).toLowerCase();
+const isStartCommand = START_COMMANDS.has(stepToken);
+const terminalCommand = TERMINAL_COMMANDS.has(stepToken) ? stepToken : null;
+let stepNumber = null;
+if (!isStartCommand && !terminalCommand) {
+  stepNumber = Number(stepRaw);
+  if (!Number.isInteger(stepNumber) || stepNumber < 1) usage();
+}
+
+if (isStartCommand && Object.keys(opts).length > 0) usage();
+if (terminalCommand === 'no-change' || terminalCommand === 'blocked') {
+  if (!opts.reason?.trim()) {
+    console.error(`${terminalCommand} requires --reason`);
+    process.exit(1);
+  }
+}
+
+const SIGNAL_PASSTHROUGH_KEYS = ['role', 'contextId', 'prNumber'];
+
+function pickSignalPassthrough(signal) {
+  const out = {};
+  for (const key of SIGNAL_PASSTHROUGH_KEYS) {
+    if (signal[key] !== undefined) out[key] = signal[key];
+  }
+  return out;
+}
+
+function resolveTerminalPreset(command) {
+  switch (command) {
+    case 'complete':
+      return { status: 'complete', outcome: 'success', disposition: 'fixed' };
+    case 'no-change':
+      return {
+        status: 'complete',
+        outcome: 'success',
+        disposition: opts['already-fixed'] ? 'already_fixed' : 'not_reproducible',
+      };
+    case 'blocked':
+      return { status: 'blocked', outcome: 'partial', disposition: 'blocked' };
+    default:
+      usage();
+      return null;
+  }
+}
+
+function loadTerminalContract(taskDir, taskPath) {
+  const contractPath = path.join(taskDir, 'inputs', 'worker-terminal-contract.json');
+  if (fs.existsSync(contractPath)) {
+    return JSON.parse(fs.readFileSync(contractPath, 'utf8'));
+  }
+  const flowType = inferFlowType(taskPath);
+  return flowType ? resolveWorkerTerminalContract(null, flowType) : null;
+}
+
+function taskFileExists(taskDir, storedPath) {
+  try {
+    return fs.statSync(path.join(taskDir, storedPath)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function assertArtifactFile(taskDir, storedPath) {
+  const abs = path.join(taskDir, storedPath);
+  if (!fs.existsSync(abs)) {
+    console.error(`missing required artifact: ${storedPath}`);
+    process.exit(1);
+  }
+  if (storedPath.endsWith('.md')) {
+    const text = fs.readFileSync(abs, 'utf8').trim();
+    if (!text) {
+      console.error(`${storedPath} exists but is empty`);
+      process.exit(1);
+    }
+  }
+}
+
+function assertRequiredArtifacts(taskDir, terminalCommand, contract) {
+  if (!contract) return;
+  const expanded = expandedArtifactsForCommand(contract, terminalCommand, (rel) =>
+    taskFileExists(taskDir, rel),
+  );
+  for (const storedPath of expanded.artifacts) {
+    if (storedPath === LEARNINGS_ARTIFACT && opts['skip-learnings']) continue;
+    assertArtifactFile(taskDir, storedPath);
+  }
+}
+
+function assertNoChangeReport(taskDir) {
+  const reportAbs = path.join(taskDir, NO_CHANGE_REPORT);
+  if (!fs.existsSync(reportAbs) || fs.statSync(reportAbs).size === 0) {
+    console.error(`missing required report: ${NO_CHANGE_REPORT}`);
+    process.exit(1);
+  }
+  return NO_CHANGE_REPORT;
+}
+
+function assertLearningsArtifact(taskDir) {
+  const learningsAbs = path.join(taskDir, LEARNINGS_ARTIFACT);
+  if (!fs.existsSync(learningsAbs)) {
+    console.error(`missing required artifact: ${LEARNINGS_ARTIFACT}`);
+    process.exit(1);
+  }
+  const text = fs.readFileSync(learningsAbs, 'utf8').trim();
+  if (!text) {
+    console.error(`${LEARNINGS_ARTIFACT} exists but is empty — write at least one bullet`);
+    process.exit(1);
+  }
+  return LEARNINGS_ARTIFACT;
+}
+
+function readArtifactText(taskDir, relativePath) {
+  const artifactAbs = path.join(taskDir, 'artifacts', relativePath);
+  if (!fs.existsSync(artifactAbs)) return null;
+  const text = fs.readFileSync(artifactAbs, 'utf8').trim();
+  return text || null;
+}
+
+function inferFlowType(taskPath) {
+  let head = '';
+  try {
+    head = fs.readFileSync(taskPath, 'utf8').split('\n').slice(0, 24).join('\n');
+  } catch {
+    return null;
+  }
+  const workerMatch = head.match(/^#\s*Worker:\s*([^\n—-]+)/im);
+  if (workerMatch) {
+    const label = workerMatch[1].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('interactive dev')) return 'dev';
+    if (/\bdev\b/.test(label) && !label.includes('review')) return 'dev';
+  }
+  return null;
+}
+
+function assertWorkerReport(taskDir, taskPath) {
+  const flowType = inferFlowType(taskPath);
+  const candidates = flowType
+    ? (FLOW_REPORT_ARTIFACTS[flowType] ?? FALLBACK_REPORT_ARTIFACTS)
+    : FALLBACK_REPORT_ARTIFACTS;
+  const found = candidates.find((name) => readArtifactText(taskDir, name));
+  if (found) return `artifacts/${found}`;
+  console.error(
+    `missing required worker report — expected non-empty artifacts/{${candidates.join(', ')}}`,
+  );
+  process.exit(1);
+  return null;
+}
+
+function assertChecklistComplete(taskPath, { allowOneUnchecked = false } = {}) {
+  const parsed = parseChecklist(fs.readFileSync(taskPath, 'utf8'));
+  const unchecked = parsed.items.filter((entry) => !entry.checked);
+  if (unchecked.length === 0) return;
+  if (allowOneUnchecked && unchecked.length === 1) return;
+  const summary = unchecked
+    .slice(0, 5)
+    .map((entry) => `${entry.stepNumber}:${entry.label}`)
+    .join('; ');
+  console.error(
+    `checklist incomplete — ${unchecked.length} step(s) still [ ] (${summary}${unchecked.length > 5 ? '; …' : ''})`,
+  );
+  process.exit(1);
+}
+
+function assertArtifactContract(taskDir, contract, terminalCommand) {
+  if (!fs.existsSync(ARTIFACT_CONTRACT_SCRIPT)) {
+    console.error(`missing artifact contract script: ${ARTIFACT_CONTRACT_SCRIPT}`);
+    process.exit(1);
+  }
+  const contractPath = path.join(taskDir, 'inputs', 'worker-terminal-contract.json');
+  const args = [ARTIFACT_CONTRACT_SCRIPT, taskDir];
+  if (fs.existsSync(contractPath)) {
+    args.push('--contract', contractPath);
+    if (terminalCommand) args.push('--terminal', terminalCommand);
+    if (opts['skip-learnings']) args.push('--skip-learnings');
+  } else {
+    if (!opts['skip-learnings']) 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');
+    }
+  }
+  const result = spawnSync(process.execPath, args, { encoding: 'utf8' });
+  if (result.status !== 0) {
+    if (result.stderr) process.stderr.write(result.stderr);
+    if (result.stdout) process.stdout.write(result.stdout);
+    process.exit(result.status ?? 1);
+  }
+}
+
+function assertTerminalPackagedEvidence(taskPath, taskDir, terminalCommand) {
+  if (terminalCommand === 'blocked') return;
+
+  const contract = loadTerminalContract(taskDir, taskPath);
+  if (contract) {
+    assertRequiredArtifacts(taskDir, terminalCommand, contract);
+    assertArtifactContract(taskDir, contract, terminalCommand);
+    return;
+  }
+
+  if (terminalCommand === 'no-change') {
+    assertNoChangeReport(taskDir);
+  } else if (terminalCommand === 'complete') {
+    assertWorkerReport(taskDir, taskPath);
+  }
+
+  if (!opts['skip-learnings']) {
+    assertLearningsArtifact(taskDir);
+  }
+
+  if (terminalCommand === 'complete' || terminalCommand === 'no-change') {
+    assertArtifactContract(taskDir);
+  }
+}
+
+function buildSignalUpdate(signal, terminal, target, timing, events, now, taskPath, _taskDir) {
+  const base = {
+    ...pickSignalPassthrough(signal),
+    step: target?.label ?? signal.step ?? 'complete',
+    checklistTiming: {
+      schemaVersion: 1,
+      source: timing.source || path.basename(taskPath),
+      events,
+    },
+    timestamp: now,
+  };
+
+  if (!terminal) {
+    return { ...base, status: 'running' };
+  }
+
+  const preset = resolveTerminalPreset(terminal.command);
+  const next = {
+    ...base,
+    status: preset.status,
+    outcome: preset.outcome,
+    disposition: preset.disposition,
+    ...(opts.reason ? { reason: opts.reason } : {}),
+    ...(terminal.command === 'complete' && opts['no-self-review']
+      ? { needsSelfReview: false }
+      : {}),
+  };
+
+  const contract = terminal ? loadTerminalContract(_taskDir, taskPath) : null;
+  if (terminal.command === 'no-change') {
+    next.evidence = {
+      reportPath: contract?.commands?.['no-change']?.report ?? NO_CHANGE_REPORT,
+    };
+  } else if (terminal.command === 'complete') {
+    const reportPath = contract?.commands?.complete?.report;
+    if (reportPath) next.evidence = { reportPath };
+  }
+
+  return next;
+}
+
+function atomicWrite(file, content, mode) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.tmp`);
+  fs.writeFileSync(tmp, content, mode ? { mode } : undefined);
+  fs.renameSync(tmp, file);
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return {};
+    throw err;
+  }
+}
+
+function stripLabel(raw) {
+  return raw
+    .replace(/^\*\*(.*?)\*\*\s*[—-]?\s*/, '$1 ')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function parseChecklist(markdown) {
+  const lines = markdown.split(/\n/);
+  const items = [];
+  let inFence = false;
+  let seen = 0;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (/^\s*```/.test(lines[i])) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const match = lines[i].match(/^(\s*[-*]\s+\[)( |x|X)(\]\s+)(.*)$/);
+    if (!match) continue;
+    seen += 1;
+    items.push({
+      lineIndex: i,
+      stepNumber: seen,
+      checked: match[2].toLowerCase() === 'x',
+      prefix: match[1],
+      suffix: match[3],
+      rawLabel: match[4],
+      label: stripLabel(match[4]),
+    });
+  }
+  return { lines, items };
+}
+
+function markStepInLines(lines, item) {
+  if (item.checked) return false;
+  lines[item.lineIndex] = `${item.prefix}x${item.suffix}${item.rawLabel}`;
+  return true;
+}
+
+function resolveTarget(taskPath, stepNumber, markLast) {
+  const original = fs.readFileSync(taskPath, 'utf8');
+  const parsed = parseChecklist(original);
+  let item = null;
+  if (stepNumber != null) {
+    item = parsed.items.find((entry) => entry.stepNumber === stepNumber) ?? null;
+    if (!item) {
+      console.error(`checklist step ${stepNumber} not found in ${taskPath}`);
+      process.exit(1);
+    }
+  } else if (markLast) {
+    const unchecked = parsed.items.filter((entry) => !entry.checked);
+    item = unchecked.length ? unchecked[unchecked.length - 1] : null;
+  }
+  let updated = original;
+  if (item) {
+    const nextLines = [...parsed.lines];
+    markStepInLines(nextLines, item);
+    updated = nextLines.join('\n');
+    if (updated !== original) atomicWrite(taskPath, updated);
+  }
+  return item
+    ? { stepNumber: item.stepNumber, label: item.label }
+    : { stepNumber: null, label: 'complete' };
+}
+
+const taskDir = path.dirname(signalPath);
+if (
+  terminalCommand &&
+  (terminalCommand === 'complete' || terminalCommand === 'no-change') &&
+  opts['mark-last'] &&
+  !opts['skip-checklist']
+) {
+  assertChecklistComplete(taskPath, { allowOneUnchecked: true });
+}
+const target = isStartCommand
+  ? { stepNumber: null, label: 'started' }
+  : resolveTarget(taskPath, stepNumber, Boolean(terminalCommand && opts['mark-last']));
+
+const now = new Date().toISOString();
+const signal = readJson(signalPath);
+const timing =
+  signal.checklistTiming && typeof signal.checklistTiming === 'object'
+    ? signal.checklistTiming
+    : { schemaVersion: 1, source: path.basename(taskPath), events: [] };
+const events = Array.isArray(timing.events) ? [...timing.events] : [];
+
+if (
+  !isStartCommand &&
+  target.stepNumber != null &&
+  !events.some(
+    (event) =>
+      event && (event.stepNumber === target.stepNumber || event.index === target.stepNumber - 1),
+  )
+) {
+  events.push({ stepNumber: target.stepNumber, label: target.label, checkedAt: now });
+}
+
+if (terminalCommand) {
+  assertTerminalPackagedEvidence(taskPath, taskDir, terminalCommand);
+}
+
+const next = buildSignalUpdate(
+  signal,
+  terminalCommand ? { command: terminalCommand } : null,
+  target,
+  timing,
+  events,
+  now,
+  taskPath,
+  taskDir,
+);
+atomicWrite(signalPath, `${JSON.stringify(next, null, 2)}\n`, 0o644);
+
+if (isStartCommand) {
+  console.log('signal started');
+} else if (terminalCommand) {
+  console.log(
+    `signal ${terminalCommand}: status=${next.status} disposition=${next.disposition ?? 'n/a'}`,
+  );
+} else {
+  console.log(`marked ${target.stepNumber}: ${target.label}`);
+}

package/scripts/worker-terminal-contract.cjs

@@ -0,0 +1,382 @@
+/** @typedef {'complete' | 'no-change' | 'blocked'} WorkerTerminalCommand */
+
+/**
+ * @typedef {object} WorkerTerminalCommandSpec
+ * @property {string} [report]
+ * @property {string[]} artifacts
+ */
+
+/**
+ * @typedef {object} WorkerTerminalWhenPresentRule
+ * @property {string} path
+ * @property {string[]} alsoRequire
+ * @property {boolean} [requireRecipeQuality]
+ * @property {boolean} [requireRecipeCoverage]
+ */
+
+/**
+ * @typedef {object} WorkerTerminalProjectConfig
+ * @property {boolean} [requireSignal]
+ * @property {Partial<Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>>} [complete]
+ * @property {Partial<Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>>} [no-change]
+ * @property {Partial<Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>>} [blocked]
+ * @property {Record<string, Partial<Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>>>} [flows]
+ * @property {WorkerTerminalWhenPresentRule[]} [whenPresent]
+ */
+
+/**
+ * @typedef {object} WorkerTerminalContractDocument
+ * @property {1} schemaVersion
+ * @property {string} flowType
+ * @property {string} [mode]
+ * @property {boolean} requireSignal
+ * @property {Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>} commands
+ * @property {WorkerTerminalWhenPresentRule[]} whenPresent
+ * @property {string} resolvedAt
+ * @property {'builtin' | 'project'} source
+ */
+
+const TERMINAL_MARK_RE = /(?:\.\/|\{\{TASK_DIR\}\}\/)mark\s+(complete|no-change|blocked)\b/;
+const TERMINAL_COMMANDS = /** @type {const} */ (['complete', 'no-change', 'blocked']);
+
+const LEARNINGS = 'artifacts/learnings.md';
+
+const PR_DESCRIPTION = 'artifacts/pr-description.md';
+
+/** @type {Record<string, Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>>} */
+const BUILTIN_FLOW_COMMANDS = {
+  dev: {
+    complete: { report: PR_DESCRIPTION, artifacts: [LEARNINGS, PR_DESCRIPTION] },
+    'no-change': {
+      report: 'artifacts/no-change-report.md',
+      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
+    },
+    blocked: { artifacts: [] },
+  },
+  'fix-bug': {
+    complete: { report: PR_DESCRIPTION, artifacts: [LEARNINGS, PR_DESCRIPTION] },
+    'no-change': {
+      report: 'artifacts/no-change-report.md',
+      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
+    },
+    blocked: { artifacts: [] },
+  },
+  'review-pr': {
+    complete: {
+      report: 'artifacts/review.md',
+      artifacts: [LEARNINGS, 'artifacts/review.md', 'artifacts/line-comments.json'],
+    },
+    'no-change': {
+      report: 'artifacts/no-change-report.md',
+      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
+    },
+    blocked: { artifacts: [] },
+  },
+  'pr-complete': {
+    complete: {
+      report: 'artifacts/comments-report.md',
+      artifacts: [LEARNINGS, 'artifacts/comments-report.md'],
+    },
+    'no-change': {
+      report: 'artifacts/no-change-report.md',
+      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
+    },
+    blocked: { artifacts: [] },
+  },
+  'merge-main': {
+    complete: {
+      report: 'artifacts/report.md',
+      artifacts: [LEARNINGS, 'artifacts/report.md'],
+    },
+    'no-change': {
+      report: 'artifacts/no-change-report.md',
+      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
+    },
+    blocked: { artifacts: [] },
+  },
+  'ci-fix': {
+    complete: { report: 'artifacts/report.md', artifacts: [LEARNINGS, 'artifacts/report.md'] },
+    'no-change': {
+      report: 'artifacts/no-change-report.md',
+      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
+    },
+    blocked: { artifacts: [] },
+  },
+  'self-review': {
+    complete: { artifacts: [LEARNINGS] },
+    'no-change': {
+      report: 'artifacts/no-change-report.md',
+      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
+    },
+    blocked: { artifacts: [] },
+  },
+  'self-review-fix': {
+    complete: { report: 'artifacts/report.md', artifacts: [LEARNINGS, 'artifacts/report.md'] },
+    'no-change': {
+      report: 'artifacts/no-change-report.md',
+      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
+    },
+    blocked: { artifacts: [] },
+  },
+  'validate-dep': {
+    complete: { report: 'artifacts/report.md', artifacts: [LEARNINGS, 'artifacts/report.md'] },
+    'no-change': {
+      report: 'artifacts/no-change-report.md',
+      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
+    },
+    blocked: { artifacts: [] },
+  },
+};
+
+const DEFAULT_WHEN_PRESENT = [
+  {
+    path: 'artifacts/recipe.json',
+    alsoRequire: ['artifacts/recipe-coverage.md', 'artifacts/evidence-manifest.json'],
+    requireRecipeQuality: true,
+    requireRecipeCoverage: true,
+  },
+];
+
+const DEFAULT_BLOCKED = { artifacts: [] };
+const DEFAULT_NO_CHANGE = {
+  report: 'artifacts/no-change-report.md',
+  artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
+};
+const DEFAULT_COMPLETE = {
+  report: 'artifacts/report.md',
+  artifacts: [LEARNINGS, 'artifacts/report.md'],
+};
+
+/** @param {WorkerTerminalCommandSpec | undefined} spec */
+function normalizeCommandSpec(spec) {
+  if (!spec) return { artifacts: [] };
+  const artifacts = [...new Set((spec.artifacts ?? []).filter(Boolean))];
+  if (spec.report && !artifacts.includes(spec.report)) artifacts.unshift(spec.report);
+  return {
+    ...(spec.report ? { report: spec.report } : {}),
+    artifacts,
+  };
+}
+
+/** @param {Partial<Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>> | undefined} layer */
+function normalizeCommandLayer(layer) {
+  /** @type {Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>} */
+  const out = {
+    complete: normalizeCommandSpec(layer?.complete ?? DEFAULT_COMPLETE),
+    'no-change': normalizeCommandSpec(layer?.['no-change'] ?? DEFAULT_NO_CHANGE),
+    blocked: normalizeCommandSpec(layer?.blocked ?? DEFAULT_BLOCKED),
+  };
+  return out;
+}
+
+/**
+ * @param {WorkerTerminalProjectConfig | null | undefined} projectConfig
+ * @param {string} flowType
+ * @param {{ mode?: string | null, now?: string }} [options]
+ * @returns {WorkerTerminalContractDocument}
+ */
+function resolveWorkerTerminalContract(projectConfig, flowType, options = {}) {
+  const mode = options.mode ?? undefined;
+  const now = options.now ?? new Date().toISOString();
+  const flowKey = String(flowType || '').trim() || 'unknown';
+
+  const defaultsLayer = normalizeCommandLayer({
+    complete: projectConfig?.complete,
+    'no-change': projectConfig?.['no-change'],
+    blocked: projectConfig?.blocked,
+  });
+
+  const builtin = BUILTIN_FLOW_COMMANDS[flowKey];
+  const flowLayer = projectConfig?.flows?.[flowKey];
+  /** @type {Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>} */
+  const commands = {
+    complete: normalizeCommandSpec(
+      flowLayer?.complete ?? builtin?.complete ?? defaultsLayer.complete,
+    ),
+    'no-change': normalizeCommandSpec(
+      flowLayer?.['no-change'] ?? builtin?.['no-change'] ?? defaultsLayer['no-change'],
+    ),
+    blocked: normalizeCommandSpec(flowLayer?.blocked ?? builtin?.blocked ?? defaultsLayer.blocked),
+  };
+
+  let requireSignal = projectConfig?.requireSignal ?? true;
+  if (flowKey === 'pr-complete' && mode === 'interactive') {
+    requireSignal = false;
+  }
+
+  const whenPresent = Array.isArray(projectConfig?.whenPresent)
+    ? projectConfig.whenPresent.map((rule) => ({
+        path: rule.path,
+        alsoRequire: [...(rule.alsoRequire ?? [])],
+        ...(rule.requireRecipeQuality ? { requireRecipeQuality: true } : {}),
+        ...(rule.requireRecipeCoverage ? { requireRecipeCoverage: true } : {}),
+      }))
+    : DEFAULT_WHEN_PRESENT.map((rule) => ({ ...rule, alsoRequire: [...rule.alsoRequire] }));
+
+  return {
+    schemaVersion: 1,
+    flowType: flowKey,
+    ...(mode ? { mode } : {}),
+    requireSignal,
+    commands,
+    whenPresent,
+    resolvedAt: now,
+    source: projectConfig ? 'project' : 'builtin',
+  };
+}
+
+/** @param {string} content */
+function templateUsesTerminalMark(content) {
+  return (
+    TERMINAL_MARK_RE.test(content) ||
+    /mark-checklist-step\.cjs[\s\S]{0,400}?\bcomplete\b/.test(content)
+  );
+}
+
+/** @param {string} content */
+function templateTerminalCommands(content) {
+  let scope = content;
+  const checklistIdx = content.indexOf('## Checklist');
+  if (checklistIdx >= 0) {
+    scope = content.slice(checklistIdx);
+  } else {
+    const completionIdx = content.indexOf('## Completion signal');
+    if (completionIdx >= 0) scope = content.slice(completionIdx);
+    else {
+      const taskIdx = content.indexOf('## Task');
+      if (taskIdx >= 0) scope = content.slice(taskIdx);
+    }
+  }
+  const commands = new Set();
+  for (const match of scope.matchAll(
+    /(?:\.\/|\{\{TASK_DIR\}\}\/)mark\s+(complete|no-change|blocked)\b/g,
+  )) {
+    commands.add(match[1]);
+  }
+  if (commands.size === 0 && /mark-checklist-step\.cjs[\s\S]{0,400}?\bcomplete\b/.test(scope)) {
+    commands.add('complete');
+  }
+  return [...commands];
+}
+
+/**
+ * @param {string} templateContent
+ * @param {WorkerTerminalContractDocument} contract
+ */
+/** @param {string} content */
+function templateBodyScope(content) {
+  const checklistIdx = content.indexOf('## Checklist');
+  if (checklistIdx >= 0) return content.slice(checklistIdx);
+  const completionIdx = content.indexOf('## Completion signal');
+  if (completionIdx >= 0) return content.slice(completionIdx);
+  const taskIdx = content.indexOf('## Task');
+  if (taskIdx >= 0) return content.slice(taskIdx);
+  return content;
+}
+
+/**
+ * Deterministic structure checks beyond terminal artifact contract.
+ * @param {string} templateContent
+ */
+function lintWorkerTemplateStructure(templateContent) {
+  /** @type {string[]} */
+  const issues = [];
+  if (/(?<!\{)\{TASK_DIR\}(?!\})/.test(templateContent)) {
+    issues.push('uses `{TASK_DIR}` — must be `{{TASK_DIR}}` (double braces)');
+  }
+
+  if (
+    templateUsesTerminalMark(templateContent) &&
+    !templateContent.includes('## Checklist') &&
+    !templateContent.includes('## Completion signal')
+  ) {
+    issues.push('terminal template missing `## Checklist` or `## Completion signal` section');
+  }
+
+  if (!templateContent.includes('## Task') && !templateContent.includes('TASK_DIR:')) {
+    issues.push('missing `## Task` block or `TASK_DIR:` metadata');
+  }
+
+  const scope = templateBodyScope(templateContent);
+  const steps = [...scope.matchAll(/\*\*(\d+)\./g)].map((match) => match[1]);
+  const duplicateSteps = [...new Set(steps.filter((step, index) => steps.indexOf(step) !== index))];
+  if (duplicateSteps.length > 0) {
+    issues.push(`duplicate checklist step number(s): ${duplicateSteps.join(', ')}`);
+  }
+
+  return issues;
+}
+
+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)) {
+      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
+    }
+  }
+
+  const commands = templateTerminalCommands(templateContent);
+  const commandSet = new Set(commands.length > 0 ? commands : ['complete']);
+  for (const command of commandSet) {
+    const spec = contract.commands[/** @type {WorkerTerminalCommand} */ (command)];
+    if (!spec) continue;
+    for (const artifactPath of spec.artifacts) {
+      if (!templateContent.includes(artifactPath)) {
+        issues.push(
+          `missing checklist/reference to required artifact \`${artifactPath}\` for \`${command}\``,
+        );
+      }
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * @param {WorkerTerminalContractDocument} contract
+ * @param {WorkerTerminalCommand} command
+ * @param {(relPath: string) => boolean} fileExists
+ */
+function expandedArtifactsForCommand(contract, command, fileExists) {
+  const spec = contract.commands[command] ?? { artifacts: [] };
+  const required = new Set(spec.artifacts);
+  for (const rule of contract.whenPresent ?? []) {
+    if (!rule.path || !fileExists(rule.path)) continue;
+    for (const path of rule.alsoRequire ?? []) required.add(path);
+  }
+  return {
+    report: spec.report,
+    artifacts: [...required],
+    requireRecipeQuality: (contract.whenPresent ?? []).some(
+      (rule) => rule.path && fileExists(rule.path) && rule.requireRecipeQuality,
+    ),
+    requireRecipeCoverage: (contract.whenPresent ?? []).some(
+      (rule) => rule.path && fileExists(rule.path) && rule.requireRecipeCoverage,
+    ),
+  };
+}
+
+module.exports = {
+  TERMINAL_COMMANDS,
+  BUILTIN_FLOW_COMMANDS,
+  resolveWorkerTerminalContract,
+  lintWorkerTemplateAgainstContract,
+  lintWorkerTemplateStructure,
+  templateUsesTerminalMark,
+  templateTerminalCommands,
+  templateBodyScope,
+  expandedArtifactsForCommand,
+};

package/skills/project-adopt/SKILL.md

@@ -17,7 +17,7 @@ Recommend a pragmatic adoption path for recipe-first validation.
 1. Recipe runner: add a local command that executes one recipe and emits artifacts.
 2. Project recipe layer: add recipes, runner manifest, project actions, and artifact conventions.
 3. Farmslot project integration: add `project.json` hooks for slot-based execution.
-4. Full OS: adopt Gateway, Command Center, multi-slot dispatch, Companion, and retrospectives.
+4. Full framework: adopt Gateway, Command Center, multi-slot dispatch, Companion, and retrospectives.
 
 ## Workflow
 
@@ -28,6 +28,6 @@ Recommend a pragmatic adoption path for recipe-first validation.
 
 ## Hard Rules
 
-- Do not prescribe the full Farmslot OS when a local recipe runner is enough.
+- Do not prescribe the full Farmslot framework when a local recipe runner is enough.
 - Do not add domain-specific assumptions.
 - Do not require a project to change its test stack before proving the first useful recipe.

package/skills/recipe-cook/SKILL.md

@@ -61,7 +61,7 @@ If an interactive slot exists, do not stop after pasting or emitting JSON in cha
 
 The harness order is mandatory.
 Do not silently batch or skip steps.
-Mark each completed checklist step `[x]` immediately. Do not batch checkbox updates.
+Mark each completed checklist step immediately. If the run-local task has a `mark` helper, use `./mark N` (1-based); otherwise change `[ ]` to `[x]` yourself. Do not batch checkbox updates.
 
 ## Output Contract
 

package/skills/recipe-cook/references/TASK.md

@@ -10,7 +10,7 @@ Do not edit the template in-place during a cooking run.
 
 Every time you complete a checklist step:
 
-1. immediately change `- [ ]` to `- [x]`
+1. run `./mark N` if present (1-based); otherwise immediately change `- [ ]` to `- [x]`
 2. update `STATUS` if needed
 3. only then move to the next step
 

package/skills/recipe-harness/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: recipe-harness
-description: Help run or install a local recipe runtime without assuming the full Farmslot OS
+description: Help run or install a local recipe runtime without assuming the full Farmslot framework
 compatibility: Claude, Codex, Cursor, and Markdown skill runners with shell access
 metadata:
   package: '@farmslot/skills'