docs(research): upstream has no stable branch and no relay release train; no history rewriting observed (#356)

[tucktuck101]

Summary

Adds one research document establishing that block/buzz has no stable, LTS or release branch — main is its only protected long-lived branch out of 793 — and that its tag and release machinery is a desktop release train, with the relay getting three tags in two months, no GitHub Release and no changelog section. No history rewriting was observed across five historical points spanning two months. Also records that upstream publishes a structured CHANGELOG.md with PR links and commit SHAs, which is a better input for the drop report than deriving a narrative from git diff.

Related issue

Closes #356

Issue type

Task

---

Agent provenance

Field	Value
Harness / provider	Claude Code
Model	claude-opus-5
Session reference	N/A - harness exposes no run id
Initiating human	@tucktuck101

Objective

Add launchpad/Research/356-upstream-ref-conventions.md recording what block/buzz's branches and tags mean and whether a vendor pin is safe against upstream's history.

Impacted components

launchpad/Research/356-upstream-ref-conventions.md

Approach and rejected alternatives

Tested history stability by reachability rather than by policy: picked five historical points the fork actually depends on — the current merge-base, the current main pin, and all three relay-v* tags — and checked whether each is still an ancestor of upstream/main. A force-push would have orphaned at least one. Read ref structure from the API and ref meaning from the changelog's heading-to-tag correspondence.

Rejected: reading upstream's branch protection to answer the rewriting question. GET repos/block/buzz/branches/main/protection returns 404 for this token — it needs push access on that repository — so the settings are unavailable. Reachability probes are weaker evidence but they are evidence I can actually gather, and the document says which it is.

Rejected: inferring tag meaning from tag names alone. relay-v0.2.1 looks like a relay release until you check whether a GitHub Release or a changelog section exists for it. Neither does, which changes what the tag can be relied on to mean.

Rejected: asking an upstream maintainer. Out of scope for a read-only investigation, and the question was answerable from published refs.

Verification

Command run:

for ref in f8692fa9b f53bbd1152464ecbb1de495e2d1d959e156138f0 68a0cc850 0d9be2fde 6e5c462ac; do
  git merge-base --is-ancestor $ref upstream/main && echo "ANCESTOR $ref $(git log -1 --format='%ad' --date=short $ref)"
done

gh api repos/block/buzz/branches --paginate --jq '.[].name' | wc -l
gh api repos/block/buzz/branches --paginate --jq '.[] | select(.protected) | .name'
gh api repos/block/buzz/branches/release --jq '.name'
git tag -l | wc -l
gh api repos/block/buzz/releases --paginate --jq '.[] | select(.tag_name|startswith("relay")) | .tag_name'
git show upstream/main:CHANGELOG.md | grep -nE '^#{2,3} ' | head -6
git log --format='%ad' --date=short upstream/main --since=21.days | sort | uniq -c | tail -5

Raw output:

$ for ref in ...; do git merge-base --is-ancestor $ref upstream/main && ...; done
ANCESTOR f8692fa9b 2026-08-17
ANCESTOR f53bbd1152464ecbb1de495e2d1d959e156138f0 2026-08-06
ANCESTOR 68a0cc850 2026-06-24
ANCESTOR 0d9be2fde 2026-07-10
ANCESTOR 6e5c462ac 2026-08-08

$ gh api repos/block/buzz/branches --paginate --jq '.[].name' | wc -l
     793
$ gh api repos/block/buzz/branches --paginate --jq '.[] | select(.protected) | .name'
main
mobile-release/0.4.10
mobile-release/0.4.11
$ gh api repos/block/buzz/branches/release --jq '.name'
{"message":"Branch not found","documentation_url":"...","status":"404"}
gh: Branch not found (HTTP 404)

$ git tag -l | wc -l
     176
$ gh api repos/block/buzz/releases --paginate --jq '.[] | select(.tag_name|startswith("relay")) | .tag_name'
(no output)

$ git show upstream/main:CHANGELOG.md | grep -nE '^#{2,3} ' | head -6
3:## v0.5.18
5:### Desktop and shared changes
48:### Other repository changes
79:## v0.5.17
81:### Desktop and shared changes
88:### Other repository changes

$ git log --format='%ad' --date=short upstream/main --since=21.days | sort | uniq -c | tail -5
  18 2026-08-17
  22 2026-08-18
  17 2026-08-19
  25 2026-08-20
  14 2026-08-21

• Tests or checks were run and the raw output is pasted above
• The diff is confined to the scope of the linked issue
• No secrets, keys, tokens or hostnames were added to tracked files

Not verified

"No history rewriting" is evidence, not proof. Five reachability probes across two months show stability; they cannot show a policy, and they would not reveal a rewrite that happened and was later restored. I could not read upstream's branch protection settings — the 404 is pasted above — so I cannot confirm force-pushes are disallowed on main, only that the branch is marked protected. I did not establish whether the *-latest and canary tags move; their names imply mutability and they currently point at April, June and July commits, which is consistent with either reading, and observing movement needs two fetches separated by time. I did not read upstream's contributing or release documentation, only its refs and changelog, so a ref policy stated in prose somewhere would have been missed. I did not verify that the 103 bare-semver tags belong to the desktop train — that rests on the ## v0.5.18 ↔ desktop-v0.5.18 correspondence, which is an inference. I did not contact any upstream maintainer. I did not run just ci; the diff is one markdown file.

Security implications

None from the diff. One security-adjacent fact is recorded: because upstream publishes no relay-specific release notes and no relay changelog section, this fork has no upstream channel that would distinguish a relay security fix from any other commit. That bears on #364 and is stated in the document rather than left to be discovered.

Escalations

ci.yml triggers on a branch that does not exist. Its trigger is push: [main, release], and no release branch exists in block/buzz or in launchpad-26/buzz. Harmless today, but #299's analysis should not treat it as a live path, and someone should decide whether to remove it or create the branch. Not fixed here — it is an upstream-owned file and changing it would add a divergence, which is precisely what #307 is about.

A method correction, recorded because a reader could repeat it. My first history-stability test checked whether de1c127fb^2 was still an ancestor of upstream/main. It is not, and that briefly looked like rewriting. It is not: ^2 is the fork's own sync-branch head, not upstream's tip. The merge-base is the valid probe. Written into the document's limits section rather than quietly dropped.

[serina-mcfall]

Independent review — no blockers, nothing to fix

Reviewed in a fresh context. I am an agent and do not approve — posting as a comment so @serina-mcfall can.

Verified exactly:

• Protected branches are main, mobile-release/0.4.10, mobile-release/0.4.11 — the same three names.
• release branch returns 404 Branch not found.
• 176 tags with the exact namespace breakdown (103 bare semver, 29 mobile, 28 desktop, 7 chart, 3 relay, 5 singles); relay tags are relay-v0.1.1, v0.2.0, v0.2.1.
• 116 releases, 0 of them relay.
• All five historical SHAs still ancestors of upstream/main, with the dates claimed.
• CHANGELOG.md's heading structure matches, line numbers included.
• Upstream branch protection 404s for a non-admin token, exactly as reported.

One number moved: 793 branches versus my 794 — a single branch, on a repo creating topic branches continuously. Not load-bearing to the branch-protection conclusion.

The claim most at risk of overreach is correctly bounded. "No history rewriting observed" is hedged in the document's own limits section: "Five reachability probes across two months is evidence of stability, not proof of a policy… I could not read upstream's branch protection settings, so I cannot confirm force-pushes are actually disallowed, only that the branch is marked protected." I independently reproduced both the 404 and all five ancestor checks that back it.

Not verified: whether the *-latest/canary tags move, and the full "103 bare-semver tags belong to the desktop train" inference beyond a three-tag spot check. The document flags both.

No blockers, no non-blocking findings, correct placement, no private-tooling paths.

[benmitchell11]

Reviewed as a research-finding PR (not a code/decision change). Note for the record: this PR's actual title/scope ("upstream has no stable branch and no relay release train; no history rewriting observed", closing #356) differs from what was listed for "#375" in my review assignment — the assignment's text for #375 actually matches PR #380. Reviewing the PR as it actually stands.

What I independently verified against the live repos (not just the pasted output):

• .github/workflows/ci.yml triggers on push: [main, release] exactly as claimed — confirmed by reading the file directly.
• block/buzz branch count: today shows 794 branches with exactly 3 protected (main, mobile-release/0.4.10, mobile-release/0.4.11) — matches the doc's protected-branch claim exactly; the total (793 vs 794) has drifted by one branch since the doc was written, which is expected given upstream's pace and not a defect.
• Tag count: git ls-remote --tags against block/buzz, deduped for ^{} peels, gives exactly 176 — matches.
• The three relay-v* tags and their SHAs (68a0cc850→relay-v0.1.1, 0d9be2fde→relay-v0.2.0, 6e5c462ac→relay-v0.2.1) match exactly what git ls-remote returns today.
• GitHub Releases breakdown: gh api repos/block/buzz/releases today gives 100 bare-semver + 12 desktop-* + 4 singletons = 116 total, 112 desktop-attributable — matches the doc's "112 of 116" claim exactly.
• No relay-* GitHub Release exists — confirmed, empty result.

Not independently re-verified (would require push access to block/buzz or a second point-in-time fetch): the 404 on upstream branch-protection settings (plausible — this is a read-only fork token), and the "no history rewriting" reachability probes themselves (would require pinning the exact historical SHAs and re-running merge-base checks against a full upstream clone, which I did not do given the other checks already corroborate the surrounding structural claims). The doc is explicit and honest that this is evidence, not proof, and says so in its own limits section.

Scope check: the doc reports facts and explicitly defers policy calls to #305/#306/#273 rather than deciding a pin criterion itself ("offered as input to #305, not as a choice"). No overreach found.

No factual errors found in what I could check. Citations, counts, and SHAs all reproduce against the live repos today.

[serina-mcfall]

Approved. Independent review found no blockers; non-blocking findings are filed as follow-up issues.