docs(fork): add FORK.md upstream-merge friction map - #1
Merged
Conversation
Capture the fork's divergence from upstream in one reference so the conflict-prone code paths are clear on every sync. - FORK.md: divergence-at-a-glance + per-feature friction tables keyed by the actual fork file changes (git log --no-merges upstream/main.. local/daily-driver), with a conflict-risk column grounded in real upstream churn (6-month commit counts per file), fork-only vs modified split, recurring release-mechanics conflicts, a post-merge checklist, and the commands to regenerate the map. - AGENTS.md: trim "Local fork status" to a pointer at FORK.md; relocate the operational nuggets (pnpm vsix --force rebuild, 22-failure test baseline, per-provider reasoning guards) into FORK.md so nothing is lost. FORK.md is a file upstream doesn't have, so it never conflicts on merge — unlike AGENTS.md, which upstream actively edits.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
FORK.md— a single reference for how this fork diverges fromupstreamand which code paths will rub on each sync — and trimsAGENTS.md's "Local fork status" to a pointer.Why here
AGENTS.mdis a file upstream actively edits (3 upstream commits touched it in recent history) and our fork already carries a 36-line diff against upstream's copy — a poor host for a growing fork registry that will itself conflict on every merge.FORK.mdis a file upstream doesn't have, so it never produces merge markers.Contents of FORK.md
git log --no-merges upstream/main..local/daily-driver), each rated on two axes: upstream churn (6-month commit counts per file, real data) × change nature (isolated additive vs. shared-logic). This keeps raw churn from oversellingClineProvider.ts(81 commits, but additive) and undersellingreasoning.ts(5 commits, but the semantic keystone).pnpm vsix --forcerebuild, the 22-failure test baseline, the effort-payload guard.AGENTS.md change
"Local fork status" trimmed to a short pointer at
FORK.md. The operational nuggets (VSIX rebuild, 22-failure baseline, per-provider reasoning guards) moved intoFORK.md— not dropped.## Conventionsand later sections untouched.Notes
FORK.mdexists in the tree.local/daily-driver(this fork's trunk), notmain.