Preserve the upstream branches that now exist only in one local clone, and map them to open PRs

[kinlane]

This is one-way and blocks the branch cleanup in #1.

This repository inherited 42 remote branches. Upstream currently has 38 open pull requests. Some of those branches are the work behind those PRs — and there has been a public commitment that people can bring stalled upstream contributions here.

Deleting branches before the mapping exists destroys the evidence of which branch backs which PR, and with it the ability to honour that promise.

Acceptance criteria

• Every one of the 42 branches cross-referenced against the 38 open upstream PRs
• The mapping published in this issue before a single branch is deleted
• Branches backing an open PR preserved as pr/<number>-<slug>, with the original author credited
• An issue opened per adopted PR
• Only then, the remainder deleted

Merging two or three of these is the cheapest credibility available: direct proof that contributing here is not a wasted afternoon. Worth prioritising over roadmap work.

[kinlane]

Correction — the premise of this issue does not hold, and the risk is the opposite of what is described here.

Checked today.

This repository has one branch.

$ git ls-remote --heads https://github.com/api-commons/spotlight-tools.git | wc -l
1
$ gh api repos/api-commons/spotlight-tools/branches --jq '.[].name'
main

The fork was created by pushing a single snapshot to main, not by copying upstream's refs. There are no 42 inherited branches here, so there is no branch cleanup to guard against, and the "one-way, blocks cleanup" framing at the top of this issue is wrong.

The counts are also off. Upstream has 29 heads and 35 open pull requests today, not 42 and 38 — that gap is ordinary drift since the numbers were first written down.

$ git ls-remote --heads https://github.com/stoplightio/spectral.git | wc -l
29
$ gh pr list --repo stoplightio/spectral --state open --limit 100 --json number | jq length
35

Where the 41 branches actually are. A local clone on the maintainer's machine — originally cloned from stoplightio/spectral, with origin later repointed here — still holds 41 remote-tracking refs. Upstream now has 29. So roughly a dozen of those branches no longer exist anywhere but that one working copy, because upstream deleted them after merging or abandoning the work.

That inverts the risk. The danger was never "we delete branches and lose the mapping." It is that the only surviving copy of a dozen abandoned upstream branches lives in an untracked directory on one laptop, and a git gc or a fresh clone ends them. Nothing here is protecting them, because they were never here.

Also worth stating plainly: most open upstream pull requests come from contributors' own forks, so their branches were never in stoplightio/spectral either and are not at risk. The at-risk set is specifically the branches that once lived upstream and have since been removed.

Revised acceptance criteria

• Push the 41 cached refs from the local clone to a durable location before anything else — a preserved/ namespace here, or a dedicated archive repository
• Diff the 41 against upstream's current 29 to identify precisely which are extinct elsewhere
• Cross-reference the survivors against the 35 open upstream pull requests, by head ref and by author
• Publish the mapping here
• Preserve anything backing an open PR as pr/<number>-<slug>, crediting the original author
• Open an issue per adopted PR

The closing line of the original issue still stands and is the reason to do this at all: merging two or three stalled upstream contributions is the cheapest credibility available to this project.

[kinlane]

Acceptance criterion 2 is done: here is the precise diff. "Roughly a dozen" is 15.

Cached refs in the local clone against upstream's current heads:

$ git branch -r | sed 's|.*origin/||' | grep -v HEAD | sort > local.txt      # 41
$ git ls-remote --heads https://github.com/stoplightio/spectral.git \
    | sed 's|.*refs/heads/||' | sort > upstream.txt                          # 29
$ comm -23 local.txt upstream.txt

Cached locally, gone from upstream — 15 branches:

Branch	Shape
feat/mob-programming-1	Feature work
feat/ruleset-migrator/v2	Feature work
feat/rulesets/aliases-in-oas	Feature work
feat/rulesets/validate-security-scopes	Feature work
feat/runtime/utils	Feature work
chore/arm-builds	Build/tooling
chore/cli/deps	Build/tooling
chore/deps/jest	Build/tooling
chore/deps-dev/socket-io	Build/tooling
fix/cli/deps	Fix
dependabot/npm_and_yarn/sigstore-4.1.1	Dependabot
dependabot/npm_and_yarn/sigstore/core-3.2.1	Dependabot
dependabot/npm_and_yarn/sigstore/verify-3.1.1	Dependabot
dependabot/npm_and_yarn/tmp-0.2.7	Dependabot
develop	Stale cache, not extinct — see below

The four Dependabot refs are disposable; they will have been closed or superseded. The five feat/* branches are the interesting ones — abandoned feature work that exists nowhere else, and exactly the "stalled contribution" this project has publicly offered a home to.

develop in that list is an artifact of the cache being stale, not a deletion. Upstream's develop is alive and is still their default branch (5c8104fd); the local ref is simply an old copy. Do not read it as extinct.

Three branches exist upstream that the local clone never fetched:

actions-sanitiization
chore/eslint-10-upgrade
fix/pin-actions

Worth a look on its own account — two of the three are upstream hardening their GitHub Actions configuration, which is the same class of problem as #16, arrived at independently. Upstream pushed as recently as today, so this is a live repository, not an abandoned one, and the survey in #13 should say so.

Correction to my own framing above: the extinct set is 15, not "roughly a dozen," and one of the 15 is a cache artifact rather than a deletion — so 14 genuinely extinct branches, of which 4 are Dependabot noise. The set actually worth preserving is ten.

Criterion 1 — pushing the cached refs somewhere durable — is still the urgent one and is still not done. Until it is, those ten exist on one laptop.

[kinlane]

Criterion 3 done — and it shrinks this issue considerably. Also correcting two numbers I got wrong above.

Corrections first

• The cache holds 40 branches, not 41. My count included refs/remotes/origin/HEAD, which is a symbolic pointer, not a branch.
• develop does not belong on the extinct list. It appeared there because the same counting bug put it in the input twice, and comm duplicated it out. refs/remotes/origin/develop exists locally at 2b6191b9 and upstream at 5c8104fd — it is a stale copy of a live branch, which is what I said, but it should never have been in the list at all.

Recomputed with deduplicated, LC_ALL=C-sorted inputs: 40 cached, 29 upstream, 14 extinct. The headline number is unchanged — the earlier "14 genuinely extinct" was right by accident, arrived at by subtracting develop from a list of 15 that should have been 14 all along.

The cross-reference

Of upstream's 35 open pull requests, only 12 come from branches in stoplightio/spectral. The other 23 come from contributors' own forks — those branches were never in upstream's repository, are not in this cache, and cannot be preserved from here by anyone except their authors.

Of those 12, this cache holds 9:

Upstream PR	Author	Branch	Opened
#2907	SB-ChetanKorde	gha-STOP-4939-OASRules	2026-03-05
#2985	copilot-swe-agent	copilot/fix-release-job-failure	2026-06-30
#2972	dependabot	undici-6.27.0	2026-06-20
#2973	dependabot	form-data-4.0.6	2026-06-21
#2974	dependabot	babel/core-7.29.7	2026-06-24
#2978	dependabot	js-yaml-3.15.0	2026-06-30
#3011	dependabot	brace-expansion-1.1.16	2026-07-20
#3012	dependabot	engine.io-6.6.9	2026-07-21
#3017	dependabot	fast-uri-3.1.4	2026-07-24

Seven are Dependabot and one is Copilot. Strip those and the "adopt a stalled upstream contribution" promise, as it applies to branches this cache actually holds, comes down to one human pull request — #2907, open since March.

None of the nine are extinct. All still exist upstream. So the pr/<number>-<slug> preservation in the original acceptance criteria protects nothing that is currently at risk.

The three upstream branches this cache never fetched are all kopernic-pl, all recent, and all open PRs: #3021 chore/eslint-10-upgrade, #3024 actions-sanitiization, #3025 fix/pin-actions. Two of the three are upstream hardening their own GitHub Actions — the same class of problem as #16, found independently, the same week.

What is actually at risk

Inverting the join: every one of the 14 extinct branches has no open pull request. Their PRs were closed, or never opened. Four are Dependabot refs and are disposable. That leaves ten, and the five that matter are abandoned feature work:

feat/mob-programming-1
feat/ruleset-migrator/v2
feat/rulesets/aliases-in-oas
feat/rulesets/validate-security-scopes
feat/runtime/utils

Nobody has an open PR for these. Upstream has deleted them. They exist in one directory on one laptop. If there is a reason to preserve anything, it is these five — not the PR-backed branches, which are safe where they are.

Revised, again

• Diff the cached refs against upstream — 40 / 29 / 14 extinct
• Cross-reference against the 35 open upstream PRs — 12 upstream-branch, 9 cached, 1 human
• Publish the mapping
• Push the 40 cached refs to preserved/* here — attempted today, blocked pending approval on a bulk-branch push
• Read the five extinct feat/* branches and decide, per branch, whether the work is worth adopting
• Approach SB-ChetanKorde about #2907 — the only human PR in scope, and the cheapest credibility available

The closing line of the original issue still stands, but it is now a much narrower claim: there is one stalled human contribution here to offer a home to, not a pool of them. Saying that plainly is better than implying a queue that does not exist.