Reticle Docs: verification for AI coding agents

reticle_act_and_wait performs one action on an element and waits for a named consequence, returning a verdict in the same call. Reach for it whenever an action is supposed to cause something: it produces a verdict. 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. This is the tool Reticle exists for. It does the act, observe and assert steps in one round trip, and it makes you name the expected consequence before the action runs. That ordering is not a convenience. An agent that acts first and then decides what counts as success will always find something that counts. Naming the consequence up front is the difference between a check and a rationalisation.

Example

{
  "ref": "e105",
  "action": "click",
  "until": { "kind": "net", "method": "POST" }
}

Real response. The initiatorStack, storageDiffs and per-event trace detail are trimmed out for length; nothing else is changed:

{
  "verified": "yes",
  "verifiedReason": "proved",
  "because": "assertion held at presence grade over a clean capture with no channel disagreeing",
  "effect": {
    "ok": true,
    "ref": "e105",
    "action": "click",
    "dispatched": true,
    "settled": true,
    "settleReason": null,
    "testid": "login-submit",
    "component": "Login",
    "role": "button",
    "name": "Sign in",
    "effect": { "focusMoved": "e104->null", "domMutatedWithin": 8, "appeared": "Signing in…" },
    "source": { "file": "src/components/Login.tsx", "line": 81, "column": 8 }
  },
  "verdict": {
    "pass": true,
    "evidence": {
      "id": "n2",
      "method": "POST",
      "url": "http://localhost:8787/api/login",
      "status": 200,
      "ok": true,
      "durationMs": 4,
      "initiator": "fetch",
      "statusText": "OK",
      "contentType": "application/json; charset=utf-8",
      "responseSize": 67,
      "requestBody": "{\"email\":\"admin@reticle.dev\",\"password\":\"[REDACTED]\"}",
      "responseBody": "{\"token\":\"[REDACTED]\",\"user\":{\"email\":\"admin@reticle.dev\"}}"
    }
  },
  "trace": {
    "window_ms": 31,
    "summary": {
      "total": 21,
      "network": 1,
      "domAdded": 0,
      "domRemoved": 1,
      "domChanged": 6,
      "routeChanges": 0,
      "consoleErrors": 0,
      "animations": 0,
      "signals": 1
    }
  },
  "summary": {
    "net": { "total": 1, "errors": 0 },
    "consoleErrors": 0,
    "statePathsChanged": ["app"],
    "storageKeysChanged": ["reticle.bench.authToken", "reticle.bench.sessionId"],
    "stateDiffs": [
      { "path": "auth", "from": null, "to": "{\"email\":\"admin@reticle.dev\"}", "atMs": 44403 }
    ],
    "signals": ["auth:granted"],
    "layoutShift": 0.016486682891845704,
    "longTasks": 0
  },
  "honesty": {
    "grade": "presence",
    "attribution": "window",
    "coverage": { "pct": 100, "partial": false },
    "integrity": { "clean": true, "issues": [] }
  },
  "engineBlindSpots": [],
  "since": 44395
}

trace is a digest of what the app did in the window. When the counts are not enough, pass the top-level since cursor to reticle_observe for the per-event timeline. engineBlindSpots lists what Reticle could not see in this session: pixels-unobserved once an action ran with a <canvas> on screen, and claim-arithmetic-unchecked while a claim states an amount and no compare ran. Do not call a run clean while it holds an entry.

The predicate grammar

until takes { kind, ...fields }. The kinds:

Kind	Asserts
`signal`	The app fired a signal, the strongest evidence available. With no `name`, only the app’s own signals count, not Reticle’s `reticle:` signals. `count` is exact
`state`	A store path reached a value
`net`	A request matched. `count` is exact, `count: 0` means it never fired, and no `count` means at least one
`route`	The route changed
`element`	An element appeared; `absent: true` asserts it went away
`text`	Text appeared or, with `absent`, disappeared
`console`	Something logged; `absent: true` asserts a clean console
`animation`	An animation ran or finished
`settled`	The page went quiet
`compare`	Two readings agree
`allOf` / `anyOf` / `not`	Combine the above

Predicates that catch real bugs

{ "until": { "kind": "net", "method": "POST", "count": 1 } }

Exactly one request. Double-submit fails this at two, and no screenshot will ever tell you.

{ "until": { "kind": "console", "absent": true } }

The action completed and logged nothing. “It worked but threw a warning” stops passing.

{ "until": { "kind": "signal", "name": "deploy:created" } }

The app itself declared success. This is the highest grade of evidence, and it requires instrumenting your app. Which is the main reason to bother.

Reading `verified`

yes

The named consequence happened, with evidence attached.

no

It did not. A finding, with a source pointer.

unknown

Reticle could not tell. Not a pass. Report it as unknown.

no-fault

The page settled with nothing wrong, but nothing was declared to prove. Not a pass. Add an until the action changes.

The `honesty` block

grade is how strong the evidence was. A fired signal outranks an element appearing. coverage.partial: true means Reticle did not observe the whole window. integrity.clean: false means something interfered with the capture and the verdict deserves less trust. A verification tool that cannot describe the quality of its own evidence is asking you to take its word for it, which is precisely the problem we started with.

Arguments

Argument	What it does
`ref`, `action`, `args`	As `reticle_act`
`target`	Find the element and act in one call, instead of a `ref`: `{ testid }`, `{ text }`, `{ role, name }` or `{ label }`. Refuses if it matches more than one
`until`	The predicate to wait for. Omit it to wait for the page to settle
`predicate`	Alias for `until`, the name `assert` and `wait_for` use
`timeout_ms`	Maximum wait, defaulting to 4000. `0` evaluates the predicate once, no wait
`refuseWhenThrottled`	Throw rather than act on a throttled tab
`intent`	What the change is supposed to make true, in prose, or the id of an intent declared earlier. Recorded on the verdict
`detail`	`"compact"` keeps only the deciding fields. Omit it for the full result
`durable`	After a `yes`, reload the page and require the element, text and state parts of `until` to hold again. A consequence that is gone after the reload turns the verdict into `no`: the UI advanced, the change did not persist

Omitting until waits for network and DOM idle, which is the deterministic replacement for a fixed sleep. To assert a consequence and settle, combine them:

{
  "kind": "allOf",
  "predicates": [{ "kind": "signal", "name": "deploy:created" }, { "kind": "settled" }]
}

Tools

Beyond the loop

CLI commands

Packages

Grammar

Long form

reticle_act_and_wait

Example

The predicate grammar

Predicates that catch real bugs

Reading `verified`

yes

no

unknown

no-fault

The `honesty` block

Arguments

​Example

​The predicate grammar

​Predicates that catch real bugs

​Reading verified

yes

no

unknown

no-fault

​The honesty block

​Arguments

Example

The predicate grammar

Predicates that catch real bugs

Reading `verified`

The `honesty` block

Arguments