@farmslot/skills 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to `@farmslot/skills` are tracked here.
 
 ## Unreleased
 
+- Active-development baseline; add user-facing changes here before release or package publication.
+
+## 0.5.0 - 2026-09-20
+
+- README documents the checklist-shaped skill rule: a skill invoked as a child checklist unit (ADR-060) needs `##` sections and `- [ ]` rows the shared parser can enumerate, informational sections named so the skip list drops them, and numbered labels matching their positions. A prose-only skill cannot be a child unit.
+
+## 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.

package/README.md

@@ -44,6 +44,35 @@ Supported layouts:
 | `project-adopt`  | Recommend the smallest useful Farmslot integration level for the project.                       |
 | `packet`         | Communicate plans, blockers, decisions, and evidence reviews as compact operator packets.       |
 
+## Checklist-shaped skills
+
+A checklist step can hand its work to a skill as a **child unit**: the step registers the
+skill, `mark` materializes its body as `subtasks/<id>.md` beside the task checklist, and the
+worker marks the skill's own rows so progress is visible per row instead of one box open for
+the whole review. Farmslot only materializes and observes files; nothing is spawned.
+
+A skill can be a child unit when its body is enumerable by the same parser the task checklist
+uses:
+
+- `##` (or deeper) headings and `- [ ]` rows, with at least one row. A prose-only skill cannot be
+  a child unit.
+- Name informational sections so the shared skip list drops them: `Rules`, `Description`,
+  `Task`, `Acceptance Criteria`, `Affected Area`, `Screenshots`, `Comments`, `Root Cause`,
+  `Recipe ACs`, `Pre-merge`. Boxes there are never steps.
+- If a row label carries its own number (`**3. …**`), it must match the row's position. The
+  numbering guard refuses a body where they diverge, because `mark` targets positions.
+
+A template step registers the installed skill and finishes it:
+
+```bash
+{{TASK_DIR}}/mark sub start perps-review --step 21 --from .agents/skills/mms-perps-review-pr/skill.md
+{{TASK_DIR}}/mark sub perps-review 1        # …one per row
+{{TASK_DIR}}/mark sub perps-review complete --report artifacts/review.md
+```
+
+The step's own box is ticked by that `complete`, so the template says what to register, and the
+skill owns what to check.
+
 ## Adoption Ladder
 
 1. Skills only: author and review recipes without a runner.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farmslot/skills",
-  "version": "0.3.0",
+  "version": "0.5.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.6.0"
+    "@farmslot/agent-runtime": "0.13.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/scripts/run-cooking-lane.cjs

@@ -429,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",',
@@ -451,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',
@@ -769,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) {
@@ -987,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');
@@ -1009,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);
@@ -1036,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
 
@@ -119,7 +119,7 @@ Completion requires:
 | 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

package/skills/recipe-cook/TASK.md

@@ -12,7 +12,6 @@ SOURCE_KIND:
 SOURCE_REF:
 ARTIFACT_DIR:
 VALIDATION_MODE:
-STATUS: pending
 ```
 
 ## Source Material
@@ -87,7 +86,7 @@ It must include:
 
 ## Checklist
 
-- [ ] **1. Fill the task block** — set `TARGET_REPO`, `SOURCE_KIND`, `SOURCE_REF`, `ARTIFACT_DIR`, `VALIDATION_MODE`, `STATUS: working`.
+- [ ] **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.
@@ -99,7 +98,7 @@ It must include:
 - [ ] **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
@@ -110,7 +108,7 @@ It must include:
 
 ## Checklist
 
-- [ ] **1. Fill the task block** — set `TARGET_REPO`, `SOURCE_KIND`, `SOURCE_REF`, `ARTIFACT_DIR`, `VALIDATION_MODE`, `STATUS: working`.
+- [ ] **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.
@@ -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>" }