From 83a79230dc2a0e30ed0dfc03121a0ae2f9ee6de6 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 8 Sep 2026 19:14:09 +0100 Subject: [PATCH 1/3] docs(a2ml): mark the "TOML-like key-value" characterisation superseded by DEED MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The standards repo is where the A2ML format speciation came from. Four satellite READMEs and one format spec told every reader — and every bot — that A2ML was a "TOML-like key-value" format. It is not: the grammar has no `key = value` production and no `[section]` production; the only bracket is `(`. Measured 2026-09-08 across all 35,884 legacy `.a2ml` files: the descriptile family had reached 0.2% conformance to the actual grammar — 10 correct against 5,424 TOML-shaped. That is the downstream cost of these twelve sentences. This commit adds a pointer, not a rewrite. Each affected document gets a WARNING banner naming `deed/spec/DEED-GRAMMAR-SPEC.adoc` as normative; the bodies are left unaltered as the honest record of what was published. Rewriting the prose belongs to the sweep in task #48, and regenerating the templates to task #62. Touched: meta-a2ml/README.adoc (3 statements) ecosystem-a2ml/README.adoc (4 statements) state-a2ml/README.adoc (3 statements) state-a2ml/spec/STATE-FORMAT-SPEC.adoc (1 statement) playbook-a2ml/README.adoc (1 statement) a2ml-templates/STATE.a2ml.template (1 statement, comment pointer) `a2ml-templates/` is a registered LOCAL spec home, so its `source_hash` is regenerated via scripts/build-registry.sh. That is the only registry change; TOPOLOGY.adoc is unaffected. The four satellite directories are not registered homes, so the banners there change no hash. asciidoctor renders all five .adoc files clean. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01QNjWX2B4FffG7zqMBMui6v --- .machine_readable/REGISTRY.a2ml | 2 +- a2ml-templates/STATE.a2ml.template | 6 ++++++ ecosystem-a2ml/README.adoc | 16 ++++++++++++++++ meta-a2ml/README.adoc | 16 ++++++++++++++++ playbook-a2ml/README.adoc | 16 ++++++++++++++++ state-a2ml/README.adoc | 16 ++++++++++++++++ state-a2ml/spec/STATE-FORMAT-SPEC.adoc | 16 ++++++++++++++++ 7 files changed, 87 insertions(+), 1 deletion(-) diff --git a/.machine_readable/REGISTRY.a2ml b/.machine_readable/REGISTRY.a2ml index ebf83637..cc73f9f5 100644 --- a/.machine_readable/REGISTRY.a2ml +++ b/.machine_readable/REGISTRY.a2ml @@ -279,7 +279,7 @@ name = "A2ML Templates" stream = "integration" home = "a2ml-templates/" canonical_doc = "a2ml-templates/STATE.a2ml.v2.spec.adoc" -source_hash = "sha256:ff30b8e1e7c5d4dcf12d17789e40064b632c92bca3d8c2f891f109dc9157dc4a" +source_hash = "sha256:16fc9e6b38b1bf06a3fdc1069127af42985562381f3ef126d0dcd0370f774783" route = "copy-in templates for the 7 A2ML files" [[spec]] diff --git a/a2ml-templates/STATE.a2ml.template b/a2ml-templates/STATE.a2ml.template index b9fbedd4..241721c8 100644 --- a/a2ml-templates/STATE.a2ml.template +++ b/a2ml-templates/STATE.a2ml.template @@ -5,6 +5,12 @@ # This file tracks the current state of the project using A2ML key-value format. # It is machine-readable and used by RSR tooling for validation. # +# SUPERSEDED SURFACE: the key-value surface below is v1. The normative grammar +# for this family is now DEED -- see deed/spec/DEED-GRAMMAR-SPEC.adoc in +# hyperpolymath/standards. DEED is an s-expression format: it has no +# "key = value" production. This template is retained until the conversion +# campaign regenerates it; do not treat its surface as the specification. +# # HUMAN SUMMARY: This is your project's "status dashboard". It tells anyone # (human or AI) where the project is right now — what phase it's in, what's # been built, and what's next. Update it as work progresses. diff --git a/ecosystem-a2ml/README.adoc b/ecosystem-a2ml/README.adoc index 7fae8557..c30241a2 100644 --- a/ecosystem-a2ml/README.adoc +++ b/ecosystem-a2ml/README.adoc @@ -12,6 +12,22 @@ image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0, :icons: font :source-highlighter: rouge +[WARNING] +==== +*Superseded characterisation.* The normative grammar for this format family is +the DEED grammar specification -- `deed/spec/DEED-GRAMMAR-SPEC.adoc` in this +repository. DEED is an *s-expression* format: there is no `key = value` +production and no `[section]` production; the only bracket is `(`. + +The "TOML-like key-value" wording below is v1 text, and it is the measured cause +of a format speciation: across all 35,884 legacy `.a2ml` files the descriptile +family had reached *0.2%* conformance to the actual grammar -- 10 correct +against 5,424 TOML-shaped. + +The body is left unaltered as the record of what was published. Do not implement +from it. +==== + == Overview == Handover (2026-01-18) diff --git a/meta-a2ml/README.adoc b/meta-a2ml/README.adoc index 1ec78dfe..120d1aa0 100644 --- a/meta-a2ml/README.adoc +++ b/meta-a2ml/README.adoc @@ -8,6 +8,22 @@ image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0, :toclevels: 2 :icons: font +[WARNING] +==== +*Superseded characterisation.* The normative grammar for this format family is +the DEED grammar specification -- `deed/spec/DEED-GRAMMAR-SPEC.adoc` in this +repository. DEED is an *s-expression* format: there is no `key = value` +production and no `[section]` production; the only bracket is `(`. + +The "TOML-like key-value" wording below is v1 text, and it is the measured cause +of a format speciation: across all 35,884 legacy `.a2ml` files the descriptile +family had reached *0.2%* conformance to the actual grammar -- 10 correct +against 5,424 TOML-shaped. + +The body is left unaltered as the record of what was published. Do not implement +from it. +==== + Machine-readable Engineering and Technical Architecture files. Part of the **A2ML Format Family** -- A2ML (Annotated Markup Language) TOML-like key-value diff --git a/playbook-a2ml/README.adoc b/playbook-a2ml/README.adoc index 2b943a21..d1f3e011 100644 --- a/playbook-a2ml/README.adoc +++ b/playbook-a2ml/README.adoc @@ -9,6 +9,22 @@ image:https://img.shields.io/badge/A2ML_Family-execution-green.svg[A2ML Family] :toclevels: 2 :icons: font +[WARNING] +==== +*Superseded characterisation.* The normative grammar for this format family is +the DEED grammar specification -- `deed/spec/DEED-GRAMMAR-SPEC.adoc` in this +repository. DEED is an *s-expression* format: there is no `key = value` +production and no `[section]` production; the only bracket is `(`. + +The "TOML-like key-value" wording below is v1 text, and it is the measured cause +of a format speciation: across all 35,884 legacy `.a2ml` files the descriptile +family had reached *0.2%* conformance to the actual grammar -- 10 correct +against 5,424 TOML-shaped. + +The body is left unaltered as the record of what was published. Do not implement +from it. +==== + Machine-readable executable plans and operational runbooks. Part of the **A2ML Format Family** -- A2ML (Annotated Markup Language) TOML-like key-value diff --git a/state-a2ml/README.adoc b/state-a2ml/README.adoc index dc49de05..0f221f6b 100644 --- a/state-a2ml/README.adoc +++ b/state-a2ml/README.adoc @@ -5,6 +5,22 @@ image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0, :toclevels: 3 :source-highlighter: highlight.js +[WARNING] +==== +*Superseded characterisation.* The normative grammar for this format family is +the DEED grammar specification -- `deed/spec/DEED-GRAMMAR-SPEC.adoc` in this +repository. DEED is an *s-expression* format: there is no `key = value` +production and no `[section]` production; the only bracket is `(`. + +The "TOML-like key-value" wording below is v1 text, and it is the measured cause +of a format speciation: across all 35,884 legacy `.a2ml` files the descriptile +family had reached *0.2%* conformance to the actual grammar -- 10 correct +against 5,424 TOML-shaped. + +The body is left unaltered as the record of what was published. Do not implement +from it. +==== + *Stateful Context Tracking Engine for AI Conversation Continuity* == Overview diff --git a/state-a2ml/spec/STATE-FORMAT-SPEC.adoc b/state-a2ml/spec/STATE-FORMAT-SPEC.adoc index 3ff68259..d2d52caa 100644 --- a/state-a2ml/spec/STATE-FORMAT-SPEC.adoc +++ b/state-a2ml/spec/STATE-FORMAT-SPEC.adoc @@ -6,6 +6,22 @@ :source-highlighter: highlight.js :icons: font +[WARNING] +==== +*Superseded characterisation.* The normative grammar for this format family is +the DEED grammar specification -- `deed/spec/DEED-GRAMMAR-SPEC.adoc` in this +repository. DEED is an *s-expression* format: there is no `key = value` +production and no `[section]` production; the only bracket is `(`. + +The "TOML-like key-value" wording below is v1 text, and it is the measured cause +of a format speciation: across all 35,884 legacy `.a2ml` files the descriptile +family had reached *0.2%* conformance to the actual grammar -- 10 correct +against 5,424 TOML-shaped. + +The body is left unaltered as the record of what was published. Do not implement +from it. +==== + [.text-center] *Internet-Draft Style Specification* + *Version 1.0.0-draft.1* + From cf0af730bf0023484db82d4cc337d2f68541cb6e Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 9 Sep 2026 09:15:07 +0100 Subject: [PATCH 2/3] chore(registry): regenerate REGISTRY.a2ml for the four edited satellite READMEs This PR edits the README of each of the four descriptile satellites (meta-a2ml, state-a2ml, ecosystem-a2ml, playbook-a2ml) to mark the "TOML-like key-value" characterisation superseded by DEED. Those READMEs are each a `canonical_doc` in the registry, so their `source_hash` entries went stale the moment the prose changed -- and nothing regenerated them. That single omission was the whole of this PR's red: * "Registry + topology in sync" failed with DRIFT: .machine_readable/REGISTRY.a2ml is stale -- run 'just registry' * "Repo self-tests" failed 2 of 39 files, and all three of its "broken pass" findings (component-readiness-grades/M3, estate-constitution/M2, neurosym-a2ml/M5) had the SAME grounding check: bash scripts/build-registry.sh --check They were not three separate defects; they were one stale artefact observed three times. Regenerated with `bash scripts/build-registry.sh` -- never hand-edited, since source_hash is computed over the spec home, not over the canonical_doc alone. The diff is exactly four source_hash lines, one per edited README, which is the expected blast radius and a useful check in itself. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01QNjWX2B4FffG7zqMBMui6v --- .machine_readable/REGISTRY.a2ml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.machine_readable/REGISTRY.a2ml b/.machine_readable/REGISTRY.a2ml index cc73f9f5..b3f86c41 100644 --- a/.machine_readable/REGISTRY.a2ml +++ b/.machine_readable/REGISTRY.a2ml @@ -63,7 +63,7 @@ name = "META.a2ml spec" stream = "foundation" home = "meta-a2ml/" canonical_doc = "meta-a2ml/README.adoc" -source_hash = "sha256:bcea50c47c391c6ade37696e34ce31145dfcab3fc8960a362d1d15bcf324306a" +source_hash = "sha256:4860fda70c0f1596d79fdec9292cf117c6434e9b2959030c6c4e142d9c28b5b0" route = "architecture decisions / governance metadata format" [[spec]] @@ -72,7 +72,7 @@ name = "STATE.a2ml spec" stream = "foundation" home = "state-a2ml/" canonical_doc = "state-a2ml/README.adoc" -source_hash = "sha256:8ec140f16e80e96a53c8365df6c06fea50bf2625f84e4ddaa306e5d10721af18" +source_hash = "sha256:266223c162d56092c2344a39c64c19af1770db12924157e1fe879c05c4af447f" route = "project-state metadata format (drives this registry's topology)" [[spec]] @@ -81,7 +81,7 @@ name = "ECOSYSTEM.a2ml spec" stream = "foundation" home = "ecosystem-a2ml/" canonical_doc = "ecosystem-a2ml/README.adoc" -source_hash = "sha256:7fbd11721e97bd85f8200db8a75267be4d7347f82ad0226e9b1296c92d47f9f2" +source_hash = "sha256:cd4a8c7229a3eef8008eda3c5b45f5a4cc39eec0868fe47e4f8b6f786a4aa509" route = "ecosystem-positioning metadata format" [[spec]] @@ -108,7 +108,7 @@ name = "PLAYBOOK.a2ml spec" stream = "foundation" home = "playbook-a2ml/" canonical_doc = "playbook-a2ml/README.adoc" -source_hash = "sha256:fa6ca3574c64d2c03851fee9a0b5ab28b16eb81ce605690f95571640a577b218" +source_hash = "sha256:2857777ff8b27bae380ef345117c260d8805aae03331a04170b169d79ff09f4a" route = "executable operational runbooks" [[spec]] From 9766128dbc8b3b47f154d1112e063183df0f5021 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Wed, 9 Sep 2026 16:10:01 +0000 Subject: [PATCH 3/3] Clarify DEED syntax and legacy A2ML conformance statistics --- ecosystem-a2ml/README.adoc | 6 +++--- meta-a2ml/README.adoc | 6 +++--- playbook-a2ml/README.adoc | 4 ++-- state-a2ml/README.adoc | 3 ++- state-a2ml/spec/STATE-FORMAT-SPEC.adoc | 3 ++- 5 files changed, 12 insertions(+), 10 deletions(-) diff --git a/ecosystem-a2ml/README.adoc b/ecosystem-a2ml/README.adoc index c30241a2..93851cd6 100644 --- a/ecosystem-a2ml/README.adoc +++ b/ecosystem-a2ml/README.adoc @@ -20,9 +20,9 @@ repository. DEED is an *s-expression* format: there is no `key = value` production and no `[section]` production; the only bracket is `(`. The "TOML-like key-value" wording below is v1 text, and it is the measured cause -of a format speciation: across all 35,884 legacy `.a2ml` files the descriptile -family had reached *0.2%* conformance to the actual grammar -- 10 correct -against 5,424 TOML-shaped. +of a format speciation: among the 5,424 TOML-shaped legacy `.a2ml` files the +descriptile family had reached *0.2%* conformance to the actual grammar -- 10 +correct. The body is left unaltered as the record of what was published. Do not implement from it. diff --git a/meta-a2ml/README.adoc b/meta-a2ml/README.adoc index 120d1aa0..4750bf3a 100644 --- a/meta-a2ml/README.adoc +++ b/meta-a2ml/README.adoc @@ -16,9 +16,9 @@ repository. DEED is an *s-expression* format: there is no `key = value` production and no `[section]` production; the only bracket is `(`. The "TOML-like key-value" wording below is v1 text, and it is the measured cause -of a format speciation: across all 35,884 legacy `.a2ml` files the descriptile -family had reached *0.2%* conformance to the actual grammar -- 10 correct -against 5,424 TOML-shaped. +of a format speciation: among the 5,424 TOML-shaped legacy `.a2ml` files the +descriptile family had reached *0.2%* conformance to the actual grammar -- 10 +correct. The body is left unaltered as the record of what was published. Do not implement from it. diff --git a/playbook-a2ml/README.adoc b/playbook-a2ml/README.adoc index d1f3e011..5e520538 100644 --- a/playbook-a2ml/README.adoc +++ b/playbook-a2ml/README.adoc @@ -14,7 +14,8 @@ image:https://img.shields.io/badge/A2ML_Family-execution-green.svg[A2ML Family] *Superseded characterisation.* The normative grammar for this format family is the DEED grammar specification -- `deed/spec/DEED-GRAMMAR-SPEC.adoc` in this repository. DEED is an *s-expression* format: there is no `key = value` -production and no `[section]` production; the only bracket is `(`. +production and no `[section]` production; DEED uses matching opening and +closing parentheses. The "TOML-like key-value" wording below is v1 text, and it is the measured cause of a format speciation: across all 35,884 legacy `.a2ml` files the descriptile @@ -268,4 +269,3 @@ If PLAYBOOK execution fails: == License MPL-2.0. - diff --git a/state-a2ml/README.adoc b/state-a2ml/README.adoc index 0f221f6b..ae25d6f2 100644 --- a/state-a2ml/README.adoc +++ b/state-a2ml/README.adoc @@ -10,7 +10,8 @@ image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0, *Superseded characterisation.* The normative grammar for this format family is the DEED grammar specification -- `deed/spec/DEED-GRAMMAR-SPEC.adoc` in this repository. DEED is an *s-expression* format: there is no `key = value` -production and no `[section]` production; the only bracket is `(`. +production and no `[section]` production; DEED uses matching opening and +closing parentheses. The "TOML-like key-value" wording below is v1 text, and it is the measured cause of a format speciation: across all 35,884 legacy `.a2ml` files the descriptile diff --git a/state-a2ml/spec/STATE-FORMAT-SPEC.adoc b/state-a2ml/spec/STATE-FORMAT-SPEC.adoc index d2d52caa..1fdb9bb0 100644 --- a/state-a2ml/spec/STATE-FORMAT-SPEC.adoc +++ b/state-a2ml/spec/STATE-FORMAT-SPEC.adoc @@ -11,7 +11,8 @@ *Superseded characterisation.* The normative grammar for this format family is the DEED grammar specification -- `deed/spec/DEED-GRAMMAR-SPEC.adoc` in this repository. DEED is an *s-expression* format: there is no `key = value` -production and no `[section]` production; the only bracket is `(`. +production and no `[section]` production; DEED uses matching opening and +closing parentheses. The "TOML-like key-value" wording below is v1 text, and it is the measured cause of a format speciation: across all 35,884 legacy `.a2ml` files the descriptile