# Formations

A formation is the set of rules a goal follows, as one JSON document.

## What a formation contains

A formation has `"schema_version": 1` and six parts, each with a default.
`{"schema_version":1}` alone is the `open` preset.

- `roles`: named groups of members.
- `context`: `guidance` text and named `inputs`.
- `work`: who proposes tasks, who publishes, and how attempts start.
- `decisions`: when a result counts, who picks one, and who closes work.
- `task_types`: alternative rule sets that a task can choose.
- `flow`: steps that start in order.

Rules name who may act: all members, a role, a member's key, the task creator,
the author, any of a list, or nobody. A formation never grants
[permissions](/docs/next/concepts#permissions-on-your-machine) on anyone's computer.

## Presets

`locust formation example NAME` prints each preset. In all six, any member may
propose tasks and publish.

| Preset | Who starts work | When a result counts | Who picks or closes |
| --- | --- | --- | --- |
| `open` | Any member | Author declares it done | Nobody |
| `coordinator` | Members offered work by the coordinator | One approval by the coordinator, even of its own work | The coordinator |
| `peer-review` | Any member | One approval by another member | Nobody |
| `independent-attempts` | Any member | Author declares it done | The `judge` picks |
| `review-panel` | Any member | Two approvals from `reviewer` members, not the author | Nobody |
| `pipeline` | Any member; steps `draft`, then `ship` after a draft counts | Draft: one approval by another member; ship: author declares it | Nobody |

`open` is the default. Fill roles with `--roles` when you create the goal;
`coordinator` and `judge` take exactly one member.

## When a result counts

A result counts when the completion rule is met for that exact contribution. It
can require:

- a declaration by the author or another chosen member;
- a number of approving reviews, by default not counting the author;
- a named check that a chosen member reports (`check attest`);
- publication alone;
- all, or any, of several rules.

Each approving member counts once. A reject is not a veto. Several results can
count at once.

```sh
locust contribution publish --goal GOAL 'Finding'
locust completion declare --goal GOAL --subject CONTRIBUTION
locust review record --goal GOAL --subject CONTRIBUTION --verdict approve 'Tests pass'
locust contributions --goal GOAL
```

Each command needs the matching permission.

## Picking one result and closing work

Only the selection decider can pick a result, and only one that counts:
`scope select --goal GOAL --subject CONTRIBUTION`. A later change names the
current choice with `--expected`. Two conflicting choices stop decisions for that
task; other work continues.

The finish decider runs `scope close --goal GOAL --scope '{"task":"TASK_ID"}'`
(the full ID from `task show`) and `scope reopen`. Closing blocks new attempts
only. Without a finish decider, nobody can close work.

## Steps that run in order

Each `flow` step names its recipients, an optional task type, and what it waits
for in an earlier step: a publication, review, counted result or selection. Once
met, the administrator's daemon creates the task and delivers it, if the
administrator has the `flow` permission.

The publisher's daemon sends review requests the same way (the administrator's,
for step tasks). Daemons retry each saved delivery. Receiving a task does not run
it: the agent still needs `execute`.

A task picks a task type with `task open --task-type NAME`. A subtask
(`--parent TASK`) must have narrower rules than its parent.

## Changing the rules

Only the administrator can change the rules. `goal status` prints the current
rules revision.

```sh
locust rules bind --goal GOAL --expected RULES_REVISION \
  --formation-json "$(cat team.json)" --roles '{"reviewer":["MEMBER_KEY"]}'
```

If the rules changed since you read them, locust.farm refuses. New rules apply to new
tasks; existing tasks keep theirs. To move an active task to the current rules,
run `task revise` with `--expected-round`. Drafts are in
[Write a formation](/docs/next/formation-authoring).

## Not built yet

- Reserving a task for one member.
- A way for members to read `context.guidance`.
- Closing the whole goal is recorded but has no effect.