standards

// 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.adoc[TOPOLOGY.adoc], 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:0-canon/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:1-formats/k9/[1-formats/k9/], link:1-formats/contractiles/[1-formats/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 <> 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/] + <>

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.adoc[TOPOLOGY.adoc] (generated from STATE + registry)

To stand up a new repo to these standards
link:1-formats/A2ML-REPO-TEMPLATE.adoc[1-formats/A2ML-REPO-TEMPLATE.adoc] + <>

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.adoc[TOPOLOGY.adoc] 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:1-formats/SATELLITES.a2ml[1-formats/SATELLITES.a2ml])
Build System – Mustfile/justfile (no Makefiles)
Stable Release Gate – link:3-practice/release-pre-flight/V1-GATE.adoc[hard v1.0.0 audit requirements] for all repos and multi-repo systems
Publication Pre-Flight – link:3-practice/publication-pre-flight/PREFLIGHT.adoc[submission gate] plus link:3-practice/publication-pre-flight/HOL-SUITABILITY-CHECKLIST.adoc[HOL] and link:3-practice/publication-pre-flight/ZENODO-DEPOSIT-CHECKLIST.adoc[Zenodo] checklists
Session Management Standards – link:3-practice/session-management-standards/README.adoc[canonical continuity, verify, and handover protocols]
Contractiles / K9 – link:1-formats/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:3-practice/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

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

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

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

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

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

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

|1-formats/a2ml/ecosystem/ |link:1-formats/a2ml/ecosystem/[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:1-formats/SATELLITES.a2ml[1-formats/SATELLITES.a2ml].

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

=== A2ML Format Family (7 Formats)

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

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

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

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

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

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

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

Templates available in 1-formats/templates/ directory.

=== Execution Pipeline

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

[source]

META validation <- Constitutional authority check
AGENTIC gating <- Operational safety
NEUROSYM semantics <- Proof obligations
PLAYBOOK derivation <- Build executable plan
Execution
ECOSYSTEM check <- Integrity verification
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):

3-practice/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]

== Usage

=== For New Hyperpolymath Projects

Copy governance templates to your repository
Create .machine_readable/ with 7 A2ML files from templates
Add Mustfile and justfile (from hyperpolymath/mustfile)
Add enforcement workflows to .github/workflows/
Install pre-commit hook
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:1-formats/SATELLITES.a2ml[1-formats/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:1-formats/a2ml/meta/[meta-a2ml] – META.a2ml, STATE.a2ml, ECOSYSTEM.a2ml (primary tier)
link:1-formats/a2ml/playbook/[playbook-a2ml] – PLAYBOOK.a2ml (execution tier)
link:1-formats/a2ml/agentic/[agentic-a2ml] – AGENTIC.a2ml (execution tier)
link:1-formats/a2ml/neurosym/[neurosym-a2ml] – NEUROSYM.a2ml (execution tier)
link:1-formats/a2ml/anchor/[anchor-a2ml] – ANCHOR.a2ml (intervention tier)
link:1-formats/a2ml/state/[state-a2ml] – STATE.a2ml (primary tier)
link:1-formats/a2ml/ecosystem/[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:

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

Canonical standards for the Hyperpolymath ecosystem.

== Architecture

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