# Update from upstream without losing local patches

Audience: AI coding agents first.

## Outcome

Update FreeTube to latest `origin/development`. Preserve all owner app-code patches, including committed fixes and current uncommitted refresh-time work. Keep unrelated local tooling directories in shared checkout untouched.

## Status

`ACTIVE` — worker: main session in `.worktrees/update-upstream`.

## Task IDs

- `UPSTREAM-1`: Capture source state and preserved WIP.
- `UPSTREAM-2`: Replay local commits on latest upstream.
- `UPSTREAM-3`: Apply uncommitted app-code patch.
- `UPSTREAM-4`: Resolve conflicts without dropping owner behavior.
- `UPSTREAM-5`: Test and inspect resulting patch.
- `UPSTREAM-6`: Install result into shared checkout, verify, commit locally.

## Source request

Owner: “get lates version from git while preserving my changes in the code, since i patched this app a few times and it did not make it to the original repo”

## Acceptance criteria

- Shared checkout reaches latest fetched `origin/development` ancestry.
- Commits `fc6ed92e8`, `0e4c33713`, and `d6e63d83c` remain represented.
- Current tracked app-code modifications and untracked `src/renderer/helpers/relativeRefreshTime.mjs` plus `test/relative-refresh-time.test.mjs` remain represented.
- Existing `.claude/` and `.slopgate/` content remains untouched.
- Relevant tests pass cleanly.
- Final local branch contains a recoverable commit history; nothing is pushed.

## Preserved WIP / ref / path

- Source branch: `development`, previously `ahead 3` of old `origin/development`.
- Latest fetched ref: `origin/development` at `86401956a`.
- Isolated path: `/home/user/Projects/FreeTubeApp/.worktrees/update-upstream`.
- Local commits, oldest first: `fc6ed92e8`, `0e4c33713`, `d6e63d83c`.
- Uncommitted tracked files: refresh widget, subscription feed tabs, Popular, Trending.
- Uncommitted app files: `src/renderer/helpers/relativeRefreshTime.mjs`, `test/relative-refresh-time.test.mjs`.
- Unrelated untracked paths: `.claude/`, `.slopgate/`; MUST NOT copy, remove, or overwrite.

## Constraints

- NEVER discard shared-checkout edits.
- Work only in claimed worktree until installation.
- Preserve behavior, not merely patch application.
- Resolve every test/build warning or justify it explicitly.
- Do not push.

## Execution steps

1. Export committed and uncommitted owner changes from source without mutating source.
2. Cherry-pick local commits in chronological order onto latest `origin/development`.
3. Apply uncommitted app patch, including required untracked source/test files.
4. Resolve each conflict by comparing upstream behavior and owner patch intent.
5. Run targeted tests, then project-required validation.
6. Replace shared branch safely only after preserving its WIP and proving the integrated result.
7. Verify shared checkout and create local commit for remaining WIP.

## Current receipt

- Fetched `origin/development`: advanced from `124faed3f` to `86401956a`.
- Claimed `.worktrees/update-upstream` from latest upstream.
- Recorded three local commits and current app-code WIP.
- No source files changed or lost.

## Next executable action

Export source app-code WIP, then cherry-pick the three local commits onto the isolated latest-upstream branch.