// SPDX-License-Identifier: CC-BY-SA-4.0
= Hyperpolymath Standards

image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: MPL-2.0,link="https://www.mozilla.org/MPL/2.0/"]

:toc: macro
:toc-placement!:
:icons: font

Organization-wide standards, specifications, and governance templates for the Hyperpolymath ecosystem.

toc::[]

== Start Here — Front Door & Routing

This monorepo holds ~7,000 files across ~30 specs. You do not need to read all
of it. There are exactly **two canonical entry points**, and everything else
routes off them:

[cols="1,1,3", options="header"]
|===
| You are… | Start at | Then

| A **human** | this file (link:README.adoc[README.adoc]) | follow the routing table below
| An **AI agent** | link:0-AI-MANIFEST.a2ml[0-AI-MANIFEST.a2ml] | then link:.machine_readable/REGISTRY.a2ml[REGISTRY.a2ml] for the machine index
|===

Every other "what is this repo" doc is now a thin pointer back to these two
(link:EXPLAINME.adoc[EXPLAINME.adoc], link:TOPOLOGY.md[TOPOLOGY.md],
`QUICKSTART-*.adoc`, `llm-warmup-*.md`).

=== If you want X, go here

[cols="2,3", options="header"]
|===
| If you want… | Go to

| The estate's highest rules, authority precedence, assurance constitution, and tension register
| link:constitution/[Constitutional district]

| The complete, verifiable index of every spec + its home + source hash
| link:.machine_readable/REGISTRY.a2ml[REGISTRY.a2ml] (machine) · link:REGISTRY.adoc[REGISTRY.adoc] (prose)

| The **A2ML / K9 foundation** (Stream 1) — the 7-format family, K9, contractiles
| link:a2ml/[a2ml/], link:k9-svc/[k9-svc/], link:contractiles/[contractiles/] and the `*-a2ml/` spec dirs

| The **language policy** (Stream 2) — allowed/banned languages, AffineScript stance
| link:.claude/CLAUDE.md[.claude/CLAUDE.md] (canonical) + the <<Language Policy>> table below

| The **protocols** — AVOW, AXEL, Overlay, K9-coordination, Consent-Aware-HTTP, 0-AI-gatekeeper
| the `*-protocol/` dirs (see link:.machine_readable/REGISTRY.a2ml[registry], stream `protocol`)

| The **readiness grades** — ARG / FRG / CRG / TRG
| link:adoption-readiness-grades/[ARG], link:foundations-readiness-grades/[FRG], link:component-readiness-grades/[CRG], link:toolchain-readiness-grades/[TRG]

| **Enforcement / CI** — what blocks bad changes
| link:.github/workflows/[.github/workflows/] + link:hooks/[hooks/] + <<Enforcement>>

| The **drift / staleness automation** — how this repo keeps itself honest
| link:REGISTRY.adoc[REGISTRY.adoc] + link:hypatia-rules/[hypatia-rules/] (HYP-S006); reusable-workflow pin freshness: link:docs/decisions/ADR-003-workflow-pin-staleness-window.adoc[ADR-003] (`scripts/check-workflow-staleness.sh` gate + `scripts/propagate-workflow-pins.sh` deliberate-bump)

| The **architecture map** (derived, never frozen)
| link:TOPOLOGY.md[TOPOLOGY.md] (generated from STATE + registry)

| To **stand up a new repo** to these standards
| link:A2ML-REPO-TEMPLATE.adoc[A2ML-REPO-TEMPLATE.adoc] + <<Usage>>

| The **education layer** — audience-split deep docs (beyond quickstart)
| link:docs/wikis/[docs/wikis/] — link:docs/wikis/users/index.adoc[Users] · link:docs/wikis/developers/index.adoc[Developers] · link:docs/wikis/maintainers/index.adoc[Maintainers]
|===

NOTE: link:.machine_readable/REGISTRY.a2ml[REGISTRY.a2ml] and
link:TOPOLOGY.md[TOPOLOGY.md] are **generated** by
`scripts/build-registry.sh` (`just registry`) and verified in CI by
`registry-verify.yml`. Do not hand-edit them.

== Overview

This repository serves as the canonical source for policies, templates, and specifications governing all Hyperpolymath projects. It provides:

* **Language Policy** -- Which languages and tools are permitted across the ecosystem
* **Language-Maturation Grades** -- link:adoption-readiness-grades/[ARG (Adoption Readiness)] + link:foundations-readiness-grades/[FRG (Foundations Readiness)] per-language profile templates; aggregated into the link:https://github.com/hyperpolymath/nextgen-languages[nextgen-languages] dashboard. TRG (Trust) + CRG (Compliance) profile templates live under each framework's `templates/` directory.
* **Decriptiles Family** -- 7 machine-readable project metadata formats in A2ML (see link:SATELLITES.a2ml[SATELLITES.a2ml])
* **Build System** -- Mustfile/justfile (no Makefiles)
* **Stable Release Gate** -- link:release-pre-flight/V1-GATE.adoc[hard `v1.0.0` audit requirements] for all repos and multi-repo systems
* **Publication Pre-Flight** -- link:publication-pre-flight/PREFLIGHT.adoc[submission gate] plus link:publication-pre-flight/HOL-SUITABILITY-CHECKLIST.adoc[HOL] and link:publication-pre-flight/ZENODO-DEPOSIT-CHECKLIST.adoc[Zenodo] checklists
* **Session Management Standards** -- link:session-management-standards/README.adoc[canonical continuity, verify, and handover protocols]
* **Contractiles / K9** -- link:contractiles/CANONICAL-TEMPLATES.adoc[canonical Must/Trust/Dust/Intent semantics] and Kennel/Yard/Hunt guidance
* **Governance Templates** -- Reusable CODE_OF_CONDUCT, CONTRIBUTING, and SECURITY documents
* **CODEOWNERS Policy** -- link:CODEOWNERS-POLICY.adoc[canonical `CODEOWNERS` rules] (no catch-all/workflow lines on solo-owned repos)
* **Licensing** -- MPL-2.0 (see link:LICENSE[LICENSE]); licence/SPDX changes are owner-only (see link:.claude/CLAUDE.md[.claude/CLAUDE.md])
* **Enforcement** -- CI/CD workflows and pre-commit hooks

== Standards Ecosystem

=== Monorepo Architecture

As of 2026-02-08, all A2ML specification satellites have been absorbed into this monorepo as subdirectories.
The previous hub-satellite architecture (with separate GitHub repos) has been consolidated here for easier maintenance and atomic cross-spec changes.

Each satellite retains its own README, spec documents, examples, and `.machine_readable/` metadata.
RSR boilerplate (LICENSE, CODE_OF_CONDUCT, CONTRIBUTING, SECURITY, MAINTAINERS) is inherited from the monorepo root.

[cols="1,2,1", options="header"]
|===
|Subdirectory |Former Repository |Content

|`meta-a2ml/`
|link:meta-a2ml/[meta-a2ml]
|META.a2ml, STATE.a2ml, ECOSYSTEM.a2ml specs, IANA registration

|`playbook-a2ml/`
|link:playbook-a2ml/[playbook-a2ml]
|PLAYBOOK.a2ml spec

|`agentic-a2ml/`
|link:agentic-a2ml/[agentic-a2ml]
|AGENTIC.a2ml spec, contractiles, Nickel configs

|`neurosym-a2ml/`
|link:neurosym-a2ml/[neurosym-a2ml]
|NEUROSYM.a2ml spec, Nickel configs

|`anchor-a2ml/`
|link:anchor-a2ml/[anchor-a2ml]
|ANCHOR.a2ml spec, contractiles

|`state-a2ml/`
|link:state-a2ml/[state-a2ml]
|STATE.a2ml spec, library, IANA registration

|`ecosystem-a2ml/`
|link:ecosystem-a2ml/[ecosystem-a2ml]
|ECOSYSTEM.a2ml spec, IANA considerations

|`standards-update/`
|https://github.com/hyperpolymath/standards-update[standards-update]
|Standards update tooling and documentation
|===

Satellite registry is still machine-readable in link:SATELLITES.a2ml[SATELLITES.a2ml].

For detailed repository structure requirements, see link:A2ML-REPO-TEMPLATE.adoc[A2ML-REPO-TEMPLATE.adoc].

=== A2ML Format Family (7 Formats)

Every Hyperpolymath repository must include these machine-readable A2ML files in `.machine_readable/`:

[cols="1,1,2,1", options="header"]
|===
|File |Tier |Purpose |Specification

|`META.a2ml`
|Primary
|Architecture decisions (ADRs), development practices
|link:meta-a2ml/[meta-a2ml]

|`STATE.a2ml`
|Primary
|Project state, phase, milestones, session history
|link:state-a2ml/[state-a2ml]

|`ECOSYSTEM.a2ml`
|Primary
|Ecosystem positioning, related projects
|link:ecosystem-a2ml/[ecosystem-a2ml]

|`PLAYBOOK.a2ml`
|Execution
|Executable plans, procedures, alerts
|link:playbook-a2ml/[playbook-a2ml]

|`AGENTIC.a2ml`
|Execution
|AI agent operational gating, entropy budgets
|link:agentic-a2ml/[agentic-a2ml]

|`NEUROSYM.a2ml`
|Execution
|Symbolic semantics, proof obligations
|link:neurosym-a2ml/[neurosym-a2ml]

|`ANCHOR.a2ml`
|Intervention
|Project recalibration/realignment
|link:anchor-a2ml/[anchor-a2ml]
|===

Templates available in `a2ml-templates/` directory.

=== Execution Pipeline

All implementations MUST respect this ordering (defined in link:SATELLITES.a2ml[SATELLITES.a2ml]):

[source]
----
1. META validation      <- Constitutional authority check
2. AGENTIC gating       <- Operational safety
3. NEUROSYM semantics   <- Proof obligations
4. PLAYBOOK derivation  <- Build executable plan
5. Execution
6. ECOSYSTEM check      <- Integrity verification
7. STATE update         <- Record outcome

INTERVENTION: ANCHOR.a2ml can override any level
----

=== RSR (Rhodium Standard Repository)

The Rhodium Standard Repository specification defines compliance requirements:

[cols="1,2", options="header"]
|===
|Repository |Purpose

|https://github.com/hyperpolymath/rhodium-standard-repositories[rhodium-standard-repositories]
|RSR specification and compliance criteria

|https://github.com/hyperpolymath/git-rsr-certified[git-rsr-certified]
|Universal RSR compliance engine

|https://github.com/hyperpolymath/rsr-template-repo[rsr-template-repo]
|Template repository for RSR compliance

|https://github.com/hyperpolymath/rhodium-pipeline[rhodium-pipeline]
|CI/CD pipeline for RSR enforcement
|===

=== Document Formats

* https://github.com/hyperpolymath/standards/tree/main/a2ml[a2ml] -- Attested Markup Language (typed, verified documents) (`application/vnd.a2ml`, v0.6.0 draft)
* https://github.com/hyperpolymath/standards/tree/main/k9-svc[k9-svc] -- Self-validating components (embedded contracts + deployment logic)
* https://github.com/hyperpolymath/stateful-artefacts-for-gitforges[stateful-artefacts-for-gitforges] -- Metadata-driven documentation pipeline

=== Palimpsest

Philosophical licensing overlay for consent-based digital interaction:

* https://github.com/hyperpolymath/palimpsest-license[palimpsest-license] -- Core license framework

Principles:

* **Consent-based digital interaction** -- Explicit permission for data use
* **Transparent AI training practices** -- Opt-in rather than opt-out
* **Preservation of metadata and attribution** -- Maintaining creative lineage
* **Protection of narrative intent** -- Respecting cultural context

=== Mustfile Build System

All repositories use Mustfile/justfile instead of Makefiles:

* https://github.com/hyperpolymath/mustfile[mustfile] -- Canonical build system

Required files:

* `Mustfile` -- Mandatory checks definition
* `justfile` -- Build recipes (https://just.systems[Just])
* `mustfile.toml` -- Configuration (optional)

== Language Policy

The link:.claude/CLAUDE.md[Hyperpolymath Language Policy] defines the technology stack permitted across all projects:

[cols="1,2,2", options="header"]
|===
|Category |Allowed |Banned

|**Primary Languages**
|AffineScript, Rust, Gleam
|TypeScript, Go, Java/Kotlin, Python

|**Runtime**
|Deno
|Node.js, npm, Bun, pnpm, yarn

|**Mobile**
|Tauri 2.0+, Dioxus
|React Native, Flutter/Dart, Swift, Kotlin

|**Config**
|Nickel, Guile Scheme
|--

|**Build**
|Mustfile, Justfile
|Makefiles

|**Special Purpose**
|Julia (batch), OCaml (AffineScript), Ada (safety-critical)
|--
|===

*Rationale:* Preference for FOSS tools with independent governance (no Big Tech dependencies), type safety, and Rust-first mobile development.

NOTE: Python is fully banned. The previous SaltStack exception has been removed.

== Enforcement

=== CI/CD Workflows

Copy these workflows to `.github/workflows/` in your repository:

* `language-policy.yml` -- Blocks banned languages
* `makefile-blocker.yml` -- Blocks any Makefile changes
* `doc-format.yml` -- Enforces AsciiDoc documentation

=== Pre-commit Hook

Install the pre-commit hook for local enforcement:

[source,bash]
----
cp hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
----

The hook checks for:

* Banned file types (TypeScript, Go, Python, Java, Kotlin, Swift)
* Makefiles
* Missing SPDX headers

== Documentation Policy

All documentation must be AsciiDoc (`.adoc`) except for GitHub-required files:

**Must be .md (GitHub community health):**

* `SECURITY.md`
* `CONTRIBUTING.md` (can redirect to `.adoc`)
* `CODE_OF_CONDUCT.md`
* `CHANGELOG.md`

**Must be .adoc:**

* `README.adoc`
* `ARCHITECTURE.adoc`
* `ROADMAP.adoc`
* `PHILOSOPHY.adoc`
* All other documentation

**Other required formats:**

* `LICENSE.txt`
* `.github/FUNDING.yml`

**UX Standards:**

All application launchers and desktop integrations must comply with the
link:docs/UX-standards/[E-Grade Launcher Standard]. This includes:

* No terminal wrapping for GUI/web applications
* Proper process management with `nohup`
* Self-diagnostic capabilities
* Clear user feedback
* Graceful error handling

See link:docs/UX-standards/README.adoc[UX Standards README] for full requirements.

== Repository Structure

[source]
----
standards/
+-- .claude/
|   +-- CLAUDE.md              # Language policy
+-- .github/
|   +-- ISSUE_TEMPLATE/        # Bug, feature, docs, question templates
|   +-- workflows/             # CI/CD enforcement workflows
|   |   +-- language-policy.yml
|   |   +-- makefile-blocker.yml
|   |   +-- doc-format.yml
|   |   +-- ...
|   +-- FUNDING.yml
|   +-- dependabot.yml
+-- hooks/                     # Git hooks
|   +-- pre-commit             # Language policy enforcement
|   +-- validate-*.sh          # Validation scripts
+-- a2ml-templates/            # A2ML file templates
|   +-- STATE.a2ml.template
|   +-- META.a2ml.template
|   +-- ECOSYSTEM.a2ml.template
|   +-- AGENTIC.a2ml.template
|   +-- NEUROSYM.a2ml.template
|   +-- PLAYBOOK.a2ml.template
+-- meta-a2ml/                 # META.a2ml specification (absorbed satellite)
|   +-- README.adoc
|   +-- spec/
|   +-- examples/
+-- playbook-a2ml/             # PLAYBOOK.a2ml specification
|   +-- README.adoc
|   +-- spec/
|   +-- examples/
+-- agentic-a2ml/              # AGENTIC.a2ml specification
|   +-- README.adoc
|   +-- spec/
|   +-- examples/
|   +-- contractiles/
|   +-- ncl/
+-- neurosym-a2ml/             # NEUROSYM.a2ml specification
|   +-- README.adoc
|   +-- spec/
|   +-- examples/
|   +-- ncl/
+-- anchor-a2ml/               # ANCHOR.a2ml specification
|   +-- README.adoc
|   +-- spec/
|   +-- examples/
|   +-- contractiles/
+-- state-a2ml/                # STATE.a2ml specification
|   +-- README.adoc
|   +-- spec/
|   +-- examples/
|   +-- lib/
+-- ecosystem-a2ml/            # ECOSYSTEM.a2ml specification
|   +-- README.adoc
|   +-- spec/
|   +-- docs/
+-- standards-update/          # Standards update tooling
|   +-- README.adoc
+-- SATELLITES.a2ml            # Hub-satellite registry (machine-readable)
+-- A2ML-REPO-TEMPLATE.adoc   # Canonical structure for -a2ml repos
+-- CODE_OF_CONDUCT.md         # Template
+-- CONTRIBUTING.md            # Template
+-- SECURITY.md                # Template
+-- LICENSE                    # MPL-2.0
+-- ROADMAP.adoc
+-- README.adoc                # This file
----

== Usage

=== For New Hyperpolymath Projects

1. Copy governance templates to your repository
2. Create `.machine_readable/` with 7 A2ML files from templates
3. Add `Mustfile` and `justfile` (from hyperpolymath/mustfile)
4. Add enforcement workflows to `.github/workflows/`
5. Install pre-commit hook
6. Add language policy to `.claude/CLAUDE.md`

=== For Contributors

* Read the link:.claude/CLAUDE.md[Language Policy] before proposing code
* No TypeScript, Go, Python, Java, Kotlin, Swift, or Makefiles
* All source files must have SPDX headers
* Follow the template in `CONTRIBUTING.md` for your project

== Related Projects

**Standards Monorepo (this repository):**

* link:SATELLITES.a2ml[SATELLITES.a2ml] -- Machine-readable satellite registry
* link:docs/UX-standards/[docs/UX-standards] -- UX standards and E-Grade launcher specification

**A2ML Format Family (local subdirectories):**

* link:meta-a2ml/[meta-a2ml] -- META.a2ml, STATE.a2ml, ECOSYSTEM.a2ml (primary tier)
* link:playbook-a2ml/[playbook-a2ml] -- PLAYBOOK.a2ml (execution tier)
* link:agentic-a2ml/[agentic-a2ml] -- AGENTIC.a2ml (execution tier)
* link:neurosym-a2ml/[neurosym-a2ml] -- NEUROSYM.a2ml (execution tier)
* link:anchor-a2ml/[anchor-a2ml] -- ANCHOR.a2ml (intervention tier)
* link:state-a2ml/[state-a2ml] -- STATE.a2ml (primary tier)
* link:ecosystem-a2ml/[ecosystem-a2ml] -- ECOSYSTEM.a2ml (primary tier)
* link:standards-update/[standards-update] -- Standards update tooling

**RSR/Rhodium:**

* https://github.com/hyperpolymath/rhodium-standard-repositories[rhodium-standard-repositories]
* https://github.com/hyperpolymath/git-rsr-certified[git-rsr-certified]
* https://github.com/hyperpolymath/rsr-template-repo[rsr-template-repo]
* https://github.com/hyperpolymath/rhodium-pipeline[rhodium-pipeline]

**Build & Licensing:**

* https://github.com/hyperpolymath/mustfile[mustfile] -- Build system standard
* https://github.com/hyperpolymath/palimpsest-license[palimpsest-license] -- Licensing framework

== License

MPL-2.0. See link:LICENSE[LICENSE] for full terms.

NOTE: Licence and SPDX headers in this repo are *owner-managed and
Manual-Only* — agents flag licence drift, they never edit `LICENSE` files or
SPDX headers (see link:.claude/CLAUDE.md[.claude/CLAUDE.md]). The Palimpsest /
PMPL framework applies only to `palimpsest-license`, `palimpsest-plasma`, and
(prospectively) `consent-aware-web` (formerly `consent-aware-http`, extracted to `metadatastician/consent-aware-web` 2026-08-07) — not to this repository.

== Contributing

This is a standards repository. To propose changes:

1. Open a Discussion for major policy changes
2. Submit an Issue for template improvements
3. PRs welcome for typos, clarifications, and infrastructure fixes

---

_Canonical standards for the Hyperpolymath ecosystem._


== Architecture

See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard.
