release: a workflow-only fix reaches no consumer until an unrelated dep-check release moves v1 (measured: 2-3 days)

[usetheodev]

Severity: HIGH — every reusable workflow in this repository is delivered by the moving v1
ref, and v1 only advances as a side effect of publishing the @theokit/dep-check npm package.
A change that touches only .github/workflows/** therefore sits on main, correct and merged,
reaching zero of the ten consumers until somebody happens to release the package.

Evidence

release.yml triggers on push: tags: ['dep-check-v*'], and advance-v1 is gated further:

if: needs.publish.result == 'success' && startsWith(github.ref, 'refs/tags/dep-check-v')

Both conditions are right for what they guard. Neither has anything to do with a workflow change.

Measured on this repository's own history:

commit	landed on main	v1 next moved	stale for
863a274 feat(checks-pass)	2026-09-01 13:41	2026-09-04 20:42 (dep-check-v0.10.0)	3d 7h
e1c663a fix(preview)	2026-09-02 16:08	same	~2d 4h
a4c8128 fix(preview)	2026-09-02 18:40	same	~2d 2h
8137d9b fix(preview)	2026-09-02 18:47	same	~2d 2h
2b90a81 fix(preview)	2026-09-02 21:09	same	~2d

Four of those five are fixes to preview.yml, one of them specifically so that a preview which
falls back to publishing everything announces that it is not installable. For two days every
consumer kept producing the silent version, and nothing said so.

Why this is not the same as the pin discipline

dep-check.yml deliberately splits the two: the workflow moves by ref so a policy change
reaches every caller, while the tool is a semver artifact that moves by a bump somebody
reviewed. That reasoning is written at the top of the file and it is correct.

The defect is that the mechanism does not implement it. Today the policy cannot move at all
without the tool moving, which is the exact coupling the split exists to avoid.

Repro

1. Merge any change that touches only .github/workflows/** into main.
2. git fetch --tags --force && git rev-parse v1 — still the previous commit.
3. Any consumer resolving @v1 runs the old workflow, indefinitely.

Suggested fix

Advance v1 on a push to main that changed workflows or composite actions, with the guard that
already exists for the release path: v1 must never point at a commit whose declared
@theokit/dep-check version is not the published one, or consumers get
npx @theokit/dep-check@<missing> failing at the point of use. That invariant is the real reason
advance-v1 is gated on a successful publish; a workflow-only path needs the same invariant
checked directly rather than inherited from the publish.

Doing it by hand instead is the option this repository already rejected in advance-v1's own
docblock: "Moving it by hand was the last manual step in a release, and it has been missed on two
of six."

Related

• feat(promotion-gate): share the develop gate — nine identical copies become one #51 — the shared promotion-gate.yml, which is blocked by exactly this: merged, it would reach
  no consumer.

---

How this was found: standardising the promotion gate across the ten consumers, the follow-up
step "convert the consumers to thin callers" required knowing when @v1 would serve the new
workflow. The answer was "at the next unrelated package release".

No secrets, tokens or credentials appear in this report.

[usetheodev]

This issue is wrong. Closing it as invalid, and recording why, because the mistake is more
instructive than the report.

ci.yml already has an advance v1 to main job. It runs on push to main, checks that the
pinned @theokit/dep-check version is on the registry, moves v1, and reads the ref back through
the annotated-tag indirection. It was introduced on 2026-08-27 in 073cbaa, whose subject is
literally "fix(ci): v1 follows main, not only releases" — a week before every commit this
issue cited as evidence.

Verified, rather than assumed this time:

main push	CI run	advance v1
f7bc309 (2026-09-02 21:49)	33687196411	success
3d84781 (2026-09-01 21:28)	33561230773	success

So workflow-only changes do reach consumers, and the table of "2–3 days stale" in the body
describes nothing that happened.

How the report went wrong

I never measured when v1 moved. I measured when tags were created, assumed the tag was the
only thing that moves v1 because release.yml's advance-v1 is gated on one, and presented the
difference between two commit dates as a latency. Every number in that table is real; none of them
answers the question the issue asks.

That is the failure mode worth naming: a wrong-mechanism measurement produces correct figures
about the wrong thing, and reads exactly like evidence. It is harder to catch than a wrong number,
because nothing about the output looks off.

What would have caught it in one command, and did once it was finally run:

gh run list --repo usetheokit/shared-workflows --workflow ci.yml --branch main \
  --json headSha,conclusion,createdAt
gh run view <id> --json jobs --jq '.jobs[] | select(.name|test("advance v1"))'

Consequence for #51

None, and the follow-up note in that PR is also wrong for the same reason. Once #51 merges to
main, CI advances v1 on that push, and the shared promotion-gate.yml is reachable by every
consumer immediately — no package release needed. The converts can follow directly.