currentai-org/os-ai-map/migrate-axis

Migrate an axis

Thin wrapper over a deliberately low-freedom workflow. This file does not restate the checklist; it enforces the posture.

Trigger

The change is to what an axis records or means, corpus-wide — not one product's value (update-product) and not one category's weights or ladder (edit-category / build-rubric).

Required reading

Read `docs/workflows/migrate-axis.md` and follow the ten-step impact checklist in order. It covers the contract, the schema, the migration script, the checkers, serialization, the warehouse and front-end contracts, the docs, the before/after distribution, and the removal rule for the old shape.

The rule this skill enforces

A migration requires a deterministic migration script and prohibits ad-hoc hand edits across the corpus. If you find yourself editing product files one at a time, stop — that is what this workflow exists to prevent. The bulk YAML diff is the script's output; reviewers check the script and the distributions, not hundreds of files. Use build/components.py's block-safe helpers, never a yaml.load/dump round-trip.

Scripts to run

uv run python -m build.preflight --skip-tests   # every CI validate gate, ~70s
uv run python -m build.preflight                # the same plus pytest, before you push

build.preflight runs what .github/workflows/validate.yml runs and accounts for every step it cannot run locally, so it does not drift the way a copied gate list does. Do not hand-assemble a subset — that is what shipped a check_components failure to CI once already.

The individual gates, for re-running one after a failure:

uv run python -m build.validate            # under the new schema
uv run python -m build.check_verification
uv run python -m build.check_payload
uv run python -m pytest tests/ -q

Plus the before/after distribution comparison, and (maintainer) check_parity once the warehouse side is deployed (docs/operations/deploy-models.md).

Stop and escalate

• It is really one category's ladder → build-rubric.
• The warehouse or front-end contract must change in lockstep → coordinate the deploy, don't

ship the repo half alone.