verisimdb-data/0-AI-MANIFEST.a2ml at main · hyperpolymath/verisimdb-data · 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
# SPDX-License-Identifier: MPL-2.0
# 0-AI-MANIFEST.a2ml — verisimdb-data
# THIS FILE MUST BE READ FIRST BY ALL AI AGENTS

## WHAT IS THIS?

This is the AI manifest for **verisimdb-data**. It declares:
- Canonical file locations (where things MUST be, and nowhere else)
- Critical invariants (rules that must NEVER be violated)
- Repository structure and organization

verisimdb-data is the git-backed flat-file data store for VeriSimDB.
It stores panic-attack scan results, dispatch manifests, drift snapshots,
and training data for the Hypatia neurosymbolic pipeline. It lives as a
subdirectory within the verisimdb project inside the nextgen-databases monorepo.

## CANONICAL LOCATIONS (UNIVERSAL RULE)

### Machine-Readable Metadata: `.machine_readable/` ONLY

These SCM files MUST exist in `.machine_readable/` directory ONLY:
1. **STATE.scm** - Project state, progress, blockers
2. **META.scm** - Architecture decisions, governance
3. **ECOSYSTEM.scm** - Position in ecosystem, relationships

**CRITICAL:** If ANY of these files exist in the root directory, this is an ERROR.

### Bot Directives: `.bot_directives/` ONLY

Bot-specific instructions for the gitbot-fleet (rhodibot, echidnabot, etc.)

### Agent Instructions

- `.claude/CLAUDE.md` - Claude-specific patterns (if exists)
- `0-AI-MANIFEST.a2ml` - THIS FILE (universal entry point)

## CORE INVARIANTS

1. **No SCM duplication** - Root must NOT contain STATE.scm, META.scm, etc.
2. **Single source of truth** - `.machine_readable/` is authoritative
3. **No stale metadata** - If root SCMs exist, they are OUT OF DATE
4. **License consistency** - All code MPL-2.0 unless platform requires MPL-2.0
5. **Author attribution** - Always "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"
6. **Data integrity** - Scan results and dispatch manifests must not be modified post-ingestion
7. **No .git in subdirectory** - This is part of the nextgen-databases monorepo

## REPOSITORY STRUCTURE

```
verisimdb-data/
├── 0-AI-MANIFEST.a2ml         # THIS FILE (start here)
├── README.adoc                # Project overview
├── index.json                 # Master index of all octads
├── scans/                     # panic-attack scan results per repo
├── dispatch/                  # Hypatia dispatch manifests (JSONL)
├── patterns/                  # Cross-repo pattern data
├── recipes/                   # Remediation recipes
├── outcomes/                  # Dispatch outcome tracking
├── health/                    # Pipeline health snapshots
├── drift/                     # Drift detection snapshots
├── hardware/                  # hardware-crash-team findings
├── .machine_readable/         # SCM files
│   ├── STATE.scm
│   ├── META.scm
│   └── ECOSYSTEM.scm
└── .bot_directives/           # Bot instructions
```

## SESSION STARTUP CHECKLIST

1. Read THIS file (0-AI-MANIFEST.a2ml) first
2. Understand canonical locations (.machine_readable/, .bot_directives/)
3. Know the invariants (no SCM duplication, data integrity, etc.)
4. Read `.machine_readable/STATE.scm` for current status

## META

- **Format Version:** 1.0.0
- **Created:** 2026-03-16
- **Maintained By:** Jonathan D.A. Jewell (hyperpolymath)
- **License:** MPL-2.0
- **Protocol:** https://github.com/hyperpolymath/0-ai-gatekeeper-protocol