Reading ank check
ank check validates the corpus: every file parses and round-trips byte for
byte, every blocked_by and reference resolves, every frozen field still
matches its anchor, and every claim ref still means something. It is the verb
you put in CI, and the one to run before adding to a corpus, because it says what
is already known to be wrong.
It answers in two levels, and the difference is the whole of how to read it.
- A fault is something wrong with the corpus: a file that does not parse, a
frozen criterion edited under a live claim, a ratification whose anchor no
longer matches. Any fault makes
checkexit 8. - A signal is something a reader should see and is not a failure: a
decision ratified by its own author, a task finished on a branch that has not
merged, a scope that matches no file yet. Signals leave the exit code at
0, because reddening a build over an observation teaches a team to stop
reading
check.
A signal is owed, or it is only known (ADR-61c273118d97). It is owed when
its subject is unsettled work – an open or in-progress task, a proposed ADR or
spec, a task a live claim holds – or when it names the command that clears it;
a fault always is. By default check prints every fault and every owed signal,
then one line counting the signals that owe nothing. ank check --all prints
every finding, ank check --kind <kind> every finding of one kind, and
--json every finding with owed on each. The exit code is the same
whichever listing you ask for.
Exit 9 is neither: the environment, not the corpus – git too old, the default branch indeterminable. The full table is the exit-code reference.
Signals on a finished task, before and after the merge
The repository here is the one the quickstart ends with: one
ADR accepted by the person who wrote it, one task finished with ank done, and
nothing committed since.
$ ank check
signal: corpus: 5 entity file(s) differ from main: this checkout does not carry the corpus the default branch does (git merge main)
2 signal(s) owe nothing: settled work, and no command clears them (ank check --all lists them)
check: ok — 1 tasks, 1 adr, 1 signal(s)
No fault, so exit 0. One signal is owed, because it names the command that
clears it, and two more are only counted. --all prints them, each line
starting with its subject:
$ ank check --all
signal: TASK-820d259af6a7: finished on another branch, main has not caught up
signal: corpus: 5 entity file(s) differ from main: this checkout does not carry the corpus the default branch does (git merge main)
signal: signers: no ratification key declared: permissions are advisory, not enforced (§8)
check: ok — 1 tasks, 1 adr, 3 signal(s)
- Ratified by its own author, and declared allowed to. You wrote the ADR
and you ratified it.
ank initmapped you to thehumanrole, whosecan: ["*"]allowsadr:accept, so the corpus has already said you may andcheckstays quiet. Withpermissions.enforceoff, the same history reportsself-ratified, for a team that wants to know. - Finished on another branch.
status: donelives in the file, so on your branch alone until the merge. The claim ref became a completion record atdone, which is what tells every other tree the task is taken (Claims and identity). - No ratification key declared. Nobody has said whose signature makes a ratification binding, so the corpus says it runs on trust. Signing keys is how that line goes away.
- Entity files differ from main. The same fact as the second line, said about the corpus rather than one task: what your checkout carries that the default branch does not.
Commit, and the completion record is pruned:
$ git add -A && git commit -m "the migration is done"
$ ank check
signal: corpus: 3 hot entities are cold and belong in .ank/archive/entities/, with every entry about them (ank archive)
└── ank archive --dry-run lists them and moves nothing
1 signal(s) owe nothing: settled work, and no command clears them (ank check --all lists them)
pruned refs/ank/claims/TASK-820d259af6a7
check: ok — 1 tasks, 1 adr, 1 signal(s)
check writes, and that line is why. It is the only verb that prunes
refs/ank/claims: orphans, and completion records whose task is done or
closed on the default branch. Everything else it does is read-only, but a
verb that writes is not a verb to poll.
The new signal is the corpus noticing that three log entries are cold. An entry is cold with its subject, and their subject is a task that is done (ADR-467ce7e9cda1). The line under it is the command that answers it, and that command reads before it moves:
$ ank archive --dry-run
LOG-3b92d9719950 created (version 0 to 1, produced 4cc65f12691c)
LOG-6b0f39d7a4c1 jwt.verify removed from session.ts
LOG-f234f9b08f06 done, proof test:local/e3b0c44298fc@9c45c50
3 cold, nothing moved (--dry-run): ank archive moves them
It lists and moves nothing, which on a corpus this size is the right answer. When the move is worth making, it is a human’s decision landing by pull request: Ratifying and archiving.
A fault
A frozen field edited behind the tool is the fault a corpus is most likely to meet. Claim a task, then change its criterion in the file:
$ ank check; echo "exit $?"
error: TASK-51c2a0f6d418: done_criteria diverges from the claim (claimed 03c659e46adf, now ef485fff585a)
signal: TASK-51c2a0f6d418: content is 3eff92338baa where the last write left 2e29f326854e: it was edited outside the CLI, which is legal and leaves no entry
signal: corpus: 2 entity file(s) differ from main: this checkout does not carry the corpus the default branch does (git merge main)
signal: corpus: 3 hot entities are cold and belong in .ank/archive/entities/, with every entry about them (ank archive)
└── ank archive --dry-run lists them and moves nothing
1 signal(s) owe nothing: settled work, and no command clears them (ank check --all lists them)
check: 1 fault(s) — 2 tasks, 1 adr, 3 signal(s)
exit 8
A fault prints as error:, first, and the summary line counts it. The signal
on the task is the same edit seen from the other side: its content no
longer hashes to what the last verb wrote, which alone would be legal. Nothing
refused the edit, and nothing could: the file is yours. What the edit cannot do
is make the hash recorded in the claim agree with it. The two criterion hashes
are content, so they are the same on your machine: 03c659e46adf is the
criterion as written, ef485fff585a as edited. done refuses and check exits
8 until the criterion is put back or the task is handed back with ank release --reason, which ends the freeze and leaves only the signal. Freezing is
verifiable, not defended.
A scope ahead of the code
A plan often decides before it codes, so a decision may name a file nobody has written yet. Whether that is a signal or a fault depends on whether some task still promises the file.
- A task’s scope that matches no file is a signal while the task is open:
the work has not started. It becomes a fault once the task is
done, because a finished task claimed to touch files that are not there. Aclosedtask promised nothing, so its dead scope stays a signal. - An ADR’s or a spec’s scope that matches no file, on a path no commit ever
carried, is a
scope-not-yetsignal while an open task covers it: the task declares the same entry, or a glob that matches it, assrc/**matchessrc/new.rs. The signal names that task. Once no open task covers it, it is adead-scopefault, and the message names the last task that covered it and how it ended:donemeans the promise was not kept,closedmeans it was withdrawn. With no task covering it at all, it is the fault it always was. The decision is ADR-91f486072d68.
A covering task lowers nothing else. A scope git records as renamed or deleted, or one whose history is too shallow to say, is reported as ADR-3094538d831e says, whatever task covers it. Once the file is committed the scope matches, and there is no finding at all.
An act a role forbids
With permissions.enforce at warn or deny, each recorded act whose actor’s
role forbids it is a signal of kind role, on the entity acted on: a birth, by
its author; an accept, by the identity its ratification tag names; a close; a
constraint edit. The line names the actor, the act and the entry of
.ank/config.yml that forbids it, the entry the verb printed on stderr when it
performed the act. A write to config.yml leaves no record in the corpus, so
that warning is all there is of it. ank check --kind role lists them, and with
permissions.enforce off roles apply to nothing and check reports none.
What check reads beyond the files
check reads refs/ank/* and walks git history. It finds the ratification
that anchors each accepted decision at refs/ank/ratify/<id>, or, for one
ratified before ADR-5e47007a75be, as the commit whose subject is ratify <id>,
and it asks where a scope that matches nothing went, a rename or a deletion. A
checkout that lacks either does not make check fail: it makes it report the
decisions anchored there unverifiable, at exit 0, which is why a pipeline has to
fetch the refs and the whole history (Running ank in CI).
ank check <path> narrows the report to the entities whose scope covers that
path. --json carries every finding with its level, subject and message, and
it is what a script reads; the machine surface shows the
document.