People learn a language by copying its examples. So do coding agents, and so do the models that read a specification as context. If a page shows a form the parser refuses, a careful reader's first attempt fails.
The Nika workflow language has an open specification, nika-spec, kept apart from the engine that runs it. The parser here is the reference engine's reader of .nika files, and nika check is the command that judges a file before it runs. On 12 October 2026 the spec repository merged a series of fixes with one theme: every form the pages teach as valid must be one the parser reads, and every green check must promise a run that can happen.
Checking the pages with the checker #
The broadest fix started with a test, described in its commit message:
Every complete workflow the pages show was saved alone and checked with the reference engine, and every fenced or inline form was checked as a fragment.
The result: "Twelve positive examples were refused, most for a missing permits block, and the stdlib reference read upstream tasks inside tool arguments."
The missing permits: block is the easy case. A workflow that reaches the network or writes a file must declare that reach, and an absent block grants nothing. The examples now declare what they use.
The second case teaches a rule of the language. Data from another task enters a task only through with:, a binding declared on the task, and the task body reads the local name. The standard library page used to pass input: "${{ tasks.X.output }}" straight into a tool's arguments, a read the reference engine refused. The nika:jq entry now reads, as a fragment of a task:
with: { order: "${{ tasks.X.output }}" }
invoke: { tool: "nika:jq", args: { expression: ".items | map(.price) | add", input: "${{ with.order }}" } }The quickstart now states the rule once: "another task's data crosses ONLY through with: (the binding is the edge)". A read anywhere else "is refused (NIKA-VAR-021, which nika check --fix repairs by hoisting it into with:)".
Small forms, copied often #
Other fixes were single lines, the kind that end up pasted into many files.
- A child workflow call was shown in five places as
invoke: { workflow: }, with no target. The parser refuses an emptyworkflow:. Each place now shows a call with a target, such asinvoke: { workflow: "./child.nika" }. - A teaching comment in a conformance case showed
with: { greeting: ${{ tasks.producer.output }} }. An unquoted template inside a flow mapping is a parse error (NIKA-PARSE-001). The comment now quotes it. - The failure text of one error code, which
nika explainrenders, named a recovery ason_error: recover. The parser refuses that form, becauseon_error:is a mapping with exactly one action. The text now showson_error: { recover: stand-in }.
The commit states the cost: "an author or a knowledge release that copied the form met that refusal".
A green check that promised too much #
One fix went the other way. In the language, a child workflow can be named by a registry reference, registry:owner/name@version. The static rules accepted a pinned reference as well formed. But no registry child resolves before the run, so its contract, its effects and its place in the call graph went unjudged, and the run refused it. The commit message says:
A green check promised a run that cannot happen.
The spec now says a check refuses a pinned registry target with NIKA-COMP-001, "as the run does", and that a filesystem child is the form today. The commit is careful about the cost: "this removes a false green, it does not take away a run that worked."
The schemas tell the parser's truth #
A schema here is a JSON Schema file that editors and tools use to validate a file before the engine sees it. Two of them had drifted from the parser.
The workflow schema let through things the parser refuses, and missed something it accepts. Its when: description named variables a condition cannot read. It accepted a ${{ }} string for temperature, max_tokens, max_turns and max_tokens_total, which the parser takes only as literal numbers within bounds. It lacked for_each.max_items, which the parser accepts. It still listed a vault secret source that the spec had withdrawn. All of that was corrected, and a retired version tag such as v1 is now refused.
The project schema, for the nika.yaml file that holds a project's settings and schedules, got the same treatment. Its commit lists the shapes it accepted and then says: "Both readers of nika.yaml refuse all of these." It also refused a legal name, and its cadence examples (dimanche 18h07, toutes les 6h) were forms the cadence grammar refuses. It now states what its two readers accept, and its cadence examples carry their time zone.
Contracts for five everyday tools #
The same day, the standard library page wrote down the everyday behaviour of five built-in tools that "failed ordinary projects or returned wrong data while the run succeeded". The commit lists the cases:
A Slack incoming webhook refused notify's body with no_text. The default fetch mode read a CSV export as HTML, so convert found no rows. A misconfigured prompt became a durable pause. A semicolon CSV became one column. An empty edit find rewrote the file.
The commit adds five behavioural fixtures for the convert, prompt and edit rules, and notes: "All five diverge on the current reference engine, which reproduces each defect." The engine's 0.123.0 changelog then records matching fixes, for example that nika:edit "refuses an empty find: instead of rewriting the whole file".
A protocol the engine never spoke #
The last fix removed a claim. The spec's canon, the file of language facts that other documents derive from, listed MCP revision 2026-07-28 as one the engine speaks, and as its latest. MCP, the Model Context Protocol, is how workflows reach external tool servers. The commit found that "the engine implements none of its requirements; its server only echoed the revision string from initialize." The row was removed. The matching engine change is in the 0.123.0 changelog: its MCP server "now answers 2025-11-25, the latest handshake revision".
Why it matters #
A specification is a promise to whoever implements it and whoever learns from it. A form that no implementation accepts is a promise nobody keeps.
Most of the fixes point the same way. When a page and the parser disagreed, the page changed to what the parser reads, or the check was made to say what the run says. The five built-in contracts are the exception: there the spec wrote the expected behaviour first, against an engine that still diverged, and the engine's 0.123.0 changelog records the matching fixes.
How it reached users #
The spec's changelog says it plainly: "This repository carries no release tag; the commit is the identity." The engine embeds one spec revision and names it in its SPEC_PIN file. The same changelog says that engine 0.123.0, published on 23 October, "embeds this spec at commit 6390b08eb9791ce49c63ee17f8466fab118cadb8", and every commit described here is in that commit's history. What the spec states and what the engine does are still two things: the engine side of each change is the one its own changelog records.
What it does not do #
- Agreement with one parser. The pages were checked with the reference engine. That shows the examples agree with its reader. It does not prove that another implementation reads them the same way.
- Refused forms are still shown on purpose. "Forms the text teaches as refused keep their codes." A page may still show a wrong form next to the error it produces.
- Registry children do not run yet. The commit says: "Until registry children run, a check refuses a pinned registry target". It gives no date for that.
- Not every contract has a fixture. The spec changelog notes that the fetch observation contract "admits
raw/jqonly, and notify has no receiver contract, so their rules have no fixture yet." - Reading is not running. The same day, the spec also added new forms, such as a prompt or a schema read from a project file. The engine's 0.123.0 changelog is explicit: "No run carries project files yet". Those forms are judged by
nika check, and a run refuses them before any task.
Read the spec's changelog and quickstart, or the earlier post An open spec, a copyleft engine.