Port 938 upstream t3code commits into the Supaterm fork with per-commit triage and parallel worktrees

I can't execute this workflow for you — I don't have access to your repository, your fork, the upstream remote, or the ability to run git, build tools, or a dev server. What I can do is give you a concrete, runnable playbook that implements each of your nine steps, with the exact commands and decision rules, so you (or an agent with repo access) can execute it.

---

## 0. Setup

```bash
git remote add upstream https://github.com/<org>/<repo>.git
git fetch upstream --tags
git fetch origin --tags
UPSTREAM_HEAD=$(git rev-parse upstream/main)
echo "upstream HEAD: $UPSTREAM_HEAD"
```

## 1. Find the last synced upstream commit

```bash
# Merge history: look for merge commits that brought upstream in
git log --merges --oneline origin/main | grep -i upstream

# Reverted port PRs: search for reverts of upstream SHAs
git log --oneline --grep='Revert' origin/main | head -50
git log --oneline --grep='Upstream:' origin/main | head -50

# Best signal: the newest commit on origin/main that carries an Upstream: trailer
LAST_SYNCED=$(git log origin/main --grep='^Upstream: ' --format='%b' \
  | grep -oE 'Upstream: [0-9a-f]{7,40}' | awk '{print $2}' \
  | while read s; do git merge-base --is-ancestor "$s" upstream/main && echo "$s"; done \
  | tail -1)
echo "last synced: $LAST_SYNCED"

# Enumerate the gap
git log --reverse --oneline "$LAST_SYNCED"..upstream/main > /tmp/upstream-gap.txt
wc -l /tmp/upstream-gap.txt
```

Cross-check against `git log --merges` and any reverted port PRs — if a revert exists, the effective sync point is the commit *before* the reverted batch, not the revert itself.

## 2. Triage ledger (write inside the repo)

Create `docs/upstream-port/ledger.md` (or wherever the repo keeps docs) with one row per commit:

```markdown
| # | Upstream SHA | Subject | Class | Reason |
|---|--------------|---------|-------|--------|
| 1 | abc1234 | fix: null check in parser | Bring | Pure bugfix, no fork divergence |
| 2 | def5678 | feat: new auth provider | Adapt | Touches files the fork renamed |
| 3 | 9012abc | chore: bump eslint | Skip | Fork pins a different eslint major |
| 4 | 3456def | refactor: split router | Decide | Overlaps fork's own router rewrite — needs owner call |
```

Classification rules:
- **Bring** — applies cleanly, no fork divergence in touched files.
- **Adapt** — real change, but files/paths/APIs were renamed or restructured in the fork.
- **Skip** — superseded by fork work, or irrelevant (e.g. CI for a platform the fork dropped).
- **Decide** — genuine conflict of intent; needs a human call before porting.

Commit the ledger before touching code so the decisions are reviewable in the PR.

## 3. Cherry-pick from a renamed upstream copy

```bash
# Build a renamed mirror of upstream so conflicts only appear where the fork really diverged
git checkout -b upstream-renamed upstream/main
# Apply the fork's rename mapping (script it — sed over paths, package names, imports)
./scripts/apply-fork-renames.sh
git commit -am "chore: apply fork rename mapping to upstream mirror"

# Then cherry-pick in upstream order onto a port branch
git checkout -b port/upstream-sync origin/main
while read sha _; do
  git cherry-pick -x "$sha" || {
    echo "CONFLICT on $sha — resolve toward fork behavior, then:"
    echo "  git add -A && git cherry-pick --continue"
    break
  }
  # Ensure the trailer is present
  git commit --amend --no-edit -m "$(git log -1 --format=%B)

Upstream: $sha"
done < /tmp/upstream-gap.txt
```

Rules:
- Resolve every conflict **toward the fork's behavior** — the fork is the source of truth for divergent code.
- Keep upstream authorship (`git cherry-pick` preserves it; `-x` adds the `(cherry picked from …)` line — keep both that and your `Upstream: <sha>` trailer).
- Fork-only fixes go in separate `fix:` / `refactor:` commits, never folded into a port commit.

## 4. Preserve fork features explicitly

Before starting, write `docs/upstream-port/fork-features.md`:

```markdown
- [ ] Feature A: <files, entry points, tests>
- [ ] Feature B: ...
```

After the port, for each item run its tests and a manual smoke check. Any regression is a port bug — fix it in a `fix:` commit, not by reverting the port.

## 5. Second pass over Skip / partial rows

```bash
# Parallel worktrees, one slice per reviewer
for slice in auth router ui cli; do
  git worktree add ../wt-$slice port/upstream-sync
done
```

In each worktree, re-read every `Skip` and every `Adapt` row and confirm the upstream intent is either present or genuinely superseded. Merge findings back as `fix:` commits on `port/upstream-sync`. Update the ledger with a `Verified` column.

## 6. Changed-files check every 40–80 commits

```bash
# After each batch
pnpm -w format:check
pnpm -w lint
pnpm -w knip
pnpm -w -r typecheck
# tests beside changed files
git diff --name-only "$BATCH_START"..HEAD | grep -E '\.(test|spec)\.' | xargs pnpm test --
```

On regression: `git bisect start HEAD "$BATCH_START"` → `git bisect run <check>` → fix the cause in a `fix:` commit.

## 7. Native builds + dev server smoke

```bash
# Android debug
cd apps/mobile && npx expo run:android --variant debug
# iOS simulator Debug
npx expo run:ios --configuration Debug --simulator "iPhone 15"

# Dev server against isolated state
export DATA_DIR=$(mktemp -d)
pnpm dev 2>&1 | tee /tmp/dev.log
```

Exercise: main shortcuts, search, an approval flow, settings. Then `grep -iE 'error|warn' /tmp/dev.log` and confirm clean.

## 8. Independent review

Run a separate reviewer (human or agent) against `port/upstream-sync` for bugs, security, code quality. For every behavioral fix, add a test that fails on the pre-fix commit:

```bash
git stash && pnpm test -- <new-test>   # must fail
git stash pop && pnpm test -- <new-test>  # must pass
```

## 9. Report

Produce `docs/upstream-port/report.md` with:
- **Manual device checks still needed** — anything the simulator/emulator can't cover (push notifications, deep links on real hardware, biometrics, background sync).
- **User-visible behavior changes** — DB migrations, native dependency bumps, auth flow changes, link/deep-link handling changes, config/env var changes.

---

If you paste the output of step 1 (`git log --reverse --oneline $LAST_SYNCED..upstream/main`) and the fork's rename mapping, I can help you draft the actual ledger rows and flag which commits are likely `Decide`.