Cyclotron

Editorial intelligence for publications.

Contents

Working on Cyclotron: the procedures

Four procedures we kept re-typing. Each is a script or a short recipe so the knowledge does not live in one person's head.

1. Merge and release

Work on a branch off origin/develop; merge to develop when green; promote develop to main with scripts/dev/release_to_main.sh (add --dry-run to check without pushing). It builds a throwaway worktree, fast-forwards to origin/main, merges origin/develop, runs make check and pushes without force, waits for the release commit semantic-release adds to main, then merges main back into develop so develop reports the released version. It never touches your checkout.

make test is the fast loop: it runs pytest -m "not slow", which skips the long replay, study and editorial-corpus tests marked @pytest.mark.slow (or a module-level pytestmark). make test-all runs the whole suite. Mark a new test slow when it takes more than a few seconds; pytest --durations=30 shows which.

make check is the gate, because CI for this private repository runs locally and .github/workflows/release.yml is kept only for the semantic-release job. It runs, in order: make test-all (the slow tests included); npm ci, npm test and npm run build in trace-ui; then git diff --exit-code on src/decision_flywheel/vendor/trace-ui, which fails when the committed bundle differs from a fresh build. If it fails on the bundle, commit the rebuilt files. Ruff joins the front of the sequence once the lint setup lands.

2. Temporary worktrees

scripts/dev/worktree.sh new NAME [BASE] creates CW_WORK/NAME (default /private/tmp/cw-work). scripts/dev/worktree.sh clean removes only worktrees whose branch is merged into origin/develop and which have no uncommitted changes. Do not delete worktree folders with a wildcard: other tools write next to them, and a full disk stops every tool, including rm. Keep more than 5 GB free. Worktrees with node_modules are the usual cause.

3. Launching a paid run

Use the replicate harness even for one run, because it enforces global caps:

scripts/replicate_study.py --base-args-file ARGS.txt --out-dir DIR \
  --replicates N --parallel 2 --max-total-optimizer-calls CAP --max-total-decision-calls CAP

ARGS.txt holds the study's own arguments without --output and --seed (see docs/replicates.md). Rules: Jev for decisions and gpt-6-luna for the optimizer unless the owner approves otherwise; set per-run caps in the args and global caps on the harness; export keys in the same shell command that launches it and never print them (read them from the owner's .env); use bash, not zsh, if you build argument arrays; watch global_budget_ledger.json in each run folder and kill the run at the cap; report the cost afterwards (Jev about 0.00005 USD per call; gpt-6-luna 0.10 USD per million input tokens and 0.50 per million output, doubled above 272,000 input tokens in one request).

4. Recording a run for the website

scripts/recordings.py add RUN_DIR --id ID --title T --summary S --notice N --tag TAG \
  --corpus-manifest M --corpus C --cycles 280 --window-size 70 \
  --optimizer-price gpt-6-luna --decision-model-price jev --catalog DIR
scripts/recordings.py publish ID [--featured]
scripts/recordings.py export-published --catalog DIR --to SITE/components/recordings

Then in the site repo run npm run recordings:sync, npm test, and look at the pages (scripts/dev/page-shots.mjs). Publish only runs that explain something; read docs/recordings.md. Keep the raw run folders: they are the evidence behind the recording.

Kanbus in cloud sessions

.claude/settings.json runs scripts/dev/ensure_kanbus.sh at session start. When kbs is missing it installs the kanbus version pinned in the tools extra of pyproject.toml into a dedicated venv (~/.cache/cyclotron/kanbus-venv, override with KANBUS_VENV) and symlinks kbs into ~/.local/bin (override with KANBUS_BIN_DIR); a venv avoids pip failing on distro-owned packages such as Debian's PyYAML. An existing kbs is left alone, with a warning if its version differs from the pin. If that directory is not on PATH, the script appends one export PATH=... line to $CLAUDE_ENV_FILE so the session's later Bash commands find kbs (without CLAUDE_ENV_FILE it prints a hint to stderr instead). The hook discards stdout but keeps stderr, so failures are visible. Use kbs commands for the board; never edit project/issues or project/events by hand.