Reticle Docs: verification for AI coding agents

reticle_assert evaluates a predicate against what the app actually did and returns a verdict: verified plus pass, evidence when it holds, and expected versus observed when it does not. Reach for it when you want a verdict on something you did not just cause, or on several actions at once. Verdicts come from reticle_act_and_wait, reticle_assert, reticle_act { steps } when a step declares expect, and reticle_verify (change/flows). Everything else moves or reads the app and proves nothing. Only verified: "yes" is a pass: unknown means Reticle could not tell, and no-fault means nothing was declared to prove. reticle_assert takes the same predicate grammar as until and evaluates it against what already happened.

A real failure

Failures teach more than passes. This assert claims that signing in lands on /dashboard, after a click that did not navigate. The page was still on /login:

{ "predicate": { "kind": "route", "pathname": "/dashboard" } }

{
  "verified": "no",
  "verifiedReason": "assertion_failed",
  "because": "the declared consequence did not hold",
  "pass": false,
  "failureReason": "current route (no route change in the window) '/login', expected '/dashboard'",
  "observed": "current route (no route change in the window) '/login'",
  "expected": "route '/dashboard'",
  "assertion": "route.pathname",
  "source": "src/components/Login.tsx:81",
  "buffer": {
    "held": 536,
    "dropped": 11,
    "note": "event buffer evicted older events (age/size cap): a negative result here may be a false negative; the evidence may have expired. Grade sooner or widen the buffer."
  }
}

The route predicate’s field is pathname. path is accepted as an alias and rewritten, but pathname is what the published schema declares, so it is the one to write.

A route predicate is decided by the last route change in the window. When there was none, it reads the session’s current URL instead, and observed says so (“current route (no route change in the window)”). So asserting the route you are already on passes; on its own it does not prove that anything navigated. Check evidence.decidedBy on a pass to see which of the two decided it.

Note also expected and observed side by side. A verdict that says only “failed” makes you go digging; this one tells you what it wanted, what it saw, and where in your source the relevant element lives.

A failure that names the real value

The same shape on a store read, which is the strongest kind of failure you can get, because it quotes the app’s own data back at you:

{
  "predicate": { "kind": "state", "store": "app", "path": "deployments.0.status", "equals": "live" }
}

{
  "verified": "no",
  "verifiedReason": "assertion_failed",
  "because": "the declared consequence did not hold",
  "pass": false,
  "failureReason": "state 'deployments.0.status' is \"queued\", expected \"live\"",
  "observed": "deployments.0.status = \"queued\"",
  "expected": "deployments.0.status = \"live\"",
  "assertion": "state.equals",
  "evidence": { "store": "app", "path": "deployments.0.status", "value": "queued" },
  "source": "src/components/Login.tsx:81"
}

A pass can still come with a warning

A presence-only predicate passes and tells you not to trust it much:

{
  "verified": "yes",
  "pass": true,
  "evidence": [
    {
      "ref": "e606",
      "role": "alert",
      "name": "Invalid email or password",
      "visible": true,
      "source": "src/components/Login.tsx:72",
      "states": ["present", "visible", "enabled"]
    }
  ],
  "advice": "This predicate only checks element/text presence, not an observable consequence. A locator healed to the wrong element (or a stale render) can satisfy it while the feature is broken. Prefer a { signal } or { net } assertion (or allOf it with one) so green means the feature actually worked."
}

Arguments

Argument	What it does
`action`	`now` (the default) evaluates against the window that already exists; `wait` waits for it to hold
`predicate` (or `until`)	`{ kind, ...fields }`. See the predicate reference
`timeout_ms`	`now`: if above zero, wait this long before failing (default `0`, capped at `55000`). `wait`: default `4000`, up to `600000`, resumed with `resume_ms` past one call’s limit
`since`	Cursor from a prior act. Scope to events after that action

Scope it with `since`

By default an assertion already counts only events since your last act, so a signal buffered before the action cannot fake a pass. Pass since when you want to set that window explicitly: to scope to one particular earlier action, or to widen it deliberately across several.

{ "predicate": { "kind": "net", "method": "POST" }, "since": 44395 }

The cursor comes from the preceding reticle_act response. Use it whenever you are asserting something an action was supposed to cause.

When to use assert over act_and_wait

Use reticle_act_and_wait when you are performing the action. Use reticle_assert when:

you are checking a precondition before acting;
the state was reached by several actions and you want one verdict over the lot;
you want to assert something extra about an action you already ran, using its since cursor.

verified: "unknown" means Reticle could not tell. It is not a pass, and it is not a failure, it is a statement that the evidence was insufficient. Report it as unknown rather than rounding it in either direction.

Tools

Beyond the loop

CLI commands

Packages

Grammar

Long form

reticle_assert

A real failure

A failure that names the real value

A pass can still come with a warning

Arguments

Scope it with `since`

When to use assert over act_and_wait

​A real failure

​A failure that names the real value

​A pass can still come with a warning

​Arguments

​Scope it with since

​When to use assert over act_and_wait

A real failure

A failure that names the real value

A pass can still come with a warning

Arguments

Scope it with `since`

When to use assert over act_and_wait