Foundry › Docs
Foundry is a governance kernel for AI agents that write code. It runs today as the manual lane: an operator admits a ticket, hands each work packet to an agent and records submit, review and settle through Core's durable store. It launches nothing.
The docs form a tree. Read from the top and stop as soon as you have what the task needs. LLM agents: do not preload. Read the layer above, then open only the one document your task names.
| Layer | What it is | Load when |
|---|---|---|
| 0 | README: what Foundry is and is not, where it is headed | always, once |
| 1 | How Foundry works: every mechanism in plain terms, plus the glossary. This index. | you need the mechanism or a word defined |
| 2 | Live reference: describes the code on main, kept current |
your task touches that area |
| 3 | Authority: the backlog and the contract, binding on every change | you pick, change or accept a ticket |
| 4 | Direction and design ahead: strategy and designs for code that does not exist yet | you make a design or investment choice |
| 5 | Dated records: reviews and designs kept because code or tests cite them | you need the history behind a specific decision |
Every document opens with a breadcrumb back to this page. A dated or design document says its status in its first lines: read that before trusting its body. When a document and the code disagree, the code is the fact, and the document needs a fix.
| Task | Read |
|---|---|
| Understand what Foundry is | README, then How Foundry works |
| Run a ticket through the lane | Lane runbook |
| Resume the current campaign | Dogfood log handoff, then the runbook, then the agent brief |
| Pick the next ticket | Repair plan: the sole backlog. It owns ordering, not any older sequence |
| Change any code | AGENTS.md, then the boundary rules |
| Write Elixir code or tests | Elixir conventions and the vendored Phoenix rules |
| Add or change a guard, transition or refusal test | Evidence tools, then the coverage-guided sweep |
| Delegate work to an agent | Agent brief |
| Build or run the gate | CI and ci/run.exs |
| Understand the durable store | Durable store, then the generated schema reference |
| Observe a running lane | Observability |
| Understand execution authority | Workflow contract |
| Check a protocol against its formal model | Ledger, Core boundary, FR-10 effects |
| Make a direction or investment choice | Strategy working summary. It is context, not permission to bypass the plan or the contract |
| Rebuild a capability the deleted daemon had | Moved knowledge |
| Document | What it covers |
|---|---|
| How Foundry works | transport, lane, kernel, Core, principals, refusals, recovery, containment; glossary |
| Lane runbook | start and stop the daemon, every lane command, refusals, recovery, logs |
| Dogfood log | the operator's record: handoff, ticket table, decisions (Q), frictions (F), scorecard |
| Agent brief | standing clauses every delegated task inherits |
| Boundary rules | the decoupling rules and the test that enforces each one |
| Durable store | the SQLite authority store: gateway, initialization, recovery, versions |
| Schema reference | generated from database.ex; a test fails if they drift. Do not edit |
| Observability | the three read-only surfaces, and what was deleted |
| CI | the standalone gate and its provenance manifest |
| Evidence tools | generative checks of a guarded reducer against its written contract |
| Coverage-guided sweep | the guard mutation sweep and its gate design |
| Elixir conventions, Phoenix rules | coding rules (the Phoenix file is vendored verbatim) |
| Ledger spec, Core boundary spec, FR-10 effects spec | Quint models and what each proves |
| Document | What it owns |
|---|---|
| Repair plan | the sole backlog: every FR ticket, status, dependencies, acceptance, amendments |
| Workflow contract | FR-06: identities, transitions, budgets, isolation, integration, activation. Tests parse its tables |
A review's approval applies to its named candidate only. It does not endorse later revisions or show that a protected route is active.
None of these change the plan, the contract or runtime behaviour. Each says so in its first lines.
| Document | What it covers |
|---|---|
| Strategy brief | investment direction: models direct and the kernel governs; compose before build |
| Product strategy | mission, post-repair initiatives I-F1 to I-F5, open decisions |
| Validation, Research register | how success is measured; external sources checked |
| Orchestrator boundary | replaceable controllers over one authority plane |
| Portable governance contract | proposed first milestone semantic facts, trust boundary and protected accepted ref |
| Portable custody | proposed first-host service account, caller authentication and isolation acceptance |
| Portable custody reconciliation | proposed bounded revoked-issuer operator evidence and atomic original-packet result protocol; not implemented |
| Portable autonomous review amendment | independently approved design-only generic scoped attestation and preauthorized ordinary exact-ref promotion; implementation review and real-host gates outstanding |
| Portable packet provenance | independently approved design-only finite role-neutral packet contract and pre-import producer seal; implementation/host gates outstanding |
| Portable custody packet binding | independently approved design-only generic atomic original-result transaction using reviewed finite packet provenance; not implemented |
| Portable custody operator ingress | Q27 full-range independently approved design-only operator login/input and FD containment; earlier P1 verdicts unchanged; implementation and real-host proof pending |
| Ecosystem boundary | what Foundry owns and what it reuses |
| Workflow profiles, Planning strategies | project-declared workflows; model-proposed plans |
| Pi harness, Jido harness | FR-09 harness candidates |
| AX substrate, Cloudflare OS | execution backend and resource-broker candidates |
| FR-10 design | owned effects and reconciliation |
| Decompose gateway, Decompose protected primitives | approved batch C2 splits of two Core modules |
| O0 authority inventory, O1 sequencing | the orchestrator seam, step by step |
These are true at the commit they name, not necessarily now. They stay because code, tests or live docs cite them.
| Document | Why it is here |
|---|---|
| Bounded effect query | the FR-18A read interface's design, now implemented; cited by observability |
| Dogfood readiness | the thin-dogfood decision and the lane's accepted risks |
| Thin lane design, its review | the lane's design; tests cite it |
| Moved knowledge | edge cases of the deleted daemon and which of FR-09 to FR-13 owns each |
| FR-08 files | kernel and Core designs, specs and fixtures that tests read |
| Clean-room sweep, FR-23 split, worktree inventory | the FR-23 clean-up audit and plan |
batch-d/reviews/ |
one review per lane ticket, linked from the dogfood log ticket table |
Everything else that is dated (audits, candidates, attestations, retired mechanisms, the
implementation log, the pre-split meta-harness proposal) is at tag records/2026-09-24
(docs/archive at the tag).
- A new document gets a breadcrumb line under its title, a status line if it is dated or design-ahead, and a row in the layer table above.
elixir bin/check_docs.exsfails on any relative link that does not resolve, or any#anchorthat names no heading in its target.- AGENTS.md applies to every provider. That neutrality does not relax launch policy, billing authorization, review identity or backend conformance.