Concepts and terminology

In the order you meet them.

The room

Organization — the room a product gets built and judged in. It holds the projects, the people and the record. Constat asks you to make one before anything else, and tells you plainly that being alone in it is fine.

Seats. Four, and a person can hold more than one.

Seat	What it means
Author	Writes the asks.
Judge	Signs the verdicts. Named per project, not per organization.
Reader	Reads the sealed records. A client, a manager, an investor.
Agents	Build, on your CI, with your key. Not people.

Roles, which are the permissions behind the seats: admin, author, reader. Being a judge is separate and is granted per project, because the person who may judge the mobile app is not always the person who may judge the billing service.

The work

Project — one piece of software and its repository. Constat reads the repository and its CI; it never writes to either, except one check run and one comment when you turn that on.

Requirement — one ask, in your own words, with acceptance criteria: the rules it will be judged by. When you approve it, the words freeze. Agents and evidence refer to the frozen words, so nobody can move the target after the fact.

A requirement is in exactly one state:

State	Meaning
draft	Written, not yet frozen.
approved	Frozen. Ready to be built.
building	An attempt is running.
implemented	The attempt finished; evidence is still arriving.
validating	The door is open. It is waiting on a person.
verified	Accepted. A Constat was sealed.
failed	Refused. The reason is on the record.
withdrawn	Taken off the board. Sealed records stay as they are.

Envelope — what an attempt runs under, frozen with the words at approval: how much it may spend, how long it may run, which files it may touch, and what evidence it is expected to produce.

The attempt

Attempt (also run) — one go at a requirement. It is built by an agent your CI runs, or it arrives on its own when somebody opens a pull request that names the requirement. Either way Constat did not build it.

An attempt is queued, running, completed, failed, or halted — halted meaning it hit a cap, or the runner never reported back.

Lane — one of a project's places for an attempt to run in. A project with three lanes may have three attempts in flight at once, on three different requirements; two attempts on the same requirement still wait for each other. The record says which lane an attempt ran in, so two that overlapped in time can be seen to have been meant to.

Claims — the agent's own account of what it did, kept as claims and never as evidence: tests_pass, implemented, files_changed, criteria_met, infeasible, other. An honest infeasible is a complete, acceptable report.

Evidence — what Constat observed for itself, each piece with its source:

Kind	What it is
ci_run	A run of your CI, and what it concluded.
criterion_check	What CI said about the check a criterion named.
diff_stat	What the change actually touched.
artifact	What CI published — the report, the pictures.
screenshot	A picture of a screen at the moment a check passed.
preview	A running copy of the attempt, for you to try.
scope_violation	A change outside the files the envelope allowed.
method_substitution	The attempt used a different method than the ask named.
build	A build, where the project has one.
manual_review	A person's own look, recorded as such.

The judgement

The ladder — for each criterion, how far the evidence actually goes: whether a check was named, whether it ran, whether it was ever seen failing before the code existed, whether it touches the lines that changed, whether it notices when they break. A criterion that passed without ever having been seen to fail reads as passed, but unproven, which is a different and weaker fact.

The door — the moment a requirement is waiting on a person. Constat opens it only when the attempt's own evidence has settled, and tells the judges.

Verdict — accept or refuse, by a named person, with a reason. Constat drafts the reason from what it observed; it never writes the word accept or refuse for you.

Constat — the sealed record, numbered. It says who accepted it, and that they are a person outside the harness that built the work. Where the author and the judge are the same person, it says that too, so a reader can weigh it.

A number is given when a person accepts, and never otherwise. A refusal is recorded just as fully — its reason, the evidence it was issued on, the attempt it judged — and carries no number, stands in no list of sealed work, and offers no release. So a Constat number always means the one thing: somebody accepted.

After the verdict

Release — how an accepted requirement reaches the world: queued, taken, waiting_for_person, merged, live, or refused. Constat watches for the merge and for the app answering at that commit; live is observed, not assumed.

The machinery

The witness — a read-only GitHub App. It reads contents, checks, runs, artifacts and secret names, never a secret's value, and it cannot write a file, push a commit or move a branch. It gains write on two things only when you allow it: its own check run, and its own comment.

The reporter — what your CI publishes for Constat to read. Constat never runs your tests; it reads the report of a run that already happened.

The runner — the small workflow in your repository that asks Constat whether there is work, and runs the agent when there is, with your key, on your CI.

The standing wake — a runner on a machine of your own, asking every thirty seconds, so there is no button to press.

What do these words mean?

Every word Constat uses on its screens has one meaning, and it is written on this page. The way back returns you to where you were.