nextgen-databases/0-AI-MANIFEST.a2ml at main · hyperpolymath/nextgen-databases · 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
# SPDX-License-Identifier: MPL-2.0
# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
# ⚠️ STOP - CRITICAL READING REQUIRED

**THIS FILE MUST BE READ FIRST BY ALL AI AGENTS**

## WHAT IS THIS?

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

## CANONICAL LOCATIONS (UNIVERSAL RULE)

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

These 6 SCM files MUST exist in `.machine_readable/` directory ONLY:
1. **.machine_readable/descriptiles/STATE.a2ml** - Project state, progress, blockers
2. **.machine_readable/descriptiles/META.a2ml** - Architecture decisions, governance
3. **.machine_readable/descriptiles/ECOSYSTEM.a2ml** - Position in ecosystem, relationships
4. **.machine_readable/descriptiles/AGENTIC.a2ml** - AI agent interaction patterns
5. **.machine_readable/descriptiles/NEUROSYM.a2ml** - Neurosymbolic integration config
6. **.machine_readable/descriptiles/PLAYBOOK.a2ml** - Operational runbook

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

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

Bot-specific instructions for:
- rhodibot - Git operations
- echidnabot - Code quality
- sustainabot - Dependency updates
- glambot - Documentation
- seambot - Integration
- finishbot - Task completion

### Agent Instructions

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

## CORE INVARIANTS

1. **Coordination only — no implementation** - This repo coordinates a portfolio of
   databases. Per-database source, schemas, migrations, database-language implementations,
   and per-database docs MUST live in that database's own repo (see `REGISTRY.adoc`).
   Adding per-database implementation content here is an ERROR.
2. **No descriptor duplication** - Keep STATE.a2ml, META.a2ml and the other descriptive anchors only under `.machine_readable/descriptiles/`; do not create duplicates at the repository root or in retired directories.
3. **Single source of truth** - `.machine_readable/` is authoritative
4. **No stale metadata** - If root SCMs exist, they are OUT OF DATE
5. **License consistency** - All code PMPL-1.0-or-later unless platform requires MPL-2.0
6. **Author attribution** - Always "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"

## REPOSITORY STRUCTURE

This is a **coordination repo**. Intended (target) contents:

```
nextgen-databases/
├── 0-AI-MANIFEST.a2ml          # THIS FILE (start here)
├── CLAUDE.md / AGENTS.adoc       # Agent guardrails (coordination-only)
├── REGISTRY.adoc               # Authoritative map: database/language -> its own repo
├── README.adoc / EXPLAINME.adoc / TOPOLOGY.adoc / ROADMAP.adoc   # Portfolio docs
├── tests/                      # CROSS-database integration tests only
├── docs/                       # Coordination docs (incl. migration runbooks)
├── .machine_readable/          # Canonical SCM metadata
├── .github/ .well-known/ LICENSES/   # Governance, protocols, licenses
└── flake.nix / Justfile / stapeln.toml / opsm.toml   # Shared env & orchestration
```

LEGACY (being extracted to their own repos — see
`docs/migration/RESITE-DATABASES-TO-OWN-REPOS.adoc` and `REGISTRY.adoc`):
`verisimdb/`, `lithoglyph/`, `quandledb/`, `nqc/`, `typeql-experimental/`,
`verisim-core/`, `verisim-modular-experiment/`. **Do NOT add new content to these.**

## KEY RELATIONSHIPS

This is a **parent/tracking (coordination) repository** — no implementation code.
Satellite repos (authoritative list in `REGISTRY.adoc`): verisimdb, lithoglyph,
glyphbase, quandledb, gnpl, vcl-ut, krl, vocarium, hermeneia, nqc.

## SESSION STARTUP CHECKLIST

✅ Read THIS file (0-AI-MANIFEST.a2ml) first
✅ Understand canonical locations (.machine_readable/, .bot_directives/)
✅ Know the invariants (no SCM duplication, etc.)
✅ Check for MCP enforcement (if applicable)
✅ Read `.machine_readable/descriptiles/STATE.a2ml` for current status
✅ Read `.machine_readable/descriptiles/AGENTIC.a2ml` for interaction patterns

## LIFECYCLE HOOKS

### on-enter (Session Start)

When starting a new session:

1. Read and acknowledge this manifest
2. Log session start (optional but recommended)
   - Format: `[YYYY-MM-DD HH:MM:SS] Session started: [agent-name]`
   - Location: `.machine_readable/session-log.txt`
3. Read `.machine_readable/descriptiles/STATE.a2ml`
4. Check for blockers
5. State understanding of canonical locations

### on-exit (Session End)

When ending a session:

1. Update `.machine_readable/descriptiles/STATE.a2ml` if changes made
2. Log session end (optional but recommended)
   - Format: `[YYYY-MM-DD HH:MM:SS] Session ended: [summary]`
   - Location: `.machine_readable/session-log.txt`
3. Document new blockers
4. Summarize outcomes

## ATTESTATION PROOF

After reading this file, demonstrate understanding by stating:

**"I have read the AI manifest. SCM files are located in `.machine_readable/` ONLY, bot directives in `.bot_directives/`, and I will not create duplicate files in the root directory."**

## META

- **Format Version:** 1.0.0
- **Created:** 2026-02-13
- **Maintained By:** Jonathan D.A. Jewell (hyperpolymath)
- **License:** PMPL-1.0-or-later
- **Protocol:** https://github.com/hyperpolymath/0-ai-gatekeeper-protocol