feat(deed): family-level DEED grammar specification (v0.1.0 DRAFT)

deed/README.adoc

@@ -0,0 +1,69 @@
+// SPDX-FileCopyrightText: © 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+// SPDX-License-Identifier: CC-BY-SA-4.0
+= DEED — the format family
+:toc: left
+:toclevels: 2
+
+*DEED* is the attestation format for this estate. One extension, `.deed`.
+
+This directory holds the *family-level* specification — the grammar every deed
+shares. The per-format satellites (`meta-a2ml/`, `anchor-a2ml/`,
+`agentic-a2ml/`, …) specify individual documents *within* that grammar and are
+subordinate to it.
+
+== Read this first
+
+[cols="1,3"]
+|===
+| Document | What it settles
+
+| `spec/DEED-GRAMMAR-SPEC.adoc` | Lexical structure, concrete syntax, the four document forms, identity semantics, the self-assertion rule, and the proposed typing chapter.
+| `spec/abnf/deed.abnf`         | The grammar in ABNF, normative for parsing.
+|===
+
+== What DEED is not
+
+[WARNING]
+====
+*DEED is an s-expression format. It is not TOML, and it is not "TOML-like".*
+
+Older text in this repository described the family as "A2ML (Annotated Markup
+Language) TOML-like key-value data formats". That description is *wrong* and it
+is not merely cosmetic: measured across all 35,884 legacy `.a2ml` files, the
+descriptile family had drifted to *0.2%* conformance (10 correct against 5,424
+TOML-shaped), because successive tools read that sentence and generated what it
+described.
+
+The grammar has *no* `key = value` form and *no* `[section]` form. The only
+bracket is `(`. A file using `=` is not a deed.
+
+`RECORD-DIALECT-SPEC.adoc` in `hyperpolymath/a2ml`, which specified that
+key/value surface, is SUPERSEDED by this specification.
+====
+
+== The four document forms
+
+[cols="1,1,2"]
+|===
+| Stem | Head | Meaning
+
+| `estate_chora.deed` | `(estate-deed`       | The estate's vocabulary. One per estate.
+| `*_chora.deed` (except `estate_chora.deed`) | `(repo-deed` | What a repo IS.
+| `ATLAS.deed`        | `(estate-atlas-deed` | The registry of all deeds.
+| `*_praxis.deed`     | `(praxis-deed`       | What a tool DOES.
+|===
+
+The repository pattern explicitly excludes `estate_chora.deed`; dispatchers
+MUST apply the exact estate filename rule before the repository pattern.
+
+Every head requires `:schema-version`.
+
+== Status
+
+v0.1.0 DRAFT. Three rulings were settled by the owner on 2026-09-08 (the
+fourth head, the version field, and the record-dialect supersession); four
+remain open and are listed at the end of the specification.
+
+== Licence
+
+Specification text: CC-BY-SA-4.0. See `LICENSE` files at the repository root.