Brainlyy

Claims

Declaring a claim, where checks live, the three computed states, and what counts as checkable.

A claim is something your notes assert that a machine can go and check.

The rule

The evaluator owns the status. The note never does.

A note declares a claim and the evidence it rests on. It does not get to say how it is doing. If you write status: VERIFIED in frontmatter it is ignored, and the note is flagged as having tried to certify itself.

That rule exists because of a bug in this project. Until recently the dashboard decided a note was VERIFIED by checking whether the text contained the word "VERIFIED", and rendered a green badge for it. Nothing verified anything, in the one tool whose whole premise is catching claims that carry no check.

Declaring one

---
claim: KYC is complete for onboarding path B
evidence: [kyc_mode, sanctions_clear, approver_recorded]
recheck: 1d
---

evidence holds names, never commands, URLs or paths. A note is untrusted, because your assistant writes notes, so a name can only ever resolve to something you put in config yourself.

The checks live in config

checks:
  kyc_mode:
    kind: http
    url: http://127.0.0.1:9000/health/kyc
    contains: fail_closed
  approver_recorded:
    kind: file
    path: ~/.brainlyy/records/approvals.json
    contains: approved_by
  disk_encrypted:
    kind: cmd
    argv: [manage-bde, -status]
    contains: "Fully Encrypted"
Kind Passes when
file the path exists, and contains the string if contains is set
http the response is under 400, and contains the string if set
cmd the command exits 0, and its output contains the string if set

cmd takes an argv list, never a string, and never runs through a shell.

The three states

State Means
VERIFIED every check passed, within the recheck window
UNVERIFIED the claim is checkable, and something failed, is missing, or expired
ASSERTED nothing here is machine-checkable, so no check will ever run

ASSERTED is not a failure. Most of what a knowledge base holds is legitimately in it: judgements, decisions, context, things that are true but not mechanically testable. Pretending otherwise is how you get a system that lies more confidently than the notes did.

What is checkable

All three must hold:

  1. the subject resolves to an artifact: a file, an endpoint, a record, a command's output
  2. the predicate is true or false without judgement
  3. it is falsifiable now, not eventually

"The sanctions screen returned clear on this account" qualifies. "Our approach to onboarding is sound" does not, and never will. Declare the second one anyway. It just stays ASSERTED.

Running it

brainlyy verify              # re-check everything, record what was observed
brainlyy verify --strict     # exit 1 if anything is unverified, for CI

Every run appends to $BRAINLYY_HOME/evidence/<year>-<month>.jsonl. Nothing is ever rewritten, so you can reconstruct what evidence supported a claim on a given date.

The number that matters

brainlyy verify reports how long the longest-lived false claim read VERIFIED before a run caught it.

That is the point of the whole thing. In the deployment this was extracted from, a knowledge base asserted a false regulatory status and fed it into daily reports for thirteen days. No check failed, because there was no check.

Creating a claim from the dashboard

The dashboard can do everything the frontmatter workflow does: declare a claim, pick its evidence from the checks config already defines, set a recheck window, and add new file and http checks to the allowlist, with a test-before-saving step, so a typo'd check fails in front of you rather than silently in the next verify run.

One thing is missing from that list on purpose: cmd checks cannot be created, or even test-run, from the dashboard. The API refuses kind: cmd outright, at every layer, with a 400.

The reason is the boundary this whole feature sits on. Config is the only place allowed to define something executable, and the dashboard is a network-reachable surface that writes config. If it could write a cmd entry, anyone who could reach the page could line up an arbitrary command and wait for the next verify to run it, and the guarantee "a browser cannot cause execution" would then rest entirely on the loopback gate never being relaxed or misjudged. Refusing cmd in the API keeps that guarantee structural rather than situational.

Adding a cmd check therefore stays what it should be: a hand edit to config.yaml, made on purpose, by someone who already controls the machine.

Honest caveats

  • A claim is only as good as its check. file exists proves a file exists, not that its contents mean what you think.
  • Nothing here detects a claim that has become false when no check covers it. That is the harder problem and it is not built yet.
  • recheck is a promise about freshness, not a scheduler. Run brainlyy verify on a timer, or the window just expires and everything reads UNVERIFIED.
PreviousHow it worksNextCLI reference