Config versioning and migration framework

Status: Partially implemented — Phase 1 (config file versioning) and Phase 2 (role manifest versioning) shipped; Phase 3 (--pr auto-migration) and Phase 4 (Renovate-style migration GitHub Action) remain open (Configuration ergonomics)

Shipped facts

config.toml and per-workspace files under ~/.config/jackin/workspaces/<name>.toml carry a top-level version field (CURRENT_CONFIG_VERSION / CURRENT_WORKSPACE_VERSION, currently v1alpha8 in crates/jackin-config/src/versions.rs). AppConfig::load_or_init (crates/jackin-config/src/app_config/persist.rs) reads the raw TOML, extracts version (missing = legacy), and walks the migration registry in crates/jackin-config/src/migrations.rs — a compile-time slice of toml_edit-based transform functions, one per version step — before deserializing into typed structs. Migrated files are rewritten atomically (atomic_write) and one line is printed to stderr. A file stamped newer than the binary's current version errors rather than silently misbehaving. This is fully automatic; operators do nothing.

jackin.role.toml carries the same version field (CURRENT_MANIFEST_VERSION, currently v1alpha6 in crates/jackin-core/src/constants.rs). Because role manifests live in repos jackin❯ does not own, migration is explicit rather than automatic: jackin role migrate <role-repo-path> (a subcommand of the main jackin binary, crates/jackin/src/cli/role.rs) and the standalone jackin-role migrate <role-repo-path> binary (crates/jackin/src/bin/role.rs, same RoleCommand enum) both apply the migration chain and write the result back to a local clone for the author to review, commit, and push. An older-stamped manifest that uses a feature newer than its declared version is rejected with a migrate hint; a manifest newer than the binary understands is rejected with an "upgrade jackin" error.

Full version history, per-file current versions, and the field-level migration tables live in Schema Versions — that page is the canonical, continuously-updated record and should not be duplicated here. Configuration File covers the version field from the config-schema side.

Remaining work

1. Phase 3 — --pr auto-migration. No --pr flag exists on jackin role migrate today. Add an opt-in path that, after writing the migrated manifest, opens a branch + PR in the role repo via gh (gated on gh auth and GitHub-remote detection), so the maintainer and operators can send migration PRs to role repos without a local checkout.
2. Phase 4 — Renovate-style migration GitHub Action. Role repos already use the jackin-project/jackin-role-action reusable workflow for validation; extending it with a scheduled migrate mode (open PR when a repo's manifest is behind, close/rebase as needed) would close the gap for role authors who never run jackin role migrate by hand. Deployment shape (hosted app vs. self-hosted workflow + PAT), target-repo discovery, and rebase/conflict handling are still open design questions — see the linked research page for the design proposal this would build on.

Related work

• Research: Renovate-style role-manifest migration automation — Phase 3/4 design proposal, prior-art comparison to Renovate, and open design questions for the CI automation.
• Schema Versions — canonical version history and migration tables.
• Configuration File — version field and config schema reference.
• Agent version pinning — pinning roles to tagged versions implies a version relationship between the jackin binary and the role manifest schema.