Skip to content

Read the catalogue address in the runbook as it answers - #185

Merged
iderex merged 1 commit into
mainfrom
docs/the-cutover-runbook-reads-the-catalogue-as-it-answers
Aug 23, 2026
Merged

Read the catalogue address in the runbook as it answers#185
iderex merged 1 commit into
mainfrom
docs/the-cutover-runbook-reads-the-catalogue-as-it-answers

Conversation

@iderex

@iderex iderex commented Aug 23, 2026

Copy link
Copy Markdown
Contributor

What was wrong

docs/domain-cutover.md is the sequence somebody follows while moving the name,
and step 9 is the step that reads the paths nothing links to. It told that reader
that a 404 on the catalogue address is what the address answers today and is
not evidence the move went badly.

The address answers now:

for p in /manifest.json /design-tokens.json; do
  printf "%-40s " "https://flowfin.dev$p"
  curl -sS -o /dev/null -w "%{http_code}\n" "https://flowfin.dev$p"
done
https://flowfin.dev/manifest.json        200
https://flowfin.dev/design-tokens.json   200

Run 2026-08-23. So the sentence inverted the reading it exists to help. On the
day of the move a 404 there is the move having dropped a file, which is the
failure #67 refuses a publish over, and the runbook said to read past it. The
tree's own reading of that address is in harness/needs-network/record/2026-08-23T03-23-54Z.md.

What this change does

git diff --name-only origin/main...HEAD
docs/domain-cutover.md

Three statements, and they are not repaired the same way.

Step 9 now says both paths answer 200 today, so a 404 at either is a dropped
file. It keeps what a 404 used to mean, with the date it stopped meaning it,
because a reader who is given only the new sentence cannot tell why the old one
was ever right.

The paths section said /manifest.json does not answer today. It now says what
it answers and that this repository does not author what it carries, which is
the position record 0006 puts that file in and the reason it is carried rather
than built.

The block under ## The state before the change keeps its 2026-08-11 reading
exactly as printed. That section exists so a rollback restores a state rather
than guessing at one, so editing the snapshot would remove the thing it is for.
A paragraph beside it names the single line that has been overtaken and what the
path answers now.

The means

Prose, in the document that already holds this sequence. What changed is what a
reader is told on the day, and there is nothing here a check could decide: no
reading of this tree says what a public name answers, which is why that class
lives in the harness outside the gate rather than in a leg.

What this does not do

#67 stays open. The publish job that refuses to complete without the
carried file does not exist, and this changes a document rather than building
one.

It edits no decision record. decisions/0006-what-answers-at-the-catalogue-address.md
and decisions/0008-the-url-shape.md both paste the same 404. Under the rule in
decisions/README.md a change to 0006 is not a correction, because 0006 rests on
the address not answering when it says the question is cheap to settle now, and
changing that changes what a reader would decide after reading it. That needs a
new record and is not taken here.

The gate

go run . ci
gate: 7 legs, in order: format, vet, test, build, links, sitemap, invariants
  format: ok, 54 file(s)
  vet: ok
  test: ok, 26 test file(s)
  build: ok, 8 file(s)
  links: every reference that stays inside this site resolves to a file the build wrote
  sitemap: every page the build wrote is listed once, and every entry has a page behind it
  invariants: ok, 38 rule(s) decided, 1 owed and not decided
7 of 7 legs ran. None was skipped.

go run . hygiene origin/main HEAD
hygiene: 1 non-merge commit(s) in origin/main..HEAD, origin internal
  6438a87ab50b: subject carries its reference
1 commit(s) judged, none refused.

Both run 2026-08-23 at 6438a87.

No second reader

This change carries no second reader. The commands above are what stands in place
of one.

The cutover runbook told a reader performing the move that a 404 on the
catalogue address is what it answers today, and that it is not evidence the move
went badly. It answers 200 now, so that sentence inverted the reading it was
written to help: on the day of the move a 404 there would be the move having
dropped the file, which is the failure this issue exists to refuse, and the
runbook said to read past it.

Three statements are repaired and they are not the same kind.

Step 9 said what a 404 means at that moment. It now says both paths answer 200
today, so a 404 at either is a dropped file, and it keeps what a 404 used to mean
with the date it stopped meaning it, because a reader who knows only the new
sentence cannot tell why the old one was ever right.

The paths section said /manifest.json does not answer today. It says what it
answers and that this repository does not author what it carries, which is
record 0006's position for that file and is why it is carried rather than built.

The state-before-the-change block keeps its 2026-08-11 reading unedited, because
that section exists so a rollback restores a state rather than guesses at one. A
paragraph beside it says which single line has been overtaken and what the path
answers now, so the block is still the state it records and no longer reads as
the state to expect on the day.

    for p in /manifest.json /design-tokens.json; do
      printf "%-40s " "https://flowfin.dev$p"
      curl -sS -o /dev/null -w "%{http_code}\n" "https://flowfin.dev$p"
    done
    https://flowfin.dev/manifest.json        200
    https://flowfin.dev/design-tokens.json   200

Run 2026-08-23.

The means is prose in the document that already holds this sequence, because
what changed is what a reader is told and there is nothing here a check could
decide: no reading of this tree says what a public name answers, which is why
that class lives in the harness outside the gate.

No decision record is edited. 0006 and 0008 both paste the same 404, and under
the rule in decisions/README.md a change to 0006 is not a correction, because it
changes what a reader would decide after reading it. That needs a new record and
is left where it belongs.

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
@iderex iderex added the documentation Improvements or additions to documentation label Aug 23, 2026
@iderex iderex self-assigned this Aug 23, 2026
@iderex iderex added this to the First release milestone Aug 23, 2026
@iderex
iderex merged commit 8a45538 into main Aug 23, 2026
17 checks passed
@iderex
iderex deleted the docs/the-cutover-runbook-reads-the-catalogue-as-it-answers branch August 23, 2026 03:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant