Repository navigation
task: how we track upstream after the fork link is gone #163
Description
Parent: #158.
After the detach there is no Sync fork button and no shared object storage. We still want to see what upstream does — #156 proved that an upstream change can break us — but we want it arriving deliberately, reviewed, never as a 583-file button press.
What this replaces
The fork link gave us a one-click sync that merged everything upstream had done since the last sync. #152 was 583 files, 100+ commits, 20 authors, and it carried a config-contract break (#156) that nobody caught in review and no CI gate could catch.
To decide and write down
- Mechanism. Upstream as a plain git remote plus cherry-pick or format-patch, versus watching their releases and reimplementing. Whichever, it is per-change, not per-batch.
- Cadence. Who looks at upstream, how often, and where the "worth taking" decision is recorded.
- Review checklist for an incoming upstream change, with the bug: upstream sync moved the Carto key to a new config field, breaking map tiles (dev now, prod on next deploy) #156 class on it explicitly: does this change any config field our deployments supply? See task(ci): guard the config contract — fail a PR that reads a config field our deployments do not supply #157 for the CI guard that should make this mechanical rather than remembered.
- Attribution. Upstream commits we take keep their authorship. Settle how — cherry-pick preserves it, a squashed reimplementation does not.
- What we do NOT take. The imported agent surface (EPIC: prune and own the imported AI agent surface (143 files, ~17.2k lines) #144) is being deleted deliberately. It must not come back through this path.
Done when
There is a short written policy in the repo, referenced from AGENTS.md, that a future session can follow to evaluate and take a single upstream change without reintroducing anything #144 removed.
Activity
diffwireauto commentedon Oct 7, 2026
docs/UPSTREAM.mdis written and referenced fromAGENTS.md:5. Branchdocs/163-upstream-tracking, commits0c696c49and9ce3b410.Four of the five required decisions are settled: mechanism (upstream as a read-only remote,
cherry-pick -xper change), review checklist (8 items, the #156 config-field class first), attribution (cherry-pick preserves it, reimplementation does not), and what we never take (#144's agent surface, framed as a principle with examples rather than a denylist).Cadence is split to #184 under the same epic. Who reads upstream and how often is an owner and team decision, not a session's, and leaving it inside this issue would have held the policy hostage to it. The document says plainly that it is unsettled and what that costs.
A Gemini 2.5 Pro adversarial review found real defects, fixed in
9ce3b410: the worktree command was Windows-only, the config-field check dead-ended in a private repo, the upstream-ref grep gave false confidence (it cannot see a path built at runtime, which is how #164 survived ten weeks), there was no rollback guidance at all, and none for a change spanning several commits.Epic #158 stays open. PR to follow.
docs(#163): how we take upstream changes now the fork link is gone
docs(#163): close the gaps an adversarial review found in UPSTREAM.md
docs(#163): how we take upstream changes now the fork link is gone
docs(#163): close the gaps an adversarial review found in UPSTREAM.md