docs: repoint the hub at the DEED grammar and repair the stale upstream pin

README.adoc

@@ -5,6 +5,33 @@
 // SPDX-License-Identifier: CC-BY-SA-4.0 for documentation
 // SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
 
+[IMPORTANT]
+====
+*The DEED format name and `.deed` extension are final, not A2ML.* Renamed
+2026-09-03, ruled final. Its proposed grammar — syntax, semantics and
+typechecking — is `deed/spec/DEED-GRAMMAR-SPEC.adoc` in
+`hyperpolymath/standards`
+(https://github.com/hyperpolymath/standards/pull/752[standards#752]). After it
+merges, it will be the single normative source; this hub holds a pointer to it,
+never a copy.
+
+DEED `.deed` documents use an *s-expression* format. There is no `key = value`
+production and no `[section]` production; the only bracket is `(`. This syntax
+statement does not apply to retained A2ML v1 material. The stale "TOML-like
+key-value" wording is superseded for DEED — see
+https://github.com/hyperpolymath/standards/pull/753[standards#753].
+
+*This repository is to be renamed `deed-ecosystem`* and restructured to match
+`k9-ecosystem` (tracked as estate task #77). That rename is the owner's trigger
+and has deliberately not been performed here.
+
+*Naming discrepancy, unresolved:* this repository expands A2ML as "Attestation
+Markup Language" (4 occurrences); `hyperpolymath/standards` expands it as
+"Annotated Markup Language" (6 occurrences). Both are in current text. The
+rename to DEED makes the question moot going forward, but the historical record
+should settle on one expansion.
+====
+
 `hyperpolymath/a2ml-ecosystem` coordinates implementations, tooling, CI
 integrations, examples, and conformance fixtures for A2ML.
 
@@ -24,9 +51,15 @@ governance authority are pinned in the https://github.com/hyperpolymath/standard
 
 == Not Owned Here
 
-The A2ML specification is owned by `hyperpolymath/standards`. This hub points
-to `a2ml/SPEC.adoc` there; until the first standards tag is cut, the pin
-is intentionally `TODO-tag`.
+The format specification is owned by `hyperpolymath/standards` and is pending
+until https://github.com/hyperpolymath/standards/pull/752[standards#752] merges.
+This hub will then point to `deed/spec/DEED-GRAMMAR-SPEC.adoc` there -- see
+link:spec/README.adoc[spec/README.adoc] for the pin and its history.
+
+The previous pointer, `a2ml/SPEC.adoc`, was correct when written but went stale
+on 2026-08-28 when commit `24a12d6f` carved `a2ml/` out of `standards` into the
+standalone `hyperpolymath/a2ml` repository. No release tag has been cut, so the
+pin stays unset rather than pointing at a path that no longer exists.
 
 == Machine-Readable Layout
 

deno/.machine_readable/ai/AI.a2ml

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: MPL-2.0
 
 # AI Assistant Instructions
 

deno/0-AI-MANIFEST.a2ml

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: MPL-2.0
 # ⚠️ STOP - CRITICAL READING REQUIRED
 
 **THIS FILE MUST BE READ FIRST BY ALL AI AGENTS**

deno/examples/0.1-AI-MANIFEST.a2ml

@@ -1 +1,2 @@
+# SPDX-License-Identifier: MPL-2.0
 # AI Manifest - Level 1: examples

deno/verification/tests/0.2-AI-MANIFEST.a2ml

@@ -1 +1,2 @@
+# SPDX-License-Identifier: MPL-2.0
 # AI Manifest - Level 1: tests

ex/.machine_readable/anchors/ANCHOR.a2ml

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: MPL-2.0
 # ⚓ ANCHOR: a2ml_ex
 # This is the canonical authority for the a2ml_ex repository.
 

gleam/.machine_readable/anchors/ANCHOR.a2ml

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: MPL-2.0
 # ⚓ ANCHOR: a2ml_gleam
 # This is the canonical authority for the a2ml_gleam repository.
 

haskell/.machine_readable/ai/AI.a2ml

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: MPL-2.0
 
 # AI Assistant Instructions
 

haskell/0-AI-MANIFEST.a2ml

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: MPL-2.0
 # ⚠️ STOP - CRITICAL READING REQUIRED
 
 **THIS FILE MUST BE READ FIRST BY ALL AI AGENTS**

haskell/examples/0.1-AI-MANIFEST.a2ml

@@ -1 +1,2 @@
+# SPDX-License-Identifier: MPL-2.0
 # AI Manifest - Level 1: examples

haskell/verification/tests/0.2-AI-MANIFEST.a2ml

@@ -1 +1,2 @@
+# SPDX-License-Identifier: MPL-2.0
 # AI Manifest - Level 1: tests

rs/.machine_readable/ai/AI.a2ml

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: MPL-2.0
 
 # AI Assistant Instructions
 

rs/0-AI-MANIFEST.a2ml

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: MPL-2.0
 # ⚠️ STOP - CRITICAL READING REQUIRED
 
 **THIS FILE MUST BE READ FIRST BY ALL AI AGENTS**

rs/examples/0.1-AI-MANIFEST.a2ml

@@ -1 +1,2 @@
+# SPDX-License-Identifier: MPL-2.0
 # AI Manifest - Level 1: examples

rs/verification/tests/0.2-AI-MANIFEST.a2ml

@@ -1 +1,2 @@
+# SPDX-License-Identifier: MPL-2.0
 # AI Manifest - Level 1: tests

showcase/.machine_readable/6a2/STATE.a2ml

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: MPL-2.0
 # STATE.a2ml — a2ml-showcase
 project = "a2ml-showcase"
 version = "0.1.0"

showcase/.machine_readable/anchors/ANCHOR.a2ml

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: MPL-2.0
 # ⚓ ANCHOR: a2ml-showcase
 # This is the canonical authority for the a2ml-showcase repository.
 

spec/README.adoc

@@ -1,15 +1,62 @@
-= A2ML Specification Pointer
+= DEED Specification Pointer (formerly A2ML)
 
 // SPDX-License-Identifier: CC-BY-SA-4.0
 
-The A2ML specification is not owned in this coordination hub.
+The format specification is not owned in this coordination hub.
 
-Canonical upstream:
+[IMPORTANT]
+====
+*The DEED format name and `.deed` extension are final* — renamed from A2ML,
+ruled final 2026-09-03. The proposed DEED grammar uses an *s-expression*
+format: there is no `key = value` production and no `[section]` production; the
+only bracket is `(`. This syntax statement does not apply to historical A2ML v1
+inputs. The stale "TOML-like key-value" wording is superseded for DEED.
+====
+
+== Canonical upstream
 
 * Repository: `hyperpolymath/standards`
-* Path: `a2ml/SPEC.adoc` (typed core + markup surface, v1.1.0)
-* Companion: `a2ml/RECORD-DIALECT-SPEC.adoc` (record surface for descriptiles, v1.0.0)
-* Pin: `891b1ed6164478616cb3375f328c6487ccb13f80` (commit pin; no A2ML release tag cut yet)
+* Path: `deed/spec/DEED-GRAMMAR-SPEC.adoc` — the proposed grammar (syntax,
+  semantics, typechecking), v0.1.0. Companion ABNF at `deed/spec/abnf/deed.abnf`.
+* Status: landing in https://github.com/hyperpolymath/standards/pull/752[standards#752].
+  Until that merges this path does not yet exist on `main`; the pin below is
+  deliberately left unset rather than pointed at a stale commit.
+
+== Why the previous pin was stale
+
+This file previously pinned:
+
+  Repository: hyperpolymath/standards
+  Path:       a2ml/SPEC.adoc  (typed core + markup surface, v1.1.0)
+  Companion:  a2ml/RECORD-DIALECT-SPEC.adoc
+  Pin:        891b1ed6164478616cb3375f328c6487ccb13f80
+
+That pointer was *correct when written* — `a2ml/` did exist in `standards` at
+commit `891b1ed6`. It was removed by `24a12d6f` (2026-08-28), *"carve-out: evict
+a2ml, lol and the repo-guardian pair"*, which moved the v1 material into the
+standalone `hyperpolymath/a2ml` repository. The satellite pointer was never
+updated, so from that date this hub pointed at a path that no longer existed.
+
+The measured 0.2% descriptile conformance came from stale "TOML-like" wording
+and files generated from it. A dangling upstream pointer is a separate
+verification risk: while it dangles, nothing downstream can check itself
+against the specification, and each consumer is free to invent its own idea of
+the format.
+
+== Where the v1 material now lives
+
+* `hyperpolymath/a2ml` — the typed core (Idris2), `SPEC.adoc`, and the dialect
+  specifications.
+* `RECORD-DIALECT-SPEC.adoc` retains its current status until
+  https://github.com/hyperpolymath/a2ml/pull/2[a2ml#2] merges; it is not yet
+  marked *SUPERSEDED*.
+* `MANIFEST-DIALECT-SPEC.adoc` in that repository describes the `---`-delimited
+  frontmatter surface of `0-AI-MANIFEST.a2ml` (894 files, 100% conformant). Its
+  disposition under DEED is an *open question* for the owner — it is
+  deliberately not stamped.
+* The existing `.a2ml` validator (`validate-action/validate-a2ml.sh`) and the
+  positive fixtures in `conformance/valid/` are historical v1 inputs, explicitly
+  non-DEED. No migration is required to make that distinction accurate.
 
 The corresponding governance authority is pinned in
 link:../.machine_readable/anchors/ANCHOR.a2ml[ANCHOR.a2ml].

validate-action/.machine_readable/ai/AI.a2ml

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: MPL-2.0
 
 # AI Assistant Instructions
 

validate-action/0-AI-MANIFEST.a2ml

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: MPL-2.0
 # ⚠️ STOP - CRITICAL READING REQUIRED
 
 **THIS FILE MUST BE READ FIRST BY ALL AI AGENTS**

validate-action/examples/0.1-AI-MANIFEST.a2ml

@@ -1 +1,2 @@
+# SPDX-License-Identifier: MPL-2.0
 # AI Manifest - Level 1: examples

validate-action/verification/tests/0.2-AI-MANIFEST.a2ml

@@ -1 +1,2 @@
+# SPDX-License-Identifier: MPL-2.0
 # AI Manifest - Level 1: tests