Rendered from docs/obligations/0162-spec-7-prints-a-package-version-that-no-check-compares-with-the-recipe.md in the Headwater corpus. Every document on this half of the site is typed by the taxonomy the descriptor names: corpus.json.

Spec 7 prints a package version that no check compares with the recipe

Context

Spec 7 prints a worked assembly recipe in a fenced block. Until 2026-09-06 that block read from.package: headwater/standard@3.4.0 and selected [design-spec, decision-record, standards-spec].

Both halves were wrong and nothing reported either. The package stood at 4.0.0, so the version had been stale across at least four minor releases. The selection did not resolve at all. design-spec and decision-record between them name purposes, kinds and a voice regime that evidence-and-obligation declares. Referential integrity refuses the triple over seven dangling names. So the specification printed a recipe the engine refuses, in the section that a first adopter reads to learn what a recipe is.

headwater check --strict was green over that block on every run. No rule reads a fenced code block for anything, and link.fragment.unresolved reads links rather than YAML. No fixture and no CI job compares a specification example with the source it describes.

The example is now correct and nothing holds it correct. It was rewritten to be the recipe this repository ships, at taxonomy-source/headwater-standard/assemblies/starter/assembly.yml. So one version number now stands in two places that must agree: the fenced block, and the from.package line of the recipe. A third place already constrains the recipe, because assembly::read refuses a recipe whose from.package does not pin the version package.yml declares. The engine holds two of the three and reads none of the prose.

HW-DR-0053 rules where a selection may be declared. This record is about the copy of it that lives in prose.

Obligation

A version or a selection that this corpus prints as a worked example is a claim about the tree, and something has to read it. The corpus owes one of two things. A check that compares a specification example with the artifact it names, or a ruling that an example is illustrative and names no real version.

The general shape is wider than this one block. This corpus states values in prose that no rule reads. The specification part on distribution is where such a value is most likely to be copied by a stranger. A reader who copies a stale example does not get a correction from any tool this repository ships. They get seven referential-integrity errors that name none of the three things they need.

Discharge

Any of three closes it.

A check that reads a fenced example against its source. The narrow form compares the from.package of every YAML block in docs/spec/ that carries an assembly: key against the package version taxonomy-source/headwater-standard/package.yml declares. This is mechanical and total, so it is an error rather than an advisory rule under the fixability bar.

A generated example. The block is written by headwater generate from the recipe, and generate --check then refuses a hand edit to it. This costs a new projection and it removes the class rather than the instance.

A ruling that an example names no real version. The block reads headwater/standard@<version> and the prose says where the real number is. This costs nothing and it weakens the example, because a recipe that cannot be copied is a recipe a reader cannot run.

Nothing here is discharged by rewriting the example again. The example is correct today, and it was correct on the day it was written too.

This record is discharged, by the first of the three. The example went stale a second time: on 2026-09-30 it printed headwater/standard@4.0.0 while the recipe pinned 4.13.0. #1487 added the_recipe_spec_seven_prints_is_the_recipe_this_repository_ships in engine/crates/resolve/tests/spec_seven_recipe.rs. It reads the fenced YAML block under An assembly has two consumption forms and taxonomy-source/headwater-standard/assemblies/starter/assembly.yml. It fails unless assembly, package, version, from.package and from.bundles are equal in both. It also fails unless the first line of the text diagram is the same from.package. The case failed on the tree before the fix and passes after it. The check is a test in the engine suite rather than a rule of headwater check, so it holds this repository's example and no adopter's. Step 1 of the taxonomy release in docs/how-to/cut-a-release.md now names spec 7, because the next version bump must move it.