Build1 publisher3 min readPublished
Failing the build on leftover UNSIGNED cells keeps laptop defaults out of the config reference
A dev.to post splits the configuration table into cells a parser can prove, cells a model may draft, and cells only a named reviewer may write, then holds the publish while any signed cell still reads UNSIGNED.
The Engineer · Build desk
What happened
- The workflow's artifact is a small extractor, a grid of signed cells, and a publish gate that fails while any leftover UNSIGNED marker remains in the table.
- Compile cells come from parsers and literal references, draft cells may be filled by a model but still need a human pass, and signed cells stay empty or UNSIGNED until a named reviewer writes them.
- A chat model given a README plus a handful of nearby files produces a table that looks complete while its default column describes a laptop checkout instead of a production deploy, the post says.
Compiled by The EngineerSomething wrong?How this is made
Why it matters
- decision With hedges banned from signed cells, a reviewer who does not know the production default has two moves: find the owner who does, or leave the cell UNSIGNED and hold the publish.
- exposure The person who pays for a hedged default is the on-call engineer who copies it into an incident note, and the post treats that path as the reason the hedge is forbidden.
- capability A CI check that refuses unsigned operational cells gives a team a way to reject bad documentation without first agreeing on how much drafting a model should do.
- constraint The grid's completeness depends on flags being declared as literal constants, so a codebase that generates flag names in a loop cannot claim the inventory is whole.
The compile lane can only own what the walk actually matches, and the match conditions are narrow. ConfigVisitor subclasses ast.NodeVisitor and defines a single method, visit_Call [16]. A flag row is appended only when the called name is add_argument, the call has positional arguments, the first one is an ast.Constant, and the evaluated string starts with a hyphen [17]. A flag name assembled from a variable or an f-string fails the Constant test and never reaches the grid [3]. Environment reads are matched by name against ENV_FUNCS = {"getenv", "get"} with a key that satisfies key.isupper() [18], so os.environ["DATABASE_URL"] is invisible to the walk, because subscript access is not a call node [1].
The same two tests also over-match. Any .get("TIMEOUT") on any dictionary in the file satisfies both and lands in the inventory as an env row [2]. I would rather review an inventory that over-reports; deleting a false row is cheap.
extract() runs ast.parse on one file's text [20], and rows are deduplicated on the (kind, id) tuple [19]. Covering a repository is the caller's problem. The script's own header calls it a labeled example, not a production inventory [15].
"The failure is mixed authority," the post says [10]. Identifiers, flag strings and in-code help text come back from a deterministic walk; production defaults, rotation policy, log-safety and the calendar window for a breaking rename do not [11]. That split is why secret-bearing names end up pasted into example blocks when a prompt never separated public flags from credentials [8]. On the signed lane the post is blunt about hedging: "Empty signed cells are honest; hedged signed cells are a defect" [12].
The counting matters for who is on the critical path. The extractor emits three fields per row, id, kind and help [21]. The signed lane wants four more on that same row: the production default, the secret classification, required-in-production status, and the breakage policy [4]. So every identifier the parser finds for free creates four cells a named reviewer has to write [4].
One failure does go away for a structural reason. The inventory is whatever the documented commit references in code [2], so an option deleted from the parser stops appearing, which is the case a chat model gets wrong when it never saw the removal commit [9][5]. That holds only when the extractor runs on the commit being documented. The post says to start from the same commit you intend to document, because configuration names drift across branches faster than narrative README sections [13].
For this to transfer, your flags have to be declared as literal strings at call sites a deterministic walk can reach [2][3]. A codebase that builds flag names in a loop gets a partial grid, and the completeness claim goes with it. The post does not report defect counts before or after adopting the gate, and the extractor is presented as a worked example for a tiny CLI [15]. Its narrowest claim is the one I would defend: unsigned operational cells are a review defect, and CI can refuse them without anyone settling whether models should exist [22].
What to watch
- Whether the extractor grows past single-file ast.parse into a repo walk, and whether Click or pydantic declaration styles get their own matchers.
- Whether anyone publishes defect counts from running the UNSIGNED gate against a real repository.
- Whether the publish gate survives its first release deadline, or acquires a skip flag for signed cells.