00 — The executable dev brief

Summary

Written to be executed by a developer agent, not just read: the grounding reads in order, the six rules that override convenience, non-negotiable implementation constraints (fixed plaintext allow-list, fail-soft per object, unconditional hash verification, localhost-only serve, writes raise), a definition of done every phase must meet, and an explicit list of what is not the developer's to decide. The 18–19 Aug revision added the sixth rule — publishing never changes the vault — and phase P4b for the published API docs.

Key concepts

• The six rules — byte-identical ciphertext everywhere; the key never reaches a server; keyless custody; byte-identical loader; plaintext only where the key is published; publishing never changes the vault
• The plaintext allow-list — fixed in code, never pattern-derived — otherwise anyone who can write to the vault can move a file into the plaintext surface by naming it
• Not yours to decide — wire formats, key formats, the six open decisions, the loader's JavaScript

Key ideas

• Phases are independently shippable: take one, finish it green, open a PR.
• If a change weakens one of the five rules, it is wrong even if the tests pass — stop and raise it.
• When the spike disagrees with the spec: the spec wins for behaviour, the spike wins for proof it is possible.

Read the document