// SPDX-License-Identifier: CC-BY-SA-4.0

= Hyperpolymath Standards — EXPLAINME
:icons: font

[NOTE]
====
*This is a thin pointer, not an entry point.* The canonical front doors are:

* *Humans* → link:README.adoc[README.adoc] (overview + "if you want X, go here" routing)
* *Agents* → link:0-AI-MANIFEST.a2ml[0-AI-MANIFEST.a2ml] (machine routing)
* *The spec index* → link:.machine_readable/REGISTRY.a2ml[REGISTRY.a2ml] (every spec + home + source hash) · prose in link:REGISTRY.adoc[REGISTRY.adoc]

This file used to carry its own hand-maintained spec inventory, which drifted
(it listed ReScript as a primary language — banned 2026-04-30 in favour of
AffineScript — and referenced `groove-protocol/` and `palimpsest-license/` as
local directories that do not exist in this monorepo). That inventory now lives
in the generated, CI-verified registry instead, so it can no longer go stale.
====

== What this repo is

The organization-wide standards monorepo: the A2ML metadata family, K9
self-validating components, the protocols, the readiness-grading frameworks
(ARG/FRG/CRG/TRG), RSR compliance, and the enforcement/CI that makes them
stick. Former satellite repos were absorbed as subdirectories on 2026-02-08.

For the full, verifiable list of specs and where each one lives, read
link:.machine_readable/REGISTRY.a2ml[REGISTRY.a2ml] (or the human prose in
link:REGISTRY.adoc[REGISTRY.adoc]).

== Architecture decisions (the durable ones)

[cols="1,3", options="header"]
|===
| Decision | Rationale

| AsciiDoc-first documentation
| Semantic structure + cross-references; `.md` only for GitHub-required files.

| Justfile over Makefiles
| Cross-platform recipes without tab sensitivity; Makefiles are banned org-wide.

| Language policy
| AffineScript (primary), Rust/SPARK, Zig, Gleam, Elixir, Idris2/Agda. Banned: TypeScript, ReScript, Python, Go, Java/Kotlin/Swift, V-lang, Makefiles. Canonical statement + carve-outs: link:.claude/CLAUDE.md[.claude/CLAUDE.md].

| A2ML over YAML/JSON for metadata
| Machine-readable, versionable, semantically typed. Each repo declares state in `.machine_readable/`.

| SHA-pinned GitHub Actions
| Prevents supply-chain attacks from mutable tags.

| Guix-first package management
| Reproducible builds; Nix flakes as fallback.
|===

== How to use this repo

. *New project?* See link:A2ML-REPO-TEMPLATE.adoc[A2ML-REPO-TEMPLATE.adoc] and the *Usage* section of link:README.adoc[README.adoc].
. *Looking for a specific spec?* link:.machine_readable/REGISTRY.a2ml[REGISTRY.a2ml].
. *Language question?* link:.claude/CLAUDE.md[.claude/CLAUDE.md].
. *CI / enforcement?* link:.github/workflows/[.github/workflows/] + link:hooks/[hooks/].
. *Build / test?* `just build`, `just test` (see link:Justfile[Justfile]).
