Skip to content

docs(fork): add FORK.md upstream-merge friction map - #1

Merged
zephg merged 1 commit into
local/daily-driverfrom
local/fork-divergence-map
Jul 11, 2026
Merged

docs(fork): add FORK.md upstream-merge friction map#1
zephg merged 1 commit into
local/daily-driverfrom
local/fork-divergence-map

Conversation

@zephg

@zephg zephg commented Jul 11, 2026

Copy link
Copy Markdown
Owner

What

Adds FORK.md — a single reference for how this fork diverges from upstream and which code paths will rub on each sync — and trims AGENTS.md's "Local fork status" to a pointer.

Why here

AGENTS.md is 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.md is a file upstream doesn't have, so it never produces merge markers.

Contents of FORK.md

  • Divergence at a glance — the 5 local features mapped to origin commits.
  • Conflict-prone code paths — per-feature tables keyed by the actual fork file changes (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 overselling ClineProvider.ts (81 commits, but additive) and underselling reasoning.ts (5 commits, but the semantic keystone).
  • Fork-only files — added files that never conflict textually but need re-wiring if upstream restructures.
  • Recurring/expected conflicts — release mechanics (version, CHANGELOG, READMEs, locales).
  • Post-merge checklist — relocated from AGENTS.md so nothing is lost: pnpm vsix --force rebuild, the 22-failure test baseline, the effort-payload guard.
  • Regenerate this map — the exact commands used to build it.

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 into FORK.md — not dropped. ## Conventions and later sections untouched.

Notes

  • Docs-only; no runtime surface to verify. Sanity-checked that every code path cited in FORK.md exists in the tree.
  • Base is local/daily-driver (this fork's trunk), not main.
  • Known limitation, documented in the file: the map is built from non-merge fork commits, so conflicts already resolved inside past merge commits aren't captured — add a row when a new area starts conflicting.

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.
@zephg
zephg merged commit 92b09c0 into local/daily-driver Jul 11, 2026
5 of 8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant