Shipping Taskuary

Two separate things, never mixed:

1. A fix reaches the owner when it is on master - the owner's app runs from the main checkout (the owner's own working copy of the repo, not a worktree), so a push + fast-forward + their restart is "shipped" for them.
2. A release reaches PyPI when tools/release.sh X.Y.Z.W finishes. That is the only way to tag.

1. Land a fix (minutes, not hours)

• One fix, one branch, merged to master as soon as its own tests pass: the test files for what it touched, plus npm exec --yes --package=node@22 -- node --test "test/*.test.mjs" (in website/) when website/src changed. Never the full suites locally - CI runs them on parallel machines. Never batch ten branches and integrate at the end: every merge re-runs everything, and a day goes.
• website/src changed -> rebuild the committed UI before pushing (npm run build, plus build:demo; build:docs when docs/site/*.md or the tool catalog changed - CI's build-web job rejects a stale site/docs).
• Push, then fast-forward the owner's checkout: git -C <main> merge --ff-only origin/master (only when it is clean). Tell them: restart Taskuary (Python changed) or refresh (UI only).
• Red CI on master -> fix forward on master at once. tools/ci-failures.sh <run-id|sha> names the failing tests.
• Agents in parallel: few, on disjoint files, targeted tests only. Five agents each running full suites on one machine made every run slow and every timing test flaky.

2. Release (one command)

From a clean, up-to-date checkout of master:

tools/release.sh 0.3.9.54

It bumps the seven version places (pyproject, both READMEs + their badge asof=, roadmap, docs manifest, the demo's three fixture fields), builds UI/demo/docs, runs the fast gates (node unit, eslint no-undef, version/docs/catalog/timewords pytest), commits, pushes, waits for ci.yml on that exact commit, tags only when green, waits for publish.yml (reruns once - the exe's signing download flakes), verifies PyPI + the GitHub release with TaskuarySetup.exe, and fast-forwards the main checkout. A clean release is ~20 min: build + gates ~3, CI ~12 (tests run in 3 parts per OS), publish ~7 (the signed exe is the long leg).

Red CI is not a restart (the owner, 2026-11-09: "20 minute release max .. rerun just that test, everything else that passed is good"). On a red run it prints the failed tests and stops - no whole-job rerun. Then:

1. Decide per test: is the test wrong (timing, a stale expectation) or the code? Fix that, commit (no push needed).
2. tools/release.sh X.Y.Z.W --after <run-id> --fixed - pushes the fix, dispatches ci-targeted.yml on the fix commit with exactly the failed tests plus the test module of every file the fix touched (Windows + macOS, ~4 min), and tags that commit when it is green - without waiting for the full ci.yml, which still runs on master. publish.yml's gate accepts a green targeted run on the tagged commit. A flake with nothing to fix: the same command with no new commit.
3. Red again -> it prints the targeted run's failures and the next --after <that run> --fixed command.

--after <run-id> alone lists what would rerun; --dry-run also prints the exact dispatch without pushing anything. A docker failure (or any job that is not tests/build-web/smoke) cannot be vouched for this way - fix it and use the full road.

Two duties, never traded against each other (the owner, 2026-11-10: "i want it released fully as long as tests pass and you just rerun the failure one. But then after release rerun ci since it's fixed and get it green.. don't hold up releases but make sure it's green. 2 things.."):

1. Release at once. A red run is fixed and released on the targeted road above - never held for a full run, never restarted.
2. Then get master green. After the release is out, the full ci.yml on master's head must end green on GitHub. The script's last step waits for it and says master is GREEN or GREEN IS STILL OWED with the failing tests. If it is owed: fix forward on master (test or code), push once, gh run rerun <run-id> --failed, and stay on it until the head is green. Land follow-up work in few pushes - a pile of small pushes leaves cancelled runs, which GitHub shows as not green.

The turn that ran a release is not finished until both are true: the version is on PyPI, and master's head is green.

Run it in the background and report when it ends; do not babysit runs by hand.

Its last step prints the Advisor agreement (lit button vs what the owner did, read-only on ~/.taskuary) - report it with the release; tools/advisor_agreement.py --replay breaks it down.

Rules that each cost hours on 2026-10-27

• Never cancel a run by looking it up by commit (gh run list --commit X ... | cancel) right after a push: it cancelled the run that mattered. Cancel only by a run id you read for that exact sha - or don't cancel; let stale runs finish.
• A browser job that runs past its time limit shows as CANCELLED, not failed. Keep each part well under its limit: CI runs browser/shard.mjs <part> 6 with 20 minutes each; a new browser test file goes in website/package.json test:browser, and if a part creeps past ~14 minutes, add parts.
• Request-count and timing tests must count what they mean on a slow machine: wait for the state, never for a fixed sleep; CI's macOS gets 1.25x time budgets (CI + darwin), local stays strict.
• Merging branches by hand: never git checkout --ours <file> on a conflicted file - it drops the other side's clean hunks too (lost three overnight fixes once). Resolve the conflicted hunks only; website/package.json's test:browser is the union.
• Version numbers on PyPI can never be reused. The publish workflow gates on CI (ci-green), so a red commit never uploads; tools/release.sh refuses a number already tagged.
• Never commit the owner's data (CLAUDE.md). Commit messages and test names use the stand-ins.
• Release notes go in the tag message and the GitHub release; the README badge updates through its asof= cache-buster.