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 operator's own personal data server; two-way operator 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. Most of the work done and a demonstration running is not the same thing: an epic ships when a stranger could check its exit criterion. 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, whatever its ## Done list holds.

blocked — cannot start until something in dependsOn lands. Two epics are blocked on something outside the project: spaces waits on a specification that still calls itself a proposal, and abuse-notices on a proposal that says nothing in it is finalised.

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.

id	title
cli	One `didbot` command, and a binary for each place the code runs

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
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
node	A host proves what it is once, and issues credentials to the sessions on it	open
subagents	A subagent is a context, so it gets an account	open
scope-policy	An agent cannot be granted what its operator has not allowed	open
ownership	The human names the agents and the agents name the human	open
vouch	What an operator 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 operator's record, in the operator'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 operator has not admitted gets nothing	blocked
e-stop	An operator can halt the swarm when nothing else is working	open
policy-dashboard	The operator onboards a server and writes policy from a site this server does not serve	open
ops-dashboard	The operator watches a running server and stops it, from a page nobody else can operate	blocked
analytics-dashboard	What this deployment's agents are doing, on a page the operator may make public	open
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
cred-delivery	A write is bound to the context that made it, and the model holds nothing	open
abuse-notices	A stranger's moderation service can tell this server one of its agents is doing harm	blocked
account-data	Every byte an account produces has one answer for when it goes	open
account-lifecycle	An account's whole life is one reviewed state machine	open
blob-storage-tiers	A blob lives on disk, in a bucket, or in both, and a deployment picks	open
cedar-engine	Cedar is the second engine, and it never permits by accident	open
dedupe-audit	A workspace-wide sweep for drifted duplicate logic, dead code, and stragglers from removed backends	open
did-minting	The server mints the identifier, not its caller	open
didjson-archive	The identity layer has a copy that is not the running server	open
handshake	A server and its operator establish each other, with no shared secret	open
heartbeat	One line an operator reads at a glance, that cannot grow	open
infra-review	What a first read of infra/ found, and what has to change before an apply	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
periodic-backups	The server backs up its own data, and something reads it back	open
policy	What an agent may do is a set of denials, evaluated at the write, from three sources	open
policy-exemptions	A policy can leave someone out without anyone being able to let themselves in	open
site	A stranger can read what this project is, without cloning it	open
tombstone-serving	An account outlives the server that answered for it	open
updates	The project says what it has done, where the network can read it	open
web-launch	Checkers run by somebody else pass against the live deployment	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.

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.