Rendered from docs/process/obligations/README.md in the Headwater
corpus. Every document on this half of the site is typed by the taxonomy
the descriptor names: corpus.json.
Project process. These notes record how Headwater itself is built and run. You do not need them to use Headwater. Back to the specification
Process obligation records
The documents on this shelf, in the reading order this corpus derives.
- The CI job named "(advisory)" carries every blocking shell suite in the repository — The CI job named advisory blocks on eleven of its own steps, not the two its name describes.
- The skills fixture suite passes on an empty input set, and always fails in a clone that has not built the engine — The skills fixture suite passes on zero verbs counted, and fails in every clone that has not yet built the engine.
- Four inline gates in the workflow decide an exit status and no suite provokes one — Four named steps of ci.yml carry a shell decision procedure that ends in exit 1, no fixture suite drives any of them over a scratch input, and no shell of this repository is parsed or linted at all. (asserted, and no human has accepted it)
- The value rule writes adopter on every self-audit record and most of them wait on a build — The value rule prescribes waiting_on=adopter on every self-audit record, HW-DR-0030 defines that value as waiting on an outside corpus, and almost none of those records does. (asserted, and no human has accepted it)
- A bare none footprint is claimed as a literal path, so two disjoint issues collide — tools/run/run-dir.sh claim treats the literal string none as an artifact path with no special case. As a result, two issues that both report footprint none produce a spurious WAITS-ON even when they touch disjoint files.
- Three small run-tooling gaps from run 20260922-1121, filed together (discharged) — A missing project-board item for two issues, an interactive-shell grep shadowed to basic-regex semantics, and a stale hook-exit-code comment have no reader outside this repository. This record files the three together under the intake cap.
- hw-run-policy names a worktree-add workaround that Write/Edit refuses under this harness (discharged) — hw-run-policy tells a subagent needing its own workspace to make one by hand with git worktree add. Edit and Write on a file under that hand-made worktree are refused. That is because the write sandbox stays pinned to the worktree the subagent was launched into.
- The plan usage of one issue is known only as the average of its run — A build-order run reports the points of the owner's 5-hour and 7-day plan windows that it spent, divided by the issues it closed. A figure for one issue needs each dispatch priced by model and token type, then matched to the issue its pull request closes.
- A build-order dispatch passes no isolation, so a stage can inherit the parent worktree as its working directory (discharged) — hw-iterate now dispatches hw-build and hw-verify with isolation: worktree, and both agent files branch in the tree the harness gives them. Case 10 of .claude/agents/fixtures.sh fails on a loop agent that passes no isolation.
- No fixture holds the symlink case of new-worktree.sh, and a bare name of two dots leaves a branch behind — The worktree script's suite stays green when pwd -P is dropped, and --name .. passes the bare-name check and leaves a branch when git then fails.
- Two hand-remedy lines for hw-cargo in hw-run-policy may not earn their cost on every dispatch (discharged) — The hw-cargo line in hw-run-policy was not dead text, because the tool still waited on slot 1 alone when every slot was busy. The tool now takes whichever slot frees first, and the line is gone.
- ci-done.sh reads a cancelled run of another branch as a red result on a main merge commit (discharged) — The CI wait script counts every run that shares a commit, so a cancelled push run of a feature branch turns a green main merge red.
- CI builds no MkDocs site, so a generated page under docs/ is never checked against a strict build before merge — No CI job runs mkdocs build --strict, and this host has neither mkdocs nor rustfmt, so a new generated page and a clippy change reach main unchecked.
- Two merge hooks of this repository print a resolve flag that the verb refuses (discharged) — The merge-regenerate and merged-fold-check hooks tell the merger to run headwater taxonomy resolve --write, and the verb rejects --write because it writes by default.
- The site-review marker lives in the common directory of a clone, so one worktree's unreviewed merge blocks the push of every worktree (discharged) — The pre-push hook read a site-review marker that every worktree of a clone shared. #1273 removed the marker, its writer and its reader, because the site pages no longer hold a fold.
- No disk floor is stated for a build-order run, and nothing prunes the cargo pool — No stage prunes the pooled cargo targets, and nothing in tools/hw-cargo enforces the free-disk floor on the pool's volume. On 2026-09-27 the pool held about 160 GB and the root volume, which then held the pool, reached 95%.
- Subagents read skills from the shared checkout, and a worktree-isolated integrator cannot fast-forward it after a merge — Every agent of a run reads its skill text from the shared checkout. The integrator is told to fast-forward that checkout after each merge, but under worktree isolation nothing does, so later agents read stale skills.
- Thirteen run-tooling gaps from run 20260928-1109, filed together — Run 20260928-1109 surfaced thirteen findings about its own agents, hooks, run scripts and CI, none with a reader outside this repository. This record files them together under the intake cap.
- Eight run-tooling gaps from run 20260929-1205, filed together — Run 20260929-1205 surfaced eight findings about its own agents, hooks, run scripts and CI, none with a reader outside this repository. This record files them together under the intake cap.
- Seven run-tooling gaps from run 20260929-2201, filed together — Run 20260929-2201 surfaced seven findings about its claims, hooks, kills, pull request bodies and CI workflows. None has a reader outside this repository, so this record files them together.
- Five run-tooling gaps from run 20261001-1107, filed together — Run 20261001-1107 surfaced five findings about its CI toolchain step, the n8n fixture scripts and a wedged verifier. None has a reader outside this repository, so this record files them together.
- Thirteen run-tooling gaps from run 20261002-1233, filed together — Run 20261002-1233 left thirteen findings about the self-hosted CI runner, stale counts in CI records, shadow-log scripts and the build-order agents. None has a reader outside this repository. (asserted, and no human has accepted it)
- Three run-tooling gaps from run 20261003-1026, filed together — A CI record states a step count that the job has passed, and the relevance grade's fixtures and record are ungoverned with a surviving mutant. None has a reader outside this repository. (asserted, and no human has accepted it)
- Five run-tooling gaps from run 20261012-2342, filed together — A workflow sits outside the code path scope, two install-route scripts have no governing document, three judge mutants survive, the write hook names a link path, and the verify wait omits --repo. None has a reader outside this repository. (asserted, and no human has accepted it)