Skip to content

docs: correct six claims the code had outgrown - #671

Merged
haribo merged 1 commit into
developfrom
docs/662-stale-claims
Sep 13, 2026
Merged

haribo merged 1 commit into
developfrom
docs/662-stale-claims

Conversation

@haribo

@haribo haribo commented Sep 13, 2026

Copy link
Copy Markdown
Owner

Summary

#662's five stale claims, plus #661's missing constraint — one PR because they touch the same
two files for the same reason: key is documented in the README and in the inventory host
table, and #661 itself says so ("…and the host table in docs/design/inventory.md if that one
is corrected under its own issue").

Each re-verified against develop before being changed:

where said now
docs/language.md:3-5 "One shipped construct has no chapter yet — as <user>" names all five: as <user>, on, parallel, override def, the inventory syntax
docs/language.md:28 a def translates a shell result "via when/tags" when is not a keyword — zero occurrences in internal/lang; the sentence now says what actually happens
docs/design/inventory.md:16-19 address | yes; no local, no interpreter address required unless local, and the table carries local, interpreter and the free-form-variable row
internal/inventory/inventory.go:1-3 "no business variables … a parsed shellf-language inventory comes later" both clauses were falseVars is a field, and lang.ParseInventory shipped
internal/std/postgres/postgres.shellf:1-7 "Only these two", arguing a postgres.config would inherit an unresolved problem four defs, and the argument recorded as a prediction the code overtook — a hundred lines above the postgres.config that resolves it
README.md:78, :115 key: as an ordinary override says it must be unencrypted, since shellf parses the file and has no passphrase prompt (ADR-0026 §3)

Found while fixing it

README.md:115 said "Only address is required" three lines above "host self = { local: "true" } (no address needed)" — the same contradiction as the design doc's table, in the file
that had already been reviewed twice today. Corrected in the same sentence.

Not changed, deliberately

docs/dogfood.md:99"A plan cannot read another host's inventory entry" — is superseded by
ADR-0054 and stays as written. That file is a dated report of what a deployment could not
express, and history is allowed to describe a world the code has left (ADR-0001). It gains a
forward pointer saying where the finding went, which is what #662 asked for.

Test plan

Doc and comment changes only. Each validation criterion from the issue, checked:

via `when` in language.md                → 0
language.md names override def           → 1
inventory.md lists local / interpreter   → 1 / 1
postgres def count vs its header         → 4 / "Four defs"
"no business variables"                  → 0
README says "unencrypted"                → 2
every new doc link resolves              → 9 ok, 0 missing

go test ./..., test/lint.sh, test/changelog-rule.sh, test/changelog-frozen.sh green.

Closes #661
Closes #662

@haribo
haribo merged commit 8a9b218 into develop Sep 13, 2026
8 checks passed
@haribo
haribo deleted the docs/662-stale-claims branch September 13, 2026 16:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant