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

# WorkGraph Reference

> WorkGraph item fields, statuses, edges, evidence, tools, and host surfaces.

# WorkGraph Reference

WorkGraph is an optional realm-scoped subsystem. Agents mutate general work
items through tools. Public RPC and REST expose observability/operator lookup.
CLI and trusted in-process hosts add narrow goal and attention controls.

## WorkItem

| Field               | Type                   | Description                                   |        |          |
| ------------------- | ---------------------- | --------------------------------------------- | ------ | -------- |
| `id`                | `WorkItemId`           | Unique work item id                           |        |          |
| `realm_id`          | `string`               | Realm that owns the item                      |        |          |
| `namespace`         | `WorkNamespace`        | Namespace within the realm, default `default` |        |          |
| `title`             | `string`               | Short title                                   |        |          |
| `description`       | `string?`              | Optional detail                               |        |          |
| `status`            | `WorkStatus`           | Lifecycle status                              |        |          |
| `priority`          | \`low                  | medium                                        | high\` | Priority |
| `completion_policy` | `WorkCompletionPolicy` | Closure policy for goal-like work             |        |          |
| `labels`            | `string[]`             | Filtering and grouping labels                 |        |          |
| `owner`             | `WorkOwner?`           | Intended owner or assignee                    |        |          |
| `claim`             | `WorkClaim?`           | Active claim owner and optional lease         |        |          |
| `machine_state`     | object                 | Generated WorkGraph lifecycle machine state   |        |          |
| `revision`          | `u64`                  | CAS revision for write tools                  |        |          |
| `due_at`            | RFC3339 timestamp?     | Due time                                      |        |          |
| `not_before`        | RFC3339 timestamp?     | Earliest eligibility time                     |        |          |
| `snoozed_until`     | RFC3339 timestamp?     | Snooze gate                                   |        |          |
| `created_at`        | RFC3339 timestamp      | Creation time                                 |        |          |
| `updated_at`        | RFC3339 timestamp      | Last update time                              |        |          |
| `terminal_at`       | RFC3339 timestamp?     | Terminal time                                 |        |          |
| `external_refs`     | `ExternalWorkRef[]`    | Typed pointers to external objects            |        |          |
| `evidence_refs`     | `WorkEvidenceRef[]`    | Typed evidence pointers                       |        |          |

## Statuses

| Status        | Meaning                                                      |
| ------------- | ------------------------------------------------------------ |
| `open`        | Created and not currently claimed                            |
| `in_progress` | Claimed or actively being worked                             |
| `blocked`     | Not ready because a block exists or machine state is blocked |
| `completed`   | Terminal success                                             |
| `cancelled`   | Terminal cancellation                                        |
| `failed`      | Terminal failure                                             |

Terminal items cannot be claimed.

## Completion Policies

| Policy                | Meaning                                                    |
| --------------------- | ---------------------------------------------------------- |
| `self_attest`         | The assigned attention target can request closure directly |
| `host_confirmed`      | Host confirmation evidence is required before closure      |
| `principal_confirmed` | A named principal must confirm before closure              |
| `supervisor`          | A supervisor owner key must authorize closure              |
| `reviewer_quorum`     | The required reviewer threshold must be satisfied          |

## Edge Kinds

| Kind           | Meaning                                        |
| -------------- | ---------------------------------------------- |
| `blocks`       | Source must resolve before target can be ready |
| `parent`       | Hierarchical grouping                          |
| `related`      | Non-blocking association                       |
| `supersedes`   | Source replaces target                         |
| `derived_from` | Source was derived from target                 |

WorkGraph rejects invalid endpoints, self edges, duplicate edges, and cycles for
`blocks` and `parent`.

## Owners And Claims

`WorkOwnerKey.kind` is one of:

* `principal`
* `agent`
* `session`
* `mob`
* `label`

Claims are revision-based. Mutating tools require the current `expected_revision`.
Optional leases allow abandoned work to become recoverable through machine-
approved transitions.

## Evidence Refs

`WorkEvidenceRef` contains:

| Field     | Type      | Description                                                                  |
| --------- | --------- | ---------------------------------------------------------------------------- |
| `kind`    | `string`  | Evidence type, such as `artifact`, `pr`, `log`, `summary`, or `notification` |
| `id`      | `string`  | External or Meerkat-owned artifact id                                        |
| `label`   | `string?` | Human label                                                                  |
| `summary` | `string?` | Short explanation                                                            |

Evidence refs are pointers. WorkGraph does not own the artifact content.

## Agent Tools

| Tool                     | Purpose                                                                   |
| ------------------------ | ------------------------------------------------------------------------- |
| `workgraph_create`       | Create a work item                                                        |
| `workgraph_get`          | Read one item                                                             |
| `workgraph_list`         | List items                                                                |
| `workgraph_ready`        | List machine-derived ready items                                          |
| `workgraph_snapshot`     | Read items, edges, ready ids, scope, timestamp, and event high-water mark |
| `workgraph_events`       | Read event history                                                        |
| `workgraph_claim`        | Claim an item with CAS revision                                           |
| `workgraph_release`      | Release an active claim                                                   |
| `workgraph_update`       | Update mutable item fields                                                |
| `workgraph_block`        | Put an item into blocked state                                            |
| `workgraph_close`        | Close as `completed`, `cancelled`, or `failed`                            |
| `workgraph_link`         | Add a graph edge                                                          |
| `workgraph_add_evidence` | Add an evidence reference                                                 |

## RPC

| Method                     | Purpose                        |
| -------------------------- | ------------------------------ |
| `workgraph/get`            | Read one item                  |
| `workgraph/list`           | List items                     |
| `workgraph/ready`          | List ready items               |
| `workgraph/snapshot`       | Read graph snapshot            |
| `workgraph/events`         | Read event history             |
| `workgraph/goal/status`    | Read goal and attention status |
| `workgraph/attention/list` | List attention bindings        |

General WorkGraph item mutation remains tool-owned. The goal and attention
mutation methods are trusted host-control methods and are not part of the public
REST or JSON-RPC catalog.

## REST

| Method | Path                        | Purpose                        |
| ------ | --------------------------- | ------------------------------ |
| `GET`  | `/workgraph/items`          | List items                     |
| `GET`  | `/workgraph/items/{id}`     | Read one item                  |
| `GET`  | `/workgraph/ready`          | List ready items               |
| `GET`  | `/workgraph/snapshot`       | Read graph snapshot            |
| `GET`  | `/workgraph/events`         | Read event history             |
| `POST` | `/workgraph/goal/status`    | Read goal and attention status |
| `POST` | `/workgraph/attention/list` | List attention bindings        |

The `GET` routes use query parameters such as `realm_id`, `namespace`,
`all_namespaces`, `statuses`, `labels`, `include_terminal`, `limit`, and
`after_seq` for events. The `POST /workgraph/goal/status` and
`POST /workgraph/attention/list` routes accept JSON request bodies.

## CLI

```bash theme={null}
rkat workgraph list [--namespace <NS>] [--all-namespaces] [--status <STATUS>] [--label <LABEL>] [--include-terminal] [--limit <N>] [--json]
rkat workgraph show <ID> [--namespace <NS>] [--json]
rkat workgraph ready [--namespace <NS>] [--label <LABEL>] [--limit <N>] [--json]
rkat workgraph snapshot [--namespace <NS>] [--all-namespaces] [--status <STATUS>] [--label <LABEL>] [--include-terminal] [--limit <N>] [--json]
rkat workgraph events [--namespace <NS>] [--all-namespaces] [--after-seq <N>] [--limit <N>] [--json]
rkat workgraph goal-create <SESSION_ID> <TITLE> [--namespace <NS>] [--description <TEXT>] [--mode <MODE>] [--completion-policy self-attest|host-confirmed] [--json]
rkat workgraph goal-status <BINDING_ID> [--namespace <NS>] [--json]
rkat workgraph goal-confirm <BINDING_ID> --expected-revision <N> --kind <KIND> --id <ID> [--namespace <NS>] [--label <TEXT>] [--summary <TEXT>] [--json]
rkat workgraph goal-close <BINDING_ID> --expected-revision <N> [--status completed|cancelled|failed] [--namespace <NS>] [--json]
rkat workgraph attention-list [--namespace <NS>] [--status <STATUS>] [--json]
rkat workgraph attention-pause <BINDING_ID> --expected-revision <N> [--namespace <NS>] [--json]
rkat workgraph attention-resume <BINDING_ID> --expected-revision <N> [--namespace <NS>] [--json]
```

CLI commands use the same realm flags as other `rkat` commands.

## Companion Skill

`workgraph-workflow` is an embedded builtin companion skill gated by the
`work_graph` capability. It teaches agents how to use the WorkGraph tool family.
It is discoverable through the normal skills inventory and is not automatically
preloaded.