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.