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. DoneMark 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.

What waits for you

What waits for you — the list behind the count at the top of every page: what is stuck, what is ready to judge, and the choices to make, worst first, each with its one action. See What waits for you, and your hats.

Hat — the part of the work you look after: Asker, Driver, Judge, Keeper or Owner. Its rows, where it has any, come first in what waits for you. A hat changes what you see first, never what you may do; that is still your role and your judge seats.

The work

Project — one piece of software and its repository. DoneMark 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 DoneMark was sealed.
failed	Refused. The reason is on the record.
withdrawn	Taken off the board. Sealed records stay as they are.

On the screens, the acceptance criteria are the lines of done when. DoneMark can draft them from one sentence of yours; a drafted line says so until a person changes or approves it.

Seen by — how each line will be witnessed: a check (an automated test), a picture (a screenshot a person looks at), a journey (a path through the running app) or a record entry.

Brief — what the whole project is for, in five short parts, written by its administrators and handed to every attempt under the requirement's own lines. See The brief and the decisions.

Decision — one rule the project has settled, told to every attempt from then on. Made on About this project, or from a judge's reason in one press.

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 DoneMark 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 DoneMark 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 four squares — the ladder, asked as four questions of each line's check: failed before, passes now, runs new code, caught a mistake. A dashed square is not measured, and never reads as green. See Reading a verdict.

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

Verdict — Sign off (accept) or Not quite (refuse), by a named person, with a reason. DoneMark drafts the reason from what it observed; it never decides for you.

DoneMark — 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 DoneMark 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. DoneMark watches for the merge and for the app answering at that commit; live is observed, not assumed.

Release — a set of asks built together on one branch, tested once by CI, judged one by one and put live in one merge. See Releases, from plan to live.

The machinery

The witness — a read-only GitHub App, still named Constat on GitHub. 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 DoneMark to read. DoneMark never runs your tests; it reads the report of a run that already happened.

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

Running copy — the preview your own host (Vercel) builds from an attempt's commit, which DoneMark links on the run page. DoneMark never hosts your app.

Journey — a person's path through the running copy, walked by your CI and photographed step by step. See Seeing it running.

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 DoneMark uses on its screens has one meaning, and it is written on this page. The way back returns you to where you were.