// 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/”] image:https://img.shields.io/badge/Docs-CC–BY–SA_4.0-lightgrey.svg[Docs: CC-BY-SA-4.0,link=“LICENSES/CC-BY-SA-4.0.txt”]

: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

|===

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

|===

NOTE: The registry and scorecards generators and the registry-verify gate were retired on 2026-10-09, because A2ML is retired. link:TOPOLOGY.adoc[TOPOLOGY.adoc] and the compliance dashboard are now frozen snapshots. See link:REGISTRY.adoc[REGISTRY.adoc] for details.

== 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.
• Machine-readable metadata – repo facts as clauses of <repo>_chora.deed (grammar link:1-formats/deed/spec/abnf/deed.abnf[deed.abnf]), contracts as *.k9.ncl, agent coordination as coordination.k9 (see <>)
• 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

=== Machine-Readable Metadata

[IMPORTANT]

A2ML is retired (owner rulings D99, D269c, D312, D313). Do not create, restore or extend a .a2ml file, and do not write a “new” A2ML file in a different shape. Machine-readable repo metadata has three forms, each with a normative grammar in this repository. ====

[cols=“2,3,3”, options=“header”] |=== |File |Purpose |Grammar and check

|<repo>_chora.deed, at the repo root (one per repo, D312) |Repo facts: identity, state, meta, ecosystem, agentic, neurosym and playbook, plus the (bot-directives …) and (contractiles …) clauses |link:1-formats/deed/spec/abnf/deed.abnf[deed.abnf] (normative, D308). Check with bun 1-formats/deed/tools/deed_lint.js FILE.deed.

|*.k9.ncl |Contracts, attested by the deed’s (contractiles …) clause |link:1-formats/k9/spec/K9-CONTRACT-SPEC.adoc[K9 contract spec]. Check with 1-formats/k9/tools/k9-validate.sh --strict FILE.

|coordination.k9, at the repo root |Agent coordination: first line K9!, schema_version: 1.2.0 |link:2-protocols/k9-coordination/spec/abnf/coordination-k9-grammar_v1.2.abnf[coordination-k9-grammar_v1.2.abnf] and link:2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC.adoc[COORDINATION-K9-SPEC]. No validator script exists yet. |===

The worked model is rsr-template-repo_chora.deed in https://github.com/hyperpolymath/rsr-template-repo[rsr-template-repo]. The mapping specs in link:1-formats/deed/mappings/[1-formats/deed/mappings/] decide where former A2ML content goes; anything a mapping spec does not list does not translate. Do not hand-convert A2ML in bulk: conversion becomes kyX’s first front end (D313).

=== Monorepo Architecture

NOTE: This section is history. The A2ML formats specified under 1-formats/a2ml/ are retired. Their specs stay in the tree for reference; do not write new files against them.

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

=== Retired: the A2ML family, its templates and its execution pipeline

The seven A2ML files (META, STATE, ECOSYSTEM, PLAYBOOK, AGENTIC, NEUROSYM, ANCHOR), the *.a2ml.template files in 1-formats/templates/, link:1-formats/A2ML-REPO-TEMPLATE.adoc[1-formats/A2ML-REPO-TEMPLATE.adoc] and the execution pipeline that 1-formats/SATELLITES.a2ml once ordered are retired with A2ML. They stay in the tree as history only. No repository is required to carry them, and no new file is written from them. Their content goes into the forms in <>, as the mapping specs decide. No execution ordering has been ruled for the deed era.

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

• link:1-formats/deed/[deed] – Repo metadata as s-expression deeds (grammar link:1-formats/deed/spec/abnf/deed.abnf[deed.abnf]); replaces A2ML, which is retired
• 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

The link:.github/workflows/k9-contractile.yml[DEED–K9 workflow] publishes one compact PR report, with expandable findings and links to dated evidence. See link:1-formats/k9/tools/CONFORMANCE-REPORTING.adoc[its scope, colours and reproduction guide].

=== What actually blocks a merge

main is gated by the ruleset main gate: append-only + required checks + signatures + scanning: 21 required status checks, branches required to be up to date, and no bypass actors. Nothing merges without producing all 21.

That last clause is the one that is easy to lose, so it is worth stating what a gate is not. A required check that no pull request can publish does not make the gate stricter — it makes every pull request undecidable. On 2026-10-24 this repository merged red repeatedly for exactly that reason, and not because a check failed: pull request #1336 stood at 65 passing checks, a cleared review and mergeable=MERGEABLE while mergeStateStatus stayed BLOCKED, because the required context named the post-merge call site of a scan that runs pre-merge under a different name. The only way through was the ruleset bypass, which discards all 21 required checks in the same action.

Three things now keep that from recurring:

• Producibility is a gate. link:.github/workflows/required-contexts.yml[required-contexts.yml] runs link:scripts/check-required-contexts.sh[scripts/check-required-contexts.sh] on every pull request and weekly. It rejects undeclared findings: PR-UNPRODUCIBLE, UNSATISFIABLE, and UNSATISFIED-RULE for data-dependent rules such as code_coverage and code_quality. App-owned contexts are excluded from findings, and declared findings are permitted.
• Exemptions are declared, dated and shrink-only. link:.machine_readable/required-contexts-allow.txt[required-contexts-allow.txt] lists known-unsatisfiable contexts with a reason. It is currently empty, which is its intended resting state; the gate warns when a listed entry stops appearing as a finding, so it cannot rot into a museum of stale exemptions. Silence is never achieved with continue-on-error or || true — both were tried here and both produced an always-green job that reported a gate it never ran.
• The repair is scripted. link:scripts/fix-required-context-name.sh[scripts/fix-required-context-name.sh] repoints a single named context at a single named ruleset, refuses every state it cannot justify, and verifies the read-back. Branch protection is edited by a narrow instrument or not at all.

The full measurement, including the 3h20m of red main that motivated it, is in link:docs/audits/audit-ci-context-producibility-2026-09-20.adoc[the context-producibility audit].

=== 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]

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 +– 1-formats/templates/ # Retired A2ML file templates (history only) | +– STATE.a2ml.template | +– META.a2ml.template | +– ECOSYSTEM.a2ml.template | +– AGENTIC.a2ml.template | +– NEUROSYM.a2ml.template | +– PLAYBOOK.a2ml.template +– 1-formats/a2ml/meta/ # Retired META.a2ml specification (history only) | +– README.adoc | +– spec/ | +– examples/ +– 1-formats/a2ml/playbook/ # Retired PLAYBOOK.a2ml specification (history only) | +– README.adoc | +– spec/ | +– examples/ +– 1-formats/a2ml/agentic/ # Retired AGENTIC.a2ml specification (history only) | +– README.adoc | +– spec/ | +– examples/ | +– 1-formats/contractiles/ | +– ncl/ +– 1-formats/a2ml/neurosym/ # Retired NEUROSYM.a2ml specification (history only) | +– README.adoc | +– spec/ | +– examples/ | +– ncl/ +– 1-formats/a2ml/anchor/ # Retired ANCHOR.a2ml specification (history only) | +– README.adoc | +– spec/ | +– examples/ | +– 1-formats/contractiles/ +– 1-formats/a2ml/state/ # Retired STATE.a2ml specification (history only) | +– README.adoc | +– spec/ | +– examples/ | +– lib/ +– 1-formats/a2ml/ecosystem/ # Retired ECOSYSTEM.a2ml specification (history only) | +– README.adoc | +– spec/ | +– docs/ +– standards-update/ # Standards update tooling | +– README.adoc +– 1-formats/SATELLITES.a2ml # Retired satellite registry (history only) +– 1-formats/A2ML-REPO-TEMPLATE.adoc # Retired structure for -a2ml repos (history only) +– CODE_OF_CONDUCT.md # Template +– CONTRIBUTING.md # Template +– 3-practice/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 <repo>_chora.deed at the repo root, modelled on rsr-template-repo_chora.deed and checked with deed_lint.js; add coordination.k9 and *.k9.ncl contracts where they apply (see <>). Do not create .a2ml files
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:1-formats/SATELLITES.a2ml[1-formats/SATELLITES.a2ml] – Retired satellite registry (history only)
• link:docs/UX-standards/[docs/UX-standards] – UX standards and E-Grade launcher specification
• link:standards-update/[standards-update] – Standards update tooling

Retired A2ML specifications (history only; see <> for the live forms):

• 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)

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.adoc[TOPOLOGY.adoc] for a visual architecture map and completion dashboard (a frozen snapshot, no longer regenerated).