headwater

headwater tells a repository which releases of what it depends on are newer than what it runs. It reads what the repository declares, asks where each dependency is published, and reports every newer release with the words upstream wrote for it. It looks often for the dependencies the repository’s authors care most about, and less often for the rest. It never changes the repository, never judges what a release means, and never acts on one: a person or an agent decides, and the change is theirs (5, 36).

Why it exists

A repository runs versions of things published elsewhere, and upstream keeps publishing. Dependency updaters make the change as well: they open a branch per bump and wait for a review. Where agents work in worktrees, a change already has its own path: a worktree, the repository’s gate, a landing through sluice. What the agents lack is the knowledge to start from: which releases exist that the repository does not run, what upstream said of each, and which advisories name a version it runs.

headwater supplies that knowledge and stops there. swancloud, the first fleet to run it, watches the tools it pins with a release adapter of its own, which finds releases and reads their notes. headwater does that work for any repository, for every dependency a profile can read (Part C).

What it promises

• The pin alone decides what is new (9). headwater keeps no record of what it reported, so a release stays in every report until the pin reaches it or an acknowledgement leaves it out (21). A fixer clears a release by landing the bump.
• Upstream’s words arrive as upstream wrote them (11). headwater gives each release’s notes whole, or the part asked for with a way to read the rest (12), and no model reads them inside headwater.
• A release has one name for ever: its dependency’s identity and its version (10). A recorder that keys on it keeps each release once.
• Asking what headwater holds costs no source anything (17). The answer comes from what headwater keeps, and writes nothing.
• Only acknowledgements cannot be rebuilt (29). The next scan rebuilds everything else headwater keeps.
• Every asker gets the same answer (32). A person at the command line, an agent at a session’s start and a pane in herdr’s sidebar ask one core and read one form (33, 35).

Where it stops

headwater moves no pin, builds nothing, tests nothing and lands nothing. A fixer does that, and the repository’s own gate decides whether it lands. headwater reports what the repository’s authors chose, never what those dependencies depend on in turn; a vulnerability scanner reads the whole graph. It never summarises notes or judges a release. It tells nobody on its own: a surface tells, when its asker asks. Licences and bills of materials are outside it (section 8).

Where it sits

headwater stands alone, with plugins for Claude Code and herdr. Its Flywheel plugin holds an adapter part that prints each release as a capture for millpond, the inbox, which lands each release once and lets curation turn it into work. Whatever bump comes of it lands through sluice. headwater never knows which inbox records its releases (design/capture/design.md).

A release that needs judgment, such as a major version or notes that announce breaking changes, can go from headwater’s herdr plugin to a sounding. A sounding is one question, worked by one session in one place, ending on a conclusion the operator decides.

How to read this book

The chapters follow a release from the declaration that names its dependency, through the scan that finds it and the brief a fixer reads, to the capture that records it. The glossary defines each term once. The open questions page lists what the operator has yet to rule, grouped by the chapter each ruling would change.

The appendix is the statement of invariants, included from design/headwater/requirements.md. Part A is what must hold of headwater, Part B its contracts across five seams, and Part C the profiles that satisfy them. A number in parentheses cites a clause of it.