Task directory contract
One directory per run, the same shape whether Farmslot dispatched the worker or an engineer started the task from a skill. Farmslot defines the files; @farmslot/agent-runtime and any harness built on it consume them.
Review completion MUST wait for the reviewer's own terminal mark before archiving its checklist and artifacts. A result file, idle runner or closed window alone does not establish successful completion.
The shared harness checklist command MUST resolve explicit --checklist and
--signal overrides before preserving a terminal signal. To resume a cleared
blocker, run checklist mark <task-dir> start, then continue numbered marks. This
uses the existing runtime start verb, preserves checked boxes and resumes signal
progress under the launcher's attempt identity. Successful terminal verdicts remain protected.
On a complete or no-change signal, checklist mark <task-dir> N validates the
declared deterministic step under the receipt rules below without reopening the
signal; other numbered marks stay ignored.
Ticket intake preserves an explicit acceptance section, including an empty one. When none is supplied,
authored AC1: or AC-1: paragraphs outside fenced code populate the same
acceptance array in source order. Paragraph boundaries exclude unrelated prose.
Existing structured criteria remain authoritative. Generated TASK.md and
<task>/inputs/handoff.json MUST consume that same normalized array.
Linked run tickets
Run.linkedTicketRefs stores operator-added Jira keys only. Metadata edits MUST
NOT rewrite ticketData, task files, package inputs, review state or evidence.
The shared reader unions the canonical Jira ref, ticketData.jiraKey, prefetched
ticketData.linkedTickets, ticket keys in description headings and acceptance
criterion prefixes, and these operator additions. Keys are uppercase and unique;
incidental references in description prose are not covered tickets.
Run list/detail in Command Center and Companion MUST show this same union and
search it through the shared run-list selection. Existing run and family summary
projections carry the covered-key union so a trimmed summary retains ticket lookup.
Removing an operator addition MUST NOT remove a key derived from frozen inputs.
A known Jira browse URL supplies links; a key without a resolved URL stays visible.
The run's recorded PR link remains available beside its tickets.
Run list rows MUST render one comma-separated line at the metadata text size,
without ticket pills or a separate label. The source ticket comes first and
appears once. A PR source is linked first, followed by covered tickets. The shared
runLinkedTicketsView.references owns this order and destinations. Long lines
scroll horizontally so additional tickets do not increase row height.
The existing metadata line also shows total wall time from startedAt or createdAt,
plus elapsed wall time from the running step's startedAt. Clients pass the
steps from the existing runActivityView so review and fix attempts share the
pipeline's current actor and attempt start. Both apps MUST use
runElapsedTimeView and tick live labels at least once per minute. Terminal totals
freeze at completedAt, falling back to statusChangedAt or updatedAt on older records.
Public surface
@farmslot/protocol exports the additive Run.linkedTicketRefs contract,
normalizeRunLinkedTicketRefs, runLinkedTicketRefs, runLinkedTicketsView and
runElapsedTimeView.
Command Center and Companion use the same reader and validation. Each platform
reuses one ticket renderer for run list and detail. The supported admin metadata
RPC run.linkedTickets.set { runId, linkedTicketRefs } replaces only the operator
additions, persists the run and broadcasts run.updated, following run.tags.set.
RunMethods.setLinkedTickets names it; CLI callers may use the existing generic
farmslot rpc entry. There is no new worker/harness hook, task input, workflow
action or wire version. The SDK addition requires a fresh minor package release.
Run checklist progress
Command Center and Companion MUST retain the run pipeline and, when its current
step has structured checklist data, show a thinner bar beneath it with
completedSteps/totalSteps and currentStep. They MUST NOT derive totals from
pipeline segments or hint text. Without checklist data, no sub-bar is rendered;
the compact strip reserves its height so live updates do not move the run row.
A finished run or idle person gate MUST NOT display the previous review's checklist.
Both clients consume the @farmslot/review-dispatch run-checklist view model and
one renderer per platform for list and detail. They hydrate through existing
task.progress and follow task.progress.updated, matching the run, slot and
active checklist. Checklist or attempt changes invalidate cached progress.
Slot-free review workspaces use their existing empty slot id and run id.
These additive UI helpers are exported by @farmslot/review-dispatch; there are
no new CLI flags, persisted fields, harness requirements or wire version changes.
Checklist row durations
The expanded Worker progress panel in both clients MUST show completed checklist
durations as muted trailing text and live elapsed time on the current row. Both
renderers consume the same @farmslot/review-dispatch checklist row model. Missing
timing MUST leave the duration blank rather than inventing a value.
TaskProgressStructured.timing carries the existing <task>/SIGNAL.json mark history,
the current attempt's startedAt when known, and finishedAt when stopped. It
belongs to that exact checklist and context; a warm reviewer MUST NOT reuse its
first launch as the current attempt start. Child units use their registration
time. A signal-only timing update MUST publish progress even if no checkbox
changed. Completed durations use deriveChecklistStepDurations; elapsed time
stops at the recorded finish. Retained worker metrics supply historical timing
after finalize.
A stopped parent also stops elapsed time on unfinished child rows, without changing the child's recorded ownership or signal status. Progress and monthly analytics use the same attempt boundary to exclude marks from before a resume.
Monthly events-YYYY-MM.ndjson records add optional checklistSteps, containing
the primary worker's step number, label and duration in milliseconds, derived
from retained Run.metrics.checklistTiming and its worker attempt start. This
additive field does not change analytics schema version 2. Existing aggregate
query results and bundle exports are unchanged.
These optional contracts belong to @farmslot/protocol; both apps and monthly
analytics are the consumers. The SDK and shared view-model require fresh minor
releases. There is no new harness writer, CLI flag or wire version.
Two documents, one checklist
The task document says what the work is. The execution checklist says how to do it, step by step. Only the checklist has steps.
| File | Holds | Steps counted? |
|---|---|---|
<task>/TASK.md | Ticket block, description, acceptance criteria, screenshots, comments, PR comment summary (pr-complete), mode preamble, project addendum, mark instructions, pointers to <task>/inputs/, appended gateway contracts | no |
<task>/CHECKLIST.md | The selected execution template, placeholders expanded, nothing injected or appended | yes |
Because the checklist carries no run data, a project can select a template from any catalog source and get the same bytes a standalone skill materializes for the same template id. The provenance digest proves it.
This is the only layout the task writer produces. One flow keeps its own pairing: lightweight interactive dev writes the operator-agreed plan into <task>/CHECKLIST.md and renders its template into <task>/TASK.md, because the plan there is decided live with the operator rather than selected from a catalog.
Layout
<task>/
TASK.md task document (built by @farmslot/agent-runtime)
CHECKLIST.md execution checklist (template, placeholders rendered, otherwise verbatim)
mark shim: exec ${FARMSLOT_MARK_CMD:-<recorded command>} "$DIR" "$@"
SIGNAL.json written only by mark
checklist-target.json role switches write it; absent = CHECKLIST.md + SIGNAL.json
inputs/
handoff.json the task record: identity, flow, task, report paths,
executionTemplate (selected checklist + digests),
templateProvenance (Farmslot only: repo revisions, selection source)
worker-terminal-contract.json artifacts required before a terminal mark
bug-input.json ticket as fetched, comments included (when a ticket exists)
plan.md supplied approved plan, when present
qa.json admitted QA inputs, when present
recipe-binding.json retained provider and recipe bindings
runtime-capability-catalog.json configured provider and task owner metadata
inherited-context.json materialized family context and any input gaps
inherited-acceptance.json qualified parent acceptance, when present
assets/ ticket attachments
artifacts/ worker output: reports, recipes, evidence; sandbox.json readiness record
acceptance-status.json acceptance-criteria ledger; written by `farmslot-agent ac` and recipe runs
task-actions/ task-local executable inputs retained with recipe proof
manifests/<manifest>.json action-manifest-v1 declarations
actions/<path> implementations and their contained helpers
subtasks/ child checklist units, written only by mark sub
index.json registry of registered units (id, parent step, paths, source digests)
<id>.md child checklist, materialized from a skill, template, or inline text
<id>-SIGNAL.json child signal (WorkerSignal + the parent link)
Typed path authority and task actions
@farmslot/protocol/task-layout owns the typed task-relative paths and references to their file-format contracts. Gateway staging, mirror, retention and family inheritance consume this catalog for task-local action inputs. Schema references reuse the existing payload owners and validators. Every named task path in the reference, skills or harness site must have an explicit contract entry and purpose. The shared @farmslot/protocol/scripts/check-task-layout-docs.mjs check runs on real Markdown and HTML files in their owning repository CI. Farmslot checks its own references without external credentials or copied consumer documents.
Task action manifests live at <task>/artifacts/task-actions/manifests/, with implementations and helpers under <task>/artifacts/task-actions/actions/. This is the single active action root. The full captured input tree and its recorded library digest travel with the proof; publication refuses missing or changed implementations and names the affected actions.
A historical follow-up may have no captured inputs at the canonical location. Its <task>/inputs/inherited-context.json then carries taskActionInputGaps: the source run, canonical path, action names grouped under their recorded library digest, and reauthor-and-revalidate with proofReuseEligible: false. The task can start and retains the original acceptance obligations, but cannot inherit that proof or select its old evidence package as fresh proof. The worker must create canonical inputs and execute new validation. A digest mismatch or damaged captured file remains a hard refusal.
Old root-layout files and publication decisions remain immutable and readable as historical artifacts. They are not an alternate implementation root. Inherited task files retain the existing read-only archive and owner-writable delivery policy. Task actions are named in the run report for manual harness triage.
Producers and consumers
One producer writes the shared layer on every surface: taskInit / farmslot-agent task init in @farmslot/agent-runtime. The gateway composes the same pieces (renderTemplatePlaceholders, buildTaskDocument, writeTaskDir) around its control-plane steps; project harnesses wrap the CLI with their defaults; recipe skills consume that shared task writer.
| File | Producer | Consumer |
|---|---|---|
<task>/TASK.md | task init; worker may append notes | worker, family follow-ups, review brief |
<task>/CHECKLIST.md | task init | worker, <task>/mark, progress parser, Command Center progress |
<task>/mark | task init; command is a project value (vars.mark_cmd) | worker |
<task>/checklist-target.json | role switch only | <task>/mark, progress path resolution (default when absent) |
<task>/SIGNAL.json | <task>/mark only | run monitor, publication gate, closeout |
<task>/inputs/handoff.json | task init | handoff closeout, learning packages, replay and eval, farmslot run |
<task>/inputs/worker-terminal-contract.json | task init from <project>/project.json worker_terminal | <task>/mark terminal commands, artifact contract check, monitor hold |
<task>/inputs/inherited-acceptance.json | gateway preparation after parent proof qualification | provisional PR-follow-up closeout; gateway revalidates the original parent independently |
<task>/inputs/bug-input.json | task init from the fetched ticket | farmslot run, review inputs |
<task>/subtasks/index.json | mark sub only | worker, gateway task watcher, review-workspace progress publisher, progress projection, view mirror |
<task>/subtasks/<id>.md | mark sub start (materialized from the named source) | worker, mark sub, progress projection, view mirror |
<task>/subtasks/<id>-SIGNAL.json | mark sub only | gateway task watcher, review-workspace progress publisher, progress projection, terminal contract check, view mirror |
<task>/artifacts/acceptance-status.json | farmslot-agent ac; a recipe run with a task dir | terminal contract check, PR body / gate summary, run detail AC panel |
<task>/artifacts/sandbox.json | project harness preparation | worker, evidence package, Command Center (later) |
<task>/artifacts/ files | worker | publication gate, review, retrospective (see worker artifacts by flow) |
Provenance
The selected checklist travels inside <task>/inputs/handoff.json as executionTemplate, identical in shape on both surfaces:
{
"executionTemplate": {
"selectionReason": "configured-default",
"id": "fix-bug/autonomous.mobile",
"sourceId": "package:example-checklists",
"flow": "fix-bug",
"platforms": ["mobile", "ios", "android"],
"labels": [],
"relativePath": "fix-bug/autonomous.mobile.md",
"sha256": "<source digest>",
"renderedSha256": "<CHECKLIST.md digest>"
}
}
sha256 is the template source. renderedSha256 is the checklist file as written. For a placeholder-free template they are equal, and equal to a skill-side materialization of the same id. Farmslot adds templateProvenance beside it (project repository revision, selection source, render time) for the run record; the reference is never stored twice. Task dirs written before 0.9 keep <task>/inputs/template-provenance.json; readers fall back to it for one release.
When the pack declares required_skills, the handoff also carries requiredSkills: the one frozen required skill set the dev worker and its review load. See project packs: Required skills.
Retained task tooling
farmslot task init uses the shared runtime producer. It retains the CLI distribution and selected provider, library and configuration bytes through the immutable installation mechanism. <task>/inputs/recipe-binding.json records the selection; <task>/artifacts/harness-provenance.json binds its bytes and the executable. The runtime owns this receipt and the installation pin manifest that verifies it. A provider is never recorded as the CLI. Full development workspaces refuse with TASK_INSTALL_UNSUPPORTED; task pinning uses the existing immutable CLI installation or a self-contained package install.
farmslot task verify <task-dir> --json checks the retained bytes before a wrapper invokes the recorded executable. task mark and task closeout use the retained provider's gates and policy. New frozen markers always enter that CLI; FARMSLOT_MARK_CMD cannot bypass its gates. Existing markers retain their recorded behavior. Product source and task recipes remain editable. Verification writes no files, and older receipts without bindingIdentity refuse without rewriting their original markers.
The root task commands consume @farmslot/recipe-cli/harness's projectTaskExecution, verifySelectedTask and withTaskProjectHost. TaskInitSpec.execution, typed by TaskExecutionInput in @farmslot/agent-runtime, connects that selection to the one task producer. The receipt's retainedInputs lists original paths, retained paths and content digests. pin identifies the producer-owned installation pin. Verification compares its manifest with the task receipt before loading a recorded executable. The installation pins live under the selected FARMSLOT_HOME. The producer and verifier use that existing home selection; task data cannot choose another store or authorize another provider source.
When FARMSLOT_HOME is unset, the pinned CLI recovers it from its logical invoking path under <home>/task-pins/<pin>/cli or layout 2's <home>/state/task-pins/<pin>/cli, before loading checkout environment or workspace state. A candidate is accepted only when its packages/cli/bin/farmslot.mjs resolves to the running CLI module. If that path has no verified pin home, the CLI follows executable-file symlinks, resolving relative targets against the physical link directory, then scans again. A symlinked pin store preserves its logical home when it contains the running CLI. An explicit home still takes precedence. Receipt verification continues to enforce the selected pin store and producer manifest.
The accepted hosted initialization contract, ADR-068 Amendment 5, applies this same producer on the execution node. The gateway supplies task data and mirrors its result; it does not replace the generated marker or task provenance. All affected active consumers migrate before activation, and the replaced producer is deleted. Existing tasks and receipts are not upgraded.
Provider retention includes its owning tooling workspace and declared installed dependency closure, independently of recipe-library discovery. The existing retained-input mappings and digests cover sibling imports and local dependency links without widening the selected recipe root or retaining the product checkout.
Handoff metadata
<task>/inputs/handoff.json is the run's identity for closeout and learning packages:
| Field | Farmslot value | Skill value |
|---|---|---|
attemptId | run id | random UUID |
surface | farmslot | skill |
project | project name | checkout basename |
repo | owner/name from repo_url or ci.repo | owner/name from the git remote |
domain | effective run domain, when any | --domain, when any |
flow | flow type | task kind |
task | title, sourceKind (jira, github-issue, github-pr, text), ticket, source URL | title, text or file, ticket, ref |
task.acceptanceCriteria | the ticket's criteria, in order; position N is ledger id AC-N | --acceptance values, same ids |
taskDocument | <task>/TASK.md | <task>/TASK.md |
report | the terminal contract's complete.report (<task>/artifacts/pr-description.md for dev / fix-bug) | <task>/artifacts/pr-description.md (dev / fix-bug) |
learnings | <task>/artifacts/learnings.md | <task>/artifacts/learnings.md |
Deterministic checklist checks
ADR-064 defines task-owned command receipts before publication.
Its CI decision check context amendment owns the read-only gate/current comparison. The linked CI decision specification defines retained provider snapshots and refresh availability; those reads do not replace command receipts or resolve publication gates.
Public surface
<project>/project.json may set ci.local_check to a nonempty portable shell command. The built-in project uses yarn ci:local; the repository quality job calls the same script. Its guard list is shared, formatting is scoped to changed files when Git supplies a base, and tests requiring a tmux server remain CI-only.
The shared task writer freezes each declaration under the deterministicChecks field in <task>/inputs/worker-terminal-contract.json, with checklist, stepNumber, reference and the resolved command. Task-init callers supply command references through their existing vars. Missing command references or malformed declarations refuse initialization. No new mark flags or top-level SDK functions are added.
Implementation checklists MUST declare [DETERMINISTIC: ci.local_check] for code validation.
Workers MUST call ./mark N and inspect failures rather than selecting or launching
commands. The frozen script MUST select changed files and affected tests rather
than a full suite. Reviewers MUST only read existing CI results, receipts and logs.
The retired CI_PARITY_STEP placeholder MUST NOT be used.
A step that produces proof MAY declare the artifact it writes on its own row, as
- [ ] 9. Retain the failing baseline run [PROOF: artifacts/recipe-baseline-run].
The path MUST be inside the task directory. ./mark N MUST refuse the tick while
that path is absent or empty, and completion MUST refuse a checked step whose
declared proof is missing or was written after the step's last mark; the worker
MUST re-mark the step to restate the claim over repaired evidence. A declared path
MUST resolve inside the task directory; one that resolves elsewhere through a
symlink MUST be refused. Completion MUST inspect only the declarations of the
checklist that is completing. A step without a declaration keeps its existing
behaviour (ADR-064 Amendment 5).
Steps MUST be claimed in order: ./mark N MUST be refused while any earlier step
is unchecked, deterministic steps included, and completion MUST refuse a checklist
whose checked steps have an unchecked step behind them. A step title MAY carry
[OPTIONAL: <when it does not apply>]; only such a step MAY be skipped, and only
through ./mark N --skip "<reason>", which MUST record the reason in the ledger.
A skipped step MUST NOT run its deterministic command and MUST NOT be required to
produce its declared proof. A step without the marker MUST NOT be skipped, and
completion MUST refuse a recorded skip on a step the template does not declare
optional. The declaration MUST come from the frozen terminal contract: a marker
present only in the checklist file MUST NOT grant a skip or waive a declared
proof. One step MUST NOT carry both [OPTIONAL: <when>] and
[DETERMINISTIC: <reference>]: a step a command receipt proves cannot also be
one the worker may declare inapplicable, and freezing the declarations MUST
refuse that template, naming the step (ADR-064 Amendment 7).
Mark and receipt rules
./mark NMUST reuse a receipt only when the frozen command, current publishable-input hash, successful completion and recorded log integrity still validate. Reuse MUST leave the receipt and log unchanged. Otherwise mark MUST execute the declared command itself before checking the box. This also applies after a complete signal. Execution uses the Git checkout containing the task, or the caller's target checkout when a standalone task is outside Git. The process inherits the configured environment and runs without a login shell.- On execution, mark MUST persist a running record first, then an immutable output log and a schema-version-1 completion receipt under
<task>/artifacts/deterministic-checks/<checklist>/<step>.json. The receipt records command, reference, checklist, step, source-input hash, timestamps, exit code, signal and the relative log path/hash. Tracked submodules bind their checked-out commit, or their recorded gitlink commit while uninitialized. Uncommitted submodule work MUST fail closed with a commit-and-rerun hint because the parent repository publishes a gitlink, not those local files. - Only exit zero, unchanged publishable inputs and successful receipt persistence permit checking the box. Failure, interruption and missing configuration MUST refuse completion. Bulk/terminal marks and checklist skip flags do not waive these checks. Custom mark engines that cannot produce receipts cannot satisfy declared steps.
- Publishable inputs are Git's tracked and nonignored untracked file inventory, paths, file permissions, file bytes or symlink targets, including tracked deletions. The task directory's owned inputs/outputs are excluded. Commit metadata is excluded, so committing identical checked content preserves a pass. Failure to identify the checkout or inputs fails closed.
- The artifact checker MUST reject absent, failed, interrupted or stale receipts, changed commands, and missing/changed logs, independently of checkbox state. The active role's frozen declarations apply; role initialization freezes its own materialized checklist through the same writer.
Publication and display
Package preparation and publication MUST validate receipts on the selected checkout. An older node checker that cannot return verified records fails closed. The package carries one optional deterministicChecks projection with command, state, exit code and log path; Command Center and Companion render it and open logs through their existing artifact viewers. After role cleanup, the last completed source-fix checklist supplies the final receipt. Read-only review checklists do not replace it. Restoring the parent MUST retain its initialized command declarations. Source or receipt changes after review require package refresh. Evidence-only refreshes of already published packages retain their archived source proof.
Receipts prevent skipped checks; they are not an attestation against a worker forging its task files. The existing trusted task initialization, artifact boundaries and publication authority still apply. Harnesses invoke the same mark/checker behavior and consume the same versioned records instead of implementing another checker.
Outcome file: one name on both surfaces
dev and fix-bug workers finish with <task>/artifacts/pr-description.md whether Farmslot dispatched the run or an engineer ran the skill. It is the PR body in the repository's PR-template shape and carries the proof summary (what changed, root cause, validation, evidence paths). Most runs want a PR, and the file is usable before anyone decides to open one.
| Stage | Farmslot | Skill |
|---|---|---|
Worker outcome (terminal contract complete.report) | <task>/artifacts/pr-description.md | <task>/artifacts/pr-description.md |
| Publication | the gateway fills the evidence section from <task>/artifacts/evidence-manifest.json and publishes after the human gate | the engineer uses the selected evidence and <task>/artifacts/pr-description.md, then a PR is opened only on request |
review-pr writes <task>/artifacts/report.md (with its QA artifacts) on both surfaces; no-change writes <task>/artifacts/no-change-report.md. <task>/inputs/handoff.json report names the outcome file, so closeout and learning packages read the same file wherever the run happened.
Layers: shared spec, control plane on top
Both surfaces produce the same task directory. Without the control plane (an engineer running the skill) the first two layers exist; with it (Farmslot) the last two are added beside them, and no shared file is renamed.
| Layer | Producer | Files | Surfaces |
|---|---|---|---|
| Worker outputs | the agent following <task>/CHECKLIST.md | <task>/artifacts/pr-description.md, <task>/artifacts/report.md, <task>/artifacts/no-change-report.md, <task>/artifacts/learnings.md, <task>/artifacts/recipe.json, <task>/artifacts/recipe-runs/<attempt>/, <task>/artifacts/recipe-coverage.md, <task>/artifacts/recipe-quality.json, <task>/artifacts/evidence-manifest.json, <task>/artifacts/validation-summary.md; optional tool logs <task>/artifacts/coverage.log and <task>/artifacts/jest.log; child records <task>/subtasks/index.json, <task>/subtasks/<id>.md, <task>/subtasks/<id>-SIGNAL.json | both |
| Harness readiness records | the retained harness and task initializer | <task>/artifacts/sandbox.json, <task>/artifacts/harness-provenance.json, <task>/artifacts/operations/<operation>.json, <task>/artifacts/operations/<operation>.log | both |
| Gateway-owned | the control plane | <task>/artifacts/diff.txt, <task>/artifacts/diff.txt.previous.<revision>, <task>/artifacts/diff-stat.json, <task>/artifacts/session-metrics.json, <task>/artifacts/workflow.mmd, <task>/artifacts/pr-package.json, <task>/artifacts/pr-package.md, <task>/artifacts/publication-gate-<slug>.md, <task>/artifacts/review-<round>/, <task>/artifacts/review-<round>.json, <task>/artifacts/review-<round>.md, <task>/artifacts/review-loop-<round>/, <task>/artifacts/publication-packages/, <task>/artifacts/pr-package-evidence/, <task>/artifacts/baseline-marker-verification/ | Farmslot |
| Review-loop outputs | reviewer roles and the change ledger | <task>/artifacts/review-feedback.md, <task>/artifacts/review-feedback.<context>.md, <task>/artifacts/review-result.json, <task>/artifacts/review-result.<context>.json, <task>/artifacts/pipeline-review-loop-<round>/, <task>/artifacts/iteration-diff.txt, <task>/artifacts/iteration-diff-stat.json | Farmslot |
The gateway-owned row lists the names recognized by isGatewayOwnedArtifactMirrorEntry in services/gateway/src/core/artifact-copy-policy.ts recognises: those files are never mirrored back from the slot and never count as worker evidence. Review-loop outputs are mirrored like worker files but belong to the control plane. The control plane also writes <task>/inputs/runtime-capability-catalog.json and the inherited context files. The supplied plan remains <task>/inputs/plan.md on both surfaces. A new gateway feature adds a name to one of these rows; it does not reuse a worker name.
Shared <task>/inputs/ names: <task>/inputs/bug-input.json for the ticket as fetched and <task>/assets/ for its attachments, on both surfaces. Task directory paths still differ (temp/tasks/<flow>/<slug>-<stamp> on the farm, temp/tasks/recipe-cook/<stamp>-<slug> for the skill); nothing reads the path, so it stays a naming difference.
Simplification ledger
Kept current with the layout. Each row is something the layout still carries that a good default could remove. Rows leave when shipped or rejected. Shipped 2026-09-13: one task-dir producer; provenance folded into <task>/inputs/handoff.json; the separate ticket-comments file removed; <task>/checklist-target.json optional for readers. Shipped 2026-09-14: the gateway no longer writes the default-valued <task>/checklist-target.json (every node runs the 0.9 <task>/mark engine).
| Candidate | Today | Simpler default | State |
|---|---|---|---|
| two naming schemes for review outputs | <task>/artifacts/review-feedback.<context>.md / <task>/artifacts/review-result.<context>.json and numbered <task>/artifacts/review-<round>.json / <task>/artifacts/review-<round>.md records | one scheme, one row in the layers table | candidate |
| harness identity | PATH resolve through the pack's recipe_runner_resolve_cmd on the farm, task-local lock on the skill | one preparation step both surfaces run, which also writes the readiness records | decision open |
| shared dev / fix-bug checklists | some pack defaults still select project templates; lightweight interactive dev keeps its operator plan | select Cook templates within ADR-049 adoption scope; review adoption needs separate approval | partial; remaining migrations need explicit approval |
| task directory path | <flow>/<slug>-<stamp> vs recipe-cook/<stamp>-<slug> | leave; nothing reads it | rejected |
What travels to the slot
Dispatch copies <task>/TASK.md, then the task-root sidecars (<task>/mark, <task>/CHECKLIST.md, and <task>/checklist-target.json when present), then <task>/assets/, <task>/inputs/, <task>/artifacts/, and <task>/subtasks/ as directories. Re-sync and warm-session handoff use the same list. At completion the gateway mirrors <task>/artifacts/, <task>/TASK.md, and <task>/CHECKLIST.md back beside the orchestrator copy as <task>/TASK.md.worker and <task>/CHECKLIST.md.worker, and every file under <task>/subtasks/ as <task>/subtasks/<name>.worker from a directory listing — child ids are chosen at registration, so there is no fixed name list.
A slot-free static review workspace (ADR-058) mirrors the same directory into its operator-visible <workspace>/view/, under the worker's own names rather than *.worker, so <task>/subtasks/index.json's own relative paths still resolve there after the workspace is cleaned up.
The mirror travels one way. Worker-mirror files are orchestrator-owned output written from the slot, so the outbound copy skips them: re-dispatching, nudging, or warm-handing off a task directory that already completed once must not put stale copies of the worker's own files back beside the live ones.
<task>/subtasks/ is also the one directory the gateway creates on the slot without writing anything into it: both file-watch primitives observe a file through its parent directory, and the directory otherwise appears only with the first mark sub start, so the task watcher would never see a child registered mid-run. The registry, the child checklists, and the child signals stay <task>/mark-written. <task>/artifacts/ is created the same way and for the same reason, so the acceptance-ledger watch has a directory to observe on a task dir that has not written one yet; the gateway writes nothing into it either.
Project addendum
A project may ship <project>/templates/task-document.md. The writer renders it with the same placeholders as worker templates and inserts it into <task>/TASK.md before the checklist pointer. Use it for project tooling the worker needs before the first step (runner resolution, environment notes). It is not a checklist: checkboxes there are not counted.
Boundaries
-
The checklist never contains run data. Ticket text, acceptance criteria, and slot facts live in
<task>/TASK.mdand<task>/inputs/. -
<task>/TASK.mdis never enumerated. A- [ ]inside an acceptance criterion cannot shift a step number. -
A ticked box is not proof. Proof is the recipe run, its evidence, and the artifacts the terminal contract requires.
-
<task>/SIGNAL.jsonis written by<task>/markonly. Hand-written signals are rejected by the monitor. -
<task>/subtasks/is written bymark subonly, and a step may own one child unit for the life of the task directory. A child unit is observed, never spawned: registering one writes files and starts no process. A parent terminal mark is refused while any registered child is unsettled, by<task>/markand again by the gateway's terminal check. Settled iscompleteordone: ablockedchild is terminal for the run but keeps its step. The verbs and their refusals live in Agent runtime. -
A child unit is not a role switch. It never writes
<task>/checklist-target.jsonand never changes the run's active task file, so a child may hang off<task>/CHECKLIST.mdor off a role checklist such as<task>/REVIEW.md; the parent link names which. A child progress update is live only while its parent checklist is the active one, andrunningwith no recent mark projects asstale— a projection only, never a status in the file. -
<task>/artifacts/acceptance-status.jsonis a task-namespace projection of the selected recipe engine's schema-2 ledger. The engine is the sole normal verdict authority; agent-runtime transfers its claims and never reduces or records manual verdicts. A QA task merges its case executions by claim id, and each row names its case execution (QA case ledger). Writes and current successful completion reject schema 1. Retained schema-1 ledgers are display only with an explicit limitation; migration preserves original bytes and frozen decisions, never manufactures moments or task bindings. Recipe verdicts come from eligible executed expectations and required occurrences; action success alone is not proof, and visual claims require verified review. Successful completion requires a current verdict for every registered criterion even without an acceptance opt-in. PR follow-ups may consume qualified parent proof under ADR-062; otherwise missing ledgers or unreadable handoffs refuse. Weak or missing engine verdicts refuse unless the resolved contract setsacceptance.allowWeak. No-change and self-review keep their existing outcome contracts.acceptance.requirecannot disable successful-completion enforcement. Per-flowacceptance.allowWeakoverrides inherit unspecified keys. Standalone validation can request the same check with--require-acceptance-status. Current acceptance readers never derive relationships from manifestcoversor substitute<task>/artifacts/recipe-coverage.md. -
Schema-2 verdicts and task projections are engine-owned;
acis read-only and cannot override them. With a gateway-derivedclaimReviewGate, completion validates the selected package (for a QA case ledger, each row's case package) through the canonical SDK reader and can present unresolved verdicts at human review. Approval remains blocked. Only the verifiedrun.overrideClaimoperation records an untestable exception in the Run store; engine/task bytes stay unchanged. Without a human gate, completion keeps its existing refusal. ADR-062 Amendment 4 defines authority and freshness. -
Lightweight interactive dev keeps its own pairing:
<task>/CHECKLIST.mdis the operator-agreed plan and<task>/TASK.mdthe context.
See also: Agent runtime, Template variables, and the worker artifacts by flow reference on the documentation site.
Read-only task status
Task status readers associate a task with <task>/inputs/recipe-binding.json's recorded
checkout target. Branch text supplies no task identity. Legacy skill tasks keep
their local progress semantics. A handoff with surface: "farmslot" binds its
attemptId to the parent run, independently of a worker signal's attempt ID.
The shared task view observes that run through the existing CLI lifecycle stream.
Worker completion does not close a watch while its parent is reviewing or
waiting for a decision. Loss of connectivity is unavailable lifecycle, never an
inferred completed run. A watch retains its bound run through task-file cleanup.
Task ownership accepts the recorded checkoutRoot or identity.target exactly,
after realpath normalization. This lets a registered nested app and its checkout
inspect their bound task without treating sibling paths as the same app.
Checkout recipe artifact ownership
After writing its canonical invocation, the SDK records <task>/artifacts/recipe-ownership/<recipeRunId>.json for checkout-local temp/recipe/calls/<call> and temp/recipe/runs/<attempt> packages. It records schema version 1, the initialized task's runId, checkout-relative taskFile and bucket path, and the invocation's recipeRunId. This attributes diagnostic output without registering acceptance claims or selecting task proof. Release reads only that task's receipts, never the slot-wide recipe history, and verifies the bucket still contains the named invocation.
Full release and direct terminal teardown collect only receipts matching their terminal, non-reloadable task/run owner, before publishing slot readiness. Direct teardown preserves task inputs and runner observations. Automatic cleanup that retains a failed checkout or local work also retains its recipe output; explicit non-replay reclamation can collect it. It retains all owned package bytes in the private run archive, then rechecks the release fence, task identity and package snapshot before removal. keepWork, protected publication/replay states, foreign or unknown receipts, links, nested checkouts, and changed evidence preserve the affected source. Legacy output without ownership is not reassigned by timestamps or filenames.
The receipt codec and node batch transport live at @farmslot/recipe-runner/runtime/artifact-owner. The SDK's artifact writer and Gateway's existing scaffolding collector are its consumers. No CLI command, flag, RPC method or proof-binding policy is added. Calls without an initialized worker identity remain unowned and are preserved.