Key concepts - OuterLayer

Everything in OuterLayer hangs off a work item. An issue becomes a work item when it is added to a factory’s Work page. Sessions, pull requests, checks and reviews all attach to the item, not to each other. Because checks attach to the item, a check still counts when one pull request is closed and another opens in its place.

Where work lives

Term	What it is
Organization	Your company’s account. It holds members, roles and billing, and one or more factories.
Factory	One team’s unit of work: its Work page, repositories, keys and policy. `appId` in config files and the API is the factory’s id.
Work page	The factory’s list of work items.
Work item	An issue added to the Work page. It gets a number of its own on the factory: issue 42 might be item 7. Commands and `OUTERLAYER_WORK` take the item number, never the issue number.
Item page	One work item’s page. Its tabs are Activity, Criteria, Findings and Checks, with the item’s sessions and pull requests beside them. See Review and merge.
Context source	One repository that supplies agent instructions and policy to the factory’s other repositories. CLI commands and messages call it the control plane. See Share instructions across repositories.

Who does the work

Term	What it is
Session	One run of a coding agent. It uploads only when it was started with `OUTERLAYER_WORK` set to an item number. See Launch a session.
Build	One attempt to turn an item into a pull request, either on a host or in a session you start yourself.
Host	A machine running `outerlayer runner` for the factory. It takes the items queued with Build. See Run work on your machines.
Runner	The `outerlayer runner` process on a host.
Claim	The hold a host, or a person’s session, has on an item while it works on it. While it lasts, no host starts the item. It expires unless it is renewed, so a stopped machine never holds an item for long.
Lease	The name error codes, flags and the CLI use for a claim. A session’s lease lasts 20 minutes, and its hooks renew it while the session works. A host renews its own while the build runs.
Item key	The key a host’s build uses in place of the runner’s key. It acts only on the claimed item and stops working when the claim ends. See Item key.
Pull request	Joins an item when a session on that item declares it. See Declare a pull request.

How the work is judged

Term	What it is
Policy	`.outerlayer/policy.yaml`, read from each pull request’s base branch. It says which checks run and whether a failing one blocks the merge. See Policy and validators.
Validator	A file in `.outerlayer/validators/` that declares one check: its name, the sentence it shows, and what satisfies it.
Check	One named pass or fail on the item, such as “a code review report is attached”. A check holds across every pull request the item has. The item page’s Checks tab lists them.
Evidence rows	The item’s checks, one row each. They show on the item page’s Checks tab. When Post session summaries on pull requests is on, they also appear in the evidence comment on each pull request.
Acceptance criteria	The list of what the item must do. The item page’s Criteria tab shows the list recorded with `outerlayer emit criteria`. A criterion missing its declared proof flags the verdict.
Artifact	A file attached as proof. Its file type sets its kind: a screenshot, a video, a report, a log, a test result, or a plain file. See Attach evidence.
Review	A person’s pass or fail on the whole item. A review is not a check. Only a person records one, on the item page or with `outerlayer work comment --pass` or `--fail`. See Review and merge.
Finding	A problem an agent hit in the factory while it worked, such as a flaky test or a wrong instruction. Findings never affect whether the work passes.

Where an item stands

Every item has one status that says whose turn it is, from Not started to Done. The list of statuses and what each means is on Review and merge.