BUG-083: #982 tightened the folder allow-list without a migration, so any dotf built from main refuses the already-deployed registry

[mlorentedev]

What

#982 renamed the ratified Bitwarden folder taxonomy from Dotfiles/apps / Dotfiles/infra to apps / infra, updating both secrets/registry.yaml and validBWFolders, the parser's allow-list. Both halves are correct. What is missing is that the deployed copy of the registry is a separate artifact with its own lifecycle (ADR-030): ~/.dotfiles/secrets/registry.yaml is refreshed by setup-linux.sh, not by merging a PR.

So a binary built from current main rejects the registry that is currently deployed on every machine:

$ cd ~/.dotfiles && dotf secrets ls
Error: secret "GITHUB_PERSONAL_ACCESS_TOKEN": bw.folder "Dotfiles/apps" is not in the ratified taxonomy (apps, infra)

$ grep -o 'folder: [A-Za-z/]*' ~/.dotfiles/secrets/registry.yaml | sort | uniq -c
     21 folder: Dotfiles/apps
      5 folder: Dotfiles/infra

Not currently broken, and that is the trap

The installed binary is 0.40.0, which predates #982, so today everything works. The failure is armed, not firing: it lands the moment anyone installs a build from main — the next release, or a scripts/install-dotf.sh run — and it lands on every machine simultaneously, before any of them has re-run setup.

Blast radius when it fires: ParseRegistry is the entry point for the whole dotf secrets surface, so ls, run, show, verify, render and two dotf doctor sections all fail at once. Reproduced here with a main-based build:

[Secrets integrity]
  [FAIL] secrets/registry.yaml not found or invalid

Note the message says "not found or invalid" for what is actually a validation failure on a file that is present and readable — so the first person to hit this will go looking for a missing file.

Why the guard did not catch it

The pattern is the dormant-value one this repo already has a lesson about, inverted: OPS-028 learned to validate bw.folder at write time rather than at activation time. This is the same field failing the other way — a value that was valid when written and was invalidated later by a change to the validator, in an artifact the validator's PR did not and could not update.

dotf doctor's deploy-drift check knows the deployed copy can lag the checkout; nothing checks that the lagging copy is still parseable by the current binary.

Options

1. Accept both spellings for a deprecation window — validBWFolders takes the old values too, WARNing on them, removed after a release. Cheapest, and it makes the change survivable in any install order.
2. Make the deploy a precondition of the parse tightening — ship the registry change, require setup, then tighten. Correct but needs coordination the release process does not currently have.
3. Have dotf doctor --fix redeploy the registry when the deployed copy fails to parse but the checkout's parses. Fixes this instance and the next one of the same shape.

Recommend 1 now (it is what makes the already-merged change safe), plus 3 as the durable guard.

Acceptance criteria

• A binary built from main parses the currently-deployed registry, or a documented, enforced ordering makes that impossible to hit.
• ParseRegistry's failure is reported as a validation error naming the file and the rule, never as "not found or invalid".
• A check fails when the deployed registry cannot be parsed by the running binary — the drift that is invisible until every secret command breaks at once.

Evidence

• refactor(secrets): drop the Dotfiles/ prefix from the folder taxonomy #982 (merged) — the rename and the allow-list tightening
• cli/internal/secrets/registry.go — validBWFolders, planeFolder
• docs/adr/adr-030-* — checkout vs deployed copy, the two-artifact lifecycle
• docs/lessons.md — the OPS-028 dormant-field lesson, the same field failing the other way

[mlorentedev]

Correction: the direction of this bug is inverted, and it is live right now.

Measured from a neutral cwd (~), so the deployed registry is the one being read:

$ /path/to/main-build dotf secrets ls
GITHUB_PERSONAL_ACCESS_TOKEN app       GITHUB_PERSONAL_ACCESS_TOKEN
...                                                          exit 0

$ dotf secrets ls          # the INSTALLED 0.40.0
Error: secret "GITHUB_PERSONAL_ACCESS_TOKEN": bw.folder "apps" is not in
the ratified taxonomy (Dotfiles/apps, Dotfiles/infra)

So it is not "a binary built from main refuses the deployed registry". It is the opposite: the registry dotf reads is already on the new apps/infra taxonomy, and the installed 0.40.0 predates #982 and cannot parse it. A binary from main parses it fine.

Consequences:

1. dotf secrets ls and doctor are broken on this machine today, not hypothetically after the next install. The issue reads as "nothing is broken until the next install", which is why nobody was looking.
2. Installing is the fix, not the risk. The earlier guidance to avoid installing kept the broken binary in place.
3. scripts/install-dotf.sh will not fix it, because it fetches a release and the latest is still 0.40.0 — the broken one. refactor(secrets): drop the Dotfiles/ prefix from the folder taxonomy #982, fix(doctor): repair the PAT-expiry check and the tagged-union consumers behind it #984, feat(harness): a PR you open is watched, not abandoned (HARNESS-072-pr-stewardship, #963) #986, fix(secrets): map DOCKERHUB_TOKEN to the scoped PAT, and detect registry/vault drift #990, fix(spec): stop announcing a review that never started (BUG-081, #989) #994 and fix(spec): store the review transcript's events, not its streaming frames (BUG-083, #995) #999 have merged since chore(main): release 0.40.0 #974 cut it. This needs a 0.41.0 release (or a local build) to clear.

The underlying observation in the original report — a taxonomy tightened without a migration for already-deployed state — stands. Only the direction of the break was recorded backwards.

[mlorentedev]

AC1 is met; AC3 is not. Rescoping rather than closing.

Two other sessions independently recommended closing this as moot today. The immediate breakage is resolved — but the acceptance criteria ask for more than that, and retiring the issue here would leave the durable half unbuilt.

AC1 — met. Verified from a neutral cwd (/tmp), so the deployed registry is the one read:

$ dotf version
dotf version 0.41.0
$ dotf secrets ls
GITHUB_PERSONAL_ACCESS_TOKEN app  GITHUB_PERSONAL_ACCESS_TOKEN
...                                          exit 0

Both copies now agree on the taxonomy — 21 folder: apps / 5 folder: infra in the checkout and in ~/.dotfiles/secrets/registry.yaml alike. Note the direction, since the body above still asserts the opposite: it was the installed 0.40.0 that could not parse the new registry, not a main build refusing the deployed one. The release fixed it by replacing the stale binary. That correction is comment 5301453624; the body has not been edited to match.

AC2 — partially met. ParseRegistry returns real validation errors naming the rule (secret %q: unknown backend %q, bw.folder ... is not in the ratified taxonomy), never "not found or invalid". But it takes []byte and so cannot name the file — with two copies of this registry on every machine and a lifecycle that lets them diverge, "which registry said this" is exactly the missing word. That is a caller-side fix.

AC3 — not met, and it is the point. "A check fails when the deployed registry cannot be parsed by the running binary." No such check exists. This whole issue is an instance of a class this repo keeps re-learning — a condition nothing checks reads as a condition that is not there — alongside #997 (an escrow that never existed reported as SKIP), #972, and #906. Closing on AC1 alone means the next taxonomy tightening is invisible in exactly the same way, and the repo standing order is that a bug class emits a guard in the same change, not a follow-up someone remembers.

Keeping this open, rescoped to the guard: a doctor section that parses the deployed registry with the running binary and FAILs on drift, plus the --fix redeploy the body already recommends as option 3. That is cli/internal/doctor/ work and sits in the same lane as #997 (PR #1006), so it follows as a separate PR.