Proposal: Sustainable Upstream Sync Strategy

[androidand]

Proposal

Context

This fork of OpenCode tracks an upstream repository on the dev branch. The current sync process (script/sync-upstream.ts + FORK_WORKFLOW.md) creates a worktree and merges upstream into it, but leaves much of the validation and custom-change preservation to manual effort. As the fork accumulates local features (Skein integration, beads, llama-swap patches, llama-skein), each sync becomes more error-prone and time-consuming.

Why

Without a structured, repeatable sync strategy:

• Custom changes (token cache_write, SSE usage injection, HTTP/1.1 upstream) are at risk of being lost during merges
• Validation is manual and incomplete — typechecks, builds, and smoke tests happen ad hoc
• The Skein dependency chain (upstream → fork → tagged snapshot → skein port) has no automation to enforce tagging discipline
• Conflict resolution is unguided — no tooling identifies which files will likely conflict

What

A comprehensive, automatable upstream sync strategy that includes:

1. Enhanced sync script — extends script/sync-upstream.ts with conflict detection, pre-merge analysis, and post-merge validation hooks
2. Custom change preservation guide — documents each custom change with exact file locations, diff context, and re-application steps
3. Validation checklist — automated checks for typecheck, build, and smoke test in the sync worktree
4. Tagging discipline — enforces the upstream → fork → tagged snapshot → skein port dependency chain
5. Updated FORK_WORKFLOW.md — consolidates all sync procedures into a single authoritative reference

Scope

• In scope:

  • Enhance script/sync-upstream.ts with conflict analysis and validation hooks
  • Expand FORK_WORKFLOW.md with full custom-change catalog and re-application procedures
  • Add a validation script (script/sync-validate.ts) for the sync worktree
  • Document the Skein port chain enforcement procedure
  • Add a GitHub Action or pre-commit hook for sync readiness checks

• Out of scope:

  • Merging specific upstream commits (that is an operational use of this strategy)
  • Changes to Skein, beads, llama-swap, or llama-skein repositories themselves
  • Automating the actual conflict resolution (we document the process, not auto-fix)

Risks

• Scope creep — mitigated by keeping tasks focused on documentation and lightweight tooling
• Script complexity — the sync script could become fragile; mitigated by keeping it simple and well-tested
• Stale custom-change docs — mitigated by including custom-change docs as part of the sync validation checklist

Disposition (2026-09-18)

Archived — superseded/obsolete. Superseded by fork/manifest.json + script/fork-verify.ts + script/sync-check.ts + FORK_WORKFLOW.md.

Tasks

Phase 1 — Custom Change Catalog

• Catalog every custom change in FORK_WORKFLOW.md — for each, record: source file, purpose, upstream commit hash where divergence began, and current diff context. Add to docs/UPSTREAM_SYNC.md under a "Custom Change Catalog" section. Validation: grep -c "^###" docs/UPSTREAM_SYNC.md ≥ 4

• Document token cache_write patch — record exact file (src/config/config.ts or wherever it lives), the upstream line range, the local modification, and the re-application steps. Add to docs/UPSTREAM_SYNC.md as a subsection with a git apply-able patch block. Validation: grep -q "cache_write" docs/UPSTREAM_SYNC.md

• Document SSE usage injection patch — record the file, purpose, and re-application procedure. Validation: grep -q "SSE" docs/UPSTREAM_SYNC.md

• Document HTTP/1.1 upstream patch — record the file, purpose, and re-application procedure. Validation: grep -q "HTTP/1.1" docs/UPSTREAM_SYNC.md

• Document llama-skein mDNS service registration — record the service name, port, and how the fork's src/local/mdns.ts discovers it. Validation: grep -q "mdns" docs/UPSTREAM_SYNC.md

Phase 2 — Enhanced Sync Script

• Add conflict-preanalysis to script/sync-upstream.ts — before the merge, run git diff --name-only upstream/dev...HEAD against the last known sync point to identify files that have diverged; log them as "likely conflict files". Validation: bun script/sync-upstream.ts --dry-run exits 0 and prints "likely conflict files"

• Add --validate flag to script/sync-upstream.ts — after merge, run typecheck, build, and smoke-test in the worktree; exit non-zero on failure. Validation: bun script/sync-upstream.ts --validate --dry-run exits 0

• Add custom-change re-application hooks — after merge, the script detects which custom changes are still needed and applies them in order, logging each as "re-applied" or "already present". Validation: bun script/sync-upstream.ts --dry-run --apply-customs prints re-application status for each cataloged change

• Add post-sync summary — output a markdown summary of what changed: upstream commits merged, custom changes re-applied, validation results, remaining conflicts. Validation: bun script/sync-upstream.ts --dry-run outputs a "--- Sync Summary ---" block

Phase 3 — Validation Script

• Create script/sync-validate.ts — standalone script that runs the full validation suite: bun typecheck, bun run build, and a smoke test (e.g., opencode run --help exits 0). Accepts a --worktree flag pointing to the sync worktree. Validation: bun script/sync-validate.ts --worktree . exits 0

• Add build check to validation — ensure bun run build succeeds in the worktree. Validation: bun script/sync-validate.ts --worktree . --check build exits 0

• Add smoke test to validation — run opencode run --help and verify exit code 0 and output contains "Usage". Validation: bun script/sync-validate.ts --worktree . --check smoke exits 0

Phase 4 — Tagging Discipline

• Document the upstream → fork → tagged snapshot → skein port chain in docs/UPSTREAM_SYNC.md with a diagram and step-by-step procedure. Validation: grep -q "tagged snapshot" docs/UPSTREAM_SYNC.md

• Add script/tag-upstream.sh — helper that creates a semver-tagged snapshot of the fork at the current upstream merge point, prints the tag name, and logs it. Validation: bash script/tag-upstream.sh creates a tag and prints it

• Document skein port update procedure — steps to update skein's dependency on the fork to point to the new tagged snapshot. Validation: grep -q "skein" docs/UPSTREAM_SYNC.md

Phase 5 — Automation & CI

• Add GitHub Action for sync readiness — ./.github/workflows/sync-readiness.yml that runs script/sync-validate.ts on every PR to dev. Validation: cat .github/workflows/sync-readiness.yml | grep -q "sync-validate"

• Add pre-commit hook for sync readiness — ./script/pre-commit-sync that runs a lightweight check (typecheck + build) before commits to dev. Validation: test -x ./script/pre-commit-sync

• Document when to use the GitHub Action vs. pre-commit hook in docs/UPSTREAM_SYNC.md. Validation: grep -q "pre-commit" docs/UPSTREAM_SYNC.md

Phase 6 — Consolidation

• Rewrite FORK_WORKFLOW.md — consolidate all sync procedures into a single authoritative reference, cross-referencing docs/UPSTREAM_SYNC.md for the custom change catalog. Validation: cat FORK_WORKFLOW.md | grep -q "UPSTREAM_SYNC.md"

• Create docs/UPSTREAM_SYNC.md — the master document containing: custom change catalog, sync procedure, validation checklist, tagging discipline, and Skein port update steps. Validation: wc -l docs/UPSTREAM_SYNC.md ≥ 50

• Add a CHANGELOG entry for the sync strategy changes. Validation: grep -q "sync" CHANGELOG.md || grep -q "Sync" CHANGELOG.md

Unchecked items above: see Disposition in proposal.md (2026-09-18).

[androidand]

Archived 2026-09-18 — see the change's Disposition section.