visible-steps-and-build-report

Date: 2026-09-11. Status: superseded.

Decision. The build is written as small named steps in code: one function per directory file, per PHS file as published, per canonicalised PHS edition, per government edition, and one join per edition, each with its own checks. The Dagster graph stays at five things, sources plus four tables, and the steps appear as rows in a build report, results/BUILD_REPORT.md, written by every build in plain language with that run's numbers. docs/HOW_IT_IS_BUILT.md is the static one-page companion.

Reason. A first attempt exposed every step as a graph node, fifty-one in all, and a reviewer could not read it. A graph is a machine's view; a reviewer needs a narrative with numbers. The steps stay visible where they help, in the code and the report, and out of the graph where they do not.

Evidence. CLI and Dagster builds on branch ladder both produced sha256 c685cd137652ec37 under main's decision log, byte-identical to main. Twenty-two assets, twenty-four checks, intermediates about 16 MB of Parquet.