--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:
error in place of data, and exits with a non-zero status:
schemais1. 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.revisionis 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 is0before 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 — yourgit 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_atis when the read started, in UTC.error.codesays why the command refused, in a word your program can act on (below).error.messageis the same text the command prints afterjig: error:, meant for a person.
Why a command refused
Act onerror.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.
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:
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:
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:
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:
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:
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:
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 youragent.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:
{"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 injig 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
--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.
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: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:
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:
"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 offersresume. Send it with the revision you read:
--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 offeringclose is closed with the revision you read, once the person has said yes:
jig task list --json lists it, now with "status":"consolidated":
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 offersapprove-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:
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.
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, asclose 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:
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 withjig task new, giving the goal on the command line instead of writing
a file first:
## 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:
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:
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.
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: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:
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:
schemas/json.md.
Which Jig is installed
jig version --json works anywhere, with no project, and answers with the envelope above:
installedis the version on your machine,X.Y.Z, orX.Y.Z+<sha>when it runs unreleased code. The+<sha>part does not count when you compare it withlatest.latestis the newest release, ornullwhen Jig does not know it: it is offline, or there is no global Jig to ask. That is not an error.checked_atsays 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.
The person’s own settings are changed with the commands a person uses, adding --json:
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.