What didbot has built and what it is building. One file per epic. milestones.md is the other view of the same work: releases worth naming, in prose, and the only place a milestone is named.

An epic is a line of work that takes many pull requests and has an exit criterion somebody could check. The tasks live inside it.

Where the reasoning goes #

In the epic, beside the work it justifies. There is no separate decision log: there was one, it reached fifty-odd entries before anything shipped, and what it mostly recorded was reasoning about things that turned out not to exist. An entry is only as good as the fact under it, and nothing checked the facts.

This directory is checked. The frontmatter builds the tables, the links have to resolve, and an epic points at work that either exists or does not — so a claim about something imaginary shows up as an item nobody can close. Reasoning that cannot survive next to the work it is about was not load-bearing.

The invariants the whole system rests on are in the repository's README, which is short on purpose.

The capabilities #

The epics are a decomposition of one list, written by the project's owner: a conformant personal data server; ephemeral did:web accounts for agents; lineage, model and execution environment tracking; third-party OAuth login for those accounts; management of which scopes may be requested, which apps may be granted anything, and which agents may write which record types; a dashboard for that policy, with the policy stored in the owner's own personal data server; bidirectional ownership verification; atproto private spaces; lexicons for recent activity and mentions; a firehose indexer; a frontend for public and private activity; and a local development workflow with simulated agent traffic.

That list is the mandate. Where anything here disagrees with it, the list wins and the epic is what changes.

The id is the commit scope #

Each epic's filename is its id, and that id never changes. plan/pds-writes.md is pds-writes, so its commits read feat(pds-writes): …. That is why the ids have no number prefix and why there is no order field: an identifier that has to be rewritten when something else moves is not an identifier. Archiving moves the file and never renames it.

plan is a valid scope too, for changes to this register.

Order is advisory #

The tables read top to bottom and that is the whole of the ordering. What constrains the work is dependsOn, which says what genuinely cannot start first, and status, which says what is blocked.

The sequence comes from order.txt, a list of ids and nothing else. An epic it does not name still appears, alphabetically, at the end of its table.

Status #

shipped — the exit criterion is met. Nothing is shipped yet. Several epics have most of their work done and a demonstration running, which is not the same thing: an epic ships when a stranger could check its exit criterion, and none can be checked until records are real. The file stays after it ships, and moves to complete/ when nothing is left open in it.

open — being worked on or ready to be. Everything is, including the four with long ## Done lists.

blocked — cannot start until something in dependsOn lands. One epic is blocked on something outside the project: spaces waits on a specification that still calls itself a proposal.

continuous — no exit criterion. Worked whenever adjacent code is open.

declined — decided against. Not blocked, which is waiting. The file stays, because a decision that is not written down gets made again.

The tables are generated #

The five tables below are output. scripts/gen-plan-readme.py reads every epic's frontmatter and rewrites what sits between the  fences; everything outside a fence is hand-written and passes through untouched. The plan-register prek hook runs it with --check, so a row that disagrees with the file it points at fails the commit.

Adding an epic is one file and one command: write plan/<id>.md with the same frontmatter keys, run scripts/gen-plan-readme.py, and stage both.

The structure and both scripts come from lance.blue's headquarters repository. The one difference is that an epic names crates rather than repos.

Complete #

Nothing open, nothing left to decide. These live in complete/, which does not exist yet.

id	title

Shipped, with loose ends #

The exit criterion is met and something is still open in the file. Nothing yet.

id	title

Open #

id	title	status
provenance	A record says which agent, which model, and what spawned it	open
pds-writes	A record is a signed commit in a repository	open
agent-accounts	An agent context becomes an account, and stops being one	open
account-types	Not every account is a session	open
scrobble	An agent says what it is working on, and the statement is its own record	open
write-policy	Which agents may write which record types	open
auth-types	Every credential this server accepts, and what each one may do	open
oauth	A third-party app signs in as an agent, with nobody at the consent screen	open
pds-xrpc	A client nobody here wrote can talk to this server	open
federation	An off-the-shelf relay and an off-the-shelf app, not just the protocol	open
credentials	A session gets a credential without a wrapper process	open
cred-delivery	A credential reaches the harness, and the model never holds it	open
node	A host proves what it is once, and issues credentials to the sessions on it	open
subagents	What a distinct subagent identity would buy, and what a harness lets you enforce	open
harnesses	What a harness has to provide for any of this to work	open
scope-policy	An agent cannot be granted what its owner has not allowed	open
ownership	The human names the agents and the agents name the human	open
vouch	What an owner vouches, what an agent vouches, and what the server vouches	open
attestation	Where an agent was provisioned from is a claim somebody else signed	open
labels	What is true about an agent arrives as a label an app already draws	open
agent-sites	An agent publishes a page of its own, at a name the zone already serves	open
policy-store	Policy is the owner's record, in the owner's repository	open
ai-preference	A stranger's declared AI preference is a ceiling on what our agents may do	open
app-allowlist	An app an owner has not admitted gets nothing	blocked
e-stop	An operator can halt the swarm when nothing else is working	open
policy-dashboard	The owner writes policy from a site this server does not run	blocked
ops-dashboard	A human can see what their agents are doing and stop them	blocked
mentions	One agent addresses another, and the other finds out	blocked
spaces	Activity that is not public, without inventing a private tier	blocked
repo-scale	A write costs the same in an old repository as in a new one	open
store-scale	The state is larger than the process holding it	open
zone-scale	The zone runs out of names before it runs out of accounts	open
capacity	A deployment stops minting before somebody else's quota does	open
dev-setup	One command takes a new machine to a working stack	open
config	How the server runs is one file; what an agent may do is never in it	open
deploy	A named version runs somewhere that is not a laptop	open
alerts	The server says when it is failing, somewhere its operator will see it	open
dns-providers	A deployment publishes its zone somewhere other than Route53	open
tls-sources	A certificate comes from somewhere other than this server's own ACME client	open
services	The component that can mint a hostname is not the component serving agent data	open
fleet	One operator runs ten personal data servers and can see and stop all of them	open
adversarial	Integration tests at the seams, not inside the components that already pass	open
license	The project has no license, and three different things need one	open
cost	What a deployment costs its operator, broken out by service	open
aws-deploy	A one-shot Terraform module an operator can consume without cloning this	open
cli	Six binaries with six naming conventions, and no way for anyone else to add a seventh	open
did-minting	The server mints the identifier, not its caller	open
handshake	A server and its operator establish each other, with no shared secret	open
name-pools	A zone is a pool with a role, and names leave it only when its role allows	open
onboarding	An operator establishes a server before the server can establish anyone else	open
onboarding-policies	A new operator is shown policies worth having, not an empty ruleset	open
policy	What an agent may do is a set of denials, evaluated at the write, from three sources	open
site	A stranger can read what this project is, without cloning it	open
stamp-contract	The hook stamps a tool it was told about, and the tool reads a contract it can name	open
updates	The project says what it has done, where the network can read it	open
witness	A stranger can check a `bot.did.registration` claim against something the server does not control	open

Continuous #

id	title
local-dev	The whole stack runs on one machine, with traffic that looks real

Not pursued #

Answered no. Nothing yet.

id	title
index	One service watches every vouched server and says what changed
canvas	A person can watch a swarm work

Where the lexicons are #

There is no lexicon epic. A bot.did.* schema is a deliverable of whichever epic needs the record. Doing it the other way round publishes a collection name nothing ends up using, and a collection name cannot be taken back once records exist in other people's repositories.