docs(machine-readable): point at the DEED grammar as the single normative source

.machine_readable/README.adoc

@@ -1,3 +1,58 @@
 // SPDX-License-Identifier: CC-BY-SA-4.0
 // Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
 = .machine_readable Pillar
+:toc:
+
+This pillar holds the repository's machine-readable records: what lets tools
+and agents read this project's state, boundaries and obligations without
+parsing prose.
+
+[IMPORTANT]
+====
+*Single normative source.* The grammar for the record family in this pillar is
+`deed/spec/DEED-GRAMMAR-SPEC.adoc` in
+https://github.com/hyperpolymath/standards[hyperpolymath/standards]. That
+document is the only place the syntax, semantics and typechecking rules are
+defined. Every other mention of the format across the estate — including every
+README in this tree — is a *pointer* to it, never a restatement.
+\nThe one sentence that follows is a deliberate, *non-normative* reminder. It is\nrepeated across this tree because its absence from the family's documentation is\nthe measured cause of the TOML-shaped divergence now found across the estate.\nWhere it and the spec ever disagree, the spec governs and this sentence is the\nerror.\n
+DEED is an *s-expression* format: there is no `key = value` production and no
+`[section]` production; the only bracket is `(`.
+
+The format formerly called A2ML is now *DEED* (`.deed`). Files here still carry
+`.a2ml` pending a single atomic estate-wide rename; do not hand-convert them.
+
+The spec path above lands when
+https://github.com/hyperpolymath/standards/pull/752[standards PR #752] merges;
+until then it exists only on that pull request's branch.
+====
+
+== Contents
+
+`descriptiles/`:: What this repository *is* and what state it is *in* — the
+six ruled descriptiles, plus `anchors/` and the files recorded there as open
+work.
+`contractiles/`:: What this repository is *obliged* to be — the Must, Trust,
+Adjust and Intent files, with `bust/` and `dust/` for failure and recovery.
+`self-validating/`:: K9 contractiles: Nickel components that carry their own
+validation and orchestration, at the three security levels described in that
+directory.
+`bot_directives/`:: Methodology-aware configuration read by AI agents at
+session start.
+`ai/`:: AI-facing guidance files: `AI.a2ml`, `0.2-AI-MANIFEST.a2ml`, and
+the per-tool rule files `.clinerules`, `.cursorrules` and `.windsurfrules`.
+`policies/`:: Maintenance axes, the maintenance checklist, and the software
+development approach.
+`configs/`:: Per-tool configuration for the repository's own toolchain.
+`integrations/`:: Records of the external services this repository speaks to.
+`compliance/`:: Licensing and dependency-policy inputs — `reuse/dep5` and the
+Rust `deny.toml`.
+`scripts/`:: Forge, lifecycle, maintenance and verification scripts.
+`ENSAID_CONFIG.a2ml`:: Per-repo configuration for PanLL and eNSAID-compatible
+tools.
+`root-allow.txt`:: The canonical allowlist of entries permitted at the
+repository root.
+
+The AI-manifest files (`0.1-AI-MANIFEST.a2ml` here, `0.2-AI-MANIFEST.a2ml` in
+several subdirectories, `0-AI-MANIFEST.a2ml` under `descriptiles/`) use more
+than one numbering scheme. That inconsistency is recorded, not resolved here.

.machine_readable/contractiles/README.adoc

@@ -4,6 +4,40 @@
 :toc:
 :sectnums:
 
+[IMPORTANT]
+====
+*Single normative source.* The grammar for the files described below is
+`deed/spec/DEED-GRAMMAR-SPEC.adoc` in
+https://github.com/hyperpolymath/standards[hyperpolymath/standards] — the only
+place the syntax, semantics and typechecking rules are defined. The next
+sentence is a deliberate, *non-normative* reminder, repeated across this tree
+because its absence from the family's documentation is the measured cause of the
+TOML-shaped divergence now found across the estate; where it and the spec ever
+disagree, the spec governs and this sentence is the error. DEED is an
+*s-expression* format: there is no `key = value` production and no `[section]`
+production; the only bracket is `(`. The format formerly called A2ML is now
+*DEED* (`.deed`); the files here still carry `.a2ml` pending a single atomic
+estate-wide rename, so do not hand-convert them. That spec path lands when
+https://github.com/hyperpolymath/standards/pull/752[standards PR #752] merges.
+
+*Unresolved citations, recorded not repaired.* The Contents list below names
+`must/Mustfile`, `trust/Trustfile.hs`, `dust/Dustfile` and `intend/Intentfile`.
+None of those four paths exists in this directory. What is actually here is
+`Mustfile.a2ml`, `Trustfile.a2ml`, `Adjustfile.a2ml` and `Intentfile.a2ml` at
+the top level, `bust/Bustfile.a2ml`, `dust/Dustfile.a2ml`, and a `Justfile`.
+The verb-directory layout, the `.hs` extension and the missing Adjust and Bust
+entries are each open work under the contractile layout and extension rulings;
+the list is left as published rather than silently rewritten.
+
+The *Fill-In Instructions* below are unresolved for the same reason and are
+*not actionable as written*: they direct the reader to edit `Mustfile`,
+`Trustfile.hs`, `Dustfile` and `Intentfile`, none of which exist here. Read them
+as a record of the layout this directory was stamped from. The files actually
+present are `Mustfile.a2ml`, `Trustfile.a2ml`, `Adjustfile.a2ml` and
+`Intentfile.a2ml` at the top level, plus `bust/Bustfile.a2ml` and
+`dust/Dustfile.a2ml`.
+====
+
 This directory contains the generalized contractiles templates. Copy the `.machine_readable/contractiles/` directory into a new repo to establish a consistent operational, validation, trust, recovery, and intent framework.
 
 == Fill-In Instructions

.machine_readable/descriptiles/README.adoc

@@ -1,30 +1,85 @@
 // SPDX-License-Identifier: CC-BY-SA-4.0
 // Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
-# A2ML descriptiles Directory
+= descriptiles
+:toc:
 
-This directory contains the 6 core A2ML machine-readable metadata files for this repository.
+Descriptiles record what this repository *is* and what state it is *in* — the
+descriptive half of the descriptile/contractile pair. The contractiles beside
+them, in `../contractiles/`, record what it is *obliged* to be.
 
-## Files
+[IMPORTANT]
+====
+*Single normative source.* The grammar for this record family is
+`deed/spec/DEED-GRAMMAR-SPEC.adoc` in
+https://github.com/hyperpolymath/standards[hyperpolymath/standards]. That
+document is the only place the syntax, semantics and typechecking rules are
+defined. Every other mention of the format across the estate — this README
+included — is a *pointer* to it, never a restatement.
+\nThe one sentence that follows is a deliberate, *non-normative* reminder. It is\nrepeated across this tree because its absence from the family's documentation is\nthe measured cause of the TOML-shaped divergence now found across the estate.\nWhere it and the spec ever disagree, the spec governs and this sentence is the\nerror.\n
+DEED is an *s-expression* format. There is *no* `key = value` production and
+*no* `[section]` production; the only bracket is `(`. That sentence is stated
+explicitly because its absence from the family's documentation is the measured
+cause of the TOML-shaped divergence now found across the estate.
 
-- `AGENTIC.a2ml` - AI agent operational gating, safety controls
-- `ECOSYSTEM.a2ml` - Project ecosystem position, relationships, explicit boundaries
-- `META.a2ml` - Architecture decisions (ADRs), development practices, design rationale
-- `NEUROSYM.a2ml` - Symbolic semantics, composition algebra
-- `PLAYBOOK.a2ml` - Executable plans, operational runbooks
-- `STATE.a2ml` - Project state, phase, milestones, session history
+The format formerly called A2ML is now *DEED* (`.deed`). The files listed below
+still carry `.a2ml` pending a single atomic estate-wide rename; do not
+hand-convert them.
 
-## Standards Compliance
+The spec path above lands when
+https://github.com/hyperpolymath/standards/pull/752[standards PR #752] merges.
+Until then that document exists only on the pull request's branch and the link
+will not resolve.
+====
 
-These files follow the A2ML Format Family specification from:
-https://github.com/hyperpolymath/standards/tree/main/a2ml
+== Contents
 
-## Generation
+The six ruled descriptiles:
 
-These files may be generated from .scm source files using transpilation tools.
-Source .scm files should be removed after successful transpilation.
+`AGENTIC.a2ml`:: AI agent operational gating and safety controls.
+`ECOSYSTEM.a2ml`:: Ecosystem position, relationships, explicit boundaries.
+`META.a2ml`:: Architecture decisions (ADRs), development practices, design
+rationale.
+`NEUROSYM.a2ml`:: Symbolic semantics and composition algebra.
+`PLAYBOOK.a2ml`:: Executable plans and operational runbooks.
+`STATE.a2ml`:: Project state, phase, milestones, session history.
 
-## See Also
+Also present in this directory, and *not* among the six. Each is recorded here
+as open work rather than described as settled:
 
-- [A2ML Repository Template](https://github.com/hyperpolymath/standards/blob/main/A2ML-REPO-TEMPLATE.adoc)
-- [6A2 Format Family](https://github.com/hyperpolymath/standards#a2ml-format-family-7-formats)
+`0-AI-MANIFEST.a2ml`:: One of the AI-manifest family, which this pillar carries
+at several levels under two different numbering schemes (`0-`, `0.1-`, `0.2-`).
+Its placement and numbering are unsettled and are not governed by the
+descriptile ruling.
+`CLADE.a2ml`:: Retained under its v1 name. "Clade" is ruled the wrong word — it
+asserts a common descent the classification does not carry — and the file is
+scheduled to become a `*_chora.deed`. That transition has not happened in this
+repository.
+`anchors/`:: Holds `ANCHOR.a2ml`. ANCHOR is ruled to be *both* descriptile and
+contractile: it states an observed drift (descriptive) and issues a mandated
+realignment (normative). It is the join between the two halves and awaits its
+own specification.
 
+== Generation
+
+These files may be generated from `.scm` source files by transpilation.
+
+[NOTE]
+====
+Earlier text here instructed that `.scm` sources be deleted after successful
+transpilation. That instruction is *withdrawn pending reconciliation*: the
+s-expression form is a sanctioned surface dialect of this family in its own
+right, not a transient build input. Do not delete `.scm` sources on the
+strength of this README.
+====
+
+== See Also
+
+* https://github.com/hyperpolymath/standards/blob/main/A2ML-REPO-TEMPLATE.adoc[Repository
+  template] — link verified live.
+* https://github.com/hyperpolymath/standards#a2ml-format-family-7-formats[Format
+  family overview] — link verified live. Earlier text labelled this the "6A2
+  Format Family"; "6A2" is deprecated, and the target names seven formats.
+
+The v1 text also cited `standards/tree/main/a2ml`. That subtree no longer
+exists on `origin/main`, so the citation is dropped; the grammar pointer above
+replaces it.