Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
Organization-wide standards, specifications, and governance templates for the Hyperpolymath ecosystem.
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:
| You are… | Start at | Then |
|---|---|---|
A human |
this file (README.adoc) |
follow the routing table below |
An AI agent |
then REGISTRY.a2ml for the machine index |
Every other "what is this repo" doc is now a thin pointer back to these two (EXPLAINME.adoc, TOPOLOGY.adoc, QUICKSTART-.adoc, llm-warmup-.md).
| If you want… | Go to |
|---|---|
The estate’s highest rules, authority precedence, assurance constitution, and tension register |
|
The complete, verifiable index of every spec + its home + source hash |
REGISTRY.a2ml (machine) · REGISTRY.adoc (prose) |
The A2ML / K9 foundation (Stream 1) — the 7-format family, K9, contractiles |
a2ml/, k9-svc/, contractiles/ and the *-a2ml/ spec dirs |
The language policy (Stream 2) — allowed/banned languages, AffineScript stance |
.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 registry, stream protocol) |
The readiness grades — ARG / FRG / CRG / TRG |
|
Enforcement / CI — what blocks bad changes |
|
The drift / staleness automation — how this repo keeps itself honest |
REGISTRY.adoc + hypatia-rules/ (HYP-S006); reusable-workflow pin freshness: ADR-003 (scripts/check-workflow-staleness.sh gate + scripts/propagate-workflow-pins.sh deliberate-bump) |
The architecture map (derived, never frozen) |
TOPOLOGY.adoc (generated from STATE + registry) |
To stand up a new repo to these standards |
|
The education layer — audience-split deep docs (beyond quickstart) |
|
Note
|
REGISTRY.a2ml and TOPOLOGY.adoc are generated by scripts/build-registry.sh (just registry) and verified in CI by registry-verify.yml. Do not hand-edit them. |
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 — ARG (Adoption Readiness) + FRG (Foundations Readiness) per-language profile templates; aggregated into the 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 SATELLITES.a2ml)
-
Build System — Mustfile/justfile (no Makefiles)
-
Stable Release Gate — hard v1.0.0 audit requirements for all repos and multi-repo systems
-
Publication Pre-Flight — submission gate plus HOL and Zenodo checklists
-
Session Management Standards — canonical continuity, verify, and handover protocols
-
Contractiles / K9 — canonical Must/Trust/Dust/Intent semantics and Kennel/Yard/Hunt guidance
-
Governance Templates — Reusable CODE_OF_CONDUCT, CONTRIBUTING, and SECURITY documents
-
CODEOWNERS Policy — canonical CODEOWNERS rules (no catch-all/workflow lines on solo-owned repos)
-
Licensing — MPL-2.0 (see LICENSE); licence/SPDX changes are owner-only (see .claude/CLAUDE.md)
-
Enforcement — CI/CD workflows and pre-commit hooks
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.
| Subdirectory | Former Repository | Content |
|---|---|---|
meta-a2ml/ |
META.a2ml, STATE.a2ml, ECOSYSTEM.a2ml specs, IANA registration |
|
playbook-a2ml/ |
PLAYBOOK.a2ml spec |
|
agentic-a2ml/ |
AGENTIC.a2ml spec, contractiles, Nickel configs |
|
neurosym-a2ml/ |
NEUROSYM.a2ml spec, Nickel configs |
|
anchor-a2ml/ |
ANCHOR.a2ml spec, contractiles |
|
state-a2ml/ |
STATE.a2ml spec, library, IANA registration |
|
ecosystem-a2ml/ |
ECOSYSTEM.a2ml spec, IANA considerations |
|
standards-update/ |
Standards update tooling and documentation |
Satellite registry is still machine-readable in SATELLITES.a2ml.
For detailed repository structure requirements, see A2ML-REPO-TEMPLATE.adoc.
Every Hyperpolymath repository must include these machine-readable A2ML files in .machine_readable/:
| File | Tier | Purpose | Specification |
|---|---|---|---|
META.a2ml |
Primary |
Architecture decisions (ADRs), development practices |
|
STATE.a2ml |
Primary |
Project state, phase, milestones, session history |
|
ECOSYSTEM.a2ml |
Primary |
Ecosystem positioning, related projects |
|
PLAYBOOK.a2ml |
Execution |
Executable plans, procedures, alerts |
|
AGENTIC.a2ml |
Execution |
AI agent operational gating, entropy budgets |
|
NEUROSYM.a2ml |
Execution |
Symbolic semantics, proof obligations |
|
ANCHOR.a2ml |
Intervention |
Project recalibration/realignment |
Templates available in a2ml-templates/ directory.
All implementations MUST respect this ordering (defined in SATELLITES.a2ml):
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
The Rhodium Standard Repository specification defines compliance requirements:
| Repository | Purpose |
|---|---|
RSR specification and compliance criteria |
|
Universal RSR compliance engine |
|
Template repository for RSR compliance |
|
CI/CD pipeline for RSR enforcement |
-
a2ml — Attested Markup Language (typed, verified documents) (application/vnd.a2ml, v0.6.0 draft)
-
k9-svc — Self-validating components (embedded contracts + deployment logic)
-
stateful-artefacts-for-gitforges — Metadata-driven documentation pipeline
Philosophical licensing overlay for consent-based digital interaction:
-
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
The Hyperpolymath Language Policy defines the technology stack permitted across all projects:
| 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. |
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
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 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 UX Standards README for full requirements.
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
-
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
-
Read the 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
Standards Monorepo (this repository):
-
SATELLITES.a2ml — Machine-readable satellite registry
-
docs/UX-standards — UX standards and E-Grade launcher specification
A2ML Format Family (local subdirectories):
-
meta-a2ml — META.a2ml, STATE.a2ml, ECOSYSTEM.a2ml (primary tier)
-
playbook-a2ml — PLAYBOOK.a2ml (execution tier)
-
agentic-a2ml — AGENTIC.a2ml (execution tier)
-
neurosym-a2ml — NEUROSYM.a2ml (execution tier)
-
anchor-a2ml — ANCHOR.a2ml (intervention tier)
-
state-a2ml — STATE.a2ml (primary tier)
-
ecosystem-a2ml — ECOSYSTEM.a2ml (primary tier)
-
standards-update — Standards update tooling
RSR/Rhodium:
Build & Licensing:
-
mustfile — Build system standard
-
palimpsest-license — Licensing framework
MPL-2.0. See 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 .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. |
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.
See TOPOLOGY.adoc for a visual architecture map and completion dashboard.