An agent worked on this branch overnight and everything says done. Is any of it checked?
You share a repository with something that writes faster than you read. It opened files, made decisions, marked things done, and left you a summary that is accurate about what it did and silent about what it assumed.
The missing piece is not more prose. It is a place where a status is stored as a claim, an assumption is stored as a question that stops the work, and a check is stored as a fact with a way to re-run it — reachable from your shell and from the agent's tools, as the same objects.
Every step is one move, on three surfaces: the shell, a chat client over MCP, and the browser consolevrek-api serves. Pick whichever you would actually touch — the choice holds for the rest of the track.
Where a surface genuinely cannot do a step, it says so rather than pretending.
01
Ask the graph what to pick up
Not the backlog, and not the repository's prose. ready is the work nothing is currently blocking, and it prints the paths each item touches. That footprint is what a ticket never tells you: two ready items over the same file is a collision you can see before you make it rather than at merge.
On the command line
what is actually available
$ vrek ready○ iss-3qhhg79 register writes an absolute VREK_DIR into .mcp.jsontouches src/cli/main.ts, test/cli.setup.test.ts○ iss-jpkfjf6 Relation lists come back sorted by target idtouches src/core/workspace.ts
In Claude, or any client that speaks MCP
the same question, in the window you were already invrek over MCP
you
What is ready on this repo that nobody is in the middle of?
62 are ready; those are the first two. I will take iss-jpkfjf6 — it touches src/core/workspace.ts and nothing else in the ready set does, so it will not collide with whatever you pick.
In the console
the first thing the console showsvrek-api
vrek console#/live
Ready to pick up
8 of 62
○register writes an absolute VREK_DIR into .mcp.jsonsrc/cli/main.ts · test/cli.setup.test.ts
○Relation lists come back sorted by target idsrc/core/workspace.ts · area:surfaces · type:bug
see all 62
02
Take it where the other writer can see
You are not the only one with a shell on this workspace. in_progress lands in the same log the agent reads on its next ready, so it stops being something you mentioned in a chat window. Name yourself once and every event you append carries you.
On the command line
claiming it, attributably
# saved to .vrek/.actor; you are asked once, not per command$ vrek whoami mike$ vrek status iss-jpkfjf6 in_progress# who touched this, in order, with nothing anonymous$ vrek log --subject iss-jpkfjf6 --order oldest
In Claude, or any client that speaks MCP
the agent cannot write as youvrek over MCP
you
Take it, and show me everyone who has touched it.
⌁vrek_set_statustool call
id: "iss-jpkfjf6"
status: "in_progress"
{ "id": "iss-jpkfjf6", "status": "in_progress" }
⌁vrek_historytool call
subject: "iss-jpkfjf6"
order: "oldest"
issue.created mike 2026-09-02
node.tagged mike 2026-09-02 area:surfaces, type:bug
status.changed claude 2026-09-17 open → in_progress
claude
In progress, and recorded as claude — the MCP server sets the actor on connect, so nothing I append is attributed to you. You opened and tagged it; the change of status is mine.
In the console
Not this surface
The console sets the status on the node's own page: the status pill is a picker of the kind's statuses, and the change is recorded under the name the console writes as — a person on a loopback server, or whoever the token or the tailnet says. It offers only what a person sets directly; answered, deferred and a check's result come from answering, deferring and resolving, which carry what those need.
03
When you would guess, ask instead
The expensive mistake is rarely the wrong answer. It is the quiet one — a lane picked at 2am, discovered in review three days later, by which time it is load-bearing. --blocks takes the work out of the ready set until a human answers, so neither you nor your agent can proceed on a guess without noticing that is what you are doing.
On the command line
a question is an object, not a message
$ vrek ask "Sort relation lists by what?" \$ --option "created_at|reads as the order things happened" \$ --option "title|stable, but unrelated to the work" \$ --blocks iss-jpkfjf6 --owner mike# and it is gone from ready until somebody answers$ vrek ready
In Claude, or any client that speaks MCP
the step that makes an agent stoppablevrek over MCP
claude
Nothing in the workspace records what order relation lists should come back in, so any order I pick is a guess that becomes load-bearing. Asking instead.
⌁vrek_asktool call
question: "Sort relation lists by what?"
options: [{ option: "created_at", consequence: "reads as the order things happened" },
{ option: "title", consequence: "stable, but unrelated to the work" }]
blocks: ["iss-jpkfjf6"]
owner: "mike"
que-8k3m1qp is on your desk and iss-jpkfjf6 has left the ready set until it is answered. I will pick up something else rather than sit here or invent an answer.
In the console
Not this surface
Asking is usually done by whoever was about to guess, which is an agent mid-task; but a person can raise one too, from the Browse page's questions tab, with the options and what changes under each. Either way the console is where it lands: it is in Waiting on a human on the Overview the moment it exists, and it is answered there, which releases the work it blocks.
04
Record done as the claim it is
status done records that somebody said so. It does not pretend to know. Until evidence is attached, the item sits in unverified, which is exactly the list of everything currently being taken on trust — usually shorter than you would like, and always shorter than the summary suggested.
On the command line
a claim, stored as a claim
$ vrek status iss-jpkfjf6 done$ vrek unverified● iss-jpkfjf6 Relation lists come back sorted by target idclaimed done by mike, no evidence
In Claude, or any client that speaks MCP
what an agent's "done" is worth, exactlyvrek over MCP
you
Is it finished?
⌁vrek_set_statustool call
id: "iss-jpkfjf6"
status: "done"
{ "id": "iss-jpkfjf6", "status": "done" }
⌁vrek_unverifiedtool call
{ "items": [
{ "id": "iss-jpkfjf6", "title": "Relation lists come back sorted by target id",
"status": "done", "updated_by": "prn-90pbht2" }
], "total": 2 }
claude
I have recorded that I say so. That is all done is here, and vrek_unverified lists it as such — mine included — until a check is attached to it.
In the console
the panel worth reading firstvrek-api
vrek console#/live
Claimed without evidence
2 of 2
●Relation lists come back sorted by target iddone by mike · no verification
●The console's node page has no section for what a node blocksdone by claude · pending: a node's page shows a 'Holds up' section
05
Attach the fact behind it
A verification says who checked it, when, and how someone else would check it again. pending is the honest result for a test that is written but has never been run — never pass. Resolve it afterwards: correcting a result appends a new event naming who corrected it, and the original stays in the log.
On the command line
evidence, and how to re-check it
$ vrek verify iss-jpkfjf6 "relations come back in created order" \$ --result pass --evidence "npm test, 916 tests; workspace.test.ts"# written but never executed is pending, and pending is honest$ vrek verify iss-jpkfjf6 "the console renders them in that order" \$ --result pending
In Claude, or any client that speaks MCP
an agent recording what it did not checkvrek over MCP
⌁vrek_verifytool call
issue: "iss-jpkfjf6"
criterion: "relations come back in created order"
result: "pass"
evidence: "npm test, 916 tests; workspace.test.ts"
{ "id": "ver-2k7p1rc", "result": "pass" }
⌁vrek_verifytool call
issue: "iss-jpkfjf6"
criterion: "the console renders them in that order"
result: "pending"
{ "id": "ver-9d3xq0m", "result": "pending" }
claude
The first I ran. The second I wrote and never opened a browser to see, so it is pending — the result that exists precisely so an agent does not have to round a guess up to pass. Somebody with a browser can resolve it.
In the console
the somebody with a browservrek-api
vrek console#/node/iss-jpkfjf6live
Claim and evidence, kept apart
✓relations come back in created orderpass · mike · npm test, 916 tests; workspace.test.ts
…the console renders them in that orderpending · claude · never run in a browser
Record the outcome
06
Hand your agent the same loop
register writes the .mcp.json that connects an agent over stdio. It gets the ready set, the ask and the verify as tools — the same objects you just used, not a summary of them. What it is told on connect is instructions, which lives in the workspace, so it is one fact for every agent rather than a file each repository drifts on its own.
On the command line
the agent joins the same workspace
$ vrek register --model claude-opus-5wrote .mcp.json — vrek-mcp over stdio, actor claude, kind agent$ vrek instructions "Start with ready. Ask rather than guess. Verify before you claim."
In Claude, or any client that speaks MCP
where the agent's instructions come fromvrek over MCP
you
Who told you to start with ready?
claude
The server did, on connect. It sends the workspace's instructions with its tool list, so it is one fact every agent on this workspace is given rather than a paragraph each repository keeps its own copy of. You can change it from here and it applies to all of us.
⌁vrek_set_instructionstool call
instructions: "Start with ready. Ask rather than guess. Verify before you claim."
{ "instructions": "Start with ready. Ask rather than guess. Verify…" }
In the console
Not this surface
Connecting an agent is a file in your checkout, so it is a shell command. The console's side of it is that you can then see what the agent did without asking it: Activity is every event as it lands, each one naming the principal and, for an agent, the session it was in.
← → to move
Nothing here is edited
A correction is a new event. You can be wrong in this system without losing the record of having been wrong, which is the property that makes it worth reading back six months later.
Deferred is not blocked
vrek defer <id> --until 2027-01-01 --because dec-dn35d6q says you chose to put it down. blocked asserts something is in the way, which is a different fact and would be a false one.