Hypatia: Neurosymbolic CI/CD Intelligence Platform

🌐 Website: hypatia.reposystem.dev | Part of the reposystem ecosystem

Table of Contents

• Overview
  • Core philosophy
• The safety triangle
• Architecture
• Installation
• Usage
• Integration with robot-repo-automaton
• Project status
• Documentation
• Related projects
• Licence
• OPSM link

Overview

Hypatia is the CI/CD governance scanner for the hyperpolymath estate (~400 repositories). It combines:

• Symbolic reasoning — 33 Elixir rule modules producing fast, deterministic findings (full rule catalogue)

• Neural learning — 8 networks on a shared blackboard, learning which fixes actually stick

• Bayesian confidence — every recipe carries a Beta-distributed confidence updated from real outcomes, which gates whether a fix is applied automatically, proposed as a PR, or merely reported

• Machine-checked proofs — Idris2 ABI definitions with dependent types, Lean 4 proofs of the Bayesian update and rate-limiting properties, and a TLA+ model of the Kin gate

Core philosophy

"Dumb rules from smart learning"

The system learns complex patterns through neural analysis, then distils them into simple, fast declarative rules that can be pre-emptively injected into new repositories, applied as cures to existing ones, and executed without ML inference overhead.

The safety triangle

Every finding is routed Eliminate > Substitute > Control, in that order — remove the hazard if you can, replace it if you cannot, and only then add a control around it. Dispatch is then gated on confidence:

>= 0.95	auto_execute — applied by robot-repo-automaton
0.85–0.94	review — rhodibot opens a PR
< 0.85	report_only — sustainabot advisory

Unknown findings are forced to report_only regardless of score (novelty gating).

panic-attack scan
      │  findings
verisim-data (git-backed flat-file store)
      │
PatternRegistry ──> TriangleRouter ──> FleetDispatcher ──> DispatchManifest (JSONL)
      │                                                            │
      └────────────── OutcomeTracker <───────────── dispatch-runner.sh
                     (Bayesian feedback loop)

Architecture

lib/	133 Elixir modules — pipeline, rules, VCL, neural, safety, web, merge orchestration
lib/rules/	33 rule modules; see the catalogue
lib/neural/	8 networks + blackboard, coordinator, persistence, rebalancer
lib/vcl/	VCL query layer over verisim-data: parser, file executor, cache, federation
lib/merge_orchestration/	12 modules — leases, ledger, ticker
lib/hypatia/web/	Dashboard, SSE stream, Prometheus /metrics, GraphQL, SARIF output
src/Hypatia/ABI/	Idris2 ABI — Types, GraphQL, gRPC, REST, FFI, RuleEngine
ffi/zig/	Zig C ABI bridge — 18 exports + 16 protocol connectors
adapters/ cli/ data/ fixer/ integration/	Rust workspace
verification/	Lean 4 proofs, TLA+ specs

See docs/architecture/topology.md for the full map.

Installation

Guix is the reproducible-build path; Nix was retired estate-wide on 2026-06-05. Podman, not Docker, is the container tool.

git clone https://github.com/hyperpolymath/hypatia.git
cd hypatia

guix shell -m guix.scm     # reproducible environment (optional)
just doctor                # toolchain preflight
just build-all             # Elixir + Rust + Zig FFI + Idris2 ABI

just --list shows all 39 recipes; CONTRIBUTING.md treats just as the canonical entry point.

Usage

The escript exposes five commands:

hypatia scan <path> [--format json|text|github|sarif] [--exit-zero]
hypatia report <path>
hypatia pr-eligibility --owner <owner> --repo <repo> --pr <n>
hypatia version
hypatia help

Mix tasks cover the operational surface — mix hypatia.rsr_score, mix hypatia.recipe_health, mix hypatia.watch, mix hypatia.triage_issues and eleven more. See the Operations wiki page.

Running the supervision tree also serves an HTML dashboard, an SSE event stream, a Prometheus /metrics endpoint and a bearer-authenticated /api/* on port 9090.

Integration with robot-repo-automaton

Hypatia writes JSONL dispatch manifests; dispatch-runner.sh in gitbot-fleet consumes them and routes each entry by its confidence tier. Outcomes flow back through mix hypatia.record_outcome, which drives the Bayesian update and, when a recipe degrades, auto-quarantine.

Project status

Development state, milestones and known gaps live in machine-readable form:

• .machine_readable/6a2/STATE.a2ml — current state and milestone status

• .machine_readable/6a2/PLAYBOOK.a2ml — operational runbook

• ROADMAP.adoc — milestone history

Before trusting any metric or green board, read docs/DEBT-REGISTER.md. It is the authoritative, evidence-backed account of what is broken, ungated or stale — including 242 tests that are excluded from every run, the safety systems that are built but not yet invoked by any dispatch path, and the CI blockage currently stopping the Rust lane.

Documentation

• docs/README.adoc — the documentation index

• Rule catalogue — every rule module and ID family

• Debt register — what is broken and what is not gated

• Wiki — getting started, architecture, operations, FAQ

• Palimpsest Philosophy — philosophical underpinnings

Related projects

• robot-repo-automaton — automated repository management

• git-hud — CI/CD intelligence system

• rhodium-standard-repositories — repository standards

• palimpsest-license — the Palimpsest licence

• OpenSSF Best Practices Badge — security certification programme

Licence

Hypatia is licensed under the Mozilla Public License 2.0. Source files declare MPL-2.0 and documentation declares CC-BY-SA-4.0, both via per-file SPDX headers; where a header and prose disagree, the header governs.

The Palimpsest Licence (PMPL) is a separate licence maintained at palimpsest-license. It is not a variant or extension of MPL-2.0 and its text is not distributed here. See NOTICE.

OPSM link

OPSM Core
  |
  v
hypatia (policy/knowledge services used by OPSM)