Bundled follow-up: templates/deps.yml matches no caller, template pins are unresolved by CI, and the canonical script does not say it is fleet-managed

[bdelanghe]

Three items that share one review and one merge, bundled deliberately: together they are the first end-to-end exercise of the canonical bump workflow in README.md (edit script → bump CANONICAL_SHA256 → merge → re-vendor per repo). That path has never been run start to finish. Doing it on a change that is also a real fix is worth more than doing it on a comment.

Filed from a session that started as a handoff read and turned into a verification pass. Every claim below was checked against the checkouts, not inferred.

1. templates/deps.yml is byte-identical to none of its callers

The template's own header says:

# STANDARDIZED ORG-WIDE CALLER — copy this file byte-identical to
# .github/workflows/deps.yml in the adopting repo.

It matches neither adopter. Both callers are pinned behind the template:

file	osv-scan pin
templates/deps.yml	62990dd15f1b0deba21e597bebd1512970544c15
infra/.github/workflows/infra-test.yml	8b7d8a8d3fbf43a4a97b47006ae40dfe32012b85
front-desk-scheduler/.github/workflows/deps.yml	8b7d8a8d3fbf43a4a97b47006ae40dfe32012b85

8b7d8a8 is an ancestor of 62990dd — the callers sit four commits back:

62990dd osv-scan: report-only silently did nothing — `bash -e` killed the triage
4e8e18f templates: pin to fa4620770395c57e4fc0d042ded33094b9e7d290
fa46207 osv-scan: add report-only adoption grace; ship it in the template (#2)
0a064f4 templates: the standardized org-wide caller (deps.yml)

So the callers predate the report-only input entirely (added in fa46207). Beyond the pin, the template also carries a weekly schedule (cron: "23 7 * * 2") and report-only: true; neither caller has either, and the comment blocks have diverged wholesale.

Nothing is broken today — neither caller passes report-only, so neither is affected by the triage bug 62990dd fixed. This is drift, not an outage. But it is drift the repo asserts does not exist.

Why it went unnoticed: only env-check has a drift gate. deps has none. This is precisely the condition #122 was filed to prevent, one lane over.

2. Ordering hazard for #2

This matters more than it looks, because #2 fans templates/deps.yml out byte-identical to 81 repos.

Executed as written today, the fleet lands on 62990dd + report-only: true while infra and front-desk-scheduler stay on 8b7d8a8 with no grace flag — turning a 2-repo inconsistency into an 83-repo one, with the two reference adopters as the outliers. #2's inventory also counts them as "3 covered", which overstates what covered means when neither file matches the artifact being rolled out.

The two callers should be re-pinned before wave 1, not after. Cheap now, 81 PRs of cleanup later.

Worth deciding alongside #8: the two existing callers are already hard-fail, so for them the report-only grace #8 wants removed is a step backwards if adopted verbatim.

3. self-test does not resolve template pins

Recorded as the fourth "hollow green" in infra/docs/cloud-sessions.md: self-test once passed on a commit whose reusable-workflow pin was a nonexistent SHA. Nothing in CI resolves pins, so @REPLACE_WITH_MERGE_SHA and a fabricated 40-hex string are equally invisible.

self-test covers the canonical script well (env-check, env-check-digest) and the converter well (check_embed_sync.py, goldens, bash -e triage). It does not check that the SHAs in templates/*.yml name real commits.

Add a step that resolves every pin in templates/*.yml with git cat-file -e <sha>^{commit}.

All three pins currently in the tree do resolve — verified on an unshallowed clone — so this gate lands green and stays green until it catches something. Note the shallow-clone trap for whoever writes it: under --depth 1 every cat-file fails, which would make the check fire constantly on a normal actions/checkout. It needs enough history to resolve, or a different resolution mechanism.

4. The canonical script does not say it is fleet-managed

tools/cloud-env-check.mjs describes adoption as:

// Repo-agnostic on purpose: everything repo-specific lives in the config file's
// "handshake" block, so another repo adopts this by copying two files and
// setting that block — no edits to this script.

env-check.yml already contradicts this in writing:

# Adoption is FOUR things, not two. The script's own header undercounts it:

Two problems. The header undercounts adoption (steps 3 and 4 — the SessionStart hook invocation and the dialog variable — live outside both files), and nothing in the vendored copy tells a reader that editing it locally is the wrong move. A vendored file with no provenance marker is an invitation to fix it in place, which is the exact failure the drift gate exists to catch — it would just catch it later and more expensively.

Add a header line naming bounded-systems/ci-workflows as canonical, stating that local edits belong upstream, and correcting two → four.

Open question, worth answering here rather than rediscovering

Should deps get the same drift gate env-check has?

Argument for: item 1 is exactly the failure the env-check gate was built to make loud, and it went unseen for a day across two repos. At 83 repos it will not stay a one-day problem.

Argument against: the two are not the same shape. env-check gates a script's bytes against a canonical copy. deps.yml is a caller whose only meaningful content is a pin — and its drift is one-directional and enumerable, so a resolver in self-test (item 3) plus a "does any caller lag the template" check may cover it without a per-repo lane. There is also a bootstrapping wrinkle: a gate on caller contents has to run in the caller's repo, which is 81 more adoption steps.

My read is that item 3 generalizes better and should be tried first — but this is a decision, and it should be made deliberately rather than by whoever next trips over it.

Checklist

• Re-pin infra/.github/workflows/infra-test.yml and front-desk-scheduler/.github/workflows/deps.yml to the template's osv-scan SHA, or bump the template — decide which direction is canonical
• Reconcile the schedule and report-only divergence between template and callers (see Remediation queue: clear findings and remove report-only grace (it has no expiry and no owner) #8)
• Add a git cat-file -e resolver over templates/*.yml pins to self-test, with enough checkout history to resolve
• Add the fleet-managed provenance line to tools/cloud-env-check.mjs; correct "two files" → four adoption steps
• Bump CANONICAL_SHA256 in env-check-drift.yml in the same commit (sha256sum tools/cloud-env-check.mjs)
• Re-vendor to infra and front-desk-scheduler; bump both caller pins (README step 4 — the part that has never been exercised)
• Answer the drift-gate-for-deps question above
• Correct Fleet rollout: standardized deps.yml across all 81 remaining bounded-systems repos #2's "3 covered" once the two callers actually match the template

Verification used

# current state, all three byte-identical and matching CANONICAL_SHA256
sha256sum tools/cloud-env-check.mjs                          # c530b86a…
diff templates/env-check.yml <caller>/.github/workflows/env-check.yml   # identical, both repos

# the deps drift
diff templates/deps.yml front-desk-scheduler/.github/workflows/deps.yml
git merge-base --is-ancestor 8b7d8a8… 62990dd…               # callers are behind

# pin resolution — requires an unshallowed clone
git fetch --unshallow
git cat-file -e <sha>^{commit}

Related: #2 (fleet rollout — the ordering hazard), #8 (report-only grace), infra#122 (the gate this pattern came from), infra#101 (tracking DAG).

[bdelanghe]

Code checklist discharged. #11 merged as 655353f, re-vendored in both adopters (infra#143, front-desk#80). Verified on main afterward rather than inferred from the merges:

ci-workflows  tools/cloud-env-check.mjs          6fb0c3e1…
infra         .claude/hooks/cloud-env-check.mjs  6fb0c3e1…
front-desk    .claude/hooks/cloud-env-check.mjs  6fb0c3e1…
CANONICAL_SHA256 in env-check-drift.yml          6fb0c3e1…

• Re-pin both callers to the template's osv-scan SHA (8b7d8a8 → 62990dd)
• Reconcile the schedule / report-only divergence — see the asymmetry note below
• git cat-file -e resolver over templates/*.yml pins
• Fleet-managed provenance line; "two files" → four adoption steps
• CANONICAL_SHA256 bumped in the same commit
• Re-vendor to both repos and bump both caller pins — README step 4, run end to end for the first time
• Answer the drift-gate-for-deps question (below)
• Correct Fleet rollout: standardized deps.yml across all 81 remaining bounded-systems repos #2's "3 covered" — accurate as of now; noted on that issue

The bump procedure works, and the guards fired on the way

Worth recording, since this was the first real exercise rather than the introduce-it-green case:

• check_env_check_digest.py caught the half-done bump before I completed it — the guard doing exactly its job.
• drift / env-check-drift passed in both adopters against a genuinely changed digest. Previously it had only ever been introduced green.
• The resolution step logs resolved 2 template pin(s) plus a ✓ per pin, so the log shows work rather than only absence of error.

One correction to this issue's own framing

Item 3 proposed a single git cat-file -e check. That is not implementable as one check, and the reason is structural: flake.nix's parity rule ("test/ should have no file that neither runner executes") collides with nix flake check running in a store path with no .git and no network. Resolution is impossible there by construction.

So it shipped as two complements, and both are load-bearing — proven by mutation, not argued:

pin	shape check	resolution
@main	FAIL	invisible
@REPLACE_WITH_MERGE_SHA	FAIL	invisible
fabricated 40-hex	pass	FAIL ← green-hole #4
real	pass	pass

Self-review then caught a third thing: both halves originally passed vacuously on an empty match set — the loop body never running, rc staying 0, green having checked nothing. The hollow-green bug, written into the tool built to catch hollow greens. Both now refuse an empty result explicitly (3485c6d).

The deliberate asymmetry between the two adopters — please do not "fix" it

• front-desk#80 adopts the weekly cron. deps.yml there is a byte-identical template copy, and the missing rescan was a real gap.
• infra#143 does not. infra-test.yml is a combined test workflow with its own trigger design — the consumer shape templates: resolve template pins in CI, and mark the canonical script fleet-managed #11 documented as legitimate.
• Neither adopts report-only: true. Both repos are already at hard-fail steady state, so taking it would be a regression dressed as a sync, and would work against Remediation queue: clear findings and remove report-only grace (it has no expiry and no owner) #8.

The open question, now with evidence

Should deps get a drift gate like env-check?

This stopped being hypothetical: a caller sat four commits behind the template and nothing caught it — not CI, not review, only a manual diff. At 83 repos that does not stay a one-day problem.

My read is unchanged from the issue body — the pin resolver generalizes better than a per-repo lane, because deps.yml's only meaningful content is a pin, and a caller-side gate would need 81 more adoption steps. But the resolver as shipped checks pins inside templates/, not whether callers have kept up with them. The gap that actually bit is still unguarded.

A cheap next step, if wanted: a scheduled job here that lists org repos, reads each deps.yml pin, and reports any lagging the template. Reconciliation rather than injection — the same shape recommended for the new-repo gap in infra#135. That would need a credential to read across repos, which is its own decision.

---

Generated by Claude Code

[bdelanghe]

Correcting my own comment above. I wrote that a reconciliation lane "needs a credential to read across repos, which is its own decision." That objection is mostly void, and it was the main thing making option-do-nothing look attractive.

Checked the org inventory rather than assuming. Of 90 repos, exactly three are private: infra, .github-private, trellis-private. Every one of the 81 repos in #2's waves is public, so their .github/workflows/deps.yml is readable unauthenticated — no App, no broker mint, no standing grant.

The single private adopter is infra, and it does not need cross-repo reach either: it can assert its own pin inside its own CI, where the repo's own token already suffices. So full fleet coverage needs no new credential at all.

That removes the reason to defer this on trust-boundary grounds. What remains is only a timing question:

• Today the lane would watch 2 callers, which a human can diff by hand — thin value.
• After wave 1 it watches 83, where the drift is undetectable by inspection. That is exactly the transition that turns this from over-engineering into the only thing standing between the fleet and a silent four-commit lag.

Recommendation: build it as part of wave 1, not before and not after. Concretely, a scheduled job here that reads each public adopter's deps.yml, extracts the osv-scan.yml@<sha> pin, and reports any that differ from templates/deps.yml — plus a one-line assertion in infra's own infra-test.yml covering the private case.

Two design notes for whoever builds it, both learned the hard way in #11:

1. Refuse an empty result. If the fetch returns nothing or the regex stops matching, the job must fail rather than report "0 laggards" — that is the vacuous-pass shape that bit the template-pins job before 3485c6d fixed it.
2. Report, do not auto-fix. Same posture as check_embed_sync.py and schema-drift.yml, and the one this repo's README already argues for.

The credential question would come back only if private repos ever adopt the lane. Worth writing down when that happens, not now.

---

Generated by Claude Code