Execution-instruction delivery
Operator instructions combine workflow/project scope with delivery settings.
workflow.execution_instruction.create, .update, and .set_scope accept
before_creation, on_every_read, when_entering_stage,
when_creating_release booleans and a stage_buckets list. Omitted fields retain stored settings on edits; creation
and existing rows default to Before creation + On every read, with no stage targets.
At least one delivery point must be selected. When entering stage requires
at least one bucket: idea, planning, refined, implementing, reviewing,
implemented, or release. Invalid selections refuse with delivery_invalid
and name the selection to correct; invalid bucket names refuse as payload_invalid.
Targets come from the item's pinned workflow definition's board_bucket,
so custom stage ids work without being added to a separate instruction map.
workflow.execution_instruction.list returns delivery_options beside the
rows: stage_buckets (the bucket vocabulary above) and defaults (the
new-instruction delivery), both read from the server's delivery model.
In the dashboard's Workflows page, the Execution instructions panel shows each
instruction's delivery points and selected stage buckets beneath its scope.
Choose New instruction or Edit to change the four delivery checkboxes and
stage-bucket checkboxes. A serving build that predates When creating release
serves no such field, and the panel omits that checkbox. The bucket list and new-instruction defaults come from
the list's delivery_options, so the panel holds no copy; a serving build that
omits them disables New instruction and Edit and shows
delivery_options_unavailable with the recovery. New instructions select
Before creation + On every read. Bucket controls are disabled until When entering stage is selected;
toggling it off keeps the draft's bucket choices. Saving requires at least one
delivery point and, for stage delivery, at least one bucket. An invalid draft
shows the required correction in the editor before any write is sent.
Before filing, read yoke workflow execution-instruction resolve --workflow W --project P --full. Its default delivery point is before_creation; the
--execution-instructions-considered attestation covers only those instructions.
Creation receipts describe that same set. The web form uses the same resolver.
Item reads resolve On every read instructions plus stage-entry instructions
targeting the live bucket. Full item reads print one full copy. The default
yoke items get read, yoke items detail get and the creation receipt print
one line counting the applicable rules and naming yoke items get ITEM --full.
Field, section and Progress Log reads print only the requested text; add
--full to a field read for the instruction prose. Work-claim acquisition
delivers the full instructions for the item; composed worker launch mandates
omit them.
Delivery is stateless, tied to these existing events; no session tracking is
added. JSON reads retain the complete instruction facts. A successful
lifecycle.transition.execute returns execution_instructions containing
stage-entry instructions for its entered bucket. Failed transitions return none.
Instructions remain separate from item content and never round-trip into it.
When creating release
Release creators are itemless, so item-bound points never reach them. An
instruction that selects When creating release is returned as
execution_instructions by deployment_runs.create and printed once by
yoke deployment-runs create, single run or release set, including replays.
Scope is project-only at this point: any workflow scope qualifies, but an
instruction with no workflow scope still reaches nothing. watch deploy
does not print them. Inspect them with yoke workflow execution-instruction resolve --project P --delivery-point when_creating_release --full; --workflow
is required for every other point and ignored for this one. To opt an
existing instruction in, resend its current prose with the flag:
yoke workflow execution-instruction update {instruction_id} --stdin --when-creating-release < current-prose.txt
The resolve function also accepts delivery_point and stage_bucket. To inspect
stage delivery directly, run yoke workflow execution-instruction resolve --workflow W --project P --delivery-point when_entering_stage --stage-bucket reviewing --full; stage-entry resolution requires a bucket. on_every_read
includes stage targets when a bucket is supplied. Summary descriptors retain
the selection in their full-read command.
CLI writes expose --before-creation / --no-before-creation, --on-every-read
/ --no-on-every-read, --when-entering-stage / --no-when-entering-stage, and
--when-creating-release / --no-when-creating-release.
Repeat --stage-bucket BUCKET to replace the target list; --clear-stage-buckets
clears it. Disable stage delivery in the same edit when clearing an enabled target.
yoke workflow execution-instruction create --content "Run implementation checks." --no-before-creation --no-on-every-read --when-entering-stage --stage-bucket implementing
yoke workflow execution-instruction set-scope {instruction_id} --all-workflows --all-projects
yoke workflow execution-instruction update {instruction_id} --content "Run review checks." --stage-bucket reviewing
Read each operation's --help before changing scope or delivery. Delivery and
scope edits are validated together before replacing bindings; prose-only and
scope-only edits preserve the instruction's delivery settings.
The delivery columns converge additively on boot. Existing instruction rows retain their prose and scope and acquire defaults; no data rewrite or separate migration entry is required.
yoke workflow execution-instruction list lists instruction ids and their first content lines. Add --full to read complete content under one ## <id> <title> heading per instruction; --section can select that heading. --json retains the complete response, including scope and delivery settings.
Keep portable guidance in shipped homes
Before adding an instruction, classify its clauses by audience and authority:
| Clause | Maintained home | Instruction appearance |
|---|---|---|
| Portable product rule or recipe | Public concept page or agent rules | Concise action and exact installed or web pointer |
| Project policy, installation topology, credentials or current operator state | Its authorized project/private owner | Only the scoped facts the receiving actor needs |
| Source-contributor procedure | The repository's contributor documentation | A pointer only for contributors with that source |
The teaching standard owns how guidance is written; agent rules own agent judgment. A public rule does not inherit an installation's release policy, account choices or current holds. Source-contributor maps and generated research views do not become an installed project's requirements.
To extract reusable guidance from an existing private instruction or strategy document, read it through its registered list/get/resolve command into private scratch. Inventory every clause and old pointer; record only neutral summaries, classifications and canonical destinations in shared evidence. Keep full text, secrets, account details and current operator state out of public repositories and logs. Verify delivery in the actual receiving context before replacing the private copy with its concise pointer. Immediately before an authorized source replacement, re-read the private record and save fresh durable private rollback evidence; an earlier planning capture is not that rollback.
Inside an installed project, point at .yoke/docs/<concept>/<page>.md from the
matching release. Outside a project, use the corresponding
https://stage.upyoke.com/docs/<concept>/<page> route and label its service identity;
a global session cannot assume this directory contains .yoke/docs. Preserve
the instruction's scope and delivery settings. A pointer alone does not prove
that a main agent or worker received the required guidance before acting.