docs(deed): first mapping spec — CLADE.a2ml → repo-deed (campaign step, #837)

1-formats/deed/mappings/README.adoc

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+= DEED mapping specs — the `.a2ml` → `.deed` frame
+:toc: macro
+Campaign: standards#837. This directory carries one mapping spec per source
+surface. A mapping spec is the *only* document a family translation may cite
+as its authority — translation without a mapping spec is how the pin-generator
+trap repeats at campaign scale.
+
+== What every mapping spec MUST contain
+
+. **Source surface** — the exact `.a2ml` files (and their template/mint paths)
+  the spec governs.
+. **Target deed form** — one of the four heads (`repo-deed`, `estate-deed`,
+  `estate-atlas-deed`, `praxis-deed`) plus the filename-stem rule the
+  translated file lands under (remember: `<stem>_chora.deed`, stem ≠ `estate`).
+. **Field table** — every source field, its target keyword/clause path, its
+  deed *value type* (string / symbol / integer / boolean / `#u5"…"` uuid5 /
+  quoted / list), and any transform (verbatim, enum-as-symbol, re-derive).
+  Anything not in the table does not translate.
+. **Drop doctrine** — what is deliberately NOT carried over. The default:
+  instructional comments (taxonomy prose, how-to text) live in the generator
+  era's docs, never in a translated deed; derivable facts are dropped, not
+  duplicated (the STATE v2 doctrine, carried into the campaign).
+. **Provenance & validation** — how the conformance lane knows the translation
+  is honest: re-derivation checks, reject cases, and the fixtures the lane
+  must parse against the normative grammar (see #837 for the pending
+  canonical-file ruling; references below say "the current grammar
+  (`deed.anbf`, v1.0.0)" until then).
+. **Acceptance greps** — the strings that MUST be greppable in the deed era
+  for the family to count as preserved (campaign acceptance criteria).
+
+== Order of families
+
+Highest-loss-risk first — a family with no v2 surface dies first if we drift:
+
+1. `CLADE.a2ml` → `repo-deed` — link:clade-to-repo-deed.adoc[clade-to-repo-deed]
+   (lineage registry; hub/satellite enums have no other home)
+2. `META.a2ml`, `ECOSYSTEM.a2ml` → `repo-deed` clauses (coordination links
+   walk the graph the land registry lives on)
+3. `STATE.a2ml` v1 → journal / `praxis-deed` decision (v2 thin-journal
+   doctrine applies — most fields die by design)
+4. `AGENTIC.a2ml`, `NEUROSYM.a2ml`, `PLAYBOOK.a2ml` → `repo-deed`
+5. `*.scorecard.a2ml` corpus (70+) → repo-deed clause vs. dedicated decision
+6. rsr-template mint sources + estate wave (after 1–5 are green in CI)
+
+== Standing constraints (from the grammar, non-negotiable)
+
+* A deed cannot contain `key = value` or `[section]` — "a file using `=` is
+  not a deed". Constitutive, not stylistic.
+* `:schema-version "1.0.0"` is structurally FIRST on every head.
+* Enums and codes that were quoted strings in a2ml become *symbols*
+  (`:primary fv`, not `:primary "fv"`) — symbols are the typed half.
+* UUIDs are `#u5"…"` literals; a bare filename never stands in for one.
+* `estate_chora.deed` dispatch is exact-stem-first; validators hand-encode
+  the ordering (grammar cannot express it).

1-formats/deed/mappings/clade-to-repo-deed.adoc

@@ -0,0 +1,207 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+= Mapping spec — `CLADE.a2ml` → `repo-deed`
+Campaign: standards#837 · Frame: link:README.adoc[mappings/README] ·
+Status: PROPOSAL (no translation until owner review; the canonical-grammar
+ruling is also still open, #837)
+
+== 1. Source surface
+
+* Estate instances: `<repo>/.machine_readable/descriptiles/CLADE.a2ml`
+  (or `.machine_readable/CLADE.a2ml` in pre-descriptile-dir repos).
+* Mint source: `rsr-template-repo:build/templates/CLADE.a2ml.in` — the file
+  every new repo is stamped from (carries the `#122` lineage extensions).
+* Registry coupling: `gv-clade-index` (verisim seed + SPEC-clade-verisim-portal
+  §Identity Model). Checks CLADE-003/004/005/006 referenced below are the
+  registry's existing gates.
+
+== 2. Target form
+
+[source]
+----
+<canonical-name>_chora.deed
+----
+
+`repo-deed` head. Stem = the repo's *canonical name* (never `estate` — grammar
+side condition; never the `UNASSIGNED-…` prefixed placeholder either). A repo
+renamed later re-derives this file like any other: the deed is a projection,
+not a rename event.
+
+Head-level scaffolding follows the grammar's required identity table
+(<<identity>> in the grammar spec):
+
+[source]
+----
+;; SPDX-License-Identifier: CC-BY-SA-4.0
+(repo-deed
+  :schema-version  "1.0.0"        ; structurally FIRST
+  :canonical-name  "<repo>"
+  :repo-uuid       #u5"<repo uuid5>"
+  :beholding-chora #u5"<estate chora>"
+  ...)
+----
+
+`:beholding-chora` is *required* and is never invented: the translator
+resolves it from the estate chora's registry entry (gv-clade-index is the
+one declaration site today) and **refuses to emit a deed without it** — a
+bare filename would resolve against nothing (grammar rationale).
+
+== 3. Field table
+
+`→` left: a2ml surface. Right: deed path + type + transform.
+
+[cols="2,3,4"]
+|===
+| a2ml surface | deed path | transform / type
+
+4+| *Head identity*
+
+| `[identity] canonical-name` | `:canonical-name` | verbatim STRING
+| `[identity] uuid` | `:repo-uuid` | **re-derived, never copied** (see §5 P-1) — uuid5 literal `#u5"…"`
+| — (new) | `:beholding-chora` | resolved from registry — uuid5 literal
+
+4+| *Clauses*
+
+| `[identity] primary-forge` | `(identity … :primary-forge github)` | STRING value → SYMBOL
+| `[identity] primary-owner` | `(identity … :owner "…")` | verbatim STRING
+| `[identity] prefixed-name` | `(identity … :prefixed-name "…")` | verbatim STRING
+| `[clade] primary` | `(clade … :primary rm)` | enum → SYMBOL (12-category closed taxonomy carried *verbatim*: fv nl rm gv db ap ix dx pt ax gm sc)
+| `[clade] primary-name` | `(clade … :primary-name "…")` | verbatim STRING (the deliberate redundancy pair with `:primary` is kept — CLADE-006 survives)
+| `[clade] secondary` | `(clade … :secondary (gv))` | list of SYMBOLs
+| `[clade] assigned` | `(clade … :assigned "2026-…")` | verbatim STRING (no date type in the grammar)
+| `[clade] rationale` | `(clade … :rationale "…")` | verbatim STRING
+| `[forges] github/gitlab/bitbucket` | `(forges … :github "o/r" …)` | verbatim STRINGs; empty stays `""`
+| `[lineage] type` | `(lineage … :type standalone)` | enum → SYMBOL — **the full post-#122 taxonomy carried verbatim**: `standalone monorepo monorepo-child inflated deflated hub satellite`
+| `[lineage] parent` | `(lineage … :parent "")` | verbatim STRING (the "monorepo parent, never a description" doctrine travels in the camera's own docs, not the field)
+| `[lineage] born` | `(lineage … :born "…")` | verbatim STRING
+| `[lineage] previous-names` | `(lineage … :previous-names ())` | list of STRINGs
+| `[lineage] instantiated-from` | `(lineage … :instantiated-from "…")` | verbatim STRING
+| `[status] phase` | `(status … :phase active)` | enum → SYMBOL — taxonomy verbatim: `reserved incubating active dormant` \| `merged superseded archived extinct`
+| `[status] since` | `(status … :since "…")` | verbatim STRING
+| `[status] present` | `(status … :present true)` | verbatim BOOLEAN
+| `[status] aliases` | `(status … :aliases ())` | list of STRINGs
+| `[status] merged-into` / `superseded-by` / `ended` | `(status … :merged-into "" …)` | verbatim STRINGs; empty stays `""`
+| `[status] successors` | `(status … :successors ())` | list of STRINGs
+| `[[status.history]]` (0..n) | `(status … (history (entry :phase … :since "…" :note "…") …))` | each entry becomes one nested `(entry …)` clause, field-for-field
+|===
+
+Fields not listed do not exist in the deed era for this family.
+
+== 4. Drop doctrine (what is NOT translated, and why that is right)
+
+* The 12-clade taxonomy comment block, the paint-type/gossamer cautionary
+  tales, the uuid recomputation instructions, and the "REGISTRATION IS NOT
+  DERIVATION" notice: **guidance**, not data. They live on in the mint
+  template's own docs and the registry spec; a per-repo deed is a record,
+  not a manual. (Same doctrine as STATE v2: discard the derivable and the
+  instructional.)
+* `previous-names`, empty `aliases`, empty `successors`: KEPT (explicitly),
+  verbatim — they are the empty *slots* that make the history greppable.
+
+== 5. Provenance & validation
+
+* **P-1 (re-derivation):** for each instance the translator recomputes
+  `uuid = UUIDv5(URL, "github.com/<owner>/<name>")` and *fails closed* on
+  mismatch — never copies a uuid and never emits the one it disagrees with
+  (`enforce-uuid-provenance` doctrine; the check errs on the side of
+  specificity, it is not an unfalsifiability guarantee).
+* **P-2 (source must parse as a2ml first):** a source file that no longer
+  parses as a2ml (e.g. already hand-"translated" halfway, containing `()`)
+  is rejected before any output assignment. A source carrying `=` inside a
+  *string* is fine (strings pass through escaped).
+* **P-3 (output must parse as DEED):** every emitted deed is parsed against
+  the current normative grammar (`deed.anbf` v1.0.0 until the #837 ruling
+  lands): full input consumed, `:schema-version` structurally first, unknown
+  clauses are *errors* (validator §conformance), no `=` anywhere outside a
+  symbol-legal position (grammar: `=` inside a symbol is legal; the field
+  separator `=` is not).
+* **P-4 (dispatch check):** emitted filenames are tested estate-file-first;
+  any repo named `estate` fails closed rather than silently matching
+  `repo-deed` as a stem.
+* **P-5 (registry gates survive):** CLADE-003/004/005/006 semantics are
+  re-expressed over the deed surface before retire-the-checker day — an
+  `UNASSIGNED` clade, a missing `(status …)`, an absent `:repo-uuid`, and a
+  `:primary`/`:primary-name` disagreement must each still fail.
+
+== 6. Worked translation (real instance: `rsr-template-repo`)
+
+Source (post-#122 template instance, abridged to fields):
+
+[source]
+----
+uuid = "a5ea1382-a34c-5334-8a46-a2ebe904c810"
+primary-forge = "github"   primary-owner = "hyperpolymath"
+canonical-name = "rsr-template-repo"   prefixed-name = "rm-rsr-template-repo"
+[clade] primary = "rm"   primary-name = "Repo Management & Tooling"
+secondary = []           assigned = "…"
+[forges] github = "hyperpolymath/rsr-template-repo"
+[lineage] type = "standalone"   parent = ""   born = "2026-03-16"
+[status] phase = "active"   since = "2026-03-16"   present = true
+[[status.history]] phase = "active"   since = "2026-03-16"
+note = "the estate's canonical repository template; in production use"
+----
+
+Emitted `rsr-template-repo_chora.deed`:
+
+[source]
+----
+;; SPDX-License-Identifier: CC-BY-SA-4.0
+(repo-deed
+  :schema-version  "1.0.0"
+  :canonical-name  "rsr-template-repo"
+  :repo-uuid       #u5"a5ea1382-a34c-5334-8a46-a2ebe904c810"
+  :beholding-chora #u5"<estate chora — resolved from gv-clade-index>"
+
+  (identity :primary-forge github
+            :owner          "hyperpolymath"
+            :prefixed-name  "rm-rsr-template-repo")
+
+  (clade    :primary       rm
+            :primary-name  "Repo Management & Tooling"
+            :secondary     (gv)
+            :assigned      "2026-03-16"
+            :rationale     "…")
+
+  (forges   :github    "hyperpolymath/rsr-template-repo"
+            :gitlab    ""
+            :bitbucket "")
+
+  (lineage  :type              standalone
+            :parent            ""
+            :born              "2026-03-16"
+            :previous-names    ()
+            :instantiated-from "rsr-template-repo")
+
+  (status   :phase        active
+            :since        "2026-03-16"
+            :present      true
+            :aliases      ()
+            :merged-into  ""
+            :superseded-by ""
+            :successors   ()
+            :ended        ""
+            (history
+              (entry :phase active
+                     :since "2026-03-16"
+                     :note  "the estate's canonical repository template; in production use"))))
+----
+
+== 7. Acceptance greps (this family is preserved iff, post-campaign)
+
+* Every former CLADE repo has an existing `<canonical-name>_chora.deed` that
+  parses against the normative grammar.
+* `grep -rl ':type hub' --include='*_chora.deed'` returns the eight Stealth
+  Glider-era hubs and `':type satellite'` their members — the #122 enums are
+  verbatim literals, not adapted spellings.
+* No emitted deed contains `=` outside a symbol.
+* `estate_chora.deed` was never produced by this family (dispatch ordering).
+
+== 8. Open questions for the owner (recorded, not decided here)
+
+. Choice of stem: canonical-name (proposed) vs prefixed-name (changes on
+  clade choice). Prefixed-name reads nicer in `ls`; canonical-name is the
+  stable identifier the grammar's identity table already commits.
+. Whether `gv-clade-index`'s own registry migrates to the estate chora in
+  the same wave or stays the external authority point `beholding-chora`
+  resolves from.
+. `:beholding-chora` for PRs minted before the chora exists in the registry
+  — sequential ordering question for the campaign wave.