Skip to content

EXPLAINME.adoc

Latest commit

 

History

History
159 lines (113 loc) · 6.14 KB

EXPLAINME.adoc

File metadata and controls

159 lines (113 loc) · 6.14 KB

Hyperpolymath Standards — EXPLAINME

Canonical source for policies, templates, and specifications

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

— README.adoc

This monorepo consolidates the A2ML specification family, governance templates, protocol definitions, and enforcement tooling that all Hyperpolymath projects must follow. Former satellite repos (meta-a2ml, playbook-a2ml, agentic-a2ml, etc.) were absorbed into subdirectories as of 2026-02-08. See README.adoc for the full directory map and specification list.

Caveat: Standards are prescriptive — not every downstream repo is fully compliant yet. Enforcement is via CI workflows and Hypatia scanning, not manual audit.

Architecture Decisions

Decision Rationale

AsciiDoc-first documentation

AsciiDoc supports semantic structure, cross-references, and conditional output better than Markdown. .md is only used for GitHub-required files (SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md).

Justfile over Makefiles

just provides cross-platform recipes without implicit rules or tab sensitivity. Makefiles are banned org-wide.

Language policy (CCCP)

Limits ecosystem fragmentation. Primary: ReScript, Rust, Gleam, Deno. Banned: TypeScript, Go, Python, Java/Kotlin/Swift. Exceptions documented per-repo.

A2ML over YAML/JSON for metadata

Machine-readable, versionable, and carries semantic meaning. Each repo declares its state via .machine_readable/STATE.a2ml.

SHA-pinned GitHub Actions

Prevents supply-chain attacks from mutable tags. All workflows pin actions by commit SHA.

Guix-first package management

Reproducible builds. Nix flakes as fallback. No npm/node_modules in production.

Evidence

Path Proves

a2ml/

A2ML format specification — the machine-readable metadata format used across all repos (47 Rust tests)

meta-a2ml/, state-a2ml/, ecosystem-a2ml/

META, STATE, ECOSYSTEM A2ML specs and IANA registration drafts

agentic-a2ml/

AGENTIC.a2ml spec — AI agent interaction patterns with contractile enforcement

neurosym-a2ml/

NEUROSYM.a2ml spec — neurosymbolic integration configuration with Nickel schemas

playbook-a2ml/, anchor-a2ml/

PLAYBOOK and ANCHOR A2ML specs — operational runbooks and intervention protocols

contractiles/

Contractile system (must/trust/dust/intend/k9) — policy enforcement primitives

k9-svc/

K9 self-validating component framework (45 Rust tests, CRG Grade B, deployed on 105+ repos)

k9-coordination-protocol/

AI agent coordination protocol (79 tests, Phase 1 complete)

axel-protocol/

Axel protocol specification — age-gating and explicit enforcement (14 Deno tests, beta)

groove-protocol/

Groove universal plug-and-play protocol — inter-service communication (10+ Zig tests, 80% complete)

avow-protocol/

AVOW consent-attested messaging — origin attribution and willingness verification (Idris2 + ReScript)

consent-aware-http/

Multi-protocol AI usage boundaries — consent headers for HTTP interactions

hooks/

Pre-commit and CI hooks — the enforcement layer that makes standards stick

.github/workflows/

23 CI/CD workflows — policy enforcement, quality gates, security scanning, deployment

How to Use This Repo

  1. New project? Copy .machine_readable/ templates into your repo and fill in the A2ML files.

  2. CI enforcement? Reference the shared workflows or copy the relevant .github/workflows/ files.

  3. Language question? Check the CCCP language policy in CLAUDE.md or the language-policy.yml workflow.

  4. Building? Run just build (requires Rust, Zig, and Deno). Run just test for the full 158+ test suite.

  5. Self-check? Run just doctor to verify your local toolchain, just heal to auto-fix common issues.

Test Coverage

Suite Technology Tests

groove-protocol/reference/ipv6t

Zig

10+

0-ai-gatekeeper-protocol/mcp-repo-guardian

Deno

36

axel-protocol

Deno

14

a2ml/bindings/rust

Rust

47

k9-svc/bindings/rust

Rust

45

avow-protocol (ReScript)

Deno

8

Total

160+

Dogfooded Across The Account

The patterns mandated here are applied everywhere — not prescribed then ignored:

Standard Where Mandated Live Examples

A2ML machine-readable metadata

a2ml/ spec (7 formats)

Every RSR repo’s .machine_readable/; meta-a2ml spec + IANA draft

SHA-pinned GitHub Actions

workflow-linter.yml CI gate

All 23 workflows in .github/workflows/ pin by SHA; enforced in >300 downstream repos

Contractile / K9 enforcement

contractiles/ + k9-svc/

hypatia, gossamer, burble, proven, proven-servers (105+ repos carry k9 guards)

Groove inter-service protocol

groove-protocol/ spec

gossamer (src/core/Groove.eph), burble (bridges), hypatia (dispatch connectors)

Idris2 ABI + Zig FFI standard

ABI-FFI-README.md + rsr-template-repo reference

ephapax (idris2/), gossamer (src/interface/abi/), burble (src/Burble/ABI/), verisimdb, typed-wasm

Guix-first package management

CCCP language policy (CLAUDE.md)

guix.scm at root; flake.nix as fallback — both present in this repo

PMPL-1.0-or-later licence

palimpsest-license/ + licence policy

SPDX header on every source file estate-wide; LICENSE here

Roadmap Phases

  • Phase A (Innervation): Wire k9 coordination across all repos, replace static 6a2 files with derived STATE.

  • Phase B (Evidence): Formal proof verification via ECHIDNA, VeriSimDB population, lol/ postulate resolution.

  • Phase C (Visibility): PanLL dashboard panels, ecosystem health metrics, compliance heatmaps.

  • Phase D (Maturity): CRG Grade A self-assessment, full dogfooding, external audit readiness.