Skip to main content
You install Jig once and upgrade it many times. Install covers the two commands; this page is about what happens afterwards — what the upgrade did on its own, what it left for you, and why the line between them is where it is.
Or say “upgrade Jig” to your agent in the project: the jig-upgrade skill updates the tool when a newer release is out, runs the upgrade with a dry run first, does the steps the release asks for by hand where it can, and asks you before it touches anything that would stop the upgrade. jig doctor tells you when it is worth running the first of these: its latest release line asks the tool’s own origin for the newest published tag and reports one of three things — a newer release is out (with the two commands above as the fix), this is already the newest, or it could not check (no network, or nothing to ask) rather than guessing “up to date” from silence. You do not have to remember to run jig doctor for this. Housekeeping asks the same question once a day (housekeeping.cadence) as part of its own fetch, and jig status — plain text or --html/--open — shows a newer release the moment one is out, with the same two commands as the fix. It says nothing when there is nothing to say: no check yet, the last one could not reach the origin, or this is already the newest.

After an upgrade: what to do, in order

This is the whole list, from the moment you decide to upgrade to the moment the project is back at work. Every step says what to do and what you should see. If you skipped several releases, the order does not change: do it once, and read every release between yours and the new one in step 5.
1

Update the tool on your machine (once per machine)

You should see one line that starts with self-update:, such as self-update: updated 0.23.0 -> 0.24.0 (…), or self-update: already current at 0.24.0 (…) when there is nothing newer. It refuses, and changes nothing, when Jig’s own checkout on your machine has uncommitted changes. This step changes no project.
2

In each project: start clean, look, then upgrade

Open a terminal in the project and make sure of two things:
  • No uncommitted changes to files git already tracks. Commit them, stash them with git stash, or finish the work they belong to. New files git does not track yet do not count.
  • You are not on the branch of a task that is still in progress. The upgrade works on a branch of its own and would take your checkout off the task’s branch. Go to your base branch (usually main) first. If a task has a worktree of its own, run the upgrade in the main checkout, not inside that worktree.
Then ask what would change, without changing anything:
It lists what would be placed, replaced, removed or kept. If something would stop a real run it says so in lines that start note: a real upgrade would stop:; deal with those first. Then run it for real:
A real run that is refused changes nothing and says why; the usual refusals are listed below.
3

See how far the upgrade went on its own, and finish the rest

The upgrade is a change of its own: it creates the branch jig/upgrade-<version> from your base branch and makes one commit titled Upgrade Jig <from> -> <to>. How much more it does depends on agent.git, the setting that says how far your agent may go with git on your behalf (run jig config keys to see where yours comes from). Find your level:none — the change is staged and nothing is committed. The run prints the one command that commits it:
Run exactly that command. Then push the branch and open a pull request the way you usually do, or, if your project does not use pull requests, merge the branch into your base branch yourself.commit — the change is committed on jig/upgrade-<version>. Nothing leaves your machine. Push the branch and open a pull request yourself, or merge it into your base branch.push — committed and pushed to origin. (A repository with no remote named origin gets upgrade: no remote named origin, so nothing is pushed at this level and above; the commit is still made.) Open the pull request yourself on your hosting site (GitHub, GitLab), or merge the branch into your base branch.pr — committed, pushed, and a pull request opened; the run prints its address. Nobody has merged it yet. Whoever may merge in your project (you, or a colleague) reviews it, waits for its checks to pass, and merges it.merge — as pr, then the run waits for the checks and merges the pull request itself once they are green. It prints merged <address>. When it cannot, it prints not merged: <reason> instead — checks red, or still running after agent.ci_timeout minutes, no checks at all, the repository refusing the merge, no hosting site available. That is a finished run, not a failure: the pull request is open, so merge it yourself once the reason is dealt with.When the run merged it itself (merge, and it printed merged <address>), there is nothing left to clean up. The run puts you back on your base branch, brings it up to date, and deletes the upgrade branch on your machine and on origin:
If you started from another branch, one more line names the way back to it:
It deletes only its own branch, with git branch -d (git itself refuses to delete a branch whose work is nowhere else), and on origin only while the branch is still at the commit that was merged. When it cannot — the branch is checked out in another worktree, or git refuses — it says upgrade: kept branch <name>: <why> and leaves it for you. To keep every branch, set git.delete_merged_branches: false in .ai/config.local.yaml; the run then also leaves you on the upgrade branch, with a next: line saying it is merged.At push and pr, or when the run printed not merged:, the upgrade branch is on origin and nothing more is needed on your machine, so the run puts you back on the branch you started from, and says how to return to the upgrade if its pull request needs a fix:
Being off the upgrade branch is what lets it be deleted after the merge: a branch that is checked out is never deleted. Inside a worktree of its own the run does not move the checkout.At none and commit the upgrade exists only on your machine, so the run leaves your checkout on the upgrade branch, and it ends with two lines that say where you are:
Once the pull request is merged (by you or a colleague), come back to your base branch, if you are not on it already, and take the merge in. When the pull request is on GitHub or GitLab and gh or glab is signed in, one command does that and the branch deletion below: jig upgrade --land, which refuses, changing nothing, while the pull request is still open, and which, run from another branch, brings the base up to date without switching you to it (more). By hand, these are two separate commands; run them one after the other.
Git says Switched to branch 'main'. Use your own base branch name if it is not main (git.base_branch in .ai/config.yaml).
Git lists the files the upgrade changed. This brings the merged upgrade onto your machine. If you merged the branch on your own machine instead of on the hosting site, you already have it and can skip this command.The upgrade branch does not need deleting by hand: once its work is in your base branch, the next housekeeping run (it starts on its own with your agent’s session, at most once a day) deletes it with git branch -d, and its copy on origin too when your agent.git is push or higher and the hosting site reports the pull request merged. To remove it at once instead:
Git says Deleted branch jig/upgrade-0.24.0. Write the version you upgraded to. This form of the command is the safe one: it refuses to delete a branch whose work is not in your base branch, so it cannot lose the upgrade.A pull request merged by squashing is recognised too: Jig asks the hosting site whether it was merged, and git checks the branch against its copy on origin. When that copy is already gone from your machine (your editor’s background fetch --prune removes it once the hosting site deletes the branch), git answers not fully merged; Jig then deletes the branch anyway if its last commit is the one the hosting site merged, or an earlier one. A branch with a commit added after that stays, and Jig says kept branch <name>: git does not see all of its commits merged. That is the one case for deleting it by hand:
Run git branch -D jig/upgrade-0.24.0 only if all of these hold: the pull request is shown as Merged (not Closed) on your hosting site, after git pull your base branch contains the upgrade (jig doctor shows the new version), and the commit added after the merge is one you do not need. -D deletes without checking anything; if any of these is not true, do not run it — ask, or leave the branch.
Two cases have no branch to clean up. A project that works on a single branch (git.branch_per_task: false) gets the commit on the branch it is on, and nothing is pushed. And when the upgrade changed nothing, it removes the branch it made and puts you back where you were, saying upgrade: nothing changed; back on <branch>.
4

Do the manual steps

The commit message, and the pull request built from it, end with a Manual steps: list and a link to this page. Those are the things the upgrade could not do for you and your project would otherwise miss. Read the list and do each item once. An empty list means there is nothing to do. The release sections below describe each release in more words.
5

Look at the new settings

A release can add settings. Nothing about your project changes until you set one — each starts on its default — but you only learn a setting exists if you look. Two places show them:
  • The upgrade itself ends with a line such as .ai/config.yaml does not mention 2 key(s) this version reads, each on its default: …. That file is the team’s, shared through Git: change it by hand and review it like code, or leave it.
  • jig config keys lists every setting this version reads, its default, and which file answers for it. The ones marked local only are personal: they are never read from .ai/config.yaml, so the upgrade line never names them. The release’s section below says which ones are new.
A personal setting goes into your own .ai/config.local.yaml, which Git ignores. Either ask your agent — “set up Jig for me” (jig-setup) asks one question at a time and writes the file after your yes — or set it yourself:
For example, autopilot.git lets autopilot runs go further with Git than the work you follow step by step. With agent.git left at pr:
agent.git: pr keeps every task you ship yourself at an open pull request that you review and merge; autopilot.git: merge lets a task run on autopilot merge its own pull request once CI passed. jig config set prints config: autopilot.git: merge (.ai/config.local.yaml), refuses a value Jig would not understand and writes nothing then, and jig status shows autopilot.git: merge (from autopilot.git). jig config unset autopilot.git --local takes it back.
6

If you skipped releases, read every section in between

Below there is one section per release, newest first, named “From X to Y”. If you upgraded from 0.22.0 to 0.24.0, read “From 0.23.0 to 0.24.0” and then “From 0.22.0 to 0.23.0”, and do what each marks as yours to do, oldest first. A section that says “nothing to do by hand” is an answer too.
7

Bring work in progress up to date

A branch that was already in progress gets the upgrade only when the base branch is merged into it, and only after the upgrade itself is merged into the base. For every branch or worktree with work in progress, switch to it and run:
Git reports the files it brought in; if a file you changed was also changed by the upgrade, it asks you to resolve that. Use your own base branch name if it is not main.
8

Restart your agent's sessions

Close and reopen the agent (Claude Code, Codex, or whichever you use) in the project. It reads Jig’s skills and your AGENTS.md when a session starts, so a session that was open during the upgrade keeps working from the old text until it is restarted.
9

Check that it took

The last line is a count, and you want 0 fail: doctor: <n> ok, <n> warn, 0 fail. Its upgrade check line reads up to date.
You want the heading to end in nothing needs you. If it names something, it names the command that deals with it. More on both at the end of this page.
10

Colleagues need only the first step

A colleague who works in the same repository runs jig self-update on their own machine, and nothing else. The upgrade lives in the repository: once its pull request is merged, git pull gives them the upgraded project. jig upgrade is done once per repository, by one person.

When the upgrade refuses

A refusal lists all its reasons at once, before anything is touched, and the fix is in the message. The usual ones: jig upgrade --dry-run does not refuse for these reasons; it prints them as note: lines, so you can see them before you try. The one refusal a dry run shares with the real run is a source that is not a release, below.

When the source is not a release

The Jig on your machine is a checkout that is not at the tag of its version: a branch (main), a commit past a release, or a version raised but not yet tagged. A checkout at the tag with files edited or added in it is not a release either; the message then says at its release tag with uncommitted changes. Its code is in no release, so a project that keeps Jig’s files in its own repository will not take it; jig upgrade --dry-run refuses too, since a plan the real run would refuse is no plan. Projects installed in link mode are not affected. Two ways out:
  • Return to a release: git -C ~/.local/share/jig checkout v0.40.0 (use the version in the message), or jig self-update once a newer release is out. For local changes, look at them with git -C ~/.local/share/jig status --short and put them away (git -C ~/.local/share/jig stash -u keeps them).
  • Take the code on purpose: jig upgrade --unreleased. The project’s .ai/manifest then records jig.version: 0.40.0+278958c.
A +<sha> after a version means unreleased code: the release number, then the commit it was taken from; .dirty after it means the checkout also had local changes. jig status shows it, and a later jig upgrade from a released Jig puts the plain version back.

What the upgrade does, and what it leaves alone

jig upgrade copies from the Jig on your machine. It replaces the files Jig installed and you did not edit, removes the ones Jig no longer ships unless you edited them, and keeps and reports everything else — as one change of its own, on a branch of its own (below). “The Jig on your machine” is the one jig status compares the project with and jig self-update moves: the jig your PATH finds. .ai/manifest records it as jig.source: global, not as the folder it lives in, because the manifest is committed and that folder is yours — on a colleague’s machine their own Jig is the one that counts. A manifest written by an older version may still name somebody’s folder, such as /Users/<name>/.local/share/jig; nothing needs editing by hand. Where that folder does not exist the upgrade uses the Jig on your machine, and the first upgrade that places a file writes global in its place. If the Jig on your machine is older than the project’s, it is not used — that would be a downgrade — and the upgrade asks you to run jig self-update first. --from <dir> still picks a checkout explicitly. The first upgrade from 0.15.0 or older ends with a shell error. Once the run has done its work, .ai/scripts/jig reports something like line 133: cmd: unbound variable — the wording and the line number depend on the version you came from, and from versions before 0.15.0 the closing summary may be missing as well. Nothing is broken: the files were already placed, and the message arrives after them, from the old jig that replaced itself while it was still being read. One file may be left unplaced — more in a project with clean filters — so run jig upgrade once more; the second run places what is left and ends cleanly. Then jig version reports the new version and jig doctor reports its upgrade check as up to date. The exception is a project whose clean filters cover Jig’s own scripts and that has upgraded before. There the old copy replaces its entry point but not its libraries, and from then on every .ai/scripts/jig command stops at once with line 37: jig_clear_git_location_env: command not found. Upgrade that project with the jig on your machine instead, as From 0.16.0 to 0.16.1 describes: it places the rest. This happens on that first upgrade only: since 0.15.1 the upgrade writes each file beside its place and renames it. Three things it will not do, and none of them are oversights. It does not edit .ai/config.yaml. That file belongs to your team, and nothing but a person edits it. A key your file does not mention takes its default, so a config written for an older version keeps working — which is also the trap, because that file is the only place anyone ever sees which settings exist. So the upgrade reports the gap instead of closing it. At the end of a real run (not a dry run) it prints a line like:
That second line means what it says. Read the list, decide whether any of it is worth having, and leave the file alone if none of it is. Nothing is wrong with a project that mentions no keys at all. It does not install your project’s tools. Jig runs your checks; it does not provide them. If a verification profile for your stack is active and its tools are missing, that is yours to fix with npm install, composer install, a virtual environment, or whatever your project uses. It does not claim a region of a file your project already had. Jig keeps the section between <!-- jig:begin --> and <!-- jig:end --> in your AGENTS.md current — but only for a project whose manifest records that Jig may. That record is written by jig init, on markers you agreed to, and the first time Jig takes over part of a file you wrote is a moment that belongs to you rather than to a command that ran while you were making coffee.

An upgrade is a change of its own

From the next release on, jig upgrade does its work as one separate change, the way a task does:
  1. The newest Jig does the work. When the copy running the command is older than the Jig it upgrades from, it hands the whole run to that newer one and says so: upgrade: this jig is 0.16.1; handing the upgrade to 0.17.0 from …. This starts with the release that brings it; an older copy still does the work itself.
  2. It checks that it may start, before it touches anything. It stops, and says what to do, when:
    • you have uncommitted changes to tracked files — commit them, git stash them, or finish the task they belong to (new files git does not track yet do not count);
    • Git converts line endings here (core.autocrlf=true) and nothing keeps Jig’s files at LF — it names the lines to add to .gitattributes;
    • you are on the branch of a started task — the upgrade would take this checkout off it. Give the task a worktree of its own with jig task start <id> --worktree, which puts this checkout back on your base branch, and run the upgrade again; if another session is still working on that task here, wait until it has finished. In the task’s own worktree, run the upgrade in the main checkout instead. A session that only looked around (jig status, jig task show of another task) does not stop it;
    • jig verify is running in this checkout — run the upgrade when it has finished.
  3. It works on a branch of its own, jig/upgrade-<version>, cut from your base branch (git.base_branch) — not from the branch you were on, so the upgrade never ends up inside a task’s pull request.
  4. It checks the result before committing. An install that is still missing something is not committed; run jig upgrade again on the same branch and it carries on.
  5. One commit, titled Upgrade Jig <from> -> <to>, with the steps this release asks for by hand and a link to this page. Then it goes as far as your agent’s git rights allow (agent.git): at none the change is staged and the run prints the one command that commits it; at commit, push, pr and merge it commits, pushes, opens the pull request and merges it once CI is green, exactly as jig task ship does.
It ends by saying where you are and how to get back:
Branches that were already in progress get the upgrade when you merge the base branch into them. If nothing needed changing, the run goes back to the branch you were on and removes the one it made. Once you have merged the upgrade’s pull request, bring it here in one step:
It asks the forge whether the pull request is merged, fast-forwards your base branch to origin’s and deletes the upgrade’s branch, here and — when your agent may push — on origin. Run from the base or the upgrade’s branch, it puts you on the base. Run from any other branch, it leaves your checkout where it is — files, uncommitted changes and all, so work in progress there, yours or another session’s, is not disturbed — and moves only the base branch; it ends with a line saying that branch still has the old Jig until you merge the base into it. It refuses, changing nothing, while the pull request is still open, while you have uncommitted changes on the base or the upgrade’s branch, when the base branch is checked out in another worktree (run it there), when your base branch has commits origin does not have, or while origin’s base here does not record the upgrade’s version yet (fetch, then run it again). Until then jig status reminds you with an upgrade pull request: line, on GitHub and GitLab alike, from the moment jig upgrade opens the pull request — it does not wait for housekeeping to hear of it. A program — Jig UI, a script that upgrades many projects — runs jig upgrade --json and reads what the run did instead of these lines: the outcome, the branch, the commit and the pull request, and the steps the release asks for by hand (Reading Jig as data). jig upgrade --dry-run never makes a branch, and it does not stop for these reasons — jig status, jig verify and jig doctor rely on it. It prints what would stop a real run as note: a real upgrade would stop: … lines instead. The one thing it refuses, as a real run does, is a source that is not a release (When the source is not a release). Two kinds of project work differently. One that uses a single branch (git.branch_per_task: false) gets the commit on the branch it is on, and nothing is pushed. One installed with jig init --link — Jig’s own repository — keeps upgrading in place, with no branch and no commit.

From 0.44.0 to 0.45.0

Nothing to do by hand, unless your project raises its version inside a task or an epic. The installer did not change. The upgrade brings new scripts, commented-out git.flow keys in the template .ai/config.yaml (your own file is not touched), a changed row and two changed paragraphs in the Jig section of AGENTS.md, and new text for the jig-autopilot, jig-consolidate, jig-idea, jig-release, jig-setup and jig-task skills. A project that raises its version. A release is now made apart from feature work (Specs and epics). From agent.git: pr, jig task ship refuses a change that raises the version (VERSION, package.json, composer.json, pyproject.toml or Cargo.toml) until the task records the commit of the base branch its release notes describe — jig task set <id> notes_through <sha> — and while the base branch has commits after it. An epic whose roadmap has no Release: line is a feature epic, and jig spec ship refuses its final pull request if that raises the version: take the bump out and release with the jig-release skill, or make it a release epic. A project that never raises a version in these files sees no change. What you will notice. Your project stays on the direct flow: the staging flow is switched on only by setting git.flow: staging. jig init and jig doctor mention it when origin has a branch named stage or staging. Your agent offers the next task that jig queue next names. A program that reads Jig’s JSON sees an origin field in jig status --json, a new item asking for jig refresh while the base branch is behind origin, and a new reason, landed, in jig knowledge proposed --json for knowledge origin already decided.

From 0.43.0 to 0.44.0

Nothing to do by hand. .ai/config.yaml did not change, and no new setting appears in the upgrade’s report. The upgrade brings new scripts and new text for the jig-pr-review skill. The review skill, for you. From 0.44.0 the installer and jig self-update place jig-pr-review in your own skills folder, so it works in any repository. The first jig self-update from 0.43.0 or older runs the old updater, which does not place it: run jig self-update once more, or the installer again (Install).

From 0.42.0 to 0.43.0

Nothing to do by hand, unless your origin is an https://github.com/... address. The installer and .ai/config.yaml did not change, and no new setting appears in the upgrade’s report. The upgrade brings new scripts and new text for the jig-verify skill. An HTTPS origin on GitHub. Jig’s pushes and fetches now go as this clone’s GitHub account, with a token it asks gh for, instead of whatever your credential helper holds. This starts with the upgrade’s own push, which already runs the new code. If several of your accounts may push to the repository, the active one is not among them and none is named, a push now stops with nothing sent, at agent.git: push too: name it before you upgrade, with jig config set --local github.account <login>. If the upgrade’s push has already stopped, its commit is on jig/upgrade-0.43.0 and running jig upgrade again does not push it: push that branch yourself and open its pull request. A push that changes a file under .github/workflows needs that account’s gh token to carry the workflow scope. gh auth refresh -s workflow adds it to the active account only; for another one, make it active for that one command with gh auth switch --user <login>, then switch back, while no other session is working: the active account is the whole machine’s, and another session would push as it meanwhile. This is a step for you, not for your agent. Over SSH, or with a GH_TOKEN in the environment, nothing changes (Two GitHub accounts). What you will notice. Under verify.full_run: ci, the header of a plain jig verify in a task’s checkout names the task and measures from the branch it was cut from. A program that reads Jig’s JSON may see not-merged from jig upgrade where it used to see failed, when the upgrade’s pull request is still open.

From 0.41.0 to 0.42.0

Nothing to do by hand, unless you have several GitHub accounts in gh. The installer and .ai/config.yaml did not change, and no new setting appears in the upgrade’s report. The upgrade brings new scripts, the new jig-pr-review skill, a new row and paragraph in the Jig section of AGENTS.md, a “Set aside” section in the spec template, and new text for the jig-autopilot, jig-consolidate, jig-idea, jig-init, jig-release and jig-setup skills. Several GitHub accounts. Jig now asks GitHub as this clone’s account rather than the one gh has active. If several of your accounts may push to the repository and the active one is not among them, jig task ship and jig gh refuse until you name it once: jig config set --local github.account <login>, or let the agent ask. It needs gh 2.40 or later (Two GitHub accounts). With one account, nothing changes. What you will notice. jig status shows a github.account: line when Jig chose among several accounts, and a drafts: line while an idea’s draft exists. An autopilot pull request’s body is shorter: no design and no journal. A program that reads Jig’s JSON may see already-filed from jig spec item file where it used to see already-exists.

From 0.40.0 to 0.41.0

Nothing to do by hand, if the Jig on your machine is a release and you have not edited a stock profile. The installer’s default and .ai/config.yaml did not change, and no new setting appears in the upgrade’s report. The upgrade brings new scripts, changes to the php, laravel, node and python profiles, and new text for the jig-accept, jig-implement, jig-review, jig-architecture-review, jig-autopilot, jig-consolidate and jig-verify skills. A stock profile you edited. jig upgrade keeps your copy of a profile.yaml or verify.sh you changed (keep-modified), so that profile goes on as in 0.40.0: a Laravel project with an edited php or laravel profile still runs its suite twice, and an edited php/profile.yaml makes jig verify warn that php names no check tests. To take the new behaviour, merge the stock profile’s changes into yours: checks: [tests] in php, node and python, covers: [php:tests] in laravel, and the jp_covered tests call around the test command in each verify.sh (Verification profiles). Check where your Jig stands first. git -C ~/.local/share/jig status -sb should print ## HEAD (no branch) and nothing under it. If it lists changed files, the upgrade refuses those too. If it names a branch past the release tag — installed with --ref main, a clone you pull, or an install from before the first release — jig upgrade in a copy-mode project now refuses it: return it to a release, as When the source is not a release says, then jig self-update. A project that already took unreleased framework files under 0.40.0 gets the released ones back from this upgrade. Until it has, the project’s own copy of Jig (.ai/scripts/jig) is the old one: its jig verify and jig status still measure pending files against such a global Jig and may ask for an upgrade that the new Jig then refuses. Return the global Jig to a release first, and they agree. What you will notice. Off a release tag, jig --version and jig status show X.Y.Z+<sha>. jig context guard says why each pending document is required. Finished tasks leave the queue on the first housekeeping run, so jig queue list gets shorter. A Laravel project’s jig verify prints skip (scope: covered by laravel, php:tests) for the php profile’s tests. A stopped autopilot run can be handed over to you (jig task autopilot <id> handover), after which jig status shows autopilot=handed-over. A program that reads Jig’s JSON may see the failure codes unreleased-source and write-still-waits, a +<sha> in jig.version values, decidable, reason and lossy on knowledge entries, handover_at on a task’s autopilot and handover among the actions a person may take.

From 0.39.0 to 0.40.0

Nothing to do by hand, unless your project comes from 0.38.1 or older: then the red box in From 0.38.1 to 0.39.0 applies to its first upgrade. The installer and .ai/config.yaml did not change, and no new setting appears in the upgrade’s report. The upgrade brings new scripts, a new priority line and paragraph in the Jig section of AGENTS.md, and new text for the jig-accept, jig-task, jig-review, jig-architecture-review, jig-autopilot, jig-consolidate, jig-idea and jig-release skills, with two new reference files under jig-task and jig-review. What you will notice. jig status has a writes: line when a write from a program waits on a branch of its own. When it would merge, jig task ship refuses if what is staged leaves changes in the tree: stage them, or pass --partial if they are not the task’s. jig task new prints a not queued: reminder on stderr. T2 and T4 reviews take two readers, and may list code smells as small findings. jig queue next can name a task as taken by another session instead of offering it, and autopilot asks it before each start, in a phase run too. jig upgrade --land in a linked worktree on the upgrade’s branch refuses and names the main checkout. A program that reads Jig’s JSON may see taken as a reason of jig queue next, a revision that moves whenever a session works a task, and upgrade-available beside an upgrade pull request for an older version.

From 0.38.1 to 0.39.0

0.38.1 asked nothing by hand, so this section covers an upgrade from 0.38.0 as well.
Run the first upgrade to 0.39.0 or newer with the Jig on your machine, by its full path. This is for a project whose Jig is 0.38.1 or older and either stops with upgrade: cannot determine the framework source root; pass --from <dir>, or has a jig.source: line in .ai/manifest naming a folder that is not on your machine — usually another person’s, such as /Users/<someone>/.local/share/jig. 0.39.0 fixes that, but jig upgrade in a project is run by the project’s own copy, which is still the old one: .ai/scripts/jig upgrade keeps failing, and so does asking your agent to “upgrade Jig”, and a jig shell function or alias that runs the project’s copy first. Do it once, in the project’s root folder, with the paths the installer uses:macOS and Linux:
Windows, in Git Bash:
The first command brings the Jig on your machine to the newest release; the second upgrades the project from it. Check the result: .ai/scripts/jig version prints that version, and .ai/manifest says jig.source: global. Then finish the upgrade as after any upgrade, from step 3. From then on the project’s own copy upgrades by itself, and a plain jig upgrade works.
If .ai/manifest names your own folder instead of global, no jig on your PATH led to the one you ran — the installer puts it there for new terminals, so open one and check with jig version. The upgrade itself is done, and it harms nobody from now on: a copy of 0.39.0 or newer reads a folder that is not on its machine as that machine’s Jig, and the next upgrade that places a file writes global. A project whose jig.source: already names a folder on your machine, or ., is not affected, and upgrades as before. Nothing else to do by hand. The installer and .ai/config.yaml did not change, and no new setting appears in the upgrade’s report. The upgrade brings new scripts and new text for the jig-consolidate, jig-review and jig-architecture-review skills and for jig-task’s delegation reference. What you will notice. jig upgrade writes jig.source: global into .ai/manifest the first time it places a file; commit it with the rest. After an upgrade that ended in a pull request, jig status shows an upgrade pull request: line until the merge is here, and jig upgrade --land brings it here (An upgrade is a change of its own). jig task ship with nothing staged now stages the changes to tracked files and ships them, where it used to refuse, and refuses instead when a new file is neither staged nor ignored: stage the new files a task added, or add them to .gitignore. A program that reads jig status --json may see the two new upgrade-pull-request-* kinds, and no upgrade-available while one stands (from 0.40.0, only while it is for this machine’s version or a newer one).

From 0.37.0 to 0.38.0

Nothing to do by hand. The installer and .ai/config.yaml did not change, and no new setting appears in the upgrade’s report. The upgrade brings new scripts and new text for the jig-task, jig-review, jig-consolidate and jig-autopilot skills; a copy of a skill you edited yourself is handled as every edited framework file is (What the upgrade does). What you will notice. Three commands refuse what they used to accept: jig task start for a T3 or T4 task with no goal in its task.md, and, for a task linked to a spec, jig task abandon without --reason and jig task set <id> status abandoned. Abandoning a task from a spec without an epic, on your main branch, switches your checkout to spec/<spec-id> and leaves it there, with the roadmap edit committed when your git level allows; jig spec ship <spec-id> sends it on. A task abandoned before the upgrade keeps its roadmap item as it was; run jig task abandon <id> --reason "<why>" on it to record the reason and close the item — after jig task unarchive <id> if housekeeping has archived it already, which it does housekeeping.abandoned_ttl (14 days) after the abandon. The first jig task ship with open P2 or P3 findings files a <task-id>-findings task. jig spec list and the status page may show a spec further along than before, because merged tasks now count. A program that reads jig spec list --json sees a new done field on each item. A pause that was already stuck. If jig task resume on 0.37.0 left a stash’s conflicts in your files and the task is still paused, the first resume on 0.38.0 does not know the stash is already there. While the conflicts are not resolved, it refuses with stash-conflict and asks you to resolve them; once they are resolved and the files git added, it applies the stash once more and the conflicts come back. Resolve them, git add the files and resume again; that resume ends the pause. To skip the second resolution, delete the paused_stash: line from .ai/workspace/tasks/<id>/state before that first resume: without a stash to apply, the resume only ends the pause, and the stash entry stays in git stash list.

From 0.36.0 to 0.37.0

Nothing to do by hand. The installer and .ai/config.yaml did not change, and no new setting appears in the upgrade’s report: housekeeping.abandoned_ttl and housekeeping.stale_after keep their keys and defaults. The upgrade brings new scripts, new text for the jig-setup skill and new comments for those two settings in the config template; a copy of the skill you edited yourself is handled as every edited framework file is (What the upgrade does). What you will notice. Housekeeping no longer deletes work nobody finished. The next run after the upgrade archives, instead of sending to the trash, an abandoned task past housekeeping.abandoned_ttl (14 days by default), and an active or ready task that nobody touched for housekeeping.stale_after (60 days) and has no pull request, no flag and no worktree. An archived task keeps its notes with no time limit and drops out of jig task list, which says how many there are; jig task list --status archived shows them and jig task unarchive <id> brings one back. A task that used to be only flagged as possibly stale now moves to the archive, with the default housekeeping.stale_after or your own. Tasks already in .ai/runtime/trash/ follow the old schedule. A program that reads jig task list --json sees new fields and the actions archive and unarchive; schema 1 stands and archived tasks are left out unless asked for. The new command jig task merge <from> --into <to> merges one task into another (Merge a task into another).

From 0.35.0 to 0.36.0

Nothing to do by hand. The installer and the skills did not change; the upgrade brings new scripts, and its report names two settings your .ai/config.yaml does not mention yet, worktree.setup and worktree.setup_timeout — both work without a line. What you will notice. Starting a task worktree in a project with an unshared folder of separate repositories no longer warns you, at the start, to add worktree.share; it says, as information, how to share the folder with that task (jig task bootstrap <id> --share <dir>). A project that shares packages/ with every task and runs a local development setup there may want to move to --share and a worktree.setup instead.

From 0.34.0 to 0.35.0

Nothing on the checklist the upgrade itself prints. The installer, .ai/config.yaml and the skills did not change; the upgrade brings new scripts. What you will notice. jig task resume <id> no longer refuses with switch to <branch> first when the pause stashed nothing: it ends the pause from any checkout. A pause made with --stash still has to be resumed where the task’s branch is checked out.

From 0.33.0 to 0.34.0

Nothing on the checklist the upgrade itself prints. The installer and .ai/config.yaml did not change. The upgrade brings new scripts, a new skill, jig-upgrade, new text for the jig-release and jig-setup skills, and a paragraph about jig-upgrade in Jig’s section of your AGENTS.md; a copy you edited yourself is handled as every edited framework file is (What the upgrade does). What you will notice. At agent.git: merge, a task whose change raises the project’s version — a release — is no longer merged by jig task ship unless an unattended run may merge it (release.merge: agent). It ends with an open pull request and not merged: this change raises the version; outside an unattended run a release's merge is the human's, or in an unattended run with release.merge: human, not merged: release.merge is human in this clone; the release's merge is the person's; a major one is opened as a draft. Asking your agent to “upgrade Jig” now runs the jig-upgrade skill.

From 0.32.0 to 0.33.0

Nothing on the checklist the upgrade itself prints. The installer and .ai/config.yaml did not change. The upgrade brings new scripts and new text for the jig-autopilot and jig-task skills and the phase-run reference; a copy you edited yourself is handled as every edited framework file is (What the upgrade does). What you will notice. A project with a folder of separate repositories that worktree.share does not name gets a line about it in jig status; add the key it names when you want task worktrees to see that folder. A task worktree made before the upgrade keeps the links it got by full path; to have relative ones, start the task’s worktree anew. The counter under .ai/runtime/revision/ now holds files rather than directories; what an earlier version left there is read and cleared as it is.

From 0.31.0 to 0.32.0

Nothing on the checklist the upgrade itself prints. The installer and .ai/config.yaml did not change. The upgrade brings new scripts and new text for the jig-task skill, which tells the agent to ask jig queue next when you ask what to take next; a copy you edited yourself is handled as every edited framework file is (What the upgrade does). What you will notice. Nothing until the project has a queue. Once it does, jig status ends its task lines with a next: line and the status page shows “Next task”. A dependency counts as done only once Jig has seen its change merged, so right after a merge jig queue next may ask you to run jig housekeeping first.

From 0.30.0 to 0.31.0

Nothing on the checklist the upgrade itself prints. The installer and .ai/config.yaml did not change. The upgrade brings new scripts and new text for the jig-task and jig-autopilot skills and the phase-run reference, which tell the agent what a pause request looks like; a copy you edited yourself is handled as every edited framework file is (What the upgrade does). What you will notice. Upgrade a project before you ask its tasks to pause. The updated global jig already writes the queue and the request, but an agent in a project whose .ai/scripts/jig is still 0.30.0 enters its next stage as before: the request waits, unseen, and jig status shows it as pending. The queue starts empty, and nothing changes in jig status or jig context until you put something in it.

From 0.29.0 to 0.30.0

Nothing on the checklist the upgrade itself prints. The installer and .ai/config.yaml did not change. The upgrade brings new scripts and new text for the review skills (jig-review, jig-architecture-review) and the jig-task delegation reference; a copy you edited yourself is handled as every edited framework file is (What the upgrade does). What you will notice. A repeat review after a fix is shorter. A review receipt written before the upgrade does not record what its diff was measured from, so the first repeat review of a task already reviewed then still reads the whole change; the next one is narrow. Your agent stops fixing P3 nits after a review and lists them in the pull request instead.

From 0.28.0 to 0.29.0

Nothing on the checklist the upgrade itself prints. The installer, the skills and .ai/config.yaml did not change; the upgrade brings new scripts only. What you will notice. Nothing, unless you ask for it: every command prints the same text as before, and --json is new. Two new files appear under .ai/runtime/, which is not under git: revision/, the clone’s revision counter, and forge-cache, where jig housekeeping keeps pull request and CI state. Housekeeping asks the forge once more per run — for the checks of open pull requests — whatever the number of tasks.

From 0.27.0 to 0.28.0

Nothing on the checklist the upgrade itself prints. The installer did not change, and .ai/config.yaml is not touched. The upgrade brings new text for the review skills (jig-review, jig-architecture-review, jig-autopilot) and two jig-task references; a copy you edited yourself is handled as every edited framework file is (What the upgrade does). What you will notice. After the upgrade your agent hands every review to a helper agent, also when you work beside it. If you had set no review model or runtime, a T2 or T3 task’s review now starts a subagent where it used to run in your session; with none set, the helper runs on your session’s model. For a T4 task a review model or review runtime unlike the coding one is what puts its review on another model; without one, the pull request says so. Nothing to set, and nothing to change if you are happy with your session’s model.

From 0.26.0 to 0.27.0

Nothing on the checklist the upgrade itself prints. The installer did not change, and .ai/config.yaml is not touched. Everything new is a personal setting, unset by default, so a project that sets none of them works as before. Yours to choose: codex.implement_model and codex.review_model. These local-only keys let a Codex session hand an entire stage to a subagent on the named model. They are unset by default. If Codex cannot start a helper you explicitly selected, your agent is instructed to stop the stage and report why. Existing claude.* values remain specific to Claude Code. Yours to choose: executor.implement_runtime and executor.review_runtime. Set either to claude or codex to have that stage run in the other runtime’s CLI, started by your agent in the task worktree with limited tools; executor.implement_model and executor.review_model name its model. Local only. jig-setup asks about them when the other CLI is installed, or set them with jig config set executor.review_runtime codex --local. Read Autopilot: a stage in the other runtime first. The upgrade no longer leaves you on its branch. At agent.git: push or pr, or merge when the run printed not merged:, the run now ends back on the branch you started from, with a next: line naming git checkout jig/upgrade-<version> should the pull request need a fix. A run inside a worktree of its own does not move. From 0.26.0 this already applies to the upgrade to 0.27.0 itself: the older code hands the run to the newest code it can reach.

From 0.23.0 to 0.24.0

Nothing on the checklist the upgrade itself prints. The installer did not change, and .ai/config.yaml is not touched. Two things are yours to look at: a new personal setting, and a change for a project that declares verify.full_run: ci. A new personal setting, autopilot.git. It is the level of Git rights for what an autopilot run ships, with the same values as agent.git (none, commit, push, pr, merge). Left unset it is whatever agent.git is, so a clone that does nothing ships exactly as before. It is a local key: it is read only from your .ai/config.local.yaml, never from the project’s .ai/config.yaml, so the upgrade’s “does not mention … key(s)” line never names it. Set it with the step “Look at the new settings” under After an upgrade, or let jig-setup ask you. The case it was made for:
What each does. agent.git: pr keeps every task you ship yourself at an open pull request that you review and merge. autopilot.git: merge lets a task whose autopilot run is on merge its own pull request once CI has passed, and lets an unattended jig spec ship merge an epic’s finish (release.merge: human still wins). jig upgrade and jig doctor keep going by agent.git; housekeeping reads both keys to decide whether it may delete a merged branch on origin. jig config set prints config: autopilot.git: merge (.ai/config.local.yaml) and refuses a value Jig would not understand; jig status shows autopilot.git: merge (from autopilot.git); jig config unset autopilot.git --local takes it back. Set it once the upgrade is in your checkout: the key is read by the 0.24.0 scripts, and the project’s older ones do not know it. If your project declares verify.full_run: ci. A plain jig verify no longer starts the full test set, in any profile, and no longer lints the whole tree. Where it used to run everything (a change to routes/, config/, composer.json, a lock file, a file no test is named after) it runs the tests it can name and the linters on the changed files, and prints what it left out:
When nothing else ran, it says this run verified nothing here: your CI is the check that counts. Things to know:
  • To run the whole thing on your machine anyway, use jig verify --full. A non-empty CI environment variable does the same, so a CI service still runs everything.
  • The same applies to the linters and static analysis a profile runs on the whole tree: phpstan, ruff, rubocop, eslint and mypy when their configuration changed, dart analyze and format and dotnet format when pubspec or the solution changed, cargo fmt and clippy on a workspace-wide change, go vet on a module-wide change, shellcheck when .shellcheckrc changed, and always tsc and swift build, which cannot narrow. They are left to CI with the same full set left to CI wording.
  • mypy now checks only the changed files under ci, where it used to check the whole tree. A file checked on its own can miss what it breaks in code that calls it, which only CI’s full run finds; and files named on the command line bypass mypy’s exclude, so a changed file in an excluded directory is checked.
  • This relies on your CI running every check on every pull request; Jig does not check that. If it does not, set verify.full_run back to local to get the old behaviour.
  • A project without verify.full_run: ci sees no change.
  • A profile you edited yourself is kept by the upgrade (keep-modified) and keeps the old behaviour until you take over the new helpers from Jig’s copy.
Placed for you. jig upgrade updates the scripts that carry this (config, profile, spec, status, task, verify and housekeeping under .ai/scripts/lib), the profiles and the skills.

From 0.22.0 to 0.23.0

Nothing on the checklist the upgrade itself prints, and nothing to do by hand. The installer did not change; .ai/config.yaml is not touched. One thing deserves a look before you upgrade a clone that has been used for a while: The first housekeeping run after the upgrade deletes the merged Jig branches it can, all at once. Branches Jig made (jig/upgrade-*, finish/<id>, close/<id>, the task branches git.branch_template names) whose work has landed are deleted from your clone, and the first run is the one that meets all the ones collected so far; on a clone that has been through dozens of tasks that is dozens of branches. Housekeeping starts on its own with your agent’s session, by default at most once a day, once the project carries the 0.23.0 scripts. On origin it deletes only when your agent.git is push or higher with housekeeping.fetch not false, only for a branch whose pull request the hosting site reports merged (on GitHub, among the last 200 pull requests it lists), and only while the branch is still at the commit that was merged. An older squash-merged branch is not recognised and stays. One whose copy on origin is already gone goes only when its last commit is the one the hosting site merged, or an earlier one; otherwise Jig says kept branch <name>: git does not see all of its commits merged. To see what it would delete, before it does, in the project’s main checkout:
It prints would delete branch <name> for each branch in your clone it would delete, and would delete branch <name> on origin, if it is still at the merged commit where it would also touch origin, and changes nothing. A branch you want to keep is safe if it is checked out in a worktree or its name is not one Jig gives. To turn the deleting off for good in this clone:
That writes .ai/config.local.yaml, which is yours alone and not committed. It is a local key: your file overrides the project’s .ai/config.yaml, per clone; set it in each clone where you want the branches kept. What is never deleted. The base branch, epic/* and spec/*, and any branch whose name is not one Jig gives its own: your own feature branches stay, whatever their state. A branch checked out in any worktree. The branch of a task whose workspace is still in place, and the branch it was cut from. A branch with an open pull request, as its head or as the base another one is stacked on. A branch holding a commit that is nowhere else: Jig deletes with git branch -d, and past Git’s refusal only a branch whose last commit is in a pull request the hosting site reports merged; anything else Jig keeps and says kept branch <name>: git does not see all of its commits merged. Housekeeping’s sweep runs only in the clone’s main checkout, and nothing is deleted when git.delete_merged_branches is false. What you will see after a merge Jig made. When jig upgrade or jig task ship merges the pull request itself (agent.git: merge), the run puts you back on your base branch, brings it up to date and deletes the branch here and on origin; the steps under After an upgrade show the lines. A task shipped from its own worktree keeps its branch until the task is closed. An upgrade that was not merged, or ran at a lower level, still leaves the checkout on the upgrade branch, as before. Which copy runs. These runs follow whichever copy of Jig runs them. jig upgrade started by the project’s older copy (0.22.0) hands the run to the newer Jig after jig self-update; a merged upgrade run entirely by 0.22.0 leaves its branch behind, and the 0.23.0 housekeeping deletes it afterwards. Housekeeping’s sweep runs from the project’s own scripts, so it starts once the upgrade is in your checkout. Placed for you. jig upgrade updates the scripts that carry this (common, config, housekeeping, task, spec and upgrade under .ai/scripts/lib).

From 0.21.0 to 0.22.0

Nothing on the checklist the upgrade itself prints, and nothing to do by hand. The installer changed (see below); .ai/config.yaml is not touched. Placed for you. jig upgrade adds .ai/scripts/lib/output.sh, the shared output layer, updates the scripts that use it (doctor, upgrade, status, checkout, task) and the jig-setup skill under .claude/skills/ and .codex/skills/. What you will see at a terminal. jig doctor and jig upgrade print what needs you first (failures, then warnings, each with its fix), group the rest, and end with a short summary. jig status reads by section (Needs you, Install, Settings, Tasks, Knowledge & specs, Recent activity here) under a heading that ends in the verdict, and groups tasks by epic and spec with each one’s progress; its rules and marks use ─, · and … where the locale is UTF-8 and plain ASCII where it is not. The installer and jig-setup use the same level words, with ask before a question. The facts are the same; the order, the grouping and the closing lines are new. Pipes, CI and agents get the same bytes as before from doctor, upgrade, status and the installer (jig-setup is a skill and speaks in blocks wherever it runs). The terminal form is chosen once per run, only when standard output is a terminal. Anything that reads the output through a pipe, a file or an agent’s shell gets the report you had in 0.21.0, byte for byte; a script that parses it keeps working. JIG_TERMINAL=0 asks for the plain form under a terminal and JIG_TERMINAL=1 for the terminal form under a pipe. NO_COLOR set to anything non-empty, or TERM=dumb, removes colour and keeps the grouping. The PowerShell installer colours through the console, never with escape codes. An upgrade no longer refuses because of a session that only looked around. In 0.21.0 an upgrade stopped when another agent session had run any Jig command in the checkout within the last hours. From 0.22.0 it stops only when you are on the branch of a started, unfinished task, and the message names the task, its branch and the way on (jig task start <id> --worktree, then the upgrade again; inside the task’s own worktree, run it in the main checkout). This holds when the upgrade is run by 0.22.0: after jig self-update, or handed there by an older copy of the project’s script, which hands the run to the newer Jig. A project with git.branch_per_task: false is not asked at all. The installer changed. install.sh and install.ps1 speak the new layout at a terminal and print what they printed before elsewhere (for install.ps1, held by line-level checks). If you run the installer again on a machine you keep up to date, nothing else changes; the Windows release checklist was not walked on a real machine for this release (see the changelog).

From 0.20.0 to 0.21.0

Nothing on the checklist the upgrade itself prints. The installer did not change. One thing is placed for you, two are yours to choose, and two change what Jig refuses. Placed for you. jig upgrade adds skills/jig-task/references/delegation.md, updates the skills that changed (jig-autopilot, jig-implement, jig-review, jig-architecture-review, jig-verify, jig-task, jig-setup, jig-idea, jig-release) under .claude/skills/ and .codex/skills/. .ai/config.yaml is not touched; the comment in the template config only gains release.merge. Finishing a task now needs its records. From 0.21.0, status ready, knowledge_consolidated true and jig task ship refuse a task whose class asks for a stage that left no record (the approved design for T3 and T4, a review receipt for T2 and up, status ready before consolidation) and say which and how to write it. A task you filed before the upgrade has no route_evidence key and is judged as before: the same list is printed as a warning (was filed before route evidence was checked, so this passes without: ...) and the task passes. A task filed after the upgrade is refused. Two command forms changed for everyone, and a refusal names the new form: lowering a class is jig task set <id> class <Tn> --reason <text>, and jig task autopilot <id> resume takes --answer <the human's answer> and is refused in an unattended run. Where nobody answers (an unattended clone), jig task gate <id> approved is refused and an approval is given with --by agent; an attended clone is unchanged. (Since 0.33.0 the refusal holds only inside a task’s own unattended run: a task worked by hand is approved by you in either kind of clone.) A script or a skill of your own that calls these must use the new forms. Where a project’s own tests or smoke steps jump a fresh task to its end, classify it and sign verification off first (jig task set <id> class T0, status ready, knowledge_consolidated true). Yours to choose: release.merge. Only for a project that releases through an epic. The default, agent, is the behaviour you had. To keep the merge of an epic’s final pull request for yourself even when your agent may merge tasks, jig config set release.merge human --local; it is personal and is ignored in .ai/config.yaml. An epic already cut finishes on finish/<id> instead of on the epic itself; nothing to do beforehand. Yours to choose: claude.implement_model and claude.review_model. Unset by default, which keeps every stage with your agent. To have Claude Code hand writing the code, or reviewing it, to a helper on a cheaper model, answer the new question in jig-setup, or jig config set claude.implement_model sonnet --local (likewise claude.review_model). Read Autopilot: helpers on another model first. A link in a task workspace is checked wherever it leads. If your .ai/workspace or .ai/workspace/tasks is a link you made yourself to a folder outside the repository and its worktrees, the commands that write into a task workspace now refuse it. The links jig task start --worktree makes, and one from a worktree to its owner’s workspace, are fine.

From 0.19.0 to 0.20.0

Nothing on the checklist the upgrade itself prints. Two things are placed for you, two are yours to choose, and one changes what a stale review means. Placed for you. jig upgrade adds the jig-release skill (under .claude/skills/ and .codex/skills/, as for the other skills), updates the other skills that changed, and refreshes the section between <!-- jig:begin --> and <!-- jig:end --> in your AGENTS.md when Jig may: it gains a paragraph on jig-release and one on lean routes. .ai/config.yaml is not touched; the upgrade’s usual report of keys it does not mention will include worktree.share, and leaving it on its default (nothing shared) is correct for most projects. Yours to choose: worktree.share. If your project keeps separate repositories under edit in a folder such as packages/, declare it in .ai/config.yaml and put the folder in .gitignore:
Do not also leave that folder in worktree.carry; if you do, it is shared and the copy is skipped with a warning. The 0.19.0 and earlier advice to work on such packages in the main checkout no longer applies. Worktrees that already exist are not changed; jig task bootstrap <id> links the shared entries into one. Yours to choose: route.depth. The default, full, is the route you ran before; nothing changes unless you set it. To take less, jig config set route.depth lean --local; it is personal and is ignored in .ai/config.yaml. Read what lean trims first (jig task route <id>, or Concepts). A task that has already started can be given a worktree. jig task start <id> --worktree on it now moves it, instead of refusing. This does not change a task you have not started. Reviews in flight. A review receipt written by 0.19.0 or earlier has no diff or context, so it is compared by the working tree, as before, until the task is reviewed again and the receipt is rewritten. After that, merging the base branch into a task no longer makes the review stale when nothing the task touches moved. If a task is stale after the upgrade, the message now says whether its own change or the knowledge under it moved.

From 0.18.0 to 0.19.0

Nothing on the checklist the upgrade itself prints. What changes is what jig verify finds, and one of your own settings gains a sibling. .devcontainer/, .ddev/ and .lando.yml are no longer reasons to refuse. The 0.18.0 section below names them as signs Jig could not place. Now a project with .ddev/config.yaml, .lando.yml or .devcontainer/devcontainer.json has its checks run in that environment, and a stopped one is refused with its start command. Of the signs 0.18.0 listed, only a .devcontainer/ or .ddev/ folder without its manifest, services mounting the project that Jig cannot pick one of, or a DB_HOST naming a compose service still stop jig verify with exit 3; a stopped environment is refused too, with its start command. The DDEV, Lando and devcontainer detectors have been tried with stand-ins for their commands only; if one misreads your setup, jig config set run.exec <command> --local overrides it, and jig verify --explain shows where the checks go. A Devilbox or Laravel Herd project may now run somewhere new. A project served by Devilbox (its PHP container mounts your project, wherever its data folder lives) has its checks run in that container; a Herd site runs them on this machine with Herd’s PHP first on PATH. Neither needs a setting. If Herd’s PHP is not the one you want, or Jig did not find it, name the folder yourself:
The other nine profiles now run in the environment instead of being skipped. In 0.18.0, inside a container the shell, python, go, rust, ruby, jvm, dotnet, dart and swift profiles were skipped with a reason; now they run there, so a check that was reported as skipped may now run, and fail. Under an environment, Python’s tools come from a .venv/ or venv/ that runs there, otherwise from the environment’s own PATH, not from the virtualenv of this machine. jig doctor and jig verify --explain may now warn. When the checks run on this machine, they compare its PHP, Node and Python with composer.json, package.json (engines.node) and .python-version. A warning is advice only; nothing is refused because of it. jig task start and jig upgrade no longer suggest deleting a session’s record. The refusals name a worktree or waiting; the record expires on its own after checkout.busy_ttl. A session that only filed tasks no longer occupies the checkout.

From 0.17.1 to 0.18.0

Nothing on the checklist the upgrade itself prints. Two things about running Jig change, and one is unchanged. If your project runs in a container, jig verify may now refuse, where it used to run on this machine. On Laravel Sail, or with one docker compose service that mounts the project, Jig finds the container and runs the checks in it; jig verify --explain prints where. If there are signs of a container it cannot place — a .devcontainer/, .ddev/ or .lando.yml, two services mounting the project, a DB_HOST in .env that names a compose service — it exits 3 with the reason. Say “set up Jig for me” (jig-setup now asks where your tests run) or set it yourself, in your own .ai/config.local.yaml:
A stopped container is refused too, with the command that starts it where Jig knows one. In a task’s worktree, a container that mounts another copy of the project is refused: start an environment for the worktree. Projects that need none of this see no change; with CI set and run.exec at auto, nothing is detected or refused. jig task start now refuses a checkout another session is working in. Where it used to move HEAD under that session, it stops, names the task or session and how long ago it ran, and offers jig task start <id> --worktree, waiting, or deleting the stale record it names. Start the task in a worktree, or finish the other work first. Leftover temporary files from older versions stay. Jig no longer leaves *.tmp.<pid> files behind when a command is interrupted, but the ones an earlier version already left are not removed. They are files named like a real file followed by .tmp. and a number (.new., .join. and .restore. too); nothing reads them, so delete them once, with no Jig command running. Unchanged: jig task set <id> status consolidated still refuses until the task’s pull request has merged, as it has since 0.17.0.

From 0.16.1 to 0.17.0

Nothing on the checklist the upgrade itself prints — that only names steps from 0.15.0 and older, and you are already past them. Two things about running the upgrade change anyway. jig upgrade now refuses a dirty working tree, where it used to run regardless. If you are in the habit of running it with edits still uncommitted, commit or git stash them first, or finish the task that owns them; the upgrade tells you which when it refuses. It also stops if another session or a jig verify run is busy in the same checkout — wait for it to finish, or the message names the record to remove if that session has already ended. It now works on its own branch, jig/upgrade-0.17.0, and makes one commit. You no longer apply the upgrade’s changes to whatever branch you happened to be on: it cuts its branch from your base branch, commits there, and — depending on your agent’s git rights — pushes, opens a pull request and merges it, the same as jig task ship. See An upgrade is a change of its own. Once that branch is merged, merge the base into any branch still in progress, the way the upgrade’s own closing lines say. If you worked around the Windows line-endings fault by hand, the workaround is now redundant. A project that added .ai/** text eol=lf (and the two skills lines) to .gitattributes to fix the known issue keeps working; the upgrade now ships the same pinning, scoped more precisely to what Jig places (.ai/manifest, .ai/scripts/**, .ai/profiles/**, .ai/templates/**, both adapters’ skill directories), for projects that never added it themselves. Nothing to reconcile either way.

From 0.16.0 to 0.16.1

Nothing to do by hand if you upgrade the way the top of this page shows: jig self-update, then jig upgrade in the project. The jig on your machine is then 0.16.1, and it does the work itself. Two kinds of project need a step more when the upgrade is run by the project’s own copy instead — .ai/scripts/jig upgrade, which is how an agent usually runs it. That copy is the version you are leaving, and in these two it hashes Jig’s files differently from 0.16.1. A repository with SHA-256 object names (created with git init --object-format=sha256). Straight after the upgrade, jig status reports every framework file as modified — measured on a project of 97 framework files:
Nothing is wrong with the files. Run the upgrade once more: this time 0.16.1 does the work, records the files as they are, and the drift goes.
A repository whose clean filters cover Jig’s own scripts — a filter= line in .gitattributes matching *.sh, say — when an earlier upgrade already left those scripts reported as modified. The project’s copy cannot replace them, itself included, so however often it runs it ends like this, and jig version stays at 0.16.0:
Run the upgrade with the jig on your machine instead; it places them, and jig status reports no drift afterwards:
An ordinary repository sees neither. Coming from 0.15.0 or older, you run the upgrade a second time anyway, for the reason given above, and in a SHA-256 repository that second run clears the drift too.

From 0.15 to 0.16

This release has three steps that only you can take. None of them happens automatically, and the first two change whether Jig keeps working the way you expect. See the changelog for everything else in the release.
1

Run the jig-init skill, so upgrades can reach your AGENTS.md

Ask your agent to run the jig-init skill. It adds the markers and records Jig’s claim to that section, with your consent, and from then on improvements to Jig’s own instructions arrive with each upgrade.Adding the markers by hand does not do it: without the recorded claim, jig upgrade reports keep-unmarked AGENTS.md and changes nothing, however well-formed your markers are.If your Jig section has also drifted from Jig’s own text, markers alone are still not enough — no claim gets recorded, and the upgrade reports keep-modified instead. Reconcile the text first, against .ai/templates/AGENTS.md, and then mark it.
2

Install the tools your project's checks need

jig verify used to answer ok when a profile for your stack was active and every one of its checks had been skipped for a missing tool. It now refuses — exit 3, nothing was checked, so this is not a pass — and jig task ship will not ship on it.jig verify --list shows which profiles are installed; install what they need. If your project is covered by no profile at all, nothing changes for you: Jig says so plainly and does not block you, because there is nothing you could install to resolve it.
3

If you wrote a profile that checks nothing by design, say so

A profile that asserts nothing about the code — one that exists to carry shared setup, say — needs verifies: nothing in its profile.yaml. Absence means the profile claims it verifies something, which is the cautious default: without the line, the day its tool goes missing it refuses rather than quietly reporting that nothing checks your project.This applies only to profiles you wrote yourself. Every profile Jig ships already declares it.

Checking that it took

Three commands answer it, and you do not need to remember which does what — run jig doctor first and follow what it says.
The lines to look for:
A warn reading Jig section in AGENTS.md is not marked, so upgrades cannot reach it means step one is still outstanding. One reading no Jig section in AGENTS.md means Jig’s instructions never reached your agent at all, which is worth fixing before anything else. One line deserves a second look because it is reported as ok rather than a warning:
That is not a problem — it is Jig respecting an edit someone made inside the markers — but it does mean this project will not receive improvements to that section. If the edit was deliberate, leave it. If nobody remembers making it, reconcile against .ai/templates/AGENTS.md.
Lists every setting this version reads, its default, and where its current value comes from — your project’s file, your personal one, or the default. Use it after reading the upgrade’s closing line, to see what the new version brought.
The one that proves step two. A pass means checks ran. nothing was checked, so this is not a pass with exit 3 means tools are still missing. nothing here checks this project with exit 0 means no profile covers your stack — not something an upgrade can fix, and not something that blocks you. Run jig verify --explain first if you want to see what a run will expand to before spending the time on it.