diff --git a/.machine_readable/README.adoc b/.machine_readable/README.adoc index 35ca4aa..2785874 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. +\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. diff --git a/.machine_readable/contractiles/README.adoc b/.machine_readable/contractiles/README.adoc index db8c4ec..fd82891 100644 --- a/.machine_readable/contractiles/README.adoc +++ b/.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 diff --git a/.machine_readable/descriptiles/README.adoc b/.machine_readable/descriptiles/README.adoc index 97414db..b4eee3c 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. +\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.