🜄Headwater

How it works Compare Proof Tutorial

Decision records

Q64 — Whether intent-time routing gains an offline embedding path in shadow mode
A relation declares lifecycle_sensitive for itself and a core requirement demands it of a family
A kind narrows the value set of an enumerated facet, and nothing else can
The vendored package root moves under .headwater and the old root is named in a refusal
The front-matter key that carries a minted identifier is id
No paragraph limit joins the language rule, because most paragraphs past six sentences hold one topic
A paragraph limit counts sentences under the language rule and never words
The matched purposes take turns at a route budget, and each pointer states what reached it
A route offers a document and never a heading inside it
The binary is the only interface an adopter must run, and every integration point outside it is declared
A probe budget prices a run identity fixed before the run, and a committed transcript, and a sweep has neither
Criterion 5 admits naming or extending a core-serving kind, and a facet-only entry ships no templates directory under criterion 2
Q66 — the corpus dashboard ships free and self-hosted, with tenant isolation stated as a data-model constraint from day one
The hand-authored decision register indexes a subset of the shelf, and stops asserting it supersedes the complete one
The resolved taxonomy is drawn by a verb that prints Mermaid and writes no file
Governs and traces_to are created by an agent, because a session proposes the line and a person types it
A live document that rests on a draft one is reported over every relation, because a draft leaves no record to cite
An engine release and a taxonomy release have disjoint tag namespaces and are cut independently
A taxonomy release publishes the source at the tagged commit and never ships the vendored copy
Each release states in its notes the release digest that a consumer pins
The runner image of the engine release build is written in the workflow because it sets the glibc floor
The citation comment of spec 5 is for an adopter's corpus, and this repository does not practice it on its own code
The live account of a domain is its own kind, split on the product and process line, and it draws on the records it cites
The APT repository is served from headwater.tools and signed by a subkey the owner's offline key certifies
Q67 — One library entry may address the keys of an entry it names in requires, and confluence holds over the dependency order
Harper does not become part of the engine now, and Q41 stands
An engine subsystem is described by a technical design spec on a shelf of its own, and its behavior stays where it is already written
A counted tombstone lists a digest of each withheld identifier, and a sealed one lists nothing
An editor integration starts headwater mcp for each query and does not embed the library
An evidence relation declares which end is the evidence, and discharges declares the source

All 103 on this shelf →

Rendered from docs/decisions/0089-a-taxonomy-release-publishes-the-source-at-the-tagged-commit-and-never-ships-the-vendored-copy.md in the Headwater corpus. Every document on this half of the site is typed by the taxonomy the descriptor names: corpus.json.

A taxonomy release publishes the source at the tagged commit and never ships the vendored copy

Context

Before this record, the reason lived only in the header comment of .github/workflows/release-taxonomy.yml (lines 21 to 33 on 2026-09-27).

This repository keeps two copies of headwater/standard. taxonomy-source/headwater-standard is the source. .headwater/packages/headwater-standard is the output of the last taxonomy publish that a maintainer ran by hand, vendored and committed next to the source. The header of .headwater/packages/headwater-standard/package.yml gives that four-step loop.

A release workflow could attach a zip of the vendored copy. That zip tells a reader when a maintainer last ran the second step of the loop. It does not tell a reader what the tagged commit publishes.

Decision

The taxonomy release builds the engine at the tagged commit and runs headwater taxonomy publish against taxonomy-source/headwater-standard at that commit. It attaches the output of that run. It never attaches a copy of .headwater/packages/headwater-standard.

The digest in the release notes is the digest that this run printed. It is not a digest carried over from the last time a maintainer regenerated .headwater/packages/.

Consequences

The tag and the artifact make the same claim: the artifact is what the source at this commit publishes. An adopter who runs headwater taxonomy vendor --expect <digest> checks the artifact in the same way that the release workflow produced it.

A vendored copy that is stale at the tagged commit does not reach an adopter through the release. It stays a defect of the loop inside this repository.

The release workflow needs a build of the engine, so a taxonomy release costs one release-profile build. The build uses --locked for the reason HW-DR-0091 states.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search