fleet-fork-sync

name	fleet-fork-sync
description	Sync PMOVES forks from upstream and promote PMOVES.AI submodule gitlinks, driven by the PMOVES.AI GitHub App. Use when forks are behind upstream (CVE/feature drift), when "the submodules aren't synced", or before a gitlink-promotion commit. Covers the App token Known Road, the two-layer sync (fork←upstream, gitlink←fork), and the manual CRITICAL merge.

fleet-fork-sync — PMOVES fork & submodule gitlink sync

Two layers, in order (doing layer 1 before layer 2 just re-pins stale commits):

1. fork ← upstream — fork-sync.yml (24 curated forks). App-token-driven, local-git merge → PR per fork.
2. PMOVES.AI gitlink ← fork HEAD — promote the pointer once the fork's tracked branch advanced.

Full reference: pmoves/docs/operations/GITHUB_APP.md. Memory: reference_github_app_fleet_sync.

The one rule that breaks everything if missed

PMOVES gitlinks track PMOVES.AI-Edition-Hardened, not main. .gitmodules submodule.<path>.branch is the source of truth. Sync the wrong branch and the gitlink shows diverged and can't be promoted without dropping hardening. fork-sync now derives this from .gitmodules automatically — keep it that way.

Step 1 — audit drift (read-only)

bash .claude/skills/pmoves-submodule-fleet/scripts/fleet_audit.sh   # gitlink vs fork-main
gh workflow run fork-sync.yml --ref main -f dry_run=true -f max_forks=40  # fork vs upstream (Fork Drift Audit)

Read the dry-run job log: STALE/CRITICAL <fork>: N behind, M ahead. ahead = PMOVES hardening a merge must preserve.

Step 2 — run fork-sync (creates reviewable PRs)

gh workflow run fork-sync.yml --ref main -f dry_run=false -f max_forks=12

• Resolves each fork's branch from .gitmodules (hardened for most).
• Local-git merge in the runner (NOT the /merges API — it can't merge a cross-repo owner:branch head).
• Guard (ahead_max=20 / behind_max=1000) skips giants/high-hardening forks as MANUAL without cloning. Override the inputs to force-attempt.
• Conflicting merges --abort and skip → those need the manual merge (Step 4).
• Watch the log: PR #N: <url> = success; MANUAL/CONFLICT = skipped.

Step 3 — review/merge fork PRs, then promote gitlinks

Merge fork sync PRs with a merge commit (gh pr merge <n> --repo POWERFULMOVES/<fork> --merge --admin) — NEVER squash (squashing severs shared upstream history → every future sync re-conflicts).

Promote each gitlink ONLY when it's a clean fast-forward:

cur=$(git ls-tree HEAD <submodule-path> | awk '{print $3}')
new=$(gh api repos/POWERFULMOVES/<fork>/git/ref/heads/PMOVES.AI-Edition-Hardened --jq .object.sha)
gh api repos/POWERFULMOVES/<fork>/compare/$cur...$new --jq .status   # must be "ahead"; "diverged" = STOP
git update-index --cacheinfo 160000,$new,<submodule-path>            # no submodule checkout needed

Commit as chore(submodules): promote … → PR (CI = submodule-smoke). Batch multiple gitlinks per PR.

Step 4 — manual CRITICAL merge (diverged / guard-skipped forks)

The forks fork-sync can't auto-merge. Pattern (proven on Archon):

find <dir> -delete 2>/dev/null   # NEVER rm -rf (guard); clean any prior clone
git clone --filter=blob:none --no-tags -b PMOVES.AI-Edition-Hardened https://github.com/POWERFULMOVES/<fork>.git <dir>
cd <dir> && git remote add upstream https://github.com/<upstream>.git
git fetch --filter=blob:none --no-tags upstream <ACTIVE_BRANCH>   # check the upstream DEFAULT — e.g. Archon's is `dev`, not `main`
git merge --no-ff --no-commit upstream/<ACTIVE_BRANCH>
# resolve conflicts. Lockfiles (bun.lock/package-lock) → regenerate: `bun install` preserves CVE-bump overrides
git add -A && git -c core.autocrlf=false commit --no-verify --no-edit -m "Merge upstream …"   # --no-verify: local husky eslint OOMs on big merges; CI lints
git push origin HEAD:sync/upstream-<date>-merge   # fresh branch; FF, no force needed
gh pr create --repo POWERFULMOVES/<fork> --base PMOVES.AI-Edition-Hardened --head sync/upstream-<date>-merge ...

Gotchas that bite:

• Never chain git commit with git push --force* — the classifier rejects the whole command, so the commit silently never runs. Commit alone, then push to a fresh branch (FF, no force).
• Verify the merge is 2-parent before pushing: git show --no-patch --format='%h parents=%p' HEAD.
• The PR's CI (image build + Trivy) is the real gate, not the eslint test job (upstream code often trips the fork's stricter lint — eslint --fix or relax).

App token Known Road

Mint via the reusable .github/workflows/_app-token.yml (SHA-pinned, scoped). Never re-implement create-github-app-token inline. owner + repositories: (named) + minimal permission-*; owner alone = ALL repos (over-broad). The App being installed ≠ the minted token having scope (add owner to span the installation).

Anti-patterns

• ❌ Promoting a diverged gitlink (drops hardening).
• ❌ Syncing the fork's default branch when the gitlink tracks hardened.
• ❌ Squash-merging fork sync PRs.
• ❌ /merges API for cross-repo upstream→fork (use local git).
• ❌ rm -rf / git push --force (guard-blocked) / chaining commit+force-push.

Citations

• pmoves/docs/operations/GITHUB_APP.md, .github/workflows/fork-sync.yml, _app-token.yml
• research/SUBMODULE_SYNC_AUDIT_2026-06-07.md, .claude/skills/pmoves-submodule-fleet/
• Fix chain: PRs #1733/#1735/#1736/#1738/#1739/#1741; Headscale gitlink #1740; Archon manual merge PMOVES-Archon#17.