hyperpolymath · Oct 9, 2026 · Oct 9, 2026
@@ -54,16 +54,36 @@
 
 ## Machine-Readable Artefacts
 
-Every Hyperpolymath repo must have `.machine_readable/` with these 6 A2ML files:
+**A2ML is retired** (owner rulings D99, D269c, D312, D313). Never create,
+restore, regenerate or extend a `.a2ml` file, and never write a "new" A2ML
+file in a different shape. Machine-readable repo metadata has three forms.
+Each has a normative grammar in this repository:
 
-- `STATE.a2ml` - Current project state and progress
-- `META.a2ml` - Architecture decisions and development practices
-- `ECOSYSTEM.a2ml` - Position in the ecosystem and related projects
-- `AGENTIC.a2ml` - AI agent interaction patterns
-- `NEUROSYM.a2ml` - Neurosymbolic integration config
-- `PLAYBOOK.a2ml` - Operational runbook
-
-See: https://github.com/hyperpolymath/standards
+| What | File | Grammar (normative) | Check |
+|---|---|---|---|
+| Repo facts: identity, state, meta, ecosystem, agentic, neurosym, playbook, and the `(bot-directives …)` and `(contractiles …)` clauses | `<repo>_chora.deed` at the repo root, one per repo (D312) | `1-formats/deed/spec/abnf/deed.abnf` (D308; prose: `1-formats/deed/spec/DEED-GRAMMAR-SPEC.adoc`) | `bun 1-formats/deed/tools/deed_lint.js FILE.deed` |
+| Contracts | `*.k9.ncl` | `1-formats/k9/spec/K9-CONTRACT-SPEC.adoc` | `1-formats/k9/tools/k9-validate.sh --strict FILE` |
+| Agent coordination | `coordination.k9` at the repo root: first line `K9!`, `schema_version: 1.1.1` | `2-protocols/k9-coordination/spec/abnf/coordination-k9-grammar_v1.1.abnf` (prose: `2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC.adoc`) | No validator script exists yet, and a generic YAML parser does not conform. The generator is `2-protocols/k9-coordination/tools/k9-init/`. |
+
+- **Translating old content.** The mapping specs in `1-formats/deed/mappings/`,
+  one per former A2ML family, decide where its content goes. Anything a
+  mapping spec does not list does not translate.
+- **The worked model** is `rsr-template-repo_chora.deed` in
+  `hyperpolymath/rsr-template-repo`.
+- **No bulk conversion.** Do not hand-convert A2ML in bulk, and do not use the
+  Python converters in `1-formats/deed/tools/`. Conversion becomes kcX's first
+  front end (D313), and Python is banned.
+- **A deed is not TOML.** A file containing `key = value` or `[section]` is not
+  a deed. `(` is the only bracket. Booleans are `#t`/`#f`. Enums are symbols
+  (`:primary fv`, not `:primary "fv"`). UUIDs are `#u5"…"` literals.
+  `:schema-version` appears exactly once at the top level.
+- **Existing `.a2ml` files**, here and in other repos, are legacy awaiting
+  migration. You may delete content from one; never add a fact to one.
+
+`.machine_readable/descriptiles/` stays the directory for descriptive anchors
+that are not yet folded into the chora deed. The `.a2ml` files still in it are
+legacy. Anything new written there is a `.deed`, such as
+`provisioning_praxis.deed`, never a `.a2ml`.
 
 ---
 
@@ -99,7 +119,8 @@ for the canonical statement.
 | **Bash/POSIX Shell** | Scripts, automation | Keep minimal |
 | **JavaScript** | Only where AffineScript cannot | MCP protocol glue, runtime APIs (transitional; prefer .affine where possible) |
 | **Nickel** | Configuration language | For complex configs |
-| **A2ML** | State/meta files | STATE.a2ml, META.a2ml, etc. (TOML-like format) |
+| **deed** | Repo metadata (`<repo>_chora.deed`) | S-expression format; grammar `1-formats/deed/spec/abnf/deed.abnf`. Replaces A2ML, which is retired. See Machine-Readable Artefacts above. |
+| **k9** | Contracts (`*.k9.ncl`) and agent coordination (`coordination.k9`) | Grammars and validators in `1-formats/k9/` and `2-protocols/k9-coordination/`. |
 | **Julia** | Batch scripts, data processing | Per RSR |
 | **OCaml** | AffineScript compiler | Language-specific |
 | **Ada** (legacy) | Safety-critical systems where Rust/SPARK is not yet reachable | Rust/SPARK is absorbing most Ada work over time. Do not start new pure-Ada projects unless Rust/SPARK cannot reach. |

@@ -15,28 +15,44 @@ The following files *MUST* be present and kept up-to-date in every repository:
 | `.tool-versions` | asdf version pinning for reproducible builds
 |===
 
-== Mandatory A2ML Files
+== Machine-Readable Metadata
 
-[NOTE]
+[IMPORTANT]
 ====
-These files use the `.a2ml` extension. Earlier versions of this doc
-listed them as `.scm`; that was stale drift. `.scm` is reserved exclusively
-for Guix-related files (`guix.scm`, `.guix-channel`). All descriptiles metadata
-files use `.a2ml`.
+*A2ML is retired* (owner rulings D99, D269c, D312, D313). This section used to
+require six `.a2ml` files (META, STATE, ECOSYSTEM, PLAYBOOK, AGENTIC,
+NEUROSYM). Do not create them, restore them, or write a "new" A2ML file in
+their place. Their content now lives in deed clauses, as below. `.scm` stays
+reserved for Guix files (`guix.scm`, `.guix-channel`).
 ====
 
-[cols="2,3"]
+[cols="2,3,3"]
 |===
-| File | Purpose
-
-| `META.a2ml` | Architecture decisions, development practices
-| `STATE.a2ml` | Project state, phase, milestones
-| `ECOSYSTEM.a2ml` | Ecosystem positioning, related projects
-| `PLAYBOOK.a2ml` | Executable plans, procedures
-| `AGENTIC.a2ml` | AI agent operational gating
-| `NEUROSYM.a2ml` | Symbolic semantics, proof obligations
+| File | Purpose | Grammar and check
+
+| `<repo>_chora.deed` (repo root, one per repo)
+| The repo's facts: identity, state, meta, ecosystem, agentic, neurosym,
+  playbook, and the `(bot-directives …)` and `(contractiles …)` clauses (D312).
+| link:../1-formats/deed/spec/abnf/deed.abnf[`deed.abnf`] (normative, D308).
+  Check with `bun 1-formats/deed/tools/deed_lint.js FILE.deed`. Model:
+  `rsr-template-repo_chora.deed` in `hyperpolymath/rsr-template-repo`.
+
+| `*.k9.ncl`
+| Contracts. The chora deed attests to them through its `(contractiles …)` clause.
+| link:../1-formats/k9/spec/K9-CONTRACT-SPEC.adoc[K9 contract spec]. Check with
+  `1-formats/k9/tools/k9-validate.sh --strict FILE`.
+
+| `coordination.k9` (repo root)
+| Agent coordination rules. First line `K9!`, `schema_version: 1.1.1`.
+| link:../2-protocols/k9-coordination/spec/abnf/coordination-k9-grammar_v1.1.abnf[`coordination-k9-grammar_v1.1.abnf`]
+  (prose: link:../2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC.adoc[COORDINATION-K9-SPEC]).
+  No validator script exists yet, and a generic YAML parser does not conform.
 |===
 
+Where a former A2ML record's content goes is decided by the mapping specs in
+link:../1-formats/deed/mappings/[`1-formats/deed/mappings/`]. Anything a
+mapping spec does not list does not translate.
+
 == Build System
 
 [cols="2,3"]
@@ -70,4 +86,5 @@ When updating these files:
 
 * link:https://github.com/hyperpolymath/rhodium-standard-repositories[RSR (Rhodium Standard Repositories)]
 * link:https://github.com/hyperpolymath/mustfile[Mustfile Specification]
-* link:https://github.com/hyperpolymath/standards/tree/main/meta-a2ml[A2ML Format Family]
+* link:../1-formats/deed/README.adoc[deed format]
+* link:../2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC.adoc[K9 coordination protocol]
@@ -8,15 +8,15 @@ thin pointer back to one of these two.
 ## WHAT IS THIS REPO?
 
 The organization-wide standards monorepo: ~30 specs that govern every
-Hyperpolymath project — the A2ML metadata family, K9 self-validating
+Hyperpolymath project — K9 self-validating
 components, the protocols, the readiness-grading frameworks (ARG/FRG/CRG/TRG),
 RSR compliance, and the enforcement/CI that makes them stick.
 
 ## ROUTING — where to go for X (machine index)
 
 | If you want… | Go to |
 |---|---|
-| A2ML / K9 foundation (Stream 1) | `a2ml/`, `1-formats/k9/`, `1-formats/contractiles/`, `*-a2ml/` |
+| K9 foundation (Stream 1) | `1-formats/k9/`, `1-formats/contractiles/` |
 | Language policy (Stream 2) | `.claude/CLAUDE.md` |
 | Protocols | `*-protocol/` |
 | Readiness grades | `adoption-readiness-grades/`, `foundations-readiness-grades/`, `component-readiness-grades/`, `toolchain-readiness-grades/` |
@@ -27,23 +27,6 @@ RSR compliance, and the enforcement/CI that makes them stick.
 | Current project state | `.machine_readable/descriptiles/STATE.a2ml` |
 | Education layer (deep docs, by audience) | `docs/wikis/` (Users / Developers / Maintainers); machine mirror `docs/wikis/0.2-AI-MANIFEST.a2ml` |
 
-## CANONICAL LOCATIONS (UNIVERSAL RULE)
-
-### Machine-readable metadata lives in `.machine_readable/descriptiles/` ONLY
-
-The 7 A2ML files MUST exist under `.machine_readable/descriptiles/` (this repo's
-absorbed-satellite layout), never in the repo root:
-
-1. **STATE.a2ml** — project state, progress, blockers
-2. **META.a2ml** — architecture decisions, governance
-3. **ECOSYSTEM.a2ml** — position in ecosystem, relationships
-4. **AGENTIC.a2ml** — AI-agent interaction patterns
-5. **NEUROSYM.a2ml** — neurosymbolic integration config
-6. **PLAYBOOK.a2ml** — operational runbook
-7. **ANCHOR.a2ml** — intervention/recalibration (under `.machine_readable/anchors/`)
-
-**CRITICAL:** if any of these appear in the repo root, that is an ERROR.
-
 ## CORE INVARIANTS
 
 1. **No A2ML duplication** — root must NOT contain STATE.a2ml, META.a2ml, etc.
@@ -64,7 +47,7 @@ absorbed-satellite layout), never in the repo root:
 ## ATTESTATION
 
 After reading, state: **"I have read the standards manifest. The human front
-door is README.adoc. A2ML state lives in .machine_readable/descriptiles/ only.
+door is README.adoc.
 Licence/SPDX is Manual-Only — I will flag, never edit."**
 
 ## META

@@ -18,6 +18,15 @@ directly. Preserve licences, coined names, MAA’s independent authority,
 and current language/build conventions. Do not add TypeScript or Deno,
 weaken validation, or describe draft/tested work as proven.
 
-Run the relevant `+just+`/`+must+` targets, A2ML/Nickel/K9 validation
-where applicable, link/canonical-name checks, and `+git diff --check+`.
+A2ML is retired (D99, D269c, D312, D313). Never create, restore or extend a
+`+.a2ml+` file. Repo metadata goes in `+<repo>_chora.deed+` clauses (grammar
+`+1-formats/deed/spec/abnf/deed.abnf+`), contracts in `+*.k9.ncl+`, and agent
+coordination in `+coordination.k9+` (grammar
+`+2-protocols/k9-coordination/spec/abnf/coordination-k9-grammar_v1.1.abnf+`).
+`+1-formats/deed/mappings/+` says where former A2ML content goes.
+
+Run the relevant `+just+`/`+must+` targets, deed validation
+(`+bun 1-formats/deed/tools/deed_lint.js+`), Nickel/K9 validation
+(`+1-formats/k9/tools/k9-validate.sh --strict+`) where applicable,
+link/canonical-name checks, and `+git diff --check+`.
 Regenerate twice and require a clean second pass for generated outputs.