<!-- Generated by scripts/ax-docs.mts from the JSDoc in registry/ouro/ax/. Do not edit; run `pnpm run docs`. -->

# ax-claims

The Ouro AX standard as data: a claim is one checkable rule about an interface an agent uses, with the reason, the evidence that admitted it, the check `ax-xray` runs and the fix. A claim is `must` only when an evaluation showed agents failing without it, or when it guards against a stated safety, compatibility or integrity hazard; every other claim is `should`.

```sh
npx shadcn@latest add ourostack/ouro-ui/ax-claims#v1.3.10
```

It installs `lib/ouro/ax/claims.ts`. Its tests are `ax-claims-tests`. Every item runs on Node 22.18 or later as it is copied: the files import each other as `./<file>.ts`. The [Ouro AX guide](ax.md) shows how they fit together.

## Exports

### `checkClaimSet`

The problems with a claim set, one line each with the fix: a missing field, a repeated id, an unknown surface, tier or scope, and a `must` claim the admission rule does not allow (one that rests on a principle, an evaluation without its run, or a hazard not stated).

```ts
function checkClaimSet(value: unknown): string[]
```

### `Claim`

```ts
interface Claim {
  id: string;
  surface: ClaimSurface;
  tier: ClaimTier;
  applies: ClaimScope;
  rule: string;
  why: string;
  evidence: ClaimEvidence;
  check: string;
  fix: string;
}
```

### `CLAIM_SCOPES`

```sh
Which surfaces a claim applies to. The X-ray decides it from what the interface says about itself (`help --json`, the
routes manifest, tools/list), not from a hand-written waiver:
- `interface`: once per interface.
- `command`, `read`, `others`, `text`, `wait`: CLI commands, the reads among them (effect private), those other people
see, those that take free text, and the wait command.
- `events`: the work-event read the adopter names.
- `route`, `read-route`, `ref-route`, `others-route`: HTTP routes that answer an error, GET routes, routes with an id
in the path, and the probes of writes other people see.
- `tool`, `tool-required`: MCP tools, and those with required arguments.
- `twin`, `action-twin`, `person-only`, `reserved`, `self`, `ui-read`, `listening`, `listening-push`: from the `ui`
inventory, the twins, the twins of agent actions, the person-only actions, the actions with a reserved id, the
actions an agent takes only on its own item (`scope: "self"`), the reads, the reads of what people say, and their
streams.
```

```ts
const CLAIM_SCOPES: readonly ["interface", "command", "read", "others", "text", "wait", "events", "route", "read-route", "ref-route", "others-route", "tool", "tool-required", "twin", "action-twin", "person-only", "reserved", "self", "ui-read", "listening", "listening-push"]
```

### `CLAIM_SET`

The claims of this version of Ouro AX. Evidence paths are relative to the Ouro UI repository (https://github.com/ourostack/ouro-ui).

```ts
const CLAIM_SET: ClaimSet
```

### `CLAIM_SET_VERSION`

The Ouro AX standard as data: a claim is one checkable rule about an interface an agent uses, with the reason, the evidence that admitted it, the check `ax-xray` runs and the fix. A claim is `must` only when an evaluation showed agents failing without it, or when it guards against a stated safety, compatibility or integrity hazard; every other claim is `should`.

```ts
const CLAIM_SET_VERSION: "1.5.0"
```

### `ClaimEvidence`

Why a claim is in the standard. `evaluation`: an agent evaluation (`source` is the run's file); `hazard`: the harm it guards against, in `finding`; `principle`: a design principle, not yet shown by a run (`should` only).

```ts
interface ClaimEvidence {
  basis: "evaluation" | "hazard" | "principle";
  source: string;
  finding: string;
}
```

### `ClaimScope`

```ts
type ClaimScope = (typeof CLAIM_SCOPES)[number];
```

### `ClaimSet`

```ts
interface ClaimSet {
  version: string;
  claims: readonly Claim[];
}
```

### `claimSetText`

The claim set as canonical JSON (keys sorted), the text its hash is taken over.

```ts
function claimSetText(set: ClaimSet): string
```

### `ClaimSurface`

```ts
type ClaimSurface = "cli" | "http" | "mcp" | "ui";
```

### `ClaimTier`

```ts
type ClaimTier = "must" | "should";
```

### `loadClaimSet`

A claim set read from JSON (an adopter's own copy, say), checked; throws with every problem when it is not one.

```ts
function loadClaimSet(value: unknown): ClaimSet
```

## The claims

Must claims first. `node lib/ouro/ax/xray.ts claims` prints their rules and checks; [the standard](ax-standard.md) says how a claim is admitted.

| Claim | Tier | Admitted by |
| --- | --- | --- |
| `cli.help-parses` | must | hazard |
| `cli.help-effects` | must | hazard |
| `cli.inventory` | must | hazard |
| `cli.exit-codes` | must | hazard |
| `cli.unknown-flag` | must | hazard |
| `cli.ambiguous-verbs` | must | hazard |
| `cli.others-need-why` | must | hazard |
| `cli.wrong-ref-first` | must | hazard |
| `cli.others-preview` | must | hazard |
| `cli.text-as-argument` | must | evaluation: [eval-baseline.md](https://github.com/ourostack/ouro-ui/blob/main/docs/decisions/2026-10-30-ouro-ax/evidence/eval-baseline.md) |
| `cli.wait-on-refs` | must | evaluation: [eval-baseline.md](https://github.com/ourostack/ouro-ui/blob/main/docs/decisions/2026-10-30-ouro-ax/evidence/eval-baseline.md) |
| `cli.reads-stay-reads` | must | hazard |
| `cli.refusals-change-nothing` | must | hazard |
| `cli.no-dev-commands` | must | hazard |
| `copy.precise-failure` | must | hazard |
| `http.inventory` | must | hazard |
| `http.wrong-ref-first` | must | hazard |
| `http.others-need-why` | must | hazard |
| `http.reads-stay-reads` | must | hazard |
| `http.refusals-change-nothing` | must | hazard |
| `mcp.effect-annotated` | must | hazard |
| `mcp.inventory` | must | hazard |
| `ui.twin-exists` | must | hazard |
| `ui.twin-effect-matches` | must | hazard |
| `ui.person-only-refuses` | must | hazard |
| `ui.reserved-person-only` | must | hazard |
| `ui.self-scope-refuses` | must | hazard |
| `ui.listening-needs-yes` | must | hazard |
| `cli.listening-push-filtered` | must | hazard |
| `cli.command-help` | should | evaluation: [eval-baseline.md](https://github.com/ourostack/ouro-ui/blob/main/docs/decisions/2026-10-30-ouro-ax/evidence/eval-baseline.md) |
| `cli.help-width` | should | principle |
| `cli.overview-short` | should | principle |
| `cli.read-json` | should | principle |
| `cli.unknown-command` | should | principle |
| `cli.flag-suggest` | should | evaluation: [xray-probe.md](https://github.com/ourostack/ouro-ui/blob/main/docs/decisions/2026-10-30-ouro-ax/evidence/xray-probe.md) |
| `cli.missing-arg` | should | principle |
| `cli.one-line-error` | should | evaluation: [eval-baseline-pipes.md](https://github.com/ourostack/ouro-ui/blob/main/docs/decisions/2026-10-30-ouro-ax/evidence/eval-baseline-pipes.md) |
| `cli.error-teaches` | should | evaluation: [eval-baseline-pipes.md](https://github.com/ourostack/ouro-ui/blob/main/docs/decisions/2026-10-30-ouro-ax/evidence/eval-baseline-pipes.md) |
| `cli.no-stack-trace` | should | principle |
| `cli.plain-pipe` | should | hazard |
| `cli.check-verdict` | should | principle |
| `cli.outcome` | should | evaluation: [outcomes-probe.md](https://github.com/ourostack/ouro-ui/blob/main/docs/decisions/2026-10-30-ouro-ax/evidence/outcomes-probe.md) |
| `cli.wait-typed` | should | evaluation: [outcomes-results.md](https://github.com/ourostack/ouro-ui/blob/main/docs/decisions/2026-10-30-ouro-ax/evidence/outcomes-results.md) |
| `cli.work-events` | should | evaluation: [flow-probe.md](https://github.com/ourostack/ouro-ui/blob/main/docs/decisions/2026-10-30-ouro-ax/evidence/flow-probe.md) |
| `cli.voice-off-in-json` | should | principle |
| `cli.voice-off-when-piped` | should | principle |
| `cli.fact-before-voice` | should | principle |
| `cli.audience-named` | should | principle |
| `cli.text-refs` | should | principle |
| `cli.named-is-listed` | should | principle |
| `cli.help-size` | should | principle |
| `http.json` | should | principle |
| `http.error-shape` | should | principle |
| `http.error-teaches` | should | principle |
| `http.index` | should | principle |
| `http.unknown-route` | should | principle |
| `mcp.tools-list` | should | evaluation: [kit-probe.md](https://github.com/ourostack/ouro-ui/blob/main/docs/decisions/2026-10-30-ouro-ax/evidence/kit-probe.md) |
| `mcp.bad-call-teaches` | should | principle |
| `mcp.unknown-tool` | should | principle |
| `ui.read-fields` | should | principle |
| `cli.listening-cursor` | should | principle |