docs(research): the drop report is 3 git commands; Copybara is the wrong shape, wei/pull is a live candidate (#368)

[tucktuck101]

Summary

Adds one research document assessing off-the-shelf tooling for vendor-drop automation. The drop report's core computation turns out to be two git commands running in 0.06 seconds, reducing 912 files to 8 contested and 80 commits to 14 to adjudicate; a third, git range-diff, mechanically finds the one divergence that has converged with upstream. Copybara is rejected with reasons (one-authoritative-repository model), wei/pull is identified as a live candidate nobody had assessed, and #356's claim that no relay changelog exists is corrected.

Related issue

Closes #368

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/368-existing-vendor-drop-tooling.md assessing existing tools for vendor-drop automation and drop-report computation against this fork's actual requirement.

Impacted components

launchpad/Research/368-existing-vendor-drop-tooling.md

Approach and rejected alternatives

Measured the bespoke baseline first, so every tool could be judged against a real number rather than an assumption about how hard the job is. That number — two commands, 0.06 seconds, 912 files to 8 — is what makes most of the candidates unnecessary rather than merely unsuitable.

Read ADR-0009 and ADR-0010 before searching, per this issue's own definition of done. That is where the relay-changelog correction came from: ADR-0009 recorded crates/buzz-relay/CHANGELOG.md on 2026-08-10 and I had missed it when answering #356.

Assessed Copybara from its own README rather than from commentary, because the decisive fact is its data model and a summary would have lost it.

Rejected: dismissing wei/pull as the naive answer, which is what I expected to do when filing this issue. Its conflictReviewers / conflictLabel / mergeMethod surface maps onto three separate things #273 is designing, so dismissing it would have been the exact "nobody looked" failure this question exists to prevent.

Rejected: recommending wei/pull. It is a third-party app needing write access to a public repository, and mergeMethod: hardreset is an irreversible action — the class this PRD's own non-goals single out. That is a privilege decision for whoever owns ADR-0015 and #103, not a tooling preference.

Rejected: rejecting Copybara for being heavyweight. JDK and Bazel are a cost, not a reason. The reason is that it models one authoritative repository and this fork has two by design.

Verification

Command run:

MB=f8692fa9b52ddcfeb4b95fb4862109983509f131
time ( comm -12 <(git diff --name-only $MB launchpad/launchpad | sort) \
                <(git diff --name-only $MB upstream/main | sort) )
git log --oneline --no-merges $MB..upstream/main -- $(cat contested.txt) | wc -l
git range-diff --no-color $MB..launchpad/launchpad $MB..upstream/main | grep -E '^ *[0-9]+: ' | grep -E ' (=|!) '
git log --oneline --cherry-mark --left-right --no-merges launchpad/launchpad...upstream/main | grep '^='
git ls-tree -r --name-only upstream/main | grep -i CHANGELOG
git diff --name-only $MB upstream/main | grep -i changelog
ls launchpad/upstream-intel

Raw output:

$ time ( comm -12 ... )
8
( ... ) 0.00s user 0.00s system 9% cpu 0.063 total

$ git log --oneline --no-merges $MB..upstream/main -- $(cat contested.txt) | wc -l
      14

$ git range-diff ... | grep -E ' (=|!) '
209:  765746534 !   6:  cc8a8b0dc fix: bump h2 0.4.14 -> 0.4.18 (RUSTSEC-2026-0258)

$ git log --cherry-mark --left-right ... | grep '^='
(no output)

$ git ls-tree -r --name-only upstream/main | grep -i CHANGELOG
CHANGELOG.md
crates/buzz-relay/CHANGELOG.md
mobile/CHANGELOG.md

$ git diff --name-only $MB upstream/main | grep -i changelog
CHANGELOG.md

$ ls launchpad/upstream-intel
ls: launchpad/upstream-intel: No such file or directory

Copybara and wei/pull quotations are verbatim from the pages linked in the document.

• 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

The load-bearing gap: whether a GitHub App-authored pull request triggers pull_request workflows. My belief that it does rests on the general distinction between the built-in Actions token and an App installation token, not on a test or a documentation quote. If it is wrong, the wei/pull case for #299 collapses. One throwaway PR would settle it and I did not run one.

Everything about wei/pull comes from its own documentation — I did not install, configure or run it, and I did not check its permission scopes, maintenance status or incident history, all of which matter for a third-party app with write access. I did not evaluate git-subtree or git-subrepo beyond their purpose; they vendor a subdirectory while this fork forks a whole repository, so the mismatch is structural rather than tested. I did not look for distribution import scripts as reusable tools. I did not fully parse git range-diff's summary format — I counted matched pairs by grepping for ! and = and verified the single hit by reading it, but my counts of ours-only and theirs-only rows were unreliable and are deliberately not reported. I measured the pipeline in a warm worktree only, not on a cold cache or fresh clone. I ran no builds and no cargo: disk on this machine is at 99% capacity with 5.2 GiB free, and nothing here required a build.

Security implications

The diff is one document. One finding is a genuine security decision rather than a tooling note, and the document says so rather than burying it: wei/pull is a third-party GitHub App that would hold write access to a public repository, and mergeMethod: hardreset is an irreversible action against a shared branch. That is the same class of risk ADR-0015 and buzz-infrastructure #103 govern, and this PRD's non-goals already record that the cohort has lost a repository to an agent taking an irreversible action with legitimately granted privilege. Adopting it is a privilege and supply-chain decision, not a convenience choice. The document raises it; it does not recommend it.

Escalations

#306 is much smaller than its framing and someone should say so before it is scoped as a large work item. The computation is three commands; what remains bespoke is presentation, and #365 established that PR #216's body is already a worked template. "Wire three git commands into the shape of an existing PR body" is a different size of task from "design an artifact".

#305 and #299 both have off-the-shelf options nobody weighed — wei/pull for both, GitHub's merge-upstream for main. Neither is consequence-free, but "we assumed bespoke" was the assumption in both issues and it should be revisited on merit.

A correction to my own #356 answer is owed. I concluded there that the relay has no changelog of its own. It has one — crates/buzz-relay/CHANGELOG.md — which ADR-0009 had already recorded. The substance of #356's conclusion survives (it is stale, updates only on relay tags, and contains desktop and mobile entries, so there is still no reliable relay-scoped signal) but the specific claim was false. #356 is closed via merged PR #375, so this correction lives here rather than being edited into it.

ADR-0009 left open exactly the problem this pipeline solves. It records that relay-only scoping "does not by itself bound what content a relay report might touch — that's a separate reduction problem, not solved by this decision." The two-command pipeline is a solution to that reduction problem, and #306 should treat it as an open item ADR-0009 flagged rather than new ground.

[tucktuck101]

Updated for the handbook source-material contract

Force-pushed an amended commit bringing this document into line with two conventions introduced after it was written, since it is unmerged and retrofitting after merge is the expensive case:

1. Every reference pinned to a full 40-character SHA. Fork-side claims cite launchpad-26/buzz at 5d76799d6e44f2f76aa7bd78c5343d339af98f63; upstream-side claims cite block/buzz at 025425591ed67518a63870316f1473ffd02dd520. The SHAs are stated once near the top and the individual references link to them, so the handbook's staleness detection can read the pins.

Two judgement calls made while doing it, flagged so a reviewer can overrule:

• Paths inside fenced blocks are left unlinked, deliberately. Those are command output; linking them would misrepresent what the command printed. Each document now says so where the pins are declared.
• A filename that is not a file in this repository is named, not linked. .github/pull.yml in the task: assess existing tooling for vendor-drop automation and drop-report computation #368 document is wei/pull's own config filename; dev-dependencies is a cargo concept. Neither is a citation, and the rule catching them is the rule working.

2. Recommendations separated from evidence and attributed. Each ## What this means for #273 section now opens with an explicit note that it is my recommendation as the author, carries no source reference, and that the evidence is above while the judgement is mine. Where a document contains something I authored rather than found — the CODEOWNERS pattern set in #369 — that is labelled in place as a proposal rather than as repository content.

No finding, figure or caveat changed. The diff is pins, section labels, and one external link moved off blob/master onto a commit SHA.

_{AI agent (Claude Opus 5) on behalf of @tucktuck101, 2026-08-22.}

[tucktuck101]

Revised for the fork's horizon (#357)

Force-pushed an amended commit adding a ## Revised for the fork's horizon (#357) section, after @tucktuck101 decided on 2026-08-22 that the fork has no expected lifetime beyond the cohort project, nobody owns upstream adoption after it ends, and the hard end is 2026-09-17.

No evidence, figure or caveat changed. Every measurement and quotation stands exactly as reviewed. What changed is the recommendations — which are now explicitly marked as mine, so the revision is visible rather than a silent rewrite.

I added the section rather than editing the original recommendations in place, so anyone who already read this document can see what moved and why.

Where a recommendation of mine was wrong under the real horizon, I have said so and withdrawn it rather than softening it. The reversals are named in the section.

_{AI agent (Claude Opus 5) on behalf of @tucktuck101, 2026-08-22.}

[serina-mcfall]

No blockers — two follow-up issues filed

I reproduced your entire measured pipeline at your own pinned refs, and it is exact.

MB=f8692fa9b  FORK=5d76799d6  UP=0254255

upstream-side changed files MB..UP:  912
contested (comm -12):                  8
commits MB..UP no-merges:             80
commits touching contested:           14

All four figures match. The 14-commit list I got is line-for-line identical to the one pasted in the note, down to cd0d33f08 fix(hooks): scope pre-push lanes…. The 8 contested files are the same 8. git ls-tree -r --name-only $UP | grep -i CHANGELOG returns exactly the three changelogs you quote, so the #356 correction is right.

This matters more than it might look. A prior batch nearly change-requested a correct document because a reviewer ran its command against a moved upstream/main instead of the pinned tip. Your refs are pinned properly, so the figures reproduce for anyone who reads carefully — which is the whole point of the genre.

The Copybara rejection is genuinely sourced. I checked every quotation against the live README: "transforming and moving code between repositories", "there is always one source of truth", "Importing sections of code from a confidential repository", "JDK 11", "released automatically without any manual testing, version compatibility or correctness guarantees", "As a label in the commit message". All verbatim. The conclusion follows from them.

Filed, not blocking

• #444 — wei/pull is called "a live candidate" in the title and summary with no date attached, while your own limits section says maintenance status was not checked. The dates: last commit on the default branch 2025-11-29 (~9 months before this note), newest release an alpha from 2025-09-13, 17 open issues including one titled "Pull has removed my files for no reason" — which bears directly on the standing hardreset write grant you flag as the main risk. Not archived, so "live" is not false; it is unevidenced where it is stated. If anyone is going to act on this recommendation, that paragraph needs its dates.

• #445 — the four sizing figures at line 98 ("4,294 files … 27 in-place edits, 21 additions, 259 commits") carry no command and do not reproduce. Two are explicable near-misses (27 = M+D, counting 2 deletions as edits; 21 is one off the 20 additions outside launchpad/). Two are not — I count 4,032 blobs at the merge-base where you say 4,294, and none of the three standard commit countings gives 259.

  I nearly filed that one as High and the recount talked me out of it: the Copybara conclusion does not rest on any of the four, and two-authority is established independently by the 351 fork-side changed files, which does reproduce.

• #449 — one Low, grouped with nits from two other notes. Line 96 presents "requires designating one of the repositories…" as a verbatim quotation; the README says "requires you to choose one of the repositories…". Substance identical, but it is a paraphrase inside quote marks in a document whose discipline is verbatim sourcing.

What I could not check

The git range-diff h2 pairing (765746534 ↔ cc8a8b0dc) and the --cherry-mark empty result — I ran out of budget before running them. Also not checked: the wei/pull config keys (conflictReviewers, conflictLabel, hardreset) against its docs, though its commit log does corroborate mergeUnstable landing 2025-07-14.

---

Reviewed at head 28984b5b6. This is a review, not an approval — approval is not mine to give.

🤖 Review drafted by Claude Code (claude-opus-5) for @serina-mcfall.

[serina-mcfall]

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