# Onus

> Onus turns a pull request into a short report of changes in meaning.

## The map for coding agents (MCP)

URL: https://onushq.com/docs/agents

The map for coding agents: onus mcp, its tools, many agents and worktrees


<!-- Generated by npm run docs:sync from crates/onus-cli/guide/agents.md in onushq/onus; edit it there. -->

# The map for coding agents (MCP)

`onus mcp` gives a coding agent the codebase map as MCP tools: where things are, what depends on what, which tests cover what, who owns it, and what a change means before it is committed. Every answer is computed from the code, never generated, and carries the file and line it comes from.

It also lets the agent hand its work in the way Onus expects: run the tests in an environment, submit the change with that evidence, see its lane and the judge's verdict, and ask for more access with evidence instead of working around its token. Nothing it offers lets an agent approve itself.

**What helps agents today is `onus_check`.** We tested whether the map makes coding agents faster or more correct when they implement a feature ([evaluation](https://github.com/onushq/onus/blob/main/docs/evaluation/2026-10-07-map-for-agents.md)). It did not, measurably: agents found code with text search just as well and rarely called the navigation tools. They did call `onus_check` before finishing, and Phase 2 now focuses on making it precise. The navigation tools below are experimental.

## Connect an agent

Claude Code:

```text
claude mcp add onus -- onus mcp
```

Any MCP client that starts servers over stdio: run `onus mcp` in the repository (or pass `--repo <worktree>`). The map is the map of the worktree the server is started in, as it is on disk now, saved but not committed changes included.

Clients that connect over HTTP (streamable HTTP): run `onus mcp --http 127.0.0.1:8765` and point the client at `http://127.0.0.1:8765/`. Only requests naming a loopback host are answered, which keeps other machines and DNS rebinding out; `--allow-host <name>` adds a host for a network you trust. The tools describe your code and can run containers, and there is no authentication. Every tool answers the same over stdio and HTTP, and to every client.

## Tools

The check:

- `onus_check`: the changes in meaning between a commit (default `HEAD`) and the worktree now, as the same rows as a pull request report, preceded by a short checklist of what to verify before finishing: third-party APIs the repository has never used (with the pinned version), implementations and test doubles of a changed interface that were not updated, committed secrets and broken boundary rules. Run it before finishing a task.
- `onus_impact`: before a change, what breaks if a symbol, file or component is removed, renamed, changes its signature, gains a required member, or only changes behavior. One site per file (file, line, how it is used; for a new required member only the implementations, found in the source text), the tests that exercise it, and what static analysis cannot see.
- `onus_invariants`: the invariants onus.yaml declares for a symbol, file or component, or all of them: rules a change must keep.

Navigation (experimental):

- `onus_status`: what the map holds (components, files, symbols, edges, tests, and coverage with its notes when `tests.coverage` names files). Start here.
- `onus_find`: symbols by name words, ranked by how many words match in the name, then in fields and parameters, then in the file path (`format phone` finds `formatPhoneNumber`; a field name finds the types that declare it). Every answer also lists matching files.
- `onus_symbol`: one symbol: kind, location, contract shape, declared invariants, how many places use it.
- `onus_dependents`: what depends on a symbol, file or component, up to `depth` steps (imports, calls, type references). Use it before changing something.
- `onus_dependencies`: what a symbol, file or component depends on: code, external services, events, tables, config keys.
- `onus_tests_for`: the test files that exercise a symbol, file or component, strongest link first. Each says how the link is known: `ran` (coverage shows this test running it), `static-ran` (the test refers to it and the measured run executed it), `static` (it refers to it; no coverage was given), `static-not-run` (it refers to it, but the measured run never executed it). When the coverage measured the target's file, `coverage` gives its executable and ran lines; no tests with lines that ran means the target ran through other code. Coverage comes from the files `tests.coverage` in onus.yaml names ([`onus help configuration`](/docs/configuration)).
- `onus_owners`: owners and sensitivity labels.
- `onus_component`: a component's public surface, the components it uses and that use it, its external services and events.
- `onus_file`: a file's symbols, imports and importers.

Handing work in (leave these out with `onus mcp --no-actions`):

- `onus_lanes`: the lane policy: what merges on its own, what goes to the judge or a person, and the floors no policy can lower. It says whether held-out checks are configured, never what they run.
- `onus_env_create`, `onus_env_run`, `onus_envs`, `onus_env_destroy`: an environment built from a commit, and commands run in it. Each run is recorded as evidence (output, JUnit results, traces, coverage) under a run id. See [`onus help environments`](/docs/environments).
- `onus_evidence`: recorded runs, a run's manifest, or one of its artifacts.
- `onus_run_test`: a test command once in a throwaway container, to reproduce a failure; nothing is recorded.
- `onus_submit`: hands in a committed change with an intent, run ids as evidence and the ids of escalations granted during the task. Onus reports it, attaches the scope of the server's task token, classifies it, and keeps it in `.onus/submissions/` where people see it in `onus ui`. Returns the lane, every reason, and a submission id.
- `onus_judge`: the verifying judge on a submission: evidence re-run in fresh containers, intent, contracts, tests, held-out checks, stopping at the first failure. The verdict is kept beside the submission. Held-out checks come from the suite `onus mcp --held-out` was given; the agent sees only how many ran and passed, and not which configuration from `lanes.judges` judged.
- `onus_escalate`, `onus_escalation`: ask for rights the token lacks, with evidence, and check the answer (`wait` waits up to 50 seconds for it). A granted request returns the new token, the old rights plus exactly what was asked, and the server uses it from then on. The granted token names its request, so it proves the grant wherever the person's decision was logged. Where a request goes is in [`onus help scopes`](/docs/scopes).
- `onus_blocked`: the safe exit. A test the agent did not write fails and cannot be fixed in scope, the spec contradicts itself or the code, or the task cannot be done as asked: the agent reports it with evidence (`kind` `broken-test`, `contradictory-spec` or `impossible-task`) and stops. It is filed like an escalation that asks for no rights, routed to the owners of the code involved, and listed even when the CLI is signed out. A person answers it; the agent reads the answer with `onus_escalation` (state `answered`).
- `onus_outcomes`: track records and the held-out backlog, read-only.

Onus Cloud (listed only when the CLI is signed in with `onus login`, `ONUS_CLOUD_TOKEN` or `ONUS_API_KEY`; see [`onus help cloud`](/docs/cloud)):

- `onus_cloud_env_create`, `onus_cloud_env_run`, `onus_cloud_envs`, `onus_cloud_env_destroy`: environments built and run on Onus Cloud's machines from a pushed commit, each run recorded by Onus Cloud.
- `onus_cloud_attach_evidence`: a recorded run to a pull request, for the judge; with `doorLog: true`, the task's slice of the door log too, cut by the server from its own log, for the change's provenance.
- `onus_cloud_status`, `onus_cloud_pulls`, `onus_cloud_pull`: who the CLI is and what its plan allows; governed pull requests, their lanes and evidence.
- `onus_cloud_map`: the map tools' questions (`{"query": "dependents", "target": …}`) asked of the map Onus Cloud keeps at a commit or a pull request's head, answered here and filtered to the token's read scope.
- `onus_cloud_token`: a narrower Onus Cloud token for a sub-agent: only the scopes and repositories named, never more than the server's, ending within 24 hours.

A server signed in with a login never sends the login with an agent's call: it mints a scoped token for the worktree's repository on first use and uses that. The flags:

- `--key <file>`: the root private key, held by the server and never shown to the agent. With it, grants decided by policy, or by a person in Onus Cloud, are minted by the server. Needs `--token`.
- `--trusted-repo <dir>`: a checkout whose files the agent cannot edit, such as a `git worktree` of the default branch outside the agent's. Signed out, with `--key`, the policy decides escalations from its map and onus.yaml. Without it, a person does. Needs `--key`.
- `--cloud-token <token>` (`ONUS_CLOUD_TOKEN`): a scoped Onus Cloud token to use as it is.
- `--cloud-repo <owner/name>` (`ONUS_CLOUD_REPO`): the repository in Onus Cloud, when the worktree's remote is not GitHub. Under a task token, calls that name a repository are checked against it.
- `--cloud-ttl <duration>`: how long the token minted from a login lasts (default `8h`, at most `24h`).

The order an agent should follow is in the server's instructions: commit, run the tests with `onus_env_create` and `onus_env_run`, `onus_submit` with an intent and those runs, then `onus_judge`.

What agents cannot do through MCP: record outcomes, grant or deny escalations, mint or widen task tokens, widen an Onus Cloud token, or choose the scope a submission is checked against. With `--token`, submissions, environments (their hosts and secrets) and escalations use the server's task token, whatever the agent asks for.

Every call is checked at the door and logged. With `--token`, each tool first checks the token: its signature when the server starts, its expiry on every call, then the tool's own rule. A refused call says which right is missing and how to ask for it:

```yaml
denied: `net:host:evil.example` is not in the token of task `sms-alerts`.
Your net rights: `net:host:sms.test.example`.
To get it: onus_escalate with scopes ["net:host:evil.example"] and evidence (a failing test is strongest).
```

- Environments belong to the task that made them. Another task cannot run commands in one, destroy it, read its runs or see it in `onus_envs`; a run used as evidence must come from the task's own environments. An environment whose hosts or secrets the token no longer allows must be made again.
- `onus_run_test` takes no `setup` under a token: setup runs with open network, and the token decides the network. Use `onus_env_create`.
- `onus_submit` takes `escalations`: ids from `onus_escalate`. Each must be granted, for the task, with a token signed by the root key, minted for that request, that holds exactly what was asked; otherwise the submission is refused with the reason. `onus submit --escalation` and `onus ui` check the same.
- A grant is minted from the first block of a token, so it drops any narrowing (`onus token attenuate`). A server whose token was narrowed for a sub-agent does not take up such a grant, and does not hand it out; the person narrows the granted token the same way and restarts the server with it.
- A task plan can name the agent (`agent: {tool: claude-code, model: opus}`). The token then carries it, and submissions and log entries made under the token use it; what the agent declares (`agent_tool`, …) is ignored, and the answer says so.
- Hosted environments and runs (`onus_cloud_*`) are checked the same way, from the log of what the task made. A pull request or a list of them is this worktree's repository: `onus_cloud_pulls` without `repository` lists only its pull requests. An environment made without `hosts` has no network.
- A tool with no rule is closed to a token.

Every call, with or without a token, is written to the audit log: the tool, a digest and a shortened copy of its arguments, the token's task and id (never the token), the agent and where its identity came from, the decision (`allowed` or `denied`, then `done` or `failed` for tools that act) and the reason. The log is `.onus/audit.jsonl` in the worktree, which `onus ui` shows; the server adds it to the repository's own `.git/info/exclude`, so `git add -A` does not commit it. `onus mcp --audit <file>` puts it where the agent cannot write. When the log cannot be written, the call is refused. Without a token nothing is refused, and calls are logged as `local`. See [`onus help scopes`](/docs/scopes).

Targets can be a symbol id (`billing:src/payments.ts#chargeCard`), a bare symbol name, a file path, a module id or a component id. Answers are JSON, sorted, and limited (default 50 items, `limit` up to 500); `truncated` says when there is more. Each answer also says which version of the map it came from and whether the map was rebuilt for it.

The same questions work from a shell, with the same answers:

```sh
onus query status
onus query find format phone
onus query dependents UserPreferences --depth 2
onus query tests-for services/billing/src/payments.ts
onus query impact UserPreferences --change add-required-member
onus query invariants
onus query overview
onus query check --base main
```

## Many agents, many worktrees

Agents often work in parallel, each in its own git worktree of one repository. Onus is built for that:

- **One server per repository.** Every `onus mcp` and `onus query` of a repository talks to one map server over a private Unix socket, and starts it if it is not running. Ten agents in a worktree share one map and one rebuild.
- **One map per worktree, kept current.** The server watches each worktree's files. A change marks the map stale; the next question rebuilds it once, however many agents are asking, and questions between changes are answered from memory in about a millisecond.
- **Facts shared across worktrees.** Parsing a file is most of the work, and worktrees share almost all of their files. The server keeps each file's facts by content, in memory and in the repository's git folder (`.git/onus/facts`), so a second worktree, a rebuild after an edit, or a restarted server parses only files whose content is new.
- **Checks reuse base commits.** `onus_check` keeps the extracted base commit and its map, so agents checking against the same commit pay for it once.

Measured on Twenty, an open-source TypeScript monorepo with 31,000 source files, 72,000 symbols and 272,000 edges (Apple M-series laptop):

| | Time |
|---|---|
| A question to a warm map (MCP tool call) | under 1 ms; `onus_find` about 30 ms |
| The same from `onus query` (a new process each time) | 20–50 ms |
| First question in a repository (full build) | 4.8 s |
| First question in a second worktree | 1.9 s |
| First question after an agent edits a file | 2.0 s |
| Eight agents asking at once after an edit | 1.7 s, one rebuild |
| `onus_check` against a commit already checked | 2.4 s |

The server exits after 30 minutes without questions. `onus query stats` shows its worktrees and cache use; `--no-server` builds the map in the calling process instead (the only mode on Windows).

## What it reads and runs

The same as every other command: the files of the worktree and, for `onus_check`, the base commit through `git archive`. Nothing from the repository is executed, the server only listens on a socket readable by your user, and no plugins are loaded.


---

## Kinds of change

URL: https://onushq.com/docs/changes

Every kind and subkind of change Onus reports


<!-- Generated by npm run docs:sync from crates/onus-cli/guide/changes.md in onushq/onus; edit it there. -->

# Kinds of change

Every row has a **kind** (one of seven), a **subkind** (the specific change) and a **level** (relationship, behavior or structure). The Kind column of the Markdown report shows a short label; the JSON has `kind` and `subkind`.

| Kind | Meaning |
|---|---|
| security-sensitive | Data leaves the system in a new way, a secret was committed, authentication or authorization code changed, a new HTTP route or public API operation appeared, or code in a sensitive component changed how it decides or writes. Always needs a person. |
| breaking | Callers or consumers outside this change may break: a contract lost something or changed in a way Onus cannot prove compatible and some user was not updated, an API operation or route was removed, or a boundary rule was broken. Always needs a person. |
| dependency | Third-party code changed: a new, upgraded or removed npm package, a lockfile, or a patched package (which needs a person). |
| config | Configuration changed. CI, policies, onus.yaml and CODEOWNERS are also rules of the game. Migrations, root build config and infrastructure need a person. |
| additive | Something new that existing callers do not notice: an optional field, a new export, a new event consumer, a new read; also a contract change whose users were all updated in the same change. |
| test | Tests were weakened (rules of the game), removed together with the code they tested, or edited to match behavior that changed (`--behavior`). |
| internal | Everything else, collapsed into one row per component, plus renames, generated code and notable edits outside sensitive components. |

"Sensitive component" means a component with a label of medium or high sensitivity in onus.yaml; `payments`, `auth` and `pii` are high unless onus.yaml says otherwise.

## Relationships between components, data and the outside world

These are compared per component, so moving code around inside a component never looks like a new relationship.

| Subkind | Kind | When |
|---|---|---|
| new-external-service | security-sensitive | A component starts calling an external service that is new to the repository, or that sends a kind of data (phone numbers, email addresses, payment details, ...) the component never sent before. Its novelty lists `new-vendor:<vendor>` and `new-data-egress:<kind>`. A new npm package that is the service's SDK is folded into this row (`new-dependency:<package>`, and `new-package:<package>` when no other component used it). |
| new-external-call | additive | A component starts calling a service another component already uses, sending nothing new. |
| external-service-removed | internal | A component stops calling a service. |
| new-event-consumer | additive | A component starts subscribing to an event. The row says whether the publishers also changed; with no publisher in the map it is low confidence. |
| new-event-publisher | additive | A component starts publishing an event; the row names the components that consume it. |
| event-consumer-removed | breaking | A component stops subscribing to an event. |
| event-publisher-removed | breaking | A component stops publishing an event others still consume (internal when nobody consumes it). |
| new-data-write | security-sensitive or additive | A component starts writing a table (Prisma). Security-sensitive in a sensitive component. |
| new-data-read | additive | A component starts reading a table. |
| data-write-removed, data-read-removed | internal | A component stops writing or reading a table. |
| new-cross-component-dependency | additive | A component starts depending on another component's code. The row names what it uses, and says so when that is internal to the other component. |
| rule-violation | breaking | A declared boundary rule is broken by a new reference (see [`onus help configuration`](/docs/configuration)). Rules of the game. Not reported when the same violation existed before. |

## Contracts

Contracts are the public symbols of a component: everything reachable from its entrypoint through exports and re-exports. Shapes come from the declared types; a type that is inferred rather than written is "unverified".

| Subkind | Kind | When |
|---|---|---|
| contract-field-added-optional | additive | An optional field or member is added (`phoneVerified?: boolean`). |
| contract-member-added | additive | An enum member or a class method or property is added. |
| contract-param-added-optional | additive | An optional or rest parameter is added. |
| contract-param-now-optional | additive | A required parameter becomes optional. |
| contract-key-added | additive | A public value without a type annotation gains a key: its initializer is an object literal, or a call such as `Schema.struct({...})` or `z.object({...})`, and the object gains a key. |
| contract-type-widened | additive | A field, method or result type changes only by gaining optional parameters or optional fields (`(p: string) => R` becomes `(p: string, opts?: O) => R`); callers and implementations keep compiling. |
| contract-union-widened | additive | A union type accepts more members (`'A' \| 'B'` becomes `'A' \| 'B' \| 'C'`). |
| export-added | additive | A symbol becomes public. Several new exports of one component are one row. |
| contract-field-added-required | breaking | A required field or method is added to an interface or type, and an implementation outside this change was not updated. |
| contract-field-removed | breaking | A field, member or method is removed. |
| contract-field-now-required | breaking | An optional field becomes required. |
| contract-field-now-optional | breaking | A required field becomes optional: readers may now get `undefined`. |
| contract-field-now-readonly | breaking | A field becomes readonly. |
| contract-param-added-required | breaking | A required parameter is added. |
| contract-param-removed | breaking | A parameter is removed. |
| contract-param-now-required | breaking | An optional parameter becomes required. |
| export-removed | breaking | A public symbol is removed or no longer exported. |
| contract-key-removed | breaking | A public value without a type annotation loses a key of its initializer. |
| contract-union-narrowed | breaking | A union type no longer accepts some members. |
| contract-changed-unverified | breaking | A type changed in a way Onus cannot prove compatible: a parameter, return, field or key type, or type parameters. Types are compared with object members and union members sorted, so reordering (as generators do) is no change. |
| contract-inferred-changed | internal | Public symbols whose types are inferred, not written, changed their bodies, and Onus has nothing to compare. One row for all of them, low confidence. |

A contract change is breaking only when something outside the change can break: a file that uses the symbol and was not changed, or, for a new required member, an implementation that was not changed (code that only reads the type is unaffected). Breaking rows name those files, test files first. Implementations are found by how they are written: `implements X`, `satisfies X`, `: X = {...}`, a function declared to return `X`, and Effect's `Layer.succeed(X, ...)` and `X.of({...})`. A cast (`as X`) is not an implementation: it compiles whatever members `X` gains.

When every user was updated in the same change, or nothing outside it uses the symbol, the row keeps its subkind but is additive ("Contract change, users updated" or "no users affected") and does not need a person. It stays breaking when Onus cannot see every user: the package is published (its package.json is not private and has `files` or `publishConfig`), or some imports of it could not be resolved.

Renaming a parameter is not a contract change. When a contract declared in onus.yaml has invariants, the row repeats them.

A contract declared in onus.yaml is a rule of the game. When its code changes (it is added or removed, or the body, shape or value of it or one of its members differs; formatting, comments and moves do not count), every row about it is marked `rulesOfTheGame` and needs a person. When no row is about it, for example a body-only edit, Onus adds one:

| Subkind | Kind | When |
|---|---|---|
| declared-contract-edited | internal | The code of a contract declared in onus.yaml changed and no other row is about it. Rules of the game. |

## Renames and moves

| Subkind | Kind | When |
|---|---|---|
| rename | internal | A symbol is renamed with an identical body. The row counts the call sites and files updated. |
| rename-incomplete | breaking | The same, but some references still use the old name. |
| moved-between-components | internal or breaking | Symbols moved from one component to another: one row per pair of components ("17 symbols moved from `orders-core` to `billing-shared`"). Exported symbols edited while moving (same name and kind, most members in common) are included, and their contract changes are listed in the row; breaking when any of those changes is breaking. The row also says when the old component no longer exports them. |
| moved-incomplete | breaking | The same, but some references still point at the old place. |

A symbol or file that moved inside one component without other changes, and a file whose only changes are formatting, comments or import paths, is not a row: it is listed under "Structure only".

## Dependencies

| Subkind | Kind | When |
|---|---|---|
| new-dependency | dependency | A package.json gains a third-party package. Novelty `new-package:<name>` when no other component used it. A package new to the repository that several components add is one row, and new packages added to the same components share a row. |
| dependency-version-changed | dependency | A declared version range changed. |
| dependency-removed | dependency | A package is removed. |
| lockfile-changed | dependency | A lockfile changed while no manifest dependency did. The row lists the installed versions that change (read from pnpm-lock.yaml, package-lock.json and yarn.lock), or says that none do when only patch hashes, checksums or resolution changed. |
| dependency-patched | dependency | A patch of a third-party package is added, changed or removed (`patches/*.patch` for pnpm and patch-package, `.yarn/patches/`). The row names the package and the files the patch edits. Needs a person: installed code changes without a version change, and the patch stops applying when the version moves. |

Workspace packages (your own `@scope/...` packages) are not third-party: depending on one shows as a relationship between components.

| Subkind | Kind | When |
|---|---|---|
| external-api-first-use | internal | Production code uses an API of a package the repository already depends on (`Effect.retry` from `effect`) that no other code in the repository uses. The row names the version the repository pins, to check the API exists in it: code written from memory of another version often calls functions that are not there. Node's built-in modules and framework virtual modules (`$app/…`, `$env/…`) are left out, and an API counts as used when the repository already reaches it another way (`RawData` imported by name, `WebSocket.RawData` through the default import). |

## Risk classes

Some changes need a person whatever their size or shape, so they get their own row instead of disappearing into a component's changed lines. Onus finds them by fixed patterns in the changed files.

| Subkind | Kind | When |
|---|---|---|
| migration-changed | config | A database migration is added, edited or removed: versioned files in a `migrations`, `migration` or `migrate` folder, `*.migration.*`, Flyway `V1__name.sql`, Drizzle `drizzle/0001_name.sql`, Alembic versions, and versioned upgrade commands (`upgrade…/…command…<timestamp>…`). The row says what the migration does to stored data, read from its SQL and TypeORM calls (creates or drops tables, adds or drops columns, creates indexes, deletes or updates rows, grants), and mentions `ON DELETE CASCADE`. The `down` step is left out. Editing a migration that already ran is called out. Snapshots and journals the tool writes beside it (`drizzle/meta/`, Prisma's `migration_lock.toml`) are part of the migration, and other code in a migrations folder gets a row only when it touches stored data. |
| public-api-changed | security-sensitive, additive or breaking | GraphQL queries, mutations or subscriptions are added, removed or change their signature, in schema files (`.graphql`, `.gql`), `gql` templates or code-first resolvers (`@Query`, `@Mutation`, `@Subscription`). Operations that skip authentication (`@skipAuth`, `@Public()` and similar) get their own security-sensitive row. Always needs a person. |
| route-added | security-sensitive | New HTTP routes: SvelteKit `+server` files, Next.js `route` files and `pages/api`, and controller decorators (`@Controller('users')` with `@Get(':id')`). The row names the methods and paths, and the `cache-control` header the route sets. |
| route-removed | breaking | HTTP routes removed. |
| auth-code-changed | security-sensitive | Code changed in files whose names say they decide who may do what (`auth`, `permission`, `guard`, `policy`, `role`, `acl`, `jwt`, `oauth`, `password`, …, also in camelCase names). One row per component, even for a refactor. |

## Configuration and rules of the game

| Subkind | Kind | Rules of the game | Files |
|---|---|---|---|
| ci-changed | config | yes | .github/workflows/*, .gitlab-ci.yml, .circleci/, .buildkite/, Jenkinsfile |
| onus-config-changed | config | yes | onus.yaml (the report used the base version) |
| lanes-model-changed | config | yes | *lanes-model.json, the learned lane model (the lane used the base version) |
| onus-pack-changed | config | yes | a framework pack listed in onus.yaml (the report used the base version) |
| codeowners-changed | config | yes | CODEOWNERS |
| policy-changed | config | yes | *.rego, policy/, policies/ |
| test-config-changed | config | yes | jest, vitest, playwright, cypress, karma and mocha configs |
| repo-settings-changed | config | yes | anything else under .github/ |
| root-build-config-changed | config | needs a person | at the repository root: tsconfig*.json, babel config, nx.json, turbo.json, .npmrc, .nvmrc, .node-version, .tool-versions |
| infrastructure-changed | config | needs a person | Terraform (.tf, .tfvars, .hcl), Kubernetes manifests (YAML with `apiVersion` and `kind`, or YAML in k8s, helm, charts, deploy, manifests, infra folders), Chart.yaml, serverless, fly, vercel, netlify, render, wrangler, cdk, Pulumi and a root app.yaml |
| env-changed | config | no | .env* |
| container-changed | config | no | Dockerfile*, docker-compose*, compose.* |
| data-schema-changed | config | no | *.prisma |
| workspace-config-changed | config | no | pnpm-workspace.yaml, .yarnrc.yml, lerna.json |
| build-config-changed | config | no | tsconfig*.json, project.json, angular.json, ESLint, Prettier, Biome and SWC configs, and bundler, framework and codegen configs (vite, webpack, rollup, tsup, esbuild, svelte, next, nuxt, astro, babel, postcss, tailwind, codegen, …) |
| package-scripts-changed | config | no | package.json `scripts` |
| package-manifest-changed | config | no | other package.json fields (dependencies are reported as packages) |
| config-changed | config | no | other .yaml, .yml, .json, .toml, .ini and .properties files |

Rows for a changed config file name what changed: the top-level keys of JSON and YAML (with `compilerOptions` broken down in tsconfig files), and the instructions of a Dockerfile (`ENV BODY_SIZE_LIMIT`, the base image).

## Tests

| Subkind | Kind | When |
|---|---|---|
| test-weakened | test | One row per component when any of these happen: a test case is removed; a case has fewer assertions; a case gains `skip`, `only` or `todo`; expected values in assertions are edited; a test file is deleted; or source code starts comparing against a string literal that only the tests use. Rules of the game. |
| tests-removed-with-code | test | Removed test cases or assertions that used code this change deletes. They covered nothing that still exists, so they do not weaken the tests and do not need a person. |

A removed case that reappears among the change's new cases (the same body, or the same title in a file of the same name, as when tests move with their code) is neither. New test cases are not a row; the component's internal row counts them.

With `onus report --behavior`, the tests that reach the change also run at the base and at the head ([`onus help environments`](/docs/environments)). What they showed is one row per component, at confidence `traced`:

| Subkind | Kind | When |
|---|---|---|
| behavior-newly-failing | internal | A case passes at the base and fails at the head, and again when run once more; or a new case fails at the head. Needs a person, and blocks the change until one approves the row. |
| behavior-changed | test | The base version of a test the change edited fails against the head's code, while the head's version passes: the behavior it pinned changed, and the test was edited to match. Snapshot mismatches land here. Rules of the game. |
| behavior-newly-passing | internal | A case fails at the base and passes at the head. |
| behavior-output-changed | internal | A case fails at both, with a different message. |

## Notable edits inside functions

Found in functions and methods that exist on both sides. Security-sensitive in a sensitive component, internal otherwise. An await, guard or throw that the change adds to another function, as when a body is extracted into a helper, moved rather than disappeared, and is not reported.

| Subkind | When |
|---|---|
| boundary-condition-changed | A comparison flips with the same operands: `a > b` becomes `a >= b`. |
| condition-constant-changed | A comparison keeps its operator but compares against a different constant. |
| constant-changed | A `const` or variable initialized with a literal changes value: `LOYALTY_RATE` from 0.1 to 0.15. |
| guard-removed | A function has fewer early exits (`if (...) return/throw`) or fewer `throw`s. An edited guard is not a removed guard. |
| await-removed | A function awaits less, and a specific await disappeared. Awaiting calls together (`await Promise.all([...])`) is not a removal. |
| error-swallowed | A new empty `catch` block. |

## Secrets

| Subkind | Kind | When |
|---|---|---|
| secret-committed | security-sensitive | An added line matches a high-confidence pattern: AWS access key ID or secret access key, GitHub token, Stripe secret key, Slack token, Google API key, SendGrid API key, npm token, or a private key block. One row per file. The value is never printed, and it is redacted from the map too. |

## Everything else

| Subkind | Kind | When |
|---|---|---|
| internal-changes | internal | The changed lines of a component that no other row explains, with their count, labeled as code, tests or docs. In components with more than 300 files, the row also names the module folders that changed. |
| generated-code-changed | internal | Files written by a tool changed: found by folder (`generated`, `__generated__`, `codegen`), name (`.generated.`, `.gen.`, `_pb.`) or a marker in the first lines (`@generated`, `DO NOT EDIT`, "This file was generated"). One row per component that lists what the other rows would have said; review the schema or generator change it mirrors. |

## Grouped rows

To keep large changes readable, Onus merges rows that say the same thing:

- Several config files of one kind in one component are one row per kind of edit ("Build config: 3 files in `billing` change `module`").
- Packages already used elsewhere in the repository, dropped packages and version changes are one row per component ("2 npm packages already used in this repository added in `c`"). A package new to the repository always keeps its own row.
- When the same kind of config or dependency change appears in more than 5 components, it is one row for all of them, and config rows stay apart by the keys they change ("Build config changes `module` in 262 components (445 files)").
- When more than 10 components have internal changes, the 10 largest keep their rows and the rest are summarized in one ("1,490 changed lines inside 106 other components").
- Several new exports of one component are one row.

Grouped rows keep every file and line in their evidence.

## Hints on every row

- `labels`: sensitivity labels of the component.
- `blastRadius`: files in the new version (tests included) that depend on the subject, not counting the file that defines it.
- `novelty`: `new-vendor:<vendor>`, `new-data-egress:<kind>`, `new-dependency:<package>`, `new-package:<package>`, `secret`.
- `confidence`: `declared` (from onus.yaml), `compiler` (confirmed by a compiler, indexer or language server), `static` (read from the code), `inferred` (from conventions) or `low` (Onus could not resolve something).
- `rulesOfTheGame`, `intentMismatch`, `needsPerson`.
- `dependentComponents`: other components (not the row's own) that depend on what the row changed. For most rows that is the subject. For a component's internal row it is the functions and classes its changed lines are in, so a body-only edit of a widely used function counts its users. 0 for other rows about a whole component. `dependents` lists those components (absent when there are none).
- `tested`: for rows that change code, whether tests reach the files it changes: `tested` (a test exercises every changed file), `traced` (each changed file is tested or seen in a runtime trace) or `untested`. Absent for rows that change no code. It is per file, not line coverage.
- `owners`: the owners of the row's component, from onus.yaml or else CODEOWNERS; a row merged from several components has all of theirs. Absent when nobody owns it. Used to route a review ([`onus help ci`](/docs/ci)), not to rank.

The lane classifier reads these hints ([`onus help lanes`](/docs/lanes)).


---

## Running Onus in CI

URL: https://onushq.com/docs/ci

Running Onus on every pull request, and outcome records kept by CI


<!-- Generated by npm run docs:sync from crates/onus-cli/guide/ci.md in onushq/onus; edit it there. -->

# Running Onus in CI

Onus only reads the checked-out files, so it is safe on pull requests from forks with read-only permissions. The one thing it writes, with `records: true`, is its own `onus/records` branch.

## GitHub Actions

The Onus action downloads the release binary for the runner, checks its SHA-256, writes the report to the job summary and posts it as one pull request comment that is updated on each push:

```yaml
name: Onus
on: pull_request
permissions:
  contents: read
  pull-requests: write      # for the comment; leave it out to skip it
jobs:
  onus:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: onushq/onus/action@v0.11.0
        id: onus
        with:
          fail-on: rule-violation,secrets
      - uses: actions/upload-artifact@v7
        with:
          name: onus-report
          path: ${{ steps.onus.outputs.report }}
```

Inputs, all optional:

- `version`: the release to download, such as v0.1.0. Defaults to the tag the action is used at, otherwise the latest release.
- `onus-path`: use this binary instead of downloading one (for example one you built).
- `base`, `head`: the commits to compare. Default: the pull request's base and head commits.
- `intent`: `true` (the default) checks the change against an `onus-intent` block in the pull request body; `false` skips the check; a file path uses that file.
- `fail-on`: fail the job on `rule-violation`, `secrets`, `behavior` (with `behavior: true`), or several (comma separated). Default `none`.
- `comment`: `false` to only write the job summary.
- `config`: an onus.yaml to use for both commits.
- `lanes`: `true` to classify the change into a risk lane with the policy in onus.yaml and the hard floors, and show it in the comment ([`onus help lanes`](/docs/lanes)). Output `lane`.
- `apply-lane`: `true` (with `lanes`) to label the pull request `onus/lane:<lane>` and fail the job for the `blocked` lane. Needs `issues: write`.
- `wait-for-review`: `true` (the default, with `records`) fails the job while the change is in the human lane and no review counts yet. Output `review`: `waiting` or `approved`. See "Reviews in the human lane" below.
- `submission`: (with `records`) the agent's own submission of the change, for its provenance. When empty, one kept on the records branch is used. See "The agent's submission" below.
- `auto-merge`: `true` (with `lanes`) to enable GitHub's auto-merge (squash) for the `auto-merge` lane. Required checks still apply. Needs `contents: write`.
- `plugins`: a plugins file's contents (YAML), written outside the repository and passed with `--plugins`. For Svelte components: `plugins: [{ name: svelte, kind: language, command: [onus-plugin-svelte], files: ["**/*.svelte"] }]` (the plugin ships in every release archive).
- `working-directory`: the repository, if not the workspace root.
- `coverage`: coverage of the head commit (lcov, Cobertura XML or Istanbul JSON) written by an earlier step, as a glob. Passed only when the checkout is the head commit (see "Which changed lines tests ran" below).
- `behavior`: `true` to run the behavior diff (`onus report --behavior`): the tests that reach the change run at the base and at the head in containers, from `environment.behavior` in the base commit's onus.yaml ([`onus help environments`](/docs/environments)). GitHub's Linux runners have Docker. A binary without the flag skips it with a warning. `behavior-budget`: seconds for it (default: the config's, else 600). With `fail-on: behavior`, a test that passes at the base and fails at the head fails the job.
- `cache`: `true` (the default) keeps the base commit's map in the Actions cache, so later pushes to the same pull request skip mapping the base again. `false` maps it every time.
- `feedback`: `true` (the default) ends the comment with a line asking for a 👍 or 👎 reaction and for `/onus caught` replies (see below).
- `github-token`: the token for the download and the comment. Default: the workflow's token.

Outputs: `report` (path of the JSON report), `markdown` (path of the Markdown report), `meaning-changes` and `needs-attention` (counts from the report's summary), and `metrics` (one line of JSON: changed files and lines, rows, findings, the time the report took and, with coverage, `coverage: {changed, ran}`). With `records: true` also `lane`, `review` (`waiting` or `approved` in the human lane), `provenance`, `rollout-strategy` (`none`, `canary` or `flag`) and `rollout-plan` (the path of `rollout.json`), and with `rollout-percent`, `rollout-decision` (see "Rollouts" below).

Notes:

- The pull request body is passed through an environment variable, never pasted into a script, so a body cannot inject shell commands.
- The action compares the base and head commits, not branch names: on `pull_request`, the checkout is a merge commit. Commits missing from a shallow checkout are fetched.
- On pull requests from forks, GitHub gives the workflow a read-only token, so the action skips the comment and only writes the job summary.
- The comment starts with a hidden `<!-- onus-report -->` marker, which is how the action finds its own comment to update.
- The action runs on Linux (x86_64 and ARM64), macOS and Windows runners.

## Outcome records on every pull request

With `records: true`, the action keeps the track record lanes depend on without anyone typing an outcome. The records live on a branch of the repository, `onus/records` (input `records-branch`), as three files that only grow by whole lines: `pulls.jsonl` (what Onus knew about each pull request while it was open), `outcomes.jsonl` (what happened to it) and `signals.jsonl` (what production said: incidents, rollbacks, deploys, rollout stages and traces, [`onus help production`](/docs/production)). Nothing outside the repository is needed.

```text
name: Onus
on:
  pull_request:
    types: [opened, synchronize, reopened, edited, ready_for_review, closed]
  pull_request_review:
    types: [submitted, dismissed]
  issue_comment:
    types: [created]
  push:
    branches: [main]
permissions:
  contents: write           # the onus/records branch
  pull-requests: write      # the comment, and reading reviews
  actions: write            # re-running the check after /onus approve or an approval
jobs:
  onus:
    # Comments matter only when they are /onus commands on pull requests.
    if: >-
      github.event_name != 'issue_comment' ||
      (github.event.issue.pull_request && startsWith(github.event.comment.body, '/onus'))
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: onushq/onus/action@v0.11.0
        with:
          records: true
```

What happens on each event:

- **Opened or pushed:** the change is submitted with the report as its evidence, classified with the policy, the risk inputs (including the reverts and incidents of the components it touches, from this repository's records), the hard floors and its agent setup's record, and judged when the lane is `judge` and `judge: true`. The comment shows the lane, why, the agent setup's record and an `/onus approve` command for each row that needs a person. The latest classification is appended to `pulls.jsonl`, with the components the change touched, the change's features (what the learned lane model trains on), and the judge configuration and its verdict when the judge decided. With `lanes.learned`, the model is read from the base commit, and the comment shows its risk on a **Learned risk:** line ([`onus help lanes`](/docs/lanes)). The change's provenance record is written to `provenance.json` (output `provenance`; `onus help provenance`), and its rollout plan to `rollout.json` (outputs `rollout-strategy` and `rollout-plan`), which the comment shows on a **Rollout:** line ([`onus help production`](/docs/production)). Production traces kept in the records (`signals.jsonl`) are passed to `onus report --traces`, so the report's map includes the calls production observed.
- **A review is submitted or dismissed:** the same as a push. The lane, the comment and the check are worked out again with the reviews as they now stand (see "Reviews in the human lane" below).
- **Merged or closed:** the pull request's latest record becomes an outcome (`merged` or `closed`), with the commit it landed as, who merged it (`mergedBy`), the components it touched and its features. Running twice records it once. The provenance record is rebuilt from the records (output `provenance`); upload it with `actions/upload-artifact` to keep it.
- **A push to the default branch:** commits that revert a merged change (`This reverts commit …`) are recorded against it; a reverted change no longer counts toward its agent setup's record.
- **A `/onus` comment** from someone with write access (owner, member or collaborator); anyone else's is answered with a 😕 and ignored:

      /onus approve new-external-service:external:acme-sms@notifications
      /onus audit ok
      /onus audit miss the opt-out was ignored
      /onus incident SMS sent twice involved: notifications, notifications:src/sms.ts#sendSms

  `approve` records a person's approval of a row and re-runs the check, so the lane updates. `audit` records a human audit of a merged change, the miss rate that says whether the automatic lanes can be trusted, and clears the change from the audit queue (`onus outcomes audits`, [`onus help lanes`](/docs/lanes)). `incident` marks a merged change as having caused one, with the components and symbols involved: an agent setup with an incident among its last 20 changes cannot auto-merge, and `onus outcomes backlog` lists where incidents happen. The action reacts with 👍 and replies with what it recorded. `/onus accuracy` is answered the same way but records nothing (see "Accuracy checks" below). `/onus caught <what>` from someone with write access is recorded too, as `caught: true` on the change's outcome, or on its pull record while it is open: the learned lane model counts it as a problem, like an incident ([`onus help lanes`](/docs/lanes)).

### Rollouts

A deploy workflow reports each stage of a rollout, and Onus decides from the change's plan and the metric samples:

```yaml
on: deployment_status
jobs:
  rollout:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: ./scripts/canary-metrics.sh > "$RUNNER_TEMP/canary.json"
      - uses: onushq/onus/action@v0.11.0
        with:
          records: true
          rollout-percent: ${{ github.event.deployment.payload.percent }}
          rollout-metrics: ${{ runner.temp }}/canary.json
```

`rollout-change` names the change (`owner/repo#123`) or a commit; by default the deployment's commit. The step runs `onus ci rollout`, records the stage and pushes the records, and sets `rollout-decision`: `promote`, `hold`, `rollback` or `complete`. A rollback fails the step, and the change's `rolled-back` outcome is already recorded. `workflow_dispatch` with the same inputs works too. Onus never moves traffic: the workflow does, on the decision. See [`onus help production`](/docs/production).

### Reviews in the human lane

A change in the human lane needs a person to approve it. `onus ci pr --reviews <file>` decides whether it has one, from the pull request's GitHub reviews as a JSON array:

```json
[{"by": "grace", "state": "APPROVED", "commit": "<sha>", "association": "MEMBER", "bot": false, "at": 1760000000}]
```

or as an object that also says who is in each owning team:

```json
{"reviews": [...], "teams": {"@acme/growth": ["grace", "lin"]}}
```

`by` is the login without `@`; `state` is `APPROVED`, `CHANGES_REQUESTED`, `COMMENTED`, `DISMISSED` or `PENDING`, in any case; `commit` is the commit reviewed; `association` is the reviewer's author association; `bot` and `at` (seconds) are optional. A host gets them with the GitHub CLI:

```text
gh api repos/OWNER/REPO/pulls/N/reviews --paginate | jq '[.[] | {by: (.user.login // "ghost"), state,
  commit: (.commit_id // ""), association: .author_association, bot: (.user.type == "Bot"),
  at: ((.submitted_at // "1970-01-01T00:00:00Z") | fromdate)}]' > reviews.json
```

The rules:

- Each reviewer's latest review counts, ordered by `at` and then by position. `COMMENTED` and `PENDING` never replace an earlier verdict; `DISMISSED` clears it.
- A review is not counted, and is listed in `ignored` with the reason, when the reviewer is a bot (`bot`, or a login ending in `[bot]`), opened the pull request (`--author`), has no write access (an association other than OWNER, MEMBER or COLLABORATOR), or approved a commit other than the head.
- Changes requested by a counted reviewer stand at any commit, as on GitHub.
- Whose approval counts in the human lane is `lanes.approval` in the base commit's onus.yaml, so a change cannot loosen it for itself. An explicit `--config` inside the repository is read at the base commit too; one outside it (a host's own) is taken as given. An onus.yaml that does not parse leaves the default, with a warning.
  - `owner`, the default when the change has owners: only an owner of what changed. That is a person named as an owner (`@grace`), or a member of an owning team (`@acme/growth`) when the reviews file lists the team's members. An approval from anyone else is listed in `ignored` as "not an owner". Changes requested by anyone with write access still stand.
  - `member`, the default when nobody owns what changed: any person with write access.
  - When `owner` cannot be checked, any person with write access counts, and `note` says why: an owning team whose members the file does not list, an owner given as an email, no owners at all, or no owner but the author who could approve (the only owner opened the pull request, or the owning teams hold nobody else). A team the file lists with no members has none: beside other owners it adds nobody.
- In the human lane the review is satisfied with at least one counted approval and no outstanding changes requested. Other lanes need no approval: there every approval from someone with write access is recorded, for provenance, and `approval` is `member`.

The owners are read at the base commit, as GitHub reads CODEOWNERS, so a change can name neither its own owner nor, with `owner`, its own approver. For each file of the rows that need a person (of every row when that finds nobody), they are the owners of the component holding it in the base commit's onus.yaml (or the `--config` read as above), else the owners CODEOWNERS at the base commit gives the file. The report's `hints.owners` come from the head and are not used here. They are the owners to ask, each once per pull request: the pull record keeps everyone asked so far. `onus ci owners --base <ref> --report <file> [--config <file>]` prints them, `{"owners": [...]}`, so a host can look up the members of owning teams before it runs `ci pr --reviews`.

The answer is the `review` key of what `onus ci pr` prints, always present:

```json
{"lane": "human", …, "review": {"required": true, "satisfied": false, "approvedBy": [],
  "changesRequestedBy": [], "owners": ["@team-growth"], "request": ["@team-growth"],
  "ignored": [{"by": "@eve", "why": "no write access (CONTRIBUTOR)"}], "approval": "owner"}}
```

`required` is true in the human lane only, and `satisfied` is true outside it. `approval` is the rule that counted the approvals, `owner` or `member`, and `note` is there only when `owner` fell back to `member`. `request` lists the owners to ask now: not asked before, never the author, and empty once satisfied. `lane.md` gains a **Review:** paragraph in the human lane: who was asked, or that it was approved and by whom. Without `--reviews` there are no reviews, so a human-lane change waits.

The pull record keeps `requested` (everyone asked), `reviewedBy` (the counted approvals of its head) and `approval` (the rule that counted them, once a review was needed or given), and the outcome keeps `reviewedBy` and `approval`. A human-lane outcome with no `reviewedBy` merged without a counted review: an admin merge, or a check that was not required.

With `records: true`, the action passes `--reviews`. It lists the pull request's reviews with the GitHub CLI, as above, and the members of each owning team of the repository's organisation that `onus ci owners` names. It asks the owners in `review.request` to review (GitHub's requested reviewers): `@org/team` of the repository's organisation as a team, `@login` as a person, never the author; emails and other organisations' teams are skipped. A name GitHub refuses (not a collaborator, or a team without access) is a warning, and the others are still asked. onus has already recorded it as asked, so it is not tried again on every push, and the comment says GitHub would not ask it. The workflow's own token cannot read team members (that needs the organisation's members: read permission), so with it onus counts anyone with write access for those teams and says so; give `github-token` a token that can read them to count only their members. While no review counts, the job fails (`wait-for-review`, default `true`) and the output `review` is `waiting`; once one does, it is `approved`. A `pull_request_review` event runs the action again, and after an approval it re-runs the failed `pull_request` check for the head (with `actions: write`), so both pass. Make the job a required status check in branch protection or a ruleset: otherwise a failed check is shown but does not stop a merge. A listing that fails passes no reviews, so the change keeps waiting. Each run is its own check of the same name on the head commit, and GitHub goes by the newest: when an approval is dismissed, the run for the dismissal fails, and it is the newest. For the same reason every review runs the action, comments too: a run that skipped the work would leave a passing check as the newest. Reviews on a closed pull request do nothing. Only `records: true` waits; `lanes: true` alone classifies without reviews, and says so in a notice when the lane is human. A pull request runs the workflow and the action as it changes them, so it could turn the wait off for itself: protect `.github/workflows` (and the action, when it is in the repository) with CODEOWNERS and *Require review from Code Owners*, or a ruleset. Onus Cloud passes `--reviews` too, and turns `satisfied` into its check.

### Who made the change

Each outcome is kept against an agent setup. Onus reads it from what git and GitHub show, in order:

1. An `Onus-Agent: tool/model/config` trailer on the head commit, such as `Onus-Agent: claude-code/opus/plan-first`. The most precise; agents can be told to add it.
2. A branch named after an agent: `claude/`, `claude-code/`, `codex/`, `cursor/`, `copilot/`, `devin/`, `jules/`, `aider/`, and `onus/` for changes pushed through the Onus gateway.
3. The bot that opened the pull request, such as `copilot-swe-agent` or `devin-ai-integration[bot]`; any other bot under its own name.
4. A `Co-authored-by` trailer naming an agent.
5. Otherwise the person who opened it, as `person/<login>`.

### The agent's submission

An agent that hands in its change with `onus submit` (or `onus_submit`) under a task token has a submission: the token's task, rights, expiry and fingerprint, verified when it was made, and the escalations granted to it. Give it to the action so the change's provenance keeps them: the `submission` input (a path written by an earlier step), or a file on the records branch at `submissions/<pull request number>.json` or `submissions/<head commit>.json`. `onus ci records pull` copies those into `submissions/` of the records folder, and a push keeps whatever else is on the branch. The action passes it to `onus ci pr --submission` and to `onus provenance --agent-submission` when the pull request closes.

Only the token and the escalations are taken from it, and only when it is for one of the pull request's commits. The record marks the token `agent-submission`, ranked below the door's word, and the `escalations` gap says the escalations it lists are the agent's word: the file is plain JSON, and anyone who can write to the records branch can put one there; one that cannot be read is a warning, never a failed job. The action cannot verify the token itself (a submission never keeps it, and no root key reaches CI), and it sees no door log and none of what Onus Cloud keeps (escalations, calls, the door log an agent attached there). Those stay gaps in the provenance record unless a host passes them (`onus help provenance`).

### Reading the records

`onus ui` reads `origin/onus/records` when there is no local outcomes file: the Outcomes page shows changes by week and lane, each agent setup's record and whether it may auto-merge, and the pull requests in flight. Its *Fetch from origin* button fetches the branch. On the command line:

```sh
onus ci records pull --dir records
onus outcomes summary --file records/outcomes.jsonl
```

### Notes

- Pull requests from forks get a read-only token on `pull_request` events, so they are classified but not recorded.
- Concurrent runs merge their records by taking every line from both sides, each as many times as the side that holds it most, and retry the push when another run pushed first. So a line one run wrote twice is kept twice, and a line two runs each wrote once is kept once.
- The `onus ci` commands the action runs work in any CI system: `onus ci pr`, `onus ci owners`, `onus ci closed`, `onus ci comment`, `onus ci push`, `onus ci rollout`, `onus ci rollback` and `onus ci records pull|push` (see [`onus help commands`](/docs/commands) and `onus ci --help`).

## Which changed lines tests ran

With coverage of the head commit, the report says how many changed lines tests ran and lists those no test ran ([`onus help reports`](/docs/reports)). The tests must run at the pull request's head commit, not the merge commit `pull_request` checks out, so check it out for them:

```yaml
steps:
  - uses: actions/checkout@v7
    with:
      ref: ${{ github.event.pull_request.head.sha }}
      fetch-depth: 0
  - run: npm ci && npx vitest run --coverage --coverage.reporter=lcov
  - uses: onushq/onus/action@v0.11.0
    with:
      coverage: coverage/lcov.info
```

When the checkout is another commit, the action leaves the coverage out with a warning. Coverage that environments recorded comes in through `evidence` (with records): the action passes those runs to `onus report --evidence` too, and only runs at the head commit count ([`onus help environments`](/docs/environments)). With `lanes.inputs.coverage`, too few changed lines run sends the change to the judge, and recorded coverage counts only from the commands it names in `commands`: recorded coverage from any other run sends the change to the judge too, so name the run that records it ([`onus help lanes`](/docs/lanes)).

## Caching the base map

Most of a report's time goes into mapping the two commits. A pull request is reported on every push, but its base commit rarely changes, so the action caches the base map (input `cache`). On the command line, the same cache is `--cache-dir`:

```sh
onus report --base "$BASE" --head "$HEAD" --cache-dir ~/.cache/onus
```

The cached map's file name is a hash of everything that shapes it: the base commit, the Onus version, the onus.yaml and its packs, the plugins file and trusted mode, and any `--base-scip` indexes. A change to any of them builds a new map; a cached file is never updated in place, and one that cannot be read is ignored. The report is byte for byte the same with or without the cache.

With a cached base map, Onus extracts only the base commit's changed files (plus `onus.yaml`, its packs and `.gitignore` files), which roughly halves the time of a report on a large repository: about 12 seconds instead of 22 for a pull request in a 31,000-file repository.

## Was the report useful? 👍 👎, /onus caught and /onus accuracy

The Phase 1 question is whether reviewers prefer the report to the raw diff. Two signals answer it, both left on the pull request itself:

- A 👍 or 👎 reaction on the Onus comment.
- A reply that starts with `/onus caught`, followed by what the report surfaced that the diff hid:

      /onus caught the new SMS vendor; I would have missed it in 1,400 lines

Anyone's `/onus caught` counts toward the catch rate. One from someone with write access is also recorded when the action keeps records (`records: true`), and trains the learned lane model. To acknowledge those replies with a 🚀, add a second workflow; the same action handles both events:

```yaml
name: Onus caught
on:
  issue_comment:
    types: [created]
permissions:
  issues: write
  pull-requests: write
jobs:
  caught:
    if: github.event.issue.pull_request && startsWith(github.event.comment.body, '/onus caught')
    runs-on: ubuntu-latest
    steps:
      - uses: onushq/onus/action@v0.11.0
```

### Accuracy checks

Wrong facts are the metric that matters most, so people can also say whether a report was right. After reading it, reply:

```text
/onus accuracy ok
/onus accuracy wrong 3 the vendor is not new
/onus accuracy missed the nightly cron job now sends email too
```

`wrong` names a row by its number in the table (from 1) or by its id; `missed` says what the report left out. Only people with write access (OWNER, MEMBER, COLLABORATOR) can give an accuracy check. With `records: true`, the action answers with a 👍, or with 😕 and the reason when it cannot take the check. It records nothing: an accuracy check is not an outcome and changes no track record. Onus Cloud asks for a check on a sample of reports, keeps the answers, and shows them with the 👍 and 👎 counts, the catch rate and review times on its Metrics page.

The comment also carries the report's metrics line in a hidden HTML comment. `scripts/onus-metrics.sh` in the Onus repository reads all of it back with the GitHub CLI, one JSON line per pull request, or one line of totals with `--summary` (reports, large reports, the share of 👍 on large pull requests, the catch rate, changed lines per row, time to first review):

```sh
scripts/onus-metrics.sh your-org/your-repo --limit 200 --summary
```

## Without the action

Install the binary and run `onus report` yourself:

```sh
curl -fsSL https://onushq.com/install.sh | sh
onus report --base "$BASE" --head "$HEAD" --intent pr-body.md >> "$GITHUB_STEP_SUMMARY"
onus report --base "$BASE" --head "$HEAD" --format json --fail-on secrets > onus-report.json
```

## Other CI systems

Onus needs only git, the checkout and the binary. In GitLab merge request pipelines:

```sh
onus report --base "$CI_MERGE_REQUEST_DIFF_BASE_SHA" --head "$CI_COMMIT_SHA" --fail-on secrets
```

## Using the exit code

- `0`: the report ran (it may still contain findings; read `summary` in the JSON).
- `1`: Onus could not run: a missing ref (fetch more history), an invalid onus.yaml, an unreadable directory.
- `2`: a `--fail-on` condition was met.

To branch on other findings, read the JSON, for example with jq:

```sh
jq '.summary.needsAttention' onus-report.json
jq -r '.changes[] | select(.hints.needsPerson) | .title' onus-report.json
```


---

## Onus Cloud from the CLI

URL: https://onushq.com/docs/cloud

Onus Cloud from the CLI: onus login, scoped tokens, hosted environments, evidence, escalations, maps and agents


<!-- Generated by npm run docs:sync from crates/onus-cli/guide/cloud.md in onushq/onus; edit it there. -->

# Onus Cloud from the CLI

Onus Cloud is the hosted Onus: it analyses every pull request of the repositories you install it on, keeps the outcome records, runs the judge, and builds environments on its own machines. Its Audits page lists the merged changes Onus sampled for a person to audit ([`onus help lanes`](/docs/lanes)); marking one ok or a miss records it with `onus outcomes audit`. The CLI signs in to it as you, so you and your agents can use it from the terminal and through `onus mcp`.

## Signing in

```sh
onus login                       # opens the browser; approve the code it shows
onus login --org acme            # and act in the organisation acme
onus login --no-browser          # print the link instead, for a machine without one
```

`onus login` shows a one-time code and opens Onus Cloud's sign-in page, where you compare the code and approve it (and pick the organisation the CLI acts in). The CLI then holds a token of its own in `~/.config/onus/cloud.json` (`$ONUS_CONFIG_DIR` or `$XDG_CONFIG_HOME` to move it), readable by you only. The token acts as you, in every organisation you belong to, with your role there; organisations that require single sign-on need you to have approved it after signing in with it. It lasts 90 days from its last use.

```sh
onus cloud status                # who, which organisation, its plan and what it allows
onus cloud use beta              # act in another organisation
onus logout                      # the token is revoked and forgotten
```

The account page in Onus Cloud lists every signed-in CLI, and revokes any of them.

**In CI**, there is no one to approve a code: set `ONUS_API_KEY` to an organisation's API key (Settings, API keys; `write` scope to create environments and attach evidence). `ONUS_CLOUD_URL` and `ONUS_CLOUD_ORG` change the address and the organisation; `--org` does too, per command.

The CLI signs in with the first of: a scoped token in `ONUS_CLOUD_TOKEN`, an API key in `ONUS_API_KEY`, the login in `cloud.json`. With `ONUS_CLOUD_TOKEN` set, neither of the others is read.

## Narrow tokens for agents and scripts

A login acts as you, everywhere you can. An agent or a script needs much less. Mint it a scoped token: one organisation, some repositories, some scopes, a fixed end.

```sh
onus cloud token create --repo acme/shop --scope pulls:read --scope env:run --ttl 2h --label sms-otp
onus_tok_7Hc0…                      # stdout: the token alone
onus: token for acme (acme/shop): pulls:read, env:run; ends 2026-10-12T19:40:00.000Z (2h). Revoke: onus cloud token revoke 3f2a…

ONUS_CLOUD_TOKEN=onus_tok_7Hc0… claude …          # the agent's onus commands use it, and nothing else
```

| Scope | Opens |
|---|---|
| `env:read` | hosted environments, their runs and logs |
| `env:run` | create, run in and destroy hosted environments (and `env:read`) |
| `evidence:write` | attach evidence to a pull request |
| `pulls:read` | governed pull requests, their analyses and evidence |
| `map:read` | a repository and the maps Onus Cloud keeps of it |
| `escalation:write` | file, read and withdraw escalations |

- **Repositories.** `--repo` is repeatable; without it the token is for this folder's GitHub repository. `--all-repos` makes it for every repository.
- **How long.** `--ttl` is `90s`, `30m`, `2h` or `1d`: one hour by default, at most 24 hours. The end is fixed; using the token does not move it.
- **Narrowable, never widenable.** A scoped token can mint a narrower one, for a sub-agent: `ONUS_CLOUD_TOKEN=<parent> onus cloud token create --scope pulls:read --ttl 30m`. A child never has a scope, a repository or an end its parent does not. API keys cannot mint tokens.
- **Revoking.** `onus cloud token list` shows your logins and scoped tokens; `onus cloud token revoke <id>` revokes one and every token minted from it. `onus logout` revokes the login and everything minted from it.
- **Denials teach.** A call the token does not open answers with the scope it needs: `Denied: this token does not have env:read … (mint one with onus cloud token create --scope env:read, or ask with onus_escalate)`. A token that ended says to ask for a new one.

`onus cloud status` says how the CLI is signed in: `with a scoped token (sms-otp) in acme: pulls:read, env:run on acme/shop; ends in 1h52m`. A scoped token acts in its one organisation, so `onus cloud use` refuses it. Onus Cloud logs every call a token makes (Settings, Audit log, CLI and agent calls).

## Hosted environments

The same environments as `onus env` ([`onus help environments`](/docs/environments)), built and run by Onus Cloud instead of your machine: no Docker needed, and every run is recorded by Onus Cloud rather than by the machine that asks.

```sh
onus cloud env create                                   # this folder's repository at its pushed HEAD
onus cloud env create --repo acme/shop --ref pull/42 --name sms
onus cloud env run sms -- npm test
onus cloud env run sms --timeout 3600 -- npx playwright test
onus cloud env show sms                                 # its runs
onus cloud env log sms <run id>                         # a run's whole output
onus cloud env list --all
onus cloud env destroy sms
```

- **What is built.** The repository's `environment:` in onus.yaml (or its devcontainer), read from the **default branch**, never from the commit under test; the commit itself must be pushed, since Onus Cloud fetches it from GitHub. `--ref` takes a branch, tag, commit or `pull/<n>`. `create` waits until it is ready (the first build of a lockfile runs the setup; later ones start from the warm image).
- **Network.** None, unless you name hosts: `--host registry.npmjs.org --host '*.example.com'`. The egress proxy allows exactly those. Setup has network, as with `onus env`. Nothing in an environment can reach Onus Cloud's own network or its cloud's metadata server.
- **Files.** Environments run under gVisor, where `/tmp` is in memory: a `seed` or `setup` that writes there is not kept when the judge rebuilds the environment to re-run a test. Write seed data under the repository or `/var`.
- **Secrets.** None. Hosted environments are for code and synthetic data.
- **Runs.** Each run is recorded like `onus env run`: the output, JUnit results and traces the environment declares, under a manifest. `run` waits and exits 0 when the command passed, 1 when it failed. Runs of one environment go one at a time.
- **Lifetime.** An environment unused for 30 minutes, or 8 hours old, is destroyed. Destroy it when you are done: its minutes count until then.
- **Plans.** The Free plan has 1 environment at a time and 300 environment minutes a month; Team has 5 at a time and 3,000 minutes, then bills the minutes beyond; Enterprise has no limits. `onus cloud status` shows what is left.

## Evidence the judge can trust

Attach a recorded run to a pull request:

```sh
onus cloud evidence acme/shop#42 --run <run id>
```

Onus Cloud keeps it for the run's commit and, when that is the pull request's head, analyses the pull request again. The judge finds the run's manifest and artifacts beside the repository, checks the run against them (the commit, the command, the exit code), and re-runs it in a fresh container with the environment's setup and seed. Its verdict says how many runs matched their manifests.

Attach the task's door log, so the change's provenance keeps every call made through the door:

```sh
onus cloud evidence acme/shop#42 --door-log --task sms [--audit .onus/audit.jsonl]
```

It sends the task's slice of the log: the entries from the task's first to its last, with whatever lies between (other tasks' entries on the same log included), so the hash chain can be checked (`schemas/door-log.schema.json`). Through `onus mcp --token`, the door also sends its inspection of the token it holds, never the token, so the change's provenance knows the token even when the agent never escalated. From the command line no door holds the token, so the slice gives it only when it holds the task's `mint` entry. Attach it after committing and pushing the work: the slice goes only to the pull request whose head, as Onus Cloud knows it, is the worktree's commit, so an agent cannot hang its log, and the other tasks' entries in it, on another change (this reads the pull request, so the token needs `pulls:read` as well as `evidence:write`). A slice cut at a commit that is not one of the change's gives neither the task nor the token. An Onus Cloud that keeps door logs passes the slice, as it was sent, to `onus ci pr --audit`, which checks the chain and keeps the task's entries in the provenance record, with Onus Cloud's own log of the calls made under the task token beside them (`--calls`; `onus help provenance`). Give `--run` as well to attach both. Each goes in its own request, so an older Onus Cloud, which does not take door logs, refuses it rather than keeping the run alone.

```sh
onus cloud pulls --attention                            # waiting for a person
onus cloud pulls --repo acme/shop --lane judge
onus cloud pull acme/shop#42                            # its lane, analyses and evidence
```

## The map Onus Cloud keeps

Onus Cloud keeps the map of every default-branch commit it maps (after each push to the default branch) and of the newest head of each pull request it analyses. A newer head of a pull request replaces the older one; a closed pull request keeps its last. Every map is the binary's own output, kept byte for byte, and so is its overview (`onus query overview`).

```text
GET /v1/orgs/<org>/repos/<owner/name>/map                        # the newest default-branch map
GET /v1/orgs/<org>/repos/<owner/name>/map?commit=<40-hex sha>    # the map of that commit
GET /v1/orgs/<org>/repos/<owner/name>/map/overview[?commit=…]    # its overview
GET /v1/orgs/<org>/repos/<owner/name>/maps                       # the maps kept, newest first
```

The `x-onus-map-commit` header names the commit of the map sent. A commit Onus Cloud never mapped answers 404 `no_map`: ask a worktree at that commit with `onus query` instead. The web app's map explorer shows the overview: components, owners, labels, what each uses and what uses it.

`onus cloud map` asks it the same questions as `onus query`, with the same JSON. The CLI downloads the map and answers here; Onus Cloud only serves the file:

```sh
onus cloud map status --repo acme/shop                          # the default branch's newest map
onus cloud map dependents UserPreferences --commit 3f2a1c…      # a commit Onus Cloud mapped
onus cloud map impact formatPhone --change change-signature --pull 42   # a pull request's head
onus cloud map --download map.json --commit 3f2a1c…             # the map itself
onus query --map map.json dependents UserPreferences --depth 2
```

The repository defaults to this folder's GitHub remote (else `ONUS_CLOUD_REPO`). `--commit` takes a full sha, or anything this folder's git resolves. Maps of a commit never change, so they are kept by sha in `~/.cache/onus/cloud-maps/` (`$ONUS_CACHE_DIR` or `$XDG_CACHE_HOME` to move it), and a second question makes no request. A map of another schema version is refused (update onus), and so is a map of another commit than the one asked for. `check` and `stats` need a worktree: use `onus query`.

## Escalations and the safe exit

An agent that needs more than its task token allows asks with evidence ([`onus help scopes`](/docs/scopes)). An agent that is blocked (a test it did not write fails, the spec contradicts itself, the task cannot be done as asked) says so with evidence and stops. When the CLI is signed in, both go to Onus Cloud, where a person sees them, decides, and is notified:

```sh
onus cloud escalate --task sms-otp --scope 'write:path:services/billing/src/**' \
  --evidence failing-test:services/billing/src/a.test.ts --reason "…" \
  --token "$TOKEN" --key-public root.pub --key root.key [--pull 42] [--wait 600]
onus cloud blocked --kind broken-test --evidence failing-test:services/orders/src/eta.test.ts \
  --reason "the test expects UTC; the fixture is local time" --task sms-otp
onus cloud escalation <id> [--wait 600]       # where it stands
onus cloud escalation list [--waiting]
onus cloud escalation withdraw <id>
```

`--repo <dir>` names the worktree whose `.onus/escalations` keeps the request (default: this folder).

- **The facts are the binary's.** The request is built here, with its blast radius, sensitive labels and owners from the map, and kept in `.onus/escalations/<id>.json`. Onus Cloud then works them out again on the repository's **default branch** (`onus escalate`, `onus escalation assess`), so a branch that edits onus.yaml cannot weaken its own request. Low-risk requests with a reproduced failing test are granted by policy; the rest wait for an owner of the code involved, or an admin.
- **The token stays here.** Onus Cloud is sent what the task token holds (task, rights, end), never the token. On a grant, the door that holds the root key (`--key`, or `onus mcp --key`) mints the new token itself: the old rights plus exactly the scopes of the request it kept, never anything the answer names. An answer about another request is refused, and so is a request file changed after it was filed, or a grant of other scopes than the file asks for: nothing is minted. A token kept beside a request is handed out only when it proves that grant. Without the key, the answer says who granted it and the command the operator runs (`onus escalation grant .onus/escalations/<id>.json --id <id> --scope '<right>' --by 'Ada (Onus Cloud)' …`). It names the request and the scopes Onus Cloud granted, so a request file the agent swapped since mints nothing. The token is picked up once it is kept beside the request.
- **The audit log.** Filing writes `sent-to-onus-cloud`; a person's grant, denial or answer is written as theirs (`Ada (Onus Cloud)`), a grant by policy as the policy's (`system:policy (Onus Cloud)`), and a withdrawal from the command line at once. `onus ui` shows which requests went to Onus Cloud.
- **Exit codes.** 0 when granted (the token alone on stdout) or answered, 1 when denied, withdrawn, expired or failed, 3 while it is being checked or waits for a person.

A blocked report asks for no rights. The person answers it (the agent sees `answered`, with the text) or denies it (the task should stop).

## For agents

When the CLI is signed in (with `onus login`, `ONUS_CLOUD_TOKEN` or `ONUS_API_KEY`), `onus mcp` adds tools for Onus Cloud:

- `onus_cloud_status`: who the CLI is, the organisation, the token's scopes, what the plan allows.
- `onus_cloud_env_create`, `onus_cloud_env_run`, `onus_cloud_envs`, `onus_cloud_env_destroy`: hosted environments; the repository and commit default to the agent's worktree and its pushed HEAD.
- `onus_cloud_attach_evidence`: a recorded run to a pull request, for the judge; with `doorLog: true`, the task's slice of the door log, which the server cuts from its own log (the agent names only the pull request).
- `onus_cloud_pulls`, `onus_cloud_pull`: governed pull requests, their lanes and evidence, read-only.
- `onus_cloud_map`: a question to the map Onus Cloud keeps, at a commit or a pull request's head, answered by the CLI; under a task token, filtered to what the task may read, as the map tools are.
- `onus_cloud_token`: a narrower token for a sub-agent, never wider than the server's.

`onus_escalate`, `onus_escalation` and `onus_blocked` go to Onus Cloud by themselves when the CLI is signed in (see above).

**The login never reaches the agent's calls.** Signed in with `onus login`, `onus mcp` mints a scoped token from the login on the first Onus Cloud call and uses it for every call after: the organisation the CLI acts in, the worktree's repository, all six scopes, 8 hours (`--cloud-ttl`, at most 24h), labelled with the task of `--token`. It mints a new one shortly before that one ends. The worktree's repository is its GitHub remote; name it with `--cloud-repo owner/name` (or `ONUS_CLOUD_REPO`) when there is none. With `--cloud-token` (or `ONUS_CLOUD_TOKEN`) it uses that token as it is, and with `ONUS_API_KEY` the key.

Signed out, the tools are not listed. Nothing an agent does through Onus Cloud approves a change.


---

## Commands

URL: https://onushq.com/docs/commands

Every command and flag, with examples and exit codes


<!-- Generated by npm run docs:sync from crates/onus-cli/guide/commands.md in onushq/onus; edit it there. -->

# Commands

Every command prints to stdout; errors and warnings go to stderr. Run `onus help <command>` for the flags of one command.

## onus map <dir>

Builds the map of a directory and prints a summary.

```sh
onus map .
onus map . --json > map.json
onus map . --config other/onus.yaml
```

- `--json`: print the whole map (format: [schemas/codebase-map.schema.json](https://github.com/onushq/onus/blob/main/schemas/codebase-map.schema.json)).
- `--config <file>`: use this onus.yaml instead of `<dir>/onus.yaml`.
- `--scip <file>`: import a SCIP index of the directory (repeatable). Runs nothing.
- `--traces <file>`: add the calls in OpenTelemetry traces (OTLP JSON) as `traced` edges (repeatable). See [`onus help environments`](/docs/environments).
- `--coverage <file>`: add line coverage of the directory (lcov, Cobertura XML or Istanbul JSON), measured at the same version of its files (repeatable). See [`onus help environments`](/docs/environments).
- `--plugins <file>`, `--trusted`, `--allow-unsandboxed`: see "Plugins" below.

## onus diff <base> <head>

Reports the changes in meaning between two directories.

```sh
onus diff old new
onus diff old new --format json > report.json
onus diff old new --intent pr-body.md --fail-on rule-violation,secrets
```

- `--format md|json`: Markdown (default) or the full JSON report (format: [schemas/semantic-report.schema.json](https://github.com/onushq/onus/blob/main/schemas/semantic-report.schema.json)).
- `--markdown-out <file>`: also write the Markdown report to a file, so one run gives both formats.
- `--intent <file>`: check the change against a stated intent: a YAML file, or Markdown (such as a pull request body) containing an `onus-intent` block. See [`onus help intent`](/docs/intent).
- `--config <file>`: the onus.yaml used for both trees. By default Onus uses the base tree's onus.yaml for both, so a change cannot relax the rules it is checked against.
- `--fail-on <what>`: exit with code 2 when `rule-violation` (a new boundary-rule violation) or `secrets` (a committed secret) is found. Repeat the flag or separate values with commas. `none` never fails.
- `--base-scip <file>`, `--head-scip <file>`: import SCIP indexes of each tree (repeatable).
- `--traces <file>`: add the calls in OpenTelemetry traces to both trees (repeatable), so they are facts of both and never changes.
- `--coverage <file>`: line coverage of the head tree (lcov, Cobertura XML or Istanbul JSON), from tests run at the head (repeatable). The report then says which changed lines tests ran; see [`onus help reports`](/docs/reports).
- `--plugins <file>`, `--trusted`, `--allow-unsandboxed`: see "Plugins" below.

## onus report --base <ref> --head <ref>

The same report for two git refs. Each ref is extracted with `git archive` into a temporary directory that is removed afterwards; the repository itself is never modified. Only the paths git reports as different are compared line by line, and the base tree takes the head's copy of every other file.

```sh
onus report --base main --head HEAD
onus report --repo ../shop --base origin/main --head feature/sms --format json
```

- `--repo <dir>`: the repository (default: the current directory).
- `--format`, `--markdown-out`, `--intent`, `--config`, `--fail-on`, `--traces`, `--coverage`, `--plugins`, `--trusted`, `--allow-unsandboxed`: as for `onus diff`. SCIP indexes for `report` come from `scip` plugins, which index each ref in trusted mode.
- `--evidence <file>`: a test run from `onus env run` (repeatable). The coverage it recorded is used when its manifest is intact and it ran at the head commit; otherwise a note says why not.
- `--cache-dir <dir>`: keep the base ref's map in this folder and reuse it on the next report against the same base commit. The report is the same either way; see [`onus help ci`](/docs/ci).
- `--head-map-out <file>`: also write the head ref's map ([schemas/codebase-map.schema.json](https://github.com/onushq/onus/blob/main/schemas/codebase-map.schema.json)) to a file. It is the map the report was computed against, so `onus query --map <file>` answers questions about the head with no second build. It holds the traces and coverage the report was given, so two reports of one commit with different evidence write different maps.

Any ref git understands works: branches, tags, `HEAD~3`, commit hashes. In JSON, `base` and `head` read like `main (abc1234)`.

## Plugins

- `--plugins <file>`: a plugins file listing language, framework, SCIP and LSP plugins (default: the file named by `ONUS_PLUGINS`). It is never read from the analyzed repository.
- `--trusted`: allow plugins that may run code from the repository (indexers, language servers). They run in a sandbox with no network.
- `--allow-unsandboxed`: with `--trusted`, allow them even where no sandbox is available.

See [`onus help plugins`](/docs/plugins).

## onus init [dir]

Writes a starter onus.yaml inferred from workspaces and CODEOWNERS. Sensitivity labels are only suggested, as comments, until you confirm them.

```sh
onus init
onus init path/to/repo --stdout     # print instead of writing
onus init --force                   # overwrite an existing onus.yaml
```

## onus schema

Writes the JSON Schemas of the map, the report, onus.yaml, the plugins file and protocol, the provenance record (`onus provenance`) and what it reads (escalation decisions, Onus Cloud's calls, a door log slice), production signals and rollout metrics, held-out suites, and the map overview (`onus query overview`).

```sh
onus schema --out schemas
onus schema                         # print them all
```

## onus mcp

Serves the map of the current worktree to a coding agent as MCP tools, on stdin and stdout. See [`onus help agents`](/docs/agents) for the tools and how many agents share one map server.

```text
claude mcp add onus -- onus mcp
```

- `--repo <dir>`: the worktree (default: the one containing the current directory).
- `--no-server`: build the map in this process instead of the repository's shared map server.
- `--token <token>` and `--key-public <file>`: the task token every call is checked against; `--key <file>`: the root private key, with which the server mints grants itself; `--trusted-repo <dir>`: a checkout whose files the agent cannot edit, from which the policy decides escalations when signed out; `--audit <file>`: the log; `--no-actions`: only the map tools.
- `--cloud-token`, `--cloud-repo`, `--cloud-ttl`: how the server signs in to Onus Cloud ([`onus help cloud`](/docs/cloud)).

## onus query <question>

The same questions as the MCP tools, from a shell, printed as JSON: `status`, `find <words>`, `symbol <id>`, `dependents <target>`, `dependencies <target>`, `tests-for <target>`, `impact <target> [--change <kind>]`, `invariants [target]`, `owners <target>`, `component <id>`, `file <path>`, `overview`, `check [--base <ref>]` and `stats`.

```sh
onus query find format phone
onus query dependents UserPreferences --depth 2 --limit 20
onus query overview
onus query --map map.json dependents money
```

- `--repo <dir>` and `--no-server`: as for `onus mcp`.
- `--depth <n>` (1 to 8) and `--limit <n>` (default 50, at most 500) where they apply.
- `--map <file>`: answer from a map JSON file instead of a worktree: one from `onus map --json` or `onus report --head-map-out`, or a map downloaded from Onus Cloud. `-` reads stdin, so `curl … | onus query --map - dependents money` works in scripts. A map of another schema version is refused. No map server is started, `check` and `stats` need a worktree, and `impact --change add-required-member` lists every file that names the type, since there is no source to read.
- `overview`: every component with its kind, roots, owners, labels, package, files, lines and first 50 public symbols, the components it uses and that use it (with edge counts), its external services and events; then the links between components, the events, the declared contracts and the rules ([schemas/map-overview.schema.json](https://github.com/onushq/onus/blob/main/schemas/map-overview.schema.json)). It is what `onus ui` draws and what Onus Cloud shows for a map it keeps.

## onus ui

Opens the web interface for the repository: everything below and above, in a browser, served on 127.0.0.1. See [`onus help web-interface`](/docs/web-interface).

```sh
onus ui
onus ui --repo ../shop --port 0 --no-open
```

- `--repo <dir>`, `--port <n>` (default 4387; 0 picks one), `--no-open`.
- `--outcomes <file>`, `--audit <file>`, `--escalations <dir>`, `--keys <dir>`: where outcome records, the audit log, escalation requests and the root key pair are kept.

## Scopes, lanes and environments

- `onus token`, `onus scope`, `onus gateway`, `onus escalate`, `onus escalation`, `onus audit`, `onus run-test`: task tokens, the git gateway, escalation and the audit log. See [`onus help scopes`](/docs/scopes).
- `onus submit`, `onus classify`, `onus judge`, `onus outcomes`: risk lanes, the judge and outcome records. `onus outcomes audits` lists the merged changes sampled for a person to audit and the audit log; `onus outcomes audit` records an audit. `onus lanes train` fits the learned lane model to outcome records; it may only raise lanes. See [`onus help lanes`](/docs/lanes).
- `onus env`, `onus evidence`: environments and the evidence store. See [`onus help environments`](/docs/environments).
- `onus signals ingest|traces|areas`: production signals kept with the records, production traces for the map, and each component's history. See [`onus help production`](/docs/production).

## onus ci

What the GitHub Action runs to keep outcome records on a branch ([`onus help ci`](/docs/ci)); usable from any CI system.

```sh
onus ci records pull --dir records                       # the onus/records branch into a folder
onus ci owners --base "$BASE" --report report.json       # who owns it, as the base commit says
onus ci pr --base "$BASE" --head "$HEAD" --change acme/shop#7 --branch codex/sms --author mike \
  --body-file body.md --report report.json --records records --out out
onus ci comment --change acme/shop#7 --body-file comment.md --author lead --association MEMBER --records records
onus ci closed --change acme/shop#7 --merged --commit "$SHA" --merged-by mike --records records
onus ci push --records records --since "$BEFORE"
onus ci rollout --commit "$SHA" --percent 25 --metrics canary.json --records records
onus ci rollback --change acme/shop#7 --reason "checkout 500s" --records records
onus ci records push --dir records --message "acme/shop#7 closed"
```

- `ci pr` submits, classifies and (with `--judge`) judges the change, appends to `pulls.jsonl`, writes `submission.json`, `classification.json`, `judgment.json`, `provenance.json`, `rollout.json` and the comment section `lane.md` to `--out`, and prints `{lane, verdict, agent, record, review, rollout, risk}` (`record.recentRollbacks` counts its agent setup's recent rollbacks; `rollout` is the plan's strategy, steps, bake time and whether it rolls back automatically; `risk` is the learned model's, or null). `--evidence <file>` adds test runs; `--reviews <file>` gives the pull request's GitHub reviews, for the human lane's review ([`onus help ci`](/docs/ci)); `--model <file>` uses that learned lane model instead of the one at the base commit (it still needs `lanes.learned`); `--escalations <file>` and `--token-inspection <file>` give the escalations and the door's inspection of the task token that Onus Cloud keeps, for the provenance record (`onus help provenance`); `--calls <file>` Onus Cloud's log of the calls made under the task token; `--audit <file>` the task's door log, or the slice of it the agent attached in Onus Cloud, whose hash chain is checked; `--submission <file>` the agent's own submission, whose token and escalations the record keeps when it is for one of the pull request's commits; `--task <id>` the task whose door log entries and calls to keep. They never stop the run: what cannot be read is a warning and a gap in the record. Only a token given instead of its inspection is refused. An escalation with no pull request is joined by `--branch` and the change's commits.
- `ci owners` prints `{owners}`: the owners `ci pr` asks to review and, with `lanes.approval: owner`, the people whose approval counts, read at the base commit (onus.yaml, then CODEOWNERS), so a host can look up owning teams' members for `--reviews`.
- `ci comment` acts on `/onus approve <row>`, `/onus audit ok|miss [note]` and `/onus incident <note> [involved: a, b]` from OWNER, MEMBER or COLLABORATOR, and prints `{command, ok, reply, rerun}`. It also answers `/onus caught <note>` (from anyone) and `/onus accuracy ok|wrong <row>|missed <note>` (write access) with what was said, `verdict`, `row`, `note` and `by`. Accuracy is never recorded. `caught` from OWNER, MEMBER or COLLABORATOR is recorded as `caught: true` on the change's outcome, or on its pull record while it is open, and its answer says so with `recorded`. `--report <file>` (the report's JSON) checks `wrong <row>` against the report's rows and turns a row number into its id.
- `ci closed` turns the pull request's latest record into an outcome, and samples a change approved without a person for an audit ([`onus help lanes`](/docs/lanes)). `--merged-by <login>` keeps who merged it on the outcome, as `@login`, for its provenance. `ci push` records reverts.
- `ci rollout` (`--change` or `--commit`) prints the change's rollout plan (for a change recorded before plans, from `lanes.rollout` in `--repo` or `--config`); with `--percent` (and `--metrics`, the stage's samples) it decides `promote`, `hold`, `rollback` or `complete`, records the stage, records a `rolled-back` outcome on `rollback`, and exits 0 for promote or complete, 2 for rollback and 3 for hold. `ci rollback` records a rollback decided elsewhere; `--planned` marks one done on purpose, which counts against no one. See [`onus help production`](/docs/production).
- `ci records` takes `--remote` (default `origin`) and `--branch` (default `onus/records`).

## onus provenance

One record of why a change was allowed through: the intent, the agent and model, the token it held, the evidence, any escalations, the lane and the judge's steps, who or what approved it, and how it rolled out (`onus help provenance`, [schemas/provenance.schema.json](https://github.com/onushq/onus/blob/main/schemas/provenance.schema.json)).

```sh
onus provenance --change acme/shop#7 --records records --from out/provenance.json --out p.json
onus provenance --submission-id 4fa91c
onus provenance --verify p.json
```

- `--change <id>`: the change, as the records name it. Default: the change of `--from`, else the submission's head commit.
- `--records <dir>` (or `--outcomes <file>`): the pull and outcome records and production signals, for the stage, approver and rollout. `--signals <file>` reads the signals from another file.
- `--from <file>`: an earlier record of the change; its facts from while the change was open are kept.
- `--submission <file>` or `--submission-id <id>`, `--classification <file>`, `--judgment <file>`: what was handed in and decided. `--submission-id` reads `.onus/submissions` of `--repo`, with the judgment, audit log, escalations and outcomes beside it.
- `--token <token>` with `--key-public <file>`: a task token, verified (an error when it does not verify) and never kept; `--audit <file>`, `--escalations <dir>` and `--task <id>`: the door log, escalation requests, and whose door decisions to include. `--audit` also takes the task's slice of the door log that the agent attached in Onus Cloud ([schemas/door-log.schema.json](https://github.com/onushq/onus/blob/main/schemas/door-log.schema.json)); its chain is checked from its first entry.
- `--calls <file>`: Onus Cloud's log of the calls made under the task token ([schemas/cloud-calls.schema.json](https://github.com/onushq/onus/blob/main/schemas/cloud-calls.schema.json)), summed up beside the door log as `doors.calls`, on Onus Cloud's word.
- `--agent-submission <file>`: the agent's own submission of a pull request, as `onus ci pr --submission` takes it: only its token and escalations, only when it is for one of the change's commits, and a warning when it cannot be read. The action passes it when the pull request closes.
- `--escalations <file>`: escalations as Onus Cloud keeps them, with their decisions ([schemas/escalation-decisions.schema.json](https://github.com/onushq/onus/blob/main/schemas/escalation-decisions.schema.json)); those for another repository or pull request, and those that neither name the change (its pull request, a commit in `--repo`, the submission or `--from`) nor share its task, are left out. One that cannot be read is left out with a warning and a gap. With `--submission-id`, the kept requests are read too. A path that does not exist is an error. `--token-inspection <file>`: the door's inspection of the task token (`{task, rights, expires}`), for `--task` when it is given. Never a token itself.
- `--out <file>`: write it instead of printing it. `--verify <file>`: check a record's digest and schema version; exit 1 when they do not match.

## onus login, onus logout, onus cloud

Onus Cloud from the terminal ([`onus help cloud`](/docs/cloud)). `onus login` signs the CLI in as you (approve the code it shows in the browser); in CI, `ONUS_API_KEY` stands in for it, and a scoped token in `ONUS_CLOUD_TOKEN` stands in for both.

```sh
onus login [--org acme] [--no-browser]
onus cloud status
onus cloud env create [--repo acme/shop] [--ref pull/42] [--name sms] [--host registry.npmjs.org]
onus cloud env run sms -- npm test
onus cloud evidence acme/shop#42 --run <run id>
onus cloud evidence acme/shop#42 --door-log --task sms
onus cloud pulls --attention
onus cloud token create --scope pulls:read [--repo acme/shop | --all-repos] [--ttl 2h] [--label sms]
onus cloud map dependents UserPreferences [--repo acme/shop] [--commit <sha> | --pull 42]
onus cloud escalate --task sms --scope 'write:path:services/billing/**' --evidence … --reason …
onus cloud blocked --kind broken-test --evidence failing-test:src/a.test.ts --reason … --task sms
onus cloud escalation <id> [--wait 600]
onus logout
```

- `cloud env create|run|list|show|log|destroy`: hosted environments; `create` and `run` wait unless `--no-wait`, and `run` exits 1 when the command failed. `--json` prints the API's answer.
- `cloud pulls`, `cloud pull <owner/name#n>`: governed pull requests, their lanes, analyses and evidence.
- `cloud evidence <owner/name#n> --run <id>`: a recorded run to a pull request, for the judge. `--door-log --task <task>` attaches the task's slice of the door log (`--audit <file>`, default `.onus/audit.jsonl` in the worktree), for the change's provenance, only when the pull request's head in Onus Cloud is the worktree's commit.
- `cloud token create|list|revoke`: scoped tokens; `create` prints the token alone on stdout.
- `cloud map <question> | --download <file>`: `onus query`'s questions asked of the map Onus Cloud keeps, answered here.
- `cloud escalate`, `cloud blocked`, `cloud escalation <id>|list|withdraw`: escalations and blocked reports in Onus Cloud. `--token`, `--key-public` and `--key` are the door's; with `--key` a grant is minted here. Exit 0 when granted or answered, 1 when denied, withdrawn, expired or failed, 3 while waiting.
- `--org <slug>` on any `cloud` command, or `ONUS_CLOUD_ORG`, picks the organisation; `ONUS_CLOUD_URL` the address.

## onus help [command | topic]

```sh
onus help                 # commands and guide topics
onus help diff            # the flags of one command
onus help configuration   # a guide topic
```

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Success, including reports that contain findings |
| 1 | A usage error (unknown flag, missing argument) or a runtime error (unreadable directory, unknown git ref, invalid onus.yaml) |
| 2 | A `--fail-on` condition was met |

Exit code 2 is never used for errors, so CI can tell "Onus found something" from "Onus could not run".


---

## Configuration

URL: https://onushq.com/docs/configuration

The onus.yaml reference: components, rules, labels, extractors


<!-- Generated by npm run docs:sync from crates/onus-cli/guide/configuration.md in onushq/onus; edit it there. -->

# Configuration: onus.yaml

Onus works without configuration. An `onus.yaml` at the repository root adds what Onus cannot infer: which components are sensitive, which boundaries must hold, how your events are published, and SDKs it does not know. `onus init` writes a starter file; the format is in [schemas/onus-config.schema.json](https://github.com/onushq/onus/blob/main/schemas/onus-config.schema.json). `onus ui` edits it with a form: every edit is checked before it is saved, a save never overwrites a change made to the file meanwhile, and the map is rebuilt with the new config at once (as it is for any edit to the file: the map server follows onus.yaml like any other file).

## A complete example

```yaml
version: 1
components:
  orders:           { path: "services/orders/**",           owners: ["@team-orders"] }
  notifications:    { path: "services/notifications/**",    owners: ["@team-growth"] }
  user-preferences: { path: "services/user-preferences/**", labels: [pii] }
  billing:          { path: "services/billing/**",          labels: [payments] }
contracts:
  UserPreferences:
    symbol: "user-preferences:src/types.ts#UserPreferences"
    invariants: ["phone numbers are stored in E.164"]
rules:
  - deny: { from: billing, to: notifications.internal }
labels:
  payments: { sensitivity: high }
  pii:      { sensitivity: high }
extractors:
  events:
    publish:   ["bus.publish($EVENT, ...)"]
    subscribe: ["bus.subscribe($EVENT, ...)"]
  externals:
    "@acme/sms": { vendor: "Acme SMS", category: sms, egress: [phone] }
  prisma:
    clients: [prisma, db]
tests:
  globs: ["**/*.test.ts", "e2e/**"]
  command: "npx vitest run {test}"
  coverage: ["coverage/lcov.info"]
testData: ["fixtures/**"]
```

Unknown keys are an error, so a typo never silently does nothing.

## Which onus.yaml a report uses

`onus diff` and `onus report` build both versions with the **base** version's onus.yaml (or `--config`). A pull request therefore cannot relax the rules it is checked against; if it changes onus.yaml, that change is itself a row needing a person.

## version

Must be `1`.

## components

A map from component id to its settings. Ids may not be empty or contain `:`, `#`, `/` or spaces.

- `path` (required): a glob, or a list of globs, of the component's files, such as `"services/orders/**"`. When several components match a file, the most specific one wins.
- `kind`: `service`, `package` or `module`. Default: `service` under services/ or apps/, `package` under packages/ or libs/, otherwise `module`.
- `owners`: default: the last matching rule in CODEOWNERS (looked up in .github/, the root, then docs/).
- `labels`: sensitivity labels, such as `payments`, `auth`, `pii` or your own.
- `entrypoints`: source files that define the public surface, relative to the component folder. Default: from package.json `exports`, `types`, `module` or `main`, mapped from build output back to source (`dist/index.js` → `src/index.ts`), else `src/index.*` or `index.*`.

Without a `components` section, Onus finds components itself:

- Cargo packages (`Cargo.toml` with a `[package]`) and Python projects (`pyproject.toml` with a project name) are components named after the package.
- In an Nx repository (an `nx.json` at the root), every folder with a `project.json` is a component, named after the project. `projectType: application` is a service and `library` a package.
- npm, pnpm or yarn workspace packages are components too; where a workspace package contains Nx projects, each file belongs to the most specific one.
- Failing both, every folder under services/, packages/ and apps/.

Files outside every component belong to `root`.

Only symbols reachable from an entrypoint (through exports and re-exports) are public contracts. A component with no entrypoint has no public surface; for libraries Onus notes it in the map, while applications are expected to have none.

## contracts

Names important contracts and the invariants people rely on. `symbol` is a map id, `<component>:<path inside the component>#<name>`; list all ids with `onus map . --json` and look under `symbols`. The invariants are repeated on any row that changes the contract. An id that matches nothing is noted in the map.

## rules

Boundary rules, evaluated on the new version of the code. Only new violations are reported.

```yaml
rules:
  - deny: { from: billing, to: notifications }            # billing may not use notifications at all
  - deny: { from: billing, to: notifications.internal }   # only its public surface
```

A reference is an import, a call or a type reference. When onus.yaml declares components, both sides must be among them, and `from` and `to` must differ. Use `--fail-on rule-violation` to fail CI on a new violation.

## labels

The sensitivity of each label: `low`, `medium` or `high`. Labels of medium or high sensitivity make a component sensitive: new data writes and notable edits there become security-sensitive. `payments`, `auth` and `pii` are high by default; set one to `low` to turn that off.

## extractors.events

Call patterns that publish and subscribe to events. `$EVENT` marks the argument holding the event name; `...` stands for the rest.

```yaml
events:
  publish:   ["bus.publish($EVENT, ...)", "emitter.emit($EVENT, ...)"]
  subscribe: ["bus.subscribe($EVENT, ...)", "@OnEvent($EVENT)"]
```

A pattern matches the call itself and any call that ends with it, so `bus.publish` also matches `this.bus.publish` and `app.bus.publish`. Patterns starting with `@` match decorators. Declaring patterns replaces the defaults:

```text
publish:   bus.publish($EVENT, ...), eventBus.publish($EVENT, ...), events.publish($EVENT, ...)
subscribe: bus.subscribe($EVENT, ...), eventBus.subscribe($EVENT, ...), events.subscribe($EVENT, ...), @OnEvent($EVENT)
```

Event names are read from string literals, constants (also imported ones) and enum members. A name computed at runtime is recorded with low confidence and noted in the map.

## extractors.externals

External services, keyed by the npm package of their SDK. They extend, and for the same package override, the built-in registry.

```yaml
externals:
  "@acme/sms": { vendor: "Acme SMS", category: sms, egress: [phone], hosts: [api.acme-sms.example] }
```

- `vendor`: the name shown in reports.
- `category`: `sms`, `email`, `payments`, `ai`, `analytics`, `monitoring`, `storage`, `chat`, `http` or your own.
- `egress`: kinds of data that leave the system through it: `phone`, `email`, `payment`, `bank-account`, `pii`, `text`, `files`, `errors` or your own. A component sending a new kind is security-sensitive.
- `hosts`: hostnames, so `fetch("https://api.acme-sms.example/...")` and `axios` calls count as calls to this vendor. Calls to other literal hosts are reported under the host name.

Built-in registry:

| Package | Vendor | Category | Egress |
|---|---|---|---|
| twilio | Twilio | sms | phone |
| stripe | Stripe | payments | payment |
| @sendgrid/mail, @sendgrid/client | SendGrid | email | email |
| nodemailer | SMTP email | email | email |
| mailgun.js | Mailgun | email | email |
| postmark | Postmark | email | email |
| @aws-sdk/client-ses | AWS SES | email | email |
| @aws-sdk/client-sns | AWS SNS | sms | phone |
| @aws-sdk/client-s3 | AWS S3 | storage | files |
| @slack/web-api | Slack | chat | text |
| openai | OpenAI | ai | text |
| @anthropic-ai/sdk | Anthropic | ai | text |
| @segment/analytics-node | Segment | analytics | pii |
| posthog-node | PostHog | analytics | pii |
| @sentry/node | Sentry | monitoring | errors |
| plaid | Plaid | payments | bank-account |
| braintree | Braintree | payments | payment |

An SDK counts as called when a function calls something imported from it, including through a class field declared with the SDK's type (`private readonly client: AcmeSmsClient` and then `this.client.send(...)`).

## extractors.packs

Framework packs: YAML files of tree-sitter queries that say what a pattern in the code means (routes, events, data access, other relationships), relative to onus.yaml. See [`onus help plugins`](/docs/plugins).

```yaml
extractors:
  packs: [onus/packs/nestjs.yaml]
```

Packs are read from the base version of a change, like this file.

## extractors.prisma

`clients`: identifiers that hold a Prisma client (default: `prisma`). Calls such as `prisma.payment.update(...)` become writes to `payment`; `findMany`, `count` and the other read operations become reads. Raw queries (`$queryRaw`, `$executeRaw`) are noted in the map, since their tables are unknown.

## tests

`globs`: which files are tests. Declaring globs replaces the defaults:

```text
**/*.test.*  **/*.spec.*  **/__tests__/**  **/test/**  **/tests/**  **/e2e/**
```

`command`: how to run one test file, with `{test}` replaced by its path, such as `npx vitest run {test}`. `onus escalation assess` uses it to reproduce the failing test an escalation names, in a container built from `environment:` ([`onus help scopes`](/docs/scopes)). Without it, failing tests are not reproduced, so no escalation is granted by policy. A command without `{test}` would run every test, so it reproduces nothing either.

`coverage`: coverage files of the working tree (lcov, Cobertura XML or Istanbul JSON), relative to the repository root, for the map agents query (`onus mcp`, `onus query`). Each rebuild reads the ones that exist, and leaves out any source file edited after the coverage file was written, with a note. With them, `onus_tests_for` says which tests ran a target, and finds tests that only reach it through other code ([`onus help agents`](/docs/agents)). Reports read coverage only from `--coverage` and `--evidence` ([`onus help environments`](/docs/environments)).

## testData

Globs of files that are test data rather than code: fixture projects, sample apps, recorded responses.

```yaml
testData:
  - fixtures/**
  - e2e/recordings/**
```

Test data is left out of the map, so a fixture app's imports, services and contracts do not show up as your code. Changes to it are summarized in one "changed lines of test data" row, and config files inside it (a fixture's package.json or tsconfig.json) are not reported as config changes.

Secret-shaped values added in test data are not counted as committed secrets: `fail-on: secrets` does not trip on them, and they appear as one row, "... added in test data", that names the files without the values. Declare only folders that hold fake credentials on purpose. As with every setting, the report uses the base commit's onus.yaml, so a pull request cannot declare its own new secret as test data.

## Files Onus never reads

Folders named .git, .onus (where Onus keeps its records), node_modules, dist, build, out, .next, .turbo, .cache, coverage, target or vendor; anything ignored by a .gitignore inside the tree; files over 2 MB; and *.min.js files.

## lanes

What happens to a change after it is reported: the default lane, rules that set or raise it, the built-in risk inputs, a learned model that may raise it, the shares of automatic merges a person audits before and after merging, the record an agent setup needs before it may auto-merge, whose review lets a human-lane change through, an optional taste reviewer and the configurations the judge rotates between, and how each lane's changes meet production traffic. See [`onus help lanes`](/docs/lanes) and [`onus help production`](/docs/production).

```yaml
lanes:
  default: judge          # auto-merge, judge, human or blocked
  auditRate: 0.05         # would-be auto-merges sent to a person before merging
  auditAfterMerge: 0.05   # changes approved without a person, audited after they merge
  minRecord: 10
  approval: owner         # whose review counts in the human lane: owner (default with owners) or member
  rules:
    - { lane: auto-merge, match: every, kinds: [internal], components: [docs] }
    - { lane: human, subkinds: [migration-changed] }
  judges:                                  # one judges each change; optional
    - name: default                        # uses lanes.taste
    - name: strict
      taste: { command: [./scripts/review-strict.sh] }
      heldOutLimit: 20                     # at most this many held-out checks
  inputs:                                  # each key optional; these are the defaults
    blastRadius: { judge: 3 }              # other components that depend on a row
    tests: { untested: judge }             # code no test or trace reaches
    confidence: { low: judge }             # rows on parts of the map Onus could not resolve
    history: { days: 90, reverts: { judge: 1 }, incidents: { human: 1 } }
    coverage:                              # off unless written
      minChanged: 0.8
      required: false
      commands: ["npm test -- --coverage"] # whose recorded coverage counts
  learned:                                 # off unless written
    model: onus.lanes-model.json           # from onus lanes train, read at the base commit
    judge: 0.6                             # raise to the judge at or above this risk
    human: 0.85                            # raise to a person at or above this risk
  rollout:                                 # each lane optional; built-in plans otherwise
    judge:
      strategy: canary                     # none, canary or flag
      steps: [5, 25, 100]                  # % of traffic
      bakeMinutes: 30
      guards:
        - { metric: error_rate, maxRatio: 1.5 }
        - { metric: checkout_conversion, minRatio: 0.97 }
```

Inputs only raise a lane. A threshold of N means N or more, and the highest lane whose threshold is met applies (`judge`, `human`, `blocked`). Writing a key replaces its default as a whole: `blastRadius: { human: 10 }` has no judge threshold, and `blastRadius: {}` turns the input off. A lane of `auto-merge` turns `tests` or `confidence` off. Thresholds are at least 1 and must not go down as the lane goes up; `history.days` is 1 to 3650.

`coverage` reads the report's coverage of the head ([`onus help reports`](/docs/reports)): when tests ran less than `minChanged` (a share from 0 to 1) of the changed executable lines, the change goes to the judge. So does a change to a file with runtime code that the coverage leaves out (`notMeasured`): coverage of other files cannot let it through. With `required: true`, a change without coverage goes to the judge too. A change with no changed executable lines, and no changed file the coverage leaves out, passes. Coverage given with `--coverage` counts. Coverage an environment recorded counts only when its run's command is one of `commands`, written exactly as `onus env run` ran it: an agent picks the commands it runs, and one could write a coverage file. When the report holds recorded coverage from another command, the change goes to the judge, whatever `required` says: an extra run must not hide an honest one. The input runs only while the change would auto-merge.

Held-out checks live outside the repository, in a suite given with `--held-out` ([`onus help lanes`](/docs/lanes)). `heldOut: { command, image, setup }` still works as one check, but agents can read onus.yaml. `judges` names must be unique, without `@` or spaces; the judge picks one per change, and an empty list turns rotation off.

The learned model also only raises a lane, and never to `blocked`. Its thresholds need `0 < judge <= human <= 1`, and the model file's name must end in `lanes-model.json`, so a change to it is a rule of the game and goes to a person.

`rollout` sets the plan of `auto-merge`, `judge` and `human` changes; a lane left out keeps its built-in plan ([`onus help production`](/docs/production) has the table), and `blocked` has none. Steps go up strictly from 1 to 100 and end at 100, and `none` takes no steps. A guard names a `metric` and at least one of `max`, `min` (on the value), `maxRatio` and `minRatio` (on the value over its baseline).

## environment

The container `onus env create` builds from a commit: its image (default: the devcontainer's), a setup command run once per lockfile and kept as a warm image, a seed command, and the files a run writes that are kept as evidence. See [`onus help environments`](/docs/environments).

```yaml
environment:
  image: node:22-alpine
  setup: npm ci
  seed: node scripts/seed-test-data.mjs
  evidence: ["reports/**/*.xml"]     # JUnit XML
  traces: ["otel/*.json"]            # OTLP JSON
  coverage: ["coverage/lcov.info"]   # lcov, Cobertura XML or Istanbul JSON
  lockfiles: [package-lock.json]     # default: the usual lockfiles
  egressImage: ubuntu/squid          # the proxy for hosts a token names
  behavior:                          # onus report --behavior
    command: "npx vitest run --reporter=junit --outputFile=reports/onus-behavior.xml {files}"
    junit: ["reports/onus-behavior*.xml"]
    budget: 600
    maxFiles: 40
    depth: 1
```

`behavior` is the behavior diff (`onus report --behavior`): `command` runs the selected test files (`{files}`, required) and writes JUnit XML to a file `junit` matches; `budget` is seconds for the whole diff, `maxFiles` the most test files run, and `depth` the code-dependency hops (0 to 2) from changed code to the tests chosen. It is read from the base commit like the rest of the config. See [`onus help environments`](/docs/environments).


---

## Environments and evidence

URL: https://onushq.com/docs/environments

Environments built from a commit, the evidence store, traces and coverage into the map, and the behavior diff


<!-- Generated by npm run docs:sync from crates/onus-cli/guide/environments.md in onushq/onus; edit it there. -->

# Environments and evidence

An environment is a container built from your repository at a commit. Commands run in it leave evidence (their output, test results, traces and coverage) in a content-addressed store, so a reviewer, or the judge, relies on what an environment recorded instead of what an agent says it ran. Environments need Docker or Podman.

## Declaring the environment

In onus.yaml:

```yaml
environment:
  image: node:22-alpine
  setup: npm ci                          # with network, once per lockfile
  seed: node scripts/seed-test-data.mjs  # synthetic data, in each new environment
  evidence: ["reports/**/*.xml"]         # JUnit XML the tests write
  traces: ["otel/*.json"]                # OTLP JSON trace files
  coverage: ["coverage/lcov.info"]       # lcov, Cobertura XML or Istanbul JSON
```

Without an `image`, Onus uses `.devcontainer/devcontainer.json`: its `image`, and its `onCreateCommand`, `updateContentCommand` and `postCreateCommand` as the setup. A devcontainer that builds from a Dockerfile needs the built image named in `environment.image`.

The declaration comes from your working tree (or `--config`), never from the commit under test: a change cannot give itself a different environment.

## Creating one

```sh
onus env create --ref feature/sms --name sms
onus env create --ref HEAD --token "$TOKEN" --key-public root.pub   # named after the token's task
```

1. **Warm image.** `setup` runs once per image, setup command and lockfile contents, and the result is kept as `onus-warm:<key>`. The next environment with the same lockfiles starts from it in about a second.
2. **The commit's files** are copied in. Files of the commit the warm image was built from are removed first, so deletions take effect.
3. **Seed.** `seed` runs, so tests get synthetic data, never production data.

The container has no capabilities, 4 GB of memory, 2 CPUs and at most 1024 processes.

**Network:** none. If the task's token names hosts (`net:host:api.example.com`, or `*.example.com` for subdomains), the environment sits on an internal network whose only way out is an egress proxy that allows exactly those hosts (`ubuntu/squid` by default; `environment.egressImage` to change it). `HTTP_PROXY` and `HTTPS_PROXY` point at it.

**Secrets:** each `secret:NAME` in the token is set as `NAME` from your `ONUS_SECRET_NAME` variable; creating fails if it is not set. No other secret reaches the container, and secret values are replaced by `[secret NAME]` in everything the store keeps.

## Running commands

```sh
onus env run sms -- npm test
onus env run sms -- npx vitest run --reporter=junit --outputFile=reports/unit.xml
```

Each run prints a test run naming its manifest, and exits 1 when the command failed. The output is ready for `onus submit --evidence`:

```sh
onus env run sms -- npm test > run.json
onus submit --base main --head feature/sms --evidence run.json --agent-tool claude-code --out submission.json
```

The judge checks every test run that names a manifest against the store: the manifest must be there, unaltered, from the head commit, with the same command and exit code. It still re-runs the command in a fresh container with the environment's setup and seed.

```sh
onus env list                     # name, commit, state, image, hosts
onus env destroy sms              # the container, its proxy and its network
```

## The evidence store

Runs are kept in the repository's git directory (`.git/onus/evidence`, shared by its worktrees; `--store` for another place):

```sh
onus evidence list                               # id, commit, environment, exit code, command, test counts
onus evidence show 3fa2c1d9                      # a manifest
onus evidence show 3fa2c1d9 --artifact -         # its output log
onus evidence show 3fa2c1d9 --artifact otel/trace.json > trace.json
```

A manifest records the commit, the command, the exit code, start and finish times, the environment (image, warm image, setup, seed, hosts, secret names) and its artifacts with their sha256: the log, the JUnit files the run wrote that match `evidence` (with test counts summed), the trace files that match `traces`, and the coverage files that match `coverage`. A manifest is named by the sha256 of its own contents, and artifacts by theirs, so an edited file no longer matches and is refused.

## Traces into the map

Traces show calls static analysis cannot see, such as an event bus dispatching to a handler, or a call into another service:

```sh
onus map . --traces trace.json
onus report --base main --head HEAD --traces trace.json
```

Spans with `code.filepath` and `code.function` (OpenTelemetry's code attributes) resolve to symbols, and each span's parent is its caller: the pair becomes a `calls` edge with confidence `traced`. A span of a service named like a component ties the caller to that component. Traced edges are only added; `diff` and `report` add them to both trees, so they never show up as changes. Files may hold one OTLP JSON document or one per line, as the OpenTelemetry Collector's file exporter writes them.

Production traces are kept with the records: `onus signals traces` turns an export into one `trace` signal in `signals.jsonl`, and `--traces` reads that file too, taking the calls of its `trace` lines and skipping the rest ([`onus help production`](/docs/production)). A call the map had only guessed (confidence `inferred` or `low`) that a trace observed is upgraded to `traced`; `onus map` says how many (`traces: 3 recorded calls, 2 traced calls added, 1 confirmed, 1 upgraded`). Static, compiler and declared edges stay as they are. With `records: true`, the action passes the records' `signals.jsonl` to `onus report --traces`.

## Coverage into the map

Coverage says which lines tests ran. Onus reads lcov (Jest, Vitest, c8, nyc, cargo-llvm-cov, `coverage lcov`), Cobertura XML (`coverage xml`, JaCoCo and .NET converters) and Istanbul JSON (`coverage-final.json`), and tells them apart by their content:

```sh
onus map . --coverage coverage/lcov.info --json
onus diff base/ head/ --coverage head-coverage.xml
onus report --base main --head HEAD --coverage coverage/lcov.info --coverage py/coverage.xml
```

Coverage applies to the head only: its line numbers belong to the commit the tests ran at. Check out that commit before running the tests. Coverage that names a line past the end of a file was measured at another commit, and that file is left out with a note. Paths may be absolute (`/home/runner/work/shop/shop/src/a.ts`): the longest map path they end with counts. Coverage of test files is dropped.

The map keeps each measured file's covered and uncovered lines. An lcov `TN:` record that names a test file (`TN:services/billing/src/discount.test.ts`) also links that test to the symbols it ran (a bare file name links only when one test file has it), so `onus query tests-for noDiscount` finds a test that only imports `applyDiscount`. `onus map` says what it read (`coverage: 1 sources (lcov 1), 41 files matched, 3 not in the map; 1,204 of 1,530 lines ran; 18 test links`).

A run in an environment keeps the files that match `environment.coverage` as `coverage` artifacts. `onus report --evidence run.json` reads them, as long as the manifest is intact and the run was at the head commit; a run at another commit is skipped with a note, and so is a kept file that is not coverage, such as an HTML report the glob caught. They count as `recorded`; a file given with `--coverage` counts as `supplied`. Each recorded source keeps its run's command. A submission made without a report (`onus ci pr`, `onus_submit`) reads the recorded coverage of its evidence the same way:

```sh
onus env run ci -- npm test -- --coverage
onus report --base main --head HEAD --evidence run.json
```

An intact manifest proves what a run recorded, not who picked the command. An agent picks its own commands (`onus_env_run`), and one of them could write a coverage file. So the coverage lane policy counts recorded coverage only from the commands it names in `lanes.inputs.coverage.commands`, such as `npm test -- --coverage`, and sends a change with recorded coverage from any other command to the judge ([`onus help lanes`](/docs/lanes)). The command still runs the change's own code, so coverage is evidence that tests ran the lines, not proof.

For agents, `tests.coverage` in onus.yaml lists coverage files of the worktree ([`onus help configuration`](/docs/configuration)). The map server reads them on each rebuild and leaves out any source file edited after the coverage was written, with a note in `onus_status`.

## Behavior diff

`onus report --behavior` runs the tests that reach a change at the base and at the head, and reports which cases now behave differently (ADR 0019). It is off unless asked for, and needs a container engine. Declare the command in onus.yaml:

```yaml
environment:
  image: node:22-alpine
  setup: npm ci
  behavior:
    command: "mkdir -p reports && npx vitest run --reporter=junit --outputFile=reports/onus-behavior.xml {files}"
    junit: ["reports/onus-behavior*.xml"]   # the default
    budget: 600     # seconds for everything, environments included (default 600)
    maxFiles: 40    # most test files run (default 40)
    depth: 1        # code-dependency hops from changed code to tests, 0 to 2 (default 1)
```

`{files}` is replaced with the selected test files, shell-quoted and relative to the repository root. The command must write JUnit XML to a file `junit` matches. Like the rest of the report's config, it comes from the base commit (or `--config`), so a pull request cannot change the command that checks it.

```sh
onus report --base main --head HEAD --behavior
onus report --base main --head HEAD --behavior --behavior-budget 300 --fail-on behavior
```

1. **Selection.** From the maps: changed test files first, then the tests that exercise a changed file, then those that exercise code depending on it, up to `depth` hops. Both maps are asked, so code deleted at the head still selects its base tests. At most `maxFiles` run; the rest are counted as `truncated`. When nothing is selected, the report says "no tests reach the changed code", which is a fact worth knowing too.
2. **Base and head.** One environment per commit, made in parallel, each running the selected files that exist on its side.
3. **Retry.** Files with cases that fail at the head, and passed or did not exist at the base, run once more at the head. A case that passes then is flaky: no row, and it is listed in `behavior.flaky`.
4. **Cross.** The base versions of selected test files the change edited (and their changed `__snapshots__` files) are written over the head's tree and run against the head's code. Its manifest records this as `overlay: {fromCommit, paths}`, and the judge never accepts such a run as evidence of the head.
5. Both environments are destroyed, also after an error or a timeout.

Each case is compared, and becomes one of four rows, grouped per component ([`onus help reports`](/docs/reports)): `behavior-newly-failing`, `behavior-changed`, `behavior-newly-passing` and `behavior-output-changed`. A case whose name and file are unknown to the maps counts under `root`. Cases failing at both sides with the same message are listed in `behavior.alreadyFailing`.

Every run is an ordinary evidence manifest, so `onus evidence show <id>` shows its log and JUnit. Each step gets what is left of the budget; one that would start after it is skipped, a run still going when it ends is stopped, and the status becomes `partial` with the reason. A newly failing case whose retry did not run still gives a row, at confidence `inferred`. Creating an environment is not stopped part way, so a slow setup can take the time past the budget. A problem never fails the report: without `environment.behavior`, `{files}` in the command, a container engine or an image, the status is `skipped` with the reason, and one `onus: behavior: …` line goes to stderr.

Limits: only runners that write JUnit and take test files as arguments; the cross run uses the head's versions of helpers and fixtures; a case renamed at the head pairs only by name, so its base and head runs are not compared (its cross run still counts); flakiness is ruled out with one re-run; and traces from these runs are not added to the map.


---

## Getting started

URL: https://onushq.com/docs/getting-started

Install Onus, build a map and read your first report


<!-- Generated by npm run docs:sync from crates/onus-cli/guide/getting-started.md in onushq/onus; edit it there. -->

# Getting started

Onus turns a change to a codebase into a short report of changes in meaning: new external services, contract changes, new relationships between components, weakened tests, broken rules. It reads TypeScript and JavaScript today.

Onus only reads files. It never installs dependencies or runs the code it analyzes, so it is safe to run on pull requests from forks.

## Install

With Homebrew, on macOS or Linux:

```sh
brew install onushq/tap/onus
```

Or, without Homebrew, the installer downloads the binary for your system from the latest GitHub release, checks its SHA-256 and puts it in ~/.local/bin:

```sh
curl -fsSL https://onushq.com/install.sh | sh
```

Set ONUS_VERSION=v0.1.0 to pin a version and ONUS_INSTALL_DIR to install elsewhere. Archives for every platform, including Windows, are at https://github.com/onushq/onus/releases.

Or build from source with Rust (https://rustup.rs):

```sh
git clone https://github.com/onushq/onus && cd onus
cargo build --release          # the binary is target/release/onus
```

Or install the binary into ~/.cargo/bin:

```sh
cargo install --git https://github.com/onushq/onus onus-cli --locked
```

Check it works:

```sh
onus --version
```

## Your first map

The map is Onus's picture of a repository: components, the contracts they expose, how they depend on each other, events, data access, external services and tests.

```sh
onus map path/to/repo           # a summary
onus map path/to/repo --json    # the whole map
```

The summary lists each component with its kind, public symbols, labels and owners, the external services found, and anything Onus could not resolve.

## Your first report

Compare two git refs of a repository:

```sh
onus report --repo path/to/repo --base main --head my-branch
```

Or two directories:

```sh
onus diff old-checkout new-checkout
```

Try it on the fixture that ships with Onus, the manifesto's "text customers when their order ships" change:

```sh
cp -R fixtures/shop/base /tmp/shop-head
cp -R fixtures/shop/scenarios/s1-sms-alerts/services /tmp/shop-head/
onus diff fixtures/shop/base /tmp/shop-head
```

You get four rows instead of 1,408 changed lines. [`onus help reports`](/docs/reports) explains how to read them.

## Tell Onus about your repository

Onus works without configuration: it finds components from npm, pnpm or yarn workspaces (or folders under services/, packages/ and apps/) and owners from CODEOWNERS. A small `onus.yaml` makes reports sharper: sensitivity labels, boundary rules, event patterns and SDKs Onus does not know.

```sh
onus init                       # writes a starter onus.yaml
```

Review it, uncomment the labels it suggests, and commit it. See [`onus help configuration`](/docs/configuration).

## Next

- [`onus help reports`](/docs/reports): reading a report
- [`onus help changes`](/docs/changes): every kind of change Onus reports
- [`onus help intent`](/docs/intent): checking a change against what it says it does
- [`onus help ci`](/docs/ci): running Onus on every pull request


---

## How Onus works

URL: https://onushq.com/docs/how-it-works

How maps are built and compared


<!-- Generated by npm run docs:sync from crates/onus-cli/guide/how-it-works.md in onushq/onus; edit it there. -->

# How Onus works

```text
base tree ──► build map ──┐
                          ├──► semantic diff ──► ranked rows ──► Markdown / JSON
head tree ──► build map ──┘         ▲
                                    └── line diff of the two trees
```

Onus builds a map of each version of the code and compares the maps, not the text. Every fact in a report comes from that analysis and a fixed sentence template; no language model writes any of it. Onus only reads files.

## 1. Building a map

Map building is a pipeline of providers: discovery providers find components, language providers analyze files, and fact providers add relationships. The ones below are built in; plugins add more, including SCIP indexes and language servers ([`onus help plugins`](/docs/plugins)).

**Files.** Onus walks the tree, skipping dependencies, build output and anything gitignored (see [`onus help configuration`](/docs/configuration)).

**Components** come from onus.yaml, else from Nx projects and npm, pnpm or yarn workspaces, else from the folders under services/, packages/ and apps/. Owners come from onus.yaml or CODEOWNERS. Each component's entrypoint comes from its package.json, mapped from build output back to source.

**Parsing.** Every .ts, .tsx, .js, .jsx, .mts and .cts file is parsed in parallel with tree-sitter. From each file Onus records:

- imports and exports, including aliases and re-exports;
- declarations: functions, interfaces, type aliases, classes, enums, constants and variables;
- each declaration's **shape**: parameters and which are optional, return types, fields and which are optional, all as normalized type text. A type that is inferred rather than written is marked unverified;
- each declaration's **fingerprint**: a hash of its code with comments, formatting, quote style, its own name and its local variable names removed. Two functions with the same logic under different names share a fingerprint;
- **body facts**: comparisons, guards, throws, awaits and empty catch blocks;
- **references**: calls and type uses, and which declaration they occur in;
- **patterns**: event publish and subscribe calls, Prisma reads and writes, `process.env` reads, calls into known SDKs, and `fetch`/`axios` calls to literal hosts;
- **tests**: cases with their full names, assertions, skip/only/todo markers and expected values.

**Linking.** Onus resolves every import itself, with no Node and no TypeScript compiler: relative paths, index files, tsconfig `paths` and `baseUrl`, and workspace package names mapped to their source. It follows re-export chains and respects local scope, so a call resolves to the declaration it really reaches. Imports of anything else become third-party packages.

**The map** gives every node a stable id: `billing:src/discount.ts#applyDiscount`, `event:OrderShipped`, `db-table:payment`, `config-key:SENDGRID_API_KEY`, `external:acme-sms`, `npm:date-fns`. Edges (`imports`, `calls`, `references-type`, `reads`, `writes`, `publishes`, `consumes`, `calls-external`, `reads-config`) connect them, each with the files and lines where it happens. Symbols reachable from an entrypoint are public; the rest are internal. The map also holds package dependencies, tests, boundary rules and diagnostics for anything Onus could not resolve. `onus map . --json` prints it.

## 2. The semantic diff

The passes run in this order:

1. **Matching.** Symbols with the same id are the same symbol. Of the rest, a removed and an added symbol with the same fingerprint are the same code: a move (same name, possibly into another component) or a rename (new name). A symbol with the same name and kind in another file whose members mostly overlap was moved and edited at once. Files that moved with identical content, or with only formatting and import-path changes, are matched too.
2. **Renames** become one row with the number of call sites updated; moves between components become one row per pair of components.
3. **Contracts.** Shapes of public symbols are compared, ignoring the order of object and union members: optional additions are additive; removals, new required members and unprovable type changes are breaking when a user or implementation outside the change was not updated.
4. **Boundary rules** from onus.yaml are checked on the new map; violations that already existed are dropped.
5. **Relationships** are compared per component: events published and consumed, tables read and written, external services called, and dependencies between components. A new vendor or a new kind of data leaving the system is security-sensitive.
6. **Packages.** New, changed and removed npm dependencies, and patched packages. An SDK of a newly reported external service is folded into that row.
7. **Risk classes.** Migrations, GraphQL operations, HTTP routes and authentication or authorization code get their own rows.
8. **Configuration** files are classified and the keys that changed are named; CI, policies, onus.yaml and CODEOWNERS are flagged as rules of the game, root build config and infrastructure as needing a person.
9. **Tests** are compared case by case for weakening; tests that moved, or went with the code they tested, are told apart.
10. **Notable edits** inside functions on both sides: flipped comparisons, changed constants, removed guards, throws and awaits (unless they moved into another function), swallowed errors.
11. **Secrets** in added lines.
12. **Generated code.** Rows about files a tool wrote become one row per component.
13. **Internal rows.** Every row lists the lines it explains; changed lines no row explains collapse into one internal row per component.

Then rows that say the same thing are grouped ([`onus help changes`](/docs/changes)), hints are filled in (labels, blast radius, confidence), the intent check marks mismatches, and the rows are ranked ([`onus help reports`](/docs/reports)).

## Why it is built this way

- **Facts are computed, never generated.** A wrong fact costs more trust than a missing one, so every row comes from deterministic analysis.
- **Conservative under uncertainty.** What Onus cannot resolve is marked low confidence and ranked as higher risk, never dropped.
- **Deterministic.** Everything is sorted; there are no timestamps or absolute paths. The same inputs give byte-identical output.
- **Safe.** Nothing from the analyzed code is installed or run, so Onus can run on any pull request.
- **Fast.** A generated workspace of about 230,000 lines maps in under a second on a laptop.

The design and its decisions are in PLAN.md and docs/adr in the repository.


---

## The intent check

URL: https://onushq.com/docs/intent

Checking a change against its stated intent


<!-- Generated by npm run docs:sync from crates/onus-cli/guide/intent.md in onushq/onus; edit it there. -->

# The intent check

The gap between what a change says it does and what it actually does is the most important signal in a review. Onus checks it deterministically: you (or the agent that wrote the change) state the intent in a small block, and every row outside it is an intent mismatch, ranked at the very top and marked as needing a person.

## Stating an intent

In a pull request body, a fenced block:

````md
```onus-intent
summary: Add SMS alerts on OrderShipped
touches: [notifications]
contracts: [UserPreferences]
externals: [Acme SMS]
```
````

Or a YAML file with the same keys. Pass either to `--intent`:

```sh
onus report --base main --head HEAD --intent pr-body.md
onus diff old new --intent intent.yaml
```

All keys are optional; unknown keys are an error. A file ending in `.md`, `.markdown` or `.txt` is read as Markdown: only its `onus-intent` block counts, and without one the check is skipped with a warning on stderr. Other files are read as YAML, unless they look like Markdown and have no block.

## What each key covers

- `summary`: free text, shown in the report.
- `touches`: the components the change may touch, by id (`notifications`), or path globs (`services/notifications/**`, any entry with `/` or `*`). A row is inside `touches` when its component is listed, or when every file it points at matches one of the globs.
- `contracts`: the contracts the change may alter, by name (`UserPreferences`) or map id. Applies to contract rows (subkinds `contract-*` and `export-*`).
- `externals`: the external services the change may start calling, by vendor (`Acme SMS`), id (`acme-sms`) or SDK package (`@acme/sms`), case-insensitive. Applies to `new-external-service` and `new-external-call` rows.

Every row must be inside `touches`. Contract rows must also be listed in `contracts`, and external-service rows in `externals`. Everything else is a mismatch, including the internal row of a component outside `touches`.

## What the report shows

```md
**Intent check:** **2 changes outside stated intent** · **Boundary rules:** no new violations

Stated intent: "Add structured fields to log lines"

- 10 lines of new code inside `billing`: `billing` is not in `touches` (logger)
- `billing` now writes to the `payment` table: `billing` is not in `touches` (logger)
```

The mismatching rows move to the top of the table with "Outside stated intent" in their Kind column. In JSON, they have `hints.intentMismatch: true`, and `intentCheck.mismatches` lists `{ changeId, reason }` for each.

## Tips

- Ask coding agents to end every pull request description with an `onus-intent` block. It costs them nothing and makes scope creep visible.
- Keep `touches` tight. A change that legitimately touches more should say so; that is the point.
- An intent never hides a row: rows inside it are still reported and ranked as usual.


---

## Risk lanes and the judge

URL: https://onushq.com/docs/lanes

Risk lanes, change submissions, the learned model, the verifying judge, outcome records and provenance


<!-- Generated by npm run docs:sync from crates/onus-cli/guide/lanes.md in onushq/onus; edit it there. -->

# Risk lanes and the judge

Once Onus has described a change, lanes decide what happens to it: merge it automatically, have the judge verify it, send it to a person, or block it. Lanes come from rules you write and from hard floors no rule can lower. A learned model you train and commit can raise a lane, never lower it.

| Lane | What happens |
|---|---|
| `auto-merge` | It merges when required checks pass (the action can enable GitHub's auto-merge). |
| `judge` | `onus judge` verifies it; it merges on `approve`. |
| `human` | An owner of what changed (`lanes.approval`) who did not open it approves its head commit. Its owners are asked to review. |
| `blocked` | It may not merge as it is. |

## Submitting a change

An agent (or a person) bundles a change with what a reviewer needs and nothing of its reasoning:

```sh
onus submit --base main --head HEAD --intent intent.yaml --evidence run.json \
  --token "$TOKEN" --key-public root.pub \
  --agent-tool claude-code --agent-model sonnet --agent-config default --out submission.json
```

The submission holds the stated intent, Onus's report, every changed path, the test runs from `onus run-test` (to be re-run), the token's verified scope, granted escalations (`--escalation <id>`, each verified with `--key-public`: granted, for the token's task, unchanged since it was filed; requests are read from `.onus/escalations`, or `--escalations-dir`), approvals (`--approve <row id>=<who>`), and the agent setup. When the token names an agent, that is the agent setup, whatever the flags say.

## Classifying

```sh
onus classify --submission submission.json --outcomes outcomes.jsonl
onus classify --report report.json              # a change without a submission (CI)
onus classify --submission submission.json --outcomes outcomes.jsonl --change acme/shop#42
```

The answer is the lane and every rule that applied, in order. Each entry has a `source` (`default`, `policy`, `input`, `floor`, `model`, `record` or `audit`), a reason, and the ids of the report rows behind it (`rows`):

1. The policy's `default` lane, or a lower one when a `match: every` rule covers every row of the change (for example, internal changes in a docs component).
2. Rules that raise the lane when any row matches.
3. Risk inputs (`lanes.inputs`, below). They can only raise the lane.
4. Hard floors:
   - **Blocked:** a committed secret, a write outside the token's scope, weakened tests without a person's approval, or tests that pass at the base and fail at the head (`behavior-newly-failing`, from `onus report --behavior`) without a person's approval of that row.
   - **Human:** rows in sensitive code (`auth`, `payments`, `pii`, or any label of medium or high sensitivity), security-sensitive rows, rules of the game (tests, CI, policies, `onus.yaml`, and edits to the code of a declared contract), rows outside the stated intent, and third-party code new to the repository (an npm package no component used before).
   - **Judge:** a new dependency never auto-merges: a package new to a component, or a new dependency between components.
5. The learned model (`lanes.learned`, below), read from the base commit: at or above its thresholds it raises a lower lane to `judge` or `human`. It never lowers a lane and never blocks.
6. An agent setup with fewer than `minRecord` merged changes on record, or with an incident or a rollback among its recent changes, cannot auto-merge. A share (`auditRate`) of the remaining auto-merges is sent to a person before merging, chosen by a hash of the head commit.

Every classification also carries the change's `rollout` plan for its lane: how it should meet production traffic, and when it rolls back ([`onus help production`](/docs/production)).

## Risk inputs

Four built-in inputs read facts Onus computes for every change. They are on by default, each can be tuned or turned off, and none can lower a lane. A fifth, `coverage`, is off unless written:

| Input | Fires when | Default |
|---|---|---|
| `blastRadius` | A row changes something other components depend on (`dependentComponents` in the report), including a body-only edit of a function they call. The highest lane whose threshold the count meets applies. | 3 or more components → `judge` |
| `tests` | A row changes code no test exercises and no runtime trace has observed (`tested: untested`). | `judge` |
| `confidence` | A row rests on parts of the map Onus could not resolve (`confidence: low`). | `judge` |
| `history` | A component the change touches had reverts, rollbacks or incidents in the last `days` days, read from `--outcomes` and the production signals beside it (`signals.jsonl`). A planned rollback does not count. | a revert → `judge`, an incident → `human`, over 90 days |
| `coverage` | Tests ran less than `minChanged` (0 to 1) of the change's changed executable lines, from coverage of the head ([`onus help reports`](/docs/reports)), or the coverage leaves out a changed file with runtime code; with `required: true`, also a change without coverage. | off |

```yaml
lanes:
  inputs:
    blastRadius: { judge: 3, human: 10 }   # `{}` turns it off
    tests: { untested: judge }             # `auto-merge` turns it off
    confidence: { low: judge }
    history:
      days: 90
      reverts: { judge: 1 }
      incidents: { human: 1 }
    coverage: { minChanged: 0.8, commands: ["npm test -- --coverage"] }   # off unless written
```

Every classification also carries `features`: what the change looked like when it was classified, which the learned model trains on, and `learned` when `lanes.learned` is set.

Test reach is per file: a file counts as tested when a test in the map exercises anything in it, and as traced when a runtime trace saw it ([`onus help environments`](/docs/environments)). It is not line coverage; `coverage` is. Coverage comes from `onus report --coverage` or `--evidence`, or, for a submission made without a report (`onus ci pr`, `onus_submit`), from the coverage its evidence runs recorded at the head commit ([`onus help environments`](/docs/environments)). The `coverage` input runs only while a change would auto-merge. It counts recorded coverage only from the commands listed in `commands`, since an agent picks the commands it runs and one could write a coverage file; when the report holds recorded coverage from any other command, the change goes to the judge, required or not. Coverage given with `--coverage` counts. History counts each change once per component, from every record in the window, so a revert and an incident count at the time they were recorded. Code outside every component counts as `root`. A backfill (`onus ci pr --at`) sees only what was recorded by then. Records shared by several repositories are scoped with `--change owner/repo#N`: only that repository's changes count, and the change itself is left out. `onus ci pr` does this for you.

## A learned model that only raises

Once outcome records show which changes went wrong, a model can learn from them. It may move a change up a lane, never below the lane the rules give it, and never to `blocked`.

```sh
onus ci records pull --dir rec
onus lanes train --outcomes rec/outcomes.jsonl          # writes onus.lanes-model.json
git add onus.lanes-model.json && git commit -m "Lanes model"

lanes:
  learned:
    model: onus.lanes-model.json   # the default
    judge: 0.6                     # raise to the judge at or above this risk
    human: 0.85                    # raise to a person at or above this risk
```

**What it learns from.** Every classification computes a fixed set of features from the report (rows of each kind, blast radius, dependent components, lines and files, novelty, sensitive code, rows that need a person, map confidence, test reach, unverified contracts, rule violations, a stated intent), the submission (passing and failing test runs) and the records (earlier changes and problems in the same components, the agent setup's record). `onus ci pr` keeps them on the pull record, `onus ci closed` copies them onto the outcome, and reverts, incidents and audits keep them. `onus outcomes record --classification <file>` copies them from a classification, for outcomes recorded by hand.

**What counts as a problem.** A change that had an incident, was reverted or rolled back (a planned rollback is not a problem: it counts as a clean merge), whose audit found a miss, or about which a person with write access said `/onus caught` ([`onus help ci`](/docs/ci)). A merged change counts as clean once it is `--settle-days` old (default 14) at the latest record's time, so reverts and incidents have had time to show. Open changes, changes closed without a catch, unsettled merges and records without features are left out, and the output says how many.

**Training.** A logistic regression on standardized features, class-balanced and L2-regularised, fitted by gradient descent from zero with a fixed number of steps. There is no randomness: the same records in any line order give the same file, byte for byte. A fifth of the changes, chosen by a hash of their ids, is held out: a first fit without them is measured on them, then the model is fitted on everything. It refuses with "too little data" (exit 1) below `--min-examples` (default 50) labelled changes or `--min-positives` (10) problems, or when the part left after holding out the fifth lacks problems or clean merges. With `--config` and `--out`, nothing is read from `--repo`, so it runs outside a repository. `--dry-run` measures and writes nothing. It prints:

```json
{ "out": "onus.lanes-model.json", "written": true, "model": "3f2a9c1e0b7d",
  "examples": 412, "positives": 23,
  "skipped": { "noFeatures": 80, "staleFeatures": 0, "unsettled": 12, "undecided": 35 },
  "holdout": { "examples": 83, "positives": 5, "auc": 0.82,
               "atJudge": { "raised": 0.21, "recall": 0.8 }, "atHuman": { "raised": 0.04, "recall": 0.4 } },
  "weights": [ { "feature": "kind.breaking", "weight": 1.21 }, … ] }
```

`raised` is the share of held-out changes at or above a threshold, and `recall` the share of held-out problems at or above it. Tune `judge` and `human` with them: lower thresholds raise more changes and catch more problems. The risk is a relative score, not a calibrated probability, because the classes are balanced.

**Applying it.** `onus classify`, `onus judge`, `onus ci pr`, `onus ui` and the MCP `onus_submit` tool read the model from the base commit (the submission's base; the working tree for `onus classify --report`), so a pull request cannot delete or retrain the model to avoid a raise. `--model <file>` hands in another one. A raise is listed with `source: "model"`:

```text
model → human: the learned model puts this change's risk at 0.91 (a person from 0.85, the judge from 0.60): 2 breaking rows (+1.42), blast radius 38 (+0.97), 3 earlier problems in billing (+0.61); model 3f2a9c1e0b7d, trained on 412 outcomes
```

When it does not raise, `learned` still holds the risk and its top factors, and the CI comment shows a **Learned risk:** line. A model file that is missing at the commit, was trained on another feature set (`stale`), or does not parse (`invalid`) is never an error: `learned.status` and `learned.note` say why, and the lane comes from rules only.

**Rules of the game.** The model file and `onus.yaml` decide lanes, so a pull request that changes either goes to a person (`lanes-model-changed`, `onus-config-changed`). Retrain after a release that adds features: an older model reports `stale` until then.

**What it is not.** Outcomes are shaped by the lanes changes got: a change a person reviewed was less likely to go wrong. The model learns what went wrong despite the lanes, which is the right target for raising a lane, but not a causal estimate of risk.

## The policy

```yaml
lanes:
  default: judge
  auditRate: 0.05
  auditAfterMerge: 0.05
  minRecord: 10
  rules:
    - { lane: auto-merge, match: every, kinds: [internal], components: [docs] }
    - { lane: human, subkinds: [migration-changed, route-added] }
  taste:
    command: [./scripts/review.sh]
  judges:
    - name: claude-reviewer                         # uses taste above
    - name: gpt-reviewer
      taste: { command: [./scripts/review-gpt.sh] }
    - name: strict
      heldOutLimit: 20
```

A rule matches a row by `kinds`, `subkinds`, `components` and `labels` (an empty list matches anything). [`onus help changes`](/docs/changes) lists the kinds and subkinds. Held-out checks are not in the policy: they live outside the repository (below).

## The judge

```sh
onus judge --submission submission.json      # exit 0 approve, 2 reject, 3 escalate
onus judge --submission submission.json --held-out ~/acme-held-out/shop
```

It verifies first and judges taste last, and stops at the first failure:

1. **Evidence:** each test run in the submission is run again at the head commit in a fresh container; a run that passed for the author must pass again. A run made in an environment (`onus env run`) names its manifest, and must match it: recorded at the head commit, with the same command and exit code ([`onus help environments`](/docs/environments)). The first run that fails stops the step; the rest are not re-run.
2. **Intent:** an intent must be stated, and no row may fall outside it.
3. **Contracts:** no breaking contract changes and no boundary-rule violations.
4. **Tests:** no weakened tests without a person's approval. With a report made with `--behavior`, a test edited to match changed behavior (`behavior-changed`) is a rule of the game, so it reaches a person instead.
5. **Held-out checks:** checks the author never saw, from a suite outside the repository, chosen from the map for this change (below). They run in order, most relevant first, up to the first failure. The author sees only counts and `a held-out check failed (exit N)`: never a check's id, command or output.
6. **Taste (optional):** `taste.command` gets the submission as JSON on stdin and prints `concern: …` lines. Concerns send the change to a person; taste can never approve, and it runs only when everything else passed. Onus itself calls no model.

Once a step fails, every later step is `skipped` with `not reached: <step> failed`, and no more containers start. So `reasons` holds one failing step's reasons: the first thing to fix. Run `onus_check` (or `onus query check`) before submitting for the whole checklist.

The judge's evidence step and the behavior diff are separate. The first re-checks what the author claims to have run; the second is Onus's own observation of the tests that reach the change, at both commits ([`onus help environments`](/docs/environments)). A run whose manifest records files written over the head's tree (the behavior diff's cross run) is never accepted as evidence.

The verdict is `approve`, `reject` with reasons the agent can act on, or `escalate` to a person. A change in the `human` lane is escalated even when every check passes; a `blocked` change is rejected.

### Held-out suites

A suite is a directory holding `held-out.yaml` and the files its checks need. Keep it outside the repository: in a private repository, a CI secret or Onus Cloud. The judge refuses a suite inside the repository's worktree, where the author could read it.

```yaml
version: 1
image: node:22-alpine        # default image for checks (default node:22)
setup: npm ci                # default setup, run with network and without the suite
limit: 6                     # at most this many checks per change, most relevant first
checks:
  - id: sms-respects-opt-out
    command: node --test /held-out/sms-opt-out.test.mjs
    covers: [notifications, user-preferences]
  - id: send-sms-unit
    command: node --test /held-out/send-sms.test.mjs
    covers: ["notifications:src/sms.ts#sendSms"]
  - id: smoke
    command: npm run build   # no covers: runs for every change
```

Each check runs in a container at the head commit with no network, the repository at `/work` (the working directory) and the suite at `/held-out`. The suite is copied into the test container only, never into the setup container, which has network. Ids are unique slugs; unknown fields are refused.

Give it to the judge with `--held-out DIR` or `ONUS_HELD_OUT`: on `onus judge`, `onus ci pr`, `onus ui` and `onus mcp` (for `onus_judge`). Two commands help people write one, without a container engine:

```sh
onus held-out check ~/acme-held-out/shop --repo .              # valid? its hash, ids and covers
onus held-out select --held-out ~/acme-held-out/shop --submission sub.json   # what would run, and why
```

**Chosen from the map.** The judge works out what the change reaches in the head map: the components of its rows and of the files git says changed (`touched`), its rows' subjects, and the pairs of components that interact with at least one side touched: a code dependency either way (a file import counts, so a change that breaks the symbols between two components still pairs them), or one publishes an event the other consumes. A `covers` entry is a component id, or a map id standing for its component; `event:` and `db-table:` ids count only as subjects. A check is chosen for its best reason:

| reason | when |
|---|---|
| `combination` | two components it covers form a pair: the cross-feature test an author's own suite rarely has |
| `subject` | a map id it covers is a row's subject, or the module of one |
| `touched` | it covers a touched component |
| `always` | it covers nothing (and `lanes.heldOut`) |
| `neighbour` | it covers a component that interacts with a touched one |

Within a reason checks keep their order in the file. The configuration's `heldOutLimit`, else the suite's `limit`, cuts the list. The head map is built only when some check has `covers`, with the same onus.yaml as the lanes; if it cannot be built, the rows alone decide, and the report says `"map": false`.

**Who sees what.** The judgment carries `heldOut: {suite, selected, ran, passed}`, safe for the author. What each check did (`why`, `with`, status, exit code and output) is for people: `onus judge --show-held-out`, `held-out.json` beside `judgment.json` from `onus ci pr`, and the lanes page of `onus ui`. No agent tool returns it, and `onus_lanes` shows only that held-out checks are configured. When a check cannot run at all (an image that will not pull, say), the author reads only that the held-out checks could not run; the error is in the report.

**The honest limit.** On a machine where an agent has a shell, a suite is only as hidden as that machine's file permissions. So is the report: `onus ui` and `onus mcp` keep it as `.onus/submissions/<id>.held-out.json` in the worktree, where such an agent can read it. Real secrecy comes from where the suite lives and where the judge runs: a CI secret, a private repository cloned with its own token, or Onus Cloud.

`lanes.heldOut` in onus.yaml still works, as one check with id `lanes.heldOut` that runs for every change. Agents can read onus.yaml, so `onus judge` notes it on stderr; prefer a suite.

### Judge configurations

With `lanes.judges` set, one configuration judges each change. Each has a `name`, and optionally its own `taste` reviewer (default `lanes.taste`) and `heldOutLimit`. The rotation picks one from a hash of the head commit and the suite's full hash, so an author who cannot read the suite cannot predict which configuration will judge a commit. Without a suite the choice is predictable from the head commit.

The judgment records `rotation: {config, index, of, forced}`, and its judge id is `<name>@<hash>`, so outcome records and `onus outcomes summary`'s `byJudge` track each configuration by name. `onus judge --judge-config <name>` (and the lanes page of `onus ui`) forces one, for example to judge an audited change again under another configuration; that is recorded as `forced: true`. Agents cannot choose. Without `judges` nothing changes, and the judge id stays the policy's hash.

Agents do not see which configuration judged. `onus_judge` leaves out `rotation`, and its judge id is the policy's hash, the same for every configuration; the judgment kept beside the submission has both, for people. Otherwise an agent could amend its commit, judge it again, and repeat until a lenient configuration came up. That is the limit: an author who sees the configuration can still shop by amending. `lane.md` from `onus ci pr` names it, so in CI an author who reads the pull-request comment can push again until it likes the one it gets, and on a machine where an agent has a shell, it can read the kept judgment. What still holds there is the record: `byJudge` shows what each configuration let through, so a lenient one shows up in its reverts, incidents and audit misses.

## Outcomes

The GitHub Action keeps these records for you with `records: true`: outcomes when pull requests close, reverts when the default branch moves, and approvals, audits and incidents from `/onus` comments ([`onus help ci`](/docs/ci)). By hand, or from another system:

```sh
onus outcomes record --file outcomes.jsonl --change acme/shop#42 --agent claude-code/sonnet/default \
  --lane auto-merge --verdict approve --judge 1a2b3c4d --result merged --audited
onus outcomes summary --file outcomes.jsonl
```

Pass `--component <id>` (repeatable) to name the components the change touched, for the history input, and `--classification <file>` to keep the change's features for the learned model. `onus ci pr` records them from the report, and `onus ci closed`, reverts and incidents keep them.

The summary gives each agent setup its record, and each judge configuration its record of the changes it decided (a verdict on record): merged, reverted, incidents, audited, missed. It also gives the share of changes in the human lane (the review budget), and the miss rate of human audits of automatic approvals, the number that says whether the automatic lanes can be trusted. A judge configuration id is a hash of the lane policy and the Onus version, so changing either starts a new record; with `lanes.judges`, each configuration keeps its own record as `<name>@<hash>`.

## Audits after merge

Some changes merge with no person looking: the `auto-merge` lane, and the `judge` lane when the judge approves. A share of them (`auditAfterMerge`, default 0.05) is sampled for a person to audit after they merge. `onus ci closed` makes the choice from a hash of the merge commit, which does not exist until the merge, so an agent cannot know beforehand whether its change will be audited. The choice is written into the outcome as `"sampled": true` and nowhere else: not in the comment, the check or the CI log.

`auditRate` is a different draw: it sends would-be auto-merges to a person before they merge. Set either to 0 to turn it off.

```sh
onus outcomes audits --file outcomes.jsonl          # what waits for a person, and the audit log
onus outcomes audit --file outcomes.jsonl --change acme/shop#42 --by @alice \
  --result miss --note "the opt-out was ignored"
```

`audits` prints `{awaiting, audited}`: the sampled changes no one audited yet, oldest first, and every audited change, most recent first. A sampled change that was later reverted or caused an incident still waits; leaving out the ones that went badly would bias the sample. `audit` records who audited, when, ok or a miss, and a note. `/onus audit ok|miss` on a merged pull request writes the same record ([`onus help ci`](/docs/ci)).

The summary's `sampledMissRate` is the number to watch: misses among the sampled changes a person audited. Because the sample is random, it estimates how many risky changes slip through without a person. `auditMissRate` counts every audit, including the ones people chose to make, and `awaitingAudit` counts what is still waiting.

## The production loop

What happens after merging changes the record:

```sh
onus outcomes ingest-reverts --file outcomes.jsonl --since v1.4.0     # reverts in git history
onus outcomes incident --file outcomes.jsonl --change acme/shop#42 \
  --involved notifications --involved "notifications:src/sms.ts#sendSms" --note "SMS sent twice"
onus outcomes backlog --file outcomes.jsonl
```

Reverts are found from commit messages (`This reverts commit …`) and recorded against the change they undo; a reverted change no longer counts toward its agent setup's record. A change turned off by a feature flag or a rolled-back rollout is recorded with `onus ci rollback`, `onus ci rollout` or `onus outcomes record --result rolled-back` and counts the same way, unless it was `--planned`: a planned rollback still counts as a merged change. An agent setup with an incident or a rollback among its last 20 changes cannot auto-merge. Incidents and rollbacks also come straight from production: `onus signals ingest` records signals from monitoring and deploy tools and turns those tied to a change into its outcomes ([`onus help production`](/docs/production)). `backlog` lists the components and symbols incidents involved, most often first: where the next held-out tests should go. Onus does not write tests.

## Provenance

Every change carries one record of why it was allowed through: the intent, the agent and model, the token it held, the evidence, any escalations, the lane and the judge's steps, who or what approved it, and how it rolled out. `onus ci pr` writes it as `provenance.json` beside the submission while the pull request is open. `onus provenance` rebuilds it from the records as outcomes arrive:

```sh
onus provenance --change acme/shop#7 --records rec --from out/provenance.json --out p.json
onus provenance --submission-id 4fa91c        # a submission kept by onus ui or onus mcp
onus provenance --submission sub.json --audit audit.jsonl --escalations escalations --task sms
onus provenance --change acme/shop#7 --records rec --escalations cloud.json --token-inspection token.json
onus provenance --change acme/shop#7 --records rec --audit door-log.json --calls calls.json
onus provenance --change acme/shop#7 --records rec --agent-submission submissions/7.json
onus provenance --verify p.json
```

`--from` is an earlier record of the change. Its facts from while the change was open (intent, report, token, evidence, escalations, lane reasons, judge, doors) are kept unless fresh ones are given. The stage, merge commit, approver and rollout are worked out again from the records every time. `--submission-id` reads `.onus/submissions/<id>.json`, its judgment, and the repository's `.onus` audit log, escalations and outcomes.

A change made through Onus Cloud has no submission or door log in CI. Onus Cloud keeps its escalations instead, each with the door's inspection of the task token. `--escalations FILE` (also on `onus ci pr`) takes them as a JSON array (`schemas/escalation-decisions.schema.json`): `id`, `kind`, `scopes`, `state`, `decidedBy`, `decidedAt` (Unix seconds or an RFC 3339 date in UTC), `reason` or `answer`, `repository`, `pull`, `ref`, `commit`, and `token: {task, rights, expires}`. The API's `{"escalations": [...]}` with a nested `decision` is read too, and so is a stored row (`status`, `pullNumber`, `input`). Pass the API's views where you can: a stored row still `waiting` past its `expiresAt` is recorded as `expired`, as the view shows it.

Which escalations are this change's:

- For a pull request (`owner/repo#n`), those for another repository or pull request are left out. The repository is matched ignoring case.
- An escalation that names the change is kept whatever its task. It names the change when it is on the pull request, the submission lists it, an earlier record (`--from`) kept it, or its `ref` or `commit` is one of the change's commits, its branch (`ci pr --branch`) or `refs/pull/<n>/head`. A `commit` elsewhere outweighs the branch's name, since a branch name may be used again. `ci pr` lists the change's commits with git; `onus provenance` does so in `--repo` when it holds them.
- One that does not name the change is kept only for the change's task. With no task, it is left out.
- The change's task is `--task`, the token's, the submission's, the inspection's or the earlier record's. Else it is the one task the escalations that name the change name. When they name several, none is picked. An escalation that does not name the change never says its task, so it never brings its token into the record.
- For a local change (a head commit), the repository and pull request are not checked. Those of the change's task are kept, or all of them when the task is not known.

An escalation that cannot be read (an unknown `state`, a value of the wrong type, a time that is not one) is left out with a warning, and `escalations` stays a gap that names it. The note names the field and what it should be, never the value given, so a token pasted into the wrong field never reaches the record. A list whose escalations are all for other changes is a gap too. An `expires` that is not a positive whole number is no expiry. `onus ci pr` never stops for this input: a file it cannot read is a warning and a gap. Only a token given instead of its inspection is refused, before anything is written. An inspection `onus ci pr` cannot read is named in the `token` gap. `onus provenance` fails on a file it cannot read, a missing one included.

`--token-inspection FILE` takes the door's inspection of the token on its own (`{task, rights, expires}`, as `onus token inspect` prints it; an `expires` of 0 is no expiry). With `--task`, it must be for that task. Without the file, the first escalation of the task that kept an inspection gives it. Either way the rights are widened by the scopes Onus Cloud granted to the task. Those are what Onus Cloud granted, not what the door minted again: the agent may never have taken up a grant. `onus provenance --escalations` given a folder reads the escalation requests kept there, as before. Given a file with `--submission-id`, it also reads the requests kept in `.onus/escalations`, so what Onus Cloud's list leaves out (kind, scopes, grade) comes from them. On a rebuild with `--from` where Onus Cloud's list is the only fresh input, it updates the escalations kept earlier, so those only the door knew stay.

The door log can travel with the work too. An agent attaches its task's slice of the log to the pull request in Onus Cloud with `onus_cloud_attach_evidence` (`doorLog: true`) or `onus cloud evidence <pull> --door-log --task <task>`. The slice is the run of entries from the task's first entry to its last, with whatever lies between, so its hash chain can be checked where it is read (`schemas/door-log.schema.json`). Through `onus mcp`, the server cuts it from its own log: the agent names nothing but the pull request. `--audit FILE` (also on `onus ci pr`) takes the slice, or a whole audit log as before. A slice's chain is checked from its first entry: whether any entry in it was changed or removed, not what came before it. The record keeps the task's entries with `doors.source: attached`, and whether the chain verified. A slice that does not verify is still recorded, as not intact, with the entries of the task it names, and the `doors` gap says why. A slice of another task than the change's keeps none of its entries, and the gap names both tasks. When nothing else names the change's task, the slice's task does, if the slice verifies.

Through `onus mcp --token`, the door also sends its inspection of the token it holds with the slice (`inspection`: `{task, rights, attenuations, expires}`, never the token). So a change made through Onus Cloud by an agent that never escalated still has its token on record, as `token.source: attached`. Without an inspection, the slice's `mint` entry gives it, when the slice holds one. Either is taken only when the slice verifies and was cut at one of the change's commits (its `head`), and ranks below every other source. A slice cut at another commit may be another change's: it gives neither the task, the token nor any decision, keeps none of its entries, and the `doors` gap names the commit. So does a slice that does not say where it was cut, when the change's commits are known. Attach it after committing and pushing the work: onus attaches a slice only to the pull request whose head in Onus Cloud is the worktree's commit.

An attached slice is the agent's word. The chain is plain sha256 with no key, so it shows that nothing in the slice was changed after it was cut, not who cut it: anyone can build a slice that verifies. So the `doors` gap stays even when it verifies, narrowed to say so. Its decisions on escalations are read only when it verifies, is of the change's task and was cut at one of its commits, and Onus Cloud's decision on the same escalation is recorded over it whatever its state; the `escalations` gap names any disagreement, and any decision only the slice gives. Its entries between the task's first and last include other tasks' entries on the same log, which travel with it. Each hash is over the entry's JSON as the door wrote it, so a host keeps the slice as it was sent (its text): a number written again another way (`1.0` as `1`, an integer past 2^53) no longer verifies.

A door log that verifies but holds nothing of the change still leaves the `doors` gap: when the change's task is not known (give `--task`, also on `onus ci pr`), or the log holds no entry of the task. Whatever the source, a door log that does not verify never gives the token or the task.

`--calls FILE` (also on `onus ci pr`) takes Onus Cloud's log of the calls made under the task token (`schemas/cloud-calls.schema.json`): a JSON array of `{at, method, route, scope, decision, tokenId, task, reason}`, where `decision` is `allowed`, `denied` or `failed`. The API's `{"calls": [...]}` with `createdAt` and `credentialId` is read too. The record sums them up in `doors.calls`: the totals, the first and last call, the token ids, the counts for each route and scope by decision, and every denial (at most 100) with its reason. Calls of another task are left out when the change's task is known, and calls never say the task. Calls that name no task are counted as the change's, on Onus Cloud's word, and `untasked` says how many. Onus Cloud's API rows name no task, so a host gives only the calls made under the change's task token. When the change's task is not known, every call given is counted and the `doors` gap says so. They are marked `source: onus-cloud`, apart from the door log: they are Onus Cloud's word and have no hash chain. With calls and no door log, `doors.source` is `onus-cloud`, `intact` is false, and the `doors` gap stays: the agent's own door log, with its MCP and gateway calls, did not reach the run. A call that cannot be read is left out with a warning, and the gap says the counts may be short. An empty list is on record: no call was made there. Only those fields are read: the API's rows carry more (`path`, `userAgent`, `credentialName`), some of it set by whoever made the call, and none of it is read or kept. A call with a `token`, or a field read that looks like one (an Onus Cloud token or API key, a PASETO, a run of base64url as long as a Biscuit), is left out like one that cannot be read; the warning and the gap name the field, never the value. A door log or a calls file that cannot be read at all is a warning and a `doors` gap, in `onus ci pr` and `onus provenance` alike, so a host refreshing a record keeps what came after the close.

| Field | What it holds |
|---|---|
| `stage` | `open`, `merged` or `closed`. |
| `intent` | Where the intent came from (`pull-request` or `submission`), its sha256, and the report's intent check. |
| `agent` | The agent setup, how it was recognised (`trailer`, `branch`, `bot`, `co-author`, `person`, `submission`), and its track record (`merged`, `recentIncidents`, `recentRollbacks`). |
| `token` | The task, rights, attenuations, expiry and a 16-digit fingerprint. Never the token itself. `source` says where it came from: `token` (verified by this run), `submission` (verified when the submission was made), `agent-submission` (the agent's own submission handed in beside the run, with `onus ci pr --submission` or `onus provenance --agent-submission`, such as one kept on the records branch: on its word, since the run cannot tell it was verified when it was made), `audit` (the door log's `mint` entry, widened by grants, when the log verifies), `inspection` (the door's inspection, from `--token-inspection` or kept by Onus Cloud with an escalation, widened by the grants there; not verified by the run) or `attached` (the door log the agent attached in Onus Cloud: the inspection sent with it, or its `mint` entry, when it verifies). The first that is given wins, in this order: `token`, `submission`, `audit`, `inspection`, `agent-submission`, `attached`. The agent's own submission ranks below the door's word. On a rebuild with `--from`, a kept token verified by a run or a submission, or taken from a door log this run read, comes before an inspection. |
| `evidence` | Each test run: command, commit, image, exit code, manifest, and whether it ran at the head commit. |
| `escalations` | Each request: kind, scopes, best evidence grade, and the last decision in the door log, by whom (`policy` for an automatic grant). A decision Onus Cloud kept, with Onus Cloud's id as `cloudId`: `granted`, `denied`, `needs-person` (waiting), `answered` (a blocked report a person answered), `open` (being checked), `withdrawn`, `expired` or `failed`. It replaces an open or waiting one, and a final decision from the submission or the door log stands against one Onus Cloud has not made yet. When both are final and differ, Onus Cloud's is recorded, since it decided, and the `escalations` gap names the disagreement. A decision only the agent gives (the escalations its own submission lists, or the door log it attached) stands against nothing: Onus Cloud's is recorded whatever its state. Kept on the agent's word alone, the `escalations` gap names it. `reason` is the decider's (the door log's reason, or Onus Cloud's `answer`), never why the agent asked. |
| `lane`, `judge` | The final lane, every rule that applied, the lane policy's hash, and the judge's verdict, steps and reasons. |
| `approval` | Who or what approved it (below), the people, the rows they approved, and who merged it. |
| `rollout` | The result now, the merge commit and time, whether a person audited it, and every outcome in order. From production: `status` (`pending`, `not-shipped`, `awaiting-deploy`, `in-progress`, `holding`, `complete`, `rolled-back` or `reverted`), the `percent` of traffic last reported, the `plan`, every deploy and rollout stage (`stages`) and the other signals tied to it (`signals`). [`onus help production`](/docs/production) has the rules. |
| `doors` | The door log's decisions for the task, and whether its hash chain is intact. `source` says where they came from: absent for the door log this run read, `attached` for the slice the agent attached in Onus Cloud, or `onus-cloud` when only Onus Cloud's calls are known. `calls` sums up Onus Cloud's log of the calls made under the task token (`source: onus-cloud`). |
| `gaps` | What the record cannot vouch for, and how to fill it. |

Who or what approved it:

| Stage | Final lane | Judge verdict | `approval.by` |
|---|---|---|---|
| open | any | any | `pending` |
| closed | any | any | `none` |
| merged | `auto-merge` | any | `policy` |
| merged | `judge` | `approve` | `judge` |
| merged | `judge` | `escalate`, `reject` or none | `person` |
| merged | `human` | any | `person` |
| merged | `blocked` | any | `override` (it merged although Onus blocked it) |

`approval.people` lists the people who approved rows, the approving reviewers, then who merged it (`onus ci closed --merged-by`), each once. When a person approved and none is known, `gaps` says so.

A gap is listed for each of `intent`, `token`, `evidence`, `escalations`, `judge` and `doors` that is empty. In CI no task token reaches the run, so `token` is a gap there unless Onus Cloud passes the door's inspection or the agent's submission comes with the change. An escalations list from Onus Cloud is on record even when it is empty, so it is not a gap. `doors` stays a gap in a hosted run: the door log the agent attaches, and Onus Cloud's calls, narrow it, never close it, since each is on its sender's word.

What a run in CI can know depends on what reaches it:

- **The agent's submission** (`onus ci pr --submission FILE`, the action's `submission` input, or one kept on the records branch at `submissions/<pull request number>.json` or `submissions/<head commit>.json`). It brings the task token's facts (`token.source: agent-submission`) and the escalations it lists, on its word: the file is plain JSON, and the record cannot tell it was verified when it was made. Its token ranks below the door's word, and the escalations it lists are recorded as granted only until Onus Cloud says otherwise; while nothing else confirms them, the `escalations` gap says they are the agent's word. It must be for one of the pull request's commits; one for another commit is left out with a warning, and so is one that cannot be read. Only its token and escalations are taken: the intent, the agent and the evidence are this run's. When the pull request closes, the action rebuilds the record with `onus provenance --agent-submission FILE`, which takes it the same way: for one of the commits in the pull records (or in `--repo` between their base and head), and only its token and escalations.
- **What the action cannot know.** It cannot verify the token itself: a submission keeps the token's task, rights, expiry and fingerprint, never the token, and no root key reaches CI, so it vouches only for what was verified when the submission was made. Whoever can write to the records branch can put a submission there. The action does not see the door log, the escalations or the calls Onus Cloud keeps; a host that has them passes `--audit`, `--escalations` and `--calls`. Without a submission or Onus Cloud, `token`, `escalations` and `doors` are gaps.
- **Onus Cloud** passes the escalations with the door's inspection of the token. Its call log (`--calls`) and the door log the agent attached (`--audit`) reach the record only from an Onus Cloud that keeps them and passes them on; an older one refuses a door log on its evidence route.

`digest` is the sha256 of the record's compact JSON with the digest left empty. `--verify` checks it and the schema version, and exits 1 when either does not match. The format is `schemas/provenance.schema.json`; new optional fields may be added under `schema: 1`.

## In CI

In the human lane, `onus ci pr --reviews <file>` decides whether the change has the review it needs: an approval of the head commit from someone with write access who is not a bot and did not open the pull request, and no outstanding request for changes. It also names the owners of the rows that need a person (onus.yaml, else CODEOWNERS) for the host to ask, each once per pull request.

`lanes.approval` says whose approval counts. With `owner`, the default when the change has owners, only an owner counts: a person named as an owner, or a member of an owning team when the host says who is in it. With `member`, the default when nobody owns what changed, anyone with write access counts. When Onus cannot check an owner (a team whose members it was not given, or an email), or no owner but the author could approve, anyone with write access counts and the review says why. The rule and the owners are read at the base commit (onus.yaml, then CODEOWNERS), so a change can neither loosen the rule for itself nor name its own approver. The rule applies in the human lane only, and it is kept on the pull record, the outcome and the provenance record (`approval.review`).

The action (with `records: true`) and Onus Cloud both pass the reviews, ask the owners to review, and keep their check failing or waiting until a review counts; see [`onus help ci`](/docs/ci).

The action classifies every pull request with `lanes: true` and shows the lane in its comment. `apply-lane: true` labels the pull request `onus/lane:<lane>` and fails the job for `blocked`; `auto-merge: true` enables GitHub's auto-merge for the `auto-merge` lane. See [`onus help ci`](/docs/ci). With `records: true`, the action also keeps the outcome records on an `onus/records` branch: outcomes when pull requests close, reverts when the default branch moves, and approvals, audits and incidents from `/onus` comments.


---

## Introduction

URL: https://onushq.com/docs

What Onus does, how to install it, and where to find each topic.


# Introduction

Onus turns a pull request into a short report of changes in meaning: new external services, contract changes, new relationships between components, weakened tests, broken rules. Every row is computed from the code by deterministic analysis, never generated, and links to the files and lines behind it. Onus only reads files: it never installs or runs the code it analyzes.

## Install

With Homebrew, on macOS or Linux:

```sh
brew install onushq/tap/onus
```

Or with the installer, which checks the download's SHA-256 and puts `onus` in `~/.local/bin`:

```sh
curl -fsSL https://onushq.com/install.sh | sh
```

Then, in a git repository:

```sh
onus report --base main --head HEAD
```

Archives for macOS, Linux and Windows are on the [releases page](https://github.com/onushq/onus/releases), and the GitHub Action reports on every pull request (see [CI](/docs/ci)).

## The guide

These pages are the guide that ships inside the `onus` binary: `onus help <topic>` prints any of them in the terminal, offline.

| Topic | What it covers |
| --- | --- |
| [getting-started](/docs/getting-started) | Install Onus, build a map and read your first report |
| [commands](/docs/commands) | Every command and flag, with examples and exit codes |
| [reports](/docs/reports) | Reading a report: rows, ranking, evidence, the changed lines tests ran and the JSON |
| [changes](/docs/changes) | Every kind and subkind of change Onus reports |
| [configuration](/docs/configuration) | The onus.yaml reference: components, rules, labels, extractors |
| [intent](/docs/intent) | Checking a change against its stated intent |
| [ci](/docs/ci) | Running Onus on every pull request, and outcome records kept by CI |
| [agents](/docs/agents) | The map for coding agents: onus mcp, its tools, many agents and worktrees |
| [scopes](/docs/scopes) | Task tokens, the git gateway, escalation with evidence and the audit log |
| [lanes](/docs/lanes) | Risk lanes, change submissions, the learned model, the verifying judge, outcome records and provenance |
| [production](/docs/production) | Production signals, rollout plans per lane and automatic rollback |
| [web-interface](/docs/web-interface) | The web interface: onus ui opens all of it in your browser |
| [environments](/docs/environments) | Environments built from a commit, the evidence store, traces and coverage into the map, and the behavior diff |
| [cloud](/docs/cloud) | Onus Cloud from the CLI: onus login, scoped tokens, hosted environments, evidence, escalations, maps and agents |
| [plugins](/docs/plugins) | New languages and frameworks, SCIP indexes, language servers, trusted mode |
| [how-it-works](/docs/how-it-works) | How maps are built and compared |
| [troubleshooting](/docs/troubleshooting) | Map confidence notes, common questions and current limits |

The source is in the [onus repository](https://github.com/onushq/onus/tree/main/crates/onus-cli/guide).


---

## Plugins

URL: https://onushq.com/docs/plugins

New languages and frameworks, SCIP indexes, language servers, trusted mode


<!-- Generated by npm run docs:sync from crates/onus-cli/guide/plugins.md in onushq/onus; edit it there. -->

# Plugins: new languages, frameworks and compiler-backed facts

Onus builds a map with *providers*:

- **discovery** providers find components (built in: `onus.yaml`, Nx projects, npm/pnpm/yarn workspaces, folders);
- **language** providers turn source files into symbols, shapes, references and tests (built in: TypeScript and JavaScript on tree-sitter);
- **fact** providers add facts to the map built so far (SCIP indexes, framework plugins).

Plugins add providers without changing Onus. They are listed in a *plugins file* that you pass with `--plugins <file>` (or `ONUS_PLUGINS`). The plugins file belongs to whoever runs Onus: Onus never reads plugins from the analyzed repository, so a pull request cannot make CI run new code.

## Framework packs: no code at all

Most framework knowledge is a pattern in the code: a decorator, a method on a known client, a call with a literal argument. A *pack* is a YAML file of tree-sitter queries and what a match means. Packs never run code, so they may be listed in the analyzed repository's `onus.yaml` (`extractors.packs`) as well as in the plugins file (`packs`). Like the rest of `onus.yaml`, packs are read from the base version of a change: a pull request cannot edit a pack to hide what it adds, and editing one is reported as a rules-of-the-game change.

```yaml
pack: nestjs
rules:
  - id: route
    query: |
      ((decorator (call_expression
         function: (identifier) @method
         arguments: (arguments . (string) @path)))
       (#match? @method "^(Get|Post|Put|Patch|Delete)$"))
    emit: { route: "{method|upper} {path}" }
  - id: on-event
    query: |
      ((decorator (call_expression
         function: (identifier) @fn
         arguments: (arguments . (_) @name)))
       (#eq? @fn "OnEvent"))
    emit: { event: consumes, name: "@name" }
  - id: cache-write
    query: |
      ((call_expression function: (member_expression
         object: (identifier) @c property: (property_identifier) @op))
       (#eq? @c "redis") (#eq? @op "set"))
    emit: { edge: writes, to: "db-table:redis-cache" }
```

Each rule has an `id`, a tree-sitter `query` over the TypeScript grammar (the same query runs on TSX and JavaScript), and one `emit`:

| Emit | Means |
|---|---|
| `event: publishes` or `consumes`, `name: "@capture"` | An event, named by the capture; literals, constants and enum members are resolved |
| `data: reads` or `writes`, `table: "<template>"` | A table read or written |
| `config: "<template>"` | A configuration key read |
| `host: "@capture"` | An outbound call to the host of the captured literal URL |
| `route: "<template>"` | An HTTP route served here: a public contract, so an added or removed route is a contract change |
| `edge: <kind>`, `to: "<template>"` | Any other relationship (`calls`, `reads`, `writes`, `publishes`, `consumes`, `calls-external`, `reads-config`, ...) |
| `diagnostic: <kind>`, `message: "<text>"` | A map confidence note |

Templates replace `{capture}` with the captured text (a string literal without its quotes) and accept `{capture|upper}` and `{capture|lower}`. Facts are attributed to the innermost declaration containing the match. Query predicates (`#eq?`, `#match?`, `#any-of?`) work as in tree-sitter.

Onus's own framework knowledge ships as packs too: Prisma reads and writes, `process.env` reads, `fetch`/`axios`/`got`/`ky` hosts, and the event patterns from `onus.yaml` (`crates/onus-lang-ts/packs/` in the repository). An invalid pack is a configuration error that names the pack and rule.

## The plugins file

```yaml
plugins:
  # A plugin speaking the Onus protocol: finds Go modules as components.
  - name: go-modules
    kind: discovery
    command: [onus-plugin-example]

  # A framework plugin: Express routes become contracts.
  - name: express-routes
    kind: facts
    command: [onus-plugin-example]

  # A SCIP indexer, run in the tree; it must write {out}/index.scip.
  - name: rust
    kind: scip
    command: [rust-analyzer, scip, ".", --output, "{out}/index.scip"]

  # A language server, driven over LSP.
  - name: python
    kind: lsp
    command: [pyright-langserver, --stdio]
    files: ["**/*.py"]
    language_id: python

packs: [packs/nestjs.yaml]   # framework packs, relative to this file

sandbox:
  preset: auto        # auto | bwrap | sandbox-exec | container | none
  # command: [docker, run, --rm, -i, --network, none, -v, "{root}:{root}:ro", -v, "{out}:{out}", -w, "{root}", my-image]
```

Each plugin has:

- `name`: recorded in the map's `builtWith.providers`;
- `kind`: `discovery`, `language`, `facts`, `scip` or `lsp`;
- `command`: the program and its arguments. `{root}` becomes the tree's root and `{out}` a fresh, writable temporary directory;
- `files` (language and lsp): globs of the files it handles;
- `language_id` (lsp): the LSP language id of those files;
- `runs_repo_code`: whether the tool may run code from the repository. Default: true for `scip` and `lsp`, false otherwise;
- `timeout_seconds`: default 300.

The format is in [schemas/onus-plugins.schema.json](https://github.com/onushq/onus/blob/main/schemas/onus-plugins.schema.json).

## Trusted mode and the sandbox

Language servers and indexers are the most precise source of facts, because they are built on each language's own compiler. They also tend to run code from the repository: rust-analyzer runs build scripts and procedural macros, gopls runs `go list`, tsserver loads plugins named in tsconfig, Gradle and Maven run build scripts. Most of them also need dependencies installed.

So a plugin with `runs_repo_code: true` runs only with `--trusted`, and only inside a sandbox with no network:

- `auto`: bubblewrap (`bwrap`) on Linux, `sandbox-exec` on macOS;
- `bwrap` or `sandbox-exec`: that one;
- `container`: Docker or Podman (`runtime`) running `image`, with no network, the tree read-only and `{out}` writable; the tools must be in the image. With Docker Desktop or Colima, the tree and the temporary folder (`TMPDIR`) must be in a shared folder. This is the option on Windows;
- a custom `command` prefix;
- `none`: no sandbox; such plugins then also need `--allow-unsandboxed`.

In every case the tree is read-only and the network is unreachable; only `{out}` and the system's temporary folders are writable.

Without `--trusted` they are skipped, and both the map and the report say so ("provider `rust` skipped: ... runs only with --trusted"). Use trusted mode where the code is already trusted, for example on the main branch, and keep pull requests from forks on the default providers, which only read files.

Importing an index that was produced elsewhere runs nothing and needs no trusted mode:

```sh
onus map . --scip index.scip
onus diff old new --base-scip old.scip --head-scip new.scip
```

## SCIP indexes

SCIP indexers index a whole repository in one pass:

| Language | Indexer | Command |
|---|---|---|
| Rust | rust-analyzer | `rust-analyzer scip . --output {out}/index.scip` |
| TypeScript, JavaScript | scip-typescript | `scip-typescript index --output {out}/index.scip` |
| Python | scip-python | `scip-python index . --output {out}/index.scip` |
| Java, Scala, Kotlin | scip-java | `scip-java index --output {out}/index.scip` |
| Go | scip-go | `scip-go --output {out}/index.scip` |

Flags change between releases; check each indexer's documentation for the current ones.

Tried: rust-analyzer indexed the Onus repository in about 3.5 seconds inside the macOS sandbox, and scip-typescript indexed an 8,500-file TypeScript monorepo in about 20 seconds, adding 10,600 compiler-confirmed references.

What an index adds:

- for files another provider analyzed: references that provider missed, such as a method call through a variable, and confirmation of the ones it found (confidence `compiler`);
- for files no provider handles: their symbols, with the signature as shape, and their references. A symbol used from another component is public.

## Language servers

For languages without an indexer, the LSP bridge starts the server, opens each file it handles, waits until the server has finished loading the project (it follows the server's progress reports), and asks for document symbols and, where the server supports it, the call hierarchy. Symbols become map symbols (their detail, usually the signature, is the shape); outgoing calls become `calls` edges with confidence `compiler`. Language servers answer one request at a time, so an index is faster on large repositories. Measured: the bridge itself handles about 15,000 requests a second, so the server sets the pace; pyright (`pyright-langserver --stdio`, language id `python`) mapped a generated 500-file, 35,000-line project in 2.6 seconds, and rust-analyzer (`rust-analyzer`, language id `rust`) mapped one Rust crate in 4.5 seconds, most of it loading the Cargo workspace.

## Svelte

Svelte components are supported by a plugin that ships with Onus, `onus-plugin-svelte`:

```yaml
plugins:
  - { name: svelte, kind: language, command: [onus-plugin-svelte], files: ["**/*.svelte"] }
```

It analyzes each component's `<script>` blocks with the TypeScript adapter, together with the repository's TypeScript files, so imports such as `$lib/api` resolve and line numbers are exact. Expressions in the markup are not analyzed, but a change to the markup is still a change: components are compared whole. It reads files only, so it needs no trusted mode.

## Writing a plugin

A plugin is any program. Onus starts its command, writes one JSON request to its stdin and reads one JSON response from its stdout; anything on stderr is shown if the plugin fails. The protocol is versioned and published as [schemas/plugin-protocol.schema.json](https://github.com/onushq/onus/blob/main/schemas/plugin-protocol.schema.json).

A request:

```json
{
  "protocol": 1,
  "kind": "facts",
  "workspace": {
    "root": "/abs/path/to/tree",
    "files": [{ "path": "services/api/src/app.ts", "component": "api", "isTest": false }],
    "components": [{ "id": "api", "kind": "service", "roots": ["services/api/**"], ... }],
    "packages": {},
    "extractors": { ... }
  },
  "map": { "files": [...], "symbols": [...], "edges": [...], "tests": [...], "diagnostics": [...] }
}
```

- `discovery` requests list every file and ask for `components`.
- `language` requests list only the files the plugin handles that no earlier provider claimed (the built-in TypeScript adapter comes first); any file under `root` can still be read.
- `facts` requests include the map built so far.

A response:

```json
{
  "protocol": 1,
  "version": "my-plugin 1.2.0",
  "components": [],
  "map": { "symbols": [...], "edges": [...] }
}
```

Everything in `map` uses the map's own types ([schemas/codebase-map.schema.json](https://github.com/onushq/onus/blob/main/schemas/codebase-map.schema.json)). Ids follow the map's rules: `<component>:<path inside the component>#<name>` for symbols, and `event:`, `db-table:`, `config-key:`, `external:`, `npm:` for shared nodes.

Onus treats plugin output as untrusted input. It drops any path outside the tree, any file the tree does not contain, and any id of an unknown component, notes what it dropped (`plugin-output-dropped`), and sorts everything, so a report stays deterministic as long as the plugin is.

The reference plugin, `crates/onus-plugin-example` in the repository, implements discovery (Go modules) and facts (Express-style HTTP routes, which become public contracts, so added or removed routes show up in reports) in about 150 lines.

## Order and precedence

1. Discovery: `onus.yaml` components, when declared, are final. Otherwise built-in discovery runs first and discovery plugins add components; for each file, the most specific component wins.
2. Languages: the built-in TypeScript adapter, then language plugins, then language servers, in the order listed. Each file belongs to the first provider that handles it.
3. Facts: imported indexes (`--scip`), then SCIP indexer plugins, then fact plugins, in the order listed. Each sees what came before.

When two providers report the same edge, its sites are combined and it keeps the more trustworthy confidence, so a compiler-confirmed reference upgrades one read from syntax.


---

## Production

URL: https://onushq.com/docs/production

Production signals, rollout plans per lane and automatic rollback


<!-- Generated by npm run docs:sync from crates/onus-cli/guide/production.md in onushq/onus; edit it there. -->

# Production: signals, rollout plans and rollback

A merge is not the end of a change. Production is the final judge: a change meets a small share of real traffic first, it rolls back when the numbers move the wrong way, and what production says goes back into the records. Incidents and rollbacks count against the agent setup that made the change and against the components it touched, so the next change there gets a stricter lane and a more careful rollout.

Onus decides and never moves traffic. Your deploy tool, flag service or rollout controller does that; Onus gives it a plan per change, a decision per stage, and keeps what happened.

Everything here lives in the records folder ([`onus help ci`](/docs/ci)), in a third file beside `pulls.jsonl` and `outcomes.jsonl`: `signals.jsonl`. `onus ci records pull|push` carries it on the records branch like the others.

## Production signals

A signal is one fact from production, in one vendor-neutral JSON shape (`schemas/production-signal.schema.json`):

| Field | What it holds |
|---|---|
| `id` | Unique per source, such as `pagerduty:Q1ABC`. Required. A signal whose id is on record already is not recorded again. |
| `kind` | `incident`, `error-spike`, `latency`, `metric`, `rollback`, `deploy` or `trace`. (`rollout` is Onus's own, below.) |
| `at` | Unix seconds; the time of the ingest when left out. |
| `source` | The system it came from: `pagerduty`, `sentry`, `datadog`, `argo`, … |
| `severity` | `low`, `medium`, `high` or `critical`. |
| `change` | The change it is about, `owner/repo#123`. |
| `commit` | A commit sha, or at least 7 hex digits of one. |
| `deploy`, `environment` | The deploy tool's id, and where (absent means production). |
| `components`, `symbols` | Map ids it involved; a symbol counts for its component. |
| `note` | What happened. |
| `metrics` | Samples, `{name, value, baseline?, unit?}`. |
| `rollout` | For a deploy: `{percent}`, the share of traffic it reached. |
| `calls` | For a trace: caller and callee pairs observed. |

One example per kind:

```json
{"id":"pagerduty:Q1ABC","kind":"incident","severity":"high","commit":"3f9a1c2","components":["billing"],"note":"checkout 500s"}
{"id":"sentry:4711","kind":"error-spike","change":"acme/shop#42","metrics":[{"name":"error_rate","value":0.031,"baseline":0.012}]}
{"id":"datadog:lat-9","kind":"latency","components":["orders"],"metrics":[{"name":"latency_p95_ms","value":840,"baseline":310}]}
{"id":"datadog:conv-2","kind":"metric","severity":"medium","components":["billing"],"metrics":[{"name":"checkout_conversion","value":0.021,"baseline":0.03}]}
{"id":"argo:rb-17","kind":"rollback","commit":"3f9a1c2","source":"argo","note":"error rate 3x"}
{"id":"deploy:4711:25","kind":"deploy","commit":"3f9a1c2","environment":"production","rollout":{"percent":25}}
{"id":"trace:9f2c41d0a7b3e611","kind":"trace","calls":[{"from":{"service":"orders","file":"src/orders.ts","function":"placeOrder"},"to":{"service":"billing"},"count":214}]}
```

Record them with one object, an array, or JSON Lines; `-` reads stdin:

```sh
onus signals ingest --records rec --file pagerduty-export.json
# {"recorded":3,"duplicates":1,"attributed":[{"id":"pd:Q1ABC","change":"acme/shop#42","by":"commit"}],
#  "outcomes":[{"change":"acme/shop#42","result":"incident"}]}
```

What happens to each signal:

- **It is tied to a change**: by `change` when that change is on record, else by `commit`, matched against the commit each change landed as and the head of its pull request (either one may be a prefix of the other). A commit several changes match goes to the most recent, and the answer lists a `warnings` entry. The stored line gets `change` and `attributedBy` (`change` or `commit`), and the pull record's components when it named none. Both fields are Onus's: an `attributedBy` in the input is dropped, and so is a `change` that is not on record (the answer warns), so a signal cannot claim a tie Onus did not find.
- **An incident or a rollback tied to a change becomes its outcome**: `incident` or `rolled-back`, with `signal` naming the signal, through the same logic as `/onus incident`. The agent setup's track record, `onus outcomes summary`, `onus ui` and Onus Cloud count it with no other step. Ingesting it again adds nothing, and neither does a second incident while the change's latest result is already an incident. A rollback after a planned one is a new rollback.
- **A signal tied to no change is still kept.** It counts toward its components' history (below).
- **A whole file fails on one bad signal**, naming the line: an empty `id`, a `commit` that is not hex or shorter than 7, a `change` that is not `owner/repo#123`, a `trace` without `calls`, `rollout` on a kind other than `deploy`, a `deploy` that names neither commit nor change, a deploy carrying a `decision`, or any `rollout` signal. Rollout stages carry Onus's decisions, and only `onus ci rollout` writes them.

### Wiring monitoring in

Turn each tool's export into signals with `jq`, and pipe them in.

PagerDuty incidents (the REST API's `/incidents`), with the commit in a custom field or the title:

```sh
curl -s -H "Authorization: Token token=$PD_TOKEN" "https://api.pagerduty.com/incidents?since=$SINCE" \
  | jq -c '.incidents[] | {id: ("pagerduty:" + .id), kind: "incident", source: "pagerduty",
           severity: (if .urgency == "high" then "high" else "medium" end),
           at: (.created_at | fromdateiso8601), note: .title,
           components: [.service.summary]}' \
  | onus signals ingest --records rec --file -
```

Sentry issues carry the release, which is the commit when releases are named after it. A release that is not a commit (`1.2.3`) is left out, since one bad signal fails the whole file:

```sh
jq -c '.[] | {id: ("sentry:" + .id), kind: "error-spike", source: "sentry", note: .title,
              commit: (.firstRelease.version // "" | if test("^[0-9a-f]{7,64}$") then . else null end)}' \
     sentry-issues.json \
  | onus signals ingest --records rec --file -
```

Datadog monitor alerts, from a webhook's payload saved to a file:

```sh
jq -c '{id: ("datadog:" + .alert_id), kind: "metric", source: "datadog", severity: "high",
        components: [.tags | split(",")[] | select(startswith("component:")) | ltrimstr("component:")],
        metrics: [{name: .metric, value: (.value | tonumber)}], note: .title}' alert.json \
  | onus signals ingest --records rec --file -
```

Then push the records: `onus ci records push --dir rec`.

## Production traces into the map

Calls production observed are calls the map should know. Keep them from an OpenTelemetry Collector's file exporter:

```sh
onus signals traces --records rec --file otel-export.json --source otel-prod
# {"recorded":1,"calls":214,"id":"trace:9f2c41d0a7b3e611"}
```

It reads OTLP JSON (one document, or one per line), pairs each span with its parent where the code attributes allow (`code.filepath`, `code.function`), counts identical pairs, keeps the 5000 busiest, and records one `trace` signal named by a hash of its calls, so the same export twice is one signal. The signal's `components` are the services that are components: those of the repository `--repo` names (found as the map finds them), and those `--service-component checkout-api=orders` names for a service whose name is not a component id. Without either, they are left out.

`--traces` (on `onus map`, `onus diff` and `onus report`) reads `signals.jsonl` as well as OTLP files: the `trace` lines give their calls, other lines are skipped. A call the map did not have becomes a `calls` edge with confidence `traced`. A call the map had only guessed (`inferred` or `low`) that production observed is upgraded to `traced`, and `onus map` says how many (`traces: 3 recorded calls, 2 traced calls added, 1 confirmed, 1 upgraded`). Static, compiler and declared edges stay as they are. Traced edges are only added, never removed. The action passes the records' `signals.jsonl` to `onus report --traces` when `records: true`, so every report's map includes what production saw ([`onus help environments`](/docs/environments)).

## Rollout plans

Every classification carries a plan for the change's lane (`onus classify`, `onus judge`, `onus ci pr`, `onus ui`). When the judge moves the lane, `onus judge` prints the final lane's plan as `rollout` beside the classification, and `onus ci pr` writes it as `rollout.json`:

```yaml
"rollout": {
  "lane": "judge", "strategy": "canary", "flag": null,
  "steps": [5, 25, 100], "bakeMinutes": 30,
  "guards": [{"metric": "error_rate", "maxRatio": 1.5}, {"metric": "latency_p95_ms", "maxRatio": 1.3}],
  "automaticRollback": true,
  "components": ["billing", "orders"],
  "reasons": ["the judge lane's plan",
              "`billing` had 1 incident and 1 revert or rollback in the last 90 days: the human lane's plan instead"]
}
```

The built-in plans:

| Lane | Strategy | Steps (% of traffic) | Bake | Rolls back when (ratio to baseline) |
|---|---|---|---|---|
| auto-merge | `canary` | 10, 100 | 10 min | error_rate > 2.0×, latency_p95_ms > 1.5× |
| judge | `canary` | 5, 25, 100 | 30 min | error_rate > 1.5×, latency_p95_ms > 1.3× |
| human | `flag` (behind a feature flag, then turned up) | 1, 5, 25, 100 | 120 min | error_rate > 1.2×, latency_p95_ms > 1.2× |
| blocked | `none`: it may not ship | none | none | none |

`lanes.rollout` in `onus.yaml` replaces a lane's plan; a lane left out keeps its built-in one ([`onus help configuration`](/docs/configuration)):

```yaml
lanes:
  rollout:
    judge:
      strategy: canary
      steps: [5, 25, 100]
      bakeMinutes: 30
      guards:
        - { metric: error_rate, maxRatio: 1.5 }
        - { metric: checkout_conversion, minRatio: 0.97 }
```

A guard sets `max` or `min` (on the value) or `maxRatio` or `minRatio` (on the value over its baseline, for metrics that must not rise or drop). Steps go up strictly from 1 to 100 and end at 100; `none` has no steps. A plan for strategy `flag` names a suggested flag key, `onus-<owner>-<repo>-<n>`.

**History tightens the plan.** When a component the change touches had an incident, a revert or a rollback in the history window (`lanes.inputs.history.days`, default 90), the change gets the next stricter lane's plan: auto-merge takes the judge's, the judge the human's. In the human lane the bake time doubles. The reason is listed. The same history raises the lane itself (the `history` input, [`onus help lanes`](/docs/lanes)).

`onus ci pr` writes the plan as `rollout.json`, keeps it on the pull record, adds it to its summary (`rollout.strategy`, `steps`, `bakeMinutes`, `automaticRollback`), and shows it in the comment:

```md
**Rollout:** `canary` 5% → 25% → 100%, 30 min at each step; rolls back automatically when error_rate > 1.5× baseline or latency_p95_ms > 1.3× baseline.
```

## Deciding each stage

A deploy tool reports a stage, with the metric samples it took (`schemas/rollout-metrics.schema.json`), and acts on Onus's decision:

```sh
onus ci rollout --change acme/shop#42 --records rec                # the plan; records nothing
onus ci rollout --commit 3f9a1c2 --percent 5 --metrics canary.json --records rec
# {"change":"acme/shop#42","percent":5,"decision":"rollback","next":null,
#  "reasons":["error_rate 0.031 is 2.6× its baseline 0.012 (limit 1.5×)"]}
```

with `canary.json`:

```json
{"metrics": [{"name": "error_rate", "value": 0.031, "baseline": 0.012},
             {"name": "latency_p95_ms", "value": 200, "baseline": 190}]}
```

| Decision | When | Exit |
|---|---|---|
| `rollback` | A guard is breached. It wins over everything else. | 2 |
| `hold` | A guard has no sample or no baseline, or the stage has not run for `bakeMinutes` since it was first reported. | 3 |
| `complete` | The stage is 100% and healthy. | 0 |
| `promote` | Healthy and baked; `next` is the next step. | 0 |

Every call with `--percent` records the stage as a `rollout` signal: the share, the decision, the samples judged. A `rollback` also records a `rolled-back` outcome against the change, once. The change is found by `--change`, or by `--commit` as signals are; one Onus has no record of, or one in the `blocked` lane, is an error (exit 1). A change recorded before rollout plans gets the plan its lane gets now: `lanes.rollout` from the `onus.yaml` in `--repo` (default the working directory) or `--config`, tightened by its components' history.

A rollback decided elsewhere, by a person or by the deploy tool's own analysis:

```sh
onus ci rollback --change acme/shop#42 --records rec --reason "checkout 500s" --involved billing
onus ci rollback --commit 3f9a1c2 --records rec --reason "flag off as planned" --planned
```

It records a `rollback` signal and the `rolled-back` outcome (or says `already rolled back`). `--planned` is for a flag turned off on purpose: the outcome is marked `planned` and counts against neither the agent setup nor the components.

### Argo Rollouts

Run `onus ci rollout` as a `job` metric provider: the analysis fails when Onus says roll back.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: AnalysisTemplate
metadata: { name: onus }
spec:
  args: [{ name: commit }, { name: percent }]
  metrics:
    - name: onus
      provider:
        job:
          spec:
            backoffLimit: 0
            template:
              spec:
                restartPolicy: Never
                containers:
                  - name: onus
                    image: ghcr.io/acme/onus-runner:latest   # onus, git, and your metrics query
                    command: [sh, -c]
                    args:
                      - |
                        onus ci records pull --dir rec
                        ./query-metrics.sh > canary.json
                        onus ci rollout --commit {{args.commit}} --percent {{args.percent}} \
                          --metrics canary.json --records rec; code=$?
                        onus ci records push --dir rec
                        [ $code -eq 0 ] || [ $code -eq 3 ]
```

A hold (exit 3) passes the job; the next analysis run decides again. A rollback (exit 2) fails it, and so does an error (exit 1: a change not on record, a blocked change, unreadable metrics), so a rollout Onus could not judge is not promoted. Set each step's pause to at least the plan's bake time.

### A flag service

A step is a flag percentage. Turn the flag named in the plan up to each step, report the stage with `onus ci rollout --percent`, and on exit 2 turn it off. The rollback is already recorded.

## Area history

```sh
onus signals areas --records rec [--days 90] [--repository acme/shop]
# {"since":1757000000,"days":90,"areas":{"billing":{"reverts":1,"incidents":1,
#   "changes":["acme/shop#42"],"errorSpikes":2,"lastAt":1759990000}}}
```

Each component's history in the window: reverts and rollbacks (a planned rollback does not count), incidents, the changes behind them (a signal tied to no change stands for itself by its id), error spikes (error-spike, latency and metric signals of medium severity or more, or none given) and when the latest was recorded. Incidents and rollbacks tied to a change are counted once, from their outcomes. Deploys, rollout stages and traces are not history. A signal tied to no change names no repository, so it counts for its components in every repository whose records hold it (Onus Cloud keeps one records folder per organisation); give its `change` or `commit` to scope it. `--repository owner/name` counts only that repository's changes (and the signals tied to no change), as a classification of one of its changes reads them; without it, every repository's changes count. This is the history the classifier's `history` input reads, and what tightens rollout plans.

An agent setup whose recent changes were rolled back cannot auto-merge either: `record.recentRollbacks` in `onus ci pr`'s summary, and a `record` reason in the lane.

## In provenance

The provenance record's `rollout` ([`onus help lanes`](/docs/lanes)) holds what production said about the change: `status`, `percent`, the `plan` from its pull record, every deploy and rollout stage in time order (`stages`), and every other signal tied to it (`signals`). `onus provenance --records` reads `signals.jsonl` there; `--signals FILE` reads another.

| First that applies | `status` | `percent` |
|---|---|---|
| still open | `pending` | none |
| closed without merging | `not-shipped` | none |
| latest outcome `rolled-back` | `rolled-back` | the last stage's |
| latest outcome `reverted` | `reverted` | the last stage's |
| no production stage yet | `awaiting-deploy` | none |
| last stage decided `rollback` | `rolled-back` | its share |
| last stage decided `hold` | `holding` | its share |
| last stage at 100, `complete` or a deploy | `complete` | 100 |
| otherwise | `in-progress` | its share |

Only stages in production (`environment` absent or `production`) count; the others are listed. A deploy that names no share counts as 100.


---

## Reading a report

URL: https://onushq.com/docs/reports

Reading a report: rows, ranking, evidence, the changed lines tests ran and the JSON


<!-- Generated by npm run docs:sync from crates/onus-cli/guide/reports.md in onushq/onus; edit it there. -->

# Reading a report

A report for the manifesto's example (1,408 changed lines in 23 files):

```md
### Onus · 4 meaning-level changes · 1 needs attention · 1,408 lines in 23 files

|   | Change                                                       | Kind                      | Why it matters |
| ● | `notifications` now calls an external SMS provider (Acme SMS) | New external dependency   | Customer phone numbers leave the system via Acme SMS, a new vendor; needs a person |
| ○ | `UserPreferences` gains an optional `phoneVerified` field     | Contract change, additive | Shared contract used in 4 files across 2 components; existing callers unaffected |
| ○ | `notifications` subscribes to the `OrderShipped` event        | New event consumer        | Additive; `orders` is unchanged |
| ○ | 1,402 lines of new code and tests inside `notifications`      | Internal                  | Stays inside `notifications`, which `billing` depends on; adds 69 test cases; ... |

**Intent check:** not stated · **Boundary rules:** no new violations
```

## The headline

The number of meaning-level changes (rows), how many need a person, and the size of the text diff: lines added plus removed, and files changed. When nothing changed in meaning (only formatting, comments or moved files), the headline says "no changes in meaning".

## The rows

Each row is one change in meaning, computed from the code and described with a fixed template. Nothing in a row is generated by a language model.

- **● or ○**: ● means a person should look at this row. Onus marks a row this way when it is security-sensitive, breaking, a rules-of-the-game change (tests, CI, policies, onus.yaml, CODEOWNERS) or outside the stated intent.
- **Change**: what happened, in one line.
- **Kind**: the kind of change ([`onus help changes`](/docs/changes) lists them all). "Outside stated intent · " is prepended when the row is an intent mismatch.
- **Why it matters**: the consequence, with the facts behind it: who depends on the thing that changed, which labels apply, what data leaves the system.

## Order

Rows are ranked so the one that deserves attention comes first. Changes outside the stated intent come first, then every row that needs a person (●), then the rest; within each of those, by kind:

1. changes outside the stated intent
2. security-sensitive changes
3. breaking changes (including boundary-rule violations)
4. new or changed dependencies
5. rules of the game (tests weakened, CI, policies, onus.yaml)
6. configuration
7. additive contract changes
8. new relationships (events, data, components)
9. tests
10. notable internal edits, then renames, then the internal rows

Within a group, rows Onus is unsure about come first (unknowns count as higher risk), then rows with changed lines no test ran (with coverage), then rows in components with sensitivity labels, then rows with a larger blast radius (more dependent files).

## Internal rows

Every row lists the lines it explains. The changed lines no row explains collapse into one internal row per component, such as "1,402 lines of new code and tests inside `notifications`". Its "why" says whether other components depend on that component, how many test cases were added, which new config keys are read, and whether some of the code could not be resolved.

## Intent check and boundary rules

- **Intent check**: "not stated" when no intent was given, "matches stated intent", or the number of changes outside it, followed by the reason for each. See [`onus help intent`](/docs/intent).
- **Boundary rules**: "none declared", "no new violations", or the number of new violations. Violations that already existed before the change are not reported.

## Evidence

The collapsed "Evidence per row" section lists, for each row, its kind and subkind, confidence, labels, blast radius, how many other components use what it changed ("used by 3 other components"), whether tests reach its code ("tested", "traced, not tested" or "untested"), with coverage how many of its changed lines tests ran ("tests ran 3 of 5 changed lines"), novelty and line counts, and every file and line behind it. Lines marked "(before the change)" are in the base tree, for example a deleted assertion.

## Tests ran

With coverage of the head (`--coverage`, or `--evidence` with runs an environment recorded at the head commit; [`onus help environments`](/docs/environments)), the intent line gains a third part:

```md
**Intent check:** matches stated intent · **Boundary rules:** no new violations · **Tests ran:** 34 of 40 changed lines (85%)
```

A changed line is an added or edited head line the coverage counts as executable. "no changed executable lines" means the change touched none in the files the coverage measured, and no changed file with runtime code was left out of it. When one was, the line says so ("no measured changed lines; 1 changed file not in the coverage"), and so does the summary of the section below. A collapsed "Changed lines no test ran" section then lists those lines by file, the changed files with runtime code the coverage does not include ("not in the coverage (no test loaded it)"), what was left out and why, and each coverage file with its format and origin (`supplied` or `recorded`). The percentage is rounded down, so 100% means every changed line ran.

Without coverage the report is exactly as before.

## Behavior

With `onus report --behavior`, the tests that reach the change run at the base and at the head ([`onus help environments`](/docs/environments)). A line under the intent line says what ran:

```md
**Behavior:** 3 test files run at base and head (selected from the map) · 1 changed, 0 newly failing · 48s of 600s
```

It says "no tests reach the changed code" when the maps link no test to it, `**partial:**` with the reason when the budget ran out or a run failed, and `skipped:` with the reason when nothing ran. A collapsed "Behavior runs" section lists each run with its cases, failures and manifest, the selected test files and why each was chosen, and the cases already failing at the base or found flaky.

What the runs showed becomes rows, one per kind and component, with `level` `behavior` and confidence `traced` (observed at runtime):

| Subkind | When | Kind | Effect |
|---|---|---|---|
| `behavior-newly-failing` | A case passes at the base and fails at the head, and again when run once more; or a new case fails at the head | Behavior change, tests fail | ●; **blocked** until a person approves the row (`/onus approve <row id>`) |
| `behavior-changed` | The base version of an edited test passes at the base but fails against the head's code, and the head's version passes: the test was edited to match new behavior | Behavior change, tests updated | ●; rules of the game, so a person reviews it |
| `behavior-newly-passing` | A case fails at the base and passes at the head | Behavior change, fix | none |
| `behavior-output-changed` | A case fails at both, with a different message | Behavior change, output | none |

Messages are compared without colours, durations, addresses or the environment's `/work/` path, and the row quotes the failure. A newly failing case that was not run again (the budget ran out) has confidence `inferred` and says so. A case that disappears at the head is left to "Tests weakened".

Without `--behavior` the report is exactly as before.

## Structure only

Files that moved without changes, and files whose only changes are formatting, comments or updated import paths, are listed here instead of as rows.

## Map confidence notes

Code in the changed files that Onus could not resolve statically: dynamic imports, calls through computed members, event names computed at runtime, unresolved imports. Rows touching these files are marked low confidence. See [`onus help troubleshooting`](/docs/troubleshooting).

## The JSON report

`--format json` gives everything in the Markdown and more ([schemas/semantic-report.schema.json](https://github.com/onushq/onus/blob/main/schemas/semantic-report.schema.json)):

- `summary`: counts of rows, rows needing attention, secrets, new rule violations and intent mismatches.
- `changes`: the ranked rows. Each has an `id`, `kind`, `subkind`, `level` (relationship, behavior or structure), `subject` (the map id it is about), `component`, `title`, `whyItMatters`, `hints` (labels, blastRadius, novelty, confidence, rulesOfTheGame, intentMismatch, needsPerson, dependentComponents, `dependents` when there are any, `tested` for rows that change code, `owners` when the component has owners, and `coverage` `{changed, ran}` when coverage was given and the row changes executable lines), `locations` (file, lines, side) and, for internal rows, `stats`.
- `intentCheck`, `ruleViolations`, `structure`, `textStats` and `mapDiagnostics`.
- `behavior`, only with `--behavior`: `status` (`complete`, `partial` or `skipped`), `reason`, the `command` template, `budgetSecs` and `elapsedSecs`, `selected` (each test file with `changed`, `depth`, `via`, and whether it exists at the `base` and `head`), `truncated`, `runs` (`side` `base`, `head`, `retry` or `cross`, `commit`, `files`, the evidence `manifest`, `exitCode`, `timedOut`, `cases`, `failed`, `skipped`), `flaky` and `alreadyFailing` (`file › case`).
- `coverage`, only with coverage: `sources` (format, path, sha256, origin, the evidence `manifest` and its run's `command` when recorded, files matched and not), `changed`, `ran`, `notRun` (head-side locations), `notMeasured` (changed files) and `notes`.

Output is deterministic: the same two trees always give byte-identical Markdown and JSON, with no timestamps or absolute paths. A coverage file is named by its path relative to the working directory, or as given when it is outside it.

## The head's map

`onus report --head-map-out <file>` also writes the head ref's map ([schemas/codebase-map.schema.json](https://github.com/onushq/onus/blob/main/schemas/codebase-map.schema.json)), built with the same onus.yaml as the report. It is the map every row was computed against, so the two always agree, and it holds the traces and coverage the report was given. Ask it questions with `onus query --map <file>`, such as what depends on a contract a row names. Onus Cloud keeps this map for the newest head of each pull request it analyses ([`onus help cloud`](/docs/cloud)).


---

## Scoped tokens, the gateway and escalation

URL: https://onushq.com/docs/scopes

Task tokens, the git gateway, escalation with evidence and the audit log


<!-- Generated by npm run docs:sync from crates/onus-cli/guide/scopes.md in onushq/onus; edit it there. -->

# Scoped tokens, the gateway and escalation

An agent should work with exactly the access its task needs, never hold your forge credential, and ask with evidence when it needs more. Onus does that with task tokens, doors that enforce them, structured escalation and an audit log. Nothing here depends on which agent you use.

## Task tokens

Create a root key once and keep the private half with whoever approves tasks:

```sh
onus token keygen --out ~/.onus-keys        # root.key (private, 0600) and root.pub
```

Describe a task in a plan:

```yaml
task: sms-alerts
writes: ["services/notifications/**"]
reads: ["services/orders/events/**"]       # optional
hosts: ["sms.test.example"]                 # optional: network for its environment
secrets: ["SMS_TEST_KEY"]                   # optional
refs: ["refs/heads/onus/sms-alerts/*"]      # default: refs/heads/onus/<task>/*
ttl: 8h                                     # default 8h
agent: {tool: claude-code, model: opus}     # optional: who does the task
```

`onus scope suggest --plan plan.yaml` proposes reads from the map: the components the task writes, what they use and what uses them. It leaves out components labeled sensitive (they must be asked for), and it never widens writes.

```sh
onus token mint --plan plan.yaml --key ~/.onus-keys/root.key --audit audit.jsonl
```

A token is a [Biscuit](https://www.biscuitsec.org/): signed rights (`write:path:<glob>`, `read:path:<glob>`, `push:ref:<glob>`, `net:host:<host>`, `secret:<NAME>`), the task id, the agent when the plan names one (`tool`, `model`, `config`, `team`) and an expiry. Submissions and log entries made under a token that names an agent use that agent, whatever the agent says it is. Writing implies reading. Anyone holding a token can narrow it for a sub-agent, but nobody can widen it without the root key:

```sh
onus token attenuate --token "$TOKEN" --key-public root.pub --only write:path:services/notifications/src/sms/**
onus token inspect --token "$TOKEN" --key-public root.pub
onus token check --token "$TOKEN" --key-public root.pub write:path:services/billing/a.ts   # exit 1 and why
```

Path globs use `*` (within a folder), `**` (any depth) and `?`, and are case-sensitive like git paths.

### Components and contracts instead of paths

A plan can name what the task may touch in the map's terms:

```yaml
task: sms-alerts
writeComponents: [notifications.internal]   # its files that declare no public symbol
readContracts: [UserPreferences]            # the file that declares the contract
escalateBefore: ["contract:*"]              # contract files need a granted escalation to change

onus token mint --plan plan.yaml --key root.key --repo .
```

Minting resolves them through the map into path rights (`writeComponents: [notifications]` means all of the component's files), so a token's paths do not drift while the task runs. `escalateBefore` adds `guard:path:` rights for the files that declare matching contracts (onus.yaml `contracts:`): the gateway refuses a push that touches one unless the token also holds `unlock:path:` for it, which only an escalation grant adds. The refusal says how to ask.

## The git gateway

The gateway holds the real repository and its credentials; agents clone from it and push to it with their token as the password:

```sh
onus gateway serve --repo /srv/gateway/shop --remote origin --base main \
  --key-public root.pub --state /srv/gateway/state --listen 127.0.0.1:9419

git clone http://agent:$TOKEN@127.0.0.1:9419/sms-alerts.git
```

- **Reads.** Each task gets a mirror whose single commit holds only the paths it may read. The other files are not in its objects or its history, so no git command can show them.
- **Writes.** Each push is checked by the mirror's hook, which verifies the token again: every changed path of every new commit must be writable, refs must be in the push scope, and symbolic links, submodules, merges, new root commits and paths that collide by case with one outside the scope are refused. A refusal says how to ask:

      onus: push refused for task `sms-alerts`:
        - `services/billing/src/refund.ts` is outside your write scope
      Your write scope: `write:path:services/notifications/**`
      To change it, ask with evidence (a failing test is the strongest):
        onus escalate --task sms-alerts --scope write:path:services/billing/src/** --evidence failing-test:<test file> --reason "…"

- **Landing.** Accepted commits are replayed onto the real base commit, same files, authors and messages, and pushed to the remote with the credential only the gateway holds. Everything the agent could not see is still in the real commits.

The gateway needs `git http-backend`, which ships with git. It answers on the address you give it; keep it on a loopback or private network.

## Read scope for the map

`onus mcp --token "$TOKEN" --key-public root.pub` answers only about files the task may read: a question about an unreadable symbol or file is refused, and lists leave out unreadable items (the answer says how many). Every other tool is checked against the token too, and every call is logged ([`onus help agents`](/docs/agents)).

## Escalation

When a task needs more, it asks with a structured request:

```sh
onus escalate --task sms-alerts --scope write:path:services/orders/src/** \
  --evidence failing-test:services/orders/src/ship.test.ts \
  --reason "the shipped event must carry the phone number" --out request.json
```

Evidence is graded: 1 a failing test, 2 a trace, 3 a path through the map, 4 a draft diff, 5 a rationale. Onus adds the blast radius (files that depend on the asked paths) and the sensitivity labels of the components involved: those of the asked paths and of the files the evidence names. It also adds the owners (from onus.yaml or CODEOWNERS), who a person-decision goes to. They are the people who own every component the asked paths reach. A path reaches a component by the component's paths (onus.yaml `path`, or its folder), so a file that does not exist yet counts. Asking for one more path can only remove an owner, never add one, so an agent cannot choose who may grant its request. There are no owners, and an admin decides, when no one owns it all, when part of an asked path is in no component (onus.yaml, CI workflows or a root package.json, say), or when a right is not a path (a ref, a host or a secret). Evidence adds no owner. A request that asks for nothing, such as a broken-test report, grants nothing, so it goes to the owners of the files its evidence names.

```sh
onus escalation decide request.json --token "$TOKEN" --key-public root.pub --key root.key \
  --reproduce-at HEAD --image node:22 --setup "npm ci" --test-command "npx vitest run {test}" \
  --audit audit.jsonl
```

A request is granted automatically only when all of these hold:

- it asks for path rights;
- the paths are outside sensitive components;
- the blast radius is small (20 files by default, `--max-blast-radius`);
- a failing test was reproduced by the test runner.

Then the command prints a new token: the original rights plus exactly what was asked, for the rest of the task. The token names the request it grants, so it proves that grant and no other. It is minted from the first block of `--token`, so grant from the token the task was given, not from a narrowed one. Otherwise it exits with code 3 and the reasons, and a person decides:

```sh
onus escalation grant request.json --token "$TOKEN" --key-public root.pub --key root.key --by @team-orders
onus escalation deny request.json --by @team-orders --reason "use the events API instead"
```

`--id <id>` and `--scope <right>` (repeated) make `grant` mint only when the file still holds that request, asking for exactly those scopes. Use them when the person decided somewhere else, such as Onus Cloud, and the file sat where the agent can write.

Before running a failing test, Onus checks that its reference is a plain path in the repository (letters, digits and `._/@+-`, no `..`, not absolute), that the file exists at the commit, and that it is a test file (onus.yaml `tests.globs`). The test command must name the test (`{test}`); one that does not would run every test, so nothing is run. A request's failing tests get 15 minutes in all, pulling the image and the setup included. A test still running then is stopped and its containers removed, and one not started by then is not run. Until then the command, `onus ui`'s Decide by policy and `onus_escalate` deciding by policy wait for it. A reference that fails a check, or a test that is stopped or not started, is not run to the end. It counts as not reproduced and sends the request to a person, even when another failing test reproduced, and the reasons say why. Whether a test reproduced is only ever what this run saw: a request file that says so is not believed, and one changed after it was filed is refused. The test only has to fail at the agent's commit, so an agent could write one that always fails; that is why the policy grants only path rights with a small blast radius outside sensitive components.

### Where a request goes

`onus_escalate` (and `onus_blocked`, a report that the task is blocked) always keeps the request in `.onus/escalations/<id>.json`. Then, in this order:

1. **Signed in to Onus Cloud** (a login, a scoped token with `escalation:write`, or an API key): it is filed there, and the local policy does not run. Onus Cloud assesses it on the repository's default branch with `onus escalation assess`, so an agent cannot weaken it by editing onus.yaml on its branch, and a person decides there. `onus_escalation` asks where it stands and writes the decision into the audit log. On a grant, `onus mcp` mints the token itself with the root key it holds (`--key`): the old rights plus exactly the scopes of the request it kept. A request file changed after it was filed, or a grant of other scopes than the file asks for, mints nothing. Onus Cloud never mints, and never sees the task token or the root key. See [`onus help cloud`](/docs/cloud).
2. **Not signed in, the server holds the root key and a trusted checkout** (`onus mcp --token … --key root.key --trusted-repo ../shop-main`): the policy above decides here, and mints on a grant. The blast radius, sensitive labels and owners come from the trusted checkout's map, and the test command from its onus.yaml (`tests.command`), run at the agent's commit. The trusted checkout is one whose files the agent cannot edit, such as a `git worktree` of the default branch outside the agent's, so the agent's commits resolve there. A git worktree shares git's config, hooks and refs with the agent's, and the server runs git and the test command in it, so keep those out of the agent's reach as well. Without it, the facts would come from the agent's own worktree, which the agent can edit, so the policy does not run.
3. **Otherwise:** the request waits in the folder for a person in `onus ui`, or `onus escalation grant`.

### Assessing without minting

`onus escalation assess` applies the same policy and mints nothing, so it needs neither a token nor a key. Hosted services use it, and it records nothing in the audit log, because assessing is not deciding:

```sh
onus escalation assess request.json --repo <trusted checkout> --reproduce-at <commit>
```

The test command comes from the trusted checkout's onus.yaml (`tests.command`), and the image and setup from its `environment:` (or devcontainer), else `node:22`. An environment that is declared but cannot be used (a devcontainer that builds from a Dockerfile, say) is not replaced by `node:22`: the test is not run, and the reasons say why. The agent's commit is only the tree the test runs in, so the agent cannot choose what reproduces a failure. `--test-command`, `--image` and `--setup` override them. Without a test command, failing tests are not reproduced, and the reasons say so. It prints the request with its reproduced evidence (which keeps its id: what a run saw is not part of it), `decision` (`granted` or `needs-person`) and `reasons`, and exits 0 when policy would grant it, 3 when a person decides.

### The test runner

`onus run-test --repo . --reference HEAD --image node:22 -- npx vitest run path/to.test.ts` runs a command at a commit in a throwaway container: no network, no capabilities, 4 GB of memory, 2 CPUs. The commit's files are copied in, never mounted, so engines that run in a VM (colima, podman machine) work too. Onus runs repository code only here and in environments ([`onus help environments`](/docs/environments)), and only when asked. An optional `--setup` command (installing dependencies) runs first in its own container, with network. It needs Docker or Podman.

## The audit log

Every decision is one JSON line: mints, mirrors, pushes accepted and refused, replays, escalations, grants and denials, and every call through a door. Each line carries the hash of the line before it, so a removed or edited line breaks the chain:

```sh
onus audit /srv/gateway/state/audit.jsonl     # "N entries, chain intact", or where it breaks
```

What the doors log:

| Action | Door | Decisions |
|---|---|---|
| `mcp:<tool>` | `onus mcp`, every tool call | `allowed` or `denied`; then `done` or `failed` for tools that act |
| `adopt-token` | `onus mcp`, when it takes up a granted escalation's token (only one that keeps every right and narrowing of the token it holds) | `allowed` |
| `auth` | the gateway, a refused password (bad token, another task's, expired) | `refused` |
| `fetch` | the gateway, every clone and fetch | `allowed` |
| `push`, `mirror`, `replay` | the gateway | as before |

An `onus mcp` entry looks like this:

```json
{
  "seq": 42, "at": 1791500000,
  "actor": "sms-alerts",                        // the token's task, or "local" without one
  "action": "mcp:onus_env_run",
  "subject": "sms-1",                           // an environment, run, submission, target, path or pull request
  "decision": "allowed",
  "reason": "the token of task `sms-alerts` allows it",
  "details": {
    "door": "mcp",
    "argsDigest": "sha256:…",                   // of the arguments, keys sorted
    "args": { "name": "sms-1", "command": "npm test" },   // long strings and lists shortened
    "token": { "task": "sms-alerts", "id": "3f9a…", "expires": 1791528800, "attenuations": 0 },
    "agent": { "tool": "claude-code", "model": "opus", "config": "", "team": "", "from": "token" },
    "missing": ["net:host:evil.example"],       // denials
    "hidden": 3,                                // questions whose answer left items out
    "result": { "runId": "…", "exitCode": 0 }   // done
  },
  "prev": "…", "hash": "…"
}
```

The token itself is never logged, only its id (the first 16 hex characters of its sha256). `details.result` keeps what later checks need: the hosted environments and runs a task made, which `onus_cloud_env_run`, `onus_cloud_env_destroy` and `onus_cloud_attach_evidence` are checked against. A broken chain refuses those calls until a person checks the log.

The chain is plain sha256: someone who can write the file can rewrite it consistently. Keep the log where agents cannot write (`onus mcp --audit`, the gateway's state folder).

The log can travel with the work. `onus_cloud_attach_evidence` with `doorLog: true`, or `onus cloud evidence <pull> --door-log --task <task>`, attaches the task's slice to the pull request in Onus Cloud: the entries from the task's first to its last, with whatever lies between, so the chain can be checked over it where it is read. `onus ci pr --audit` and `onus provenance --audit` check it and keep the task's entries in the change's provenance (`onus help provenance`). Through `onus mcp --token`, the door sends its inspection of the token it holds with the slice (`{task, rights, attenuations, expires}`), never the token. A slice shows only that nothing in it was changed or removed, not what came before it, nor who cut it. Other tasks' entries between the task's first and last go with it, so it is attached only to the pull request whose head in Onus Cloud is the worktree's commit.


---

## Troubleshooting

URL: https://onushq.com/docs/troubleshooting

Map confidence notes, common questions and current limits


<!-- Generated by npm run docs:sync from crates/onus-cli/guide/troubleshooting.md in onushq/onus; edit it there. -->

# Troubleshooting

## Map confidence notes

These diagnostics mean Onus could not resolve something statically. Rows touching those files are marked low confidence and rank higher.

| Diagnostic | Meaning | What to do |
|---|---|---|
| unresolved-import | An import points at a file or export that does not exist. | Check the path, tsconfig `paths`, or the workspace package's entrypoint. |
| dynamic-import | `import(x)` or `require(x)` with a computed path. | Nothing, if intended; the target is unknown to Onus. |
| dynamic-access | A call through a computed member, such as `handlers[name]()`. | Nothing, if intended. |
| dynamic-config-key | `process.env[x]` with a computed key. | Nothing, if intended. |
| dynamic-event-name | An event name computed at runtime. | Use a string literal, a constant or an enum member. |
| raw-query | `prisma.$queryRaw` and similar: the tables are unknown. | Nothing; the call is flagged so a person can look. |
| parse-error | The file has a syntax error; its facts may be incomplete. | Fix the syntax. |
| no-entrypoint | A component has no entrypoint, so all its symbols are internal. | Add `main`, `types` or `exports` to its package.json, or `entrypoints` in onus.yaml. |
| unknown-contract | A contract in onus.yaml names a symbol that is not in the map. | Fix the id; list ids with `onus map . --json`. |
| provider-skipped | A plugin that may run repository code was not run, because trusted mode is off. | Run with `--trusted` where the code is trusted. |
| provider-failed | A plugin failed, timed out, returned invalid JSON, or has no sandbox available. | Read the message; check the plugin's command and `sandbox`. |
| plugin-output-dropped | A plugin returned paths outside the tree or ids of unknown components; those parts were ignored. | Fix the plugin. |

## Common questions

**A change I care about only shows up in the internal row.**
Onus reports the kinds of change listed in [`onus help changes`](/docs/changes). Label the component (`labels: [payments]`) so edits there become security-sensitive, declare your event patterns and SDKs in onus.yaml, and declare boundary rules.

**An exported symbol is listed as internal.**
Only symbols reachable from the component's entrypoint are public. Check which entrypoint Onus found (`onus map . --json`, under `components`) and set `entrypoints` in onus.yaml if it is wrong.

**My SDK is not detected as an external service.**
Add it under `extractors.externals`, keyed by its npm package. Onus counts an SDK as called when code calls something imported from it, directly or through a class field declared with its type.

**My events are not detected.**
Declare the call patterns under `extractors.events`; declaring them replaces the defaults.

**A rename shows up as a removed and an added symbol.**
Renames are detected only when the body is identical. A rename plus an edit shows as two changes; for a public symbol that means an export removed (breaking) and an export added.

**`onus report` says a ref is unknown.**
The commit is not in the local clone. In CI, fetch the full history (`fetch-depth: 0`) or fetch the base commit explicitly.

**The line counts differ from GitHub's.**
Onus diffs the two trees it analyzes: files in skipped folders or ignored by .gitignore are not counted, and a file moved with identical content counts as zero lines.

**The same pull request gives a different report.**
It should not: output is deterministic for the same two trees and the same onus.yaml. The base version's onus.yaml is used for both trees, so a pull request that edits onus.yaml is still checked against the old file.

**Is it safe to run on pull requests from forks?**
Yes. Onus reads files only: it never installs dependencies, runs scripts or executes the code it analyzes.

**The report states something wrong.**
That is a bug: a wrong fact is worse than a missing one. Open an issue with the JSON report (`--format json`) and, if you can share them, the files involved.

## Current limits

- Built in: TypeScript and JavaScript. Other languages need a plugin, a SCIP index or a language server ([`onus help plugins`](/docs/plugins)).
- CommonJS exports (`module.exports`, `exports.x`) are not modeled.
- Data access is detected for Prisma only.
- No runtime information: dependency injection, reflection and calls between services over the network are only visible through the patterns above.


---

## The web interface

URL: https://onushq.com/docs/web-interface

The web interface: onus ui opens all of it in your browser


<!-- Generated by npm run docs:sync from crates/onus-cli/guide/web-interface.md in onushq/onus; edit it there. -->

# The web interface

`onus ui` opens everything Onus does for a repository in your browser: the map, reports, lanes and the judge, environments and evidence, tokens, escalations, the audit log and outcomes. It ships inside the binary; nothing is installed and nothing leaves your machine.

```sh
onus ui                      # the repository containing the current directory
onus ui --repo ../shop --port 0 --no-open
```

It prints an address such as `http://127.0.0.1:4387/#token=…` and opens it.

## What it shows

| Page | What you can do |
|---|---|
| Overview | Map totals, the component graph, uncommitted work, recent commits, what is set up |
| Map | The component graph (pan and zoom, by layer or by folder, focus on a component and its neighbours, filter imports, calls and types), a treemap by folder and size, components, files, events and external services; find symbols; per component, symbol and file: owners, public surface, dependents, dependencies, tests, declared invariants, and the impact of a change |
| Changes | Check uncommitted work (what `onus_check` gives an agent), or report any two refs, with an intent; download Markdown or JSON |
| Lanes & judge | The lane policy; submissions agents handed in over MCP; make a submission with evidence from the store, classify it and run the judge |
| Environments | Create environments, run commands, browse the evidence store and its artifacts, run a test once |
| Outcomes | Changes by week and lane, each agent setup's progress toward auto-merge, pull requests in flight, totals per agent setup and judge, the human-lane share and audit miss rate; record outcomes and incidents and find reverts, or fetch the records the GitHub Action keeps |
| Tokens & scopes | Generate a root key, plan a task, suggest reads, mint, inspect, check and narrow tokens |
| Escalations | File requests with evidence; decide by policy, grant or deny |
| Audit log | Every decision, and whether the hash chain is intact |
| onus.yaml | Edit it with a form (components, labels, boundary rules, contracts, lanes, events and services, tests, the environment) or as YAML, checked as you type; review the changes and save. Edits touch only the lines they change, so comments and alignment stay as written, and the map is rebuilt with the new config at once. Start from what `onus init` suggests |
| Guide | This guide |

The map follows the files on disk, so pages show your work as you edit.

## Where things are kept

- Outcome records: `.onus/outcomes.jsonl` (`--outcomes`); when that file does not exist, the `onus/records` branch the GitHub Action keeps (`origin/onus/records`), read-only
- The audit log: `.onus/audit.jsonl` (`--audit`)
- Escalation requests: `.onus/escalations/` (`--escalations`), with granted tokens beside them for the agent to collect
- Submissions from agents: `.onus/submissions/`
- The root key pair: `~/.onus-keys` (`--keys`)
- Evidence: the repository's git directory, as for `onus env`

## Security

The server listens on 127.0.0.1 only and answers only requests addressed to a loopback name, so a web page elsewhere cannot reach it through DNS rebinding. Its API needs the session token from the address it printed; the token travels in the address's fragment, which browsers never send to a server, and the page keeps it for the tab only. Cross-origin requests are refused. Anyone who can run programs as you can already do what the interface does.

## Building from source

Release binaries include the interface. A build from source embeds it when `ui/build` exists:

```sh
cd ui && npm ci && npm run build
cargo build --release -p onus-cli
```

Without it, `onus ui` serves the API and a page that says how to add the interface. To work on the interface itself, run `ONUS_UI_TOKEN=dev onus ui --no-open` and, in `ui/`, `npm run dev`, then open `http://localhost:5173/#token=dev`.


---