@farmslot/skills 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -4,4 +4,10 @@ All notable changes to `@farmslot/skills` are tracked here.
 
 ## Unreleased
 
+## 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.1",
   "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,12 @@
       "default": "./dist/index.js"
     },
     "./skills/*": "./skills/*/SKILL.md",
-    "./schemas/*": "./schemas/*"
+    "./schemas/*": "./schemas/*",
+    "./scripts/mark-checklist-step.cjs": "./scripts/mark-checklist-step.cjs"
   },
   "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 +55,7 @@
   ],
   "files": [
     "README.md",
+    "LICENSE",
     "CHANGELOG.md",
     "bin/**/*.mjs",
     "dist/**/*.js",

package/scripts/mark-checklist-step.cjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+const fs = require('node:fs');
+const path = require('node:path');
+
+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 usageLine =
+  'usage: mark <step-number|start|complete|no-change|blocked> [--reason text] [--already-fixed] [--mark-last] [--no-self-review]';
+
+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]',
+      '  ./mark no-change --reason "..." [--already-fixed] [--mark-last]',
+      '  ./mark blocked --reason "..." [--mark-last]',
+      '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') {
+    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 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 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 }
+      : {}),
+  };
+
+  if (terminal.command === 'no-change') {
+    next.evidence = { reportPath: assertNoChangeReport(taskDir) };
+  }
+
+  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);
+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 });
+}
+
+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/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'