workflow-ship-change

# Workflow: ship a change A change is **done** only when all of these are true, and the report shows each one: 1. **Screenshots** of the real rendered game: the start state, the key moment and the result. They're shown inline in the report. 2. **Its own changelog version**, with its pictures on the in-game changelog page. 3. **Verified**: - your own tests; - the tests of commits you merged in; - the asset checks; - the full suite, run on the pushed commit. 4. **Committed**: one cohesive commit, with only your own files staged. 5. **Pushed** to `main` as a fast-forward, and confirmed on GitHub. 6. **Live**: the build of that exact `main` is published, and confirmed working on the real domain. 7. **Measured**: the sizes of the commit, the push, any upload and the publish, all measured, never estimated. Pushing and publishing are standing authorizations for the project's own repository and live site. So don't ask before them, **except** where a guardrail below says stop. Read the project's `AGENTS.md` before starting, and this skill's `references/<project>.md` if there is one. Project rules change often, and wherever they differ from this skill, they win. ## Guardrails: stop and ask the user - **Any upload over 50 MB.** That covers a git push, a Netlify deploy, a media release, and files sent to any outside service. - Measure first (`upload-size.sh`, or the pack size `push-main.sh` prints), and state the size when asking. - Count the whole operation, and never split it to get under. - A full Supabase media release (about 861 MiB) always needs asking. - **A force-push**, rewriting remote history, changing repository visibility, or pushing to another repository. - **A new site or project**, or changing a site's access, domain or DNS, unless the task is exactly that and the user asked for it. - **When the permission check blocks** a deploy, rollback or upload: stop. Don't retry it another way or through another thread. Tell the user the exact click path or command. - **Live broken after your publish:** say so first in your report, with the measured evidence and the rollback click path. Don't bury it. ## Guardrails: never - Never publish anything but the clean, pushed `origin/main`. No unmerged branch, no uncommitted file. - Never deploy large media to Netlify as a fallback; media lives in Supabase Storage. - Never publish to a host the project has retired, even if old scripts still point at it. - Never run the broad image optimizer (`pnpm images:optimize`, or `optimize-images.py --apply`). It rewrites other sessions' pending images. Use `runtime-assets.py --only '<your glob>'`, then `--verify`. - Never stage credentials, `.env*`, `node_modules`, caches or build output, and never use `git add -A` in a shared checkout. - Never call a local commit pushed, or a deploy live, until you've confirmed it on the remote or the domain. - Never kill a process you didn't start. Check its working folder first: `lsof -a -p <pid> -d cwd`. ## Steps ### 0. Before you start - Run `git fetch`, then `git log origin/main --oneline -30`, and search for your area. Look in the sibling worktrees (`git -C <wt> diff --stat`) for someone already making the same edit. - Work in your own worktree on a branch off `origin/main`. Other sessions edit the shared checkout live. ### 1. Screenshots - Capture the real game at 1600×900 using the project's review fixtures (`?review=<name>`). Take the start, the key moment and the result. - If the project names a capture tool, use it. Otherwise capture headlessly over CDP (see the `workflow-progress-screenshots` skill), and say which you used. - Look at every picture before using it. Stray toasts, stale numbers, or the wrong scene mean recapture. - Label them honestly: headless browser captures, and a phone-sized viewport is not a device test. - Keep capture scripts in the worktree's gitignored `qa/captures/`; the session scratchpad is wiped on restart. ### 2. Changelog version - Follow the project's changelog rules exactly: format, versioning, and how pictures are added. - Write for players: what they can see or do now, with no file names or hashes. - Changes to tests, tooling, docs or rules get no version. - If another session took your version number, renumber yours on merge, and keep their entries. ### 3. Verify - Run the suites your change touches as you go. - After merging `main`, also run every test file the incoming commits touched: `git diff --name-only <old-base> <new-base> -- tests`. - Run the image verify if images shipped. - The full suite takes 10–40 minutes on a busy machine. Run it with `run_in_background` and read the log. Re-run a timeout-looking failure on its own before calling it real. - Report honestly which runs were full and which were targeted, with pass and fail counts. ### 4. Commit - `git diff --cached` must be empty before you start. - Stage **explicit paths** only. - Run `commit-size.sh` on the staged changes; its numbers go in the report. - One commit per cohesive change. While still iterating, amend a single work-in-progress commit instead of piling up small ones. - Write the message in the repo's style, ending with the attribution line the system gives you. ### 5. Merge and push 1. `git fetch`, then `git rebase origin/main` (or merge, on a shared branch). 2. Resolve conflicts keeping everyone's work. For generated JSON (image audit, manifests), take upstream's file, re-add your own records, and recompute totals with the project's tool. 3. `node --check` every `src` and `tests` file. Then run your tests plus the incoming commits' tests. 4. `push-main.sh`: - it refuses anything that isn't a fast-forward; - it measures the pack and stops over 50 MB; - it pushes with `--progress` and prints git's "Writing objects" line (the bytes sent); - it confirms `origin/main` equals HEAD. If `main` moved, go back to step 1. 5. Run the full suite on the pushed commit, and fix forward if it breaks. ### 6. Publish live - Build in a checkout whose HEAD is exactly `origin/main` and whose tracked files are clean. - If the build changes a tracked file, commit and push that file first, then build again. - Measure what will be uploaded (`upload-size.sh dist`, plus any media release). Over 50 MB, stop and ask. - **Deploy to a draft or preview URL first.** Run `verify-live.sh <draft-url>`: the page, its scripts and art, and the gate route. Promote to production only when it passes. This step exists because a production deploy once went out without its edge function: the site served its page but 404'd every image, and nobody could play. - After promoting, run `verify-live.sh` on the real domain. Record the deploy ID, the publication time, the live game version, and the bytes sent. - If another session published after you, that's fine as long as it also published `main`. ## Report Short, in this order: 1. The commit hash, pushed and confirmed. Commit size: files, total size, largest files. Push size: the bytes sent. 2. Live: URL, deploy ID, time, live version, and the `verify-live.sh` result. Upload size: bytes sent, built-site size, and any media release. If you didn't publish, say why (for example "held: needs a media release over 50 MB; asking"). 3. What changed, for a player, plus the changelog version and title. 4. Tests: which runs were full and which targeted, with pass and fail counts. 5. Screenshots with captions, labelled as headless captures. 6. Anything deferred or departed from, and why.