Install
Two separate acts: the binary, which is the tool, and the skills, which teach an agent how to use it. Installing one leaves the other where it was, unless you ask the binary to place the skills.
The short version is two lines:
npm install -g @haksolot/ank # the binary for your platform
npx skills add haksolot/ank # the skills, for your agent
Everything below is for the cases those two do not fit.
What you need
- git 2.34 or newer. Claims live in git refs, and Ank checks the version at startup.
sh. Verifiers run undersh -con all three operating systems. On Windows it comes with Git for Windows, so requiring git makes it free.- Rust 1.95 or newer, only if you build from source.
The binary
Three routes install ank, and only three: each is a command served from this repository and derived from a published release, and none of them owes anything to a registry with a gatekeeper of its own.
npm, on any machine that has node, and the one to reach for behind a firewall that blocks downloading a bare executable but lets a registry through:
npx @haksolot/ank --version
npm install -g @haksolot/ank
The binary is inside the package: one package per platform, installed through
optionalDependencies, with no postinstall step fetching anything. A
postinstall download would die behind the very firewall this channel exists
to cross, after the install looked like it had worked.
It covers linux x64, linux arm64, darwin arm64 and win32 x64. On
anything else, an Intel Mac for one, the wrapper exits 9 and names cargo install.
curl | sh, on Linux and macOS:
curl -fsSL https://raw.githubusercontent.com/haksolot/ank/main/install.sh | sh
It reads your platform from uname, fetches the archive and the .sha256
published beside it, and refuses before unpacking if the two disagree. On a
platform no release carries, it refuses by name and lists the platforms that
exist.
A PowerShell one-liner, on Windows, the same shape as the line above it:
irm https://raw.githubusercontent.com/haksolot/ank/main/install.ps1 | iex
It verifies the .sha256 the same way, runs under Windows PowerShell 5.1 as
well as PowerShell 7, and moves a running ank.exe aside before writing the new
one, so an upgrade works from a shell that already has ank on its PATH.
Where an archive came from. The .sha256 beside an archive catches a
truncated or corrupted download, and whoever could replace the archive on the
release page could replace its hash too. So every archive of a release after
0.9.4 also carries a build provenance attestation, which GitHub signs for the
release.yml run that built the file. Check one by hand with
gh:
gh release download v<version> --repo haksolot/ank --pattern 'ank-*-x86_64-unknown-linux-musl.tar.gz'
gh attestation verify ank-<version>-x86_64-unknown-linux-musl.tar.gz \
--repo haksolot/ank --signer-workflow haksolot/ank/.github/workflows/release.yml
When a signed-in gh is on PATH, both installers run that check before
unpacking and refuse an archive that fails it, with exit 4. Each says in one
line which check it made: verified: sha256 and provenance, or verified: sha256 only followed by the reason. To refuse any install the check cannot be
made for, pass --require-provenance to install.sh or -RequireProvenance to
install.ps1, or set ANK_REQUIRE_PROVENANCE for either: it exits 5 without a
signed-in gh, and 4 for a release from before the attestations.
Two fallbacks remain when none of the three fits, and this project supports
neither as a route. The releases
page carries the archives the
installers fetch, one per target with a .sha256 beside it; unpacking one by
hand is what those installers do for you. And the tree builds:
cargo install --git https://github.com/haksolot/ank ank-cli
--git because nothing publishes to crates.io. That puts ank in
~/.cargo/bin, and needs Rust 1.95 or newer and a C compiler.
No package manager ships ank. Homebrew, Scoop, apt, winget and the AUR each carried a channel here or an attempt at one, and each was withdrawn; adding one back means replacing the decision that withdrew them.
Whichever you took, check it answers:
$ ank --version
ank 0.8.0 (8310e75, skill 0d916cc3d9a5)
Three components: the version, the commit it was built from, and the revision
of the skill it was built alongside. The commit tells you whether your binary
predates the behaviour you are reading about. The revision is the value skill/SKILL.md carries under
metadata.revision, so an agent that has loaded the skill can compare it with
the one its tool prints, and see for itself that its instructions predate its
binary. Worth checking when the skill came from a clone and the binary from a
release: those are two points in history, and nothing forces them to match.
The same executable carries every surface. A client with no shell reaches the
verbs over MCP through ank mcp, and the background cache warmer is ank watch: there is nothing further to install for either. The MCP server
says how a client is configured.
Where the binary you run comes from
A globally installed ank tracks the published release, not the tree you
have checked out. The two are the same file only on the day of a
release.
It matters when a corpus is written by a binary newer than yours: somebody
else’s release, or your own tree if you contribute to Ank itself. Then the tool
managing the work and the tool being changed both print ank 0.8.0, and only
the commit separates them, which is why --version carries it.
Contributors hit a sharper form. On Windows a running
executable cannot be relinked, so a command that rebuilds the tree while
target/debug/ank runs it fails on the lock. The habit that avoids it is to
copy the built binary outside target/ and run the copy, which drifts from the
tree as soon as the tree moves. Rebuild and re-copy it after a merge.
One half of this the tool diagnoses on its own. A corpus whose entities declare a schema newer than the binary reads is refused entity by entity, so every verb that lists would silently answer short; each says so first:
$ ank find --type task
warning: corpus at schema 5, this binary reads 4: 1 entity left out of every listing
-> no release is known to read schema 5: ank --version names the build, build from the tree or wait for a release
TASK-c971 [open] Ordinary task
It warns and still answers: the entities this build understands are worth having, and a corpus mid-migration is a real state.
The second line is one of two, chosen by whether a release can help. The
schema a published version reads is stamped into the binary at build time, from
the newest tag’s own source, so the message names the road that resolves the
state. Above, no release reads the corpus: the schema landed on the default
branch after the last tag, the ordinary case for a contributor, so it sends you
to the tree. Where a published release does read it, your binary is simply old,
and the line names the install:
-> the binary is older than the corpus: ank --version names the build, npm install -g @haksolot/ank replaces it.
Naming the install in the first case would fetch the very build that refused, and a reader whose advice visibly does nothing concludes the tool is broken.
The other half, an old binary reading an old corpus, is undetectable: nothing in
the files says a newer format exists. That one is --version, the update below,
and the paragraphs above.
Updating
ank update --check reads the latest release from the repository releases are
published from, with git ls-remote --tags, and installs nothing:
$ ank update --check
running 0.8.0
latest 0.8.0
up to date
It exits 0 whether or not a newer release exists, because 8 belongs to check,
and when one does its last line says a newer release exists: ank update installs it. A script branches on newer:
$ ank update --check --json
{"contract":1,"current":"0.8.0","latest":"0.8.0","newer":false}
ank update installs that release through the route that placed the binary you
are running: npm install -g @haksolot/ank@<version> for a binary inside the npm
package, and otherwise the installer for your platform, told the directory the
binary already sits in. It downloads and unpacks nothing itself, so the checksum
is verified where it always was. At or above the latest release it installs
nothing and says so:
$ ank update
running 0.8.0
latest 0.8.0
up to date
Otherwise it prints the command it hands the install to, runs it, and exits
with that command’s code. The installer it pipes is the one tagged with the
release it installs, read from raw.githubusercontent.com/haksolot/ank/v<version>/,
so a change on main reaches an update only once a release carries it. A
release at or below 0.9.4 still takes the installer on main, as before. --version <v> installs the release it names, an
older one included. The skills stay where they are: when the new release carries
another skill revision than the binary it replaced, update names ank skills --install in one line and leaves running it to you.
Only this verb reaches the network for a release, and only when you run it. A
binary built under a cargo target directory was placed by no route, so update
refuses it at exit 7 and names cargo build. Where the releases are read from
is ANK_UPDATE_REPOSITORY.
The skills
Seven plain markdown files, one per skill, each the only copy in git. Every route below points at it, or, for the binary, carries the copy its build read, so nobody keeps a second copy in step by hand.
ank skill/SKILL.md the contract
ank-plan skill/plan/SKILL.md interview a goal into ADRs, specs and tasks
ank-drift skill/drift/SKILL.md audit decisions against the code
ank-loop skill/loop/SKILL.md work the backlog autonomously
ank-tdd skill/tdd/SKILL.md drive an implementation test-first
ank-diagnose skill/diagnose/SKILL.md work a defect back to its cause
ank-herdr skill/herdr/SKILL.md orchestrate several agents from a herdr-core terminal
skill/SKILL.md is
the one an agent loads by default, and it stands alone: why ank is shaped as it
is, the verbs grouped by the moment each is used, and the rules that bind every
agent. It names each sibling so an agent reaching for an activity knows what to
load, and works whether or not they are installed. The five activity policies,
ank-plan, ank-drift, ank-loop, ank-tdd and ank-diagnose, carry one
activity each and load when it calls for them. The sixth sibling, ank-herdr,
is for the agent that runs the others: its description triggers only inside a
herdr-core terminal. What an agent does with them once installed is Multi-agent
work.
The routes:
ank skills --install from the binary you installed, nothing cloned
npx skills add haksolot/ank a machine with node and no ank
/plugin marketplace add haksolot/ank Claude Code, as a plugin
by hand copy skill/SKILL.md where your harness loads it
From the binary
The build embeds the seven files, so the binary in your hand already carries the
skills written for it. ank skills lists them, with the revision each file
declares. The revisions below are the ones this page was written against; yours
are whatever ank --version names:
$ ank skills
ank 0d916cc3d9a5 Read a repository's tasks and binding constraints, claim work, and finish it with proof. Use when working in a repo that has a .ank/ directory.
ank-diagnose b5d9c0b96462 Work a defect back to its cause before changing anything, and close it with a regression test. Use when a claimed task's criterion names a defect in a repository with a .ank/ directory.
ank-drift 36cf5808e95e Audit the decisions in .ank/ against the current code and report what no longer holds. Use when asked whether ADRs, specs, or tasks are still accurate, after a milestone, or when the corpus and the code seem to disagree.
ank-herdr a0567f7f382a Orchestrate several ank agents in parallel, each on its own task, worktree and branch. Use only inside a herdr-core terminal, when asked to fan ank tasks out across agents in a repository with a .ank/ directory.
ank-loop 9f00f607cdb8 Work through the open tasks in .ank/ without supervision, one claim at a time. Use when asked to work the backlog, chain tasks, or run autonomously in a repository with a .ank/ directory.
ank-plan 83130b664c7e Interview a goal into decisions and tasks recorded in .ank/. Use when someone brings a feature, change, or problem to plan before implementation in a repository with a .ank/ directory.
ank-tdd 96d151e6812e Drive an implementation test-first, red before green, against a claimed task's frozen criterion. Use when implementing a task in a repository with a .ank/ directory.
One line per file: the name, the revision that file declares, and the whole
description. The revisions are the build’s, which is what makes them comparable
with the one --version printed. Run inside a corpus, the same verb prints a
second block under that listing, which Multi-agent
work reads.
ank skills --install writes them into a new directory under the temporary
directory and hands that directory to the skills CLI below, without asking:
the flag is the consent. It prints two lines of its own, wrote 7 skills to <directory> and running: npx skills add <directory> -y; everything after them
is the skills CLI’s own report of the seven skills it found and where it
linked each one. The -y answers that CLI’s question of which skills and which
agents: all of them, from an agent’s session or from your own terminal alike.
The files are the binary’s, so they match the build ank --version names.
npx itself goes online to fetch the skills CLI the first
time it has none cached. That CLI installs copies into .agents/skills of the
directory it ran from, and they outlive the temporary
directory. Without npx on your PATH, the verb prints the directory it wrote
and the command to run later, and exits 0.
The skills CLI
The route for a machine that has node and no ank. It detects what you run (Claude Code, Codex, Cursor, OpenCode and some thirty more) and links each one to a single copy. Ask it what it found before you let it install:
npx skills add haksolot/ank --list
It clones the repository and lists the seven skills it found, each with its
description. Drop --list to install them all, or name one with --skill. That
route installs the skills and leaves the binary to you.
This is the widest route and the least anchored one. It finds the skills through
its own recursive scan, since skill/ is outside the directories it looks in by
name, so it works because the fallback works. If a future version of that CLI
narrows its search, this route breaks first, and the hand copy below is the
answer.
Claude Code, as a plugin
This repository serves as its own marketplace:
/plugin marketplace add haksolot/ank
/plugin install ank@ank
Then ask what it costs, the question worth asking of anything loaded on every session:
claude plugin details ank
It prints the plugin’s component inventory, the seven skills and zero agents,
hooks or servers, then a projected token cost per skill, split into always-on
and on-invoke. Nothing of the plugin runs unless you call ank yourself, and
the counts are estimates that move with the skill files and with whatever does
the counting.
Read the two columns as what they are. Always-on is one description per skill, paid by every session whether or not anything fires; on-invoke is a body, paid by the session that wanted it. Splitting the teaching moved cost from the second column to the first: an agent executing a task skips the planning policy, and every session pays a little more to know the policies exist. The ceiling on the bodies holds anyway, because the by-hand route copies whole files into harnesses that may load all of it every session.
By hand
Each skill is one file with nothing generated in it. Where no route above fits
your harness, copy skill/SKILL.md into whatever it loads and you have lost
nothing. Copy
skill/plan/SKILL.md, skill/drift/SKILL.md, skill/loop/SKILL.md,
skill/tdd/SKILL.md and skill/diagnose/SKILL.md beside it for the activity
policies, and skill/herdr/SKILL.md for orchestrating agents from a herdr-core terminal,
or keep the contract alone, which stands on its own.
The Claude Code hook
The binary also serves as a hook handler for Claude Code. One command writes its entries into your user-level settings:
ank hooks install claude
It edits settings.json in CLAUDE_CONFIG_DIR, or ~/.claude/settings.json
when that variable is unset or empty, and adds two entries. The SessionStart
one hands the agent ank status and a pointer to the contract at the start of
every session. The PreToolUse one runs before the file tools: it keeps the
agent out of .ank/, and warns when an edit lands on a file that none of the
agent’s claims covers.
Both entries call the binary that installed them by its absolute path, so run the command again after you move or replace that binary. A second install leaves the file as it was, every byte it did not add stays where it was, and this takes out exactly what install wrote:
ank hooks remove claude
Outside a corpus the hook stays silent and lets every tool call through. Its two guards, the levels they take and how a launch environment tightens them are in Integrating.
Next: the quickstart, from ank init to a first finished task.
Quickstart
By the end of this page your repository holds one binding constraint, one
finished task, and a proof that Ank wrote after running the verification
itself. It takes about ten minutes. It assumes ank answers ank --version;
Install gets it there.
Every command and output below was run against a fresh repository, and the suite replays them against the binary on every change. Each step says what it does and links to the page that explains it whole.
Initialise a repository
Three files are in the tree before anything starts, because every scope and every verifier below points at one of them. These are their exact contents, one line each, since two hashes further down are hashes of them:
src/auth/session.ts export function createSession(id) { return store.put(id) }
tests/auth.sh exit 0
README.md # auth service
All three have to exist. A scope matching no file and a verifier whose command
is missing are the two ways this walk ends in red, and both stay silent until
ank done, a dozen commands later.
From the root of that repository:
$ ank init
created .ank/entities
wrote .ank/config.yml
wrote .gitattributes
wrote .gitignore
pointer added to AGENTS.md
@AGENTS.md added to CLAUDE.md
refspec added: +refs/ank/*:refs/ank/*
Two of those files are for the agents who will work here. AGENTS.md
gains a short block telling them to run ank context <path> before editing a
path and to reach .ank/ through the CLI, and naming claim, done and
help. CLAUDE.md gains the line @AGENTS.md, which makes Claude Code load
that block. Only the run that creates .ank/ writes them.
A repository with no origin prints the last line differently: there is no
remote to add a refspec to, so init names itself as the command to run once
there is one. A second init after adding the remote picks it up:
$ ank init
created .ank/entities
wrote .ank/config.yml
wrote .gitattributes
wrote .gitignore
pointer added to AGENTS.md
@AGENTS.md added to CLAUDE.md
refspec +refs/ank/*:refs/ank/* not added: no remote named origin yet, run this once it exists (ank init)
$ git init -q --bare ../origin.git && git remote add origin ../origin.git
$ ank init
refspec added: +refs/ank/*:refs/ank/*
Otherwise a second init writes nothing and says already initialised, nothing to do. Whether you want an origin at all is a question about
coordination, answered in Claims and identity.
Every entity lives flat in .ank/entities, and a field tells a task from an
ADR. The .gitattributes line keeps .ank/ in LF on a Windows checkout. The
.gitignore line covers the SQLite index, which every command rebuilds from
the files when it is missing. The refspec makes claims travel, since hosts
fetch only the standard refs on their own. Both git files are appended to, so
an existing .gitignore keeps what it had. The file format
describes the whole layout.
Name your default branch. It is the one key init leaves unset on purpose:
init runs before the reference branch is known, and writing main there would
be a guess. .ank/config.yml is written through the CLI:
$ ank config default_branch main
default_branch (unset) -> main
Without it, Ank looks for refs/remotes/origin/HEAD, which a repository with
no remote lacks, and check says what it stopped judging:
$ ank check | grep 'default branch'
signal: coordination: default branch indeterminable, completion refs neither pruned nor judged and log entries not compared against it (ank config default_branch <name>)
A clone sets refs/remotes/origin/HEAD for you; setting the key anyway costs
one line and makes both kinds of repository behave alike.
The two kinds this page uses
Each entity is a markdown file with YAML frontmatter. Four kinds exist and this page needs two; the others are a spec, normative text that describes, and a log entry, written once.
An ADR is a decision that constrains code. Its constraint is the one
field injected into an agent’s context, so it is short and imperative; the body
holds the reasoning and costs nothing at injection time.
A task is a unit of work. Its done_criteria says what would prove it
finished.
Both carry a scope, a list of globs, and the scope is the only thing joining
the two kinds. “Everything about the auth migration” is answered by
ank context src/auth/. The full field list is in
Entity fields.
Write the first constraint
$ ank new adr --title "Opaque sessions over stateless JWT" \
--scope "src/auth/**" \
--constraint "Do not introduce self-contained JWTs for user auth. Every session goes through the Redis store."
created ADR-06d29e727d24 Opaque sessions over stateless JWT
It is created proposed: visible, and binding nobody yet. One command
promotes it. It writes the ratification as a tag at refs/ank/ratify/<id>,
signed where the repository signs, updates the file, and commits nothing:
$ git add -A && git commit -m "adr: opaque sessions"
$ ank accept 06d2
accepted ADR-06d29e727d24 -> 3f0a6b2
Short prefixes work everywhere an id is accepted, and an ambiguous one lists
the candidates. The tag’s message carries the hash of constraint and scope
at acceptance:
ratify ADR-06d29e727d24
constraint+scope: c5d4f3478ad5
by: human:marie
That hash is the anchor: edit the constraint afterwards and ank check
notices. accept runs on any branch, and the file it updates travels with your
next commit. Ratifying covers the act and
Signing keys how others verify it.
Declare the verifiers, then the task
A task names verifiers, and their commands live in .ank/config.yml. Writing a
run for a new name declares one:
$ ank config verifiers.auth-tests.run "sh tests/auth.sh"
verifiers.auth-tests.run (unset) -> sh tests/auth.sh
$ ank config verifiers.no-jwt.run "! grep -rq jwt.verify src/auth/"
verifiers.no-jwt.run (unset) -> ! grep -rq jwt.verify src/auth/
Then the task, naming both:
$ ank new task --title "Migrate auth to opaque sessions" \
--scope "src/auth/**" \
--criteria "The auth tests pass and no reference to jwt.verify remains in src/auth/" \
--verify auth-tests --verify no-jwt
created TASK-820d259af6a7 Migrate auth to opaque sessions
Every verifier a task names has to pass. The list a task gets when it names none, and everything else about verifiers, is in Proof and verifiers.
Orientation
ank context is the first call, and the only one you have to remember. With no
argument it covers the whole repository; with a path it covers that perimeter.
$ ank context src/auth/
CONSTRAINTS (1 active)
ADR-06d2 Opaque sessions over stateless JWT
TASKS (1)
TASK-820d [open] Migrate auth to opaque sessions
> ank claim TASK-820d to start
Before a claim, each constraint shows its title. The question here is which
perimeter to enter, and titles answer it in the least space. The full
constraint arrives with the claim, below; ank show 06d2 prints it at any time.
The output ends with the next command, as every output here does.
Claim
$ ank claim 820d
claimed TASK-820d259af6a7 migrate-auth-to-opaque-sessions -> HEAD
The task is in_progress, a ref says who holds it, and its done_criteria is
frozen by hash. The next commands need no id. How long a claim lasts and why
each session needs its own identity are Claims and identity.
Run ank context again and it narrows to this task: its criterion, and the
constraints matching its scope in full.
$ ank context
TASK-820d Migrate auth to opaque sessions
DONE_CRITERIA
The auth tests pass and no reference to jwt.verify remains in src/auth/
CONSTRAINTS (1 active)
ADR-06d2 Do not introduce self-contained JWTs for user auth. Every session goes through the Redis store.
ank show 820d prints the entity whole: frontmatter, body, where the
reasoning lives, and log.
Work, and log what you learn
$ ank log "jwt.verify removed from session.ts"
logged LOG-6b0f39d7a4c1 on TASK-820d259af6a7
The log is a work trace. Write to it when you discover something: each entry
renews the claim, so working is what keeps the lock. ank log 820d with no
message reads the entries back, newest first. How they are stored is
the file format.
Finish
$ ank done
running: auth-tests ... ok (0.0s)
running: no-jwt ... ok (0.0s)
proof recorded: auth-tests@94a1f671c577 -> local/e3b0c44298fc@9c45c50 (scope/18d14da584ab)
proof recorded: no-jwt@791cc818d0ad -> local/e3b0c44298fc@9c45c50 (scope/18d14da584ab)
TASK-820d259af6a7 -> done
This is the point of the tool: Ank ran the verifiers itself and recorded what ran, so the status is Ank’s measurement of the tree. What each hash on those lines means is in Proof and verifiers.
Commit, and read check
Ank leaves committing to you. Its files wait in your working tree and travel
through your normal review. Before you commit, check reads them:
$ 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)
One signal asks for something, the uncommitted work, and two more only
report; ank check --all prints those. Commit, and the uncommitted work is
gone:
$ 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)
That is the green this page set out to reach: signals, no fault, exit 0. Each line, and the pruned ref, is explained in Reading ank check.
When a command refuses, its exit code carries the meaning and its message ends with the command to run next. The codes are the exit-code reference.
Starting where there is already code
Everything above happened in a new repository. ank init on two years of
history leaves you with an empty corpus, and the question becomes which
decisions this code has already made. That reading is an agent’s work, and
these three prompts ask for it. Both installers offer to print the same three,
and a test holds the copies together.
Run this once, at the root of the repository:
ank init
Then paste each prompt into your agent, one at a time, reading what comes back before you send the next.
What the code already decided. This is the one you judge the tool on. A constraint you recognise on sight was true and unwritten, and now the next agent reads it without being told.
Read this repository and write, as ank ADRs, the decisions its code
has already made: the ones a newcomer would break without knowing
they existed. One ADR per decision, each with a scope glob covering
the files it binds and a constraint stated as a rule. Leave them
proposed; I ratify them myself.
They land proposed. ank review lists what is waiting, and ank accept <id>
stays yours, one at a time.
What it still owes. An agent can take work that has a scope and a
criterion, which is what ank claim freezes and ank done measures. TODOs and
issues become that here.
Read the TODOs, the open issues and the README of this repository,
and turn what they promise into ank tasks. Give each one a scope
glob and a done_criteria a test could settle, and use blocked_by
only where a task genuinely waits on another.
Whether the answer holds. The third is the uncomfortable one. Writing down what was implicit ordinarily turns up constraints the code already breaks, and what you want first is the list, before anybody starts repairing.
Run ank check and ank review here, then read every ADR back against
the code its scope matches. Tell me which constraints the code
already breaks and which scopes match no file, and change nothing
until I have read your answer.
The tool waits on none of the three. A corpus holding only the ADRs from the
first prompt is already worth ank context.
Why it works this way
You have now done the loop once, which is the right moment for the four properties underneath it.
Scope, not hierarchy. Constraints and work are two planes joined only by globs. A rule written last year binds work created today, and a glob can be checked against the filesystem, where a label can only be remembered.
Nobody declares themselves done. An agent that reports its own result can
simply be wrong, so ank done runs the verifiers itself and records what ran,
hashed.
Freezing is verifiable. You can edit any file. Frozen fields are anchored by
a hash the editor cannot reach, and ank check compares, so editing a
criterion to unblock yourself only makes the divergence visible.
Git does the hard parts. Claims are git refs, so the compare-and-swap that arbitrates two agents is the one git already guarantees. Undo, history and recovery are git’s, and there is no server to run.
One call is bounded at 8000 characters by default, roughly 2000 tokens: what
context serves has to fit in a context window beside the code, and every
choice above pays for that. The normative text behind all of
it is the specification; ank help lists every verb, and
ank help <verb> answers about one.
Proof and verifiers
A task is finished when ank done says so, and ank done says so only after it
has run the task’s verifiers itself and recorded what ran. This page is where
verifiers come from, how a task gets its list, what done writes, and what a
proof is worth depending on who produced it.
The examples run in the repository the quickstart builds: a
src/auth/session.ts, a tests/auth.sh that exits 0, and a default branch
named main.
A verifier is declared once, in config.yml
A task names verifiers; it never carries a shell command. The definitions live
in .ank/config.yml, under the repository’s own review, and they go in through
the same verb as every other key: writing a run for a name the file does not
carry is how a verifier is declared.
$ ank config verifiers.auth-tests.run "sh tests/auth.sh"
verifiers.auth-tests.run (unset) -> sh tests/auth.sh
$ ank config verifiers.no-jwt.run "! grep -rq jwt.verify src/auth/"
verifiers.no-jwt.run (unset) -> ! grep -rq jwt.verify src/auth/
which is what the file then carries:
verifiers:
auth-tests:
run: sh tests/auth.sh
no-jwt:
run: "! grep -rq jwt.verify src/auth/"
ank config --unset verifiers.no-jwt takes one back out. Reading a key says
where the value comes from, this repository or a default the tool resolved:
$ ank config verifiers.auth-tests.run
sh tests/auth.sh
$ ank config verifiers.auth-tests.timeout
10m (default)
The distinction is the reason writing is line surgery rather than a round-trip through a YAML serializer. Your comments, blank lines, key order and quoting survive a write, and a key you never set is never written out: an unset key follows the tool, a written one is pinned here, and a serializer would quietly convert every one of the first kind into the second. Every key a verifier takes is in config.yml keys.
A verifier runs under sh -c from the root of the working tree, on all three
operating systems, and passes when it exits 0.
A task names its list when it is written
Declare the verifiers first. A task that names one config.yml does not know is
refused at creation, so a name you misremember fails when you write the task
rather than at the close:
$ ank new task --title "Migrate auth" --scope "src/auth/**" --verify auth-tests
error[7]: no verifier 'auth-tests' in .ank/config.yml
-> ank config verifiers.auth-tests.run "<command>"
With the definitions in place, --verify names them one at a time, and a
composite criterion is mechanised by several verifiers rather than by one that
covers half of it:
$ ank new task --title "Migrate auth to opaque sessions" \
--scope "src/auth/**" \
--criteria "The auth tests pass and no reference to jwt.verify remains in src/auth/" \
--verify auth-tests --verify no-jwt
created TASK-820d259af6a7 Migrate auth to opaque sessions
The default list
--verify one at a time is the right amount of ceremony for a verifier that
suits one perimeter and the wrong amount for the suite every task in the
repository has to pass. A verifier marked default joins every task written
afterwards:
$ ank config verifiers.no-jwt.default true
verifiers.no-jwt.default false (default) -> true
which lands beside the run it belongs to, and nowhere else in the file:
verifiers:
auth-tests:
run: sh tests/auth.sh
no-jwt:
run: "! grep -rq jwt.verify src/auth/"
default: true
The read form is the same as any other key, and an unmarked verifier answers
false (default) – the tool’s default for the default key, which is the one
place the word does double duty:
$ ank config verifiers.no-jwt.default
true
$ ank config verifiers.auth-tests.default
false (default)
A task created now with no --verify of its own carries verify: [no-jwt] in
its frontmatter, without anybody naming it. --verify replaces that list
rather than adding to it, so a task that names its own verifiers gets exactly
those.
Declining it
--no-verify is the third possibility, and it is a judgement, not a
shortcut. It writes a task with no verify: at all:
$ ank new task --title "Say in the README what a session is now" \
--scope "README.md" \
--criteria "The README describes opaque sessions and names no JWT" \
--no-verify
created TASK-51c2a0f6d418 Say in the README what a session is now
Use it where no declared verifier can settle the criterion – prose a person has
to read, a behaviour only a published release answers – and where that is
genuinely the case, say so when you write the task, so the empty list is
visible in its diff. A task that reaches done with an empty verify: nobody
decided on closes on a proof nothing ran.
What done records
$ ank claim 820d
claimed TASK-820d259af6a7 migrate-auth-to-opaque-sessions -> HEAD
$ ank done
running: auth-tests ... ok (0.0s)
running: no-jwt ... ok (0.0s)
proof recorded: auth-tests@94a1f671c577 -> local/e3b0c44298fc@9c45c50 (scope/18d14da584ab)
proof recorded: no-jwt@791cc818d0ad -> local/e3b0c44298fc@9c45c50 (scope/18d14da584ab)
TASK-820d259af6a7 -> done
One proof entry per verifier, carrying the hash of the verifier definition that
executed, a hash of what it printed, the HEAD commit, and a hash of the scope
files’ content at that moment. Four of those hashes are content and not
identity, so they are the same on your machine as on this page. 94a1f671c577
and 791cc818d0ad are the two verifier definitions; e3b0c44298fc is what each
of them printed, which is nothing; and 18d14da584ab is src/auth/session.ts
as the quickstart wrote it. The commit is the one your tree is on, so that one
is yours.
If a verifier fails or times out, the transition is refused and the task stays where it is.
A task with no verifier needs a proof you hand it. There is nothing for
done to run, so --proof becomes mandatory:
$ ank claim 51c2
claimed TASK-51c2a0f6d418 say-in-the-readme-what-a-session-is-now -> HEAD
$ ank done
error[5]: proof required to move TASK-51c2a0f6d418 to done
-> ank done --proof commit:<sha>
The reverse is refused too: a task that declares verifiers takes no --proof,
because what closes it is what ran and not what somebody typed. Give a proof you
already hold, commit:<sha>, and never a run id you would have to wait for.
What a proof is worth
The proof types are commit, test, human-review and assertion, and what
separates them is not local versus hosted but who controls the environment.
A CI reference is out of the agent’s reach and guarantees the most;
commit:<sha> is checked with git; a local test proves what ran in a tree the
agent could have altered; assertion:"..." guarantees nothing and is marked
weak, which is what keeps it from quietly becoming the default path.
The type is half the answer, and the entry records the other half. Every
proof carries via: verifier when Ank ran the verifier itself, attested
when it arrived on refs/ank/proof/<id>, submitted when a caller typed it,
because a run reference is the strongest thing in that list when a pipeline
wrote it and the weakest when somebody typed it (ADR-b6b69053a47b). Typing
--proof test:<run-id> is still accepted and still recorded; what it does not
do is clear the done with no test proof signal, which stays until a pipeline
anchors the run. Entries written before the field carry no via and are read
exactly as they were.
A run that already passed on the same bytes is not run again. Every run
done starts is recorded, pass or fail, under <git-common-dir>/ank/runs/,
keyed on the verifier’s name@hash and a digest of the files its inputs
match – tracked, or untracked and not ignored, as they are on disk – or of the
whole tree without inputs. A later done, in this worktree or a sibling of
it, reuses a passing entry with the same key no older than
proof.reuse_max_age (default 24h) instead of starting the verifier, and
says so: the entry keeps the reference and the route of the run it came from
and adds reused: local and by: <identity>. A failure is never reused, nor a
run from another machine, nor an attestation. Split a suite into verifiers with
disjoint inputs and only those whose files changed run again;
ank done --fresh runs every one (ADR-a2faf59f6ce0).
Splitting a suite into verifiers walks through it on
two packages, with ank verify running ahead of the close.
done records what ran on the machine that ran it, which is a local claim.
Anchoring a run is how a pipeline adds the external
half after the merge, without a commit.
done proves the task in the working tree it ran in. It does not prove the
change merges, or that the combined system works: that gap, and the task that
closes it, are Multi-agent work.
Splitting a suite into verifiers
ank done runs every verifier the task declares, and a suite that takes ten
minutes makes every close cost ten minutes. This page is the recipe for cutting
that cost in your own repository, in any language: split the suite into one
verifier per package, tell each one which files it reads, and let done skip
what it has already seen pass. Proof and verifiers is where
verifiers themselves are explained; this page assumes it.
Two mechanisms do the work, and they answer different questions:
donereuses by content. A run is recorded under the verifier’s definition and a digest of the files itsinputsmatch. A laterdonewhose key is the same, and whose recorded run passed, reuses it instead of starting the verifier again. Nothing about the branch, the commit or the order of events enters the key: the same bytes are the same answer.ank verifyselects by change, and proves nothing. It runs the verifiers whoseinputsmatch a file changed on the branch and records each run wheredonewill find it. It needs no claim, writes no proof, no ref and no entity, and its selection is printed and never recorded. What it buys is that thedonewhich follows has nothing left to run.
A repository with two packages
Two packages, billing/ and search/, each with a test script of its own,
billing/test.sh and search/test.sh. One verifier per package, each
declaring the files that can change its result, and both marked default so
every task carries them:
$ ank config verifiers.billing-tests.run "sh billing/test.sh"
verifiers.billing-tests.run (unset) -> sh billing/test.sh
$ ank config verifiers.billing-tests.inputs "[billing/**]"
verifiers.billing-tests.inputs (unset) -> ["billing/**"]
$ ank config verifiers.billing-tests.default true
verifiers.billing-tests.default false (default) -> true
$ ank config verifiers.search-tests.run "sh search/test.sh"
verifiers.search-tests.run (unset) -> sh search/test.sh
$ ank config verifiers.search-tests.inputs "[search/**]"
verifiers.search-tests.inputs (unset) -> ["search/**"]
$ ank config verifiers.search-tests.default true
verifiers.search-tests.default false (default) -> true
verifiers:
billing-tests:
run: sh billing/test.sh
inputs: ["billing/**"]
default: true
search-tests:
run: sh search/test.sh
inputs: ["search/**"]
default: true
The inputs are disjoint, and that is the whole design. A change under
billing/ cannot alter what search-tests reads, so its last passing run
stays valid. A verifier with no inputs reads the whole tree: any change at
all invalidates it, and ank verify always selects it. In a real repository the
inputs of a package’s tests are the package itself and whatever it depends on
inside the repository, shared code and lock files included; an input you leave
out is a change the reuse will not see.
The first close runs everything
Nothing has been recorded yet, so the first task to close runs both:
$ ank new task --title "Rank exact matches first" --scope "search/**" \
--criteria "An exact title match ranks above a partial one"
created TASK-f89bb33affbf Rank exact matches first
$ ank claim f89b
claimed TASK-f89bb33affbf rank-exact-matches-first -> HEAD
$ ank done
running: billing-tests ... ok (0.0s)
running: search-tests ... ok (0.0s)
proof recorded: billing-tests@98f3ff3419f0 -> local/e3b0c44298fc@5f99e12 (scope/e2825598a6ca)
proof recorded: search-tests@bd59a126e55a -> local/e3b0c44298fc@5f99e12 (scope/e2825598a6ca)
TASK-f89bb33affbf -> done
Both runs are now recorded under <git-common-dir>/ank/runs/, which every
worktree of the repository shares.
A change to one package
The next task changes billing/ on a branch of its own:
$ ank new task --title "Round invoice totals half to even" --scope "billing/**" \
--criteria "Totals round half to even"
created TASK-5493c635b193 Round invoice totals half to even
$ echo '# half to even' >> billing/test.sh
$ ank verify
running: billing-tests ... ok (0.0s)
3 file(s) changed since ada2f49; ran 1 of 2 verifier(s), recorded for reuse
billing-tests ok
search-tests skipped, no input changed
ank verify read what changed since the merge-base with the default branch –
billing/test.sh, and the task and its log entry, not yet committed – selected
the one verifier whose inputs that touches, and ran that one. It
proved nothing: the task is still in_progress, no proof was written, and
nothing about the selection was kept. What it kept is the run.
The done that follows
$ ank claim 5493
claimed TASK-5493c635b193 round-invoice-totals-half-to-even -> HEAD
$ ank done
running: billing-tests ... reused (local, by human:marie)
running: search-tests ... reused (local, by human:marie)
proof recorded: billing-tests@98f3ff3419f0 -> local/e3b0c44298fc@ada2f49 (scope/9bd058bccab7)
proof recorded: search-tests@bd59a126e55a -> local/e3b0c44298fc@5f99e12 (scope/9bd058bccab7)
TASK-5493c635b193 -> done
Neither verifier started. billing-tests is the run ank verify just
recorded, on the bytes billing/ holds now. search-tests is the run the
previous close recorded: search/ has not changed since, so the key is the
same and the answer is the same. The commits in the two entries say so: ada2f49 is
where ank verify ran, 5f99e12 where the first close did. Each entry keeps
the reference and the route of the run it came from and adds reused: local
and by:, so the record says which closes ran a verifier and which took an
earlier answer.
What is never reused
A failure is never reused, nor a run from another machine, nor an attestation,
nor a run older than proof.reuse_max_age (default 24h). ank done --fresh
runs every verifier regardless. And ank verify is never a substitute for
done: a task closes only when done has recorded its proof, whether the runs
behind that proof were started by done itself or found waiting.
Claims and identity
A claim is how one agent takes a task and every other agent sees that it is
taken. It is a git ref rather than a field, it lasts as long as somebody is
working, and it is held by an identity the caller declares. This page is the
whole lifecycle, from claim to release or done.
What a claim does
$ ank claim 820d
claimed TASK-820d259af6a7 migrate-auth-to-opaque-sessions -> HEAD
Three things happened. The task moved to in_progress. A claim ref appeared at
refs/ank/claims/TASK-820d259af6a7, which is what arbitrates two people or two
agents reaching for the same task: git’s compare-and-swap, one winner. And the
done_criteria was frozen: its hash went into the claim record, where the
file’s editor cannot reach it.
The freeze is the rule worth internalising. Editing the criterion to make the
work fit does not unblock anything; done compares against the recorded hash
and refuses, and check reports the divergence. If the criterion is genuinely
wrong, hand the task back and say so. A subtask you discover is a new task with a
blocked_by, never a softened criterion.
claim also sets HEAD, so the commands that follow need no id. One claim at a
time, per identity.
One identity per session
Claiming a second task while you already hold one is refused:
$ ank claim 51c2
error[7]: human:marie holds a live claim on TASK-820d259af6a7 (expires in 30m)
-> ank release --reason "<why>" (a second session on this machine sets its own ANK_AGENT)
If you meant it, the first way out is the one to take: finish the task you hold
or hand it back. If the refusal surprises you, it is almost certainly two
terminals. $ANK_AGENT names the session, and unset it falls back to
<user>@<hostname>, so two sessions on one machine are the same agent as far as
the refs can tell. Give every concurrent session an identity of its own:
$ ANK_AGENT=human:marie-2 ank claim 51c2
claimed TASK-51c2a0f6d418 say-in-the-readme-what-a-session-is-now -> HEAD
Two sessions sharing an identity are not arbitrated, they are merged.
Claiming the task the identity already holds is granted again at exit 0, so a
second session with no ANK_AGENT of its own silently starts work the first one
is already doing:
$ ank claim 820d
claimed TASK-820d259af6a7 migrate-auth-to-opaque-sessions -> HEAD
So the failure mode is not a message nobody sees. It is two sessions writing the same perimeter under one name, which the refs cannot tell apart and no reader can untangle afterwards. That is why the refusal above names the identity rather than calling you its holder: under a shared identity, the session being refused may have claimed nothing at all.
Write the identity typed. An identity that goes into an entity says what
kind of actor it is (ADR-3877fef1d662): human:<id> is a person,
<producer>/<version> an agent – claude-code/opus-5, and a suffix after +
for one session of it – and process:<id> something automated, which is the
form a pipeline uses. The convention is what lets check say that an entity was
written by an agent and read by no human; the fallback <user>@<hostname>
carries no type and so answers that question with nothing. It is a signal and
not a wall – anyone can type human: in front of a model – and what it buys is
that the ordinary case is legible.
Identity is declared, never proved, and it is deliberately not bound to the
session: a PID or a TTY in it would mean losing your claim to a restarted
terminal. $ANK_AGENT records who was working rather than restricting who may.
Nothing in ank refuses on identity; the refusals are on state, and the one hard
authority line is the signed ratification ank accept writes at
refs/ank/ratify/<id>.
The lease, and what renews it
A claim lasts 30 minutes by default and is renewed by working, not by reporting
(ADR-0bb7ea8991bc). Three verbs move the lease, measured by reading the expiry
out of ank status --json before and after each call:
ank context, in every form – bare, with a path, with--json.ank show <id>, when<id>is the task this identity holds.ank showover any other entity leaves the lease alone, so it is the subject that renews and not the verb.ank log "<message>", the appending form.ank log <id>, which reads, does not.
find, status, scope, graph, check, review and help leave the expiry
untouched. So there is no heartbeat command to remember: writing down what you
learned is what keeps the lock. A tool that shows a corpus to somebody must not
put context or show on a timer, and the machine surface
says what to poll instead.
An expired claim is not a live one. If a build ran long and the lease ran out,
the task stays in_progress and you re-acquire it silently, provided nobody
took it over; and nothing stands between anybody and a task whose lease ran out,
yours or another’s. A task that is in_progress in its file with no ref behind
it is simply one whose claim expired.
Handing a task back
$ ank release --reason "the criterion names a test that does not exist yet"
released TASK-820d259af6a7 -> open
The reason is recorded in the task’s log, where the next holder reads it with
ank log <id> before repeating what you tried. Never let a claim lapse in
silence: an expired lease tells the next agent nothing about why.
When done, the claim becomes a completion
done does not delete the claim ref. It turns it into a completion record naming
the commit and the branch the task was finished on, because status: done lives
in the file, therefore on your branch alone until the merge, and during all that
time the task would look free to everyone else. Anyone who tries to claim it
meanwhile is refused with the commit and the branch named, and every other tree
answers finished on another branch (commit …, branch …), not merged here yet.
check prunes the record once the default branch says the task is done:
Reading ank check shows both states.
Where claims travel
Coordination between clones needs a remote named origin, and nothing
else. Whether claims travel is not configured: a repository with an origin
pushes every claim to it as a compare-and-swap, and one without keeps them as
local refs. GitHub is not required. A bare repository reachable over file://
or ssh on the same network is a remote named origin like any other: claim
reads it first, so the second clone to take a task is refused with code 4 and
the holder named, and the push settles a race the read misses. ank init adds
the refspec that makes refs/ank/* travel, since hosts do not fetch
non-standard refs on their own.
A remote named ank takes the claims, and only the claims. git remote add ank <url> is the whole setup, and there is no key to set: from then on every
read and write of refs/ank/claims/* (claim records and completion records
alike) goes to ank, while ratifications, proofs, the default branch and
everything else stay on origin, where CI and every fork read them
(ADR-b6fe84504ff2). Losing that remote costs leases and nothing else. status
names it on a line of its own, coordination ank carries refs/ank/claims/*, everything else stays on origin, and as coordination_remote in --json, so a
remote given that name for another reason is seen at once; status --remote
reads the claims off it. With ank and no origin, claims are arbitrated
through ank and every other ref stays local, as with no remote at all.
A fetch from origin never touches the claims ank carries. origin’s
+refs/ank/*:refs/ank/* matches refs/ank/claims/* too, so left alone a git fetch origin would write whatever claims origin still holds and git fetch --prune origin would delete every live claim it does not. init therefore
gives ank the fetch refspec +refs/ank/claims/*:refs/ank/claims/* and origin
the negative refspec ^refs/ank/claims/*, which keeps the claims out of its
fetch and its prune while ratifications and proofs still come; where ank was
added after init, the first status or check writes both and says so on
standard error, one line per refspec (ADR-b6fe84504ff2). Removing ank gives
origin the claims back, and the same repair takes the negative refspec away, so
a clone with origin alone ends with exactly the two refspecs above. Where a
refspec could not be written, status warns and check reports a signal of
kind claims-refspec, each naming the remote whose fetch lacks it.
An origin without the refspec is repaired by the first verb that asks.
In a repository with no origin, init adds nothing and says so: refspec +refs/ank/*:refs/ank/* not added: no remote named origin yet, run this once it exists (ank init), and it says the same on every re-run until there is one.
Once origin exists without the refspec, which is also the state of every
fresh clone since git clone does not carry remote.origin.fetch, the first
status or check adds it, fetches refs/ank/* once, and says both on
standard error (ADR-1b030fe70442):
$ ank status
refspec added: +refs/ank/*:refs/ank/*, and refs/ank/* fetched from origin
$ ank check
1 signal(s) owe nothing: settled work, and no command clears them (ank check --all lists them)
check: ok — 0 tasks, 0 adr, 0 signal(s)
A clone that already has the refspec pays nothing for it, and with no origin
nothing is written, so git remote add origin keeps working. An origin that
cannot be reached still gets the refspec, and the next git fetch brings the
refs. Where the refspec itself could not be written, status warns and check
reports a signal, both naming ank init, which writes it the same way. A
re-run of init leaves AGENTS.md and CLAUDE.md as it finds them: the
agent bootstrap block and its @AGENTS.md import are written by the run that
creates .ank/ and by no later one, so a repository that dropped them on
purpose keeps them dropped through every repair (ADR-1f5a45d43f82,
ADR-5eb0f65c75da).
Without a remote, git worktrees of a single clone are still arbitrated,
because they share refs/ank/. Two clones with no common origin are not
arbitrated: both claims of one task succeed, both agents work, and nothing
reports it, not status, not check, not later.
A push that cannot reach the remote leaves the claim standing in your clone and
says so on stderr: the claim holds there only, and another clone can take the
same task. A remote that is reached and refuses the write for a reason of its
own (a hook, a ruleset, a credential) is reported with that reason, exactly as
git push --porcelain printed it: claim exits 9 and keeps nothing, since a
claim the remote refused is not one your clone may believe in, while log,
done, release and close keep what they wrote and warn with the reason.
Neither is ever reported as a task held by somebody else. A contributor working
from a fork is in the first position, and
CONTRIBUTING.md
says how coordination happens instead.
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.
Running ank in CI
Read this part before the recipes, because the recipes are the easy half. The
whole integration surface is two things: an exit code, and --json. Learn
those and you can write the pipeline for a CI system nobody here has heard of.
ank check is the verb a pipeline runs, and it has three answers a pipeline
routes on: 0 for a healthy corpus, signals included; 8 for findings,
which is the failure a pipeline exists to catch; and 9 for the environment
rather than the corpus – git too old, sh missing, the default branch
indeterminable. A pipeline that collapses 9 into “the check failed” sends
somebody to fix sound work. What the levels mean is Reading ank
check.
--json is opt-in on every verb and is what you parse. It carries no colour and
no layout, and it stays byte-for-byte what your parser already reads.
That is the contract. Everything below is the CI system’s own syntax around it.
Check out the whole history
On GitHub that is one line. ank check walks history: it reads the ratification
commit that anchors a constraint frozen before ADR-5e47007a75be, and it asks
where a scope that matches nothing went, a rename or a deletion. actions/checkout fetches one commit by
default, and a corpus read from one commit does not report itself unreadable –
it reports itself unverified, at exit 0. Measured on this repository at
8310e75: a --depth 1 clone answers
check: ok — 440 tasks, 61 adr, 728 signal(s) where the full clone of the
same commit answers 663, and 71 of those extra signals read
ratified, but no ratification commit is reachable: the freeze cannot be verified,
each noting that the history here is shallow, so where it went cannot be verified (git fetch --unshallow). Green, and every frozen constraint
unchecked, which is a worse failure than the red it replaces:
- uses: actions/checkout@v5
with:
fetch-depth: 0
Every host spells the depth its own way, and the thing to carry across is the
property rather than the key: check needs the history that reaches the
ratification commits, and a shallow checkout is silent about what it could not
read.
Fetch refs/ank/* before check
A ratification made since ADR-5e47007a75be is not a commit but a tag object at
refs/ank/ratify/<id>, and no host’s checkout fetches refs/ank/*. Read
without the ref, such a decision falls back to its file: check cannot verify
it, which is a signal at exit 0, and the same green-and-unchecked failure as a
shallow clone. check adds the refspec and fetches once in a clone that lacks
it, but a fetch that fails there is not an error, so a pipeline fetches the refs
itself and lets a failure fail the step:
- name: the refs ank reads
run: git fetch origin '+refs/ank/*:refs/ank/*'
One direction and read-only, so it runs on every event: a pull request from a
fork fetches from origin, the repository the pull request targets, and
verifies its ratifications the same way as one from a branch there. A refspec
matching nothing succeeds, so a corpus with no refs yet passes through
untouched.
Check a sibling repository out
A decision can bind two repositories (Several repositories). On a
laptop without the sibling checkout, check answers without it: the peer that
cannot be read is a signal, at exit 0. A pipeline expects the sibling, so it
checks it out beside the repository, at the path peers.<name> declares, and
runs check --peers, which makes a declared peer that cannot be read a fault at
exit 8. ank itself clones nothing (ADR-96fe1f9d619a), so the checkout is the
pipeline’s step:
- uses: actions/checkout@v5
with:
fetch-depth: 0
path: web
- uses: actions/checkout@v5
with:
repository: example/api
fetch-depth: 0
path: api
- name: ank check --peers
working-directory: web
run: ank check --peers
Without the sibling, plain check stays green and --peers turns red, naming
the peer, the path it was looked for at, and the override for a layout that
differs:
$ cd /work/web && ank check; echo "exit $?"
signal: peers.api: peer 'api' at ../api is not a corpus, answered without it (ank config --user peers.98204934184e14045a2158a2bd0f23586745d560.api <path>)
1 signal(s) owe nothing: settled work, and no command clears them (ank check --all lists them)
check: ok — 0 tasks, 0 adr, 1 signal(s)
exit 0
$ cd /work/web && ank check --peers; echo "exit $?"
error: peers.api: peer 'api' at ../api is not a corpus, answered without it (ank config --user peers.98204934184e14045a2158a2bd0f23586745d560.api <path>)
1 signal(s) owe nothing: settled work, and no command clears them (ank check --all lists them)
check: 1 fault(s) — 0 tasks, 0 adr, 0 signal(s)
exit 8
With the sibling checked out beside it, check --peers answers as check
does:
$ git clone -q /work/api.elsewhere /work/api
$ cd /work/web && ank check --peers; echo "exit $?"
1 signal(s) owe nothing: settled work, and no command clears them (ank check --all lists them)
check: ok — 0 tasks, 0 adr, 0 signal(s)
exit 0
--peers asks for the sibling to be readable, and only that: an edge naming a
task the sibling has yet to merge stays what check already says it is
(ADR-09b985a5627e).
The recipes
A bare shell, which is the recipe the other two wrap:
#!/bin/sh
code=0
ank check || code=$?
case $code in
0) ;;
8) echo "ank check: findings, see above" >&2; exit 1 ;;
9) echo "ank check: environment unavailable, not a corpus failure" >&2; exit 2 ;;
*) echo "ank check: unexpected exit $code" >&2; exit 1 ;;
esac
GitHub Actions:
- name: ank check
run: |
code=0
ank check || code=$?
case $code in
0) ;;
8) exit 1 ;;
9) echo "::notice::ank could not run: environment"; exit 2 ;;
*) exit 1 ;;
esac
GitLab CI:
ank:check:
script:
- |
code=0
ank check || code=$?
case $code in
0) ;;
8) exit 1 ;;
9) echo "ank could not run: environment"; exit 2 ;;
*) exit 1 ;;
esac
Three vendors, one contract, and the third one is a shell script in a YAML file like the other two.
ank check || code=$? and never a bare ank check followed by case $?: a
GitHub Actions run: block is bash -e, so the bare form aborts the step on
exit 8 and the routing you wrote is never reached. The || code=$? form is what
survives set -e, which is why it is in all three rather than in the one that
needs it.
There is no --format github, and there never will be. Annotations,
folding markers and job summaries are one vendor’s protocol, and putting them in
the binary would couple the tool to a company. A pipeline that wants annotations
pipes --json into whatever produces them, which is exactly the arrangement
that lets the fourth vendor work without anybody shipping a release for it.
Anchoring a run
done records what ran on the machine that ran it. That is a local claim, and a
pipeline can anchor the same task to a run anybody can re-read
(Proof and verifiers says why that is worth
more):
ank attest <id> --proof test:<run-id> --detached
--detached writes the proof to refs/ank/proof/<id> and touches no file, so
the pipeline produces no commit: it needs no write access to the branch and
cannot race the merge. It is still a write to the remote, though, and on GitHub
that is a permission: the job that attests raises it, to the one thing it
writes, and every other job keeps contents: read.
permissions:
contents: write
Which ids. check is the work list, and nothing diffs .ank/ to build it.
A finished task with no external anchor carries the signal
done with no test proof: nothing external anchors it, so the ids are the
subjects of that finding and --json is what a pipeline reads them out of:
ids=$(ank check --json | jq -r '
.findings[]
| select(.message | startswith("done with no test proof"))
| .subject')
Fetch the proofs already written first, before that check runs.
actions/checkout fetches history and not refs/ank/*, so a job that skips
this reads a corpus in which nothing is anchored and re-attests every finished
task, on every push, forever. Measured on run 33285805350: 199 ids listed and
336 seconds spent pushing refs that were already there, against 16 genuinely
unproved in a clone that carries them.
git fetch origin '+refs/ank/proof/*:refs/ank/proof/*'
One direction and read-only. A refspec matching nothing succeeds, so a corpus with no proofs yet passes through untouched.
Run it on the default branch and on a push, and nowhere else. The signal is
gated on the task appearing done on the default branch, so on a feature branch
straight after done there is nothing to anchor and this job would build for
two minutes to be told so. A pull_request event runs on a merge commit no
branch carries, and a fork’s token cannot push a ref at all, which would fail
the job for a reason about the event rather than about the corpus:
if: >-
github.event_name == 'push' &&
github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
The identity doing the attesting is typed like any other, and a pipeline is
process: (Claims and identity):
env:
ANK_AGENT: process:github-actions
The proof is a ref, so it has to reach the remote to be worth anything, and
because the ref is the whole of what this verb produces, a push that did not
land is a failure and not a warning: attest --detached exits 9 and names
the push to run. Nothing special is needed to notice it, which is the point:
ank attest "$id" --proof "test:$RUN_ID" --detached
--json still reports "pushed", so an integration that prefers to read the
flag reads the same fact. What it must not do is read the flag instead of the
code, because the two now say the same thing.
Attest on every run without worrying about the ref: it grows with facts and
never with runs. A fact is a proof type, the criteria hash it was attested
against and the identity attesting it, and a second run of the same fact
replaces the first, so show lists the latest run. A corpus whose proof refs
were written before that rule carries one entry per run, and check names each
such ref with the command that rewrites it, one ref by name:
ank attest <id> --compact --detached
It keeps one entry per fact, adds nothing and pushes that one ref. Never push
refs/ank/* with a wildcard to do the same: from a worktree, that force-reverts
the attestations a pipeline wrote.
This repository’s own pipeline does all of the above in its attest job, and
CI jobs and required checks maps it.
Multi-agent work
Ank is built for several agents working one repository at once, each taking a task the others can see is taken. This page is what handing the loop to an agent involves, and what running several of them actually requires. The skills that teach an agent the loop are installed by the routes in Install, and claims and identities, which do the arbitrating, are Claims and identity.
What the agent is taught
skill/SKILL.md is the contract an agent loads, and six siblings sit beside it.
Five carry a policy each, planning, drift audit, the autonomous loop, test-first
implementation and diagnosis, loaded when the activity calls for them. The sixth,
ank-herdr, teaches the agent that runs the others from a herdr-core terminal rather than
one doing the work (below). The contract names all
six, so an agent that loaded only it knows each one exists.
One convention it carries is worth knowing before you watch an agent follow it:
.ank/ is opaque to an agent, the way .git/ is. Reading goes through
ank show, ank find and ank context; writing goes through the verbs. The CLI
knows what the files do not: the context budget, the frozen criterion, who holds
which claim. A human with an editor keeps every power they had.
What that costs a session is the frontmatter, not the page. A skill’s name
and description are always loaded, somewhere between fifty and eighty tokens
each; a body is read when its skill is invoked. Install
shows the projection per skill.
The methods a corpus uses
A task can name the sibling its work calls for with ank new task --method tdd,
and ank context prints that name beneath the criterion once the task is
claimed. A sibling that opens under a claim writes an entry saying so with
ank log --method tdd, titled with its name and kept apart from the work trace
(ADR-a8f9c603a0e7). The designation is read, never enforced, and ank skills is where it
is read: inside a corpus it prints the catalogue and then a second block. On a
corpus of three tasks – one designating tdd whose holder loaded it, one
designating diagnose whose holder never did, and one designating nothing where
tdd was loaded anyway – the block reads:
METHODS
diagnose designated 1 fired 0 undesignated 0
drift designated 0 fired 0 undesignated 0
herdr designated 0 fired 0 undesignated 0
loop designated 0 fired 0 undesignated 0
plan designated 0 fired 0 undesignated 0
tdd designated 1 fired 1 undesignated 1
designated counts the tasks naming the sibling, fired those of them carrying
its entry, and undesignated its entries on tasks naming none. ank skills --json carries the same counts as integers. The numbers are read from the
corpus, printed to whoever asks, and sent nowhere; outside a corpus the verb
prints the catalogue alone.
One agent, one working tree, one identity
The nominal case is a tree per agent, a clone or a git worktree, each on its
own branch cut fresh from the default one, and each session with an
ANK_AGENT of its own. ank status names the drift from the default branch,
and a stale base turns a green tree red elsewhere.
Several agents in one tree runs, and it is a degraded mode rather than the
design: two sessions sharing a tree and an identity share a claim instead of
arbitrating over it (Claims and identity
shows what that looks like). What arbitrates properly is a git worktree per
agent, because every worktree of a repository shares refs/ank/, so the
compare-and-swap settles them. Separate clones are arbitrated only when there is
a remote, which is what the push carries: origin, or a remote named ank
when there is one, which then carries the claims alone
(Where claims travel).
Take the task that cannot collide, or take none. status says what another
agent holds; claim names a live claim whose scope intersects yours and takes
the task anyway (ADR-052accd6e3b2), a fact to read and not an error to refuse;
graph shows what blocked_by orders. When nothing open is both unblocked and
clear, an idle session is cheaper than two agents rewriting one perimeter.
Parallel work and integration
The section above says who works where. This one assembles the whole run: several tasks, several agents, one change landing on the default branch.
Parallelism is derived, not declared. blocked_by is the only relation
between tasks, and it is the only thing that serializes work. Tasks whose
blockers are finished are ready together, and ank context computes that
mechanically: every open task in the perimeter, the ready ones first, ordered by
how many other tasks each would unblock. Do not serialize independent tasks
because they belong to the same change. If the order matters, that is a
blocked_by; if there is no blocked_by, the order is a fiction. ank graph
prints the DAG when you want the shape rather than the next move.
One branch per task. Each agent claims its task, works in its own tree on
its own branch, and finishes there. ank done proves the task in the working
tree it ran in: the verifiers ran against those files and the proof records
their hash. It does not prove the change merges, or that the combined system
works. Until the merge lands, the claim ref stands as a completion record, so no
other tree takes the task for free (Claims and
identity).
Integration is a task. When several tasks form one change, the whole is
verified the way the parts were: an ordinary task, blocked_by each part, with
its own criterion and its own verifiers. This is the spec’s model rather than a
workaround: blocked_by is a DAG with no rollup precisely because a parent
that completes when its children do is completion without proof, and the seam
between the parts is exactly where integration regressions live. The
integration task becomes ready when the last part finishes; whoever claims it
merges the branches, runs the combined verification, and records done like
any other task.
Where the branches meet is git’s business, and both shapes are legitimate:
- Independent tasks merge to the default branch directly. Two tasks that share nothing need no ceremony between them, and no integration task either.
- A multi-task change goes through an integration branch. Branch it off the default branch, merge each task’s branch into it, resolve conflicts there, and point the integration task’s verification at the combined result. The default branch receives one verified change instead of three partial ones.
What ank will not do. No verb creates a worktree, names a branch, or merges
one. Tasks, claims, criteria, dependencies and proofs are ank’s plane; branches,
worktrees, merges and history are git’s, and git is already good at them. The
one place the planes touch is accept, and it touches them by writing a ref,
refs/ank/ratify/<id>, never a branch or a commit.
Running agents from herdr
skill/herdr (ank-herdr) is the policy for running this page from a single
orchestrating agent inside a herdr-core terminal
(ADR-2fc9b88cc0bd). The orchestrator claims nothing: it reads ank context,
ank graph and ank status, names the pairs of ready tasks whose scopes
collide, gives every other ready task a worker of its own – one worktree, one
branch and one ANK_AGENT, set with TMPDIR and PATH in the command that starts the
worker, which inherits the herdr-core server’s environment – and
lands the finished branches one at a time. It teaches the ank layer only, and
leaves herdr-core’s own commands to hc --skill. Nothing in it is a verb: ank
still creates no worktree and merges nothing; the orchestrator does, with git
and hc.
Dispatching across repositories
When the work spans several repositories, a backend and the client that calls it, each one keeps its own corpus, its own claims and its own workers, and Several repositories is how one corpus reads another. An orchestrator dispatching across them runs the same loop in each repository, plus four reads that look over the boundary from the one it stands in:
ank status --peersadds each declared peer’s live claims toelsewhere, addressed<id>@<peer>, so a worker about to start inwebsees what is held inapi.ank find --peersandank context --peersadd each peer’s rows and ready tasks, read at the peer’s default branch.ank check --peersmakes an unreadable declared peer a fault, so the orchestrator learns before dispatching that a sibling checkout is missing.ank claim, run by the worker, prints the constraints a peer binds onto the task’s scope in a section of their own, andank donestates which of them moved since.
Claims and writes stay per repository: a worker claims and closes in the
repository its task lives in. A blocked_by naming a peer task releases only
once that task is done on the peer’s default branch, so the orchestrator lands
the peer’s branch first, and the waiting task becomes ready in the order the
merges arrive.
Several repositories
One .ank/ per repository stays authoritative: a corpus belongs to the code it
constrains. Several repositories still share decisions, a backend and the client
that calls it being the usual pair, and ank lets one corpus read another without
ever writing to it (ADR-a1de673043b4). This page walks through the whole of it
with two repositories side by side, /work/api and /work/web, in the order
you meet it: a declaration at both ends, the same peers from every worktree, the
override for a layout that differs, naming an entity of a peer, the peer’s
default branch as the one place it is read, the peer constraints under a claim,
the view across repositories, and what never crosses.
Every block below is replayed against the binary in two scratch repositories.
A binding needs a declaration at both ends
The decision lives in the repository that governs: api declares web as a
peer, by a path relative to its own root, and scopes its ADR into it with
<peer>:<glob>.
$ cd /work/api && ank config peers.web ../web
peers.web (unset) -> ../web
$ cd /work/api && ank new adr --title "Every request carries a trace id" \
--scope "web:src/**" \
--constraint "Every call the web client makes to the API sends an X-Trace-Id header."
created ADR-351131160961 Every request carries a trace id
$ cd /work/api && ank accept 3511
accepted ADR-351131160961 -> 5c88658
That is one end, once committed: another repository reads api from the git
objects of its default branch (ADR-09b985a5627e). Inside web, nothing binds yet, because web has not said it
reads api, and a corpus is never discovered from the filesystem:
$ cd /work/web && ank context src/
> no ready tasks in scope
check in api names the missing half. The end that resolves its own
declaration reads the other end’s config.yml at its default branch, sees no
peer there resolving back, and prints the command that completes the binding.
It is a signal and exits 0, since the repair lives in the other repository:
$ cd /work/api && ank check --kind peer-half-declared
signal: peers.web: peer 'web' declares no peer resolving back to this corpus, so ADR-351131160961 binds nothing there (ank --repo ../web config peers.api ../api)
check: ok — 0 tasks, 1 adr, 1 signal(s)
check in web says the same from the other side when only web declares.
The governed repository declares the governing one, and the constraint is
served where the code it binds lives, by context and by scope alike:
$ cd /work/web && ank config peers.api ../api
peers.api (unset) -> ../api
$ cd /work/web && ank context src/
CONSTRAINTS (1 active)
ADR-351131160961@api Every request carries a trace id
> no ready tasks in scope
$ cd /work/web && ank scope src/client.ts
src/client.ts
ADR (1)
ADR-351131160961@api [accepted] Every request carries a trace id
So the direction is: the governing corpus names the governed one in its scope,
through its own peers.<name>; the governed corpus names the governing one in
its peers.<name> to read it. ank help config says the same in one line.
Every worktree reads the same peers
An agent works in a linked worktree of its own, and a worktree can sit
anywhere: ../api from /work/trees/trace would name /work/trees/api. A
relative peer path resolves against the root of the main checkout, the parent
of the git common directory, so every worktree of web reaches api with no
override (ADR-a14dabe4b259):
$ cd /work/web && git worktree add -q ../trees/trace -b trace
$ cd /work/trees/trace && ank context src/
CONSTRAINTS (1 active)
ADR-351131160961@api Every request carries a trace id
> no ready tasks in scope
When the committed path is wrong here
peers.api ../api in config.yml is a convention: the layout every clone is
expected to follow. On a machine where api was checked out somewhere else, the
peer is not a corpus, and the binding disappears with a warning that names the
fix:
$ mv /work/api /work/backend
$ cd /work/web && ank context src/
warning: peer 'api' at ../api is not a corpus, answered without it (ank config --user peers.98204934184e14045a2158a2bd0f23586745d560.api <path>)
> no ready tasks in scope
The answer is never to edit config.yml, which every other clone shares. The
reader overrides the path in their own corpora.yml, keyed by the identity of
the corpus that declares the peer (its root commit) and the peer’s name
(ADR-da2819aef598):
$ cd /work/web && ank config --user peers.98204934184e14045a2158a2bd0f23586745d560.api ../backend
peers.98204934184e14045a2158a2bd0f23586745d560.api ../backend
$ cd /work/web && ank context src/
CONSTRAINTS (1 active)
ADR-351131160961@api Every request carries a trace id
> no ready tasks in scope
The override is read wherever the declaration is read, including when a peer resolves one of its own declarations back to the reader, and it is never committed.
A peer is a path to a checkout that already exists on this disk, never a URL: no
verb clones, fetches or caches one (ADR-96fe1f9d619a). ank config refuses a
value shaped as a URL when it is written, and names the override instead:
$ cd /work/web && ank config peers.api git@github.com:acme/api.git
error[1]: 'git@github.com:acme/api.git' is a URL: a peer is a path to a checkout on this disk, and ank never clones or fetches one
-> clone it where you want it, then ank config --user peers.98204934184e14045a2158a2bd0f23586745d560.api <path>
Naming an entity of a peer
An entity whose home is a peer is printed <id>@<peer>, and every verb that
reads an identifier takes the same form:
$ cd /work/web && ank show ADR-3511@api
---
id: ADR-351131160961
type: adr
slug: every-request-carries-a-trace-id
title: Every request carries a trace id
created: 2026-10-02T16:35:33Z
author: human:marie
status: accepted
scope:
- web:src/**
constraint: |
Every call the web client makes to the API sends an X-Trace-Id header.
ratified: 65824fc735cf
anchor: 5c88658e1f2b9d0a47c3e6f81b2d94a7c05e3f19
verified:
- by: human:marie
at: 2026-10-02T16:35:33Z
schema: 4
version: 2
---
EDITS (1)
└── 2026-10-02T16:35:33Z human:marie — created (version 0 to 1, produced cd2cc889ba78)
A task can wait on a task of a peer the same way (ADR-c23bef1cc93e). The backend writes the work its client depends on:
$ cd /work/backend && ank new task --title "Accept X-Trace-Id on every route" \
--scope "src/**" --criteria "Every route reads X-Trace-Id" --no-verify
created TASK-e799393f5249 Accept X-Trace-Id on every route
and the client’s task names it in blocked_by:
$ cd /work/web && ank new task --title "Send X-Trace-Id from the client" \
--scope "src/**" --criteria "The client sends X-Trace-Id on every call" \
--blocked-by TASK-e799393f5249@api --no-verify
created TASK-8eed823dc16e Send X-Trace-Id from the client
claim treats it as blocked while the peer’s task is not done, and points at
the task it waits on:
$ cd /work/web && ank claim 8eed
error[7]: TASK-8eed823dc16e is blocked by TASK-e799393f5249@api
-> ank show TASK-e799393f5249@api
An edge that cannot be read holds. A reader that cannot see a peer answers
locally and says so; a blocker doing the same would answer “nothing blocks you”,
which releases exactly the work the edge exists to hold. Remove the override, so
that api is once more not a corpus on this machine, and the claim is still
refused, naming the peer and the command that settles it:
$ cd /work/web && ank config --user --unset peers.98204934184e14045a2158a2bd0f23586745d560.api
peers.98204934184e14045a2158a2bd0f23586745d560.api (unset)
$ cd /work/web && ank claim 8eed
error[7]: TASK-8eed823dc16e is blocked by TASK-e799393f5249@api: peer 'api' at ../api is not a corpus, nothing to read, and an edge that cannot be read holds
-> ank config --user peers.98204934184e14045a2158a2bd0f23586745d560.api <path>
A missing sibling checkout never unblocks work.
Read at the peer’s default branch
A peer is read from the git objects of its default branch: the local branch
first, refs/remotes/origin/<branch> second. The branch its checkout is on, its
uncommitted files and its other worktrees change nothing a reader is served
(ADR-09b985a5627e). Put api back where the convention expects it, and accept
a second ADR there on a branch of its own:
$ mv /work/backend /work/api
$ cd /work/api && git switch -q -c draft
$ cd /work/api && ank new adr --title "Every response echoes the trace id" \
--scope "web:src/**" \
--constraint "The web client logs the X-Trace-Id each response echoes."
created ADR-57539c2a652d Every response echoes the trace id
$ cd /work/api && ank accept 5753
accepted ADR-57539c2a652d -> 2292f47
Accepted and committed, on draft, with draft checked out. In web it binds
nothing yet:
$ cd /work/web && ank context src/
CONSTRAINTS (1 active)
ADR-351131160961@api Every request carries a trace id
TASKS (1)
TASK-8eed [open] Send X-Trace-Id from the client
> no ready tasks in scope (1 blocked)
It binds once it reaches main:
$ cd /work/api && git switch -q main && git merge -q --no-edit draft
$ cd /work/web && ank context src/
CONSTRAINTS (2 active)
ADR-57539c2a652d@api Every response echoes the trace id
ADR-351131160961@api Every request carries a trace id
TASKS (1)
TASK-8eed [open] Send X-Trace-Id from the client
> no ready tasks in scope (1 blocked)
The same rule settles a blocked_by: a peer task releases the edge once it is
done on the peer’s default branch, and done on a branch that has yet to merge
holds it. In api, Omar claims the task the client waits on, on a branch of
their own:
$ cd /work/api && git switch -q -c task/trace
$ cd /work/api && ANK_AGENT=human:omar ank claim e799
claimed TASK-e799393f5249 accept-x-trace-id-on-every-route -> HEAD
Seeing across repositories
Claims stay per repository, so a plain status in web sees only the claims of
web. --peers adds each declared peer’s live claims to elsewhere, addressed
<id>@<peer>, shown and left unarbitrated:
$ cd /work/web && ank status --peers
branch main (default main)
drift none, level with main
identity human:marie (ANK_AGENT)
no claim
elsewhere 1 claim(s) by other agents
TASK-e799393f5249@api Accept X-Trace-Id on every route (human:omar until 2026-11-03T10:19:30Z)
perimeter the whole repository, 2 constraint(s)
queue 0 proposal(s), 0 finished elsewhere
corpus 0 fault(s), 0 signal(s), 1 owing nothing
> ank context
find --peers lists each declared peer’s rows after this corpus’s own, read at
the peer’s default branch together with its claims; context --peers does the
same for the ready tasks:
$ cd /work/web && ank find --peers --type task
TASK-8eed [open] Send X-Trace-Id from the client
TASK-e799@api [claimed:human:omar] Accept X-Trace-Id on every route
The peer constraints under a claim
Omar finishes on task/trace:
$ cd /work/api && echo "// reads X-Trace-Id" >> src/routes.ts && git commit -qam "read X-Trace-Id"
$ cd /work/api && ANK_AGENT=human:omar ank done --proof commit:$(git rev-parse --short HEAD)
proof recorded: commit -> 39c7d60
TASK-e799393f5249 -> done
task/trace has yet to merge, so in web the edge still holds:
$ cd /work/web && ank claim 8eed
error[7]: TASK-8eed823dc16e is blocked by TASK-e799393f5249@api
-> ank show TASK-e799393f5249@api
Once it merges, the claim goes through, and it prints every constraint api
binds onto the claimed scope in a section of its own, naming the peer and the
default-branch commit it was read at (ADR-50952ba5e226):
$ cd /work/api && git switch -q main && git merge -q --no-edit task/trace
$ cd /work/web && ank claim 8eed
claimed TASK-8eed823dc16e send-x-trace-id-from-the-client -> HEAD
PEER CONSTRAINTS (api at e072acf0b34d, 2 active)
ADR-57539c2a652d@api The web client logs the X-Trace-Id each response echoes.
ADR-351131160961@api Every call the web client makes to the API sends an X-Trace-Id header.
context under the claim prints the same section. The claim records that
commit and the hash of each peer constraint it served, outside the frozen hash
of the criterion, and done states any peer constraint added, changed or
retired since, as information: it refuses nothing on that account.
What never crosses
Reading is the whole of it. Three things stay on their own side of the boundary:
- Claims and writes. A claim is a ref in one repository’s
refs/ank/*, and nothing arbitrates across a boundary those refs cannot reach, so claims stay per repository. No verb writes to a peer’s corpus: not a task, not a log entry, not a claim (ADR-a1de673043b4). The task inapiabove is claimed and closed inapi. - An unreadable peer as an answer. An edge whose peer cannot be read is not satisfied, as shown above (ADR-c23bef1cc93e).
- A local glob. A scope entry with no
<peer>:prefix is confronted with this repository’s tree and nothing else:src/**inwebnever covers a path ofapi, however the two are laid out on disk. Only an entry that names a peer reaches into it, through the peer’s declaration, which is what keeps a binding verifiable where the layout differs (ADR-da2819aef598, ADR-96fe1f9d619a).
What crosses is the declaration that a constraint binds a peer, read by the peer. The ADR keeps exactly one home. The keys themselves are in config.yml keys.
How ank compares
Other tools curate a layer over a codebase too. Here is where ank differs from each, and what each comparison costs it.
Against retrieval
RAG answers what looks relevant to this query; ank context src/auth/ answers
what applies to this path. The first ranks by similarity, the second is a
set-membership test, and for a constraint that is the whole point, because a rule
that should have bound but ranked seventh did not bind, and nothing says so. No
embeddings, no index service, no re-indexing per commit.
The cost is real: somebody has to have written the constraint and its scope. Ank replaces the wiki page nobody found, and a corpus nobody curated still needs search.
Against an LLM-maintained wiki
Karpathy’s pattern is three layers (raw sources, a wiki the model owns, a schema file) and three operations: ingest, query, lint. Ank has that shape and differs on what the middle layer is.
A wiki page is derived from sources and can be regenerated if lost; an ADR records a choice that has none. Somebody decided opaque sessions over JWTs, and the record is the only copy, and nothing can re-ingest its way back to it. Hence hash-anchored and signed at ratification rather than rewritten, and a lint that is mechanical, where the wiki’s lint is a model re-reading for contradictions.
Against OKF
Google’s Open Knowledge Format is the closest relative, reached
independently: markdown with YAML frontmatter, no server, no SDK, identity carried
by the path, the format as the contract so producer and consumer stay swappable.
Its v0.2 trust signals are the same instinct as ank’s proofs, and ank has adopted
two outright: the actor convention and verified.
One axis diverges, deliberately on both sides. OKF tells consumers to accept a document whatever it lacks; ank rejects an unknown field. OKF optimises for knowledge crossing organisations, where a rejected document is knowledge lost; ank optimises for a criterion that cannot be quietly weakened, where an accepted-but-malformed file is a rule that silently stopped applying.
Against a process-skills workflow
Matt Pocock’s skills are the richest example: prompts covering the whole cycle, interviewing the human until the spec is precise, cutting it into tickets, driving the implementation test-first, reviewing before merge. The skill is the method, and the agent is held to it while it works.
Ank ships methods too, and holds the other end of them. Seven skills travel
inside the binary, built from skill/: the contract every agent loads, in
skill/SKILL.md, and six siblings beside it, in skill/*/SKILL.md. Five of
them teach one activity of the work each, in skill/plan, skill/drift,
skill/loop, skill/tdd and skill/diagnose, and skill/herdr teaches the
agent orchestrating the others from a herdr-core terminal. A task may name any
sibling, and planning designates one of the five. ank new --method tdd writes the designation into it, ank context
names it and the sibling to load beneath the criterion once the task is
claimed, ank log --method tdd records that it fired, and ank skills counts
designations against firings per method. A name no sibling carries is refused
at exit 7, when the task is written.
No verb enforces one. done leaves method unread: the criterion is frozen
by hash at claim, done runs the declared verifiers itself and records what
they returned, and the proof records the route by which it arrived. A verifier
measures the tree, whatever process produced it, which is the point
(ADR-e4a5a8873fe3). An agent graded on its process learns to fake the process.
An agent graded on the tree has to change the tree.
So the method is taught and the outcome is measured, and the cost is the mirror of retrieval’s: a designation nobody honours is a line of frontmatter, and only the tree says whether the work was done. A team that wants a practice ank does not ship writes a skill for it, and ank still verifies only the outcome.
What it costs to run
Two numbers, each beside its source. The seven skills cost 334 tokens in every
session, which is their frontmatter: the name and description a harness keeps
loaded from the start, the body being read when a skill is invoked. That is 38
tokens for the contract and 41 to 57 for each sibling, counted with cl100k_base
over the seven SKILL.md under skill/ by this command, run at the root of the
repository with tiktoken installed:
python3 -c 'import glob,re,tiktoken; e=tiktoken.get_encoding("cl100k_base"); n=[len(e.encode("".join(re.findall(r"^(?:name|description): .*\n", open(p).read().split("---\n")[1], re.M)))) for p in ["skill/SKILL.md", *sorted(glob.glob("skill/*/SKILL.md"))]]; print(n, sum(n))'
And orientation is bounded at 8000 characters, the context_budget that
.ank/config.yml sets and that the config keys list as its
default.
Exit codes
Every ank verb exits with one of these codes, and the code carries the meaning so a script can route without parsing output. They are stable. ank help --json publishes which verb returns which, under each verb’s refuses.
A refusal writes error[<code>]: <message> on stderr, followed by the exact command to run next; under --json it leaves stdout empty.
| Code | Name | Meaning |
|---|---|---|
| 0 | Ok | the verb answered |
| 1 | Generic | generic error: a call the parser refuses, a file the tool cannot make sense of |
| 2 | NotFound | no such entity, or a prefix matching more than one |
| 3 | Conflict | version conflict: the entity moved under the caller, redo context |
| 4 | Unavailable | the task is unavailable: held by another agent, or finished on another branch; take something else |
| 5 | Proof | a proof is missing, malformed, or of a type this act does not accept |
| 6 | Transition | the act is illegal from the state the entity is in: a frozen field diverged, a transition the state machine does not allow, or a write without the claim it needs |
| 7 | Prerequisite | a prerequisite is missing: the task is blocked, it has no done_criteria, a mandatory flag was not given, or the caller already holds a live claim |
| 8 | Findings | check or review found a fault; a signal alone leaves the code at 0 |
| 9 | Environment | the environment, not the work: sh or git absent, git older than 2.34, $EDITOR unset, a default branch that cannot be determined, a detached proof that never reached the remote, a claim the remote refused, a directory that refuses the lock |
Two of them are the ones an agentic loop must handle: 3 means somebody moved, read again, and 4 means take something else. 6 and 7 are two codes on purpose: in 6 the state forbids what was asked; in 7 the thing asked for is legal and something it depends on is absent. 9 is not a failure of the work, and a pipeline that collapses it into “the command failed” sends somebody to fix sound code.
The file format
For anyone writing a tool that reads or writes .ank/: an editor plugin, an
exporter, a linter, a second implementation.
The format is the specification, and the CLI is a reference implementation of
it rather than a gatekeeper. Nothing here needs ank to be installed or asks
your tool to call it. It is specified by the accepted data-model spec on the
specification page and may still change before 1.0, each
change arriving as a new schema value.
This document is not normative. Section 3 of the specification is: The data
model, one of the spec documents the specification
lists. Where the two disagree the specification is right and this page is a bug. What you will find here instead
is the mechanical half a writer has to reproduce exactly, the field order, the
emission rules and the quoting predicate, which the specification states as
properties rather than as a list, plus a pointer to the section that argues each
one.
Two things settle a disagreement in practice, in this order: the specification,
then crates/ank-core/tests/golden/, which is the suite your implementation can
run against.
Layout
.ank/
config.yml repository settings, named verifiers, and under signers:
the keys allowed to ratify (§8)
entities/TASK-<hex>.md
entities/ADR-<hex>.md
entities/SPEC-<hex>.md
entities/LOG-<hex>.md one entry of the work trace, written once
archive/entities/<ID>.md the cold half, same format, read on demand, never rewritten
log/<ID>.md the previous shape of the trace, read and never written
index.db.<N> derived cache, one per index schema N, belongs in .gitignore,
never a source of truth
Flat, deliberately: attachment happens through the scope field, not through
location (§3). A file’s name is its id; nothing resolves through the directory
tree.
One directory for every kind. The kind is already in the id prefix, which is
already in the file name, so a per-kind subdirectory would state it a third time
and the only thing a third copy can do is disagree with the first two (§6). The
path is computed from the id with no lookup: every entity is at
.ank/entities/<ID>.md, whatever its kind, log entries included.
An entity’s entries are a query, not a path. They are the entities of kind
log whose about names it, so finding them means reading the directory, or
your own index, where the previous shape let you compute one address. That is the
one thing this layout gives up, and it is deliberate (§3).
The layout is fixed, not configured. A layout read from config.yml would
mean your tool has to parse the configuration before it can find a file, and the
conformance suite at the end of this page would stop being something anybody can
run against a directory.
The archive is the second root, and the only other one. .ank/archive/ holds
the cold half of the corpus at archive/entities/<ID>.md, flat and in the same
format by the same rule as above: one file per entity, the file name is the id,
readable with no parser and no tool. It is a directory rather than a packfile or
a walk of git history because either of those would put a parser, or git,
between a reader and a file.
A tool reading .ank/ needs three things from it. It is read on demand and
never by default: the listing, the prefix resolution and the load of the hot
corpus answer exactly what they answered before the archive existed, so a tool
that ignores it is still correct, only blind to the cold half. It is resolved
against both roots wherever an id is resolved, so a reference, a supersession,
a blocker or an entry’s subject naming an archived entity names something, and a
scope pointing at .ank/entities/<ID>.md for an entity since archived is not
dead; an id present in both roots is one entity, read hot. And an archived file
is never edited: it is parsed once when it arrives, the content hash recorded
then is its digest and is never updated, and a file whose bytes stop matching is
a fault rather than a change to take in. That digest is recorded in
index.db.<N> and in no file, which is the one place the cache is load-bearing; the section on
what is derived says what deleting it costs.
A writer moves files there with ank archive and never by hand; the move
commits nothing, and what the hot corpus holds is settled by a human reading a
diff.
The previous layouts, and the window for them. Corpora written before the
flat directory are at tasks/TASK-<hex>.md and adr/ADR-<hex>.md, with the log
inside the task body; corpora written between that revision and this one carry
the trace as one file per entity under .ank/log/. A reader must accept all of
them; a writer must never produce them. A corpus holding several layouts is
one corpus, and nothing in it is counted twice: if an id resolves in both, decide
and document which wins rather than silently preferring one, and an entity’s
entries are the union of the two sources. ank check reports a corpus still in a
previous shape as a signal, not a fault, naming the command that moves it: such a
corpus parses, round-trips and answers every verb.
This dual read is a window, not a feature. It exists for the release across which an existing corpus moves, and a new tool has no reason to write anything but the flat layout.
Identifiers are TASK-, ADR-, SPEC- or LOG- followed by exactly 12
hexadecimal characters, lowercase on output and accepted in either case on
input. They hash the act of creation (timestamp, identity, title, entropy)
never the content, so they survive every edit (§3). A tool that resolves short
prefixes must require at least 4 hex characters and must fail on an ambiguous
one, listing the candidates. Guessing is the one behaviour the format rules out
by name.
The shape of a file
Markdown with YAML frontmatter, UTF-8 without BOM, LF line endings:
---
<frontmatter>
---
<body>
The delimiters are exact: the file begins with ---\n, and the frontmatter ends
at the first \n---\n. Everything after that separator is the body, kept
verbatim, byte for byte. The body is free-form markdown and carries no
convention at all: the log, the one convention that might sit there, is an
entity of its own.
Unknown fields are rejected, not ignored. That is what turns a typo like
priorty: into an error instead of a silent loss, and it is the reason the
schema rule in the next section exists at all.
Fields, in canonical order
Canonical form is a fixed field order, and a serializer that emits the right fields in the wrong order produces a non-canonical file. The order is not alphabetical and not negotiable; it is the one the registry declares.
A kind is declared once, as a row of a registry: the name written in type,
the id prefix, the status values, which fields are required and which optional,
and the canonical order (§3). Entity fields is that registry
printed, generated from the table the binary reads and writes with: every kind,
every field in order, its emission form, whether it is always emitted, and the
values an enum field takes. Reproduce it as data, a table your serializer walks,
rather than as one emitter per kind; the order is the single thing most easily
lost by rewriting two straight-line emitters as a generic loop, and it is what
the round-trip rests on.
An unknown kind is rejected naming the kind, not naming the first field it
happens to carry. Inside a known kind, an unknown field is still rejected. The two
refusals answer different questions: priorty: in a task is a typo, and
type: epic is a document your tool does not know how to read.
Task
A proof entry emits its own keys in order: type, ref, then tree,
criteria, verifier, via, reused and by, each omitted when absent. The
values type and via take are listed with the fields. via
is the route by which the entry arrived, and its absence means the entry was
written before the field existed, never a fourth route. reused and by mark
an entry done took from a recorded run rather than from an execution for this
task: reused says where from, local for the run registry, and by names the
identity that ran it. Their absence means the entry was run for its task.
A verified entry emits by, then at. Both are required in an entry that
exists at all, an entry missing either being rejected, while the list itself is
optional on every kind.
ADR
amends names the ADRs this one changes in part, between see and the
succession. It is a flow list of entity ids, omitted when empty like a
spec’s references, and it retires nothing: each ADR it names stays accepted and
binding for everything the amendment does not touch, where supersedes replaces
the whole of one (ADR-9ee76b578257). A reader resolves each entry as it resolves a
reference, following the succession to its end; an entry naming an absent
entity, a kind other than adr, or an ADR that is not accepted is a finding
there rather than a parse error here.
enforced_by names what holds the rule mechanically, between see and
amends (ADR-25584c56c1a7). It is a block sequence of <path>#<symbol>
entries, each a file the tree counts and a symbol that file contains – a test
function, a verifier name in a workflow, a check rule – and it is omitted
when empty, so an ADR nothing is declared to hold is byte-identical to one
written before the field existed. It sits outside the ratification anchor,
which hashes constraint and scope alone, so it is written on an accepted
ADR as on a proposed one, by ank new adr --enforced-by and by ank amend --enforced-by and --drop-enforced-by. A reader takes each entry as a string:
a path no tracked file matches, or a symbol the file does not contain, is a
signal naming the entry rather than a parse error here. context serves an
ADR carrying the field by its title, with its entries, in both modes, and the
field confers nothing: the rule binds whether or not something enforces it.
Spec
An ADR without its constraint, and the absence is what makes it a kind of its
own: a spec describes where an ADR binds, so nothing in it is ever injected into
an agent’s context (§3).
The anchor differs from an ADR’s in what it covers and in nothing else: a spec
has no field carrying its authority, so ratified is taken over the body and
scope together. A tool that verifies one hashes the body as it hashes a
constraint, under the normalisation below.
references names the documents and decisions this one rests on, in the position
blocked_by takes on a task: immediately after the perimeter, before the
succession. It is a flow list of entity ids and it is omitted when empty, not
written []: a task always states whether it has blockers, and a document that
cites nothing has nothing to state. A reader resolves each entry against the
corpus; what a checker then reports of it is §4’s business and not the format’s,
and an entry naming a kind other than spec or adr is a finding there rather
than a parse error here (§3).
Log entry
No status, and that is not an omission: an entry is written once and has
nothing to transition to, so the registry declares the kind without one and your
parser must not require it. version stays, and on this kind it is a detector
rather than a counter: an entry above 1 has been rewritten, which the format
says should not happen.
records marks an entry a verb wrote, not a holder. Absent, the entry is
work. The values known to this build are listed
with the fields.
edit and create share one grammar, which carries the versions the write
moved between and the hash of the content it produced. Both of these were
written by the binary:
+scope docs/** (version 2 to 3, replaced 80bdeffde4e7, produced a06b2b863b0e)
created (version 0 to 1, produced f9b82c19eaec)
edit is a change of content outside a status transition, and names the fields
it changed and the hash of the state it replaced. create is the record new
writes at birth: version 0 is the state before the file existed, and replaced
is absent because nothing was. An entry about a log entry never carries
create, since an entry is the record.
method carries neither, and that is why the grammar above is a property of
two values rather than of the field. ank log --method <name> writes it to
record that a sibling skill opened under a claim, and the entry’s title is the
name alone:
tdd
A value your reader does not know is read as machinery and never refused.
Optional fields are omitted, never emitted empty. An entity with no author
serialises without the key at all. Writing author: with nothing after it would
change every older file on its first rewrite, and the round-trip guarantee below
forbids that.
Actors
Every field naming an actor, author and the by of a verified entry, is
typed: human:<id> is a person, <producer>/<version> is an agent,
process:<id> is an automated process (§3).
A value that does not match the convention is not a parse error. Your parser
must accept it; reporting it belongs to a linter, and ank check reports the
whole pre-convention set once for the corpus rather than once per file. This is
the one place where being strict would be wrong: the convention postdates most
of the author values in an existing corpus, and a parser that refused them
would lock those files out of their own format. Write typed actors; read
anything.
Emission rules
Literal blocks carry the multi-line fields, done_criteria and
constraint. Two spaces of indent, and the chomping indicator records whether
the value ends in a newline: | when it does, |- when it does not.
done_criteria: |
Auth integration tests pass, and no reference to
jwt.verify remains in src/auth/
Flow lists carry references: blocked_by: [TASK-51c2a7f0b3d9],
verify: [auth-tests, no-jwt].
Block sequences carry scope, proof and verified, two spaces of indent:
scope:
- src/auth/**
- src/middleware/session.ts
verified:
- by: human:marie
at: 2026-07-27T09:40:00Z
Scalars are emitted bare when that is unambiguous and quoted otherwise,
conservatively: when in doubt, quote. The reference implementation emits a
scalar bare only when all of these hold: it is non-empty; it contains no
newline, no ": " and no " #"; it does not end in : or a space; it does not
begin with any of
- ? : # & * ! | > ' " % @ ` [ ] { } ,
or a space; it is not one of null, ~, true, false, yes, no; and it
does not parse as a number. Otherwise it is double-quoted, with \, " and
newline escaped.
“Parses as a number” is Rust’s str::parse::<f64>, and naming the parser is
the point: it is wider than YAML’s own number grammar, so a writer that
substitutes its own language’s parser agrees everywhere except where it matters.
Measured through the binary, these titles come back double-quoted
inf INF infinity Infinity nan NaN NAN 1e5 +3 .5 1. 007
and these come back bare
0x10 5_000 1_0 1e
The infinities and NaN, in any case, are what another parser will miss;
5_000 and 0x10 are what it may wrongly catch.
Reproducing this predicate exactly is what makes a third-party writer round-trip.
The round-trip guarantee
serialize(parse(x)) == x, byte for byte, when x is in canonical form
Valid but non-canonical input (another acceptable YAML form, superfluous quotes, CRLF) is read correctly and normalised on first rewrite (§3). That is what lets a human or a third-party tool write a file without knowing the canonical form, without making that form an authoritative variant.
Read is not the same as accepted. A file that parses but does not round-trip
is a fault under ank check, reported as non-canonical form (round-trip differs) and exiting 8. Measured by double-quoting one bare title in an
otherwise canonical file: ank show goes on printing the entity unchanged while
check turns red on it. A third-party writer that does not reproduce the
emission rules therefore writes a corpus that reads perfectly everywhere and
fails its own repository’s check.
CRLF is read, never written. A parser must accept it; a serializer must not
produce it. A ---\r\n diagnosed as “missing frontmatter” sends the reader
looking for a delimiter that is right there, so normalise line endings before
splitting, not after. ank init writes a .gitattributes carrying
.ank/** text eol=lf, because on Windows git would otherwise convert back on
every checkout what the tool has just normalised.
CRLF is the one exception to that fault. When dropping the carriage returns
leaves exactly the canonical form, the content is right and only the checkout is
wrong, so check reports a signal at exit 0 instead, naming git config core.autocrlf input. Measured on one file taken through all three states: LF
and canonical is silent, the same bytes at CRLF give the signal and exit 0, and
a genuinely non-canonical file is the fault whichever line endings it carries.
Reading a version you do not know
schema is the format version, and a tool declares a range of versions it
reads, not a single one.
The version the reference implementation writes, and the range it reads, are printed with the fields.
Version 3 carries the log leaving the entity body and the verified list with
its typed actors. The flat layout arrived in the same revision and carries no
bump of its own: it moves files, not fields, so a reader that finds the file
finds every field it already knew. Version 4 carries one field, records on a
log entry.
Both bumps are the case the field exists for, and it is the same case twice. A
reader that does not know the log has left the body opens a task file, finds no
## Log section, and shows an empty history for a task that has one, silently,
with nothing reading anywhere as an error. A reader that does not know records
drops it on the next rewrite, and an entry written to stay out of the work trace
silently rejoins it. Refusing on the version says the one true thing before
either happens.
A bump is paid for by the builds already distributed, and it is worth saying where. Every entity a verb writes carries the version that build writes, so a corpus edited by a build at 4 becomes unreadable to a build at 3 one entity at a time: the older build warns once that the schema is ahead and every listing then answers as if those entities were not there. That is the designed behaviour of the range and not a side effect of it.
Older is a promise the format keeps: every field introduced after version 1 is optional at parse time, and its absence means “written before this existed” rather than “invalid”. A corpus is never migrated by a tool that refuses to read it.
Newer is refused, and refused on the version rather than on the first field it
does not recognise. Since unknown fields are rejected, a tool that checked
only its own version would report a file one version newer as unknown field
author, and its reader would go hunting for a typo. Naming the version says
the one true thing: this file is newer than this tool. The argument is in §3.
A new kind carries no bump either, and needs none: an unknown kind is
rejected naming the kind, which is the same honest refusal by a different
mechanism, so a tool that does not know spec or log stops on that entity and
says which kind stopped it. The spec and log kinds are therefore readable at
any version in the range, and the one case no bump could reach, a reader that
opens a task file alone and looks for its entries where an older shape kept them
is covered by continuing to read that shape for one window (§6).
The log
The log is neither a section of the body nor a file per entity: an entry is an
entity. It carries the instant in created, the identity in author, the
message in title, and what it is about in about, and it is written once and
never modified. A correction is a new entry naming the one it corrects.
The line grammar has not changed, and it is now how an entry is printed
rather than how it is stored: a dash and a space, the timestamp, a space, the
identity, a space, an em dash, a space, the message. ank log prints each
entry that way, after its short id and two spaces:
LOG-9cfb - 2026-07-26T14:02:11Z claude-code/1.4.2 — jwt.verify removed from session.ts
So an entry written under either previous shape reads across unchanged and nothing about it is reinterpreted: only where it lives has moved, twice.
A message longer than a line is split across title and the body, and the
split is lossless. A message of at most 100 characters is the whole of the
title, and the body is empty. 100 itself is included, so a message of exactly
that length does not split. Longer, the title runs to the last space at or
before character 100 and at or after character 50, the limit itself where there
is no such space and the first newline where one comes earlier, and the body is
a newline, the remainder verbatim, a newline.
The message is the exact concatenation of the two. The separating space belongs to the remainder, so joining inserts nothing; recovering the remainder removes exactly one newline at each end and never trims. Given this 111-character message
discrepancy: the criterion assumes merge=union is configured for the log path, and .gitattributes declares none
ank log stores
title: "discrepancy: the criterion assumes merge=union is configured for the log path, and .gitattributes"
whose value is 97 characters, because the cut is the last space at or before character 100, and with the body
\n declares none\n
which is a newline, the remainder, a newline. The remainder opens with the space that separated the two words, so a reader that concatenates the title with it gets the message back byte for byte: 97 + 14 = 111. A body that is not of that shape carries no remainder, and the message is the title alone.
The rule exists because the title is what every lister prints, on every kind: a
2000-character title is one enormous quoted scalar and it is printed in full
wherever entities are listed. So print the head of the message with a trailing
… when there is more, and let a reader ask for the entry itself to see the
whole. Machine output carries the whole message: a parser reads no page.
Any kind may be logged against, whether a task, an ADR or a spec, and an entity with no entries has an empty log, never an error. Do not write one to record that there is nothing to record.
Order an entity’s entries by created, then seq, then the identifier. All
three are read off the entity; none of them is the file name, the directory
order or anything else outside it.
seq exists because a timestamp is not an order. created has one-second
resolution, and writing an entry costs a few hundred milliseconds, so several
entries inside one second is the ordinary case: measured on four entries written
about one task, 12 runs of 12 put all four in the same second, and 10 of those
12 came back in the wrong order when the identifier was the only tiebreak: a
hash of the act of creation, which carries no order at all. An append-only file
carried insertion order for free; a set of files does not.
When you write an entry, set seq to one more than the highest seq you can
see on the entries already about that subject, or 0 if there are none. That
requires reading them first, which is a bounded read and the same query you need
to display them. Two writers who cannot see each other will produce the same
value; that is correct rather than broken, since they were concurrent, created
separates them when their instants differ, and the identifier settles the rest.
Never treat equal seq as a conflict, and never rewrite an entry to renumber
it.
An entry read out of one of the previous layouts takes the 0-based index of
its line in the file, which is the order that file recorded. Since created
is read first, a file whose lines contradict their own timestamps is reordered
by the timestamps: measured on the reference corpus, one file of 178 stores its
lines newest-first. The guarantee is therefore exact: across distinct instants
the timestamps order the entries, and within one instant the line order does.
Writing an entry is not a write to the entity it is about. It writes no
frontmatter there, bumps no version there, and touches no file carrying a
frozen field. An entity file changes only on a real transition. That property is
the reason the log left the body, and a tool that records an entry and rewrites
the entity has given it up.
Two entries are two files, which is why there is no merge rule for the log.
No rule unions log sections by timestamp, and the reason once recorded for
having none was wrong: git does not union two appends by
itself, it conflicts on them, unless a repository configures merge=union for
the path (§7). What has been protecting the corpus all along is one file per
entity, and an entry that is an entity extends that to the trace: there is no
file for two parties to append to.
One convention lives in the message, and it is where a disproved criterion is
recorded. A message opening with discrepancy: says that the frozen
done_criteria of that task rests in part on a false premise, and states what
was measured instead (§3):
LOG-d41c - 2026-08-14T18:16:03Z claude-code/03fd — discrepancy: the criterion assumes tests/skill.rs passes untouched; two tests there read `ank help`
It is a convention on the message and never on the grammar, released: <reason>
being the same kind and older, so it costs no field, no schema bump and no
migration, and every log a corpus already holds stays valid. It changes nothing
mechanically: the criterion is untouched, its hash still anchors it, and done
still verifies against that hash. A tool that reads the log should surface such
an entry; none should ever read it as permission to accept less.
The log is a work trace, not proof: nothing authoritative is anchored in it, which is why there is no chained hash over it (§3), and which is what makes an entry written by a second party harmless. A tool may read entries and may add them; it should never reorder or rewrite one.
In a corpus in the earliest layout, the log is a ## Log section at the end of
the task body; in the one between, it is a file per entity under .ank/log/,
one line per entry. Both carry the same line grammar. Read them there; write
neither.
What is derived, and must never be stored
A file says less than the corpus does, on purpose. Four things are computed at read time and have no field:
- Blocked. A task is blocked if and only if at least one of its
blocked_byis notdone.closeddoes not unblock. There is noblockedstatus to go stale. - Reverse edges. What a task unblocks is derived by walking
blocked_byacross the corpus. A stored reverse edge is a second copy that can disagree with the first. - The claim. Never in the file. See below.
- The index.
index.db.<N>is a cache rebuilt from the files, and every query it answers is answered again once it has been rebuilt, with one exception, which is the next paragraph.
One file per index schema (ADR-3db9735a7036). N is the index schema of
the binary reading it, and a binary opens, rebuilds and writes only its own
file: two binaries of different schemas on one corpus, the one on PATH and
the one a worktree just built, each keep their own index warm instead of
dropping each other’s. Every other index.db*, the unsuffixed .ank/index.db
a release before the split wrote included, is left byte for byte as it is,
disposable like the rest and ignored by the same .ank/index.db* line. When a
binary creates its file, it takes the archived digests from the newest file of
an older schema present, or from .ank/index.db where there is none, so an
upgrade does not reset what the next paragraph is about.
Deleting index.db.<N> loses one thing, and it is the one thing in there that is
not derived from the files: the digest an archived file arrived with. An
archived entity is never edited, and that is enforced by comparing the file’s
bytes against the hash recorded when the index first read it. The corpus has
nowhere to keep that hash, since the archived file cannot carry a digest of
itself, so it lives in the cache and nowhere else. Measured on a corpus of four archived
entries: appending a line to one of them makes ank check exit 8 naming the
file; rm .ank/index.db* and the same check exits 0, on that run and on every
run after it, because the rebuild takes the changed bytes as the digest.
So “deleting it is always safe” is true of everything a reader queries and false
of archived integrity. A tool that intends to say anything about an archived
file’s bytes must treat the cache as state, and the only authority that survives
its deletion is git: git checkout -- .ank/archive/entities/<ID>.md restores the
file, where a reindex only re-blesses whatever is there.
What lives outside the files
A tool that reads only .ank/ sees the durable state and none of the
coordination. Two things are deliberately elsewhere, and both matter if your
tool intends to say anything about them.
Claims are git refs, one per task, at refs/ank/claims/<task-id>. The ref
has two states and the record it points at says which: a claim (holder,
expiry, the frozen criterion hash, the hash of applicable constraints) or a
completed record (commit, branch, identity, timestamp) written by done. A
task that is in_progress in the file with no ref behind it is simply one whose
claim expired: legal, and re-claimable (§7).
A ratification is a tag object, at a ref (ADR-5e47007a75be). accept writes
ratified: into the entity, and the copy that counts is in an annotated tag
object that refs/ank/ratify/<id> points at, because the copy in the file is
written by whoever writes the file. The tag object holds:
object: the blob of.ank/entities/<id>.mdasacceptwrote it, so the exact bytes made binding are readable withgit cat-file -pand nothing else;tag:ratify/<id>, andtagger: git’s identity and the instant;- a message whose subject is
ratify <id>, then the lines a ratification carries:constraint+scope: <hash>orbody+scope: <hash>(below),by: <actor>, andsupersedes: <id>where one applies; - a signature, git’s own under whatever
gpg.formatthe repository uses, where the repository signs (§8), and none where it does not.
anchor: names the tag object, beside ratified:. A commit could not be
named by the file it ratified, since a commit cannot contain its own
identifier; a tag written before the file can. The order is what follows from
that: the blob is the file with every field accept writes except anchor,
which cannot be among the bytes the tag it names was made from, and the file
accept leaves is that blob plus the one anchor: line. The field holds a git
object name, lowercase hex; whether the object exists and a ref points at it is
a question for the repository, not for the parser. An entity whose anchor is a
commit carries no anchor: at all, and it reads and rewrites unchanged.
The recipe reproduces one without ank, which is what makes it a standard and
not an implementation detail. Four plumbing commands, run on the file accept
writes before it adds anchor::
git hash-object -w .ank/entities/<id>.md # the blob
git tag -s -m 'ratify <id>' -m '<lines>' ratify/<id> <blob>
git update-ref refs/ank/ratify/<id> <tag> # <tag>: rev-parse ratify/<id>
git tag -d ratify/<id> # the object stays, the tag name goes
tag -s is the one command that signs; in a repository that does not sign it is
tag -a, and the object carries no signature. The temporary
name under refs/tags/ exists for the instant between the second and the
fourth command, because a ratification is not a release and must not look like
one to a forge. The ref travels with refs/ank/* (§7), pushed with
compare-and-swap. A verifier judges the signature with git verify-tag against
the keys declared under signers: (§8), and reads every ratification of a
corpus in one git for-each-ref refs/ank/ratify and one git cat-file --batch.
A worked vector follows the two hashes.
An anchor made before that decision is a commit message, and it stays one: it
is never rewritten, and accept --reanchor is the one act that moves it into a
ref, under the same hash and a new signature. Such a commit has the subject
ratify <id> and a body carrying the same lines a tag message carries. The file
cannot name the commit, so the subject is the only pointer there is (§3), and a
verifier asks the history only for an anchor the refs do not carry.
A verifier finds it by subject, over the whole history, with no path restriction:
git rev-list --full-history HEAD
reading each commit’s subject and taking the first that is ratify <id>. The
walk is newest-first, so a decision ratified twice answers with the newest.
--full-history because path simplification exists to explain a tree’s final
state and is free to drop a commit that a merge made redundant; dropping the
ratification would report a perfectly frozen decision as unverifiable. No path
restriction because the subject is the key, and a subject is independent of
where the file sits. Measured on ank’s own repository, where ADR-01b6dd05f0db
was ratified at .ank/entities/ and later moved to .ank/archive/entities/: a
walk restricted to its current path returns no ratify commit for it at all,
where the unrestricted walk returns exactly one. A verifier that restricts by
path reports that decision unverifiable, which is the one verdict that looks
like an answer and is not.
One walk answers the whole corpus, and that is also why it is one walk: the question is asked once per decision and again for every task a decision bears on, so a search per entity is a process count that grows with the corpus.
accept also records who ran it, as a verified entry naming the typed
actor and the instant. The signature on the ratification tag says that a key
authorised the act, which is true of an agent typing under a cached passphrase as
much as of a human at a keyboard, so the entity carries the actor as well. It is
a record and not a defence: an actor value is declared and never proved, exactly
as author is, and what it buys is that an honest ratification leaves a trace a
reader can tell apart. ank check reports a decision whose ratifying actor is
its own author as a signal, never as a fault, because a solo maintainer does that
legitimately.
The key names what was hashed, and there are two because there are two kinds
that carry an anchor: constraint+scope: <hash> on an ADR, body+scope: <hash>
on a spec. A spec declares no constraint, that absence being what justifies the
kind, so the authority is carried by the whole document, and a message claiming
constraint+scope over one would name a field the file does not have. A reader
accepts either key; a writer writes the one its kind carries.
The two hashes
Both are SHA-256 over normalised text, displayed as the first 12 hex characters, and a verifier accepts the short form or the full one.
Normalisation is what makes a hash insensitive to editing noise without ever tolerating a change of meaning: CRLF becomes LF, trailing whitespace is stripped from each line, trailing blank lines are removed.
- The criterion freeze, recorded by
claim:hash(normalize(done_criteria)). - The ratification anchor, recorded by
accept: the normalised anchored text, a newline, then eachscopeglob trimmed and followed by a newline, and then the whole buffer normalised a second time before it is hashed, which removes the newline the last glob was just given. The anchored text is an ADR’sconstraintand a spec’s body, which is the one place the two anchors differ and what the message key above says.
That second normalisation is the entire difference between a tool that agrees
with ank accept and one that does not, so the recipe is worth writing out. The
bytes hashed are
normalize(text) + "\n" + globs.join("\n")
with no trailing newline, the globs trimmed and in the order the file lists them.
A worked vector, taken from a real accept. An ADR whose constraint is
Never Y and whose scope is the single glob src/**, ratified by the binary,
produced the tag message
constraint+scope: 33045e58af8d
and printf 'Never Y\nsrc/**' | sha256sum gives 33045e58af8d…. Keep the
trailing newline the per-glob rule appears to ask for and the same decision
hashes to b88d9f81eb08, which no ratification anywhere carries: an
implementation off by that one byte reports every ADR in the corpus as diverged.
Several globs join the same way: Rule two. over src/** and docs/**
recorded 16a85fda1d17, which is printf 'Rule two.\nsrc/**\ndocs/**'.
The same anchor as a tag, built from the recipe. That line is the one a
ratification commit carried before ADR-5e47007a75be, unchanged. The tag below is
the recipe run by hand, with the identity and
the instant fixed so that every object name below is reproducible. The file is the
ADR above as accept writes it, before anchor::
$ git hash-object -w .ank/entities/ADR-a0c4e6f8b2d1.md
6e79bc4532a163811397b05d537027350cc0e8e0
$ git tag -a -m 'ratify ADR-a0c4e6f8b2d1' -m "$(printf 'constraint+scope: 33045e58af8d\nby: human:marie')" ratify/ADR-a0c4e6f8b2d1 6e79bc4532a163811397b05d537027350cc0e8e0
$ git rev-parse ratify/ADR-a0c4e6f8b2d1
ad7ac6bdac0374ad4148e7c2d0330b90a94e96df
$ git update-ref refs/ank/ratify/ADR-a0c4e6f8b2d1 ad7ac6bdac0374ad4148e7c2d0330b90a94e96df && git tag -d ratify/ADR-a0c4e6f8b2d1
Deleted tag 'ratify/ADR-a0c4e6f8b2d1' (was ad7ac6b)
$ git cat-file -p refs/ank/ratify/ADR-a0c4e6f8b2d1
object 6e79bc4532a163811397b05d537027350cc0e8e0
type blob
tag ratify/ADR-a0c4e6f8b2d1
tagger marie <marie@example.com> 1792249200 +0000
ratify ADR-a0c4e6f8b2d1
constraint+scope: 33045e58af8d
by: human:marie
and the file accept leaves carries the object name the ref holds as its anchor:
$ echo "anchor: $(git rev-parse refs/ank/ratify/ADR-a0c4e6f8b2d1)"
anchor: ad7ac6bdac0374ad4148e7c2d0330b90a94e96df
on the line between ratified: and verified:. The tag is unsigned here
because the recipe ran with -a; with -s the message gains the signature
block and the object gains another name, which is the point of naming it. A
reader compares the constraint+scope line of the object the ref points at, and
never the copy in the file.
Freezing is verifiable, not defended (§2). Your tool can rewrite any field in any file; what it cannot do is make the recorded hash agree afterwards.
Concurrency
version is an integer incremented on every write, and it is an intra-tree
compare-and-swap: read, compare, write, under a file lock, with the write done
atomically (write-then-rename). It protects one working tree: a human and an
agent sharing a checkout. Between clones, git’s own compare-and-swap at push
time is what arbitrates (§7).
Conformance
crates/ank-core/tests/golden/ is a reusable suite, and it is small enough to
port in an afternoon:
-
valid/: every file must parse, and re-serialising it must reproduce the input byte for byte once it is in canonical form. Two fixtures are not, and they are the two shapes the format reads and never writes, so for those two the assertion is against the normalised input rather than the bytes on disk:Fixture What it is not canonical in What the comparison normalises TASK-c71f0e5a9b23.mdCRLF line endings back to LF TASK-9dd8e04b1358.mdits closing ---is the last bytethe final newline is put back Exactly one of each, and the suite asserts the counts rather than the files: a
.gitattributesthat converted the first, or an editor that added a newline to the second, would otherwise leave a green test covering nothing. The second shape can only be an entity with an empty body, since a body puts the newline after the delimiter by construction.Every version in the reader range carries a fixture, 1 through 4, and the suite fails a bump shipped without one. The old ones are there to stay: a file written before a field existed must survive a rewrite unchanged, and if one of them moves, the version bump has silently become a migration. Every kind carries one too: a log entry is an ordinary entity fixture like any other, and a fixture in the previous shape, a whole log keyed by the id of the entity it belongs to, stays for as long as that shape is read.
-
invalid/: every file must be rejected with the right error, not merely rejected. Seventeen fixtures, each naming a distinct failure:Fixture What must be refused no-frontmatter.mda file with no frontmatter at all unterminated-frontmatter.mdan opening ---with no closing onebad-id.mdan identifier that is not 12 hex characters bad-schema.mda schema outside the range, naming the version found bad-status.mda status the kind does not declare bad-glob.mda scopeentry that is not a valid globmissing-scope.mda scopewritten[]type-mismatch.mdtypedisagreeing with the id prefixunknown-field.mdan unknown field inside a known kind unknown-kind.mda kind the registry does not declare criteria-by-without-criteria.mdcriteria_bywith nodone_criteriabad-proof-via.mda viaoutside the closed setverified-without-at.mda verifiedentry withbyand noatspec-with-constraint.mda constrainton a speclog-without-about.mda log entry with no aboutlog-without-seq.mda log entry with no seqlog/bad-log-line.mda log file holding a line the grammar refuses Most of them assert on more than the error’s type, and that is where a permissive implementation is actually caught.
unknown-kindmust nameepic, not the id prefix and not the first field an unknown kind happens to carry: a reader told “invalid identifier” goes hunting for a typo in the hex.bad-schemamust name the version it found.bad-proof-via,verified-without-at,spec-with-constraint,log-without-aboutandlog-without-seqmust each name the field,spec-with-constraintnamingconstraintrather than the kind, because the field is the one a spec exists in order not to carry.bad-log-linemust name line 2: the file’s other two lines are entries the grammar accepts, so a fixture whose every line were bad would pass for a reader that gave up on the first one.The first two rows are one distinction and not two cases of one error, which is why both fixtures exist.
no-frontmatter.mdnever opens a frontmatter;unterminated-frontmatter.mdopens one and never closes it, and its refusal names the closing delimiter: unterminated frontmatter: no closing---after the opening one. Telling a reader that a file which plainly starts with---must start with---sends them looking for a delimiter that is right there, which is the same hour---\r\nalready cost. A reader that folds the two into one error passes this fixture and fails the person holding the file.One case per kind at least, or a kind ships with its strictness untested. The list grows with the format; what does not change is that a test asserting only that parsing returned an error passes for the wrong reason forever.
There is no invalid fixture for a malformed actor. That is deliberate and is the one place strictness is wrong: the convention is checked, never parsed (above).
The second half is where a permissive implementation is caught. Accepting a file the format rejects is the failure mode that spreads, because the corpus it writes still looks fine until something else reads it.
Where to go next
- The specification: each spec declares in its own body which sections it carries – §3 for the data model and canonical form, §6 for storage, §7 for the coordination plane, §8 for identity and ratification.
- Entity fields and config.yml keys: the tables, generated from the registry the binary reads with.
- The quickstart: if you also want to use the tool.
Entity fields
Every kind, with its fields in canonical order: the kind registry the binary reads and writes with, printed. The file format says what the order and the emission forms mean; this page is the table it describes.
This build writes schema 4, and reads schema 1 through 4. A file declaring a newer schema is refused on its version, never on the first field it does not recognise.
Task
type: task, ids TASK-<12 hex>.
| # | Field | Emission | Presence | Values | Notes |
|---|---|---|---|---|---|
| 1 | id | bare | always emitted | TASK-<12 hex> | |
| 2 | type | bare | always emitted | always task | |
| 3 | slug | scalar | omitted when absent | cosmetic, never resolved on | |
| 4 | title | scalar | always emitted | ||
| 5 | created | scalar | always emitted | ISO 8601, always UTC with the Z suffix | |
| 6 | author | scalar | omitted when absent | a typed actor; absent means the entity predates the field | |
| 7 | status | bare | always emitted | open | in_progress | done | closed | |
| 8 | scope | block sequence | always emitted | globs, never empty | |
| 9 | blocked_by | flow list | always emitted | task ids, [] when empty | |
| 10 | done_criteria | literal block | omitted when absent | frozen by hash at claim | |
| 11 | criteria_by | bare | omitted when absent | creator | claimer | invalid without done_criteria |
| 12 | verify | flow list | omitted when absent | verifier names config.yml declares | |
| 13 | method | scalar | omitted when absent | a sibling skill the binary carries | |
| 14 | proof | block sequence of maps | omitted when absent | keys in order: type, ref, tree, criteria, verifier, via, reused, by | |
| 15 | verified | block sequence of maps | omitted when absent | readings: by, then at, both required in an entry | |
| 16 | schema | integer | always emitted | ||
| 17 | version | integer | always emitted |
ADR
type: adr, ids ADR-<12 hex>.
| # | Field | Emission | Presence | Values | Notes |
|---|---|---|---|---|---|
| 1 | id | bare | always emitted | ADR-<12 hex> | |
| 2 | type | bare | always emitted | always adr | |
| 3 | slug | scalar | omitted when absent | cosmetic, never resolved on | |
| 4 | title | scalar | always emitted | ||
| 5 | created | scalar | always emitted | ISO 8601, always UTC with the Z suffix | |
| 6 | author | scalar | omitted when absent | a typed actor; absent means the entity predates the field | |
| 7 | status | bare | always emitted | proposed | accepted | superseded | |
| 8 | scope | block sequence | always emitted | globs, never empty | |
| 9 | constraint | literal block | always emitted | binding on every scope it covers once accepted | |
| 10 | see | scalar | omitted when absent | reference code the constraint points at | |
| 11 | enforced_by | block sequence | omitted when absent | <path>#<symbol> entries naming what holds the rule mechanically | |
| 12 | amends | flow list | omitted when absent | ADR ids this one changes in part | |
| 13 | supersedes | bare | omitted when absent | an entity id | |
| 14 | ratified | scalar | omitted when absent | the hash of constraint and scope accept made binding | |
| 15 | anchor | scalar | omitted when absent | the tag object at refs/ank/ratify/<id>; absent on a commit anchor | |
| 16 | verified | block sequence of maps | omitted when absent | readings: by, then at, both required in an entry | |
| 17 | schema | integer | always emitted | ||
| 18 | version | integer | always emitted |
Spec
type: spec, ids SPEC-<12 hex>.
| # | Field | Emission | Presence | Values | Notes |
|---|---|---|---|---|---|
| 1 | id | bare | always emitted | SPEC-<12 hex> | |
| 2 | type | bare | always emitted | always spec | |
| 3 | slug | scalar | omitted when absent | cosmetic, never resolved on | |
| 4 | title | scalar | always emitted | ||
| 5 | created | scalar | always emitted | ISO 8601, always UTC with the Z suffix | |
| 6 | author | scalar | omitted when absent | a typed actor; absent means the entity predates the field | |
| 7 | status | bare | always emitted | proposed | accepted | superseded | |
| 8 | scope | block sequence | always emitted | globs, never empty; what the document governs | |
| 9 | references | flow list | omitted when absent | entity ids | |
| 10 | supersedes | bare | omitted when absent | an entity id | |
| 11 | ratified | scalar | omitted when absent | the hash of the body and scope accept made binding | |
| 12 | anchor | scalar | omitted when absent | the tag object at refs/ank/ratify/<id>; absent on a commit anchor | |
| 13 | verified | block sequence of maps | omitted when absent | readings: by, then at, both required in an entry | |
| 14 | schema | integer | always emitted | ||
| 15 | version | integer | always emitted |
Log entry
type: log, ids LOG-<12 hex>.
| # | Field | Emission | Presence | Values | Notes |
|---|---|---|---|---|---|
| 1 | id | bare | always emitted | LOG-<12 hex> | |
| 2 | type | bare | always emitted | always log | |
| 3 | slug | scalar | omitted when absent | cosmetic, never resolved on | |
| 4 | title | scalar | always emitted | the message, or its head | |
| 5 | created | scalar | always emitted | ISO 8601, always UTC with the Z suffix; the instant of the entry | |
| 6 | author | scalar | omitted when absent | a typed actor; who wrote the entry | |
| 7 | scope | block sequence | always emitted | the subject’s scope as it stood | |
| 8 | about | bare | always emitted | an entity id of any kind | |
| 9 | seq | integer | always emitted | rank among that entity’s entries, from 0 | |
| 10 | records | scalar | omitted when absent | edit | create | method | absent is work; a value unknown to the reader is read as machinery |
| 11 | verified | block sequence of maps | omitted when absent | readings: by, then at, both required in an entry | |
| 12 | schema | integer | always emitted | ||
| 13 | version | integer | always emitted | above 1 means the entry was rewritten |
records
What a log entry a verb wrote records. Absent, the entry is work; a value this build does not know is read as machinery and never refused.
| Value | Records |
|---|---|
edit | a change of content outside a status transition: the fields, the versions, the hash replaced and the hash produced |
create | the creation of its subject: version 0 to 1 and the hash produced |
method | a sibling skill opened under a claim; the title is its name |
Proof type
What a proof entry’s ref points at. A weak type anchors nothing outside the agent’s reach, and check marks it.
| Value | Trust | Meaning |
|---|---|---|
test | strong | a test run, by a reference to it |
commit | strong | a commit the work is in |
human-review | weak | somebody read the work |
assertion | weak | a statement, and nothing behind it |
Proof via
The route by which a proof entry arrived. Absent means the entry was written before the field existed, never a fourth route; a test entry submitted by a caller anchors nothing outside the agent’s reach.
| Value | Meaning |
|---|---|
verifier | ank ran a verifier config.yml declares; its own statement |
attested | reached the task on refs/ank/proof/<id>, written by whoever held the pipeline |
submitted | a caller passed it to done --proof or attest --proof; recorded as given |
config.yml keys
Every key .ank/config.yml may carry, with the type of its value and what an absent key means. A key not listed here is refused, and so is a file whose schema is newer than this build reads.
This build reads schema: 1 through schema: 2; a file carrying requires_ank declares schema: 2, and one without it may stay at schema: 1. A duration is <n><unit>, the unit one of s, m, h or d. <name> stands for a key the file chooses; ank config <key> reads and writes each key, signers aside, which ank signers writes.
| Key | Type | Default | Notes |
|---|---|---|---|
schema | integer | required | the version of this file’s format |
requires_ank | version | none | MAJOR.MINOR.PATCH: the oldest ank this corpus needs, compared with the running binary and never with a release; a file carrying it declares schema: 2; absent, no requirement; moved by ank config requires_ank |
context_budget | integer | 8000 | what context hands a reader, in characters; at least 1 |
claim_ttl_max | duration | 2h | the longest lease a claim is granted, whatever --ttl asks; at least 1s |
claim_ttl_default | duration | 30m | the lease claim grants without --ttl, capped by claim_ttl_max; at least 1s |
default_branch | string | none | the branch carrying the reference state; absent, refs/remotes/origin/HEAD names it |
peers.<name> | path | none | a peer corpus a scope entry reaches by name: a path to a checkout on disk, relative to this root or absolute, and never a URL; a reader whose layout differs overrides it in their own corpora.yml with ank config --user peers.<identity>.<name> <path> |
verifiers.<name>.run | command | required | what done runs through sh; required in a declared verifier |
verifiers.<name>.timeout | duration | 10m | how long done lets the command run; at least 1s |
verifiers.<name>.default | boolean | false | true writes the verifier into every task ank new task creates |
verifiers.<name>.inputs | list of globs | none | the files whose content can change the result, relative to the root; absent, the whole tree; written as one flow sequence, never empty |
proof.reuse_max_age | duration | 24h | how old a passing run recorded under <git-common-dir>/ank/runs/ may be for done to reuse it rather than run the verifier again, at least 1s; done --fresh reuses nothing |
verifier_jobs | integer | none | how many verifiers one done runs at once, at least 1; absent, the machine’s available parallelism |
verifier_lock | boolean | true | whether done waits for the verifiers another done of the repository is running, in any of its worktrees, before it starts its own; false lets them run at the same time (ADR-eab130f731f3) |
roles.<name>.can | list of strings | none | what the role may do, each entry a word of the role vocabulary below; a list other than ["*"] forbids every act it omits, so can: [] forbids every act, while absent the key restricts nothing; written as one flow sequence by ank config roles.<name>.can, which declares the role when it is absent, and --unset leaves the role with no can key |
roles.<name>.cannot | list of strings | [] | what the role may not do, each entry a word of the role vocabulary below; written by ank config roles.<name>.cannot |
identities.<identity> | string | none | the role of an identity, one roles declares; one absent from the table is an agent; written by ank config identities.<identity> <role> and removed by --unset |
permissions.enforce | off, warn or deny | off | how roles apply: off not at all, warn and deny as ADR-ddbe024ca7f2 sets; ank init writes warn into the corpus it creates; moved by ank config permissions.enforce |
weight.hot_files | integer | 3000 | check signals a hot corpus holding more entity files |
weight.plane_bytes | integer | 4000000 | check signals claim and proof records weighing more bytes |
guard.corpus | deny or off | deny | what ank hooks run does with a file tool aimed under the corpus directory: deny refuses it, off lets it through; a launch environment may set ANK_GUARD_CORPUS tighter, never looser (ADR-43cbb20dcbf1) |
guard.edit | off, warn or claim | warn | what ank hooks run does with an edit no live claim of the identity covers: off says nothing, warn lets it through naming the path, claim refuses it; a launch environment may set ANK_GUARD_EDIT tighter, never looser (ADR-43cbb20dcbf1) |
signers.<principal>.keys[].key | string | required | a key allowed to ratify, gpg <fingerprint> or <ssh key type> <base64>; the block is written by ank signers, never by ank config (ADR-5c6db7a161b8) |
signers.<principal>.keys[].note | string | none | what the key is, for the reader; ank signers migrate puts the comments of a former .ank/allowed_signers here |
signers.<principal>.keys[].valid_before | date | none | YYYY-MM-DD: the key ratifies nothing committed from that day on, UTC, and what it signed before stays verified; absent, the key has no end |
The role vocabulary
Every entry of roles.<name>.can and roles.<name>.cannot is one of these words, and ank check faults config.yml on a word outside them. An act is forbidden to an identity when its role lists it under cannot, or has a can list other than ["*"] that omits it; an identity absent from identities has the role agent.
*: every act;can: ["*"]is the only list that allows everythingcontext:ank contextfind:ank findclaim:ank claimlog:ank log, which writes an entrydone:ank donenew:task:ank new tasknew:adr:proposed:ank new adr, which writes a proposed ADRnew:spec:proposed:ank new spec, which writes a proposed specadr:accept:ank accepton an ADRspec:accept:ank accepton a specadr:edit-constraint: a change to the constraint of an ADRtask:close:ank closedelete: removing an entityconfig:permissions: a write toroles,identities,permissions,checkorratifyin this file
Environment variables
Every variable the binary reads, and what it changes. None of them is required:
with the environment empty but for PATH, every verb works, and the variables
below adjust who is acting, where a file is found, and how output looks.
Every variable
| Variable | Read by | What it changes |
|---|---|---|
ANK_AGENT | every verb, and ank mcp | the identity this session acts as: who holds a claim, who wrote an entity, who ran done. Unset or blank, <user>@<hostname>, and ank mcp writes under ank-mcp/<version> |
USERNAME | every verb, with ANK_AGENT unset | the <user> of the fallback identity; the first of USERNAME, USER, LOGNAME set and not blank wins, and none gives unknown |
USER | every verb, with ANK_AGENT unset | the <user> of the fallback identity, when USERNAME gives none |
LOGNAME | every verb, with ANK_AGENT unset | the <user> of the fallback identity, when USERNAME and USER give none |
COMPUTERNAME | every verb, with ANK_AGENT unset | the <hostname> of the fallback identity, cut at its first dot and lowercased; the first of COMPUTERNAME, HOSTNAME set wins, and none asks the hostname program, then says localhost |
HOSTNAME | every verb, with ANK_AGENT unset | the <hostname> of the fallback identity, when COMPUTERNAME gives none |
ANK_UPDATE_REPOSITORY | ank update | the repository release tags are read from, in place of https://github.com/haksolot/ank; empty counts as unset |
NO_COLOR | every verb at a terminal, and ank tui | set and not empty, takes the colour and nothing else; the empty value is not an opt-out |
TERM | every verb at a terminal, and ank tui | dumb takes the colour, as NO_COLOR=1 does, and draws the structure of ank tui in ASCII; on Windows, set at all, it says the console renders escape sequences |
WT_SESSION | every verb at a Windows terminal | set, says the console renders escape sequences; with none of WT_SESSION, TERM, TERM_PROGRAM, ConEmuANSI, ANSICON set, the output is plain |
TERM_PROGRAM | every verb at a Windows terminal | set, says the console renders escape sequences |
ConEmuANSI | every verb at a Windows terminal | set, says the console renders escape sequences |
ANSICON | every verb at a Windows terminal | set, says the console renders escape sequences |
EDITOR | ank edit | the editor ank edit <id> opens when given no field to change; unset or blank, the verb refuses at exit 9 |
APPDATA | ank config --user, --repo, ank mcp, ank watch, ank tui | on Windows, the reader’s configuration directory is %APPDATA%\ank; unset, a verb that needs it refuses at exit 9 |
XDG_CONFIG_HOME | ank config --user, --repo, ank mcp, ank watch, ank tui | elsewhere than Windows, the reader’s configuration directory is $XDG_CONFIG_HOME/ank; empty counts as unset |
HOME | ank config --user, --repo, ank mcp, ank watch, ank tui | with XDG_CONFIG_HOME unset, the reader’s configuration directory is $HOME/.config/ank; neither set, a verb that needs it refuses at exit 9 |
CLAUDE_CONFIG_DIR | ank hooks install claude, ank hooks remove claude | the directory holding the settings.json the entries are written into and taken out of, as Claude Code reads it; unset or empty, .claude under the home directory, which is HOME, and the profile directory on Windows |
ANK_GUARD_CORPUS | ank hooks run claude pre-tool-use | the level of guard.corpus for this session, deny or off, set by whoever launches the agent; it may tighten the level .ank/config.yml declares and never loosen it, so a looser or unknown value is ignored and the hook says so. Unset or empty, the declared level |
ANK_GUARD_EDIT | ank hooks run claude pre-tool-use | the level of guard.edit for this session, off, warn or claim, set by whoever launches the agent; it may tighten the level .ank/config.yml declares and never loosen it, so a looser or unknown value is ignored and the hook says so. Unset or empty, the declared level |
ANK_PERMISSIONS_ENFORCE | ank hooks run claude pre-tool-use | the level of permissions.enforce for this session, off, warn or deny, set by whoever launches the agent; under deny the hook refuses a shell call to an ank verb the identity’s role forbids. It may only tighten the level .ank/config.yml declares, so a looser or unknown value is ignored and the hook says so. Unset or empty, the declared level |
PATH | ank done, ank skills --install, ank update | where sh and git, npx, and npm, powershell, pwsh and curl are looked for; a program found on none of its directories is refused by name |
PATHEXT | ank skills --install, ank update, on Windows | the extensions tried on PATH, in its order, of .COM, .EXE, .BAT, .CMD; unset, those four |
The test suite sets these to observe the binary. They are not an interface, and a release may change or remove any of them without notice:
| Variable | Read by | What it changes |
|---|---|---|
ANK_INDEX_BUSY_MS | every verb that opens the index | how long, in milliseconds, a connection waits on an index another process holds locked; unset, five seconds |
ANK_INDEX_STEPS | every verb that writes the index | a file the SQLite steps a refresh executed are written to |
ANK_INDEX_REFRESHED | every verb that opens the index | a file every refresh appends what it hashed and reindexed to |
ANK_TRACE_READS | every verb that reads the corpus | an absolute path every entity parse and every index opening appends a line to |
ANK_AGENT
The identity this session acts as: who holds a claim, who wrote an entity, who
ran done. Unset, it falls back to <user>@<hostname>, which carries no actor
type and makes two sessions on one machine one agent. ank status says which
one is in force and where it came from:
$ ank status
branch main
warning: no default branch, so completion refs are neither pruned nor judged (ank config default_branch <name>)
identity claude-code/opus-5+docs (ANK_AGENT)
no claim
elsewhere no claim by another agent
perimeter the whole repository, 0 constraint(s)
queue 0 proposal(s), 0 finished elsewhere
corpus 0 fault(s), 1 signal(s), 1 owing nothing
> ank context
How to write one, and why a concurrent session needs its own, is Claims and
identity. ank mcp writes under
ank-mcp/<version> unless this variable names another identity.
ANK_UPDATE_REPOSITORY
Where releases are read from. ank update is the only verb that reads it,
because it is the only verb that asks the network anything (ADR-64f32c74a0f9).
It replaces https://github.com/haksolot/ank in the git ls-remote --tags --refs the check makes, so a mirror, an internal clone or a fixture all serve.
Against a bare clone tagged v0.9.0 and v0.7.0:
$ ANK_UPDATE_REPOSITORY=/srv/ank-mirror.git ank update --check --json
{"contract":1,"current":"0.8.0","latest":"0.9.0","newer":true}
A repository carrying no tag it can parse answers "latest":null and
"newer":false, and still exits 0. What update does with the answer is
Install.
NO_COLOR and TERM
NO_COLOR takes the colour and nothing else. Colour is emitted only when
stdout is a terminal, so a pipe, a file and --json are plain already and the
variable changes nothing for a program reading them. It matters when a person
has the terminal: through a pseudo-terminal ank status came back 538 bytes
carrying 22 escape sequences, and NO_COLOR=1 448 bytes carrying none. The
empty value is deliberately not an opt-out – NO_COLOR= is how a shell spells
“unset this for the child” – and it measured 538 bytes and 22 sequences, exactly
as unset did. TERM=dumb is read the same way as NO_COLOR=1.
EDITOR
What ank edit <id> opens when it is given no field to change. It is read by
that verb alone, and its absence is an environment to repair rather than a
failure of the work:
$ env -u EDITOR ank edit TASK-b700
error[9]: EDITOR is not set, and there is no editor to open
-> EDITOR=vi ank edit TASK-b7004333d81f
Where the reader’s configuration lives
Three files belong to the person running ank rather than to any repository:
corpora.yml, the corpora the MCP server
may reach; watch.yml, what the watcher keeps warm; and
events.jsonl, the stream the watcher writes. They sit in one directory:
%APPDATA%\ank on Windows, and elsewhere $XDG_CONFIG_HOME/ank, falling back
to $HOME/.config/ank. ank watch --where prints the path it resolved: with
XDG_CONFIG_HOME=/srv/cfg it printed /srv/cfg/ank/watch.yml, and with that
variable unset and HOME=/home/me, /home/me/.config/ank/watch.yml.
With none of the three set, a verb that needs the directory refuses at exit 9 and names the variable to set.
Variables that are not an interface
Three ANK_ names appear in the source and in no table above. ANK_COMMIT,
ANK_SKILL and ANK_RELEASED_SCHEMA are read by the build, not at run time:
they are what ank --version and the schema warning print. The ANK_INDEX_
names and ANK_TRACE_READS are read at run time, which is why the table lists
them, but they exist for the test suite to observe the index and the reads, and
a release may change or remove any of them without notice.
The specification
The normative text behind every page of this site lives in the corpus, as
spec entities, and not here. A page explains and links; a spec states the rule,
and where the two disagree the spec is right and the page is a bug
(ADR-33970fcdb6e8). They argue the design; they are not a tutorial.
Each one says in its own body which sections of the original single document it
carries, so a rule that reads (§7) is resolved by the spec that claims §7. In a
checkout, ank find --type spec lists them and ank show <id> prints one whole.
On the web, each link below opens the file as the default branch has it.
- SPEC-3d417b8d8d91 Intent, principles, and what v1 leaves out
- SPEC-ed5f09df66ef The data model
- SPEC-3252ad5a72e3 Storage and search
- SPEC-43a2bcb939e3 Synchronisation
- SPEC-ff885356f1f9 Proof, anchoring and authority
- SPEC-79012ba18769 The CLI surface
- SPEC-558c07ebae8e Presentation: structure for every reader, colour for a terminal, and an identifier by its kind
- SPEC-a1234da5449a The attention budget and the constraint lifecycle
- SPEC-f0eef72fe74d Bootstrapping, teaching and distribution
- SPEC-e8518a6aab5c Implementation, and the decisions that bound it
The list is every spec the corpus holds as accepted, and a test holds it to
ank find --type spec on this repository: a spec accepted, superseded or
retitled without this page following turns the suite red. A superseded spec is
left off, and ank show still prints it, with the one that replaced it named.
Linked, not rendered. The specs are read here through GitHub’s view of the
file rather than copied into the site at build time. A rendered copy would need
the site’s build to run ank, and would be one more place the text could be
read out of step with the corpus it came from; the link always reaches the
default branch’s bytes.
The machine surface
For someone writing a tool that reads or drives an ank corpus, who has never seen this repository: a board, an editor plugin, a dashboard, an agent harness, anything that reads a corpus and shows it to somebody. A pipeline needs less than this, and Running ank in CI is the whole of it. A client with no shell reaches the same verbs through the MCP server, and the watcher is the optional process that tells a reader a corpus moved.
What costs such a reader real time to discover is below.
The entry point is ank help --json
Not this document, and not the source. The surface describes itself, and the description is generated from the same table the binary dispatches from, so it cannot fall behind what the binary does.
$ ank help --json | cut -c1-64
{"contract":1,"verbs":[{"name":"context","usage":"ank context [<
One verb, whole, is the shape of every entry:
$ ank help close --json
{"contract":1,"verbs":[{"name":"close","usage":"ank close <id>","summary":"closes a task that will never be done; --reason is mandatory","group":"shape the work","writes":"both","outside":"nothing","destructive":true,"open_world":false,"flags":[{"name":"--reason","short":null,"takes_value":true,"repeatable":false},{"name":"--json","short":"-j","takes_value":false,"repeatable":false},{"name":"--quiet","short":"-q","takes_value":false,"repeatable":false},{"name":"--repo","short":"-r","takes_value":true,"repeatable":false},{"name":"--worktree","short":null,"takes_value":true,"repeatable":false}],"notes":["the ref is not the whole product: a push that does not reach the remote leaves the write standing in this clone, and the verb exits 0; a remote that refuses the write is named with its reason"],"refuses":[{"code":7,"when":"no --reason: a closure nobody explained is one nobody can reopen"},{"code":2,"when":"no such entity, or the prefix matches more than one"},{"code":1,"when":"a flag this verb does not take, or a value the parser cannot read"},{"code":3,"when":"the entity moved between the read and the write: redo context, somebody else wrote"},{"code":9,"when":"git is absent or older than 2.34: an environment to repair, not work that failed"},{"code":6,"when":"the task is already closed or already done: neither is a state this verb moves out of"}],"kinds":[],"returns":[{"when":null,"fields":[{"name":"contract","type":"number","nullable":false},{"name":"task","type":"string","nullable":false},{"name":"status","type":"string","nullable":false},{"name":"claim_revoked","type":"boolean","nullable":false}]}]}]}
So a client can discover, without reading a line of Rust: every verb, its flags and their short forms, the states it refuses on with the code each returns, and the fields of the document that comes back.
kinds is empty except where a verb writes several kinds of entity, which
today is new. There each kind names the flags it takes, the ones whose absence
it refuses and the ones another kind owns, each with its code: an ADR without
--constraint is a 7 you can read before you meet it. ank help new adr --json
is the same document narrowed to that kind, flags, notes and refusals included.
returns is a list, because a verb may answer two questions. config <key>
reads and config <key> <value> writes; log <id> reads and log <id> <message>
appends; show over a task carries the blocked_by edges and over an ADR does
not, since a document carrying them empty would be answering a question nobody
asked. Over an ADR it carries amends, the ids it amends in part, and
amended_by, every accepted ADR amending it, both present and empty on an ADR
with neither, since every ADR answers that question; a spec and a log entry
carry neither. Each shape names the call that returns it in its when, which is null
where the verb has only one.
returns is flat, with the path in the name. A nested field appears as
tasks followed by tasks.id and tasks.title, in the order the document emits
them. No key in any document contains a dot, so a client that wants the tree
splits on one character. The reason it is flat rather than nested is that this
document describes its own output too, and a description that recursed into
itself would not terminate.
The type vocabulary is six words: string, number, boolean, string[],
object, object[]. nullable is separate from the type and is load-bearing:
null and "" are different answers, and a client that treats a nullable string
as a string breaks on the first detached HEAD it meets.
Every document carries the contract version
"contract": 1
It leads every --json document, and it is the field to read before deciding you
can read the rest.
Within one version a document may gain a field, and may never lose, rename or retype one. So parse leniently, because an unknown field is not a breaking change and your parser must not refuse one, and treat a change of this number as the signal to look again.
It is not the version of the binary. ank --version says which build is in hand;
this says which shapes came out of it, and a release that changes no document
leaves it untouched.
The exit codes
The semantics are in the code so a caller can route without parsing output. They
are stable, and ank help --json publishes which verb returns which. The table
is the exit-code reference, generated from the enum that
declares them.
Two of them are the ones a loop must handle. 3 means “somebody moved, read again”. 4 means “take something else”.
6 and 7 are two codes on purpose. In 6 the state forbids what you asked; in 7
the thing you asked for is legal and something it depends on is absent. claim
on a task with no done_criteria is a 7, because taking the task is legal and
the criterion it would freeze is not there. A client that conflates them reacts
wrongly to one of the two.
9 is not a failure of the work. git absent or too old, sh missing,
$EDITOR unset, a default branch that cannot be determined. Collapsing it into
“the command failed” sends somebody to fix sound code.
1 has no reaction of its own to prescribe. It is what a mistyped command and an unparseable file both get, and a script that routes on it is guessing.
Every refusal names the exact command to run next, on stderr, and that is stable too:
$ ank show TASK-9999
error[2]: entity not found: TASK-9999
-> ank find TASK-9999
$ ank claim TASK-6da1
error[4]: TASK-6da126c832be held by tool/1.0 (expires in 30m)
-> ank context
A refusal leaves stdout empty, and a warning may not
Under --json a refusal writes nothing at all to stdout. Not an error
document, not an empty object: zero bytes. The message and its hint go to
stderr, the code goes to the exit status, and that is the whole answer.
Measured across three codes – show TASK-9999 (2), done with no claim held
(6), close with no --reason (7) – stdout was 0 bytes every time. So parse stdout only once the code says 0; a parse error
on a refusal is a client reading the wrong stream.
A warning is the other case, and it does not all go to one stream. There are two kinds and the split is deliberate.
The warnings about the corpus are in the document, under a warnings array
of strings, with stderr left empty. Four verbs carry the field – context,
claim, log in its appending form, and release – and ank help --json is
where to read which, rather than this list:
$ ANK_AGENT=tool/2.0 ank claim TASK-0e61 --json
{"contract":1,"task":"TASK-0e6148ab8b03","holder":"tool/2.0","expires":"2026-09-20T18:15:44Z","warnings":["tool/1.0 holds TASK-efd813eedb23, overlapping on src/**"]}
An intersecting claim is named and never refused (ADR-052accd6e3b2), so the fact
has to reach a caller somewhere it will be read, and under --json that is the
document rather than a stream a parser was told to ignore. The array is present
and empty when there is nothing to say, so a client reads it unconditionally.
The warnings about the refs are on stderr, in both modes, because they are
not the answer: a write whose ref did not reach the remote leaves the document
and the exit code exactly as they would have been. done, release and close
each owe one. Against an unreachable remote, with stderr sent to a file of its
own, done put the document on stdout and exited 0:
$ ank done --proof commit:8db4465 --json 2>stderr.txt; echo "exit $?"
{"contract":1,"task":"TASK-277368641a6e","status":"done","commit":"8db44652564828e480ea7e5be3768b14f9c03893","branch":"main","proofs":1,"outside_scope":[]}
exit 0
and the warning on stderr:
$ cat stderr.txt
warning: claim not pushed: it holds in this clone only, and another clone can take the same task
So read stderr, and do not assume it is empty on success – but do not look there for what the document already carries.
The global flags
ank help --json carries every flag of every verb, so none of this is a list to
maintain by hand. Four flags are on nearly every verb, and what each one does is
worth stating once.
--json, short -j, on all 29 verbs. One line on stdout, never coloured.
--quiet, short -q, on all 29 verbs, and it empties stdout rather than
shortening it: ank check printed 340 bytes on one corpus, ank check --quiet
printed 0, and both exited 0. What is left is the exit code, which is the point
– a caller that only routes on the code pays for no output at all. It does not
silence a refusal: ank show TASK-9999 --quiet still puts error[2] on stderr
and still exits 2. --json wins over it, so --quiet --json is still a
document.
--repo <path>, short -r, on 27 verbs: which corpus. init refuses it by
name, and watch takes its corpora from its own declaration.
--worktree <path>, no short form, on every verb but watch: which tree
that corpus is anchored to. --repo says where .ank/ is; --worktree says
where a scope glob is confronted, where a path argument resolves, where a
verifier runs, and where a commit: proof is looked up (ADR-9e56318631f3). The
two are equal unless you separate them, and separating them shows: one corpus
whose single task is scoped src/**, checked against a tree that has src/,
reported 3 signals; checked against a tree that does not, 4, the extra one being
scope 'src/**' matches no file yet. That is the flag a tool wants when one
.ank/ sits above several checkouts. A path that is not a directory is refused
at exit 1, naming the confusion the refusal exists for:
$ ank status --worktree /nope/nope
error[1]: --worktree /nope/nope is not a directory
-> --worktree names the tree the corpus is anchored to, not its corpus
The remaining short forms belong to one verb or two and are read from ank help <verb> --json rather than from here: -c for --criteria, -b for
--blocked-by, -v for --verify, -p for --proof, -t and -s for
find’s --type and --status, -l for context --limit, -u for config --unset.
A task’s state is not in its file
This is the one that costs the most time, because a tool that gets it wrong under-reports silently.
The file is the entity. The state is the file together with three things that are not in it:
-
refs/ank/claims/<id>, who holds the task and until when. A claim lives in a git ref and never in the file, so two clones arbitrate through the remote rather than through a field somebody has to merge. -
refs/ank/proof/<id>, proofs a pipeline attested without making a commit. -
the log entities whose
aboutnames the task, one file per entry, stored beside the entities and not inside them:$ cat .ank/entities/LOG-c0f96bc669ae.md --- id: LOG-c0f96bc669ae type: log title: the layout is not the contract created: 2026-08-26T00:22:04Z author: tool/1.0 scope: - src/** about: TASK-6da126c832be seq: 2 schema: 4 version: 1 ---An entry carrying
recordsis machinery rather than work: written by a verb that changed the entity’s content, not by the agent holding it. This task carries two: thecreaterecordnewwrote at its birth, and anedit, because the criterion in the file below was amended before a claim froze it. The edit’s message is the whole of that accounting:$ cat .ank/entities/LOG-e6c24bc5f3e2.md --- id: LOG-e6c24bc5f3e2 type: log title: done_criteria (version 1 to 2, replaced b1f3aa97873c, produced 83947c872580) created: 2026-08-26T00:22:04Z author: tool/1.0 scope: - src/** about: TASK-6da126c832be seq: 1 records: edit schema: 4 version: 1 ---
Read the file alone and here is what you see:
$ cat .ank/entities/TASK-6da126c832be.md
---
id: TASK-6da126c832be
type: task
slug: the-parser-reads-a-corpus-without-opening-a-file
title: The parser reads a corpus without opening a file
created: 2026-08-26T00:22:04Z
author: tool/1.0
status: in_progress
scope:
- src/**
blocked_by: []
done_criteria: |
A caller reads every entity through the CLI.
criteria_by: creator
schema: 4
version: 3
---
in_progress, version: 3, and not one word about who is holding it, when the
lease expires, what they have learned, or what the two versions before this one
were. Ask the CLI instead and the same task answers whole:
$ ank show TASK-6da1 --json
{"contract":1,"id":"TASK-6da126c832be","coordination":"claimed by tool/1.0","blocked_by":[],"unblocks":[],"detached_proofs":[],"log_total":1,"log_shown":1,"log":[{"id":"LOG-c0f96bc669ae","timestamp":"2026-08-26T00:22:04Z","who":"tool/1.0","message":"the layout is not the contract","records":null}],"machinery":[{"id":"LOG-3a51d0c2b7e4","timestamp":"2026-08-26T00:22:04Z","who":"tool/1.0","message":"created (version 0 to 1, produced 5b0e7c93d1a2)","records":"create"},{"id":"LOG-e6c24bc5f3e2","timestamp":"2026-08-26T00:22:04Z","who":"tool/1.0","message":"done_criteria (version 1 to 2, replaced b1f3aa97873c, produced 83947c872580)","records":"edit"}],"content":"---\nid: TASK-6da126c832be\ntype: task\nslug: the-parser-reads-a-corpus-without-opening-a-file\ntitle: The parser reads a corpus without opening a file\ncreated: 2026-08-26T00:22:04Z\nauthor: tool/1.0\nstatus: in_progress\nscope:\n - src/**\nblocked_by: []\ndone_criteria: |\n A caller reads every entity through the CLI.\ncriteria_by: creator\nschema: 4\nversion: 3\n---\n"}
coordination came from the ref. log and machinery came from the log
entities, split on records: the work trace is what a holder wrote and is what
the budget is spent on, the machinery is what the verbs wrote and is listed
under it, so a task edited eight times does not answer “what did the last holder
learn” with eight mechanical lines. records is null on a work entry, and a
client reading log alone still sees the field. log_total and log_shown
count the work trace and never the machinery. content is the file, byte for
byte, so nothing is lost by going through the verb.
So read through the CLI, not through the directory. Not as a matter of taste:
a reader that walks .ank/ is reading one of the three sources and will report a
held task as free.
If you do read the files, whether from a viewer with no binary to call or a parser
in another language, then read all three, and read the refs correctly: most of them are in
.git/packed-refs rather than under .git/refs/, and a reader that walks only
the loose ones finds almost none of them.
ank check writes. Do not poll it
It prunes the claim refs it finds stale: orphans, and completion refs whose task
is done or closed on the default branch. The binary says so itself:
$ ank help check
ank check [<path>]
the mechanical invariants: parse, round-trip, references, frozen fields, orphaned claims; prunes the claim refs it finds stale, so it writes
flags: --kind <v> --peers --all
global: -j, --json -q, --quiet -r, --repo <v> --worktree <v>
note: exit 8 means findings; a signal alone leaves it 0
the only verb that prunes refs/ank/claims: orphans, and completion refs whose task is done or closed on the default branch
a signal kind firing on more entities than the smaller of 20 and five percent of the hot corpus, and on more than five, is reported once for the corpus, naming five and the command that lists the rest; a fault never is
--kind <kind> lists the findings of that kind alone, one per entity and never folded; the exit code stays the whole corpus's
by default check lists every fault and every owed signal, then one line counting the signals that owe nothing; --all lists every finding, --kind every finding of its kind, and --json every finding with owed on each; the exit code is the same in every case
a signal 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 burst is owed while one entity it counts is unsettled; a fault always is
a declared peer that cannot be read is a signal; --peers makes it a fault, for the CI job that checks the sibling out, and changes nothing else: a peer task its default branch does not hold yet stays what check says it is
refuses: the path names nothing inside this repository (1)
the corpus carries at least one fault; a signal alone leaves the code at 0 (8)
--kind names a word no rule of check answers to; the refusal lists the ones it does (7)
A dashboard refreshing every thirty seconds must not call it. ank status and
ank find are what a poll uses; check is the verb a human or a pipeline runs
deliberately.
ank show is not a poll either, and for a different reason: it renews a
claim when its subject is the task the caller holds, and so does context.
A screen nobody is sitting at would keep an abandoned claim alive all night, and
every other agent would go on reading the task as held. Which verbs move the
lease, measured, is Claims and identity.
Poll status and find; call context and show when somebody is actually
working.
Two planes, and only one of them is precious. What check prunes is the
coordination plane, the refs that say who holds what, and losing a ref
there loses a fact nothing else carries. Separately, every verb that reads the
corpus may write a disposable one: a SQLite index beside the files, which
stores a content hash per file and reindexes whatever diverged when it is opened.
That is why an entity edited by hand or arrived through git checkout shows up
on the next read with no reindex command to forget. Deleting that index is always
safe, and it is never the source of truth. But it does mean a “read” verb
touches the disk, which is worth knowing before you point twenty pollers at one
working tree.
It is also one of the two verbs that walk git history, review being the other
and sharing the same inspection, to say where a dead scope went. That makes both
of them slower than a read, and it is a second reason not to put either on a
timer. Only check prunes, so only check writes; but neither is a poll.
What a finding means, fault or signal, is Reading ank check. Under
--json each one carries its level, its kind, its subject and its message. The
kind is one stable word per rule, the word ank check --kind takes. Each one
also carries owed, whether a reader has anything to do about it, and
--json lists every finding, owed or not, where the human listing prints the
owed ones and counts the rest; unowed is that count:
$ ank check --json
{"contract":1,"faults":0,"signals":4,"unowed":1,"tasks":1,"adr":1,"hot_files":6,"plane_bytes":186,"pruned":[],"findings":[{"level":"signal","kind":"read-by-no-human","subject":"ADR-57715ae64348","message":"written by an agent and read by no human","note":[],"charge":[],"owed":true},{"level":"signal","kind":"read-by-no-human","subject":"TASK-6da126c832be","message":"written by an agent and read by no human","note":[],"charge":[],"owed":true},{"level":"signal","kind":"default-branch-unknown","subject":"coordination","message":"default branch indeterminable, completion refs neither pruned nor judged and log entries not compared against it (ank config default_branch <name>)","note":[],"charge":[],"owed":true},{"level":"signal","kind":"no-signers","subject":"signers","message":"no ratification key declared: permissions are advisory, not enforced (§8)","note":[],"charge":[],"owed":false}]}
The conformance suite is offered to you
Two sets of fixtures in this repository are yours to reuse. The first says so in
its own header (“any third-party tool that claims to read or write the format
can reuse the tests/golden/ directory”) and the second is offered here, which
is the only place it is said:
crates/ank-core/tests/golden/: the file format. Valid files that must round-trip byte for byte in canonical form, and invalid ones with the error each must produce. If you are writing a parser in another language, this is what tells you it is right, and the file format is what it is checking against.crates/ank-cli/tests/golden-json/: the machine surface. One fixture per document the CLI returns, captured from the process rather than from a function, so what they pin is what leaves the binary. If you are writing a client, these are the exact bytes to write it against.
Both are plain files in a public repository. Copy them into your own suite; a shape that changes here without its fixture changing is a failing test on our side, which is what makes them worth copying.
An agent harness calls ank hooks
For an agent harness the binary is also the hook handler (ADR-43cbb20dcbf1).
ank hooks install <agent> writes into that agent’s user-level settings the
entries that call ank hooks run <agent> <event>, and nothing beside them: no
script file, so there is nothing to keep in step but the binary. Claude Code is
the only agent this version installs for, and ank help hooks is the whole
verb.
Install and remove. Claude Code’s file is settings.json in
CLAUDE_CONFIG_DIR, or in .claude under the home directory when that is unset
or empty. Install adds one SessionStart entry and one PreToolUse entry
matched to the file tools (Read, Write, Edit, MultiEdit,
NotebookEdit, Glob, Grep) and to Bash, each running the binary that
installed it by its absolute path. An entry an earlier install matched to the
file tools alone has its matcher moved in place. A second install changes
nothing:
$ ank hooks install claude
installed claude hooks (SessionStart, PreToolUse) in /home/me/.claude/settings.json
$ ank hooks install claude
claude hooks already installed in /home/me/.claude/settings.json
$ grep -o 'hooks run claude [a-z-]*' /home/me/.claude/settings.json
hooks run claude session-start
hooks run claude pre-tool-use
The file is somebody else’s, so it is edited and never rewritten: every byte
install did not add stays where it was, and remove takes out exactly what
install wrote, giving the file back as install found it:
$ ank hooks remove claude
removed claude hooks (SessionStart, PreToolUse) from /home/me/.claude/settings.json
$ cat /home/me/.claude/settings.json
{
"theme": "dark"
}
What runs. The harness hands run its event as a JSON payload on stdin,
and what run prints is the harness’s own format, which is why it refuses
--json. At session start it serves the agent ank status and a pointer to
the contract. Before a file tool it applies two guards, each a key of
.ank/config.yml set with ank config:
guard.corpus,denyoroff, defaultdeny. A file tool aimed under the corpus directory is refused, naming the verbs that read it instead.guard.edit,off,warnorclaim, defaultwarn. An edit no live claim of the identity covers is let through with a message naming the path underwarn, and refused underclaim. A tool that only reads is not an edit, at any level.
In a corpus where tool/1.0 holds a task scoped src/**, with the payload
reduced to the fields the guards read (the harness also sends its cwd, which
run resolves a relative path against):
$ echo '{"tool_name":"Read","tool_input":{"file_path":".ank/config.yml"}}' | ank hooks run claude pre-tool-use
{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":".ank/config.yml is under the corpus directory, which is reached through the ank CLI and never by opening its files: `ank show <id>` prints an entity whole, `ank find <query>` lists, `ank context <path>` serves what binds a perimeter."}}
$ echo '{"tool_name":"Edit","tool_input":{"file_path":"src/main.rs"}}' | ank hooks run claude pre-tool-use; echo "exit $?"
exit 0
$ echo '{"tool_name":"Edit","tool_input":{"file_path":"docs/page.md"}}' | ank hooks run claude pre-tool-use
{"systemMessage":"no live claim of tool/1.0 covers docs/page.md: `ank context docs/page.md` names what binds it and what is claimable, and `ank claim <id>` takes the task.","hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"no live claim of tool/1.0 covers docs/page.md: `ank context docs/page.md` names what binds it and what is claimable, and `ank claim <id>` takes the task."}}
The edit inside the claim gets no output at all, only the exit code, which the harness reads as nothing to say.
The launch environment only tightens. ANK_GUARD_CORPUS and
ANK_GUARD_EDIT, set by whoever launches the agent, may raise the level the
corpus declares and never lower it. A looser value, or one that is not a level,
is ignored, and run says so in its message:
$ echo '{"tool_name":"Edit","tool_input":{"file_path":"docs/page.md"}}' | ANK_GUARD_EDIT=claim ank hooks run claude pre-tool-use
{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"guard.edit is claim, and no live claim of tool/1.0 covers docs/page.md: `ank context docs/page.md` names the task that does, and `ank claim <id>` takes it."}}
$ ank config guard.edit claim
guard.edit warn (default) -> claim
$ echo '{"tool_name":"Edit","tool_input":{"file_path":"docs/page.md"}}' | ANK_GUARD_EDIT=off ank hooks run claude pre-tool-use
{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"guard.edit is claim, and no live claim of tool/1.0 covers docs/page.md: `ank context docs/page.md` names the task that does, and `ank claim <id>` takes it. ANK_GUARD_EDIT=off was ignored: .ank/config.yml declares guard.edit claim, and the launch environment may tighten it, never loosen it."}}
So an orchestrator that launches its workers with ANK_GUARD_EDIT=claim holds
them to their claims whatever the corpus declares, and a corpus that declares
claim cannot be loosened by a launch. Both variables are in the environment
reference.
A third guard reads shell calls. Under permissions.enforce deny, a Bash
call whose command runs an ank verb the identity’s role forbids is refused,
naming the role, the entry of .ank/config.yml that forbids the act, and the
command, which is a human’s to run. The two file guards ignore a shell call.
The command is split on &&, ||, ;, |, & and newlines; each part whose
program is ank, by any path and after NAME=value prefixes or env, is read
as the verb would read it. A command that runs ank through another program,
sh -c or xargs among them, is let through, and the verb then warns as it
does under warn. The identity judged is the session’s ANK_AGENT, whatever
the command itself exports. ANK_PERMISSIONS_ENFORCE tightens the declared
level the way the two guard variables do. With tool/1.0 mapped to human by
init, and a worker that nothing maps, so an agent:
$ ank config permissions.enforce deny
permissions.enforce warn -> deny
$ echo '{"tool_name":"Bash","tool_input":{"command":"ank accept ADR-06d29e727d24"}}' | ANK_AGENT=claude-code/worker ank hooks run claude pre-tool-use
{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"permissions.enforce is deny, and role 'agent' of claude-code/worker forbids adr:accept (roles.agent.cannot lists it): `ank accept ADR-06d29e727d24` is a human's to run, from their own terminal under an identity whose role allows it."}}
$ echo '{"tool_name":"Bash","tool_input":{"command":"ank context src"}}' | ANK_AGENT=claude-code/worker ank hooks run claude pre-tool-use; echo "exit $?"
exit 0
A command that runs no ank is answered before any corpus is read, and starts no process.
Fail-open. A hook that blocks the harness on its own error is worse than no
hook, so run never does. Outside a corpus it is silent and exits 0, and a
payload it cannot read, or an error of its own, lets the tool call through:
$ echo 'not a payload' | ank hooks run claude pre-tool-use; echo "exit $?"
exit 0
$ cd /srv/plain && echo '{"tool_name":"Read","tool_input":{"file_path":".ank/config.yml"}}' | ank hooks run claude pre-tool-use; echo "exit $?"
exit 0
What binds and what does not
- Bind to
--json, never to the human output. One line, stdout only, never coloured, and a refusal leaves stdout empty rather than putting a shape there your parser has to tell apart. Warnings split: the ones about the corpus are awarningsarray inside that document, the ones about a ref that did not reach the remote are on stderr in both modes. - Bind to the exit code, never to the wording of an error. The message and the hint are written for a person to read and may be improved; the code is the contract.
- Bind to
ank help --jsonfor what a verb accepts and returns, rather than to a list you maintain. A list maintained by hand is a list that will disagree, and the disagreement surfaces on your side, days later, as a bug you cannot see from there. - One corpus is addressed at a time, by
--repo <path>on the CLI and by thecorpusargument over MCP, so a tool holding several addresses each on its own. One process may hold several; nothing merges them. Claims are per repository, and nothing merges the claim spaces of two clones, becauserefs/ank/*cannot carry such an arbitration. - Do not poll a verb that renews a claim.
contextandshowover the held task move the lease;statusandfinddo not, and they are what a refresh is for. - Do not bind to
ank watch, and bind toevents.jsonlonly as the watcher says.
The MCP server
A client that has no shell reaches ank through ank mcp, a verb of the one
executable every route installs (ADR-1ea31c2f3c5a). There is no second file to
fetch, sign or discover: what the CLI dispatches is what the surface serves,
because they are the same file. It speaks JSON-RPC over stdio and the client
spawns it, which means it is configured rather than started.
Configuring a client
Three configurations, and each of them is pasted rather than derived.
Claude Code, one line, which writes the entry for you:
claude mcp add ank -- ank mcp --repo /path/to/your/repo
or .mcp.json at the root of the repository, which is the form that travels
with the tree and reaches everyone who clones it:
{
"mcpServers": {
"ank": {
"command": "ank",
"args": ["mcp", "--repo", "/path/to/your/repo"]
}
}
}
Claude Desktop, in claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows), which has no project
directory of its own and so has nothing else to go on:
{
"mcpServers": {
"ank": {
"command": "ank",
"args": ["mcp", "--repo", "/path/to/your/repo"]
}
}
}
Cursor, in .cursor/mcp.json beside the repository, or ~/.cursor/mcp.json
for every project at once:
{
"mcpServers": {
"ank": {
"command": "ank",
"args": ["mcp", "--repo", "/path/to/your/repo"]
}
}
}
command is ank and mcp is the first argument, in all three. If you
have a configuration written against ank-mcp, that is the one line to change:
releases up to 0.6.0 placed a second executable by that name and no route places
one any more, so a client still naming it gets command not found rather than a
wrong answer.
--repo is written out in all three, and that is the point of showing them.
A client spawns the server in whatever directory it happens to be in, and with
no --repo the server takes that directory. The failure mode is not an error:
it is a process quietly speaking for a corpus nobody meant, or for none. The
configuration is also where it is named rather than something a call may
override; a call that tries is refused, below. A path with no corpus under it is
refused before any client is listening, rather than after, so it reaches a
person rather than a log:
$ ank mcp --repo /tmp
error[1]: no .ank/ found from /tmp
-> ank init
Several repositories, one server
Several repositories do not need several servers. --repo names the corpus
a call naming none of its own goes to; every other corpus that server may reach
is declared once, outside every repository, and the configuration above does
not change by a character. The declaration is written through the CLI, keyed on
the repository identity of the corpus and never on a path:
$ ank config --user corpora.bccc32d77d8a9a329f772f789dc5fb1054259d70 /srv/back
corpora.bccc32d77d8a9a329f772f789dc5fb1054259d70 /srv/back
What that writes is corpora.yml (ADR-96174f1ac2b7), in the reader’s
configuration directory (Environment variables
says where that is):
schema: 1
corpora:
bccc32d77d8a9a329f772f789dc5fb1054259d70: /srv/back
The identity is the root commit, which ank status --json prints under
"corpus", so run that in the repository you want to declare and paste what it
gives you.
What the surface is
Four properties of it are load-bearing, and none of them is visible from a tool list.
Every verb COMMANDS carries, generated from that table. Not a curated
subset, under any protocol (ADR-fd98f4bc6dea). It is the same table ank help --json is generated from, walked: the summary becomes the tool description, the
refusals and their exit codes are written into it so a client can read what a
call will refuse before making it, and the flags become the input schema. One
tool per verb, whatever the table carries, named ank_<verb> because a bare
context collides with every other server a client has loaded and ank context
is not a legal tool name. Positionals arrive as arguments, an array of strings,
exactly as they sit on the command line; flags arrive under their own names with
the leading dashes stripped. Where a verb takes a fixed word first, as hooks,
signers and new do, the schema holds the first item to those words with
prefixItems and types every later item as a plain string, so
["install", "claude"] is a call the schema accepts. Where a verb refuses to
run without a positional, arguments is required and minItems counts what
it needs. What a call gets back is the document --json
returns, as structuredContent and as the text block beside it, with the exit
code next to both; a refusal answers no document and carries none. Every tool
also carries readOnlyHint, destructiveHint and openWorldHint, all three
and always, derived from what ank help --json declares for the verb:
read-only where writes and outside are both nothing, destructive where
destructive is true, open world where open_world is true. writes counts
the corpus and outside counts everything else, such as the harness settings
hooks install rewrites. Nothing in the server names a verb, so
the two surfaces cannot disagree about what exists.
One process may speak for several corpora, and never for a merged one.
--repo is resolved once, at startup, and that corpus is where a call naming
none of its own goes, so a client that never passes the argument sees exactly
what it saw before the argument existed. Every tool also carries an optional
corpus argument (ADR-fd98f4bc6dea), whose value is the repository identity of
ADR-621a7fd96ce1 – the root commit, never a path. One server, addressed at one
corpus at startup, answering out of another the reader declared:
--> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ank_find","arguments":{"arguments":["--status","open"],"corpus":"bccc32d77d8a9a329f772f789dc5fb1054259d70"}}}
<-- {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\"contract\":1,\"corpus\":\"bccc32d77d8a9a329f772f789dc5fb1054259d70\",\"total\":1,\"shown\":1,\"hidden\":0,\"results\":[{\"id\":\"TASK-6a3615347674\",\"kind\":\"task\",\"status\":\"open\",\"state\":\"open\",\"title\":\"The back answers a query\",\"created\":\"2026-08-26T00:22:04Z\",\"archived\":false,\"anchored_by\":null}]}"}],"isError":false,"exitCode":0,"structuredContent":{"contract":1,"corpus":"bccc32d77d8a9a329f772f789dc5fb1054259d70","total":1,"shown":1,"hidden":0,"results":[{"id":"TASK-6a3615347674","kind":"task","status":"open","state":"open","title":"The back answers a query","created":"2026-08-26T00:22:04Z","archived":false,"anchored_by":null}]}}}
That permits multiplexing. It still forbids merging, and telling those two
apart is the whole of the decision, so it is worth being exact about which one
you are building. Every call becomes ank --repo <one corpus> <verb> --json,
one corpus at a time. There is no merged claim space, no claim held on a
client’s behalf, and no arbitration across clones, because refs/ank/* is per
repository and cannot carry one – the same ban federation gets
(ADR-a1de673043b4), carried into the multi-corpus clause in the same words.
Two claims taken through one server land in refs/ank/claims of two
repositories, and neither corpus carries a word about the other’s task. So a
board over four repositories is one server and four corpora addressed on their
own, presented together by whatever sits above them; it is not four claim
spaces made into one, and a client that shows them as one list must not
arbitrate over that list. What a multi-corpus server does acquire is one
identity holding a lease in several corpora at once, and nothing beyond it.
The reachable set is declared, and nothing is discovered: the startup corpus
plus whatever corpora.yml declares. A caller cannot name a corpus by path, so
there is no spelling of “every corpus on this machine”; and an identity nobody
declared is refused by name, with nothing spawned and no falling back to the
corpus the client did not ask for:
<-- {"jsonrpc":"2.0","id":4,"result":{"content":[{"type":"text","text":"error[9]: no corpus is declared under 0000000000000000000000000000000000000000, and this server reaches no corpus nobody declared\n -> ank config --user corpora.0000000000000000000000000000000000000000 <path>"}],"isError":true,"exitCode":9,"stderr":"error[9]: no corpus is declared under 0000000000000000000000000000000000000000, and this server reaches no corpus nobody declared\n -> ank config --user corpora.0000000000000000000000000000000000000000 <path>"}}
<-- {"jsonrpc":"2.0","id":5,"result":{"content":[{"type":"text","text":"error[9]: '/srv/back' is not a repository identity\n -> a corpus is named by its root commit, never a path, a remote or a slug: ank status --json prints it under \"corpus\""}],"isError":true,"exitCode":9,"stderr":"error[9]: '/srv/back' is not a repository identity\n -> a corpus is named by its root commit, never a path, a remote or a slug: ank status --json prints it under \"corpus\""}}
Both are 9, and 9 is the right code for both: what is missing is a declaration in the reader’s configuration, not anything in either corpus.
The three flags the server keeps for itself stay refused. A call that passes
--repo, --json or --quiet is turned away by name rather than being allowed
to contradict the process it is talking to, and --repo is turned away naming
the argument a caller reaches for instead:
<-- {"jsonrpc":"2.0","id":6,"error":{"code":-32602,"message":"--repo belongs to the server: name a corpus with the corpus argument, by the identity ank status --json prints, never by a path"}}
Nothing is hidden by that and nothing is curated: every verb takes exactly the arguments the table gives it, plus the one argument that says which corpus it runs in.
A refusal is the CLI’s refusal, and it carries the CLI’s exit code. The
surface spawns ank; it does not link it. So a refusal on state is not
re-derived here, it is inherited, hint and all, and it comes back as a result
rather than as a protocol error, because the request was well formed and the
answer is no:
<-- {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"error[2]: entity not found: TASK-9999\n -> ank find TASK-9999"}],"isError":true,"exitCode":2,"stderr":"error[2]: entity not found: TASK-9999\n -> ank find TASK-9999"}}
exitCode is present on every call including a successful one, so a client that
branches on it never has to tell absence from zero; stderr is carried
separately for the reason warnings live there in the first place. The two error
channels stay apart: a JSON-RPC error means the request was wrong, a result
with isError means the corpus said no. A client that conflates them reports
its own bug as a state of your repository.
No claim is taken that the CLI would not have taken in that clone. Every
claim goes to refs/ank/claims/<id> in that repository – the corpus the call
named, or the startup one where it named none – arbitrated by the same
compare-and-swap against the same remote. The server holds no claim on a
client’s behalf, renews none for anybody, and pools no clients under one
identity: one stdio server serves one client, so one process is one caller. It
writes under a typed process identity, ank-mcp/<version>, unless $ANK_AGENT
names one, so a deployment that already names its agents keeps naming them.
accept is a tool here like every other verb, because a generated surface
curates nothing out. Being reachable over a protocol changes nothing about it:
it is still the human act it is on the command line, a signed ref with the same
refusals and no way around them.
What a document, an exit code and a warning mean is the same here as on the command line, and the machine surface is where it is said.
The watcher
ank watch is a background process that keeps the derived index of the corpora
you declare current, so the ank you run finds a cache it does not have to
rebuild. It is a verb of the same one executable every route installs
(ADR-1ea31c2f3c5a), so every installation already has it – and running one is
still nobody’s condition for anything, which is the statement below about
nothing depending on it. Everything else worth knowing about it as an
integrator is what it refuses to be (ADR-4b45f344344f).
It keeps a cache warm, and answers nothing
It is not a surface. No socket, no protocol, no query of its own, and no
subset of the verbs. There is nothing here to ask: a caller that wants an answer
runs the CLI, or talks to ank mcp. A watcher answering the three
questions a dashboard finds convenient would be the curated subset
ADR-fd98f4bc6dea refuses, reached from the other direction, and it would be a
third dispatch path in a project that has spent its history reducing to one. It
does tell you when a corpus it watches changes, on a stream described below,
and that is push and never pull: it says what moved, it says nothing about what
moved, and there is still nothing to connect to.
Nothing depends on it. Every verb gives the same output and the same exit
code with it stopped; its absence is never an error, and no installation route
makes running it a condition of using ank. The installation without a watcher is
the one every CI runner, every container and every agent has, so it is the
normal one, made slower rather than made lesser. Stopping it is always safe, and
stopping_the_daemon_changes_no_verbs_output_and_no_verbs_exit_code in its
suite is what keeps that true.
Nothing it serves is believed over the files. The index is a cache the CLI
rebuilds from a content hash per .ank/ file at read time, so a listing off a
warm index and a listing off no index are the same bytes. The watcher does not
compute that listing and holds no copy of it: it spawns ank and asks for a
read, which is what leaves the index current. It is a cache warmer, so a poll it
misses costs latency and never correctness.
It watches what you declared, and looks for nothing. The declaration is
watch.yml, beside the corpora.yml of ADR-96174f1ac2b7 in the reader’s
configuration directory (Environment
variables says where).
It lives outside every repository, and it is keyed on the repository identity of
ADR-621a7fd96ce1 rather than on a path:
schema: 1
# Seconds between two mirrors of refs/ank/claims/*. Optional; 60 when omitted.
fetch: 60
watch:
# The key is the root commit, which `ank status --json` prints under
# "corpus". One checkout, or a list of them.
4f0b8c2d1e6a39572c84ab0d6f31e75c9a2b48d0: /home/me/work/ank
9c31ea77b04d5f2681ac3e095b7d4f60a8213ce5: /home/me/work/other
Two worktrees of one repository are two paths under one key, and therefore one
watched corpus – which is the whole reason the key is not the path. A key that
is not a root commit is refused by name, a checkout filed under another
repository’s identity is refused with both identities, and a directory carrying
no .ank/ is refused rather than searched around: ank watch --list prints
what would be watched without watching anything, and ank watch --where prints
where the declaration is read from.
The only things it writes into a repository are that repository’s own
.ank/index.db.<N>, the index of the binary’s own schema N, and a mirror of
refs/ank/claims/*. The mirror lands in
refs/ank/watch/<remote>/claims/*, a tracking namespace of the watcher’s own, and
carries the remote’s claims alone: a mirrored proof is read by nobody, so none
is fetched (ADR-4b45f344344f). <remote> is the remote that carries the claims
(ADR-b6fe84504ff2): ank when the repository has a remote by that name, and
origin otherwise, so with both a cycle fetches from ank and runs nothing
against origin. The watcher asks which one when it starts, once per checkout,
and not on every cycle: after git remote add ank in a watched checkout,
restart the watcher, and ank watch --list names the mirror it reads. No branch, no tag, no working tree, no index of
git’s, and no refs/ank/claims. It takes no claim, holds none on anybody’s
behalf, and renews none – a claim is renewed by working, not by reporting
(ADR-0bb7ea8991bc). A fetch that fails is a line on stderr and never an exit
code: the watcher keeps watching, and a dead network downgrades what it offers
rather than stopping it.
What the mirror buys is one line of ank status. refs/ank/claims/* in a
clone is whatever somebody last fetched by hand, so on a parc of clones the
elsewhere section reports who held what an hour ago and has no way to say so.
status reads the mirror beside its own plane and reports both as one list,
with the local record winning wherever they carry the same task. No other verb
reads it, and none may: an installation with a watcher and one without have to
be one product. That is asserted rather than promised, in
a_claim_a_watcher_mirrored_is_reported_by_status_and_by_nothing_else, which
compares every listing verb byte for byte with the mirror present and absent.
A change becomes an event, and the stream is yours to follow
The watcher appends a line when a corpus it watches changes, and any program may follow it. That is the one thing it offers a consumer, and it is offered as a file rather than as a connection: there is nothing to bind to, nothing to negotiate, and nothing you can ask it. Several readers follow the same bytes without the watcher knowing any of them exist.
Where it is. events.jsonl, beside watch.yml in the same directory. One
file for every corpus the watcher was handed; each line says which corpus it is
about.
What a line is. One JSON object, one line, newline-terminated:
{"schema":1,"corpus":"<root commit>","change":"entities"}
{"schema":1,"corpus":"<root commit>","change":"refs"}
schemais the shape of the line, and it is not the contract version that--jsondocuments carry: the two move for different reasons. Within a schema a line may gain a field and may never lose, rename or retype one. Skip a line whose schema you do not know rather than guessing at it.corpusis the repository identity of the watched corpus – the root commit, whichank status --jsonprints under"corpus". Never a path, and no path is carried beside it: a corpus reached by two paths is one corpus, and a field naming one would be an invitation to key on it. Two checkouts of one corpus changing produce two lines carrying the same identity, and the answer to both is the same one read.changesays what moved.entitiesis “a file under that corpus’s.ank/was written, added or removed”;refsis “the watcher’s mirror of the remote’srefs/ank/*moved”, which is how a claim taken in a clone you cannot see reaches you. The vocabulary is closed at those two today and may gain a word.
What a line is not. It carries no title, no status, no body, no identifier
and no entity content of any kind, and it never will: an event that carried the
new state of a task would save you a call and would make the watcher a source of
corpus data that nothing generated from the verb table ever validated
(ADR-4b45f344344f). What changed is on the stream; what is now true of it is what
the CLI answers, and no_event_carries_entity_content_a_reader_would_get_from_the_cli
asserts the absence rather than promising it. An event also never says what to do
about itself. There is one sensible thing to do, which is to read the corpus
again, and the stream does not presume to say so.
How to follow it. Open the file, remember the offset you have read to, and read the bytes past it whenever you like. Three rules and they are the whole protocol:
- Consume whole lines only. The watcher writes one line per call, but a reader that took a half-written one would repaint on a corpus it could not name.
- If the file is shorter than your offset, the watcher started it over and you read from the beginning again. The stream is news and not a log: nothing is anchored in it, nothing hashes over it, so it is bounded rather than kept, and what you missed while you were not running is missed whatever the bound is.
- If the file is not there, no watcher has ever run for this reader. That is not an error and not a degraded mode: read the corpus when your person asks, as every installation without a watcher does. If it appears later, follow it from its beginning.
What it does not license. Following the stream is not a second way into the
corpus, and it must not become one. ank tui follows it and still reaches every
byte it shows by running the CLI with --json, because the event says a corpus
moved and nothing more. And an event is a repaint, never a write: the reader
answers one by running status and find, and deliberately not show, which
renews the lease when the id is the task the caller holds (ADR-0bb7ea8991bc). A
screen nobody is sitting at is told the corpus changed all night and keeps
nobody’s claim alive; an_event_repaints_the_list_and_renews_no_claim is what
holds that true.
What to bind to
- Do not bind to
ank watch. It answers nothing, and it is optional by construction. Write your integration against the CLI or the protocol surface, and let the watcher make those answers arrive sooner where somebody chose to run one. - You may bind to
events.jsonl, and it is a narrow license: it tells you a corpus changed so you can stop asking on a timer. Every answer still comes from the CLI, and your integration has to work with no stream at all, because most installations have none.
Ratifying and archiving
Two acts decide what the corpus is, and both are a human’s: ank accept makes a
proposed decision binding, and ank archive moves what is cold out of the hot
corpus. This page is the recipe for each on this repository, where main is
protected and takes no direct push.
Ratifying a decision
Ratifying is one command, on whatever branch you are on:
ank accept <id>...
For each id, accept writes an annotated tag object at refs/ank/ratify/<id>,
signed where the repository signs (Signing keys), and rewrites the
entity file: status: accepted, ratified: with the hash, anchor: naming the
tag object, and a verified entry. It then pushes the ref to origin with
compare-and-swap. It commits nothing, and it carries no branch precondition
(ADR-5e47007a75be): the ref is a fact about the repository, not about a branch.
When the push does not land, accept exits 9 and keeps nothing: no ref, no
change to the file. A ratification readable by nobody else did not happen, and
the verb says so rather than warning (ADR-af533e7a3e03).
The ref binds as soon as it reaches the remote. context and scope serve
a decision as binding wherever a verified ref matches the constraint and scope
of the file they read, whatever its status: says, so a branch that still
carries the file as proposed is bound by it too. check names a file that
has not caught up, as a signal: ratified by refs/ank/ratify/<id>, but .ank/entities/<id>.md still reads proposed: the file has not caught up.
The file lands with the next change, by any merge method. Commit it on the
branch you are working on, or on one of its own, and let it reach main
through a pull request like anything else. It does not need a pull request of
its own, a merge commit, or anybody to come back for it: the authority is the
ref, and the file only declares what the ref already makes true.
A clone reads the refs only once it has fetched them. git clone does not
fetch refs/ank/*, and the first ank check or ank status in a clone adds
the refspec and fetches them once; the line below does it by hand. A clone
without them falls back to the file and sees proposed: less, never wrong. CI fetches them before check (CI jobs).
git fetch origin '+refs/ank/*:refs/ank/*'
accept refuses a supersession while any tracked file outside .ank/ still cites
the document it retires (ADR-3b6ba766a42e). Re-point those citations first, in
their own change: the refusal names every site with its line, and there is no
bypass.
Without ank
The ratification is git plumbing, so a repository without the binary can make
one. Bring the file to the form accept writes, every field but anchor:
(the file format has the fields, and
the two hashes how ratified: is computed), then:
git hash-object -w .ank/entities/<id>.md # the blob
git tag -s -m 'ratify <id>' -m '<lines>' ratify/<id> <blob>
git update-ref refs/ank/ratify/<id> "$(git rev-parse ratify/<id>)"
git tag -d ratify/<id> # the object stays, the tag name goes
git push --force-with-lease=refs/ank/ratify/<id>: origin refs/ank/ratify/<id>
and add anchor: <tag> to the file, the object name git rev-parse printed.
<lines> are constraint+scope: <hash> (or body+scope: <hash> for a spec)
and by: <actor>, and supersedes: <id> where one applies. In a repository
that does not sign, tag -s is tag -a. The temporary name under refs/tags/
lives between the second and the fourth command only, because a ratification is
not a release and must not look like one to a forge. The empty lease is the
compare-and-swap: the push is refused, ! [rejected] ... (stale info), when
the remote already holds a different ratification under that name.
Anchors made before the ref
Before ADR-5e47007a75be, a ratification was a commit whose subject is
ratify <id>, and those anchors are never rewritten. check reaches a decision
by its ref first, and by walking rev-list --full-history for that subject only
when no ref carries it. The merge-commit rule now protects these anchors and
nothing else, and it stays because keeping it costs nothing:
- a merge commit keeps the subject, the SHA and the signature, and
ank checkverifies the ratification exactly as if it had been committed in place; - a squash rewrites the subject to the pull request title, so the anchor is
never found again.
checkreports the entity as unverifiable, which is a signal and exit 0: the corpus quietly stops being verifiable while CI stays green; - a rebase keeps the subject, so the anchor is still found, but it replays the
commit without its signature. In a corpus that signs, and this one does,
checkreports that as a fault (ADR-964be4d940b2 makes signing a regime the corpus is in, so an unsigned corpus survives a rebase and this one would not).
A squash or a rebase of a branch carrying no ratify <id> commit loses
nothing, and every ratification made by accept today is such a branch. Both
are still disabled on the repository and in its ruleset, which has no bypass
actors, for as long as a commit anchor lives in the history. Which key signs,
and how check judges the signature, is Signing keys.
A commit anchor moves into a ref with one command:
ank accept <id> --reanchor
It writes the tag and the ref that accept writes today, over the same anchor:
the message carries the constraint+scope: (or body+scope:) hash the commit
recorded, any supersedes:, and a reanchors: line naming the commit it moves.
The tag is signed by whoever runs it, and the by: line and the verified
entry it adds to the file name that person, not the author of the first
ratification: re-anchoring is a new reading, and it says so. It pushes the ref
like accept does, and fails at exit 9 with nothing kept when the push does
not land. Nothing in history is rewritten: the ratify <id> commit stays
where it is, and nothing is committed; the file, now naming the tag under
anchor:, lands with the next change. From then on check judges the ref, so
the decision verifies in a shallow clone that never held the commit, and ank show <id> says the tag was re-anchored from that commit.
It refuses, writing nothing:
- at exit 6, a document a ref already carries:
<id> is already carried by refs/ank/ratify/<id> (tag <sha>): there is no commit anchor left to move; - at exit 6, a document whose file has moved from the anchor its commit
records:
<id> has moved from the anchor its commit <sha> records (ratified <hash>, now <hash>): re-anchoring would sign the edit. The commit ratified the old text, and a new reading of it does not ratify the new one: the way forward it names isank new adr --supersedes <id>; - at exit 6, a document no commit ratified:
<id> is proposed, and no ratification of it has an anchor to move, and the command it names is a plainank accept <id>; - at exit 7, a document whose
ratify <id>commit this clone does not hold:no ratify <id> commit is reachable from this clone, so there is nothing to re-anchor from, which a shallow clone answers withgit fetch --unshallow.
Moving the scope of a ratified decision
When the code moves and the decision does not, the perimeter follows the file without a new identifier (ADR-bb9ccdba9be7). Two commands, the second a human’s:
ank amend <id> --drop-scope "<old>" --scope "<new>"
ank accept <id> --rescope
amend edits the scope of an accepted ADR or spec, and only its scope. The
file then no longer matches the anchor its ref carries, and until the rescope
check says so as a signal, its scope was amended after its ratification, and .ank/entities/<id>.md has not caught up with it: ank accept <id> --rescope. While it waits, context does not inject the constraint: the
scope it would bind is one nobody has signed yet. When check reports a scope
git records as renamed on an accepted document, the repair it names is these
two commands.
accept --rescope signs that scope, like accept, where the repository signs.
It writes a new tag in place of the one at refs/ank/ratify/<id>, with
compare-and-swap here and on origin, and rewrites ratified:, anchor: and
verified in the file. The message carries the new anchor, the previous one,
and the previous scope, one line per glob:
ratify <id>
constraint+scope: <new hash>
previous: <previous hash>
previous-scope: <glob>
by: <actor>
check holds the chain to what it claims: the signature, the new anchor
against the file, and the previous anchor recomputed from the current
constraint (or body) with the previous scope. A tag whose previous anchor does
not recompute is a fault, its rescope <tag> names the previous anchor <hash>, but its constraint with the previous scope hashes to <hash>: the decision changed under a rescope. The identifier, the status and every citation stay.
Like accept, it commits nothing and fails at exit 9 with nothing kept when
the push does not land, including when origin holds another tag than the one
this clone replaced.
It refuses at exit 6, writing nothing:
-
a document that is not accepted:
<id> is proposed, and only an accepted document has a scope to rescope; -
a scope that did not change:
<id> declares the scope its ratification carries: there is nothing to rescope; -
a constraint, or a spec’s body, that changed since the ratification:
<id>'s constraint changed since its ratification: a rescope only moves the perimeter. Changing the decision isank new adr --supersedes <id>; -
a document no ref carries. An anchor that is still a
ratify <id>commit is moved into a ref first, before the scope is amended, whichamendasks for at exit 6 andcheck’s repair names in that order:ank accept <id> --reanchor ank amend <id> --drop-scope "<old>" --scope "<new>" ank accept <id> --rescope
Archiving what is cold
ank archive moves what is cold into .ank/archive/entities/: superseded
documents, and every entry whose subject is cold, meaning a superseded document
or a task done on the default branch (ADR-467ce7e9cda1). check names the verb
in one signal when the hot corpus holds any of it. Like accept, it decides what
the corpus is, so a human runs it, and like accept it commits nothing: it
renames files and stops. Unlike accept, it writes no ref, so the move exists
once it lands, and the commit and its pull request are yours.
git switch main && git pull
git switch -c archive/<date>
ank archive --dry-run # read the list: this is what moves
ank archive # the same list, moved
ank check # green: references, blockers and scopes resolve into the archive
git add -A .ank # git sees each file as a rename
git commit -m "archive what is cold"
git push -u origin archive/<date>
gh pr create --fill --base main --head archive/<date>
gh pr merge --merge
git switch -c archive/<date> puts you on the branch, so here gh resolves the
pull request from where you stand and the bare gh pr merge works.
Run it from a branch cut from the default branch and level with it: an entry is
cold when its task is done on the default branch, which is what the verb reads,
so a local default branch that is behind leaves entries hot that could have
moved. An archived file is never edited afterwards; check verifies it against
the digest it arrived with and reports a changed one as a fault.
Releasing
A release is a tag. release.yml publishes on a pushed v* tag and on nothing
else, because a release that could be produced from a branch would make “the
binary for v0.8.0” a question rather than an answer. Everything a release ships
– the archive names, the npm packages, the release title – derives from the
tag. What makes that safe is that the tree has to agree with the tag before
anything is built.
Bump the version literals
Twelve literals across eight files carry the version, and every one of them must say the version you are about to tag:
crates/ank-cli/Cargo.toml version = "<v>"
crates/ank-core/Cargo.toml version = "<v>"
npm/ank/package.json "version"
npm/ank/package.json the four optionalDependencies pins
npm/ank-linux-x64-musl/package.json "version"
npm/ank-linux-arm64-musl/package.json "version"
npm/ank-darwin-arm64/package.json "version"
npm/ank-win32-x64/package.json "version"
.claude-plugin/plugin.json "version"
You do not have to remember that list. The check that gates the release prints it, with the exact line that repairs each literal, when you hand it a version the tree does not carry:
$ bash .github/scripts/check-version.sh 0.8.1
version 0.8.1 disagrees with 10 of 10 version literals
...
repair every line above, then move the tag:
crates/ank-cli/Cargo.toml: version = "0.8.1"
crates/ank-core/Cargo.toml: version = "0.8.1"
npm pkg set version=0.8.1 --prefix npm/ank
...
and answers version 0.8.1 agrees with all 10 version literals once they are
bumped. Run it before you tag. The bump lands like any change, by pull request,
and Cargo.lock follows the two manifests on the next build.
The same script runs on every pull request against fixture trees, as the
version check job, so a bump that touched six of the seven files is red on the
branch that made it and not on the tag (CI jobs and required
checks).
Rehearse with a dispatch
release.yml also runs on workflow_dispatch, and a dispatch builds the same
five targets and publishes nothing. Run one before tagging whenever the pipeline
itself changed:
gh workflow run release.yml --ref main
The alternative is discovering that the release pipeline is broken at the moment you use it, on a tag you then have to delete, and a tag is the one thing here that is awkward to take back. On a dispatch the version job says there is no tag to compare and skips the comparison, the five builds and the four npm smoke tests run in full, and the two publish jobs do not start.
Tag
With the literals bumped and merged, tag the merge commit on main and push the
tag. The tags so far are annotated, with the version as the first line of the
message and what the release adds under it:
git switch main && git pull
git tag -a v<version>
git push origin v<version>
What the run then does, in order:
- version compares the tag with every literal and refuses before anything is built. A check at the end would already have spent the matrix.
- build runs the tests and packages one archive per target:
x86_64-unknown-linux-musl,aarch64-unknown-linux-muslon an arm64 runner,aarch64-apple-darwin,x86_64-apple-darwinon an Intel runner, andx86_64-pc-windows-msvc, each with a.sha256. - npm smoke installs the assembled packages from their tarballs on four platforms and checks the wrapper answers like the binary.
- publish creates the GitHub release from the five archives, only once every build row passed. A release carrying four targets out of five would look complete.
- publish-npm publishes the four platform packages and then the wrapper, only once every smoke row agrees.
A version with a prerelease suffix, v0.9.0-rc1, publishes under the npm
dist-tag next and as a GitHub prerelease, so it is installable by whoever asks
for it by name and never becomes what a bare npm install -g @haksolot/ank
resolves to. Anything else publishes as latest.
Trusted Publishing
publish-npm holds no npm credential. It runs with id-token: write, and npm
exchanges the job’s OIDC token for a short-lived publish credential, so
the pipeline uses no secret at all: the GitHub release is
created under the workflow’s own token, and the registry attaches provenance to
every package it receives.
npmjs.com decides whom to trust, per package. Each of the five packages,
@haksolot/ank, @haksolot/ank-linux-x64-musl,
@haksolot/ank-linux-arm64-musl, @haksolot/ank-darwin-arm64 and
@haksolot/ank-win32-x64, names GitHub Actions as its trusted publisher
under Settings → Trusted Publisher, with the owner haksolot, the repository
ank and the workflow file release.yml. Renaming that file, or adding a
sixth package, means adding the new name there before the next tag, or that
package’s publish is refused.
The same page carries Allowed actions, and it has to allow publishing
directly. npm always allows a staged publish, which waits for somebody to
approve it on the website, and adds a direct publish only when that box is
ticked. A trust left at its default answers this job with 403 Forbidden ... OIDC permission denied for this action, after the job has already signed its
provenance, so the error reads as an authentication that succeeded. Managing
dist-tags can stay off: --tag is applied by the publish itself.
A refused publish fails publish-npm alone. The GitHub release still
publishes, because the release page is the primary channel and npm a
convenience on top of it. Re-run the failed job once npmjs.com is corrected:
the rerun replays the workflow of the tagged commit, so a fix to release.yml
itself reaches npm only with the next tag.
After the release
ank update --check against the new tag should report it as latest, and the
installers read the release page directly, so both routes serve it as soon as
the release exists. Nothing else is published: no package manager ships ank
(Install says why).
CI jobs and required checks
Four workflows run on this repository. Three of them run on every pull request
and on every push to main; the fourth runs on a tag.
The required checks
The ruleset on main requires six checks by name, and a pull request cannot
merge until each of them is green:
ubuntu-latest the three gates, on Linux
macos-latest the three gates, on macOS
windows-latest the three gates, on Windows
version check / ubuntu-latest release.yml's version check, against its fixtures
msrv / ubuntu-latest the workspace builds on the declared MSRV
msrv is tight / ubuntu-latest the minor below it does not
The three gates are the ones CONTRIBUTING.md asks you to run locally: cargo fmt --check, cargo test --workspace, and ank check on the repository’s own
corpus. The ruleset also allows the merge commit and nothing else, and has no
bypass actors; Ratifying and archiving
says which anchors that still protects.
ci.yml
-
changes, first, says whether the pull request touches anything outside.ank/. It diffs the merge commit against its base and writescode=truewhen any path outside.ank/changed, or on a push, where everything runs. -
test, a matrix overubuntu-latest,macos-latestandwindows-latest, and the three required checks named after them. It checks out the whole history, becauseank checkwalks it, and runs the three gates. Beforeank check, on every event, it fetches+refs/ank/*:refs/ank/*fromorigin, read-only: a ratification made since ADR-5e47007a75be is a ref there,actions/checkoutdoes not fetch it, and a pull request from a fork verifies it the same way as one from a branch here. The Linux leg keeps the binary it built forattest.The suite runs under the
ciprofile of.config/nextest.toml, which runs every test to the end and bounds each one at 600 seconds, about twice the slowest test that passes (the bound and the measurement are written beside the setting). A lineSLOW [> 60.000s]in the log is a test still running at that mark and is not a failure. A lineTIMEOUTis a test nextest killed when it reached the bound: it counts as a failure, the leg is red, and the line names the test. Read it as a hang, a test waiting on something that will never come, rather than as a slow runner, and look at that test on that platform before rerunning the job. -
attest / ubuntu-latestruns on a push tomainonly, after the matrix. It anchors every taskcheckreports asdone with no test proofto this run, withank attest --proof test:<run-id> --detached, and it is the only job in the file that holdscontents: write. It turns red rather than skipping when the proof does not reach the remote. The recipe it follows is Anchoring a run. -
version check / ubuntu-latestruns.github/scripts/check-version-fixtures.sh, the release’s version check exercised against fixture trees on every pull request instead of only on a tag (Releasing). It has no local equivalent other than running the script:bash .github/scripts/check-version-fixtures.sh -
msrv, a three-platform matrix building on the declared minimum Rust version. Only its ubuntu leg is required, because the floor is one number for the workspace; the other two legs run and report, and they are what would catch a floor that differed per target. -
msrv is tight / ubuntu-latestrequires the minor below the floor to fail. Both MSRV jobs are The MSRV.
A pull request that changes only .ank/ runs the ubuntu leg whole and nothing
else. The corpus is judged by ank check, which that leg runs, and by the
tests that read the live repository, which that leg runs too; the macOS and
Windows legs, both MSRV jobs and the version check have nothing to learn from a
corpus diff, and would cost it thirteen minutes. They are skipped by a condition
on the job, or on every step of a matrix job, never by a paths: filter on the
workflow: a job skipped by its condition reports success to the ruleset, where a
workflow filtered out leaves its required checks pending and the pull request
unmergeable. docs/ counts as code: the suite replays the pages.
Pull request runs superseded by a new push are cancelled. Runs on main are
queued and never cancelled, because two attest jobs racing on
refs/ank/proof/* would turn an intermediate merge red while the head of main
is green.
docs.yml
Builds this site with mdBook, pinned by version and by the digest of its release
archive, on every pull request, and checks that every internal link and fragment
resolves in the built site. A push to main also deploys it to GitHub Pages; a
pull request never does. It is not a required check, and a red build still
blocks nothing but the site.
install.yml
Tests install.sh and install.ps1 against the published release, on the
platforms each claims to install, including macos-15-intel, which no other
workflow carries. It asserts the two things neither installer may ever do:
unpack an archive whose hash does not match, and end in silence on a platform it
has no archive for. It reads the release page and writes nothing.
release.yml
Runs on a pushed v* tag, and on workflow_dispatch as a rehearsal that builds
and publishes nothing. Its jobs are version, build, npm-smoke, publish
and publish-npm, and Releasing walks them in order.
The MSRV
The minimum supported Rust version is measured, never chosen. It is the oldest toolchain the workspace builds on, found by walking toolchains upward against the tree, and it moves when a dependency moves it.
Where it is declared
rust-version is declared in every crate of the workspace, six manifests
carrying the same number:
crates/ank-contract/Cargo.toml
crates/ank-core/Cargo.toml
crates/ank-cli/Cargo.toml
crates/ank-mcp/Cargo.toml
crates/ank-daemon/Cargo.toml
crates/ank-tui/Cargo.toml
What enforces it
Two CI jobs, both required on main (CI jobs and required checks):
msrv builds on the declared toolchain, proving it is sufficient, and msrv is tight requires the minor below it to fail, proving it is not higher than the
tree needs. Both read the number out of a manifest rather than carrying it, so
neither job is edited when the floor moves.
They read two of the six, crates/ank-cli/Cargo.toml and
crates/ank-core/Cargo.toml, and msrv fails when those two disagree. Nothing
compares the other four, so moving the floor means moving all six by hand, and
the two directions fail differently. A manifest left above the new floor is
caught, because msrv builds on the declared toolchain without
--ignore-rust-version and cargo refuses the package outright, with rustc <running> is not supported by the following package. One left below it is
caught by nothing, and goes on declaring a floor the workspace no longer has.
Moving it
Never edit that number to make a build pass. The floor is a consequence of a dependency, not a target held on purpose, and re-measuring means re-running the walk, one toolchain at a time from the current floor upward:
cargo +<toolchain> build --workspace --locked --ignore-rust-version
The first toolchain that builds is the floor. Write it into all six manifests,
in one change, and let both jobs confirm it: msrv that it builds, msrv is tight that the one below does not.
An unexpectedly successful build on an older toolchain names a number to lower. It does not lower it. If a job goes red here, read the diagnostic and open an issue or a task; the walk is what decides, and a human runs the walk.
Signing keys
A ratification is a tag object at refs/ank/ratify/<id> (a commit, for one
made before ADR-5e47007a75be), and a signature is what makes it answerable to
somebody. Signing is a regime the corpus is in, not a precondition of ratifying
(ADR-964be4d940b2): ank accept writes a signed tag where the repository is
configured to sign, and an unsigned one where it is not, and it never refuses
for want of a key. What changes is what ank check can say about
the result. The rules it applies, and the four outcomes it keeps apart, are
section 8 of the specification, in Proof, anchoring and
authority; this page is how to set a repository up so they
apply.
Until a key is declared
A corpus that declares no key says so, once, as a signal on signers:
no ratification key declared: permissions are advisory, not enforced (§8).
That is one of the lines the quickstart ends with. It is honest rather
than wrong: every ratification is still anchored by its hash, and nothing
pretends a signature was checked. Declaring a key is what turns it into a check.
Sign your commits
The set-up is git’s. With an SSH key, which git has signed with since 2.34:
git config gpg.format ssh
git config user.signingkey ~/.ssh/id_ed25519.pub
With OpenPGP, gpg.format stays at its default and user.signingkey names the
key id. accept signs whenever the repository can: when user.signingkey is
set, or commit.gpgsign is true. It does not wait for commit.gpgsign,
because a maintainer who signs selectively still means a ratification to be
signed, so whether your ordinary commits are signed is yours to decide; check
only ever judges the ratifications.
Declare the key under signers:
The keys allowed to ratify are declared in .ank/config.yml, under signers:,
keyed by principal (ADR-5c6db7a161b8). Each key carries git’s <keytype> <key>
form, an optional note, and an optional valid_before date:
signers:
marie@example.com:
keys:
- key: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...
note: laptop
sean@example.com:
keys:
- key: gpg 0123456789ABCDEF0123456789ABCDEF01234567
note: release key
- key: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAJ...
note: lost on reinstall
valid_before: 2026-10-11
The key type names the format. An ssh-* entry is the public key itself, its
trailing comment left out; a gpg entry is the full fingerprint or the long key
id. config.yml is versioned like any other file, so declaring a key is a diff
in review, and it lands on main by pull request before the key it declares can
ratify anything there.
The block has one writer, and it is not ank config. Declaring who may
ratify is a trust act the skills reserve to a human, as they reserve accept:
ank config signers.* is refused and names ank signers, which writes only the
lines of its change and leaves every comment, order and quoting elsewhere in
config.yml as it was.
A new machine
A key that is not declared ratifies nothing, so a new machine is declared before
it ratifies, and the declaration lands on main the way any change does. With
git set up to sign on that machine, as above, from a branch cut from main:
git switch -c signers/laptop main
ank signers add --note "laptop"
add declares the key user.signingkey names, under the principal
user.email names. --key takes a public key file or '<keytype> <key>'
instead, --principal another principal, and --note what a reviewer should
know about the key. A key already declared, under any principal, is refused at
6 and nothing is written. add commits nothing: review the diff, then land it
by pull request:
git diff .ank/config.yml
git commit -am "Declare the laptop key"
git push -u origin signers/laptop
gh pr create --fill --base main --head signers/laptop
Until that pull request is merged, a ratification signed on the new machine is
judged against the signers: that main holds, and the key is not in it.
Retiring and removing a key
ank signers retire 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAJ...'
ank signers retire 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAJ...' --date 2026-10-11
retire sets valid_before, today in UTC or the date --date names. remove
deletes the key outright:
ank signers remove 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAJ...'
Both take the key as signers: declares it, <keytype> <key> or the key alone,
and both land by pull request, as add does.
A key is retired by date rather than removed. With valid_before set, the
key ratifies nothing committed from that day on (midnight UTC), and what it
signed before stays verified. Removing a key instead turns every ratification it
signed into a fault, which is the act for a compromised key and the faults it
raises are the point: the committer date is chosen by whoever signs, so a stolen
key can still sign a backdated commit that a date would accept.
check reads signers: and nothing else, for both formats. Under
gpg.format = ssh it hands git an allowed-signers file it generates from the
block, each valid_before written as git’s valid-before option, and judges
the date itself as well, so a git that does not honour the option still refuses
a retired key. Under OpenPGP git never reads an allowed-signers file at all, so
check matches the fingerprint and judges valid_before against the committer
date itself. Your repository’s own git configuration is never changed: git verify-commit goes on resolving signatures the way you set it up.
Coming from .ank/allowed_signers
Before signers:, the keys were declared in .ank/allowed_signers, in git’s
allowed-signers layout. check no longer reads that file, and reports one that
is still present as a fault naming the command that moves it:
ank signers migrate
It writes every key of the file under signers:, keyed by its principal, keeps
the comment lines above a key and the comment after it as that key’s note,
carries a valid-before option as valid_before, appends the block without
touching a byte above it, and deletes the file. It commits nothing: review the
diff and land it by pull request like any other change to config.yml.
What check says afterwards
Once a key is declared, check judges every ratification against signers:,
a tag through git verify-tag and an older commit through its own signature,
and keeps four outcomes apart, which section 8 of the specification lists with
the reason for each. The one to expect on a machine that is not yours is
the signal and not the fault: a CI runner without your public key is a correct
repository on an incomplete machine, and check says it could not verify rather
than either failing or passing it.
A ratification made before ADR-5e47007a75be is a commit, and merged by squash or rebase it loses what this page set up; the merge method that keeps it is Ratifying and archiving. A tag travels as a ref and no merge method touches it.
Re-recording the demo
The README opens on a recording of the loop: ank context, ank graph, a claim,
the code change, and ank done. It is a function of three scripts in
assets/demo/, so a retake is a re-run and not a performance, and it goes stale
whenever the output it shows changes.
assets/demo/setup.sh builds the demo repository the recording is made in
assets/demo/play.sh what the recording plays, command by command
assets/demo/render.sh renders the cast to the two images the README shows
assets/demo/demo.cast the last recording, as asciicast v2
What the scripts expect
They were written for one machine and say so in their first lines, rather than taking arguments:
- the repository checked out at
~/ank, and built withcargo build --release, because bothsetup.shandplay.shrun~/ank/target/release/ank; ~/demofree:setup.shdeletes and rebuilds it, and writes a throwaway SSH signing key to~/demo-signso the ratification in the recording is signed;- agg on the
PATHor in~/.cargo/bin, and JetBrains Mono in~/fontsor in the directoryANK_DEMO_FONT_DIRnames.render.shrefuses at exit 9 and prints the install command when either is missing, rather than falling back to another font without saying so.
Retaking it
cargo build --release
bash assets/demo/setup.sh
asciinema rec --cols 100 --rows 34 -c "bash assets/demo/play.sh" assets/demo/demo.cast
bash assets/demo/render.sh assets/demo/demo.cast assets
setup.sh ends by printing ank graph and ank context on the fresh demo
repository; read them before recording, because they are the state the
recording starts from. The cast is recorded at 100 by 34, the size the current
one declares. render.sh writes assets/demo.gif in Catppuccin Latte and
assets/demo-dark.gif in Mocha, which the README picks between with
prefers-color-scheme.
GIF and not SVG, and that was measured. An SVG rendering of a cast animates
when the SVG is inlined into a page and not when it is loaded through an
<img>, which is the only way a README can embed it, so it showed an empty
terminal. play.sh keeps to the eight ANSI colours for the same kind of
reason: a 256-colour escape would come out of the terminal’s palette instead of
the theme render.sh hands agg.
Commit the cast and both images together, and update the image’s alt text in
the README if what the recording shows changed.
Project conventions
The rules a change to this repository is held to beyond the three gates in
CONTRIBUTING.md.
The binding ones are ratified ADRs, and ank context <path> serves them in full
for the files you are about to touch; this page names where each one lives
rather than restating it.
Working the loop on this repository
The development plan lives in .ank/, and it is worked with the same loop
the quickstart teaches: ank context, ank claim, ank log,
ank done. The corpus is reached through the CLI and never by opening its files
(ADR-3c8d94a0bbe0): ank show <id> gives an entity whole, ank find lists,
ank context binds, and scope, graph, status, review, check and the
read form of log answer the rest. Which verbs write is not a list that ADR
keeps, because a list went stale once per new route: every verb declares it, and
ank help --json carries it as writes, one of nothing, files, refs or
both, held by a test to what the verb leaves on disk. It constrains agents, not
people: a human with an editor keeps every power they had, and ank check
remains what notices.
A task here declares its verifiers when it is written, and a plain ank new task already carries one test verifier per workspace crate, test-ank-cli,
test-ank-core and the rest, with fmt-check, which .ank/config.yml marks
default (Proof and verifiers). Each declares the
files it reads, so done reruns the crates a change reaches and reuses the
others.
Changing the format
The format is the specification, and ank-core is its reference
implementation. Every format change happens in this order, and it is ratified
(ADR-63b59c5c26f7):
- the specification: the
specdocument that states the rule, which for a format change is The data model (the specification). No field exists in the code without existing there first. - the goldens:
crates/ank-core/tests/golden/.valid/must round-trip byte for byte once normalised,invalid/must be rejected with the expected error. - the code.
The round-trip is byte-identical on canonical form; valid but non-canonical input is read correctly and normalised on first rewrite. CRLF is read, never written, and one golden is in CRLF on purpose and must come back in LF.
Documentation
Documentation a person reads lives in docs/, changes by pull request, and is
published as this site (ADR-33970fcdb6e8). A block presented as what ank prints
is replayed against the binary by crates/ank-cli/tests/doc_replay.rs, and a
reference table is generated from the source table it describes
(ADR-2b62b9a1fe67): the exit codes, the entity fields and the config.yml keys
each carry the command that regenerates them in their first lines. A normative
rule is linked, never restated.
Testing
A criterion that talks about the binary is tested through the binary. When a
done_criteria says “the binary does X”, the test invokes the binary, not only
the function meant to produce X. Two real defects shipped past green unit tests
that way. The same rule applies to platforms: OS-dependent behaviour is not
verified until it has run on all three.
English only
English is the only language of the project (ADR-d3a8dcf38817): prose, identifiers, comments, CLI output, error messages, entity titles, bodies, slugs and log entries. Non-English text is a finding, not a matter of taste. The one exception is a string whose meaning is its literal value: an external proof reference, a quoted third-party message, a fixture asserting a byte sequence.
Style
- Self-correcting errors. Every refusal prints the exact command to run next, never generic help.
- Terse output, in the shape of
git status.--jsoneverywhere, strictly opt-in, and never colored. - No emojis in messages, documentation or comments.
- No new dependency without necessity. A static binary is the goal.