> ## Documentation Index
> Fetch the complete documentation index at: https://jig.fapost.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Reading Jig as data

> Read your project's tasks, specs and what needs you from a script, a bot or a dashboard as JSON, without parsing text and without touching the network.

Jig's commands print text for a person. A program — a CI step, a chat bot, a dashboard such as
[Jig UI](https://jig-ui.fapost.in) — 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.

```bash theme={null}
jig task list --json
jig task list --json --all
jig task artifacts <id> --json
jig task artifact read <id> plan --json
jig spec list --json
jig status --json
jig queue list --json
jig knowledge proposed --json
jig knowledge sources --json
```

> [!NOTE]
>
> 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](#a-pull-requests-state-now)), 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`:

```json theme={null}
{"schema":1,"revision":1792079790,"generated_at":"2026-10-15T12:00:00Z","data":{"tasks":[...],"hidden":0,"housekeeping":null}}
```

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:

```json theme={null}
{"schema":1,"revision":1792079790,"generated_at":"2026-10-15T12:00:00Z","error":{"code":"usage","message":"task list: invalid status: bogus"}}
```

* `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](#writes-on-a-branch-of-their-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.

| `error.code` | What happened |
| - | - |
| `usage` | the command was called with an argument it does not take, or with a value it does not accept — check how your program calls it |
| `not-a-repository` | it ran outside a Git repository |
| `not-initialised` | the repository has no Jig yet; `jig init` sets it up |
| `stale-revision` | a write carried a `revision` that is no longer current: something changed since your program read it. Nothing was written — read again, and show the person the conflict |
| `not-found` | the task or epic named does not exist, is not in the queue where the command needs it, the task has no such document yet (`jig task artifact read`), or the knowledge document named does not exist (`jig knowledge read`) or links no source (`jig knowledge sources --diff`). For a roadmap edit: the spec it names is neither on its branch nor on the base, the phase or item is not in the roadmap on that branch, or the task it would file does not exist. Also `jig writes ship` with nothing waiting, and the task a `jig task gate`, `abandon`, `archive`, `unarchive` or `jig spec drop` names; for `jig spec drop` also a task linked to no spec, a spec with no roadmap on its branch, and a roadmap with no item that names the task |
| `already-exists` | what the command would create is already there: a task with that id, a roadmap item with that text. Nothing was written — for a task id, choose another |
| `already-filed` | the roadmap item you asked to file already names a task, filed earlier here or in another clone; the message names it. Nothing was written — another id does not help, read the roadmap again |
| `git-not-allowed` | [a write on a branch of its own](#writes-on-a-branch-of-their-own) was asked for at `agent.git: none`, where Jig commits nothing. Nothing was written; the message names the setting |
| `write-busy` | another such write is running in this project. Nothing was written — try again in a moment; if it goes on, the message names a leftover claim of a stopped write to delete |
| `unreleased-source` | copy-mode `jig init` or `jig upgrade` (dry run too) found the framework checkout off its release tag, or at it with uncommitted changes, and `--unreleased` was not given. Nothing was changed; the message names where the checkout stands and the ways out |
| `branch-checked-out` | the write's branch is checked out somewhere, and Jig never moves a checkout. Nothing was written; the message names where |
| `branch-diverged` | the write's branch and the one on the remote have diverged. Nothing was written, and nothing is forced |
| `branch-has-other-commits` | the write's branch has commits here that no write made and the remote does not have: yours, and a write does not publish them. Nothing was written; the message names the branch |
| `base-not-on-origin` | the write's base is not on the remote, at `agent.git: push` or above: a branch cut from it would carry out whatever is on it. Nothing was written; push that base yourself |
| `write-still-waits` | an earlier edit of the same spec, or of knowledge, still waits where this one cannot go: into another base, because an epic opened or finished since, or as edits that never reached the remote above ones whose pull request was closed or whose branch was deleted there. Nothing was written; the message names the branch and what to do |
| `tree-in-the-way` | an unfinished write left files at Jig's tree that git will not remove (links and empty directories Jig clears itself). Nothing was written, and trying again does not help: delete the path the message names |
| `commit-refused` | Git refused the commit, usually a hook of the project; the message says what it said. This edit was not committed; an earlier one already waiting on the branch still waits |
| `epic-missing` | the spec is built on an epic branch that is neither here nor on the remote. Nothing was written |
| `not-linkable` | the task cannot be linked to the roadmap item, or the item is done. Nothing was written |
| `not-proposed` | the knowledge document is not a proposal, nor, for `reject`, a stub whose linked file changed since it was approved: it was decided already, perhaps on a branch that still waits. Nothing was written |
| `not-on-base` | the knowledge document, or the change to the file a stub links, is in your checkout but not on the base the decision is judged on: not committed, or not pushed. Nothing was written — push it first |
| `not-on-branch` | the knowledge document, or that change, reached the base after the branch the decisions wait on was cut, and bringing the base into that branch conflicts. Nothing was written — merge or close the decisions waiting there, then decide. Without a conflict the decision brings the base in and joins the pull request that waits |
| `source-missing` | the file a knowledge stub links is missing or not tracked. Nothing was written |
| `not-closable` | the task you asked to close is not one Jig offers to close: its knowledge decision is not recorded, its pull request is not merged, or, on the staging flow, its work is not in the base yet. Nothing was written — show the person the message, which is the reason |
| `not-paused` | the task you asked to resume is neither paused nor parked at the staging branch: somebody resumed it first. Nothing was written — read again |
| `already-paused` | the task you asked to pause is paused already: somebody paused it first. Nothing was written — read again |
| `wrong-checkout` | the task's pause put work aside in a stash, and the stash can only be applied where the task's branch is checked out. Nothing was written — show the person the message, which names that place |
| `stash-conflict` | the stash the pause put aside did not apply, or applied with conflicts that are not resolved yet. The task stays paused and the stash is kept — the person resolves it in the task's checkout and resumes again; a stash already applied with conflicts is not applied a second time |
| `upgrade-blocked` | `jig upgrade` would not start here and changed nothing; the message names every reason and what to do |
| `not-merged` | the upgrade is done and waits for its pull request to be merged: `jig upgrade --land` found it still open, or `jig upgrade` found this version already on an unmerged `jig/upgrade-<version>` branch whose pull request is open. Nothing was changed; the message names the pull request — merge it, then run `jig upgrade --land` |
| `unknown-key`, `not-local`, `invalid-value`, `secret-key` | `jig config set --json` refused a key or value: a name Jig does not read, a key only the team's `.ai/config.yaml` answers for, a value the key does not accept, or a secret on a command line. Nothing was written |
| `not-on-staging` | `jig task promote` found none of the task's own commits in the tested staging commit. Nothing was pushed and no pull request opened |
| `behind-staging` | `jig task promote` found own commits of the task the tested staging commit does not have: a fix made after the test. Nothing was pushed and no pull request opened |
| `carries-staging` | the staging branch was merged into the task's branch, so its pull request would take untested work of others along (`jig task promote`, `jig task land`). Nothing was pushed or merged |
| `base-conflict` | `jig task promote` found the task's branch in conflict with the base branch. Without `--json` it exits 3; with it the refusal carries the paths in `message`. Whoever merges the base into the task branch resolves it. Nothing was pushed |
| `shallow-clone` | `jig task promote` ran in a shallow clone, where what a commit contains cannot be told. Nothing was pushed |
| `ci-red` | a person's merge (`jig task land --by human`, `jig task merge-pr`) found a check of the pull request failed. Checks are looked at once, never waited for. Nothing was merged |
| `ci-pending` | the same, with a check still running. Nothing was merged |
| `ci-none` | the same, with no check run on the pull request. Nothing was merged |
| `not-approved` | the pull request has changes requested or still waits for a reviewer (`message` says whom), or, for `jig task land --by human`, it is not approved and the project does not let it land without a review. Nothing was merged |
| `review-required` | `jig task land --by human --without-review` under `git.staging_review: require`: only an approval lands it. Nothing was merged |
| `conflict` | the pull request conflicts with its base. `jig task land --by human` never merges a conflict directly; the agent lands it. Nothing was merged |
| `draft` | the pull request is a draft, which is never merged. Nothing was merged |
| `mergeable-unknown` | the forge could not say yet whether the pull request merges cleanly. Ask again in a moment; nothing was merged |
| `forge-refused` | the forge refused the merge — branch protection, a required review, rights, no merge method the repository allows, or a pull request head that is not the commit that was shipped. `message` holds the forge's first line. Nothing was forced |
| `no-pull-request` | the task has no pull request to act on |
| `pull-request-closed` | the task's pull request is closed unmerged (for `jig task request-review`, merged too: nobody is asked to review any more) |
| `wrong-flow` | the command does not apply to the task in this project: not on a sound `staging` flow, a task cut from another base than `git.base_branch`, `git.staging_land: external`, `jig task land` on a pull request that goes into another branch than the staging branch (into the base branch the message names `jig task merge-pr <id> --by human`), or `jig task merge-pr` on a pull request that goes into the staging branch (the message names `jig task land <id> --by human`) |
| `not-ready` | `jig task land --by human`: the ship's gates do not pass (the knowledge decision, a blocking finding, the review receipt, the route's records); `message` is their text |
| `not-shipped` | the task's branch is not on origin as it was shipped: it has commits origin does not, or origin has no such branch |
| `notes-stale` | a release's notes no longer reach the base's tip, found right before `jig task merge-pr` merges a pull request that raises the version. Nothing was merged |
| `reviewer-unknown` | `jig task request-review`: a `--reviewer` names nobody the repository may ask, several people (`message` lists them), or a team. Only people are asked; nobody was asked |
| `autopilot-running` | the task's autopilot run is `on`: the agent is on it. For `jig task gate` without `--by agent`: the task's unattended run is `on`, so an approval there is the agent's, not a person's. Nothing was written |
| `autopilot-stopped` | `jig task gate` without `--by agent` for a task whose unattended run is `stopped`: nobody answers inside it. The message names the way on — an answer to the stop, or a handover. Nothing was written |
| `no-gate` | `jig task gate` was asked for a task that has no human gate: its class is not T3 or T4, or it has no `design.md` yet. Nothing was written |
| `already-archived` | the task you asked to archive is archived already: somebody archived it first. Nothing was written — read again |
| `not-archived` | the task you asked to unarchive is not archived: somebody unarchived it first. Nothing was written — read again |
| `wrong-status` | the task's status does not let the command run: archiving a task that is `consolidated`, abandoning one that is `archived` (unarchive it first), or closing a roadmap item for a task that is not `abandoned`. Nothing was written — read again |
| `already-closed` | `jig spec drop` found every roadmap item that names the task checked already: somebody closed it first. Nothing was written — read again |
| `ship-running` | a `jig task ship` of the task is waiting for CI and lands or merges the pull request itself (`shipping` in `jig task list --json`). Nothing was written |
| `git-level` | a command without `--by human` ran at an `agent.git` below what it needs. The action is the person's: run it with `--by human` |
| `forge-unavailable` | the command could not ask the forge: none set up for this clone, its CLI missing or not signed in, or the call failed (`jig pr reviewers`, `jig task land --by human`, `jig task promote --json`, `jig task request-review`, `jig task merge-pr`, `jig task pr-status`). `message` holds why |
| `failed` | anything else: the message says what |

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:

```json theme={null}
{
  "id": "booking-message",
  "class": "T1",
  "status": "active",
  "issue": null,
  "goal": "Show the booking reference in the confirmation message.",
  "knowledge_consolidated": false,
  "paused": false,
  "created_at": "2026-10-14",
  "updated_at": "2026-10-15",
  "branch": "task/booking-message",
  "base_branch": "main",
  "spec": {"id": "booking-flow", "title": "Booking flow", "phase": 2, "epic": "epic/booking-flow"},
  "worktree": {"path": "/home/me/shop.worktrees/booking-message", "uncommitted": 2},
  "gate": null,
  "autopilot": null,
  "pull_request": {
    "url": "https://github.com/me/shop/pull/42",
    "state": "open",
    "ci": "green",
    "fetched_at": "2026-10-15T09:00:00Z",
    "base": "main",
    "mergeable": "mergeable",
    "review": {"state": "approved", "waiting_for": []}
  },
  "shipping": null,
  "housekeeping_flags": [],
  "actions": [
    {"id": "start", "command": "jig task start booking-message", "offered": false, "reason": "task start: already started on task/booking-message; ..."},
    {"id": "pause", "command": "jig task pause booking-message", "offered": true, "reason": null},
    ...
  ]
}
```

`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:

| `id` | What it does |
| - | - |
| `start` | Start a task that was filed for later; refused for a T3 or T4 task whose `task.md` has no goal. Its command carries `--out-of-order --reason <text>` when the queue advises another task the plain start would be refused for |
| `pause`, `resume` | Set the task aside, and pick it up again |
| `request-pause`, `cancel-pause-request` | Ask a running task to pause when it finishes its current stage, and take the request back; a task nobody started is not offered a request, since no stage of it would take one — pause it with `pause` |
| `approve-gate` | Approve the design of a T3 or T4 task waiting at its gate |
| `answer-stop` | Answer an autopilot run that stopped to ask you something |
| `handover` | Take a stopped autopilot run over and finish the task without autopilot; its `command` asks for your words as `<text>` |
| `set-class` | Change the task's class |
| `ship` | Commit, push and open the pull request, as far as your settings let the agent |
| `land` | On the staging flow, land the task's open pull request on the staging branch. The `command` ends in `--by human`: it is the person's own landing, which does not read `agent.git` |
| `request-review` | Ask the forge to add reviewers to the task's open pull request; its `command` asks for `--reviewer <login>` |
| `merge` | Merge the task's open pull request into its own base on the forge (the direct flow, and a staging-flow task whose pull request went into the base: one that changes the flow itself; a pull request into the staging branch is landed, and `land` is the action). Withheld while the forge cache says the checks are red or pending or that it conflicts |
| `promote` | On the staging flow, open the pull request that takes a tested task into the main branch |
| `pr-status` | Read where the task's pull request stands on the forge now (checks, review, mergeability, protection); the only action that asks the forge by itself |
| `close` | Close a task whose work has landed |
| `abandon` | Give the task up; its `command` asks for `--reason <text>` when the task is linked to a spec |
| `archive` | Put an active, ready or abandoned task away, without deleting it |
| `unarchive` | Bring an archived task back to the status it had |
| `reopen` | Take back an abandoned task |
| `drop-item` | Close the roadmap item an abandoned task left open, in Jig's own tree, on a branch of the spec's own: no checkout of yours moves (see [Giving a task up](#giving-a-task-up-and-putting-it-away)). Offered only when the item is there to close, in the roadmap as this clone has it, and `agent.git` lets Jig commit; an archived task that was abandoned still offers it |

`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.

```json theme={null}
{
  "id": "booking",
  "title": "Booking flow",
  "missing_files": [],
  "release": "minor",
  "epic": {"branch": "epic/booking", "state": "open", "checked_out": false, "missing": false, "ref": "refs/remotes/origin/epic/booking"},
  "progress": {"done": 1, "total": 3, "filed": 1, "fog": 1},
  "phases": [
    {
      "phase": 1,
      "title": "Book a table",
      "done": 1, "total": 3, "filed": 1, "fog": 1,
      "items": [
        {"id": "i-3f9a1c5e02b7", "text": "`booking-form` — the form", "checked": true, "done": true, "task": "booking-form", "fog": false},
        {"id": "i-91d4e7a60c38", "text": "`booking-message` — the confirmation", "checked": false, "done": false, "task": "booking-message", "fog": false},
        {"id": "i-5b02c8d7e419", "text": "fog: reminders by text message", "checked": false, "done": false, "task": null, "fog": true}
      ]
    }
  ],
  "waiting": null
}
```

`progress` is the same count `jig spec list` prints, and the sum of the phases. Each item has an `id`,
which a [roadmap write](#changing-a-roadmap) 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`](#writes-on-a-branch-of-their-own) 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.

```json theme={null}
{
  "attention": [
    {
      "kind": "autopilot-stopped",
      "subject": {"type": "task", "id": "booking-message"},
      "tasks": ["booking-message"],
      "title": "Autopilot stopped and is waiting for you",
      "detail": "stopped 5 min ago: Which payment provider should the refund use?",
      "todo": "Answer from any session: jig task autopilot booking-message answer --answer <text>; the run resumes when a session with a free slot runs jig task autopilot booking-message resume (jig queue next lists it under resume first).",
      "url": null,
      "question": "Which payment provider should the refund use?",
      "stopped_at": "2026-10-15T08:55:00Z"
    }
  ],
  "housekeeping": {"ran_at": "2026-10-15T09:00:00Z", "forge": "github", "stale": false},
  "knowledge_counts_at": "2026-10-15T08:00:00Z"
}
```

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](https://jig.fapost.in/manual-control.md#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:

```json theme={null}
{
  "kind": "pull-request-waiting",
  "subject": {"type": "task", "id": "booking-message"},
  "tasks": ["booking-message"],
  "title": "A pull request is waiting for review or merge",
  "detail": "CI is green and it merges cleanly, as of 2026-11-14T09:00:00Z",
  "todo": "Merge it: jig task merge-pr booking-message --by human; see why it waits: jig task pr-status booking-message --json",
  "url": "https://github.com/me/shop/pull/42",
  "pull_request": {"branch": "task/booking-message", "base": "main", "state": "open", "fetched_at": "2026-11-14T09:00:00Z", "url": "https://github.com/me/shop/pull/42", "ci": "green", "mergeable": "mergeable", "review": {"state": "none", "waiting_for": []}},
  "actions": [
    {"id": "merge", "command": "jig task merge-pr booking-message --by human", "offered": true, "reason": null},
    {"id": "pr-status", "command": "jig task pr-status booking-message --json", "offered": true, "reason": null}
  ]
}
```

`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:

```json theme={null}
"origin": {"base": "main", "fetched_at": "2026-11-12T09:00:00Z", "behind": 5, "ahead": 0}
```

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:

```bash theme={null}
jig refresh --json
```

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`](https://github.com/fapost-lab/jig/blob/main/schemas/json.md#jig-refresh---json).

## 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:

```json theme={null}
{"schema":1,"revision":1792079790,"generated_at":"2026-10-19T12:00:00Z","data":{"items":[
  {"ref":"epic:booking","kind":"epic","id":"booking","level":null,"position":100,"priority":0,"depends_on":[]},
  {"ref":"task:booking-form","kind":"task","id":"booking-form","level":"epic:booking","position":100,"priority":null,"depends_on":[]},
  {"ref":"task:booking-message","kind":"task","id":"booking-message","level":"epic:booking","position":200,"priority":1,"depends_on":[{"on":"task:booking-form","reason":"Quotes the form"}]}
]}}
```

`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:

```json theme={null}
{"schema":1,"revision":1794604700,"generated_at":"2026-11-13T21:17:53Z","data":{"next":{"ref":"task:booking-form","kind":"task","id":"booking-form","level":null,"position":100,"priority":1,"started":false},"reason":null,"waiting":[{"ref":"task:booking-message","on":"task:booking-form","state":"unknown","reason":"The message quotes the form"}],"taken":[],"in_progress":[{"ref":"task:booking-export","id":"booking-export","priority":2}],"blocked":[],"not_queued":1,"resume":[],"slots":{"limit":2,"building":1,"free":1}}}
```

`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](https://github.com/fapost-lab/jig/blob/main/schemas/json.md).

## 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:

```json theme={null}
{"base": "staging", "source": "history", "author": "me", "candidates": [{"login": "alice", "name": "Alice Smith", "reviews": 2}]}
```

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](https://github.com/fapost-lab/jig/blob/main/schemas/json.md#jig-pr-reviewers---json).

## 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:

```json theme={null}
{"task_id": "booking-message", "pull_request": {"url": "https://github.com/me/shop/pull/42", "state": "open", "draft": false, "base": "main", "mergeable": "clean",
  "checks": {"state": "pending", "list": [{"name": "test (ubuntu)", "state": "pending", "url": "https://github.com/me/shop/actions/runs/1", "duration_s": 420}]},
  "review": {"state": "waiting", "waiting_for": ["alice"]},
  "blockers": ["ci-pending", "not-approved"]}}
```

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](https://github.com/fapost-lab/jig/blob/main/schemas/json.md#jig-task-pr-status---json).

## 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`:

| Command | What it does |
| - | - |
| `jig task request-review <id> --reviewer <login> --by human` | asks the forge to add reviewers to the open pull request; takes none off |
| `jig task land <id> --by human` | lands the pull request on the staging branch: CI looked at once, review asked as `git.staging_review` says; a conflict is refused, never merged directly |
| `jig task merge-pr <id> --by human` | merges the pull request into its own base on the forge (the direct flow), and closes the task when its knowledge decision is recorded |
| `jig task promote <id> --by human` | opens the pull request that takes a tested task into the main branch |

`--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](#changing-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](https://github.com/fapost-lab/jig/blob/main/schemas/json.md#jig-task-land---by-human---json).

## 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:

```bash theme={null}
jig queue move booking-message --after booking-form --revision 1792079790 --json
jig queue set booking-message --priority 0 --revision 1792079790 --json
jig queue depend booking-message --on booking-form --reason "Quotes the form" --revision 1792079790 --json
```

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:

```json theme={null}
{"schema":1,"revision":1792079790,"generated_at":"2026-10-19T12:00:00Z","data":{"ref":"task:booking-message","item":{"ref":"task:booking-message","kind":"task","id":"booking-message","level":null,"position":150,"priority":0,"depends_on":[]}}}
```

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`](https://jig.fapost.in/configuration) allows. Nothing you have checked out moves or goes dirty.

```json theme={null}
{"schema":1,"revision":1793825280,"generated_at":"2026-11-04T20:55:47Z","data":{"spec":"foo","item":{"id":"i-7d2bc8dc7707","text":"Export a page","checked":false,"task":null,"fog":false,"phase":2},"write":{"target":"spec:foo","branch":"spec/foo","base":"main","commit":"4354faecc647079ac9e77cc352e8d007374c250e","commits":1,"pushed":true,"pr":null,"merged":false,"committed":true,"level":"push","note":"agent.git is push: the pull request is yours"}}}
```

`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:

```bash theme={null}
jig writes --json
```

```json theme={null}
{"schema":1,"revision":1793825285,"generated_at":"2026-11-04T20:55:48Z","data":{"writes":[{"target":"spec:foo","branch":"spec/foo","base":"main","commit":"4354faecc647079ac9e77cc352e8d007374c250e","commits":1,"pushed":true,"pr":null,"merged":false}]}}
```

`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`:

```bash theme={null}
jig writes ship spec:foo --json
```

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](https://github.com/fapost-lab/jig/blob/main/schemas/json.md).

### Changing a roadmap

Each item in `jig spec list --json` has an `id`, which a write names it by:

```bash theme={null}
jig spec item add foo --phase 2 --text "Export a page" --revision 1793825280 --json
jig spec item move foo i-7d2bc8dc7707 --phase 1 --top --revision 1793825290 --json
jig spec item file foo i-7d2bc8dc7707 --task export-page --revision 1793825300 --json
jig spec item file foo i-7d2bc8dc7707 --new export-page --goal "Export a page" --revision 1793825300 --json
```

`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

```bash theme={null}
jig knowledge accept feature-alpha --revision 1793825286 --json
jig knowledge reject feature-beta --revision 1793825290 --json
jig knowledge reviewed convention-stub --revision 1793825295 --json
```

```json theme={null}
{"schema":1,"revision":1793825286,"generated_at":"2026-11-04T20:55:49Z","data":{"decisions":[{"id":"feature-alpha","decision":"accepted","path":".ai/knowledge/features/alpha.md"}],"write":{"target":"knowledge","branch":"knowledge/decisions","base":"main","commit":"d84d893f204caa70748ed0c58f9779be39197148","commits":1,"pushed":true,"pr":null,"merged":false,"committed":true,"level":"push","note":"agent.git is push: the pull request is yours"}}}
```

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.

```bash theme={null}
jig knowledge decide --accept feature-alpha --reject feature-beta --reviewed convention-stub --revision 1793825286 --json
```

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:

```bash theme={null}
jig queue request booking-message pause --reason "Need to check the copy first" --revision 1792079790 --json
jig queue cancel booking-message pause --revision 1792079790 --json
```

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:

```json theme={null}
{"schema":1,"revision":1792079790,"generated_at":"2026-10-19T12:00:00Z","data":{"ref":"task:booking-message","request":{"kind":"pause","requested_at":"2026-10-19T12:00:00Z","reason":"Need to check the copy first"}}}
```

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:

```bash theme={null}
jig task pause booking-message --revision 1792079790 --json
```

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`.

```json theme={null}
{"schema":1,"revision":1792079790,"generated_at":"2026-10-19T12:00:00Z","data":{"task":{"id":"booking-message","paused":true,"…":"…"},"pause":{"stash":null,"request":null}}}
```

## Resuming a paused task

A paused task offers `resume`. Send it with the revision you read:

```bash theme={null}
jig task resume booking-message --revision 1792079790 --json
```

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:

```json theme={null}
{"schema":1,"revision":1792079790,"generated_at":"2026-10-19T12:00:00Z","data":{"task":{"id":"booking-message","paused":false,"…":"…"},"resume":{"paused_days":2,"stash":null,"uncommitted":0,"overlap":["src/booking/message.ts"],"parked":null}}}
```

`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:

```bash theme={null}
jig task set booking-message status consolidated --revision 1792079790 --json
```

The answer is the task as `jig task list --json` lists it, now with `"status":"consolidated"`:

```json theme={null}
{"schema":1,"revision":1792079790,"generated_at":"2026-10-19T12:00:00Z","data":{"task":{"id":"booking-message","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:

```bash theme={null}
jig task gate booking-message approved --revision 1792079790 --json
```

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.

```json theme={null}
{"schema":1,"revision":1792079790,"generated_at":"2026-10-19T12:00:00Z","data":{"task":{"id":"booking-message","gate":"approved","…":"…"},"gate":{"state":"approved","by":"human","design":"069789757ba120c7030986efcf80aeee2b2e7c26"}}}
```

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:

```bash theme={null}
jig task abandon booking-message --reason "lives in monitoring" --moved-to "../monitoring#bookings" --revision 1792079790 --json
jig task archive booking-message --revision 1792079790 --json
jig task unarchive booking-message --revision 1792079790 --json
```

`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:

```json theme={null}
{"schema":1,"revision":1792079790,"generated_at":"2026-10-19T12:00:00Z","data":{"task":{"id":"booking-message","status":"abandoned","…":"…"},"abandon":{"reason":"lives in monitoring","moved_to":"../monitoring#bookings","note":null,"spec":"booking"}}}
```

`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:

```bash theme={null}
jig spec drop booking-message --json
```

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](#writes-on-a-branch-of-their-own).
The answer is the item as the roadmap now has it, and where the edit went:

```json theme={null}
{"schema":1,"revision":1794662924,"generated_at":"2026-11-14T13:28:41Z","data":{"spec":"booking","task":"booking-message","item":{"id":"i-6e0c406be4be","text":"`booking-message` — Guests get a message — dropped (2026-11-14): lives in monitoring","checked":true,"task":"booking-message","fog":false,"phase":2},"write":{"target":"spec:booking","branch":"spec/booking","base":"main","commit":"5fecbc36ed6e764db54d47c03b915594a99a84f7","commits":1,"pushed":false,"pr":null,"merged":false,"committed":true,"level":"commit","note":"agent.git is commit: pushing spec/booking is yours"}}}
```

`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:

```bash theme={null}
jig task new booking-message --goal "Guests get a confirmation message after booking" --json
```

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:

```json theme={null}
{"schema":1,"revision":1792405174,"generated_at":"2026-10-19T10:22:28Z","data":{"task":{"id":"booking-message","class":null,"status":"active","issue":null,"goal":"Guests get a confirmation message after booking","knowledge_consolidated":false,"paused":false,"pause_request":null,"created_at":"2026-10-19","updated_at":"2026-10-19","branch":null,"base_branch":"main","worktree":null,"gate":null,"autopilot":null,"pull_request":null,"housekeeping_flags":[],"actions":[...]}}}
```

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:

```json theme={null}
{"schema":1,"revision":1792405176,"generated_at":"2026-10-19T10:22:28Z","error":{"code":"already-exists","message":"task new: task already exists: booking-message"}}
```

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`](https://github.com/fapost-lab/jig/blob/main/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:

```bash theme={null}
jig task artifacts booking-message --json
```

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:

```json theme={null}
{"schema":1,"revision":1792405174,"generated_at":"2026-10-29T10:22:28Z","data":{"task":"booking-message","artifacts":[{"kind":"task","state":"present","reason":null,"updated_at":"2026-10-29T09:12:40Z","bytes":1365},{"kind":"discovery","state":"missing","reason":null,"updated_at":null,"bytes":null},...]}}
```

`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:

```bash theme={null}
jig task artifact read booking-message plan --json
```

```json theme={null}
{"schema":1,"revision":1792405174,"generated_at":"2026-10-29T10:22:30Z","data":{"task":"booking-message","kind":"plan","updated_at":"2026-10-29T09:12:40Z","bytes":2221,"content":"# Plan\n\n..."}}
```

`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:

```bash theme={null}
jig knowledge proposed --json
jig knowledge sources --json
jig knowledge sources --diff convention-coding-style --json
jig knowledge read convention-coding-style --json
```

`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):

```json theme={null}
{"schema":1,"revision":1793805159,"generated_at":"2026-11-04T15:12:41Z","data":{"proposals":[{"id":"feature-billing","type":"feature","domains":["billing"],"path":".ai/knowledge/features/billing.md","paths":["src/billing/**"],"summary":"How invoices are issued","source":null,"waiting":null,"decidable":true,"reason":null,"lossy":false},{"id":"convention-release","type":"convention","domains":["core"],"path":".ai/knowledge/sources/release.md","paths":[],"summary":null,"source":"docs/release.md","waiting":null,"decidable":true,"reason":null,"lossy":false}],"waiting":null}}
```

`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:

```json theme={null}
{"schema":1,"revision":1793805159,"generated_at":"2026-11-04T15:12:49Z","data":{"sources":[{"id":"convention-coding-style","state":"changed","status":"active","path":".ai/knowledge/sources/coding-style.md","source":"docs/coding-style.md","bytes":62,"waiting":null,"decidable":true,"reason":null,"lossy":false},{"id":"convention-release","state":"proposed","status":"proposed","path":".ai/knowledge/sources/release.md","source":"docs/release.md","bytes":21,"waiting":null,"decidable":true,"reason":null,"lossy":false}],"counts":{"linked":2,"changed":1,"unrecorded":0,"missing":0},"waiting":null}}
```

`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:

```json theme={null}
{"schema":1,"revision":1793805159,"generated_at":"2026-11-04T15:12:50Z","data":{"id":"convention-coding-style","source":"docs/coding-style.md","state":"changed","approved_hash":"d9dc8059e3a61983d9e3ab6d32dfabc8aa7feb2d","diff":"--- docs/coding-style.md (approved)\n+++ docs/coding-style.md\n@@ -1,2 +1,4 @@\n # Style\n Use tabs.\n+Use spaces, never tabs.\n+Quote \"everything\".\n","lossy":false}}
```

`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.

```json theme={null}
{"schema":1,"revision":1793805159,"generated_at":"2026-11-04T15:12:51Z","data":{"id":"convention-release","status":"proposed","path":".ai/knowledge/sources/release.md","bytes":261,"content":"---\nid: convention-release\n...","lossy":false,"source":{"path":"docs/release.md","bytes":21,"content":"# Release\n...","lossy":false}}}
```

A decision is [written on a branch of its own](#deciding-knowledge). 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:

```bash theme={null}
jig upgrade --json
```

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](#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:

```bash theme={null}
jig upgrade --land --json
```

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:

```json theme={null}
{"schema":1,"revision":1792500000,"generated_at":"2026-10-25T09:08:11Z","error":{"code":"upgrade-blocked","message":"upgrade: nothing was changed:\n  - the working tree has uncommitted changes; commit them, stash them (`git stash`), or finish the task they belong to, then run `jig upgrade` again"}}
```

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:

```json theme={null}
{"schema":1,"revision":0,"generated_at":"2026-11-15T12:00:00Z","data":{"installed":"0.45.0","latest":"0.46.0","checked_at":"2026-11-15T12:00:00Z"}}
```

* `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:

```bash theme={null}
jig config keys --json
```

```json theme={null}
{"schema":1,"revision":1792079790,"generated_at":"2026-11-04T12:00:00Z","data":{"keys":[{"key":"agent.git","value":"none","set":false,"source":"default","scope":"local only","kind":"choice","allowed":["none","commit","push","pr","merge"],"default":"none","description":"How far your agent takes a finished task with git.","secret":false}]}}
```

`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.

> [!WARNING]
>
> 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`:

```bash theme={null}
jig config set agent.git pr --local --json
jig config unset agent.git --local --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](#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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.