git-reticulator/0-AI-MANIFEST.a2ml at main · hyperpolymath/git-reticulator · 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
# ⚠️ READ THIS FIRST (all AI agents)

# SPDX-License-Identifier: MPL-2.0
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>

## WHAT IS THIS?

AI manifest for **git-reticulator** — a semantic-lattice + embedding builder
for git repositories, and the symbolic (layer-1) half of a neuro-symbolic
retrieval stack (see `.machine_readable/6a2/NEUROSYM.a2ml`).

It declares canonical file locations, critical invariants, and — importantly —
the **honesty rule** for this repo: distinguish what is IMPLEMENTED from what is
SKELETON (stub) from what is ASPIRATIONAL (designed, not buildable).

## HONESTY RULE (specific to this repo)

git-reticulator is early. Much of the "core" lives in `.affine` files that
**cannot compile** (AffineScript has no working compiler yet) and that, as
written, call Rust crates AffineScript cannot bind. The Rust host is ~237 LOC
of `println!` stubs. Therefore:

- Never document a stub as a working feature.
- Never assert "lattice" algebra (meet/join) — the structure is a typed DAG
  until `PROOF-NEEDS.md` P1/P2 are discharged. Say "typed graph" / "DAG".
- Status legend everywhere: **IMPLEMENTED | SKELETON | ASPIRATIONAL**.

## CANONICAL LOCATIONS

### Machine-readable metadata: `.machine_readable/6a2/` ONLY
The six a2ml files live here (NOT repo root, NOT `.machine_readable/` root):
1. `STATE.a2ml` — honest project state, blockers, next actions
2. `META.a2ml` — architecture decisions (ADRs), rationale
3. `ECOSYSTEM.a2ml` — relationships (affinescript, verisim, vcl-ut, k9, Hypatia)
4. `AGENTIC.a2ml` — AI agent permissions/constraints + RAG-provider role
5. `NEUROSYM.a2ml` — the neuro-symbolic architecture (the thesis of this repo)
6. `PLAYBOOK.a2ml` — neuro-symbolic playbooks + ops runbook

### Proof obligations: `PROOF-NEEDS.md` (repo root)
What must be proved to earn the word "lattice" and to make retrieval provable.

### Agent instructions: `.machine_readable/agent_instructions/`
`methodology.a2ml`, `coverage.a2ml`, `debt.a2ml` (ADR-002 methodology layer).

### Contractiles: `contractiles/` (load-bearing) — see note below
The root `contractiles/{intend,must,trust}/*.a2ml` are the canonical, generating
source: `contractile.just` is generated from them and imported by the Justfile.
A second, NON-load-bearing set exists at `.machine_readable/*.contractile`
(documentation-style); consolidating the two is tracked in STATE.a2ml.

### Community/forge metadata: `.github/`, plus root `SECURITY.md`, `CONTRIBUTING.md`.

## CORE INVARIANTS

1. State files in `.machine_readable/6a2/` only — no duplication in root.
2. `.machine_readable/6a2/` is the single source of truth for project state.
3. All code MPL-2.0; SPDX header on every file.
4. Author attribution: "Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>".
5. Container images use Chainguard base; runtime Podman (Containerfile, not Dockerfile);
   orchestration selur-compose (not docker-compose).
6. No template placeholders ever committed (`{{...}}`, `[YOUR-REPO-NAME]`).

## ACTUAL REPOSITORY STRUCTURE (as built, 2026-06-03)

```
git-reticulator/
├── 0-AI-MANIFEST.a2ml          # THIS FILE
├── README.adoc                 # pitch + honest status
├── EXPLAINME.adoc              # developer deep-dive
├── PROOF-NEEDS.md              # formal obligations (the 'lattice' debt)
├── TEST-NEEDS.md               # test inventory (smoke-level today)
├── READINESS.md                # CRG grade source (read by `just crg-grade`)
├── TOPOLOGY.md                 # accurate module map + data flow
├── Cargo.toml / Justfile       # Rust build + task runner
├── src/
│   ├── lib.rs                  # host library (SKELETON: println stubs)
│   ├── cli/main.rs             # `reticulate` CLI (clap)
│   ├── api/app.rs              # actix-web REST shell (stub responses)
│   └── lattice/affine/         # ASPIRATIONAL core (cannot compile yet)
│       ├── models.affine       # data model (Keyword/Relationship/Lattice)
│       ├── storage.affine      # Postgres + pgRouting persistence
│       └── lattice.affine      # build_lattice / zoom_to_node (LOD)
├── tests/                      # *.rs smoke/contract + lattice_tests.affine
├── benches/                    # criterion harness
├── contractiles/               # load-bearing contractile sources
├── docs/                       # setup + tech-debt audit
└── .machine_readable/
    ├── 6a2/                    # the six a2ml files (canonical state)
    ├── agent_instructions/     # methodology/coverage/debt
    └── *.contractile           # secondary (non-load-bearing) contractile docs
```

## SESSION STARTUP CHECKLIST

1. Read THIS file.
2. Read `.machine_readable/6a2/STATE.a2ml` (honest status).
3. Read `PROOF-NEEDS.md` before touching anything that claims "lattice".
4. Respect the IMPLEMENTED/SKELETON/ASPIRATIONAL legend in all edits.

## ATTESTATION

"I have read the manifest. State lives in `.machine_readable/6a2/` only. I will
mark SKELETON/ASPIRATIONAL honestly, will not claim 'lattice' algebra without
discharging PROOF-NEEDS.md P1/P2, and will not commit template placeholders."