Self-contained runbook. Also stored at ~/Documents/_Repo-System-Proposal-2026-06-14/AGENT-INSTRUCTIONS-fix-repos.md. Referenced by the repo-hygiene skill. Hand to any coding agent (Claude Code, Codex, etc.). Run on the machine via Desktop Commander/terminal, NOT the Cowork sandbox.

Context

• Repos under ~/Documents/Projects/Repos/sail-*; ~/Documents/Projects/ = repo sail-projects-root (gitignores Repos/*); ~/Documents/ is not a repo. GitHub org samaguiar1982-cpu.
• KEY FACT: every leaf's LOCAL main is behind origin/main (−9 to −19) because other agents push to origin. Origin is source of truth. Do NOT merge stale local agent branches into stale local main and push blindly.
• Other agents (Codex, superpowers) hold worktrees + scheduled tasks here. Do not break them.
• Backups in ~/Documents/Codex/migration-backup-2026-06-14/ (15 bundles + .git copies of litify/seo/marketing + templates tar; removed collision refs logged in *-removed-refs.txt).

Multi-device reality (ROOT CAUSE)

The ' 2' collision refs, duplicate ... 2/... 3 folders, and stale index.lock files are the signature of a file-sync service (iCloud/Dropbox/OneDrive) replicating .git across devices, which corrupts repos. Non-negotiables: (1) GitHub origin is the ONLY cross-device channel — never sync .git via file-sync; (2) get the repo tree OUT of any synced path (Step 7); (3) per-device: git fetch + git pull --ff-only at session start, push when done; (4) run the migration on ONE device with others idle and repo-touching scheduled tasks paused.

Hard rules

1. Never run git from Repos/ or any non-repo folder; verify git rev-parse --show-toplevel ends in /Repos/<repo> (if it resolves to .../Projects, STOP).
2. Back up .git before mutating: cp -R .git $HOME/Documents/Codex/repo-backups/$(date +%F)/<repo>.git.copy.
3. Direct push to origin is ALLOWED but safely: git fetch first; plain git push (or --force-with-lease, NEVER plain --force). If rejected non-fast-forward, git pull --rebase origin main, resolve, retest, push. Never overwrite origin.
4. Branches matching *cred*/*redact*/*credential*/*leaked* are SECURITY branches — do not merge/push without Sam's explicit OK.
5. Large-repo checkout/merge are slow (2-3 min) but complete — run in background (nohup), poll, don't kill early.
6. export GIT_OPTIONAL_LOCKS=0 and pass -c core.fsmonitor=false to checkout/merge.

Step 1 — clear chronic blockers in every leaf

Delete stale *.lock, delete ' 2' collision refs (log first), remove gc.log, kill stray fsmonitor daemons.

Step 2 — reconcile each leaf AGAINST ORIGIN

Per repo: backup .git; git fetch origin --prune; commit any uncommitted work; count commits not on origin/main; git checkout -B main origin/main (origin wins); cherry-pick only unmerged work; safe-push (fetch again, push, rebase+push if rejected); delete stale parked branch after work is pushed. Do sail-infrastructure, sail-marketing, sail-seo, sail-templates first. Note: sail-infrastructure has a prior local-only merge (3 ahead/9 behind) — reset to origin/main.

Step 3 — sail-litify (huge + 22 worktrees)