= Hyperpolymath Standards

image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"]
image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"]

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

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

toc::[]

== 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 link:SATELLITES.a2ml[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 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
|https://github.com/hyperpolymath/meta-a2ml[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
|https://github.com/hyperpolymath/playbook-a2ml[playbook-a2ml]

|`AGENTIC.a2ml`
|Execution
|AI agent operational gating, entropy budgets
|https://github.com/hyperpolymath/agentic-a2ml[agentic-a2ml]

|`NEUROSYM.a2ml`
|Execution
|Symbolic semantics, proof obligations
|https://github.com/hyperpolymath/neurosym-a2ml[neurosym-a2ml]

|`ANCHOR.a2ml`
|Intervention
|Project recalibration/realignment
|https://github.com/hyperpolymath/anchor-a2ml[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 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
|===

=== 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**
|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:

[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`

== 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
│   └── 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 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 Hub:**

* https://github.com/hyperpolymath/standards[standards] — This repository (hub)
* link:SATELLITES.a2ml[SATELLITES.a2ml] — Machine-readable satellite registry

**A2ML Format Family (Satellites):**

* https://github.com/hyperpolymath/meta-a2ml[meta-a2ml] — META.a2ml, STATE.a2ml, ECOSYSTEM.a2ml (primary tier)
* https://github.com/hyperpolymath/playbook-a2ml[playbook-a2ml] — PLAYBOOK.a2ml (execution tier)
* https://github.com/hyperpolymath/agentic-a2ml[agentic-a2ml] — AGENTIC.a2ml (execution tier)
* https://github.com/hyperpolymath/neurosym-a2ml[neurosym-a2ml] — NEUROSYM.a2ml (execution tier)
* https://github.com/hyperpolymath/anchor-a2ml[anchor-a2ml] — ANCHOR.a2ml (intervention tier)

**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

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

See link:LICENSE.txt[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._
