@farmslot/skills 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,15 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farmslot/skills",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,7 +16,9 @@
     },
     "./skills/*": "./skills/*/SKILL.md",
     "./schemas/*": "./schemas/*",
-    "./scripts/mark-checklist-step.cjs": "./scripts/mark-checklist-step.cjs"
+    "./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",
@@ -64,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

@@ -1,13 +1,34 @@
 #!/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]';
+  '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(
@@ -17,9 +38,12 @@ function printHelp() {
       '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]',
-      '  ./mark no-change --reason "..." [--already-fixed] [--mark-last]',
+      '  ./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'),
   );
@@ -47,7 +71,13 @@ 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') {
+  if (
+    key === '--mark-last' ||
+    key === '--already-fixed' ||
+    key === '--no-self-review' ||
+    key === '--skip-learnings' ||
+    key === '--skip-checklist'
+  ) {
     opts[key.slice(2)] = true;
     continue;
   }
@@ -102,6 +132,49 @@ function resolveTerminalPreset(command) {
   }
 }
 
+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) {
@@ -111,7 +184,127 @@ function assertNoChangeReport(taskDir) {
   return NO_CHANGE_REPORT;
 }
 
-function buildSignalUpdate(signal, terminal, target, timing, events, now, taskPath, taskDir) {
+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',
@@ -139,8 +332,14 @@ function buildSignalUpdate(signal, terminal, target, timing, events, now, taskPa
       : {}),
   };
 
+  const contract = terminal ? loadTerminalContract(_taskDir, taskPath) : null;
   if (terminal.command === 'no-change') {
-    next.evidence = { reportPath: assertNoChangeReport(taskDir) };
+    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;
@@ -231,6 +430,14 @@ function resolveTarget(taskPath, stepNumber, markLast) {
 }
 
 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']));
@@ -254,6 +461,10 @@ if (
   events.push({ stepNumber: target.stepNumber, label: target.label, checkedAt: now });
 }
 
+if (terminalCommand) {
+  assertTerminalPackagedEvidence(taskPath, taskDir, terminalCommand);
+}
+
 const next = buildSignalUpdate(
   signal,
   terminalCommand ? { command: terminalCommand } : null,

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,
+};