From 05b03047c277bad6d63e6ee9cd3c453482b2fd47 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 9 Sep 2026 00:45:51 +0100 Subject: [PATCH 1/3] docs(machine-readable): point at the DEED grammar as the single normative source MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three READMEs in this pillar described the record format in their own words. Each now points at the one normative document instead. No .a2ml file is touched and nothing is renamed or converted. descriptiles/README.adoc — was Markdown inside a .adoc. Asciidoctor's Markdown compatibility carried the ATX headings and the "-" bullets, but both [label](url) links rendered as literal bracket text with the URL auto-linked beside them; verified by rendering the pre-change file. Rewritten as real AsciiDoc. Drops the deprecated "6A2" term, whose own target names seven formats. Replaces the one dead link — standards/tree/main/a2ml, whose subtree is gone from origin/main — with the DEED grammar pointer; the other two links were verified live and are kept. States explicitly that DEED has no key = value form, since the absence of that statement is the documented cause of the family-wide divergence. Also documents the three entries the old file omitted: 0-AI-MANIFEST.a2ml, CLADE.a2ml and anchors/, each recorded as open work rather than described as settled. The "delete .scm sources after transpilation" instruction is marked withdrawn pending reconciliation, because s-expression is a sanctioned surface dialect, not a transient build input. README.adoc — was a three-line stub. Now carries the pillar-level normative pointer and describes each of the eleven subdirectories and root files actually present, including the AI-manifest numbering inconsistency. contractiles/README.adoc — pointer banner only; the body is untouched. Records that its Contents list names four paths (must/Mustfile, trust/Trustfile.hs, dust/Dustfile, intend/Intentfile) none of which exists here, rather than silently repairing them. Verified: asciidoctor renders all three files clean, exit 0, no warnings. Verified: the strings changed here appear in no other file in the repository, so this is not a scaffolding template source and no generated repo is left stale by it. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01QNjWX2B4FffG7zqMBMui6v --- .machine_readable/README.adoc | 55 +++++++++++++ .machine_readable/contractiles/README.adoc | 22 ++++++ .machine_readable/descriptiles/README.adoc | 91 +++++++++++++++++----- 3 files changed, 150 insertions(+), 18 deletions(-) diff --git a/.machine_readable/README.adoc b/.machine_readable/README.adoc index 35ca4aa..c961473 100644 --- a/.machine_readable/README.adoc +++ b/.machine_readable/README.adoc @@ -1,3 +1,58 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) Jonathan D.A. Jewell = .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. + +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 (`CLAUDE.md`, `GEMINI.md`, `AI.a2ml` and +kin). +`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. diff --git a/.machine_readable/contractiles/README.adoc b/.machine_readable/contractiles/README.adoc index db8c4ec..13886a3 100644 --- a/.machine_readable/contractiles/README.adoc +++ b/.machine_readable/contractiles/README.adoc @@ -4,6 +4,28 @@ :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. 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. +==== + 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 diff --git a/.machine_readable/descriptiles/README.adoc b/.machine_readable/descriptiles/README.adoc index 97414db..80204ac 100644 --- a/.machine_readable/descriptiles/README.adoc +++ b/.machine_readable/descriptiles/README.adoc @@ -1,30 +1,85 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) Jonathan D.A. Jewell -# 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. -- `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 +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. -## Standards Compliance +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. -These files follow the A2ML Format Family specification from: -https://github.com/hyperpolymath/standards/tree/main/a2ml +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. +==== -## Generation +== Contents -These files may be generated from .scm source files using transpilation tools. -Source .scm files should be removed after successful transpilation. +The six ruled descriptiles: -## See Also +`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. -- [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) +Also present in this directory, and *not* among the six. Each is recorded here +as open work rather than described as settled: +`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. From d7d16d8b95b32a4fd6159d34fdcdd8b5fcab42f4 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 9 Sep 2026 00:53:38 +0100 Subject: [PATCH 2/3] docs(machine-readable): correct the ai/ inventory to the directory's actual contents MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The pillar README's `ai/` entry listed `CLAUDE.md` and `GEMINI.md`. Neither file is in that directory. The listing was copied from the examples in `ai/README.adoc` rather than measured against the directory. Measured contents of `.machine_readable/ai/`: `AI.a2ml`, `0.2-AI-MANIFEST.a2ml`, `.clinerules`, `.cursorrules`, `.windsurfrules`, `README.adoc`. The entry now names those. This is a §5 correction — a README whose whole argument is that the format's documentation must be verified rather than restated should not itself carry an unverified inventory. Verified: asciidoctor renders the file clean, exit 0, no warnings. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01QNjWX2B4FffG7zqMBMui6v --- .machine_readable/README.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.machine_readable/README.adoc b/.machine_readable/README.adoc index c961473..74da4c3 100644 --- a/.machine_readable/README.adoc +++ b/.machine_readable/README.adoc @@ -39,8 +39,8 @@ 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 (`CLAUDE.md`, `GEMINI.md`, `AI.a2ml` and -kin). +`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. From 25c847c24d7d2d1b72d529522e7150fcf4346f36 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 9 Sep 2026 00:57:04 +0100 Subject: [PATCH 3/3] docs(machine-readable): resolve two self-contradictions the review found MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both findings were verified against the files rather than taken on trust; both were real. 1. The banner asserted that every README in this tree is a pointer to the DEED spec and "never a restatement", and then immediately restated the syntax rule. That is a contradiction on its own terms. The repetition is deliberate — the rule's absence from the family's documentation is the measured cause of the TOML-shaped divergence across the estate — so the fix is to say so: the sentence is now marked explicitly non-normative, with the spec named as governing where the two ever disagree. Applied to all three banners. 2. `contractiles/README.adoc` recorded that its Contents list names four paths that do not exist, but left the Fill-In Instructions below telling the reader to edit those same four files — and line 29 declares this directory a copy-me template, so those instructions are live, not decorative. They are now marked not actionable as written, with the six files that are actually present named. The instructions and the Contents list are still left as published: the verb-directory layout and the file extensions are governed by separate open rulings, so recording is right and rewriting would pre-empt them. The published body below the banner remains untouched; both additions sit inside the banner block. Verified: asciidoctor renders all three files clean, exit 0, no warnings. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01QNjWX2B4FffG7zqMBMui6v --- .machine_readable/README.adoc | 2 +- .machine_readable/contractiles/README.adoc | 14 +++++++++++++- .machine_readable/descriptiles/README.adoc | 2 +- 3 files changed, 15 insertions(+), 3 deletions(-) diff --git a/.machine_readable/README.adoc b/.machine_readable/README.adoc index 74da4c3..2785874 100644 --- a/.machine_readable/README.adoc +++ b/.machine_readable/README.adoc @@ -15,7 +15,7 @@ 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 `(`. diff --git a/.machine_readable/contractiles/README.adoc b/.machine_readable/contractiles/README.adoc index 13886a3..fd82891 100644 --- a/.machine_readable/contractiles/README.adoc +++ b/.machine_readable/contractiles/README.adoc @@ -9,7 +9,11 @@ *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. DEED is an +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 @@ -24,6 +28,14 @@ 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. diff --git a/.machine_readable/descriptiles/README.adoc b/.machine_readable/descriptiles/README.adoc index 80204ac..b4eee3c 100644 --- a/.machine_readable/descriptiles/README.adoc +++ b/.machine_readable/descriptiles/README.adoc @@ -15,7 +15,7 @@ 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