panll/0-AI-MANIFEST.a2ml at main · hyperpolymath/panll · 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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
; SPDX-License-Identifier: MPL-2.0
; SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath)
;
; 0-AI-MANIFEST.a2ml — Universal AI entry point for PanLL
; Media-Type: application/a2ml

; THIS FILE MUST BE READ FIRST BY ALL AI AGENTS

(manifest
  (identity
    (name "PanLL")
    (full-name "PanLL eNSAID — Neurosymbolic AI Development Environment")
    (version "0.1.0-alpha")
    (repo "https://github.com/hyperpolymath/panll")
    (license "MPL-2.0")
    (author "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"))

  (purpose
    "Three-panel neurosymbolic workbench (Binary Star co-orbit model).
     Panel-L (Symbolic), Panel-N (Neural/ECHIDNA), Panel-W (World/VeriSimDB).
     Cognitive governance via Anti-Crash, Vexometer, Orbital sync, Contractiles.
     TypeLL provides cross-panel type intelligence as a shared service.")

  ;; ===================================================================
  ;; CONTEXT TIERS — controls what agents should load and when
  ;; ===================================================================

  (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
    ; Tier 2 (load on demand): .machine_readable/*.scm, docs/design/
    ; Tier 3 (never load unless asked): tests/, generated/, CI configs
    ;
    ; DO NOT READ unless specifically asked:
    ;   tests/          — test files (run them, don't read them)
    ;   generated/      — auto-generated code
    ;   target/         — build artifacts
    ;   node_modules/   — dependencies
    ;   lib/bs/         — ReScript compiler cache
    ;   *.lock          — lock files
    ;   src-gossamer/target/ — Rust build output
    )

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

  (canonical-locations
    (ai-manifest     "0-AI-MANIFEST.a2ml"         "THIS FILE — read first")
    (ai-instructions ".claude/CLAUDE.md"           "Claude-specific patterns")

    ; Machine-readable checkpoint files (ONLY in .machine_readable/)
    (state           ".machine_readable/STATE.scm")
    (meta            ".machine_readable/META.scm")
    (ecosystem       ".machine_readable/ECOSYSTEM.scm")

    ; Key source files — see .claude/CLAUDE.md for full file table
    (model-root      "src/Model.res"               "Composition root")
    (messages        "src/Msg.res"                  "TEA message variants")
    (update-engine   "src/Update.res"               "State transition kernel")
    (view-root       "src/View.res"                 "Root view renderer")

    ; Infrastructure
    (gossamer-backend "src-gossamer/src/main.rs"    "Rust/Gossamer backend")
    (elixir-backend  "beam/"                        "Elixir/BEAM API layer")
    (rescript-config "rescript.json"                 "ReScript compiler config")
    (deno-config     "deno.json"                    "Deno tasks and import map"))

  ;; ===================================================================
  ;; TECH STACK
  ;; ===================================================================

  (tech-stack
    (primary    "ReScript"      "Gossamer (Rust + Zig + WebKitGTK)")
    (secondary  "Elixir/OTP"    "Deno")
    (testing    "Deno.test")
    (backend-provers "ECHIDNA REST on port 9000")
    (backend-db      "VeriSimDB REST on port 8080"))

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

  (critical-invariants
    ; Architecture
    (rule "TEA pattern: Model -> Msg -> Update -> View — no MVC, no Redux")
    (rule "All state lives in Model.model — no global mutable state")
    (rule "Anti-Crash validates ALL neural tokens — no bypasses")
    (rule "Contractiles evaluate after EVERY state-modifying update")
    (rule "TypeLL is cross-cutting — any panel can call TypeLLService")
    (rule "SCM files ONLY in .machine_readable/ — NEVER in root")
    (rule "Panels, not panes — PanLL uses 'panels' terminology")

    ; Ports
    (rule "Dev server: 8000 | ECHIDNA: 9000 | VeriSimDB: 8080")

    ; Code policy
    (rule "No TypeScript — ReScript only")
    (rule "No npm/bun — Deno only")
    (rule "MPL-2.0 on all source files"))

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

  (structure
    "panll/
     ├── 0-AI-MANIFEST.a2ml         # THIS FILE
     ├── src/                        # ReScript source (230 files, TEA)
     │   ├── Model.res, Msg.res, Update.res, View.res, App.res
     │   ├── model/                  # Domain modules (Pane, Echidna, VeriSim, Governance, TypeLL, ...)
     │   ├── core/                   # Engines (AntiCrash, Orbital, Contractiles, TypeLL, Vab, ...)
     │   ├── components/             # 106 panel views
     │   ├── commands/               # Gossamer bridge commands
     │   └── modules/                # Module registry + TypeLLService
     ├── src-gossamer/               # Rust/Gossamer backend
     ├── beam/                       # Elixir/BEAM API layer
     ├── tests/                      # 979 tests, 41 suites
     ├── .machine_readable/          # SCM checkpoint files
     └── .bot_directives/            # Bot instructions")

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

  (lifecycle
    (on-enter
      (step "Read THIS file first")
      (step "Read .claude/CLAUDE.md for build commands and conventions")
      (step "Read .machine_readable/STATE.scm for current status"))

    (on-exit
      (step "Update .machine_readable/STATE.scm if changes were made")
      (step "Summarise outcomes for session continuity")))

  ;; ===================================================================
  ;; CALLING ECHIDNA VIA BOJ
  ;; ===================================================================
  ;; All ECHIDNA calls go through the echidna-llm-mcp BoJ cartridge.
  ;; Never call ECHIDNA directly.
  ;;
  ;; Tools:
  ;;   echidna_list_provers  — discovery: 105 provers with tier/category
  ;;   echidna_prove         — invoke prover on a file path
  ;;   echidna_verify        — verify inline proof content
  ;;   echidna_search        — keyword search over proof corpus
  ;;   echidna_suggest_tactics — advisory tactic suggestions
  ;;   echidna_rank_provers  — advisory prover ranking
  ;;
  ;; Example:
  ;;   { "tool": "echidna_prove", "args": { "file": "/path/proof.lean", "prover": "Lean" } }
  ;;
  ;; Full protocol: boj-server/cartridges/echidna-llm-mcp/docs/CALL-PROTOCOL.adoc

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