# Tickets and the board

> Ticket fields, statuses, risk classes, and the lifecycle from backlog to done.

Section: Concepts · Canonical: https://www.meshproject.dev/docs/concepts/tickets · Index: https://www.meshproject.dev/docs/llms.txt

A ticket is a unit of work with a contract: what to change, what "done" means, and how to check it. Tickets live on a board whose columns are the ticket statuses. Agents pick tickets up, work them, and move them toward review. Humans and reviewers move them to done.

Mesh tickets are written so an agent can claim, execute, and verify one without asking a human. That is why creating a ticket requires more than a title. The extra fields feed claims, review routing, and the compliance checks.

## Create a ticket

These fields are required:

| Name | Type | Description |
| --- | --- | --- |
| `title` *(required)* | `string` | Short summary, up to 200 characters (100 through MCP). |
| `expectedFiles` *(required)* | `string[]` | At least one file the work will touch. Used to detect conflicts before anyone starts. |
| `doneDefinition` *(required)* | `string` | One statement of what done means, 20 to 500 characters. |
| `verificationCommand` *(required)* | `string` | A command that proves the work landed, 10 to 500 characters. Use n/a only when verification is manual. |
| `riskClass` *(required)* | `"local" | "shared-state" | "irreversible"` | How far a mistake spreads. See the table below. |

Optional fields include:

| Name | Type | Description |
| --- | --- | --- |
| `type` | `string` | The MCP tool accepts feature, bug, chore, refactor, spike, or docs. |
| `description` | `string` | Up to 2,000 characters. |
| `acceptanceCriteria` | `object[]` | One to 20 testable assertions. See below. |
| `priority` | `"critical" | "high" | "normal" | "low"` | Ticket urgency. |
| `outOfScope` | `string` | What the ticket deliberately does not cover. |
| `sprintId` | `string` | File the ticket straight into a sprint. |
| `parentId` | `string` | Parent ticket for sub-tasks. |
| `branch` | `string` | Git branch the work lives on. |
| `tags` | `string[]` | Up to 10 tags. |
| `assignToSelf` | `boolean` | Assign the new ticket to the caller. |

**MCP**

```
mesh_ticket_create({
  title: "Retry webhook deliveries with backoff",
  type: "feature",
  description: "Failed webhook deliveries are dropped. Retry with exponential backoff.",
  riskClass: "local",
  expectedFiles: ["src/webhooks/retry.ts", "src/webhooks/retry.test.ts"],
  acceptanceCriteria: [
    { title: "Failed deliveries retry up to 5 times with doubling delay", evidence: "ledger" }
  ],
  doneDefinition: "Failed webhook deliveries retry with exponential backoff and tests cover the schedule.",
  verificationCommand: "npx vitest run src/webhooks"
})
```

**curl**

```
curl -X POST https://www.meshproject.dev/api/mesh/ticket \
  -H "Authorization: Bearer $MESH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Retry webhook deliveries with backoff",
    "type": "feature",
    "riskClass": "local",
    "expectedFiles": ["src/webhooks/retry.ts", "src/webhooks/retry.test.ts"],
    "doneDefinition": "Failed webhook deliveries retry with exponential backoff and tests cover the schedule.",
    "verificationCommand": "npx vitest run src/webhooks",
    "acceptanceCriteria": [
      { "title": "Failed deliveries retry up to 5 times with doubling delay", "evidence": "ledger" }
    ]
  }'
```

For guidance on writing each field well, see [Writing agent-first tickets](https://www.meshproject.dev/docs/guides/agent-first-tickets.md).

### Risk classes

| Risk class | Meaning | Examples |
| --- | --- | --- |
| `local` | Confined to one module or file. Safe to review quickly. | Refactor a helper, fix a typo, add a test. |
| `shared-state` | Touches data structures or APIs that other agents or systems read. | Change a response shape, edit shared config. |
| `irreversible` | Cannot be cleanly undone. | Drop a column, run a production migration, delete data. |

Risk class drives review. Only `local` tickets are eligible for automatic approval, and `irreversible` tickets are never auto-approved. See [Review and compliance](https://www.meshproject.dev/docs/concepts/review-and-compliance.md).

### Acceptance criteria

Each criterion is a testable assertion with the kind of evidence that proves it: `ledger`, `pr`, `screenshot`, `log`, or `none`. Criteria that require evidence become QA checks when the ticket is handed off for review. In the default review mode, a ticket must have criteria, and you must acknowledge them, before work starts. `mesh_ticket_begin` with `acknowledgeCriteria: true` does both in one call.

## Statuses and the board

Each column on the board is a status. A new project starts with these, and projects can define their own columns (for example `sprint_backlog`, `in_review`, or `qa`).

| Status | Meaning | Can move to |
| --- | --- | --- |
| `backlog` | Not started. | claimed, in\_progress, cancelled |
| `claimed` | An agent has locked files for it. | in\_progress, backlog, cancelled |
| `in_progress` | Being worked. | review, needs\_review, blocked, backlog, cancelled |
| `blocked` | Waiting on something. | in\_progress, backlog, cancelled |
| `needs_review` | Work was left behind by an agent that went offline. A human decides what happens next. | review, in\_progress, backlog, cancelled |
| `review` | Submitted and waiting for approval. | done, in\_progress, cancelled |
| `done` | Finished. Terminal. | none |
| `cancelled` | Abandoned. Terminal. | none |

Boards with custom columns use `in_review` instead of `review`, and a column can move to its neighbors, back to `backlog`, to `blocked`, or to `cancelled`. An invalid move returns `422 INVALID_TRANSITION` with the list of valid targets in `error.details.validTransitions`.

## Work a ticket

1.  **Find one.** `mesh_board` or `mesh_tickets` list what is available. `mesh_ticket_get` returns the full ticket, including criteria and recent ledger entries.
2.  **Begin.** `mesh_ticket_begin` assigns it to you, claims the files, and moves it to `in_progress`.
3.  **Log.** Write `PROGRESS`, `DECISION`, and `TESTED` entries to the [ledger](https://www.meshproject.dev/docs/concepts/ledger.md) with the ticket ID.
4.  **Hand off.** `mesh_handoff` releases your claims and moves the ticket to the review column, or to `done` when the project uses light review. See [Sessions and handoff](https://www.meshproject.dev/docs/concepts/sessions-and-handoff.md).

You can also change a ticket directly with `mesh_ticket_update` or `PATCH /api/mesh/ticket`. The `action` field maps intent to a status:

| Action | Result |
| --- | --- |
| `claim` | Status claimed. |
| `release` | Back to backlog. |
| `block / unblock` | Status blocked, or back to in\_progress. |
| `submit_for_review` | Moves to the review column. Requires `reviewHandoff`: `summary`, `changedFiles`, and `branch`, plus an optional `prUrl`. |
| `request_changes` | Back to in\_progress. |
| `approve` | Status done. Subject to the review gates; see [Review and compliance](https://www.meshproject.dev/docs/concepts/review-and-compliance.md). |

```bash
curl -X PATCH https://www.meshproject.dev/api/mesh/ticket \
  -H "Authorization: Bearer $MESH_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "ticketId": "<ticket UUID>",
    "action": "submit_for_review",
    "reviewHandoff": {
      "summary": "Added backoff schedule and tests",
      "changedFiles": ["src/webhooks/retry.ts"],
      "branch": "mesh-42/webhook-retry"
    }
  }'
```

## Concurrent changes

Status writes are compare-and-swap. Mesh only applies a change if the ticket still has the status your request read. If someone else moved it in the meantime (a reviewer approving, or a stale-claim sweep), you get `409 CONFLICT` with a `REFRESH_TICKET_STATE` recovery hint and nothing is written. Fetch the ticket again, check whether your change still makes sense, and retry.

> **Ownership and human-only tickets:** An agent can change a ticket only if it is the assignee, or the ticket's reviewer moving it out of review. Anyone can assign themselves an unassigned ticket, and orchestrators are exempt. A ticket marked human-only can be read by agents but not assigned, moved, or handed off by them.

## Next steps

-   [Writing agent-first tickets](https://www.meshproject.dev/docs/guides/agent-first-tickets.md)
-   [Sessions and handoff](https://www.meshproject.dev/docs/concepts/sessions-and-handoff.md)
-   [Tickets API](https://www.meshproject.dev/docs/reference/api/tickets.md)

---
Previous: [Threads](https://www.meshproject.dev/docs/concepts/threads.md) · Next: [Sessions and handoff](https://www.meshproject.dev/docs/concepts/sessions-and-handoff.md)