Correct the False No-Vocabulary Claims About Environment Secrets in spec/ #2268

Hub prose says spec/secrets.json has no vocabulary for per-environment secrets, and that a repository declares those names in its own environments block. Both claims are false against the tree.

The false claims

• spec/secrets.json, the static-secret mechanism note: it says the per-environment names are something "this file has no vocabulary for", and that "A repo declares them in its own environments block below instead".
  • spec/secrets.schema.json (around lines 48-63) does define an environments object, with names, secrets, variables, environmentSecrets and notes.
  • spec/secrets.json itself has no environments key. Its top-level keys are $schema, note, baseline, mechanisms, targetMechanisms, featureMechanisms and typeMechanisms. So there is no "block below".
• spec/secrets.json, the top-level note: "environments, where a repo carries it" assumes a repository carries a secrets.json. docs/repo-config.md says downstream repositories carry no copy of spec/secrets.json.
• spec/project-types.json (around line 115): "which spec/secrets.json cannot yet express" is false for the same reason as the static-secret note.

Why it matters

A registry drift note copied these claims. Blog's entry pointed operators to a secrets.json environments block that Blog's main does not have. Copilot caught it on promotion #2254, and #2269 corrects that one note. As long as the source text stays wrong, the next note that copies it repeats the error.

What to decide

There are two candidate fixes, and they interact with #2070, which proposes one declared source for environment-scope names, checked by the audit:

1. Correct the prose now so it says what is true: the schema allows an environments block, no file uses one, and no tool reads environment-scoped stores.
2. Leave the wording until Declare Per-Environment Secrets and Variables Once and Check Them From the Hub #2070 settles where environment names are declared, then rewrite all three statements together.

Option 1 is the smaller change and removes the false pointers today.

Found by local-strict-review while fixing the Blog note, raised as pre-existing.

🤖 Generated with Claude Code