feat(workflows): reusable sync-main-to-edge workflow

[alex-nsheaps]

Summary

Adds a reusable workflow at .github/workflows/sync-main-to-edge.yaml that consumer repos can call to keep one or more */edge branches in sync with their default branch (typically main).

• Reads a .gitupstream YAML config from the caller repo (schema below)
• Builds a job matrix from sync[*].targets
• Calls aormsby/Fork-Sync-With-Upstream-action@v3.4.3 (SHA-pinned 83d78e8c4bf524e79b091cf257deba4dee9e60df) once per target
• Gracefully skips targets that don't yet exist on the remote (so repos without an edge branch yet stay green)

.gitupstream schema (YAML, repo root)

version: 1
sync:
  - upstream: main
    targets:
      - alex/edge

Action chosen — why aormsby/Fork-Sync-With-Upstream-action

Candidate	Stars	Last push	Archived	Verdict
aormsby/Fork-Sync-With-Upstream-action	316	2026-04	no	✅ chosen
tgymnich/fork-sync	464	2024-09	no	fork-centric
repo-sync/pull-request	349	2023-06	yes	archived
dabreadman/sync-upstream-repo	47	2024-02	no	low signal
wei/git-sync	266	2022-10	no	force-push only, 3yr stale

Full research: alex repo .claude/tmp/edge-sync-action-research.md.

aormsby's README explicitly states "It should work to keep any two branches in sync" — same-repo branch-to-branch is a first-class use case. We point upstream_sync_repo at ${{ github.repository }} so the action operates inside one repo.

Action pinning

All uses: are SHA-pinned per Henry's P2 rule:

• actions/checkout → de0fac2e4500dabe0009e67214ff5f5447ce83dd (v6)
• aormsby/Fork-Sync-With-Upstream-action → 83d78e8c4bf524e79b091cf257deba4dee9e60df (v3.4.3)

yq is installed by curl from the v4.53.2 release for matrix-building.

Test plan

• Reusable workflow CI green on this PR (lint/format only — runtime tested on consumer PRs)
• Consumer PR in nsheaps/agents exercises the workflow against the existing alex/edge branch
• Consumer PR in nsheaps/.ai-agent-alex exercises the skip-missing-target path

Open Questions

1. Should the reusable workflow also support a prune mode that deletes edge branches no longer listed in .gitupstream? Not in scope here — flag for follow-up if you want it.
2. The aormsby action uses GITHUB_TOKEN for push. On repos where main → edge push is blocked by branch protection on edge, the sync will fail. Do we want protection on edge branches? Current assumption: edge is unprotected so the auto-sync just works.
3. Do you want workflow_call only (current design), or also workflow_dispatch for manual one-off runs? Easy to add — say the word.

Refs nsheaps/.ai-agent-alex#685.

🤖 Generated with Claude Code

Decisions (Q1/Q2/Q3 follow-up 2026-05-28)

Nate answered the original Open Questions (Discord msg):

• Q1 (ref pinning): Keep uses: ...@main for the reusable.
• Q2 (placeholder .gitupstream): Seed each agent repo with <agent>/edge target + create the branch. Done in this PR set; alex/edge, jack/edge, henry/edge now exist on their respective repos.
• Q3 (triggers): All three — push: branches:[main], schedule: '0 6 * * *' (nightly UTC), workflow_dispatch:.

Full follow-up: https://github.com/nsheaps/.ai-agent-alex/blob/main/docs/journal/2026/05/28/edge-sync-q2q3-followup.md