Skip to content

standards-update

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

standards-update

README.adoc

Hyperpolymath Standards

License: PMPL-1.0 Palimpsest

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

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

  • A2ML Format Family — 7 machine-readable project metadata formats (see SATELLITES.a2ml)

  • Build System — Mustfile/justfile (no Makefiles)

  • Governance Templates — Reusable CODE_OF_CONDUCT, CONTRIBUTING, and SECURITY documents

  • Licensing Framework — PMPL-1.0-or-later with Palimpsest philosophical principles

  • Enforcement — CI/CD workflows and pre-commit hooks

Standards Ecosystem

Hub-Satellite Architecture

This repository is the hub for the A2ML Format Family. All specification repos are satellites registered in SATELLITES.a2ml.

For detailed repository structure requirements, see A2ML-REPO-TEMPLATE.adoc.

A2ML Format Family (7 Formats)

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

meta-a2ml

STATE.a2ml

Primary

Project state, phase, milestones, session history

Companion to META

ECOSYSTEM.a2ml

Primary

Ecosystem positioning, related projects

Companion to META

PLAYBOOK.a2ml

Execution

Executable plans, procedures, alerts

playbook-a2ml

AGENTIC.a2ml

Execution

AI agent operational gating, entropy budgets

agentic-a2ml

NEUROSYM.a2ml

Execution

Symbolic semantics, proof obligations

neurosym-a2ml

ANCHOR.a2ml

Intervention

Project recalibration/realignment

anchor-a2ml

Templates available in a2ml-templates/ directory.

A2ML Atomicity Protocol (AAP)

When multiple agents or bots may write to A2ML files concurrently, the AAP prevents lost writes:

  1. Read the file and record git-sha-at-read in the [provenance] section

  2. Lock by creating .machine_readable/.lock-<FILENAME> (advisory)

  3. Write the updated file with new [provenance] metadata

  4. Release by removing the lock file

  5. Conflict — if git-sha-at-read does not match current HEAD, re-read and retry

All A2ML files include a [provenance] section for audit trail and conflict detection.

Execution Pipeline

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

RSR (Rhodium Standard Repository)

The Rhodium Standard Repository specification defines compliance requirements:

Repository Purpose

rhodium-standard-repositories

RSR specification and compliance criteria

git-rsr-certified

Universal RSR compliance engine

rsr-template-repo

Template repository for RSR compliance

rhodium-pipeline

CI/CD pipeline for RSR enforcement

Palimpsest

Philosophical licensing overlay for consent-based digital interaction:

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:

Required files:

  • Mustfile — Mandatory checks definition

  • justfile — Build recipes (Just)

  • mustfile.toml — Configuration (optional)

Language Policy

The Hyperpolymath Language Policy defines the technology stack permitted across all projects:

Category Allowed Banned

Primary Languages

ReScript, 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, A2ML (TOML-like)

 — 

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:

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

Repository Structure

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
│   └── ANCHOR.a2ml.template
├── 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.txt                # PMPL-1.0-or-later + Palimpsest
├── ROADMAP.adoc
└── README.adoc                # This file

Usage

For New Hyperpolymath Projects

  1. Copy governance templates to your repository

  2. Create .machine_readable/ with 6 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 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 Hub:

A2ML Format Family (Satellites):

RSR/Rhodium:

Build & Licensing:

License

PMPL-1.0-or-later with Palimpsest philosophical overlay.

See LICENSE.txt for full terms.

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.