# Labels

Issue labels help FJX govern workflow state.  Create these three at the **organization level** so that every repo inherits them:

1. lifecycle: `agent/*`
1. work type: `type/*`
1. risk: `risk/*`

## Required: Agent Lifecycle

The `agent/*` set drives the state machine. These are the only labels FJX actively relies on. Create them as **exclusive** so only one `agent/*` can be applied at a time — the state machine is single-state by design.

| Label            | Meaning                              |
| ---------------  | ------------------------------------ |
| `agent/new`      | Awaiting PM triage.                  |
| `agent/working`  | Working agent has claimed the issue. |
| `agent/review`   | Work is handed off — to PM, to QA.   |
| `agent/blocked`  | Human intervention required.         |

**Dispatch is by assignment, not label.** The label says "what state is this in." The assignee says "who runs next." See the [state diagram](./#state-diagram) for the full transitions and the [agents](../agents/) for who reads which label when.

**Phase lives in the brief, not in labels.** A dev cycle in the `propose` phase and one in the `apply` phase both carry `agent/working`; the PM brief distinguishes them. Don't reach for `agent/propose` or `agent/apply` labels — they're not part of the model.

## Required: Work Type

Helps the PM give DEV & QA appropriate context & prompts.

| Label           |  Meaning                                 |
| --------------- |  --------------------------------------- |
| `type/bug`      |  Bug fixex                               |
| `type/chore`    |  Maintenance & simple features           |
| `type/feature`  |  New functionality that warrants a spec  |
| `type/security` |  ??? |

## Recommended: Risk

Risk and workflow phase are independent axes — a `simple`-phase change can still be `risk/high` (see [Scenario 2: bump dependencies](../scenarios.md)). PM uses risk to shape the brief; humans use it to decide where to look closely.

| Label         | Meaning                   |
| ------------- | ------------------------- |
| `risk/low`    | Safe, can auto-run        |
| `risk/medium` | Basic validation suffices |
| `risk/high`   | Warrants extra validation |

## Recommended: Complexity

This label can help choose an appropriate agent (eg jr vs sr dev) or level of effort (eg simple qa vs penetration testing).

| Label             | Meaning                                          |
| -------------     | ------------------------------------------------ |
| `complexity/low`  | Consider cheaper model, less thorough validation |
| `complexity/high` | Justifies more spend on model & validation       |

## Optional: Domain labels

`area/*`, `kind/*`, `pri/*` — anything your team finds useful. FJX is neutral on these; apply your existing conventions.

## Creating the label set

Two reasonable paths:

1. **Forgejo UI** — `<org>/-/labels` → New label. Apply the table above, set the four `agent/*` as exclusive. One-time setup, takes a few minutes.
2. **`fjx label list`** — populates the cache from existing labels; useful for verifying a fresh org's setup is complete before pointing agents at it.

Per-repo, no further label work is needed — org labels are inherited automatically.

## When labels and reality drift

Working agents are allowed (and expected) to fix label state when it disagrees with what they observe:

- A claimed issue without `agent/working` → add `agent/working`.
- A handed-off issue still wearing `agent/working` → strip and add `agent/review`.
- An `agent/blocked` issue that no longer has the underlying blocker → strip `agent/blocked` (this is normally a PM `/unblock`, but a working agent picking up a stale blocker can clear it with a ledger note).

PM does **not** police label state. It applies labels under the [`/<command>` vocabulary](./slash-commands/) and trigger conditions; everything else is the working agent's surface.