docs(corpus): add configuration corpus template - #1543
Conversation
Adds launchpad/docs/corpus/templates/configuration.md, defining what a corpus node documenting a configuration surface (env vars, deploy-time settings) must contain, grounded in the Twelve-Factor App's Config factor (the litmus test for what counts as config) combined with the Good Docs Project's Reference template (its guide names configuration settings as one of its own intended use cases). Closes #1332 Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
tucktuck101
left a comment
tucktuck101
left a comment
There was a problem hiding this comment.
Review — configuration corpus template
Secret handling is strong: section 4 flatly forbids quoting a live credential, key, token or
hostname value, which is the thing that mattered most for a configuration template in a
world-readable repo. No blocking finding. But the template inverts Twelve-Factor's litmus test in
a way its own required sections contradict three times.
High — the Twelve-Factor litmus test is turned into a membership test
configuration.md:174-181 states: "A setting that fails that test — a value the codebase could
not survive being made public with — is configuration; a value the codebase could survive
being made public with is not."
The primary source says something different. From https://12factor.net/config (fetched):
An app's config is everything that is likely to vary between deploys ... including
"Per-deploy values such as the canonical hostname for the deploy".
"A litmus test for whether an app has all config correctly factored out of the code is
whether the codebase could be made open source at any moment, without compromising any
credentials."
That is a test of externalization, not of membership. The page's own definition — which this
node quotes two lines earlier — is deploy-variance, and its worked examples include a
non-credential.
The inversion also contradicts the node itself three times:
- the mandatory
Secretcolumn at:299— by:177's rule aSecret: norow is not
configuration at all and may not be in the table; - required section 3 at
:306-311, which asks the author to confirm rows are "genuinely
deploy-varying per Twelve-Factor's test", quoting the credentials sentence — which cannot
establish deploy-variance; - the boundary bullet at
:264-266, which uses "the litmus test" correctly as a deploy-variance
test.
Concretely: this node names crates/buzz-relay/src/config.rs as its first intended instance. Under
:177's rule almost none of its settings (BUZZ_REDIS_POOL_SIZE, BUZZ_DRAIN_JITTER_MS, the bind
address) is configuration — defeating the template's purpose. The FACT at :40 enables the
misreading by quoting the test with its subject clause removed.
Make deploy-variance the membership test, as :264-266 already does, and keep the credentials
sentence as the separate externalization/secrets check.
Medium — nothing says what a Secret: yes row's Default cell may contain
Required section 2 (:297-301) makes a Default column mandatory for every row ("at minimum ... its
default (or 'none — required')") with no carve-out for secrets, and the evidence expectation at
:401-405 sends the author to the code: "the authoritative default is whatever the loading code
falls back to when the variable is unset." Section 4 simultaneously forbids quoting a live
credential value.
That collision is live in the file this node names as its first instance:
crates/buzz-relay/src/config.rs:741-742 is
s3_secret_key: std::env::var("BUZZ_S3_SECRET_KEY").unwrap_or_else(|_| "buzz_dev_secret".to_string())
— a literal fallback on a credential-shaped setting. That particular literal is a committed dev
placeholder (.env.example sets the same value), so there is no live leak today and section 4's
prohibition is absolute enough that a careful author will not paste it — hence medium, not
blocking. But the two rules are left to collide with nothing written to resolve them. One clause:
for a Secret: yes row the Default cell is "none — supplied per deploy", "generated", or
"placeholder in .env.example", never the literal the loading code falls back to.
Low — the row-ordering rule is claimed as a local invention but is upstream
:300-305 says the source-declaration-order rule "is this template's own requirement, not a
convention the Good Docs Project's guide states; that guide is silent on row ordering". The narrow
claim holds — guide_reference.md has zero matches for order/alphabet/sort/sequence. But the
Reference template in the same pack, the artifact this node says it adapts,
states it explicitly: template_reference.md line 15 reads "Organize the tables or structured
entries so that they appear in the same order as in the reference material." Sibling #1534
attributes the same rule to the Good Docs Project, so the batch currently disagrees with itself
about one source. Cite template_reference.md and keep the true, narrower observation about the
guide.
Low — one node cannot declare two part-of edges to one target
:256-258 advises that a node needing two templates' required sections "likely needs both ...
declared as two part-of relationships to a broader capability node". relationships.schema.json:45-46
defines part-of as "source is a constituent section/child of target" — a node cannot be a child
of the same target twice, and node.schema.json sets no uniqueItems, so the duplicate would
validate cleanly while carrying no meaning. The intended advice is presumably to split the subject
into two nodes, each with one part-of edge to the shared capability node. Say that.
Not findings, ruled out on evidence
- Index registration: the corpus
AGENTS.mdandREADME.mdboth state that indexes are
generated derived views, never hand-authored, and the ten-step "Creating a node" procedure has
no registration step. All 26 template PRs leavingAGENTS.mduntouched is correct. - CI green at head (latest run per check); node validates clean.
Reviewed by tucktuck101's review lane. Every failing claim reported above was reproduced by me against this PR head before posting.
Address tucktuck101's Blocking finding on PR #1536: the deployment corpus template required an environment inventory, a deployment/infrastructure node inventory, and evidence citations (including to another repository's own docs), but nowhere forbade recording a live secret, hostname, endpoint or credential value while doing so -- contradicting launchpad/AGENTS.md §8 ("Never add a secret, key, token, or private hostname to a tracked file"), launchpad/ENVIRONMENTS.md's "No hostnames" rule, and launchpad/SECURITY-POSTURE.md's point that nothing automatically catches a §8 violation. Add required section 4, "Secrets and sensitive values", modeled on configuration.md's (PR #1543) Secrets discipline section: point at the role and the configuration reference (a Helm value, a Secret name, a Terraform resource), never the literal value. Renumber the remaining required sections 5-8 accordingly, add pointer notes to the environment and node inventory items (5, 6), and extend the same rule into Evidence expectations so citing real configuration or another repository's documentation still never means quoting a secret-shaped value out of it. Does not touch the Medium finding (upstream Helm profiles presented as this fork's own environments) -- that is tracked separately as issue #1713. corpus validate.py: PASS, no new errors (same 15 pre-existing UNVERIFIED notices for commit-reference and external-URL citations). Unit test suite (launchpad/project-intelligence/corpus/tests/test_validate.py): 79 passed. Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
2 participants
Summary
Adds
launchpad/docs/corpus/templates/configuration.md, a template node stating what a corpus node documenting a configuration surface (env vars, deploy-time settings) must contain, its required sections, evidence expectations, and the industry model it adapts. Grounded in the Twelve-Factor App's Config factor (the litmus test for what counts as config) combined with the Good Docs Project's Reference template, whose own guide names configuration-settings documentation as one of its intended use cases.Related issue
Closes #1332
Issue type
Task
Agent provenance
Objective
Create
launchpad/docs/corpus/templates/configuration.mdas the corpus template node for configuration-surface documentation.Impacted components
Approach and rejected alternatives
Considered citing only the Twelve-Factor App's Config factor as the industry model, but it is a design principle (what counts as config, why to separate it from code, why env vars) with no prescribed documentation sections — it would leave the template with a test but no shape to fill in. Considered citing only the Good Docs Project's Reference template, but on its own it gives no way to decide whether a given value belongs in a configuration table at all (its own guide names configuration settings as a use case but supplies no configuration-specific litmus test or secrets discipline). Rejected inventing a third, unsourced shape. Settled on combining both — Twelve-Factor for the test, Good Docs Reference for the shape — the same two-source pattern PR #1534 (
#1346, reference template) used for its own subject. Also considered classifying this node's owntypeas something other thangovernance(the enum has notemplate/policy/configurationvalue); usedgovernance, matching the four merged corpus meta-documents and two open sibling template branches independently verified to use the same value.Verification
Command run:
Raw output:
Also run, exit 0:
Not verified
No node has yet been authored from this template, so whether its required sections are actually sufficient for a real configuration surface is untested — the node's own "Expected but not verified" section names this and two other specific gaps (row-by-row litmus-test coverage of
buzz-relay's full config surface was sampled, not exhaustive; and#1346's reference/configuration boundary reflects that template's current unmerged branch text, which may still change before merge). Codex cross-review (#1467) is down; a same-model adversarial review substituted, and four of its findings (two High, two Medium — a false attribution of a row-ordering convention to a source that doesn't state it, a misattributed Diátaxis quote missing its own citation, an uncharitable framing of a license-correction note, and an overclaimed "already landed" precedent) were fixed in commit1843b0b26before this PR was opened; this is not independent human or cross-model review.Security implications
None. This is a documentation-only change to a corpus template file; it defines no runtime behavior, adds no code, and (per its own Secrets discipline requirement, self-applied) contains no credential-shaped values, only environment-variable names.
Escalations
None filed. No blocker, out-of-scope, or unresolved finding surfaced during drafting or review that needed a separate issue; the four review findings above were fixable in place rather than requiring escalation.