[WS2] Implement shuvcode-style upstream sync automation

[randomm]

Parent: #158

Objective

Set up automated upstream sync infrastructure modeled on shuvcode's proven 4-layer system, so upstream releases flow into our fork with ≤30% manual intervention.

Architecture (adapted from shuvcode)

Layer 1: Release Watcher

• GitHub Action triggered on upstream release tags (or scheduled polling)
• Detects new upstream versions via GitHub API

Layer 2: Merge Workflow (upstream-sync.yml)

• Fetches upstream tag, resolves to SHA
• Attempts git merge --no-commit --no-ff into integration branch
• Runs auto-resolution rules (see below)
• If clean: commits, runs validation, pushes
• If conflicts: categorizes and triages

Layer 3: Auto-Resolution Rules

Pattern	Resolution
bun.lock	Accept upstream
*.md (docs)	Accept upstream
.gitignore, configs	Accept upstream
Our additive files (rg.ts, task.ts, check_task.ts, async-tasks.ts, tools.ts, tasks.ts)	Preserve ours
Our deleted files (glob.ts, glob.txt, grep.ts, grep.txt)	Ensure deleted
registry.ts	Attempt auto-merge (8 lines)
session/index.ts, session/prompt.ts	Flag for manual review

Layer 4: Failure Handling

• Create GitHub issue with conflict details and categorization
• Include diff context for manual resolution
• Optional: AI agent fallback (like shuvcode's /opencode comment trigger)

Key Files to Create

script/sync/fork-features.json

Manifest tracking our fork-specific features:

{
  "features": [
    {
      "name": "async-task-tool",
      "files": {
        "additive": ["session/async-tasks.ts", "tool/task.ts", "tool/check_task.ts", "session/tools.ts", "util/tasks.ts"],
        "modified": ["session/index.ts", "session/prompt.ts", "tool/registry.ts"]
      },
      "criticalCode": ["AsyncTaskManager", "check_task", "TaskSlot"]
    },
    {
      "name": "rg-tool",
      "files": {
        "additive": ["tool/rg.ts", "tool/rg.txt"],
        "modified": ["tool/registry.ts"],
        "deleted": ["tool/glob.ts", "tool/glob.txt", "tool/grep.ts", "tool/grep.txt"]
      },
      "criticalCode": ["RgTool", "files_only"]
    }
  ]
}

script/sync/fork-features.test.ts

Automated test verifying all criticalCode markers exist in codebase after any merge. Catches silent feature deletions.

.github/workflows/upstream-sync.yml

The main sync workflow.

.github/last-synced-tag

State file tracking last successfully synced upstream version.

Acceptance Criteria

• Workflow triggers on new upstream release tags
• Auto-resolves lockfile, markdown, and additive file conflicts
• Creates detailed issue on unresolvable conflicts
• fork-features.json manifest covers all fork-specific files
• fork-features.test.ts verifies critical markers survive merges
• Validation pipeline (typecheck → test → build) runs after merge
• Integration branch used for staging before dev merge
• Successfully syncs at least one upstream release end-to-end

References

• shuvcode sync system: https://github.com/Latitudes-Dev/shuvcode
• shuvcode fork-features.json: script/sync/ directory
• shuvcode detect-conflicts.ts: conflict categorization logic