hypatia/0-AI-MANIFEST.a2ml at main · hyperpolymath/hypatia · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
; SPDX-License-Identifier: PMPL-1.0-or-later
; SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath)
;
; 0-AI-MANIFEST.a2ml — Universal AI entry point for Hypatia
; Media-Type: application/a2ml

; THIS FILE MUST BE READ FIRST BY ALL AI AGENTS

(manifest
  (identity
    (name "hypatia")
    (full-name "Hypatia — Neurosymbolic CI/CD Intelligence")
    (version "0.7.x")
    (repo "https://github.com/hyperpolymath/hypatia")
    (license "PMPL-1.0-or-later")
    (author "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"))

  (purpose
    "Neurosymbolic CI/CD intelligence layer. Coordinates gitbot-fleet
     (rhodibot, echidnabot, sustainabot, glambot, seambot, finishbot)
     via safety triangle pipeline (Eliminate > Substitute > Control).
     5 neural networks, VQL queries over verisimdb-data, Bayesian confidence,
     Logtalk rules for pattern detection. Scans 300+ repos.")

  ;; ===================================================================
  ;; CONTEXT TIERS
  ;; ===================================================================

  (context-tiers
    ; Tier 0 (always load): This file + .claude/CLAUDE.md — orientation only
    ; Tier 1 (load if working on code): README.adoc, EXPLAINME.adoc, Justfile, mix.exs
    ; Tier 2 (load on demand): .machine_readable/6a2/*.a2ml, docs/
    ; Tier 3 (never load unless asked): test/, _build/, deps/, generated/
    ;
    ; DO NOT READ unless specifically asked:
    ;   test/           — test files (run them, don't read them)
    ;   _build/         — Elixir build output
    ;   deps/           — Elixir dependencies
    ;   target/         — Rust build output
    ;   generated/      — auto-generated code
    ;   *.lock          — lock files
    )

  ;; ===================================================================
  ;; CANONICAL LOCATIONS
  ;; ===================================================================

  (canonical-locations
    (ai-manifest     "0-AI-MANIFEST.a2ml"           "THIS FILE")
    (ai-instructions ".claude/CLAUDE.md"             "Claude-specific patterns — DETAILED")
    (state           ".machine_readable/6a2/STATE.a2ml")
    (meta            ".machine_readable/6a2/META.a2ml")
    (ecosystem       ".machine_readable/6a2/ECOSYSTEM.a2ml")
    (bot-directives  ".machine_readable/bot_directives/"))

  ;; ===================================================================
  ;; ARCHITECTURE SUMMARY
  ;; ===================================================================

  (architecture
    (description "Safety triangle pipeline with neural dispatch")
    (layers
      (elixir-pipeline "lib/"       "8 core modules — pattern analysis, dispatch, learning")
      (neural          "lib/neural/" "5 networks + coordinator GenServer")
      (vql             "lib/vql/"    "Built-in VQL parser, file executor, query cache")
      (idris2-abi      "src/abi/"    "Types, GraphQL, gRPC, REST with proofs")
      (zig-ffi         "ffi/zig/"    "7 exported C ABI functions")
      (rust            "src/rust/"   "Adapters, CLI, data, fixer, integration"))
    (data-flow
      "panic-attack scan -> verisimdb-data -> Elixir pipeline -> triangle route -> fleet dispatch"))

  ;; ===================================================================
  ;; STRUCTURE OVERVIEW (detail in CLAUDE.md)
  ;; ===================================================================

  (structure
    "hypatia/
     ├── 0-AI-MANIFEST.a2ml         # THIS FILE
     ├── lib/                        # Elixir pipeline (8 core + VQL + neural + safety)
     ├── src/abi/                    # Idris2 ABI (Types, GraphQL, gRPC, REST, FFI)
     ├── ffi/zig/                    # Zig FFI bridge (7 functions)
     ├── src/rust/                   # Rust workspace (adapters, cli, data, fixer)
     ├── .machine_readable/          # State, meta, ecosystem, bot directives
     └── .bot_directives/            # Bot instructions")

  ;; ===================================================================
  ;; CRITICAL INVARIANTS
  ;; ===================================================================

  (critical-invariants
    (rule "SCM files ONLY in .machine_readable/ — never in root")
    (rule "Safety triangle: Eliminate > Substitute > Control — order matters")
    (rule "Confidence gates: >=0.95 auto-execute, 0.85-0.94 review, <0.85 report")
    (rule "PMPL-1.0-or-later on all source files")
    (rule "Author: Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"))

  ;; ===================================================================
  ;; SESSION LIFECYCLE
  ;; ===================================================================

  (lifecycle
    (on-enter
      (step "Read THIS file first")
      (step "Read .claude/CLAUDE.md — contains detailed architecture tables")
      (step "Read .machine_readable/6a2/STATE.a2ml for current status"))

    (on-exit
      (step "Update .machine_readable/6a2/STATE.a2ml if changes made")
      (step "Summarise outcomes")))

  (format-meta
    (version "2.1.0")
    (media-type "application/a2ml")
    (created "2026-02-15")
    (last-updated "2026-03-24")
    (maintained-by "Jonathan D.A. Jewell / hyperpolymath")
    (protocol "https://github.com/hyperpolymath/0-ai-gatekeeper-protocol")))