Skip to main content
Jig’s commands print text for a person. A program — a CI step, a chat bot, a dashboard such as Jig UI — can ask for the same answer as JSON instead, by adding --json. Today jig task list, jig task artifacts, jig task artifact read, jig spec list, jig status, jig queue list, jig queue next, jig config keys, jig knowledge proposed, jig knowledge sources, jig knowledge read, jig pr reviewers, jig task pr-status and jig writes offer it, and jig queue, jig task new, jig upgrade, jig config set|unset, jig spec item and jig knowledge decide|accept|reject|reviewed answer in it when they write, as do jig task request-review|land|promote|merge-pr with --by human; more commands will, in the same form.
A --json read never touches the network. It reads files on your disk and asks Git about your local repository; it never calls gh or fetches. You can run it as often as you like, in many projects at once, without running into a forge’s rate limits. There are two exceptions, both called when a person asks and never on a timer: jig pr reviewers --json (below), because who may review a pull request is known only to the forge, and jig task pr-status <id> --json (a pull request’s state), because why it waits is too.

The envelope

Every --json command prints exactly one line: a JSON object called the envelope. On success it carries the answer in data:
When the command refuses — an unknown flag, a project without Jig — it still prints one line, with error in place of data, and exits with a non-zero status:
  • schema is 1. It changes only when a field is removed, renamed or changes type. New fields can appear at any time without it changing, so ignore the fields you do not know.
  • revision is a number that changes whenever Jig writes anything in the project — a task, its documents, a spec, knowledge, a housekeeping run — in this checkout or any of its worktrees. If it is the same as on your last read, Jig changed nothing; if it differs, read again. It is 0 before Jig’s first write, and only its changes mean anything: compare it, do not do arithmetic with it. A file changed by hand or by git — your git pull, or the branch Jig checks out after a merge — does not change it: watch the files too if that matters to you. In a clone with no main checkout to find — one made with --separate-git-dir, a submodule, or the worktrees of a bare repository — the revision is kept under <git-dir>/jig/ (the clone’s git common directory) instead, where every checkout of the clone finds it, and so are the lock and the records of a write on a branch of its own.
  • generated_at is when the read started, in UTC.
  • error.code says why the command refused, in a word your program can act on (below). error.message is the same text the command prints after jig: error:, meant for a person.
Warnings meant for a person still go to stderr, so stdout always holds just the envelope.

Why a command refused

Act on error.code, never on the wording of error.message: codes stay as they are, messages may be reworded. New codes may appear, for refusals that today read failed. Treat a code you do not know as failed. Whatever the code, the command exits with a non-zero status.

Tasks

jig task list --json lists the same tasks as jig task list with the same flags: unfinished ones by default, everything with --all, one status with --status <status>. data.hidden says how many finished tasks were left out, and data.archived how many of those are archived. A task Jig put away has status: "archived", and three fields say how: archived_at (a date), archived_reason (abandoned, stale, manual or absorbed) and archived_from (the status before); they are null on every other task. The value is new, but schema 1 stands: archived tasks are left out of the default selection, so a program appears to see one only when it asks with --status archived or --all. To show an archive column, ask for jig task list --json --status archived; an archived task offers only the unarchive action. Merging tasks (jig task merge) adds four more fields to every task: absorbed_into (the receiving task’s id, or null) and the arrays absorbs, absorbs_partly and partly_in (empty when there is nothing to say). A task absorbed whole is archived with archived_reason: "absorbed". These are additions, so schema 1 stands. Each task carries what Jig knows about it:
spec names the spec a task was filed from, read from the Spec: line of its task.md: its id, its title, the phase of the roadmap it belongs to (null when the line names none) and the epic branch its roadmap declares (null when it declares none, which is also the answer for a task whose pull request goes into main). It is null for a task that was not filed from a spec. Jig reads it from the files, so it asks no forge and costs nothing per task. A fact Jig does not have is null: branch is null for a task not started yet, goal for a task whose ## Goal holds nothing but an HTML comment such as the template’s <!-- … --> hint, gate for a task without a design approval step, autopilot for a task that never ran on autopilot. The flags are the ones the last jig housekeeping run raised and that still apply, for example needs-consolidation for merged work nobody has closed yet; data.housekeeping says when that run was. In a project on the staging flow (git.flow: staging), each task also carries staging, right after base_branch: "on" when its work is on the staging branch on origin, "behind" when it has commits of its own after that (a fix QA asked for, pushed or not), and null when none of its work is there. Merging the base branch into the task does not make it behind. Jig reads this from git every time and asks no forge, so a task your CI merged into the staging branch (git.staging_land: external) reads the same as one merged through a pull request. On any other flow the field is not there at all, so nothing changes for such a project. Beside it, parked says whether the task waits at the staging branch: null, or {"reason": "review" | "signal", "hint": "landing" | null, "review": {...} | null}. review is an open pull request into the staging branch, signal work on the staging branch waiting for “prepare for prod”, and landing means the pull request is approved (or git.staging_review is none) and the person lands it themselves (their agent.git is below merge): a pull request that still waits for a reviewer, has changes requested or has no review yet is parked for review with no landing hint, so a board offers the landing only when it can succeed. The review key holds {"state": "approved" | "changes" | "waiting" | "none", "waiting_for": ["login", ...]} for a task parked for review (who a waiting review waits for), and null for signal and when Jig has not read the review yet. Only a ready task is parked; jig task resume <id> takes one back for a fix (its status becomes active, and it is not parked again until the next jig task ship, at any agent.git), and the resume action is offered for it. Why it waits is read every time and never stored; signal follows the staging branch as last fetched, so under git.staging_land: external a shipped task reads null until a fetch shows that CI merged it. pull_request is the task’s own pull request: the one jig task ship opened, or, when you opened it by hand, the newest one from the task’s branch into where its pull request goes (the staging branch on the staging flow). It says whether it is open, merged or closed, how its checks went (green, red, pending, or none when no check ran), the base it goes into, whether it mergeable or conflicting, and its review — the same {"state", "waiting_for"} as in parked, null when Jig has not read one. All of it is what the last jig housekeeping heard from the forge, at fetched_at; the read itself never asks. When housekeeping has not run, or the forge did not answer, they are null or as old as fetched_at says — run jig housekeeping to refresh them. Checks and reviews are asked only for open pull requests, and GitLab’s list carries none, so there ci is null and the review is read only for merge requests into the staging branch. On the staging flow a task also has promotion, right after pull_request: the pull request that carries it from the staging branch into the base, {"url", "state", "ci", "mergeable", "fetched_at"}, or null while there is none (and for a task of an epic, which is never promoted). shipping is {"since": "<UTC time>"} while a jig task ship of this task is waiting for CI to merge or land the pull request itself, and null otherwise. It tells “the agent will merge it when CI passes” from “the merge is yours” and from “nobody is watching”. The ship writes a record under .ai/runtime/shipping/ and removes it when it ends; a read counts it only while that process is alive, so a ship that was killed does not stay on the card.

What a person may do next

actions lists what a person can do with the task right now, so a dashboard can show the right buttons without knowing Jig’s rules. Every task carries the same twenty-one actions, in the same order: offered is true when Jig would accept the action now, and command is the Jig command that does it, with the values you supply written as <text>, <Tn>, <login> or <file>. The commands of land, request-review, merge and promote carry --by human: the form for a person, or a dashboard acting for one, which is not limited by agent.git (that setting limits only the agent). The forge’s own protection still holds either way. When offered is false, reason says why, in the same words the command itself would refuse with. Jig judges the task’s own state. A few things it cannot know until the command runs: whether you are in the right place (run resume and ship in the task’s worktree when it has one), whether there is anything to commit, and whether the forge agrees. close trusts what the last jig housekeeping heard about the pull request: until it has seen the merge, close stays unavailable. More actions may appear later; ignore the ones you do not know.

Specs

jig spec list --json lists the same specs as jig spec list, each with its roadmap as data: its phases, the items of each phase, and how far it has come.
progress is the same count jig spec list prints, and the sum of the phases. Each item has an id, which a roadmap write names it by, and says whether it is checked, whether it counts as done, which task it names, if any, and whether it is still fog. An item counts as done when it is checked, or when the task it names is known on this machine to have merged — closed, or seen merged by the last jig housekeeping — even before its checkbox reaches the branch you read. waiting is the edit of this spec that has not landed yet, or null when none waits. It is the write as jig writes lists it (target, branch, base, commit, commits, pushed, pr and merged) with progress and phases beside it: the roadmap as it is on that branch, so a page can show the edit right after it was written. A spec built on an epic branch keeps its roadmap there. When you read it from another branch, the phases come from the epic’s branch as your repository last fetched it — epic.ref names it — and when that branch is nowhere on your disk, epic.missing is true and progress is null. release is the version level the epic will be released at, or null when none was recorded.

What needs you

jig status --json lists what needs a person in the project — the same items, in the same order, as the “Needs you” cards on the status page (jig status --open), because both are built from one list. An empty attention means nothing needs you.
A program acts on kind and subject; title, detail and todo are the words the page shows a person, and may be reworded. The kinds cover a stopped autopilot run (autopilot-stopped, or phase-stopped for a phase run, whose tasks lists every stopped task; a run a person has already answered is no item, and autopilot-stopped carries the run’s question and stopped_at), a design at its gate (gate-waiting, gate-changed), a finished task waiting for your git step (git-step), pull requests to review, merge or close (pull-request-waiting, pull-request-was-open, pull-request-of-abandoned-task), on the staging flow the staging branch drifting from the base branch (staging-unpromoted, with "staging": {"branch", "days"}; staging-unowned, your own commits there that no task holds, with "staging": {"commits", "list", "ack"} — the count, up to 20 of them, and jig staging ack --expect <count>, the command that marks them as known (it refuses when the count moved since your read); promotion-conflicting, with the same pull_request as an upgrade’s — the staging drift report), what housekeeping flagged (needs-consolidation, wrong-base, closed-unmerged, worktree-kept), a task started against the queue’s advice (started-out-of-order), knowledge to decide (knowledge-proposed, sources-changed) a newer jig (release-available), and a project whose own Jig is older than the one on your machine (upgrade-available — the item a program lists to show which projects need jig upgrade; it alone carries "versions": {"from": "0.32.0", "to": "0.33.0"}, the project’s Jig and your machine’s), and an upgrade that ended in a pull request: upgrade-pull-request-waiting while it is open, upgrade-pull-request-merged once it is merged but your base branch here still has the old Jig. Both carry "pull_request": {"branch", "base", "state", "fetched_at"} and "versions": {"to"}, and while one stands for your machine’s version or a newer one upgrade-available is not listed: what the project needs is the merge and jig upgrade --land, not a second upgrade. One for an older version, such as a pull request nobody merged or closed, does not hide the newer upgrade. The items about a task’s open pull request (pull-request-waiting, pull-request-was-open) carry what the forge cache says and what a person can do, so a card needs no second read:
pull_request.ci is green, red, pending, none or null, and mergeable is mergeable, conflicting or null, and review is the review object or null; fetched_at is null when the cache does not say when. pull_request itself is null while housekeeping has no entry for the task’s branch — right after jig task ship, until the next run — so state is always a string where the object is printed; url and actions are there either way. A task parked at the staging branch whose pull request is not approved yet gets this item too, titled by its review: “A pull request is waiting for review” (detail names who, when the cache does) or “Changes were requested on a pull request”. actions holds the same objects jig task list --json prints for the task, only the ones that fit: merge and pr-status, or land and pr-status for a task parked at the staging branch for review and landing. Because the item is as old as the cache, press pr-status before a merge when the decision matters. Pull request items are as old as the last jig housekeeping run; housekeeping.stale is true when that run is older than your housekeeping cadence or the forge did not answer, so one may be missing. The knowledge counts are the ones the last full jig status took for the page, at knowledge_counts_at.

Keeping the view current

A read never fetches, so what it says about origin — a pull request merged, a decision landed — is as of the clone’s last fetch. jig status --json says how old that is and how far the base branch here is behind:
While behind is above 0 the attention list carries base-behind-origin. One command brings the clone up, and a program may run it from a button or when its page opens:
It fetches origin, fast-forwards the base branch to origin/<base>, and closes the writes in Jig’s own tree that are over — a pull request merged by squash, then the base changed the same files again, reads as waiting until something asks GitHub or GitLab — and nothing else. It never moves the person’s checkout: on a task branch the base moves alone, and their branch and files stay as they are. It never stashes or forces, and changes in the checkout stop it only when the fast-forward would overwrite them. A base that cannot move is an answer, not an error: the command exits 0 and base.outcome says why — blocked-by-changes with git’s message naming the files, checked-out-elsewhere with the worktree (git refuses to move a branch another worktree has checked out), diverged, missing — so the page can say it in words. writes lists each write it closed, with why. The fields are in schemas/json.md.

The queue

The queue holds the priority, order and dependencies of tasks and epics, one per project, shared by every worktree. jig queue list --json (or jig queue --json) reads all of it:
items is in the queue’s order: the top level (level null) by position, then each epic’s tasks under their level. An empty queue is "items":[]. An item is the same object a write below answers with, so a board renders both with one piece of code. The queue holds order, not the tasks themselves: read it together with jig task list --json and join a task item to a task by id, and an epic item to jig spec list --json by the spec’s id. All of them carry the same revision when nothing was written between the reads, and the one you send with a change is the revision of the queue read you showed. A task that is closed, abandoned, archived or gone leaves the queue on its own: the command that finished it takes it out, and so does every jig housekeeping run (jig queue prune --json does it on demand). One finished since then may still be listed with no match in the default task list, so join against jig task list --json --all or show it as it is.

Which task is next

jig queue next --json answers what the queue advises, so a board needs no rules of its own. It reads the queue, the tasks’ state and the last jig housekeeping run, never the network, and changes nothing:
next is the task to take, or null with a reason (waiting, taken, in_progress, blocked, paused or empty) when there is none. taken lists each candidate another session is working on, with the checkout it works in, since when, idle_seconds since it was last active and the command, the words of the Jig command it last ran; such a task is never advised. Each of checkout, since and command is null when the note of that session does not hold it. waiting lists each dependency that holds a candidate back, in state open, broken (it never ends; drop it with jig queue undepend) or unknown. in_progress lists the queued tasks already started, which are never advised (next.started is always false). blocked lists the tasks a watcher could not start now, each with its kind: a run stopped for a person (stopped) or ended not merged (not_merged), a task whose task.md holds only the stub (stub) or a release’s notes task (version); none of them is advised, and a queue held only by such stops answers blocked, not empty. not_queued counts the active tasks outside the queue. resume lists the answered autopilot runs to resume before anything new (ref, id, priority, stopped_at, answered_at), which are not in in_progress; slots is {"limit", "building", "free"}; a dependency on a task whose run is stopped reads state waiting. The fields are in the schema.

Who may review a pull request

jig pr reviewers --json lists the people to offer as reviewers before jig task ship <id> --reviewer <login>: those who reviewed the last merged pull requests into the staging branch (or the base, or --base <branch>), most frequent first, or, when nobody did, everyone the repository may ask. Only people, never teams or bots, and never the account that opens the pull request:
It asks the forge, so call it when a person is about to choose, not on a timer. When the forge cannot be asked it is refused with the code forge-unavailable. The fields are in the schema.

A pull request’s state now

jig task pr-status <id> --json reads where the task’s pull request stands on the forge at this moment: the checks one by one with their links and how long they have run, the review and the people it still waits for, whether it merges cleanly, whether it is a draft, what the base branch’s protection asks, and blockers, the codes jig task merge-pr would refuse it with now:
It is the second read that asks the forge (the first is jig pr reviewers), so call it when a person presses a button, not on a timer. It writes nothing and does not change the revision. Without the forge it is refused with forge-unavailable. The fields are in the schema.

A person’s pull request actions

Four commands act on a task’s pull request for a person, and answer in the envelope with --json: --by human says a person decided, so these do not read agent.git; without it each command keeps the agent’s level and refuses with git-level below it. The agent never passes --by human. They never wait for CI and never override the forge: branch protection refuses with forge-refused, red or running checks with ci-red and ci-pending. While the agent works the task — an autopilot run on, or a jig task ship waiting for CI (shipping) — they refuse with autopilot-running and ship-running. A write is checked against the revision your program read (--revision <n>, as in the queue): stale-revision means nothing was sent to the forge. The answer carries the refreshed task. The fields and every refusal are in the schema.

Changing the queue

A program changes the queue with the same commands a person uses, adding --json and the revision of the read it decided on:
If anything changed in the project since that read — another person’s drag, an agent’s task update — the write is refused with stale-revision and nothing is written: read again and let the person decide again. Two programs that send the same revision cannot both land: at most one does, and when a third write slips in between, neither. A write that lands answers with the item as the queue now holds it:
The envelope’s revision is taken before the write, so with --revision it is the one you sent; the write raised it, so read again before the next change. A move moves one item, never the others: drag an item by sending one move, not by renumbering the list. position is only for comparing within a level — the top level (null) orders epics and tasks without an epic, and epic:<spec-id> orders that epic’s tasks.

Writes on a branch of their own

A person’s checkout is usually on the default branch or on a task’s branch, and another session may be working in it. So a change to a roadmap, or a decision on knowledge, is not written there: Jig commits it on a branch of its own, in a tree of its own that lasts as long as the command, and takes it as far as your agent.git allows. Nothing you have checked out moves or goes dirty.
write says where it went: the branch, the commit, whether it was pushed, the pull request, whether it merged, and in note, for a person, why it went no further. A push that failed is said there and is not a refusal: the commit stands and waits, and jig writes ship <target> carries it on. At agent.git: none, the default, these writes are refused with git-not-allowed: Jig commits nothing until you say it may. Edits in a row go on one branch and one pull request. A write never merges, even at merge, because a merge waits for CI: jig writes ship <target> does that when the edits are done. Until the edit lands, it waits, and a read says where. jig status counts what waits on a line of its own, writes: 1 waiting (jig writes), and prints it only when something does:
jig writes without --json prints one line for each: the target, the branch and the base it goes into, the number of commits, and the pull request, or pushed, no pull request or not pushed. To carry a waiting write further than the write itself did, as far as agent.git allows, name its target, spec:<id> or knowledge:
It answers {"write": {...}} with the same fields as a write above. With nothing waiting under that target it is refused with not-found. jig spec list --json gives each spec waiting, with the roadmap as it is on that branch, and jig knowledge proposed --json gives each proposal one with what was decided. It stops waiting once the commits are on its base as of the last fetch, since a read never fetches. A branch left behind stays where it is: when it merged by squash, its pull request was closed or it was deleted on the remote, the next edit takes a new name such as spec/foo-2, never one that is another spec’s id. A commit above what a merged pull request held keeps its name and waits for a new one. When you are on the branch yourself, or another worktree is, the write is refused with branch-checked-out, and the message says where: finish there or switch away. When the branch has commits of yours that the remote does not have, the write is refused with branch-has-other-commits: push or merge them, or move them off. A write starts from the remote’s base, so what you have not pushed to your own main stays out of it. What the remote holds is what it says it has: a branch deleted there counts for nothing, pruned or not. jig writes ship sends nothing of a pull request that was closed unmerged or merged with those edits, or of a branch the remote deleted: it answers not-found, the edit leaves jig writes, and the next edit takes a new name. An edit still waiting is never left out of sight: when an epic opened or finished since it was made, or when it never reached the remote above edits that were turned down, the next write is refused with write-still-waits until you merge, close or move it. The full shape is in the schema.

Changing a roadmap

Each item in jig spec list --json has an id, which a write names it by:
add takes --after <item>, --top or --bottom, the bottom by default, and move takes the same or --phase. file names a task filed earlier with jig task new: the item gets the task in front, and the task is linked to the spec. With --new <task-id> [--goal <text>] in place of --task, file files the task as well, in the same write, so the --revision you carry is the one of your read: jig task new moves the revision, and a task filed first would make the write stale. Everything is checked before anything is written; a refusal files no task. A spec with an open epic is edited through a pull request into the epic. The id holds through a move, a check and a filing, because it is a digest of the item’s words. Reword the item and the id changes, and a write with the old one is refused with not-found: it never touches the wrong item. Read again.

Deciding knowledge

Without --revision and --json these commands do what they always did: they change the file in your working tree, for a person deciding with an agent. To send several decisions of different kinds at once — what a person decided on a page before pressing one button — use decide. It is one write at one revision: one fetch, one commit and one push for the lot, and if any decision is refused, none is made.
The answer is the same object, with a decision per flag in the order given. Name each document once. reject also drops the link of an accepted stub whose file changed, has no approved text recorded, or is gone (changed, unrecorded, missing in sources --json): the stub becomes rejected, stays at its path, and no agent is handed the file any more. A stub whose file is unchanged is refused not-proposed. A decision is judged on the branch it is written on, not on your checkout. A proposal committed only here, or a file edited only here, is not there yet: the read says so with decidable: false and the reason the write would be refused with, not-on-base, so a page can say “push it first” before anyone presses the button. What reached the base after the decisions waiting were cut is decidable: the write brings the base into their branch and the decision joins their pull request.

Asking a running task to pause

A task an agent is working on cannot be paused from outside without losing the agent’s step. Ask instead, and the agent pauses the task when it finishes the stage it is on:
The request is kept until it is honoured or cancelled, whatever stage the task reaches meanwhile. The agent working on the task honours it at its next stage — an autopilot run when it enters the stage, any agent when the stage reads its context with jig context resolve --task <id> --stage <stage>: the task becomes paused, the request goes, and the agent stops. jig task pause honours it too. The answer is the request as the queue now holds it, null after a cancel:
While it waits, jig task list --json shows it on the task as pause_request, with requested_at for the age you show beside it, and offers cancel-pause-request instead of request-pause. Asking twice is refused with already-exists, and the first request keeps its time. Asking a task that is already paused, or finished, is refused. A task nobody started has no stage for a request to wait for, so it is not offered request-pause: the action’s reason sends you to pause, which pauses it at once. Send that with the revision you read too:
The answer is the task, now with "paused":true, and what the pause did: the stash it made (only with --stash), and the request it took with it, if one was waiting. A task paused already is refused with already-paused.

Resuming a paused task

A paused task offers resume. Send it with the revision you read:
A pause an agent made for a request puts nothing aside, so the resume only clears the pause and runs in any checkout — your program may run it in the clone’s main checkout even when the task works in a worktree of its own. A pause a person made with --stash put their uncommitted work aside; that resume applies it, so it must run where the task’s branch is checked out, and from anywhere else it is refused with wrong-checkout. The answer is the task as jig task list --json lists it, now with "paused":false, and what the resume found:
overlap lists the files the task changed that also changed on its base while it was paused — worth showing before the person continues. parked is null for a resume that ended a pause; when the resume took a task back from the staging branch instead, it holds the reason it was parked, review or signal. A resume somebody else made first is refused with not-paused; any other write in the clone since your read, with stale-revision.

Closing a task

A task offering close is closed with the revision you read, once the person has said yes:
The answer is the task as jig task list --json lists it, now with "status":"consolidated":
The command asks the forge about the pull request now, so it can refuse a close the page offered from a stale cache. A close that is not offered — the knowledge decision is not recorded, the pull request is not merged, or, on the staging flow, the work is not in the base yet — is refused with not-closable, and its message is the reason to show as it is, the one the close action carries. A write somebody else made since your read is refused with stale-revision, an unknown task with not-found; nothing is written in any of them. --revision and --json belong to this close alone: jig task set booking-message class T2 --revision 1792079790 is refused with usage, not written without the check.

Approving a design

A T3 or T4 task whose design waits at its gate offers approve-gate. The person’s yes is sent with the revision of the read that showed them the design, and without --by, so it is recorded as theirs:
The answer is the task as jig task list --json lists it, and what was approved: design is the hash of the design documents, the one a review receipt pins afterwards.
A design written since your read raises the revision, so the approval is refused with stale-revision and nothing is approved: read the task again and show the person the design as it is now. Other refusals: no-gate (not a T3 or T4 task, or no design yet), autopilot-running and autopilot-stopped (the task’s unattended run: nobody answers there, so an approval is not a person’s; the message of the stopped one names the way on) and not-found. Nothing is written in any of them. --by agent is the self-approval of an unattended run; anywhere else it is refused with failed, and a dashboard never sends it.

Giving a task up, and putting it away

Three more writes of a task take the revision you read and answer with the task, as close does:
abandon records why, and where the work went; both are optional, and a task whose task.md links a spec must give a reason (usage). Its answer carries what was recorded next to the task:
note is what the text form says about a target that is not there yet (the command that files the task there; Jig never writes to another repository), and spec names the spec whose roadmap item the task leaves open. The command touches the task’s record and nothing else: no checkout moves and the roadmap is not edited. The item waits, unchecked and visible, and the task then offers drop-item, which closes it:
It makes the same edit jig spec drop makes at a checkout — the item is checked and ends with — dropped (<day>): <reason> — but on spec/<id>, in a tree of Jig’s own, reaching the base through a pull request as far as your settings let the agent, like a roadmap edit. The answer is the item as the roadmap now has it, and where the edit went:
drop-item is refused with wrong-status for a task that is not abandoned, already-closed when somebody closed the item first, not-found for a task linked to no spec or a roadmap that does not name it, and git-not-allowed at agent.git: none, as every write on a branch of its own is. archive puts an unfinished task away and unarchive brings it back to the status it had. archive is refused with already-archived for a task archived already and wrong-status for a consolidated one; unarchive with not-archived. An archived task also leaves the queue; read it with jig queue list --json. Every one of them is refused with stale-revision for a write somebody made since your read, and with not-found for an unknown task; nothing is written in any of them.

Filing a task

A program files a task with jig task new, giving the goal on the command line instead of writing a file first:
The goal becomes the paragraph under ## Goal in the task’s task.md. It is one line of text, not empty and not starting with #. Without --goal the task has none yet, and its goal is null. You may add --class and --domains as a person would. The answer is the filed task, the same object jig task list --json lists for it:
When the id is taken, the refusal says so in its own code, so your program can ask the person for another id rather than show a generic failure:
An id Jig does not accept — a space, a leading dash — and a goal that is empty or spans lines are usage. The full field list is in the repository, in schemas/json.md.

A task’s documents

A task keeps its documents — task.md, the analysis, the design, the plan, the review and the rest — in its workspace. When the task runs in a worktree, only Jig knows where that workspace really is, so a program asks Jig instead of looking for the files:
The answer lists every kind of document Jig knows, always all twelve and always in the same order, so a page can show a fixed set and mark what is not written yet:
state is present, empty (the file is there with nothing in it), missing (not written yet) or unavailable (there is something Jig will not read — a link out of the workspace, a directory — and reason says what). updated_at and bytes are the file’s, for present and empty. Open one of them with:
content is the Markdown exactly as it is in the file. A document not written yet is refused as not-found, and so is a task the clone does not have. Both commands only read: the revision stays where it was, and comparing it tells you when to read again. Without --json, jig task artifact read prints the document itself.

Knowledge waiting for a person

Documents an agent proposed wait for a person to accept or reject them, and a linked source file that changed since it was approved waits for a person to approve the new text. Both are readable as data, so a page can show them without parsing text:
proposed lists each document whose status is proposed, with its id, type, domains, its path and paths, its summary and, for a stub that links an existing file, that file as source (null for the rest):
sources lists each stub with the state of the file it links: ok, changed (the file is not the text that was approved), unrecorded (nothing was ever approved), missing, or the stub’s own status while it is not accepted yet, with the file’s size in bytes and the counts the text form prints on its last line:
sources --diff <id> answers for one stub and carries the difference between the approved text and the file now in diff, a unified diff in one string:
diff is null when there is nothing to compare: the file is ok or missing, was never approved (unrecorded), or is changed but git no longer has the approved text. In the last two cases the file is read whole. A source can hold anything, quotes and control characters included; the answer stays one valid JSON line. Bytes that are not UTF-8 are dropped from diff and from source, and lossy says so. A stub not accepted yet reads its status in state, as in sources. An id no document has, or a document that links no source, is refused as not-found. These reads write nothing: the revision stays where it was. read <id> gives the text being decided: the document’s whole file, frontmatter included, whatever its status, and for a stub the file it links as it is now (source is null for any other document, and for a stub whose file is missing). Bytes that are not UTF-8 are dropped from a text or a file name and the lossy beside it says so. An id no document has is refused as not-found. It has no text form. Each proposal and each source carries lossy too: true when one of its strings held bytes that are not UTF-8 and they were dropped. A file name read without them may be another file’s — docs/w<FF>.md reads docs/w.md — so do not open a path or source whose record says lossy. On a machine without iconv, every byte outside ASCII becomes ? instead, one ? per byte, and lossy says so too.
A decision is written on a branch of its own. Until it lands the document here still reads proposed or changed, and its waiting says what was decided and where: {"decision":"accepted","branch":"knowledge/decisions","pr":"https://…"}, null when nothing waits. The waiting beside the list is the write itself. Each proposal and each source also carries decidable and reason: true and null when a decision sent now would be judged on what the read shows, as of the last fetch; otherwise false and not-on-base, the code the decision would be refused with, or landed: origin’s base decided it already and this checkout is only behind, so no decision is owed — show it as decided, and offer jig refresh.

Upgrading a project

A program upgrades a project the way a person does, and reads what happened:
The text the command prints for a person goes to stderr; stdout holds the envelope. outcome says how it ended — upgraded, staged (left for the person to commit), nothing-to-do, incomplete (run it again) — and git how far it went by the project’s agent.git: the branch, the commit, the pull request and whether it was merged. manual_steps lists what this release asks for by hand; an agent can do those, a script cannot. jig upgrade --dry-run --json changes nothing and lists in would_stop what a real run would refuse for. Which projects need an upgrade at all is the upgrade-available item of jig status --json (What needs you). An upgrade at agent.git: pr ends with its pull request open and the project back on its base branch, still at the old Jig. jig status --json keeps saying so — upgrade-pull-request-waiting, then upgrade-pull-request-merged — so a program shows the state from the project, not from its own memory. Run again before the merge, jig upgrade --json is refused as not-merged when the forge reports that pull request open, with its URL in the message: the upgrade is done and waits for the merge, which a program shows as waiting, not as a failure. Once it is merged, the program brings it in:
It asks the forge, fast-forwards the base branch to origin’s and deletes the upgrade’s branch. From the base or the upgrade’s branch it checks the base out; from any other branch it moves only the base branch and leaves the checkout alone, and land.checkout_on_base is false. Its data has the shape of jig upgrade --json with outcome landed or nothing-to-do and a land object beside git. A pull request still open is refused as not-merged; uncommitted changes on the base or the upgrade’s branch, a base checked out in another worktree or a base that cannot be fast-forwarded as upgrade-blocked. Neither changes anything. When the upgrade cannot start, it changes nothing and says why in its own code, with every reason in the message:
The whole shape is in schemas/json.md.

Which Jig is installed

jig version --json works anywhere, with no project, and answers with the envelope above:
  • installed is the version on your machine, X.Y.Z, or X.Y.Z+<sha> when it runs unreleased code. The +<sha> part does not count when you compare it with latest.
  • latest is the newest release, or null when Jig does not know it: it is offline, or there is no global Jig to ask. That is not an error. checked_at says when Jig last asked.
  • Jig asks the network at most every 6 hours (every hour after a failed try) and keeps the answer in ~/.cache/jig/latest-release; reading it more often costs nothing.

Your settings

A page can show the settings of a project and change the person’s own. jig config keys --json lists every key Jig reads, with the value this clone gets for it and where that value comes from:
source is local (the person’s .ai/config.local.yaml), project (the team’s .ai/config.yaml) or default. scope says who may answer the key: project keys are the team’s and a page shows them read-only; local and local only keys the person may set. kind tells the page which control to offer: a checkbox for boolean, a choice among allowed for choice, a field for the rest (duration, number, text, list). A value is always a string, as the file writes it.
A secret’s value never leaves Jig in a --json answer. notify.telegram.token has "secret":true and "value":null always; set says only whether a token is there. Jig also refuses to take a token on a command line, so a page cannot set it either: the person writes it into the file, or runs jig notify setup in their own terminal.
The person’s own settings are changed with the commands a person uses, adding --json:
A write answers with the new state of each key it touched, as keys lists it, and unset also names in removed the keys it took out of the file. A key that cannot be written, or a value it does not accept, is refused with unknown-key, not-local, invalid-value or secret-key (Why a command refused), and nothing is written. --dry-run cannot be combined with --json: a dry run writes nothing and the answer is the state after a write, so the command is refused with usage. Both commands take --revision <n> like a queue write: another write in the project since your read is refused with stale-revision, so a page and jig-setup writing the same file cannot overwrite each other’s change unseen. .ai/config.yaml is the team’s; no command here writes it.