Why
Five statements in the docs and package comments describe a shellf that no longer exists. Each
verified against the current tree.
| where |
says |
actually |
docs/language.md:3-4 |
"One shipped construct has no chapter yet — as <user>" |
no chapter for on, parallel, override def, or the inventory syntax either (grep '^## ' docs/language.md) |
docs/language.md:28 |
a def translates a ShellResult "via when/tags" |
when is not a keyword — zero occurrences in internal/lang |
docs/design/inventory.md:16 |
address | yes | network endpoint |
not required for local: "true" (README.md:112). local and interpreter are absent from the table although both are host fields (internal/inventory/inventory.go:17-18) |
internal/inventory/inventory.go:1-3 |
"Connection coordinates only — no business variables. Built in Go for now; a parsed shellf-language inventory comes later" |
both clauses false: Vars map[string]string at :19, and the inventory is parsed in the shellf language at internal/lang/parser.go:361 |
internal/std/postgres/postgres.shellf:3 |
"Only these two" |
four defs in the file. Worse, :5 argues that a postgres.config "would also inherit the versioned-path problem (#546), unresolved" — 130 lines above the postgres.config that resolves it with pg_conftool |
docs/design/inventory.md:63 does carry a > **Superseded.** note, but it covers only the
free-form-variables point. The address/local/interpreter row is untouched by it — worth
saying, because an earlier audit in #642 read that note as covering the file and it does not.
Not a defect, listed so it is not re-raised
docs/dogfood.md:99 — "A plan cannot read another host's inventory entry" — is superseded by
ADR-0054. It stays: dogfood.md 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). A one-line forward
pointer to ADR-0054 is welcome; rewriting the finding is not.
Build
Correct the five. postgres.shellf's header is the one to think about rather than patch: it
argues a decision that the file itself has since reversed, so it needs rewriting, not a count
fix.
language.md is the largest: the missing chapters are real work, and the honest first move is
to make the header say what is missing instead of understating it. Writing the chapters can be
its own issue — but a spec that claims completeness it does not have is worse than one that
lists its holes.
Validation
grep -n 'when' docs/language.md — no occurrence presents it as a construct.
docs/language.md's header names every shipped construct that has no chapter, checked
against grep '^## ' docs/language.md and the plan grammar in internal/lang/parser.go.
docs/design/inventory.md's host table lists local and interpreter, and address is not
marked required unconditionally.
internal/inventory/inventory.go's package comment is true of the package as it is.
grep -c '^def ' internal/std/postgres/postgres.shellf agrees with its header.
Out of scope
Writing the missing language.md chapters. Naming the gap is this issue; filling it is
another, and pretending otherwise is how this one never closes.
Why
Five statements in the docs and package comments describe a shellf that no longer exists. Each
verified against the current tree.
docs/language.md:3-4as <user>"on,parallel,override def, or the inventory syntax either (grep '^## ' docs/language.md)docs/language.md:28ShellResult"viawhen/tags"whenis not a keyword — zero occurrences ininternal/langdocs/design/inventory.md:16address| yes | network endpointlocal: "true"(README.md:112).localandinterpreterare absent from the table although both are host fields (internal/inventory/inventory.go:17-18)internal/inventory/inventory.go:1-3Vars map[string]stringat:19, and the inventory is parsed in the shellf language atinternal/lang/parser.go:361internal/std/postgres/postgres.shellf:3:5argues that apostgres.config"would also inherit the versioned-path problem (#546), unresolved" — 130 lines above thepostgres.configthat resolves it withpg_conftooldocs/design/inventory.md:63does carry a> **Superseded.**note, but it covers only thefree-form-variables point. The
address/local/interpreterrow is untouched by it — worthsaying, because an earlier audit in #642 read that note as covering the file and it does not.
Not a defect, listed so it is not re-raised
docs/dogfood.md:99— "A plan cannot read another host's inventory entry" — is superseded byADR-0054. It stays:
dogfood.mdis a dated report of what a deployment could not express,and history is allowed to describe a world the code has left (ADR-0001). A one-line forward
pointer to ADR-0054 is welcome; rewriting the finding is not.
Build
Correct the five.
postgres.shellf's header is the one to think about rather than patch: itargues a decision that the file itself has since reversed, so it needs rewriting, not a count
fix.
language.mdis the largest: the missing chapters are real work, and the honest first move isto make the header say what is missing instead of understating it. Writing the chapters can be
its own issue — but a spec that claims completeness it does not have is worse than one that
lists its holes.
Validation
grep -n 'when' docs/language.md— no occurrence presents it as a construct.docs/language.md's header names every shipped construct that has no chapter, checkedagainst
grep '^## ' docs/language.mdand the plan grammar ininternal/lang/parser.go.docs/design/inventory.md's host table listslocalandinterpreter, andaddressis notmarked required unconditionally.
internal/inventory/inventory.go's package comment is true of the package as it is.grep -c '^def ' internal/std/postgres/postgres.shellfagrees with its header.Out of scope
Writing the missing
language.mdchapters. Naming the gap is this issue; filling it isanother, and pretending otherwise is how this one never closes.