Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
---
status: Accepted
date: 2026-08-22
issue: launchpad-26/buzz#304
decided_in: launchpad-26/buzz#304
supersedes: none
---

# ADR-0021 — Upstream is adopted by merging; a decline is recorded, not withheld

## Decision

**The fork adopts upstream by merging the vendor drop. A decision not to take an upstream
change is recorded in the divergence ledger, not expressed by declining to merge.**

`launchpad-26/main` is a vendor branch — upstream pinned at a chosen point, advanced
deliberately. A drop is merged into `launchpad` in full. Where the cohort disagrees with
upstream's implementation, that disagreement is a **row in the ledger** stating the fork's
standing position and the mechanism that enforces it, not an omitted commit.

Two alternatives are rejected outright:

- **Cherry-pick only what is wanted.** Rejected because it is *decline-by-default*: to adopt
anything you must positively evaluate everything. In the drop measured while this was
decided, that is **67 commits across 796 files evaluated to protect 8**. Upstream's tempo
being too fast for the cohort to keep up is the reason this work exists at all, so the
posture that scales with total upstream churn rather than with contested files is the wrong
one. It also never advances the merge-base, so the gap and the conflict surface grow
monotonically, and adopted commits exist twice under different hashes — which progressively
degrades the branch-to-branch comparison the vendor branch exists to provide.
- **Hybrid by scope** — merge outside a declared owned surface, cherry-pick within it.
Rejected as **not expressible**: git has no per-path merge-base. Approximating it means a
merge plus per-path overrides, which is this decision described less clearly.

**The load-bearing argument, and the reason this is not the one-way door it appears to be.**

The obvious objection to merging is that the merge-base advances, so git records every
declined commit as integrated and will never offer it again — the disagreement is recorded
once, invisibly, and cannot be revisited. That is true of git's merge machinery **considered
alone**. It is not true of this fork, because the vendor branch holds upstream's version at a
known point indefinitely:

```
git diff main launchpad -- <path>
```

shows exactly what was declined and exactly what adopting it later would cost. **The ledger
plus `main` is what makes the door two-way.** Git is not asked to remember the decision; the
ledger remembers the position and `main` remembers upstream's content. Neither alone is
sufficient — a ledger without the vendor branch records a position with nothing to compare it
against, and a vendor branch without a ledger preserves upstream's version with no record of
why the fork went the other way.

This is also the argument for keeping the two-stage design (`main` as vendor branch,
`launchpad` as the working branch) rather than merging `upstream/main` directly into a branch
off `launchpad`. Two earlier reviews recommended collapsing it on the grounds that `main` had
no consumer. Under this decision `main` **is** the consumer of record: it is the baseline that
makes a decline recoverable.

## Context

The fork carries deliberate divergence from `block/buzz` and expects it to grow. It does not
want to track upstream; it wants to adopt selectively, taking what it wants and deliberately
diverging where it disagrees with upstream's direction. PRD #273's original premise — "keep the
fork current" — was wrong, and correcting it surfaced this as the decision everything else
hangs from.

Measured on 2026-08-21 against merge-base `f8692fa9b` (2026-08-17):

| | Count |
|---|---|
| Files tracked on `upstream/main` | 4,294 |
| Upstream files the fork has modified | 48 (1.1%) |
| — fork-only additions, which cannot conflict | 21 |
| — deletions | 2 |
| — **true modifications of files upstream still owns** | **25** |
| Upstream commits not yet adopted | 67 |
| Upstream files those commits touch | 796 |
| **Of those 796, files the fork also touches** | **8** |
| Files conflicting on a test merge | 4 |

The asymmetry is the whole argument. **99% of what upstream did is uncontested** — the fork has
no opinion about it and never will. Any mechanism whose cost scales with total upstream churn
rather than with contested files is the wrong shape for this repository.

Two further options were considered and rejected as *standing* mechanisms, though either may be
right for an individual case:

- **Merge, then revert what is unwanted.** Uses only core git and leaves a readable record. But
a revert is *content* on `launchpad`: it conflicts with any later upstream change to the same
code, adoption after a revert is manual, and reverting a multi-file upstream commit takes down
changes the fork actually wanted. Workable for a handful of clean, isolated declines; poor as
the general rule.
- **Squashed vendor drops** — import each drop as a single commit and discard upstream's
individual history. The classic vendor-branch pattern, and it makes the drop-to-drop diff the
natural review artifact. Rejected because it destroys upstream authorship and `git blame`
across 4,294 files, and the fork already holds upstream's real history for free.

A mechanism note that constrains how declines are enforced, recorded here because it is easy to
assume otherwise: **`rerere` is a labour-saver, not a durability mechanism.** It matches on a
hash of the conflict preimage, so when upstream evolves the code surrounding a declined hunk the
preimage changes and the replay silently stops firing — precisely when upstream is most active,
which is the case a vendor fork most needs it for. A merge driver is durable but only
file-granular. Neither alone can hold a position such as "upstream wins on all of `lefthook.yml`
except one line", which is the actual shape of one of the fork's existing divergences. Ledger
rows therefore carry a mechanism as well as a position; that is #294's subject, not this record's.

## Consequences

**Good.** Uncontested upstream arrives free. The merge-base advances every drop, so the gap does
not accumulate, and `git diff main launchpad` narrows to the cohort's actual divergence rather
than divergence plus unadopted upstream work. Curation cost tracks the contested surface, which
is the small number.

**Good.** Declines are revisitable rather than lost, for the reason above. A cohort that changes
its mind about a past decline has a one-command way to see what it would cost.

**Bad.** The ledger stops being documentation and becomes a **control surface**. A missing row is
now a lost decision, not merely an undocumented one — the file silently gets default treatment
and nothing reports that a position was dropped. This raises the stakes on whether the ledger is
machine-checked (#301) and on what a row must contain (#294).

**Bad, and true under every option considered.** No mechanism makes permanent disagreement inside
a *shared* file cheap. The cost is proportional to how much upstream keeps changing code the fork
has overridden, and nothing in this decision controls that. The only real lever is expressing
disagreement as a fork-owned file rather than an edit to upstream's, which is a separate open
decision (#307).

**Bad.** The first drop is the expensive one — 67 commits, 8 contested files, 4 live conflicts,
and no recorded resolutions to draw on. The mechanism should not be judged by how that drop feels.

**Bad, and accepted.** Merging means the fork takes upstream content it has not read. That is
already true of how the fork relates to upstream and is not a new exposure, but this decision
makes it policy rather than habit. What is reviewed per drop is settled separately in ADR-0022.

## Security implications

A durable decline is durable **against upstream security fixes too**. If a ledger row is enforced
by a merge driver, upstream's fix to that file is silently discarded on every future drop, with
nothing reporting it. Two row-groups in the current ledger are exactly this shape: `bin/lefthook`
and `bin/.lefthook-*.pkg` select the binary that executes on every commit and push, and
`Dockerfile` and `deploy/compose/compose.yml` determine which image the fork deploys — #141 was
the failure of unknowingly running someone else's build. ADR-0017's position for the lefthook pin
is "whichever version is newer", which is neither side and is precisely the shape that keeps
upstream's fixes flowing; that is the pattern to prefer for security-relevant rows. Any row whose
mechanism is "fork always wins, automatically" must be flagged in the ledger as requiring review
at each drop rather than trusted to hold itself.

Merging also means ~788 uncontested files per drop enter the fork unread. That is the accepted
posture, bounded by ADR-0022, and it is stated there rather than assumed here.

## Provenance

Decided by @tucktuck101 in conversation on 2026-08-22, after a recommendation.

**His call:** merge-based adoption over cherry-picking, and the two rejections — cherry-pick-only
as decline-by-default, and hybrid-by-scope as inexpressible.

**The recommendation:** merge with declines enforced from the ledger at whatever granularity each
file needs, drafted as option A in #304 by an AI agent (Claude Opus 5) on 2026-08-22, together
with the ledger-plus-`main` two-way-door argument and the 8-of-796 measurement that the decision
turned on. The agent drafted the options and the evidence; it did not choose between them.

**Why the reasoning is recorded and not only the rule.** The objection this decision has to answer
— that merging makes a decline permanent and invisible — is correct on its face and will be raised
again by anyone who has run a vendor branch before. The answer is not "merging is fine"; it is
that the ledger and the vendor branch together restore what git alone forgets. A record that
stated the rule without that argument would be re-litigated at the first drop that declines
something anyone cares about.
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
---
status: Accepted
date: 2026-08-22
issue: launchpad-26/buzz#306
decided_in: launchpad-26/buzz#306
supersedes: none
---

# ADR-0022 — Curation covers the contested surface; the rest is adopted wholesale by policy

## Decision

**Per-drop adjudication covers only the contested surface: files the fork has modified that
upstream has also touched since the last vendor drop. Everything else upstream changed is
adopted wholesale, without per-change review, by stated policy.**

In the drop measured while this was decided, that is **8 files out of the 796 upstream
touched**. The remaining 788 are taken unreviewed — deliberately, as a recorded position, not
as an oversight.

This is premised on [ADR-0021](ADR-0021-merge-based-adoption-with-recorded-declines.md).
Under merge-based adoption there is a coherent "remainder" to adopt wholesale; under
cherry-picking there is no remainder, because nothing arrives unless it is chosen.

**Why, and not just what.** The alternative — adjudicating all 67 unadopted upstream commits,
or all 796 files they touch — is unaffordable at upstream's tempo, which is the reason PRD #273
exists. An artifact too long to read does not produce review; it produces skimming. **A skimmed
review is worse than an honest blanket policy, because it looks like review.** It carries the
same cost in attention, delivers none of the assurance, and leaves a record implying files were
examined when they were not. The cohort would rather state plainly that 99% of upstream is
adopted unread than maintain a ritual that claims otherwise.

The scope is computed, not curated by hand: the contested surface is the intersection of the
divergence ledger's rows with the files upstream changed in the drop.

## Context

The corrected premise of PRD #273 is that the change agent's job is curation — surface what
upstream changed since the last drop, propose adoption or decline per change, make the declines
durable. "Per change" left the unit open, and the unit determines whether the whole thing is
affordable.

Measured on 2026-08-21 against merge-base `f8692fa9b` (2026-08-17):

| Unit of adjudication | Items a human must consider |
|---|---|
| Per upstream commit | 67 |
| Per upstream file touched | 796 |
| **Per contested file** | **8** |

All three describe the same drop. The fork has modified 48 of upstream's 4,294 files (1.1%), of
which 27 can ever conflict; 8 of those 27 were touched by this drop and 4 conflicted.

There is a real tension in the requirement, and this record resolves it rather than leaving it
to be discovered. "Selectively adopt" sounds like reviewing everything and choosing. But
selective adoption is *more* expensive per change than wholesale merging, not less, and the
stated reason this work exists is that upstream's tempo is already too fast to keep up with. The
requirement is coherent **if and only if** curation is scoped to the surface the fork actually
has opinions about. Scoped that way it is affordable and honest. Scoped to everything it is
neither.

Three other options were considered:

- **Per-commit adjudication of all 67.** The most literal reading, and nothing passes unseen.
Rejected for the skimming argument above.
- **Areas rather than files** — group by subsystem (relay, desktop, mobile, CI) and adjudicate
per area. Closer to how the cohort thinks, and it scales as the contested surface grows.
Rejected for now because the grouping has to be defined and maintained, and an area-level
"adopt" hides file-level surprises; it remains available if the contested surface outgrows a
per-file list.
- **No artifact — just `git diff main upstream/main`.** Complete by construction and free.
Rejected: 796 files is a haystack, not a review artifact, and it carries none of the ledger
context that makes a decline decidable.

**What this does not decide.** #306 asked more than the scope question, and the rest stays open:
the drop report's shape and format, how contested items are presented, whether a model writes any
part of it, and how the uncontested remainder is summarised. Those are still that issue's subject.
This record settles only which files are adjudicated and which are not.

## Consequences

**Good.** Curation becomes affordable — 8 items rather than 796 — which is the difference between
a practice that survives and one abandoned after two drops. The scope is computed from the ledger,
so it needs no separate maintenance.

**Good.** An unexamined habit becomes a stated policy that can be argued with. The fork already
adopts upstream largely unread; writing that down makes it reviewable rather than tacit.

**Bad, and the most important cost here: an upstream change to a file the fork does not currently
touch is taken unreviewed, and that is exactly how the worst hazard found so far arrives.**
Upstream's new `bin/.lefthookrc` sets `LEFTHOOK_BIN` to the Hermit-pinned `bin/lefthook` at 2.1.3
— the version ADR-0017 records as crashing every contributor's first push in this fork, because
the branch name `launchpad` collides with the top-level `launchpad/` directory. That file is not
in the ledger, does not conflict, and merges clean. Under this decision it is adopted without
review, reintroducing filed bug #196.

**This scope ruling does not solve that, and nothing in this record should be read as claiming it
does.** A clean merge is not evidence of a correct merge. Detecting this class of failure requires
building and testing the drop — `just ci` on the drop PR — which is blocked separately (#299) and
is not something curation scope can deliver. The honest statement of the residual risk is: the
contested surface catches disagreements the fork has already recorded, and catches nothing else.

**Bad.** The contested surface is computed from the ledger, so an incomplete ledger produces a
report that is *confidently* incomplete — it will not mention a file it does not know is
contested, and it will not look empty while doing so. That is a worse failure mode than an
obviously missing report, and it is the strongest argument for the ledger being machine-checked
(#301).

**Bad, and accepted.** A security fix upstream ships to an uncontested file is adopted unread on
the next drop, which is the desired outcome, but a security *regression* in the same file is
adopted just as silently. The compensating control is upstream awareness (#3), not curation.

## Security implications

This record formalises adopting roughly 99% of upstream's changes without per-change review. That
is the fork's existing posture — it runs upstream's code today — so the decision does not create
the exposure, but it does make it policy, and policy should be stated at its true strength: **the
cohort accepts externally-authored code into its deployed build without reading it, on every
drop.**

Two things bound that. First, the fork merges from a single upstream it already depends on
wholesale, not from many; the trust decision is one relationship, made once, not 796 decisions per
drop. Second, the vendor branch pins upstream at a chosen point rather than tracking HEAD
(ADR-0021), so the content adopted is a point somebody selected rather than whatever was pushed
that hour.

What is *not* bounded, and should not be presented as though it were: nothing in this decision
inspects the 788 unreviewed files for hostile or broken content, and the `bin/.lefthookrc` case
above demonstrates that a merge-clean upstream file can carry a defect with real local
consequences — in that instance, changing which binary executes on every commit and push. The
control for that is building and testing the drop before it merges, which is a different decision
and is currently unresolved.

## Provenance

Decided by @tucktuck101 in conversation on 2026-08-22, after a recommendation.

**His call:** that curation is scoped to the contested surface and the remainder is adopted
wholesale by policy, and that the reason — not merely the rule — be recorded.

**The recommendation:** the same scoping, drafted as option A in #306 by an AI agent (Claude Opus
5) on 2026-08-22, together with the affordability analysis, the 67 / 796 / 8 comparison, and the
argument that a skimmed review is worse than an honest blanket policy. The agent had raised the
tension in the requirement as a strain worth naming rather than working around; this decision
resolves it. The agent drafted the options and the evidence; it did not choose between them.

**Recorded against the agent's own finding.** The `bin/.lefthookrc` hazard in Consequences was
found by that agent while sweeping this PRD, and it is the clearest single argument *against* the
decision recorded here. It is written into the record deliberately, at the decider's instruction,
rather than left in an issue comment — a scope ruling whose known counter-example lives somewhere
else is a scope ruling nobody can evaluate.
Loading