@farmslot/skills 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,15 @@ All notable changes to `@farmslot/skills` are tracked here.
 
 - Active-development baseline; add user-facing changes here before release or package publication.
 
+## 0.4.0 - 2026-09-17
+
+- Recipe Cook lane: the runner envelope reports `terminal_status` (`done|blocked|failed`) and `terminal_reason`; the lane no longer reads or rewrites a `STATUS:` line in the run-local TASK.md, and `meta.json` records `terminal_reason`. Templates and skill text drop the field. An envelope without a valid `terminal_status`, or a blocked/failed one without `terminal_reason`, fails the run; the model output stays in `runner-output.txt`. The `tmux-model-driver` launcher and watcher stop mentioning or parsing the field.
+
+## 0.3.0 - 2026-08-03
+
+- Teach recipe authors to start from existing parameterized recipes and compose them node by node before adding new capabilities.
+- Active-development baseline; add user-facing changes here before release or package publication.
+
 ## 0.2.0 - 2026-07-19
 
 - Teach recipe authors to inspect declared actions and reusable flows before creating new capabilities

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farmslot/skills",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -33,7 +33,7 @@
     "prepublishOnly": "node ../../scripts/quality/check-farmslot-package-readiness.mjs --publish --packages @farmslot/skills"
   },
   "dependencies": {
-    "@farmslot/agent-runtime": "0.2.0"
+    "@farmslot/agent-runtime": "0.10.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/scripts/run-cooking-lane.cjs

@@ -222,9 +222,7 @@ function resolveRepoLocalContext({ startDir, repoName }) {
   const repoRoot = findUp(startDir, (candidate) => {
     if (!fs.existsSync(path.join(candidate, '.git'))) return false;
     if (repoName === 'example-browser') {
-      return (
-        findFilesByBasename(candidate, ['validate-recipe.js', 'validate-flow-schema.js']).length > 0
-      );
+      return findFilesByBasename(candidate, ['validate-recipe.js']).length > 0;
     }
     if (repoName === 'example-mobile') {
       return findFilesByBasename(candidate, ['validate-recipe.sh']).length > 0;
@@ -431,7 +429,9 @@ function buildPrompt({
     '',
     '## Required output JSON schema',
     '{',
-    '  "task_markdown": "full TASK.md content based on the provided template. Set STATUS to the correct terminal value: done, blocked, or failed. Inside ## Validation Evidence include the exact standalone token RECIPE_COOK_VALIDATION_PENDING.",',
+    '  "task_markdown": "full TASK.md content based on the provided template. Inside ## Validation Evidence include the exact standalone token RECIPE_COOK_VALIDATION_PENDING.",',
+    '  "terminal_status": "done|blocked|failed",',
+    '  "terminal_reason": "one sentence naming the concrete blocker or failure; null when done",',
     '  "recipe_json": { "valid": "json object" },',
     '  "recipe_cook_json": { "valid": "json object" } or null,',
     '  "evidence_verdict": "good|ok|bad",',
@@ -453,7 +453,8 @@ function buildPrompt({
     '',
     'The JSON object you return is the final serialized payload for those files.',
     'Emit the JSON last, after you have fully reasoned through:',
-    '- the rewritten TASK.md contents, including the correct terminal STATUS',
+    '- the rewritten TASK.md contents',
+    '- the terminal_status (done, blocked, or failed) and, for blocked or failed, its concrete terminal_reason',
     '- the recipe artifact contents',
     '- the learning artifact contents',
     '- what validation commands should run',
@@ -661,17 +662,11 @@ function discoverValidationSteps({ repoName, repoRoot, recipePath, artifactsDir,
   }
 
   if (repoName === 'example-browser') {
-    const schemaValidator = findFilesByBasename(repoRoot, ['validate-flow-schema.js'])[0];
     const recipeValidator = findFilesByBasename(repoRoot, ['validate-recipe.js'])[0];
-    if (!schemaValidator || !recipeValidator) {
+    if (!recipeValidator) {
       return [];
     }
     const steps = [
-      {
-        name: 'schema_validation',
-        command: ['node', schemaValidator, recipePath],
-        cwd: repoRoot,
-      },
       {
         name: 'dry_run',
         command: ['node', recipeValidator, '--recipe', recipePath, '--dry-run'],
@@ -777,26 +772,47 @@ function renderValidationEvidence(validationResults, cdpPort, repoRoot) {
   return lines.join('\n');
 }
 
-function deriveTerminalState(taskMarkdown, validationResults) {
+// Terminal state comes from the runner's explicit envelope field, never from
+// status text in the task markdown. Two evidence-based overrides remain: an
+// UNRESOLVED proof target blocks, and a failed validation step fails.
+function deriveTerminalState(envelope, taskMarkdown, validationResults) {
   const text = String(taskMarkdown || '');
-  if (/\bSTATUS:\s*blocked\b/i.test(text)) {
-    return { status: 'blocked', outcome: 'partial' };
+  // A reason only travels with a non-done envelope; a note attached to a done
+  // envelope must not be presented as the blocker or failure cause. The two
+  // evidence overrides below are reachable only for done envelopes, so they
+  // synthesize their own reason.
+  const reason =
+    envelope.terminal_status !== 'done' &&
+    typeof envelope.terminal_reason === 'string' &&
+    envelope.terminal_reason.trim()
+      ? envelope.terminal_reason.trim()
+      : null;
+  if (envelope.terminal_status === 'blocked') {
+    return { status: 'blocked', outcome: 'partial', reason };
   }
-  if (/\bSTATUS:\s*failed\b/i.test(text)) {
-    return { status: 'failed', outcome: 'failure' };
+  if (envelope.terminal_status === 'failed') {
+    return { status: 'failed', outcome: 'failure', reason };
   }
   if (/^\s*[-*]\s+.*:\s*UNRESOLVED\b/m.test(text)) {
-    return { status: 'blocked', outcome: 'partial' };
+    return {
+      status: 'blocked',
+      outcome: 'partial',
+      reason: 'a required proof target remains UNRESOLVED',
+    };
   }
 
-  const failingStep = Object.values(validationResults || {}).find(
-    (result) => result.exit_code !== 0 && result.exit_code !== -1,
+  const failingStep = Object.entries(validationResults || {}).find(
+    ([, result]) => result.exit_code !== 0 && result.exit_code !== -1,
   );
   if (failingStep) {
-    return { status: 'failed', outcome: 'failure' };
+    return {
+      status: 'failed',
+      outcome: 'failure',
+      reason: `validation step ${failingStep[0]} exited ${failingStep[1].exit_code}`,
+    };
   }
 
-  return { status: 'done', outcome: 'success' };
+  return { status: 'done', outcome: 'success', reason: null };
 }
 
 function injectValidationEvidence(taskMarkdown, evidenceBlock) {
@@ -995,6 +1011,15 @@ async function main() {
     typeof envelope.next_delta === 'string' && envelope.next_delta.trim(),
     'Runner output missing next_delta',
   );
+  assert(
+    ['done', 'blocked', 'failed'].includes(envelope.terminal_status),
+    `Runner output missing terminal_status (done|blocked|failed). See ${path.join(runDir, 'runner-output.txt')}`,
+  );
+  assert(
+    envelope.terminal_status === 'done' ||
+      (typeof envelope.terminal_reason === 'string' && envelope.terminal_reason.trim()),
+    `Runner output missing terminal_reason for terminal_status ${envelope.terminal_status}. See ${path.join(runDir, 'runner-output.txt')}`,
+  );
   writeJson(path.join(runDir, 'runner-response.json'), envelope);
 
   const recipePath = path.join(artifactsDir, 'recipe.json');
@@ -1017,11 +1042,7 @@ async function main() {
   const evidenceBlock = renderValidationEvidence(validationResults, effectiveCdpPort, projectRoot);
   const normalizedTask = normalizeTaskArtifactDir(envelope.task_markdown, artifactsDir);
   let finalTask = injectValidationEvidence(normalizedTask, evidenceBlock);
-  const terminalState = deriveTerminalState(finalTask, validationResults);
-  finalTask = finalTask.replace(
-    /STATUS:\s*(pending|working|done|blocked|failed)/i,
-    `STATUS: ${terminalState.status}`,
-  );
+  const terminalState = deriveTerminalState(envelope, finalTask, validationResults);
   writeFile(path.join(runDir, 'TASK.md'), finalTask);
 
   const verdict = mapVerdict(envelope.evidence_verdict, validationResults);
@@ -1044,6 +1065,7 @@ async function main() {
         : terminalState.outcome === 'partial'
           ? 'blocked'
           : 'completed',
+    terminal_reason: terminalState.reason,
   });
   writeJson(path.join(artifactsDir, 'grade.json'), {
     recipe_semantic: verdict,

package/skills/recipe-cook/SKILL.md

@@ -93,7 +93,7 @@ Completion requires:
 - unresolved-target audit written
 - validation evidence recorded
 - all required proof targets either `PROVEN` or explicitly non-applicable by contract
-- `STATUS: done` in the run-local copied `TASK.md`
+- `terminal_status: done` in the run envelope; `blocked` and `failed` carry a concrete `terminal_reason`
 
 ## Hard Rules
 
@@ -101,7 +101,7 @@ Completion requires:
 - Do not emit canonical success output if every target is unresolved
 - Do not prefer screenshots when state proof is enough
 - Do not skip screenshots when the claim is visual or review-sensitive
-- Do not rebuild known flows as raw steps when `call` exists
+- Do not rebuild known recipes as raw steps when `call` exists
 - Do not stop after printing a recipe or JSON payload if writable artifacts and validation surfaces still exist
 - Do not leave the copied `TASK.md` as the untouched template
 - Do not write `SIGNAL.json` with `complete/success` when a required validation failed or when a required proof target remains `UNRESOLVED`
@@ -112,14 +112,14 @@ Completion requires:
 
 | Pitfall                                                            | Correct Pattern                                                                                      |
 | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
-| Treating cooking as deterministic templating                       | Treat it as LLM synthesis constrained by repo flows/evals and honest proof                           |
+| Treating cooking as deterministic templating                       | Treat it as LLM synthesis constrained by repo journeys/recipes/evals and honest proof                |
 | Using the whole PR description as one target                       | Extract small executable proof targets                                                               |
 | Defaulting every UI claim to screenshots only                      | choose `visual` or `mixed` deliberately                                                              |
 | Defaulting every non-visual claim to a screenshot anyway           | prefer state/log/trace proof                                                                         |
-| Rewriting long repeated setup chains                               | reuse `call` flows                                                                                   |
+| Rewriting long repeated setup chains                               | reuse parameterized recipes through `call`                                                           |
 | Forcing a canonical recipe when the claim is unresolved            | stop or emit only resolved targets with explicit gaps                                                |
 | Treating interactive farmslot execution like chat-only drafting    | keep driving the workspace until artifacts + validation evidence exist                               |
-| Writing recipe artifacts but forgetting the copied `TASK.md`       | rewrite the task file and update `STATUS` / evidence sections before stopping                        |
+| Writing recipe artifacts but forgetting the copied `TASK.md`       | rewrite the task file and update the evidence sections before stopping                               |
 | Inventing non-canonical runner fields like `timeout` on `wait_for` | use documented runner field names such as `timeout_ms` so live validation honors the intended timing |
 
 ## Stop Conditions
@@ -127,7 +127,7 @@ Completion requires:
 Stop and report instead of forcing a recipe when:
 
 - target text is still too ambiguous to map honestly
-- repo has no viable flow/eval/native interaction path for the claim
+- repo has no viable recipe/eval/native interaction path for the claim
 - current runner context is missing and the missing context changes what should be proven
 - the repo has no validation runner and you already recorded `validation unavailable`
 

package/skills/recipe-cook/TASK.md

@@ -12,7 +12,6 @@ SOURCE_KIND:
 SOURCE_REF:
 ARTIFACT_DIR:
 VALIDATION_MODE:
-STATUS: pending
 ```
 
 ## Source Material
@@ -22,7 +21,7 @@ Paste or summarize:
 - PR body
 - linked ticket ACs / expected behavior
 - investigation findings
-- existing recipe / flow / eval refs
+- existing action / recipe / eval refs
 
 ## Acceptance Criteria
 
@@ -87,19 +86,19 @@ It must include:
 
 ## Checklist
 
-- [ ] **1. Fill the task block** — set `TARGET_REPO`, `SOURCE_KIND`, `SOURCE_REF`, `ARTIFACT_DIR`, `VALIDATION_MODE`, `STATUS: working`.
-- [ ] **2. Gather the real source of truth** — PR/ticket/investigation text plus existing flows/evals in the target repo.
+- [ ] **1. Fill the task block** — set `TARGET_REPO`, `SOURCE_KIND`, `SOURCE_REF`, `ARTIFACT_DIR`, `VALIDATION_MODE`.
+- [ ] **2. Gather the real source of truth** — PR/ticket/investigation text plus existing user journeys, recipes, and evals in the target repo.
 - [ ] **3. Enumerate acceptance criteria** — write a numbered canonical list under `## Acceptance Criteria`.
 - [ ] **4. Extract proof targets** — split the work into the smallest executable claims.
 - [ ] **5. Decide proof mode** — choose `state`, `visual`, or `mixed` for every target and justify every `mixed`.
-- [ ] **6. Discover reuse** — list existing `flow` / `eval_ref` / canonical recipe surfaces before writing new graph steps.
+- [ ] **6. Discover reuse** — list existing actions, recipes, and eval refs before writing new graph steps.
 - [ ] **7. Draft the recipe** — write `artifacts/recipe.json` and, when supported, `artifacts/recipe-cook.json`.
 - [ ] **8. Run schema validation** — if the repo provides a schema validator, run it and record the command + output under `## Validation Evidence`.
 - [ ] **9. Run runner dry-run validation** — if the repo provides a runner, run at least a dry-run and record the command + output.
 - [ ] **10. Handle unavailable validation honestly** — if the repo has no validator or runner, write `validation unavailable` with the reason. Do not fake success.
 - [ ] **11. Write the learning artifact** — write `artifacts/recipe-cook-learning.json` with evidence verdict and proposed next delta.
 - [ ] **12. Audit unresolved targets** — update `## Resolved vs Unresolved` and `## Recipe Coverage Audit` after validation evidence exists.
-- [ ] **13. Final completion gate** — set `STATUS: done` only after recipe writing, validation evidence, learning artifact, and unresolved-target audit are all present.
+- [ ] **13. Final completion gate** — reach the Success outcome only after recipe writing, validation evidence, learning artifact, and unresolved-target audit are all present.
 
 ## Failure Conditions
 

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

@@ -11,8 +11,7 @@ Do not edit the template in-place during a cooking run.
 Every time you complete a checklist step:
 
 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
+2. only then move to the next step
 
 Do not batch checkbox updates.
 Do not leave completed steps unchecked.
@@ -31,7 +30,6 @@ TASK_DIR: {{TASK_DIR}}
 ARTIFACT_DIR: {{ARTIFACT_DIR}}
 SOURCE_BUNDLE_FILE: {{SOURCE_BUNDLE_FILE}}
 VALIDATION_MODE: {{VALIDATION_MODE}}
-STATUS: pending
 ```
 
 ## Source Material
@@ -43,7 +41,7 @@ Then replace this section with your own summary of:
 - PR body
 - linked ticket ACs / expected behavior
 - investigation findings
-- existing recipe / flow / eval refs
+- existing action / recipe / eval refs
 
 ## Acceptance Criteria
 
@@ -110,12 +108,12 @@ It must include:
 
 ## Checklist
 
-- [ ] **1. Fill the task block** — set `TARGET_REPO`, `SOURCE_KIND`, `SOURCE_REF`, `ARTIFACT_DIR`, `VALIDATION_MODE`, `STATUS: working`.
-- [ ] **2. Gather the real source of truth** — PR/ticket/investigation text plus existing flows/evals in the target repo.
+- [ ] **1. Fill the task block** — set `TARGET_REPO`, `SOURCE_KIND`, `SOURCE_REF`, `ARTIFACT_DIR`, `VALIDATION_MODE`.
+- [ ] **2. Gather the real source of truth** — PR/ticket/investigation text plus existing user journeys, recipes, and evals in the target repo.
 - [ ] **3. Enumerate acceptance criteria** — write a numbered canonical list under `## Acceptance Criteria`.
 - [ ] **4. Extract proof targets** — split the work into the smallest executable claims.
 - [ ] **5. Decide proof mode** — choose `state`, `visual`, or `mixed` for every target and justify every `mixed`.
-- [ ] **6. Discover reuse** — list existing `flow` / `eval_ref` / canonical recipe surfaces before writing new graph steps.
+- [ ] **6. Discover reuse** — list existing actions, recipes, and eval refs before writing new graph steps.
 - [ ] **7. Draft the recipe** — write `artifacts/recipe.json` and, when supported, `artifacts/recipe-cook.json`. Use documented runner field names for nodes (for example `timeout_ms` / `poll_ms` on `wait_for`), not guessed aliases.
 - [ ] **8. Rewrite this copied TASK file** — replace the template placeholders with the real run data and working notes. Leaving the untouched template is a failure.
 - [ ] **9. Run schema validation** — if the repo provides a schema validator, run it and record the command + output under `## Validation Evidence`.
@@ -124,7 +122,7 @@ It must include:
 - [ ] **12. Handle unavailable validation honestly** — if the repo has no validator or runner, write `validation unavailable` with the reason. Do not fake success.
 - [ ] **13. Write the learning artifact** — write `artifacts/recipe-cook-learning.json` with evidence verdict and proposed next delta.
 - [ ] **14. Audit unresolved targets** — update `## Resolved vs Unresolved` and `## Recipe Coverage Audit` after validation evidence exists.
-- [ ] **15. Final completion gate** — set `STATUS: done` only after recipe writing, rewritten TASK.md, validation evidence, learning artifact, and unresolved-target audit are all present.
+- [ ] **15. Final completion gate** — reach the Success outcome only after recipe writing, rewritten TASK.md, validation evidence, learning artifact, and unresolved-target audit are all present.
 - [ ] **16. Write terminal signal** — write exactly one terminal `SIGNAL.json` based on the outcome matrix below.
 
 ## Outcome Matrix
@@ -134,7 +132,6 @@ Write `SIGNAL.json` only after step 15 is evaluated.
 - **Success**:
   - every required validation passed or was explicitly non-applicable by contract
   - no required proof target remains `UNRESOLVED`
-  - `STATUS: done`
   - signal:
     ```json
     { "status": "complete", "outcome": "success" }
@@ -143,7 +140,6 @@ Write `SIGNAL.json` only after step 15 is evaluated.
 - **Blocked**:
   - a concrete environment/runtime/tooling blocker prevented required validation
   - or a proof target remains `UNRESOLVED` because a required live/runtime dependency was unavailable
-  - `STATUS: blocked`
   - signal:
     ```json
     { "status": "blocked", "outcome": "partial", "reason": "<concrete blocker>" }
@@ -152,7 +148,6 @@ Write `SIGNAL.json` only after step 15 is evaluated.
 - **Failed**:
   - a required validation actually ran and failed
   - or the recipe/proof contradicts the PR claim
-  - `STATUS: failed`
   - signal:
     ```json
     { "status": "failed", "outcome": "failure", "reason": "<concrete failure>" }

package/skills/recipe-cook/repos/example-browser.md

@@ -12,7 +12,7 @@ Use this overlay when the target project is a browser or web app and has no more
 Start with:
 
 ```bash
-rg --files | rg 'recipes?/.*\\.json$|flows?/.*\\.json$|validate-recipe\\.(js|mjs|cjs|ts)|validate-flow-schema\\.(js|mjs|cjs|ts)|playwright|cypress|vitest|agentic-toolkit\\.md'
+rg --files | rg 'recipes?/.*\\.json$|validate-recipe\\.(js|mjs|cjs|ts)|playwright|cypress|vitest|agentic-toolkit\\.md'
 ```
 
 Then inspect package scripts for existing validation surfaces:
@@ -37,7 +37,6 @@ Look for:
 Use repo-local commands first. Common shapes include:
 
 ```bash
-node <validate-flow-schema.js> <recipe.json>
 node <validate-recipe.js> --recipe <recipe.json> --dry-run
 npm test -- --runInBand
 ```

package/skills/recipe-cook/repos/example-mobile.md

@@ -12,7 +12,7 @@ Use this overlay when the target project is a mobile app and has no more specifi
 Start with:
 
 ```bash
-rg --files | rg 'recipes?/.*\\.json$|flows?/.*\\.json$|validate-recipe\\.(sh|js|mjs|cjs|ts)|detox|maestro|appium|testIds?|accessibility|agentic-toolkit\\.md'
+rg --files | rg 'recipes?/.*\\.json$|validate-recipe\\.(sh|js|mjs|cjs|ts)|detox|maestro|appium|testIds?|accessibility|agentic-toolkit\\.md'
 ```
 
 Then inspect package scripts for local test and validation commands:
@@ -23,7 +23,7 @@ node -e "const p=require('./package.json'); console.log(p.scripts || {})"
 
 ## Cooking Rules
 
-- Prefer stable accessibility labels, test IDs, or existing mobile flows when they exist.
+- Prefer stable accessibility labels, test IDs, or existing mobile automation when it exists.
 - Keep proof targets separate from platform mechanics.
 - Do not import web-only selectors or desktop assumptions into mobile recipes.
 - If mobile lacks a repo-owned helper, write a recipe and proof plan, then mark live validation unavailable with the concrete blocker.

package/skills/recipe-harness/SKILL.md

@@ -16,7 +16,7 @@ Use the local recipe runtime when one exists, or recommend the smallest install
 
 1. Find the project-owned recipe command first.
 2. If no command exists, check for `@farmslot/recipe-harness` or an app-specific harness package.
-3. Before authoring, inspect declared actions and reusable flows. Prefer project discovery commands. For generic flow discovery, run `farmslot-recipe flows list` and `farmslot-recipe flows describe <ref>`. If no action discovery command exists, read only the relevant project manifest entries and examples.
+3. Before authoring, inspect the closest recipes with `farmslot-recipe run --list` and `farmslot-recipe run <id> --describe`, then inspect declared actions only if no recipe fits. Prefer project discovery commands; otherwise read only the relevant manifest entries and examples.
 4. Run dry-run or schema validation before live execution when available.
 5. Record artifact paths and validation output.
 6. If no runner exists, stop with a concrete install recommendation.
@@ -25,7 +25,7 @@ Use the local recipe runtime when one exists, or recommend the smallest install
 
 - Do not invent runner commands.
 - Do not require Farmslot Gateway, pool files, slots, Command Center, or Companion for first use.
-- Do not bypass project fixtures or user-flow validation by directly mutating app state.
+- Do not bypass project fixtures or user-journey validation by directly mutating app state.
 
 ## Output