From 2f5c75ea1ac0177b443981b95865d09c777f61de Mon Sep 17 00:00:00 2001 From: tucktuck101 Date: Sat, 22 Aug 2026 00:12:23 +1200 Subject: [PATCH] =?UTF-8?q?docs(decisions):=20record=20ADR-0021=20and=20AD?= =?UTF-8?q?R-0022=20=E2=80=94=20merge-based=20adoption,=20curation=20scope?= =?UTF-8?q?d=20to=20the=20contested=20surface?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ADR-0021: upstream is adopted by merging the vendor drop; a decline is a row in the divergence ledger, not an omitted commit. Cherry-pick-only rejected as decline-by-default (67 commits / 796 files evaluated to protect 8); hybrid-by-scope rejected as inexpressible (git has no per-path merge-base). The load-bearing argument is recorded: the ledger plus `main` makes a decline revisitable via `git diff main launchpad -- `, so merging is not the one-way door it appears to be. ADR-0022: per-drop adjudication covers only the contested surface — files the fork has modified that upstream also touched. The remaining 99% is adopted wholesale by stated policy, because adjudicating all 67 commits degrades into skimming, which is worse than an honest blanket policy since it looks like review. Records the counter-example against itself: upstream's bin/.lefthookrc merges clean, is not in the ledger, and reintroduces #196. Closes #304 Refs #306 (scope half only; report shape, unit and model involvement stay open) Signed-off-by: tucktuck101 --- ...e-based-adoption-with-recorded-declines.md | 169 ++++++++++++++++++ ...uration-scoped-to-the-contested-surface.md | 151 ++++++++++++++++ 2 files changed, 320 insertions(+) create mode 100644 launchpad/decisions/ADR-0021-merge-based-adoption-with-recorded-declines.md create mode 100644 launchpad/decisions/ADR-0022-curation-scoped-to-the-contested-surface.md diff --git a/launchpad/decisions/ADR-0021-merge-based-adoption-with-recorded-declines.md b/launchpad/decisions/ADR-0021-merge-based-adoption-with-recorded-declines.md new file mode 100644 index 00000000000..53c4707d5d3 --- /dev/null +++ b/launchpad/decisions/ADR-0021-merge-based-adoption-with-recorded-declines.md @@ -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 -- +``` + +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. diff --git a/launchpad/decisions/ADR-0022-curation-scoped-to-the-contested-surface.md b/launchpad/decisions/ADR-0022-curation-scoped-to-the-contested-surface.md new file mode 100644 index 00000000000..830ba6629c0 --- /dev/null +++ b/launchpad/decisions/ADR-0022-curation-scoped-to-the-contested-surface.md @@ -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.