From f14b2bd5f8a0579cc13118d51e8f1c4a5e9076aa Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 20:27:10 +0100 Subject: [PATCH] docs(readme): convert README.adoc -> Markdown README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README must be real Markdown to render in GitHub community-health, the GitHub profile, and external MCP directories (Glama) — AsciiDoc shows as raw markup there. pandoc asciidoc->GFM, badges fixed to clickable, SPDX header kept as an HTML comment, duplicate README.adoc removed. Co-Authored-By: Claude Opus 4.8 --- README.adoc | 135 ---------------------------------------------------- README.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 130 insertions(+), 135 deletions(-) delete mode 100644 README.adoc create mode 100644 README.md diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 108d58f..0000000 --- a/README.adoc +++ /dev/null @@ -1,135 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -= gv-clade-index -Jonathan D.A. Jewell -v0.1.0, 2026-03-16 -:toc: left -:toclevels: 3 -:icons: font - -== Overview - -The *clade-index* is the central registry for the entire hyperpolymath ecosystem. -It provides a VeriSimDB-backed taxonomy of 200+ repositories organised into 12 clades, -with a pointer authority system for tracking data ownership, and VCL queries for -dashboards, drift detection, and work tracking. - -*Map and territory*: This registry is the map — queryable, presentable, always clean. -Repositories are the territory. Editing the map never damages the territory. - -== Clade Taxonomy - -[cols="1,3,4"] -|=== -| Code | Clade | Description - -| `fv` | Formal Verification & Proofs | Provable correctness, reversibility, dependent types -| `nl` | Nextgen Languages | Compilers, runtimes, language tooling -| `rm` | Repo Management & Tooling | Scaffolding, graph analysis, bot orchestration -| `gv` | Governance & Standards | Licensing, compliance, policy enforcement -| `db` | Databases | Database engines, query languages -| `ap` | Applications | End-user apps, web, desktop, services -| `ix` | Infrastructure & Cloud | Containers, deployment, sysadmin -| `dx` | Developer Ecosystem | Dev tools, editor integrations, bindings -| `pt` | Protocols & Interop | Internet standards, protocol implementations -| `ax` | AI & Neurosymbolic | ML, neural proof synthesis, AI governance -| `gm` | Games & Interactive | Game engines, interactive experiences -| `sc` | Security | Scanning, vulnerability management, access control -|=== - -== Structure - -[source] ----- -gv-clade-index/ -├── 0-AI-MANIFEST.a2ml # AI agent entry point -├── .machine_readable/ # State, meta, ecosystem, clade declaration -├── verisim/ -│ ├── config.a2ml # VeriSimDB instance config -│ ├── schema/ # VCL schemas (7 entity types) -│ │ ├── repo.vcl # Repository octad -│ │ ├── clade.vcl # Clade definition -│ │ ├── todo.vcl # Work items -│ │ ├── observation.vcl # Bot/agent findings -│ │ ├── feedback.vcl # External feedback -│ │ ├── lineage.vcl # Inflate/deflate history -│ │ └── forge-identity.vcl # PK/FK forge mapping -│ ├── seed/ # Initial data -│ │ ├── clades.a2ml # 12 clade definitions -│ │ ├── repos.a2ml # 200 repo registrations -│ │ └── forges.a2ml # Forge account definitions -│ └── queries/ # Pre-built VCL queries -│ ├── dashboard.vcl # Ecosystem overview -│ ├── stale.vcl # Inactive repos -│ ├── orphans.vcl # Unclassified repos -│ ├── drift.vcl # State divergence -│ ├── bot-findings.vcl # Unacknowledged bot observations -│ ├── blocked.vcl # Blocked work items -│ ├── cross-clade-deps.vcl # Cross-boundary dependencies -│ └── feedback-status.vcl # Feedback resolution tracking -├── sync/ # Sync tooling (Phase 2) -├── views/ # Generated outputs (not committed) -└── contractiles/ - └── must/ - └── clade-hygiene.a2ml # Every repo MUST have CLADE.a2ml ----- - -== Portal Architecture - -[source] ----- -hyperpolymath.github.io Cloudflare Worker VeriSimDB (VPS) -(ReScript/WASM) --> (API Gateway) --> (Rust + Elixir) - | -Public read --------------------------------------------------> KV snapshot -LLM query ------------------- API key ---------------------> Read-only -Contributor ------------------ OAuth -----------------------> Scoped access -Bot writes ------------------- Signed JWT ------------------> Write observations ----- - -== Identity Model - -Every repo has: - -* *Primary key*: GitHub (`gh:hyperpolymath/{name}`) -* *Foreign keys*: GitLab, Bitbucket, Codeberg, SourceHut mirrors -* *UUID*: Deterministic v5, derived from `github.com/hyperpolymath/{name}` -* *Clade*: Primary (1) + secondary (0+) -* *Lineage*: standalone, monorepo, monorepo-child, inflated, deflated - -== Pointer Authority - -Every cached value in VeriSimDB declares its canonical source: - -* `pointer` -- value lives in the repo (VeriSimDB caches + drift-detects) -* `local` -- VeriSimDB owns it (TODOs, bot observations) -* `derived` -- computed from other values (clade health scores) - -== Contractile System - -This repo includes a `clade-hygiene.a2ml` contractile: - -* **CLADE-001**: Every repo must have `.machine_readable/CLADE.a2ml` -* **CLADE-002**: CLADE.a2ml must declare a primary clade code -* **CLADE-003**: Primary clade code must be one of the 12 valid codes - -== Implementation Phases - -[cols="1,3,4"] -|=== -| Phase | Deliverable | Status - -| 0 | Clade taxonomy, repo seed, VCL schema | *Complete* -| 1 | Deploy CLADE.a2ml to all 200 repos | Pending -| 2 | VeriSimDB instance on VPS | Pending -| 3 | Cloudflare Worker API (hardened, tested, CI-gated) | In progress (~60%) -| 4 | ReScript/typed-WASM portal | Pending -| 5 | LLM query endpoint | Pending -| 6 | Bot write endpoints | Pending -| 7 | Contributor OAuth | Pending -| 8 | Repo lockdown | Pending -|=== - -== License - -link:LICENSE[MPL-2.0] diff --git a/README.md b/README.md new file mode 100644 index 0000000..d954e39 --- /dev/null +++ b/README.md @@ -0,0 +1,130 @@ + + +# Overview + +The **clade-index** is the central registry for the entire hyperpolymath +ecosystem. It provides a VeriSimDB-backed taxonomy of 200+ repositories +organised into 12 clades, with a pointer authority system for tracking +data ownership, and VCL queries for dashboards, drift detection, and +work tracking. + +**Map and territory**: This registry is the map — queryable, +presentable, always clean. Repositories are the territory. Editing the +map never damages the territory. + +# Clade Taxonomy + +| Code | Clade | Description | +|----|----|----| +| `fv` | Formal Verification & Proofs | Provable correctness, reversibility, dependent types | +| `nl` | Nextgen Languages | Compilers, runtimes, language tooling | +| `rm` | Repo Management & Tooling | Scaffolding, graph analysis, bot orchestration | +| `gv` | Governance & Standards | Licensing, compliance, policy enforcement | +| `db` | Databases | Database engines, query languages | +| `ap` | Applications | End-user apps, web, desktop, services | +| `ix` | Infrastructure & Cloud | Containers, deployment, sysadmin | +| `dx` | Developer Ecosystem | Dev tools, editor integrations, bindings | +| `pt` | Protocols & Interop | Internet standards, protocol implementations | +| `ax` | AI & Neurosymbolic | ML, neural proof synthesis, AI governance | +| `gm` | Games & Interactive | Game engines, interactive experiences | +| `sc` | Security | Scanning, vulnerability management, access control | + +# Structure + + gv-clade-index/ + ├── 0-AI-MANIFEST.a2ml # AI agent entry point + ├── .machine_readable/ # State, meta, ecosystem, clade declaration + ├── verisim/ + │ ├── config.a2ml # VeriSimDB instance config + │ ├── schema/ # VCL schemas (7 entity types) + │ │ ├── repo.vcl # Repository octad + │ │ ├── clade.vcl # Clade definition + │ │ ├── todo.vcl # Work items + │ │ ├── observation.vcl # Bot/agent findings + │ │ ├── feedback.vcl # External feedback + │ │ ├── lineage.vcl # Inflate/deflate history + │ │ └── forge-identity.vcl # PK/FK forge mapping + │ ├── seed/ # Initial data + │ │ ├── clades.a2ml # 12 clade definitions + │ │ ├── repos.a2ml # 200 repo registrations + │ │ └── forges.a2ml # Forge account definitions + │ └── queries/ # Pre-built VCL queries + │ ├── dashboard.vcl # Ecosystem overview + │ ├── stale.vcl # Inactive repos + │ ├── orphans.vcl # Unclassified repos + │ ├── drift.vcl # State divergence + │ ├── bot-findings.vcl # Unacknowledged bot observations + │ ├── blocked.vcl # Blocked work items + │ ├── cross-clade-deps.vcl # Cross-boundary dependencies + │ └── feedback-status.vcl # Feedback resolution tracking + ├── sync/ # Sync tooling (Phase 2) + ├── views/ # Generated outputs (not committed) + └── contractiles/ + └── must/ + └── clade-hygiene.a2ml # Every repo MUST have CLADE.a2ml + +# Portal Architecture + + hyperpolymath.github.io Cloudflare Worker VeriSimDB (VPS) + (ReScript/WASM) --> (API Gateway) --> (Rust + Elixir) + | + Public read --------------------------------------------------> KV snapshot + LLM query ------------------- API key ---------------------> Read-only + Contributor ------------------ OAuth -----------------------> Scoped access + Bot writes ------------------- Signed JWT ------------------> Write observations + +# Identity Model + +Every repo has: + +- **Primary key**: GitHub (`gh:hyperpolymath/{name}`) + +- **Foreign keys**: GitLab, Bitbucket, Codeberg, SourceHut mirrors + +- **UUID**: Deterministic v5, derived from + `github.com/hyperpolymath/{name}` + +- **Clade**: Primary (1) + secondary (0+) + +- **Lineage**: standalone, monorepo, monorepo-child, inflated, deflated + +# Pointer Authority + +Every cached value in VeriSimDB declares its canonical source: + +- `pointer` — value lives in the repo (VeriSimDB caches + drift-detects) + +- `local` — VeriSimDB owns it (TODOs, bot observations) + +- `derived` — computed from other values (clade health scores) + +# Contractile System + +This repo includes a `clade-hygiene.a2ml` contractile: + +- **CLADE-001**: Every repo must have `.machine_readable/CLADE.a2ml` + +- **CLADE-002**: CLADE.a2ml must declare a primary clade code + +- **CLADE-003**: Primary clade code must be one of the 12 valid codes + +# Implementation Phases + +| Phase | Deliverable | Status | +|----|----|----| +| 0 | Clade taxonomy, repo seed, VCL schema | **Complete** | +| 1 | Deploy CLADE.a2ml to all 200 repos | Pending | +| 2 | VeriSimDB instance on VPS | Pending | +| 3 | Cloudflare Worker API (hardened, tested, CI-gated) | In progress (~60%) | +| 4 | ReScript/typed-WASM portal | Pending | +| 5 | LLM query endpoint | Pending | +| 6 | Bot write endpoints | Pending | +| 7 | Contributor OAuth | Pending | +| 8 | Repo lockdown | Pending | + +# License + +MPL-2