hamtab-sync-branches

name	hamtab-sync-branches
description	Sync HamTabV1 deployment branches — merge `main` into `lanmode` and `hostedmode` with the mandatory pre-merge divergence check and post-merge validation. Use when the user says "sync branches", after committing shared code changes to `main`, or before a release. NOT for docs-only changes.

HamTab — Sync Branches

Deploys shared main code to the two deployment branches. This skill executes the procedure in CLAUDE.md §Branch Sync Protocol, encoded so the validation can't be skipped — a skipped post-merge check caused a 2-hour production outage (RCA 2026-02-06: a duplicated server.js section → SyntaxError → container down).

Source of truth & alignment

• CLAUDE.md §Branch Sync Protocol is authoritative. Branch strategy is a project-CLAUDE.md concern (instructions.md hierarchy). If CLAUDE.md and these steps ever disagree, follow CLAUDE.md and update this skill — do not let this file drift into a third copy. The generic cross-org loop in ai-workflows/reference/governance-decisions.md §Branch Sync Bash Script is the baseline; HamTabV1's protocol is the richer superset (it adds the divergence + validation checks) and wins for this repo.
• aiw does not cover branch sync. Per instructions.md ("use aiw for all operations it supports; fall back to Bash for … branch sync"), raw git here is correct — do not invent an aiw call for the merge/push. Normal coordination (aiw work release …, session end) is separate and unchanged by this skill.
• Global hard rules still apply (~/.claude/instructions.md):
  • Pre-commit branch check — run git branch --show-current before any commit you make while fixing a failed validation; commit to the branch you're fixing, never main by accident.
  • Never --no-verify / --no-gpg-sign — pre-commit hooks are load-bearing; fix the cause.
  • Never git reset --hard to undo a wrong-branch commit — use git branch <x> && git reset --soft HEAD~1, git stash, or git cherry-pick. Check git status for files you didn't touch first.

Preconditions

• You are in ~/code/stevencheist/HamTabV1.
• Work is committed on main. (Run git status first; stash or commit anything pending.)
• This is code, not docs-only. Docs-only changes (CLAUDE.md, ROADMAP.md, README.md) do NOT get synced — return early and tell the user.

Hard rules

• Never push a deployment branch if any validation fails. Fix on the branch, re-validate, then push.
• Never edit shared files on a deployment branch. If the divergence check flags shared-file edits on lanmode/hostedmode, STOP and resolve per CLAUDE.md (cherry-pick to main first).
• Deployment branches are remote-primary — always git pull origin <branch> before merging.

Procedure

1. Publish main

git checkout main
git pull origin main --no-edit
git push origin main
git fetch --all

2. For each deployment branch (lanmode, then hostedmode)

git checkout <branch>
git pull origin <branch>

2a. Pre-merge divergence check — has the deployment branch modified shared files?

git diff main...HEAD --name-only \
  | grep -E '^(src/|server|public/(index\.html|style\.css)|esbuild)' \
  | grep -v 'src/update\.js\|src/settings-sync\.js'

If this prints anything: STOP. A shared file was edited on the wrong branch. Resolve per CLAUDE.md §Pre-merge divergence check (usually: redo the change on main, then merge). Do not proceed.

2b. Merge

git merge main -m "Merge main into <branch>"

2c. Post-merge validation — run the bundled script (it must exit 0):

bash .claude/skills/hamtab-sync-branches/validate.sh <branch>

It checks: node -c server.js (syntax), duplicate // --- section headers, and (on hostedmode) that @cloudflare/containers survived the merge and every root *.js is in the Dockerfile COPY list.

If validation fails → fix on the branch, re-run validate.sh, only then continue.

2d. Push (only if validation passed)

git push origin <branch>

On hostedmode, before pushing: if new user-facing features landed, run the SEO Update Checklist (sitemap lastmod, JSON-LD featureList, <noscript>), per CLAUDE.md §SEO.

3. Return to main

git checkout main
git pull origin main

Report back

Tell the user, per branch: merged ✅, validation result, pushed ✅ (or blocked + why). Remind them hostedmode auto-deploys to production on push.